From 97c34d19058fc1f5486892389d0457b9ccef8c7b Mon Sep 17 00:00:00 2001 From: Jonathan Ong Date: Sun, 28 Feb 2016 16:18:14 -0800 Subject: [PATCH] docs: note stream error handling and destruction. ref: #612 --- docs/api/response.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/api/response.md b/docs/api/response.md index a5a4ac6..3e357b3 100644 --- a/docs/api/response.md +++ b/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.