circuit

Prevent cascading failures in your Gleam applications. Circuit breaker pattern with sliding window tracking, OTP-supervised state, and support for both Erlang and JavaScript targets.

---

What is a circuit breaker?

When a downstream service (an API, a database, a queue) starts failing, naively retrying every call makes things worse — you flood a struggling service and slow your whole application down in the process.

A circuit breaker wraps those calls and watches for failures. After enough failures it trips open, blocking calls entirely and returning an error instantly instead of waiting. After a cooldown it allows a single probe call through to check if the service has recovered. If it has, the circuit closes again and normal traffic resumes.

Three states:

State	Behaviour
Closed	Normal. Calls pass through, results are tracked.
Open	Tripped. All calls blocked, Error(CircuitOpen) returned immediately.
HalfOpen	Recovery probe. One call allowed through — success closes, failure re-opens.

---

Installation

gleam add circuit@1

---

Quick Start

import circuit

pub fn main() {
  // 1. Configure and start a breaker
  let assert Ok(breaker) =
    circuit.new()
    |> circuit.failure_threshold(5)  // trip after 5 failures
    |> circuit.window_size(10)       // track the last 10 calls
    |> circuit.reset_timeout(30_000) // wait 30s before probing
    |> circuit.start()

  // 2. Wrap your calls
  case circuit.call(breaker, fn() {
    case fetch_user(42) {
      Ok(_user) -> circuit.Success
      Error(_)  -> circuit.Failure("fetch_user failed")
    }
  }) {
    Ok(Nil)                          -> // call succeeded
    Error(circuit.CircuitOpen)       -> // blocked — use a fallback or return cached data
    Error(circuit.CallFailed(reason)) -> // call ran but failed
  }
}

That's it. The breaker tracks results, manages state transitions, and runs as a supervised OTP process — no global state, no ETS tables.

---

API

Function	Description
new()	Create a Config with default values
failure_threshold(config, n)	Set failures required to trip (default: 5)
window_size(config, n)	Set sliding window size (default: 10)
reset_timeout(config, ms)	Set cooldown before HalfOpen probe (default: 30 000ms)
start(config)	Spawn the breaker actor, returns Result(CircuitBreaker, _)
call(breaker, f)	Run f through the breaker, auto-records result
record_result(breaker, result)	Manually record a Success or Failure
state(breaker)	Read the current CircuitState
reset(breaker)	Manually reset to Closed and clear the window

Full documentation: hexdocs.pm/circuit

---

Development

gleam test  # run the test suite
gleam build # compile and check

---

Made with ♥ using Gleam