fastapi-loopguard 0.6.0

Catch event-loop blocking in FastAPI and see which requests were in flight.

When something blocks your event loop (via time.sleep(), blocking I/O, or CPU work), LoopGuard detects it and narrows it down to the requests that were in flight when the loop stalled. The sentinel measures loop lag, so it cannot name the single guilty handler — it reports every request that was active during the stall.

Install

pip install fastapi-loopguard

Quick Start

from fastapi import FastAPI
from fastapi_loopguard import LoopGuardMiddleware

app = FastAPI()
app.add_middleware(LoopGuardMiddleware)

Enforcement Modes

from fastapi_loopguard import LoopGuardConfig

# Development: diagnostic headers on every response
config = LoopGuardConfig(dev_mode=True)

# Development / CI: fail loudly with an educational 503
config = LoopGuardConfig(enforcement_mode="strict")

# Production: silent logging
config = LoopGuardConfig(enforcement_mode="log")

app.add_middleware(LoopGuardMiddleware, config=config)

What You Get

Strict Mode

Returns an educational 503 page that explains what went wrong and how to fix it:

Warn Mode

Adds diagnostic headers to every response for debugging:

Log Mode

Writes structured logs listing the requests that were in flight:

Testing AI-Generated Code

AI agents write plausible async code that quietly blocks the event loop. The bundled pytest plugin turns that into a red test and a machine-readable report the agent can fix from — no per-test annotations:

# pytest.ini
[pytest]
loopguard_all_async = true          # every async test fails on blocking
loopguard_report = loopguard.json   # verdicts + fix hints for the agent

See docs/AI-HARNESS.md for the report schema, the no_blocking / allow_blocking markers, and a drop-in snippet for your project's agent instructions.

Full Configuration Reference