flowsurgeon 0.2.0__tar.gz

flowsurgeon-0.2.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.3
+Name: flowsurgeon
+Version: 0.2.0
+Summary: FlowSurgeon — framework-agnostic profiling middleware for Python (WSGI & ASGI).
+Keywords: wsgi,asgi,middleware,profiling,debugging,fastapi,flask,starlette
+Author: Samandar-Komilov
+Author-email: Samandar-Komilov <voidpointer07@gmail.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/Samandar-Komilov/flowsurgeon
+Project-URL: Repository, https://github.com/Samandar-Komilov/flowsurgeon
+Project-URL: Issues, https://github.com/Samandar-Komilov/flowsurgeon/issues
+Description-Content-Type: text/markdown
+
+# FlowSurgeon
+
+Framework-agnostic profiling middleware for Python — works with **Flask** (WSGI) and **FastAPI / Starlette** (ASGI) out of the box.
+
+FlowSurgeon injects a lightweight debug panel into every HTML response and stores request history in a local SQLite database, giving you timing, headers, and status codes without touching your application code.
+
+## Features
+
+- Zero required dependencies — pure stdlib
+- WSGI middleware (`FlowSurgeonWSGI`) for Flask, Django, and any WSGI app
+- ASGI middleware (`FlowSurgeonASGI`) for FastAPI, Starlette, and any ASGI app
+- `FlowSurgeon()` factory — auto-detects WSGI vs ASGI
+- Inline debug panel injected into HTML responses
+- Built-in history UI at `/__flowsurgeon__/`
+- SQLite persistence with auto-pruning
+- Sensitive header redaction (`Authorization`, `Cookie`)
+- `FLOWSURGEON_ENABLED` environment variable kill switch
+
+## Installation
+
+```bash
+pip install flowsurgeon
+```
+
+## Quick start
+
+### FastAPI (ASGI)
+
+```python
+from fastapi import FastAPI
+from flowsurgeon import FlowSurgeon, Config
+
+_app = FastAPI()
+app = FlowSurgeon(_app, config=Config(enabled=True))
+
+@_app.get("/")
+async def index():
+    return {"hello": "world"}
+```
+
+Run with uvicorn:
+
+```bash
+uvicorn myapp:app
+```
+
+### Flask (WSGI)
+
+```python
+from flask import Flask
+from flowsurgeon import FlowSurgeon, Config
+
+flask_app = Flask(__name__)
+flask_app.wsgi_app = FlowSurgeon(
+    flask_app.wsgi_app,
+    config=Config(enabled=True),
+)
+```
+
+## Configuration
+
+```python
+from flowsurgeon import Config
+
+Config(
+    enabled=True,                          # default: False (or FLOWSURGEON_ENABLED=1)
+    allowed_hosts=["127.0.0.1", "::1"],    # hosts that see the panel
+    db_path="flowsurgeon.db",              # SQLite file path
+    max_stored_requests=1000,              # auto-prune threshold
+    debug_route="/__flowsurgeon__",        # history UI prefix
+    strip_sensitive_headers=["authorization", "cookie", "set-cookie"],
+)
+```
+
+## Debug UI
+
+| Route | Description |
+|---|---|
+| `/__flowsurgeon__/` | Paginated request history |
+| `/__flowsurgeon__/{id}` | Full detail for one request |
+
+## Roadmap
+
+- v0.3.0 — SQL query tracking (SQLAlchemy, DB-API 2.0)
+- v0.4.0 — CPU and memory profiling panel
+- v0.5.0 — Log capture and headers panel
+- v0.6.0 — Improved history/search UI
+
+## License
+
+MIT

flowsurgeon-0.2.0/README.md

@@ -0,0 +1,91 @@
+# FlowSurgeon
+
+Framework-agnostic profiling middleware for Python — works with **Flask** (WSGI) and **FastAPI / Starlette** (ASGI) out of the box.
+
+FlowSurgeon injects a lightweight debug panel into every HTML response and stores request history in a local SQLite database, giving you timing, headers, and status codes without touching your application code.
+
+## Features
+
+- Zero required dependencies — pure stdlib
+- WSGI middleware (`FlowSurgeonWSGI`) for Flask, Django, and any WSGI app
+- ASGI middleware (`FlowSurgeonASGI`) for FastAPI, Starlette, and any ASGI app
+- `FlowSurgeon()` factory — auto-detects WSGI vs ASGI
+- Inline debug panel injected into HTML responses
+- Built-in history UI at `/__flowsurgeon__/`
+- SQLite persistence with auto-pruning
+- Sensitive header redaction (`Authorization`, `Cookie`)
+- `FLOWSURGEON_ENABLED` environment variable kill switch
+
+## Installation
+
+```bash
+pip install flowsurgeon
+```
+
+## Quick start
+
+### FastAPI (ASGI)
+
+```python
+from fastapi import FastAPI
+from flowsurgeon import FlowSurgeon, Config
+
+_app = FastAPI()
+app = FlowSurgeon(_app, config=Config(enabled=True))
+
+@_app.get("/")
+async def index():
+    return {"hello": "world"}
+```
+
+Run with uvicorn:
+
+```bash
+uvicorn myapp:app
+```
+
+### Flask (WSGI)
+
+```python
+from flask import Flask
+from flowsurgeon import FlowSurgeon, Config
+
+flask_app = Flask(__name__)
+flask_app.wsgi_app = FlowSurgeon(
+    flask_app.wsgi_app,
+    config=Config(enabled=True),
+)
+```
+
+## Configuration
+
+```python
+from flowsurgeon import Config
+
+Config(
+    enabled=True,                          # default: False (or FLOWSURGEON_ENABLED=1)
+    allowed_hosts=["127.0.0.1", "::1"],    # hosts that see the panel
+    db_path="flowsurgeon.db",              # SQLite file path
+    max_stored_requests=1000,              # auto-prune threshold
+    debug_route="/__flowsurgeon__",        # history UI prefix
+    strip_sensitive_headers=["authorization", "cookie", "set-cookie"],
+)
+```
+
+## Debug UI
+
+| Route | Description |
+|---|---|
+| `/__flowsurgeon__/` | Paginated request history |
+| `/__flowsurgeon__/{id}` | Full detail for one request |
+
+## Roadmap
+
+- v0.3.0 — SQL query tracking (SQLAlchemy, DB-API 2.0)
+- v0.4.0 — CPU and memory profiling panel
+- v0.5.0 — Log capture and headers panel
+- v0.6.0 — Improved history/search UI
+
+## License
+
+MIT

flowsurgeon-0.2.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "flowsurgeon"
+version = "0.2.0"
+description = "FlowSurgeon — framework-agnostic profiling middleware for Python (WSGI & ASGI)."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Samandar-Komilov", email = "voidpointer07@gmail.com" }]
+requires-python = ">=3.12"
+dependencies = []
+keywords = ["wsgi", "asgi", "middleware", "profiling", "debugging", "fastapi", "flask", "starlette"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware",
+    "Topic :: Software Development :: Debuggers",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/Samandar-Komilov/flowsurgeon"
+Repository = "https://github.com/Samandar-Komilov/flowsurgeon"
+Issues = "https://github.com/Samandar-Komilov/flowsurgeon/issues"
+
+[build-system]
+requires = ["uv_build>=0.9.17,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.0.0",
+]
+examples = [
+    "fastapi>=0.135.1",
+    "flask>=3.1.3",
+    "uvicorn>=0.41.0",
+]

flowsurgeon-0.2.0/src/flowsurgeon/__init__.py

@@ -0,0 +1,39 @@
+"""FlowSurgeon — framework-agnostic profiling middleware for Python."""
+
+from __future__ import annotations
+
+import inspect
+
+from flowsurgeon.core.config import Config
+from flowsurgeon.core.records import RequestRecord
+from flowsurgeon.middleware.asgi import FlowSurgeonASGI
+from flowsurgeon.middleware.wsgi import FlowSurgeonWSGI
+from flowsurgeon.storage.async_sqlite import AsyncSQLiteBackend
+from flowsurgeon.storage.base import StorageBackend
+from flowsurgeon.storage.sqlite import SQLiteBackend
+
+
+def FlowSurgeon(app, *, config: Config | None = None, storage=None):
+    """Auto-detect WSGI vs ASGI and wrap *app* with the appropriate middleware.
+
+    Detection is based on whether ``app.__call__`` is a coroutine function.
+    FastAPI / Starlette apps are detected as ASGI; plain WSGI callables
+    (Flask, Django, etc.) are wrapped with :class:`FlowSurgeonWSGI`.
+    """
+    if inspect.iscoroutinefunction(app) or inspect.iscoroutinefunction(getattr(app, "__call__", None)):
+        return FlowSurgeonASGI(app, config=config, storage=storage)
+    return FlowSurgeonWSGI(app, config=config, storage=storage)
+
+
+__all__ = [
+    "AsyncSQLiteBackend",
+    "Config",
+    "FlowSurgeon",
+    "FlowSurgeonASGI",
+    "FlowSurgeonWSGI",
+    "RequestRecord",
+    "SQLiteBackend",
+    "StorageBackend",
+]
+
+__version__ = "0.2.0"

flowsurgeon-0.2.0/src/flowsurgeon/core/__init__.py

@@ -0,0 +1,4 @@
+from flowsurgeon.core.config import Config
+from flowsurgeon.core.records import RequestRecord
+
+__all__ = ["Config", "RequestRecord"]

flowsurgeon-0.2.0/src/flowsurgeon/core/config.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Config:
+    """FlowSurgeon configuration.
+
+    Parameters
+    ----------
+    enabled:
+        Master switch. Defaults to False; can be overridden by the
+        FLOWSURGEON_ENABLED environment variable.
+    allowed_hosts:
+        Only serve the debug panel to requests from these hosts/IPs.
+        Defaults to localhost addresses only.
+    db_path:
+        Path to the SQLite database file used for persistence.
+    max_stored_requests:
+        Maximum number of request records to keep in the database.
+        Older records are pruned automatically.
+    debug_route:
+        URL prefix for the built-in debug UI.
+    strip_sensitive_headers:
+        Header names whose values will be redacted before storage.
+    """
+
+    enabled: bool = field(default_factory=lambda: _env_bool("FLOWSURGEON_ENABLED", False))
+    allowed_hosts: list[str] = field(default_factory=lambda: ["127.0.0.1", "::1", "localhost"])
+    db_path: str = "flowsurgeon.db"
+    max_stored_requests: int = 1000
+    debug_route: str = "/__flowsurgeon__"
+    strip_sensitive_headers: list[str] = field(
+        default_factory=lambda: ["authorization", "cookie", "set-cookie"]
+    )
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    val = os.environ.get(name)
+    if val is None:
+        return default
+    return val.lower() in ("1", "true", "yes")

flowsurgeon-0.2.0/src/flowsurgeon/core/records.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+
+@dataclass
+class RequestRecord:
+    """Captured data for a single HTTP request."""
+
+    request_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    method: str = ""
+    path: str = ""
+    query_string: str = ""
+    status_code: int = 0
+    duration_ms: float = 0.0
+    request_headers: dict[str, str] = field(default_factory=dict)
+    response_headers: dict[str, str] = field(default_factory=dict)
+    client_host: str = ""

flowsurgeon-0.2.0/src/flowsurgeon/middleware/__init__.py

@@ -0,0 +1,3 @@
+from flowsurgeon.middleware.wsgi import FlowSurgeonWSGI
+
+__all__ = ["FlowSurgeonWSGI"]

flowsurgeon-0.2.0/src/flowsurgeon/middleware/asgi.py

@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+import time
+from typing import Awaitable, Callable
+
+from flowsurgeon.core.config import Config
+from flowsurgeon.core.records import RequestRecord
+from flowsurgeon.storage.async_sqlite import AsyncSQLiteBackend
+from flowsurgeon.ui.panel import render_detail_page, render_history_page, render_panel
+
+# ASGI type aliases
+Scope = dict
+Receive = Callable[[], Awaitable[dict]]
+Send = Callable[[dict], Awaitable[None]]
+ASGIApp = Callable[[Scope, Receive, Send], Awaitable[None]]
+
+_HTML_CONTENT_TYPES = ("text/html",)
+
+
+class FlowSurgeonASGI:
+    """ASGI middleware that profiles requests and injects a debug panel.
+
+    Parameters
+    ----------
+    app:
+        The wrapped ASGI application.
+    config:
+        FlowSurgeon configuration. Defaults to :class:`Config` with all
+        defaults applied.
+    storage:
+        Async storage backend. Defaults to :class:`AsyncSQLiteBackend`
+        pointed at ``config.db_path``.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        config: Config | None = None,
+        storage: AsyncSQLiteBackend | None = None,
+    ) -> None:
+        self._app = app
+        self._config = config or Config()
+        self._storage: AsyncSQLiteBackend = storage or AsyncSQLiteBackend(self._config.db_path)
+
+    # ------------------------------------------------------------------
+    # ASGI entry point
+    # ------------------------------------------------------------------
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] == "lifespan":
+            await self._handle_lifespan(scope, receive, send)
+            return
+
+        if scope["type"] != "http":
+            await self._app(scope, receive, send)
+            return
+
+        if not self._config.enabled:
+            await self._app(scope, receive, send)
+            return
+
+        client_host = _client_host(scope)
+        if not self._is_allowed(client_host):
+            await self._app(scope, receive, send)
+            return
+
+        path = scope.get("path", "/")
+        debug_route = self._config.debug_route
+
+        if path == debug_route or path == debug_route + "/":
+            await self._serve_history(send)
+            return
+        if path.startswith(debug_route + "/"):
+            request_id = path[len(debug_route) + 1 :]
+            await self._serve_detail(request_id, send)
+            return
+
+        await self._profile_request(scope, receive, send, client_host, path)
+
+    # ------------------------------------------------------------------
+    # Lifespan
+    # ------------------------------------------------------------------
+
+    async def _handle_lifespan(self, scope: Scope, receive: Receive, send: Send) -> None:
+        async def receive_wrapper() -> dict:
+            message = await receive()
+            if message["type"] == "lifespan.startup":
+                await self._storage.start()
+            return message
+
+        async def send_wrapper(message: dict) -> None:
+            if message["type"] == "lifespan.shutdown.complete":
+                await self._storage.close()
+            await send(message)
+
+        await self._app(scope, receive_wrapper, send_wrapper)
+
+    # ------------------------------------------------------------------
+    # Debug UI routes
+    # ------------------------------------------------------------------
+
+    async def _serve_history(self, send: Send) -> None:
+        records = await self._storage.list_recent(limit=100)
+        body = render_history_page(records, self._config.debug_route).encode()
+        await send(
+            {
+                "type": "http.response.start",
+                "status": 200,
+                "headers": [
+                    (b"content-type", b"text/html; charset=utf-8"),
+                    (b"content-length", str(len(body)).encode()),
+                ],
+            }
+        )
+        await send({"type": "http.response.body", "body": body})
+
+    async def _serve_detail(self, request_id: str, send: Send) -> None:
+        record = await self._storage.get(request_id)
+        if record is None:
+            body = b"<h1>Not found</h1>"
+            await send(
+                {
+                    "type": "http.response.start",
+                    "status": 404,
+                    "headers": [
+                        (b"content-type", b"text/html; charset=utf-8"),
+                        (b"content-length", str(len(body)).encode()),
+                    ],
+                }
+            )
+            await send({"type": "http.response.body", "body": body})
+            return
+        body = render_detail_page(record, self._config.debug_route).encode()
+        await send(
+            {
+                "type": "http.response.start",
+                "status": 200,
+                "headers": [
+                    (b"content-type", b"text/html; charset=utf-8"),
+                    (b"content-length", str(len(body)).encode()),
+                ],
+            }
+        )
+        await send({"type": "http.response.body", "body": body})
+
+    # ------------------------------------------------------------------
+    # Request profiling
+    # ------------------------------------------------------------------
+
+    async def _profile_request(
+        self,
+        scope: Scope,
+        receive: Receive,
+        send: Send,
+        client_host: str,
+        path: str,
+    ) -> None:
+        raw_headers: list[tuple[bytes, bytes]] = scope.get("headers", [])
+        qs = scope.get("query_string", b"").decode("latin-1")
+
+        record = RequestRecord(
+            method=scope.get("method", "GET"),
+            path=path,
+            query_string=qs,
+            client_host=client_host,
+            request_headers=_asgi_headers_to_dict(
+                raw_headers, self._config.strip_sensitive_headers
+            ),
+        )
+
+        # Capture response start + body chunks, detect if HTML to decide strategy
+        start_message: dict | None = None
+        is_html = False
+        forwarding = False  # True when we're in pass-through mode (non-HTML)
+        body_chunks: list[bytes] = []
+
+        async def capturing_send(message: dict) -> None:
+            nonlocal start_message, is_html, forwarding
+
+            if message["type"] == "http.response.start":
+                start_message = message
+                ct = _get_asgi_header(message.get("headers", []), b"content-type") or b""
+                is_html = any(h.encode() in ct for h in _HTML_CONTENT_TYPES)
+                if not is_html:
+                    # Non-HTML: forward start immediately and switch to pass-through
+                    await send(message)
+                    forwarding = True
+                return
+
+            if message["type"] == "http.response.body":
+                if forwarding:
+                    await send(message)
+                else:
+                    body_chunks.append(message.get("body", b""))
+
+        t0 = time.perf_counter()
+        await self._app(scope, receive, capturing_send)
+        duration_ms = (time.perf_counter() - t0) * 1000
+
+        if start_message is None:
+            return  # degenerate app
+
+        status_code: int = start_message["status"]
+        resp_raw_headers: list[tuple[bytes, bytes]] = start_message.get("headers", [])
+
+        record.status_code = status_code
+        record.duration_ms = duration_ms
+        record.response_headers = _asgi_headers_to_dict(
+            resp_raw_headers, self._config.strip_sensitive_headers
+        )
+
+        # Persist asynchronously (non-blocking)
+        await self._storage.enqueue(record, self._config.max_stored_requests)
+
+        if forwarding:
+            # Already forwarded — nothing more to do
+            return
+
+        # HTML path: inject panel, then forward full response
+        body = b"".join(body_chunks)
+        panel_html = render_panel(record, self._config.debug_route).encode()
+        if b"</body>" in body:
+            body = body.replace(b"</body>", panel_html + b"</body>", 1)
+        else:
+            body += panel_html
+
+        # Rebuild headers with updated Content-Length
+        updated_headers = [(k, v) for k, v in resp_raw_headers if k.lower() != b"content-length"]
+        updated_headers.append((b"content-length", str(len(body)).encode()))
+
+        await send(
+            {
+                "type": "http.response.start",
+                "status": status_code,
+                "headers": updated_headers,
+            }
+        )
+        await send({"type": "http.response.body", "body": body})
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _is_allowed(self, host: str) -> bool:
+        return host in self._config.allowed_hosts
+
+
+# ---------------------------------------------------------------------------
+# Module-level helpers
+# ---------------------------------------------------------------------------
+
+
+def _client_host(scope: Scope) -> str:
+    headers: list[tuple[bytes, bytes]] = scope.get("headers", [])
+    for name, value in headers:
+        if name.lower() == b"x-forwarded-for":
+            return value.decode("latin-1").split(",")[0].strip()
+    client = scope.get("client")
+    return client[0] if client else ""
+
+
+def _asgi_headers_to_dict(headers: list[tuple[bytes, bytes]], strip: list[str]) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for name_bytes, value_bytes in headers:
+        name = name_bytes.decode("latin-1").lower()
+        value = value_bytes.decode("latin-1")
+        result[name] = "[redacted]" if name in strip else value
+    return result
+
+
+def _get_asgi_header(headers: list[tuple[bytes, bytes]], name: bytes) -> bytes | None:
+    name_lower = name.lower()
+    for k, v in headers:
+        if k.lower() == name_lower:
+            return v
+    return None