Resilient HTTP Client

0.4.0 verified Sat Apr 25 auth: no javascript maintenance

A fault-tolerant, reactive HTTP client for Node.js and browsers, designed for distributed systems and microservices. Version 0.4.0 (latest, last released in 2016, no recent updates) provides transparent server fallback, dynamic server discovery (e.g., via Consul), request retry/backoff, and client-side load balancing based on empirical server latency. It is middleware-oriented, lightweight (~9KB gzipped), dependency-free, and supports both callback and promise-based async requests. Differentiates from alternatives like Axios or Got by focusing on resilience patterns (circuit breaker, failover) inspired by Netflix's Ribbon and Chaos Engineering.

Common errors

error module 'resilient' not found ↓

cause Package not installed or missing from node_modules.

fix

Run 'npm install resilient --save'.

error Uncaught TypeError: resilient is not a function ↓

cause Incorrect import: using ES6 import syntax or destructuring import.

fix

Use const resilient = require('resilient');

error TypeError: client.get is not a function ↓

cause client is not properly initialized; perhaps called before module loaded or factory not invoked.

fix

Ensure resilient() is called with options and returns client object.

error Error: connect ECONNREFUSED ↓

cause No servers available or discovery fails; default server list empty.

fix

Configure at least one server in discovery.servers or provide dynamic discovery URL.

error Cannot read property 'body' of undefined ↓

cause The callback is called with (err, res) but res is undefined when error occurs.

fix

Check if err is truthy before accessing res.body.

Warnings

deprecated The package has not been updated since 2016; it uses outdated APIs and may not work with modern Node.js versions. ↓

fix Consider migrating to a maintained alternative like Axios with retry plugins or Got with timeout and retry.

breaking Node.js 4+ required; incompatible with Node.js versions below 4. ↓

fix Upgrade Node.js to version 4 or higher.

gotcha The client does not support promises natively (callback only). Using promises requires wrapping or a library like Bluebird. ↓

fix Use client.get().then() is not available; wrap callbacks in promises.

gotcha Errors from the client use custom error codes (e.g., 'RERR_REQUEST_FAILED'). Standard HTTP errors may not be caught. ↓

fix Check for err.code and compare with resilient error constants.

gotcha The discovery interval and retry count are global; cannot be overridden per-request. ↓

fix Set discovery options in constructor; no per-request override available.

Install

npm install resilient

yarn add resilient

pnpm add resilient

Imports

resilient

wrong

import resilient from 'resilient';

correct

const resilient = require('resilient');

CJS only; no ESM support.

ResilientClient

wrong

const client = new resilient.Client();

correct

const client = resilient({ service: { basePath: '/api' } });

The factory function returns a client instance; no class constructor.

middleware
wrong
```
client.use('middleware');
```
correct
```
client.use(middleware());
```
Middleware must be a function, not a string.

Quickstart

Creates a resilient client with static server discovery, retry, fallback, and round-robin load balancing, then performs a GET request.

const resilient = require('resilient');
const client = resilient({
  service: {
    basePath: '/api',
    timeout: 5000,
    retry: 2,
    fallback: true
  },
  discovery: {
    servers: ['http://server1.example.com', 'http://server2.example.com'],
    interval: 30000
  },
  balancer: {
    policy: 'roundRobin'
  }
});

client.get('/users', (err, res) => {
  if (err) {
    console.error('Request failed:', err.message);
  } else {
    console.log('Response:', res.body);
  }
});