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.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! Turning a decoded field section into a `Request`: RFC 9113 §8.2 and §8.3,//! which RFC 9114 §4.1 and §4.3 restate almost word for word for HTTP/3.//!//! Shared by both drivers because the rules genuinely are the same. HTTP/3//! inherited the pseudo-header design rather than reinventing it, so the list//! of them, the requirement that they come first, the lower-case field names//! and the refusal of connection-specific fields are one set of rules with//! two section numbers. What differs is the number that ends up in//! `Request.version`, which is why that is a parameter.//!//! Pure, and separate from the driver for the same reason `http1/head.zig` is//! separate — this is where the malformed-request rules live, and they should//! be testable and fuzzable on a slice of fields with no connection anywhere//! near them.//!//! Every failure here is a **stream** error. A malformed request is one//! request's problem, and tearing down a connection for it would take with it//! every other request multiplexed on the same one. The only things that are//! connection errors arrive earlier, in HPACK: a section that does not decode//! leaves the dynamic table out of step and nothing after it can be trusted.
const std = @import("std");const Io = std.Io;const Allocator = std.mem.Allocator;
const protocol = @import("../protocol.zig");const transport = @import("../transport.zig");const Field = protocol.Field;const Headers = protocol.Headers;const Length = protocol.Length;const Method = protocol.Method;const Target = protocol.Target;const token = protocol.token;
const Request = @import("../server/Request.zig");
pub const Error = error{ /// The request is malformed (§8.1.1): a pseudo-header missing, repeated, /// out of place or unknown; a field name that is not lower case or not a /// token; a value carrying an octet that would re-frame the message; a /// connection-specific field; a `content-length` that is not a number. Malformed, /// A `CONNECT`, which this server does not implement. Answered `501` /// rather than treated as malformed, which is what `http1` does with an /// authority-form target for the same reason. NotImplemented, OutOfMemory,};
/// The fields a request's pseudo-headers carry, before they become a/// `Request`.const Pseudo = struct { method: ?[]const u8 = null, scheme: ?[]const u8 = null, authority: ?[]const u8 = null, path: ?[]const u8 = null, /// RFC 8441 §4, and only defined at all when this server has advertised /// `SETTINGS_ENABLE_CONNECT_PROTOCOL`. protocol: ?[]const u8 = null,};
pub const Options = struct { /// Whether `SETTINGS_ENABLE_CONNECT_PROTOCOL` has been advertised. /// /// It has to be asked here because it changes what is malformed. RFC 8441 /// §3 is explicit that a client using `:protocol` without having been /// told it may "would [be] detect[ed as] a malformed request" by a /// non-supporting peer — so when this is false, `:protocol` is an /// undefined pseudo-header and §8.3 rejects it like any other. extended_connect: bool = false, /// Which version this field section arrived over, which is the only thing /// the two callers disagree about. version: protocol.Version = .http_2,};
/// Builds a `Request` from a decoded field section.////// `fields` is consumed: the pseudo-headers are taken out of it and the rest/// become `Request.headers`, which borrows the same storage. Both the fields/// and everything they point at must live in `arena`.pub fn build( io: Io, arena: Allocator, fields: *std.ArrayList(Field), info: transport.Connection.Info, body: Request.Body, options: Options,) Error!Request { var pseudo: Pseudo = .{}; var seen_regular = false; var kept: usize = 0;
for (fields.items) |field| { if (field.name.len == 0) return error.Malformed;
if (field.name[0] == ':') { // §8.3: "All pseudo-header fields MUST appear in a field block // before all regular field lines." One after a regular field is // malformed, not merely untidy -- an intermediary that reordered // them would be rewriting the request. if (seen_regular) return error.Malformed; const slot: *?[]const u8 = if (std.mem.eql(u8, field.name, ":method")) &pseudo.method else if (std.mem.eql(u8, field.name, ":scheme")) &pseudo.scheme else if (std.mem.eql(u8, field.name, ":authority")) &pseudo.authority else if (std.mem.eql(u8, field.name, ":path")) &pseudo.path else if (options.extended_connect and std.mem.eql(u8, field.name, ":protocol")) &pseudo.protocol else // §8.3: an endpoint must treat a request containing an // undefined or a response-only pseudo-header as malformed. // `:status` lands here. return error.Malformed; // §8.3: no pseudo-header may appear more than once. if (slot.* != null) return error.Malformed; if (!token.isFieldValue(field.value)) return error.Malformed; slot.* = field.value; continue; }
seen_regular = true; try checkRegular(field); fields.items[kept] = field; kept += 1; } fields.items.len = kept;
const method = Method.parse(pseudo.method orelse return error.Malformed) catch return error.Malformed;
// §8.5. A plain `CONNECT` has no `:scheme` and no `:path` and means a // tunnel to the host in `:authority`, which this server has nowhere to // hand. RFC 8441's extended CONNECT is a different thing wearing the same // method: `:protocol` names a protocol to speak *on the stream*, and §4 // says the server "MUST NOT create a tunnel to the host indicated by the // :authority as it would with a CONNECT method request that was not // modified by this extension". So the two are told apart by `:protocol` // and nothing else. if (pseudo.protocol) |name| { // RFC 8441 §4 only defines `:protocol` on CONNECT. On anything else // it is a pseudo-header with no meaning, which §8.3 makes malformed. if (!method.eql(Method.connect)) return error.Malformed; if (name.len == 0) return error.Malformed; // The registry it draws from holds tokens, and a value that is not // one could not name an entry in it. if (!token.isToken(name)) return error.Malformed; } else if (method.eql(Method.connect)) { return error.NotImplemented; }
const scheme = pseudo.scheme orelse return error.Malformed; if (scheme.len == 0) return error.Malformed; const path = pseudo.path orelse return error.Malformed; // §8.3.1: "This pseudo-header field MUST NOT be empty for http or https // URIs". if (path.len == 0) return error.Malformed;
var target = Target.parse(path) catch return error.Malformed; switch (target.form) { .origin => {}, // §8.3.1 allows `*` only for an OPTIONS request. .asterisk => if (!method.eql(Method.options)) return error.Malformed, // An absolute or authority form in `:path` is a client trying to slip // a different request past whatever is in front of us. .absolute, .authority => return error.Malformed, }
// The two things HTTP/2 carries beside the path. Without the authority, // `Request.authority()` would fall back to a `host` field that h2 clients // do not send, and return null for every request. target.scheme = scheme; const host = hostOf(fields.items); if (pseudo.authority) |a| { if (a.len == 0) return error.Malformed; _ = Target.parseAuthority(a) catch return error.Malformed; // §8.3.1: if both are present they must agree. A client and a proxy // that believed different ones is the shape of a cache poisoning. if (host) |h| { if (!token.eqlIgnoreCase(h, a)) return error.Malformed; } target.authority = a; } else if (host) |h| { if (h.len == 0) return error.Malformed; _ = Target.parseAuthority(h) catch return error.Malformed; target.authority = h; } else { // §8.3.1 requires `:authority` for an http or https URI unless the // request carries a `Host`. return error.Malformed; }
var declared = body; if (contentLength(fields.items)) |length| { const n = length catch return error.Malformed; declared.length = if (n == 0) .none else .{ .exact = n }; }
return .{ .io = io, .arena = arena, .version = options.version, .method = method, .target = target, .headers = .initBorrowed(fields.items), .connection = info, .body = declared, .connect_protocol = pseudo.protocol, };}
test build { var arena_state: std.heap.ArenaAllocator = .init(testing.allocator); defer arena_state.deinit(); const arena = arena_state.allocator();
var fields: std.ArrayList(Field) = .empty; try fields.appendSlice(arena, &.{ .{ .name = ":method", .value = "GET" }, .{ .name = ":scheme", .value = "https" }, .{ .name = ":authority", .value = "a.example" }, .{ .name = ":path", .value = "/index.html" }, .{ .name = "accept", .value = "text/html" }, }); const req = try build( Io.failing, arena, &fields, .{}, .{ .reader = Request.Body.empty_reader, .length = .none }, .{ .version = .http_3 }, );
try testing.expectEqualStrings("GET", req.method.name); try testing.expectEqualStrings("/index.html", req.target.path); try testing.expectEqualStrings("a.example", req.authority().?); try testing.expectEqual(protocol.Version.http_3, req.version); // The pseudo-headers were taken out; what is left is the headers. try testing.expectEqual(@as(usize, 1), fields.items.len); try testing.expectEqualStrings("text/html", req.header("accept").?);}
/// The rules RFC 9113 §8.2 puts on an ordinary field line.fn checkRegular(field: Field) Error!void { // §8.2.1: "A field name MUST NOT contain characters in the ranges ... // This includes ... uppercase characters". A name that is not a token is // caught by the same check. for (field.name) |c| { if (c >= 'A' and c <= 'Z') return error.Malformed; if (!token.isTokenChar(c)) return error.Malformed; } // §8.2.1 on values, which `isFieldValue` already states exactly: no NUL, // CR or LF, and no leading or trailing space or tab. if (!token.isFieldValue(field.value)) return error.Malformed;
// §8.2.2. These describe a single hop and have no meaning in HTTP/2, // where the connection is managed by frames. const forbidden = [_][]const u8{ "connection", "proxy-connection", "keep-alive", "transfer-encoding", "upgrade", }; for (forbidden) |name| { if (std.mem.eql(u8, field.name, name)) return error.Malformed; } // §8.2.2: "The only exception to this is the TE header field, which MAY // be present in an HTTP/2 request; when it is, it MUST NOT contain any // value other than 'trailers'." if (std.mem.eql(u8, field.name, "te") and !std.mem.eql(u8, field.value, "trailers")) { return error.Malformed; }}
fn hostOf(fields: []const Field) ?[]const u8 { for (fields) |f| { if (std.mem.eql(u8, f.name, "host")) return f.value; } return null;}
fn contentLength(fields: []const Field) ?(error{Malformed}!u64) { var found: ?u64 = null; for (fields) |f| { if (!std.mem.eql(u8, f.name, "content-length")) continue; const n = protocol.parseContentLength(f.value) orelse return error.Malformed; // Two that disagree is the same ambiguity HTTP/1.1 refuses. if (found) |first| { if (first != n) return error.Malformed; } else found = n; } if (found) |n| return n; return null;}
const testing = std.testing;
const Built = struct { arena: std.heap.ArenaAllocator, fields: std.ArrayList(Field), request: Request,
fn deinit(b: *Built) void { b.arena.deinit(); }};
fn buildFrom(fields: []const Field) Error!Built { return buildWith(fields, .{});}
/// The same with `SETTINGS_ENABLE_CONNECT_PROTOCOL` advertised, which changes/// `:protocol` from an undefined pseudo-header into a defined one.fn buildExtended(fields: []const Field) Error!Built { return buildWith(fields, .{ .extended_connect = true });}
fn buildWith(fields: []const Field, options: Options) Error!Built { var b: Built = .{ .arena = .init(testing.allocator), .fields = .empty, .request = undefined, }; errdefer b.arena.deinit(); const arena = b.arena.allocator(); for (fields) |f| try b.fields.append(arena, f); b.request = try build( Io.failing, arena, &b.fields, .{}, .{ .reader = Request.Body.empty_reader, .length = .none }, options, ); return b;}
fn expectMalformed(fields: []const Field) !void { if (buildFrom(fields)) |*b| { var owned = b.*; owned.deinit(); return error.TestExpectedMalformed; } else |err| { try testing.expectEqual(Error.Malformed, err); }}
const ok_request = [_]Field{ .{ .name = ":method", .value = "GET" }, .{ .name = ":scheme", .value = "http" }, .{ .name = ":authority", .value = "a.example" }, .{ .name = ":path", .value = "/thing?q=1" },};
test "an ordinary request" { var b = try buildFrom(&(ok_request ++ [_]Field{ .{ .name = "accept", .value = "text/plain" }, })); defer b.deinit();
try testing.expectEqualStrings("GET", b.request.method.name); try testing.expectEqualStrings("/thing", b.request.target.path); try testing.expectEqualStrings("q=1", b.request.target.query.?); try testing.expectEqualStrings("http", b.request.scheme()); // The line that makes `authority()` work at all over HTTP/2. try testing.expectEqualStrings("a.example", b.request.authority().?); try testing.expectEqual(protocol.Version.http_2, b.request.version);
// The pseudo-headers are gone from the field list; the rest remain. try testing.expectEqual(@as(usize, 1), b.request.headers.fields.items.len); try testing.expectEqualStrings("text/plain", b.request.header("accept").?);}
test "the scheme comes from :scheme, not from the transport" { // A request that says `https` over a connection the transport calls // insecure still reports `https`, because `:scheme` is what the client // asked for and a terminator in front may well have been the TLS end. var b = try buildFrom(&[_]Field{ .{ .name = ":method", .value = "GET" }, .{ .name = ":scheme", .value = "https" }, .{ .name = ":authority", .value = "a.example" }, .{ .name = ":path", .value = "/" }, }); defer b.deinit(); try testing.expectEqualStrings("https", b.request.scheme());}
test "asterisk is for OPTIONS and nothing else" { var b = try buildFrom(&[_]Field{ .{ .name = ":method", .value = "OPTIONS" }, .{ .name = ":scheme", .value = "http" }, .{ .name = ":authority", .value = "a.example" }, .{ .name = ":path", .value = "*" }, }); defer b.deinit(); try testing.expectEqual(Target.Form.asterisk, b.request.target.form);
try expectMalformed(&[_]Field{ .{ .name = ":method", .value = "GET" }, .{ .name = ":scheme", .value = "http" }, .{ .name = ":authority", .value = "a.example" }, .{ .name = ":path", .value = "*" }, });}
test "content-length becomes the declared length" { var b = try buildFrom(&(ok_request ++ [_]Field{ .{ .name = "content-length", .value = "42" }, })); defer b.deinit(); try testing.expectEqual(@as(u64, 42), b.request.body.length.exact);
// Zero is no body at all, not a body of nothing. var z = try buildFrom(&(ok_request ++ [_]Field{ .{ .name = "content-length", .value = "0" }, })); defer z.deinit(); try testing.expectEqual(protocol.Length.none, z.request.body.length);}
test "pseudo-headers that are missing, repeated, late or invented" { // Each of the three required ones, absent. try expectMalformed(&[_]Field{ .{ .name = ":scheme", .value = "http" }, .{ .name = ":path", .value = "/" }, }); try expectMalformed(&[_]Field{ .{ .name = ":method", .value = "GET" }, .{ .name = ":path", .value = "/" }, }); try expectMalformed(&[_]Field{ .{ .name = ":method", .value = "GET" }, .{ .name = ":scheme", .value = "http" }, }); // Repeated. try expectMalformed(&(ok_request ++ [_]Field{ .{ .name = ":path", .value = "/other" }, })); // After a regular field. try expectMalformed(&[_]Field{ .{ .name = ":method", .value = "GET" }, .{ .name = "accept", .value = "*/*" }, .{ .name = ":scheme", .value = "http" }, .{ .name = ":authority", .value = "a" }, .{ .name = ":path", .value = "/" }, }); // Invented, and the response-only one. try expectMalformed(&(ok_request ++ [_]Field{ .{ .name = ":version", .value = "2" }, })); try expectMalformed(&(ok_request ++ [_]Field{ .{ .name = ":status", .value = "200" }, })); // An empty `:path`. try expectMalformed(&[_]Field{ .{ .name = ":method", .value = "GET" }, .{ .name = ":scheme", .value = "http" }, .{ .name = ":authority", .value = "a" }, .{ .name = ":path", .value = "" }, });}
test "an uppercase field name is malformed, not something to fold" { // RFC 9113 §8.2.1. Folding it would mean this server and an intermediary // that refused it disagreed about the request. try expectMalformed(&(ok_request ++ [_]Field{ .{ .name = "Accept", .value = "*/*" }, }));}
test "the connection-specific fields HTTP/2 forbids" { for ([_][]const u8{ "connection", "proxy-connection", "keep-alive", "transfer-encoding", "upgrade", }) |name| { try expectMalformed(&(ok_request ++ [_]Field{ .{ .name = name, .value = "x" }, })); } // `te` is the one exception, and only with this exact value. var b = try buildFrom(&(ok_request ++ [_]Field{ .{ .name = "te", .value = "trailers" }, })); defer b.deinit(); try expectMalformed(&(ok_request ++ [_]Field{ .{ .name = "te", .value = "gzip" }, }));}
test "a value that would re-frame an HTTP/1.1 message downstream" { // Nothing in HPACK stops a field value carrying CR or LF. If this server // accepted one and anything in front of it re-serialised to HTTP/1.1, // that value would become two header lines. try expectMalformed(&(ok_request ++ [_]Field{ .{ .name = "x-evil", .value = "a\r\nInjected: yes" }, })); try expectMalformed(&(ok_request ++ [_]Field{ .{ .name = "x-evil", .value = "trailing " }, }));}
test ":authority and host must agree" { var b = try buildFrom(&(ok_request ++ [_]Field{ .{ .name = "host", .value = "a.example" }, })); defer b.deinit(); try testing.expectEqualStrings("a.example", b.request.authority().?);
try expectMalformed(&(ok_request ++ [_]Field{ .{ .name = "host", .value = "somewhere.else" }, }));
// With no `:authority` at all, `host` stands in. var h = try buildFrom(&[_]Field{ .{ .name = ":method", .value = "GET" }, .{ .name = ":scheme", .value = "http" }, .{ .name = ":path", .value = "/" }, .{ .name = "host", .value = "a.example" }, }); defer h.deinit(); try testing.expectEqualStrings("a.example", h.request.authority().?);
// And with neither, the request cannot be routed. try expectMalformed(&[_]Field{ .{ .name = ":method", .value = "GET" }, .{ .name = ":scheme", .value = "http" }, .{ .name = ":path", .value = "/" }, });}
test "CONNECT is 501 rather than malformed" { const fields = [_]Field{ .{ .name = ":method", .value = "CONNECT" }, .{ .name = ":authority", .value = "a.example:443" }, }; if (buildFrom(&fields)) |*b| { var owned = b.*; owned.deinit(); return error.TestExpectedError; } else |err| { try testing.expectEqual(Error.NotImplemented, err); }}
test "content-lengths that disagree, and ones that are not numbers" { try expectMalformed(&(ok_request ++ [_]Field{ .{ .name = "content-length", .value = "5" }, .{ .name = "content-length", .value = "6" }, })); try expectMalformed(&(ok_request ++ [_]Field{ .{ .name = "content-length", .value = "+5" }, })); // Two that agree are a duplicated header, not a disagreement. var b = try buildFrom(&(ok_request ++ [_]Field{ .{ .name = "content-length", .value = "5" }, .{ .name = "content-length", .value = "5" }, })); defer b.deinit(); try testing.expectEqual(@as(u64, 5), b.request.body.length.exact);}
// -- RFC 8441 extended CONNECT ----------------------------------------------
const extended_connect_request = [_]Field{ .{ .name = ":method", .value = "CONNECT" }, .{ .name = ":protocol", .value = "websocket" }, .{ .name = ":scheme", .value = "https" }, .{ .name = ":path", .value = "/chat" }, .{ .name = ":authority", .value = "server.example.com" },};
test "an extended CONNECT is an ordinary request with a :protocol" { // RFC 8441 §5.1's example, and the point of the test is everything it is // *not*: there is no tunnel to `:authority`, the target is the path, and // a handler sees a request it can route like any other. var b = try buildExtended(&extended_connect_request); defer b.deinit();
try testing.expect(b.request.method.eql(Method.connect)); try testing.expectEqualStrings("websocket", b.request.connect_protocol.?); try testing.expectEqualStrings("/chat", b.request.target.path); try testing.expectEqualStrings("https", b.request.target.scheme.?); try testing.expectEqualStrings("server.example.com", b.request.authority().?); // And the handler's question answers itself, whichever version asked it. try testing.expect(b.request.offersUpgrade("websocket")); try testing.expect(b.request.offersUpgrade("WebSocket")); try testing.expect(!b.request.offersUpgrade("h2c"));}
test "a :protocol is malformed when the setting was never advertised" { // RFC 8441 §3: a client that uses the extension without being told it is // available is talking to a server for which `:protocol` is simply an // undefined pseudo-header, and §8.3 makes that malformed. try expectMalformed(&extended_connect_request);}
test "a plain CONNECT is still not implemented" { const fields = [_]Field{ .{ .name = ":method", .value = "CONNECT" }, .{ .name = ":authority", .value = "example.com:443" }, }; try testing.expectError(Error.NotImplemented, buildExtended(&fields)); try testing.expectError(Error.NotImplemented, buildFrom(&fields));}
test "an extended CONNECT without :scheme or :path is malformed" { // RFC 8441 §4: "On requests that contain the :protocol pseudo-header // field, the :scheme and :path pseudo-header fields of the target URI // MUST also be included." Without them it is a plain CONNECT wearing a // `:protocol`, and the two mean entirely different things. inline for (.{ ":scheme", ":path" }) |missing| { var fields: std.ArrayList(Field) = .empty; defer fields.deinit(testing.allocator); for (extended_connect_request) |f| { if (!std.mem.eql(u8, f.name, missing)) { try fields.append(testing.allocator, f); } } if (buildExtended(fields.items)) |*b| { var owned = b.*; owned.deinit(); return error.TestExpectedMalformed; } else |err| { try testing.expectEqual(Error.Malformed, err); } }}
test "a :protocol on anything but CONNECT is malformed" { try expectMalformedExtended(&.{ .{ .name = ":method", .value = "GET" }, .{ .name = ":protocol", .value = "websocket" }, .{ .name = ":scheme", .value = "https" }, .{ .name = ":path", .value = "/chat" }, .{ .name = ":authority", .value = "a.example" }, });}
test "a :protocol that is not a token is malformed" { try expectMalformedExtended(&.{ .{ .name = ":method", .value = "CONNECT" }, .{ .name = ":protocol", .value = "web socket" }, .{ .name = ":scheme", .value = "https" }, .{ .name = ":path", .value = "/chat" }, .{ .name = ":authority", .value = "a.example" }, });}
test "an extended CONNECT may not carry the fields RFC 6455 used to need" { // RFC 8441 §5: "[RFC6455] requires the use of Connection and Upgrade // header fields that are not part of HTTP/2. They MUST NOT be included in // the CONNECT request defined here." §8.2.2 already refuses them, which // is why there is nothing extra to write — this pins that the two rules // are the same rule. inline for (.{ "connection", "upgrade" }) |name| { var fields: std.ArrayList(Field) = .empty; defer fields.deinit(testing.allocator); try fields.appendSlice(testing.allocator, &extended_connect_request); try fields.append(testing.allocator, .{ .name = name, .value = "upgrade" }); if (buildExtended(fields.items)) |*b| { var owned = b.*; owned.deinit(); return error.TestExpectedMalformed; } else |err| { try testing.expectEqual(Error.Malformed, err); } }}
fn expectMalformedExtended(fields: []const Field) !void { if (buildExtended(fields)) |*b| { var owned = b.*; owned.deinit(); return error.TestExpectedMalformed; } else |err| { try testing.expectEqual(Error.Malformed, err); }}