ktorio / ktorio/ktor-documentation
Document behavior change: KTOR-2832 URLBuilder(urlString) schemeless URL parsing
- Dominant language
- Kotlin
- Stars
- 540
- Forks
- 375
- Avg merge
- 2d 20h
- Merged PRs (30d)
- 19
Description
## Context
PR: https://github.com/ktorio/ktor/pull/5395
Issue: https://youtrack.jetbrains.com/issue/KTOR-2832
## What changed
In Ktor 4.0.0, `URLBuilder(urlString)` now treats schemeless strings (those without `://` and not starting with `/`) as an authority (host with optional port and path) instead of a relative path. Previously, `URLBuilder("localhost")` would produce `http://localhost/localhost` — the input was treated as a path segment. Now it correctly produces `http://localhost`.
This is a **breaking behavioral change** for users who relied on passing bare path strings to the `URLBuilder(urlString)` factory function. The `takeFrom()` method retains the old relative URL resolution behavior.
## What should be documented
- Update the `URLBuilder` documentation to explain how schemeless strings are parsed
- Add a migration note for 4.0.0 explaining the behavior change
- Clarify the difference between `URLBuilder(urlString)` (treats input as standalone URL) and `takeFrom(urlString)` (resolves as relative URL against existing builder state)
- Affected API: `URLBuilder(urlString: String)` factory function in `io.ktor.http`
## Suggested code snippet
```kotlin
// Ktor 4.0: schemeless strings are now parsed as host
val url1 = URLBuilder("localhost:8080").buildString() // "http://localhost:8080"
val url2 = URLBuilder("example.com/api/v1").buildString() // "http://example.com/api/v1"
// Use takeFrom() for relative URL resolution against an existing base
val builder = URLBuilder("https://example.com/base/")
builder.takeFrom("relative/path") // resolves to "https://example.com/base/relative/path"
```
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Contributor guide
Research direction
Start with the URLBuilder(urlString: String) documentation in io.ktor.http and the 4.0.0 migration notes. Document schemeless parsing, include the supplied examples, and clarify how URLBuilder(urlString) differs from takeFrom(urlString); done means both locations explain the behavior change and migration path.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kotlin
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100