---
name: "AnyEvent::Connector"
section: "3pm"
platform: "linux"
package: "libanyevent-connector-perl"
version: "0.04-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/AnyEvent::Connector"
---

# AnyEvent::Connector(3pm)

tcp\_connect with transparent proxy handling

## 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.