Response.pm

filter: Statementstmt 99.4% 176 / 177 Branchbran 95.3% 82 / 86 Conditioncond 96.7% 60 / 62 MC/DCmcdc 91.4% 32 / 35 Subroutinesub 100% 28 / 28 Podpod 100% 24 / 24 totaltotal 97.5% 402 / 412 CC 70 SCAR 22.8
CC
70
Cov
98%
freshness_lifetime
18.0
filename
17.0
parse
11.1
CRAP 9.8
« Config.pm ↑ Summary Headers.pm »
1 package HTTP::Response;
2  
3 12 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 12 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 12 our $VERSION = '7.04';
7  
8 12 ▶use parent 'HTTP::Message';
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 12 ▶use HTTP::Status ();
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12  
13 sub new
14 24 ▶{
Subroutine new: called CC=1 SCAR=0.0
Pod documented
15 24 my($class, $rc, $msg, $header, $content) = @_;
16 24 my $self = $class->SUPER::new($header, $content);
17 24 $self->code($rc);
18 24 $self->message($msg);
19 24 $self;
20 }
21  
22  
23 sub parse
24 13 ▶{
Subroutine parse: called CC=11 SCAR=24.0
Pod documented
25 13 my($class, $str) = @_;
26 13 ▶ Carp::carp('Undefined argument to parse()') if $^W && ! defined $str;
Branch: 1 branch
BranchTrueFalseTotal
if $^W and not defined $str 1 12 13
Condition100%3/3
$^W and not defined $str
!ll&&!rl&&r
1111
MC/DC100%2/2
$^W and not defined $str
$^W not defined $str
Truth table100%3/3
A and not(B)
A= $^WB= not defined $str
ABresult
0X0
100
111
27 13 my $status_line;
28 13 ▶ if (defined $str && $str =~ s/^(.*)\n//) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $str and $str =~ s/^(.*)\n//) { } 11 2 13
Condition66%2/3
defined $str and $str =~ s/^(.*)\n//
!ll&&!rl&&r
2011
MC/DC50%1/2
defined $str and $str =~ s/^(.*)\n//
defined $str $str =~ s/^(.*)\n//
Truth table66%2/3
A and B
A= defined $strB= $str =~ s/^(.*)\n//
ABresult
0X0
100
111
29 11 $status_line = $1;
30 }
31 else {
32 2 $status_line = $str;
33 2 $str = "";
34 }
35  
36 13 ▶ $status_line =~ s/\r\z// if defined $status_line;
Branch: 1 branch
BranchTrueFalseTotal
if defined $status_line 11 2 13
37  
38 13 my $self = $class->SUPER::parse($str);
39 13 ▶ if (defined $status_line) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $status_line) 11 2 13
40 11 my($protocol, $code, $message);
41 11 ▶ if ($status_line =~ /^\d{3} /) {
Branch: 1 branch
BranchTrueFalseTotal
if ($status_line =~ /^\d{3} /) { } 9 2 11
42 # Looks like a response created by HTTP::Response->new
43 9 ($code, $message) = split(' ', $status_line, 2);
44 } else {
45 2 ($protocol, $code, $message) = split(' ', $status_line, 3);
46 }
47 11 ▶ $self->protocol($protocol) if $protocol;
Branch: 1 branch
BranchTrueFalseTotal
if $protocol 2 9 11
48 11 ▶ $self->code($code) if defined($code);
Branch: 1 branch
BranchTrueFalseTotal
if defined $code 11 0 11
49 11 ▶ $self->message($message) if defined($message);
Branch: 1 branch
BranchTrueFalseTotal
if defined $message 11 0 11
50 }
51 13 $self;
52 }
53  
54  
55 sub clone
56 2 ▶{
Subroutine clone: called CC=2 SCAR=6.9
Pod documented
57 2 my $self = shift;
58 2 my $clone = bless $self->SUPER::clone, ref($self);
59 2 $clone->code($self->code);
60 2 $clone->message($self->message);
61 2 ▶ $clone->request($self->request->clone) if $self->request;
Branch: 1 branch
BranchTrueFalseTotal
if $self->request 1 1 2
62 # we don't clone previous
63 2 $clone;
64 }
65  
66  
67 46 ▶sub code { shift->_elem('_rc', @_); }
Subroutine code: called CC=1 SCAR=0.0
Pod documented
68 44 ▶sub message { shift->_elem('_msg', @_); }
Subroutine message: called CC=1 SCAR=0.0
Pod documented
69 12 ▶sub previous { shift->_elem('_previous',@_); }
Subroutine previous: called CC=1 SCAR=0.0
Pod documented
70 39 ▶sub request { shift->_elem('_request', @_); }
Subroutine request: called CC=1 SCAR=0.0
Pod documented
71  
72  
73 sub status_line
74 19 ▶{
Subroutine status_line: called CC=4 SCAR=13.9
Pod documented
75 19 my $self = shift;
76 19 ▶ my $code = $self->{'_rc'} || "000";
Condition100%2/2
$self->{'_rc'} || '000'
l!l
127
MC/DC100%1/1
$self->{'_rc'} || '000'
$self->{'_rc'}
Truth table100%2/2
A
A= $self->{'_rc'}
Aresult
11
00
77 19 ▶ my $mess = $self->{'_msg'} || HTTP::Status::status_message($code) || "Unknown code";
Condition100%5/5
$self->{'_msg'} || &HTTP::Status::status_message($code) || 'Unknown code'
l!l
127
$self->{"_msg"} or &HTTP::Status::status_message($code)
l!l&&r!l&&!r
757
MC/DC100%2/2
$self->{'_msg'} || &HTTP::Status::status_message($code) || 'Unknown code'
$self->{"_msg"} &HTTP::Status::status_message($code)
Truth table100%3/3
A or B
A= $self->{"_msg"}B= &HTTP::Status::status_message($code)
ABresult
1X1
011
000
78 19 return "$code $mess";
79 }
80  
81  
82 sub base
83 7 ▶{
Subroutine base: called CC=4 SCAR=13.9
Pod documented
84 7 my $self = shift;
85 7 my $base = (
86 $self->header('Content-Base'), # used to be HTTP/1.1
87 $self->header('Base'), # HTTP/1.0
88 )[0];
89 7 ▶ if ($base && $base =~ /^$URI::scheme_re:/o) {
Branch: 1 branch
BranchTrueFalseTotal
if ($base and $base =~ /^$URI::scheme_re:/o) 1 6 7
Condition100%3/3
$base and $base =~ /^$URI::scheme_re:/o
!ll&&!rl&&r
421
MC/DC100%2/2
$base and $base =~ /^$URI::scheme_re:/o
$base $base =~ /^$URI::scheme_re:/o
Truth table100%3/3
A and B
A= $baseB= $base =~ /^$URI::scheme_re:/o
ABresult
0X0
100
111
90 # already absolute
91 1 return $HTTP::URI_CLASS->new($base);
92 }
93  
94 6 my $req = $self->request;
95 6 ▶ if ($req) {
Branch: 1 branch
BranchTrueFalseTotal
if ($req) 5 1 6
96 # if $base is undef here, the return value is effectively
97 # just a copy of $self->request->uri.
98 5 return $HTTP::URI_CLASS->new_abs($base, $req->uri);
99 }
100  
101 # can't find an absolute base
102 1 return undef;
103 }
104  
105  
106 4 ▶sub redirects {
Subroutine redirects: called CC=3 SCAR=11.0
Pod documented
107 4 my $self = shift;
108 4 my @r;
109 4 my $r = $self;
110 4 ▶ while (my $p = $r->previous) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $p = $r->previous) 5 4 9
111 5 push(@r, $p);
112 5 $r = $p;
113 }
114 4 ▶ return @r unless wantarray;
Branch: 1 branch
BranchTrueFalseTotal
unless wantarray 3 1 4
115 1 return reverse @r;
116 }
117  
118  
119 sub filename
120 10 ▶{
Subroutine filename: called CC=17 SCAR=28.4
Pod documented
121 10 my $self = shift;
122 10 my $file;
123  
124 10 my $cd = $self->header('Content-Disposition');
125 10 ▶ if ($cd) {
Branch: 1 branch
BranchTrueFalseTotal
if ($cd) 7 3 10
126 7 require HTTP::Headers::Util;
127 7 ▶ if (my @cd = HTTP::Headers::Util::split_header_words($cd)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my(@cd) = HTTP::Headers::Util::split_header_words($cd)) 7 0 7
128 7 my ($disposition, undef, %cd_param) = @{$cd[-1]};
129 7 $file = $cd_param{filename};
130  
131 # RFC 2047 encoded?
132 7 ▶ if ($file && $file =~ /^=\?(.+?)\?(.+?)\?(.+)\?=$/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($file and $file =~ /^=\?(.+?)\?(.+?)\?(.+)\?=$/) 4 3 7
Condition100%3/3
$file and $file =~ /^=\?(.+?)\?(.+?)\?(.+)\?=$/
!ll&&!rl&&r
214
MC/DC100%2/2
$file and $file =~ /^=\?(.+?)\?(.+?)\?(.+)\?=$/
$file $file =~ /^=\?(.+?)\?(.+?)\?(.+)\?=$/
Truth table100%3/3
A and B
A= $fileB= $file =~ /^=\?(.+?)\?(.+?)\?(.+)\?=$/
ABresult
0X0
100
111
133 4 my $charset = $1;
134 4 my $encoding = uc($2);
135 4 my $encfile = $3;
136  
137 4 ▶ if ($encoding eq 'Q' || $encoding eq 'B') {
Branch: 1 branch
BranchTrueFalseTotal
if ($encoding eq "Q" or $encoding eq "B") 3 1 4
Condition100%3/3
$encoding eq "Q" or $encoding eq "B"
l!l&&r!l&&!r
121
MC/DC100%2/2
$encoding eq "Q" or $encoding eq "B"
$encoding eq "Q" $encoding eq "B"
Truth table100%3/3
A or B
A= $encoding eq "Q"B= $encoding eq "B"
ABresult
1X1
011
000
138 3 local($SIG{__DIE__});
139 3 eval {
140 3 ▶ if ($encoding eq 'Q') {
Branch: 1 branch
BranchTrueFalseTotal
if ($encoding eq 'Q') { } 1 2 3
141 1 $encfile =~ s/_/ /g;
142 1 require MIME::QuotedPrint;
143 1 $encfile = MIME::QuotedPrint::decode($encfile);
144 }
145 else { # $encoding eq 'B'
146 2 require MIME::Base64;
147 2 $encfile = MIME::Base64::decode($encfile);
148 }
149  
150 3 require Encode;
151 3 require Encode::Locale;
152 3 Encode::from_to($encfile, $charset, "locale_fs");
153 };
154  
155 3 ▶ $file = $encfile unless $@;
Branch: 1 branch
BranchTrueFalseTotal
unless $@ 2 1 3
156 }
157 }
158 }
159 }
160  
161 10 ▶ unless (defined($file) && length($file)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $file and length $file) 5 5 10
Condition100%3/3
defined $file and length $file
!ll&&!rl&&r
415
MC/DC100%2/2
defined $file and length $file
defined $file length $file
Truth table100%3/3
A and B
A= defined $fileB= length $file
ABresult
0X0
100
111
162 5 my $uri;
163 5 ▶ if (my $cl = $self->header('Content-Location')) {
Branch: 2 branches
BranchTrueFalseTotal
if (my $cl = $self->header('Content-Location')) { } 1 4 5
elsif (my $request = $self->request) { } 3 1 4
164 1 $uri = URI->new($cl);
165 }
166 elsif (my $request = $self->request) {
167 3 $uri = $request->uri;
168 }
169  
170 5 ▶ if ($uri) {
Branch: 1 branch
BranchTrueFalseTotal
if ($uri) 2 3 5
171 2 $file = ($uri->path_segments)[-1];
172 }
173 }
174  
175 10 ▶ if ($file) {
Branch: 1 branch
BranchTrueFalseTotal
if ($file) 7 3 10
176 7 $file =~ s,.*[\\/],,; # basename
177 }
178  
179 10 ▶ if ($file && !length($file)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($file and not length $file) 0 10 10
Condition66%2/3
$file and not length $file
!ll&&!rl&&r
370
MC/DC0%0/2
$file and not length $file
$file not length $file
Truth table66%2/3
A and not(B)
A= $fileB= not length $file
ABresult
0X0
100
111
180 0 $file = undef;
181 }
182  
183 10 $file;
184 }
185  
186  
187 sub as_string
188 15 ▶{
Subroutine as_string: called CC=3 SCAR=11.0
Pod documented
189 15 my $self = shift;
190 15 my($eol) = @_;
191 15 ▶ $eol = "\n" unless defined $eol;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $eol 12 3 15
192  
193 15 my $status_line = $self->status_line;
194 15 my $proto = $self->protocol;
195 15 ▶ $status_line = "$proto $status_line" if $proto;
Branch: 1 branch
BranchTrueFalseTotal
if $proto 1 14 15
196  
197 15 return join($eol, $status_line, $self->SUPER::as_string($eol));
198 }
199  
200  
201 sub dump
202 2 ▶{
Subroutine dump: called CC=2 SCAR=6.9
Pod documented
203 2 my $self = shift;
204  
205 2 my $status_line = $self->status_line;
206 2 my $proto = $self->protocol;
207 2 ▶ $status_line = "$proto $status_line" if $proto;
Branch: 1 branch
BranchTrueFalseTotal
if $proto 1 1 2
208  
209 2 return $self->SUPER::dump(
210 preheader => $status_line,
211 @_,
212 );
213 }
214  
215  
216 1 ▶sub is_info { HTTP::Status::is_info (shift->{'_rc'}); }
Subroutine is_info: called CC=1 SCAR=0.0
Pod documented
217 4 ▶sub is_success { HTTP::Status::is_success (shift->{'_rc'}); }
Subroutine is_success: called CC=1 SCAR=0.0
Pod documented
218 1 ▶sub is_redirect { HTTP::Status::is_redirect (shift->{'_rc'}); }
Subroutine is_redirect: called CC=1 SCAR=0.0
Pod documented
219 1 ▶sub is_error { HTTP::Status::is_error (shift->{'_rc'}); }
Subroutine is_error: called CC=1 SCAR=0.0
Pod documented
220 1 ▶sub is_client_error { HTTP::Status::is_client_error (shift->{'_rc'}); }
Subroutine is_client_error: called CC=1 SCAR=0.0
Pod documented
221 1 ▶sub is_server_error { HTTP::Status::is_server_error (shift->{'_rc'}); }
Subroutine is_server_error: called CC=1 SCAR=0.0
Pod documented
222  
223  
224 sub error_as_HTML
225 1 ▶{
Subroutine error_as_HTML: called CC=1 SCAR=0.0
Pod documented
226 1 my $self = shift;
227 1 my $title = 'An Error Occurred';
228 1 my $body = $self->status_line;
229 1 $body =~ s/&/&/g;
230 1 $body =~ s/</&lt;/g;
231 1 return <<EOM;
232 <html>
233 <head><title>$title</title></head>
234 <body>
235 <h1>$title</h1>
236 <p>$body</p>
237 </body>
238 </html>
239 EOM
240 }
241  
242  
243 sub current_age
244 13 ▶{
Subroutine current_age: called CC=11 SCAR=24.0
Pod documented
245 13 my $self = shift;
246 13 my $time = shift;
247  
248 # Implementation of RFC 2616 section 13.2.3
249 # (age calculations)
250 13 my $response_time = $self->client_date;
251 13 my $date = $self->date;
252  
253 13 my $age = 0;
254 13 ▶ if ($response_time && $date) {
Branch: 1 branch
BranchTrueFalseTotal
if ($response_time and $date) 9 4 13
Condition100%3/3
$response_time and $date
!ll&&!rl&&r
319
MC/DC100%2/2
$response_time and $date
$response_time $date
Truth table100%3/3
A and B
A= $response_timeB= $date
ABresult
0X0
100
111
255 9 $age = $response_time - $date; # apparent_age
256 9 ▶ $age = 0 if $age < 0;
Branch: 1 branch
BranchTrueFalseTotal
if $age < 0 3 6 9
257 }
258  
259 13 my $age_v = $self->header('Age');
260 13 ▶ if ($age_v && $age_v > $age) {
Branch: 1 branch
BranchTrueFalseTotal
if ($age_v and $age_v > $age) 4 9 13
Condition100%3/3
$age_v and $age_v > $age
!ll&&!rl&&r
634
MC/DC100%2/2
$age_v and $age_v > $age
$age_v $age_v > $age
Truth table100%3/3
A and B
A= $age_vB= $age_v > $age
ABresult
0X0
100
111
261 4 $age = $age_v; # corrected_received_age
262 }
263  
264 13 ▶ if ($response_time) {
Branch: 1 branch
BranchTrueFalseTotal
if ($response_time) 10 3 13
265 10 my $request = $self->request;
266 10 ▶ if ($request) {
Branch: 1 branch
BranchTrueFalseTotal
if ($request) 8 2 10
267 8 my $request_time = $request->date;
268 8 ▶ if ($request_time && $request_time < $response_time) {
Branch: 1 branch
BranchTrueFalseTotal
if ($request_time and $request_time < $response_time) 6 2 8
Condition100%3/3
$request_time and $request_time < $response_time
!ll&&!rl&&r
116
MC/DC100%2/2
$request_time and $request_time < $response_time
$request_time $request_time < $response_time
Truth table100%3/3
A and B
A= $request_timeB= $request_time < $response_time
ABresult
0X0
100
111
269 # Add response_delay to age to get 'corrected_initial_age'
270 6 $age += $response_time - $request_time;
271 }
272 }
273 10 ▶ $age += ($time || time) - $response_time;
Condition100%2/2
$time || time
l!l
46
MC/DC100%1/1
$time || time
$time
Truth table100%2/2
A
A= $time
Aresult
11
00
274 }
275 13 return $age;
276 }
277  
278  
279 sub freshness_lifetime
280 24 ▶{
Subroutine freshness_lifetime: called CC=18 SCAR=28.9
Pod documented
281 24 my($self, %opt) = @_;
282  
283 # First look for the Cache-Control: max-age=n header
284 24 for my $cc ($self->header('Cache-Control')) {
285 6 for my $cc_dir (split(/\s*,\s*/, $cc)) {
286 6 ▶ return $1 if $cc_dir =~ /^max-age\s*=\s*(\d+)/i;
Branch: 1 branch
BranchTrueFalseTotal
if $cc_dir =~ /^max-age\s*=\s*(\d+)/i 3 3 6
287 }
288 }
289  
290 # Next possibility is to look at the "Expires" header
291 21 ▶ my $date = $self->date || $self->client_date || $opt{time} || time;
Condition100%8/8
$self->date || $self->client_date || $opt{'time'} || time
l!l
129
$self->date or $self->client_date or $opt{"time"}
l!l&&r!l&&!r
939
$self->date or $self->client_date
l!l&&r!l&&!r
8112
MC/DC100%3/3
$self->date || $self->client_date || $opt{'time'} || time
$self->date $self->client_date $opt{"time"}
Truth table100%4/4
A or B or C
A= $self->dateB= $self->client_dateC= $opt{"time"}
ABCresult
1XX1
01X1
0011
0000
292 21 ▶ if (my $expires = $self->expires) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $expires = $self->expires) 1 20 21
293 1 return $expires - $date;
294 }
295  
296 # Must apply heuristic expiration
297 20 ▶ return undef if exists $opt{heuristic_expiry} && !$opt{heuristic_expiry};
Branch: 1 branch
BranchTrueFalseTotal
if exists $opt{"heuristic_expiry"} and not $opt{"heuristic_expiry"} 4 16 20
Condition100%3/3
exists $opt{"heuristic_expiry"} and not $opt{"heuristic_expiry"}
!ll&&!rl&&r
1514
MC/DC100%2/2
exists $opt{"heuristic_expiry"} and not $opt{"heuristic_expiry"}
exists $opt{"heuristic_expiry"} not $opt{"heuristic_expiry"}
Truth table100%3/3
A and not(B)
A= exists $opt{"heuristic_expiry"}B= not $opt{"heuristic_expiry"}
ABresult
0X0
100
111
298  
299 # Default heuristic expiration parameters
300 16 ▶ $opt{h_min} ||= 60;
Condition100%2/2
$opt{"h_min"} ||= 60
l!l
214
MC/DC100%1/1
$opt{"h_min"} ||= 60
$opt{"h_min"}
Truth table100%2/2
A
A= $opt{"h_min"}
Aresult
11
00
301 16 ▶ $opt{h_max} ||= 24 * 3600;
Condition100%2/2
$opt{"h_max"} ||= 86400
l!l
115
MC/DC100%1/1
$opt{"h_max"} ||= 86400
$opt{"h_max"}
Truth table100%2/2
A
A= $opt{"h_max"}
Aresult
11
00
302 16 ▶ $opt{h_lastmod_fraction} ||= 0.10; # 10% since last-mod suggested by RFC2616
Condition100%2/2
$opt{"h_lastmod_fraction"} ||= "0.1"
l!l
115
MC/DC100%1/1
$opt{"h_lastmod_fraction"} ||= "0.1"
$opt{"h_lastmod_fraction"}
Truth table100%2/2
A
A= $opt{"h_lastmod_fraction"}
Aresult
11
00
303 16 ▶ $opt{h_default} ||= 3600;
Condition100%2/2
$opt{"h_default"} ||= 3600
l!l
115
MC/DC100%1/1
$opt{"h_default"} ||= 3600
$opt{"h_default"}
Truth table100%2/2
A
A= $opt{"h_default"}
Aresult
11
00
304  
305 # Should give a warning if more than 24 hours according to
306 # RFC 2616 section 13.2.4. Here we just make this the default
307 # maximum value.
308  
309 16 ▶ if (my $last_modified = $self->last_modified) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $last_modified = $self->last_modified) 12 4 16
310 12 my $h_exp = ($date - $last_modified) * $opt{h_lastmod_fraction};
311 12 ▶ return $opt{h_min} if $h_exp < $opt{h_min};
Branch: 1 branch
BranchTrueFalseTotal
if $h_exp < $opt{"h_min"} 2 10 12
312 10 ▶ return $opt{h_max} if $h_exp > $opt{h_max};
Branch: 1 branch
BranchTrueFalseTotal
if $h_exp > $opt{"h_max"} 8 2 10
313 2 return $h_exp;
314 }
315  
316 # default when all else fails
317 4 ▶ return $opt{h_min} if $opt{h_min} > $opt{h_default};
Branch: 1 branch
BranchTrueFalseTotal
if $opt{"h_min"} > $opt{"h_default"} 1 3 4
318 3 return $opt{h_default};
319 }
320  
321  
322 sub is_fresh
323 3 ▶{
Subroutine is_fresh: called CC=3 SCAR=11.0
Pod documented
324 3 my($self, %opt) = @_;
325 3 ▶ $opt{time} ||= time;
Condition100%2/2
$opt{"time"} ||= time
l!l
12
MC/DC100%1/1
$opt{"time"} ||= time
$opt{"time"}
Truth table100%2/2
A
A= $opt{"time"}
Aresult
11
00
326 3 my $f = $self->freshness_lifetime(%opt);
327 3 ▶ return undef unless defined($f);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $f 1 2 3
328 2 return $f > $self->current_age($opt{time});
329 }
330  
331  
332 sub fresh_until
333 5 ▶{
Subroutine fresh_until: called CC=3 SCAR=11.0
Pod documented
334 5 my($self, %opt) = @_;
335 5 ▶ $opt{time} ||= time;
Condition100%2/2
$opt{"time"} ||= time
l!l
14
MC/DC100%1/1
$opt{"time"} ||= time
$opt{"time"}
Truth table100%2/2
A
A= $opt{"time"}
Aresult
11
00
336 5 my $f = $self->freshness_lifetime(%opt);
337 5 ▶ return undef unless defined($f);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $f 1 4 5
338 4 return $f - $self->current_age($opt{time}) + $opt{time};
339 }
340  
341 12 1;
342  
343 =pod
344  
345 =encoding UTF-8
346  
347 =head1 NAME
348  
349 HTTP::Response - HTTP style response message
350  
351 =head1 VERSION
352  
353 version 7.04
354  
355 =head1 SYNOPSIS
356  
357 Response objects are returned by the request() method of the C<LWP::UserAgent>:
358  
359 # ...
360 $response = $ua->request($request);
361 if ($response->is_success) {
362 print $response->decoded_content;
363 }
364 else {
365 print STDERR $response->status_line, "\n";
366 }
367  
368 =head1 DESCRIPTION
369  
370 The C<HTTP::Response> class encapsulates HTTP style responses. A
371 response consists of a response line, some headers, and a content
372 body. Note that the LWP library uses HTTP style responses even for
373 non-HTTP protocol schemes. Instances of this class are usually
374 created and returned by the request() method of an C<LWP::UserAgent>
375 object.
376  
377 C<HTTP::Response> is a subclass of C<HTTP::Message> and therefore
378 inherits its methods. The following additional methods are available:
379  
380 =over 4
381  
382 =item $r = HTTP::Response->new( $code )
383  
384 =item $r = HTTP::Response->new( $code, $msg )
385  
386 =item $r = HTTP::Response->new( $code, $msg, $header )
387  
388 =item $r = HTTP::Response->new( $code, $msg, $header, $content )
389  
390 Constructs a new C<HTTP::Response> object describing a response with
391 response code $code and optional message $msg. The optional $header
392 argument should be a reference to an C<HTTP::Headers> object or a
393 plain array reference of key/value pairs. The optional $content
394 argument should be a string of bytes. The meanings of these arguments are
395 described below.
396  
397 =item $r = HTTP::Response->parse( $str )
398  
399 This constructs a new response object by parsing the given string.
400  
401 =item $r->code
402  
403 =item $r->code( $code )
404  
405 This is used to get/set the code attribute. The code is a 3 digit
406 number that encode the overall outcome of an HTTP response. The
407 C<HTTP::Status> module provide constants that provide mnemonic names
408 for the code attribute.
409  
410 =item $r->message
411  
412 =item $r->message( $message )
413  
414 This is used to get/set the message attribute. The message is a short
415 human readable single line string that explains the response code.
416  
417 =item $r->header( $field )
418  
419 =item $r->header( $field => $value )
420  
421 This is used to get/set header values and it is inherited from
422 C<HTTP::Headers> via C<HTTP::Message>. See L<HTTP::Headers> for
423 details and other similar methods that can be used to access the
424 headers.
425  
426 =item $r->content
427  
428 =item $r->content( $bytes )
429  
430 This is used to get/set the raw content and it is inherited from the
431 C<HTTP::Message> base class. See L<HTTP::Message> for details and
432 other methods that can be used to access the content.
433  
434 =item $r->decoded_content( %options )
435  
436 This will return the content after any C<Content-Encoding> and
437 charsets have been decoded. See L<HTTP::Message> for details.
438  
439 =item $r->request
440  
441 =item $r->request( $request )
442  
443 This is used to get/set the request attribute. The request attribute
444 is a reference to the request that caused this response. It does
445 not have to be the same request passed to the $ua->request() method,
446 because there might have been redirects and authorization retries in
447 between.
448  
449 =item $r->previous
450  
451 =item $r->previous( $response )
452  
453 This is used to get/set the previous attribute. The previous
454 attribute is used to link together chains of responses. You get
455 chains of responses if the first response is redirect or unauthorized.
456 The value is C<undef> if this is the first response in a chain.
457  
458 Note that the method $r->redirects is provided as a more convenient
459 way to access the response chain.
460  
461 =item $r->status_line
462  
463 Returns the string "E<lt>code> E<lt>message>". If the message attribute
464 is not set then the official name of E<lt>code> (see L<HTTP::Status>)
465 is substituted.
466  
467 =item $r->base
468  
469 Returns the base URI for this response. The return value will be a
470 reference to a URI object.
471  
472 The base URI is obtained from one the following sources (in priority
473 order):
474  
475 =over 4
476  
477 =item 1.
478  
479 Embedded in the document content, for instance <BASE HREF="...">
480 in HTML documents.
481  
482 =item 2.
483  
484 A "Content-Base:" header in the response.
485  
486 For backwards compatibility with older HTTP implementations we will
487 also look for the "Base:" header.
488  
489 =item 3.
490  
491 The URI used to request this response. This might not be the original
492 URI that was passed to $ua->request() method, because we might have
493 received some redirect responses first.
494  
495 =back
496  
497 If none of these sources provide an absolute URI, undef is returned.
498  
499 B<Note>: previous versions of HTTP::Response would also consider
500 a "Content-Location:" header,
501 as L<RFC 2616|https://www.rfc-editor.org/rfc/rfc2616> said it should be.
502 But this was never widely implemented by browsers,
503 and now L<RFC 7231|https://www.rfc-editor.org/rfc/rfc7231>
504 says it should no longer be considered.
505  
506 When the LWP protocol modules produce the HTTP::Response object, then any base
507 URI embedded in the document (step 1) will already have initialized the
508 "Content-Base:" header. (See L<LWP::UserAgent/parse_head>). This means that
509 this method only performs the last 2 steps (the content is not always available
510 either).
511  
512 =item $r->filename
513  
514 Returns a filename for this response. Note that doing sanity checks
515 on the returned filename (eg. removing characters that cannot be used
516 on the target filesystem where the filename would be used, and
517 laundering it for security purposes) are the caller's responsibility;
518 the only related thing done by this method is that it makes a simple
519 attempt to return a plain filename with no preceding path segments.
520  
521 The filename is obtained from one the following sources (in priority
522 order):
523  
524 =over 4
525  
526 =item 1.
527  
528 A "Content-Disposition:" header in the response. Proper decoding of
529 RFC 2047 encoded filenames requires the C<MIME::QuotedPrint> (for "Q"
530 encoding), C<MIME::Base64> (for "B" encoding), and C<Encode> modules.
531  
532 =item 2.
533  
534 A "Content-Location:" header in the response.
535  
536 =item 3.
537  
538 The URI used to request this response. This might not be the original
539 URI that was passed to $ua->request() method, because we might have
540 received some redirect responses first.
541  
542 =back
543  
544 If a filename cannot be derived from any of these sources, undef is
545 returned.
546  
547 =item $r->as_string
548  
549 =item $r->as_string( $eol )
550  
551 Returns a textual representation of the response.
552  
553 =item $r->is_info
554  
555 =item $r->is_success
556  
557 =item $r->is_redirect
558  
559 =item $r->is_error
560  
561 =item $r->is_client_error
562  
563 =item $r->is_server_error
564  
565 These methods indicate if the response was informational, successful, a
566 redirection, or an error. See L<HTTP::Status> for the meaning of these.
567  
568 =item $r->error_as_HTML
569  
570 Returns a string containing a complete HTML document indicating what
571 error occurred. This method should only be called when $r->is_error
572 is TRUE.
573  
574 =item $r->redirects
575  
576 Returns the list of redirect responses that lead up to this response
577 by following the $r->previous chain. The list order is oldest first.
578  
579 In scalar context return the number of redirect responses leading up
580 to this one.
581  
582 =item $r->current_age
583  
584 Calculates the "current age" of the response as specified by RFC 2616
585 section 13.2.3. The age of a response is the time since it was sent
586 by the origin server. The returned value is a number representing the
587 age in seconds.
588  
589 =item $r->freshness_lifetime( %opt )
590  
591 Calculates the "freshness lifetime" of the response as specified by
592 RFC 2616 section 13.2.4. The "freshness lifetime" is the length of
593 time between the generation of a response and its expiration time.
594 The returned value is the number of seconds until expiry.
595  
596 If the response does not contain an "Expires" or a "Cache-Control"
597 header, then this function will apply some simple heuristic based on
598 the "Last-Modified" header to determine a suitable lifetime. The
599 following options might be passed to control the heuristics:
600  
601 =over
602  
603 =item heuristic_expiry => $bool
604  
605 If passed as a FALSE value, don't apply heuristics and just return
606 C<undef> when "Expires" or "Cache-Control" is lacking.
607  
608 =item h_lastmod_fraction => $num
609  
610 This number represent the fraction of the difference since the
611 "Last-Modified" timestamp to make the expiry time. The default is
612 C<0.10>, the suggested typical setting of 10% in RFC 2616.
613  
614 =item h_min => $sec
615  
616 This is the lower limit of the heuristic expiry age to use. The
617 default is C<60> (1 minute).
618  
619 =item h_max => $sec
620  
621 This is the upper limit of the heuristic expiry age to use. The
622 default is C<86400> (24 hours).
623  
624 =item h_default => $sec
625  
626 This is the expiry age to use when nothing else applies. The default
627 is C<3600> (1 hour) or "h_min" if greater.
628  
629 =back
630  
631 =item $r->is_fresh( %opt )
632  
633 Returns TRUE if the response is fresh, based on the values of
634 freshness_lifetime() and current_age(). If the response is no longer
635 fresh, then it has to be re-fetched or re-validated by the origin
636 server.
637  
638 Options might be passed to control expiry heuristics, see the
639 description of freshness_lifetime().
640  
641 =item $r->fresh_until( %opt )
642  
643 Returns the time (seconds since epoch) when this entity is no longer fresh.
644  
645 Options might be passed to control expiry heuristics, see the
646 description of freshness_lifetime().
647  
648 =back
649  
650 =head1 SEE ALSO
651  
652 L<HTTP::Headers>, L<HTTP::Message>, L<HTTP::Status>, L<HTTP::Request>
653  
654 =head1 AUTHOR
655  
656 Gisle Aas <gisle@activestate.com>
657  
658 =head1 COPYRIGHT AND LICENSE
659  
660 This software is copyright (c) 1994 by Gisle Aas.
661  
662 This is free software; you can redistribute it and/or modify it under
663 the same terms as the Perl 5 programming language system itself.
664  
665 =cut
666  
667 __END__
« Config.pm ↑ Summary Headers.pm »