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