KTOR-2832 Fix URLBuilder(urlString) parsing for schemeless URLs

[e5l]

Summary

• Fixes https://youtrack.jetbrains.com/issue/KTOR-2832
• URLBuilder(urlString) now treats schemeless strings without a leading / as an authority (host with optional port and path) instead of a relative path
• This fixes surprising behavior where URLBuilder("localhost") produced http://localhost/localhost, URLBuilder("google.com") produced http://localhost/google.com, and URLBuilder("localhost:8080") parsed localhost as a URL scheme

KTOR-2832

Test plan

• Added 5 reproducer tests covering bare hostname, domain name, host:port, host/path, and host:port/path
• Updated existing tests to reflect the new behavior for schemeless strings
• All existing tests in the module continue to pass across all platforms (allTests)

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

The URLBuilder constructor is redesigned to interpret schemeless strings as host/authority components by prepending "//" before delegating to takeFrom, while special schemes without authority (mailto, data, tel, about) are handled explicitly. Test cases updated to reflect new parsing behavior for schemeless input patterns.

Changes

Cohort / File(s)	Summary
URL Builder Implementation ktor-http/common/src/io/ktor/http/URLUtils.kt	Complete rewrite of URLBuilder(urlString: String) constructor with conditional logic to distinguish special schemes without authority, explicit scheme detection, and default host/authority interpretation for schemeless input. Introduces SPECIAL_SCHEMES_WITHOUT_AUTHORITY set.
URL Builder Tests ktor-http/common/test/io/ktor/tests/http/URLBuilderTest.kt, ktor-http/common/test/io/ktor/tests/http/UrlTest.kt	Added test cases for schemeless string parsing as host/authority (e.g., "a", "a/b/c"), KTOR-2832 host-with-port scenarios, and updated isRelativePath expectations. Adjusted parseUrl behavior and special scheme handling in test assertions.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• KTOR-5708 Add data url support #4827 — Modifies URL parsing for special schemes (about, tel, data) with related payload and append routine handling.

Suggested reviewers

• osipxd
• bjhham

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.25% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: fixing URLBuilder parsing to correctly handle schemeless URLs, directly referencing the KTOR-2832 issue.
Description check	✅ Passed	The description addresses motivation (fixes KTOR-2832, explains the problem), solution (treats schemeless strings as authority), and test plan (5 reproducer tests added, existing tests updated). However, it does not explicitly identify the subsystem affected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch claude/KTOR-2832-urlbuilder-no-protocol

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@ktor-http/common/test/io/ktor/tests/http/UrlTest.kt`:
- Around line 368-369: The test currently assumes schemeless input should parse
as null, but parseUrl now treats schemeless strings as hosts; update UrlTest.kt
to reflect the new semantics by replacing the existing assertion with one that
asserts parseUrl("incorrecturl") is not null and that its host equals
"incorrecturl" (use the parseUrl function and the Url/host accessor in the
test), and also add/update the KDoc or a short migration note near the parseUrl
declaration stating that schemeless inputs are interpreted as hosts so callers
relying on null should adjust accordingly.

---

ℹ️ Review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 17f9fda and 618577c.

📒 Files selected for processing (3)

• ktor-http/common/src/io/ktor/http/URLUtils.kt
• ktor-http/common/test/io/ktor/tests/http/URLBuilderTest.kt
• ktor-http/common/test/io/ktor/tests/http/UrlTest.kt

[bjhham]

I think this one ought to be targetted for 4.0.0 because it's quite a significant behavioural change which many people may rely on.

The only way I see us mitigating the risk here is if we were to invoke some new logic for guessing whether or not the string looks like a host / authority (checking for localhost or matching on standard TLD's and IP patterns), then defaulting to a path on the negative condition.

[e5l]

Agreed — retargeted to main (4.0.0) since this is a significant behavioral change. Thanks for the feedback @bjhham!

[osipxd]

retargeted to main (4.0.0)

Actually we don't have a branch to track next major release. I'd not introduce it right now. At least until we polish and automate the process of branch synchronization.

[e5l]

Closing for now — need to resolve branch targeting discussion (no branch for next major release yet). Will revisit when the process is settled.