// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // 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; } }