NAME

PAGI::Headers - ordered, case-insensitive, multi-value HTTP header container

DESCRIPTION

Holds HTTP headers as an ordered list of [name, value] byte pairs -- the PAGI wire form. Lookup is case-insensitive (ASCII fold; field names are ASCII tokens); original casing is preserved on output. Insertion order is preserved (never sorted). Multiple values per name are first-class (e.g. Set-Cookie).

Lookups scan the ordered list -- header sets are small, so this is deliberately indexless.

This container is not a hash and does not overload hash dereference; iterate names with names and read values with get/get_all, or take an explicit plain-hash snapshot with to_hash.

METHODS

to_hash

my $flat  = $headers->to_hash;     # { Name => last-value }
my $multi = $headers->to_hash(1);  # { Name => [ all values ] }

Returns a plain hashref snapshot keyed by distinct header name (grouped case-insensitively, using the casing and order names reports). The flat form mirrors get -- one value per name, last wins. Passing a true argument returns the multi-value form, mirroring get_all -- an arrayref of every value for each name. Values are not comma-joined (unlike HTTP::Headers/Mojo::Headers).

Header values are opaque bytes and pass through untouched -- including CR, LF, and NUL. This container does not validate or sanitize them; rejecting injection bytes on the wire is the server's job, which it MUST do when emitting a response (see "Response Start - send event" in PAGI::Spec::Www). A value must, however, be defined: add, set, and set_default croak on an undef value rather than storing it, since an undefined header value is a caller bug, not data.