pipelex-api 0.71.0__py3-none-any.whl

pipelex_api/method_cache.py

@@ -0,0 +1,241 @@
+"""Per-instance on-disk clone cache for fetched method packages, keyed by resolved commit SHA.
+
+A `method_ref` run fetches a public git repository. Cloning on every request would hammer
+GitHub's anonymous-clone rate limits and add seconds of latency, so this server keeps the
+clones on local disk — but **never keyed by tag**: tags can move, and a moved tag must
+change what runs. Instead, each request first resolves the reference to its commit SHA with
+a cheap `git ls-remote` (no clone), then looks the clone up by that SHA. A repointed tag or
+an advanced default branch resolves to a new SHA and therefore a fresh clone; the cached
+copy of the old SHA ages out on its own.
+
+The cache is per server instance (a directory under the system temp dir by default,
+`METHOD_CACHE_DIR` to override) and bounded three ways — clone count, total bytes, and age —
+via the `MAX_METHOD_CACHE_*` knobs in `pipelex_api.limits`. Eviction runs on insert, oldest-first by
+last use, and never evicts the most recently used entry. Package location, bounds, and the
+structures scan are NOT cached: they re-run against the cached clone on every request, so a
+deployment-mode change (or a ceiling change) applies immediately.
+
+Concurrency: clones land in a per-request staging directory and are installed with an atomic
+`rename`, so two concurrent requests for the same SHA cannot corrupt each other — the loser
+of the rename race discards its staging copy and uses the winner's. The resolution seam
+(`pipelex_api.method_source`) copies everything it needs out of the cached clone before the run
+starts, so eviction can never pull a directory out from under a running pipeline.
+"""
+
+import os
+import shutil
+import subprocess
+import tempfile
+import threading
+import time
+import uuid
+from functools import cache
+from pathlib import Path
+
+from pipelex import log
+from pipelex.methods.exceptions import MethodFetchError
+from pipelex.methods.fetching import FetchedMethodPackage, ensure_package_within_bounds, fetch_method_package
+from pipelex.methods.method_ref import MethodRef
+from pipelex.methods.package_locator import locate_package_in_clone
+from pipelex.system.environment import get_optional_env
+
+from pipelex_api.limits import MAX_METHOD_CACHE_AGE_SECONDS, MAX_METHOD_CACHE_CLONES, MAX_METHOD_CACHE_TOTAL_BYTES
+
+LS_REMOTE_TIMEOUT_SECONDS = 60
+
+_STAGING_DIR_NAME = ".staging"
+_DEFAULT_CACHE_DIR_NAME = "pipelex-api-method-cache"
+
+
+def _run_ls_remote(*, clone_url: str, ref_patterns: list[str], ref_str: str) -> list[tuple[str, str]]:
+    """Run `git ls-remote` for the given ref patterns and return `(sha, ref_name)` pairs.
+
+    Raises:
+        MethodFetchError: If git is unavailable, the remote cannot be reached, or the call times out.
+    """
+    try:
+        result = subprocess.run(  # noqa: S603 — fixed argv, no shell; the URL is derived from the validated address grammar
+            ["git", "ls-remote", clone_url, *ref_patterns],  # noqa: S607
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=LS_REMOTE_TIMEOUT_SECONDS,
+        )
+    except FileNotFoundError as exc:
+        msg = "git is not installed or not found on PATH"
+        raise MethodFetchError(msg) from exc
+    except subprocess.CalledProcessError as exc:
+        msg = f"Failed to fetch method '{ref_str}': could not reach the repository ({exc.stderr.strip()})"
+        raise MethodFetchError(msg) from exc
+    except subprocess.TimeoutExpired as exc:
+        msg = f"Timed out resolving method '{ref_str}' against the remote repository"
+        raise MethodFetchError(msg) from exc
+
+    pairs: list[tuple[str, str]] = []
+    for line in result.stdout.strip().splitlines():
+        parts = line.split("\t")
+        if len(parts) == 2:
+            pairs.append((parts[0], parts[1]))
+    return pairs
+
+
+def resolve_remote_commit_sha(*, ref: MethodRef, clone_url: str | None = None) -> str:
+    """Resolve a method reference to the commit SHA it currently points at, without cloning.
+
+    For a `@<tag>` reference, only `refs/tags/<tag>` is consulted — a branch of the same
+    name does not count, so `@main` is refused here, before any clone (the same tags-only
+    rule `pipelex.methods.fetching.ensure_cloned_at_tag` enforces after a clone). For an
+    annotated tag the peeled (`^{}`) commit SHA is returned, matching what `rev-parse HEAD`
+    reports inside a clone at that tag. A bare reference resolves the default branch `HEAD`.
+
+    Args:
+        ref: The parsed method reference.
+        clone_url: Override for the derived clone URL (tests, non-default remotes).
+
+    Returns:
+        The full commit SHA the reference resolves to right now.
+
+    Raises:
+        MethodFetchError: If the remote cannot be reached, or `@<tag>` does not name a tag.
+    """
+    effective_clone_url = clone_url or ref.clone_url
+    if ref.tag:
+        pairs = _run_ls_remote(
+            clone_url=effective_clone_url,
+            ref_patterns=[f"refs/tags/{ref.tag}", f"refs/tags/{ref.tag}^{{}}"],
+            ref_str=ref.ref_str,
+        )
+        peeled = [sha for sha, name in pairs if name.endswith("^{}")]
+        if peeled:
+            return peeled[0]
+        direct = [sha for sha, name in pairs if name == f"refs/tags/{ref.tag}"]
+        if direct:
+            return direct[0]
+        msg = (
+            f"'{ref.tag}' in method reference '{ref.ref_str}' does not name a git tag on the repository — "
+            f"`@<tag>` pins a git tag (recommended form vX.Y.Z); branch names are not accepted."
+        )
+        raise MethodFetchError(msg)
+    pairs = _run_ls_remote(clone_url=effective_clone_url, ref_patterns=["HEAD"], ref_str=ref.ref_str)
+    head = [sha for sha, name in pairs if name == "HEAD"]
+    if not head:
+        msg = f"The repository behind method reference '{ref.ref_str}' has no HEAD (empty repository?)"
+        raise MethodFetchError(msg)
+    return head[0]
+
+
+def _directory_size_bytes(directory: Path) -> int:
+    total = 0
+    for file_path in directory.rglob("*"):
+        if file_path.is_file() and not file_path.is_symlink():
+            total += file_path.stat().st_size
+    return total
+
+
+class MethodCloneCache:
+    """SHA-keyed, bounded, on-disk cache of method-package clones (see the module docstring)."""
+
+    def __init__(self, *, root_dir: Path) -> None:
+        self._root = root_dir
+        self._lock = threading.Lock()
+
+    def get_or_fetch(self, *, ref: MethodRef, clone_url: str | None = None) -> FetchedMethodPackage:
+        """Return the package a reference points at, cloning only when its SHA is not cached.
+
+        Always re-runs package location and the bounds check against the (possibly cached)
+        clone — only the clone itself is cached, never a verdict about it.
+
+        Args:
+            ref: The parsed method reference.
+            clone_url: Override for the derived clone URL (tests, non-default remotes).
+
+        Returns:
+            The fetched package, rooted inside the cache directory.
+
+        Raises:
+            MethodFetchError: If SHA resolution or the clone fails, or `@<tag>` is not a tag.
+            MethodPackageNotFoundError: If no package matches the requested address.
+            MethodPackageAmbiguityError: If more than one package matches.
+            MethodPackageTooLargeError: If the selected package exceeds the ceilings.
+        """
+        commit_sha = resolve_remote_commit_sha(ref=ref, clone_url=clone_url)
+        clone_dir = self._root / commit_sha
+        with self._lock:
+            if clone_dir.is_dir():
+                os.utime(clone_dir)  # LRU bookkeeping: mtime is the eviction order
+                return self._package_from_clone(ref=ref, clone_dir=clone_dir, commit_sha=commit_sha)
+
+        # Miss: clone into a per-request staging dir (outside the lock — clones are slow),
+        # then install atomically. A tag repointed between ls-remote and clone resolves to the
+        # clone's ACTUAL commit SHA — that is what gets recorded and keyed, never the stale one.
+        staging_root = self._root / _STAGING_DIR_NAME
+        staging_root.mkdir(parents=True, exist_ok=True)
+        staging_dir = staging_root / uuid.uuid4().hex
+        try:
+            fetched = fetch_method_package(ref=ref, dest_dir=staging_dir, clone_url=clone_url)
+            target_dir = self._root / fetched.commit_sha
+            with self._lock:
+                if not target_dir.exists():
+                    try:
+                        staging_dir.rename(target_dir)
+                    except OSError:
+                        # A concurrent request installed the same SHA between the check and the
+                        # rename; its copy is identical (same commit), so use it.
+                        log.debug(f"Method clone cache: lost the install race for {fetched.commit_sha}, reusing the winner's copy")
+                self._evict()
+                return self._package_from_clone(ref=ref, clone_dir=target_dir, commit_sha=fetched.commit_sha)
+        finally:
+            shutil.rmtree(staging_dir, ignore_errors=True)
+
+    def _package_from_clone(self, *, ref: MethodRef, clone_dir: Path, commit_sha: str) -> FetchedMethodPackage:
+        """Locate + bound the requested package inside a cached clone (never cached themselves)."""
+        located = locate_package_in_clone(clone_root=clone_dir, requested_address=ref.address)
+        ensure_package_within_bounds(package_dir=located.package_dir, package_address=located.full_address)
+        return FetchedMethodPackage(
+            ref=ref,
+            full_address=located.full_address,
+            commit_sha=commit_sha,
+            clone_dir=clone_dir,
+            package_dir=located.package_dir,
+            manifest=located.manifest,
+        )
+
+    def _evict(self) -> None:
+        """Enforce the age, count, and byte bounds — oldest-first, keeping the newest entry.
+
+        Called with the lock held, right after an install. Best-effort by design: a clone
+        directory another process already removed is simply skipped.
+        """
+        entries = sorted(
+            (entry for entry in self._root.iterdir() if entry.is_dir() and entry.name != _STAGING_DIR_NAME),
+            key=lambda entry: entry.stat().st_mtime,
+        )
+        if not entries:
+            return
+        newest = entries[-1]
+        now = time.time()
+        survivors: list[Path] = []
+        for entry in entries:
+            if entry != newest and now - entry.stat().st_mtime > MAX_METHOD_CACHE_AGE_SECONDS:
+                shutil.rmtree(entry, ignore_errors=True)
+            else:
+                survivors.append(entry)
+        total_bytes = sum(_directory_size_bytes(entry) for entry in survivors)
+        while len(survivors) > 1 and (len(survivors) > MAX_METHOD_CACHE_CLONES or total_bytes > MAX_METHOD_CACHE_TOTAL_BYTES):
+            oldest = survivors.pop(0)
+            total_bytes -= _directory_size_bytes(oldest)
+            shutil.rmtree(oldest, ignore_errors=True)
+
+
+@cache
+def get_method_clone_cache() -> MethodCloneCache:
+    """The per-instance clone cache singleton.
+
+    The root directory is `METHOD_CACHE_DIR` when set, else a fixed directory under the
+    system temp dir — per instance, surviving requests but not the host, which is exactly
+    the cache's contract (a cold instance re-clones once per SHA).
+    """
+    configured = get_optional_env("METHOD_CACHE_DIR")
+    root_dir = Path(configured) if configured else Path(tempfile.gettempdir()) / _DEFAULT_CACHE_DIR_NAME
+    root_dir.mkdir(parents=True, exist_ok=True)
+    return MethodCloneCache(root_dir=root_dir)

pipelex_api/method_source.py

@@ -0,0 +1,215 @@
+"""Resolve a `method_ref` into run/validate/tooling inputs: fetch → locate → refuse → materialize.
+
+The wire field `method_ref` carries a globally resolvable address —
+`github.com/<owner>/<repo>[/<selector>][@<tag>]` — and THIS runner is its resolver (the
+layered extension policy's Rule 3: an address needs no catalog, so it is a layer-2 concept;
+the hosted-only `method_id` never reaches this server). The grammar, the fetch-at-tag, the
+manifest-identity package location, the bounds, and the structures check all live in
+`pipelex.methods`; this module composes them behind the SHA-keyed clone cache
+(`pipelex_api.method_cache`) and shapes the result for each route family:
+
+- The run routes and `/validate` use :func:`fetched_method_source`: the package's `.mthds`
+  files travel as `mthds_contents` (paired with their real relative paths as
+  `mthds_sources`, so diagnostics carry true per-file labels), and only the non-`.mthds`
+  files are materialized into a temporary `library_dirs` entry — exactly the split the
+  method-bundle transport uses, so a fetched package runs the same proven path.
+- The tooling routes (`/resolve`, `/codegen`, `/build/*`) use
+  :func:`fetch_method_mthds_files`: only the `.mthds` files, as `files[]` items, paired with
+  the manifest's `main_pipe` so the per-pipe projections default their selector exactly as a
+  run does. No Python ever loads there, so the execution-locus gate does not apply.
+
+The security gate (packaging invariant 7 — execution locus decides): `.mthds` content is
+data, always acceptable. On a deployment that is NOT sandbox-hosted, a fetched package
+carrying ANY `.py` is refused with the same 403 the bundle transport uses
+(`CustomCodeRequiresSandbox`) — running it would import customer code in-process. On a
+sandbox-hosted deployment, PipeFunc `.py` is acceptable (captured as text, executed in the
+network-blocked sandbox) but a package declaring `StructuredContent` subclasses is refused
+loudly (`MethodStructuresRefusedError` → 403): structure classes would have to be imported into
+the runner's own process, and the rule-naming error teaches authors to express types as MTHDS
+concepts. The library load refuses the same classes again, for a bundle as for a package.
+
+Everything a run needs is copied OUT of the cached clone before this module yields — the
+`.mthds` text into memory, the rest into a per-request temp directory — so cache eviction
+can never race a running pipeline.
+"""
+
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path, PurePosixPath
+from typing import NamedTuple
+
+from mthds.package.discovery import MANIFEST_FILENAME
+from pipelex import log
+from pipelex.config import is_pipe_func_sandbox_hosted
+from pipelex.methods.fetching import FetchedMethodPackage, MethodProvenance
+from pipelex.methods.method_ref import parse_method_ref
+from pipelex.methods.structures_check import ensure_no_structured_content_python
+from pydantic import BaseModel, ConfigDict, Field
+
+from pipelex_api.bundle import ParsedBundle, materialize_parsed
+from pipelex_api.error_types import ErrorType
+from pipelex_api.errors import raise_forbidden, raise_validation_error
+from pipelex_api.limits import MAX_MTHDS_FILE_BYTES
+from pipelex_api.method_cache import get_method_clone_cache
+from pipelex_api.schemas.models import MthdsFileItem
+
+_SKIPPED_DIR_NAMES = {".git", "__pycache__"}
+
+
+class FetchedMethodSource(BaseModel):
+    """A fetched package shaped for the run/validate path (see the module docstring)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    mthds_contents: list[str]
+    mthds_sources: list[str]
+    library_dirs: list[str] | None = None
+    main_pipe: str | None = Field(default=None, description="The manifest's declared entry pipe; a request `pipe_code` overrides it.")
+    provenance: MethodProvenance
+
+
+class FetchedMthdsFiles(NamedTuple):
+    """A fetched package shaped for the tooling path: its `.mthds` files plus the manifest's entry pipe."""
+
+    files: list[MthdsFileItem]
+    """The package's `.mthds` files as `files[]` items, each labelled with its real relative path."""
+
+    main_pipe: str | None
+    """The manifest's declared `main_pipe` (a bare pipe code), or None when the manifest declares none."""
+
+
+def _fetch_package(method_ref: str) -> FetchedMethodPackage:
+    """Parse the reference and fetch its package through the SHA-keyed clone cache.
+
+    Every failure mode is a distinct pipelex `MethodRefError` subclass, rendered by the
+    global handler as RFC 7807 `problem+json` with the class name as `error_type` and the
+    status the API maps for it (`pipelex_api.exception_handlers._ERROR_TYPE_STATUS_OVERRIDES`).
+    """
+    ref = parse_method_ref(method_ref)
+    package = get_method_clone_cache().get_or_fetch(ref=ref)
+    log.info(
+        f"Resolved method_ref '{ref.ref_str}': address={package.provenance.address} "
+        f"tag={package.provenance.tag} commit_sha={package.provenance.commit_sha}"
+    )
+    return package
+
+
+def _package_files(package: FetchedMethodPackage) -> list[Path]:
+    """The package's files, deterministically ordered, with VCS/tooling residue skipped."""
+    files: list[Path] = []
+    for file_path in sorted(package.package_dir.rglob("*")):
+        relative_parts = file_path.relative_to(package.package_dir).parts
+        if any(part in _SKIPPED_DIR_NAMES for part in relative_parts):
+            continue
+        if file_path.is_file():
+            files.append(file_path)
+    return files
+
+
+def _read_mthds_text(file_path: Path, *, relative: str, package_address: str) -> str:
+    try:
+        content = file_path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        raise_validation_error(message=f"File '{relative}' in method package '{package_address}' is not valid UTF-8.")
+    if len(content.encode("utf-8")) > MAX_MTHDS_FILE_BYTES:
+        msg = f"File '{relative}' in method package '{package_address}' exceeds the {MAX_MTHDS_FILE_BYTES // 1024} KiB per-file limit."
+        raise_validation_error(message=msg)
+    return content
+
+
+def _apply_execution_locus_gate(package: FetchedMethodPackage, *, python_relpaths: list[str]) -> None:
+    """Refuse Python that would execute where it must not (see the module docstring)."""
+    if not python_relpaths:
+        return
+    if not is_pipe_func_sandbox_hosted():
+        msg = f"Method package '{package.full_address}' ships custom Python (.py); running it requires a sandbox-hosted deployment."
+        raise_forbidden(message=msg, error_type=ErrorType.CUSTOM_CODE_REQUIRES_SANDBOX)
+    ensure_no_structured_content_python(package_dir=package.package_dir, package_address=package.full_address)
+
+
+@contextmanager
+def fetched_method_source(method_ref: str) -> Generator[FetchedMethodSource, None, None]:
+    """Fetch a `method_ref`'s package and shape it for the run/validate path.
+
+    Yields the package's `.mthds` files as `(mthds_contents, mthds_sources)` pairs and its
+    non-`.mthds` files (PipeFunc `.py`, `requirements.txt`, …) materialized into a temporary
+    `library_dirs` entry, cleaned up on exit. The execution-locus gate runs before anything
+    touches disk.
+
+    Args:
+        method_ref: The raw `method_ref` string from the request.
+
+    Raises:
+        MethodRefError subclasses: parse, fetch, location, bounds, and structures failures —
+            each rendered as `problem+json` by the global handler.
+        ApiError: the 403 custom-code gate on a non-sandbox deployment, and 422s for a
+            package whose `.mthds` content this server cannot accept.
+    """
+    package = _fetch_package(method_ref)
+    files = _package_files(package)
+    python_relpaths = [file_path.relative_to(package.package_dir).as_posix() for file_path in files if file_path.suffix == ".py"]
+    _apply_execution_locus_gate(package, python_relpaths=python_relpaths)
+
+    mthds_contents: list[str] = []
+    mthds_sources: list[str] = []
+    other_entries: list[tuple[PurePosixPath, bytes]] = []
+    for file_path in files:
+        relative = file_path.relative_to(package.package_dir).as_posix()
+        if file_path.suffix == ".mthds":
+            mthds_contents.append(_read_mthds_text(file_path, relative=relative, package_address=package.full_address))
+            mthds_sources.append(relative)
+        elif file_path.name != MANIFEST_FILENAME:
+            # The manifest is already consumed (identity + `main_pipe`); materializing it into
+            # the library dir would hand the local loader a package boundary it must not see.
+            other_entries.append((PurePosixPath(relative), file_path.read_bytes()))
+    if not mthds_contents:
+        raise_validation_error(message=f"Method package '{package.full_address}' contains no .mthds file.")
+
+    if not other_entries:
+        yield FetchedMethodSource(
+            mthds_contents=mthds_contents,
+            mthds_sources=mthds_sources,
+            library_dirs=None,
+            main_pipe=package.manifest.main_pipe,
+            provenance=package.provenance,
+        )
+        return
+    with materialize_parsed(ParsedBundle(entries=tuple(other_entries))) as bundle:
+        yield FetchedMethodSource(
+            mthds_contents=mthds_contents,
+            mthds_sources=mthds_sources,
+            library_dirs=[str(bundle.directory)],
+            main_pipe=package.manifest.main_pipe,
+            provenance=package.provenance,
+        )
+
+
+def fetch_method_mthds_files(method_ref: str) -> FetchedMthdsFiles:
+    """Fetch a `method_ref`'s package and return its `.mthds` files as `files[]` items, plus its `main_pipe`.
+
+    The tooling-route shape: each item pairs the file's content with its real relative path
+    as `source`, so crate provenance and diagnostics carry true per-file labels. Only
+    `.mthds` data travels — the package's Python (if any) never loads on these routes, so
+    the execution-locus gate does not apply here. The manifest's `main_pipe` rides beside the
+    files so a per-pipe projection can default its selector the way a run does — the manifest
+    is the package author's declaration of the entry pipe, and dropping it here would make
+    `main_pipe` buy them nothing on the tooling routes.
+
+    Args:
+        method_ref: The raw `method_ref` string from the request.
+
+    Raises:
+        MethodRefError subclasses: parse, fetch, location, and bounds failures.
+        ApiError: 422 for a package with no `.mthds` file or one this server cannot accept.
+    """
+    package = _fetch_package(method_ref)
+    items: list[MthdsFileItem] = []
+    for file_path in _package_files(package):
+        if file_path.suffix != ".mthds":
+            continue
+        relative = file_path.relative_to(package.package_dir).as_posix()
+        content = _read_mthds_text(file_path, relative=relative, package_address=package.full_address)
+        items.append(MthdsFileItem(content=content, source=relative))
+    if not items:
+        raise_validation_error(message=f"Method package '{package.full_address}' contains no .mthds file.")
+    return FetchedMthdsFiles(files=items, main_pipe=package.manifest.main_pipe)

pipelex_api/middleware.py

@@ -0,0 +1,209 @@
+"""ASGI middleware shared across the FastAPI app."""
+
+import re
+import secrets
+import time
+from collections.abc import Awaitable, Callable
+
+from fastapi import Request, Response
+from fastapi.responses import JSONResponse
+from pipelex import log
+from starlette.datastructures import MutableHeaders
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from pipelex_api.error_types import ErrorType
+from pipelex_api.limits import MAX_REQUEST_BODY_BYTES, MAX_REQUEST_BODY_MIB
+from pipelex_api.problem_document import PROBLEM_JSON_MEDIA_TYPE, build_problem_document_from_api_error
+
+
+def request_id_of(request: Request) -> str | None:
+    """Return the correlation id `RequestIdMiddleware` stored on this request, or `None` when it did not run.
+
+    `getattr` rather than attribute access: a request that never went through the middleware — a unit
+    test issuing a bare ASGI call, a non-HTTP scope — simply has no id, and a reader of the id is not
+    the place to discover that. This is the one way the API reads the id back; the runtime's bound log
+    context carries the same value onto every record but is not a lookup table for anyone else.
+    """
+    return getattr(request.state, "request_id", None)
+
+
+def _too_large_response(*, request: Request) -> JSONResponse:
+    """Build the 413 RFC 7807 problem response for an over-limit request body.
+
+    The body-size check runs in middleware, before routing, so it cannot go
+    through the `pipelex_api.errors` helpers — a middleware must `return` a response,
+    not raise. It builds the same problem document directly, reading the request
+    context off the `Request` it was handed. `RequestIdMiddleware` runs outermost,
+    so the id is already on `request.state` by the time this is reached; that
+    middleware's `send` wrapper also stamps the `X-Request-ID` header onto this
+    response.
+    """
+    document = build_problem_document_from_api_error(
+        ErrorType.PAYLOAD_TOO_LARGE,
+        f"Request body exceeds {MAX_REQUEST_BODY_MIB} MiB limit",
+        413,
+        instance=request.url.path,
+        request_id=request_id_of(request),
+    )
+    return JSONResponse(status_code=413, content=document, media_type=PROBLEM_JSON_MEDIA_TYPE)
+
+
+async def request_body_size_middleware(request: Request, call_next: Callable[[Request], Awaitable[Response]]) -> Response:
+    """Reject requests whose body exceeds MAX_REQUEST_BODY_BYTES.
+
+    Two layers of defense:
+      1. Trust `Content-Length` header when present — fast reject before any body is read.
+      2. For chunked / missing-header requests, wrap `receive` so we count bytes as
+         they arrive. When the cumulative count crosses the cap, the over-limit
+         chunk is NOT forwarded: it is replaced with an end-of-stream marker so
+         `await request.body()` returns a bounded (often empty) body rather than
+         the full oversized payload, and any further read keeps returning the
+         same terminator (NOT `http.disconnect`, which would raise
+         `ClientDisconnect` and escape past the 413 override). The 413 response
+         then overrides whatever the route returned on its truncated input.
+    """
+    content_length = request.headers.get("content-length")
+    if content_length is not None:
+        try:
+            declared = int(content_length)
+        except ValueError:
+            declared = -1
+        if declared > MAX_REQUEST_BODY_BYTES:
+            return _too_large_response(request=request)
+
+    original_receive = request.receive
+    bytes_seen = 0
+    too_large = False
+
+    async def counting_receive() -> Message:
+        nonlocal bytes_seen, too_large
+        if too_large:
+            # Idempotent end-of-stream on every subsequent read. Returning
+            # `http.disconnect` instead would raise `ClientDisconnect` in
+            # Starlette's body reader, which would escape `call_next` as an
+            # exception and bypass the 413 override below — the request would
+            # land as a sanitized 500 instead of 413.
+            return {"type": "http.request", "body": b"", "more_body": False}
+        message = await original_receive()
+        if message.get("type") == "http.request":
+            body = message.get("body", b"")
+            if isinstance(body, (bytes, bytearray)):
+                bytes_seen += len(body)
+                if bytes_seen > MAX_REQUEST_BODY_BYTES:
+                    too_large = True
+                    return {"type": "http.request", "body": b"", "more_body": False}
+        return message
+
+    request._receive = counting_receive  # type: ignore[assignment]  # noqa: SLF001
+
+    response = await call_next(request)
+    if too_large:
+        return _too_large_response(request=request)
+    return response
+
+
+# --- Request correlation -----------------------------------------------------
+
+REQUEST_ID_HEADER = "X-Request-ID"
+
+# Crockford's Base32 alphabet — the ULID encoding. Excludes I, L, O, U so a
+# request id stays unambiguous if a human transcribes it out of a log.
+_CROCKFORD_BASE32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+_ULID_LENGTH = 26
+_ULID_RANDOM_BITS = 80
+_ULID_TIMESTAMP_MASK = (1 << 48) - 1
+
+# An inbound X-Request-ID is reflected into response headers, logs, and error
+# bodies, so a client-supplied value is never trusted verbatim: it must be a
+# bounded run of injection-safe characters or it is discarded. ULIDs and UUIDs
+# both satisfy this.
+_REQUEST_ID_MAX_LENGTH = 128
+_REQUEST_ID_CHARSET = re.compile(r"\A[A-Za-z0-9_-]+\Z")
+
+
+def generate_request_id() -> str:
+    """Generate a fresh ULID: a 26-char, time-sortable, URL-safe identifier.
+
+    The high 48 bits encode a millisecond Unix timestamp, so ids sort by
+    creation time; the low 80 bits are cryptographically random. The 128-bit
+    value is rendered in Crockford Base32.
+    """
+    timestamp_ms = (time.time_ns() // 1_000_000) & _ULID_TIMESTAMP_MASK
+    value = (timestamp_ms << _ULID_RANDOM_BITS) | secrets.randbits(_ULID_RANDOM_BITS)
+    digits = [""] * _ULID_LENGTH
+    for index in range(_ULID_LENGTH - 1, -1, -1):
+        value, remainder = divmod(value, 32)
+        digits[index] = _CROCKFORD_BASE32[remainder]
+    return "".join(digits)
+
+
+def _is_valid_request_id(candidate: str) -> bool:
+    """Return whether a client-supplied request id is safe to reflect back verbatim."""
+    return 0 < len(candidate) <= _REQUEST_ID_MAX_LENGTH and _REQUEST_ID_CHARSET.match(candidate) is not None
+
+
+def _resolve_request_id(scope: Scope) -> str:
+    """Return the request id for this request.
+
+    Reuses a valid inbound `X-Request-ID` header; otherwise — absent,
+    malformed, or over-long — mints a fresh ULID.
+    """
+    for name, value in scope.get("headers", []):
+        if name == b"x-request-id":
+            candidate: str = value.decode("latin-1").strip()
+            if _is_valid_request_id(candidate):
+                return candidate
+            break
+    return generate_request_id()
+
+
+class RequestIdMiddleware:
+    """Pure-ASGI middleware that assigns a correlation id to every HTTP request.
+
+    For each request it reuses a valid inbound `X-Request-ID` or mints a fresh
+    ULID, stores it on `request.state.request_id`, binds the runtime's log
+    context to that id for the duration of the request, and echoes
+    `X-Request-ID` on the response (success and error alike).
+
+    Binding the runtime's context rather than an API-owned contextvar is what
+    puts `request_id` on *every* record emitted underneath — the API's own
+    error lines, and equally the ones pipelex emits from inside a run — as an
+    attribute a structured sink indexes, with no call site having to pass it
+    and no message having to interpolate it. The binding is in-process only: a
+    run dispatched to a worker gets the id from its `RunMetadata`, where the
+    run routes put it by passing `request_id_of(request)` to the runner.
+
+    Applied in `pipelex_api.main` by wrapping the whole FastAPI app
+    (`app = RequestIdMiddleware(app)`), NOT via `app.add_middleware()`.
+    `add_middleware` always nests a middleware *inside* Starlette's
+    `ServerErrorMiddleware`, which would leave it unable to bind the context
+    for — or set a header on — the catch-all 500 that `ServerErrorMiddleware`
+    emits. Wrapping the app puts this middleware genuinely outermost, outside
+    `ServerErrorMiddleware`, so the context is bound and `X-Request-ID` is
+    echoed on every response, the catch-all 500 included. Raw ASGI (rather than
+    `BaseHTTPMiddleware`) keeps a single contextvar context across the whole
+    stack and lets the `send` wrapper inject the header on any response.
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        request_id = _resolve_request_id(scope)
+        scope.setdefault("state", {})["request_id"] = request_id
+
+        async def send_with_request_id(message: Message) -> None:
+            if message["type"] == "http.response.start":
+                MutableHeaders(scope=message)[REQUEST_ID_HEADER] = request_id
+            await send(message)
+
+        # The runtime's own context, not an API-owned one: `request_id` is one of the three run
+        # identifiers it reserves, so every record emitted underneath carries it as an attribute.
+        # The route path is deliberately not bound here — it is not a run identifier, and the API
+        # ships it as a `route` field on the lines that want it (see `pipelex_api.exception_handlers`).
+        with log.context(request_id=request_id):
+            await self.app(scope, receive, send_with_request_id)