README.md

CB2

Implementation of the circuit breaker pattern in Ruby, backed by Redis.

Setup circuit breakers wrapping external service calls, be it HTTP, TCP, etc. When a service becomes unavailable the circuit breaker will open and quickly refuse any additional requests to it. After a specific window the breaker closes again, allowing calls to go through.

This pattern makes your application more resilient to third party failures, because it won't exhaust resources trying to make calls to an unresponsive service. This is particularly relevant to apps running on servers susceptible to request queuing, like Unicorn or Puma. It can also help the services you depend on to recover faster, by reducing the load on them.

CB2 tracks errors over a rolling window of time (size configurable), and opens after the error rate hits a certain percentage. The circuit stays open (rejecting calls) for another specified period, and then from there it goes to the half-open state: in which a succesful request will make it close again, but a failure will put it immediatelly back at the open state. Martin Fowler has a nice diagram to further explain these states.

Usage

Instantiate a circuit breaker:

breaker = CB2::Breaker.new(
  service: "aws"       # identify each circuit breaker individually
  duration: 60,        # keep track of errors over a 1 min window
  threshold: 5,        # open the circuit breaker when error rate is at 5%
  reenable_after: 600, # keep it open for 10 mins
  redis: Redis.new)    # redis connection it should use to keep state

Then wrap service calls with it:

breaker.run do
  some_api_request()
end

The breaker will open when that block raises enough exceptions to trigger the threshold. Handle these exceptions to react accordingly:

begin
  breaker.run do
    some_api_request()
  end
rescue CB2::BreakerOpen
  alternate_response() # fallback to cached data, or raise a user-friendly exception
end

Custom-Handling Errors

You may not want certains errors to count towards the circuit opening.

To do so, add an entry to the hash table in the handle options, where the key is the class of the error to be handled, and the value is a function that accepts an error as a parameter, and returns true if it should be processed, false otherwise.

breaker = CB2::Breaker.new(
  service: "aws"       # identify each circuit breaker individually
  duration: 60,        # keep track of errors over a 1 min window
  threshold: 5,        # open the circuit breaker when error rate is at 5%
  reenable_after: 600, # keep it open for 10 mins
  redis: Redis.new,    # redis connection it should use to keep state
  handle: { RuntimeError => Proc.new { |e| e.message == 'foo' } })

Circuit breaker stub

CB2 can also run as a stub. Use it to aid testing, simulations and gradual rollouts:

breaker = CB2::Breaker.new(
  strategy: "stub",
  allow: true) # set it to false to always block requests

See also

This might be the only percent-based breaker in Ruby so far. For count-based breakers (eg: open after X exceptions) you can also check breaker_box and circuit_breaker.

Meta

Created by Pedro Belo.