From d76e1208daf58539203e04842ecd868cdca59072 Mon Sep 17 00:00:00 2001 From: "Jeffrey C. Ollie" Date: Wed, 16 Sep 2026 11:10:59 -0500 Subject: [PATCH] HPACK: Huffman code, primitives, and the two tables --- build.zig | 26 +- src/http2.zig | 32 ++ src/http2/hpack.zig | 320 ++++++++++++++++++ src/http2/hpack/huffman.zig | 627 ++++++++++++++++++++++++++++++++++++ src/http2/hpack/table.zig | 377 ++++++++++++++++++++++ src/root.zig | 1 + 6 files changed, 1380 insertions(+), 3 deletions(-) create mode 100644 src/http2.zig create mode 100644 src/http2/hpack.zig create mode 100644 src/http2/hpack/huffman.zig create mode 100644 src/http2/hpack/table.zig diff --git a/build.zig b/build.zig index 8766641..0b7c626 100644 --- a/build.zig +++ b/build.zig @@ -38,11 +38,25 @@ pub fn build(b: *std.Build) void { const run_step = b.step("run", "Run the demonstration server"); run_step.dependOn(&run_cmd.step); + // Narrows every test executable below to the tests whose name contains + // this. `-Dfuzz-filter` is separate and narrows the fuzz module only, + // because the fuzzer takes one test at a time and naming a target is what + // you want when a finding is being chased. + const test_filter = b.option( + []const u8, + "test-filter", + "Run only the tests whose name contains this", + ); + const filters: []const []const u8 = if (test_filter) |f| &.{f} else &.{}; + // A test executable covers one module, so each needs its own. Missing one // out would not fail: its tests would simply never run. const test_step = b.step("test", "Run tests"); for ([_]*std.Build.Module{ mod, exe.root_module }) |m| { - test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = m })).step); + test_step.dependOn(&b.addRunArtifact(b.addTest(.{ + .root_module = m, + .filters = filters, + })).step); } const e2e_mod = b.createModule(.{ @@ -51,7 +65,10 @@ pub fn build(b: *std.Build) void { .optimize = optimize, .imports = &.{.{ .name = "http", .module = mod }}, }); - test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = e2e_mod })).step); + test_step.dependOn(&b.addRunArtifact(b.addTest(.{ + .root_module = e2e_mod, + .filters = filters, + })).step); const tcp_mod = b.createModule(.{ .root_source_file = b.path("tests/tcp.zig"), @@ -59,7 +76,10 @@ pub fn build(b: *std.Build) void { .optimize = optimize, .imports = &.{.{ .name = "http", .module = mod }}, }); - test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = tcp_mod })).step); + test_step.dependOn(&b.addRunArtifact(b.addTest(.{ + .root_module = tcp_mod, + .filters = filters, + })).step); // The fuzz targets: what the head parser, the path resolver, the date // parser and the driver as a whole must do with input nobody wrote. They diff --git a/src/http2.zig b/src/http2.zig new file mode 100644 index 0000000..de23c60 --- /dev/null +++ b/src/http2.zig @@ -0,0 +1,32 @@ +// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie +// SPDX-License-Identifier: MIT + +//! HTTP/2 on the wire: RFC 9113, and the header compression it carries its +//! field sections in, RFC 7541. +//! +//! The sibling of `http1`, behind the same two seams: `server.Server` picks +//! it for a connection, and it fills in a `Request` and drives a `Response`. +//! Nothing in `protocol`, `transport` or `server` is particular to either +//! version, which is what lets one handler serve both. + +const std = @import("std"); + +pub const hpack = @import("http2/hpack.zig"); + +/// RFC 9113 §3.4. A client using prior knowledge sends this before anything +/// else, and a TLS client that negotiated `h2` sends it too. +/// +/// It is shaped like an HTTP/1.1 request on purpose, so that a server which +/// does not speak HTTP/2 refuses it as a request rather than being confused +/// by it: the method is `PRI`, the target is `*`, and the version is +/// `HTTP/2.0`, which an HTTP/1.1 parser rejects with `505`. +pub const preface = "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"; + +/// The shortest prefix of `preface` that no HTTP/1.x request line can begin +/// with, which is what `server.Server` looks at to tell the two apart without +/// waiting for octets a small request would never send. +pub const preface_prefix = preface[0..4]; + +test { + std.testing.refAllDecls(@This()); +} diff --git a/src/http2/hpack.zig b/src/http2/hpack.zig new file mode 100644 index 0000000..6c8f75d --- /dev/null +++ b/src/http2/hpack.zig @@ -0,0 +1,320 @@ +// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie +// SPDX-License-Identifier: MIT + +//! HPACK: the header compression HTTP/2 carries its field sections in, RFC +//! 7541. +//! +//! Two primitives underneath everything else — an integer encoding that can +//! spill across as many octets as it likes, and a string literal that may or +//! may not be Huffman-coded — and then five representations built out of +//! them. This file holds the primitives; `hpack/Decoder.zig` and +//! `hpack/Encoder.zig` hold the representations, and `hpack/table.zig` holds +//! the two tables they index into. +//! +//! ## Where a decoded string lives +//! +//! Every name and value the decoder produces is copied into an allocator the +//! caller passes for the field section — in this server, the arena belonging +//! to the stream the section arrived on. The only exception is a static-table +//! hit, whose strings are `.rodata` and outlive everything. +//! +//! That is the load-bearing decision in this whole module, and it is worth +//! the paragraphs because the cheaper-looking alternatives are all wrong: +//! +//! * **Not the decoder's own buffer.** HPACK state is per *connection*; a +//! decoded field section belongs to one *stream* and must stay valid until +//! that stream's handler returns. HTTP/2 is multiplexed, so the decoder +//! will be decoding another stream's section while the first handler is +//! still reading its headers. Anything owned by the decoder is the wrong +//! lifetime by construction rather than by accident. +//! * **Not the dynamic table**, even though it outlives the section. It is a +//! ring that evicts, and it can evict *during the very section that +//! references it*: a literal with incremental indexing anywhere in a +//! section can push out an entry that an indexed field earlier in the same +//! section pointed at. Handing out slices into it is a use-after-free that +//! a fuzzer finds and a table of worked examples does not. +//! * **Not the field section either.** A section arrives split across a +//! HEADERS frame and any number of CONTINUATION frames, so the driver +//! reassembles it into a buffer it owns and reuses. Borrowing would make +//! the rule "valid until the next field section on this connection", which +//! is not a rule a handler can be expected to keep. +//! +//! So the contract, which the fuzz target states as a property: **no slice +//! the decoder returns points into the field section it was given, or into +//! the dynamic table.** One `memcpy` of a few hundred octets per request, +//! next to a syscall. + +const std = @import("std"); + +pub const huffman = @import("hpack/huffman.zig"); +pub const table = @import("hpack/table.zig"); + +const Writer = std.Io.Writer; + +pub const IntError = error{ + /// The integer ran off the end of the field section. + Truncated, + /// More continuation octets than the result can hold. + /// + /// RFC 7541 §5.1 leaves the bound to the implementation and warns about + /// exactly this: the encoding is not required to be minimal, so + /// `1f 80 80 80 80 80 80 ...` is a syntactically fine way to write a + /// small number using as many octets as the sender likes, and a decoder + /// without a cap loops until the section runs out. + /// + /// The cap is on the shift rather than on a count of octets, so what is + /// refused is the value that would not have fit rather than the one that + /// was merely written oddly. + IntegerOverflow, +}; + +pub const StringError = IntError || huffman.DecodeError; + +/// A position in a field section. +/// +/// Everything the decoder reads goes through one, which is what keeps the +/// bounds checks in a single place rather than one per representation — and a +/// field section is the input a server is most often handed by somebody who +/// means it harm. +pub const Cursor = struct { + bytes: []const u8, + pos: usize = 0, + + pub fn atEnd(c: Cursor) bool { + return c.pos >= c.bytes.len; + } + + pub fn byte(c: *Cursor) error{Truncated}!u8 { + if (c.pos >= c.bytes.len) return error.Truncated; + defer c.pos += 1; + return c.bytes[c.pos]; + } + + pub fn peekByte(c: Cursor) error{Truncated}!u8 { + if (c.pos >= c.bytes.len) return error.Truncated; + return c.bytes[c.pos]; + } + + pub fn slice(c: *Cursor, n: usize) error{Truncated}![]const u8 { + if (n > c.bytes.len - c.pos) return error.Truncated; + defer c.pos += n; + return c.bytes[c.pos..][0..n]; + } + + /// The prefixed integer of RFC 7541 §5.1, `prefix_bits` wide. + /// + /// The octet carrying the prefix is consumed here; the flag bits above + /// the prefix are the caller's to have peeked at already. + pub fn int(c: *Cursor, prefix_bits: u4) IntError!u32 { + std.debug.assert(prefix_bits >= 1 and prefix_bits <= 8); + const max: u32 = (@as(u32, 1) << prefix_bits) - 1; + const first = try c.byte(); + const prefix: u32 = first & @as(u8, @intCast(max)); + // A prefix below its maximum is the whole value, and there are no + // continuation octets to read. + if (prefix < max) return prefix; + + var value: u32 = max; + var shift: u5 = 0; + while (true) { + const b = try c.byte(); + const payload: u32 = b & 0x7f; + // Seven bits at a time. `shlExact` is the whole overflow check: + // it refuses a shift that would push a meaningful bit off the top + // of a `u32`, which is exactly the value that cannot fit however + // few octets it was written in. + const addend = std.math.shlExact(u32, payload, shift) catch + return error.IntegerOverflow; + value = std.math.add(u32, value, addend) catch return error.IntegerOverflow; + if (b & 0x80 == 0) return value; + // Running out of shift *is* the cap on the octet count: after the + // fifth continuation octet there is nowhere left to put anything. + shift = std.math.add(u5, shift, 7) catch return error.IntegerOverflow; + } + } + + /// The string literal of RFC 7541 §5.2. + /// + /// The result is either a sub-slice of `bytes` — when the literal was not + /// Huffman-coded, in which case nothing is copied — or a prefix of + /// `scratch`. Neither is somewhere it may be kept; see the note at the + /// top of this file. + pub fn string(c: *Cursor, scratch: []u8) StringError![]const u8 { + const first = try c.peekByte(); + const coded = first & 0x80 != 0; + const len = try c.int(7); + const raw = try c.slice(len); + if (!coded) return raw; + return huffman.decode(raw, scratch); + } + + /// Steps over a string literal without decoding it, which is what a + /// decoder does for a field it has already decided is over budget and + /// which is not going into the dynamic table. + pub fn skipString(c: *Cursor) IntError!void { + _ = try c.peekByte(); + const len = try c.int(7); + _ = try c.slice(len); + } +}; + +/// Writes a prefixed integer. `high_bits` is the pattern above the prefix — +/// `0x80` for an indexed field, `0x40` for a literal with incremental +/// indexing, and so on. +pub fn writeInt(out: *Writer, prefix_bits: u4, high_bits: u8, value: u32) Writer.Error!void { + std.debug.assert(prefix_bits >= 1 and prefix_bits <= 8); + const max: u32 = (@as(u32, 1) << prefix_bits) - 1; + if (value < max) return out.writeByte(high_bits | @as(u8, @intCast(value))); + + try out.writeByte(high_bits | @as(u8, @intCast(max))); + var rest = value - max; + while (rest >= 128) { + try out.writeByte(@as(u8, @truncate(rest & 0x7f)) | 0x80); + rest >>= 7; + } + try out.writeByte(@intCast(rest)); +} + +/// Writes a string literal, Huffman-coded when that is shorter — which is +/// what §5.2 leaves to the encoder, and what every implementation does, +/// because a coded string longer than its input is one the decoder has to do +/// more work to get back. +/// +/// `lowercase` is not an optimisation. RFC 9113 §8.2.1 requires field names +/// to be lower case on the wire and `protocol.Headers` deliberately stores +/// them as the handler wrote them, so somewhere has to fold them. This is the +/// right somewhere: the last thing that touches the octets, and the only one +/// that can do it without a buffer. +pub fn writeString(out: *Writer, s: []const u8, lowercase: bool) Writer.Error!void { + if (huffman.worthwhile(s, lowercase)) { + try writeInt(out, 7, 0x80, @intCast(huffman.encodedLen(s, lowercase))); + return huffman.encode(out, s, lowercase); + } + try writeInt(out, 7, 0x00, @intCast(s.len)); + if (!lowercase) return out.writeAll(s); + for (s) |c| try out.writeByte(if (c >= 'A' and c <= 'Z') c + 32 else c); +} + +test { + std.testing.refAllDecls(@This()); +} + +const testing = std.testing; + +test "RFC 7541 C.1, the three integer examples" { + // C.1.1: 10 with a five-bit prefix fits in the prefix. + var c: Cursor = .{ .bytes = &.{0x0a} }; + try testing.expectEqual(@as(u32, 10), try c.int(5)); + + // C.1.2: 1337 with a five-bit prefix spills into two continuation octets. + c = .{ .bytes = &.{ 0x1f, 0x9a, 0x0a } }; + try testing.expectEqual(@as(u32, 1337), try c.int(5)); + try testing.expect(c.atEnd()); + + // C.1.3: 42 starting at an octet boundary, which is a prefix of eight. + c = .{ .bytes = &.{0x2a} }; + try testing.expectEqual(@as(u32, 42), try c.int(8)); +} + +test "integers round trip at every prefix width" { + const values = [_]u32{ + 0, 1, 2, 126, 127, + 128, 255, 256, 1337, 16383, + 16384, 65535, 65536, 1 << 20, (1 << 31) - 1, + 1 << 31, std.math.maxInt(u32) - 1, std.math.maxInt(u32), + }; + var buffer: [16]u8 = undefined; + for (1..9) |prefix| { + for (values) |value| { + var w: Writer = .fixed(&buffer); + try writeInt(&w, @intCast(prefix), 0, value); + var c: Cursor = .{ .bytes = buffer[0..w.end] }; + try testing.expectEqual(value, try c.int(@intCast(prefix))); + try testing.expect(c.atEnd()); + } + } +} + +test "the high bits above a prefix survive" { + var buffer: [16]u8 = undefined; + var w: Writer = .fixed(&buffer); + try writeInt(&w, 7, 0x80, 10); + try testing.expectEqual(@as(u8, 0x8a), buffer[0]); + + // And are not mistaken for part of the value on the way back. + var c: Cursor = .{ .bytes = buffer[0..w.end] }; + try testing.expectEqual(@as(u32, 10), try c.int(7)); +} + +test "integers that will not fit are refused rather than wrapped" { + // A continuation chain that never terminates. + var c: Cursor = .{ .bytes = &.{ 0x1f, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80 } }; + try testing.expectError(error.IntegerOverflow, c.int(5)); + + // The non-minimal encoding RFC 7541 §5.1 warns about: a small value + // written in as many octets as the sender liked. + c = .{ .bytes = &.{ 0x1f, 0x80, 0x80, 0x80, 0x80, 0x80, 0x00 } }; + try testing.expectError(error.IntegerOverflow, c.int(5)); + + // A value one past what a u32 holds. + c = .{ .bytes = &.{ 0x1f, 0xe1, 0xff, 0xff, 0xff, 0x0f } }; + try testing.expectError(error.IntegerOverflow, c.int(5)); + + // And one that simply ends. + c = .{ .bytes = &.{ 0x1f, 0x80 } }; + try testing.expectError(error.Truncated, c.int(5)); +} + +test "string literals, coded and not" { + var scratch: [64]u8 = undefined; + var buffer: [64]u8 = undefined; + + // A string Huffman coding would not shrink is written as it is. + var w: Writer = .fixed(&buffer); + try writeString(&w, "\x00\x01\x02", false); + try testing.expectEqual(@as(u8, 0x03), buffer[0]); // no Huffman bit + var c: Cursor = .{ .bytes = buffer[0..w.end] }; + try testing.expectEqualStrings("\x00\x01\x02", try c.string(&scratch)); + + // One it would is, and the length prefix carries the Huffman bit. + w = .fixed(&buffer); + try writeString(&w, "www.example.com", false); + try testing.expect(buffer[0] & 0x80 != 0); + try testing.expectEqual(@as(u8, 0x8c), buffer[0]); // twelve octets + c = .{ .bytes = buffer[0..w.end] }; + try testing.expectEqualStrings("www.example.com", try c.string(&scratch)); + + // A name is folded on the way out and comes back folded. + w = .fixed(&buffer); + try writeString(&w, "Content-Type", true); + c = .{ .bytes = buffer[0..w.end] }; + try testing.expectEqualStrings("content-type", try c.string(&scratch)); +} + +test "an uncoded literal is not copied" { + var scratch: [64]u8 = undefined; + const section = [_]u8{ 0x05, 'h', 'e', 'l', 'l', 'o' }; + var c: Cursor = .{ .bytes = §ion }; + const s = try c.string(&scratch); + try testing.expectEqualStrings("hello", s); + // It points into the section, which is exactly why the decoder above this + // has to copy before handing it to a handler. + try testing.expectEqual(@intFromPtr(§ion[1]), @intFromPtr(s.ptr)); +} + +test "strings that run off the end" { + var scratch: [64]u8 = undefined; + var c: Cursor = .{ .bytes = &.{ 0x05, 'h', 'i' } }; + try testing.expectError(error.Truncated, c.string(&scratch)); + + // A Huffman string that needs more room than the scratch buffer. + var tiny: [2]u8 = undefined; + c = .{ .bytes = &.{ 0x8c, 0xf1, 0xe3, 0xc2, 0xe5, 0xf2, 0x3a, 0x6b, 0xa0, 0xab, 0x90, 0xf4, 0xff } }; + try testing.expectError(error.StringTooLong, c.string(&tiny)); +} + +test "skipString steps over a literal without decoding it" { + var c: Cursor = .{ .bytes = &.{ 0x05, 'h', 'e', 'l', 'l', 'o', 0x99 } }; + try c.skipString(); + try testing.expectEqual(@as(u8, 0x99), try c.byte()); +} diff --git a/src/http2/hpack/huffman.zig b/src/http2/hpack/huffman.zig new file mode 100644 index 0000000..d60086a --- /dev/null +++ b/src/http2/hpack/huffman.zig @@ -0,0 +1,627 @@ +// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie +// SPDX-License-Identifier: MIT + +//! The Huffman code HPACK string literals may be written in: RFC 7541 +//! Appendix B. +//! +//! One table, transcribed from the appendix and laid out so that it can be +//! read against it line by line, and everything else in this file computed +//! from that table at compile time. That is the whole design, and it is a +//! choice about what can go wrong rather than about speed. +//! +//! ## Why a canonical walk and not a lookup table +//! +//! The fast way to decode a Huffman code is a multi-level lookup table — an +//! eight-bit root and sub-tables for the longer codes — which decodes a +//! symbol in one or two array reads. The fastest way is a generated state +//! machine, four bits at a time over 256 states, which is what nghttp2 does. +//! +//! Both are rejected here for the same reason: a reviewer cannot check either +//! against the RFC. A state machine is a blob emitted by a program that is not +//! in this repository, and a multi-level table is eighty lines of construction +//! code whose correctness is not visible from reading it. What is here instead +//! keeps the 257 rows looking like the appendix and derives the four small +//! arrays the decoder needs beside them, with the derivation asserting the +//! properties it depends on — so a mis-transcribed row fails to compile rather +//! than at three in the morning. +//! +//! The cost is up to thirty iterations per output octet instead of one lookup. +//! It is worth being precise about the adversarial case rather than waving at +//! it: a peer that codes every octet as a thirty-bit symbol makes the decoder +//! do thirty iterations per octet, but it had to spend thirty bits to buy +//! them. The work is one iteration per *input bit*, and the input is already +//! bounded by the frame layer and by `max_header_list_size`. Three +//! instructions per input bit on a bounded input is not a denial of service. +//! +//! If a benchmark ever says otherwise, the table below stays the single source +//! of truth and a lookup table can be derived from it at compile time without +//! anything else in this file changing. That is the other reason to structure +//! it this way. + +const std = @import("std"); +const assert = std.debug.assert; + +const Writer = std.Io.Writer; + +/// One row of Appendix B: the code, aligned to the least significant bit of +/// `bits`, and how many bits of it are meaningful. +pub const Code = struct { + bits: u32, + len: u5, +}; + +/// The end-of-string symbol. It is never emitted — RFC 7541 §5.2 requires a +/// string literal containing it to be refused — but it is part of the code, +/// and its top bits are what valid padding is made of. +pub const eos = 256; + +/// The longest code in the table. Worth knowing as a constant because it +/// bounds the decoder's bit accumulator. +pub const max_code_len = 30; + +/// RFC 7541 Appendix B, transcribed. The comment on each row is the +/// appendix's own label for the symbol, so that this table can be diffed +/// against the RFC by eye — which is the only defence against a transcription +/// error that there is. +/// +/// Every other table in this file is computed from this one, so this is the +/// only thing a reviewer has to check. +pub const codes: [257]Code = .{ + .{ .bits = 0x1ff8, .len = 13 }, // ( 0) + .{ .bits = 0x7fffd8, .len = 23 }, // ( 1) + .{ .bits = 0xfffffe2, .len = 28 }, // ( 2) + .{ .bits = 0xfffffe3, .len = 28 }, // ( 3) + .{ .bits = 0xfffffe4, .len = 28 }, // ( 4) + .{ .bits = 0xfffffe5, .len = 28 }, // ( 5) + .{ .bits = 0xfffffe6, .len = 28 }, // ( 6) + .{ .bits = 0xfffffe7, .len = 28 }, // ( 7) + .{ .bits = 0xfffffe8, .len = 28 }, // ( 8) + .{ .bits = 0xffffea, .len = 24 }, // ( 9) + .{ .bits = 0x3ffffffc, .len = 30 }, // ( 10) + .{ .bits = 0xfffffe9, .len = 28 }, // ( 11) + .{ .bits = 0xfffffea, .len = 28 }, // ( 12) + .{ .bits = 0x3ffffffd, .len = 30 }, // ( 13) + .{ .bits = 0xfffffeb, .len = 28 }, // ( 14) + .{ .bits = 0xfffffec, .len = 28 }, // ( 15) + .{ .bits = 0xfffffed, .len = 28 }, // ( 16) + .{ .bits = 0xfffffee, .len = 28 }, // ( 17) + .{ .bits = 0xfffffef, .len = 28 }, // ( 18) + .{ .bits = 0xffffff0, .len = 28 }, // ( 19) + .{ .bits = 0xffffff1, .len = 28 }, // ( 20) + .{ .bits = 0xffffff2, .len = 28 }, // ( 21) + .{ .bits = 0x3ffffffe, .len = 30 }, // ( 22) + .{ .bits = 0xffffff3, .len = 28 }, // ( 23) + .{ .bits = 0xffffff4, .len = 28 }, // ( 24) + .{ .bits = 0xffffff5, .len = 28 }, // ( 25) + .{ .bits = 0xffffff6, .len = 28 }, // ( 26) + .{ .bits = 0xffffff7, .len = 28 }, // ( 27) + .{ .bits = 0xffffff8, .len = 28 }, // ( 28) + .{ .bits = 0xffffff9, .len = 28 }, // ( 29) + .{ .bits = 0xffffffa, .len = 28 }, // ( 30) + .{ .bits = 0xffffffb, .len = 28 }, // ( 31) + .{ .bits = 0x14, .len = 6 }, // ' ' ( 32) + .{ .bits = 0x3f8, .len = 10 }, // '!' ( 33) + .{ .bits = 0x3f9, .len = 10 }, // '"' ( 34) + .{ .bits = 0xffa, .len = 12 }, // '#' ( 35) + .{ .bits = 0x1ff9, .len = 13 }, // '$' ( 36) + .{ .bits = 0x15, .len = 6 }, // '%' ( 37) + .{ .bits = 0xf8, .len = 8 }, // '&' ( 38) + .{ .bits = 0x7fa, .len = 11 }, // ''' ( 39) + .{ .bits = 0x3fa, .len = 10 }, // '(' ( 40) + .{ .bits = 0x3fb, .len = 10 }, // ')' ( 41) + .{ .bits = 0xf9, .len = 8 }, // '*' ( 42) + .{ .bits = 0x7fb, .len = 11 }, // '+' ( 43) + .{ .bits = 0xfa, .len = 8 }, // ',' ( 44) + .{ .bits = 0x16, .len = 6 }, // '-' ( 45) + .{ .bits = 0x17, .len = 6 }, // '.' ( 46) + .{ .bits = 0x18, .len = 6 }, // '/' ( 47) + .{ .bits = 0x0, .len = 5 }, // '0' ( 48) + .{ .bits = 0x1, .len = 5 }, // '1' ( 49) + .{ .bits = 0x2, .len = 5 }, // '2' ( 50) + .{ .bits = 0x19, .len = 6 }, // '3' ( 51) + .{ .bits = 0x1a, .len = 6 }, // '4' ( 52) + .{ .bits = 0x1b, .len = 6 }, // '5' ( 53) + .{ .bits = 0x1c, .len = 6 }, // '6' ( 54) + .{ .bits = 0x1d, .len = 6 }, // '7' ( 55) + .{ .bits = 0x1e, .len = 6 }, // '8' ( 56) + .{ .bits = 0x1f, .len = 6 }, // '9' ( 57) + .{ .bits = 0x5c, .len = 7 }, // ':' ( 58) + .{ .bits = 0xfb, .len = 8 }, // ';' ( 59) + .{ .bits = 0x7ffc, .len = 15 }, // '<' ( 60) + .{ .bits = 0x20, .len = 6 }, // '=' ( 61) + .{ .bits = 0xffb, .len = 12 }, // '>' ( 62) + .{ .bits = 0x3fc, .len = 10 }, // '?' ( 63) + .{ .bits = 0x1ffa, .len = 13 }, // '@' ( 64) + .{ .bits = 0x21, .len = 6 }, // 'A' ( 65) + .{ .bits = 0x5d, .len = 7 }, // 'B' ( 66) + .{ .bits = 0x5e, .len = 7 }, // 'C' ( 67) + .{ .bits = 0x5f, .len = 7 }, // 'D' ( 68) + .{ .bits = 0x60, .len = 7 }, // 'E' ( 69) + .{ .bits = 0x61, .len = 7 }, // 'F' ( 70) + .{ .bits = 0x62, .len = 7 }, // 'G' ( 71) + .{ .bits = 0x63, .len = 7 }, // 'H' ( 72) + .{ .bits = 0x64, .len = 7 }, // 'I' ( 73) + .{ .bits = 0x65, .len = 7 }, // 'J' ( 74) + .{ .bits = 0x66, .len = 7 }, // 'K' ( 75) + .{ .bits = 0x67, .len = 7 }, // 'L' ( 76) + .{ .bits = 0x68, .len = 7 }, // 'M' ( 77) + .{ .bits = 0x69, .len = 7 }, // 'N' ( 78) + .{ .bits = 0x6a, .len = 7 }, // 'O' ( 79) + .{ .bits = 0x6b, .len = 7 }, // 'P' ( 80) + .{ .bits = 0x6c, .len = 7 }, // 'Q' ( 81) + .{ .bits = 0x6d, .len = 7 }, // 'R' ( 82) + .{ .bits = 0x6e, .len = 7 }, // 'S' ( 83) + .{ .bits = 0x6f, .len = 7 }, // 'T' ( 84) + .{ .bits = 0x70, .len = 7 }, // 'U' ( 85) + .{ .bits = 0x71, .len = 7 }, // 'V' ( 86) + .{ .bits = 0x72, .len = 7 }, // 'W' ( 87) + .{ .bits = 0xfc, .len = 8 }, // 'X' ( 88) + .{ .bits = 0x73, .len = 7 }, // 'Y' ( 89) + .{ .bits = 0xfd, .len = 8 }, // 'Z' ( 90) + .{ .bits = 0x1ffb, .len = 13 }, // '[' ( 91) + .{ .bits = 0x7fff0, .len = 19 }, // '\' ( 92) + .{ .bits = 0x1ffc, .len = 13 }, // ']' ( 93) + .{ .bits = 0x3ffc, .len = 14 }, // '^' ( 94) + .{ .bits = 0x22, .len = 6 }, // '_' ( 95) + .{ .bits = 0x7ffd, .len = 15 }, // '`' ( 96) + .{ .bits = 0x3, .len = 5 }, // 'a' ( 97) + .{ .bits = 0x23, .len = 6 }, // 'b' ( 98) + .{ .bits = 0x4, .len = 5 }, // 'c' ( 99) + .{ .bits = 0x24, .len = 6 }, // 'd' (100) + .{ .bits = 0x5, .len = 5 }, // 'e' (101) + .{ .bits = 0x25, .len = 6 }, // 'f' (102) + .{ .bits = 0x26, .len = 6 }, // 'g' (103) + .{ .bits = 0x27, .len = 6 }, // 'h' (104) + .{ .bits = 0x6, .len = 5 }, // 'i' (105) + .{ .bits = 0x74, .len = 7 }, // 'j' (106) + .{ .bits = 0x75, .len = 7 }, // 'k' (107) + .{ .bits = 0x28, .len = 6 }, // 'l' (108) + .{ .bits = 0x29, .len = 6 }, // 'm' (109) + .{ .bits = 0x2a, .len = 6 }, // 'n' (110) + .{ .bits = 0x7, .len = 5 }, // 'o' (111) + .{ .bits = 0x2b, .len = 6 }, // 'p' (112) + .{ .bits = 0x76, .len = 7 }, // 'q' (113) + .{ .bits = 0x2c, .len = 6 }, // 'r' (114) + .{ .bits = 0x8, .len = 5 }, // 's' (115) + .{ .bits = 0x9, .len = 5 }, // 't' (116) + .{ .bits = 0x2d, .len = 6 }, // 'u' (117) + .{ .bits = 0x77, .len = 7 }, // 'v' (118) + .{ .bits = 0x78, .len = 7 }, // 'w' (119) + .{ .bits = 0x79, .len = 7 }, // 'x' (120) + .{ .bits = 0x7a, .len = 7 }, // 'y' (121) + .{ .bits = 0x7b, .len = 7 }, // 'z' (122) + .{ .bits = 0x7ffe, .len = 15 }, // '{' (123) + .{ .bits = 0x7fc, .len = 11 }, // '|' (124) + .{ .bits = 0x3ffd, .len = 14 }, // '}' (125) + .{ .bits = 0x1ffd, .len = 13 }, // '~' (126) + .{ .bits = 0xffffffc, .len = 28 }, // (127) + .{ .bits = 0xfffe6, .len = 20 }, // (128) + .{ .bits = 0x3fffd2, .len = 22 }, // (129) + .{ .bits = 0xfffe7, .len = 20 }, // (130) + .{ .bits = 0xfffe8, .len = 20 }, // (131) + .{ .bits = 0x3fffd3, .len = 22 }, // (132) + .{ .bits = 0x3fffd4, .len = 22 }, // (133) + .{ .bits = 0x3fffd5, .len = 22 }, // (134) + .{ .bits = 0x7fffd9, .len = 23 }, // (135) + .{ .bits = 0x3fffd6, .len = 22 }, // (136) + .{ .bits = 0x7fffda, .len = 23 }, // (137) + .{ .bits = 0x7fffdb, .len = 23 }, // (138) + .{ .bits = 0x7fffdc, .len = 23 }, // (139) + .{ .bits = 0x7fffdd, .len = 23 }, // (140) + .{ .bits = 0x7fffde, .len = 23 }, // (141) + .{ .bits = 0xffffeb, .len = 24 }, // (142) + .{ .bits = 0x7fffdf, .len = 23 }, // (143) + .{ .bits = 0xffffec, .len = 24 }, // (144) + .{ .bits = 0xffffed, .len = 24 }, // (145) + .{ .bits = 0x3fffd7, .len = 22 }, // (146) + .{ .bits = 0x7fffe0, .len = 23 }, // (147) + .{ .bits = 0xffffee, .len = 24 }, // (148) + .{ .bits = 0x7fffe1, .len = 23 }, // (149) + .{ .bits = 0x7fffe2, .len = 23 }, // (150) + .{ .bits = 0x7fffe3, .len = 23 }, // (151) + .{ .bits = 0x7fffe4, .len = 23 }, // (152) + .{ .bits = 0x1fffdc, .len = 21 }, // (153) + .{ .bits = 0x3fffd8, .len = 22 }, // (154) + .{ .bits = 0x7fffe5, .len = 23 }, // (155) + .{ .bits = 0x3fffd9, .len = 22 }, // (156) + .{ .bits = 0x7fffe6, .len = 23 }, // (157) + .{ .bits = 0x7fffe7, .len = 23 }, // (158) + .{ .bits = 0xffffef, .len = 24 }, // (159) + .{ .bits = 0x3fffda, .len = 22 }, // (160) + .{ .bits = 0x1fffdd, .len = 21 }, // (161) + .{ .bits = 0xfffe9, .len = 20 }, // (162) + .{ .bits = 0x3fffdb, .len = 22 }, // (163) + .{ .bits = 0x3fffdc, .len = 22 }, // (164) + .{ .bits = 0x7fffe8, .len = 23 }, // (165) + .{ .bits = 0x7fffe9, .len = 23 }, // (166) + .{ .bits = 0x1fffde, .len = 21 }, // (167) + .{ .bits = 0x7fffea, .len = 23 }, // (168) + .{ .bits = 0x3fffdd, .len = 22 }, // (169) + .{ .bits = 0x3fffde, .len = 22 }, // (170) + .{ .bits = 0xfffff0, .len = 24 }, // (171) + .{ .bits = 0x1fffdf, .len = 21 }, // (172) + .{ .bits = 0x3fffdf, .len = 22 }, // (173) + .{ .bits = 0x7fffeb, .len = 23 }, // (174) + .{ .bits = 0x7fffec, .len = 23 }, // (175) + .{ .bits = 0x1fffe0, .len = 21 }, // (176) + .{ .bits = 0x1fffe1, .len = 21 }, // (177) + .{ .bits = 0x3fffe0, .len = 22 }, // (178) + .{ .bits = 0x1fffe2, .len = 21 }, // (179) + .{ .bits = 0x7fffed, .len = 23 }, // (180) + .{ .bits = 0x3fffe1, .len = 22 }, // (181) + .{ .bits = 0x7fffee, .len = 23 }, // (182) + .{ .bits = 0x7fffef, .len = 23 }, // (183) + .{ .bits = 0xfffea, .len = 20 }, // (184) + .{ .bits = 0x3fffe2, .len = 22 }, // (185) + .{ .bits = 0x3fffe3, .len = 22 }, // (186) + .{ .bits = 0x3fffe4, .len = 22 }, // (187) + .{ .bits = 0x7ffff0, .len = 23 }, // (188) + .{ .bits = 0x3fffe5, .len = 22 }, // (189) + .{ .bits = 0x3fffe6, .len = 22 }, // (190) + .{ .bits = 0x7ffff1, .len = 23 }, // (191) + .{ .bits = 0x3ffffe0, .len = 26 }, // (192) + .{ .bits = 0x3ffffe1, .len = 26 }, // (193) + .{ .bits = 0xfffeb, .len = 20 }, // (194) + .{ .bits = 0x7fff1, .len = 19 }, // (195) + .{ .bits = 0x3fffe7, .len = 22 }, // (196) + .{ .bits = 0x7ffff2, .len = 23 }, // (197) + .{ .bits = 0x3fffe8, .len = 22 }, // (198) + .{ .bits = 0x1ffffec, .len = 25 }, // (199) + .{ .bits = 0x3ffffe2, .len = 26 }, // (200) + .{ .bits = 0x3ffffe3, .len = 26 }, // (201) + .{ .bits = 0x3ffffe4, .len = 26 }, // (202) + .{ .bits = 0x7ffffde, .len = 27 }, // (203) + .{ .bits = 0x7ffffdf, .len = 27 }, // (204) + .{ .bits = 0x3ffffe5, .len = 26 }, // (205) + .{ .bits = 0xfffff1, .len = 24 }, // (206) + .{ .bits = 0x1ffffed, .len = 25 }, // (207) + .{ .bits = 0x7fff2, .len = 19 }, // (208) + .{ .bits = 0x1fffe3, .len = 21 }, // (209) + .{ .bits = 0x3ffffe6, .len = 26 }, // (210) + .{ .bits = 0x7ffffe0, .len = 27 }, // (211) + .{ .bits = 0x7ffffe1, .len = 27 }, // (212) + .{ .bits = 0x3ffffe7, .len = 26 }, // (213) + .{ .bits = 0x7ffffe2, .len = 27 }, // (214) + .{ .bits = 0xfffff2, .len = 24 }, // (215) + .{ .bits = 0x1fffe4, .len = 21 }, // (216) + .{ .bits = 0x1fffe5, .len = 21 }, // (217) + .{ .bits = 0x3ffffe8, .len = 26 }, // (218) + .{ .bits = 0x3ffffe9, .len = 26 }, // (219) + .{ .bits = 0xffffffd, .len = 28 }, // (220) + .{ .bits = 0x7ffffe3, .len = 27 }, // (221) + .{ .bits = 0x7ffffe4, .len = 27 }, // (222) + .{ .bits = 0x7ffffe5, .len = 27 }, // (223) + .{ .bits = 0xfffec, .len = 20 }, // (224) + .{ .bits = 0xfffff3, .len = 24 }, // (225) + .{ .bits = 0xfffed, .len = 20 }, // (226) + .{ .bits = 0x1fffe6, .len = 21 }, // (227) + .{ .bits = 0x3fffe9, .len = 22 }, // (228) + .{ .bits = 0x1fffe7, .len = 21 }, // (229) + .{ .bits = 0x1fffe8, .len = 21 }, // (230) + .{ .bits = 0x7ffff3, .len = 23 }, // (231) + .{ .bits = 0x3fffea, .len = 22 }, // (232) + .{ .bits = 0x3fffeb, .len = 22 }, // (233) + .{ .bits = 0x1ffffee, .len = 25 }, // (234) + .{ .bits = 0x1ffffef, .len = 25 }, // (235) + .{ .bits = 0xfffff4, .len = 24 }, // (236) + .{ .bits = 0xfffff5, .len = 24 }, // (237) + .{ .bits = 0x3ffffea, .len = 26 }, // (238) + .{ .bits = 0x7ffff4, .len = 23 }, // (239) + .{ .bits = 0x3ffffeb, .len = 26 }, // (240) + .{ .bits = 0x7ffffe6, .len = 27 }, // (241) + .{ .bits = 0x3ffffec, .len = 26 }, // (242) + .{ .bits = 0x3ffffed, .len = 26 }, // (243) + .{ .bits = 0x7ffffe7, .len = 27 }, // (244) + .{ .bits = 0x7ffffe8, .len = 27 }, // (245) + .{ .bits = 0x7ffffe9, .len = 27 }, // (246) + .{ .bits = 0x7ffffea, .len = 27 }, // (247) + .{ .bits = 0x7ffffeb, .len = 27 }, // (248) + .{ .bits = 0xffffffe, .len = 28 }, // (249) + .{ .bits = 0x7ffffec, .len = 27 }, // (250) + .{ .bits = 0x7ffffed, .len = 27 }, // (251) + .{ .bits = 0x7ffffee, .len = 27 }, // (252) + .{ .bits = 0x7ffffef, .len = 27 }, // (253) + .{ .bits = 0x7fffff0, .len = 27 }, // (254) + .{ .bits = 0x3ffffee, .len = 26 }, // (255) + .{ .bits = 0x3fffffff, .len = 30 }, // EOS (256) +}; + +/// The table above, rearranged into what a decoder actually needs — and, +/// while it is being rearranged, checked. +/// +/// A canonical Huffman code has two properties that together make decoding a +/// matter of one comparison per bit: +/// +/// * **It is complete.** The Kraft sum — the total of `2^-len` over every +/// symbol — is exactly one, which means every infinite bit string starts +/// with exactly one code. No bit pattern is undecodable for want of a +/// symbol, so the decoder never has to ask whether it has gone wrong; it +/// only has to ask whether it has run out of input. +/// * **Each length's codes are one contiguous run**, and each run begins +/// where the previous length's ended, shifted up by one bit. That is what +/// makes `code < limit[len]` a sufficient test for "this is a code of +/// length `len`", and it is what turns the symbol lookup into an index. +/// +/// Both are asserted below at compile time. They are true of Appendix B, and +/// if a row is ever mistyped one of them stops being true — which is a build +/// failure naming this file rather than a server that decodes one header in a +/// million into somebody else's bytes. +const Canonical = struct { + /// How many symbols have a code of each length. + count: [max_code_len + 1]u16, + /// The numerically smallest code of each length. + first_code: [max_code_len + 1]u32, + /// One past the largest code of each length — `first_code + count`, + /// precomputed because it is what the decoder compares against. + limit: [max_code_len + 1]u32, + /// Where each length's symbols begin in `symbols`. + first_index: [max_code_len + 1]u16, + /// Every symbol, ordered by (length, code). For a canonical code that is + /// the same as ordered by code within each length, which is why the + /// decoder can index straight into it. + symbols: [257]u16, +}; + +const canonical: Canonical = build(); + +fn build() Canonical { + @setEvalBranchQuota(100_000); + + var c: Canonical = .{ + .count = @splat(0), + .first_code = @splat(0), + .limit = @splat(0), + .first_index = @splat(0), + .symbols = @splat(0), + }; + + for (codes) |code| { + assert(code.len >= 1 and code.len <= max_code_len); + // A code whose value does not fit in the length it claims is a + // mistyped row, and the cheapest one to catch. + assert(code.bits < (@as(u64, 1) << code.len)); + c.count[code.len] += 1; + } + + // Kraft's equality, computed in a fixed-point fraction with 2^-30 as its + // unit so that it is exact: a complete code sums to exactly 1 << 30. + var kraft: u64 = 0; + for (1..max_code_len + 1) |len| { + kraft += @as(u64, c.count[len]) << @intCast(max_code_len - len); + } + assert(kraft == @as(u64, 1) << max_code_len); + + // Lay out the runs, and check as we go that each one starts where the + // previous ended. + var code: u32 = 0; + var index: u16 = 0; + for (1..max_code_len + 1) |len| { + c.first_code[len] = code; + c.first_index[len] = index; + c.limit[len] = code + c.count[len]; + code = (code + c.count[len]) << 1; + index += c.count[len]; + } + assert(index == codes.len); + + // And place the symbols, which is also where "contiguous" is checked: a + // code that is not `first_code[len] + n` for the n-th symbol of that + // length would land outside its run. + var next: [max_code_len + 1]u16 = @splat(0); + for (codes, 0..) |entry, symbol| { + const offset = entry.bits - c.first_code[entry.len]; + assert(offset < c.count[entry.len]); + assert(next[entry.len] <= c.count[entry.len]); + c.symbols[c.first_index[entry.len] + offset] = @intCast(symbol); + next[entry.len] += 1; + } + + return c; +} + +/// The octets `s` occupies once Huffman-coded, padding included. +/// +/// `lowercase` maps A-Z to a-z on the way, because RFC 9113 §8.2.1 requires +/// field names to be lower case on the wire and `protocol.Headers` +/// deliberately keeps them as the handler wrote them. Doing it here rather +/// than in a buffer somewhere is what makes the conversion free. +pub fn encodedLen(s: []const u8, lowercase: bool) usize { + var bits: usize = 0; + for (s) |raw| bits += codes[fold(raw, lowercase)].len; + return (bits + 7) / 8; +} + +/// Whether Huffman coding `s` would make it shorter. RFC 7541 §5.2 leaves the +/// choice to the encoder, and a coded string longer than its input is one the +/// decoder has to do more work to get back. +pub fn worthwhile(s: []const u8, lowercase: bool) bool { + return encodedLen(s, lowercase) < s.len; +} + +fn fold(c: u8, lowercase: bool) u8 { + return if (lowercase and c >= 'A' and c <= 'Z') c + 32 else c; +} + +/// Writes `s` Huffman-coded. The final octet is padded with the most +/// significant bits of the EOS code, which are all ones — §5.2 requires +/// exactly that, and `decode` refuses anything else. +pub fn encode(out: *Writer, s: []const u8, lowercase: bool) Writer.Error!void { + var acc: u64 = 0; + var bits: u6 = 0; + for (s) |raw| { + const code = codes[fold(raw, lowercase)]; + acc = (acc << code.len) | code.bits; + bits += code.len; + while (bits >= 8) { + bits -= 8; + try out.writeByte(@truncate(acc >> bits)); + } + } + if (bits != 0) { + const pad: u6 = 8 - bits; + try out.writeByte(@truncate((acc << pad) | ((@as(u64, 1) << pad) - 1))); + } +} + +pub const DecodeError = error{ + /// RFC 7541 §5.2: "A padding strictly longer than 7 bits MUST be treated + /// as a decoding error." + /// + /// Reachable because the all-ones padding is a prefix of EOS and no + /// all-ones string shorter than thirty bits completes any code, so eight + /// or more leftover bits can only be over-long padding. + PaddingTooLong, + /// RFC 7541 §5.2: "A padding not corresponding to the most significant + /// bits of the code corresponding to the EOS symbol MUST be treated as a + /// decoding error." Which is to say the leftover bits must all be ones. + BadPadding, + /// RFC 7541 §5.2: "A Huffman-encoded string literal containing the EOS + /// symbol MUST be treated as a decoding error." + /// + /// It is forbidden because it is a second way to say where a string ends, + /// and two ways is one too many: an intermediary that honoured it and one + /// that did not would disagree about the length of a header. + EosInInput, + /// The decoded string is longer than the buffer it was given. + StringTooLong, +}; + +/// Decodes `src` into `dst`, returning the part of `dst` that was used. +pub fn decode(src: []const u8, dst: []u8) DecodeError![]u8 { + // The live bits, right-aligned in `acc`, with `bits` of them meaningful. + // Never more than 37 at once — 30 for the longest code plus the seven that + // can be left over — so nothing is ever shifted off the top. + var acc: u64 = 0; + var bits: u6 = 0; + var read: usize = 0; + var written: usize = 0; + + while (true) { + while (bits <= max_code_len - 1 and read < src.len) : (read += 1) { + acc = (acc << 8) | src[read]; + bits += 8; + } + if (bits == 0) return dst[0..written]; + + // Walk the bits, longest-possible-code first, stopping the moment the + // accumulated value falls inside a length's run. One comparison per + // bit, and no search: a shorter code would already have matched. + var len: u5 = 0; + var code: u32 = 0; + const symbol: ?u16 = found: while (len < max_code_len) { + if (len == bits) break :found null; + len += 1; + // Parenthesised deliberately: in Zig `&`, `^` and `|` share one + // precedence level and associate left, so without them this reads + // as `(code | bit) & 1` and the accumulated code never exceeds a + // single bit. + code = (code << 1) | (@as(u32, @truncate(acc >> (bits - len))) & 1); + if (code < canonical.limit[len]) { + const offset = code - canonical.first_code[len]; + break :found canonical.symbols[canonical.first_index[len] + offset]; + } + } else null; + + const sym = symbol orelse { + // Nothing left but padding: `bits` of it, which must be the top + // `bits` bits of EOS, which are all ones. + if (bits > 7) return error.PaddingTooLong; + if (code != (@as(u32, 1) << @intCast(bits)) - 1) return error.BadPadding; + return dst[0..written]; + }; + if (sym == eos) return error.EosInInput; + if (written == dst.len) return error.StringTooLong; + dst[written] = @intCast(sym); + written += 1; + bits -= len; + acc &= (@as(u64, 1) << bits) - 1; + } +} + +const testing = std.testing; + +fn expectRoundTrip(s: []const u8) !void { + var buffer: [1024]u8 = undefined; + var w: Writer = .fixed(&buffer); + try encode(&w, s, false); + try testing.expectEqual(encodedLen(s, false), w.end); + + var back: [1024]u8 = undefined; + try testing.expectEqualStrings(s, try decode(buffer[0..w.end], &back)); +} + +test "every octet survives a round trip, alone and in company" { + for (0..256) |i| { + const one = [_]u8{@intCast(i)}; + try expectRoundTrip(&one); + } + var all: [256]u8 = undefined; + for (&all, 0..) |*c, i| c.* = @intCast(i); + try expectRoundTrip(&all); + try expectRoundTrip(""); + try expectRoundTrip("www.example.com"); + try expectRoundTrip("no-cache"); + try expectRoundTrip("custom-key"); +} + +test "the strings RFC 7541 Appendix C.4 codes" { + // C.4.1: "www.example.com" is fifteen octets and codes to twelve. + var buffer: [64]u8 = undefined; + var w: Writer = .fixed(&buffer); + try encode(&w, "www.example.com", false); + try testing.expectEqualSlices(u8, &.{ + 0xf1, 0xe3, 0xc2, 0xe5, 0xf2, 0x3a, 0x6b, 0xa0, 0xab, 0x90, 0xf4, 0xff, + }, buffer[0..w.end]); + + // C.4.2: "no-cache". + w = .fixed(&buffer); + try encode(&w, "no-cache", false); + try testing.expectEqualSlices(u8, &.{ + 0xa8, 0xeb, 0x10, 0x64, 0x9c, 0xbf, + }, buffer[0..w.end]); +} + +test "lower-casing on the way out" { + var buffer: [64]u8 = undefined; + var w: Writer = .fixed(&buffer); + try encode(&w, "Content-Type", true); + + var back: [64]u8 = undefined; + try testing.expectEqualStrings("content-type", try decode(buffer[0..w.end], &back)); + try testing.expectEqual(encodedLen("Content-Type", true), w.end); +} + +test "the three conditions RFC 7541 requires to be refused" { + var back: [64]u8 = undefined; + + // An explicit EOS: thirty one-bits, then padding. Refused even though it + // is a perfectly good code, because §5.2 says so. + try testing.expectError(error.EosInInput, decode(&.{ 0xff, 0xff, 0xff, 0xff }, &back)); + + // Padding of eight bits or more. `0x14` is ' ' in six bits; the two bits + // left over are fine, but a whole extra all-ones octet is not. + try testing.expectError(error.PaddingTooLong, decode(&.{ 0x53, 0xff }, &back)); + + // Padding that is not all ones. `0x50` is ' ' followed by two zero bits. + try testing.expectError(error.BadPadding, decode(&.{0x50}, &back)); +} + +test "a decode that will not fit is refused rather than truncated" { + var tiny: [2]u8 = undefined; + // "www.example.com" needs fifteen octets and is being given two. + try testing.expectError(error.StringTooLong, decode(&.{ + 0xf1, 0xe3, 0xc2, 0xe5, 0xf2, 0x3a, 0x6b, 0xa0, 0xab, 0x90, 0xf4, 0xff, + }, &tiny)); +} + +test "the derived tables agree with the transcribed one" { + // Everything `build` asserts is checked at compile time; this checks the + // result the other way round, by walking every symbol back out of the + // tables the decoder actually reads. + for (codes, 0..) |code, symbol| { + const offset = code.bits - canonical.first_code[code.len]; + const index = canonical.first_index[code.len] + offset; + try testing.expectEqual(@as(u16, @intCast(symbol)), canonical.symbols[index]); + try testing.expect(code.bits < canonical.limit[code.len]); + } +} diff --git a/src/http2/hpack/table.zig b/src/http2/hpack/table.zig new file mode 100644 index 0000000..d873f65 --- /dev/null +++ b/src/http2/hpack/table.zig @@ -0,0 +1,377 @@ +// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie +// SPDX-License-Identifier: MIT + +//! The two tables an HPACK index can name: the static one from RFC 7541 +//! Appendix A, and the dynamic one of §2.3.2. +//! +//! They share one index space (§2.3.3): 1 through 61 are the static table, +//! and 62 upwards are the dynamic table with the *most recently added* entry +//! first. That ordering is the thing to keep in mind while reading this file +//! — a dynamic entry's index changes every time another is inserted, which is +//! why nothing here hands out indices that are meant to be kept. + +const std = @import("std"); +const Allocator = std.mem.Allocator; + +const protocol = @import("../../protocol.zig"); +const Field = protocol.Field; +const token = protocol.token; + +/// RFC 7541 Appendix A, transcribed. An empty value means the entry names a +/// field whose value is always given as a literal. +pub const static: [61]Field = .{ + .{ .name = ":authority", .value = "" }, // 1 + .{ .name = ":method", .value = "GET" }, // 2 + .{ .name = ":method", .value = "POST" }, // 3 + .{ .name = ":path", .value = "/" }, // 4 + .{ .name = ":path", .value = "/index.html" }, // 5 + .{ .name = ":scheme", .value = "http" }, // 6 + .{ .name = ":scheme", .value = "https" }, // 7 + .{ .name = ":status", .value = "200" }, // 8 + .{ .name = ":status", .value = "204" }, // 9 + .{ .name = ":status", .value = "206" }, // 10 + .{ .name = ":status", .value = "304" }, // 11 + .{ .name = ":status", .value = "400" }, // 12 + .{ .name = ":status", .value = "404" }, // 13 + .{ .name = ":status", .value = "500" }, // 14 + .{ .name = "accept-charset", .value = "" }, // 15 + .{ .name = "accept-encoding", .value = "gzip, deflate" }, // 16 + .{ .name = "accept-language", .value = "" }, // 17 + .{ .name = "accept-ranges", .value = "" }, // 18 + .{ .name = "accept", .value = "" }, // 19 + .{ .name = "access-control-allow-origin", .value = "" }, // 20 + .{ .name = "age", .value = "" }, // 21 + .{ .name = "allow", .value = "" }, // 22 + .{ .name = "authorization", .value = "" }, // 23 + .{ .name = "cache-control", .value = "" }, // 24 + .{ .name = "content-disposition", .value = "" }, // 25 + .{ .name = "content-encoding", .value = "" }, // 26 + .{ .name = "content-language", .value = "" }, // 27 + .{ .name = "content-length", .value = "" }, // 28 + .{ .name = "content-location", .value = "" }, // 29 + .{ .name = "content-range", .value = "" }, // 30 + .{ .name = "content-type", .value = "" }, // 31 + .{ .name = "cookie", .value = "" }, // 32 + .{ .name = "date", .value = "" }, // 33 + .{ .name = "etag", .value = "" }, // 34 + .{ .name = "expect", .value = "" }, // 35 + .{ .name = "expires", .value = "" }, // 36 + .{ .name = "from", .value = "" }, // 37 + .{ .name = "host", .value = "" }, // 38 + .{ .name = "if-match", .value = "" }, // 39 + .{ .name = "if-modified-since", .value = "" }, // 40 + .{ .name = "if-none-match", .value = "" }, // 41 + .{ .name = "if-range", .value = "" }, // 42 + .{ .name = "if-unmodified-since", .value = "" }, // 43 + .{ .name = "last-modified", .value = "" }, // 44 + .{ .name = "link", .value = "" }, // 45 + .{ .name = "location", .value = "" }, // 46 + .{ .name = "max-forwards", .value = "" }, // 47 + .{ .name = "proxy-authenticate", .value = "" }, // 48 + .{ .name = "proxy-authorization", .value = "" }, // 49 + .{ .name = "range", .value = "" }, // 50 + .{ .name = "referer", .value = "" }, // 51 + .{ .name = "refresh", .value = "" }, // 52 + .{ .name = "retry-after", .value = "" }, // 53 + .{ .name = "server", .value = "" }, // 54 + .{ .name = "set-cookie", .value = "" }, // 55 + .{ .name = "strict-transport-security", .value = "" }, // 56 + .{ .name = "transfer-encoding", .value = "" }, // 57 + .{ .name = "user-agent", .value = "" }, // 58 + .{ .name = "vary", .value = "" }, // 59 + .{ .name = "via", .value = "" }, // 60 + .{ .name = "www-authenticate", .value = "" }, // 61 +}; + +/// Where each name's run begins and ends in `static`, as zero-based offsets. +/// Entries sharing a name are contiguous in Appendix A — asserted below — so +/// one hash gets the run and a short scan finds the value. +const Run = struct { first: u8, last: u8 }; + +const by_name = blk: { + @setEvalBranchQuota(20_000); + var pairs: [static.len]struct { []const u8, Run } = undefined; + var count: usize = 0; + var i: usize = 0; + while (i < static.len) { + var j = i; + while (j + 1 < static.len and + std.mem.eql(u8, static[j + 1].name, static[i].name)) : (j += 1) + {} + // The property the run representation depends on: a name may not + // reappear later in the table. A transcription that scrambled the + // order would fail here rather than silently making some entries + // unfindable. + for (static[j + 1 ..]) |later| { + if (std.mem.eql(u8, later.name, static[i].name)) { + @compileError("static table entries for " ++ static[i].name ++ " are not contiguous"); + } + } + pairs[count] = .{ static[i].name, .{ .first = i, .last = j } }; + count += 1; + i = j + 1; + } + break :blk std.StaticStringMap(Run).initComptime(pairs[0..count].*); +}; + +/// The index of the static entry with this name and value, or null. +/// +/// Names are compared without regard to case because the encoder is fed them +/// as the handler wrote them, and `Headers` deliberately keeps that spelling. +/// Values are compared exactly — `GET` and `get` are different methods. +pub fn findStatic(name: []const u8, value: []const u8) ?u8 { + const run = by_name.get(name) orelse return findStaticSlow(name, value); + var i = run.first; + while (i <= run.last) : (i += 1) { + if (std.mem.eql(u8, static[i].value, value)) return i + 1; + } + return null; +} + +/// The lowest index of any static entry with this name, which is what a +/// literal with an indexed name wants. +pub fn findStaticName(name: []const u8) ?u8 { + if (by_name.get(name)) |run| return run.first + 1; + return findStaticNameSlow(name); +} + +/// The case-insensitive fallback. `StaticStringMap` hashes exactly, so a name +/// that is not already lower case misses it and lands here — which is the +/// common path for a response, since the library's own `sendStatus` sets +/// `Content-Type`. +fn findStaticSlow(name: []const u8, value: []const u8) ?u8 { + for (static, 0..) |entry, i| { + if (token.eqlIgnoreCase(entry.name, name) and std.mem.eql(u8, entry.value, value)) { + return @intCast(i + 1); + } + } + return null; +} + +fn findStaticNameSlow(name: []const u8) ?u8 { + for (static, 0..) |entry, i| { + if (token.eqlIgnoreCase(entry.name, name)) return @intCast(i + 1); + } + return null; +} + +/// The overhead RFC 7541 §4.1 charges each entry, on top of its name and +/// value. +/// +/// It is not the real cost of this data structure and is not meant to be. It +/// is a fixed estimate so that two endpoints with entirely different +/// representations agree about the exact moment an eviction happens — and +/// they must agree, because an eviction one end makes and the other does not +/// shifts every index after it. +pub const entry_overhead = 32; + +pub const Dynamic = struct { + /// Newest first, so that the HPACK index and the slot index differ by a + /// constant and the code reads the way §2.3.3 draws it. Insertion is + /// therefore an insert at zero — a move of at most a few hundred slots, + /// since the capacity divided by `entry_overhead` bounds the count — and + /// eviction is a pop from the end, which is the operation that must not + /// be got wrong. + entries: std.ArrayList(Entry) = .empty, + /// The running total. A field rather than a computation because eviction + /// compares against it on every insertion, and recomputing it is how the + /// two drift apart. + size: u32 = 0, + /// The capacity in force, which a dynamic table size update sets. + capacity: u32, + /// The ceiling such an update may not exceed: `SETTINGS_HEADER_TABLE_SIZE` + /// as this endpoint advertised it. + max_capacity: u32, + + pub const Entry = struct { + /// Owned. The field section these came from is gone by the time this + /// entry is indexed; see the note at the top of `hpack.zig`. + name: []const u8, + value: []const u8, + + pub fn size(e: Entry) u32 { + return @intCast(e.name.len + e.value.len + entry_overhead); + } + }; + + pub fn init(max_capacity: u32) Dynamic { + return .{ .capacity = max_capacity, .max_capacity = max_capacity }; + } + + pub fn deinit(d: *Dynamic, gpa: Allocator) void { + for (d.entries.items) |e| { + gpa.free(e.name); + gpa.free(e.value); + } + d.entries.deinit(gpa); + d.* = undefined; + } + + /// The entry at an HPACK index, which for the dynamic table starts at 62. + pub fn get(d: *const Dynamic, index: u32) ?Entry { + if (index <= static.len) return null; + const slot = index - static.len - 1; + if (slot >= d.entries.items.len) return null; + return d.entries.items[slot]; + } + + pub const InsertError = Allocator.Error; + + /// Adds an entry, evicting from the end until it fits. + /// + /// RFC 7541 §4.4: "It is not an error to attempt to add an entry that is + /// larger than the maximum size; an attempt to add an entry larger than + /// the maximum size causes the table to be emptied of all existing + /// entries and results in an empty table." That sentence is the whole + /// reason this is not three lines, and it has a test of its own. + pub fn insert(d: *Dynamic, gpa: Allocator, name: []const u8, value: []const u8) InsertError!void { + const wanted: u32 = @intCast(name.len + value.len + entry_overhead); + d.evictTo(gpa, if (wanted > d.capacity) 0 else d.capacity - wanted); + if (wanted > d.capacity) return; + + const owned_name = try gpa.dupe(u8, name); + errdefer gpa.free(owned_name); + const owned_value = try gpa.dupe(u8, value); + errdefer gpa.free(owned_value); + + try d.entries.insert(gpa, 0, .{ .name = owned_name, .value = owned_value }); + d.size += wanted; + } + + pub const CapacityError = error{ + /// A dynamic table size update above `SETTINGS_HEADER_TABLE_SIZE` + /// (RFC 7541 §6.3). + TableSizeTooLarge, + }; + + /// A dynamic table size update. + pub fn setCapacity(d: *Dynamic, gpa: Allocator, n: u32) CapacityError!void { + if (n > d.max_capacity) return error.TableSizeTooLarge; + d.capacity = n; + d.evictTo(gpa, n); + } + + /// Called when the peer acknowledges a SETTINGS frame of ours that + /// changed `SETTINGS_HEADER_TABLE_SIZE` — **not** when that frame is + /// sent. + /// + /// Until the acknowledgement arrives the peer is entitled to go on using + /// the old size, so lowering this early makes a conformant peer look like + /// it is breaking the rules. A real interoperability bug rather than a + /// theoretical one. + pub fn setMaxCapacity(d: *Dynamic, gpa: Allocator, n: u32) void { + d.max_capacity = n; + if (d.capacity > n) { + d.capacity = n; + d.evictTo(gpa, n); + } + } + + fn evictTo(d: *Dynamic, gpa: Allocator, limit: u32) void { + while (d.size > limit) { + const last = d.entries.pop() orelse break; + d.size -= last.size(); + gpa.free(last.name); + gpa.free(last.value); + } + } +}; + +const testing = std.testing; + +test "the static table is the one in Appendix A" { + try testing.expectEqual(@as(usize, 61), static.len); + try testing.expectEqualStrings(":authority", static[0].name); + try testing.expectEqualStrings("", static[0].value); + try testing.expectEqualStrings("www-authenticate", static[60].name); + + // The worked lookups RFC 7541 uses in Appendix C. + try testing.expectEqual(@as(u8, 2), findStatic(":method", "GET").?); + try testing.expectEqual(@as(u8, 6), findStatic(":scheme", "http").?); + try testing.expectEqual(@as(u8, 4), findStatic(":path", "/").?); + try testing.expectEqual(@as(u8, 8), findStatic(":status", "200").?); + try testing.expectEqual(@as(u8, 1), findStaticName(":authority").?); + try testing.expectEqual(@as(u8, 8), findStaticName(":status").?); + + try testing.expect(findStatic(":method", "PROPFIND") == null); + try testing.expect(findStaticName("x-made-up") == null); +} + +test "names are matched without regard to case, values exactly" { + // Which is the path the library's own `sendStatus` takes, since it sets + // `Content-Type` rather than `content-type`. + try testing.expectEqual(@as(u8, 31), findStaticName("Content-Type").?); + try testing.expectEqual(@as(u8, 31), findStaticName("content-type").?); + // A method is case-sensitive and `get` is not `GET`. + try testing.expect(findStatic(":method", "get") == null); +} + +test "insertion, indexing and eviction" { + const gpa = testing.allocator; + var d: Dynamic = .init(256); + defer d.deinit(gpa); + + try d.insert(gpa, "custom-key", "custom-value"); + try testing.expectEqual(@as(u32, 10 + 12 + 32), d.size); + // The newest entry is 62, immediately after the static table. + try testing.expectEqualStrings("custom-key", d.get(62).?.name); + try testing.expect(d.get(63) == null); + // An index inside the static table is not this table's business. + try testing.expect(d.get(61) == null); + + try d.insert(gpa, "second", "entry"); + // And now the newest is 62 and the first has moved down. + try testing.expectEqualStrings("second", d.get(62).?.name); + try testing.expectEqualStrings("custom-key", d.get(63).?.name); +} + +test "an entry larger than the capacity empties the table and is not added" { + // RFC 7541 §4.4, quoted in `insert`. It is deliberately not an error. + const gpa = testing.allocator; + var d: Dynamic = .init(100); + defer d.deinit(gpa); + + try d.insert(gpa, "small", "one"); + try testing.expectEqual(@as(usize, 1), d.entries.items.len); + + try d.insert(gpa, "x" ** 40, "y" ** 40); + try testing.expectEqual(@as(usize, 0), d.entries.items.len); + try testing.expectEqual(@as(u32, 0), d.size); +} + +test "a size update evicts, and one above the ceiling is refused" { + const gpa = testing.allocator; + var d: Dynamic = .init(4096); + defer d.deinit(gpa); + + try d.insert(gpa, "aaaa", "bbbb"); + try d.insert(gpa, "cccc", "dddd"); + try testing.expectEqual(@as(u32, 80), d.size); + + // Down to one entry's worth. + try d.setCapacity(gpa, 40); + try testing.expectEqual(@as(usize, 1), d.entries.items.len); + // The one kept is the newest. + try testing.expectEqualStrings("cccc", d.get(62).?.name); + + try d.setCapacity(gpa, 0); + try testing.expectEqual(@as(usize, 0), d.entries.items.len); + + try testing.expectError(error.TableSizeTooLarge, d.setCapacity(gpa, 4097)); +} + +test "the recorded size is always the sum of the entries" { + const gpa = testing.allocator; + var d: Dynamic = .init(300); + defer d.deinit(gpa); + + const names = [_][]const u8{ "a", "bb", "ccc", "dddd", "eeeee" }; + for (0..40) |i| { + const n = names[i % names.len]; + try d.insert(gpa, n, n); + var total: u32 = 0; + for (d.entries.items) |e| total += e.size(); + try testing.expectEqual(total, d.size); + try testing.expect(d.size <= d.capacity); + } +} diff --git a/src/root.zig b/src/root.zig index 0e63267..1359cc2 100644 --- a/src/root.zig +++ b/src/root.zig @@ -103,6 +103,7 @@ const std = @import("std"); pub const http1 = @import("http1.zig"); +pub const http2 = @import("http2.zig"); pub const protocol = @import("protocol.zig"); pub const server = @import("server.zig"); pub const transport = @import("transport.zig"); -- knotmirror 0.0.1