wwwdude

wwwdude is a small and flexible http client library on top of node's http.request.

Supported HTTP verbs

• GET
• PUT
• POST
• DELETE
• HEAD

Features

• 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)

Installation

You can install install wwwdude via npm:

npm install wwwdude

Usage

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));
    });

Transparent Content Parsing

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.

Creating own content parsers

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
});

API

wwwdude.createClient([options])

Creates a new client object with predefined options for each request made with this instance.

options hash

• 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.

client.get(url [, requestOptions])

Creates a HTTP GET request

client.put(url [, requestOptions])

Creates a HTTP PUT request

client.post(url, [, requestOptions])

Creates a HTTP POST request

client.delete(url[, requestOptions])

Creates a HTTP DELETE request

client.head(url [, requestOptions)]

Creates a HTTP HEAD request

requestOptions hash

• headers see customHeaders
• payload content to transmit with PUT or POST request

customHeaders hash

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' };

Listeners

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' ...

Human readable response codes

• 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.

request.send()

The send() call has been removed. Please don't use it!

Tests

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.

TODO:

• More configurable redirect following (loop detection, ttl support)
• Fully automatic content parsing based on Content-Type headers
• Multipart HTTP Uploads

License

wwwdude is licensed under the MIT license.