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.

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 });

Events

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

• fire (or execute) - 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

Development

Contributions to Opossum are welcome! When contributing, be sure that you've added a test for any code changes you've made, and that make test passes.

Releasing

• Make sure everything works: make clean && npm install && make ci
• Run standard-version: npm run release
• Push to GitHub: git push --follow-tags origin master
• Publish to npmjs.com: npm publish
• Assuming all goes well, head over to https://github.com/bucharest-gold/opossum/releases and update the release with any relevant notes. The generated CHANGELOG.md file should be updated, so you can use it to document release changes.
• Tweet, blog and otherwise promote your awesome success!

Changelog

0.4.0 (2016-12-20)

Features

• Full featured browser capabilities (427c155)

<a name="0.3.0"></a>