wwwdude

node-wwwdude

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

Supported HTTP verbs

• GET
• PUT
• POST
• DELETE
• HEAD

Features

• Very customizable (custom headers on client/request basis ...)
• Auto follow redirect
• Flexible handling of responses with event listeners

Installation

You can install install wwwdude via npm:

npm install http://github.com/pfleidi/node-wwwdude/tarball/master 

Usage

A working example:

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

var client = wwwdude.createClient({
    headers: { 'User-Agent': 'fucking magnets' },
  });

client.get('http://google.com/')
  .addListener('error', function (data, resp) {
      sys.puts('Error for: ' + resp.host + ' code: ' + resp.statusCode); 
      sys.puts('Headers: ' + sys.inspect(resp.headers));
    })
  .addListener('network-error', function (err) {
      sys.puts('Network Error: ' + sys.inspect(err));
    })
  .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));
    }).send();

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.
• logger the logger you want to use. Default is an internal logger using sys.log.
• headers a hash with the headers you want to use for each request.

The createClient call returns a Request object. On that request object you can call methods for each supported HTTP verb.

client.get(url[, customHeaders])

Creates a HTTP GET request

client.put(url, payload[, customHeaders])

Creates a HTTP PUT request

client.post(url, payload[, customHeaders])

Creates a HTTP POST request

client.delete(url[, customHeaders)]

Creates a HTTP DELETE request

client.head(url[, customHeaders)]

Creates a HTTP HEAD 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' };

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.
• error emitted when the request was unsuccessful. This is emitted for every response with status code > 400.
• 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

• 100 'continue'
• 101 'switching-protocols'
• 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(); });

Tha passed callback function takes two parameters: data and response. Data contains the content returned from the server. Request is a instance of node's http.ClientResponse.

request.send()

The send() call actually sends the request. The handlers are called when the request returns.

Tests

To run the unit tests, nodeunit and log4js-node are required. You can install them via npm:

npm install nodeunit log4js

There's a Makefile to run the tests:

make test

TODO:

• Add plugin infrastructure
• More configurable redirect following (set max. redirect count, disable following of redirect)
• Pluggable logger support
• Pluggable support for transparent content decoders

License

node-wwwdude is licensed unter the MIT license.