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
• Very customizable (custom headers on client/request basis ...)
• Automatic redirect following
• Automatic gzip decode support
• Automatic support for HTTPS (node 0.4.x only)
• Flexible handling of responses with event emitters

Installation

You can install install wwwdude via npm:

npm install wwwdude

Usage

A working example:

var sys = require('sys'),
wwwdude = require('wwwdude');

var client = wwwdude.createClient({
    headers: { 'User-Agent': 'wwwdude test 42' },
    gzip: true
  });

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.

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 expresso connect semver

There's a Makefile to run the tests:

make test

TODO:

• More configurable redirect following (set max. redirect count)
• Multipart HTTP Uploads
• setting custom timeout values

License

wwwdude is licensed under the MIT license.