Resilience Patterns

Overview

Lexigram provides composable fault-tolerance primitives: retry, circuit breaker, bulkhead, rate limiter, and timeout. Patterns compose into a ResiliencePipeline.

Decorators

All decorators take config objects, not raw keyword arguments. Decorators apply bottom-up — write the stack so the closest decorator to the function runs first:

from lexigram.resilience import retry, circuit_breaker, bulkhead, with_timeout
from lexigram.resilience import RetryConfig, CircuitBreakerConfig, BulkheadConfig, TimeoutConfig, CircuitBreakerRegistry

@with_timeout(TimeoutConfig(timeout=30.0))                                              # 4th: outermost deadline
@retry(RetryConfig(max_attempts=3, base_delay=1.0, backoff_factor=2.0))                 # 3rd: retry inside CB
@circuit_breaker("external-api", registry=CircuitBreakerRegistry(), config=CircuitBreakerConfig(failure_threshold=5, recovery_timeout=30))  # 2nd: fail fast
@bulkhead(BulkheadConfig(max_concurrent=10, queue_size=20))                             # 1st: limit concurrency
async def call_external_api(payload: dict) -> Result[Response, DomainError]:
    return await self.client.post(payload)

Programmatic API

from lexigram.resilience import (
    RetryConfig, CircuitBreaker, RetryPolicy,
    CircuitBreakerConfig, CircuitBreakerRegistry,
    ResiliencePipeline, TimeoutConfig,
)

# Retry
config = RetryConfig(max_attempts=3, base_delay=1.0, backoff_factor=2.0, jitter=True)
policy = RetryPolicy(config)
result = await policy.execute(lambda: fetch_data())

# Circuit breaker — use protect() as context manager
cb = CircuitBreaker(CircuitBreakerConfig(failure_threshold=5, recovery_timeout=30.0))
async with cb.protect():
    result = await call_service()

# Resilience pipeline
from lexigram.resilience import ResiliencePipeline

pipeline = ResiliencePipeline(
    retry_config=RetryConfig(max_attempts=3),
    circuit_config=CircuitBreakerConfig(failure_threshold=5, recovery_timeout=30),
    timeout_config=TimeoutConfig(timeout=15.0),
)
result = await pipeline.execute(fetch_data)

Composition Order

Request → Bulkhead → Circuit Breaker → Retry → Timeout → Service

Quick Reference

Config

resilience:
  retry:
    max_attempts: 3
    base_delay: 1.0
    backoff_factor: 2.0
    jitter: true
  circuit_breaker:
    failure_threshold: 5
    recovery_timeout: 30.0

Common Mistakes

• Retrying non-idempotent operations — can cause duplicate charges/actions
• Placing retry outside circuit breaker — retries keep hammering a dead service
• No jitter on retry delay — thundering herd on recovery
• Sync functions: use circuit_breaker_sync — the other decorators auto-detect sync/async
• Missing fallback — user gets 500 instead of a degraded response