summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/site/lib/LWP
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/site/lib/LWP')
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/Authen/Basic.pm18
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/Authen/Digest.pm15
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/Authen/Ntlm.pm2
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/ConnCache.pm4
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/Debug.pm2
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/Debug/TraceHTTP.pm2
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/DebugFile.pm2
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/MediaTypes.pm32
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/MemberMixin.pm2
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/Protocol.pm2
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/Protocol/cpan.pm2
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/Protocol/data.pm2
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/Protocol/file.pm2
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/Protocol/ftp.pm2
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/Protocol/gopher.pm2
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/Protocol/http.pm2
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/Protocol/loopback.pm2
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/Protocol/mailto.pm2
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/Protocol/nntp.pm2
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/Protocol/nogo.pm2
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/RobotUA.pm2
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/Simple.pm2
-rw-r--r--Master/tlpkg/tlperl/site/lib/LWP/UserAgent.pm245
23 files changed, 259 insertions, 91 deletions
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Authen/Basic.pm b/Master/tlpkg/tlperl/site/lib/LWP/Authen/Basic.pm
index d33e4af2e40..513475f1a3c 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Authen/Basic.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Authen/Basic.pm
@@ -2,7 +2,7 @@ package LWP::Authen::Basic;
use strict;
-our $VERSION = '6.37';
+our $VERSION = '6.43';
require MIME::Base64;
@@ -11,6 +11,10 @@ sub auth_header {
return "Basic " . MIME::Base64::encode("$user:$pass", "");
}
+sub _reauth_requested {
+ return 0;
+}
+
sub authenticate
{
my($class, $ua, $proxy, $auth_param, $response,
@@ -37,9 +41,15 @@ sub authenticate
});
$h->{auth_param} = $auth_param;
- if (!$proxy && !$request->header($auth_header) && $ua->credentials($host_port, $realm)) {
- # we can make sure this handler applies and retry
- add_path($h, $url->path);
+ my $reauth_requested
+ = $class->_reauth_requested($auth_param, $ua, $request, $auth_header);
+ if ( !$proxy
+ && (!$request->header($auth_header) || $reauth_requested)
+ && $ua->credentials($host_port, $realm))
+ {
+ # we can make sure this handler applies and retry
+ add_path($h, $url->path)
+ unless $reauth_requested; # Do not clobber up path list for retries
return $ua->request($request->clone, $arg, $size, $response);
}
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Authen/Digest.pm b/Master/tlpkg/tlperl/site/lib/LWP/Authen/Digest.pm
index 2e11ac638b9..5ed025182f6 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Authen/Digest.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Authen/Digest.pm
@@ -3,10 +3,23 @@ package LWP::Authen::Digest;
use strict;
use base 'LWP::Authen::Basic';
-our $VERSION = '6.37';
+our $VERSION = '6.43';
require Digest::MD5;
+sub _reauth_requested {
+ my ($class, $auth_param, $ua, $request, $auth_header) = @_;
+ my $ret = defined($$auth_param{stale}) && lc($$auth_param{stale}) eq 'true';
+ if ($ret) {
+ my $hdr = $request->header($auth_header);
+ $hdr =~ tr/,/;/; # "," is used to separate auth-params!!
+ ($hdr) = HTTP::Headers::Util::split_header_words($hdr);
+ my $nonce = {@$hdr}->{nonce};
+ delete $$ua{authen_md5_nonce_count}{$nonce};
+ }
+ return $ret;
+}
+
sub auth_header {
my($class, $user, $pass, $request, $ua, $h) = @_;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Authen/Ntlm.pm b/Master/tlpkg/tlperl/site/lib/LWP/Authen/Ntlm.pm
index b4eaad1eaa9..ebe07e2c1af 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Authen/Ntlm.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Authen/Ntlm.pm
@@ -2,7 +2,7 @@ package LWP::Authen::Ntlm;
use strict;
-our $VERSION = '6.37';
+our $VERSION = '6.43';
use Authen::NTLM "1.02";
use MIME::Base64 "2.12";
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/ConnCache.pm b/Master/tlpkg/tlperl/site/lib/LWP/ConnCache.pm
index d4cfc66e266..240eacf0910 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/ConnCache.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/ConnCache.pm
@@ -2,7 +2,7 @@ package LWP::ConnCache;
use strict;
-our $VERSION = '6.37';
+our $VERSION = '6.43';
our $DEBUG;
sub new {
@@ -201,7 +201,7 @@ The following basic methods are provided:
This method constructs a new L<LWP::ConnCache> object. The only
option currently accepted is C<total_capacity>. If specified it
-initialize the L<LWP::ConnCache/total_capacity> option. It defaults to C<1>.
+initializes the L<LWP::ConnCache/total_capacity> option. It defaults to C<1>.
=head2 total_capacity
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Debug.pm b/Master/tlpkg/tlperl/site/lib/LWP/Debug.pm
index c93a80ade30..7f05c433575 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Debug.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Debug.pm
@@ -1,6 +1,6 @@
package LWP::Debug; # legacy
-our $VERSION = '6.37';
+our $VERSION = '6.43';
require Exporter;
our @ISA = qw(Exporter);
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Debug/TraceHTTP.pm b/Master/tlpkg/tlperl/site/lib/LWP/Debug/TraceHTTP.pm
index 0644644616c..febd627e0b6 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Debug/TraceHTTP.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Debug/TraceHTTP.pm
@@ -11,7 +11,7 @@ package LWP::Debug::TraceHTTP;
use strict;
use base 'LWP::Protocol::http';
-our $VERSION = '6.37';
+our $VERSION = '6.43';
package # hide from PAUSE
LWP::Debug::TraceHTTP::Socket;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/DebugFile.pm b/Master/tlpkg/tlperl/site/lib/LWP/DebugFile.pm
index f35cdf3426d..8a931ce4b15 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/DebugFile.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/DebugFile.pm
@@ -1,6 +1,6 @@
package LWP::DebugFile;
-our $VERSION = '6.37';
+our $VERSION = '6.43';
# legacy stub
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/MediaTypes.pm b/Master/tlpkg/tlperl/site/lib/LWP/MediaTypes.pm
index 8c2a8aee334..22d00e3391b 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/MediaTypes.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/MediaTypes.pm
@@ -4,9 +4,11 @@ require Exporter;
@ISA = qw(Exporter);
@EXPORT = qw(guess_media_type media_suffix);
@EXPORT_OK = qw(add_type add_encoding read_media_types);
-$VERSION = "6.02";
+our $VERSION = '6.04';
use strict;
+use Scalar::Util qw(blessed);
+use Carp qw(croak);
# note: These hashes will also be filled with the entries found in
# the 'media.types' file.
@@ -47,10 +49,17 @@ sub guess_media_type
return undef unless defined $file;
my $fullname;
- if (ref($file)) {
- # assume URI object
- $file = $file->path;
- #XXX should handle non http:, file: or ftp: URIs differently
+ if (ref $file) {
+ croak("Unable to determine filetype on unblessed refs") unless blessed($file);
+ if ($file->can('path')) {
+ $file = $file->path;
+ }
+ elsif ($file->can('filename')) {
+ $fullname = $file->filename;
+ }
+ else {
+ $fullname = "" . $file;
+ }
}
else {
$fullname = $file; # enable peek at actual file
@@ -124,7 +133,7 @@ sub media_suffix {
}
-sub file_exts
+sub file_exts
{
require File::Basename;
my @parts = reverse split(/\./, File::Basename::basename($_[0]));
@@ -133,7 +142,7 @@ sub file_exts
}
-sub add_type
+sub add_type
{
my($type, @exts) = @_;
for my $ext (@exts) {
@@ -154,7 +163,7 @@ sub add_encoding
}
-sub read_media_types
+sub read_media_types
{
my(@files) = @_;
@@ -214,9 +223,12 @@ The following functions are exported by default:
=item guess_media_type( $uri )
-=item guess_media_type( $filename_or_uri, $header_to_modify )
+=item guess_media_type( $filename_or_object, $header_to_modify )
-This function tries to guess media type and encoding for a file or a URI.
+This function tries to guess media type and encoding for a file or objects that
+support the a C<path> or C<filename> method, eg, L<URI> or L<File::Temp> objects.
+When an object does not support either method, it will be stringified to
+determine the filename.
It returns the content type, which is a string like C<"text/html">.
In array context it also returns any content encodings applied (in the
order used to encode the file). You can pass a URI object
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/MemberMixin.pm b/Master/tlpkg/tlperl/site/lib/LWP/MemberMixin.pm
index 4ed9053cbc2..f32d27df447 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/MemberMixin.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/MemberMixin.pm
@@ -1,6 +1,6 @@
package LWP::MemberMixin;
-our $VERSION = '6.37';
+our $VERSION = '6.43';
sub _elem {
my $self = shift;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol.pm
index f5966ab1c16..d1f03f133bf 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol.pm
@@ -2,7 +2,7 @@ package LWP::Protocol;
use base 'LWP::MemberMixin';
-our $VERSION = '6.37';
+our $VERSION = '6.43';
use strict;
use Carp ();
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/cpan.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/cpan.pm
index 1f6bd0d91b9..93f1c8a2452 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/cpan.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/cpan.pm
@@ -4,7 +4,7 @@ use strict;
use base qw(LWP::Protocol);
-our $VERSION = '6.37';
+our $VERSION = '6.43';
require URI;
require HTTP::Status;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/data.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/data.pm
index 8460f05be9f..fdbdb2fe93d 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/data.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/data.pm
@@ -4,7 +4,7 @@ package LWP::Protocol::data;
use strict;
-our $VERSION = '6.37';
+our $VERSION = '6.43';
require HTTP::Response;
require HTTP::Status;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/file.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/file.pm
index 01c14eeafa7..90c1c1b07cf 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/file.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/file.pm
@@ -4,7 +4,7 @@ use base qw(LWP::Protocol);
use strict;
-our $VERSION = '6.37';
+our $VERSION = '6.43';
require LWP::MediaTypes;
require HTTP::Request;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/ftp.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/ftp.pm
index d45a877f593..c6d75294a99 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/ftp.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/ftp.pm
@@ -5,7 +5,7 @@ package LWP::Protocol::ftp;
use base qw(LWP::Protocol);
use strict;
-our $VERSION = '6.37';
+our $VERSION = '6.43';
use Carp ();
use HTTP::Status ();
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/gopher.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/gopher.pm
index 6fd6ff710ba..3c3f8c96f61 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/gopher.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/gopher.pm
@@ -9,7 +9,7 @@ package LWP::Protocol::gopher;
use strict;
-our $VERSION = '6.37';
+our $VERSION = '6.43';
require HTTP::Response;
require HTTP::Status;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/http.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/http.pm
index ec53e23d95d..052b773d711 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/http.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/http.pm
@@ -2,7 +2,7 @@ package LWP::Protocol::http;
use strict;
-our $VERSION = '6.37';
+our $VERSION = '6.43';
require HTTP::Response;
require HTTP::Status;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/loopback.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/loopback.pm
index b7645deee66..a00a53e7103 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/loopback.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/loopback.pm
@@ -2,7 +2,7 @@ package LWP::Protocol::loopback;
use strict;
-our $VERSION = '6.37';
+our $VERSION = '6.43';
require HTTP::Response;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/mailto.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/mailto.pm
index d970edafbe6..15a4d40d9da 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/mailto.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/mailto.pm
@@ -11,7 +11,7 @@ require HTTP::Status;
use Carp;
use strict;
-our $VERSION = '6.37';
+our $VERSION = '6.43';
use base qw(LWP::Protocol);
our $SENDMAIL;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/nntp.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/nntp.pm
index 3cbde3f4e0a..c667c342041 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/nntp.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/nntp.pm
@@ -4,7 +4,7 @@ package LWP::Protocol::nntp;
use base qw(LWP::Protocol);
-our $VERSION = '6.37';
+our $VERSION = '6.43';
require HTTP::Response;
require HTTP::Status;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/nogo.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/nogo.pm
index 32f09579bff..5a9fe059078 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/nogo.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/nogo.pm
@@ -7,7 +7,7 @@ package LWP::Protocol::nogo;
use strict;
-our $VERSION = '6.37';
+our $VERSION = '6.43';
require HTTP::Response;
require HTTP::Status;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/RobotUA.pm b/Master/tlpkg/tlperl/site/lib/LWP/RobotUA.pm
index a418fe32fe5..9fe93324a04 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/RobotUA.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/RobotUA.pm
@@ -2,7 +2,7 @@ package LWP::RobotUA;
use base qw(LWP::UserAgent);
-our $VERSION = '6.37';
+our $VERSION = '6.43';
require WWW::RobotRules;
require HTTP::Request;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Simple.pm b/Master/tlpkg/tlperl/site/lib/LWP/Simple.pm
index f1b91b13ca6..cf4b4b0c566 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Simple.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Simple.pm
@@ -2,7 +2,7 @@ package LWP::Simple;
use strict;
-our $VERSION = '6.37';
+our $VERSION = '6.43';
require Exporter;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/UserAgent.pm b/Master/tlpkg/tlperl/site/lib/LWP/UserAgent.pm
index 58f09e0b2a9..668d1c04886 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/UserAgent.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/UserAgent.pm
@@ -15,7 +15,7 @@ use LWP::Protocol ();
use Scalar::Util qw(blessed);
use Try::Tiny qw(try catch);
-our $VERSION = '6.37';
+our $VERSION = '6.43';
sub new
{
@@ -420,8 +420,11 @@ sub request {
"Unsupported authentication scheme '$scheme'");
next CHALLENGE;
}
- return $class->authenticate($self, $proxy, $challenge, $response,
+ my $re = $class->authenticate($self, $proxy, $challenge, $response,
$request, $arg, $size);
+
+ next CHALLENGE if $re->code == HTTP::Status::RC_UNAUTHORIZED;
+ return $re;
}
return $response;
}
@@ -489,6 +492,21 @@ sub head {
return $self->request( HTTP::Request::Common::HEAD( @parameters ), @suff );
}
+sub patch {
+ require HTTP::Request::Common;
+ my($self, @parameters) = @_;
+ my @suff = $self->_process_colonic_headers(\@parameters, (ref($parameters[1]) ? 2 : 1));
+
+ # this work-around is in place as HTTP::Request::Common
+ # did not implement a patch convenience method until
+ # version 6.12. Once we can bump the prereq to at least
+ # that version, we can use ::PATCH instead of this hack
+ my $req = HTTP::Request::Common::PUT(@parameters);
+ $req->method('PATCH');
+
+ $self->_maybe_copy_default_content_type($req, @parameters);
+ return $self->request($req, @suff);
+}
sub put {
require HTTP::Request::Common;
@@ -966,6 +984,8 @@ sub mirror
{
my($self, $url, $file) = @_;
+ die "Local file name is missing" unless defined $file && length $file;
+
my $request = HTTP::Request->new('GET', $url);
# If the file exists, add a cache-related header
@@ -979,10 +999,10 @@ sub mirror
my $response = $self->request($request, $tmpfile);
if ( $response->header('X-Died') ) {
- die $response->header('X-Died');
+ die $response->header('X-Died');
}
- # Only fetching a fresh copy of the would be considered success.
+ # Only fetching a fresh copy of the file would be considered success.
# If the file was not modified, "304" would returned, which
# is considered by HTTP::Status to be a "redirect", /not/ "success"
if ( $response->is_success ) {
@@ -1017,7 +1037,7 @@ sub mirror
}
# The local copy is fresh enough, so just delete the temp file
else {
- unlink($tmpfile);
+ unlink($tmpfile);
}
return $response;
}
@@ -1133,22 +1153,48 @@ LWP::UserAgent - Web user agent class
=head1 SYNOPSIS
- use strict;
- use warnings;
- use LWP::UserAgent ();
+ use strict;
+ use warnings;
+
+ use LWP::UserAgent ();
- my $ua = LWP::UserAgent->new;
- $ua->timeout(10);
- $ua->env_proxy;
+ my $ua = LWP::UserAgent->new(timeout => 10);
+ $ua->env_proxy;
- my $response = $ua->get('http://search.cpan.org/');
+ my $response = $ua->get('http://example.com');
- if ($response->is_success) {
- print $response->decoded_content; # or whatever
- }
- else {
- die $response->status_line;
- }
+ if ($response->is_success) {
+ print $response->decoded_content;
+ }
+ else {
+ die $response->status_line;
+ }
+
+Extra layers of security (note the C<cookie_jar> and C<protocols_allowed>):
+
+ use strict;
+ use warnings;
+
+ use HTTP::CookieJar::LWP ();
+ use LWP::UserAgent ();
+
+ my $jar = HTTP::CookieJar::LWP->new;
+ my $ua = LWP::UserAgent->new(
+ cookie_jar => $jar,
+ protocols_allowed => ['http', 'https'],
+ timeout => 10,
+ );
+
+ $ua->env_proxy;
+
+ my $response = $ua->get('http://example.com');
+
+ if ($response->is_success) {
+ print $response->decoded_content;
+ }
+ else {
+ die $response->status_line;
+ }
=head1 DESCRIPTION
@@ -1221,7 +1267,7 @@ is passed in with a true value, then proxy settings are read from environment
variables (see L<LWP::UserAgent/env_proxy>). If C<env_proxy> isn't provided, the
C<PERL_LWP_ENV_PROXY> environment variable controls if
L<LWP::UserAgent/env_proxy> is called during initialization. If the
-C<keep_alive> option is passed in, then a C<LWP::ConnCache> is set up (see
+C<keep_alive> option value is defined and non-zero, then an C<LWP::ConnCache> is set up (see
L<LWP::UserAgent/conn_cache>). The C<keep_alive> value is passed on as the
C<total_capacity> for the connection cache.
@@ -1276,7 +1322,16 @@ the cookie jar object must implement the C<extract_cookies($response)> and
C<add_cookie_header($request)> methods. These methods will then be
invoked by the user agent as requests are sent and responses are
received. Normally this will be a L<HTTP::Cookies> object or some
-subclass.
+subclass. You are, however, encouraged to use L<HTTP::CookieJar::LWP>
+instead. See L</"BEST PRACTICES"> for more information.
+
+ use HTTP::CookieJar::LWP ();
+
+ my $jar = HTTP::CookieJar::LWP->new;
+ my $ua = LWP::UserAgent->new( cookie_jar => $jar );
+
+ # or after object creation
+ $ua->cookie_jar( $cookie_jar );
The default is to have no cookie jar, i.e. never automatically add
C<Cookie> headers to the requests.
@@ -1592,34 +1647,27 @@ the active handlers:
Add handler to be invoked in the given processing phase. For how to
specify C<%matchspec> see L<HTTP::Config/"Matching">.
-The possible values C<$phase> and the corresponding callback signatures are:
+The possible values C<$phase> and the corresponding callback signatures are as
+follows. Note that the handlers are documented in the order in which they will
+be run, which is:
-=over
+ request_preprepare
+ request_prepare
+ request_send
+ response_header
+ response_data
+ response_done
+ response_redirect
-=item response_data => sub { my($response, $ua, $handler, $data) = @_; ... }
-
-This handler is called for each chunk of data received for the
-response. The handler might croak to abort the request.
-
-This handler needs to return a TRUE value to be called again for
-subsequent chunks for the same request.
-
-=item response_done => sub { my($response, $ua, $handler) = @_; ... }
-
-The handler is called after the response has been fully received, but
-before any redirect handling is attempted. The handler can be used to
-extract information or modify the response.
-
-=item response_header => sub { my($response, $ua, $handler) = @_; ... }
+=over
-This handler is called right after the response headers have been
-received, but before any content data. The handler might set up
-handlers for data and might croak to abort the request.
+=item request_preprepare => sub { my($request, $ua, $handler) = @_; ... }
-The handler might set the C<< $response->{default_add_content} >> value to
-control if any received data should be added to the response object
-directly. This will initially be false if the C<< $ua->request() >> method
-was called with a C<$content_file> or C<$content_cb argument>; otherwise true.
+The handler is called before the C<request_prepare> and other standard
+initialization of the request. This can be used to set up headers
+and attributes that the C<request_prepare> handler depends on. Proxy
+initialization should take place here; but in general don't register
+handlers for this phase.
=item request_prepare => sub { my($request, $ua, $handler) = @_; ... }
@@ -1634,14 +1682,6 @@ The return value from the callback is ignored. If an exception is
raised it will abort the request and make the request method return a
"400 Bad request" response.
-=item request_preprepare => sub { my($request, $ua, $handler) = @_; ... }
-
-The handler is called before the C<request_prepare> and other standard
-initialization of the request. This can be used to set up headers
-and attributes that the C<request_prepare> handler depends on. Proxy
-initialization should take place here; but in general don't register
-handlers for this phase.
-
=item request_send => sub { my($request, $ua, $handler) = @_; ... }
This handler gets a chance of handling requests before they're sent to the
@@ -1651,6 +1691,31 @@ wishes to terminate the processing; otherwise it should return nothing.
The C<response_header> and C<response_data> handlers will not be
invoked for this response, but the C<response_done> will be.
+=item response_header => sub { my($response, $ua, $handler) = @_; ... }
+
+This handler is called right after the response headers have been
+received, but before any content data. The handler might set up
+handlers for data and might croak to abort the request.
+
+The handler might set the C<< $response->{default_add_content} >> value to
+control if any received data should be added to the response object
+directly. This will initially be false if the C<< $ua->request() >> method
+was called with a C<$content_file> or C<$content_cb argument>; otherwise true.
+
+=item response_data => sub { my($response, $ua, $handler, $data) = @_; ... }
+
+This handler is called for each chunk of data received for the
+response. The handler might croak to abort the request.
+
+This handler needs to return a TRUE value to be called again for
+subsequent chunks for the same request.
+
+=item response_done => sub { my($response, $ua, $handler) = @_; ... }
+
+The handler is called after the response has been fully received, but
+before any redirect handling is attempted. The handler can be used to
+extract information or modify the response.
+
=item response_redirect => sub { my($response, $ua, $handler) = @_; ... }
The handler is called in C<< $ua->request >> after C<response_done>. If the
@@ -1687,7 +1752,7 @@ the given processing phase.
$ua->remove_handler( undef, %matchspec );
$ua->remove_handler( $phase, %matchspec );
- $ua->remove_handlers(); # REMOVE ALL HANDLERS IN ALL PHASES
+ $ua->remove_handler(); # REMOVE ALL HANDLERS IN ALL PHASES
Remove handlers that match the given C<%matchspec>. If C<$phase> is not
provided, remove handlers from all phases.
@@ -1751,9 +1816,9 @@ Fields names that start with ":" are special. These will not
initialize headers of the request but will determine how the response
content is treated. The following special field names are recognized:
- :content_file => $filename
- :content_cb => \&callback
- :read_size_hint => $bytes
+ ':content_file' => $filename
+ ':content_cb' => \&callback
+ ':read_size_hint' => $bytes
If a $filename is provided with the C<:content_file> option, then the
response content will be saved here instead of in the response
@@ -1827,6 +1892,33 @@ forced to match that of the server.
The return value is an L<HTTP::Response> object.
+=head2 patch
+ # Any version of HTTP::Message works with this form:
+ my $res = $ua->patch( $url, $field_name => $value, Content => $content );
+
+ # Using hash or array references requires HTTP::Message >= 6.12
+ use HTTP::Request 6.12;
+ my $res = $ua->patch( $url, \%form );
+ my $res = $ua->patch( $url, \@form );
+ my $res = $ua->patch( $url, \%form, $field_name => $value, ... );
+ my $res = $ua->patch( $url, $field_name => $value, Content => \%form );
+ my $res = $ua->patch( $url, $field_name => $value, Content => \@form );
+
+This method will dispatch a C<PATCH> request on the given URL, with
+C<%form> or C<@form> providing the key/value pairs for the fill-in form
+content. Additional headers and content options are the same as for
+the L<LWP::UserAgent/get> method.
+
+CAVEAT:
+
+This method can only accept content that is in key-value pairs when using
+L<HTTP::Request::Common> prior to version C<6.12>. Any use of hash or array
+references will result in an error prior to version C<6.12>.
+
+This method will use the C<PATCH> function from L<HTTP::Request::Common>
+to build the request. See L<HTTP::Request::Common> for a details on
+how to pass form content and other advanced features.
+
=head2 post
my $res = $ua->post( $url, \%form );
@@ -1988,6 +2080,47 @@ is in the object's C<requests_redirectable> list,
false if the proposed redirection is to a C<file://...>
URL, and true otherwise.
+=head1 BEST PRACTICES
+
+The default settings can get you up and running quickly, but there are settings
+you can change in order to make your life easier.
+
+=head2 Handling Cookies
+
+You are encouraged to install L<Mozilla::PublicSuffix> and use
+L<HTTP::CookieJar::LWP> as your cookie jar. L<HTTP::CookieJar::LWP> provides a
+better security model matching that of current Web browsers when
+L<Mozilla::PublicSuffix> is installed.
+
+ use HTTP::CookieJar::LWP ();
+
+ my $jar = HTTP::CookieJar::LWP->new;
+ my $ua = LWP::UserAgent->new( cookie_jar => $jar );
+
+See L</"cookie_jar"> for more information.
+
+=head2 Managing Protocols
+
+C<protocols_allowed> gives you the ability to whitelist the protocols you're
+willing to allow.
+
+ my $ua = LWP::UserAgent->new(
+ protocols_allowed => [ 'http', 'https' ]
+ );
+
+This will prevent you from inadvertently following URLs like
+C<file:///etc/passwd>. See L</"protocols_allowed">.
+
+C<protocols_forbidden> gives you the ability to blacklist the protocols you're
+unwilling to allow.
+
+ my $ua = LWP::UserAgent->new(
+ protocols_forbidden => [ 'file', 'mailto', 'ssh', ]
+ );
+
+This can also prevent you from inadvertently following URLs like
+C<file:///etc/passwd>. See L</protocols_forbidden>.
+
=head1 SEE ALSO
See L<LWP> for a complete overview of libwww-perl5. See L<lwpcook>