NAME
"Net::Async::HTTP" - use HTTP with "IO::Async"
SYNOPSIS
use IO::Async::Loop;
use Net::Async::HTTP;
use URI;
my $loop = IO::Async::Loop->new();
my $http = Net::Async::HTTP->new();
$loop->add( $http );
$http->do_request(
uri => URI->new( "http://www.cpan.org/" ),
on_response => sub {
my ( $response ) = @_;
print "Front page of http://www.cpan.org/ is:\n";
print $response->as_string;
$loop->loop_stop;
},
on_error => sub {
my ( $message ) = @_;
print "Cannot fetch http://www.cpan.org/ - $message\n";
$loop->loop_stop;
},
);
$loop->loop_forever;
DESCRIPTION
This object class implements an asynchronous HTTP user agent. It sends requests to servers, and invokes continuation callbacks when responses are received. The object supports multiple concurrent connections to servers, and allows multiple outstanding requests in pipeline to any one connection. Normally, only one such object will be needed per program to support any number of requests.
This module optionally supports SSL connections, if IO::Async::SSL is installed. If so, SSL can be requested either by passing a URI with the "https" scheme, or by passing the a true value as the "SSL" parameter.
PARAMETERS
The following named parameters may be passed to "new" or "configure":
user_agent => STRING
A string to set in the "User-Agent" HTTP header. If not
supplied, one will be constructed that declares
"Net::Async::HTTP" and the version number.
max_redirects => INT
Optional. How many levels of redirection to follow. If not
supplied, will default to 3. Give 0 to disable redirection
entirely.
proxy_host => STRING
proxy_port => INT
Optional. Default values to apply to each "request" method.
cookie_jar => HTTP::Cookies
Optional. A reference to a HTTP::Cookies object. Will be used to
set cookies in requests and store them from responses.
METHODS
$http->do_request( %args )
Send an HTTP request to a server, and set up the callbacks to receive a
reply. The request may be represented by an HTTP::Request object, or a
URI object, depending on the arguments passed.
The following named arguments are used for "HTTP::Request"s:
request => HTTP::Request
A reference to an "HTTP::Request" object
host => STRING
port => INT
Hostname and port number of the server to connect to
SSL => BOOL
Optional. If true, an SSL connection will be used.
The following named arguments are used for "URI" requests:
uri => URI
A reference to a "URI" object. If the scheme is "https" then an
SSL connection will be used.
method => STRING
Optional. The HTTP method. If missing, "GET" is used.
content => STRING or ARRAY ref
Optional. The body content to use for "POST" requests. If this
is a plain scalar instead of an ARRAY ref, it will not be form
encoded. In this case, a "content_type" field must also be
supplied to describe it.
request_body => CODE or STRING
Optional. Allows request body content to be generated by a
callback, rather than being provided as part of the "request"
object. This can either be a "CODE" reference to a generator
function, or a plain string.
As this is passed to the underlying IO::Async::Stream "write"
method, the usual semantics apply here. If passed a "CODE"
reference, it will be called repeatedly whenever it's safe to
write. The code should should return "undef" to indicate
completion.
As with the "content" parameter, the "content_type" field should
be specified explicitly in the request header, as should the
content length (typically via the HTTP::Request "content_length"
method). See also examples/PUT.pl.
content_type => STRING
The type of non-form data "content".
user => STRING
pass => STRING
Optional. If both are given, the HTTP Basic Authorization header
will be sent with these details.
proxy_host => STRING
proxy_port => INT
Optional. Override the hostname or port number implied by the
URI.
For either request type, it takes the following continuation callbacks:
on_response => CODE
A callback that is invoked when a response to this request has
been received. It will be passed an HTTP::Response object
containing the response the server sent.
$on_response->( $response )
on_header => CODE
Alternative to "on_response". A callback that is invoked when
the header of a response has been received. It is expected to
return a "CODE" reference for handling chunks of body content.
This "CODE" reference will be invoked with no arguments once the
end of the request has been reached.
$on_body_chunk = $on_header->( $header )
$on_body_chunk->( $data )
$on_body_chunk->()
on_error => CODE
A callback that is invoked if an error occurs while trying to
send the request or obtain the response. It will be passed an
error message.
$on_error->( $message )
on_redirect => CODE
Optional. A callback that is invoked if a redirect response is
received, before the new location is fetched. It will be passed
the response and the new URL.
$on_redirect->( $response, $location )
max_redirects => INT
Optional. How many levels of redirection to follow. If not
supplied, will default to the value given in the constructor.
SUBCLASS METHODS
The following methods are intended as points for subclasses to override, to add extra functionallity.
$http->prepare_request( $request )
Called just before the "HTTP::Request" object is sent to the server.
$http->process_response( $response )
Called after a non-redirect "HTTP::Response" has been received from a
server. The originating request will be set in the object.
SEE ALSO
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>