flowHttp
Treat node.js http(s) as a simple duplex stream
Install
npm install flowhttp
Basic usage
var flowHttp = ; // A simple GET request; // Upload a filefs;
API
flowHttp.request(options)
At the core of the flowHttp
module is the flowHttp.request()
method.
This method performs a basic HTTP or HTTPS request (defaults to GET).
options
can be an object or a string. If options
is a string, it is
automatically parsed with
url.parse().
The options
argument is identical to the first argument of the
http.request()
method in the http core module. You should check out that documentation
for the most up-to-date info related to your version of node.js.
It returns a flowHttp.Request
object which can be used to send data
along with the request and receive data from the response. This makes it
very easy to read data from any request and optionally write data to a
POST or PUT request.
flowHttp.get(options)
One of 4 convenience methods corresponding to the standard HTTP REST
verbs. The only difference between this method and flowHttp.request()
is that it sets the method to GET and calls req.end()
automatically.
flowHttp.post(options)
One of 4 convenience methods corresponding to the standard HTTP REST
verbs. The only difference between this method and flowHttp.request()
is that it sets the method to POST.
flowHttp.put(options)
One of 4 convenience methods corresponding to the standard HTTP REST
verbs. The only difference between this method and flowHttp.request()
is that it sets the method to PUT.
flowHttp.del(options)
One of 4 convenience methods corresponding to the standard HTTP REST
verbs. The only difference between this method and flowHttp.request()
is that it sets the method to DELETE and calls req.end()
automatically.
flowHttp(options)
Since most requests are GET requests, the flowHttp.get()
method have
been aliased for your convenience.
flowHttp.agent
Set this property to http.globalAgent can easily be overwritten:
flowHttpagent = false; // don't use an agent
For more info about custom agents, see http.Agent.
Class: flowHttp.Request
The Request
object is returned by flowHttp.request()
and its
convenience methods. Request
inherits from
stream.Duplex.
var duplexRequestStream = ;
Besides the normal methods and properties avaliable on a duplex stream, the following API have been made available:
request.req
The native http.ClientRequest object.
request.res
The native
http.IncomingMessage
object. Note that this property will not be available until the
response
event have been emittet.
request.setHeader(name, value)
An alias for request.req.setHeader()
.
request.getHeader(name)
An alias for request.req.getHeader()
.
request.removeHeader(name)
An alias for request.req.removeHeader()
.
Event 'response'
function (response) {}
Get access to the raw http.IncomingMessage reponse object. This is emitted before any data or end event. You would normally not need to listen for this event unless you need to acceess the response headers or status code.
Event 'data'
function (chunk) {}
Emitted for each chunk of the reponse body.
Event 'end'
function () {}
Emitted when the entire reponse have been received.
Event 'error'
function (err) {}
If an error occurs during the request/reponse cycle, you will get notified here.
Examples
A dead simple GET request piped to STDOUT:
;
Same as above by listening to the emitted events:
var body = ''; ;
Upload a picture by piping it through a simple POST request and outputting the response to STDOUT:
fs ;
POST data to the remote server and pipe the response to STDOUT:
var req = flowHttp;req;req;red; // call end to send the request
Piping
A very common usage of flowHttp is to pipe the response to a writable stream:
;
But what if the writeable stream needs access to the
http.IncomingMessage
object? E.g. to know the HTTP status code or read
some of the headers.
To allow for this, a special response
event is emittet to all
writeable streams attached using the request.pipe()
method. Consider
the following example:
var util = ;var zlib = ;var PassThrough = PassThrough; // Decoder that will check the Conent-Encoding headers and optionally// decode the body of the HTTP requestvar { var decoder = this; PassThrough; // Listen for the special `response` event this; // Record the source of the pipe to be used above this;};util; ;
See the flowhttp-decoder module for a fully working example.
Chaining
If you chain multiple streams using the .pipe()
method, you might want
to forward the response
event down the line. A special
readable._forwardFlowHttpResponse()
method have been added to the
Readable
class. This method will therefore be available for all
streams that you pipe from.
See the flowhttp-decoder module as an example of how to implement this in your own streams.
Modules supporting flowHttp
- flowhttp-status - Supply
a whitelist of HTTP status codes. If the HTTP response doesn't conform
to this whitelist, an
error
event will be emittet on the stream - flowhttp-decoder - Automatically decode gzipped and deflated responses
License
MIT