« blib/lib/PAGI/Middleware/Session/State/Header.pm
↑ Summary
blib/lib/PAGI/Middleware/Session/State/Callback.pm »
| 1 | package PAGI::Headers; | ||||||||||||||||||||||||||||
| 2 | 37 | $PAGI::Headers::VERSION = '0.002002'; | |||||||||||||||||||||||||||
| 3 | 37 | ▶ | use strict; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 4 | 37 | ▶ | use warnings; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 5 | 37 | ▶ | use Carp qw(croak); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 6 | |||||||||||||||||||||||||||||
| 7 | # Iterating @{$headers} yields the [name,value] pairs (the PAGI wire form), so | ||||||||||||||||||||||||||||
| 8 | # `@{$res->headers}` callers keep working. READ-ONLY: it returns a COPY, so | ||||||||||||||||||||||||||||
| 9 | # pushing onto it does not mutate the container -- use add(). Emission must use | ||||||||||||||||||||||||||||
| 10 | # to_pairs, never this overload. | ||||||||||||||||||||||||||||
| 11 | 37 | ▶ | use overload '@{}' => sub { $_[0]->to_pairs }, fallback => 1; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 12 | |||||||||||||||||||||||||||||
| 13 | =head1 NAME | ||||||||||||||||||||||||||||
| 14 | |||||||||||||||||||||||||||||
| 15 | PAGI::Headers - ordered, case-insensitive, multi-value HTTP header container | ||||||||||||||||||||||||||||
| 16 | |||||||||||||||||||||||||||||
| 17 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||
| 18 | |||||||||||||||||||||||||||||
| 19 | Holds HTTP headers as an ordered list of C<[name, value]> byte pairs -- the PAGI | ||||||||||||||||||||||||||||
| 20 | wire form. Lookup is case-insensitive (ASCII fold; field names are ASCII tokens); | ||||||||||||||||||||||||||||
| 21 | original casing is preserved on output. Insertion order is preserved (never | ||||||||||||||||||||||||||||
| 22 | sorted). Multiple values per name are first-class (e.g. C<Set-Cookie>). | ||||||||||||||||||||||||||||
| 23 | |||||||||||||||||||||||||||||
| 24 | Lookups scan the ordered list -- header sets are small, so this is deliberately | ||||||||||||||||||||||||||||
| 25 | indexless. | ||||||||||||||||||||||||||||
| 26 | |||||||||||||||||||||||||||||
| 27 | This container is B<not> a hash and does not overload hash dereference; iterate | ||||||||||||||||||||||||||||
| 28 | names with C<names> and read values with C<get>/C<get_all>, or take an explicit | ||||||||||||||||||||||||||||
| 29 | plain-hash snapshot with C<to_hash>. | ||||||||||||||||||||||||||||
| 30 | |||||||||||||||||||||||||||||
| 31 | =head1 METHODS | ||||||||||||||||||||||||||||
| 32 | |||||||||||||||||||||||||||||
| 33 | =head2 to_hash | ||||||||||||||||||||||||||||
| 34 | |||||||||||||||||||||||||||||
| 35 | my $flat = $headers->to_hash; # { Name => last-value } | ||||||||||||||||||||||||||||
| 36 | my $multi = $headers->to_hash(1); # { Name => [ all values ] } | ||||||||||||||||||||||||||||
| 37 | |||||||||||||||||||||||||||||
| 38 | Returns a plain hashref snapshot keyed by distinct header name (grouped | ||||||||||||||||||||||||||||
| 39 | case-insensitively, using the casing and order C<names> reports). The flat form | ||||||||||||||||||||||||||||
| 40 | mirrors C<get> -- one value per name, last wins. Passing a true argument returns | ||||||||||||||||||||||||||||
| 41 | the multi-value form, mirroring C<get_all> -- an arrayref of every value for each | ||||||||||||||||||||||||||||
| 42 | name. Values are B<not> comma-joined (unlike L<HTTP::Headers>/L<Mojo::Headers>). | ||||||||||||||||||||||||||||
| 43 | |||||||||||||||||||||||||||||
| 44 | Header values are opaque bytes and pass through untouched -- including C<CR>, | ||||||||||||||||||||||||||||
| 45 | C<LF>, and C<NUL>. This container does B<not> validate or sanitize them; rejecting | ||||||||||||||||||||||||||||
| 46 | injection bytes on the wire is the server's job, which it B<MUST> do when emitting | ||||||||||||||||||||||||||||
| 47 | a response (see L<PAGI::Spec::Www/"Response Start - send event">). A value must, | ||||||||||||||||||||||||||||
| 48 | however, be B<defined>: C<add>, C<set>, and C<set_default> C<croak> on an C<undef> | ||||||||||||||||||||||||||||
| 49 | value rather than storing it, since an undefined header value is a caller bug, not | ||||||||||||||||||||||||||||
| 50 | data. | ||||||||||||||||||||||||||||
| 51 | |||||||||||||||||||||||||||||
| 52 | =cut | ||||||||||||||||||||||||||||
| 53 | |||||||||||||||||||||||||||||
| 54 | # ASCII-only lowercase for name keying. Field names are ASCII tokens (RFC 7230); | ||||||||||||||||||||||||||||
| 55 | # Perl's lc() is Unicode-aware and could mis-fold stray bytes. | ||||||||||||||||||||||||||||
| 56 | 948 | ▶ | sub _fold { my $k = $_[0]; $k =~ tr/A-Z/a-z/; return $k } | ||||||||||||||||||||||||||
|
Subroutine
_fold: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 57 | |||||||||||||||||||||||||||||
| 58 | # Hop-by-hop headers (RFC 7230 ยง6.1) -- not safe to forward through a proxy. | ||||||||||||||||||||||||||||
| 59 | 37 | my %HOP = map { $_ => 1 } qw( | |||||||||||||||||||||||||||
| 60 | connection keep-alive proxy-authenticate proxy-authorization | ||||||||||||||||||||||||||||
| 61 | te trailer transfer-encoding upgrade | ||||||||||||||||||||||||||||
| 62 | ); | ||||||||||||||||||||||||||||
| 63 | |||||||||||||||||||||||||||||
| 64 | 250 | ▶ | sub new { | ||||||||||||||||||||||||||
|
Subroutine
new: called CC=3 SCAR=11.0
Pod
undocumented
| |||||||||||||||||||||||||||||
| 65 | 250 | my ($class, $pairs) = @_; | |||||||||||||||||||||||||||
| 66 | 250 | my @p; | |||||||||||||||||||||||||||
| 67 | 250 | ▶ | if (defined $pairs) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 68 | 62 | ▶ | croak("PAGI::Headers->new expects an arrayref of [name, value] pairs") | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 69 | unless ref($pairs) eq 'ARRAY'; | ||||||||||||||||||||||||||||
| 70 | 62 | @p = map { [ $_->[0], $_->[1] ] } @$pairs; | |||||||||||||||||||||||||||
| 71 | } | ||||||||||||||||||||||||||||
| 72 | 250 | return bless { pairs => \@p }, $class; | |||||||||||||||||||||||||||
| 73 | } | ||||||||||||||||||||||||||||
| 74 | |||||||||||||||||||||||||||||
| 75 | 5 | ▶ | sub clone { return PAGI::Headers->new($_[0]->{pairs}) } | ||||||||||||||||||||||||||
|
Subroutine
clone: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||
| 76 | |||||||||||||||||||||||||||||
| 77 | # --- reads (case-insensitive) --- | ||||||||||||||||||||||||||||
| 78 | |||||||||||||||||||||||||||||
| 79 | 160 | ▶ | sub get { | ||||||||||||||||||||||||||
|
Subroutine
get: called CC=4 SCAR=13.9
Pod
undocumented
| |||||||||||||||||||||||||||||
| 80 | 160 | my ($self, $name) = @_; | |||||||||||||||||||||||||||
| 81 | 160 | ▶ | croak("header name required") unless defined $name; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 82 | 159 | my $key = _fold($name); | |||||||||||||||||||||||||||
| 83 | 159 | my $val; | |||||||||||||||||||||||||||
| 84 | 159 | ▶ | for my $p (@{$self->{pairs}}) { $val = $p->[1] if _fold($p->[0]) eq $key } | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 85 | 159 | return $val; | |||||||||||||||||||||||||||
| 86 | } | ||||||||||||||||||||||||||||
| 87 | |||||||||||||||||||||||||||||
| 88 | 25 | ▶ | sub get_all { | ||||||||||||||||||||||||||
|
Subroutine
get_all: called CC=2 SCAR=7.0
Pod
undocumented
| |||||||||||||||||||||||||||||
| 89 | 25 | my ($self, $name) = @_; | |||||||||||||||||||||||||||
| 90 | 25 | ▶ | croak("header name required") unless defined $name; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 91 | 25 | my $key = _fold($name); | |||||||||||||||||||||||||||
| 92 | 25 | return map { $_->[1] } grep { _fold($_->[0]) eq $key } @{$self->{pairs}}; | |||||||||||||||||||||||||||
| 93 | } | ||||||||||||||||||||||||||||
| 94 | |||||||||||||||||||||||||||||
| 95 | 197 | ▶ | sub has { | ||||||||||||||||||||||||||
|
Subroutine
has: called CC=5 SCAR=16.6
Pod
undocumented
| |||||||||||||||||||||||||||||
| 96 | 197 | my ($self, $name) = @_; | |||||||||||||||||||||||||||
| 97 | 197 | ▶ | return 0 unless defined $name && length $name; | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
defined $name and length $name
MC/DC0%0/2
defined $name and length $name
defined $name
length $name
Truth table33%1/3
A and B
A= defined $nameB= length $name
| |||||||||||||||||||||||||||||
| 98 | 197 | my $key = _fold($name); | |||||||||||||||||||||||||||
| 99 | 197 | ▶ | for my $p (@{$self->{pairs}}) { return 1 if _fold($p->[0]) eq $key } | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 100 | 97 | return 0; | |||||||||||||||||||||||||||
| 101 | } | ||||||||||||||||||||||||||||
| 102 | |||||||||||||||||||||||||||||
| 103 | 9 | ▶ | sub names { | ||||||||||||||||||||||||||
|
Subroutine
names: called CC=3 SCAR=11.0
Pod
undocumented
| |||||||||||||||||||||||||||||
| 104 | 9 | my ($self) = @_; | |||||||||||||||||||||||||||
| 105 | 9 | my (%seen, @names); | |||||||||||||||||||||||||||
| 106 | 9 | for my $p (@{$self->{pairs}}) { | |||||||||||||||||||||||||||
| 107 | 18 | ▶ | push @names, $p->[0] unless $seen{ _fold($p->[0]) }++; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 108 | } | ||||||||||||||||||||||||||||
| 109 | 9 | return @names; | |||||||||||||||||||||||||||
| 110 | } | ||||||||||||||||||||||||||||
| 111 | |||||||||||||||||||||||||||||
| 112 | 4 | ▶ | sub count { scalar @{ $_[0]->{pairs} } } | ||||||||||||||||||||||||||
|
Subroutine
count: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||
| 113 | 3 | ▶ | sub is_empty { @{ $_[0]->{pairs} } ? 0 : 1 } | ||||||||||||||||||||||||||
|
Subroutine
is_empty: called CC=2 SCAR=6.9
Pod
undocumented
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 114 | |||||||||||||||||||||||||||||
| 115 | # --- writes (return $self) --- | ||||||||||||||||||||||||||||
| 116 | |||||||||||||||||||||||||||||
| 117 | 46 | ▶ | sub set { | ||||||||||||||||||||||||||
|
Subroutine
set: called CC=4 SCAR=13.9
Pod
undocumented
| |||||||||||||||||||||||||||||
| 118 | 46 | my ($self, $name, @values) = @_; | |||||||||||||||||||||||||||
| 119 | 46 | ▶ | croak("header name required") unless defined $name; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 120 | 46 | ▶ | croak("header value must be defined") if grep { !defined } @values; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 121 | 45 | my $key = _fold($name); | |||||||||||||||||||||||||||
| 122 | 45 | @{$self->{pairs}} = grep { _fold($_->[0]) ne $key } @{$self->{pairs}}; | |||||||||||||||||||||||||||
| 123 | 45 | push @{$self->{pairs}}, [ $name, $_ ] for @values; | |||||||||||||||||||||||||||
| 124 | 45 | return $self; | |||||||||||||||||||||||||||
| 125 | } | ||||||||||||||||||||||||||||
| 126 | |||||||||||||||||||||||||||||
| 127 | 162 | ▶ | sub add { | ||||||||||||||||||||||||||
|
Subroutine
add: called CC=4 SCAR=13.9
Pod
undocumented
| |||||||||||||||||||||||||||||
| 128 | 162 | my ($self, $name, @values) = @_; | |||||||||||||||||||||||||||
| 129 | 162 | ▶ | croak("header name required") unless defined $name; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 130 | 162 | ▶ | croak("header value must be defined") if grep { !defined } @values; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 131 | 160 | push @{$self->{pairs}}, [ $name, $_ ] for @values; | |||||||||||||||||||||||||||
| 132 | 160 | return $self; | |||||||||||||||||||||||||||
| 133 | } | ||||||||||||||||||||||||||||
| 134 | |||||||||||||||||||||||||||||
| 135 | 96 | ▶ | sub set_default { | ||||||||||||||||||||||||||
|
Subroutine
set_default: called CC=2 SCAR=6.9
Pod
undocumented
| |||||||||||||||||||||||||||||
| 136 | 96 | my ($self, $name, $value) = @_; | |||||||||||||||||||||||||||
| 137 | 96 | ▶ | return $self if $self->has($name); | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 138 | 84 | return $self->add($name, $value); | |||||||||||||||||||||||||||
| 139 | } | ||||||||||||||||||||||||||||
| 140 | |||||||||||||||||||||||||||||
| 141 | 5 | ▶ | sub remove { | ||||||||||||||||||||||||||
|
Subroutine
remove: called CC=2 SCAR=6.9
Pod
undocumented
| |||||||||||||||||||||||||||||
| 142 | 5 | my ($self, $name) = @_; | |||||||||||||||||||||||||||
| 143 | 5 | ▶ | croak("header name required") unless defined $name; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 144 | 5 | my $key = _fold($name); | |||||||||||||||||||||||||||
| 145 | 5 | my @removed = map { $_->[1] } grep { _fold($_->[0]) eq $key } @{$self->{pairs}}; | |||||||||||||||||||||||||||
| 146 | 5 | @{$self->{pairs}} = grep { _fold($_->[0]) ne $key } @{$self->{pairs}}; | |||||||||||||||||||||||||||
| 147 | 5 | return @removed; | |||||||||||||||||||||||||||
| 148 | } | ||||||||||||||||||||||||||||
| 149 | |||||||||||||||||||||||||||||
| 150 | 2 | ▶ | sub clear { @{ $_[0]->{pairs} } = (); return $_[0] } | ||||||||||||||||||||||||||
|
Subroutine
clear: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||
| 151 | |||||||||||||||||||||||||||||
| 152 | 1 | ▶ | sub remove_content_headers { | ||||||||||||||||||||||||||
|
Subroutine
remove_content_headers: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||
| 153 | 1 | my ($self) = @_; | |||||||||||||||||||||||||||
| 154 | 1 | my @removed = grep { _fold($_->[0]) =~ /^content-/ } @{$self->{pairs}}; | |||||||||||||||||||||||||||
| 155 | 1 | @{$self->{pairs}} = grep { _fold($_->[0]) !~ /^content-/ } @{$self->{pairs}}; | |||||||||||||||||||||||||||
| 156 | 1 | return PAGI::Headers->new(\@removed); | |||||||||||||||||||||||||||
| 157 | } | ||||||||||||||||||||||||||||
| 158 | |||||||||||||||||||||||||||||
| 159 | # Strip hop-by-hop headers: the fixed RFC 7230 set PLUS any field NAMED by the | ||||||||||||||||||||||||||||
| 160 | # Connection header (e.g. "Connection: X-Secret" makes X-Secret hop-by-hop). | ||||||||||||||||||||||||||||
| 161 | 1 | ▶ | sub dehop { | ||||||||||||||||||||||||||
|
Subroutine
dehop: called CC=4 SCAR=13.9
Pod
undocumented
| |||||||||||||||||||||||||||||
| 162 | 1 | my ($self) = @_; | |||||||||||||||||||||||||||
| 163 | 1 | my %drop = %HOP; | |||||||||||||||||||||||||||
| 164 | 1 | for my $conn ($self->get_all('connection')) { | |||||||||||||||||||||||||||
| 165 | 1 | for my $tok (split /,/, $conn) { | |||||||||||||||||||||||||||
| 166 | 2 | $tok =~ s/\A\s+//; $tok =~ s/\s+\z//; | |||||||||||||||||||||||||||
| 167 | 2 | ▶ | $drop{ _fold($tok) } = 1 if length $tok; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 168 | } | ||||||||||||||||||||||||||||
| 169 | } | ||||||||||||||||||||||||||||
| 170 | 1 | @{$self->{pairs}} = grep { !$drop{ _fold($_->[0]) } } @{$self->{pairs}}; | |||||||||||||||||||||||||||
| 171 | 1 | return $self; | |||||||||||||||||||||||||||
| 172 | } | ||||||||||||||||||||||||||||
| 173 | |||||||||||||||||||||||||||||
| 174 | # --- output --- | ||||||||||||||||||||||||||||
| 175 | |||||||||||||||||||||||||||||
| 176 | 151 | ▶ | sub to_pairs { return [ map { [ $_->[0], $_->[1] ] } @{ $_[0]->{pairs} } ] } | ||||||||||||||||||||||||||
|
Subroutine
to_pairs: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||
| 177 | 2 | ▶ | sub flatten { return map { @$_ } @{ $_[0]->{pairs} } } | ||||||||||||||||||||||||||
|
Subroutine
flatten: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||
| 178 | |||||||||||||||||||||||||||||
| 179 | # Plain-hash snapshot, keyed by distinct name (case-insensitively grouped, in | ||||||||||||||||||||||||||||
| 180 | # names() order/casing). Flat form mirrors get() -- one value per name, last | ||||||||||||||||||||||||||||
| 181 | # wins; multi form (truthy arg) mirrors get_all() -- an arrayref of every value. | ||||||||||||||||||||||||||||
| 182 | # This is the explicit "I want a hash" path; the container itself is NOT a hash. | ||||||||||||||||||||||||||||
| 183 | 5 | ▶ | sub to_hash { | ||||||||||||||||||||||||||
|
Subroutine
to_hash: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||
| 184 | 5 | my ($self, $multi) = @_; | |||||||||||||||||||||||||||
| 185 | 5 | ▶ | return { map { $_ => [ $self->get_all($_) ] } $self->names } if $multi; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 186 | 3 | return { map { $_ => $self->get($_) } $self->names }; | |||||||||||||||||||||||||||
| 187 | } | ||||||||||||||||||||||||||||
| 188 | |||||||||||||||||||||||||||||
| 189 | # Debug/inspection only -- NOT a wire-emission helper. It does not validate or | ||||||||||||||||||||||||||||
| 190 | # strip CR/LF, so it is unsafe for untrusted header values; wire safety is the | ||||||||||||||||||||||||||||
| 191 | # server's job (it validates http.response.start). The real output is to_pairs. | ||||||||||||||||||||||||||||
| 192 | 3 | ▶ | sub to_string { return join('', map { "$_->[0]: $_->[1]\r\n" } @{ $_[0]->{pairs} }) } | ||||||||||||||||||||||||||
|
Subroutine
to_string: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||
| 193 | |||||||||||||||||||||||||||||
| 194 | 37 | 1; | |||||||||||||||||||||||||||