From 78cc7d3d11dfc24b65bc21378299f6f2777631bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Sat, 10 Feb 2018 12:18:37 +0100 Subject: [PATCH] Improve documentation --- README.md | 105 ++++++++++++++++++-------------------------------- composer.json | 2 +- 2 files changed, 39 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index 05db113..a1acb6d 100644 --- a/README.md +++ b/README.md @@ -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) @@ -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` 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 @@ -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` +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: @@ -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); @@ -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( @@ -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); @@ -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 @@ -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. @@ -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 @@ -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 @@ -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 @@ -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: @@ -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/). diff --git a/composer.json b/composer.json index 51f0be0..f95eba5 100644 --- a/composer.json +++ b/composer.json @@ -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",