easy-breaker

A simple and low overhead circuit breaker utility.

Install

npm i easy-breaker

Usage

Require the library and initialize it with the function you want to put under the Circuit Breaker.

const EasyBreaker = require('easy-breaker')
const simpleGet = require('simple-get')

const get = EasyBreaker(simpleGet)

get('http://example.com', function (err, res) {
  if (err) throw err
  console.log(res.statusCode)
})

If the function times out, the error will be a TimeoutError. If the threshold has been reached and the circuit is open the error will be a CircuitOpenError.

You can access the errors constructors with require('easy-breaker').errors. You can access the state constants with require('easy-breaker').states.

Options

You can pass some custom option to change the default behavior of EasyBreaker:

const EasyBreaker = require('easy-breaker')
const simpleGet = require('simple-get')

// the following options object contains the default values
const get = EasyBreaker(simpleGet, {
  threshold: 5
  timeout: 1000 * 10
  resetTimeout: 1000 * 10
  context: null,
  maxEventListeners: 100
  promise: false
})

• threshold: is the maximum numbers of failures you accept to have before opening the circuit.
• timeout: is the maximum number of milliseconds you can wait before return a TimeoutError (read the caveats section about how the timeout is handled).
• resetTimeout: time before the circuit will move from open to half-open
• context: a custom context for the function to call
• maxEventListeners: since this library relies on events, it can happen that you reach the maximum number of events listeners before the memory leak warn. To avoid that log, just set an higher number with this property.
• promise: if you need to handle promised API, see below.

Promises

Promises and async-await are supported as well! Just pass the option { promise: true } and you are done! Note the if you use the promise version of the api also the function you are wrapping should return a promise.

const EasyBreaker = require('easy-breaker')
const got = require('got')

const get = EasyBreaker(got, { promise: true })

get('http://example.com')
  .then(console.log)
  .catch(console.log)

Events

This circuit breaker is an event emitter, if needed you can listen to its events:

• open
• half-open
• close
• result
• tick

Caveats

Run a timer for every function is pretty expensive, especially if you are running the code in a heavy load environment. To fix this problem and get better performances, EasyBreaker uses an atomic clock, in other words uses an interval that emits a tick event every timeout / 2 milliseconds. Every running functions listens for that event and if the number of ticks received is higher than 3 it will return a TimeoutError.

Acknowledgements

Image curtesy of Martin Fowler.

License

MIT

Copyright © 2018 Tomas Della Vedova