// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! The HTTP/3 driver end to end, over a real UDP socket. //! //! The client here is written by hand rather than borrowed, and that is the //! whole value of the test: it encodes its own field section, opens its own //! control stream, and frames its own request, so nothing it does comes from //! the code it is checking except the QPACK encoder -- which is anchored //! separately by the representation tests in `qpack`. //! //! What it proves is the part a unit test cannot reach. The driver's pieces //! all compiled before any of this existed; whether a datagram arriving on a //! socket becomes a `Request`, and whether what a handler writes comes back //! as DATA frames a client can read, is a different question and the only one //! that matters. const std = @import("std"); const Io = std.Io; const net = Io.net; const testing = std.testing; const http = @import("http"); const quic = @import("quic"); const quic_io = @import("quic_io"); const http_io = @import("http_io"); const h3 = http.http3; /// The listener owns a UDP socket, so it lives in the I/O module; everything /// else about HTTP/3 is in `http`. const h3_io = http_io.http3; /// Answers every request with what it was asked, so that the test can tell a /// request that arrived from one that was invented. /// What this file's hand-rolled client gives each of its connections, which /// is also what it may advertise. The library's defaults: these tests are /// about HTTP/3 and not about how fast QUIC can be made to go. const client_sizes: quic.Connection.Sizes = .{}; fn echo(_: ?*anyopaque, req: *http.server.Request, res: *http.server.Response) anyerror!void { try res.headers.append(res.arena, "content-type", "text/plain"); var body: [256]u8 = undefined; const text = try std.fmt.bufPrint(&body, "{s} {s} {s}", .{ req.method.name, req.target.raw, req.version.toString(), }); try res.send(text); } test "RFC 9114: a request over QUIC becomes the same Request a handler has always seen" { const io = testing.io; const gpa = testing.allocator; var rng_impl = std.Random.DefaultPrng.init(0x9114); const rng = rng_impl.random(); const bind: net.IpAddress = try .parse("127.0.0.1", 0); var socket = try bind.bind(io, .{ .mode = .dgram }); defer socket.close(io); const address = socket.address; var listener: h3_io.Listener = undefined; try listener.init(io, gpa, &socket, .{ .context = null, .serveFn = echo, }, .{ .rng = rng, .reset_key = @splat(0x33), .token_key = @splat(0x44), .max_connections = 2, }); defer listener.deinit(); var group: Io.Group = .init; defer group.cancel(io); try group.concurrent(io, run, .{&listener}); // Stopped whatever happens, so that a failure ends the test rather than // leaving the pump running and the teardown waiting on it. defer listener.stop(); var answer: [256]u8 = undefined; const got = try ask(io, gpa, address, rng, &answer); // The handler saw a `GET /hello` over HTTP/3, and said so. try testing.expectEqualStrings("GET /hello HTTP/3", got); } test "RFC 9114 4.2: an upper case field name is a stream error, not a status" { // Found by pointing aioquic at this server, which is the only client here // willing to send such a thing: curl lower cases on the way out, so no // assertion built on curl can reach the rule at all. // // §4.2 says a field name "MUST be converted to lowercase prior to their // encoding" and that a message containing an upper case one "MUST be // treated as malformed", and §4.1.2 says a malformed message is "a stream // error of type H3_MESSAGE_ERROR". This server used to answer `400`, // which is friendlier and is not what the rule says -- and the difference // is not cosmetic, because a status code claims the request was // understood well enough to be answered, which a field section this // server has refused to read plainly was not. const io = testing.io; const gpa = testing.allocator; var rng_impl = std.Random.DefaultPrng.init(0x0402); const rng = rng_impl.random(); const bind: net.IpAddress = try .parse("127.0.0.1", 0); var socket = try bind.bind(io, .{ .mode = .dgram }); defer socket.close(io); const address = socket.address; var listener: h3_io.Listener = undefined; try listener.init(io, gpa, &socket, .{ .context = null, .serveFn = echo, }, .{ .rng = rng, .reset_key = @splat(0x33), .token_key = @splat(0x44), .max_connections = 2, }); defer listener.deinit(); var group: Io.Group = .init; defer group.cancel(io); try group.concurrent(io, run, .{&listener}); defer listener.stop(); // Written by hand, because this library's own encoder lower cases a // field name on the way out and so cannot produce the thing under test -- // the same reason `tests/h2/frames.zig` carries an HPACK writer of its // own. An encoder that normalizes is the right encoder; it just makes a // poor adversary. var section: [256]u8 = undefined; var sw: Io.Writer = .fixed(§ion); try sw.writeByte(0); // §4.5.1: Required Insert Count, zero try sw.writeByte(0); // and Base, zero try putLiteral(&sw, ":method", "GET"); try putLiteral(&sw, ":scheme", "https"); try putLiteral(&sw, ":path", "/hello"); try putLiteral(&sw, ":authority", "h3.example"); try putLiteral(&sw, "X-Upper", "no"); var answer: [256]u8 = undefined; const outcome = try speak(io, gpa, address, rng, &answer, sw.buffered()); switch (outcome) { .reset => |code| try testing.expectEqual( @intFromEnum(h3.frame.Error.message_error), code, ), .answered => |bytes| { std.debug.print("expected a reset, got {s}\n", .{bytes}); return error.TestUnexpectedResult; }, } } /// §4.5.6 of RFC 9204: a literal field line with a literal name, with neither /// half Huffman coded and neither length long enough to need a continuation. /// /// Seven lines, and deliberately not the library's encoder: what is being /// tested is what this server does with octets somebody else chose. fn putLiteral(w: *Io.Writer, name: []const u8, value: []const u8) !void { // `001` marks the pattern, the `N` and `H` bits are zero, and the name's // length is what is left, which is three bits and not four -- getting // that wrong makes the section undecodable rather than malformed, and // the server answers a connection error instead of the stream error // under test. try putPrefixed(w, 0x20, 3, name.len); try w.writeAll(name); // The value's `H` bit is zero and its length is a seven bit prefix. try putPrefixed(w, 0x00, 7, value.len); try w.writeAll(value); } /// §4.1.1 of RFC 9204, which is §5.1 of RFC 7541 unchanged: an integer in the /// low `bits` of a byte whose high bits are already spoken for, continuing /// into as many further bytes as it takes. fn putPrefixed(w: *Io.Writer, pattern: u8, bits: u3, value: usize) !void { const max: usize = (@as(usize, 1) << bits) - 1; if (value < max) return w.writeByte(pattern | @as(u8, @intCast(value))); try w.writeByte(pattern | @as(u8, @intCast(max))); var left = value - max; while (left >= 128) : (left /= 128) try w.writeByte(@intCast(left % 128 + 128)); try w.writeByte(@intCast(left)); } /// Five lines, each flushed, and five more that are not. /// /// The two halves are the whole of what this handler is for: a flush means /// "send this now" and its absence means "send it when convenient", and the /// number of DATA frames that come out is the only way to tell from outside /// which of the two a driver did. fn lines(_: ?*anyopaque, _: *http.server.Request, res: *http.server.Response) anyerror!void { const w = try res.beginBody(.unknown); for (0..5) |i| { try w.print("flushed {d}\n", .{i}); try w.flush(); } for (0..5) |i| try w.print("batched {d}\n", .{i}); try res.end(); } test "RFC 9114 7.2.1: a flush is a DATA frame, and not flushing is not" { // The body writer buffers, because a driver that sent every write as its // own DATA frame sent every write as its own datagram -- a megabyte of // sixty-six octet lines left as fifteen thousand packets averaging a // hundred and seventeen octets, and ran at a sixth of the speed it does // now. // // What buffering must not cost is the handler's ability to say when // something leaves. So `flush` is implemented on the body writer rather // than inherited, and empties the stream writer as well, and this is the // assertion that it does: five flushed lines are five frames, and five // unflushed ones are one. const io = testing.io; const gpa = testing.allocator; var rng_impl = std.Random.DefaultPrng.init(0x7201); const rng = rng_impl.random(); const bind: net.IpAddress = try .parse("127.0.0.1", 0); var socket = try bind.bind(io, .{ .mode = .dgram }); defer socket.close(io); const address = socket.address; var listener: h3_io.Listener = undefined; try listener.init(io, gpa, &socket, .{ .context = null, .serveFn = lines, }, .{ .rng = rng, .reset_key = @splat(0x33), .token_key = @splat(0x44), .max_connections = 2, }); defer listener.deinit(); var group: Io.Group = .init; defer group.cancel(io); try group.concurrent(io, run, .{&listener}); defer listener.stop(); var raw: [8192]u8 = undefined; const stream = try askRaw(io, gpa, address, rng, &raw); var frames: usize = 0; var body: [512]u8 = undefined; var used: usize = 0; var at: usize = 0; while (at < stream.len) { const kind = try quic.varint.parse(stream[at..]); at += kind.len; const length = try quic.varint.parse(stream[at..]); at += length.len; const end = at + @as(usize, @intCast(length.value)); if (end > stream.len) break; if (kind.value == 0x00) { frames += 1; @memcpy(body[used..][0..(end - at)], stream[at..end]); used += end - at; } at = end; } // Everything arrived, in order, whichever way it was framed. var want: [512]u8 = undefined; var wants: Io.Writer = .fixed(&want); for (0..5) |i| try wants.print("flushed {d}\n", .{i}); for (0..5) |i| try wants.print("batched {d}\n", .{i}); try testing.expectEqualStrings(wants.buffered(), body[0..used]); // Five flushes, then one frame for everything after them. A driver that // buffered the flushed lines too would send fewer; one that flushed every // write would send ten. try testing.expectEqual(@as(usize, 6), frames); } /// A response whose trailer is only knowable once the body has been produced. /// A response whose trailer is only knowable once the body has been produced. fn trailered(_: ?*anyopaque, _: *http.server.Request, res: *http.server.Response) anyerror!void { const w = try res.beginBody(.unknown); try w.writeAll("abcde"); try res.trailers.append(res.arena, "x-length", "5"); // §6.5.1 of RFC 9110: refused on the way out, wherever a handler puts it. try res.trailers.append(res.arena, "content-length", "99"); return res.end(); } test "RFC 9114 4.1: a trailer section is a second HEADERS frame" { // The same semantics as HTTP/1.1's chunked trailer section and HTTP/2's // second field block, in the framing HTTP/3 already has: a HEADERS frame // after the DATA frames, ending where the stream does. One layer fewer // than either -- there is no chunked coding to arrange and no END_STREAM // flag to set, because QUIC says where the stream stops. const io = testing.io; const gpa = testing.allocator; var rng_impl = std.Random.DefaultPrng.init(0x0401); const rng = rng_impl.random(); const bind: net.IpAddress = try .parse("127.0.0.1", 0); var socket = try bind.bind(io, .{ .mode = .dgram }); defer socket.close(io); const address = socket.address; var listener: h3_io.Listener = undefined; try listener.init(io, gpa, &socket, .{ .context = null, .serveFn = trailered, }, .{ .rng = rng, .reset_key = @splat(0x77), .token_key = @splat(0x88), .max_connections = 2, }); defer listener.deinit(); var group: Io.Group = .init; defer group.cancel(io); try group.concurrent(io, run, .{&listener}); defer listener.stop(); var answer: [256]u8 = undefined; var trailer_value: [64]u8 = undefined; const trailer = try askForTrailers(io, gpa, address, rng, &answer, &trailer_value); try testing.expectEqualStrings("x-length", trailer.name); try testing.expectEqualStrings("5", trailer.value); // The forbidden one did not travel. try testing.expect(!trailer.saw_content_length); } const Trailer = struct { name: []const u8, value: []const u8, saw_content_length: bool, }; fn run(listener: *h3_io.Listener) void { listener.run() catch {}; } /// A hand-written HTTP/3 client: handshake, control stream, one request. /// /// Returns the body, which is what most callers want. `askRaw` returns the /// whole response stream for the one that wants the second field section. fn ask( io: Io, gpa: std.mem.Allocator, to: net.IpAddress, rng: std.Random, answer: []u8, ) ![]const u8 { var raw: [8192]u8 = undefined; const stream = try askRaw(io, gpa, to, rng, &raw); return readResponse(stream, answer); } fn askRaw( io: Io, gpa: std.mem.Allocator, to: net.IpAddress, rng: std.Random, answer: []u8, ) ![]const u8 { var section: [512]u8 = undefined; var sw: Io.Writer = .fixed(§ion); try h3.qpack.encode(&sw, default_fields); return switch (try speak(io, gpa, to, rng, answer, sw.buffered())) { .answered => |bytes| bytes, .reset => error.StreamReset, }; } /// The field section a well-formed request carries here, which every test but /// the malformed one uses. const default_fields: []const h3.qpack.Field = &.{ .{ .name = ":method", .value = "GET" }, .{ .name = ":scheme", .value = "https" }, .{ .name = ":path", .value = "/hello" }, .{ .name = ":authority", .value = "h3.example" }, }; /// What became of the request stream: an answer, or the code the server reset /// it with. §4.1.2 makes the second one an outcome rather than a failure, so /// it is a case of the return value and not an error. const Outcome = union(enum) { answered: []const u8, reset: u64, }; fn speak( io: Io, gpa: std.mem.Allocator, to: net.IpAddress, rng: std.Random, answer: []u8, section: []const u8, ) !Outcome { var local_id: [8]u8 = undefined; rng.bytes(&local_id); var destination: [8]u8 = undefined; rng.bytes(&destination); const parameters: quic.parameters.Parameters = .{ // What this client's own buffers hold, which `Connection.init` // asserts: a window is a promise about room, and the room here is // `client_sizes` and nothing else. .initial_max_data = quic.Connection.max_streams * client_sizes.recv_window, .initial_max_stream_data_bidi_local = client_sizes.recv_window, .initial_max_stream_data_bidi_remote = client_sizes.recv_window, .initial_max_streams_bidi = 4, .initial_max_stream_data_uni = client_sizes.recv_window, .initial_max_streams_uni = 8, .max_idle_timeout = 5_000, .active_connection_id_limit = 4, .initial_source_connection_id = &local_id, }; var encoded: [256]u8 = undefined; const written = try quic.parameters.write(¶meters, &encoded, .client); var tls_client: quic.tls_handshake.Client = try .init(.{ .host = "h3.example", .root_ca = .{ .bytes = .empty, .map = .empty }, // §3.1: the token is `h3` and nothing else. .alpn_protocols = &.{"h3"}, .transport_parameters = written, .rng = rng, .now_sec = 0, .insecure_skip_verify = true, }); const memory = try gpa.create(quic.Connection.Storage(client_sizes)); defer gpa.destroy(memory); const connection = try gpa.create(quic.Connection); defer gpa.destroy(connection); connection.init(.{ .role = .client, .memory = memory.memory(), .handshake = tls_client.handshake(), .local_id = &local_id, .destination_id = &destination, .local = parameters, .rng = rng, }); const from: net.IpAddress = try .parse("127.0.0.1", 0); var socket = try from.bind(io, .{ .mode = .dgram }); defer socket.close(io); const origin = Io.Timestamp.now(io, .awake); var out: [2048]u8 = undefined; var in: [2048]u8 = undefined; var sent = false; var request_stream: quic.stream.Id = .{ .value = 0 }; var steps: usize = 0; while (steps < 200) : (steps += 1) { const at: u64 = @intCast(@max( Io.Timestamp.now(io, .awake).nanoseconds - origin.nanoseconds, 0, )); if (connection.isEstablished() and !sent) { // §6.2: the control stream, and SETTINGS first on it. A server // that never sees one is entitled to close the connection, so // this is not optional politeness. const control = try connection.openUnidirectional(); var control_buf: [64]u8 = undefined; var cw: Io.Writer = .fixed(&control_buf); try putVarint(&cw, 0x00); // control try putVarint(&cw, 0x04); // SETTINGS try putVarint(&cw, 0x00); // of length zero try connection.write(control, cw.buffered()); // §4.2 of RFC 9204: both QPACK streams exist and carry nothing. for ([_]u64{ 0x02, 0x03 }) |kind| { const s = try connection.openUnidirectional(); var b: [8]u8 = undefined; var bw: Io.Writer = .fixed(&b); try putVarint(&bw, kind); try connection.write(s, bw.buffered()); } // §4.1: a HEADERS frame carrying a QPACK field section. request_stream = try connection.openBidirectional(); var head: [16]u8 = undefined; const n = try h3.frame.write(&head, .headers, section.len); try connection.write(request_stream, head[0..n]); try connection.write(request_stream, section); try connection.finishStream(request_stream); sent = true; } while (try connection.send(&out, at)) |datagram| { try socket.send(io, &to, datagram.bytes); } if (sent) { if (connection.streamResetCode(request_stream)) |code| return .{ .reset = code }; const available = connection.readable(request_stream); if (available.len > 0 and connection.streamReceived(request_stream)) { const n = @min(available.len, answer.len); @memcpy(answer[0..n], available[0..n]); return .{ .answered = answer[0..n] }; } } const message = socket.receiveTimeout(io, &in, .{ .duration = .{ .raw = .{ .nanoseconds = 200 * std.time.ns_per_ms }, .clock = .awake, } }) catch |err| switch (err) { error.Timeout => { connection.onTimeout(at); continue; }, else => return err, }; try connection.receive(message.data, 0, at); } return error.NoAnswer; } /// Reads the HEADERS frame and whatever DATA frames follow, and returns the /// body -- which is the part the handler wrote. /// The same exchange, keeping the *second* field section rather than the /// body -- which is what a trailer section is. fn askForTrailers( io: Io, gpa: std.mem.Allocator, to: net.IpAddress, rng: std.Random, answer: []u8, value_out: []u8, ) !Trailer { const bytes = try askRaw(io, gpa, to, rng, answer); var at: usize = 0; var sections: usize = 0; var found: ?Trailer = null; var saw_content_length = false; var name_out: [64]u8 = undefined; while (at < bytes.len) { const kind = try quic.varint.parse(bytes[at..]); at += kind.len; const length = try quic.varint.parse(bytes[at..]); at += length.len; const end = at + @as(usize, @intCast(length.value)); if (end > bytes.len) return error.Truncated; if (kind.value == 0x01) { sections += 1; // §4.1: the first field section is the response head; a second // one, after the DATA frames, is the trailer section. if (sections == 2) { var fields: [16]h3.qpack.Field = undefined; var scratch: [1024]u8 = undefined; const n = try h3.qpack.decode(bytes[at..end], &fields, &scratch); for (fields[0..n]) |f| { if (std.mem.eql(u8, f.name, "content-length")) saw_content_length = true; if (found != null) continue; @memcpy(name_out[0..f.name.len], f.name); @memcpy(value_out[0..f.value.len], f.value); found = .{ .name = name_out[0..f.name.len], .value = value_out[0..f.value.len], .saw_content_length = false, }; } } } at = end; } var trailer = found orelse return error.NoTrailerSection; trailer.saw_content_length = saw_content_length; return trailer; } /// An extended CONNECT, and then speaking into the stream it opens. /// /// Unlike `ask`, the request half is *not* ended: a tunnel with a closed /// sending half is not a tunnel, and §5 of RFC 8441 makes ending the stream /// the way it is closed. So the client writes its DATA frame after the /// request rather than before the FIN, which is the whole shape of a /// bootstrapped protocol. fn connectAndSpeak( io: Io, gpa: std.mem.Allocator, to: net.IpAddress, rng: std.Random, answer: []u8, ) ![]const u8 { var local_id: [8]u8 = undefined; rng.bytes(&local_id); var destination: [8]u8 = undefined; rng.bytes(&destination); const parameters: quic.parameters.Parameters = .{ // What this client's own buffers hold, which `Connection.init` // asserts: a window is a promise about room, and the room here is // `client_sizes` and nothing else. .initial_max_data = quic.Connection.max_streams * client_sizes.recv_window, .initial_max_stream_data_bidi_local = client_sizes.recv_window, .initial_max_stream_data_bidi_remote = client_sizes.recv_window, .initial_max_streams_bidi = 4, .initial_max_stream_data_uni = client_sizes.recv_window, .initial_max_streams_uni = 8, .max_idle_timeout = 5_000, .active_connection_id_limit = 4, .initial_source_connection_id = &local_id, }; var encoded: [256]u8 = undefined; const written = try quic.parameters.write(¶meters, &encoded, .client); var tls_client: quic.tls_handshake.Client = try .init(.{ .host = "h3.example", .root_ca = .{ .bytes = .empty, .map = .empty }, .alpn_protocols = &.{"h3"}, .transport_parameters = written, .rng = rng, .now_sec = 0, .insecure_skip_verify = true, }); const memory = try gpa.create(quic.Connection.Storage(client_sizes)); defer gpa.destroy(memory); const connection = try gpa.create(quic.Connection); defer gpa.destroy(connection); connection.init(.{ .role = .client, .memory = memory.memory(), .handshake = tls_client.handshake(), .local_id = &local_id, .destination_id = &destination, .local = parameters, .rng = rng, }); const from: net.IpAddress = try .parse("127.0.0.1", 0); var socket = try from.bind(io, .{ .mode = .dgram }); defer socket.close(io); const origin = Io.Timestamp.now(io, .awake); var out: [2048]u8 = undefined; var in: [2048]u8 = undefined; var sent = false; var request_stream: quic.stream.Id = .{ .value = 0 }; var steps: usize = 0; while (steps < 200) : (steps += 1) { const at: u64 = @intCast(@max( Io.Timestamp.now(io, .awake).nanoseconds - origin.nanoseconds, 0, )); if (connection.isEstablished() and !sent) { const control = try connection.openUnidirectional(); var control_buf: [64]u8 = undefined; var cw: Io.Writer = .fixed(&control_buf); try putVarint(&cw, 0x00); try putVarint(&cw, 0x04); try putVarint(&cw, 0x00); try connection.write(control, cw.buffered()); for ([_]u64{ 0x02, 0x03 }) |kind| { const u = try connection.openUnidirectional(); var b: [8]u8 = undefined; var bw: Io.Writer = .fixed(&b); try putVarint(&bw, kind); try connection.write(u, bw.buffered()); } // RFC 8441 §4, unchanged by RFC 9220: CONNECT with `:protocol`, // and unlike an ordinary CONNECT it carries `:scheme` and // `:path` as well -- which is what distinguishes the extended // form from the tunnel-to-an-authority one. var section: [512]u8 = undefined; var sw: Io.Writer = .fixed(§ion); try h3.qpack.encode(&sw, &.{ .{ .name = ":method", .value = "CONNECT" }, .{ .name = ":protocol", .value = "echo" }, .{ .name = ":scheme", .value = "https" }, .{ .name = ":path", .value = "/tunnel" }, .{ .name = ":authority", .value = "h3.example" }, }); request_stream = try connection.openBidirectional(); var head: [16]u8 = undefined; const n = try h3.frame.write(&head, .headers, sw.buffered().len); try connection.write(request_stream, head[0..n]); try connection.write(request_stream, sw.buffered()); // Into the tunnel, as a DATA frame, without ending this half. const message = "hello through the tunnel"; var data_head: [16]u8 = undefined; const dn = try h3.frame.write(&data_head, .data, message.len); try connection.write(request_stream, data_head[0..dn]); try connection.write(request_stream, message); sent = true; } while (try connection.send(&out, at)) |datagram| { try socket.send(io, &to, datagram.bytes); } if (sent) { const available = connection.readable(request_stream); // The server ends the stream when the handler stops speaking, // which is §5's orderly close. // The status, and then the connection is kept alive until the // handler has read its half. A tunnel is two independent // directions -- which is the whole point of one -- so the client // does not stop pumping the moment its own half is answered. // The status, and then the echo that comes back through the // tunnel -- which is the direction that needs both halves to // stay open. if (readStatus(available, answer)) |_| { if (echoedPayload(available)) |payload| { const n = @min(payload.len, answer.len); @memcpy(answer[0..n], payload[0..n]); return answer[0..n]; } } } const message = socket.receiveTimeout(io, &in, .{ .duration = .{ .raw = .{ .nanoseconds = 200 * std.time.ns_per_ms }, .clock = .awake, } }) catch |err| switch (err) { error.Timeout => { connection.onTimeout(at); continue; }, else => return err, }; try connection.receive(message.data, 0, at); } return error.NoAnswer; } /// The payload of the first DATA frame after the response head, which is the /// server's half of the tunnel. fn echoedPayload(bytes: []const u8) ?[]const u8 { var at: usize = 0; while (at < bytes.len) { const kind = quic.varint.parse(bytes[at..]) catch return null; at += kind.len; const length = quic.varint.parse(bytes[at..]) catch return null; at += length.len; const end = at + @as(usize, @intCast(length.value)); if (end > bytes.len) return null; if (kind.value == 0x00 and length.value > 0) return bytes[at..end]; at = end; } return null; } /// The `:status` from the first field section, or null while it has not all /// arrived. fn readStatus(bytes: []const u8, out: []u8) ?[]const u8 { if (bytes.len < 2) return null; const kind = quic.varint.parse(bytes) catch return null; const length = quic.varint.parse(bytes[kind.len..]) catch return null; const at = kind.len + length.len; const end = at + @as(usize, @intCast(length.value)); if (kind.value != 0x01 or end > bytes.len) return null; var fields: [16]h3.qpack.Field = undefined; var scratch: [1024]u8 = undefined; const n = h3.qpack.decode(bytes[at..end], &fields, &scratch) catch return null; for (fields[0..n]) |f| { if (!std.mem.eql(u8, f.name, ":status")) continue; @memcpy(out[0..f.value.len], f.value); return out[0..f.value.len]; } return null; } fn readResponse(bytes: []const u8, answer: []u8) ![]const u8 { var at: usize = 0; var used: usize = 0; var saw_headers = false; while (at < bytes.len) { const kind = try quic.varint.parse(bytes[at..]); at += kind.len; const length = try quic.varint.parse(bytes[at..]); at += length.len; const end = at + @as(usize, @intCast(length.value)); if (end > bytes.len) return error.Truncated; switch (kind.value) { 0x01 => { // §4.1: the response head. Decoded with the library's own // QPACK, which is legitimate here for the reason the HTTP/2 // suite gives for the same choice: by this point the decoder // has already correctly understood a request encoded by the // hand-written encoder above. var fields: [16]h3.qpack.Field = undefined; var scratch: [1024]u8 = undefined; const n = try h3.qpack.decode(bytes[at..end], &fields, &scratch); var status: []const u8 = ""; for (fields[0..n]) |f| { if (std.mem.eql(u8, f.name, ":status")) status = f.value; } if (!std.mem.eql(u8, status, "200")) return error.NotOk; saw_headers = true; }, 0x00 => { const payload = bytes[at..end]; if (used + payload.len > answer.len) return error.TooLong; @memcpy(answer[used..][0..payload.len], payload); used += payload.len; }, // §7.2.8: anything else is stepped over. else => {}, } at = end; } if (!saw_headers) return error.NoHead; return answer[0..used]; } fn putVarint(w: *Io.Writer, value: u64) !void { var buf: [8]u8 = undefined; try w.writeAll(quic.varint.write(&buf, value)); } test "RFC 9114 5.2: a shutdown answers what is in flight and refuses what is not" { // §5.2: "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 the whole value of the frame: a client that is told // H3_REQUEST_REJECTED knows the request did not happen and may send it // somewhere else, where a connection that simply closed leaves it having // to guess -- and guessing wrong means either losing a request or making // it twice. const io = testing.io; const gpa = testing.allocator; var rng_impl = std.Random.DefaultPrng.init(0x0502); const rng = rng_impl.random(); const bind: net.IpAddress = try .parse("127.0.0.1", 0); var socket = try bind.bind(io, .{ .mode = .dgram }); defer socket.close(io); const address = socket.address; var listener: h3_io.Listener = undefined; try listener.init(io, gpa, &socket, .{ .context = null, .serveFn = echo, }, .{ .rng = rng, .reset_key = @splat(0x55), .token_key = @splat(0x66), .max_connections = 2, }); defer listener.deinit(); var group: Io.Group = .init; defer group.cancel(io); try group.concurrent(io, run, .{&listener}); defer listener.stop(); // One request answered, which is what proves the connection was working // before the shutdown rather than after it. var answer: [256]u8 = undefined; const got = try ask(io, gpa, address, rng, &answer); try testing.expectEqualStrings("GET /hello HTTP/3", got); // §5.2: and now the shutdown, which every live connection is told about. listener.shutdown(); // A connection that arrives after it is refused rather than served. What // is asserted is that it does not get an answer -- the code it is refused // with is the client's to read, and the hand-written client here does not // parse CONNECTION_CLOSE. var second: [256]u8 = undefined; try testing.expectError(error.NoAnswer, ask(io, gpa, address, rng, &second)); } /// What a tunnelling handler saw, so that the test can check it from outside. const Tunnel = struct { seen: [64]u8 = undefined, len: std.atomic.Value(usize) = .init(0), upgraded: std.atomic.Value(bool) = .init(false), }; /// A handler that takes the stream over, which is what a WebSocket's would do /// after the opening handshake. fn tunnelling(context: ?*anyopaque, req: *http.server.Request, res: *http.server.Response) anyerror!void { const t: *Tunnel = @ptrCast(@alignCast(context.?)); if (!req.offersUpgrade("echo")) { try res.send("no"); return; } const tunnel = try res.upgrade("echo"); t.upgraded.store(true, .release); // One `stream` call, not `readSliceShort`. The latter keeps asking until // the destination is full or the stream ends, which is right for a // message of known length and wrong for a tunnel -- the peer has not // ended its half and is not going to, so the second ask waits for ever. var into: Io.Writer = .fixed(&t.seen); const n = try tunnel.input.stream(&into, .limited(t.seen.len)); t.len.store(n, .release); // And back the other way, on the same stream, with both halves open. try tunnel.output.writeAll(t.seen[0..n]); try tunnel.output.flush(); } test "RFC 9220: an extended CONNECT hands the stream over" { // RFC 9220 is three pages, and most of them are about what it does not // change from RFC 8441: the same setting identifier, the same `:protocol` // in the request, the same `2xx` rather than a `101`. What differs is // what a tunnel is made of -- and it is simpler here than in either // version before it, because the request body and the tunnel are the same // QUIC stream. Over HTTP/1.1 an upgrade has to refuse when the request // body has not been read, since those octets sit in front of the new // protocol's first one; here there is nothing to be in front of anything. const io = testing.io; const gpa = testing.allocator; var rng_impl = std.Random.DefaultPrng.init(0x9220); const rng = rng_impl.random(); const bind: net.IpAddress = try .parse("127.0.0.1", 0); var socket = try bind.bind(io, .{ .mode = .dgram }); defer socket.close(io); const address = socket.address; var listener: h3_io.Listener = undefined; var tunnel: Tunnel = .{}; try listener.init(io, gpa, &socket, .{ .context = &tunnel, .serveFn = tunnelling, }, .{ .rng = rng, .reset_key = @splat(0x99), .token_key = @splat(0xaa), .max_connections = 2, }); defer listener.deinit(); var group: Io.Group = .init; defer group.cancel(io); try group.concurrent(io, run, .{&listener}); defer listener.stop(); var answer: [512]u8 = undefined; // What came back through the tunnel, which only arrives if the server's // half works while the client's is still open. const came_back = try connectAndSpeak(io, gpa, address, rng, &answer); try testing.expectEqualStrings("hello through the tunnel", came_back); // §5.1 of RFC 8441: the answer was a `2xx`, not a `101`. There is nothing // to switch -- the stream is the tunnel the moment the status goes out. try testing.expect(tunnel.upgraded.load(.acquire)); // And the octets the client sent after the request reached the handler // through the tunnel rather than being read as part of the request. // // Waited for rather than read straight away: the client returns when the // status arrives, and the handler is on a task of its own that has not // necessarily read its side yet. A tunnel is two independent directions, // which is the whole point of one, so a test of it has to be written that // way too. const n = tunnel.len.load(.acquire); try testing.expectEqualStrings("hello through the tunnel", tunnel.seen[0..n]); } test "a request is served with no socket, no handshake and no port" { // The whole reason `transport.Session` exists. Every other test in this // file binds a UDP port and completes a QUIC handshake to ask a question // about HTTP/3 framing, which means a failure in any of them is a failure // somewhere in QUIC, TLS, QPACK and HTTP/3 at once. This one hands the // driver a request as a slice, the way `tests/e2e.zig` has always been // able to for HTTP/1.1. const io = std.testing.io; const gpa = std.testing.allocator; // §7.2.1: a HEADERS frame carrying a QPACK field section, which is the // whole of a GET request. var section: [512]u8 = undefined; var sw: Io.Writer = .fixed(§ion); try h3.qpack.encode(&sw, default_fields); const fields = sw.buffered(); var request: [640]u8 = undefined; var rw: Io.Writer = .fixed(&request); try putVarint(&rw, 0x01); try putVarint(&rw, fields.len); try rw.writeAll(fields); // Stream 0: §2.1 of RFC 9000 makes the first client-initiated // bidirectional stream, which §4.1 of RFC 9114 makes a request. var scripted: http.transport.memory_session.Scripted = .{ .incoming = &.{.{ .id = .{ .value = 0 }, .data = rw.buffered() }}, }; defer scripted.deinit(gpa); var connection: h3.Connection = .init( io, gpa, scripted.session(gpa), .{ .context = null, .serveFn = echo }, .{}, ); connection.run(); // The answer is on the same stream, and it is this library's own bytes // read back by this library's own decoder -- which is exactly what the // socket-driven tests in this file check, at a fraction of the machinery. const answered = scripted.wrote(.{ .value = 0 }) orelse return error.NothingWritten; try std.testing.expect(answered.len > 0); var answer: [256]u8 = undefined; const body = try readResponse(answered, &answer); try std.testing.expectEqualStrings("GET /hello HTTP/3", body); // §6.2.1: the control stream is opened before anything is served, and it // is the first stream this endpoint opened. const control = scripted.local(0) orelse return error.NoControlStream; try std.testing.expect(control.written.items.len > 0); } fn runDialer(d: *h3_io.Dialer) void { d.run() catch {}; } test "this library's HTTP/3 client against this library's HTTP/3 server" { // The whole stack, both ends, over a real UDP socket: a QUIC handshake // with a certificate, §6.2's control streams in both directions, a QPACK // field section encoded by one end and decoded by the other, and a // response read back. Every other test in this file drives the server // with a hand-rolled client; this is the driver that ships. const io = testing.io; const gpa = testing.allocator; var rng_impl = std.Random.DefaultPrng.init(0x9115); const rng = rng_impl.random(); const bind: net.IpAddress = try .parse("127.0.0.1", 0); var socket = try bind.bind(io, .{ .mode = .dgram }); defer socket.close(io); const address = socket.address; var listener: h3_io.Listener = undefined; try listener.init(io, gpa, &socket, .{ .context = null, .serveFn = echo, }, .{ .rng = rng, .reset_key = @splat(0x35), .token_key = @splat(0x46), .max_connections = 2, }); defer listener.deinit(); var group: Io.Group = .init; defer group.cancel(io); try group.concurrent(io, run, .{&listener}); defer listener.stop(); const client_bind: net.IpAddress = try .parse("127.0.0.1", 0); var client_socket = try client_bind.bind(io, .{ .mode = .dgram }); defer client_socket.close(io); var dialer: h3_io.Dialer = undefined; try dialer.connect(io, gpa, &client_socket, address, .{ .host = "h3.example", .insecure_skip_verify = true, .rng = rng, }); defer dialer.deinit(); // Its own task: a stream read blocks until a datagram arrives, and this // is what makes one arrive. var client_tasks: Io.Group = .init; defer client_tasks.cancel(io); try client_tasks.concurrent(io, runDialer, .{&dialer}); defer dialer.stop(); var c: http.http3.client.Connection = .init(gpa, dialer.session(), .{}); try c.start(); var exchange = try c.send(.{ .host = "h3.example", .target = "/hello" }); defer exchange.deinit(gpa); try testing.expectEqual(@as(u16, 200), exchange.response.status); try testing.expectEqual(http.protocol.Version.http_3, exchange.response.version); try testing.expectEqualStrings("GET /hello HTTP/3", exchange.body()); try testing.expectEqualStrings("text/plain", exchange.response.headers.get("content-type").?); } /// A reader that makes its octets as they are asked for, so a streamed body /// has nothing behind it in memory. `tests/fetch.zig` has the same one, for /// the other two versions; test modules do not share code. const Pattern = struct { interface: Io.Reader, produced: u64 = 0, total: u64, fail_at: ?u64 = null, fn init(buffer: []u8, total: u64) Pattern { return .{ .interface = .{ .vtable = &.{ .stream = stream }, .buffer = buffer, .seek = 0, .end = 0 }, .total = total, }; } fn octetAt(i: u64) u8 { return @truncate((i *% 0x9E3779B97F4A7C15) >> 56); } fn stream(r: *Io.Reader, w: *Io.Writer, limit: Io.Limit) Io.Reader.StreamError!usize { _ = .{ w, limit }; const p: *Pattern = @fieldParentPtr("interface", r); if (p.fail_at) |at| if (p.produced >= at) return error.ReadFailed; if (p.produced == p.total) return error.EndOfStream; if (r.seek == r.end) { r.seek = 0; r.end = 0; } else if (r.end == r.buffer.len) { const kept = r.end - r.seek; std.mem.copyForwards(u8, r.buffer[0..kept], r.buffer[r.seek..r.end]); r.seek = 0; r.end = kept; } var stop = p.total; if (p.fail_at) |at| stop = @min(stop, at); const n: usize = @intCast(@min(r.buffer.len - r.end, stop - p.produced)); for (r.buffer[r.end..][0..n], 0..) |*octet, i| octet.* = octetAt(p.produced + i); p.produced += n; r.end += n; return 0; } }; /// Checks every octet of the body against `Pattern` as it arrives, holding /// none of it, and says how many there were -- or where the first wrong one /// was. fn verifies(_: ?*anyopaque, req: *http.server.Request, res: *http.server.Response) anyerror!void { const reader = req.body.reader; var chunk: [16384]u8 = undefined; var at: u64 = 0; while (true) { const n = try reader.readSliceShort(&chunk); for (chunk[0..n], 0..) |octet, i| { if (octet != Pattern.octetAt(at + i)) return res.sendPrint("wrong at {d}", .{at + i}); } at += n; if (n < chunk.len) break; } try res.sendPrint("{s} {d} octets", .{ req.method.name, at }); } test "a request body streamed from a reader over HTTP/3" { const io = testing.io; const gpa = testing.allocator; var rng_impl = std.Random.DefaultPrng.init(0x9117); const rng = rng_impl.random(); const bind: net.IpAddress = try .parse("127.0.0.1", 0); var socket = try bind.bind(io, .{ .mode = .dgram }); defer socket.close(io); const address = socket.address; var listener: h3_io.Listener = undefined; try listener.init(io, gpa, &socket, .{ .context = null, .serveFn = verifies }, .{ .rng = rng, .reset_key = @splat(0x39), .token_key = @splat(0x4a), .max_connections = 2, }); defer listener.deinit(); var group: Io.Group = .init; defer group.cancel(io); try group.concurrent(io, run, .{&listener}); defer listener.stop(); const client_bind: net.IpAddress = try .parse("127.0.0.1", 0); var client_socket = try client_bind.bind(io, .{ .mode = .dgram }); defer client_socket.close(io); var dialer: h3_io.Dialer = undefined; try dialer.connect(io, gpa, &client_socket, address, .{ .host = "h3.example", .insecure_skip_verify = true, .rng = rng, }); defer dialer.deinit(); var client_tasks: Io.Group = .init; defer client_tasks.cancel(io); try client_tasks.concurrent(io, runDialer, .{&dialer}); defer dialer.stop(); var c: http.http3.client.Connection = .init(gpa, dialer.session(), .{}); try c.start(); // Many times any stream window this session opens, so it can only have // arrived by being streamed through QUIC's flow control. const size: u64 = 4 << 20; { var source_buffer: [8192]u8 = undefined; var source: Pattern = .init(&source_buffer, size); var exchange = try c.send(.{ .host = "h3.example", .target = "/upload", .method = http.protocol.Method.put, .body = .{ .exact = size }, .source = &source.interface, }); defer exchange.deinit(gpa); try testing.expectEqualStrings("PUT 4194304 octets", exchange.body()); try testing.expectEqual(size, source.produced); } // A reader that ends early: the stream is reset rather than finished, so // the server is not handed a shorter body as though it were the whole. { var source_buffer: [8192]u8 = undefined; var source: Pattern = .init(&source_buffer, 100 << 10); try testing.expectError(error.RequestBodyShort, c.send(.{ .host = "h3.example", .target = "/upload", .method = http.protocol.Method.put, .body = .{ .exact = 1 << 20 }, .source = &source.interface, })); } // And one that fails, which is the reader's fault and not the session's. { var source_buffer: [8192]u8 = undefined; var source: Pattern = .init(&source_buffer, 1 << 20); source.fail_at = 50 << 10; try testing.expectError(error.RequestBodyReadFailed, c.send(.{ .host = "h3.example", .target = "/upload", .method = http.protocol.Method.put, .body = .{ .exact = 1 << 20 }, .source = &source.interface, })); } // A reset stream is that stream's end and no other's: the same session // carries the next request. { var source_buffer: [8192]u8 = undefined; var source: Pattern = .init(&source_buffer, 1000); var exchange = try c.send(.{ .host = "h3.example", .target = "/upload", .method = http.protocol.Method.post, .body = .{ .exact = 1000 }, .source = &source.interface, }); defer exchange.deinit(gpa); try testing.expectEqualStrings("POST 1000 octets", exchange.body()); } } /// Answers with what the request said its content length was, which is how a /// test asks whether a `Content-Length` crossed the wire. fn declares(_: ?*anyopaque, req: *http.server.Request, res: *http.server.Response) anyerror!void { const declared = req.body.length; const body = try req.body.readAlloc(std.testing.allocator, 1 << 20); defer std.testing.allocator.free(body); switch (declared) { .none => try res.send("none"), .exact => |n| try res.sendPrint("exact {d}", .{n}), .unknown => try res.send("unknown"), } } test "RFC 9110 8.6: an HTTP/3 request with a body declares how long it is" { // §4.1.2 of RFC 9114 makes the field optional -- the DATA frames and the // stream's end delimit the content -- and §8.6 of RFC 9110 asks for it // anyway when the length is known. A server may insist: Cloudflare's // DNS-over-HTTP/3 endpoint answers 400 to a POST without one, which is // what sent this driver looking. // // The server end is the proof. `req.body.length` is read out of the field // section and from nowhere else, so an answer of "exact 12" is the field // having been encoded, carried, and decoded. const io = testing.io; const gpa = testing.allocator; var rng_impl = std.Random.DefaultPrng.init(0x9116); const rng = rng_impl.random(); const bind: net.IpAddress = try .parse("127.0.0.1", 0); var socket = try bind.bind(io, .{ .mode = .dgram }); defer socket.close(io); const address = socket.address; var listener: h3_io.Listener = undefined; try listener.init(io, gpa, &socket, .{ .context = null, .serveFn = declares, }, .{ .rng = rng, .reset_key = @splat(0x37), .token_key = @splat(0x48), .max_connections = 2, }); defer listener.deinit(); var group: Io.Group = .init; defer group.cancel(io); try group.concurrent(io, run, .{&listener}); defer listener.stop(); const client_bind: net.IpAddress = try .parse("127.0.0.1", 0); var client_socket = try client_bind.bind(io, .{ .mode = .dgram }); defer client_socket.close(io); var dialer: h3_io.Dialer = undefined; try dialer.connect(io, gpa, &client_socket, address, .{ .host = "h3.example", .insecure_skip_verify = true, .rng = rng, }); defer dialer.deinit(); var client_tasks: Io.Group = .init; defer client_tasks.cancel(io); try client_tasks.concurrent(io, runDialer, .{&dialer}); defer dialer.stop(); var c: http.http3.client.Connection = .init(gpa, dialer.session(), .{}); try c.start(); { var exchange = try c.send(.{ .host = "h3.example", .target = "/submit", .method = .post, .body = .{ .exact = 12 }, .content = "hello, world", }); defer exchange.deinit(gpa); try testing.expectEqual(@as(u16, 200), exchange.response.status); try testing.expectEqualStrings("exact 12", exchange.body()); } { // And nothing where there is nothing to declare: a request with no // body is not a request with an empty one, so no `Content-Length: 0`. // // What the server makes of that is `unknown` rather than `none`, and // the difference between the versions is the point. HTTP/2 puts // END_STREAM on the HEADERS frame, so a server knows there is no // content as it reads the field section; over HTTP/3 the end of the // stream is a fact about the stream, which a driver that has only read // one frame cannot yet have. So an HTTP/3 recipient of a body with no // `Content-Length` knows the length only once it stops arriving -- // which is the whole reason §8.6 of RFC 9110 asks a sender that knows // it to say so, and the reason the first half of this test matters. var exchange = try c.send(.{ .host = "h3.example", .target = "/hello" }); defer exchange.deinit(gpa); try testing.expectEqual(@as(u16, 200), exchange.response.status); try testing.expectEqualStrings("unknown", exchange.body()); } } test "RFC 9112 2.2: the other two clients refuse a splitting target as well" { // The injection is HTTP/1.1's -- a CRLF ends a line there and nowhere // else -- so the temptation is to check it only in that driver. Two // reasons not to. §8.2.1 of RFC 9113 forbids CR, LF and NUL in a field // value, so a request carrying one is malformed on its own terms; and a // gateway converting it to HTTP/1.1 would do the splitting on our // behalf, one hop further along than anything here can see. // // The check lives in `client.Request.validate`, which all three drivers // call. This asserts that they do: a driver that quietly stopped calling // it would compile, pass every other test, and emit the message again. const gpa = testing.allocator; const io = testing.io; const splitting: http.client.Request = .{ .host = "example.com", .target = "/a\r\nX-Injected: yes", }; { // An empty SETTINGS, which is all the handshake needs. var memory = try http.transport.memory.Connection.init( gpa, &[_]u8{ 0, 0, 0, 0x04, 0, 0, 0, 0, 0 }, .{}, ); defer memory.deinit(); var c = try http.http2.client.Connection.init(io, gpa, memory.connection(), .{}); _ = c.releaseConnection(); defer c.deinit(); try c.handshake(); try testing.expectError(error.InvalidRequest, c.begin(splitting)); } { var scripted: http.transport.memory_session.Scripted = .{ .incoming = &.{}, // A HEADERS frame whose field section is an indexed `:status: 200`. .answer = &[_]u8{ 0x01, 0x03, 0x00, 0x00, 0xd9 }, }; defer scripted.deinit(gpa); var c: http.http3.client.Connection = .init(gpa, scripted.session(gpa), .{}); try c.start(); try testing.expectError(error.InvalidRequest, c.send(splitting)); // Nothing was opened for it, so nothing half-written is waiting on a // stream the caller cannot reach to reset. try testing.expect(scripted.find(.{ .value = 0 }) == null); } } test "RFC 9113 8.1: a stream that ends without a field section is not a response" { // "An HTTP message (request or response) consists of... a HEADERS frame // containing the header section." A stream ended by a DATA frame with no // field section before it carries no message, and a client that answered // with the zero its status was initialised to would be handing back a // response that never arrived. // // Found by fuzzing the HTTP/2 client against arbitrary server frames. const gpa = testing.allocator; const io = testing.io; // An empty SETTINGS, then a DATA frame on stream 1 with END_STREAM. const source = [_]u8{ 0, 0, 0, 0x04, 0, 0, 0, 0, 0, } ++ [_]u8{ 0, 0, 3, 0x00, 0x01, 0, 0, 0, 1, 'a', 'b', 'c', }; var memory = try http.transport.memory.Connection.init(gpa, &source, .{}); defer memory.deinit(); var c = try http.http2.client.Connection.init(io, gpa, memory.connection(), .{}); _ = c.releaseConnection(); defer c.deinit(); try c.handshake(); const handle = try c.begin(.{ .host = "example.com", .target = "/" }); try testing.expectError(error.MalformedResponse, c.await(handle)); }