Debian Codegraph @

vendor/clue/http-proxy-react/README.md

raw
1 # clue/reactphp-http-proxy
2
3 [![CI status](https://github.com/clue/reactphp-http-proxy/actions/workflows/ci.yml/badge.svg)](https://github.com/clue/reactphp-http-proxy/actions)
4 [![code coverage](https://img.shields.io/badge/code%20coverage-100%25-success)](#tests)
5 [![installs on Packagist](https://img.shields.io/packagist/dt/clue/http-proxy-react?color=blue&label=installs%20on%20Packagist)](https://packagist.org/packages/clue/http-proxy-react)
6
7 Async HTTP proxy connector, tunnel any TCP/IP-based protocol through an HTTP
8 CONNECT proxy server, built on top of [ReactPHP](https://reactphp.org/).
9
10 HTTP CONNECT proxy servers (also commonly known as "HTTPS proxy" or "SSL proxy")
11 are commonly used to tunnel HTTPS traffic through an intermediary ("proxy"), to
12 conceal the origin address (anonymity) or to circumvent address blocking
13 (geoblocking). While many (public) HTTP CONNECT proxy servers often limit this
14 to HTTPS port `443` only, this can technically be used to tunnel any
15 TCP/IP-based protocol (HTTP, SMTP, IMAP etc.).
16 This library provides a simple API to create these tunneled connections for you.
17 Because it implements ReactPHP's standard
18 [`ConnectorInterface`](https://github.com/reactphp/socket#connectorinterface),
19 it can simply be used in place of a normal connector.
20 This makes it fairly simple to add HTTP CONNECT proxy support to pretty much any
21 existing higher-level protocol implementation.
22
23 * **Async execution of connections** -
24 Send any number of HTTP CONNECT requests in parallel and process their
25 responses as soon as results come in.
26 The Promise-based design provides a *sane* interface to working with out of
27 order responses and possible connection errors.
28 * **Standard interfaces** -
29 Allows easy integration with existing higher-level components by implementing
30 ReactPHP's standard
31 [`ConnectorInterface`](https://github.com/reactphp/socket#connectorinterface).
32 * **Lightweight, SOLID design** -
33 Provides a thin abstraction that is [*just good enough*](https://en.wikipedia.org/wiki/Principle_of_good_enough)
34 and does not get in your way.
35 Builds on top of well-tested components and well-established concepts instead of reinventing the wheel.
36 * **Good test coverage** -
37 Comes with an automated tests suite and is regularly tested against actual proxy servers in the wild.
38
39 **Table of contents**
40
41 * [Support us](#support-us)
42 * [Quickstart example](#quickstart-example)
43 * [Usage](#usage)
44 * [ProxyConnector](#proxyconnector)
45 * [Plain TCP connections](#plain-tcp-connections)
46 * [Secure TLS connections](#secure-tls-connections)
47 * [HTTP requests](#http-requests)
48 * [Connection timeout](#connection-timeout)
49 * [DNS resolution](#dns-resolution)
50 * [Authentication](#authentication)
51 * [Advanced HTTP headers](#advanced-http-headers)
52 * [Advanced secure proxy connections](#advanced-secure-proxy-connections)
53 * [Advanced Unix domain sockets](#advanced-unix-domain-sockets)
54 * [Install](#install)
55 * [Tests](#tests)
56 * [License](#license)
57 * [More](#more)
58
59 ## Support us
60
61 I maintain an ecosystem of open-source projects that have been downloaded
62 hundreds of millions of times and are actively maintained and continuously
63 improved. If you find any of these projects useful, please consider
64 [becoming a sponsor on GitHub](https://github.com/sponsors/clue). Your support
65 helps ensure long-term maintenance and continued development. Thank you! 🚀
66
67 ## Quickstart example
68
69 The following example code demonstrates how this library can be used to send a
70 secure HTTPS request to google.com through a local HTTP proxy server:
71
72 ```php
73 <?php
74
75 require __DIR__ . '/vendor/autoload.php';
76
77 $proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080');
78
79 $connector = new React\Socket\Connector(array(
80 'tcp' => $proxy,
81 'dns' => false
82 ));
83
84 $browser = new React\Http\Browser($connector);
85
86 $browser->get('https://google.com/')->then(function (Psr\Http\Message\ResponseInterface $response) {
87 var_dump($response->getHeaders(), (string) $response->getBody());
88 }, function (Exception $e) {
89 echo 'Error: ' . $e->getMessage() . PHP_EOL;
90 });
91 ```
92
93 See also the [examples](examples).
94
95 ## Usage
96
97 ### ProxyConnector
98
99 The `ProxyConnector` is responsible for creating plain TCP/IP connections to
100 any destination by using an intermediary HTTP CONNECT proxy.
101
102 ```
103 [you] -> [proxy] -> [destination]
104 ```
105
106 Its constructor simply accepts an HTTP proxy URL with the proxy server address:
107
108 ```php
109 $proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080');
110 ```
111
112 The proxy URL may or may not contain a scheme and port definition. The default
113 port will be `80` for HTTP (or `443` for HTTPS), but many common HTTP proxy
114 servers use custom ports (often the alternative HTTP port `8080`).
115
116 If you need custom connector settings (DNS resolution, TLS parameters, timeouts,
117 proxy servers etc.), you can explicitly pass a custom instance of the
118 [`ConnectorInterface`](https://github.com/reactphp/socket#connectorinterface):
119
120 ```php
121 $connector = new React\Socket\Connector(array(
122 'dns' => '127.0.0.1',
123 'tcp' => array(
124 'bindto' => '192.168.10.1:0'
125 ),
126 'tls' => array(
127 'verify_peer' => false,
128 'verify_peer_name' => false
129 )
130 ));
131
132 $proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080', $connector);
133 ```
134
135 This is the main class in this package.
136 Because it implements ReactPHP's standard
137 [`ConnectorInterface`](https://github.com/reactphp/socket#connectorinterface),
138 it can simply be used in place of a normal connector.
139 Accordingly, it provides only a single public method, the
140 [`connect()`](https://github.com/reactphp/socket#connect) method.
141 The `connect(string $uri): PromiseInterface<ConnectionInterface, Exception>`
142 method can be used to establish a streaming connection.
143 It returns a [Promise](https://github.com/reactphp/promise) which either
144 fulfills with a [ConnectionInterface](https://github.com/reactphp/socket#connectioninterface)
145 on success or rejects with an `Exception` on error.
146
147 This makes it fairly simple to add HTTP CONNECT proxy support to pretty much any
148 higher-level component:
149
150 ```diff
151 - $acme = new AcmeApi($connector);
152 + $proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080', $connector);
153 + $acme = new AcmeApi($proxy);
154 ```
155
156 #### Plain TCP connections
157
158 HTTP CONNECT proxies are most frequently used to issue HTTPS requests to your destination.
159 However, this is actually performed on a higher protocol layer and this
160 connector is actually inherently a general-purpose plain TCP/IP connector.
161 As documented above, you can simply invoke its `connect()` method to establish
162 a streaming plain TCP/IP connection and use any higher level protocol like so:
163
164 ```php
165 $proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080');
166
167 $proxy->connect('tcp://smtp.googlemail.com:587')->then(function (React\Socket\ConnectionInterface $connection) {
168 $connection->write("EHLO local\r\n");
169 $connection->on('data', function ($chunk) use ($connection) {
170 echo $chunk;
171 });
172 }, function (Exception $e) {
173 echo 'Error: ' . $e->getMessage() . PHP_EOL;
174 });
175 ```
176
177 You can either use the `ProxyConnector` directly or you may want to wrap this connector
178 in ReactPHP's [`Connector`](https://github.com/reactphp/socket#connector):
179
180 ```php
181 $proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080');
182
183 $connector = new React\Socket\Connector(array(
184 'tcp' => $proxy,
185 'dns' => false
186 ));
187
188 $connector->connect('tcp://smtp.googlemail.com:587')->then(function (React\Socket\ConnectionInterface $connection) {
189 $connection->write("EHLO local\r\n");
190 $connection->on('data', function ($chunk) use ($connection) {
191 echo $chunk;
192 });
193 }, function (Exception $e) {
194 echo 'Error: ' . $e->getMessage() . PHP_EOL;
195 });
196 ```
197
198 Note that HTTP CONNECT proxies often restrict which ports one may connect to.
199 Many (public) proxy servers do in fact limit this to HTTPS (443) only.
200
201 #### Secure TLS connections
202
203 This class can also be used if you want to establish a secure TLS connection
204 (formerly known as SSL) between you and your destination, such as when using
205 secure HTTPS to your destination site. You can simply wrap this connector in
206 ReactPHP's [`Connector`](https://github.com/reactphp/socket#connector):
207
208 ```php
209 $proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080');
210
211 $connector = new React\Socket\Connector(array(
212 'tcp' => $proxy,
213 'dns' => false
214 ));
215
216 $connector->connect('tls://smtp.googlemail.com:465')->then(function (React\Socket\ConnectionInterface $connection) {
217 $connection->write("EHLO local\r\n");
218 $connection->on('data', function ($chunk) use ($connection) {
219 echo $chunk;
220 });
221 }, function (Exception $e) {
222 echo 'Error: ' . $e->getMessage() . PHP_EOL;
223 });
224 ```
225
226 > Note how secure TLS connections are in fact entirely handled outside of
227 this HTTP CONNECT client implementation.
228
229 #### HTTP requests
230
231 This library also allows you to send HTTP requests through an HTTP CONNECT proxy server.
232
233 In order to send HTTP requests, you first have to add a dependency for
234 [ReactPHP's async HTTP client](https://github.com/reactphp/http#client-usage).
235 This allows you to send both plain HTTP and TLS-encrypted HTTPS requests like this:
236
237 ```php
238 $proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080');
239
240 $connector = new React\Socket\Connector(array(
241 'tcp' => $proxy,
242 'dns' => false
243 ));
244
245 $browser = new React\Http\Browser($connector);
246
247 $browser->get('https://example.com/')->then(function (Psr\Http\Message\ResponseInterface $response) {
248 var_dump($response->getHeaders(), (string) $response->getBody());
249 }, function (Exception $e) {
250 echo 'Error: ' . $e->getMessage() . PHP_EOL;
251 });
252 ```
253
254 See also [ReactPHP's HTTP client](https://github.com/reactphp/http#client-usage)
255 and any of the [examples](examples/) for more details.
256
257 #### Connection timeout
258
259 By default, the `ProxyConnector` does not implement any timeouts for establishing remote
260 connections.
261 Your underlying operating system may impose limits on pending and/or idle TCP/IP
262 connections, anywhere in a range of a few minutes to several hours.
263
264 Many use cases require more control over the timeout and likely values much
265 smaller, usually in the range of a few seconds only.
266
267 You can use ReactPHP's [`Connector`](https://github.com/reactphp/socket#connector)
268 to decorate any given `ConnectorInterface` instance.
269 It provides the same `connect()` method, but will automatically reject the
270 underlying connection attempt if it takes too long:
271
272 ```php
273 $proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080');
274
275 $connector = new React\Socket\Connector(array(
276 'tcp' => $proxy,
277 'dns' => false,
278 'timeout' => 3.0
279 ));
280
281 $connector->connect('tcp://google.com:80')->then(function ($connection) {
282 // connection succeeded within 3.0 seconds
283 }, function (Exception $e) {
284 echo 'Error: ' . $e->getMessage() . PHP_EOL;
285 });
286 ```
287
288 See also any of the [examples](examples).
289
290 > Note how the connection timeout is in fact entirely handled outside of this
291 HTTP CONNECT client implementation.
292
293 #### DNS resolution
294
295 By default, the `ProxyConnector` does not perform any DNS resolution at all and simply
296 forwards any hostname you're trying to connect to the remote proxy server.
297 The remote proxy server is thus responsible for looking up any hostnames via DNS
298 (this default mode is thus called *remote DNS resolution*).
299
300 As an alternative, you can also send the destination IP to the remote proxy
301 server.
302 In this mode you either have to stick to using IPs only (which is ofen unfeasable)
303 or perform any DNS lookups locally and only transmit the resolved destination IPs
304 (this mode is thus called *local DNS resolution*).
305
306 The default *remote DNS resolution* is useful if your local `ProxyConnector` either can
307 not resolve target hostnames because it has no direct access to the internet or
308 if it should not resolve target hostnames because its outgoing DNS traffic might
309 be intercepted.
310
311 As noted above, the `ProxyConnector` defaults to using remote DNS resolution.
312 However, wrapping the `ProxyConnector` in ReactPHP's
313 [`Connector`](https://github.com/reactphp/socket#connector) actually
314 performs local DNS resolution unless explicitly defined otherwise.
315 Given that remote DNS resolution is assumed to be the preferred mode, all
316 other examples explicitly disable DNS resolution like this:
317
318 ```php
319 $proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080');
320
321 $connector = new React\Socket\Connector(array(
322 'tcp' => $proxy,
323 'dns' => false
324 ));
325 ```
326
327 If you want to explicitly use *local DNS resolution*, you can use the following code:
328
329 ```php
330 $proxy = new Clue\React\HttpProxy\ProxyConnector('127.0.0.1:8080');
331
332 // set up Connector which uses Google's public DNS (8.8.8.8)
333 $connector = new React\Socket\Connector(array(
334 'tcp' => $proxy,
335 'dns' => '8.8.8.8'
336 ));
337 ```
338
339 > Note how local DNS resolution is in fact entirely handled outside of this
340 HTTP CONNECT client implementation.
341
342 #### Authentication
343
344 If your HTTP proxy server requires authentication, you may pass the username and
345 password as part of the HTTP proxy URL like this:
346
347 ```php
348 $proxy = new Clue\React\HttpProxy\ProxyConnector('alice:[email protected]:8080');
349 ```
350
351 Note that both the username and password must be percent-encoded if they contain
352 special characters:
353
354 ```php
355 $user = 'he:llo';
356 $pass = 'p@ss';
357 $url = rawurlencode($user) . ':' . rawurlencode($pass) . '@127.0.0.1:8080';
358
359 $proxy = new Clue\React\HttpProxy\ProxyConnector($url);
360 ```
361
362 > The authentication details will be used for basic authentication and will be
363 transferred in the `Proxy-Authorization` HTTP request header for each
364 connection attempt.
365 If the authentication details are missing or not accepted by the remote HTTP
366 proxy server, it is expected to reject each connection attempt with a
367 `407` (Proxy Authentication Required) response status code and an exception
368 error code of `SOCKET_EACCES` (13).
369
370 #### Advanced HTTP headers
371
372 The `ProxyConnector` constructor accepts an optional array of custom request
373 headers to send in the `CONNECT` request. This can be useful if you're using a
374 custom proxy setup or authentication scheme if the proxy server does not support
375 basic [authentication](#authentication) as documented above. This is rarely used
376 in practice, but may be useful for some more advanced use cases. In this case,
377 you may simply pass an assoc array of additional request headers like this:
378
379 ```php
380 $proxy = new Clue\React\HttpProxy\ProxyConnector(
381 '127.0.0.1:8080',
382 null,
383 array(
384 'Proxy-Authorization' => 'Bearer abc123',
385 'User-Agent' => 'ReactPHP'
386 )
387 );
388 ```
389
390 #### Advanced secure proxy connections
391
392 Note that communication between the client and the proxy is usually via an
393 unencrypted, plain TCP/IP HTTP connection. Note that this is the most common
394 setup, because you can still establish a TLS connection between you and the
395 destination host as above.
396
397 If you want to connect to a (rather rare) HTTPS proxy, you may want use the
398 `https://` scheme (HTTPS default port 443) to create a secure connection to the proxy:
399
400 ```php
401 $proxy = new Clue\React\HttpProxy\ProxyConnector('https://127.0.0.1:443');
402
403 $proxy->connect('tcp://smtp.googlemail.com:587');
404 ```
405
406 #### Advanced Unix domain sockets
407
408 HTTP CONNECT proxy servers support forwarding TCP/IP based connections and
409 higher level protocols.
410 In some advanced cases, it may be useful to let your HTTP CONNECT proxy server
411 listen on a Unix domain socket (UDS) path instead of a IP:port combination.
412 For example, this allows you to rely on file system permissions instead of
413 having to rely on explicit [authentication](#authentication).
414
415 You can simply use the `http+unix://` URI scheme like this:
416
417 ```php
418 $proxy = new Clue\React\HttpProxy\ProxyConnector('http+unix:///tmp/proxy.sock');
419
420 $proxy->connect('tcp://google.com:80')->then(function (React\Socket\ConnectionInterface $connection) {
421 // connected…
422 }, function (Exception $e) {
423 echo 'Error: ' . $e->getMessage() . PHP_EOL;
424 });
425 ```
426
427 Similarly, you can also combine this with [authentication](#authentication)
428 like this:
429
430 ```php
431 $proxy = new Clue\React\HttpProxy\ProxyConnector('http+unix://alice:password@/tmp/proxy.sock');
432 ```
433
434 > Note that Unix domain sockets (UDS) are considered advanced usage and PHP only
435 has limited support for this.
436 In particular, enabling [secure TLS](#secure-tls-connections) may not be
437 supported.
438
439 > Note that the HTTP CONNECT protocol does not support the notion of UDS paths.
440 The above works reasonably well because UDS is only used for the connection between
441 client and proxy server and the path will not actually passed over the protocol.
442 This implies that this does not support connecting to UDS destination paths.
443
444 ## Install
445
446 The recommended way to install this library is [through Composer](https://getcomposer.org/).
447 [New to Composer?](https://getcomposer.org/doc/00-intro.md)
448
449 This project follows [SemVer](https://semver.org/).
450 This will install the latest supported version:
451
452 ```bash
453 composer require clue/http-proxy-react:^1.10
454 ```
455
456 See also the [CHANGELOG](CHANGELOG.md) for details about version upgrades.
457
458 This project aims to run on any platform and thus does not require any PHP
459 extensions and supports running on legacy PHP 5.3 through current PHP 8+ and
460 HHVM.
461 It's *highly recommended to use the latest supported PHP version* for this project.
462
463 ## Tests
464
465 To run the test suite, you first need to clone this repo and then install all
466 dependencies [through Composer](https://getcomposer.org/):
467
468 ```bash
469 composer install
470 ```
471
472 To run the test suite, go to the project root and run:
473
474 ```bash
475 vendor/bin/phpunit
476 ```
477
478 The test suite contains tests that rely on a working internet connection,
479 alternatively you can also run it like this:
480
481 ```bash
482 vendor/bin/phpunit --exclude-group internet
483 ```
484
485 The test suite is set up to always ensure 100% code coverage across all
486 supported environments. If you have the Xdebug extension installed, you can also
487 generate a code coverage report locally like this:
488
489 ```bash
490 XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-text
491 ```
492
493 ## License
494
495 This project is released under the permissive [MIT license](LICENSE).
496
497 > Do you use this project in a commercial setting? Sponsoring with invoicing is
498 available, contact me ([@clue](https://github.com/clue)) for details.
499
500 ## More
501
502 * If you want to learn more about how the
503 [`ConnectorInterface`](https://github.com/reactphp/socket#connectorinterface)
504 and its usual implementations look like, refer to the documentation of the underlying
505 [react/socket](https://github.com/reactphp/socket) component.
506 * If you want to learn more about processing streams of data, refer to the
507 documentation of the underlying
508 [react/stream](https://github.com/reactphp/stream) component.
509 * As an alternative to an HTTP CONNECT proxy, you may also want to look into
510 using a SOCKS (SOCKS4/SOCKS5) proxy instead.
511 You may want to use [clue/reactphp-socks](https://github.com/clue/reactphp-socks)
512 which also provides an implementation of the same
513 [`ConnectorInterface`](https://github.com/reactphp/socket#connectorinterface)
514 so that supporting either proxy protocol should be fairly trivial.
515 * As an alternative to an HTTP CONNECT proxy, you may also want to look into
516 using an SSH proxy (SSH tunnel) instead.
517 You may want to use [clue/reactphp-ssh-proxy](https://github.com/clue/reactphp-ssh-proxy)
518 which also provides an implementation of the same
519 [`ConnectorInterface`](https://github.com/reactphp/socket#connectorinterface)
520 so that supporting either proxy protocol should be fairly trivial.
521 * If you're dealing with public proxies, you'll likely have to work with mixed
522 quality and unreliable proxies. You may want to look into using
523 [clue/reactphp-connection-manager-extra](https://github.com/clue/reactphp-connection-manager-extra)
524 which allows retrying unreliable ones, implying connection timeouts,
525 concurrently working with multiple connectors and more.
526 * If you're looking for an end-user HTTP CONNECT proxy server daemon, you may
527 want to use [LeProxy](https://leproxy.org/).