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

Comparing AnyEvent-HTTP/README (file contents):
Revision 1.25 by root, Sun Jun 8 23:33:28 2014 UTC vs.
Revision 1.28 by root, Mon Apr 27 12:14:12 2020 UTC

… …
147 $scheme must be either missing or must be "http" for HTTP. 147 $scheme must be either missing or must be "http" for HTTP.
148 148
149 If not specified, then the default proxy is used (see 149 If not specified, then the default proxy is used (see
150 "AnyEvent::HTTP::set_proxy"). 150 "AnyEvent::HTTP::set_proxy").
151 151
152 Currently, if your proxy requires authorization, you have to
153 specify an appropriate "Proxy-Authorization" header in every
154 request.
155
156 Note that this module will prefer an existing persistent
157 connection, even if that connection was made using another
158 proxy. If you need to ensure that a new connection is made in
159 this case, you can either force "persistent" to false or e.g.
160 use the proxy address in your "sessionid".
161
152 body => $string 162 body => $string
153 The request body, usually empty. Will be sent as-is (future 163 The request body, usually empty. Will be sent as-is (future
154 versions of this module might offer more options). 164 versions of this module might offer more options).
155 165
156 cookie_jar => $hash_ref 166 cookie_jar => $hash_ref
… …
185 The default for this option is "low", which could be interpreted 195 The default for this option is "low", which could be interpreted
186 as "give me the page, no matter what". 196 as "give me the page, no matter what".
187 197
188 See also the "sessionid" parameter. 198 See also the "sessionid" parameter.
189 199
190 session => $string 200 sessionid => $string
191 The module might reuse connections to the same host internally. 201 The module might reuse connections to the same host internally
192 Sometimes (e.g. when using TLS), you do not want to reuse 202 (regardless of other settings, such as "tcp_connect" or
193 connections from other sessions. This can be achieved by setting 203 "proxy"). Sometimes (e.g. when using TLS or a specfic proxy),
194 this parameter to some unique ID (such as the address of an 204 you do not want to reuse connections from other sessions. This
195 object storing your state data, or the TLS context) - only 205 can be achieved by setting this parameter to some unique ID
196 connections using the same unique ID will be reused. 206 (such as the address of an object storing your state data or the
207 TLS context, or the proxy IP) - only connections using the same
208 unique ID will be reused.
197 209
198 on_prepare => $callback->($fh) 210 on_prepare => $callback->($fh)
199 In rare cases you need to "tune" the socket before it is used to 211 In rare cases you need to "tune" the socket before it is used to
200 connect (for example, to bind it on a given IP address). This 212 connect (for example, to bind it on a given IP address). This
201 parameter overrides the prepare callback passed to 213 parameter overrides the prepare callback passed to
… …
210 AnyEvent::HTTP establishes connections. Normally it uses 222 AnyEvent::HTTP establishes connections. Normally it uses
211 AnyEvent::Socket::tcp_connect to do this, but you can provide 223 AnyEvent::Socket::tcp_connect to do this, but you can provide
212 your own "tcp_connect" function - obviously, it has to follow 224 your own "tcp_connect" function - obviously, it has to follow
213 the same calling conventions, except that it may always return a 225 the same calling conventions, except that it may always return a
214 connection guard object. 226 connection guard object.
227
228 The connections made by this hook will be treated as equivalent
229 to connections made the built-in way, specifically, they will be
230 put into and taken from the persistent connection cache. If your
231 $tcp_connect function is incompatible with this kind of re-use,
232 consider switching off "persistent" connections and/or providing
233 a "sessionid" identifier.
215 234
216 There are probably lots of weird uses for this function, 235 There are probably lots of weird uses for this function,
217 starting from tracing the hosts "http_request" actually tries to 236 starting from tracing the hosts "http_request" actually tries to
218 connect, to (inexact but fast) host => IP address caching or 237 connect, to (inexact but fast) host => IP address caching or
219 even socks protocol support. 238 even socks protocol support.
… …
293 312
294 persistent => $boolean 313 persistent => $boolean
295 Try to create/reuse a persistent connection. When this flag is 314 Try to create/reuse a persistent connection. When this flag is
296 set (default: true for idempotent requests, false for all 315 set (default: true for idempotent requests, false for all
297 others), then "http_request" tries to re-use an existing 316 others), then "http_request" tries to re-use an existing
298 (previously-created) persistent connection to the host and, 317 (previously-created) persistent connection to same host (i.e.
318 identical URL scheme, hostname, port and sessionid) and, failing
299 failing that, tries to create a new one. 319 that, tries to create a new one.
300 320
301 Requests failing in certain ways will be automatically retried 321 Requests failing in certain ways will be automatically retried
302 once, which is dangerous for non-idempotent requests, which is 322 once, which is dangerous for non-idempotent requests, which is
303 why it defaults to off for them. The reason for this is because 323 why it defaults to off for them. The reason for this is because
304 the bozos who designed HTTP/1.1 made it impossible to 324 the bozos who designed HTTP/1.1 made it impossible to
305 distinguish between a fatal error and a normal connection 325 distinguish between a fatal error and a normal connection
306 timeout, so you never know whether there was a problem with your 326 timeout, so you never know whether there was a problem with your
307 request or not. 327 request or not.
308 328
309 When reusing an existent connection, many parameters (such as 329 When reusing an existent connection, many parameters (such as
310 TLS context) will be ignored. See the "session" parameter for a 330 TLS context) will be ignored. See the "sessionid" parameter for
311 workaround. 331 a workaround.
312 332
313 keepalive => $boolean 333 keepalive => $boolean
314 Only used when "persistent" is also true. This parameter decides 334 Only used when "persistent" is also true. This parameter decides
315 whether "http_request" tries to handshake a HTTP/1.0-style 335 whether "http_request" tries to handshake a HTTP/1.0-style
316 keep-alive connection (as opposed to only a HTTP/1.1 persistent 336 keep-alive connection (as opposed to only a HTTP/1.1 persistent
… …
393 save cookies to disk, and you should call this function after 413 save cookies to disk, and you should call this function after
394 loading them again. If you have a long-running program you can 414 loading them again. If you have a long-running program you can
395 additionally call this function from time to time. 415 additionally call this function from time to time.
396 416
397 A cookie jar is initially an empty hash-reference that is managed by 417 A cookie jar is initially an empty hash-reference that is managed by
398 this module. It's format is subject to change, but currently it is 418 this module. Its format is subject to change, but currently it is as
399 like this: 419 follows:
400 420
401 The key "version" has to contain 1, otherwise the hash gets emptied. 421 The key "version" has to contain 2, otherwise the hash gets cleared.
402 All other keys are hostnames or IP addresses pointing to 422 All other keys are hostnames or IP addresses pointing to
403 hash-references. The key for these inner hash references is the 423 hash-references. The key for these inner hash references is the
404 server path for which this cookie is meant, and the values are again 424 server path for which this cookie is meant, and the values are again
405 hash-references. Each key of those hash-references is a cookie name, 425 hash-references. Each key of those hash-references is a cookie name,
406 and the value, you guessed it, is another hash-reference, this time 426 and the value, you guessed it, is another hash-reference, this time
… …
411 431
412 Here is an example of a cookie jar with a single cookie, so you have 432 Here is an example of a cookie jar with a single cookie, so you have
413 a chance of understanding the above paragraph: 433 a chance of understanding the above paragraph:
414 434
415 { 435 {
416 version => 1, 436 version => 2,
417 "10.0.0.1" => { 437 "10.0.0.1" => {
418 "/" => { 438 "/" => {
419 "mythweb_id" => { 439 "mythweb_id" => {
420 _expires => 1293917923, 440 _expires => 1293917923,
421 value => "ooRung9dThee3ooyXooM1Ohm", 441 value => "ooRung9dThee3ooyXooM1Ohm",
… …
445 "Mozilla/5.0 (compatible; U; AnyEvent-HTTP/$VERSION; 465 "Mozilla/5.0 (compatible; U; AnyEvent-HTTP/$VERSION;
446 +http://software.schmorp.de/pkg/AnyEvent)"). 466 +http://software.schmorp.de/pkg/AnyEvent)").
447 467
448 $AnyEvent::HTTP::MAX_PER_HOST 468 $AnyEvent::HTTP::MAX_PER_HOST
449 The maximum number of concurrent connections to the same host 469 The maximum number of concurrent connections to the same host
450 (identified by the hostname). If the limit is exceeded, then the 470 (identified by the hostname). If the limit is exceeded, then
451 additional requests are queued until previous connections are 471 additional requests are queued until previous connections are
452 closed. Both persistent and non-persistent connections are counted 472 closed. Both persistent and non-persistent connections are counted
453 in this limit. 473 in this limit.
454 474
455 The default value for this is 4, and it is highly advisable to not 475 The default value for this is 4, and it is highly advisable to not
… …
496 or die "$file: $!"; 516 or die "$file: $!";
497 517
498 my %hdr; 518 my %hdr;
499 my $ofs = 0; 519 my $ofs = 0;
500 520
501 warn stat $fh;
502 warn -s _;
503 if (stat $fh and -s _) { 521 if (stat $fh and -s _) {
504 $ofs = -s _; 522 $ofs = -s _;
505 warn "-s is ", $ofs; 523 warn "-s is ", $ofs;
506 $hdr{"if-unmodified-since"} = AnyEvent::HTTP::format_date +(stat _)[9]; 524 $hdr{"if-unmodified-since"} = AnyEvent::HTTP::format_date +(stat _)[9];
507 $hdr{"range"} = "bytes=$ofs-"; 525 $hdr{"range"} = "bytes=$ofs-";
… …
535 my (undef, $hdr) = @_; 553 my (undef, $hdr) = @_;
536 554
537 my $status = $hdr->{Status}; 555 my $status = $hdr->{Status};
538 556
539 if (my $time = AnyEvent::HTTP::parse_date $hdr->{"last-modified"}) { 557 if (my $time = AnyEvent::HTTP::parse_date $hdr->{"last-modified"}) {
540 utime $fh, $time, $time; 558 utime $time, $time, $fh;
541 } 559 }
542 560
543 if ($status == 200 || $status == 206 || $status == 416) { 561 if ($status == 200 || $status == 206 || $status == 416) {
544 # download ok || resume ok || file already fully downloaded 562 # download ok || resume ok || file already fully downloaded
545 $cb->(1, $hdr); 563 $cb->(1, $hdr);

Diff Legend

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