[Pkg-javascript-commits] [node-stream-http] 37/208: Readme improvements

[Bastien Roucariès]

This is an automated email from the git hooks/post-receive script.

rouca pushed a commit to branch master
in repository node-stream-http.

commit 4eed14a948dcdad32b296915d1bbe330e650e537
Author: John Hiesey <john at hiesey.com>
Date:   Tue Jul 7 22:21:01 2015 -0700

    Readme improvements
---
 README.md                        | 63 ++++++++++++++++++++++++++++++++++------
 lib/request.js                   |  5 +---
 test/browser/binary-streaming.js |  2 +-
 3 files changed, 56 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 509a032..99c7454 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,8 @@
 # httpstream
 
 This module is an implementation of node's native `http` module for the browser.
-It tries to match node's API and behavior as closely as possible, but some features
-aren't available, since browsers don't give nearly as much control over requests for security
-reasons.
+It tries to match node's api and behavior as closely as possible, but some features
+aren't available, since browsers don't give nearly as much control over requests.
 
 This is heavily inspired by, and intended to replace, [http-browserify](https://github.com/substack/http-browserify)
 
@@ -14,17 +13,63 @@ the request has completed whenever possible.
 
 The following browsers support true streaming, where only a small amount of the request
 has to be held in memory at once:
-* Chrome >=??? (using the `fetch` api)
-* Firefox >=??? (using `moz-chunked-arraybuffer`)
+* Chrome >= 43 (using the `fetch` api)
+* Firefox >= 9 (using `moz-chunked-arraybuffer` responseType with xhr)
 
 The following browsers support pseudo-streaming, where the data is available before the
 request finishes, but the entire response must be held in memory:
-* Chrome >=(old)
-* Safari >=(old)
+* Chrome
+* Safari >= 5, and maybe older
 * IE >= 10
+* Most other Webkit-based browsers, including the default Android browser
 
-Additionally, older browsers other than IE support pseudo-streaming using multipart
-responses, but only for text (FILL IN HERE)
+All browsers newer than IE8 support binary responses. All of the above browsers that
+support true streaming or pseudo-streaming support that for binary data as well
+except for IE10. Old (presto-based) Opera also does not support binary streaming either.
+
+## How do you use it?
+
+The intent is to have the same api as the client part of the
+[node HTTP module](https://nodejs.org/api/http.html). The interfaces are the same wherever
+practical, although limitations in browsers make an exact clone of the node api impossible.
+
+This module implements `http.request`, `http.get`, and most of `http.ClientRequest`
+and `http.IncomingMessage` in addition to `http.METHODS` and `http.STATUS_CODES`. See the
+node docs for how these work.
+
+### Extra features compared to node
+
+* The `options.withCredentials` boolean flag, used to indicate if the browser should send
+cookies or authentication information with a CORS request. Default true.
+
+This module has to make some tradeoffs to support binary data and/or streaming. Generally,
+the module can make a fairly good decision about which underlying browser features to use,
+but sometimes it helps to get a little input from the user.
+
+* The `options.mode` field passed into `http.request` or `http.get` can take on one of the
+following values:
+  * 'default' (or any falsy value, including undefined): Try to provide partial data before
+the equest completes, but not at the cost of correctness for binary data. In some cases
+the implementation may be a bit slow.
+  * 'prefer-stream': Provide data before the request completes even if binary data (anything
+that isn't a single-byte ASCII or utf8 character) will be corrupted. Of course, this option
+is only safe for text data.
+  * 'prefer-fast': Use an implementation that does less processing even if it means that
+partial data isn't available. This is particularly useful when making large requests in
+a browser like Safari that has a weaker javascript engine.
+
+### Features missing compared to node
+
+* `http.Agent` is only a stub
+* The 'socket', 'connect', 'upgrade', and 'continue' events on `http.ClientRequest`.
+* Any operations, including `request.setTimeout`, that operate directly on the underlying
+socket.
+* Any options that are disallowed for security reasons. This includes setting or getting
+certian headers.
+* `message.httpVersion`
+* `message.rawHeaders` is modified by the browser, and may not quite match what is sent by
+the server.
+* `message.trailers` and `message.rawTrailers` will remain empty.
 
 ## Example
 
diff --git a/lib/request.js b/lib/request.js
index 1e198d4..1dd8225 100644
--- a/lib/request.js
+++ b/lib/request.js
@@ -43,7 +43,7 @@ var ClientRequest = module.exports = function (opts) {
 	if (opts.mode === 'prefer-streaming') {
 		// If streaming is a high priority but binary compatibility isn't
 		preferBinary = false
-	} else if (opts.mode === 'prefer-binary') {
+	} else if (opts.mode === 'prefer-fast') {
 		// If binary is preferred for speed
 		preferBinary = true
 	} else if (!opts.mode || opts.mode === 'default') {
@@ -171,9 +171,6 @@ ClientRequest.prototype._onFinish = function () {
 			return
 		}
 	}
-
-	// This is the best approximation to where 'socket' should be fired
-	self.emit('socket')
 }
 
 /**
diff --git a/test/browser/binary-streaming.js b/test/browser/binary-streaming.js
index a69adb6..59093b2 100644
--- a/test/browser/binary-streaming.js
+++ b/test/browser/binary-streaming.js
@@ -48,7 +48,7 @@ test('binary streaming', function (t) {
 test('large binary request without streaming', function (t) {
 	http.get({
 		path: '/browserify.png?copies=' + COPIES,
-		mode: 'prefer-binary',
+		mode: 'prefer-fast',
 	}, function (res) {
 		var buffers = []
 		res.on('end', function () {

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-javascript/node-stream-http.git