1HTTP(3) User Contributed Perl Documentation HTTP(3)
2
6 AnyEvent::HTTP - simple but non-blocking HTTP/HTTPS client
7
9 use AnyEvent::HTTP;
10 http_get "http://www.nethype.de/", sub { print $_[1] };
12 # ... do something else here
14
16 This module is an AnyEvent user, you need to make sure that you use and
17 run a supported event loop.
18 This module implements a simple, stateless and non-blocking HTTP
20 client. It supports GET, POST and other request methods, cookies and
21 more, all on a very low level. It can follow redirects supports proxies
22 and automatically limits the number of connections to the values
23 specified in the RFC.
24 It should generally be a "good client" that is enough for most HTTP
26 tasks. Simple tasks should be simple, but complex tasks should still be
27 possible as the user retains control over request and response headers.
28 The caller is responsible for authentication management, cookies (if
30 the simplistic implementation in this module doesn't suffice), referer
31 and other high-level protocol details for which this module offers only
32 limited support.
33 METHODS
35 http_get $url, key => value..., $cb->($data, $headers)
36 Executes an HTTP-GET request. See the http_request function for
37 details on additional parameters and the return value.
38 http_head $url, key => value..., $cb->($data, $headers)
40 Executes an HTTP-HEAD request. See the http_request function for
41 details on additional parameters and the return value.
42 http_post $url, $body, key => value..., $cb->($data, $headers)
44 Executes an HTTP-POST request with a request body of $body. See the
45 http_request function for details on additional parameters and the
46 return value.
47 http_request $method => $url, key => value..., $cb->($data, $headers)
49 Executes a HTTP request of type $method (e.g. "GET", "POST"). The
50 URL must be an absolute http or https URL.
51 When called in void context, nothing is returned. In other
53 contexts, "http_request" returns a "cancellation guard" - you have
54 to keep the object at least alive until the callback get called. If
55 the object gets destroyed before the callbakc is called, the
56 request will be cancelled.
57 The callback will be called with the response body data as first
59 argument (or "undef" if an error occured), and a hash-ref with
60 response headers as second argument.
61 All the headers in that hash are lowercased. In addition to the
63 response headers, the "pseudo-headers" (uppercase to avoid clashing
64 with possible response headers) "HTTPVersion", "Status" and
65 "Reason" contain the three parts of the HTTP Status-Line of the
66 same name.
67 The pseudo-header "URL" contains the actual URL (which can differ
69 from the requested URL when following redirects - for example, you
70 might get an error that your URL scheme is not supported even
71 though your URL is a valid http URL because it redirected to an ftp
72 URL, in which case you can look at the URL pseudo header).
73 The pseudo-header "Redirect" only exists when the request was a
75 result of an internal redirect. In that case it is an array
76 reference with the "($data, $headers)" from the redirect response.
77 Note that this response could in turn be the result of a redirect
78 itself, and "$headers->{Redirect}[1]{Redirect}" will then contain
79 the original response, and so on.
80 If the server sends a header multiple times, then their contents
82 will be joined together with a comma (","), as per the HTTP spec.
83 If an internal error occurs, such as not being able to resolve a
85 hostname, then $data will be "undef", "$headers->{Status}" will be
86 "59x" (usually 599) and the "Reason" pseudo-header will contain an
87 error message.
88 A typical callback might look like this:
90 sub {
92 my ($body, $hdr) = @_;
93 if ($hdr->{Status} =~ /^2/) {
95 ... everything should be ok
96 } else {
97 print "error, $hdr->{Status} $hdr->{Reason}\n";
98 }
99 }
100 Additional parameters are key-value pairs, and are fully optional.
102 They include:
103 recurse => $count (default: $MAX_RECURSE)
105 Whether to recurse requests or not, e.g. on redirects,
106 authentication retries and so on, and how often to do so.
107 headers => hashref
109 The request headers to use. Currently, "http_request" may
110 provide its own "Host:", "Content-Length:", "Connection:" and
111 "Cookie:" headers and will provide defaults for "User-Agent:"
112 and "Referer:" (this can be suppressed by using "undef" for
113 these headers in which case they won't be sent at all).
114 timeout => $seconds
116 The time-out to use for various stages - each connect attempt
117 will reset the timeout, as will read or write activity, i.e.
118 this is not an overall timeout.
119 Default timeout is 5 minutes.
121 proxy => [$host, $port[, $scheme]] or undef
123 Use the given http proxy for all requests. If not specified,
124 then the default proxy (as specified by $ENV{http_proxy}) is
125 used.
126 $scheme must be either missing, "http" for HTTP or "https" for
128 HTTPS.
129 body => $string
131 The request body, usually empty. Will be-sent as-is (future
132 versions of this module might offer more options).
133 cookie_jar => $hash_ref
135 Passing this parameter enables (simplified) cookie-processing,
136 loosely based on the original netscape specification.
137 The $hash_ref must be an (initially empty) hash reference which
139 will get updated automatically. It is possible to save the
140 cookie_jar to persistent storage with something like JSON or
141 Storable, but this is not recommended, as expiry times are
142 currently being ignored.
143 Note that this cookie implementation is not of very high
145 quality, nor meant to be complete. If you want complete cookie
146 management you have to do that on your own. "cookie_jar" is
147 meant as a quick fix to get some cookie-using sites working.
148 Cookies are a privacy disaster, do not use them unless required
149 to.
150 tls_ctx => $scheme | $tls_ctx
152 Specifies the AnyEvent::TLS context to be used for https
153 connections. This parameter follows the same rules as the
154 "tls_ctx" parameter to AnyEvent::Handle, but additionally, the
155 two strings "low" or "high" can be specified, which give you a
156 predefined low-security (no verification, highest
157 compatibility) and high-security (CA and common-name
158 verification) TLS context.
159 The default for this option is "low", which could be
161 interpreted as "give me the page, no matter what".
162 on_prepare => $callback->($fh)
164 In rare cases you need to "tune" the socket before it is used
165 to connect (for exmaple, to bind it on a given IP address).
166 This parameter overrides the prepare callback passed to
167 "AnyEvent::Socket::tcp_connect" and behaves exactly the same
168 way (e.g. it has to provide a timeout). See the description for
169 the $prepare_cb argument of "AnyEvent::Socket::tcp_connect" for
170 details.
171 on_header => $callback->($headers)
173 When specified, this callback will be called with the header
174 hash as soon as headers have been successfully received from
175 the remote server (not on locally-generated errors).
176 It has to return either true (in which case AnyEvent::HTTP will
178 continue), or false, in which case AnyEvent::HTTP will cancel
179 the download (and call the finish callback with an error code
180 of 598).
181 This callback is useful, among other things, to quickly reject
183 unwanted content, which, if it is supposed to be rare, can be
184 faster than first doing a "HEAD" request.
185 Example: cancel the request unless the content-type is
187 "text/html".
188 on_header => sub {
190 $_[0]{"content-type"} =~ /^text\/html\s*(?:;|$)/
191 },
192 on_body => $callback->($partial_body, $headers)
194 When specified, all body data will be passed to this callback
195 instead of to the completion callback. The completion callback
196 will get the empty string instead of the body data.
197 It has to return either true (in which case AnyEvent::HTTP will
199 continue), or false, in which case AnyEvent::HTTP will cancel
200 the download (and call the completion callback with an error
201 code of 598).
202 This callback is useful when the data is too large to be held
204 in memory (so the callback writes it to a file) or when only
205 some information should be extracted, or when the body should
206 be processed incrementally.
207 It is usually preferred over doing your own body handling via
209 "want_body_handle", but in case of streaming APIs, where HTTP
210 is only used to create a connection, "want_body_handle" is the
211 better alternative, as it allows you to install your own event
212 handler, reducing resource usage.
213 want_body_handle => $enable
215 When enabled (default is disabled), the behaviour of
216 AnyEvent::HTTP changes considerably: after parsing the headers,
217 and instead of downloading the body (if any), the completion
218 callback will be called. Instead of the $body argument
219 containing the body data, the callback will receive the
220 AnyEvent::Handle object associated with the connection. In
221 error cases, "undef" will be passed. When there is no body
222 (e.g. status 304), the empty string will be passed.
223 The handle object might or might not be in TLS mode, might be
225 connected to a proxy, be a persistent connection etc., and
226 configured in unspecified ways. The user is responsible for
227 this handle (it will not be used by this module anymore).
228 This is useful with some push-type services, where, after the
230 initial headers, an interactive protocol is used (typical
231 example would be the push-style twitter API which starts a
232 JSON/XML stream).
233 If you think you need this, first have a look at "on_body", to
235 see if that doesn't solve your problem in a better way.
236 Example: make a simple HTTP GET request for http://www.nethype.de/
238 http_request GET => "http://www.nethype.de/", sub {
240 my ($body, $hdr) = @_;
241 print "$body\n";
242 };
243 Example: make a HTTP HEAD request on https://www.google.com/, use a
245 timeout of 30 seconds.
246 http_request
248 GET => "https://www.google.com",
249 timeout => 30,
250 sub {
251 my ($body, $hdr) = @_;
252 use Data::Dumper;
253 print Dumper $hdr;
254 }
255 ;
256 Example: make another simple HTTP GET request, but immediately try
258 to cancel it.
259 my $request = http_request GET => "http://www.nethype.de/", sub {
261 my ($body, $hdr) = @_;
262 print "$body\n";
263 };
264 undef $request;
266 DNS CACHING
268 AnyEvent::HTTP uses the AnyEvent::Socket::tcp_connect function for the
269 actual connection, which in turn uses AnyEvent::DNS to resolve
270 hostnames. The latter is a simple stub resolver and does no caching on
271 its own. If you want DNS caching, you currently have to provide your
272 own default resolver (by storing a suitable resolver object in
273 $AnyEvent::DNS::RESOLVER).
274 GLOBAL FUNCTIONS AND VARIABLES
276 AnyEvent::HTTP::set_proxy "proxy-url"
277 Sets the default proxy server to use. The proxy-url must begin with
278 a string of the form "http://host:port" (optionally "https:..."),
279 croaks otherwise.
280 To clear an already-set proxy, use "undef".
282 $AnyEvent::HTTP::MAX_RECURSE
284 The default value for the "recurse" request parameter (default:
285 10).
286 $AnyEvent::HTTP::USERAGENT
288 The default value for the "User-Agent" header (the default is
289 "Mozilla/5.0 (compatible; U; AnyEvent-HTTP/$VERSION;
290 +http://software.schmorp.de/pkg/AnyEvent)").
291 $AnyEvent::HTTP::MAX_PER_HOST
293 The maximum number of concurrent connections to the same host
294 (identified by the hostname). If the limit is exceeded, then the
295 additional requests are queued until previous connections are
296 closed.
297 The default value for this is 4, and it is highly advisable to not
299 increase it.
300 $AnyEvent::HTTP::ACTIVE
302 The number of active connections. This is not the number of
303 currently running requests, but the number of currently open and
304 non-idle TCP connections. This number of can be useful for load-
305 leveling.
306
308 AnyEvent.
309
311 Marc Lehmann <schmorp@schmorp.de>
312 http://home.schmorp.de/
313 With many thanks to D‐XD‐XD‐XN~XN~XD‐XD‐X D‐XD‐XD‐XD‐XN~XD‐XD‐X, who provided
315 countless testcases and bugreports.
316perl v5.12.2 2010-09-06 HTTP(3)