Foundation

Foundation logo

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.1"}
  ]
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.