docs: add a Why kuri? section to the README - #161
Merged
Conversation
Add a section after the intro explaining the motivation and value: URL parsing is subtle and the details ad-hoc parsers miss (percent-encoding, IDNA, dot-segment resolution, port elision) are the ones that cause interop and security bugs; RFC 3986 and the WHATWG URL Standard genuinely differ; the platform primitives (java.net.URI/URL) are lenient, quirky, and JVM-only, leaving Kotlin Multiplatform without a standards-faithful, dependency-free option. States kuri's priorities in order: measured correctness, two explicit models, safety on untrusted input, and one API across every target.
Cut the Why section from three paragraphs plus a list down to one paragraph. Lead with the concrete stakes: parser disagreement turns into SSRF bypasses, origin confusion, and poisoned cache keys, and the JVM built-ins are lenient, quirky (URL.equals can hit DNS), and JVM-only. Keep the argument specific and readable rather than exhaustive.
Convert the Why section from a paragraph to points, and add the Kotlin Multiplatform angle: the standard library has no URL type, so shared code either drops to a JVM-only parser or reimplements parsing per platform. Tighten the platform-primitive claims to what the JDK actually documents: java.net.URI is specified against the superseded RFC 2396, and java.net.URL.equals() makes a blocking DNS call.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
The README explained what kuri is and how to use it, but not why it exists. This adds a short Why kuri? section after the intro, as a list of points.
Content
java.net.URIis specified against the superseded RFC 2396,java.net.URLbarely validates and itsequals()makes a blocking DNS call, and neither runs off the JVM.Claims about the JDK were verified against the Corretto JDK source (URI references RFC 2396; URL.equals does a blocking name resolution). Kept short, as points, no tables.