lexigram-resilience

Resilience patterns for the Lexigram Framework (circuit breaker, retry, bulkhead, rate limiting, throttle, fallback)

Overview

lexigram-resilience provides circuit breakers, retry policies, bulkhead isolation, timeouts, rate limiting, throttling, fallback patterns, resilience pipelines, and idempotency key management. All implementations are async-first and designed for high-concurrency workloads. Distributed backends are available for circuit breakers, rate limiters, and idempotency stores when shared state across instances is required.

Full documentation: docs.lexigram.dev

Install

uv add lexigram-resilience
# Optional extras
uv add "lexigram-resilience[idempotency-redis,idempotency-database]"

Quick Start

from lexigram import Application
from lexigram.di.module import Module, module

# Import the module from the package
from lexigram.resilience import ResilienceModule


@module(imports=[ResilienceModule.configure()])
class AppModule(Module):
    pass


async with Application.boot(modules=[AppModule]) as app:
    # use app.container to resolve services
    ...

Configuration

Zero-config usage: Call ResilienceModule.configure() with no arguments to use defaults.

Option 1 — YAML file

# application.yaml
resilience:
  circuit_breaker:
    failure_threshold: 5
    recovery_timeout: 60.0
  retry:
    max_attempts: 3
    base_delay: 1.0
  bulkhead:
    max_concurrent: 10

Option 2 — Profiles + Environment Variables (recommended)

export LEX_RESILIENCE__ENABLED=true
# Environment variables for each field

Option 3 — Python

from lexigram.resilience.config import ResilienceConfig
from lexigram.resilience import ResilienceModule

config = ResilienceConfig(...)
ResilienceModule.configure(config)

Config reference

Module Factory Methods

Key Features

• CircuitBreaker — Opens circuit after repeated failures, prevents cascading failures
• CircuitBreakerRegistry — Named circuit breaker lookup and management
• RetryPolicy — Exponential backoff, jitter, retry on specific exceptions
• Bulkhead — Semaphore-based concurrency limiting with queue support
• TimeoutManager — Async context manager for operation timeouts
• RateLimiter — Token bucket, sliding window, and distributed rate limiting
• Throttler — Request throttling with configurable limits and windows
• ResiliencePipeline — Composable pipeline chaining multiple resilience patterns
• Idempotency subsystem — Idempotency key management with in-memory, database, and Redis backends

Testing

async with Application.boot(modules=[ResilienceModule.stub()]) as app:
    # your test code
    ...

In-memory backends are safe for testing with no external dependencies:

from lexigram.resilience import (
    InMemoryCircuitBreakerBackend,
    InMemoryIdempotencyStore,
)

cb = CircuitBreaker(name="test_cb")  # Uses InMemoryCircuitBreakerBackend
store = InMemoryIdempotencyStore()  # Local-only

Key Source Files