fastapi-loopguard 0.4.0__tar.gz → 0.5.0__tar.gz

fastapi_loopguard-0.5.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## 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.5.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 (dev_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) and its floor follows the calibrated threshold, so neither calibration nor adaptation can be poisoned upward by the app's own blocking. A failed or cancelled calibration keeps the fallback threshold and must never raise into startup.
+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. Cumulative window sums are recorded in `RequestContext.cumulative_events`, separate from the individual-lag `blocking_events` list; `blocking_count` / `total_blocking_ms` sum both.
+8. **Lifecycle calls are idempotent, and lazy monitors stop when idle.** `start()`, `start_with_background_calibration()`, and `stop()` all return early when already in the target state. `_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.5.0/FINDINGS.md

@@ -0,0 +1,84 @@
+# Findings not fixed in the 0.5 pass
+
+Everything noticed while fixing the 0.5 correctness defects but deliberately
+left alone. Each item is its own future task.
+
+## Detection design
+
+1. **Sub-threshold noise can still inflate the adaptive threshold.**
+   The 0.5 fix censors detected-blocking samples out of the window, but
+   samples just below the threshold are admitted by design, and
+   `P95 x threshold_multiplier` of ~40ms noise still produces a ~230ms
+   threshold that would mask a later 100ms block. Per the forensics guidance,
+   median+MAD over the censored window would be more robust than a percentile.
+
+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; worth documenting.
+
+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"**; since 0.5 it is also the hard ceiling for
+    the calibrated threshold.
+
+13. **`_handle_lifespan` locals `started` / `shutdown_complete` are write-only.**
+
+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.
+
+## 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.0 → fastapi_loopguard-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: fastapi-loopguard
-Version: 0.4.0
+Version: 0.5.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
@@ -48,7 +48,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">
@@ -59,7 +59,7 @@ Description-Content-Type: text/markdown
 
 ---
 
-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 +88,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")
 
@@ -118,10 +121,14 @@ 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" />
 </p>
 
 ---
+
+<p align="center">
+  <a href="docs/CONFIGURATION.md"><strong>Full Configuration Reference</strong></a>
+</p>

{fastapi_loopguard-0.4.0 → fastapi_loopguard-0.5.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">
@@ -14,7 +14,7 @@
 
 ---
 
-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 +43,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")
 
@@ -73,10 +76,14 @@ 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" />
 </p>
 
 ---
+
+<p align="center">
+  <a href="docs/CONFIGURATION.md"><strong>Full Configuration Reference</strong></a>
+</p>

fastapi_loopguard-0.5.0/docs/CONFIGURATION.md

@@ -0,0 +1,134 @@
+# Configuration Reference
+
+All configuration options for `LoopGuardConfig`.
+
+## Quick Reference
+
+```python
+from fastapi_loopguard import LoopGuardConfig
+
+config = LoopGuardConfig(
+    # Enforcement
+    enforcement_mode="warn",      # "log" | "warn" | "strict"
+    dev_mode=False,               # Adds X-Blocking-* response headers when True
+
+    # Detection tuning
+    monitor_interval_ms=10.0,     # How often to check (ms)
+    threshold_multiplier=5.0,     # Blocking = lag > baseline × multiplier
+    fallback_threshold_ms=50.0,   # Threshold if calibration fails
+
+    # Cumulative detection (enabled by default)
+    cumulative_blocking_enabled=True,
+    cumulative_blocking_threshold_ms=200.0,
+    cumulative_window_ms=1000.0,
+
+    # Adaptive threshold (disabled by default)
+    adaptive_threshold=False,
+
+    # Integrations
+    prometheus_enabled=False,
+    log_blocking_events=True,
+)
+```
+
+---
+
+## Core Settings
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | bool | `True` | Master switch. Set `False` to disable entirely. |
+| `enforcement_mode` | str | `"warn"` | How to respond: `"log"`, `"warn"`, or `"strict"` |
+| `dev_mode` | bool | `False` | Enables response headers. Never changes the enforcement mode. |
+| `log_blocking_events` | bool | `True` | Log blocking events to console |
+| `exclude_paths` | frozenset | `{"/health", ...}` | Paths to skip monitoring |
+
+---
+
+## Detection Tuning
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `monitor_interval_ms` | float | `10.0` | Sentinel check frequency (ms) |
+| `threshold_multiplier` | float | `5.0` | Blocking detected when lag > baseline × this |
+| `calibration_iterations` | int | `100` | Samples during startup calibration |
+| `fallback_threshold_ms` | float | `50.0` | Used if calibration is unreliable |
+
+---
+
+## Cumulative Blocking Detection
+
+Catches "death by a thousand cuts" - many small blocks that add up.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `cumulative_blocking_enabled` | bool | `True` | Enable cumulative detection |
+| `cumulative_blocking_threshold_ms` | float | `200.0` | Alert if total blocking exceeds this... |
+| `cumulative_window_ms` | float | `1000.0` | ...within this time window (ms) |
+
+**Example:** With defaults, alerts if blocking totals >200ms within any 1-second window.
+
+---
+
+## Adaptive Threshold
+
+Dynamically adjusts threshold based on observed latency. Useful for high-concurrency environments.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `adaptive_threshold` | bool | `False` | Enable adaptive mode |
+| `adaptive_window_size` | int | `1000` | Samples in sliding window |
+| `adaptive_percentile` | float | `0.95` | Percentile for baseline (0.5-0.99) |
+| `adaptive_min_samples` | int | `100` | Min samples before activation |
+| `adaptive_update_interval_ms` | float | `1000.0` | Recalculation frequency (ms) |
+
+---
+
+## Integrations
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `prometheus_enabled` | bool | `False` | Expose Prometheus metrics |
+
+When enabled, exposes:
+- `loopguard_blocking_events_total` - Counter of blocking events
+- `loopguard_blocking_duration_ms` - Histogram of blocking durations
+
+---
+
+## Common Configurations
+
+### Development (diagnostic headers)
+```python
+config = LoopGuardConfig(dev_mode=True)
+```
+
+### Development / CI (strict enforcement, 503 on blocking)
+```python
+config = LoopGuardConfig(enforcement_mode="strict")
+```
+
+### Production (silent monitoring)
+```python
+config = LoopGuardConfig(
+    enforcement_mode="log",
+    prometheus_enabled=True,
+)
+```
+
+### High-concurrency (adaptive threshold)
+```python
+config = LoopGuardConfig(
+    adaptive_threshold=True,
+    adaptive_percentile=0.99,
+)
+```
+
+### Sensitive detection (lower threshold)
+```python
+config = LoopGuardConfig(
+    monitor_interval_ms=5.0,
+    threshold_multiplier=3.0,
+    fallback_threshold_ms=30.0,
+)
+```

{fastapi_loopguard-0.4.0 → fastapi_loopguard-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fastapi-loopguard"
-version = "0.4.0"
+version = "0.5.0"
 description = "Detect event-loop blocking in FastAPI/Starlette with per-request attribution"
 readme = "README.md"
 license = "MIT"

{fastapi_loopguard-0.4.0 → fastapi_loopguard-0.5.0}/src/fastapi_loopguard/__init__.py

@@ -1,4 +1,8 @@
-"""FastAPI LoopGuard - Detect event-loop blocking with per-request attribution.
+"""FastAPI LoopGuard - Detect event-loop blocking and report in-flight requests.
+
+The sentinel measures event-loop lag, so it cannot identify the single
+handler that blocked; it attributes each stall to every request that was
+in flight at the time.
 
 Usage:
     from fastapi import FastAPI
@@ -29,6 +33,8 @@ v0.3.0 Changes:
     - High-concurrency configuration documentation
 """
 
+from importlib.metadata import version as _package_version
+
 from .config import LoopGuardConfig
 from .context import (
     RequestContext,
@@ -42,7 +48,7 @@ from .context import (
 from .middleware import LoopGuardMiddleware
 from .monitor import SentinelMonitor
 
-__version__ = "0.3.0"
+__version__ = _package_version("fastapi-loopguard")
 
 __all__ = [
     # Core classes

{fastapi_loopguard-0.4.0 → fastapi_loopguard-0.5.0}/src/fastapi_loopguard/config.py

@@ -46,7 +46,7 @@ class LoopGuardConfig:
     adaptive_update_interval_ms: float = 1000.0
 
     # Cumulative blocking detection
-    cumulative_blocking_enabled: bool = False
+    cumulative_blocking_enabled: bool = True
     cumulative_blocking_threshold_ms: float = 200.0
     cumulative_window_ms: float = 1000.0
 

{fastapi_loopguard-0.4.0 → fastapi_loopguard-0.5.0}/src/fastapi_loopguard/context.py

@@ -24,7 +24,10 @@ class RequestContext:
         path: The request path (e.g., "/api/users").
         method: HTTP method (GET, POST, etc.).
         start_time: Monotonic timestamp when request started.
-        blocking_events: List of (lag_ms, timestamp) tuples for blocking detected.
+        blocking_events: List of (lag_ms, timestamp) tuples, one per observed
+            lag sample that exceeded the threshold.
+        cumulative_events: List of (lag_ms, timestamp) tuples where lag_ms is
+            a window sum from cumulative detection, not an individual sample.
     """
 
     request_id: str
@@ -32,20 +35,30 @@ class RequestContext:
     method: str
     start_time: float = field(default_factory=time.monotonic)
     blocking_events: list[tuple[float, float]] = field(default_factory=list)
+    cumulative_events: list[tuple[float, float]] = field(default_factory=list)
 
-    def record_blocking(self, lag_ms: float) -> None:
-        """Record a blocking event for this request."""
-        self.blocking_events.append((lag_ms, time.monotonic()))
+    def record_blocking(self, lag_ms: float, cumulative: bool = False) -> None:
+        """Record a blocking event for this request.
+
+        Args:
+            lag_ms: The observed lag in milliseconds.
+            cumulative: True when lag_ms is a window sum from cumulative
+                detection rather than a single observed lag sample.
+        """
+        events = self.cumulative_events if cumulative else self.blocking_events
+        events.append((lag_ms, time.monotonic()))
 
     @property
     def total_blocking_ms(self) -> float:
-        """Sum of all blocking event durations."""
-        return sum(lag for lag, _ in self.blocking_events)
+        """Sum of all blocking event durations (individual and cumulative)."""
+        return sum(lag for lag, _ in self.blocking_events) + sum(
+            lag for lag, _ in self.cumulative_events
+        )
 
     @property
     def blocking_count(self) -> int:
-        """Number of blocking events detected."""
-        return len(self.blocking_events)
+        """Number of blocking events detected (individual and cumulative)."""
+        return len(self.blocking_events) + len(self.cumulative_events)
 
 
 class RequestRegistry: