Something went wrong. Try again.
An HTTP library for Zig 0.17, server and client, HTTP/1.0 through HTTP/3, with the protocol in a module that owns no socket.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// 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 };}