[ViewVC] Diff of: cvs/AnyEvent-HTTP/README

Comparing AnyEvent-HTTP/README (file contents):
Revision 1.16 by root, Tue Jan 11 06:38:47 2011 UTC vs.
Revision 1.28 by root, Mon Apr 27 12:14:12 2020 UTC

     This module is an AnyEvent user, you need to make sure that you use and
     run a supported event loop.
     This module implements a simple, stateless and non-blocking HTTP client.
     It supports GET, POST and other request methods, cookies and more, all
-    on a very low level. It can follow redirects supports proxies and
+    on a very low level. It can follow redirects, supports proxies, and
     automatically limits the number of connections to the values specified
     in the RFC.
     It should generally be a "good client" that is enough for most HTTP
     tasks. Simple tasks should be simple, but complex tasks should still be
         object at least alive until the callback get called. If the object
         gets destroyed before the callback is called, the request will be
         cancelled.
         The callback will be called with the response body data as first
-        argument (or "undef" if an error occured), and a hash-ref with
+        argument (or "undef" if an error occurred), and a hash-ref with
         response headers (and trailers) as second argument.
         All the headers in that hash are lowercased. In addition to the
         response headers, the "pseudo-headers" (uppercase to avoid clashing
         with possible response headers) "HTTPVersion", "Status" and "Reason"
         If an internal error occurs, such as not being able to resolve a
         hostname, then $data will be "undef", "$headers->{Status}" will be
         590-599 and the "Reason" pseudo-header will contain an error
         message. Currently the following status codes are used:
-        595 - errors during connection etsbalishment, proxy handshake.
+        595 - errors during connection establishment, proxy handshake.
         596 - errors during TLS negotiation, request sending and header
         processing.
         597 - errors during body receiving or processing.
         598 - user aborted request via "on_header" or "on_body".
         599 - other, usually nonretryable, errors (garbled URL etc.).
         Additional parameters are key-value pairs, and are fully optional.
         They include:
         recurse => $count (default: $MAX_RECURSE)
             Whether to recurse requests or not, e.g. on redirects,
-            authentication retries and so on, and how often to do so.
+            authentication and other retries and so on, and how often to do
+            so.
+            Only redirects to http and https URLs are supported. While most
+            common redirection forms are handled entirely within this
+            module, some require the use of the optional URI module. If it
+            is required but missing, then the request will fail with an
+            error.
         headers => hashref
             The request headers to use. Currently, "http_request" may
             provide its own "Host:", "Content-Length:", "Connection:" and
             "Cookie:" headers and will provide defaults at least for "TE:",
             You really should provide your own "User-Agent:" header value
             that is appropriate for your program - I wouldn't be surprised
             if the default AnyEvent string gets blocked by webservers sooner
             or later.
+            Also, make sure that your headers names and values do not
+            contain any embedded newlines.
         timeout => $seconds
             The time-out to use for various stages - each connect attempt
             will reset the timeout, as will read or write activity, i.e.
             this is not an overall timeout.
             Default timeout is 5 minutes.
         proxy => [$host, $port[, $scheme]] or undef
-            Use the given http proxy for all requests. If not specified,
+            Use the given http proxy for all requests, or no proxy if
-            then the default proxy (as specified by $ENV{http_proxy}) is
-            used.
+            "undef" is used.
             $scheme must be either missing or must be "http" for HTTP.
+            If not specified, then the default proxy is used (see
+            "AnyEvent::HTTP::set_proxy").
+            Currently, if your proxy requires authorization, you have to
+            specify an appropriate "Proxy-Authorization" header in every
+            request.
+            Note that this module will prefer an existing persistent
+            connection, even if that connection was made using another
+            proxy. If you need to ensure that a new connection is made in
+            this case, you can either force "persistent" to false or e.g.
+            use the proxy address in your "sessionid".
         body => $string
             The request body, usually empty. Will be sent as-is (future
             versions of this module might offer more options).
             The default for this option is "low", which could be interpreted
             as "give me the page, no matter what".
             See also the "sessionid" parameter.
-        session => $string
+        sessionid => $string
-            The module might reuse connections to the same host internally.
+            The module might reuse connections to the same host internally
-            Sometimes (e.g. when using TLS), you do not want to reuse
+            (regardless of other settings, such as "tcp_connect" or
-            connections from other sessions. This can be achieved by setting
+            "proxy"). Sometimes (e.g. when using TLS or a specfic proxy),
-            this parameter to some unique ID (such as the address of an
+            you do not want to reuse connections from other sessions. This
-            object storing your state data, or the TLS context) - only
+            can be achieved by setting this parameter to some unique ID
-            connections using the same unique ID will be reused.
+            (such as the address of an object storing your state data or the
+            TLS context, or the proxy IP) - only connections using the same
+            unique ID will be reused.
         on_prepare => $callback->($fh)
             In rare cases you need to "tune" the socket before it is used to
-            connect (for exmaple, to bind it on a given IP address). This
+            connect (for example, to bind it on a given IP address). This
             parameter overrides the prepare callback passed to
             "AnyEvent::Socket::tcp_connect" and behaves exactly the same way
             (e.g. it has to provide a timeout). See the description for the
             $prepare_cb argument of "AnyEvent::Socket::tcp_connect" for
             details.
             AnyEvent::HTTP establishes connections. Normally it uses
             AnyEvent::Socket::tcp_connect to do this, but you can provide
             your own "tcp_connect" function - obviously, it has to follow
             the same calling conventions, except that it may always return a
             connection guard object.
+            The connections made by this hook will be treated as equivalent
+            to connections made the built-in way, specifically, they will be
+            put into and taken from the persistent connection cache. If your
+            $tcp_connect function is incompatible with this kind of re-use,
+            consider switching off "persistent" connections and/or providing
+            a "sessionid" identifier.
             There are probably lots of weird uses for this function,
             starting from tracing the hosts "http_request" actually tries to
             connect, to (inexact but fast) host => IP address caching or
             even socks protocol support.
         persistent => $boolean
             Try to create/reuse a persistent connection. When this flag is
             set (default: true for idempotent requests, false for all
             others), then "http_request" tries to re-use an existing
-            (previously-created) persistent connection to the host and,
+            (previously-created) persistent connection to same host (i.e.
+            identical URL scheme, hostname, port and sessionid) and, failing
-            failing that, tries to create a new one.
+            that, tries to create a new one.
             Requests failing in certain ways will be automatically retried
             once, which is dangerous for non-idempotent requests, which is
             why it defaults to off for them. The reason for this is because
             the bozos who designed HTTP/1.1 made it impossible to
             distinguish between a fatal error and a normal connection
             timeout, so you never know whether there was a problem with your
             request or not.
             When reusing an existent connection, many parameters (such as
-            TLS context) will be ignored. See the "session" parameter for a
+            TLS context) will be ignored. See the "sessionid" parameter for
-            workaround.
+            a workaround.
         keepalive => $boolean
             Only used when "persistent" is also true. This parameter decides
             whether "http_request" tries to handshake a HTTP/1.0-style
             keep-alive connection (as opposed to only a HTTP/1.1 persistent
         Example: do a HTTP HEAD request on https://www.google.com/, use a
         timeout of 30 seconds.
            http_request
-              GET     => "https://www.google.com",
+              HEAD    => "https://www.google.com",
               headers => { "user-agent" => "MySearchClient 1.0" },
               timeout => 30,
               sub {
                  my ($body, $hdr) = @_;
                  use Data::Dumper;
         Sets the default proxy server to use. The proxy-url must begin with
         a string of the form "http://host:port", croaks otherwise.
         To clear an already-set proxy, use "undef".
+        When AnyEvent::HTTP is loaded for the first time it will query the
+        default proxy from the operating system, currently by looking at
+        "$ENV{http_proxy"}.
     AnyEvent::HTTP::cookie_jar_expire $jar[, $session_end]
         Remove all cookies from the cookie jar that have been expired. If
         $session_end is given and true, then additionally remove all session
         cookies.
         You should call this function (with a true $session_end) before you
         save cookies to disk, and you should call this function after
         loading them again. If you have a long-running program you can
-        additonally call this function from time to time.
+        additionally call this function from time to time.
         A cookie jar is initially an empty hash-reference that is managed by
-        this module. It's format is subject to change, but currently it is
+        this module. Its format is subject to change, but currently it is as
-        like this:
+        follows:
-        The key "version" has to contain 1, otherwise the hash gets emptied.
+        The key "version" has to contain 2, otherwise the hash gets cleared.
         All other keys are hostnames or IP addresses pointing to
         hash-references. The key for these inner hash references is the
         server path for which this cookie is meant, and the values are again
-        hash-references. The keys of those hash-references is the cookie
+        hash-references. Each key of those hash-references is a cookie name,
-        name, and the value, you guessed it, is another hash-reference, this
+        and the value, you guessed it, is another hash-reference, this time
-        time with the key-value pairs from the cookie, except for "expires"
+        with the key-value pairs from the cookie, except for "expires" and
-        and "max-age", which have been replaced by a "_expires" key that
+        "max-age", which have been replaced by a "_expires" key that
-        contains the cookie expiry timestamp.
+        contains the cookie expiry timestamp. Session cookies are indicated
+        by not having an "_expires" key.
         Here is an example of a cookie jar with a single cookie, so you have
         a chance of understanding the above paragraph:
            {
-              version    => 1,
+              version    => 2,
               "10.0.0.1" => {
                  "/" => {
                     "mythweb_id" => {
                       _expires => 1293917923,
                       value    => "ooRung9dThee3ooyXooM1Ohm",
     $AnyEvent::HTTP::MAX_RECURSE
         The default value for the "recurse" request parameter (default: 10).
     $AnyEvent::HTTP::TIMEOUT
-        The default timeout for conenction operations (default: 300).
+        The default timeout for connection operations (default: 300).
     $AnyEvent::HTTP::USERAGENT
         The default value for the "User-Agent" header (the default is
         "Mozilla/5.0 (compatible; U; AnyEvent-HTTP/$VERSION;
         +http://software.schmorp.de/pkg/AnyEvent)").
     $AnyEvent::HTTP::MAX_PER_HOST
         The maximum number of concurrent connections to the same host
-        (identified by the hostname). If the limit is exceeded, then the
+        (identified by the hostname). If the limit is exceeded, then
         additional requests are queued until previous connections are
         closed. Both persistent and non-persistent connections are counted
         in this limit.
         The default value for this is 4, and it is highly advisable to not
         increase it much.
         For comparison: the RFC's recommend 4 non-persistent or 2 persistent
-        connections, older browsers used 2, newers (such as firefox 3)
+        connections, older browsers used 2, newer ones (such as firefox 3)
         typically use 6, and Opera uses 8 because like, they have the
         fastest browser and give a shit for everybody else on the planet.
     $AnyEvent::HTTP::PERSISTENT_TIMEOUT
-        The time after which idle persistent conenctions get closed by
+        The time after which idle persistent connections get closed by
         AnyEvent::HTTP (default: 3).
     $AnyEvent::HTTP::ACTIVE
         The number of active connections. This is not the number of
         currently running requests, but the number of currently open and
         non-idle TCP connections. This number can be useful for
         load-leveling.
   SHOWCASE
-    This section contaisn some more elaborate "real-world" examples or code
+    This section contains some more elaborate "real-world" examples or code
     snippets.
   HTTP/1.1 FILE DOWNLOAD
-    Downloading files with HTTP cna be quite tricky, especially when
+    Downloading files with HTTP can be quite tricky, especially when
-    something goes wrong and you want tor esume.
+    something goes wrong and you want to resume.
     Here is a function that initiates and resumes a download. It uses the
     last modified time to check for file content changes, and works with
     many HTTP/1.0 servers as well, and usually falls back to a complete
     re-download on older servers.
     It calls the completion callback with either "undef", which means a
-    nonretryable error occured, 0 when the download was partial and should
+    nonretryable error occurred, 0 when the download was partial and should
     be retried, and 1 if it was successful.
        use AnyEvent::HTTP;
        sub download($$$) {
              or die "$file: $!";
           my %hdr;
           my $ofs = 0;
-          warn stat $fh;
-          warn -s _;
           if (stat $fh and -s _) {
              $ofs = -s _;
-             warn "-s is ", $ofs;#d#
+             warn "-s is ", $ofs;
              $hdr{"if-unmodified-since"} = AnyEvent::HTTP::format_date +(stat _)[9];
              $hdr{"range"} = "bytes=$ofs-";
           }
           http_get $url,
                 my (undef, $hdr) = @_;
                 my $status = $hdr->{Status};
                 if (my $time = AnyEvent::HTTP::parse_date $hdr->{"last-modified"}) {
-                   utime $fh, $time, $time;
+                   utime $time, $time, $fh;
                 }
                 if ($status == 200 || $status == 206 || $status == 416) {
                    # download ok || resume ok || file already fully downloaded
                    $cb->(1, $hdr);
 AUTHOR
        Marc Lehmann <schmorp@schmorp.de>
        http://home.schmorp.de/
-    With many thanks to Дмитрий Шалашов, who provided
+    With many thanks to Дмитрий Шалашов, who provided countless testcases
-    countless testcases and bugreports.
+    and bugreports.

Diff Legend

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

Comparing AnyEvent-HTTP/README (file contents): Revision 1.16 by root, Tue Jan 11 06:38:47 2011 UTC vs. Revision 1.28 by root, Mon Apr 27 12:14:12 2020 UTC

Diff Legend

Comparing AnyEvent-HTTP/README (file contents):
Revision 1.16 by root, Tue Jan 11 06:38:47 2011 UTC vs.
Revision 1.28 by root, Mon Apr 27 12:14:12 2020 UTC