NAME

       AnyEvent::Connector - tcp_connect with transparent proxy handling

SYNOPSIS

           use AnyEvent::Connector;

           ## Specify the proxy setting explicitly.
           my $c = AnyEvent::Connector->new(
               proxy => 'http://proxy.example.com:8080',
               no_proxy => ['localhost', 'your-internal-domain.net']
           );

           ## Proxy setting from "http_proxy" and "no_proxy" environment variables.
           my $cenv = AnyEvent::Connector->new(
               env_proxy => "http",
           );

           ## Same API as AnyEvent::Socket::tcp_connect
           my $guard = $c->tcp_connect(
               "target.hogehoge.org", 80,
               sub {
                   ## connect callback
                   my ($fh ,$host, $port, $retry) = @_;
                   ...;
               },
               sub {
                   ## prepare calback
                   my ($fh) = @_;
                   ...;
               }
           );

DESCRIPTION

       AnyEvent::Connector object has "tcp_connect" method compatible with that from AnyEvent::Socket, and it
       handles proxy settings transparently.

CLASS METHODS

   $conn = AnyEvent::Connector->new(%args)
       The constructor.

       Fields in %args are:

       "proxy" => STR (optional)
           String of proxy URL. Currently only "http" proxy is supported.

           If both "proxy" and "env_proxy" are not specified, the $conn will directly connect to the destination
           host.

           If both "proxy" and "env_proxy" are specified, setting by "proxy" is used.

           Setting empty string to "proxy" disables the proxy setting done by "env_proxy" option.

       "no_proxy" => STR or ARRAYREF of STR (optional)
           String or array-ref of strings of domain names, to which the $conn will directly connect.

           If both "no_proxy" and "env_proxy" are specified, setting by "no_proxy" is used.

           Setting  empty  string  or  empty  array-ref  to  "no_proxy"  disables  the  no_proxy setting done by
           "env_proxy" option.

       "env_proxy" => STR (optional)
           String of protocol specifier. If  specified,  proxy  settings  for  that  protocol  are  loaded  from
           environment variables, and $conn is created.

           For  example,  if  "http" is specified, "http_proxy" (or "HTTP_PROXY") and "no_proxy" (or "NO_PROXY")
           environment variables are used to set "proxy" and "no_proxy" options, respectively.

           "proxy" and "no_proxy" options have precedence over "env_proxy" option.

OBJECT METHOD

   $guard = $conn->tcp_connect($host, $port, $connect_cb, $prepare_cb)
       Make a (possibly proxied) TCP connection to the given $host and $port.

       If "$conn->proxy_for($host, $port)" returns "undef", the behavior of this method is exactly the  same  as
       "tcp_connect" function from AnyEvent::Socket.

       If "$conn->proxy_for($host, $port)" returns a proxy URL, it behaves in the following way.

       •   It connects to the proxy, and tells the proxy to connect to the final destination, $host and $port.

       •   It  runs  $connect_cb  after  the  connection to the proxy AND (hopefully) the connection between the
           proxy and the final destination are both established.

               $connect_cb->($cb_fh, $cb_host, $cb_port, $cb_retry)

           $cb_fh is the filehandle to the proxy. $cb_host and $cb_port are the hostname and port of the proxy.

       •   If the TCP connection to the proxy is established but the connection to the final  destination  fails
           for  some  reason,  $connect_cb is called with no argument passed (just as the original "tcp_connect"
           does).

       •   If given, it runs $prepare_cb before it starts connecting to the proxy.

   $proxy = $conn->proxy_for($host, $port)
       If $conn uses a proxy to connect to the given $host and $port, it returns the string of  the  proxy  URL.
       Otherwise, it returns "undef".

SEE ALSO

       •   AnyEvent::Socket

       •   AnyEvent::HTTP   -   it  has  "tcp_connect"  option  to  implement  proxy  connection.  You  can  use
           AnyEvent::Connector for it.

REPOSITORY

       <https://github.com/debug-ito/AnyEvent-Connector>

BUGS AND FEATURE REQUESTS

       Please      report      bugs      and      feature      requests      to      my      Github       issues
       <https://github.com/debug-ito/AnyEvent-Connector/issues>.

       Although       I       prefer      Github,      non-Github      users      can      use      CPAN      RT
       <https://rt.cpan.org/Public/Dist/Display.html?Name=AnyEvent-Connector>.     Please    send    email    to
       "bug-AnyEvent-Connector at rt.cpan.org" to report bugs if you do not have CPAN RT account.

AUTHOR

       Toshio Ito, "<toshioito at cpan.org>"

LICENSE AND COPYRIGHT

       Copyright 2018 Toshio Ito.

       This  program  is  free software; you can redistribute it and/or modify it under the terms of either: the
       GNU General Public License as published by the Free Software Foundation; or the Artistic License.

       See <http://dev.perl.org/licenses/> for more information.

perl v5.36.0                                       2023-11-11                           AnyEvent::Connector(3pm)