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.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! The HPACK decoder: RFC 7541 §6, the five representations a field section//! is made of.//!//! Stateful, and the state is per *connection* — the dynamic table is built//! by every field section in arrival order, so sections must be decoded in//! the order they arrived and exactly once. That is why decoding belongs to//! the connection's reader task and nothing else, and why a decode that fails//! part way through cannot be retried: the table is now a guess.//!//! Pure in the sense that matters: it takes a slice, not a connection.//! Reassembling a HEADERS frame and its CONTINUATION frames into that slice//! is the driver's job, which is what lets this be fuzzed on a string the way//! `http1.head.parse` is.
const std = @import("std");const Allocator = std.mem.Allocator;
const protocol = @import("../../protocol.zig");const Field = protocol.Field;
const hpack = @import("../hpack.zig");const table = @import("table.zig");const Cursor = hpack.Cursor;
const Decoder = @This();
table_: table.Dynamic,/// Where a Huffman-coded string is decoded before it is measured and copied.////// Owned by the caller and handed over at `init`, the same way/// `http1.head.read` is handed the buffer it reads a head into: how much/// memory a connection costs is the server's policy, not this type's.////// Its length is the longest single name or value that can be decoded, which/// is why exceeding it is fatal to the connection — see `StringTooLong`.scratch: []u8,limits: Limits,
pub const Limits = struct { /// `SETTINGS_MAX_HEADER_LIST_SIZE` as this endpoint advertises it, /// counted the way RFC 9113 §6.5.2 counts it: the uncompressed name and /// value plus 32 per field — deliberately the same accounting as a /// dynamic table entry, so that one number bounds both. max_header_list_size: u32 = 32 * 1024,};
pub const CompressionError = error{ /// The section ended in the middle of a representation. Truncated, /// An index naming neither a static entry nor a live dynamic one. /// /// Index zero is in here too: RFC 7541 §6.1 says "the index value of 0 is /// not used", so an indexed field representation of zero is malformed. InvalidIndex, IntegerOverflow, /// The four conditions RFC 7541 §5.2 puts on a Huffman string, kept apart /// so that a failure names the rule it broke. PaddingTooLong, BadPadding, EosInInput, /// A single name or value longer than `scratch`. /// /// This is the one size limit that has to be fatal to the connection /// rather than to the stream, and the reason is worth following. A field /// that cannot be decoded cannot be inserted into the dynamic table; a /// table that missed an insertion no longer matches the peer's; and every /// index after it means something different to each end. There is no way /// back from that except a new connection. So `scratch` is sized /// generously and a peer that reaches it is not a peer with a large /// cookie. StringTooLong, /// A dynamic table size update above `SETTINGS_HEADER_TABLE_SIZE` /// (RFC 7541 §6.3). TableSizeTooLarge, /// A dynamic table size update that was not at the start of the section. /// /// RFC 7541 §4.2 requires the update to come first, and the reason is /// that it is a statement about the table the *rest of this section* is /// indexed against. One in the middle would mean the indices before it /// and after it were resolved against different tables. SizeUpdateNotFirst,};
pub const LimitError = error{ /// The section decoded to more than `max_header_list_size`. /// /// Deliberately not a compression error, and the distinction is /// load-bearing: RFC 9113 §6.5.2 says an endpoint receiving a field /// section larger than it advertised "MUST NOT consider it a connection /// error" — the right answer is `431` on that one stream. Which in turn /// means the section has to be decoded all the way to the end anyway, to /// keep the dynamic table in step with the peer's, and `decode` does /// exactly that: past the budget it stops appending and stops copying, /// keeps decoding, keeps the table in step, and reports this at the end. HeaderListTooLarge,};
pub const Error = CompressionError || LimitError || Allocator.Error;
/// Whether a failure takes the whole connection down.////// Exhaustive on purpose: a new member of `Error` cannot be added without/// somebody deciding which of the two it is.pub fn isCompressionError(err: Error) bool { return switch (err) { error.Truncated, error.InvalidIndex, error.IntegerOverflow, error.PaddingTooLong, error.BadPadding, error.EosInInput, error.StringTooLong, error.TableSizeTooLarge, error.SizeUpdateNotFirst, => true, error.HeaderListTooLarge, error.OutOfMemory => false, };}
test isCompressionError { // A table that may have missed an insertion poisons every later section. try std.testing.expect(isCompressionError(error.InvalidIndex)); // An oversized section is one stream's 431, and the table is still good. try std.testing.expect(!isCompressionError(error.HeaderListTooLarge));}
/// A decoder with an empty dynamic table.////// `header_table_size` is `SETTINGS_HEADER_TABLE_SIZE` as this endpoint/// advertises it, the ceiling for the peer's size updates. `scratch` is/// borrowed for the decoder's life; see the field of that name.pub fn init(header_table_size: u32, scratch: []u8, limits: Limits) Decoder { return .{ .table_ = .init(header_table_size), .scratch = scratch, .limits = limits, };}
test init { var scratch: [4096]u8 = undefined; var d: Decoder = .init(4096, &scratch, .{ .max_header_list_size = 16 * 1024 }); defer d.deinit(std.testing.allocator); try std.testing.expectEqual(@as(u32, 16 * 1024), d.limits.max_header_list_size);}
/// Frees the dynamic table. `gpa` must be the one every `decode` was given;/// `scratch` is the caller's and is not freed here.pub fn deinit(d: *Decoder, gpa: Allocator) void { d.table_.deinit(gpa); d.* = undefined;}
test deinit { var scratch: [64]u8 = undefined; var d: Decoder = .init(4096, &scratch, .{}); d.deinit(std.testing.allocator);}
/// Called when the peer acknowledges a SETTINGS frame of ours that changed/// `SETTINGS_HEADER_TABLE_SIZE`. See `table.Dynamic.setMaxCapacity` for why/// it is the acknowledgement and not the send.pub fn setMaxTableSize(d: *Decoder, gpa: Allocator, n: u32) void { d.table_.setMaxCapacity(gpa, n);}
test setMaxTableSize { const gpa = std.testing.allocator; var scratch: [64]u8 = undefined; var d: Decoder = .init(4096, &scratch, .{}); defer d.deinit(gpa); d.setMaxTableSize(gpa, 0);
var arena_state: std.heap.ArenaAllocator = .init(gpa); defer arena_state.deinit(); var fields: std.ArrayList(Field) = .empty; // A size update to 16 is now above the ceiling, which is fatal. try std.testing.expectError( error.TableSizeTooLarge, d.decode(gpa, arena_state.allocator(), &.{0x30}, &fields), );}
/// Appends the decoded fields to `fields`, copying every name and value into/// `arena` — with the one exception described at the top of `hpack.zig`./// `fields` is grown with `arena` too, so it is freed along with the strings.////// `gpa` is the dynamic table's allocator and lives as long as the/// connection; `arena` is the field section's and lives as long as the stream.////// A failure for which `isCompressionError` is true leaves the dynamic table/// out of step with the peer's, and nothing more may be decoded. A/// `HeaderListTooLarge` does not: the whole section was decoded and the table/// kept, but `fields` holds only what fit in the budget.pub fn decode( d: *Decoder, gpa: Allocator, arena: Allocator, block: []const u8, fields: *std.ArrayList(Field),) Error!void { var c: Cursor = .{ .bytes = block }; var used: u64 = 0; var over = false; var saw_field = false;
while (!c.atEnd()) { const first = try c.peekByte();
if (first & 0x80 != 0) { // §6.1, indexed field: name and value both come from a table. const index = try c.int(7); if (index == 0) return error.InvalidIndex; const entry = try d.lookup(index); try d.emit(arena, fields, entry.name, entry.value, entry.owned, &used, &over); saw_field = true; continue; }
if (first & 0x20 != 0 and first & 0xc0 == 0) { // §6.3, dynamic table size update. `001xxxxx`. if (saw_field) return error.SizeUpdateNotFirst; const size = try c.int(5); try d.table_.setCapacity(gpa, size); continue; }
// The three literal forms differ only in what they do to the table // and in what they promise an intermediary. const indexing: enum { incremental, without, never } = if (first & 0x40 != 0) .incremental else if (first & 0x10 != 0) .never else .without; const prefix_bits: u4 = if (indexing == .incremental) 6 else 4;
const name_index = try c.int(prefix_bits); var name_owned = true; var name = if (name_index == 0) blk: { break :blk try d.copyString(arena, &c, &name_owned); } else blk: { const entry = try d.lookup(name_index); name_owned = entry.owned; break :blk entry.name; };
var value_owned = true; const value = try d.copyString(arena, &c, &value_owned);
if (indexing == .incremental) { // RFC 7541 §4.4 warns about exactly this: "The name of the new // entry may reference the name of an entry in the dynamic table // that is evicted" -- and `insert` evicts before it copies, so // by the time it reads `name` the octets it points at have been // freed. Copying first is the only order that works, and it is // not a copy wasted: the same slice is about to be handed to // `emit`, which would have to copy it anyway. // // Found by the `hpack` fuzz target as a segmentation fault // inside `Allocator.dupe`, which is what reading a page the // allocator has already given back looks like. if (!name_owned) { name = try arena.dupe(u8, name); name_owned = true; } // Inserted whatever the budget says, because the peer has // inserted it too and the two tables must agree. try d.table_.insert(gpa, name, value); } try d.emit(arena, fields, name, value, name_owned and value_owned, &used, &over); saw_field = true; }
if (over) return error.HeaderListTooLarge;}
test decode { const gpa = std.testing.allocator; var scratch: [4096]u8 = undefined; var d: Decoder = .init(4096, &scratch, .{}); defer d.deinit(gpa);
var arena_state: std.heap.ArenaAllocator = .init(gpa); defer arena_state.deinit(); var fields: std.ArrayList(Field) = .empty;
// RFC 7541 C.3.1: three indexed fields and a literal `:authority` with // incremental indexing. const block = [_]u8{ 0x82, 0x86, 0x84, 0x41, 0x0f } ++ "www.example.com".*; try d.decode(gpa, arena_state.allocator(), &block, &fields);
try std.testing.expectEqual(@as(usize, 4), fields.items.len); try std.testing.expectEqualStrings(":method", fields.items[0].name); try std.testing.expectEqualStrings("GET", fields.items[0].value); try std.testing.expectEqualStrings("www.example.com", fields.items[3].value); // And the literal went into the dynamic table, as the peer's did. try std.testing.expectEqual(@as(u32, 57), d.table_.size);}
const Looked = struct { name: []const u8, value: []const u8, /// Whether the strings outlive this field section on their own. True only /// for the static table, whose strings are `.rodata`. owned: bool,};
fn lookup(d: *const Decoder, index: u32) CompressionError!Looked { if (index <= table.static.len) { const entry = table.static[index - 1]; return .{ .name = entry.name, .value = entry.value, .owned = true }; } const entry = d.table_.get(index) orelse return error.InvalidIndex; // Not `owned`: the dynamic table is a ring that evicts, and it can evict // during this very section. return .{ .name = entry.name, .value = entry.value, .owned = false };}
/// Reads a string literal and returns something that will outlive the section.////// An uncoded literal is a sub-slice of the section and a coded one is a/// prefix of `scratch`; neither survives, so both are copied. The copy is the/// contract stated at the top of `hpack.zig`.fn copyString(d: *Decoder, arena: Allocator, c: *Cursor, owned: *bool) Error![]const u8 { const raw = c.string(d.scratch) catch |err| switch (err) { error.Truncated => return error.Truncated, error.IntegerOverflow => return error.IntegerOverflow, error.PaddingTooLong => return error.PaddingTooLong, error.BadPadding => return error.BadPadding, error.EosInInput => return error.EosInInput, error.StringTooLong => return error.StringTooLong, }; owned.* = true; return arena.dupe(u8, raw);}
/// Adds a field to the list unless the section has already gone over budget.////// `already_safe` says the strings outlive the section without being copied,/// which is true only of static-table entries.fn emit( d: *Decoder, arena: Allocator, fields: *std.ArrayList(Field), name: []const u8, value: []const u8, already_safe: bool, used: *u64, over: *bool,) Error!void { used.* += name.len + value.len + table.entry_overhead; if (used.* > d.limits.max_header_list_size) { over.* = true; return; } if (over.*) return; const kept_name = if (already_safe) name else try arena.dupe(u8, name); const kept_value = if (already_safe) value else try arena.dupe(u8, value); try fields.append(arena, .{ .name = kept_name, .value = kept_value });}
test { std.testing.refAllDecls(@This());}