Document behavior change: KTOR-2832 URLBuilder(urlString) schemeless URL parsing

[e5l]

Context

PR: ktorio/ktor#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

// 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