8000 Merge pull request #19 from clue-labs/docs · SimonFrings/reactphp-http-proxy@c3af12a · GitHub
[go: up one dir, main page]
Skip to content

Commit c3af12a

Browse files
clueclue
authored
Merge pull request clue#19 from clue-labs/docs
Improve documentation
2 parents 7c7dbca + 78cc7d3 commit c3af12a

File tree

2 files changed

+39
-68
lines changed

2 files changed

+39
-68
lines changed

‎README.md

Lines changed: 38 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,12 @@
11
# 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)
22

3-
Async HTTP CONNECT proxy connector, use any TCP/IP protocol through an HTTP proxy server, built on top of [ReactPHP](http://reactphp.org).
3+
Async HTTP proxy connector, use any TCP/IP protocol through an HTTP CONNECT proxy server,
4+
built on top of [ReactPHP](https://reactphp.org).
45

56
**Table of contents**
67

78
* [Quickstart example](#quickstart-example)
89
* [Usage](#usage)
9-
* [ConnectorInterface](#connectorinterface)
10-
* [connect()](#connect)
1110
* [ProxyConnector](#proxyconnector)
1211
* [Plain TCP connections](#plain-tcp-connections)
1312
* [Secure TLS connections](#secure-tls-connections)
@@ -49,45 +48,6 @@ See also the [examples](examples).
4948

5049
## Usage
5150

52-
### ConnectorInterface
53-
54-
The `ConnectorInterface` is responsible for providing an interface for
55-
establishing streaming connections, such as a normal TCP/IP connection.
56-
57-
In order to use this library, you should understand how this integrates with its
58-
ecosystem.
59-
This base interface is actually defined in React's
60-
[Socket component](https://github.com/reactphp/socket) and used
61-
throughout React's ecosystem.
62-
63-
Most higher-level components (such as HTTP, database or other networking
64-
service clients) accept an instance implementing this interface to create their
65-
TCP/IP connection to the underlying networking service.
66-
This is usually done via dependency injection, so it's fairly simple to actually
67-
swap this implementation against this library in order to connect through an
68-
HTTP CONNECT proxy.
69-
70-
The interface only offers a single method:
71-
72-
#### connect()
73-
74-
The `connect(string $uri): PromiseInterface<ConnectionInterface, Exception>` method
75-
can be used to establish a streaming connection.
76-
It returns a [Promise](https://github.com/reactphp/promise) which either
77-
fulfills with a [ConnectionInterface](https://github.com/reactphp/socket#connectioninterface) or
78-
rejects with an `Exception`:
79-
80-
```php
81-
$connector->connect('google.com:443')->then(
82-
function (ConnectionInterface $stream) {
83-
// connection successfully established
84-
},
85-
function (Exception $error) {
86-
// failed to connect due to $error
87-
}
88-
);
89-
```
90-
9151
### ProxyConnector
9252

9353
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);
10767

10868
The proxy URL may or may not contain a scheme and port definition. The default
10969
port will be `80` for HTTP (or `443` for HTTPS), but many common HTTP proxy
110-
servers use custom ports.
70+
servers use custom ports (often the alternative HTTP port `8080`).
11171
In its most simple form, the given connector will be a
11272
[`\React\Socket\Connector`](https://github.com/reactphp/socket#connector) if you
11373
want to connect to a given IP address as above.
11474

11575
This is the main class in this package.
116-
Because it implements the the [`ConnectorInterface`](#connectorinterface), it
117-
can simply be used in place of a normal connector.
76+
Because it implements ReactPHP's standard
77+
[`ConnectorInterface`](https://github.com/reactphp/socket#connectorinterface),
78+
it can simply be used in place of a normal connector.
79+
Accordingly, it provides only a single public method, the
80+
[`connect()`](https://github.com/reactphp/socket#connect) method.
81+
The `connect(string $uri): PromiseInterface<ConnectionInterface, Exception>`
82+
method can be used to establish a streaming connection.
83+
It returns a [Promise](https://github.com/reactphp/promise) which either
84+
fulfills with a [ConnectionInterface](https://github.com/reactphp/socket#connectioninterface)
85+
on success or rejects with an `Exception` on error.
86+
11887
This makes it fairly simple to add HTTP CONNECT proxy support to pretty much any
11988
higher-level component:
12089

@@ -126,12 +95,11 @@ higher-level component:
12695

12796
#### Plain TCP connections
12897

129-
This is most frequently used to issue HTTPS requests to your destination.
98+
HTTP CONNECT proxies are most frequently used to issue HTTPS requests to your destination.
13099
However, this is actually performed on a higher protocol layer and this
131100
connector is actually inherently a general-purpose plain TCP/IP connector.
132-
133-
The `ProxyConnector` implements the [`ConnectorInterface`](#connectorinterface) and
134-
hence provides a single public method, the [`connect()`](#connect) method.
101+
As documented above, you can simply invoke its `connect()` method to establish
102+
a streaming plain TCP/IP connection and use any higher level protocol like so:
135103

136104
```php
137105
$proxy = new ProxyConnector('http://127.0.0.1:8080', $connector);
@@ -145,7 +113,7 @@ $proxy->connect('tcp://smtp.googlemail.com:587')->then(function (ConnectionInter
145113
```
146114

147115
You can either use the `ProxyConnector` directly or you may want to wrap this connector
148-
in React's [`Connector`](https://github.com/reactphp/socket#connector):
116+
in ReactPHP's [`Connector`](https://github.com/reactphp/socket#connector):
149117

150118
```php
151119
$connector = new Connector($loop, array(
@@ -166,10 +134,11 @@ Many (public) proxy servers do in fact limit this to HTTPS (443) only.
166134

167135
#### Secure TLS connections
168136

169-
If you want to establish a TLS connection (such as HTTPS) between you and
170-
your destination, you may want to wrap this connector in React's
171-
[`Connector`](https://github.com/reactphp/socket#connector) or the low-level
172-
[`SecureConnector`](https://github.com/reactphp/socket#secureconnector):
137+
This class can also be used if you want to establish a secure TLS connection
138+
(formerly known as SSL) between you and your destination, such as when using
139+
secure HTTPS to your destination site. You can simply wrap this connector in
140+
ReactPHP's [`Connector`](https://github.com/reactphp/socket#connector) or the
141+
low-level [`SecureConnector`](https://github.com/reactphp/socket#secureconnector):
173142

174143
```php
175144
$proxy = new ProxyConnector('http://127.0.0.1:8080', $connector);
@@ -186,7 +155,7 @@ $connector->connect('tls://smtp.googlemail.com:465')->then(function (ConnectionI
186155
});
187156
```
188157

189-
> Also note how secure TLS connections are in fact entirely handled outside of
158+
> Note how secure TLS connections are in fact entirely handled outside of
190159
this HTTP CONNECT client implementation.
191160

192161
#### Connection timeout
@@ -199,7 +168,7 @@ connections, anywhere in a range of a few minutes to several hours.
199168
Many use cases require more control over the timeout and likely values much
200169
smaller, usually in the range of a few seconds only.
201170

202-
You can use React's [`Connector`](https://github.com/reactphp/socket#connector)
171+
You can use ReactPHP's [`Connector`](https://github.com/reactphp/socket#connector)
203172
or the low-level
204173
[`TimeoutConnector`](https://github.com/reactphp/socket#timeoutconnector)
205174
to decorate any given `ConnectorInterface` instance.
@@ -220,7 +189,7 @@ $connector->connect('tcp://google.com:80')->then(function ($stream) {
220189

221190
See also any of the [examples](examples).
222191

223-
> Also note how connection timeout is in fact entirely handled outside of this
192+
> Note how connection timeout is in fact entirely handled outside of this
224193
HTTP CONNECT client implementation.
225194

226195
#### DNS resolution
@@ -242,7 +211,7 @@ if it should not resolve target hostnames because its outgoing DNS traffic might
242211
be intercepted.
243212

244213
As noted above, the `ProxyConnector` defaults to using remote DNS resolution.
245-
However, wrapping the `ProxyConnector` in React's
214+
However, wrapping the `ProxyConnector` in ReactPHP's
246215
[`Connector`](https://github.com/reactphp/socket#connector) actually
247216
performs local DNS resolution unless explicitly defined otherwise.
248217
Given that remote DNS resolution is assumed to be the preferred mode, all
@@ -265,7 +234,7 @@ $connector = Connector($loop, array(
265234
));
266235
```
267236

268-
> Also note how local DNS resolution is in fact entirely handled outside of this
237+
> Note how local DNS resolution is in fact entirely handled outside of this
269238
HTTP CONNECT client implementation.
270239

271240
#### Authentication
@@ -306,7 +275,7 @@ setup, because you can still establish a TLS connection between you and the
306275
destination host as above.
307276

308277
If you want to connect to a (rather rare) HTTPS proxy, you may want use the
309-
`https://` scheme (HTTPS default port 443) and use React's
278+
`https://` scheme (HTTPS default port 443) and use ReactPHP's
310279
[`Connector`](https://github.com/reactphp/socket#connector) or the low-level
311280
[`SecureConnector`](https://github.com/reactphp/socket#secureconnector)
312281
instance to create a secure connection to the proxy:
@@ -359,21 +328,23 @@ MIT
359328

360329
## More
361330

331+
* If you want to learn more about how the
332+
[`ConnectorInterface`](https://github.com/reactphp/socket#connectorinterface)
333+
and its usual implementations look like, refer to the documentation of the underlying
334+
[react/socket](https://github.com/reactphp/socket) component.
362335
* If you want to learn more about processing streams of data, refer to the
363336
documentation of the underlying
364337
[react/stream](https://github.com/reactphp/stream) component.
365-
* If you want to learn more about how the
366-
[`ConnectorInterface`](#connectorinterface) and its usual implementations look
367-
like, refer to the documentation of the underlying
368-
[react/socket](https://github.com/reactphp/socket) component.
369338
* As an alternative to an HTTP CONNECT proxy, you may also want to look into
370339
using a SOCKS (SOCKS4/SOCKS5) proxy instead.
371340
You may want to use [clue/socks-react](https://github.com/clue/php-socks-react)
372-
which also provides an implementation of the
373-
[`ConnectorInterface`](#connectorinterface) so that supporting either proxy
374-
protocol should be fairly trivial.
341+
which also provides an implementation of the same
342+
[`ConnectorInterface`](https://github.com/reactphp/socket#connectorinterface)
343+
so that supporting either proxy protocol should be fairly trivial.
375344
* If you're dealing with public proxies, you'll likely have to work with mixed
376345
quality and unreliable proxies. You may want to look into using
377346
[clue/connection-manager-extra](https://github.com/clue/php-connection-manager-extra)
378347
which allows retrying unreliable ones, implying connection timeouts,
379348
concurrently working with multiple connectors and more.
349+
* If you're looking for an end-user HTTP CONNECT proxy server daemon, you may
350+
want to use [LeProxy](https://leproxy.org/).

‎composer.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "clue/http-proxy-react",
3-
"description": "Async HTTP CONNECT proxy connector, use any TCP/IP protocol through an HTTP proxy server, built on top of ReactPHP",
3+
"description": "Async HTTP proxy connector, use any TCP/IP protocol through an HTTP CONNECT proxy server, built on top of ReactPHP",
44
"keywords": ["HTTP", "CONNECT", "proxy", "ReactPHP", "async"],
55
"homepage": "https://github.com/clue/php-http-proxy-react",
66
"license": "MIT",

0 commit comments

Comments
 (0)
0