wwwdude

wwwdude

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

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

API

wwwdude.createClient([options]) or wwwdude([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.

The createClient call returns a Request object. On this object you can call a method 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', '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 499 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 and connect are required. You can install it via npm:

npm install expresso connect

There's a Makefile to run the tests:

make test

TODO:

• More configurable redirect following (set max. redirect count)
• Pluggable support for transparent content en/decoders
• https detection
• setting custom timeout values

License

wwwdude is licensed under the MIT license.