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