// 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, /// 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 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, /// §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, /// §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, }; 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, 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, 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, }; } 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; } /// Hands the connection back without closing it. pub fn releaseConnection(c: *Connection) transport.Connection { c.owns_connection = false; return c.conn; } /// §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; } } 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; nothing is read here, so /// several may be begun before any is awaited and they are then genuinely /// in flight together. 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), }; errdefer c.release(s); try c.writeRequest(s, request); return .{ .slot = slot, .id = 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. 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.reset) |code| { return if (code == .refused_stream) error.StreamRefused else error.StreamReset; } try c.pump(); } if (s.reset) |code| { return if (code == .refused_stream) error.StreamRefused else error.StreamReset; } // §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; }, } } 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 = Response.Body.empty_reader, .length = s.body.items.len, .present = s.body.items.len > 0, }, }; } /// The body of a completed stream, which lives until `finish`. 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; } /// Gives the stream's slot back. Everything `await` returned for it /// points into memory this frees. 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); } /// One request, begun and awaited. pub fn send(c: *Connection, request: Request) Error!Response { const handle = try c.begin(request); return c.await(handle); } 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; 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 (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| { c.theirs.apply(entry) catch return c.fail(.protocol_error, "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; s.send_window = @intCast(@as(i64, s.send_window) + delta); } } 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; }; 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; }; if (!s.head_done) { try c.readStatus(s); s.head_done = true; } if (first.flags & 0x01 != 0) s.done = true; // END_STREAM } /// §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.streamMalformed(s); if (!std.mem.eql(u8, field.name, ":status")) return c.streamMalformed(s); if (status != null) return c.streamMalformed(s); if (field.value.len != 3) return c.streamMalformed(s); var n: u16 = 0; for (field.value) |ch| { if (ch < '0' or ch > '9') return c.streamMalformed(s); n = n * 10 + (ch - '0'); } 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.streamMalformed(s); } // §8.2.2: connection-specific fields have no meaning in HTTP/2. if (isConnectionSpecific(field.name)) return c.streamMalformed(s); } s.status = status orelse return c.streamMalformed(s); // 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. fn streamMalformed(c: *Connection, s: *Stream) Error!void { frame.writeRstStream(c.conn.output, s.id, .protocol_error) catch return error.WriteFailed; c.conn.output.flush() catch return error.WriteFailed; s.reset = .protocol_error; s.done = true; return error.MalformedResponse; } 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"); 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()); }