fastapi-redline 0.2.0a1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,236 @@
1
+ """``install(app, ...)``: wire Redline into a FastAPI/Starlette application."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import contextlib
7
+ import logging
8
+ import re
9
+ from collections.abc import Callable, Mapping, Sequence
10
+ from typing import Any
11
+
12
+ from fastapi import Depends, FastAPI
13
+ from fastapi.params import Depends as DependsParam
14
+
15
+ from redline_core import Recorder, Settings, configure
16
+ from redline_core.access import Access
17
+ from redline_core.api import RedlineAPI
18
+ from redline_core.config import ResolvedConfig, resolve_settings
19
+ from redline_core.explain import ExplainExecutor
20
+ from redline_core.load.control import run_hooks
21
+ from redline_core.storage import SQLiteStore, Store
22
+
23
+ from ._middleware import RedlineMiddleware
24
+ from ._security import redline_guard, refuse_false, scope_info
25
+ from ._serialize import instrument_serialization
26
+ from ._sqlalchemy import (
27
+ EngineLike,
28
+ alias_for,
29
+ build_executor,
30
+ instrument_engine,
31
+ name_engines,
32
+ vendor_of,
33
+ )
34
+ from .router import build_router
35
+ from .suggest import SQLAlchemyFixSuggester
36
+
37
+ __all__ = ["Redline", "install"]
38
+
39
+ logger = logging.getLogger("redline")
40
+
41
+
42
+ def _guard_prefix(routes: Sequence[Any], prefix: str) -> None:
43
+ """Make Redline's routes cost one ``str.startswith`` for every other request.
44
+
45
+ They sit first in the app's route list (so they win over catch-all routes), and
46
+ FastAPI's own matching of an included router walks each of its routes; this skips
47
+ that walk unless the path is under ``prefix``. Each route keeps its type, so
48
+ ``isinstance`` checks in FastAPI (OpenAPI, ``url_path_for``…) see it unchanged.
49
+ """
50
+ from starlette.routing import Match
51
+
52
+ under = prefix + "/"
53
+
54
+ for route in routes:
55
+ original = route.matches
56
+
57
+ def matches(scope: Any, _original: Any = original) -> Any:
58
+ path = scope.get("path", "")
59
+ if path != prefix and not path.startswith(under):
60
+ root = scope.get("root_path", "")
61
+ if not root or not path.startswith(root):
62
+ return Match.NONE, {}
63
+ path = path[len(root) :]
64
+ if path != prefix and not path.startswith(under):
65
+ return Match.NONE, {}
66
+ return _original(scope)
67
+
68
+ try:
69
+ route.matches = matches
70
+ except AttributeError: # pragma: no cover - a route type with __slots__
71
+ pass
72
+
73
+
74
+ class Redline:
75
+ """The handle ``install()`` returns."""
76
+
77
+ def __init__(
78
+ self,
79
+ *,
80
+ app: FastAPI,
81
+ prefix: str,
82
+ settings: Settings,
83
+ recorder: Recorder,
84
+ store: Store,
85
+ suggester: SQLAlchemyFixSuggester,
86
+ config: ResolvedConfig | None = None,
87
+ access: Access | None = None,
88
+ ) -> None:
89
+ self.app = app
90
+ self.prefix = prefix
91
+ self.settings = settings
92
+ self.recorder = recorder
93
+ self.store = store
94
+ self.suggester = suggester
95
+ self.config = config
96
+ self.access = access if access is not None else Access(settings)
97
+ self.engines: dict[str, EngineLike] = {}
98
+ self.loop: asyncio.AbstractEventLoop | None = None
99
+ launcher, stopper = run_hooks(store, settings)
100
+ self.api = RedlineAPI(
101
+ store,
102
+ settings,
103
+ framework="fastapi",
104
+ explain_executor=self._executor_for,
105
+ run_launcher=launcher,
106
+ run_stopper=stopper,
107
+ config=config,
108
+ access=self.access,
109
+ )
110
+
111
+ def add_engine(self, engine: EngineLike, alias: str | None = None) -> str:
112
+ """Instrument another engine; returns its ``db_alias``."""
113
+ if alias is None:
114
+ alias = alias_for(engine, self.engines)
115
+ self.engines[alias] = engine
116
+ if self.settings.enabled:
117
+ instrument_engine(engine, alias)
118
+ return alias
119
+
120
+ def _executor_for(self, alias: str, vendor: str) -> ExplainExecutor | None:
121
+ engine = self.engines.get(alias)
122
+ if engine is None:
123
+ return None
124
+ return build_executor(engine, vendor_of(engine), lambda: self.loop)
125
+
126
+ def close(self) -> None:
127
+ """Flush pending traces and close the store (called on app shutdown)."""
128
+ with contextlib.suppress(Exception):
129
+ self.store.flush(5.0)
130
+ self.store.close()
131
+
132
+
133
+ def install(
134
+ app: FastAPI,
135
+ *,
136
+ engine: Any = None,
137
+ settings: Mapping[str, Any] | Settings | None = None,
138
+ prefix: str | None = None,
139
+ dependencies: Sequence[Callable[..., Any] | DependsParam] | None = None,
140
+ models: Any = None,
141
+ store: Store | None = None,
142
+ ) -> Redline:
143
+ """Install Redline on ``app``.
144
+
145
+ ``engine``
146
+ A sync ``Engine``, an ``AsyncEngine``, a list of them, or ``{alias: engine}``.
147
+ The first of a list is the ``"default"`` db alias (used by EXPLAIN).
148
+ ``settings``
149
+ A ``Settings`` or a dict of settings (case-insensitive keys). They are the top
150
+ layer over ``redline.toml`` / ``[tool.redline]`` and ``REDLINE_*`` variables
151
+ (``redline_core.config``).
152
+ ``prefix``
153
+ Where the UI and API live (default: the ``mount_path`` setting, else
154
+ ``/_redline``). Never recorded.
155
+ ``dependencies``
156
+ FastAPI dependencies protecting the UI and API, e.g.
157
+ ``[Depends(require_admin)]``; giving them implies ``access="framework"`` unless
158
+ the ``access`` setting is set explicitly. When omitted, the ``access`` setting
159
+ decides. ``[]`` is the same as omitting it. Refuse by raising ``HTTPException``
160
+ (answered in the API's error shape); a dependency that *returns* ``False`` is
161
+ refused with 403 too. When ``access`` is not set at all, Redline answers 404
162
+ unless ``app.debug`` is on (then ``local``: loopback clients addressing
163
+ ``localhost``/``127.0.0.1``/``[::1]``).
164
+ ``models``
165
+ Declarative ``Base``/``registry`` (or a list) for fix suggestions; by default every
166
+ registry SQLAlchemy knows about.
167
+ ``store``
168
+ A custom ``Store``; default is the SQLite file at ``storage_path``.
169
+ """
170
+ if getattr(app.state, "redline", None) is not None:
171
+ raise RuntimeError("Redline is already installed on this app.")
172
+ # An empty list is no hook at all: the normal default rules apply, not "framework"
173
+ # with nothing to check.
174
+ resolved = resolve_settings(settings, native_hook=bool(dependencies))
175
+ cfg = resolved.settings
176
+ prefix = prefix if prefix is not None else (cfg.mount_path or "/_redline")
177
+ prefix = "/" + prefix.strip("/")
178
+ if prefix == "/":
179
+ raise ValueError("prefix must be a sub-path such as '/_redline'.")
180
+ own = rf"^{re.escape(prefix)}(/|$)"
181
+ if own not in cfg.ignore_paths:
182
+ cfg = cfg.replace(ignore_paths=[*cfg.ignore_paths, own])
183
+ access = Access(cfg, access_explicit=resolved.access_explicit, debug=lambda: bool(app.debug))
184
+
185
+ store = store if store is not None else SQLiteStore.from_settings(cfg)
186
+ suggester = SQLAlchemyFixSuggester(models, project_root=cfg.project_root)
187
+ recorder = configure(cfg, store, [suggester])
188
+ redline = Redline(
189
+ app=app,
190
+ prefix=prefix,
191
+ settings=cfg,
192
+ recorder=recorder,
193
+ store=store,
194
+ suggester=suggester,
195
+ config=resolved,
196
+ access=access,
197
+ )
198
+ for alias, eng in name_engines(engine).items():
199
+ redline.add_engine(eng, alias)
200
+
201
+ deps: list[Any] = [Depends(redline_guard(access, prefix))]
202
+ if dependencies:
203
+ deps.append(refuse_false(dependencies))
204
+ access.log_startup(prefix, "pass install(app, dependencies=[...])")
205
+
206
+ router = build_router(redline, deps)
207
+ before = len(app.router.routes)
208
+ app.include_router(router, prefix=prefix)
209
+ added = app.router.routes[before:]
210
+ del app.router.routes[before:]
211
+ _guard_prefix(added, prefix)
212
+ app.router.routes[0:0] = added # win over catch-all routes declared earlier
213
+
214
+ if cfg.enabled: # disabled: no middleware and no SQLAlchemy listeners at all
215
+ app.add_middleware(
216
+ RedlineMiddleware,
217
+ recorder=recorder,
218
+ prefix=prefix,
219
+ debug=lambda: bool(app.debug),
220
+ force_ok=lambda scope: access.may_force(scope_info(scope), debug=bool(app.debug)),
221
+ )
222
+ instrument_serialization()
223
+
224
+ original = app.router.lifespan_context
225
+
226
+ @contextlib.asynccontextmanager
227
+ async def lifespan(a: Any):
228
+ async with original(a) as state:
229
+ try:
230
+ yield state
231
+ finally:
232
+ await asyncio.to_thread(redline.close)
233
+
234
+ app.router.lifespan_context = lifespan
235
+ app.state.redline = redline
236
+ return redline
File without changes
@@ -0,0 +1,165 @@
1
+ """The UI + JSON API router mounted under ``prefix``."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ from collections.abc import Callable, Coroutine, Sequence
7
+ from typing import Any
8
+
9
+ from fastapi import APIRouter, HTTPException, Request, Response
10
+ from fastapi.concurrency import run_in_threadpool
11
+ from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, StreamingResponse
12
+ from fastapi.routing import APIRoute
13
+
14
+ from redline_core import stream, ui
15
+ from redline_core.api import RawResponse, own_base_url
16
+ from redline_core.storage import FilterError
17
+
18
+ from ._security import RedlineHTTPError, request_info
19
+
20
+ __all__ = ["RedlineRoute", "build_router", "error_response"]
21
+
22
+ _NO_STORE = {"Cache-Control": "no-store"}
23
+ _IMMUTABLE = {"Cache-Control": "public, max-age=31536000, immutable"}
24
+ _SECURITY = {
25
+ "X-Content-Type-Options": "nosniff",
26
+ "Referrer-Policy": "same-origin",
27
+ "X-Frame-Options": "DENY",
28
+ }
29
+ _CODES = {
30
+ 400: "bad_request",
31
+ 401: "unauthorized",
32
+ 403: "forbidden",
33
+ 404: "not_found",
34
+ 405: "method_not_allowed",
35
+ 429: "too_many_requests",
36
+ }
37
+
38
+
39
+ def error_response(
40
+ status: int,
41
+ code: str,
42
+ message: str,
43
+ headers: dict[str, str] | None = None,
44
+ extra: dict[str, Any] | None = None,
45
+ ) -> JSONResponse:
46
+ """A JSON error in the API's shape (``CONTRACT.md`` §5)."""
47
+ return JSONResponse(
48
+ {"error": {"code": code, "message": message, **(extra or {})}},
49
+ status_code=status,
50
+ headers={**_NO_STORE, **_SECURITY, **(headers or {})},
51
+ )
52
+
53
+
54
+ class RedlineRoute(APIRoute):
55
+ """Renders ``HTTPException`` – from Redline's guards *and* your auth dependencies –
56
+ as ``{"error": {"code", "message"}}`` instead of FastAPI's ``{"detail": ...}``, so
57
+ the UI can show it. Headers such as ``WWW-Authenticate`` are kept."""
58
+
59
+ def get_route_handler(self) -> Callable[[Request], Coroutine[Any, Any, Response]]:
60
+ handler = super().get_route_handler()
61
+
62
+ async def route_handler(request: Request) -> Response:
63
+ try:
64
+ return await handler(request)
65
+ except HTTPException as exc:
66
+ extra: dict[str, Any] = {}
67
+ if isinstance(exc, RedlineHTTPError):
68
+ code, message, extra = exc.code, exc.message, exc.extra
69
+ else:
70
+ code = _CODES.get(exc.status_code, "http_error")
71
+ detail = exc.detail
72
+ message = detail if isinstance(detail, str) else str(detail or code)
73
+ return error_response(
74
+ exc.status_code, code, message, dict(exc.headers or {}), extra
75
+ )
76
+
77
+ return route_handler
78
+
79
+
80
+ def build_router(redline: Any, dependencies: Sequence[Any]) -> APIRouter:
81
+ router = APIRouter(
82
+ dependencies=list(dependencies), include_in_schema=False, route_class=RedlineRoute
83
+ )
84
+
85
+ @router.get("/")
86
+ async def index() -> HTMLResponse:
87
+ return HTMLResponse(ui.index_html(), headers={**_NO_STORE, **_SECURITY})
88
+
89
+ @router.get("/assets/{path:path}")
90
+ async def assets(path: str) -> Response:
91
+ file = ui.asset_path(f"assets/{path}")
92
+ if file is None:
93
+ return error_response(404, "not_found", "No such asset.")
94
+ return FileResponse(
95
+ file, media_type=ui.content_type(file), headers={**_IMMUTABLE, **_SECURITY}
96
+ )
97
+
98
+ @router.get("/api/stream")
99
+ async def live(request: Request) -> Response:
100
+ """Server-sent events: one ``trace`` event per new trace (``CONTRACT.md`` §12)."""
101
+ try:
102
+ since = stream.parse_since(request.query_params)
103
+ except FilterError as exc:
104
+ return error_response(400, "invalid_filter", str(exc))
105
+ return StreamingResponse(
106
+ stream.async_events(
107
+ redline.api,
108
+ since,
109
+ request.is_disconnected,
110
+ after=stream.parse_after(request.query_params, request.headers),
111
+ ),
112
+ media_type=stream.CONTENT_TYPE,
113
+ headers=stream.SSE_HEADERS,
114
+ )
115
+
116
+ @router.api_route(
117
+ "/api/{path:path}",
118
+ methods=["GET", "POST", "DELETE", "PUT", "PATCH"], # the core answers 405 for the last two
119
+ )
120
+ async def api(request: Request, path: str) -> Response:
121
+ redline.loop = asyncio.get_running_loop()
122
+ if path.strip("/") in ("login", "logout"): # the access gate's own endpoints
123
+ body = await request.body() if request.method == "POST" else None
124
+ decision = redline.access.handle(request_info(request, redline.prefix), body)
125
+ if decision is not None:
126
+ return JSONResponse(
127
+ decision.body(),
128
+ status_code=decision.status,
129
+ headers={**_NO_STORE, **_SECURITY, **decision.headers},
130
+ )
131
+ params: dict[str, Any] = {}
132
+ for key, value in request.query_params.multi_items():
133
+ if key in params:
134
+ prev = params[key]
135
+ params[key] = [*prev, value] if isinstance(prev, list) else [prev, value]
136
+ else:
137
+ params[key] = value
138
+ body = await request.body() if request.method == "POST" else None
139
+ # the server's own listening port, never the Host header (CONTRACT.md §18)
140
+ scope = request.scope
141
+ base_url = own_base_url(
142
+ scope.get("scheme"), scope.get("server"), scope.get("root_path", "")
143
+ )
144
+ status, payload = await run_in_threadpool(
145
+ redline.api.dispatch, request.method, f"api/{path}", params, body, base_url=base_url
146
+ )
147
+ if isinstance(payload, RawResponse): # the snapshot page
148
+ return Response(
149
+ payload.body,
150
+ status_code=payload.status,
151
+ media_type=payload.content_type,
152
+ headers={**payload.headers, **_NO_STORE, **_SECURITY},
153
+ )
154
+ return JSONResponse(payload, status_code=status, headers={**_NO_STORE, **_SECURITY})
155
+
156
+ @router.get("/{name}")
157
+ async def top_level(name: str) -> Response:
158
+ file = ui.asset_path(name) # badge.js, favicon.svg etc.
159
+ if file is None:
160
+ return error_response(404, "not_found", "Not found.")
161
+ return FileResponse(
162
+ file, media_type=ui.content_type(file), headers={**_NO_STORE, **_SECURITY}
163
+ )
164
+
165
+ return router
@@ -0,0 +1,5 @@
1
+ """Compatibility shim: the implementation lives in :mod:`redline_core.contrib.sqlalchemy`."""
2
+
3
+ from redline_core.contrib.sqlalchemy.suggest import SQLAlchemyFixSuggester, _ensure_import
4
+
5
+ __all__ = ["SQLAlchemyFixSuggester", "_ensure_import"]
@@ -0,0 +1,267 @@
1
+ Metadata-Version: 2.5
2
+ Name: fastapi-redline
3
+ Version: 0.2.0a1
4
+ Summary: A modern request profiler for FastAPI and SQLAlchemy: span timelines, N+1 detection with fix diffs, one-click EXPLAIN, flamegraphs and a fast web UI.
5
+ Project-URL: Homepage, https://github.com/Pythondeveloper6/redline
6
+ Project-URL: Documentation, https://pythondeveloper6.github.io/redline/fastapi/
7
+ Project-URL: Source, https://github.com/Pythondeveloper6/redline
8
+ Project-URL: Issues, https://github.com/Pythondeveloper6/redline/issues
9
+ Project-URL: Changelog, https://github.com/Pythondeveloper6/redline/blob/main/CHANGELOG.md
10
+ Author-email: Mahmoud Ahmed <pythondeveloper6@gmail.com>
11
+ Maintainer-email: Mahmoud Ahmed <pythondeveloper6@gmail.com>
12
+ License-Expression: MIT
13
+ License-File: LICENSE
14
+ Keywords: explain,fastapi,flamegraph,n+1,performance,profiler,sqlalchemy,starlette
15
+ Classifier: Development Status :: 3 - Alpha
16
+ Classifier: Environment :: Web Environment
17
+ Classifier: Framework :: AsyncIO
18
+ Classifier: Framework :: FastAPI
19
+ Classifier: Intended Audience :: Developers
20
+ Classifier: Operating System :: OS Independent
21
+ Classifier: Programming Language :: Python :: 3
22
+ Classifier: Programming Language :: Python :: 3 :: Only
23
+ Classifier: Programming Language :: Python :: 3.10
24
+ Classifier: Programming Language :: Python :: 3.11
25
+ Classifier: Programming Language :: Python :: 3.12
26
+ Classifier: Programming Language :: Python :: 3.13
27
+ Classifier: Programming Language :: Python :: 3.14
28
+ Classifier: Topic :: Software Development :: Debuggers
29
+ Classifier: Topic :: System :: Monitoring
30
+ Classifier: Typing :: Typed
31
+ Requires-Python: >=3.10
32
+ Requires-Dist: fastapi<1.0,>=0.110
33
+ Requires-Dist: redline-core==0.2.0a1
34
+ Requires-Dist: sqlalchemy[asyncio]<3.0,>=2.0
35
+ Provides-Extra: profile
36
+ Requires-Dist: redline-core[profile]==0.2.0a1; extra == 'profile'
37
+ Description-Content-Type: text/markdown
38
+
39
+ <p align="center">
40
+ <a href="https://pythondeveloper6.github.io/redline/">
41
+ <picture>
42
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Pythondeveloper6/redline/main/docs/assets/logo-dark.svg">
43
+ <img alt="Redline" src="https://raw.githubusercontent.com/Pythondeveloper6/redline/main/docs/assets/logo-light.svg" height="56">
44
+ </picture>
45
+ </a>
46
+ </p>
47
+
48
+ # fastapi-redline
49
+
50
+ The FastAPI + SQLAlchemy adapter for [Redline](https://github.com/Pythondeveloper6/redline#readme): a request profiler and
51
+ backend analyzer. Every request becomes a trace with a span timeline, the SQL it ran, N+1
52
+ and duplicate-query detection with **concrete fix diffs**, one-click `EXPLAIN`, optional
53
+ flamegraphs, and a fast web UI served from your own app.
54
+
55
+ ```python
56
+ from fastapi import FastAPI
57
+ from sqlalchemy.ext.asyncio import create_async_engine
58
+ from fastapi_redline import install
59
+
60
+ app = FastAPI()
61
+ engine = create_async_engine("sqlite+aiosqlite:///app.db")
62
+
63
+ # access="local": localhost only (unset, Redline answers 404 outside debug mode)
64
+ install(app, engine=engine, settings={"access": "local"}) # UI at http://localhost:8000/_redline/
65
+ ```
66
+
67
+ Traces are stored in their own SQLite file (`.redline/redline.db`), never in your database.
68
+
69
+ ## Install
70
+
71
+ ```bash
72
+ pip install \
73
+ "fastapi-redline @ git+https://github.com/Pythondeveloper6/redline#subdirectory=packages/fastapi-redline" \
74
+ "redline-core @ git+https://github.com/Pythondeveloper6/redline#subdirectory=packages/redline-core"
75
+ ```
76
+
77
+ Not on PyPI yet: install from GitHub, naming `redline-core` in the same command (the adapter
78
+ pins it exactly). Docs: <https://pythondeveloper6.github.io/redline/>.
79
+
80
+ Add the extra to the core requirement for flamegraphs:
81
+ `"redline-core[profile] @ git+https://github.com/Pythondeveloper6/redline#subdirectory=packages/redline-core"`.
82
+
83
+ Python 3.10+, FastAPI 0.110+, SQLAlchemy 2.x.
84
+
85
+ ## `install()`
86
+
87
+ ```python
88
+ install(
89
+ app,
90
+ engine=None, # Engine | AsyncEngine | [engines] | {"alias": engine}
91
+ settings=None, # dict | redline_core.Settings
92
+ prefix=None, # default: the mount_path setting, else "/_redline"
93
+ dependencies=None, # auth dependencies for the UI + API (see below)
94
+ models=None, # Base / registry for fix suggestions (default: auto-discover)
95
+ store=None, # custom Store (default: SQLite file at storage_path)
96
+ ) -> Redline
97
+ ```
98
+
99
+ What it does:
100
+
101
+ - configures the recorder and the store, and **flushes and closes the store on shutdown**
102
+ (it wraps your lifespan; an existing `lifespan=` keeps working);
103
+ - adds a pure ASGI middleware (not `BaseHTTPMiddleware`);
104
+ - instruments the engines;
105
+ - mounts the UI and JSON API under `prefix` (ahead of any catch-all route you declared).
106
+
107
+ Call it after your app is built, before it starts. `settings` takes any
108
+ [Redline setting](../redline-core/README.md) with case-insensitive keys:
109
+
110
+ ```python
111
+ install(app, engine=engine, settings={
112
+ "sample_rate": 0.1, # keep 10% of requests ...
113
+ "always_keep_slower_than_ms": 300, # ... plus every slow one and every error
114
+ "slow_query_ms": 50,
115
+ })
116
+ ```
117
+
118
+ ### Multiple engines
119
+
120
+ The first engine of a list is the `"default"` db alias; others are named after their
121
+ database file, or pass a dict. The alias is stored on each query so EXPLAIN runs on the right
122
+ engine.
123
+
124
+ ```python
125
+ install(app, engine=[async_engine, sync_engine])
126
+ install(app, engine={"main": main_engine, "analytics": analytics_engine})
127
+ redline = install(app)
128
+ redline.add_engine(late_engine) # instrument an engine created later
129
+ ```
130
+
131
+ ### SQLModel
132
+
133
+ Nothing to do: SQLModel tables live in a regular SQLAlchemy registry, which the fix
134
+ suggester discovers (or pass `models=SQLModel`).
135
+
136
+ ## What is recorded
137
+
138
+ - **Request / response**: method, path, route template (`/orders/{order_id}`), endpoint
139
+ dotted name, status, headers, query string and body. Secrets are redacted by the core
140
+ (`Authorization`, cookies, `password`/`token`/`card` keys...).
141
+ - **Bodies are never consumed or buffered unboundedly.** The request body is copied as the
142
+ app reads it; response bodies, including streams, are kept only up to `max_body_bytes`.
143
+ - **SQL** through `before/after_cursor_execute`: statement, bound params (redacted),
144
+ duration, rowcount, vendor, executemany, `db_alias`, and the project line that issued the
145
+ query, also through `AsyncSession` (the greenlet boundary is bridged).
146
+ - **Unhandled exceptions** are recorded and re-raised untouched.
147
+ - Spans from `def` endpoints running in Starlette's threadpool attach to the right request
148
+ (context is copied to the worker thread; tested under concurrency).
149
+ - The trace is finished when the last response chunk is sent, so background tasks do not
150
+ inflate latency. Work that starts a bare `threading.Thread` is not attributed to any
151
+ request.
152
+ - Your own spans: `with redline_core.span("pricing.compute"): ...` (also `async with` and
153
+ as a decorator).
154
+ - `X-Redline-Run: <id>;step=<n>` becomes tags (used by the load tester).
155
+
156
+ ### Outbound HTTP (httpx)
157
+
158
+ Opt-in, once at startup:
159
+
160
+ ```python
161
+ from fastapi_redline import instrument_httpx
162
+
163
+ instrument_httpx() # every httpx.Client / AsyncClient call becomes an http_out span
164
+ ```
165
+
166
+ URLs are redacted (`?api_key=...` is masked). Use `uninstrument_httpx()` to undo it.
167
+
168
+ ### Profiling
169
+
170
+ Flamegraphs are opt-in per request: add `?_redline=profile` or the header
171
+ `X-Redline-Profile: 1` (needs the `[profile]` extra). They are recorded with pyinstrument in
172
+ async mode, so concurrent requests do not pollute each other.
173
+
174
+ ## Fix suggestions
175
+
176
+ For an N+1, `SQLAlchemyFixSuggester` maps the repeated query back to your models and tells
177
+ you how to eager-load it:
178
+
179
+ | Repeated query | Suggestion |
180
+ |---|---|
181
+ | child table filtered by its foreign key | `selectinload(Parent.children)` |
182
+ | parent looked up by primary key, once per row | `joinedload(Child.parent)` |
183
+ | association (secondary) table filtered by the parent | `selectinload(Parent.tags)` |
184
+
185
+ It then walks the call stack to find the `select(Parent)` or `session.query(Parent)` in
186
+ your source and produces a real unified diff:
187
+
188
+ ```diff
189
+ - orders = (await session.scalars(select(Order).order_by(Order.id).limit(30))).all()
190
+ + orders = (await session.scalars(select(Order).order_by(Order.id).limit(30).options(selectinload(Order.items)))).all()
191
+ ```
192
+
193
+ plus the `from sqlalchemy.orm import selectinload` line when it is missing. When the
194
+ statement cannot be located (it lives in another module, or is built dynamically) you get
195
+ the one-line code hint with lower confidence instead. Both the lazy-load form
196
+ (`order.items`) and explicit per-row queries are recognised.
197
+
198
+ ## Access control
199
+
200
+ The UI exposes your SQL, request bodies and EXPLAIN, so treat it like an admin tool.
201
+
202
+ **Default.** With no `dependencies`, the `access` setting decides (default `local`, served only in debug mode until you set `access`): only loopback clients (127.0.0.0/8, `::1`; unix sockets only with `trust_unix_socket`)
203
+ that address the server by a loopback name (`Host: localhost`, `127.0.0.1`, `[::1]`, any port;
204
+ this blocks DNS rebinding)
205
+ are served and a warning is logged at startup. Refusals, and `HTTPException`s from your own
206
+ dependencies, are JSON `{"error": {"code": "forbidden" | "unauthorized" | ..., "message"}}`.
207
+ Add other host names with the `allowed_hosts` setting. Passing `dependencies=` implies
208
+ `access="framework"`. A loopback peer sending `X-Forwarded-For` without being in
209
+ `trusted_proxies` is refused; behind a reverse proxy use `access="token"` and
210
+ `trusted_proxies`. Tokens, basic auth, `allowed_ips` and `read_only` are described in the
211
+ [access control docs](https://pythondeveloper6.github.io/redline/access-control/).
212
+
213
+ **Your existing auth dependency:**
214
+
215
+ ```python
216
+ from fastapi import Depends
217
+
218
+ install(app, engine=engine, dependencies=[Depends(require_admin_user)])
219
+ ```
220
+
221
+ **HTTP Basic:**
222
+
223
+ ```python
224
+ import secrets
225
+ from fastapi import Depends, HTTPException
226
+ from fastapi.security import HTTPBasic, HTTPBasicCredentials
227
+
228
+ basic = HTTPBasic()
229
+
230
+ def redline_auth(creds: HTTPBasicCredentials = Depends(basic)) -> None:
231
+ ok = secrets.compare_digest(creds.username, "admin") and secrets.compare_digest(
232
+ creds.password, os.environ["REDLINE_PASSWORD"]
233
+ )
234
+ if not ok:
235
+ raise HTTPException(401, headers={"WWW-Authenticate": "Basic"})
236
+
237
+ install(app, engine=engine, dependencies=[Depends(redline_auth)])
238
+ ```
239
+
240
+ (`dependencies=[]` is the same as passing none. A dependency that returns `False` is refused with 403; raising `HTTPException` is the normal way.)
241
+
242
+ **CSRF.** The mutating endpoints (`DELETE` traces, `POST explain`) reject browser requests
243
+ whose `Origin` does not match the request host, `Origin: null`, and
244
+ `Sec-Fetch-Site: cross-site`. Browsers always send `Origin` on those methods, so another
245
+ website cannot drive your Redline through a logged-in browser. Non-browser clients (curl,
246
+ scripts) send no `Origin` and are only subject to your auth dependencies.
247
+
248
+ ## EXPLAIN
249
+
250
+ `POST /_redline/api/explain` runs `EXPLAIN` for a recorded SELECT on the engine it came
251
+ from (matched by `db_alias`) inside a transaction that is always rolled back (and
252
+ `READ ONLY` on PostgreSQL). The captured SQL is in the driver's paramstyle and goes
253
+ through `exec_driver_sql`. Async engines run on the application's event loop. `EXPLAIN
254
+ ANALYZE` executes the query, so it is off unless `explain_analyze=True`.
255
+
256
+ ## Development
257
+
258
+ ```bash
259
+ uv sync --all-packages
260
+ cd packages/fastapi-redline && uv run pytest
261
+ ```
262
+
263
+ A runnable demo with deliberately bad endpoints lives in [`examples/fastapi`](https://github.com/Pythondeveloper6/redline/blob/main/examples/fastapi).
264
+
265
+ ## License
266
+
267
+ MIT
@@ -0,0 +1,14 @@
1
+ fastapi_redline/__init__.py,sha256=0xj6hdidt7az8J1msC-Zm7VT5pIrlMrHXUqbzuqxT-E,997
2
+ fastapi_redline/_httpx.py,sha256=vd2nVdA4K1khx0KWjJC-ojmG8vk_5BTCzJ1YckP_zvk,220
3
+ fastapi_redline/_middleware.py,sha256=kzj_Lluoj51QcqVP3aeSQt9xV1EyVTe5jPseS0B4pww,11065
4
+ fastapi_redline/_security.py,sha256=wyAb8oHQpdDX7s4KvoshW4Qz0CAzbyoBvbykuL2jvdo,8798
5
+ fastapi_redline/_serialize.py,sha256=dR-cqTN1XW-JrQ4Gu3ETx3pj0KXHNmsGHbfuHdhOJ48,3997
6
+ fastapi_redline/_sqlalchemy.py,sha256=zho_YxZqGNZpDChZmnAxb_tIHR56zAHbLj_UlHHAPLo,384
7
+ fastapi_redline/integration.py,sha256=Kbc92cRB8ipLQ9pZMp2oP5GuYUDoe6qq1dSQupwCLXw,8678
8
+ fastapi_redline/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
9
+ fastapi_redline/router.py,sha256=Qp7EKm8Tuwd16ZwIgmpIBU_vUfE6SzK-pKw-K_ujYZI,6395
10
+ fastapi_redline/suggest.py,sha256=XNw_skhJ8ww-y080vUhCoEGRG02hvzK1h6DC-9M_MlY,242
11
+ fastapi_redline-0.2.0a1.dist-info/METADATA,sha256=hvvIk5LwbzZCoXHXA9kA8eBkg1OtALi9nouKoujrKzI,11516
12
+ fastapi_redline-0.2.0a1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
13
+ fastapi_redline-0.2.0a1.dist-info/licenses/LICENSE,sha256=iNRgkNhv4ywVj_7s8Rd8Vq6wO10lRkZMX9KAsNwivKU,1070
14
+ fastapi_redline-0.2.0a1.dist-info/RECORD,,