Skip to content

docs: add a Why kuri? section to the README #161

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
OmarAlJarrah merged 3 commits into from
Jul 20, 2026
Merged

docs: add a Why kuri? section to the README #161

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
af637de
docs: add a Why kuri? section to the README
OmarAlJarrah Jul 20, 2026
552d448
docs: tighten the Why kuri? section to a single paragraph
OmarAlJarrah Jul 20, 2026
fb86a2e
docs: make Why kuri? a bullet list and add the Kotlin Multiplatform gap
OmarAlJarrah Jul 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,20 @@ Standard, and UTS #46 for internationalized hosts. Parsing returns a result inst
immutable, and the whole API reads naturally from both Kotlin and Java. It runs everywhere Kotlin does — JVM,
Android, JS, Wasm, and native.

## Why kuri?

- URL parsing looks trivial and almost never is. The parts most parsers skip (percent-encoding, IDNA hosts,
dot-segment resolution, port elision) are where the bugs hide.
- RFC 3986 and the WHATWG URL Standard are different specs with different rules. When two parts of a system
read the same URL differently, that gap becomes an SSRF filter bypass, an origin mix-up, a poisoned cache key.
- The JVM's built-ins don't help: `java.net.URI` is specified against the superseded RFC 2396, `java.net.URL`
barely validates and its `equals()` makes a blocking DNS call to compare two values, and neither exists off
the JVM.
- That leaves a gap on Kotlin Multiplatform: the standard library has no URL type, so shared code either drops
to a JVM-only parser and loses the other targets, or reimplements parsing per platform and drifts.
- kuri closes it: one parser in common Kotlin, checked against the standards' own conformance suites, so you
get the same result on JVM, Android, JS, Wasm, and native, with errors as values and your choice of spec.

## Installation

```kotlin
Expand Down