Skip to content

Commit 4ecff16

Browse files
clueclue
committed
Merge pull request #29 from clue-labs/connector
Documentation for `Connector`
2 parents b463286 + 0a091a4 commit 4ecff16

5 files changed

Lines changed: 98 additions & 19 deletions

File tree

‎README.md‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,9 @@ to google.com via a local SOCKS proxy server:
1212
```php
1313
$loop = React\EventLoop\Factory::create();
1414
$client = new Client('127.0.0.1:9050', $loop);
15+
$connector = $client->createConnector();
1516

16-
$client->getConnection('www.google.com:80')->then(function ($stream) {
17+
$connector->create('www.google.com:80')->then(function ($stream) {
1718
$stream->write("GET / HTTP/1.0\r\n\r\n");
1819
});
1920

@@ -263,6 +264,24 @@ If you do not want to use authentication anymore:
263264
$client->unsetAuth();
264265
```
265266

267+
### Connector
268+
269+
The `Connector` instance can be used to establish TCP connections to remote hosts.
270+
Each instance can be used to establish any number of TCP connections.
271+
272+
It implements React's `ConnectorInterface` which only provides a single
273+
`create()` method.
274+
275+
The `create($host, $port)` method can be used to establish a TCP
276+
connection to the given target host and port.
277+
278+
It functions as an [adapter](https://en.wikipedia.org/wiki/Adapter_pattern):
279+
Many higher-level networking protocols build on top of TCP. It you're dealing
280+
with one such client implementation, it probably uses/accepts an instance
281+
implementing React's `ConnectorInterface` (and usually its default `Connector`
282+
instance). In this case you can also pass this `Connector` instance instead
283+
to make this client implementation SOCKS-aware. That's it.
284+
266285
### Server
267286

268287
#### Server protocol

‎src/Client.php‎

Lines changed: 47 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -135,17 +135,48 @@ public function unsetAuth()
135135
$this->auth = null;
136136
}
137137

138-
public function createSecureConnector()
138+
/**
139+
* Creates a Connector instance that can be used to establish TCP connections to remote hosts.
140+
*
141+
* This return a new `Connector` instance which can then be used to establish
142+
* any number of TCP connections.
143+
*
144+
* @return Connector
145+
* @see Connector
146+
*/
147+
public function createConnector()
139148
{
140-
return new SecureConnector($this->createConnector(), $this->loop);
149+
return new Connector($this);
141150
}
142151

143-
public function createConnector()
152+
/**
153+
* Creates a SecureConnector instance that can be used to establish encrypted TLS connections to remote hosts.
154+
*
155+
* This is actually a convenience helper method that uses React's normal
156+
* `SecureConnector` wrapper and this libraries' `Connector` for the
157+
* underlying TCP connection.
158+
*
159+
* @return SecureConnector
160+
* @uses self::createConnector()
161+
*/
162+
public function createSecureConnector()
144163
{
145-
return new Connector($this);
164+
return new SecureConnector($this->createConnector(), $this->loop);
146165
}
147166

148-
public function getConnection($host, $port)
167+
/**
168+
* Should not be called directly, use createConnector() instead.
169+
*
170+
* This method contains the internal implementation for estasblishing a
171+
* connection to the SOCKS server.
172+
*
173+
* @param string $host
174+
* @param int $port
175+
* @return Promise Promise<Stream,Exception>
176+
* @internal use self::createConnector() instead
177+
* @see self::createConnector()
178+
*/
179+
public function createConnection($host, $port)
149180
{
150181
if (strlen($host) > 255 || $port > 65535 || $port < 0) {
151182
$deferred = new Deferred();
@@ -214,6 +245,17 @@ private function resolve($host)
214245
return $this->resolver->resolve($host);
215246
}
216247

248+
/**
249+
* Internal helper used to handle the communication with the SOCKS server
250+
*
251+
* @param Stream $stream
252+
* @param string $host
253+
* @param int $port
254+
* @param float $timeout
255+
* @param string $protocolVersion
256+
* @param string|null $auth
257+
* @return Promise Promise<stream, Exception>
258+
*/
217259
public function handleConnectedSocks(Stream $stream, $host, $port, $timeout, $protocolVersion, $auth=null)
218260
{
219261
$deferred = new Deferred();

‎src/Connector.php‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,24 @@
55
use React\SocketClient\ConnectorInterface;
66
use Clue\React\Socks\Client;
77

8+
/**
9+
* The Connector instance can be used to establish TCP connections to remote hosts.
10+
*
11+
* Each instance can be used to establish any number of TCP connections.
12+
*
13+
* It implements React's `ConnectorInterface` which only provides a single
14+
* `create()` method.
15+
*
16+
* You can use this method directly in order to establish a TCP connection to
17+
* the given target host and port.
18+
*
19+
* It functions as an adapter:
20+
* Many higher-level networking protocols build on top of TCP. It you're dealing
21+
* with one such client implementation, it probably uses/accepts an instance
22+
* implementing React's `ConnectorInterface` (and usually its default `Connector`
23+
* instance). In this case you can also pass this `Connector` instance instead
24+
* to make this client implementation SOCKS-aware. That's it.
25+
*/
826
class Connector implements ConnectorInterface
927
{
1028
private $client;
@@ -16,6 +34,6 @@ public function __construct(Client $socksClient)
1634

1735
public function create($host, $port)
1836
{
19-
return $this->client->getConnection($host, $port);
37+
return $this->client->createConnection($host, $port);
2038
}
2139
}

‎tests/ClientTest.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -151,9 +151,9 @@ public function testCreateSecureConnector()
151151
/**
152152
* @dataProvider providerAddress
153153
*/
154-
public function testGetConnection($host, $port)
154+
public function testCreateConnection($host, $port)
155155
{
156-
$this->assertInstanceOf('\React\Promise\PromiseInterface', $this->client->getConnection($host, $port));
156+
$this->assertInstanceOf('\React\Promise\PromiseInterface', $this->client->createConnection($host, $port));
157157
}
158158

159159
public function providerAddress()

‎tests/FunctionalTest.php‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -25,78 +25,78 @@ public function setUp()
2525

2626
public function testConnection()
2727
{
28-
$this->assertResolveStream($this->client->getConnection('www.google.com', 80));
28+
$this->assertResolveStream($this->client->createConnection('www.google.com', 80));
2929
}
3030

3131
public function testConnectionSocks4()
3232
{
3333
$this->server->setProtocolVersion(4);
3434
$this->client->setProtocolVersion(4);
3535

36-
$this->assertResolveStream($this->client->getConnection('www.google.com', 80));
36+
$this->assertResolveStream($this->client->createConnection('www.google.com', 80));
3737
}
3838

3939
public function testConnectionSocks5()
4040
{
4141
$this->server->setProtocolVersion(5);
4242
$this->client->setProtocolVersion(5);
4343

44-
$this->assertResolveStream($this->client->getConnection('www.google.com', 80));
44+
$this->assertResolveStream($this->client->createConnection('www.google.com', 80));
4545
}
4646

4747
public function testConnectionInvalidSocks4aRemote()
4848
{
4949
$this->client->setProtocolVersion('4a');
5050
$this->client->setResolveLocal(false);
5151

52-
$this->assertResolveStream($this->client->getConnection('www.google.com', 80));
52+
$this->assertResolveStream($this->client->createConnection('www.google.com', 80));
5353
}
5454

5555
public function testConnectionSocks5Remote()
5656
{
5757
$this->client->setProtocolVersion(5);
5858
$this->client->setResolveLocal(false);
5959

60-
$this->assertResolveStream($this->client->getConnection('www.google.com', 80));
60+
$this->assertResolveStream($this->client->createConnection('www.google.com', 80));
6161
}
6262

6363
public function testConnectionAuthentication()
6464
{
6565
$this->server->setAuthArray(array('name' => 'pass'));
6666
$this->client->setAuth('name', 'pass');
6767

68-
$this->assertResolveStream($this->client->getConnection('www.google.com', 80));
68+
$this->assertResolveStream($this->client->createConnection('www.google.com', 80));
6969
}
7070

7171
public function testConnectionAuthenticationUnused()
7272
{
7373
$this->client->setAuth('name', 'pass');
7474

75-
$this->assertResolveStream($this->client->getConnection('www.google.com', 80));
75+
$this->assertResolveStream($this->client->createConnection('www.google.com', 80));
7676
}
7777

7878
public function testConnectionInvalidProtocolMismatch()
7979
{
8080
$this->server->setProtocolVersion(5);
8181
$this->client->setProtocolVersion(4);
8282

83-
$this->assertRejectPromise($this->client->getConnection('www.google.com', 80));
83+
$this->assertRejectPromise($this->client->createConnection('www.google.com', 80));
8484
}
8585

8686
public function testConnectionInvalidNoAuthentication()
8787
{
8888
$this->server->setAuthArray(array('name' => 'pass'));
8989
$this->client->setProtocolVersion(5);
9090

91-
$this->assertRejectPromise($this->client->getConnection('www.google.com', 80));
91+
$this->assertRejectPromise($this->client->createConnection('www.google.com', 80));
9292
}
9393

9494
public function testConnectionInvalidAuthenticationMismatch()
9595
{
9696
$this->server->setAuthArray(array('name' => 'pass'));
9797
$this->client->setAuth('user', 'other');
9898

99-
$this->assertRejectPromise($this->client->getConnection('www.google.com', 80));
99+
$this->assertRejectPromise($this->client->createConnection('www.google.com', 80));
100100
}
101101

102102
public function testConnectorOkay()

0 commit comments

Comments
 (0)