The behaviour implemented by circuit breaker backends.

A service's breaker is chosen with the :backend circuit breaker option, and defaults to ExternalService.CircuitBreaker.Fuse — a node-local breaker built on the :fuse library.

Writing a backend

defmodule MyApp.CircuitBreaker do
  @behaviour ExternalService.CircuitBreaker

  @impl true
  def install(service, options) do
    {:ok, %{key: service, tolerate: options[:tolerate]}}
  end

  @impl true
  def ask(_service, config), do: if MyStore.open?(config.key), do: :blown, else: :ok

  @impl true
  def melt(_service, config), do: MyStore.record_failure(config.key)

  @impl true
  def reset(_service, config), do: MyStore.close(config.key)

  @impl true
  def remove(_service, config), do: MyStore.forget(config.key)
end

Backends are stateless modules. install/2 returns an opaque config term that is stored with the rest of the service state (in :persistent_term) and handed back to every other callback, so a backend needs no process, supervisor, or registry of its own.

Driving a breaker directly

Most of the time the breaker is driven for you: ExternalService.call/3 asks it before each attempt and melts it on failure. The functions in this module are for the cases that fall outside a guarded call.

The one that matters is melt/1 — recording a failure the library never saw:

# A streaming connection to the service dropped, or a webhook timed out.
# That is a real failure, but it did not happen inside `call/3`.
ExternalService.CircuitBreaker.melt(:payments)

Melting counts toward the service's configured :tolerate exactly as an in-call failure does, so enough out-of-band failures will open the breaker — and, with ExternalService.CircuitBreaker.Cluster, open it across the cluster.

ask/1 and reset/1 are also here, though ExternalService.available?/1, ExternalService.blown?/1, and ExternalService.reset/1 say the same thing more readably and are usually the better call.