Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation for Connector concepts (TCP/TLS, timeouts, DNS resolution) #11

Merged
merged 3 commits into from
Jun 9, 2017
Merged

Documentation for Connector concepts (TCP/TLS, timeouts, DNS resolution) #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
45a7a24
Use main Connector class where possible
clue May 9, 2017
57d2137
Add chapters for plain TCP and secure TLS connections
clue Jun 8, 2017
01013ff
Documentation for connection timeouts and DNS resolution
clue Jun 8, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
146 changes: 133 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,11 @@ Async HTTP CONNECT proxy connector, use any TCP/IP protocol through an HTTP prox
* [ConnectorInterface](#connectorinterface)
* [connect()](#connect)
* [ProxyConnector](#proxyconnector)
* [Plain TCP connections](#plain-tcp-connections)
* [Secure TLS connections](#secure-tls-connections)
* [Connection timeout](#connection-timeout)
* [DNS resolution](#dns-resolution)
* [Advanced secure proxy connections](#advanced-secure-proxy-connections)
* [Install](#install)
* [Tests](#tests)
* [License](#license)
Expand All @@ -21,11 +26,15 @@ secure HTTPS request to google.com through a local HTTP proxy server:

```php
$loop = React\EventLoop\Factory::create();
$connector = new TcpConnector($loop);
$proxy = new ProxyConnector('127.0.0.1:8080', $connector);
$ssl = new SecureConnector($proxy, $loop);

$ssl->connect('google.com:443')->then(function (ConnectionInterface $stream) {
$proxy = new ProxyConnector('127.0.0.1:8080', new Connector($loop));
$connector = new Connector($loop, array(
'tcp' => $proxy,
'timeout' => 3.0,
'dns' => false
));

$connector->connect('tls://google.com:443')->then(function (ConnectionInterface $stream) {
$stream->write("GET / HTTP/1.1\r\nHost: google.com\r\nConnection: close\r\n\r\n");
$stream->on('data', function ($chunk) {
echo $chunk;
Expand Down Expand Up @@ -91,15 +100,15 @@ Its constructor simply accepts an HTTP proxy URL and a connector used to connect
to the proxy server address:

```php
$connector = new TcpConnector($loop);
$connector = new Connector($loop);
$proxy = new ProxyConnector('127.0.0.1:8080', $connector);
```

The proxy URL may or may not contain a scheme and port definition. The default
port will be `80` for HTTP (or `443` for HTTPS), but many common HTTP proxy
servers use custom ports.
In its most simple form, the given connector will be a
[`TcpConnector`](https://github.com/reactphp/socket#tcpconnector) if you
[`\React\Socket\Connector`](https://github.com/reactphp/socket#connector) if you
want to connect to a given IP address as above.

This is the main class in this package.
Expand All @@ -114,14 +123,36 @@ higher-level component:
+ $client = new SomeClient($proxy);
```

#### Plain TCP connections

This is most frequently used to issue HTTPS requests to your destination.
However, this is actually performed on a higher protocol layer and this
connector is actually inherently a general-purpose plain TCP/IP connector:
connector is actually inherently a general-purpose plain TCP/IP connector.

The `ProxyConnector` implements the [`ConnectorInterface`](#connectorinterface) and
hence provides a single public method, the [`connect()`](#connect) method.

```php
$proxy = new ProxyConnector('127.0.0.1:8080', $connector);

$proxy->connect('smtp.googlemail.com:587')->then(function (ConnectionInterface $stream) {
$proxy->connect('tcp://smtp.googlemail.com:587')->then(function (ConnectionInterface $stream) {
$stream->write("EHLO local\r\n");
$stream->on('data', function ($chunk) use ($stream) {
echo $chunk;
});
});
```

You can either use the `ProxyConnector` directly or you may want to wrap this connector
in React's [`Connector`](https://github.com/reactphp/socket#connector):

```php
$connector = new Connector($loop, array(
'tcp' => $proxy,
'dns' => false
));

$connector->connect('tcp://smtp.googlemail.com:587')->then(function (ConnectionInterface $stream) {
$stream->write("EHLO local\r\n");
$stream->on('data', function ($chunk) use ($stream) {
echo $chunk;
Expand All @@ -132,23 +163,112 @@ $proxy->connect('smtp.googlemail.com:587')->then(function (ConnectionInterface $
Note that HTTP CONNECT proxies often restrict which ports one may connect to.
Many (public) proxy servers do in fact limit this to HTTPS (443) only.

#### Secure TLS connections

If you want to establish a TLS connection (such as HTTPS) between you and
your destination, you may want to wrap this connector in a
[`SecureConnector`](https://github.com/reactphp/socket#secureconnector)
instance:
your destination, you may want to wrap this connector in React's
[`Connector`](https://github.com/reactphp/socket#connector) or the low-level
[`SecureConnector`](https://github.com/reactphp/socket#secureconnector):

```php
$proxy = new ProxyConnector('127.0.0.1:8080', $connector);
$ssl = new SecureConnector($proxy, $loop);
$connector = new Connector($loop, array(
'tcp' => $proxy,
'dns' => false
));

$ssl->connect('smtp.googlemail.com:465')->then(function (ConnectionInterface $stream) {
$connector->connect('tls://smtp.googlemail.com:465')->then(function (ConnectionInterface $stream) {
$stream->write("EHLO local\r\n");
$stream->on('data', function ($chunk) use ($stream) {
echo $chunk;
});
});
```

> Also note how secure TLS connections are in fact entirely handled outside of
this HTTP CONNECT client implementation.

#### Connection timeout

By default, the `ProxyConnector` does not implement any timeouts for establishing remote
connections.
Your underlying operating system may impose limits on pending and/or idle TCP/IP
connections, anywhere in a range of a few minutes to several hours.

Many use cases require more control over the timeout and likely values much
smaller, usually in the range of a few seconds only.

You can use React's [`Connector`](https://github.com/reactphp/socket#connector)
or the low-level
[`TimeoutConnector`](https://github.com/reactphp/socket#timeoutconnector)
to decorate any given `ConnectorInterface` instance.
It provides the same `connect()` method, but will automatically reject the
underlying connection attempt if it takes too long:

```php
$connector = new Connector($loop, array(
'tcp' => $proxy,
'dns' => false,
'timeout' => 3.0
));

$connector->connect('tcp://google.com:80')->then(function ($stream) {
// connection succeeded within 3.0 seconds
});
```

See also any of the [examples](examples).

> Also note how connection timeout is in fact entirely handled outside of this
HTTP CONNECT client implementation.

#### DNS resolution

By default, the `ProxyConnector` does not perform any DNS resolution at all and simply
forwards any hostname you're trying to connect to the remote proxy server.
The remote proxy server is thus responsible for looking up any hostnames via DNS
(this default mode is thus called *remote DNS resolution*).

As an alternative, you can also send the destination IP to the remote proxy
server.
In this mode you either have to stick to using IPs only (which is ofen unfeasable)
or perform any DNS lookups locally and only transmit the resolved destination IPs
(this mode is thus called *local DNS resolution*).

The default *remote DNS resolution* is useful if your local `ProxyConnector` either can
not resolve target hostnames because it has no direct access to the internet or
if it should not resolve target hostnames because its outgoing DNS traffic might
be intercepted.

As noted above, the `ProxyConnector` defaults to using remote DNS resolution.
However, wrapping the `ProxyConnector` in React's
[`Connector`](https://github.com/reactphp/socket#connector) actually
performs local DNS resolution unless explicitly defined otherwise.
Given that remote DNS resolution is assumed to be the preferred mode, all
other examples explicitly disable DNS resoltion like this:

```php
$connector = new Connector($loop, array(
'tcp' => $proxy,
'dns' => false
));
```

If you want to explicitly use *local DNS resolution*, you can use the following code:

```php
// set up Connector which uses Google's public DNS (8.8.8.8)
$connector = Connector($loop, array(
'tcp' => $proxy,
'dns' => '8.8.8.8'
));
```

> Also note how local DNS resolution is in fact entirely handled outside of this
HTTP CONNECT client implementation.

#### Advanced secure proxy connections

Note that communication between the client and the proxy is usually via an
unencrypted, plain TCP/IP HTTP connection. Note that this is the most common
setup, because you can still establish a TLS connection between you and the
Expand Down
14 changes: 8 additions & 6 deletions examples/01-proxy-https.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,7 @@
// The proxy can be given as first argument and defaults to localhost:8080 otherwise.

use Clue\React\HttpProxy\ProxyConnector;
use React\Socket\TcpConnector;
use React\Socket\SecureConnector;
use React\Socket\Connector;
use React\Socket\ConnectionInterface;

require __DIR__ . '/../vendor/autoload.php';
Expand All @@ -14,11 +13,14 @@

$loop = React\EventLoop\Factory::create();

$connector = new TcpConnector($loop);
$proxy = new ProxyConnector($url, $connector);
$ssl = new SecureConnector($proxy, $loop);
$proxy = new ProxyConnector($url, new Connector($loop));
$connector = new Connector($loop, array(
'tcp' => $proxy,
'timeout' => 3.0,
'dns' => false
));

$ssl->connect('google.com:443')->then(function (ConnectionInterface $stream) {
$connector->connect('tls://google.com:443')->then(function (ConnectionInterface $stream) {
$stream->write("GET / HTTP/1.1\r\nHost: google.com\r\nConnection: close\r\n\r\n");
$stream->on('data', function ($chunk) {
echo $chunk;
Expand Down
22 changes: 9 additions & 13 deletions examples/02-optional-proxy-https.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,30 +8,26 @@
// network protocol otherwise.

use Clue\React\HttpProxy\ProxyConnector;
use React\Socket\TcpConnector;
use React\Socket\SecureConnector;
use React\Socket\DnsConnector;
use React\Dns\Resolver\Factory;
use React\Socket\Connector;
use React\Socket\ConnectionInterface;

require __DIR__ . '/../vendor/autoload.php';

$loop = React\EventLoop\Factory::create();

$tcp = new TcpConnector($loop);
$dnsFactory = new Factory();
$resolver = $dnsFactory->create('8.8.8.8', $loop);
$dns = new DnsConnector($tcp, $resolver);
$connector = new Connector($loop);

// first argument given? use this as the proxy URL
if (isset($argv[1])) {
$proxy = new ProxyConnector($argv[1], $dns);
$connector = new SecureConnector($proxy, $loop);
} else {
$connector = new SecureConnector($dns, $loop);
$proxy = new ProxyConnector($argv[1], $connector);
$connector = new Connector($loop, array(
'tcp' => $proxy,
'timeout' => 3.0,
'dns' => false
));
}

$connector->connect('google.com:443')->then(function (ConnectionInterface $stream) {
$connector->connect('tls://google.com:443')->then(function (ConnectionInterface $stream) {
$stream->write("GET / HTTP/1.1\r\nHost: google.com\r\nConnection: close\r\n\r\n");
$stream->on('data', function ($chunk) {
echo $chunk;
Expand Down
12 changes: 8 additions & 4 deletions examples/11-proxy-smtp.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
// Please note that MANY public proxies do not allow SMTP connections, YMMV.

use Clue\React\HttpProxy\ProxyConnector;
use React\Socket\TcpConnector;
use React\Socket\Connector;
use React\Socket\ConnectionInterface;

require __DIR__ . '/../vendor/autoload.php';
Expand All @@ -14,10 +14,14 @@

$loop = React\EventLoop\Factory::create();

$connector = new TcpConnector($loop);
$proxy = new ProxyConnector($url, $connector);
$proxy = new ProxyConnector($url, new Connector($loop));
$connector = new Connector($loop, array(
'tcp' => $proxy,
'timeout' => 3.0,
'dns' => false
));

$proxy->connect('smtp.googlemail.com:587')->then(function (ConnectionInterface $stream) {
$connector->connect('tcp://smtp.googlemail.com:587')->then(function (ConnectionInterface $stream) {
$stream->write("EHLO local\r\n");
$stream->on('data', function ($chunk) use ($stream) {
echo $chunk;
Expand Down
14 changes: 8 additions & 6 deletions examples/12-proxy-smtps.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,7 @@
// Please note that MANY public proxies do not allow SMTP connections, YMMV.

use Clue\React\HttpProxy\ProxyConnector;
use React\Socket\TcpConnector;
use React\Socket\SecureConnector;
use React\Socket\Connector;
use React\Socket\ConnectionInterface;

require __DIR__ . '/../vendor/autoload.php';
Expand All @@ -18,11 +17,14 @@

$loop = React\EventLoop\Factory::create();

$connector = new TcpConnector($loop);
$proxy = new ProxyConnector($url, $connector);
$ssl = new SecureConnector($proxy, $loop);
$proxy = new ProxyConnector($url, new Connector($loop));
$connector = new Connector($loop, array(
'tcp' => $proxy,
'timeout' => 3.0,
'dns' => false
));

$ssl->connect('smtp.googlemail.com:465')->then(function (ConnectionInterface $stream) {
$connector->connect('tls://smtp.googlemail.com:465')->then(function (ConnectionInterface $stream) {
$stream->write("EHLO local\r\n");
$stream->on('data', function ($chunk) use ($stream) {
echo $chunk;
Expand Down
4 changes: 2 additions & 2 deletions src/ProxyConnector.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,8 @@ class ProxyConnector implements ConnectorInterface
* port definition. The default port will be `80` for HTTP (or `443` for
* HTTPS), but many common HTTP proxy servers use custom ports.
* @param ConnectorInterface $connector In its most simple form, the given
* connector will be a TcpConnector if you want to connect to a given IP
* address.
* connector will be a \React\Socket\Connector if you want to connect to
* a given IP address.
* @throws InvalidArgumentException if the proxy URL is invalid
*/
public function __construct($proxyUrl, ConnectorInterface $connector)
Expand Down