tripwire

# Tripwire

[![Hex.pm](https://img.shields.io/hexpm/v/tripwire.svg)](https://hex.pm/packages/tripwire)

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

## Installation

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

## Quick start

```elixir
# 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](guides/tutorials/getting-started.md) walks through
  installing Tripwire, wrapping a GenServer, and watching the circuit trip and
  recover.
- [How to protect a GenServer](guides/how-to/protect-a-genserver.md) covers
  adding breakers to a supervision tree, tuning thresholds and timeouts, and
  handling return values.
- [About Tripwire's architecture](guides/explanation/architecture.md) 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](https://hexdocs.pm/elixir/1.20.2/compatibility-and-deprecations.html)
    for more information

### Get the Source

Clone the project locally:

```bash
# 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:

```bash
cd tripwire/
mix deps.get
```

### Test

Run the test suite:

```bash
mix test
```

## Versioning

This project uses [Semantic Versioning](https://semver.org/). For a list of
available versions, see the [repository tag
list](https://github.com/nrednav/tripwire/tags).

## Issues & Requests

If you encounter a bug or have a feature request, please [open an
issue](https://github.com/nrednav/tripwire/issues) on the GitHub repository.

## License

This project is licensed under the MIT License - see the [LICENSE](./LICENSE)
file for details.