-
-
Save isaacs/5321376 to your computer and use it in GitHub Desktop.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
From aeef9518c6ecea8bee896dee28b8796814d187c0 Mon Sep 17 00:00:00 2001 | |
From: isaacs <i@izs.me> | |
Date: Fri, 5 Apr 2013 11:07:53 -0700 | |
Subject: [PATCH] doc: Correct caveats for http Readables | |
--- | |
doc/api/http.markdown | 70 +++++++----------------------------------------- | |
1 files changed, 11 insertions(+), 59 deletions(-) | |
diff --git a/doc/api/http.markdown b/doc/api/http.markdown | |
index a6f0641..594d19b 100644 | |
--- a/doc/api/http.markdown | |
+++ b/doc/api/http.markdown | |
@@ -557,28 +557,14 @@ headers have been received. The `'response'` event is executed with one | |
argument which is an instance of `http.IncomingMessage`. | |
During the `'response'` event, one can add listeners to the | |
-response object; particularly to listen for the `'data'` event. Note that | |
-the `'response'` event is called before any part of the response body is received, | |
-so there is no need to worry about racing to catch the first part of the | |
-body. As long as a listener for `'data'` is added during the `'response'` | |
-event, the entire body will be caught. | |
+response object; particularly to listen for the `'data'` event. | |
- | |
- // Good | |
- request.on('response', function (response) { | |
- response.on('data', function (chunk) { | |
- console.log('BODY: ' + chunk); | |
- }); | |
- }); | |
- | |
- // Bad - misses all or part of the body | |
- request.on('response', function (response) { | |
- setTimeout(function () { | |
- response.on('data', function (chunk) { | |
- console.log('BODY: ' + chunk); | |
- }); | |
- }, 10); | |
- }); | |
+If no `'response'` handler is added, then the response will be | |
+entirely discarded. However, if you add a `'response'` event handler, | |
+then you **must** consume the data from the response object, either by | |
+calling `response.read()` whenever there is a `'readable'` event, or | |
+by adding a `'data'` handler, or by calling the `.resume()` method. | |
+Until the data is consumed, the `'end'` event will not fire. | |
Note: Node does not check whether Content-Length and the length of the body | |
which has been transmitted are equal or not. | |
@@ -774,26 +760,8 @@ An `IncomingMessage` object is created by `http.Server` or `http.ClientRequest` | |
and passed as the first argument to the `'request'` and `'response'` event | |
respectively. It may be used to access response status, headers and data. | |
-It implements the [Readable Stream][] interface. `http.IncomingMessage` is an | |
-[EventEmitter][] with the following events: | |
- | |
-### Event: 'data' | |
- | |
-`function (chunk) { }` | |
- | |
-Emitted when a piece of the message body is received. The chunk is a string if | |
-an encoding has been set with `message.setEncoding()`, otherwise it's | |
-a [Buffer][]. | |
- | |
-Note that the __data will be lost__ if there is no listener when a | |
-`IncomingMessage` emits a `'data'` event. | |
- | |
-### Event: 'end' | |
- | |
-`function () { }` | |
- | |
-Emitted exactly once for each response. After that, no more `'data'` events | |
-will be emitted on the response. | |
+It implements the [Readable Stream][] interface, as well as the | |
+following additional events, methods, and properties. | |
### Event: 'close' | |
@@ -802,9 +770,8 @@ will be emitted on the response. | |
Indicates that the underlaying connection was terminated before | |
`response.end()` was called or able to flush. | |
-Just like `'end'`, this event occurs only once per response, and no more | |
-`'data'` events will fire afterwards. See [http.ServerResponse][]'s `'close'` | |
-event for more information. | |
+Just like `'end'`, this event occurs only once per response. See | |
+[http.ServerResponse][]'s `'close'` event for more information. | |
### message.httpVersion | |
@@ -840,21 +807,6 @@ The request/response trailers object. Only populated after the 'end' event. | |
Calls `message.connection.setTimeout(msecs, callback)`. | |
-### message.setEncoding([encoding]) | |
- | |
-Set the encoding for data emitted by the `'data'` event. See [stream.setEncoding()][] for more | |
-information. | |
- | |
-Should be set before any `'data'` events have been emitted. | |
- | |
-### message.pause() | |
- | |
-Pauses request/response from emitting events. Useful to throttle back a download. | |
- | |
-### message.resume() | |
- | |
-Resumes a paused request/response. | |
- | |
### message.method | |
**Only valid for request obtained from `http.Server`.** | |
-- | |
1.7.5.4 | |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment