fastapi-loopguard 0.4.1__tar.gz → 0.6.0__tar.gz

{fastapi_loopguard-0.4.1 → fastapi_loopguard-0.6.0}/.github/workflows/ci.yml

@@ -41,7 +41,7 @@ jobs:
           coverage xml
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v7
         if: matrix.python-version == '3.12'
         with:
           files: ./coverage.xml

fastapi_loopguard-0.6.0/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+## 0.6.0 (2026-08-12)
+
+Detection-core hardening plus the AI test harness. Fixes found by a
+line-by-line audit of the detection path; every item below changes
+observable behavior.
+
+- The adaptive threshold can no longer ratchet itself blind. Recalculation
+  is clamped to the `fallback_threshold_ms` ceiling; previously each raise
+  widened the censor gate that admits the next round of samples, compounding
+  50 -> 241 -> 573ms within seconds on merely-noisy traffic.
+- Cumulative detection no longer counts timer jitter. The window now sums
+  baseline-corrected excess lag (`max(0, lag - baseline)`); raw per-tick
+  platform jitter (~2ms idle on macOS) alone could previously cross the
+  200ms default within one 1000ms window on a completely idle loop.
+- Lazy stop/start race fixed: a request arriving while the monitor was
+  stopping (last request just finished) used to observe stale lifecycle
+  flags and run unmonitored. Flags are now cleared before the stop awaits,
+  so a mid-stop request starts a fresh monitor.
+- `stop()` no longer swallows a cancellation aimed at the calling task.
+  It runs inside request `finally` blocks; the old
+  `suppress(CancelledError)` turned client disconnects and server shutdown
+  into requests that ignored their own cancellation.
+- `stop()` issued during a blocking `start()` calibration now vetoes the
+  loop start instead of being a silent no-op.
+- A lifespan app that raises no longer leaks the monitor tasks.
+- One blocking event now logs exactly one summary line instead of one line
+  per in-flight request (O(N) log formatting on the loop thread right after
+  a stall). The per-context `on_blocking` callback contract is unchanged.
+- New config validation: `fallback_threshold_ms >= monitor_interval_ms`,
+  `adaptive_update_interval_ms >= monitor_interval_ms`, and `exclude_paths`
+  may not be a bare string (it would silently become a substring match).
+- Strict mode's clean-path headers are now computed from the request
+  context instead of hardcoded zero literals.
+- Calibration clamps a negative raw baseline (timers may fire up to
+  clock_resolution early) to 0.
+
+AI test harness (pytest plugin):
+
+- New `loopguard_all_async` mode (ini or `--loopguard-all-async`): every
+  async test is treated as `@pytest.mark.no_blocking`, with a new
+  `@pytest.mark.allow_blocking` opt-out marker. Built for gating
+  AI-generated code without per-test annotations.
+- New `loopguard_report` option (ini or `--loopguard-report=PATH`): writes
+  a JSON verdict file at session end with per-test blocking events and
+  concrete sync->async fix hints. See `docs/AI-HARNESS.md`.
+- The detector is now armed before the test body runs. A test that blocked
+  before its first real await (an ASGI request dispatch does exactly that)
+  was previously invisible to the gate.
+- BREAKING: the `loopguard_detector` fixture was removed. It yielded a
+  detector that was never started, so assertions on its (always empty)
+  `blocking_events` passed unconditionally.
+- `@pytest.mark.no_blocking` on a synchronous test now emits a warning
+  instead of silently doing nothing.
+- The plugin no longer calls `asyncio.iscoroutinefunction` (deprecated on
+  Python 3.14), so downstream suites running `-W error` stay green.
+- `BlockingDetector.stop()` no longer swallows the test's own cancellation.
+
+Also:
+
+- New `evals/` directory: a starter benchmark (5 FastAPI tasks + runner)
+  scoring whether an AI model writes non-blocking async code.
+- `configure_logging()` is idempotent and disables propagation;
+  `StructuredFormatter` preserves `exc_info` tracebacks.
+- `prometheus-client` joined the `dev` extra so the metrics tests run in CI.
+
+## 0.5.0 (2026-08-11)
+
+Correctness release. Every fix below changes externally observable behavior.
+
+- `dev_mode` no longer turns blocking into 503s. Previously, one endpoint's
+  sync block made every concurrent innocent request fail with 503 while the
+  actual culprit returned 200. `dev_mode` now only adds diagnostic headers;
+  a 503 requires explicitly setting `enforcement_mode="strict"`. Docs no
+  longer claim the library identifies which endpoint caused blocking — it
+  reports the requests that were in flight during the stall.
+- A single blocking event is reported once, not twice. A 300ms block used to
+  produce two events summing to ~600ms in headers and logs (single-shot plus
+  a cumulative re-count of the same sample). Cumulative window sums are now
+  recorded separately from individual lag samples.
+- Calibration can no longer be poisoned by the app's own blocking. Background
+  calibration during a busy blocking startup used to raise the detection
+  threshold to ~8x the fallback, after which real blocking went undetected.
+  A calibrated threshold now only ever tightens the fallback.
+- The adaptive threshold no longer chases sustained blocking. ~120 blocks of
+  ~70ms used to yield ~9 detections and a final threshold near 380ms;
+  detection now keeps firing for the whole run.
+- Adaptive mode no longer discards a calibration-tightened threshold. Its
+  floor used to be pinned at the fallback and its first update fired
+  immediately, snapping a calibrated 10ms threshold back to 50ms on the
+  first tick. The floor now follows the calibrated threshold.
+- Responses using ASGI extension messages no longer hang in strict mode:
+  `http.response.pathsend` (Starlette `FileResponse` on Hypercorn/Granian),
+  `http.response.trailers`, and unknown message types now pass through.
+- `"trailers": True` and any other key on `http.response.start` survive
+  header injection instead of being silently dropped.
+- The monitor no longer leaks background tasks when startup fails
+  (`lifespan.startup.failed` / `lifespan.shutdown.failed` now stop it), and a
+  lazily started monitor (apps without lifespan, e.g. tests using
+  `httpx.ASGITransport`) stops when the last in-flight request finishes.
+- `__version__` now matches the installed package metadata (it was hard-coded
+  to 0.3.0 while the package shipped as 0.4.1), and the 503 error page links
+  to the real repository.

fastapi_loopguard-0.6.0/CLAUDE.md

@@ -0,0 +1,109 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+fastapi-loopguard — a middleware library that detects event-loop blocking in FastAPI/Starlette apps with per-request attribution. When synchronous code (`time.sleep`, blocking I/O, CPU-bound work) freezes the async event loop, LoopGuard reports which requests were in flight and, depending on enforcement mode, warns, logs, or fails the response with an educational 503.
+
+**Division of docs — do not duplicate them here.** `README.md` owns the pitch, install, and quick-start snippet. `docs/CONFIGURATION.md` is the authoritative reference for every `LoopGuardConfig` option and the recommended recipes; add new options there. This file owns architecture, invariants, and workflow.
+
+There is no CONTRIBUTING.md. Release history lives in `CHANGELOG.md` (since 0.5.0) and in git tags (`v0.3.0` …).
+
+## Quick Start
+
+```bash
+pip install -e ".[dev]"                  # dev deps: pytest, mypy, ruff, coverage, httpx, fastapi
+pytest                                   # full suite (asyncio_mode=auto, testpaths=tests)
+pytest tests/test_middleware.py::TestLoopGuardMiddleware::test_dev_mode_headers   # one test
+mypy src/                                # strict mode, src/ only
+ruff check src/ tests/                   # lint — CI runs this exact scope
+ruff format --check src/ tests/          # CI verifies formatting; drop --check to rewrite
+coverage run -m pytest tests/ && coverage report --fail-under=80   # the CI gate
+
+pip install -e ".[stress]"               # everything under examples/ needs uvicorn + locust
+python examples/demo_app.py              # demo on :8765 — /api/users returns 503 (strict mode)
+python examples/stress_app.py            # stress target on :8000
+python examples/run_stress_test.py --skip-locust   # validation suite against a running :8000
+```
+
+CI lints and type-checks `src/` and `tests/` only — `examples/` is unchecked and does not satisfy the `ANN` rules the rest of the tree does. `tests/test_metrics.py` skips entirely unless `.[prometheus]` is installed, which is why `metrics.py` reports 0% coverage on a plain `.[dev]` run; the 80% gate still passes at ~88% overall.
+
+## Tech Stack (versions verified 2026-08-11)
+
+- Python `>=3.12`; CI matrix is 3.12 and 3.13. mypy is pinned to `python_version = "3.12"` with `strict = true`.
+- **One runtime dependency: `starlette>=0.37.0,<1.0`.** FastAPI is a *dev* dependency — the middleware is pure ASGI and must never import `fastapi` from `src/`. Adding any runtime dependency requires asking first.
+- Extras: `prometheus` (prometheus-client), `structlog`, `all`, `dev`, `stress` (locust + uvicorn). The `structlog` extra is currently declared but unused — nothing imports structlog.
+- ruff selects `["E","F","I","N","W","UP","B","C4","SIM","ANN"]`, ignoring only `ANN401`. **`ANN` means every function needs full annotations**, tests and fixtures included. Line length 88, double quotes.
+- Build backend is hatchling; wheel packages `src/fastapi_loopguard`. Publishing triggers on a `v*` tag via PyPI trusted publishing (OIDC) — there is **no version-bump automation**, so `pyproject.toml` must be bumped by hand. `__init__.__version__` is derived from installed package metadata; after bumping, re-run `pip install -e .` or the version tests fail against stale metadata.
+- `.claude/` is git-ignored and excluded from the sdist. Committing anything there needs an explicit `.gitignore` negation.
+
+## Architecture
+
+```
+src/fastapi_loopguard/
+  config.py         LoopGuardConfig — frozen slotted dataclass + __post_init__ validation
+  context.py        RequestContext, RequestRegistry, module-global _registry, free functions
+  monitor.py        SentinelMonitor sleep-measure loop, AdaptiveThreshold
+  middleware.py     pure-ASGI LoopGuardMiddleware, enforcement modes, HTML/JSON error pages
+  logging.py        StructuredFormatter (JSON), configure_logging, log_blocking_event
+  metrics.py        optional Prometheus LoopGuardMetrics (see Known Gaps — not wired in)
+  pytest_plugin.py  pytest11 entry point, @pytest.mark.no_blocking, BlockingDetector
+```
+
+**Layering (strict — a module imports only lower layers):** `config`, `context` → `monitor` → `middleware`. `logging`, `metrics`, and `pytest_plugin` are leaves; nothing on the detection path imports them, and they must not import `middleware`. `middleware.py` imports `LoopGuardConfig` inside `__init__` with an "avoid circular imports" comment — the cycle no longer exists, but the deferred import is harmless and not worth churning.
+
+`pytest_plugin.py` is registered as a `pytest11` entry point, so it auto-loads for **every** project that installs this package. Treat its hooks as public API and keep them cheap and side-effect-free for unmarked tests.
+
+**Detection flow:** ASGI `lifespan.startup` starts the monitor → `_handle_http` skips `exclude_paths`, then registers a `RequestContext` and writes the id to `scope["state"]["loopguard_request_id"]` → `_monitor_loop` sleeps `monitor_interval_ms` and computes `lag_ms = (elapsed - interval) * 1000` → lag over threshold calls `_handle_blocking`, which calls `record_blocking` on every active context → the send wrapper reads `ctx.blocking_count` / `ctx.total_blocking_ms` and emits headers or a 503 → `finally` unregisters (and stops a lazily started monitor once the registry empties) → any terminal lifespan message (`shutdown.complete`, `shutdown.failed`, `startup.failed`) stops the monitor.
+
+## Detection Invariants (non-negotiable)
+
+1. **Pure ASGI — never `BaseHTTPMiddleware`.** It is deprecated, breaks contextvars, and leaks memory. `__call__` dispatches on `scope["type"]`; WebSocket and every other type pass through untouched, with no context registered.
+2. **Blocking attributes to ALL active requests.** The sentinel measures loop lag, not call stacks, so it cannot know which request blocked. `_handle_blocking` iterates every context from `get_active_requests()` and records the same lag on each. This over-reports under concurrency **by design** — narrowing it is a redesign, not a bug fix.
+3. **The registry needs no locks.** asyncio is single-threaded, so `RequestRegistry` is a plain dict keyed by `request_id`. Never add a lock, a `threading` primitive, or thread-safety without first changing that premise and saying so.
+4. **Calibration never blocks the first request, and can only tighten.** `start_with_background_calibration()` starts `_monitor_loop` immediately on `fallback_threshold_ms` and calibrates in a named background task. Baseline is the **minimum** of `calibration_iterations` samples (the idle floor — robust to contamination from live traffic), and the calibrated threshold is clamped to `[monitor_interval_ms, fallback_threshold_ms]`: it may lower the fallback, never raise it. The adaptive window is censored (only sub-threshold samples admitted), its floor follows the calibrated threshold, and its recalculated value is clamped to the `fallback_threshold_ms` ceiling — without the ceiling each raise widens the censor gate and the threshold ratchets upward unboundedly. So neither calibration nor adaptation can be poisoned upward by the app's own blocking or its noise. A failed or cancelled calibration keeps the fallback threshold and must never raise into startup. Config guarantees `fallback_threshold_ms >= monitor_interval_ms`, so the clamp can never invert.
+5. **Unregister always runs.** `_handle_http` wraps dispatch in `try/finally: unregister_request(request_id)`. An exception from the wrapped app must never leak a context into the registry — a leak makes every later blocking event attribute to a dead request forever.
+6. **`dev_mode` is headers-only; a 503 requires explicit strict mode.** `_get_effective_enforcement_mode()` always returns `enforcement_mode` — `dev_mode` never changes it. Because blocking is attributed to ALL in-flight requests (invariant 2), a status change punishes innocent bystanders, so it must stay opt-in via `enforcement_mode="strict"`. No text anywhere may claim the library identifies WHICH endpoint blocked — it narrows it to the requests in flight during the stall.
+7. **One blocking event is reported exactly once.** A sample that fires the single-shot detection is never appended to `_lag_history`, within one `_monitor_loop` iteration a single-lag trigger suppresses the cumulative one, and `_lag_history` is cleared after a cumulative fire so a window reports at most once. The window stores **baseline-corrected excess lag** (`max(0, lag - baseline)`), never raw lag — raw per-tick timer jitter alone would sum past the default cumulative threshold on an idle loop. Cumulative window sums are recorded in `RequestContext.cumulative_events`, separate from the individual-lag `blocking_events` list; `blocking_count` / `total_blocking_ms` sum both. One event also emits exactly **one log line** (a summary across in-flight requests), never one line per context — no O(N) work on the loop thread right after a stall.
+8. **Lifecycle calls are idempotent, race-free, and cancellation-safe; lazy monitors stop when idle.** `start()`, `start_with_background_calibration()`, and `stop()` all return early when already in the target state. `start()` marks `_running` **before** its blocking calibration so a concurrent `stop()` vetoes the loop start. `_stop_monitor` clears `_started`/`_lazy_started`/`_monitor` **before** awaiting the monitor's stop — that await yields, and a request arriving mid-stop must see `_started=False` and start a fresh monitor rather than run unmonitored. `stop()` awaits cancelled tasks via `_cancel_and_wait`, which re-raises when the *calling* task has a pending cancellation (it runs inside request `finally` blocks; a bare `suppress(CancelledError)` would make requests ignore their own cancellation). A lifespan app that raises gets the monitor stopped in the `except` path, not leaked. `_handle_http` lazily starts the monitor for apps that run without ASGI lifespan and stops it when the last in-flight request unregisters (so `httpx.ASGITransport` tests leak no tasks); lifespan-managed monitors persist between requests. Double-start must stay a no-op. Consequence: in lazy mode background calibration rarely completes and the fallback threshold governs.
+
+## Conventions
+
+- **`LoopGuardConfig` is frozen — never mutate it, construct a new one.** All validation lives in `__post_init__` and raises `ValueError` with a message naming the field.
+- Every new config option needs three things: a validation rule in `__post_init__`, a case in `TestLoopGuardConfig`, and a row in `docs/CONFIGURATION.md`. Missing any one of them is an incomplete change.
+- **Response headers are lowercase bytes.** Pass-through responses carry `x-request-id`, `x-blocking-count`, `x-blocking-total-ms`, and `x-blocking-detected`, plus `x-loopguard-warning: blocking-detected` in warn mode. The strict 503 built by `_send_strict_error` carries `x-loopguard-enforcement: strict` and **omits `x-blocking-detected`** — a separate header set, not an extension of the first.
+- `request_id` is the first 8 characters of a `uuid4` — short enough to read in a terminal, not a security token.
+- **All internal timing uses `loop.time()` or `time.monotonic()`** — never `datetime` or wall-clock, which jump under NTP.
+- Hot-path classes use `__slots__`: `LoopGuardConfig`, `RequestContext`, `RequestRegistry`, `SentinelMonitor`, `AdaptiveThreshold`, `LoopGuardMiddleware`. Adding an attribute means adding it to `__slots__`, and `test_context.py` asserts the absence of `__dict__`.
+- Logger name is `"fastapi_loopguard"`, shared by `monitor.py` and `logging.py`. `monitor.py` logs inline with `%`-style lazy formatting; `logging.log_blocking_event()` is a helper for library *users* and is intentionally not called internally.
+- `exclude_paths` is checked before anything else in `_handle_http`, so health checks cost nothing.
+- Backward-compat shims are public API and stay: `get_current_request`, `set_current_request`, `reset_current_request`, `init_metrics`. `get_current_request` returns an arbitrary active context and is only correct for single-request cases — new code uses `get_active_requests()`.
+- `logging`, `metrics`, and `pytest_plugin` are **not** re-exported from `__init__.py`; import them by module path.
+
+## Testing
+
+- Definition of done: `pytest` green, `mypy src/` clean, `ruff check src/ tests/` and `ruff format --check src/ tests/` clean, and coverage at or above **80** (`--fail-under=80` is the CI gate).
+- **There is no `conftest.py`.** The `clear_registry` fixture is duplicated per file, roughly 15 times. Match the local pattern in the file you are editing; introducing a shared conftest is its own change, not a side effect of an unrelated one.
+- Blocking is simulated with `time.sleep(...)` followed by a short `await asyncio.sleep(...)` — the second call is what lets the sentinel observe the lag while the context is still registered. Omitting it makes the test pass for the wrong reason.
+- HTTP tests use `httpx.AsyncClient(transport=ASGITransport(app=app))`. Plugin tests use the `pytester` fixture to run generated test files in-process.
+- Each invariant has dedicated coverage: `test_enforcement_mode.py` for modes and dev-mode escalation, `test_monitor.py` for calibration, idempotency, and task cancellation, `test_cumulative_blocking.py` for the window, `test_context.py` for registry lifecycle and `__slots__`, `test_pytest_plugin.py` for the marker.
+- Timing tests are inherently flaky under load. Prefer driving `SentinelMonitor` directly with an `on_blocking` callback (as `test_cumulative_blocking.py` does) over asserting on wall-clock durations.
+
+## Known Gaps (accurate as of 2026-08-11)
+
+Recorded so they are not rediscovered. None are fixed yet; fixing any of them is its own task. The fuller list, including design tensions deferred from the 0.5 correctness pass, is `FINDINGS.md`.
+
+1. **`prometheus_enabled` is inert.** Neither `middleware.py` nor `monitor.py` imports `metrics.py`, so enabling the flag exposes nothing. Wiring it up means calling `record_blocking` / `record_request` / `set_threshold` from the monitor.
+2. **`docs/CONFIGURATION.md` names metrics that do not exist.** It lists `loopguard_blocking_events_total` and `loopguard_blocking_duration_ms`; the real names are `loopguard_blocking_total`, `loopguard_lag_seconds`, `loopguard_requests_monitored_total`, and `loopguard_threshold_seconds`.
+3. **`get_metrics()` can never find an instance.** It reads `_instances[prefix]` while `create_metrics` writes `f"{prefix}:{id(registry)}"`. `tests/test_metrics.py:188` documents the mismatch in a comment instead of failing on it.
+4. **`_generate_warning_banner()` is dead code** — defined in `middleware.py`, never called.
+
+## Fundamental Guidelines
+
+*(Distilled from [andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills))*
+
+- **Think first.** Surface assumptions and tradeoffs; if a request is ambiguous or a simpler approach exists, say so before coding — don't pick silently.
+- **Simplicity first.** Minimum code that solves the problem. No speculative features, abstractions, config, or error handling for impossible cases.
+- **Surgical changes.** Touch only what the task requires. Match existing style, don't refactor working code, remove only orphans your own change created.
+- **Goal-driven.** Turn tasks into verifiable goals (e.g. "fix bug" → "write a failing test, make it pass"); state a brief plan for multi-step work.

fastapi_loopguard-0.6.0/FINDINGS.md

@@ -0,0 +1,105 @@
+# Findings not fixed in the 0.5/0.6 passes
+
+Everything noticed while fixing the 0.5 correctness defects (and the 0.6
+hardening pass) but deliberately left alone. Each item is its own future task.
+
+## Detection design
+
+1. ~~**Sub-threshold noise can still inflate the adaptive threshold.**~~
+   **Fixed in the 0.6 pass:** the adaptive threshold is now clamped to the
+   `fallback_threshold_ms` ceiling, closing both the one-step inflation and
+   the compounding ratchet (each raise widened the censor gate). Median+MAD
+   over the censored window remains a possible refinement below the ceiling.
+
+2. **Strict mode cannot fail a response after `http.response.start` has passed.**
+   If blocking is first detected mid-stream, the 200 and its headers are
+   already on the wire and the body keeps streaming; the response then claims
+   no blocking. Inherent to header-based reporting. Documented by test
+   (`test_enforcement_mode.py::TestStrictModeStreaming`). Related accepted
+   behavior, also documented by test: if the app raises after strict mode
+   swallowed its `http.response.start`, the exception wins — the client gets
+   the server's 500, not LoopGuard's 503.
+
+3. **Explicit strict mode still 503s all in-flight requests.**
+   The sentinel cannot name the culprit, so strict mode punishes bystanders
+   under concurrency. Now opt-in and documented, but the real per-callback
+   attribution rewrite (the 0.5+ plan) is what removes this.
+
+4. **Lazy mode (no ASGI lifespan) rarely completes calibration.**
+   The stop-when-idle lifecycle cancels background calibration when the last
+   request finishes, so lifespan-less deployments run on the fallback
+   threshold and have no between-request monitoring. Accepted tradeoff for
+   not leaking tasks; worth a README note if such deployments matter.
+
+## ASGI / architecture
+
+5. **`exclude_paths` matches the raw `scope["path"]`.**
+   Breaks under `root_path` and `Mount`, and `/health/live` is not excluded by
+   `/health`. Prefix or route-template matching would fix it.
+
+6. **Module-global `RequestRegistry` breaks with two apps in one process.**
+   A mounted sub-app or a second middleware-wrapped app cross-attributes
+   blocking between apps. Keying state per middleware instance (or per loop)
+   would fix it.
+
+7. **The package could be zero-dependency.**
+   `middleware.py` imports only type aliases from `starlette.types`; moving
+   that import under `TYPE_CHECKING` removes the runtime dependency entirely
+   (works on Litestar, Quart, Django ASGI, ...). Also, the `<1.0` upper bound
+   on starlette will block installs the day Starlette 1.0 ships.
+
+8. **`get_current_request()` returns an arbitrary active context.**
+   A backward-compat shim that silently gives wrong answers under concurrency.
+   Pre-1.0 with few users, removal is cheaper than the confusion.
+
+## Dead / inert code and docs drift
+
+9. **`prometheus_enabled` is inert** (known gap #1): nothing on the detection
+   path imports `metrics.py`. Out of scope here (`metrics.py` untouchable).
+
+10. **`_generate_warning_banner()` is dead code** (known gap #4).
+
+11. **`docs/CONFIGURATION.md` names metrics that do not exist** (known gap #2)
+    and `get_metrics()` can never find an instance (known gap #3).
+
+12. ~~**`docs/CONFIGURATION.md` describes `fallback_threshold_ms` as "Used if
+    calibration is unreliable"**~~ — fixed in the 0.6 pass; the docs now
+    describe it as the hard ceiling.
+
+13. ~~**`_handle_lifespan` locals `started` / `shutdown_complete` are
+    write-only.**~~ — removed in the 0.6 pass.
+
+14. **The `structlog` extra is declared but nothing imports structlog**
+    (already noted in CLAUDE.md).
+
+## Repro caveat worth keeping
+
+15. **Calibration poisoning (defect 2) required blocking to span the whole
+    calibration window.** With idle gaps, clean tail samples dominated and the
+    old `max(..., fallback)` floor masked the bug. The fix removes the
+    mechanism either way, but tests that "prove" poisoning need dense blocking.
+
+## Accepted in the 0.6 hardening pass (documented, not fixed)
+
+16. **Installing the middleware twice injects duplicate `x-*` headers.**
+    Nothing marks a scope as already instrumented; two instances register two
+    contexts per request and both send wrappers extend the headers. Low
+    priority — a doubled middleware is a user configuration error.
+
+17. **`Accept` negotiation is a bare substring test with last-header-wins.**
+    Duplicate `Accept` headers collapse via `dict()`, and q-values are
+    ignored, so `text/html;q=0.1, application/json;q=0.9` still gets the HTML
+    page. Cosmetic: only chooses the error-page format.
+
+18. **8-hex-char request ids (32 bits) can collide silently.** A collision
+    overwrites the registry entry and the first unregister removes the second
+    request's context. Birthday bound is ~77k concurrent in-flight requests;
+    accepted as unrealistic, noted here so it is a known trade.
+
+## Fixed since the first draft
+
+- Adaptive mode discarding the calibrated threshold (floor pinned at the
+  fallback, first update firing immediately) — fixed on this branch; the
+  adaptive floor now follows the calibrated threshold.
+- CLAUDE.md invariants 4 and 6 and known gaps 1-2 describing pre-0.5
+  behavior — CLAUDE.md updated on this branch.

{fastapi_loopguard-0.4.1 → fastapi_loopguard-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: fastapi-loopguard
-Version: 0.4.1
+Version: 0.6.0
 Summary: Detect event-loop blocking in FastAPI/Starlette with per-request attribution
 Project-URL: Homepage, https://github.com/parhamdavari/fastapi-loopguard
 Project-URL: Documentation, https://github.com/parhamdavari/fastapi-loopguard#readme
@@ -22,7 +22,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Monitoring
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
-Requires-Dist: starlette<1.0,>=0.37.0
+Requires-Dist: starlette<2.0,>=0.37.0
 Provides-Extra: all
 Requires-Dist: prometheus-client>=0.19.0; extra == 'all'
 Requires-Dist: structlog>=24.1.0; extra == 'all'
@@ -31,6 +31,7 @@ Requires-Dist: coverage>=7.4.0; extra == 'dev'
 Requires-Dist: fastapi>=0.110.0; extra == 'dev'
 Requires-Dist: httpx>=0.27.0; extra == 'dev'
 Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: prometheus-client>=0.19.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.3.0; extra == 'dev'
@@ -48,7 +49,7 @@ Description-Content-Type: text/markdown
 </p>
 
 <p align="center">
-  <strong>Catch event-loop blocking in FastAPI with per-request attribution.</strong>
+  <strong>Catch event-loop blocking in FastAPI and see which requests were in flight.</strong>
 </p>
 
 <p align="center">
@@ -57,9 +58,13 @@ Description-Content-Type: text/markdown
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
 </p>
 
+<p align="center">
+  <img src="assets/demo.gif" alt="LoopGuard demo: a fast endpoint passes, a blocking endpoint fails with a 503, and the console banner explains why" width="800" />
+</p>
+
 ---
 
-When a request blocks your event loop (via `time.sleep()`, blocking I/O, or CPU work), LoopGuard detects it **and tells you which endpoint caused it**.
+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
 
@@ -88,9 +93,12 @@ app.add_middleware(LoopGuardMiddleware)
 ```python
 from fastapi_loopguard import LoopGuardConfig
 
-# Development: strict enforcement (503 on blocking)
+# 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")
 
@@ -103,7 +111,7 @@ app.add_middleware(LoopGuardMiddleware, config=config)
 Returns an educational 503 page that explains what went wrong and how to fix it:
 
 <p align="center">
-  <img src="assets/error-page-screenshot.png" alt="Strict mode error page" width="600" />
+  <img src="assets/error-page.gif" alt="Strict mode error page" width="600" />
 </p>
 
 ---
@@ -118,7 +126,7 @@ Adds diagnostic headers to every response for debugging:
 ---
 
 ### Log Mode
-Writes structured logs with full request attribution:
+Writes structured logs listing the requests that were in flight:
 
 <p align="center">
   <img src="assets/error-page-screenshot-console.png" alt="Console output" width="600" />
@@ -126,6 +134,21 @@ Writes structured logs with full request attribution:
 
 ---
 
+## 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:
+
+```ini
+# 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](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.
+
+---
+
 <p align="center">
   <a href="docs/CONFIGURATION.md"><strong>Full Configuration Reference</strong></a>
 </p>

{fastapi_loopguard-0.4.1 → fastapi_loopguard-0.6.0}/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <strong>Catch event-loop blocking in FastAPI with per-request attribution.</strong>
+  <strong>Catch event-loop blocking in FastAPI and see which requests were in flight.</strong>
 </p>
 
 <p align="center">
@@ -12,9 +12,13 @@
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
 </p>
 
+<p align="center">
+  <img src="assets/demo.gif" alt="LoopGuard demo: a fast endpoint passes, a blocking endpoint fails with a 503, and the console banner explains why" width="800" />
+</p>
+
 ---
 
-When a request blocks your event loop (via `time.sleep()`, blocking I/O, or CPU work), LoopGuard detects it **and tells you which endpoint caused it**.
+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
 
@@ -43,9 +47,12 @@ app.add_middleware(LoopGuardMiddleware)
 ```python
 from fastapi_loopguard import LoopGuardConfig
 
-# Development: strict enforcement (503 on blocking)
+# 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")
 
@@ -58,7 +65,7 @@ app.add_middleware(LoopGuardMiddleware, config=config)
 Returns an educational 503 page that explains what went wrong and how to fix it:
 
 <p align="center">
-  <img src="assets/error-page-screenshot.png" alt="Strict mode error page" width="600" />
+  <img src="assets/error-page.gif" alt="Strict mode error page" width="600" />
 </p>
 
 ---
@@ -73,7 +80,7 @@ Adds diagnostic headers to every response for debugging:
 ---
 
 ### Log Mode
-Writes structured logs with full request attribution:
+Writes structured logs listing the requests that were in flight:
 
 <p align="center">
   <img src="assets/error-page-screenshot-console.png" alt="Console output" width="600" />
@@ -81,6 +88,21 @@ Writes structured logs with full request attribution:
 
 ---
 
+## 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:
+
+```ini
+# 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](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.
+
+---
+
 <p align="center">
   <a href="docs/CONFIGURATION.md"><strong>Full Configuration Reference</strong></a>
 </p>

fastapi_loopguard-0.6.0/assets/demo.tape

@@ -0,0 +1,59 @@
+# VHS tape for assets/demo.gif — reproduce with:
+#   brew install vhs
+#   pip install -e ".[stress]"   (needs uvicorn; run from the repo root)
+#   vhs assets/demo.tape
+#
+# Story: pain -> catch -> install.
+#   1. baseline: the async app answers in ~0.1s
+#   2. one request runs blocking code -> EVERY request freezes with it
+#      (the hang is real: /api/items stalls ~2s on screen, then the
+#      blocking request comes back 503)
+#   3. the LoopGuard console banner explains the fix + install CTA
+
+Output assets/demo.gif
+
+Set Shell bash
+Set FontSize 14
+Set Width 800
+Set Height 540
+Set Padding 12
+Set TypingSpeed 20ms
+Set Theme "Catppuccin Mocha"
+Set WindowBar Colorful
+Set BorderRadius 8
+
+Hide
+Type "source .venv/bin/activate && python examples/demo_app.py >/tmp/loopguard-demo.log 2>&1 & sleep 2; TIMEFORMAT='  took %Rs'; clear"
+Enter
+Sleep 2.5s
+Show
+
+Type "# a healthy async app"
+Enter
+Type "time curl -s localhost:8765/api/items"
+Enter
+Sleep 2s
+
+Ctrl+L
+Type "# one request runs blocking code - every request freezes with it"
+Enter
+Type "(curl -so /dev/null -w 'culprit -> %{http_code}\n' localhost:8765/api/users &)"
+Enter
+Type "time curl -s localhost:8765/api/items"
+Enter
+Sleep 4.5s
+
+Ctrl+L
+Type "# the server console explains what happened"
+Enter
+Type "grep -B 2 -A 18 'LOOPGUARD' /tmp/loopguard-demo.log"
+Enter
+Sleep 2.5s
+Type "# pip install fastapi-loopguard  ->  app.add_middleware(LoopGuardMiddleware)"
+Enter
+Sleep 2.5s
+
+Hide
+Type "kill %1"
+Enter
+Sleep 500ms