// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! An HTTP/2 client: RFC 9113 from the other end. //! //! The same seam as everything else here -- a `transport.Connection` is a //! reader and a writer, and this puts frames on one. What differs from the //! HTTP/1.1 client is not the plumbing but the shape of an exchange: HTTP/2 //! is multiplexed, so a request is *begun* and *awaited* as two steps, and //! several may be outstanding between them. //! //! ## Why the pump is the caller's and not a task's //! //! The server runs a reader task and a task per stream, because a server does //! not know when its next request arrives and a handler must not block the //! connection. A client knows exactly what it asked for, so nothing has to //! run on its own: `await` reads frames until the stream it was asked about //! is finished, and frames for *other* streams are filed into their own slots //! as it goes. Two requests begun before either is awaited are genuinely in //! flight at once, which is the whole point of the version, and it costs no //! `Io.Group`, no mutex and no second task. //! //! What it does cost is a buffer per outstanding stream, bounded by the //! window this client advertises -- see `Config.stream_receive_window`. A //! caller that awaits one stream while another is delivering is buffering the //! second, and flow control is what stops that being unbounded. const std = @import("std"); const Io = std.Io; const Allocator = std.mem.Allocator; const protocol = @import("../protocol.zig"); const transport = @import("../transport.zig"); const frame = @import("frame.zig"); const hpack = @import("hpack.zig"); const Settings = @import("Settings.zig"); const Request = @import("../client/Request.zig"); const Response = @import("../client/Response.zig"); const Field = protocol.Field; const Headers = protocol.Headers; const coding = protocol.coding; const token = protocol.token; /// §3.4: the client's connection preface, which is the first thing on the /// wire and is deliberately something no HTTP/1.1 server will answer. pub const preface = @import("../http2.zig").preface; pub const Config = struct { /// What this client advertises per stream, and so the most a response /// body may buffer while another stream is being awaited. stream_receive_window: u31 = 256 * 1024, /// The connection-level receive window. connection_receive_window: u31 = 1024 * 1024, /// How many streams may be outstanding at once, which is the size of the /// table rather than a limit negotiated with anybody -- the server's own /// `SETTINGS_MAX_CONCURRENT_STREAMS` is honored on top of it. max_concurrent_streams: usize = 16, /// The HPACK dynamic table this client will keep for what it receives. header_table_size: u32 = 4096, /// The largest field section this client will accept, summed as §6.5.2 /// counts it. max_header_list_size: u32 = 64 * 1024, /// The largest frame this client will accept. max_frame_size: u24 = 16384, /// The most fields a response may carry. max_fields: usize = 128, /// How many interim responses may come ahead of the final one. See /// `http1.client.Config.max_interim_responses`. max_interim_responses: u8 = 16, /// The most a response body may accumulate. /// /// Flow control bounds what a peer may have *in flight*, not what it may /// send in total: credit is replenished as data is read, so a stream /// window of 256 KiB does not stop a server sending gigabytes. Without /// this the list a body is gathered into grows for as long as the server /// keeps writing, which is a client allocating without limit at a peer's /// choosing. The HTTP/3 driver has had this; this one did not. max_body_len: usize = 8 * 1024 * 1024, /// Content codings to ask for, and to undo when a response carries one. /// See `http1.client.Config.accept_encodings`, which this mirrors — the /// decision, the cost and the field ownership are the same, and only the /// undoing differs: a multiplexed body is gathered before it is decoded /// rather than decoded as it streams. accept_encodings: []const coding.Coding = &.{}, }; pub const Error = error{ WriteFailed, ReadFailed, /// The response body grew past `Config.max_body_len`. BodyTooLong, /// A `Content-Encoding` this end asked for and then could not undo: the /// octets are not that coding, or what they decode to is larger than /// `Config.max_body_len`. BadContentEncoding, /// The server went away, or the connection ended before the response did. NoResponse, /// The server sent something RFC 9113 does not allow, and the connection /// has been closed with a GOAWAY. ProtocolError, /// The response could not be decompressed. §4.3 makes this fatal to the /// connection rather than to the stream: HPACK state is shared, so a /// decoder that has lost its place cannot read any later block either. CompressionError, /// The server refused this stream. Another connection may do. StreamRefused, /// The server reset this stream. StreamReset, /// The response head is not one this can use: no `:status`, a pseudo /// header after an ordinary one, or an uppercase field name. MalformedResponse, /// More interim responses arrived than `max_interim_responses` allows. /// The stream is reset; the connection and its other streams go on. TooManyInterimResponses, /// More streams outstanding than the table or the server allows. TooManyStreams, /// The request cannot be sent as described. InvalidRequest, /// `Request.source` ended before the length the request declared. The /// stream is reset, since what was sent of it is not a whole message. RequestBodyShort, /// `Request.source` failed while the body was being sent -- the reader's /// failure, not the connection's, which is `WriteFailed`. RequestBodyReadFailed, OutOfMemory, }; /// What `begin` hands back: a stream to await. pub const Handle = struct { slot: usize, id: u31, }; const Stream = struct { id: u31 = 0, in_use: bool = false, /// Whether the content coding has already been taken off `body`, so that /// a second `await` for the same stream does not try to undo it twice. decoded: bool = false, /// §5.1's states, reduced to what a client needs: whether the response /// head has arrived, whether the response is finished, and whether the /// peer ended it for us. head_done: bool = false, done: bool = false, reset: ?frame.ErrorCode = null, /// Why this stream's response cannot be used, when it cannot: a stream /// error this client found and reset the stream for. Kept here, and /// reported by this stream's own `await`, because the frame that showed /// it may have been read by an `await` for some other stream. failure: ?Error = null, /// §8.1: how many interim responses have arrived, and who to tell. interims: u8 = 0, interim: ?Request.InterimHook = null, /// §10.1.1 of RFC 9110: content held back for a `100 Continue`, until it /// is sent or the server answers without asking for it. held: ?Held = null, /// A `100 Continue` arrived for `held`. Sent from this stream's own /// `await`, which is not necessarily the one that read the `100`. continued: bool = false, /// The server answered before asking, and `held` was never sent. unsent: bool = false, /// §8.1: the response's field section, decoded. fields: std.ArrayList(Field) = .empty, arena: std.heap.ArenaAllocator = undefined, status: u16 = 0, /// The body as it arrives, bounded by the window this client advertised. body: std.ArrayList(u8) = .empty, /// What `Response.body.reader` reads the gathered body through. Here /// rather than in the response because the response is returned by value /// and what it points at has to stay where it is. body_reader: Io.Reader = undefined, /// §5.2: what may still be sent and received on this stream. send_window: i32 = 0, recv_window: i32 = 0, /// Whether the request was a HEAD, which §8.1 makes the only reason a /// response with a body's fields carries no body. to_head: bool = false, }; /// What `Request.content` or `Request.source` was, kept until a `100 Continue` /// asks for it. Borrowed: it is the caller's, which is why /// `Request.expect_continue` asks that it stay valid until `await`. const Held = struct { content: ?[]const u8, source: ?*Io.Reader, length: u64, }; pub const Connection = struct { io: Io, gpa: Allocator, conn: transport.Connection, config: Config, owns_connection: bool = true, encoder: hpack.Encoder = .{}, decoder: hpack.Decoder, decoder_scratch: []u8, /// The window a coded body is undone through, allocated when the first one /// arrives and kept for the connection's life. decode_window: []u8 = &.{}, /// A field section is accumulated here across CONTINUATION frames, /// because §4.3 forbids anything between them and the decoder cannot be /// fed a fragment. block: std.ArrayList(u8) = .empty, /// What this client advertises, and what the server said. ours: Settings, theirs: Settings = .{}, settings_acked: bool = false, streams: []Stream, /// The stream the last `send` left open, which the next one finishes. sent: ?Handle = null, next_id: u31 = 1, /// Connection-level flow control, §6.9. send_window: i32 = 65535, recv_window: i32, /// §6.8: the last stream the server said it would process, once it has /// said so. goaway: ?u31 = null, /// Allocates the stream table and the HPACK state. Nothing is written; /// that is `handshake`. /// /// `conn` becomes this connection's, and `deinit` closes it unless /// `releaseConnection` has handed it back first. pub fn init( io: Io, gpa: Allocator, conn: transport.Connection, config: Config, ) Allocator.Error!Connection { const scratch = try gpa.alloc(u8, 4096); errdefer gpa.free(scratch); const streams = try gpa.alloc(Stream, config.max_concurrent_streams); errdefer gpa.free(streams); for (streams) |*s| s.* = .{}; return .{ .io = io, .gpa = gpa, .conn = conn, .config = config, .decoder = .init(config.header_table_size, scratch, .{ .max_header_list_size = config.max_header_list_size, }), .decoder_scratch = scratch, .ours = .{ .header_table_size = config.header_table_size, // §8.4: a client that will not accept pushes says so, and a // PUSH_PROMISE after that is a connection error. Saying it is // cheaper than implementing a cache nobody asked for. .enable_push = false, .initial_window_size = config.stream_receive_window, .max_frame_size = config.max_frame_size, .max_header_list_size = config.max_header_list_size, }, .streams = streams, // §6.9.2: "the connection flow-control window is also 65,535 // octets" to begin with, and SETTINGS_INITIAL_WINDOW_SIZE does // not change it -- that setting is about *stream* windows. The // only way to raise the connection's is a WINDOW_UPDATE on // stream 0, which `handshake` sends. .recv_window = 65535, }; } test init { var server: transport.memory.Connection = try .init(testing.allocator, hello_server, .{}); defer server.deinit(); var c: Connection = try .init(testing.io, testing.allocator, server.connection(), .{}); defer c.deinit(); // Nothing has gone on the wire yet. try testing.expectEqual(@as(usize, 0), server.written().len); } /// Frees every stream, including any never `finish`ed, and everything a /// `Response` from `await` pointed into; then closes the connection, /// unless `releaseConnection` was called. pub fn deinit(c: *Connection) void { for (c.streams) |*s| if (s.in_use) c.release(s); c.gpa.free(c.streams); c.block.deinit(c.gpa); c.decoder.deinit(c.gpa); c.gpa.free(c.decoder_scratch); c.gpa.free(c.decode_window); if (c.owns_connection) c.conn.close(c.io, c.gpa); c.* = undefined; } test deinit { var server: transport.memory.Connection = try .init(testing.allocator, hello_server, .{}); defer server.deinit(); var c: Connection = try .init(testing.io, testing.allocator, server.connection(), .{}); c.deinit(); } /// Hands the connection back, so that `deinit` will not close it. The /// caller is then the one to close it. pub fn releaseConnection(c: *Connection) transport.Connection { c.owns_connection = false; return c.conn; } test releaseConnection { var server: transport.memory.Connection = try .init(testing.allocator, hello_server, .{}); defer server.deinit(); var c: Connection = try .init(testing.io, testing.allocator, server.connection(), .{}); const conn = c.releaseConnection(); c.deinit(); // Still open, and still usable by whoever has it now. try conn.output.writeAll("still mine"); try conn.output.flush(); try testing.expectEqualStrings("still mine", server.written()); } /// §3.4: sends the preface and this client's SETTINGS, and reads the /// server's. /// /// Separate from `init` because it writes, and a caller that wants to /// know whether the server speaks HTTP/2 at all wants that answer before /// it builds a request. pub fn handshake(c: *Connection) Error!void { const out = c.conn.output; out.writeAll(preface) catch return error.WriteFailed; try c.writeSettings(); out.flush() catch return error.WriteFailed; // The server's SETTINGS is required to be the first frame it sends, // so anything else here is a server that is not speaking HTTP/2. const header = frame.Header.read(c.conn.input) catch return error.NoResponse; if (header.type != .settings) return c.fail(.protocol_error, "first frame was not SETTINGS"); try c.onSettings(header); // And raise the connection window, which nothing else can. Without // this a peer stops after 65535 octets across all streams and waits // for credit -- and a client whose own accounting said it had more // waits with it, which is a deadlock neither end is at fault for. if (c.config.connection_receive_window > 65535) { const increment: u31 = c.config.connection_receive_window - 65535; frame.writeWindowUpdate(c.conn.output, 0, increment) catch return error.WriteFailed; c.recv_window += @intCast(increment); c.conn.output.flush() catch return error.WriteFailed; } } test handshake { var server: transport.memory.Connection = try .init(testing.allocator, hello_server, .{}); defer server.deinit(); var c: Connection = try .init(testing.io, testing.allocator, server.connection(), .{}); defer c.deinit(); try c.handshake(); try testing.expect(std.mem.startsWith(u8, server.written(), preface)); // The server's SETTINGS, nine octets with no payload, and no more. try testing.expectEqual(@as(usize, 9), server.consumed()); } fn writeSettings(c: *Connection) Error!void { var payload: [64]u8 = undefined; var w: Io.Writer = .fixed(&payload); c.ours.writePayload(&w, .{}) catch return error.WriteFailed; const bytes = w.buffered(); const h: frame.Header = .{ .length = @intCast(bytes.len), .type = .settings, .flags = 0, .stream_id = 0, }; h.writeTo(c.conn.output) catch return error.WriteFailed; c.conn.output.writeAll(bytes) catch return error.WriteFailed; } /// Opens a stream and sends the request on it. /// /// Returns as soon as the request is written, so several may be begun /// before any is awaited and they are then genuinely in flight together. /// Nothing is read unless flow control stops the content part way: then /// frames are read, and filed for whichever stream they belong to, until /// the server opens the window or ends the stream. With /// `Request.expect_continue` only the head is sent here, and the content /// waits for this stream's `await`. /// /// The handle stays valid until `finish`, which the caller owes it /// whether or not `await` succeeds. pub fn begin(c: *Connection, request: Request) Error!Handle { if (c.goaway != null) return error.StreamRefused; // Before a slot is taken and an identifier spent: §5.1.1 only ever // counts up, so an identifier burnt on a request that never went out // is one the peer will see as a gap and treat as an idle stream // implicitly closed. try request.validate(); if (request.host.len == 0) return error.InvalidRequest; const slot = c.freeSlot() orelse return error.TooManyStreams; const s = &c.streams[slot]; const id = c.next_id; // §5.1.1: "Streams initiated by a client MUST use odd-numbered stream // identifiers." c.next_id += 2; s.* = .{ .id = id, .in_use = true, .arena = .init(c.gpa), .send_window = c.theirs.initial_window_size, .recv_window = @intCast(c.ours.initial_window_size), .to_head = request.method.eql(protocol.Method.head), .interim = request.interim, }; errdefer c.release(s); try c.writeRequest(s, request); return .{ .slot = slot, .id = id }; } test begin { var server: transport.memory.Connection = try .init(testing.allocator, hello_server, .{}); defer server.deinit(); var c: Connection = try .init(testing.io, testing.allocator, server.connection(), .{}); defer c.deinit(); try c.handshake(); const one = try c.begin(.{ .host = "example.com", .target = "/a" }); defer c.finish(one); const two = try c.begin(.{ .host = "example.com", .target = "/b" }); defer c.finish(two); // §5.1.1: a client's streams are odd and only ever count up. try testing.expectEqual(@as(u31, 1), one.id); try testing.expectEqual(@as(u31, 3), two.id); } /// Reads frames until this stream's response is complete. /// /// Frames for other streams are filed as they arrive, so awaiting one /// request does not stall another. A `100 Continue` for content `begin` /// held back sends it from here; a final response that came without one /// ends this end's half of the stream with RST_STREAM(NO_ERROR) instead, /// and is reported with `Response.content_sent` false. /// /// What is returned points into the stream's memory and is valid until /// `finish`. The whole body has been gathered by the time this returns, /// and can be read through `Response.body.reader` as over any other /// version or taken as a slice from `body`. Awaiting the same handle again /// returns the same response, with its reader back at the start. pub fn await(c: *Connection, handle: Handle) Error!Response { const s = &c.streams[handle.slot]; if (!s.in_use or s.id != handle.id) return error.NoResponse; while (!s.done) { if (s.failure) |err| return err; if (s.reset) |code| { return if (code == .refused_stream) error.StreamRefused else error.StreamReset; } if (s.continued) { s.continued = false; try c.sendHeld(s); continue; } try c.pump(); } if (s.failure) |err| return err; if (s.reset) |code| { return if (code == .refused_stream) error.StreamRefused else error.StreamReset; } if (s.held != null) { // §10.1.1 of RFC 9110: the server answered without asking for // the content, and the response is complete. §8.1 of RFC 9113: // what is left of this end's half of the stream is closed with // RST_STREAM of NO_ERROR rather than with content nobody reads. s.held = null; s.unsent = true; frame.writeRstStream(c.conn.output, s.id, .no_error) catch return error.WriteFailed; c.conn.output.flush() catch return error.WriteFailed; } // §8.1: "An HTTP message (request or response) consists of... a // HEADERS frame containing the header section". A stream that ended // without one carries no message, and answering with the zero that // `status` was initialised to would be handing back a response that // never arrived. Found by fuzzing, on a stream ended by a DATA frame // with no field section before it. if (!s.head_done) return error.MalformedResponse; // §8.4: the representation, once all of it is here. A multiplexed body // has no single reader to wrap -- its octets arrive interleaved with // every other stream's -- so the coding comes off the gathered whole. if (c.config.accept_encodings.len > 0 and s.body.items.len > 0 and !s.decoded) { const headers: protocol.Headers = .{ .fields = s.fields }; switch (coding.applied(headers.get("content-encoding"))) { .identity, .unsupported => {}, .one => |applied| for (c.config.accept_encodings) |want| { if (want != applied) continue; const need = coding.decodeBufferLen(applied); if (c.decode_window.len < need) { c.gpa.free(c.decode_window); c.decode_window = c.gpa.alloc(u8, need) catch { c.decode_window = &.{}; return error.OutOfMemory; }; } const plain = coding.undo( c.gpa, s.body.items, applied, c.decode_window, c.config.max_body_len, ) catch |err| switch (err) { error.OutOfMemory => return error.OutOfMemory, // A body this end asked for and cannot read is not a // body to hand over as if it were the representation. error.Malformed, error.TooLarge, error.Unsupported => return error.BadContentEncoding, }; s.body.clearRetainingCapacity(); s.body.appendSlice(c.gpa, plain) catch { c.gpa.free(plain); return error.OutOfMemory; }; c.gpa.free(plain); // Once, however many times `await` is called for this // stream. s.decoded = true; break; }, } } s.body_reader = .fixed(s.body.items); return .{ .status = s.status, .version = .http_2, // §8.3.1 removed it: "HTTP/2 does not define a way to carry the // reason phrase", so there is nothing to carry. .reason = "", .headers = .{ .fields = s.fields }, .body = .{ .reader = &s.body_reader, .length = s.body.items.len, .present = s.body.items.len > 0, }, .content_sent = !s.unsent, }; } test await { var server: transport.memory.Connection = try .init(testing.allocator, hello_server, .{}); defer server.deinit(); var c: Connection = try .init(testing.io, testing.allocator, server.connection(), .{}); defer c.deinit(); try c.handshake(); const handle = try c.begin(.{ .host = "example.com" }); defer c.finish(handle); const res = try c.await(handle); try testing.expectEqual(@as(u16, 200), res.status); try testing.expectEqual(protocol.Version.http_2, res.version); try testing.expectEqual(@as(?u64, 5), res.body.length); // Read the way a response over any version is read. const body_read = try res.body.readAlloc(testing.allocator, 64); defer testing.allocator.free(body_read); try testing.expectEqualStrings("hello", body_read); } /// The content `writeRequest` held back, now that a `100 Continue` has /// asked for it. fn sendHeld(c: *Connection, s: *Stream) Error!void { const held = s.held orelse return; s.held = null; if (held.content) |content| { try c.writeData(s, content); } else if (held.source) |source| { try c.writeDataFrom(s, source, held.length); } c.conn.output.flush() catch return error.WriteFailed; } /// The body of a completed stream, with any content coding `await` undid /// already taken off, which lives until `finish`. Empty for a handle that /// has already been finished. pub fn body(c: *Connection, handle: Handle) []const u8 { const s = &c.streams[handle.slot]; if (!s.in_use or s.id != handle.id) return &.{}; return s.body.items; } test body { var server: transport.memory.Connection = try .init(testing.allocator, hello_server, .{}); defer server.deinit(); var c: Connection = try .init(testing.io, testing.allocator, server.connection(), .{}); defer c.deinit(); try c.handshake(); const handle = try c.begin(.{ .host = "example.com" }); defer c.finish(handle); _ = try c.await(handle); try testing.expectEqualStrings("hello", c.body(handle)); } /// Gives the stream's slot back. Everything `await` returned for it /// points into memory this frees. A handle that was already finished is /// ignored. pub fn finish(c: *Connection, handle: Handle) void { const s = &c.streams[handle.slot]; if (!s.in_use or s.id != handle.id) return; c.release(s); } test finish { var server: transport.memory.Connection = try .init(testing.allocator, hello_server, .{}); defer server.deinit(); var c: Connection = try .init(testing.io, testing.allocator, server.connection(), .{}); defer c.deinit(); try c.handshake(); const handle = try c.begin(.{ .host = "example.com" }); _ = try c.await(handle); c.finish(handle); // The handle names nothing now. try testing.expectEqualStrings("", c.body(handle)); try testing.expectError(error.NoResponse, c.await(handle)); } /// One request, begun and awaited, for a caller that makes one at a time. /// /// The same bargain as the HTTP/1.1 client's `send`: the response, its /// fields and its body reader are valid until the next `send` or `deinit`, /// and the next `send` finishes the stream this one leaves open. A caller /// that wants several requests in flight at once uses `begin`, `await` and /// `finish`, which `send` leaves alone. pub fn send(c: *Connection, request: Request) Error!Response { if (c.sent) |previous| { c.finish(previous); c.sent = null; } const handle = try c.begin(request); const res = c.await(handle) catch |err| { c.finish(handle); return err; }; c.sent = handle; return res; } test send { var server: transport.memory.Connection = try .init(testing.allocator, hello_server, .{}); defer server.deinit(); var c: Connection = try .init(testing.io, testing.allocator, server.connection(), .{}); defer c.deinit(); try c.handshake(); const res = try c.send(.{ .host = "example.com" }); try testing.expectEqual(@as(u16, 200), res.status); } test "send gives its stream back at the next send" { // Two exchanges, on streams 1 and 3, through a client that will hold // only one stream open at a time. const two = hello_server ++ "\x00\x00\x01\x01\x04\x00\x00\x00\x03" ++ "\x88" ++ "\x00\x00\x02\x00\x01\x00\x00\x00\x03" ++ "ok"; var server: transport.memory.Connection = try .init(testing.allocator, two, .{}); defer server.deinit(); var c: Connection = try .init(testing.io, testing.allocator, server.connection(), .{ .max_concurrent_streams = 1, }); defer c.deinit(); try c.handshake(); _ = try c.send(.{ .host = "example.com" }); const second = try c.send(.{ .host = "example.com" }); const body_read = try second.body.readAlloc(testing.allocator, 64); defer testing.allocator.free(body_read); try testing.expectEqualStrings("ok", body_read); } fn release(c: *Connection, s: *Stream) void { // `fields` is grown by the decoder with the *arena*, not the general // allocator -- see `hpack.Decoder.emit`, which appends there so that // a name taken from the dynamic table has the same lifetime as one // copied out of the block. So the arena frees the list along with // everything in it, and freeing it here would be freeing memory the // general allocator never handed out. s.body.deinit(c.gpa); s.arena.deinit(); s.* = .{}; } fn freeSlot(c: *Connection) ?usize { for (c.streams, 0..) |*s, i| { if (!s.in_use) return i; } return null; } fn find(c: *Connection, id: u31) ?*Stream { for (c.streams) |*s| { if (s.in_use and s.id == id) return s; } return null; } // -- sending ------------------------------------------------------------ fn writeRequest(c: *Connection, s: *Stream, request: Request) Error!void { // §8.3.1: the pseudo-headers come first and in no particular order // among themselves, but all before any ordinary field. `:authority` // rather than a `Host` field, which §8.3.1 says a client "MUST NOT" // send where an authority is available. var block: std.ArrayList(u8) = .empty; defer block.deinit(c.gpa); var w: Io.Writer.Allocating = .fromArrayList(c.gpa, &block); defer block = w.toArrayList(); const scheme = if (c.conn.info.secure) "https" else "http"; c.encoder.field(&w.writer, ":method", request.method.name) catch return error.OutOfMemory; c.encoder.field(&w.writer, ":scheme", scheme) catch return error.OutOfMemory; c.encoder.field(&w.writer, ":authority", request.host) catch return error.OutOfMemory; c.encoder.field(&w.writer, ":path", request.target) catch return error.OutOfMemory; // §8.1: the content is delimited by the stream rather than by this // field, so it is optional -- and sent anyway when the length is // known, for the reasons `Request.declaredContentLength` gives. The // HTTP/3 driver asks the same question of the same function. var length_text: [20]u8 = undefined; if (try request.declaredContentLength()) |length| { const text = std.fmt.bufPrint(&length_text, "{d}", .{length}) catch unreachable; c.encoder.field(&w.writer, "content-length", text) catch return error.OutOfMemory; } // §12.5.3 of RFC 9110, in the same lowercase §8.2.1 wants everything // else in. The order is the preference; no weights, for the reason // the HTTP/1.x driver gives. if (c.config.accept_encodings.len > 0) { var names: [64]u8 = undefined; var at: usize = 0; for (c.config.accept_encodings, 0..) |want, i| { const text = want.name(); if (i > 0) { if (at + 2 > names.len) return error.InvalidRequest; names[at] = ','; names[at + 1] = ' '; at += 2; } if (at + text.len > names.len) return error.InvalidRequest; @memcpy(names[at..][0..text.len], text); at += text.len; } c.encoder.field(&w.writer, "accept-encoding", names[0..at]) catch return error.OutOfMemory; } for (request.headers.fields.items) |field| { // §8.2.1: "Field names MUST be converted to lowercase", and the // encoder does it on the way out -- the last place that can, // without allocating. if (Request.isReserved(field.name)) return error.InvalidRequest; if (c.config.accept_encodings.len > 0 and protocol.token.eqlIgnoreCase(field.name, "accept-encoding")) { return error.InvalidRequest; } // §8.2.2: connection-specific fields have no meaning here and a // recipient "MUST treat a message containing them as malformed". if (isConnectionSpecific(field.name)) return error.InvalidRequest; c.encoder.field(&w.writer, field.name, field.value) catch return error.OutOfMemory; } w.writer.flush() catch return error.OutOfMemory; // §10.1.1 of RFC 9110: only with content to hold back. const expecting = request.expect_continue and request.hasContent(); if (expecting) { c.encoder.field(&w.writer, "expect", "100-continue") catch return error.OutOfMemory; w.writer.flush() catch return error.OutOfMemory; } const has_body = if (request.content) |content| content.len > 0 else request.source != null and request.body.exact > 0; try c.writeHeadersFrames(s.id, w.writer.buffered(), !has_body); if (expecting) { // The head alone; the content waits for this stream's `await`. s.held = .{ .content = request.content, .source = request.source, .length = if (request.body == .exact) request.body.exact else 0, }; c.conn.output.flush() catch return error.WriteFailed; return; } if (request.content) |content| { if (content.len > 0) try c.writeData(s, content); } else if (request.source) |source| { if (request.body.exact > 0) try c.writeDataFrom(s, source, request.body.exact); } c.conn.output.flush() catch return error.WriteFailed; } /// §6.2 and §4.3: a field section goes out as one HEADERS frame and as /// many CONTINUATION frames as it takes, with nothing in between -- the /// compression state is connection-wide, so an interleaved frame would /// leave the peer's decoder unable to read anything after it. fn writeHeadersFrames(c: *Connection, id: u31, section: []const u8, end_stream: bool) Error!void { const max = c.theirs.max_frame_size; var at: usize = 0; var first = true; while (true) { const take = @min(section.len - at, max); const last = at + take == section.len; const flags: u8 = blk: { var f: u8 = 0; if (last) f |= 0x04; // END_HEADERS if (first and end_stream) f |= 0x01; // END_STREAM break :blk f; }; const h: frame.Header = .{ .length = @intCast(take), .type = if (first) .headers else .continuation, .flags = flags, .stream_id = id, }; h.writeTo(c.conn.output) catch return error.WriteFailed; c.conn.output.writeAll(section[at..][0..take]) catch return error.WriteFailed; at += take; first = false; if (last) break; } } /// §6.9: a DATA frame may be no larger than what both windows allow, and /// what is left over waits for a WINDOW_UPDATE. fn writeData(c: *Connection, s: *Stream, content: []const u8) Error!void { var at: usize = 0; while (at < content.len) { while (c.send_window <= 0 or s.send_window <= 0) { // Nothing may go until the peer says so, and the only thing // that says so is a frame -- so read one. c.conn.output.flush() catch return error.WriteFailed; try c.pump(); if (s.reset != null) return; // §8.1: a server may answer before it has read the request // body, and §5.1 lets it end the stream when it does. What is // left of the body then has nowhere to go -- and a server // that answered without reading will never open the window // again, so waiting for it is waiting for ever. This is not // an error: the exchange is complete, and the response is // what was wanted. if (s.done) return; } const room: usize = @intCast(@min(c.send_window, s.send_window)); const take = @min(@min(content.len - at, room), c.theirs.max_frame_size); const last = at + take == content.len; const h: frame.Header = .{ .length = @intCast(take), .type = .data, .flags = if (last) 0x01 else 0, .stream_id = s.id, }; h.writeTo(c.conn.output) catch return error.WriteFailed; c.conn.output.writeAll(content[at..][0..take]) catch return error.WriteFailed; at += take; c.send_window -= @intCast(take); s.send_window -= @intCast(take); } } /// `writeData` for a body read as it is sent: each frame is filled from /// `source` just before it goes, so no more of the body is ever in memory /// than one frame's worth. /// /// A frame's length is written ahead of its payload, so the payload has to /// be in hand first, which is what `scratch` is for -- read into, then /// written out. Its size caps a frame below the peer's /// `SETTINGS_MAX_FRAME_SIZE` when that is larger, which costs a frame /// header per 16 KiB and nothing else. fn writeDataFrom(c: *Connection, s: *Stream, source: *Io.Reader, length: u64) Error!void { var scratch: [16384]u8 = undefined; var left = length; while (left > 0) { while (c.send_window <= 0 or s.send_window <= 0) { c.conn.output.flush() catch return error.WriteFailed; try c.pump(); if (s.reset != null) return; // Answered before the body was read, as `writeData` explains. // What the reader still holds is the caller's to discard. if (s.done) return; } const room: usize = @intCast(@min(c.send_window, s.send_window)); const want: usize = @intCast(@min(left, @min(room, @min(c.theirs.max_frame_size, scratch.len)))); const got = source.readSliceShort(scratch[0..want]) catch return c.abandon(s, error.RequestBodyReadFailed); // Fewer than asked for is the reader's end, which came before the // length the HEADERS frame declared. Nothing of this piece is sent: // the stream is reset rather than ended, so the peer is told the // message is not whole instead of being handed a shorter one. if (got < want) return c.abandon(s, error.RequestBodyShort); left -= got; const h: frame.Header = .{ .length = @intCast(got), .type = .data, .flags = if (left == 0) 0x01 else 0, .stream_id = s.id, }; h.writeTo(c.conn.output) catch return error.WriteFailed; c.conn.output.writeAll(scratch[0..got]) catch return error.WriteFailed; c.send_window -= @intCast(got); s.send_window -= @intCast(got); } } /// §5.4.2: ends a stream this end can no longer complete with /// RST_STREAM, so that the peer stops waiting for the rest of it, and /// returns `err` for the caller. fn abandon(c: *Connection, s: *Stream, err: Error) Error { // CANCEL, §7: "the stream is no longer needed" -- this end gave up on // it, which is not a protocol fault on either side. frame.writeRstStream(c.conn.output, s.id, .cancel) catch return error.WriteFailed; c.conn.output.flush() catch return error.WriteFailed; s.reset = .cancel; s.done = true; return err; } // -- receiving ---------------------------------------------------------- /// Reads one frame and files it. fn pump(c: *Connection) Error!void { const header = frame.Header.read(c.conn.input) catch |err| switch (err) { error.EndOfStream => return c.endAll(), error.ReadFailed => return error.ReadFailed, }; // §4.2 and §4.1, applied before the payload is read: a frame larger // than was advertised is a connection error, and reading it first // would be doing what it asked. if (frame.checkHeader(header, c.ours.max_frame_size)) |fault| { return c.fail(fault.code, "frame header"); } switch (header.type) { .settings => try c.onSettings(header), .headers, .continuation => try c.onHeaders(header), .data => try c.onData(header), .window_update => try c.onWindowUpdate(header), .rst_stream => try c.onRstStream(header), .ping => try c.onPing(header), .goaway => try c.onGoaway(header), .push_promise => return c.fail(.protocol_error, "push after SETTINGS_ENABLE_PUSH 0"), // §4.1: "Implementations MUST ignore and discard any frame that // has a type that is unknown", and §6.3's PRIORITY is deprecated // by §5.3.2 with nothing to do in its place. else => try c.discard(header.length), } } fn discard(c: *Connection, length: u24) Error!void { c.conn.input.discardAll(length) catch return error.ReadFailed; } /// Reads a payload into `list`, in whatever pieces the connection /// delivers it. /// /// Not `Io.Reader.take`, which would need the whole frame in the /// transport's buffer at once -- and §4.2 puts the floor for /// SETTINGS_MAX_FRAME_SIZE at 16384, which is larger than the buffer a /// connection is given by default. The server streams payloads for the /// same reason; a client that took them whole would work against a peer /// sending small frames and fail against one sending large ones, which /// is the worst way for this to be wrong. fn appendPayload(c: *Connection, list: *std.ArrayList(u8), length: u24) Error!void { const at = list.items.len; if (at + length > c.config.max_body_len) return error.BodyTooLong; list.resize(c.gpa, at + length) catch return error.OutOfMemory; c.conn.input.readSliceAll(list.items[at..]) catch return error.ReadFailed; } /// A payload small enough to be read into a fixed array, which is every /// frame this needs whole: none of them is larger than eight octets. fn fixedPayload(c: *Connection, comptime n: usize) Error![n]u8 { const bytes = c.conn.input.takeArray(n) catch return error.ReadFailed; return bytes.*; } fn onSettings(c: *Connection, header: frame.Header) Error!void { if (header.flags & 0x01 != 0) { // An acknowledgement of ours, which carries no payload. c.settings_acked = true; return; } // §6.5: "A SETTINGS frame with a length other than a multiple of 6 // octets MUST be treated as a connection error." if (header.length % 6 != 0) return c.fail(.frame_size_error, "SETTINGS length"); const before = c.theirs.initial_window_size; var left = header.length; while (left > 0) : (left -= 6) { const entry_bytes = try c.fixedPayload(6); var it = Settings.iterate(&entry_bytes); while (it.next()) |entry| { // §6.5.2 gives the code: an initial window past 2^31-1 is a // FLOW_CONTROL_ERROR, anything else out of range a // PROTOCOL_ERROR. c.theirs.apply(entry) catch |err| return c.fail(Settings.errorCode(err), "bad setting"); if (entry.id == .header_table_size) c.encoder.setPeerTableSize(entry.value); } } // §6.9.2: a change to SETTINGS_INITIAL_WINDOW_SIZE adjusts every open // stream's window by the difference, and may drive one negative -- // which is legal and is why the window is signed. const delta = @as(i64, c.theirs.initial_window_size) - @as(i64, before); if (delta != 0) { for (c.streams) |*s| { if (!s.in_use) continue; const updated = @as(i64, s.send_window) + delta; // "An endpoint MUST treat a change to // SETTINGS_INITIAL_WINDOW_SIZE that causes any flow-control // window to exceed the maximum size as a connection error of // type FLOW_CONTROL_ERROR." Narrowed only once it is known to // fit, or a window the peer had grown with WINDOW_UPDATE was a // panic here. if (updated > Settings.max_window_size) { return c.fail(.flow_control_error, "initial window overflow"); } s.send_window = @intCast(updated); } } frame.writeSettingsAck(c.conn.output) catch return error.WriteFailed; c.conn.output.flush() catch return error.WriteFailed; } fn onPing(c: *Connection, header: frame.Header) Error!void { if (header.length != 8) return c.fail(.frame_size_error, "PING length"); const payload = try c.fixedPayload(8); // §6.7: an ACK is not answered; anything else is answered with its // own payload echoed back. if (header.flags & 0x01 != 0) return; frame.writePingAck(c.conn.output, &payload) catch return error.WriteFailed; c.conn.output.flush() catch return error.WriteFailed; } fn onGoaway(c: *Connection, header: frame.Header) Error!void { if (header.length < 8) return c.fail(.frame_size_error, "GOAWAY"); const payload = try c.fixedPayload(8); // §6.8's debug data is "for diagnostic purposes only" and carries no // semantics, so it is discarded rather than kept. try c.discard(header.length - 8); const away = frame.parseGoaway(&payload) catch return c.fail(.frame_size_error, "GOAWAY"); c.goaway = away.last_stream_id; // §6.8: everything above the last identifier was not processed, and // saying so is what lets a caller retry it somewhere else. for (c.streams) |*s| { if (!s.in_use or s.done) continue; if (s.id > away.last_stream_id) { s.reset = .refused_stream; s.done = true; } } } fn onRstStream(c: *Connection, header: frame.Header) Error!void { if (header.length != 4) return c.fail(.frame_size_error, "RST_STREAM"); const payload = try c.fixedPayload(4); const code = frame.parseRstStream(&payload) catch return c.fail(.frame_size_error, "RST_STREAM"); const s = c.find(header.stream_id) orelse return; s.reset = code; s.done = true; } fn onWindowUpdate(c: *Connection, header: frame.Header) Error!void { if (header.length != 4) return c.fail(.frame_size_error, "WINDOW_UPDATE"); const payload = try c.fixedPayload(4); const increment = frame.parseWindowUpdate(&payload) catch return c.fail(.frame_size_error, "WINDOW_UPDATE"); // §6.9: "A receiver MUST treat the receipt of a WINDOW_UPDATE frame // with a flow-control window increment of 0 as a stream error." if (increment == 0) return c.fail(.protocol_error, "zero WINDOW_UPDATE"); if (header.stream_id == 0) { const next = @as(i64, c.send_window) + increment; if (next > Settings.max_window_size) return c.fail(.flow_control_error, "window overflow"); c.send_window = @intCast(next); return; } const s = c.find(header.stream_id) orelse return; const next = @as(i64, s.send_window) + increment; if (next > Settings.max_window_size) return c.fail(.flow_control_error, "window overflow"); s.send_window = @intCast(next); } /// §6.2 and §6.10: a field section arrives as HEADERS and then /// CONTINUATION frames with nothing in between, so the whole section is /// gathered before any of it is decoded. fn onHeaders(c: *Connection, first: frame.Header) Error!void { var header = first; c.block.clearRetainingCapacity(); while (true) { // §6.2: HEADERS may be padded and may carry the deprecated // priority fields, and both come off the front before the // fragment -- read rather than sliced, since the payload is // never in hand whole. var left = header.length; var pad: u8 = 0; if (header.type == .headers) { if (header.flags & 0x08 != 0) { if (left < 1) return c.fail(.protocol_error, "pad length"); pad = (try c.fixedPayload(1))[0]; left -= 1; } if (header.flags & 0x20 != 0) { if (left < 5) return c.fail(.protocol_error, "priority fields"); _ = try c.fixedPayload(5); left -= 5; } if (pad > left) return c.fail(.protocol_error, "padding exceeds frame"); left -= pad; } try c.appendPayload(&c.block, left); try c.discard(pad); if (header.flags & 0x04 != 0) break; // END_HEADERS // §6.10: "A receiver MUST treat the receipt of any other type of // frame or a frame on a different stream as a connection error." // The compression context is shared, so a section interrupted // once leaves every later section unreadable. const next = frame.Header.read(c.conn.input) catch return error.ReadFailed; if (next.type != .continuation or next.stream_id != header.stream_id) { return c.fail(.protocol_error, "interrupted field section"); } if (frame.checkHeader(next, c.ours.max_frame_size)) |fault| { return c.fail(fault.code, "continuation header"); } header = next; } const s = c.find(first.stream_id) orelse { // A section for a stream this client has forgotten still has to // be decoded, because the decoder's table must stay in step. var scratch: std.ArrayList(Field) = .empty; var arena: std.heap.ArenaAllocator = .init(c.gpa); defer arena.deinit(); c.decoder.decode(c.gpa, arena.allocator(), c.block.items, &scratch) catch |err| { if (hpack.Decoder.isCompressionError(err)) { return c.fail(.compression_error, "hpack"); } return error.OutOfMemory; }; return; }; const end_stream = first.flags & 0x01 != 0; // §8.1: a response is zero or more interim responses, then the final // one, then at most one trailer section -- each its own HEADERS -- // and which of the three this is depends on what came before it. if (s.done or s.head_done) { // The trailer section, which is decoded only to keep the // decoder's table in step and then dropped, as the other two // drivers drop theirs: a caller has no way to ask for it. var scratch: std.ArrayList(Field) = .empty; var arena: std.heap.ArenaAllocator = .init(c.gpa); defer arena.deinit(); c.decoder.decode(c.gpa, arena.allocator(), c.block.items, &scratch) catch |err| { if (hpack.Decoder.isCompressionError(err)) return c.fail(.compression_error, "hpack"); return error.OutOfMemory; }; if (s.failure != null) return; // §5.1: nothing may follow END_STREAM, and §8.1 makes the trailer // section "the last frame in the sequence", which "bears an // END_STREAM flag". if (s.done) return c.streamFail(s, error.MalformedResponse, .stream_closed); if (!end_stream) return c.streamFail(s, error.MalformedResponse, .protocol_error); s.done = true; return; } c.decoder.decode(c.gpa, s.arena.allocator(), c.block.items, &s.fields) catch |err| { if (hpack.Decoder.isCompressionError(err)) return c.fail(.compression_error, "hpack"); return error.OutOfMemory; }; try c.readStatus(s); if (s.failure != null) return; if (s.status >= 100 and s.status <= 199) { // §8.6: "HTTP/2 removes support for the 101 (Switching // Protocols) informational status code", and §8.1: "a HEADERS // frame with the END_STREAM flag set that carries an // informational status code is malformed". if (s.status == 101 or end_stream) return c.streamFail(s, error.MalformedResponse, .protocol_error); s.interims += 1; if (s.interims > c.config.max_interim_responses) { return c.streamFail(s, error.TooManyInterimResponses, .cancel); } if (s.interim) |hook| { const borrowed: protocol.Headers = .{ .fields = s.fields }; hook.notify(.{ .status = s.status, .version = .http_2, .headers = &borrowed }); } // §10.1.1 of RFC 9110: what held content was waiting for. if (s.status == 100 and s.held != null) s.continued = true; // Gone once told: the arena holds nothing yet but this section, // so it starts again empty for the next one, and a server sending // interim responses costs this client one of them at a time. _ = s.arena.reset(.retain_capacity); s.fields = .empty; s.status = 0; return; } s.head_done = true; if (end_stream) s.done = true; } /// §8.3.2: a response's control data is a single `:status` pseudo-header, /// before every ordinary field. fn readStatus(c: *Connection, s: *Stream) Error!void { var seen_ordinary = false; var status: ?u16 = null; for (s.fields.items) |field| { if (field.name.len > 0 and field.name[0] == ':') { // §8.3: "Pseudo-header fields MUST appear in a field block // before all regular field lines." if (seen_ordinary) return c.streamFail(s, error.MalformedResponse, .protocol_error); if (!std.mem.eql(u8, field.name, ":status")) return c.streamFail(s, error.MalformedResponse, .protocol_error); if (status != null) return c.streamFail(s, error.MalformedResponse, .protocol_error); if (field.value.len != 3) return c.streamFail(s, error.MalformedResponse, .protocol_error); var n: u16 = 0; for (field.value) |ch| { if (ch < '0' or ch > '9') return c.streamFail(s, error.MalformedResponse, .protocol_error); n = n * 10 + (ch - '0'); } // §15 of RFC 9110: three digits, of which the first is the // class -- and there is no class below 1. if (n < 100) return c.streamFail(s, error.MalformedResponse, .protocol_error); status = n; continue; } seen_ordinary = true; // §8.2.1: "A field name MUST NOT contain characters in the // ranges 0x00-0x20, 0x41-0x5a, or 0x7f-0xff" -- which is to say // an uppercase letter makes a message malformed. for (field.name) |ch| { if (ch >= 'A' and ch <= 'Z') return c.streamFail(s, error.MalformedResponse, .protocol_error); } // §8.2.2: connection-specific fields have no meaning in HTTP/2. if (isConnectionSpecific(field.name)) return c.streamFail(s, error.MalformedResponse, .protocol_error); } s.status = status orelse return c.streamFail(s, error.MalformedResponse, .protocol_error); // The pseudo-header is control data rather than a field, so it does // not stay in the list -- the same treatment `field.request` gives // `:method` and the rest on the server side. A caller that found // `:status` among the headers would be seeing the wire rather than // the message, and `Headers.append` would refuse to put it back: // `token.isToken` excludes the colon. var kept: usize = 0; for (s.fields.items) |field| { if (field.name.len > 0 and field.name[0] == ':') continue; s.fields.items[kept] = field; kept += 1; } s.fields.shrinkRetainingCapacity(kept); } /// §8.1.1: a malformed message is a *stream* error, so the connection and /// every other request on it survive. /// /// So the stream is reset and marked with why, and the error is this /// stream's `await` to report -- not returned from here, which would hand /// it to whichever `await` is reading, for whatever stream that is. fn streamFail(c: *Connection, s: *Stream, why: Error, code: frame.ErrorCode) Error!void { frame.writeRstStream(c.conn.output, s.id, code) catch return error.WriteFailed; c.conn.output.flush() catch return error.WriteFailed; s.reset = code; s.done = true; s.failure = why; } fn onData(c: *Connection, header: frame.Header) Error!void { const received: u31 = header.length; var left = header.length; var pad: u8 = 0; if (header.flags & 0x08 != 0) { if (left < 1) return c.fail(.protocol_error, "pad length"); pad = (try c.fixedPayload(1))[0]; left -= 1; if (pad > left) return c.fail(.protocol_error, "padding exceeds frame"); left -= pad; } // §6.9.1: the whole frame counts against the window, padding // included -- what was spent on the wire is what is replaced. c.recv_window -= received; if (c.recv_window < 0) return c.fail(.flow_control_error, "connection window"); const s = c.find(header.stream_id); if (s) |stream| { stream.recv_window -= received; if (stream.recv_window < 0) return c.fail(.flow_control_error, "stream window"); if (stream.failure != null) { try c.discard(left + pad); return c.replenish(s); } // §8.1: content comes after the final response's head and before // the end of the stream. Before it is in the middle of the // interim responses, where there is no message for it to belong // to; after the end is §5.1's half-closed stream. if (!stream.head_done or stream.done) { try c.discard(left + pad); try c.streamFail( stream, error.MalformedResponse, if (stream.done) .stream_closed else .protocol_error, ); return c.replenish(s); } try c.appendPayload(&stream.body, left); try c.discard(pad); if (header.flags & 0x01 != 0) stream.done = true; } else { try c.discard(left + pad); } // Replenished as it is taken, because this client has already put the // octets somewhere: the buffer is the window, so what has been // buffered is what may be asked for again. try c.replenish(s); } fn replenish(c: *Connection, s: ?*Stream) Error!void { const half = c.config.connection_receive_window / 2; if (c.recv_window <= half) { const increment: u31 = @intCast(@as(i64, c.config.connection_receive_window) - c.recv_window); if (increment > 0) { frame.writeWindowUpdate(c.conn.output, 0, increment) catch return error.WriteFailed; c.recv_window += @intCast(increment); } } if (s) |stream| { if (stream.done) return; const stream_half = c.config.stream_receive_window / 2; if (stream.recv_window <= stream_half) { const increment: u31 = @intCast(@as(i64, c.config.stream_receive_window) - stream.recv_window); if (increment > 0) { frame.writeWindowUpdate(c.conn.output, stream.id, increment) catch return error.WriteFailed; stream.recv_window += @intCast(increment); } } } c.conn.output.flush() catch return error.WriteFailed; } /// The connection ended. Everything still waiting was not answered. fn endAll(c: *Connection) Error!void { var any = false; for (c.streams) |*s| { if (!s.in_use or s.done) continue; any = true; s.done = true; s.reset = .refused_stream; } if (!any) return error.NoResponse; } /// §5.4.1: a connection error is a GOAWAY and then no more frames. fn fail(c: *Connection, code: frame.ErrorCode, why: []const u8) Error { frame.writeGoaway(c.conn.output, c.lastStream(), code, why) catch {}; c.conn.output.flush() catch {}; for (c.streams) |*s| { if (!s.in_use) continue; s.done = true; if (s.reset == null) s.reset = code; } return switch (code) { .compression_error => error.CompressionError, else => error.ProtocolError, }; } fn lastStream(c: *const Connection) u31 { var highest: u31 = 0; for (c.streams) |*s| { if (s.in_use and s.id > highest) highest = s.id; } return highest; } }; /// §8.2.2: the fields that describe an HTTP/1.1 connection and have no /// meaning here. `TE` is the one exception and only with the value /// `trailers`, which this does not send. fn isConnectionSpecific(name: []const u8) bool { const names = [_][]const u8{ "connection", "proxy-connection", "keep-alive", "transfer-encoding", "upgrade", }; for (names) |one| { if (token.eqlIgnoreCase(name, one)) return true; } return false; } test { std.testing.refAllDecls(@This()); } const testing = std.testing; /// A server's half of one exchange, for the examples on `Connection`: its /// SETTINGS, then a `200` on stream 1 with the body `hello`. const hello_server: []const u8 = // SETTINGS, empty. "\x00\x00\x00\x04\x00\x00\x00\x00\x00" ++ // HEADERS on stream 1, END_HEADERS: `:status: 200`, static index 8. "\x00\x00\x01\x01\x04\x00\x00\x00\x01" ++ "\x88" ++ // DATA on stream 1, END_STREAM. "\x00\x00\x05\x00\x01\x00\x00\x00\x01" ++ "hello"; test "RFC 9113 6.9.2: SETTINGS_INITIAL_WINDOW_SIZE pushing a stream window past 2^31-1 is a FLOW_CONTROL_ERROR, not a panic" { const script = "\x00\x00\x00\x04\x00\x00\x00\x00\x00" ++ // WINDOW_UPDATE stream 1, +(2^31-1 - 65535): window now exactly 2^31-1. "\x00\x00\x04\x08\x00\x00\x00\x00\x01" ++ "\x7f\xff\x00\x00" ++ // SETTINGS_INITIAL_WINDOW_SIZE = 65536: +1 to every open stream. "\x00\x00\x06\x04\x00\x00\x00\x00\x00" ++ "\x00\x04\x00\x01\x00\x00"; var server: transport.memory.Connection = try .init(testing.allocator, script, .{}); defer server.deinit(); var c: Connection = try .init(testing.io, testing.allocator, server.connection(), .{}); defer c.deinit(); try c.handshake(); const handle = try c.begin(.{ .host = "example.com" }); defer c.finish(handle); // §6.9.2: a connection error of type FLOW_CONTROL_ERROR. try testing.expectError(error.ProtocolError, c.await(handle)); } test "RFC 9113 6.5.2: SETTINGS_INITIAL_WINDOW_SIZE above 2^31-1 is answered with FLOW_CONTROL_ERROR" { // SETTINGS_INITIAL_WINDOW_SIZE = 2^31. const script = "\x00\x00\x06\x04\x00\x00\x00\x00\x00" ++ "\x00\x04\x80\x00\x00\x00"; var server: transport.memory.Connection = try .init(testing.allocator, script, .{}); defer server.deinit(); var c: Connection = try .init(testing.io, testing.allocator, server.connection(), .{}); defer c.deinit(); try testing.expectError(error.ProtocolError, c.handshake()); // The GOAWAY is the last frame written; its error code is the last four // octets before the debug data. const out = server.written(); var rest = out[preface.len..]; var code: ?u32 = null; while (rest.len >= 9) { const len = std.mem.readInt(u24, rest[0..3], .big); if (rest[3] == 0x07) code = std.mem.readInt(u32, rest[13..17], .big); rest = rest[9 + len ..]; } // §6.5.2: "Values above the maximum flow-control window size of 2^31-1 // MUST be treated as a connection error of type FLOW_CONTROL_ERROR." try testing.expectEqual(@as(?u32, @backingInt(frame.ErrorCode.flow_control_error)), code); }