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 );

     my ( $response ) = $http->do_request(
        uri => URI->new( "http://www.cpan.org/" ),
     )->get;

     print "Front page of http://www.cpan.org/ is:\n";
     print $response->as_string;

DESCRIPTION
    This object class implements an asynchronous HTTP user agent. It sends
    requests to servers, returning Future instances to yield responses when
    they 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.

    As well as using futures the module also supports a callback-based
    interface.

    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.

    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.

    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 yielded as
            the result of the future, or passed to the `on_response'
            callback. When true, such an error response causes the future to
            fail, or the `on_error' callback to be invoked.

            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
            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
    When returning a Future, the following methods all indicate HTTP-level
    errors using the Future failure name of `http'. If the error relates to
    a specific response it will be included. The original request is also
    included.

     $f->fail( $message, "http", $response, $request )

  $http->do_request( %args ) ==> $response
    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.

    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.

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

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

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

  $http->GET( $uri, %args ) ==> $response
  $http->HEAD( $uri, %args ) ==> $response
    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
    *   http://tools.ietf.org/html/rfc2616 - Hypertext Transfer Protocol --
        HTTP/1.1

SPONSORS
    Parts of this code were paid for by

    * Socialflow http://www.socialflow.com

    * Shadowcat Systems http://www.shadow.cat

AUTHOR
    Paul Evans <leonerd@leonerd.org.uk>

