create-caspian-app 1.6.4 → 1.8.1

package/dist/main.py

@@ -41,7 +41,15 @@ from dotenv import load_dotenv
 import uvicorn
 from casp.state_manager import StateManager
 from casp.cache_handler import CacheHandler
-from casp.caspian_config import get_files_index, get_config
+from casp.caspian_config import RouteEntry, get_files_index, get_config, route_priority
+from casp.api_routes import (
+    csrf_required,
+    discover_handlers,
+    select_handler,
+    to_response,
+    verify_csrf,
+)
+from casp.errors import HttpError
 from casp.auth import (
     Auth,
     GoogleProvider,
@@ -49,6 +57,43 @@ from casp.auth import (
     configure_auth,
 )
 from casp.rpc import register_rpc_routes, rpc_limiter
+from casp.errors import (
+    error_headers,
+    error_info,
+    error_response_headers,
+    fallback_html_response,
+    find_error_boundaries,
+    prefers_html,
+    problem_response,
+    rpc_error_response,
+)
+from casp.observability import (
+    PROBE_PATHS,
+    ObservabilitySettings,
+    RequestIdMiddleware,
+    RequestLogMiddleware,
+    add_readiness_check,
+    check_readiness,
+    record,
+    request_id_for,
+)
+from casp.observability import configure as configure_observability
+from casp.maintenance import MaintenanceMiddleware, MaintenanceState
+from casp.request_pipeline import RequestPipelineMiddleware, load_pipeline
+from casp.jobs import jobs_lifespan, registered_jobs
+from casp.schedule import schedule as app_schedule
+from casp.schedule import scheduler_lifespan
+from casp.i18n import LocaleMiddleware
+from casp.i18n import current_locale as current_app_locale
+from casp.i18n import enabled as i18n_enabled
+from casp.seo import (
+    ROBOTS_PATH,
+    SITEMAP_PATH,
+    call_provider,
+    configured_base_url,
+    render_robots,
+    render_sitemap,
+)
 from casp.layout import (
     render_with_nested_layouts,
     _finalize_page_region,
@@ -136,6 +181,48 @@ if cfg.prisma:
 # calendar is affected -- session expiry and cache TTLs stay on UTC by design.
 APP_TIMEZONE = get_app_timezone()
 
+APP_ROOT = Path(__file__).resolve().parent
+PUBLIC_FRAMEWORK_PATHS: tuple[str, ...] = (*PROBE_PATHS, SITEMAP_PATH, ROBOTS_PATH)
+
+# Structured request/event logs and /ready policy. Production defaults: JSON
+# request records on stderr. See casp.observability.ObservabilitySettings.
+configure_observability(
+    ObservabilitySettings.from_env(is_production=IS_PRODUCTION, service_name=cfg.projectName)
+)
+
+if prisma is not None:
+    # The generated client connects lazily, so this also proves a connection
+    # can be opened. Cheap and side-effect free, as readiness checks must be.
+    async def _database_ready() -> None:
+        await prisma.query_raw("SELECT 1")
+
+    # `replace=True`: the dev server runs this file as __main__ and uvicorn then
+    # imports it again as `main`, so this module body executes twice.
+    add_readiness_check("database", _database_ready, replace=True)
+
+# App-owned readiness checks (`@readiness_check("name")`) register on import.
+if (APP_ROOT / "src" / "lib" / "readiness.py").is_file():
+    importlib.import_module("src.lib.readiness")
+
+# Authorization policies are app-owned and register themselves on
+# `casp.authorization.gate` when imported. The file is optional.
+if (APP_ROOT / "src" / "lib" / "auth" / "policies.py").is_file():
+    importlib.import_module("src.lib.auth.policies")
+
+# Background jobs (`@job`) and the task schedule register themselves on import.
+# Both files are optional; the schedule usually imports the jobs it dispatches.
+for _optional_module in ("jobs", "schedule"):
+    if (APP_ROOT / "src" / "lib" / f"{_optional_module}.py").is_file():
+        importlib.import_module(f"src.lib.{_optional_module}")
+
+
+def load_app_middleware() -> list[Any]:
+    """Entries from the optional `src/middleware.py` (the application pipeline)."""
+    if not (APP_ROOT / "src" / "middleware.py").is_file():
+        return []
+    return load_pipeline(importlib.import_module("src.middleware"))
+
+
 # ====
 # CORS configuration (shared .env convention, mirrors casp.rpc origin checks)
 # ====
@@ -368,6 +455,14 @@ def get_app_lifespans() -> list[LifespanFactory]:
     if prisma is not None:
         lifespans.append(prisma_lifespan)
 
+    # Job workers start after the database lifespan and drain before it exits;
+    # the scheduler starts after the workers and stops before they drain, so a
+    # timer can never enqueue into a queue that is already shutting down.
+    if registered_jobs():
+        lifespans.append(jobs_lifespan)
+    if app_schedule.tasks:
+        lifespans.append(scheduler_lifespan)
+
     # MCP lifecycle
     # FastMCP needs its lifespan running so the MCP session manager starts.
     if mcp_app is not None:
@@ -409,7 +504,21 @@ app = FastAPI(
 
 @app.get("/health")
 async def healthcheck():
-    return {"status": "ok"}
+    # Liveness: the process can serve HTTP. Deliberately checks no dependency --
+    # restarting a healthy process does not repair an unavailable database.
+    return JSONResponse({"status": "ok"}, headers={"Cache-Control": "no-store"})
+
+
+@app.get("/ready")
+async def readinesscheck():
+    # Readiness: every registered dependency check passes. Names and statuses
+    # only; failure details go to the log stream.
+    ready, checks = await check_readiness()
+    return JSONResponse(
+        {"status": "ok" if ready else "unavailable", "checks": checks},
+        status_code=200 if ready else 503,
+        headers={"Cache-Control": "no-store"},
+    )
 
 
 # ====
@@ -662,7 +771,9 @@ class AuthMiddleware:
         self.app = app
 
     async def __call__(self, scope: Scope, receive: Receive, send: Send):
-        if scope["type"] != "http":
+        if scope["type"] != "http" or scope.get("path") in PUBLIC_FRAMEWORK_PATHS:
+            # Probes (for orchestrators) and sitemap/robots (for crawlers) are
+            # answered without a session, whatever the route-privacy policy says.
             await self.app(scope, receive, send)
             return
         request = Request(scope, receive, send)
@@ -783,7 +894,7 @@ class RateLimitMiddleware:
             return
 
         path = scope.get("path", "")
-        if path == "/health":
+        if path in PROBE_PATHS:
             await self.app(scope, receive, send)
             return
 
@@ -1027,22 +1138,115 @@ def is_request_cacheable(request: Request) -> bool:
         return False
 
 
-def register_routes():
-    idx = get_files_index()
-    for route in idx.routes:
-        base_path = f"src/app/{route.fs_dir}" if route.fs_dir else "src/app"
-        full_path = f"{base_path}/index.py".replace("//", "/")
-        register_single_route(route.fastapi_rule, full_path)
+def _route_file_path(fs_dir: str, filename: str) -> str:
+    base_path = f"src/app/{fs_dir}" if fs_dir else "src/app"
+    return f"{base_path}/{filename}".replace("//", "/")
 
 
-def register_single_route(url_pattern: str, file_path: str):
-    async def make_handler(request: Request):
+def register_route_entry(route: RouteEntry, *, api: bool = False) -> None:
+    """Register a page (`index.py`) or API endpoint (`route.py`).
+
+    An optional catch-all (`[[...slug]]`) registers its base URL with the
+    parameter set to None, then the path form.
+    """
+    for rule, default_params in route.fastapi_rules():
+        if api:
+            register_api_route(
+                rule, _route_file_path(route.fs_dir, "route.py"), default_params=default_params
+            )
+        else:
+            register_single_route(
+                rule, _route_file_path(route.fs_dir, "index.py"), default_params=default_params
+            )
+
+
+def register_routes():
+    idx = get_files_index()
+    # Pages and API routes share one URL space, so they are ordered together:
+    # a catch-all page must never shadow a more specific API route.
+    entries = [(route, False) for route in idx.routes]
+    entries += [(route, True) for route in idx.api_routes]
+    for route, api in sorted(entries, key=lambda entry: route_priority(entry[0])):
+        register_route_entry(route, api=api)
+
+
+def _build_route_call(
+    func: Callable[..., Any], request: Request, params: dict[str, Any]
+) -> tuple[list[Any], dict[str, Any]]:
+    """Arguments for a `route.py` handler, using the same contract as `page()`:
+    path params as one positional dict, `request` by keyword, query params by name.
+    """
+    signature = inspect.signature(func)
+    call_args: list[Any] = [params] if params else []
+    call_kwargs: dict[str, Any] = {}
+    if "request" in signature.parameters:
+        call_kwargs["request"] = request
+    for name, param in signature.parameters.items():
+        if name in call_kwargs or name == "kwargs":
+            continue
+        if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+            continue
+        if name in request.query_params:
+            call_kwargs[name] = _coerce_query_param(request, name, param)
+    return call_args, call_kwargs
+
+
+def register_api_route(
+    url_pattern: str,
+    file_path: str,
+    *,
+    default_params: Optional[dict[str, Any]] = None,
+):
+    """Register a `route.py` API endpoint: one function per HTTP method, no layouts."""
+    methods = list(discover_handlers(load_route_module(file_path)))
+    # FastAPI's APIRoute does not add HEAD for GET the way a Starlette Route does.
+    if "GET" in methods and "HEAD" not in methods:
+        methods.append("HEAD")
+
+    async def api_handler(request: Request):
+        try:
+            module = load_route_module(file_path)
+            handler = select_handler(discover_handlers(module), request.method)
+            if handler is None:
+                raise HttpError(405)
+            if csrf_required(module):
+                await verify_csrf(request, session_cookie=SESSION_COOKIE_NAME)
+
+            params = {**(default_params or {}), **request.path_params}
+            call_args, call_kwargs = _build_route_call(handler, request, params)
+            result = handler(*call_args, **call_kwargs)
+            if inspect.isawaitable(result):
+                result = await result
+            return to_response(result)
+        except Exception as exc:
+            return await render_error_response(request, exc, APP_ROOT_DIR, is_api=True)
+
+    endpoint = re.sub(r"[^0-9A-Za-z_]", "_", file_path)
+    app.add_api_route(url_pattern, api_handler, methods=methods, name=endpoint)
+
+
+def register_single_route(
+    url_pattern: str,
+    file_path: str,
+    *,
+    default_params: Optional[dict[str, Any]] = None,
+):
+    boundary_dir = os.path.dirname(file_path)
+
+    async def render_page(request: Request):
         _runtime_metadata.set(None)
         _runtime_injections.set({"head": [], "body": []})
 
-        kwargs = dict(request.path_params)
-        current_uri = request.url.path
+        kwargs = {**(default_params or {}), **request.path_params}
+        # The page cache keys on path plus query string, so `/products?page=2`
+        # never serves the cached `/products` document.
+        current_uri = request.url.path + (f"?{request.url.query}" if request.url.query else "")
         request_is_cacheable = is_request_cacheable(request)
+        if i18n_enabled():
+            # Each language is its own cached document; the marker sits in the
+            # query part so revalidate_path("/x") still clears every language.
+            separator = "&" if "?" in current_uri else "?"
+            current_uri = f"{current_uri}{separator}__locale={current_app_locale()}"
 
         # 1. Cache Check (Fast Path)
         if CACHE_ENABLED and request_is_cacheable:
@@ -1057,6 +1261,7 @@ def register_single_route(url_pattern: str, file_path: str):
 
         req_should_cache = None
         req_cache_ttl = 0
+        req_cache_tags: list[str] = []
 
         page_content_source = file_path
 
@@ -1098,6 +1303,7 @@ def register_single_route(url_pattern: str, file_path: str):
         if cache_settings:
             req_should_cache = cache_settings.enabled
             req_cache_ttl = cache_settings.ttl
+            req_cache_tags = list(getattr(cache_settings, "tags", None) or [])
 
         if isinstance(result, tuple):
             page_content = result[0]
@@ -1113,16 +1319,7 @@ def register_single_route(url_pattern: str, file_path: str):
         static_meta = getattr(module, "metadata", None)
 
         def extract_meta(obj):
-            d = {}
-            if not obj:
-                return d
-            if obj.title:
-                d["title"] = obj.title
-            if obj.description:
-                d["description"] = obj.description
-            if obj.extra:
-                d.update(obj.extra)
-            return d
+            return dict(obj.to_dict()) if obj else {}
 
         page_metadata.update(extract_meta(static_meta))
         page_metadata.update(extract_meta(dynamic_meta))
@@ -1158,10 +1355,18 @@ def register_single_route(url_pattern: str, file_path: str):
         # the shared, URI-keyed cache on disk.
         if should_cache and request_is_cacheable:
             ttl_to_save = req_cache_ttl if req_cache_ttl > 0 else DEFAULT_TTL
-            CacheHandler.save_cache(current_uri, html_output, ttl_to_save)
+            CacheHandler.save_cache(current_uri, html_output, ttl_to_save, tags=req_cache_tags)
 
         return response
 
+    async def make_handler(request: Request):
+        # A failing page (or a layout below its nearest `error.py`) is rendered
+        # by that boundary instead of escaping to the global 500 handler.
+        try:
+            return await render_page(request)
+        except Exception as exc:
+            return await render_error_response(request, exc, boundary_dir, is_page=True)
+
     endpoint = (
         file_path.replace("/", "_")
         .replace("\\", "_")
@@ -1182,6 +1387,11 @@ def register_single_route(url_pattern: str, file_path: str):
         if normalized_methods:
             route_methods = list(dict.fromkeys(normalized_methods))
 
+    # FastAPI's APIRoute does not answer HEAD for GET the way a Starlette Route
+    # does; crawlers, uptime monitors, and BrowserSync all send HEAD.
+    if "GET" in route_methods and "HEAD" not in route_methods:
+        route_methods.append("HEAD")
+
     app.add_api_route(url_pattern, make_handler, methods=route_methods, name=endpoint)
 
 
@@ -1511,6 +1721,57 @@ def finalize_html(html_output: str) -> str:
 register_routes()
 register_rpc_routes(app)
 
+
+SEO_FILES: dict[str, tuple[str, str]] = {
+    SITEMAP_PATH: ("sitemap.py", "sitemap"),
+    ROBOTS_PATH: ("robots.py", "robots"),
+}
+
+
+def _make_seo_handler(url: str, filename: str, func_name: str):
+    page_path = os.path.join("src", "app", filename)
+
+    async def seo_handler(request: Request):
+        if not os.path.exists(page_path):
+            raise HttpError(404)
+        provider = getattr(load_route_module(page_path), func_name, None)
+        if not callable(provider):
+            raise HttpError.internal(f"{page_path} must define {func_name}()")
+        value = await call_provider(provider, request)
+        base_url = configured_base_url() or str(request.base_url).rstrip("/")
+        if url == SITEMAP_PATH:
+            return Response(render_sitemap(value or [], base_url), media_type="application/xml")
+        return PlainTextResponse(render_robots(value, base_url))
+
+    return seo_handler
+
+
+def register_seo_routes() -> list[str]:
+    """Serve `src/app/sitemap.py` at /sitemap.xml and `src/app/robots.py` at /robots.txt."""
+    registered: list[str] = []
+    for url, (filename, func_name) in SEO_FILES.items():
+        if not os.path.exists(os.path.join("src", "app", filename)):
+            continue
+        if (APP_ROOT / "public" / url.lstrip("/")).is_file():
+            print(
+                f"[caspian] WARNING: public{url} exists and is served before src/app/{filename}; "
+                "remove one of them.",
+                file=sys.stderr,
+                flush=True,
+            )
+        app.add_api_route(
+            url,
+            _make_seo_handler(url, filename, func_name),
+            methods=["GET"],
+            include_in_schema=False,
+            name=f"seo_{func_name}",
+        )
+        registered.append(url)
+    return registered
+
+
+SEO_ROUTES = register_seo_routes()
+
 # Mount the FastMCP app at /mcp so the endpoint is exactly /mcp.
 if mcp_app is not None:
     # Starlette's automatic mount redirect builds an absolute URL from the
@@ -1573,14 +1834,8 @@ async def _render_special_page(
 
     page_metadata = default_metadata.copy()
     for metadata_obj in (getattr(module, "metadata", None), _runtime_metadata.get()):
-        if not metadata_obj:
-            continue
-        if metadata_obj.title:
-            page_metadata["title"] = metadata_obj.title
-        if metadata_obj.description:
-            page_metadata["description"] = metadata_obj.description
-        if metadata_obj.extra:
-            page_metadata.update(metadata_obj.extra)
+        if metadata_obj:
+            page_metadata.update(metadata_obj.to_dict())
 
     page_source = getattr(page_content, "source_path", page_path)
     html_output, root_layout_id = await render_with_nested_layouts(
@@ -1596,11 +1851,13 @@ async def _render_special_page(
     return finalize_html(html_output), root_layout_id
 
 
-@app.exception_handler(StarletteHTTPException)
-async def custom_404_handler(request: Request, exc: StarletteHTTPException):
-    if exc.status_code == 404:
-        not_found_path = os.path.join("src", "app", "not_found.py")
-        if os.path.exists(not_found_path):
+APP_ROOT_DIR = "src/app"
+
+
+async def _render_not_found_response(request: Request, headers: dict[str, str]) -> Response:
+    not_found_path = os.path.join("src", "app", "not_found.py")
+    if os.path.exists(not_found_path):
+        try:
             html_output, root_layout_id = await _render_special_page(
                 page_path=not_found_path,
                 request=request,
@@ -1610,52 +1867,137 @@ async def custom_404_handler(request: Request, exc: StarletteHTTPException):
                 },
                 context_data={},
             )
-            resp = HTMLResponse(content=html_output, status_code=404)
+        except Exception as render_exc:
+            print(f"[error-boundary] {not_found_path} failed to render: {render_exc!r}", flush=True)
+        else:
+            resp = HTMLResponse(content=html_output, status_code=404, headers=headers)
             resp.headers["X-PP-Root-Layout"] = root_layout_id
             return resp
-    return HTMLResponse(content=f"<h1>{exc.detail}</h1>", status_code=exc.status_code)
+    return HTMLResponse(content="<h1>404 - Not Found</h1>", status_code=404, headers=headers)
 
 
-@app.exception_handler(Exception)
-async def custom_general_exception_handler(request: Request, exc: Exception):
-    full_trace = traceback.format_exc()
-    print(full_trace)
-    error_message = _client_error_message(exc)
-    error_trace = full_trace if not IS_PRODUCTION else None
-
-    error_page_path = os.path.join("src", "app", "error.py")
-    if os.path.exists(error_page_path):
-        context_data = {
-            "request": request,
-            "error_message": error_message,
-            "error_trace": error_trace,
-        }
+def _log_error(request: Request, exc: BaseException, status: int, trace: str) -> None:
+    if status == 404:
+        return
+    summary = f"{status} {request.method} {request.url.path}"
+    if status >= 500:
+        # Server-side diagnostic; the client response is redacted separately.
+        record("error", "http", summary, exception=type(exc).__name__, trace=trace)
+    elif not IS_PRODUCTION:
+        record("warn", "http", f"{summary}: {exc}")
+
+
+async def render_error_response(
+    request: Request,
+    exc: BaseException,
+    route_dir: str,
+    *,
+    is_page: bool = False,
+    is_api: bool = False,
+) -> Response:
+    """Turn a failure into the response shape its caller expects.
+
+    - RPC calls keep the PulsePoint wire (`{"error", "requestId"}`).
+    - `route.py` endpoints (`is_api`) always get `application/problem+json`, as
+      do API clients of other non-page endpoints.
+    - Pages (and browsers) get the nearest `error.py` boundary above
+      `route_dir`, wrapped by the layouts at and above that boundary. A
+      boundary that itself fails yields to the next ancestor boundary.
+    - A 404 renders the global `not_found.py`.
+
+    Client-visible text is redacted in production by `casp.errors`, and every
+    error response is `no-store` with the request id attached.
+    """
+    trace = "".join(traceback.format_exception(exc))
+    info = error_info(
+        exc,
+        is_production=IS_PRODUCTION,
+        request_id=request_id_for(request),
+        trace=trace,
+    )
+    _log_error(request, exc, info.status, trace)
+    extra_headers = error_headers(exc)
+
+    if request.headers.get("X-PP-RPC") == "true":
+        return rpc_error_response(info, headers=extra_headers)
+    if is_api or (not is_page and not prefers_html(request)):
+        return problem_response(info, headers=extra_headers)
+
+    headers = error_response_headers(info, extra_headers)
+    if info.status == 404:
+        return await _render_not_found_response(request, headers)
+
+    for boundary_path in find_error_boundaries(route_dir):
         try:
             html_output, root_layout_id = await _render_special_page(
-                page_path=error_page_path,
+                page_path=boundary_path,
                 request=request,
                 default_metadata={
-                    "title": "Application Error",
-                    "description": "An unexpected error occurred.",
+                    "title": info.reason,
+                    "description": "An error occurred while loading this page.",
+                },
+                context_data={
+                    "error": info,
+                    # Legacy `page(error_message, error_trace)` signature.
+                    "error_message": info.message,
+                    "error_trace": info.trace,
                 },
-                context_data=context_data,
             )
-            resp = HTMLResponse(content=html_output, status_code=500)
-            resp.headers["X-PP-Root-Layout"] = root_layout_id
-            return resp
         except Exception as render_exc:
-            print("Error rendering error.py:", render_exc)
-    return HTMLResponse(
-        content=f"<h1>500 - Internal Server Error</h1><p>{error_message}</p>", status_code=500
+            print(f"[error-boundary] {boundary_path} failed to render: {render_exc!r}", flush=True)
+            continue
+        response = HTMLResponse(content=html_output, status_code=info.status, headers=headers)
+        response.headers["X-PP-Root-Layout"] = root_layout_id
+        return response
+
+    return fallback_html_response(info, headers=extra_headers)
+
+
+@app.exception_handler(StarletteHTTPException)
+async def custom_404_handler(request: Request, exc: StarletteHTTPException):
+    # 404 stays an HTML page for every client, as it always has.
+    return await render_error_response(request, exc, APP_ROOT_DIR, is_page=exc.status_code == 404)
+
+
+@app.exception_handler(Exception)
+async def custom_general_exception_handler(request: Request, exc: Exception):
+    return await render_error_response(request, exc, APP_ROOT_DIR)
+
+
+async def render_maintenance_page(request: Request, state: MaintenanceState) -> Optional[Response]:
+    """Render `src/app/maintenance.py` for browsers while maintenance mode is on.
+
+    It runs outside the session and auth layers, so layouts that need a session
+    fail here; the middleware then serves its built-in page instead.
+    """
+    page_path = os.path.join("src", "app", "maintenance.py")
+    if not os.path.exists(page_path):
+        return None
+    html_output, root_layout_id = await _render_special_page(
+        page_path=page_path,
+        request=request,
+        default_metadata={"title": "Maintenance", "description": state.message},
+        context_data={"maintenance": state},
     )
+    response = HTMLResponse(content=html_output)
+    response.headers["X-PP-Root-Layout"] = root_layout_id
+    return response
 
 
 # ====
 # Middleware Order (LAST added runs FIRST)
 # ====
 app.add_middleware(RPCMiddleware)
+# The application pipeline (`src/middleware.py`): after auth, so it can read the
+# session and is never reached by refused requests; around pages, `route.py`,
+# and RPC. It skips public files, WebSockets, /health, /ready, and /mcp.
+app.add_middleware(RequestPipelineMiddleware, entries=load_app_middleware())
 app.add_middleware(AuthMiddleware)
 app.add_middleware(CSRFMiddleware)
+# Locale resolution (no-op without src/locales or APP_LOCALES): inside the
+# session so a saved choice is readable, outside auth so route privacy and
+# routing both see the path with any `/es` prefix removed.
+app.add_middleware(LocaleMiddleware)
 
 app.add_middleware(
     SessionMiddleware,
@@ -1673,6 +2015,16 @@ app.add_middleware(MissingPublicAssetMiddleware)
 # Outermost of the security layers: reject flooding before any session
 # decryption, template rendering, or database work is spent on the request.
 app.add_middleware(RateLimitMiddleware)
+# Maintenance mode sits inside public-file serving (stylesheets and images keep
+# loading for the maintenance page) and outside everything that does real work.
+app.add_middleware(
+    MaintenanceMiddleware,
+    render=render_maintenance_page,
+    secure_cookie=IS_PRODUCTION,
+)
+# Request records and counters: inside public-file serving (assets are not
+# application traffic), outside maintenance and rate limiting so refusals count.
+app.add_middleware(RequestLogMiddleware)
 # The public directory is itself the URL contract: any existing nested file is
 # served without adding a directory-specific route above. Keep upload content
 # in attachment mode unless its MIME type is explicitly safe to render inline.
@@ -1688,6 +2040,14 @@ app.add_middleware(SecurityHeadersMiddleware)
 if not IS_PRODUCTION:
     app.add_middleware(RequestDiagnosticsMiddleware)
 
+# Outermost: every response, including timeouts, rate-limit refusals, and error
+# pages, carries an `X-Request-Id`. A valid incoming id from a trusted gateway is
+# kept unless REQUEST_ID_TRUST_INCOMING=false.
+app.add_middleware(
+    RequestIdMiddleware,
+    accept_incoming=_bool_env("REQUEST_ID_TRUST_INCOMING", True),
+)
+
 
 def _consume_dev_control_stream(
     server: uvicorn.Server,