rail

An enhanced HTTP/RESTful API Client

rail is an io.js/node.js HTTP client supporting https, http and http2.

A set of built-in plugins, currently featuring buffer, cookies, json, redirect, retry, timeout & validate simplify making requests, and a powerful event-driven plugin interface aids in the implementation of complex automated RESTful API calls.

The concept of a single request is extended to a possible series of requests further referenced as a call. This allows a seamless integration of redirect and authentication mechanisms that require multiple requests to satisfy the original one.

The API is mostly compatible with https.request() and allows rail to be used as a drop-in replacement. A completely transparent plugin integration enables scenarios with automated retries on upload stream errors, while still exhibiting a behavior similar to https.request().

rail works with io.js, node.js 0.10.x & 4.1.

Installation
Examples
Use as a drop-in replacement
Plugins
API
Plugin API
Tests
ChangeLog
License

Installation

$ npm install rail --save-exact

Examples

URL only

Directly pass an URL that gets parsed into proto, host, port & path.

var RAIL = require('rail');

RAIL.call('https://www.github.com/skenqbx/rail', function(response) {
  // consume response
}).end();

URL & Plugin Options

Again, only pass an URL, but this time as a property to allow passing of plugin options.

var RAIL = require('rail');

RAIL.call({
  url: 'https://www.github.com/skenqbx/rail',
  buffer: true
}, function(response) {
  if (response.buffer) {
    console.log(response.buffer.toString());
  }
}).end();

Request & Plugin Options

The usual way of supplying every parameter separately.

var RAIL = require('rail');

RAIL.call({
  host: 'www.github.com',
  path: '/skenqbx/rail',
  buffer: true
}, function(response) {
  if (response.buffer) {
    console.log(response.buffer.toString());
  }
}).end();

Custom Client

A custom client allows to define default options and configure a set of plugins for all calls made with that client.

var RAIL = require('rail');

var client = new RAIL({
  // set default request options
  request: {
    host: 'github.com'  // set default host
  },
  // load & configure the buffer plugin
  buffer: {
    default: true // buffer all responses by default
  },
  // load & configure the json plugin
  json: {
    auto: true // try to parse all responses with content-type equal to application/json
  },
  // load & configure the redirect plugin
  redirect: {
    limit: 3 // allow a maximum of three redirects for each call
  }
});

// load custom "my" plugin
client.use('my', MyPlugin/*, pluginOptions */);

Now use the custom client the same way as the globalClient above

var call = client.call({
  path: '/skenqbx/rail'
}, function(response) {
  // check if we got a json response
  if (response.json) {
    console.log(response.json);

  // alternatively use the raw response body
  } else if (response.buffer) {
    console.log(response.buffer.toString());

  // ... or if a bailout happened (buffer max size exceeded)
  } else if (response.buffer !== null) {
    // consume the response
    response.on('readable', function() { /* ... */ });
    response.on('end', function() { /* ... */ });
  }
});

call.on('error', function(err) { /* ... */ });

call.end();

Use as a drop-in replacement

rail does not support the hostname, auth, localAddress & socketPath options, see rail.call() for more information.

When not using https, make sure to set the correct default protocol

var RAIL = require('rail');
RAIL.globalClient.proto = 'http';

... and then replace every call to http.request with RAIL.call.

Alternatively create a custom client with defaults & plugins configured to your needs.

Tests

npm run lint Lint the code using eslint and these rules
npm test Lint the code, run tests with mocha & collect coverage with istanbul
- detailed coverage report is available at coverage/lcov-report/index.html
npm run update Dependency update tests performed by next-update
run ./tools/cross-test.sh to test all relevant io.js/node.js versions, uses nvm

Coverage

Statements   : 98.17% ( 803/818 )
Branches     : 91.53% ( 378/413 )
Functions    : 100% ( 109/109 )
Lines        : 98.17% ( 803/818 )

skenqbx/rail