From 524fe9d6cad26d032467a4d056ba61c9798c4e1d Mon Sep 17 00:00:00 2001
From: Niels Theen <werwofl@googlemail.com>
Date: Mon, 20 Mar 2017 23:18:53 +0100
Subject: [PATCH] Adapt README

---
 README.md | 51 +++++++++++++++++++++++++++++++++------------------
 1 file changed, 33 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 3751c332..20fcc6b1 100644
--- a/README.md
+++ b/README.md
@@ -104,25 +104,40 @@ for more details.
 ### Request
 
 A HTTP request will be sent by a client to the [Server](#server).
-The `Server` will receive this request on the `data` event and
-is responsible to create a request object from this data.
-This object will be passed to the callback function.
- 
-The request is an instance of [PSR-7 RequestInterface](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-7-http-message.md#32-psrhttpmessagerequestinterface).
-
-As defined in PSR-7, the `getBody()` method returns a stream instance
-which implements the [PSR-7 StreamInterface](http://www.php-fig.org/psr/psr-7/#psrhttpmessagestreaminterface).
-Note that the incoming request will be processed once the request headers have
-been received, which implies that the (potentially much larger) request body
-may still be outstanding (in a streaming state).
+The `Server` will receive this request and
+is responsible for creating a request object from this data.
+The request will be processed once the request headers have
+been received, irrespective of the (potentially much larger) request body (see also below).
+This object implements the
+[PSR-7 RequestInterface](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-7-http-message.md#32-psrhttpmessagerequestinterface).
+and will be passed to the callback function.
+
+ ```php 
+$http = new Server($socket, function (RequestInterface $request, Response $response) {
+    $response->writeHead(200, array('Content-Type' => 'text/plain'));
+    $response->write("The method of the request is: " . $request->getMethod());
+    $response->end("The requested path is: " . $request->getUri()->getPath());
+});
+```
+
+For more details about the request object, check out the [PSR-7 RequestInterface](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-7-http-message.md#32-psrhttpmessagerequestinterface) documentation.
+
+If you want to access the request body you can use `getBody()`.
+This method returns an instance that implements both the [PSR-7 StreamInterface](http://www.php-fig.org/psr/psr-7/#psrhttpmessagestreaminterface)
+and the [ReactPHP ReadableStreamInterface](https://github.com/reactphp/stream#readablestreaminterface).
+Because of the `ReactPHP ReadableStreamInterface` implemantation
+you have opportunities like receiving large amount of data without
+the need to buffer, deny the request if the body is too big or
+start processing parts of the body without waiting for
+the complete body data.
+Use this to receive the full potential out of such scenarios and
+create a fast application.
 However, most of the `PSR-7 StreamInterface` methods have been
 designed under the assumption of being in control of the request body.
-Given that this does not apply to this server, the following
+This does not apply to this server, the following
 `PSR-7 StreamInterface` methods are not used and SHOULD NOT be called:
 `tell()`, `eof()`, `seek()`, `rewind()`, `write()` and `read()`.
-Instead, the returned stream instance *also* implements the 
-[ReactPHP ReadableStreamInterface](https://github.com/reactphp/stream#readablestreaminterface)
-which gives you access to the incoming request body as the individual chunks
+The stream you access to the incoming request body as the individual chunks
 arrive:
 
 ```php
@@ -161,11 +176,11 @@ advance because the request message uses chunked transfer encoding.
 ```php 
 $http = new Server($socket, function (RequestInterface $request, Response $response) {
     $response->writeHead(200, array('Content-Type' => 'text/plain'));
-    $response->write("Request method: " . $request->getMethod() . "\n");
     if ($request->getBody()->getSize() !== null) {
-        $response->write("Request body size: " . $request->getBody()->getSize() . "\n");
+        $response->end("Request body size: " . $request->getBody()->getSize() . "\n");
+        return;
     }
-    $response->end("The requested path is: " . $request->getUri()->getPath());
+    $response->end("No size given.");
 });
 ```