// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! The request target: the second word of an HTTP/1.1 request line, and the //! `:path` and `:authority` of an HTTP/2 or HTTP/3 request, which is why it //! lives here rather than in `http1`. //! //! RFC 9112 §3.2 gives it four forms, and a server has to tell them apart //! because they mean different things: //! //! * origin-form — `/index.html?q=1`, what an ordinary request carries. //! * absolute-form — `http://example.com/index.html`, which a request through //! a proxy carries and which a server must accept in any request, because a //! client is allowed to send it and because a server that guesses at the //! host from the `Host` line when an absolute-form target disagrees is how //! a cache is poisoned. RFC 9112 §3.2.2 settles it: the target wins. //! * authority-form — `example.com:443`, only in a `CONNECT`. //! * asterisk-form — `*`, only in a server-wide `OPTIONS`. //! //! Parsing keeps every slice pointing into the target as it arrived, and //! decodes nothing. Percent-encoding is undone by `resolvePath`, which is a //! separate step because undoing it is where the traversal bugs live and the //! decision about what a decoded `..` means belongs to the thing that is //! about to open a file. const std = @import("std"); const Target = @This(); /// The target exactly as it arrived. raw: []const u8, form: Form, /// The path, percent-encoding intact and always starting with `/` for the /// forms that have one. Empty for authority-form; `*` for asterisk-form. path: []const u8, /// What followed the first `?`, without the `?` itself. Null when there was /// no `?` at all, which is not the same as an empty query: `/a` and `/a?` /// are different targets, and a handler that redirects one to the other /// wants to know which it got. query: ?[]const u8, /// absolute-form only. scheme: ?[]const u8, /// absolute-form and authority-form. authority: ?[]const u8, pub const Form = enum { origin, absolute, authority, asterisk }; pub const ParseError = error{ /// Empty, carrying an octet a target may not contain, or not matching any /// of the four forms. InvalidTarget, }; /// Whether an octet may appear in a request target. /// /// The exclusions are what stops the request line from being rewritten: /// space and the controls would end the target early and let the rest be read /// as the version or as a second request, and `#` would hand the server a /// fragment, which RFC 9110 §7.1 says is never sent. The rest of the /// gen-delims and the non-ASCII octets are let through, because a target /// carrying them is malformed rather than dangerous and rejecting it turns /// a `404` into a `400` for a lot of real traffic. fn isTargetChar(c: u8) bool { return switch (c) { 0x00...0x20, 0x7f => false, '#', '"', '<', '>', '\\', '^', '`', '{', '|', '}' => false, else => true, }; } /// Takes a request target apart, telling the four forms apart by their first /// octets: `*` alone, a leading `/`, a scheme followed by `://`, and /// otherwise a `host:port`. Borrows `raw`, and decodes nothing. pub fn parse(raw: []const u8) ParseError!Target { if (raw.len == 0) return error.InvalidTarget; for (raw) |c| if (!isTargetChar(c)) return error.InvalidTarget; if (std.mem.eql(u8, raw, "*")) return .{ .raw = raw, .form = .asterisk, .path = raw, .query = null, .scheme = null, .authority = null, }; if (raw[0] == '/') { const path, const query = splitQuery(raw); return .{ .raw = raw, .form = .origin, .path = path, .query = query, .scheme = null, .authority = null, }; } if (schemeLen(raw)) |n| { // scheme ":" "//" authority path-abempty [ "?" query ] const after_slashes = raw[n + 3 ..]; const authority_len = std.mem.indexOfAny(u8, after_slashes, "/?") orelse after_slashes.len; const authority = after_slashes[0..authority_len]; // §4.2.1 of RFC 9110: an http URI with an empty host is invalid and a // recipient "MUST reject it", and §4.2.4 forbids userinfo. The same // check authority-form gets, so that `http://:80/` or // `http://u@h/` cannot become the authority a handler is told about. _ = parseAuthority(authority) catch return error.InvalidTarget; const rest = after_slashes[authority_len..]; const path, const query = if (rest.len == 0 or rest[0] == '?') // An absolute URI with an empty path means the root. .{ "/", if (rest.len == 0) null else rest[1..] } else splitQuery(rest); return .{ .raw = raw, .form = .absolute, .path = path, .query = query, .scheme = raw[0..n], .authority = authority, }; } // authority-form. Nothing else may be left, so anything with a path or a // query in it is not a target at all. if (std.mem.indexOfAny(u8, raw, "/?") != null) return error.InvalidTarget; _ = parseAuthority(raw) catch return error.InvalidTarget; return .{ .raw = raw, .form = .authority, .path = "", .query = null, .scheme = null, .authority = raw, }; } fn splitQuery(s: []const u8) struct { []const u8, ?[]const u8 } { const i = std.mem.indexOfScalar(u8, s, '?') orelse return .{ s, null }; return .{ s[0..i], s[i + 1 ..] }; } /// The length of the scheme at the start of `s`, when `s` begins with /// `scheme "://"`. Null otherwise, including for a bare `host:port`, which is /// how authority-form is told from absolute-form. fn schemeLen(s: []const u8) ?usize { if (s.len == 0) return null; if (!std.ascii.isAlphabetic(s[0])) return null; var i: usize = 1; while (i < s.len) : (i += 1) { switch (s[i]) { 'a'...'z', 'A'...'Z', '0'...'9', '+', '-', '.' => {}, ':' => break, else => return null, } } else return null; if (!std.mem.startsWith(u8, s[i..], "://")) return null; return i; } /// A host and an optional port, which is what both an authority and a `Host` /// field line hold. pub const Authority = struct { /// The host, with the brackets around an IPv6 literal removed. host: []const u8, /// Null when the authority named no port, which means the default for /// the scheme. port: ?u16, /// Whether the host arrived as a bracketed IPv6 literal, which has to go /// back in the brackets if it is ever written out again. is_ip6_literal: bool, }; pub const AuthorityError = error{ /// Empty host, an unterminated IPv6 literal, or a port that is not a /// number that fits. InvalidAuthority, }; /// Splits `host[:port]`, understanding the brackets an IPv6 literal is /// carried in. /// /// Userinfo — the `user:pass@` that RFC 3986 allows — is rejected rather than /// ignored. RFC 9110 §4.2.4 forbids it in an http or https URI, and a server /// that quietly drops it will disagree about the host with any participant /// that does not. pub fn parseAuthority(s: []const u8) AuthorityError!Authority { if (s.len == 0) return error.InvalidAuthority; if (std.mem.indexOfScalar(u8, s, '@') != null) return error.InvalidAuthority; if (s[0] == '[') { const close = std.mem.indexOfScalar(u8, s, ']') orelse return error.InvalidAuthority; if (close == 1) return error.InvalidAuthority; const host = s[1..close]; const rest = s[close + 1 ..]; if (rest.len == 0) return .{ .host = host, .port = null, .is_ip6_literal = true }; if (rest[0] != ':') return error.InvalidAuthority; return .{ .host = host, .port = try parsePort(rest[1..]), .is_ip6_literal = true }; } if (std.mem.lastIndexOfScalar(u8, s, ':')) |i| { // A second colon in an unbracketed authority would be an IPv6 // literal that lost its brackets, which is not a valid authority. if (std.mem.indexOfScalar(u8, s, ':').? != i) return error.InvalidAuthority; if (i == 0) return error.InvalidAuthority; return .{ .host = s[0..i], .port = try parsePort(s[i + 1 ..]), .is_ip6_literal = false }; } return .{ .host = s, .port = null, .is_ip6_literal = false }; } fn parsePort(s: []const u8) AuthorityError!u16 { if (s.len == 0) return error.InvalidAuthority; // `parseInt` would take a sign and an underscore; a port takes neither. for (s) |c| if (!std.ascii.isDigit(c)) return error.InvalidAuthority; return std.fmt.parseInt(u16, s, 10) catch error.InvalidAuthority; } pub const ResolveError = error{ /// A `%` not followed by two hexadecimal digits. BadPercentEncoding, /// A segment decoded to something containing a `/`, which would have made /// a path separator out of an octet the client escaped precisely so that /// it would not be one. EmbeddedSeparator, /// A segment decoded to something containing a NUL, which is how a path /// is truncated on the way into a C library. EmbeddedNul, /// More `..` segments than there were segments to leave. PathEscapesRoot, /// `buf` was too small. The result is never longer than the path, so a /// buffer the size of the path always fits. NoSpaceLeft, /// The target has no path: authority-form or asterisk-form. NotAPath, }; /// Percent-decodes the path and removes its `.` and `..` segments, writing /// the result into `buf` and returning the part of it that was used. /// /// This is the function that decides whether a request can read outside what /// the server meant to serve, so it is worth saying exactly what it does: /// /// * Each segment is decoded on its own, and a segment that decodes to /// something containing a `/` is rejected. `%2F` therefore cannot create a /// segment boundary — the client escaped it so that it would not be one, /// and honoring that is the difference between `/files/a%2F..%2Fb` naming /// one odd file and naming `/b`. /// * `.` and `..` are removed after decoding, so `%2e%2e` is a `..`. It has /// to be: `.` is unreserved, so a percent-encoded one is the same character /// by RFC 3986 §6.2.2.2, and a decoder that did not would leave a traversal /// for whatever decodes next. /// * A `..` with nothing left to leave is an error rather than a no-op. RFC /// 3986 discards it; a server has no business serving a request that was /// trying to get above its root, and telling the client so is more use than /// pretending it asked for something else. /// * Empty segments survive, so `/a//b` stays `/a//b`. RFC 3986's algorithm /// keeps them, and a server that collapses them will disagree about the /// path with any cache or proxy in front of it that does not. /// /// The result always begins with `/` and is never longer than `path`. /// /// **Apply it exactly once.** Resolving decodes, so the answer is not a /// request target and must not be fed back in: `/%2541` resolves to `/%41`, /// which resolves again to `/A`. Every double-decoding traversal bug ever /// filed is that sentence, and the defense is to decode at one point and /// carry the decoded path everywhere after it. pub fn resolvePath(t: Target, buf: []u8) ResolveError![]const u8 { switch (t.form) { .origin, .absolute => {}, .authority, .asterisk => return error.NotAPath, } std.debug.assert(t.path.len > 0 and t.path[0] == '/'); var len: usize = 0; var trailing_slash = false; var it = std.mem.splitScalar(u8, t.path[1..], '/'); while (it.next()) |segment| { if (len + 1 > buf.len) return error.NoSpaceLeft; const decoded = try percentDecode(buf[len + 1 ..], segment); if (std.mem.eql(u8, decoded, ".")) { trailing_slash = true; continue; } if (std.mem.eql(u8, decoded, "..")) { if (len == 0) return error.PathEscapesRoot; len = std.mem.lastIndexOfScalar(u8, buf[0..len], '/').?; trailing_slash = true; continue; } if (std.mem.indexOfScalar(u8, decoded, '/') != null) return error.EmbeddedSeparator; if (std.mem.indexOfScalar(u8, decoded, 0) != null) return error.EmbeddedNul; buf[len] = '/'; len += 1 + decoded.len; trailing_slash = false; } if (trailing_slash and (len == 0 or buf[len - 1] != '/')) { if (len + 1 > buf.len) return error.NoSpaceLeft; buf[len] = '/'; len += 1; } if (len == 0) { if (buf.len < 1) return error.NoSpaceLeft; buf[0] = '/'; len = 1; } return buf[0..len]; } /// Undoes percent-encoding into `dest`, returning the part used. /// /// `+` is left alone. It means a space only in /// `application/x-www-form-urlencoded` data, which is a media type rather /// than part of the URI syntax, so a path containing one keeps it and /// `percentDecodeForm` is where the substitution happens. /// /// Nothing is rejected on account of what it decodes to — a `%2F` or a /// `%00` comes out as the octet it names. Whether that is acceptable is the /// caller's question; `resolvePath` is the caller that answers it for a path. pub fn percentDecode(dest: []u8, src: []const u8) error{ BadPercentEncoding, NoSpaceLeft }![]u8 { return decode(dest, src, false); } /// The loop behind both decoders. The `+` substitution has to happen here, /// on the octets as written, because after decoding a `+` that was sent as /// `%2B` can no longer be told from one that was sent as itself. fn decode(dest: []u8, src: []const u8, plus_is_space: bool) error{ BadPercentEncoding, NoSpaceLeft }![]u8 { var len: usize = 0; var i: usize = 0; while (i < src.len) { if (len >= dest.len) return error.NoSpaceLeft; if (src[i] == '%') { if (i + 2 >= src.len) return error.BadPercentEncoding; const hi = std.fmt.charToDigit(src[i + 1], 16) catch return error.BadPercentEncoding; const lo = std.fmt.charToDigit(src[i + 2], 16) catch return error.BadPercentEncoding; dest[len] = hi * 16 + lo; i += 3; } else { dest[len] = if (plus_is_space and src[i] == '+') ' ' else src[i]; i += 1; } len += 1; } return dest[0..len]; } /// Walks a query string as `application/x-www-form-urlencoded` name/value /// pairs, which is what an HTML form and nearly every API put there, though /// nothing in the URI syntax says a query has to be one. /// /// Values are handed over still encoded, because decoding needs somewhere to /// put the result: `percentDecodeForm` is the other half. pub const Query = struct { rest: []const u8, pub const Pair = struct { name: []const u8, /// Null when the pair was a bare name with no `=` at all, which is /// not the same as an empty value. value: ?[]const u8, }; /// The next pair, or null at the end of the query. Pairs are separated /// by `&` or by `;`, and empty ones between two separators are skipped. /// The pair is split at its first `=`, so a value may contain more. pub fn next(q: *Query) ?Pair { while (true) { if (q.rest.len == 0) return null; const end = std.mem.indexOfAny(u8, q.rest, "&;") orelse q.rest.len; const pair = q.rest[0..end]; q.rest = if (end == q.rest.len) q.rest[end..] else q.rest[end + 1 ..]; if (pair.len == 0) continue; if (std.mem.indexOfScalar(u8, pair, '=')) |i| { return .{ .name = pair[0..i], .value = pair[i + 1 ..] }; } return .{ .name = pair, .value = null }; } } test next { var q: Query = .{ .rest = "page=2&&sort=name" }; const page = q.next().?; try std.testing.expectEqualStrings("page", page.name); try std.testing.expectEqualStrings("2", page.value.?); // The empty pair between `&&` is skipped rather than yielded. try std.testing.expectEqualStrings("sort", q.next().?.name); try std.testing.expect(q.next() == null); } }; /// Starts a walk over the query as name/value pairs. An absent query walks as /// an empty one. pub fn queryIterator(t: Target) Query { return .{ .rest = t.query orelse "" }; } /// `percentDecode`, with `+` decoded as a space, which is what form encoding /// means by it. Only a `+` written as itself is a space: `%2B` is how form /// data sends a plus sign, and it decodes to one. pub fn percentDecodeForm(dest: []u8, src: []const u8) error{ BadPercentEncoding, NoSpaceLeft }![]u8 { return decode(dest, src, true); } test "origin-form" { const t = try parse("/a/b?x=1&y=2"); try std.testing.expectEqual(Form.origin, t.form); try std.testing.expectEqualStrings("/a/b", t.path); try std.testing.expectEqualStrings("x=1&y=2", t.query.?); // No `?` at all is not the same as an empty query. try std.testing.expect((try parse("/a")).query == null); try std.testing.expectEqualStrings("", (try parse("/a?")).query.?); } test "absolute-form" { const t = try parse("http://example.com:8080/a?b"); try std.testing.expectEqual(Form.absolute, t.form); try std.testing.expectEqualStrings("http", t.scheme.?); try std.testing.expectEqualStrings("example.com:8080", t.authority.?); try std.testing.expectEqualStrings("/a", t.path); try std.testing.expectEqualStrings("b", t.query.?); // An absolute URI with no path names the root. const root = try parse("http://example.com"); try std.testing.expectEqualStrings("/", root.path); try std.testing.expect(root.query == null); const rooted_query = try parse("http://example.com?q"); try std.testing.expectEqualStrings("/", rooted_query.path); try std.testing.expectEqualStrings("q", rooted_query.query.?); } test "authority-form and asterisk-form" { const a = try parse("example.com:443"); try std.testing.expectEqual(Form.authority, a.form); try std.testing.expectEqualStrings("example.com:443", a.authority.?); const star = try parse("*"); try std.testing.expectEqual(Form.asterisk, star.form); } test "targets that are not targets" { try std.testing.expectError(error.InvalidTarget, parse("")); try std.testing.expectError(error.InvalidTarget, parse("/a b")); try std.testing.expectError(error.InvalidTarget, parse("/a\x00b")); try std.testing.expectError(error.InvalidTarget, parse("/a#frag")); try std.testing.expectError(error.InvalidTarget, parse("/a\r\nX: y")); // A path with no scheme and no leading slash is not authority-form. try std.testing.expectError(error.InvalidTarget, parse("a/b")); } test parseAuthority { const plain = try parseAuthority("example.com"); try std.testing.expectEqualStrings("example.com", plain.host); try std.testing.expect(plain.port == null); const ported = try parseAuthority("example.com:8080"); try std.testing.expectEqualStrings("example.com", ported.host); try std.testing.expectEqual(@as(u16, 8080), ported.port.?); const v6 = try parseAuthority("[2001:db8::1]:443"); try std.testing.expectEqualStrings("2001:db8::1", v6.host); try std.testing.expectEqual(@as(u16, 443), v6.port.?); try std.testing.expect(v6.is_ip6_literal); try std.testing.expectError(error.InvalidAuthority, parseAuthority("")); try std.testing.expectError(error.InvalidAuthority, parseAuthority("user:pass@example.com")); try std.testing.expectError(error.InvalidAuthority, parseAuthority("2001:db8::1")); try std.testing.expectError(error.InvalidAuthority, parseAuthority("[2001:db8::1")); try std.testing.expectError(error.InvalidAuthority, parseAuthority("example.com:99999")); try std.testing.expectError(error.InvalidAuthority, parseAuthority("example.com:")); } fn expectResolved(expected: []const u8, target: []const u8) !void { var buf: [256]u8 = undefined; const t = try parse(target); try std.testing.expectEqualStrings(expected, try t.resolvePath(&buf)); } test resolvePath { try expectResolved("/", "/"); try expectResolved("/a/b", "/a/b"); try expectResolved("/a/", "/a/"); try expectResolved("/a/b", "/a/./b"); try expectResolved("/b", "/a/../b"); try expectResolved("/a/", "/a/b/.."); try expectResolved("/", "/a/.."); try expectResolved("/a//b", "/a//b"); try expectResolved("/a b", "/a%20b"); // A percent-encoded dot segment is a dot segment. try expectResolved("/b", "/a/%2e%2e/b"); // The query is not part of the path, so nothing in it can traverse. try expectResolved("/a", "/a?../../etc/passwd"); // An absolute-form target resolves its path like any other. try expectResolved("/b", "http://example.com/a/../b"); } test "resolvePath refuses to leave the root" { var buf: [256]u8 = undefined; try std.testing.expectError(error.PathEscapesRoot, (try parse("/..")).resolvePath(&buf)); try std.testing.expectError(error.PathEscapesRoot, (try parse("/a/../..")).resolvePath(&buf)); try std.testing.expectError(error.PathEscapesRoot, (try parse("/%2e%2e/etc/passwd")).resolvePath(&buf)); // An escaped separator cannot become one. try std.testing.expectError(error.EmbeddedSeparator, (try parse("/a%2f..%2fb")).resolvePath(&buf)); try std.testing.expectError(error.EmbeddedNul, (try parse("/a%00.png")).resolvePath(&buf)); try std.testing.expectError(error.BadPercentEncoding, (try parse("/a%zz")).resolvePath(&buf)); try std.testing.expectError(error.BadPercentEncoding, (try parse("/a%2")).resolvePath(&buf)); try std.testing.expectError(error.NotAPath, (try parse("*")).resolvePath(&buf)); } test Query { const t = try parse("/s?q=zig+lang&empty=&bare&=novalue"); var it = t.queryIterator(); const first = it.next().?; try std.testing.expectEqualStrings("q", first.name); var buf: [32]u8 = undefined; try std.testing.expectEqualStrings("zig lang", try percentDecodeForm(&buf, first.value.?)); const second = it.next().?; try std.testing.expectEqualStrings("empty", second.name); try std.testing.expectEqualStrings("", second.value.?); const third = it.next().?; try std.testing.expectEqualStrings("bare", third.name); try std.testing.expect(third.value == null); const fourth = it.next().?; try std.testing.expectEqualStrings("", fourth.name); try std.testing.expectEqualStrings("novalue", fourth.value.?); try std.testing.expect(it.next() == null); } test { // Without this, the doctests inside `Query` are never compiled. _ = Query; } test parse { const t = try parse("/search?q=zig"); try std.testing.expectEqual(Form.origin, t.form); try std.testing.expectEqualStrings("/search", t.path); try std.testing.expectEqualStrings("q=zig", t.query.?); // Through a proxy, the same request names its host as well. const proxied = try parse("http://example.com/search?q=zig"); try std.testing.expectEqual(Form.absolute, proxied.form); try std.testing.expectEqualStrings("example.com", proxied.authority.?); try std.testing.expectEqualStrings("/search", proxied.path); try std.testing.expectEqual(Form.authority, (try parse("example.com:443")).form); try std.testing.expectEqual(Form.asterisk, (try parse("*")).form); try std.testing.expectError(error.InvalidTarget, parse("/a b")); } test percentDecode { var buf: [32]u8 = undefined; try std.testing.expectEqualStrings("a b/c", try percentDecode(&buf, "a%20b%2Fc")); // `+` is only a space in form data. try std.testing.expectEqualStrings("a+b", try percentDecode(&buf, "a+b")); try std.testing.expectError(error.BadPercentEncoding, percentDecode(&buf, "%4")); try std.testing.expectError(error.NoSpaceLeft, percentDecode(buf[0..2], "abc")); } test queryIterator { var it = (try parse("/s?lang=zig&v")).queryIterator(); try std.testing.expectEqualStrings("lang", it.next().?.name); try std.testing.expect(it.next().?.value == null); try std.testing.expect(it.next() == null); // No query at all walks as an empty one. var none = (try parse("/s")).queryIterator(); try std.testing.expect(none.next() == null); } test percentDecodeForm { var buf: [32]u8 = undefined; try std.testing.expectEqualStrings("zig lang", try percentDecodeForm(&buf, "zig+lang")); try std.testing.expectEqualStrings("caf\xc3\xa9 au lait", try percentDecodeForm(&buf, "caf%C3%A9+au+lait")); // An encoded plus sign is a plus sign, not a space. try std.testing.expectEqualStrings("1+1 = 2", try percentDecodeForm(&buf, "1%2B1+%3D+2")); }