// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! Syntax-based normalization (RFC 3986 §6.2.2). //! //! Case normalization and dot-segment removal live here. Percent-encoding //! normalization does not need a pass: components are stored decoded, so //! `%41`, `%61` and `A`/`a` are already indistinguishable from each other by //! the time they reach a `Components`, and writing always re-escapes in the //! same canonical form. const std = @import("std"); const format_mod = @import("format.zig"); const schemes = @import("schemes.zig"); const components = @import("components.zig"); const Components = components.Components; pub const Options = struct { /// Lowercase the scheme; scheme comparison is case-insensitive. scheme: bool = true, /// Lowercase a registered name; DNS lookups are case-insensitive. host: bool = true, /// Remove `.` and `..` segments. path: bool = true, /// Drop the port when it is the scheme's default. This is scheme-based /// normalization (RFC 3986 §6.2.3) rather than the syntax-based kind the /// rest of this pass does, so it is off by default; it is worth enabling /// before comparing two URIs for equivalence. drop_default_port: bool = false, /// Give an empty path a `/`, when there is an authority for it to follow: /// RFC 3986 §6.2.3 makes `http://example.com` and `http://example.com/` /// equivalent and names the second as the normal form. Like /// `drop_default_port` this is scheme-based normalization, so it is off by /// default, and like it, it is worth enabling before comparing two URIs. /// /// A reference with no authority is left alone: `mailto:me@example.com` /// has an empty path with nothing for a `/` to follow. root_empty_path: bool = false, }; /// Remove `.` and `..` segments, per RFC 3986 §5.2.4. /// /// A trailing `.` or `..` leaves an empty final segment, so `a/b/..` normalizes /// to `a/` rather than `a` — the result still names a directory. pub fn resolveDotSegments(alloc: std.mem.Allocator, path: []const []const u8) ![]const []const u8 { var out: std.ArrayList([]const u8) = .empty; errdefer out.deinit(alloc); try out.ensureTotalCapacity(alloc, path.len + 1); for (path) |seg| { if (std.mem.eql(u8, seg, ".")) continue; if (std.mem.eql(u8, seg, "..")) { if (out.items.len > 0) _ = out.pop(); continue; } out.appendAssumeCapacity(seg); } if (path.len > 0) { const last = path[path.len - 1]; if (std.mem.eql(u8, last, ".") or std.mem.eql(u8, last, "..")) { try out.append(alloc, ""); } } return out.toOwnedSlice(alloc); } /// A path, in the form the parser would have produced for the same text. pub const Path = struct { rooted: bool, segments: []const []const u8, }; /// Fold a path into the one form of it that survives being written and read /// back, given whether the reference has an authority. /// /// Two shapes need folding, and dot-segment removal produces both: /// /// * A path of a single empty segment that is not rooted has no text of its /// own -- it is written as the empty string, which reads back as no path /// at all. Resolving `..` against `a` leaves exactly that: the trailing /// empty segment that makes a result name a directory, with nothing in /// front of it. Likewise `rooted` with no segments, since the leading `/` /// is only written when a segment follows it. /// * With no authority, a leading empty segment is written as the leading /// `/` and reads back as `rooted`, and a second one would be read back as /// the start of an authority -- `//a` is a host, not a path. So each /// leading empty segment is folded into `rooted`, which is the only text /// the reference can have: resolving `.//` against `x` gives `/`, which is /// what RFC 3986 §5.2.4 arrives at as well. pub fn canonicalPath(has_authority: bool, rooted: bool, path: []const []const u8) Path { var out: Path = .{ .rooted = rooted, .segments = path }; if (!has_authority) { while (out.segments.len > 1 and out.segments[0].len == 0) { out.rooted = true; out.segments = out.segments[1..]; } if (!out.rooted and out.segments.len == 1 and out.segments[0].len == 0) { out.segments = &.{}; } } // An authority is always followed by a `/` when anything follows it at // all, so with an authority `rooted` is exactly "the path is not empty". if (out.segments.len == 0) { out.rooted = false; } else if (has_authority) { out.rooted = true; } return out; } /// Apply the requested normalizations, allocating anything new from `alloc`. /// Untouched fields are borrowed from `c`. pub fn normalize(alloc: std.mem.Allocator, c: Components, opts: Options) !Components { var out = c; if (opts.scheme) { if (c.scheme) |s| out.scheme = try lower(alloc, s); } if (opts.host) { // Only a registered name is case-insensitive; address literals are // already canonical and left exactly as written. if (c.host) |host| switch (host) { .hostname => |s| out.host = .{ .hostname = try lower(alloc, s) }, else => {}, }; } if (opts.path) { const p = canonicalPath( format_mod.hasAuthority(c), out.rooted, try resolveDotSegments(alloc, c.path), ); out.rooted = p.rooted; out.path = p.segments; } if (opts.root_empty_path and out.path.len == 0 and format_mod.hasAuthority(c)) { out.rooted = true; out.path = &.{""}; } if (opts.drop_default_port) { if (c.port != null and out.scheme != null and schemes.defaultPort(out.scheme.?) == c.port) { out.port = null; } } return out; } fn lower(alloc: std.mem.Allocator, s: []const u8) ![]const u8 { const out = try alloc.alloc(u8, s.len); for (s, out) |c, *d| d.* = std.ascii.toLower(c); return out; }