Debian Codegraph @

vendor/clue/socks-react/CHANGELOG.md

raw
1 # Changelog
2
3 ## 1.5.0 (2026-04-14)
4
5 * Feature: Improve PHP 8.5+, PHP 8.4+, PHP 8.3+ and PHP 8.2+ support.
6 (#118, #123 and #124 by @clue and #113 by @yadaiio)
7
8 * Feature / Fix: Update close handler to avoid unhandled promise rejections.
9 (#117 by @clue)
10
11 * Fix: Avoid unneeded shutdown timer on already closed connection.
12 (#125 by @clue)
13
14 * Minor documentation improvements.
15 (#112 by @yadaiio)
16
17 * Improve test suite, use reactphp/async instead of clue/reactphp-block and support legacy PHP 7.2 with PHPUnit 8.5.
18 (#121 by @dinooo13 and @clue and #116, #120 and #122 by @clue)
19
20 ## 1.4.0 (2022-08-31)
21
22 * Feature: Full support for PHP 8.1 and PHP 8.2.
23 (#105 by @clue and #108 by @SimonFrings)
24
25 * Feature: Mark passwords and URIs as `#[\SensitiveParameter]` (PHP 8.2+).
26 (#109 by @SimonFrings)
27
28 * Feature: Forward compatibility with upcoming Promise v3.
29 (#106 by @clue)
30
31 * Bug: Fix invalid references in exception stack trace.
32 (#104 by @clue)
33
34 * Improve test suite and fix legacy HHVM build.
35 (#107 by @SimonFrings)
36
37 ## 1.3.0 (2021-08-06)
38
39 * Feature: Simplify usage by supporting new default loop and making `Connector` optional.
40 (#100 and #101 by @clue)
41
42 ```php
43 // old (still supported)
44 $proxy = new Clue\React\Socks\Client(
45 $url,
46 new React\Socket\Connector($loop)
47 );
48 $server = new Clue\React\Socks\Server($loop);
49 $server->listen(new React\Socket\Server('127.0.0.1:1080', $loop));
50
51 // new (using default loop)
52 $proxy = new Clue\React\Socks\Client('127.0.0.1:1080');
53 $socks = new Clue\React\Socks\Server();
54 $socks->listen(new React\Socket\SocketServer('127.0.0.1:1080'));
55 ```
56
57 * Documentation improvements and updated examples.
58 (#98 and #102 by @clue and #99 by @PaulRotmann)
59
60 * Improve test suite and use GitHub actions for continuous integration (CI).
61 (#97 by @SimonFrings)
62
63 ## 1.2.0 (2020-10-23)
64
65 * Enhanced documentation for ReactPHP's new HTTP client.
66 (#95 by @SimonFrings)
67
68 * Improve test suite, prepare PHP 8 support and support PHPUnit 9.3.
69 (#96 by @SimonFrings)
70
71 ## 1.1.0 (2020-06-19)
72
73 * Feature / Fix: Support PHP 7.4 by skipping unneeded cleanup of exception trace args.
74 (#92 by @clue)
75
76 * Clean up test suite and add `.gitattributes` to exclude dev files from exports.
77 Run tests on PHP 7.4, PHPUnit 9 and simplify test matrix.
78 Link to using SSH proxy (SSH tunnel) as an alternative.
79 (#88 by @clue and #91 and #93 by @SimonFrings)
80
81 ## 1.0.0 (2018-11-20)
82
83 * First stable release, now following SemVer!
84
85 * Feature / BC break: Unify SOCKS5 and SOCKS4(a) protocol version handling,
86 the `Client` now defaults to SOCKS5 instead of SOCKS4a,
87 remove explicit SOCKS4a handling and merge into SOCKS4 protocol handling and
88 URI scheme `socks5://` now only acts as an alias for default `socks://` scheme.
89 (#74, #81 and #87 by @clue)
90
91 ```php
92 // old: defaults to SOCKS4a
93 $client = new Client('127.0.0.1:1080', $connector);
94 $client = new Client('socks://127.0.0.1:1080', $connector);
95
96 // new: defaults to SOCKS5
97 $client = new Client('127.0.0.1:1080', $connector);
98 $client = new Client('socks://127.0.0.1:1080', $connector);
99
100 // new: explicitly use legacy SOCKS4(a)
101 $client = new Client('socks4://127.0.0.1:1080', $connector);
102
103 // unchanged: explicitly use SOCKS5
104 $client = new Client('socks5://127.0.0.1:1080', $connector);
105 ```
106
107 * Feature / BC break: Clean up `Server` interface,
108 add `Server::listen()` method instead of accepting socket in constructor,
109 replace `Server::setAuth()` with optional constructor parameter,
110 remove undocumented "connection" event from Server and drop explicit Evenement dependency and
111 mark all classes as `final` and all internal APIs as `@internal`
112 (#78, #79, #80 and #84 by @clue)
113
114 ```php
115 // old: socket passed to server constructor
116 $socket = new React\Socket\Server(1080, $loop);
117 $server = new Clue\React\Socks\Server($loop, $socket);
118
119 // old: authentication via setAuthArray()/setAuth() methods
120 $server = new Clue\React\Socks\Server($loop, $socket);
121 $server->setAuthArray(array(
122 'tom' => 'password',
123 'admin' => 'root'
124 ));
125
126 // new: socket passed to listen() method
127 $server = new Clue\React\Socks\Server($loop);
128 $socket = new React\Socket\Server(1080, $loop);
129 $server->listen($socket);
130
131 // new: authentication passed to server constructor
132 $server = new Clue\React\Socks\Server($loop, null, array(
133 'tom' => 'password',
134 'admin' => 'root'
135 ));
136 $server->listen($socket);
137 ```
138
139 * Feature: Improve error reporting for failed connections attempts by always including target URI in exceptions and
140 improve promise cancellation and clean up any garbage references.
141 (#82 and #83 by @clue)
142
143 All error messages now always contain a reference to the remote URI to give
144 more details which connection actually failed and the reason for this error.
145 Similarly, any underlying connection issues to the proxy server will now be
146 reported as part of the previous exception.
147
148 For most common use cases this means that simply reporting the `Exception`
149 message should give the most relevant details for any connection issues:
150
151 ```php
152 $promise = $proxy->connect('tcp://example.com:80');
153 $promise->then(function (ConnectionInterface $connection) {
154 // …
155 }, function (Exception $e) {
156 echo $e->getMessage();
157 });
158 ```
159
160 * Improve documentation and examples, link to other projects and update project homepage.
161 (#73, #75 and #85 by @clue)
162
163 ## 0.8.7 (2017-12-17)
164
165 * Feature: Support SOCKS over TLS (`sockss://` URI scheme)
166 (#70 and #71 by @clue)
167
168 ```php
169 // new: now supports SOCKS over TLS
170 $client = new Client('socks5s://localhost', $connector);
171 ```
172
173 * Feature: Support communication over Unix domain sockets (UDS)
174 (#69 by @clue)
175
176 ```php
177 // new: now supports SOCKS over Unix domain sockets (UDS)
178 $client = new Client('socks5+unix:///tmp/proxy.sock', $connector);
179 ```
180
181 * Improve test suite by adding forward compatibility with PHPUnit 6
182 (#68 by @clue)
183
184 ## 0.8.6 (2017-09-17)
185
186 * Feature: Forward compatibility with Evenement v3.0
187 (#67 by @WyriHaximus)
188
189 ## 0.8.5 (2017-09-01)
190
191 * Feature: Use socket error codes for connection rejections
192 (#63 by @clue)
193
194 ```php
195 $promise = $proxy->connect('imap.example.com:143');
196 $promise->then(null, function (Exception $e) {
197 if ($e->getCode() === SOCKET_EACCES) {
198 echo 'Failed to authenticate with proxy!';
199 }
200 throw $e;
201 });
202 ```
203
204 * Feature: Report matching SOCKS5 error codes for server side connection errors
205 (#62 by @clue)
206
207 * Fix: Fix SOCKS5 client receiving destination hostnames and
208 fix IPv6 addresses as hostnames for TLS certificates
209 (#64 and #65 by @clue)
210
211 * Improve test suite by locking Travis distro so new defaults will not break the build and
212 optionally exclude tests that rely on working internet connection
213 (#61 and #66 by @clue)
214
215 ## 0.8.4 (2017-07-27)
216
217 * Feature: Server now passes client source address to Connector
218 (#60 by @clue)
219
220 ## 0.8.3 (2017-07-18)
221
222 * Feature: Pass full remote URI as parameter to authentication callback
223 (#58 by @clue)
224
225 ```php
226 // new third parameter passed to authentication callback
227 $server->setAuth(function ($user, $pass, $remote) {
228 $ip = parse_url($remote, PHP_URL_HOST);
229
230 return ($ip === '127.0.0.1');
231 });
232 ```
233
234 * Fix: Fix connecting to IPv6 address via SOCKS5 server and validate target
235 URI so hostname can not contain excessive URI components
236 (#59 by @clue)
237
238 * Improve test suite by fixing HHVM build for now again and ignore future HHVM build errors
239 (#57 by @clue)
240
241 ## 0.8.2 (2017-05-09)
242
243 * Feature: Forward compatibility with upcoming Socket v1.0 and v0.8
244 (#56 by @clue)
245
246 ## 0.8.1 (2017-04-21)
247
248 * Update examples to use URIs with default port 1080 and accept proxy URI arguments
249 (#54 by @clue)
250
251 * Remove now unneeded dependency on `react/stream`
252 (#55 by @clue)
253
254 ## 0.8.0 (2017-04-18)
255
256 * Feature: Merge `Server` class from clue/socks-server
257 (#52 by @clue)
258
259 ```php
260 $socket = new React\Socket\Server(1080, $loop);
261 $server = new Clue\React\Socks\Server($loop, $socket);
262 ```
263
264 > Upgrading from [clue/socks-server](https://github.com/clue/php-socks-server)?
265 The classes have been moved as-is, so you can simply start using the new
266 class name `Clue\React\Socks\Server` with no other changes required.
267
268 ## 0.7.0 (2017-04-14)
269
270 * Feature / BC break: Replace deprecated SocketClient with Socket v0.7 and
271 use `connect($uri)` instead of `create($host, $port)`
272 (#51 by @clue)
273
274 ```php
275 // old
276 $connector = new React\SocketClient\TcpConnector($loop);
277 $client = new Client(1080, $connector);
278 $client->create('google.com', 80)->then(function (Stream $conn) {
279 $conn->write("…");
280 });
281
282 // new
283 $connector = new React\Socket\TcpConnector($loop);
284 $client = new Client(1080, $connector);
285 $client->connect('google.com:80')->then(function (ConnectionInterface $conn) {
286 $conn->write("…");
287 });
288 ```
289
290 * Improve test suite by adding PHPUnit to require-dev
291 (#50 by @clue)
292
293 ## 0.6.0 (2016-11-29)
294
295 * Feature / BC break: Pass connector into `Client` instead of loop, remove unneeded deps
296 (#49 by @clue)
297
298 ```php
299 // old (connector is create implicitly)
300 $client = new Client('127.0.0.1', $loop);
301
302 // old (connector can optionally be passed)
303 $client = new Client('127.0.0.1', $loop, $connector);
304
305 // new (connector is now mandatory)
306 $connector = new React\SocketClient\TcpConnector($loop);
307 $client = new Client('127.0.0.1', $connector);
308 ```
309
310 * Feature / BC break: `Client` now implements `ConnectorInterface`, remove `Connector` adapter
311 (#47 by @clue)
312
313 ```php
314 // old (explicit connector functions as an adapter)
315 $connector = $client->createConnector();
316 $promise = $connector->create('google.com', 80);
317
318 // new (client can be used as connector right away)
319 $promise = $client->create('google.com', 80);
320 ```
321
322 * Feature / BC break: Remove `createSecureConnector()`, use `SecureConnector` instead
323 (#47 by @clue)
324
325 ```php
326 // old (tight coupling and hidden dependency)
327 $tls = $client->createSecureConnector();
328 $promise = $tls->create('google.com', 443);
329
330 // new (more explicit, loose coupling)
331 $tls = new React\SocketClient\SecureConnector($client, $loop);
332 $promise = $tls->create('google.com', 443);
333 ```
334
335 * Feature / BC break: Remove `setResolveLocal()` and local DNS resolution and default to remote DNS resolution, use `DnsConnector` instead
336 (#44 by @clue)
337
338 ```php
339 // old (implicitly defaults to true, can be disabled)
340 $client->setResolveLocal(false);
341 $tcp = $client->createConnector();
342 $promise = $tcp->create('google.com', 80);
343
344 // new (always disabled, can be re-enabled like this)
345 $factory = new React\Dns\Resolver\Factory();
346 $resolver = $factory->createCached('8.8.8.8', $loop);
347 $tcp = new React\SocketClient\DnsConnector($client, $resolver);
348 $promise = $tcp->create('google.com', 80);
349 ```
350
351 * Feature / BC break: Remove `setTimeout()`, use `TimeoutConnector` instead
352 (#45 by @clue)
353
354 ```php
355 // old (timeout only applies to TCP/IP connection)
356 $client = new Client('127.0.0.1', …);
357 $client->setTimeout(3.0);
358 $tcp = $client->createConnector();
359 $promise = $tcp->create('google.com', 80);
360
361 // new (timeout can be added to any layer)
362 $client = new Client('127.0.0.1', …);
363 $tcp = new React\SocketClient\TimeoutConnector($client, 3.0, $loop);
364 $promise = $tcp->create('google.com', 80);
365 ```
366
367 * Feature / BC break: Remove `setProtocolVersion()` and `setAuth()` mutators, only support SOCKS URI for protocol version and authentication (immutable API)
368 (#46 by @clue)
369
370 ```php
371 // old (state can be mutated after instantiation)
372 $client = new Client('127.0.0.1', …);
373 $client->setProtocolVersion('5');
374 $client->setAuth('user', 'pass');
375
376 // new (immutable after construction, already supported as of v0.5.2 - now mandatory)
377 $client = new Client('socks5://user:[email protected]', …);
378 ```
379
380 ## 0.5.2 (2016-11-25)
381
382 * Feature: Apply protocol version and username/password auth from SOCKS URI
383 (#43 by @clue)
384
385 ```php
386 // explicitly use SOCKS5
387 $client = new Client('socks5://127.0.0.1', $loop);
388
389 // use authentication (automatically SOCKS5)
390 $client = new Client('user:[email protected]', $loop);
391 ```
392
393 * More explicit client examples, including proxy chaining
394 (#42 by @clue)
395
396 ## 0.5.1 (2016-11-21)
397
398 * Feature: Support Promise cancellation
399 (#39 by @clue)
400
401 ```php
402 $promise = $connector->create($host, $port);
403
404 $promise->cancel();
405 ```
406
407 * Feature: Timeout now cancels pending connection attempt
408 (#39, #22 by @clue)
409
410 ## 0.5.0 (2016-11-07)
411
412 * Remove / BC break: Split off Server to clue/socks-server
413 (#35 by @clue)
414
415 > Upgrading? Check [clue/socks-server](https://github.com/clue/php-socks-server) for details.
416
417 * Improve documentation and project structure
418
419 ## 0.4.0 (2016-03-19)
420
421 * Feature: Support proper SSL/TLS connections with additional SSL context options
422 (#31, #33 by @clue)
423
424 * Documentation for advanced Connector setups (bindto, multihop)
425 (#32 by @clue)
426
427 ## 0.3.0 (2015-06-20)
428
429 * BC break / Feature: Client ctor now accepts a SOCKS server URI
430 ([#24](https://github.com/clue/php-socks-react/pull/24))
431
432 ```php
433 // old
434 $client = new Client($loop, 'localhost', 9050);
435
436 // new
437 $client = new Client('localhost:9050', $loop);
438 ```
439
440 * Feature: Automatically assume default SOCKS port (1080) if not given explicitly
441 ([#26](https://github.com/clue/php-socks-react/pull/26))
442
443 * Improve documentation and test suite
444
445 ## 0.2.1 (2014-11-13)
446
447 * Support React PHP v0.4 (while preserving BC with React PHP v0.3)
448 ([#16](https://github.com/clue/php-socks-react/pull/16))
449
450 * Improve examples and add first class support for HHVM
451 ([#15](https://github.com/clue/php-socks-react/pull/15) and [#17](https://github.com/clue/php-socks-react/pull/17))
452
453 ## 0.2.0 (2014-09-27)
454
455 * BC break / Feature: Simplify constructors by making parameters optional.
456 ([#10](https://github.com/clue/php-socks-react/pull/10))
457
458 The `Factory` has been removed, you can now create instances of the `Client`
459 and `Server` yourself:
460
461 ```php
462 // old
463 $factory = new Factory($loop, $dns);
464 $client = $factory->createClient('localhost', 9050);
465 $server = $factory->createSever($socket);
466
467 // new
468 $client = new Client($loop, 'localhost', 9050);
469 $server = new Server($loop, $socket);
470 ```
471
472 * BC break: Remove HTTP support and link to [clue/buzz-react](https://github.com/clue/php-buzz-react) instead.
473 ([#9](https://github.com/clue/php-socks-react/pull/9))
474
475 HTTP operates on a different layer than this low-level SOCKS library.
476 Removing this reduces the footprint of this library.
477
478 > Upgrading? Check the [README](https://github.com/clue/php-socks-react#http-requests) for details.
479
480 * Fix: Refactored to support other, faster loops (libev/libevent)
481 ([#12](https://github.com/clue/php-socks-react/pull/12))
482
483 * Explicitly list dependencies, clean up examples and extend test suite significantly
484
485 ## 0.1.0 (2014-05-19)
486
487 * First stable release
488 * Async SOCKS `Client` and `Server` implementation
489 * Project was originally part of [clue/socks](https://github.com/clue/php-socks)
490 and was split off from its latest release v0.4.0
491 ([#1](https://github.com/clue/reactphp-socks/issues/1))
492
493 > Upgrading from clue/socks v0.4.0? Use namespace `Clue\React\Socks` instead of `Socks` and you're ready to go!
494
495 ## 0.0.0 (2011-04-26)
496
497 * Initial concept, originally tracked as part of
498 [clue/socks](https://github.com/clue/php-socks)