fastapi-redline 0.2.0a1__py3-none-any.whl

fastapi_redline/__init__.py

@@ -0,0 +1,38 @@
+"""fastapi-redline: the FastAPI + SQLAlchemy adapter for Redline.
+
+::
+
+    from fastapi import FastAPI
+    from sqlalchemy.ext.asyncio import create_async_engine
+    from fastapi_redline import install
+
+    app = FastAPI()
+    engine = create_async_engine("sqlite+aiosqlite:///app.db")
+    install(app, engine=engine)          # UI at /_redline/
+"""
+
+from __future__ import annotations
+
+from ._httpx import instrument_httpx, uninstrument_httpx
+from ._middleware import RedlineMiddleware
+from ._security import RedlineHTTPError, csrf_guard, local_only, loopback_guard
+from ._sqlalchemy import instrument_engine
+from .integration import Redline, install
+from .suggest import SQLAlchemyFixSuggester
+
+__version__ = "0.2.0a1"
+
+__all__ = [
+    "Redline",
+    "RedlineHTTPError",
+    "RedlineMiddleware",
+    "SQLAlchemyFixSuggester",
+    "__version__",
+    "csrf_guard",
+    "install",
+    "instrument_engine",
+    "instrument_httpx",
+    "local_only",
+    "loopback_guard",
+    "uninstrument_httpx",
+]

fastapi_redline/_httpx.py

@@ -0,0 +1,5 @@
+"""Compatibility shim: the implementation lives in :mod:`redline_core.contrib.httpx`."""
+
+from redline_core.contrib.httpx import instrument_httpx, uninstrument_httpx
+
+__all__ = ["instrument_httpx", "uninstrument_httpx"]

fastapi_redline/_middleware.py

@@ -0,0 +1,264 @@
+"""The pure-ASGI recording middleware.
+
+Not ``BaseHTTPMiddleware``: that wraps the app in extra tasks, breaks contextvars
+propagation for sync endpoints and buffers streaming responses. This one:
+
+* *tees* the request body as the app reads it (the app sees the untouched ``receive``);
+* wraps ``send`` to capture status, headers and a size-capped copy of the response body –
+  a stream is never buffered beyond ``max_body_bytes``;
+* finishes the trace right after the last body chunk is sent, so background tasks do not
+  count towards latency;
+* resolves the route template (``/orders/{id}``) from ``scope["route"]`` once routing ran;
+* adds ``Server-Timing`` to the response start (``server_timing`` setting) and injects the
+  floating badge into small, single-message HTML pages (``badge`` setting): the start
+  message is held back only when it announces a 2xx ``text/html`` body that is not
+  compressed, allowed by the CSP and at most ``BADGE_MAX_BYTES`` long; a body that turns
+  out to be streamed (``more_body``) is passed through untouched.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from typing import Any
+
+from redline_core import Recorder, get_recorder, ui
+from redline_core.contrib.asgi import track_request
+from redline_core.sampling import profile_requested
+
+__all__ = ["RedlineMiddleware"]
+
+_JSON_PAIR = re.compile(r'("(?:[^"\\]|\\.)*")(\s*:\s*)("(?:[^"\\]|\\.)*"|[^,}\]\s]+)')
+
+
+def _wants_profile(headers: list[tuple[bytes, bytes]], query: bytes) -> bool:
+    header = next((v for k, v in headers if k == b"x-redline-profile"), None)
+    return profile_requested(query, header)
+
+
+def _header(headers: list[tuple[bytes, bytes]], name: bytes) -> str | None:
+    for key, value in headers:
+        if key.lower() == name:
+            return value.decode("latin-1")
+    return None
+
+
+def _endpoint_name(endpoint: Any) -> str | None:
+    if endpoint is None:
+        return None
+    target = getattr(endpoint, "func", endpoint)  # functools.partial
+    module = getattr(target, "__module__", None)
+    name = getattr(target, "__qualname__", None) or getattr(target, "__name__", None)
+    if name is None:
+        name = type(target).__qualname__
+        module = type(target).__module__
+    return f"{module}.{name}" if module else name
+
+
+class _Capture:
+    """A byte buffer that keeps at most ``limit + 1`` bytes (the +1 lets core flag truncation)."""
+
+    __slots__ = ("buf", "limit", "total")
+
+    def __init__(self, limit: int) -> None:
+        self.buf = bytearray()
+        self.limit = limit
+        self.total = 0
+
+    def add(self, chunk: bytes) -> None:
+        self.total += len(chunk)
+        room = self.limit + 1 - len(self.buf)
+        if room > 0 and chunk:
+            self.buf += chunk[:room]
+
+    def value(self, recorder: Recorder, content_type: str | None) -> bytes:
+        data = bytes(self.buf)
+        if len(data) > self.limit and content_type and "json" in content_type:
+            # A cut JSON document cannot be parsed by core's key-based masking; mask the
+            # visible "key": value pairs so a secret in the first bytes never leaks.
+            redactor = recorder.redactor
+            text = data.decode("utf-8", errors="ignore")
+            text = _JSON_PAIR.sub(
+                lambda m: (
+                    f'{m.group(1)}{m.group(2)}"[redacted]"'
+                    if redactor.is_secret_key(m.group(1)[1:-1])
+                    else m.group(0)
+                ),
+                text,
+            )
+            data = text.encode("utf-8")
+        return data
+
+
+def _with_header(headers: list[tuple[bytes, bytes]], name: bytes, value: str) -> None:
+    """Append ``value`` to header ``name`` (comma-joined) or add it, in place."""
+    if not value:
+        return
+    for i, (key, old) in enumerate(headers):
+        if key.lower() == name:
+            headers[i] = (key, old + b", " + value.encode("latin-1"))
+            return
+    headers.append((name, value.encode("latin-1")))
+
+
+def _badge_candidate(status: int, headers: list[tuple[bytes, bytes]]) -> bool:
+    if not ui.badge_allowed(
+        status,
+        _header(headers, b"content-type"),
+        content_encoding=_header(headers, b"content-encoding"),
+        csp=", ".join(
+            v.decode("latin-1") for k, v in headers if k.lower() == b"content-security-policy"
+        ),
+    ):
+        return False
+    if _header(headers, b"content-disposition") or _header(headers, b"last-modified"):
+        return False  # a file (FileResponse / StaticFiles / download), not a rendered page
+    length = _header(headers, b"content-length")
+    if length is None:
+        return True  # decided on the first body message (``more_body``)
+    try:
+        return int(length) <= ui.BADGE_MAX_BYTES
+    except ValueError:
+        return False
+
+
+class RedlineMiddleware:
+    def __init__(
+        self,
+        app: Any,
+        recorder: Recorder | None = None,
+        prefix: str = "/_redline",
+        debug: Callable[[], bool] | None = None,
+        force_ok: Callable[[Any], bool] | None = None,
+    ) -> None:
+        self.app = app
+        self.recorder = recorder
+        self.prefix = prefix
+        self.debug = debug or (lambda: False)
+        #: ``force_ok(scope)``: may this request force profiling (``X-Redline-Profile``,
+        #: ``?_redline=profile``)? Called only when such a flag is present.
+        self.force_ok = force_ok or (lambda scope: self.debug())
+
+    async def __call__(self, scope: Any, receive: Any, send: Any) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+        recorder = self.recorder or get_recorder()
+        path: str = scope["path"]
+        if not recorder.should_record(path):
+            await self.app(scope, receive, send)
+            return
+
+        settings = recorder.settings
+        headers = list(scope.get("headers") or [])
+        query = scope.get("query_string", b"")
+        client = scope.get("client")
+        builder = recorder.start_trace(
+            framework="fastapi",
+            method=scope["method"],
+            path=path,
+            headers=headers,
+            query=query,
+            client=client[0] if client else None,
+            profile_requested=_wants_profile(headers, query) and self.force_ok(scope),
+        )
+        root_path = scope.get("root_path", "")
+        limit = settings.max_body_bytes
+        req = _Capture(limit) if settings.capture_request_body else None
+        res = _Capture(limit)
+        capture_res = settings.capture_response_body
+        state: dict[str, Any] = {"status": None, "headers": [], "done": False}
+        server_timing = builder.active and ui.server_timing_enabled(settings, self.debug())
+        badge = builder.active and ui.badge_enabled(settings, self.debug())
+        held: list[Any] = []  # a response start held back for badge injection
+
+        def finalize(status: int | None = None, error: BaseException | None = None) -> None:
+            if state["done"]:
+                return
+            state["done"] = True
+            if req is not None:
+                builder.req_body = req.value(recorder, _header(headers, b"content-type"))
+            route = scope.get("route")
+            route_path = getattr(route, "path", None)
+            if route_path is not None:
+                mounted = scope.get("root_path", "")
+                if mounted != root_path and mounted.startswith(root_path):
+                    route_path = mounted[len(root_path) :] + route_path
+            resp_headers = state["headers"]
+            body = None
+            if capture_res and _header(resp_headers, b"content-encoding") is None:
+                body = res.value(recorder, _header(resp_headers, b"content-type"))
+            try:
+                recorder.finish_trace(
+                    builder,
+                    status=status or state["status"] or 500,
+                    headers=resp_headers,
+                    body=body,
+                    size=res.total,
+                    route=route_path,
+                    view=_endpoint_name(scope.get("endpoint")),
+                    error=error,
+                    path_params=scope.get("path_params") or None,
+                )
+            except Exception:  # pragma: no cover - recording must never break a request
+                import logging
+
+                logging.getLogger("redline").exception("Redline failed to finish a trace")
+
+        async def recv() -> Any:
+            message = await receive()
+            if req is not None and message["type"] == "http.request":
+                chunk = message.get("body", b"")
+                if chunk:
+                    req.add(chunk)
+            return message
+
+        def inject(start: Any, message: Any, chunk: bytes) -> tuple[Any, Any]:
+            summary = ui.badge_summary(builder, start["status"])
+            snippet = ui.badge_snippet(builder.id, root_path + self.prefix, summary)
+            body = ui.inject_badge(chunk, snippet)
+            if body is None:
+                return start, message
+            out = [(k, v) for k, v in start["headers"] if k.lower() != b"content-length"]
+            if len(out) != len(start["headers"]):
+                out.append((b"content-length", str(len(body)).encode("latin-1")))
+            return {**start, "headers": out}, {**message, "body": body}
+
+        async def send_wrapper(message: Any) -> None:
+            kind = message["type"]
+            if kind == "http.response.start":
+                state["status"] = message["status"]
+                state["headers"] = list(message.get("headers") or [])
+                if server_timing:
+                    out = list(state["headers"])
+                    _with_header(out, b"server-timing", builder.server_timing())
+                    message = {**message, "headers": out}
+                if badge and _badge_candidate(message["status"], state["headers"]):
+                    held.append(message)
+                    return
+            elif kind == "http.response.body":
+                chunk = message.get("body", b"")
+                if capture_res:
+                    res.add(chunk)
+                else:
+                    res.total += len(chunk)
+                if held:
+                    start = held.pop()
+                    if not message.get("more_body", False) and len(chunk) <= ui.BADGE_MAX_BYTES:
+                        start, message = inject(start, message, chunk)
+                    await send(start)
+            await send(message)
+            if kind == "http.response.body" and not message.get("more_body", False):
+                finalize()
+
+        try:
+            async with track_request(builder):  # event-loop lag monitor (blocking spans)
+                await self.app(scope, recv, send_wrapper)
+        except Exception as exc:
+            finalize(error=exc)
+            raise
+        except BaseException:  # cancellation: the client went away
+            finalize(status=state["status"] or 499)
+            raise
+        else:
+            finalize()

fastapi_redline/_security.py

@@ -0,0 +1,228 @@
+"""Access control for the Redline UI and API.
+
+Every Redline request goes through :func:`redline_guard`, which asks the core access gate
+(:class:`redline_core.access.Access`, ``CONTRACT.md`` §18) – the ``access`` setting picks
+the policy (``local`` by default; ``token``, ``basic``, ``framework``, ``custom``,
+``open``). Passing ``install(dependencies=[...])`` implies ``access="framework"``: your
+dependencies decide, and FastAPI runs them as usual.
+
+The helpers below are kept for explicit use as dependencies:
+
+* :func:`local_only` / :func:`loopback_guard` – loopback clients addressing a loopback
+  ``Host`` (against DNS rebinding);
+* :func:`csrf_guard` – the Origin / ``Sec-Fetch-Site`` check (the gate applies it anyway);
+* :class:`RedlineHTTPError` – what the guards raise; the Redline router renders it (and
+  any ``HTTPException`` from your own auth dependencies) in the API's error shape,
+  ``{"error": {"code": ..., "message": ...}}``.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable, Iterable, Sequence
+from typing import Any
+from urllib.parse import urlsplit
+
+from fastapi import Depends, HTTPException, Request
+from fastapi.params import Depends as DependsParam
+
+from redline_core.access import (
+    LOCAL_HOST_NAMES,
+    Access,
+    Decision,
+    RequestInfo,
+    is_local_host,
+    is_loopback,
+)
+
+__all__ = [
+    "LOCAL_HOST_NAMES",
+    "RedlineHTTPError",
+    "csrf_guard",
+    "is_local_host_header",
+    "local_only",
+    "loopback_guard",
+    "redline_guard",
+    "refuse_false",
+    "request_info",
+]
+
+_SAFE = {"GET", "HEAD", "OPTIONS"}
+_TESTCLIENT = "testclient"  # Starlette's TestClient reports this as the client address
+
+
+class RedlineHTTPError(HTTPException):
+    """An ``HTTPException`` with a machine-readable ``code`` for the error shape."""
+
+    def __init__(
+        self,
+        status_code: int,
+        code: str,
+        message: str,
+        headers: dict[str, str] | None = None,
+        extra: dict | None = None,
+    ) -> None:
+        super().__init__(status_code=status_code, detail=message, headers=headers)
+        self.code = code
+        self.message = message
+        self.extra = dict(extra or {})
+
+    @classmethod
+    def from_decision(cls, decision: Decision) -> RedlineHTTPError:
+        return cls(
+            decision.status,
+            decision.code,
+            decision.message,
+            dict(decision.headers) or None,
+            dict(decision.extra),
+        )
+
+
+def _client_ip(request: Request) -> str | None:
+    host = request.client.host if request.client else None
+    return "127.0.0.1" if host == _TESTCLIENT else host
+
+
+def _is_loopback(host: str | None) -> bool:
+    """Whether a *client address* is loopback (``None`` is a unix socket)."""
+    return host == _TESTCLIENT or is_loopback(host)
+
+
+def is_local_host_header(header: str | None, extra: Iterable[str] = ()) -> bool:
+    """Whether a ``Host`` header names this machine's loopback interface (see
+    :func:`redline_core.access.is_local_host`)."""
+    return is_local_host(header, extra)
+
+
+def scope_info(scope: Any) -> RequestInfo:
+    """A :class:`RequestInfo` from a raw ASGI scope (for the profile-flag check)."""
+    client = scope.get("client")
+    host = client[0] if client else None
+    return RequestInfo.build(
+        method=scope.get("method", "GET"),
+        path="",
+        client_ip="127.0.0.1" if host == _TESTCLIENT else host,
+        headers=scope.get("headers") or [],
+        scheme=scope.get("scheme", "http"),
+        mount=scope.get("root_path", "") or "/",
+    )
+
+
+def request_info(request: Request, mount: str) -> RequestInfo:
+    """The framework-neutral description of a request under ``mount`` (e.g. ``/_redline``)."""
+    root = request.scope.get("root_path", "") or ""
+    path = request.scope.get("path", "")
+    if root and path.startswith(root + "/"):
+        path = path[len(root) :]
+    rel = path[len(mount) :] if path.startswith(mount) else path
+    return RequestInfo.build(
+        method=request.method,
+        path=rel.lstrip("/"),
+        client_ip=_client_ip(request),
+        headers=request.headers.items(),
+        scheme=request.url.scheme,
+        mount=f"{root.rstrip('/')}{mount}",
+    )
+
+
+def redline_guard(access: Access, mount: str) -> Callable[[Request], Awaitable[None]]:
+    """The dependency every Redline route runs first: the core access check."""
+
+    async def guard(request: Request) -> None:
+        decision = access.check(request_info(request, mount), framework_ok=lambda: True)
+        if not decision.allowed:
+            raise RedlineHTTPError.from_decision(decision)
+
+    guard.__name__ = "redline_guard"
+    return guard
+
+
+def refuse_false(dependencies: Sequence[Any]) -> Any:
+    """One dependency that runs the user's ``dependencies`` and refuses with 403 when any
+    of them *returns* ``False``.
+
+    Raising ``HTTPException`` is the normal way for a FastAPI dependency to refuse; this
+    catches the easy mistake of a check that returns a bool (``return user.is_admin``),
+    which FastAPI would otherwise ignore – letting everyone in. Only ``False`` itself
+    refuses: ``None`` (no return value) and other values pass. The dependencies are
+    resolved by FastAPI as usual (sub-dependencies, ``yield``, ``Security`` scopes).
+    """
+    params = [
+        inspect.Parameter(
+            f"_redline_dep_{i}",
+            inspect.Parameter.KEYWORD_ONLY,
+            default=d if isinstance(d, DependsParam) else Depends(d),
+        )
+        for i, d in enumerate(dependencies)
+    ]
+
+    async def check(**results: Any) -> None:
+        if any(value is False for value in results.values()):
+            raise RedlineHTTPError(
+                403, "forbidden", "Redline refused this request (a dependency returned False)."
+            )
+
+    check.__signature__ = inspect.Signature(params)  # type: ignore[attr-defined]
+    check.__name__ = "redline_dependencies"
+    return Depends(check)
+
+
+def loopback_guard(*, allowed_hosts: Iterable[str] = ()) -> Callable[[Request], Awaitable[None]]:
+    """A dependency allowing only loopback clients that address a loopback ``Host``.
+
+    Checking the ``Host`` header defeats **DNS rebinding**: a web page on
+    ``evil.example`` that re-points its own DNS name at ``127.0.0.1`` can make your
+    browser send requests to the local server, but they carry ``Host: evil.example``.
+    ``allowed_hosts`` adds names (e.g. a ``/etc/hosts`` alias such as ``"devbox"``);
+    ports are ignored. (The ``access="local"`` policy does the same with the
+    ``allowed_hosts`` setting.)
+    """
+    extra = frozenset(h.strip().lower() for h in allowed_hosts)
+
+    async def guard(request: Request) -> None:
+        client = request.client.host if request.client else None
+        if not _is_loopback(client):
+            raise RedlineHTTPError(
+                403,
+                "forbidden",
+                "Redline is only reachable from localhost. Pass "
+                "install(app, dependencies=[Depends(your_auth)]) to expose it.",
+            )
+        if not is_local_host(request.headers.get("host"), extra):
+            raise RedlineHTTPError(
+                403,
+                "forbidden",
+                "Redline only answers requests addressed to localhost, 127.0.0.1 or [::1] "
+                "(this request's Host header names another site, as in a DNS-rebinding "
+                "attack). Use loopback_guard(allowed_hosts=[...]) to allow another name.",
+            )
+
+    return guard
+
+
+#: Loopback clients, loopback ``Host`` names (what ``access="local"`` enforces).
+local_only = loopback_guard()
+local_only.__name__ = "local_only"
+local_only.__doc__ = "Allow only loopback clients addressing a loopback Host."
+
+
+async def csrf_guard(request: Request) -> None:
+    """Reject cross-site requests to the mutating endpoints.
+
+    Browsers attach an ``Origin`` header to every cross-origin and every same-origin
+    non-GET request, so it must match the host the request was addressed to. Requests
+    without ``Origin`` (curl, scripts) cannot be forged by a web page and are allowed.
+    ``Sec-Fetch-Site: cross-site`` is rejected too. The access gate applies the same rule
+    to every Redline request.
+    """
+    if request.method in _SAFE:
+        return
+    if request.headers.get("sec-fetch-site") in ("cross-site", "same-site"):
+        raise RedlineHTTPError(403, "csrf_failed", "Cross-site request blocked.")
+    origin = request.headers.get("origin")
+    if origin is None:
+        return
+    allowed = {h.strip().lower() for h in (request.headers.get("host"),) if h}
+    netloc = urlsplit(origin).netloc.lower() if origin != "null" else ""
+    if netloc not in allowed:
+        raise RedlineHTTPError(403, "csrf_failed", "Cross-origin request blocked.")

fastapi_redline/_serialize.py

@@ -0,0 +1,108 @@
+"""Response serialization as ``serializer`` spans.
+
+FastAPI validates and serializes the endpoint's return value in
+``fastapi.routing.serialize_response`` (response-model validation + Pydantic dump, or
+``jsonable_encoder`` without a response model). That one coroutine is wrapped: the span
+covers all of it, nested models included. The wrapper is looked up as a module global by
+FastAPI's request handler, so patching the attribute is enough; it is defensive about the
+signature (keyword-only today, but only ``field``/``response_content`` are read, by name)
+and costs one ``ContextVar.get()`` outside a traced request.
+
+The span's callsite (a stack walk) is captured only when the serialization is over
+``slow_serializer_ms``, i.e. when a ``slow_serializer`` issue can point at it: the endpoint
+has already returned when FastAPI serializes, so a fast span's stack says nothing useful.
+"""
+
+from __future__ import annotations
+
+import functools
+import time
+from typing import Any, get_args, get_origin
+
+from redline_core import record_span
+from redline_core.recorder import _trace
+
+__all__ = ["instrument_serialization", "uninstrument_serialization"]
+
+_perf = time.perf_counter
+_originals: dict[str, Any] = {}
+_SEQUENCES = (list, tuple, set, frozenset)
+
+
+def _type_name(annotation: Any) -> str | None:
+    """``Order`` for ``Order``, ``list[Order]``, ``Optional[Order]``…"""
+    if annotation is None:
+        return None
+    args = [a for a in get_args(annotation) if a is not type(None)]
+    if get_origin(annotation) is not None and args:
+        return _type_name(args[0])
+    return getattr(annotation, "__name__", None)
+
+
+def _describe(field: Any, content: Any) -> tuple[str, int | None]:
+    """``(model name, item count or None)`` for one serialization."""
+    items = len(content) if isinstance(content, _SEQUENCES) else None
+    annotation = getattr(field, "type_", None)
+    if annotation is None:
+        info = getattr(field, "field_info", None)
+        annotation = getattr(info, "annotation", None)
+    name = _type_name(annotation)
+    if name is None:
+        sample = content[0] if items else content
+        name = type(sample).__name__ if items != 0 else "list"
+    return name, items
+
+
+def instrument_serialization() -> bool:
+    """Patch ``fastapi.routing.serialize_response``; ``False`` if it is not there. Idempotent."""
+    try:
+        from fastapi import routing
+    except ImportError:  # pragma: no cover - fastapi is this package's dependency
+        return False
+    original = getattr(routing, "serialize_response", None)
+    if original is None:
+        return False
+    if _originals:
+        return True
+    _originals["serialize_response"] = original
+
+    @functools.wraps(original)
+    async def serialize_response(*args: Any, **kwargs: Any) -> Any:
+        builder = _trace.get()
+        if builder is None:
+            return await original(*args, **kwargs)
+        start = _perf()
+        try:
+            return await original(*args, **kwargs)
+        finally:
+            duration = _perf() - start
+            try:
+                name, items = _describe(kwargs.get("field"), kwargs.get("response_content"))
+            except Exception:
+                name, items = "response", None
+            slow = duration * 1000.0 >= builder.recorder.settings.slow_serializer_ms
+            record_span(
+                "serializer",
+                f"serialize {name}",
+                start,
+                duration,
+                {
+                    "library": "pydantic",
+                    "serializer": name,
+                    "items": items,
+                    "many": items is not None,
+                },
+                slow,
+            )
+
+    routing.serialize_response = serialize_response
+    return True
+
+
+def uninstrument_serialization() -> None:
+    """Undo :func:`instrument_serialization`."""
+    if not _originals:
+        return
+    from fastapi import routing
+
+    routing.serialize_response = _originals.pop("serialize_response")

fastapi_redline/_sqlalchemy.py

@@ -0,0 +1,19 @@
+"""Compatibility shim: the implementation lives in :mod:`redline_core.contrib.sqlalchemy`."""
+
+from redline_core.contrib.sqlalchemy import (
+    EngineLike,
+    alias_for,
+    build_executor,
+    instrument_engine,
+    name_engines,
+    vendor_of,
+)
+
+__all__ = [
+    "EngineLike",
+    "alias_for",
+    "build_executor",
+    "instrument_engine",
+    "name_engines",
+    "vendor_of",
+]