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.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! One HTTP/3 connection, on one QUIC connection.//!//! Smaller than the HTTP/2 driver rather than larger, and the difference is//! all the things that are no longer here. There is no connection preface to//! read, because QUIC's handshake is one. No flow control, no WINDOW_UPDATE,//! no stream table and no MAX_CONCURRENT_STREAMS, because a QUIC connection//! already has all of that and §4.6 of RFC 9114 says so outright. No//! RST_STREAM, because QUIC has one. No writer lock, because a QUIC stream is//! independent of every other and there is no single byte stream to serialise//! onto -- which was the largest single piece of the HTTP/2 driver.//!//! What is left is three unidirectional streams that carry the connection's//! own business, and a task per request.//!//! ## The streams//!//! §6.2: each unidirectional stream begins with a varint saying what it is.//! Both ends open a control stream (0x00) and the two QPACK streams (0x02 and//! 0x03); §4.2 of RFC 9204 requires the QPACK pair to exist even when, as//! here, they will never carry anything. A stream of an unknown type is//! abandoned rather than refused (§6.2), which is the same "ignore what you//! do not know" rule the frame layer has and exists so that extensions can be//! deployed without a flag day.//!//! §6.2.1 is the sharp edge: the control stream "MUST NOT be closed", and//! either end closing one is H3_CLOSED_CRITICAL_STREAM. A second control//! stream is H3_STREAM_CREATION_ERROR. Neither can happen by accident, which//! is exactly why they are worth checking -- a peer doing either is either//! broken or probing.
const std = @import("std");const Io = std.Io;const Allocator = std.mem.Allocator;
const quic = @import("quic");
const protocol = @import("../protocol.zig");const transport = @import("../transport.zig");const Handler = @import("../server/Handler.zig");const Request = @import("../server/Request.zig");const Response = @import("../server/Response.zig");const compression = @import("../server/compression.zig");const Headers = protocol.Headers;const Status = protocol.Status;
const frame = @import("frame.zig");const qpack = @import("qpack.zig");const request_builder = @import("../field/request.zig");
const log = std.log.scoped(.http3);
const Connection = @This();
pub const Config = struct { /// §7.2.4.1: the largest field section this server will decode, before /// compression. A section over it is one request's problem and gets a /// 431, not a connection error -- §4.2.2 of RFC 9114 says so, and the /// reasoning is the same as HTTP/2's: RST_STREAM would tell the client /// "nothing happened, try again", which it would, for ever. max_field_section_size: u32 = 16 * 1024, /// The most request body, in octets of DATA frame payload, this server /// will read for one request, or null for no limit beyond what the /// handler chooses to read -- which is how the HTTP/1 and HTTP/2 servers /// behave, and so the default. A request whose `content-length` is over /// it is answered `413` before the handler runs. One that sends more /// without saying so has its body read fail at the limit, and is /// answered `413` unless the handler has already begun a response. Either /// way the client is asked to stop sending, with H3_NO_ERROR as §4.1 of /// RFC 9114 asks. max_body_len: ?u64 = null, /// How many field lines one request may carry. max_fields: usize = 64, /// RFC 9220: whether to advertise `SETTINGS_ENABLE_CONNECT_PROTOCOL`, /// which is what lets a client send an extended CONNECT and so what lets /// a WebSocket run over HTTP/3. /// /// RFC 9220 is three pages and most of them are about what it does *not* /// change: the setting has the same identifier as RFC 8441's, the request /// has the same shape, and the answer is the same `2xx`. What differs is /// that there is no stream to be careful about -- see `upgrade`. enable_connect_protocol: bool = true, /// Whether to code a response body, and how. Null is a server that does /// not compress; the same `server.compression.Config` the other two /// drivers take, because a content coding is the representation's and not /// the version's. compression: ?compression.Config = null, /// Whether to undo a content coding on a request body before the handler /// sees it. The same option the other two drivers take. request_decoding: ?compression.RequestDecoding = null,};
io: Io,gpa: Allocator,session: transport.Session,handler: Handler,config: Config,/// §6.2.1: one control stream in each direction, and they may not close.control_out: ?transport.Stream = null,control_in_seen: bool = false,/// §7.2.4: SETTINGS must be the first frame on the control stream, and this/// is how "must" is checked.peer_settings_seen: bool = false,/// §7.2.4.1: the client's SETTINGS_MAX_FIELD_SECTION_SIZE, which is/// unlimited until its SETTINGS says otherwise. Written by the task reading/// the control stream and read by every request's, so atomic.peer_max_field_section_size: std.atomic.Value(u64) = .init(std.math.maxInt(u64)),/// §5.2: the stream identifier this endpoint named in the GOAWAY it sent, or/// null while it has sent none.////// "The identifier in a GOAWAY frame... indicates the highest-numbered/// request... that might have been processed", and a request at or above it/// was not -- which is what makes a graceful shutdown safe to retry against.sent_goaway: ?u64 = null,/// §2.1 of RFC 9000: the next client-initiated bidirectional stream this/// endpoint has not seen, which is what a GOAWAY names.next_request_stream: u64 = 0,/// §7.2.6: the identifier in the last GOAWAY the peer sent. A second one may/// only name something lower.peer_goaway: ?u64 = null,/// §7.2.7: the last MAX_PUSH_ID the peer sent, which a later one may not go/// below. Nothing else is done with it, because this server does not push;/// it is kept because the rule about the sequence is a rule whether or not/// the permission is ever used.peer_max_push_id: ?u64 = null,tasks: Io.Group = .init,mutex: Io.Mutex = .init,
/// A connection that will serve `session` with `handler`. Nothing is read or/// sent until `run`.////// There is no `deinit`: what a request needs is allocated from `gpa` per/// request and freed when it is answered, and the session is the caller's to/// close.pub fn init( io: Io, gpa: Allocator, session: transport.Session, handler: Handler, config: Config,) Connection { return .{ .io = io, .gpa = gpa, .session = session, .handler = handler, .config = config, };}
/// A handler for the examples below, answering every request with "hi".fn testHandler(_: *Request, res: *Response) Handler.Error!void { try res.send("hi");}
/// A request stream for the examples below: one HEADERS frame asking for `/`.fn testRequestStream(buffer: []u8) ![]const u8 { return testRequestStreamFor(buffer, "GET");}
/// The same, with a method of the caller's choosing.fn testRequestStreamFor(buffer: []u8, method: []const u8) ![]const u8 { var section: [128]u8 = undefined; var sw: Io.Writer = .fixed(§ion); try qpack.encode(&sw, &.{ .{ .name = ":method", .value = method }, .{ .name = ":scheme", .value = "https" }, .{ .name = ":authority", .value = "example.com" }, .{ .name = ":path", .value = "/" }, }); var w: Io.Writer = .fixed(buffer); var header: [16]u8 = undefined; try w.writeAll(header[0..try frame.write(&header, .headers, sw.buffered().len)]); try w.writeAll(sw.buffered()); return w.buffered();}
test init { var scripted: transport.memory_session.Scripted = .{ .incoming = &.{} }; defer scripted.deinit(std.testing.allocator); const c: Connection = .init( std.testing.io, std.testing.allocator, scripted.session(std.testing.allocator), .initStateless(testHandler), .{ .max_body_len = 4096 }, ); try std.testing.expectEqual(@as(?u64, 4096), c.config.max_body_len); // Not even the control stream is open until `run`. try std.testing.expect(c.control_out == null);}
/// Serves one connection until the peer goes away.////// Separate from `init` so that whoever is serving can hold a pointer to the/// connection while it runs -- which is what `Listener.shutdown` needs, since/// a GOAWAY has to reach a connection that is in the middle of its work.////// Errors are not returned: a stream error ends that request, and a/// connection error closes the session with the code §8.1 gives it. Every/// request task has finished by the time this returns.pub fn run(c: *Connection) void { const io = c.io; const session = c.session; // Every stream task has returned before this frame goes away, which // matters because they point into it. defer c.tasks.cancel(io);
// §6.2: the control streams cannot be opened until the peer has said how // many streams this endpoint may open, and it says so in its transport // parameters -- which arrive with the handshake. Opening them any earlier // is a STREAM_LIMIT_ERROR against a limit that is zero because nothing // has been negotiated yet. if (!session.waitEstablished()) return;
c.openControlStreams() catch |err| { log.debug("could not open the control streams: {s}", .{@errorName(err)}); return; };
while (session.accept()) |stream| { // §5.2: a request that arrives at or above the identifier this // endpoint named in its GOAWAY was not processed, and saying so is // the whole value of a graceful shutdown -- a client that is told // H3_REQUEST_REJECTED knows it may send the request again somewhere // else, where a connection that simply closed leaves it guessing // whether the request happened. if (c.refuses(stream.id)) { c.reject(stream); continue; }
// §6.1: a bidirectional stream from a client is a request. A // unidirectional one says what it is in its first varint, and // reading that is itself blocking, so it happens on a task rather // than in this loop -- a peer that opened a stream and sent nothing // would otherwise stop every request behind it. c.tasks.concurrent(io, runStream, .{ c, stream }) catch { // §4.1: "the server MAY abort the stream", and REQUEST_REJECTED // is the code that means nothing happened and another connection // would do. c.reject(stream); }; }
c.tasks.await(io) catch {};}
test run { var request: [256]u8 = undefined; var scripted: transport.memory_session.Scripted = .{ .incoming = &.{.{ .id = .{ .value = 0 }, .data = try testRequestStream(&request) }}, }; defer scripted.deinit(std.testing.allocator); var c: Connection = .init( std.testing.io, std.testing.allocator, scripted.session(std.testing.allocator), .initStateless(testHandler), .{}, ); c.run();
try std.testing.expect(scripted.closed == null); // The answer on the request's own stream opens with a HEADERS frame. const answered = scripted.wrote(.{ .value = 0 }).?; const head = try frame.parse(answered); try std.testing.expectEqual(frame.Kind.headers, head.kind); var fields: [8]qpack.Field = undefined; var scratch: [64]u8 = undefined; const n = try qpack.decode(answered[head.header_len..head.end().?], &fields, &scratch); try std.testing.expect(n > 0); try std.testing.expectEqualStrings(":status", fields[0].name); try std.testing.expectEqualStrings("200", fields[0].value);}
/// What one request served by `serve` got back on its stream, for the tests/// below that care about the response's framing rather than its content.const TestAnswer = struct { status: [3]u8 = undefined, content_length_buf: [20]u8 = undefined, content_length_len: ?usize = null, /// How many DATA frames followed the head, and how much they carried. data_frames: usize = 0, data_len: u64 = 0, finished: bool = false, reset: ?u64 = null,
fn contentLength(a: *const TestAnswer) ?[]const u8 { return a.content_length_buf[0 .. a.content_length_len orelse return null]; }};
fn testServe(method: []const u8, comptime serve: fn (*Request, *Response) Handler.Error!void) !TestAnswer { var request: [256]u8 = undefined; var scripted: transport.memory_session.Scripted = .{ .incoming = &.{.{ .id = .{ .value = 0 }, .data = try testRequestStreamFor(&request, method) }}, }; defer scripted.deinit(std.testing.allocator); var c: Connection = .init( std.testing.io, std.testing.allocator, scripted.session(std.testing.allocator), .initStateless(serve), .{}, ); c.run();
const state = scripted.find(.{ .value = 0 }).?; var answer: TestAnswer = .{ .finished = state.finished, .reset = state.reset }; var rest = state.written.items; const head = try frame.parse(rest); try std.testing.expectEqual(frame.Kind.headers, head.kind); var fields: [16]qpack.Field = undefined; var scratch: [256]u8 = undefined; const n = try qpack.decode(rest[head.header_len..head.end().?], &fields, &scratch); for (fields[0..n]) |f| { if (std.mem.eql(u8, f.name, ":status")) answer.status = f.value[0..3].*; if (std.mem.eql(u8, f.name, "content-length")) { @memcpy(answer.content_length_buf[0..f.value.len], f.value); answer.content_length_len = f.value.len; } } rest = rest[head.end().?..]; while (rest.len > 0) { const h = try frame.parse(rest); if (h.kind == .data) { answer.data_frames += 1; answer.data_len += h.length; } rest = rest[h.end().?..]; } return answer;}
test "RFC 9114 4.1.2: a response to HEAD carries its length and no content" { const answer = try testServe("HEAD", testHandler); try std.testing.expectEqualStrings("200", &answer.status); // §9.3.2 of RFC 9110: the length the GET would have had. try std.testing.expectEqualStrings("2", answer.contentLength().?); try std.testing.expectEqual(@as(usize, 0), answer.data_frames); try std.testing.expect(answer.finished);}
test "RFC 9110 8.6: a 204 has neither content nor a content-length" { const NoContent = struct { fn serve(_: *Request, res: *Response) Handler.Error!void { res.status = .no_content; try res.send("ignored"); } }; const answer = try testServe("GET", NoContent.serve); try std.testing.expectEqualStrings("204", &answer.status); try std.testing.expect(answer.contentLength() == null); try std.testing.expectEqual(@as(usize, 0), answer.data_frames);}
test "RFC 9114 4.1.2: a body shorter than its declared length ends the stream" { const Short = struct { fn serve(_: *Request, res: *Response) Handler.Error!void { const w = try res.beginBody(.{ .exact = 5 }); try w.writeAll("he"); } }; const answer = try testServe("GET", Short.serve); // Not finished, which would tell the client two octets were all of it. try std.testing.expect(!answer.finished); try std.testing.expectEqual(@as(?u64, @backingInt(frame.Error.internal_error)), answer.reset);}
test "RFC 9114 4.1.2: a body longer than its declared length is refused" { const Long = struct { fn serve(_: *Request, res: *Response) Handler.Error!void { const w = try res.beginBody(.{ .exact = 2 }); try w.writeAll("hello"); try w.flush(); try res.end(); } }; const answer = try testServe("GET", Long.serve); try std.testing.expect(answer.data_len <= 2); try std.testing.expect(!answer.finished); try std.testing.expectEqual(@as(?u64, @backingInt(frame.Error.internal_error)), answer.reset);}
fn runStream(c: *Connection, stream: transport.Stream) void { if (stream.id.directionality() == .bidirectional) { c.mutex.lockUncancelable(c.io); c.next_request_stream = @max(c.next_request_stream, stream.id.value + 4); c.mutex.unlock(c.io); } if (stream.id.directionality() == .unidirectional) { c.serveUnidirectional(stream); } else { c.serveRequest(stream); }}
/// §5.2: whether a request on this stream is one this endpoint has already/// said it would not process.fn refuses(c: *Connection, id: quic.stream.Id) bool { const last = c.sent_goaway orelse return false; if (id.directionality() != .bidirectional) return false; return id.value >= last;}
/// A request stream that stopped before its field section was whole.////// §7.1 makes a frame cut off by the end of its stream a connection error,/// H3_FRAME_ERROR -- but QUIC delivers a peer's RESET_STREAM to a reader as/// that same end, and a client cancelling an upload resets mid-frame as a/// matter of course. Once both halves of the stream are done the transport no/// longer knows which it was, so the two cannot be told apart reliably, and/// closing the connection over a cancelled request would take every other/// request on it down too. Both are answered as one request ending instead:/// §4.1.2's "if a client-initiated stream terminates without enough of the/// HTTP message to provide a complete response, the server SHOULD abort its/// response stream with the error code H3_REQUEST_INCOMPLETE". A read that/// failed is the connection going, which needs no answer. Returning without/// either left the client waiting until the idle timeout.fn endedEarly(c: *Connection, stream: transport.Stream, how: enum { incomplete, failed }) void { switch (how) { .incomplete => c.abort(stream, .request_incomplete), .failed => {}, }}
fn reject(c: *Connection, stream: transport.Stream) void { // §4.1.2: "the server MAY abort the stream", and H3_REQUEST_REJECTED is // the code that means nothing happened here and another connection would // do. It is the one answer a client can act on without having to know // whether the request took effect. c.abort(stream, .request_rejected);}
/// Ends one request stream without answering it, which is what §4.1.2 calls a/// stream error: the connection and every other request on it are unaffected.////// Both halves, because a QUIC stream has two and resetting one says nothing/// about the other. Without the STOP_SENDING a client that is still uploading/// a request body has been told its answer will never come and not told to/// stop asking, so it goes on paying for octets this server has already/// decided to discard -- which §4.1 puts as "a server can abort reading the/// request stream".fn abort(c: *Connection, stream: transport.Stream, code: frame.Error) void { c.session.resetStream(stream.id, @backingInt(code)); c.session.stopSending(stream.id, @backingInt(code));}
/// §5.2: begins a graceful shutdown.////// The identifier named is the next request stream this endpoint has not yet/// seen, so everything already in flight is finished and everything after it/// is refused with a code the client can retry on. §2.1 of RFC 9000 numbers/// client-initiated bidirectional streams 0, 4, 8..., which is why the step/// is four rather than one.////// §5.2 describes doing this twice -- an initial GOAWAY naming the largest/// possible identifier, to stop new requests while leaving time for those in/// flight, then a second naming the real cut-off. This sends the cut-off/// directly, which is the same guarantee in one frame: what is in flight/// finishes, and nothing new is taken.////// Safe to call from another task while `run` is serving. Before `run` has/// opened the control stream there is nowhere to send a GOAWAY, and this does/// nothing; a call that would not lower the identifier already sent does/// nothing either.pub fn shutdown(c: *Connection) void { c.mutex.lockUncancelable(c.io); defer c.mutex.unlock(c.io);
const control = c.control_out orelse return; const last = c.next_request_stream; // §7.2.6: "an endpoint MAY send multiple GOAWAY frames indicating // different identifiers, but the identifier in each frame MUST NOT be // greater than the identifier in any previous frame." if (c.sent_goaway) |already| { if (last >= already) return; } c.sent_goaway = last;
var buffer: [32]u8 = undefined; var w = control.writer(&buffer); var body: [8]u8 = undefined; var bw: Io.Writer = .fixed(&body); writeVarint(&bw, last) catch return;
var header: [16]u8 = undefined; const n = frame.write(&header, .goaway, bw.buffered().len) catch return; w.interface.writeAll(header[0..n]) catch return; w.interface.writeAll(bw.buffered()) catch return; w.interface.flush() catch return;}
test shutdown { var request: [256]u8 = undefined; var scripted: transport.memory_session.Scripted = .{ .incoming = &.{.{ .id = .{ .value = 0 }, .data = try testRequestStream(&request) }}, }; defer scripted.deinit(std.testing.allocator); var c: Connection = .init( std.testing.io, std.testing.allocator, scripted.session(std.testing.allocator), .initStateless(testHandler), .{}, ); c.run(); c.shutdown();
// §5.2: request stream 0 was seen, so the GOAWAY names 4 -- the next // client-initiated bidirectional stream -- as the first one refused. const control = scripted.local(0).?.written.items; try std.testing.expectEqualSlices(u8, &.{ @backingInt(frame.Kind.goaway), 0x01, 0x04 }, control[control.len - 3 ..]);}
/// §4.1: a request stream carries a HEADERS frame, then the body, then/// nothing.////// This is where the four-layer claim gets its third test, and the first/// against a transport that is not a byte stream. What goes in is a QUIC/// stream and a QPACK field section; what comes out is the same `Request`/// and `Response` a handler has been written against since HTTP/1.0, built/// by the same `field.request` the HTTP/2 driver uses.fn serveRequest(c: *Connection, stream: transport.Stream) void { var arena_state: std.heap.ArenaAllocator = .init(c.gpa); defer arena_state.deinit(); const arena = arena_state.allocator();
var read_buffer: [4096]u8 = undefined; var r = stream.reader(&read_buffer);
// §4.1: "an HTTP message (request or response) consists of... the header // field section... followed by zero or more DATA frames". So the first // frame decides whether this is a request at all. const header = while (true) { const h = c.readFrameHeader(&r.interface) catch |err| { c.endedEarly(stream, if (err == error.EndOfStream) .incomplete else .failed); return; }; if (h.kind == .headers) break h; // §9: "implementations MUST ignore unknown or unsupported values in // all extensible protocol elements", and §4.1 lets a frame of an // unknown type sit anywhere in a message, before the HEADERS too. // Closing the connection over one closed it over grease. DATA is the // one known type a request stream allows besides HEADERS, so anything // else allowed is unknown. if (h.kind != .data and h.kind.allowedOnRequestStream()) { r.interface.discardAll64(h.length) catch |err| { c.endedEarly(stream, if (err == error.EndOfStream) .incomplete else .failed); return; }; continue; } // §4.1: a request stream that opens with anything else. DATA before // HEADERS is the case worth naming, because it is what a client that // has lost track of its own framing produces. c.close(.frame_unexpected, "a request stream did not open with HEADERS"); return; }; if (header.length > c.config.max_field_section_size) { // §4.2.2: one request's problem, and the answer is a status rather // than a reset -- a reset says "nothing happened, try again", which // the client would, for ever. c.respondStatus(stream, .request_header_fields_too_large); return; }
const section = arena.alloc(u8, @intCast(header.length)) catch return; // All of it, not whatever has arrived. A QUIC stream delivers what it // has, and a field section large enough to span two datagrams would // otherwise be read short and abandoned without a word -- which is a // failure that depends on timing, so it is absent on a loopback socket // and present on a network. r.interface.readSliceAll(section) catch |err| { c.endedEarly(stream, if (err == error.EndOfStream) .incomplete else .failed); return; };
var fields: [64]qpack.Field = undefined; var scratch: [8192]u8 = undefined; const n = qpack.decodeBounded( section, fields[0..@min(fields.len, c.config.max_fields)], &scratch, c.config.max_field_section_size, ) catch |err| switch (err) { // The check on the frame's length above is on the compressed size, // and §4.2.2 sets the limit on the decoded one -- which the static // table can make many times larger. Over either is the same 431, and // so is running out of room to decode into: all three are this // server's limits rather than the peer's mistakes, and none of them // leaves anything behind, because with no dynamic table there is no // state for an abandoned section to put out of step. error.TooLarge, error.TooManyFields, error.TooLong => { c.respondStatus(stream, .request_header_fields_too_large); return; }, // §6 of RFC 9204 gives every one of these the same code, because a // field section that cannot be decoded leaves the connection unable // to decode any later one either -- there is no per-stream recovery // from a compression failure, which is the price of a shared table // even when, as here, the table is empty. else => { log.debug("could not decode the field section: {s}", .{@errorName(err)}); c.close(.qpack_decompression_failed, "the field section did not decode"); return; }, };
// Into the shape `field.request` reads, which is the same list the HTTP/2 // driver hands it. var list: std.ArrayList(protocol.Field) = .empty; for (fields[0..n]) |f| { const name = arena.dupe(u8, f.name) catch return; const value = arena.dupe(u8, f.value) catch return; list.append(arena, .{ .name = name, .value = value }) catch return; }
// §4.1: the body is whatever DATA frames follow, so the handler cannot be // handed the stream itself -- it would read the next frame's type and // length as the first two octets of the message. var body_reader: BodyReader = .init(c, stream, &r.interface); var req = request_builder.build( c.io, arena, &list, .{ .secure = true, .alpn = "h3" }, body: { const plain: Request.Body = .{ .reader = &body_reader.interface, .length = .unknown, }; const decoding = c.config.request_decoding orelse break :body plain; // §8.4: undone before the handler when asked, and the failure is // answered rather than hidden -- coded octets reaching a handler // that was promised decoded ones is a wrong answer, not an error. const decoded = compression.decodeRequest( arena, decoding, protocol.Headers.initBorrowed(list.items).get("content-encoding"), plain.reader, plain.length, ) catch { // The same answer `build`'s own `OutOfMemory` gets three // lines below: give the stream up rather than hand a handler // coded octets it was told would be decoded. c.abort(stream, .internal_error); return; }; break :body .{ .reader = decoded.reader, .length = decoded.length }; }, .{ .version = .http_3, .extended_connect = c.config.enable_connect_protocol, }, ) catch |err| switch (err) { // §4.1.2: a malformed request "MUST be treated as a stream error of // type H3_MESSAGE_ERROR", which is one request rather than the // connection -- the thing HTTP/1.1 cannot do. // // A `400` would be friendlier and is what this used to send, but it // is not what the rule says, and the difference is not cosmetic: a // status code is a claim that the request was understood well enough // to be answered, and a field name this server has rejected as // unreadable is by definition one it did not understand. HTTP/2 has // always reset here, for the same reason. error.Malformed => { c.abort(stream, .message_error); return; }, error.NotImplemented => { c.respondStatus(stream, .not_implemented); return; }, error.OutOfMemory => return, };
// `build` has already refused a `content-length` that does not parse or // that disagrees with itself. if (req.headers.get("content-length")) |value| body_reader.declared = protocol.parseContentLength(value); if (body_reader.declared) |declared| if (declared > c.config.max_body_len orelse std.math.maxInt(u64)) { // §15.5.14 of RFC 9110, and before the handler or a `100 Continue`: // a body this server will not read is not one to ask for. c.refuseBody(stream); return; };
var out_buffer: [4096]u8 = undefined; var state: ResponseState = .{ .connection = c, .stream = stream, .writer = stream.writer(&out_buffer), }; state.method_has_body = req.method.responseHasBody(); state.connect_protocol = req.connect_protocol; state.reader = &body_reader.interface; state.body_reader = &body_reader;
var res: Response = .{ .headers = .empty, .arena = arena, .version = .http_3, .context = &state, .vtable = &response_vtable, .accept_encoding = req.headers.get("accept-encoding"), .compress = c.config.compression, };
if (req.headers.get("expect")) |expect| { if (!protocol.token.containsToken(expect, "100-continue")) { // §10.1.1 of RFC 9110: an expectation that is not understood is // refused rather than ignored, as by the other two drivers. c.respondStatus(stream, .expectation_failed); return; } body_reader.asks = .{ .response = &res, .stream = stream }; }
c.handler.serve(&req, &res) catch |err| { log.debug("handler failed for {s} {s}: {s}", .{ req.method.name, req.target.raw, @errorName(err), }); // The request's own body ended the stream already, and the // handler is only reporting that. if (body_reader.aborted) return; // The body ran past `max_body_len`, which is what the handler is // reporting, and nothing has been said about it yet. if (body_reader.too_large and res.state == .head) { c.refuseBody(stream); return; } // The head is already out saying what the body would be, so a // status is no longer possible. §4.1.2: ending the stream is, and it // ends this request and no other. if (res.state == .head) c.respondStatus(stream, .internal_server_error) else c.abort(stream, .internal_error); return; };
switch (res.state) { // A handler that read past the limit and let the failure go has // not answered the request it was given, so the limit does. .head => if (body_reader.too_large) c.refuseBody(stream) else res.send("") catch {}, // A body that came out a different length from the one declared // fails here, and §4.1.2 makes what the client would otherwise get // a malformed response; the stream is ended instead. .body => res.end() catch c.abort(stream, .internal_error), .ended => {}, // §5 of RFC 8441, which RFC 9220 inherits: "orderly TCP-level // closures are represented as END_STREAM flags". The handler has // stopped speaking whatever it was speaking, so the tunnel closes the // way a socket would -- which here means ending the QUIC stream, // because that is what says where a stream stops. .upgraded => state.writer.finish() catch {}, }}
/// §4.1: the request body, which is the payloads of the DATA frames that/// follow the HEADERS frame and nothing else.////// The frame headers between them are why a handler cannot simply be handed/// the stream: it would read a type and a length as the first two octets of/// the message, and every DATA frame after the first would splice two more/// into the middle of it. HTTP/2's driver has the same job and does not look/// like this, because there the frames arrive on a connection shared with/// every other stream and are taken apart before they reach a stream at all.const BodyReader = struct { interface: Io.Reader, source: *Io.Reader, /// The connection, so that a frame which has no business on a request /// stream can end it. §7.2 makes those connection errors rather than /// stream errors, which is a judgement about what they mean: a peer /// sending SETTINGS down a request stream has lost track of which stream /// is which, and nothing else it says can be trusted either. connection: *Connection, /// The request stream, which a body that breaks a rule is ended on. stream: transport.Stream, /// What is left of the DATA frame being read. remaining: u64 = 0, /// The request's `content-length`, when it declared one, and how much /// has arrived against it. §4.1.2: a body that comes out a different /// length is a malformed request, which the handler must not be given as /// though it were whole. declared: ?u64 = null, received: u64 = 0, /// `Config.max_body_len`, unlimited when that is null, and whether the /// body has run past it. max_len: u64, too_large: bool = false, /// Whether this reader has already ended the stream with a reset, after /// which nothing more is written to it: a handler failing over the read /// error would otherwise answer with a 500 down a stream already reset, /// and a write on one can wait on flow control that never comes. aborted: bool = false, /// Whether the stream has ended or something on it was not a DATA frame. finished: bool = false, /// §10.1.1 of RFC 9110: the response to send a `100 Continue` on, the /// first time the body is read, for a client holding its content back /// until it is asked -- the same rule the other two drivers follow -- and /// the stream the content is held back on. Null once asked, and when /// nobody is waiting. asks: ?struct { response: *Response, stream: transport.Stream } = null,
fn init(connection: *Connection, stream: transport.Stream, source: *Io.Reader) BodyReader { return .{ .interface = .{ .vtable = &.{ .stream = streamImpl }, .buffer = &.{}, .seek = 0, .end = 0, }, .source = source, .connection = connection, .stream = stream, .max_len = connection.config.max_body_len orelse std.math.maxInt(u64), }; }
/// The message has ended, at the end of the stream or at its trailers: /// whether it ended at the length it declared. fn end(b: *BodyReader) Io.Reader.StreamError!usize { b.finished = true; if (b.declared) |declared| if (b.received != declared) return b.malformed(); return error.EndOfStream; }
/// §4.1.2: "a request or response that is defined as having content when /// it contains a Content-Length header field" whose DATA frames add up to /// another length "MUST be treated as malformed", and a malformed request /// is a stream error of type H3_MESSAGE_ERROR. fn malformed(b: *BodyReader) error{ReadFailed} { b.finished = true; b.aborted = true; b.connection.abort(b.stream, .message_error); return error.ReadFailed; }
/// The stream ended inside a frame. See `endedEarly` for why that is /// this request's end rather than the connection's: the handler is told /// the read failed, never that a body cut off was the whole of it. fn truncated(b: *BodyReader) error{ReadFailed} { b.finished = true; b.aborted = true; b.connection.abort(b.stream, .request_incomplete); return error.ReadFailed; }
fn streamImpl(io_reader: *Io.Reader, w: *Io.Writer, limit: Io.Limit) Io.Reader.StreamError!usize { const b: *BodyReader = @alignCast(@fieldParentPtr("interface", io_reader)); if (b.finished) return error.EndOfStream;
if (b.asks) |ask| { b.asks = null; // Not once the head is out: a response already on its way answers // the expectation by itself. And not once the client has finished // the stream, which it has done without waiting -- its content is // all here, or there never was any -- so nothing is held back to // ask for, and §10.1.1 lets a server that "has already received // some or all of the content" say nothing. Asked here rather than // when the request arrived, since a client that stopped waiting // may have sent the rest in between. if (ask.response.state == .head and !ask.stream.session.received(ask.stream.id)) { ask.response.sendInterim(.@"continue", &.empty) catch return error.ReadFailed; } }
while (b.remaining == 0) { // The end of the stream between frames is the end of the body; // anywhere else it has cut a frame short. _ = b.source.peekByte() catch |err| switch (err) { error.EndOfStream => return b.end(), error.ReadFailed => { b.finished = true; return error.ReadFailed; }, }; const kind = readVarint(b.source) catch |err| return b.readFault(err); const length = readVarint(b.source) catch |err| return b.readFault(err); const f: frame.Kind = @fromBackingInt(@intCast(kind)); switch (f) { .data => b.remaining = length, // §4.1: trailers, which are read and discarded the way // HTTP/1.1's chunked trailers are -- a handler has no way to // ask for them, so delivering them would be inventing an // interface rather than implementing one. .headers => { b.source.discardAll64(length) catch |err| return b.readFault(err); return b.end(); }, else => { // §7.2: SETTINGS, GOAWAY, MAX_PUSH_ID and CANCEL_PUSH // belong to the control stream, and §7.2.5 says a server // "MUST treat the receipt of a PUSH_PROMISE frame as a // connection error of type H3_FRAME_UNEXPECTED". An // unknown type is a different thing entirely and is // stepped over, per §7.2.8. if (!f.allowedOnRequestStream()) { b.connection.close( .frame_unexpected, "a control frame on a request stream", ); b.finished = true; return error.EndOfStream; } b.source.discardAll64(length) catch |err| return b.readFault(err); }, } }
// More than was declared is knowable before the end, and is refused // before the excess reaches the handler. if (b.declared) |declared| if (b.received + b.remaining > declared) return b.malformed(); // More than this server reads, which with no `content-length` is // known only here. Not a reset: the request is well formed, and // `serveRequest` answers it with a `413`. if (b.received + b.remaining > b.max_len) { b.finished = true; b.too_large = true; return error.ReadFailed; }
const take = @min(b.remaining, limit.toInt() orelse b.remaining); const n = b.source.stream(w, .limited64(take)) catch |err| switch (err) { error.EndOfStream => return b.truncated(), else => |e| { b.finished = true; return e; }, }; b.remaining -= n; b.received += n; return n; }
fn readFault(b: *BodyReader, err: anyerror) error{ReadFailed} { if (err == error.EndOfStream) return b.truncated(); b.finished = true; return error.ReadFailed; }};
/// What a response needs to know: which stream it is going out on, and the/// writer it is going out through.const ResponseState = struct { connection: *Connection, stream: transport.Stream, writer: transport.Stream.Writer, body: BodyWriter = undefined, /// Whether the request's method allows a response body at all, which a /// `HEAD` does not: §9.3.2 of RFC 9110 has the response describe the body /// a `GET` would have had, and send none of it. method_has_body: bool = true, /// RFC 9220: the `:protocol` the client asked for, if it sent one. connect_protocol: ?[]const u8 = null, /// The reader the handler gets when the stream becomes a tunnel. reader: ?*Io.Reader = null, /// The request body's reader, which a handler's own `100 Continue` tells /// not to send another. body_reader: ?*BodyReader = null, /// What the body writer buffers into, so that a handler writing a line at /// a time does not spend a datagram on each line. body_buffer: [4096]u8 = undefined, /// Whether `body` has been initialised, which decides whether there is /// anything for `end` to flush. A response with no body never touches it, /// and flushing an undefined writer is a crash rather than a no-op. body_begun: bool = false,};
/// §7.2.1: the body, as DATA frames.////// One frame per drain rather than one per write, and nothing reaches the/// socket until the buffer fills or the handler flushes. The first version of/// this did the opposite -- no buffer, a frame per write, and a flush at the/// end of every one -- on the argument that a handler writing a line at a/// time is doing so on purpose and a driver should not decide otherwise for/// it. The argument is wrong twice over.////// It is wrong about this library, whose HTTP/1.1 driver buffers a body the/// same way and whose own demonstration server calls `flush` explicitly when/// it wants a line to leave -- so a handler already says when it means it,/// and the ones that do not were being charged for a decision they never/// made. And it is wrong about the cost, which is not the three octets of/// frame header it counted: every write became its own datagram. A megabyte/// written in sixty-six octet lines left as fifteen thousand packets of a/// hundred and seventeen octets, against the nine hundred a full-sized/// datagram needs, and the connection spent its time on packet headers,/// authentication tags and acknowledgements. It ran at two megabytes a/// second where the same handler over HTTP/1.1 ran at six hundred.////// A handler that means each line to leave on its own still gets exactly/// that, because `flush` is implemented here rather than inherited: it/// empties this buffer *and* the stream's, so an explicit flush reaches the/// wire. That is a stronger promise than the HTTP/1.1 driver makes.const BodyWriter = struct { interface: Io.Writer, state: *ResponseState, /// Whether a drain sends what it wrote instead of leaving it for the next /// one. A response batches; a tunnel does not, because a tunnel carries a /// conversation and an octet held back waiting for company is a peer /// waiting for an answer that has been written and not sent. when: When, /// What the response head declared, and so what becomes of what the /// handler writes. mode: Mode = .unknown, /// In `.exact`, how much of the declared length is still to come. remaining: u64 = 0,
const When = enum { batched, at_once };
/// The same three as the HTTP/2 driver's body writer, for the same /// reasons. const Mode = enum { /// A response with no content -- to a `HEAD`, or a `204` or a /// `304` -- whose body the handler may write anyway and which goes /// nowhere. §4.1.2 of RFC 9114 makes DATA frames on one malformed. discard, /// A declared length, which what is written may not exceed and has /// to reach. exact, unknown, };
fn init(state: *ResponseState, buffer: []u8, when: When) BodyWriter { return .{ .interface = .{ .vtable = &.{ .drain = drain, .flush = flushAll }, .buffer = buffer, }, .state = state, .when = when, }; }
/// Writes what is buffered here and whatever `data` adds, as one DATA /// frame, and leaves it in the stream writer rather than sending it. fn drain(io_writer: *Io.Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize { const b: *BodyWriter = @alignCast(@fieldParentPtr("interface", io_writer));
const buffered = io_writer.buffered(); const from_data = Io.Writer.countSplat(data, splat); if (buffered.len + from_data == 0) return 0;
try b.write(buffered, data, splat, buffered.len + from_data); io_writer.end = 0; if (b.when == .at_once) try b.state.writer.interface.flush(); return from_data; }
/// Empties this writer and the stream's, which is what makes an explicit /// `flush` in a handler mean "send this now" rather than "move it to /// another buffer". fn flushAll(io_writer: *Io.Writer) Io.Writer.Error!void { const b: *BodyWriter = @alignCast(@fieldParentPtr("interface", io_writer));
const buffered = io_writer.buffered(); if (buffered.len != 0) { try b.write(buffered, &.{}, 0, buffered.len); io_writer.end = 0; } try b.state.writer.interface.flush(); }
/// One frame header, then the octets it counted. fn write( b: *BodyWriter, buffered: []const u8, data: []const []const u8, splat: usize, total: usize, ) Io.Writer.Error!void { const out = &b.state.writer.interface;
switch (b.mode) { .discard => return, // §4.1.2: a `content-length` that does not equal the sum of the // DATA frames' lengths makes the response malformed, so more // than was declared is refused rather than sent. .exact => { if (total > b.remaining) return error.WriteFailed; b.remaining -= total; }, .unknown => {}, }
var header: [16]u8 = undefined; const n = frame.write(&header, .data, total) catch return error.WriteFailed; try out.writeAll(header[0..n]);
if (buffered.len != 0) try out.writeAll(buffered); if (data.len == 0) return; for (data[0 .. data.len - 1]) |bytes| try out.writeAll(bytes); const pattern = data[data.len - 1]; for (0..splat) |_| try out.writeAll(pattern); }};
const response_vtable: Response.VTable = .{ .beginBody = beginBody, .end = endBody, .sendInterim = sendInterim, .upgrade = upgrade,};
/// RFC 9220: hands the stream over, once the client has asked for a protocol/// this handler is willing to speak.////// The same exchange as RFC 8441's over HTTP/2 -- a `:protocol` in the/// request, a `2xx` rather than a `101`, and the stream becomes the tunnel --/// and simpler than either of the versions before it, for a reason worth/// stating.////// Over HTTP/1.1 an upgrade has to refuse when the request body has not been/// read, because those octets sit in the byte stream *in front of* the new/// protocol's first octet and handing the stream over would corrupt it. Over/// HTTP/2 that check is unnecessary because DATA frames are framed/// separately. Here it is unnecessary for a stronger reason: the request body/// and the tunnel are the same QUIC stream, delivered in order by the/// transport, so there is nothing to be in front of anything and nothing for/// this function to check.fn upgrade(res: *Response, protocol_name: []const u8) Response.UpgradeError!Response.Upgrade { const state: *ResponseState = @ptrCast(@alignCast(res.context.?)); const c = state.connection;
if (!c.config.enable_connect_protocol) return error.UpgradeUnavailable;
// RFC 9110 §7.8's rule with RFC 8441's spelling, which RFC 9220 inherits // unchanged: a server may not switch to a protocol the client did not ask // for, and here the asking is `:protocol` rather than an `Upgrade` field. const offered = state.connect_protocol orelse return error.NotOffered; if (!protocol.token.eqlIgnoreCase(offered, protocol_name)) return error.NotOffered;
// §5.1 of RFC 8441: `200`, not `101`. There is nothing to switch -- the // stream becomes the tunnel the moment a 2xx goes out -- and the driver // picks the status rather than the handler, the same way the HTTP/1.1 // side picks `101`. writeFieldSection(state, .ok, &res.headers, null) catch return error.WriteFailed;
// A body of no particular length, which is what a tunnel is, and one // that sends what it is given rather than waiting for more of it. state.body = .init(state, &.{}, .at_once); state.body_begun = true; return .{ .input = state.reader orelse return error.WriteFailed, .output = &state.body.interface, };}
fn beginBody(res: *Response, length: protocol.Length) Response.Error!*Io.Writer { const state: *ResponseState = @ptrCast(@alignCast(res.context.?)); const declared = try writeHead(state, res, length); // §4.1: the body goes out as DATA frames, so what the handler gets is a // writer that puts a frame header in front of what it is given rather // than the stream itself. state.body = .init(state, &state.body_buffer, .batched); state.body.mode = if (!Response.statusAllowsBody(res.status) or !state.method_has_body) .discard else switch (declared) { .none => .discard, .exact => .exact, .unknown => .unknown, }; state.body.remaining = switch (declared) { .exact => |n| n, else => 0, }; state.body_begun = true; return &state.body.interface;}
fn endBody(res: *Response) Response.Error!void { const state: *ResponseState = @ptrCast(@alignCast(res.context.?)); // Whatever the handler wrote last and did not flush. Before the trailers, // because §4.1 puts the second field section after the content and a // trailer that overtook the end of the body would describe something the // recipient had not been given yet. if (state.body_begun) state.body.interface.flush() catch return error.WriteFailed; // Short of the length declared, which is as malformed as over it. The // stream is left unfinished for the caller to end, because finishing it // would tell the client the response was whole. if (state.body_begun and state.body.mode == .exact and state.body.remaining != 0) return error.LengthMismatch; try sendTrailers(state, res); state.writer.finish() catch return error.WriteFailed;}
/// RFC 9114 §4.1: the trailer section, which is a second HEADERS frame after/// the DATA frames.////// Simpler again than HTTP/2's, which needs END_STREAM on the frame: here the/// end of the trailer section is the end of the QUIC stream, and the stream/// ends because the writer finishes it. One framing layer fewer, which is the/// pattern the whole driver has.fn sendTrailers(state: *ResponseState, res: *Response) Response.Error!void { if (res.trailers.fields.items.len == 0) return;
var fields: [64]qpack.Field = undefined; var count: usize = 0; for (res.trailers.fields.items) |f| { if (count == fields.len) break; // §6.5.1 of RFC 9110, and §4.1's own rule that a trailer section has // no pseudo-headers in it. if (Response.isForbiddenTrailer(f.name)) continue; if (f.name.len > 0 and f.name[0] == ':') continue; fields[count] = .{ .name = f.name, .value = f.value }; count += 1; } if (count == 0) return; try state.connection.holdToFieldLimit(fields[0..count]);
var section: [4096]u8 = undefined; var sw: Io.Writer = .fixed(§ion); qpack.encode(&sw, fields[0..count]) catch return error.WriteFailed; const body = sw.buffered();
var header: [16]u8 = undefined; const n = frame.write(&header, .headers, body.len) catch return error.WriteFailed; state.writer.interface.writeAll(header[0..n]) catch return error.WriteFailed; state.writer.interface.writeAll(body) catch return error.WriteFailed; state.writer.interface.flush() catch return error.WriteFailed;}
fn sendInterim(res: *Response, status: protocol.Status, headers: *const Headers) Response.Error!void { const state: *ResponseState = @ptrCast(@alignCast(res.context.?)); if (status == .@"continue") if (state.body_reader) |b| { b.asks = null; }; // §4.1: an informational response is a HEADERS frame like any other, and // more of them may follow. Which is what makes `103 Early Hints` work // here and over HTTP/2, where HTTP/1.0 silently drops it. try writeFieldSection(state, status, headers, null);}
/// §4.1: the status and the fields, as one HEADERS frame. Returns the length/// the head declared, which is the handler's unless the status allows no/// body at all.////// The `content-length` follows §8.6 of RFC 9110: none on a `204`, and on a/// `304` or a response to `HEAD` the length the body would have had, which is/// what the handler declared even though none of it is sent.fn writeHead(state: *ResponseState, res: *Response, length: protocol.Length) Response.Error!protocol.Length { const allows_body = Response.statusAllowsBody(res.status); const declared: protocol.Length = if (allows_body or res.status == .not_modified) length else .none; const content_length: ?u64 = switch (declared) { .exact => |n| n, .none => if (allows_body) 0 else null, .unknown => null, }; try writeFieldSection(state, res.status, &res.headers, content_length); return declared;}
fn writeFieldSection( state: *ResponseState, status: protocol.Status, headers: *const Headers, content_length: ?u64,) Response.Error!void { var fields: [64]qpack.Field = undefined; var count: usize = 0;
var status_text: [3]u8 = undefined; _ = std.fmt.bufPrint(&status_text, "{d}", .{@backingInt(status)}) catch return error.WriteFailed; fields[count] = .{ .name = ":status", .value = &status_text }; count += 1;
var length_text: [20]u8 = undefined; if (content_length) |n| { const text = std.fmt.bufPrint(&length_text, "{d}", .{n}) catch return error.WriteFailed; fields[count] = .{ .name = "content-length", .value = text }; count += 1; }
for (headers.fields.items) |field| { if (count == fields.len) break; // §4.2: "an endpoint MUST NOT generate an HTTP/3 field section // containing connection-specific fields", and the driver owns the // rest of these -- a handler that set `content-length` would be // setting it twice, and one that set `connection` would be describing // a hop that does not exist. if (isDriverField(field.name)) continue; if (field.name.len > 0 and field.name[0] == ':') continue; fields[count] = .{ .name = field.name, .value = field.value }; count += 1; } try state.connection.holdToFieldLimit(fields[0..count]);
var section: [8192]u8 = undefined; var sw: Io.Writer = .fixed(§ion); qpack.encode(&sw, fields[0..count]) catch return error.WriteFailed; const body = sw.buffered();
var header: [16]u8 = undefined; const n = frame.write(&header, .headers, body.len) catch return error.WriteFailed; state.writer.interface.writeAll(header[0..n]) catch return error.WriteFailed; state.writer.interface.writeAll(body) catch return error.WriteFailed; state.writer.interface.flush() catch return error.WriteFailed;}
/// §4.2.2: "An implementation that has received this parameter SHOULD NOT/// send an HTTP message header that exceeds the indicated size, as the peer/// will likely refuse to process it." The size is §4.2.2's, each field's name/// and value and 32 octets more, counted before compression.////// Checked before anything is written, so that a final head refused here/// leaves the response still unanswered and the handler's failure is/// answered with a bare `500`, which fits where the head did not.fn holdToFieldLimit(c: *Connection, fields: []const qpack.Field) Response.Error!void { var size: u64 = 0; for (fields) |f| size += f.name.len + f.value.len + 32; if (size > c.peer_max_field_section_size.load(.acquire)) return error.FieldSectionTooLarge;}
/// The fields this driver writes itself, which a handler may not.////// The same list as the HTTP/2 driver's, and for a sharper reason here:/// §4.2 of RFC 9114 makes a connection-specific field a malformed message/// rather than merely useless, because HTTP/3 has no hop for one to describe.fn isDriverField(name: []const u8) bool { const managed = [_][]const u8{ "content-length", "transfer-encoding", "connection", "keep-alive", "upgrade", "proxy-connection", }; for (managed) |m| { if (std.ascii.eqlIgnoreCase(name, m)) return true; } return false;}
/// §4.1 of RFC 9114: a server that "does not need to receive the remainder/// of the request" may "abort reading the request stream, send a complete/// response, and cleanly close the sending part of the stream", asking the/// client to stop with H3_NO_ERROR. Here the response is a `413`.fn refuseBody(c: *Connection, stream: transport.Stream) void { c.session.stopSending(stream.id, @backingInt(frame.Error.no_error)); c.respondStatus(stream, .payload_too_large);}
fn respondStatus(c: *Connection, stream: transport.Stream, status: protocol.Status) void { var out_buffer: [1024]u8 = undefined; var state: ResponseState = .{ .connection = c, .stream = stream, .writer = stream.writer(&out_buffer), }; const empty: Headers = .empty; writeFieldSection(&state, status, &empty, 0) catch |err| { // A client whose limit cannot fit even a bare status is answered // the one way left, so that the stream does not hang open. if (err == error.FieldSectionTooLarge) c.abort(stream, .internal_error); return; }; state.writer.finish() catch {};}
fn readFrameHeader(c: *Connection, r: *Io.Reader) !frame.Header { _ = c; // §16 of RFC 9000: a varint's first two bits say how long it is, and the // header's length is the two together -- which `Header.end` counts from. const kind_len = @as(usize, 1) << @intCast((try r.peekByte()) >> 6); const kind = try readVarint(r); const length_len = @as(usize, 1) << @intCast((try r.peekByte()) >> 6); const length = try readVarint(r); return .{ .kind = @fromBackingInt(@intCast(kind)), .length = length, .header_len = kind_len + length_len };}
/// §6.2: opens this endpoint's control stream and the two QPACK streams.fn openControlStreams(c: *Connection) !void { const control = try c.session.openUnidirectional(); c.control_out = control;
var buffer: [64]u8 = undefined; var w = control.writer(&buffer);
// §6.2: the stream type, then §7.2.4's SETTINGS, which "MUST be sent as // the first frame" on it. try writeVarint(&w.interface, @backingInt(frame.StreamType.control)); try writeSettings(&w.interface, c.config); try w.interface.flush();
// §4.2 of RFC 9204: both QPACK streams have to exist, even though this // encoder never inserts and so never sends anything on either. A peer // that waited for them before encoding would wait for ever. inline for (.{ frame.StreamType.qpack_encoder, frame.StreamType.qpack_decoder }) |kind| { const s = try c.session.openUnidirectional(); var b: [8]u8 = undefined; var sw = s.writer(&b); try writeVarint(&sw.interface, @backingInt(kind)); try sw.interface.flush(); }}
fn writeSettings(w: *Io.Writer, config: Config) !void { // Two settings and a body built first, because §7.2.4's frame carries its // length in front of it and the length is not known until the pairs are. var body: [32]u8 = undefined; var bw: Io.Writer = .fixed(&body); // §7.2.4.1. try writeVarint(&bw, 0x06); // SETTINGS_MAX_FIELD_SECTION_SIZE try writeVarint(&bw, config.max_field_section_size); // RFC 9204 §5: zero, which is this decoder saying it will keep no dynamic // table and so no peer may insert into one. try writeVarint(&bw, 0x01); // SETTINGS_QPACK_MAX_TABLE_CAPACITY try writeVarint(&bw, 0); try writeVarint(&bw, 0x07); // SETTINGS_QPACK_BLOCKED_STREAMS try writeVarint(&bw, 0); // RFC 9220 §3: the same identifier RFC 8441 gave it for HTTP/2, which is // the whole of what that document had to say about the wire. if (config.enable_connect_protocol) { try writeVarint(&bw, 0x08); // SETTINGS_ENABLE_CONNECT_PROTOCOL try writeVarint(&bw, 1); }
const payload = bw.buffered(); var header: [16]u8 = undefined; const n = try frame.write(&header, .settings, payload.len); try w.writeAll(header[0..n]); try w.writeAll(payload);}
fn writeVarint(w: *Io.Writer, value: u64) !void { var buf: [8]u8 = undefined; const written = quic.varint.write(&buf, value); try w.writeAll(written);}
/// §6.2: a unidirectional stream says what it is in its first varint.fn serveUnidirectional(c: *Connection, stream: transport.Stream) void { var buffer: [1024]u8 = undefined; var r = stream.reader(&buffer);
const kind = readVarint(&r.interface) catch return; switch (@as(frame.StreamType, @fromBackingInt(@intCast(kind)))) { .control => { // §6.2.1: "only one control stream per peer", and a second is // H3_STREAM_CREATION_ERROR. if (c.control_in_seen) { c.close(.stream_creation_error, "a second control stream"); return; } c.control_in_seen = true; c.readControl(&r.interface); }, // RFC 9204 §4.2: they exist and carry nothing, because this decoder // advertised no table for the peer to describe. Anything at all on // the encoder stream is an insertion into a table that was refused. // // Both are as critical as the control stream, and for the same // reason: "closing either unidirectional stream type MUST be treated // as a connection error of type H3_CLOSED_CRITICAL_STREAM". A peer // that ends one has ended the compression context the connection is // still using, whatever it may have meant by it. .qpack_encoder => { if (r.interface.takeByte()) |_| { c.close(.qpack_encoder_stream_error, "an insertion into a table of zero capacity"); } else |err| switch (err) { error.EndOfStream => c.close( .closed_critical_stream, "the peer closed its QPACK encoder stream", ), else => {}, } }, // Nothing this encoder sends can be acknowledged, since nothing it // sends uses a dynamic table, so the instructions here are read only // to notice the stream ending. .qpack_decoder => { _ = r.interface.discardRemaining() catch return; c.close(.closed_critical_stream, "the peer closed its QPACK decoder stream"); }, // §4.6: "a server MUST treat receipt of a push stream as a connection // error of type H3_STREAM_CREATION_ERROR", since a client has no // business pushing to a server. .push => c.close(.stream_creation_error, "a client push stream"), // §6.2: "recipients of unknown stream types MUST either abort reading // of the stream or discard incoming data without further processing" // -- the same tolerance the frame layer has, and for the same reason. // Aborted, with the code §6.2 suggests, rather than left: a stream // nobody reads holds the peer's flow-control credit for the life of // the connection. _ => c.session.stopSending(stream.id, @backingInt(frame.Error.stream_creation_error)), }}
/// §7.2.4: reads the peer's SETTINGS, then whatever else the control stream/// carries.fn readControl(c: *Connection, r: *Io.Reader) void { while (true) { // A read that fails is not the same as a stream that ended, and the // difference decides whether the peer has broken a rule or the // connection has simply gone. Reporting the second as the first sends // whoever reads the log looking for a protocol violation that never // happened, which is a worse bug than it looks: the line is the only // thing they have. const kind = readVarint(r) catch |err| switch (err) { error.EndOfStream => break, else => return, }; const length = readVarint(r) catch |err| switch (err) { error.EndOfStream => break, else => return, };
const f: frame.Kind = @fromBackingInt(@intCast(kind)); if (!f.allowedOnControlStream()) { c.close(.frame_unexpected, "a request frame on the control stream"); return; } // §7.2.4: "if the first frame of the control stream is any other // frame type, this MUST be treated as a connection error of type // H3_MISSING_SETTINGS." if (!c.peer_settings_seen) { if (f != .settings) { c.close(.missing_settings, "the control stream did not open with SETTINGS"); return; } c.peer_settings_seen = true; } else if (f == .settings) { // §7.2.4: "SETTINGS frames MUST NOT be sent subsequently." c.close(.frame_unexpected, "a second SETTINGS frame"); return; }
// §7.2.6: a GOAWAY, which is the one control frame a server has to // check rather than step over. if (f == .goaway) { if (!c.onGoaway(r, length)) return; continue; }
if (f == .settings) { const settings = frame.readSettings(r, length) catch |err| { switch (err) { error.Malformed => c.close(.frame_error, "a malformed SETTINGS frame"), error.ReservedSetting => c.close(.settings_error, "an HTTP/2 setting in SETTINGS"), error.ReadFailed => {}, } return; }; if (settings.max_field_section_size) |limit| c.peer_max_field_section_size.store(limit, .release); continue; }
// §7.2.3: "if a server receives a CANCEL_PUSH frame for a push ID // that has not yet been mentioned by a PUSH_PROMISE frame, this MUST // be treated as a connection error of type H3_ID_ERROR". This server // has never mentioned one and never will, so there is no push ID a // client can legitimately cancel and no value to read before saying // so. if (f == .cancel_push) { c.close(.id_error, "a CANCEL_PUSH for a push that was never promised"); return; }
// §7.2.7: "a MAX_PUSH_ID frame cannot reduce the maximum push ID". if (f == .max_push_id) { if (!c.onMaxPushId(r, length)) return; continue; }
// Anything else is a frame this server steps over, and is still read // to the end, because a stream is a stream and the next frame begins // where this one stops. r.discardAll64(length) catch return; }
// §6.2.1: "the sender MUST NOT close the control stream, and the receiver // MUST NOT request that the sender close it. If either control stream is // closed at any point, this MUST be treated as a connection error of type // H3_CLOSED_CRITICAL_STREAM." c.close(.closed_critical_stream, "the peer closed its control stream");}
/// §7.2.6: a GOAWAY from the client.////// False when the connection has been closed over it, so the caller stops/// reading. Two things are checked, and both are H3_ID_ERROR:////// The identifier a *client* sends is a push ID, not a stream ID -- "a client/// MUST send a push ID that is... the GOAWAY frame from a server contains a/// stream ID". This server promises no pushes, so the only push ID it can/// honestly have processed is none at all, and any value is acceptable to/// note and act on by not pushing, which it was not going to do.////// And a second GOAWAY may only name something lower: "the identifier in each/// frame MUST NOT be greater than the identifier in any previous frame". An/// increasing one would be a peer taking back a promise it had already made/// about what it would not accept, which is the one thing the frame exists to/// make reliable.fn onGoaway(c: *Connection, r: *Io.Reader, length: u64) bool { const got = readVarintSized(r) catch { c.close(.frame_error, "a truncated GOAWAY"); return false; }; // §7.1: a payload with anything beyond its one identifier is // H3_FRAME_ERROR. Not checking it read the excess as the next frame. if (got.len != length) { c.close(.frame_error, "a GOAWAY that is not one identifier"); return false; } const id = got.value; if (c.peer_goaway) |already| { if (id > already) { c.close(.id_error, "a GOAWAY naming a higher identifier than the last"); return false; } } c.peer_goaway = id;
// §5.2: the client is shutting down, so this endpoint stops taking new // requests from it as well. Not required of a server -- the frame is about // what the *client* will accept -- but a client that has said it is going // away is not one to start new work with, and answering the requests // already in flight is what both ends want. c.mutex.lockUncancelable(c.io); const last = c.next_request_stream; c.mutex.unlock(c.io); if (c.sent_goaway == null) { c.sent_goaway = last; } return true;}
/// §16 of RFC 9000's variable-length integer, read from a stream.////// The first two bits say how many octets there are, which is what makes this/// readable without a lookahead -- and `readSliceAll` for the rest, because a/// varint can straddle whatever boundary the stream happened to deliver on.fn readVarint(r: *Io.Reader) !u64 { return (try readVarintSized(r)).value;}
/// The same, and how many octets it took.////// §16 of RFC 9000 lets an encoder choose any width that holds the value, so/// the width cannot be worked back from the value -- and a frame whose body/// is one identifier is only well formed if that identifier fills it, which/// is a comparison nothing can make without this.fn readVarintSized(r: *Io.Reader) !struct { value: u64, len: usize } { const first = try r.takeByte(); const extra: usize = @as(usize, 1) << @as(u2, @intCast(first >> 6)); var buf: [8]u8 = undefined; buf[0] = first; if (extra > 1) try r.readSliceAll(buf[1..extra]); const parsed = try quic.varint.parse(buf[0..extra]); return .{ .value = parsed.value, .len = extra };}
/// §7.2.7: a client raising the number of pushes it would accept, which this/// server answers by continuing not to push.////// The frame is still checked, because the rule is about the sequence rather/// than about pushing: a value below the last one is H3_ID_ERROR whether or/// not either end ever intended to use the permission.fn onMaxPushId(c: *Connection, r: *Io.Reader, length: u64) bool { const got = readVarintSized(r) catch { c.close(.frame_error, "a truncated MAX_PUSH_ID"); return false; }; // §7.1: a frame body with anything in it beyond the fields the type // defines is H3_FRAME_ERROR. if (got.len != length) { c.close(.frame_error, "a MAX_PUSH_ID that is not one identifier"); return false; } if (c.peer_max_push_id) |already| { if (got.value < already) { c.close(.id_error, "a MAX_PUSH_ID smaller than the last"); return false; } } c.peer_max_push_id = got.value; return true;}
fn close(c: *Connection, code: frame.Error, why: []const u8) void { log.debug("connection error {s}: {s}", .{ @tagName(code), why }); c.session.close(@backingInt(code), why);}
test { std.testing.refAllDecls(@This());}
/// A request stream: `before` the HEADERS frame, a POST to `/` with/// `extra_fields`, and `after` it. Built in `buffer`, which it returns a slice/// of.fn testPostStream(buffer: []u8, extra_fields: []const qpack.Field, after: []const u8, before: []const u8) ![]const u8 { var fields_buf: [16]qpack.Field = undefined; const base = [_]qpack.Field{ .{ .name = ":method", .value = "POST" }, .{ .name = ":scheme", .value = "https" }, .{ .name = ":authority", .value = "example.com" }, .{ .name = ":path", .value = "/" }, }; @memcpy(fields_buf[0..base.len], &base); @memcpy(fields_buf[base.len..][0..extra_fields.len], extra_fields); var section: [256]u8 = undefined; var sw: Io.Writer = .fixed(§ion); try qpack.encode(&sw, fields_buf[0 .. base.len + extra_fields.len]); var w: Io.Writer = .fixed(buffer); try w.writeAll(before); var header: [16]u8 = undefined; try w.writeAll(header[0..try frame.write(&header, .headers, sw.buffered().len)]); try w.writeAll(sw.buffered()); try w.writeAll(after); return w.buffered();}
/// What `bodyHandler` found, for the tests below. One test at a time runs in/// a test binary, so a global is enough.var test_body: struct { len: usize = 0, failed: bool = false } = .{};
/// Reads the whole request body and answers "ok", noting in `test_body` how/// much there was or that the read failed.fn bodyHandler(req: *Request, res: *Response) Handler.Error!void { test_body = .{}; const got = req.body.readAlloc(std.testing.allocator, 1 << 20) catch { test_body.failed = true; return error.WriteFailed; }; defer std.testing.allocator.free(got); test_body.len = got.len; try res.send("ok");}
/// Runs a connection over the given incoming streams to the end.fn testRun(scripted: *transport.memory_session.Scripted, handler: Handler) void { var c: Connection = .init(std.testing.io, std.testing.allocator, scripted.session(std.testing.allocator), handler, .{}); c.run();}
test "RFC 9114 7.2.6: a GOAWAY with octets after its identifier is H3_FRAME_ERROR" { // A GOAWAY of length 3 whose identifier is one octet; the two octets after // it would otherwise have been read as a reserved frame of length zero. var scripted: transport.memory_session.Scripted = .{ .incoming = &.{ .{ .id = .{ .value = 2 }, .data = &.{ 0x00, 0x04, 0x00, 0x07, 0x03, 0x00, 0x21, 0x00 } }, } }; defer scripted.deinit(std.testing.allocator); testRun(&scripted, .initStateless(testHandler)); try std.testing.expectEqual(@as(u64, @backingInt(frame.Error.frame_error)), scripted.closed.?.code);}
test "RFC 9114 7.2.4.1: an HTTP/2 setting in SETTINGS is H3_SETTINGS_ERROR" { // 0x02 is HTTP/2's SETTINGS_ENABLE_PUSH. var scripted: transport.memory_session.Scripted = .{ .incoming = &.{ .{ .id = .{ .value = 2 }, .data = &.{ 0x00, 0x04, 0x02, 0x02, 0x00 } }, } }; defer scripted.deinit(std.testing.allocator); testRun(&scripted, .initStateless(testHandler)); try std.testing.expectEqual(@as(u64, @backingInt(frame.Error.settings_error)), scripted.closed.?.code);}
test "RFC 9114 9: an unknown frame type before HEADERS is stepped over" { var request: [256]u8 = undefined; const data = try testPostStream(&request, &.{}, "", &.{ 0x21, 0x00 }); var scripted: transport.memory_session.Scripted = .{ .incoming = &.{.{ .id = .{ .value = 0 }, .data = data }} }; defer scripted.deinit(std.testing.allocator); testRun(&scripted, .initStateless(testHandler)); try std.testing.expect(scripted.closed == null); try std.testing.expect(scripted.wrote(.{ .value = 0 }).?.len > 0);}
test "RFC 9114 4.1.2: a request stream ending inside a DATA frame is H3_REQUEST_INCOMPLETE" { // DATA claims ten octets and the stream ends after three, which the // handler used to be given as the whole body. var request: [256]u8 = undefined; const data = try testPostStream(&request, &.{}, &.{ 0x00, 0x0a, 'a', 'b', 'c' }, ""); var scripted: transport.memory_session.Scripted = .{ .incoming = &.{.{ .id = .{ .value = 0 }, .data = data }} }; defer scripted.deinit(std.testing.allocator); testRun(&scripted, .initStateless(bodyHandler)); try std.testing.expect(test_body.failed); try std.testing.expect(scripted.closed == null); try std.testing.expectEqual(@as(?u64, @backingInt(frame.Error.request_incomplete)), scripted.find(.{ .value = 0 }).?.reset);}
test "RFC 9114 4.1.2: a request stream ending inside its HEADERS frame is H3_REQUEST_INCOMPLETE" { // HEADERS claims five octets and the stream ends after one. This used to // get no answer at all, and the client waited for the idle timeout. var scripted: transport.memory_session.Scripted = .{ .incoming = &.{ .{ .id = .{ .value = 0 }, .data = &.{ 0x01, 0x05, 0x00 } }, } }; defer scripted.deinit(std.testing.allocator); testRun(&scripted, .initStateless(testHandler)); try std.testing.expect(scripted.closed == null); try std.testing.expectEqual(@as(?u64, @backingInt(frame.Error.request_incomplete)), scripted.find(.{ .value = 0 }).?.reset);}
test "RFC 9114 4.1.2: a request stream that ends before any frame is H3_REQUEST_INCOMPLETE" { var scripted: transport.memory_session.Scripted = .{ .incoming = &.{ .{ .id = .{ .value = 0 }, .data = &.{} }, } }; defer scripted.deinit(std.testing.allocator); testRun(&scripted, .initStateless(testHandler)); try std.testing.expect(scripted.closed == null); try std.testing.expectEqual(@as(?u64, @backingInt(frame.Error.request_incomplete)), scripted.find(.{ .value = 0 }).?.reset);}
test "RFC 9114 4.1.2: a request body shorter than its content-length is H3_MESSAGE_ERROR" { var request: [256]u8 = undefined; const data = try testPostStream(&request, &.{.{ .name = "content-length", .value = "10" }}, &.{ 0x00, 0x03, 'a', 'b', 'c' }, ""); var scripted: transport.memory_session.Scripted = .{ .incoming = &.{.{ .id = .{ .value = 0 }, .data = data }} }; defer scripted.deinit(std.testing.allocator); testRun(&scripted, .initStateless(bodyHandler)); try std.testing.expect(test_body.failed); try std.testing.expectEqual(@as(?u64, @backingInt(frame.Error.message_error)), scripted.find(.{ .value = 0 }).?.reset);}
test "RFC 9114 4.1.2: a request body longer than its content-length is H3_MESSAGE_ERROR" { var request: [256]u8 = undefined; const data = try testPostStream(&request, &.{.{ .name = "content-length", .value = "1" }}, &.{ 0x00, 0x03, 'a', 'b', 'c' }, ""); var scripted: transport.memory_session.Scripted = .{ .incoming = &.{.{ .id = .{ .value = 0 }, .data = data }} }; defer scripted.deinit(std.testing.allocator); testRun(&scripted, .initStateless(bodyHandler)); try std.testing.expect(test_body.failed); try std.testing.expectEqual(@as(?u64, @backingInt(frame.Error.message_error)), scripted.find(.{ .value = 0 }).?.reset);}
test "RFC 9114 4.1.2: a request body of its declared length reaches the handler whole" { var request: [256]u8 = undefined; const data = try testPostStream(&request, &.{.{ .name = "content-length", .value = "5" }}, &.{ 0x00, 0x02, 'a', 'b', 0x00, 0x03, 'c', 'd', 'e' }, ""); var scripted: transport.memory_session.Scripted = .{ .incoming = &.{.{ .id = .{ .value = 0 }, .data = data }} }; defer scripted.deinit(std.testing.allocator); testRun(&scripted, .initStateless(bodyHandler)); try std.testing.expect(!test_body.failed); try std.testing.expectEqual(@as(usize, 5), test_body.len); try std.testing.expect(scripted.find(.{ .value = 0 }).?.reset == null);}
/// Runs a connection with `max_body_len` of 4 over one request stream, and/// what came back on it.fn testLimitedBody(data: []const u8, handler: Handler) !struct { status: [3]u8, finished: bool, stopped: ?u64, reset: ?u64 } { var scripted: transport.memory_session.Scripted = .{ .incoming = &.{.{ .id = .{ .value = 0 }, .data = data }} }; defer scripted.deinit(std.testing.allocator); var c: Connection = .init(std.testing.io, std.testing.allocator, scripted.session(std.testing.allocator), handler, .{ .max_body_len = 4, }); c.run(); const state = scripted.find(.{ .value = 0 }).?; const head = try frame.parse(state.written.items); var fields: [8]qpack.Field = undefined; var scratch: [64]u8 = undefined; const n = try qpack.decode(state.written.items[head.header_len..head.end().?], &fields, &scratch); try std.testing.expect(n > 0); return .{ .status = fields[0].value[0..3].*, .finished = state.finished, .stopped = state.stopped, .reset = state.reset };}
test "a request declaring more body than max_body_len is answered 413 before the handler" { var request: [256]u8 = undefined; const data = try testPostStream(&request, &.{.{ .name = "content-length", .value = "5" }}, &.{ 0x00, 0x05, 'a', 'b', 'c', 'd', 'e' }, ""); test_body = .{ .len = 99 }; const got = try testLimitedBody(data, .initStateless(bodyHandler)); try std.testing.expectEqualStrings("413", &got.status); try std.testing.expect(got.finished); try std.testing.expectEqual(@as(?u64, @backingInt(frame.Error.no_error)), got.stopped); // The handler never ran. try std.testing.expectEqual(@as(usize, 99), test_body.len);}
test "a request body that runs past max_body_len is answered 413" { var request: [256]u8 = undefined; // No content-length, so only reading it finds out. const data = try testPostStream(&request, &.{}, &.{ 0x00, 0x03, 'a', 'b', 'c', 0x00, 0x02, 'd', 'e' }, ""); const got = try testLimitedBody(data, .initStateless(bodyHandler)); try std.testing.expect(test_body.failed); try std.testing.expectEqualStrings("413", &got.status); try std.testing.expect(got.finished); try std.testing.expectEqual(@as(?u64, null), got.reset); try std.testing.expectEqual(@as(?u64, @backingInt(frame.Error.no_error)), got.stopped);
// Up to the limit is read as ever. const within = try testPostStream(&request, &.{}, &.{ 0x00, 0x02, 'a', 'b', 0x00, 0x02, 'c', 'd' }, ""); const ok = try testLimitedBody(within, .initStateless(bodyHandler)); try std.testing.expect(!test_body.failed); try std.testing.expectEqual(@as(usize, 4), test_body.len); try std.testing.expectEqualStrings("200", &ok.status);}
/// Answers with an `x-big` field of `test_big_len` octets, once the client's/// SETTINGS have been read: the control stream is read on a task of its own,/// and a handler that ran first would be answering a client with no limit.var test_big_len: usize = 0;
fn bigFieldHandler(req: *Request, res: *Response) Handler.Error!void { _ = req; const state: *ResponseState = @ptrCast(@alignCast(res.context.?)); while (state.connection.peer_max_field_section_size.load(.acquire) == std.math.maxInt(u64)) try std.testing.io.sleep(.fromMilliseconds(1), .awake); const big: [80]u8 = @splat('a'); try res.headers.append(res.arena, "x-big", big[0..test_big_len]); try res.send("ok");}
test "RFC 9114 4.2.2: a response head over the client's limit is not sent" { var request: [256]u8 = undefined; const data = try testRequestStream(&request); // A control stream whose SETTINGS put SETTINGS_MAX_FIELD_SECTION_SIZE // (0x06) at 200, a two-octet varint. const control = [_]u8{ 0x00, 0x04, 0x03, 0x06, 0x40, 0xc8 };
for ([_]struct { len: usize, status: []const u8 }{ // :status, content-length and x-big come to 7+3+32, 14+1+32 and // 5+75+32, which is 201 and over the limit; with 64 octets it is // 190, which is under it. .{ .len = 75, .status = "500" }, .{ .len = 64, .status = "200" }, }) |case| { test_big_len = case.len; var scripted: transport.memory_session.Scripted = .{ .incoming = &.{ .{ .id = .{ .value = 2 }, .data = &control }, .{ .id = .{ .value = 0 }, .data = data }, } }; defer scripted.deinit(std.testing.allocator); testRun(&scripted, .initStateless(bigFieldHandler));
const state = scripted.find(.{ .value = 0 }).?; const head = try frame.parse(state.written.items); var fields: [8]qpack.Field = undefined; var scratch: [256]u8 = undefined; const n = try qpack.decode(state.written.items[head.header_len..head.end().?], &fields, &scratch); try std.testing.expect(n > 0); try std.testing.expectEqualStrings(":status", fields[0].name); try std.testing.expectEqualStrings(case.status, fields[0].value); try std.testing.expect(state.finished); }}
const unknown_stream: [2000]u8 = .{0x21} ++ @as([1999]u8, @splat('x'));
test "RFC 9114 6.2: an unknown unidirectional stream type is aborted" { // Larger than one read buffer, so that a stream merely abandoned shows up // as one only partly read. var scripted: transport.memory_session.Scripted = .{ .incoming = &.{ .{ .id = .{ .value = 2 }, .data = &unknown_stream }, } }; defer scripted.deinit(std.testing.allocator); testRun(&scripted, .initStateless(testHandler)); try std.testing.expectEqual(@as(?u64, @backingInt(frame.Error.stream_creation_error)), scripted.find(.{ .value = 2 }).?.stopped);}