defmodule TripSwitch do
@moduledoc """
TripSwitch is an Elixir implementation of a circuit breaker. The circuit
breaker is a popular pattern in softwares that depends on various
components/services to keep running.
This library allows you wrap calls (signals) to remote calls in a trip switch.
The switch monitors each invocation and records failures, the trip switch gets
broken once the recorded failures reaches or surpasses the specified threshold.
## Signal
A signal is simple a function that gets invoked. The state of the trip switch gets
updated based on the result (current) of this signal, see `t:TripSwitch.signal/0`.
### Examples
iex> TripSwitch.send(id, fn -> {:ok, :good} end)
{:ok, :good}
iex> TripSwitch.send(id, fn -> {:error, :bad} end) # record this signal as a failure
{:error, :bad}
Note that a switch only stops invoking a signal after the failure threshold have been
reached. In this case, the switch keeps is considered `broken` until it's repaired.
## Repairs
It's obvious you are asking yourself what you should do when a trip switch gets broken. This
library have a concept called Repair. What this means is that a switch is sent for repair
automatically once it gets broken. Not all trip switches are considered fixable, you
need to specify a `repair_time` (in milliseconds) when the trip switch is created
else you need to manually fix (reset) the trip switch whenever it gets broken.
## Thresholds
For a trip switch to function correctly, a threshold is needed to be specified. This allows
us to define the capacity/expectation of the trip switch. The threshold is specified as
a float value, usually between 0 and 1 (ex. 0.2566 or 0.13 and so on).
Simply, a threshold is the percentage of bad signals a trip switch receives before it gets
broken and sent for repair.
## Usage
To create a trip switch you need to add it to your supervision tree:
```elixir
children = [{TripSwitch, name: :switch, threshold: 0.5}]
Supervisor.start_link(children, opts)
```
It supports following options:
- `:name` - this will be used as the id for the switch
- `:threshold` - the maximum number of thresholds before the switch trips
- `:repair_time` - time taken for the switch to get fixed after it gets broken
## Telemetry
Being a big fan of observability, this library exposes information about it internals
using the community approved library (`telemetry`). You can use the `telemetry_poller`
library to poll these metrics. Below are events that this library publishes.
Below are events published by `trip_switch`:
* `[:trip_switch, :signal, :start]` - dispatched before a given signal is handled
* Measurement: `%{system_time: system_time}`
* Metadata: `%{id: atom(), tag: String.t()}`
* `[:trip_switch, :signal, :stop]` - dispatched after a given signal have been handled
* Measurement: ` %{duration: native_time}`
* Metadata: `%{id: atom(), tag: String.t()}`
* `[:trip_switch, :repair, :start]` - dispatched when auto-repair is scheduled
* Measurement: `%{system_time: system_time}`
* Metadata: `%{id: atom(), tag: String.t()}`
* `[:trip_switch, :repair, :stop]` - dispatched after an auto-repair have been completed
* Measurement: ` %{duration: native_time}`
* Metadata: `%{id: atom(), tag: String.t()}`
"""
use GenServer
alias TripSwitch.Breaker
@type signal :: (() -> Breaker.current())
@event_prefix :trip_switch
@doc """
Checks if the switch is broken.
A switch is considered broken if the underlying breaker is `half_open` or `open`.
## Examples
iex> TripSwitch.broken?(:switch)
true
"""
@spec broken?(atom()) :: boolean()
def broken?(id), do: Breaker.broken?(get(id))
@doc """
Send a signal to the underlying breaker.
The signal is a function that performs some actions then return
a result that alters the state of the underlying breaker.
## Examples
iex> TripSwitch.send(:switch, fn -> {:ok, %{name: "a"}}) end)
{:ok, %{name: "a"}}
iex> TripSwitch.send(:switch, fn -> {:error, :not_found} end)
{:error, :not_found}
"""
@spec send(atom(), signal()) :: {:ok, term()} | :broken
def send(id, signal) do
metadata = %{id: id, tag: FlakeId.get()}
:telemetry.span([@event_prefix, :signal], metadata, fn ->
with %Breaker{} = breaker <- get(id),
false <- Breaker.broken?(breaker),
{result, breaker} <- Breaker.handle(breaker, signal.()),
:ok <- GenServer.call(via(id), {:save, breaker}) do
{result, metadata}
else
true -> {:broken, metadata}
end
end)
end
@doc """
Reset the given switch.
Calling this function on a broken switch returns it to a working state.
### Examples
iex> TripSwitch.reset(:switch)
:ok
"""
@spec reset(atom()) :: :ok
def reset(id), do: GenServer.call(via(id), :reset)
@spec child_spec(keyword()) :: Supervisor.child_spec()
def child_spec(opts) do
unless name = opts[:name] do
raise ArgumentError, "expected :name option to be present"
end
Supervisor.child_spec(super(opts), id: {__MODULE__, name})
end
@impl GenServer
def init(opts), do: {:ok, %{breaker: Breaker.new(opts), repair: nil}}
@doc false
@spec start_link(keyword()) :: GenServer.on_start()
def start_link(opts) do
name = Keyword.fetch!(opts, :name)
GenServer.start_link(__MODULE__, opts, name: via(name))
end
@impl GenServer
def handle_call(:get, _from, %{breaker: breaker} = state) do
{:reply, breaker, state}
end
def handle_call(:reset, _from, %{breaker: breaker} = state) do
state = cancel_timer(%{state | breaker: Breaker.reset(breaker)})
{:reply, :ok, state}
end
def handle_call({:save, breaker}, _from, state) do
state = schedule_or_cancel_repair(breaker, state)
{:reply, :ok, state}
end
@impl GenServer
def handle_info({:repair, start_time, tag}, %{breaker: breaker} = state) do
state = cancel_timer(%{state | breaker: Breaker.repair(breaker)})
:ok = emit_repair_stop_event(get_id(), start_time, tag)
{:noreply, state}
end
defp schedule_or_cancel_repair(%Breaker{repair_time: at} = breaker, state) do
with true <- Breaker.repairable?(breaker),
state <- cancel_timer(state),
{start_time, tag} <- emit_repair_start_event(get_id()),
timer <- Process.send_after(self(), {:repair, start_time, tag}, at) do
%{state | breaker: breaker, repair: timer}
else
false -> cancel_timer(%{state | breaker: breaker})
end
end
defp get_id do
[id] = Registry.keys(TripSwitch.Registry, self())
id
end
defp cancel_timer(state) do
case state.repair do
ref when is_reference(ref) ->
Process.cancel_timer(ref)
%{state | repair: nil}
nil ->
state
end
end
defp emit_repair_start_event(id) do
tag = FlakeId.get()
now = System.system_time()
metadata = %{id: id, tag: tag}
measurements = %{monotonic_time: System.monotonic_time(), system_time: now}
:ok = :telemetry.execute([@event_prefix, :repair, :start], measurements, metadata)
{now, tag}
end
defp emit_repair_stop_event(id, start_time, tag) do
now = System.monotonic_time()
metadata = %{id: id, tag: tag}
measurements = %{
monotonic_time: now,
duration: start_time - now
}
:ok = :telemetry.execute([@event_prefix, :repair, :stop], measurements, metadata)
end
defp get(id), do: GenServer.call(via(id), :get)
defp via(id), do: {:via, Registry, {TripSwitch.Registry, id}}
end
