// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! The plain-data pieces a URI decomposes into, shared by the parser, the //! formatter and `Uri` itself. const std = @import("std"); /// The host subcomponent of an authority (RFC 3986 §3.2.2). pub const Host = union(enum) { /// A dotted-quad literal, e.g. `192.0.2.16`. ipv4: []const u8, /// An address literal, *without* the surrounding square brackets. ipv6: []const u8, /// A registered name, decoded. May be empty (`file:///path`). hostname: []const u8, pub fn text(self: Host) []const u8 { return switch (self) { inline else => |s| s, }; } pub fn eql(a: Host, b: Host) bool { return std.meta.activeTag(a) == std.meta.activeTag(b) and std.mem.eql(u8, a.text(), b.text()); } }; /// One `key` or `key=value` pair from the query string, decoded. /// /// A null `value` means the key appeared bare (`?flag`), which is distinct from /// an empty value (`?flag=`). pub const QueryParam = struct { key: []const u8, value: ?[]const u8 = null, pub fn eql(a: QueryParam, b: QueryParam) bool { if (!std.mem.eql(u8, a.key, b.key)) return false; if (a.value == null or b.value == null) return (a.value == null) == (b.value == null); return std.mem.eql(u8, a.value.?, b.value.?); } }; /// Every field of a URI, with no ownership attached. `Uri` embeds these same /// fields; `Components` is how you hand a set of them to a constructor. /// /// All string fields are *decoded*: `path` holds `"a/b"` for the segment /// `a%2Fb`, and writing a `Uri` back out re-escapes as needed. pub const Components = struct { /// Scheme name without the trailing `:`, e.g. `"https"`. Null for a /// relative reference. scheme: ?[]const u8 = null, /// Userinfo before any `:`. Null when no userinfo is present. username: ?[]const u8 = null, /// Userinfo after the first `:`. Null when the userinfo had no `:`. password: ?[]const u8 = null, host: ?Host = null, port: ?u16 = null, /// Whether the path is absolute — i.e. whether it is written with a leading /// `/`. This is kept separate from `path` so that `"/a"` and `"a"` differ /// without an empty leading segment cluttering every path. rooted: bool = false, /// Path segments, decoded, *not* including the empty segment implied by /// `rooted`. `"/a/b/"` is `.{ "a", "b", "" }` with `rooted = true`. /// /// Some combinations have no text of their own, and so are never produced /// by parsing: `rooted` with no segments at all, a single empty segment /// without `rooted`, and -- with no authority for it to follow -- a /// leading empty segment, which is written as the leading `/` rather than /// as a segment. `normalize.canonicalPath` folds a path into the form that /// survives being written and read back. path: []const []const u8 = &.{}, query: []const QueryParam = &.{}, /// Fragment without the leading `#`, decoded. fragment: ?[]const u8 = null, pub fn eql(a: Components, b: Components) bool { if (!optEqlStr(a.scheme, b.scheme)) return false; if (!optEqlStr(a.username, b.username)) return false; if (!optEqlStr(a.password, b.password)) return false; if (a.host == null or b.host == null) { if ((a.host == null) != (b.host == null)) return false; } else if (!a.host.?.eql(b.host.?)) return false; if (a.port != b.port) return false; if (a.rooted != b.rooted) return false; if (a.path.len != b.path.len) return false; for (a.path, b.path) |x, y| if (!std.mem.eql(u8, x, y)) return false; if (a.query.len != b.query.len) return false; for (a.query, b.query) |x, y| if (!x.eql(y)) return false; return optEqlStr(a.fragment, b.fragment); } pub fn hash(self: Components) u64 { var h = std.hash.Wyhash.init(0); hashOptStr(&h, self.scheme); hashOptStr(&h, self.username); hashOptStr(&h, self.password); if (self.host) |host| { h.update(&.{@as(u8, @backingInt(std.meta.activeTag(host)))}); hashStr(&h, host.text()); } else h.update("\xff"); // Hash the payload explicitly: an optional's padding bytes are undefined. if (self.port) |p| { h.update("p"); h.update(std.mem.asBytes(&p)); } else h.update("\xff"); h.update(&.{@intFromBool(self.rooted)}); h.update(std.mem.asBytes(&self.path.len)); for (self.path) |s| hashStr(&h, s); h.update(std.mem.asBytes(&self.query.len)); for (self.query) |p| { hashStr(&h, p.key); hashOptStr(&h, p.value); } hashOptStr(&h, self.fragment); return h.final(); } /// Deep-copy every string into `alloc`. The result borrows nothing from /// `self`; with an arena this is how `Uri` takes ownership of its parts. pub fn dupe(self: Components, alloc: std.mem.Allocator) !Components { var out: Components = .{ .port = self.port, .rooted = self.rooted, }; out.scheme = try dupeOptStr(alloc, self.scheme); out.username = try dupeOptStr(alloc, self.username); out.password = try dupeOptStr(alloc, self.password); if (self.host) |host| out.host = switch (host) { .ipv4 => |s| .{ .ipv4 = try alloc.dupe(u8, s) }, .ipv6 => |s| .{ .ipv6 = try alloc.dupe(u8, s) }, .hostname => |s| .{ .hostname = try alloc.dupe(u8, s) }, }; const path = try alloc.alloc([]const u8, self.path.len); for (self.path, path) |src, *dst| dst.* = try alloc.dupe(u8, src); out.path = path; const query = try alloc.alloc(QueryParam, self.query.len); for (self.query, query) |src, *dst| dst.* = .{ .key = try alloc.dupe(u8, src.key), .value = try dupeOptStr(alloc, src.value), }; out.query = query; out.fragment = try dupeOptStr(alloc, self.fragment); return out; } }; fn optEqlStr(a: ?[]const u8, b: ?[]const u8) bool { if (a == null or b == null) return (a == null) == (b == null); return std.mem.eql(u8, a.?, b.?); } fn dupeOptStr(alloc: std.mem.Allocator, s: ?[]const u8) !?[]const u8 { return if (s) |v| try alloc.dupe(u8, v) else null; } fn hashStr(h: *std.hash.Wyhash, s: []const u8) void { h.update(std.mem.asBytes(&s.len)); h.update(s); } fn hashOptStr(h: *std.hash.Wyhash, s: ?[]const u8) void { if (s) |v| hashStr(h, v) else h.update("\xff"); }