\href{https://saucelabs.com/u/stream-http}{\texttt{ }}

This module is an implementation of Node\textquotesingle{}s native {\ttfamily http} module for the browser. It tries to match Node\textquotesingle{}s API and behavior as closely as possible, but some features aren\textquotesingle{}t available, since browsers don\textquotesingle{}t give nearly as much control over requests.

This is heavily inspired by, and intended to replace, \href{https://github.com/substack/http-browserify}{\texttt{ http-\/browserify}}.\hypertarget{md_sfcode_node_modules_stream_http_README_autotoc_md28920}{}\doxysection{What does it do?}\label{md_sfcode_node_modules_stream_http_README_autotoc_md28920}
In accordance with its name, {\ttfamily 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\+:
\begin{DoxyItemize}
\item Chrome $>$= 58 (using {\ttfamily fetch} and {\ttfamily Writable\+Stream})
\end{DoxyItemize}

The following browsers support true streaming, where only a small amount of the request has to be held in memory at once\+:
\begin{DoxyItemize}
\item Chrome $>$= 43 (using the {\ttfamily fetch} API)
\item Firefox $>$= 9 (using {\ttfamily moz-\/chunked-\/arraybuffer} response\+Type with xhr)
\end{DoxyItemize}

The following browsers support pseudo-\/streaming, where the data is available before the request finishes, but the entire response must be held in memory\+:
\begin{DoxyItemize}
\item Chrome
\item Safari $>$= 5, and maybe older
\item IE $>$= 10
\item Most other Webkit-\/based browsers, including the default Android browser
\end{DoxyItemize}

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.\hypertarget{md_sfcode_node_modules_stream_http_README_autotoc_md28921}{}\doxysubsection{IE8 note\+:}\label{md_sfcode_node_modules_stream_http_README_autotoc_md28921}
As of version 2.\+0.\+0, IE8 support requires the user to supply polyfills for {\ttfamily Object.\+keys}, {\ttfamily Array.\+prototype.\+for\+Each}, and {\ttfamily Array.\+prototype.\+index\+Of}. Example implementations are provided in \href{ie8-polyfill.js}{\texttt{ ie8-\/polyfill.\+js}}; alternately, you may want to consider using \href{https://github.com/es-shims/es5-shim}{\texttt{ es5-\/shim}}. All browsers with full ES5 support shouldn\textquotesingle{}t require any polyfills.\hypertarget{md_sfcode_node_modules_stream_http_README_autotoc_md28922}{}\doxysection{How do you use it?}\label{md_sfcode_node_modules_stream_http_README_autotoc_md28922}
The intent is to have the same API as the client part of the \href{https://nodejs.org/api/http.html}{\texttt{ Node HTTP module}}. The interfaces are the same wherever practical, although limitations in browsers make an exact clone of the Node API impossible.

This module implements {\ttfamily http.\+request}, {\ttfamily http.\+get}, and most of {\ttfamily http.\+Client\+Request} and {\ttfamily http.\+Incoming\+Message} in addition to {\ttfamily http.\+METHODS} and {\ttfamily http.\+STATUS\+\_\+\+CODES}. See the Node docs for how these work.\hypertarget{md_sfcode_node_modules_stream_http_README_autotoc_md28923}{}\doxysubsection{Extra features compared to Node}\label{md_sfcode_node_modules_stream_http_README_autotoc_md28923}

\begin{DoxyItemize}
\item The {\ttfamily 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.
\item The {\ttfamily options.\+with\+Credentials} boolean flag, used to indicate if the browser should send cookies or authentication information with a CORS request. Default false.
\end{DoxyItemize}

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.


\begin{DoxyItemize}
\item The {\ttfamily options.\+mode} field passed into {\ttfamily http.\+request} or {\ttfamily http.\+get} can take on one of the following values\+:
\begin{DoxyItemize}
\item \textquotesingle{}default\textquotesingle{} (or any falsy value, including {\ttfamily undefined})\+: Try to provide partial data before the request completes, but not at the cost of correctness for binary data or correctness of the \textquotesingle{}content-\/type\textquotesingle{} 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 Java\+Script engine.
\item \textquotesingle{}allow-\/wrong-\/content-\/type\textquotesingle{}\+: Provides partial data in more cases than \textquotesingle{}default\textquotesingle{}, but at the expense of causing the \textquotesingle{}content-\/type\textquotesingle{} response header to be incorrectly reported (as \textquotesingle{}text/plain; charset=x-\/user-\/defined\textquotesingle{}) 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.
\item \textquotesingle{}prefer-\/stream\textquotesingle{}\+: Provide data before the request completes even if binary data (anything that isn\textquotesingle{}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 \textquotesingle{}content-\/type\textquotesingle{} response header to be incorrectly reported (as \textquotesingle{}text/plain; charset=x-\/user-\/defined\textquotesingle{}).
\item \textquotesingle{}disable-\/fetch\textquotesingle{}\+: Force the use of plain XHR regardless of the browser declaring a fetch capability. Preserves the correctness of binary data and the \textquotesingle{}content-\/type\textquotesingle{} response header.
\item \textquotesingle{}prefer-\/fast\textquotesingle{}\+: Deprecated; now a synonym for \textquotesingle{}default\textquotesingle{}, which has the same performance characteristics as this mode did in versions before 1.\+5.
\end{DoxyItemize}
\item {\ttfamily options.\+request\+Timeout} 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 {\ttfamily set\+Timeout} functions, which apply to pauses in data transfer over the underlying socket, or the node {\ttfamily timeout} option, which applies to opening the connection.
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_stream_http_README_autotoc_md28924}{}\doxysubsection{Features missing compared to Node}\label{md_sfcode_node_modules_stream_http_README_autotoc_md28924}

\begin{DoxyItemize}
\item {\ttfamily http.\+Agent} is only a stub
\item The \textquotesingle{}socket\textquotesingle{}, \textquotesingle{}connect\textquotesingle{}, \textquotesingle{}upgrade\textquotesingle{}, and \textquotesingle{}continue\textquotesingle{} events on {\ttfamily http.\+Client\+Request}.
\item Any operations, including {\ttfamily request.\+set\+Timeout}, that operate directly on the underlying socket.
\item Any options that are disallowed for security reasons. This includes setting or getting certain headers.
\item {\ttfamily message.\+http\+Version}
\item {\ttfamily message.\+raw\+Headers} is modified by the browser, and may not quite match what is sent by the server.
\item {\ttfamily message.\+trailers} and {\ttfamily message.\+raw\+Trailers} will remain empty.
\item Redirects are followed silently by the browser, so it isn\textquotesingle{}t possible to access the 301/302 redirect pages.
\item The {\ttfamily timeout} event/option and {\ttfamily set\+Timeout} functions, which operate on the underlying socket, are not available. However, see {\ttfamily options.\+request\+Timeout} above.
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_stream_http_README_autotoc_md28925}{}\doxysection{Example}\label{md_sfcode_node_modules_stream_http_README_autotoc_md28925}

\begin{DoxyCode}{0}
\DoxyCodeLine{http.get('/bundle.js', function (res) \{}
\DoxyCodeLine{    var div = document.getElementById('result');}
\DoxyCodeLine{    div.innerHTML += 'GET /beep<br>';}
\DoxyCodeLine{}
\DoxyCodeLine{    res.on('data', function (buf) \{}
\DoxyCodeLine{        div.innerHTML += buf;}
\DoxyCodeLine{    \});}
\DoxyCodeLine{}
\DoxyCodeLine{    res.on('end', function () \{}
\DoxyCodeLine{        div.innerHTML += '<br>\_\_END\_\_';}
\DoxyCodeLine{    \});}
\DoxyCodeLine{\}) }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_stream_http_README_autotoc_md28926}{}\doxysection{Running tests}\label{md_sfcode_node_modules_stream_http_README_autotoc_md28926}
There are two sets of tests\+: the tests that run in Node (found in {\ttfamily test/node}) and the tests that run in the browser (found in {\ttfamily test/browser}). Normally the browser tests run on \href{http://saucelabs.com/}{\texttt{ Sauce Labs}}.

Running {\ttfamily 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 \href{https://github.com/defunctzombie/zuul/wiki/zuulrc}{\texttt{ {\ttfamily .zuulrc} file}}.

To run just the Node tests, run {\ttfamily npm run test-\/node}.

To run the browser tests locally, run {\ttfamily npm run test-\/browser-\/local} and point your browser to {\ttfamily \href{http://localhost:8080/__zuul}{\texttt{ http\+://localhost\+:8080/\+\_\+\+\_\+zuul}}}\hypertarget{md_sfcode_node_modules_stream_http_README_autotoc_md28927}{}\doxysection{License}\label{md_sfcode_node_modules_stream_http_README_autotoc_md28927}
MIT. Copyright (C) John Hiesey and other contributors. 