FastAPI¶
The interlock-cb[fastapi] extra protects a route's outgoing dependency with a
shared Registry and turns a tripped breaker into a clean
503 Service Unavailable response with a Retry-After header.
Usage¶
Install the exception handler once, then inject a per-name breaker into any route
with Depends:
from typing import Annotated
from fastapi import Depends, FastAPI
from interlock import CircuitBreaker, Registry
from interlock.integrations.fastapi import breaker_dependency, install_exception_handler
app = FastAPI()
registry = Registry()
install_exception_handler(app)
orders_db = breaker_dependency('orders-db', registry=registry)
@app.get('/orders')
async def orders(breaker: Annotated[CircuitBreaker, Depends(orders_db)]) -> list[dict]:
return await breaker.call(fetch_orders)
When fetch_orders fails often enough, the breaker opens. The next request is
rejected with CircuitOpenError before fetch_orders runs, and the installed
handler converts it into:
HTTP/1.1 503 Service Unavailable
Retry-After: 30
Content-Type: application/json
{"detail": "Circuit 'orders-db' is open"}
How it works¶
breaker_dependency(name, *, registry)returns a FastAPI dependency that yields the named breaker from the sharedRegistry. The breaker is created lazily on first use and reused on every later request, so all requests to that route share one breaker (and one view of the dependency's health).install_exception_handler(app)registers a handler forCircuitOpenError. It responds503and setsRetry-Afterto the breaker'sretry_afterestimate, rounded up to whole seconds (per RFC 7231). The header is omitted when there is no estimate (for example afterforce_open()).
You protect the outgoing call (breaker.call(...)) rather than the route
itself: only the dependency you wrap counts toward the breaker, and the breaker's
own admission logic (probes, half-open) keeps working.
Sharing breakers across routes¶
Reuse the same name (and the same registry) to share one breaker across
several routes that all depend on the same downstream:
orders_db = breaker_dependency('orders-db', registry=registry)
@app.get('/orders')
async def list_orders(breaker: Annotated[CircuitBreaker, Depends(orders_db)]) -> list[dict]:
return await breaker.call(fetch_orders)
@app.get('/orders/{order_id}')
async def get_order(order_id: int, breaker: Annotated[CircuitBreaker, Depends(orders_db)]) -> dict:
return await breaker.call(fetch_order, order_id)
Pass config, clock, classifier or listener to the Registry to tune
every breaker it creates, or override per name via registry.get(name, config=...).
Custom responses¶
For a different response shape, register your own handler instead of
install_exception_handler:
from fastapi import Request, Response
from interlock import CircuitOpenError
@app.exception_handler(CircuitOpenError)
async def on_open(request: Request, exc: CircuitOpenError) -> Response: ...
Testing the lifecycle¶
The breaker reads time only through its Clock, so a test can take a route
through an outage and the recovery after it without sleeping. Give the
Registry a fake clock; every breaker it creates uses it.
from typing import Annotated
from fastapi import Depends, FastAPI
from fastapi.testclient import TestClient
from interlock import CircuitBreaker, Config, Registry, State
from interlock.integrations.fastapi import breaker_dependency, install_exception_handler
class FakeClock:
def __init__(self) -> None:
self.now = 0.0
def monotonic(self) -> float:
return self.now
class OrdersDb:
def __init__(self) -> None:
self.healthy = False
async def fetch_orders(self) -> list[dict]:
if not self.healthy:
raise ConnectionError('orders-db is down')
return [{'id': 1}]
def test__orders_db_outage__opens_then_recovers() -> None:
clock = FakeClock()
db = OrdersDb()
registry = Registry(
config=Config(
minimum_number_of_calls=5,
window_size=5,
wait_duration_in_open=30.0,
permitted_calls_in_half_open=1,
),
clock=clock,
)
app = FastAPI()
install_exception_handler(app)
orders_db = breaker_dependency('orders-db', registry=registry)
@app.get('/orders')
async def orders(breaker: Annotated[CircuitBreaker, Depends(orders_db)]) -> list[dict]:
return await breaker.call(db.fetch_orders)
client = TestClient(app, raise_server_exceptions=False)
for _ in range(5):
assert client.get('/orders').status_code == 500
rejected = client.get('/orders')
assert rejected.status_code == 503
assert rejected.headers['Retry-After'] == '30'
db.healthy = True
clock.now += 30.0
assert client.get('/orders').status_code == 200
assert registry.get('orders-db').state is State.CLOSED
The five failed requests fill the window and trip the breaker. The sixth is
rejected with 503 before fetch_orders runs, and Retry-After carries the
remaining open wait. Once the dependency is back and the clock has passed
wait_duration_in_open, the next request is admitted as a probe. With
permitted_calls_in_half_open=1 that probe is the whole round, so its success
closes the circuit. raise_server_exceptions=False turns the failing requests
into 500 responses instead of exceptions inside the test.
To watch the same lifecycle event by event outside a web framework, run the lifecycle demo.