opossum

What is opossum?

Opossum is a Node.js package that implements the circuit breaker pattern. It helps in making your application more resilient by preventing cascading failures and providing fallback mechanisms when external services fail or become unresponsive.

What are opossum's main functionalities?

Circuit Breaker

This feature allows you to wrap a function that might fail with a circuit breaker. If the function fails too many times, the circuit breaker will open and prevent further calls to the failing function until it recovers.

const CircuitBreaker = require('opossum');

async function asyncFunctionThatCouldFail() {
  // Simulate a function that could fail
  return 'Success!';
}

const breaker = new CircuitBreaker(asyncFunctionThatCouldFail);

breaker.fire()
  .then(console.log)
  .catch(console.error);

Fallback

This feature allows you to specify a fallback function that will be called when the main function fails. This can be useful for providing a default response or alternative behavior when the primary function is unavailable.

const CircuitBreaker = require('opossum');

async function asyncFunctionThatCouldFail() {
  throw new Error('Failed!');
}

const breaker = new CircuitBreaker(asyncFunctionThatCouldFail, {
  fallback: () => 'Fallback response'
});

breaker.fire()
  .then(console.log)
  .catch(console.error);

Status Monitoring

This feature allows you to monitor the status of the circuit breaker. You can listen for events such as 'open', 'halfOpen', and 'close' to take appropriate actions based on the state of the circuit breaker.

const CircuitBreaker = require('opossum');

async function asyncFunctionThatCouldFail() {
  return 'Success!';
}

const breaker = new CircuitBreaker(asyncFunctionThatCouldFail);

breaker.on('open', () => console.log('Circuit breaker opened!'));
breaker.on('halfOpen', () => console.log('Circuit breaker half-open!'));
breaker.on('close', () => console.log('Circuit breaker closed!'));

breaker.fire()
  .then(console.log)
  .catch(console.error);

Other packages similar to opossum

cockatiel

Cockatiel is a resilience library for JavaScript and TypeScript that provides policies for retries, timeouts, and circuit breakers. Compared to Opossum, Cockatiel offers a more comprehensive set of resilience policies and is designed to work seamlessly with TypeScript.

promise-breaker

Promise-breaker is a lightweight library that provides a simple implementation of the circuit breaker pattern for promises. It is less feature-rich compared to Opossum but can be a good choice for simpler use cases where only basic circuit breaker functionality is needed.

brakes

Brakes is a Node.js library that provides a robust implementation of the circuit breaker pattern along with additional features like bulkheading and fallback mechanisms. It is similar to Opossum in terms of functionality but offers more advanced features for handling complex failure scenarios.

README

opossum

Opossum is a Node.js circuit breaker that executes asynchronous functions and monitors their execution status. When things start failing, opossum plays dead and fails fast. If you want, you can provide a fallback function to be executed when in the failure state.

For more about the circuit breaker pattern, there are lots of resources on the web - search it! Here is one place to start reading.

	Project Info
License:	Apache-2.0
Build:	make
Documentation:	https://bucharest-gold.github.io/opossum/
Issue tracker:	https://github.com/bucharest-gold/opossum/issues
Engines:	Node.js 4.x, 5.x, 6.x

Usage

Let's say you've got an API that depends on something that might fail - a network operation, or disk read, for example. Wrap that puppy up in a CircuitBreaker and you have control over your destiny.

const circuitBreaker = require('opossum');

function asyncFunctionThatCouldFail (x, y) {
  return new Promise((resolve, reject) => {
    // Do something, maybe on the network or a disk
  });
}

const options = {
  timeout: 3000, // If our function takes longer than 3 seconds, trigger a failure
  maxFailures: 5, // Once we fail this many times in a row, start failing fast
  resetTimeout: 30000 // After 30 seconds, try again.
};
const breaker = circuitBreaker(asyncFunctionThatCouldFail, options);

breaker.fire('foo', 'bar')
  .then((result) => console.log(result))
  .catch(console.error);

You could also provide a fallback function that will be executed instead of indicating failure. After the resetTimeout expires, opossum will try the circuit again.

const breaker = circuitBreaker(asyncFunctionThatCouldFail, options);
// if asyncFunctionThatCouldFail starts to fail, firing the breaker
// will trigger our fallback function
breaker.fallback(() => 'Sorry, out of service right now');

When a fallback function is triggered, it's considered a failure, and the fallback function will continue to be executed until the breaker is closed, after the resetTimeout has expired.

Browser

Opossum really shines in a browser. You can use it to guard against network failures in your AJAX calls. A browserified version of module is available as a compressed file, or exploded in the dist folder.

Here is an example using hapi.js. See the examples folder for more detail.

// server.js
const server = new Hapi.Server();
server.register(require('inert', (err) => possibleError(err)));
server.route({
  method: 'GET',
  path: '/opossum.js',
  handler: {
    file: {
      path: path.join(__dirname, 'node_modules', 'opossum', 'dist', 'opossum-min.js'),
    }
  }
});

<html>
<head>
  <title>My Super App</title>
  <script type='text/javascript' src="/jquery.js"></script>
  <script type='text/javascript' src="/opossum.js"></script>
  <script type='text/javascript' src="/app.js"></script>
<body>
...
</body>
</head>
</html>

// app.js
const route = 'https://example-service.com/rest/route';
const circuitBreakerOptions = {
  timeout: 500,
  maxFailures: 3,
  resetTimeout: 5000
};

const circuit = circuitBreaker(() => $.get(route), circuitBreakerOptions);
circuit.fallback(() => `${route} unavailable right now. Try later.`));
circuit.on('success', (result) => $(element).append(JSON.stringify(result)}));

$(() => {
  $('#serviceButton').click(() => circuit.fire().catch((e) => console.error(e)));
});

Events

A CircuitBreaker will emit events for important things that occur. Here are the events you can listen for.

• fire - emitted when the breaker is fired.
• reject - emitted when the breaker is open (or halfOpen).
• timeout - emitted when the breaker action times out.
• success - emitted when the breaker action completes successfully
• failure - emitted when the breaker action fails, called with the error
• open - emitted when the breaker state changes to open
• close - emitted when the breaker state changes to closed
• halfOpen - emitted when the breaker state changes to halfOpen
• fallback - emitted when the breaker has a fallback function and executes it

Handling events gives a greater level of control over your application behavior.

const circuit = circuitBreaker(() => $.get(route), circuitBreakerOptions);

circuit.fallback(() => ({ body: `${route} unavailable right now. Try later.` }));

circuit.on('success',
  (result) => $(element).append(
    makeNode(`SUCCESS: ${JSON.stringify(result)}`)));

circuit.on('timeout',
  () => $(element).append(
    makeNode(`TIMEOUT: ${route} is taking too long to respond.`)));

circuit.on('reject',
  () => $(element).append(
    makeNode(`REJECTED: The breaker for ${route} is open. Failing fast.`)));

circuit.on('open',
  () => $(element).append(
    makeNode(`OPEN: The breaker for ${route} just opened.`)));

circuit.on('halfOpen',
  () => $(element).append(
    makeNode(`HALF_OPEN: The breaker for ${route} is half open.`)));

circuit.on('close',
  () => $(element).append(
    makeNode(`CLOSE: The breaker for ${route} has closed. Service OK.`)));

circuit.on('fallback',
  (data) => $(element).append(
    makeNode(`FALLBACK: ${JSON.stringify(data)}`)));

Promises vs. Callbacks

The opossum API uses a Promise as a return value for a breaker that has been fired. But your circuit action - the async function that might fail - doesn't have to return a promise. Check this out.

const fs = require('fs');
const circuitBreaker = require('opossum');

const readFile = circuitBreaker.promisify(fs.readFile);
const breaker = circuitBreaker(readFile, options);

breaker.fire('./package.json', 'utf-8')
  .then(console.log)
  .catch(console.error);

Now, you've got easy monitoring of all those Node.js I/O bount functions. How do you deal with that? Easy, my friend - just promisify it.

And just for fun, your circuit doesn't even really have to be a function. Not sure when you'd use this - but you could if you wanted to.

const breaker = circuitBreaker('foo', options);

breaker.fire()
  .then((result) => console.log(result)) // logs 'foo'
  .catch(console.error);

Promise Interoperability

The Promise implementation used in opossum is compliant with both the ES6 Promise API as well as the promises/A+ API. This means that it doesn't matter what flavor of promise your API uses, opossum should work fine with them. If you would like to control what Promise implementation used in opossum, provide a Promise constructor function in your options when you create the breaker. E.g.

// Force to use native JS promises
const breaker = circuitBreaker(readFile, { Promise: Promise });

Changelog

0.5.0 (2016-12-22)

Bug Fixes

• ensure fallback event emits after function call (df40ea7)
• ensure pending close flag is reset (5a1b70b)
• ensure that promise is rejected on fallback (d4496d8)
• fix (again) browser load of circuitBreaker (58a80fb)
• fix export of module in browser environment (5a0594c)

Features

• allow for a CircuitBreaker as a fallback (85cbc34)
• Full featured browser capabilities (2cc08f0)

<a name="0.4.0"></a>