145 lines
7.0 KiB
Markdown
145 lines
7.0 KiB
Markdown
# stream-http [](https://travis-ci.org/jhiesey/stream-http)
|
|
|
|
[](https://saucelabs.com/u/stream-http)
|
|
|
|
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.
|
|
|
|
This is heavily inspired by, and intended to replace, [http-browserify](https://github.com/substack/http-browserify).
|
|
|
|
## What does it do?
|
|
|
|
In accordance with its name, `stream-http` tries to provide data to its caller before
|
|
the request has completed whenever possible.
|
|
|
|
Backpressure, allowing the browser to only pull data from the server as fast as it is
|
|
consumed, is supported in:
|
|
* Chrome >= 58 (using `fetch` and `WritableStream`)
|
|
|
|
The following browsers support true streaming, where only a small amount of the request
|
|
has to be held in memory at once:
|
|
* 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
|
|
* Safari >= 5, and maybe older
|
|
* IE >= 10
|
|
* Most other Webkit-based browsers, including the default Android browser
|
|
|
|
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.
|
|
|
|
### IE8 note:
|
|
As of version 2.0.0, IE8 support requires the user to supply polyfills for
|
|
`Object.keys`, `Array.prototype.forEach`, and `Array.prototype.indexOf`. Example
|
|
implementations are provided in [ie8-polyfill.js](ie8-polyfill.js); alternately,
|
|
you may want to consider using [es5-shim](https://github.com/es-shims/es5-shim).
|
|
All browsers with full ES5 support shouldn't require any polyfills.
|
|
|
|
## 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 `message.url` property provides access to the final URL after all redirects. This
|
|
is useful since the browser follows all redirects silently, unlike Node. It is available
|
|
in Chrome 37 and newer, Firefox 32 and newer, and Safari 9 and newer.
|
|
|
|
* The `options.withCredentials` boolean flag, used to indicate if the browser should send
|
|
cookies or authentication information with a CORS request. Default false.
|
|
|
|
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 developer.
|
|
|
|
* 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 request completes, but not at the cost of correctness for binary data or correctness of
|
|
the 'content-type' response header. This mode will also avoid slower code paths whenever
|
|
possible, which is particularly useful when making large requests in a browser like Safari
|
|
that has a weaker JavaScript engine.
|
|
* 'allow-wrong-content-type': Provides partial data in more cases than 'default', but
|
|
at the expense of causing the 'content-type' response header to be incorrectly reported
|
|
(as 'text/plain; charset=x-user-defined') in some browsers, notably Safari and Chrome 42
|
|
and older. Preserves binary data whenever possible. In some cases the implementation may
|
|
also be a bit slow. This was the default in versions of this module before 1.5.
|
|
* '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. May also cause the 'content-type' response header to be
|
|
incorrectly reported (as 'text/plain; charset=x-user-defined').
|
|
* 'disable-fetch': Force the use of plain XHR regardless of the browser declaring a fetch
|
|
capability. Preserves the correctness of binary data and the 'content-type' response header.
|
|
* 'prefer-fast': Deprecated; now a synonym for 'default', which has the same performance
|
|
characteristics as this mode did in versions before 1.5.
|
|
|
|
* `options.requestTimeout` allows setting a timeout in millisecionds for XHR and fetch (if
|
|
supported by the browser). This is a limit on how long the entire process takes from
|
|
beginning to end. Note that this is not the same as the node `setTimeout` functions,
|
|
which apply to pauses in data transfer over the underlying socket, or the node `timeout`
|
|
option, which applies to opening the connection.
|
|
|
|
### 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
|
|
certain 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.
|
|
* Redirects are followed silently by the browser, so it isn't possible to access the 301/302
|
|
redirect pages.
|
|
* The `timeout` event/option and `setTimeout` functions, which operate on the underlying
|
|
socket, are not available. However, see `options.requestTimeout` above.
|
|
|
|
## Example
|
|
|
|
``` js
|
|
http.get('/bundle.js', function (res) {
|
|
var div = document.getElementById('result');
|
|
div.innerHTML += 'GET /beep<br>';
|
|
|
|
res.on('data', function (buf) {
|
|
div.innerHTML += buf;
|
|
});
|
|
|
|
res.on('end', function () {
|
|
div.innerHTML += '<br>__END__';
|
|
});
|
|
})
|
|
```
|
|
|
|
## Running tests
|
|
|
|
There are two sets of tests: the tests that run in Node (found in `test/node`) and the tests
|
|
that run in the browser (found in `test/browser`). Normally the browser tests run on
|
|
[Sauce Labs](http://saucelabs.com/).
|
|
|
|
Running `npm test` will run both sets of tests, but in order for the Sauce Labs tests to run
|
|
you will need to sign up for an account (free for open source projects) and put the
|
|
credentials in a [`.zuulrc` file](https://github.com/defunctzombie/zuul/wiki/zuulrc).
|
|
|
|
To run just the Node tests, run `npm run test-node`.
|
|
|
|
To run the browser tests locally, run `npm run test-browser-local` and point your browser to
|
|
`http://localhost:8080/__zuul`
|
|
|
|
## License
|
|
|
|
MIT. Copyright (C) John Hiesey and other contributors.
|