// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! A `transport.Session` made of slices, for driving HTTP/3 without a socket. //! //! The counterpart to `transport.memory` and there for the same reason: the //! HTTP/1.1 driver can be handed a request as a string literal, and until //! there was a seam for multiplexed connections the HTTP/3 driver could not, //! so every one of its tests bound a UDP port and completed a QUIC handshake //! to ask a question about a frame. What that costs is not only speed. A //! failure there is a failure somewhere in QUIC, TLS, QPACK and HTTP/3 at //! once, and narrowing it down is a separate job from finding it. //! //! The streams the peer opens are written out in advance and the driver's //! answers are kept, so a test is a pair of byte slices and an assertion -- //! the shape `tests/e2e.zig` has always had for HTTP/1.1. const std = @import("std"); const Io = std.Io; const assert = std.debug.assert; const quic = @import("quic"); const session_mod = @import("session.zig"); const Session = session_mod.Session; const Stream = session_mod.Stream; /// How many streams one scripted session tracks, incoming and outgoing /// together. A fixed table, like everything else here. pub const max_streams = 32; /// One stream the peer opens, and what it sends on it. pub const Incoming = struct { id: quic.stream.Id, data: []const u8, /// What `Session.received` says of the stream: whether the peer has /// finished it. False is a peer still holding something back -- a client /// waiting for a `100 Continue`, say -- even though `data`, being all of /// what the script will ever deliver, still ends where it ends. received: bool = true, }; pub const Scripted = struct { /// What the peer opens, in the order it opens them. incoming: []const Incoming, /// What the peer sends on a bidirectional stream *this* end opens, which /// is where a client's response arrives. One canned answer rather than a /// list, because a scripted session is for asking one question at a time. answer: []const u8 = &.{}, /// Where the next `accept` will look. next: usize = 0, /// The next identifier `openUnidirectional` hands out. §2.1 of RFC 9000 /// numbers a server's unidirectional streams 3, 7, 11 and so on. next_local: u64 = 3, /// The next identifier `openBidirectional` hands out. next_bidi: u64 = 0, streams: [max_streams]State = @splat(.{}), len: usize = 0, /// What the driver said before giving up on the whole connection, if it /// did. closed: ?Closed = null, /// Held because the vtable has nowhere to put one and a written stream /// has to grow somewhere. gpa: std.mem.Allocator = undefined, pub const Closed = struct { code: u64, why: []const u8 }; pub const State = struct { id: quic.stream.Id = .{ .value = 0 }, /// What the peer sent and how much of it has been handed over. input: []const u8 = &.{}, read: usize = 0, /// What the driver has written, and whether it ended its half. written: std.ArrayList(u8) = .empty, /// How many writes reached this stream *before* its FIN, which is how a /// test asks whether the last octets travelled with the FIN or ahead of /// it. A write that came in through `finishWith` is not counted, /// because that is the one that did not go ahead. writes: usize = 0, /// How many octets travelled *with* the FIN, which is the question /// §19.8 of RFC 9000 leaves open and some servers answer strictly: a /// FIN is permitted in a STREAM frame carrying no data, and a peer is /// within its rights to expect the last octets on the frame that ends /// the stream. Zero here on a stream that sent a body means the FIN /// travelled alone. fin_carried: usize = 0, finished: bool = false, /// §4.1 of RFC 9114: the code the driver abandoned this stream with. reset: ?u64 = null, stopped: ?u64 = null, /// See `Incoming.received`. A stream this end opened has its whole /// answer scripted, so it is received. received: bool = true, in_use: bool = false, }; /// Frees what the driver wrote. `gpa` is the allocator given to /// `session`. pub fn deinit(s: *Scripted, gpa: std.mem.Allocator) void { for (&s.streams) |*state| state.written.deinit(gpa); } test deinit { const gpa = std.testing.allocator; var scripted: Scripted = .{ .incoming = &.{} }; const stream = try scripted.session(gpa).openUnidirectional(); var w = stream.writer(&.{}); try w.interface.writeAll("grown from gpa"); scripted.deinit(gpa); } /// The seam, for handing to a driver. `gpa` is what the streams' written /// octets are grown with, and is the one `deinit` is given back. pub fn session(s: *Scripted, gpa: std.mem.Allocator) Session { s.gpa = gpa; return .{ .context = s, .vtable = &vtable }; } test session { const gpa = std.testing.allocator; var scripted: Scripted = .{ .incoming = &.{ .{ .id = .{ .value = 0 }, .data = "GET" }, } }; defer scripted.deinit(gpa); const s = scripted.session(gpa); try std.testing.expect(s.waitEstablished()); const stream = s.accept().?; var buffer: [16]u8 = undefined; var r = stream.reader(&buffer); try std.testing.expectEqualStrings("GET", try r.interface.take(3)); } /// What the driver wrote on a stream, or null if the stream was never /// opened or accepted. pub fn wrote(s: *const Scripted, id: quic.stream.Id) ?[]const u8 { const state = s.find(id) orelse return null; return state.written.items; } test wrote { const gpa = std.testing.allocator; var scripted: Scripted = .{ .incoming = &.{} }; defer scripted.deinit(gpa); const stream = try scripted.session(gpa).openUnidirectional(); var w = stream.writer(&.{}); try w.interface.writeAll("\x00"); try std.testing.expectEqualStrings("\x00", scripted.wrote(stream.id).?); try std.testing.expect(scripted.wrote(.{ .value = 99 }) == null); } /// The `index`th stream with no scripted input, in the order the streams /// were opened -- which is to say the streams the driver opened for its /// own use. §6.2 of RFC 9114 has the control stream first. /// /// Told apart by having nothing to read, so a bidirectional stream opened /// while `answer` is non-empty is not counted, and an incoming one whose /// `data` is empty is. pub fn local(s: *const Scripted, index: usize) ?*const State { var seen: usize = 0; for (s.streams[0..s.len]) |*state| { if (!state.in_use or state.input.len != 0) continue; if (seen == index) return state; seen += 1; } return null; } test local { const gpa = std.testing.allocator; var scripted: Scripted = .{ .incoming = &.{ .{ .id = .{ .value = 0 }, .data = "a request" }, } }; defer scripted.deinit(gpa); const s = scripted.session(gpa); _ = s.accept().?; const control = try s.openUnidirectional(); const encoder = try s.openUnidirectional(); try std.testing.expectEqual(control.id.value, scripted.local(0).?.id.value); try std.testing.expectEqual(encoder.id.value, scripted.local(1).?.id.value); try std.testing.expect(scripted.local(2) == null); } /// One stream's state, for a test asking what the driver did to it, or /// null if the stream was never opened or accepted. pub fn find(s: *const Scripted, id: quic.stream.Id) ?*const State { for (s.streams[0..s.len]) |*state| { if (state.in_use and state.id.value == id.value) return state; } return null; } test find { const gpa = std.testing.allocator; var scripted: Scripted = .{ .incoming = &.{} }; defer scripted.deinit(gpa); const stream = try scripted.session(gpa).openBidirectional(); var w = stream.writer(&.{}); try w.interface.writeAll("ab"); try w.finish(); const state = scripted.find(stream.id).?; try std.testing.expect(state.finished); // An unbuffered writer sent its octets ahead of the FIN. try std.testing.expectEqual(@as(usize, 1), state.writes); try std.testing.expectEqual(@as(usize, 0), state.fin_carried); } fn findMut(s: *Scripted, id: quic.stream.Id) ?*State { for (s.streams[0..s.len]) |*state| { if (state.in_use and state.id.value == id.value) return state; } return null; } fn open(s: *Scripted, id: quic.stream.Id, input: []const u8) ?*State { if (s.findMut(id)) |existing| return existing; if (s.len == s.streams.len) return null; const state = &s.streams[s.len]; s.len += 1; state.* = .{ .id = id, .input = input, .in_use = true }; return state; } }; fn cast(context: ?*anyopaque) *Scripted { return @ptrCast(@alignCast(context.?)); } const vtable: Session.VTable = .{ .waitEstablished = waitEstablished, .accept = accept, .openUnidirectional = openUnidirectional, .openBidirectional = openBidirectional, .streamIn = streamIn, .writeOut = writeOut, .finish = finish, .finishWith = finishWith, .received = received, .resetStream = resetStream, .stopSending = stopSending, .close = close, }; /// Nothing to wait for: a scripted session is established from the start, /// which is the one thing a test never wants to spend a round trip on. fn waitEstablished(context: ?*anyopaque) bool { _ = context; return true; } fn accept(context: ?*anyopaque) ?quic.stream.Id { const s = cast(context); if (s.next == s.incoming.len) return null; const entry = s.incoming[s.next]; s.next += 1; const state = s.open(entry.id, entry.data) orelse return null; state.received = entry.received; return entry.id; } fn openUnidirectional(context: ?*anyopaque) Session.OpenError!quic.stream.Id { const s = cast(context); const id: quic.stream.Id = .{ .value = s.next_local }; s.next_local += 4; _ = s.open(id, &.{}) orelse return error.StreamUnavailable; return id; } fn openBidirectional(context: ?*anyopaque) Session.OpenError!quic.stream.Id { const s = cast(context); // §2.1 of RFC 9000 numbers a client's bidirectional streams 0, 4, 8 and // so on, which is the series `next_local` is not using. const id: quic.stream.Id = .{ .value = s.next_bidi }; s.next_bidi += 4; _ = s.open(id, s.answer) orelse return error.StreamUnavailable; return id; } fn streamIn( context: ?*anyopaque, id: quic.stream.Id, w: *Io.Writer, limit: Io.Limit, ) Io.Reader.StreamError!usize { const s = cast(context); const state = s.findMut(id) orelse return error.EndOfStream; const left = state.input[state.read..]; // Everything the peer will ever send is already here, so the end of the // slice is the end of the stream rather than a pause in it. That is the // one way a scripted session is not a network: it never blocks. if (left.len == 0) return error.EndOfStream; const take = @min(left.len, limit.toInt() orelse left.len); const n = w.write(left[0..take]) catch return error.WriteFailed; state.read += n; return n; } fn writeOut(context: ?*anyopaque, id: quic.stream.Id, bytes: []const u8) Io.Writer.Error!void { const s = cast(context); const state = s.findMut(id) orelse return error.WriteFailed; state.written.appendSlice(s.gpa, bytes) catch return error.WriteFailed; state.writes += 1; } fn finish(context: ?*anyopaque, id: quic.stream.Id) Io.Writer.Error!void { const s = cast(context); const state = s.findMut(id) orelse return error.WriteFailed; state.finished = true; } /// The same in one call, so that a scripted session drives the path a real one /// takes rather than the fallback beside it. /// /// The octets are appended here rather than through `writeOut`, which leaves /// `State.writes` counting only what was sent ahead of the FIN -- the thing a /// test wants to know. fn finishWith(context: ?*anyopaque, id: quic.stream.Id, bytes: []const u8) Io.Writer.Error!void { const s = cast(context); const state = s.findMut(id) orelse return error.WriteFailed; state.written.appendSlice(s.gpa, bytes) catch return error.WriteFailed; state.fin_carried = bytes.len; state.finished = true; } fn received(context: ?*anyopaque, id: quic.stream.Id) bool { const state = cast(context).findMut(id) orelse return true; return state.received; } fn resetStream(context: ?*anyopaque, id: quic.stream.Id, code: u64) void { if (cast(context).findMut(id)) |state| state.reset = code; } fn stopSending(context: ?*anyopaque, id: quic.stream.Id, code: u64) void { if (cast(context).findMut(id)) |state| state.stopped = code; } fn close(context: ?*anyopaque, code: u64, why: []const u8) void { cast(context).closed = .{ .code = code, .why = why }; }