Per-endpoint circuit breaker with three states: closed, open, and half-open.
Protects downstream Aurinko API endpoints from cascading failures.
States
- Closed — Normal operation. Requests flow through.
- Open — Too many failures. Requests are rejected immediately without hitting the API.
- Half-open — Cooldown expired. A single probe request is allowed through. If it succeeds, the circuit closes. If it fails, the circuit reopens.
Configuration
config :aurinko,
circuit_breaker_enabled: true,
circuit_breaker_threshold: 5, # failures before opening
circuit_breaker_timeout: 30_000, # ms before transitioning to half-open
circuit_breaker_window: 60_000 # rolling window for failure counting (ms)Usage
Aurinko.CircuitBreaker.call("email.list", fn -> make_request() end)Summary
Functions
Execute fun through the named circuit breaker.
Returns a specification to start this module under a supervisor.
Manually reset (close) a circuit breaker.
Return current state of a named circuit.
Types
@type circuit_name() :: String.t()
@type circuit_state() :: %{ name: circuit_name(), state: state_name(), failure_count: non_neg_integer(), last_failure_at: integer() | nil, opened_at: integer() | nil, success_count: non_neg_integer() }
@type state_name() :: :closed | :open | :half_open
Functions
@spec call(circuit_name(), (-> result)) :: result | {:error, :circuit_open} when result: term()
Execute fun through the named circuit breaker.
Returns {:error, :circuit_open} if the circuit is open and the request
should not be attempted.
Examples
Aurinko.CircuitBreaker.call("aurinko.email", fn ->
Req.get("https://api.aurinko.io/v1/email/messages")
end)Returns a specification to start this module under a supervisor.
See Supervisor.
@spec reset(circuit_name()) :: :ok
Manually reset (close) a circuit breaker.
@spec status(circuit_name()) :: circuit_state()
Return current state of a named circuit.