Jido.Signal.Dispatch.CircuitBreaker (Jido Signal v1.2.0)

View Source

Circuit breaker wrapper using :fuse for dispatch adapters.

Circuits are per-adapter-type (e.g., one circuit for all HTTP calls, one for all webhook calls). This provides bulk fault isolation without the overhead of per-endpoint circuits.

Configuration

Default settings:

  • 5 failures in 10 seconds triggers the circuit to open
  • 30 second reset time before trying again

Usage

# Install circuit for an adapter type
:ok = CircuitBreaker.install(:http)

# Run a function with circuit breaker protection
case CircuitBreaker.run(:http, fn -> make_request() end) do
  :ok -> :ok
  {:ok, response} -> {:ok, response}
  {:error, :circuit_open} -> {:error, :circuit_open}
  {:error, reason} -> {:error, reason}
end

# Check status
:ok = CircuitBreaker.status(:http)  # or :blown

# Reset manually
:ok = CircuitBreaker.reset(:http)

Summary

Functions

install(adapter_type, opts \\ [])

Installs a circuit breaker for the given adapter type.

installed?(adapter_type)

Checks if a circuit is installed.

reset(adapter_type)

Resets a circuit, allowing requests through again.

run(adapter_type, fun)

Runs a function with circuit breaker protection.

status(adapter_type)

Returns the current status of a circuit.

Functions

install(adapter_type, opts \\ [])

@spec install(
  atom(),
  keyword()
) :: :ok | {:error, term()}

Installs a circuit breaker for the given adapter type.

Should be called once at application startup for each adapter type that needs protection.

Parameters

  • adapter_type - Atom identifying the adapter (e.g., :http, :webhook)
  • opts - Optional configuration:
    • :strategy - Fuse strategy, defaults to {:standard, 5, 10_000} (5 failures in 10 seconds)
    • :refresh - Reset time in milliseconds, defaults to 30_000

Returns

  • :ok - Circuit installed successfully
  • {:error, term()} - Installation failed

installed?(adapter_type)

@spec installed?(atom()) :: boolean()

Checks if a circuit is installed.

Parameters

  • adapter_type - Atom identifying the adapter

Returns

  • true - Circuit is installed
  • false - Circuit is not installed

reset(adapter_type)

@spec reset(atom()) :: :ok

Resets a circuit, allowing requests through again.

Parameters

  • adapter_type - Atom identifying the adapter

Returns

  • :ok - Circuit reset successfully

run(adapter_type, fun)

@spec run(atom(), (-> any())) :: any() | {:error, :circuit_open}

Runs a function with circuit breaker protection.

Returns the function result if the circuit is closed, or {:error, :circuit_open} if open. On failure, the fuse is melted (failure recorded).

Parameters

  • adapter_type - Atom identifying the adapter
  • fun - Zero-arity function to execute

Returns

  • Result of fun if circuit is closed and execution succeeds
  • {:error, :circuit_open} if circuit is open
  • {:error, {:exception, message}} if function raises

status(adapter_type)

@spec status(atom()) :: :ok | :blown

Returns the current status of a circuit.

Parameters

  • adapter_type - Atom identifying the adapter

Returns

  • :ok - Circuit is closed (healthy)
  • :blown - Circuit is open (failing)