// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // 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); }