Add bug notes about HTTP streams and throttling

diff --git a/doc/api.markdown b/doc/api.markdown
index c2467a1..da0ee84 100644 (file)
--- a/doc/api.markdown
+++ b/doc/api.markdown
@@ -1801,6 +1801,10 @@ authentication details.
 This object is created internally by a HTTP server--not by the user. It is
 passed as the second parameter to the `'request'` event. It is a writable stream.
 
+BUG: `http.ServerResponse` does not yet implement all the throttling
+mechanisms of writable streams. In particiular the return value of `write()`
+is not in line with the interface and it does not emit a `drain` event.
+
 ### response.writeHead(statusCode[, reasonPhrase] , headers)
 
 Sends a response header to the request. The status code is a 3-digit HTTP
@@ -1946,6 +1950,11 @@ event, the entire body will be caught.
     });
 
 This is a writable stream.
+
+BUG: `http.ClientRequest` does not yet implement all the throttling
+mechanisms of writable streams. In particiular the return value of `write()`
+is not in line with the interface and it does not emit a `drain` event.
+
 This is an `EventEmitter` with the following events:
 
 ### Event 'response'