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