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

Improve documentation #19

Merged
merged 1 commit into from
Feb 12, 2018
Merged

Improve documentation #19

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
105 changes: 38 additions & 67 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,12 @@
# clue/http-proxy-react [![Build Status](https://travis-ci.org/clue/php-http-proxy-react.svg?branch=master)](https://travis-ci.org/clue/php-http-proxy-react)

Async HTTP CONNECT proxy connector, use any TCP/IP protocol through an HTTP proxy server, built on top of [ReactPHP](http://reactphp.org).
Async HTTP proxy connector, use any TCP/IP protocol through an HTTP CONNECT proxy server,
built on top of [ReactPHP](https://reactphp.org).

**Table of contents**

* [Quickstart example](#quickstart-example)
* [Usage](#usage)
* [ConnectorInterface](#connectorinterface)
* [connect()](#connect)
* [ProxyConnector](#proxyconnector)
* [Plain TCP connections](#plain-tcp-connections)
* [Secure TLS connections](#secure-tls-connections)
Expand Down Expand Up @@ -49,45 +48,6 @@ See also the [examples](examples).

## Usage

### ConnectorInterface

The `ConnectorInterface` is responsible for providing an interface for
establishing streaming connections, such as a normal TCP/IP connection.

In order to use this library, you should understand how this integrates with its
ecosystem.
This base interface is actually defined in React's
[Socket component](https://github.com/reactphp/socket) and used
throughout React's ecosystem.

Most higher-level components (such as HTTP, database or other networking
service clients) accept an instance implementing this interface to create their
TCP/IP connection to the underlying networking service.
This is usually done via dependency injection, so it's fairly simple to actually
swap this implementation against this library in order to connect through an
HTTP CONNECT proxy.

The interface only offers a single method:

#### connect()

The `connect(string $uri): PromiseInterface<ConnectionInterface, Exception>` method
can be used to establish a streaming connection.
It returns a [Promise](https://github.com/reactphp/promise) which either
fulfills with a [ConnectionInterface](https://github.com/reactphp/socket#connectioninterface) or
rejects with an `Exception`:

```php
$connector->connect('google.com:443')->then(
function (ConnectionInterface $stream) {
// connection successfully established
},
function (Exception $error) {
// failed to connect due to $error
}
);
```

### ProxyConnector

The `ProxyConnector` is responsible for creating plain TCP/IP connections to
Expand All @@ -107,14 +67,23 @@ $proxy = new ProxyConnector('http://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.
servers use custom ports (often the alternative HTTP port `8080`).
In its most simple form, the given connector will be a
[`\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.
Because it implements the the [`ConnectorInterface`](#connectorinterface), it
can simply be used in place of a normal connector.
Because it implements ReactPHP's standard
[`ConnectorInterface`](https://github.com/reactphp/socket#connectorinterface),
it can simply be used in place of a normal connector.
Accordingly, it provides only a single public method, the
[`connect()`](https://github.com/reactphp/socket#connect) method.
The `connect(string $uri): PromiseInterface<ConnectionInterface, Exception>`
method can be used to establish a streaming connection.
It returns a [Promise](https://github.com/reactphp/promise) which either
fulfills with a [ConnectionInterface](https://github.com/reactphp/socket#connectioninterface)
on success or rejects with an `Exception` on error.

This makes it fairly simple to add HTTP CONNECT proxy support to pretty much any
higher-level component:

Expand All @@ -126,12 +95,11 @@ higher-level component:

#### Plain TCP connections

This is most frequently used to issue HTTPS requests to your destination.
HTTP CONNECT proxies are 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.

The `ProxyConnector` implements the [`ConnectorInterface`](#connectorinterface) and
hence provides a single public method, the [`connect()`](#connect) method.
As documented above, you can simply invoke its `connect()` method to establish
a streaming plain TCP/IP connection and use any higher level protocol like so:

```php
$proxy = new ProxyConnector('http://127.0.0.1:8080', $connector);
Expand All @@ -145,7 +113,7 @@ $proxy->connect('tcp://smtp.googlemail.com:587')->then(function (ConnectionInter
```

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):
in ReactPHP's [`Connector`](https://github.com/reactphp/socket#connector):

```php
$connector = new Connector($loop, array(
Expand All @@ -166,10 +134,11 @@ 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 React's
[`Connector`](https://github.com/reactphp/socket#connector) or the low-level
[`SecureConnector`](https://github.com/reactphp/socket#secureconnector):
This class can also be used if you want to establish a secure TLS connection
(formerly known as SSL) between you and your destination, such as when using
secure HTTPS to your destination site. You can simply wrap this connector in
ReactPHP's [`Connector`](https://github.com/reactphp/socket#connector) or the
low-level [`SecureConnector`](https://github.com/reactphp/socket#secureconnector):

```php
$proxy = new ProxyConnector('http://127.0.0.1:8080', $connector);
Expand All @@ -186,7 +155,7 @@ $connector->connect('tls://smtp.googlemail.com:465')->then(function (ConnectionI
});
```

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

#### Connection timeout
Expand All @@ -199,7 +168,7 @@ 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)
You can use ReactPHP'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.
Expand All @@ -220,7 +189,7 @@ $connector->connect('tcp://google.com:80')->then(function ($stream) {

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

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

#### DNS resolution
Expand All @@ -242,7 +211,7 @@ 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
However, wrapping the `ProxyConnector` in ReactPHP'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
Expand All @@ -265,7 +234,7 @@ $connector = Connector($loop, array(
));
```

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

#### Authentication
Expand Down Expand Up @@ -306,7 +275,7 @@ setup, because you can still establish a TLS connection between you and the
destination host as above.

If you want to connect to a (rather rare) HTTPS proxy, you may want use the
`https://` scheme (HTTPS default port 443) and use React's
`https://` scheme (HTTPS default port 443) and use ReactPHP's
[`Connector`](https://github.com/reactphp/socket#connector) or the low-level
[`SecureConnector`](https://github.com/reactphp/socket#secureconnector)
instance to create a secure connection to the proxy:
Expand Down Expand Up @@ -359,21 +328,23 @@ MIT

## More

* If you want to learn more about how the
[`ConnectorInterface`](https://github.com/reactphp/socket#connectorinterface)
and its usual implementations look like, refer to the documentation of the underlying
[react/socket](https://github.com/reactphp/socket) component.
* If you want to learn more about processing streams of data, refer to the
documentation of the underlying
[react/stream](https://github.com/reactphp/stream) component.
* If you want to learn more about how the
[`ConnectorInterface`](#connectorinterface) and its usual implementations look
like, refer to the documentation of the underlying
[react/socket](https://github.com/reactphp/socket) component.
* As an alternative to an HTTP CONNECT proxy, you may also want to look into
using a SOCKS (SOCKS4/SOCKS5) proxy instead.
You may want to use [clue/socks-react](https://github.com/clue/php-socks-react)
which also provides an implementation of the
[`ConnectorInterface`](#connectorinterface) so that supporting either proxy
protocol should be fairly trivial.
which also provides an implementation of the same
[`ConnectorInterface`](https://github.com/reactphp/socket#connectorinterface)
so that supporting either proxy protocol should be fairly trivial.
* If you're dealing with public proxies, you'll likely have to work with mixed
quality and unreliable proxies. You may want to look into using
[clue/connection-manager-extra](https://github.com/clue/php-connection-manager-extra)
which allows retrying unreliable ones, implying connection timeouts,
concurrently working with multiple connectors and more.
* If you're looking for an end-user HTTP CONNECT proxy server daemon, you may
want to use [LeProxy](https://leproxy.org/).
2 changes: 1 addition & 1 deletion composer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "clue/http-proxy-react",
"description": "Async HTTP CONNECT proxy connector, use any TCP/IP protocol through an HTTP proxy server, built on top of ReactPHP",
"description": "Async HTTP proxy connector, use any TCP/IP protocol through an HTTP CONNECT proxy server, built on top of ReactPHP",
"keywords": ["HTTP", "CONNECT", "proxy", "ReactPHP", "async"],
"homepage": "https://github.com/clue/php-http-proxy-react",
"license": "MIT",
Expand Down