view release on metacpan or  search on metacpan

lib/AnyEvent/Connector.pm  view on Meta::CPAN

    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) = @_;
            ...;
        }
    );

=head1 DESCRIPTION

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

=head1 CLASS METHODS

=head2 $conn = AnyEvent::Connector->new(%args)

The constructor.

Fields in C<%args> are:

=over

=item C<proxy> => STR (optional)

String of proxy URL. Currently only C<http> proxy is supported.

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

If both C<proxy> and C<env_proxy> are specified, setting by C<proxy> is used.

Setting empty string to C<proxy> disables the proxy setting done by C<env_proxy> option.

=item C<no_proxy> => STR or ARRAYREF of STR (optional)

String or array-ref of strings of domain names, to which the C<$conn> will directly connect.

If both C<no_proxy> and C<env_proxy> are specified, setting by C<no_proxy> is used.

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

=item C<env_proxy> => STR (optional)

String of protocol specifier. If specified, proxy settings for that
protocol are loaded from environment variables, and C<$conn> is
created.

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

C<proxy> and C<no_proxy> options have precedence over C<env_proxy>
option.

=back

=head1 OBJECT METHOD

=head2 $guard = $conn->tcp_connect($host, $port, $connect_cb, $prepare_cb)

Make a (possibly proxied) TCP connection to the given C<$host> and
C<$port>.

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

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

=over

=item *

It connects to the proxy, and tells the proxy to connect to the final
destination, C<$host> and C<$port>.

=item *

It runs C<$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)

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

=item *

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

=item *

If given, it runs C<$prepare_cb> before it starts connecting to the
proxy.

=back

=head2 $proxy = $conn->proxy_for($host, $port)

If C<$conn> uses a proxy to connect to the given C<$host> and
C<$port>, it returns the string of the proxy URL. Otherwise, it
returns C<undef>.