// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // 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, }; } pub fn init(header_table_size: u32, scratch: []u8, limits: Limits) Decoder { return .{ .table_ = .init(header_table_size), .scratch = scratch, .limits = limits, }; } pub fn deinit(d: *Decoder, gpa: Allocator) void { d.table_.deinit(gpa); d.* = undefined; } /// 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); } /// Appends the decoded fields to `fields`, copying every name and value into /// `arena` — with the one exception described at the top of `hpack.zig`. /// /// `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. 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; } 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()); }