Skip to content

Resilience

ResilientAsyncHttpClient wraps httpx.AsyncClient with a per-key circuit breaker (purgatory), retry with Retry-After awareness (stamina), and a rate limiter clamped from response headers — the resilience extra.

from rn_forge.commons.integration.resilience import ResilientAsyncHttpClient

async with ResilientAsyncHttpClient("https://api.example.com", name="example-api") as client:
    response = await client.get("/widgets")

Per-key breakers

Pass key= to request/get/post/... to protect several independent upstreams (e.g. one breaker per tenant or per upstream organisation) from one client instance — each key gets its own circuit, tripped independently:

await client.get("/widgets", key=f"tenant-{tenant_id}")

Only failures that say something about the upstream count toward fail_max: connection errors, timeouts and the transient statuses (429, 500, 502, 503, 504). A 404 or 422 is raised to the caller but never opens the circuit.

The metrics seam

on_state_change(key, old_state, new_state) is called on every circuit transition. It defaults to an AppLogger warning — wire it to your own metrics backend rather than expecting this module to import OpenTelemetry:

ResilientAsyncHttpClient(
    "https://api.example.com",
    name="example-api",
    on_state_change=lambda key, old, new: my_metrics.increment("circuitbreaker_state", tags=[key, new]),
)

Testable timing

The rate limiter's clock/sleep are constructor-injectable, so a test can run on a fake clock instead of real wall time. X-RateLimit-Reset is read as a Unix epoch timestamp, so clock is a wall clock (default time.time), not a monotonic one:

client = ResilientAsyncHttpClient(
    "https://api.example.com",
    name="example-api",
    clock=fake_clock,
    sleep=fake_sleep,
)

Escape hatch

client.client is the underlying httpx.AsyncClient, for anything this facade doesn't cover.