Prepare v0.6.0 release

Author: clue

CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## 0.6.0 (2017-02-17)
+
+* Feature / BC break: Use `connect($uri)` instead of `create($host, $port)`
+  and resolve with a `ConnectionInterface` instead of `Stream`
+  and expose remote and local addresses through this interface
+  and remove superfluous and undocumented `ConnectionException`.
+  (#74, #82 and #84 by @clue)
+
+  ```php
+  // old
+  $connector->create('google.com', 80)->then(function (Stream $conn) {
+      echo 'Connected' . PHP_EOL;
+      $conn->write("GET / HTTP/1.0\r\n\r\n");
+  });
+
+  // new
+  $connector->connect('google.com:80')->then(function (ConnectionInterface $conn) {
+      echo 'Connected to ' . $conn->getRemoteAddress() . PHP_EOL;
+      $conn->write("GET / HTTP/1.0\r\n\r\n");
+  });
+  ```
+
+  > Note that both the old `Stream` and the new `ConnectionInterface` implement
+    the same underlying `DuplexStreamInterface`, so their streaming behavior is
+    actually equivalent.
+    In order to upgrade, simply use the new typehints.
+    Existing stream handlers should continue to work unchanged.
+
+* Feature / BC break: All connectors now MUST offer cancellation support.
+  You can now rely on getting a rejected promise when calling `cancel()` on a
+  pending connection attempt.
+  (#79 by @clue)
+
+  ```php
+  // old: promise resolution not enforced and thus unreliable
+  $promise = $connector->create($host, $port);
+  $promise->cancel();
+  $promise->then(/* MAY still be called */, /* SHOULD be called */);
+
+  // new: rejecting after cancellation is mandatory
+  $promise = $connector->connect($uri);
+  $promise->cancel();
+  $promise->then(/* MUST NOT be called */, /* MUST be called */);
+  ```
+
+  > Note that this behavior is only mandatory for *pending* connection attempts.
+    Once the promise is settled (resolved), calling `cancel()` will have no effect.
+
+* BC break: All connector classes are now marked `final`
+  and you can no longer `extend` them
+  (which was never documented or recommended anyway).
+  Please use composition instead of extension.
+  (#85 by @clue)
+
 ## 0.5.3 (2016-12-24)
 
 * Fix: Skip IPv6 tests if not supported by the system

README.md

@@ -2,26 +2,35 @@
 
 [![Build Status](https://secure.travis-ci.org/reactphp/socket-client.png?branch=master)](http://travis-ci.org/reactphp/socket-client) [![Code Climate](https://codeclimate.com/github/reactphp/socket-client/badges/gpa.svg)](https://codeclimate.com/github/reactphp/socket-client)
 
-Async Connector to open TCP/IP and SSL/TLS based connections.
+Async, streaming plaintext TCP/IP and secure TLS based connections for [ReactPHP](https://reactphp.org/)
 
-> The master branch contains the code for the upcoming 0.6 release.
-For the code of the current stable 0.5.x release, checkout the
-[0.5 branch](https://github.com/reactphp/socket-client/tree/0.5).
-
-## Introduction
-
-Think of this library as an async version of
+You can think of this library as an async version of
 [`fsockopen()`](http://www.php.net/function.fsockopen) or
 [`stream_socket_client()`](http://php.net/function.stream-socket-client).
-
-Before you can actually transmit and receive data to/from a remote server, you
-have to establish a connection to the remote end. Establishing this connection
-through the internet/network takes some time as it requires several steps in
-order to complete:
-
-1. Resolve remote target hostname via DNS (+cache)
-2. Complete TCP handshake (2 roundtrips) with remote target IP:port
-3. Optionally enable SSL/TLS on the new resulting connection
+If you want to transmit and receive data to/from a remote server, you first
+have to establish a connection to the remote end.
+Establishing this connection through the internet/network may take some time
+as it requires several steps (such as resolving target hostname, completing
+TCP/IP handshake and enabling TLS) in order to complete.
+This component provides an async version of all this so you can establish and
+handle multiple connections without blocking.
+
+**Table of Contents**
+
+* [Usage](#usage)
+  * [ConnectorInterface](#connectorinterface)
+    * [connect()](#connect)
+  * [ConnectionInterface](#connectioninterface)
+    * [getRemoteAddress()](#getremoteaddress)
+    * [getLocalAddress()](#getlocaladdress)
+  * [Plaintext TCP/IP connections](#plaintext-tcpip-connections)
+  * [DNS resolution](#dns-resolution)
+  * [Secure TLS connections](#secure-tls-connections)
+  * [Connection timeout](#connection-timeouts)
+  * [Unix domain sockets](#unix-domain-sockets)
+* [Install](#install)
+* [Tests](#tests)
+* [License](#license)
 
 ## Usage
 
@@ -170,7 +179,7 @@ If your system has multiple interfaces (e.g. a WAN and a LAN interface),
 you can use this method to find out which interface was actually
 used for this connection.
 
-### Async TCP/IP connections
+### Plaintext TCP/IP connections
 
 The `React\SocketClient\TcpConnector` class implements the
 [`ConnectorInterface`](#connectorinterface) and allows you to create plaintext
@@ -271,7 +280,7 @@ $connector = new React\SocketClient\Connector($loop, $dns);
 $connector->connect('www.google.com:80')->then($callback);
 ```
 
-### Async SSL/TLS connections
+### Secure TLS connections
 
 The `SecureConnector` class implements the
 [`ConnectorInterface`](#connectorinterface) and allows you to create secure
@@ -383,15 +392,26 @@ The recommended way to install this library is [through Composer](http://getcomp
 This will install the latest supported version:
 
 ```bash
-$ composer require react/socket-client:^0.5.3
+$ composer require react/socket-client:^0.6
 ```
 
 More details about version upgrades can be found in the [CHANGELOG](CHANGELOG.md).
 
 ## Tests
 
-To run the test suite, you need PHPUnit. Go to the project root and run:
+To run the test suite, you first need to clone this repo and then install all
+dependencies [through Composer](http://getcomposer.org):
+
+```bash
+$ composer install
+```
+
+To run the test suite, go to the project root and run:
 
 ```bash
-$ phpunit
+$ php vendor/bin/phpunit
 ```
+
+## License
+
+MIT, see [LICENSE file](LICENSE).