Connection Pooling

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.

user_agent => STRING

headers => ARRAY or HASH

A set of extra headers to apply to every outgoing request. May be specified either as an even-sized array containing key/value pairs, or a hash.

Individual header values may be added or changed without replacing the entire set by using the configure method and passing a key called "+headers":

   $http->configure( +headers => { One_More => "Key" } );

max_redirects => INT

max_in_flight => INT

max_connections_per_host => INT

Currently, if not supplied it will default to 1. However, it has been found in practice that most programs will raise this limit to something higher, perhaps 3 or 4. Therefore, a future version of this module may set a higher value.

To test if your application will handle this correctly, you can set a different default by setting an environment variable:

   $ NET_ASYNC_HTTP_MAXCONNS=3 perl ...

timeout => NUM

stall_timeout => NUM

proxy_host => STRING

proxy_port => INT

cookie_jar => HTTP::Cookies

pipeline => BOOL

close_after_request => BOOL

Optional. If true, will set the "Connection: close" header on outgoing requests and disable pipelining, thus making every request use a new connection.

family => INT

local_host => STRING

local_port => INT

local_addrs => ARRAY

local_addr => HASH or ARRAY

fail_on_error => BOOL

The HTTP response and request objects will be passed as well as the code and message, and the failure name will be "http".

   ( $code_message, "http", $response, $request ) = $f->failure

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

read_len => INT

write_len => INT

ip_tos => INT or STRING

decode_content => BOOL

Currently the default is false, because this behaviour is new, but it may default to true in a later version. Applications which care which behaviour applies should set this to a defined value to ensure it doesn't change.

SSL_*

require_SSL => BOOL

SOCKS_*

Additionally, any parameters whose names start with "SOCKS_" will be stored and used by Net::Async::SOCKS to establish connections via a configured proxy.

do_request

   $response = await $http->do_request( %args );

Send an HTTP request to a server, returning a Future that will yield the response. 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

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.

family => INT

Optional. Restricts the socket family for connecting. If not defined, will default to the globally-configured value in the object.

SSL => BOOL

Optional. If true, an SSL connection will be used.

The following named arguments are used for "URI" requests:

uri => URI or STRING

A reference to a "URI" object, or a plain string giving the request URI. If the scheme is "https" then an SSL connection will be used.

method => STRING

Optional. The HTTP method name. If missing, "GET" is used.

content => STRING or ARRAY ref

Optional. The body content to use for "PUT" or "POST" requests.

If this is a plain scalar it will be used directly, and a "content_type" field must also be supplied to describe it.

If this is an ARRAY ref and the request method is "POST", it will be form encoded. It should contain an even-sized list of field names and values. For more detail see "POST" in HTTP::Request::Common.

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.

headers => ARRAY|HASH

Optional. If provided, contains additional HTTP headers to set on the constructed request object. If provided as an ARRAY reference, it should contain an even-sized list of name/value pairs.

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

request_body => STRING | CODE | Future

Optional. Allows request body content to be generated by a future or callback, rather than being provided as part of the "request" object. This can either be a plain string, a "CODE" reference to a generator function, or a future.

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. If passed a "Future" it is expected to eventually yield the body value.

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.

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.

on_ready => CODE

Optional. A callback that is invoked once a socket connection is established with the HTTP server, but before the request is actually sent over it. This may be used by the client code to inspect the socket, or perform any other operations on it. This code is expected to return a "Future"; only once that has completed will the request cycle continue. If it fails, that failure is propagated to the caller.

   $f = $on_ready->( $connection )
    

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 )
    

on_body_write => CODE

Optional. A callback that is invoked after each successful "syswrite" of the body content. This may be used to implement an upload progress indicator or similar. It will be passed the total number of bytes of body content written so far (i.e. excluding bytes consumed in the header).

   $on_body_write->( $written )
    

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.

On a timeout, the returned future will fail with either "timeout" or "stall_timeout" as the operation name.

   ( $message, "timeout" ) = $f->failure
    

do_request (void)

   $http->do_request( %args )

When not returning a future, the following extra arguments are used as callbacks instead:

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, and whatever it returns will be used as the result of the returned "Future", if there is one.

   $on_body_chunk = $on_header->( $header )

      $on_body_chunk->( $data )
      $response = $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 )
    

GET, HEAD, PUT, ...

   $response = await $http->GET( $uri, %args );

   $response = await $http->HEAD( $uri, %args );

   $response = await $http->PUT( $uri, $content, %args );

   $response = await $http->POST( $uri, $content, %args );

   $response = await $http->PATCH( $uri, $content, %args );

Convenient wrappers for performing "GET", "HEAD", "PUT", "POST" or "PATCH" requests with a "URI" object and few if any other arguments, returning a "Future".

Remember that "POST" with non-form data (as indicated by a plain scalar instead of an "ARRAY" reference of form data name/value pairs) needs a "content_type" key in %args.

prepare_request

   $http->prepare_request( $request )

Called just before the "HTTP::Request" object is sent to the server.

process_response

   $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.

register_decoder

   Net::Async::HTTP->register_decoder( $name, $q, $make_decoder )

Registers an encoding type called $name, at the quality value $q. In order to decode this encoding type, $make_decoder will be invoked with no paramters, and expected to return a CODE reference to perform one instance of decoding.

   $decoder = $make_decoder->()

This decoder will be invoked on string buffers to decode them until the end of stream is reached, when it will be invoked with no arguments.

   $content = $decoder->( $encoded_content )
   $content = $decoder->() # EOS

Concurrent GET

   use Future::AsyncAwait;
   use Future::Utils qw( fmap_void );

   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,
     concurrent => 5;

   await $future;