--- AnyEvent-HTTP/HTTP.pm	2010/12/29 23:59:36	1.59
+++ AnyEvent-HTTP/HTTP.pm	2010/12/30 03:45:01	1.61
@@ -218,7 +218,8 @@
 In even rarer cases you want total control over how AnyEvent::HTTP
 establishes connections. Normally it uses L<AnyEvent::Socket::tcp_connect>
 to do this, but you can provide your own C<tcp_connect> function -
-obviously, it has to follow the same calling conventions.
+obviously, it has to follow the same calling conventions, except that it
+may always return a connection guard object.
 
 There are probably lots of weird uses for this function, starting from
 tracing the hosts C<http_request> actually tries to connect, to (inexact
@@ -807,6 +808,16 @@
 
 To clear an already-set proxy, use C<undef>.
 
+=item $date = AnyEvent::HTTP::format_date $timestamp
+
+Takes a POSIX timestamp (seconds since the epoch) and formats it as a HTTP
+Date (RFC 2616).
+
+=item $timestamp = AnyEvent::HTTP::parse_date $date
+
+Takes a HTTP Date (RFC 2616) and returns the corresponding POSIX
+timestamp, or C<undef> if the date cannot be parsed.
+
 =item $AnyEvent::HTTP::MAX_RECURSE
 
 The default value for the C<recurse> request parameter (default: C<10>).
@@ -835,6 +846,49 @@
 
 =cut
 
+our @month   = qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec);
+our @weekday = qw(Sun Mon Tue Wed Thu Fri Sat);
+
+sub format_date($) {
+   my ($time) = @_;
+
+   # RFC 822/1123 format
+   my ($S, $M, $H, $mday, $mon, $year, $wday, $yday, undef) = gmtime $time;
+
+   sprintf "%s, %02d %s %04d %02d:%02d:%02d GMT",
+      $weekday[$wday], $mday, $month[$mon], $year + 1900,
+      $H, $M, $S;
+}
+
+sub parse_date($) {
+   my ($date) = @_;
+
+   my ($d, $m, $y, $H, $M, $S);
+
+   if ($date =~ /^[A-Z][a-z][a-z], ([0-9][0-9]) ([A-Z][a-z][a-z]) ([0-9][0-9][0-9][0-9]) ([0-9][0-9]):([0-9][0-9]):([0-9][0-9]) GMT$/) {
+      # RFC 822/1123, required by RFC 2616
+      ($d, $m, $y, $H, $M, $S) = ($1, $2, $3, $4, $5, $6);
+
+   } elsif ($date =~ /^[A-Z][a-z]+, ([0-9][0-9])-([A-Z][a-z][a-z])-([0-9][0-9]) ([0-9][0-9]):([0-9][0-9]):([0-9][0-9]) GMT$/) {
+      # RFC 850
+      ($d, $m, $y, $H, $M, $S) = ($1, $2, $3 < 69 ? $3 + 2000 : $3 + 1900, $4, $5, $6);
+
+   } elsif ($date =~ /^[A-Z][a-z][a-z] ([A-Z][a-z][a-z]) ([0-9 ][0-9]) ([0-9][0-9]):([0-9][0-9]):([0-9][0-9]) ([0-9][0-9][0-9][0-9])$/) {
+      # ISO C's asctime
+      ($d, $m, $y, $H, $M, $S) = ($2, $1, $6, $3, $4, $5);
+   }
+   # other formats fail in the loop below
+
+   for (0..11) {
+      if ($m eq $month[$_]) {
+         require Time::Local;
+         return Time::Local::timegm ($S, $M, $H, $d, $_, $y);
+      }
+   }
+
+   undef
+}
+
 sub set_proxy($) {
    if (length $_[0]) {
       $_[0] =~ m%^(https?):// ([^:/]+) (?: : (\d*) )?%ix
@@ -850,6 +904,62 @@
    set_proxy $ENV{http_proxy};
 };
 
+=head2 SOCKS PROXIES
+
+Socks proxies are not directly supported by AnyEvent::HTTP. You can
+compile your perl to support socks, or use an external program such as
+F<socksify> (dante) or F<tsocks> to make your program use a socks proxy
+transparently.
+
+Alternatively, for AnyEvent::HTTP only, you can use your own
+C<tcp_connect> function that does the proxy handshake - here is an example
+that works with socks4a proxies:
+
+   use Errno;
+   use AnyEvent::Util;
+   use AnyEvent::Socket;
+   use AnyEvent::Handle;
+
+   # host, port and username of/for your socks4a proxy
+   my $socks_host = "10.0.0.23";
+   my $socks_port = 9050;
+   my $socks_user = "";
+
+   sub socks4a_connect {
+      my ($host, $port, $connect_cb, $prepare_cb) = @_;
+
+      my $hdl = new AnyEvent::Handle
+         connect    => [$socks_host, $socks_port],
+         on_prepare => sub { $prepare_cb->($_[0]{fh}) },
+         on_error   => sub { $connect_cb->() },
+      ;
+
+      $hdl->push_write (pack "CCnNZ*Z*", 4, 1, $port, 1, $socks_user, $host);
+
+      $hdl->push_read (chunk => 8, sub {
+         my ($hdl, $chunk) = @_;
+         my ($status, $port, $ipn) = unpack "xCna4", $chunk;
+
+         if ($status == 0x5a) {
+            $connect_cb->($hdl->{fh}, (format_address $ipn) . ":$port");
+         } else {
+            $! = Errno::ENXIO; $connect_cb->();
+         }
+      });
+
+      $hdl
+   }
+
+Use C<socks4a_connect> instead of C<tcp_connect> when doing C<http_request>s,
+possibly after switching off other proxy types:
+
+   AnyEvent::HTTP::set_proxy undef; # usually you do not want other proxies
+
+   http_get 'http://www.google.com', tcp_connect => \&socks4a_connect, sub {
+      my ($data, $headers) = @_;
+      ...
+   };
+
 =head1 SEE ALSO
 
 L<AnyEvent>.