Prepare v1.0.0 release

clue · Nov 20, 2018 · f60ae62 · f60ae62
1 parent 9db7fa7
commit f60ae62
Show file tree

Hide file tree

Showing 3 changed files with 139 additions and 18 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,87 @@
 # Changelog
 
+## 1.0.0 (2018-11-20)
+
+*   First stable release, now following SemVer!
+
+*   Feature / BC break: Unify SOCKS5 and SOCKS4(a) protocol version handling,
+    the `Client` now defaults to SOCKS5 instead of SOCKS4a,
+    remove explicit SOCKS4a handling and merge into SOCKS4 protocol handling and
+    URI scheme `socks5://` now only acts as an alias for default `socks://` scheme.
+    (#74, #81 and #87 by @clue)
+
+    ```php
+    // old: defaults to SOCKS4a
+    $client = new Client('127.0.0.1:1080', $connector);
+    $client = new Client('socks://127.0.0.1:1080', $connector);
+
+    // new: defaults to SOCKS5
+    $client = new Client('127.0.0.1:1080', $connector);
+    $client = new Client('socks://127.0.0.1:1080', $connector);
+
+    // new: explicitly use legacy SOCKS4(a)
+    $client = new Client('socks4://127.0.0.1:1080', $connector);
+
+    // unchanged: explicitly use SOCKS5
+    $client = new Client('socks5://127.0.0.1:1080', $connector);
+    ```
+
+*   Feature / BC break: Clean up `Server` interface,
+    add `Server::listen()` method instead of accepting socket in constructor,
+    replace `Server::setAuth()` with optional constructor parameter,
+    remove undocumented "connection" event from Server and drop explicit Evenement dependency and
+    mark all classes as `final` and all internal APIs as `@internal`
+    (#78, #79, #80 and #84 by @clue)
+
+    ```php
+    // old: socket passed to server constructor
+    $socket = new React\Socket\Server(1080, $loop);
+    $server = new Clue\React\Socks\Server($loop, $socket);
+
+    // old: authentication via setAuthArray()/setAuth() methods
+    $server = new Clue\React\Socks\Server($loop, $socket);
+    $server->setAuthArray(array(
+        'tom' => 'password',
+        'admin' => 'root'
+    ));
+
+    // new: socket passed to listen() method
+    $server = new Clue\React\Socks\Server($loop);
+    $socket = new React\Socket\Server(1080, $loop);
+    $server->listen($socket);
+
+    // new: authentication passed to server constructor
+    $server = new Clue\React\Socks\Server($loop, null, array(
+        'tom' => 'password',
+        'admin' => 'root'
+    ));
+    $server->listen($socket);
+    ```
+
+*   Feature: Improve error reporting for failed connections attempts by always including target URI in exceptions and
+    improve promise cancellation and clean up any garbage references.
+    (#82 and #83 by @clue)
+
+    All error messages now always contain a reference to the remote URI to give
+    more details which connection actually failed and the reason for this error.
+    Similarly, any underlying connection issues to the proxy server will now be
+    reported as part of the previous exception.
+
+    For most common use cases this means that simply reporting the `Exception`
+    message should give the most relevant details for any connection issues:
+
+    ```php
+    $promise = $proxy->connect('tcp://example.com:80');
+    $promise->then(function (ConnectionInterface $connection) {
+        // …
+    }, function (Exception $e) {
+        echo $e->getMessage();
+    });
+    ```
+
+*   Improve documentation and examples, link to other projects and update project homepage.
+    (#73, #75 and #85 by @clue)
+
 ## 0.8.7 (2017-12-17)
 
 *   Feature: Support SOCKS over TLS (`sockss://` URI scheme)

diff --git a/README.md b/README.md
@@ -1,11 +1,39 @@
 # clue/reactphp-socks [![Build Status](https://travis-ci.org/clue/reactphp-socks.svg?branch=master)](https://travis-ci.org/clue/reactphp-socks)
 
-Async SOCKS proxy connector client and server implementation, use any TCP/IP-based
+Async SOCKS proxy connector client and server implementation, tunnel any TCP/IP-based
 protocol through a SOCKS5 or SOCKS4(a) proxy server, built on top of
 [ReactPHP](https://reactphp.org).
 
-The SOCKS protocol family can be used to easily tunnel TCP connections independent
-of the actual application level protocol, such as HTTP, SMTP, IMAP, Telnet etc.
+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 (HTTP,
+SMTP, IMAP etc.).
+This library provides a simple API to create these tunneled connections for you.
+Because it implements ReactPHP's standard
+[`ConnectorInterface`](https://github.com/reactphp/socket#connectorinterface),
+it can simply be used in place of a normal connector.
+This makes it fairly simple to add SOCKS proxy support to pretty much any
+existing higher-level protocol implementation.
+Besides the client side, it also provides a simple SOCKS server implementation
+which allows you to build your own SOCKS proxy servers with custom business logic.
+
+* **Async execution of connections** -
+  Send any number of SOCKS requests in parallel and process their
+  responses as soon as results come in.
+  The Promise-based design provides a *sane* interface to working with out of
+  bound responses and possible connection errors.
+* **Standard interfaces** -
+  Allows easy integration with existing higher-level components by implementing
+  ReactPHP's standard
+  [`ConnectorInterface`](https://github.com/reactphp/socket#connectorinterface).
+* **Lightweight, SOLID design** -
+  Provides a thin abstraction that is [*just good enough*](https://en.wikipedia.org/wiki/Principle_of_good_enough)
+  and does not get in your way.
+  Builds on top of well-tested components and well-established concepts instead of reinventing the wheel.
+* **Good test coverage** -
+  Comes with an automated tests suite and is regularly tested against actual proxy servers in the wild.
 
 **Table of contents**
 
@@ -255,10 +283,10 @@ a generic proxy allowing higher level application protocols to work through it.
   </tr>
   <tr>
     <th>Protocol specification</th>
-    <td><a href="http://tools.ietf.org/html/rfc1928">RFC 1928</a></td>
+    <td><a href="https://tools.ietf.org/html/rfc1928">RFC 1928</a></td>
     <td>
-      <a href="http://ftp.icm.edu.pl/packages/socks/socks4/SOCKS4.protocol">SOCKS4.protocol</a> /
-      <a href="http://ftp.icm.edu.pl/packages/socks/socks4/SOCKS4A.protocol">SOCKS4A.protocol</a>
+      <a href="https://ftp.icm.edu.pl/packages/socks/socks4/SOCKS4.protocol">SOCKS4.protocol</a> /
+      <a href="https://ftp.icm.edu.pl/packages/socks/socks4/SOCKS4A.protocol">SOCKS4A.protocol</a>
     </td>
   </tr>
   <tr>
@@ -278,7 +306,7 @@ a generic proxy allowing higher level application protocols to work through it.
   </tr>
   <tr>
     <th><a href="#authentication">Username/Password authentication</a></th>
-    <td>✓ (as per <a href="http://tools.ietf.org/html/rfc1929">RFC 1929</a>)</td>
+    <td>✓ (as per <a href="https://tools.ietf.org/html/rfc1929">RFC 1929</a>)</td>
     <td>✗</td>
   </tr>
   <tr>
@@ -385,7 +413,7 @@ as usual.
 #### Authentication
 
 This library supports username/password authentication for SOCKS5 servers as
-defined in [RFC 1929](http://tools.ietf.org/html/rfc1929).
+defined in [RFC 1929](https://tools.ietf.org/html/rfc1929).
 
 On the client side, simply pass your username and password to use for
 authentication (see below).
@@ -927,32 +955,40 @@ $client = new Client('socks+unix:///tmp/proxy.sock', $connector);
 
 ### Using the Tor (anonymity network) to tunnel SOCKS connections
 
-The [Tor anonymity network](http://www.torproject.org) client software is designed
+The [Tor anonymity network](https://www.torproject.org) client software is designed
 to encrypt your traffic and route it over a network of several nodes to conceal its origin.
 It presents a SOCKS5 and SOCKS4(a) interface on TCP port 9050 by default
-which allows you to tunnel any traffic through the anonymity network.
-In most scenarios you probably don't want your client to resolve the target hostnames,
-because you would leak DNS information to anybody observing your local traffic.
-Also, Tor provides hidden services through an `.onion` pseudo top-level domain
-which have to be resolved by Tor.
+which allows you to tunnel any traffic through the anonymity network:
 
-```PHP
+```php
 $client = new Client('127.0.0.1:9050', $connector);
 ```
 
+In most common scenarios you probably want to stick to default
+[remote DNS resolution](#dns-resolution) and don't want your client to resolve the target hostnames,
+because you would leak DNS information to anybody observing your local traffic.
+Also, Tor provides hidden services through an `.onion` pseudo top-level domain
+which have to be resolved by Tor.
+
 ## Install
 
 The recommended way to install this library is [through Composer](https://getcomposer.org).
 [New to Composer?](https://getcomposer.org/doc/00-intro.md)
 
+This project follows [SemVer](https://semver.org/).
 This will install the latest supported version:
 
 ```bash
-$ composer require clue/socks-react:^0.8.7
+$ composer require clue/socks-react:^1.0
 ```
 
 See also the [CHANGELOG](CHANGELOG.md) for details about version upgrades.
 
+This project aims to run on any platform and thus does not require any PHP
+extensions and supports running on legacy PHP 5.3 through current PHP 7+ and
+HHVM.
+It's *highly recommended to use PHP 7+* for this project.
+
 ## Tests
 
 To run the test suite, you first need to clone this repo and then install all
@@ -977,7 +1013,10 @@ $ php vendor/bin/phpunit --exclude-group internet
 
 ## License
 
-MIT, see LICENSE
+This project is released under the permissive [MIT license](LICENSE).
+
+> Did you know that I offer custom development services and issuing invoices for
+  sponsorships of releases and for contributions? Contact me (@clue) for details.
 
 ## More
 

diff --git a/composer.json b/composer.json
@@ -1,6 +1,6 @@
 {
     "name": "clue/socks-react",
-    "description": "Async SOCKS proxy connector client and server implementation, use any TCP/IP-based protocol through a SOCKS5 or SOCKS4(a) proxy server, built on top of ReactPHP.",
+    "description": "Async SOCKS proxy connector client and server implementation, tunnel any TCP/IP-based protocol through a SOCKS5 or SOCKS4(a) proxy server, built on top of ReactPHP.",
     "keywords": ["socks client", "socks server", "socks5", "socks4a", "proxy server", "tcp tunnel", "async", "ReactPHP"],
     "homepage": "https://github.com/clue/reactphp-socks",
     "license": "MIT",