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