Merge pull request #19 from clue-labs/docs

Improve documentation

Author: clue

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<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
@@ -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:
 
@@ -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/).

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",