/ 
Net-Async-HTTP-0.27_002
River stage two • 25 direct dependents • 29 total dependents
/ Net::Async::HTTP

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 requests in the 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 a true value as the SSL parameter.

Connection Pooling

There are three ways in which connections to HTTP server hosts are managed by this object, controlled by the value of max_connections_per_host. This controls when new connections are established to servers, as compared to waiting for existing connections to be free, as new requests are made to them.

They are:

max_connections_per_host = 1

This is the default setting. In this mode, there will be one connection per host on which there are active or pending requests. If new requests are made while an existing one is outstanding, they will be queued to wait for it.

If pipelining is active on the connection (because both the pipeline option is true and the connection is known to be an HTTP/1.1 server), then requests will be pipelined into the connection awaiting their response. If not, they will be queued awaiting a response to the previous before sending the next.

max_connections_per_host > 1

In this mode, there can be more than one connection per host. If a new request is made, it will try to re-use idle connections if there are any, or if they are all busy it will create a new connection to the host, up to the configured limit.

max_connections_per_host = 0

In this mode, there is no upper limit to the number of connections per host. Every new request will try to reuse an idle connection, or else create a new one if all the existing ones are busy.

These modes all apply per hostname / server port pair; they do not affect the behaviour of connections made to differing hostnames, or differing ports on the same hostname.

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.

max_in_flight => INT

Optional. The maximum number of in-flight requests to allow per host when pipelining is enabled and supported on that host. If more requests are made over this limit they will be queued internally by the object and not sent to the server until responses are received. If not supplied, will default to 4. Give 0 to disable the limit entirely.

max_connections_per_host => INT

Optional. Controls the maximum number of connections per hostname/server port pair, before requests will be queued awaiting one to be free. If not supplied, will default to 1. Give 0 to disable the limit entirely. See also the "Connection Pooling" section documented above.

timeout => NUM

Optional. How long in seconds to wait before giving up on a request. If not supplied then no default will be applied, and no timeout will take place.

stall_timeout => NUM

Optional. How long in seconds to wait after each write or read of data on a socket, before giving up on a request. This may be more useful than timeout on large-file operations, as it will not time out provided that regular progress is still being made.

proxy_host => STRING
proxy_port => INT

Optional. Default values to apply to each request method.

Optional. A reference to a HTTP::Cookies object. Will be used to set cookies in requests and store them from responses.

pipeline => BOOL

Optional. If false, disables HTTP/1.1-style request pipelining.

local_host => STRING
local_port => INT
local_addrs => ARRAY
local_addr => HASH or ARRAY

Optional. Parameters to pass on to the connect method used to connect sockets to HTTP servers. Sets the local socket address to bind() to. For more detail, see the documentation in IO::Async::Connector.

fail_on_error => BOOL

Optional. Affects the behaviour of response handling when a 4xx or 5xx response code is received. When false, these responses will be processed as other responses and passed to the on_response callback, or used to set the successful result of the Future. When true, such an error response causes the on_error handling or a failed Future instead. The HTTP response and request objects will be passed as well as the code and message.

$on_error->( "$code $message", $response, $request )

( $code_message, $response, $request ) = $f->failure
read_len => INT
write_len => INT

Optional. Used to set the reading and writing buffer lengths on the underlying IO::Async::Stream objects that represent connections to the server. If not define, a default of 64 KiB will be used.

ip_tos => INT or STRING

Optional. Used to set the IP_TOS socket option on client sockets. If given, should either be a IPTOS_* constant, or one of the string names lowdelay, throughput, reliability or mincost. If undefined or left absent, no option will be set.

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::Requests:

request => HTTP::Request

A reference to an HTTP::Request object

host => STRING

Hostname of the server to connect to

port => INT or STRING

Optional. Port number or service of the server to connect to. If not defined, will default to http or https depending on whether SSL is being used.

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.

expect_continue => BOOL

Optional. If true, sets the Expect request header to the value 100-continue and does not send the request_body parameter until a 100 Continue response is received from the server. If an error response is received then the request_body code, if present, will not be invoked.

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 )

If this is invoked because of a received 4xx or 5xx error code in an HTTP response, it will be invoked with the response and request objects as well.

$on_error->( $message, $response, $request )
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.

timeout => NUM
stall_timeout => NUM

Optional. Overrides the object's configured timeout values for this one request. If not specified, will use the configured defaults.

$future = $http->do_request( %args )

This method also returns a Future, which will eventually yield the (final non-redirect) HTTP::Response. If returning a future, then the on_response, on_header and on_error callbacks are optional.

$future = $http->GET( $uri, %args )

$future = $http->HEAD( $uri, %args )

Convenient wrappers for using the GET or HEAD methods with a URI object and few if any other arguments, returning a Future.

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.

EXAMPLES

Concurrent GET

The Future-returning GET method makes it easy to await multiple URLs at once, by using the Future::Utils fmap_void utility

my @URLs = ( ... );

my $http = Net::Async::HTTP->new( ... );
$loop->add( $http );

my $future = fmap_void {
   my ( $url ) = @_;
   $http->GET( $url )
        ->on_done( sub {
           my $response = shift;
           say "$url succeeded: ", $response->code;
           say "  Content-Type":", $response->content_type;
        } )
        ->on_fail( sub {
           my $failure = shift;
           say "$url failed: $failure";
        } );
} foreach => \@URLs;

$loop->await( $future );

SEE ALSO

SPONSORS

Parts of this code were paid for by

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>