docs: note stream error handling and destruction. ref: #612

Author: jonathanong

docs/api/response.md

@@ -136,6 +136,23 @@ If `response.status` has not been set, Koa will automatically set the status to
 
   The Content-Type is defaulted to application/octet-stream.
 
+  Whenever a stream is set as the response body, `.onerror` is automatically added as a listener to the `error` event to catch any errors.
+  In addition, whenever the request is closed (even prematurely), the stream is destroyed.
+  If you do not want these two features, do not set the stream as the body directly.
+  For example, you may not want this when setting the body as an HTTP stream in a proxy as it would destroy the underlying connection.
+
+  See: https://github.com/koajs/koa/pull/612 for more information.
+
+  Here's an example of stream error handling without automatically destroying the stream:
+
+```js
+const PassThrough = require('stream').PassThrough
+
+app.use(function * (next) {
+  this.body = someHTTPStream.on('error', this.onerror).pipe(PassThrough())
+})
+```
+
 #### Object
 
   The Content-Type is defaulted to application/json.