AnyEvent::Connector(3p)

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.