.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Net::Async::HTTP 3pm" .TH Net::Async::HTTP 3pm "2021-03-12" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" "Net::Async::HTTP" \- use HTTP with "IO::Async" .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Future::AsyncAwait; \& \& 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 = await $http\->do_request( \& uri => URI\->new( "http://www.cpan.org/" ), \& ); \& \& print "Front page of http://www.cpan.org/ is:\en"; \& print $response\->as_string; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This object class implements an asynchronous \s-1HTTP\s0 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. .PP As well as using futures the module also supports a callback-based interface. .PP This module optionally supports \s-1SSL\s0 connections, if IO::Async::SSL is installed. If so, \s-1SSL\s0 can be requested either by passing a \s-1URI\s0 with the \&\f(CW\*(C`https\*(C'\fR scheme, or by passing a true value as the \f(CW\*(C`SSL\*(C'\fR parameter. .SS "Connection Pooling" .IX Subsection "Connection Pooling" There are three ways in which connections to \s-1HTTP\s0 server hosts are managed by this object, controlled by the value of \f(CW\*(C`max_connections_per_host\*(C'\fR. 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. .PP They are: .IP "max_connections_per_host = 1" 2 .IX Item "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. .Sp If pipelining is active on the connection (because both the \f(CW\*(C`pipeline\*(C'\fR option is true and the connection is known to be an \s-1HTTP/1.1\s0 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. .IP "max_connections_per_host > 1" 2 .IX Item "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. .IP "max_connections_per_host = 0" 2 .IX Item "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. .PP 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. .SH "PARAMETERS" .IX Header "PARAMETERS" The following named parameters may be passed to \f(CW\*(C`new\*(C'\fR or \f(CW\*(C`configure\*(C'\fR: .SS "user_agent => \s-1STRING\s0" .IX Subsection "user_agent => STRING" A string to set in the \f(CW\*(C`User\-Agent\*(C'\fR \s-1HTTP\s0 header. If not supplied, one will be constructed that declares \f(CW\*(C`Net::Async::HTTP\*(C'\fR and the version number. .SS "headers => \s-1ARRAY\s0 or \s-1HASH\s0" .IX Subsection "headers => ARRAY or HASH" \&\fISince version 0.45.\fR .PP 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. .PP Individual header values may be added or changed without replacing the entire set by using the configure method and passing a key called \f(CW\*(C`+headers\*(C'\fR: .PP .Vb 1 \& $http\->configure( +headers => { One_More => "Key" } ); .Ve .SS "max_redirects => \s-1INT\s0" .IX Subsection "max_redirects => INT" Optional. How many levels of redirection to follow. If not supplied, will default to 3. Give 0 to disable redirection entirely. .SS "max_in_flight => \s-1INT\s0" .IX Subsection "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. .SS "max_connections_per_host => \s-1INT\s0" .IX Subsection "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. Give 0 to disable the limit entirely. See also the \*(L"Connection Pooling\*(R" section documented above. .PP 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. .PP To test if your application will handle this correctly, you can set a different default by setting an environment variable: .PP .Vb 1 \& $ NET_ASYNC_HTTP_MAXCONNS=3 perl ... .Ve .SS "timeout => \s-1NUM\s0" .IX Subsection "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. .SS "stall_timeout => \s-1NUM\s0" .IX Subsection "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 \&\f(CW\*(C`timeout\*(C'\fR on large-file operations, as it will not time out provided that regular progress is still being made. .SS "proxy_host => \s-1STRING\s0" .IX Subsection "proxy_host => STRING" .SS "proxy_port => \s-1INT\s0" .IX Subsection "proxy_port => INT" Optional. Default values to apply to each \f(CW\*(C`request\*(C'\fR method. .SS "cookie_jar => HTTP::Cookies" .IX Subsection "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. .SS "pipeline => \s-1BOOL\s0" .IX Subsection "pipeline => BOOL" Optional. If false, disables \s-1HTTP/1\s0.1\-style request pipelining. .SS "close_after_request => \s-1BOOL\s0" .IX Subsection "close_after_request => BOOL" \&\fISince version 0.45.\fR .PP Optional. If true, will set the \f(CW\*(C`Connection: close\*(C'\fR header on outgoing requests and disable pipelining, thus making every request use a new connection. .SS "family => \s-1INT\s0" .IX Subsection "family => INT" .SS "local_host => \s-1STRING\s0" .IX Subsection "local_host => STRING" .SS "local_port => \s-1INT\s0" .IX Subsection "local_port => INT" .SS "local_addrs => \s-1ARRAY\s0" .IX Subsection "local_addrs => ARRAY" .SS "local_addr => \s-1HASH\s0 or \s-1ARRAY\s0" .IX Subsection "local_addr => HASH or ARRAY" Optional. Parameters to pass on to the \f(CW\*(C`connect\*(C'\fR method used to connect sockets to \s-1HTTP\s0 servers. Sets the socket family and local socket address to \&\f(CW\*(C`bind()\*(C'\fR to. For more detail, see the documentation in IO::Async::Connector. .SS "fail_on_error => \s-1BOOL\s0" .IX Subsection "fail_on_error => BOOL" Optional. Affects the behaviour of response handling when a \f(CW\*(C`4xx\*(C'\fR or \f(CW\*(C`5xx\*(C'\fR 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 \&\f(CW\*(C`on_response\*(C'\fR callback. When true, such an error response causes the future to fail, or the \f(CW\*(C`on_error\*(C'\fR callback to be invoked. .PP The \s-1HTTP\s0 response and request objects will be passed as well as the code and message, and the failure name will be \f(CW\*(C`http\*(C'\fR. .PP .Vb 1 \& ( $code_message, "http", $response, $request ) = $f\->failure \& \& $on_error\->( "$code $message", $response, $request ) .Ve .SS "read_len => \s-1INT\s0" .IX Subsection "read_len => INT" .SS "write_len => \s-1INT\s0" .IX Subsection "write_len => INT" Optional. Used to set the reading and writing buffer lengths on the underlying \&\f(CW\*(C`IO::Async::Stream\*(C'\fR objects that represent connections to the server. If not define, a default of 64 KiB will be used. .SS "ip_tos => \s-1INT\s0 or \s-1STRING\s0" .IX Subsection "ip_tos => INT or STRING" Optional. Used to set the \f(CW\*(C`IP_TOS\*(C'\fR socket option on client sockets. If given, should either be a \f(CW\*(C`IPTOS_*\*(C'\fR constant, or one of the string names \&\f(CW\*(C`lowdelay\*(C'\fR, \f(CW\*(C`throughput\*(C'\fR, \f(CW\*(C`reliability\*(C'\fR or \f(CW\*(C`mincost\*(C'\fR. If undefined or left absent, no option will be set. .SS "decode_content => \s-1BOOL\s0" .IX Subsection "decode_content => BOOL" Optional. If true, incoming responses that have a recognised \&\f(CW\*(C`Content\-Encoding\*(C'\fR are handled by the module, and decompressed content is passed to the body handling callback or returned in the \f(CW\*(C`HTTP::Response\*(C'\fR. See \&\*(L"\s-1CONTENT DECODING\*(R"\s0 below for details of which encoding types are recognised. When this option is enabled, outgoing requests also have the \&\f(CW\*(C`Accept\-Encoding\*(C'\fR header added to them if it does not already exist. .PP 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. .SS "SSL_*" .IX Subsection "SSL_*" Additionally, any parameters whose names start with \f(CW\*(C`SSL_\*(C'\fR will be stored and passed on requests to perform \s-1SSL\s0 requests. This simplifies configuration of common \s-1SSL\s0 parameters. .SS "require_SSL => \s-1BOOL\s0" .IX Subsection "require_SSL => BOOL" Optional. If true, then any attempt to make a request that does not use \s-1SSL\s0 (either by calling \f(CW\*(C`request\*(C'\fR, or as a result of a redirection) will immediately fail. .SS "SOCKS_*" .IX Subsection "SOCKS_*" \&\fISince version 0.42.\fR .PP Additionally, any parameters whose names start with \f(CW\*(C`SOCKS_\*(C'\fR will be stored and used by Net::Async::SOCKS to establish connections via a configured proxy. .SH "METHODS" .IX Header "METHODS" The following methods documented in an \f(CW\*(C`await\*(C'\fR expression return Future instances. .PP When returning a Future, the following methods all indicate HTTP-level errors using the Future failure name of \f(CW\*(C`http\*(C'\fR. If the error relates to a specific response it will be included. The original request is also included. .PP .Vb 1 \& $f\->fail( $message, "http", $response, $request ) .Ve .SS "do_request" .IX Subsection "do_request" .Vb 1 \& $response = await $http\->do_request( %args ); .Ve .PP Send an \s-1HTTP\s0 request to a server, returning a Future that will yield the response. The request may be represented by an HTTP::Request object, or a \&\s-1URI\s0 object, depending on the arguments passed. .PP The following named arguments are used for \f(CW\*(C`HTTP::Request\*(C'\fRs: .IP "request => HTTP::Request" 8 .IX Item "request => HTTP::Request" A reference to an \f(CW\*(C`HTTP::Request\*(C'\fR object .IP "host => \s-1STRING\s0" 8 .IX Item "host => STRING" Hostname of the server to connect to .IP "port => \s-1INT\s0 or \s-1STRING\s0" 8 .IX Item "port => INT or STRING" Optional. Port number or service of the server to connect to. If not defined, will default to \f(CW\*(C`http\*(C'\fR or \f(CW\*(C`https\*(C'\fR depending on whether \s-1SSL\s0 is being used. .IP "family => \s-1INT\s0" 8 .IX Item "family => INT" Optional. Restricts the socket family for connecting. If not defined, will default to the globally-configured value in the object. .IP "\s-1SSL\s0 => \s-1BOOL\s0" 8 .IX Item "SSL => BOOL" Optional. If true, an \s-1SSL\s0 connection will be used. .PP The following named arguments are used for \f(CW\*(C`URI\*(C'\fR requests: .IP "uri => \s-1URI\s0 or \s-1STRING\s0" 8 .IX Item "uri => URI or STRING" A reference to a \f(CW\*(C`URI\*(C'\fR object, or a plain string giving the request \s-1URI.\s0 If the scheme is \f(CW\*(C`https\*(C'\fR then an \s-1SSL\s0 connection will be used. .IP "method => \s-1STRING\s0" 8 .IX Item "method => STRING" Optional. The \s-1HTTP\s0 method name. If missing, \f(CW\*(C`GET\*(C'\fR is used. .IP "content => \s-1STRING\s0 or \s-1ARRAY\s0 ref" 8 .IX Item "content => STRING or ARRAY ref" Optional. The body content to use for \f(CW\*(C`PUT\*(C'\fR or \f(CW\*(C`POST\*(C'\fR requests. .Sp If this is a plain scalar it will be used directly, and a \f(CW\*(C`content_type\*(C'\fR field must also be supplied to describe it. .Sp If this is an \s-1ARRAY\s0 ref and the request method is \f(CW\*(C`POST\*(C'\fR, it will be form encoded. It should contain an even-sized list of field names and values. For more detail see \*(L"\s-1POST\*(R"\s0 in HTTP::Request::Common. .IP "content_type => \s-1STRING\s0" 8 .IX Item "content_type => STRING" The type of non-form data \f(CW\*(C`content\*(C'\fR. .IP "user => \s-1STRING\s0" 8 .IX Item "user => STRING" .PD 0 .IP "pass => \s-1STRING\s0" 8 .IX Item "pass => STRING" .PD Optional. If both are given, the \s-1HTTP\s0 Basic Authorization header will be sent with these details. .IP "headers => ARRAY|HASH" 8 .IX Item "headers => ARRAY|HASH" Optional. If provided, contains additional \s-1HTTP\s0 headers to set on the constructed request object. If provided as an \s-1ARRAY\s0 reference, it should contain an even-sized list of name/value pairs. .IP "proxy_host => \s-1STRING\s0" 8 .IX Item "proxy_host => STRING" .PD 0 .IP "proxy_port => \s-1INT\s0" 8 .IX Item "proxy_port => INT" .PD Optional. Override the hostname or port number implied by the \s-1URI.\s0 .PP For either request type, it takes the following arguments: .IP "request_body => \s-1STRING\s0 | \s-1CODE\s0 | Future" 8 .IX Item "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 \f(CW\*(C`request\*(C'\fR object. This can either be a plain string, a \f(CW\*(C`CODE\*(C'\fR reference to a generator function, or a future. .Sp As this is passed to the underlying IO::Async::Stream \f(CW\*(C`write\*(C'\fR method, the usual semantics apply here. If passed a \f(CW\*(C`CODE\*(C'\fR reference, it will be called repeatedly whenever it's safe to write. The code should should return \f(CW\*(C`undef\*(C'\fR to indicate completion. If passed a \f(CW\*(C`Future\*(C'\fR it is expected to eventually yield the body value. .Sp As with the \f(CW\*(C`content\*(C'\fR parameter, the \f(CW\*(C`content_type\*(C'\fR field should be specified explicitly in the request header, as should the content length (typically via the HTTP::Request \f(CW\*(C`content_length\*(C'\fR method). See also \&\fIexamples/PUT.pl\fR. .IP "expect_continue => \s-1BOOL\s0" 8 .IX Item "expect_continue => BOOL" Optional. If true, sets the \f(CW\*(C`Expect\*(C'\fR request header to the value \&\f(CW\*(C`100\-continue\*(C'\fR and does not send the \f(CW\*(C`request_body\*(C'\fR parameter until a \&\f(CW\*(C`100 Continue\*(C'\fR response is received from the server. If an error response is received then the \f(CW\*(C`request_body\*(C'\fR code, if present, will not be invoked. .IP "on_ready => \s-1CODE\s0" 8 .IX Item "on_ready => CODE" Optional. A callback that is invoked once a socket connection is established with the \s-1HTTP\s0 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 \f(CW\*(C`Future\*(C'\fR; only once that has completed will the request cycle continue. If it fails, that failure is propagated to the caller. .Sp .Vb 1 \& $f = $on_ready\->( $connection ) .Ve .IP "on_redirect => \s-1CODE\s0" 8 .IX Item "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 \&\s-1URL.\s0 .Sp .Vb 1 \& $on_redirect\->( $response, $location ) .Ve .IP "on_body_write => \s-1CODE\s0" 8 .IX Item "on_body_write => CODE" Optional. A callback that is invoked after each successful \f(CW\*(C`syswrite\*(C'\fR 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). .Sp .Vb 1 \& $on_body_write\->( $written ) .Ve .IP "max_redirects => \s-1INT\s0" 8 .IX Item "max_redirects => INT" Optional. How many levels of redirection to follow. If not supplied, will default to the value given in the constructor. .IP "timeout => \s-1NUM\s0" 8 .IX Item "timeout => NUM" .PD 0 .IP "stall_timeout => \s-1NUM\s0" 8 .IX Item "stall_timeout => NUM" .PD Optional. Overrides the object's configured timeout values for this one request. If not specified, will use the configured defaults. .Sp On a timeout, the returned future will fail with either \f(CW\*(C`timeout\*(C'\fR or \&\f(CW\*(C`stall_timeout\*(C'\fR as the operation name. .Sp .Vb 1 \& ( $message, "timeout" ) = $f\->failure .Ve .SS "do_request (void)" .IX Subsection "do_request (void)" .Vb 1 \& $http\->do_request( %args ) .Ve .PP When not returning a future, the following extra arguments are used as callbacks instead: .IP "on_response => \s-1CODE\s0" 8 .IX Item "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. .Sp .Vb 1 \& $on_response\->( $response ) .Ve .IP "on_header => \s-1CODE\s0" 8 .IX Item "on_header => CODE" Alternative to \f(CW\*(C`on_response\*(C'\fR. A callback that is invoked when the header of a response has been received. It is expected to return a \f(CW\*(C`CODE\*(C'\fR reference for handling chunks of body content. This \f(CW\*(C`CODE\*(C'\fR 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 \f(CW\*(C`Future\*(C'\fR, if there is one. .Sp .Vb 1 \& $on_body_chunk = $on_header\->( $header ) \& \& $on_body_chunk\->( $data ) \& $response = $on_body_chunk\->() .Ve .IP "on_error => \s-1CODE\s0" 8 .IX Item "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. .Sp .Vb 1 \& $on_error\->( $message ) .Ve .Sp If this is invoked because of a received \f(CW\*(C`4xx\*(C'\fR or \f(CW\*(C`5xx\*(C'\fR error code in an \&\s-1HTTP\s0 response, it will be invoked with the response and request objects as well. .Sp .Vb 1 \& $on_error\->( $message, $response, $request ) .Ve .SS "\s-1GET, HEAD, PUT, ...\s0" .IX Subsection "GET, HEAD, PUT, ..." .Vb 1 \& $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 ); .Ve .PP Convenient wrappers for performing \f(CW\*(C`GET\*(C'\fR, \f(CW\*(C`HEAD\*(C'\fR, \f(CW\*(C`PUT\*(C'\fR, \f(CW\*(C`POST\*(C'\fR or \&\f(CW\*(C`PATCH\*(C'\fR requests with a \f(CW\*(C`URI\*(C'\fR object and few if any other arguments, returning a \f(CW\*(C`Future\*(C'\fR. .PP Remember that \f(CW\*(C`POST\*(C'\fR with non-form data (as indicated by a plain scalar instead of an \f(CW\*(C`ARRAY\*(C'\fR reference of form data name/value pairs) needs a \&\f(CW\*(C`content_type\*(C'\fR key in \f(CW%args\fR. .SH "SUBCLASS METHODS" .IX Header "SUBCLASS METHODS" The following methods are intended as points for subclasses to override, to add extra functionallity. .SS "prepare_request" .IX Subsection "prepare_request" .Vb 1 \& $http\->prepare_request( $request ) .Ve .PP Called just before the \f(CW\*(C`HTTP::Request\*(C'\fR object is sent to the server. .SS "process_response" .IX Subsection "process_response" .Vb 1 \& $http\->process_response( $response ) .Ve .PP Called after a non-redirect \f(CW\*(C`HTTP::Response\*(C'\fR has been received from a server. The originating request will be set in the object. .SH "CONTENT DECODING" .IX Header "CONTENT DECODING" If the required decompression modules are installed and available, compressed content can be decoded. If the received \f(CW\*(C`Content\-Encoding\*(C'\fR is recognised and the required module is available, the content is transparently decoded and the decoded content is returned in the resulting response object, or passed to the data chunk handler. In this case, the original \f(CW\*(C`Content\-Encoding\*(C'\fR header will be deleted from the response, and its value will be available instead as \&\f(CW\*(C`X\-Original\-Content\-Encoding\*(C'\fR. .PP The following content encoding types are recognised by these modules: .IP "\(bu" 4 gzip (q=0.7) and deflate (q=0.5) .Sp Recognised if Compress::Raw::Zlib version 2.057 or newer is installed. .IP "\(bu" 4 bzip2 (q=0.8) .Sp Recognised if Compress::Bzip2 version 2.10 or newer is installed. .PP Other content encoding types can be registered by calling the following method .SS "register_decoder" .IX Subsection "register_decoder" .Vb 1 \& Net::Async::HTTP\->register_decoder( $name, $q, $make_decoder ) .Ve .PP Registers an encoding type called \f(CW$name\fR, at the quality value \f(CW$q\fR. In order to decode this encoding type, \f(CW$make_decoder\fR will be invoked with no paramters, and expected to return a \s-1CODE\s0 reference to perform one instance of decoding. .PP .Vb 1 \& $decoder = $make_decoder\->() .Ve .PP 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. .PP .Vb 2 \& $content = $decoder\->( $encoded_content ) \& $content = $decoder\->() # EOS .Ve .SH "EXAMPLES" .IX Header "EXAMPLES" .SS "Concurrent \s-1GET\s0" .IX Subsection "Concurrent GET" The \f(CW\*(C`Future\*(C'\fR\-returning \f(CW\*(C`GET\*(C'\fR method makes it easy to await multiple URLs at once, by using the Future::Utils \f(CW\*(C`fmap_void\*(C'\fR utility .PP .Vb 2 \& 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 => \e@URLs, \& concurrent => 5; \& \& await $future; .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 \- Hypertext Transfer Protocol \*(-- \s-1HTTP/1.1\s0 .SH "SPONSORS" .IX Header "SPONSORS" Parts of this code, or bugfixes to it were paid for by .IP "\(bu" 2 SocialFlow .IP "\(bu" 2 Shadowcat Systems .IP "\(bu" 2 NET-A-PORTER .IP "\(bu" 2 Cisco .SH "AUTHOR" .IX Header "AUTHOR" Paul Evans