wwwdude is a small and flexible http client library on top of node's http.request.
- GET
- PUT
- POST
- DELETE
- HEAD
- Support for Node 0.2.x AND 0.4.x
- Flexible handling of responses with event emitters
- Very customizable (custom headers on client/request basis ...)
- Automatic redirect following
- Automatic gzip decode support
- Automatic content parsing support
- Automatic support for HTTPS (node >= 0.4.x only)
- Support for request timeouts (EXPERIMENTAL, node >= 0.4.x only)
You can install install wwwdude via npm:
npm install wwwdude
A working example:
var sys = require('sys');
var wwwdude = require('wwwdude');
var client = wwwdude.createClient({
headers: { 'User-Agent': 'wwwdude test 42' },
gzip: true,
timeout: 500 // 500ms timeout
});
client.get('http://google.com/')
.addListener('error', function (err) {
sys.puts('Network Error: ' + sys.inspect(err));
})
.addListener('http-error', function (data, resp) {
sys.puts('HTTP Error for: ' + resp.host + ' code: ' + resp.statusCode);
})
.addListener('redirect', function (data, resp) {
sys.puts('Redirecting to: ' + resp.headers['location']);
sys.puts('Headers: ' + sys.inspect(resp.headers));
})
.addListener('success', function (data, resp) {
sys.debug('Got data: ' + data);
sys.puts('Headers: ' + sys.inspect(resp.headers));
});
wwwdude supports transparent parsing of retrieved content. Parsers for XML and JSON are already included. Just add a contentParser property to the options hash when creating a new client:
var client = wwwdude.createClient({
contentParser: wwwdude.parsers.json
});
client.get('http://some.url/content.json').on('success', function (data, response) {
sys.puts('data: ' + sys.inspect(data));
sys.puts('String content: ' + response.rawData);
});
Retrieved content will now be returned as a JavaScript object instead of a string. A string representation can still be found in response.rawData.
It is also possible to create own content parsers. An example fuch such a parser would be:
function parser(content, callback) {
asyncParseOperation(function (error, result) {
if (error) {
callback(error);
} else {
callback(null, result);
}
});
}
var client = wwwdude.createClient({
contentParser: parser
});
Creates a new client object with predefined options for each request made with this instance.
- encoding content encoding. e.g. binary or utf8. Default is utf8.
- followRedirect boolean value which enables/disables automatic redirect following. Default is true.
- gzip boolean value which enables/disables gzip compression
- headers a hash with the headers you want to use for each request.
- contentParser a callback driven content parser e.g. wwwdude.parsers.json.
- timeout a timeout value after which the request should be canceled.
The createClient call returns a Request object. On this object you can call a method for each supported HTTP verb.
Creates a HTTP GET request
Creates a HTTP PUT request
Creates a HTTP POST request
Creates a HTTP DELETE request
Creates a HTTP HEAD request
- headers see customHeaders
- payload content to transmit with PUT or POST request
The customHeaders hash contains a set of HTTP headers which should be added to a request. They are optional. A working example would be:
customHeaders = { 'User-Agent': 'Foo', 'Accept': 'text/html', 'Content-Type': 'application/json' };
Every request call returns a Request object that emits events. You can add listeners for all those events.
- complete emitted when the request has finished. It doesn't matter if it was successful or not.
- success emitted when the request was successful (HTTP code 200).
- error emitted when the request was unsuccessful. This will occur if a network error (tcp, dns, ...) happened.
- http-error emitted when a HTTP status code > 400 was detected.
- http-client-error emitted when a HTTP status code between 400 and 500 was detected.
- http-server-error emitted when a HTTP status code > 500 was detected.
- redirect emitted when a redirect occurred.
- 2XX, 3XX, 4XX, 5XX etc emitted for every request with a response code of the same status class.
- actual response code emitted for every response with a matching response code. E.g. 200, 301, 404 ...
- actual human readable response code emitted for every response with a matching readable response. E.g. 'not-found', 'bad-request', 'forbidden' ...
- 200 'ok'
- 201 'created'
- 202 'accepted'
- 203 'non-authorative-information'
- 204 'no-content'
- 205 'reset-content'
- 207 'partial-content'
- 300 'multiple-choices'
- 301 'moved-permanently'
- 302 'found'
- 303 'see-other'
- 304 'not-modified'
- 305 'use-proxy'
- 307 'temporary-redirect'
- 400 'bad-request'
- 401 'unauthorized'
- 402 'payment-required'
- 403 'forbidden'
- 404 'not-found'
- 405 'method-not-allowed'
- 406 'not-acceptable'
- 407 'proxy-authentication-required'
- 408 'request-timeout'
- 409 'conflict'
- 410 'gone'
- 411 'length-required'
- 412 'precondition-failed'
- 413 'request-entity-too-large'
- 414 'request-uri-too-long'
- 415 'unsupported-media-type'
- 416 'request-range-not-satisfiable'
- 417 'expectation-failed'
- 500 'internal-server-error'
- 501 'not-implemented'
- 502 'bad-gateway'
- 503 'service-unavailable'
- 504 'gateway-timeout'
- 505 'http-version-not-supported'
To register for an event, you can use the addListener() method.
request.addListener(event, function (data, response) { doSomeThing(); });
There is also a shorter alternative method called on():
request.on(event, function (data, response) { doSomeThing(); });
The passed callback function takes two parameters: data and response. Data contains the content returned from the server.
The send() call has been removed. Please don't use it!
To run the unit tests, expresso, semver and connect are required. You can install it via npm:
npm install xml2js-expat expresso connect semver
There's a Makefile to run the tests:
make test
Unfortunately, the tests currently run only on Node >= 0.4, but the client still works on Node 0.2.x.
- More configurable redirect following (loop detection, ttl support)
- Fully automatic content parsing based on Content-Type headers
- Multipart HTTP Uploads
wwwdude is licensed under the MIT license.