HTTP-Tiny
view release on metacpan or search on metacpan
my $response = HTTP::Tiny->new->get('http://example.com/');
die "Failed!\n" unless $response->{success};
print "$response->{status} $response->{reason}\n";
while (my ($k, $v) = each %{$response->{headers}}) {
for (ref $v eq 'ARRAY' ? @$v : $v) {
print "$k: $_\n";
}
}
print $response->{content} if length $response->{content};
DESCRIPTION
This is a very simple HTTP/1.1 client, designed for doing simple
requests without the overhead of a large framework like LWP::UserAgent.
It is more correct and more complete than HTTP::Lite. It supports
proxies and redirection. It also correctly resumes after EINTR.
If IO::Socket::IP 0.25 or later is installed, HTTP::Tiny will use it
instead of IO::Socket::INET for transparent support for both IPv4 and
IPv6.
Cookie support requires HTTP::CookieJar or an equivalent class.
METHODS
new
$http = HTTP::Tiny->new( %attributes );
This constructor returns a new HTTP::Tiny object. Valid attributes
include:
* "agent" — A user-agent string (defaults to '"HTTP-Tiny/$VERSION"').
If "agent" — ends in a space character, the default user-agent
string is appended.
* "allow_credentialed_redirects" - If a "3XX" redirects to a different
scheme, host or port, by default HTTP::Tiny will strip away
caller-supplied "Authorization", "Cookie" and "Proxy-Authorization"
headers from the redirected request and from all subsequent requests
in the chain. Set this to a true value to revert to the legacy
behavior of forwarding those headers. Default is "false".
* "allow_downgrade" — If a "3XX" redirect changes the scheme from
"https" to plain "http", HTTP::Tiny will by default refuse to follow
it, returning the "3XX" response. Set this to a true value to revert
to the legacy behavior of redirecting "https" to "http". Default is
"false".
* "cookie_jar" — An instance of HTTP::CookieJar — or equivalent class
that supports the "add" and "cookie_header" methods
* "default_headers" — A hashref of default headers to apply to
requests
* "local_address" — The local IP address to bind to
* "keep_alive" — Whether to reuse the last connection (if for the same
scheme, host and port) (defaults to 1)
* "keep_alive_timeout" — How many seconds to keep a connection
available for after a request (defaults to 0, unlimited)
* "max_redirect" — Maximum number of redirects allowed (defaults to 5)
* "max_size" — Maximum response size in bytes (only when not using a
data callback). If defined, requests with responses larger than this
will return a 599 status code.
* "http_proxy" — URL of a proxy server to use for HTTP connections
(default is $ENV{http_proxy} — if set)
* "https_proxy" — URL of a proxy server to use for HTTPS connections
(default is $ENV{https_proxy} — if set)
* "proxy" — URL of a generic proxy server for both HTTP and HTTPS
connections (default is $ENV{all_proxy} — if set)
* "no_proxy" — List of domain suffixes that should not be proxied.
Must be a comma-separated string or an array reference. (default is
$ENV{no_proxy} —)
* "timeout" — Request timeout in seconds (default is 60) If a socket
open, read or write takes longer than the timeout, the request
response status code will be 599.
* "verify_SSL" — A boolean that indicates whether to validate the
TLS/SSL certificate of an "https" — connection (default is true).
Changed from false to true in version 0.083.
* "SSL_options" — A hashref of "SSL_*" — options to pass through to
IO::Socket::SSL
* $ENV{PERL_HTTP_TINY_SSL_INSECURE_BY_DEFAULT} - Changes the default
certificate verification behavior to not check server identity if
set to 1. Only effective if "verify_SSL" is not set. Added in
version 0.083.
An accessor/mutator method exists for each attribute.
Passing an explicit "undef" for "proxy", "http_proxy" or "https_proxy"
will prevent getting the corresponding proxies from the environment.
Errors during request execution will result in a pseudo-HTTP status code
of 599 and a reason of "Internal Exception". The content field in the
response will contain the text of the error.
The "keep_alive" parameter enables a persistent connection, but only to
a single destination scheme, host and port. If any connection-relevant
attributes are modified via accessor, or if the process ID or thread ID
change, the persistent connection will be dropped. If you want
persistent connections across multiple destinations, use multiple
HTTP::Tiny objects.
The "keep_alive_timeout" parameter allows you to control how long a keep
alive connection will be considered for reuse. By setting this lower
than the server keep alive time, this allows you to avoid race
conditions where the server closes the connection while preparing to
write the request on a reused persistent connection.
See "TLS/SSL SUPPORT" for more on the "verify_SSL" and "SSL_options"
attributes.
get|head|put|post|patch|delete
$response = $http->get($url);
$response = $http->get($url, \%options);
$response = $http->head($url);
These methods are shorthand for calling request() for the given method.
The URL must have unsafe characters escaped and international domain
names encoded. See request() for valid options and a description of the
response.
The "success" field of the response will be true if the status code is
"2XX".
post_form
$response = $http->post_form($url, $form_data);
$response = $http->post_form($url, $form_data, \%options);
This method executes a "POST" request and sends the key/value pairs from
a form data hash or array reference to the given URL with a
"content-type" of "application/x-www-form-urlencoded". If data is
provided as an array reference, the order is preserved; if provided as a
hash reference, the terms are sorted by key for consistency. See
documentation for the "www_form_urlencode" method for details on the
encoding.
The URL must have unsafe characters escaped and international domain
names encoded. See request() for valid options and a description of the
response. Any "content-type" header or content in the options hashref
will be ignored.
The "success" field of the response will be true if the status code is
"2XX".
mirror
$response = $http->mirror($url, $file, \%options)
if ( $response->{success} ) {
print "$file is up to date\n";
}
Executes a "GET" request for the URL and saves the response body to the
file name provided. The URL must have unsafe characters escaped and
international domain names encoded. If the file already exists, the
request will include an "If-Modified-Since" header with the modification
timestamp of the file. You may specify a different "If-Modified-Since"
header yourself in the "$options->{headers}" hash.
The "success" field of the response will be true if the status code is
"2XX" or if the status code is 304 (unmodified).
If the file was modified and the server response includes a properly
formatted "Last-Modified" header, the file modification time will be
updated accordingly.
request
"2XX" status code
* "url" — URL that provided the response. This is the URL of the
request unless there were redirections, in which case it is the last
URL queried in a redirection chain
* "status" — The HTTP status code of the response
* "reason" — The response phrase returned by the server
* "content" — The body of the response. If the response does not have
any content or if a data callback is provided to consume the
response body, this will be the empty string
* "headers" — A hashref of header fields. All header field names will
be normalized to be lower case. If a header is repeated, the value
will be an arrayref; it will otherwise be a scalar string containing
the value
* "protocol" - If this field exists, it is the protocol of the
response such as HTTP/1.0 or HTTP/1.1
* "redirects" If this field exists, it is an arrayref of response hash
references from redirects in the same order that redirections
occurred. If it does not exist, then no redirections occurred.
On an error during the execution of the request, the "status" field will
contain 599, and the "content" field will contain the text of the error.
www_form_urlencode
$params = $http->www_form_urlencode( $data );
$response = $http->get("http://example.com/query?$params");
This method converts the key/value pairs from a data hash or array
reference into a "x-www-form-urlencoded" string. The keys and values
from the data reference will be UTF-8 encoded and escaped per RFC 3986.
If a value is an array reference, the key will be repeated with each of
the values of the array reference. If data is provided as a hash
reference, the key/value pairs in the resulting string will be sorted by
key and value for consistent ordering.
can_ssl
$ok = HTTP::Tiny->can_ssl;
($ok, $why) = HTTP::Tiny->can_ssl;
($ok, $why) = $http->can_ssl;
Indicates if SSL support is available. When called as a class object, it
checks for the correct version of Net::SSLeay and IO::Socket::SSL. When
called as an object methods, if "SSL_verify" is true or if
"SSL_verify_mode" is set in "SSL_options", it checks that a CA file is
available.
In scalar context, returns a boolean indicating if SSL is available. In
list context, returns the boolean and a (possibly multi-line) string of
errors indicating why SSL isn't available.
connected
$host = $http->connected;
($host, $port) = $http->connected;
Indicates if a connection to a peer is being kept alive, per the
"keep_alive" option.
In scalar context, returns the peer host and port, joined with a colon,
or "undef" (if no peer is connected). In list context, returns the peer
host and port or an empty list (if no peer is connected).
Note: This method cannot reliably be used to discover whether the remote
host has closed its end of the socket.
TLS/SSL SUPPORT
Direct "https" connections are supported only if IO::Socket::SSL 1.56 or
greater and Net::SSLeay 1.49 or greater are installed. An error will
occur if new enough versions of these modules are not installed or if
the TLS encryption fails. You can also use HTTP::Tiny::can_ssl() utility
function that returns boolean to see if the required modules are
installed.
An "https" connection may be made via an "http" proxy that supports the
CONNECT command (i.e. RFC 2817). You may not proxy "https" via a proxy
that itself requires "https" to communicate.
TLS/SSL provides two distinct capabilities:
* Encrypted communication channel
* Verification of server identity
By default, HTTP::Tiny verifies server identity.
This was changed in version 0.083 due to security concerns. The previous
default behavior can be enabled by setting
$ENV{PERL_HTTP_TINY_SSL_INSECURE_BY_DEFAULT} to 1.
Verification is done by checking that that the TLS/SSL connection has a
valid certificate corresponding to the host name of the connection and
that the certificate has been verified by a CA. Assuming you trust the
CA, this will protect against machine-in-the-middle attacks
<http://en.wikipedia.org/wiki/Machine-in-the-middle_attack>.
Certificate verification requires a file or directory containing trusted
CA certificates.
IO::Socket::SSL::default_ca() is called to detect the default location
of your CA certificates. This also supports the environment variables
"SSL_CERT_FILE" and "SSL_CERT_DIR", and will fail over to Mozilla::CA if
no certs are found.
If IO::Socket::SSL::default_ca() is not able to find usable CA
certificates, HTTP::Tiny will search several well-known system-specific
default locations for a CA certificate file as a last resort:
* /etc/ssl/certs/ca-certificates.crt
* /etc/pki/tls/certs/ca-bundle.crt
* /etc/ssl/ca-bundle.pem
* /etc/openssl/certs/ca-certificates.crt
* /etc/ssl/cert.pem
( run in 1.755 second using v1.01-cache-2.11-cpan-71847e10f99 )