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.113 by root, Sat Jan 12 15:41:35 2013 UTC vs.
Revision 1.117 by root, Mon Sep 9 21:41:43 2013 UTC

… …
89C<http_request> returns a "cancellation guard" - you have to keep the 89C<http_request> returns a "cancellation guard" - you have to keep the
90object at least alive until the callback get called. If the object gets 90object at least alive until the callback get called. If the object gets
91destroyed before the callback is called, the request will be cancelled. 91destroyed before the callback is called, the request will be cancelled.
92 92
93The callback will be called with the response body data as first argument 93The callback will be called with the response body data as first argument
94(or C<undef> if an error occured), and a hash-ref with response headers 94(or C<undef> if an error occurred), and a hash-ref with response headers
95(and trailers) as second argument. 95(and trailers) as second argument.
96 96
97All the headers in that hash are lowercased. In addition to the response 97All the headers in that hash are lowercased. In addition to the response
98headers, the "pseudo-headers" (uppercase to avoid clashing with possible 98headers, the "pseudo-headers" (uppercase to avoid clashing with possible
99response headers) C<HTTPVersion>, C<Status> and C<Reason> contain the 99response headers) C<HTTPVersion>, C<Status> and C<Reason> contain the
… …
123C<590>-C<599> and the C<Reason> pseudo-header will contain an error 123C<590>-C<599> and the C<Reason> pseudo-header will contain an error
124message. Currently the following status codes are used: 124message. Currently the following status codes are used:
125 125
126=over 4 126=over 4
127 127
128=item 595 - errors during connection etsbalishment, proxy handshake. 128=item 595 - errors during connection establishment, proxy handshake.
129 129
130=item 596 - errors during TLS negotiation, request sending and header processing. 130=item 596 - errors during TLS negotiation, request sending and header processing.
131 131
132=item 597 - errors during body receiving or processing. 132=item 597 - errors during body receiving or processing.
133 133
… …
242context) - only connections using the same unique ID will be reused. 242context) - only connections using the same unique ID will be reused.
243 243
244=item on_prepare => $callback->($fh) 244=item on_prepare => $callback->($fh)
245 245
246In rare cases you need to "tune" the socket before it is used to 246In rare cases you need to "tune" the socket before it is used to
247connect (for exmaple, to bind it on a given IP address). This parameter 247connect (for example, to bind it on a given IP address). This parameter
248overrides the prepare callback passed to C<AnyEvent::Socket::tcp_connect> 248overrides the prepare callback passed to C<AnyEvent::Socket::tcp_connect>
249and behaves exactly the same way (e.g. it has to provide a 249and behaves exactly the same way (e.g. it has to provide a
250timeout). See the description for the C<$prepare_cb> argument of 250timeout). See the description for the C<$prepare_cb> argument of
251C<AnyEvent::Socket::tcp_connect> for details. 251C<AnyEvent::Socket::tcp_connect> for details.
252 252
… …
689 689
690 $cb->(undef, $hdr); 690 $cb->(undef, $hdr);
691 () 691 ()
692} 692}
693 693
694our %IDEMPOTENT = (
695 DELETE => 1,
696 GET => 1,
697 HEAD => 1,
698 OPTIONS => 1,
699 PUT => 1,
700 TRACE => 1,
701
702 ACL => 1,
703 "BASELINE-CONTROL" => 1,
704 BIND => 1,
705 CHECKIN => 1,
706 CHECKOUT => 1,
707 COPY => 1,
708 LABEL => 1,
709 LINK => 1,
710 MERGE => 1,
711 MKACTIVITY => 1,
712 MKCALENDAR => 1,
713 MKCOL => 1,
714 MKREDIRECTREF => 1,
715 MKWORKSPACE => 1,
716 MOVE => 1,
717 ORDERPATCH => 1,
718 PROPFIND => 1,
719 PROPPATCH => 1,
720 REBIND => 1,
721 REPORT => 1,
722 SEARCH => 1,
723 UNBIND => 1,
724 UNCHECKOUT => 1,
725 UNLINK => 1,
726 UNLOCK => 1,
727 UPDATE => 1,
728 UPDATEREDIRECTREF => 1,
729 "VERSION-CONTROL" => 1,
730);
731
694sub http_request($$@) { 732sub http_request($$@) {
695 my $cb = pop; 733 my $cb = pop;
696 my ($method, $url, %arg) = @_; 734 my ($method, $url, %arg) = @_;
697 735
698 my %hdr; 736 my %hdr;
… …
773 $hdr{"user-agent"} = $USERAGENT unless exists $hdr{"user-agent"}; 811 $hdr{"user-agent"} = $USERAGENT unless exists $hdr{"user-agent"};
774 812
775 $hdr{"content-length"} = length $arg{body} 813 $hdr{"content-length"} = length $arg{body}
776 if length $arg{body} || $method ne "GET"; 814 if length $arg{body} || $method ne "GET";
777 815
778 my $idempotent = $method =~ /^(?:GET|HEAD|PUT|DELETE|OPTIONS|TRACE)$/; 816 my $idempotent = $IDEMPOTENT{$method};
779 817
780 # default value for keepalive is true iff the request is for an idempotent method 818 # default value for keepalive is true iff the request is for an idempotent method
781 my $persistent = exists $arg{persistent} ? !!$arg{persistent} : $idempotent; 819 my $persistent = exists $arg{persistent} ? !!$arg{persistent} : $idempotent;
782 my $keepalive = exists $arg{keepalive} ? !!$arg{keepalive} : !$proxy; 820 my $keepalive = exists $arg{keepalive} ? !!$arg{keepalive} : !$proxy;
783 my $was_persistent; # true if this is actually a recycled connection 821 my $was_persistent; # true if this is actually a recycled connection
… …
806 . (join "", map "\u$_: $hdr{$_}\015\012", grep defined $hdr{$_}, keys %hdr) 844 . (join "", map "\u$_: $hdr{$_}\015\012", grep defined $hdr{$_}, keys %hdr)
807 . "\015\012" 845 . "\015\012"
808 . (delete $arg{body}) 846 . (delete $arg{body})
809 ); 847 );
810 848
811 # return if error occured during push_write() 849 # return if error occurred during push_write()
812 return unless %state; 850 return unless %state;
813 851
814 # reduce memory usage, save a kitten, also re-use it for the response headers. 852 # reduce memory usage, save a kitten, also re-use it for the response headers.
815 %hdr = (); 853 %hdr = ();
816 854
… …
1206C<$session_end> is given and true, then additionally remove all session 1244C<$session_end> is given and true, then additionally remove all session
1207cookies. 1245cookies.
1208 1246
1209You should call this function (with a true C<$session_end>) before you 1247You should call this function (with a true C<$session_end>) before you
1210save cookies to disk, and you should call this function after loading them 1248save cookies to disk, and you should call this function after loading them
1211again. If you have a long-running program you can additonally call this 1249again. If you have a long-running program you can additionally call this
1212function from time to time. 1250function from time to time.
1213 1251
1214A cookie jar is initially an empty hash-reference that is managed by this 1252A cookie jar is initially an empty hash-reference that is managed by this
1215module. It's format is subject to change, but currently it is like this: 1253module. It's format is subject to change, but currently it is like this:
1216 1254
1217The key C<version> has to contain C<1>, otherwise the hash gets 1255The key C<version> has to contain C<1>, otherwise the hash gets
1218emptied. All other keys are hostnames or IP addresses pointing to 1256emptied. All other keys are hostnames or IP addresses pointing to
1219hash-references. The key for these inner hash references is the 1257hash-references. The key for these inner hash references is the
1220server path for which this cookie is meant, and the values are again 1258server path for which this cookie is meant, and the values are again
1221hash-references. The keys of those hash-references is the cookie name, and 1259hash-references. Each key of those hash-references is a cookie name, and
1222the value, you guessed it, is another hash-reference, this time with the 1260the value, you guessed it, is another hash-reference, this time with the
1223key-value pairs from the cookie, except for C<expires> and C<max-age>, 1261key-value pairs from the cookie, except for C<expires> and C<max-age>,
1224which have been replaced by a C<_expires> key that contains the cookie 1262which have been replaced by a C<_expires> key that contains the cookie
1225expiry timestamp. 1263expiry timestamp. Session cookies are indicated by not having an
1264C<_expires> key.
1226 1265
1227Here is an example of a cookie jar with a single cookie, so you have a 1266Here is an example of a cookie jar with a single cookie, so you have a
1228chance of understanding the above paragraph: 1267chance of understanding the above paragraph:
1229 1268
1230 { 1269 {
… …
1272 1311
1273The default value for this is C<4>, and it is highly advisable to not 1312The default value for this is C<4>, and it is highly advisable to not
1274increase it much. 1313increase it much.
1275 1314
1276For comparison: the RFC's recommend 4 non-persistent or 2 persistent 1315For comparison: the RFC's recommend 4 non-persistent or 2 persistent
1277connections, older browsers used 2, newers (such as firefox 3) typically 1316connections, older browsers used 2, newer ones (such as firefox 3)
1278use 6, and Opera uses 8 because like, they have the fastest browser and 1317typically use 6, and Opera uses 8 because like, they have the fastest
1279give a shit for everybody else on the planet. 1318browser and give a shit for everybody else on the planet.
1280 1319
1281=item $AnyEvent::HTTP::PERSISTENT_TIMEOUT 1320=item $AnyEvent::HTTP::PERSISTENT_TIMEOUT
1282 1321
1283The time after which idle persistent conenctions get closed by 1322The time after which idle persistent connections get closed by
1284AnyEvent::HTTP (default: C<3>). 1323AnyEvent::HTTP (default: C<3>).
1285 1324
1286=item $AnyEvent::HTTP::ACTIVE 1325=item $AnyEvent::HTTP::ACTIVE
1287 1326
1288The number of active connections. This is not the number of currently 1327The number of active connections. This is not the number of currently
… …
1353 set_proxy $ENV{http_proxy}; 1392 set_proxy $ENV{http_proxy};
1354}; 1393};
1355 1394
1356=head2 SHOWCASE 1395=head2 SHOWCASE
1357 1396
1358This section contaisn some more elaborate "real-world" examples or code 1397This section contains some more elaborate "real-world" examples or code
1359snippets. 1398snippets.
1360 1399
1361=head2 HTTP/1.1 FILE DOWNLOAD 1400=head2 HTTP/1.1 FILE DOWNLOAD
1362 1401
1363Downloading files with HTTP can be quite tricky, especially when something 1402Downloading files with HTTP can be quite tricky, especially when something
… …
1367last modified time to check for file content changes, and works with many 1406last modified time to check for file content changes, and works with many
1368HTTP/1.0 servers as well, and usually falls back to a complete re-download 1407HTTP/1.0 servers as well, and usually falls back to a complete re-download
1369on older servers. 1408on older servers.
1370 1409
1371It calls the completion callback with either C<undef>, which means a 1410It calls the completion callback with either C<undef>, which means a
1372nonretryable error occured, C<0> when the download was partial and should 1411nonretryable error occurred, C<0> when the download was partial and should
1373be retried, and C<1> if it was successful. 1412be retried, and C<1> if it was successful.
1374 1413
1375 use AnyEvent::HTTP; 1414 use AnyEvent::HTTP;
1376 1415
1377 sub download($$$) { 1416 sub download($$$) {

Diff Legend

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