Node Wwwdude Save

A flexible HTTP client library for node.js

Project README

wwwdude of node's http.request.

Supported HTTP verbs

  • GET
  • PUT
  • POST
  • 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

  .addListener('error', function (err) {
      sys.puts('Network Error: ' + sys.inspect(err));
  .addListener('http-error', function (data, resp) {
      sys.puts('HTTP Error for: ' + + ' 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) {
    } 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.

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


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.


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.

Open Source Agenda is not affiliated with "Node Wwwdude" Project. README Source: pfleidi/node-wwwdude
Open Issues
Last Commit
12 years ago

Open Source Agenda Badge

Open Source Agenda Rating