nativegate 0.1.0__py3-none-any.whl

nativegate/generators/middleware_gen.py

@@ -0,0 +1,717 @@
+"""The generated service's middleware: request identity, access logs, auth, limits.
+
+Emitted as one `middleware.py` per service with a single entry point,
+`install_middleware(app, service_name)`, called by both the standalone
+`service.py` and the composed gateway app. Same reason `error_gen` is shared:
+middleware attaches to an *app*, and a service router mounted into a gateway
+runs under the gateway's app, so installing it in one place only would miss
+the deployment more likely to face the internet.
+
+TWO RULES THIS FILE IS BUILT AROUND
+
+**Secrets come from the environment, never from config or the image.** API
+keys are read from `NATIVEGATE_API_KEYS` at startup. Nothing is baked into
+`nativegate.yaml` (which is committed) or into a layer (which is pullable by
+anyone who can reach the registry).
+
+**Auth fails closed.** If `api.auth: api_key` is configured and no keys are
+present in the environment, the service **refuses to start** rather than
+serving unauthenticated. A misconfiguration that silently disables
+authentication is worse than one that pages someone at deploy time — the
+first is discovered by an attacker, the second by the person deploying.
+
+WHAT IS DELIBERATELY HONEST ABOUT THE RATE LIMITER
+
+It is per-process. Generated images run several gunicorn workers, so a limit
+of N is really N×`WEB_CONCURRENCY` across the service, and it resets when a
+worker is recycled. That is useful as a crude backstop against one client
+melting one worker; it is **not** a quota system, and real global limiting
+belongs at the ingress, where there is one place to count. Saying so is the
+point — an in-process counter presented as a global limit is the kind of
+control that is trusted until the day it matters.
+"""
+
+from __future__ import annotations
+
+from .mcp_gen import MCP_MOUNT_PATH
+
+MIDDLEWARE_FILENAME = "middleware.py"
+
+# Names of the env vars the generated middleware reads. Kept here so the CLI
+# and the docs can name them without re-deriving the strings.
+ENV_API_KEYS = "NATIVEGATE_API_KEYS"
+ENV_RATE_LIMIT = "NATIVEGATE_RATE_LIMIT_PER_MINUTE"
+ENV_MAX_BODY = "NATIVEGATE_MAX_REQUEST_BYTES"
+
+# Provenance stamped onto every access-log line. Set by whatever runs the
+# container (the console's deployer), not by the image, so they are read per
+# call rather than frozen at import.
+ENV_PROJECT = "NATIVEGATE_PROJECT"
+ENV_BUILD_ID = "NATIVEGATE_BUILD_ID"
+ENV_IMAGE_DIGEST = "NATIVEGATE_IMAGE_DIGEST"
+
+AUTH_MODES = ("none", "api_key")
+
+
+def generate_middleware_py(service_name: str, auth: str = "none") -> str:
+    """The service's `middleware.py`.
+
+    `auth` is the *configured* mode, baked in at generate time on purpose: a
+    service generated to require authentication should not be able to have it
+    turned off by an environment variable at runtime.
+    """
+    if auth not in AUTH_MODES:
+        raise ValueError(
+            f"Unknown auth mode {auth!r} for service {service_name!r}; "
+            f"expected one of {', '.join(AUTH_MODES)}."
+        )
+
+    return f'''# Generated by nativegate. Do not edit by hand — re-run `ngate generate`.
+"""Request identity, access logging, authentication and limits for {service_name}.
+
+Installed by both `service.py` and the gateway app via `install_middleware`.
+See the nativegate docs on production readiness for what each layer does and,
+just as importantly, what it does not.
+"""
+from __future__ import annotations
+
+import hmac
+import json
+import logging
+import os
+import signal
+import sys
+import time
+import uuid
+from collections import deque
+from datetime import datetime, timezone
+from threading import Lock
+
+from fastapi import HTTPException, Request
+from fastapi.responses import JSONResponse
+
+__all__ = [
+    "install_middleware",
+    "readiness",
+    "start_draining",
+    "AuthNotConfigured",
+    "current_request_id",
+    "log_call",
+]
+
+_LOG = logging.getLogger("nativegate.{service_name}")
+_ACCESS_LOG = logging.getLogger("nativegate.{service_name}.access")
+
+# Characters of a call's input/output payload kept per access-log line.
+# Bounded because these lines go to stdout, get parsed by the console's
+# tailer and stored in SQLite — an uploaded array or a large struct dump
+# would otherwise make one call balloon the log stream and the evidence
+# pack it feeds.
+_PAYLOAD_LIMIT = 2000
+
+
+def _truncate_payload(text: str | None) -> str | None:
+    if not text:
+        return None
+    if len(text) > _PAYLOAD_LIMIT:
+        return text[:_PAYLOAD_LIMIT] + f"... ({{len(text)}} chars total)"
+    return text
+
+
+# Bytes of an HTTP body carried forward from the capture into the log line.
+# Larger than _PAYLOAD_LIMIT so a body that will be truncated anyway is still
+# recognisably the right body.
+#
+# Honest about what this does NOT bound: a captured body is whole in memory
+# before it gets here, because reading a request body and draining a response
+# iterator are both all-or-nothing. What keeps that from being unbounded is
+# the content-type gate (binary payloads — the large ones for a native
+# service — are never read at all) and, for requests, the separate
+# `_limit_body` layer. This limit only stops a large *JSON* body from being
+# copied on into a log line no reader can use past _PAYLOAD_LIMIT anyway.
+_CAPTURE_LIMIT = 8192
+
+
+def _is_capturable(content_type: str, content_encoding: str = "") -> bool:
+    """Whether a body with these headers is worth recording.
+
+    JSON only. Everything else a generated service returns is binary (packed
+    arrays, files): its bytes are noise in a log line, and skipping it is
+    what keeps the large payloads out of memory. Notably this also excludes
+    `text/event-stream`, which must not be buffered at all — see the
+    streaming note in `_access_log`.
+
+    The media type is parsed rather than substring-matched. `"json" in
+    content_type` would admit `multipart/form-data;
+    boundary=----WebKitFormBoundaryjson1a2b` — a boundary is client-chosen,
+    so a binary upload could put itself in the log as mojibake purely by
+    naming itself that, which is precisely what this gate exists to stop.
+    `+json` is honoured so structured error bodies
+    (`application/problem+json`) are captured like any other JSON.
+
+    `content_encoding` rejects a compressed body (a GZipMiddleware installed
+    inside this one, a handler setting it by hand). Its bytes are still JSON
+    by content type, but decoding them as text yields mojibake — a corrupted
+    audit record is worse than an absent one, because nothing about it looks
+    wrong.
+    """
+    encoding = content_encoding.strip().lower()
+    if encoding and encoding != "identity":
+        return False
+    media_type = content_type.split(";", 1)[0].strip().lower()
+    return media_type == "application/json" or media_type.endswith("+json")
+
+
+def _capture_body(raw: bytes) -> str | None:
+    """The loggable string form of a body already known to be capturable.
+
+    `errors="replace"` rather than a try/except: _CAPTURE_LIMIT cuts at a
+    byte offset, which lands mid-character often enough on non-ASCII input
+    that treating it as a decode failure would silently drop whole payloads
+    for the tail of one character.
+    """
+    if not raw:
+        return None
+    return raw[:_CAPTURE_LIMIT].decode("utf-8", errors="replace")
+
+
+def _provenance() -> dict:
+    """Which project, which build, which image produced this line.
+
+    `build_id` is emitted as an int because a consumer joining log rows against
+    build records wants a number, not the string form it arrived as; an
+    unparseable value is nulled rather than passed through half-typed.
+    """
+    raw_build_id = os.environ.get("{ENV_BUILD_ID}") or ""
+    try:
+        build_id = int(raw_build_id)
+    except ValueError:
+        build_id = None
+    return {{
+        "project": os.environ.get("{ENV_PROJECT}") or None,
+        "build_id": build_id,
+        "image_digest": os.environ.get("{ENV_IMAGE_DIGEST}") or None,
+    }}
+
+
+class _JsonLineFormatter(logging.Formatter):
+    """One JSON object per line on stdout — the schema the console tails.
+
+    Not the stdlib `extra=` fields verbatim: the console needs a fixed set of
+    keys present on every line (nulled, not omitted, when a field does not
+    apply to that call), so it can parse REST and MCP rows with one schema
+    rather than two.
+
+    The provenance fields (`project`, `build_id`, `image_digest`) are resolved
+    here rather than at the call sites so REST and MCP rows cannot drift, and
+    from the environment on every line rather than at import: a container's env
+    is set at `docker run`, after this module is already loaded.
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        return json.dumps(
+            {{
+                "ts": datetime.now(timezone.utc).isoformat(),
+                "service": getattr(record, "service", "{service_name}"),
+                "kind": getattr(record, "kind", "rest"),
+                "method": getattr(record, "method", None),
+                "path": getattr(record, "path", None),
+                "tool": getattr(record, "tool", None),
+                "status": getattr(record, "status", None),
+                "duration_ms": getattr(record, "duration_ms", None),
+                "request_id": getattr(record, "request_id", "-"),
+                "input": getattr(record, "input", None),
+                "output": getattr(record, "output", None),
+                **_provenance(),
+            }}
+        )
+
+
+class _StdoutHandler(logging.StreamHandler):
+    """Resolves `sys.stdout` on every emit rather than once at construction.
+
+    A handler built with `logging.StreamHandler(sys.stdout)` freezes whatever
+    stream object `sys.stdout` was at import time — wrong the moment anything
+    (a test's capsys, a reloader) swaps `sys.stdout` out afterwards.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(sys.stdout)
+
+    @property
+    def stream(self):
+        return sys.stdout
+
+    @stream.setter
+    def stream(self, value) -> None:
+        pass
+
+
+def _install_json_access_log() -> None:
+    # Idempotent: install_middleware and the MCP server's module-level import
+    # can both run in the same process, and a second handler would duplicate
+    # every line.
+    if any(isinstance(h, _StdoutHandler) for h in _ACCESS_LOG.handlers):
+        return
+    handler = _StdoutHandler()
+    handler.setFormatter(_JsonLineFormatter())
+    _ACCESS_LOG.addHandler(handler)
+    _ACCESS_LOG.setLevel(logging.INFO)
+    _ACCESS_LOG.propagate = False
+
+
+def log_call(
+    *,
+    kind: str,
+    request_id: str,
+    method: str | None = None,
+    path: str | None = None,
+    tool: str | None = None,
+    status: int | None = None,
+    duration_ms: float,
+    service_name: str = "{service_name}",
+    input_data: str | None = None,
+    output_data: str | None = None,
+) -> None:
+    """Emit one access-log line. Shared by the REST middleware and the MCP
+    server so both `kind`s go through the same formatter and schema.
+
+    `input_data`/`output_data` are already-serialised JSON strings (the
+    caller owns encoding, since a request body and an MCP tool result are
+    shaped nothing alike) and are truncated here so one oversized payload
+    cannot inflate this line past what the console's tailer and SQLite
+    column are meant to hold.
+    """
+    _install_json_access_log()
+    _ACCESS_LOG.info(
+        "%s %s",
+        kind,
+        tool if tool is not None else path,
+        extra={{
+            "service": service_name,
+            "kind": kind,
+            "method": method,
+            "path": path,
+            "tool": tool,
+            "status": status,
+            "duration_ms": round(duration_ms, 3),
+            "request_id": request_id,
+            "input": _truncate_payload(input_data),
+            "output": _truncate_payload(output_data),
+        }},
+    )
+
+MCP_MOUNT_PATH = "{MCP_MOUNT_PATH}"
+
+
+def _is_mcp_transport_path(path: str) -> bool:
+    """Whether `path` addresses the mounted MCP app.
+
+    A boundary match, not `startswith("{MCP_MOUNT_PATH}")`: a sibling route such as
+    `/mcpconfig` or `/mcp-status` shares the prefix but is ordinary REST
+    traffic, and labelling it `mcp_http` would put a row in the audit trail
+    describing a layer the request never went through.
+    """
+    return path == MCP_MOUNT_PATH or path.startswith(MCP_MOUNT_PATH + "/")
+
+
+# Baked in at generate time from `api.auth` in nativegate.yaml. Deliberately not
+# an environment variable: a service generated to require authentication must
+# not be silently downgraded by the environment it happens to start in.
+AUTH_MODE = "{auth}"
+
+# Paths that never require authentication. An orchestrator probing readiness
+# has no credentials, and a liveness probe that 401s is a service that looks
+# dead and gets restarted forever.
+_UNAUTHENTICATED_PATHS = frozenset({{"/healthz", "/readyz"}})
+
+
+class AuthNotConfigured(RuntimeError):
+    """Raised at startup when auth is required but no keys are present."""
+
+
+def _load_api_keys() -> list[str]:
+    raw = os.environ.get("{ENV_API_KEYS}", "")
+    return [k.strip() for k in raw.split(",") if k.strip()]
+
+
+def _int_env(name: str, default: int) -> int:
+    try:
+        return int(os.environ.get(name, "") or default)
+    except ValueError:
+        _LOG.warning("%s is not an integer; falling back to %s", name, default)
+        return default
+
+
+class _RateLimiter:
+    """Per-process sliding window. See the module docstring for the caveat.
+
+    A deque of timestamps per client rather than a token bucket: the window is
+    exact, and for the request rates a native-compute service sees the memory
+    is irrelevant. Old entries are evicted on access, so an idle client's
+    deque costs nothing after its window passes.
+    """
+
+    def __init__(self, per_minute: int) -> None:
+        self.per_minute = per_minute
+        self._hits: dict[str, deque[float]] = {{}}
+        self._lock = Lock()
+
+    def allow(self, client: str, now: float) -> bool:
+        if self.per_minute <= 0:
+            return True
+        cutoff = now - 60.0
+        with self._lock:
+            hits = self._hits.setdefault(client, deque())
+            while hits and hits[0] < cutoff:
+                hits.popleft()
+            if not hits:
+                # Keeps the dict from growing without bound as clients churn.
+                self._hits.pop(client, None)
+                hits = self._hits.setdefault(client, deque())
+            if len(hits) >= self.per_minute:
+                return False
+            hits.append(now)
+            return True
+
+
+def current_request_id(request: Request) -> str:
+    """The id for this request, for handlers that want to log against it."""
+    return getattr(request.state, "request_id", "-")
+
+
+def install_middleware(app, service_name: str = "{service_name}") -> None:
+    """Attach every middleware layer to `app`, outermost first.
+
+    Order matters and is not arbitrary:
+
+    1. request id — so everything below it, including rejections, can be
+       correlated. A 401 with no id is an unanswerable support ticket.
+    2. access log — directly inside the request id, so it sees an id on every
+       line, and OUTSIDE the layers that reject. An access log nested inside
+       auth records only the calls that got through: a 401, a 413 and a 429
+       would each leave no row at all, which is exactly the traffic an audit
+       of a governed service most needs to see. The cost is that the recorded
+       duration includes the layers below rather than the handler alone —
+       cheap, and honest, since that is what the caller waited for.
+    3. body size — cheapest rejection, and it runs before anything reads the
+       body into memory.
+    4. auth — before the rate limiter, so an unauthenticated flood is rejected
+       without consuming the caller's quota, and so the limiter can key on the
+       authenticated identity rather than a spoofable address.
+    5. rate limit — keyed by API key when there is one, client address if not.
+
+    Starlette runs `add_middleware` in reverse registration order, so these
+    are registered bottom-up.
+    """
+    api_keys = _load_api_keys()
+    if AUTH_MODE == "api_key" and not api_keys:
+        raise AuthNotConfigured(
+            f"{{service_name}} is configured with `api.auth: api_key` but "
+            "{ENV_API_KEYS} is empty. Refusing to start rather than serve "
+            "unauthenticated. Set it to a comma-separated list of keys, or "
+            "regenerate the service with `api.auth: none` if it is genuinely "
+            "meant to be open."
+        )
+    if AUTH_MODE == "none":
+        # Not a warning on every request — once, at startup, where an operator
+        # reading boot logs will actually see it.
+        _LOG.warning(
+            "%s is serving WITHOUT authentication (api.auth: none). Anything "
+            "that can reach the port can call the native code.", service_name
+        )
+
+    limiter = _RateLimiter(_int_env("{ENV_RATE_LIMIT}", 0))
+    max_body = _int_env("{ENV_MAX_BODY}", 1_048_576)
+
+    @app.middleware("http")
+    async def _rate_limit(request: Request, call_next):
+        if limiter.per_minute > 0 and request.url.path not in _UNAUTHENTICATED_PATHS:
+            client = getattr(request.state, "auth_key", None) or (
+                request.client.host if request.client else "unknown"
+            )
+            if not limiter.allow(client, time.monotonic()):
+                _LOG.warning(
+                    "rate limit exceeded for %s on %s (request %s)",
+                    client, request.url.path, current_request_id(request),
+                )
+                return JSONResponse(
+                    status_code=429,
+                    content={{
+                        "error": "rate limit exceeded",
+                        "limit_per_minute": limiter.per_minute,
+                        "request_id": current_request_id(request),
+                    }},
+                    headers={{"Retry-After": "60"}},
+                )
+        return await call_next(request)
+
+    @app.middleware("http")
+    async def _authenticate(request: Request, call_next):
+        if AUTH_MODE == "api_key" and request.url.path not in _UNAUTHENTICATED_PATHS:
+            presented = request.headers.get("x-api-key") or ""
+            bearer = request.headers.get("authorization", "")
+            if not presented and bearer.lower().startswith("bearer "):
+                presented = bearer[7:].strip()
+            # compare_digest against every key: a short-circuit `in` leaks key
+            # length and position through timing. The loop is deliberately not
+            # broken early for the same reason.
+            matched = False
+            for key in api_keys:
+                if hmac.compare_digest(presented, key):
+                    matched = True
+            if not matched:
+                _LOG.warning(
+                    "rejected unauthenticated %s %s (request %s)",
+                    request.method, request.url.path, current_request_id(request),
+                )
+                return JSONResponse(
+                    status_code=401,
+                    content={{
+                        "error": "unauthorized",
+                        "request_id": current_request_id(request),
+                    }},
+                    headers={{"WWW-Authenticate": "Bearer"}},
+                )
+            request.state.auth_key = presented
+        return await call_next(request)
+
+    @app.middleware("http")
+    async def _limit_body(request: Request, call_next):
+        declared = request.headers.get("content-length")
+        if declared is not None:
+            try:
+                if int(declared) > max_body:
+                    return JSONResponse(
+                        status_code=413,
+                        content={{
+                            "error": "request body too large",
+                            "max_request_bytes": max_body,
+                            "request_id": current_request_id(request),
+                        }},
+                    )
+            except ValueError:
+                return JSONResponse(
+                    status_code=400,
+                    content={{"error": "malformed Content-Length"}},
+                )
+        return await call_next(request)
+
+    @app.middleware("http")
+    async def _access_log(request: Request, call_next):
+        started = time.perf_counter()
+        is_mcp = _is_mcp_transport_path(request.url.path)
+
+        # Payloads are recorded for REST only. The MCP mount speaks a
+        # streaming transport, and the tool call underneath it already logs
+        # its own decoded arguments and result (mcp_server.py) — capturing
+        # here as well would both risk buffering a live stream and store the
+        # same payload twice under two `kind`s.
+        input_data = None
+        if not is_mcp and _is_capturable(
+            request.headers.get("content-type", ""),
+            request.headers.get("content-encoding", ""),
+        ):
+            # Reading the body here does NOT starve the endpoint, and this
+            # layer must not try to help it along. BaseHTTPMiddleware hands
+            # dispatch a `_CachedRequest`, whose `wrapped_receive` replays a
+            # body that `.body()` already cached — downstream sees the whole
+            # request without anything from us.
+            #
+            # Re-injecting a replay onto `request._receive` (the obvious
+            # move, and wrong) additionally poisons the disconnect path: once
+            # the body is consumed, `wrapped_receive` awaits that same
+            # channel expecting only `http.disconnect`, and a replay that
+            # keeps answering `http.request` makes it raise "Unexpected
+            # message received". That crashed every body-carrying request
+            # whose handler returned a streaming response.
+            try:
+                raw = await request.body()
+            except Exception:  # noqa: BLE001 - logging must never break the call
+                raw = b""
+            input_data = _capture_body(raw)
+
+        response = await call_next(request)
+
+        # Draining `body_iterator` is why this is gated on content type
+        # rather than done unconditionally: for a genuinely streaming
+        # response the loop below would not end until the stream did, turning
+        # an incremental response into a buffered one. JSON responses are
+        # already fully materialised by the time they reach here, so
+        # collecting and replaying their chunks changes nothing the client
+        # can observe.
+        output_data = None
+        body_iterator = getattr(response, "body_iterator", None)
+        if (
+            not is_mcp
+            and body_iterator is not None
+            # A Content-Length is the difference between a response that is
+            # already whole and one still being produced. Starlette sets it
+            # on a materialised body (JSONResponse and friends) and cannot
+            # set it on a StreamingResponse, whose length is unknown until
+            # the generator ends. Without this, a handler streaming
+            # newline-delimited JSON would be drained to completion before
+            # the client saw its first byte — and never released at all if
+            # the generator does not terminate.
+            #
+            # The header is taken at its word. A handler that returns a
+            # StreamingResponse and sets Content-Length on it by hand would
+            # still be drained — but that response is already malformed on
+            # its own terms (it declares a length Starlette will not
+            # enforce), and guessing around a handler that lies about its
+            # own body is not something this layer can do better than the
+            # framework.
+            and response.headers.get("content-length") is not None
+            and _is_capturable(
+                response.headers.get("content-type", ""),
+                response.headers.get("content-encoding", ""),
+            )
+        ):
+            # Chunks accumulate outside the try and the replacement iterator
+            # is installed unconditionally, so no path can leave the original
+            # (now partly drained) iterator on the response.
+            #
+            # Belt and braces, not a live bug: an exception here can only
+            # come from the downstream app, which BaseHTTPMiddleware runs in
+            # a task group that re-raises it on unwind regardless of what
+            # this clause does — measured, and the client sees the same error
+            # either way. It is written this way so the guarantee survives a
+            # future where that is no longer true, and so re-raising after
+            # the collected chunks keeps the failure the response's own
+            # rather than this layer's.
+            chunks: list = []
+            failure: BaseException | None = None
+            try:
+                async for chunk in body_iterator:
+                    chunks.append(chunk)
+            except Exception as exc:  # noqa: BLE001 - re-raised below, not swallowed
+                failure = exc
+
+            async def _replay_response(_chunks: list = chunks, _failure=failure):
+                for chunk in _chunks:
+                    yield chunk
+                if _failure is not None:
+                    raise _failure
+
+            response.body_iterator = _replay_response()
+            if failure is None:
+                # Not every chunk is a body chunk. `body_stream()` yields a
+                # raw ASGI message dict for `http.response.pathsend` (a
+                # FileResponse on a server advertising that extension) —
+                # Starlette's own `stream_response` has an `isinstance(chunk,
+                # dict)` branch for it, and `bytes(a_dict)` would raise
+                # TypeError here, failing a download that had already
+                # succeeded. Non-bytes chunks are passed through to the
+                # client by the replay above and simply left out of the log.
+                #
+                # str is handled for the same defensive reason, though it is
+                # currently unreachable: the downstream response encodes at
+                # the ASGI send boundary before this layer sees it (measured).
+                output_data = _capture_body(
+                    b"".join(
+                        c.encode("utf-8") if isinstance(c, str) else c
+                        for c in chunks
+                        if isinstance(c, (bytes, bytearray, memoryview, str))
+                    )
+                )
+
+        duration_ms = (time.perf_counter() - started) * 1000.0
+        # MCP transport requests are logged under their own kind rather than
+        # skipped. mcp_server.py's FastMCP hook only fires for actual tool
+        # dispatch, so skipping the whole mount left `initialize`, `tools/list`
+        # and malformed JSON-RPC bodies with no record anywhere — an audit hole
+        # in a governed service. A tools/call now yields two rows, one per
+        # layer, which is honest because they are two distinct events; the
+        # `kind` keeps them unambiguously separable, and they are deliberately
+        # NOT correlated by a contextvar (the tool call re-enters through an
+        # in-process ASGI transport and may run in a different task).
+        log_call(
+            kind="mcp_http" if _is_mcp_transport_path(request.url.path) else "rest",
+            request_id=current_request_id(request),
+            method=request.method,
+            path=request.url.path,
+            status=response.status_code,
+            duration_ms=duration_ms,
+            service_name=service_name,
+            input_data=input_data,
+            output_data=output_data,
+        )
+        response.headers["X-Response-Time-Ms"] = f"{{duration_ms:.1f}}"
+        return response
+
+    @app.middleware("http")
+    async def _request_id(request: Request, call_next):
+        # Honour an inbound id so a trace survives the hop from a gateway or
+        # service mesh, but bound its length and character set: it is attacker
+        # -controlled and it ends up in log lines.
+        inbound = request.headers.get("x-request-id", "")
+        if inbound and len(inbound) <= 64 and inbound.isascii() and inbound.isprintable():
+            request_id = inbound
+        else:
+            request_id = uuid.uuid4().hex[:12]
+        request.state.request_id = request_id
+        response = await call_next(request)
+        response.headers["X-Request-ID"] = request_id
+        return response
+
+
+_DRAINING = False
+
+
+def start_draining() -> None:
+    """Stop reporting ready. Called on SIGTERM; safe to call directly."""
+    global _DRAINING
+    _DRAINING = True
+    _LOG.info("draining: /readyz will report 503 while in-flight work finishes")
+
+
+def readiness(app, service_name: str = "{service_name}"):
+    """Register `/readyz`, distinct from `/healthz` liveness.
+
+    WHAT READINESS IS ACTUALLY FOR HERE
+
+    The obvious reading — "has the app finished starting?" — is worth nothing
+    in this service. `service.py` imports `router.py`, which imports the native
+    extension at module scope, so a worker that failed to load it never becomes
+    able to answer anything at all. Any request that gets a response at all is
+    proof the extension imported. A readiness probe asserting that would be a
+    slower liveness probe.
+
+    What readiness genuinely buys is **draining**. On a rolling deploy or a
+    scale-down, the orchestrator sends SIGTERM and gunicorn stops accepting new
+    work while finishing what is in flight. Without a readiness signal the load
+    balancer keeps routing to that worker for as long as its own health check
+    interval, and those requests are refused. Reporting 503 the moment SIGTERM
+    lands takes the process out of rotation *before* it stops accepting, which
+    is the difference between a clean deploy and a burst of 502s.
+
+    Liveness must NOT do this: a draining process is deliberately not ready but
+    perfectly alive, and a liveness probe that failed here would get it killed
+    mid-request instead of drained.
+    """
+
+    # Chained, not replaced. gunicorn and uvicorn install their own SIGTERM
+    # handlers to run graceful shutdown; overwriting one would turn a graceful
+    # drain into an abrupt exit, which is the opposite of the goal.
+    try:
+        previous = signal.getsignal(signal.SIGTERM)
+
+        def _drain_then_delegate(signum, frame):
+            start_draining()
+            if callable(previous):
+                previous(signum, frame)
+
+        signal.signal(signal.SIGTERM, _drain_then_delegate)
+    except (ValueError, OSError):
+        # Not the main thread (some test runners, some embeddings). Draining is
+        # an optimisation, not a correctness requirement — carry on without it.
+        _LOG.debug("could not install a SIGTERM drain handler; /readyz is static")
+
+    @app.get("/readyz", tags=["health"])
+    def readyz():
+        if _DRAINING:
+            raise HTTPException(status_code=503, detail="draining")
+        return {{"status": "ready", "service": service_name}}
+
+    return readyz
+'''