Simplify usage by making Connector optional

clue · clue · commit 60fb9671f7fb · 2021-07-22T13:05:16.000+02:00
diff --git a/README.md b/README.md
@@ -71,10 +71,7 @@ The following example code demonstrates how this library can be used to send a
 secure HTTPS request to google.com through a local HTTP proxy server:
 
 ```php
-$proxy = new Clue\React\HttpProxy\ProxyConnector(
-    '127.0.0.1:8080',
-    new React\Socket\Connector()
-);
+$proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080');
 
 $connector = new React\Socket\Connector(null, array(
     'tcp' => $proxy,
@@ -103,22 +100,34 @@ any destination by using an intermediary HTTP CONNECT proxy.
 [you] -> [proxy] -> [destination]
 ```
 
-Its constructor simply accepts an HTTP proxy URL and a connector used to connect
-to the proxy server address:
+Its constructor simply accepts an HTTP proxy URL with the proxy server address:
 
 ```php
-$proxy = new Clue\React\HttpProxy\ProxyConnector(
-    'http://127.0.0.1:8080',
-    new React\Socket\Connector()
-);
+$proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080');
 ```
 
 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 (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.
+
+If you need custom connector settings (DNS resolution, TLS parameters, timeouts,
+proxy servers etc.), you can explicitly pass a custom instance of the
+[`ConnectorInterface`](https://github.com/reactphp/socket#connectorinterface):
+
+```php
+$connector = new React\Socket\Connector(null, array(
+    'dns' => '127.0.0.1',
+    'tcp' => array(
+        'bindto' => '192.168.10.1:0'
+    ),
+    'tls' => array(
+        'verify_peer' => false,
+        'verify_peer_name' => false
+    )
+));
+
+$proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080', $connector);
+```
 
 This is the main class in this package.
 Because it implements ReactPHP's standard
@@ -137,7 +146,7 @@ higher-level component:
 
 ```diff
 - $acme = new AcmeApi($connector);
-+ $proxy = new Clue\React\HttpProxy\ProxyConnector('http://127.0.0.1:8080', $connector);
++ $proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080', $connector);
 + $acme = new AcmeApi($proxy);
 ```
 
@@ -150,10 +159,7 @@ 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 Clue\React\HttpProxy\ProxyConnector(
-    '127.0.0.1:8080',
-    new React\Socket\Connector()
-);
+$proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080');
 
 $proxy->connect('tcp://smtp.googlemail.com:587')->then(function (React\Socket\ConnectionInterface $connection) {
     $connection->write("EHLO local\r\n");
@@ -167,10 +173,7 @@ You can either use the `ProxyConnector` directly or you may want to wrap this co
 in ReactPHP's [`Connector`](https://github.com/reactphp/socket#connector):
 
 ```php
-$proxy = new Clue\React\HttpProxy\ProxyConnector(
-    '127.0.0.1:8080',
-    new React\Socket\Connector()
-);
+$proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080');
 
 $connector = new React\Socket\Connector(null, array(
     'tcp' => $proxy,
@@ -193,14 +196,10 @@ Many (public) proxy servers do in fact limit this to HTTPS (443) only.
 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):
+ReactPHP's [`Connector`](https://github.com/reactphp/socket#connector):
 
 ```php
-$proxy = new Clue\React\HttpProxy\ProxyConnector(
-    '127.0.0.1:8080',
-    new React\Socket\Connector()
-);
+$proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080');
 
 $connector = new React\Socket\Connector(null, array(
     'tcp' => $proxy,
@@ -227,10 +226,7 @@ In order to send HTTP requests, you first have to add a dependency for
 This allows you to send both plain HTTP and TLS-encrypted HTTPS requests like this:
 
 ```php
-$proxy = new Clue\React\HttpProxy\ProxyConnector(
-    '127.0.0.1:8080',
-    new React\Socket\Connector()
-);
+$proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080');
 
 $connector = new React\Socket\Connector(null, array(
     'tcp' => $proxy,
@@ -260,17 +256,12 @@ 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 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.
 It provides the same `connect()` method, but will automatically reject the
 underlying connection attempt if it takes too long:
 
 ```php
-$proxy = new Clue\React\HttpProxy\ProxyConnector(
-    '127.0.0.1:8080',
-    new React\Socket\Connector()
-);
+$proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080');
 
 $connector = new React\Socket\Connector(null, array(
     'tcp' => $proxy,
@@ -314,10 +305,7 @@ Given that remote DNS resolution is assumed to be the preferred mode, all
 other examples explicitly disable DNS resolution like this:
 
 ```php
-$proxy = new Clue\React\HttpProxy\ProxyConnector(
-    '127.0.0.1:8080',
-    new React\Socket\Connector()
-);
+$proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080');
 
 $connector = new React\Socket\Connector(null, array(
     'tcp' => $proxy,
@@ -328,10 +316,7 @@ $connector = new React\Socket\Connector(null, array(
 If you want to explicitly use *local DNS resolution*, you can use the following code:
 
 ```php
-$proxy = new Clue\React\HttpProxy\ProxyConnector(
-    '127.0.0.1:8080',
-    new React\Socket\Connector()
-);
+$proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080');
 
 // set up Connector which uses Google's public DNS (8.8.8.8)
 $connector = new React\Socket\Connector(null, array(
@@ -349,10 +334,7 @@ If your HTTP proxy server requires authentication, you may pass the username and
 password as part of the HTTP proxy URL like this:
 
 ```php
-$proxy = new Clue\React\HttpProxy\ProxyConnector(
-    'http://user:pass@127.0.0.1:8080',
-    new React\Socket\Connector()
-);
+$proxy = new Clue\React\HttpProxy\ProxyConnector('user:pass@127.0.0.1:8080');
 ```
 
 Note that both the username and password must be percent-encoded if they contain
@@ -361,11 +343,9 @@ special characters:
 ```php
 $user = 'he:llo';
 $pass = 'p@ss';
+$url = rawurlencode($user) . ':' . rawurlencode($pass) . '@127.0.0.1:8080';
 
-$proxy = new Clue\React\HttpProxy\ProxyConnector(
-    rawurlencode($user) . ':' . rawurlencode($pass) . '@127.0.0.1:8080',
-    $connector
-);
+$proxy = new Clue\React\HttpProxy\ProxyConnector($url);
 ```
 
 > The authentication details will be used for basic authentication and will be
@@ -388,7 +368,7 @@ you may simply pass an assoc array of additional request headers like this:
 ```php
 $proxy = new Clue\React\HttpProxy\ProxyConnector(
     '127.0.0.1:8080',
-    $connector,
+    null,
     array(
         'Proxy-Authorization' => 'Bearer abc123',
         'User-Agent' => 'ReactPHP'
@@ -404,16 +384,10 @@ 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 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:
+`https://` scheme (HTTPS default port 443) to create a secure connection to the proxy:
 
 ```php
-$proxy = new Clue\React\HttpProxy\ProxyConnector(
-    'https://127.0.0.1:443',
-    new React\Socket\Connector()
-);
+$proxy = new Clue\React\HttpProxy\ProxyConnector('https://127.0.0.1:443');
 
 $proxy->connect('tcp://smtp.googlemail.com:587');
 ```
@@ -430,10 +404,7 @@ having to rely on explicit [authentication](#authentication).
 You can simply use the `http+unix://` URI scheme like this:
 
 ```php
-$proxy = new Clue\React\HttpProxy\ProxyConnector(
-    'http+unix:///tmp/proxy.sock',
-    new React\Socket\Connector()
-);
+$proxy = new Clue\React\HttpProxy\ProxyConnector('http+unix:///tmp/proxy.sock');
 
 $proxy->connect('tcp://google.com:80')->then(function (React\Socket\ConnectionInterface $connection) {
     // connected…
@@ -444,10 +415,7 @@ Similarly, you can also combine this with [authentication](#authentication)
 like this:
 
 ```php
-$proxy = new Clue\React\HttpProxy\ProxyConnector(
-    'http+unix://user:pass@/tmp/proxy.sock',
-    new React\Socket\Connector()
-);
+$proxy = new Clue\React\HttpProxy\ProxyConnector('http+unix://user:pass@/tmp/proxy.sock');
 ```
 
 > Note that Unix domain sockets (UDS) are considered advanced usage and PHP only
diff --git a/examples/01-http-request.php b/examples/01-http-request.php
@@ -21,10 +21,7 @@
     $url = 'localhost:8080';
 }
 
-$proxy = new Clue\React\HttpProxy\ProxyConnector(
-    $url,
-    new React\Socket\Connector()
-);
+$proxy = new Clue\React\HttpProxy\ProxyConnector($url);
 
 $connector = new React\Socket\Connector(null, array(
     'tcp' => $proxy,
diff --git a/examples/02-optional-proxy-http-request.php b/examples/02-optional-proxy-http-request.php
@@ -18,10 +18,7 @@
 $connector = null;
 $url = getenv('http_proxy');
 if ($url !== false) {
-    $proxy = new Clue\React\HttpProxy\ProxyConnector(
-        $url,
-        new React\Socket\Connector()
-    );
+    $proxy = new Clue\React\HttpProxy\ProxyConnector($url);
 
     $connector = new React\Socket\Connector(null, array(
         'tcp' => $proxy,
diff --git a/examples/11-proxy-raw-https-protocol.php b/examples/11-proxy-raw-https-protocol.php
@@ -24,10 +24,7 @@
     $url = 'localhost:8080';
 }
 
-$proxy = new Clue\React\HttpProxy\ProxyConnector(
-    $url,
-    new React\Socket\Connector()
-);
+$proxy = new Clue\React\HttpProxy\ProxyConnector($url);
 
 $connector = new React\Socket\Connector(null, array(
     'tcp' => $proxy,
diff --git a/examples/12-optional-proxy-raw-https-protocol.php b/examples/12-optional-proxy-raw-https-protocol.php
@@ -22,20 +22,17 @@
 
 require __DIR__ . '/../vendor/autoload.php';
 
-$connector = new React\Socket\Connector();
-
 $url = getenv('http_proxy');
 if ($url !== false) {
-    $proxy = new Clue\React\HttpProxy\ProxyConnector(
-        $url,
-        $connector
-    );
+    $proxy = new Clue\React\HttpProxy\ProxyConnector($url);
 
     $connector = new React\Socket\Connector(null, array(
         'tcp' => $proxy,
         'timeout' => 3.0,
         'dns' => false
     ));
+} else {
+    $connector = new React\Socket\Connector();
 }
 
 $connector->connect('tls://google.com:443')->then(function (React\Socket\ConnectionInterface $connection) {
diff --git a/examples/13-custom-proxy-headers.php b/examples/13-custom-proxy-headers.php
@@ -26,7 +26,7 @@
 
 $proxy = new Clue\React\HttpProxy\ProxyConnector(
     $url,
-    new React\Socket\Connector(),
+    null,
     array(
         'X-Custom-Header-1' => 'Value-1',
         'X-Custom-Header-2' => 'Value-2',
diff --git a/examples/21-proxy-raw-smtp-protocol.php b/examples/21-proxy-raw-smtp-protocol.php
@@ -23,10 +23,7 @@
     $url = 'localhost:8080';
 }
 
-$proxy = new Clue\React\HttpProxy\ProxyConnector(
-    $url,
-    new React\Socket\Connector()
-);
+$proxy = new Clue\React\HttpProxy\ProxyConnector($url);
 
 $connector = new React\Socket\Connector(null, array(
     'tcp' => $proxy,
diff --git a/examples/22-proxy-raw-smtps-protocol.php b/examples/22-proxy-raw-smtps-protocol.php
@@ -26,10 +26,7 @@
     $url = 'localhost:8080';
 }
 
-$proxy = new Clue\React\HttpProxy\ProxyConnector(
-    $url,
-    new React\Socket\Connector()
-);
+$proxy = new Clue\React\HttpProxy\ProxyConnector($url);
 
 $connector = new React\Socket\Connector(null, array(
     'tcp' => $proxy,
diff --git a/src/ProxyConnector.php b/src/ProxyConnector.php
@@ -9,8 +9,10 @@
 use React\Promise;
 use React\Promise\Deferred;
 use React\Socket\ConnectionInterface;
+use React\Socket\Connector;
 use React\Socket\ConnectorInterface;
 use React\Socket\FixedUriConnector;
+use React\Socket\UnixConnector;
 
 /**
  * A simple Connector that uses an HTTP CONNECT proxy to create plain TCP/IP connections to any destination
@@ -51,13 +53,11 @@ class ProxyConnector implements ConnectorInterface
      * @param string $proxyUrl 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.
-     * @param ConnectorInterface $connector In its most simple form, the given
-     *     connector will be a \React\Socket\Connector if you want to connect to
-     *     a given IP address.
+     * @param ?ConnectorInterface $connector (Optional) Connector to use.
      * @param array $httpHeaders Custom HTTP headers to be sent to the proxy.
      * @throws InvalidArgumentException if the proxy URL is invalid
      */
-    public function __construct($proxyUrl, ConnectorInterface $connector, array $httpHeaders = array())
+    public function __construct($proxyUrl, ConnectorInterface $connector = null, array $httpHeaders = array())
     {
         // support `http+unix://` scheme for Unix domain socket (UDS) paths
         if (preg_match('/^http\+unix:\/\/(.*?@)?(.+?)$/', $proxyUrl, $match)) {
@@ -67,7 +67,7 @@ public function __construct($proxyUrl, ConnectorInterface $connector, array $htt
             // connector uses Unix transport scheme and explicit path given
             $connector = new FixedUriConnector(
                 'unix://' . $match[2],
-                $connector
+                $connector ?: new UnixConnector()
             );
         }
 
@@ -86,7 +86,7 @@ public function __construct($proxyUrl, ConnectorInterface $connector, array $htt
         }
         $parts['scheme'] = $parts['scheme'] === 'https' ? 'tls' : 'tcp';
 
-        $this->connector = $connector;
+        $this->connector = $connector ?: new Connector();
         $this->proxyUri = $parts['scheme'] . '://' . $parts['host'] . ':' . $parts['port'];
 
         // prepare Proxy-Authorization header if URI contains username/password
diff --git a/tests/FunctionalTest.php b/tests/FunctionalTest.php
diff --git a/tests/ProxyConnectorTest.php b/tests/ProxyConnectorTest.php
