Consistent close() and error event semantics

Author: clue

README.md

@@ -22,25 +22,32 @@ Calling this method finalizes the outgoing request body (which may be empty).
 Data will be buffered until the underlying connection is established, at which
 point buffered data will be sent and all further data will be ignored.
 
+The `Request#close()` method can be used to
+forefully close sending the request.
+Unlike the `end()` method, this method discards any buffers and closes the
+underlying connection.
+
 Request implements WritableStreamInterface, so a Stream can be piped to it.
 Interesting events emitted by Request:
 
 * `response`: The response headers were received from the server and successfully
   parsed. The first argument is a Response instance.
 * `drain`: The outgoing buffer drained and the response is ready to accept more
   data for the next `write()` call.
-* `error`: An error occurred.
-* `end`: The request is finished. If an error occurred, it is passed as first
-  argument. Second and third arguments are the Response and the Request.
+* `error`: An error occurred, an `Exception` is passed as first argument.
+* `close`: The request is closed. If an error occurred, this event will be
+  preceeded by an `error` event.
 
 Response implements ReadableStreamInterface.
 Interesting events emitted by Response:
 
-* `data`: Passes a chunk of the response body as first argument and a Response
-  object itself as second argument. When a response encounters a chunked encoded response it will parse it transparently for the user of `Response` and removing the `Transfer-Encoding` header.
-* `error`: An error occurred.
-* `end`: The response has been fully received. If an error
-  occurred, it is passed as first argument.
+* `data`: Passes a chunk of the response body as first argument.
+  When a response encounters a chunked encoded response it will parse it
+  transparently for the user and removing the `Transfer-Encoding` header.
+* `error`: An error occurred, an `Exception` is passed as first argument.
+* `end`: The response has been fully received.
+* `close`: The response is closed. If an error occured, this event will be
+  preceeded by an `error` event.
 
 ### Example
 

src/Request.php

@@ -29,7 +29,6 @@ class Request implements WritableStreamInterface
     private $stream;
     private $buffer;
     private $responseFactory;
-    private $response;
     private $state = self::STATE_INIT;
     private $ended = false;
 
@@ -127,6 +126,7 @@ public function handleDrain()
         $this->emit('drain');
     }
 
+    /** @internal */
     public function handleData($data)
     {
         $this->buffer .= $data;
@@ -135,7 +135,7 @@ public function handleData($data)
             try {
                 list($response, $bodyChunk) = $this->parseResponse($this->buffer);
             } catch (\InvalidArgumentException $exception) {
-                $this->emit('error', [$exception, $this]);
+                $this->emit('error', array($exception));
             }
 
             $this->buffer = null;
@@ -150,8 +150,6 @@ public function handleData($data)
                 return;
             }
 
-            $this->response = $response;
-
             $response->on('close', function () {
                 $this->close();
             });
@@ -169,12 +167,16 @@ public function handleData($data)
         }
     }
 
+    /** @internal */
     public function handleEnd()
     {
-        $this->handleClose();
+        $this->closeError(new \RuntimeException(
+            "Connection ended before receiving response"
+        ));
     }
 
-    public function handleError($error)
+    /** @internal */
+    public function handleError(\Exception $error)
     {
         $this->closeError(new \RuntimeException(
             "An error occurred in the underlying stream",
@@ -183,13 +185,13 @@ public function handleError($error)
         ));
     }
 
+    /** @internal */
     public function handleClose()
     {
-        $this->closeError(new \RuntimeException(
-            "Connection closed before receiving response"
-        ));
+        $this->close();
     }
 
+    /** @internal */
     public function closeError(\Exception $error)
     {
         if (self::STATE_END <= $this->state) {
@@ -212,7 +214,7 @@ public function close()
             $this->stream->close();
         }
 
-        $this->emit('close', array());
+        $this->emit('close');
         $this->removeAllListeners();
     }
 

src/Response.php

@@ -75,22 +75,25 @@ public function getHeaders()
         return $this->headers;
     }
 
+    /** @internal */
     public function handleData($data)
     {
         if ($this->readable) {
             $this->emit('data', array($data));
         }
     }
 
+    /** @internal */
     public function handleEnd()
     {
         if (!$this->readable) {
             return;
         }
-        $this->emit('end', array());
+        $this->emit('end');
         $this->close();
     }
 
+    /** @internal */
     public function handleError(\Exception $error)
     {
         if (!$this->readable) {
@@ -105,6 +108,7 @@ public function handleError(\Exception $error)
         $this->close();
     }
 
+    /** @internal */
     public function handleClose()
     {
         $this->close();
@@ -117,11 +121,10 @@ public function close()
         }
 
         $this->readable = false;
+        $this->stream->close();
 
-        $this->emit('close', array());
-
+        $this->emit('close');
         $this->removeAllListeners();
-        $this->stream->close();
     }
 
     public function isReadable()

tests/RequestTest.php

@@ -216,8 +216,7 @@ public function requestShouldEmitErrorIfGuzzleParseThrowsException()
         $handler->expects($this->once())
             ->method('__invoke')
             ->with(
-                $this->isInstanceOf('\InvalidArgumentException'),
-                $this->isInstanceOf('React\HttpClient\Request')
+                $this->isInstanceOf('\InvalidArgumentException')
             );
 
         $request->on('error', $handler);