Something went wrong. Try again.
An HTTP library for Zig 0.17, server and client, HTTP/1.0 through HTTP/3, with the protocol in a module that owns no socket.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// 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"));}