ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-HTTP/HTTP.pm
(Generate patch)

Comparing AnyEvent-HTTP/HTTP.pm (file contents):
Revision 1.131 by root, Thu Aug 30 17:04:28 2018 UTC vs.
Revision 1.140 by root, Wed Mar 6 19:29:18 2024 UTC

… …
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use AnyEvent::HTTP; 7 use AnyEvent::HTTP;
8 8
9 http_get "http://www.nethype.de/", sub { print $_[1] }; 9 http_get "http://www.nethype.de/", sub {
10 my ($body, $hdr) = @_;
11 print "$hdr->{URL} Status: $hdr->{Status}\n";
12 print $body;
13 };
10 14
11 # ... do something else here 15 # ... do something else here
12 16
13=head1 DESCRIPTION 17=head1 DESCRIPTION
14 18
… …
46use AnyEvent::Util (); 50use AnyEvent::Util ();
47use AnyEvent::Handle (); 51use AnyEvent::Handle ();
48 52
49use base Exporter::; 53use base Exporter::;
50 54
51our $VERSION = 2.24; 55our $VERSION = 2.25;
52 56
53our @EXPORT = qw(http_get http_post http_head http_request); 57our @EXPORT = qw(http_get http_post http_head http_request);
54 58
55our $USERAGENT = "Mozilla/5.0 (compatible; U; AnyEvent-HTTP/$VERSION; +http://software.schmorp.de/pkg/AnyEvent)"; 59our $USERAGENT = "Mozilla/5.0 (compatible; U; AnyEvent-HTTP/$VERSION; +http://software.schmorp.de/pkg/AnyEvent)";
56our $MAX_RECURSE = 10; 60our $MAX_RECURSE = 10;
… …
198C<AnyEvent::HTTP::set_proxy>). 202C<AnyEvent::HTTP::set_proxy>).
199 203
200Currently, if your proxy requires authorization, you have to specify an 204Currently, if your proxy requires authorization, you have to specify an
201appropriate "Proxy-Authorization" header in every request. 205appropriate "Proxy-Authorization" header in every request.
202 206
207Note that this module will prefer an existing persistent connection,
208even if that connection was made using another proxy. If you need to
209ensure that a new connection is made in this case, you can either force
210C<persistent> to false or e.g. use the proxy address in your C<sessionid>.
211
203=item body => $string 212=item body => $string
204 213
205The request body, usually empty. Will be sent as-is (future versions of 214The request body, usually empty. Will be sent as-is (future versions of
206this module might offer more options). 215this module might offer more options).
207 216
… …
239The default for this option is C<low>, which could be interpreted as "give 248The default for this option is C<low>, which could be interpreted as "give
240me the page, no matter what". 249me the page, no matter what".
241 250
242See also the C<sessionid> parameter. 251See also the C<sessionid> parameter.
243 252
244=item session => $string 253=item sessionid => $string
245 254
246The module might reuse connections to the same host internally. Sometimes 255The module might reuse connections to the same host internally (regardless
247(e.g. when using TLS), you do not want to reuse connections from other 256of other settings, such as C<tcp_connect> or C<proxy>). Sometimes (e.g.
257when using TLS or a specfic proxy), you do not want to reuse connections
248sessions. This can be achieved by setting this parameter to some unique 258from other sessions. This can be achieved by setting this parameter to
249ID (such as the address of an object storing your state data, or the TLS 259some unique ID (such as the address of an object storing your state data
250context) - only connections using the same unique ID will be reused. 260or the TLS context, or the proxy IP) - only connections using the same
261unique ID will be reused.
251 262
252=item on_prepare => $callback->($fh) 263=item on_prepare => $callback->($fh)
253 264
254In rare cases you need to "tune" the socket before it is used to 265In rare cases you need to "tune" the socket before it is used to
255connect (for example, to bind it on a given IP address). This parameter 266connect (for example, to bind it on a given IP address). This parameter
… …
263In even rarer cases you want total control over how AnyEvent::HTTP 274In even rarer cases you want total control over how AnyEvent::HTTP
264establishes connections. Normally it uses L<AnyEvent::Socket::tcp_connect> 275establishes connections. Normally it uses L<AnyEvent::Socket::tcp_connect>
265to do this, but you can provide your own C<tcp_connect> function - 276to do this, but you can provide your own C<tcp_connect> function -
266obviously, it has to follow the same calling conventions, except that it 277obviously, it has to follow the same calling conventions, except that it
267may always return a connection guard object. 278may always return a connection guard object.
279
280The connections made by this hook will be treated as equivalent to
281connections made the built-in way, specifically, they will be put into
282and taken from the persistent connection cache. If your C<$tcp_connect>
283function is incompatible with this kind of re-use, consider switching off
284C<persistent> connections and/or providing a C<sessionid> identifier.
268 285
269There are probably lots of weird uses for this function, starting from 286There are probably lots of weird uses for this function, starting from
270tracing the hosts C<http_request> actually tries to connect, to (inexact 287tracing the hosts C<http_request> actually tries to connect, to (inexact
271but fast) host => IP address caching or even socks protocol support. 288but fast) host => IP address caching or even socks protocol support.
272 289
… …
342=item persistent => $boolean 359=item persistent => $boolean
343 360
344Try to create/reuse a persistent connection. When this flag is set 361Try to create/reuse a persistent connection. When this flag is set
345(default: true for idempotent requests, false for all others), then 362(default: true for idempotent requests, false for all others), then
346C<http_request> tries to re-use an existing (previously-created) 363C<http_request> tries to re-use an existing (previously-created)
347persistent connection to the host and, failing that, tries to create a new 364persistent connection to same host (i.e. identical URL scheme, hostname,
348one. 365port and sessionid) and, failing that, tries to create a new one.
349 366
350Requests failing in certain ways will be automatically retried once, which 367Requests failing in certain ways will be automatically retried once, which
351is dangerous for non-idempotent requests, which is why it defaults to off 368is dangerous for non-idempotent requests, which is why it defaults to off
352for them. The reason for this is because the bozos who designed HTTP/1.1 369for them. The reason for this is because the bozos who designed HTTP/1.1
353made it impossible to distinguish between a fatal error and a normal 370made it impossible to distinguish between a fatal error and a normal
354connection timeout, so you never know whether there was a problem with 371connection timeout, so you never know whether there was a problem with
355your request or not. 372your request or not.
356 373
357When reusing an existent connection, many parameters (such as TLS context) 374When reusing an existent connection, many parameters (such as TLS context)
358will be ignored. See the C<session> parameter for a workaround. 375will be ignored. See the C<sessionid> parameter for a workaround.
359 376
360=item keepalive => $boolean 377=item keepalive => $boolean
361 378
362Only used when C<persistent> is also true. This parameter decides whether 379Only used when C<persistent> is also true. This parameter decides whether
363C<http_request> tries to handshake a HTTP/1.0-style keep-alive connection 380C<http_request> tries to handshake a HTTP/1.0-style keep-alive connection
… …
703} 720}
704 721
705our %IDEMPOTENT = ( 722our %IDEMPOTENT = (
706 DELETE => 1, 723 DELETE => 1,
707 GET => 1, 724 GET => 1,
725 QUERY => 1,
708 HEAD => 1, 726 HEAD => 1,
709 OPTIONS => 1, 727 OPTIONS => 1,
710 PUT => 1, 728 PUT => 1,
711 TRACE => 1, 729 TRACE => 1,
712 730
… …
724 MKCOL => 1, 742 MKCOL => 1,
725 MKREDIRECTREF => 1, 743 MKREDIRECTREF => 1,
726 MKWORKSPACE => 1, 744 MKWORKSPACE => 1,
727 MOVE => 1, 745 MOVE => 1,
728 ORDERPATCH => 1, 746 ORDERPATCH => 1,
747 PRI => 1,
729 PROPFIND => 1, 748 PROPFIND => 1,
730 PROPPATCH => 1, 749 PROPPATCH => 1,
731 REBIND => 1, 750 REBIND => 1,
732 REPORT => 1, 751 REPORT => 1,
733 SEARCH => 1, 752 SEARCH => 1,
… …
1225# $state{handle}->destroyed 1244# $state{handle}->destroyed
1226# and die "AnyEvent::HTTP: unexpectedly got a destructed handle (1), please report.";#d# 1245# and die "AnyEvent::HTTP: unexpectedly got a destructed handle (1), please report.";#d#
1227 $prepare_handle->(); 1246 $prepare_handle->();
1228# $state{handle}->destroyed 1247# $state{handle}->destroyed
1229# and die "AnyEvent::HTTP: unexpectedly got a destructed handle (2), please report.";#d# 1248# and die "AnyEvent::HTTP: unexpectedly got a destructed handle (2), please report.";#d#
1249 $rpath = $upath;
1230 $handle_actual_request->(); 1250 $handle_actual_request->();
1231 1251
1232 } else { 1252 } else {
1233 my $tcp_connect = $arg{tcp_connect} 1253 my $tcp_connect = $arg{tcp_connect}
1234 || do { require AnyEvent::Socket; \&AnyEvent::Socket::tcp_connect }; 1254 || do { require AnyEvent::Socket; \&AnyEvent::Socket::tcp_connect };
… …
1309 1329
1310Here is an example of a cookie jar with a single cookie, so you have a 1330Here is an example of a cookie jar with a single cookie, so you have a
1311chance of understanding the above paragraph: 1331chance of understanding the above paragraph:
1312 1332
1313 { 1333 {
1314 version => 1, 1334 version => 2,
1315 "10.0.0.1" => { 1335 "10.0.0.1" => {
1316 "/" => { 1336 "/" => {
1317 "mythweb_id" => { 1337 "mythweb_id" => {
1318 _expires => 1293917923, 1338 _expires => 1293917923,
1319 value => "ooRung9dThee3ooyXooM1Ohm", 1339 value => "ooRung9dThee3ooyXooM1Ohm",

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines