Tripwire

Tripwire wraps GenServer calls with a circuit breaker, fast-failing requests when a dependency is unhealthy and automatically probing for recovery.

Installation

def deps do
  [
    {:tripwire, "~> 0.1.0"}
  ]
end

Quick start

# In your Application.start/2:
children = [
  {Registry, keys: :unique, name: Tripwire.Breaker.registry()},
  {Task.Supervisor, name: Tripwire.TaskSupervisor},
  {MyApp.Weather, [name: MyApp.Weather]},
  {Tripwire, target_key: :weather, target_pid: MyApp.Weather}
]

# Call through the breaker:
{:ok, :sunny} = Tripwire.call(:weather, :forecast)
{:error, :circuit_open} = Tripwire.call(:weather, :forecast) # after failures

Modules

• Tripwire: the public API for call/3, start_link/1, and child_spec/1.
• Tripwire.Breaker: the per-target GenServer that tracks failures and manages circuit state.
• Tripwire.State: the pure state machine implementing :closed, :open, and :half_open transitions.

Documentation

• Getting started walks through installing Tripwire, wrapping a GenServer, and watching the circuit trip and recover.
• How to protect a GenServer covers adding breakers to a supervision tree, tuning thresholds and timeouts, and handling return values.
• About Tripwire's architecture explains why the three-state model, three-module structure, async forwarding, and BEAM primitive choices exist.
• API reference is generated from the module documentation (@doc / @moduledoc) and published at https://hexdocs.pm/tripwire.

Development

This section explains how to setup the project locally for development.

Dependencies

• Elixir ~> 1.16 (OTP 24+)
  • See Compatibility and deprecations for more information

Get the Source

Clone the project locally:

# via HTTPS
git clone https://github.com/nrednav/tripwire.git

# via SSH
git clone git@github.com:nrednav/tripwire.git

Install

Install the project's dependencies:

cd tripwire/
mix deps.get

Test

Run the test suite:

mix test

Versioning

This project uses Semantic Versioning. For a list of available versions, see the repository tag list.

Issues & Requests

If you encounter a bug or have a feature request, please open an issue on the GitHub repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.