Foundation.Infrastructure.CircuitBreaker (foundation v0.1.0)

Circuit breaker wrapper around :fuse library.

Provides standardized circuit breaker functionality with telemetry integration and Foundation-specific error handling. Translates :fuse errors to Foundation.Types.Error structures.

Usage

# Start a fuse instance
{:ok, _pid} = CircuitBreaker.start_fuse_instance(:my_service, options)

# Execute protected operation
case CircuitBreaker.execute(:my_service, fn -> risky_operation() end) do
  {:ok, result} -> result
  {:error, error} -> handle_error(error)
end

# Check circuit status
status = CircuitBreaker.get_status(:my_service)

Summary

Types

fuse_name()
fuse_options()
operation()
operation_result()

Functions

execute(name, operation, metadata \\ %{})

Execute an operation protected by the circuit breaker.

get_status(name)

Get the current status of a circuit breaker.

reset(name)

Reset a blown circuit breaker manually.

start_fuse_instance(name, options \\ [])

Start a new fuse instance with the given name and options.

Types

fuse_name()

@type fuse_name() :: atom()

fuse_options()

@type fuse_options() :: [
  strategy: :standard | :fault_injection,
  tolerance: non_neg_integer(),
  refresh: non_neg_integer()
]

operation()

@type operation() :: (-> any())

operation_result()

@type operation_result() :: {:ok, any()} | {:error, Foundation.Types.Error.t()}

Functions

execute(name, operation, metadata \\ %{})

@spec execute(fuse_name(), operation(), map()) :: operation_result()

Execute an operation protected by the circuit breaker.

Parameters

  • name: Fuse instance name
  • operation: Function to execute
  • metadata: Additional telemetry metadata

Examples

iex> CircuitBreaker.execute(:database, fn -> DB.query("SELECT 1") end)
{:ok, [%{column: 1}]}

iex> CircuitBreaker.execute(:failing_service, fn -> raise "boom" end)
{:error, %Error{error_type: :circuit_breaker_blown}}

get_status(name)

@spec get_status(fuse_name()) :: :ok | :blown | {:error, Foundation.Types.Error.t()}

Get the current status of a circuit breaker.

Parameters

  • name: Fuse instance name

Returns

  • :ok - Circuit is closed (healthy)
  • :blown - Circuit is open (unhealthy)
  • {:error, Error.t()} - Fuse not found or other error

Examples

iex> CircuitBreaker.get_status(:my_service)
:ok

iex> CircuitBreaker.get_status(:blown_service) 
:blown

reset(name)

@spec reset(fuse_name()) :: :ok | {:error, Foundation.Types.Error.t()}

Reset a blown circuit breaker manually.

Parameters

  • name: Fuse instance name

Examples

iex> CircuitBreaker.reset(:my_service)
:ok

start_fuse_instance(name, options \\ [])

@spec start_fuse_instance(fuse_name(), fuse_options()) ::
  :ok | {:error, Foundation.Types.Error.t()}

Start a new fuse instance with the given name and options.

Parameters

  • name: Unique atom identifier for the fuse
  • options: Fuse configuration options

Examples

iex> CircuitBreaker.start_fuse_instance(:database, 
...>   strategy: :standard, tolerance: 5, refresh: 60_000)
{:ok, #PID<0.123.0>}