// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! A client's half of an HTTP/2 conversation, written out by hand. //! //! This file deliberately imports nothing from `http`. Every request in the //! suite is framed and compressed by code that shares nothing with the code //! under test, so a mistake the server and the library's own encoder agreed //! about — the kind a round trip through one implementation cannot see — //! shows up here as a disagreement. //! //! Which is why the HPACK written here is the dumbest representation RFC 7541 //! has: a literal with a new name, never indexed, never Huffman-coded. It is //! fifteen lines, it needs no table, and it is checkable against §6.2.2 by //! reading it. The server's *own* dynamic table still moves underneath it — //! nothing here inserts, but the decoder under test must keep in step all the //! same — and that is the point. const std = @import("std"); const Allocator = std.mem.Allocator; /// RFC 9113 §3.4. pub const preface = "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"; pub const Field = struct { name: []const u8, value: []const u8, }; /// The frame types of §6, as plain numbers because a test sometimes wants to /// send one that is not in the enumeration at all. pub const Type = struct { pub const data: u8 = 0x0; pub const headers: u8 = 0x1; pub const priority: u8 = 0x2; pub const rst_stream: u8 = 0x3; pub const settings: u8 = 0x4; pub const push_promise: u8 = 0x5; pub const ping: u8 = 0x6; pub const goaway: u8 = 0x7; pub const window_update: u8 = 0x8; pub const continuation: u8 = 0x9; }; pub const Flags = struct { pub const end_stream: u8 = 0x1; /// The same bit as `end_stream`, on the frames where it means this. pub const ack: u8 = 0x1; pub const end_headers: u8 = 0x4; pub const padded: u8 = 0x8; pub const priority: u8 = 0x20; }; /// The settings identifiers of §6.5.2. pub const Setting = struct { pub const header_table_size: u16 = 0x1; pub const enable_push: u16 = 0x2; pub const max_concurrent_streams: u16 = 0x3; pub const initial_window_size: u16 = 0x4; pub const max_frame_size: u16 = 0x5; pub const max_header_list_size: u16 = 0x6; }; pub const ErrorCode = struct { pub const no_error: u32 = 0x0; pub const protocol_error: u32 = 0x1; pub const internal_error: u32 = 0x2; pub const flow_control_error: u32 = 0x3; pub const settings_timeout: u32 = 0x4; pub const stream_closed: u32 = 0x5; pub const frame_size_error: u32 = 0x6; pub const refused_stream: u32 = 0x7; pub const cancel: u32 = 0x8; pub const compression_error: u32 = 0x9; pub const connect_error: u32 = 0xa; pub const enhance_your_calm: u32 = 0xb; pub const inadequate_security: u32 = 0xc; pub const http_1_1_required: u32 = 0xd; }; /// Accumulates the octets a client would send. pub const Builder = struct { gpa: Allocator, bytes: std.ArrayList(u8) = .empty, pub fn init(gpa: Allocator) Builder { return .{ .gpa = gpa }; } pub fn deinit(b: *Builder) void { b.bytes.deinit(b.gpa); b.* = undefined; } pub fn written(b: *const Builder) []const u8 { return b.bytes.items; } /// The preface and the SETTINGS frame that must follow it, which is how /// every conversation starts. pub fn begin(b: *Builder) !void { try b.bytes.appendSlice(b.gpa, preface); try b.settings(&.{}); } /// One frame, with no check on any of it: the way to send something the /// server must refuse. pub fn raw(b: *Builder, kind: u8, flags: u8, stream_id: u32, payload: []const u8) !void { var head: [9]u8 = undefined; head[0] = @intCast((payload.len >> 16) & 0xff); head[1] = @intCast((payload.len >> 8) & 0xff); head[2] = @intCast(payload.len & 0xff); head[3] = kind; head[4] = flags; std.mem.writeInt(u32, head[5..9], stream_id, .big); try b.bytes.appendSlice(b.gpa, &head); try b.bytes.appendSlice(b.gpa, payload); } pub fn settings(b: *Builder, pairs: []const [2]u32) !void { var payload: std.ArrayList(u8) = .empty; defer payload.deinit(b.gpa); for (pairs) |pair| { var entry: [6]u8 = undefined; std.mem.writeInt(u16, entry[0..2], @intCast(pair[0]), .big); std.mem.writeInt(u32, entry[2..6], pair[1], .big); try payload.appendSlice(b.gpa, &entry); } try b.raw(Type.settings, 0, 0, payload.items); } pub fn settingsAck(b: *Builder) !void { try b.raw(Type.settings, Flags.ack, 0, ""); } /// A request, in one HEADERS frame. pub fn headers(b: *Builder, stream_id: u32, flags: u8, fields: []const Field) !void { const encoded = try encode(b.gpa, fields); defer b.gpa.free(encoded); try b.raw(Type.headers, flags | Flags.end_headers, stream_id, encoded); } /// A request whose field block is already encoded, for the tests that /// split one across CONTINUATION frames or corrupt it on purpose. pub fn headersRaw(b: *Builder, stream_id: u32, flags: u8, block: []const u8) !void { try b.raw(Type.headers, flags, stream_id, block); } pub fn continuation(b: *Builder, stream_id: u32, flags: u8, block: []const u8) !void { try b.raw(Type.continuation, flags, stream_id, block); } pub fn data(b: *Builder, stream_id: u32, flags: u8, payload: []const u8) !void { try b.raw(Type.data, flags, stream_id, payload); } pub fn rstStream(b: *Builder, stream_id: u32, code: u32) !void { var payload: [4]u8 = undefined; std.mem.writeInt(u32, &payload, code, .big); try b.raw(Type.rst_stream, 0, stream_id, &payload); } pub fn windowUpdate(b: *Builder, stream_id: u32, increment: u32) !void { var payload: [4]u8 = undefined; std.mem.writeInt(u32, &payload, increment, .big); try b.raw(Type.window_update, 0, stream_id, &payload); } pub fn ping(b: *Builder, flags: u8, payload: *const [8]u8) !void { try b.raw(Type.ping, flags, 0, payload); } pub fn goaway(b: *Builder, last_stream_id: u32, code: u32, debug: []const u8) !void { var payload: std.ArrayList(u8) = .empty; defer payload.deinit(b.gpa); var head: [8]u8 = undefined; std.mem.writeInt(u32, head[0..4], last_stream_id, .big); std.mem.writeInt(u32, head[4..8], code, .big); try payload.appendSlice(b.gpa, &head); try payload.appendSlice(b.gpa, debug); try b.raw(Type.goaway, 0, 0, payload.items); } pub fn priority(b: *Builder, stream_id: u32, depends_on: u32, weight: u8) !void { var payload: [5]u8 = undefined; std.mem.writeInt(u32, payload[0..4], depends_on, .big); payload[4] = weight; try b.raw(Type.priority, 0, stream_id, &payload); } }; /// The request fields of an ordinary `GET`, which most tests want and none /// want to retype. pub fn get(path: []const u8) [4]Field { return .{ .{ .name = ":method", .value = "GET" }, .{ .name = ":scheme", .value = "http" }, .{ .name = ":authority", .value = "a.example" }, .{ .name = ":path", .value = path }, }; } pub fn post(path: []const u8) [4]Field { return .{ .{ .name = ":method", .value = "POST" }, .{ .name = ":scheme", .value = "http" }, .{ .name = ":authority", .value = "a.example" }, .{ .name = ":path", .value = path }, }; } /// A field block: every field as RFC 7541 §6.2.2's literal without indexing, /// with a new name and no Huffman coding. /// /// `0000` then a four-bit zero index says "the name is a literal too", and /// each string is a seven-bit prefixed length with the Huffman bit clear. /// Nothing here touches a table, which is what makes it safe to write by /// hand: an encoder that indexes has to model the decoder's table exactly, /// and one that does not has no state to get wrong. pub fn encode(gpa: Allocator, fields: []const Field) ![]u8 { var out: std.ArrayList(u8) = .empty; errdefer out.deinit(gpa); for (fields) |field| { try out.append(gpa, 0x00); try writeString(gpa, &out, field.name); try writeString(gpa, &out, field.value); } return out.toOwnedSlice(gpa); } fn writeString(gpa: Allocator, out: *std.ArrayList(u8), s: []const u8) !void { try writeInt(gpa, out, 7, s.len); try out.appendSlice(gpa, s); } /// RFC 7541 §5.1's prefixed integer. The high bit of the first octet is left /// clear, which for a string length means "not Huffman-coded". fn writeInt(gpa: Allocator, out: *std.ArrayList(u8), prefix_bits: u4, value: usize) !void { const max = (@as(usize, 1) << prefix_bits) - 1; if (value < max) { try out.append(gpa, @intCast(value)); return; } try out.append(gpa, @intCast(max)); var rest = value - max; while (rest >= 128) { try out.append(gpa, @intCast((rest & 0x7f) | 0x80)); rest >>= 7; } try out.append(gpa, @intCast(rest)); } const testing = std.testing; test "the prefixed integer is the one in RFC 7541 Appendix C.1" { const gpa = testing.allocator; var out: std.ArrayList(u8) = .empty; defer out.deinit(gpa); // C.1.1: 10 in a five-bit prefix is one octet. try writeInt(gpa, &out, 5, 10); try testing.expectEqualSlices(u8, &.{0x0a}, out.items); // C.1.2: 1337 in a five-bit prefix is three. out.clearRetainingCapacity(); try writeInt(gpa, &out, 5, 1337); try testing.expectEqualSlices(u8, &.{ 0x1f, 0x9a, 0x0a }, out.items); // C.1.3: 42 with an eight-bit prefix is one. out.clearRetainingCapacity(); try writeInt(gpa, &out, 8, 42); try testing.expectEqualSlices(u8, &.{0x2a}, out.items); } test "a field block is a literal with a new name" { const gpa = testing.allocator; const block = try encode(gpa, &.{.{ .name = "a", .value = "bc" }}); defer gpa.free(block); try testing.expectEqualSlices(u8, &.{ 0x00, 0x01, 'a', 0x02, 'b', 'c' }, block); }