Something went wrong. Try again.
A URI parser and formatter for Zig, modelled on Python's hyperlink package, with LDAP URLs, file: URIs and sdns:// DNS stamps beside it.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! Percent-encoding (RFC 3986 §2.1) and the per-component character sets that//! decide which bytes may appear literally in each part of a URI.//!//! `Uri` stores every component *decoded*, so these sets are only consulted when//! a `Uri` is written back out as text. Each set is the largest set of bytes that//! can appear literally in that component without changing how the result//! re-parses, which keeps output minimally escaped.
const std = @import("std");
pub const Error = error{InvalidPercentEncoding};
/// A set of byte values, used to describe which bytes need no escaping.pub const CharSet = struct { bits: [256]bool = @splat(false),
pub inline fn has(self: *const CharSet, c: u8) bool { return self.bits[c]; }};
/// Build a `CharSet` at comptime: optionally every ASCII alphanumeric, plus the/// bytes in `add`, minus the bytes in `sub`.pub fn charSet(comptime opts: struct { alnum: bool = true, add: []const u8 = "", sub: []const u8 = "",}) CharSet { comptime { @setEvalBranchQuota(10_000); var cs = CharSet{}; if (opts.alnum) { for (0..128) |c| { if (std.ascii.isAlphanumeric(@intCast(c))) cs.bits[c] = true; } } for (opts.add) |c| cs.bits[c] = true; for (opts.sub) |c| cs.bits[c] = false; return cs; }}
/// RFC 3986 §2.3 `unreserved`, minus the alphanumerics that `charSet` adds.pub const unreserved_punct = "-._~";/// RFC 3986 §2.2 `sub-delims`.pub const sub_delims = "!$&'()*+,;=";
/// RFC 3986 §3.1 `scheme` characters (after the mandatory leading ALPHA).pub const scheme: CharSet = charSet(.{ .add = "+-." });
/// A username may not contain a literal `:` — that would start the password.pub const username: CharSet = charSet(.{ .add = unreserved_punct ++ sub_delims });/// A password runs to the `@`, so a literal `:` is unambiguous.pub const password: CharSet = charSet(.{ .add = unreserved_punct ++ sub_delims ++ ":" });/// A registered name ends at `:`, `/`, `?` or `#`.pub const host: CharSet = charSet(.{ .add = unreserved_punct ++ sub_delims });
/// RFC 3986 §3.3 `pchar`. A literal `/` would split the segment, so it is absent.pub const segment: CharSet = charSet(.{ .add = unreserved_punct ++ sub_delims ++ ":@" });/// RFC 3986 §3.3 `segment-nz-nc`: the first segment of a rootless relative/// reference must not contain `:`, or it would be mistaken for a scheme.pub const segment_nc: CharSet = charSet(.{ .add = unreserved_punct ++ sub_delims ++ "@" });
/// `&` separates parameters and `=` separates a key from its value.pub const query_key: CharSet = charSet(.{ .add = unreserved_punct ++ sub_delims ++ ":@/?", .sub = "&=" });/// Only `&` is special in a value; a literal `=` cannot be misread.pub const query_value: CharSet = charSet(.{ .add = unreserved_punct ++ sub_delims ++ ":@/?", .sub = "&" });/// A fragment runs to the end of the reference, so only `#` is excluded.pub const fragment: CharSet = charSet(.{ .add = unreserved_punct ++ sub_delims ++ ":@/?" });
const hex_digits = "0123456789ABCDEF";
/// Write `s` to `w`, escaping every byte outside `safe` as `%XX` with uppercase/// hex digits (the form RFC 3986 §6.2.2.1 prefers).pub fn encode(w: *std.Io.Writer, s: []const u8, safe: *const CharSet) std.Io.Writer.Error!void { var run_start: usize = 0; for (s, 0..) |c, i| { if (safe.has(c)) continue; if (i > run_start) try w.writeAll(s[run_start..i]); try w.writeAll(&.{ '%', hex_digits[c >> 4], hex_digits[c & 0xf] }); run_start = i + 1; } if (run_start < s.len) try w.writeAll(s[run_start..]);}
/// `encode`, into a freshly allocated slice owned by the caller.pub fn encodeAlloc(alloc: std.mem.Allocator, s: []const u8, safe: *const CharSet) ![]u8 { var aw: std.Io.Writer.Allocating = .init(alloc); errdefer aw.deinit(); encode(&aw.writer, s, safe) catch |err| switch (err) { error.WriteFailed => return error.OutOfMemory, }; return aw.toOwnedSlice();}
fn hexValue(c: u8) ?u8 { return switch (c) { '0'...'9' => c - '0', 'a'...'f' => c - 'a' + 10, 'A'...'F' => c - 'A' + 10, else => null, };}
/// Decode `%XX` escapes in `s` into a freshly allocated slice owned by the caller.////// The result is a raw byte string: it is *not* validated as UTF-8, because/// `%FF` and friends are legal in a URI and carry no encoding guarantee.////// When `strict` is false a `%` that is not followed by two hex digits is kept/// as a literal `%` byte, matching what browsers and Python's `hyperlink` do/// with the malformed URLs that occur in practice. When `strict` is true such a/// `%` is an `error.InvalidPercentEncoding`.pub fn decode(alloc: std.mem.Allocator, s: []const u8, strict: bool) (Error || std.mem.Allocator.Error)![]u8 { // The decoded form is never longer than the input, so one exact allocation // does; the common case has no escapes at all and this is a plain copy. const first = std.mem.indexOfScalar(u8, s, '%') orelse return alloc.dupe(u8, s);
var out = try alloc.alloc(u8, s.len); errdefer alloc.free(out);
@memcpy(out[0..first], s[0..first]); var len = first; var i = first; while (i < s.len) { if (s[i] != '%') { out[len] = s[i]; len += 1; i += 1; continue; } const hi = if (i + 2 < s.len) hexValue(s[i + 1]) else null; const lo = if (i + 2 < s.len) hexValue(s[i + 2]) else null; if (hi == null or lo == null) { if (strict) return error.InvalidPercentEncoding; out[len] = '%'; len += 1; i += 1; continue; } out[len] = (hi.? << 4) | lo.?; len += 1; i += 3; } return alloc.realloc(out, len);}
/// RFC 3987 §2.2 `ucschar`: the non-ASCII code points an IRI may carry/// literally, rather than percent-encoded.pub fn isUcsChar(cp: u21) bool { return switch (cp) { 0xA0...0xD7FF, 0xF900...0xFDCF, 0xFDF0...0xFFEF, => true, else => blk: { // The remaining ranges are the first 0xFFFE code points of each // plane from 1 to 13, plus part of plane 14. if (cp < 0x10000 or cp > 0xEFFFD) break :blk false; const plane = cp >> 16; const low = cp & 0xFFFF; if (plane >= 1 and plane <= 13) break :blk low <= 0xFFFD; if (plane == 14) break :blk cp >= 0xE1000 and cp <= 0xEFFFD; break :blk false; }, };}
/// RFC 3987 §2.2 `iprivate`: private-use code points, allowed literally in an/// IRI's query and nowhere else.pub fn isIPrivate(cp: u21) bool { return switch (cp) { 0xE000...0xF8FF, 0xF0000...0xFFFFD, 0x100000...0x10FFFD, => true, else => false, };}
/// How much of a component may be written literally.pub const Form = enum { /// A URI (RFC 3986): ASCII only, so every non-ASCII byte is escaped. uri, /// An IRI (RFC 3987): `ucschar` is written as literal UTF-8. iri, /// An IRI query, which additionally permits `iprivate`. iri_query,};
/// `encode`, but in IRI form the non-ASCII code points RFC 3987 permits are/// written literally instead of being escaped.////// Bytes that are not valid UTF-8 are always escaped: a decoded component may/// hold arbitrary bytes, and an IRI has to remain text.pub fn encodeForm( w: *std.Io.Writer, s: []const u8, safe: *const CharSet, form: Form,) std.Io.Writer.Error!void { if (form == .uri) return encode(w, s, safe);
var i: usize = 0; while (i < s.len) { const c = s[i]; if (c < 0x80) { if (safe.has(c)) { try w.writeByte(c); } else { try w.writeAll(&.{ '%', hex_digits[c >> 4], hex_digits[c & 0xf] }); } i += 1; continue; } const n = std.unicode.utf8ByteSequenceLength(c) catch 0; const cp: ?u21 = if (n >= 2 and i + n <= s.len) (std.unicode.utf8Decode(s[i .. i + n]) catch null) else null; if (cp) |v| { const allowed = isUcsChar(v) or (form == .iri_query and isIPrivate(v)); if (allowed) { try w.writeAll(s[i .. i + n]); i += n; continue; } } // Not a permitted IRI character, or not valid UTF-8 at all. try w.writeAll(&.{ '%', hex_digits[c >> 4], hex_digits[c & 0xf] }); i += 1; }}