Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
feature/Deep-json-422-depends · L-261001-414c11 (#1311)
Louis Choquel4182de4c1b70
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ab84a8520..0e867efe2 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -22,6 +22,8 @@### Fixed+- **The API server refuses a deeply nested body the same way on every Python**: a JSON request body whose arrays and objects nest deeper than 128 levels, its own envelope included, is now refused before it is parsed, on every route that takes one, with a 422 `InvalidJSON` saying it is nested too deeply. On Python 3.14 whether the run routes refused such a body depended on the size of the thread's stack, so it could reach validation and fail as a `ValidationError` or be accepted, and the other routes answered it with a bare 400 rather than a problem document.+- **A client leaving mid-upload is a 400 in the API server's logs**: when a client disconnects before its request body arrived in full, the server answers a 400 `BadRequest` and logs it at warning level, where the run routes logged a 500 server fault with a traceback.- **The API image runs methods by address**: the image carries `git`, which fetching a method named by `method_ref` needs, where the `0.33.2` image removed it with the build tools and failed every such run.## [v0.70.0] - 2026-09-29diff --git a/api/CLAUDE.md b/api/CLAUDE.mdindex 34aba46a6..cc2ad557b 100644--- a/api/CLAUDE.md+++ b/api/CLAUDE.md@@ -174,6 +174,7 @@ except SomeSpecificError as exc:- One router per feature domain, tagged for OpenAPI: `APIRouter(tags=["pipeline"])`- Routers composed hierarchically in `routes/__init__.py`+- A router whose routes declare a JSON body is built with `route_class=JsonBodyRoute` (`pipelex_api/json_body.py`), which refuses a body nested deeper than `MAX_JSON_NESTING_DEPTH` before FastAPI parses it; `tests/unit/test_json_body.py` fails on a body-declaring route that is not one. A route that reads its raw body parses it with `decode_json_body`, never with a bare `json.loads`- Auth applied at router level via `dependencies=[Depends(auth_dependency)]`- Health check endpoint excluded from authdiff --git a/api/pipelex_api/exception_handlers.py b/api/pipelex_api/exception_handlers.pyindex c3b93e10f..06c38e50f 100644--- a/api/pipelex_api/exception_handlers.py+++ b/api/pipelex_api/exception_handlers.py@@ -36,6 +36,7 @@ from fastapi.responses import JSONResponsefrom pipelex import logfrom pipelex.base_exceptions import DisclosureMode, ErrorDomain, ErrorReport, PipelexErrorfrom pipelex.plugins.registrar import HttpErrorMapperFn+from starlette.requests import ClientDisconnectfrom pipelex_api.error_types import ErrorTypefrom pipelex_api.errors import ApiError@@ -54,7 +55,7 @@ if TYPE_CHECKING:_ExceptionHandler = Callable[[Request, Exception], Awaitable[Response]]# The value of the `event` field every error record carries: the one key a log sink filters this-# server's error stream on, whichever of the three handlers below produced the record.+# server's error stream on, whichever of the handlers below produced the record.API_ERROR_EVENT = "api_error"@@ -615,6 +616,26 @@ async def handle_request_validation_error(request: Request, exc: Exception) -> Rreturn JSONResponse(status_code=422, content=document, media_type=PROBLEM_JSON_MEDIA_TYPE)+async def handle_client_disconnect(request: Request, exc: Exception) -> Response: # noqa: ARG001 — Starlette's handler contract+ """Answer a client that left before its request body arrived in full with a 400, logged as a caller's failure.++ Starlette raises `ClientDisconnect` from a body read when the client goes away mid-upload: from the+ nesting check of a `JsonBodyRoute`, and from the run routes, which read their raw body themselves.+ Nobody is left to read the answer, so what matters is the record it leaves: a 400 `BadRequest` at+ `warning`, as FastAPI's own body read answered it, never a 500 server fault logged with a traceback.+ """+ document = build_problem_document_from_api_error(+ ErrorType.BAD_REQUEST,+ "The client disconnected before the request body was received in full.",+ 400,+ instance=request.url.path,+ request_id=request_id_of(request),+ error_domain=ErrorDomain.INPUT,+ )+ _log_api_authored_error(document=document, status=400, request=request)+ return JSONResponse(status_code=400, content=document, media_type=PROBLEM_JSON_MEDIA_TYPE)++def register_exception_handlers(app: FastAPI,*,@@ -626,6 +647,8 @@ def register_exception_handlers(Resolution is most-specific-first: an API-authored `ApiError` →`handle_api_error`; a FastAPI `RequestValidationError` (automaticrequest-body / parameter validation) → `handle_request_validation_error`; a+ Starlette `ClientDisconnect` (the client left mid-upload) →+ `handle_client_disconnect`; a`PipelexError` (including an orchestrator plugin's `PipelexError`-derivedworkflow failure) → `handle_pipelex_error`; a bare orchestrator-SDK transporterror → that plugin's mapper-backed handler (see `http_error_mappers`);@@ -652,7 +675,7 @@ def register_exception_handlers((`handle_pipelex_error` and every mapper handler) via the closures below —production passes the startup-resolved value (`pipelex_api.main.ERROR_DISCLOSURE_MODE`);tests pass whatever the test needs and the default (`VERBOSE`) covers the common- case. The other three handlers don't render an `ErrorReport`, so they register+ case. The other handlers don't render an `ErrorReport`, so they registerdirectly — `handle_unexpected_error` still honors the mode, reading it back off`app.state` (set below) rather than through a closure."""@@ -663,6 +686,7 @@ def register_exception_handlers(app.add_exception_handler(ApiError, handle_api_error)app.add_exception_handler(RequestValidationError, handle_request_validation_error)+ app.add_exception_handler(ClientDisconnect, handle_client_disconnect)app.add_exception_handler(PipelexError, _pipelex_error)for exc_type, mapper in (http_error_mappers or {}).items():app.add_exception_handler(exc_type, _make_orchestrator_error_handler(mapper, disclosure_mode=disclosure_mode))diff --git a/api/pipelex_api/json_body.py b/api/pipelex_api/json_body.pynew file mode 100644index 000000000..03d53528d--- /dev/null+++ b/api/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_handlerdiff --git a/api/pipelex_api/limits.py b/api/pipelex_api/limits.pyindex 3e3c3e562..721bee1bc 100644--- a/api/pipelex_api/limits.py+++ b/api/pipelex_api/limits.py@@ -13,6 +13,15 @@ DEFAULT_MAX_MTHDS_FILE_KIB = 1024 # 1 MiB per .mthds fileDEFAULT_MAX_MTHDS_FILES_PER_REQUEST = 16DEFAULT_MAX_PIPE_CODE_LEN = 256MAX_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 = 128DEFAULT_MAX_CALLBACK_URLS = 5DEFAULT_MAX_CALLBACK_URL_LEN = 2048DEFAULT_MAX_AGENT_SPEC_KIB = 256 # 256 KiB for JSON concept/pipe specsdiff --git a/api/pipelex_api/routes/pipelex/agent/concept.py b/api/pipelex_api/routes/pipelex/agent/concept.pyindex c7711479a..96bac9fe9 100644--- a/api/pipelex_api/routes/pipelex/agent/concept.py+++ b/api/pipelex_api/routes/pipelex/agent/concept.py@@ -8,9 +8,10 @@ from pipelex.builder.operations.concept_ops import concept_spec_to_toml, parse_cfrom pydantic import BaseModel, Field, ValidationError, field_validatorfrom pipelex_api.errors import raise_validation_error+from pipelex_api.json_body import JsonBodyRoutefrom pipelex_api.limits import MAX_AGENT_SPEC_BYTES-router = APIRouter(tags=["agent"])+router = APIRouter(tags=["agent"], route_class=JsonBodyRoute)class BuildConceptRequest(BaseModel):diff --git a/api/pipelex_api/routes/pipelex/agent/pipe_spec.py b/api/pipelex_api/routes/pipelex/agent/pipe_spec.pyindex 55c961324..a57e7d731 100644--- a/api/pipelex_api/routes/pipelex/agent/pipe_spec.py+++ b/api/pipelex_api/routes/pipelex/agent/pipe_spec.py@@ -8,9 +8,10 @@ from pipelex.builder.operations.pipe_ops import parse_pipe_spec, pipe_spec_to_tofrom pydantic import BaseModel, Field, ValidationError, field_validatorfrom pipelex_api.errors import raise_validation_error+from pipelex_api.json_body import JsonBodyRoutefrom pipelex_api.limits import MAX_AGENT_SPEC_BYTES-router = APIRouter(tags=["agent"])+router = APIRouter(tags=["agent"], route_class=JsonBodyRoute)class BuildPipeSpecRequest(BaseModel):diff --git a/api/pipelex_api/routes/pipelex/build/inputs.py b/api/pipelex_api/routes/pipelex/build/inputs.pyindex 71d39e838..04d9c664a 100644--- a/api/pipelex_api/routes/pipelex/build/inputs.py+++ b/api/pipelex_api/routes/pipelex/build/inputs.py@@ -8,6 +8,7 @@ from pipelex.pipe_machinery.rendering.input_renderer import InputsTemplateFormatfrom pipelex.pipeline.exceptions import ValidateBundleErrorfrom pydantic import BaseModel, Field, model_validator+from pipelex_api.json_body import JsonBodyRoutefrom pipelex_api.openapi_responses import PROBLEM_404_METHOD_PACKAGE, PROBLEM_501_METHOD_REFfrom pipelex_api.routes.pipelex.crate_ops import (CrateInvalidReport,@@ -19,7 +20,7 @@ from pipelex_api.routes.pipelex.crate_ops import ()from pipelex_api.schemas.models import MthdsPipeRequest-router = APIRouter(tags=["build"])+router = APIRouter(tags=["build"], route_class=JsonBodyRoute)INPUTS_GENERATED_MESSAGE = "Inputs template generated successfully"NO_INPUTS_MESSAGE = "This pipe declares no inputs — the template is empty."diff --git a/api/pipelex_api/routes/pipelex/build/output.py b/api/pipelex_api/routes/pipelex/build/output.pyindex bb8f4c2ff..1bc2c4007 100644--- a/api/pipelex_api/routes/pipelex/build/output.py+++ b/api/pipelex_api/routes/pipelex/build/output.py@@ -9,6 +9,7 @@ from pipelex.pipeline.exceptions import ValidateBundleErrorfrom pydantic import BaseModel, Field, model_validatorfrom pipelex_api.errors import raise_validation_error+from pipelex_api.json_body import JsonBodyRoutefrom pipelex_api.openapi_responses import PROBLEM_404_METHOD_PACKAGE, PROBLEM_501_METHOD_REFfrom pipelex_api.routes.pipelex.crate_ops import (CrateInvalidReport,@@ -20,7 +21,7 @@ from pipelex_api.routes.pipelex.crate_ops import ()from pipelex_api.schemas.models import MthdsPipeRequest-router = APIRouter(tags=["build"])+router = APIRouter(tags=["build"], route_class=JsonBodyRoute)class BuildOutputRequest(MthdsPipeRequest):diff --git a/api/pipelex_api/routes/pipelex/build/runner.py b/api/pipelex_api/routes/pipelex/build/runner.pyindex 4b03209b9..03a6bd74d 100644--- a/api/pipelex_api/routes/pipelex/build/runner.py+++ b/api/pipelex_api/routes/pipelex/build/runner.py@@ -25,6 +25,7 @@ from pipelex.tools.typing.pydantic_utils import empty_list_factory_offrom pydantic import BaseModel, Fieldfrom pipelex_api.errors import raise_validation_error+from pipelex_api.json_body import JsonBodyRoutefrom pipelex_api.openapi_responses import PROBLEM_404_METHOD_PACKAGE, PROBLEM_501_METHOD_REFfrom pipelex_api.routes.pipelex.crate_ops import (CrateInvalidReport,@@ -37,7 +38,7 @@ from pipelex_api.routes.pipelex.crate_ops import (from pipelex_api.routes.pipelex.pipeline import get_request_user_idfrom pipelex_api.schemas.models import ALLOW_SIGNATURES_DESCRIPTION, CallerAnalyticsGroupsMixin, MthdsPipeRequest-router = APIRouter(tags=["build"])+router = APIRouter(tags=["build"], route_class=JsonBodyRoute)class BuildRunnerRequest(MthdsPipeRequest, CallerAnalyticsGroupsMixin):diff --git a/api/pipelex_api/routes/pipelex/codegen.py b/api/pipelex_api/routes/pipelex/codegen.pyindex 9deed3be4..c52bc0cd8 100644--- a/api/pipelex_api/routes/pipelex/codegen.py+++ b/api/pipelex_api/routes/pipelex/codegen.py@@ -12,6 +12,7 @@ from pipelex.tools.misc.package_utils import get_package_versionfrom pipelex.tools.typing.pydantic_utils import empty_list_factory_offrom pydantic import BaseModel, Field, model_validator+from pipelex_api.json_body import JsonBodyRoutefrom pipelex_api.openapi_responses import PROBLEM_404_METHOD_PACKAGE, PROBLEM_501_METHOD_REFfrom pipelex_api.routes.pipelex.crate_ops import (CrateInvalidReport,@@ -22,7 +23,7 @@ from pipelex_api.routes.pipelex.crate_ops import ()from pipelex_api.schemas.models import MthdsFilesRequest-router = APIRouter(tags=["codegen"])+router = APIRouter(tags=["codegen"], route_class=JsonBodyRoute)class CodegenRouteKind(StrEnum):diff --git a/api/pipelex_api/routes/pipelex/pipe_io.py b/api/pipelex_api/routes/pipelex/pipe_io.pyindex 849731916..db945f1fd 100644--- a/api/pipelex_api/routes/pipelex/pipe_io.py+++ b/api/pipelex_api/routes/pipelex/pipe_io.py@@ -11,6 +11,7 @@ from pipelex.pipeline.validate_bundle import build_pending_signaturesfrom pipelex.tools.typing.pydantic_utils import empty_list_factory_offrom pydantic import BaseModel, Field+from pipelex_api.json_body import JsonBodyRoutefrom pipelex_api.openapi_responses import PROBLEM_404_METHOD_PACKAGE, PROBLEM_501_METHOD_REFfrom pipelex_api.routes.pipelex.crate_ops import (CrateInvalidReport,@@ -26,7 +27,7 @@ from pipelex_api.schemas.models import MthdsFileItem, MthdsPipeRequestif TYPE_CHECKING:from pipelex.pipe_machinery.pipe_abstract import PipeAbstract-router = APIRouter(tags=["pipe-io"])+router = APIRouter(tags=["pipe-io"], route_class=JsonBodyRoute)class PipeIORequest(MthdsPipeRequest):diff --git a/api/pipelex_api/routes/pipelex/pipeline.py b/api/pipelex_api/routes/pipelex/pipeline.pyindex 83c61c248..6516412e3 100644--- a/api/pipelex_api/routes/pipelex/pipeline.py+++ b/api/pipelex_api/routes/pipelex/pipeline.py@@ -2,7 +2,6 @@ from __future__ import annotationsimport hashlibimport hmac-import jsonfrom contextlib import contextmanagerfrom pathlib import Path, PurePosixPathfrom typing import TYPE_CHECKING, Annotated, Any, NamedTuple, cast@@ -30,6 +29,7 @@ from pipelex_api.api_config import get_api_config, resolve_orchestration_modefrom pipelex_api.bundle import ParsedBundle, materialize_parsed, parse_bundlefrom pipelex_api.error_types import ErrorTypefrom pipelex_api.errors import raise_bad_request, raise_forbidden, raise_validation_error+from pipelex_api.json_body import decode_json_bodyfrom pipelex_api.method_source import fetched_method_sourcefrom pipelex_api.middleware import request_id_offrom pipelex_api.openapi_responses import (@@ -545,7 +545,7 @@ def _find_reserved_object_key(payload: object) -> str | None:def _decode_body(body: bytes) -> dict[str, Any]:"""Parse the run body as plain JSON and confirm it is an object free of class markers. Raises 422 if not.- The body is parsed with `json.loads`, never with kajson. kajson reads a+ The body is parsed as plain JSON by `decode_json_body`, never with kajson. kajson reads a`{"__class__": ..., "__module__": ...}` object as an order to import that module andinstantiate that class, so decoding a caller's body with it let any caller run code on theserver (`subprocess.Popen` included) before a single field was validated. The MTHDS Protocol@@ -555,20 +555,12 @@ def _decode_body(body: bytes) -> dict[str, Any]:back to life the moment the runtime round-trips the inputs through kajson. So a key a kajsondecoder treats as a marker is refused at any depth with a 422 `ReservedObjectKey`.- The parse failures are caller mistakes, so they map to a 422 `InvalidJSON` rather than a- sanitized 500:- - `UnicodeDecodeError` — the body bytes are not valid UTF-8.- - `ValueError` — `json.JSONDecodeError` (it subclasses `ValueError`).- - `RecursionError` — a deeply nested JSON array or object exhausts the parser's- recursion budget.+ The parse is `decode_json_body`'s, so its failures are caller mistakes answered with a 422+ `InvalidJSON` rather than a sanitized 500: a body nested deeper than `MAX_JSON_NESTING_DEPTH`,+ refused before it is parsed whatever the interpreter and its stack, a body that is not UTF-8,+ and one that is not JSON."""- try:- decoded = 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,- )+ decoded = decode_json_body(body)if not isinstance(decoded, dict):raise_validation_error(message="Request body must be a JSON object",diff --git a/api/pipelex_api/routes/pipelex/resolve.py b/api/pipelex_api/routes/pipelex/resolve.pyindex 8676063cd..22fb7690b 100644--- a/api/pipelex_api/routes/pipelex/resolve.py+++ b/api/pipelex_api/routes/pipelex/resolve.py@@ -7,6 +7,7 @@ from pipelex.codegen.crate_encoding import encode_crate_jsonfrom pipelex.pipeline.exceptions import ValidateBundleErrorfrom pydantic import BaseModel, Field+from pipelex_api.json_body import JsonBodyRoutefrom pipelex_api.openapi_responses import PROBLEM_404_METHOD_PACKAGE, PROBLEM_501_METHOD_REFfrom pipelex_api.routes.pipelex.crate_ops import (CrateInvalidReport,@@ -16,7 +17,7 @@ from pipelex_api.routes.pipelex.crate_ops import ()from pipelex_api.schemas.models import MthdsFilesRequest-router = APIRouter(tags=["resolve"])+router = APIRouter(tags=["resolve"], route_class=JsonBodyRoute)class ResolveValidReport(BaseModel):diff --git a/api/pipelex_api/routes/pipelex/tools.py b/api/pipelex_api/routes/pipelex/tools.pyindex 17df2b848..b6a344831 100644--- a/api/pipelex_api/routes/pipelex/tools.py+++ b/api/pipelex_api/routes/pipelex/tools.py@@ -7,9 +7,10 @@ from fastapi import APIRouterfrom pydantic import BaseModel, Field, field_validatorfrom pipelex_api.errors import raise_validation_error+from pipelex_api.json_body import JsonBodyRoutefrom pipelex_api.limits import MAX_MTHDS_FILE_BYTES-router = APIRouter(tags=["tools"])+router = APIRouter(tags=["tools"], route_class=JsonBodyRoute)class MthdsToolRequest(BaseModel):diff --git a/api/pipelex_api/routes/pipelex/validate.py b/api/pipelex_api/routes/pipelex/validate.pyindex 7dad0c313..6cdd388fe 100644--- a/api/pipelex_api/routes/pipelex/validate.py+++ b/api/pipelex_api/routes/pipelex/validate.py@@ -14,12 +14,13 @@ from pydantic import BaseModel, Field, model_validatorfrom pipelex_api.errors import raise_validation_errorfrom pipelex_api.exception_handlers import problem_response_from_error_report+from pipelex_api.json_body import JsonBodyRoutefrom pipelex_api.method_source import fetched_method_sourcefrom pipelex_api.openapi_responses import PROBLEM_403_RUN_POLICY, PROBLEM_404_METHOD_PACKAGEfrom pipelex_api.routes.pipelex.pipeline import ApiRunner, get_request_user_idfrom pipelex_api.schemas.models import CallerAnalyticsGroupsMixin, MthdsContentsRequest-router = APIRouter(tags=["validate"])+router = APIRouter(tags=["validate"], route_class=JsonBodyRoute)class RenderFormat(StrEnum):diff --git a/api/pyproject.toml b/api/pyproject.tomlindex 54d3b3318..2bf19c5c3 100644--- a/api/pyproject.toml+++ b/api/pyproject.toml@@ -381,6 +381,7 @@ runtime-evaluated-base-classes = ["tests/**/*.py" = ["T201", # Allow print statements in test files"INP001", # Allow test files to not have __init__.py in their directories (avoids namespace collisions)+ "S311", # Seeded pseudo-random test data is not cryptography]"scripts/**/*.py" = ["INP001", # scripts/ is a directory of standalone entry points, not a packagediff --git a/api/tests/unit/test_exception_handlers.py b/api/tests/unit/test_exception_handlers.pyindex da7eb671a..b34dee41e 100644--- a/api/tests/unit/test_exception_handlers.py+++ b/api/tests/unit/test_exception_handlers.py@@ -8,6 +8,8 @@ SDK), and uncaught `Exception` each end up at their respective handler exactlythe way the real app routes them."""+import asyncio+import jsonimport refrom typing import Any, cast@@ -32,6 +34,7 @@ from pipelex.plugins.registrar import HttpErrorMapperFn, PluginOrigin, PluginRegfrom pipelex.system.exceptions import EnvVarNotFoundErrorfrom pydantic import BaseModel, ConfigDictfrom pytest_mock import MockerFixture+from starlette.types import Message, Scopefrom typing_extensions import overridefrom pipelex_api.error_types import ErrorType@@ -39,6 +42,8 @@ from pipelex_api.errors import raise_internal_server_error, raise_validation_errfrom pipelex_api.exception_handlers import API_ERROR_EVENT, register_exception_handlersfrom pipelex_api.middleware import REQUEST_ID_HEADER, RequestIdMiddlewarefrom pipelex_api.problem_document import PROBLEM_JSON_MEDIA_TYPE+from pipelex_api.routes.pipelex.pipeline import router as pipeline_router+from pipelex_api.routes.pipelex.tools import router as tools_routerfrom pipelex_api.security import RequestUser# Crockford Base32, 26 chars — the ULID alphabet RequestIdMiddleware mints.@@ -655,6 +660,57 @@ class TestExceptionHandlers:assert fields["detail"] == "a caller-side mistake"log_spy.error.assert_not_called()+ @pytest.mark.parametrize("path", ["/v1/lint", "/v1/execute"], ids=["typed-body-route", "raw-body-run-route"])+ def test_client_disconnect_is_a_400_logged_as_a_warning(self, mocker: MockerFixture, path: str):+ # A client that leaves mid-upload makes the body read raise `ClientDisconnect`, from a typed route's+ # nesting check or from a run route's own read. It is the caller's failure: a 400 at warning, never a+ # 500 server fault with a traceback.+ log_spy = mocker.patch("pipelex_api.exception_handlers.log")+ app = FastAPI()+ register_exception_handlers(app)+ app.include_router(tools_router, prefix="/v1")+ app.include_router(pipeline_router, prefix="/v1")+ sent: list[Message] = []+ reads = 0++ async def receive() -> Message:+ # The first read gets the start of the body; every later one finds the client gone.+ nonlocal reads+ reads += 1+ if reads == 1:+ return {"type": "http.request", "body": b'{"content": "dom', "more_body": True}+ return {"type": "http.disconnect"}++ async def send(message: Message) -> None:+ sent.append(message)++ scope: Scope = {+ "type": "http",+ "asgi": {"version": "3.0"},+ "http_version": "1.1",+ "method": "POST",+ "scheme": "http",+ "path": path,+ "raw_path": path.encode(),+ "root_path": "",+ "query_string": b"",+ "headers": [(b"content-type", b"application/json")],+ "client": ("testclient", 50000),+ "server": ("testserver", 80),+ }+ asyncio.run(app(scope, receive, send))++ start = next(message for message in sent if message["type"] == "http.response.start")+ assert start["status"] == 400+ body = json.loads(b"".join(message.get("body", b"") for message in sent if message["type"] == "http.response.body"))+ assert body["error_type"] == "BadRequest"+ assert body["error_domain"] == "input"+ log_spy.warning.assert_called_once()+ fields = _emitted_fields(log_spy, as_error=False)+ assert fields["status"] == 400+ assert fields["error_type"] == "BadRequest"+ log_spy.error.assert_not_called()+def test_the_summary_message_names_the_status_and_the_error_type(self, mocker: MockerFixture):# The message is built from server-authored values alone, so it stays a stable sentence# whatever a caller sent; everything variable is a field beside it.diff --git a/api/tests/unit/test_json_body.py b/api/tests/unit/test_json_body.pynew file mode 100644index 000000000..c0a529e48--- /dev/null+++ b/api/tests/unit/test_json_body.py@@ -0,0 +1,238 @@+"""The nesting-depth bound on JSON request bodies (`pipelex_api.json_body`).++Up to Python 3.13 `json.loads` raised `RecursionError` on a deeply nested body at a fixed count; from 3.14+it raises only when the thread's stack runs out, so the same body was refused on one host and parsed on+another. The server now bounds the depth itself, before parsing. These tests pin the scan (exact on valid+JSON, blind to brackets inside strings, linear at the body cap), the 422 `InvalidJSON` a body past the+limit gets on a route with a typed body, and the invariant that every such route of the app is checked.+The run routes, which parse their raw body, are covered in `test_pipeline_routes.py`.+"""++import json+import random+from collections.abc import Callable+from typing import cast++import pytest+from fastapi import FastAPI+from fastapi.routing import APIRoute+from fastapi.testclient import TestClient+from pytest_mock import MockerFixture++from pipelex_api.errors import ApiError+from pipelex_api.exception_handlers import register_exception_handlers+from pipelex_api.json_body import JsonBodyRoute, decode_json_body, json_nesting_exceeds+from pipelex_api.limits import MAX_JSON_NESTING_DEPTH, MAX_REQUEST_BODY_BYTES+from pipelex_api.problem_document import PROBLEM_JSON_MEDIA_TYPE+from pipelex_api.routes import router as api_router+from tests.unit._constants import VALID_MTHDS++# Deep enough to exhaust the parser's recursion budget on Python 3.13 and earlier.+RECURSION_DEEP = 100_000++# Strings full of what the scan must not count: brackets, braces, escaped quotes and backslashes.+TRICKY_STRINGS = ["", "[", "]]", "{[", '"', '\\"', "\\", "\\\\", '"]', '[\\"{', "é[", " ", "\\u0022["]+++def _nested_arrays(depth: int) -> bytes:+ return b"[" * depth + b"]" * depth+++def _nested_objects(depth: int) -> bytes:+ return b'{"k":' * depth + b"null" + b"}" * depth if depth else b"null"+++def _nested_mixed(depth: int) -> bytes:+ opening = b"".join(b'{"k":' if level % 2 else b"[" for level in range(depth))+ closing = b"".join(b"}" if level % 2 else b"]" for level in reversed(range(depth)))+ return opening + b"0" + closing+++def _parsed_depth(value: object) -> int:+ """Return how deep a parsed JSON value nests its lists and dicts, walked without recursion."""+ deepest = 0+ stack: list[tuple[object, int]] = [(value, 1)]+ while stack:+ current, level = stack.pop()+ children: list[object]+ if isinstance(current, dict):+ children = list(cast("dict[str, object]", current).values())+ elif isinstance(current, list):+ children = cast("list[object]", current)+ else:+ continue+ deepest = max(deepest, level)+ stack.extend((child, level + 1) for child in children)+ return deepest+++def _random_value(rng: random.Random, *, budget: int) -> object:+ roll = rng.random()+ if budget > 0 and roll < 0.4:+ return [_random_value(rng, budget=budget - 1) for _ in range(rng.randint(0, 3))]+ if budget > 0 and roll < 0.8:+ return {rng.choice(TRICKY_STRINGS): _random_value(rng, budget=budget - 1) for _ in range(rng.randint(0, 3))}+ return rng.choice([*TRICKY_STRINGS, 0, 1.5, True, None])+++def _client() -> TestClient:+ app = FastAPI()+ app.include_router(api_router, prefix="/v1")+ register_exception_handlers(app)+ return TestClient(app)+++class TestJsonBodyNesting:+ @pytest.mark.parametrize("nested", [_nested_arrays, _nested_objects, _nested_mixed])+ def test_counts_arrays_and_objects_up_to_the_limit(self, nested: Callable[[int], bytes]):+ at_limit = nested(MAX_JSON_NESTING_DEPTH)+ past_limit = nested(MAX_JSON_NESTING_DEPTH + 1)+ assert _parsed_depth(json.loads(at_limit)) == MAX_JSON_NESTING_DEPTH+ assert not json_nesting_exceeds(at_limit, max_depth=MAX_JSON_NESTING_DEPTH)+ assert json_nesting_exceeds(past_limit, max_depth=MAX_JSON_NESTING_DEPTH)++ @pytest.mark.parametrize(+ ("body", "depth"),+ [+ (b'["' + b"[" * 1000 + b'"]', 1),+ (b'["\\"' + b"[{" * 1000 + b'"]', 1),+ (b'{"\\"[[[": "]]]\\\\", "k": [["\\"\\\\\\"[[["]]}', 3),+ (b'["\\u0022' + b"[" * 1000 + b'"]', 1),+ (b'["\\\\", ' + _nested_arrays(MAX_JSON_NESTING_DEPTH) + b"]", MAX_JSON_NESTING_DEPTH + 1),+ (b'{"\\\\\\\\": "\\\\\\"", "k": ' + _nested_objects(MAX_JSON_NESTING_DEPTH) + b"}", MAX_JSON_NESTING_DEPTH + 1),+ ],+ ids=[+ "brackets-in-a-string",+ "brackets-after-an-escaped-quote",+ "keys-and-values-with-escapes",+ "brackets-after-a-unicode-escaped-quote",+ "nesting-after-an-escaped-backslash",+ "nesting-after-escaped-backslashes-and-quotes",+ ],+ )+ def test_brackets_inside_strings_do_not_count(self, body: bytes, depth: int):+ # Each body is valid JSON, so the parser states its true depth. An escaped quote leaves its string+ # open, while a quote after an escaped backslash closes it.+ assert _parsed_depth(json.loads(body)) == depth+ assert not json_nesting_exceeds(body, max_depth=depth)+ assert json_nesting_exceeds(body, max_depth=depth - 1)++ def test_matches_the_parsed_depth_of_random_documents(self):+ rng = random.Random(20261001)+ for _ in range(300):+ document = _random_value(rng, budget=rng.randint(0, 10))+ body = json.dumps(document, ensure_ascii=rng.random() < 0.5).encode("utf-8")+ depth = _parsed_depth(document)+ for max_depth in range(12):+ assert json_nesting_exceeds(body, max_depth=max_depth) == (depth > max_depth), (body, max_depth)++ @pytest.mark.parametrize("chunk_bytes", [1, 2, 3, 7, 64])+ def test_chunk_boundaries_do_not_change_the_answer(self, mocker: MockerFixture, chunk_bytes: int):+ # The scan splits at quotes and measures runs a chunk at a time; tiny chunks cut strings, escapes+ # and runs at every possible point, and the answer must stay the parsed depth.+ mocker.patch("pipelex_api.json_body._CHUNK_BYTES", chunk_bytes)+ rng = random.Random(chunk_bytes)+ for _ in range(60):+ document = _random_value(rng, budget=rng.randint(0, 8))+ body = json.dumps(document).encode("utf-8")+ depth = _parsed_depth(document)+ for max_depth in range(10):+ assert json_nesting_exceeds(body, max_depth=max_depth) == (depth > max_depth), (body, max_depth)++ @pytest.mark.parametrize(+ "body",+ [+ b"[" * RECURSION_DEEP,+ b'{"inputs": ' + b"[" * RECURSION_DEEP,+ b"[" * RECURSION_DEEP + b"}" * RECURSION_DEEP,+ b'{"a": "an escaped quote \\" then ' + b"]" * 10 + b'", ' + b"[" * RECURSION_DEEP,+ ],+ ids=["unclosed-arrays", "unclosed-inside-an-object", "mismatched-closers", "unclosed-after-a-string"],+ )+ def test_refuses_a_deep_body_that_is_not_valid_json(self, body: bytes):+ # A parser recurses through an unclosed body before it finds the end, so the scan reports the+ # depth it would reach whether or not the brackets ever close.+ assert json_nesting_exceeds(body, max_depth=MAX_JSON_NESTING_DEPTH)++ @pytest.mark.parametrize("encoding", ["utf-16", "utf-16-le", "utf-16-be", "utf-32", "utf-8-sig"])+ def test_reads_every_encoding_the_parser_accepts(self, encoding: str):+ # FastAPI hands a typed body's bytes to `json.loads`, which also accepts UTF-16 and UTF-32: the scan+ # must see the brackets those encodings spell, and their escaped quotes.+ within = '["\\"[[[", ' + "[" * (MAX_JSON_NESTING_DEPTH - 1) + "]" * (MAX_JSON_NESTING_DEPTH - 1) + "]"+ past = '["\\"]]]", ' + "[" * MAX_JSON_NESTING_DEPTH + "]" * MAX_JSON_NESTING_DEPTH + "]"+ assert _parsed_depth(json.loads(within.encode(encoding))) == MAX_JSON_NESTING_DEPTH+ assert not json_nesting_exceeds(within.encode(encoding), max_depth=MAX_JSON_NESTING_DEPTH)+ assert json_nesting_exceeds(past.encode(encoding), max_depth=MAX_JSON_NESTING_DEPTH)++ def test_scans_bodies_at_the_size_cap(self):+ # No timing is asserted; a body as large as the server accepts must simply be answered, exactly.+ # One is mostly a string full of brackets, the other is nothing but small arrays.+ string_heavy_head = b'{"doc": "'+ string_heavy_tail = b'", "deep": ' + _nested_arrays(MAX_JSON_NESTING_DEPTH) + b"}"+ filler = b'[{\\"' * ((MAX_REQUEST_BODY_BYTES - len(string_heavy_head) - len(string_heavy_tail)) // 4)+ assert json_nesting_exceeds(string_heavy_head + filler + string_heavy_tail, max_depth=MAX_JSON_NESTING_DEPTH)+ assert not json_nesting_exceeds(string_heavy_head + filler + string_heavy_tail, max_depth=MAX_JSON_NESTING_DEPTH + 1)++ flat = b"[" + b"[]," * ((MAX_REQUEST_BODY_BYTES - 4) // 3) + b"[]]"+ assert not json_nesting_exceeds(flat, max_depth=2)+ assert json_nesting_exceeds(flat, max_depth=1)++ def test_typed_route_refuses_a_body_past_the_limit(self):+ # The lint route declares its body, so FastAPI parses it: the check runs in front of FastAPI.+ response = _client().post(+ "/v1/lint",+ content=b'{"content": ' + json.dumps(VALID_MTHDS).encode() + b', "padding": ' + _nested_arrays(MAX_JSON_NESTING_DEPTH) + b"}",+ headers={"content-type": "application/json"},+ )++ assert response.status_code == 422, response.text+ assert response.headers["content-type"] == PROBLEM_JSON_MEDIA_TYPE+ problem = response.json()+ assert problem["error_type"] == "InvalidJSON"+ assert problem["error_domain"] == "input"+ assert f"at most {MAX_JSON_NESTING_DEPTH} levels" in problem["detail"]++ def test_typed_route_accepts_a_body_at_the_limit(self):+ response = _client().post(+ "/v1/lint",+ content=b'{"content": ' + json.dumps(VALID_MTHDS).encode() + b', "padding": ' + _nested_arrays(MAX_JSON_NESTING_DEPTH - 1) + b"}",+ headers={"content-type": "application/json"},+ )++ assert response.status_code == 200, response.text+ assert response.json() == {"diagnostics": []}++ def test_typed_route_refuses_a_body_deep_enough_to_overflow_the_parser(self):+ # FastAPI used to turn the parser's `RecursionError` into a bare 400, and on Python 3.14 a large+ # stack let the body through: either way, it is now the 422 every other route answers.+ response = _client().post(+ "/v1/lint",+ content=b'{"content": "", "padding": ' + _nested_arrays(RECURSION_DEEP) + b"}",+ headers={"content-type": "application/json"},+ )++ assert response.status_code == 422, response.text+ assert response.headers["content-type"] == PROBLEM_JSON_MEDIA_TYPE+ assert response.json()["error_type"] == "InvalidJSON"++ def test_every_route_with_a_json_body_is_bounded(self):+ # Imported here, as in `test_openapi_contract.py`, so a bad env var fails this test rather than the collection.+ from pipelex_api.main import fastapi_app # noqa: PLC0415++ body_routes = [route for route in fastapi_app.routes if isinstance(route, APIRoute) and route.body_field is not None]+ assert body_routes, "the app declares no route with a body: the invariant below would hold vacuously"+ unbounded = [route.path for route in body_routes if not isinstance(route, JsonBodyRoute)]+ assert not unbounded, f"build these routes' router with route_class=JsonBodyRoute: {unbounded}"++ def test_recursion_error_is_still_refused_as_invalid_json(self, mocker: MockerFixture):+ # The depth check leaves the parser nothing deep enough to raise `RecursionError`; the catch+ # behind it stays, and answers the same 422.+ mocker.patch("pipelex_api.json_body.json_nesting_exceeds", return_value=False)+ mocker.patch("pipelex_api.json_body.json.loads", side_effect=RecursionError("maximum recursion depth exceeded"))++ with pytest.raises(ApiError) as raised:+ decode_json_body(b'{"inputs": []}')++ assert raised.value.status_code == 422+ assert raised.value.document["error_type"] == "InvalidJSON"+ assert "not valid JSON" in raised.value.document["detail"]diff --git a/api/tests/unit/test_pipeline_routes.py b/api/tests/unit/test_pipeline_routes.pyindex 452e1db2e..c3efe63c7 100644--- a/api/tests/unit/test_pipeline_routes.py+++ b/api/tests/unit/test_pipeline_routes.py@@ -4,6 +4,7 @@ The actual pipeline runner is mocked: we only assert that the API layerparses, validates, dispatches, and shapes responses correctly."""+import jsonfrom typing import Any, castimport pytest@@ -20,6 +21,7 @@ from pytest_mock import MockerFixtureimport pipelex_api.routes.pipelex.pipeline as pipeline_modulefrom pipelex_api.exception_handlers import register_exception_handlers+from pipelex_api.limits import MAX_JSON_NESTING_DEPTHfrom pipelex_api.middleware import REQUEST_ID_HEADER, RequestIdMiddlewarefrom pipelex_api.routes.pipelex.pipeline import router as pipeline_routerfrom tests.unit._constants import VALID_MTHDS@@ -128,9 +130,10 @@ class TestPipelineRoutes:assert response.json()["error_type"] == "InvalidJSON"def test_execute_rejects_recursion_error(self, mocker: MockerFixture):- # A deeply nested JSON array exhausts the parser's recursion budget and raises- # `RecursionError` inside `json.loads`. That is a caller-input failure and must map- # to 422 InvalidJSON, not escape to the catch-all 500 handler.+ # A body nested this deep made `json.loads` raise `RecursionError` up to Python 3.13, while on+ # 3.14 it parses whenever the thread's stack is large enough. The server bounds the nesting+ # before parsing, so the answer is the same 422 InvalidJSON on every interpreter and stack,+ # never the catch-all 500 nor a later `ValidationError`.client, _, _ = _build_client(mocker)depth = 100_000response = client.post(@@ -143,9 +146,29 @@ class TestPipelineRoutes:problem = response.json()assert problem["error_type"] == "InvalidJSON"assert problem["error_domain"] == "input"+ assert f"at most {MAX_JSON_NESTING_DEPTH} levels" in problem["detail"]# The opaque-500 sentinel must never appear for a caller-input failure.assert problem["error_type"] != "InternalServerError"+ @pytest.mark.parametrize("route", ["/v1/execute", "/v1/start"])+ def test_run_routes_bound_nesting_at_the_limit(self, mocker: MockerFixture, route: str):+ # The envelope and `inputs` are two levels, so this body nests exactly the limit and the next one level past it.+ client, execute_mock, start_mock = _build_client(mocker)++ def run_body(nesting: int) -> bytes:+ nested = b"[" * nesting + b"]" * nesting+ return b'{"pipe_code": "echo", "mthds_contents": ' + json.dumps([VALID_MTHDS]).encode() + b', "inputs": {"text": ' + nested + b"}}"++ accepted = client.post(route, content=run_body(MAX_JSON_NESTING_DEPTH - 2), headers={"content-type": "application/json"})+ assert accepted.status_code in {200, 202}, accepted.text+ assert execute_mock.await_count + start_mock.await_count == 1++ refused = client.post(route, content=run_body(MAX_JSON_NESTING_DEPTH - 1), headers={"content-type": "application/json"})+ assert refused.status_code == 422+ assert refused.json()["error_type"] == "InvalidJSON"+ assert f"at most {MAX_JSON_NESTING_DEPTH} levels" in refused.json()["detail"]+ assert execute_mock.await_count + start_mock.await_count == 1+@pytest.mark.parametrize("route", ["/v1/execute", "/v1/start"])def test_run_routes_never_instantiate_a_class_the_body_names(self, mocker: MockerFixture, route: str):"""The kajson remote-code-execution gadget: a body naming `subprocess.Popen` used to makediff --git a/docs/api-server/configuration.md b/docs/api-server/configuration.mdindex 31277b5bd..6a0d2d00a 100644--- a/docs/api-server/configuration.md+++ b/docs/api-server/configuration.md@@ -37,6 +37,8 @@ PIPELEX_ENV=dev# rejects with 413. Defaults to 100 MiB. Raise it for larger documents,# lower it to harden the server. Read at startup — change requires a restart.# MAX_REQUEST_BODY_MIB=100+# A JSON body may also nest its arrays and objects at most 128 levels deep. That bound is+# fixed, not configurable (see error-responses.md).# ── Running a method by address (`method_ref`) ────────────────────────────# See pipe-run.md → "Running a method by address". All read at startup.diff --git a/docs/api-server/error-responses.md b/docs/api-server/error-responses.mdindex 1e0272ecd..c80909d7a 100644--- a/docs/api-server/error-responses.md+++ b/docs/api-server/error-responses.md@@ -154,6 +154,7 @@ The HTTP status follows pipelex's `error_domain_to_http_status`:A few specific statuses bypass the domain mapping:- **400** — a well-formed request this deployment cannot serve. `error_type = "StartRequiresAsyncOrchestration"`: `POST /v1/start` is fire-and-forget by nature, and this deployment's orchestrator is blocking-only (the in-process `direct` default), so it refuses honestly rather than blocking and acking — use `POST /v1/execute` instead.+- **400** — `error_type = "BadRequest"`: the client disconnected before its request body was received in full. The client is gone before the answer, so this one is seen in the server's logs, at warning level.- **401** — missing/invalid bearer token. `WWW-Authenticate: Bearer` is set. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`).- **403** — authenticated but not authorized, or refused by deployment policy. The cases: a storage-ownership mismatch; `error_type = "OrchestrationModeOverrideForbidden"` — the request asked for an `orchestration_mode` this deployment does not allow overriding per request (`allow_request_orchestration_mode_override = false`); `error_type = "CustomCodeRequiresSandbox"` — the method (an uploaded bundle, or a fetched `method_ref` package) ships custom Python `.py` files and this deployment is not sandbox-hosted, so running caller-supplied code in-process is refused; `error_type = "MethodStructuresRefusedError"` — a fetched `method_ref` package declares in-process Python structure classes (`StructuredContent` subclasses), which hosted execution always refuses, sandbox or not — express the types as MTHDS concepts with inline structures instead (see [Pipe Run](pipe-run.md#running-a-method-by-address-method_ref)).- **404** — `error_type = "MethodPackageNotFoundError"`: the `method_ref` repository was fetched, but no package in it matches the requested address by manifest identity. The `detail` lists the package addresses the repository does contain, so the caller can correct the selector.@@ -164,7 +165,9 @@ A few specific statuses bypass the domain mapping:The `method_ref` resolution errors are also mapped explicitly rather than through the domain table: `MethodRefParseError`, `MethodFetchError`, `MethodPackageAmbiguityError` and `MethodPackageTooLargeError` are **422** (the caller can fix the reference, pin a tag, or shrink the package), `MethodPackageNotFoundError` is the **404** above, and `MethodStructuresRefusedError` is a **403**, whether the method was fetched by `method_ref` or sent as a bundle. These pipelex `MethodRefError` subclasses do not classify an `error_domain`, so without the explicit mapping they would fall through to the 500 default — which would misreport caller-fixable failures as server faults.-The run routes read their body as plain JSON before anything else, and two refusals come from that step, both **422**. A body that is not valid UTF-8, not valid JSON, nested too deeply to parse, or not a JSON object answers `InvalidJSON`. A body carrying, in any object at any depth, a key named `__class__` or `__module__`, or a key starting with `__kajson`, answers `ReservedObjectKey`, and the `detail` names the key, cut short when it is long. Those are the keys a kajson decoder reads as an order to import and instantiate a class, so the runner refuses them rather than carry them as data. Only keys are checked: a string value that mentions `__class__` is accepted.+Every route that takes a JSON body refuses one whose arrays and objects nest more than 128 levels deep, the body's own envelope included, with a **422** `InvalidJSON` whose `detail` says the body is nested too deeply. The depth is checked before the body is parsed, so the answer does not depend on the Python version or the stack size the server runs with. The bound is fixed rather than configurable, and real inputs stay far below it.++The run routes read their body as plain JSON before anything else, and two refusals come from that step, both **422**. A body that is not valid UTF-8, not valid JSON, nested too deeply, or not a JSON object answers `InvalidJSON`. A body carrying, in any object at any depth, a key named `__class__` or `__module__`, or a key starting with `__kajson`, answers `ReservedObjectKey`, and the `detail` names the key, cut short when it is long. Those are the keys a kajson decoder reads as an order to import and instantiate a class, so the runner refuses them rather than carry them as data. Only keys are checked: a string value that mentions `__class__` is accepted.A pipe selection the server cannot make is an input **422** named for its failure, never the generic `ValidationError`: `EntryPipeNotFoundError` when the selector names no pipe, and `EntryPipeAmbiguousError` when a bare code matches pipes in several domains. The run routes answer an unknown or ambiguous `pipe_code` that way. `POST /v1/pipe-io` and the `/v1/build/*` routes answer every selection refusal that way, counting a request with no `pipe_ref` over a method that declares no `main_pipe` as `EntryPipeNotFoundError` and one over a method whose domains declare several as `EntryPipeAmbiguousError` (see [Pipe I/O](pipe-io.md#pipe-selection)).