resilient.js [][travis]

<img align="right" height="150" src="https://raw.githubusercontent.com/resilient-http/resilient-http.github.io/master/images/logo.png" />

A reactive HTTP client for node.js and browsers designed for distributed systems, providing fault tolerance capabilities with transparent server fallback, dynamic server discovery (e.g: using Consul), request retry/backoff logic, optional client-side balancing based on empirical server latency and more...

Provides a simple middleware-oriented programmatic API and featured command-line interface. It has been designed to be lightweight (just ~2K SLOC. 9KB gzipped) and dependency free.

To get started, take a look to how does it work, basic usage, examples and API docs.

Resilient is conceptually similar to Ribbon, a Netflix's project and it was inspired by Chaos Engineering.

Contents

• Features
• Installation
• Environments
• Middleware layer
• Framework-specific adapters
• Related projects
• How does it work?
• Basic usage
  • Static servers
  • Dynamic servers lookup
• Middleware Layer
  • Types of middleware
  • Middleware API
• Command-line interface
• API
  • Client
  • Options
    • Service
    • Balancer
    • Discovery
  • Built-in errors
  • Events
• FAQ
• Contributing
• License

Features

• Supports callback and promise based async requests.
• Reliable failover and error handling with transparent server fallback
• Smart network error handling covering multiple failure scenarios
• Smart balancer logic based on empirical server score (network latency, errors and succesfull requests)
• Transparent request retry cycle attempts on failure (configurable)
• Discern best servers based on scoring per read and write operations when balancing
• In/out traffic extensible middleware layer
• Configurable balancer policy by weight
• Configurable timeouts, retry loop, cache TTL, fallback behavior...)
• Avoid fallback/retry cycles per custom HTTP responses codes or verbs
• Define custom timeouts per HTTP method (e.g permissive for POST/PUT/DELETE, aggressive for GET)
• Parallel servers discovering for faster availability
• Built-in support for request/response interceptors (via middleware)
• Built-in support for servers caching to improve reliability when fallback
• Configurable external HTTP client to use as forward request proxy (instead of using the embedded one)
• Dynamic servers auto discovering (based on the resilient specification or via middleware)
• Able to plug in custom failure strategies to determine if a request was failed or not.
• Supports promiscuous errors (handles 400-499 codes as fallback errors)
• Supports pre/post request hooks via event bus API
• Supports mock/stub working mode via middleware (useful for testing)
• Reliable HTTP client (it uses internally request and lil-http for the browser)
• Round robin scheduling algorithm for traffic distribution (experimental)
• Featured cURL-inspired command-line interface
• Lightweight library (just ~2K SLOC, 9KB gzipped)
• Dependency free in browser environments (in node.js it only depends on request package)
• Cross JS engine. ES5/6 compliant (requires Promise global to be available)

Installation

Via npm

npm install resilient

Via Bower

bower install resilient

Via Component

component install resilient-http/resilient.js

Or loading the script remotely

<script src="//cdn.rawgit.com/resilient-http/resilient.js/0.4.0/resilient.js"></script>

Environments

Runs in any ES5 compliant engine.

| | | | | --- | --- | --- | --- | --- | --- | +4 | +33 | +29 | +10 | +19 | +7.1 |

Middleware

• Consul - Example

Framework-specific adapters

• angular-resilient - Turn $http into a resilient and fault tolerant client

Related projects

• resilient-server - node.js powered dummy HTTP lookup server for testing/development

How to use?

See the basic usage and examples for detailed use cases

How does it work?

The following graph represents from a high-level point of view the internal logic encapsulated in Resilient HTTP client.

<img src="http://rawgit.com/resilient-http/resilient-http.github.io/master/images/algorithm.svg" />

Basic usage

If require is available, you must use it to fetch the module. Otherwise it will be available as global exposed as resilient

var Resilient = require('resilient')

Static servers

Define your service servers pool

var servers = [
  'http://api1.server.com',
  'http://api2.server.com',
  'http://api3.server.com'
]

Create a new client and set the servers to balance

var client = Resilient({ service: { basePath: '/api/1.0' }})
client.setServers(servers)

Perform a request (the best available server will be used automatically)

client.get('/users').then(function (res) {
  if (res.status === 200) {
    console.log('Success:', res.data)
  }
})

Dynamic servers lookup

Define the lookup servers pool

var servers = [
  'http://discover1.server.com',
  'http://discover2.server.com',
  'http://discover3.server.com'
]

Create a new client and set the discovering servers

var client = Resilient({ service: { basePath: '/api/1.0' }})
client.discoveryServers(servers)

Finally, perform the request (and that's all, Resilient will take care about everything to reach the best server)

client.get('/users').then(function (res) {
  if (res.status === 200) {
    console.log('Success:', res.data)
  }
})

Note: you could use Consul or other HTTP server using a custom middleware as discovery server. For more information about the Resilient discovery interface, take a look at the documentation

For more usage cases take a look to the examples

Middleware Layer

From version 0.3.x Resilient introduces support for duplex middleware. It essentially provides an interceptor like layer to use external components to augment a specific functionality.

From a high-level point of view it's conceptually similar to an evented API approach, which is commonly used in a event-driven environment with JavaScript, but in this case it's slightly different in terms of flow control nature and relies more in data mutation compared to events.

The significant feature in Resilient middleware layer is that it provides bidirectional control flow for both incoming and outgoing HTTP traffic. This allows you to perform multiple actions before and after a request of a specific type is made by Resilient. This might be considered also as a sort hooks in aspect-oriented programming.

Types of middleware

Since Resilient is divided in two communication live cycle layers, one for the discovery servers and the other one for the service end servers, middleware can be created for both layers:

• service - Default. Use this type in middleware which are oriented for final servers communication, such as request transformers, autorization...
• discovery - Use this type in middleware which are oriented only for lookup communication, for instance used as adapter for a lookup server which is not compatible with the Resilient lookup protocol.

Note: the middleware type should be defined a static member of the middleware returned function, using the type property.

Middleware API

Required interface for middleware:

Function([ params ])
  -> Func