# zig-uri A URI parser and formatter for Zig, modelled on Python's [`hyperlink`](https://hyperlink.readthedocs.io/) package. Requires Zig 0.16. Address literals are validated with [z46][z46]; IDNA and IRI support are optional and behind a build flag. **[API documentation][docs]** — generated from the source and published on every green build of `main`. ```zig const uri = @import("uri"); const u = try uri.Uri.parse(alloc, "https://example.com/docs/intro.html?lang=en#top"); defer u.deinit(); u.scheme.? // "https" u.host.?.hostname // "example.com" u.rooted // true u.path // .{ "docs", "intro.html" } u.first("lang").? // .{ .key = "lang", .value = "en" } u.effectivePort() // 443 const link = try u.click(alloc, "../api/v1/"); defer link.deinit(); // https://example.com/api/v1/ ``` ## Components are stored decoded Every string on a `Uri` is already percent-decoded, so you can use it directly: ```zig const u = try uri.Uri.parse(alloc, "http://x/a%2Fb?q=1%262"); u.path[0] // "a/b" — one segment, not two u.first("q").?.value.? // "1&2" ``` Writing re-applies the encoding, escaping each component with the largest character set that cannot change how the result re-parses. Output is therefore minimally and canonically escaped rather than byte-identical to the input: `%2f` comes back as `%2F`, and `%41` comes back as `A`. Parsing the output always yields exactly the same components, and writing it again is a fixed point. The test suite enforces both on every table case and on 20,000 randomized delimiter-heavy inputs. Decoded values are byte strings, not validated UTF-8 — `%FF` is legal in a URI and carries no encoding guarantee. By default a `%` that is not followed by two hex digits is kept as a literal `%`, which is what browsers do with the malformed URLs that occur in practice. `Uri.parseOpts(alloc, text, .{ .strict_percent = true })` rejects it instead. ## Ownership A `Uri` owns an arena holding all of its strings, so every accessor is allocation-free and no field needs freeing individually. A `Uri` is immutable: `replace`, `child`, `sibling`, `click`, `relativize`, `normalize`, `add`, `set` and `remove` each return a **new** `Uri` with its own arena, independent of the receiver. ```zig const a = try uri.Uri.parse(alloc, "http://example.com/a"); const b = try a.replace(alloc, .{ .scheme = "https" }); a.deinit(); // b is still valid defer b.deinit(); ``` `Replace` fields are doubly optional: omitting one keeps the current value, `.port = 8080` sets it, and `.port = @as(?u16, null)` clears it. ## API ### Parsing and building | | | |---|---| | `Uri.parse(alloc, text)` | parse a URI reference | | `Uri.parseOpts(alloc, text, opts)` | as above, with `.strict_percent` | | `Uri.init(alloc, components)` | build from loose `Components` | | `Uri.fromPath(alloc, path, opts)` | build a `file:` URI from a filesystem path | | `Uri.clone(alloc)` / `deinit()` | copy / free | | `parts()` | the components as borrowed plain data | ### Inspection `scheme`, `username`, `password`, `host`, `port`, `rooted`, `path`, `query`, `fragment` are plain fields. Plus `isAbsolute()`, `usesNetloc()`, `defaultPort()`, `effectivePort()`, `eql()`, `hash()`. ### Text `write(w, opts)`, `toText(alloc, opts)`, `authority(alloc, opts)`, and `{f}` formatting. The password is withheld unless `.with_password = true`, so a stray log line cannot leak a credential. ### Derivation `replace`, `child`, `sibling`, `click`, `clickUri`, `relativize`, `normalize`. ### File paths `Uri.fromPath` and `Uri.toPath` convert between a filesystem path and the [RFC 8089][8089] `file:` URI naming it, in either platform's path syntax. The `file` submodule holds the same pair over plain `Components`, along with `file.Platform`. Always available. See *File paths* below. ### Query `get`, `first`, `last`, `has`, `add`, `set`, `remove`, `removeWhere`. ### Unicode (with `-Dunicode=true`) `Uri.toUri`, `Uri.toIri`, and `TextOptions.form`. The `idna`, `normalization` and `punycode` submodules. `unicode_enabled` reports whether the flag was set. ### LDAP URLs `ldap.Url`, also exported as `LdapUrl`, parses [RFC 4516][4516] `ldap://`, `ldaps://` and `ldapi://` URLs, whose `?`-separated positional sections a generic URI parser cannot recover. Always available. See *LDAP URLs* below. ### Data URLs `data.Url`, also exported as `DataUrl`, parses [RFC 2397][2397] `data:` URLs — the media type, its parameters, and the document itself, decoded — which a generic parser splits at every `/` of a base64 body. Always available. See *Data URLs* below. ### DNS stamps `stamp.Stamp`, also exported as `Stamp`, parses the `sdns://` strings a DNS resolver is published as — all eight protocols, from plain DNS to an oblivious DoH relay. Always available. See *DNS stamps* below. ### Free functions `defaultPort`, `usesNetloc`, `percentEncode`, `percentDecode`, plus the `percent`, `parse`, `format`, `normalize`, `query`, `schemes`, `components`, `punycode`, `ldap`, `data` and `stamp` submodules. ## Differences from `hyperlink` - **`port` is what was written.** `hyperlink`'s `.port` falls back to the scheme's default; here `port` stays `null` unless a port was present, so `http://x` and `http://x:80` round-trip distinctly. Use `effectivePort()` for the fallback behaviour. - **`rooted` and `path` instead of a leading empty segment.** `/a/b` is `rooted = true` with `path = .{ "a", "b" }`. - **An empty fragment is preserved.** `hyperlink` cannot tell `http://x/#` from `http://x/`; here `fragment` is `""` versus `null`. - **`click` follows RFC 3986 §5.2.2 strictly.** `hyperlink` raises `NotImplementedError` for a reference with a scheme and a rootless path; `click("g:h")` here returns `g:h`, as the RFC specifies. All 41 examples in RFC 3986 §5.4 are in the test suite. - **`//` is written only for a real authority.** `hyperlink` emits it for any scheme that could have one, turning `http:/foo` into `http:///foo` — which re-parses with an *empty* host rather than no host. Ask for an empty authority explicitly with `.host = .{ .hostname = "" }`. - **Two default ports are corrected.** `nfs` is 2049 rather than the portmapper's 111, and `rtspu` is 554 rather than 5005. Both are wrong in `hyperlink`; see *Default ports* below for the citations. - **`set` appends when the key is absent**, rather than inserting before the last parameter. - **Address literals are validated.** `hyperlink` accepts whatever sits between the brackets; here an IPv6 literal has to parse, and an IPv4 one has to be four dec-octets. See *Address literals* below. - **Scheme-based normalization is opt-in.** `hyperlink`'s `normalize()` always gives an empty path a `/`; here that is `.root_empty_path = true`, alongside `.drop_default_port`, so the syntax-based rules RFC 3986 §6.2.2 gives stay separable from the scheme-based ones in §6.2.3. - **A few inputs are accepted rather than refused.** A control character in a component is escaped on the way out (`#\n\n` writes as `#%0A%0A`) instead of being a parse error, and an authority ending in a bare `:` has no port rather than being rejected, which is what RFC 3986 §3.2.3 allows and what browsers do. - **IDNA and IRI are opt-in.** `hyperlink` always has them; here they need `-Dunicode=true`, which keeps the default build dependency-free. `toUri` and `toIri` correspond to `to_uri()` and `to_iri()`. See *IDNA and IRI* below. `hyperlink`'s own round-trip corpus and the inputs its tests use to pin down corner cases are in `src/tests_hyperlink.zig`, along with every place the two libraries write the same URI differently — so a deliberate divergence cannot quietly become an accidental one. ## Relative references `click` resolves a reference against a base; `relativize` is the inverse, and finds a reference that resolves back to a given target. It is what generates the link from one document to another: ```zig const base = try uri.Uri.parse(alloc, "https://example.com/docs/intro.html"); const target = try uri.Uri.parse(alloc, "https://example.com/api/v1/index.html"); const rel = try base.relativize(alloc, target, .{}); defer rel.deinit(); try rel.toText(alloc, .{}); // ../api/v1/index.html ``` RFC 3986 specifies resolution and says nothing about going the other way, so what counts as the answer is a choice. The one made here is the shortest reference that resolves to the target, preferring the forms §4.2 lists in the order it lists them — same-document, then relative path, then absolute path, then network path, and failing all of those the target itself. **The round trip is guaranteed by construction, not by hope.** `relativize` resolves its own answer against the base and compares it with the target before returning it, falling back to a copy of the target when the two disagree. So: ```zig const there_and_back = try base.clickUri(alloc, rel); // equals base.clickUri(alloc, target), always ``` Two consequences follow from that check rather than from the algorithm: - **Resolution removes dot segments, so a reference cannot reproduce them.** A target of `http://x/a/../b` relativizes to something resolving to `http://x/b`, which is what resolving the target itself gives as well. - **Some targets no reference can reach.** `http://x` — an authority with no path at all — is one: any reference resolved against a base that has a path yields at least `/`. The answer there is the target, unchanged and still absolute, which `isAbsolute()` reports. A differing scheme has the same answer, since a relative reference carries no scheme and can only be read back under the base's. A differing authority does too, unless `.network_path = true` asks for the protocol-relative form: ```zig try base.relativize(alloc, other_host, .{ .network_path = true }); // //other.example/a/b ``` That is off by default because such a reference means different things under different schemes, and a caller relativizing across hosts is usually better told that it cannot be done. `.absolute_path = true` is the other option: it emits `/a/b` rather than walking up with `..`, which is what links that must survive the document itself moving want. ## File paths `Uri.fromPath` builds the [RFC 8089][8089] `file:` URI naming a filesystem path, and `Uri.toPath` reads one back: ```zig const u = try uri.Uri.fromPath(alloc, "/home/jeff/a b.txt", .{}); defer u.deinit(); try u.toText(alloc, .{}); // file:///home/jeff/a%20b.txt try u.toPath(alloc, .{}); // /home/jeff/a b.txt ``` A local path is written with an empty authority and three slashes, which is what browsers, editors and desktop environments expect. Reading accepts the other two forms RFC 8089 §2 makes equivalent: `file://localhost/a` and the authority-less `file:/a`. `.platform` says whose path syntax is being read or written, and defaults to the platform being built for. Naming one explicitly — `.{ .platform = .windows }` — is how a test, or a tool handling paths from somewhere else, converts a Windows path on a POSIX machine. Windows has three shapes, and RFC 8089 Appendix E describes the first two: | | | |---|---| | `C:\Users\me` | a drive path, whose letter becomes the first path segment: `file:///C:/Users/me`. The legacy `file:///C\|/Users/me` reads back as the same path. | | `\\server\share\file` | a UNC path, whose server becomes the URI's host: `file://server/share/file`. | | `\Users\me` | rooted on whatever the current drive is. Not fully qualified, but exactly what `file:///Users/me` reads back as. | A POSIX path round-trips exactly, bytes and all — it is a split and a join, and a path is not required to be UTF-8. A Windows path round-trips *canonically*: both separators are accepted and only `\` is written, so `C:/a` comes back as `C:\a`. **What has no conversion is refused rather than mangled**, which is most of what the tests are about: - A **relative path** has no `file:` URI, since resolving one needs the working directory and that is I/O this library does not do. Ask your `Io` for the directory and descend with `child`. - A **segment holding a separator** has no path. `file:///a%2Fb` names one file called `a/b`, and writing it out would name two. - The **Win32 device namespace** — `\\?\C:\x`, `\\.\PhysicalDrive0` — is not a share, and neither is the `file://./x` that would read back as one. - A path that would be **ambiguous once written**: `\C:` becomes `file:///C:`, which everything reading it takes for the drive, and `file:////a` would become a UNC prefix under an authority that says it is not one. (A colon cannot appear in a Windows filename anyway.) - A **host this platform cannot reach by path**, which on POSIX is every host but `localhost`. Query and fragment are ignored by `toPath`, since neither names anything on a filesystem. Everything else about a `file:` URI is ordinary, so `click`, `relativize` and `normalize` all work on one. ## Address literals Hosts that look like IP addresses are checked with [z46][z46], which is a required dependency — unlike the Unicode support, address literals are core RFC 3986 §3.2.2 syntax rather than an add-on. The literal is *validated*, never rewritten. `[1080:0:0:0:8:800:200C:417A]` round-trips exactly as written rather than being canonicalised to `[1080::8:800:200c:417a]`, which keeps the guarantee in *Components are stored decoded* intact. The consequence is that two spellings of one address are still different `Uri` values: `[::1]` does not equal `[0:0:0:0:0:0:0:1]`. What changes is that malformed literals are now rejected rather than carried through: ```zig try uri.Uri.parse(alloc, "http://[::gg]/"); // error.InvalidIPv6Literal try uri.Uri.parse(alloc, "http://[1:2:3]/"); // error.InvalidIPv6Literal ``` An RFC 6874 zone identifier is accepted in its percent-encoded form, `[fe80::1%25eth0]`, and rejected when the `%` is left bare. RFC 3986's IPvFuture form (`[v7.something]`) is accepted on shape alone, since it has no defined interpretation to check against. For IPv4, RFC 3986 tries `IPv4address` first and falls back to `reg-name`, so anything that is not exactly four dec-octets is simply a host name: ```zig u.host.?.ipv4 // "192.0.2.16" u.host.?.hostname // "192.168.01.1" -- a leading zero is not a dec-octet ``` That last case is the reason to be strict. A parser reading `192.168.01.1` as octal and one reading it as decimal disagree about which host it names. [z46]: https://codeberg.org/jcollie/z46 ## IDNA and IRI Building with `-Dunicode=true` adds internationalized domain names and IRIs. The core parser is unchanged and dependency-free without it; the flag pulls in [uucode][uucode] for Unicode character data. ```sh zig build test -Dunicode=true ``` ```zig const u = try uri.Uri.parse(alloc, "https://Bücher.example/straße?q=café#ü"); const as_uri = try u.toUri(alloc); // host to its xn-- form try as_uri.toText(alloc, .{}); // https://xn--bcher-kva.example/stra%C3%9Fe?q=caf%C3%A9#%C3%BC const as_iri = try as_uri.toIri(alloc); // host back to Unicode try as_iri.toText(alloc, .{ .form = .iri }); // https://bücher.example/straße?q=café#ü ``` `toUri` and `toIri` convert only the *host*, because that is the only component whose two forms differ by more than escaping. Everything else is stored decoded, so `TextOptions.form` decides it: `.uri` percent-encodes non-ASCII (RFC 3986), `.iri` writes the characters RFC 3987 permits literally. `idna.toAscii` and `idna.toUnicode` are also available directly, along with `punycode` (RFC 3492) and `normalization.nfc`. ### What it implements [UTS #46][uts46] — the profile browsers implement — with **non-transitional processing by default**, so `faß.de` encodes to `xn--fa-hia.de` rather than folding to `fass.de`. `Options` exposes `transitional`, `use_std3_ascii_rules`, `check_hyphens`, `check_bidi`, `check_joiners` and `verify_dns_length`. Only the UTS #46 mapping table is generated into this repository (`src/idna_table.zig`, from `IdnaMappingTable.txt`); it is derived data of the UTS with no equivalent in the UCD. Every other Unicode property — general category, script, joining type, bidi class, combining class, canonical decompositions and composition exclusions — comes from uucode. NFC is implemented here rather than taken from a table, on uucode's data. Its inverse composition map is derived on first use by inverting uucode's decompositions, so it can never disagree with the Unicode version uucode was built against. `punycode` needs no Unicode data at all and is compiled in either way. ### Conformance Verified against Unicode's own suites: | Suite | Result | |---|---| | `IdnaTestV2.txt` (UTS #46) | 12,774 checks, 0 failures | | `NormalizationTest.txt` (NFC) | 100,170 checks, 0 failures | | RFC 3492 §7.1 Punycode vectors | all pass | Those suites total about 3.5 MB, too much to ship to every consumer, so a deterministic sample is committed as `src/unicode_vectors.zig` and runs on every build: every 13th case that expects an error, plus a spaced sample of those expected to succeed — 455 IDNA and 364 NFC cases. To re-run the full suites, download them into `testdata/` and regenerate with the scripts in `tools/`, which name the exact source URLs. Two version notes. uucode is built against Unicode 17.0.0, while the newest published `IdnaMappingTable.txt` is 16.0.0 — Unicode has not released IDNA data for 17 yet, so the mapping table trails the character properties by one version. And lone surrogates cannot be carried through a Zig `[]const u8`, so those rows of `IdnaTestV2.txt` are skipped rather than mis-tested; such input is rejected as invalid UTF-8 regardless. [uucode]: https://github.com/jacobsandlund/uucode [uts46]: https://www.unicode.org/reports/tr46/ ## LDAP URLs [RFC 4516][4516] URLs are not URIs with an interesting query. Everything after the host is *positional*, separated by `?` rather than by `&`, and the third position holds an RFC 4515 search filter — which is full of the characters a generic parser reads as structure: ```zig const uri = @import("uri"); const url = try uri.ldap.Url.parse( alloc, "ldap://ldap.example.com/dc=example,dc=com?cn,mail?sub?(&(objectClass=person)(sn=Jensen))", ); defer url.deinit(); url.host.?.hostname // "ldap.example.com" url.effectivePort().? // 389 url.dn.? // "dc=example,dc=com" url.attributes // .{ "cn", "mail" } url.effectiveScope() // .sub url.effectiveFilter() // "(&(objectClass=person)(sn=Jensen))" ``` Through `Uri.parse` that same text gives two query parameters with the filter shredded between them, because the `&` in `(&(objectClass=…)…)` is a parameter separator there. Hence a parser of its own, in the `ldap` submodule — always compiled in, since it needs no Unicode data. | | | |---|---| | `ldap.Url.parse(alloc, text)` | parse an LDAP URL | | `ldap.Url.parseOpts(alloc, text, opts)` | as above, with `.strict_percent` | | `deinit()`, `eql()` | free / compare | | `scheme`, `host`, `port`, `dn`, `attributes`, `scope`, `filter`, `extensions` | plain fields | | `effectivePort()`, `effectiveDn()`, `effectiveScope()`, `effectiveFilter()` | with RFC 4516 §2's defaults applied | | `extension(name)`, `hasCriticalExtension()` | the extensions list | | `write(w)`, `toText(alloc)`, `{f}` | back to text | Three schemes are accepted. `ldap` is the one RFC 4516 defines. `ldaps` — LDAP over TLS on port 636 — was never standardized, and [RFC 4513][4513] §2.1 recommends StartTLS on an `ldap` URL instead, but it is too widely deployed to refuse. `ldapi` is OpenLDAP's extension for a Unix domain socket, where the host is the percent-encoded socket path and there is no port at all. As everywhere else in this library, the fields hold exactly what was written and the defaults are a separate question: `dn` is `null` for `ldap://host` and `""` for `ldap://host/`, and `effectiveDn()` is `""` either way. Text comes back canonically rather than identically escaped, and a trailing run of empty `?` sections is dropped, since nothing distinguishes it from their absence. Two things are deliberately *not* done. The DN is a single decoded string rather than a parsed sequence of RDNs — [RFC 4514][4514] is a grammar of its own, with its own backslash escapes that the URL decoding must leave alone, so `o=An%20Example%5C2C%20Inc.,c=US` yields `o=An Example\2C Inc.,c=US` with the `\2C` still in it. The filter, likewise, is handed over as written rather than parsed into [RFC 4515][4515] terms. Both belong to an LDAP client, not to a URL parser. ## Data URLs [RFC 2397][2397] URLs carry a document in the URL itself, and have none of the structure RFC 3986 looks for: no authority, no hierarchy, and a body that, in base64, is full of the `/` and `+` a generic parser treats as delimiters. ```zig const uri = @import("uri"); const url = try uri.data.Url.parse(alloc, "data:text/plain;charset=utf-8;base64,aMOpbGxv"); defer url.deinit(); url.media_type.? // "text/plain" url.parameter("charset").? // "utf-8" url.base64 // true url.data // "héllo" -- the document, decoded ``` Through `Uri.parse` the same text gives a path of segments cut at each `/` of the base64, which then has to be glued back together and decoded by hand. | | | |---|---| | `data.Url.parse(alloc, text)` | parse a data URL | | `data.Url.parseOpts(alloc, text, opts)` | as above, with `.strict_percent` | | `deinit()`, `eql()` | free / compare | | `media_type`, `parameters`, `base64`, `data`, `fragment` | plain fields | | `effectiveMediaType()`, `effectiveCharset()` | with RFC 2397 §2's default of `text/plain;charset=US-ASCII` applied | | `parameter(name)` | a parameter's value, the name matched without regard to case | | `write(w)`, `toText(alloc)`, `{f}` | back to text | `data` is the document: percent-decoded, and then base64-decoded when the URL says `;base64`. Base64 is accepted with or without its padding and with the line breaks and spaces a URL copied out of a document picks up; it is written back padded and unbroken. Parameters may be written with no media type in front of them — `data:;charset=utf-8,…` — as RFC 2397 allows. The header is split before anything is decoded, so `%2C` in a parameter is a comma in its value rather than the end of the header. A `#` ends the data, and what follows it is kept as `fragment`. ## DNS stamps A DNS stamp is how a resolver is published as one string: `sdns://` and then base64url of a binary structure saying which protocol to speak, where to reach it, and — for the two protocols that authenticate without the web PKI — what key or hash to insist on. It is what a resolver list such as `public-resolvers.md` is made of, and what a DNS client is handed when somebody says "use this resolver". ```zig const uri = @import("uri"); const s = try uri.Stamp.parse( alloc, "sdns://AgcAAAAAAAAABzEuMC4wLjEAEmRucy5jbG91ZGZsYXJlLmNvbQovZG5zLXF1ZXJ5", ); defer s.deinit(); s.protocol() // .doh s.properties().?.no_log // true s.body.doh.address // "1.0.0.1" s.body.doh.hostname // "dns.cloudflare.com" s.body.doh.path // "/dns-query" ``` This is a parser of its own for the same reason `ldap` is. Routing a stamp through `Uri.parse` appears to work — the base64url body lands in `Host.hostname` and comes back unharmed by a coincidence of the alphabet — but `NormalizeOptions.host` would lowercase it, `percent.decode` runs over it whether or not it holds a `%`, and a mistyped stamp is reported as `error.InvalidPort`. None of that is a base to build on. The eight protocols and what each one's body holds. `LP` is a field behind a one-byte length; `VLP` is a list of them, with the high bit set on the length of every element but the last: | | Protocol | Body | |---|---|---| | `0x00` | `plain` | properties, LP(address) | | `0x01` | `dnscrypt` | properties, LP(address), LP(provider key), LP(provider name) | | `0x02` | `doh` | properties, LP(address), VLP(hashes), LP(hostname), LP(path), VLP(bootstrap) | | `0x03` | `dot` | as `doh`, with no path | | `0x04` | `doq` | as `dot` | | `0x05` | `odoh_target` | properties, LP(hostname), LP(path) | | `0x81` | `dnscrypt_relay` | LP(address) — **and no properties word** | | `0x85` | `odoh_relay` | as `doh` | | | | |---|---| | `Stamp.parse(alloc, text)` | parse a stamp | | `deinit()`, `eql()` | free / compare | | `body` | the union, tagged by `Protocol` | | `protocol()`, `properties()`, `address()` | what every stamp answers, whichever variant it is | | `write(w)`, `toText(alloc)`, `{f}` | back to text | Four things are worth knowing before reading a stamp: - **Addresses come back as text**, not as a `z46.Endpoint`, even though this library parses address literals with z46. A z46 type in the API would force every consumer's z46 pin to match this one's; `z46.Endpoint.parse` on the other side costs a line and nothing crosses. - **The relay stamp has no properties word.** `0x81` is the one layout that starts with a length rather than eight bytes of flags, which is why `properties()` returns an optional. - **The properties are advertisement, not evidence.** A stamp is written by whoever publishes the resolver; `dnssec`, `no_log` and `no_filter` are claims. Bits with no assigned meaning are kept, so a stamp written by something newer still round-trips. - **An unknown protocol byte is an error**, not a variant to pass along. A stamp says how to reach a resolver, and a caller handed one it cannot interpret would have to guess. The body is base64url without padding. Padding is accepted when it is there and anything outside the alphabet is refused, and a stamp with bytes left over after its last field is `error.TrailingBytes` rather than a partial parse. ## Specifications The library implements [RFC 3986][3986], *Uniform Resource Identifier (URI): Generic Syntax*. Where the code cites a section, this is what it means: | Section | | Where | |---|---|---| | [§2.1][s2.1] | Percent-Encoding | `percent.encode`, `percent.decode` | | [§2.2][s2.2] | Reserved Characters | the `sub_delims` set in `percent` | | [§2.3][s2.3] | Unreserved Characters | `percent.unreserved_punct` | | [§3.1][s3.1] | Scheme | scheme parsing; case-insensitive lookup in `schemes` | | [§3.2.1][s3.2.1] | User Information | `username` / `password` | | [§3.2.2][s3.2.2] | Host | `Host.ipv4`, `.ipv6`, `.hostname` | | [§3.2.3][s3.2.3] | Port | a bare `:` is an absent port, not a zero one | | [§3.3][s3.3] | Path | `rooted` + `path`; `segment-nz-nc`; the no-authority `//` rule | | [§4.2][s4.2] | Relative Reference | `isAbsolute`; the reference forms `relativize` chooses between | | [§5.2.2][s5.2.2] | Transform References | `click`, strictly; `relativize` inverts it | | [§5.2.3][s5.2.3] | Merge Paths | merging a relative path against the base | | [§5.2.4][s5.2.4] | Remove Dot Segments | `normalize.resolveDotSegments` | | [§5.4][s5.4] | Reference Resolution Examples | all 41 are in the test suite | | [§6.2.2][s6.2.2] | Syntax-Based Normalization | `Uri.normalize` | | [§6.2.2.1][s6.2.2.1] | Case Normalization | lowercased scheme/host, uppercase `%XX` | | [§6.2.3][s6.2.3] | Scheme-Based Normalization | `.drop_default_port`, `.root_empty_path` | RFC 3986 obsoletes [RFC 2396][2396] and updates [RFC 1738][1738], whose remaining scheme definitions were themselves obsoleted piecemeal by RFC 4248 and RFC 4266; neither older document is implemented here, and the RFC 1738 percent-encoding rules in particular should not be assumed. Three related specifications are implemented only in a `-Dunicode=true` build, and one is deliberately left alone: | | | |---|---| | [RFC 3987][3987] | Internationalized Resource Identifiers. `Uri.toUri` and `Uri.toIri` convert the host between its Unicode and `xn--` forms, and `TextOptions.form` decides whether everything else is escaped or written literally. Needs `-Dunicode=true`. | | [RFC 5890][5890], [RFC 5891][5891] | IDNA2008, by way of the [UTS #46][uts46] profile browsers implement. Needs `-Dunicode=true`; without it a non-ASCII host is percent-encoded as UTF-8 rather than converted to Punycode. | | [RFC 6874][6874], obsoleted by [RFC 9844][9844] | IPv6 zone identifiers. `[fe80::1%25eth0]` is accepted in the percent-encoded form the RFC requires, and rejected when the `%` is left bare. The zone is validated for shape and never interpreted. | | [RFC 5952][5952] | IPv6 text representation, deliberately **not** implemented. Address literals are never rewritten, so case and `::` placement survive a round trip. | The `ldap` submodule implements [RFC 4516][4516], *Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator*, whose host and port come straight from RFC 3986 §3.2.2 and §3.2.3. The two grammars it defers to — [RFC 4514][4514] for a distinguished name and [RFC 4515][4515] for a search filter — are carried as decoded strings rather than parsed, and the scopes are those of [RFC 4511][4511] §4.5.1.2. The `data` submodule implements [RFC 2397][2397], *The "data" URL scheme*. Media type parameter names are matched without regard to case, as [RFC 2045][2045] §5.1 has it for MIME. The `stamp` submodule implements the [DNS Stamps specification][stamps], which is not an RFC: it is maintained by Frank Denis alongside `dnscrypt-proxy`, and the protocols it names are defined by the [DNSCrypt version 2 protocol specification][dnscrypt], [RFC 8484][8484] (DoH), [RFC 7858][7858] (DoT), [RFC 9250][9250] (DoQ) and [RFC 9230][9230] (Oblivious DoH). The `file` submodule implements [RFC 8089][8089], *The "file" URI Scheme*, including the Windows drive letters and UNC paths of its Appendix E. See *File paths* above for what it does not convert. The scheme tables in `schemes.zig` follow [RFC 7595][7595] (BCP 35) and the IANA registries. Schemes appearing in the tests and in the rootless-scheme list are defined by [RFC 6068][6068] (`mailto`), [RFC 8089][8089] (`file`) and [RFC 8141][8141] (`urn`). ### Default ports All 40 entries in `defaultPort` were checked against IANA's [Service Name and Transport Protocol Port Number Registry][iana-ports] and, for schemes whose defining document states a default, against that RFC. Where the two disagree the RFC wins: a default port belongs to the *URI scheme*, and a scheme need not share a name — or a protocol — with the IANA service sitting on its port. Twenty-three entries match an IANA service of the same name outright. The rest are worth recording: | Scheme | Port | | |---|---|---| | `nfs` | 2049 | **Corrected.** Was 111, which is `sunrpc`, the portmapper rather than NFS. [RFC 2224 §3][2224] specifies 2049, matching IANA. | | `rtspu` | 554 | **Corrected.** Was 5005, which IANA assigns to `avt-profile-2`. [RFC 2326 §3.2][2326] gives `rtsp` and `rtspu` one default of 554; they differ in transport, TCP versus UDP, not in port. | | `sftp` | 22 | Correct. SSH File Transfer runs over SSH. IANA's `sftp` is 115, an unrelated and long-obsolete Simple File Transfer Protocol. | | `prospero` | 1525 | Correct. [RFC 4157][4157] says "the port defaults to 1525". IANA's `prospero` is 191; 1525 is its `prospero-np`. | | `ventrilo` | 3784 | Convention, not an assignment — IANA gives 3784 to `bfd-control` ([RFC 5881][5881]). Kept because it is what clients use. | | `afp` `dns` `ircs` `mms` `pop` `smb` `vnc` `wais` `ws` `wss` | — | Correct, but filed by IANA under another service name: `afpovertcp`, `domain`, `ircs-u`, `ms-streaming`, `pop3`, `microsoft-ds`, `rfb`, `z39.50`, and — for `ws`/`wss` — `http` and `https` ([RFC 6455 §3][6455]). | The two corrections are also wrong in Python's `hyperlink` and in `boltons.urlutils`, which is where this table was originally adapted from. `defaultPort` reports what a scheme means by an absent port. It is not a claim that a host is listening there, and `Uri.port` still holds only what was actually written — see `effectivePort()`. [3986]: https://www.rfc-editor.org/rfc/rfc3986 [s2.1]: https://www.rfc-editor.org/rfc/rfc3986#section-2.1 [s2.2]: https://www.rfc-editor.org/rfc/rfc3986#section-2.2 [s2.3]: https://www.rfc-editor.org/rfc/rfc3986#section-2.3 [s3.1]: https://www.rfc-editor.org/rfc/rfc3986#section-3.1 [s3.2.1]: https://www.rfc-editor.org/rfc/rfc3986#section-3.2.1 [s3.2.2]: https://www.rfc-editor.org/rfc/rfc3986#section-3.2.2 [s3.2.3]: https://www.rfc-editor.org/rfc/rfc3986#section-3.2.3 [s3.3]: https://www.rfc-editor.org/rfc/rfc3986#section-3.3 [s4.2]: https://www.rfc-editor.org/rfc/rfc3986#section-4.2 [s5.2.2]: https://www.rfc-editor.org/rfc/rfc3986#section-5.2.2 [s5.2.3]: https://www.rfc-editor.org/rfc/rfc3986#section-5.2.3 [s5.2.4]: https://www.rfc-editor.org/rfc/rfc3986#section-5.2.4 [s5.4]: https://www.rfc-editor.org/rfc/rfc3986#section-5.4 [s6.2.2]: https://www.rfc-editor.org/rfc/rfc3986#section-6.2.2 [s6.2.2.1]: https://www.rfc-editor.org/rfc/rfc3986#section-6.2.2.1 [s6.2.3]: https://www.rfc-editor.org/rfc/rfc3986#section-6.2.3 [2396]: https://www.rfc-editor.org/rfc/rfc2396 [1738]: https://www.rfc-editor.org/rfc/rfc1738 [3987]: https://www.rfc-editor.org/rfc/rfc3987 [5890]: https://www.rfc-editor.org/rfc/rfc5890 [5891]: https://www.rfc-editor.org/rfc/rfc5891 [5952]: https://www.rfc-editor.org/rfc/rfc5952 [6068]: https://www.rfc-editor.org/rfc/rfc6068 [6874]: https://www.rfc-editor.org/rfc/rfc6874 [9844]: https://www.rfc-editor.org/rfc/rfc9844 [7595]: https://www.rfc-editor.org/rfc/rfc7595 [8089]: https://www.rfc-editor.org/rfc/rfc8089 [8141]: https://www.rfc-editor.org/rfc/rfc8141 [4511]: https://www.rfc-editor.org/rfc/rfc4511 [4513]: https://www.rfc-editor.org/rfc/rfc4513 [4514]: https://www.rfc-editor.org/rfc/rfc4514 [4515]: https://www.rfc-editor.org/rfc/rfc4515 [4516]: https://www.rfc-editor.org/rfc/rfc4516 [2397]: https://www.rfc-editor.org/rfc/rfc2397 [2045]: https://www.rfc-editor.org/rfc/rfc2045 [stamps]: https://dnscrypt.info/stamps-specifications/ [dnscrypt]: https://dnscrypt.info/protocol/ [7858]: https://www.rfc-editor.org/rfc/rfc7858 [8484]: https://www.rfc-editor.org/rfc/rfc8484 [9230]: https://www.rfc-editor.org/rfc/rfc9230 [9250]: https://www.rfc-editor.org/rfc/rfc9250 [2224]: https://www.rfc-editor.org/rfc/rfc2224 [2326]: https://www.rfc-editor.org/rfc/rfc2326#section-3.2 [4157]: https://www.rfc-editor.org/rfc/rfc4157 [5881]: https://www.rfc-editor.org/rfc/rfc5881 [6455]: https://www.rfc-editor.org/rfc/rfc6455#section-3 [iana-ports]: https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml ## Repository The repository's home is my Forgejo instance at [git.jcollie.dev/jeff/zig-uri](https://git.jcollie.dev/jeff/zig-uri), which is where CI runs and the API documentation is published from. It is also published on [Radicle][radicle] and mirrored to Codeberg and [Tangled](https://tangled.org/jcollie.dev/zig-uri). Any of the four will do; the Radicle copy needs no account and no forge. ```sh # Forgejo git clone https://git.jcollie.dev/jeff/zig-uri.git # Radicle rad clone rad:zrcnvxgQxKm2DSmX3Q9VSF2dHJ8m # Codeberg git clone https://codeberg.org/jcollie/zig-uri.git # Tangled git clone https://tangled.org/jcollie.dev/zig-uri ``` `rad clone` finds seeds through your local node's routing table, so the node has to be running first: ```sh rad node start ``` If you already have the repository and only want to follow it, seeding it makes your node help host it for others: ```sh rad seed rad:zrcnvxgQxKm2DSmX3Q9VSF2dHJ8m ``` The Radicle repository is public, its default branch is `main`, and it is named `zig-uri` — the same name and default branch as the Forgejo, Codeberg and Tangled copies, so any of the four gives the same history. [radicle]: https://radicle.xyz ## Building ```sh zig build test # run the test suite zig build test -Dunicode=true # ...including IDNA and IRI zig build test --fuzz=1M # ...and search for new failures zig build docs # generate API docs into zig-out/docs zig build docs-serve # ...and read them at http://127.0.0.1:8000/ zig build wasm # build the browser bundle into zig-out/web zig build web-serve # ...and try it at http://127.0.0.1:8001/ zig build test-web # test the JavaScript binding under node nix build .#checks.x86_64-linux.browser # ...and in a real browser ``` ### Fuzzing `src/fuzz.zig` and `src/fuzz_unicode.zig` state the properties that have to hold for any input — parsing and writing are inverses, writing is a fixed point, normalization and reference resolution leave a reference that still round-trips, percent-encoding and Punycode round-trip exactly, and both directions of IDNA agree — and let `std.testing.Smith` generate the inputs. Smith is structure-aware: it is asked for a length, an index or a byte from a restricted alphabet rather than for a flat blob, so the search moves through the shape of a URI reference instead of hammering a string that stops parsing after its first byte. One of the targets builds `Components` by hand, which is how the writer gets fed the values parsing can never produce — a `/` inside a path segment, an `@` inside a host. `zig build test` compiles the fuzz tests and runs each against one smoke input, so they cost an ordinary test run nothing. `zig build test --fuzz=N` is what searches; a failure prints the input it was reached with and saves it to `.zig-cache/f/crash`. Zig 0.16.0 needs two workarounds for this, both in `flake.nix`: its test runner does not compile in fuzz mode (it hands an error return trace to a function that wants a different kind of stack trace), so the devshell points `ZIG_LIB_DIR` at a copy of the library with that one line fixed. Coverage is separately broken — the table of program counters comes out empty — so `--fuzz=N` prints its findings and then fails on the coverage report, and plain `--fuzz` panics in the build runner rather than serving the web UI. So there is a loop of our own as well, in `tools/fuzz.zig`, which runs the same targets against input it makes up and, unlike the other one, says how many inputs it got through: ```console $ zig build fuzz-run # a minute of each target $ zig build fuzz-run -- --seconds 300 --target click $ zig build fuzz-run -Dunicode=true # the IDNA targets as well $ zig build fuzz-run -- --input fuzz-findings/x.bin --target click ``` What it has in place of coverage feedback is a corpus: real references, paths, LDAP URLs and stamps to mutate, since a URI of random bytes stops parsing at its first byte. Two things about that are worth knowing before adding to it. A seed reaches a target through that target's own alphabet — `Smith` copies a byte only when the weights list it and replaces every other with the first weight's, so a seed written as `https://example.com` arrives as `%%%%%://%%a%%%e.%%%`, keeping its shape and losing everything else; the corpora are therefore written in each target's letters, and the targets that ask for plain bytes get a separate one spelled the ordinary way. And the tail of an input is a run of *small numbers* rather than random bytes, because `Smith.value` answers anything out of range with the range's minimum: a random tail would make every boolean false, so `normalize`'s five options would only ever be tested in one of their thirty-two combinations. The loop also holds a `DebugAllocator` and asks it after every input whether anything was left behind, which is a property no fixed test states: every path through `Uri.parse` and what is built on it has to free what it allocated, including the paths an error takes. A leak ends the run, because the memory is still outstanding and every later input would be reported as leaking it too. `docs-serve` exists because the generated viewer fetches `sources.tar` and `main.wasm` at runtime, which a browser refuses to do from a `file://` page — the same reason `zig std` runs a server. Use `-Ddocs-port=N` for a different port. The published copy at [jeff.jcollie.page/zig-uri][docs] is the same output, built with `-Dunicode=true` so it covers `idna`, `normalization` and `punycode` as well as the core parser. CI republishes it whenever `main` goes green. [docs]: https://jeff.jcollie.page/zig-uri/ ## In a browser The library also compiles to WebAssembly, with a JavaScript binding on top of it, so a page can parse and resolve URIs with the same code the Zig tests exercise: ```sh zig build wasm -Dunicode=true # -> zig-out/web/{uri.wasm,uri.js,index.html} zig build web-serve # a demo page at http://127.0.0.1:8001/ ``` `zig-out/web` is the whole of what has to be served. `uri.wasm` is 84 KB without Unicode support and 462 KB with it, or 34 KB and 125 KB over the wire once a server has gzipped it — the difference is almost entirely the UTS #46 and normalization tables. ```js import { init, Uri } from "./uri.js"; await init(); const u = Uri.parse("https://user@example.com/a/b/?q=1&flag#top"); u.host; // "example.com" u.path; // ["a", "b", ""] -- the empty segment is the trailing slash u.first("q"); // { key: "q", value: "1" } u.first("flag") // { key: "flag", value: null } -- a bare key, not an empty one u.resolve("../c/").toString(); // "https://user@example.com/a/c/" u.set("q", "2").toString(); // "https://user@example.com/a/b/?q=2&flag#top" u.child("d").toString(); // "https://user@example.com/a/b/d?q=1&flag#top" Uri.parse("HTTPS://Example.COM:443/a/./b/..") .normalize({ dropDefaultPort: true }) .toString(); // "https://example.com/a/" // These two need a module built with -Dunicode=true. Uri.parse("http://münchen.de/straße").toUri().toString(); // "http://xn--mnchen-3ya.de/stra%C3%9Fe" Uri.parse("http://xn--mnchen-3ya.de/stra%C3%9Fe").toIri().toString({ form: "iri" }); // "http://münchen.de/straße" ``` `init()` fetches `uri.wasm` from beside `uri.js`; pass it a URL, a `Response`, or the bytes if they are already in hand. `initSync(bytes)` is the same thing without the await, which is how the node tests load it. As in Zig, a `Uri` is immutable: `with`, `child`, `sibling`, `resolve`, `normalize`, `add`, `set` and `remove` each return a new one, and instances are frozen. Alongside the class there are text-in/text-out functions — `resolve`, `normalize`, `toUri`, `toIri`, `idnaToAscii`, `idnaToUnicode`, `percentEncode`, `percentDecode` — which never build a JavaScript string from a component and so are exactly as faithful as the Zig library. That distinction matters in one place. A decoded component is a byte string and a JavaScript string is not, so a percent escape that is not valid UTF-8 — `http://x/%FF`, a stray Latin-1 query from a legacy site — arrives as U+FFFD in a `Uri` field and re-encodes as `%EF%BF%BD`. Reading components apart and putting them back together is lossy for such input; the text functions above carry it through unharmed. The ABI itself is documented in `src/wasm.zig`: `(ptr, len)` pairs of UTF-8 in and a static `{ ok, ptr, len }` record out, with option structs flattened to bitfields. It has no imports at all, so `WebAssembly.instantiate(bytes, {})` is the whole of what instantiating it takes. ### Testing it `web/tests.js` is one suite run by two runners. `zig build test-web` runs it under node, which is fast enough to keep in the edit loop. `nix flake check` runs the same suite in a real browser: it boots a NixOS virtual machine, serves the bundle from nginx inside it, and drives headless Chromium against `browser-test.html`, then checks the demo page renders what the library computed. Only the second one exercises what a browser actually does — module resolution, `WebAssembly.instantiateStreaming`, and whether the server sends `application/wasm` — so both run in CI. ## Using it as a dependency The repository lives at [git.jcollie.dev/jeff/zig-uri](https://git.jcollie.dev/jeff/zig-uri), mirrored to [codeberg.org/jcollie/zig-uri](https://codeberg.org/jcollie/zig-uri) and [tangled.org/jcollie.dev/zig-uri](https://tangled.org/jcollie.dev/zig-uri), and on Radicle as `rad:zrcnvxgQxKm2DSmX3Q9VSF2dHJ8m` (see *Repository* above). `zig fetch` needs an HTTP or git URL, which rules out the Radicle copy; any of the https copies serves the same history, and the commands below use the Codeberg mirror because that is what `REUSE.toml` names as the download location. Pin a specific commit — `zig fetch` wants a full 40-character SHA or a ref name, and rejects an abbreviated hash: ```sh zig fetch --save git+https://codeberg.org/jcollie/zig-uri.git# ``` Or name a branch, or take a tarball: ```sh zig fetch --save git+https://codeberg.org/jcollie/zig-uri.git#main zig fetch --save https://codeberg.org/jcollie/zig-uri/archive/main.tar.gz ``` Naming a branch does not leave the dependency floating: `zig fetch` resolves the ref at fetch time and records it as `?ref=main#`, so the pin is still to one commit. Either way `--save` writes the entry and its integrity hash into your `build.zig.zon`, under the name `uri`: ```zig .dependencies = .{ .uri = .{ .url = "git+https://codeberg.org/jcollie/zig-uri.git#04ded71f8d88fded46b3eaf1e8e02f44c8c47b7e", .hash = "uri-0.1.0-yCrwNFS4AQCXVzzGneu7zkEf9kopQC3n8KbzJpyDnFnP", }, }, ``` Then wire the module into whatever needs it, in `build.zig`: ```zig const uri_dep = b.dependency("uri", .{}); exe_module.addImport("uri", uri_dep.module("uri")); ``` To get IDNA and IRI support, ask for it through the dependency — that is what pulls in uucode: ```zig const uri_dep = b.dependency("uri", .{ .unicode = true }); ``` ```zig const uri = @import("uri"); ``` ## References cited Everything this library was written against, with the status each document held when it was consulted. *Specifications* above says what the code does with them; this is the bibliography. ### Generic syntax - Berners-Lee, T., R. Fielding, and L. Masinter. *Uniform Resource Identifier (URI): Generic Syntax*. RFC 3986, STD 66. Internet Engineering Task Force, January 2005. Internet Standard; updated by RFC 7320 and RFC 8820. - Berners-Lee, T., R. Fielding, and L. Masinter. *Uniform Resource Identifiers (URI): Generic Syntax*. RFC 2396. Network Working Group, August 1998. Draft Standard; obsoleted by RFC 3986. - Berners-Lee, T., L. Masinter, and M. McCahill. *Uniform Resource Locators (URL)*. RFC 1738. Network Working Group, December 1994. Proposed Standard; updated by RFC 3986, obsoleted in part by RFC 4248 and RFC 4266. - Thaler, D., T. Hansen, and T. Hardie. *Guidelines and Registration Procedures for URI Schemes*. RFC 7595, BCP 35. Internet Engineering Task Force, June 2015. Best Current Practice; updated by RFC 8615. - Carpenter, B., S. Cheshire, and R. Hinden. *Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers*. RFC 6874. Internet Engineering Task Force, February 2013. Proposed Standard; obsoleted by RFC 9844. - Carpenter, B., and R. Hinden. *Entering IPv6 Zone Identifiers in User Interfaces*. RFC 9844. Internet Engineering Task Force, August 2025. Proposed Standard. - Kawamura, S., and M. Kawashima. *A Recommendation for IPv6 Address Text Representation*. RFC 5952. Internet Engineering Task Force, August 2010. Proposed Standard. Read and deliberately not implemented; see *Address literals* above. ### Internationalization - Duerst, M., and M. Suignard. *Internationalized Resource Identifiers (IRIs)*. RFC 3987. Internet Engineering Task Force, January 2005. Proposed Standard. - Klensin, J. *Internationalized Domain Names for Applications (IDNA): Definitions and Document Framework*. RFC 5890. Internet Engineering Task Force, August 2010. Proposed Standard. - Klensin, J. *Internationalized Domain Names in Applications (IDNA): Protocol*. RFC 5891. Internet Engineering Task Force, August 2010. Proposed Standard. - Faltstrom, P. *The Unicode Code Points and Internationalized Domain Names for Applications (IDNA)*. RFC 5892. Internet Engineering Task Force, August 2010. Proposed Standard; updated by RFC 8753. The source of the CONTEXTJ rules in `idna.zig`. - Alvestrand, H., and C. Karp. *Right-to-Left Scripts for Internationalized Domain Names for Applications (IDNA)*. RFC 5893. Internet Engineering Task Force, August 2010. Proposed Standard. The Bidi rule. - Costello, A. *Punycode: A Bootstring Encoding of Unicode for Internationalized Domain Names in Applications (IDNA)*. RFC 3492. Internet Engineering Task Force, March 2003. Proposed Standard; updated by RFC 5891. - Davis, M., and M. Scherer. *Unicode IDNA Compatibility Processing*. Unicode Technical Standard #46, revision 35, Unicode 17.0.0. Unicode Consortium, 4 September 2025. - Whistler, K. *Unicode Normalization Forms*. Unicode Standard Annex #15, revision 57, Unicode 17.0.0. Unicode Consortium, 30 July 2025. - Whistler, K. *Unicode Character Database*. Unicode Standard Annex #44, revision 36, Unicode 17.0.0. Unicode Consortium, 27 August 2025. The publication that defines `NormalizationTest.txt` and the `idna/` data files the conformance suites are drawn from. ### Individual schemes - Duerst, M., L. Masinter, and J. Zawinski. *The 'mailto' URI Scheme*. RFC 6068. Internet Engineering Task Force, October 2010. Proposed Standard. - Kerwin, M. *The "file" URI Scheme*. RFC 8089. Internet Engineering Task Force, February 2017. Proposed Standard; updated by RFC 9844. - Saint-Andre, P., and J. Klensin. *Uniform Resource Names (URNs)*. RFC 8141. Internet Engineering Task Force, April 2017. Proposed Standard. - Callaghan, B. *NFS URL Scheme*. RFC 2224. Network Working Group, October 1997. Informational. The source of the corrected `nfs` default port. - Schulzrinne, H., A. Rao, and R. Lanphier. *Real Time Streaming Protocol (RTSP)*. RFC 2326. Internet Engineering Task Force, April 1998. Proposed Standard; obsoleted by RFC 7826. The source of the corrected `rtspu` default port. - Hoffman, P. *The prospero URI Scheme*. RFC 4157. Internet Engineering Task Force, August 2005. Historic. - Fette, I., and A. Melnikov. *The WebSocket Protocol*. RFC 6455. Internet Engineering Task Force, December 2011. Proposed Standard; updated by RFC 7936, RFC 8307 and RFC 8441. Why `ws` and `wss` default to the HTTP ports. - Katz, D., and D. Ward. *Bidirectional Forwarding Detection (BFD) for IPv4 and IPv6 (Single Hop)*. RFC 5881. Internet Engineering Task Force, June 2010. Proposed Standard. What IANA assigns port 3784 to, which `ventrilo` uses by convention anyway. ### LDAP - Smith, M., and T. Howes. *Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator*. RFC 4516. Internet Engineering Task Force, June 2006. Proposed Standard. - Sermersheim, J. *Lightweight Directory Access Protocol (LDAP): The Protocol*. RFC 4511. Internet Engineering Task Force, June 2006. Proposed Standard. The search scopes of §4.5.1.2. - Zeilenga, K. *Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names*. RFC 4514. Internet Engineering Task Force, June 2006. Proposed Standard. Carried as a decoded string, not parsed. - Smith, M., and T. Howes. *Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters*. RFC 4515. Internet Engineering Task Force, June 2006. Proposed Standard. Also carried as a decoded string. - Harrison, R. *Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms*. RFC 4513. Internet Engineering Task Force, June 2006. Proposed Standard; updated by RFC 8996. Why `ldaps` was never standardized. ### Data URLs - Masinter, L. *The "data" URL scheme*. RFC 2397. Network Working Group, August 1998. Proposed Standard. - Freed, N., and N. Borenstein. *Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies*. RFC 2045. Network Working Group, November 1996. Draft Standard. Why parameter names are compared without regard to case. ### DNS stamps - Denis, F. *DNS Stamps Specification*. DNSCrypt project, 2024. Retrieved 22 September 2026. - Denis, F. *The DNSCrypt Protocol*. Internet-Draft draft-denis-dprive-dnscrypt, 2026. Work in Progress; editor's copy retrieved 22 September 2026. - Hoffman, P., and P. McManus. *DNS Queries over HTTPS (DoH)*. RFC 8484. Internet Engineering Task Force, October 2018. Proposed Standard. - Hu, Z., L. Zhu, J. Heidemann, A. Mankin, D. Wessels, and P. Hoffman. *Specification for DNS over Transport Layer Security (TLS)*. RFC 7858. Internet Engineering Task Force, May 2016. Proposed Standard; updated by RFC 8310. - Huitema, C., S. Dickinson, and A. Mankin. *DNS over Dedicated QUIC Connections*. RFC 9250. Internet Engineering Task Force, May 2022. Proposed Standard. - Kinnear, E., P. McManus, T. Pauly, T. Verma, and C. A. Wood. *Oblivious DNS over HTTPS*. RFC 9230. Independent Submission, June 2022. Experimental. ### Registries - Internet Assigned Numbers Authority. *Service Name and Transport Protocol Port Number Registry*. Retrieved 23 September 2026. Every entry in `defaultPort` was checked against it. - Internet Assigned Numbers Authority. *Uniform Resource Identifier (URI) Schemes*. Retrieved 23 September 2026. What the tables in `schemes.zig` follow. ### Prior art and dependencies - Hashemi, M. *hyperlink: Immutable, Pythonic, correct URLs*. Python Hyper. The library whose API shape and default-port table this one was adapted from. - Hashemi, M. *boltons*. Its `boltons.urlutils` carries the same default-port table, including the two entries corrected here. - Sandlund, J. *uucode: Unicode character data for Zig*. The source of every Unicode property the `-Dunicode` build uses except the UTS #46 mapping table. These are kept in a Zotero collection named `zig-uri`, which holds the full text of each RFC alongside its entry. ## Licence MIT. See `LICENSES/MIT.txt`.