Electric circuit breaker internals

Today I would like to talk a bit about one of the most commonly used patterns in enterprise architecture — Circuit Breaker — and its implementation using purely functional approach. To make it more interesting, I will implement it as a TypeScript module — so you can use it in your front-end apps.

N.B. The creation of the described package was inspired by the Glue.CircuitBreaker module for Haskell. The module itself is available here: github://circuit-breaker-monad.

What is a Circuit Breaker?

Context and problem definition

Your application is communicating with a third-party service over some kind of protocol. It could be an HTTP API, a socket API, or maybe something else, but it’s major characteristics are these:

You don’t control the network’s reliability, so packets may be dropped at random.

You don’t control the service’s reliability, so it may fail at an unexpected time.

Service errors and network failures are temporary. The service and the environment self-recover themselves after a period of time.

If the service doesn’t respond after a certain timeout, the request is considered as failed.

Solution

Circuit Breaker is a design pattern which resembles a simple finite state machine with the following states:

Closed — requests are transported directly to the service. If the request is failed, the internal error counter is increased. If the amount of errors over a certain time span is greater than the given threshold, the Circuit Breaker’s state is changed to Open, and the internal timer is started — Circuit Breaker gives an external service some time to recover. When the timer goes off, the state is changed to Half-open. Open — requests are immediately finished with error. Half-open — in this state the first request (I will call it a canary request from now on) is allowed to pass to the service. If a canary request succeeds, the error is considered to be solved and the circuit goes to the Closed state again.

This is quite simple description of a Circuit Breaker pattern. You may want to read a blog post by Martin Fowler about Circuit Breaker’s implementation using traditional imperative languages.

Challenges of functional implementation

When you read the description of this pattern, you may have noticed that Circuit Breaker is a stateful pattern, as well as it requires atomic changes of that state (because you want this thing to be as robust as possible, as it should handle all of your network requests).

In a functional world, we have an approach to implement such requirements: an IORef monad — a mutable variable inside the IO monad. Basically, it lets you have a piece of (pure) functional code which communicates with (impure) outside world and atomically modify a variable inside those computations. You may want to take a look at it’s Haskell implementation for more details.

Implementation

Let’s dive into code! As my library of choice, I will use the awesome fp-ts, which already has an implementation of IORef , as well as Task , Either , and their combination ( TaskEither ) monads.

First of all, let’s define our basic logic.

The Circuit Breaker is a proxy wrapper around a network request, which we will model as a simple thunk of Promise<T> , leaving the implementation of the call to the user – whether he or she will use a fetch , a plain ol' XMLHttpRequest or axios , it doesn't matter. As we model our stateful Circuit Breaker using a stateless functional approach, we will utilize a common abstraction technique by taking the state as a parameter to the main function. The result of a Circuit Breaker call we will model as a tuple of the next state and lazy result of the call. We usually represent async interactions using a Task, but the request may fail, leading us to usage of Either monad as well. So the resulting call will be modeled using a TaskEither monad.

Let’s write a representation of Circuit Breaker’s status as a sum type:

Note that I don’t define BreakerHalfOpen status. It is only needed for stateful implementations, where the breaker itself controls its state. But as we are going with 'inverted' functional approach, the "half-open" state can easily be inferred from the combination of current time and BreakerOpen 's payload, timeOpened .

Given these states, our main breaker service could be defined like this:

Implementation of callIfClosed is pretty straightforward:

Function incErrors deals with changing breaker's state from "closed" to "open" if errors count reaches threshold:

The function callIfOpen is more interesting. Remember that we need to pass a request through if the timeout is finished!

And the last part of our puzzle, canaryCall , is really simple:

Conclusion

There you have it, a Circuit Breaker pattern in an (almost) purely functional approach! To make it more useful, it is better to provide configuration for MAX_BREAKER_FAILURES , RESET_TIMEOUT and BREAKER_ERROR_DESCRIPTION variables. I like to do this using a Reader monad. So a final implementation you can find here: github://circuit-breaker-monad. Star, fork and try using in your projects! And if you have a suggestion or you have found an issue, please write me in the Issues section.

I would be happy to know about your experience, so please ping me back at @ybogomolov in Telegram, @YuriyBogomolov in Twitter or via yuriy.bogomolov@gmail.com.