Something went wrong. Try again.
An HTTP library for Zig 0.17, server and client, HTTP/1.0 through HTTP/3, with the protocol in a module that owns no socket.
Something went wrong. Try again.
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// 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.//!//! ## Two 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`.//!//! 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 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.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();}
/// 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, /// 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, 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, .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, .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.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);
// 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; }, } }
if (s.dispatch(header)) |fault| return fault; } }
/// 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; }
frame.writeSettingsAck(s.conn.output) catch return .conn(.no_error); s.conn.output.flush() catch return .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; };
// `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; if (updated > Settings.max_window_size) { s.resetStream(header.stream_id, .flow_control_error); return null; } stream.send_window = @intCast(updated); 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); }
return s.openStream(header.stream_id, flags.end_stream); }
/// 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 { 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); };
// §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);
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; }
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, @intFromEnum(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,
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),
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 }, .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 { s.sendReset(stream.id, .internal_error); return; }; break :body .{ .reader = decoded.reader, .length = decoded.length }; }, .{ .extended_connect = s.config.enable_connect_protocol }, ) catch |err| { switch (err) { error.Malformed => s.sendReset(stream.id, .protocol_error), error.NotImplemented => stream.respondStatus(.not_implemented), error.OutOfMemory => s.sendReset(stream.id, .internal_error), } return; };
stream.method_has_body = req.method.responseHasBody(); stream.connect_protocol = req.connect_protocol;
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) { 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. s.sendReset(stream.id, .internal_error); } return; };
switch (res.state) { .head => res.send("") catch {}, .body => res.end() catch {}, .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; }; } }
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}", .{@intFromEnum(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}", .{@intFromEnum(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; } // §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, err: ?Fault = null,
const Fault = error{ /// The peer reset the stream while the handler was reading. StreamReset, /// The connection is gone. ConnectionLost, Canceled, };
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; };
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; }, }; w.advance(n); b.credit(@intCast(n)); return n; }
/// 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; } }};