// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! The HTTP/2 driver: one connection's streams, read off a byte stream and //! answered on it. //! //! The sibling of `http1/Connection.zig`, and the shape is deliberately the //! same — a `Session` holding everything, buffers allocated once, free //! functions wired into `Response.VTable` that recover the stream through //! `@ptrCast(@alignCast(res.context.?))`. What is different is that there are //! many requests in flight at once, and nearly every complication below comes //! from that. //! //! ## Three kinds of task //! //! The task that called `serve` becomes the **frame reader** and stays that //! for the life of the connection. It owns `conn.input`, the HPACK decoder, //! the stream table and the settings. Each request gets a **stream task** of //! its own, spawned with `Io.Group.concurrent`. And one **control writer** //! sends the frames the reader answers with -- acknowledgements, //! WINDOW_UPDATE, RST_STREAM -- so that the reader never writes to the socket //! and so never blocks on it; `Serializer` has the deadlock that prevents. //! //! A separate reader is not a choice. If the handler ran on the reader's //! task, a handler that reads its own request body would deadlock at once and //! always: the DATA frames it is waiting for can only arrive through the task //! that is waiting for them, so `POST` would be impossible. `Group.async` is //! no good either — its contract permits running the function inline before //! returning, which is exactly that deadlock — so `concurrent` is the only //! option, and an `Io` that cannot provide it cannot serve HTTP/2. //! //! ## Lock order //! //! `streams_mutex` then `fc_mutex` then the serializer's. The first two are //! never held across I/O; the serializer's is held across I/O and nothing //! else may be taken while it is. //! //! `reset_mutex` is outside that order because it is a leaf: it guards one //! array, it is never held while anything else is taken, and it has to be //! reachable from under both of the first two — `onWindowUpdate` holds the //! pair when it resets a stream whose window the peer overflowed. //! //! ## Arena ownership //! //! The reader owns a stream's arena until the stream's task is spawned, and //! never afterwards. Unlike `http1` it is never reset — which is why the //! field list may live in it. The use-after-free that bit `http1` (an //! `ArrayList` whose capacity pointed into freed arena memory) cannot happen //! without a reset, so the rule that file follows does not apply here. const std = @import("std"); const Io = std.Io; const Allocator = std.mem.Allocator; const assert = std.debug.assert; const protocol = @import("../protocol.zig"); const transport = @import("../transport.zig"); const Field = protocol.Field; const Headers = protocol.Headers; const Length = protocol.Length; const Status = protocol.Status; const token = protocol.token; const Handler = @import("../server/Handler.zig"); const Request = @import("../server/Request.zig"); const Response = @import("../server/Response.zig"); const compression = @import("../server/compression.zig"); const frame = @import("frame.zig"); const hpack = @import("hpack.zig"); const request_builder = @import("../field/request.zig"); const Serializer = @import("Serializer.zig"); const Settings = @import("Settings.zig"); const log = std.log.scoped(.http2); pub const Config = struct { /// Advertised as `SETTINGS_MAX_CONCURRENT_STREAMS`. /// /// Also, and less obviously, a bound on how many tasks one connection can /// have in flight. Under `Io.Threaded` a task is an OS thread, so this is /// a thread count per connection; under a fibre-based `Io` it is nearly /// free. The default is the conventional one and the right number depends /// on which `Io` the caller supplied. max_concurrent_streams: u32 = 100, /// Advertised as `SETTINGS_INITIAL_WINDOW_SIZE`, and the size of the /// buffer each request body is queued through. stream_receive_window: u31 = 65535, /// Advertised as `SETTINGS_MAX_FRAME_SIZE`. max_frame_size: u24 = 16384, /// Advertised as `SETTINGS_MAX_HEADER_LIST_SIZE`. max_header_list_size: u32 = 16 * 1024, /// Advertised as `SETTINGS_HEADER_TABLE_SIZE`. header_table_size: u32 = 4096, /// The connection-level receive window. /// /// Replenished as octets are *routed* to a stream rather than as handlers /// consume them. If it were consumption-based, one handler that never /// read its request body would eat the whole connection window and starve /// every other stream — head-of-line blocking of exactly the kind HTTP/2 /// exists to remove, and reachable by one lazy handler. Backpressure /// belongs at stream level, where it is per-request. connection_receive_window: u31 = 1 << 20, /// The most compressed octets one field block may occupy across its /// HEADERS and CONTINUATION frames. max_field_block_len: usize = 32 * 1024, /// The most CONTINUATION frames one field block may be split across. /// /// A byte cap alone does not stop the flood of CVE-2024-27316: the attack /// is a stream of CONTINUATION frames with *empty* fragments, which add /// no octets and can go on forever. Each frame's nine-octet header is /// charged against `max_field_block_len` as well, so an empty flood hits /// that cap too; this is the second, more legible limit. max_continuation_frames: u32 = 16, /// The longest single decoded name or value. max_field_len: usize = 8 * 1024, /// How much of a request body nobody read will be thrown away. max_drain_len: u64 = 1 << 20, /// The most request body this server will read for one request, or null /// for no limit beyond what the handler chooses to read. A request whose /// `content-length` is over it is answered `413` before the handler runs. /// One that sends more without saying so has its body read fail at the /// limit, and is answered `413` unless the handler has already begun a /// response. Either way the `413` is followed by RST_STREAM with /// NO_ERROR, which §8.1 of RFC 9113 gives a server for asking the client /// to stop sending. The same option exists on the HTTP/1 and HTTP/3 /// servers. max_body_len: ?u64 = null, /// The most streams one connection may serve before it is closed. max_streams: u64 = 1 << 20, /// How many streams may end without this server having answered them /// before the connection is refused. /// /// This is the defence against the rapid reset of CVE-2023-44487, and /// what makes that attack work is worth stating: a stream the client /// resets closes at once and so never counts against /// `max_concurrent_streams`, which means the concurrency limit limits /// nothing. A client can open and cancel streams as fast as it can write /// frames, and each one costs the server a task, an arena and a handler. /// /// Every RST_STREAM the peer sends spends a token; every stream that runs /// to completion without being cancelled returns one, to the initial /// value at most. /// /// Charging the cancellation rather than the unanswered work is /// deliberate. A fast handler may well have finished before the /// RST_STREAM lands, so counting only what went unanswered counts almost /// nothing — and the cost the attack is really buying is the task, the /// arena and the field decode, all of which are spent by then. Under /// `Io.Threaded` a task is an operating system thread, which is the /// expensive part and is spent before any handler runs. /// /// A client that cancels a few requests because somebody navigated away /// never notices; one that cancels everything runs out. reset_budget: u32 = 200, /// How much work that goes nowhere a connection may ask for. /// /// SETTINGS, PING, RST_STREAM, PRIORITY, an empty DATA frame and a frame /// for a stream that has gone all cost the server something and move the /// conversation no further. RFC 9113 §10.5 blesses a limit on exactly /// this. One weighted counter rather than five separate ones, and /// deliberately clock-free: a limit that depended on a clock could not be /// tested over a transport with no I/O in it. /// /// Its weakness is worth knowing — a flood interleaved with real traffic /// is partly paid for by that traffic — and a time-based bucket is the /// more precise alternative if one is ever wanted. max_noise: u32 = 1000, /// Whether to advertise `SETTINGS_ENABLE_CONNECT_PROTOCOL` (RFC 8441), /// which is what lets a client reach `Response.upgrade` over HTTP/2. /// /// On by default, and it costs nothing to leave on: extended CONNECT is /// only ever reached by a client that sends `:protocol`, and until a /// handler calls `res.upgrade(...)` such a request is answered like any /// other. A server that wants nothing to do with tunnels sets this false, /// and then `:protocol` is an undefined pseudo-header and the request is /// malformed -- which is precisely what RFC 8441 §3 says a non-supporting /// peer does. enable_connect_protocol: bool = true, /// What to send as `server`, or null for none. server_name: ?[]const u8 = "zig-http", /// Whether to send `date`. send_date: bool = true, /// Whether to code a response body, and how. Null is a server that does /// not compress; the policy and its defaults are /// `server.compression.Config`'s, and are the same ones the other two /// drivers take — a coding is the representation's and not the version's. compression: ?compression.Config = null, /// Whether to undo a content coding on a request body before the handler /// sees it. The same option the other two drivers take, for the same /// reason: a coding is the representation's and not the version's. request_decoding: ?compression.RequestDecoding = null, }; /// The connection-level flow-control window both ends start with (§6.9.2). /// Unlike a stream's, no SETTINGS value can change it. const initial_connection_window: u31 = 65535; pub const Error = Allocator.Error; /// Serves a connection until it ends. Does not close it; the caller that /// opened it closes it. It does shut down the writing half, after the /// GOAWAY that ends every connection, so that the peer sees an orderly end. /// /// The calling task becomes the connection's frame reader, and each request /// runs `handler` on a task of its own, so `io` must be able to run tasks /// concurrently. Every stream's task has returned by the time this does: /// awaited when the peer simply stopped sending, cancelled after a /// connection error. A protocol failure is answered on the wire, with /// RST_STREAM or GOAWAY, and not returned: the only error is running out of /// memory while setting up. pub fn serve( io: Io, gpa: Allocator, conn: *transport.Connection, handler: Handler, config: Config, ) Error!void { var session: Session = undefined; try session.init(io, gpa, conn, handler, config); defer session.deinit(); session.run(); } test serve { const hello = struct { fn serve(req: *Request, res: *Response) Handler.Error!void { _ = req; try res.send("hello"); } }; // A client's half, written out by hand: the preface, an empty SETTINGS, // and a HEADERS frame on stream 1 that ends the stream -- `GET`, `http` // and `/` from the static table, and a literal `:authority`. const client: []const u8 = @import("../http2.zig").preface ++ [_]u8{ 0x00, 0x00, 0x00, 0x04, 0x00, 0x00, 0x00, 0x00, 0x00 } ++ [_]u8{ 0x00, 0x00, 0x0e, 0x01, 0x05, 0x00, 0x00, 0x00, 0x01 } ++ [_]u8{ 0x82, 0x86, 0x84, 0x41, 0x09 } ++ "a.example"; var memory: transport.memory.Connection = try .init(std.testing.allocator, client, .{}); defer memory.deinit(); var conn = memory.connection(); try serve(std.testing.io, std.testing.allocator, &conn, .initStateless(hello.serve), .{}); const written = memory.written(); // The server's own preface is a SETTINGS frame, and comes first. try std.testing.expectEqual(@as(u8, 0x04), written[3]); // The handler's body went out in a DATA frame on stream 1. try std.testing.expect(std.mem.indexOf(u8, written, "hello") != null); } test "the reader goes on reading when the socket will take no more" { // A peer that has stopped reading: the socket takes the server's preface // and then never another octet, and a write past that waits until it is // cancelled. const Stuck = struct { interface: Io.Writer, room: usize, never: Io.Event = .unset, /// Set once a wait has been cancelled. A cancellation is spent on /// the first wait that sees it, so a second one would never end. broken: bool = false, fn drain(w: *Io.Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize { const st: *@This() = @alignCast(@fieldParentPtr("interface", w)); const total = Io.Writer.countSplat(data, splat); if (total == 0) return 0; if (st.broken) return error.WriteFailed; if (st.room == 0) { st.never.wait(std.testing.io) catch {}; st.broken = true; return error.WriteFailed; } const n = @min(st.room, total); st.room -= n; return n; } }; var stuck: Stuck = .{ .interface = .{ .vtable = &.{ .drain = Stuck.drain }, .buffer = &.{} }, .room = 128, }; // And that keeps talking: forty PINGs, each of which wants an answer the // socket will not take. Before the control writer, the reader answered // them itself, blocked on the first answer that did not fit, and read // nothing more -- which is the half of a deadlock this end supplies. const ping = [_]u8{ 0x00, 0x00, 0x08, 0x06, 0x00, 0x00, 0x00, 0x00, 0x00 } ++ "pingpong".*; const client: []const u8 = @import("../http2.zig").preface ++ [_]u8{ 0x00, 0x00, 0x00, 0x04, 0x00, 0x00, 0x00, 0x00, 0x00 } ++ @as([40 * ping.len]u8, @bitCast(@as([40][ping.len]u8, @splat(ping)))); var memory: transport.memory.Connection = try .init(std.testing.allocator, client, .{}); defer memory.deinit(); var conn = memory.connection(); conn.output = &stuck.interface; const Run = struct { fn run(c: *transport.Connection) void { const nothing = struct { fn serve(_: *Request, _: *Response) Handler.Error!void {} }; serve(std.testing.io, std.testing.allocator, c, .initStateless(nothing.serve), .{}) catch {}; } }; var group: Io.Group = .init; try group.concurrent(std.testing.io, Run.run, .{&conn}); var waited: usize = 0; while (memory.consumed() < client.len and waited < 500) : (waited += 1) { try std.testing.io.sleep(.fromMilliseconds(10), .awake); } const consumed = memory.consumed(); // The GOAWAY at the end cannot be written either, so the connection is // ended the way a server shutting down would end it. group.cancel(std.testing.io); try std.testing.expectEqual(client.len, consumed); } test "RFC 9113 8.1.1: a body shorter than its declared length resets the stream" { const short = struct { fn serve(req: *Request, res: *Response) Handler.Error!void { _ = req; const w = try res.beginBody(.{ .exact = 5 }); try w.writeAll("he"); } }; // The same request as `serve`'s example. const client: []const u8 = @import("../http2.zig").preface ++ [_]u8{ 0x00, 0x00, 0x00, 0x04, 0x00, 0x00, 0x00, 0x00, 0x00 } ++ [_]u8{ 0x00, 0x00, 0x0e, 0x01, 0x05, 0x00, 0x00, 0x00, 0x01 } ++ [_]u8{ 0x82, 0x86, 0x84, 0x41, 0x09 } ++ "a.example"; var memory: transport.memory.Connection = try .init(std.testing.allocator, client, .{}); defer memory.deinit(); var conn = memory.connection(); try serve(std.testing.io, std.testing.allocator, &conn, .initStateless(short.serve), .{}); // §8.1.1: content that does not match its `content-length` is // malformed, so the client has to be told the response is not whole -- // which END_STREAM would claim and silence would leave it waiting for. var rest = memory.written(); var reset: ?u32 = null; var ended = false; while (rest.len >= 9) { const len = std.mem.readInt(u24, rest[0..3], .big); const kind = rest[3]; const flags = rest[4]; const id = std.mem.readInt(u32, rest[5..9], .big) & 0x7fff_ffff; if (id == 1 and kind == @backingInt(frame.Type.rst_stream)) reset = std.mem.readInt(u32, rest[9..13], .big); if (id == 1 and kind == @backingInt(frame.Type.data) and flags & 0x01 != 0) ended = true; rest = rest[9 + len ..]; } try std.testing.expect(!ended); try std.testing.expectEqual(@as(?u32, @backingInt(frame.ErrorCode.internal_error)), reset); } /// Whether a connection-level failure should be reported at all. A peer that /// simply went away is not news. fn worthLogging(code: frame.ErrorCode) bool { return code != .no_error; } const Session = struct { io: Io, gpa: Allocator, conn: *transport.Connection, handler: Handler, config: Config, writer: Serializer, decoder: hpack.Decoder, encoder: hpack.Encoder, decoder_scratch: []u8, /// What we told the peer, and what the peer told us. ours: Settings, peer: Settings, streams_mutex: Io.Mutex, streams: std.AutoHashMapUnmanaged(u31, *Stream), active_streams: u32, /// Streams a stream task has reset while the peer might still have been /// sending, for the reader to close its half of. The peer stops at the /// RST_STREAM and never sends END_STREAM, so nothing else would, and the /// stream would hold a `max_concurrent_streams` slot for the life of the /// connection. Under `streams_mutex`. retiring: std.ArrayList(u31), /// The highest identifier the peer has opened, for the monotonicity rule. last_peer_stream_id: u31, /// The highest this server actually dispatched to a handler, which is /// what GOAWAY must name: it is a promise about what the client may /// safely retry elsewhere. last_processed_stream_id: u31, streams_started: u64, going_away: bool, /// The peer's `SETTINGS_INITIAL_WINDOW_SIZE` as it stood when the open /// streams were given their windows. peer_initial_window: u31, fc_mutex: Io.Mutex, /// One condition for both levels. A body writer waits on /// `min(connection, stream) > 0` and must wake for either, and with two /// conditions it could sleep on one and miss the other. fc_cond: Io.Condition, send_window: i32, recv_window: i32, /// Octets routed but not yet credited back to the peer. recv_pending: u31, dead: bool, /// Whether the peer has stopped sending, which is what makes an empty /// send window permanent: a WINDOW_UPDATE is the only thing that opens /// one, and it can only arrive on a connection still being read. input_ended: bool, tasks: Io.Group, /// The control writer, alone: in a group of its own because it runs until /// cancelled, and `tasks` is awaited on the way out. control_writer: Io.Group, field_block: std.ArrayList(u8), /// The last few streams this server reset, and nothing else. /// /// RFC 9113 §5.1 draws a line this server has to draw too: a frame /// arriving after the peer's own END_STREAM is a connection error of type /// STREAM_CLOSED, while a frame arriving after *we* sent RST_STREAM was /// in flight when we did and has to be tolerated. Once a stream leaves /// the table there is nothing left to say which of the two it was, so the /// identifiers we reset are remembered — a handful of them, in a ring, /// because a frame for a stream reset long ago is not in flight, it is a /// peer that has lost track. /// Guards `recently_reset` alone, and is never held while anything else /// is taken. A leaf lock rather than a place in the order at the top of /// this file, because `sendReset` is reached from inside `streams_mutex` /// and `fc_mutex` both -- `onWindowUpdate` holds the pair when it resets /// a stream whose window the peer overflowed -- and a lock that can be /// taken under either has to be below both. reset_mutex: Io.Mutex, recently_reset: [16]u31, recently_reset_next: u8, /// Tokens left for streams that end without an answer. See /// `Config.reset_budget`. reset_budget: u32, /// Accumulated cost of frames that went nowhere. See `Config.max_noise`. noise: u32, fn init( s: *Session, io: Io, gpa: Allocator, conn: *transport.Connection, handler: Handler, config: Config, ) Allocator.Error!void { const scratch = try gpa.alloc(u8, config.max_field_len); errdefer gpa.free(scratch); s.* = .{ .io = io, .gpa = gpa, .conn = conn, .handler = handler, .config = config, .writer = .init(io, conn.output), .decoder = .init(config.header_table_size, scratch, .{ .max_header_list_size = config.max_header_list_size, }), .encoder = .{}, .decoder_scratch = scratch, .ours = .{ .header_table_size = config.header_table_size, .enable_push = false, .max_concurrent_streams = config.max_concurrent_streams, .initial_window_size = config.stream_receive_window, .max_frame_size = config.max_frame_size, .enable_connect_protocol = config.enable_connect_protocol, .max_header_list_size = config.max_header_list_size, }, .peer = .{}, .streams_mutex = .init, .streams = .empty, .active_streams = 0, .retiring = .empty, .last_peer_stream_id = 0, .last_processed_stream_id = 0, .streams_started = 0, .going_away = false, .peer_initial_window = 65535, .fc_mutex = .init, .fc_cond = .init, .send_window = 65535, .recv_window = config.connection_receive_window, .recv_pending = 0, .dead = false, .input_ended = false, .tasks = .init, .control_writer = .init, .field_block = .empty, .reset_mutex = .init, .recently_reset = @splat(0), .recently_reset_next = 0, .reset_budget = config.reset_budget, .noise = 0, }; } fn deinit(s: *Session) void { var it = s.streams.valueIterator(); while (it.next()) |stream| stream.*.release(s.gpa); s.streams.deinit(s.gpa); s.retiring.deinit(s.gpa); s.field_block.deinit(s.gpa); s.decoder.deinit(s.gpa); s.gpa.free(s.decoder_scratch); s.* = undefined; } fn run(s: *Session) void { // Ordered deliberately. The GOAWAY below is written inline, and this // runs after it, so the peer is told why before its streams are // stopped. `cancel` also awaits, so every stream task has returned // before `deinit` frees anything they point into. defer s.tasks.cancel(s.io); // Last of all, after the GOAWAY, which empties the outbox on its way // out and so sends anything the writer had not got to. defer s.control_writer.cancel(s.io); // An `Io` that cannot give the control writer a task cannot give the // streams one either, and `Connection.serve`'s contract already says // so; the GOAWAY below is the answer to both. s.control_writer.concurrent(s.io, Serializer.runControlWriter, .{&s.writer}) catch { s.writer.sendGoaway(0, .internal_error, "") catch {}; return; }; // The server's own connection preface goes out first, before the // client's has even been read. §3.4 requires our SETTINGS to be the // first frame we send, and a GOAWAY refusing a bad preface is still a // frame — a peer that received one with no SETTINGS ahead of it would // be right to call the connection malformed. const fault: frame.Fault = s.sendInitialSettings() orelse s.readPreface() orelse s.readLoop(); // A peer that simply stopped sending has broken nothing. The streams // already in flight were received whole, their responses still have // somewhere to go, and throwing that work away would mean a client // which closed its sending half after its last request -- which is // an ordinary thing to do, and what every test over a transport made // of a fixed string does -- got no answers at all. // // A connection *error* is the other case. Nothing further can be // understood, so a handler still running is producing octets nobody // will ever read, and the streams are stopped rather than waited for. if (fault.code == .no_error) { s.endInput(); s.tasks.await(s.io) catch {}; } s.markDead(); if (worthLogging(fault.code)) { log.debug("connection error: {f}", .{fault.code}); } s.writer.sendGoaway(s.last_processed_stream_id, fault.code, "") catch {}; // Half-close and then read whatever the peer had already sent. A // socket closed with unread data in its receive queue is closed with // a RST, which the peer sees as the connection breaking rather than // as the orderly shutdown the GOAWAY just promised. s.conn.shutdownWrite(s.io); var discarded: u64 = 0; while (discarded < s.config.max_drain_len) { const n = s.conn.input.discard(.limited64(s.config.max_drain_len - discarded)) catch break; if (n == 0) break; discarded += n; } } /// Tells every stream that nothing more is coming, without telling it /// that anything went wrong. /// /// The difference from `markDead` is the whole of the graceful path: a /// body reader sees the end of its body rather than a reset, and a writer /// with credit in hand goes on spending it. What does stop is waiting — /// for a request body that will never arrive, and for a window that will /// never open. fn endInput(s: *Session) void { s.fc_mutex.lockUncancelable(s.io); s.input_ended = true; s.fc_mutex.unlock(s.io); s.fc_cond.broadcast(s.io); s.streams_mutex.lockUncancelable(s.io); var it = s.streams.valueIterator(); while (it.next()) |stream| stream.*.endInput(s.io); s.streams_mutex.unlock(s.io); } /// Wakes everything blocked on flow control so that the stream tasks can /// unwind rather than wait for a peer that is gone. fn markDead(s: *Session) void { s.fc_mutex.lockUncancelable(s.io); s.dead = true; s.fc_mutex.unlock(s.io); s.fc_cond.broadcast(s.io); s.streams_mutex.lockUncancelable(s.io); var it = s.streams.valueIterator(); while (it.next()) |stream| stream.*.abort(s.io); s.streams_mutex.unlock(s.io); } const http2 = @import("../http2.zig"); /// Matches the preface as it arrives rather than waiting for all of it. /// /// A client that sends a short wrong preface and then waits is entitled /// to a GOAWAY, and asking for twenty-four octets first would mean /// blocking for octets it is never going to send. fn readPreface(s: *Session) ?frame.Fault { var matched: usize = 0; while (matched < http2.preface.len) { const available = s.conn.input.peekGreedy(1) catch return .conn(.protocol_error); const n = @min(available.len, http2.preface.len - matched); if (!std.mem.eql(u8, available[0..n], http2.preface[matched..][0..n])) { return .conn(.protocol_error); } s.conn.input.toss(n); matched += n; } return null; } fn sendInitialSettings(s: *Session) ?frame.Fault { var payload: [6 * 9]u8 = undefined; var w: Io.Writer = .fixed(&payload); s.ours.writePayload(&w, .{}) catch return .conn(.internal_error); s.writer.send(.{ .length = @intCast(w.end), .type = .settings, .flags = 0, .stream_id = 0, }, payload[0..w.end]) catch return .conn(.no_error); // And then raise the *connection* window, which SETTINGS cannot // touch. // // `SETTINGS_INITIAL_WINDOW_SIZE` sets the window for each stream and // says nothing about the connection, whose own window stays at the // 65535-octet default of §6.9.2 until a WINDOW_UPDATE on stream zero // moves it. Without this, a configured connection window larger than // the default is a number this server believes and the peer has never // heard: an upload stalls at exactly 65535 octets with both ends // behaving correctly and neither able to go on. if (s.config.connection_receive_window > initial_connection_window) { const increment = s.config.connection_receive_window - initial_connection_window; var bytes: [4]u8 = undefined; std.mem.writeInt(u32, &bytes, increment, .big); s.writer.send(.{ .length = 4, .type = .window_update, .flags = 0, .stream_id = 0, }, &bytes) catch return .conn(.no_error); } return null; } fn readLoop(s: *Session) frame.Fault { while (true) { const header = frame.Header.read(s.conn.input) catch |err| switch (err) { // A peer that closed at a frame boundary is a connection // ending, not a connection erring. error.EndOfStream => return .conn(.no_error), error.ReadFailed => return .conn(.no_error), }; if (frame.checkHeader(header, s.ours.max_frame_size)) |fault| { switch (fault.scope) { .connection => return fault, .stream => { s.conn.input.discardAll(header.length) catch return .conn(.no_error); // §5.1.1: an identifier no client can own is a // connection error, and that takes precedence over // whatever else was wrong with the frame. Answering // with RST_STREAM instead would name a stream that is // idle by definition, and §5.1 makes a frame on an // idle stream a connection error for whoever receives // it -- so the complaint would itself be a violation. if (header.stream_id == 0 or header.stream_id % 2 == 0) { return .conn(.protocol_error); } s.resetStream(header.stream_id, fault.code); continue; }, } } // Before the frame rather than after: a HEADERS opening a stream // is where a slot held by a stream already reset would refuse it. s.closeRetired(); if (s.dispatch(header)) |fault| return fault; } } /// The reader's half of each stream in `retiring`, which only the reader /// may close: it alone writes `remote`, and it uses a stream it has /// looked up without a reference, which is safe only while its own half /// is open. The input queue is closed without marking the stream reset, /// so that a stream answered with a status still counts as answered /// against `reset_budget`; every task that queues one has finished with /// its handler. fn closeRetired(s: *Session) void { while (true) { s.streams_mutex.lockUncancelable(s.io); const id = s.retiring.pop() orelse { s.streams_mutex.unlock(s.io); return; }; const found = s.streams.get(id); s.streams_mutex.unlock(s.io); const stream = found orelse continue; if (stream.remote == .closed) continue; stream.remote = .closed; stream.endInput(s.io); s.closeStreamHalf(stream); } } /// Charges a frame that cost this server something and advanced nothing. /// Returns a fault once a connection has done nothing else for too long. fn charge(s: *Session, weight: u32) ?frame.Fault { s.noise +|= weight; if (s.noise > s.config.max_noise) return .conn(.enhance_your_calm); return null; } /// Paid back by a frame that did advance something: a request dispatched, /// or a DATA frame that actually carried payload. fn credit(s: *Session, weight: u32) void { s.noise -|= weight; } fn dispatch(s: *Session, header: frame.Header) ?frame.Fault { if (switch (header.type) { .settings => s.charge(4), .ping => s.charge(2), .rst_stream => s.charge(2), .priority => s.charge(1), .window_update => s.charge(1), _ => s.charge(1), else => null, }) |fault| return fault; // §5.1.1: even identifiers belong to streams the server initiates, // and this server initiates none -- push is switched off and there is // no other way. So a frame the client sent on one names a stream that // cannot exist, and the only answer is a connection error. Checked // here, once, rather than in each handler: getting it wrong in one of // them means answering with RST_STREAM for a stream that is idle by // definition, which §5.1 makes a connection error for the peer that // receives it. if (header.stream_id != 0 and header.stream_id % 2 == 0) { return .conn(.protocol_error); } return switch (header.type) { .settings => s.onSettings(header), .ping => s.onPing(header), .goaway => s.onGoaway(header), .window_update => s.onWindowUpdate(header), .rst_stream => s.onRstStream(header), .priority => s.onPriority(header), .headers => s.onHeaders(header), .data => s.onData(header), // §6.10: a CONTINUATION that does not follow a HEADERS this // server is still assembling. `onHeaders` consumes the ones that // do, so reaching here means the peer sent one out of sequence. .continuation => .conn(.protocol_error), .push_promise => .conn(.protocol_error), // §4.1: discard what we do not know. _ => { s.conn.input.discardAll(header.length) catch return .conn(.no_error); return null; }, }; } fn onSettings(s: *Session, header: frame.Header) ?frame.Fault { if (frame.AckFlags.from(header.flags).ack) return null; var remaining = header.length; var new_initial_window: ?u31 = null; while (remaining >= 6) : (remaining -= 6) { const entry_bytes = s.conn.input.takeArray(6) catch return .conn(.no_error); var it = Settings.iterate(entry_bytes); const entry = it.next().?; s.peer.apply(entry) catch |err| return .conn(Settings.errorCode(err)); if (entry.id == .initial_window_size) new_initial_window = s.peer.initial_window_size; if (entry.id == .header_table_size) s.encoder.setPeerTableSize(entry.value); } // §6.9.2: a change to the initial window size adjusts every open // stream's send window by the difference, and the result may legally // go negative — which is why these are signed. if (new_initial_window) |window| { if (s.applyInitialWindow(window)) |fault| return fault; } // Through the serializer like every other frame. This once wrote to // the socket directly, with no lock, and so could land in the middle // of a frame a stream task was writing. s.writer.sendControl(.{ .length = 0, .type = .settings, .flags = (frame.AckFlags{ .ack = true }).toInt(), .stream_id = 0, }, &.{}) catch |err| return switch (err) { error.OutboxFull => .conn(.enhance_your_calm), else => .conn(.no_error), }; return null; } fn applyInitialWindow(s: *Session, window: u31) ?frame.Fault { s.streams_mutex.lockUncancelable(s.io); defer s.streams_mutex.unlock(s.io); s.fc_mutex.lockUncancelable(s.io); defer s.fc_mutex.unlock(s.io); const previous = s.peer_initial_window; const delta = @as(i64, window) - @as(i64, previous); s.peer_initial_window = window; var it = s.streams.valueIterator(); while (it.next()) |stream| { const updated = @as(i64, stream.*.send_window) + delta; if (updated > Settings.max_window_size) return .conn(.flow_control_error); stream.*.send_window = @intCast(updated); } s.fc_cond.broadcast(s.io); return null; } fn onPing(s: *Session, header: frame.Header) ?frame.Fault { const payload = s.conn.input.takeArray(8) catch return .conn(.no_error); // §6.7: an ACK is an answer to ours and is not answered again. if (frame.AckFlags.from(header.flags).ack) return null; s.writer.sendControl(.{ .length = 8, .type = .ping, .flags = (frame.AckFlags{ .ack = true }).toInt(), .stream_id = 0, }, payload) catch |err| return switch (err) { error.OutboxFull => .conn(.enhance_your_calm), else => .conn(.no_error), }; return null; } fn onGoaway(s: *Session, header: frame.Header) ?frame.Fault { s.conn.input.discardAll(header.length) catch return .conn(.no_error); // The peer is finishing. Serve what is already in flight and accept // nothing new. s.going_away = true; return null; } fn onWindowUpdate(s: *Session, header: frame.Header) ?frame.Fault { const payload = s.conn.input.takeArray(4) catch return .conn(.no_error); const increment = frame.parseWindowUpdate(payload) catch |err| { // §6.9: a zero increment is a connection error on stream zero and // a stream error on any other. if (header.stream_id == 0) return .conn(frame.errorCode(err)); s.resetStream(header.stream_id, frame.errorCode(err)); return null; }; // The locks are held in a block of their own, because the one answer // that resets a stream has to give them up first: `resetStream` takes // `streams_mutex` itself, and taking it again here hung the reader for // good on a single WINDOW_UPDATE. const overflowed = blk: { // `streams_mutex` before `fc_mutex`, which is the order stated at // the top of this file and the one `applyInitialWindow` takes. The // other way round is an inversion between the two, and a deadlock // waiting for the right interleaving. s.streams_mutex.lockUncancelable(s.io); defer s.streams_mutex.unlock(s.io); s.fc_mutex.lockUncancelable(s.io); defer s.fc_mutex.unlock(s.io); defer s.fc_cond.broadcast(s.io); if (header.stream_id == 0) { const updated = @as(i64, s.send_window) + increment; if (updated > Settings.max_window_size) return .conn(.flow_control_error); s.send_window = @intCast(updated); return null; } // §5.1: a frame for an idle stream -- one with an identifier the // peer has never opened -- is a connection error. The stream table // cannot tell "never existed" from "already finished", which is // what the high-water mark is for. if (header.stream_id > s.last_peer_stream_id) return .conn(.protocol_error); const stream = s.streams.get(header.stream_id) orelse return null; const updated = @as(i64, stream.send_window) + increment; // §6.9.1: a stream window past 2^31-1 is a stream error. if (updated > Settings.max_window_size) break :blk true; stream.send_window = @intCast(updated); break :blk false; }; if (overflowed) s.resetStream(header.stream_id, .flow_control_error); return null; } fn onRstStream(s: *Session, header: frame.Header) ?frame.Fault { _ = s.conn.input.takeArray(4) catch return .conn(.no_error); // §6.4: a RST_STREAM on an idle stream is a connection error. if (header.stream_id > s.last_peer_stream_id) return .conn(.protocol_error); s.streams_mutex.lockUncancelable(s.io); s.reset_budget -|= 1; const spent = s.reset_budget == 0; s.streams_mutex.unlock(s.io); s.finishStream(header.stream_id, .cancel); if (spent) return .conn(.enhance_your_calm); return null; } fn onPriority(s: *Session, header: frame.Header) ?frame.Fault { // §5.3.2 deprecates the RFC 7540 prioritisation scheme, and RFC 9218 // is the replacement this does not implement. The five octets are // still parsed, because one rule about them survives: a stream may // not depend on itself (§5.3.1). Everything else is discarded. const payload = s.conn.input.takeArray(5) catch return .conn(.no_error); const priority = frame.parsePriority(payload) catch return .conn(.protocol_error); if (priority.dependency == header.stream_id) return .conn(.protocol_error); return null; } fn onHeaders(s: *Session, header: frame.Header) ?frame.Fault { const flags = frame.HeadersFlags.from(header.flags); // §6.2: the padding and priority prologue come before the fragment. var payload_left = header.length; var pad_len: u8 = 0; if (flags.padded) { pad_len = s.conn.input.takeByte() catch return .conn(.no_error); if (payload_left == 0) return .conn(.protocol_error); payload_left -= 1; } if (flags.priority) { if (payload_left < 5) return .conn(.protocol_error); const fields_bytes = s.conn.input.takeArray(5) catch return .conn(.no_error); const priority = frame.parsePriority(fields_bytes) catch return .conn(.protocol_error); // §5.3.1: "A stream cannot depend on itself." if (priority.dependency == header.stream_id) return .conn(.protocol_error); payload_left -= 5; } if (pad_len > payload_left) return .conn(.protocol_error); const fragment_len = payload_left - pad_len; s.field_block.clearRetainingCapacity(); if (s.appendFragment(fragment_len)) |fault| return fault; s.conn.input.discardAll(pad_len) catch return .conn(.no_error); // §6.10: nothing but CONTINUATION frames for this stream may appear // until one carries END_HEADERS. var continuations: u32 = 0; var end_headers = flags.end_headers; while (!end_headers) { continuations += 1; if (continuations > s.config.max_continuation_frames) { return .conn(.enhance_your_calm); } const next = frame.Header.read(s.conn.input) catch return .conn(.no_error); if (next.type != .continuation or next.stream_id != header.stream_id) { return .conn(.protocol_error); } if (frame.checkHeader(next, s.ours.max_frame_size)) |fault| return fault; if (s.appendFragment(next.length)) |fault| return fault; end_headers = frame.ContinuationFlags.from(next.flags).end_headers; } // A second field section on a stream that is still open is trailers. // Anything else -- a stream that has finished, or an identifier that // has gone backwards -- falls through to `openStream`, which is where // the §5.1.1 rules about identifiers live. s.streams_mutex.lockUncancelable(s.io); const existing = s.streams.get(header.stream_id); s.streams_mutex.unlock(s.io); if (existing) |st| { // §5.1: the peer has already said it was finished sending, so // there is no room for another field section. if (st.remote == .closed) return .conn(.stream_closed); return s.onTrailers(st, flags.end_stream); } // §5.1: once this server has sent RST_STREAM it "MUST ignore frames // that it receives on closed streams" for a while, and a trailer // section the peer sent before the reset reached it is one of those // -- the same allowance `onData` makes for DATA. Refusing a stream // over `max_concurrent_streams` is exactly how that happens. The // block is still decoded, because it changed the peer's table. if (header.stream_id <= s.last_peer_stream_id and s.wasRecentlyReset(header.stream_id)) { return s.decodeAndDiscard(); } return s.openStream(header.stream_id, flags.end_stream); } /// Decodes the field block in `field_block` for its effect on the dynamic /// table alone, and drops the fields. fn decodeAndDiscard(s: *Session) ?frame.Fault { var scratch: std.heap.ArenaAllocator = .init(s.gpa); defer scratch.deinit(); var fields: std.ArrayList(Field) = .empty; s.decoder.decode(s.gpa, scratch.allocator(), s.field_block.items, &fields) catch |err| { if (hpack.Decoder.isCompressionError(err)) return .conn(.compression_error); if (err == error.OutOfMemory) return .conn(.internal_error); }; return null; } /// A second field section on a stream that already has one: trailers. /// /// Decoded and thrown away, which is the same decision `http1` makes /// about a chunked body's trailer section and for the same reason — they /// arrive after the handler has usually begun its response, so there is /// nowhere useful to put them. What matters is that the block is decoded /// at all: the peer's dynamic table has already changed and ours has to /// match, or every index after this means something else. fn onTrailers(s: *Session, stream: *Stream, end_stream: bool) ?frame.Fault { if (s.decodeAndDiscard()) |fault| return fault; // §8.1: a trailing field section must end the stream. One that did // not would leave the peer able to send a third, and there is no such // thing. if (!end_stream) return .conn(.protocol_error); stream.remote = .closed; if (stream.content_length) |declared| { if (stream.received != declared) { s.resetStream(stream.id, .protocol_error); return null; } } if (stream.body) |queue| queue.close(s.io); s.closeStreamHalf(stream); return null; } fn appendFragment(s: *Session, len: u24) ?frame.Fault { // Each frame's own header is charged too, so that a flood of empty // CONTINUATION frames reaches the cap rather than running forever. const cost = @as(usize, len) + frame.header_len; if (s.field_block.items.len + cost > s.config.max_field_block_len) { return .conn(.enhance_your_calm); } const dest = s.field_block.addManyAsSlice(s.gpa, len) catch return .conn(.internal_error); s.conn.input.readSliceAll(dest) catch return .conn(.no_error); return null; } fn contentLengthOf(fields: []const Field) ?u64 { for (fields) |f| { if (std.mem.eql(u8, f.name, "content-length")) { return protocol.parseContentLength(f.value); } } return null; } fn openStream(s: *Session, id: u31, end_stream: bool) ?frame.Fault { // §5.1.1: a client's streams are odd, and identifiers only ever // increase. Either rule broken means the two ends disagree about // which streams exist. if (id % 2 == 0 or id <= s.last_peer_stream_id) return .conn(.protocol_error); s.last_peer_stream_id = id; var fields: std.ArrayList(Field) = .empty; var arena_state: std.heap.ArenaAllocator = .init(s.gpa); var keep_arena = false; defer if (!keep_arena) arena_state.deinit(); const arena = arena_state.allocator(); // Decoded whatever happens next, because the peer's dynamic table has // already been changed by this block and ours must match. var over_budget = false; s.decoder.decode(s.gpa, arena, s.field_block.items, &fields) catch |err| { if (hpack.Decoder.isCompressionError(err)) return .conn(.compression_error); if (err == error.OutOfMemory) return .conn(.internal_error); over_budget = true; }; if (s.going_away) return null; if (s.streams_started >= s.config.max_streams) return .conn(.no_error); if (s.outOfResetBudget()) return .conn(.enhance_your_calm); if (s.active_streams >= s.config.max_concurrent_streams) { s.sendReset(id, .refused_stream); return null; } // The request body's queue, before the stream exists, and this // ordering is load-bearing. `arena_state` is *copied* into the stream // below, and `arena` is an interface pointing at this function's // local — so an allocation made through it after the copy is recorded // in a copy that nobody ever deinits, and leaks. Everything the arena // is asked for on the reader's side has to be asked for before the // copy; after it, the arena to use is `stream.arena`. var body_buf: []u8 = &.{}; var body_queue: ?*Io.Queue(u8) = null; if (!end_stream) { body_buf = s.gpa.alloc(u8, s.config.stream_receive_window) catch return .conn(.internal_error); const queue = arena.create(Io.Queue(u8)) catch { s.gpa.free(body_buf); return .conn(.internal_error); }; queue.* = .init(body_buf); body_queue = queue; } const stream = s.gpa.create(Stream) catch { if (body_buf.len != 0) s.gpa.free(body_buf); return .conn(.internal_error); }; // Sized to the largest DATA frame the peer will accept, so that small // writes coalesce into one frame instead of one frame each. const write_buf = s.gpa.alloc(u8, s.config.max_frame_size) catch { if (body_buf.len != 0) s.gpa.free(body_buf); s.gpa.destroy(stream); return .conn(.internal_error); }; stream.* = .{ .session = s, .id = id, .arena = arena_state, .fields = fields, .refs = .init(2), .remote = if (end_stream) .closed else .open, .local = .idle, .reset = .init(false), .send_window = s.peer_initial_window, .content_length = contentLengthOf(fields.items), .received = 0, .body = body_queue, .body_buf = body_buf, .write_buf = write_buf, .body_reader = undefined, .body_writer = undefined, .answered = false, .connect_protocol = null, .too_large = over_budget, .end_stream_sent = false, .method_has_body = true, .halves_done = .init(0), }; keep_arena = true; s.streams_mutex.lockUncancelable(s.io); s.streams.put(s.gpa, id, stream) catch { s.streams_mutex.unlock(s.io); stream.release(s.gpa); return .conn(.internal_error); }; s.active_streams += 1; s.streams_started += 1; s.streams_mutex.unlock(s.io); s.last_processed_stream_id = id; // A request actually dispatched is the thing this connection is for. s.credit(4); // A request whose HEADERS carried END_STREAM has nothing more coming, // so the reader is already done with it. Without this the stream // stays in the table for ever, `active_streams` never falls, and the // connection silently stops accepting new streams after // `max_concurrent_streams` of them — which looks exactly like a // client being throttled and is in fact a leak. if (end_stream) s.closeStreamHalf(stream); s.tasks.concurrent(s.io, Stream.run, .{stream}) catch |err| switch (err) { // REFUSED_STREAM means "nothing happened, try elsewhere", which // is exactly true and is the only honest answer when this `Io` // cannot give us a task. It must not be run inline: a handler // reading its body on the reader's task waits for frames only // that task can deliver. error.ConcurrencyUnavailable => { s.sendReset(id, .refused_stream); s.closeStreamHalf(stream); stream.release(s.gpa); return null; }, }; return null; } fn onData(s: *Session, header: frame.Header) ?frame.Fault { const flags = frame.DataFlags.from(header.flags); var payload_left = header.length; var pad_len: u8 = 0; if (flags.padded) { if (payload_left == 0) return .conn(.protocol_error); pad_len = s.conn.input.takeByte() catch return .conn(.no_error); payload_left -= 1; } if (pad_len > payload_left) return .conn(.protocol_error); const data_len = payload_left - pad_len; // §6.9.1: the whole frame counts against the connection window, // padding included, whatever becomes of the octets. if (s.chargeConnectionWindow(header.length)) |fault| return fault; s.streams_mutex.lockUncancelable(s.io); const stream = s.streams.get(header.stream_id); s.streams_mutex.unlock(s.io); if (stream) |st| { if (st.remote == .closed) { s.conn.input.discardAll(header.length) catch return .conn(.no_error); s.sendReset(header.stream_id, .stream_closed); return null; } if (s.routeData(st, data_len)) |fault| return fault; s.conn.input.discardAll(pad_len) catch return .conn(.no_error); // §6.9.1: the padding counted against the stream window as well, // and nothing else would ever give it back. if (s.creditPadding(st, header.length - data_len)) |fault| return fault; if (data_len == 0) { if (s.charge(1)) |fault| return fault; } else { s.credit(4); } st.received += data_len; if (st.content_length) |declared| { // More than was promised, which is knowable before the end. if (st.received > declared) { s.resetStream(header.stream_id, .protocol_error); return null; } } if (flags.end_stream) { st.remote = .closed; if (st.content_length) |declared| { if (st.received != declared) { s.resetStream(header.stream_id, .protocol_error); return null; } } if (st.body) |queue| queue.close(s.io); s.closeStreamHalf(st); } return null; } // §5.1. DATA for a stream that was never opened is a connection // error; for one this server reset, it was in flight when the // RST_STREAM went out and is tolerated; for one the peer itself // ended, there is nothing in flight to excuse it. if (header.stream_id > s.last_peer_stream_id) return .conn(.protocol_error); s.conn.input.discardAll(header.length) catch return .conn(.no_error); if (!s.wasRecentlyReset(header.stream_id)) return .conn(.stream_closed); return null; } /// Gives the stream window back what padding took from it, at half the /// window as `BodyReader.credit` does, so a stream of padded frames costs /// one WINDOW_UPDATE per half window rather than one per frame. fn creditPadding(s: *Session, stream: *Stream, overhead: u24) ?frame.Fault { if (overhead == 0) return null; stream.padding_pending += @intCast(overhead); if (stream.padding_pending < s.config.stream_receive_window / 2) return null; const amount = stream.padding_pending; stream.padding_pending = 0; var payload: [4]u8 = undefined; std.mem.writeInt(u32, &payload, amount, .big); s.writer.sendControl(.{ .length = 4, .type = .window_update, .flags = 0, .stream_id = stream.id, }, &payload) catch |err| return switch (err) { error.OutboxFull => .conn(.enhance_your_calm), else => .conn(.no_error), }; return null; } fn routeData(s: *Session, stream: *Stream, len: u24) ?frame.Fault { var left = len; var chunk: [4096]u8 = undefined; while (left > 0) { const take = @min(left, chunk.len); s.conn.input.readSliceAll(chunk[0..take]) catch return .conn(.no_error); left -= @intCast(take); const queue = stream.body orelse continue; // Never blocks: the stream's receive window is exactly this // queue's capacity, so whatever the peer was allowed to send // fits. A short put means our accounting and the peer's have // diverged. const put = queue.put(s.io, chunk[0..take], 0) catch continue; if (put < take) return .conn(.flow_control_error); } return null; } fn chargeConnectionWindow(s: *Session, len: u24) ?frame.Fault { s.fc_mutex.lockUncancelable(s.io); defer s.fc_mutex.unlock(s.io); s.recv_window -= @intCast(len); if (s.recv_window < 0) return .conn(.flow_control_error); s.recv_pending += @intCast(len); // Replenished on routing rather than on consumption; see `Config`. if (s.recv_pending >= s.config.connection_receive_window / 2) { const amount = s.recv_pending; s.recv_pending = 0; s.recv_window += amount; var payload: [4]u8 = undefined; std.mem.writeInt(u32, &payload, amount, .big); s.writer.sendControl(.{ .length = 4, .type = .window_update, .flags = 0, .stream_id = 0, }, &payload) catch |err| return switch (err) { error.OutboxFull => .conn(.enhance_your_calm), else => .conn(.no_error), }; } return null; } /// Records that this stream is being reset, and says whether this is the /// first time. /// /// Locked because both tasks reach it: the reader resets a stream the /// peer got wrong, and the stream task resets one whose handler failed /// after the head had gone. fn claimReset(s: *Session, id: u31) bool { s.reset_mutex.lockUncancelable(s.io); defer s.reset_mutex.unlock(s.io); for (s.recently_reset) |seen| { if (seen == id and id != 0) return false; } s.recently_reset[s.recently_reset_next] = id; s.recently_reset_next = (s.recently_reset_next + 1) % @as(u8, s.recently_reset.len); return true; } fn wasRecentlyReset(s: *Session, id: u31) bool { s.reset_mutex.lockUncancelable(s.io); defer s.reset_mutex.unlock(s.io); for (s.recently_reset) |seen| { if (seen == id and id != 0) return true; } return false; } fn sendReset(s: *Session, id: u31, code: frame.ErrorCode) void { // One complaint per stream. A second RST_STREAM names a stream this // server has already closed, and a frame on a closed stream is // itself something the peer may treat as an error -- so a duplicate // turns one complaint into two problems. Identifiers are never // reused, so "already reset" is true for the rest of the connection. // // This is also the reason the memory of resets is kept under a lock // of its own: the reader task and a stream task can both decide to // reset the same stream at the same moment, which is exactly the case // being suppressed, and it is a data race on the ring as well. if (!s.claimReset(id)) return; var payload: [4]u8 = undefined; std.mem.writeInt(u32, &payload, @backingInt(code), .big); s.writer.sendControl(.{ .length = 4, .type = .rst_stream, .flags = 0, .stream_id = id, }, &payload) catch {}; } /// Tells a stream to stop, from the reader task. fn resetStream(s: *Session, id: u31, code: frame.ErrorCode) void { s.sendReset(id, code); s.finishStream(id, code); } fn finishStream(s: *Session, id: u31, code: frame.ErrorCode) void { s.streams_mutex.lockUncancelable(s.io); const stream = s.streams.get(id); s.streams_mutex.unlock(s.io); const st = stream orelse return; _ = code; st.reset.store(true, .release); st.abort(s.io); st.remote = .closed; s.closeStreamHalf(st); } /// One of a stream's two halves is done with. The last one out removes it /// from the table. /// One of a stream's two halves is finished with: the reader's, when the /// peer has sent everything it is going to, and the stream task's, when /// the handler has returned. The second one out removes the stream. /// /// Exactly two, and the `!= 2` is load-bearing: a stream can be told to /// finish twice — END_STREAM closes the reader's half and a RST_STREAM /// arriving behind it would close it again — and acting on the third call /// would release the stream a second time. fn closeStreamHalf(s: *Session, stream: *Stream) void { if (stream.halves_done.fetchAdd(1, .acq_rel) + 1 != 2) return; s.streams_mutex.lockUncancelable(s.io); if (s.streams.fetchRemove(stream.id)) |_| { s.active_streams -= 1; // A stream that ran to completion without being cancelled gives // a token back, so ordinary traffic keeps the budget full and // only a run of cancellations drains it. if (stream.answered and !stream.reset.load(.acquire)) { s.reset_budget = @min(s.reset_budget + 1, s.config.reset_budget); } } s.streams_mutex.unlock(s.io); stream.release(s.gpa); } /// Whether the connection has been cancelled at more than it has served. fn outOfResetBudget(s: *Session) bool { s.streams_mutex.lockUncancelable(s.io); defer s.streams_mutex.unlock(s.io); return s.reset_budget == 0; } }; /// One request in flight. const Stream = struct { session: *Session, id: u31, /// Never reset. Everything the request and the response point at lives /// here until the last reference goes. arena: std.heap.ArenaAllocator, fields: std.ArrayList(Field), refs: std.atomic.Value(u8), /// What the peer may still send. Written only by the reader task. remote: enum { idle, open, closed }, /// What we may still send. Written only by this stream's task. local: enum { idle, headers_sent, closed }, reset: std.atomic.Value(bool), send_window: i32, body: ?*Io.Queue(u8), body_buf: []u8, write_buf: []u8, body_reader: BodyReader, body_writer: BodyWriter, /// What `content-length` said, if anything, and how much has arrived. /// §8.1.2.6 makes a mismatch a stream error, and it has to be checked /// here rather than in the handler because the handler may never read the /// body at all. content_length: ?u64, received: u64, /// Padding and pad-length octets received but not yet credited back to /// the stream window. The reader task's alone: these octets never reach /// the queue, so the handler draining it never gives them back. padding_pending: u31 = 0, answered: bool, end_stream_sent: bool, /// The `:protocol` of an RFC 8441 extended CONNECT, kept because /// `upgrade` is reached through the response and has no other way back to /// the request. connect_protocol: ?[]const u8, /// Whether this request's field section was larger than /// `SETTINGS_MAX_HEADER_LIST_SIZE`, in which case the field list is /// short of whatever did not fit and the handler never sees it. too_large: bool, /// Whether a response to this request carries octets. A `HEAD` declares /// the length the matching `GET` would have had and sends none of it. method_has_body: bool, halves_done: std.atomic.Value(u8), /// §10.1.1 of RFC 9110: the client is holding its content back until it /// is asked for, and the first read of the body asks -- the same rule /// the HTTP/1.1 driver follows. Written only by this stream's task. expect_continue: bool = false, continue_sent: bool = false, fn release(stream: *Stream, gpa: Allocator) void { if (stream.refs.fetchSub(1, .acq_rel) > 1) return; if (stream.body_buf.len != 0) gpa.free(stream.body_buf); if (stream.write_buf.len != 0) gpa.free(stream.write_buf); stream.arena.deinit(); gpa.destroy(stream); } /// Wakes anything this stream has blocked, so that its task can unwind. fn abort(stream: *Stream, io: Io) void { stream.reset.store(true, .release); if (stream.body) |queue| queue.close(io); } /// The half of `abort` that is not a failure: the request body is over, /// and the handler may still answer. Closing a queue twice is harmless — /// it sets a flag — which matters because END_STREAM has usually closed /// this one already. fn endInput(stream: *Stream, io: Io) void { if (stream.body) |queue| queue.close(io); } fn run(stream: *Stream) void { const s = stream.session; defer { s.closeStreamHalf(stream); stream.release(s.gpa); } stream.body_reader = .{ .interface = .{ .vtable = &.{ .stream = BodyReader.streamImpl, .discard = BodyReader.discardImpl }, .buffer = &.{}, .seek = 0, .end = 0, }, .stream = stream, .finished = stream.body == null, }; stream.body_writer = .{ .interface = .{ .vtable = &BodyWriter.vtable, .buffer = &.{} }, .stream = stream, .mode = .discard, .remaining = 0, }; // §10.5.1: too large a field section is one request's problem, and // the answer is a status rather than a reset. RST_STREAM with // REFUSED_STREAM would be the easy thing to send and would be a lie // -- it means "nothing happened here, try another connection", and a // client that believed it would send the same oversized request // again and get the same answer forever. The block was decoded in // full above whatever happened, so the dynamic table is in step and // the connection carries on. if (stream.too_large) { stream.respondStatus(.request_header_fields_too_large); return; } var req = request_builder.build( s.io, stream.arena.allocator(), &stream.fields, s.conn.info, body: { const plain: Request.Body = .{ .reader = &stream.body_reader.interface, .length = if (stream.body == null) .none else .unknown, }; const decoding = s.config.request_decoding orelse break :body plain; // §8.4: undone before the handler, when asked. A failure here // resets the stream rather than handing over coded octets a // handler was told would be decoded. const decoded = compression.decodeRequest( stream.arena.allocator(), decoding, protocol.Headers.initBorrowed(stream.fields.items).get("content-encoding"), plain.reader, plain.length, ) catch { stream.resetFromTask(.internal_error); return; }; break :body .{ .reader = decoded.reader, .length = decoded.length }; }, .{ .extended_connect = s.config.enable_connect_protocol }, ) catch |err| { switch (err) { error.Malformed => stream.resetFromTask(.protocol_error), error.NotImplemented => stream.respondStatus(.not_implemented), error.OutOfMemory => stream.resetFromTask(.internal_error), } return; }; stream.method_has_body = req.method.responseHasBody(); stream.connect_protocol = req.connect_protocol; // §15.5.14 of RFC 9110, and before the handler or a `100 Continue`: // a body this server will not read is not one to ask for. if (stream.content_length) |declared| if (declared > s.config.max_body_len orelse std.math.maxInt(u64)) { stream.refuseBody(); return; }; if (req.headers.get("expect")) |expect| { if (!token.containsToken(expect, "100-continue")) { // §10.1.1 of RFC 9110: an expectation that is not understood // is refused rather than ignored, as over HTTP/1.1. stream.respondStatus(.expectation_failed); return; } // Only while there is content still to come: END_STREAM on the // HEADERS left nothing held back to ask for. stream.expect_continue = stream.body != null; } var res: Response = .{ .headers = .empty, .arena = stream.arena.allocator(), .version = .http_2, .context = stream, .vtable = &response_vtable, .accept_encoding = req.headers.get("accept-encoding"), .compress = s.config.compression, }; s.handler.serve(&req, &res) catch |err| { log.debug("handler failed for {s} {s}: {s}", .{ req.method.name, req.target.raw, @errorName(err), }); if (res.state == .head) { // The body ran past `max_body_len`, which is what the // handler is reporting. if (stream.body_reader.tooLarge()) { stream.refuseBody(); } else { stream.respondStatus(.internal_server_error); } } else { // The head is already out saying how long the body would be. // One RST_STREAM ends this request and leaves every other // stream on the connection alone -- which is the thing // HTTP/1.1 cannot do, where the only option is to close. stream.resetFromTask(.internal_error); } return; }; switch (res.state) { // A handler that read past the limit and let the failure go has // not answered the request it was given, so the limit does. .head => if (stream.body_reader.tooLarge()) stream.refuseBody() else res.send("") catch {}, // A body short of its declared length fails here, without // END_STREAM. §8.1.1 makes the response malformed, and the // client has to be told rather than left waiting on a stream // that will never end, so it is reset the way a handler failure // is. .body => res.end() catch stream.resetFromTask(.internal_error), .ended => {}, // RFC 8441 §5: "Orderly TCP-level closures are represented as // END_STREAM flags." The handler has stopped speaking whatever it // was speaking, so the tunnel closes the way a socket would. .upgraded => stream.body_writer.finish() catch {}, } } fn methodHasResponseBody(stream: *const Stream) bool { return stream.method_has_body; } /// The buffer a response body is written through. /// /// Sized so that small writes coalesce into one DATA frame, and no larger /// than what the peer said it would accept. fn writeBuffer(stream: *Stream) []u8 { const limit = @min(stream.write_buf.len, stream.session.peer.max_frame_size); return stream.write_buf[0..limit]; } /// RFC 9113 §8.1: the trailer section, which is a second field block with /// END_STREAM on it. /// /// "An HTTP request or response... can optionally include a trailer /// section... sent as a HEADERS frame with the END_STREAM flag set", and /// that is the whole of it -- no chunked coding to arrange, no terminator /// to split in two, because a field section is already the shape HTTP/2 /// sends everything in. What HTTP/1.1 needs §7.1.2 for costs nothing /// here. /// /// Sent before the body writer finishes, because the writer's last act is /// to put END_STREAM on an empty DATA frame -- and a trailer section /// after the end of the stream is on a stream that has closed. fn sendTrailers(stream: *Stream, res: *Response) Response.Error!void { if (res.trailers.fields.items.len == 0) return; if (stream.end_stream_sent) return; var fields: std.ArrayList(Field) = .empty; for (res.trailers.fields.items) |f| { // §6.5.1 of RFC 9110, and §8.1's own rule that a trailer section // carries no pseudo-headers -- it is not a message head and has // no status to give. if (Response.isForbiddenTrailer(f.name)) continue; if (f.name.len > 0 and f.name[0] == ':') continue; fields.append(res.arena, .{ .name = f.name, .value = f.value }) catch return error.OutOfMemory; } if (fields.items.len == 0) return; try stream.sendFieldBlock(fields.items, true); stream.end_stream_sent = true; } /// A field block as HEADERS plus however many CONTINUATION frames the /// peer's maximum frame size requires, all under one hold of the /// serializer: §6.2 forbids any other frame between them, and a block /// interrupted half way leaves the peer's HPACK decoder permanently out /// of step with ours. fn sendFieldBlock(stream: *Stream, fields: []const Field, end_stream: bool) Response.Error!void { const s = stream.session; var encoded: std.ArrayList(u8) = .empty; defer encoded.deinit(s.gpa); var w: Io.Writer.Allocating = .fromArrayList(s.gpa, &encoded); defer encoded = w.toArrayList(); s.encoder.encode(&w.writer, fields) catch return error.OutOfMemory; const block = w.written(); const max = @as(usize, s.peer.max_frame_size); const out = s.writer.acquire() catch |err| return switch (err) { error.Canceled => error.WriteFailed, error.WriteFailed => error.WriteFailed, }; defer s.writer.release(); var offset: usize = 0; var first = true; while (true) { const take = @min(max, block.len - offset); const last = offset + take == block.len; const header: frame.Header = if (first) .{ .length = @intCast(take), .type = .headers, .flags = (frame.HeadersFlags{ .end_stream = end_stream, .end_headers = last, }).toInt(), .stream_id = stream.id, } else .{ .length = @intCast(take), .type = .continuation, .flags = (frame.ContinuationFlags{ .end_headers = last }).toInt(), .stream_id = stream.id, }; header.writeTo(out) catch return error.WriteFailed; out.writeAll(block[offset..][0..take]) catch return error.WriteFailed; offset += take; first = false; if (last) break; } } /// Reserves send-window credit, blocking until there is some. /// /// Credit is taken under the lock and spent outside it, so two streams /// never serialise on `fc_mutex` across a socket write. fn reserve(stream: *Stream, want: usize) BodyWriter.Fault!u31 { const s = stream.session; s.fc_mutex.lock(s.io) catch { s.io.recancel(); return error.Canceled; }; defer s.fc_mutex.unlock(s.io); while (true) { if (stream.reset.load(.acquire)) return error.StreamReset; if (s.dead) return error.ConnectionLost; const available = @min(s.send_window, stream.send_window); if (available > 0) { const n: u31 = @intCast(@min(@min(want, @as(usize, @intCast(available))), s.peer.max_frame_size)); s.send_window -= n; stream.send_window -= n; return n; } // Credit is checked before this, not after, because a peer that // has stopped sending may still be reading: what is already // granted is still spendable, and only the waiting is pointless. if (s.input_ended) return error.ConnectionLost; s.fc_cond.wait(s.io, &s.fc_mutex) catch { s.io.recancel(); return error.Canceled; }; } } /// RST_STREAM from this stream's task, after its handler is done with it, /// and the reader's half queued for closing; see `Session.retiring`. fn resetFromTask(stream: *Stream, code: frame.ErrorCode) void { const s = stream.session; s.sendReset(stream.id, code); s.streams_mutex.lockUncancelable(s.io); defer s.streams_mutex.unlock(s.io); // Without the room, the stream holds its slot until the connection // ends, which is what it did before this existed. s.retiring.append(s.gpa, stream.id) catch {}; } /// §8.1 of RFC 9113: "A server can send a complete response prior to the /// client sending an entire request", and "MAY request that the client /// abort transmission of a request without error by sending a RST_STREAM /// with an error code of NO_ERROR after sending a complete response". /// Here the response is a `413`. fn refuseBody(stream: *Stream) void { stream.respondStatus(.payload_too_large); stream.resetFromTask(.no_error); } fn respondStatus(stream: *Stream, status: Status) void { var res: Response = .{ .status = status, .headers = .empty, .arena = stream.arena.allocator(), .version = .http_2, .context = stream, .vtable = &response_vtable, }; res.sendStatus(status) catch {}; } }; const response_vtable: Response.VTable = .{ .beginBody = beginBody, .end = endBody, .sendInterim = sendInterim, // RFC 8441's extended CONNECT, which is what HTTP/2 has instead of // `Upgrade`. It refuses with `UpgradeUnavailable` when the setting that // enables it has not been advertised, so a handler falls back to `426` // exactly as it would against a client that never offered. .upgrade = upgrade, }; /// RFC 8441's half of `Response.upgrade`. /// /// Where HTTP/1.1 sends `101` and then stops speaking HTTP on the whole /// connection, this sends `200` and stops speaking HTTP on **one stream**. /// Every other stream carries on, which is the thing the HTTP/1.1 mechanism /// cannot do at all: there, an upgraded connection is spent. fn upgrade(res: *Response, protocol_name: []const u8) Response.UpgradeError!Response.Upgrade { const stream: *Stream = @ptrCast(@alignCast(res.context.?)); const s = stream.session; if (!s.config.enable_connect_protocol) return error.UpgradeUnavailable; // RFC 9110 §7.8's rule, which RFC 8441 inherits with a different spelling: // a server may not switch to a protocol the client did not ask for. Here // the asking is `:protocol` rather than an `Upgrade` field. const offered = stream.connect_protocol orelse return error.NotOffered; if (!protocol.token.eqlIgnoreCase(offered, protocol_name)) return error.NotOffered; // No `BodyNotConsumed` check, and its absence is the point. Over HTTP/1.1 // an unread request body sits in the byte stream in front of the new // protocol's first octet, so handing the stream over would corrupt it. // Here the request body *is* the tunnel: DATA frames are framed // separately, nothing is in front of anything, and a WebSocket client // that sent its first frame immediately is holding exactly the octets the // handler is about to want. var fields: std.ArrayList(Field) = .empty; const arena = res.arena; // `200`, not `101`. RFC 8441 §5.1's example, and there is nothing to // switch: the stream becomes the tunnel the moment a 2xx goes out. The // driver picks it rather than the handler, the same way the HTTP/1.1 side // picks `101`. fields.append(arena, .{ .name = ":status", .value = "200" }) catch return error.OutOfMemory; if (!res.headers.has("date")) { if (s.config.send_date) { const now = Io.Clock.real.now(s.io); const seconds: i64 = @intCast(@divFloor(now.nanoseconds, std.time.ns_per_s)); var buf: [protocol.date.imf_len]u8 = undefined; if (protocol.date.formatImf(&buf, seconds)) |formatted| { const owned = arena.dupe(u8, formatted) catch return error.OutOfMemory; fields.append(arena, .{ .name = "date", .value = owned }) catch return error.OutOfMemory; } else |_| {} } } if (!res.headers.has("server")) { if (s.config.server_name) |name| { fields.append(arena, .{ .name = "server", .value = name }) catch return error.OutOfMemory; } } // Whatever the handler set goes out — which for a WebSocket is // `sec-websocket-protocol`, the subprotocol it picked. `isDriverField` // still refuses the hop-by-hop names, which RFC 8441 §5 says MUST NOT // appear here anyway. for (res.headers.fields.items) |field| { if (isDriverField(field.name)) continue; if (field.name.len != 0 and field.name[0] == ':') continue; fields.append(arena, field) catch return error.OutOfMemory; } // END_STREAM clear, or there would be no tunnel to speak into. try stream.sendFieldBlock(fields.items, false); stream.local = .headers_sent; stream.answered = true; // A body of no particular length, which is what a tunnel is. stream.body_writer.mode = .unknown; stream.body_writer.remaining = 0; stream.body_writer.interface.buffer = stream.writeBuffer(); stream.body_writer.interface.end = 0; return .{ .input = &stream.body_reader.interface, .output = &stream.body_writer.interface, }; } fn beginBody(res: *Response, length: Length) Response.Error!*Io.Writer { const stream: *Stream = @ptrCast(@alignCast(res.context.?)); const s = stream.session; const allows_body = Response.statusAllowsBody(res.status); const emits_body = allows_body and stream.methodHasResponseBody(); const declared: Length = if (allows_body or res.status == .not_modified) length else .none; var fields: std.ArrayList(Field) = .empty; const arena = res.arena; var status_buf: [3]u8 = undefined; const status_text = std.fmt.bufPrint(&status_buf, "{d}", .{@backingInt(res.status)}) catch return error.WriteFailed; // §8.3.2: `:status` is the only response pseudo-header, and it comes // first. fields.append(arena, .{ .name = ":status", .value = status_text }) catch return error.OutOfMemory; switch (declared) { .none => if (allows_body) { fields.append(arena, .{ .name = "content-length", .value = "0" }) catch return error.OutOfMemory; }, .exact => |n| { const text = std.fmt.allocPrint(arena, "{d}", .{n}) catch return error.OutOfMemory; fields.append(arena, .{ .name = "content-length", .value = text }) catch return error.OutOfMemory; }, // Nothing special at all: no `content-length`, just DATA frames. This // is the case `Length` exists for. .unknown => {}, } if (!res.headers.has("date")) { if (s.config.send_date) { const now = Io.Clock.real.now(s.io); const seconds: i64 = @intCast(@divFloor(now.nanoseconds, std.time.ns_per_s)); var buf: [protocol.date.imf_len]u8 = undefined; if (protocol.date.formatImf(&buf, seconds)) |formatted| { const owned = arena.dupe(u8, formatted) catch return error.OutOfMemory; fields.append(arena, .{ .name = "date", .value = owned }) catch return error.OutOfMemory; } else |_| {} } } if (!res.headers.has("server")) { if (s.config.server_name) |name| { fields.append(arena, .{ .name = "server", .value = name }) catch return error.OutOfMemory; } } for (res.headers.fields.items) |field| { if (isDriverField(field.name)) continue; // A handler cannot set one through `setHeader`, but // `appendAssumeValid` would let one through, and a `:` name in a // response field section is malformed. if (field.name.len != 0 and field.name[0] == ':') continue; fields.append(arena, field) catch return error.OutOfMemory; } const end_stream = !emits_body or declared == .none; try stream.sendFieldBlock(fields.items, end_stream); if (end_stream) stream.end_stream_sent = true; stream.local = .headers_sent; stream.answered = true; stream.body_writer.mode = if (!emits_body) .discard else switch (declared) { .none => .discard, .exact => .exact, .unknown => .unknown, }; stream.body_writer.remaining = switch (declared) { .exact => |n| n, else => 0, }; stream.body_writer.interface.buffer = stream.writeBuffer(); stream.body_writer.interface.end = 0; return &stream.body_writer.interface; } fn endBody(res: *Response) Response.Error!void { const stream: *Stream = @ptrCast(@alignCast(res.context.?)); // Flushed before the trailers, not after. What the handler wrote is // still in the writer's buffer until this call, so sending the trailer // section first would put it *in front of* the last of the body -- which // is a stream whose field section arrives before the content it // describes, and which a peer reads as a second response head. stream.body_writer.interface.flush() catch return error.WriteFailed; try stream.sendTrailers(res); try stream.body_writer.finish(); stream.local = .closed; } fn sendInterim(res: *Response, status: Status, headers: *const Headers) Response.Error!void { const stream: *Stream = @ptrCast(@alignCast(res.context.?)); const arena = res.arena; var fields: std.ArrayList(Field) = .empty; var status_buf: [3]u8 = undefined; const text = std.fmt.bufPrint(&status_buf, "{d}", .{@backingInt(status)}) catch return error.WriteFailed; fields.append(arena, .{ .name = ":status", .value = text }) catch return error.OutOfMemory; for (headers.fields.items) |field| { if (isDriverField(field.name)) continue; fields.append(arena, field) catch return error.OutOfMemory; } // A handler that sends its own `100` has answered the expectation, and // the body reader is not to send a second. if (status == .@"continue") stream.continue_sent = true; // §8.1: an interim response is a HEADERS frame with no END_STREAM, and // unlike HTTP/1.0 there is no version that cannot understand one. return stream.sendFieldBlock(fields.items, false); } /// The fields this driver writes for itself, plus the ones HTTP/2 forbids /// outright. A handler that sets one is overruled. fn isDriverField(name: []const u8) bool { const managed = [_][]const u8{ "content-length", "transfer-encoding", "connection", "keep-alive", "upgrade", "proxy-connection", }; for (managed) |m| { if (token.eqlIgnoreCase(name, m)) return true; } return false; } test { std.testing.refAllDecls(@This()); } /// The request body, delivered from the reader task through a bounded queue. /// /// The queue's capacity *is* the stream's receive window, which is what lets /// the reader route DATA without ever blocking: whatever the peer was allowed /// to send fits by construction. Credit goes back to the peer as the handler /// drains it, so flow control is the backpressure rather than something /// bolted beside it. const BodyReader = struct { interface: Io.Reader, stream: *Stream, finished: bool = false, /// Consumed but not yet credited back. pending: u31 = 0, /// How much has been handed to the handler, against /// `Config.max_body_len`. received: u64 = 0, err: ?Fault = null, const Fault = error{ /// The peer reset the stream while the handler was reading. StreamReset, /// The connection is gone. ConnectionLost, Canceled, /// The body ran past `Config.max_body_len`. BodyTooLarge, }; fn tooLarge(b: *const BodyReader) bool { const err = b.err orelse return false; return err == error.BodyTooLarge; } fn streamImpl(r: *Io.Reader, w: *Io.Writer, limit: Io.Limit) Io.Reader.StreamError!usize { const b: *BodyReader = @alignCast(@fieldParentPtr("interface", r)); if (b.finished) return error.EndOfStream; const stream = b.stream; const s = stream.session; const queue = stream.body orelse { b.finished = true; return error.EndOfStream; }; // §10.1.1 of RFC 9110: the client is waiting to be asked, and this is // the asking. Not once the head is out: a response already on its // way answers the expectation by itself. if (stream.expect_continue and !stream.continue_sent and stream.local == .idle) { stream.continue_sent = true; stream.sendFieldBlock(&.{.{ .name = ":status", .value = "100" }}, false) catch { b.err = error.ConnectionLost; return error.ReadFailed; }; } const dest = limit.slice(try w.writableSliceGreedy(1)); const n = queue.get(s.io, dest, 1) catch |err| switch (err) { // The queue closes on END_STREAM and on a reset; which it was is // the difference between a body that ended and one that was cut // off, and only the flag says. error.Closed => { b.finished = true; if (stream.reset.load(.acquire)) { b.err = error.StreamReset; return error.ReadFailed; } return error.EndOfStream; }, error.Canceled => { s.io.recancel(); b.err = error.Canceled; return error.ReadFailed; }, }; // Refused before the excess reaches the handler. if (b.received + n > s.config.max_body_len orelse std.math.maxInt(u64)) { b.finished = true; b.err = error.BodyTooLarge; return error.ReadFailed; } b.received += n; w.advance(n); b.credit(@intCast(n)); return n; } /// `Io.Reader`'s own discard streams into a writer with no buffer, and /// `streamImpl` copies out of the queue into the writer's buffer -- so /// without this, `discardRemaining` on a request body was an assertion /// failure. Read through a scratch buffer instead. fn discardImpl(r: *Io.Reader, limit: Io.Limit) Io.Reader.Error!usize { var scratch: [4096]u8 = undefined; var w: Io.Writer = .fixed(&scratch); return streamImpl(r, &w, limit.min(.limited(scratch.len))) catch |err| switch (err) { // A fixed writer of this size always has room for what was asked. error.WriteFailed => unreachable, else => |e| e, }; } /// Gives window credit back as the handler consumes. /// /// At half the window, which is the threshold that is provably live: the /// peer only stalls once it has sent a whole window, so a handler reading /// that far has already crossed the halfway mark and released credit. fn credit(b: *BodyReader, n: u31) void { const s = b.stream.session; b.pending += n; if (b.pending < s.config.stream_receive_window / 2) return; const amount = b.pending; b.pending = 0; var payload: [4]u8 = undefined; std.mem.writeInt(u32, &payload, amount, .big); s.writer.sendControl(.{ .length = 4, .type = .window_update, .flags = 0, .stream_id = b.stream.id, }, &payload) catch {}; } }; /// The response body, as DATA frames. const BodyWriter = struct { interface: Io.Writer, stream: *Stream, mode: Mode, /// `.exact` only: how many octets are still owed. When a chunk brings /// this to zero the chunk carries END_STREAM, so a declared-length body /// costs no extra frame to end. remaining: u64, err: ?Fault = null, const Mode = enum { /// A `HEAD`, or a status that may not carry a body: the length was /// declared and the octets are dropped. discard, /// Held to the declared length. exact, /// However many get written; END_STREAM goes on the last frame. unknown, }; const Fault = error{ StreamReset, ConnectionLost, /// The handler wrote more than the length it declared. LengthMismatch, Canceled, }; const vtable: Io.Writer.VTable = .{ .drain = drain }; fn drain(w: *Io.Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize { const b: *BodyWriter = @alignCast(@fieldParentPtr("interface", w)); const buffered = w.buffered(); const from_data = Io.Writer.countSplat(data, splat); const total = buffered.len + from_data; switch (b.mode) { .discard => {}, .exact, .unknown => { if (b.mode == .exact and total > b.remaining) { b.err = error.LengthMismatch; return error.WriteFailed; } if (total != 0) try b.emit(buffered, data, splat, total); }, } if (b.mode == .exact) b.remaining -= total; w.end = 0; return from_data; } /// Splits `total` octets across DATA frames no larger than the peer's /// maximum and no larger than the window allows, blocking for credit. fn emit( b: *BodyWriter, buffered: []const u8, data: []const []const u8, splat: usize, total: usize, ) Io.Writer.Error!void { var pieces: Pieces = .{ .buffered = buffered, .data = data, .splat = splat }; // `remaining` is what was still owed before this drain, so a declared // body finishes here exactly when the two are equal. END_STREAM then // rides the last frame and the body costs no extra one to end. const finishes = b.mode == .exact and b.remaining == total; var left = total; while (left > 0) { const credit = b.stream.reserve(left) catch |err| { b.err = err; return error.WriteFailed; }; const take = @min(left, @as(usize, credit)); left -= take; try b.writeFrame(&pieces, take, finishes and left == 0); // Credit taken but not spent is given back, or the window leaks. if (credit > take) b.refund(credit - @as(u31, @intCast(take))); } } fn refund(b: *BodyWriter, amount: u31) void { const s = b.stream.session; s.fc_mutex.lockUncancelable(s.io); s.send_window += amount; b.stream.send_window += amount; s.fc_mutex.unlock(s.io); s.fc_cond.broadcast(s.io); } fn writeFrame(b: *BodyWriter, pieces: *Pieces, len: usize, end_stream: bool) Io.Writer.Error!void { const s = b.stream.session; const out = s.writer.acquire() catch { b.err = error.ConnectionLost; return error.WriteFailed; }; defer s.writer.release(); (frame.Header{ .length = @intCast(len), .type = .data, .flags = (frame.DataFlags{ .end_stream = end_stream }).toInt(), .stream_id = b.stream.id, }).writeTo(out) catch { b.err = error.ConnectionLost; return error.WriteFailed; }; pieces.writeTo(out, len) catch { b.err = error.ConnectionLost; return error.WriteFailed; }; if (end_stream) b.stream.end_stream_sent = true; } /// Walks the buffered octets and then each slice of a drain's `data`, /// handing out runs of a requested length without copying any of it. const Pieces = struct { buffered: []const u8, data: []const []const u8, splat: usize, index: usize = 0, offset: usize = 0, splat_done: usize = 0, fn writeTo(p: *Pieces, out: *Io.Writer, want: usize) Io.Writer.Error!void { var left = want; while (left > 0) { const piece = p.current() orelse return; const take = @min(left, piece.len - p.offset); try out.writeAll(piece[p.offset..][0..take]); p.offset += take; left -= take; if (p.offset == piece.len) { p.offset = 0; p.advance(); } } } fn current(p: *Pieces) ?[]const u8 { if (p.index == 0) return if (p.buffered.len != 0) p.buffered else blk: { p.index = 1; break :blk p.current(); }; const i = p.index - 1; if (i >= p.data.len) return null; if (i == p.data.len - 1 and p.splat_done >= p.splat) return null; return p.data[i]; } fn advance(p: *Pieces) void { if (p.index == 0) { p.index = 1; return; } const i = p.index - 1; if (i == p.data.len - 1) { p.splat_done += 1; if (p.splat_done >= p.splat) p.index += 1; return; } p.index += 1; } }; fn finish(b: *BodyWriter) Response.Error!void { b.interface.flush() catch return error.WriteFailed; switch (b.mode) { .discard => {}, .exact => if (b.remaining != 0) return error.LengthMismatch, .unknown => {}, } if (!b.stream.end_stream_sent) { const s = b.stream.session; s.writer.send(.{ .length = 0, .type = .data, .flags = (frame.DataFlags{ .end_stream = true }).toInt(), .stream_id = b.stream.id, }, &.{}) catch return error.WriteFailed; b.stream.end_stream_sent = true; } } }; test "RFC 9113 6.9.1: a WINDOW_UPDATE overflowing a stream window resets it without hanging the reader" { const nothing = struct { fn serve(_: *Request, _: *Response) Handler.Error!void {} }; // HEADERS on stream 1 without END_STREAM, so the stream stays in the // table, then a WINDOW_UPDATE of 2^31-1 that takes its window past the // §6.9.1 limit: a stream error of FLOW_CONTROL_ERROR. const client: []const u8 = @import("../http2.zig").preface ++ [_]u8{ 0x00, 0x00, 0x00, 0x04, 0x00, 0x00, 0x00, 0x00, 0x00 } ++ [_]u8{ 0x00, 0x00, 0x0e, 0x01, 0x04, 0x00, 0x00, 0x00, 0x01 } ++ [_]u8{ 0x82, 0x86, 0x84, 0x41, 0x09 } ++ "a.example" ++ [_]u8{ 0x00, 0x00, 0x04, 0x08, 0x00, 0x00, 0x00, 0x00, 0x01, 0x7f, 0xff, 0xff, 0xff }; var memory: transport.memory.Connection = try .init(std.testing.allocator, client, .{}); defer memory.deinit(); var conn = memory.connection(); const Run = struct { done: std.atomic.Value(bool) = .init(false), fn run(r: *@This(), c: *transport.Connection) void { serve(std.testing.io, std.testing.allocator, c, .initStateless(nothing.serve), .{}) catch {}; r.done.store(true, .release); } }; var r: Run = .{}; var group: Io.Group = .init; try group.concurrent(std.testing.io, Run.run, .{ &r, &conn }); var waited: usize = 0; while (!r.done.load(.acquire) and waited < 200) : (waited += 1) { try std.testing.io.sleep(.fromMilliseconds(10), .awake); } // A reader stuck on an uncancelable lock cannot be unwound, so a hang // ends the test run rather than waiting on it forever. if (!r.done.load(.acquire)) @panic("the reader deadlocked on a WINDOW_UPDATE"); group.await(std.testing.io) catch {}; var rest = memory.written(); var reset: ?u32 = null; while (rest.len >= 9) { const len = std.mem.readInt(u24, rest[0..3], .big); const id = std.mem.readInt(u32, rest[5..9], .big) & 0x7fff_ffff; if (id == 1 and rest[3] == @backingInt(frame.Type.rst_stream)) reset = std.mem.readInt(u32, rest[9..13], .big); rest = rest[9 + len ..]; } try std.testing.expectEqual(@as(?u32, @backingInt(frame.ErrorCode.flow_control_error)), reset); } test "RFC 9113 5.1: trailers in flight on a stream this server refused do not end the connection" { const nothing = struct { fn serve(_: *Request, _: *Response) Handler.Error!void {} }; // Stream 1 stays open (no END_STREAM); stream 3 is refused because only // one stream is allowed; the client, which had not yet seen the // RST_STREAM, finishes stream 3 with a trailer section. §5.1: frames on a // stream after we sent RST_STREAM are to be ignored. const client: []const u8 = @import("../http2.zig").preface ++ [_]u8{ 0x00, 0x00, 0x00, 0x04, 0x00, 0x00, 0x00, 0x00, 0x00 } ++ [_]u8{ 0x00, 0x00, 0x0e, 0x01, 0x04, 0x00, 0x00, 0x00, 0x01 } ++ [_]u8{ 0x82, 0x86, 0x84, 0x41, 0x09 } ++ "a.example" ++ [_]u8{ 0x00, 0x00, 0x04, 0x01, 0x04, 0x00, 0x00, 0x00, 0x03 } ++ [_]u8{ 0x82, 0x86, 0x84, 0xbe } ++ [_]u8{ 0x00, 0x00, 0x07, 0x01, 0x05, 0x00, 0x00, 0x00, 0x03 } ++ [_]u8{ 0x00, 0x03 } ++ "x-t" ++ [_]u8{0x01} ++ "v"; var memory: transport.memory.Connection = try .init(std.testing.allocator, client, .{}); defer memory.deinit(); var conn = memory.connection(); try serve(std.testing.io, std.testing.allocator, &conn, .initStateless(nothing.serve), .{ .max_concurrent_streams = 1 }); var rest = memory.written(); var refused = false; var goaway_code: ?u32 = null; while (rest.len >= 9) { const len = std.mem.readInt(u24, rest[0..3], .big); const kind = rest[3]; const id = std.mem.readInt(u32, rest[5..9], .big) & 0x7fff_ffff; if (id == 3 and kind == @backingInt(frame.Type.rst_stream)) refused = true; if (kind == @backingInt(frame.Type.goaway)) goaway_code = std.mem.readInt(u32, rest[13..17], .big); rest = rest[9 + len ..]; } try std.testing.expect(refused); try std.testing.expectEqual(@as(?u32, @backingInt(frame.ErrorCode.no_error)), goaway_code); } test "RFC 9113 6.9.1: padding in request DATA is given back to the stream window" { const reads = struct { fn serve(req: *Request, res: *Response) Handler.Error!void { var sink: [64]u8 = undefined; var d: Io.Writer.Discarding = .init(&sink); _ = req.body.reader.streamRemaining(&d.writer) catch {}; try res.send(""); } }; // §6.9.1: padding counts against the stream window. Four padded DATA // frames of 256 octets each, one octet of data apiece, fill a 1024-octet // stream window exactly; the handler then reads every octet delivered. const padded = [_]u8{ 0x00, 0x01, 0x00, 0x00, 0x08, 0x00, 0x00, 0x00, 0x01, 254, 'x' } ++ @as([254]u8, @splat(0)); const client: []const u8 = @import("../http2.zig").preface ++ [_]u8{ 0x00, 0x00, 0x00, 0x04, 0x00, 0x00, 0x00, 0x00, 0x00 } ++ [_]u8{ 0x00, 0x00, 0x0e, 0x01, 0x04, 0x00, 0x00, 0x00, 0x01 } ++ [_]u8{ 0x83, 0x86, 0x84, 0x41, 0x09 } ++ "a.example" ++ padded ++ padded ++ padded ++ padded; var memory: transport.memory.Connection = try .init(std.testing.allocator, client, .{}); defer memory.deinit(); var conn = memory.connection(); try serve(std.testing.io, std.testing.allocator, &conn, .initStateless(reads.serve), .{ .stream_receive_window = 1024 }); // The whole window was spent and everything in it was consumed, so the // peer's window must have been reopened; otherwise it is stuck at zero. var rest = memory.written(); var credited: u32 = 0; while (rest.len >= 9) { const len = std.mem.readInt(u24, rest[0..3], .big); const kind = rest[3]; const id = std.mem.readInt(u32, rest[5..9], .big) & 0x7fff_ffff; if (id == 1 and kind == @backingInt(frame.Type.window_update)) credited += std.mem.readInt(u32, rest[9..13], .big); rest = rest[9 + len ..]; } try std.testing.expect(credited > 0); } /// What `max_body_len` of 4 made of one POST on stream 1: the body of the /// response, and the code of the RST_STREAM after it. const LimitedAnswer = struct { body: [32]u8 = undefined, body_len: usize = 0, reset: ?u32 = null }; fn serveLimited(request: []const u8) !LimitedAnswer { const reads = struct { fn serve(req: *Request, res: *Response) Handler.Error!void { _ = try req.body.reader.discardRemaining(); try res.send("ok"); } }; const client: []const u8 = try std.mem.concat(std.testing.allocator, u8, &.{ @import("../http2.zig").preface, &.{ 0x00, 0x00, 0x00, 0x04, 0x00, 0x00, 0x00, 0x00, 0x00 }, request, }); defer std.testing.allocator.free(client); var memory: transport.memory.Connection = try .init(std.testing.allocator, client, .{}); defer memory.deinit(); var conn = memory.connection(); try serve(std.testing.io, std.testing.allocator, &conn, .initStateless(reads.serve), .{ .max_body_len = 4 }); var answer: LimitedAnswer = .{}; var rest = memory.written(); while (rest.len >= 9) { const len = std.mem.readInt(u24, rest[0..3], .big); const kind = rest[3]; const id = std.mem.readInt(u32, rest[5..9], .big) & 0x7fff_ffff; if (id == 1 and kind == @backingInt(frame.Type.rst_stream)) answer.reset = std.mem.readInt(u32, rest[9..13], .big); if (id == 1 and kind == @backingInt(frame.Type.data)) { @memcpy(answer.body[answer.body_len..][0..len], rest[9..][0..len]); answer.body_len += len; } rest = rest[9 + len ..]; } return answer; } /// HEADERS for `POST /` at a.example on stream 1, with `content-length` when /// `length` is not empty, and without END_STREAM. fn postHeaders(buffer: []u8, length: []const u8) []const u8 { var w: Io.Writer = .fixed(buffer); const block_len: u24 = @intCast(14 + if (length.len > 0) 3 + length.len else 0); var len_bytes: [3]u8 = undefined; std.mem.writeInt(u24, &len_bytes, block_len, .big); w.writeAll(&len_bytes) catch unreachable; w.writeAll(&.{ 0x01, 0x04, 0x00, 0x00, 0x00, 0x01 }) catch unreachable; w.writeAll(&.{ 0x83, 0x86, 0x84, 0x41, 0x09 }) catch unreachable; w.writeAll("a.example") catch unreachable; // §6.2.2 of RFC 7541: a literal without indexing, the name being static // index 28, `content-length`. if (length.len > 0) { w.writeAll(&.{ 0x0f, 28 - 15, @intCast(length.len) }) catch unreachable; w.writeAll(length) catch unreachable; } return w.buffered(); } fn dataFrame(comptime payload: []const u8, comptime end: bool) [9 + payload.len]u8 { return [_]u8{ 0x00, 0x00, payload.len, 0x00, if (end) 0x01 else 0x00, 0x00, 0x00, 0x00, 0x01 } ++ payload[0..payload.len].*; } test "a content-length over max_body_len is a 413 before the handler" { var buffer: [64]u8 = undefined; const request = try std.mem.concat(std.testing.allocator, u8, &.{ postHeaders(&buffer, "5"), &dataFrame("hello", true) }); defer std.testing.allocator.free(request); const got = try serveLimited(request); try std.testing.expect(std.mem.startsWith(u8, got.body[0..got.body_len], "413 ")); try std.testing.expectEqual(@as(?u32, @backingInt(frame.ErrorCode.no_error)), got.reset); } test "a request body that runs past max_body_len is a 413" { var buffer: [64]u8 = undefined; const over = try std.mem.concat(std.testing.allocator, u8, &.{ postHeaders(&buffer, ""), &dataFrame("abc", false), &dataFrame("de", true) }); defer std.testing.allocator.free(over); const got = try serveLimited(over); try std.testing.expect(std.mem.startsWith(u8, got.body[0..got.body_len], "413 ")); try std.testing.expectEqual(@as(?u32, @backingInt(frame.ErrorCode.no_error)), got.reset); // Up to the limit is read as ever. const within = try std.mem.concat(std.testing.allocator, u8, &.{ postHeaders(&buffer, ""), &dataFrame("ab", false), &dataFrame("cd", true) }); defer std.testing.allocator.free(within); const ok = try serveLimited(within); try std.testing.expectEqualStrings("ok", ok.body[0..ok.body_len]); try std.testing.expectEqual(@as(?u32, null), ok.reset); } test "discardRemaining on an HTTP/2 request body reads it rather than failing an assertion" { const discards = struct { fn serve(req: *Request, res: *Response) Handler.Error!void { const n = try req.body.reader.discardRemaining(); try res.sendPrint("{d}", .{n}); } }; var buffer: [64]u8 = undefined; const request = try std.mem.concat(std.testing.allocator, u8, &.{ postHeaders(&buffer, ""), &dataFrame("abc", false), &dataFrame("de", true) }); defer std.testing.allocator.free(request); const client: []const u8 = try std.mem.concat(std.testing.allocator, u8, &.{ @import("../http2.zig").preface, &.{ 0x00, 0x00, 0x00, 0x04, 0x00, 0x00, 0x00, 0x00, 0x00 }, request, }); defer std.testing.allocator.free(client); var memory: transport.memory.Connection = try .init(std.testing.allocator, client, .{}); defer memory.deinit(); var conn = memory.connection(); try serve(std.testing.io, std.testing.allocator, &conn, .initStateless(discards.serve), .{}); var rest = memory.written(); var body: std.ArrayList(u8) = .empty; defer body.deinit(std.testing.allocator); while (rest.len >= 9) { const len = std.mem.readInt(u24, rest[0..3], .big); const id = std.mem.readInt(u32, rest[5..9], .big) & 0x7fff_ffff; if (id == 1 and rest[3] == @backingInt(frame.Type.data)) try body.appendSlice(std.testing.allocator, rest[9..][0..len]); rest = rest[9 + len ..]; } try std.testing.expectEqualStrings("5", body.items); } /// A transport that delivers `first`, then waits until the server has written /// RST_STREAM on stream 1 before delivering `second` -- so a test can say what /// the server does with a stream it has reset, rather than racing it. const ResetGate = struct { io: Io, first: []const u8, second: []const u8, pos: usize = 0, in_second: bool = false, read_buf: [8192]u8 = undefined, reader: Io.Reader = undefined, write_buf: [4096]u8 = undefined, writer: Io.Writer = undefined, out: Io.Writer.Allocating, reset_seen: Io.Event = .unset, fn connection(g: *ResetGate) transport.Connection { g.reader = .{ .vtable = &.{ .stream = stream }, .buffer = &g.read_buf, .seek = 0, .end = 0 }; g.writer = .{ .vtable = &.{ .drain = drain }, .buffer = &g.write_buf }; return .{ .input = &g.reader, .output = &g.writer, .info = .{}, .context = g, .vtable = &.{ .close = close } }; } fn stream(r: *Io.Reader, w: *Io.Writer, limit: Io.Limit) Io.Reader.StreamError!usize { const g: *ResetGate = @alignCast(@fieldParentPtr("reader", r)); var source = if (g.in_second) g.second else g.first; if (g.pos == source.len) { if (g.in_second) return error.EndOfStream; g.reset_seen.wait(g.io) catch return error.ReadFailed; g.in_second = true; g.pos = 0; source = g.second; } const dest = limit.slice(try w.writableSliceGreedy(1)); const n = @min(dest.len, source.len - g.pos); @memcpy(dest[0..n], source[g.pos..][0..n]); w.advance(n); g.pos += n; return n; } fn drain(w: *Io.Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize { const g: *ResetGate = @alignCast(@fieldParentPtr("writer", w)); try g.out.writer.writeAll(w.buffered()); w.end = 0; var n: usize = 0; for (data[0 .. data.len - 1]) |d| { try g.out.writer.writeAll(d); n += d.len; } const last = data[data.len - 1]; for (0..splat) |_| try g.out.writer.writeAll(last); n += last.len * splat; // RST_STREAM's header on stream 1: four octets, type 3, no flags. if (std.mem.indexOf(u8, g.out.written(), &.{ 0x00, 0x00, 0x04, 0x03, 0x00, 0x00, 0x00, 0x00, 0x01 }) != null) { g.reset_seen.set(g.io); } return n; } fn close(_: ?*anyopaque, _: Io, _: Allocator) void {} }; test "a stream this server reset while the body was still coming does not hold a concurrency slot" { var buffer: [64]u8 = undefined; // Stream 1 declares five octets, over the limit, and sends none: the // client stops once it is told to with RST_STREAM, so END_STREAM never // comes. Then stream 3, which only one concurrent stream allows if stream // 1 has gone. const first = try std.mem.concat(std.testing.allocator, u8, &.{ @import("../http2.zig").preface, &.{ 0x00, 0x00, 0x00, 0x04, 0x00, 0x00, 0x00, 0x00, 0x00 }, postHeaders(&buffer, "5"), }); defer std.testing.allocator.free(first); const second = [_]u8{ 0x00, 0x00, 0x0e, 0x01, 0x05, 0x00, 0x00, 0x00, 0x03 } ++ [_]u8{ 0x82, 0x86, 0x84, 0x41, 0x09 } ++ "a.example"; const second_bytes: []const u8 = second; var gate: ResetGate = .{ .io = std.testing.io, .first = first, .second = second_bytes, .out = .init(std.testing.allocator) }; defer gate.out.deinit(); var conn = gate.connection(); const nothing = struct { fn serve(_: *Request, _: *Response) Handler.Error!void {} }; try serve(std.testing.io, std.testing.allocator, &conn, .initStateless(nothing.serve), .{ .max_body_len = 4, .max_concurrent_streams = 1, }); var rest = gate.out.written(); var answered = false; var refused: ?u32 = null; while (rest.len >= 9) { const len = std.mem.readInt(u24, rest[0..3], .big); const id = std.mem.readInt(u32, rest[5..9], .big) & 0x7fff_ffff; if (id == 3 and rest[3] == @backingInt(frame.Type.headers)) answered = true; if (id == 3 and rest[3] == @backingInt(frame.Type.rst_stream)) refused = std.mem.readInt(u32, rest[9..13], .big); rest = rest[9 + len ..]; } try std.testing.expectEqual(@as(?u32, null), refused); try std.testing.expect(answered); }