pipelex-api 0.71.0__py3-none-any.whl

pipelex_api/json_body.py

@@ -0,0 +1,182 @@
+"""JSON request bodies, bounded in nesting depth before any parser reads them.
+
+`json.loads` recurses once per nested array or object. Up to Python 3.13 a deeply nested body made it
+raise `RecursionError` at a fixed count; from Python 3.14 the guard is the thread's actual stack size,
+so the same body overflows on a small stack and parses on a large one, to be refused later for some
+other reason or accepted. The server therefore bounds the nesting itself, before parsing: a body nested
+deeper than `MAX_JSON_NESTING_DEPTH` answers the same 422 `InvalidJSON` on every interpreter and stack.
+
+Every JSON body the server parses goes through `ensure_json_nesting_within_limit`, by one of two doors:
+
+- A route that declares a typed body has it parsed by FastAPI. Its router is built with
+  `route_class=JsonBodyRoute`, which checks the body before FastAPI parses it, and
+  `tests/unit/test_json_body.py` fails when a body-declaring route of the app is not one.
+- A route that reads its raw body, as the run routes do, parses it with `decode_json_body`.
+"""
+
+import json
+import re
+from collections.abc import Callable, Coroutine
+from itertools import accumulate, cycle
+from operator import mul
+from typing import Any
+
+from fastapi import Request, Response, params
+from fastapi.routing import APIRoute
+from typing_extensions import override
+
+from pipelex_api.error_types import ErrorType
+from pipelex_api.errors import raise_validation_error
+from pipelex_api.limits import MAX_JSON_NESTING_DEPTH
+
+# The two escape sequences that can hide a quote. Once they are gone, every quote left delimits a string.
+_ESCAPED_BACKSLASH = b"\\\\"
+_ESCAPED_QUOTE = b'\\"'
+# Only quotes and brackets matter to nesting, and an object nests like an array.
+_NOT_STRUCTURAL = bytes(byte for byte in range(256) if byte not in b'"[]{}')
+_BRACES_AS_BRACKETS = bytes.maketrans(b"{}", b"[]")
+_ADJACENT_QUOTES = b'""'
+_QUOTE = b'"'
+_INNERMOST_PAIR = b"[]"
+_OPEN_BRACKET = ord("[")
+_BRACKET_RUN = re.compile(rb"\[+|\]+")
+# Peeling stops once a pass removes less than this fraction of the brackets the scan started with.
+_PEEL_STOP_DIVISOR = 8
+# The stages that build a list per piece, splitting at quotes and measuring runs, work a chunk at a time,
+# so no list grows with the body and its memory stays bounded however the body is shaped.
+_CHUNK_BYTES = 1 << 20
+
+
+def _as_utf8(body: bytes) -> bytes:
+    """Return the body in UTF-8, the encoding the scan reads.
+
+    `json.loads` given bytes also accepts UTF-16 and UTF-32, which FastAPI passes it as they come, and in
+    which a quote or an escape is not the single byte the scan looks for. Such a body is transcoded the way
+    `json.loads` decodes it. A body that does not decode is answered empty: the parser fails on the same
+    bytes before it reads a single bracket.
+    """
+    encoding = json.detect_encoding(body)
+    if encoding in {"utf-8", "utf-8-sig"}:
+        return body
+    try:
+        return body.decode(encoding, "surrogatepass").encode("utf-8", "surrogatepass")
+    except UnicodeError:
+        return b""
+
+
+def _brackets_outside_strings(body: bytes) -> bytes:
+    r"""Return the body's brackets that lie outside strings, in order, with every brace written as a bracket.
+
+    The escapes that can hide a quote are dropped first: removing every `\\` and then every `\"`, each
+    left to right, pairs a run of backslashes the way a parser does. The body is then cut down to its quotes
+    and brackets. Adjacent quotes enclose no bracket, whether they open and close one string or close one and
+    open the next, so dropping them changes nothing and spares the split below a piece per short string.
+    With every quote left a delimiter, the pieces between quotes alternate outside and inside strings,
+    starting outside, and the outside ones hold the brackets that nest. The skeleton is split a chunk at a
+    time, each chunk starting inside a string when the quotes before it are odd in number. An unterminated
+    string runs to the end, as it does for a parser.
+    """
+    unescaped = body.replace(_ESCAPED_BACKSLASH, b"").replace(_ESCAPED_QUOTE, b"")
+    skeleton = unescaped.translate(_BRACES_AS_BRACKETS, _NOT_STRUCTURAL).replace(_ADJACENT_QUOTES, b"")
+    outside: list[bytes] = []
+    in_string = False
+    for start in range(0, len(skeleton), _CHUNK_BYTES):
+        pieces = skeleton[start : start + _CHUNK_BYTES].split(_QUOTE)
+        outside.append(b"".join(pieces[1 if in_string else 0 :: 2]))
+        # A chunk split into an even number of pieces holds an odd number of quotes.
+        in_string ^= len(pieces) % 2 == 0
+    return b"".join(outside)
+
+
+def json_nesting_exceeds(body: bytes, *, max_depth: int) -> bool:
+    """Tell whether a JSON body nests its arrays and objects more than `max_depth` levels deep, without parsing it.
+
+    The answer is exact for a valid JSON document. For an invalid one it is never lower than the depth a
+    parser reaches before it stops, so no body this lets through makes `json.loads` recurse past `max_depth`.
+
+    It costs time linear in the body and never loops in Python over its bytes: a multi-megabyte body is
+    mostly strings, which `bytes` operations skip at C speed, and the brackets left are measured in two
+    stages. First, each pass of `replace(b"[]", b"")` removes the innermost level of every array and object
+    at once, which leaves the depth of every remaining bracket unchanged and lowers the deepest point by
+    exactly one. Passes continue while they remove much, which settles flat and shallow documents
+    outright. Then the runs of opening and closing brackets that remain, few by then, are summed in turn,
+    and the deepest running total plus the levels peeled is the body's depth.
+    """
+    brackets = _brackets_outside_strings(_as_utf8(body))
+    stop_below = len(brackets) // _PEEL_STOP_DIVISOR
+    peeled = 0
+    while brackets:
+        shorter = brackets.replace(_INNERMOST_PAIR, b"")
+        removed = len(brackets) - len(shorter)
+        if not removed:
+            break
+        brackets = shorter
+        peeled += 1
+        if peeled > max_depth:
+            return True
+        if removed < stop_below:
+            break
+    depth = 0
+    for start in range(0, len(brackets), _CHUNK_BYTES):
+        chunk = brackets[start : start + _CHUNK_BYTES]
+        # Maximal runs alternate between opening and closing brackets, so their signs alternate too.
+        signs = cycle((1, -1) if chunk[0] == _OPEN_BRACKET else (-1, 1))
+        running = list(accumulate(map(mul, map(len, _BRACKET_RUN.findall(chunk)), signs), initial=depth))
+        if max(running) + peeled > max_depth:
+            return True
+        depth = running[-1]
+    return False
+
+
+def ensure_json_nesting_within_limit(body: bytes) -> None:
+    """Refuse a request body nested deeper than `MAX_JSON_NESTING_DEPTH` with a 422 `InvalidJSON`."""
+    if json_nesting_exceeds(body, max_depth=MAX_JSON_NESTING_DEPTH):
+        raise_validation_error(
+            message=f"Request body is nested too deeply: its JSON arrays and objects may nest at most {MAX_JSON_NESTING_DEPTH} levels.",
+            error_type=ErrorType.INVALID_JSON,
+        )
+
+
+def decode_json_body(body: bytes) -> Any:
+    """Parse a raw request body as plain JSON, refusing it with a 422 `InvalidJSON` when it cannot be.
+
+    For a route that reads its body itself rather than declaring a typed one. The refusals are caller
+    mistakes, never a sanitized 500:
+      - a body nested deeper than `MAX_JSON_NESTING_DEPTH`, checked before parsing;
+      - `UnicodeDecodeError`: the bytes are not valid UTF-8;
+      - `ValueError`: `json.JSONDecodeError`, which subclasses it;
+      - `RecursionError`: the depth check leaves the parser nothing deep enough to raise it, so this only
+        stands as a second line of defence.
+    """
+    ensure_json_nesting_within_limit(body)
+    try:
+        return json.loads(body.decode("utf-8"))
+    except (UnicodeDecodeError, ValueError, RecursionError) as exc:
+        raise_validation_error(
+            message=f"Request body is not valid JSON: {exc!s}",
+            error_type=ErrorType.INVALID_JSON,
+        )
+
+
+class JsonBodyRoute(APIRoute):
+    """An `APIRoute` that checks a declared JSON body's nesting depth before FastAPI parses it.
+
+    FastAPI parses a typed body with `json.loads` and turns any failure but a `JSONDecodeError` into a
+    bare 400, so the check runs in front of FastAPI's own handler, where its 422 reaches the API's
+    exception handlers like any other `ApiError`. The body it reads is cached on the request, so FastAPI
+    does not read it twice. A route that declares no body, or a form body, is left as it is: one that
+    reads its raw body parses it with `decode_json_body`.
+    """
+
+    @override
+    def get_route_handler(self) -> Callable[[Request], Coroutine[Any, Any, Response]]:
+        handler = super().get_route_handler()
+        if self.body_field is None or isinstance(self.body_field.field_info, params.Form):
+            # No body, or a form body, which FastAPI never hands to `json.loads`.
+            return handler
+
+        async def bounded_handler(request: Request) -> Response:
+            ensure_json_nesting_within_limit(await request.body())
+            return await handler(request)
+
+        return bounded_handler

pipelex_api/limits.py

@@ -0,0 +1,67 @@
+"""Centralized, env-tunable size limits for incoming requests.
+
+Every endpoint that accepts user-supplied content bounds it via constants
+imported from this module. Values are read once at import time — change
+requires a process restart.
+"""
+
+from pipelex import log
+from pipelex.system.environment import get_optional_env
+
+DEFAULT_MAX_REQUEST_BODY_MIB = 100
+DEFAULT_MAX_MTHDS_FILE_KIB = 1024  # 1 MiB per .mthds file
+DEFAULT_MAX_MTHDS_FILES_PER_REQUEST = 16
+DEFAULT_MAX_PIPE_CODE_LEN = 256
+MAX_METHOD_REF_LEN = 512  # `method_ref` selector strings; a fixed schema bound, not env-tunable
+# How deep the arrays and objects of a JSON request body may nest, the body's own envelope included
+# (`{"inputs": {"x": [1]}}` nests three levels). Every route checks it before parsing, with
+# `pipelex_api.json_body`, because how deep `json.loads` can recurse depends on the interpreter and,
+# from Python 3.14, on the thread's stack size. Real inputs nest a few dozen levels at most. The bound
+# also sits well below pydantic's own JSON parser, which refuses a document nested past 200 levels and
+# reads a run's inputs again downstream, a few envelope levels deeper, where a transported PipeFunc
+# request and the trace event logs are parsed. A fixed bound, not env-tunable: raising it would hand the
+# parser's stack back to the caller.
+MAX_JSON_NESTING_DEPTH = 128
+DEFAULT_MAX_CALLBACK_URLS = 5
+DEFAULT_MAX_CALLBACK_URL_LEN = 2048
+DEFAULT_MAX_AGENT_SPEC_KIB = 256  # 256 KiB for JSON concept/pipe specs
+DEFAULT_MAX_BUNDLE_FILES = 128  # entries in a materialized method bundle (.mthds + .py + requirements.txt)
+DEFAULT_MAX_BUNDLE_TOTAL_KIB = 8 * 1024  # 8 MiB decompressed across the whole bundle (zip-bomb guard)
+DEFAULT_MAX_METHOD_CACHE_CLONES = 64  # cached method-package clones (one per resolved commit SHA)
+DEFAULT_MAX_METHOD_CACHE_TOTAL_KIB = 512 * 1024  # 512 MiB across all cached clones
+DEFAULT_MAX_METHOD_CACHE_AGE_HOURS = 24  # a cached clone unused for this long is evicted
+
+
+def _read_positive_int(env_var: str, default: int) -> int:
+    raw = get_optional_env(env_var)
+    if not raw:
+        return default
+    try:
+        parsed = int(raw)
+    except ValueError:
+        log.warning(f"Invalid {env_var}={raw!r}, falling back to {default}")
+        return default
+    if parsed <= 0:
+        log.warning(f"{env_var} must be positive (got {parsed}), falling back to {default}")
+        return default
+    return parsed
+
+
+MAX_REQUEST_BODY_MIB = _read_positive_int("MAX_REQUEST_BODY_MIB", DEFAULT_MAX_REQUEST_BODY_MIB)
+MAX_REQUEST_BODY_BYTES = MAX_REQUEST_BODY_MIB * 1024 * 1024
+
+MAX_MTHDS_FILE_BYTES = _read_positive_int("MAX_MTHDS_FILE_KIB", DEFAULT_MAX_MTHDS_FILE_KIB) * 1024
+MAX_MTHDS_FILES_PER_REQUEST = _read_positive_int("MAX_MTHDS_FILES_PER_REQUEST", DEFAULT_MAX_MTHDS_FILES_PER_REQUEST)
+MAX_PIPE_CODE_LEN = _read_positive_int("MAX_PIPE_CODE_LEN", DEFAULT_MAX_PIPE_CODE_LEN)
+
+MAX_CALLBACK_URLS = _read_positive_int("MAX_CALLBACK_URLS", DEFAULT_MAX_CALLBACK_URLS)
+MAX_CALLBACK_URL_LEN = _read_positive_int("MAX_CALLBACK_URL_LEN", DEFAULT_MAX_CALLBACK_URL_LEN)
+
+MAX_AGENT_SPEC_BYTES = _read_positive_int("MAX_AGENT_SPEC_KIB", DEFAULT_MAX_AGENT_SPEC_KIB) * 1024
+
+MAX_BUNDLE_FILES = _read_positive_int("MAX_BUNDLE_FILES", DEFAULT_MAX_BUNDLE_FILES)
+MAX_BUNDLE_TOTAL_BYTES = _read_positive_int("MAX_BUNDLE_TOTAL_KIB", DEFAULT_MAX_BUNDLE_TOTAL_KIB) * 1024
+
+MAX_METHOD_CACHE_CLONES = _read_positive_int("MAX_METHOD_CACHE_CLONES", DEFAULT_MAX_METHOD_CACHE_CLONES)
+MAX_METHOD_CACHE_TOTAL_BYTES = _read_positive_int("MAX_METHOD_CACHE_TOTAL_KIB", DEFAULT_MAX_METHOD_CACHE_TOTAL_KIB) * 1024
+MAX_METHOD_CACHE_AGE_SECONDS = _read_positive_int("MAX_METHOD_CACHE_AGE_HOURS", DEFAULT_MAX_METHOD_CACHE_AGE_HOURS) * 3600

pipelex_api/main.py

@@ -0,0 +1,221 @@
+"""FastAPI app init, middleware, and router registration.
+
+App construction lives here; the failure → HTTP response mapping lives in
+`pipelex_api.exception_handlers` (registered against this app below). Routes
+therefore no longer need to catch and shape errors themselves — anything
+they raise lands in the right handler by exception class.
+"""
+
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as package_version
+
+from fastapi import Depends, FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from mthds.protocol.protocol import PROTOCOL_VERSION
+from pipelex.interpreter_plugins.builtins import BUILTIN_PLUGINS, CORE_UNCONDITIONAL_PLUGIN_NAMES, ENTRY_POINT_GROUPS
+from pipelex.pipelex import Pipelex
+from pipelex.plugins.discovery import build_registrar
+from pipelex.plugins.registrar import HttpErrorMapperFn
+from pipelex.system.configuration.config_loader import config_manager
+from pipelex.system.configuration.configs import PipelexConfig
+from pipelex.system.environment import get_optional_env
+from pipelex.system.runtime import IntegrationMode
+from pydantic import BaseModel, Field
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from pipelex_api.api_config import get_api_config, resolve_boot_orchestrator
+from pipelex_api.disclosure import resolve_disclosure_mode
+from pipelex_api.exception_handlers import register_exception_handlers
+from pipelex_api.middleware import RequestIdMiddleware, request_body_size_middleware
+from pipelex_api.openapi_schema import PipelexFastAPI
+from pipelex_api.routes import router as api_router
+from pipelex_api.routes.health import router as health_router
+from pipelex_api.routes.version import router as version_router
+from pipelex_api.security import get_auth_dependency
+
+
+@asynccontextmanager
+async def lifespan(_app: FastAPI) -> AsyncGenerator[None]:
+    # Resolve the deployment's orchestration mode BEFORE booting, so the process can boot
+    # under the matching orchestrator. `orchestration_mode` selects the dispatch arm; a
+    # non-`direct` (async/boot) orchestrator — e.g. "temporal" — must additionally claim the
+    # process-global execution hub slots at boot, which the shared WorkflowExecutor requires
+    # (`is_*_boot_active()`): without it, a `temporal`-mode runner resolves the Temporal
+    # dispatch arm but the underlying pipe-run stack is still in-process, and dispatch fails
+    # with AsyncExecutionNotEnabledError. The base `direct` mode names no orchestrator and
+    # boots in-process (boot_orchestrator=None). `resolve_boot_orchestrator` derives boot from
+    # the deployment config and refuses a config whose single boot can't service its own
+    # per-request override policy (a `direct` default with override on) — so boot and dispatch
+    # can never be set inconsistently.
+    #
+    # Loading `api.toml` here also fails the app fast on a malformed config / baked override
+    # (the same posture as ERROR_DISCLOSURE), now even before the singleton exists. The loader
+    # only needs `runtime_manager.environment` (from PIPELEX_ENV), which resolves without a
+    # live singleton. get_api_config() is @cache'd, so the warm here is reused everywhere.
+    boot_orchestrator = resolve_boot_orchestrator(get_api_config())
+    Pipelex.make(integration_mode=IntegrationMode.FASTAPI, boot_orchestrator=boot_orchestrator)
+    try:
+        yield
+    finally:
+        Pipelex.teardown_if_needed()
+
+
+def _resolve_cors_origins() -> tuple[list[str], bool]:
+    """Read CORS_ALLOW_ORIGINS env var. Returns (origins, allow_credentials).
+
+    Default: wildcard origins, credentials disabled — the only valid combination
+    when origins is `*` (browsers reject credentials with wildcard). To enable
+    credentials, set CORS_ALLOW_ORIGINS to a comma-separated allowlist.
+    """
+    raw = get_optional_env("CORS_ALLOW_ORIGINS")
+    if not raw or raw.strip() == "*":
+        return ["*"], False
+    origins = [origin.strip() for origin in raw.split(",") if origin.strip()]
+    if not origins:
+        return ["*"], False
+    return origins, True
+
+
+# Resolve and validate ERROR_DISCLOSURE once, at module/startup: an unrecognized
+# value raises here and the production app fails to boot rather than silently
+# defaulting. Passed into `register_exception_handlers` below; the resolved
+# mode drives how much of an error report reaches a client. Kept module-level
+# so the production fail-fast lives on this single import path — only this
+# module triggers it, not `pipelex_api.exception_handlers` (which lets tests register
+# the handlers without inheriting the env-validation crash).
+ERROR_DISCLOSURE_MODE = resolve_disclosure_mode()
+
+
+def _resolve_http_error_mappers() -> dict[type[Exception], HttpErrorMapperFn]:
+    """Resolve the orchestrator plugins' HTTP-error mappers for this deployment.
+
+    Runs the pure, repeatable `build_registrar` against the loaded config (the same
+    standalone pattern `pipelex plugins list` uses) and reads back the
+    `{exc_type: to_error_report}` map each installed orchestrator plugin contributed
+    via `PluginRegistrar.add_http_error_mapper`. The base installs no orchestrator
+    plugin, so this is an empty map and no transport-error handler is registered; a
+    flavor (e.g. the Temporal one) contributes its plugin's mapper here, and only at
+    this point — at app construction, where the plugin (and therefore its SDK) is by
+    definition installed — is the plugin's exc-type provider thunk run. Resolved once
+    at module import so a duplicate/broken plugin fails the app fast, mirroring the
+    `ERROR_DISCLOSURE` fail-fast above.
+
+    Safe at import because the map is a pure function of *installed* plugins (entry
+    points + `config.runtime.plugins.disabled`) — never of the `boot_orchestrator` that
+    `Pipelex.make` selects at boot — so an import-time resolution yields the identical
+    map a post-boot one would. `boot_orchestrator=None` is passed for exactly that
+    reason: it gates only a plugin's hub-slot claims, which this throwaway registrar
+    never applies, while the HTTP-error mapper a plugin contributes is unconditional.
+    Naming the deployment's real orchestrator here would change nothing in the map and
+    would drag `api.toml` loading onto the import path.
+
+    `load_config_validated` rather than a load followed by a `model_validate`, because
+    that is the tolerant entry point the boot itself uses: a configuration a pipelex
+    schema change left behind is replayed through its migration ledger in memory and
+    re-validated, so a stale-but-explainable config warns instead of stopping the boot.
+    Validating the raw dict here would refuse, at import, a config the very next step
+    (`Pipelex.make` in `lifespan`) accepts — the app would never start over a file
+    pipelex offers to migrate.
+    """
+    config = config_manager.load_config_validated(config_cls=PipelexConfig)
+    return build_registrar(
+        config=config,
+        boot_orchestrator=None,
+        builtin_plugins=BUILTIN_PLUGINS,
+        core_unconditional_plugin_names=CORE_UNCONDITIONAL_PLUGIN_NAMES,
+        entry_point_groups=ENTRY_POINT_GROUPS,
+    ).get_http_error_mappers()
+
+
+HTTP_ERROR_MAPPERS = _resolve_http_error_mappers()
+
+
+def _own_version() -> str:
+    """This server package's version — best-effort for app metadata."""
+    try:
+        return package_version("pipelex-api")
+    except PackageNotFoundError:
+        return "0.0.0"
+
+
+fastapi_app = PipelexFastAPI(
+    redirect_slashes=False,
+    lifespan=lifespan,
+    title="Pipelex API",
+    version=_own_version(),
+    summary=f"The source-available Pipelex runner — implements MTHDS Protocol v{PROTOCOL_VERSION}.",
+    description=(
+        f"This server implements the [MTHDS Protocol](https://mthds.ai) v{PROTOCOL_VERSION} "
+        "(`POST /execute`, `POST /start`, `POST /validate`, `GET /models`, `GET /version` — "
+        "marked `x-mthds-protocol: true`) plus the Pipelex API extensions: resolve and codegen "
+        "(`/resolve`, `/codegen`), build tooling (`/build/*`), and editor tooling (`/lint`, `/format`). "
+        "Contract layering: MTHDS Protocol ⊂ Pipelex API (this server) ⊂ Pipelex hosted API. "
+        "All endpoints are served under the `/v1` base path; "
+        "every error is an RFC 7807 `application/problem+json` problem document, documented per "
+        "operation as a `ProblemDocument`."
+    ),
+    license_info={"name": "Elastic License 2.0", "identifier": "Elastic-2.0"},
+)
+
+# Order matters: Starlette's `add_middleware` PREPENDS (see
+# `user_middleware.insert(0, ...)` in `starlette.applications`), so the LAST
+# `add_middleware` call becomes the OUTERMOST wrapper. Body-size is registered
+# first so CORS ends up wrapping it: a 413 short-circuit from the body-size
+# middleware still passes back through CORSMiddleware on the way out, so a
+# cross-origin browser POST sees the RFC 7807 413 with the
+# `Access-Control-Allow-Origin` header it needs — not a generic CORS error
+# that swallows the response.
+fastapi_app.add_middleware(BaseHTTPMiddleware, dispatch=request_body_size_middleware)
+
+cors_origins, cors_allow_credentials = _resolve_cors_origins()
+fastapi_app.add_middleware(
+    CORSMiddleware,
+    allow_origins=cors_origins,
+    allow_credentials=cors_allow_credentials,
+    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+    allow_headers=["*"],
+    expose_headers=["*"],
+)
+
+fastapi_app.include_router(health_router)
+
+# `GET /v1/version` is the protocol handshake — ALWAYS public, mounted without
+# the auth dependency exactly like `/health` (clients call it for feature
+# detection before they have credentials).
+fastapi_app.include_router(version_router, prefix="/v1")
+
+# Register all other routes WITH authentication (auto-selects based on AUTH_MODE env var: none/jwt/api_key).
+# The API mounts at `/v1` — the SDKs compose `{MTHDS_BASE_URL}/v1/{endpoint}` (master D10); no `/api/v1`
+# mount and no alias remain.
+auth_dependency = get_auth_dependency()
+fastapi_app.include_router(api_router, prefix="/v1", dependencies=[Depends(auth_dependency)])
+
+
+class ServiceIdentity(BaseModel):
+    """Body of `GET /` — the service identity banner."""
+
+    message: str = Field(..., description="Name of the service answering on this origin.")
+
+
+@fastapi_app.get("/", summary="Service identity banner", tags=["health"])
+async def root() -> ServiceIdentity:
+    """Identify the service answering on this origin. No auth required.
+
+    A human-facing banner for someone who lands on the bare origin — not a
+    liveness probe (that is `GET /health`) and not the protocol handshake
+    (`GET /v1/version`). It reads nothing and can only succeed.
+    """
+    return ServiceIdentity(message="Pipelex API")
+
+
+register_exception_handlers(fastapi_app, disclosure_mode=ERROR_DISCLOSURE_MODE, http_error_mappers=HTTP_ERROR_MAPPERS)
+
+
+# RequestIdMiddleware wraps the *entire* FastAPI app — including Starlette's
+# ServerErrorMiddleware, which `add_middleware` could only ever nest inside.
+# This is what makes it genuinely outermost: the request-id contextvars are
+# bound, and `X-Request-ID` is echoed, on every response — the catch-all 500
+# included. `app` is the ASGI entrypoint (uvicorn loads `pipelex_api.main:app`).
+app = RequestIdMiddleware(fastapi_app)