Documentation and example for HTTP CONNECT proxy

Author: clue

README.md

@@ -50,6 +50,7 @@ mess with most of the low-level details.
   * [UriInterface](#uriinterface)
   * [ResponseException](#responseexception)
 * [Advanced](#advanced)
+  * [HTTP proxy](#http-proxy)
   * [SOCKS proxy](#socks-proxy)
   * [Unix domain sockets](#unix-domain-sockets)
 * [Install](#install)
@@ -590,15 +591,32 @@ access its underlying [`ResponseInterface`](#responseinterface) object.
 
 ## Advanced
 
+### HTTP proxy
+
+You can also establish your outgoing connections through an HTTP CONNECT proxy server
+by adding a dependency to [clue/reactphp-http-proxy](https://github.com/clue/reactphp-http-proxy).
+
+HTTP CONNECT proxy servers (also commonly known as "HTTPS proxy" or "SSL proxy")
+are commonly used to tunnel HTTPS traffic through an intermediary ("proxy"), to
+conceal the origin address (anonymity) or to circumvent address blocking
+(geoblocking). While many (public) HTTP CONNECT proxy servers often limit this
+to HTTPS port`443` only, this can technically be used to tunnel any TCP/IP-based
+protocol, such as plain HTTP and TLS-encrypted HTTPS.
+
+See also the [HTTP CONNECT proxy example](examples/11-http-proxy.php).
+
 ### SOCKS proxy
 
 You can also establish your outgoing connections through a SOCKS proxy server
 by adding a dependency to [clue/reactphp-socks](https://github.com/clue/reactphp-socks).
 
-The SOCKS protocol operates at the TCP/IP layer and thus requires minimal effort at the HTTP application layer.
-This works for both plain HTTP and SSL encrypted HTTPS requests.
+The SOCKS proxy protocol family (SOCKS5, SOCKS4 and SOCKS4a) is commonly used to
+tunnel HTTP(S) traffic through an intermediary ("proxy"), to conceal the origin
+address (anonymity) or to circumvent address blocking (geoblocking). While many
+(public) SOCKS proxy servers often limit this to HTTP(S) port `80` and `443`
+only, this can technically be used to tunnel any TCP/IP-based protocol.
 
-See also the [SOCKS example](examples/11-socks-proxy.php).
+See also the [SOCKS proxy example](examples/12-socks-proxy.php).
 
 ### Unix domain sockets
 
@@ -623,7 +641,7 @@ $client->get('http://localhost/info')->then(function (ResponseInterface $respons
 });
 ```
 
-See also the [Unix Domain Sockets (UDS) example](examples/12-unix-domain-sockets.php).
+See also the [Unix Domain Sockets (UDS) example](examples/13-unix-domain-sockets.php).
 
 ## Install
 

composer.json

@@ -27,6 +27,7 @@
     },
     "require-dev": {
         "clue/block-react": "^1.0",
+        "clue/http-proxy-react": "^1.3",
         "clue/socks-react": "^0.8",
         "phpunit/phpunit": "^7.0 || ^6.4 || ^5.7 || ^4.8.35",
         "react/http": "^0.8"

examples/11-http-proxy.php

@@ -0,0 +1,29 @@
+<?php
+
+use Clue\React\Buzz\Browser;
+use Clue\React\HttpProxy\ProxyConnector as HttpConnectClient;
+use Psr\Http\Message\ResponseInterface;
+use React\EventLoop\Factory as LoopFactory;
+use React\Socket\Connector;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$loop = LoopFactory::create();
+
+// create a new HTTP CONNECT proxy client which connects to a HTTP CONNECT proxy server listening on localhost:8080
+// not already running a HTTP CONNECT proxy server? Try LeProxy.org!
+$proxy = new HttpConnectClient('127.0.0.1:8080', new Connector($loop));
+
+// create a Browser object that uses the HTTP CONNECT proxy client for connections
+$connector = new Connector($loop, array(
+    'tcp' => $proxy,
+    'dns' => false
+));
+$browser = new Browser($loop, $connector);
+
+// demo fetching HTTP headers (or bail out otherwise)
+$browser->get('https://www.google.com/')->then(function (ResponseInterface $response) {
+    echo RingCentral\Psr7\str($response);
+}, 'printf');
+
+$loop->run();

examples/11-socks-proxy.php examples/12-socks-proxy.phpexamples/11-socks-proxy.php renamed to examples/12-socks-proxy.php

@@ -5,17 +5,16 @@
 use Psr\Http\Message\ResponseInterface;
 use React\EventLoop\Factory as LoopFactory;
 use React\Socket\Connector;
-use RingCentral\Psr7;
 
 require __DIR__ . '/../vendor/autoload.php';
 
 $loop = LoopFactory::create();
 
-// create a new SOCKS client which connects to a SOCKS server listening on localhost:1080
-// not already running a SOCKS server? Try this: ssh -D 1080 localhost
+// create a new SOCKS proxy client which connects to a SOCKS proxy server listening on localhost:1080
+// not already running a SOCKS proxy server? Try LeProxy.org or this: `ssh -D 1080 localhost`
 $proxy = new SocksClient('127.0.0.1:1080', new Connector($loop));
 
-// create a Browser object that uses the SOCKS client for connections
+// create a Browser object that uses the SOCKS proxy client for connections
 $connector = new Connector($loop, array(
     'tcp' => $proxy,
     'dns' => false
@@ -24,7 +23,7 @@
 
 // demo fetching HTTP headers (or bail out otherwise)
 $browser->get('https://www.google.com/')->then(function (ResponseInterface $response) {
-    echo Psr7\str($response);
+    echo RingCentral\Psr7\str($response);
 }, 'printf');
 
 $loop->run();