fastapi-loopguard 0.3.1__tar.gz

fastapi_loopguard-0.3.1/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

fastapi_loopguard-0.3.1/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: |
+          ruff check src/ tests/
+          ruff format --check src/ tests/
+
+      - name: Type check with mypy
+        run: mypy src/
+
+      - name: Run tests with coverage
+        run: |
+          coverage run -m pytest tests/ -v
+          coverage report --fail-under=80
+          coverage xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        if: matrix.python-version == '3.12'
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false

fastapi_loopguard-0.3.1/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fastapi_loopguard-0.3.1/.gitignore

@@ -0,0 +1,115 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.log
+.ruff_cache/
+
+# Data files
+*.csv
+*.sqlite
+*.db
+
+# Performance profiling
+perf.data
+*.prof
+*.pstat
+
+# AI / Editors
+.claude/
+.cursor/

fastapi_loopguard-0.3.1/CLAUDE.md

@@ -0,0 +1,79 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+fastapi-loopguard is a middleware library that detects event-loop blocking in FastAPI/Starlette applications with per-request attribution. It identifies when synchronous operations (like `time.sleep()`, blocking I/O, or CPU-bound code) block the async event loop and reports which request was responsible.
+
+## Development Commands
+
+```bash
+# Install dependencies (including dev tools)
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run single test
+pytest tests/test_middleware.py::TestLoopGuardMiddleware::test_dev_mode_headers
+
+# Type checking (strict mode)
+mypy src/
+
+# Linting and formatting
+ruff check src/ tests/
+ruff format src/ tests/
+
+# Coverage
+coverage run -m pytest && coverage report
+```
+
+## Architecture
+
+### Core Components
+
+**LoopGuardMiddleware** (`middleware.py`): Pure ASGI middleware (no BaseHTTPMiddleware) that:
+- Handles ASGI lifespan events for proper startup/shutdown of the monitor
+- Registers request contexts for attribution via `RequestRegistry`
+- Injects debug headers (X-Request-Id, X-Blocking-Count, etc.) in dev mode via send wrapper
+
+**SentinelMonitor** (`monitor.py`): Background async task that detects blocking by:
+1. Sleeping for short intervals (default 10ms)
+2. Measuring actual elapsed time vs expected time
+3. If lag exceeds threshold (baseline × multiplier), blocking occurred
+4. Attributes blocking to ALL active requests since we can't determine the specific cause
+
+**RequestRegistry** (`context.py`): Thread-safe (via single-threaded asyncio) registry tracking concurrent requests. Uses dict keyed by request_id. When blocking is detected, the monitor iterates all active contexts.
+
+**LoopGuardConfig** (`config.py`): Frozen dataclass with validation. Key settings:
+- `monitor_interval_ms`: Check frequency (default 10ms)
+- `threshold_multiplier`: Blocking = lag > baseline × multiplier (default 5.0)
+- `dev_mode`: Enables X-Blocking-* response headers
+- `adaptive_threshold`: Enable sliding-window based automatic threshold adjustment (v0.3.0+)
+
+**AdaptiveThreshold** (`monitor.py`): Sliding window percentile-based threshold calculator:
+- Maintains a bounded deque of recent lag samples (`adaptive_window_size`)
+- Recalculates threshold as `P{adaptive_percentile} × multiplier`
+- Only activates after `adaptive_min_samples` collected
+- Reduces false positives in high-concurrency environments
+
+### Blocking Detection Flow
+
+1. Middleware registers `RequestContext` in global `RequestRegistry`
+2. `SentinelMonitor` runs continuous sleep-measure loop
+3. On startup: background calibration measures baseline latency (P75 of samples)
+4. When lag > threshold: `_handle_blocking()` iterates all active contexts via `get_active_requests()`
+5. Each context's `record_blocking()` appends event to `blocking_events` list
+6. On response: middleware reads context stats and adds headers
+
+### Optional Components
+
+- **Prometheus metrics** (`metrics.py`): Optional `prometheus_client` integration
+- **pytest plugin** (`pytest_plugin.py`): `@pytest.mark.no_blocking` marker fails tests that block
+
+## Test Configuration
+
+- Uses `pytest-asyncio` with `asyncio_mode = "auto"` and `asyncio_default_fixture_loop_scope = "function"`
+- Tests use `httpx.AsyncClient` with `ASGITransport` for testing ASGI apps
+- Each test clears the global `RequestRegistry` via `clear_registry` fixture

fastapi_loopguard-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Parham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_loopguard-0.3.1/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: fastapi-loopguard
+Version: 0.3.1
+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
+Project-URL: Repository, https://github.com/parhamdavari/fastapi-loopguard
+Project-URL: Issues, https://github.com/parhamdavari/fastapi-loopguard/issues
+Author: Parham
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,blocking,event-loop,fastapi,middleware,monitoring,performance,starlette
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+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
+Provides-Extra: all
+Requires-Dist: prometheus-client>=0.19.0; extra == 'all'
+Requires-Dist: structlog>=24.1.0; extra == 'all'
+Provides-Extra: dev
+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: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Provides-Extra: prometheus
+Requires-Dist: prometheus-client>=0.19.0; extra == 'prometheus'
+Provides-Extra: stress
+Requires-Dist: locust>=2.20.0; extra == 'stress'
+Requires-Dist: uvicorn>=0.27.0; extra == 'stress'
+Provides-Extra: structlog
+Requires-Dist: structlog>=24.1.0; extra == 'structlog'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/loopguard-logo.webp" alt="LoopGuard logo" width="320" />
+</p>
+
+<p align="center">
+  Detect event-loop blocking in FastAPI/Starlette with <strong>per-request attribution</strong>.
+</p>
+
+---
+
+[![PyPI version](https://badge.fury.io/py/fastapi-loopguard.svg)](https://badge.fury.io/py/fastapi-loopguard)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+`fastapi-loopguard` monitors your event loop and tells you exactly which request caused the blocking. It handles high-concurrency environments with adaptive thresholds and integrates seamlessly with Prometheus.
+
+###
+
+### Quick Start
+
+```bash
+pip install fastapi-loopguard
+```
+
+```python
+from fastapi import FastAPI
+from fastapi_loopguard import LoopGuardMiddleware
+
+app = FastAPI()
+app.add_middleware(LoopGuardMiddleware)
+```
+
+### Features
+
+*   **Per-Request Attribution**: Pinpoint the exact endpoint causing latency.
+*   **Cumulative Blocking Detection**: Catch "death by a thousand cuts" where frequent small blocks freeze the loop.
+*   **Adaptive Thresholds**: Smart baselines that adjust to server load.
+*   **Zero-Overhead Sentinel**: Cooperative monitoring with negligible CPU usage.
+*   **Observability Ready**: Built-in support for Prometheus and structured logging.
+
+### Configuration
+
+LoopGuard is highly configurable to suit your environment:
+
+```python
+from fastapi import FastAPI
+from fastapi_loopguard import LoopGuardMiddleware, LoopGuardConfig
+
+config = LoopGuardConfig(
+    # Basic settings
+    monitor_interval_ms=10.0,
+    fallback_threshold_ms=50.0,
+    
+    # Enable Cumulative Blocking Detection
+    # Detects frequent small blocks (e.g., 20ms) that sum up to a large freeze
+    cumulative_blocking_enabled=True,
+    cumulative_blocking_threshold_ms=200.0, # Alert if total block > 200ms...
+    cumulative_window_ms=1000.0,            # ...within any 1-second window
+)
+
+app = FastAPI()
+app.add_middleware(LoopGuardMiddleware, config=config)
+```
+
+### Request/Response flows
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor Client
+    participant MW as Middleware<br/>(middleware.py)
+    participant Reg as Context Registry<br/>(context.py)
+    participant Mon as Sentinel Monitor<br/>(monitor.py)
+    participant App as FastAPI App<br/>(Your Code)
+
+    Note over MW, App: Request Flow
+    
+    Client->>MW: HTTP Request
+    activate MW
+    
+    MW->>Reg: Register Context
+    activate Reg
+    Reg-->>MW: Done
+    deactivate Reg
+
+    MW->>App: Forward Request
+    activate App
+    
+    par Async Monitoring
+        Mon->>Reg: Detect Blocking &<br/>Update Contexts
+        activate Mon
+        activate Reg
+        Reg-->>Mon: Updated
+        deactivate Reg
+        deactivate Mon
+    and App Processing
+        App-->>MW: Process Complete
+        deactivate App
+    end
+
+    MW->>Reg: Unregister Context
+    activate Reg
+    Reg-->>MW: Done
+    deactivate Reg
+
+    MW->>Client: Response + Headers
+    deactivate MW
+```
+

fastapi_loopguard-0.3.1/README.md

@@ -0,0 +1,109 @@
+<p align="center">
+  <img src="assets/loopguard-logo.webp" alt="LoopGuard logo" width="320" />
+</p>
+
+<p align="center">
+  Detect event-loop blocking in FastAPI/Starlette with <strong>per-request attribution</strong>.
+</p>
+
+---
+
+[![PyPI version](https://badge.fury.io/py/fastapi-loopguard.svg)](https://badge.fury.io/py/fastapi-loopguard)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+`fastapi-loopguard` monitors your event loop and tells you exactly which request caused the blocking. It handles high-concurrency environments with adaptive thresholds and integrates seamlessly with Prometheus.
+
+###
+
+### Quick Start
+
+```bash
+pip install fastapi-loopguard
+```
+
+```python
+from fastapi import FastAPI
+from fastapi_loopguard import LoopGuardMiddleware
+
+app = FastAPI()
+app.add_middleware(LoopGuardMiddleware)
+```
+
+### Features
+
+*   **Per-Request Attribution**: Pinpoint the exact endpoint causing latency.
+*   **Cumulative Blocking Detection**: Catch "death by a thousand cuts" where frequent small blocks freeze the loop.
+*   **Adaptive Thresholds**: Smart baselines that adjust to server load.
+*   **Zero-Overhead Sentinel**: Cooperative monitoring with negligible CPU usage.
+*   **Observability Ready**: Built-in support for Prometheus and structured logging.
+
+### Configuration
+
+LoopGuard is highly configurable to suit your environment:
+
+```python
+from fastapi import FastAPI
+from fastapi_loopguard import LoopGuardMiddleware, LoopGuardConfig
+
+config = LoopGuardConfig(
+    # Basic settings
+    monitor_interval_ms=10.0,
+    fallback_threshold_ms=50.0,
+    
+    # Enable Cumulative Blocking Detection
+    # Detects frequent small blocks (e.g., 20ms) that sum up to a large freeze
+    cumulative_blocking_enabled=True,
+    cumulative_blocking_threshold_ms=200.0, # Alert if total block > 200ms...
+    cumulative_window_ms=1000.0,            # ...within any 1-second window
+)
+
+app = FastAPI()
+app.add_middleware(LoopGuardMiddleware, config=config)
+```
+
+### Request/Response flows
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor Client
+    participant MW as Middleware<br/>(middleware.py)
+    participant Reg as Context Registry<br/>(context.py)
+    participant Mon as Sentinel Monitor<br/>(monitor.py)
+    participant App as FastAPI App<br/>(Your Code)
+
+    Note over MW, App: Request Flow
+    
+    Client->>MW: HTTP Request
+    activate MW
+    
+    MW->>Reg: Register Context
+    activate Reg
+    Reg-->>MW: Done
+    deactivate Reg
+
+    MW->>App: Forward Request
+    activate App
+    
+    par Async Monitoring
+        Mon->>Reg: Detect Blocking &<br/>Update Contexts
+        activate Mon
+        activate Reg
+        Reg-->>Mon: Updated
+        deactivate Reg
+        deactivate Mon
+    and App Processing
+        App-->>MW: Process Complete
+        deactivate App
+    end
+
+    MW->>Reg: Unregister Context
+    activate Reg
+    Reg-->>MW: Done
+    deactivate Reg
+
+    MW->>Client: Response + Headers
+    deactivate MW
+```
+

fastapi_loopguard-0.3.1/examples/demo_app.py

@@ -0,0 +1,58 @@
+"""Demo app showing fastapi-loopguard blocking detection."""
+
+import asyncio
+import time
+
+from fastapi import FastAPI
+
+from fastapi_loopguard import LoopGuardConfig, LoopGuardMiddleware
+
+app = FastAPI(title="LoopGuard Demo")
+
+# Configure with dev_mode for headers and logging enabled
+config = LoopGuardConfig(
+    dev_mode=True,
+    log_blocking_events=True,
+    fallback_threshold_ms=30.0,  # Low threshold for demo
+)
+app.add_middleware(LoopGuardMiddleware, config=config)
+
+
+@app.get("/")
+async def root():
+    """Non-blocking endpoint."""
+    return {"message": "Hello, this is non-blocking!"}
+
+
+@app.get("/api/users")
+async def get_users():
+    """Endpoint that blocks the event loop - will trigger warning."""
+    # This blocks the event loop! BAD!
+    time.sleep(0.15)  # 150ms blocking
+    # Small yield to let monitor detect the blocking while context is still active
+    await asyncio.sleep(0.02)
+    return {"users": ["alice", "bob", "charlie"]}
+
+
+@app.get("/api/items")
+async def get_items():
+    """Non-blocking endpoint using async sleep."""
+    # This is correct - doesn't block
+    await asyncio.sleep(0.1)
+    return {"items": ["item1", "item2", "item3"]}
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    print("\n" + "=" * 60)
+    print("LoopGuard Demo App")
+    print("=" * 60)
+    print("\nEndpoints:")
+    print("  GET /           - Non-blocking (no warning)")
+    print("  GET /api/users  - BLOCKING (will trigger warning)")
+    print("  GET /api/items  - Non-blocking async sleep (no warning)")
+    print("\nTry: curl http://localhost:8765/api/users")
+    print("=" * 60 + "\n")
+
+    uvicorn.run(app, host="0.0.0.0", port=8765, log_level="info")