fastapi-loopguard 0.3.1__py3-none-any.whl

fastapi_loopguard/pytest_plugin.py

@@ -0,0 +1,135 @@
+"""Pytest plugin for detecting event loop blocking in tests.
+
+Usage:
+    # pytest.ini
+    [pytest]
+    loopguard_threshold_ms = 50
+
+    # In test files
+    import pytest
+
+    @pytest.mark.no_blocking
+    async def test_my_endpoint():
+        # If this test blocks the event loop, it will fail
+        ...
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections.abc import Generator
+from typing import Any
+
+import pytest
+
+# Marker for tests that should fail on blocking
+MARKER_NAME = "no_blocking"
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    """Register the no_blocking marker."""
+    config.addinivalue_line(
+        "markers",
+        f"{MARKER_NAME}: fail test if event loop blocking is detected",
+    )
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    """Add loopguard options to pytest."""
+    parser.addini(
+        "loopguard_threshold_ms",
+        "Blocking detection threshold in milliseconds",
+        type="string",
+        default="50",
+    )
+
+
+class BlockingDetector:
+    """Detects event loop blocking during test execution."""
+
+    def __init__(self, threshold_ms: float = 50.0) -> None:
+        self.threshold_ms = threshold_ms
+        self.blocking_events: list[float] = []
+        self._running = False
+        self._task: asyncio.Task[None] | None = None
+
+    async def start(self) -> None:
+        """Start the blocking detector."""
+        self._running = True
+        self._task = asyncio.create_task(self._monitor())
+
+    async def stop(self) -> None:
+        """Stop the blocking detector."""
+        self._running = False
+        if self._task:
+            self._task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._task
+
+    async def _monitor(self) -> None:
+        """Monitor for blocking."""
+        loop = asyncio.get_running_loop()
+        interval = 0.005  # 5ms
+
+        while self._running:
+            start = loop.time()
+            await asyncio.sleep(interval)
+            elapsed = loop.time() - start
+            lag_ms = (elapsed - interval) * 1000
+
+            if lag_ms > self.threshold_ms:
+                self.blocking_events.append(lag_ms)
+
+
+@pytest.fixture
+def loopguard_detector(
+    request: pytest.FixtureRequest,
+) -> Generator[BlockingDetector, None, None]:
+    """Fixture that provides a blocking detector for tests."""
+    threshold_str = request.config.getini("loopguard_threshold_ms")
+    threshold = float(threshold_str) if threshold_str else 50.0
+
+    detector = BlockingDetector(threshold_ms=threshold)
+    yield detector
+
+
+@pytest.hookimpl(tryfirst=True)
+def pytest_runtest_call(item: pytest.Item) -> None:
+    """Check for blocking after test execution."""
+    marker = item.get_closest_marker(MARKER_NAME)
+    if marker is None:
+        return
+
+    # Only works with Function items (which have obj attribute)
+    if not isinstance(item, pytest.Function):
+        return
+
+    # Store the original test function
+    original_func = item.obj
+
+    if asyncio.iscoroutinefunction(original_func):
+        # Wrap async test with blocking detection
+        async def wrapped(*args: Any, **kwargs: Any) -> Any:
+            threshold_str = item.config.getini("loopguard_threshold_ms")
+            threshold = float(threshold_str) if threshold_str else 50.0
+
+            detector = BlockingDetector(threshold_ms=threshold)
+            await detector.start()
+
+            try:
+                result = await original_func(*args, **kwargs)
+            finally:
+                await detector.stop()
+
+            if detector.blocking_events:
+                max_lag = max(detector.blocking_events)
+                pytest.fail(
+                    f"Event loop blocking detected! "
+                    f"{len(detector.blocking_events)} blocking event(s), "
+                    f"max lag: {max_lag:.2f}ms (threshold: {threshold}ms)"
+                )
+
+            return result
+
+        item.obj = wrapped

fastapi_loopguard-0.3.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+fastapi_loopguard/__init__.py,sha256=Rd6OC1wfGYQ7RCt6GRmCfd2S-rU_tz-u4Hwfw9TollU,1744
+fastapi_loopguard/config.py,sha256=KpeUHrGOxituZP6JRmvRKmIf__Oxd7xCFIVoQgRMazM,4166
+fastapi_loopguard/context.py,sha256=5K9R_cf_QY3vm9MX7BdY2ZH6CJ5ie2CXXS7Xd3pKi4g,6199
+fastapi_loopguard/logging.py,sha256=dOPTt0kqL8TddJU8UCdYm06DgKapVNVwn9KzgdtvoVk,2822
+fastapi_loopguard/metrics.py,sha256=h8nv9C4s3E8MgRswpMFkRESB0tE5MWAwGlz_BnMUSSo,6009
+fastapi_loopguard/middleware.py,sha256=2HXtQE6YKqqlOFePyIULcsubj6y6g5N5SkIfi29-32c,7667
+fastapi_loopguard/monitor.py,sha256=X3wKkIJ3XBhorZPPMR2MkbBecW3ER10yhMWfB9-erp0,14477
+fastapi_loopguard/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_loopguard/pytest_plugin.py,sha256=ZPqnEoiRViiz3uAk1ZlJZvl3DfqlFTZvUbKFiP9BaLA,4097
+fastapi_loopguard-0.3.1.dist-info/METADATA,sha256=c9M9CU3UJYTR_YeAIvNlpJLVNbNp6pnEF18beGaigYs,5071
+fastapi_loopguard-0.3.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+fastapi_loopguard-0.3.1.dist-info/entry_points.txt,sha256=tCJjzUcjpSL0ZWR_CFypskuZk_rCJRVEpTYNxzpfiII,55
+fastapi_loopguard-0.3.1.dist-info/licenses/LICENSE,sha256=X7DWiPGillxEDm4x1pGjpNCBDCFSovy0P009ODioYUg,1084
+fastapi_loopguard-0.3.1.dist-info/RECORD,,

fastapi_loopguard-0.3.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fastapi_loopguard-0.3.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+loopguard = fastapi_loopguard.pytest_plugin

fastapi_loopguard-0.3.1.dist-info/licenses/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.