Merge 00db652 into 66e92ff

.gitignore

@@ -3,4 +3,4 @@ build
 composer.lock
 phpunit.xml
 vendor
-reports
+reports

README.md

@@ -1,14 +1,36 @@
-# websocket-server
+# Websocket Server
 
-This package provides a WebSocket `RequestHandler` for [Amp's HTTP server](https://github.com/amphp/http-server).
+This library provides a [Request Handler](https://amphp.org/http-server/classes/request-handler) to easily handle Websocket 
+connections using [amphp/http-server](https://github.com/amphp/http-server).
+
+## Installation
+
+This package can be installed as a [Composer](https://getcomposer.org) dependency.
+
+```
+composer require amphp/websocket-server
+```
+
+> Currently this library is undergoing a RC phase on a push to 2.0! Please check out the 2.0 RC and let us know if you have any feedback.
+
+## Documentation
+
+The documentation for this library is currently a work in progress. Pull Requests to improve the documentation 
+are always welcome!
+
+## Requirements
+
+- PHP 7.1+
 
 ## Example
 
 ```php
 <?php
 
-// Note that this example requires amphp/http-server-router,
-// amphp/http-server-static-content and amphp/log to be installed.
+// Note that this example requires:
+// amphp/http-server-router
+// amphp/http-server-static-content
+// amphp/log
 
 use Amp\Http\Server\Request;
 use Amp\Http\Server\Response;
@@ -18,31 +40,36 @@ use Amp\Http\Server\StaticContent\DocumentRoot;
 use Amp\Log\ConsoleFormatter;
 use Amp\Log\StreamHandler;
 use Amp\Loop;
+use Amp\Promise;
 use Amp\Socket;
+use Amp\Success;
 use Amp\Websocket\Client;
 use Amp\Websocket\Message;
 use Amp\Websocket\Server\Websocket;
 use Monolog\Logger;
 use function Amp\ByteStream\getStdout;
+use function Amp\call;
 
 require __DIR__ . '/vendor/autoload.php';
 
 $websocket = new class extends Websocket {
-    public function onHandshake(Request $request, Response $response): Response
+    public function handleHandshake(Request $request, Response $response): Promise
     {
         if (!\in_array($request->getHeader('origin'), ['http://localhost:1337', 'http://127.0.0.1:1337', 'http://[::1]:1337'], true)) {
             $response->setStatus(403);
         }
 
-        return $response;
+        return new Success($response);
     }
 
-    public function onConnection(Client $client, Request $request): \Generator
+    public function handleClient(Client $client, Request $request, Response $response): Promise
     {
-        while ($message = yield $client->receive()) {
-            \assert($message instanceof Message);
-            $this->broadcast(\sprintf('%d: %s', $client->getId(), yield $message->buffer()));
-        }
+        return call(function() use($client) {
+            while ($message = yield $client->receive()) {
+                \assert($message instanceof Message);
+                $this->broadcast(\sprintf('%d: %s', $client->getId(), yield $message->buffer()));
+            }
+        });  
     }
 };
 

src/Websocket.php

@@ -61,17 +61,22 @@ public function __construct(
 
     /**
      * Respond to websocket handshake requests.
+     *
      * If a websocket application doesn't wish to impose any special constraints on the
      * handshake it doesn't have to do anything in this method (other than return the
      * given Response object) and all handshakes will be automatically accepted.
-     * This method provides an opportunity to set application-specific headers on the
-     * websocket response.
+     *
+     * This method provides an opportunity to set application-specific headers, including
+     * cookies, on the websocket response. Although any non-101 status code can be used
+     * to reject the websocket connection it is generally recommended to use a 4xx status
+     * code that is descriptive of why the handshake was rejected.
      *
      * @param Request  $request The HTTP request that instigated the handshake
      * @param Response $response The switching protocol response for adding headers, etc.
      *
-     * @return Promise<Response> Resolve with the given response to accept the connection
-     *     or resolve with a new Response object to deny the connection.
+     * @return Promise<Response> Resolve the Promise with a Response set to a status code
+     *                           other than {@link Status::SWITCHING_PROTOCOLS} to deny the
+     *                           handshake Request.
      */
     abstract protected function handleHandshake(Request $request, Response $response): Promise;