ktorio / ktorio/ktor-documentation

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

Open Beginner friendly
#775 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.