// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! The HTTP/2 driver, end to end, over a transport made of a string. //! //! The sibling of `tests/e2e.zig`, and the same argument for existing: what //! matters about an HTTP server is the octets, and a test that called the //! frame parser and then the response writer separately would pass while the //! two disagreed. h2spec in `tests/nixos/h2spec.nix` judges conformance from //! outside, but it costs a virtual machine and it cannot be pointed at a //! handler that misbehaves on purpose. //! //! Two things differ from the HTTP/1.x suite. //! //! The `Io` is real. `e2e.zig` runs on `Io.failing` because the HTTP/1.x //! driver needs no concurrency; the HTTP/2 driver does, structurally — a //! handler reading its own request body waits for DATA frames that only the //! reader task can deliver, so an `Io` that cannot run two tasks at once must //! refuse every stream. So `std.testing.io` it is. The valuable half of the //! HTTP/1.x approach survives: the client's octets are still fixed in //! advance, and there is still no socket and no port. //! //! And the client is written by hand, in `tests/h2/frames.zig`, by code that //! imports nothing from `http`. The response side is read back with the //! library's own HPACK decoder, which is legitimate here in a way it would //! not be on the request side: by the time a response is decoded, that same //! decoder has already correctly understood a request encoded by something //! sharing no code with it, on that same connection, with the dynamic table //! moving underneath both. Appendix C anchors the decoder itself. const std = @import("std"); const Io = std.Io; const testing = std.testing; const http = @import("http"); const Request = http.server.Request; const Response = http.server.Response; const Handler = http.server.Handler; const Field = http.protocol.Field; const frames = @import("h2/frames.zig"); const oracle = @import("h2/oracle.zig"); const Flags = frames.Flags; const Type = frames.Type; const ErrorCode = frames.ErrorCode; const gpa = testing.allocator; const Options = struct { /// Deliver the client's octets this many at a time, or all at once. chunk: usize = 0, read_buffer_len: usize = 8192, config: http.http2.Config = .{ .send_date = false, .server_name = null }, /// What the client's own SETTINGS said, so that the oracle judges frame /// sizes by the number the server was actually given. limits: oracle.Limits = .{}, }; /// Runs one connection and hands back everything the server wrote, parsed. fn converse(client: []const u8, handler: Handler, options: Options) !Conversation { var c: http.transport.memory.Connection = try .init(gpa, client, .{ .chunk = options.chunk, .read_buffer_len = options.read_buffer_len, }); defer c.deinit(); var conn = c.connection(); try http.http2.serve(testing.io, gpa, &conn, handler, options.config); return Conversation.init(try gpa.dupe(u8, c.written()), options); } /// What the server wrote, as frames, and as the responses those frames mean. /// /// `deinit` is not optional and `dump` is the thing to reach for first when a /// test here fails: a diff of two hex strings is not a test failure anybody /// can act on. const Conversation = struct { bytes: []u8, list: []oracle.Frame, arena: std.heap.ArenaAllocator, streams: std.AutoArrayHashMapUnmanaged(u31, Stream), /// What `oracle.check` made of it, kept rather than asserted so that /// `dump` can print the conversation beside the rule it broke. violation: ?oracle.Violation, const Stream = struct { /// One entry per HEADERS frame, in order: an interim response and /// then the final one make two. heads: std.ArrayList([]Field) = .empty, body: std.ArrayList(u8) = .empty, ended: bool = false, reset: ?u32 = null, /// The response proper: the last field section carrying `:status`. /// /// Not simply the last section. A stream can carry several, and two /// of the reasons are different: §15.2 of RFC 9110 lets any number of /// interim `1xx` responses precede the real one, so the *last* with a /// status is the one that counts -- and §8.1 of RFC 9113 lets a /// trailer section follow it, which has no status at all because it /// is not a message head. Taking the last section outright read the /// trailer as the response and reported one with no `:status`. /// /// Empty when the server never sent one, which is what a stream that /// was reset before its response looks like. fn head(s: *const Stream) []const Field { var i = s.heads.items.len; while (i > 0) { i -= 1; for (s.heads.items[i]) |f| { if (std.mem.eql(u8, f.name, ":status")) return s.heads.items[i]; } } return &.{}; } fn get(s: *const Stream, name: []const u8) ?[]const u8 { for (s.head()) |f| { if (std.mem.eql(u8, f.name, name)) return f.value; } return null; } }; fn init(bytes: []u8, options: Options) !Conversation { var c: Conversation = .{ .bytes = bytes, .list = &.{}, .arena = .init(gpa), .streams = .empty, .violation = null, }; errdefer c.deinit(); c.list = try oracle.parse(gpa, bytes); c.violation = oracle.check(c.list, options.limits); // Decoding a conversation whose field blocks are not intact would be // decoding a fiction, so the rules come first and the meaning second. if (c.violation == null) try c.decode(options); return c; } /// Reassembles each field block and decodes it, in arrival order and with /// one decoder, exactly as a client must. fn decode(c: *Conversation, options: Options) !void { const arena = c.arena.allocator(); const scratch = try gpa.alloc(u8, 64 * 1024); defer gpa.free(scratch); var decoder: http.http2.hpack.Decoder = .init( options.config.header_table_size, scratch, .{ .max_header_list_size = 1 << 20 }, ); defer decoder.deinit(gpa); var block: std.ArrayList(u8) = .empty; defer block.deinit(gpa); var at: usize = 0; while (at < c.list.len) : (at += 1) { const f = c.list[at]; switch (f.kind) { Type.headers => { block.clearRetainingCapacity(); try block.appendSlice(gpa, f.payload); var done = f.has(Flags.end_headers); while (!done) { at += 1; try block.appendSlice(gpa, c.list[at].payload); done = c.list[at].has(Flags.end_headers); } var fields: std.ArrayList(Field) = .empty; try decoder.decode(gpa, arena, block.items, &fields); const s = try c.stream(f.stream_id); try s.heads.append(gpa, try fields.toOwnedSlice(arena)); if (f.has(Flags.end_stream)) s.ended = true; }, Type.data => { const s = try c.stream(f.stream_id); try s.body.appendSlice(gpa, f.payload); if (f.has(Flags.end_stream)) s.ended = true; }, Type.rst_stream => { const s = try c.stream(f.stream_id); s.reset = std.mem.readInt(u32, f.payload[0..4], .big); }, else => {}, } } } fn stream(c: *Conversation, id: u31) !*Stream { const entry = try c.streams.getOrPut(gpa, id); if (!entry.found_existing) entry.value_ptr.* = .{}; return entry.value_ptr; } fn deinit(c: *Conversation) void { for (c.streams.values()) |*s| { s.heads.deinit(gpa); s.body.deinit(gpa); } c.streams.deinit(gpa); c.arena.deinit(); gpa.free(c.list); gpa.free(c.bytes); c.* = undefined; } // -- what a test asks it ------------------------------------------------ fn on(c: *Conversation, id: u31) !*const Stream { return c.streams.getPtr(id) orelse { c.dump("no such stream"); return error.NoSuchStream; }; } fn expectStatus(c: *Conversation, id: u31, status: []const u8) !void { const s = try c.on(id); const got = s.get(":status") orelse { c.dump("a response with no :status"); return error.NoStatus; }; testing.expectEqualStrings(status, got) catch |err| { c.dump("wrong status"); return err; }; } fn expectBody(c: *Conversation, id: u31, body: []const u8) !void { const s = try c.on(id); testing.expectEqualStrings(body, s.body.items) catch |err| { c.dump("wrong body"); return err; }; } fn expectField(c: *Conversation, id: u31, name: []const u8, value: []const u8) !void { const s = try c.on(id); const got = s.get(name) orelse { c.dump("a response without the field"); std.debug.print("looked for {s}\n", .{name}); return error.NoSuchField; }; testing.expectEqualStrings(value, got) catch |err| { c.dump("wrong field value"); return err; }; } fn expectNoField(c: *Conversation, id: u31, name: []const u8) !void { const s = try c.on(id); if (s.get(name)) |value| { c.dump("a field that should not be there"); std.debug.print("{s}: {s}\n", .{ name, value }); return error.UnexpectedField; } } fn expectReset(c: *Conversation, id: u31, code: u32) !void { const s = try c.on(id); const got = s.reset orelse { c.dump("no RST_STREAM"); return error.NotReset; }; testing.expectEqualStrings(oracle.errorName(code), oracle.errorName(got)) catch |err| { c.dump("reset with the wrong code"); return err; }; } const Goaway = struct { last_stream_id: u31, code: u32 }; fn goaway(c: *const Conversation) ?Goaway { var last: ?Goaway = null; for (c.list) |f| { if (f.kind != Type.goaway or f.payload.len < 8) continue; last = .{ .last_stream_id = @truncate(std.mem.readInt(u32, f.payload[0..4], .big)), .code = std.mem.readInt(u32, f.payload[4..8], .big), }; } return last; } fn expectGoaway(c: *Conversation, code: u32) !void { const got = c.goaway() orelse { c.dump("no GOAWAY"); return error.NoGoaway; }; testing.expectEqualStrings(oracle.errorName(code), oracle.errorName(got.code)) catch |err| { c.dump("GOAWAY with the wrong code"); return err; }; } /// That the connection ended tidily rather than with a complaint. /// /// Every conversation here ends in a GOAWAY, because the client's octets /// run out and a transport made of a string has no more to give; what /// distinguishes a stream error from a connection error is the code that /// GOAWAY carries, not whether there is one. fn expectNoConnectionError(c: *Conversation) !void { const got = c.goaway() orelse return; if (got.code == ErrorCode.no_error) return; c.dump("a connection error where a stream error was expected"); return error.UnexpectedConnectionError; } fn expectWellFormed(c: *Conversation) !void { if (c.violation) |v| { c.dump(@errorName(v)); return v; } } fn count(c: *const Conversation, kind: u8) usize { var n: usize = 0; for (c.list) |f| { if (f.kind == kind) n += 1; } return n; } /// The whole conversation, frame by frame, with the field sections /// decoded. The first thing to reach for when something here fails. fn dump(c: *const Conversation, why: []const u8) void { var buffer: [4096]u8 = undefined; const locked = std.debug.lockStderr(&buffer); defer std.debug.unlockStderr(); const w = &locked.file_writer.interface; w.print("\n-- {s} -- {d} octets, {d} frames\n", .{ why, c.bytes.len, c.list.len }) catch return; oracle.dump(c.list, w) catch return; var it = c.streams.iterator(); while (it.next()) |entry| { const s = entry.value_ptr; w.print(" stream {d}:", .{entry.key_ptr.*}) catch return; for (s.heads.items) |head| { for (head) |f| w.print(" {s}={s}", .{ f.name, f.value }) catch return; w.print(" |", .{}) catch return; } w.print(" body {d} octets, ended={}\n", .{ s.body.items.len, s.ended }) catch return; } w.flush() catch return; } }; // -- the handlers the tests use --------------------------------------------- fn echo(req: *Request, res: *Response) anyerror!void { try res.setHeader("Content-Type", "text/plain"); const body = try req.body.readAlloc(req.arena, 1 << 20); try res.sendPrint("{s} {s} {s}|{s}|{s}", .{ req.method.name, req.target.path, req.target.query orelse "", req.authority() orelse "", body, }); } const echo_handler: Handler = .initStateless(echo); /// A handler that cannot finish, because its body is larger than the /// connection's send window and nothing in these scripted conversations ever /// sends a WINDOW_UPDATE. /// /// It exists for the reset budget test, which is about what a stream costs /// while it is still being worked on. With a handler that answers instantly /// the test is a race it usually wins: the reader charges the budget as the /// resets arrive, the stream tasks refund it as they complete, and whether /// the charge or the refund lands first is the thread scheduler's business. /// Blocking every handler on flow control removes the refunds and with them /// the race, and it is also the honest shape of the attack -- a stream nobody /// is working on is not what CVE-2023-44487 is about. fn stalls(req: *Request, res: *Response) anyerror!void { _ = req; const w = try res.beginBody(.unknown); var sent: usize = 0; while (sent < 1 << 18) : (sent += 1024) { try w.writeAll(&@as([1024]u8, @splat('x'))); } try res.end(); } const stalling_handler: Handler = .initStateless(stalls); fn empty(req: *Request, res: *Response) anyerror!void { _ = req; res.status = .no_content; // `.none` rather than `.{ .exact = 0 }`: a 204 declaring a length of zero // is a field nobody needs, and over HTTP/2 it is the difference between // END_STREAM on the HEADERS frame and an empty DATA frame after it. _ = try res.beginBody(.none); try res.end(); } fn unknownLength(req: *Request, res: *Response) anyerror!void { _ = req; const w = try res.beginBody(.unknown); try w.writeAll("one"); try w.flush(); try w.writeAll("two"); try res.end(); } fn failing(req: *Request, res: *Response) anyerror!void { _ = .{ req, res }; return error.TheHandlerBroke; } fn failingAfterHead(req: *Request, res: *Response) anyerror!void { _ = req; const w = try res.beginBody(.unknown); try w.writeAll("partial"); try w.flush(); return error.TheHandlerBrokeLate; } // -- the tests -------------------------------------------------------------- test "the simplest request there is" { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, Flags.end_stream, &frames.get("/")); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectStatus(1, "200"); try c.expectBody(1, "GET / |a.example|"); // Lower case on the way out, §8.2.1, although the handler wrote // `Content-Type`. try c.expectField(1, "content-type", "text/plain"); try c.expectField(1, "content-length", "17"); } test "the preface and the settings exchange" { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); // The server's own SETTINGS, the acknowledgement of the client's, and a // WINDOW_UPDATE raising the connection window -- which is the one thing // `SETTINGS_INITIAL_WINDOW_SIZE` cannot do, since §6.9.2 fixes the // connection window at 65535 and only a WINDOW_UPDATE moves it. try testing.expectEqual(@as(usize, 2), c.count(Type.settings)); try testing.expect(c.count(Type.window_update) >= 1); try testing.expect(c.list[0].kind == Type.settings); try testing.expect(!c.list[0].has(Flags.ack)); } test "an octet at a time" { // The framing must not depend on how the octets arrived, which for a // binary protocol means a frame header split across two reads. var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, Flags.end_stream, &frames.get("/slowly")); var c = try converse(b.written(), echo_handler, .{ .chunk = 1 }); defer c.deinit(); try c.expectWellFormed(); try c.expectBody(1, "GET /slowly |a.example|"); } test "three requests multiplexed onto one connection" { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); // Interleaved on purpose, and all opened before any of them is finished: // this is the thing HTTP/1.1 cannot do at all. try b.headers(1, 0, &frames.post("/a")); try b.headers(3, 0, &frames.post("/b")); try b.headers(5, 0, &frames.post("/c")); try b.data(3, Flags.end_stream, "second"); try b.data(5, Flags.end_stream, "third"); try b.data(1, Flags.end_stream, "first"); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectBody(1, "POST /a |a.example|first"); try c.expectBody(3, "POST /b |a.example|second"); try c.expectBody(5, "POST /c |a.example|third"); } test "a request body split across DATA frames" { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, 0, &frames.post("/echo")); try b.data(1, 0, "one "); try b.data(1, 0, "two "); try b.data(1, Flags.end_stream, "three"); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectBody(1, "POST /echo |a.example|one two three"); } test "a field block split across CONTINUATION frames" { const block = try frames.encode(gpa, &frames.get("/split")); defer gpa.free(block); var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); // Three fragments, the middle one empty, which is legal and is the shape // the CVE-2024-27316 flood is built out of. try b.headersRaw(1, Flags.end_stream, block[0..5]); try b.continuation(1, 0, ""); try b.continuation(1, Flags.end_headers, block[5..]); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectBody(1, "GET /split |a.example|"); } test "a body of unknown length is DATA frames and no transfer-encoding" { // The same handler that costs a chunked coding over HTTP/1.1. Sending // `transfer-encoding` at all would make the message malformed (§8.2.2), // and there is nothing to declare a length with, so it is simply DATA. var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, Flags.end_stream, &frames.get("/stream")); var c = try converse(b.written(), .initStateless(unknownLength), .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectBody(1, "onetwo"); try c.expectNoField(1, "transfer-encoding"); try c.expectNoField(1, "content-length"); } test "a response with no body ends on the HEADERS frame" { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, Flags.end_stream, &frames.get("/nothing")); var c = try converse(b.written(), .initStateless(empty), .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectStatus(1, "204"); // No DATA at all: a 204 with an empty DATA frame is a frame wasted, and // §8.1 does not want a body here. try testing.expectEqual(@as(usize, 0), c.count(Type.data)); const s = try c.on(1); try testing.expect(s.ended); } test "HEAD declares the length and sends none of it" { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, Flags.end_stream, &[_]frames.Field{ .{ .name = ":method", .value = "HEAD" }, .{ .name = ":scheme", .value = "http" }, .{ .name = ":authority", .value = "a.example" }, .{ .name = ":path", .value = "/" }, }); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); // The length the matching GET would have had -- "HEAD / |a.example|" -- // declared, and none of the octets sent. try c.expectField(1, "content-length", "18"); try c.expectBody(1, ""); } test "a handler that fails before the head is a 500 on one stream" { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, Flags.end_stream, &frames.get("/boom")); try b.headers(3, Flags.end_stream, &frames.get("/fine")); var c = try converse(b.written(), .initStateless(failing), .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectStatus(1, "500"); // And the connection is still good for the next request, which over // HTTP/1.1 it would not be. try c.expectStatus(3, "500"); try c.expectNoConnectionError(); } test "a handler that fails after the head costs one RST_STREAM" { // The thing HTTP/2 does better: over HTTP/1.1 a handler that fails once // the head has gone can only be reported by closing the connection, // because the framing is already committed. Here it is one stream. var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, Flags.end_stream, &frames.get("/late")); var c = try converse(b.written(), .initStateless(failingAfterHead), .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectStatus(1, "200"); try c.expectReset(1, ErrorCode.internal_error); } // -- what a malformed request gets ------------------------------------------ fn expectMalformed(fields: []const frames.Field) !void { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, Flags.end_stream, fields); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); // §8.1.1: a malformed request is a stream error, not a connection one. // Getting that wrong means one bad request from one client ends every // other request on the connection. try c.expectReset(1, ErrorCode.protocol_error); try c.expectNoConnectionError(); } test "a request missing :path is malformed" { try expectMalformed(&.{ .{ .name = ":method", .value = "GET" }, .{ .name = ":scheme", .value = "http" }, .{ .name = ":authority", .value = "a.example" }, }); } test "a pseudo-header after a regular field is malformed" { // §8.3: they come first, all of them. try expectMalformed(&.{ .{ .name = ":method", .value = "GET" }, .{ .name = ":scheme", .value = "http" }, .{ .name = ":path", .value = "/" }, .{ .name = "accept", .value = "*/*" }, .{ .name = ":authority", .value = "a.example" }, }); } test "an upper-case field name is malformed" { // §8.2.1. The rule exists because a recipient that lower-cases on the way // through can be made to disagree with one that does not. try expectMalformed(&.{ .{ .name = ":method", .value = "GET" }, .{ .name = ":scheme", .value = "http" }, .{ .name = ":authority", .value = "a.example" }, .{ .name = ":path", .value = "/" }, .{ .name = "Accept", .value = "*/*" }, }); } test "a connection-specific field is malformed" { // §8.2.2. `connection` has no meaning in HTTP/2 and carrying one is how a // request is smuggled past a translating intermediary. try expectMalformed(&.{ .{ .name = ":method", .value = "GET" }, .{ .name = ":scheme", .value = "http" }, .{ .name = ":authority", .value = "a.example" }, .{ .name = ":path", .value = "/" }, .{ .name = "connection", .value = "keep-alive" }, }); } test "an unknown pseudo-header is malformed" { try expectMalformed(&.{ .{ .name = ":method", .value = "GET" }, .{ .name = ":scheme", .value = "http" }, .{ .name = ":authority", .value = "a.example" }, .{ .name = ":path", .value = "/" }, .{ .name = ":invented", .value = "x" }, }); } test "an absolute-form :path is malformed" { // The HTTP/1.1 absolute form carried into HTTP/2, where `:scheme` and // `:authority` already say those things. Two ways to say one thing is // exactly what a smuggling attempt needs. try expectMalformed(&.{ .{ .name = ":method", .value = "GET" }, .{ .name = ":scheme", .value = "http" }, .{ .name = ":authority", .value = "a.example" }, .{ .name = ":path", .value = "http://other.example/p" }, }); } // -- what a malformed connection gets --------------------------------------- test "a client that does not send the preface gets a connection error" { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.settings(&.{}); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectGoaway(ErrorCode.protocol_error); } test "a DATA frame on stream zero is a connection error" { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.data(0, 0, "x"); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectGoaway(ErrorCode.protocol_error); } test "a stream identifier that goes backwards is a connection error" { // §5.1.1. Reusing an identifier, or picking one below the highest already // seen, is how a request is made to look like part of an earlier one. var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(3, Flags.end_stream, &frames.get("/first")); try b.headers(1, Flags.end_stream, &frames.get("/second")); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectGoaway(ErrorCode.protocol_error); } test "an even stream identifier is a connection error" { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(2, Flags.end_stream, &frames.get("/")); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectGoaway(ErrorCode.protocol_error); } test "a field block that will not decode is a connection error" { // §4.3: the compression context is the connection's, so a block that // cannot be decoded has cost the connection its ability to decode // anything ever again. It is the one header problem that cannot be a // stream error. var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); // An indexed field representation naming an index that is in no table. try b.headersRaw(1, Flags.end_stream | Flags.end_headers, &.{ 0xff, 0xff, 0xff, 0x7f }); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectGoaway(ErrorCode.compression_error); } test "a frame between a HEADERS and its CONTINUATION is a connection error" { const block = try frames.encode(gpa, &frames.get("/")); defer gpa.free(block); var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headersRaw(1, Flags.end_stream, block[0..5]); try b.ping(0, "12345678"); try b.continuation(1, Flags.end_headers, block[5..]); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectGoaway(ErrorCode.protocol_error); } test "a SETTINGS frame whose length is not a multiple of six is a connection error" { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.raw(Type.settings, 0, 0, "abc"); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectGoaway(ErrorCode.frame_size_error); } test "a frame of an unknown type is ignored" { // §4.1, and it is what makes the protocol extensible: a type nobody knows // must be discarded, not refused. var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.raw(0x42, 0xff, 0, "whatever this is"); try b.headers(1, Flags.end_stream, &frames.get("/after")); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectBody(1, "GET /after |a.example|"); try c.expectNoConnectionError(); } test "a PING is answered with its own payload" { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.ping(0, "abcdefgh"); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); var answered = false; for (c.list) |f| { if (f.kind != Type.ping or !f.has(Flags.ack)) continue; try testing.expectEqualStrings("abcdefgh", f.payload); answered = true; } try testing.expect(answered); } test "a PING acknowledgement is not answered" { // Answering one would be an infinite exchange between two conformant // servers, which is why §6.7 says an ACK gets no reply. var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.ping(Flags.ack, "abcdefgh"); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); try testing.expectEqual(@as(usize, 0), c.count(Type.ping)); } // -- flow control ----------------------------------------------------------- test "the send window is respected and the response stops at it" { // The client opens with a tiny `SETTINGS_INITIAL_WINDOW_SIZE` and then // never opens the window again. Pinning the window in the opening // SETTINGS rather than interleaving a WINDOW_UPDATE is what makes this // assertable against a transport that cannot react: the server writes // everything it is allowed to write and then stops, and what it wrote is // exactly the window. var b: frames.Builder = .init(gpa); defer b.deinit(); try b.bytes.appendSlice(gpa, frames.preface); try b.settings(&.{.{ frames.Setting.initial_window_size, 10 }}); try b.headers(1, Flags.end_stream, &frames.get("/bulk")); var c = try converse(b.written(), .initStateless(bulk), .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectStatus(1, "200"); const s = try c.on(1); try testing.expectEqual(@as(usize, 10), s.body.items.len); try testing.expect(!s.ended); } test "a WINDOW_UPDATE lets the rest of the response out" { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.bytes.appendSlice(gpa, frames.preface); try b.settings(&.{.{ frames.Setting.initial_window_size, 10 }}); try b.headers(1, Flags.end_stream, &frames.get("/bulk")); // Sent ahead of time rather than in response to anything, because this // transport cannot react -- but it reaches the server's flow control by // the same path a reactive one would. try b.windowUpdate(1, 1000); var c = try converse(b.written(), .initStateless(bulk), .{}); defer c.deinit(); try c.expectWellFormed(); const s = try c.on(1); try testing.expectEqual(@as(usize, bulk_body.len), s.body.items.len); try testing.expect(s.ended); } const bulk_body = repeat("0123456789", 10); fn bulk(req: *Request, res: *Response) anyerror!void { _ = req; const w = try res.beginBody(.{ .exact = bulk_body.len }); try w.writeAll(bulk_body); try res.end(); } test "the receive window is replenished as a body is read" { // A body exactly as large as the window the server advertised, which is // all a client may send before hearing back: the whole point of the // window is that the next octet has to be paid for. So what this asserts // is that the server *did* pay -- that reading the body gave the credit // back, rather than leaving a client which had used its whole window // unable to send anything more on that stream ever again. // // The client here could not have reacted anyway; a transport made of a // string has nothing left to say. The credit is still emitted, and it is // still the server's accounting that decides how much. const window = 16384; const body = &@as([window]u8, @splat('x')); var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, 0, &frames.post("/echo")); var sent: usize = 0; while (sent < body.len) : (sent += 512) { const take = @min(512, body.len - sent); const last = sent + take == body.len; try b.data(1, if (last) Flags.end_stream else 0, body[sent..][0..take]); } var c = try converse(b.written(), echo_handler, .{ .config = .{ .send_date = false, .server_name = null, .stream_receive_window = window, }, }); defer c.deinit(); try c.expectWellFormed(); try c.expectBody(1, "POST /echo |a.example|" ++ body); // Credit given back on the stream: some, and never more than was spent. // Too little stalls the next request on that stream; too much is a // window the peer may legitimately overrun. var credited: u64 = 0; for (c.list) |f| { if (f.kind != Type.window_update or f.stream_id != 1) continue; credited += std.mem.readInt(u32, f.payload[0..4], .big); } if (credited == 0 or credited > window) { c.dump("stream credit out of range"); std.debug.print("credited {d} of a {d} window\n", .{ credited, window }); return error.BadStreamCredit; } } // -- the hardening ---------------------------------------------------------- test "a CONTINUATION flood is refused" { // CVE-2024-27316. The attack is a field block that never ends, not a big // one, so what stops it has to be inside the loop that accumulates the // fragments rather than a check on the total afterwards. var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headersRaw(1, Flags.end_stream, ""); for (0..1000) |_| try b.continuation(1, 0, ""); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectGoaway(ErrorCode.enhance_your_calm); // And it gave up long before it read the thousandth frame. try testing.expect(c.bytes.len < 4096); } test "rapid reset runs out of budget" { // CVE-2023-44487. A stream the client resets closes at once and so never // counts against `SETTINGS_MAX_CONCURRENT_STREAMS`, which means the // concurrency limit limits nothing: the client can open and cancel as // fast as it can write, and each one costs a task, an arena and a field // decode. const budget = 20; var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); var id: u32 = 1; while (id < 2 * (budget + 10)) : (id += 2) { try b.headers(id, Flags.end_stream, &frames.get("/")); try b.rstStream(id, ErrorCode.cancel); } var c = try converse(b.written(), stalling_handler, .{ .config = .{ .send_date = false, .server_name = null, .reset_budget = budget, }, }); defer c.deinit(); try c.expectWellFormed(); try c.expectGoaway(ErrorCode.enhance_your_calm); } test "a flood of frames that do nothing is refused" { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); for (0..500) |_| try b.priority(1, 0, 16); var c = try converse(b.written(), echo_handler, .{ .config = .{ .send_date = false, .server_name = null, .max_noise = 50 }, }); defer c.deinit(); try c.expectWellFormed(); try c.expectGoaway(ErrorCode.enhance_your_calm); } test "a header list over the advertised maximum is 431 and not a connection error" { // §6.5.2 is explicit that this is not a connection error, which means the // block still has to be decoded to the end -- the dynamic table must stay // in step or every later block on this connection is nonsense. var fields: std.ArrayList(frames.Field) = .empty; defer fields.deinit(gpa); try fields.appendSlice(gpa, &frames.get("/")); for (0..200) |_| { try fields.append(gpa, .{ .name = "x-padding", .value = repeat("0123456789", 4) }); } var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, Flags.end_stream, fields.items); // And the connection still works afterwards, which is the half that would // silently break if the decoder had stopped early. try b.headers(3, Flags.end_stream, &frames.get("/after")); var c = try converse(b.written(), echo_handler, .{ .config = .{ .send_date = false, .server_name = null, .max_header_list_size = 1024, .max_field_block_len = 64 * 1024, }, }); defer c.deinit(); try c.expectWellFormed(); try c.expectStatus(1, "431"); try c.expectBody(3, "GET /after |a.example|"); } // -- RFC 8441 extended CONNECT ---------------------------------------------- fn connect(path: []const u8, protocol_name: []const u8) [5]frames.Field { return .{ .{ .name = ":method", .value = "CONNECT" }, .{ .name = ":protocol", .value = protocol_name }, .{ .name = ":scheme", .value = "http" }, .{ .name = ":authority", .value = "a.example" }, .{ .name = ":path", .value = path }, }; } /// A handler that switches protocols and then speaks something that is not /// HTTP: it reads a line and writes it back shouting. fn tunnel(req: *Request, res: *Response) anyerror!void { if (!req.offersUpgrade("chat")) return res.sendStatus(.upgrade_required); try res.setHeader("Sec-WebSocket-Protocol", "chat"); const stream = res.upgrade("chat") catch |err| switch (err) { error.NotOffered, error.UpgradeUnavailable => { return res.sendStatus(.upgrade_required); }, else => |e| return e, }; const said = try stream.input.allocRemaining(req.arena, .limited(1 << 16)); const shouted = try std.ascii.allocUpperString(req.arena, said); try stream.output.writeAll(shouted); try stream.output.flush(); } const tunnel_handler: Handler = .initStateless(tunnel); test "an extended CONNECT turns one stream into a tunnel" { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, 0, &connect("/chat", "chat")); try b.data(1, Flags.end_stream, "hello there"); var c = try converse(b.written(), tunnel_handler, .{}); defer c.deinit(); try c.expectWellFormed(); // 200, not 101: RFC 8441 §5.1. There is nothing to switch -- the stream // is the tunnel as soon as a 2xx goes out. try c.expectStatus(1, "200"); try c.expectField(1, "sec-websocket-protocol", "chat"); // And what came back is not HTTP at all. try c.expectBody(1, "HELLO THERE"); const st = try c.on(1); try testing.expect(st.ended); } test "the server advertises SETTINGS_ENABLE_CONNECT_PROTOCOL" { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); var c = try converse(b.written(), tunnel_handler, .{}); defer c.deinit(); try c.expectWellFormed(); // Without this a conformant client will never send `:protocol` at all, // which is the whole of RFC 8441 §3. var advertised = false; for (c.list) |f| { if (f.kind != Type.settings or f.has(Flags.ack)) continue; var at: usize = 0; while (at + 6 <= f.payload.len) : (at += 6) { const id = std.mem.readInt(u16, f.payload[at..][0..2], .big); const value = std.mem.readInt(u32, f.payload[at + 2 ..][0..4], .big); if (id != 0x8) continue; try testing.expectEqual(@as(u32, 1), value); advertised = true; } } try testing.expect(advertised); } test "a tunnel is one stream and the others carry on" { // The thing HTTP/1.1 cannot do at all: there, an upgraded connection is // spent, and every request that would have been multiplexed with it has // to find another socket. var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, 0, &connect("/chat", "chat")); try b.headers(3, Flags.end_stream, &frames.get("/ordinary")); try b.data(1, Flags.end_stream, "still here"); var c = try converse(b.written(), .init(&Router{}, Router.serve), .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectStatus(1, "200"); try c.expectBody(1, "STILL HERE"); try c.expectStatus(3, "200"); try c.expectBody(3, "GET /ordinary |a.example|"); } /// Routes the tunnel path to `tunnel` and everything else to `echo`, so that /// one connection can carry both at once. const Router = struct { fn serve(_: *const Router, req: *Request, res: *Response) anyerror!void { if (std.mem.eql(u8, req.target.path, "/chat")) return tunnel(req, res); return echo(req, res); } }; test "a protocol the client did not offer is refused" { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, Flags.end_stream, &connect("/chat", "something-else")); var c = try converse(b.written(), tunnel_handler, .{}); defer c.deinit(); try c.expectWellFormed(); // The handler asked `offersUpgrade("chat")`, was told no, and sent 426 -- // exactly what it would have done over HTTP/1.1. try c.expectStatus(1, "426"); } test "with the setting switched off, :protocol is malformed" { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, Flags.end_stream, &connect("/chat", "chat")); var c = try converse(b.written(), tunnel_handler, .{ .config = .{ .send_date = false, .server_name = null, .enable_connect_protocol = false, }, }); defer c.deinit(); try c.expectWellFormed(); // RFC 8441 §3 describes exactly this: a non-supporting peer "would detect // a malformed request and generate a stream error". try c.expectReset(1, ErrorCode.protocol_error); try c.expectNoConnectionError(); } test "a plain CONNECT is still refused" { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, Flags.end_stream, &[_]frames.Field{ .{ .name = ":method", .value = "CONNECT" }, .{ .name = ":authority", .value = "elsewhere.example:443" }, }); var c = try converse(b.written(), tunnel_handler, .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectStatus(1, "501"); } test "a tunnel that is never written to still ends the stream" { // The handler returns without saying anything, which for a tunnel means // the peer must still see END_STREAM -- RFC 8441 §5 makes that the // equivalent of an orderly TCP close, and a client waiting for it would // otherwise wait for ever. var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, Flags.end_stream, &connect("/chat", "chat")); var c = try converse(b.written(), .initStateless(silentTunnel), .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectStatus(1, "200"); const st = try c.on(1); try testing.expect(st.ended); } fn silentTunnel(req: *Request, res: *Response) anyerror!void { if (!req.offersUpgrade("chat")) return res.sendStatus(.upgrade_required); _ = try res.upgrade("chat"); } test { std.testing.refAllDecls(@This()); } /// A response whose trailer is only knowable once the body has been produced. fn trailered(_: *Request, res: *Response) anyerror!void { const w = try res.beginBody(.unknown); try w.writeAll("abcde"); try res.trailers.append(res.arena, "x-length", "5"); // §6.5.1 of RFC 9110: refused on the way out, wherever a handler puts it. try res.trailers.append(res.arena, "content-length", "99"); // §8.1 also forbids a pseudo-header in a trailer section, and that one // cannot be tested from here: `Headers.append` validates a name with // `token.isToken`, which excludes `:`, so a handler cannot construct the // field at all. The guard in the driver is belt and braces over an API // that already refuses -- which is worth knowing rather than discovering, // because the attempt fails as a handler error and shows up as an // RST_STREAM with no hint of why. return res.end(); } test "RFC 9113 8.1: a trailer section is a second field block with END_STREAM" { // "An HTTP request or response... can optionally include a trailer // section... sent as a HEADERS frame with the END_STREAM flag set." So // the stream carries two field sections rather than one, and what HTTP/1.1 // needs a special terminator for costs nothing here -- a field section is // already the shape HTTP/2 sends everything in. var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, Flags.end_stream, &frames.get("/")); var c = try converse(b.written(), .initStateless(trailered), .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectStatus(1, "200"); try c.expectBody(1, "abcde"); const s = try c.on(1); try testing.expectEqual(@as(usize, 2), s.heads.items.len); const trailer = s.heads.items[1]; var saw_length = false; for (trailer) |f| { // The framing field did not travel. try testing.expect(!std.mem.eql(u8, f.name, "content-length")); try testing.expect(f.name.len == 0 or f.name[0] != ':'); if (std.mem.eql(u8, f.name, "x-length")) { try testing.expectEqualStrings("5", f.value); saw_length = true; } } try testing.expect(saw_length); // And the stream ended on the trailer section rather than on a DATA // frame, which is what END_STREAM on a HEADERS frame means. try testing.expect(s.ended); } /// `s` said `n` times over: what `s ** n` spelled before Zig 0.17 took the /// operator away. inline fn repeat(comptime s: []const u8, comptime n: usize) *const [s.len * n]u8 { comptime { const rows: [n][s.len]u8 = @splat(s[0..s.len].*); const flat: [s.len * n]u8 = @bitCast(rows); return ♭ } } // RFC 9110 10.1.1: a 100-continue expectation, which a client holding its // content back is waiting on an answer to. /// `post(path)` with an `expect` field after it. fn expecting(path: []const u8, value: []const u8) [5]frames.Field { const p = frames.post(path); return .{ p[0], p[1], p[2], p[3], .{ .name = "expect", .value = value } }; } fn statusOf(head: []const Field) ?[]const u8 { for (head) |f| if (std.mem.eql(u8, f.name, ":status")) return f.value; return null; } /// Answers without reading the body, which is the answer a client holding its /// content back is hoping to hear early. fn refuses(_: *Request, res: *Response) anyerror!void { return res.sendStatus(.unauthorized); } test "RFC 9110 10.1.1: a 100 Continue goes out when the handler asks for the body" { var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, 0, &expecting("/echo", "100-continue")); try b.data(1, Flags.end_stream, "hello"); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); const s = try c.on(1); try testing.expectEqual(@as(usize, 2), s.heads.items.len); try testing.expectEqualStrings("100", statusOf(s.heads.items[0]).?); try c.expectStatus(1, "200"); try c.expectBody(1, "POST /echo |a.example|hello"); } test "RFC 9110 10.1.1: no 100 when the handler answers without the body" { // The client is still holding its content, and the answer it was waiting // for is the refusal itself. var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, 0, &expecting("/private", "100-continue")); var c = try converse(b.written(), .initStateless(refuses), .{}); defer c.deinit(); try c.expectWellFormed(); const s = try c.on(1); try testing.expectEqual(@as(usize, 1), s.heads.items.len); try c.expectStatus(1, "401"); } test "RFC 9110 10.1.1: no 100 for a request whose content has already ended" { // END_STREAM on the HEADERS: there is nothing held back to ask for. var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, Flags.end_stream, &expecting("/echo", "100-continue")); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); try testing.expectEqual(@as(usize, 1), (try c.on(1)).heads.items.len); try c.expectStatus(1, "200"); } test "RFC 9110 10.1.1: an expectation the server does not understand is a 417" { // "A server that receives an Expect field value containing a member other // than 100-continue MAY respond with a 417", and this one does rather // than ignoring a condition the client set on the request. var b: frames.Builder = .init(gpa); defer b.deinit(); try b.begin(); try b.headers(1, 0, &expecting("/echo", "something-else")); try b.data(1, Flags.end_stream, "hello"); var c = try converse(b.written(), echo_handler, .{}); defer c.deinit(); try c.expectWellFormed(); try c.expectStatus(1, "417"); }