blib/lib/PAGI/Headers.pm

filter: Statementstmt 100% 132 / 132 Branchbran 79.4% 27 / 34 Conditioncond 33.3% 1 / 3 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 100% 25 / 25 Podpod 5.2% 1 / 19 totaltotal 86.5% 186 / 215 CC 26 SCAR 10.4
CC
26
Cov
95%
has
5.2
add
4.0
dehop
4.0
CRAP 2.8
« 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
BranchTrueFalseTotal
if (defined $pairs) 62 188 250
68 62 ▶ croak("PAGI::Headers->new expects an arrayref of [name, value] pairs")
Branch: 1 branch
BranchTrueFalseTotal
unless ref $pairs eq "ARRAY" 0 62 62
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
BranchTrueFalseTotal
unless defined $name 1 159 160
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
BranchTrueFalseTotal
if _fold($p->[0]) eq $key 163 76 239
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
BranchTrueFalseTotal
unless defined $name 0 25 25
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
BranchTrueFalseTotal
unless defined $name and length $name 0 197 197
Condition33%1/3
defined $name and length $name
!ll&&!rl&&r
00197
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
ABresult
0X0
100
111
98 197 my $key = _fold($name);
99 197 ▶ for my $p (@{$self->{pairs}}) { return 1 if _fold($p->[0]) eq $key }
Branch: 1 branch
BranchTrueFalseTotal
if _fold($p->[0]) eq $key 100 59 159
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
BranchTrueFalseTotal
unless $seen{_fold($p->[0])}++ 12 6 18
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
BranchTrueFalseTotal
@{$_[0]{'pairs'};} ? : 1 2 3
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
BranchTrueFalseTotal
unless defined $name 0 46 46
120 46 ▶ croak("header value must be defined") if grep { !defined } @values;
Branch: 1 branch
BranchTrueFalseTotal
if grep {not defined $_;} @values 1 45 46
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
BranchTrueFalseTotal
unless defined $name 0 162 162
130 162 ▶ croak("header value must be defined") if grep { !defined } @values;
Branch: 1 branch
BranchTrueFalseTotal
if grep {not defined $_;} @values 2 160 162
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
BranchTrueFalseTotal
if $self->has($name) 12 84 96
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
BranchTrueFalseTotal
unless defined $name 0 5 5
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
BranchTrueFalseTotal
if length $tok 2 0 2
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
BranchTrueFalseTotal
if $multi 2 3 5
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;
« blib/lib/PAGI/Middleware/Session/State/Header.pm ↑ Summary blib/lib/PAGI/Middleware/Session/State/Callback.pm »