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. 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. 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. 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 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 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 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 Optional. Specifies a timeout in seconds, after which to give up on the request and fail it with an error. If this happens, the error message will be `Timed out'. $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. my @URLs = ( ... ); my $http = Net::Async::HTTP->new( ... ); $loop->add( $http ); my $future = Future->wait_all( map { 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"; } ); } @URLs ); $loop->await( $future ); SEE ALSO * http://tools.ietf.org/html/rfc2616 - Hypertext Transfer Protocol -- HTTP/1.1 AUTHOR Paul Evans