Foundation
Lightweight resilience primitives for Elixir
Foundation provides composable building blocks for resilient Elixir applications: backoff policies, retry loops, rate-limit windows, circuit breakers, semaphores, and telemetry helpers.
The primitives stay generic: for example, circuit breakers support success/failure/ignore outcomes, and Dispatch reacts to externally supplied backoff without assuming any HTTP provider semantics.
Installation
Add foundation to your dependencies in mix.exs:
def deps do
[
{:foundation, "~> 0.2.2"}
]
end
Foundation 0.2+ is a complete rewrite and is not compatible with the 0.1.x series. See the Migration Guide for details.
Quick Start
alias Foundation.{Backoff, Retry}
# Define backoff and retry policies
backoff = Backoff.Policy.new(strategy: :exponential, base_ms: 100, max_ms: 5_000)
policy = Retry.Policy.new(
max_attempts: 5,
backoff: backoff,
retry_on: fn
{:error, :timeout} -> true
{:error, :rate_limited} -> true
_ -> false
end
)
# Run with automatic retries
{result, _state} = Retry.run(fn -> call_api() end, policy)
See the Getting Started guide for a full walkthrough.
Features
| Feature | Module | Guide |
|---|---|---|
| Backoff -- Exponential, linear, and constant strategies with jitter | Foundation.Backoff |
Backoff & Retry |
| Retry -- Configurable retry loops with timeout and progress tracking | Foundation.Retry |
Backoff & Retry |
HTTP Retry -- Status classification and Retry-After parsing |
Foundation.Retry.HTTP |
HTTP Retry |
| Polling -- Long-running workflow polling with backoff and cancellation | Foundation.Poller |
Polling |
| Rate Limiting -- Shared backoff windows for API rate limits | Foundation.RateLimit.BackoffWindow |
Rate Limiting |
| Circuit Breaker -- Protect downstream services with automatic recovery | Foundation.CircuitBreaker |
Circuit Breakers |
| Semaphores -- Counting and weighted semaphores for concurrency control | Foundation.Semaphore.* |
Semaphores |
| Dispatch -- Layered limiter combining concurrency, throttling, and byte budgets | Foundation.Dispatch |
Dispatch |
| Telemetry -- Lightweight helpers with optional reporter integration | Foundation.Telemetry |
Telemetry |
Requirements
- Elixir 1.15+
- OTP 26+
Documentation
Full documentation is available at HexDocs.
License
Foundation is released under the MIT License. See LICENSE for details.