Skip to content

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/Runner-speaks-problem · L-261015-130c3f (#1454)

Louis Choqueld7cf01265417
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 963d0691d..e6e14723e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,7 +14,8 @@
- **`--error-format` on `pipelex-agent` itself and on its `inputs` commands**: the error format can be given before the command, `pipelex-agent --error-format json validate bundle …`, where a command's own `--error-format` still wins and its `--format` still serves when neither is given, so a caller forwards one flag whatever the command; the `inputs` commands take `--error-format` too, falling back to the program's and then to JSON, never to their `--format`, which is the template's serialization.
- **`InputFreeValueError` and the input-free rendering of a refusal**: a pydantic validator raising `InputFreeValueError` (`pipelex.tools.typing.validation_exceptions`) declares that its message names nothing of the value it refused, which keeps its sentence wherever a refusal of a run's data is written, and `format_validation_error_without_input()` and `describe_exception_without_input()` (`pipelex.tools.typing.pydantic_utils`) write a `ValidationError` as its locations and reasons, never the values it refused.
- **`PipelexRequestError`**: the runtime's own refusal of a request it cannot serve is a `PipelineRequestError` of the mthds package carrying the core code `request.invalid` (or `request.unsupported`) and its problem document, so a client reads the same refusal whether the runtime or the standard's client raised it.
-- **The security event**: a refusal coded in the `security.` or `pipelex.security.` family fails its run under that code and logs one record on its own logger, `pipelex.errors.security_event`, at warning level, with the message `A security rule refused a request` and `event.name` set to `pipelex.security.refusal`, naming the code, its domain, the kind of target refused, the class of destination when the rule knows it (`loopback`, `private`, `link_local`, `metadata`, `scheme`, `foreign_storage_key`), the run, the request and each of the run's extras as `run.extras.<key>`, and never the URL, path, template or any input value. The process that raises a refusal logs it, once: the pipe run for a refusal raised while it executes, its delivery included, the runner for one before the run exists and for one raised in its own process that no pipe run logged, and the API server for one answered before any run, the refusals it authors itself included (a reserved object key, a callback URL the SSRF rule refuses, a resource path or a method file path leaving the method: absolute, naming a drive or a network share, or climbing with `..`, read with either separator, while a path of the wrong shape is `request.invalid` and logs none), which keep their response, while a failure rebuilt from another process's report is never logged again, since the orchestrator that rebuilds it marks it, and no event names a run id a request body chose; `pipelex.errors.security_event` gives a host `emit_security_event()`, `mark_security_event_emitted()` and `log_security_event()`, and a raise site states the class of destination with `PipelexError.with_security_target_class()`.
+- **Validation warnings as problem items**: `warning_problem_items()` in `pipelex.pipeline.validation_errors` gives a valid report's warnings as problem items, each under the code its type names, a hint lint's `method.hint_invalid` naming its hint from the new `ValidationErrorItem.hint_key` and located at the declaration the hint is on, a concept at `concept.<Concept>`, a field of its structure at `concept.<Concept>.structure.<field>`, a pipe's input at the pipe and the input, and `root_escape_of()`, whose `RootEscape` gives both the reason a path leaving its root is refused and its `rule`, and `path_refusal_error()` in `pipelex.core.bundle_resources.bundle_resource`, which builds the refusal of a submitted file's path from that escape, with its code and its parameters, the `rule` of `security.input_path_refused` or the field `resources` of `request.invalid`.
+- **The security event**: a refusal coded in the `security.` or `pipelex.security.` family fails its run under that code and logs one record on its own logger, `pipelex.errors.security_event`, at warning level, with the message `A security rule refused a request` and `event.name` set to `pipelex.security.refusal`, naming the code, its domain, the kind of target refused, the class of destination when the rule knows it (`loopback`, `private`, `link_local`, `metadata`, `scheme`, `foreign_storage_key`, which the caller's problem states as the registry's `private`, since its sentence reads the class as a word), the run, the request and each of the run's extras as `run.extras.<key>`, which the API server reads off a request's `analytics_groups` as soon as its JSON body is parsed, on the diagnostic routes as on the run routes, and never the URL, path, template or any input value. The process that raises a refusal logs it, once: the pipe run for a refusal raised while it executes, its delivery included, the validation sweep for one a dry run meets before its pipe run starts, such as while its mock inputs are built, the runner for one before the run exists and for one raised in its own process that no pipe run logged, and the API server for one answered before any run, the refusals it authors itself included (a reserved object key, a callback URL the SSRF rule refuses, a resource path or a method file path leaving the method: absolute, naming a drive or a network share, or climbing with `..`, read with either separator, while a path of the wrong shape, empty or holding a backslash or a colon, logs none and is `request.invalid` as a key of `resources` or a file submitted beside a method, and `method.package_invalid` with the reason `invalid_tree_path` as a key of `files` or a member of `bundle_b64`), which keep their response, while a failure rebuilt from another process's report is never logged again, since the orchestrator that rebuilds it marks it, and no event names a run id a request body chose; `pipelex.errors.security_event` gives a host `emit_security_event()`, `mark_security_event_emitted()` and `log_security_event()`, and a raise site states the class of destination with `PipelexError.with_security_target_class()`.
### Changed
@@ -27,12 +28,17 @@
- **Plugin API v9 (Breaking)**: an HTTP-error mapper registered with `add_http_error_mapper(exc_type_provider=..., to_pipelex_error=...)` returns the `PipelexError` a transport exception stands for, where `to_error_report` returned a report, and a bundle validator's `validate_bundles` returns a `BundleValidationFailure`, the refusal's problem in the operator's view with its validation items, as its invalid verdict, and a host plugin's carrier of a problem recovered across a transport boundary overrides `PipelexError.recovered_problem()` to return it rather than overriding `to_problem()`, which a located run failure no longer reads as a carrier; `PLUGIN_API_VERSION` moves to 9, so a plugin declaring `targets_api = 8` is refused at discovery with `PluginApiVersionMismatchError`.
- **`pipelex.test_extras.problem_parity` (Breaking)**: the parity fixtures a distributed executor's tests share with the local runner's moved from `pipelex.test_extras.error_report_parity`, and their classes are `ProblemParityTestData`, `SearchProblemParityTestData` and `JudgeProblemParityTestData`.
- **A run failure reports its root fault's code (Breaking)**: the root fault a run failure's problem reports is the first error down its cause chain that declares a code of its own, and its code, title, type, domain and retry verdict are the problem's, with no `runtime` floor on the domain; a consumer that branched on the wrapper's `error_type` branches on `code`. A `PipeFunc` whose function raised reads `pipe.function_raised` whatever it raised, a coded error of a helper the function called included, which rides as the cause, while a failure of the executor running it, such as its timeout, keeps its own code, and an exception an executor lets through that is not a Pipelex error, such as an out-of-process executor's transport failure, reads `runtime.unexpected`. A failure below an exception that is not a Pipelex error lends the error above it no code, fact, location or advice.
-- **The runner's request refusals carry their code (Breaking)**: a `/v1/execute` or `/v1/start` body the runner refuses beyond its schema (a bundle sent with `mthds_contents`, `method_ref` beside a bundle or `mthds_contents`, `resources` or `dependencies` without the files they belong to, no run source, a hosted-only field such as `method_id`) answers a 422 `PipelexRequestError` carrying `request.invalid` or `request.unsupported`, where it answered `ValidationError`, and the API's `ProblemDocument` schema documents `code`.
+- **The runner's own refusals are coded problem documents (Breaking)**: every error response of the API server, a 404 for a path no route serves, a 405 and a 413 included, is a problem document carrying a registry `code`, and the API's `ErrorType` is gone with the `error_type`, `error_domain`, `retryable` and `instance` members, the `tree_refusal`, `missing_blobs` and `mismatched_blobs` members becoming the code's parameters or the operator's diagnostics. A field the runner refuses is `request.invalid` naming it as `params.field`, with one item in `errors` per refused field up to a bound, which the operator's `diagnostics.message` keeps too, saying how many more faults there were, a rule over several fields naming the one to change, such as the second of two selectors sent or `mthds_sources` beside a `method_ref`, a body or a part of one it cannot parse `request.malformed` with a `reason`, a size limit `request.too_large` with its `limit` and the `size` in bytes, an encoded value measured by the bytes it carries, and a method tree it cannot read `method.package_invalid` with a `reason`, the standard's tree refusal code or one of the runner's own, one per rule and one per limit, so an archive past its member count reads `bundle_too_many_files`, while a body refused beyond its schema on `/v1/execute` or `/v1/start` (a bundle sent with `mthds_contents`, `method_ref` beside a bundle, `resources` or `dependencies` without their files, no run source, a hosted-only field such as `method_id`) answers a `PipelexRequestError` carrying `request.invalid` or `request.unsupported`; the API's `ProblemDocument` schema documents `code`, and `request_id`, taken from `X-Request-ID` or minted, is what correlates a response with the server's log.
+- **The runner's refusals answer their code's status (Breaking)**: an orchestration-mode override the deployment forbids is a 422 where it was a 403, custom Python on a deployment that is not sandbox-hosted a 501 where it was a 403, `/v1/start` on a blocking-only deployment a 501 `runtime.unsupported` where it was a 400, a registry-form `method_ref` a 422 `request.unsupported` where it was a 501, invalid base64 and a client gone mid-upload a 422 where they were a 400, an archive past its file-count or decompressed-size ceiling and too many `resources` a 422 where they were a 413, a blob past the per-file limit a 413 where it was a 422, a forwarded `X-User-Id` that is not path-safe a 422 `request.invalid` naming the header where it was a 400, a body FastAPI could not parse, holding bytes that are not UTF-8 or an integer past Python's digit limit, a 422 `request.malformed` with the reason `not_utf8` or `integer_too_long` where it was a 400, while the framework's own refusals, plain `{"detail": …}` bodies until now, keep their status under a code whose required parameters the runner can fill, a 400 as `request.malformed` with the reason `unreadable`, a 401 as `auth.missing_credential` keeping its `WWW-Authenticate` challenge, a 403 as `auth.invalid_credential`, a 413 as `request.malformed` with the reason `too_large`, a 429 as `runtime.unavailable` keeping its `Retry-After`, and any other, such as a 415, as `request.malformed` with the reason `unreadable`, a `read_scope` a `jwt` caller may not read a 403 `auth.forbidden` whose `requirement` is `read_scope_under_caller` where it was a 403 `ReadScopeForbidden`, and a token whose claims the runner cannot use a 500 where it was a 401; a 401 carries `WWW-Authenticate: Bearer` only where the deployment reads a bearer token (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`), so behind a trusted proxy a missing `X-User-Id` is a 401 asking for no token.
+- **Damaged stored bytes are a damaged stored file, never retried**: bytes the API server's blob store holds under a hash that do not hash to it, or are not the size it holds them at, answer a 500 `pipelex.storage.damaged`, a new code of the Pipelex error registry, naming the kind of storage, whose verdict is not to retry, since a retry reads the same damaged object, and which `/v1/execute`, `/v1/start` and `/v1/validate` declare in their OpenAPI responses; the server's line naming the object to remove, `Stored blob bytes do not match their hash`, carries `blob_sha256`, `blob_size_bytes`, `read_size_bytes` and `storage_scheme`.
+- **The `/validate` Markdown presents the verdict's items (Breaking)**: the opt-in `rendered_markdown` of an invalid verdict is rendered from the problem items its `errors` holds, in the same view, each under its code's title with its code, location, sentence, suggestions and suggested fix, so a caller reads no wording its view of the items leaves out, where it rendered the validation items' own messages; `pipelex.pipeline.validation_render.render_invalid_verdict_markdown(items=..., message=...)` replaces `render_invalid_validation_markdown(report)`.
+- **The diagnostic routes' verdicts carry problem items (Breaking)**: the invalid arm of `/v1/validate`, `/v1/resolve`, `/v1/codegen` and `/v1/pipe-io` carries `errors`, one problem item per finding with its `code`, `detail`, `params` and `location` and a suggested fix naming its file as `file`, where it carried `validation_errors`, the valid arm's `warnings` are problem items too, and a top-level member a verdict has no value for, such as `default_pipe_ref` or `graph_spec`, is absent rather than `null`. The OpenAPI artifact no longer publishes `ValidationErrorItem` or pipelex's `SuggestedFix`, and names every schema reachable from the standard's problem item with a `Problem` prefix, such as `ProblemSuggestedFix` and `ProblemSetKeyOp`.
- **Pipe selection refusals carry the code of their case**: an entry pipe the selector names but no closure declares reads `request.pipe_not_found`, a bare selector matching pipes in several domains `request.pipe_ambiguous`, a request with no selector over a closure declaring no `main_pipe`, or several, `request.pipe_unspecified`, naming the declared ones as its `candidates`, a manifest `main_pipe` the closure lacks `method.pipe_unresolved`, and one it declares in several domains `method.ref_ambiguous`, all still a 422, a dependency's `alias->code` matching pipes in several of its domains naming them as `candidates` too; a run of a method on disk with no pipe named refuses several declared `main_pipe`s and a manifest `main_pipe` several bundles define the same way.
- **`PipeIOContractError` is the method's (Breaking)**: a structure that cannot be projected into its IO contract answers a 422 carrying `method.concept_invalid`, where it answered a 500.
- **Storage and remote-file failures say whose they are**: an S3 or GCS refusal of the deployment's credentials (`AccessDenied`, an invalid or expired key, `Forbidden`) carries `pipelex.config.credential_refused`, a bucket that does not exist `pipelex.config.invalid` and missing credentials `pipelex.config.credential_missing`, apart from an outage, `pipelex.storage.unavailable`; a remote file that times out, refuses the connection or answers a 5xx, 408, 425 or 429 is `input.url_unreachable`, which a retry may cure, and any other failed fetch `input.file_unreadable`.
- **Builtins raised where a reader sees them are coded classes**: refusals that raised a bare `ValueError`, `RuntimeError`, `ImportError` or `NotImplementedError` raise a coded `PipelexError`, such as `RunParameterError` for a run's metadata, extras or storage scope (still a `ValueError`), `ExportedPipeNotFoundError` and `ExportedPipeAmbiguousError` for a CLI pipe selector, `BundleClosureEmptyError`, `StorageNotConfiguredError`, `UrlSyntaxError`, `LocalFileMissingError` and `UnsupportedImageMimeTypeError`, and the classes that were rooted outside `PipelexError` (`PipeValidationError`, `ConceptValueError`, `QualifiedRefError`, `SemVerError`, `MethodNotFoundError` and the like) join it.
- **Inference failures carry the code their classification picks (Breaking)**: the classification of a provider's failure picks a code with its category, a `ServiceErrorCode` a plugin contributes names its `error_code`, and a category that repeats the call within the run must pick a code that invites a retry; an error built with a category alone reports the category's code (`provider.unavailable` for `TRANSIENT`, `runtime.misconfigured` for `CONFIGURATION`, `provider.quota_exhausted` for `CAPACITY`, `provider.outcome_unknown` for `AMBIGUOUS`). A provider 400 that carries no context-window or content-policy signal is `runtime.unexpected`, answered 500, where it was the caller's 422, and a local extractor's `OSError` is `runtime.unexpected`, no longer repeated within the run.
+- **One rule for a request id (Breaking)**: a run's `request_id` holds ASCII letters, digits, `_` and `-` alone, at most 128 of them, the rule the API server applies to an inbound `X-Request-ID`, now one function, `pipelex.system.job_metadata.is_valid_request_id()`, where a run accepted any printable ASCII, a space, a quote or an `=` that could forge a field of a key=value log line or a parameter of a header included; `RunParameterError` no longer quotes the refused value.
- **A truncated completion says which limit cut it**: `LLMCompletionTruncatedError` carries `model.output_truncated` when the method's `max_tokens` cut the answer and `model.context_exceeded` when the context window did, both the method's to change.
- **`ModelDeckPresetValidationError` is spelt right (Breaking)**: the error a model deck preset that fails validation raises was `ModelDeckPresetValidatonError`, and its reports carried that `error_type`; a consumer that branched on the old name branches on the new one, or on its code, `pipelex.config.invalid`.
- **Usage statistics carry the error's code (Breaking)**: a failed `command_completed` or `run_completed` carries the code of its error in `error_code` and that code's domain in `error_domain`, now one of `input`, `method`, `account`, `operator` and `runtime` where it read `input`, `config`, `runtime` or `other`, and a `model_used` counts its failed calls by the domain of their code, in `failures_input`, `failures_method`, `failures_account`, `failures_operator` and `failures_runtime`, where it counted them by the runtime's inference category, which no event carries any more. A failed hosted run's `command_completed` carries the code and the domain the hosted API sent, and none when it sent none, and every surface reads a refusal a server answered by that rule, a run's `run_completed` reading the catch-all where nothing was sent rather than the code the client infers from the status. Every event's `schema` is 2, so a receiver tells these events from an earlier release's.
@@ -40,8 +46,8 @@
- **The `pipelex` error panels print the problem**: a panel names the problem's title, its detail, its next step, its code with its domain and retry verdict, its location and its request id beside the fields it printed, and a run that fails, or any failure a command root catches, prints its problem the same way on stderr, where it printed one line with the message. Every panel, an invalid bundle's, an unavailable model's or a telemetry file's included, and the stack trace `--traceback` adds to it, now goes to stderr, where the panels and their stack traces went to stdout, so a command's piped output holds only what it produced.
- **A configuration refusal names its setting and its file**: `pipelex.config.invalid` raised for a configuration that does not validate, a telemetry configuration, a tracing sink or what a former release left in the inference configuration names the setting, its file and the configuration it belongs to in the operator's next step, a file the refusal can single out, a former release's or one that does not parse (`pipelex.config.syntax`, where `pipelex show config` named `pipelex.toml` whichever layer failed), named relative to the working directory or as `~/…` under the home directory, never with the home directory's account, and its advice, the tip a CLI prints, follows the pending migration, `pipelex migrate` when it would rewrite the files and a correction by hand when it would not, and else the refusal's code: `pipelex init` for a missing file, setting the variable for one that is not set, and `pipelex doctor` for a configuration that does not validate or parse. The refusal of what a former release left carries in `diagnostics.migration` what `pipelex migrate` would do about it, from the cleanup's dry run, so a JSON reader, who gets no tip, reads the remedy too.
- **A pipe's failure line carries its code, not its text**: `The execution of a pipe failed` carries the problem's `error.code` beside `error.type` and no longer `error.message`, so a log query selects failed pipes by code, and the line holds neither the caller's own text, a function's message or a template's source, nor a refused host.
-- **`Jinja2TemplateSecurityError` is a `SecurityError` (Breaking)**: the template sandbox's refusal at render time now derives from `SecurityError`, like `UriReadRefusedError`, `SsrfBlockedError` and `UnsafeSchemaError`, instead of `ToolError`, so a host catching `SecurityError` catches it too and an `except ToolError` no longer does; it stays a type of its own, apart from `Jinja2TemplateRenderError`, and its class name, which the operator reads as `diagnostics.error_class`, and its code, `security.template_refused` on a method's template, are unchanged.
-- **A security refusal is never a validation verdict (Breaking)**: a refusal a raise site coded in the `security.` family is let through by the bundle-validation cascade whatever its class, as a `SecurityError` always was, so a `PipeDocGen` step whose `template_file` climbs above its method tree's root fails `validate` and a run with `security.method_path_refused` and logs its security event, where it was a `method.invalid` verdict naming the pipe.
+- **`Jinja2TemplateSecurityError` is a `SecurityError` (Breaking)**: the template sandbox's refusal at render time now derives from `SecurityError`, like `UriReadRefusedError`, `SsrfBlockedError` and `UnsafeSchemaError`, instead of `ToolError`, so a host catching `SecurityError` catches it too and an `except ToolError` no longer does; it stays a type of its own, apart from `Jinja2TemplateRenderError`, and its class name, which the operator reads as `diagnostics.error_class`, its code, `security.template_refused` on a method's template, its title and its classification are unchanged.
+- **A security refusal is never a validation verdict (Breaking)**: a refusal a raise site coded in the `security.` family is let through by the bundle-validation cascade whatever its class, as a `SecurityError` always was, so a `PipeDocGen` step whose `template_file` climbs above its method tree's root fails `validate` and a run with `security.method_path_refused` and logs its security event, where it was a `method.invalid` verdict naming the pipe; a refusal a validation's dry run meets, such as a template the sandbox refuses at render, fails it the same way under its own code, every failure riding its items and the event logged once, where it was an item of an invalid verdict.
- **`mthds` 0.22.1 and `pipelex-sdk` 0.46.0 (Breaking)**: the exact pins move from `mthds==0.22.0` and `pipelex-sdk==0.45.0` to `mthds==0.22.1`, the release whose errors carry the MTHDS problem document read by its registry code, and `pipelex-sdk==0.46.0`, the release built on it; everyone downstream inherits those exact versions.
### Fixed
@@ -67,7 +73,8 @@
### Security
-- **Callback URLs are held to the runtime's SSRF rule**: the runner refuses a `/v1/start` callback URL with the rule the webhook delivery applies when it fires, `pipelex.tools.network.host_rules`, so a cloud metadata name spelled in capitals or with a trailing dot, and an address that is not publicly routable such as a carrier-grade NAT one, are refused with a 422 `InvalidCallbackUrls` before the run, where the runner's own copy of the rule let them through to the delivery.
+- **Callback URLs are held to the runtime's SSRF rule**: the runner refuses a `/v1/start` callback URL with the rule the webhook delivery applies when it fires, `pipelex.tools.network.host_rules`, so a cloud metadata name spelled in capitals or with a trailing dot, and an address that is not publicly routable such as a carrier-grade NAT one, are refused with a 422 `security.input_url_refused` before the run, where the runner's own copy of the rule let them through to the delivery; a host of dots alone, such as `http://./hook`, names no host, and a host and port written with no scheme, such as `localhost:3000/cb`, opens no authority, so each is a 422 `request.invalid` naming `callback_urls`, with no security event, while a scheme-relative URL whose host the rule refuses, such as `//169.254.169.254/latest/meta-data`, is the rule's refusal, classed by its host.
+- **The API server's error line quotes no exception (Breaking)**: every error line carries `error.code` and names the classes of the failure's exception chain in `error.chain`, and an error-level line adds `error.frames`, where the deepest exception was raised, in place of the traceback under `exception`, so no exception's text, which a foreign exception can fill with a run's inputs or a model's answer, reaches the log, and an exception the catch-all answered no longer reaches the server, whose log would print its traceback; the `detail` field is gone too. The error's message rides the operator view's `diagnostics` alone, which only a request the operator authenticated reads (`AUTH_MODE=api_key`, or a trusted proxy's forwarded identity), so every line names the problem's operator-only parameters as `error.params.<name>`, such as the `component` of a `runtime.misconfigured`, whichever view the response took. A refusal the runner answers in place of a framework exception, FastAPI's `RequestValidationError`, Starlette's `ClientDisconnect` or an `HTTPException`, names that exception's class after its own in `error.chain`, and a failure no handler recorded that ended a request after its response had started, the catch-all's own failure while a response streamed, is written as `A request failed after its response had started`, naming its path, the status already sent and its classes alone, where it was dropped unrecorded; so is a failure to send the answer the server built for a failure no handler answered, such as to a client already gone. A line's level says who has to act, from its status and its code's domain: a 4xx is a warning, a 5xx an error with frames only when its domain is the runtime's or the operator's, a 501, what the deployment does not offer, such as custom Python without a sandbox or `/v1/start` on a blocking-only orchestrator, a warning without frames, where every 5xx was an error, and a 404 or 405 for a request no route serves a debug line, where it was a warning.
## [v0.89.0] - 2026-10-17
diff --git a/api/.claude/skills/postman-bundle/SKILL.md b/api/.claude/skills/postman-bundle/SKILL.md
index edd5c0c2e..dabbbad54 100644
--- a/api/.claude/skills/postman-bundle/SKILL.md
+++ b/api/.claude/skills/postman-bundle/SKILL.md
@@ -32,7 +32,7 @@ This is a focused, one-bundle-at-a-time tool. It is **not** the full collection
| `resolve` | `POST /v1/resolve` | `files[]` crate | no | no | no (free) |
| `codegen` | `POST /v1/codegen` | `files[]` crate + `kind`/`target` | no | no | no (free) |
-Every non-run endpoint answers with the **`/validate` verdict discipline**: a produced verdict is always a `200` discriminated on `is_valid` — the artifact on the valid arm, structured `validation_errors[]` on the invalid arm. Non-2xx is reserved for no-verdict conditions (request-shape `422`, auth `401`/`403`, server `5xx`), rendered as RFC 7807 `problem+json`.
+Every non-run endpoint answers with the **`/validate` verdict discipline**: a produced verdict is always a `200` discriminated on `is_valid` — the artifact on the valid arm, structured `errors[]` problem items on the invalid arm. Non-2xx is reserved for no-verdict conditions (request-shape `422`, auth `401`, server `5xx`), rendered as RFC 9457 `problem+json` with a registry `code`.
## What it produces in Postman
@@ -51,7 +51,7 @@ Which requests appear depends on `--endpoint`: the default `both` is `execute` +
## The two request envelopes
-**Run + validate routes** carry the bundle as parallel lists — `mthds_contents` (full text of each `.mthds` file, main one first) plus, on `/validate`, `mthds_sources` (one filename per content, so `validation_errors[].source` names the owning file):
+**Run + validate routes** carry the bundle as parallel lists — `mthds_contents` (full text of each `.mthds` file, main one first) plus, on `/validate`, `mthds_sources` (one filename per content, so `errors[].location.file` names the owning file):
```json
{
diff --git a/api/.claude/skills/postman-bundle/scripts/build_postman_query.py b/api/.claude/skills/postman-bundle/scripts/build_postman_query.py
index 5b54e1fda..3560c71c0 100644
--- a/api/.claude/skills/postman-bundle/scripts/build_postman_query.py
+++ b/api/.claude/skills/postman-bundle/scripts/build_postman_query.py
@@ -293,7 +293,7 @@ def build_validate_body(
- ``allow_signatures`` — always present (real clients send the bool verbatim;
``false`` is the strict default).
- ``mthds_sources`` — when provided, parallel to ``mthds_contents``; each entry
- names the owning file so server-side ``validation_errors[].source`` resolves.
+ names the owning file so server-side ``errors[].location.file`` resolves.
- ``render`` — the opt-in Pipelex-API presentation hint (e.g. ``["markdown"]``).
A **skill** validates with the default Markdown view, so it sends
``render: ["markdown"]`` and reads the ``rendered_markdown`` the 200 carries; a
@@ -718,7 +718,7 @@ def main() -> None:
f"- allow_signatures: {args.allow_signatures}\n"
f"{render_line}\n"
"Takes no pipe_code and no inputs. 200 discriminated on `is_valid`: the bundle blueprint, "
- f"graph spec, and per-pipe IO contracts — or structured validation_errors[]. {trailer}"
+ f"graph spec, and per-pipe IO contracts — or structured errors[]. {trailer}"
)
if key == "resolve":
return (
@@ -726,7 +726,7 @@ def main() -> None:
"refs, flattened refinement, materialized natives, fingerprint. NO inference, no dry-run sweep.\n\n"
f"{source_lines}\n"
"200 discriminated on `is_valid`: the canonical JSON crate on the valid arm, structured "
- f"validation_errors[] on the invalid arm. {trailer}"
+ f"errors[] on the invalid arm. {trailer}"
)
# codegen
return (
diff --git a/api/CLAUDE.md b/api/CLAUDE.md
index d7a1934dc..22effd474 100644
--- a/api/CLAUDE.md
+++ b/api/CLAUDE.md
@@ -133,6 +133,13 @@ make docker-logs # Tail Docker container logs
- **Never** silence the `BLE001` lint rule with `# noqa: BLE001`. If `BLE001`
fires, the right answer is always to identify the real exception types and
narrow the `except`, not to suppress the warning.
+- The one exception is the absolute root of the API, the case pipelex's own
+ rule sanctions: `AnsweredErrorBarrier` in `pipelex_api/exception_handlers.py`,
+ outside Starlette's catch-all, which must stop whatever reaches it. It takes
+ the suppression form pipelex uses, `# ruff: ignore[BLE001]`, with a comment
+ line under the `except` naming that case. The code is spelled out because this
+ member's ruff runs without `preview`, which a rule's name, as pipelex writes
+ it (`blind-except`), needs.
- Always chain exceptions: `raise NewError(msg) from exc`
- Write the error message as a variable before raising
- Convert third-party exceptions to domain-specific ones
@@ -196,13 +203,13 @@ async def execute(
## Error Responses
-Every error is rendered as RFC 9457 `application/problem+json` by the global handlers in `pipelex_api/exception_handlers.py`. **Route handlers do not shape errors themselves** — they call into pipelex and let exceptions propagate. The wire contract is documented at `docs/api-server/error-responses.md`, at the repository root.
+Every error is rendered as RFC 9457 `application/problem+json` by the global handlers in `pipelex_api/exception_handlers.py`, and every problem carries a registry `code`, a 404 or a 405 included; there is no `error_type` and no `instance`, and `request_id`, which `RequestIdMiddleware` takes from an inbound `X-Request-ID` or mints, correlates a response with its log lines. **Route handlers do not shape errors themselves** — they call into pipelex and let exceptions propagate. The wire contract is documented at `docs/api-server/error-responses.md`, at the repository root.
- **Domain errors** (pipelex `PipelexError` subclasses) — raise from your code and let them propagate, choosing the error's code and parameters where you raise it (`with_error_code()`, `with_params()`) when its class declares a set. The `PipelexError` global handler builds the error's problem in the operator view, `to_problem(view=ProblemView.OPERATOR)`, and `problem_response` renders it with the status the problem's code declares, in the view the request's identity gives it (`pipelex_api/problem_view.py`: the operator's for the API key and for a request the trusted proxy forwarded, the caller's otherwise). A failure a route receives as a value, such as a validator's refusal that carries no validation items, goes through `problem_response` too. Do not wrap, classify, or re-shape.
-- **API-authored 4xx/5xx** — use the helpers in `pipelex_api/errors.py`: `raise_validation_error`, `raise_bad_request`, `raise_forbidden`, `raise_unauthenticated`, `raise_payload_too_large`, `raise_internal_server_error`. Each raises an `ApiError` carrying a pre-built problem document; the global handler emits it. **Do not raise `HTTPException` directly** — FastAPI's default handler wraps the body as `{"detail": <whatever>}` and cannot emit a flat RFC 9457 document.
-- **Auth errors** — the helpers set `WWW-Authenticate: Bearer` automatically on 401.
-- **Logging** — the global handlers emit one structured record per error, with the fixed message `A request ended in an error response` (the key the error stream is selected by; there is no `event` field) and the fields `url.path`, `error.type`, `error_domain`, `retryable`, `http.response.status_code`, and `user.id` / `pipe_code` / `pipeline_run_id` when the request bound them. On a domain error the record also carries `error.code`, `error_category`, and the diagnostics' `backend_name`, `model_handle`, `provider_status_code` and `provider_request_id`, and its `error.type` is the class of the exception that escaped, which for an exception that is not a `PipelexError` is that exception's class rather than the stand-in its problem names. `detail` rides the API-authored path only: a domain error's record is built from the operator view, whose `diagnostics` carry the cause, while the body's `detail` is only its code's sentence. They travel as `fields=` on the runtime's log call, never interpolated into the message, and `request_id` is not among them: `RequestIdMiddleware` binds it on the runtime's log context, so every record emitted under the request already carries it. The server selects the `json` sink, so a record reaches stderr as one JSON object per line — see `docs/api-server/logging.md` at the repository root. Log disposition follows the final HTTP status: 4xx logs at `warning` (caller mistakes, the provider-429 passthrough, and API-level 4xx overrides like the 409 conflict); 5xx logs at `error` with traceback. Routes should not log error tracebacks themselves.
-- **Documenting a failure in OpenAPI** — the shared, typed `responses=` declarations live in `pipelex_api/openapi_responses.py` (`ProblemDocument` + one constant per status). Every auth-wrapped `/v1` route already documents `401`/`413`/`422`/`500` via the composite router's `responses=` (`pipelex_api/routes/__init__.py`); a route declares on its own decorator only the statuses **it alone** can produce. Never hand-write an error `content` block: `pipelex_api/openapi_schema.py` re-keys the generated schema onto `application/problem+json`, because FastAPI renders a response `model` under the route's response-class media type and offers no per-response override. Adding a new status means adding a constant there and referencing it — then `make openapi-export`.
+- **The runner's own refusals** are `PipelexError`s too, the classes of `pipelex_api/exceptions.py`, each declaring its code or its set of codes: `RunnerRequestError` (`request.invalid` naming the refused `field`, or the code the raise site chooses: `request.malformed` with a `reason`, `request.too_large` with `limit` and `size`, `request.unsupported`, `request.blobs_missing`, `request.not_found`, `request.method_not_allowed`, and `runtime.unavailable` for a framework 429), `RunnerAuthError` (the `auth.*` codes and `pipelex.deployment.token_claims_invalid`, with the `challenge` its 401 carries), `RunnerMisconfiguredError` (`runtime.misconfigured`, its `component` read by the operator alone), `RequestMethodError` (`method.package_invalid` with a `reason`, a `MethodPackageReason` or the standard's tree refusal code, and a `path` or a `limit`, `method.syntax`, `method.resource_missing`, `security.input_path_refused`), `RequestFieldConflictError` (`request.invalid` from a model validator judging several fields, naming the one to change), `BlobStoreDamagedError` (`pipelex.storage.damaged`, a 500 never retried, which the routes reading held blobs declare as `PROBLEM_500_HELD_BLOBS`), `OrchestrationOverrideForbiddenError`, `CustomCodeRequiresSandboxError`, `ReservedObjectKeyError` and `CallbackUrlRefusedError`. Raise one, choosing the code with `with_error_code()` and giving its parameters with `with_params()`; the message is the operator's and rides `diagnostics` alone, while the caller reads the code's sentence. A new class goes in that module, declares its code in its own body (`tests/unit/test_error_code_gate.py`), and is recorded with the root `make generate-error-identity`. A request the route's model refuses becomes `request.invalid` with one item per refused field (`pipelex_api/request_refusals.py`); a model validator over several fields raises `RequestFieldConflictError` so its item names a field rather than `body`. A typed body is parsed by `JsonBodyRoute` before FastAPI validates it, so a body that does not decode or parse is the caller's `request.malformed`, never FastAPI's bare 400, and its `analytics_groups` are bound on the request right then (`run_extras_binding.py`, which the run routes call too), so the security event of any later refusal names whose request it was. Pick the registry code that fits; the vendored registry is not edited here. **Do not raise `HTTPException` directly** — no route raises one: `handle_http_exception` answers the framework's own, each 4xx keeping its status and its meaning under a code whose required parameters the runner can fill, since the framework names nothing but a status and a header (`framework_refusal`: a 400 or 422 is `request.malformed` with the reason `unreadable`, keeping its status, a 401 `auth.missing_credential` keeping its challenge, a 403 `auth.invalid_credential`, a 404 or 405 from routing, a 413 `request.malformed` with the reason `too_large`, a 429 `runtime.unavailable` naming the rate limiter, keeping its `Retry-After`, any other `request.malformed` with the reason `unreadable`; `tests/unit/test_exception_handlers.py` checks every 4xx fills its code's parameters), never as a 500, and a 5xx as `runtime.unexpected`. A refusal standing in for a framework exception (`_standing_in_for`) is chained from it, so the record's `error.chain` names it.
+- **Auth errors** — a 401 carries the `WWW-Authenticate` challenge its `RunnerAuthError` names, `Bearer` from the token and API-key verifiers, and none behind a trusted proxy, which reads no bearer token; `problem_json_response` adds no challenge of its own. A forwarded `X-User-Id` that is not path-safe is a `RunnerRequestError` naming the header, a 422.
+- **Logging** — the global handlers emit one structured record per error, with the fixed message `A request ended in an error response` (the key the error stream is selected by; there is no `event` field) and the fields `url.path`, `error.code`, `error.type`, `error.chain`, `error_domain`, `retryable`, `http.response.status_code`, and `user.id` / `pipe_code` / `pipeline_run_id` when the request bound them, plus `error_category` and the diagnostics' `backend_name`, `model_handle`, `provider_status_code` and `provider_request_id` when the failure has them. `error.type` is the class of the exception that escaped, which for an exception that is not a `PipelexError` is that exception's class rather than the stand-in its problem names, and `error.chain` the classes of the exceptions it was raised from or while handling. **No record carries an exception's text or its traceback**: a foreign exception's text can quote a run's inputs or a model's answer, so an `error` record adds `error.frames`, where the deepest exception of the chain was raised, every record adds the problem's operator-only parameters as `error.params.<name>` (the `component` of a `runtime.misconfigured`), and the message rides the operator view's `diagnostics` alone, which only an operator-authenticated request reads. `AnsweredErrorBarrier`, between `RequestIdMiddleware` and the app in `main.py`, stops the exception Starlette's `ServerErrorMiddleware` raises again after the catch-all answered it, so uvicorn never logs its traceback; a failure no handler recorded once a response had started, the catch-all's own, or one sending the barrier's own answer, it records first as `A request failed after its response had started`, by class alone. The record is built from the operator view, and carries no `detail`. The fields travel as `fields=` on the runtime's log call, never interpolated into the message, and `request_id` is not among them: `RequestIdMiddleware` binds it on the runtime's log context, so every record emitted under the request already carries it. The server selects the `json` sink, so a record reaches stderr as one JSON object per line — see `docs/api-server/logging.md` at the repository root. The record's level says who has to act (`record_level_of`, from the final HTTP status and the code's domain, the registry's who-must-act): a 4xx logs at `warning` (caller mistakes, the provider-429 passthrough, and the 409 conflict); a 5xx logs at `error`, with frames, only when its domain is `runtime` or `operator`, and at `warning` without frames when it is a 501, what this deployment does not offer, which any caller can ask for again, or when its domain is the caller's; a routing 404 or 405 logs at `debug`, as scanners send them by the thousand. Decide a new level from those two facts, never from a list of codes. A security refusal also logs its security event. Routes should not log errors themselves.
+- **Documenting a failure in OpenAPI** — the shared, typed `responses=` declarations live in `pipelex_api/openapi_responses.py` (`ProblemDocument` + one constant per status, such as `PROBLEM_404_METHOD_PACKAGE`, `PROBLEM_409_DUPLICATE_RUN`, `PROBLEM_501_RUN_POLICY` and `PROBLEM_501_START`, each describing the codes it answers). Every auth-wrapped `/v1` route already documents `401`/`413`/`422`/`500` via the composite router's `responses=` (`pipelex_api/routes/__init__.py`, `COMMON_PROBLEM_RESPONSES`); a route declares on its own decorator only the statuses **it alone** can produce. A schema reachable from the standard's `ProblemItem` is published under a `Problem` prefix (`pipelex_api/openapi_schema.py`), so it never takes the name of pipelex's own model of the same name. Never hand-write an error `content` block: `pipelex_api/openapi_schema.py` re-keys the generated schema onto `application/problem+json`, because FastAPI renders a response `model` under the route's response-class media type and offers no per-response override. Adding a new status means adding a constant there and referencing it — then `make openapi-export`.
Typical route:
@@ -218,11 +225,12 @@ async def start(
return await api_runner.start(run_request, user=user, request_id=request_id_of(request))
```
-For an API-authored failure that has no `PipelexError`:
+For a refusal the runner authors itself:
```python
if upload_size > MAX_UPLOAD_BYTES:
- raise_payload_too_large(message=f"Upload exceeds {MAX_UPLOAD_BYTES} bytes.")
+ msg = f"The upload is {upload_size} bytes, over the {MAX_UPLOAD_BYTES}-byte limit."
+ raise RunnerRequestError(msg).with_error_code(CoreCode.REQUEST_TOO_LARGE).with_params(limit=MAX_UPLOAD_BYTES, size=upload_size)
```
## Request/Response Models
diff --git a/api/pipelex_api/api_config.py b/api/pipelex_api/api_config.py
index 3357f5809..7e7a9bc95 100644
--- a/api/pipelex_api/api_config.py
+++ b/api/pipelex_api/api_config.py
@@ -30,9 +30,7 @@ from pipelex.runtime_bridge.orchestration_mode import DIRECT_ORCHESTRATION_MODE
from pipelex.system.configuration.config_loader import config_manager
from pydantic import BaseModel, ConfigDict
-from pipelex_api.error_types import ErrorType
-from pipelex_api.errors import raise_forbidden
-from pipelex_api.exceptions import ApiBootConfigError
+from pipelex_api.exceptions import ApiBootConfigError, OrchestrationOverrideForbiddenError
API_CONFIG_NAME = "api"
@@ -95,7 +93,7 @@ def resolve_orchestration_mode(requested: str | None, *, config: ApiConfig) -> s
override (``allow_request_orchestration_mode_override``). A caller-supplied
token equal to the default is always honored (it changes nothing). A caller
trying to FORCE a different mode on a runner whose policy forbids it is refused
- with a 403 — so a locked-down Temporal runner can never be coerced into
+ with a 422 ``pipelex.deployment.orchestration_override_forbidden`` — so a locked-down Temporal runner can never be coerced into
``direct`` (whose whole point would be to bypass distributed execution), and
vice versa. The token is a plain string compare; an *unregistered* token is
not rejected here — that surfaces at dispatch as ``MissingOrchestratorError``.
@@ -108,7 +106,7 @@ def resolve_orchestration_mode(requested: str | None, *, config: ApiConfig) -> s
f"This deployment does not allow overriding orchestration_mode per request "
f"(configured mode '{config.orchestration_mode}', requested '{requested}')."
)
- raise_forbidden(msg, error_type=ErrorType.ORCHESTRATION_MODE_OVERRIDE_FORBIDDEN)
+ raise OrchestrationOverrideForbiddenError(msg, requested_mode=requested)
def is_callers_override(*, orchestration_mode: str, config: ApiConfig) -> bool:
diff --git a/api/pipelex_api/blob_store.py b/api/pipelex_api/blob_store.py
index 13b98f6e5..41b6f0453 100644
--- a/api/pipelex_api/blob_store.py
+++ b/api/pipelex_api/blob_store.py
@@ -36,14 +36,17 @@ From this the blob store answers without reading what it does not need:
- `POST /v1/blobs/missing` lists a hash this runner does not hold at the size the sender states, an object held at
another size included. The upload then tells the two cases apart, holding the bytes: bytes of the size held are the
ones held, and nothing is written, while bytes of another size mean the object held is damaged, which only a storage
- that does not publish writes whole could leave, a 500 `BlobStoreCorrupted`, since nothing writes over a blob and its
- operator must remove the object.
+ that does not publish writes whole could leave, a 500 `pipelex.storage.damaged`, since nothing writes over a blob
+ and its operator must remove the object.
- A run looks up each hash's stored size first. A hash held at another size than an entry states is a 422
- `BlobMismatch`, never `MissingBlobs`, since uploading those bytes again would change nothing: the entry is wrong.
+ `request.invalid`, never `request.blobs_missing`, since uploading those bytes again would change nothing: the entry
+ is wrong.
Only a blob held at the size its entries state is read, so the bytes read are bounded by the sizes the request
states, which its census already held to the tree's limits, and each is checked against its hash once read. Bytes
- that do not hash to their key mean the storage itself is damaged, which no caller can repair: a 500
- `BlobStoreCorrupted`.
+ that do not hash to their key mean the object stored under it is damaged, which no caller can repair and no retry
+ cures: a 500 `pipelex.storage.damaged` naming the kind of storage, whose verdict is not to retry, and an error
+ record, "Stored blob bytes do not match their hash", naming the hash for the operator to remove the object, after
+ which the blob is uploaded again.
Lookups and reads run a bounded number at a time, so one request naming many blobs never opens them all at once.
"""
@@ -54,15 +57,17 @@ from functools import partial
from mthds.method_tree.digest import DIGEST_PREFIX, sha256_hex, tree_listing
from mthds.method_tree.file_entry import BlobStore, InMemoryBlobStore
from mthds.method_tree.models import MethodTree
+from pipelex import log
+from pipelex.config import get_config
from pipelex.core.method_trees.exceptions import MethodFileUnavailableError
from pipelex.core.method_trees.method_files import TreeListing
from pipelex.runtime_hub import get_storage_provider
from pipelex.tools.misc.async_utils import gather_bounded
from pipelex.tools.storage.exceptions import StorageFileNotFoundError
+from pipelex.tools.storage.storage_config import StorageMethod
from pipelex.tools.storage.storage_provider_abstract import PIPELEX_STORAGE_SCHEME, StorageProviderAbstract
-from pipelex_api.error_types import ErrorType
-from pipelex_api.errors import raise_internal_server_error
+from pipelex_api.exceptions import BlobStoreDamagedError
BLOBS_PREFIX = "blobs"
TREES_PREFIX = "trees"
@@ -72,19 +77,49 @@ _LISTING_CONTENT_TYPE = "text/plain; charset=utf-8"
# request runs at a time.
MAX_CONCURRENT_BLOB_LOOKUPS = 16
MAX_CONCURRENT_BLOB_TRANSFERS = 4
+# The message of the error record a blob read whose bytes do not match their hash writes, for the operator to search.
+BLOB_DAMAGED_MESSAGE = "Stored blob bytes do not match their hash"
+
+
+def problem_scheme_of(*, storage_method: str) -> str | None:
+ """The kind of storage a `pipelex.storage.*` problem names for a configured storage method, as the registry spells it.
+
+ `None` for a storage plugin's own method, which the registry's kinds do not list.
+ """
+ match storage_method:
+ case StorageMethod.LOCAL:
+ return "local"
+ case StorageMethod.IN_MEMORY:
+ return "memory"
+ case StorageMethod.S3:
+ return "s3"
+ case StorageMethod.GCP:
+ return "gcs"
+ case _:
+ # An external storage plugin's method token: the configured method is an open string.
+ return None
class RunnerBlobStore:
"""The blobs and tree listings of one caller's scope, over the deployment's storage provider."""
- def __init__(self, *, scope: str, storage: StorageProviderAbstract) -> None:
+ def __init__(self, *, scope: str, storage: StorageProviderAbstract, scheme: str | None) -> None:
+ """Build the blob store of one scope.
+
+ Args:
+ scope: The prefix of the scope's blobs and listings.
+ storage: The storage provider holding them.
+ scheme: The kind of storage the provider is, as a `pipelex.storage.*` problem names it (`problem_scheme_of`).
+ """
self._scope = scope
self._storage = storage
+ self._scheme = scheme
@classmethod
def make_for_scope(cls, *, scope: str) -> "RunnerBlobStore":
"""The blob store of `scope`, over the storage provider the runtime booted with."""
- return cls(scope=scope, storage=get_storage_provider())
+ scheme = problem_scheme_of(storage_method=get_config().runtime.storage.method)
+ return cls(scope=scope, storage=get_storage_provider(), scheme=scheme)
@property
def scope(self) -> str:
@@ -119,15 +154,21 @@ class RunnerBlobStore:
async def _read_verified(self, *, sha256: str, size: int) -> bytes:
"""The stored bytes of `sha256`, held at `size`, checked against their hash.
- Raises (as a problem document): a 500 `BlobStoreCorrupted` for bytes that are not `size` bytes hashing to `sha256`.
+ Raises (as a problem document): a 500 `pipelex.storage.damaged` naming the kind of storage, for bytes that
+ are not `size` bytes hashing to `sha256`, after an error record naming the hash, the one place the operator
+ reads which damaged object to remove.
"""
data = await self._storage.load(f"{PIPELEX_STORAGE_SCHEME}{self._blob_key(sha256=sha256)}")
if len(data) != size or sha256_hex(data) != sha256:
+ log.error(
+ BLOB_DAMAGED_MESSAGE,
+ fields={"blob_sha256": sha256, "blob_size_bytes": size, "read_size_bytes": len(data), "storage_scheme": self._scheme},
+ )
msg = (
- f"The bytes this runner's blob store holds under {sha256} do not hash to it: its storage is damaged, "
- "and its operator must remove that object for the blob to be uploaded again."
+ f"The bytes this runner's blob store holds under {sha256} do not hash to it: the storage holds a damaged "
+ "object, which its operator removes for the blob to be uploaded again."
)
- raise_internal_server_error(message=msg, error_type=ErrorType.BLOB_STORE_CORRUPTED)
+ raise BlobStoreDamagedError(msg, scheme=self._scheme)
return data
async def read_held(self, *, sizes: Mapping[str, int]) -> BlobStore:
@@ -149,8 +190,9 @@ class RunnerBlobStore:
free, with its hash as its checksum: a writer that created it meanwhile wrote the same bytes, and the key
holding an object is the blob held.
- Raises (as a problem document): a 500 `BlobStoreCorrupted` when an object of another size is held under the
- hash, which only damaged storage could hold and which this runner never writes over.
+ Raises (as a problem document): a 500 `pipelex.storage.damaged` naming the kind of storage when an object of
+ another size is held under the hash, which only damaged storage could hold and which this runner never writes
+ over, after the error record naming the hash that a read of damaged bytes writes.
"""
sha256 = sha256_hex(data)
await self._store_hashed_blob(sha256=sha256, data=data)
@@ -164,11 +206,15 @@ class RunnerBlobStore:
data=data, key=self._blob_key(sha256=sha256), content_type=_BLOB_CONTENT_TYPE, checksum_sha256_hex=sha256
)
elif held_size != len(data):
+ log.error(
+ BLOB_DAMAGED_MESSAGE,
+ fields={"blob_sha256": sha256, "blob_size_bytes": held_size, "read_size_bytes": len(data), "storage_scheme": self._scheme},
+ )
msg = (
f"This runner's blob store holds {held_size} bytes under {sha256}, whose bytes are {len(data)} long: its "
"storage is damaged, and its operator must remove that object for the blob to be uploaded again."
)
- raise_internal_server_error(message=msg, error_type=ErrorType.BLOB_STORE_CORRUPTED)
+ raise BlobStoreDamagedError(msg, scheme=self._scheme)
async def holds_tree(self, *, tree_digest: str) -> bool:
"""Whether the listing of the tree `tree_digest` names is held, which means every file of the tree is."""
diff --git a/api/pipelex_api/blob_upload.py b/api/pipelex_api/blob_upload.py
index 0c9b828f1..d5e027f1e 100644
--- a/api/pipelex_api/blob_upload.py
+++ b/api/pipelex_api/blob_upload.py
@@ -5,8 +5,9 @@ must say that the upload is allowed, as a presigned URL does on an object store.
names: its URL is its own `PUT /v1/blobs/{sha256}` with a query naming the blob store's scope, an expiry and an
HMAC-SHA256 signature over the scope, the hash and the expiry. The upload route checks the signature and the expiry,
writes under the scope the signature binds and nowhere else, and answers a missing, forged or expired signature with a
-403 `BlobUploadNotAuthorized`. The upload route therefore needs no bearer token: only a caller who passed the
-deployment's authentication on `POST /v1/blobs/missing` holds a target, for one hash, in its own scope, for a while.
+403 `auth.forbidden` whose `requirement` is a signed upload target. The upload route therefore needs no bearer token:
+only a caller who passed the deployment's authentication on `POST /v1/blobs/missing` holds a target, for one hash, in
+its own scope, for a while.
The key is `BLOB_UPLOAD_SIGNING_KEY` when the deployment sets it, which it must when several instances serve one
deployment, since a target named by one instance is checked by whichever instance receives the upload; otherwise each
@@ -28,8 +29,7 @@ from urllib.parse import urlencode, urlsplit
from fastapi import Request
from pipelex.system.environment import get_optional_env
-from pipelex_api.error_types import ErrorType
-from pipelex_api.errors import raise_internal_server_error
+from pipelex_api.exceptions import RunnerMisconfiguredError
from pipelex_api.limits import BLOB_UPLOAD_URL_TTL_SECONDS
PUBLIC_BASE_URL_ENV = "PUBLIC_BASE_URL"
@@ -62,8 +62,8 @@ def signed_upload_query(*, scope: str, sha256: str) -> str:
def _public_base_url() -> str | None:
"""`PUBLIC_BASE_URL` without its trailing slash, or None when unset.
- Raises (as a problem document): a 500 `ServerMisconfigured` for a value that is not an absolute http or https URL
- without a query or a fragment.
+ Raises (as a problem document): a 500 `runtime.misconfigured` naming `PUBLIC_BASE_URL`, for a value that is not an
+ absolute http or https URL without a query or a fragment.
"""
configured = get_optional_env(PUBLIC_BASE_URL_ENV)
if not configured:
@@ -71,7 +71,7 @@ def _public_base_url() -> str | None:
parts = urlsplit(configured)
if parts.scheme not in {"http", "https"} or not parts.netloc or parts.query or parts.fragment:
msg = f"Server configuration error: {PUBLIC_BASE_URL_ENV} must be an absolute http or https URL, such as https://runner.example.com."
- raise_internal_server_error(message=msg, error_type=ErrorType.SERVER_MISCONFIGURED)
+ raise RunnerMisconfiguredError(msg, component=PUBLIC_BASE_URL_ENV)
return configured.rstrip("/")
diff --git a/api/pipelex_api/bundle.py b/api/pipelex_api/bundle.py
index d4a58a155..56198e426 100644
--- a/api/pipelex_api/bundle.py
+++ b/api/pipelex_api/bundle.py
@@ -16,30 +16,30 @@ import binascii
import zipfile
from io import BytesIO
+from mthds.protocol.problem.registry import CoreCode, RequestMalformedReason
from pipelex import log
from pipelex.tools.log.error_fields import error_fields
-from pipelex_api.error_types import ErrorType
-from pipelex_api.errors import raise_bad_request, raise_payload_too_large, raise_validation_error
-from pipelex_api.limits import MAX_BUNDLE_FILES, MAX_BUNDLE_TOTAL_BYTES
+from pipelex_api.exceptions import MethodPackageReason, RequestMethodError, RunnerRequestError
+from pipelex_api.limits import MAX_BUNDLE_FILES, MAX_BUNDLE_TOTAL_BYTES, base64_decoded_size
-# Base64 inflates by 4/3; a zip is compressed, so a bundle whose DECOMPRESSED content is within
-# the ceiling encodes to well under this. Bounding the base64 string BEFORE decoding stops a
-# ~100 MiB request-body (the only other bound) from being expanded into ~75 MiB of heap just to
-# be rejected later by the decompressed-size guard. Slack (+4) covers padding.
-_MAX_BUNDLE_B64_CHARS = MAX_BUNDLE_TOTAL_BYTES * 4 // 3 + 4
+# The request field the archive rides, which the refusals of its encoding name.
+_BUNDLE_FIELD = "bundle_b64"
def _guard_count(count: int) -> None:
if count == 0:
- raise_validation_error(message="Bundle is empty (no files)", error_type=ErrorType.INVALID_BUNDLE)
+ msg = "Bundle is empty (no files)"
+ raise RunnerRequestError(msg, field=_BUNDLE_FIELD)
if count > MAX_BUNDLE_FILES:
- raise_payload_too_large(message=f"Bundle exceeds the {MAX_BUNDLE_FILES}-file limit (got {count})")
+ msg = f"Bundle exceeds the {MAX_BUNDLE_FILES}-file limit (got {count})"
+ raise RequestMethodError(msg).with_params(reason=MethodPackageReason.BUNDLE_TOO_MANY_FILES, limit=MAX_BUNDLE_FILES)
def _guard_running_total(total_bytes: int) -> None:
if total_bytes > MAX_BUNDLE_TOTAL_BYTES:
- raise_payload_too_large(message=f"Bundle exceeds the {MAX_BUNDLE_TOTAL_BYTES // 1024} KiB decompressed-size limit")
+ msg = f"Bundle exceeds the {MAX_BUNDLE_TOTAL_BYTES // 1024} KiB decompressed-size limit"
+ raise RequestMethodError(msg).with_params(reason=MethodPackageReason.BUNDLE_TOO_LARGE, limit=MAX_BUNDLE_TOTAL_BYTES)
def decode_bundle_archive(*, bundle_b64: str) -> list[tuple[str, bytes]]:
@@ -50,24 +50,45 @@ def decode_bundle_archive(*, bundle_b64: str) -> list[tuple[str, bytes]]:
cheap length check on the still-encoded string runs FIRST, so an oversized payload is refused before it is buffered
into memory as decoded bytes. A name the archive gives twice is returned twice, for the tree's reader to refuse.
- Raises (as problem documents): an oversized archive (413 `PayloadTooLarge`), a value that is not base64 (400
- `InvalidBase64`), and one that is not a zip archive or holds no file (422 `InvalidBundle`).
+ Raises (as problem documents): an archive past the size limit (413 `request.too_large`, its limit and its size in
+ bytes, the size read off the encoded length), a value that is
+ not base64 or not a zip archive (422 `request.malformed`), an archive holding no file (422 `request.invalid`), and
+ one past the limit on its files or on its decompressed size (422 `method.package_invalid`).
"""
- if len(bundle_b64) > _MAX_BUNDLE_B64_CHARS:
- raise_payload_too_large(message=f"bundle_b64 exceeds the {MAX_BUNDLE_TOTAL_BYTES // 1024} KiB compressed-size limit")
+ # A zip is compressed, so a bundle whose decompressed content is within the ceiling is an archive well under it. Its
+ # size is read off the encoded length, so a ~100 MiB request body, the only other bound, is refused before it is
+ # expanded into ~75 MiB of heap just to be refused later by the decompressed-size guard.
+ archive_bytes = base64_decoded_size(encoded=bundle_b64)
+ if archive_bytes > MAX_BUNDLE_TOTAL_BYTES:
+ msg = f"bundle_b64 exceeds the {MAX_BUNDLE_TOTAL_BYTES // 1024} KiB compressed-size limit"
+ raise (
+ RunnerRequestError(msg, field=_BUNDLE_FIELD)
+ .with_error_code(CoreCode.REQUEST_TOO_LARGE)
+ .with_params(limit=MAX_BUNDLE_TOTAL_BYTES, size=archive_bytes)
+ )
try:
raw = base64.b64decode(bundle_b64, validate=True)
except (binascii.Error, ValueError) as decode_error:
# DEBUG: the refusal below is a caller's mistake, which the error handler already logs; this keeps the cause.
log.debug("A bundle's base64 could not be decoded", fields=error_fields(exc=decode_error))
- raise_bad_request(message="bundle_b64 is not valid base64", error_type=ErrorType.INVALID_BASE64)
+ msg = "bundle_b64 is not valid base64"
+ raise (
+ RunnerRequestError(msg, field=_BUNDLE_FIELD)
+ .with_error_code(CoreCode.REQUEST_MALFORMED)
+ .with_params(reason=RequestMalformedReason.BAD_BASE64)
+ ) from decode_error
try:
archive = zipfile.ZipFile(BytesIO(raw))
except zipfile.BadZipFile as zip_error:
# DEBUG: the refusal below is a caller's mistake, which the error handler already logs; this keeps the cause.
log.debug("A bundle is not a valid zip archive", fields=error_fields(exc=zip_error))
- raise_validation_error(message="bundle_b64 is not a valid zip archive", error_type=ErrorType.INVALID_BUNDLE)
+ msg = "bundle_b64 is not a valid zip archive"
+ raise (
+ RunnerRequestError(msg, field=_BUNDLE_FIELD)
+ .with_error_code(CoreCode.REQUEST_MALFORMED)
+ .with_params(reason=RequestMalformedReason.BAD_ZIP)
+ ) from zip_error
entries: list[tuple[str, bytes]] = []
total_bytes = 0
diff --git a/api/pipelex_api/bundle_resources.py b/api/pipelex_api/bundle_resources.py
index 7be215ad3..f8c72040f 100644
--- a/api/pipelex_api/bundle_resources.py
+++ b/api/pipelex_api/bundle_resources.py
@@ -10,40 +10,44 @@ the tree's rule judges them as it judges the tree's own files.
Refusals, in the order they are checked:
-- more `resources` than `MAX_RESOURCES_PER_REQUEST` → 413 `PayloadTooLarge`;
-- a path that cannot name a file inside the bundle (absolute, a drive, a `..` segment, a backslash, a colon, empty, or
- a second spelling of a path already submitted) → 422 `InvalidResourcePath`, before any value is decoded, which also
- logs a security event when the path leaves the bundle, as a key of a method tree does;
-- a file whose encoded length already exceeds the per-file ceiling → 413 `PayloadTooLarge`, before decoding;
-- a value that is not valid base64 → 400 `InvalidBase64`, as `bundle_b64` is;
-- a decoded file over `MAX_RESOURCE_FILE_BYTES`, or a running total over `MAX_RESOURCES_TOTAL_BYTES` → 413.
+- more `resources` than `MAX_RESOURCES_PER_REQUEST` → 422 `request.invalid`, naming the field;
+- a path that leaves the bundle (absolute, a drive, a `..` segment) → 422 `security.input_path_refused`, with the rule
+ it breaks, before any value is decoded, which also logs a security event, as a key of a method tree does;
+- a path of the wrong shape (a backslash, a colon, empty, or a second spelling of a path already submitted) → 422
+ `request.invalid`, naming the field;
+- a file whose size, read off its encoded length, exceeds `MAX_RESOURCE_FILE_BYTES` → 413 `request.too_large`, before
+ decoding;
+- a value that is not valid base64 → 422 `request.malformed`, as `bundle_b64` is;
+- a running total of decoded files over `MAX_RESOURCES_TOTAL_BYTES` → 413 `request.too_large`.
+
+Every `request.too_large` states its `limit` and its `size` in bytes, never in encoded characters.
"""
import base64
import binascii
from typing import NoReturn
+from mthds.protocol.problem.registry import CoreCode, RequestMalformedReason
from pipelex import log
-from pipelex.core.bundle_resources.bundle_resource import canonical_resource_path
-from pipelex.core.bundle_resources.exceptions import BundleResourcePathError
+from pipelex.core.bundle_resources.bundle_resource import SUBMITTED_FILES_FIELD, canonical_resource_path
from pipelex.tools.log.error_fields import error_fields
-from pipelex_api.error_types import ErrorType
-from pipelex_api.errors import raise_bad_request, raise_payload_too_large, raise_validation_error, security_refusal_of
-from pipelex_api.limits import MAX_RESOURCE_FILE_BYTES, MAX_RESOURCES_PER_REQUEST, MAX_RESOURCES_TOTAL_BYTES
-
-# Base64 inflates by 4/3, so a file within the ceiling encodes to at most this many characters (+4 covers padding).
-# Checking the encoded length first refuses an oversized file before it is decoded into memory.
-_MAX_RESOURCE_B64_CHARS = MAX_RESOURCE_FILE_BYTES * 4 // 3 + 4
+from pipelex_api.exceptions import RunnerRequestError
+from pipelex_api.limits import MAX_RESOURCE_FILE_BYTES, MAX_RESOURCES_PER_REQUEST, MAX_RESOURCES_TOTAL_BYTES, base64_decoded_size
def refuse_two_files_under_one_path(*, path: str, where: str) -> NoReturn:
- """Refuse two different files sent under one path, naming the path, with a 422 `InvalidResourcePath`."""
+ """Refuse two different files sent under one path, naming the path, with a 422 `request.invalid` on `resources`."""
msg = (
f"Two different files are named '{path}', {where}. A path names one file of a method: send one of them, or rename "
"one and the step that reads it."
)
- raise_validation_error(message=msg, error_type=ErrorType.INVALID_RESOURCE_PATH)
+ raise RunnerRequestError(msg, field=SUBMITTED_FILES_FIELD)
+
+
+def _too_large(*, message: str, limit: int, size: int) -> RunnerRequestError:
+ """The refusal of submitted files past one of this runner's byte limits, a 413 `request.too_large`."""
+ return RunnerRequestError(message, field=SUBMITTED_FILES_FIELD).with_error_code(CoreCode.REQUEST_TOO_LARGE).with_params(limit=limit, size=size)
def decode_bundle_resources(*, resources: dict[str, str] | None) -> dict[str, bytes] | None:
@@ -51,38 +55,41 @@ def decode_bundle_resources(*, resources: dict[str, str] | None) -> dict[str, by
if not resources:
return None
if len(resources) > MAX_RESOURCES_PER_REQUEST:
- raise_payload_too_large(message=f"resources exceeds the {MAX_RESOURCES_PER_REQUEST}-file limit (got {len(resources)})")
- # Every path first, so a second spelling of one file is refused as such before any value is decoded.
+ # A count, not bytes, so not `request.too_large`, whose parameters are sizes in bytes: the field is refused.
+ msg = f"resources exceeds the {MAX_RESOURCES_PER_REQUEST}-file limit (got {len(resources)})"
+ raise RunnerRequestError(msg, field=SUBMITTED_FILES_FIELD)
+ # Every path first, so a second spelling of one file is refused as such before any value is decoded. A path that
+ # leaves the bundle is a security rule's refusal (`security.input_path_refused`), whose security event the error
+ # handler logs; one of the wrong shape is the request's (`request.invalid`), and logs none. Both propagate as raised.
sent_by_path: dict[str, tuple[str, str]] = {}
for path, encoded in resources.items():
- try:
- canonical_path = canonical_resource_path(path=path)
- except BundleResourcePathError as exc:
- # A path that leaves the bundle is a security rule's refusal (`security.input_path_refused`), whose security event
- # the response's handler logs; one of the wrong shape is the request's (`request.invalid`), and logs none. The
- # response keeps its error type either way.
- raise_validation_error(message=exc.message, error_type=ErrorType.INVALID_RESOURCE_PATH, security_refusal=security_refusal_of(error=exc))
+ canonical_path = canonical_resource_path(path=path)
if canonical_path in sent_by_path:
msg = f"Two files submitted with the bundle name the same file '{canonical_path}'."
- raise_validation_error(message=msg, error_type=ErrorType.INVALID_RESOURCE_PATH)
+ raise RunnerRequestError(msg, field=SUBMITTED_FILES_FIELD)
sent_by_path[canonical_path] = (path, encoded)
files: dict[str, bytes] = {}
total_bytes = 0
for canonical_path, (path, encoded) in sent_by_path.items():
- if len(encoded) > _MAX_RESOURCE_B64_CHARS:
- raise_payload_too_large(message=f"The file '{path}' in resources exceeds the {MAX_RESOURCE_FILE_BYTES // 1024} KiB per-file limit")
+ # Read off the encoded length, so an oversized file is refused before it is decoded into memory.
+ file_bytes = base64_decoded_size(encoded=encoded)
+ if file_bytes > MAX_RESOURCE_FILE_BYTES:
+ msg = f"The file '{path}' in resources exceeds the {MAX_RESOURCE_FILE_BYTES // 1024} KiB per-file limit"
+ raise _too_large(message=msg, limit=MAX_RESOURCE_FILE_BYTES, size=file_bytes)
try:
data = base64.b64decode(encoded, validate=True)
except (binascii.Error, ValueError) as decode_error:
# DEBUG: the refusal below is a caller's mistake, which the error handler already logs; this keeps the cause.
log.debug("A submitted file's base64 could not be decoded", fields=error_fields(exc=decode_error))
- raise_bad_request(message=f"The file '{path}' in resources is not valid base64", error_type=ErrorType.INVALID_BASE64)
- if len(data) > MAX_RESOURCE_FILE_BYTES:
- raise_payload_too_large(
- message=f"The file '{canonical_path}' a step reads exceeds the {MAX_RESOURCE_FILE_BYTES // 1024} KiB per-file limit"
- )
+ msg = f"The file '{path}' in resources is not valid base64"
+ raise (
+ RunnerRequestError(msg, field=SUBMITTED_FILES_FIELD)
+ .with_error_code(CoreCode.REQUEST_MALFORMED)
+ .with_params(reason=RequestMalformedReason.BAD_BASE64)
+ ) from decode_error
total_bytes += len(data)
if total_bytes > MAX_RESOURCES_TOTAL_BYTES:
- raise_payload_too_large(message=f"The files the bundle's steps read exceed the {MAX_RESOURCES_TOTAL_BYTES // 1024} KiB total-size limit")
+ msg = f"The files the bundle's steps read exceed the {MAX_RESOURCES_TOTAL_BYTES // 1024} KiB total-size limit"
+ raise _too_large(message=msg, limit=MAX_RESOURCES_TOTAL_BYTES, size=total_bytes)
files[canonical_path] = data
return files
diff --git a/api/pipelex_api/error_types.py b/api/pipelex_api/error_types.py
deleted file mode 100644
index bc4ad3437..000000000
--- a/api/pipelex_api/error_types.py
+++ /dev/null
@@ -1,115 +0,0 @@
-"""Centralized `error_type` symbols for API-authored error responses.
-
-Every fixed (non-dynamic) `error_type` an API-authored error emits lives here
-so call sites reference symbols, not literals — easier to grep, rename, and
-document. The `pipelex_api.errors` helpers stamp one of these onto the RFC 7807
-problem document as the `error_type` extension member.
-
-Pipelex domain errors answer their problem document, whose identity is its
-registry `code`, and are NOT enumerated here.
-"""
-
-from enum import StrEnum
-
-
-class ErrorType(StrEnum):
- # Authentication / authorization
- UNAUTHENTICATED = "Unauthenticated"
- FORBIDDEN = "Forbidden"
- # A caller asked to run in an orchestration_mode this deployment forbids overriding
- # (per-request override is off — see `allow_request_orchestration_mode_override` in api.toml).
- # A 403: the deployment policy refuses to honor the requested mode.
- ORCHESTRATION_MODE_OVERRIDE_FORBIDDEN = "OrchestrationModeOverrideForbidden"
- INVALID_TOKEN = "InvalidToken"
- TOKEN_EXPIRED = "TokenExpired"
- SERVER_MISCONFIGURED = "ServerMisconfigured"
-
- # A caller hit `/start` on a deployment whose resolved orchestration mode cannot do genuine
- # async (its orchestrator's `supports_fire_and_forget` is False — e.g. the in-process `direct`
- # base). `/start` is fire-and-forget by nature, so rather than silently running blocking and
- # acking, it refuses HONESTLY with a 400: use `/execute` (synchronous) instead. Checked AFTER
- # the override policy, so a forbidden per-request override still 403s first.
- START_REQUIRES_ASYNC_ORCHESTRATION = "StartRequiresAsyncOrchestration"
-
- # Request validation
- BAD_REQUEST = "BadRequest"
- VALIDATION_ERROR = "ValidationError"
- INVALID_JSON = "InvalidJSON"
- # A run request's body carries, at any depth, an object key a kajson decoder reads as a class
- # marker: `__class__`, `__module__`, or anything starting with `__kajson`. A 422, not data: the
- # run body is plain JSON, and such a key would make a later kajson round trip of the inputs
- # import and instantiate whatever class the caller named.
- RESERVED_OBJECT_KEY = "ReservedObjectKey"
- INVALID_CALLBACK_URLS = "InvalidCallbackUrls"
- # A run request's `storage_scope` extra is not one to three path-safe segments. A 422, not a
- # 500 from deep in the run: the value becomes a storage key prefix, so a `..` escapes the tenant.
- INVALID_STORAGE_SCOPE = "InvalidStorageScope"
- # A run request's `read_scope` extra is not one to three path-safe segments, or the run's storage
- # scope does not lie under it, so the run could not read back what it writes.
- INVALID_READ_SCOPE = "InvalidReadScope"
- # A caller authenticated by its own token (`AUTH_MODE=jwt`) sent a `read_scope` that does not lie under its own id.
- # A 403: the scope is well formed, but this caller may not read under it.
- READ_SCOPE_FORBIDDEN = "ReadScopeForbidden"
- # A run request's `analytics_groups` extra is not a mapping of group type to group key within
- # the runtime's charset and entry cap (`pipelex.system.run_extras`).
- INVALID_ANALYTICS_GROUPS = "InvalidAnalyticsGroups"
- INVALID_MODEL_CATEGORY = "InvalidModelCategory"
- # `GET /v1/models/check` was given a `reference` it cannot check: blank once trimmed, a sigil or a
- # namespace with nothing after it, or longer than the route's bound. A reference that parses and
- # resolves nowhere is never refused: it is the `not_found` verdict.
- INVALID_MODEL_REFERENCE = "InvalidModelReference"
- INVALID_BASE64 = "InvalidBase64"
- PAYLOAD_TOO_LARGE = "PayloadTooLarge"
- # A run request carried a malformed method bundle (`bundle_b64` / `files`): a corrupt zip, a
- # bundle with no `.mthds` file, or both transport forms supplied at once.
- INVALID_BUNDLE = "InvalidBundle"
- # A request's map of file entries (`files`, a tree of `dependencies`, a `bundle_b64` archive read as
- # one) is not a method tree the MTHDS standard admits: a key given twice, a key that is not a tree
- # path or names a file the membership rule keeps out of every tree, keys that collide, an empty map,
- # or a malformed entry. A 422 whose `tree_refusal` member carries the standard's refusal code and
- # the paths it names.
- INVALID_METHOD_FILES = "InvalidMethodFiles"
- # A request names, by hash, bytes this runner's blob store does not hold at the stated size. A 422
- # whose `missing_blobs` member lists every such hash at once, so a sender learns in one answer what to
- # upload (`POST /v1/blobs/missing`, then `PUT /v1/blobs/{sha256}`).
- MISSING_BLOBS = "MissingBlobs"
- # A method tree, or a blob, passes one of this runner's limits on a tree's file count, its total
- # size or one file's size (`MAX_METHOD_TREE_FILES`, `MAX_METHOD_TREE_TOTAL_KIB`,
- # `MAX_METHOD_TREE_FILE_KIB`). A 422 naming the limit, refused before any blob is read or uploaded.
- METHOD_TREE_TOO_LARGE = "MethodTreeTooLarge"
- # `PUT /v1/blobs/{sha256}` was sent bytes whose SHA-256 is not the one its path names,
- # `POST /v1/blobs/missing` named one hash twice with different sizes, or a request's hash entry states a size other
- # than the one this runner holds that hash's bytes at, which uploading them again would not change. A 422 whose
- # `mismatched_blobs` member, on a request's entries, lists each such hash with the size held.
- BLOB_MISMATCH = "BlobMismatch"
- # The bytes this runner's blob store holds under a hash do not hash to it: the storage is damaged. A 500 no caller
- # can repair; the operator removes the object, and the blob is then uploaded again.
- BLOB_STORE_CORRUPTED = "BlobStoreCorrupted"
- # `PUT /v1/blobs/{sha256}` was called without the signed query `POST /v1/blobs/missing` names in its upload
- # target, with one whose signature does not hold, or past its expiry. A 403: the upload is not stored.
- BLOB_UPLOAD_NOT_AUTHORIZED = "BlobUploadNotAuthorized"
- # A request's `resources` map keys a submitted file by a path that cannot name a file inside the
- # bundle: absolute, with a `..` segment, a backslash or a colon, empty, or a second spelling of a
- # path already submitted. A 422: the key is the path a step names, relative to the bundle.
- INVALID_RESOURCE_PATH = "InvalidResourcePath"
- # A method carrying custom Python (`.py` in a bundle, or in a fetched `method_ref` package)
- # reached a deployment that is NOT sandbox-hosted. Running customer code in-process is
- # refused (403): custom code is a sandbox-hosted capability only. Use a sandbox-hosted
- # deployment. (On a sandbox-hosted deployment, a bundle or a fetched package declaring Python
- # STRUCTURE classes is still refused — that is pipelex's `MethodStructuresRefusedError`, not this.)
- CUSTOM_CODE_REQUIRES_SANDBOX = "CustomCodeRequiresSandbox"
-
- # A caller selected a closure by a REGISTRY-FORM `method_ref` (not a `github.com/...`
- # address) on a tooling route. Address-form refs resolve server-side (fetch at tag, package
- # located by manifest identity); the registry form is the packaging program's closing phase,
- # so it keeps an honest 501 until a method registry exists — never a silent empty verdict.
- METHOD_REF_NOT_SUPPORTED = "MethodRefNotSupported"
-
- # Misc
- PACKAGE_NOT_FOUND = "PackageNotFound"
- # The `error_type` for the catch-all 500 emitted by `handle_unexpected_error`
- # (any failure matched by no more-specific handler — not an `ApiError`, a
- # `RequestValidationError`, a `PipelexError`, or an orchestrator plugin's mapped
- # transport exception). Stays in this enum so the same `build_problem_document_from_api_error`
- # builder renders it — same shape as every other API-authored 500.
- INTERNAL_SERVER_ERROR = "InternalServerError"
diff --git a/api/pipelex_api/error_uri.py b/api/pipelex_api/error_uri.py
deleted file mode 100644
index e8d118108..000000000
--- a/api/pipelex_api/error_uri.py
+++ /dev/null
@@ -1,42 +0,0 @@
-"""RFC 7807 `type` URI and `title` for API-authored errors.
-
-A pipelex error's problem always carries its own `type` and `title`, both the
-registry code's: the code's documentation page and the code's title. The global
-exception handler never needs these helpers for a `PipelexError`.
-
-They exist for the *other* error source: the API's own 4xx responses
-(`raise_validation_error` and friends in `pipelex_api.errors`), authored from the
-static `pipelex_api.error_types.ErrorType` enum with no pipelex error behind them.
-`build_problem_document_from_api_error` uses these to give an API-authored
-error an RFC 7807 `type` / `title` pair. Unlike a pipelex error's, that pair
-is still derived from a class name (`URLs.error_docs_base`, `pascal_case_to_kebab`,
-`pascal_case_to_sentence`) until every API-authored raise carries its own
-registry code. Both functions are pure.
-"""
-
-from pipelex.tools.misc.string_utils import pascal_case_to_kebab, pascal_case_to_sentence
-from pipelex.urls import URLs
-
-
-def error_type_uri(error_type: str) -> str:
- """Return the RFC 7807 `type` URI for an error type name.
-
- `ValidationError` -> `https://docs.pipelex.com/latest/errors/validation-error/`.
- The URI is derived from the class name, trailing slash included. No page
- lives at it: the per-class error pages are retired, and the docs site's 404
- page sends such a URI to the Error Codes index. The type URI stays
- class-derived until every API-authored raise carries its code from the error
- registry, whose type URI names the code's page, as a pipelex error's already does.
- """
- return f"{URLs.error_docs_base}/{pascal_case_to_kebab(error_type)}/"
-
-
-def error_type_title(error_type: str) -> str:
- """Return a human-readable RFC 7807 `title` for an error type name.
-
- `ValidationError` -> `Validation error`; `BadRequest` -> `Bad request`.
- Sentence case via `pascal_case_to_sentence`. It does NOT strip a trailing
- `Error`: an API `ErrorType` such as `ValidationError` must keep the suffix —
- `"Validation"` alone would be a worse label than `"Validation error"`.
- """
- return pascal_case_to_sentence(error_type)
diff --git a/api/pipelex_api/errors.py b/api/pipelex_api/errors.py
deleted file mode 100644
index e99633ff4..000000000
--- a/api/pipelex_api/errors.py
+++ /dev/null
@@ -1,217 +0,0 @@
-"""API-authored error helpers — RFC 7807 problem responses for the 4xx/5xx the API owns.
-
-These cover failures the API detects at its own boundary — request validation,
-auth, payload-size limits, server misconfiguration — as opposed to pipelex
-domain errors, which answer their own problem document through the global
-`PipelexError` handler in `pipelex_api.exception_handlers`.
-
-Each helper builds an RFC 7807 problem document (`build_problem_document_from_api_error`)
-and raises `ApiError`. The `handle_api_error` handler registered in
-`pipelex_api.exception_handlers` renders it as `application/problem+json`. Routes do
-NOT catch pipelex exceptions themselves — anything that is not an
-API-authored `ApiError` propagates to the global handlers. There are no
-catch tuples here anymore: the global `PipelexError` / `Exception` handlers
-are the single translation point for everything the API does not author
-itself.
-"""
-
-from collections.abc import Mapping
-from typing import Any, NamedTuple, NoReturn
-
-from pipelex.base_exceptions import ErrorDomain, PipelexError
-from pipelex.errors.error_codes import ErrorCode
-from pipelex.errors.security_event import log_security_event, security_target_kind
-from pipelex.errors.security_target import SecurityTargetClass
-
-from pipelex_api.error_types import ErrorType
-from pipelex_api.problem_document import build_problem_document_from_api_error
-
-
-class ApiSecurityRefusal(NamedTuple):
- """The refusal of a security rule an API-authored error answers, which its handler logs as a security event.
-
- It holds what the event names and never what was refused: the refusal's code, the class of the error that refused
- (or the response's `error_type` when no error class did), and the class of destination when the rule knows it.
- """
-
- code: ErrorCode
- error_type: str
- target_class: SecurityTargetClass | None = None
-
-
-def security_refusal_of(*, error: BaseException | None) -> ApiSecurityRefusal | None:
- """The security refusal `error` reports, when it is a `PipelexError` whose code is a security refusal, else `None`.
-
- For a route that answers a pipelex refusal with an API-authored problem document, which keeps the response the
- API has always given while the refusal still logs its security event.
- """
- if not isinstance(error, PipelexError):
- return None
- code = error.resolve_error_code()
- if security_target_kind(code=code) is None:
- return None
- return ApiSecurityRefusal(code=code, error_type=type(error).__name__, target_class=error.security_target_class)
-
-
-class ApiError(Exception):
- """An API-authored error carrying a ready-rendered RFC 7807 problem document.
-
- Raised by the `raise_*` helpers below; rendered by `handle_api_error` in
- `pipelex_api.exception_handlers` as `application/problem+json`. Distinct from a pipelex
- `PipelexError`: there is no problem of a pipelex error behind it — the failure is the
- API's own request validation, auth, or configuration check. The problem
- document is built at raise time, less the request context: `instance` and
- `request_id` are stamped by the handler, which is the frame that holds the
- `Request`.
- """
-
- def __init__(
- self,
- *,
- status_code: int,
- document: dict[str, Any],
- headers: dict[str, str] | None = None,
- security_refusal: ApiSecurityRefusal | None = None,
- ) -> None:
- self.status_code = status_code
- self.document = document
- self.headers: dict[str, str] = headers or {}
- self.security_refusal = security_refusal
- super().__init__(str(document.get("detail", "")))
-
-
-def log_api_security_event(*, api_error: ApiError, extras: Mapping[str, str] | None) -> None:
- """Log the security event of an API-authored error that answers a security rule's refusal, and nothing otherwise.
-
- The event names the request through the log context and the run's extras the body carried, never a run id, since
- no run exists yet, and never what was refused.
- """
- refusal = api_error.security_refusal
- if refusal is None:
- return
- log_security_event(code=refusal.code, error_type=refusal.error_type, target_class=refusal.target_class, extras=extras)
-
-
-def _raise_api_error(
- *,
- error_type: ErrorType,
- message: str,
- status: int,
- error_domain: ErrorDomain,
- headers: dict[str, str] | None = None,
- members: Mapping[str, Any] | None = None,
- security_refusal: ApiSecurityRefusal | None = None,
-) -> NoReturn:
- """Build the RFC 7807 document and raise `ApiError`.
-
- The document is built without the request context: `instance` and
- `request_id` are stamped by `handle_api_error`, from the `Request` it is
- handed. That keeps these helpers parameter-clean — a call site deep inside
- a route still needs no `Request` — while leaving the API with no ambient
- request state of its own, and it is how the three error paths end up
- reading the route and the id from exactly one place.
- """
- document = build_problem_document_from_api_error(
- error_type,
- message,
- status,
- instance=None,
- request_id=None,
- error_domain=error_domain,
- )
- if members:
- # Extension members of RFC 7807 (section 3.2), such as `missing_blobs`: data a client acts on, beside the prose.
- document.update(members)
- raise ApiError(status_code=status, document=document, headers=headers, security_refusal=security_refusal)
-
-
-def raise_validation_error(
- message: str,
- error_type: ErrorType = ErrorType.VALIDATION_ERROR,
- *,
- security_refusal: ApiSecurityRefusal | None = None,
-) -> NoReturn:
- """Raise a 422 RFC 7807 problem response for invalid caller input.
-
- `security_refusal` names the security rule the input broke, when it broke one, so the response's handler logs
- the security event of the refusal; the response is the same either way.
- """
- _raise_api_error(error_type=error_type, message=message, status=422, error_domain=ErrorDomain.INPUT, security_refusal=security_refusal)
-
-
-def raise_validation_problem(
- *,
- message: str,
- error_type: ErrorType,
- members: Mapping[str, Any],
- security_refusal: ApiSecurityRefusal | None = None,
-) -> NoReturn:
- """Raise a 422 RFC 7807 problem response for invalid caller input, carrying extension members a client acts on.
-
- The members join the document beside `detail`, such as the `missing_blobs` a sender uploads before it sends the
- request again, or the `tree_refusal` naming the standard's refusal code and the paths it names. `security_refusal`
- is `raise_validation_error`'s.
- """
- _raise_api_error(
- error_type=error_type,
- message=message,
- status=422,
- error_domain=ErrorDomain.INPUT,
- members=members,
- security_refusal=security_refusal,
- )
-
-
-def raise_bad_request(message: str, error_type: ErrorType = ErrorType.BAD_REQUEST) -> NoReturn:
- """Raise a 400 RFC 7807 problem response for a malformed request."""
- _raise_api_error(error_type=error_type, message=message, status=400, error_domain=ErrorDomain.INPUT)
-
-
-def raise_payload_too_large(message: str) -> NoReturn:
- """Raise a 413 RFC 7807 problem response for an over-limit payload."""
- _raise_api_error(error_type=ErrorType.PAYLOAD_TOO_LARGE, message=message, status=413, error_domain=ErrorDomain.INPUT)
-
-
-def raise_forbidden(message: str, error_type: ErrorType = ErrorType.FORBIDDEN) -> NoReturn:
- """Raise a 403 RFC 7807 problem response for an authorization failure."""
- _raise_api_error(error_type=error_type, message=message, status=403, error_domain=ErrorDomain.INPUT)
-
-
-def raise_unauthenticated(message: str, error_type: ErrorType = ErrorType.UNAUTHENTICATED) -> NoReturn:
- """Raise a 401 RFC 7807 problem response, with the `WWW-Authenticate: Bearer` challenge.
-
- RFC 7807 fully supports the challenge header: moving the body to
- `application/problem+json` does not break an OAuth/JWT client that parses
- `WWW-Authenticate`.
- """
- _raise_api_error(
- error_type=error_type,
- message=message,
- status=401,
- error_domain=ErrorDomain.INPUT,
- headers={"WWW-Authenticate": "Bearer"},
- )
-
-
-def raise_not_implemented(message: str, error_type: ErrorType) -> NoReturn:
- """Raise a 501 RFC 7807 problem response for a spec'd capability this server does not implement yet.
-
- For request shapes the published contract accepts but this deployment cannot serve (e.g. a
- `method_ref` closure selector before the method registry exists). A no-verdict condition —
- distinct from a 422 (the request is well-formed per the contract) and from a 200 invalid
- verdict (nothing was diagnosed). Classified `CONFIG` domain: neither the request nor the
- content is at fault.
- """
- _raise_api_error(error_type=error_type, message=message, status=501, error_domain=ErrorDomain.CONFIG)
-
-
-def raise_internal_server_error(message: str, error_type: ErrorType) -> NoReturn:
- """Raise a 500 RFC 7807 problem response for an API-owned server fault.
-
- For the API's own configuration / invariant failures — a missing secret, a
- storage backend that cannot presign, absent package metadata. NOT for
- pipelex domain errors, which answer their own problem through the
- global `PipelexError` handler. Classified `CONFIG` domain: an operator, not
- the caller, fixes it.
- """
- _raise_api_error(error_type=error_type, message=message, status=500, error_domain=ErrorDomain.CONFIG)
diff --git a/api/pipelex_api/exception_handlers.py b/api/pipelex_api/exception_handlers.py
index 5f29b3517..eac0b2b99 100644
--- a/api/pipelex_api/exception_handlers.py
+++ b/api/pipelex_api/exception_handlers.py
@@ -1,11 +1,15 @@
"""Global FastAPI exception handlers that translate any failure into RFC 9457.
The single place the API renders a failure into an HTTP response. Every
-handler produces the same `application/problem+json` shape: an `ApiError`
-(raised by the `pipelex_api.errors` 4xx/5xx helpers) carries a pre-built problem
-document; a FastAPI `RequestValidationError` from automatic request
-validation is rendered into one; every `PipelexError` becomes its problem
-document (`PipelexError.to_problem`); each orchestrator plugin's
+handler produces the same `application/problem+json` shape, a problem document
+with a registry code: every `PipelexError` becomes its problem document
+(`PipelexError.to_problem`), the runner's own refusals included, which it raises
+as the classes of `pipelex_api.exceptions`; a FastAPI `RequestValidationError`
+from automatic request validation becomes `request.invalid`, one item per
+refused field; a route nobody serves is `request.not_found`, a method a route
+does not accept `request.method_not_allowed`, and any other refusal the
+framework raises while reading a request `request.malformed`; a client gone
+mid-upload is `request.malformed` too; each orchestrator plugin's
transport-fault mapper (contributed through the plugin SPI's
`add_http_error_mapper`, discovered at app construction) gets its own handler
rendering the problem of the `PipelexError` it maps the fault to; everything
@@ -30,34 +34,34 @@ router wiring), so a misconfigured env var can't crash test collection of
every module that imports a handler at once.
"""
-import math
+import traceback
from collections.abc import Awaitable, Callable
+from enum import StrEnum, unique
+from http import HTTPStatus
from typing import TYPE_CHECKING, Any, cast
from fastapi import FastAPI, Request, Response
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
+from mthds.protocol.problem.registry import CoreCode, ProblemDomain
from pipelex import log
-from pipelex.base_exceptions import ErrorDomain, PipelexError
+from pipelex.base_exceptions import ErrorDomain, PipelexError, iter_traceback_chain
from pipelex.cogt.exceptions import find_inference_error_category_in_chain
-from pipelex.errors.error_codes import error_code_spec, parse_error_code
-from pipelex.errors.problem import PipelexProblem, ProblemView, caller_view_of
+from pipelex.errors.problem import PipelexProblem, ProblemDiagnostics, ProblemView
from pipelex.errors.security_event import emit_security_event
from pipelex.pipe_run.located_failure import make_unexpected_failure
from pipelex.plugins.registrar import HttpErrorMapperFn
from pipelex.system.telemetry.otel_constants import OTelLogAttr
from pipelex.tools.log.error_fields import ERROR_TYPE_FIELD
+from starlette.exceptions import HTTPException as StarletteHTTPException
from starlette.requests import ClientDisconnect
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
-from pipelex_api.error_types import ErrorType
-from pipelex_api.errors import ApiError, log_api_security_event
+from pipelex_api.exceptions import RunnerAuthError, RunnerRequestError
from pipelex_api.middleware import request_id_of
-from pipelex_api.problem_document import (
- PROBLEM_JSON_MEDIA_TYPE,
- build_problem_document_from_api_error,
- with_request_context,
-)
+from pipelex_api.problem_document import problem_json_response, problem_status
from pipelex_api.problem_view import problem_view_of
+from pipelex_api.request_refusals import callback_url_refusal_in, refused_request_error
if TYPE_CHECKING:
from pipelex_api.security import RequestUser
@@ -65,6 +69,19 @@ if TYPE_CHECKING:
# A Starlette/FastAPI async exception handler: `(request, exc) -> response`.
_ExceptionHandler = Callable[[Request, Exception], Awaitable[Response]]
+# The classes of the exceptions a failure's chain holds, by name, outermost first: what each one was raised from or
+# while handling, as a traceback would print them, without their text.
+ERROR_CHAIN_FIELD = "error.chain"
+
+# Where the deepest exception of the chain was raised, as `file:line in function` from the outermost frame inward,
+# without the source lines or any exception's text. Written on a 5xx alone, the failure an operator debugs.
+ERROR_FRAMES_FIELD = "error.frames"
+
+# The prefix of the fields carrying the problem's operator-only parameters, one field per parameter, such as
+# `error.params.component`. The registry marks a parameter operator-only when it names the runtime's own configuration
+# or one of its components, never a caller's content, so the record carries them whatever view the response took.
+ERROR_PARAMS_FIELD_PREFIX = "error.params."
+
def _user_id_of(request: Request) -> str | None:
"""Return the authenticated caller's id, when one is on the request.
@@ -115,11 +132,12 @@ def _pipeline_run_id_of(request: Request) -> str | None:
def _run_extras_of(request: Request) -> dict[str, str] | None:
- """Return the run's extras when `_parse_request` bound them on the request.
+ """Return the labels the request's body named, its `analytics_groups`, when they were bound on the request.
- The opaque labels a host attaches to a run, which the hosted plane fills with the organization. They ride
+ The opaque labels a host attaches to a request, which the hosted plane fills with the organization. They ride
the security event a refusal answered here logs, so a refusal before any run exists still names whose
- request it was. `None` for a route that parses no run request, or a body whose extras did not validate.
+ request it was. Bound as soon as a JSON body is parsed (`pipelex_api.run_extras_binding`); `None` for a request
+ with no JSON body, or a body naming no labels or labels that did not validate.
"""
return getattr(request.state, "run_extras", None)
@@ -128,8 +146,7 @@ def _request_fields(request: Request) -> dict[str, Any]:
"""Return the request-scoped attributes every error record carries.
Single source of truth for the `url.path` / `user.id` / `pipe_code` /
- `pipeline_run_id` set, so the three log paths (`_log_error_report`,
- `_log_api_authored_error`, `handle_unexpected_error`) cannot drift. The
+ `pipeline_run_id` set, which every record `_log_problem` emits carries. The
path and the caller take their OpenTelemetry keys, the pipe and the run
the runtime's own field names, so a query written for the runtime's lines
finds these too.
@@ -154,36 +171,30 @@ def _request_fields(request: Request) -> dict[str, Any]:
}
-# The HTTP status of a problem whose code the registry gives none, which only a client's own failure has.
-_FALLBACK_PROBLEM_STATUS = 500
+@unique
+class RecordLevel(StrEnum):
+ """The level of the record an error response writes, which decides whether it reaches the error-rate alerts.
-
-def _retry_after_header(problem: PipelexProblem, *, status: int) -> dict[str, str]:
- """Return a `Retry-After` header dict when a retry hint applies to this response.
-
- Emitted only when the response is itself a retry invitation — a 429, such as
- a provider's rate limit passed through — so a hint never rides a 500/422
- where `Retry-After` is meaningless. The problem's `retry_after`, which only a
- code inviting a retry carries and which is always finite, is rounded up to an
- integer. Empty dict when no hint applies.
+ `ERROR` for a failure whoever runs the server must look at, with the frames its deepest exception was raised through;
+ `WARNING` for a failure the caller caused or can avoid, without frames; `DEBUG` for a request no route serves, which
+ scanners send by the thousand and which nobody has anything to do about.
"""
- if status != 429:
- return {}
- seconds = problem.retry_after
- if seconds is None or not math.isfinite(seconds):
- return {}
- return {"Retry-After": str(max(0, math.ceil(seconds)))}
+ DEBUG = "debug"
+ WARNING = "warning"
+ ERROR = "error"
-def _status_of(problem: PipelexProblem) -> int:
- """The HTTP status of the response a problem is the body of: its code's, from the error registry."""
- code = parse_error_code(problem.code)
- if code is None:
- return _FALLBACK_PROBLEM_STATUS
- return error_code_spec(code).status or _FALLBACK_PROBLEM_STATUS
+ @property
+ def writes_frames(self) -> bool:
+ """Whether the record names where the deepest exception of the chain was raised, which only an operator's fault needs."""
+ match self:
+ case RecordLevel.ERROR:
+ return True
+ case RecordLevel.WARNING | RecordLevel.DEBUG:
+ return False
-def _emit_api_error(*, fields: dict[str, Any], as_error: bool) -> None:
+def _emit_api_error(*, fields: dict[str, Any], level: RecordLevel) -> None:
"""Emit one error record: a fixed message, everything about the failure a record attribute.
The message is the same on every error line, whichever handler produced it, so it is the key a
@@ -199,39 +210,94 @@ def _emit_api_error(*, fields: dict[str, Any], as_error: bool) -> None:
JSON sink's line, an OTLP attribute on the collector's.
`None`-valued fields are dropped, so an identifier this request never bound is
- absent rather than carried as a null. `as_error` picks the level — `error`
- (with the traceback) for operator-actionable failures, `warning` for
- `INPUT`-domain caller mistakes.
+ absent rather than carried as a null. `level` is the record's (`RecordLevel`). No record
+ carries the exception itself, whose traceback would print the text of every
+ exception of its chain, and a foreign exception's text, a pydantic
+ `ValidationError`'s or a method function's, can quote a run's inputs or a
+ model's answer: the record names the chain's classes and where the deepest
+ was raised instead (`_chain_fields`), with the problem's operator-only
+ parameters, which name the runtime's own configuration or component, such as
+ the `component` of a `runtime.misconfigured`. The capped message rides the
+ operator view's diagnostics alone, which only a request the operator
+ authenticated reads in its response.
"""
attributes = {key: value for key, value in fields.items() if value is not None}
- if as_error:
- log.error("A request ended in an error response", fields=attributes, include_exception=True)
- else:
- log.warning("A request ended in an error response", fields=attributes)
+ match level:
+ case RecordLevel.ERROR:
+ log.error("A request ended in an error response", fields=attributes)
+ case RecordLevel.WARNING:
+ log.warning("A request ended in an error response", fields=attributes)
+ case RecordLevel.DEBUG:
+ log.debug("A request ended in an error response", fields=attributes)
-def _emit_at_error_level(status: int) -> bool:
- """Decide the log disposition from the final HTTP status, not the error domain.
+def _chain_fields(error: BaseException, *, with_frames: bool) -> dict[str, Any]:
+ """The record fields naming a failure's exceptions by class, and with `with_frames` where the deepest was raised.
- A 5xx is a server fault — log at `error` with a traceback. A 4xx is
- client-facing (a caller mistake or a benign conflict) — log at `warning`
- without a traceback. Keying off the status the code declares is what keeps
- a conflict, such as ``pipelex.run.already_exists`` answered with 409, out of
- the error dashboards, while still covering the 422 caller mistakes and the
- provider-429 passthrough without a second per-error-type registry.
+ Never an exception's text: the classes and the frames are this server's code, while a message can be anyone's data.
+ """
+ chain = list(iter_traceback_chain(error))
+ fields: dict[str, Any] = {ERROR_CHAIN_FIELD: [type(link).__name__ for link in chain]}
+ if with_frames:
+ deepest = chain[-1]
+ frames = traceback.StackSummary.extract(traceback.walk_tb(deepest.__traceback__), lookup_lines=False)
+ fields[ERROR_FRAMES_FIELD] = [f"{frame.filename}:{frame.lineno} in {frame.name}" for frame in frames]
+ return fields
+
+
+def _operator_param_fields(*, diagnostics: ProblemDiagnostics | None) -> dict[str, Any]:
+ """The record fields carrying a problem's operator-only parameters, one per parameter, under `error.params.`.
+
+ The operator view keeps them in its diagnostics, which a caller's response leaves out, so the record is where the
+ operator reads them whatever view the response took: the `component` of a `runtime.misconfigured`, the `dependency`
+ of a `runtime.unavailable`, the setting or the file of a `pipelex.config.*`. The registry declares a parameter
+ operator-only when it names the runtime's own configuration or one of its components, never a caller's content, so
+ no run data reaches the record through them.
"""
- return status >= 500
+ if diagnostics is None or not diagnostics.params:
+ return {}
+ return {f"{ERROR_PARAMS_FIELD_PREFIX}{name}": value for name, value in diagnostics.params.items()}
+
+
+def record_level_of(*, status: int, domain: ProblemDomain) -> RecordLevel:
+ """The level of an error response's record, from its status and from who must act on it, its code's domain.
+ A 4xx is the caller's to act on, a mistake or a benign conflict such as ``pipelex.run.already_exists`` answered with
+ 409, so it logs at `warning`. A 5xx logs at `error` only when the server has something to fix:
-def _log_problem(problem: PipelexProblem, *, error: BaseException | None, request: Request, status: int) -> None:
+ - a `501` states that this deployment does not offer what the request asks for, custom code without a sandbox,
+ `/v1/start` on a blocking-only orchestrator, a model it serves no backend for. The operator decides whether to
+ offer it, but nothing is broken, and the caller meets the refusal each time it asks again, so it logs at `warning`,
+ or any caller could fill the error-rate alerts by repeating it;
+ - any other 5xx logs at `warning` when its domain is the caller's (`input`, `method`, `account`), a refusal the
+ caller can avoid, such as a webhook receiver of its own that refused a delivery, and at `error` when it is the
+ runtime's or the operator's.
+ """
+ match status:
+ case HTTPStatus.NOT_IMPLEMENTED:
+ return RecordLevel.WARNING
+ case server_status if server_status >= HTTPStatus.INTERNAL_SERVER_ERROR:
+ match domain:
+ case ProblemDomain.INPUT | ProblemDomain.METHOD | ProblemDomain.ACCOUNT:
+ return RecordLevel.WARNING
+ case ProblemDomain.OPERATOR | ProblemDomain.RUNTIME:
+ return RecordLevel.ERROR
+ case _:
+ return RecordLevel.WARNING
+
+
+def _log_problem(problem: PipelexProblem, *, error: BaseException | None, request: Request, status: int, level: RecordLevel | None) -> None:
"""Emit the structured error record for a failure answered with a problem, from the operator view.
- Disposition follows the HTTP status (see ``_emit_at_error_level``):
- a 4xx is client-facing and logs at `warning` without a traceback (caller
- mistakes, a provider's 429 passed through, and the 409 conflict), a 5xx
- logs at `error` with the traceback. `error.code` is the problem's code and
- `error.type` the class of the exception that escaped, else the class the
- operator view names. `user.id` rides every record when auth bound a caller —
+ Its level is `level` when the caller names one, else follows the HTTP status and the code's domain
+ (``record_level_of``): a 4xx is client-facing and logs at `warning` (caller mistakes, a provider's 429 passed through,
+ and the 409 conflict), a 5xx the server has to fix logs at `error` with the frames its deepest exception was raised
+ through. No record carries an
+ exception's text or its traceback (``_emit_api_error``). `error.code` is the
+ problem's code, `error.type` the class of the exception that escaped, else
+ the class the operator view names, and `error.chain` the classes of the
+ exceptions it was raised from, and each operator-only parameter of the problem
+ rides `error.params.<name>`. `user.id` rides every record when auth bound a caller —
without it, the storage / pipeline-backend leg of a failure carries only
`request_id` and `url.path`, and tying the failure to the caller requires
correlating the request id across unrelated records.
@@ -268,69 +334,35 @@ def _log_problem(problem: PipelexProblem, *, error: BaseException | None, reques
if diagnostics is not None and diagnostics.provider is not None:
fields["provider_status_code"] = diagnostics.provider.status
fields["provider_request_id"] = diagnostics.provider.request_id
- _emit_api_error(fields=fields, as_error=_emit_at_error_level(status))
-
-
-def _log_api_authored_error(*, document: dict[str, Any], status: int, request: Request) -> None:
- """Emit the structured error record for an API-authored error response.
-
- Shares the disposition rule and the common-key set of `_log_problem`
- so every error response — a pipelex error's problem
- *or* an API-authored 4xx/5xx raised by an `pipelex_api.errors` helper — produces
- one error record a downstream sink can filter uniformly on its message and
- on `request_id`, `url.path`, `error.type`, `error_domain`, `retryable`
- and `http.response.status_code`. Without this, an API-owned 500 (a `raise_internal_server_error`
- site — `/version`'s missing-package case is the canonical example)
- would land with zero operator output, since `handle_api_error` only
- serializes the response.
-
- Where the two helpers differ — by design, matching what each side actually
- has to log:
- - API-authored docs add `detail`, which the API wrote itself from what it
- checked, so it is the cause an operator reads.
- - API-authored docs omit `error.code`, `error_category`, `backend_name`, `model_handle`,
- `provider_status_code` and `provider_request_id` — those are inference-domain classifiers pipelex
- sets only on classifiable failures and the API never authors itself.
-
- A 4xx logs at `warning` without a traceback; a 5xx logs at `error` with
- the traceback — same status-keyed disposition rule `_log_problem`
- uses (see ``_emit_at_error_level``), so a sink dedup'ing by level sees one
- shape.
- """
- fields: dict[str, Any] = {
- **_request_fields(request),
- ERROR_TYPE_FIELD: document.get("error_type"),
- "error_domain": document.get("error_domain"),
- "retryable": document.get("retryable"),
- OTelLogAttr.HTTP_RESPONSE_STATUS_CODE: status,
- "detail": document.get("detail"),
- }
- _emit_api_error(fields=fields, as_error=_emit_at_error_level(status))
+ fields.update(_operator_param_fields(diagnostics=diagnostics))
+ record_level = level or record_level_of(status=status, domain=problem.effective_domain)
+ if error is not None:
+ fields.update(_chain_fields(error, with_frames=record_level.writes_frames))
+ _emit_api_error(fields=fields, level=record_level)
-def problem_response(problem: PipelexProblem, *, error: BaseException | None, request: Request) -> JSONResponse:
+def problem_response(
+ problem: PipelexProblem,
+ *,
+ error: BaseException | None,
+ request: Request,
+ headers: dict[str, str] | None = None,
+ status: int | None = None,
+ record_level: RecordLevel | None = None,
+) -> JSONResponse:
"""Render a problem built in the operator's view as the response to `request`, and log the failure.
- The single rendering of every failure a problem describes: a raised `PipelexError`, an
- orchestrator plugin's mapped transport fault, an unexpected exception, and a fault the
- `/validate` route receives as a value rather than a raise, for which `error` is `None`. The status is the code's, the
- record is logged from the operator view, and the body is the view of the request's reader
- (`pipelex_api.problem_view`), with its `status` member set to the response's.
+ The single rendering of every failure a problem describes: a raised `PipelexError`, the runner's own refusals
+ included, an orchestrator plugin's mapped transport fault, an unexpected exception, and a fault the `/validate` route
+ receives as a value rather than a raise, for which `error` is `None`. The status is the code's, unless `status` names
+ the one a framework refusal keeps; the record is logged from the operator view, at `record_level` when the caller
+ names one, else at the level its status and its code's domain give it (`record_level_of`), and the body is the view
+ of the request's reader (`pipelex_api.problem_view`), rendered by `pipelex_api.problem_document.problem_json_response`,
+ which adds `headers` to the ones its status calls for.
"""
- status = _status_of(problem)
- _log_problem(problem, error=error, request=request, status=status)
- match problem_view_of(request):
- case ProblemView.OPERATOR:
- reader_problem = problem
- case ProblemView.CALLER:
- reader_problem = caller_view_of(problem=problem)
- document = reader_problem.model_copy(update={"status": status}).to_wire()
- return JSONResponse(
- status_code=status,
- content=document,
- media_type=PROBLEM_JSON_MEDIA_TYPE,
- headers=_retry_after_header(problem, status=status),
- )
+ answered_status = status or problem_status(problem)
+ _log_problem(problem, error=error, request=request, status=answered_status, level=record_level)
+ return problem_json_response(problem, view=problem_view_of(request), headers=headers, status=answered_status)
def operator_problem_of(error: PipelexError, *, request: Request) -> PipelexProblem:
@@ -357,7 +389,18 @@ async def handle_pipelex_error(request: Request, exc: Exception) -> Response:
# the log context's, which `RequestIdMiddleware` binds for the whole request. No run id: the one a body names
# is the caller's claim, and no run the runtime assigned one to exists yet.
emit_security_event(error=error, extras=_run_extras_of(request))
- return problem_response(operator_problem_of(error, request=request), error=error, request=request)
+ return problem_response(operator_problem_of(error, request=request), error=error, request=request, headers=_challenge_headers(error))
+
+
+def _challenge_headers(error: PipelexError) -> dict[str, str] | None:
+ """The `WWW-Authenticate` challenge of an authentication refusal that names one, the scheme the deployment reads.
+
+ A refusal behind a trusted proxy names none: that deployment reads no credential of the request, so a challenge
+ would ask for one it never reads.
+ """
+ if isinstance(error, RunnerAuthError) and error.challenge is not None:
+ return {"WWW-Authenticate": error.challenge}
+ return None
def _make_orchestrator_error_handler(mapper: HttpErrorMapperFn) -> "_ExceptionHandler":
@@ -384,8 +427,9 @@ def _make_orchestrator_error_handler(mapper: HttpErrorMapperFn) -> "_ExceptionHa
async def handle_unexpected_error(request: Request, exc: Exception) -> Response:
"""Catch-all for any failure matched by no more-specific handler.
- Covers anything that is not an `ApiError`, a `RequestValidationError`, a
- `PipelexError`, or an orchestrator plugin's mapped transport exception — so on
+ Covers anything that is not a `RequestValidationError`, a `ClientDisconnect`, a
+ Starlette `HTTPException`, a `PipelexError`, or an orchestrator plugin's mapped
+ transport exception — so on
the orchestrator-agnostic base (which installs no mapper), an *unmapped* bare
transport/runtime error collapses here to a 500.
@@ -394,147 +438,266 @@ async def handle_unexpected_error(request: Request, exc: Exception) -> Response:
`PipelexUnexpectedError` (`make_unexpected_failure`) and answered as its
problem, `runtime.unexpected`, through the same rendering as every other
failure: the caller reads the code's own sentences and never the exception's
- text, and the operator reads its class in `diagnostics`, never its text either,
- which can carry anything of a run's data. A
- traceback reaches no response — it goes to the operator log, correlated by
- request id.
+ text, and a request the operator authenticated reads its class in
+ `diagnostics`, never its text either, which can carry anything of a run's
+ data. Neither a traceback nor the exception's text reaches the response or
+ the log: the operator's record names the chain's classes and the frames it
+ was raised through, correlated by request id.
This handler also covers a failure *inside* another handler: Starlette's
`ServerErrorMiddleware` wraps the others, so such a failure still lands here
- rather than a bodyless default.
+ rather than a bodyless default. That middleware raises the exception again
+ once this handler answered it, for the server to log with its traceback;
+ `AnsweredErrorBarrier` stops it there, so its text reaches no log either.
"""
unexpected_failure = make_unexpected_failure(error=exc)
- return problem_response(operator_problem_of(unexpected_failure, request=request), error=exc, request=request)
-
-
-async def handle_api_error(request: Request, exc: Exception) -> Response:
- """Render an API-authored `ApiError` as an RFC 7807 problem response.
-
- `ApiError` is raised by the `raise_*` helpers in `pipelex_api.errors` for the API's
- own 4xx/5xx — request validation, auth, payload limits, misconfiguration.
- The helper builds the problem document at raise time, where it holds no
- `Request`, so this handler stamps the two request-scoped members (`instance`
- and `request_id`) onto a copy of it, read from the same place as the
- request-validation path reads them. A `PipelexError`'s problem carries
- `request_id` alone, since the problem document leaves the RFC's `instance`
- out: the request id already names the occurrence. It then
- serializes that document, re-attaches any `WWW-Authenticate` challenge header,
- and emits the structured error record so an API-owned 500 from any
- route is observable (a `raise_internal_server_error` site like `version.py`'s
- missing-package case is the canonical example — it has no preceding
- `log.error` at the call site). An `ApiError` answering a security rule's refusal,
- a reserved object key, a callback URL or a path leaving the method, also logs its
- security event here, with the run's extras the body carried and no run id.
- `exc` is typed `Exception` to match Starlette's handler contract; FastAPI only
- routes an `ApiError` here, so the cast is sound.
+ response = problem_response(operator_problem_of(unexpected_failure, request=request), error=exc, request=request)
+ # Marked once its record is written, so `AnsweredErrorBarrier` tells the exception Starlette raises again after this
+ # answer from one nothing recorded.
+ request.state.answered_error = exc
+ return response
+
+
+async def handle_request_validation_error(request: Request, exc: Exception) -> Response:
+ """Answer FastAPI's automatic request validation failure as `request.invalid`, one item per refused field.
+
+ FastAPI raises `RequestValidationError` when a request body, query, or path parameter fails the endpoint's declared
+ model: an extra field under `extra="forbid"`, a length breach, a missing or mistyped field, a `field_validator`
+ raising `ValueError`. Its built-in handler would answer a bare `{"detail": [...]}` in `application/json`; this
+ handler answers the runner's own refusal instead (`pipelex_api.request_refusals`), `request.invalid` with one item
+ per refused field, or `request.malformed` for a body that is not JSON, through the same rendering every pipelex error
+ takes. A callback URL the SSRF rules refuse is found among the faults and answered as its own security refusal,
+ whichever route's model ran the check. `exc` is typed `Exception` to match Starlette's handler contract; FastAPI only
+ routes a `RequestValidationError` here, so the cast is sound.
"""
- api_error = cast("ApiError", exc)
- document = with_request_context(
- api_error.document,
- instance=request.url.path,
- request_id=request_id_of(request),
- )
- _log_api_authored_error(document=document, status=api_error.status_code, request=request)
- log_api_security_event(api_error=api_error, extras=_run_extras_of(request))
- return JSONResponse(
- status_code=api_error.status_code,
- content=document,
- media_type=PROBLEM_JSON_MEDIA_TYPE,
- headers=api_error.headers,
+ validation_error = cast("RequestValidationError", exc)
+ faults = validation_error.errors()
+ # A callback URL refusal is the error the model's validator raised, answered as itself; any other fault is answered by
+ # a refusal standing in for FastAPI's exception, chained from it so the record's `error.chain` still names it.
+ refusal = callback_url_refusal_in(faults=faults) or _standing_in_for(
+ refused_request_error(faults=faults, located_by_request_part=True), original=validation_error
)
+ return await handle_pipelex_error(request, refusal)
-def _summarize_request_validation_error(exc: RequestValidationError) -> str:
- """Render FastAPI's per-field validation failures as one human-readable string.
+def _standing_in_for(refusal: PipelexError, *, original: Exception) -> PipelexError:
+ """`refusal`, chained from the framework exception it answers in its place, as `raise refusal from original` would chain it.
- `RequestValidationError.errors()` is a list of per-field dicts; RFC 7807's
- `detail` is a single human-readable string, so each entry is rendered as
- `<location>: <message>` and the lot joined. Only `loc` and `msg` are read —
- both are plain strings / ints — so nothing unserializable from a crafted
- request body can reach the response.
+ A handler answering a framework exception through one of the runner's refusals builds that refusal itself, so nothing
+ raises it from the exception it stands in for. Chained, the record's `error.chain` names the framework exception
+ after the refusal, and the operator view's `diagnostics.causes` name its class, never its text.
"""
- parts: list[str] = []
- for error in exc.errors():
- location = ".".join(str(item) for item in error.get("loc", ()))
- message = error.get("msg") or "Invalid input"
- parts.append(f"{location}: {message}" if location else message)
- return "; ".join(parts) or "Request validation failed"
+ refusal.__cause__ = original
+ refusal.__suppress_context__ = True
+ return refusal
-# The `error_type` a FastAPI-validated body failing on exactly one of these fields carries,
-# so a client branches on the same value whichever route refused the field. `/execute` and
-# `/start` read their extras by hand and classify them the same way in `pipelex_api.routes.pipelex.pipeline`.
-_BODY_FIELD_ERROR_TYPES: dict[str, ErrorType] = {
- "analytics_groups": ErrorType.INVALID_ANALYTICS_GROUPS,
-}
+# The reason a body the client stopped sending is malformed, which none of the reasons `request.malformed` lists names.
+_BODY_INCOMPLETE_REASON = "body_incomplete"
-def _request_validation_error_type(exc: RequestValidationError) -> ErrorType:
- """Classify a request validation failure by the body field that failed.
+async def handle_client_disconnect(request: Request, exc: Exception) -> Response:
+ """Answer a client that left before its request body arrived in full as `request.malformed`, logged as a caller's failure.
- Only a failure confined to one classified body field gets that field's type; anything
- else — several fields, a query parameter, a model-level validator — keeps the generic
- `ValidationError`, because naming one field would hide the others.
+ 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 422 at `warning`, a caller's failure, never a 500 server fault logged with a
+ traceback. The body that arrived is cut short, so it is malformed; no reason the code lists fits a truncated body,
+ and its reason takes any string beside them, so the runner names this one itself.
"""
- failed_fields: set[str] = set()
- for error in exc.errors():
- location = tuple(error.get("loc", ()))
- if len(location) < 2 or location[0] != "body":
- return ErrorType.VALIDATION_ERROR
- failed_fields.add(str(location[1]))
- if len(failed_fields) != 1:
- return ErrorType.VALIDATION_ERROR
- return _BODY_FIELD_ERROR_TYPES.get(failed_fields.pop(), ErrorType.VALIDATION_ERROR)
-
-
-async def handle_request_validation_error(request: Request, exc: Exception) -> Response:
- """Translate FastAPI's automatic request validation failure into RFC 7807.
-
- FastAPI raises `RequestValidationError` when a request body, query, or path
- parameter fails the endpoint's declared Pydantic model — an extra field
- under `extra="forbid"`, a `min_length` / `max_length` breach, a missing or
- mistyped field, a `field_validator` raising `ValueError`, malformed JSON. Its
- built-in handler would answer with a bare `{"detail": [...]}` /
- `application/json` body; registering this handler overrides that so an
- endpoint's caller-input rejection is the same `application/problem+json`
- shape as an explicit `raise_validation_error` — one error contract across
- every endpoint. `exc` is typed `Exception` to match Starlette's handler
- contract; FastAPI only routes a `RequestValidationError` here, so the cast
- is sound.
+ message = "The client disconnected before the request body was received in full"
+ refusal = RunnerRequestError(message).with_error_code(CoreCode.REQUEST_MALFORMED).with_params(reason=_BODY_INCOMPLETE_REASON)
+ return await handle_pipelex_error(request, _standing_in_for(refusal, original=exc))
+
+
+# The reason a body the framework refused to read is malformed, for a refusal no check of the runner's own made first.
+_BODY_UNREADABLE_REASON = "unreadable"
+
+# The reason a body the framework refused as too large is malformed: the framework names no limit and no size, which the
+# runner's `request.too_large` must state, so the refusal is the reading's, and keeps its 413.
+_BODY_TOO_LARGE_REASON = "too_large"
+
+# The component a rate limit in front of a route is, which the operator reads on the record of the 429 it answered.
+_RATE_LIMITER_DEPENDENCY = "rate_limiter"
+
+# The one header a framework refusal of each status keeps, the one its answer needs: the methods a route accepts on a
+# 405, the challenge a credential refusal names on a 401, and the delay a rate limit asks for on a 429. Any other header
+# it was raised with is dropped. Compared in lower case, as HTTP header names are.
+_KEPT_FRAMEWORK_HEADER_BY_STATUS: dict[int, str] = {401: "www-authenticate", 405: "allow", 429: "retry-after"}
+
+
+def framework_refusal(*, status: int, challenge: str | None) -> tuple[PipelexError, int | None]:
+ """The runner's refusal answering a 4xx the framework raised, and the status it keeps when its code declares another.
+
+ Each refusal carries a code whose required parameters it can fill: the framework says nothing about a refusal but its
+ status and a header, so a code whose parameters it cannot know gives way to one whose parameters it can.
+
+ - a 400, or a 422 raised as an `HTTPException`, is a request the framework could not read, `request.malformed` with
+ the reason `unreadable`, keeping its status;
+ - a 401 is `auth.missing_credential`, with the challenge the raise named;
+ - a 403 is `auth.invalid_credential`, keeping its 403: `auth.forbidden` would need the `requirement` the identity
+ lacks, which the framework does not say;
+ - a 404 and a 405 are a request no route serves, `request.not_found` and `request.method_not_allowed`;
+ - a 413 is `request.malformed` with the reason `too_large`, keeping its 413: `request.too_large` states a limit and a
+ size, which the framework does not say;
+ - a 429 is `runtime.unavailable`, whose verdict invites a retry after the `Retry-After` the raise named, keeping its
+ 429, with the rate limiter as the dependency the operator reads: `account.rate_limited` would need the limit and
+ the window, which the framework does not say;
+ - any other 4xx, a 415 among them, is `request.malformed` with the reason `unreadable`, keeping its status: a form
+ of request the framework would not read.
"""
- validation_error = cast("RequestValidationError", exc)
- document = build_problem_document_from_api_error(
- _request_validation_error_type(validation_error),
- _summarize_request_validation_error(validation_error),
- 422,
- instance=request.url.path,
- request_id=request_id_of(request),
- error_domain=ErrorDomain.INPUT,
+ refusal: PipelexError
+ kept_status: int | None = None
+ match status:
+ case 400 | 422:
+ message = f"The framework refused to read the request with HTTP {status}"
+ refusal = RunnerRequestError(message).with_error_code(CoreCode.REQUEST_MALFORMED).with_params(reason=_BODY_UNREADABLE_REASON)
+ kept_status = status
+ case 401:
+ message = "The framework refused the request for want of a credential"
+ refusal = RunnerAuthError(message, challenge=challenge).with_error_code(CoreCode.AUTH_MISSING_CREDENTIAL)
+ case 403:
+ message = "The framework refused the request: its credential does not permit this operation"
+ refusal = RunnerAuthError(message).with_error_code(CoreCode.AUTH_INVALID_CREDENTIAL)
+ kept_status = status
+ case 404:
+ refusal = RunnerRequestError("No route serves this path").with_error_code(CoreCode.REQUEST_NOT_FOUND)
+ case 405:
+ refusal = RunnerRequestError("This route does not accept the request's method").with_error_code(CoreCode.REQUEST_METHOD_NOT_ALLOWED)
+ case 413:
+ message = "The framework refused the request as too large"
+ refusal = RunnerRequestError(message).with_error_code(CoreCode.REQUEST_MALFORMED).with_params(reason=_BODY_TOO_LARGE_REASON)
+ kept_status = status
+ case 429:
+ message = "A rate limit refused the request"
+ refusal = RunnerRequestError(message).with_error_code(CoreCode.RUNTIME_UNAVAILABLE).with_params(dependency=_RATE_LIMITER_DEPENDENCY)
+ kept_status = status
+ case _:
+ message = f"The framework refused the request with HTTP {status}, a status no registry code declares"
+ refusal = RunnerRequestError(message).with_error_code(CoreCode.REQUEST_MALFORMED).with_params(reason=_BODY_UNREADABLE_REASON)
+ kept_status = status
+ return refusal, kept_status
+
+
+# The statuses of the refusals Starlette's routing raises before any route runs, for a path nobody serves or a method its
+# route does not accept, which scanners probing for `/wp-admin` or `/.env` send by the thousand.
+_ROUTING_STATUSES = frozenset({HTTPStatus.NOT_FOUND, HTTPStatus.METHOD_NOT_ALLOWED})
+
+
+async def handle_http_exception(request: Request, exc: Exception) -> Response:
+ """Answer the refusals Starlette and FastAPI raise as `HTTPException`s as problems, never a client's 4xx as a 500.
+
+ Starlette raises an `HTTPException` when routing fails before any route runs: a 404 for a path nobody serves, and a
+ 405 for a method the path's route does not accept, with the `Allow` header listing the methods it does. The framework
+ raises one while it reads a request, too: FastAPI's 400 for a typed body its parse fails on with anything but a
+ `JSONDecodeError`, and Starlette's 400 for a form it cannot parse, which `JsonBodyRoute` mostly answers first
+ (`pipelex_api.json_body`). And a dependency the framework runs may raise one: FastAPI's security classes answer a
+ missing credential with a 401 or a 403, a rate limiter with a 429. No route of the runner raises one itself (its
+ refusals are the classes of `pipelex_api.exceptions`).
+
+ Each 4xx keeps its meaning (`framework_refusal`): it is answered under a code whose meaning matches its own and whose
+ parameters the runner can fill, keeping its status where that code declares another, and the one header it was
+ raised with that its answer needs rides along, the `Allow` of a 405, the `WWW-Authenticate` challenge of a 401 or the
+ `Retry-After` of a 429. A routing 404 or 405 writes its record at `DEBUG`, as Starlette's own answer wrote none: no one
+ has anything to do about a path nobody serves, and a scanner probing for them would otherwise fill the warnings. A 5xx
+ is the framework's own failure, `runtime.unexpected`. The refusal is chained from the `HTTPException`, so the record's
+ `error.chain` names it. `exc` is typed `Exception` to match Starlette's handler contract; Starlette only routes an
+ `HTTPException` here, so the cast is sound.
+ """
+ http_exception = cast("StarletteHTTPException", exc)
+ status = http_exception.status_code
+ if not 400 <= status < 500:
+ return await handle_unexpected_error(request, http_exception)
+ kept_header = _KEPT_FRAMEWORK_HEADER_BY_STATUS.get(status)
+ kept_headers = {key: value for key, value in (http_exception.headers or {}).items() if key.lower() == kept_header}
+ challenge = next(iter(kept_headers.values()), None) if kept_header == "www-authenticate" else None
+ refusal, kept_status = framework_refusal(status=status, challenge=challenge)
+ refusal = _standing_in_for(refusal, original=http_exception)
+ record_level = RecordLevel.DEBUG if status in _ROUTING_STATUSES else None
+ return problem_response(
+ operator_problem_of(refusal, request=request),
+ error=refusal,
+ request=request,
+ headers=kept_headers,
+ status=kept_status,
+ record_level=record_level,
)
- # Same error record as an explicit `raise_validation_error`,
- # so FastAPI's automatic-validation 422s aren't silent in operator logs.
- _log_api_authored_error(document=document, status=422, request=request)
- return 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.
+# The message of the record `AnsweredErrorBarrier` writes for a failure no handler recorded, once a response had started.
+UNRECORDED_FAILURE_MESSAGE = "A request failed after its response had started"
+
+
+class AnsweredErrorBarrier:
+ """Pure-ASGI layer around the app that keeps an exception it answered from reaching the server that runs it.
- 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.
+ Starlette's `ServerErrorMiddleware` runs the catch-all handler (`handle_unexpected_error`) and then raises the
+ exception again, so that the server can log it: uvicorn writes it with its traceback through its own logger,
+ outside the runner's records, and a traceback prints the text of every exception of its chain, which a foreign
+ exception can fill with a run's inputs or a model's answer. This layer sits outside that middleware and stops the
+ exception there. When no response has started, which only a failure of the handler itself leaves, the failure is
+ answered and logged here as the handler would have. Once one has, nothing can be answered any more: the exception
+ the handler answered, which it marks once its record is written, is dropped, and any other, the handler's own
+ failure while a response was streaming or sending, is dropped after a record of its own,
+ `UNRECORDED_FAILURE_MESSAGE`, which names the request's path, the status already sent and the chain by class, never
+ an exception's text. A failure of the barrier's own answer, the catch-all building it or the server sending it, such
+ as to a client already gone, is recorded and dropped the same way. So no exception, and no text of one, leaves the
+ app, and none leaves it unrecorded.
+
+ `pipelex_api.main` puts it directly around the FastAPI app, inside `RequestIdMiddleware`, so the request's log
+ context is still bound while it answers.
"""
- 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 __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
+ sent_status: int | None = None
+
+ async def tracking_send(message: Message) -> None:
+ nonlocal sent_status
+ if message["type"] == "http.response.start":
+ sent_status = message["status"]
+ await send(message)
+
+ try:
+ await self.app(scope, receive, tracking_send)
+ except Exception as exc: # ruff: ignore[BLE001]
+ # The absolute root of an API endpoint handler, outside Starlette's own catch-all, which raises whatever
+ # reached it again.
+ request = Request(scope)
+ if sent_status is not None:
+ if getattr(request.state, "answered_error", None) is not exc:
+ _log_unrecorded_failure(exc, request=request, sent_status=sent_status)
+ return
+ try:
+ response = await handle_unexpected_error(request, exc)
+ await response(scope, receive, tracking_send)
+ except Exception as answer_failure: # ruff: ignore[BLE001]
+ # The absolute root still: the barrier's own answer failed, the catch-all building it or the server
+ # sending it, such as to a client already gone, and nothing is left to answer it.
+ _log_unrecorded_failure(answer_failure, request=request, sent_status=sent_status)
+
+
+def _log_unrecorded_failure(error: BaseException, *, request: Request, sent_status: int | None) -> None:
+ """Record a failure no handler recorded, which ended a request after its response had started.
+
+ The response's status and part of it are already sent, so the failure is answered by no problem: the record names the
+ request's path, the status sent, the class that escaped and the classes of its chain, and never an exception's text.
+ `sent_status` is `None` only when the barrier's own answer failed before its status was sent, which leaves the
+ server to answer for it, and the record then names no status.
+ """
+ fields: dict[str, Any] = {
+ "url.path": request.url.path,
+ ERROR_TYPE_FIELD: type(error).__name__,
+ **_chain_fields(error, with_frames=False),
+ }
+ if sent_status is not None:
+ fields[OTelLogAttr.HTTP_RESPONSE_STATUS_CODE] = sent_status
+ log.error(UNRECORDED_FAILURE_MESSAGE, fields=fields)
def register_exception_handlers(
@@ -544,11 +707,11 @@ def register_exception_handlers(
) -> None:
"""Register the app-level exception handlers on `app`.
- Resolution is most-specific-first: an API-authored `ApiError` →
- `handle_api_error`; a FastAPI `RequestValidationError` (automatic
+ Resolution is most-specific-first: a FastAPI `RequestValidationError` (automatic
request-body / parameter validation) → `handle_request_validation_error`; a
Starlette `ClientDisconnect` (the client left mid-upload) →
- `handle_client_disconnect`; a
+ `handle_client_disconnect`; a Starlette `HTTPException` (a path no route
+ serves, a method a route does not accept) → `handle_http_exception`; a
`PipelexError` (including an orchestrator plugin's `PipelexError`-derived
workflow failure) → `handle_pipelex_error`; a bare orchestrator-SDK transport
error → that plugin's mapper-backed handler (see `http_error_mappers`);
@@ -575,9 +738,9 @@ def register_exception_handlers(
picked per request, by the identity its authentication established
(`pipelex_api.problem_view`).
"""
- 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(StarletteHTTPException, handle_http_exception)
app.add_exception_handler(PipelexError, handle_pipelex_error)
for exc_type, mapper in (http_error_mappers or {}).items():
app.add_exception_handler(exc_type, _make_orchestrator_error_handler(mapper))
diff --git a/api/pipelex_api/exceptions.py b/api/pipelex_api/exceptions.py
index 282255cea..59c3bd884 100644
--- a/api/pipelex_api/exceptions.py
+++ b/api/pipelex_api/exceptions.py
@@ -6,13 +6,44 @@ body, as pipelex's error model requires (``pipelex/errors/error_code_declaration
beside the code that raises them, as every error class does: the same gate refuses one defined outside an
``exceptions.py`` or ``<topic>_exceptions.py`` module.
-The API-authored refusals (``pipelex_api.errors.ApiError``, built from ``pipelex_api.error_types.ErrorType``) are a
-separate family with no pipelex error behind them.
+The refusals the runner authors at its own boundary, a request it cannot parse or accept, a credential it refuses, a
+method tree it cannot read, a deployment policy, are raised as these classes like any other pipelex error, so the one
+global handler (``pipelex_api.exception_handlers.handle_pipelex_error``) answers each with its problem document, in the
+view of the request's reader, and logs the security event of one that is a security refusal. A raise site chooses the
+code its class declares with ``with_error_code`` and gives the code's parameters with ``with_params``; the problem's
+``detail`` and ``next_step`` are the code's sentences, while the message stays the operator's, in ``diagnostics``.
"""
+from enum import StrEnum, unique
+from typing import Any
+
+from mthds.protocol.problem.models import ProblemLocation
from mthds.protocol.problem.registry import CoreCode
from pipelex.base_exceptions import PipelexError
+from pipelex.errors.error_code_declaration import ErrorCodeSet
+from pipelex.errors.problem import make_location
from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
+from pipelex.errors.security_target import SecurityTargetClass
+from typing_extensions import override
+
+
+class RequestFieldConflictError(PipelexError, ValueError):
+ """A request whose fields contradict each other, refused by its model's validator, naming the field to change.
+
+ Also a ``ValueError``, since a model validator raises it, which pydantic reports as a fault of the body as a whole,
+ located at no field. The request's refusal reads it from the fault's context (``pipelex_api.request_refusals``) and
+ names its ``field`` instead, so the `request.invalid` item tells the caller which field to change or drop.
+ """
+
+ error_code = CoreCode.REQUEST_INVALID
+
+ def __init__(self, message: str, *, field: str) -> None:
+ super().__init__(message)
+ self.field = field
+
+ @override
+ def problem_params(self) -> dict[str, Any]:
+ return {"field": self.field}
class ApiBootConfigError(PipelexError):
@@ -31,8 +62,260 @@ class CallbackUrlRefusedError(PipelexError, ValueError):
"""A completion callback URL the SSRF rules refuse: a scheme other than http or https, or a disallowed host.
Also a ``ValueError``, since the check runs inside the request model's validator, which turns only a ``ValueError``
- into a validation error. The route answering the validation error reads it from there to log its security event,
- with the class of destination it states and never the URL.
+ into a validation error. The run routes find it there and raise it again, so it answers with its own code and logs
+ its security event, with the class of destination it states and never the URL.
"""
error_code = CoreCode.SECURITY_INPUT_URL_REFUSED
+
+ @override
+ def problem_params(self) -> dict[str, Any]:
+ target_class = self.security_target_class
+ reason: str
+ match target_class:
+ case SecurityTargetClass.SCHEME:
+ reason = "scheme_not_allowed"
+ case (
+ SecurityTargetClass.LOOPBACK
+ | SecurityTargetClass.PRIVATE
+ | SecurityTargetClass.LINK_LOCAL
+ | SecurityTargetClass.METADATA
+ | SecurityTargetClass.FOREIGN_STORAGE_KEY
+ | None
+ ):
+ reason = "host_not_allowed"
+ params: dict[str, Any] = {"input": "callback_urls", "reason": reason}
+ # A host the rules could not classify has no class to state: the parameter is left out rather than given as a
+ # `None` its code would refuse, and the sentence that names it falls back on the code's generic one.
+ if target_class is not None:
+ params["target_class"] = target_class.listed_target_class
+ return params
+
+ @override
+ def problem_location(self) -> ProblemLocation | None:
+ return make_location(field="callback_urls")
+
+
+class RunnerRequestError(PipelexError):
+ """A request the runner refuses at its own boundary, before it reads a method or runs anything.
+
+ Its code defaults to ``request.invalid``, a field the route's rules refuse, which ``field`` names, as the problem's
+ ``field`` parameter and its location. The raise site chooses ``request.malformed`` for a body, or an encoded part of
+ one, that cannot be parsed, ``request.too_large`` for a request past one of this runner's size limits,
+ ``request.unsupported`` for a form this runner does not accept, ``request.blobs_missing`` for files sent by hash
+ that this runner does not hold, ``request.not_found`` and ``request.method_not_allowed`` for a request no route
+ serves, and ``runtime.unavailable``, naming the rate limiter as its ``dependency``, for a request a rate limit in
+ front of a route refused, which only the web framework's own refusal answers
+ (``pipelex_api.exception_handlers.framework_refusal``).
+ """
+
+ error_code = ErrorCodeSet(
+ default=CoreCode.REQUEST_INVALID,
+ others=(
+ CoreCode.REQUEST_MALFORMED,
+ CoreCode.REQUEST_TOO_LARGE,
+ CoreCode.REQUEST_UNSUPPORTED,
+ CoreCode.REQUEST_BLOBS_MISSING,
+ CoreCode.REQUEST_NOT_FOUND,
+ CoreCode.REQUEST_METHOD_NOT_ALLOWED,
+ CoreCode.RUNTIME_UNAVAILABLE,
+ ),
+ )
+
+ def __init__(self, message: str, *, field: str | None = None) -> None:
+ """Build the refusal of a request.
+
+ Args:
+ message: What is wrong with the request, for the operator's diagnostics.
+ field: The refused field, as the request spells it, or a dotted path into the body; `None` when the refusal is
+ of the request as a whole.
+ """
+ super().__init__(message)
+ self.field = field
+
+ @override
+ def problem_params(self) -> dict[str, Any]:
+ if self.field is None:
+ return {}
+ return {"field": self.field}
+
+ @override
+ def problem_location(self) -> ProblemLocation | None:
+ return make_location(field=self.field)
+
+
+class RunnerAuthError(PipelexError):
+ """A request the runner's authentication refuses.
+
+ Its code defaults to ``auth.invalid_credential``, a credential the runner refuses. The raise site chooses
+ ``auth.missing_credential`` when the request carries none, ``auth.credential_expired`` when its token expired, and
+ ``pipelex.deployment.token_claims_invalid`` when a token whose signature holds carries claims this runner cannot use,
+ which its issuer, not its bearer, must fix, and ``auth.forbidden`` when the request lacks what an operation needs,
+ whose ``requirement`` it names, such as the signed target a blob upload needs.
+ """
+
+ error_code = ErrorCodeSet(
+ default=CoreCode.AUTH_INVALID_CREDENTIAL,
+ others=(
+ CoreCode.AUTH_MISSING_CREDENTIAL,
+ CoreCode.AUTH_CREDENTIAL_EXPIRED,
+ CoreCode.AUTH_FORBIDDEN,
+ PipelexErrorCode.DEPLOYMENT_TOKEN_CLAIMS_INVALID,
+ ),
+ )
+
+ def __init__(self, message: str, *, challenge: str | None = None) -> None:
+ """Build the refusal of a request's authentication.
+
+ Args:
+ message: What the authentication refused, for the operator's diagnostics.
+ challenge: The `WWW-Authenticate` challenge the response carries, naming the scheme of the credential the
+ deployment reads, `Bearer` for a token or an API key; `None` where it reads no credential of the
+ request, as behind a trusted proxy, which a challenge would ask for one the deployment never reads.
+ """
+ super().__init__(message)
+ self.challenge = challenge
+
+
+class RunnerMisconfiguredError(PipelexError):
+ """The runner's own configuration or installation cannot serve the request: a setting is missing or wrong.
+
+ ``component`` names what is misconfigured, such as the environment variable, and only the operator's view reads it.
+ """
+
+ error_code = CoreCode.RUNTIME_MISCONFIGURED
+
+ def __init__(self, message: str, *, component: str) -> None:
+ super().__init__(message)
+ self.component = component
+
+ @override
+ def problem_params(self) -> dict[str, Any]:
+ return {"component": self.component}
+
+
+class BlobStoreDamagedError(PipelexError):
+ """Bytes the blob store holds under a hash do not hash to it, or are not the size it holds them at.
+
+ The object stored under the hash is damaged: storage holds it, but not the bytes the runtime stored. No caller
+ can repair that, no upload of theirs changes it, and a retry reads the same damaged object, which stays until the
+ operator removes it: ``pipelex.storage.damaged``, a 500 whose verdict is not to retry and whose step is to report
+ it. ``scheme`` is the kind of storage the deployment runs, ``None`` for a storage plugin whose kind the registry does
+ not list.
+ """
+
+ error_code = PipelexErrorCode.STORAGE_DAMAGED
+
+ def __init__(self, message: str, *, scheme: str | None) -> None:
+ super().__init__(message)
+ self.scheme = scheme
+
+ @override
+ def problem_params(self) -> dict[str, Any]:
+ if self.scheme is None:
+ return {}
+ return {"scheme": self.scheme}
+
+
+class OrchestrationOverrideForbiddenError(PipelexError):
+ """A request choosing an orchestration mode on a deployment that fixes its own."""
+
+ error_code = PipelexErrorCode.DEPLOYMENT_ORCHESTRATION_OVERRIDE_FORBIDDEN
+
+ def __init__(self, message: str, *, requested_mode: str) -> None:
+ super().__init__(message)
+ self.requested_mode = requested_mode
+
+ @override
+ def problem_params(self) -> dict[str, Any]:
+ return {"requested_mode": self.requested_mode}
+
+
+class CustomCodeOrigin(StrEnum):
+ """Where a method that ships Python carries it: in the bundle a request sent, or in a package fetched by address."""
+
+ BUNDLE = "bundle"
+ PACKAGE = "package"
+
+
+class CustomCodeRequiresSandboxError(PipelexError):
+ """A method shipping Python on a deployment that runs none outside the Daytona sandbox."""
+
+ error_code = PipelexErrorCode.DEPLOYMENT_CUSTOM_CODE_REQUIRES_SANDBOX
+
+ def __init__(self, message: str, *, origin: CustomCodeOrigin) -> None:
+ super().__init__(message)
+ self.origin = origin
+
+ @override
+ def problem_params(self) -> dict[str, Any]:
+ return {"origin": self.origin}
+
+
+class ReservedObjectKeyError(PipelexError):
+ """A request body holding an object key a kajson decoder reads as a class marker, which a security rule refuses."""
+
+ error_code = PipelexErrorCode.SECURITY_RESERVED_KEY
+
+ def __init__(self, message: str, *, keys: list[str]) -> None:
+ super().__init__(message)
+ self.keys = keys
+
+ @override
+ def problem_params(self) -> dict[str, Any]:
+ return {"keys": self.keys}
+
+
+@unique
+class MethodPackageReason(StrEnum):
+ """The `reason` of a `method.package_invalid` this runner raises itself, one member per rule and one per limit.
+
+ Beside them, a refusal of the standard's tree rule gives the standard's own refusal code (`TreeRefusalCode`) as its
+ reason. A limit's refusal also gives its `limit`, and each limit has its own reason, so a caller reads which one the
+ method passed: a tree's, a request's or a `bundle_b64` archive's.
+ """
+
+ # The limits of one method tree.
+ TOO_MANY_FILES = "too_many_files"
+ FILE_TOO_LARGE = "file_too_large"
+ TREE_TOO_LARGE = "tree_too_large"
+ # The limits of a request's trees together.
+ TOO_MANY_DEPENDENCIES = "too_many_dependencies"
+ METHOD_TOO_LARGE = "method_too_large"
+ # The limits of a `bundle_b64` archive, on its members and on its decompressed size.
+ BUNDLE_TOO_MANY_FILES = "bundle_too_many_files"
+ BUNDLE_TOO_LARGE = "bundle_too_large"
+ # The method's own tree holds no `.mthds` bundle.
+ NO_BUNDLE = "no_bundle"
+ # The manifest of a shipped package or of a dependency tree.
+ MANIFEST_MISSING = "manifest_missing"
+ MANIFEST_INVALID = "manifest_invalid"
+ PACKAGE_NAME_INVALID = "package_name_invalid"
+ # Two dependencies a reference could not tell apart.
+ DEPENDENCY_ADDRESS_COLLISION = "dependency_address_collision"
+ # A fetched package holds a file whose name is not UTF-8 text.
+ FILE_NAME_NOT_UTF8 = "file_name_not_utf8"
+
+
+class RequestMethodError(PipelexError):
+ """A method the request carries, or names by address, that the runner refuses to read as a method.
+
+ Its code defaults to ``method.package_invalid``, a tree breaking a rule of the method's package, whose ``reason``
+ and ``path`` or ``limit`` the raise site gives. The raise site chooses ``method.syntax`` for a bundle that is not
+ text, ``method.resource_missing`` for a file reference naming no file of the tree, and
+ ``security.input_path_refused`` for a path of the tree that would leave its root, a security refusal. ``file`` names
+ the file of the tree the refusal is about, when there is one.
+ """
+
+ error_code = ErrorCodeSet(
+ default=CoreCode.METHOD_PACKAGE_INVALID,
+ others=(CoreCode.METHOD_SYNTAX, CoreCode.METHOD_RESOURCE_MISSING, CoreCode.SECURITY_INPUT_PATH_REFUSED),
+ )
+
+ def __init__(self, message: str, *, file: str | None = None) -> None:
+ super().__init__(message)
+ self.file = file
+
+ @override
+ def problem_location(self) -> ProblemLocation | None:
+ return make_location(file=self.file)
diff --git a/api/pipelex_api/json_body.py b/api/pipelex_api/json_body.py
index 03d53528d..1cddffce2 100644
--- a/api/pipelex_api/json_body.py
+++ b/api/pipelex_api/json_body.py
@@ -4,16 +4,22 @@
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.
+deeper than `MAX_JSON_NESTING_DEPTH` answers the same 422 `request.malformed` 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 declares a typed body is built with `route_class=JsonBodyRoute`, which checks the body and parses it
+ before FastAPI validates it, and `tests/unit/test_json_body.py` fails when a body-declaring route of the app is not
+ one. FastAPI's own parse turns any failure but a `JSONDecodeError` into a bare 400, which the error handlers could
+ only read as a fault of the server; parsing it here first answers each one as the caller's `request.malformed`.
- A route that reads its raw body, as the run routes do, parses it with `decode_json_body`.
+
+Both doors refuse a body in the same words: one nested too deeply (`too_deeply_nested`), one whose bytes do not decode
+(`not_utf8`), one that is not JSON (`not_json`), and one holding an integer longer than Python reads from a string
+(`integer_too_long`, past `sys.get_int_max_str_digits()`), each a 422 `request.malformed`.
"""
+import email.message
import json
import re
from collections.abc import Callable, Coroutine
@@ -22,12 +28,15 @@ from operator import mul
from typing import Any
from fastapi import Request, Response, params
+from fastapi.datastructures import DefaultPlaceholder
from fastapi.routing import APIRoute
+from mthds.protocol.problem.registry import CoreCode, RequestMalformedReason
+from starlette.types import Receive, Scope
from typing_extensions import override
-from pipelex_api.error_types import ErrorType
-from pipelex_api.errors import raise_validation_error
+from pipelex_api.exceptions import RunnerRequestError
from pipelex_api.limits import MAX_JSON_NESTING_DEPTH
+from pipelex_api.run_extras_binding import bind_run_extras
# The two escape sequences that can hide a quote. Once they are gone, every quote left delimits a string.
_ESCAPED_BACKSLASH = b"\\\\"
@@ -128,44 +137,111 @@ def json_nesting_exceeds(body: bytes, *, max_depth: int) -> bool:
return False
+# The reason a body nested past the limit is malformed. The code's reasons name no nesting depth, and its reason takes
+# any string beside them, so the runner names this one itself: no size limit of the registry counts levels.
+TOO_DEEPLY_NESTED_REASON = "too_deeply_nested"
+
+# The reason a body holding an integer literal longer than Python converts from a string is malformed: JSON sets no bound
+# on a number's digits, the parser refuses past `sys.get_int_max_str_digits()`, and none of the code's reasons names it.
+INTEGER_TOO_LONG_REASON = "integer_too_long"
+
+
def ensure_json_nesting_within_limit(body: bytes) -> None:
- """Refuse a request body nested deeper than `MAX_JSON_NESTING_DEPTH` with a 422 `InvalidJSON`."""
+ """Refuse a request body nested deeper than `MAX_JSON_NESTING_DEPTH` with a 422 `request.malformed`."""
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,
- )
+ msg = f"Request body is nested too deeply: its JSON arrays and objects may nest at most {MAX_JSON_NESTING_DEPTH} levels"
+ raise RunnerRequestError(msg).with_error_code(CoreCode.REQUEST_MALFORMED).with_params(reason=TOO_DEEPLY_NESTED_REASON)
+
+
+def _malformed(*, message: str, reason: str) -> RunnerRequestError:
+ return RunnerRequestError(message).with_error_code(CoreCode.REQUEST_MALFORMED).with_params(reason=reason)
+
+
+def _loads_json_text(text: str) -> Any:
+ """Parse a decoded body as JSON, refusing it with a 422 `request.malformed` naming why it cannot be.
+
+ - `json.JSONDecodeError`: the text is not JSON;
+ - any other `ValueError`, which `json.loads` given a string raises only for an integer literal longer than
+ `sys.get_int_max_str_digits()`: the integer is too long to read;
+ - `RecursionError`: the depth check leaves the parser nothing deep enough to raise it, so this only stands as a
+ second line of defence.
+ """
+ try:
+ return json.loads(text)
+ except (json.JSONDecodeError, RecursionError) as exc:
+ msg = f"Request body is not valid JSON: {exc!s}"
+ raise _malformed(message=msg, reason=RequestMalformedReason.NOT_JSON) from exc
+ except ValueError as exc:
+ msg = f"Request body holds an integer too long to read: {exc!s}"
+ raise _malformed(message=msg, reason=INTEGER_TOO_LONG_REASON) from exc
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.
+ """Parse a raw request body as plain JSON, refusing it with a 422 `request.malformed` 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.
+ mistakes, never a sanitized 500: a body nested deeper than `MAX_JSON_NESTING_DEPTH`, checked before parsing;
+ bytes that are not valid UTF-8; and the parse's own refusals (`_loads_json_text`).
"""
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,
- )
+ text = body.decode("utf-8")
+ except UnicodeDecodeError as exc:
+ msg = f"Request body is not valid UTF-8: {exc!s}"
+ raise _malformed(message=msg, reason=RequestMalformedReason.NOT_UTF8) from exc
+ return _loads_json_text(text)
+
+
+def parse_typed_json_body(body: bytes) -> Any:
+ """Parse a typed route's body as FastAPI would, refusing what FastAPI could only answer with a bare 400.
+
+ The bytes are decoded the way `json.loads` decodes bytes, which FastAPI hands them to: in the UTF-8, UTF-16 or
+ UTF-32 the body's first bytes spell, a BOM dropped. A body that does not decode is `not_utf8`, the encoding JSON
+ exchanged between systems must use; the parse's own refusals are `_loads_json_text`'s.
+ """
+ try:
+ text = body.decode(json.detect_encoding(body), "surrogatepass")
+ except UnicodeDecodeError as exc:
+ msg = f"Request body does not decode as JSON text: {exc!s}"
+ raise _malformed(message=msg, reason=RequestMalformedReason.NOT_UTF8) from exc
+ return _loads_json_text(text)
+
+
+class _ParsedJsonRequest(Request):
+ """A request whose body was parsed before FastAPI asked for it, so FastAPI reads that value rather than parse again."""
+
+ def __init__(self, scope: Scope, receive: Receive) -> None:
+ super().__init__(scope, receive)
+ self._parsed_body: Any = None
+ self._is_body_parsed = False
+
+ def hold_parsed_body(self, parsed: Any) -> None:
+ self._parsed_body = parsed
+ self._is_body_parsed = True
+
+ @override
+ async def json(self) -> Any:
+ if self._is_body_parsed:
+ return self._parsed_body
+ return await super().json()
class JsonBodyRoute(APIRoute):
- """An `APIRoute` that checks a declared JSON body's nesting depth before FastAPI parses it.
+ """An `APIRoute` that checks and parses a declared JSON body before FastAPI validates 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`.
+ bare 400, an `HTTPException` the error handlers cannot tell from a fault of the server: bytes that do not decode,
+ an integer past Python's digit limit, a parser recursing out of stack. This route reads the body, checks its nesting
+ depth and parses it in front of FastAPI's own handler, so each of those is the caller's 422 `request.malformed`
+ reaching the API's exception handlers like any other `PipelexError`. The handler receives a request built from the
+ same connection that holds the body and its parsed value, so FastAPI neither reads nor parses the body again. 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`.
+
+ The body is parsed only where FastAPI would parse it, a body with bytes whose content type is JSON (`_reads_as_json`):
+ FastAPI hands any other body to the model as raw bytes, which the model refuses field by field, and so does this route.
+ A parsed body's `analytics_groups` are bound on the request before FastAPI validates any field
+ (`pipelex_api.run_extras_binding`), so the security event of a refusal of the request names whose request it was.
"""
@override
@@ -174,9 +250,52 @@ class JsonBodyRoute(APIRoute):
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
+ is_strict = holds_content_type_strictly(self)
+
+ async def parsing_handler(request: Request) -> Response:
+ parsed_request = _ParsedJsonRequest(request.scope, request.receive)
+ body = await parsed_request.body()
+ ensure_json_nesting_within_limit(body)
+ if body and _reads_as_json(content_type=parsed_request.headers.get("content-type"), is_strict=is_strict):
+ parsed_body = parse_typed_json_body(body)
+ # Before FastAPI validates a field, so a refusal of this request names whose request it was.
+ bind_run_extras(request=parsed_request, body=parsed_body)
+ parsed_request.hold_parsed_body(parsed_body)
+ return await handler(parsed_request)
+
+ return parsing_handler
- async def bounded_handler(request: Request) -> Response:
- ensure_json_nesting_within_limit(await request.body())
- return await handler(request)
- return bounded_handler
+# FastAPI 0.132.0 added a route's `strict_content_type`, which defaults to `True`. The releases before it, which the
+# dependency floor still admits, have no such attribute and parse a body that declares no content type as JSON, as a
+# route that does not hold to its content type does: this is the value they behave by.
+_STRICT_CONTENT_TYPE_BEFORE_FASTAPI_0_132 = False
+
+
+def holds_content_type_strictly(route: APIRoute) -> bool:
+ """Whether FastAPI refuses to parse a body that declares no content type as JSON on this route.
+
+ Read from the route's `strict_content_type`, the setting FastAPI's own parse reads, a default it was given unwrapped
+ to its value. A FastAPI release older than 0.132.0 has no such setting and always parses that body as JSON, so a
+ route of one reads as not strict.
+ """
+ strict_content_type = getattr(route, "strict_content_type", _STRICT_CONTENT_TYPE_BEFORE_FASTAPI_0_132)
+ if isinstance(strict_content_type, DefaultPlaceholder):
+ return bool(strict_content_type.value)
+ return bool(strict_content_type)
+
+
+def _reads_as_json(*, content_type: str | None, is_strict: bool) -> bool:
+ """Whether FastAPI parses a typed body of this content type as JSON, by its own rule.
+
+ A JSON media type, `application/json` or `application/<anything>+json`, is parsed; a body that declares no content
+ type is parsed only on a route that does not hold to its content type strictly; any other body is not.
+ """
+ if not content_type:
+ return not is_strict
+ message = email.message.Message()
+ message["content-type"] = content_type
+ if message.get_content_maintype() != "application":
+ return False
+ subtype = message.get_content_subtype()
+ return subtype == "json" or subtype.endswith("+json")
diff --git a/api/pipelex_api/limits.py b/api/pipelex_api/limits.py
index 9acf0e0f7..aa0fd9694 100644
--- a/api/pipelex_api/limits.py
+++ b/api/pipelex_api/limits.py
@@ -71,3 +71,19 @@ BLOB_UPLOAD_URL_TTL_SECONDS = get_positive_int_env(env_var="BLOB_UPLOAD_URL_TTL_
MAX_METHOD_CACHE_CLONES = get_positive_int_env(env_var="MAX_METHOD_CACHE_CLONES", default=DEFAULT_MAX_METHOD_CACHE_CLONES)
MAX_METHOD_CACHE_TOTAL_BYTES = get_positive_int_env(env_var="MAX_METHOD_CACHE_TOTAL_KIB", default=DEFAULT_MAX_METHOD_CACHE_TOTAL_KIB) * 1024
MAX_METHOD_CACHE_AGE_SECONDS = get_positive_int_env(env_var="MAX_METHOD_CACHE_AGE_HOURS", default=DEFAULT_MAX_METHOD_CACHE_AGE_HOURS) * 3600
+
+# Standard base64 writes three bytes as four characters, padding the last group with `=`.
+_BASE64_GROUP_CHARS = 4
+_BASE64_GROUP_BYTES = 3
+
+
+def base64_decoded_size(*, encoded: str) -> int:
+ """The number of bytes a standard base64 value decodes to, read off its length without decoding it.
+
+ The byte limits are checked against it before a value is decoded, so an oversized value is refused before it is
+ expanded into memory, and the refusal states the limit and the size in bytes, as `request.too_large` does: every
+ four characters carry three bytes, less one per `=` of padding. The size is exact for a value that is valid base64;
+ any other value is refused as malformed once it is decoded.
+ """
+ padding = 2 if encoded.endswith("==") else 1 if encoded.endswith("=") else 0
+ return max(0, len(encoded) * _BASE64_GROUP_BYTES // _BASE64_GROUP_CHARS - padding)
diff --git a/api/pipelex_api/main.py b/api/pipelex_api/main.py
index c7ac2c7cb..3bf33eaa0 100644
--- a/api/pipelex_api/main.py
+++ b/api/pipelex_api/main.py
@@ -26,7 +26,7 @@ from pydantic import BaseModel, Field
from starlette.middleware.base import BaseHTTPMiddleware
from pipelex_api.api_config import get_api_config, resolve_boot_orchestrator
-from pipelex_api.exception_handlers import register_exception_handlers
+from pipelex_api.exception_handlers import AnsweredErrorBarrier, register_exception_handlers
from pipelex_api.middleware import RequestIdMiddleware, request_body_size_middleware
from pipelex_api.openapi_schema import PipelexFastAPI
from pipelex_api.routes import router as api_router
@@ -215,5 +215,8 @@ register_exception_handlers(fastapi_app, http_error_mappers=HTTP_ERROR_MAPPERS)
# ServerErrorMiddleware, which `add_middleware` could only ever nest inside.
# This is what makes it genuinely outermost: the request-id contextvars are
# bound, and `X-Request-ID` is echoed, on every response — the catch-all 500
-# included. `app` is the ASGI entrypoint (uvicorn loads `pipelex_api.main:app`).
-app = RequestIdMiddleware(fastapi_app)
+# included. Between the two, AnsweredErrorBarrier stops the exception
+# ServerErrorMiddleware raises again after the catch-all answered it, which the
+# server would otherwise log with its traceback, the exception's text included.
+# `app` is the ASGI entrypoint (uvicorn loads `pipelex_api.main:app`).
+app = RequestIdMiddleware(AnsweredErrorBarrier(fastapi_app))
diff --git a/api/pipelex_api/method_source.py b/api/pipelex_api/method_source.py
index 85aa2b929..6382a00d7 100644
--- a/api/pipelex_api/method_source.py
+++ b/api/pipelex_api/method_source.py
@@ -26,7 +26,7 @@ same path, the files a step reads, such as a `PipeDocGen` template, included.
The security gate (packaging invariant 7 — execution locus decides) is the request tree's
(`pipelex_api.method_tree_request.ensure_python_allowed`): on a deployment that is not sandbox-hosted, a package
-carrying any `.py` is refused with a 403 `CustomCodeRequiresSandbox`; on a sandbox-hosted one, PipeFunc `.py` is
+carrying any `.py` is refused with a 501 `pipelex.deployment.custom_code_requires_sandbox`; on a sandbox-hosted one, PipeFunc `.py` is
acceptable but a package declaring `StructuredContent` subclasses is refused (`MethodStructuresRefusedError`, a 422
`pipelex.deployment.python_structures_refused`).
@@ -52,6 +52,7 @@ from pipelex.methods.exceptions import MethodFetchError
from pipelex.methods.fetching import FetchedMethodPackage, MethodProvenance
from pipelex.methods.method_ref import parse_method_ref
+from pipelex_api.exceptions import MethodPackageReason
from pipelex_api.method_cache import get_method_clone_cache
from pipelex_api.method_tree_request import (
RequestMethod,
@@ -143,9 +144,7 @@ def _package_tree_entries(*, package: FetchedMethodPackage) -> list[_GitTreeEntr
except UnicodeDecodeError as exc:
msg = f"Method package '{package.full_address}' holds a file whose name is not UTF-8 text, which no method tree can hold."
raise (
- MethodFetchError(msg)
- .with_error_code(CoreCode.METHOD_PACKAGE_INVALID)
- .with_params(reason="a file's name is not UTF-8 text, which no method tree can hold")
+ MethodFetchError(msg).with_error_code(CoreCode.METHOD_PACKAGE_INVALID).with_params(reason=MethodPackageReason.FILE_NAME_NOT_UTF8)
) from exc
if not path.startswith(prefix):
continue
@@ -245,8 +244,9 @@ def _read_package_method(*, package: FetchedMethodPackage) -> RequestMethod:
continue
vendored_label = f"The package '.mthds/methods/{vendored_dir.name}/' of method package '{package.full_address}'"
dependency_tree = _read_listed_tree(root=vendored_dir, package_address=vendored_label, label=vendored_label)
- address = dependency_address_of(tree=dependency_tree, fallback_name=vendored_dir.name, label=vendored_label)
- add_dependency(dependencies=dependencies, address=address, tree=dependency_tree, label=vendored_label)
+ root = f".mthds/methods/{vendored_dir.name}/"
+ address = dependency_address_of(tree=dependency_tree, fallback_name=vendored_dir.name, label=vendored_label, root=root)
+ add_dependency(dependencies=dependencies, address=address, tree=dependency_tree, label=vendored_label, root=root)
request_method = RequestMethod(tree=tree, dependencies=dependencies)
ensure_method_within_limits(request_method=request_method, label=label)
return request_method
@@ -259,8 +259,7 @@ def _fetched_package(method_ref: str) -> Generator[FetchedMethodPackage, None, N
"""Parse the reference and fetch its package through the SHA-keyed clone cache, its clone pinned in the block.
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`).
+ global handler as the `problem+json` document of its code, with the status its code declares.
"""
ref = parse_method_ref(method_ref)
with get_method_clone_cache().pinned_package(ref=ref) as package:
@@ -288,7 +287,7 @@ def fetched_method(method_ref: str) -> FetchedMethod:
MethodRefError subclasses: parse, fetch, location and bounds failures, each rendered as `problem+json` by the
global handler.
MethodTreeLoadError: The standard refused the package's tree (a 422 naming the package by its address).
- ApiError: A tree past this runner's limits, or a shipped package without a manifest (422s).
+ RequestMethodError: A tree past this runner's limits, or a shipped package without a manifest (422s).
"""
with _fetched_package(method_ref) as package:
request_method = _read_package_method(package=package)
diff --git a/api/pipelex_api/method_tree_request.py b/api/pipelex_api/method_tree_request.py
index 57a16fce6..3e525fc58 100644
--- a/api/pipelex_api/method_tree_request.py
+++ b/api/pipelex_api/method_tree_request.py
@@ -14,16 +14,18 @@ What this module does, in order:
1. Every limit of this runner on a tree (`MAX_METHOD_TREE_FILES`, `MAX_METHOD_TREE_TOTAL_KIB`,
`MAX_METHOD_TREE_FILE_KIB`) is checked on the sizes the entries state, before any blob is read: a 422
- `MethodTreeTooLarge` naming the limit.
+ `method.package_invalid` whose `reason` names the limit and whose `limit` gives it.
2. The bytes of every hash entry are read from the runner's blob store, under the caller's scope, at once.
-3. The map is read (`read_file_map`): a refusal of the standard is a 422 `InvalidMethodFiles` whose `tree_refusal`
- member carries the refusal's code and the paths it names, and hash entries the store does not hold at their stated
- size are one 422 `MissingBlobs` whose `missing_blobs` member lists every such hash.
+3. The map is read (`read_file_map`): a refusal of the standard is a 422 `method.package_invalid` whose `reason` is the
+ refusal's code and whose `path` is the first path it names, except a key leaving the tree, which is the security
+ refusal `security.input_path_refused`, and an entry of the wrong shape, which is `request.invalid`; hash entries the
+ store does not hold at their stated size are one 422 `request.blobs_missing` whose `missing_blobs` parameter lists
+ every such hash.
4. The files `resources` sends join the tree (`with_resources`), the same bytes under a path the tree holds or a new
- file at a tree path; other bytes under a path the tree holds are a 422 `InvalidResourcePath` naming it.
-5. Python is honored only on a sandbox-hosted deployment: a method holding a `.py` file is refused with a 403
- `CustomCodeRequiresSandbox` before anything is written, and on a sandbox-hosted deployment a tree declaring a Python
- structure class is refused (`MethodStructuresRefusedError`, a 422).
+ file at a tree path; other bytes under a path the tree holds are a 422 `request.invalid` naming `resources`.
+5. Python is honored only on a sandbox-hosted deployment: a method holding a `.py` file is refused with a 501
+ `pipelex.deployment.custom_code_requires_sandbox` before anything is written, and on a sandbox-hosted deployment a
+ tree declaring a Python structure class is refused (`MethodStructuresRefusedError`, a 422).
6. Each tree read in full is recorded in the blob store, its files then its listing, so the next request can send it
by hash, and `POST /v1/blobs/missing` answers its digest with one lookup.
7. The trees are written out into a temporary directory and held as written (`pipelex.libraries.written_trees`), so
@@ -49,10 +51,10 @@ from mthds.method_tree.vocabulary import TreeRefusalCode
from mthds.package.exceptions import ManifestError
from mthds.package.manifest.parser import parse_methods_toml
from mthds.package.manifest.schema import MethodsManifest
-from mthds.protocol.problem.registry import CoreCode
+from mthds.protocol.problem.registry import CoreCode, MethodResourceMissingReason, RequestMalformedReason
from pipelex.cli.installed_methods import PROVENANCE_FILENAME
from pipelex.config import is_pipe_func_sandbox_hosted
-from pipelex.core.bundle_resources.bundle_resource import root_escape_refusal
+from pipelex.core.bundle_resources.bundle_resource import SUBMITTED_FILES_FIELD, root_escape_of
from pipelex.libraries.written_trees import WRITTEN_METHOD_TREES, write_method_tree
from pipelex.methods.structures_check import ensure_no_structured_content_in_library_sources, ensure_no_structured_content_python
from pipelex.mthds_parsing.parser import MthdsParser
@@ -63,8 +65,7 @@ from pipelex.pipeline.validate_bundle_translation import translate_to_validate_b
from pipelex_api.blob_store import RunnerBlobStore
from pipelex_api.bundle import decode_bundle_archive
from pipelex_api.bundle_resources import refuse_two_files_under_one_path
-from pipelex_api.error_types import ErrorType
-from pipelex_api.errors import ApiSecurityRefusal, raise_forbidden, raise_validation_error, raise_validation_problem
+from pipelex_api.exceptions import CustomCodeOrigin, CustomCodeRequiresSandboxError, MethodPackageReason, RequestMethodError, RunnerRequestError
from pipelex_api.limits import (
MAX_METHOD_DEPENDENCIES,
MAX_METHOD_REQUEST_TOTAL_BYTES,
@@ -75,6 +76,7 @@ from pipelex_api.limits import (
FILES_FIELD = "files"
DEPENDENCIES_FIELD = "dependencies"
+BUNDLE_FIELD = "bundle_b64"
PYTHON_SUFFIX = ".py"
FILES_LABEL = "The `files` map"
ARCHIVE_LABEL = "The `bundle_b64` archive"
@@ -86,6 +88,8 @@ REQUEST_METHOD_LABEL = "sent in the request"
VENDORED_METHODS_PREFIX = ".mthds/methods/"
# A file the membership rule judges a directory by, which stands in for any file inside a directory being judged.
_ANY_FILE_NAME = "file"
+# The `finding` of a `method.syntax` refusing a bundle that is not text.
+NOT_UTF8_FINDING = "the bundle is not UTF-8 text"
class RequestTree(NamedTuple):
@@ -184,15 +188,16 @@ def tree_documents_of(*, body: bytes) -> TreeDocuments:
tree. It is decoded as `json.loads` decodes bytes, UTF-8, UTF-16 or UTF-32, as the route's own parser accepted it.
A member given twice in the body is read as JSON reads it, the last one counting, and a `null` member is absent.
- Raises (as problem documents): a 422 `InvalidJSON` for a body that does not decode or parse, and a 422
- `InvalidMethodFiles` for `dependencies` that is not an object, or that gives one address twice.
+ Raises (as problem documents): a 422 `request.malformed` for a body that does not decode or parse, and a 422
+ `request.invalid` naming `dependencies` when it is not an object, or gives one address twice.
"""
try:
parsed = _parse_keeping_pairs(body.decode(json.detect_encoding(body), "surrogatepass"))
except (UnicodeDecodeError, ValueError) as exc:
# The route's parser read these bytes already, so this is a second line of defence: `JSONDecodeError` and
# an integer longer than Python converts are both a `ValueError`.
- raise_validation_error(message=f"Request body is not valid JSON: {exc!s}", error_type=ErrorType.INVALID_JSON)
+ msg = f"Request body is not valid JSON: {exc!s}"
+ raise RunnerRequestError(msg).with_error_code(CoreCode.REQUEST_MALFORMED).with_params(reason=RequestMalformedReason.NOT_JSON) from exc
if not isinstance(parsed, _JsonObject):
return TreeDocuments(files=None, dependencies=None)
members = dict(parsed.pairs)
@@ -203,15 +208,12 @@ def tree_documents_of(*, body: bytes) -> TreeDocuments:
return TreeDocuments(files=files_document, dependencies=None)
if not isinstance(dependencies_member, _JsonObject):
msg = "`dependencies` must be a JSON object mapping each dependency's address to its map of file entries."
- raise_validation_error(message=msg, error_type=ErrorType.INVALID_METHOD_FILES)
+ raise RunnerRequestError(msg, field=DEPENDENCIES_FIELD)
dependency_documents: dict[str, str] = {}
for address, dependency_member in dependencies_member.pairs:
if address in dependency_documents:
- raise_validation_problem(
- message=f"`dependencies` gives the address '{wire_name(address)}' twice.",
- error_type=ErrorType.INVALID_METHOD_FILES,
- members={"tree_refusal": {"code": TreeRefusalCode.DUPLICATE_KEY, "names": [wire_name(address)]}},
- )
+ msg = f"`dependencies` gives the address '{wire_name(address)}' twice."
+ raise RunnerRequestError(msg, field=DEPENDENCIES_FIELD)
dependency_documents[address] = _serialized(dependency_member)
return TreeDocuments(files=files_document, dependencies=dependency_documents)
@@ -278,23 +280,25 @@ def wire_name(name: str) -> str:
def ensure_within_tree_limits(*, file_count: int, total_bytes: int, largest_path: str | None, largest_bytes: int, label: str) -> None:
- """Refuse a tree past one of this runner's limits, naming the limit, with a 422 `MethodTreeTooLarge`."""
+ """Refuse a tree past one of this runner's limits with a 422 `method.package_invalid`, its `reason` naming the limit."""
if file_count > MAX_METHOD_TREE_FILES:
msg = f"{label} holds {file_count} files, past this runner's limit of {MAX_METHOD_TREE_FILES} files in a method tree."
- raise_validation_error(message=msg, error_type=ErrorType.METHOD_TREE_TOO_LARGE)
+ raise RequestMethodError(msg).with_params(reason=MethodPackageReason.TOO_MANY_FILES, limit=MAX_METHOD_TREE_FILES)
if largest_path is not None and largest_bytes > MAX_METHOD_TREE_FILE_BYTES:
msg = (
f"{label} holds the file '{wire_name(largest_path)}' of {largest_bytes} bytes, past this runner's limit of "
f"{MAX_METHOD_TREE_FILE_BYTES // 1024} KiB for one file of a method tree."
)
- raise_validation_error(message=msg, error_type=ErrorType.METHOD_TREE_TOO_LARGE)
+ raise RequestMethodError(msg, file=wire_name(largest_path)).with_params(
+ reason=MethodPackageReason.FILE_TOO_LARGE, path=wire_name(largest_path), limit=MAX_METHOD_TREE_FILE_BYTES
+ )
if total_bytes > MAX_METHOD_TREE_TOTAL_BYTES:
msg = f"{label} holds {total_bytes} bytes, past this runner's limit of {MAX_METHOD_TREE_TOTAL_BYTES // 1024} KiB for a method tree."
- raise_validation_error(message=msg, error_type=ErrorType.METHOD_TREE_TOO_LARGE)
+ raise RequestMethodError(msg).with_params(reason=MethodPackageReason.TREE_TOO_LARGE, limit=MAX_METHOD_TREE_TOTAL_BYTES)
def ensure_tree_within_limits(*, tree: RequestTree, label: str) -> None:
- """Refuse a tree read in full that passes one of this runner's limits, with a 422 `MethodTreeTooLarge`."""
+ """Refuse a tree read in full that passes one of this runner's limits, with a 422 `method.package_invalid`."""
largest_path: str | None = None
largest_bytes = 0
for tree_path, data in tree.contents.items():
@@ -310,24 +314,24 @@ def ensure_tree_within_limits(*, tree: RequestTree, label: str) -> None:
def ensure_trees_within_request_limits(*, dependency_count: int, total_bytes: int, label: str) -> None:
- """Refuse a method whose trees together pass this runner's limits, with a 422 `MethodTreeTooLarge`.
+ """Refuse a method whose trees together pass this runner's limits, with a 422 `method.package_invalid`.
Each tree is held to the tree limits on its own; these bound what one request carries in all, its method's tree and
every dependency tree beside it, so the memory and the disk a request takes do not grow with its dependencies.
"""
if dependency_count > MAX_METHOD_DEPENDENCIES:
msg = f"{label} carries {dependency_count} dependencies, past this runner's limit of {MAX_METHOD_DEPENDENCIES} dependency trees."
- raise_validation_error(message=msg, error_type=ErrorType.METHOD_TREE_TOO_LARGE)
+ raise RequestMethodError(msg).with_params(reason=MethodPackageReason.TOO_MANY_DEPENDENCIES, limit=MAX_METHOD_DEPENDENCIES)
if total_bytes > MAX_METHOD_REQUEST_TOTAL_BYTES:
msg = (
f"{label} holds {total_bytes} bytes across its tree and its dependency trees, past this runner's limit of "
f"{MAX_METHOD_REQUEST_TOTAL_BYTES // 1024} KiB for a method and its dependencies."
)
- raise_validation_error(message=msg, error_type=ErrorType.METHOD_TREE_TOO_LARGE)
+ raise RequestMethodError(msg).with_params(reason=MethodPackageReason.METHOD_TOO_LARGE, limit=MAX_METHOD_REQUEST_TOTAL_BYTES)
def ensure_method_within_limits(*, request_method: "RequestMethod", label: str) -> None:
- """Refuse a method read in full whose trees together pass this runner's limits, with a 422 `MethodTreeTooLarge`."""
+ """Refuse a method read in full whose trees together pass this runner's limits, with a 422 `method.package_invalid`."""
trees = [request_method.tree, *request_method.dependencies.values()]
ensure_trees_within_request_limits(
dependency_count=len(request_method.dependencies),
@@ -336,66 +340,62 @@ def ensure_method_within_limits(*, request_method: "RequestMethod", label: str)
)
-def _refuse_map(*, refusal_error: MethodTreeRefusedError, label: str) -> NoReturn:
- """Answer the standard's refusal of a map: the hashes to upload, or the code and the paths it names."""
+def _refuse_map(*, refusal_error: MethodTreeRefusedError, label: str, field: str) -> NoReturn:
+ """Answer the standard's refusal of a map with the code it is, its facts as the code's parameters.
+
+ Hashes this runner does not hold are `request.blobs_missing`, listing every one to upload. A key that is not a tree
+ path and tries to leave the tree is the security refusal `security.input_path_refused`, by the runtime's one rule for
+ a caller's path that leaves its root (`root_escape_of`): absolute, naming a drive or a network share, or climbing
+ with a `..` segment, read with either separator, whether the caller sent it as a key of `files` or as a member of
+ `bundle_b64`, as it is under `resources`. An entry of the wrong shape is the request's own, `request.invalid` naming
+ the field the map rides. A file reference that names no file of the tree, or that leaves it, is
+ `method.resource_missing`. Every other refusal is a rule of the method's package the tree breaks,
+ `method.package_invalid`, whose `reason` is the standard's refusal code and whose `path` is the first path it names.
+
+ Args:
+ refusal_error: The standard's refusal.
+ label: How the refusal names the map, such as "The `files` map".
+ field: The request field the map rides, such as `files`.
+ """
refusal = refusal_error.refusal
+ names = [wire_name(name) for name in refusal.names]
+ first_name = names[0] if names else None
+ msg = f"{label} is not a method tree. {refusal_error.message}"
match refusal.code:
case TreeRefusalCode.MISSING_BLOB:
msg = (
f"{label} names, by hash, bytes this runner does not hold at their stated size: {', '.join(refusal.names)}. "
"Upload them (POST /v1/blobs/missing, then PUT /v1/blobs/{sha256}) and send the request again."
)
- raise_validation_problem(message=msg, error_type=ErrorType.MISSING_BLOBS, members={"missing_blobs": list(refusal.names)})
- case (
- TreeRefusalCode.SYMBOLIC_LINK
- | TreeRefusalCode.SPECIAL_FILE
- | TreeRefusalCode.INVALID_TREE_PATH
- | TreeRefusalCode.NORMALIZATION_COLLISION
- | TreeRefusalCode.PATH_COLLISION
- | TreeRefusalCode.EMPTY_TREE
- | TreeRefusalCode.LONE_FILE_EXCLUDED
- | TreeRefusalCode.GITIGNORE_NOT_UTF8
- | TreeRefusalCode.DUPLICATE_KEY
- | TreeRefusalCode.EXCLUDED_NAME
- | TreeRefusalCode.MALFORMED_ENTRY
- | TreeRefusalCode.REFERENCE_INVALID
- | TreeRefusalCode.REFERENCE_LEAVES_TREE
- | TreeRefusalCode.REFERENCE_NOT_A_TREE_PATH
- | TreeRefusalCode.REFERENCE_NOT_IN_TREE
- | TreeRefusalCode.REFERENCE_IN_ONE_FILE_TREE
- | TreeRefusalCode.FUNCTION_NAME_WITHOUT_MODULE
- | TreeRefusalCode.FUNCTION_NAME_INVALID_SEGMENT
- | TreeRefusalCode.MODULE_NOT_IN_TREE
- | TreeRefusalCode.MODULE_AMBIGUOUS
- ):
- raise_validation_problem(
- message=f"{label} is not a method tree. {refusal_error.message}",
- error_type=ErrorType.INVALID_METHOD_FILES,
- members={"tree_refusal": {"code": refusal.code, "names": [wire_name(name) for name in refusal.names]}},
- security_refusal=_tree_path_security_refusal(refusal_error=refusal_error),
- )
-
-
-def _tree_path_security_refusal(*, refusal_error: MethodTreeRefusedError) -> ApiSecurityRefusal | None:
- """The security refusal a tree refusal is, when a path it names tries to leave the tree, else `None`.
-
- The standard's reader refuses a key that is not a tree path without saying why, so the runtime's one rule for a
- caller's path that leaves its root decides (`root_escape_refusal`): a path that is absolute, names a drive or a
- network share, or climbs with a `..` segment, read with either separator, is a traversal,
- `security.input_path_refused`, whether the caller sent it as a key of `files` or as a member of `bundle_b64`, which
- the same reader judges, and as it is under `resources`. Every other path the reader refuses (an empty segment, a
- backslash, a colon, a path not in NFC) is the shape of how the caller packed the method, a refusal of the request
- and no security event.
- """
- refusal = refusal_error.refusal
- match refusal.code:
+ raise (
+ RunnerRequestError(msg, field=field).with_error_code(CoreCode.REQUEST_BLOBS_MISSING).with_params(missing_blobs=list(refusal.names))
+ ) from refusal_error
case TreeRefusalCode.INVALID_TREE_PATH:
- if any(root_escape_refusal(path=name) is not None for name in refusal.names):
- return ApiSecurityRefusal(code=CoreCode.SECURITY_INPUT_PATH_REFUSED, error_type=type(refusal_error).__name__)
- return None
+ for name in refusal.names:
+ escape = root_escape_of(path=name)
+ if escape is not None:
+ raise (
+ RequestMethodError(msg, file=wire_name(name))
+ .with_error_code(CoreCode.SECURITY_INPUT_PATH_REFUSED)
+ .with_params(rule=escape.rule)
+ ) from refusal_error
+ raise RequestMethodError(msg, file=first_name).with_params(reason=refusal.code, path=first_name) from refusal_error
+ case TreeRefusalCode.MALFORMED_ENTRY:
+ raise RunnerRequestError(msg, field=field) from refusal_error
+ case TreeRefusalCode.REFERENCE_NOT_IN_TREE:
+ raise (
+ RequestMethodError(msg, file=first_name)
+ .with_error_code(CoreCode.METHOD_RESOURCE_MISSING)
+ .with_params(file=first_name or "", reason=MethodResourceMissingReason.NOT_IN_TREE)
+ ) from refusal_error
+ case TreeRefusalCode.REFERENCE_LEAVES_TREE:
+ raise (
+ RequestMethodError(msg, file=first_name)
+ .with_error_code(CoreCode.METHOD_RESOURCE_MISSING)
+ .with_params(file=first_name or "", reason=MethodResourceMissingReason.LEAVES_TREE)
+ ) from refusal_error
case (
- TreeRefusalCode.MISSING_BLOB
- | TreeRefusalCode.SYMBOLIC_LINK
+ TreeRefusalCode.SYMBOLIC_LINK
| TreeRefusalCode.SPECIAL_FILE
| TreeRefusalCode.NORMALIZATION_COLLISION
| TreeRefusalCode.PATH_COLLISION
@@ -404,21 +404,18 @@ def _tree_path_security_refusal(*, refusal_error: MethodTreeRefusedError) -> Api
| TreeRefusalCode.GITIGNORE_NOT_UTF8
| TreeRefusalCode.DUPLICATE_KEY
| TreeRefusalCode.EXCLUDED_NAME
- | TreeRefusalCode.MALFORMED_ENTRY
| TreeRefusalCode.REFERENCE_INVALID
- | TreeRefusalCode.REFERENCE_LEAVES_TREE
| TreeRefusalCode.REFERENCE_NOT_A_TREE_PATH
- | TreeRefusalCode.REFERENCE_NOT_IN_TREE
| TreeRefusalCode.REFERENCE_IN_ONE_FILE_TREE
| TreeRefusalCode.FUNCTION_NAME_WITHOUT_MODULE
| TreeRefusalCode.FUNCTION_NAME_INVALID_SEGMENT
| TreeRefusalCode.MODULE_NOT_IN_TREE
| TreeRefusalCode.MODULE_AMBIGUOUS
):
- return None
+ raise RequestMethodError(msg, file=first_name).with_params(reason=refusal.code, path=first_name) from refusal_error
-async def _held_blobs(*, blob_store: RunnerBlobStore, stated_sizes: dict[str, set[int]], label: str) -> BlobStore:
+async def _held_blobs(*, blob_store: RunnerBlobStore, stated_sizes: dict[str, set[int]], label: str, field: str) -> BlobStore:
"""The bytes a map's hash entries name that the blob store holds, looked up by size before any is read.
A hash held at another size than one of its entries states is refused, since uploading its bytes again would not
@@ -426,8 +423,8 @@ async def _held_blobs(*, blob_store: RunnerBlobStore, stated_sizes: dict[str, se
census bounded, so reading them reads no more than the census allowed. A hash not held is left out, for the reader
to report among the blobs this runner does not hold.
- Raises (as a problem document): a 422 `BlobMismatch` whose `mismatched_blobs` member lists each hash held at another
- size, with that size.
+ Raises (as a problem document): a 422 `request.invalid` naming the field the map rides; its message, in the operator's
+ diagnostics, lists each hash held at another size, with that size, which no parameter of the code carries.
"""
stored = await blob_store.stored_sizes(sha256s=sorted(stated_sizes))
mismatched = {sha256: size for sha256, size in stored.items() if size is not None and stated_sizes[sha256] != {size}}
@@ -437,24 +434,24 @@ async def _held_blobs(*, blob_store: RunnerBlobStore, stated_sizes: dict[str, se
f"{label} states a size for a hash other than the size of the bytes this runner holds under it: {described}. "
"A hash names one set of bytes, so state the size of those bytes."
)
- raise_validation_problem(
- message=msg,
- error_type=ErrorType.BLOB_MISMATCH,
- members={"mismatched_blobs": [{"sha256": sha256, "held_size": size} for sha256, size in mismatched.items()]},
- )
+ raise RunnerRequestError(msg, field=field)
return await blob_store.read_held(sizes={sha256: size for sha256, size in stored.items() if size is not None})
-async def read_request_tree(*, document: str, blob_store: RunnerBlobStore | None, label: str, census: _MapCensus | None = None) -> RequestTree:
+async def read_request_tree(
+ *, document: str, blob_store: RunnerBlobStore | None, label: str, field: str, census: _MapCensus | None = None
+) -> RequestTree:
"""Read one map of file entries a request carried, its hash entries from the runner's blob store.
Args:
document: The map's JSON text, as the request carried it.
blob_store: The blob store of the caller's scope, or None for a map that names no bytes by hash.
label: How a refusal names the map, such as "The `files` map".
+ field: The request field the map rides, such as `files`, which a refusal of the request names.
census: The map's census when the caller took it already, else taken here.
- Raises (as problem documents): `MethodTreeTooLarge`, `InvalidMethodFiles` and `MissingBlobs`, each a 422.
+ Raises (as problem documents): the refusals of `_refuse_map`, `method.package_invalid` for a tree past a limit, and
+ `request.invalid` for a map the reader cannot take as a source of a tree, each a 422.
"""
if census is None:
census = _census(document=document)
@@ -468,13 +465,14 @@ async def read_request_tree(*, document: str, blob_store: RunnerBlobStore | None
label=label,
)
if census.stated_sizes and blob_store is not None:
- held = await _held_blobs(blob_store=blob_store, stated_sizes=census.stated_sizes, label=label)
+ held = await _held_blobs(blob_store=blob_store, stated_sizes=census.stated_sizes, label=label, field=field)
try:
reading = read_file_map(document, blob_store=held)
except MethodTreeRefusedError as exc:
- _refuse_map(refusal_error=exc, label=label)
+ _refuse_map(refusal_error=exc, label=label, field=field)
except TreeSourceError as exc:
- raise_validation_problem(message=f"{label} is not a method tree. {exc.message}", error_type=ErrorType.INVALID_METHOD_FILES, members={})
+ msg = f"{label} is not a method tree. {exc.message}"
+ raise RunnerRequestError(msg, field=field) from exc
request_tree = RequestTree(tree=reading.tree, contents=reading.contents)
ensure_tree_within_limits(tree=request_tree, label=label)
return request_tree
@@ -486,9 +484,12 @@ def _base64_map_document(*, entries: list[tuple[str, bytes]]) -> str:
return _serialized(_JsonObject(pairs=pairs))
-def manifest_of(*, tree: RequestTree, label: str) -> MethodsManifest | None:
+def manifest_of(*, tree: RequestTree, label: str, root: str) -> MethodsManifest | None:
"""The `METHODS.toml` at a tree's root, parsed, or None when the tree holds none there.
+ `root` is the path the request names the tree's root by, empty for the method's own tree and `<address>/` or
+ `.mthds/methods/<name>/` for a package it ships, so that a refusal's `path` names the manifest as the request does.
+
Raises:
MethodEntryError: The manifest is not UTF-8 text, or not a valid manifest (a 422 in the input domain).
"""
@@ -499,10 +500,18 @@ def manifest_of(*, tree: RequestTree, label: str) -> MethodsManifest | None:
return parse_methods_toml(manifest_bytes.decode("utf-8"))
except UnicodeDecodeError as exc:
msg = f"The {MANIFEST_NAME} of {label} is not UTF-8 text."
- raise MethodEntryError(msg).with_error_code(CoreCode.METHOD_PACKAGE_INVALID) from exc
+ raise (
+ MethodEntryError(msg)
+ .with_error_code(CoreCode.METHOD_PACKAGE_INVALID)
+ .with_params(reason=MethodPackageReason.MANIFEST_INVALID, path=f"{root}{MANIFEST_NAME}")
+ ) from exc
except ManifestError as exc:
msg = f"The {MANIFEST_NAME} of {label} is not a valid manifest: {exc.message}"
- raise MethodEntryError(msg).with_error_code(CoreCode.METHOD_PACKAGE_INVALID) from exc
+ raise (
+ MethodEntryError(msg)
+ .with_error_code(CoreCode.METHOD_PACKAGE_INVALID)
+ .with_params(reason=MethodPackageReason.MANIFEST_INVALID, path=f"{root}{MANIFEST_NAME}")
+ ) from exc
def is_package_dir_name(name: str) -> bool:
@@ -518,22 +527,21 @@ def is_package_dir_name(name: str) -> bool:
return not excluded_name_violation(f"{name}/{_ANY_FILE_NAME}")
-def dependency_address_of(*, tree: RequestTree, fallback_name: str, label: str) -> str:
+def dependency_address_of(*, tree: RequestTree, fallback_name: str, label: str, root: str) -> str:
"""The address a dependency tree's manifest declares, `address/name`, as a reference names the package.
A manifest declaring no name takes `fallback_name`, the name of the directory the tree is written as, which is the
- name the engine's discovery gives such a package; it must then be a name a package's directory can take.
+ name the engine's discovery gives such a package; it must then be a name a package's directory can take. `root` is
+ the path the request names the tree's root by (`manifest_of`).
- Raises (as a 422 `InvalidMethodFiles`): a tree with no valid `METHODS.toml` at its root, or one whose manifest
- declares no name when `fallback_name` cannot name a package's directory.
+ Raises (as a 422 `method.package_invalid`): a tree with no valid `METHODS.toml` at its root (the manifest's own
+ refusal, `MethodEntryError`, when it holds one that cannot be read), or one whose manifest declares no name when
+ `fallback_name` cannot name a package's directory.
"""
- try:
- manifest = manifest_of(tree=tree, label=label)
- except MethodEntryError as exc:
- raise_validation_error(message=exc.message, error_type=ErrorType.INVALID_METHOD_FILES)
+ manifest = manifest_of(tree=tree, label=label, root=root)
if manifest is None:
msg = f"{label} holds no {MANIFEST_NAME} at its root, so no reference could find it as a package."
- raise_validation_error(message=msg, error_type=ErrorType.INVALID_METHOD_FILES)
+ raise RequestMethodError(msg).with_params(reason=MethodPackageReason.MANIFEST_MISSING, path=f"{root}{MANIFEST_NAME}")
if manifest.name is not None:
return f"{manifest.address}/{manifest.name}"
if not is_package_dir_name(fallback_name):
@@ -541,7 +549,7 @@ def dependency_address_of(*, tree: RequestTree, fallback_name: str, label: str)
f"{label} declares no name in its {MANIFEST_NAME}, so it takes the last segment of its address, "
f"'{wire_name(fallback_name)}', which cannot name a package's directory: declare the package's name in its {MANIFEST_NAME}."
)
- raise_validation_error(message=msg, error_type=ErrorType.INVALID_METHOD_FILES)
+ raise RequestMethodError(msg).with_params(reason=MethodPackageReason.PACKAGE_NAME_INVALID, path=f"{root}{MANIFEST_NAME}")
return f"{manifest.address}/{fallback_name}"
@@ -550,11 +558,11 @@ def dependency_dir_name(*, address: str) -> str:
return address.rsplit("/", 1)[-1]
-def add_dependency(*, dependencies: dict[str, RequestTree], address: str, tree: RequestTree, label: str) -> None:
+def add_dependency(*, dependencies: dict[str, RequestTree], address: str, tree: RequestTree, label: str, root: str) -> None:
"""Add a dependency tree under its address, refusing an address a reference could not tell from one already there.
A reference matches a package by its address without regard to case, so two addresses differing only in case are
- one identity too.
+ one identity too. `root` is the path the request names the tree's root by, which a refusal names.
"""
for known in dependencies:
if known.casefold() == address.casefold():
@@ -562,7 +570,7 @@ def add_dependency(*, dependencies: dict[str, RequestTree], address: str, tree:
f"{label} declares the address '{wire_name(address)}', which another dependency of the request declares too: a reference "
"matches a package by its address without regard to case, so it could not tell them apart."
)
- raise_validation_error(message=msg, error_type=ErrorType.INVALID_METHOD_FILES)
+ raise RequestMethodError(msg).with_params(reason=MethodPackageReason.DEPENDENCY_ADDRESS_COLLISION, path=root)
dependencies[address] = tree
@@ -571,13 +579,13 @@ async def read_request_method(*, documents: TreeDocuments, blob_store: RunnerBlo
Each dependency tree's manifest must declare the address it is keyed by.
- Raises (as problem documents): the refusals of `read_request_tree`, and a 422 `InvalidMethodFiles` for
- `dependencies` without `files` or a dependency keyed by another address than its manifest's.
+ Raises (as problem documents): the refusals of `read_request_tree`, and a 422 `request.invalid` naming
+ `dependencies` for dependencies without `files` or a dependency keyed by another address than its manifest's.
"""
if documents.files is None:
if documents.dependencies:
msg = "`dependencies` accompany the method's own `files`: send the method's tree in `files`, and its dependencies beside it."
- raise_validation_error(message=msg, error_type=ErrorType.INVALID_METHOD_FILES)
+ raise RunnerRequestError(msg, field=DEPENDENCIES_FIELD)
return None
dependency_documents = documents.dependencies or {}
# Every map's census first, so the request's trees together are held to their limits before any blob is read.
@@ -588,18 +596,20 @@ async def read_request_method(*, documents: TreeDocuments, blob_store: RunnerBlo
total_bytes=sum(census.stated_bytes for census in [files_census, *dependency_censuses.values()] if census is not None),
label=_METHOD_LABEL,
)
- tree = await read_request_tree(document=documents.files, blob_store=blob_store, label=FILES_LABEL, census=files_census)
+ tree = await read_request_tree(document=documents.files, blob_store=blob_store, label=FILES_LABEL, field=FILES_FIELD, census=files_census)
dependencies: dict[str, RequestTree] = {}
for address, dependency_document in dependency_documents.items():
label = f"The dependency '{wire_name(address)}'"
dependency_tree = await read_request_tree(
- document=dependency_document, blob_store=blob_store, label=label, census=dependency_censuses[address]
+ document=dependency_document, blob_store=blob_store, label=label, field=DEPENDENCIES_FIELD, census=dependency_censuses[address]
)
- declared = dependency_address_of(tree=dependency_tree, fallback_name=dependency_dir_name(address=address), label=label)
+ # The caller names a file of a dependency by the dependency's address, then its path inside it.
+ root = f"{address}/"
+ declared = dependency_address_of(tree=dependency_tree, fallback_name=dependency_dir_name(address=address), label=label, root=root)
if declared != address:
msg = f"{label} is keyed by an address its {MANIFEST_NAME} does not declare: it declares '{declared}'."
- raise_validation_error(message=msg, error_type=ErrorType.INVALID_METHOD_FILES)
- add_dependency(dependencies=dependencies, address=address, tree=dependency_tree, label=label)
+ raise RunnerRequestError(msg, field=DEPENDENCIES_FIELD)
+ add_dependency(dependencies=dependencies, address=address, tree=dependency_tree, label=label, root=root)
request_method = RequestMethod(tree=tree, dependencies=dependencies)
ensure_method_within_limits(request_method=request_method, label=_METHOD_LABEL)
return request_method
@@ -615,7 +625,8 @@ async def read_archive_method(*, bundle_b64: str) -> RequestMethod:
included, is refused by the tree's rule.
Raises (as problem documents): the archive's own refusals (`decode_bundle_archive`), the refusals of
- `read_request_tree`, and a 422 `InvalidMethodFiles` for a shipped package with no manifest, or two declaring one address.
+ `read_request_tree`, and a 422 `method.package_invalid` for a shipped package with no manifest, or two declaring one
+ address.
"""
archive_entries = decode_bundle_archive(bundle_b64=bundle_b64)
own_entries: list[tuple[str, bytes]] = []
@@ -630,13 +641,16 @@ async def read_archive_method(*, bundle_b64: str) -> RequestMethod:
vendored_entries.setdefault(package_name, []).append((package_path, data))
else:
own_entries.append((name, data))
- tree = await read_request_tree(document=_base64_map_document(entries=own_entries), blob_store=None, label=ARCHIVE_LABEL)
+ tree = await read_request_tree(document=_base64_map_document(entries=own_entries), blob_store=None, label=ARCHIVE_LABEL, field=BUNDLE_FIELD)
dependencies: dict[str, RequestTree] = {}
for package_name, package_entries in vendored_entries.items():
label = f"The package '{VENDORED_METHODS_PREFIX}{package_name}/' of {ARCHIVE_LABEL[0].lower()}{ARCHIVE_LABEL[1:]}"
- dependency_tree = await read_request_tree(document=_base64_map_document(entries=package_entries), blob_store=None, label=label)
- address = dependency_address_of(tree=dependency_tree, fallback_name=package_name, label=label)
- add_dependency(dependencies=dependencies, address=address, tree=dependency_tree, label=label)
+ dependency_tree = await read_request_tree(
+ document=_base64_map_document(entries=package_entries), blob_store=None, label=label, field=BUNDLE_FIELD
+ )
+ root = f"{VENDORED_METHODS_PREFIX}{package_name}/"
+ address = dependency_address_of(tree=dependency_tree, fallback_name=package_name, label=label, root=root)
+ add_dependency(dependencies=dependencies, address=address, tree=dependency_tree, label=label, root=root)
request_method = RequestMethod(tree=tree, dependencies=dependencies)
ensure_method_within_limits(request_method=request_method, label=ARCHIVE_LABEL)
return request_method
@@ -648,8 +662,8 @@ def with_resources(*, request_method: RequestMethod, resources: Mapping[str, byt
A file the tree already holds with the same bytes changes nothing; other bytes under a path the tree holds, or a path
that cannot name a file of a tree, are refused naming the path.
- Raises (as problem documents): a 422 `InvalidResourcePath` for two different files under one path or a path no tree
- could hold, and a 422 `MethodTreeTooLarge` for a tree the files take past this runner's limits.
+ Raises (as problem documents): a 422 `request.invalid` naming `resources` for two different files under one path or
+ a path no tree could hold, and a 422 `method.package_invalid` for a tree the files take past this runner's limits.
"""
if not resources:
return request_method
@@ -664,12 +678,12 @@ def with_resources(*, request_method: RequestMethod, resources: Mapping[str, byt
if violation is not None or excluded_name_violation(path):
reason = violation or "the membership rule keeps it out of every method tree"
msg = f"The file '{wire_name(path)}' sent in `resources` cannot be a file of the method's tree: {reason}."
- raise_validation_error(message=msg, error_type=ErrorType.INVALID_RESOURCE_PATH)
+ raise RunnerRequestError(msg, field=SUBMITTED_FILES_FIELD)
contents[path] = data
collisions = path_collisions(contents)
if collisions:
msg = f"The files sent in `resources` collide with the method's files: {', '.join(repr(path) for path in collisions)}."
- raise_validation_error(message=msg, error_type=ErrorType.INVALID_RESOURCE_PATH)
+ raise RunnerRequestError(msg, field=SUBMITTED_FILES_FIELD)
merged = RequestMethod(tree=RequestTree.make_from_contents(contents=contents), dependencies=request_method.dependencies)
ensure_tree_within_limits(tree=merged.tree, label=_WITH_RESOURCES_LABEL)
ensure_method_within_limits(request_method=merged, label=_WITH_RESOURCES_LABEL)
@@ -689,19 +703,20 @@ def _python_sources(*, tree: RequestTree) -> dict[str, str]:
return sources
-def ensure_python_allowed(*, request_method: RequestMethod, label: str) -> None:
+def ensure_python_allowed(*, request_method: RequestMethod, label: str, origin: CustomCodeOrigin) -> None:
"""Refuse a method shipping Python where it may not run, before anything of it is written.
- On a deployment that is not sandbox-hosted, any `.py` file is refused (403 `CustomCodeRequiresSandbox`): running it
- would import it in-process. On a sandbox-hosted deployment, the method's own tree declaring a Python structure class
- is refused (`MethodStructuresRefusedError`, a 422), naming each file by its tree path; a dependency tree is checked
- once written, by its address (`written_method`).
+ On a deployment that is not sandbox-hosted, any `.py` file is refused (501
+ `pipelex.deployment.custom_code_requires_sandbox`, whose `origin` says whether the request sent the method or named
+ a package to fetch): running it would import it in-process. On a sandbox-hosted deployment, the method's own tree
+ declaring a Python structure class is refused (`MethodStructuresRefusedError`, a 422), naming each file by its tree
+ path; a dependency tree is checked once written, by its address (`written_method`).
"""
if not request_method.has_python:
return
if not is_pipe_func_sandbox_hosted():
msg = f"{label} ships custom Python (.py); running it requires a sandbox-hosted deployment."
- raise_forbidden(message=msg, error_type=ErrorType.CUSTOM_CODE_REQUIRES_SANDBOX)
+ raise CustomCodeRequiresSandboxError(msg, origin=origin)
ensure_no_structured_content_in_library_sources(sources_by_dir={Path(): _python_sources(tree=request_method.tree)})
@@ -713,12 +728,12 @@ async def record_request_method(*, request_method: RequestMethod, blob_store: Ru
def ensure_method_holds_a_bundle(*, request_method: RequestMethod, label: str) -> None:
- """Refuse a method whose own tree holds no `.mthds` bundle, with a 422 `InvalidBundle`."""
+ """Refuse a method whose own tree holds no `.mthds` bundle, with a 422 `method.package_invalid`."""
if not request_method.tree.bundle_paths:
msg = f"{label} holds no .mthds bundle of its own."
if request_method.dependencies:
msg += " The packages it carries are dependencies: the method's own bundles go in its own tree."
- raise_validation_error(message=msg, error_type=ErrorType.INVALID_BUNDLE)
+ raise RequestMethodError(msg).with_params(reason=MethodPackageReason.NO_BUNDLE)
def select_tree_entry(*, tree: RequestTree, method_label: str) -> MethodEntry:
@@ -740,11 +755,11 @@ def select_tree_entry(*, tree: RequestTree, method_label: str) -> MethodEntry:
content = tree.contents[tree_path].decode("utf-8")
except UnicodeDecodeError as exc:
msg = f"The bundle '{tree_path}' of the method {method_label} is not UTF-8 text."
- raise MethodEntryError(msg).with_error_code(CoreCode.METHOD_SYNTAX) from exc
+ raise MethodEntryError(msg).with_error_code(CoreCode.METHOD_SYNTAX).with_params(finding=NOT_UTF8_FINDING) from exc
with translate_to_validate_bundle_error():
blueprint = MthdsParser.make_pipelex_bundle_blueprint(mthds_content=content, mthds_source=tree_path)
candidates.append(EntryCandidate.of_blueprint(tree_path=tree_path, blueprint=blueprint))
- manifest = manifest_of(tree=tree, label=f"the method {method_label}")
+ manifest = manifest_of(tree=tree, label=f"the method {method_label}", root="")
return select_entry(candidates=candidates, manifest=manifest, method_label=method_label)
diff --git a/api/pipelex_api/middleware.py b/api/pipelex_api/middleware.py
index 47dc20cbe..36b948d58 100644
--- a/api/pipelex_api/middleware.py
+++ b/api/pipelex_api/middleware.py
@@ -1,19 +1,21 @@
"""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 mthds.protocol.problem.registry import CoreCode
from pipelex import log
+from pipelex.errors.problem import ProblemView
+from pipelex.system.job_metadata import is_valid_request_id
from starlette.datastructures import MutableHeaders
from starlette.types import ASGIApp, Message, Receive, Scope, Send
-from pipelex_api.error_types import ErrorType
+from pipelex_api.exceptions import RunnerRequestError
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
+from pipelex_api.problem_document import problem_json_response
def request_id_of(request: Request) -> str | None:
@@ -27,25 +29,23 @@ def request_id_of(request: Request) -> str | None:
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.
+def _too_large_response(*, request: Request, size: int) -> JSONResponse:
+ """Build the 413 `request.too_large` 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.
+ The body-size check runs in middleware, before routing, so no exception handler answers it: a middleware must
+ `return` a response, not raise. It renders the same problem a `RunnerRequestError` carrying `request.too_large` would,
+ in the caller's view, since no authentication has run yet to mark the request as the operator's.
+ `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.
+
+ Args:
+ request: The refused request.
+ size: The bytes the request reached: the length it declared, or the bytes read before the read was cut.
"""
- 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)
+ message = f"Request body exceeds the {MAX_REQUEST_BODY_MIB} MiB limit"
+ refusal = RunnerRequestError(message).with_error_code(CoreCode.REQUEST_TOO_LARGE).with_params(limit=MAX_REQUEST_BODY_BYTES, size=size)
+ problem = refusal.to_problem(view=ProblemView.OPERATOR, request_id=request_id_of(request))
+ return problem_json_response(problem, view=ProblemView.CALLER)
async def request_body_size_middleware(request: Request, call_next: Callable[[Request], Awaitable[Response]]) -> Response:
@@ -69,7 +69,7 @@ async def request_body_size_middleware(request: Request, call_next: Callable[[Re
except ValueError:
declared = -1
if declared > MAX_REQUEST_BODY_BYTES:
- return _too_large_response(request=request)
+ return _too_large_response(request=request, size=declared)
original_receive = request.receive
bytes_seen = 0
@@ -98,7 +98,7 @@ async def request_body_size_middleware(request: Request, call_next: Callable[[Re
response = await call_next(request)
if too_large:
- return _too_large_response(request=request)
+ return _too_large_response(request=request, size=bytes_seen)
return response
@@ -113,13 +113,6 @@ _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.
@@ -137,21 +130,20 @@ def generate_request_id() -> str:
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.
+ malformed, or over-long — mints a fresh ULID. An inbound id is reflected
+ into response headers, logs and error bodies, so it is never trusted
+ verbatim: it must pass the runtime's one request id rule
+ (`pipelex.system.job_metadata.is_valid_request_id`), the one a run applies
+ to the id it is handed, or it is discarded. ULIDs and UUIDs both pass.
"""
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):
+ if is_valid_request_id(value=candidate):
return candidate
break
return generate_request_id()
diff --git a/api/pipelex_api/openapi_responses.py b/api/pipelex_api/openapi_responses.py
index d45223ce6..44d8658b6 100644
--- a/api/pipelex_api/openapi_responses.py
+++ b/api/pipelex_api/openapi_responses.py
@@ -1,18 +1,19 @@
"""Documentation-only models and shared `responses=` declarations for the API's problem documents.
Every failure this server emits is an `application/problem+json` document built
-by the global handlers in `pipelex_api.exception_handlers` — the problem of a
-pipelex error (`PipelexError.to_problem`, in the view of the request's reader)
-or the document of an API-authored `ApiError`
-(`build_problem_document_from_api_error`). The models here exist **only** so the
-committed OpenAPI artifact can publish that shape with a real schema instead of
-an untyped `additionalProperties: true` blob — nothing in the request path
-imports them, and adding a field here does not change a single response byte.
-Keep them in step with `docs/api-server/error-responses.md`, which is the prose contract.
-
-The members of a pipelex error's problem reuse the problem's own models (its next
-step, parameters, location, items and diagnostics), so the shapes published here
-are the ones the problem is validated with.
+by the global handlers in `pipelex_api.exception_handlers`: the problem of a
+pipelex error (`PipelexError.to_problem`, in the view of the request's reader),
+the runner's own refusals included, which it raises as the classes of
+`pipelex_api.exceptions`. Every document carries a registry `code`. The models
+here exist **only** so the committed OpenAPI artifact can publish that shape with
+a real schema instead of an untyped `additionalProperties: true` blob — nothing in
+the request path imports them, and adding a field here does not change a single
+response byte. Keep them in step with `docs/api-server/error-responses.md`, which
+is the prose contract.
+
+The members of a problem reuse the problem's own models (its next step,
+parameters, location, items and diagnostics), so the shapes published here are
+the ones the problem is validated with.
The response dicts below are attached two ways:
@@ -24,6 +25,10 @@ The response dicts below are attached two ways:
- The single-status constants go on the routes that can additionally produce
them (`responses=` on the decorator merges over the router-level set).
+A path no route serves (404 `request.not_found`) and a method a route does not
+accept (405 `request.method_not_allowed`) answer the same document, but belong to
+no operation, so no operation declares them.
+
The media type is NOT set here. FastAPI renders a `responses` entry's `model`
under the route's own response-class media type (`application/json`), with no
per-response override; `PipelexFastAPI.openapi()` in `pipelex_api.openapi_schema`
@@ -41,12 +46,11 @@ from pydantic import BaseModel, ConfigDict, Field
class ProblemDocument(BaseModel):
"""An RFC 9457 `application/problem+json` error body — the shape of every failure response.
- A pipelex error answers its problem document: the RFC's members (`type`, `title`, `status`, `detail`), the MTHDS
+ Every failure answers its problem document: the RFC's members (`type`, `title`, `status`, `detail`), the MTHDS
core's (`code`, `domain`, `retry`, `next_step`, always present, and `retry_after`, `params`, `location`, `errors`,
- `pipeline_run_id` when they hold a value) and Pipelex's (`request_id`, and `diagnostics` in the operator view
- alone). An API-authored error carries no `code` yet, and is classified by `error_type`, `error_domain` and
- `retryable` instead, with its request path as `instance`. No member is ever written as `null`: a member with no
- value is absent. `extra="allow"` mirrors RFC 9457's open-ended extension-member rule.
+ `pipeline_run_id` when they hold a value) and Pipelex's (`request_id`, always present on a response of this server,
+ and `diagnostics` in the operator view alone). No member is ever written as `null`: a member with no value is
+ absent. `extra="allow"` mirrors RFC 9457's open-ended extension-member rule.
"""
model_config = ConfigDict(extra="allow")
@@ -54,14 +58,11 @@ class ProblemDocument(BaseModel):
type: str = Field(
...,
description=(
- "Stable URI of the error's documentation page: the page of its `code` (`https://mthds.ai/errors/<code>` for a core code, "
- "`https://docs.pipelex.com/errors/<code>` for a Pipelex code), or `https://docs.pipelex.com/latest/errors/<kebab-error-type>/` "
- "for an API-authored error, which carries no `code` yet."
+ "Stable URI of the documentation page of the error's `code`: `https://mthds.ai/errors/<code>` for a core code, "
+ "`https://docs.pipelex.com/errors/<code>` for a Pipelex code."
),
)
- title: str = Field(
- ..., description="Short, human-readable summary: the title of the error's `code`, or of its `error_type` when it carries none."
- )
+ title: str = Field(..., description="Short, human-readable summary: the title of the error's `code`.")
status: int = Field(..., description="HTTP status code, repeated in the body per RFC 9457: the status its `code` declares.")
detail: str = Field(
...,
@@ -70,21 +71,18 @@ class ProblemDocument(BaseModel):
"Never parsed: a program branches on `code`."
),
)
- code: str | None = Field(
- default=None,
+ code: str = Field(
+ ...,
description=(
"Registry code of the error, what a client branches on: a core code of the MTHDS standard (e.g. `request.invalid`) "
- "or a Pipelex code (e.g. `pipelex.config.invalid`). Present on every error the runtime raises; absent on an "
- "API-authored error."
+ "or a Pipelex code (e.g. `pipelex.config.invalid`)."
),
)
- domain: str | None = Field(default=None, description="Who must act, the code's domain: `input`, `method`, `account`, `operator` or `runtime`.")
- retry: str | None = Field(
- default=None, description="Whether repeating the request can succeed, the code's verdict: `yes`, `no` or `outcome_unknown`."
- )
+ domain: str = Field(..., description="Who must act, the code's domain: `input`, `method`, `account`, `operator` or `runtime`.")
+ retry: str = Field(..., description="Whether repeating the request can succeed, the code's verdict: `yes`, `no` or `outcome_unknown`.")
retry_after: float | None = Field(default=None, description="Seconds to wait before a retry, when known, on a code whose verdict is `yes`.")
- next_step: NextStep | None = Field(
- default=None,
+ next_step: NextStep = Field(
+ ...,
description="What the reader should do next: a kind and a sentence, aimed at the caller, or at the operator in the operator view.",
)
params: ProblemParams | None = Field(default=None, description="The code's typed parameters, the ones its templates are rendered with.")
@@ -94,12 +92,16 @@ class ProblemDocument(BaseModel):
errors: list[ProblemItem] | None = Field(
default=None,
description=(
- "One item per fault, for a refusal with several, such as a method that does not validate. "
- "On `/validate`, `/resolve`, `/codegen` and `/pipe-io` an invalid bundle is a **200** verdict instead."
+ "One item per fault, for a refusal with several, such as a request whose fields the route refuses. "
+ "On `/validate`, `/resolve`, `/codegen` and `/pipe-io` an invalid bundle is a **200** verdict instead, "
+ "whose `errors` are items of this same shape."
),
)
pipeline_run_id: str | None = Field(default=None, description="The run the failure belongs to.")
- request_id: str | None = Field(default=None, description="Correlation id, echoed in the `X-Request-ID` response header.")
+ request_id: str | None = Field(
+ default=None,
+ description="Correlation id, echoed in the `X-Request-ID` response header: the caller's own when valid, else one the runner mints.",
+ )
diagnostics: ProblemDiagnostics | None = Field(
default=None,
description=(
@@ -107,13 +109,6 @@ class ProblemDocument(BaseModel):
"Present only when the request was authenticated as the operator's (`AUTH_MODE=api_key`, or a trusted proxy)."
),
)
- instance: str | None = Field(default=None, description="Path of the request that failed, on an API-authored error.")
- error_type: str | None = Field(default=None, description="Stable name of an API-authored error (e.g. `Unauthenticated`).")
- error_domain: str | None = Field(
- default=None,
- description="On an API-authored error: `input` (caller can fix it → 4xx) or `config` (deployment must fix it → 5xx).",
- )
- retryable: bool | None = Field(default=None, description="On an API-authored error: whether retrying the same request can plausibly succeed.")
def _problem(description: str, *, headers: dict[str, Any] | None = None) -> dict[str, Any]:
@@ -129,42 +124,24 @@ def _problem(description: str, *, headers: dict[str, Any] | None = None) -> dict
return response
-PROBLEM_400_START_REQUIRES_ASYNC: dict[str, Any] = _problem(
- "`StartRequiresAsyncOrchestration` — this deployment's orchestrator is blocking-only and cannot honor "
- "fire-and-forget delivery. Use `POST /execute` instead.",
-)
-
PROBLEM_401: dict[str, Any] = _problem(
- "Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`).",
+ "`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused or expired "
+ "bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`), or trusts a "
+ "proxy's forwarded identity and the proxy forwarded none.",
headers={
"WWW-Authenticate": {
- "description": "Authentication challenge — always `Bearer`.",
+ "description": (
+ "Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key` or "
+ "`AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request."
+ ),
"schema": {"type": "string"},
}
},
)
-PROBLEM_403_RUN_POLICY: dict[str, Any] = _problem(
- "A deployment-policy refusal: `OrchestrationModeOverrideForbidden` — the request asked for an "
- "`orchestration_mode` this deployment does not allow overriding per request "
- "(`allow_request_orchestration_mode_override = false`); `CustomCodeRequiresSandbox` — the method (a bundle, or a "
- "fetched `method_ref` package) ships custom Python and this deployment is not sandbox-hosted; or "
- "`ReadScopeForbidden` — on a `jwt` deployment, the request sent a `read_scope` that does not lie under the caller's "
- "own `user_id`. The refusal of a method whose Python declares structure classes, "
- "`pipelex.deployment.python_structures_refused`, is a 422 instead, since the method's author changes it.",
-)
-
-PROBLEM_403_METHOD_PYTHON_POLICY: dict[str, Any] = _problem(
- "The run routes' Python policy, applied to the method's tree: `CustomCodeRequiresSandbox` — the method (sent in "
- "`files`, or a fetched `method_ref` package) ships custom Python and this deployment is not sandbox-hosted. "
- "Also `ReadScopeForbidden` — on a `jwt` deployment, the request sent a `read_scope` that does not lie under the "
- "caller's own `user_id`. The refusal of a method whose Python declares structure classes, "
- "`pipelex.deployment.python_structures_refused`, is a 422 instead, since the method's author changes it.",
-)
-
PROBLEM_403_READ_SCOPE: dict[str, Any] = _problem(
- "`ReadScopeForbidden` — on a `jwt` deployment, the request sent a `read_scope` that does not lie under the caller's "
- "own `user_id`, the only scope its token may read.",
+ "`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment, the request sent "
+ "a `read_scope` that does not lie under the caller's own `user_id`, the only scope its token may read.",
)
PROBLEM_409_DUPLICATE_RUN: dict[str, Any] = _problem(
@@ -173,13 +150,17 @@ PROBLEM_409_DUPLICATE_RUN: dict[str, Any] = _problem(
)
PROBLEM_413: dict[str, Any] = _problem(
- "Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).",
+ "`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment's byte "
+ "limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give both in bytes.",
)
PROBLEM_422: dict[str, Any] = _problem(
- "The request could not be processed: a malformed body, a field failing validation, or a pipelex error whose code "
- "the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the diagnostic routes "
- "an *invalid bundle* is a **200** verdict, not a 422 — see each route's response contract.",
+ "The request could not be processed: a body that does not parse (`request.malformed`), fields the route refuses "
+ "(`request.invalid`, one item in `errors` per refused field), a security rule's refusal (such as "
+ "`pipelex.security.reserved_key` or `security.input_url_refused`), a method tree the runner cannot read "
+ "(`method.package_invalid`), or a pipelex error whose code the caller fixes (a `.mthds` bundle that does not "
+ "validate, a missing input). Note that on the diagnostic routes an *invalid bundle* is a **200** verdict, not a "
+ "422 — see each route's response contract.",
)
PROBLEM_429: dict[str, Any] = _problem(
@@ -192,13 +173,33 @@ PROBLEM_429: dict[str, Any] = _problem(
},
)
-PROBLEM_500: dict[str, Any] = _problem(
- "A failure the caller cannot fix (a missing env var, a bad TOML override, a backend fault), or an unexpected "
- "error answered as `runtime.unexpected`. Report the `request_id`.",
+_PROBLEM_500_DESCRIPTION = (
+ "A failure the caller cannot fix: the runner's own configuration (`runtime.misconfigured`, such as a missing env "
+ "var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`. Report the "
+ "`request_id`."
+)
+
+PROBLEM_500: dict[str, Any] = _problem(_PROBLEM_500_DESCRIPTION)
+
+# The 500 of a route that reads files a request names by hash from the runner's blob store, which can also find one of
+# them damaged. It replaces the composite router's 500 on those routes, so its description names that code too.
+PROBLEM_500_HELD_BLOBS: dict[str, Any] = _problem(
+ f"{_PROBLEM_500_DESCRIPTION} Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the "
+ "blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its "
+ "verdict is not to retry. The operator removes the object, for the blob to be uploaded again.",
+)
+
+PROBLEM_501_RUN_POLICY: dict[str, Any] = _problem(
+ "`pipelex.deployment.custom_code_requires_sandbox` — the method (a bundle, or a fetched `method_ref` package, as "
+ "`params.origin` says) ships custom Python and this deployment is not sandbox-hosted. The refusal of a method whose "
+ "Python declares structure classes, `pipelex.deployment.python_structures_refused`, is a 422 instead, since the "
+ "method's author changes it.",
)
-PROBLEM_501_ASYNC_NOT_ENABLED: dict[str, Any] = _problem(
- "`runtime.unsupported` — this deployment does not provide async pipeline execution. Permanent under the current deployment; do not retry.",
+PROBLEM_501_START: dict[str, Any] = _problem(
+ "`runtime.unsupported` — this deployment cannot honor fire-and-forget delivery: its orchestrator is blocking-only, or "
+ "its async execution is not enabled. Permanent under the current deployment; use `POST /execute` instead. Or "
+ "`pipelex.deployment.custom_code_requires_sandbox`, as on `POST /execute`.",
)
PROBLEM_404_METHOD_PACKAGE: dict[str, Any] = _problem(
@@ -206,15 +207,9 @@ PROBLEM_404_METHOD_PACKAGE: dict[str, Any] = _problem(
)
PROBLEM_403_BLOB_UPLOAD: dict[str, Any] = _problem(
- "`BlobUploadNotAuthorized` — the upload does not carry the signed query an upload target of `POST /v1/blobs/missing` "
- "names, its signature does not hold for this hash and scope, or it has expired. Ask `POST /v1/blobs/missing` again "
- "for a fresh target.",
-)
-
-PROBLEM_501_METHOD_REF: dict[str, Any] = _problem(
- "`MethodRefNotSupported` — the request selected its method by a **registry-form** `method_ref` (not a "
- "`github.com/...` address), and no server-side method registry resolves those yet. Use an address-form reference "
- "or send the method's tree in `files` instead.",
+ "`auth.forbidden`, whose `params.requirement` is `signed_upload_target` — the upload does not carry the signed query "
+ "an upload target of `POST /v1/blobs/missing` names, its signature does not hold for this hash and scope, or it has "
+ "expired. Ask `POST /v1/blobs/missing` again for a fresh target.",
)
diff --git a/api/pipelex_api/openapi_schema.py b/api/pipelex_api/openapi_schema.py
index 062f7fe5d..11c3aa9b2 100644
--- a/api/pipelex_api/openapi_schema.py
+++ b/api/pipelex_api/openapi_schema.py
@@ -65,16 +65,22 @@ def use_problem_json_media_type(schema: dict[str, Any]) -> None:
content[PROBLEM_JSON_MEDIA_TYPE] = json_content
-# Two families of models share their class names: the fix vocabulary `pipelex.suggested_fix` publishes on a verdict's
-# `ValidationErrorItem`, and the standard's, which a problem's `ProblemItem` carries (`file` where Pipelex's has `source`,
-# and a catch-all for an operation kind it does not list). Pydantic names both by their module when they meet, which would
-# rename the schemas a generated client binds to; this pass gives Pipelex's their own names back, and the standard's the
-# `Problem` prefix its other models carry.
+# Two families of models share their class names: the fix vocabulary of `pipelex.suggested_fix`, which the migration
+# ledger's entries carry, and the standard's, which a problem's `ProblemItem` carries (`file` where Pipelex's has
+# `source`, and a catch-all for an operation kind it does not list). Pydantic names both by their module when they meet,
+# which would rename the schemas a generated client binds to; this pass gives Pipelex's their own names back, and the
+# standard's the `Problem` prefix its other models carry.
_SCHEMA_RENAMES_BY_PREFIX: dict[str, str] = {
"pipelex__suggested_fix__": "",
"mthds__protocol__problem__models__": "Problem",
}
+# The standard's problem item, the root of the standard's models on the wire. Every schema it reaches is the standard's
+# and carries the `Problem` prefix, whether or not a Pipelex model of the same class name is published beside it, so a
+# schema's name does not depend on which other models a release happens to publish.
+_STANDARD_ROOT_SCHEMA = "ProblemItem"
+_STANDARD_SCHEMA_PREFIX = "Problem"
+
_SCHEMA_REF_PREFIX = "#/components/schemas/"
@@ -97,16 +103,36 @@ def _with_renamed_refs(node: Any, *, renames: dict[str, str]) -> Any:
return node
-def name_shared_fix_schemas(schema: dict[str, Any]) -> None:
- """Rename the module-qualified fix schemas Pydantic generates for the two fix families, in place.
+def _referenced_schemas(node: Any) -> set[str]:
+ """The names of the schemas ``node`` references."""
+ if isinstance(node, dict):
+ return {name for value in cast("dict[str, Any]", node).values() for name in _referenced_schemas(value)}
+ if isinstance(node, list):
+ return {name for item in cast("list[Any]", node) for name in _referenced_schemas(item)}
+ if isinstance(node, str) and node.startswith(_SCHEMA_REF_PREFIX):
+ return {node.removeprefix(_SCHEMA_REF_PREFIX)}
+ return set()
- Refuses a rename onto a name another schema already holds, which would merge two shapes into one.
- """
- components: dict[str, Any] = schema.get("components", {})
- schemas: dict[str, Any] = components.get("schemas", {})
- renames = {name: _renamed_schema(name) for name in schemas if _renamed_schema(name) != name}
+
+def _reached_schemas(*, schemas: dict[str, Any], root: str) -> set[str]:
+ """The schemas ``root`` reaches through its references, itself included."""
+ reached: set[str] = set()
+ pending = [root]
+ while pending:
+ name = pending.pop()
+ if name in reached or name not in schemas:
+ continue
+ reached.add(name)
+ pending.extend(_referenced_schemas(schemas[name]))
+ return reached
+
+
+def _apply_schema_renames(schema: dict[str, Any], *, renames: dict[str, str]) -> None:
+ """Rename schemas and every reference to them, in place, refusing a rename onto a name another schema holds."""
if not renames:
return
+ components: dict[str, Any] = schema.get("components", {})
+ schemas: dict[str, Any] = components.get("schemas", {})
taken = set(schemas) - set(renames)
clashes = sorted(new_name for new_name in renames.values() if new_name in taken)
if clashes:
@@ -118,6 +144,23 @@ def name_shared_fix_schemas(schema: dict[str, Any]) -> None:
schema[key] = _with_renamed_refs(schema[key], renames=renames)
+def name_shared_fix_schemas(schema: dict[str, Any]) -> None:
+ """Rename the module-qualified fix schemas Pydantic generates for the two fix families, in place.
+
+ The module-qualified names come back first, then every schema the standard's problem item reaches takes the
+ `Problem` prefix it lacks. Refuses a rename onto a name another schema already holds, which would merge two shapes
+ into one.
+ """
+ schemas: dict[str, Any] = schema.get("components", {}).get("schemas", {})
+ _apply_schema_renames(schema, renames={name: _renamed_schema(name) for name in schemas if _renamed_schema(name) != name})
+ schemas = schema.get("components", {}).get("schemas", {})
+ standard_schemas = _reached_schemas(schemas=schemas, root=_STANDARD_ROOT_SCHEMA)
+ _apply_schema_renames(
+ schema,
+ renames={name: f"{_STANDARD_SCHEMA_PREFIX}{name}" for name in standard_schemas if not name.startswith(_STANDARD_SCHEMA_PREFIX)},
+ )
+
+
class PipelexFastAPI(FastAPI):
"""The app class. Stock FastAPI, extended only to publish errors as `application/problem+json`."""
diff --git a/api/pipelex_api/problem_document.py b/api/pipelex_api/problem_document.py
index 7d9e887f3..84fc0a5e7 100644
--- a/api/pipelex_api/problem_document.py
+++ b/api/pipelex_api/problem_document.py
@@ -1,89 +1,81 @@
-"""Problem-document construction for the API's own errors.
+"""The rendering of a problem document as the HTTP response that carries it.
-A pure module — no FastAPI imports, no I/O. A pipelex error answers its own
-problem document (`PipelexError.to_problem`, rendered by
-`pipelex_api.exception_handlers.problem_response`); this module builds the
-document of an API-authored 4xx/5xx that has no `PipelexError` behind it
-(`raise_validation_error` and friends in `pipelex_api.errors`), from the static
-`ErrorType` enum. It returns a plain `dict` the caller serializes as
-`application/problem+json`.
+A pure module: no logging and no request state of its own. Every failure the runner answers is a problem
+(`pipelex.errors.problem.PipelexProblem`) built in the operator's view, and this module renders it as the response a
+reader receives: the view of that reader, the status its code declares, and the headers the status calls for. The
+global handlers in `pipelex_api.exception_handlers` log the failure and then render it here, and so does the body-size
+middleware in `pipelex_api.middleware`, which answers before any handler runs. Keeping the rendering here lets both
+share it while the handlers import the middleware's request-id reader, with no import cycle between them.
"""
-from typing import Any
+import math
-from pipelex.base_exceptions import ErrorDomain
+from fastapi.responses import JSONResponse
+from pipelex.errors.error_codes import error_code_spec, parse_error_code
+from pipelex.errors.problem import PipelexProblem, ProblemView, caller_view_of
-from pipelex_api.error_types import ErrorType
-from pipelex_api.error_uri import error_type_title, error_type_uri
-
-# Content type for every error response — RFC 7807 problem documents. Lives
-# here, the module that builds them, so the FastAPI app, the middleware, and
-# the error handlers can all reference one constant without a circular import.
+# Content type for every error response, an RFC 9457 problem document. Lives here, the module that renders them, so the
+# FastAPI app, the middleware and the error handlers all reference one constant.
PROBLEM_JSON_MEDIA_TYPE = "application/problem+json"
+# The HTTP status of a problem whose code the registry gives none, which only a client's own failure has.
+_FALLBACK_PROBLEM_STATUS = 500
-def build_problem_document_from_api_error(
- error_type: ErrorType,
- message: str,
- status: int,
- *,
- instance: str | None,
- request_id: str | None,
- error_domain: ErrorDomain | None = ErrorDomain.INPUT,
- retryable: bool = False,
-) -> dict[str, Any]:
- """Build an RFC 7807 problem document for an API-authored error.
- Used by the `pipelex_api.errors` 4xx/5xx helpers, whose failures are the API's own
- request validation, auth, or configuration checks rather than a pipelex
- domain error — there is no `PipelexError` whose problem it could answer. The
- `type` URI and `title` are derived from the static `ErrorType` enum, and the
- `error_type` / `error_domain` / `retryable` members classify it until every
- API-authored error answers a registry code.
+def problem_status(problem: PipelexProblem) -> int:
+ """The HTTP status of the response a problem is the body of: its code's, from the error registry."""
+ code = parse_error_code(problem.code)
+ if code is None:
+ return _FALLBACK_PROBLEM_STATUS
+ return error_code_spec(code).status or _FALLBACK_PROBLEM_STATUS
- `error_domain` defaults to `INPUT` — the caller can fix a 4xx. API-owned
- 5xx (a missing secret, a misconfigured backend) pass `CONFIG`: an operator,
- not the caller, fixes those. `None` omits the member entirely, matching how
- a domain-less pipelex error renders.
- `retryable` defaults to `False`: every error this builder authors is a
- caller-input mistake or a server misconfiguration, neither of which a blind
- retry fixes. Carried as a positional contract member rather than dropped on
- `None`, so clients can drive retry logic uniformly without branching on
- field presence.
+def _retry_after_header(problem: PipelexProblem, *, status: int) -> dict[str, str]:
+ """Return a `Retry-After` header dict when a retry hint applies to this response.
- `None`-valued context (`instance`, `request_id`) is dropped rather than
- emitted as `null`, as a problem document never writes a member as `null`.
+ Emitted only when the response is itself a retry invitation, a 429 such as a provider's rate limit passed through,
+ so a hint never rides a 500 or a 422, where `Retry-After` is meaningless. The problem's `retry_after`, which only a
+ code inviting a retry carries and which is always finite, is rounded up to an integer. Empty when no hint applies.
"""
- document: dict[str, Any] = {
- "type": error_type_uri(error_type),
- "title": error_type_title(error_type),
- "status": status,
- "detail": message,
- }
- if instance is not None:
- document["instance"] = instance
- if request_id is not None:
- document["request_id"] = request_id
- document["error_type"] = error_type
- if error_domain is not None:
- document["error_domain"] = error_domain
- document["retryable"] = retryable
- return document
+ if status != 429:
+ return {}
+ seconds = problem.retry_after
+ if seconds is None or not math.isfinite(seconds):
+ return {}
+ return {"Retry-After": str(max(0, math.ceil(seconds)))}
+
+
+def problem_json_response(
+ problem: PipelexProblem, *, view: ProblemView, headers: dict[str, str] | None = None, status: int | None = None
+) -> JSONResponse:
+ """Render a problem built in the operator's view as the `application/problem+json` response a reader of `view` receives.
+ The status is the one the problem's code declares, unless `status` names another, and the body's `status` member
+ repeats it, as RFC 9457 asks. The caller's view leaves the operator's `diagnostics` out and aims the step at the
+ caller. A 429 carries the `Retry-After` its problem gives. `headers` are added to it, such as the `Allow` header of a
+ 405 or the `WWW-Authenticate` challenge of a 401, which the refusal names only where the deployment reads a bearer
+ credential.
-def with_request_context(document: dict[str, Any], *, instance: str | None, request_id: str | None) -> dict[str, Any]:
- """Return a copy of a problem document carrying the two request-scoped members.
+ Args:
+ problem: The problem, in the operator's view.
+ view: The view of whoever receives the response.
+ headers: Further headers of the response.
+ status: The status to answer with in place of the code's, which only a refusal the web framework raised gives,
+ when the code it is answered under declares another, so that it keeps the status it was raised with.
- The `pipelex_api.errors` helpers build their document where no `Request` is in hand — a validation
- check deep inside a route, an auth refusal — so `instance` and `request_id` are stamped later,
- by the handler that renders the response and does hold the request. A copy rather than an
- in-place edit, because the `ApiError` a caller catches and inspects must read exactly as it was
- raised. `None` is dropped rather than emitted as `null`, the rule every builder here follows.
+ Returns:
+ The response.
"""
- stamped = dict(document)
- if instance is not None:
- stamped["instance"] = instance
- if request_id is not None:
- stamped["request_id"] = request_id
- return stamped
+ status = status or problem_status(problem)
+ match view:
+ case ProblemView.OPERATOR:
+ reader_problem = problem
+ case ProblemView.CALLER:
+ reader_problem = caller_view_of(problem=problem)
+ response_headers = {**(headers or {}), **_retry_after_header(problem, status=status)}
+ return JSONResponse(
+ status_code=status,
+ content=reader_problem.model_copy(update={"status": status}).to_wire(),
+ media_type=PROBLEM_JSON_MEDIA_TYPE,
+ headers=response_headers,
+ )
diff --git a/api/pipelex_api/request_refusals.py b/api/pipelex_api/request_refusals.py
new file mode 100644
index 000000000..359a98c28
--- /dev/null
+++ b/api/pipelex_api/request_refusals.py
@@ -0,0 +1,126 @@
+"""A request the route's rules refused, field by field, as the runner's refusal: one problem item per field.
+
+FastAPI refuses a body, a query or a path parameter that fails the route's declared model with a
+`RequestValidationError`, and the run routes, which validate their extras by hand, meet pydantic's own
+`ValidationError`. Both list their faults the same way, each with the location of the field it refused, so both become
+one `RunnerRequestError`: `request.invalid`, with one item per refused field, each naming the field as its `field`
+parameter and its location, and the first field as the problem's own. A body that is not JSON at all is
+`request.malformed` instead, since no field of it could be read.
+
+Only each fault's location and pydantic's message are read, and the field a model validator's refusal names: a
+validator that judges several fields together reports a fault of the body as a whole, located at no field, so it raises a
+`RequestFieldConflictError` naming the field to change, which pydantic keeps in the fault's context and the item names.
+The message, which may quote what the caller sent, rides the operator's diagnostics alone: a caller reads each item's
+sentence, which its code renders from the field's name.
+"""
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from mthds.protocol.problem.registry import CoreCode, RequestMalformedReason
+from pipelex.errors.problem import make_location, make_problem_item
+
+from pipelex_api.exceptions import CallbackUrlRefusedError, RequestFieldConflictError, RunnerRequestError
+
+# The first segment of the location FastAPI gives a fault, naming the part of the request it is in rather than a field.
+_REQUEST_PARTS = frozenset({"body", "query", "path", "header", "cookie"})
+
+# The field a fault of the body as a whole is about, which names no field: a model validator's refusal names its own.
+WHOLE_BODY_FIELD = "body"
+
+# The type pydantic gives a body that is not JSON, which FastAPI reports as a fault of the body.
+_JSON_INVALID_TYPE = "json_invalid"
+
+# The longest path a refusal names: a path holds the keys of a mapping the caller sent, which the caller picks the length
+# of, so a longer one is cut, marked by an ellipsis.
+MAX_REFUSED_FIELD_PATH_LEN = 256
+
+# The most refused fields a refusal names one by one: a list the caller sent can fail item by item, and the first ones
+# are enough to start fixing it.
+MAX_REFUSED_FIELDS = 50
+
+
+def refused_field_path(*, loc: Sequence[Any], located_by_request_part: bool) -> str:
+ """The dotted path of the field a fault refused, from its location, or `body` for a fault of the body as a whole.
+
+ Args:
+ loc: The fault's location, as pydantic gives it.
+ located_by_request_part: Whether the location starts with the part of the request it is in, as FastAPI's does,
+ which is left out of the path.
+
+ Returns:
+ The path, such as `callback_urls.0`, cut to `MAX_REFUSED_FIELD_PATH_LEN` characters.
+ """
+ parts = [str(part) for part in loc]
+ if located_by_request_part and parts and parts[0] in _REQUEST_PARTS:
+ parts = parts[1:]
+ path = ".".join(parts) or WHOLE_BODY_FIELD
+ if len(path) > MAX_REFUSED_FIELD_PATH_LEN:
+ return f"{path[:MAX_REFUSED_FIELD_PATH_LEN]}…"
+ return path
+
+
+def _fault_field_path(*, fault: Mapping[str, Any], located_by_request_part: bool) -> str:
+ """The path of the field a fault refused: the one its validator names, else the one its location gives."""
+ context: Mapping[str, Any] = fault.get("ctx") or {}
+ error: object = context.get("error")
+ if isinstance(error, RequestFieldConflictError):
+ return error.field
+ return refused_field_path(loc=fault.get("loc", ()), located_by_request_part=located_by_request_part)
+
+
+def _summary(*, faults: Sequence[Mapping[str, Any]], paths: Sequence[str]) -> str:
+ """The operator's account of the refusal: the first `MAX_REFUSED_FIELDS` faults as `<field>: <message>`, joined.
+
+ A list the caller sent can fail item by item, so the account names as many faults as the refusal names fields, and
+ then how many more there were.
+
+ Args:
+ faults: The faults pydantic reported.
+ paths: The path of the field each fault refused, in the same order.
+ """
+ described = [f"{path}: {fault.get('msg') or 'Invalid input'}" for fault, path in zip(faults[:MAX_REFUSED_FIELDS], paths, strict=False)]
+ unnamed_count = len(faults) - len(described)
+ if unnamed_count > 0:
+ described.append(f"and {unnamed_count} more")
+ return "; ".join(described) or "Request validation failed"
+
+
+def refused_request_error(*, faults: Sequence[Mapping[str, Any]], located_by_request_part: bool) -> RunnerRequestError:
+ """The runner's refusal of a request whose fields the route's rules refused, one item per refused field.
+
+ Args:
+ faults: The faults pydantic reported, each with its `loc`, `msg` and `type`.
+ located_by_request_part: Whether each location starts with the part of the request it is in, as FastAPI's do.
+
+ Returns:
+ `request.malformed` for a body that is not JSON, else `request.invalid` with one item per refused field, the
+ first `MAX_REFUSED_FIELDS` of them. Its message names as many faults, then how many more there were.
+ """
+ fault_paths = [_fault_field_path(fault=fault, located_by_request_part=located_by_request_part) for fault in faults]
+ message = _summary(faults=faults, paths=fault_paths)
+ if any(fault.get("type") == _JSON_INVALID_TYPE for fault in faults):
+ return RunnerRequestError(message).with_error_code(CoreCode.REQUEST_MALFORMED).with_params(reason=RequestMalformedReason.NOT_JSON)
+ paths: list[str] = []
+ for path in fault_paths:
+ if path not in paths and len(paths) < MAX_REFUSED_FIELDS:
+ paths.append(path)
+ if not paths:
+ paths.append(WHOLE_BODY_FIELD)
+ items = [make_problem_item(code=CoreCode.REQUEST_INVALID, params={"field": path}, location=make_location(field=path)) for path in paths]
+ return RunnerRequestError(message, field=paths[0]).with_items(items=items)
+
+
+def callback_url_refusal_in(*, faults: Sequence[Mapping[str, Any]]) -> CallbackUrlRefusedError | None:
+ """The refusal of a callback URL the SSRF rules raised among a request's faults, if there is one.
+
+ The rule runs in the request model's validator, and a validator's error rides its fault's context, where pydantic
+ keeps the exception it raised. A request that also fails on another field is still the security rule's refusal, so
+ the first one found is answered, with its own code, and logs its security event, whatever else failed.
+ """
+ for fault in faults:
+ context: Mapping[str, Any] = fault.get("ctx") or {}
+ error: object = context.get("error")
+ if isinstance(error, CallbackUrlRefusedError):
+ return error
+ return None
diff --git a/api/pipelex_api/routes/blob_upload.py b/api/pipelex_api/routes/blob_upload.py
index 5c7dfb0b2..e1bdcf328 100644
--- a/api/pipelex_api/routes/blob_upload.py
+++ b/api/pipelex_api/routes/blob_upload.py
@@ -5,26 +5,28 @@ the signed query of its target (`pipelex_api.blob_upload`), which only a caller
authentication on `POST /v1/blobs/missing` holds, so a sender uploads with exactly the headers the target names. The
bytes are written under the scope the signature binds, whole and create-only (`pipelex_api.blob_store`): a blob is never
changed, so uploading bytes the runner already holds succeeds and changes nothing, and bytes of another size than the
-object held under their hash, which only damaged storage could hold, are a 500 `BlobStoreCorrupted` rather than written
-over it. Only `blobs/` is ever written here, never a tree's listing under `trees/`, so an uploaded file that happens to
-read as a listing proves nothing.
+object held under their hash, which only damaged storage could hold, are a 500 `pipelex.storage.damaged` rather than
+written over it. Only `blobs/` is ever written here, never a tree's listing under `trees/`, so an uploaded file that
+happens to read as a listing proves nothing.
"""
from typing import Annotated
from fastapi import APIRouter, Path, Query, Request, Response
from mthds.method_tree.digest import sha256_hex
+from mthds.protocol.problem.registry import CoreCode
from pipelex_api.blob_store import RunnerBlobStore
from pipelex_api.blob_upload import EXPIRES_PARAM, SCOPE_PARAM, SIGNATURE_PARAM, is_upload_authorized
-from pipelex_api.error_types import ErrorType
-from pipelex_api.errors import raise_forbidden, raise_validation_error
+from pipelex_api.exceptions import RunnerAuthError, RunnerRequestError
from pipelex_api.limits import MAX_METHOD_TREE_FILE_BYTES
-from pipelex_api.openapi_responses import PROBLEM_403_BLOB_UPLOAD, PROBLEM_413, PROBLEM_422, PROBLEM_500
+from pipelex_api.openapi_responses import PROBLEM_403_BLOB_UPLOAD, PROBLEM_413, PROBLEM_422, PROBLEM_500_HELD_BLOBS
router = APIRouter(tags=["blobs"])
SHA256_PATTERN = r"^[0-9a-f]{64}$"
+# What an upload refused for its target lacks, as the `requirement` of its `auth.forbidden`.
+SIGNED_UPLOAD_TARGET_REQUIREMENT = "signed_upload_target"
@router.put(
@@ -34,7 +36,7 @@ SHA256_PATTERN = r"^[0-9a-f]{64}$"
summary="Upload one blob's bytes to the target POST /blobs/missing named.",
# Mounted outside the composite `/v1` router, so it inherits none of its shared problem responses: it declares
# the statuses it can produce itself, and never answers 401.
- responses={403: PROBLEM_403_BLOB_UPLOAD, 413: PROBLEM_413, 422: PROBLEM_422, 500: PROBLEM_500},
+ responses={403: PROBLEM_403_BLOB_UPLOAD, 413: PROBLEM_413, 422: PROBLEM_422, 500: PROBLEM_500_HELD_BLOBS},
openapi_extra={
"x-mthds-protocol": True,
"requestBody": {
@@ -53,21 +55,26 @@ async def put_blob(
"""Store one blob's bytes under its SHA-256, as the upload target `POST /v1/blobs/missing` named (MTHDS Protocol).
The body is the blob's bytes and nothing else. A target whose signature does not hold, or that has expired, is a
- 403 `BlobUploadNotAuthorized`, as is a query that is not one this runner signs, such as an expiry that is not a
- decimal integer; a body past `MAX_METHOD_TREE_FILE_KIB` a 422 `MethodTreeTooLarge`; and a body whose SHA-256 is not
- the path's a 422 `BlobMismatch`. A blob is never changed: uploading bytes the runner already holds answers 204 and
- changes nothing, and uploading bytes whose hash names an object of another size, which only damaged storage could
- hold, is a 500 `BlobStoreCorrupted` that leaves the object as it is.
+ 403 `auth.forbidden` whose `requirement` is a signed upload target, as is a query that is not one this runner signs,
+ such as an expiry that is not a decimal integer; a body past `MAX_METHOD_TREE_FILE_KIB` a 413 `request.too_large`;
+ and a body whose SHA-256 is not the path's a 422 `request.invalid` naming the body. A blob is never changed:
+ uploading bytes the runner already holds answers 204 and changes nothing, and uploading bytes whose hash names an
+ object of another size, which only damaged storage could hold, is a 500 `pipelex.storage.damaged` that leaves the
+ object as it is.
"""
if not is_upload_authorized(scope=scope, sha256=sha256, expires=expires, signature=signature) or scope is None:
msg = "This upload carries no valid target: ask POST /v1/blobs/missing for one, and upload to the URL it names before it expires."
- raise_forbidden(message=msg, error_type=ErrorType.BLOB_UPLOAD_NOT_AUTHORIZED)
+ raise RunnerAuthError(msg).with_error_code(CoreCode.AUTH_FORBIDDEN).with_params(requirement=SIGNED_UPLOAD_TARGET_REQUIREMENT)
body = await request.body()
if len(body) > MAX_METHOD_TREE_FILE_BYTES:
msg = f"The blob holds {len(body)} bytes, past this runner's limit of {MAX_METHOD_TREE_FILE_BYTES // 1024} KiB for one file of a method tree."
- raise_validation_error(message=msg, error_type=ErrorType.METHOD_TREE_TOO_LARGE)
+ raise (
+ RunnerRequestError(msg, field="body")
+ .with_error_code(CoreCode.REQUEST_TOO_LARGE)
+ .with_params(limit=MAX_METHOD_TREE_FILE_BYTES, size=len(body))
+ )
if sha256_hex(body) != sha256:
msg = f"The body's SHA-256 is not {sha256}, the hash the path names: nothing was stored."
- raise_validation_error(message=msg, error_type=ErrorType.BLOB_MISMATCH)
+ raise RunnerRequestError(msg, field="body")
await RunnerBlobStore.make_for_scope(scope=scope).store_blob(data=body)
return Response(status_code=204)
diff --git a/api/pipelex_api/routes/pipelex/agent/models.py b/api/pipelex_api/routes/pipelex/agent/models.py
index 1bc6a7510..07ecd2e77 100644
--- a/api/pipelex_api/routes/pipelex/agent/models.py
+++ b/api/pipelex_api/routes/pipelex/agent/models.py
@@ -10,13 +10,12 @@ from pipelex.cogt.models.model_reference_check import ModelCheckCategory, ModelR
from pipelex.pipeline.runner import PipelexModelDeck
from pipelex.runtime_hub import get_model_deck
-from pipelex_api.error_types import ErrorType
-from pipelex_api.errors import raise_validation_error
+from pipelex_api.exceptions import RunnerRequestError
from pipelex_api.routes.pipelex.pipeline import ApiRunner
router = APIRouter(tags=["agent"])
-# The longest reference the check accepts once trimmed; one character more is refused with `InvalidModelReference`.
+# The longest reference the check accepts once trimmed; one character more is refused with `request.invalid`.
MAX_MODEL_REFERENCE_LENGTH = 199
@@ -34,25 +33,21 @@ async def get_models(
the flat `models` list (`{name, type}` entries) plus this implementation's
category-keyed routing extensions (`aliases`, `waterfalls`). The `type` query
param is a SINGLE protocol `ModelCategory` value: repeated `?type=` values
- (arity, `ValidationError`) and unknown categories (`InvalidModelCategory`) are
- both 422s (RFC 7807).
+ and unknown categories are both 422 `request.invalid` naming `type`.
"""
# Protocol arity: `type` is a plain single-value enum. FastAPI silently keeps one of
# several repeated scalar query params, so the multi-value rejection must be explicit.
- # Generic ValidationError, not InvalidModelCategory: the values may all be valid —
- # what's wrong is the arity.
if len(request.query_params.getlist("type")) > 1:
- raise_validation_error(message="The `type` query parameter accepts a single value")
+ msg = "The `type` query parameter accepts a single value"
+ raise RunnerRequestError(msg, field="type")
category: ModelCategory | None = None
if model_type is not None:
try:
category = ModelCategory(model_type)
- except ValueError:
+ except ValueError as exc:
valid = ", ".join(sorted(member.value for member in ModelCategory))
- raise_validation_error(
- message=f"Invalid model category. Valid values: {valid}",
- error_type=ErrorType.INVALID_MODEL_CATEGORY,
- )
+ msg = f"Invalid model category. Valid values: {valid}"
+ raise RunnerRequestError(msg, field="type") from exc
return await ApiRunner().models(category=category)
@@ -88,34 +83,33 @@ async def check_model(
reference found `resolved` in a category is one a pipe of that category may name, and one found
`not_found` is one a validation refuses. A verdict is a `200` whatever the resolution, and on
`not_found` it carries the suggestions a failing validation of the same reference offers. A
- request that cannot produce a verdict is an input `422`: `ValidationError` for a missing or
- repeated `reference` or a repeated `type`, `InvalidModelReference` for a reference that is blank,
- a sigil or a namespace alone, or too long, and `InvalidModelCategory` for an unknown `type`.
+ request that cannot produce a verdict is an input `422` `request.invalid` naming the parameter: a
+ missing or repeated `reference`, a repeated `type`, a reference that is blank, a sigil or a namespace
+ alone, or too long, and an unknown `type`.
"""
for parameter_name in ("reference", "type"):
if len(request.query_params.getlist(parameter_name)) > 1:
- raise_validation_error(message=f"The `{parameter_name}` query parameter accepts a single value")
+ msg = f"The `{parameter_name}` query parameter accepts a single value"
+ raise RunnerRequestError(msg, field=parameter_name)
# The parser trims the reference itself, and its `raw` is the trimmed text the length limit measures.
try:
parsed_reference = ModelReference.parse(reference)
except ModelReferenceParseError as exc:
- raise_validation_error(message=exc.message, error_type=ErrorType.INVALID_MODEL_REFERENCE)
+ raise RunnerRequestError(exc.message, field="reference") from exc
if len(parsed_reference.raw) > MAX_MODEL_REFERENCE_LENGTH:
too_long_message = (
f"The model reference holds {len(parsed_reference.raw)} characters once trimmed, more than the {MAX_MODEL_REFERENCE_LENGTH} accepted"
)
- raise_validation_error(message=too_long_message, error_type=ErrorType.INVALID_MODEL_REFERENCE)
+ raise RunnerRequestError(too_long_message, field="reference")
category: ModelCheckCategory | None = None
if model_type is not None:
try:
category = ModelCheckCategory(model_type)
- except ValueError:
+ except ValueError as exc:
valid = ", ".join(sorted(member.value for member in ModelCheckCategory))
- raise_validation_error(
- message=f"Invalid model category. Valid values: {valid}",
- error_type=ErrorType.INVALID_MODEL_CATEGORY,
- )
+ msg = f"Invalid model category. Valid values: {valid}"
+ raise RunnerRequestError(msg, field="type") from exc
return check_model_reference(model_deck=get_model_deck(), reference=parsed_reference, category=category)
diff --git a/api/pipelex_api/routes/pipelex/blobs.py b/api/pipelex_api/routes/pipelex/blobs.py
index 74f798956..143b353bc 100644
--- a/api/pipelex_api/routes/pipelex/blobs.py
+++ b/api/pipelex_api/routes/pipelex/blobs.py
@@ -16,8 +16,7 @@ from pydantic import BaseModel, ConfigDict, Field, StrictInt
from pipelex_api.blob_store import RunnerBlobStore
from pipelex_api.blob_upload import upload_target_url
-from pipelex_api.error_types import ErrorType
-from pipelex_api.errors import raise_validation_error
+from pipelex_api.exceptions import RunnerRequestError
from pipelex_api.json_body import JsonBodyRoute
from pipelex_api.method_tree_request import ensure_within_tree_limits
from pipelex_api.openapi_responses import PROBLEM_403_READ_SCOPE
@@ -26,6 +25,9 @@ from pipelex_api.routes.pipelex.pipeline import resolve_blob_scope
router = APIRouter(tags=["blobs"], route_class=JsonBodyRoute)
SHA256_PATTERN = r"^[0-9a-f]{64}$"
+# The body field listing the blobs, and the query parameter naming their scope, which a refusal names as its `field`.
+_BLOBS_FIELD = "blobs"
+_READ_SCOPE_FIELD = "read_scope"
_OCTET_STREAM = "application/octet-stream"
_SIZE_DESCRIPTION = (
"The length of the bytes, a JSON integer written without a fraction or an exponent. A size written 13.0 is refused, "
@@ -82,7 +84,7 @@ def _unique_blobs(*, blobs: list[BlobRef]) -> dict[str, int]:
known = sizes.get(blob.sha256)
if known is not None and known != blob.size:
msg = f"The blob {blob.sha256} is listed twice with different sizes, {known} and {blob.size}: one hash names one set of bytes."
- raise_validation_error(message=msg, error_type=ErrorType.BLOB_MISMATCH)
+ raise RunnerRequestError(msg, field=_BLOBS_FIELD)
sizes[blob.sha256] = blob.size
return sizes
@@ -110,12 +112,13 @@ async def find_missing_blobs(
A blob it holds at the stated size is left out, and an empty list means there is nothing to upload; a hash held
at another size than the one stated is listed too, and its upload tells the two cases apart: bytes of the size held
- change nothing, and bytes of another size mean the object held is damaged, a 500 `BlobStoreCorrupted`, since nothing
- writes over a blob. When the request names the tree the blobs
+ change nothing, and bytes of another size mean the object held is damaged, a 500 `pipelex.storage.damaged`, since
+ nothing writes over a blob. When the request names the tree the blobs
make up by its `digest`, this runner has recorded that tree as held in full, which it does only after reading every
file of a tree a request sent, and every listed blob is a file of that tree, the answer is an empty list at once.
- A hash given twice with different sizes is a 422 `BlobMismatch`, and a blob or a set of blobs past this runner's
- tree limits a 422 `MethodTreeTooLarge`, both refused before anything is uploaded. Each upload target is this runner's own
+ A hash given twice with different sizes is a 422 `request.invalid` naming `blobs`, and a blob or a set of blobs past
+ this runner's tree limits a 422 `method.package_invalid`, both refused before anything is uploaded. Each upload
+ target is this runner's own
`PUT /v1/blobs/{sha256}`, at `PUBLIC_BASE_URL` when the deployment sets it, its query signed for that hash and
the caller's scope, valid for `BLOB_UPLOAD_URL_TTL_SECONDS`, to send with exactly the headers it names.
"""
@@ -123,7 +126,7 @@ async def find_missing_blobs(
try:
validate_read_scope(value=read_scope)
except ValueError as exc:
- raise_validation_error(message=str(exc), error_type=ErrorType.INVALID_READ_SCOPE)
+ raise RunnerRequestError(str(exc), field=_READ_SCOPE_FIELD) from exc
sizes = _unique_blobs(blobs=request_data.blobs)
largest_sha256 = max(sizes, key=lambda sha256: sizes[sha256], default=None)
ensure_within_tree_limits(
diff --git a/api/pipelex_api/routes/pipelex/codegen.py b/api/pipelex_api/routes/pipelex/codegen.py
index 8439a0529..3a4835bc1 100644
--- a/api/pipelex_api/routes/pipelex/codegen.py
+++ b/api/pipelex_api/routes/pipelex/codegen.py
@@ -14,8 +14,10 @@ from pipelex.tools.misc.package_utils import get_package_version
from pipelex.tools.typing.pydantic_utils import empty_list_factory_of
from pydantic import BaseModel, Field, model_validator
+from pipelex_api.exceptions import RequestFieldConflictError
from pipelex_api.json_body import JsonBodyRoute
-from pipelex_api.openapi_responses import PROBLEM_403_METHOD_PYTHON_POLICY, PROBLEM_404_METHOD_PACKAGE, PROBLEM_501_METHOD_REF
+from pipelex_api.openapi_responses import PROBLEM_403_READ_SCOPE, PROBLEM_404_METHOD_PACKAGE, PROBLEM_500_HELD_BLOBS, PROBLEM_501_RUN_POLICY
+from pipelex_api.problem_view import problem_view_of
from pipelex_api.routes.pipelex.crate_ops import (
CrateInvalidReport,
GeneratedArtifact,
@@ -77,7 +79,7 @@ class CodegenRequest(MethodTreeRequest):
case CodegenRouteKind.TYPES:
if self.pipe_ref is not None:
msg = "pipe_ref is not accepted for kind='types' (a concept-set-wide projection)"
- raise ValueError(msg)
+ raise RequestFieldConflictError(msg, field="pipe_ref")
return self
@@ -112,9 +114,10 @@ CodegenResponse = Annotated[Union[CodegenValidReport, CrateInvalidReport], Field
@router.post(
"/codegen",
response_model=CodegenResponse,
- # On top of the composite router's shared 401/413/422/500: the Python policy's 403s and the
- # `method_ref` fetch outcomes, shared with `/resolve`.
- responses={403: PROBLEM_403_METHOD_PYTHON_POLICY, 404: PROBLEM_404_METHOD_PACKAGE, 501: PROBLEM_501_METHOD_REF},
+ # On top of the composite router's shared 401/413/422/500: the refusals of the method's tree shared with `/resolve`,
+ # a `read_scope` outside the caller's own, the `method_ref` package-not-found 404, a damaged blob a hash entry
+ # names, and the Python policy's 501.
+ responses={403: PROBLEM_403_READ_SCOPE, 404: PROBLEM_404_METHOD_PACKAGE, 500: PROBLEM_500_HELD_BLOBS, 501: PROBLEM_501_RUN_POLICY},
# NOT tagged `x-mthds-protocol` — a Pipelex API extension, like `/resolve`. The MTHDS standard
# specifies the crate this reads (the Library Crate Format); it specifies no type projection, so
# every `target` here — `ts-zod` and `python-pydantic` no less than `python-structures` — is ours.
@@ -132,12 +135,12 @@ async def codegen_mthds(request: Request, request_data: CodegenRequest) -> JSONR
- **Valid verdict (200, `is_valid: true`):** the artifacts + lock on the valid arm.
- **Invalid verdict (200, `is_valid: false`):** the library could not be parsed, loaded, or
- validated — `validation_errors[]` from pipelex's one shared builder; no artifacts exist.
+ validated — `errors[]`, one problem item per error; no artifacts exist.
- **No verdict (non-2xx):** an unknown projection `kind`/`target`, a `pipe_ref` on a
concept-set-wide kind, or a malformed method selector is a request-shape 422 problem+json; the
- method's tree is refused as `/resolve` refuses it (422 `InvalidMethodFiles` or `MissingBlobs`,
- the Python policy's 403s, the `method_ref` fetch outcomes, 501 for a registry-form
- `method_ref`); auth is 401/403; server fault is 5xx.
+ method's tree is refused as `/resolve` refuses it (a 422 `method.package_invalid` or
+ `request.blobs_missing`, the Python policy's refusals, the `method_ref` fetch outcomes, a 422
+ `request.unsupported` for a registry-form `method_ref`); auth is 401/403; server fault is 5xx.
"""
with CodeGenerationReport(
artifact=UsageStatsCodegenArtifact.TYPES, target=usage_stats_codegen_target(target=request_data.target)
@@ -174,5 +177,5 @@ async def _generate_codegen_response(*, request: Request, request_data: CodegenR
outcome = await project_resolved_method(request=request, request_data=request_data, project=_projection_response)
if isinstance(outcome, ValidateBundleError):
generation_report.declare_failed()
- return invalid_crate_report_response(outcome)
+ return invalid_crate_report_response(outcome, view=problem_view_of(request))
return outcome
diff --git a/api/pipelex_api/routes/pipelex/crate_ops.py b/api/pipelex_api/routes/pipelex/crate_ops.py
index 2f43310be..3eb74dec0 100644
--- a/api/pipelex_api/routes/pipelex/crate_ops.py
+++ b/api/pipelex_api/routes/pipelex/crate_ops.py
@@ -9,7 +9,7 @@ calls by its address loads only when the request shipped it, in `dependencies` o
`.mthds/methods/`, and one nothing shipped is the invalid verdict, never a lookup among the methods installed on this
server or a fetch. They speak the same verdict vocabulary as
`POST /validate`: a produced verdict is a 200 discriminated on `is_valid`, with the invalid arm carrying the
-structured `validation_errors[]` built by pipelex's one shared builder. This module holds the pieces they share so
+structured `errors[]` built by pipelex's one shared builder. This module holds the pieces they share so
the envelopes cannot drift.
The invalid arm here is the *crate* verdict: it deliberately omits `/validate`'s runnability facts
@@ -29,8 +29,8 @@ from typing import Literal, NamedTuple, NoReturn, TypeVar
from fastapi import Request
from fastapi.responses import JSONResponse
+from mthds.protocol.problem.models import ProblemItem
from mthds.protocol.problem.registry import CoreCode
-from pipelex.base_exceptions import ValidationErrorItem
from pipelex.errors.problem import ProblemView
from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, get_required_entry_pipe
from pipelex.libraries.library_crate import LibraryCrate
@@ -42,8 +42,7 @@ from pipelex.pipeline.resolve_bundle import resolve_crate_from_method_dir
from pipelex.tools.typing.pydantic_utils import empty_list_factory_of
from pydantic import BaseModel, Field
-from pipelex_api.error_types import ErrorType
-from pipelex_api.errors import raise_not_implemented
+from pipelex_api.exceptions import RunnerRequestError
from pipelex_api.method_tree_request import RequestMethod, WrittenMethod, manifest_of, written_method
from pipelex_api.routes.pipelex.method_selection import select_request_method
from pipelex_api.schemas.models import MethodTreeRequest
@@ -51,6 +50,9 @@ from pipelex_api.schemas.models import MethodTreeRequest
#: What a route makes of a resolved method, in the worker thread that holds it loaded.
ProjectionT = TypeVar("ProjectionT")
+# The `reason` of the `request.unsupported` refusing a registry-form `method_ref`, which no registry here resolves.
+REGISTRY_FORM_METHOD_REF_REASON = "registry_form_method_ref"
+
class GeneratedArtifact(BaseModel):
"""One generated file: its path relative to the client's chosen output root, and its full content."""
@@ -60,36 +62,36 @@ class GeneratedArtifact(BaseModel):
class CrateInvalidReport(BaseModel):
- """The 200 **invalid** arm shared by `/resolve` and `/codegen` — the crate-verdict vocabulary.
+ """The 200 **invalid** arm shared by `/resolve`, `/codegen` and `/pipe-io` — the crate-verdict vocabulary.
Same discipline as `/validate`'s `InvalidReport`: an invalid library is the *successful
product* of a diagnostic call (the request was well-formed; the library was not), so it rides
- a 200 discriminated on `is_valid`, carrying the same structured `ValidationErrorItem`s the
- local CLI and `/validate` emit for the identical failure.
+ a 200 discriminated on `is_valid`, carrying the same problem items in `errors` that `/validate`
+ emits for the identical failure.
"""
is_valid: Literal[False] = False
"""Discriminant of the invalid arm (mirrors the valid arms' `Literal[True]`)."""
- validation_errors: list[ValidationErrorItem] = Field(
- default_factory=empty_list_factory_of(ValidationErrorItem),
- description="Per-error diagnostics, built by pipelex's one shared builder — non-empty on every invalid verdict.",
+ errors: list[ProblemItem] = Field(
+ default_factory=empty_list_factory_of(ProblemItem),
+ description=(
+ "One problem item per error, each with its own code, its parameters and its location — non-empty on every "
+ "invalid verdict. The items of the verdict's problem, as a refusal's `errors` carry them."
+ ),
)
message: str = Field(default="MTHDS library could not be resolved", description="Human-readable summary of the verdict.")
-def invalid_crate_report_response(validate_error: ValidateBundleError) -> JSONResponse:
+def invalid_crate_report_response(validate_error: ValidateBundleError, *, view: ProblemView) -> JSONResponse:
"""Render a produced "could not resolve" verdict as a 200 `CrateInvalidReport`.
- The items are the error's own (`ValidateBundleError.validation_error_items`) and the message is
- its problem's `detail`, the sentence its code renders, which reads the same in every view.
- `exclude_none` drops each item's unset locators so the wire items match the agent CLI's
- byte-for-byte — the "one error item, two surfaces" guarantee `/validate` already keeps.
+ The items are those of the error's problem in the view of the request's reader (`ValidateBundleError.problem_items`,
+ one per item of pipelex's one shared builder), and the message is its `detail`, the sentence its code renders, which
+ reads the same in every view. `exclude_none` drops each item's unset members, as the standard writes a problem item.
"""
- invalid_report = CrateInvalidReport(
- validation_errors=validate_error.validation_error_items(),
- message=validate_error.to_problem(view=ProblemView.CALLER).detail,
- )
+ problem = validate_error.to_problem(view=view)
+ invalid_report = CrateInvalidReport(errors=list(problem.errors or []), message=problem.detail)
return JSONResponse(content=invalid_report.model_dump(mode="json", serialize_as_any=True, by_alias=True, exclude_none=True))
@@ -114,7 +116,7 @@ class ResolvedMethod(NamedTuple):
Raises:
MethodEntryError: The manifest is not UTF-8 text, or not a valid manifest (a 422 in the input domain).
"""
- manifest = manifest_of(tree=self.request_method.tree, label=f"the method {self.method_label}")
+ manifest = manifest_of(tree=self.request_method.tree, label=f"the method {self.method_label}", root="")
return manifest.main_pipe if manifest is not None else None
@@ -163,16 +165,20 @@ async def project_resolved_method(
verdict instead, the `ValidateBundleError` carrying the structured validation items, with `project` never called and
nothing left loaded.
- Raises (as problem documents): 501 for a registry-form `method_ref`; the 422s and 403s of `select_request_method`;
- the address-form fetch and location failures (`MethodRefError` subclasses); and whatever `project` raises, such as
- a selection refusal.
+ Raises (as problem documents): a 422 `request.unsupported` for a registry-form `method_ref`; the refusals of
+ `select_request_method`; the address-form fetch and location failures (`MethodRefError` subclasses); and whatever
+ `project` raises, such as a selection refusal.
"""
if request_data.method_ref is not None and not looks_like_method_ref(request_data.method_ref):
- raise_not_implemented(
+ msg = (
"Registry-form method_ref resolution is not available on this server: no method registry is wired. "
"Use an address-form reference (a `github.com/...` address, e.g. `github.com/Pipelex/methods/[email protected]`) "
- "or send the method's tree in `files`.",
- error_type=ErrorType.METHOD_REF_NOT_SUPPORTED,
+ "or send the method's tree in `files`."
+ )
+ raise (
+ RunnerRequestError(msg, field="method_ref")
+ .with_error_code(CoreCode.REQUEST_UNSUPPORTED)
+ .with_params(reason=REGISTRY_FORM_METHOD_REF_REASON)
)
selected = await select_request_method(
request=request, method_ref=request_data.method_ref, resources=request_data.resources, read_scope=request_data.read_scope
@@ -237,7 +243,7 @@ def resolve_requested_pipe(crate: LibraryCrate, *, pipe_ref: str | None, manifes
failed selection — an unknown ref, an ambiguous one, a chain that finds no entry pipe or several —
is an input-domain 422 rather than an invalid-crate verdict, since nothing about the *closure* is
wrong in any of them. It is raised as the engine's own entry-lookup error class (see
- `_raise_selection_refusal`), so an unknown or ambiguous ref carries the `error_type` the run routes
+ `_raise_selection_refusal`), so an unknown or ambiguous ref carries the code the run routes
answer for the same `pipe_code`. A chain finding no entry pipe or several has no run-route twin to
match: this route refuses both the way the pipe-selector design classifies them.
diff --git a/api/pipelex_api/routes/pipelex/method_selection.py b/api/pipelex_api/routes/pipelex/method_selection.py
index a194e480e..60eb82e25 100644
--- a/api/pipelex_api/routes/pipelex/method_selection.py
+++ b/api/pipelex_api/routes/pipelex/method_selection.py
@@ -4,8 +4,9 @@
`dependencies` it carries and the `resources` that join it, or fetched by an address-form `method_ref`. This module reads
either into a `RequestMethod` with the run routes' own machinery (`pipelex_api.method_tree_request`,
`pipelex_api.method_source.fetched_method`), so the four routes accept, refuse and resolve a tree exactly as the run
-routes do: the same limits, the same `InvalidMethodFiles` and `MissingBlobs` refusals, the same fetch, and the same
-Python policy, a `.py` file refused with a 403 `CustomCodeRequiresSandbox` unless the deployment is sandbox-hosted.
+routes do: the same limits, the same `method.package_invalid` and `request.blobs_missing` refusals, the same fetch, and
+the same Python policy, a `.py` file refused with a 501 `pipelex.deployment.custom_code_requires_sandbox` unless the
+deployment is sandbox-hosted.
A sent tree's hash entries resolve in the blob store of the request's `read_scope`, else of the caller's own id
(`resolve_blob_scope`), and the tree is recorded in that store only under a `read_scope` the host named: without one, the
@@ -19,7 +20,7 @@ from fastapi import Request
from pipelex_api.blob_store import RunnerBlobStore
from pipelex_api.bundle_resources import decode_bundle_resources
-from pipelex_api.errors import raise_validation_error
+from pipelex_api.exceptions import CustomCodeOrigin, RunnerRequestError
from pipelex_api.method_source import fetched_method
from pipelex_api.method_tree_request import (
REQUEST_METHOD_LABEL,
@@ -57,9 +58,10 @@ async def select_request_method(
The request envelope already refused a body naming neither or both, so a request without a `method_ref` sends
`files`, read from the raw JSON text of its body (`tree_documents_of`).
- Raises (as problem documents): the refusals of `read_request_method` and `with_resources` (422s), the
- `method_ref` fetch outcomes (`fetched_method`), a 422 `InvalidBundle` for a method whose own tree holds no `.mthds`
- file, and the Python policy's 403s (`ensure_python_allowed`).
+ Raises (as problem documents): the refusals of `read_request_method` and `with_resources`, the `method_ref` fetch
+ outcomes (`fetched_method`), a 422 `method.package_invalid` whose `reason` is `no_bundle` for a method whose own tree
+ holds no `.mthds` file, and the Python policy's refusals (`ensure_python_allowed`): a 501
+ `pipelex.deployment.custom_code_requires_sandbox`, or a 422 `pipelex.deployment.python_structures_refused`.
The Python policy holds for the crate routes too, although they run nothing: on a deployment that is not
sandbox-hosted, loading the library imports every `.py` of the tree declaring a `StructuredContent` subclass
@@ -70,16 +72,17 @@ async def select_request_method(
fetched = await asyncio.to_thread(fetched_method, method_ref)
package_label = f"Method package {fetched.label}"
ensure_method_holds_a_bundle(request_method=fetched.request_method, label=package_label)
- ensure_python_allowed(request_method=fetched.request_method, label=package_label)
+ ensure_python_allowed(request_method=fetched.request_method, label=package_label, origin=CustomCodeOrigin.PACKAGE)
return SelectedMethod(request_method=fetched.request_method, method_label=fetched.label)
blob_store = RunnerBlobStore.make_for_scope(scope=resolve_blob_scope(request, read_scope=read_scope))
sent_method = await read_request_method(documents=tree_documents_of(body=await request.body()), blob_store=blob_store)
if sent_method is None:
# Unreachable: the request envelope already refused a body naming no method.
- raise_validation_error(message="This request sends no method tree in `files` and no `method_ref`.")
+ msg = "This request sends no method tree in `files` and no `method_ref`."
+ raise RunnerRequestError(msg, field="files")
request_method = with_resources(request_method=sent_method, resources=decode_bundle_resources(resources=resources))
ensure_method_holds_a_bundle(request_method=request_method, label=_SENT_METHOD_LABEL)
- ensure_python_allowed(request_method=request_method, label=_SENT_METHOD_LABEL)
+ ensure_python_allowed(request_method=request_method, label=_SENT_METHOD_LABEL, origin=CustomCodeOrigin.BUNDLE)
if read_scope is not None:
await record_request_method(request_method=request_method, blob_store=blob_store)
return SelectedMethod(request_method=request_method, method_label=REQUEST_METHOD_LABEL)
diff --git a/api/pipelex_api/routes/pipelex/pipe_io.py b/api/pipelex_api/routes/pipelex/pipe_io.py
index cf4e959e0..bb34080ec 100644
--- a/api/pipelex_api/routes/pipelex/pipe_io.py
+++ b/api/pipelex_api/routes/pipelex/pipe_io.py
@@ -11,7 +11,8 @@ from pipelex.pipeline.validate_bundle import build_pending_signatures
from pydantic import BaseModel, Field
from pipelex_api.json_body import JsonBodyRoute
-from pipelex_api.openapi_responses import PROBLEM_403_METHOD_PYTHON_POLICY, PROBLEM_404_METHOD_PACKAGE, PROBLEM_501_METHOD_REF
+from pipelex_api.openapi_responses import PROBLEM_403_READ_SCOPE, PROBLEM_404_METHOD_PACKAGE, PROBLEM_500_HELD_BLOBS, PROBLEM_501_RUN_POLICY
+from pipelex_api.problem_view import problem_view_of
from pipelex_api.routes.pipelex.crate_ops import (
CrateInvalidReport,
RequestedPipe,
@@ -114,9 +115,10 @@ PipeIOResponse = Annotated[Union[PipeIOValidReport, CrateInvalidReport], Field(d
@router.post(
"/pipe-io",
response_model=PipeIOResponse,
- # On top of the composite router's shared 401/413/422/500: the Python policy's 403s and the
- # `method_ref` fetch outcomes it shares with `/resolve` and `/codegen`.
- responses={403: PROBLEM_403_METHOD_PYTHON_POLICY, 404: PROBLEM_404_METHOD_PACKAGE, 501: PROBLEM_501_METHOD_REF},
+ # On top of the composite router's shared 401/413/422/500: the refusals of the method's tree it shares with
+ # `/resolve` and `/codegen`, a `read_scope` outside the caller's own, the `method_ref` package-not-found 404, a
+ # damaged blob a hash entry names, and the Python policy's 501.
+ responses={403: PROBLEM_403_READ_SCOPE, 404: PROBLEM_404_METHOD_PACKAGE, 500: PROBLEM_500_HELD_BLOBS, 501: PROBLEM_501_RUN_POLICY},
# NOT tagged `x-mthds-protocol`: it carries the standard's artifacts under their neutral names,
# but the route is a Pipelex API extension, and the flag marks the standard's five operations alone.
)
@@ -136,15 +138,16 @@ async def pipe_io(request: Request, request_data: PipeIORequest) -> JSONResponse
- **Invalid verdict (200, `is_valid: false`):** the closure could not be parsed, loaded, or
statically validated — the crate verdict, carrying no artifact, no selection and no files.
- **No verdict (non-2xx):** a malformed body and neither or both method selectors are
- request-shape 422s (`ValidationError`); a `files` map that is not a method tree is a 422
- `InvalidMethodFiles`, and hash entries this runner does not hold one 422 `MissingBlobs`, as on
- `/validate`; custom Python on a deployment that is not sandbox-hosted, or a Python structure
- class, is a 403; a selection refusal is an input 422 named for its failure,
- `EntryPipeNotFoundError` for an unknown `pipe_ref` or a single-pipe request whose chain finds no
- entry pipe, `EntryPipeAmbiguousError` for an ambiguous one or a chain that finds several; the
- `method_ref` fetch outcomes are those of `/resolve` (404, 422, 501);
- an artifact that cannot be derived (`PipeIOContractError`) is a 500. All RFC 7807
- `application/problem+json` via the global handlers.
+ request-shape 422s (`request.invalid`); a `files` map that is not a method tree is a 422
+ `method.package_invalid`, and hash entries this runner does not hold a 422
+ `request.blobs_missing`, as on `/validate`; custom Python on a deployment that is not
+ sandbox-hosted is a 501 `pipelex.deployment.custom_code_requires_sandbox`, and a Python
+ structure class a 422 `pipelex.deployment.python_structures_refused`; a selection refusal is an
+ input 422 named for its failure, `request.pipe_not_found` for an unknown `pipe_ref` or a
+ single-pipe request whose chain finds no entry pipe, `request.pipe_ambiguous` for an ambiguous
+ one or a chain that finds several; the `method_ref` fetch outcomes are those of `/resolve` (404,
+ 422); an artifact that cannot be derived (`PipeIOContractError`) is a 500. All
+ `application/problem+json` documents with a registry `code`, via the global handlers.
"""
outcome = await project_resolved_method(
request=request,
@@ -152,7 +155,7 @@ async def pipe_io(request: Request, request_data: PipeIORequest) -> JSONResponse
project=lambda resolution: _pipe_io_response(resolution=resolution, request_data=request_data),
)
if isinstance(outcome, ValidateBundleError):
- return invalid_crate_report_response(outcome)
+ return invalid_crate_report_response(outcome, view=problem_view_of(request))
return outcome
diff --git a/api/pipelex_api/routes/pipelex/pipeline.py b/api/pipelex_api/routes/pipelex/pipeline.py
index f3b5e0d23..64ceb8cf1 100644
--- a/api/pipelex_api/routes/pipelex/pipeline.py
+++ b/api/pipelex_api/routes/pipelex/pipeline.py
@@ -18,6 +18,7 @@ from pipelex.errors.problem import ProblemView
from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
from pipelex.libraries.method_requirements import ensure_served_method_requirements_met
from pipelex.pipe_run.delivery_assignment import DeliveryAssignment, StorageTarget, WebhookTarget
+from pipelex.pipe_run.exceptions import AsyncExecutionNotEnabledError
from pipelex.pipe_run.pipe_run_protocol import PipeRunProtocol
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.pipeline_response import PipelexRunResultExecute, PipelexRunResultStart, RunState
@@ -36,11 +37,11 @@ from typing_extensions import override
from pipelex_api.api_config import ApiConfig, get_api_config, is_callers_override, resolve_orchestration_mode
from pipelex_api.blob_store import RunnerBlobStore
from pipelex_api.bundle_resources import decode_bundle_resources
-from pipelex_api.error_types import ErrorType
-from pipelex_api.errors import ApiSecurityRefusal, raise_bad_request, raise_forbidden, raise_validation_error, security_refusal_of
+from pipelex_api.exceptions import CustomCodeOrigin, ReservedObjectKeyError, RunnerAuthError, RunnerRequestError
from pipelex_api.json_body import decode_json_body
from pipelex_api.method_source import fetched_method
from pipelex_api.method_tree_request import (
+ BUNDLE_FIELD,
REQUEST_METHOD_LABEL,
RequestMethod,
ensure_method_holds_a_bundle,
@@ -55,15 +56,18 @@ from pipelex_api.method_tree_request import (
)
from pipelex_api.middleware import request_id_of
from pipelex_api.openapi_responses import (
- PROBLEM_400_START_REQUIRES_ASYNC,
- PROBLEM_403_RUN_POLICY,
+ PROBLEM_403_READ_SCOPE,
PROBLEM_404_METHOD_PACKAGE,
PROBLEM_409_DUPLICATE_RUN,
PROBLEM_429,
- PROBLEM_501_ASYNC_NOT_ENABLED,
+ PROBLEM_500_HELD_BLOBS,
+ PROBLEM_501_RUN_POLICY,
+ PROBLEM_501_START,
)
from pipelex_api.problem_view import problem_view_of
+from pipelex_api.request_refusals import WHOLE_BODY_FIELD, callback_url_refusal_in, refused_request_error
from pipelex_api.routes.pipelex.utils import get_current_iso_timestamp
+from pipelex_api.run_extras_binding import bind_run_extras
from pipelex_api.schemas.models import (
PipelexApiExecuteRequest,
PipelexApiExecuteResponse,
@@ -138,6 +142,10 @@ def _resolve_storage_scope(request: Request, *, requested: str | None) -> str:
return requested or get_request_user_id(request)
+# What a request refused for its `read_scope` lacks, as the `requirement` of its `auth.forbidden`.
+READ_SCOPE_UNDER_CALLER_REQUIREMENT = "read_scope_under_caller"
+
+
def bound_read_scope(request: Request, *, requested: str | None) -> str | None:
"""The read scope a request sent, once this caller may read under it; every route taking a `read_scope` reads it here.
@@ -145,9 +153,9 @@ def bound_read_scope(request: Request, *, requested: str | None) -> str | None:
trusted proxy forwarding the user's identity (the hosted plane, which sends the organization it serves) or a
single tenant, and with the shared `api_key` it is one tenant: a sent value is taken as it is. With `AUTH_MODE=jwt`
the caller reaches this runner directly, its token's `user_id` its only identity, so it reads only under that id: a
- sent scope must be the id or lie under it, else the request is refused with a 403 `ReadScopeForbidden` before
- anything is read, so no caller reads another's blobs or runs under another's scope. A run's storage scope must lie
- under its read scope, so it is bound with it.
+ sent scope must be the id or lie under it, else the request is refused with a 403 `auth.forbidden`, whose
+ `requirement` is `read_scope_under_caller`, before anything is read, so no caller reads another's blobs or runs
+ under another's scope. A run's storage scope must lie under its read scope, so it is bound with it.
"""
if requested is None:
return None
@@ -157,10 +165,8 @@ def bound_read_scope(request: Request, *, requested: str | None) -> str | None:
case AuthMode.JWT:
caller_id = get_request_user_id(request)
if requested.split("/")[0] != caller_id:
- raise_forbidden(
- message=f"The read_scope {requested!r} does not lie under this caller's own id, the only scope its token may read.",
- error_type=ErrorType.READ_SCOPE_FORBIDDEN,
- )
+ msg = f"The read_scope {requested!r} does not lie under this caller's own id, the only scope its token may read."
+ raise RunnerAuthError(msg).with_error_code(CoreCode.AUTH_FORBIDDEN).with_params(requirement=READ_SCOPE_UNDER_CALLER_REQUIREMENT)
return requested
@@ -195,6 +201,10 @@ class _RunScopes(NamedTuple):
read_scope: str | None
+# The run request's field naming the scope a run may read, which a refusal of the scopes it resolves to names.
+_READ_SCOPE_FIELD = "read_scope"
+
+
def _resolve_run_scopes(request: Request, *, extras: PipelineApiExtras) -> _RunScopes:
"""Resolve the run's storage and read scopes, and refuse a pair the run could not work under.
@@ -207,18 +217,14 @@ def _resolve_run_scopes(request: Request, *, extras: PipelineApiExtras) -> _RunS
read_scope = _resolve_read_scope(request, requested=extras.read_scope)
if read_scope is not None:
if storage_scope == LOCAL_STORAGE_SCOPE:
- raise_validation_error(
- message=f"A run with a read_scope must pass its own storage_scope, not the local sentinel {LOCAL_STORAGE_SCOPE!r}.",
- error_type=ErrorType.INVALID_READ_SCOPE,
- )
+ msg = f"A run with a read_scope must pass its own storage_scope, not the local sentinel {LOCAL_STORAGE_SCOPE!r}."
+ raise RunnerRequestError(msg, field=_READ_SCOPE_FIELD)
try:
validate_storage_scope_within_read_scope(storage_scope=storage_scope, read_scope=read_scope)
except ValueError as exc:
origin = "sent" if extras.read_scope is not None else "defaulted to the caller's id"
- raise_validation_error(
- message=f"{exc} The read_scope {read_scope!r} was {origin}, and the storage_scope is {storage_scope!r}.",
- error_type=ErrorType.INVALID_READ_SCOPE,
- )
+ msg = f"{exc} The read_scope {read_scope!r} was {origin}, and the storage_scope is {storage_scope!r}."
+ raise RunnerRequestError(msg, field=_READ_SCOPE_FIELD) from exc
return _RunScopes(storage_scope=storage_scope, read_scope=read_scope)
@@ -350,7 +356,7 @@ class ApiRunner(PipelexMTHDSProtocol):
"""Execute a method synchronously, dispatching by the resolved `orchestration_mode`.
Symmetric with `start`: the effective `orchestration_mode` is resolved FIRST (config default
- + optional per-request override, so a forbidden override is refused with a 403 before any
+ + optional per-request override, so a forbidden override is refused with a 422 before any
library load), then the run is dispatched through the hub's `OrchestratorRegistry` instead
of the boot-global pipe-run slot. `direct` runs in-process on this agnostic base; a
`temporal` mode dispatches the whole job to a worker and awaits it. A mode with no registered
@@ -370,7 +376,7 @@ class ApiRunner(PipelexMTHDSProtocol):
(`PipelineApiExtras.orchestration_mode`).
"""
# Resolve the effective orchestration mode FIRST — a per-request override the deployment
- # policy forbids is refused (403) here, before any library load / run registration. Mirrors start().
+ # policy forbids is refused (422) here, before any library load / run registration. Mirrors start().
api_config = get_api_config()
orchestration_mode = resolve_orchestration_mode(requested_orchestration_mode, config=api_config)
orchestrator = get_orchestrator_registry().get_optional(mode=orchestration_mode)
@@ -424,7 +430,7 @@ class ApiRunner(PipelexMTHDSProtocol):
`/start` is genuinely fire-and-forget, so it is HONEST about its capability: the resolved
mode's orchestrator is looked up and its `supports_fire_and_forget` checked BEFORE any
library load. A blocking-only orchestrator (the in-process `direct` base) cannot honor
- async delivery, so it is refused with a 400 (`START_REQUIRES_ASYNC_ORCHESTRATION`) — use
+ async delivery, so it is refused with a 501 (`runtime.unsupported`) — use
`/execute` — rather than silently running blocking and acking. A mode with no registered
orchestrator fails loud with `MissingOrchestratorError` (carrying the install hint), also
before any library load.
@@ -443,7 +449,7 @@ class ApiRunner(PipelexMTHDSProtocol):
is an API-layer extra threaded into `RunMetadata.request_id` for log
correlation, so it reaches the job a worker is handed. `requested_orchestration_mode` is the optional per-request backend override
(`PipelineApiExtras.orchestration_mode`); it is resolved against the deployment's
- `api.toml` policy and a forbidden override is refused with a 403.
+ `api.toml` policy and a forbidden override is refused with a 422.
"""
if extra:
# Nothing on the wire reaches `extra`: the route parses the extras itself and passes them by name, so a
@@ -451,10 +457,10 @@ class ApiRunner(PipelexMTHDSProtocol):
msg = f"ApiRunner defines no extension args beyond its named ones; got {sorted(extra)}."
raise PipelexUnexpectedError(msg)
# Resolve the effective orchestration mode FIRST — a per-request override the deployment
- # policy forbids is refused (403) here. Then look up the orchestrator and check its async
+ # policy forbids is refused (422) here. Then look up the orchestrator and check its async
# capability: `/start` is fire-and-forget, so a blocking-only orchestrator (direct on the
- # agnostic base) is refused HONESTLY with a 400 instead of silently running blocking and
- # acking. Both gates run BEFORE pipeline_run_setup so a doomed request never loads a library.
+ # agnostic base) is refused HONESTLY with a 501 `runtime.unsupported` instead of silently
+ # running blocking and acking. Both gates run BEFORE pipeline_run_setup so a doomed request never loads a library.
api_config = get_api_config()
orchestration_mode = resolve_orchestration_mode(requested_orchestration_mode, config=api_config)
orchestrator = get_orchestrator_registry().get_optional(mode=orchestration_mode)
@@ -465,7 +471,7 @@ class ApiRunner(PipelexMTHDSProtocol):
f"Orchestration mode '{orchestration_mode}' cannot honor fire-and-forget delivery: /start requires an "
f"async-capable orchestration, and this deployment has none. Use /execute (synchronous) instead."
)
- raise_bad_request(msg, error_type=ErrorType.START_REQUIRES_ASYNC_ORCHESTRATION)
+ raise AsyncExecutionNotEnabledError(msg)
await self._ensure_served_method_requirements_met()
created_at = get_current_iso_timestamp()
pipelex_inputs: PipelineInputs | WorkingMemory | None = cast("PipelineInputs | WorkingMemory | None", inputs)
@@ -580,7 +586,7 @@ class ApiRunner(PipelexMTHDSProtocol):
"""Validate MTHDS bundles, returning the verdict as a value (the route maps it to a 200).
Mode-aware, mirroring `start`: the effective `orchestration_mode` is resolved FIRST (config
- default + optional per-request override, so a forbidden override is refused with a 403
+ default + optional per-request override, so a forbidden override is refused with a 422
before any library load), then dispatched through the hub's `BundleValidatorRegistry`.
`direct` validates in-process on this agnostic base; a `temporal` mode dispatches the
whole job to a worker (`pipelex-temporal`). A mode with no registered validator fails
@@ -617,7 +623,7 @@ class ApiRunner(PipelexMTHDSProtocol):
would fall back to: nothing lists or erases what a validation would leave under that prefix.
"""
# Resolve the effective mode FIRST — a per-request override the deployment policy forbids
- # is refused (403) here, before any validator dispatch / library load. Mirrors start().
+ # is refused (422) here, before any validator dispatch / library load. Mirrors start().
api_config = get_api_config()
orchestration_mode = resolve_orchestration_mode(requested_orchestration_mode, config=api_config)
validator = get_bundle_validator_registry().get_optional(mode=orchestration_mode)
@@ -698,20 +704,18 @@ def _decode_body(body: bytes) -> dict[str, Any]:
Parsing as plain data is not enough on its own: a marker accepted as an ordinary dict comes
back to life the moment the runtime round-trips the inputs through kajson. So the caller,
`_parse_request`, refuses a key a kajson decoder treats as a marker at any depth with a 422
- `ReservedObjectKey` (`_refuse_reserved_object_keys`), once the run's extras are bound for the
- security event that refusal logs.
+ `pipelex.security.reserved_key` (`_refuse_reserved_object_keys`), once the run's extras are bound
+ for the security event that refusal logs.
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`,
+ `request.malformed` 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.
+ and one that is not JSON. A body that parses to anything but an object is a 422 `request.invalid`.
"""
decoded = decode_json_body(body)
if not isinstance(decoded, dict):
- raise_validation_error(
- message="Request body must be a JSON object",
- error_type=ErrorType.INVALID_JSON,
- )
+ msg = "Request body must be a JSON object"
+ raise RunnerRequestError(msg, field=WHOLE_BODY_FIELD)
return cast("dict[str, Any]", decoded)
@@ -719,45 +723,18 @@ def _refuse_reserved_object_keys(request_data: dict[str, Any]) -> None:
"""Refuse a body holding an object key a kajson decoder reads as a class marker, at any depth, with a 422.
The refusal is a security rule's, `pipelex.security.reserved_key`, so it logs a security event, which names the
- kind of thing refused and never the key.
+ kind of thing refused and never the key. The problem's `keys` parameter names the key the caller sent, bounded as
+ the correlation fields are.
"""
reserved_key = _find_reserved_object_key(request_data)
if reserved_key is not None:
- # The key is the caller's, as long as the body allows (any `__kajson…` key matches), and the
- # detail is logged as a field: echo it bounded, as the correlation fields are.
+ # The key is the caller's, as long as the body allows (any `__kajson…` key matches): echo it bounded.
shown_key = reserved_key if len(reserved_key) <= _MAX_CORRELATION_FIELD_LEN else f"{reserved_key[:_MAX_CORRELATION_FIELD_LEN]}…"
- raise_validation_error(
- message=(
- f"Request body contains the reserved object key '{shown_key}'. A run request is plain JSON: "
- f"no object in it may carry a '__class__' or '__module__' key, or a key starting with '{_RESERVED_OBJECT_KEY_PREFIX}'."
- ),
- error_type=ErrorType.RESERVED_OBJECT_KEY,
- security_refusal=ApiSecurityRefusal(code=PipelexErrorCode.SECURITY_RESERVED_KEY, error_type=ErrorType.RESERVED_OBJECT_KEY),
+ msg = (
+ f"Request body contains the reserved object key '{shown_key}'. A run request is plain JSON: "
+ f"no object in it may carry a '__class__' or '__module__' key, or a key starting with '{_RESERVED_OBJECT_KEY_PREFIX}'."
)
-
-
-# The `error_type` a 422 on one extras field carries. A field absent from this map
-# (`pipeline_run_id`, `orchestration_mode`) answers with the generic `ValidationError`.
-_EXTRAS_FIELD_ERROR_TYPES: dict[str, ErrorType] = {
- "callback_urls": ErrorType.INVALID_CALLBACK_URLS,
- "storage_scope": ErrorType.INVALID_STORAGE_SCOPE,
- "read_scope": ErrorType.INVALID_READ_SCOPE,
- "analytics_groups": ErrorType.INVALID_ANALYTICS_GROUPS,
-}
-
-
-def _extras_error_type(exc: ValidationError) -> ErrorType:
- """Classify an extras failure by the field that failed, so a client can branch on `error_type`.
-
- Every extras failure used to answer `InvalidCallbackUrls`, including a traversal in
- `storage_scope` on a request that carried no callback at all. A body failing on
- more than one field gets the generic `ValidationError`: naming one of them would
- send the caller to fix that field and leave the other one for the next request.
- """
- failed_fields = {str(error["loc"][0]) for error in exc.errors() if error["loc"]}
- if len(failed_fields) != 1:
- return ErrorType.VALIDATION_ERROR
- return _EXTRAS_FIELD_ERROR_TYPES.get(failed_fields.pop(), ErrorType.VALIDATION_ERROR)
+ raise ReservedObjectKeyError(msg, keys=[shown_key])
def _validate_extras(request_data: dict[str, Any]) -> PipelineApiExtras:
@@ -768,41 +745,16 @@ def _validate_extras(request_data: dict[str, Any]) -> PipelineApiExtras:
second list to keep in step. Such a list would drop a forgotten key SILENTLY, and for
`storage_scope` that is worse than an error: the run falls back to the caller's own id
and writes to the wrong prefix while reporting success.
+
+ A field the model refuses is a 422 `request.invalid` with one item per refused field (`refused_request_error`),
+ except a callback URL the SSRF rules refuse, which is answered as its own security refusal,
+ `security.input_url_refused`, whatever else failed (`callback_url_refusal_in`).
"""
try:
return PipelineApiExtras.model_validate(request_data)
except ValidationError as exc:
- raise_validation_error(
- message=str(exc),
- error_type=_extras_error_type(exc),
- security_refusal=_security_refusal_in(exc),
- )
-
-
-def _security_refusal_in(exc: ValidationError) -> ApiSecurityRefusal | None:
- """The refusal of a security rule an extras validator raised, such as a callback URL aimed at a private address.
-
- A validator's error rides its entry's context, where pydantic keeps the exception it raised. A body that also fails
- on another field is still the security rule's refusal, so the first one found is reported whatever else failed.
- """
- for error in exc.errors():
- refusal = security_refusal_of(error=error.get("ctx", {}).get("error"))
- if refusal is not None:
- return refusal
- return None
-
-
-def _validated_run_extras_or_none(request_data: dict[str, Any]) -> dict[str, str] | None:
- """The body's `analytics_groups` when they pass the runtime's rules on their own, else `None`.
-
- Read before anything else is refused, so that the security event of a refusal before the extras are validated,
- such as a reserved object key or a callback URL, still names whose request it was, with values the runtime's
- own rules accepted.
- """
- try:
- return PipelineApiExtras.model_validate({"analytics_groups": request_data.get("analytics_groups")}).analytics_groups
- except ValidationError:
- return None
+ faults = exc.errors()
+ raise (callback_url_refusal_in(faults=faults) or refused_request_error(faults=faults, located_by_request_part=False)) from exc
# Per-field bound applied at the request.state binding site so an oversized
@@ -853,8 +805,9 @@ async def _parse_request(request: Request) -> _ParsedRunRequest:
"""
body = await request.body()
request_data = _decode_body(body)
- # The run's opaque extras, for the security event a refusal of this request logs before any run carries them.
- request.state.run_extras = _validated_run_extras_or_none(request_data)
+ # The run's opaque extras, read before anything else is refused, so that the security event a refusal of this request
+ # logs before any run carries them, a reserved object key or a callback URL, still names whose request it was.
+ bind_run_extras(request=request, body=request_data)
_refuse_reserved_object_keys(request_data)
# Bind body-derived correlation identifiers onto `request.state` as soon as
# the raw dict is in hand — before `_validate_extras` or `from_body`, so a
@@ -870,11 +823,11 @@ async def _parse_request(request: Request) -> _ParsedRunRequest:
run_request = RunRequest.from_body(request_data)
except ValidationError as exc:
# A body whose fields fail Pydantic coercion is a caller mistake, not a server fault, so it maps to
- # a 422 rather than escaping to the generic-500 fallback. A body naming its run source wrongly, or
- # none, is refused by `from_body` as a `PipelexRequestError` instead, which needs no catch here: it
- # is a `PipelexError` carrying `request.invalid` or `request.unsupported`, and the global handler
- # answers it with its code.
- raise_validation_error(message=str(exc))
+ # a 422 `request.invalid`, one item per refused field, rather than escaping to the generic-500 fallback.
+ # A body naming its run source wrongly, or none, is refused by `from_body` as a `PipelexRequestError`
+ # instead, which needs no catch here: it is a `PipelexError` carrying `request.invalid` or
+ # `request.unsupported`, and the global handler answers it with its code.
+ raise refused_request_error(faults=exc.errors(), located_by_request_part=False) from exc
return _ParsedRunRequest(run_request=run_request, extras=extras, body=body)
@@ -898,7 +851,8 @@ async def _request_method_of(*, run_request: RunRequest, body: bytes, blob_store
The files `resources` sends join the tree. Every tree is recorded in the blob store once the Python gate passed.
"""
if run_request.bundle_b64 is not None and run_request.files is not None:
- raise_validation_error(message="Provide either bundle_b64 or files, not both", error_type=ErrorType.INVALID_BUNDLE)
+ msg = "Provide either bundle_b64 or files, not both"
+ raise RunnerRequestError(msg, field=BUNDLE_FIELD)
request_method: RequestMethod | None
if run_request.bundle_b64 is not None:
request_method = await read_archive_method(bundle_b64=run_request.bundle_b64)
@@ -911,7 +865,7 @@ async def _request_method_of(*, run_request: RunRequest, body: bytes, blob_store
return None
request_method = with_resources(request_method=request_method, resources=decode_bundle_resources(resources=run_request.resources))
ensure_method_holds_a_bundle(request_method=request_method, label="This method")
- ensure_python_allowed(request_method=request_method, label="This method")
+ ensure_python_allowed(request_method=request_method, label="This method", origin=CustomCodeOrigin.BUNDLE)
await record_request_method(request_method=request_method, blob_store=blob_store)
return request_method
@@ -933,7 +887,7 @@ async def _run_source(*, run_request: RunRequest, body: bytes, blob_scope: str)
the runtime's `submitted_files`.
Security gate: a method shipping custom Python (`.py`) is only honored on a sandbox-hosted deployment, refused with
- a 403 before anything is written (`ensure_python_allowed`).
+ a 501 before anything is written (`ensure_python_allowed`).
"""
method_provenance: MethodProvenance | None = None
method_label = REQUEST_METHOD_LABEL
@@ -941,7 +895,7 @@ async def _run_source(*, run_request: RunRequest, body: bytes, blob_scope: str)
fetched = await asyncio.to_thread(fetched_method, run_request.method_ref)
request_method: RequestMethod | None = fetched.request_method
ensure_method_holds_a_bundle(request_method=fetched.request_method, label=f"Method package {fetched.label}")
- ensure_python_allowed(request_method=fetched.request_method, label=f"Method package {fetched.label}")
+ ensure_python_allowed(request_method=fetched.request_method, label=f"Method package {fetched.label}", origin=CustomCodeOrigin.PACKAGE)
method_provenance = fetched.provenance
method_label = fetched.label
else:
@@ -976,14 +930,19 @@ async def _run_source(*, run_request: RunRequest, body: bytes, blob_scope: str)
# `JSONResponse` built from a trimmed dump, so FastAPI never serializes through this model —
# it is purely what the artifact publishes, and it must match `apply_tokens_usage_wire_shape`.
response_model=PipelexApiExecuteResponse,
- # On top of the composite router's shared 401/413/422/500: the policy 403s (a forbidden
- # per-request `orchestration_mode` override, the custom-code sandbox gate, the structures
- # refusal on a bundle or a fetched package), the `method_ref` package-not-found 404, and the provider
- # rate-limit passthrough (429) — `/execute` is the only route that runs inference, so it is
- # the only one that can be rate-limited upstream. NO 409: unlike `/start`, `/execute` takes
- # no client-supplied `pipeline_run_id` (the base runner generates one per call), so a caller
- # cannot collide with an in-flight run.
- responses={403: PROBLEM_403_RUN_POLICY, 404: PROBLEM_404_METHOD_PACKAGE, 429: PROBLEM_429},
+ # On top of the composite router's shared 401/413/422/500: a `read_scope` outside the caller's own (403), the
+ # `method_ref` package-not-found 404, the provider rate-limit passthrough (429) — `/execute` is the only route that runs inference, so
+ # it is the only one that can be rate-limited upstream — and the custom-code sandbox gate's 501 on a
+ # bundle or a fetched package. NO 409: unlike `/start`, `/execute` takes no client-supplied
+ # `pipeline_run_id` (the base runner generates one per call), so a caller cannot collide with an
+ # in-flight run. Its 500 names, beside the shared one's codes, a damaged blob a `files` map names by hash.
+ responses={
+ 403: PROBLEM_403_READ_SCOPE,
+ 404: PROBLEM_404_METHOD_PACKAGE,
+ 429: PROBLEM_429,
+ 500: PROBLEM_500_HELD_BLOBS,
+ 501: PROBLEM_501_RUN_POLICY,
+ },
# Documented body = the protocol's RunRequest plus THIS server's own
# `orchestration_mode` extension (the route honors a per-request override). The
# body is read through the raw Request (plain JSON with the reserved-key
@@ -1052,19 +1011,19 @@ async def execute(request: Request) -> JSONResponse:
# On top of the composite router's shared 401/413/422/500. `/start` is fire-and-forget, so
# its extra failures are all about the backend's ability to honor that and about the
# client-supplied run id it (alone) accepts:
- # 400 — the resolved orchestrator is blocking-only (the in-process `direct` base): refuse
- # honestly rather than block-and-ack. Use `/execute`.
- # 403 — a per-request `orchestration_mode` override the deployment forbids, or the
- # custom-code sandbox gate on a bundle or a fetched package.
+ # 403 — a `read_scope` that does not lie under the caller's own id, on a `jwt` deployment.
# 404 — a `method_ref` whose repository holds no matching package.
# 409 — the submitted `pipeline_run_id` is still registered for an in-flight run.
- # 501 — an async-capable deployment whose async execution is not enabled.
+ # 500 — beside the shared one's codes, a damaged blob a `files` map names by hash.
+ # 501 — the resolved orchestrator is blocking-only (the in-process `direct` base), or the
+ # deployment's async execution is not enabled: refuse honestly rather than block-and-ack,
+ # use `/execute`; or the custom-code sandbox gate on a bundle or a fetched package.
responses={
- 400: PROBLEM_400_START_REQUIRES_ASYNC,
- 403: PROBLEM_403_RUN_POLICY,
+ 403: PROBLEM_403_READ_SCOPE,
404: PROBLEM_404_METHOD_PACKAGE,
409: PROBLEM_409_DUPLICATE_RUN,
- 501: PROBLEM_501_ASYNC_NOT_ENABLED,
+ 500: PROBLEM_500_HELD_BLOBS,
+ 501: PROBLEM_501_START,
},
# Documented body = the protocol's StartRequest plus THIS server's own
# extensions (callback_urls) — the protocol model no longer advertises
@@ -1096,8 +1055,8 @@ async def start(
sets `FIRE_AND_FORGET` delivery and checks the resolved orchestrator can honor it. A Temporal
deployment (`orchestration_mode = "temporal"`) enqueues the run and returns immediately with a
`workflow_id`. On the orchestrator-agnostic base (`orchestration_mode = "direct"`, the default)
- the in-process orchestrator is blocking-only, so `/start` is HONEST: it refuses with a `400`
- (`StartRequiresAsyncOrchestration`) — use `/execute` — rather than silently blocking and acking.
+ the in-process orchestrator is blocking-only, so `/start` is HONEST: it refuses with a `501`
+ (`runtime.unsupported`) — use `/execute` — rather than silently blocking and acking.
The completion callback (`callback_urls` / storage delivery) fires on the async path.
"""
run_request, extras, body = parsed
diff --git a/api/pipelex_api/routes/pipelex/resolve.py b/api/pipelex_api/routes/pipelex/resolve.py
index 0d2239f67..7eeca28fa 100644
--- a/api/pipelex_api/routes/pipelex/resolve.py
+++ b/api/pipelex_api/routes/pipelex/resolve.py
@@ -8,7 +8,8 @@ from pipelex.pipeline.exceptions import ValidateBundleError
from pydantic import BaseModel, Field
from pipelex_api.json_body import JsonBodyRoute
-from pipelex_api.openapi_responses import PROBLEM_403_METHOD_PYTHON_POLICY, PROBLEM_404_METHOD_PACKAGE, PROBLEM_501_METHOD_REF
+from pipelex_api.openapi_responses import PROBLEM_403_READ_SCOPE, PROBLEM_404_METHOD_PACKAGE, PROBLEM_500_HELD_BLOBS, PROBLEM_501_RUN_POLICY
+from pipelex_api.problem_view import problem_view_of
from pipelex_api.routes.pipelex.crate_ops import CrateInvalidReport, ResolvedMethod, invalid_crate_report_response, project_resolved_method
from pipelex_api.schemas.models import MethodTreeRequest
@@ -37,9 +38,9 @@ ResolveResponse = Annotated[Union[ResolveValidReport, CrateInvalidReport], Field
@router.post(
"/resolve",
response_model=ResolveResponse,
- # On top of the composite router's shared 401/413/422/500: the Python policy's 403s, the
- # `method_ref` package-not-found 404, and the registry-form `method_ref` no registry resolves yet.
- responses={403: PROBLEM_403_METHOD_PYTHON_POLICY, 404: PROBLEM_404_METHOD_PACKAGE, 501: PROBLEM_501_METHOD_REF},
+ # On top of the composite router's shared 401/413/422/500: a `read_scope` outside the caller's own, the
+ # `method_ref` package-not-found 404, a damaged blob a hash entry names, and the Python policy's 501.
+ responses={403: PROBLEM_403_READ_SCOPE, 404: PROBLEM_404_METHOD_PACKAGE, 500: PROBLEM_500_HELD_BLOBS, 501: PROBLEM_501_RUN_POLICY},
# NOT tagged `x-mthds-protocol`: the MTHDS Protocol is the five operations `execute`, `start`,
# `validate`, `models`, `version`. `/resolve` is a Pipelex API extension. The *artifact* it
# emits — the normalized library crate — IS standard-owned (the MTHDS Library Crate Format), so
@@ -59,17 +60,20 @@ async def resolve_mthds(request: Request, request_data: MethodTreeRequest) -> JS
- **Valid verdict (200, `is_valid: true`):** the crate on the valid arm.
- **Invalid verdict (200, `is_valid: false`):** the library could not be parsed, loaded, or
- validated — `validation_errors[]` from pipelex's one shared builder.
+ validated — `errors[]`, one problem item per error.
- **No verdict (non-2xx):** a malformed request body (neither or both method selectors) is a
- request-shape 422; a `files` map that is not a method tree is a 422 `InvalidMethodFiles`, and
- hash entries this runner does not hold one 422 `MissingBlobs`; custom Python on a deployment
- that is not sandbox-hosted, or a Python structure class, is a 403; a registry-form `method_ref`
- is a 501 until server-side method registry resolution exists; auth is 401/403; server fault is
- 5xx. All RFC 7807 `application/problem+json` via the global handlers.
+ request-shape 422 `request.invalid`; a `files` map that is not a method tree is a 422
+ `method.package_invalid`, and hash entries this runner does not hold a 422
+ `request.blobs_missing`; custom Python on a deployment that is not sandbox-hosted is a 501
+ `pipelex.deployment.custom_code_requires_sandbox`, and a Python structure class a 422
+ `pipelex.deployment.python_structures_refused`; a registry-form `method_ref` is a 422
+ `request.unsupported` until server-side method registry resolution exists; auth is 401/403;
+ server fault is 5xx. All `application/problem+json` documents with a registry `code`, via the
+ global handlers.
"""
outcome = await project_resolved_method(request=request, request_data=request_data, project=_crate_response)
if isinstance(outcome, ValidateBundleError):
- return invalid_crate_report_response(outcome)
+ return invalid_crate_report_response(outcome, view=problem_view_of(request))
return outcome
diff --git a/api/pipelex_api/routes/pipelex/tools.py b/api/pipelex_api/routes/pipelex/tools.py
index b6a344831..449afda62 100644
--- a/api/pipelex_api/routes/pipelex/tools.py
+++ b/api/pipelex_api/routes/pipelex/tools.py
@@ -6,7 +6,7 @@ import pipelex_tools
from fastapi import APIRouter
from pydantic import BaseModel, Field, field_validator
-from pipelex_api.errors import raise_validation_error
+from pipelex_api.exceptions import RunnerRequestError
from pipelex_api.json_body import JsonBodyRoute
from pipelex_api.limits import MAX_MTHDS_FILE_BYTES
@@ -102,10 +102,11 @@ async def format_mthds(request_data: FormatRequest) -> FormatResponse:
"""Format one .mthds file with the canonical MTHDS formatter.
Syntax errors return 200 with diagnostics and unchanged content. Malformed
- formatter options are caller input errors and return RFC 7807 422.
+ formatter options are caller input errors and return a 422 `request.invalid`
+ naming `options`.
"""
try:
result = pipelex_tools.format_mthds(request_data.content, options=request_data.options)
except ValueError as exc:
- raise_validation_error(str(exc))
+ raise RunnerRequestError(str(exc), field="options") from exc
return FormatResponse.model_validate(result)
diff --git a/api/pipelex_api/routes/pipelex/validate.py b/api/pipelex_api/routes/pipelex/validate.py
index ec7cdcc40..dd3e93719 100644
--- a/api/pipelex_api/routes/pipelex/validate.py
+++ b/api/pipelex_api/routes/pipelex/validate.py
@@ -1,15 +1,17 @@
from enum import StrEnum
-from typing import Annotated, Literal, Self, Union
+from typing import Annotated, Any, Literal, Self, Union
from fastapi import APIRouter, Request
from fastapi.responses import JSONResponse
-from pipelex.base_exceptions import ValidationErrorItem
+from mthds.protocol.problem.models import ProblemItem
from pipelex.errors.bundle_validation_failure import BundleValidationFailure
+from pipelex.errors.problem import ProblemView, caller_view_of
from pipelex.pipe_machinery.pipe_factory import PipeFactory
from pipelex.pipeline.exceptions import MethodEntryError, ValidateBundleError
from pipelex.pipeline.input_form import PipeInputFormDescriptor, PipeOutputFormDescriptor
from pipelex.pipeline.method_entry import MethodEntry
-from pipelex.pipeline.validation_render import format_validate_markdown, render_invalid_validation_markdown
+from pipelex.pipeline.validation_errors import warning_problem_items
+from pipelex.pipeline.validation_render import format_validate_markdown, render_invalid_verdict_markdown
from pipelex.pipeline.validation_report import PipelexValidationReport
from pipelex.system.storage_scope import validate_read_scope
from pipelex.tools.typing.pydantic_utils import empty_list_factory_of
@@ -17,10 +19,12 @@ from pydantic import BaseModel, Field, field_validator, model_validator
from pipelex_api.bundle_resources import decode_bundle_resources
from pipelex_api.exception_handlers import problem_response
+from pipelex_api.exceptions import RequestFieldConflictError
from pipelex_api.json_body import JsonBodyRoute
from pipelex_api.method_tree_request import RequestMethod, select_tree_entry, written_method
from pipelex_api.middleware import request_id_of
-from pipelex_api.openapi_responses import PROBLEM_403_RUN_POLICY, PROBLEM_404_METHOD_PACKAGE
+from pipelex_api.openapi_responses import PROBLEM_403_READ_SCOPE, PROBLEM_404_METHOD_PACKAGE, PROBLEM_500_HELD_BLOBS, PROBLEM_501_RUN_POLICY
+from pipelex_api.problem_view import problem_view_of
from pipelex_api.routes.pipelex.method_selection import select_request_method
from pipelex_api.routes.pipelex.pipeline import ApiRunner, bound_read_scope, get_request_user_id
from pipelex_api.schemas.models import RESOURCES_FIELD_DESCRIPTION, CallerAnalyticsGroupsMixin, MthdsContentsRequest
@@ -79,9 +83,9 @@ class ValidateRequest(MthdsContentsRequest, CallerAnalyticsGroupsMixin):
`mthds_sources`, when provided, pairs each `mthds_contents[i]` with a logical source (e.g. the
file's path relative to the submitted directory). The runner threads it onto
- `blueprint.source`, so the structured `validation_errors` on a 200 `InvalidReport` carry a real
- `source` the client maps back to the owning file — without it the in-memory load path leaves
- `source` null and cross-file diagnostics misfire. Omit it and behavior is unchanged.
+ `blueprint.source`, so the problem items in `errors` on a 200 `InvalidReport` carry a real
+ `location.file` the client maps back to the owning file — without it the in-memory load path
+ leaves the file unknown and cross-file diagnostics misfire. Omit it and behavior is unchanged.
"""
mthds_sources: list[str] | None = Field(
@@ -119,7 +123,8 @@ class ValidateRequest(MthdsContentsRequest, CallerAnalyticsGroupsMixin):
"`/start`). An OPEN string token: `direct` validates in-process; a `temporal` mode dispatches the whole "
"job to a worker; any plugin-provided token is accepted and an unregistered one is refused at dispatch. "
"Honored only when the deployment sets `allow_request_orchestration_mode_override = true` in its `api.toml`; "
- "otherwise a token that differs from the deployment default is refused with a 403. Omitted → the default."
+ "otherwise a token that differs from the deployment default is refused with a 422 "
+ "`pipelex.deployment.orchestration_override_forbidden`. Omitted → the default."
),
)
@@ -148,17 +153,17 @@ class ValidateRequest(MthdsContentsRequest, CallerAnalyticsGroupsMixin):
# two is a request-shape bug → 422.
if self.mthds_sources is not None and self.mthds_contents is None:
msg = "mthds_sources accompanies inline mthds_contents; the files of a method tree are named by their tree paths"
- raise ValueError(msg)
+ raise RequestFieldConflictError(msg, field="mthds_sources")
# `resources` are the files the inline contents' steps read; a `method_ref`'s files are the package's own.
if self.resources and self.method_ref is not None:
msg = "resources accompany inline mthds_contents; a method_ref's files are the package's own"
- raise ValueError(msg)
+ raise RequestFieldConflictError(msg, field="resources")
# A caller-supplied length mismatch is a request-shape bug → caught here as a 422.
# Without this guard it reaches the runtime's `validate_bundle`, which treats the
# mismatch as an internal host error (500) — the wrong status for caller input.
if self.mthds_sources is not None and self.mthds_contents is not None and len(self.mthds_sources) != len(self.mthds_contents):
msg = "mthds_sources, when provided, must be a per-item source list matching mthds_contents in length"
- raise ValueError(msg)
+ raise RequestFieldConflictError(msg, field="mthds_sources")
return self
@@ -197,6 +202,10 @@ class ValidReport(PipelexValidationReport):
discriminant. The extras exist for HTTP clients only (the webapp reads back `mthds_contents`);
they are NOT part of the canonical report and no in-process consumer should depend on them.
+ `warnings` is re-declared as problem items: the canonical report holds the advisory findings as the validation
+ items the local channels render, and the wire carries each as the problem item its type's code makes
+ (`pipelex.pipeline.validation_errors.warning_problem_items`), the item shape `errors` has on the invalid arm.
+
Two inherited fields are deliberately re-declared: `input_form` and `output_form`. The canonical
report requires both (a backend that forgets to derive one must fail loudly rather than ship an
empty view), but on the wire each is an opt-in structured view gated by the request's `views` —
@@ -214,6 +223,13 @@ class ValidReport(PipelexValidationReport):
"`.mthds` bundles in tree path order."
),
)
+ warnings: list[ProblemItem] = Field( # type: ignore[assignment] # pyright: ignore[reportIncompatibleVariableOverride]
+ default_factory=empty_list_factory_of(ProblemItem),
+ description=(
+ "Advisory findings on the valid bundle, one problem item each, with the code the finding's type names: they "
+ "never flip `is_valid`. The same item shape as the invalid arm's `errors`."
+ ),
+ )
message: str = Field(default="MTHDS content validated successfully", description="Status message")
default_pipe_ref: str | None = Field(
default=None,
@@ -222,7 +238,7 @@ class ValidReport(PipelexValidationReport):
"selector-less run of THIS request would execute. For a method tree (`files` or a `method_ref`) it is "
"the tree's entry pipe by the MTHDS protocol's rule: the `main_pipe` of the `METHODS.toml` at its root, "
"else the one `main_pipe` its bundles declare. For inline `mthds_contents` it is the closure's primary "
- "blueprint's `main_pipe` qualified by its domain. `null` when no entry pipe is determined, in which case a "
+ "blueprint's `main_pipe` qualified by its domain. Absent when no entry pipe is determined, in which case a "
"selector-less run would be refused too."
),
)
@@ -260,19 +276,23 @@ class InvalidReport(BaseModel):
`problem+json` 422/5xx is reserved for the no-verdict conditions (malformed request body,
`mthds_sources` length mismatch, auth, server fault). The structural artifacts
(`bundle_blueprint`, `pipe_io_contracts`, `graph_spec`, `validated_pipes`) do not exist when
- load/parse/wiring failed, so this arm omits them and carries only the per-error diagnostics
- plus the runnability facts. The `input_form` and `output_form` views follow them into absence for
- the same reason — both derive from a crate that was never assembled — so neither is declared here and `views`
- has no effect on this arm (unlike `rendered_markdown`, which rides both arms because failure
+ load/parse/wiring failed, so this arm omits them and carries only the per-error diagnostics,
+ as the problem items of the verdict's problem (`errors`), plus the runnability facts. The
+ `input_form` and `output_form` views follow them into absence for the same reason — both derive
+ from a crate that was never assembled — so neither is declared here and `views` has no effect
+ on this arm (unlike `rendered_markdown`, which rides both arms because failure
text is exactly what a human surface wants).
"""
is_valid: Literal[False] = False
"""Discriminant of the invalid arm (mirrors `ValidReport`/`PipelexValidationReport`'s `Literal[True]`)."""
- validation_errors: list[ValidationErrorItem] = Field(
- default_factory=empty_list_factory_of(ValidationErrorItem),
- description="Per-error diagnostics, built by pipelex's one shared builder — non-empty on every invalid verdict.",
+ errors: list[ProblemItem] = Field(
+ default_factory=empty_list_factory_of(ProblemItem),
+ description=(
+ "One problem item per error, each with its own code, its parameters and its location — non-empty on every "
+ "invalid verdict. The items of the verdict's problem, as a refusal's `errors` carry them."
+ ),
)
pending_signatures: list[str] = Field(
default_factory=list,
@@ -286,7 +306,7 @@ class InvalidReport(BaseModel):
default=None,
description=(
"Opt-in Pipelex-API presentation extra: a server-rendered Markdown view of the invalid verdict's "
- "`validation_errors`, present only when the request's `render` includes `markdown`. Absent by default."
+ "errors, present only when the request's `render` includes `markdown`. Absent by default."
),
)
@@ -299,13 +319,12 @@ ValidationResponse = Annotated[Union[ValidReport, InvalidReport], Field(discrimi
@router.post(
"/validate",
response_model=ValidationResponse,
- # On top of the composite router's shared 401/413/422/500: the policy 403s (the
- # `orchestration_mode` override gate it shares with `/start`, plus — for a `method_ref` —
- # the custom-code sandbox gate) and the `method_ref`
- # package-not-found 404. Note what is deliberately NOT here: an *invalid bundle* is a
- # produced verdict on a 200, never a 4xx — and a selector-resolution failure is a non-2xx
- # problem+json, never an `is_valid: false` verdict.
- responses={403: PROBLEM_403_RUN_POLICY, 404: PROBLEM_404_METHOD_PACKAGE},
+ # On top of the composite router's shared 401/413/422/500: a `read_scope` outside the caller's own, the custom-code
+ # sandbox gate's 501 and the `method_ref` package-not-found 404. Note what is deliberately NOT here: an *invalid
+ # bundle* is a produced verdict on a 200, never a 4xx — and a selector-resolution failure is a
+ # non-2xx problem+json, never an `is_valid: false` verdict. Its 500 names, beside the shared one's codes, a damaged
+ # blob a `files` map names by hash.
+ responses={403: PROBLEM_403_READ_SCOPE, 404: PROBLEM_404_METHOD_PACKAGE, 500: PROBLEM_500_HELD_BLOBS, 501: PROBLEM_501_RUN_POLICY},
openapi_extra={"x-mthds-protocol": True},
)
async def validate_mthds(request: Request, request_data: ValidateRequest) -> JSONResponse:
@@ -336,24 +355,25 @@ async def validate_mthds(request: Request, request_data: ValidateRequest) -> JSO
byte-identical to a request that omits `views`. They are separate tokens because they answer
separate questions — a caller building a fill-in form wants the inputs, a caller rendering a
result or registering a tool signature with a return type wants the output.
- - **Invalid verdict (200, `is_valid: false`):** the `InvalidReport` arm — `validation_errors[]`
- (the structured per-error diagnostics, built by pipelex's one shared builder, incl. one
- located `dry_run` item per pipe whose dry run failed) + `message`, with the structural artifacts absent. The runner
- returns this as a value (a `BundleValidationFailure` with `validation_errors`) regardless of backend — the
+ - **Invalid verdict (200, `is_valid: false`):** the `InvalidReport` arm — `errors[]`, one problem item per
+ error with its own code (incl. one located item per pipe whose dry run failed, with the failure's code), the
+ items of the verdict's problem — + `message`, with the structural artifacts absent. The runner
+ returns this as a value (a `BundleValidationFailure` with validation items) regardless of backend — the
in-process arm from the bundle's `ValidateBundleError`, the dispatched arm recovered from the
worker — so the route maps it to a 200 by matching validation diagnostics, never by catching an
exception. A returned failure without validation diagnostics is a backend, configuration or runtime
fault, and its problem is answered as every raised failure's is.
+ - **Either arm:** a member with no value is absent rather than `null`, at the arm's top level and in its
+ problem items; the structured artifacts of the valid arm keep their own serialization.
- **No verdict (non-2xx):** a malformed request body, an `mthds_sources` length mismatch, or
- both/neither of `mthds_contents` / `method_ref` is a request-shape **422**; a forbidden
- `orchestration_mode` override is a **403**; a host-wiring programmer error or a genuine
- orchestrator fault is a **5xx**; auth is **401/403**. A `method_ref` **resolution failure**
- is also a no-verdict condition — never an `is_valid: false`: each answers the status its
- code declares, such as a **422** for a malformed reference, a **502** for a failed fetch, a
- **404** for no matching package in the repository and a **422** for the method's Python
- structure classes, and the custom-code sandbox gate a **403**. All are
- `application/problem+json` rendered by the global handlers in
- `pipelex_api.exception_handlers` — routes never shape them.
+ both/neither of `mthds_contents` / `method_ref` is a request-shape **422**, and so is a forbidden
+ `orchestration_mode` override; a host-wiring programmer error or a genuine orchestrator fault is a
+ **5xx**; auth is **401/403**. A `method_ref` **resolution failure** is also a no-verdict condition —
+ never an `is_valid: false`: each answers the status its code declares, such as a **422** for a
+ malformed reference, a **502** for a failed fetch, a **404** for no matching package in the
+ repository and a **422** for the method's Python structure classes, and the custom-code sandbox gate
+ a **501**. All are `application/problem+json` documents carrying a registry `code`, rendered by the
+ global handlers in `pipelex_api.exception_handlers` — routes never shape them.
"""
# Opt-in presentation formats (D-D): resolved once, threaded into both 200 arms. Empty by
# default → no `rendered_*` field, response byte-identical to the no-`render` request.
@@ -423,7 +443,7 @@ async def validate_mthds(request: Request, request_data: ValidateRequest) -> JSO
)
if isinstance(verdict, BundleValidationFailure):
if verdict.validation_errors:
- return _invalid_report_response(verdict, requested_formats=requested_formats)
+ return _invalid_report_response(verdict, requested_formats=requested_formats, view=problem_view_of(request))
return problem_response(verdict.problem.model_copy(update={"request_id": request_id_of(request)}), error=None, request=request)
report = verdict
# The echo of a tree is its bundles' text, decoded strictly now that the valid verdict says they loaded.
@@ -435,11 +455,14 @@ async def validate_mthds(request: Request, request_data: ValidateRequest) -> JSO
response_data = ValidReport.model_validate(
{
**dict(report),
+ "warnings": warning_problem_items(warnings=report.warnings),
"mthds_contents": validated_contents,
"default_pipe_ref": tree_default_pipe_ref if default_pipe_ref_known else _effective_default_pipe_ref(report),
}
)
- content = response_data.model_dump(mode="json", serialize_as_any=True, by_alias=True)
+ content = _without_unset_members(response_data.model_dump(mode="json", serialize_as_any=True, by_alias=True))
+ # The problem items are dumped as the standard writes them, with no member written as `null`.
+ content["warnings"] = [warning.model_dump(mode="json", exclude_none=True) for warning in response_data.warnings]
# `rendered_markdown` is a presentation extra (D-D), not part of the report: attach it only when
# `markdown` was requested, else pop it so the response stays byte-identical to a no-`render` call
# (the valid arm is dumped without `exclude_none`, so the default `null` would otherwise linger).
@@ -462,29 +485,37 @@ async def validate_mthds(request: Request, request_data: ValidateRequest) -> JSO
return JSONResponse(content=content)
-def _invalid_report_response(failure: BundleValidationFailure, *, requested_formats: set[RenderFormat]) -> JSONResponse:
+def _without_unset_members(content: dict[str, Any]) -> dict[str, Any]:
+ """A verdict's members without those that hold no value: a member with no value is absent, never `null`.
+
+ Only the arm's own members are dropped: inside an extension artifact, such as the bundle blueprint or a JSON
+ schema, a `null` may be the value itself.
+ """
+ return {name: value for name, value in content.items() if value is not None}
+
+
+def _invalid_report_response(failure: BundleValidationFailure, *, requested_formats: set[RenderFormat], view: ProblemView) -> JSONResponse:
"""Render a produced "invalid" verdict as a 200 `InvalidReport` (D-A / D-C / D-D).
- The `validation_errors[]` come straight from pipelex's one shared builder via
- `ValidateBundleError.validation_error_items()`, so the hosted invalid arm carries the same typed
- items the agent CLI emits (including one located `dry_run` item per pipe whose dry run failed —
- the structured-info invariant, which the parse-level `blueprint_validation` residual makes total,
- guarantees this list is non-empty on every invalid verdict that reaches the wire,
- since the empty-`mthds_contents` edge case is a request-shape 422 via `min_length=1`).
- `message` is the failure's problem's `detail`, the sentence its code renders, which reads the same in every view.
+ The `errors[]` are the problem items of the verdict's problem, in the view of the request's reader, one per item of
+ pipelex's one shared builder (`ValidateBundleError.problem_items()`), each with its own code: including one located
+ item per pipe whose dry run failed — the structured-info invariant, which the parse-level residual makes total,
+ guarantees this list is non-empty on every invalid verdict that reaches the wire, since the empty-`mthds_contents`
+ edge case is a request-shape 422 via `min_length=1`. `message` is the problem's `detail`, the sentence its code
+ renders, which reads the same in every view.
"""
- invalid_report = InvalidReport(
- validation_errors=failure.validation_errors,
- message=failure.problem.detail,
- )
- # `exclude_none` drops each item's unset locators, so a wire item carries only what its fault has. The
- # items are `ValidateBundleError.validation_error_items()`, the ones the agent CLI's problem turns into its
- # `errors` — the "one error item, two surfaces" guarantee. The invalid arm's own fields are all non-None,
- # so none are lost; and `rendered_markdown` stays absent here unless explicitly requested below.
+ match view:
+ case ProblemView.OPERATOR:
+ problem = failure.problem
+ case ProblemView.CALLER:
+ problem = caller_view_of(problem=failure.problem)
+ items = list(problem.errors or [])
+ invalid_report = InvalidReport(errors=items, message=problem.detail)
+ # `exclude_none` drops each item's unset members, as the standard writes a problem item, and the arm's own: none is
+ # written as `null`, and `rendered_markdown` stays absent unless explicitly requested below.
content = invalid_report.model_dump(mode="json", serialize_as_any=True, by_alias=True, exclude_none=True)
- # Opt-in presentation extra (D-D): a faithful render of the structured `validation_errors`,
- # attached only when `markdown` was requested. Built from the just-dumped content so the renderer
- # reads the same items the wire carries.
+ # Opt-in presentation extra (D-D), attached only when `markdown` was requested: the Markdown of the very items
+ # `errors` holds, in the same view, so it never says what the reader's view leaves out of them.
if RenderFormat.MARKDOWN in requested_formats:
- content["rendered_markdown"] = render_invalid_validation_markdown(content)
+ content["rendered_markdown"] = render_invalid_verdict_markdown(items=items, message=problem.detail)
return JSONResponse(content=content)
diff --git a/api/pipelex_api/routes/version.py b/api/pipelex_api/routes/version.py
index ea696691e..0b2ccac75 100644
--- a/api/pipelex_api/routes/version.py
+++ b/api/pipelex_api/routes/version.py
@@ -12,8 +12,7 @@ from fastapi import APIRouter
from mthds.protocol.protocol import PROTOCOL_VERSION
from pipelex.pipeline.runner import PipelexVersionInfo
-from pipelex_api.error_types import ErrorType
-from pipelex_api.errors import raise_internal_server_error
+from pipelex_api.exceptions import RunnerMisconfiguredError
from pipelex_api.openapi_responses import PROBLEM_500
router = APIRouter(tags=["discovery"])
@@ -44,7 +43,8 @@ async def get_version() -> PipelexVersionInfo:
implementation_version = version(IMPLEMENTATION_NAME)
runtime_version = version("pipelex")
except PackageNotFoundError as exc:
- raise_internal_server_error(f"Package metadata is not available: {exc}", error_type=ErrorType.PACKAGE_NOT_FOUND)
+ msg = f"Package metadata is not available: {exc}"
+ raise RunnerMisconfiguredError(msg, component="package_metadata") from exc
return PipelexVersionInfo(
protocol_version=PROTOCOL_VERSION,
runner_version=implementation_version,
diff --git a/api/pipelex_api/run_extras_binding.py b/api/pipelex_api/run_extras_binding.py
new file mode 100644
index 000000000..d7c061586
--- /dev/null
+++ b/api/pipelex_api/run_extras_binding.py
@@ -0,0 +1,54 @@
+"""The labels a host attaches to a request, its `analytics_groups`, bound on the request before anything is refused.
+
+The hosted plane fills them with the organization a request is made for. A refusal answered before the request's work
+begins, a path leaving its tree, a callback URL aimed at a private address, a reserved object key, logs a security event
+(`pipelex.errors.security_event`), which names whose request it was by those labels, as `run.extras.<key>`. So they are
+read off the body as soon as it is parsed, before any field is refused: by `JsonBodyRoute` for every route declaring a
+typed body, `/validate`, `/resolve`, `/codegen`, `/pipe-io` and `/v1/blobs/missing` among them, and by the run routes,
+which parse their raw body themselves. The exception handlers read them back (`_run_extras_of`).
+
+Only labels that pass the runtime's own rules on their own are bound (`pipelex.system.run_extras.validate_run_extras`),
+so the event never carries a value the runtime would refuse, and a body whose labels are refused binds none: that
+refusal is the request's own `request.invalid`, answered when its model is validated.
+"""
+
+from typing import Any, cast
+
+from fastapi import Request
+from pydantic import ValidationError
+
+from pipelex_api.schemas.models import CallerAnalyticsGroupsMixin
+
+ANALYTICS_GROUPS_FIELD = "analytics_groups"
+
+
+def validated_run_extras_or_none(*, body: Any) -> dict[str, str] | None:
+ """The body's `analytics_groups` when they pass the runtime's rules on their own, else `None`.
+
+ Args:
+ body: The request's parsed JSON body, whatever its shape: a body that is not an object names no labels.
+
+ Returns:
+ The labels, or `None` when the body names none or names some the runtime refuses.
+ """
+ if not isinstance(body, dict):
+ return None
+ # A JSON object's keys are strings: what each value is, the labels' rules decide.
+ labels = cast("dict[str, Any]", body).get(ANALYTICS_GROUPS_FIELD)
+ try:
+ return CallerAnalyticsGroupsMixin.model_validate({ANALYTICS_GROUPS_FIELD: labels}).analytics_groups
+ except ValidationError:
+ return None
+
+
+def bind_run_extras(*, request: Request, body: Any) -> None:
+ """Bind the body's valid labels on the request's state, where the exception handlers read them.
+
+ The state lives in the request's scope, so every `Request` built from it, the one an exception handler receives
+ included, reads what this one bound.
+
+ Args:
+ request: The request whose body was parsed.
+ body: Its parsed JSON body.
+ """
+ request.state.run_extras = validated_run_extras_or_none(body=body)
diff --git a/api/pipelex_api/schemas/models.py b/api/pipelex_api/schemas/models.py
index 46a7b7e81..65561e0e9 100644
--- a/api/pipelex_api/schemas/models.py
+++ b/api/pipelex_api/schemas/models.py
@@ -25,7 +25,7 @@ from pipelex.tools.network.host_rules import classify_disallowed_host, is_disall
from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
from pydantic.functional_validators import SkipValidation
-from pipelex_api.exceptions import CallbackUrlRefusedError
+from pipelex_api.exceptions import CallbackUrlRefusedError, RequestFieldConflictError
from pipelex_api.limits import (
DEFAULT_MAX_RESOURCE_FILE_KIB,
DEFAULT_MAX_RESOURCES_PER_REQUEST,
@@ -72,9 +72,10 @@ FILES_FIELD_DESCRIPTION = (
'value is the file\'s UTF-8 text, `{"base64": ...}` holding its bytes, or `{"sha256": ..., "size": ...}` '
"naming bytes this runner already holds (uploaded with `POST /v1/blobs/missing` then `PUT /v1/blobs/{sha256}`). The "
"map is read from the request's JSON text: a key given twice, a key the membership rule keeps out of every tree "
- "(`.mthds/` included), colliding keys and a malformed entry are a 422 `InvalidMethodFiles` whose `tree_refusal` names "
- "the code and the paths, and hash entries the runner does not hold are one 422 `MissingBlobs` whose `missing_blobs` "
- "lists every such hash. Its `.mthds` files are the method's bundles and every other file is one a step may read, "
+ "(`.mthds/` included) and colliding keys are a 422 `method.package_invalid` whose `reason` is the refusal's code and "
+ "whose `path` names the first path, a key leaving the tree is a 422 `security.input_path_refused`, a malformed entry "
+ "is a 422 `request.invalid`, and hash entries the runner does not hold are one 422 `request.blobs_missing` whose "
+ "`missing_blobs` parameter lists every such hash. Its `.mthds` files are the method's bundles and every other file is one a step may read, "
"such as a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`, the run starts at the `main_pipe` of the "
"`METHODS.toml` at the tree's root, or else at the one `main_pipe` its bundles declare. Custom `.py` is only honored "
"on a sandbox-hosted deployment."
@@ -390,23 +391,34 @@ _ORCHESTRATION_MODE_DESCRIPTION = (
"plugin-provided token are accepted; an unregistered token is refused at dispatch. The delivery axis "
"(blocking vs fire-and-forget) is endpoint-set, never requestable. Honored ONLY when the deployment sets "
"`allow_request_orchestration_mode_override = true` in its `api.toml`; otherwise a token that differs from "
- "the deployment default is refused with a 403. Omit it to use the deployment default."
+ "the deployment default is refused with a 422 `pipelex.deployment.orchestration_override_forbidden`. Omit it to use "
+ "the deployment default."
)
_ALLOWED_CALLBACK_SCHEMES = frozenset({"http", "https"})
+# The marker that opens a URL's authority, where it names its host.
+_AUTHORITY_MARKER = "//"
-def _is_disallowed_host(host: str) -> bool:
- """True if `host` is a destination a completion callback must not reach: the runtime's own SSRF rule.
- Used to harden /start callback_urls against SSRF — a malicious client could otherwise aim webhooks at internal
- services or cloud metadata endpoints (e.g. 169.254.169.254). The rule is the one the delivery-time guard applies
- when the webhook fires, `pipelex.tools.network.host_rules`, so a spelling the guard refuses at fire time (an
- uppercase or trailing-dot alias, a carrier-grade NAT address) is refused here first. Best-effort: hostnames that
- resolve to private addresses at fire time aren't blocked here, only literal IPs and the known internal names.
+def _opens_authority(*, url: str, scheme: str) -> bool:
+ """Whether `url` opens an authority, `//` right after its scheme, or at its start when it names none.
+
+ Read for a URL whose authority `urlparse` found empty, which it reads the same with `//` or without: `file:///x`
+ opens an empty authority behind a scheme the SSRF rule refuses, while `file:/x`, or `example.com:8080/hook`, whose
+ host `urlparse` takes for a scheme, opens none.
"""
- return is_disallowed_host(host)
+ remainder = url.strip()
+ if scheme:
+ remainder = remainder[len(scheme) + 1 :]
+ return remainder.startswith(_AUTHORITY_MARKER)
+
+
+def _refused_host_error(*, host: str) -> CallbackUrlRefusedError:
+ """The SSRF rule's refusal of a callback URL naming `host`, stating the class of destination its event names."""
+ msg = f"callback URL host {host!r} is not allowed (private/loopback/metadata addresses are blocked)"
+ return CallbackUrlRefusedError(msg).with_security_target_class(classify_disallowed_host(host))
class PipelineApiExtras(BaseModel):
@@ -488,22 +500,37 @@ class PipelineApiExtras(BaseModel):
msg = f"callback URL exceeds {MAX_CALLBACK_URL_LEN} chars"
raise ValueError(msg)
parsed = urlparse(url)
- # A URL with no scheme or no host is malformed, the shape of the field, which a plain `ValueError` refuses
- # with no security event. A scheme other than http or https, and a host the SSRF rule refuses, are a security
- # rule's refusals, so each states the class of destination its security event names.
+ # A URL that opens no authority, no scheme or no host is malformed, the shape of the field, which a plain
+ # `ValueError` refuses with no security event: `example.com:8080/hook` or `localhost:3000/cb` opens no
+ # authority, and `urlparse` takes its host for a scheme, which is no scheme the rule refuses. A scheme other
+ # than http or https, and a host the SSRF rule refuses, are a security rule's refusals, so each states the
+ # class of destination its security event names.
+ if not parsed.netloc and not _opens_authority(url=url, scheme=parsed.scheme):
+ msg = "callback URL must be an absolute http or https URL, naming its host after '//'"
+ raise ValueError(msg)
+ host = parsed.hostname
+ # A host of dots alone, such as `.`, is empty once the SSRF rule drops a trailing dot, so it names no host
+ # either, and no class of destination a security event could state.
if not parsed.scheme:
+ # A scheme-relative URL, `//host/path`, names a host but no scheme: a host the SSRF rule refuses is still
+ # that rule's refusal, classed by the host, and any other leaves the URL malformed.
+ if host and host.rstrip(".") and is_disallowed_host(host):
+ raise _refused_host_error(host=host)
msg = "callback URL must be an absolute http or https URL, starting with its scheme"
raise ValueError(msg)
if parsed.scheme not in _ALLOWED_CALLBACK_SCHEMES:
msg = f"callback URL scheme must be http or https (got {parsed.scheme!r})"
raise CallbackUrlRefusedError(msg).with_security_target_class(SecurityTargetClass.SCHEME)
- host = parsed.hostname
- if not host:
+ if not host or not host.rstrip("."):
msg = "callback URL must name a host"
raise ValueError(msg)
- if _is_disallowed_host(host):
- msg = f"callback URL host {parsed.hostname!r} is not allowed (private/loopback/metadata addresses are blocked)"
- raise CallbackUrlRefusedError(msg).with_security_target_class(classify_disallowed_host(host))
+ # The runtime's own SSRF rule, the one the delivery-time guard applies when the webhook fires
+ # (`pipelex.tools.network.host_rules`), so a spelling the guard refuses at fire time, an uppercase or
+ # trailing-dot alias or a carrier-grade NAT address, is refused here first, before a malicious client can
+ # aim a webhook at an internal service or a cloud metadata endpoint. Best effort: a hostname resolving to a
+ # private address at fire time is not refused here, only literal IPs and the known internal names.
+ if is_disallowed_host(host):
+ raise _refused_host_error(host=host)
return value
@@ -611,8 +638,8 @@ class MethodTreeRequest(BaseModel):
(`pipelex_api.method_tree_request`), with the `dependencies` it carries and the `resources` that join it. An
**address-form** `method_ref` (`github.com/<owner>/<repo>[/<selector>][@<tag>]`) is resolved by this server through
the run routes' fetch path: the package's tree is read from its commit's git objects, with the packages it ships
- under `.mthds/methods/`. The **registry form** (any non-address reference) stays reserved and answers 501 until
- server-side method-registry resolution exists. Either way the method is held to the run routes' Python policy:
+ under `.mthds/methods/`. The **registry form** (any non-address reference) stays reserved, a 422
+ `request.unsupported`, until server-side method-registry resolution exists. Either way the method is held to the run routes' Python policy:
custom `.py` only on a sandbox-hosted deployment, and no Python structure class at all.
"""
@@ -629,8 +656,8 @@ class MethodTreeRequest(BaseModel):
description=(
"PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — a published method by reference, instead of its tree. "
"Address form (`github.com/<owner>/<repo>[/<selector>][@<tag>]`) is fetched and read as a `files` tree is, "
- "through the same path as a `method_ref` run; the registry form stays reserved (501 until a method registry "
- "exists). Exactly one of `files` / `method_ref`."
+ "through the same path as a `method_ref` run; the registry form stays reserved (a 422 `request.unsupported` "
+ "until a method registry exists). Exactly one of `files` / `method_ref`."
),
)
resources: dict[str, str] | None = Field(default=None, description=RESOURCES_FIELD_DESCRIPTION)
@@ -645,15 +672,16 @@ class MethodTreeRequest(BaseModel):
@model_validator(mode="after")
def _exactly_one_selector(self) -> Self:
+ # Each refusal names the field to change: the second selector when both are sent, the first when none is.
if (self.files is None) == (self.method_ref is None):
msg = "provide exactly one of `files` or `method_ref`"
- raise ValueError(msg)
+ raise RequestFieldConflictError(msg, field="method_ref" if self.method_ref is not None else "files")
if self.dependencies is not None and self.files is None:
msg = "`dependencies` accompany the method's own `files`"
- raise ValueError(msg)
+ raise RequestFieldConflictError(msg, field="dependencies")
if self.resources and self.method_ref is not None:
msg = "resources accompany a method sent in `files`; a method_ref's files are the package's own"
- raise ValueError(msg)
+ raise RequestFieldConflictError(msg, field="resources")
return self
@@ -667,8 +695,8 @@ class MethodTreePipeRequest(MethodTreeRequest):
`main_pipe`, which is what a single-bundle caller almost always wants. A closure that declares no
`main_pipe` — or several, across domains — cannot be defaulted from its own declarations, so when
no manifest `main_pipe` settles it a route that needs one pipe refuses the omitted selector with an
- input 422, `EntryPipeNotFoundError` or `EntryPipeAmbiguousError`
- (`crate_ops.resolve_requested_pipe`), never the request-shape `ValidationError` of a malformed body.
+ input 422 named for its failure (`crate_ops.resolve_requested_pipe`), never the request-shape
+ `request.invalid` of a malformed body.
"""
pipe_ref: str | None = Field(
@@ -744,11 +772,16 @@ class MthdsContentsRequest(BaseModel):
def _exactly_one_content_selector(self) -> Self:
# Strict XOR (the addressing design's tooling-route rule): a stateless diagnostic call
# has no linkage slot, so a second selector could only be ignored — refuse it instead.
- selectors = [self.mthds_contents, self.files, self.method_ref]
- if sum(selector is not None for selector in selectors) != 1:
+ # Each refusal names the field to change: the second selector sent, or the first when none is.
+ sent = [
+ name
+ for name, selector in (("mthds_contents", self.mthds_contents), ("files", self.files), ("method_ref", self.method_ref))
+ if selector is not None
+ ]
+ if len(sent) != 1:
msg = "provide exactly one of `mthds_contents`, `files` or `method_ref`"
- raise ValueError(msg)
+ raise RequestFieldConflictError(msg, field=sent[1] if sent else "mthds_contents")
if self.dependencies is not None and self.files is None:
msg = "`dependencies` accompany the method's own `files`"
- raise ValueError(msg)
+ raise RequestFieldConflictError(msg, field="dependencies")
return self
diff --git a/api/pipelex_api/security.py b/api/pipelex_api/security.py
index 9886431ea..1ef14dd6d 100644
--- a/api/pipelex_api/security.py
+++ b/api/pipelex_api/security.py
@@ -14,16 +14,16 @@ from typing import Annotated, Any
import jwt
from fastapi import Depends, Request
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from mthds.protocol.problem.registry import CoreCode
from pipelex import log
+from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
from pipelex.system.environment import get_optional_env
from pipelex.system.storage_scope import SINGLE_TENANT_USER_ID
from pipelex.tools.log.error_fields import error_fields
from pipelex.tools.log.log_fields import USER_ACTION_FIELD
from pydantic import BaseModel, Field
-from pipelex_api.error_types import ErrorType
-from pipelex_api.errors import raise_bad_request, raise_internal_server_error, raise_unauthenticated
-from pipelex_api.exceptions import InvalidAuthModeError
+from pipelex_api.exceptions import InvalidAuthModeError, RunnerAuthError, RunnerMisconfiguredError, RunnerRequestError
from pipelex_api.problem_view import mark_operator_request
AUTH_MODE_ENV_VAR = "AUTH_MODE"
@@ -31,6 +31,10 @@ AUTH_MODE_ENV_VAR = "AUTH_MODE"
# JWT Configuration (only used when AUTH_MODE=jwt)
JWT_ALGORITHM = "HS256"
+# The `WWW-Authenticate` challenge of a 401 where the deployment reads a bearer credential, a token or the API key
+# (RFC 9110, section 15.5.2). A deployment behind a trusted proxy reads none, so its refusals carry no challenge.
+BEARER_CHALLENGE = "Bearer"
+
# A caller's `user_id` is the first path segment of every `pipelex-storage://`
# URI and S3 key (`<user_id>/...`). The runner treats it as an OPAQUE id and
# does NOT validate its identity/shape: a self-hosted deployment may use any id
@@ -82,9 +86,9 @@ def is_safe_user_id(value: str) -> bool:
# does NOT raise FastAPI's default `HTTPException` (which would emit
# `application/json` `{"detail": "Not authenticated"}` — the old, pre-RFC-7807
# shape) before our verifiers run. With `auto_error=False`, `HTTPBearer`
-# returns `None` in that case, and the verifiers below raise
-# `raise_unauthenticated(...)` so the response is the same RFC 7807
-# `application/problem+json` document as every other 401 on the surface.
+# returns `None` in that case, and the verifiers below raise a
+# `RunnerAuthError` carrying `auth.missing_credential`, so the response is the
+# same `application/problem+json` document as every other 401 on the surface.
security = HTTPBearer(auto_error=False)
@@ -97,8 +101,8 @@ class AuthMode(StrEnum):
class AuthRefusalReason(StrEnum):
"""Why the server refused a caller's own credentials, as the `auth_refusal_reason` field of the line that says so.
- These are the caller's mistakes, answered with a 401 the exception handler records at WARNING with its `error.type`
- and `detail`, so the line naming the reason is diagnosis and logs at DEBUG. A token that verifies but whose
+ These are the caller's mistakes, answered with a 401 the exception handler records at WARNING with its `error.code`
+ and `error.type`, so the line naming the reason is diagnosis and logs at DEBUG. A token that verifies but whose
`user_id` claim is unusable is no caller's mistake: whoever minted it holds the server's secret, so it is the
deployment's issuer that is misconfigured, and that line stays a WARNING the operator can act on.
"""
@@ -175,17 +179,19 @@ async def verify_jwt(
if credentials is None:
# Missing, empty, or non-Bearer `Authorization` header. `HTTPBearer`
# is configured with `auto_error=False` so this branch (rather than
- # FastAPI's default `HTTPException`) shapes the response — same RFC
- # 7807 `application/problem+json` as every other 401.
+ # FastAPI's default `HTTPException`) shapes the response — the same
+ # `application/problem+json` as every other 401.
log.debug(CREDENTIALS_REFUSED_MESSAGE, fields={"auth_mode": AuthMode.JWT, "auth_refusal_reason": AuthRefusalReason.MISSING_BEARER_TOKEN})
- raise_unauthenticated("Missing or malformed Authorization header")
+ msg = "Missing or malformed Authorization header"
+ raise RunnerAuthError(msg, challenge=BEARER_CHALLENGE).with_error_code(CoreCode.AUTH_MISSING_CREDENTIAL)
jwt_secret = get_optional_env("JWT_SECRET_KEY")
if not jwt_secret:
log.error(
"An environment variable the authentication mode requires is not set", fields={"env_var": "JWT_SECRET_KEY", "auth_mode": AuthMode.JWT}
)
- raise_internal_server_error("Server configuration error: JWT_SECRET_KEY not configured", error_type=ErrorType.SERVER_MISCONFIGURED)
+ msg = "Server configuration error: JWT_SECRET_KEY not configured"
+ raise RunnerMisconfiguredError(msg, component="JWT_SECRET_KEY")
token = credentials.credentials
@@ -204,7 +210,10 @@ async def verify_jwt(
user_id = payload.get("user_id")
if not user_id:
log.warning("A verified token has no user id claim", fields={USER_ACTION_FIELD: TOKEN_ISSUER_USER_ACTION})
- raise_unauthenticated("Invalid token: missing user_id claim", error_type=ErrorType.INVALID_TOKEN)
+ msg = "Invalid token: missing user_id claim"
+ raise (
+ RunnerAuthError(msg).with_error_code(PipelexErrorCode.DEPLOYMENT_TOKEN_CLAIMS_INVALID).with_params(claim="user_id", reason="missing")
+ )
if not isinstance(user_id, str) or not is_safe_user_id(user_id):
# The claim is refused, so it is not `user.id`, which names an authenticated caller and is always a string:
# the line carries the type the claim was decoded as, and never its value.
@@ -212,7 +221,8 @@ async def verify_jwt(
"A verified token's user id claim is not a path-safe segment",
fields={"claim_type": type(user_id).__name__, USER_ACTION_FIELD: TOKEN_ISSUER_USER_ACTION},
)
- raise_unauthenticated("Invalid token: user_id claim must be a single path-safe segment", error_type=ErrorType.INVALID_TOKEN)
+ msg = "Invalid token: user_id claim must be a single path-safe segment"
+ raise RunnerAuthError(msg).with_error_code(PipelexErrorCode.DEPLOYMENT_TOKEN_CLAIMS_INVALID).with_params(claim="user_id", reason="unsafe")
if user_id == SINGLE_TENANT_USER_ID:
# Path-safe, but reserved for the no-user-model deployment. An
# authenticated token must not claim it, or that caller's runs would
@@ -220,23 +230,25 @@ async def verify_jwt(
# users — beside whatever a no-auth deployment of the same image
# wrote there.
log.warning("A verified token's user id claim is the reserved single-tenant id", fields={USER_ACTION_FIELD: TOKEN_ISSUER_USER_ACTION})
- raise_unauthenticated(
- f"Invalid token: user_id claim must not be the reserved {SINGLE_TENANT_USER_ID!r} value",
- error_type=ErrorType.INVALID_TOKEN,
+ msg = f"Invalid token: user_id claim must not be the reserved {SINGLE_TENANT_USER_ID!r} value"
+ raise (
+ RunnerAuthError(msg).with_error_code(PipelexErrorCode.DEPLOYMENT_TOKEN_CLAIMS_INVALID).with_params(claim="user_id", reason="reserved")
)
_set_request_user(request, user_id=user_id)
return payload
- except jwt.ExpiredSignatureError:
+ except jwt.ExpiredSignatureError as exc:
log.debug(CREDENTIALS_REFUSED_MESSAGE, fields={"auth_mode": AuthMode.JWT, "auth_refusal_reason": AuthRefusalReason.EXPIRED_TOKEN})
- raise_unauthenticated("Token expired", error_type=ErrorType.TOKEN_EXPIRED)
+ msg = "Token expired"
+ raise RunnerAuthError(msg, challenge=BEARER_CHALLENGE).with_error_code(CoreCode.AUTH_CREDENTIAL_EXPIRED) from exc
except jwt.InvalidTokenError as exc:
log.debug(
CREDENTIALS_REFUSED_MESSAGE,
fields={"auth_mode": AuthMode.JWT, "auth_refusal_reason": AuthRefusalReason.INVALID_TOKEN, **error_fields(exc=exc)},
)
- raise_unauthenticated("Invalid token", error_type=ErrorType.INVALID_TOKEN)
+ msg = "Invalid token"
+ raise RunnerAuthError(msg, challenge=BEARER_CHALLENGE) from exc
async def verify_api_key(request: Request, credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(security)]) -> str:
@@ -250,17 +262,20 @@ async def verify_api_key(request: Request, credentials: Annotated[HTTPAuthorizat
# matching branch in `verify_jwt` for why this lives here and not
# in `HTTPBearer`'s default `auto_error=True` behavior.
log.debug(CREDENTIALS_REFUSED_MESSAGE, fields={"auth_mode": AuthMode.API_KEY, "auth_refusal_reason": AuthRefusalReason.MISSING_BEARER_TOKEN})
- raise_unauthenticated("Missing or malformed Authorization header")
+ msg = "Missing or malformed Authorization header"
+ raise RunnerAuthError(msg, challenge=BEARER_CHALLENGE).with_error_code(CoreCode.AUTH_MISSING_CREDENTIAL)
api_key = get_optional_env("API_KEY")
if not api_key:
log.error("An environment variable the authentication mode requires is not set", fields={"env_var": "API_KEY", "auth_mode": AuthMode.API_KEY})
- raise_internal_server_error("Server configuration error: API_KEY not configured", error_type=ErrorType.SERVER_MISCONFIGURED)
+ msg = "Server configuration error: API_KEY not configured"
+ raise RunnerMisconfiguredError(msg, component="API_KEY")
if credentials.credentials != api_key:
log.debug(CREDENTIALS_REFUSED_MESSAGE, fields={"auth_mode": AuthMode.API_KEY, "auth_refusal_reason": AuthRefusalReason.API_KEY_MISMATCH})
- raise_unauthenticated("Invalid authentication token", error_type=ErrorType.INVALID_TOKEN)
+ msg = "Invalid authentication token"
+ raise RunnerAuthError(msg, challenge=BEARER_CHALLENGE)
mark_operator_request(request)
return credentials.credentials
@@ -304,13 +319,17 @@ async def no_auth(request: Request) -> None:
USER_ACTION_FIELD: "Make sure the proxy in front of the server authenticates every request and forwards X-User-Id",
},
)
- raise_unauthenticated("Identity required: no X-User-Id was forwarded", error_type=ErrorType.INVALID_TOKEN)
+ # No challenge: this deployment reads no credential of the request, so a `WWW-Authenticate: Bearer` would ask
+ # for a token it never reads.
+ msg = "Identity required: no X-User-Id was forwarded"
+ raise RunnerAuthError(msg).with_error_code(CoreCode.AUTH_MISSING_CREDENTIAL)
if not is_safe_user_id(user_id):
- # A non-empty but path-unsafe id: the proxy intended to authenticate
- # someone and sent a malformed value. Fail closed.
+ # A non-empty but path-unsafe id: the proxy intended to authenticate someone and sent a malformed value, so the
+ # request is refused, naming the header, rather than any credential failing. Fail closed.
# No value: the header is refused, so it names no caller, and it is whatever text anyone reaching the server sent.
log.warning("A forwarded user id is not a path-safe segment and the request was refused")
- raise_bad_request("Forwarded X-User-Id must be a single path-safe segment", error_type=ErrorType.BAD_REQUEST)
+ msg = "Forwarded X-User-Id must be a single path-safe segment"
+ raise RunnerRequestError(msg, field=ForwardedIdentityHeader.USER_ID)
_set_request_user(request, user_id=user_id)
mark_operator_request(request)
diff --git a/api/postman/sample-bundles/README.md b/api/postman/sample-bundles/README.md
index 87bc374f4..b5549642b 100644
--- a/api/postman/sample-bundles/README.md
+++ b/api/postman/sample-bundles/README.md
@@ -13,17 +13,17 @@ Each verdict below was confirmed against a live `POST /v1/validate`.
| `fashion_moodboard.mthds` | valid · **runnable** | Real demo bundle (search → LLM → image gen). Validates free; executing it is expensive. |
| `batch_candidate_screening.mthds` | valid · **runnable** | Real demo bundle (inline structures; PDF `Document` inputs needed to actually run). |
| `draft_with_signature.mthds` | valid · **NOT runnable** | One step is a forward-declared `PipeSignature` → `is_runnable:false`, `pending_signatures` lists it. Running it raises `PipeSignatureNotExecutableError`. |
-| `invalid/missing_main_pipe.mthds` | valid (no `main_pipe`) | Kept here for reference: a bundle with **no `main_pipe` still validates** (`graph_spec:null`). It is *not* an invalid case. |
+| `invalid/missing_main_pipe.mthds` | valid (no `main_pipe`) | Kept here for reference: a bundle with **no `main_pipe` still validates** (no `graph_spec`). It is *not* an invalid case. |
## Invalid — one distinct error type each
-| File | `validation_errors[].error_type` / category | What it shows |
+| File | `errors[].code` | What it shows |
|---|---|---|
-| `invalid/syntax_error.mthds` | TOML parse error | Malformed bundle text — fails before blueprint validation. |
-| `invalid/missing_pipe_ref.mthds` | dependency pipe not found | A `PipeSequence` step references a pipe that is never defined. |
-| `invalid/unknown_concept.mthds` | concept reference unresolved | A pipe `output` names a concept that is never declared and is not native. |
-| `invalid/prompt_input_mismatch.mthds` | `missing_input_variable` (blueprint_validation) | The prompt uses `$city`, which is not a declared input. |
-| `invalid/bad_pipe_type.mthds` | `union_tag_invalid` | `type = "PipeWizardry"` — not a real pipe type. |
+| `invalid/syntax_error.mthds` | `method.syntax` | Malformed bundle text — fails before blueprint validation. |
+| `invalid/missing_pipe_ref.mthds` | `method.pipe_unresolved` | A `PipeSequence` step references a pipe that is never defined. |
+| `invalid/unknown_concept.mthds` | `method.concept_unresolved` | A pipe `output` names a concept that is never declared and is not native. |
+| `invalid/prompt_input_mismatch.mthds` | `method.input_undeclared` | The prompt uses `$city`, which is not a declared input. |
+| `invalid/bad_pipe_type.mthds` | `method.pipe_type_invalid` | `type = "PipeWizardry"` — not a real pipe type. |
## Inputs
diff --git a/api/tests/unit/_problems.py b/api/tests/unit/_problems.py
new file mode 100644
index 000000000..5fe7b6a74
--- /dev/null
+++ b/api/tests/unit/_problems.py
@@ -0,0 +1,70 @@
+"""Assertions on the problem documents the runner answers, shared by the route tests.
+
+Every failure the runner answers is an `application/problem+json` document carrying a registry `code`, the status its
+code declares, repeated in the body, and no member written as `null`. These helpers assert that shape once, so a test
+states only what is particular to its refusal: the code, and the parameters or the field it names.
+"""
+
+import json
+from collections.abc import Mapping
+from typing import Any, Protocol
+
+from pipelex.base_exceptions import PipelexError
+from pipelex.errors.problem import ProblemView
+
+from pipelex_api.problem_document import problem_json_response
+
+PROBLEM_JSON = "application/problem+json"
+
+
+class ClientResponse(Protocol):
+ """What these helpers read of a test client's response, whichever HTTP client package the test client is built on."""
+
+ @property
+ def status_code(self) -> int: ...
+
+ @property
+ def headers(self) -> Mapping[str, str]: ...
+
+ @property
+ def text(self) -> str: ...
+
+ def json(self) -> Any: ...
+
+
+def assert_problem(response: ClientResponse, *, status: int, code: str, field: str | None = None) -> dict[str, Any]:
+ """Assert that a response is the problem document of `code` at `status`, and return its body.
+
+ Args:
+ response: The response a test client received.
+ status: The HTTP status the code declares.
+ code: The registry code the problem must carry.
+ field: The request field the problem's `field` parameter must name, when the code has one.
+
+ Returns:
+ The problem document.
+ """
+ assert response.status_code == status, response.text
+ assert response.headers["content-type"] == PROBLEM_JSON, response.headers
+ body: dict[str, Any] = response.json()
+ assert body["code"] == code, body
+ assert body["status"] == status, body
+ assert "instance" not in body, body
+ assert "error_type" not in body, body
+ assert None not in body.values(), body
+ if field is not None:
+ assert body["params"]["field"] == field, body
+ return body
+
+
+def problem_of(error: PipelexError, *, view: ProblemView = ProblemView.OPERATOR) -> dict[str, Any]:
+ """The problem document a raised error is answered with, in `view`, as the global handler renders it, its status included."""
+ response = problem_json_response(error.to_problem(view=ProblemView.OPERATOR), view=view)
+ body: dict[str, Any] = json.loads(bytes(response.body))
+ assert body["status"] == response.status_code, body
+ return body
+
+
+def problem_items_fields(body: dict[str, Any]) -> list[str]:
+ """The `field` parameter of each of a problem's items, in order: the fields a request refusal names one by one."""
+ return [item["params"]["field"] for item in body.get("errors", [])]
diff --git a/api/tests/unit/test_analytics_groups_extras.py b/api/tests/unit/test_analytics_groups_extras.py
index 13884f3e8..b704f5780 100644
--- a/api/tests/unit/test_analytics_groups_extras.py
+++ b/api/tests/unit/test_analytics_groups_extras.py
@@ -29,6 +29,7 @@ from pipelex_api.api_config import ApiConfig
from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.routes import router as api_router
from tests.unit._constants import VALID_MTHDS
+from tests.unit._problems import assert_problem, problem_items_fields
if TYPE_CHECKING:
from pipelex.system.job_metadata import RunMetadata
@@ -141,24 +142,19 @@ class TestAnalyticsGroupsReachTheRun:
response = client.post(route, json=_run_body(analytics_groups=bad_groups))
- assert response.status_code == 422, response.text
- assert response.headers["content-type"] == "application/problem+json"
- body = response.json()
- assert body["error_type"] == "InvalidAnalyticsGroups"
- assert "analytics_groups" in body["detail"]
+ body = assert_problem(response, status=422, code="request.invalid")
+ # The refused field, or a key inside it, which the path names from the field down.
+ assert body["params"]["field"].split(".")[0] == "analytics_groups", body
+ assert [field.split(".")[0] for field in problem_items_fields(body)] == ["analytics_groups"]
assert orchestrator.run_metadatas == []
- def test_a_body_failing_on_two_extras_gets_the_generic_error_type(self, mocker: MockerFixture) -> None:
+ def test_a_body_failing_on_two_extras_names_both(self, mocker: MockerFixture) -> None:
# Naming one of the two fields would send the caller to fix that one and leave the other
- # for the next request, so the classification falls back to the generic type and the
- # detail names both.
+ # for the next request, so the refusal carries one item per refused field.
client, orchestrator = _build_client(mocker)
response = client.post("/v1/start", json=_run_body(storage_scope="../escape", analytics_groups={"Organization": "org_acme"}))
- assert response.status_code == 422, response.text
- body = response.json()
- assert body["error_type"] == "ValidationError"
- assert "storage_scope" in body["detail"]
- assert "analytics_groups" in body["detail"]
+ body = assert_problem(response, status=422, code="request.invalid")
+ assert sorted(problem_items_fields(body)) == ["analytics_groups", "storage_scope"]
assert orchestrator.run_metadatas == []
diff --git a/api/tests/unit/test_api_config.py b/api/tests/unit/test_api_config.py
index db98ad32b..d3e04c537 100644
--- a/api/tests/unit/test_api_config.py
+++ b/api/tests/unit/test_api_config.py
@@ -13,12 +13,12 @@ from fastapi import FastAPI
from fastapi.testclient import TestClient
from pipelex_api.api_config import ApiConfig, get_api_config, resolve_boot_orchestrator, resolve_orchestration_mode
-from pipelex_api.errors import ApiError
from pipelex_api.exception_handlers import register_exception_handlers
-from pipelex_api.exceptions import ApiBootConfigError
+from pipelex_api.exceptions import ApiBootConfigError, OrchestrationOverrideForbiddenError
from pipelex_api.middleware import RequestIdMiddleware
from pipelex_api.routes.pipelex.pipeline import router as pipeline_router
from tests.unit._constants import VALID_MTHDS
+from tests.unit._problems import assert_problem, problem_of
def _temporal_locked_config() -> ApiConfig:
@@ -49,10 +49,12 @@ class TestResolveOrchestrationMode:
def test_forbidden_override_is_refused(self):
# A caller must not be able to force `direct` on a locked-down distributed runner.
- with pytest.raises(ApiError) as exc_info:
+ with pytest.raises(OrchestrationOverrideForbiddenError) as exc_info:
resolve_orchestration_mode("direct", config=_temporal_locked_config())
- assert exc_info.value.status_code == 403
- assert exc_info.value.document["error_type"] == "OrchestrationModeOverrideForbidden"
+ problem = problem_of(exc_info.value)
+ assert problem["status"] == 422
+ assert problem["code"] == "pipelex.deployment.orchestration_override_forbidden"
+ assert problem["params"] == {"requested_mode": "direct"}
def test_allowed_override_is_honored(self):
config = ApiConfig(orchestration_mode="temporal", allow_request_orchestration_mode_override=True)
@@ -94,14 +96,13 @@ class TestStartOverridePolicyEndToEnd:
register_exception_handlers(app)
return TestClient(RequestIdMiddleware(app))
- def test_forbidden_per_request_mode_on_start_is_403(self):
+ def test_forbidden_per_request_mode_on_start_is_422(self):
# The base config is `direct` with override off, so a caller forcing a different backend on
- # `POST /start` is refused with a 403 BEFORE any library load / dispatch — the policy gate
+ # `POST /start` is refused with a 422 BEFORE any library load / dispatch — the policy gate
# is the first thing `ApiRunner.start` checks.
response = self._client().post(
"/v1/start",
json={"pipe_code": "echo", "mthds_contents": [VALID_MTHDS], "orchestration_mode": "temporal"},
)
- assert response.status_code == 403, response.text
- assert response.headers["content-type"].startswith("application/problem+json")
- assert response.json()["error_type"] == "OrchestrationModeOverrideForbidden"
+ body = assert_problem(response, status=422, code="pipelex.deployment.orchestration_override_forbidden")
+ assert body["params"] == {"requested_mode": "temporal"}
diff --git a/api/tests/unit/test_blob_routes.py b/api/tests/unit/test_blob_routes.py
index 49aea294b..5f211e9c3 100644
--- a/api/tests/unit/test_blob_routes.py
+++ b/api/tests/unit/test_blob_routes.py
@@ -21,6 +21,7 @@ from pipelex_api.routes import router as api_router
from pipelex_api.routes.blob_upload import router as blob_upload_router
from pipelex_api.routes.version import router as version_router
from tests.unit._constants import VALID_MTHDS
+from tests.unit._problems import assert_problem
_TEMPLATE = b"<h1>A template</h1>"
_NOTES = b"Some notes"
@@ -55,13 +56,10 @@ def _upload(client: TestClient, *, target: dict[str, Any], data: bytes) -> Any:
return client.request(upload["method"], upload["url"], content=data, headers=upload["headers"])
-def _assert_problem(response: Any, *, status: int, error_type: str) -> str:
- assert response.status_code == status, response.text
- assert response.headers["content-type"].startswith("application/problem+json")
- problem = response.json()
- assert problem["error_type"] == error_type, response.text
- detail: str = problem["detail"]
- return detail
+def _assert_not_authorized(response: Any) -> None:
+ """The refusal of an upload whose target this runner did not sign: what it lacks is a signed upload target."""
+ problem = assert_problem(response, status=403, code="auth.forbidden")
+ assert problem["params"] == {"requirement": "signed_upload_target"}
class TestBlobRoutes:
@@ -99,9 +97,8 @@ class TestBlobRoutes:
client = _build_client()
(target,) = _missing(client, _TEMPLATE)
- detail = _assert_problem(_upload(client, target=target, data=_NOTES), status=422, error_type="BlobMismatch")
+ assert_problem(_upload(client, target=target, data=_NOTES), status=422, code="request.invalid", field="body")
- assert sha256_hex(_TEMPLATE) in detail
assert [blob["sha256"] for blob in _missing(client, _TEMPLATE, _NOTES)] == [sha256_hex(_TEMPLATE), sha256_hex(_NOTES)]
@pytest.mark.parametrize("tampering", ["no_query", "forged_signature", "another_scope", "another_hash"])
@@ -127,7 +124,7 @@ class TestBlobRoutes:
response = client.put(path, params=query, content=data, headers={"content-type": "application/octet-stream"})
- _assert_problem(response, status=403, error_type="BlobUploadNotAuthorized")
+ _assert_not_authorized(response)
assert len(_missing(client, _TEMPLATE, _NOTES)) == 2
def test_an_expired_target_is_refused(self, mocker: MockerFixture) -> None:
@@ -135,21 +132,20 @@ class TestBlobRoutes:
client = _build_client()
(target,) = _missing(client, _TEMPLATE)
- _assert_problem(_upload(client, target=target, data=_TEMPLATE), status=403, error_type="BlobUploadNotAuthorized")
+ _assert_not_authorized(_upload(client, target=target, data=_TEMPLATE))
def test_an_upload_past_the_per_file_limit_is_refused(self, mocker: MockerFixture) -> None:
client = _build_client()
(target,) = _missing(client, _TEMPLATE)
mocker.patch("pipelex_api.routes.blob_upload.MAX_METHOD_TREE_FILE_BYTES", len(_TEMPLATE) - 1)
- _assert_problem(_upload(client, target=target, data=_TEMPLATE), status=422, error_type="MethodTreeTooLarge")
+ problem = assert_problem(_upload(client, target=target, data=_TEMPLATE), status=413, code="request.too_large")
+ assert problem["params"] == {"limit": len(_TEMPLATE) - 1, "size": len(_TEMPLATE)}
def test_one_hash_listed_with_two_sizes_is_refused(self) -> None:
body = {"blobs": [_blob_ref(_TEMPLATE), {"sha256": sha256_hex(_TEMPLATE), "size": len(_TEMPLATE) + 1}]}
- detail = _assert_problem(_build_client().post("/v1/blobs/missing", json=body), status=422, error_type="BlobMismatch")
-
- assert sha256_hex(_TEMPLATE) in detail
+ assert_problem(_build_client().post("/v1/blobs/missing", json=body), status=422, code="request.invalid", field="blobs")
@pytest.mark.parametrize("size", [12.0, 12.5, "12", True])
def test_a_size_that_is_not_a_json_integer_is_refused(self, size: Any) -> None:
@@ -164,7 +160,8 @@ class TestBlobRoutes:
response = _build_client().post("/v1/blobs/missing", json={"blobs": [_blob_ref(_TEMPLATE), _blob_ref(_NOTES)]})
- _assert_problem(response, status=422, error_type="MethodTreeTooLarge")
+ problem = assert_problem(response, status=422, code="method.package_invalid")
+ assert problem["params"] == {"reason": "too_many_files", "limit": 1}
def test_one_scopes_blobs_are_not_held_for_another(self) -> None:
client = _build_client()
@@ -178,7 +175,7 @@ class TestBlobRoutes:
def test_a_read_scope_that_is_not_a_scope_is_refused(self) -> None:
response = _build_client().post("/v1/blobs/missing", json={"blobs": []}, params={"read_scope": "../escape"})
- _assert_problem(response, status=422, error_type="InvalidReadScope")
+ assert_problem(response, status=422, code="request.invalid", field="read_scope")
def test_a_tree_read_in_full_is_answered_by_its_digest(self) -> None:
"""Once a request sent the tree, the runner holds its listing, and asking with the tree's digest is one lookup."""
@@ -259,7 +256,7 @@ class TestBlobRoutes:
response = client.put(url.path, params=query, content=_TEMPLATE, headers={"content-type": "application/octet-stream"})
- _assert_problem(response, status=403, error_type="BlobUploadNotAuthorized")
+ _assert_not_authorized(response)
def test_upload_targets_start_with_the_configured_public_base_url(self, mocker: MockerFixture) -> None:
"""Behind a proxy terminating TLS, the URL a request arrived at is not the one a sender reaches."""
@@ -285,7 +282,7 @@ class TestBlobRoutes:
response = _build_client().post("/v1/blobs/missing", json={"blobs": [_blob_ref(_TEMPLATE)]})
- _assert_problem(response, status=500, error_type="ServerMisconfigured")
+ assert_problem(response, status=500, code="runtime.misconfigured")
def test_a_blob_held_at_another_size_is_listed_and_its_upload_never_writes_over_it(self, blob_storage: InMemoryStorageProvider) -> None:
"""Bytes held short are damaged storage: they are asked for, and their upload is a 500 that leaves the object as it is."""
@@ -295,7 +292,7 @@ class TestBlobRoutes:
(target,) = _missing(client, _TEMPLATE)
uploaded = _upload(client, target=target, data=_TEMPLATE)
- _assert_problem(uploaded, status=500, error_type="BlobStoreCorrupted")
+ assert_problem(uploaded, status=500, code="pipelex.storage.damaged")
assert blob_storage.root[f"single-tenant/blobs/{sha256_hex(_TEMPLATE)}"] == _TEMPLATE[:5]
def test_a_held_digest_answers_alone_only_for_blobs_of_its_tree(self) -> None:
diff --git a/api/tests/unit/test_blob_store.py b/api/tests/unit/test_blob_store.py
index de5a27bf1..48e07e6db 100644
--- a/api/tests/unit/test_blob_store.py
+++ b/api/tests/unit/test_blob_store.py
@@ -8,17 +8,27 @@ without a lookup per file.
import asyncio
import json
+import logging
import pytest
from mthds.method_tree.digest import digest_of_contents, sha256_hex, tree_files_from_contents, tree_listing
+from pipelex.tools.log.log_fields import carried_attributes
from pipelex.tools.storage.exceptions import StorageFileNotFoundError
+from pipelex.tools.storage.storage_config import StorageMethod
from pipelex.tools.storage.storage_provider_abstract import StorageProviderAbstract, StoredData
from pytest_mock import MockerFixture
from typing_extensions import override
-from pipelex_api.blob_store import MAX_CONCURRENT_BLOB_LOOKUPS, MAX_CONCURRENT_BLOB_TRANSFERS, RunnerBlobStore
-from pipelex_api.errors import ApiError
+from pipelex_api.blob_store import (
+ BLOB_DAMAGED_MESSAGE,
+ MAX_CONCURRENT_BLOB_LOOKUPS,
+ MAX_CONCURRENT_BLOB_TRANSFERS,
+ RunnerBlobStore,
+ problem_scheme_of,
+)
+from pipelex_api.exceptions import BlobStoreDamagedError, RunnerRequestError
from pipelex_api.method_tree_request import RequestTree, read_request_tree
+from tests.unit._problems import problem_of
_SCOPE = "single-tenant"
@@ -97,61 +107,81 @@ def _hash_map(entries: dict[str, tuple[bytes, int]]) -> str:
return json.dumps({tree_path: {"sha256": sha256_hex(data), "size": size} for tree_path, (data, size) in entries.items()})
-def _problem_of(exc_info: pytest.ExceptionInfo[ApiError]) -> dict[str, object]:
- document: dict[str, object] = exc_info.value.document
- return document
-
-
@pytest.mark.asyncio(loop_scope="class")
class TestRunnerBlobStore:
async def test_a_blob_held_at_another_size_is_refused_before_any_byte_is_read(self) -> None:
- """An entry stating a size other than the held bytes' is a `BlobMismatch`, and the census bounds every read."""
+ """An entry stating a size other than the held bytes' is a `request.invalid`, and the census bounds every read."""
storage = _CountingStorage()
- blob_store = RunnerBlobStore(scope=_SCOPE, storage=storage)
+ blob_store = RunnerBlobStore(scope=_SCOPE, storage=storage, scheme="memory")
large = b"x" * 4096
await blob_store.store_blob(data=large)
- with pytest.raises(ApiError) as exc_info:
- await read_request_tree(document=_hash_map({"large.bin": (large, 0)}), blob_store=blob_store, label="The `files` map")
+ with pytest.raises(RunnerRequestError) as exc_info:
+ await read_request_tree(document=_hash_map({"large.bin": (large, 0)}), blob_store=blob_store, label="The `files` map", field="files")
- problem = _problem_of(exc_info)
- assert exc_info.value.status_code == 422
- assert problem["error_type"] == "BlobMismatch"
- assert problem["mismatched_blobs"] == [{"sha256": sha256_hex(large), "held_size": len(large)}]
+ problem = problem_of(exc_info.value)
+ assert problem["status"] == 422
+ assert problem["code"] == "request.invalid"
+ assert problem["params"] == {"field": "files"}
+ # The hash and the size held ride the operator's message alone.
+ assert f"{sha256_hex(large)}" in problem["diagnostics"]["message"]
assert storage.loaded_keys == []
async def test_a_blob_not_held_is_missing_and_a_held_one_is_read_and_checked(self) -> None:
storage = _CountingStorage()
- blob_store = RunnerBlobStore(scope=_SCOPE, storage=storage)
+ blob_store = RunnerBlobStore(scope=_SCOPE, storage=storage, scheme="memory")
held = b"held bytes"
absent = b"absent bytes"
await blob_store.store_blob(data=held)
- with pytest.raises(ApiError) as exc_info:
+ with pytest.raises(RunnerRequestError) as exc_info:
await read_request_tree(
- document=_hash_map({"held.txt": (held, len(held)), "absent.txt": (absent, len(absent))}), blob_store=blob_store, label="The map"
+ document=_hash_map({"held.txt": (held, len(held)), "absent.txt": (absent, len(absent))}),
+ blob_store=blob_store,
+ label="The map",
+ field="files",
)
- assert _problem_of(exc_info)["missing_blobs"] == [sha256_hex(absent)]
+ problem = problem_of(exc_info.value)
+ assert problem["code"] == "request.blobs_missing"
+ assert problem["params"] == {"missing_blobs": [sha256_hex(absent)]}
- tree = await read_request_tree(document=_hash_map({"held.txt": (held, len(held))}), blob_store=blob_store, label="The map")
+ tree = await read_request_tree(document=_hash_map({"held.txt": (held, len(held))}), blob_store=blob_store, label="The map", field="files")
assert tree == RequestTree.make_from_contents(contents={"held.txt": held})
- async def test_bytes_that_do_not_hash_to_their_key_are_a_server_fault(self) -> None:
- """Damaged storage is no caller's doing, and no upload of theirs would change it: a 500 naming the hash."""
+ async def test_bytes_that_do_not_hash_to_their_key_are_a_damaged_stored_file_never_retried(self, caplog: pytest.LogCaptureFixture) -> None:
+ """A damaged object does not heal: a retry reads the same bytes, so the verdict is not to retry.
+
+ No caller's doing, and no upload of theirs would change it: storage holds the object, but not the bytes the runtime
+ stored, `pipelex.storage.damaged`, which the caller reports. Not `pipelex.storage.unavailable`, whose retry verdict would
+ send a client round its retry budget, nor `runtime.misconfigured`, which tells the operator to change a setting
+ none of which is wrong; the operator finds which object to remove in a record of its own, naming the hash.
+ """
storage = _CountingStorage()
- blob_store = RunnerBlobStore(scope=_SCOPE, storage=storage)
+ blob_store = RunnerBlobStore(scope=_SCOPE, storage=storage, scheme="memory")
data = b"the true bytes"
storage.objects[_blob_key(data)] = b"the damaged!!!"
- with pytest.raises(ApiError) as exc_info:
- await read_request_tree(document=_hash_map({"file.txt": (data, len(data))}), blob_store=blob_store, label="The map")
-
- assert exc_info.value.status_code == 500
- assert _problem_of(exc_info)["error_type"] == "BlobStoreCorrupted"
+ with caplog.at_level(logging.ERROR), pytest.raises(BlobStoreDamagedError) as exc_info:
+ await read_request_tree(document=_hash_map({"file.txt": (data, len(data))}), blob_store=blob_store, label="The map", field="files")
+
+ problem = problem_of(exc_info.value)
+ assert problem["status"] == 500
+ assert problem["code"] == "pipelex.storage.damaged"
+ assert problem["retry"] == "no"
+ assert problem["next_step"]["kind"] == "report"
+ assert problem["params"] == {"scheme": "memory"}
+ (record,) = [record for record in caplog.records if record.getMessage() == BLOB_DAMAGED_MESSAGE]
+ assert record.levelno == logging.ERROR
+ assert carried_attributes(record=record) == {
+ "blob_sha256": sha256_hex(data),
+ "blob_size_bytes": len(data),
+ "read_size_bytes": len(b"the damaged!!!"),
+ "storage_scheme": "memory",
+ }
async def test_lookups_and_reads_run_a_bounded_number_at_a_time(self) -> None:
storage = _CountingStorage()
- blob_store = RunnerBlobStore(scope=_SCOPE, storage=storage)
+ blob_store = RunnerBlobStore(scope=_SCOPE, storage=storage, scheme="memory")
blobs = [f"file number {index_blob}".encode() for index_blob in range(3 * MAX_CONCURRENT_BLOB_LOOKUPS)]
for data in blobs:
storage.objects[_blob_key(data)] = data
@@ -166,16 +196,18 @@ class TestRunnerBlobStore:
async def test_a_short_object_is_asked_for_and_its_upload_is_a_server_fault_that_writes_nothing(self) -> None:
"""A blob cut short is damaged storage, which no write repairs: nothing writes over a blob, so its operator must."""
storage = _CountingStorage()
- blob_store = RunnerBlobStore(scope=_SCOPE, storage=storage)
+ blob_store = RunnerBlobStore(scope=_SCOPE, storage=storage, scheme="memory")
data = b"the whole blob, of which a failed write kept only a part"
storage.objects[_blob_key(data)] = data[:10]
assert await blob_store.missing_blobs(sizes={sha256_hex(data): len(data)}) == [sha256_hex(data)]
- with pytest.raises(ApiError) as exc_info:
+ with pytest.raises(BlobStoreDamagedError) as exc_info:
await blob_store.store_blob(data=data)
- assert exc_info.value.status_code == 500
- assert _problem_of(exc_info)["error_type"] == "BlobStoreCorrupted"
+ problem = problem_of(exc_info.value)
+ assert problem["status"] == 500
+ assert problem["code"] == "pipelex.storage.damaged"
+ assert problem["params"] == {"scheme": "memory"}
assert storage.objects[_blob_key(data)] == data[:10]
assert storage.created == []
assert storage.unconditional_keys == []
@@ -183,7 +215,7 @@ class TestRunnerBlobStore:
async def test_blobs_and_listings_are_created_only_with_their_checksums(self) -> None:
"""Every write names its SHA-256, the blob's hash or the listing's digest, and none is unconditional."""
storage = _CountingStorage()
- blob_store = RunnerBlobStore(scope=_SCOPE, storage=storage)
+ blob_store = RunnerBlobStore(scope=_SCOPE, storage=storage, scheme="memory")
contents = {"main.mthds": b"domain = 'a'", "notes.txt": b"some notes"}
request_tree = RequestTree.make_from_contents(contents=contents)
@@ -199,7 +231,7 @@ class TestRunnerBlobStore:
async def test_files_of_the_same_bytes_are_one_blob_written_once(self) -> None:
"""Two empty `__init__.py` files name one blob key, which a tree records with one lookup and one create."""
storage = _CountingStorage()
- blob_store = RunnerBlobStore(scope=_SCOPE, storage=storage)
+ blob_store = RunnerBlobStore(scope=_SCOPE, storage=storage, scheme="memory")
contents = {"main.mthds": b"domain = 'a'", "pkg/__init__.py": b"", "pkg/sub/__init__.py": b""}
request_tree = RequestTree.make_from_contents(contents=contents)
@@ -217,7 +249,7 @@ class TestRunnerBlobStore:
async def test_a_blob_another_writer_created_meanwhile_is_held(self, mocker: MockerFixture) -> None:
"""The lookup found nothing, then the create found the key taken: the same bytes are held, and that is no error."""
storage = _CountingStorage()
- blob_store = RunnerBlobStore(scope=_SCOPE, storage=storage)
+ blob_store = RunnerBlobStore(scope=_SCOPE, storage=storage, scheme="memory")
data = b"bytes two writers send at once"
async def _absent_then_created(key: str) -> int:
@@ -234,7 +266,7 @@ class TestRunnerBlobStore:
async def test_a_tree_whose_listing_is_held_is_recorded_without_a_lookup_per_file(self) -> None:
storage = _CountingStorage()
- blob_store = RunnerBlobStore(scope=_SCOPE, storage=storage)
+ blob_store = RunnerBlobStore(scope=_SCOPE, storage=storage, scheme="memory")
contents = {f"file_{index_file}.txt": f"content {index_file}".encode() for index_file in range(5)}
request_tree = RequestTree.make_from_contents(contents=contents)
await blob_store.record_tree(tree=request_tree.tree, contents=request_tree.contents)
@@ -247,10 +279,27 @@ class TestRunnerBlobStore:
async def test_a_listing_that_is_not_the_digest_s_holds_no_tree(self) -> None:
storage = _CountingStorage()
- blob_store = RunnerBlobStore(scope=_SCOPE, storage=storage)
+ blob_store = RunnerBlobStore(scope=_SCOPE, storage=storage, scheme="memory")
contents = {"a.txt": b"a"}
digest = digest_of_contents(contents)
other_listing = tree_listing(tree_files_from_contents({"b.txt": b"b"}))
storage.objects[f"{_SCOPE}/trees/{digest.removeprefix('sha256:')}"] = other_listing
assert await blob_store.tree_hashes(tree_digest=digest) is None
+
+
+class TestProblemScheme:
+ @pytest.mark.parametrize(
+ ("storage_method", "scheme"),
+ [
+ (StorageMethod.LOCAL, "local"),
+ (StorageMethod.IN_MEMORY, "memory"),
+ (StorageMethod.S3, "s3"),
+ (StorageMethod.GCP, "gcs"),
+ ("azure", None),
+ ],
+ )
+ def test_the_problem_names_the_kind_of_storage_as_the_registry_spells_it(self, storage_method: str, scheme: str | None) -> None:
+ assert problem_scheme_of(storage_method=storage_method) == scheme
+ params = problem_of(BlobStoreDamagedError("damaged", scheme=scheme)).get("params")
+ assert params == ({"scheme": scheme} if scheme is not None else None)
diff --git a/api/tests/unit/test_bundle_archive.py b/api/tests/unit/test_bundle_archive.py
index c01a40a5d..b221c3119 100644
--- a/api/tests/unit/test_bundle_archive.py
+++ b/api/tests/unit/test_bundle_archive.py
@@ -14,7 +14,9 @@ import pytest
from pytest_mock import MockerFixture
from pipelex_api.bundle import decode_bundle_archive
-from pipelex_api.errors import ApiError
+from pipelex_api.exceptions import RequestMethodError, RunnerRequestError
+from pipelex_api.limits import base64_decoded_size
+from tests.unit._problems import problem_of
_MAIN_MTHDS = 'domain = "b"\nmain_pipe = "echo"\n'
@@ -51,46 +53,65 @@ class TestBundleArchive:
assert decode_bundle_archive(bundle_b64=bundle_b64) == [("notes.txt", b"a"), ("notes.txt", b"b")]
def test_an_empty_archive_is_refused(self):
- with pytest.raises(ApiError) as exc:
+ with pytest.raises(RunnerRequestError) as exc:
decode_bundle_archive(bundle_b64=_zip_b64([]))
- assert exc.value.status_code == 422
- assert exc.value.document["error_type"] == "InvalidBundle"
+ problem = problem_of(exc.value)
+ assert problem["status"] == 422
+ assert problem["code"] == "request.invalid"
+ assert problem["params"] == {"field": "bundle_b64"}
def test_file_count_ceiling(self, mocker: MockerFixture):
mocker.patch("pipelex_api.bundle.MAX_BUNDLE_FILES", 2)
- with pytest.raises(ApiError) as exc:
+ with pytest.raises(RequestMethodError) as exc:
decode_bundle_archive(bundle_b64=_zip_b64([(f"file_{index}.py", "x") for index in range(3)]))
- assert exc.value.status_code == 413
- assert exc.value.document["error_type"] == "PayloadTooLarge"
+ problem = problem_of(exc.value)
+ assert problem["status"] == 422
+ assert problem["code"] == "method.package_invalid"
+ # The archive's own limit on its members, which the reason tells from a tree's limit on its files.
+ assert problem["params"] == {"reason": "bundle_too_many_files", "limit": 2}
def test_zip_bomb_bounded_by_total_size(self, mocker: MockerFixture):
# A highly compressible entry that decompresses well past the (patched) ceiling must be
# refused by the bounded read, not silently expanded into memory.
mocker.patch("pipelex_api.bundle.MAX_BUNDLE_TOTAL_BYTES", 1024)
- with pytest.raises(ApiError) as exc:
+ with pytest.raises(RequestMethodError) as exc:
decode_bundle_archive(bundle_b64=_zip_b64([("bomb.txt", "A" * (1024 * 64))]))
- assert exc.value.status_code == 413
- assert exc.value.document["error_type"] == "PayloadTooLarge"
+ problem = problem_of(exc.value)
+ assert problem["status"] == 422
+ assert problem["code"] == "method.package_invalid"
+ assert problem["params"] == {"reason": "bundle_too_large", "limit": 1024}
def test_corrupt_zip_rejected(self):
not_a_zip = base64.b64encode(b"this is definitely not a zip archive").decode("ascii")
- with pytest.raises(ApiError) as exc:
+ with pytest.raises(RunnerRequestError) as exc:
decode_bundle_archive(bundle_b64=not_a_zip)
- assert exc.value.status_code == 422
- assert exc.value.document["error_type"] == "InvalidBundle"
+ problem = problem_of(exc.value)
+ assert problem["status"] == 422
+ assert problem["code"] == "request.malformed"
+ assert problem["params"] == {"reason": "bad_zip"}
def test_invalid_base64_rejected(self):
- with pytest.raises(ApiError) as exc:
+ with pytest.raises(RunnerRequestError) as exc:
decode_bundle_archive(bundle_b64="!!! not base64 !!!")
- assert exc.value.status_code == 400
- assert exc.value.document["error_type"] == "InvalidBase64"
+ problem = problem_of(exc.value)
+ assert problem["status"] == 422
+ assert problem["code"] == "request.malformed"
+ assert problem["params"] == {"reason": "bad_base64"}
def test_oversized_base64_rejected_before_decode(self, mocker: MockerFixture):
# The cheap length check on the still-encoded string fires before any b64decode.
- mocker.patch("pipelex_api.bundle._MAX_BUNDLE_B64_CHARS", 16)
+ mocker.patch("pipelex_api.bundle.MAX_BUNDLE_TOTAL_BYTES", 16)
decode_spy = mocker.spy(base64, "b64decode")
- with pytest.raises(ApiError) as exc:
+ with pytest.raises(RunnerRequestError) as exc:
decode_bundle_archive(bundle_b64="A" * 64)
- assert exc.value.status_code == 413
- assert exc.value.document["error_type"] == "PayloadTooLarge"
+ problem = problem_of(exc.value)
+ assert problem["status"] == 413
+ assert problem["code"] == "request.too_large"
+ # The limit and the size are bytes, the archive's size read off the encoded length: 64 characters carry 48 bytes.
+ assert problem["params"] == {"limit": 16, "size": 48}
decode_spy.assert_not_called()
+
+ @pytest.mark.parametrize("byte_count", [*range(10), 1023, 1024, 1025])
+ def test_the_size_read_off_an_encoded_value_is_its_decoded_size(self, byte_count: int):
+ encoded = base64.b64encode(bytes(byte_count)).decode("ascii")
+ assert base64_decoded_size(encoded=encoded) == byte_count
diff --git a/api/tests/unit/test_bundle_resources_routes.py b/api/tests/unit/test_bundle_resources_routes.py
index d41c3f1ac..a0a20c431 100644
--- a/api/tests/unit/test_bundle_resources_routes.py
+++ b/api/tests/unit/test_bundle_resources_routes.py
@@ -40,6 +40,7 @@ from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.problem_view import mark_operator_request
from pipelex_api.routes import router as api_router
from tests.unit._constants import STUB_METHOD_ADDRESS
+from tests.unit._problems import assert_problem
_PIPELINE_NS = "pipelex_api.routes.pipelex.pipeline"
_RESOURCES_NS = "pipelex_api.bundle_resources"
@@ -197,15 +198,12 @@ def _contents_body(*, route: str, resources: dict[str, str], mthds: str = _INVOI
return {"files": {"invoicing.mthds": mthds}, "resources": resources}
-def _assert_problem(response: Any, *, status: int, error_type: str) -> str:
- """An API-authored refusal: its `error_type`, and the `detail` the API wrote from what it checked."""
- assert response.status_code == status, response.text
- assert response.headers["content-type"].startswith("application/problem+json")
- problem = response.json()
- assert problem["error_type"] == error_type, response.text
+def _assert_refusal(response: Any, *, status: int, code: str, params: dict[str, Any]) -> dict[str, Any]:
+ """A refusal of the request the runner authors itself: its code, and the parameters its sentences are rendered from."""
+ problem = assert_problem(response, status=status, code=code)
+ assert problem.get("params") == params, problem
assert "is_valid" not in problem
- detail: str = problem["detail"]
- return detail
+ return problem
def _assert_coded_problem(response: Any, *, code: CoreCode, params: dict[str, Any]) -> dict[str, Any]:
@@ -226,11 +224,12 @@ def _assert_coded_problem(response: Any, *, code: CoreCode, params: dict[str, An
def _assert_the_verdict_names_the_missing_file(*, verdict: dict[str, Any], file: str, reason: str) -> None:
"""An invalid verdict whose one item is a file of the step missing from the method's tree, in the code's sentence."""
assert verdict["is_valid"] is False
- (item,) = verdict["validation_errors"]
- assert item["category"] == "pipe_validation"
- assert item["pipe_code"] == "print_invoice"
+ (item,) = verdict["errors"]
+ assert item["code"] == "method.resource_missing", item
+ assert item["params"] == {"file": file, "reason": reason}, item
+ assert item["location"]["pipe"] == "print_invoice", item
# A verdict is the caller's: its item reads `method.resource_missing`'s sentence, never the runtime's own message.
- assert item["message"] == f"The file reference '{file}' resolves to no file of the method's tree (reason: {reason})."
+ assert item["detail"] == f"The file reference '{file}' resolves to no file of the method's tree (reason: {reason})."
class TestBundleResourcesRoutes:
@@ -270,19 +269,21 @@ class TestBundleResourcesRoutes:
assert "'templates/logo.png'" in problem["diagnostics"]["message"]
@pytest.mark.parametrize(
- ("path", "reason"),
+ ("path", "code", "params"),
[
- ("/etc/invoice.docx", "absolute"),
- ("../invoice.docx", "'..' segment"),
- ("templates\\invoice.docx", "backslash"),
- ("C:invoice.docx", "drive"),
- ("invoice:v2.docx", "colon"),
+ # A path that would leave the tree is a security rule's refusal, naming the rule it broke.
+ ("/etc/invoice.docx", "security.input_path_refused", {"rule": "absolute"}),
+ ("../invoice.docx", "security.input_path_refused", {"rule": "parent_segment"}),
+ ("C:invoice.docx", "security.input_path_refused", {"rule": "absolute"}),
+ # A path no tree could hold is a malformed field.
+ ("templates\\invoice.docx", "request.invalid", {"field": "resources"}),
+ ("invoice:v2.docx", "request.invalid", {"field": "resources"}),
],
)
- def test_a_path_that_cannot_name_a_file_inside_the_bundle_is_refused(self, path: str, reason: str) -> None:
+ def test_a_path_that_cannot_name_a_file_inside_the_bundle_is_refused(self, path: str, code: str, params: dict[str, str]) -> None:
response = _build_client().post("/v1/validate", json={"mthds_contents": [_INVOICE_MTHDS], "resources": {path: _b64(_TEMPLATE_BYTES)}})
- assert reason in _assert_problem(response, status=422, error_type="InvalidResourcePath")
+ _assert_refusal(response, status=422, code=code, params=params)
@pytest.mark.parametrize("second_value", [pytest.param(_b64(b"b"), id="both_base64"), pytest.param("not base64!", id="second_not_base64")])
def test_two_spellings_of_one_file_are_refused_before_either_is_decoded(self, second_value: str) -> None:
@@ -291,31 +292,47 @@ class TestBundleResourcesRoutes:
json={"mthds_contents": [_INVOICE_MTHDS], "resources": {_TEMPLATE_PATH: _b64(b"a"), f"./{_TEMPLATE_PATH}": second_value}},
)
- assert "name the same file" in _assert_problem(response, status=422, error_type="InvalidResourcePath")
+ _assert_refusal(response, status=422, code="request.invalid", params={"field": "resources"})
def test_a_value_that_is_not_base64_is_refused(self) -> None:
response = _build_client().post("/v1/validate", json={"mthds_contents": [_INVOICE_MTHDS], "resources": {_TEMPLATE_PATH: "not base64!"}})
- _assert_problem(response, status=400, error_type="InvalidBase64")
+ _assert_refusal(response, status=422, code="request.malformed", params={"reason": "bad_base64"})
@pytest.mark.parametrize(
("limit_patches", "resources", "expected"),
[
- pytest.param({"MAX_RESOURCES_PER_REQUEST": 1}, {"a.docx": _b64(b"a"), "b.docx": _b64(b"b")}, "1-file limit", id="count"),
- pytest.param({"MAX_RESOURCE_FILE_BYTES": 2048, "_MAX_RESOURCE_B64_CHARS": 1024}, {"a.docx": _b64(bytes(1000))}, "per-file", id="encoded"),
- pytest.param({"MAX_RESOURCE_FILE_BYTES": 1024}, {"a.docx": _b64(bytes(1025))}, "per-file", id="decoded"),
- pytest.param({"MAX_RESOURCES_TOTAL_BYTES": 1024}, {"a.docx": _b64(bytes(600)), "b.docx": _b64(bytes(600))}, "total-size", id="total"),
+ pytest.param(
+ {"MAX_RESOURCES_PER_REQUEST": 1},
+ {"a.docx": _b64(b"a"), "b.docx": _b64(b"b")},
+ (422, "request.invalid", {"field": "resources"}),
+ id="count",
+ ),
+ # The limit and the size are bytes, the size read off the encoded length, never a count of encoded characters.
+ pytest.param(
+ {"MAX_RESOURCE_FILE_BYTES": 1024},
+ {"a.docx": _b64(bytes(1025))},
+ (413, "request.too_large", {"limit": 1024, "size": 1025}),
+ id="per_file",
+ ),
+ pytest.param(
+ {"MAX_RESOURCES_TOTAL_BYTES": 1024},
+ {"a.docx": _b64(bytes(600)), "b.docx": _b64(bytes(600))},
+ (413, "request.too_large", {"limit": 1024, "size": 1200}),
+ id="total",
+ ),
],
)
def test_the_limits_are_enforced_before_the_bundle_loads(
- self, mocker: MockerFixture, limit_patches: dict[str, int], resources: dict[str, str], expected: str
+ self, mocker: MockerFixture, limit_patches: dict[str, int], resources: dict[str, str], expected: tuple[int, str, dict[str, Any]]
) -> None:
+ status, code, params = expected
for name, value in limit_patches.items():
mocker.patch(f"{_RESOURCES_NS}.{name}", value)
response = _build_client().post("/v1/validate", json={"mthds_contents": [_INVOICE_MTHDS], "resources": resources})
- assert expected in _assert_problem(response, status=413, error_type="PayloadTooLarge")
+ _assert_refusal(response, status=status, code=code, params=params)
@pytest.mark.parametrize("route", ["/v1/validate", "/v1/execute", "/v1/pipe-io", "/v1/resolve", "/v1/codegen"])
def test_resources_beside_a_method_ref_are_refused(self, route: str) -> None:
@@ -327,12 +344,9 @@ class TestBundleResourcesRoutes:
response = _build_client().post(route, json=body)
- # The run route refuses it in its request model, as the runtime's `request.invalid` naming the field; the crate
- # routes refuse it themselves, with the API-authored `ValidationError`.
- if route == "/v1/execute":
- _assert_coded_problem(response, code=CoreCode.REQUEST_INVALID, params={"field": "resources"})
- else:
- assert "method_ref" in _assert_problem(response, status=422, error_type="ValidationError")
+ # The run route refuses it in its request model, the crate routes in theirs: either way, `request.invalid` naming
+ # the field to drop.
+ assert_problem(response, status=422, code="request.invalid", field="resources")
def test_a_source_label_naming_a_file_on_the_runner_never_reads_beside_it(self, mocker: MockerFixture, tmp_path: Path) -> None:
"""A caller's absolute source naming a real bundle file, with the template file beside it, reaches nothing on the runner's disk."""
@@ -364,7 +378,7 @@ class TestBundleResourcesRoutes:
verdict = response.json()
assert verdict["is_valid"] is sends_the_template, response.text
if not sends_the_template:
- assert _TEMPLATE_PATH in json.dumps(verdict["validation_errors"])
+ assert _TEMPLATE_PATH in json.dumps(verdict["errors"])
def test_resources_with_no_bundle_to_read_them_are_refused(self) -> None:
response = _build_client().post("/v1/execute", json={"pipe_code": "print_invoice", "resources": {_TEMPLATE_PATH: _b64(_TEMPLATE_BYTES)}})
@@ -481,9 +495,7 @@ class TestBundleResourcesRoutes:
"resources": {_TEMPLATE_PATH: _b64(b"another template")},
}
- detail = _assert_problem(_build_client().post("/v1/execute", json=body), status=422, error_type="InvalidResourcePath")
-
- assert f"'{_TEMPLATE_PATH}'" in detail
+ _assert_refusal(_build_client().post("/v1/execute", json=body), status=422, code="request.invalid", params={"field": "resources"})
@pytest.mark.parametrize("sends_the_logo", [True, False])
def test_a_file_only_a_template_s_relative_url_names_travels_in_the_method_s_tree(self, mocker: MockerFixture, sends_the_logo: bool) -> None:
@@ -571,5 +583,19 @@ class TestBundleResourcesRoutes:
},
)
- detail = _assert_problem(response, status=422, error_type="MethodTreeTooLarge")
- assert f"'{_TEMPLATE_PATH}'" in detail
+ problem = _assert_refusal(
+ response,
+ status=422,
+ code="method.package_invalid",
+ params={"reason": "file_too_large", "path": _TEMPLATE_PATH, "limit": len(_INVOICE_MTHDS.encode("utf-8")) + 1},
+ )
+ assert problem["location"] == {"file": _TEMPLATE_PATH}
+
+ def test_a_file_past_its_limit_is_refused_before_it_is_decoded(self, mocker: MockerFixture) -> None:
+ mocker.patch(f"{_RESOURCES_NS}.MAX_RESOURCE_FILE_BYTES", 1024)
+ decode_spy = mocker.spy(base64, "b64decode")
+
+ response = _build_client().post("/v1/validate", json={"mthds_contents": [_INVOICE_MTHDS], "resources": {"a.docx": _b64(bytes(1024 * 3))}})
+
+ _assert_refusal(response, status=413, code="request.too_large", params={"limit": 1024, "size": 1024 * 3})
+ decode_spy.assert_not_called()
diff --git a/api/tests/unit/test_codegen_route.py b/api/tests/unit/test_codegen_route.py
index 535bb9269..6f9d25eaa 100644
--- a/api/tests/unit/test_codegen_route.py
+++ b/api/tests/unit/test_codegen_route.py
@@ -22,6 +22,7 @@ from pytest_mock import MockerFixture
from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.routes import router as api_router
from tests.unit._constants import INVALID_MAIN_PIPE_MTHDS, STUB_METHOD_ADDRESS, VALID_MTHDS
+from tests.unit._problems import assert_problem
def _build_client() -> TestClient:
@@ -89,7 +90,8 @@ class TestCodegenRoute:
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is False
- assert body["validation_errors"], "an invalid verdict must carry a non-empty validation_errors[]"
+ assert body["errors"], "an invalid verdict must carry a non-empty errors[]"
+ assert all(item["code"] for item in body["errors"])
assert "artifacts" not in body
@pytest.mark.parametrize(
@@ -107,9 +109,13 @@ class TestCodegenRoute:
payload: dict[str, object] = {"files": {"main.mthds": VALID_MTHDS}, "kind": "types", "target": "ts-zod"}
payload.update(payload_patch)
response = client.post("/v1/codegen", json=payload)
- assert response.status_code == 422, response.text
- assert response.headers["content-type"] == "application/problem+json"
- assert response.json()["error_type"] == "ValidationError"
+ assert_problem(response, status=422, code="request.invalid")
+
+ def test_a_pipe_ref_on_a_concept_set_wide_kind_names_the_pipe_ref(self):
+ client = _build_client()
+ payload = {"files": {"main.mthds": VALID_MTHDS}, "kind": "types", "target": "ts-zod", "pipe_ref": "smoke.echo"}
+ response = client.post("/v1/codegen", json=payload)
+ assert_problem(response, status=422, code="request.invalid", field="pipe_ref")
def test_an_address_method_ref_projects_the_fetched_package(self, install_method_package: Callable[..., Path]):
install_method_package(files={"documents.mthds": VALID_MTHDS})
@@ -125,16 +131,13 @@ class TestCodegenRoute:
def test_the_retired_list_shape_is_refused_as_no_method_tree(self):
client = _build_client()
response = client.post("/v1/codegen", json={"files": [{"content": VALID_MTHDS}], "kind": "types", "target": "ts-zod"})
- assert response.status_code == 422, response.text
- assert response.headers["content-type"] == "application/problem+json"
- assert response.json()["error_type"] == "InvalidMethodFiles"
+ assert_problem(response, status=422, code="request.invalid", field="files")
- def test_method_ref_is_501_problem_json_until_registry_exists(self):
+ def test_a_registry_form_method_ref_is_an_unsupported_request_until_registry_exists(self):
client = _build_client()
response = client.post("/v1/codegen", json={"method_ref": "acme/methods/x", "kind": "types", "target": "ts-zod"})
- assert response.status_code == 501, response.text
- assert response.headers["content-type"] == "application/problem+json"
- assert response.json()["error_type"] == "MethodRefNotSupported"
+ problem = assert_problem(response, status=422, code="request.unsupported")
+ assert problem["params"] == {"field": "method_ref", "reason": "registry_form_method_ref"}
def test_codegen_tears_down_its_library(self, mocker: MockerFixture):
# The engine core leaves the library loaded + current on success; the route owns teardown.
diff --git a/api/tests/unit/test_error_log_records.py b/api/tests/unit/test_error_log_records.py
index a67ba6514..41afd6702 100644
--- a/api/tests/unit/test_error_log_records.py
+++ b/api/tests/unit/test_error_log_records.py
@@ -9,11 +9,13 @@ output takes in production, minus the process stream it is written to.
import json
import logging
+from collections.abc import AsyncIterator
from pathlib import Path
from typing import Any, cast
import pytest
from fastapi import APIRouter, FastAPI
+from fastapi.responses import StreamingResponse
from fastapi.testclient import TestClient
from pipelex.base_exceptions import PipelexConfigError
from pipelex.system.console_target import ConsoleTarget
@@ -21,10 +23,18 @@ from pipelex.tools.log.json_log_sink import JsonLogFormatter
from pipelex.tools.log.log_sink import LogSinkMethod
from pipelex.tools.misc.pretty import PrettyPrintMode
from pipelex.tools.misc.toml_utils import load_toml_from_path
+from pytest_mock import MockerFixture
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
-from pipelex_api.error_types import ErrorType
-from pipelex_api.errors import raise_validation_error
-from pipelex_api.exception_handlers import register_exception_handlers
+from pipelex_api.exception_handlers import (
+ ERROR_CHAIN_FIELD,
+ ERROR_FRAMES_FIELD,
+ ERROR_PARAMS_FIELD_PREFIX,
+ UNRECORDED_FAILURE_MESSAGE,
+ AnsweredErrorBarrier,
+ register_exception_handlers,
+)
+from pipelex_api.exceptions import RunnerMisconfiguredError, RunnerRequestError
from pipelex_api.middleware import REQUEST_ID_HEADER, RequestIdMiddleware
_SHIPPED_PIPELEX_CONFIG = Path(__file__).parents[2] / ".pipelex" / "pipelex.toml"
@@ -34,11 +44,40 @@ _router = APIRouter()
@_router.get("/pipelex-failure")
async def pipelex_failure_route() -> None:
- # An operator-actionable 500 — the `error`-level branch, with a traceback on the record.
+ # An operator-actionable 500 — the `error`-level branch, with the frames of its chain on the record.
msg = "the gateway config is missing"
raise PipelexConfigError(msg)
+# The text of a foreign exception a run's data can reach, such as a pydantic error quoting an input or a method
+# function's own failure: it must reach no record.
+_RUN_DATA_TEXT = "the patient's record reads: Jane Doe, born 1970-01-01"
+
+
+def _fail_on_run_data() -> None:
+ """A method function failing with a message quoting the run's data."""
+ raise ValueError(_RUN_DATA_TEXT)
+
+
+@_router.get("/chained-failure")
+async def chained_failure_route() -> None:
+ # A Pipelex 500 raised from a foreign exception whose text quotes a run's data, and raised while handling another.
+ try:
+ _fail_on_run_data()
+ except ValueError as exc:
+ msg = f"the step failed: {exc}"
+ raise PipelexConfigError(msg) from exc
+
+
+@_router.get("/implicitly-chained-failure")
+async def implicitly_chained_failure_route() -> None:
+ # A bug of ours raised while handling a foreign failure: the chain is implicit, and the catch-all answers it.
+ try:
+ _fail_on_run_data()
+ except ValueError:
+ raise KeyError(_RUN_DATA_TEXT) # noqa: B904
+
+
# The text of an exception that is not a Pipelex error, which may name anything on the host: the operator's alone.
_FOREIGN_FAILURE_TEXT = "the cache index at /srv/pipelex/private/index.db is corrupt"
@@ -49,23 +88,54 @@ async def foreign_failure_route() -> None:
raise RuntimeError(_FOREIGN_FAILURE_TEXT)
-@_router.get("/caller-mistake")
-async def caller_mistake_route(detail: str) -> None:
- # A caller-input 422 whose `detail` is exactly what the caller sent — the `warning`-level
- # branch, and the one field on the record that a caller controls.
- raise_validation_error(detail, ErrorType.VALIDATION_ERROR)
+@_router.get("/misconfigured")
+async def misconfigured_route() -> None:
+ # A runner-authored 500 naming the component misconfigured, a parameter only the operator reads.
+ msg = "the API key is not set"
+ raise RunnerMisconfiguredError(msg, component="API_KEY")
+
+
+# A marker planted in the text of a foreign exception that reaches the catch-all, which no record may carry.
+_PLANTED_MARKER = "planted-marker-7f3a: the patient's diagnosis"
+
+
+@_router.get("/planted-failure")
+async def planted_failure_route() -> None:
+ raise LookupError(_PLANTED_MARKER)
+
+
+async def _stream_failing_midway() -> AsyncIterator[bytes]:
+ """A body that fails once its first chunk, and so the response's status, has been sent."""
+ yield b"the first chunk"
+ raise LookupError(_PLANTED_MARKER)
+
+
+@_router.get("/stream-failure")
+async def stream_failure_route() -> StreamingResponse:
+ # A response that fails while it streams: the status is sent, so the failure can no longer be answered.
+ return StreamingResponse(_stream_failing_midway(), media_type="text/plain")
+
+
+@_router.get("/caller-mistake/{token:path}")
+async def caller_mistake_route(token: str) -> None:
+ # A caller-input 422 — the `warning`-level branch. Its path is exactly what the caller sent, and it rides the record
+ # as `url.path`, percent-decoded: the one field on the record that a caller controls.
+ msg = f"the token {token!r} is refused"
+ raise RunnerRequestError(msg, field="token")
-def _build_client(*, raise_server_exceptions: bool = True) -> TestClient:
+def _build_client(*, raise_server_exceptions: bool = True, with_barrier: bool = False) -> TestClient:
"""Wire a throwaway app with the production handlers and the request-id middleware.
`raise_server_exceptions` must be `False` for a route whose exception reaches the catch-all handler, which
- Starlette's `ServerErrorMiddleware` runs and then re-raises.
+ Starlette's `ServerErrorMiddleware` runs and then re-raises, unless `with_barrier` wraps the app as
+ `pipelex_api.main` does, in the `AnsweredErrorBarrier` that stops that exception before the server.
"""
app = FastAPI()
register_exception_handlers(app)
app.include_router(_router)
- return TestClient(RequestIdMiddleware(app), raise_server_exceptions=raise_server_exceptions)
+ asgi_app: ASGIApp = AnsweredErrorBarrier(app) if with_barrier else app
+ return TestClient(RequestIdMiddleware(asgi_app), raise_server_exceptions=raise_server_exceptions)
# The message every error line carries, whichever handler produced it: the key the error stream is selected by.
@@ -118,11 +188,12 @@ class TestErrorLogRecords:
assert getattr(record, "request_id", None) == response.headers[REQUEST_ID_HEADER]
assert getattr(record, "url.path", None) == "/pipelex-failure"
assert getattr(record, "error.type", None) == "PipelexConfigError"
+ assert getattr(record, ERROR_CHAIN_FIELD, None) == ["PipelexConfigError"]
- def test_an_unexpected_failure_keeps_its_class_and_text_for_the_operator_alone(self, caplog: pytest.LogCaptureFixture):
+ def test_an_unexpected_failure_keeps_its_class_and_where_it_was_raised_for_the_operator(self, caplog: pytest.LogCaptureFixture):
# The catch-all answers the caller the code's sentences, and the operator's record keeps what escaped: its class
- # as `error.type`, and its text with its traceback under `exception`, never in a field a caller-supplied value
- # could share.
+ # as `error.type`, and the frames it was raised through, never its text, which the operator view's diagnostics
+ # carry for whoever reads it.
with caplog.at_level(logging.WARNING):
response = _build_client(raise_server_exceptions=False).get("/foreign-failure")
assert response.status_code == 500
@@ -133,22 +204,239 @@ class TestErrorLogRecords:
assert record.levelno == logging.ERROR
assert getattr(record, "error.code", None) == "runtime.unexpected"
assert getattr(record, "error.type", None) == "RuntimeError"
- assert record.exc_info is not None
- assert isinstance(record.exc_info[1], RuntimeError)
+ assert record.exc_info is None
+ payload = _rendered_json(record)
+ assert "exception" not in payload
+ assert payload[ERROR_CHAIN_FIELD] == ["RuntimeError"]
+ assert any(frame.endswith(" in foreign_failure_route") for frame in payload[ERROR_FRAMES_FIELD]), payload
+ assert _FOREIGN_FAILURE_TEXT not in json.dumps(payload)
+
+ @pytest.mark.parametrize(
+ ("route", "chain", "deepest_frame"),
+ [
+ pytest.param("/chained-failure", ["PipelexConfigError", "ValueError"], "_fail_on_run_data", id="explicit-cause"),
+ pytest.param("/implicitly-chained-failure", ["KeyError", "ValueError"], "_fail_on_run_data", id="implicit-context"),
+ ],
+ )
+ def test_a_chained_foreign_exception_text_reaches_no_record(
+ self, caplog: pytest.LogCaptureFixture, route: str, chain: list[str], deepest_frame: str
+ ):
+ # A traceback prints the text of every exception of its chain, and a foreign exception's text can quote a run's
+ # inputs or a model's answer. The handler's record names the chain by class and the deepest exception's frames
+ # instead, so the run's data reaches no record, not even one the handler emits at `error`.
+ with caplog.at_level(logging.DEBUG):
+ response = _build_client(raise_server_exceptions=False).get(route)
+ assert response.status_code == 500
+ assert _RUN_DATA_TEXT not in response.text
+ record = _api_error_record(caplog)
+ assert record.levelno == logging.ERROR
+ assert record.exc_info is None
+ payload = _rendered_json(record)
+ assert payload[ERROR_CHAIN_FIELD] == chain
+ assert payload[ERROR_FRAMES_FIELD][-1].endswith(f" in {deepest_frame}"), payload
+ handler_records = [record for record in caplog.records if record.name.startswith("pipelex_api")]
+ assert handler_records
+ for handler_record in handler_records:
+ assert _RUN_DATA_TEXT not in JsonLogFormatter().format(handler_record)
+
+ def test_a_caller_view_record_names_the_operator_only_parameters(self, caplog: pytest.LogCaptureFixture):
+ # A caller's response leaves the diagnostics out, so the record is the one place the operator reads which
+ # component is misconfigured; the message, which may quote anything, still reaches no record.
+ with caplog.at_level(logging.WARNING):
+ response = _build_client().get("/misconfigured")
+ assert response.status_code == 500
+ assert "diagnostics" not in response.json()
+ assert "API_KEY" not in response.text
+ payload = _rendered_json(_api_error_record(caplog))
+ assert payload["error.code"] == "runtime.misconfigured"
+ assert payload[f"{ERROR_PARAMS_FIELD_PREFIX}component"] == "API_KEY"
+ assert "the API key is not set" not in json.dumps(payload)
+
+ def test_a_caller_parameter_is_no_operator_field(self, caplog: pytest.LogCaptureFixture):
+ # Only the parameters the registry declares operator-only ride the record: a caller's refusal names its field
+ # in the response, and the record adds nothing under `error.params.`.
+ with caplog.at_level(logging.WARNING):
+ _build_client().get("/caller-mistake/malformed")
+ payload = _rendered_json(_api_error_record(caplog))
+ assert not [key for key in payload if key.startswith(ERROR_PARAMS_FIELD_PREFIX)], payload
+
+ def test_an_answered_exception_reaches_no_record_and_no_server(self, caplog: pytest.LogCaptureFixture):
+ # Starlette's `ServerErrorMiddleware` raises the exception again once the catch-all answered it, for the server
+ # to log with its traceback, which prints the exception's text. The barrier stops it: the test client, which
+ # raises whatever leaves the app, receives the answer, and no record anywhere carries the planted text.
+ with caplog.at_level(logging.DEBUG):
+ response = _build_client(with_barrier=True).get("/planted-failure")
+ assert response.status_code == 500
+ assert response.json()["code"] == "runtime.unexpected"
+ assert _PLANTED_MARKER not in response.text
+ assert _api_error_record(caplog).levelno == logging.ERROR
+ for record in caplog.records:
+ assert record.exc_info is None, record
+ assert _PLANTED_MARKER not in JsonLogFormatter().format(record)
+
+ def test_without_the_barrier_the_answered_exception_leaves_the_app(self):
+ # What the barrier stops: the exception, its text included, reaching whatever runs the app.
+ with pytest.raises(LookupError, match="planted-marker"):
+ _build_client().get("/planted-failure")
+
+ @pytest.mark.asyncio
+ async def test_the_barrier_answers_a_failure_no_handler_answered(self, caplog: pytest.LogCaptureFixture):
+ # A failure that started no response, which only a failure of the handlers themselves leaves, is answered and
+ # recorded here like any other, by class.
+ async def failing_app(_scope: Scope, _receive: Receive, _send: Send) -> None:
+ raise LookupError(_PLANTED_MARKER)
+
+ sent: list[Message] = []
+
+ async def receive() -> Message:
+ return {"type": "http.request", "body": b"", "more_body": False}
+
+ async def send(message: Message) -> None:
+ sent.append(message)
+
+ scope: Scope = {"type": "http", "method": "GET", "path": "/", "raw_path": b"/", "query_string": b"", "headers": [], "app": None}
+ with caplog.at_level(logging.DEBUG):
+ await AnsweredErrorBarrier(failing_app)(scope, receive, send)
+ assert sent[0]["type"] == "http.response.start"
+ assert sent[0]["status"] == 500
+ body = json.loads(b"".join(message.get("body", b"") for message in sent if message["type"] == "http.response.body"))
+ assert body["code"] == "runtime.unexpected"
+ for record in caplog.records:
+ assert _PLANTED_MARKER not in JsonLogFormatter().format(record)
+
+ @pytest.mark.asyncio
+ async def test_the_barrier_records_and_drops_a_failure_to_send_its_own_answer(self, caplog: pytest.LogCaptureFixture):
+ # The barrier answers a failure no handler answered, and the server fails to send that answer, as it does for a
+ # client already gone: the failure is recorded by class and dropped, never raised to the server.
+ async def failing_app(_scope: Scope, _receive: Receive, _send: Send) -> None:
+ raise LookupError(_PLANTED_MARKER)
+
+ async def receive() -> Message:
+ return {"type": "http.request", "body": b"", "more_body": False}
+
+ async def send(_message: Message) -> None:
+ raise ConnectionResetError(_PLANTED_MARKER)
+
+ scope: Scope = {"type": "http", "method": "GET", "path": "/gone", "raw_path": b"/gone", "query_string": b"", "headers": [], "app": None}
+ with caplog.at_level(logging.DEBUG):
+ await AnsweredErrorBarrier(failing_app)(scope, receive, send)
+ (record,) = [record for record in caplog.records if record.getMessage() == UNRECORDED_FAILURE_MESSAGE]
+ payload = _rendered_json(record)
+ assert payload["url.path"] == "/gone"
+ assert payload["http.response.status_code"] == 500
+ assert payload["error.type"] == "ConnectionResetError"
+ for any_record in caplog.records:
+ assert any_record.exc_info is None, any_record
+ assert _PLANTED_MARKER not in JsonLogFormatter().format(any_record)
+
+ @pytest.mark.asyncio
+ async def test_the_barrier_records_and_drops_a_failure_of_the_catch_all_before_any_response(
+ self, caplog: pytest.LogCaptureFixture, mocker: MockerFixture
+ ):
+ # The catch-all fails while the barrier builds its answer, before any status was sent: nothing can be answered,
+ # so the failure is recorded by class, naming no status, and dropped, leaving the server to answer for it.
+ mocker.patch("pipelex_api.exception_handlers.make_unexpected_failure", side_effect=KeyError(_PLANTED_MARKER))
+
+ async def failing_app(_scope: Scope, _receive: Receive, _send: Send) -> None:
+ raise LookupError(_PLANTED_MARKER)
+
+ async def receive() -> Message:
+ return {"type": "http.request", "body": b"", "more_body": False}
+
+ sent: list[Message] = []
+
+ async def send(message: Message) -> None:
+ sent.append(message)
+
+ scope: Scope = {"type": "http", "method": "GET", "path": "/", "raw_path": b"/", "query_string": b"", "headers": [], "app": None}
+ with caplog.at_level(logging.DEBUG):
+ await AnsweredErrorBarrier(failing_app)(scope, receive, send)
+ assert sent == []
+ (record,) = [record for record in caplog.records if record.getMessage() == UNRECORDED_FAILURE_MESSAGE]
+ payload = _rendered_json(record)
+ assert "http.response.status_code" not in payload
+ assert payload["error.type"] == "KeyError"
+ assert payload[ERROR_CHAIN_FIELD] == ["KeyError", "LookupError"]
+ for any_record in caplog.records:
+ assert _PLANTED_MARKER not in JsonLogFormatter().format(any_record)
+
+ def test_a_failure_the_catch_all_answered_mid_stream_is_recorded_once(self, caplog: pytest.LogCaptureFixture):
+ # Starlette runs the catch-all handler even once the response has started, and it writes the failure's record:
+ # the barrier then drops the exception Starlette raises again, writing nothing more.
+ with caplog.at_level(logging.DEBUG):
+ response = _build_client(with_barrier=True).get("/stream-failure")
+ assert response.status_code == 200
+ assert _api_error_record(caplog).levelno == logging.ERROR
+ assert not [record for record in caplog.records if record.getMessage() == UNRECORDED_FAILURE_MESSAGE]
+
+ def test_a_catch_all_failing_mid_stream_leaves_a_record_naming_the_chain(self, caplog: pytest.LogCaptureFixture, mocker: MockerFixture):
+ # The catch-all handler itself fails while the response streams: Starlette raises the handler's exception, which
+ # no handler recorded, so the barrier records it by class before dropping it, never with any exception's text.
+ handler_bug = KeyError(_PLANTED_MARKER)
+ mocker.patch("pipelex_api.exception_handlers.make_unexpected_failure", side_effect=handler_bug)
+ with caplog.at_level(logging.DEBUG):
+ response = _build_client(with_barrier=True).get("/stream-failure")
+ assert response.status_code == 200
+ (record,) = [record for record in caplog.records if record.getMessage() == UNRECORDED_FAILURE_MESSAGE]
+ assert record.levelno == logging.ERROR
+ payload = _rendered_json(record)
+ assert payload["url.path"] == "/stream-failure"
+ assert payload["http.response.status_code"] == 200
+ assert payload["error.type"] == "KeyError"
+ # Raised while the handler answered the stream's own failure, which the chain names after it.
+ assert payload[ERROR_CHAIN_FIELD] == ["KeyError", "LookupError"]
+ assert ERROR_FRAMES_FIELD not in payload
+ # The request it ended, from the log context the middleware bound, still open around the barrier.
+ assert getattr(record, "request_id", None) == response.headers[REQUEST_ID_HEADER]
+ for any_record in caplog.records:
+ assert any_record.exc_info is None, any_record
+ assert _PLANTED_MARKER not in JsonLogFormatter().format(any_record)
+
+ @pytest.mark.asyncio
+ async def test_the_barrier_records_a_failure_no_handler_saw_after_the_response_started(self, caplog: pytest.LogCaptureFixture):
+ # A failure that reaches the barrier with the response started and no handler's mark on it is recorded, by class.
+ async def failing_app(_scope: Scope, _receive: Receive, send: Send) -> None:
+ await send({"type": "http.response.start", "status": 201, "headers": []})
+ try:
+ _fail_on_run_data()
+ except ValueError as exc:
+ raise RuntimeError(_PLANTED_MARKER) from exc
+
+ async def receive() -> Message:
+ return {"type": "http.request", "body": b"", "more_body": False}
+
+ sent: list[Message] = []
+
+ async def send(message: Message) -> None:
+ sent.append(message)
+
+ scope: Scope = {"type": "http", "method": "GET", "path": "/started", "raw_path": b"/started", "query_string": b"", "headers": [], "app": None}
+ with caplog.at_level(logging.DEBUG):
+ await AnsweredErrorBarrier(failing_app)(scope, receive, send)
+ assert [message["type"] for message in sent] == ["http.response.start"]
+ (record,) = [record for record in caplog.records if record.getMessage() == UNRECORDED_FAILURE_MESSAGE]
payload = _rendered_json(record)
- assert f"RuntimeError: {_FOREIGN_FAILURE_TEXT}" in payload["exception"]
+ assert payload["http.response.status_code"] == 201
+ assert payload[ERROR_CHAIN_FIELD] == ["RuntimeError", "ValueError"]
+ for any_record in caplog.records:
+ formatted = JsonLogFormatter().format(any_record)
+ assert _PLANTED_MARKER not in formatted
+ assert _RUN_DATA_TEXT not in formatted
def test_a_caller_mistake_records_a_warning_carrying_the_same_identifiers(self, caplog: pytest.LogCaptureFixture):
# A 4xx is a caller mistake, so it lands at `warning` — but it carries the same message and
# the same two identifiers, so one query over the message returns the whole error stream of a request.
with caplog.at_level(logging.WARNING):
- response = _build_client().get("/caller-mistake", params={"detail": "the input is malformed"})
+ response = _build_client().get("/caller-mistake/malformed")
assert response.status_code == 422
record = _api_error_record(caplog)
assert record.levelno == logging.WARNING
assert getattr(record, "request_id", None) == response.headers[REQUEST_ID_HEADER]
- assert getattr(record, "url.path", None) == "/caller-mistake"
+ assert getattr(record, "url.path", None) == "/caller-mistake/malformed"
assert getattr(record, "http.response.status_code", None) == 422
+ assert getattr(record, "error.code", None) == "request.invalid"
+ assert getattr(record, ERROR_CHAIN_FIELD, None) == ["RunnerRequestError"]
+ assert getattr(record, ERROR_FRAMES_FIELD, None) is None
def test_the_json_sink_writes_one_object_per_line_with_the_fields_flat(self, caplog: pytest.LogCaptureFixture):
# The shape the runner's configured sink puts on stderr: the sink's own keys, then every
@@ -167,47 +455,46 @@ class TestErrorLogRecords:
# `retryable` is the verdict of the error's code, which every error carries, so it is always
# written: `pipelex.config.invalid` is no fault a repeat can cure.
assert payload["retryable"] is False
- # `time` and `logger` come from the sink itself; an operator-actionable failure carries
- # its traceback under `exception` rather than spilling it across the line.
+ # `time` and `logger` come from the sink itself. An operator-actionable failure carries its chain by class and
+ # the frames it was raised through as fields, and no traceback, which would print its text.
assert payload["time"].endswith("Z")
- assert "PipelexConfigError" in payload["exception"]
+ assert "exception" not in payload
+ assert payload[ERROR_CHAIN_FIELD] == ["PipelexConfigError"]
+ assert any(frame.endswith(" in pipelex_failure_route") for frame in payload[ERROR_FRAMES_FIELD]), payload
@pytest.mark.parametrize(
- ("crafted_detail", "logged_detail"),
+ ("crafted_segment", "logged_path"),
[
# Back when the API flattened its own fields into a `key=value` run, each of these
- # forged either a sibling field or a whole second line. The API renders nothing now:
- # the runtime escapes a control character in a field's value and the sink escapes what
- # it writes, so each must survive as one field's value.
- ("legit\nstatus=200 event=auth_success", "legit\\nstatus=200 event=auth_success"),
- ("hijack status=200 event=fake", "hijack status=200 event=fake"),
- ("legit\rstatus=200", "legit\\rstatus=200"),
- ('has " a quote = inside', 'has " a quote = inside'),
+ # forged either a sibling field or a whole second line. The API renders nothing now: the
+ # URL parser drops a control character from the path the record carries, and the sink
+ # writes each value inside one string, so each must survive as one field's value.
+ ("legit%0Astatus=200 event=auth_success", "/unserved/legitstatus=200 event=auth_success"),
+ ("hijack status=200 event=fake", "/unserved/hijack status=200 event=fake"),
+ ("legit%0Dstatus=200", "/unserved/legitstatus=200"),
+ ('has " a quote = inside', '/unserved/has " a quote = inside'),
],
)
- def test_a_crafted_detail_survives_as_one_value_and_forges_nothing(
- self, caplog: pytest.LogCaptureFixture, crafted_detail: str, logged_detail: str
- ):
- # The escaping the API used to do itself is the runtime's job now, in two layers. The
- # redaction processor every sink sits behind turns a control character in a field's value
- # into its printable escape, so a newline the caller sent reads `\n` in `detail`; then
- # `json.dumps` writes each value inside one string, so a quote or an `=` stays part of it.
- # Either way the line stays one object and the value comes back as one field.
- with caplog.at_level(logging.WARNING):
- response = _build_client().get("/caller-mistake", params={"detail": crafted_detail})
- assert response.status_code == 422
+ def test_a_crafted_path_survives_as_one_value_and_forges_nothing(self, caplog: pytest.LogCaptureFixture, crafted_segment: str, logged_path: str):
+ # The path a caller sends is the one value of the record it controls whatever the route, a path no route serves
+ # included, whose record is a debug one. `json.dumps` writes each value inside one string, so a quote or an `=`
+ # stays part of it, and the line stays one object with the value as one field.
+ with caplog.at_level(logging.DEBUG):
+ response = _build_client().get(f"/unserved/{crafted_segment}")
+ assert response.status_code == 404
payload = _rendered_json(_api_error_record(caplog))
- assert payload["detail"] == logged_detail
- assert "event" not in payload, "a crafted detail forged a field"
- assert payload["http.response.status_code"] == 422, "a crafted detail forged or overwrote a field"
+ assert payload["url.path"] == logged_path
+ assert payload["error.code"] == "request.not_found"
+ assert "event" not in payload, "a crafted path forged a field"
+ assert payload["http.response.status_code"] == 404, "a crafted path forged or overwrote a field"
assert payload["message"] == _ERROR_MESSAGE, "caller input reached the message"
- def test_a_credential_echoed_into_a_detail_is_redacted_on_the_line(self, caplog: pytest.LogCaptureFixture):
- # A validation message can echo what the caller sent, header text included. The runtime's
+ def test_a_credential_echoed_into_a_path_is_redacted_on_the_line(self, caplog: pytest.LogCaptureFixture):
+ # A request line can carry what the caller sent, header text included. The runtime's
# redaction processor scrubs the credential out of the field before the sink writes it, and
# keeps the scheme, so the line still says which kind of credential went.
with caplog.at_level(logging.WARNING):
- response = _build_client().get("/caller-mistake", params={"detail": "rejected Authorization: Bearer placeholder-not-a-token"})
+ response = _build_client().get("/caller-mistake/rejected Authorization: Bearer placeholder-not-a-token")
assert response.status_code == 422
payload = _rendered_json(_api_error_record(caplog))
- assert payload["detail"] == "rejected Authorization: Bearer [REDACTED]"
+ assert payload["url.path"] == "/caller-mistake/rejected Authorization: Bearer [REDACTED]"
diff --git a/api/tests/unit/test_error_responses.py b/api/tests/unit/test_error_responses.py
index 68c9471db..805b80a57 100644
--- a/api/tests/unit/test_error_responses.py
+++ b/api/tests/unit/test_error_responses.py
@@ -1,19 +1,13 @@
-"""Phase 3 regression tests — every API error path emits one RFC 7807 shape.
-
-Builds a production-faithful app (the real routers, the global exception
-handlers, `RequestIdMiddleware`, the body-size middleware) and asserts that
-4xx/5xx responses across the surface are `application/problem+json` with the
-RFC 7807 fields and an `X-Request-ID` header — never the old
-`{"detail": {...}}` envelope, and never FastAPI's default `{"detail": [...]}`
-for automatic request validation. Covers regression checks T1 (413), T2
-(a route-level 403) and T5 (`X-Request-ID` on every error response).
-
-The 400/403/401 vehicles used to be the storage and upload routes. Those moved
-to the hosted platform, so each assertion now rides a different route that
-raises through the same helper — the envelope is what is under test, never the
-route that produced it.
+"""Every error path of the runner answers one shape: the problem document of a registry code.
+
+Builds a production-faithful app (the real routers, the global exception handlers, `RequestIdMiddleware`, the body-size
+middleware) and asserts that 4xx and 5xx responses across the surface are `application/problem+json` carrying a code,
+the status that code declares, the request's id, which also rides the `X-Request-ID` header, and no `instance` — never
+the old `{"detail": {...}}` envelope, and never FastAPI's default `{"detail": [...]}` for automatic request validation.
+The envelope is what is under test, never the route that produced it.
"""
+import json
from collections.abc import Iterator
from importlib.metadata import PackageNotFoundError
@@ -23,12 +17,14 @@ from fastapi.testclient import TestClient
from pytest_mock import MockerFixture
from starlette.middleware.base import BaseHTTPMiddleware
-from pipelex_api.exception_handlers import register_exception_handlers
+from pipelex_api import json_body
+from pipelex_api.exception_handlers import AnsweredErrorBarrier, register_exception_handlers
+from pipelex_api.limits import MAX_REQUEST_BODY_BYTES
from pipelex_api.middleware import REQUEST_ID_HEADER, RequestIdMiddleware, request_body_size_middleware
-from pipelex_api.problem_document import PROBLEM_JSON_MEDIA_TYPE
from pipelex_api.routes import router as api_router
from pipelex_api.routes.version import router as version_router
from pipelex_api.security import RequestUser, get_request_user, verify_api_key
+from tests.unit._problems import assert_problem, problem_items_fields
USER_A = "aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa"
USER_B = "bbbbbbbb-bbbb-4bbb-bbbb-bbbbbbbbbbbb"
@@ -38,15 +34,15 @@ FILE_HASH = "cccccccc-cccc-4ccc-cccc-cccccccccccc"
def _build_client(*, user: RequestUser | None = None, with_auth: bool = False) -> TestClient:
"""Wire a production-faithful app: real routers, handlers, both middlewares.
- `RequestIdMiddleware` wraps the whole app exactly as in `pipelex_api.main`, so the
- request-id contextvars are bound and `X-Request-ID` is stamped on every
- response. `get_request_user` is overridden so routes see the caller
+ `RequestIdMiddleware` wraps the whole app, through `AnsweredErrorBarrier`, exactly as
+ in `pipelex_api.main`, so the request-id contextvars are bound and `X-Request-ID` is
+ stamped on every response. `get_request_user` is overridden so routes see the caller
identity the test wants.
- `with_auth` mounts the composite router behind the SAME `auth_dependency`
- `pipelex_api.main` uses, which is the only way to reach a real 401 — every
- `raise_unauthenticated` lives in the verifiers that dependency runs, not in
- a route body.
+ `with_auth` mounts the composite router behind an authentication dependency
+ `pipelex_api.main` can select, the API key's verifier, which is the only way to reach
+ a real 401: every authentication refusal, a `RunnerAuthError`, is raised by the
+ verifier that dependency runs, not in a route body.
"""
app = FastAPI(redirect_slashes=False)
app.add_middleware(BaseHTTPMiddleware, dispatch=request_body_size_middleware)
@@ -61,87 +57,65 @@ def _build_client(*, user: RequestUser | None = None, with_auth: bool = False) -
return user
app.dependency_overrides[get_request_user] = _override_user
- return TestClient(RequestIdMiddleware(app))
+ return TestClient(RequestIdMiddleware(AnsweredErrorBarrier(app)))
class TestErrorResponses:
- def test_validation_error_is_rfc7807_input_domain(self):
- # /models with an unknown category → raise_validation_error → 422.
+ def test_a_refused_field_is_a_request_invalid_problem_in_the_input_domain(self):
+ # /models with an unknown category: the runner refuses the field itself.
response = _build_client().get("/v1/models?type=not-a-real-category")
- assert response.status_code == 422
- assert response.headers["content-type"] == PROBLEM_JSON_MEDIA_TYPE
- body = response.json()
- assert body["error_type"] == "InvalidModelCategory"
- assert body["error_domain"] == "input"
- assert body["instance"] == "/v1/models"
- assert body["status"] == 422
+ body = assert_problem(response, status=422, code="request.invalid", field="type")
+ assert body["domain"] == "input"
assert body["request_id"] == response.headers[REQUEST_ID_HEADER]
- # API-authored caller-input errors are non-retryable across the surface.
- assert body["retryable"] is False
+ # A caller's mistake is not retried as it is.
+ assert body["retry"] == "no"
- def test_request_validation_error_is_rfc7807(self):
- # FastAPI's automatic body validation (here: mthds_contents below its
- # min_length) must answer in the same RFC 7807 shape as every other
- # path — not FastAPI's default {"detail": [...]} / application/json.
+ def test_a_body_the_route_model_refuses_is_the_same_problem(self):
+ # FastAPI's automatic body validation (here: mthds_contents below its min_length) answers in the same shape as
+ # every other path — not FastAPI's default {"detail": [...]} / application/json.
response = _build_client().post("/v1/validate", json={"mthds_contents": []})
- assert response.status_code == 422
- assert response.headers["content-type"] == PROBLEM_JSON_MEDIA_TYPE
- body = response.json()
- assert body["error_type"] == "ValidationError"
- assert body["error_domain"] == "input"
- assert body["status"] == 422
- assert body["instance"] == "/v1/validate"
- assert isinstance(body["detail"], str)
- assert "mthds_contents" in body["detail"]
+ body = assert_problem(response, status=422, code="request.invalid", field="mthds_contents")
+ assert body["domain"] == "input"
+ assert body["detail"] == "The request's field 'mthds_contents' does not match the route's schema."
+ assert problem_items_fields(body) == ["mthds_contents"]
assert body["request_id"] == response.headers[REQUEST_ID_HEADER]
- assert body["retryable"] is False
+ assert body["retry"] == "no"
- def test_bad_request_is_rfc7807(self):
- # A `bundle_b64` that is not valid base64 → raise_bad_request → 400.
+ def test_an_encoded_part_that_cannot_be_decoded_is_a_malformed_request(self):
+ # A `bundle_b64` that is not valid base64: the request cannot be read, a 422 like every caller's mistake.
client = _build_client(user=RequestUser(user_id=USER_A))
response = client.post("/v1/execute", json={"bundle_b64": "not!base64", "pipe_code": "smoke"})
- assert response.status_code == 400
- assert response.headers["content-type"] == PROBLEM_JSON_MEDIA_TYPE
- body = response.json()
- assert body["error_type"] == "InvalidBase64"
- assert body["error_domain"] == "input"
+ body = assert_problem(response, status=422, code="request.malformed")
+ assert body["params"] == {"reason": "bad_base64"}
+ assert body["domain"] == "input"
assert body["request_id"] == response.headers[REQUEST_ID_HEADER]
- assert body["retryable"] is False
+ assert body["retry"] == "no"
- def test_forbidden_is_rfc7807(self):
- # REGRESSION T2: a per-request orchestration-mode override the
- # deployment forbids → raise_forbidden → 403.
+ def test_a_deployment_policy_refusal_is_its_own_code(self):
+ # A per-request orchestration-mode override the deployment forbids: the request is the caller's to change.
client = _build_client(user=RequestUser(user_id=USER_A))
response = client.post(
"/v1/execute",
json={"mthds_contents": ['domain = "smoke"'], "pipe_code": "smoke", "orchestration_mode": "definitely-not-the-default"},
)
- assert response.status_code == 403
- assert response.headers["content-type"] == PROBLEM_JSON_MEDIA_TYPE
- body = response.json()
- assert body["error_type"] == "OrchestrationModeOverrideForbidden"
- assert body["status"] == 403
+ body = assert_problem(response, status=422, code="pipelex.deployment.orchestration_override_forbidden")
+ assert body["params"] == {"requested_mode": "definitely-not-the-default"}
assert body["request_id"] == response.headers[REQUEST_ID_HEADER]
- assert body["retryable"] is False
+ assert body["retry"] == "no"
- def test_payload_too_large_is_rfc7807(self):
- # REGRESSION T1: a body over the cap → 413 via the body-size middleware.
+ def test_a_body_past_the_size_limit_is_a_too_large_problem(self):
+ # A declared body over the cap: a 413 from the body-size middleware, before any route runs.
response = _build_client().get(
"/v1/version",
headers={"content-length": str(200 * 1024 * 1024)},
)
- assert response.status_code == 413
- assert response.headers["content-type"] == PROBLEM_JSON_MEDIA_TYPE
- body = response.json()
- assert body["error_type"] == "PayloadTooLarge"
- assert body["error_domain"] == "input"
- assert body["status"] == 413
- # The body-size middleware has to return a response rather than raise, so it builds its own
- # problem document — and it reads the route and the id off the `Request` it was handed,
- # like every other error path.
- assert body["instance"] == "/v1/version"
+ body = assert_problem(response, status=413, code="request.too_large")
+ assert body["params"] == {"limit": MAX_REQUEST_BODY_BYTES, "size": 200 * 1024 * 1024}
+ assert body["domain"] == "input"
+ # The body-size middleware has to return a response rather than raise, so it renders the problem itself, and it
+ # reads the request's id off the `Request` it was handed, like every other error path.
assert body["request_id"] == response.headers[REQUEST_ID_HEADER]
- assert body["retryable"] is False
+ assert body["retry"] == "no"
def test_payload_too_large_chunked_does_not_buffer_oversized_body(self, mocker: MockerFixture):
# REGRESSION T1b: a chunked / no-content-length over-limit body must reject
@@ -173,40 +147,68 @@ class TestErrorResponses:
response = client.post("/echo", content=streaming_body())
- assert response.status_code == 413
- assert response.headers["content-type"] == PROBLEM_JSON_MEDIA_TYPE
- assert response.json()["error_type"] == "PayloadTooLarge"
+ body = assert_problem(response, status=413, code="request.too_large")
+ # A body streamed without a declared length is refused at the first chunk past the limit, which is all it read.
+ assert body["params"]["limit"] == 1024
# With the fix, the over-limit first chunk is replaced with an end-of-stream
# marker, so the route observes an empty body. Without the fix, the route
# would see all 4096 bytes.
assert bytes_seen_by_route == [0]
- def test_internal_server_error_is_rfc7807_config_domain(self, mocker: MockerFixture):
- # Absent package metadata → raise_internal_server_error → 500 CONFIG.
+ def test_a_typed_route_reads_its_body_through_the_size_limit(self, mocker: MockerFixture):
+ # `JsonBodyRoute` reads a typed body itself, before FastAPI: it must read it through the body-size middleware's
+ # counting `receive`, once, so a body streamed past the limit is refused as too large rather than parsed.
+ mocker.patch("pipelex_api.middleware.MAX_REQUEST_BODY_BYTES", 1024)
+ parse_spy = mocker.spy(json_body, "parse_typed_json_body")
+ runner_spy = mocker.patch("pipelex_api.routes.pipelex.validate.ApiRunner")
+ over_limit = json.dumps({"mthds_contents": ["x" * 4096]}).encode("utf-8")
+
+ def streaming_body() -> Iterator[bytes]:
+ yield over_limit
+
+ response = _build_client().post("/v1/validate", content=streaming_body(), headers={"content-type": "application/json"})
+
+ body = assert_problem(response, status=413, code="request.too_large")
+ assert body["params"] == {"limit": 1024, "size": len(over_limit)}
+ # The route read the end of stream the middleware put in place of the over-limit chunk, never the body itself.
+ parse_spy.assert_not_called()
+ runner_spy.assert_not_called()
+
+ def test_a_typed_route_reads_a_body_within_the_limit_once(self, mocker: MockerFixture):
+ # The same route reading the same middleware's `receive` gets the whole body when it is within the limit, and
+ # FastAPI validates the value the route parsed, reading the body no second time.
+ mocker.patch("pipelex_api.middleware.MAX_REQUEST_BODY_BYTES", 1024)
+ parse_spy = mocker.spy(json_body, "parse_typed_json_body")
+
+ def streaming_body() -> Iterator[bytes]:
+ yield b'{"mthds_contents": []}'
+
+ response = _build_client().post("/v1/validate", content=streaming_body(), headers={"content-type": "application/json"})
+
+ # An empty list is refused by the route's model, which proves the model read the parsed body.
+ assert_problem(response, status=422, code="request.invalid")
+ assert parse_spy.call_count == 1
+
+ def test_a_misconfigured_runner_is_a_runtime_problem(self, mocker: MockerFixture):
+ # Absent package metadata: the installation, not the request, is at fault.
mocker.patch("pipelex_api.routes.version.version", side_effect=PackageNotFoundError("pipelex"))
response = _build_client().get("/v1/version")
- assert response.status_code == 500
- assert response.headers["content-type"] == PROBLEM_JSON_MEDIA_TYPE
- body = response.json()
- assert body["error_type"] == "PackageNotFound"
- assert body["error_domain"] == "config"
- assert body["status"] == 500
+ body = assert_problem(response, status=500, code="runtime.misconfigured")
+ assert body["domain"] == "operator"
assert body["request_id"] == response.headers[REQUEST_ID_HEADER]
- # An API-owned 5xx is non-retryable: the operator, not the caller,
- # fixes a missing package; the symmetry with the 4xx paths is the
- # uniform retry contract clients can rely on.
- assert body["retryable"] is False
+ # The operator, not the caller, fixes a missing package, so the caller does not retry it.
+ assert body["retry"] == "no"
+ # Which component is misconfigured is the operator's to read, never the caller's.
+ assert "params" not in body
+ assert "diagnostics" not in body
def test_unauthenticated_carries_www_authenticate_challenge(self):
# No Authorization header on an auth-wrapped route → 401 + challenge.
response = _build_client(user=None, with_auth=True).post("/v1/validate", json={"mthds_contents": ['domain = "smoke"']})
- assert response.status_code == 401
- assert response.headers["content-type"] == PROBLEM_JSON_MEDIA_TYPE
+ body = assert_problem(response, status=401, code="auth.missing_credential")
assert response.headers["WWW-Authenticate"] == "Bearer"
- body = response.json()
- assert body["error_type"] == "Unauthenticated"
assert body["request_id"] == response.headers[REQUEST_ID_HEADER]
- assert body["retryable"] is False
+ assert body["retry"] == "no"
def test_inbound_request_id_is_echoed_into_error_body(self):
# A caller-supplied X-Request-ID rides through to the response body.
diff --git a/api/tests/unit/test_error_uri.py b/api/tests/unit/test_error_uri.py
deleted file mode 100644
index 04ecb1916..000000000
--- a/api/tests/unit/test_error_uri.py
+++ /dev/null
@@ -1,35 +0,0 @@
-"""Unit tests for the RFC 7807 type-URI and title helpers."""
-
-import pytest
-
-from pipelex_api.error_uri import error_type_title, error_type_uri
-
-
-class TestErrorUri:
- @pytest.mark.parametrize(
- ("error_type", "expected"),
- [
- ("EnvVarNotFoundError", "https://docs.pipelex.com/latest/errors/env-var-not-found-error/"),
- ("ValidationError", "https://docs.pipelex.com/latest/errors/validation-error/"),
- ("PayloadTooLarge", "https://docs.pipelex.com/latest/errors/payload-too-large/"),
- ("InvalidJSON", "https://docs.pipelex.com/latest/errors/invalid-json/"),
- ("LLMCompletionError", "https://docs.pipelex.com/latest/errors/llm-completion-error/"),
- ],
- )
- def test_error_type_uri(self, error_type: str, expected: str):
- assert error_type_uri(error_type) == expected
-
- @pytest.mark.parametrize(
- ("error_type", "expected"),
- [
- ("EnvVarNotFoundError", "Env var not found error"),
- ("ValidationError", "Validation error"),
- ("PayloadTooLarge", "Payload too large"),
- ("BadRequest", "Bad request"),
- # A trailing acronym is preserved by pipelex's pascal_case_to_sentence
- # (`InvalidJSON` → `Invalid JSON`); pinned so the behavior is visible.
- ("InvalidJSON", "Invalid JSON"),
- ],
- )
- def test_error_type_title(self, error_type: str, expected: str):
- assert error_type_title(error_type) == expected
diff --git a/api/tests/unit/test_exception_handlers.py b/api/tests/unit/test_exception_handlers.py
index 12946425f..bfbdf50c6 100644
--- a/api/tests/unit/test_exception_handlers.py
+++ b/api/tests/unit/test_exception_handlers.py
@@ -1,7 +1,7 @@
"""Integration tests for the global FastAPI exception handlers.
These tests register the production handlers on a throwaway FastAPI app whose
-routes raise straight through — `ApiError`, `RequestValidationError`,
+routes raise straight through — the runner's own refusals, `RequestValidationError`,
`PipelexError`, a bare orchestrator-SDK transport error (handled via a synthetic
plugin-contributed mapper, proving the plugin seam without importing any
orchestrator SDK), and uncaught `Exception` each end up at their respective
@@ -13,13 +13,14 @@ the operator's, which `test_problem_views.py` drives through the real dependenci
import asyncio
import json
+import logging
import re
from typing import Any, cast
import pytest
from fastapi import APIRouter, Depends, FastAPI, Request
from fastapi.testclient import TestClient
-from mthds.protocol.problem.registry import CoreCode
+from mthds.protocol.problem.registry import CoreCode, ProblemDomain
from pipelex.base_exceptions import PipelexConfigError, PipelexError, ProblemFacts
from pipelex.cogt.exceptions import InferenceErrorCategory, LLMCompletionError
from pipelex.cogt.inference.error_classification import ProviderErrorMetadata
@@ -37,18 +38,27 @@ from pipelex.plugins.registrar import HttpErrorMapperFn, PluginOrigin, PluginReg
from pipelex.system.exceptions import EnvVarNotFoundError
from pydantic import BaseModel, ConfigDict
from pytest_mock import MockerFixture
+from starlette.exceptions import HTTPException as StarletteHTTPException
from starlette.types import Message, Scope
from typing_extensions import override
-from pipelex_api.error_types import ErrorType
-from pipelex_api.errors import raise_internal_server_error, raise_validation_error
-from pipelex_api.exception_handlers import problem_response, register_exception_handlers
+from pipelex_api.exception_handlers import (
+ ERROR_CHAIN_FIELD,
+ ERROR_FRAMES_FIELD,
+ RecordLevel,
+ framework_refusal,
+ problem_response,
+ record_level_of,
+ register_exception_handlers,
+)
+from pipelex_api.exceptions import RunnerMisconfiguredError, RunnerRequestError
from pipelex_api.middleware import REQUEST_ID_HEADER, RequestIdMiddleware
from pipelex_api.problem_document import PROBLEM_JSON_MEDIA_TYPE
from pipelex_api.problem_view import mark_operator_request
from pipelex_api.routes.pipelex.pipeline import router as pipeline_router
from pipelex_api.routes.pipelex.tools import router as tools_router
from pipelex_api.security import RequestUser
+from tests.unit._problems import assert_problem, problem_items_fields
from tests.unit.test_data import ProblemTestData, rate_limited_failure
# Crockford Base32, 26 chars — the ULID alphabet RequestIdMiddleware mints.
@@ -245,25 +255,54 @@ async def crafted_retry_route(case: str) -> None:
raise _CraftedRetryError(retry_after=retry_after).with_error_code(code)
+# The field the runner's own refusal names in these routes.
+_REFUSED_FIELD = "name"
+
+
+def _caller_mistake() -> RunnerRequestError:
+ """A runner refusal of the request, a 422 `request.invalid`."""
+ msg = "a caller-side mistake"
+ return RunnerRequestError(msg, field=_REFUSED_FIELD)
+
+
@_router.get("/api-input-error")
async def api_input_error_route() -> None:
- # An API-authored 422 — the INPUT-domain branch of `handle_api_error`.
- raise_validation_error("a caller-side mistake")
+ # A runner-authored 422, raised as its coded class like any pipelex error.
+ raise _caller_mistake()
@_router.get("/crafted-detail")
async def crafted_detail_route(detail: str) -> None:
- # An API-authored 422 whose `detail` is exactly what the caller sent — the real shape of the
- # `raise_validation_error(str(exc))` sites, where the message is built from caller input.
- raise_validation_error(detail)
+ # A runner refusal whose message quotes exactly what the caller sent: the real shape of a refusal built from what a
+ # parser said about caller input.
+ msg = f"the value is refused: {detail}"
+ raise RunnerRequestError(msg, field=_REFUSED_FIELD)
@_router.get("/api-config-error")
async def api_config_error_route() -> None:
- # An API-authored 500 — the CONFIG-domain branch of `handle_api_error`
- # (the `version.py` `PackageNotFoundError → raise_internal_server_error`
- # path goes through this same code).
- raise_internal_server_error("the configuration is broken", error_type=ErrorType.SERVER_MISCONFIGURED)
+ # A runner-authored 500: the runner's own configuration (the `version.py` `PackageNotFoundError` path goes through
+ # this same code).
+ msg = "the configuration is broken"
+ raise RunnerMisconfiguredError(msg, component="API_KEY")
+
+
+@_router.get("/framework-refusal/{status}")
+async def framework_refusal_route(status: int) -> None:
+ # What the framework raises while it reads a request: FastAPI's bare 400 for a body its parse fails on.
+ raise StarletteHTTPException(status_code=status, detail="There was an error parsing the body")
+
+
+# The headers a framework refusal may be raised with: the challenge FastAPI's security classes name, and a limiter's delay.
+_RAISED_CHALLENGE = 'Bearer realm="pipelex"'
+_RAISED_RETRY_AFTER = "7"
+
+
+@_router.get("/framework-refusal-with-headers/{status}")
+async def framework_refusal_with_headers_route(status: int) -> None:
+ # What a dependency the framework runs raises: a security class's 401 or 403, a rate limiter's 429.
+ headers = {"WWW-Authenticate": _RAISED_CHALLENGE, "Retry-After": _RAISED_RETRY_AFTER, "X-Internal": "not kept"}
+ raise StarletteHTTPException(status_code=status, detail="Not authenticated", headers=headers)
class _RequestValidationBody(BaseModel):
@@ -331,7 +370,7 @@ async def authenticated_config_error_route(request: Request) -> None:
@_router.get("/authenticated-api-input-error")
async def authenticated_api_input_error_route(request: Request) -> None:
_bind_test_user(request)
- raise_validation_error("a caller-side mistake")
+ raise _caller_mistake()
@_router.get("/authenticated-unexpected-error")
@@ -351,10 +390,9 @@ async def run_state_pipelex_error_route(request: Request) -> None:
@_router.get("/pipeline-state-api-input-error")
async def run_state_api_input_error_route(request: Request) -> None:
- # An API-authored 4xx raised after `_parse_request` bound state — exercises
- # `_log_api_authored_error`.
+ # A runner-authored 4xx raised after `_parse_request` bound state.
_bind_test_run_state(request)
- raise_validation_error("a caller-side mistake")
+ raise _caller_mistake()
@_router.get("/pipeline-state-unexpected-error")
@@ -519,7 +557,8 @@ class TestExceptionHandlers:
body = json.loads(bytes(response.body))
assert body["status"] == expected_status
assert body["code"] == code
- fields = _emitted_fields(log_spy, as_error=expected_status >= 500)
+ # A 501 states what this deployment does not offer, which the caller meets each time it asks: a warning.
+ fields = _emitted_fields(log_spy, as_error=expected_status >= 500 and expected_status != 501)
assert fields["http.response.status_code"] == expected_status
assert fields["error.code"] == code
@@ -638,11 +677,10 @@ class TestExceptionHandlers:
("GET", "/synthetic-transport-error", None, 500),
("GET", "/corrupt-error", None, 500),
("GET", "/unexpected-error", None, 500),
- # Cover the API-authored paths (`handle_api_error`) and FastAPI's
- # automatic-validation path (`handle_request_validation_error`):
- # the request-id propagation is the same structural property, but
- # the three branches build the response document differently and
- # are worth sweeping.
+ # Cover the runner's own refusals and FastAPI's automatic-validation
+ # path (`handle_request_validation_error`): the request-id
+ # propagation is the same structural property, but each is raised
+ # from a different place and is worth sweeping.
("GET", "/api-input-error", None, 422),
("GET", "/api-config-error", None, 500),
("POST", "/needs-body", {"wrong": 1}, 422),
@@ -661,6 +699,141 @@ class TestExceptionHandlers:
assert _ULID_RE.match(request_id) is not None
assert response.json()["request_id"] == request_id
+ def test_a_path_no_route_serves_is_a_not_found_problem(self, mocker: MockerFixture):
+ # Starlette's own 404 would be a bare `{"detail": "Not Found"}`: the runner answers its problem instead.
+ log_spy = mocker.patch("pipelex_api.exception_handlers.log")
+ response = _build_client().get("/no-such-route")
+ body = assert_problem(response, status=404, code="request.not_found")
+ assert body["request_id"] == response.headers[REQUEST_ID_HEADER]
+ assert "params" not in body
+ # Nobody has anything to do about a path nobody serves, which scanners probe by the thousand: its record is a
+ # debug one, never a warning.
+ log_spy.warning.assert_not_called()
+ log_spy.error.assert_not_called()
+ fields = log_spy.debug.call_args.kwargs["fields"]
+ assert fields["error.code"] == "request.not_found"
+ assert fields["http.response.status_code"] == 404
+ assert ERROR_FRAMES_FIELD not in fields
+
+ def test_a_method_the_route_does_not_accept_is_a_method_not_allowed_problem_keeping_allow(self, mocker: MockerFixture):
+ log_spy = mocker.patch("pipelex_api.exception_handlers.log")
+ response = _build_client().get("/needs-body")
+ assert_problem(response, status=405, code="request.method_not_allowed")
+ assert response.headers["Allow"] == "POST"
+ log_spy.warning.assert_not_called()
+ log_spy.error.assert_not_called()
+ assert log_spy.debug.call_args.kwargs["fields"]["error.code"] == "request.method_not_allowed"
+
+ def test_a_routing_refusal_writes_no_warning_record(self, caplog: pytest.LogCaptureFixture):
+ # Through the real log, not a spy: no record at `WARNING` or above reaches a sink for a path nobody serves.
+ with caplog.at_level("DEBUG"):
+ _build_client().get("/wp-admin/setup.php")
+ _build_client().get("/needs-body")
+ assert [record for record in caplog.records if record.levelno >= logging.WARNING] == []
+
+ def test_a_framework_4xx_is_the_caller_s_malformed_request_never_a_500(self, mocker: MockerFixture):
+ log_spy = mocker.patch("pipelex_api.exception_handlers.log")
+ response = _build_client().get("/framework-refusal/400")
+ # It keeps its 400, as every framework 4xx keeps its status.
+ body = assert_problem(response, status=400, code="request.malformed")
+ assert body["params"] == {"reason": "unreadable"}
+ assert "There was an error parsing the body" not in response.text
+ # A caller's mistake: a warning, never the error level of a fault of the server.
+ log_spy.error.assert_not_called()
+ assert _emitted_fields(log_spy, as_error=False)["error.code"] == "request.malformed"
+
+ def test_a_framework_422_is_the_caller_s_malformed_request_too(self):
+ response = _build_client().get("/framework-refusal/422")
+ body = assert_problem(response, status=422, code="request.malformed")
+ assert body["params"] == {"reason": "unreadable"}
+
+ @pytest.mark.parametrize(
+ ("raised_status", "status", "code", "kept_header"),
+ [
+ # A security class's missing credential, keeping the challenge it named.
+ (401, 401, "auth.missing_credential", "WWW-Authenticate"),
+ # A security class's refusal of a credential: the framework names no requirement for `auth.forbidden`.
+ (403, 403, "auth.invalid_credential", None),
+ # The framework names no limit and no size for `request.too_large`.
+ (413, 413, "request.malformed", None),
+ # No code declares a 415: the refusal keeps its status, a form of request the framework would not read.
+ (415, 415, "request.malformed", None),
+ # A rate limiter's refusal, keeping the delay it asked for: the framework names no limit and no window for
+ # `account.rate_limited`.
+ (429, 429, "runtime.unavailable", "Retry-After"),
+ ],
+ )
+ def test_a_framework_4xx_keeps_its_meaning(self, mocker: MockerFixture, raised_status: int, status: int, code: str, kept_header: str | None):
+ # Only a 400 or a 422 is a request the framework could not read: every other 4xx is answered under the code whose
+ # status and meaning match it, or keeps its status, never as a malformed request.
+ log_spy = mocker.patch("pipelex_api.exception_handlers.log")
+ response = _build_client().get(f"/framework-refusal-with-headers/{raised_status}")
+ assert_problem(response, status=status, code=code)
+ assert "Not authenticated" not in response.text
+ kept = {"WWW-Authenticate": _RAISED_CHALLENGE, "Retry-After": _RAISED_RETRY_AFTER}
+ for header, value in kept.items():
+ if header == kept_header:
+ assert response.headers[header] == value
+ else:
+ assert header not in response.headers
+ assert "X-Internal" not in response.headers
+ log_spy.error.assert_not_called()
+ fields = _emitted_fields(log_spy, as_error=False)
+ assert fields["error.code"] == code
+ assert fields["http.response.status_code"] == status
+ # The refusal stands in for the framework's exception, which the record's chain still names.
+ assert fields[ERROR_CHAIN_FIELD] == [fields["error.type"], "HTTPException"]
+
+ @pytest.mark.parametrize("raised_status", range(400, 500))
+ def test_every_framework_refusal_fills_its_code_s_parameters(self, raised_status: int):
+ """Whatever 4xx the framework raises, the refusal answering it carries every parameter its code requires.
+
+ A code whose required parameter is missing renders its fallback sentence, which tells the caller nothing.
+ """
+ refusal, kept_status = framework_refusal(status=raised_status, challenge=None)
+ problem = refusal.to_problem(view=ProblemView.OPERATOR)
+ # Every framework refusal is answered under one of the standard's own codes.
+ spec = error_code_spec(CoreCode(problem.code))
+ params = problem.params.model_dump(exclude_none=True) if problem.params else {}
+ spec.params_model.model_validate(params)
+ required = {name for name, field in spec.params_model.model_fields.items() if field.is_required()}
+ assert required <= set(params), (problem.code, params)
+ # The caller reads the code's sentence filled from those parameters, never the fallback naming none.
+ assert problem.detail == spec.detail.format(**params)
+ # The status answered is the one the framework raised, whether the code declares it or the refusal keeps it.
+ assert (kept_status or spec.status) == raised_status
+
+ @pytest.mark.parametrize(
+ ("status", "domain", "level", "frames"),
+ [
+ (422, ProblemDomain.INPUT, RecordLevel.WARNING, False),
+ (409, ProblemDomain.RUNTIME, RecordLevel.WARNING, False),
+ (429, ProblemDomain.RUNTIME, RecordLevel.WARNING, False),
+ # What this deployment does not offer, which a caller meets each time it asks.
+ (501, ProblemDomain.OPERATOR, RecordLevel.WARNING, False),
+ # A refusal the caller can avoid, such as its own webhook receiver refusing a delivery.
+ (502, ProblemDomain.INPUT, RecordLevel.WARNING, False),
+ (500, ProblemDomain.METHOD, RecordLevel.WARNING, False),
+ (500, ProblemDomain.ACCOUNT, RecordLevel.WARNING, False),
+ (500, ProblemDomain.OPERATOR, RecordLevel.ERROR, True),
+ (500, ProblemDomain.RUNTIME, RecordLevel.ERROR, True),
+ (503, ProblemDomain.RUNTIME, RecordLevel.ERROR, True),
+ ],
+ )
+ def test_only_a_fault_the_server_must_fix_is_recorded_as_an_error(self, status: int, domain: ProblemDomain, level: RecordLevel, frames: bool):
+ record_level = record_level_of(status=status, domain=domain)
+ assert record_level == level
+ assert record_level.writes_frames is frames
+
+ def test_a_framework_401_without_a_challenge_names_none(self):
+ response = _build_client().get("/framework-refusal/401")
+ assert_problem(response, status=401, code="auth.missing_credential")
+ assert "WWW-Authenticate" not in response.headers
+
+ def test_a_framework_5xx_is_the_runtime_s_fault(self):
+ response = _build_client(raise_server_exceptions=False).get("/framework-refusal/503")
+ assert_problem(response, status=500, code="runtime.unexpected")
+
def test_inbound_request_id_is_echoed(self):
response = _build_client().get("/config-error", headers={REQUEST_ID_HEADER: "inbound-correlation-007"})
assert response.headers[REQUEST_ID_HEADER] == "inbound-correlation-007"
@@ -683,7 +856,10 @@ class TestExceptionHandlers:
assert fields["url.path"] == "/config-error"
# A domain error's record carries no `detail`: the cause is the diagnostics', the body's detail is only its code's sentence.
assert "detail" not in fields
- assert log_spy.error.call_args.kwargs["include_exception"] is True
+ # No traceback, which would print the text of every exception of the chain: the chain by class, and the frames.
+ assert "include_exception" not in log_spy.error.call_args.kwargs
+ assert fields[ERROR_CHAIN_FIELD] == ["PipelexConfigError"]
+ assert fields[ERROR_FRAMES_FIELD]
def test_provider_failure_record_carries_the_providers_answer(self, mocker: MockerFixture):
log_spy = mocker.patch("pipelex_api.exception_handlers.log")
@@ -712,52 +888,53 @@ class TestExceptionHandlers:
fields = _emitted_fields(log_spy, as_error=True)
assert fields["error.code"] == CoreCode.RUNTIME_UNEXPECTED
assert fields["error.type"] == "RuntimeError"
- assert log_spy.error.call_args.kwargs["include_exception"] is True
-
- def test_api_authored_500_emits_structured_error_record(self, mocker: MockerFixture):
- # Without `handle_api_error` logging, an `ApiError`-shaped 500 produces
- # zero operator output (`/version`'s `PackageNotFoundError →
- # raise_internal_server_error` is the canonical silent case). Assert
- # the handler emits one `api_error` record at `error` level whose fields
- # mirror the response — the same set `_log_problem` ships for a
- # pipelex-derived 500, so a downstream sink queries them uniformly.
+ assert "include_exception" not in log_spy.error.call_args.kwargs
+ assert fields[ERROR_CHAIN_FIELD] == ["RuntimeError"]
+ assert any(frame.endswith(" in unexpected_error_route") for frame in fields[ERROR_FRAMES_FIELD]), fields
+
+ def test_runner_authored_500_emits_structured_error_record(self, mocker: MockerFixture):
+ # A runner-authored 500 (`/version`'s `PackageNotFoundError` is the canonical case) is a pipelex error like any
+ # other, so it emits the same record at `error` level, the set `_log_problem` ships for every 500, which a
+ # downstream sink queries uniformly.
log_spy = mocker.patch("pipelex_api.exception_handlers.log")
response = _build_client().get("/api-config-error")
assert response.status_code == 500
+ assert response.json()["code"] == "runtime.misconfigured"
log_spy.error.assert_called_once()
fields = _emitted_fields(log_spy, as_error=True)
assert fields["http.response.status_code"] == 500
- assert fields["error.type"] == "ServerMisconfigured"
+ assert fields["error.code"] == "runtime.misconfigured"
+ assert fields["error.type"] == "RunnerMisconfiguredError"
assert fields["error_domain"] == "config"
assert fields["retryable"] is False
assert fields["url.path"] == "/api-config-error"
- # The operator-facing cause rides a field of its own and never reaches the message, which
- # is what stops a crafted value from shaping the rendered line at all.
- assert fields["detail"] == "the configuration is broken"
- assert log_spy.error.call_args.kwargs["include_exception"] is True
+ # The operator's message rides the response's diagnostics, never the record.
+ assert "detail" not in fields
+ assert "the configuration is broken" not in json.dumps(fields)
log_spy.warning.assert_not_called()
- def test_api_authored_4xx_emits_structured_warning_record(self, mocker: MockerFixture):
- # Mirror at the warning level: an INPUT-domain `ApiError` is a caller
- # mistake, not an operator fault, so it logs at `warning` without a
- # traceback — same disposition rule `_log_problem` uses.
+ def test_runner_authored_4xx_emits_structured_warning_record(self, mocker: MockerFixture):
+ # Mirror at the warning level: a refusal of the request is a caller mistake, not an operator fault, so it logs
+ # at `warning` — the same disposition rule every problem follows.
log_spy = mocker.patch("pipelex_api.exception_handlers.log")
response = _build_client().get("/api-input-error")
- assert response.status_code == 422
+ body = assert_problem(response, status=422, code="request.invalid", field=_REFUSED_FIELD)
+ assert body["location"] == {"field": _REFUSED_FIELD}
log_spy.warning.assert_called_once()
fields = _emitted_fields(log_spy, as_error=False)
assert fields["http.response.status_code"] == 422
- assert fields["error.type"] == "ValidationError"
+ assert fields["error.code"] == "request.invalid"
+ assert fields["error.type"] == "RunnerRequestError"
assert fields["error_domain"] == "input"
assert fields["retryable"] is False
- assert fields["detail"] == "a caller-side mistake"
+ assert ERROR_FRAMES_FIELD not in fields
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):
+ def test_client_disconnect_is_a_422_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.
+ # nesting check or from a run route's own read. It is the caller's failure: a 422 `request.malformed` at
+ # warning, never a 500 server fault.
log_spy = mocker.patch("pipelex_api.exception_handlers.log")
app = FastAPI()
register_exception_handlers(app)
@@ -794,16 +971,26 @@ class TestExceptionHandlers:
asyncio.run(app(scope, receive, send))
start = next(message for message in sent if message["type"] == "http.response.start")
- assert start["status"] == 400
+ assert start["status"] == 422
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"
+ assert body["code"] == "request.malformed"
+ assert body["domain"] == "input"
+ assert body["params"] == {"reason": "body_incomplete"}
log_spy.warning.assert_called_once()
fields = _emitted_fields(log_spy, as_error=False)
- assert fields["http.response.status_code"] == 400
- assert fields["error.type"] == "BadRequest"
+ assert fields["http.response.status_code"] == 422
+ assert fields["error.type"] == "RunnerRequestError"
+ # The refusal stands in for Starlette's exception, chained from it, so the record still names the class that escaped.
+ assert fields[ERROR_CHAIN_FIELD] == ["RunnerRequestError", "ClientDisconnect"]
log_spy.error.assert_not_called()
+ def test_the_operator_reads_the_framework_exception_a_refusal_stands_in_for(self):
+ # The stand-in's diagnostics name the class it answers among its causes, never its text.
+ response = _build_client(as_operator=True).post("/needs-body", json={"wrong": 1})
+ body = assert_problem(response, status=422, code="request.invalid", field="field")
+ assert body["diagnostics"]["error_class"] == "RunnerRequestError"
+ assert [cause["error_class"] for cause in body["diagnostics"]["causes"]] == ["RequestValidationError"]
+
def test_the_message_is_fixed_and_the_failure_rides_the_fields(self, mocker: MockerFixture):
# The message is the same sentence on every error line, at either level, so it is the key a
# query or an alert selects the error stream by; the status and the error type, which used
@@ -815,7 +1002,7 @@ class TestExceptionHandlers:
assert log_spy.warning.call_args.args[0] == "A request ended in an error response"
fields = _emitted_fields(log_spy, as_error=True)
assert fields["http.response.status_code"] == 500
- assert fields["error.type"] == "ServerMisconfigured"
+ assert fields["error.type"] == "RunnerMisconfiguredError"
assert "event" not in fields
@pytest.mark.parametrize(
@@ -850,19 +1037,16 @@ class TestExceptionHandlers:
assert fields["error.type"] == "PipelexConfigError"
assert fields["error.code"] == PipelexErrorCode.CONFIG_INVALID
- def test_user_id_rides_authenticated_api_authored_record(self, mocker: MockerFixture):
- # `handle_api_error` covers the API-authored 4xx surface (storage's
- # `raise_bad_request`, `raise_forbidden`, `raise_payload_too_large`;
- # uploader's same set). It must ride the same `user.id` correlation
- # `_log_problem` does so the contract is uniform — a caller
- # mistake and a backend failure both name the caller.
+ def test_user_id_rides_authenticated_runner_authored_record(self, mocker: MockerFixture):
+ # The runner's own refusals ride the same `user.id` correlation every problem does, so the contract is
+ # uniform — a caller mistake and a backend failure both name the caller.
log_spy = mocker.patch("pipelex_api.exception_handlers.log")
response = _build_client().get("/authenticated-api-input-error")
assert response.status_code == 422
log_spy.warning.assert_called_once()
fields = _emitted_fields(log_spy, as_error=False)
assert fields["user.id"] == _TEST_USER_ID
- assert fields["error.type"] == "ValidationError"
+ assert fields["error.type"] == "RunnerRequestError"
def test_user_id_rides_authenticated_unexpected_error_record(self, mocker: MockerFixture):
# The catch-all 500 (`handle_unexpected_error`) is the one place a
@@ -901,11 +1085,9 @@ class TestExceptionHandlers:
# The bound run id rides the problem too, so a caller can name the run it asks about.
assert response.json()["pipeline_run_id"] == _TEST_RUN_ID
- def test_run_state_rides_api_authored_record(self, mocker: MockerFixture):
- # API-authored 4xx surface: `raise_validation_error` raised from a
- # route that has already bound pipe state must ship the same fields,
- # so the operator record is uniform across the validation and the
- # pipelex-domain failure surfaces.
+ def test_run_state_rides_runner_authored_record(self, mocker: MockerFixture):
+ # A runner refusal raised from a route that has already bound pipe state ships the same fields, so the operator
+ # record is uniform across the request refusals and the pipelex-domain failures.
log_spy = mocker.patch("pipelex_api.exception_handlers.log")
response = _build_client().get("/pipeline-state-api-input-error")
assert response.status_code == 422
@@ -913,7 +1095,7 @@ class TestExceptionHandlers:
fields = _emitted_fields(log_spy, as_error=False)
assert fields["pipe_code"] == _TEST_PIPE_CODE
assert fields["pipeline_run_id"] == _TEST_RUN_ID
- assert fields["error.type"] == "ValidationError"
+ assert fields["error.type"] == "RunnerRequestError"
def test_run_state_rides_unexpected_error_record(self, mocker: MockerFixture):
# The catch-all 500 is the most operationally expensive case for a
@@ -946,10 +1128,9 @@ class TestExceptionHandlers:
assert "pipeline_run_id" not in response.json()
def test_request_validation_error_emits_structured_warning_record(self, mocker: MockerFixture):
- # FastAPI's automatic-validation 422 goes through
- # `handle_request_validation_error`, not `handle_api_error`, but emits
- # the same `api_error` record so the surface is uniform — whichever code
- # path rejects a caller-input failure, the operator record is identical.
+ # FastAPI's automatic-validation 422 goes through `handle_request_validation_error`, which answers the
+ # runner's own refusal, so it emits the same record every problem does — whichever code path rejects a
+ # caller-input failure, the operator record is identical.
log_spy = mocker.patch("pipelex_api.exception_handlers.log")
# `{"wrong": 1}` triggers FastAPI's automatic validation failure on
# `_RequestValidationBody`: `field` is missing AND `wrong` is an
@@ -957,15 +1138,19 @@ class TestExceptionHandlers:
# actually fires — Pydantic's default `extra="ignore"` would have
# left only the missing-field error).
response = _build_client().post("/needs-body", json={"wrong": 1})
- assert response.status_code == 422
+ body = assert_problem(response, status=422, code="request.invalid", field="field")
+ # One item per refused field, in the order pydantic reports them, each named as its `field` parameter.
+ assert problem_items_fields(body) == ["field", "wrong"]
+ assert [item["location"] for item in body["errors"]] == [{"field": "field"}, {"field": "wrong"}]
log_spy.warning.assert_called_once()
fields = _emitted_fields(log_spy, as_error=False)
assert fields["http.response.status_code"] == 422
- assert fields["error.type"] == "ValidationError"
+ assert fields["error.code"] == "request.invalid"
+ assert fields["error.type"] == "RunnerRequestError"
+ # The refusal stands in for FastAPI's exception, chained from it, so the record still names the class that escaped.
+ assert fields[ERROR_CHAIN_FIELD] == ["RunnerRequestError", "RequestValidationError"]
assert fields["error_domain"] == "input"
- # The summary covers both per-field failures the request triggered.
- assert "field" in fields["detail"]
- assert "wrong" in fields["detail"]
+ assert "detail" not in fields
log_spy.error.assert_not_called()
@pytest.mark.parametrize(
@@ -983,19 +1168,17 @@ class TestExceptionHandlers:
'has " a quote = inside',
],
)
- def test_crafted_detail_stays_one_field_and_shapes_no_other(self, mocker: MockerFixture, crafted_detail: str) -> None:
- # `_log_api_authored_error` ships `document["detail"]`, and `detail` originates from caller
- # input on several routes (`raise_validation_error(str(exc))`, callback-URL rejections,
- # `_summarize_request_validation_error`'s per-field messages). The API renders none of it
- # any more: the value is handed to the runtime as one field, so it cannot forge a sibling
- # field and cannot reach the message, and the selected sink is what escapes it on the way
- # out. Pin that at the handler, so a route shipping some new caller-controlled field later
- # is covered without re-auditing this surface.
+ def test_crafted_detail_reaches_neither_the_record_nor_the_caller(self, mocker: MockerFixture, crafted_detail: str) -> None:
+ # A refusal's message can quote what the caller sent. It rides the operator view's diagnostics alone: the
+ # record carries the code and the classes, and the caller reads the code's sentence, so a crafted value can
+ # neither forge a field nor reach the message. Pin that at the handler, so a route raising some new refusal
+ # built from caller input later is covered without re-auditing this surface.
log_spy = mocker.patch("pipelex_api.exception_handlers.log")
response = _build_client().get("/crafted-detail", params={"detail": crafted_detail})
- assert response.status_code == 422
+ body = assert_problem(response, status=422, code="request.invalid", field=_REFUSED_FIELD)
+ assert crafted_detail not in json.dumps(body)
fields = _emitted_fields(log_spy, as_error=False)
- assert fields["detail"] == crafted_detail, f"the value was altered on the way to the record: {fields['detail']!r}"
+ assert crafted_detail not in json.dumps(fields), "caller input reached the record"
assert fields["http.response.status_code"] == 422, "a crafted detail overwrote a legitimate field"
message = log_spy.warning.call_args.args[0]
assert crafted_detail not in message, f"caller input reached the message: {message!r}"
@@ -1018,12 +1201,14 @@ class TestExceptionHandlers:
assert body["request_id"] == response.headers[REQUEST_ID_HEADER]
def test_async_execution_not_enabled_logs_its_status(self, mocker: MockerFixture):
- # The record carries the status the client saw.
+ # The record carries the status the client saw. A 501 states what this deployment does not offer, which any
+ # caller can ask for again and again: a warning without frames, never an error filling the alerts.
log_spy = mocker.patch("pipelex_api.exception_handlers.log")
response = _build_client().get("/async-execution-not-enabled")
assert response.status_code == 501
- log_spy.error.assert_called_once()
- fields = _emitted_fields(log_spy, as_error=True)
+ log_spy.error.assert_not_called()
+ fields = _emitted_fields(log_spy, as_error=False)
+ assert ERROR_FRAMES_FIELD not in fields
assert fields["http.response.status_code"] == 501
assert fields["error.type"] == "AsyncExecutionNotEnabledError"
assert fields["error.code"] == CoreCode.RUNTIME_UNSUPPORTED
diff --git a/api/tests/unit/test_execute_dispatch.py b/api/tests/unit/test_execute_dispatch.py
index 163a24e1c..c1c90ecb3 100644
--- a/api/tests/unit/test_execute_dispatch.py
+++ b/api/tests/unit/test_execute_dispatch.py
@@ -45,6 +45,7 @@ from pipelex_api.middleware import REQUEST_ID_HEADER, RequestIdMiddleware
from pipelex_api.routes import router as api_router
from pipelex_api.routes.pipelex.pipeline import ApiRunner
from tests.unit._constants import VALID_MTHDS
+from tests.unit._problems import assert_problem
_PIPELINE_NS = "pipelex_api.routes.pipelex.pipeline"
@@ -330,9 +331,8 @@ class TestExecuteDispatch:
},
)
- assert response.status_code == 403, response.text
- assert response.headers["content-type"].startswith("application/problem+json")
- assert response.json()["error_type"] == "OrchestrationModeOverrideForbidden"
+ problem = assert_problem(response, status=422, code="pipelex.deployment.orchestration_override_forbidden")
+ assert problem["params"] == {"requested_mode": "temporal"}
def test_inbound_request_id_reaches_the_dispatched_job(self, mocker: MockerFixture) -> None:
"""On a `temporal` deployment, the inbound `X-Request-ID` rides the job the orchestrator is handed.
diff --git a/api/tests/unit/test_json_body.py b/api/tests/unit/test_json_body.py
index c0a529e48..de09997a5 100644
--- a/api/tests/unit/test_json_body.py
+++ b/api/tests/unit/test_json_body.py
@@ -3,29 +3,40 @@
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
+JSON, blind to brackets inside strings, linear at the body cap), the 422 `request.malformed` 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
+import sys
from collections.abc import Callable
from typing import cast
import pytest
-from fastapi import FastAPI
+from fastapi import FastAPI, Request, Response
+from fastapi.datastructures import Default, DefaultPlaceholder
from fastapi.routing import APIRoute
from fastapi.testclient import TestClient
+from pydantic import BaseModel
from pytest_mock import MockerFixture
+from starlette.types import Message, Scope
-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.exceptions import RunnerRequestError
+from pipelex_api.json_body import (
+ INTEGER_TOO_LONG_REASON,
+ TOO_DEEPLY_NESTED_REASON,
+ JsonBodyRoute,
+ decode_json_body,
+ holds_content_type_strictly,
+ 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
+from tests.unit._problems import assert_problem, problem_of
# Deep enough to exhaust the parser's recursion budget on Python 3.13 and earlier.
RECURSION_DEEP = 100_000
@@ -185,12 +196,9 @@ class TestJsonBodyNesting:
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"]
+ problem = assert_problem(response, status=422, code="request.malformed")
+ assert problem["domain"] == "input"
+ assert problem["params"] == {"reason": TOO_DEEPLY_NESTED_REASON}
def test_typed_route_accepts_a_body_at_the_limit(self):
response = _client().post(
@@ -211,9 +219,39 @@ class TestJsonBodyNesting:
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"
+ problem = assert_problem(response, status=422, code="request.malformed")
+ assert problem["params"] == {"reason": TOO_DEEPLY_NESTED_REASON}
+
+ @pytest.mark.parametrize("route", ["/v1/format", "/v1/validate"])
+ def test_typed_route_refuses_a_body_that_is_not_utf8_as_the_caller_s(self, route: str):
+ # FastAPI's own parse turned the decode error into a bare 400 the handlers could only read as a fault of the
+ # server, a 500; the route now parses first and names the reason.
+ response = _client().post(route, content=b"\xff{}", headers={"content-type": "application/json"})
+
+ problem = assert_problem(response, status=422, code="request.malformed")
+ assert problem["params"] == {"reason": "not_utf8"}
+
+ @pytest.mark.parametrize("route", ["/v1/format", "/v1/validate"])
+ def test_typed_route_refuses_an_integer_past_the_digit_limit_as_the_caller_s(self, route: str):
+ # `json.loads` refuses an integer literal longer than `sys.get_int_max_str_digits()` with a plain `ValueError`.
+ too_long = "1" * (sys.get_int_max_str_digits() + 1)
+ response = _client().post(route, content=f'{{"content": "", "padding": {too_long}}}'.encode(), headers={"content-type": "application/json"})
+
+ problem = assert_problem(response, status=422, code="request.malformed")
+ assert problem["params"] == {"reason": INTEGER_TOO_LONG_REASON}
+
+ def test_typed_route_reads_a_body_that_is_not_json_as_fastapi_does(self):
+ # A body whose content type is not JSON is handed to the model as raw bytes, which it refuses field by field:
+ # the route parses only what FastAPI would.
+ response = _client().post("/v1/format", content=b"\xff{}", headers={"content-type": "text/plain"})
+
+ assert_problem(response, status=422, code="request.invalid")
+
+ def test_typed_route_reads_a_utf16_body_as_fastapi_does(self):
+ body = json.dumps({"content": VALID_MTHDS}).encode("utf-16")
+ response = _client().post("/v1/lint", content=body, headers={"content-type": "application/json"})
+
+ assert response.status_code == 200, response.text
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.
@@ -230,9 +268,95 @@ class TestJsonBodyNesting:
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:
+ with pytest.raises(RunnerRequestError) 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"]
+ # The patch replaces `json.loads` module-wide, and rendering the problem parses JSON too.
+ mocker.stopall()
+ problem = problem_of(raised.value)
+ assert problem["status"] == 422
+ assert problem["code"] == "request.malformed"
+ assert problem["params"] == {"reason": "not_json"}
+ assert isinstance(raised.value.__cause__, RecursionError)
+
+
+class _TypedBody(BaseModel):
+ content: str
+
+
+async def _typed_endpoint(body: _TypedBody) -> dict[str, str]:
+ return {"content": body.content}
+
+
+def _typed_route() -> JsonBodyRoute:
+ return JsonBodyRoute("/typed", _typed_endpoint, methods=["POST"])
+
+
+def _request_declaring_no_content_type(body: bytes) -> Request:
+ """A request to the typed route whose body declares no content type."""
+
+ async def receive() -> Message:
+ return {"type": "http.request", "body": body, "more_body": False}
+
+ scope: Scope = {"type": "http", "method": "POST", "path": "/typed", "raw_path": b"/typed", "query_string": b"", "headers": []}
+ return Request(scope, receive)
+
+
+class TestStrictContentType:
+ """A body that declares no content type is parsed as JSON exactly where FastAPI's own parse would parse it.
+
+ FastAPI 0.132.0 added a route's `strict_content_type`, which the dependency floor (`fastapi>=0.118.0`) does not
+ require, so a release without it must still build and serve the routes, parsing such a body as JSON as it does.
+ """
+
+ @pytest.mark.parametrize(
+ ("setting", "is_strict"),
+ [(Default(True), True), (Default(False), False), (True, True), (False, False)],
+ )
+ def test_reads_the_route_s_setting(self, mocker: MockerFixture, setting: bool | DefaultPlaceholder, is_strict: bool):
+ route = _typed_route()
+ mocker.patch.object(route, "strict_content_type", setting)
+ assert holds_content_type_strictly(route) is is_strict
+
+ def test_a_route_of_a_fastapi_without_the_setting_does_not_hold_to_its_content_type(self):
+ route = _typed_route()
+ del route.strict_content_type # A route as a FastAPI release older than 0.132.0 builds it.
+ assert holds_content_type_strictly(route) is False
+
+ @pytest.mark.asyncio
+ async def test_a_fastapi_without_the_setting_parses_a_body_declaring_no_content_type(self, mocker: MockerFixture):
+ # Its own parse reads such a body as JSON, so the route parses it first, and refuses one that is not UTF-8 as
+ # the caller's malformed request, never as the bare 400 FastAPI would raise.
+ route = _typed_route()
+ del route.strict_content_type
+ framework_handler = mocker.AsyncMock(return_value=Response())
+ # FastAPI's own handler, which a release without the setting builds without reading it.
+ mocker.patch.object(APIRoute, "get_route_handler", return_value=framework_handler)
+ handler = route.get_route_handler()
+
+ with pytest.raises(RunnerRequestError) as raised:
+ await handler(_request_declaring_no_content_type(b"\xff{}"))
+
+ assert problem_of(raised.value)["params"] == {"reason": "not_utf8"}
+ framework_handler.assert_not_awaited()
+
+ @pytest.mark.asyncio
+ @pytest.mark.parametrize(("setting", "parses"), [(Default(True), False), (True, False), (Default(False), True), (False, True)])
+ async def test_a_fastapi_with_the_setting_parses_as_the_setting_says(
+ self, mocker: MockerFixture, setting: bool | DefaultPlaceholder, parses: bool
+ ):
+ route = _typed_route()
+ mocker.patch.object(route, "strict_content_type", setting)
+ framework_handler = mocker.AsyncMock(return_value=Response())
+ mocker.patch.object(APIRoute, "get_route_handler", return_value=framework_handler)
+ handler = route.get_route_handler()
+ request = _request_declaring_no_content_type(b"\xff{}")
+
+ if parses:
+ with pytest.raises(RunnerRequestError):
+ await handler(request)
+ framework_handler.assert_not_awaited()
+ else:
+ # A strict route leaves the body to FastAPI, which reads it as raw bytes the model refuses field by field.
+ await handler(request)
+ framework_handler.assert_awaited_once()
diff --git a/api/tests/unit/test_method_ref_run.py b/api/tests/unit/test_method_ref_run.py
index 697a51426..d253610c9 100644
--- a/api/tests/unit/test_method_ref_run.py
+++ b/api/tests/unit/test_method_ref_run.py
@@ -30,6 +30,7 @@ from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.problem_view import mark_operator_request
from pipelex_api.routes.pipelex.pipeline import router as pipeline_router
from tests.unit._constants import STUB_METHOD_ADDRESS, STUB_METHOD_COMMIT_SHA, STUB_METHOD_MANIFEST, VALID_MTHDS
+from tests.unit._problems import assert_problem
_METHOD_REF = f"{STUB_METHOD_ADDRESS}@v0.1.0"
_TREE_NS = "pipelex_api.method_tree_request"
@@ -262,9 +263,8 @@ class TestMethodRefRun:
mocker.patch(f"{_TREE_NS}.is_pipe_func_sandbox_hosted", return_value=False)
client, _ = _build_client(mocker)
response = client.post("/v1/execute", json={"method_ref": _METHOD_REF, "inputs": {}})
- assert response.status_code == 403, response.text
- assert response.headers["content-type"] == "application/problem+json"
- assert response.json()["error_type"] == "CustomCodeRequiresSandbox"
+ problem = assert_problem(response, status=501, code="pipelex.deployment.custom_code_requires_sandbox")
+ assert problem["params"] == {"origin": "package"}
def test_python_package_is_written_whole_when_sandbox_hosted(self, mocker: MockerFixture, install_method_package: Callable[..., Path]):
install_method_package(files={"documents.mthds": VALID_MTHDS, "funcs/pipe_func.py": _PIPE_FUNC_PY})
diff --git a/api/tests/unit/test_method_ref_validate.py b/api/tests/unit/test_method_ref_validate.py
index b45d9ca32..ae9efd77d 100644
--- a/api/tests/unit/test_method_ref_validate.py
+++ b/api/tests/unit/test_method_ref_validate.py
@@ -18,6 +18,7 @@ from mthds.protocol.problem.registry import CoreCode
from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.routes import router as api_router
from tests.unit._constants import INVALID_MAIN_PIPE_MTHDS, STUB_METHOD_ADDRESS, VALID_MTHDS
+from tests.unit._problems import assert_problem
_METHOD_REF = f"{STUB_METHOD_ADDRESS}@v0.1.0"
@@ -48,10 +49,10 @@ class TestMethodRefValidate:
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is False
- assert body["validation_errors"], "an invalid verdict must carry a non-empty validation_errors[]"
+ assert body["errors"], "an invalid verdict must carry a non-empty errors[]"
# The package's real relative file name fed `mthds_sources`, so the diagnostic points
- # at the owning file rather than carrying a null source.
- assert body["validation_errors"][0]["source"] == "broken.mthds"
+ # at the owning file rather than carrying no file.
+ assert body["errors"][0]["location"]["file"] == "broken.mthds"
def test_resolution_failure_is_non_2xx_problem_json_never_a_false_verdict(self, install_method_package: Callable[..., Path]):
install_method_package(files={"documents.mthds": VALID_MTHDS})
@@ -70,14 +71,13 @@ class TestMethodRefValidate:
client = _build_client()
both = client.post("/v1/validate", json={"method_ref": _METHOD_REF, "mthds_contents": [VALID_MTHDS]})
neither = client.post("/v1/validate", json={})
- for response in (both, neither):
- assert response.status_code == 422, response.text
- assert response.headers["content-type"] == "application/problem+json"
- assert "exactly one of" in response.json()["detail"]
+ # The request model's own rule names the field to change: the second selector sent, or the first when none is.
+ # Its message is the operator's to read.
+ assert_problem(both, status=422, code="request.invalid", field="method_ref")
+ assert_problem(neither, status=422, code="request.invalid", field="mthds_contents")
def test_mthds_sources_do_not_accompany_a_method_ref(self, install_method_package: Callable[..., Path]):
install_method_package(files={"documents.mthds": VALID_MTHDS})
client = _build_client()
response = client.post("/v1/validate", json={"method_ref": _METHOD_REF, "mthds_sources": ["main.mthds"]})
- assert response.status_code == 422, response.text
- assert "named by their tree paths" in response.json()["detail"]
+ assert_problem(response, status=422, code="request.invalid", field="mthds_sources")
diff --git a/api/tests/unit/test_method_requirements_refusal.py b/api/tests/unit/test_method_requirements_refusal.py
index e9ab12107..3144ec0ba 100644
--- a/api/tests/unit/test_method_requirements_refusal.py
+++ b/api/tests/unit/test_method_requirements_refusal.py
@@ -246,10 +246,9 @@ class TestMethodRequirementsRefusal:
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is False
- (item,) = body["validation_errors"]
- assert item["source"] == "requirements.txt"
- assert item["line"] == 1
- assert "pandas 2.2.3 is there" in item["message"]
+ (item,) = body["errors"]
+ assert item["code"] == "method.dependency_missing"
+ assert item["location"] == {"file": "requirements.txt", "line": 1}
assert validator.calls == 0
@pytest.mark.usefixtures("sandbox_hosted_mode")
diff --git a/api/tests/unit/test_method_tree_runs.py b/api/tests/unit/test_method_tree_runs.py
index 3e3885fc9..3e9fe2d3f 100644
--- a/api/tests/unit/test_method_tree_runs.py
+++ b/api/tests/unit/test_method_tree_runs.py
@@ -26,6 +26,7 @@ from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.problem_view import mark_operator_request
from pipelex_api.routes import router as api_router
from pipelex_api.routes.blob_upload import router as blob_upload_router
+from tests.unit._problems import assert_problem
_PIPELINE_NS = "pipelex_api.routes.pipelex.pipeline"
@@ -138,11 +139,8 @@ class TestMethodTreeRuns:
"/v1/execute", json={"files": {"greet.mthds": _GREET_MTHDS, "notes.txt": _hash_entry(_NOTES)}, "inputs": {"text": "x"}}
)
- assert response.status_code == 422, response.text
- problem = response.json()
- assert problem["error_type"] == "MissingBlobs"
- assert problem["missing_blobs"] == [sha256_hex(_NOTES)]
- assert "/v1/blobs/missing" in problem["detail"]
+ problem = assert_problem(response, status=422, code="request.blobs_missing")
+ assert problem["params"] == {"missing_blobs": [sha256_hex(_NOTES)]}
def test_a_size_other_than_the_held_bytes_is_a_mismatch_no_upload_repeats(self, mocker: MockerFixture) -> None:
"""A sender following the answers, asking which blobs are missing and uploading them, ends at the mismatch, never in a loop."""
@@ -160,10 +158,8 @@ class TestMethodTreeRuns:
assert uploaded.status_code == 204, uploaded.text
for response in (first, again):
- assert response.status_code == 422, response.text
- problem = response.json()
- assert problem["error_type"] == "BlobMismatch"
- assert problem["mismatched_blobs"] == [{"sha256": sha256_hex(_NOTES), "held_size": len(_NOTES)}]
+ # Not `request.blobs_missing`, which would send the sender to upload the same bytes again.
+ assert_problem(response, status=422, code="request.invalid", field="files")
def test_a_hash_resolves_only_in_the_callers_own_scope(self, mocker: MockerFixture) -> None:
client = _build_client(mocker)
@@ -175,8 +171,7 @@ class TestMethodTreeRuns:
assert own.status_code == 200, own.text
assert "Hello a" in _run_output(own.json())
- assert other.status_code == 422, other.text
- assert other.json()["error_type"] == "MissingBlobs"
+ assert_problem(other, status=422, code="request.blobs_missing")
def test_a_callers_bundle_that_does_not_parse_is_its_422_named_by_tree_path(self, mocker: MockerFixture) -> None:
"""The written tree is the caller's own library directory, so its refusal is the caller's 422, never the runner's 500."""
@@ -211,7 +206,7 @@ class TestMethodTreeRuns:
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is False
- assert {item["source"] for item in body["validation_errors"]} == {"methods/broken.mthds"}
+ assert {item["location"]["file"] for item in body["errors"]} == {"methods/broken.mthds"}
_assert_no_host_path(body)
@pytest.mark.usefixtures("sandbox_hosted_mode")
@@ -225,9 +220,9 @@ class TestMethodTreeRuns:
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is False, body
- (item,) = body["validation_errors"]
- assert item["source"] == "helpers/broken.py"
- assert item["line"] == 4
+ (item,) = body["errors"]
+ assert item["location"]["file"] == "helpers/broken.py"
+ assert item["location"]["line"] == 4
_assert_no_host_path(body)
def test_python_in_a_tree_is_refused_where_it_could_not_run(self, mocker: MockerFixture) -> None:
@@ -235,8 +230,8 @@ class TestMethodTreeRuns:
response = client.post("/v1/validate", json={"files": {"greet.mthds": _GREET_MTHDS, "helpers/tool.py": "VALUE = 1\n"}})
- assert response.status_code == 403, response.text
- assert response.json()["error_type"] == "CustomCodeRequiresSandbox"
+ problem = assert_problem(response, status=501, code="pipelex.deployment.custom_code_requires_sandbox")
+ assert problem["params"] == {"origin": "bundle"}
def test_a_json_constant_outside_the_tree_is_never_a_server_error(self, mocker: MockerFixture) -> None:
"""`NaN` is the rest of the server's to judge where it stands outside a map of file entries, and a 422 inside one."""
@@ -252,8 +247,7 @@ class TestMethodTreeRuns:
assert response.status_code == 422, response.text
assert response.json()["code"] == CoreCode.INPUT_INVALID
assert response.json()["domain"] == "input"
- assert inside_the_tree.status_code == 422, inside_the_tree.text
- assert inside_the_tree.json()["error_type"] == "InvalidMethodFiles"
+ assert_problem(inside_the_tree, status=422, code="request.invalid", field="files")
@pytest.mark.parametrize("encoding", ["utf-16", "utf-32", "utf-8-sig"])
def test_validate_reads_a_tree_from_a_body_in_any_json_encoding(self, mocker: MockerFixture, encoding: str) -> None:
@@ -283,7 +277,7 @@ class TestMethodTreeRuns:
assert validated.status_code == 200, validated.text
verdict = validated.json()
assert verdict["is_valid"] is False
- assert [item["source"] for item in verdict["validation_errors"]] == ["bad.mthds"]
+ assert [item["location"]["file"] for item in verdict["errors"]] == ["bad.mthds"]
_assert_no_host_path(verdict)
@pytest.mark.usefixtures("sandbox_hosted_mode")
@@ -296,7 +290,7 @@ class TestMethodTreeRuns:
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is False, body
- assert [item["source"] for item in body["validation_errors"]] == ["helpers/nul.py"]
+ assert [item["location"]["file"] for item in body["errors"]] == ["helpers/nul.py"]
def test_files_sent_in_resources_are_held_to_the_tree_limits(self, mocker: MockerFixture) -> None:
mocker.patch("pipelex_api.method_tree_request.MAX_METHOD_TREE_FILES", 2)
@@ -307,15 +301,17 @@ class TestMethodTreeRuns:
past = client.post("/v1/validate", json={"files": files, "resources": {"extra.txt": base64.b64encode(b"one more").decode("ascii")}})
assert within.status_code == 200, within.text
- assert past.status_code == 422, past.text
- assert past.json()["error_type"] == "MethodTreeTooLarge"
- assert "`resources`" in past.json()["detail"]
+ problem = assert_problem(past, status=422, code="method.package_invalid")
+ assert problem["params"] == {"reason": "too_many_files", "limit": 2}
@pytest.mark.parametrize(
- ("limit", "value"),
- [("MAX_METHOD_DEPENDENCIES", 0), ("MAX_METHOD_REQUEST_TOTAL_BYTES", len(_GREET_MTHDS) + 10)],
+ ("limit", "value", "reason"),
+ [
+ ("MAX_METHOD_DEPENDENCIES", 0, "too_many_dependencies"),
+ ("MAX_METHOD_REQUEST_TOTAL_BYTES", len(_GREET_MTHDS) + 10, "method_too_large"),
+ ],
)
- def test_a_method_and_its_dependencies_are_held_to_limits_together(self, mocker: MockerFixture, limit: str, value: int) -> None:
+ def test_a_method_and_its_dependencies_are_held_to_limits_together(self, mocker: MockerFixture, limit: str, value: int, reason: str) -> None:
"""Each tree passes its own limits, yet the request carries too many trees, or too many bytes across them."""
mocker.patch(f"pipelex_api.method_tree_request.{limit}", value)
client = _build_client(mocker)
@@ -323,8 +319,8 @@ class TestMethodTreeRuns:
response = client.post("/v1/validate", json={"files": {"greet.mthds": _GREET_MTHDS}, "dependencies": {_DEPENDENCY_ADDRESS: dependency}})
- assert response.status_code == 422, response.text
- assert response.json()["error_type"] == "MethodTreeTooLarge"
+ problem = assert_problem(response, status=422, code="method.package_invalid")
+ assert problem["params"] == {"reason": reason, "limit": value}
@pytest.mark.parametrize("last_segment", ["..", "."])
def test_a_nameless_dependency_keyed_by_an_address_no_directory_can_take_is_refused(self, mocker: MockerFixture, last_segment: str) -> None:
@@ -335,7 +331,5 @@ class TestMethodTreeRuns:
response = client.post("/v1/validate", json={"files": {"greet.mthds": _GREET_MTHDS}, "dependencies": {address: dependency}})
- assert response.status_code == 422, response.text
- problem = response.json()
- assert problem["error_type"] == "InvalidMethodFiles"
- assert "cannot name a package's directory" in problem["detail"]
+ problem = assert_problem(response, status=422, code="method.package_invalid")
+ assert problem["params"] == {"reason": "package_name_invalid", "path": f"{address}/METHODS.toml"}
diff --git a/api/tests/unit/test_models_check_route.py b/api/tests/unit/test_models_check_route.py
index d4d609803..99cb64b64 100644
--- a/api/tests/unit/test_models_check_route.py
+++ b/api/tests/unit/test_models_check_route.py
@@ -9,6 +9,7 @@ from fastapi.testclient import TestClient
from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.routes import router as api_router
from pipelex_api.routes.pipelex.agent.models import MAX_MODEL_REFERENCE_LENGTH
+from tests.unit._problems import assert_problem
_CHECK_PATH = "/v1/models/check"
@@ -91,11 +92,10 @@ class TestModelsCheckRoute:
assert validation.status_code == 200, validation.text
report = validation.json()
assert report["is_valid"] is False
- (item,) = report["validation_errors"]
- assert item["error_type"] == "unknown_model"
- assert item["model_reference"] == llm_handle
- assert item["model_type"] == "img_gen"
- assert "but not as an image-generation model" in item["message"]
+ (item,) = report["errors"]
+ assert item["code"] == "model.unknown"
+ assert item["params"] == {"model": llm_handle, "model_type": "img_gen"}
+ assert item["location"]["field"] == "model"
def test_doc_gen_is_a_category_of_the_check(self):
client = _build_client()
@@ -114,28 +114,25 @@ class TestModelsCheckRoute:
assert verdict["category"] is None
@pytest.mark.parametrize(
- ("params", "error_type"),
+ ("params", "field"),
[
- pytest.param([], "ValidationError", id="reference-missing"),
- pytest.param([("reference", "@a"), ("reference", "@b")], "ValidationError", id="reference-repeated"),
- pytest.param([("reference", "@a"), ("type", "llm"), ("type", "extract")], "ValidationError", id="type-repeated"),
- pytest.param([("reference", "")], "InvalidModelReference", id="empty"),
- pytest.param([("reference", " ")], "InvalidModelReference", id="blank"),
- pytest.param([("reference", "~")], "InvalidModelReference", id="sigil-alone"),
- pytest.param([("reference", "handle:")], "InvalidModelReference", id="namespace-alone"),
- pytest.param([("reference", "@" + "x" * MAX_MODEL_REFERENCE_LENGTH)], "InvalidModelReference", id="past-the-bound"),
- pytest.param([("reference", "@a"), ("type", "bogus_category")], "InvalidModelCategory", id="type-unknown"),
- pytest.param([("reference", "@a"), ("type", "")], "InvalidModelCategory", id="type-empty"),
+ pytest.param([], "reference", id="reference-missing"),
+ pytest.param([("reference", "@a"), ("reference", "@b")], "reference", id="reference-repeated"),
+ pytest.param([("reference", "@a"), ("type", "llm"), ("type", "extract")], "type", id="type-repeated"),
+ pytest.param([("reference", "")], "reference", id="empty"),
+ pytest.param([("reference", " ")], "reference", id="blank"),
+ pytest.param([("reference", "~")], "reference", id="sigil-alone"),
+ pytest.param([("reference", "handle:")], "reference", id="namespace-alone"),
+ pytest.param([("reference", "@" + "x" * MAX_MODEL_REFERENCE_LENGTH)], "reference", id="past-the-bound"),
+ pytest.param([("reference", "@a"), ("type", "bogus_category")], "type", id="type-unknown"),
+ pytest.param([("reference", "@a"), ("type", "")], "type", id="type-empty"),
],
)
- def test_a_request_with_no_verdict_is_an_input_422(self, params: list[tuple[str, str]], error_type: str):
+ def test_a_request_with_no_verdict_is_an_input_422(self, params: list[tuple[str, str]], field: str):
client = _build_client()
response = client.get(_CHECK_PATH, params=tuple(params))
- assert response.status_code == 422, response.text
- assert response.headers["content-type"] == "application/problem+json"
- problem = response.json()
- assert problem["error_type"] == error_type
- assert problem["error_domain"] == "input"
+ problem = assert_problem(response, status=422, code="request.invalid", field=field)
+ assert problem["domain"] == "input"
assert "resolution" not in problem
diff --git a/api/tests/unit/test_openapi_contract.py b/api/tests/unit/test_openapi_contract.py
index ccdd5e208..a3b30788e 100644
--- a/api/tests/unit/test_openapi_contract.py
+++ b/api/tests/unit/test_openapi_contract.py
@@ -7,9 +7,10 @@ regenerated from this same `fastapi_app.openapi()`) tells a client about failure
(`pipelex_api.exception_handlers`), so every documented 4xx/5xx must say so — with a `$ref` to the
typed `ProblemDocument`, not FastAPI's default `HTTPValidationError` on `application/json`.
- The statuses a given route can additionally produce (`/execute`'s provider-429, `/start`'s
- 409 duplicate run, `/resolve`'s 501 `method_ref`, …) are documented on that route.
-- The `suggested_fix` surface pipelex's codegen work added reaches the wire: a client reading
- the artifact can find it from a problem document, not just from `/validate`'s 200 arm.
+ 409 duplicate run, the 404 of a method address nothing is fetched from, the 501 of a deployment
+ policy, …) are documented on that route.
+- The `suggested_fix` surface pipelex's codegen work added reaches the wire, on the standard's
+ problem item, which a problem document's `errors[]` and `/validate`'s 200 arms carry alike.
- `x-mthds-protocol` marks exactly the MTHDS Protocol operations and nothing else — the flag is
how a conformance suite or a third-party runner extracts the portable subset of this artifact,
so a Pipelex extension wearing it would misrepresent the standard.
@@ -59,9 +60,9 @@ MTHDS_PROTOCOL_OPERATIONS = {
# The extra statuses each route can produce on top of COMMON_STATUSES.
ROUTE_EXTRA_STATUSES = {
- ("/v1/execute", "post"): (403, 429),
- ("/v1/start", "post"): (400, 403, 409, 501),
- ("/v1/validate", "post"): (403,),
+ ("/v1/execute", "post"): (403, 404, 429, 501),
+ ("/v1/start", "post"): (403, 404, 409, 501),
+ ("/v1/validate", "post"): (403, 404, 501),
("/v1/resolve", "post"): (403, 404, 501),
("/v1/pipe-io", "post"): (403, 404, 501),
("/v1/codegen", "post"): (403, 404, 501),
@@ -173,52 +174,51 @@ class TestOpenApiErrorContract:
rate_limited = openapi_schema["paths"]["/v1/execute"]["post"]["responses"]["429"]
assert "Retry-After" in rate_limited["headers"]
- def test_problem_document_items_carry_the_standard_s_suggested_fix(self, openapi_schema: dict[str, Any]):
- """A problem document publishes `errors[]` of the standard's `ProblemItem`, whose fix is the standard's
- `ProblemSuggestedFix` (naming its file `file`), while a 200 invalid arm's `ValidationErrorItem` keeps Pipelex's
- `SuggestedFix` (naming it `source`): each under its own name, never a module-qualified one.
+ def test_problem_items_carry_the_standard_s_suggested_fix(self, openapi_schema: dict[str, Any]):
+ """A problem document's `errors[]` and both `/validate` arms' items are the standard's `ProblemItem`, whose fix is
+ the standard's `ProblemSuggestedFix` (naming its file `file`): every schema the standard's item reaches carries the
+ `Problem` prefix, never a module-qualified name, and Pipelex's own `ValidationErrorItem` is off the wire.
"""
schemas = openapi_schema["components"]["schemas"]
assert "validation_errors" not in schemas["ProblemDocument"]["properties"]
errors = schemas["ProblemDocument"]["properties"]["errors"]
item_refs = [option["items"]["$ref"] for option in errors["anyOf"] if option.get("type") == "array"]
assert item_refs == ["#/components/schemas/ProblemItem"]
+ assert schemas["InvalidReport"]["properties"]["errors"]["items"]["$ref"] == "#/components/schemas/ProblemItem"
+ assert schemas["ValidReport"]["properties"]["warnings"]["items"]["$ref"] == "#/components/schemas/ProblemItem"
+ assert "ValidationErrorItem" not in schemas
- def _fix_refs(item_schema: str) -> list[str]:
- return [option["$ref"] for option in schemas[item_schema]["properties"]["suggested_fix"]["anyOf"] if "$ref" in option]
-
- assert _fix_refs("ProblemItem") == ["#/components/schemas/ProblemSuggestedFix"]
- assert _fix_refs("ValidationErrorItem") == ["#/components/schemas/SuggestedFix"]
+ fix_refs = [option["$ref"] for option in schemas["ProblemItem"]["properties"]["suggested_fix"]["anyOf"] if "$ref" in option]
+ assert fix_refs == ["#/components/schemas/ProblemSuggestedFix"]
assert "file" in schemas["ProblemSuggestedFix"]["properties"]
- assert "source" in schemas["SuggestedFix"]["properties"]
assert not [name for name in schemas if "__" in name]
def test_suggested_fix_surface_is_published(self, openapi_schema: dict[str, Any]):
- """The codegen fix planner's output is part of the published contract: a `ValidationErrorItem`
- may carry a `SuggestedFix`, whose `ops[]` are the machine contract (the rendered diff is not).
+ """The codegen fix planner's output is part of the published contract: a problem item may carry the standard's
+ suggested fix, whose `ops[]` are the machine contract (the rendered diff is not).
- An op is a union discriminated on `kind`, one member model per kind — so a client picks the
- member off the wire value rather than reading a single open shape whose fields depend on a
- `kind` enum beside them. The whole vocabulary is published here: this is the `.mthds` fix
- path, which carries every kind (a ledger carries only the structural subset).
+ Each op is one of the standard's member models, one per kind it lists, plus the reader-side catch-all for a kind it
+ does not; every member is a published schema, so a client that reads an op off the wire lands on a shape the
+ artifact defines.
"""
schemas = openapi_schema["components"]["schemas"]
- suggested_fix = schemas["ValidationErrorItem"]["properties"]["suggested_fix"]
- assert any(option.get("$ref") == "#/components/schemas/SuggestedFix" for option in suggested_fix["anyOf"])
- fix_properties = schemas["SuggestedFix"]["properties"]
+ fix_properties = schemas["ProblemSuggestedFix"]["properties"]
assert {"fix_code", "description", "safety", "ops"} <= set(fix_properties)
- op_schema = fix_properties["ops"]["items"]
- assert op_schema["discriminator"]["propertyName"] == "kind"
- kind_mapping = op_schema["discriminator"]["mapping"]
- assert set(kind_mapping) == {"set_key", "ensure_table", "delete_key", "delete_table", "rename_table_key", "move_key", "remap_value"}
- # Every member the discriminator names is a `oneOf` option AND a published schema, so a
- # client that resolves a `kind` off the wire always lands on a shape the artifact defines.
- member_refs = {option["$ref"] for option in op_schema["oneOf"]}
- assert set(kind_mapping.values()) == member_refs
- assert all(ref.rsplit("/", 1)[-1] in schemas for ref in member_refs)
-
- assert set(schemas["FixSafety"]["enum"]) == {"safe", "unsafe"}
+ member_refs = {option["$ref"] for option in fix_properties["ops"]["items"]["oneOf"]}
+ member_names = {ref.rsplit("/", 1)[-1] for ref in member_refs}
+ assert member_names == {
+ "ProblemSetKeyOp",
+ "ProblemEnsureTableOp",
+ "ProblemDeleteKeyOp",
+ "ProblemDeleteTableOp",
+ "ProblemRenameTableKeyOp",
+ "ProblemMoveKeyOp",
+ "ProblemRemapValueOp",
+ "ProblemUnknownFixOp",
+ }
+ assert member_names <= set(schemas)
+ assert set(schemas["ProblemFixSafety"]["enum"]) == {"safe", "unsafe"}
def test_execute_publishes_the_tokens_usage_wire_records(self, openapi_schema: dict[str, Any]):
"""`/execute` returns a `JSONResponse` built from a trimmed dump, so FastAPI never validates
diff --git a/api/tests/unit/test_pipe_io_route.py b/api/tests/unit/test_pipe_io_route.py
index 6a9738c20..03f1ee773 100644
--- a/api/tests/unit/test_pipe_io_route.py
+++ b/api/tests/unit/test_pipe_io_route.py
@@ -44,6 +44,7 @@ from tests.unit._constants import (
STUB_METHOD_MANIFEST_NOMAIN_ENTRY,
VALID_MTHDS,
)
+from tests.unit._problems import assert_problem
PIPE_IO_PATH = "/v1/pipe-io"
@@ -53,11 +54,9 @@ STUB_METHOD_REF = f"{STUB_METHOD_ADDRESS}@v0.1.0"
# The three artifact maps the valid arm carries, sharing one key set.
ARTIFACT_FIELDS = ("pipe_io_contracts", "input_form", "output_form")
-# The `error_type` of a malformed request's 422, which the API authors itself; a pipe-selection refusal is the
-# runtime's, answered under its registry code.
-REQUEST_SHAPE_ERROR = "ValidationError"
-# A `files` member that is no method tree, refused by the standard's reader as on `/v1/validate`.
-INVALID_METHOD_FILES_ERROR = "InvalidMethodFiles"
+# The code of a malformed request's 422, which the runner authors itself; a pipe-selection refusal is answered under the
+# code its failure names.
+REQUEST_SHAPE_CODE = "request.invalid"
# Every field only the valid arm carries: the invalid arm is the crate verdict alone.
VALID_ARM_ONLY_FIELDS = ("pipe_ref", "default_pipe_ref", *ARTIFACT_FIELDS, "pending_signatures", "is_runnable", "files")
@@ -81,7 +80,7 @@ def _valid_arm(client: TestClient, payload: dict[str, Any]) -> dict[str, Any]:
assert response.status_code == 200, response.text
body: dict[str, Any] = response.json()
assert body["is_valid"] is True, response.text
- assert "validation_errors" not in body
+ assert "errors" not in body
return body
@@ -90,16 +89,12 @@ def _assert_keys(body: dict[str, Any], expected: set[str]) -> None:
assert set(body[field_name]) == expected, f"`{field_name}` keyed by {sorted(body[field_name])}, expected {sorted(expected)}"
-def _assert_input_422(response: Any, *, error_type: str) -> str:
- """Assert an API-authored no-verdict input 422 of the given `error_type`, and return its detail."""
- assert response.status_code == 422, response.text
- assert response.headers["content-type"] == "application/problem+json"
- problem = response.json()
- assert problem["error_type"] == error_type, response.text
- assert problem["error_domain"] == "input"
+def _assert_input_422(response: Any, *, code: str) -> dict[str, Any]:
+ """Assert a runner-authored no-verdict input 422 of the given `code`, and return its problem."""
+ problem = assert_problem(response, status=422, code=code)
+ assert problem["domain"] == "input"
assert "is_valid" not in problem
- detail: str = problem["detail"]
- return detail
+ return problem
def _assert_selection_refusal(response: Any, *, code: CoreCode, params: dict[str, Any]) -> dict[str, Any]:
@@ -369,8 +364,8 @@ class TestPipeIoRoute:
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is False
- assert body["validation_errors"]
- assert body["validation_errors"][0]["source"] == "broken.mthds"
+ assert body["errors"]
+ assert body["errors"][0]["location"]["file"] == "broken.mthds"
assert body["message"]
for field_name in VALID_ARM_ONLY_FIELDS:
assert field_name not in body, f"the invalid arm never carries `{field_name}`"
@@ -445,24 +440,27 @@ class TestPipeIoRoute:
)
def test_closure_selector_xor_is_a_request_shape_422(self, payload: dict[str, Any]):
client = _build_client()
- _assert_input_422(client.post(PIPE_IO_PATH, json=payload), error_type=REQUEST_SHAPE_ERROR)
+ _assert_input_422(client.post(PIPE_IO_PATH, json=payload), code=REQUEST_SHAPE_CODE)
def test_an_out_of_bounds_pipe_ref_is_a_request_shape_422(self):
client = _build_client()
payload = {"files": {"main.mthds": VALID_MTHDS}, "pipe_ref": "x" * (MAX_PIPE_CODE_LEN + 1)}
- _assert_input_422(client.post(PIPE_IO_PATH, json=payload), error_type=REQUEST_SHAPE_ERROR)
+ _assert_input_422(client.post(PIPE_IO_PATH, json=payload), code=REQUEST_SHAPE_CODE)
@pytest.mark.parametrize(
- "files",
+ ("files", "code"),
[
- pytest.param({}, id="empty-map"),
- pytest.param([], id="empty-list"),
- pytest.param([{"content": VALID_MTHDS, "source": "main.mthds"}], id="the-retired-list-shape"),
+ pytest.param({}, "method.package_invalid", id="empty-map"),
+ pytest.param([], "request.invalid", id="empty-list"),
+ pytest.param([{"content": VALID_MTHDS, "source": "main.mthds"}], "request.invalid", id="the-retired-list-shape"),
],
)
- def test_a_files_member_that_is_no_method_tree_is_invalid_method_files(self, files: Any):
+ def test_a_files_member_that_is_no_method_tree_is_refused_as_validate_refuses_it(self, files: Any, code: str):
+ # Refused by the standard's reader as on `/v1/validate`: a map that is no tree is the method's, a list is no map.
client = _build_client()
- _assert_input_422(client.post(PIPE_IO_PATH, json={"files": files}), error_type=INVALID_METHOD_FILES_ERROR)
+ problem = assert_problem(client.post(PIPE_IO_PATH, json={"files": files}), status=422, code=code)
+ validate_problem = assert_problem(client.post("/v1/validate", json={"files": files}), status=422, code=code)
+ assert problem.get("params") == validate_problem.get("params")
def test_a_bare_pipe_code_resolves_but_is_answered_qualified(self):
# The engine's entry lookup still accepts a bare request code, falling back across domains, until
diff --git a/api/tests/unit/test_pipeline_bundle.py b/api/tests/unit/test_pipeline_bundle.py
index cc9c305cc..1407a3e3d 100644
--- a/api/tests/unit/test_pipeline_bundle.py
+++ b/api/tests/unit/test_pipeline_bundle.py
@@ -23,7 +23,7 @@ from mthds.protocol.problem.registry import CoreCode
from pipelex.pipeline.pipeline_response import PipelexRunResultStart, RunState
from pytest_mock import MockerFixture
-from pipelex_api.exception_handlers import register_exception_handlers
+from pipelex_api.exception_handlers import ERROR_FRAMES_FIELD, register_exception_handlers
from pipelex_api.problem_view import mark_operator_request
from pipelex_api.routes.pipelex.pipeline import router as pipeline_router
from tests.unit._constants import (
@@ -34,6 +34,7 @@ from tests.unit._constants import (
VENDORED_PROBE_MANIFEST,
VENDORED_PROBE_MTHDS,
)
+from tests.unit._problems import assert_problem
_PIPE_FUNC_PY = "def echo(working_memory):\n return 'hi'\n"
_TREE_NS = "pipelex_api.method_tree_request"
@@ -215,12 +216,9 @@ def _build_client(mocker: MockerFixture, *, as_operator: bool = False) -> tuple[
def _assert_tree_refusal(response: Any, *, code: str, named: str) -> None:
- assert response.status_code == 422, response.text
- problem = response.json()
- assert problem["error_type"] == "InvalidMethodFiles", response.text
- assert problem["tree_refusal"]["code"] == code
- assert named in problem["tree_refusal"]["names"]
- assert repr(named) in problem["detail"] or f"'{named}'" in problem["detail"]
+ """The refusal of a tree breaking the method tree's rule: the refusal's code as the reason, and the path it names."""
+ problem = assert_problem(response, status=422, code="method.package_invalid")
+ assert problem["params"] == {"reason": code, "path": named}, problem
class TestPipelineBundle:
@@ -279,11 +277,16 @@ class TestPipelineBundle:
def test_python_bundle_forbidden_when_not_hosted(self, mocker: MockerFixture):
mocker.patch(f"{_TREE_NS}.is_pipe_func_sandbox_hosted", return_value=False)
client, snapshot = _build_client(mocker)
+ log_spy = mocker.patch("pipelex_api.exception_handlers.log")
response = client.post("/v1/execute", json={"files": {"main.mthds": VALID_MTHDS, "funcs/pipe_func.py": _PIPE_FUNC_PY}})
- assert response.status_code == 403
- assert response.headers["content-type"] == "application/problem+json"
- assert response.json()["error_type"] == "CustomCodeRequiresSandbox"
+ problem = assert_problem(response, status=501, code="pipelex.deployment.custom_code_requires_sandbox")
+ assert problem["params"] == {"origin": "bundle"}
assert snapshot == {}, "the runner was reached"
+ # A caller sending custom code to a deployment without a sandbox can do so at will: a warning without frames.
+ log_spy.error.assert_not_called()
+ fields = log_spy.warning.call_args.kwargs["fields"]
+ assert fields["error.code"] == "pipelex.deployment.custom_code_requires_sandbox"
+ assert ERROR_FRAMES_FIELD not in fields
def test_python_bundle_is_written_with_its_tree_when_hosted(self, mocker: MockerFixture):
mocker.patch(f"{_TREE_NS}.is_pipe_func_sandbox_hosted", return_value=True)
@@ -299,14 +302,13 @@ class TestPipelineBundle:
"/v1/execute",
json={"files": {"main.mthds": VALID_MTHDS}, "bundle_b64": _zip_b64({"main.mthds": VALID_MTHDS})},
)
- assert response.status_code == 422
- assert response.json()["error_type"] == "InvalidBundle"
+ assert_problem(response, status=422, code="request.invalid", field="bundle_b64")
def test_a_tree_holding_no_bundle_is_refused(self, mocker: MockerFixture):
client, snapshot = _build_client(mocker)
response = client.post("/v1/execute", json={"files": {"notes.txt": "x"}, "pipe_code": "smoke.echo", "inputs": {}})
- assert response.status_code == 422, response.text
- assert response.json()["error_type"] == "InvalidBundle"
+ problem = assert_problem(response, status=422, code="method.package_invalid")
+ assert problem["params"] == {"reason": "no_bundle"}
assert snapshot == {}, "the runner was reached"
@pytest.mark.parametrize(
@@ -323,10 +325,7 @@ class TestPipelineBundle:
response = client.post("/v1/execute", content=raw_body, headers={"content-type": "application/json"})
- assert response.status_code == 422, response.text
- problem = response.json()
- assert problem["error_type"] == "InvalidMethodFiles"
- assert problem["tree_refusal"] == {"code": code, "names": [named]}
+ _assert_tree_refusal(response, code=code, named=named)
assert snapshot == {}, "the runner was reached"
def test_a_text_entry_that_is_not_utf8_text_is_refused(self, mocker: MockerFixture):
@@ -335,10 +334,7 @@ class TestPipelineBundle:
response = client.post("/v1/execute", content=raw_body, headers={"content-type": "application/json"})
- assert response.status_code == 422, response.text
- problem = response.json()
- assert problem["error_type"] == "InvalidMethodFiles"
- assert problem["tree_refusal"]["names"] == ["notes.txt"]
+ assert_problem(response, status=422, code="request.invalid", field="files")
assert snapshot == {}, "the runner was reached"
def test_bundle_and_mthds_contents_are_mutually_exclusive(self, mocker: MockerFixture):
@@ -386,10 +382,7 @@ class TestPipelineBundle:
response = client.post("/v1/execute", json={**body, "inputs": {"text": "hi"}})
- assert response.status_code == 422, response.text
- problem = response.json()
- assert problem["error_type"] == "InvalidMethodFiles"
- assert VENDORED_PROBE_ADDRESS in problem["detail"]
+ assert_problem(response, status=422, code="request.invalid", field="dependencies")
assert snapshot == {}, "the runner was reached"
def test_dependencies_without_files_are_refused(self, mocker: MockerFixture):
@@ -419,10 +412,8 @@ class TestPipelineBundle:
response = client.post("/v1/execute", json={"bundle_b64": _zip_b64(files), "inputs": {"text": "hi"}})
- assert response.status_code == 422, response.text
- problem = response.json()
- assert problem["error_type"] == "InvalidMethodFiles"
- assert named in problem["detail"]
+ problem = assert_problem(response, status=422, code="method.package_invalid")
+ assert problem["params"]["path"] == named.strip("'"), problem
assert snapshot == {}, "the runner was reached"
@pytest.mark.parametrize("shape", list(_REFUSED_ARCHIVE_PACKAGES))
@@ -432,10 +423,8 @@ class TestPipelineBundle:
response = client.post("/v1/execute", json={"bundle_b64": _zip_b64(files), "inputs": {"text": "hi"}})
- assert response.status_code == 422, response.text
- problem = response.json()
- assert problem["error_type"] == "InvalidMethodFiles"
- assert named in problem["detail"]
+ problem = assert_problem(response, status=422, code="method.package_invalid")
+ assert problem["params"]["path"] == f"{named}METHODS.toml", problem
assert snapshot == {}, "the runner was reached"
def test_an_archive_whose_only_bundles_are_shipped_packages_is_refused(self, mocker: MockerFixture):
@@ -444,9 +433,8 @@ class TestPipelineBundle:
response = client.post("/v1/execute", json={"bundle_b64": _zip_b64(files), "inputs": {"text": "hi"}})
- assert response.status_code == 422, response.text
- problem = response.json()
- assert problem["error_type"] in {"InvalidBundle", "InvalidMethodFiles"}
+ problem = assert_problem(response, status=422, code="method.package_invalid")
+ assert problem["params"] == {"reason": "empty_tree"}
assert snapshot == {}, "the runner was reached"
@pytest.mark.parametrize("bundle", list(_DUPLICATE_IDENTITY_BUNDLES))
@@ -457,10 +445,8 @@ class TestPipelineBundle:
response = client.post("/v1/execute", json={"bundle_b64": _zip_b64(files), "inputs": {"text": "hi"}})
- assert response.status_code == 422, response.text
- problem = response.json()
- assert problem["error_type"] == "InvalidMethodFiles"
- assert VENDORED_PROBE_ADDRESS.casefold() in problem["detail"].casefold()
+ problem = assert_problem(response, status=422, code="method.package_invalid")
+ assert problem["params"]["reason"] == "dependency_address_collision", problem
assert snapshot == {}, "the runner was reached"
@pytest.mark.parametrize("transport", ["files", "bundle_b64"])
diff --git a/api/tests/unit/test_pipeline_routes.py b/api/tests/unit/test_pipeline_routes.py
index c3efe63c7..2a652dacb 100644
--- a/api/tests/unit/test_pipeline_routes.py
+++ b/api/tests/unit/test_pipeline_routes.py
@@ -14,6 +14,7 @@ from pipelex.base_exceptions import PipelexConfigError
from pipelex.cogt.llm.llm_report import LLMTokensUsage
from pipelex.cogt.usage.cost_category import CostCategory
from pipelex.cogt.usage.token_category import TokenCategory
+from pipelex.errors.problem import ProblemView
from pipelex.pipeline.pipeline_response import PipelexRunResultStart, RunState
from pipelex.system.job_metadata import JobMetadata, RunMetadata
from pipelex.system.storage_scope import SINGLE_TENANT_USER_ID
@@ -21,10 +22,13 @@ from pytest_mock import MockerFixture
import pipelex_api.routes.pipelex.pipeline as pipeline_module
from pipelex_api.exception_handlers import register_exception_handlers
+from pipelex_api.exceptions import CallbackUrlRefusedError
+from pipelex_api.json_body import TOO_DEEPLY_NESTED_REASON
from pipelex_api.limits import MAX_JSON_NESTING_DEPTH
from pipelex_api.middleware import REQUEST_ID_HEADER, RequestIdMiddleware
from pipelex_api.routes.pipelex.pipeline import router as pipeline_router
from tests.unit._constants import VALID_MTHDS
+from tests.unit._problems import assert_problem
def _build_client(mocker: MockerFixture, *, with_request_id_middleware: bool = False) -> tuple[TestClient, Any, Any]:
@@ -114,9 +118,7 @@ class TestPipelineRoutes:
content=b'"just a string"',
headers={"content-type": "application/json"},
)
- assert response.status_code == 422
- assert response.headers["content-type"] == "application/problem+json"
- assert response.json()["error_type"] == "InvalidJSON"
+ assert_problem(response, status=422, code="request.invalid", field="body")
def test_execute_rejects_invalid_json(self, mocker: MockerFixture):
client, _, _ = _build_client(mocker)
@@ -125,14 +127,13 @@ class TestPipelineRoutes:
content=b"{not json",
headers={"content-type": "application/json"},
)
- assert response.status_code == 422
- assert response.headers["content-type"] == "application/problem+json"
- assert response.json()["error_type"] == "InvalidJSON"
+ problem = assert_problem(response, status=422, code="request.malformed")
+ assert problem["params"] == {"reason": "not_json"}
def test_execute_rejects_recursion_error(self, mocker: MockerFixture):
# 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,
+ # before parsing, so the answer is the same 422 `request.malformed` on every interpreter and stack,
# never the catch-all 500 nor a later `ValidationError`.
client, _, _ = _build_client(mocker)
depth = 100_000
@@ -141,14 +142,9 @@ class TestPipelineRoutes:
content=b'{"inputs": ' + b"[" * depth + b"]" * depth + b"}",
headers={"content-type": "application/json"},
)
- assert response.status_code == 422
- assert response.headers["content-type"] == "application/problem+json"
- 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"
+ problem = assert_problem(response, status=422, code="request.malformed")
+ assert problem["domain"] == "input"
+ assert problem["params"] == {"reason": TOO_DEEPLY_NESTED_REASON}
@pytest.mark.parametrize("route", ["/v1/execute", "/v1/start"])
def test_run_routes_bound_nesting_at_the_limit(self, mocker: MockerFixture, route: str):
@@ -164,9 +160,8 @@ class TestPipelineRoutes:
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"]
+ refusal = assert_problem(refused, status=422, code="request.malformed")
+ assert refusal["params"] == {"reason": TOO_DEEPLY_NESTED_REASON}
assert execute_mock.await_count + start_mock.await_count == 1
@pytest.mark.parametrize("route", ["/v1/execute", "/v1/start"])
@@ -185,11 +180,8 @@ class TestPipelineRoutes:
"inputs": {"text": {"__class__": "Popen", "__module__": "subprocess", "args": ["touch", "pipelex-api-rce-probe"]}},
},
)
- assert response.status_code == 422
- assert response.headers["content-type"] == "application/problem+json"
- problem = response.json()
- assert problem["error_type"] == "ReservedObjectKey"
- assert problem["error_domain"] == "input"
+ problem = assert_problem(response, status=422, code="pipelex.security.reserved_key")
+ assert problem["domain"] == "input"
popen_mock.assert_not_called()
execute_mock.assert_not_awaited()
start_mock.assert_not_awaited()
@@ -212,27 +204,23 @@ class TestPipelineRoutes:
"""
client, execute_mock, _ = _build_client(mocker)
response = client.post("/v1/execute", json=body)
- assert response.status_code == 422, label
- assert response.headers["content-type"] == "application/problem+json", label
- problem = response.json()
- assert problem["error_type"] == "ReservedObjectKey", label
- assert problem["error_domain"] == "input", label
- assert f"'{reserved_key}'" in problem["detail"], label
+ problem = assert_problem(response, status=422, code="pipelex.security.reserved_key")
+ assert problem["domain"] == "input", label
+ assert problem["params"] == {"keys": [reserved_key]}, label
execute_mock.assert_not_awaited()
def test_execute_bounds_the_reserved_key_it_echoes(self, mocker: MockerFixture):
- """Any key starting with `__kajson` is refused, so the caller picks its length. The `detail`
- names it cut to the correlation-field bound, since the detail is also logged as a field.
+ """Any key starting with `__kajson` is refused, so the caller picks its length. The problem
+ names it cut to the correlation-field bound, so the caller cannot inflate the answer.
"""
client, _, _ = _build_client(mocker)
long_key = "__kajson" + "k" * 100_000
response = client.post("/v1/execute", json={"pipe_code": "echo", "inputs": {"doc": {long_key: 1}}})
- assert response.status_code == 422
- problem = response.json()
- assert problem["error_type"] == "ReservedObjectKey"
- assert "'__kajsonkkkk" in problem["detail"]
- assert "…'" in problem["detail"]
- assert len(problem["detail"]) < 1_000
+ problem = assert_problem(response, status=422, code="pipelex.security.reserved_key")
+ (shown_key,) = problem["params"]["keys"]
+ assert shown_key.startswith("__kajsonkkkk")
+ assert shown_key.endswith("…")
+ assert len(response.text) < 2_000
def test_execute_accepts_marker_lookalikes_as_plain_data(self, mocker: MockerFixture):
"""Only the reserved keys themselves are refused: a value that mentions `__class__`, and a
@@ -379,7 +367,7 @@ class TestPipelineRoutes:
"/v1/start",
json={
"pipe_code": body_pipe_code,
- # An AWS-metadata URL — blocked by `_is_disallowed_host`, so
+ # An AWS-metadata URL — blocked by `is_disallowed_host`, so
# `_validate_extras` raises 422 before `from_body` runs.
"callback_urls": ["http://169.254.169.254/latest/meta-data/"],
},
@@ -440,11 +428,35 @@ class TestPipelineRoutes:
"/v1/start",
json={"pipe_code": "echo", "callback_urls": [bad_url]},
)
- assert response.status_code == 422
- assert response.headers["content-type"] == "application/problem+json"
- assert response.json()["error_type"] == "InvalidCallbackUrls"
+ problem = assert_problem(response, status=422, code="security.input_url_refused")
+ assert problem["params"]["input"] == "callback_urls"
+ assert problem["location"] == {"field": "callback_urls"}
+ assert bad_url not in response.text
start_mock.assert_not_awaited()
+ @pytest.mark.parametrize("hostless_url", ["http://./hook", "https://../hook"])
+ def test_a_callback_host_of_dots_alone_names_no_host(self, mocker: MockerFixture, hostless_url: str):
+ # Empty once its trailing dots are dropped, as the SSRF rule drops them: a URL naming no host, the shape of the
+ # field, never a security refusal whose sentence names a class of destination it has none of.
+ client, _, start_mock = _build_client(mocker)
+ log_spy = mocker.patch("pipelex.errors.problem._warn")
+ response = client.post("/v1/start", json={"pipe_code": "echo", "callback_urls": [hostless_url]})
+ assert_problem(response, status=422, code="request.invalid", field="callback_urls")
+ log_spy.assert_not_called()
+ start_mock.assert_not_awaited()
+
+ def test_a_callback_refusal_naming_no_class_leaves_the_parameter_out(self, mocker: MockerFixture):
+ # A refusal that states no class of destination gives no `target_class`, rather than a `None` for its code to
+ # refuse, so no parameter is dropped and logged.
+ warn_spy = mocker.patch("pipelex.errors.problem._warn")
+ refusal = CallbackUrlRefusedError("callback URL host is not allowed")
+ assert "target_class" not in refusal.problem_params()
+ problem = refusal.to_problem(view=ProblemView.OPERATOR)
+ assert problem.params is not None
+ assert "target_class" not in problem.params.as_wire()
+ dropped = [call for call in warn_spy.call_args_list if "parameter" in call.kwargs["message"]]
+ assert not dropped, dropped
+
def test_start_rejects_too_many_callbacks(self, mocker: MockerFixture):
client, _, start_mock = _build_client(mocker)
response = client.post(
@@ -454,15 +466,10 @@ class TestPipelineRoutes:
"callback_urls": [f"https://example.com/{idx}" for idx in range(20)],
},
)
- # `callback_urls` exceeds `PipelineApiExtras.max_length`. The route
- # validates extras explicitly (`_validate_extras`) and re-raises the
- # resulting Pydantic `ValidationError` via `raise_validation_error`
- # with the more-specific `InvalidCallbackUrls` error_type — so the
- # response is RFC 7807 422 / `application/problem+json` but classified
- # one level finer than the generic FastAPI automatic-validation path.
- assert response.status_code == 422
- assert response.headers["content-type"] == "application/problem+json"
- assert response.json()["error_type"] == "InvalidCallbackUrls"
+ # `callback_urls` exceeds `PipelineApiExtras.max_length`. The route validates extras explicitly
+ # (`_validate_extras`) and answers the resulting pydantic `ValidationError` as the runner's own refusal,
+ # `request.invalid` naming the field, as FastAPI's automatic validation path does.
+ assert_problem(response, status=422, code="request.invalid", field="callback_urls")
start_mock.assert_not_awaited()
@@ -510,9 +517,7 @@ class TestStorageScopeReachesTheRun:
# becomes a storage key prefix, so a traversal in it escapes the tenant.
client, _, start_mock = _build_client(mocker)
response = client.post("/v1/start", json={"pipe_code": "echo", "storage_scope": bad_scope})
- assert response.status_code == 422
- assert response.headers["content-type"] == "application/problem+json"
- # Classified by the field that failed: this used to answer `InvalidCallbackUrls`
- # on a request that carried no callback at all.
- assert response.json()["error_type"] == "InvalidStorageScope"
+ # Named by the field that failed: this used to answer a callback URL refusal on a request that carried no
+ # callback at all.
+ assert_problem(response, status=422, code="request.invalid", field="storage_scope")
start_mock.assert_not_awaited()
diff --git a/api/tests/unit/test_problem_document.py b/api/tests/unit/test_problem_document.py
index 1a492b04e..47af23637 100644
--- a/api/tests/unit/test_problem_document.py
+++ b/api/tests/unit/test_problem_document.py
@@ -1,83 +1,85 @@
-"""Unit tests for the problem document of an API-authored error.
+"""Unit tests for the rendering of a problem as the HTTP response that carries it.
-A `PipelexError` answers its own problem (`PipelexError.to_problem`), rendered by
-`pipelex_api.exception_handlers.problem_response` and pinned in `test_exception_handlers.py` and
-`test_problem_views.py`; this module covers only the document the API builds for its own 4xx and
-5xx, which no `PipelexError` stands behind.
+Every failure the runner answers is a problem built in the operator's view; `pipelex_api.problem_document` renders it as
+the response a reader receives. The handlers that build the problems are pinned in `test_exception_handlers.py` and
+`test_problem_views.py`; this module covers the rendering alone: the status, the view, the headers, and a body with no
+member written as `null`.
"""
-from pipelex.base_exceptions import ErrorDomain
+import json
-from pipelex_api.error_types import ErrorType
-from pipelex_api.problem_document import build_problem_document_from_api_error, with_request_context
+from mthds.protocol.problem.registry import CoreCode
+from pipelex.errors.problem import ProblemView, make_problem
+
+from pipelex_api.exceptions import RunnerAuthError, RunnerMisconfiguredError, RunnerRequestError
+from pipelex_api.problem_document import PROBLEM_JSON_MEDIA_TYPE, problem_json_response, problem_status
+
+
+def _body_of(response_body: bytes | memoryview) -> dict[str, object]:
+ body: dict[str, object] = json.loads(bytes(response_body))
+ return body
class TestProblemDocument:
- def test_api_error_variant_is_input_domain(self):
- doc = build_problem_document_from_api_error(
- ErrorType.VALIDATION_ERROR,
- "field 'pipe_code' is required",
- 422,
- instance="/v1/execute",
- request_id="REQ9",
- )
- assert doc == {
- "type": "https://docs.pipelex.com/latest/errors/validation-error/",
- "title": "Validation error",
- "status": 422,
- "detail": "field 'pipe_code' is required",
- "instance": "/v1/execute",
- "request_id": "REQ9",
- "error_type": "ValidationError",
- "error_domain": "input",
- # Every API-authored error is non-retryable: a caller mistake is not fixed by a blind
- # retry. Carried as a uniform contract member so clients drive retry logic without
- # branching on field presence.
- "retryable": False,
- }
-
- def test_api_error_variant_config_domain_for_server_fault(self):
- # An API-owned 5xx (a missing secret, an unconfigured backend) classifies
- # CONFIG, not INPUT — an operator, not the caller, fixes it.
- doc = build_problem_document_from_api_error(
- ErrorType.SERVER_MISCONFIGURED,
- "Server configuration error: API_KEY not configured",
- 500,
- instance="/v1/upload",
- request_id="REQ-CFG",
- error_domain=ErrorDomain.CONFIG,
+ def test_a_runner_refusal_answers_its_code_with_no_instance_and_no_null(self):
+ problem = RunnerRequestError("the field is refused", field="pipe_code").to_problem(view=ProblemView.OPERATOR, request_id="REQ9")
+
+ response = problem_json_response(problem, view=ProblemView.CALLER)
+
+ assert response.status_code == 422
+ assert response.media_type == PROBLEM_JSON_MEDIA_TYPE
+ body = _body_of(response.body)
+ assert body["code"] == "request.invalid"
+ assert body["status"] == 422
+ assert body["domain"] == "input"
+ assert body["retry"] == "no"
+ assert body["params"] == {"field": "pipe_code"}
+ assert body["location"] == {"field": "pipe_code"}
+ assert body["request_id"] == "REQ9"
+ assert body["type"] == "https://mthds.ai/errors/request.invalid"
+ assert "instance" not in body
+ assert "error_type" not in body
+ assert None not in body.values()
+
+ def test_the_caller_view_leaves_the_diagnostics_out_and_the_operator_view_keeps_them(self):
+ # The operator's message rides the diagnostics alone: the caller reads the code's sentence.
+ problem = RunnerMisconfiguredError("API_KEY is not set", component="API_KEY").to_problem(view=ProblemView.OPERATOR)
+
+ caller_body = _body_of(problem_json_response(problem, view=ProblemView.CALLER).body)
+ operator_body = _body_of(problem_json_response(problem, view=ProblemView.OPERATOR).body)
+
+ assert caller_body["code"] == "runtime.misconfigured"
+ assert caller_body["status"] == 500
+ assert "diagnostics" not in caller_body
+ assert "API_KEY is not set" not in json.dumps(caller_body)
+ diagnostics = operator_body["diagnostics"]
+ assert isinstance(diagnostics, dict)
+ assert diagnostics["error_class"] == "RunnerMisconfiguredError"
+ assert "API_KEY is not set" in json.dumps(operator_body)
+
+ def test_a_401_carries_the_challenge_its_raise_site_names_and_no_other(self):
+ """The challenge names the credential the deployment reads, which only the refusal knows: none behind a proxy."""
+ problem = RunnerAuthError("no credential").with_error_code(CoreCode.AUTH_MISSING_CREDENTIAL).to_problem(view=ProblemView.OPERATOR)
+
+ bare = problem_json_response(problem, view=ProblemView.CALLER)
+ challenged = problem_json_response(problem, view=ProblemView.CALLER, headers={"WWW-Authenticate": "Bearer"})
+
+ assert bare.status_code == 401
+ assert "WWW-Authenticate" not in bare.headers
+ assert challenged.headers["WWW-Authenticate"] == "Bearer"
+ assert _body_of(challenged.body)["code"] == "auth.missing_credential"
+
+ def test_further_headers_are_added_to_the_response(self):
+ problem = RunnerRequestError("method not allowed").with_error_code(CoreCode.REQUEST_METHOD_NOT_ALLOWED).to_problem(view=ProblemView.OPERATOR)
+
+ response = problem_json_response(problem, view=ProblemView.CALLER, headers={"Allow": "GET"})
+
+ assert response.status_code == 405
+ assert response.headers["Allow"] == "GET"
+ assert "Retry-After" not in response.headers
+
+ def test_the_status_is_the_one_the_code_declares(self):
+ assert problem_status(make_problem(code=CoreCode.REQUEST_TOO_LARGE, view=ProblemView.CALLER, params={"limit": 10, "size": 11})) == 413
+ assert (
+ problem_status(make_problem(code=CoreCode.RUNTIME_UNSUPPORTED, view=ProblemView.CALLER, params={"capability": "fire_and_forget"})) == 501
)
- assert doc["status"] == 500
- assert doc["title"] == "Server misconfigured"
- assert doc["error_type"] == "ServerMisconfigured"
- assert doc["error_domain"] == "config"
- # An API-owned 5xx is no more retryable than a 4xx — the operator, not
- # the caller, fixes a missing secret; a blind retry does nothing.
- assert doc["retryable"] is False
-
- def test_none_valued_fields_dropped(self):
- api_doc = build_problem_document_from_api_error(ErrorType.BAD_REQUEST, "bad request", 400, instance=None, request_id=None)
- assert None not in api_doc.values()
- assert "instance" not in api_doc
- assert "request_id" not in api_doc
- # `retryable` is a contract member, not a drop-on-None one — present
- # even when `instance`/`request_id` are absent.
- assert api_doc["retryable"] is False
-
- def test_request_context_is_stamped_on_a_copy(self):
- """The handler stamps the request's members on a copy, so the raised `ApiError` reads exactly as it was raised."""
- raised = build_problem_document_from_api_error(ErrorType.BAD_REQUEST, "bad request", 400, instance=None, request_id=None)
- before = dict(raised)
-
- stamped = with_request_context(raised, instance="/v1/start", request_id="REQ-STAMP")
-
- assert stamped == {**before, "instance": "/v1/start", "request_id": "REQ-STAMP"}
- assert raised == before
-
- def test_request_context_drops_none(self):
- raised = build_problem_document_from_api_error(ErrorType.BAD_REQUEST, "bad request", 400, instance=None, request_id=None)
-
- stamped = with_request_context(raised, instance=None, request_id=None)
-
- assert stamped == raised
- assert None not in stamped.values()
diff --git a/api/tests/unit/test_problem_views.py b/api/tests/unit/test_problem_views.py
index 28352ed06..ee06cc66f 100644
--- a/api/tests/unit/test_problem_views.py
+++ b/api/tests/unit/test_problem_views.py
@@ -32,6 +32,7 @@ from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.middleware import RequestIdMiddleware
from pipelex_api.problem_view import mark_operator_request
from pipelex_api.security import ForwardedIdentityHeader, no_auth, verify_api_key, verify_jwt
+from tests.unit._problems import assert_problem
from tests.unit.test_data import ProblemTestData, rate_limited_failure
_GATEWAY_CONFIG_MESSAGE = "the gateway config is missing"
@@ -230,11 +231,8 @@ class TestProblemViews:
response = client.get("/config-error", headers={"Authorization": "Bearer not-the-configured-key"})
- assert response.status_code == 401
- body = response.json()
- assert body["error_type"] == "InvalidToken"
+ body = assert_problem(response, status=401, code="auth.invalid_credential")
assert "diagnostics" not in body
- assert "code" not in body
@pytest.mark.parametrize("identity", list(_IDENTITIES))
def test_an_unknown_code_reaches_a_caller_without_the_operator_step(self, mocker: MockerFixture, identity: _Identity) -> None:
diff --git a/api/tests/unit/test_protocol_conformance.py b/api/tests/unit/test_protocol_conformance.py
index d7f4ce7af..eb59e1a31 100644
--- a/api/tests/unit/test_protocol_conformance.py
+++ b/api/tests/unit/test_protocol_conformance.py
@@ -172,7 +172,7 @@ class TestProtocolConformance:
callback_url = f"http://127.0.0.1:{server.server_port}/completion"
# --- relax both SSRF layers for the loopback receiver (test-only) --------
- mocker.patch("pipelex_api.schemas.models._is_disallowed_host", return_value=False)
+ mocker.patch("pipelex_api.schemas.models.is_disallowed_host", return_value=False)
mocker.patch("pipelex.pipe_run.delivery_executor.SsrfGuardedTransport", httpx.AsyncHTTPTransport)
# The signing secret is pinned HERE rather than relying on the ambient
diff --git a/api/tests/unit/test_protocol_parity.py b/api/tests/unit/test_protocol_parity.py
index 50f045e20..e2a87c09f 100644
--- a/api/tests/unit/test_protocol_parity.py
+++ b/api/tests/unit/test_protocol_parity.py
@@ -7,7 +7,8 @@ shared report keys are byte-identical and the wire extras (`mthds_contents`, `me
`default_pipe_ref`) appear on the HTTP envelope only. `is_valid` is a canonical report field on both backends (not a
wire extra — the `success` extra is retired). `graph_spec` is compared by presence/absence,
not value: it carries run-specific identity (graph id, node timings, random dry-run data),
-so two runs never serialize identically.
+so two runs never serialize identically. The wire writes no member it leaves unset, where the local report holds
+`None`, and it carries the report's `warnings` as problem items, the shape the invalid arm's `errors` have.
Two report fields are gated on the wire rather than dropped: `input_form` and `output_form` are
opt-in structured views the route attaches only when the request's `views` names them. So the parity
@@ -25,6 +26,7 @@ from fastapi import FastAPI
from fastapi.testclient import TestClient
from mthds.protocol.models import ModelCategory
from pipelex.pipeline.runner import PipelexMTHDSProtocol
+from pipelex.pipeline.validation_errors import warning_problem_items
from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.routes import router as api_router
@@ -62,8 +64,12 @@ class TestProtocolParity:
)
async def test_validate_parity(self, mthds_contents: list[str], allow_signatures: bool):
local_report = await PipelexMTHDSProtocol().validate(mthds_contents=mthds_contents, allow_signatures=allow_signatures)
- # Same serialization options as the route's JSONResponse path.
- local_dump = local_report.model_dump(mode="json", serialize_as_any=True, by_alias=True)
+ # Same serialization options as the route's JSONResponse path, which writes no unset member, and the warnings
+ # as the problem items the wire carries.
+ local_dump = {
+ key: value for key, value in local_report.model_dump(mode="json", serialize_as_any=True, by_alias=True).items() if value is not None
+ }
+ local_dump["warnings"] = [item.model_dump(mode="json", exclude_none=True) for item in warning_problem_items(warnings=local_report.warnings)]
client = _build_client()
# Opt into every gated view so the parity claim covers the whole canonical report: a view is
@@ -75,13 +81,16 @@ class TestProtocolParity:
assert response.status_code == 200, response.text
body = response.json()
- # The wire extras are HTTP-only — and they are the ONLY divergence in key sets.
+ # The wire extras are HTTP-only — and they are the ONLY divergence in key sets. `default_pipe_ref` is absent
+ # when the request has no default pipe, as every unset member is.
assert VALIDATE_WIRE_EXTRAS.isdisjoint(local_dump)
assert set(local_dump) >= VALIDATE_OPT_IN_VIEWS, "an opt-in view must be a canonical report field, not a wire-only invention"
- assert set(body) == set(local_dump) | VALIDATE_WIRE_EXTRAS
+ assert set(body) - VALIDATE_WIRE_EXTRAS == set(local_dump)
+ assert {"mthds_contents", "message"} <= set(body)
+ assert None not in body.values()
# graph_spec: presence parity (run-specific content — see module docstring).
- assert (body["graph_spec"] is None) == (local_dump["graph_spec"] is None)
+ assert ("graph_spec" in body) == ("graph_spec" in local_dump)
# Every other shared key is identical between the two backends.
for key in sorted(set(local_dump) - {"graph_spec"}):
diff --git a/api/tests/unit/test_read_scope_binding.py b/api/tests/unit/test_read_scope_binding.py
index cd283b583..4653bea51 100644
--- a/api/tests/unit/test_read_scope_binding.py
+++ b/api/tests/unit/test_read_scope_binding.py
@@ -1,9 +1,10 @@
"""A caller holding its own token reads only under its own id, on every route that takes a `read_scope`.
With `AUTH_MODE=jwt` the caller reaches the runner directly, so the read scope it sends is its own claim, not a trusted
-host's: a scope lying under another id is refused with a 403 `ReadScopeForbidden` before anything is read, whether the
-route resolves hash entries in that scope's blob store, hands it to a validator or runs under it. On the other modes
-the caller is the host or one tenant, so the same scope is taken as it is.
+host's: a scope lying under another id is refused with a 403 `auth.forbidden`, whose `requirement` is
+`read_scope_under_caller`, before anything is read, whether the route resolves hash entries in that scope's blob store,
+hands it to a validator or runs under it. On the other modes the caller is the host or one tenant, so the same scope is
+taken as it is.
"""
from collections.abc import Awaitable, Callable
@@ -21,6 +22,7 @@ from pipelex_api.routes import router as api_router
from pipelex_api.routes.blob_upload import router as blob_upload_router
from pipelex_api.security import AUTH_MODE_ENV_VAR, RequestUser
from tests.unit._constants import VALID_MTHDS
+from tests.unit._problems import assert_problem
_PIPELINE_NS = "pipelex_api.routes.pipelex.pipeline"
_CALLER_ID = "user_a"
@@ -81,11 +83,8 @@ class TestReadScopeBinding:
response = _post(client, route=route, read_scope=read_scope)
- assert response.status_code == 403, response.text
- assert response.headers["content-type"] == "application/problem+json"
- problem = response.json()
- assert problem["error_type"] == "ReadScopeForbidden", response.text
- assert repr(read_scope) in problem["detail"]
+ problem = assert_problem(response, status=403, code="auth.forbidden")
+ assert problem["params"] == {"requirement": "read_scope_under_caller"}, problem
@pytest.mark.parametrize("route", _ROUTES)
@pytest.mark.parametrize("read_scope", [_CALLER_ID, f"{_CALLER_ID}/org_x"])
diff --git a/api/tests/unit/test_read_scope_extras.py b/api/tests/unit/test_read_scope_extras.py
index 8e522d72d..5935fa624 100644
--- a/api/tests/unit/test_read_scope_extras.py
+++ b/api/tests/unit/test_read_scope_extras.py
@@ -29,6 +29,7 @@ from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.routes import router as api_router
from pipelex_api.security import RequestUser
from tests.unit._constants import VALID_MTHDS
+from tests.unit._problems import assert_problem
if TYPE_CHECKING:
from pipelex.system.job_metadata import RunMetadata
@@ -125,8 +126,7 @@ class TestReadScopeRefusals:
response = client.post(route, json=_run_body(read_scope=bad_scope))
- assert response.status_code == 422, response.text
- assert response.json()["error_type"] == "InvalidReadScope"
+ assert_problem(response, status=422, code="request.invalid", field="read_scope")
assert orchestrator.run_metadatas == []
def test_storage_scope_outside_the_read_scope_is_a_422(self, mocker: MockerFixture, route: str) -> None:
@@ -134,10 +134,7 @@ class TestReadScopeRefusals:
response = client.post(route, json=_run_body(storage_scope="org_other/mt_1/run_7", read_scope="org_acme"))
- assert response.status_code == 422, response.text
- body = response.json()
- assert body["error_type"] == "InvalidReadScope"
- assert "was sent" in body["detail"]
+ assert_problem(response, status=422, code="request.invalid", field="read_scope")
assert orchestrator.run_metadatas == []
def test_host_storage_scope_without_a_read_scope_fails_closed(self, mocker: MockerFixture, route: str) -> None:
@@ -147,10 +144,7 @@ class TestReadScopeRefusals:
response = client.post(route, json=_run_body(storage_scope="org_acme/mt_1/run_7"))
- assert response.status_code == 422, response.text
- body = response.json()
- assert body["error_type"] == "InvalidReadScope"
- assert "defaulted to the caller's id" in body["detail"]
+ assert_problem(response, status=422, code="request.invalid", field="read_scope")
assert orchestrator.run_metadatas == []
def test_local_storage_sentinel_beside_a_read_scope_is_a_422(self, mocker: MockerFixture, route: str) -> None:
@@ -158,6 +152,5 @@ class TestReadScopeRefusals:
response = client.post(route, json=_run_body(storage_scope=LOCAL_STORAGE_SCOPE, read_scope=LOCAL_STORAGE_SCOPE))
- assert response.status_code == 422, response.text
- assert response.json()["error_type"] == "InvalidReadScope"
+ assert_problem(response, status=422, code="request.invalid", field="read_scope")
assert orchestrator.run_metadatas == []
diff --git a/api/tests/unit/test_request_id_middleware.py b/api/tests/unit/test_request_id_middleware.py
index c92642c74..310194147 100644
--- a/api/tests/unit/test_request_id_middleware.py
+++ b/api/tests/unit/test_request_id_middleware.py
@@ -8,6 +8,7 @@ import pytest
from fastapi import APIRouter, FastAPI, HTTPException, Request
from fastapi.testclient import TestClient
from pipelex import log
+from pipelex.system.job_metadata import is_valid_request_id
from pipelex.tools.log.log_context import get_log_context
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.types import Message, Receive, Scope, Send
@@ -130,6 +131,16 @@ class TestRequestIdMiddleware:
assert returned != "bad id with spaces"
assert _ULID_RE.match(returned) is not None
+ @pytest.mark.parametrize("inbound", ["abc error.code=forged", 'abc"def', "abc;q=1", "req.123"])
+ def test_replaces_an_inbound_id_the_runtime_s_rule_refuses(self, inbound: str):
+ """The middleware applies the runtime's one rule, so every id it passes on is one a run accepts."""
+ response = _build_client().get("/probe", headers={REQUEST_ID_HEADER: inbound})
+ returned = response.headers[REQUEST_ID_HEADER]
+ assert returned != inbound
+ assert _ULID_RE.match(returned) is not None
+ assert not is_valid_request_id(value=inbound)
+ assert is_valid_request_id(value=returned)
+
def test_replaces_overlong_inbound_id(self):
overlong = "a" * 200
response = _build_client().get("/probe", headers={REQUEST_ID_HEADER: overlong})
diff --git a/api/tests/unit/test_request_refusals.py b/api/tests/unit/test_request_refusals.py
new file mode 100644
index 000000000..d8660d012
--- /dev/null
+++ b/api/tests/unit/test_request_refusals.py
@@ -0,0 +1,40 @@
+from typing import Any
+
+from pytest_mock import MockerFixture
+
+from pipelex_api import request_refusals
+from pipelex_api.request_refusals import MAX_REFUSED_FIELDS, refused_request_error
+
+# How many faults past the bound a refusal reports, as a list the caller sent can fail item by item.
+_EXTRA_FAULT_COUNT = 7
+
+
+def _item_faults(*, count: int) -> list[dict[str, Any]]:
+ """One fault per item of a list field, as FastAPI reports them, each located in the body."""
+ return [{"loc": ("body", "callback_urls", index_fault), "msg": "Value error, malformed", "type": "value_error"} for index_fault in range(count)]
+
+
+class TestRequestRefusals:
+ def test_the_message_names_as_many_faults_as_the_items_then_how_many_more(self):
+ # The items stop at `MAX_REFUSED_FIELDS`, and so does the operator's account, which says how many it left out
+ # rather than growing with whatever the caller sent.
+ faults = _item_faults(count=MAX_REFUSED_FIELDS + _EXTRA_FAULT_COUNT)
+ refusal = refused_request_error(faults=faults, located_by_request_part=True)
+ described = refusal.message.split("; ")
+ assert len(described) == MAX_REFUSED_FIELDS + 1
+ assert described[0] == "callback_urls.0: Value error, malformed"
+ assert described[MAX_REFUSED_FIELDS - 1] == f"callback_urls.{MAX_REFUSED_FIELDS - 1}: Value error, malformed"
+ assert described[-1] == f"and {_EXTRA_FAULT_COUNT} more"
+ items = refusal.problem_items()
+ assert items is not None
+ assert len(items) == MAX_REFUSED_FIELDS
+
+ def test_a_message_within_the_bound_names_every_fault(self):
+ refusal = refused_request_error(faults=_item_faults(count=2), located_by_request_part=True)
+ assert refusal.message == "callback_urls.0: Value error, malformed; callback_urls.1: Value error, malformed"
+
+ def test_each_fault_s_path_is_read_once(self, mocker: MockerFixture):
+ faults = _item_faults(count=3)
+ path_spy = mocker.spy(request_refusals, "_fault_field_path")
+ refused_request_error(faults=faults, located_by_request_part=True)
+ assert path_spy.call_count == len(faults)
diff --git a/api/tests/unit/test_resolve_route.py b/api/tests/unit/test_resolve_route.py
index a9f451fb2..b88e38115 100644
--- a/api/tests/unit/test_resolve_route.py
+++ b/api/tests/unit/test_resolve_route.py
@@ -4,8 +4,8 @@ Pins `conformance/specs/pipelex-codegen.md#route-envelopes`, in the `conformance
that verify it: the request takes the method's tree as the protocol's `files` map XOR a `method_ref`,
read exactly as `/v1/validate` and the run routes read it; a produced verdict is a 200 discriminated on
`is_valid` with the crate on the valid arm; request-shape errors are 422 problem+json; an address-form
-`method_ref` resolves the fetched package's tree, while the registry form keeps its honest 501 until the
-method registry exists.
+`method_ref` resolves the fetched package's tree, while the registry form is refused as a 422
+`request.unsupported` until the method registry exists.
"""
import base64
@@ -26,6 +26,7 @@ from pipelex_api.limits import MAX_METHOD_TREE_FILE_BYTES
from pipelex_api.routes import router as api_router
from pipelex_api.routes.blob_upload import router as blob_upload_router
from tests.unit._constants import INVALID_MAIN_PIPE_MTHDS, SIBLING_MTHDS, VALID_MTHDS
+from tests.unit._problems import assert_problem
RESOLVE_PATH = "/v1/resolve"
@@ -42,15 +43,6 @@ def _hash_entry(data: bytes) -> dict[str, Any]:
return {"sha256": sha256_hex(data), "size": len(data)}
-def _assert_problem(response: Any, *, status: int, error_type: str) -> dict[str, Any]:
- assert response.status_code == status, response.text
- assert response.headers["content-type"] == "application/problem+json"
- problem: dict[str, Any] = response.json()
- assert problem["error_type"] == error_type, response.text
- assert "is_valid" not in problem
- return problem
-
-
class TestResolveRoute:
def test_a_tree_resolves_to_the_crate_on_the_valid_arm(self):
client = _build_client()
@@ -95,10 +87,11 @@ class TestResolveRoute:
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is False
- assert body["validation_errors"], "an invalid verdict must carry a non-empty validation_errors[]"
- assert body["validation_errors"][0]["message"]
- # The bundle's tree path threads through to the diagnostics.
- assert body["validation_errors"][0]["source"] == "methods/broken.mthds"
+ assert body["errors"], "an invalid verdict must carry a non-empty errors[]"
+ assert body["errors"][0]["code"]
+ assert body["errors"][0]["detail"]
+ # The bundle's tree path threads through to the items' location.
+ assert body["errors"][0]["location"]["file"] == "methods/broken.mthds"
# No crate exists on the invalid arm; the runnability facts are /validate vocabulary, absent here.
assert "crate" not in body
assert "is_runnable" not in body
@@ -116,59 +109,65 @@ class TestResolveRoute:
assert "smoke.echo" in crate["pipes"]
assert crate["source_map"]["smoke.echo"] == "documents.mthds"
- def test_registry_form_method_ref_keeps_the_501(self):
+ def test_registry_form_method_ref_is_an_unsupported_request(self):
# The registry form (any non-address reference) stays reserved for the packaging
- # program's closing phase — an honest 501, never a silent empty verdict.
+ # program's closing phase — an honest refusal of the form, never a silent empty verdict.
client = _build_client()
response = client.post(RESOLVE_PATH, json={"method_ref": "acme/invoice-tools"})
- _assert_problem(response, status=501, error_type="MethodRefNotSupported")
+ problem = assert_problem(response, status=422, code="request.unsupported")
+ assert problem["params"] == {"field": "method_ref", "reason": "registry_form_method_ref"}
@pytest.mark.parametrize(
- "payload",
+ ("payload", "field"),
[
- pytest.param({}, id="neither"),
- pytest.param({"files": {"main.mthds": VALID_MTHDS}, "method_ref": "acme/x"}, id="both"),
- pytest.param({"method_ref": "acme/x", "dependencies": {}}, id="dependencies-without-files"),
+ pytest.param({}, "files", id="neither"),
+ pytest.param({"files": {"main.mthds": VALID_MTHDS}, "method_ref": "acme/x"}, "method_ref", id="both"),
+ pytest.param({"method_ref": "acme/x", "dependencies": {}}, "dependencies", id="dependencies-without-files"),
],
)
- def test_a_malformed_method_selector_is_a_request_shape_422(self, payload: dict[str, Any]):
- _assert_problem(_build_client().post(RESOLVE_PATH, json=payload), status=422, error_type="ValidationError")
+ def test_a_malformed_method_selector_is_a_request_shape_422(self, payload: dict[str, Any], field: str):
+ # The model's rule names the field to change, never the body as a whole: the first selector when none is sent,
+ # the second when both are, and the `dependencies` sent without the tree they belong to.
+ assert_problem(_build_client().post(RESOLVE_PATH, json=payload), status=422, code="request.invalid", field=field)
@pytest.mark.parametrize(
- ("files", "refusal_code"),
+ ("files", "code", "reason"),
[
- pytest.param([{"content": VALID_MTHDS, "source": "main.mthds"}], None, id="the-retired-list-shape"),
- pytest.param({}, "empty_tree", id="empty-map"),
- pytest.param({"../main.mthds": VALID_MTHDS}, "invalid_tree_path", id="path-leaving-the-tree"),
- pytest.param({".mthds/main.mthds": VALID_MTHDS}, "excluded_name", id="excluded-name"),
+ pytest.param([{"content": VALID_MTHDS, "source": "main.mthds"}], "request.invalid", None, id="the-retired-list-shape"),
+ pytest.param({}, "method.package_invalid", "empty_tree", id="empty-map"),
+ pytest.param({"../main.mthds": VALID_MTHDS}, "security.input_path_refused", None, id="path-leaving-the-tree"),
+ pytest.param({".mthds/main.mthds": VALID_MTHDS}, "method.package_invalid", "excluded_name", id="excluded-name"),
],
)
- def test_a_files_member_that_is_no_method_tree_is_refused_as_validate_refuses_it(self, files: Any, refusal_code: str | None):
+ def test_a_files_member_that_is_no_method_tree_is_refused_as_validate_refuses_it(self, files: Any, code: str, reason: str | None):
client = _build_client()
- problem = _assert_problem(client.post(RESOLVE_PATH, json={"files": files}), status=422, error_type="InvalidMethodFiles")
- validate_problem = _assert_problem(client.post("/v1/validate", json={"files": files}), status=422, error_type="InvalidMethodFiles")
- if refusal_code is not None:
- assert problem["tree_refusal"]["code"] == refusal_code
- assert problem.get("tree_refusal") == validate_problem.get("tree_refusal")
+ response = client.post(RESOLVE_PATH, json={"files": files})
+ validate_response = client.post("/v1/validate", json={"files": files})
+ problem = assert_problem(response, status=422, code=code)
+ validate_problem = assert_problem(validate_response, status=422, code=code)
+ if reason is not None:
+ assert problem["params"]["reason"] == reason, problem
+ assert problem.get("params") == validate_problem.get("params")
def test_a_hash_the_runner_does_not_hold_is_a_422_naming_it(self):
notes = b"notes the runner never received"
response = _build_client().post(RESOLVE_PATH, json={"files": {"main.mthds": VALID_MTHDS, "notes.txt": _hash_entry(notes)}})
- problem = _assert_problem(response, status=422, error_type="MissingBlobs")
- assert problem["missing_blobs"] == [sha256_hex(notes)]
+ problem = assert_problem(response, status=422, code="request.blobs_missing")
+ assert problem["params"] == {"missing_blobs": [sha256_hex(notes)]}
def test_a_file_past_the_tree_limit_is_refused(self):
response = _build_client().post(RESOLVE_PATH, json={"files": {"main.mthds": VALID_MTHDS, "big.txt": "a" * (MAX_METHOD_TREE_FILE_BYTES + 1)}})
- problem = _assert_problem(response, status=422, error_type="MethodTreeTooLarge")
- assert "'big.txt'" in problem["detail"]
+ problem = assert_problem(response, status=422, code="method.package_invalid")
+ assert problem["params"] == {"reason": "file_too_large", "path": "big.txt", "limit": MAX_METHOD_TREE_FILE_BYTES}
def test_python_in_a_tree_is_refused_where_it_could_not_run(self):
response = _build_client().post(RESOLVE_PATH, json={"files": {"main.mthds": VALID_MTHDS, "helpers/tool.py": "VALUE = 1\n"}})
- _assert_problem(response, status=403, error_type="CustomCodeRequiresSandbox")
+ assert_problem(response, status=501, code="pipelex.deployment.custom_code_requires_sandbox")
def test_a_tree_without_a_bundle_is_refused(self):
response = _build_client().post(RESOLVE_PATH, json={"files": {"notes.txt": "no bundle here"}})
- _assert_problem(response, status=422, error_type="InvalidBundle")
+ problem = assert_problem(response, status=422, code="method.package_invalid")
+ assert problem["params"] == {"reason": "no_bundle"}
def test_resolve_tears_down_its_library(self, mocker: MockerFixture):
# The engine core leaves the library loaded + current on success (so /codegen can read live
diff --git a/api/tests/unit/test_security_event_routes.py b/api/tests/unit/test_security_event_routes.py
index d4cf4771a..39c0d1717 100644
--- a/api/tests/unit/test_security_event_routes.py
+++ b/api/tests/unit/test_security_event_routes.py
@@ -34,6 +34,7 @@ from pipelex_api.api_config import ApiConfig
from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.middleware import REQUEST_ID_HEADER, RequestIdMiddleware
from pipelex_api.routes import router as api_router
+from tests.unit._problems import assert_problem
_PIPELINE_NS = "pipelex_api.routes.pipelex.pipeline"
_MODE = "temporal"
@@ -107,7 +108,6 @@ class _ServerRefusal(NamedTuple):
route: str
body: dict[str, Any]
- error_type: str
code: ErrorCode
event_error_type: str
target: str
@@ -217,9 +217,8 @@ class TestSecurityEventRoutes:
_ServerRefusal(
route="/v1/execute",
body={"inputs": {"photo": {"__class__": "subprocess.Popen", "args": ["id"]}}},
- error_type="ReservedObjectKey",
code=PipelexErrorCode.SECURITY_RESERVED_KEY,
- event_error_type="ReservedObjectKey",
+ event_error_type="ReservedObjectKeyError",
target="object_key",
target_class=None,
refused_content="__class__",
@@ -230,7 +229,6 @@ class TestSecurityEventRoutes:
_ServerRefusal(
route="/v1/start",
body={"callback_urls": ["http://169.254.169.254/latest/meta-data/"]},
- error_type="InvalidCallbackUrls",
code=CoreCode.SECURITY_INPUT_URL_REFUSED,
event_error_type="CallbackUrlRefusedError",
target="url",
@@ -243,7 +241,6 @@ class TestSecurityEventRoutes:
_ServerRefusal(
route="/v1/start",
body={"callback_urls": ["https://10.0.0.5/hooks/done"]},
- error_type="InvalidCallbackUrls",
code=CoreCode.SECURITY_INPUT_URL_REFUSED,
event_error_type="CallbackUrlRefusedError",
target="url",
@@ -256,7 +253,6 @@ class TestSecurityEventRoutes:
_ServerRefusal(
route="/v1/start",
body={"callback_urls": ["http://METADATA.google.internal./computeMetadata/v1/"]},
- error_type="InvalidCallbackUrls",
code=CoreCode.SECURITY_INPUT_URL_REFUSED,
event_error_type="CallbackUrlRefusedError",
target="url",
@@ -269,7 +265,6 @@ class TestSecurityEventRoutes:
_ServerRefusal(
route="/v1/start",
body={"callback_urls": ["file:///etc/passwd"]},
- error_type="InvalidCallbackUrls",
code=CoreCode.SECURITY_INPUT_URL_REFUSED,
event_error_type="CallbackUrlRefusedError",
target="url",
@@ -278,11 +273,34 @@ class TestSecurityEventRoutes:
),
id="callback_scheme",
),
+ pytest.param(
+ _ServerRefusal(
+ route="/v1/start",
+ body={"callback_urls": ["//169.254.169.254/latest/meta-data"]},
+ code=CoreCode.SECURITY_INPUT_URL_REFUSED,
+ event_error_type="CallbackUrlRefusedError",
+ target="url",
+ target_class="metadata",
+ refused_content="169.254.169.254",
+ ),
+ id="callback_scheme_relative_metadata_endpoint",
+ ),
+ pytest.param(
+ _ServerRefusal(
+ route="/v1/start",
+ body={"callback_urls": ["//127.0.0.1:8080/cb"]},
+ code=CoreCode.SECURITY_INPUT_URL_REFUSED,
+ event_error_type="CallbackUrlRefusedError",
+ target="url",
+ target_class="loopback",
+ refused_content="127.0.0.1",
+ ),
+ id="callback_scheme_relative_loopback",
+ ),
pytest.param(
_ServerRefusal(
route="/v1/execute",
body={"resources": {"../secrets/key.pem": base64.b64encode(b"x").decode("ascii")}},
- error_type="InvalidResourcePath",
code=CoreCode.SECURITY_INPUT_PATH_REFUSED,
event_error_type="BundleResourcePathError",
target="path",
@@ -295,9 +313,8 @@ class TestSecurityEventRoutes:
_ServerRefusal(
route="/v1/execute",
body={"mthds_contents": None, "files": {"main.mthds": _DESCRIBE_IMAGE_MTHDS, "../secrets/key.pem": "x"}},
- error_type="InvalidMethodFiles",
code=CoreCode.SECURITY_INPUT_PATH_REFUSED,
- event_error_type="MethodTreeRefusedError",
+ event_error_type="RequestMethodError",
target="path",
target_class=None,
refused_content="key.pem",
@@ -308,9 +325,8 @@ class TestSecurityEventRoutes:
_ServerRefusal(
route="/v1/execute",
body={"mthds_contents": None, "files": {"main.mthds": _DESCRIBE_IMAGE_MTHDS, "/etc/key.pem": "x"}},
- error_type="InvalidMethodFiles",
code=CoreCode.SECURITY_INPUT_PATH_REFUSED,
- event_error_type="MethodTreeRefusedError",
+ event_error_type="RequestMethodError",
target="path",
target_class=None,
refused_content="key.pem",
@@ -322,9 +338,8 @@ class TestSecurityEventRoutes:
_ServerRefusal(
route="/v1/execute",
body={"mthds_contents": None, "files": {"main.mthds": _DESCRIBE_IMAGE_MTHDS, path: "x"}},
- error_type="InvalidMethodFiles",
code=CoreCode.SECURITY_INPUT_PATH_REFUSED,
- event_error_type="MethodTreeRefusedError",
+ event_error_type="RequestMethodError",
target="path",
target_class=None,
refused_content=refused_content,
@@ -338,9 +353,8 @@ class TestSecurityEventRoutes:
_ServerRefusal(
route="/v1/execute",
body={"mthds_contents": None, "bundle_b64": _bundle_b64({"main.mthds": _DESCRIBE_IMAGE_MTHDS, path: "x"})},
- error_type="InvalidMethodFiles",
code=CoreCode.SECURITY_INPUT_PATH_REFUSED,
- event_error_type="MethodTreeRefusedError",
+ event_error_type="RequestMethodError",
target="path",
target_class=None,
refused_content=refused_content,
@@ -354,7 +368,6 @@ class TestSecurityEventRoutes:
_ServerRefusal(
route="/v1/execute",
body={"resources": {path: _b64("x")}},
- error_type="InvalidResourcePath",
code=CoreCode.SECURITY_INPUT_PATH_REFUSED,
event_error_type="BundleResourcePathError",
target="path",
@@ -376,8 +389,7 @@ class TestSecurityEventRoutes:
with _security_event_lines() as lines:
response = client.post(case.route, json=request_body, headers={REQUEST_ID_HEADER: _REQUEST_ID})
- assert response.status_code == 422, response.text
- assert response.json()["error_type"] == case.error_type
+ assert_problem(response, status=422, code=case.code)
(line,) = lines
assert line["message"] == SECURITY_EVENT_MESSAGE
assert line["event.name"] == SECURITY_EVENT_NAME
@@ -418,36 +430,99 @@ class TestSecurityEventRoutes:
assert "passwd" not in json.dumps(line)
@pytest.mark.parametrize(
- ("route", "body", "error_type"),
+ ("route", "body", "event_error_type"),
[
- pytest.param("/v1/start", {"callback_urls": [""]}, "InvalidCallbackUrls", id="empty_callback_url"),
- pytest.param("/v1/start", {"callback_urls": ["https://hooks.example.com/" + "a" * 5000]}, "InvalidCallbackUrls", id="long_callback_url"),
- pytest.param("/v1/start", {"callback_urls": ["hooks.example.com/done"]}, "InvalidCallbackUrls", id="callback_url_without_scheme"),
- pytest.param("/v1/start", {"callback_urls": ["http:///done"]}, "InvalidCallbackUrls", id="callback_url_without_host"),
+ pytest.param(
+ "/v1/validate",
+ {"mthds_contents": [_DESCRIBE_IMAGE_MTHDS], "resources": {"../private": "YQ=="}},
+ "BundleResourcePathError",
+ id="validate_resource",
+ ),
+ pytest.param(
+ "/v1/validate",
+ {"files": {"main.mthds": _DESCRIBE_IMAGE_MTHDS, "../secrets/key.pem": "x"}},
+ "RequestMethodError",
+ id="validate_tree",
+ ),
+ pytest.param(
+ "/v1/resolve", {"files": {"main.mthds": _DESCRIBE_IMAGE_MTHDS, "../secrets/key.pem": "x"}}, "RequestMethodError", id="resolve"
+ ),
+ pytest.param(
+ "/v1/codegen",
+ {"kind": "types", "target": "ts-zod", "files": {"main.mthds": _DESCRIBE_IMAGE_MTHDS, "../secrets/key.pem": "x"}},
+ "RequestMethodError",
+ id="codegen",
+ ),
+ pytest.param(
+ "/v1/pipe-io", {"files": {"main.mthds": _DESCRIBE_IMAGE_MTHDS, "../secrets/key.pem": "x"}}, "RequestMethodError", id="pipe_io"
+ ),
+ ],
+ )
+ def test_a_diagnostic_route_s_refusal_names_whose_request_it_was(
+ self, mocker: MockerFixture, route: str, body: dict[str, Any], event_error_type: str
+ ) -> None:
+ """A route that runs nothing still binds the labels its body names before refusing it, so its event carries them."""
+ client = _build_client(mocker)
+
+ with _security_event_lines() as lines:
+ response = client.post(route, json={**body, "analytics_groups": {"org_id": "org_abc"}}, headers={REQUEST_ID_HEADER: _REQUEST_ID})
+
+ assert_problem(response, status=422, code=CoreCode.SECURITY_INPUT_PATH_REFUSED)
+ (line,) = lines
+ assert line["error.type"] == event_error_type
+ assert line["run.extras.org_id"] == "org_abc"
+ assert line["request_id"] == _REQUEST_ID
+ assert "private" not in json.dumps(line)
+ assert "key.pem" not in json.dumps(line)
+
+ def test_labels_the_runtime_refuses_ride_no_event(self, mocker: MockerFixture) -> None:
+ """Only labels that pass the runtime's own rules are bound: a refused value never reaches a security event."""
+ client = _build_client(mocker)
+ body = {"mthds_contents": [_DESCRIBE_IMAGE_MTHDS], "resources": {"../private": "YQ=="}, "analytics_groups": {"org_id": "org abc\nforged"}}
+
+ with _security_event_lines() as lines:
+ response = client.post("/v1/validate", json=body)
+
+ # The labels are the request's own mistake, which its model refuses before the route reads any resource.
+ assert_problem(response, status=422, code="request.invalid", field="analytics_groups")
+ assert lines == []
+
+ @pytest.mark.parametrize(
+ ("route", "body", "code"),
+ [
+ pytest.param("/v1/start", {"callback_urls": [""]}, "request.invalid", id="empty_callback_url"),
+ pytest.param("/v1/start", {"callback_urls": ["https://hooks.example.com/" + "a" * 5000]}, "request.invalid", id="long_callback_url"),
+ pytest.param("/v1/start", {"callback_urls": ["hooks.example.com/done"]}, "request.invalid", id="callback_url_without_scheme"),
+ pytest.param("/v1/start", {"callback_urls": ["http:///done"]}, "request.invalid", id="callback_url_without_host"),
+ # A host and a port with no scheme open no authority, though `urlparse` takes the host for a scheme.
+ pytest.param("/v1/start", {"callback_urls": ["example.com:8080/hook"]}, "request.invalid", id="callback_host_and_port_without_scheme"),
+ pytest.param("/v1/start", {"callback_urls": ["localhost:3000/cb"]}, "request.invalid", id="callback_localhost_and_port_without_scheme"),
+ # A scheme-relative URL naming a host the SSRF rule allows still names no scheme.
+ pytest.param("/v1/start", {"callback_urls": ["//hooks.example.com/done"]}, "request.invalid", id="callback_scheme_relative_public_host"),
pytest.param(
"/v1/execute",
{"mthds_contents": None, "files": {"main.mthds": _DESCRIBE_IMAGE_MTHDS, "notes//a.txt": "x"}},
- "InvalidMethodFiles",
+ "method.package_invalid",
id="empty_segment_in_a_file_path",
),
pytest.param(
"/v1/execute",
{"mthds_contents": None, "files": {"main.mthds": _DESCRIBE_IMAGE_MTHDS, "notes\\a.txt": "x"}},
- "InvalidMethodFiles",
+ "method.package_invalid",
id="backslash_in_a_file_path",
),
pytest.param(
"/v1/execute",
{"mthds_contents": None, "files": {"main.mthds": _DESCRIBE_IMAGE_MTHDS, "notes:v2.txt": "x"}},
- "InvalidMethodFiles",
+ "method.package_invalid",
id="colon_in_a_file_path",
),
- pytest.param("/v1/execute", {"resources": {"notes\\a.txt": _b64("x")}}, "InvalidResourcePath", id="backslash_in_a_resource_path"),
- pytest.param("/v1/execute", {"resources": {"notes:v2.txt": _b64("x")}}, "InvalidResourcePath", id="colon_in_a_resource_path"),
- pytest.param("/v1/execute", {"resources": {"": _b64("x")}}, "InvalidResourcePath", id="empty_resource_path"),
+ pytest.param("/v1/execute", {"resources": {"notes\\a.txt": _b64("x")}}, "request.invalid", id="backslash_in_a_resource_path"),
+ pytest.param("/v1/execute", {"resources": {"notes:v2.txt": _b64("x")}}, "request.invalid", id="colon_in_a_resource_path"),
+ pytest.param("/v1/execute", {"resources": {"": _b64("x")}}, "request.invalid", id="empty_resource_path"),
],
)
- def test_a_refusal_of_the_request_shape_logs_no_event(self, mocker: MockerFixture, route: str, body: dict[str, Any], error_type: str) -> None:
+ def test_a_refusal_of_the_request_shape_logs_no_event(self, mocker: MockerFixture, route: str, body: dict[str, Any], code: str) -> None:
"""A malformed field is the caller's mistake, not an attempt to reach what a security rule forbids."""
client = _build_client(mocker)
request_body = {key: value for key, value in {**_run_body(), **body}.items() if value is not None}
@@ -455,6 +530,5 @@ class TestSecurityEventRoutes:
with _security_event_lines() as lines:
response = client.post(route, json=request_body, headers={REQUEST_ID_HEADER: _REQUEST_ID})
- assert response.status_code == 422, response.text
- assert response.json()["error_type"] == error_type
+ assert_problem(response, status=422, code=code)
assert lines == []
diff --git a/api/tests/unit/test_security_log_levels.py b/api/tests/unit/test_security_log_levels.py
index b37e67bbb..54b6ad66f 100644
--- a/api/tests/unit/test_security_log_levels.py
+++ b/api/tests/unit/test_security_log_levels.py
@@ -134,7 +134,8 @@ class TestSecurityLogLevels:
with caplog.at_level(logging.DEBUG, logger=SECURITY_LOGGER):
response = client.get(RoutePath.WHOAMI, headers={"Authorization": f"Bearer {token}"})
- assert response.status_code == 401
+ assert response.status_code == 500
+ assert response.json()["code"] == "pipelex.deployment.token_claims_invalid"
(record,) = _security_records(caplog)
assert record.levelno == logging.WARNING
assert "user_action" in carried_attributes(record=record)
diff --git a/api/tests/unit/test_security_no_auth.py b/api/tests/unit/test_security_no_auth.py
index 1dcd3a1b5..e24ee4b86 100644
--- a/api/tests/unit/test_security_no_auth.py
+++ b/api/tests/unit/test_security_no_auth.py
@@ -12,6 +12,7 @@ from pytest_mock import MockerFixture
from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.security import ForwardedIdentityHeader, RequestUser, get_request_user, no_auth
from tests.unit._constants import RoutePath
+from tests.unit._problems import assert_problem
USER_ID = "11111111-1111-4111-1111-111111111111"
@@ -81,8 +82,9 @@ class TestNoAuthForwardedHeaders:
client = _build_client()
headers: dict[str, str] = {} if user_id is None else {ForwardedIdentityHeader.USER_ID: user_id}
response = client.get(RoutePath.WHOAMI, headers=headers)
- assert response.status_code == 401
- assert response.headers["content-type"] == "application/problem+json"
+ assert_problem(response, status=401, code="auth.missing_credential")
+ # This deployment reads no bearer token, so its 401 asks for none.
+ assert "WWW-Authenticate" not in response.headers
def test_the_reserved_single_tenant_id_is_not_special_on_the_wire(self, mocker: MockerFixture):
"""`single-tenant` forwarded by a proxy is an ordinary path-safe id here.
@@ -119,7 +121,8 @@ class TestNoAuthForwardedHeaders:
`user_id` is the owner segment of every storage key, so a value
containing `/`, `\`, control chars, or being `.`/`..` could enable
traversal. The proxy intended to authenticate someone but forwarded a
- malformed value — we reject the request (400) rather than silently
+ malformed value — we refuse the request (422 `request.invalid` naming the
+ header, which no credential of the caller's could fix) rather than silently
downgrade to a shared owner and scope the caller's outputs into someone
else's namespace.
"""
@@ -128,9 +131,8 @@ class TestNoAuthForwardedHeaders:
headers: dict[str, str] = {ForwardedIdentityHeader.USER_ID: unsafe_user_id}
with caplog.at_level(logging.WARNING):
response = client.get(RoutePath.WHOAMI, headers=headers)
- assert response.status_code == 400
- assert response.headers["content-type"] == "application/problem+json"
- assert response.json()["error_type"] == "BadRequest"
+ assert_problem(response, status=422, code="request.invalid", field=ForwardedIdentityHeader.USER_ID)
+ assert "WWW-Authenticate" not in response.headers
# The refused header names no caller, so it is never logged as `user.id`, nor logged at all: anyone reaching
# the server could otherwise have any text recorded as a user.
(record,) = [
diff --git a/api/tests/unit/test_security_verifiers.py b/api/tests/unit/test_security_verifiers.py
index 9c8678e05..7be957e21 100644
--- a/api/tests/unit/test_security_verifiers.py
+++ b/api/tests/unit/test_security_verifiers.py
@@ -15,6 +15,7 @@ from pytest_mock import MockerFixture
from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.security import RequestUser, get_request_user, verify_api_key, verify_jwt
from tests.unit._constants import RoutePath
+from tests.unit._problems import assert_problem
JWT_SECRET = "test-jwt-secret-do-not-use-in-prod"
API_KEY = "test-api-key-static"
@@ -73,9 +74,10 @@ class TestSecurityVerifiers:
client = _build_jwt_client()
token = jwt.encode({"sub": "google#abc"}, JWT_SECRET, algorithm="HS256")
response = client.get(RoutePath.WHOAMI, headers={"Authorization": f"Bearer {token}"})
- assert response.status_code == 401
- assert response.headers["content-type"] == "application/problem+json"
- assert response.json()["error_type"] == "InvalidToken"
+ body = assert_problem(response, status=500, code="pipelex.deployment.token_claims_invalid")
+ # The issuer, not the bearer, fixes a claim: the operator's to know, so the claim and the reason ride the diagnostics.
+ assert "WWW-Authenticate" not in response.headers
+ assert "diagnostics" not in body
def test_jwt_missing_user_id_claim_rejected(self, mocker: MockerFixture):
"""No `user_id` claim means no caller identifier — reject."""
@@ -83,10 +85,10 @@ class TestSecurityVerifiers:
client = _build_jwt_client()
token = jwt.encode({"iat": 0}, JWT_SECRET, algorithm="HS256")
response = client.get(RoutePath.WHOAMI, headers={"Authorization": f"Bearer {token}"})
- assert response.status_code == 401
- assert response.headers["content-type"] == "application/problem+json"
- assert response.headers["WWW-Authenticate"] == "Bearer"
- assert response.json()["error_type"] == "InvalidToken"
+ body = assert_problem(response, status=500, code="pipelex.deployment.token_claims_invalid")
+ # The issuer, not the bearer, fixes a claim: the operator's to know, so the claim and the reason ride the diagnostics.
+ assert "WWW-Authenticate" not in response.headers
+ assert "diagnostics" not in body
@pytest.mark.parametrize(
"unsafe_user_id",
@@ -114,10 +116,10 @@ class TestSecurityVerifiers:
client = _build_jwt_client()
token = jwt.encode({"user_id": unsafe_user_id}, JWT_SECRET, algorithm="HS256")
response = client.get(RoutePath.WHOAMI, headers={"Authorization": f"Bearer {token}"})
- assert response.status_code == 401
- assert response.headers["content-type"] == "application/problem+json"
- assert response.headers["WWW-Authenticate"] == "Bearer"
- assert response.json()["error_type"] == "InvalidToken"
+ body = assert_problem(response, status=500, code="pipelex.deployment.token_claims_invalid")
+ # The issuer, not the bearer, fixes a claim: the operator's to know, so the claim and the reason ride the diagnostics.
+ assert "WWW-Authenticate" not in response.headers
+ assert "diagnostics" not in body
@pytest.mark.parametrize(
("refused_claim", "expected_claim_type"),
@@ -143,7 +145,7 @@ class TestSecurityVerifiers:
with caplog.at_level(logging.WARNING):
response = client.get(RoutePath.WHOAMI, headers={"Authorization": f"Bearer {token}"})
- assert response.status_code == 401
+ assert response.status_code == 500
(record,) = [record for record in caplog.records if record.getMessage() == "A verified token's user id claim is not a path-safe segment"]
carried = carried_attributes(record=record)
assert carried.get("claim_type") == expected_claim_type
@@ -183,38 +185,32 @@ class TestSecurityVerifiers:
client = _build_jwt_client()
token = jwt.encode({"user_id": SINGLE_TENANT_USER_ID}, JWT_SECRET, algorithm="HS256")
response = client.get(RoutePath.WHOAMI, headers={"Authorization": f"Bearer {token}"})
- assert response.status_code == 401
- assert response.headers["content-type"] == "application/problem+json"
- assert response.headers["WWW-Authenticate"] == "Bearer"
- assert response.json()["error_type"] == "InvalidToken"
+ body = assert_problem(response, status=500, code="pipelex.deployment.token_claims_invalid")
+ # The issuer, not the bearer, fixes a claim: the operator's to know, so the claim and the reason ride the diagnostics.
+ assert "WWW-Authenticate" not in response.headers
+ assert "diagnostics" not in body
def test_jwt_invalid_token_rejected(self, mocker: MockerFixture):
mocker.patch("pipelex_api.security.get_optional_env", return_value=JWT_SECRET)
client = _build_jwt_client()
response = client.get(RoutePath.WHOAMI, headers={"Authorization": "Bearer not.a.real.token"})
- assert response.status_code == 401
- assert response.headers["content-type"] == "application/problem+json"
+ assert_problem(response, status=401, code="auth.invalid_credential")
assert response.headers["WWW-Authenticate"] == "Bearer"
- assert response.json()["error_type"] == "InvalidToken"
def test_jwt_wrong_secret_rejected(self, mocker: MockerFixture):
mocker.patch("pipelex_api.security.get_optional_env", return_value=JWT_SECRET)
client = _build_jwt_client()
token = jwt.encode({"user_id": USER_ID_UUID}, "different-secret", algorithm="HS256")
response = client.get(RoutePath.WHOAMI, headers={"Authorization": f"Bearer {token}"})
- assert response.status_code == 401
- assert response.headers["content-type"] == "application/problem+json"
+ assert_problem(response, status=401, code="auth.invalid_credential")
assert response.headers["WWW-Authenticate"] == "Bearer"
- assert response.json()["error_type"] == "InvalidToken"
def test_jwt_missing_secret_returns_500(self, mocker: MockerFixture):
mocker.patch("pipelex_api.security.get_optional_env", return_value=None)
client = _build_jwt_client()
token = jwt.encode({"user_id": USER_ID_UUID}, "anything", algorithm="HS256")
response = client.get(RoutePath.WHOAMI, headers={"Authorization": f"Bearer {token}"})
- assert response.status_code == 500
- assert response.headers["content-type"] == "application/problem+json"
- assert response.json()["error_type"] == "ServerMisconfigured"
+ assert_problem(response, status=500, code="runtime.misconfigured")
def test_api_key_happy_path(self, mocker: MockerFixture):
mocker.patch("pipelex_api.security.get_optional_env", return_value=API_KEY)
@@ -227,18 +223,14 @@ class TestSecurityVerifiers:
mocker.patch("pipelex_api.security.get_optional_env", return_value=API_KEY)
client = _build_api_key_client()
response = client.get(RoutePath.PING, headers={"Authorization": "Bearer wrong-key"})
- assert response.status_code == 401
- assert response.headers["content-type"] == "application/problem+json"
+ assert_problem(response, status=401, code="auth.invalid_credential")
assert response.headers["WWW-Authenticate"] == "Bearer"
- assert response.json()["error_type"] == "InvalidToken"
def test_api_key_missing_env_returns_500(self, mocker: MockerFixture):
mocker.patch("pipelex_api.security.get_optional_env", return_value=None)
client = _build_api_key_client()
response = client.get(RoutePath.PING, headers={"Authorization": "Bearer anything"})
- assert response.status_code == 500
- assert response.headers["content-type"] == "application/problem+json"
- assert response.json()["error_type"] == "ServerMisconfigured"
+ assert_problem(response, status=500, code="runtime.misconfigured")
@pytest.mark.parametrize(
"authorization",
@@ -255,17 +247,15 @@ class TestSecurityVerifiers:
`HTTPBearer(auto_error=False)` means none of these branches go through
FastAPI's default `HTTPException` handler (which would emit
`application/json` `{"detail": "Not authenticated"}`). Instead
- `verify_api_key` sees `credentials is None` and calls
- `raise_unauthenticated(...)` — same problem document as every other 401.
+ `verify_api_key` sees `credentials is None` and raises the runner's own
+ `auth.missing_credential` refusal — the problem document every 401 is.
"""
mocker.patch("pipelex_api.security.get_optional_env", return_value=API_KEY)
client = _build_api_key_client()
headers: dict[str, str] = {} if authorization is None else {"Authorization": authorization}
response = client.get(RoutePath.PING, headers=headers)
- assert response.status_code == 401
- assert response.headers["content-type"] == "application/problem+json"
+ assert_problem(response, status=401, code="auth.missing_credential")
assert response.headers["WWW-Authenticate"] == "Bearer"
- assert response.json()["error_type"] == "Unauthenticated"
@pytest.mark.parametrize(
"authorization",
@@ -282,7 +272,5 @@ class TestSecurityVerifiers:
client = _build_jwt_client()
headers: dict[str, str] = {} if authorization is None else {"Authorization": authorization}
response = client.get(RoutePath.WHOAMI, headers=headers)
- assert response.status_code == 401
- assert response.headers["content-type"] == "application/problem+json"
+ assert_problem(response, status=401, code="auth.missing_credential")
assert response.headers["WWW-Authenticate"] == "Bearer"
- assert response.json()["error_type"] == "Unauthenticated"
diff --git a/api/tests/unit/test_simple_routes.py b/api/tests/unit/test_simple_routes.py
index 54a073997..0fe633ca1 100644
--- a/api/tests/unit/test_simple_routes.py
+++ b/api/tests/unit/test_simple_routes.py
@@ -10,9 +10,11 @@ from pytest_mock import MockerFixture
from starlette.middleware.base import BaseHTTPMiddleware
from pipelex_api.exception_handlers import register_exception_handlers
+from pipelex_api.limits import MAX_REQUEST_BODY_BYTES
from pipelex_api.middleware import request_body_size_middleware
from pipelex_api.routes.health import router as health_router
from pipelex_api.routes.version import router as version_router
+from tests.unit._problems import assert_problem
def _build_client_with_body_cap() -> TestClient:
@@ -46,14 +48,11 @@ class TestSimpleRoutes:
mocker.patch("pipelex_api.routes.version.version", side_effect=PackageNotFoundError("pipelex"))
client = _build_client_with_body_cap()
response = client.get("/v1/version")
- assert response.status_code == 500
- assert response.headers["content-type"] == "application/problem+json"
- assert response.json()["error_type"] == "PackageNotFound"
+ assert_problem(response, status=500, code="runtime.misconfigured")
def test_request_body_size_rejects_oversized_via_content_length(self):
client = _build_client_with_body_cap()
# 200 MiB declared > 100 MiB default cap.
response = client.get("/health", headers={"content-length": str(200 * 1024 * 1024)})
- assert response.status_code == 413
- assert response.headers["content-type"] == "application/problem+json"
- assert response.json()["error_type"] == "PayloadTooLarge"
+ problem = assert_problem(response, status=413, code="request.too_large")
+ assert problem["params"] == {"limit": MAX_REQUEST_BODY_BYTES, "size": 200 * 1024 * 1024}
diff --git a/api/tests/unit/test_start_dispatch.py b/api/tests/unit/test_start_dispatch.py
index 72e5394cb..cb666ab3c 100644
--- a/api/tests/unit/test_start_dispatch.py
+++ b/api/tests/unit/test_start_dispatch.py
@@ -5,7 +5,7 @@ Fire-and-forget vs blocking is the ENDPOINT's delivery axis, never configured: `
checks the resolved `orchestration_mode`'s orchestrator BEFORE any library load: an async-capable
orchestrator (`supports_fire_and_forget=True`, e.g. `temporal`) acks `202` with its `workflow_id`,
while a blocking-only orchestrator (`supports_fire_and_forget=False`, e.g. the in-process `direct`
-base) is refused HONESTLY with a `400` (`StartRequiresAsyncOrchestration`) instead of silently
+base) is refused HONESTLY with a `501` (`runtime.unsupported`, naming the capability) instead of silently
running blocking and acking. This pins both arms end-to-end on `POST /start`, with a stub orchestrator
registered under the resolved mode (the boot slot is never used).
"""
@@ -19,9 +19,10 @@ from pipelex.runtime_bridge.payloads import PipelexPipeDispatchAck, PipelexPipeR
from pytest_mock import MockerFixture
from pipelex_api.api_config import ApiConfig
-from pipelex_api.exception_handlers import register_exception_handlers
+from pipelex_api.exception_handlers import ERROR_FRAMES_FIELD, register_exception_handlers
from pipelex_api.routes import router as api_router
from tests.unit._constants import VALID_MTHDS
+from tests.unit._problems import assert_problem
_PIPELINE_NS = "pipelex_api.routes.pipelex.pipeline"
@@ -101,22 +102,28 @@ class TestStartCapabilityGate:
assert fingerprint
assert body["crate_fingerprint"] == fingerprint
- def test_start_honestly_400s_when_orchestrator_is_blocking_only(self, mocker: MockerFixture) -> None:
+ def test_start_honestly_501s_when_orchestrator_is_blocking_only(self, mocker: MockerFixture) -> None:
# The orchestrator-agnostic base (`direct`) is blocking-only: /start refuses honestly with a
- # 400 BEFORE any dispatch (the capability check runs before pipeline_run_setup), so the stub's
+ # 501 BEFORE any dispatch (the capability check runs before pipeline_run_setup), so the stub's
# `execute` is never awaited — no silent block-and-ack.
_force_config(mocker, mode="direct")
# workflow_id is a placeholder: the blocking-only backend is refused before `start` is ever
# reached, so this value is never observed.
stub = _RecordingStub(workflow_id="wf-unused", supports_fire_and_forget=False)
_register_stub(mocker, mode="direct", stub=stub)
+ log_spy = mocker.patch("pipelex_api.exception_handlers.log")
response = _build_client().post(
"/v1/start",
json={"pipe_code": "echo", "mthds_contents": [VALID_MTHDS], "inputs": {"text": "hello"}},
)
- assert response.status_code == 400, response.text
- assert response.headers["content-type"].startswith("application/problem+json")
- assert response.json()["error_type"] == "StartRequiresAsyncOrchestration"
+ problem = assert_problem(response, status=501, code="runtime.unsupported")
+ assert problem["params"] == {"capability": "asynchronous execution"}
assert stub.calls == []
+ # Any caller can ask this deployment again and again for what it does not offer: the refusal is recorded as a
+ # warning without frames, never as an error filling the alerts.
+ log_spy.error.assert_not_called()
+ fields = log_spy.warning.call_args.kwargs["fields"]
+ assert fields["error.code"] == "runtime.unsupported"
+ assert ERROR_FRAMES_FIELD not in fields
diff --git a/api/tests/unit/test_tools_routes.py b/api/tests/unit/test_tools_routes.py
index 684d389d1..b8329b3db 100644
--- a/api/tests/unit/test_tools_routes.py
+++ b/api/tests/unit/test_tools_routes.py
@@ -7,6 +7,7 @@ from pipelex_api.openapi_schema import PipelexFastAPI
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
+from tests.unit._problems import assert_problem
SCHEMA_INVALID_MTHDS = """\
domain = "broken"
@@ -61,11 +62,7 @@ class TestLintRoute:
def test_oversized_content_returns_rfc7807_422(self):
response = _build_client().post("/v1/lint", json={"content": "a" * (MAX_MTHDS_FILE_BYTES + 1)})
- assert response.status_code == 422, response.text
- assert response.headers["content-type"] == PROBLEM_JSON_MEDIA_TYPE
- body = response.json()
- assert body["error_type"] == "ValidationError"
- assert "MTHDS file exceeds" in body["detail"]
+ assert_problem(response, status=422, code="request.invalid", field="content")
class TestFormatRoute:
@@ -98,11 +95,7 @@ class TestFormatRoute:
def test_malformed_options_return_rfc7807_422(self):
response = _build_client().post("/v1/format", json={"content": "a = 1\n", "options": {"column_width": "wide"}})
- assert response.status_code == 422, response.text
- assert response.headers["content-type"] == PROBLEM_JSON_MEDIA_TYPE
- body = response.json()
- assert body["error_type"] == "ValidationError"
- assert "column_width" in body["detail"]
+ assert_problem(response, status=422, code="request.invalid", field="options")
class TestToolsRouteSchema:
diff --git a/api/tests/unit/test_unresolved_package_reference.py b/api/tests/unit/test_unresolved_package_reference.py
index 5a3d12534..512d3621b 100644
--- a/api/tests/unit/test_unresolved_package_reference.py
+++ b/api/tests/unit/test_unresolved_package_reference.py
@@ -14,7 +14,6 @@ import pytest
from fastapi import Depends, FastAPI
from fastapi.testclient import TestClient
from mthds.protocol.problem.registry import CoreCode
-from pipelex.base_exceptions import ValidationErrorCategory
from pipelex.errors.problem import ProblemView
from pipelex.pipe_run.delivery_assignment import DeliveryAssignment
from pipelex.pipe_run.pipe_job import PipeJob
@@ -26,7 +25,7 @@ from pipelex_api.api_config import ApiConfig
from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.problem_view import mark_operator_request
from pipelex_api.routes import router as api_router
-from tests.unit._constants import UNRESOLVED_PACKAGE_MTHDS, UNRESOLVED_PACKAGE_REFERENCE, VENDORED_PROBE_ADDRESS
+from tests.unit._constants import UNRESOLVED_PACKAGE_MTHDS, VENDORED_PROBE_ADDRESS
_PIPELINE_NS = "pipelex_api.routes.pipelex.pipeline"
@@ -70,15 +69,12 @@ def _build_client(mocker: MockerFixture, *, tmp_path: Path, view: ProblemView, o
def _assert_the_package_item(items: list[dict[str, Any]]) -> None:
- assert len(items) == 1, items
- item = items[0]
- assert item["category"] == ValidationErrorCategory.PIPE_VALIDATION
- assert item["error_type"] == "unresolved_package_dependency"
- assert item["pipe_code"] == "echo"
- assert item["domain_code"] == "smoke"
- assert item["missing_pipe_code"] == UNRESOLVED_PACKAGE_REFERENCE
- assert item["field_path"] == "pipe.echo.steps[0].pipe"
- assert "github.com/invented/probe-lib/probe" in item["message"]
+ """The one item of a method calling a package it cannot reach: located on the step, naming the package and why."""
+ (item,) = items
+ assert item["code"] == CoreCode.METHOD_DEPENDENCY_MISSING
+ assert item["location"] == {"pipe": "echo", "field": "pipe.echo.steps[0].pipe"}
+ # The caller reads which package the method calls and why it is not there, from the code's parameters.
+ assert item.get("params") == {"kind": "package", "name": VENDORED_PROBE_ADDRESS, "reason": "not_found"}
class TestUnresolvedPackageReference:
@@ -91,7 +87,7 @@ class TestUnresolvedPackageReference:
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is False
- _assert_the_package_item(body["validation_errors"])
+ _assert_the_package_item(body["errors"])
@pytest.mark.parametrize("view", [ProblemView.OPERATOR, ProblemView.CALLER])
@pytest.mark.parametrize("path", ["/v1/execute", "/v1/start"])
@@ -106,11 +102,7 @@ class TestUnresolvedPackageReference:
body = response.json()
assert body["code"] == CoreCode.METHOD_INVALID
assert body["domain"] == "method"
- (item,) = body["errors"]
- assert item["code"] == CoreCode.METHOD_DEPENDENCY_MISSING
- assert item["location"] == {"pipe": "echo", "field": "pipe.echo.steps[0].pipe"}
- # The caller reads which package the method calls and why it is not there, from the code's parameters.
- assert item.get("params") == {"kind": "package", "name": VENDORED_PROBE_ADDRESS, "reason": "not_found"}
+ _assert_the_package_item(body["errors"])
match view:
case ProblemView.OPERATOR:
assert body["diagnostics"]["error_class"] == "ValidateBundleError"
diff --git a/api/tests/unit/test_validate_and_models_routes.py b/api/tests/unit/test_validate_and_models_routes.py
index 7dd9fd304..d1352624c 100644
--- a/api/tests/unit/test_validate_and_models_routes.py
+++ b/api/tests/unit/test_validate_and_models_routes.py
@@ -13,6 +13,7 @@ from pytest_mock import MockerFixture
from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.routes import router as api_router
from tests.unit._constants import VALID_MTHDS
+from tests.unit._problems import assert_problem
def _build_client() -> TestClient:
@@ -30,9 +31,7 @@ class TestValidateAndModelsRoutes:
"/v1/validate",
json={"mthds_contents": [oversized]},
)
- assert response.status_code == 422
- assert response.headers["content-type"] == "application/problem+json"
- assert response.json()["error_type"] == "ValidationError"
+ assert_problem(response, status=422, code="request.invalid", field="mthds_contents")
def test_validate_rejects_too_many_files(self):
client = _build_client()
@@ -40,9 +39,7 @@ class TestValidateAndModelsRoutes:
"/v1/validate",
json={"mthds_contents": [VALID_MTHDS] * 32},
)
- assert response.status_code == 422
- assert response.headers["content-type"] == "application/problem+json"
- assert response.json()["error_type"] == "ValidationError"
+ assert_problem(response, status=422, code="request.invalid", field="mthds_contents")
def test_validate_invalid_mthds_returns_200_invalid_report(self):
# `/validate` is a diagnostic endpoint: an invalid bundle is a produced verdict, so it rides
@@ -63,17 +60,13 @@ class TestValidateAndModelsRoutes:
# The verdict's message is the sentence its code renders, `method.invalid`'s; the interpreter's
# actual complaint rides the item, so the client still reads what is wrong and where.
assert body["message"] == error_code_spec(CoreCode.METHOD_INVALID).detail
- assert "TOML syntax error" in body["validation_errors"][0]["message"]
- # The diagnostics list is non-empty on every invalid arm — the structured-info invariant is
- # total. A raw TOML-syntax error is a parse-level failure the interpreter raises with no
- # categorized error-data, but the shared builder's last-resort residual still emits one
- # `blueprint_validation` item carrying the message (no `source` at this layer). A categorized
- # failure (e.g. an invalid `main_pipe`) yields richer items; that path is pinned in
- # test_validate_errors.py.
- assert isinstance(body["validation_errors"], list)
- assert body["validation_errors"], "an invalid verdict must carry a non-empty validation_errors[]"
- assert body["validation_errors"][0]["category"] == "blueprint_validation"
- assert body["validation_errors"][0]["message"]
+ # The item list is non-empty on every invalid arm — the structured-info invariant is total. A raw
+ # TOML-syntax error is the method's syntax finding, located where the parser stopped; a categorized
+ # failure (e.g. an invalid `main_pipe`) yields its own codes, pinned in test_validate_errors.py.
+ (item,) = body["errors"]
+ assert item["code"] == "method.syntax"
+ assert item["location"]["line"] == 1
+ assert item["params"]["finding"].startswith("TOML syntax error")
# The valid arm's structural artifacts + the retired `success` extra are absent.
assert "bundle_blueprint" not in body
assert "success" not in body
@@ -89,21 +82,16 @@ class TestValidateAndModelsRoutes:
# the unfiltered deck.
client = _build_client()
response = client.get(f"/v1/models?type={bad_type}")
- assert response.status_code == 422
- assert response.headers["content-type"] == "application/problem+json"
- assert response.json()["error_type"] == "InvalidModelCategory"
+ assert_problem(response, status=422, code="request.invalid", field="type")
def test_models_rejects_repeated_type_param(self):
# D11: the protocol's `type` filter is a single plain value. The old route accepted
# repeated `?type=` values (list[str] Query) — that extension is dropped, and FastAPI
# would otherwise silently keep one of the values, so the rejection is explicit.
- # Generic ValidationError (not InvalidModelCategory): both values are valid
- # categories — what's wrong is the arity.
+ # Both values are valid categories — what's wrong is the arity, still a refusal of the field.
client = _build_client()
response = client.get("/v1/models?type=llm&type=extract")
- assert response.status_code == 422
- assert response.headers["content-type"] == "application/problem+json"
- assert response.json()["error_type"] == "ValidationError"
+ assert_problem(response, status=422, code="request.invalid", field="type")
def test_models_returns_protocol_deck(self):
# The deck is the protocol `ModelDeck` shape produced by `PipelexMTHDSProtocol.models`:
@@ -144,9 +132,7 @@ class TestValidateAndModelsRoutes:
# crate routes take `files[]`, whose empty-selector rejection is pinned in the pipe-io suite).
client = _build_client()
response = client.post("/v1/validate", json={"mthds_contents": []})
- assert response.status_code == 422
- assert response.headers["content-type"] == "application/problem+json"
- assert response.json()["error_type"] == "ValidationError"
+ assert_problem(response, status=422, code="request.invalid", field="mthds_contents")
def test_validate_tears_down_validate_bundle_library_without_leaking(self, mocker: MockerFixture):
# validate_bundle opens a library and leaves it loaded + current on success (the D6 contract);
diff --git a/api/tests/unit/test_validate_caller_identity.py b/api/tests/unit/test_validate_caller_identity.py
index da1fc8bf8..165f505e7 100644
--- a/api/tests/unit/test_validate_caller_identity.py
+++ b/api/tests/unit/test_validate_caller_identity.py
@@ -34,6 +34,7 @@ from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.routes import router as api_router
from pipelex_api.security import RequestUser
from tests.unit._constants import STUB_METHOD_ADDRESS, VALID_MTHDS
+from tests.unit._problems import assert_problem, problem_items_fields
_PIPELINE_NS = "pipelex_api.routes.pipelex.pipeline"
_DIRECT_VALIDATOR_NS = "pipelex.pipeline.direct_bundle_validator"
@@ -169,16 +170,14 @@ class TestValidationCallerIdentity:
response = client.post("/v1/validate", json={"mthds_contents": [VALID_MTHDS], "analytics_groups": bad_groups})
- assert response.status_code == 422, response.text
- assert response.headers["content-type"] == "application/problem+json"
- body = response.json()
- assert body["error_type"] == "InvalidAnalyticsGroups"
- assert "analytics_groups" in body["detail"]
+ body = assert_problem(response, status=422, code="request.invalid")
+ # The refused field, or a key inside it, which the path names from the field down.
+ assert [field.split(".")[0] for field in problem_items_fields(body)] == ["analytics_groups"]
assert validator.caller_identities == []
- def test_validate_failing_on_two_fields_gets_the_generic_error_type(self, mocker: MockerFixture) -> None:
+ def test_validate_failing_on_two_fields_names_both(self, mocker: MockerFixture) -> None:
# Naming one field would send the caller to fix that one and leave the other for the next
- # request, so the classification falls back to the generic type and the detail names both.
+ # request, so the refusal carries one item per refused field.
validator = _register_recording_validator(mocker)
client = _build_client(user_id=_USER_ID)
@@ -187,9 +186,6 @@ class TestValidationCallerIdentity:
json={"mthds_contents": [VALID_MTHDS], "allow_signatures": "not-a-bool", "analytics_groups": {"Organization": "org_acme"}},
)
- assert response.status_code == 422, response.text
- body = response.json()
- assert body["error_type"] == "ValidationError"
- assert "analytics_groups" in body["detail"]
- assert "allow_signatures" in body["detail"]
+ body = assert_problem(response, status=422, code="request.invalid")
+ assert sorted(field.split(".")[0] for field in problem_items_fields(body)) == ["allow_signatures", "analytics_groups"]
assert validator.caller_identities == []
diff --git a/api/tests/unit/test_validate_default_pipe_ref.py b/api/tests/unit/test_validate_default_pipe_ref.py
index f8ae4b066..36de76094 100644
--- a/api/tests/unit/test_validate_default_pipe_ref.py
+++ b/api/tests/unit/test_validate_default_pipe_ref.py
@@ -49,18 +49,18 @@ class TestValidateDefaultPipeRef:
# `bundle_blueprint.main_pipe` leaves the caller to reconstruct the domain.
assert body["default_pipe_ref"] == "smoke.echo"
- def test_a_closure_declaring_no_main_pipe_reports_null(self):
+ def test_a_closure_declaring_no_main_pipe_reports_none(self):
client = _build_client()
response = client.post("/v1/validate", json={"mthds_contents": [NO_MAIN_PIPE_MTHDS]})
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is True
- assert body["default_pipe_ref"] is None
+ assert "default_pipe_ref" not in body
- def test_several_declared_main_pipes_report_the_run_default_not_null(self):
+ def test_several_declared_main_pipes_report_the_run_default(self):
# The field states the RUN default (`select_primary_blueprint`: first blueprint declaring
# `main_pipe`), NOT `/pipe-io`'s stricter rule that 422s on several. `/execute` and
- # `/start` run this closure happily, so reporting null would make a consumer refuse to
+ # `/start` run this closure happily, so reporting none would make a consumer refuse to
# prepare a method the server would run.
client = _build_client()
response = client.post("/v1/validate", json={"mthds_contents": [VALID_MTHDS, SECOND_MAIN_PIPE_MTHDS]})
@@ -106,7 +106,7 @@ class TestValidateDefaultPipeRef:
assert response.status_code == 200, response.text
assert response.json()["default_pipe_ref"] == "smoke.echo"
- def test_a_manifest_without_main_pipe_reports_null(self, install_method_package: Callable[..., Path]):
+ def test_a_manifest_without_main_pipe_reports_none(self, install_method_package: Callable[..., Path]):
# The protocol's entry rule: a method whose manifest declares no `main_pipe` has no pipe to start at, whatever
# its bundles declare, so a selector-less run is refused and the field says nothing.
install_method_package(files={"documents.mthds": VALID_MTHDS}, manifest_toml=STUB_METHOD_MANIFEST_NO_MAIN_PIPE)
@@ -115,9 +115,9 @@ class TestValidateDefaultPipeRef:
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is True
- assert body["default_pipe_ref"] is None
+ assert "default_pipe_ref" not in body
- def test_a_manifest_naming_a_pipe_the_closure_lacks_reports_null(self, install_method_package: Callable[..., Path]):
+ def test_a_manifest_naming_a_pipe_the_closure_lacks_reports_none(self, install_method_package: Callable[..., Path]):
# The manifest names `shout`; the package's closure holds only `smoke.echo`. A selector-less
# run would pass `shout` and fail to resolve it, so the field must not fall back to the
# closure's `echo` — that names a pipe no run of this address executes.
@@ -127,7 +127,7 @@ class TestValidateDefaultPipeRef:
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is True
- assert body["default_pipe_ref"] is None
+ assert "default_pipe_ref" not in body
def test_a_manifest_bare_code_two_domains_declare_resolves_in_the_domain_exporting_it(self, install_method_package: Callable[..., Path]):
# The manifest names `echo`, declared by both `smoke` and `twin`, and exports it from `smoke` alone: the domain
diff --git a/api/tests/unit/test_validate_dispatch.py b/api/tests/unit/test_validate_dispatch.py
index fcc82d6e8..135d2abb8 100644
--- a/api/tests/unit/test_validate_dispatch.py
+++ b/api/tests/unit/test_validate_dispatch.py
@@ -23,6 +23,7 @@ from pipelex.errors.bundle_validation_failure import BundleValidationFailure
from pipelex.errors.error_codes import error_code_spec
from pipelex.errors.problem import ProblemDiagnostics, ProblemView, make_problem
from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
+from pipelex.pipeline.validation_errors import problem_item_of
from pipelex.plugins.bundle_validator_registry import BundleValidatorRegistry
from pipelex.runtime_bridge.exceptions import MissingBundleValidatorError
from pipelex.system.caller_identity import CallerIdentity
@@ -33,6 +34,7 @@ from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.routes import router as api_router
from pipelex_api.routes.pipelex.pipeline import ApiRunner
from tests.unit._constants import VALID_MTHDS
+from tests.unit._problems import assert_problem
_PIPELINE_NS = "pipelex_api.routes.pipelex.pipeline"
@@ -101,9 +103,14 @@ def _register_stub_for_temporal(mocker: MockerFixture, stub: _StubBundleValidato
class TestValidateDispatch:
def test_non_direct_validators_invalid_verdict_maps_to_200_invalid_report(self, mocker: MockerFixture) -> None:
"""A non-direct validator's returned failure with items is mapped to a 200 InvalidReport, threading the request."""
+ bad_ref = ValidationErrorItem(category=ValidationErrorCategory.BLUEPRINT_VALIDATION, message="bad ref")
invalid_verdict = BundleValidationFailure(
- problem=make_problem(code=CoreCode.METHOD_INVALID, view=ProblemView.OPERATOR),
- validation_errors=[ValidationErrorItem(category=ValidationErrorCategory.BLUEPRINT_VALIDATION, message="bad ref")],
+ problem=make_problem(
+ code=CoreCode.METHOD_INVALID,
+ view=ProblemView.OPERATOR,
+ errors=[problem_item_of(item=bad_ref, code=CoreCode.METHOD_SCHEMA_VIOLATION)],
+ ),
+ validation_errors=[bad_ref],
)
stub = _StubBundleValidator(verdict=invalid_verdict)
_register_stub_for_temporal(mocker, stub)
@@ -114,7 +121,10 @@ class TestValidateDispatch:
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is False
- assert body["validation_errors"] == [{"category": ValidationErrorCategory.BLUEPRINT_VALIDATION, "message": "bad ref"}]
+ # The verdict's items, as the validator built them, each with its code, its sentence and its parameters.
+ assert body["errors"] == [
+ {"code": "method.schema_violation", "detail": error_code_spec(CoreCode.METHOD_SCHEMA_VIOLATION).title, "params": {"finding": "bad ref"}}
+ ]
assert body["message"] == error_code_spec(CoreCode.METHOD_INVALID).detail
# The dispatch reached the registered non-direct validator, with the request threaded through.
assert len(stub.calls) == 1
@@ -184,7 +194,7 @@ class TestValidateDispatch:
assert exc_info.value.resolve_error_code() == PipelexErrorCode.PLUGIN_NOT_FOUND
def test_forbidden_orchestration_mode_override_is_a_403(self) -> None:
- """The route threads orchestration_mode into the same override policy /start uses: a forbidden override is a 403."""
+ """The route threads orchestration_mode into the same override policy /start uses: a forbidden override is a 422."""
client = _build_client()
# Packaged default is `direct` with override OFF; forcing a different backend is refused before dispatch.
response = client.post(
@@ -192,6 +202,5 @@ class TestValidateDispatch:
json={"mthds_contents": [VALID_MTHDS], "orchestration_mode": "temporal"},
)
- assert response.status_code == 403, response.text
- assert response.headers["content-type"].startswith("application/problem+json")
- assert response.json()["error_type"] == "OrchestrationModeOverrideForbidden"
+ problem = assert_problem(response, status=422, code="pipelex.deployment.orchestration_override_forbidden")
+ assert problem["params"] == {"requested_mode": "temporal"}
diff --git a/api/tests/unit/test_validate_envelope.py b/api/tests/unit/test_validate_envelope.py
index 2565675b7..475742853 100644
--- a/api/tests/unit/test_validate_envelope.py
+++ b/api/tests/unit/test_validate_envelope.py
@@ -10,7 +10,7 @@ DIRECT in-process on the orchestrator-agnostic base (F2): the real in-process va
orchestrator-backend selection.
Includes the D2 regression pin: a bundle that declares no `main_pipe` validates with 200 and
-`graph_spec=null` — the former 422 precondition is deleted.
+no `graph_spec` — the former 422 precondition is deleted.
"""
from fastapi import FastAPI
@@ -82,7 +82,7 @@ class TestValidateEnvelope:
response = client.post("/v1/validate", json={"mthds_contents": [NO_MAIN_PIPE_MTHDS]})
assert response.status_code == 200, response.text
body = response.json()
- assert body["graph_spec"] is None
+ assert "graph_spec" not in body
assert body["bundle_blueprint"]["domain"] == "nomain"
assert body["pipe_io_contracts"]["nomain.echo"]["output"]["multiplicity"] == "single"
assert body["validated_pipes"] == [{"pipe_ref": "nomain.echo", "status": DryRunStatus.SUCCESS}]
diff --git a/api/tests/unit/test_validate_errors.py b/api/tests/unit/test_validate_errors.py
index 54d61f74b..b1378ca44 100644
--- a/api/tests/unit/test_validate_errors.py
+++ b/api/tests/unit/test_validate_errors.py
@@ -2,8 +2,9 @@
`/validate` is a **diagnostic endpoint**: a produced verdict — valid or invalid — always rides a
**200**, discriminated in the body on `is_valid`. An invalid bundle answers a 200 `InvalidReport`
-carrying a structured `validation_errors[]` list (the per-error diagnostics the VS Code extension
-maps to per-line problems), built by pipelex's one shared builder; the structural artifacts
+carrying `errors[]`, one problem item per finding (the per-error diagnostics the VS Code extension
+maps to per-line problems), each with its registry code, the parameters its sentence is rendered
+from, and its location, built by pipelex's one shared builder; the structural artifacts
(`bundle_blueprint`, `pipe_io_contracts`, `graph_spec`, `validated_pipes`) are absent on the invalid
arm. Non-2xx is reserved for *no-verdict* conditions: a malformed body or an
`mthds_sources`/`mthds_contents` length mismatch is a request-shape **422**; a server fault that
@@ -11,7 +12,7 @@ is not a produced verdict (a host-wiring `PipelexError` / `PipelexUnexpectedErro
When the caller sends `mthds_sources` parallel to `mthds_contents`, each name is threaded onto
`blueprint.source`, so pipe/concept and blueprint errors name the owning file on BOTH the invalid
-arm (`validation_errors[].source`) and the valid arm (`bundle_blueprint.source`).
+arm (`errors[].location.file`) and the valid arm (`bundle_blueprint.source`).
Asserts the in-process wire response via `TestClient`; the conformance HTTP arm asserts the same
200-diagnostic contract on the REAL wire (the spec's `<!-- unverified -->` markers point there).
@@ -22,7 +23,7 @@ from typing import Any
from fastapi import FastAPI
from fastapi.testclient import TestClient
from mthds.protocol.problem.registry import CoreCode
-from pipelex.base_exceptions import PipelexConfigError, ValidationErrorCategory
+from pipelex.base_exceptions import PipelexConfigError
from pipelex.core.exceptions import (
DryRunFailureErrorData,
PipeFactoryErrorData,
@@ -39,6 +40,7 @@ from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.routes import router as api_router
from pipelex_api.routes.pipelex.pipeline import ApiRunner
from tests.unit._constants import INVALID_MAIN_PIPE_MTHDS, UNKNOWN_MODEL_MTHDS, VALID_MTHDS
+from tests.unit._problems import assert_problem
# Structural artifacts that exist only on the valid arm — the invalid arm must NOT carry them.
_STRUCTURAL_FIELDS = ("bundle_blueprint", "pipe_io_contracts", "graph_spec", "validated_pipes")
@@ -119,10 +121,12 @@ class TestValidateErrors:
assert field not in body, f"invalid arm leaked structural field {field!r}: {body}"
# The retired wire extra is gone — the verdict is `is_valid`, never `success`.
assert "success" not in body
- items: list[dict[str, Any]] = body["validation_errors"]
+ items: list[dict[str, Any]] = body["errors"]
assert isinstance(items, list)
assert items, body
- assert all(item["category"] in set(ValidationErrorCategory) and "message" in item for item in items)
+ assert all(item["code"] and item["detail"] for item in items)
+ # An item writes no member as null.
+ assert all(None not in item.values() for item in items)
def test_validation_errors_carry_threaded_source(self):
client = _build_client()
@@ -134,12 +138,12 @@ class TestValidateErrors:
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is False
- items: list[dict[str, Any]] = body["validation_errors"]
+ items: list[dict[str, Any]] = body["errors"]
# Pins that the dict-seeded blueprint-validation item carries the threaded name (not some
# coincidental other item): a regression that stopped seeding `source` would fail here.
- sourced = [item for item in items if item.get("source") == "broken.mthds"]
- assert sourced, f"no validation_errors item carried the threaded source: {items}"
- assert any(item["category"] == ValidationErrorCategory.BLUEPRINT_VALIDATION for item in sourced)
+ sourced = [item for item in items if item.get("location", {}).get("file") == "broken.mthds"]
+ assert sourced, f"no errors item carried the threaded source: {items}"
+ assert any(item["code"] == "method.identifier_invalid" for item in sourced)
def test_toml_syntax_errors_carry_threaded_source(self):
client = _build_client()
@@ -154,11 +158,13 @@ class TestValidateErrors:
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is False
- items: list[dict[str, Any]] = body["validation_errors"]
- sourced = [item for item in items if item.get("source") == "broken.mthds"]
- assert sourced, f"no validation_errors item carried the threaded source: {items}"
- assert any(item["category"] == ValidationErrorCategory.BLUEPRINT_VALIDATION for item in sourced)
- assert any("TOML syntax error" in item["message"] for item in sourced)
+ items: list[dict[str, Any]] = body["errors"]
+ sourced = [item for item in items if item.get("location", {}).get("file") == "broken.mthds"]
+ assert sourced, f"no errors item carried the threaded source: {items}"
+ (item,) = sourced
+ assert item["code"] == "method.syntax"
+ assert item["location"] == {"file": "broken.mthds", "line": 1, "column": 19}
+ assert item["params"]["finding"].startswith("TOML syntax error")
def test_unknown_model_is_a_located_item_of_the_invalid_verdict(self):
# A model the deck does not define is refused while the pipe is built. That refusal is an
@@ -173,21 +179,18 @@ class TestValidateErrors:
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is False
- items: list[dict[str, Any]] = body["validation_errors"]
+ items: list[dict[str, Any]] = body["errors"]
assert len(items) == 1, items
item = items[0]
- assert item["category"] == ValidationErrorCategory.PIPE_VALIDATION
- assert item["error_type"] == "unknown_model"
- assert item["pipe_code"] == "echo"
- assert item["source"] == "echo.mthds"
- assert item["field_path"] == "pipe.echo.model"
- assert item["model_reference"] == "no-such-model-in-any-deck"
- assert item["model_type"] == "llm"
+ assert item["code"] == "model.unknown"
+ assert item["params"] == {"model": "no-such-model-in-any-deck", "model_type": "llm"}
+ assert item["location"] == {"pipe": "echo", "field": "model", "file": "echo.mthds"}
+ assert item["detail"] == "The method names the llm model 'no-such-model-in-any-deck', which no catalog knows."
def test_all_categories_project_onto_invalid_report(self, mocker: MockerFixture):
- # Every structured category lands on the 200 InvalidReport, and collectively the items cover
- # the full ValidationErrorItem field set (so a dropped field would fail here, not silently
- # vanish at the verdict->wire boundary). The runner returns the invalid verdict as a value
+ # Every structured category lands on the 200 InvalidReport as a problem item under its own code, and
+ # collectively the items carry every member of a problem item and every locator (so a dropped one would fail
+ # here, not silently vanish at the verdict->wire boundary). The runner returns the invalid verdict as a value
# (a BundleValidationFailure) — here the one a validator builds from the ValidateBundleError.
mocker.patch.object(ApiRunner, "validate_verdict", new=mocker.AsyncMock(return_value=_failure_of(_multi_category_error())))
client = _build_client()
@@ -197,31 +200,18 @@ class TestValidateErrors:
body = response.json()
assert body["is_valid"] is False
assert body["is_runnable"] is False
- items: list[dict[str, Any]] = body["validation_errors"]
- categories = {item["category"] for item in items}
- assert categories == {
- ValidationErrorCategory.BLUEPRINT_VALIDATION,
- ValidationErrorCategory.PIPE_FACTORY,
- ValidationErrorCategory.PIPE_VALIDATION,
- }
- # The union of populated fields across the items covers every ValidationErrorItem field.
- populated = {key for item in items for key, value in item.items() if value is not None}
- assert populated.issuperset(
- {
- "category",
- "message",
- "error_type",
- "pipe_code",
- "concept_code",
- "domain_code",
- "source",
- "field_path",
- "field_name",
- "variable_names",
- "missing_concept_code",
- "declared_concepts",
- }
- ), f"missing fields: {populated}"
+ items: list[dict[str, Any]] = body["errors"]
+ assert [item["code"] for item in items] == [
+ "method.input_undeclared",
+ "method.concept_unresolved",
+ "method.output_concept_mismatch",
+ ]
+ # The union of members across the items covers every member of a problem item and every locator.
+ assert {key for item in items for key in item} == {"code", "detail", "params", "location"}
+ assert {key for item in items for key in item.get("location", {})} == {"pipe", "field", "file"}
+ undeclared, unresolved, _ = items
+ assert undeclared["params"] == {"pipe": "summarize", "variables": ["contract"]}
+ assert unresolved["params"] == {"concept": "Summari"}
def test_dry_run_failures_become_one_located_item_per_failing_pipe(self, mocker: MockerFixture):
# A failing dry run is one `dry_run` item per failing pipe, located at the innermost pipe
@@ -249,18 +239,15 @@ class TestValidateErrors:
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is False
- items: list[dict[str, Any]] = body["validation_errors"]
+ items: list[dict[str, Any]] = body["errors"]
assert len(items) == 2, items
- assert all(item["category"] == ValidationErrorCategory.DRY_RUN for item in items)
- assert all(item["error_type"] == "DryRunError" for item in items)
+ # Each item carries the code the dry-run failure was raised under.
+ assert all(item["code"] == CoreCode.METHOD_WIRING_INVALID for item in items)
located_item, unlocated_item = items
- assert located_item["pipe_code"] == "summarize"
- assert located_item["domain_code"] == "legal"
- assert located_item["source"] == "pipe.mthds"
- assert located_item["message"] == "Pipe 'summarize' failed: boom."
- assert unlocated_item["message"] == "Dry run failed: unlocated."
- for locator in ("pipe_code", "domain_code", "source"):
- assert locator not in unlocated_item, unlocated_item
+ assert located_item["location"] == {"pipe": "summarize", "file": "pipe.mthds"}
+ assert located_item["params"]["finding"] == "Pipe 'summarize' failed: boom."
+ assert unlocated_item["params"] == {"finding": "Dry run failed: unlocated."}
+ assert "location" not in unlocated_item, unlocated_item
def test_non_verdict_failure_is_not_a_200_verdict(self, mocker: MockerFixture):
# The runner returns a produced verdict (valid report | BundleValidationFailure) as a value; only
@@ -288,7 +275,7 @@ class TestValidateErrors:
body = response.json()
assert body["is_valid"] is True
# Valid arm threads the same name, so a client can correlate the report's primary blueprint to
- # its file exactly as it would a failure's `validation_errors[].source`.
+ # its file exactly as it would a failure's `errors[].location.file`.
assert body["bundle_blueprint"]["source"] == "api://smoke.mthds"
def test_length_mismatch_is_a_request_error(self):
@@ -299,8 +286,6 @@ class TestValidateErrors:
)
# Caught at request validation as a 422 — never reaches the runtime (which would 500 on the
- # mismatch). The validator message rides the problem `detail`. This is a no-verdict
- # request-shape condition, NOT a content verdict.
- assert response.status_code == 422, response.text
- assert response.headers["content-type"].startswith("application/problem+json")
- assert "mthds_sources" in response.text
+ # mismatch). The model's own rule names the field to correct, and its message rides the operator's
+ # diagnostics alone. This is a no-verdict request-shape condition, NOT a content verdict.
+ assert_problem(response, status=422, code="request.invalid", field="mthds_sources")
diff --git a/api/tests/unit/test_validate_graph_target.py b/api/tests/unit/test_validate_graph_target.py
index ac83e1350..3f4e89e48 100644
--- a/api/tests/unit/test_validate_graph_target.py
+++ b/api/tests/unit/test_validate_graph_target.py
@@ -132,8 +132,8 @@ class TestValidateGraphTarget:
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is True
- assert body["default_pipe_ref"] is None
- assert body["graph_spec"] is None
+ assert "default_pipe_ref" not in body
+ assert "graph_spec" not in body
def test_a_manifest_naming_a_pipe_the_closure_lacks_gets_no_graph(self, install_method_package: Callable[..., Path]) -> None:
# The manifest names `shout`; the closure holds only `smoke.echo`. No run by this address
@@ -147,8 +147,8 @@ class TestValidateGraphTarget:
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is True
- assert body["default_pipe_ref"] is None
- assert body["graph_spec"] is None
+ assert "default_pipe_ref" not in body
+ assert "graph_spec" not in body
def test_inline_contents_graph_the_closures_declaration(self) -> None:
client = _build_client()
diff --git a/api/tests/unit/test_validate_render.py b/api/tests/unit/test_validate_render.py
index 41886defd..a8bf9f686 100644
--- a/api/tests/unit/test_validate_render.py
+++ b/api/tests/unit/test_validate_render.py
@@ -4,17 +4,74 @@ The neutral 200 verdict body is unchanged by default; when the request's `render
supported `markdown` token, the response gains a `rendered_markdown` field on BOTH 200 arms (valid
and invalid). An unknown/unsupported token is silently ignored (lenient-ignore, NOT a 422) because
`render` is a presentation hint, not part of the verdict contract. The markdown is rendered
-server-side by the shared pipelex renderers (`format_validate_markdown` / `render_invalid_validation_markdown`),
-so the API and the local CLI cannot drift in format/structure.
+server-side by the shared pipelex renderers (`format_validate_markdown` / `render_invalid_verdict_markdown`), the
+invalid arm's from the very items its `errors` holds, in the same view, so the Markdown never says what that view leaves
+out of them.
"""
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+
from fastapi import FastAPI
from fastapi.testclient import TestClient
+from mthds.protocol.problem.models import ProblemItem
+from mthds.protocol.problem.registry import CoreCode
+from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
+from pipelex.errors.bundle_validation_failure import BundleValidationFailure
+from pipelex.errors.problem import ProblemView, make_problem, make_problem_item
+from pipelex.plugins.bundle_validator_registry import BundleValidatorRegistry
+from pipelex.system.caller_identity import CallerIdentity
+from pytest_mock import MockerFixture
+from pipelex_api.api_config import ApiConfig
from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.routes import router as api_router
from tests.unit._constants import INVALID_MAIN_PIPE_MTHDS, VALID_MTHDS
+_PIPELINE_NS = "pipelex_api.routes.pipelex.pipeline"
+_MODE = "temporal"
+
+# The wording a validation item carries for the operator's tools, which no view of the verdict's items holds.
+_OPERATOR_WORDING = "operator-wording-5c1e: the step failed reading /srv/pipelex/cache/index.db"
+
+# A parameter its code declares operator-only, which an item read back from elsewhere may still carry.
+_OPERATOR_ONLY_COMPONENT = "operator-only-component-9b2d"
+
+
+class _InvalidVerdictValidator:
+ """Answers an invalid verdict whose validation item speaks in the operator's words, and whose problem items do not."""
+
+ async def validate_bundles(
+ self,
+ *,
+ mthds_contents: list[str] | None, # noqa: ARG002
+ mthds_sources: list[str] | None, # noqa: ARG002
+ allow_signatures: bool, # noqa: ARG002
+ library_dirs: Sequence[Path] | None, # noqa: ARG002
+ caller_identity: CallerIdentity | None, # noqa: ARG002
+ graph_pipe_code: str | None, # noqa: ARG002
+ submitted_files: Mapping[str, bytes] | None, # noqa: ARG002
+ method_dir: Path | None, # noqa: ARG002
+ methods_dirs: Sequence[Path] | None, # noqa: ARG002
+ read_scope: str | None, # noqa: ARG002
+ ) -> BundleValidationFailure:
+ located_item = make_problem_item(code=CoreCode.METHOD_SCHEMA_VIOLATION)
+ # Built by hand, as a stored record read back may be, with a parameter only the operator reads.
+ read_back_item = ProblemItem.model_validate(
+ {
+ "code": CoreCode.RUNTIME_MISCONFIGURED,
+ "detail": "The runtime is misconfigured, so it cannot serve this request.",
+ "params": {"component": _OPERATOR_ONLY_COMPONENT},
+ }
+ )
+ return BundleValidationFailure(
+ problem=make_problem(code=CoreCode.METHOD_INVALID, view=ProblemView.OPERATOR, errors=[located_item, read_back_item]),
+ validation_errors=[
+ ValidationErrorItem(category=ValidationErrorCategory.BLUEPRINT_VALIDATION, message=_OPERATOR_WORDING),
+ ValidationErrorItem(category=ValidationErrorCategory.BLUEPRINT_VALIDATION, message=_OPERATOR_WORDING),
+ ],
+ )
+
def _build_client() -> TestClient:
app = FastAPI()
@@ -51,7 +108,7 @@ class TestValidateRenderedMarkdown:
assert body["is_valid"] is False
assert body["rendered_markdown"].startswith("# Validation failed")
# The structured verdict is still present; markdown is the view, not a replacement.
- assert body["validation_errors"]
+ assert body["errors"]
def test_invalid_arm_without_render_has_no_rendered_markdown(self):
client = _build_client()
@@ -78,3 +135,26 @@ class TestValidateRenderedMarkdown:
assert response.status_code == 200, response.text
body = response.json()
assert body["rendered_markdown"].startswith("# Validation passed")
+
+ def test_a_caller_reads_only_the_caller_s_wording_in_both_the_items_and_the_markdown(self, mocker: MockerFixture):
+ # The request is the caller's (no authentication marked it the operator's): its `errors` are the caller's view of
+ # the verdict's items, and the Markdown beside them is rendered from those very items, never from the validation
+ # items' own messages or a parameter that view leaves out.
+ config = ApiConfig(orchestration_mode=_MODE, allow_request_orchestration_mode_override=False)
+ mocker.patch(f"{_PIPELINE_NS}.get_api_config", return_value=config)
+ registry = BundleValidatorRegistry({_MODE: _InvalidVerdictValidator()})
+ mocker.patch(f"{_PIPELINE_NS}.get_bundle_validator_registry", return_value=registry)
+
+ response = _build_client().post("/v1/validate", json={"mthds_contents": [VALID_MTHDS], "render": ["markdown"]})
+
+ assert response.status_code == 200, response.text
+ body = response.json()
+ assert body["is_valid"] is False
+ assert _OPERATOR_WORDING not in response.text
+ assert _OPERATOR_ONLY_COMPONENT not in response.text
+ markdown = body["rendered_markdown"]
+ assert markdown.startswith("# Validation failed")
+ # Every item of `errors` is in the Markdown, by its code and in its sentence.
+ for item in body["errors"]:
+ assert f"(`{item['code']}`)" in markdown
+ assert f" - {item['detail']}" in markdown
diff --git a/api/tests/unit/test_validate_template_check_warnings.py b/api/tests/unit/test_validate_template_check_warnings.py
index 1f42e2eee..baa49b357 100644
--- a/api/tests/unit/test_validate_template_check_warnings.py
+++ b/api/tests/unit/test_validate_template_check_warnings.py
@@ -1,6 +1,7 @@
from fastapi import FastAPI
from fastapi.testclient import TestClient
from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
+from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
from pipelex.validation_error_types import TemplateCheckErrorType
from pytest_mock import MockerFixture
@@ -42,9 +43,13 @@ class TestValidateTemplateCheckWarnings:
body = response.json()
assert body["is_valid"] is True
family.assert_called_once()
- template_warnings = [warning for warning in body["warnings"] if warning["error_type"] == TemplateCheckErrorType.TEMPLATE_CHECK_WARNING]
+ # The warning rides as a problem item under its code, with the facts its sentence is rendered from.
+ template_warnings = [warning for warning in body["warnings"] if warning["code"] == PipelexErrorCode.DOCGEN_TEMPLATE_WARNING]
assert len(template_warnings) == 1
- assert {key: value for key, value in template_warnings[0].items() if value is not None} == _TEMPLATE_WARNING.model_dump(
- mode="json", exclude_none=True
- )
+ assert template_warnings[0] == {
+ "code": PipelexErrorCode.DOCGEN_TEMPLATE_WARNING,
+ "detail": f"The document template 'invoice.xlsx' may be faulty: {_TEMPLATE_WARNING.message}",
+ "params": {"template": "invoice.xlsx", "finding": _TEMPLATE_WARNING.message},
+ "location": {"pipe": "print_invoice"},
+ }
assert f"- **{TemplateCheckErrorType.TEMPLATE_CHECK_WARNING}** — {_TEMPLATE_WARNING.message}" in body["rendered_markdown"]
diff --git a/api/tests/unit/test_validate_views.py b/api/tests/unit/test_validate_views.py
index fafe9605e..932298bf4 100644
--- a/api/tests/unit/test_validate_views.py
+++ b/api/tests/unit/test_validate_views.py
@@ -90,7 +90,7 @@ class TestValidateInputFormView:
body = response.json()
assert body["is_valid"] is False
assert "input_form" not in body, f"The invalid arm never carries `input_form`, got keys: {sorted(body)}"
- assert body["validation_errors"]
+ assert body["errors"]
def test_unknown_view_token_is_ignored_not_422(self):
# Lenient-ignore: a stale view token must never fail the call.
diff --git a/api/tests/unit/test_vendored_method_packages.py b/api/tests/unit/test_vendored_method_packages.py
index ac3a5f03d..d4bea1e9a 100644
--- a/api/tests/unit/test_vendored_method_packages.py
+++ b/api/tests/unit/test_vendored_method_packages.py
@@ -22,7 +22,6 @@ from fastapi.testclient import TestClient
from mthds.protocol.problem.registry import CoreCode
from pipelex.config import get_config
from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
-from pipelex.methods.address_dependencies import ADDRESS_DEPENDENCY_REFUSAL_MARKER
from pipelex.pipe_run.delivery_assignment import DeliveryAssignment
from pipelex.pipe_run.pipe_job import PipeJob
from pipelex.plugins.orchestrator_registry import OrchestratorRegistry
@@ -30,8 +29,8 @@ from pipelex.runtime_bridge.payloads import PipelexPipeDispatchAck, PipelexPipeR
from pytest_mock import MockerFixture
from pipelex_api.api_config import ApiConfig
-from pipelex_api.errors import ApiError
from pipelex_api.exception_handlers import register_exception_handlers
+from pipelex_api.exceptions import RequestMethodError
from pipelex_api.method_source import fetched_method
from pipelex_api.problem_view import mark_operator_request
from pipelex_api.routes import router as api_router
@@ -45,6 +44,7 @@ from tests.unit._constants import (
VENDORED_PROBE_MARKER,
VENDORED_PROBE_MTHDS,
)
+from tests.unit._problems import assert_problem
_PIPELINE_NS = "pipelex_api.routes.pipelex.pipeline"
_METHOD_REF = f"{STUB_METHOD_ADDRESS}@v0.1.0"
@@ -270,12 +270,8 @@ class TestVendoredMethodPackages:
response = client.post("/v1/execute", json={"method_ref": _METHOD_REF, "inputs": {"text": "hello"}})
- assert response.status_code == 422, response.text
- body = response.json()
- assert body["error_type"] == "InvalidMethodFiles"
- assert f"method package '{STUB_METHOD_ADDRESS}'" in body["detail"]
- assert VENDORED_PROBE_ADDRESS in body["detail"]
- assert "'.mthds/methods/b/'" in body["detail"]
+ body = assert_problem(response, status=422, code="method.package_invalid")
+ assert body["params"] == {"reason": "dependency_address_collision", "path": ".mthds/methods/b/"}
def test_a_method_ref_package_keeps_its_shipped_files_apart(self, install_method_package: Callable[..., Path]):
install_method_package(files={"smoke.mthds": UNRESOLVED_PACKAGE_MTHDS, **_package_vendoring_files()})
@@ -309,14 +305,12 @@ class TestVendoredMethodPackages:
install_method_package(files={"smoke.mthds": UNRESOLVED_PACKAGE_MTHDS, ".mthds/methods/unfinished/draft.mthds": UNRESOLVED_PACKAGE_MTHDS})
client = _build_client(mocker, tmp_path=tmp_path)
- with pytest.raises(ApiError, match="unfinished"):
+ with pytest.raises(RequestMethodError, match="unfinished"):
fetched_method(_METHOD_REF)
response = client.post("/v1/pipe-io", json={"method_ref": _METHOD_REF})
- assert response.status_code == 422, response.text
- problem = response.json()
- assert problem["error_type"] == "InvalidMethodFiles"
- assert "unfinished" in problem["detail"]
+ problem = assert_problem(response, status=422, code="method.package_invalid")
+ assert problem["params"] == {"reason": "manifest_missing", "path": ".mthds/methods/unfinished/METHODS.toml"}, problem
@pytest.mark.parametrize("route", ["/v1/pipe-io", "/v1/resolve", "/v1/codegen"])
def test_a_crate_route_resolves_the_dependency_a_method_ref_ships(
@@ -353,13 +347,14 @@ class TestVendoredMethodPackages:
verdict = response.json()
assert verdict["is_valid"] is sends_the_dependency, response.text
if not sends_the_dependency:
- assert [(item["error_type"], item["missing_pipe_code"]) for item in verdict["validation_errors"]] == [
- ("unresolved_package_dependency", UNRESOLVED_PACKAGE_REFERENCE)
- ]
+ package_address = UNRESOLVED_PACKAGE_REFERENCE.split("->", maxsplit=1)[0]
+ assert [(item["code"], item["params"]) for item in verdict["errors"]] == [
+ ("method.dependency_missing", {"kind": "package", "name": package_address, "reason": "not_found"})
+ ], verdict
@pytest.mark.parametrize("route", ["/v1/pipe-io", "/v1/resolve", "/v1/codegen"])
def test_a_crate_route_never_looks_up_or_fetches_a_dependency_nothing_shipped(self, mocker: MockerFixture, tmp_path: Path, route: str):
- """Even with fetch-on-miss on, a crate route resolves statically, refusing the call in the words a hosted run matches."""
+ """Even with fetch-on-miss on, a crate route resolves statically, its verdict naming the missing package by its code."""
client = _build_client(mocker, tmp_path=tmp_path)
mocker.patch("pipelex.methods.fetch_on_miss.is_method_fetch_on_miss_enabled", return_value=True)
lookup = mocker.patch(
@@ -377,11 +372,10 @@ class TestVendoredMethodPackages:
verdict = response.json()
assert verdict["is_valid"] is False, response.text
lookup.assert_not_called()
- [item] = verdict["validation_errors"]
- assert item["error_type"] == "unresolved_package_dependency"
- assert item["source"] == "bundle.mthds"
- # The item quotes the refusal itself; the verdict's message is the sentence its code renders.
- assert f"{ADDRESS_DEPENDENCY_REFUSAL_MARKER} '{VENDORED_PROBE_ADDRESS}'" in item["message"]
+ [item] = verdict["errors"]
+ assert item["code"] == "method.dependency_missing"
+ assert item["params"] == {"kind": "package", "name": VENDORED_PROBE_ADDRESS, "reason": "not_found"}
+ assert item["location"]["file"] == "bundle.mthds"
def test_validate_by_method_ref_resolves_the_dependency_it_ships(
self, mocker: MockerFixture, tmp_path: Path, install_method_package: Callable[..., Path]
@@ -408,9 +402,10 @@ class TestVendoredMethodPackages:
assert response.status_code == 200, response.text
body = response.json()
assert body["is_valid"] is False
- assert [(item["error_type"], item["missing_pipe_code"]) for item in body["validation_errors"]] == [
- ("unresolved_package_dependency", UNRESOLVED_PACKAGE_REFERENCE)
- ]
+ package_address = UNRESOLVED_PACKAGE_REFERENCE.split("->", maxsplit=1)[0]
+ assert [(item["code"], item["params"]) for item in body["errors"]] == [
+ ("method.dependency_missing", {"kind": "package", "name": package_address, "reason": "not_found"})
+ ], body
def _package_vendoring_files() -> dict[str, str]:
diff --git a/docs/api-server/codegen.md b/docs/api-server/codegen.md
index 256e2011b..b05d86742 100644
--- a/docs/api-server/codegen.md
+++ b/docs/api-server/codegen.md
@@ -4,26 +4,26 @@ Resolve a library closure into its **normalized library crate**, and project tha
Both are **Pipelex API extensions**, not MTHDS Protocol routes: they are not tagged `x-mthds-protocol` in the [OpenAPI artifact](openapi/pipelex-api.openapi.yaml), and an MTHDS runner is not required to serve them. The *crate* is a different matter — its shape is the standard's [Library Crate Format](https://mthds.ai), so the wire fields are brand-neutral and any MTHDS tool can read one. What is ours is the HTTP surface that produces it, and the type projection on top (the standard specifies none).
-Both endpoints speak the [`POST /v1/validate`](pipe-validate.md) verdict discipline: a **produced verdict is always a `200`** discriminated on `is_valid`; the invalid arm carries the structured `validation_errors[]` from pipelex's one shared builder — each item optionally carrying a [`suggested_fix`](error-responses.md#suggested-fixes). Non-2xx is reserved for *no verdict could be produced*: request-shape errors (an unknown projection `kind`/`target`, a malformed method selector) and a method tree that cannot be read are `422` RFC 9457 `application/problem+json`, the custom-Python policy is a `403` (the refusal of Python structure classes a `422`), a registry-form `method_ref` is `501`, an address-form `method_ref` that fails to resolve maps per the [`method_ref` error table](pipe-run.md#running-a-method-by-address-method_ref), auth is `401`/`403`, server faults are `5xx`.
+Both endpoints speak the [`POST /v1/validate`](pipe-validate.md) verdict discipline: a **produced verdict is always a `200`** discriminated on `is_valid`; the invalid arm carries the structured `errors[]`, one problem item per finding from pipelex's one shared builder — each item optionally carrying a [`suggested_fix`](error-responses.md#suggested-fixes). Non-2xx is reserved for *no verdict could be produced*: request-shape errors (an unknown projection `kind`/`target`, a malformed method selector) are `422` `request.invalid` RFC 9457 `application/problem+json`, a method tree that cannot be read is a `422` naming its refusal, custom Python on a deployment that is not sandbox-hosted is a `501` `pipelex.deployment.custom_code_requires_sandbox` (the refusal of Python structure classes a `422`), a registry-form `method_ref` is a `422` `request.unsupported` whose `reason` is `registry_form_method_ref`, an address-form `method_ref` that fails to resolve maps per the [`method_ref` error table](pipe-run.md#running-a-method-by-address-method_ref), auth is `401`/`403`, server faults are `5xx`.
## Selecting the method
Both endpoints take the method the way [`POST /v1/validate`](pipe-validate.md#validating-a-method-tree) and the [run routes](pipe-run.md#sending-a-method-as-a-tree) take it, as a method tree, read by the same machinery, so a tree one route accepts, refuses or resolves, the others accept, refuse or resolve the same way. The request names it with exactly one of:
- `files` (object): the method as the MTHDS protocol's map of file entries, each key a tree path and each value the file's text, `{"base64": "…"}` or `{"sha256": "…", "size": n}` naming bytes this runner already holds in its [blob store](pipe-run.md#sending-files-by-hash). The tree is written whole and loaded as the caller's library directory: every `.mthds` bundle is named by its tree path, which threads onto diagnostics and the crate's `source_map`, and every other file is one a step may read, such as a `PipeDocGen` template beside its bundle.
-- `method_ref` (string): a reference to a published method. The **address form**, `github.com/<owner>/<repo>` plus an optional package selector and `@<tag>`, is resolved server-side through the same fetch path as a [`method_ref` run](pipe-run.md#running-a-method-by-address-method_ref): the package's whole tree is read from the commit and loaded as a tree sent in `files` is, and the packages it ships under its own `.mthds/methods/<name>/` are loaded beside it, so a call into one resolves. The **registry form** (any non-address reference) stays reserved: the server answers **`501`** (`MethodRefNotSupported`) until method-registry resolution lands.
+- `method_ref` (string): a reference to a published method. The **address form**, `github.com/<owner>/<repo>` plus an optional package selector and `@<tag>`, is resolved server-side through the same fetch path as a [`method_ref` run](pipe-run.md#running-a-method-by-address-method_ref): the package's whole tree is read from the commit and loaded as a tree sent in `files` is, and the packages it ships under its own `.mthds/methods/<name>/` are loaded beside it, so a call into one resolves. The **registry form** (any non-address reference) stays reserved: the server answers a **`422`** `request.unsupported`, whose `reason` is `registry_form_method_ref`, until method-registry resolution lands.
Providing neither or both is a request-shape `422`. Beside `files`, the request may also carry:
- `dependencies` (object): the method packages the method calls by address, each a map of file entries keyed by its address, as on a [run](pipe-run.md#sending-the-method-packages-the-method-calls). They are loaded beside the method, never merged into it, so a cross-package call resolves without the server fetching or holding a copy. `dependencies` without `files` is a request-shape `422`.
- `resources` (object): files the method's steps read, such as a `PipeDocGen` step's `template_file`, keyed by the path from the tree's root, each in standard base64, joining the tree with the rules and refusals of [`/v1/validate`](pipe-validate.md#sending-the-files-the-steps-read-resources). A step that names a template file the tree does not hold cannot be built, so the method is invalid. `resources` beside a `method_ref` is a request-shape `422`: a published method's files are its package's own.
-- `read_scope` (string): **Pipelex-API extension.** The scope the request reads the method under, as on `/v1/validate`: a hash entry of `files` resolves in that scope's blob store, else in the caller's own id's, and only a request carrying a `read_scope` records the tree it read in the blob store; [a `jwt` caller may send only a scope under its own id](pipe-run.md#host-supplied-run-context-storage_scope-and-analytics_groups), else a `403 ReadScopeForbidden`.
+- `read_scope` (string): **Pipelex-API extension.** The scope the request reads the method under, as on `/v1/validate`: a hash entry of `files` resolves in that scope's blob store, else in the caller's own id's, and only a request carrying a `read_scope` records the tree it read in the blob store; [a `jwt` caller may send only a scope under its own id](pipe-run.md#host-supplied-run-context-storage_scope-and-analytics_groups), else a `403` `auth.forbidden` whose `requirement` is `read_scope_under_caller`.
-**The tree's refusals produce no verdict**, exactly as on `/v1/validate`: a key or entry the tree's rule refuses is a `422 InvalidMethodFiles` with its `tree_refusal` member, a hash the runner does not hold a `422 MissingBlobs`, a tree past its limits a `422 MethodTreeTooLarge`, and a tree holding no `.mthds` bundle of its own a `422 InvalidBundle`. A `files` member that is not a map, such as a list, is an `InvalidMethodFiles` too.
+**The tree's refusals produce no verdict**, exactly as on `/v1/validate`: a key the tree's rule refuses is a `422` `method.package_invalid` naming the rule as its `reason`, or `security.input_path_refused` for a key leaving the tree's root, a malformed entry a `422` `request.invalid`, a hash the runner does not hold a `422` `request.blobs_missing`, a tree past its limits a `422` `method.package_invalid` naming the limit, and a tree holding no `.mthds` bundle of its own a `422` `method.package_invalid` whose `reason` is `no_bundle`. A `files` member that is not a map, such as a list, is a `422` `request.invalid` naming `files`.
-**Python follows the run routes' policy.** A projection runs nothing, but loading a method's library on a deployment that is not sandbox-hosted imports each of its `.py` files that declares a structure class (a `StructuredContent` subclass), which runs that file's module-level code in the server's process. So there a tree, sent or fetched, that holds any `.py` file is refused with a `403 CustomCodeRequiresSandbox` before anything is written. On a sandbox-hosted deployment, a tree whose Python declares a structure class is refused with a `422` problem, `pipelex.deployment.python_structures_refused`, as on a [run](pipe-run.md#sending-a-method-as-a-tree).
+**Python follows the run routes' policy.** A projection runs nothing, but loading a method's library on a deployment that is not sandbox-hosted imports each of its `.py` files that declares a structure class (a `StructuredContent` subclass), which runs that file's module-level code in the server's process. So there a tree, sent or fetched, that holds any `.py` file is refused with a `501` `pipelex.deployment.custom_code_requires_sandbox` before anything is written. On a sandbox-hosted deployment, a tree whose Python declares a structure class is refused with a `422` problem, `pipelex.deployment.python_structures_refused`, as on a [run](pipe-run.md#sending-a-method-as-a-tree).
-**A call by address resolves only from what was shipped.** A package the method calls by its address is loaded from the packages the request sends in `dependencies`, or that a fetched package ships under its `.mthds/methods/`, and from nowhere else: these routes never read a method installed on the runner and never fetch one. A call into a package nothing shipped is therefore the invalid verdict, one `unresolved_package_dependency` item per package, located on the pipe that calls it, whose message names it as `address-based dependency '<address>'`. The method is written out, loaded, projected and released in a worker thread, so a slow load never holds up the server's other requests.
+**A call by address resolves only from what was shipped.** A package the method calls by its address is loaded from the packages the request sends in `dependencies`, or that a fetched package ships under its `.mthds/methods/`, and from nowhere else: these routes never read a method installed on the runner and never fetch one. A call into a package nothing shipped is therefore the invalid verdict, one `method.dependency_missing` item per package, located on the pipe that calls it, naming the package's address as its `name` with the `reason` `not_found`. The method is written out, loaded, projected and released in a worker thread, so a slow load never holds up the server's other requests.
## Resolve
@@ -62,7 +62,7 @@ Resolution is a first-class language operation alongside validation: the closure
`crate` is the canonical JSON encoding of the normalized crate — the same bytes `pipelex resolve --format json` prints, so fingerprints computed from either surface agree.
-**Response (invalid verdict):** `200` with `is_valid: false` and `validation_errors[]` (no crate exists).
+**Response (invalid verdict):** `200` with `is_valid: false` and `errors[]` (no crate exists).
## Codegen
diff --git a/docs/api-server/configuration.md b/docs/api-server/configuration.md
index 9967c80ed..52778437c 100644
--- a/docs/api-server/configuration.md
+++ b/docs/api-server/configuration.md
@@ -51,7 +51,7 @@ PIPELEX_ENV=dev
# ── Methods sent as trees, and the blob store (`files`, `/v1/blobs/*`) ─────
# See pipe-run.md → "Sending a method as a tree" and "Sending files by hash".
# Each tree of a request is bounded on its own; over any limit is a 422
-# MethodTreeTooLarge. All read at startup.
+# method.package_invalid naming the limit. All read at startup.
# MAX_METHOD_TREE_FILES=1000 # files in one tree
# MAX_METHOD_TREE_FILE_KIB=32768 # bytes per file, and per uploaded blob (default 32 MiB)
# MAX_METHOD_TREE_TOTAL_KIB=65536 # bytes across one tree (default 64 MiB)
@@ -156,7 +156,7 @@ The base is **orchestrator-agnostic**. WHICH backend a top-level run dispatches
| Key | Meaning | Base default |
| --- | --- | --- |
| `orchestration_mode` | Which **backend** (orchestrator) a top-level run dispatches to. An **open string token**: `direct` (in-process), `temporal`, and any plugin-provided token are accepted; an unregistered token fails loud at dispatch with the plugin's install hint. | `direct` |
-| `allow_request_orchestration_mode_override` | Whether a caller may set `orchestration_mode` per request on `POST /v1/execute`, `POST /v1/start`, and `POST /v1/validate`. When `false`, a requested token that differs from the deployment default is refused with a `403`. | `false` |
+| `allow_request_orchestration_mode_override` | Whether a caller may set `orchestration_mode` per request on `POST /v1/execute`, `POST /v1/start`, and `POST /v1/validate`. When `false`, a requested token that differs from the deployment default is refused with a `422` `pipelex.deployment.orchestration_override_forbidden`. | `false` |
The packaged default (`orchestration_mode = "direct"`, override off) is what the generic image ships.
@@ -165,7 +165,7 @@ The packaged default (`orchestration_mode = "direct"`, override off) is what the
**`orchestration_mode` is one of two orthogonal axes.** It names only the **backend**. The other axis — *delivery*, i.e. whether the caller waits — is **endpoint-intrinsic**, never configured and never requestable:
- `POST /v1/execute` and `POST /v1/validate` are **synchronous** (`BLOCKING` delivery): they return the full output / the verdict.
-- `POST /v1/start` is **fire-and-forget** (`FIRE_AND_FORGET` delivery): it returns immediately with a `workflow_id`. It works only on a backend that is genuinely async-capable. A Temporal deployment (`orchestration_mode = "temporal"`) enqueues on `/start` and returns a `workflow_id`. On the orchestrator-agnostic base (`orchestration_mode = "direct"`) the in-process orchestrator is blocking-only, so `/start` is **HONEST**: it refuses with a `400` (`StartRequiresAsyncOrchestration`) — use `/execute` — rather than silently running blocking and acking.
+- `POST /v1/start` is **fire-and-forget** (`FIRE_AND_FORGET` delivery): it returns immediately with a `workflow_id`. It works only on a backend that is genuinely async-capable. A Temporal deployment (`orchestration_mode = "temporal"`) enqueues on `/start` and returns a `workflow_id`. On the orchestrator-agnostic base (`orchestration_mode = "direct"`) the in-process orchestrator is blocking-only, so `/start` is **HONEST**: it refuses with a `501` `runtime.unsupported` — use `/execute` — rather than silently running blocking and acking.
So a deployment sets **one** `orchestration_mode` and each endpoint applies its own delivery — there is no fire-and-forget token to configure or request.
diff --git a/docs/api-server/error-responses.md b/docs/api-server/error-responses.md
index 99beab76b..c35402111 100644
--- a/docs/api-server/error-responses.md
+++ b/docs/api-server/error-responses.md
@@ -1,6 +1,6 @@
# Error Responses
-Every error returned by the API is an RFC 9457 `application/problem+json` document. A failure the Pipelex runtime raised, which is every domain error, every run failure and the catch-all, answers its **problem document**, named by a registry code and seen through the view the request's identity gives it. A refusal the API authors itself, such as a malformed body, a missing token or a payload over its limit, answers a problem document of its own, classified by an `error_type`.
+Every error returned by the API is an RFC 9457 `application/problem+json` **problem document**, named by a registry code and seen through the view the request's identity gives it. That holds for a failure the Pipelex runtime raised, which is every domain error, every run failure and the catch-all, and for a refusal the runner authors itself at its own boundary, such as a malformed body, a missing token, a payload over its limit or a path no route serves: there is one shape, and a client branches on its `code`.
## Envelope
@@ -59,20 +59,17 @@ A failure the runtime raised looks like this, in the caller view:
- `request_id` — server-correlated identifier for the request. Echoed from inbound `X-Request-ID` if provided, otherwise generated. Use this when reporting issues.
- `diagnostics` — present in the operator view alone. See [Views chosen by identity](#views-chosen-by-identity).
-### API-authored errors
+### The runner's own refusals
-A refusal the API authors itself, before the runtime is asked anything, carries no `code` yet. It keeps the classification members it had before the problem document, beside the RFC's `type`, `title`, `status` and `detail`:
+A refusal the runner authors itself, before the runtime is asked anything, is a problem document like any other, named by its code and seen through the view the request's identity gives it. Its `detail` and `next_step` are its code's sentences, and the runner's own account of what it checked rides the operator view's `diagnostics.message`. The codes it answers are listed under [Status codes](#status-codes). A few conventions hold across them:
-- `error_type` — the refusal's name, such as `ValidationError`, `InvalidJSON`, `Unauthenticated` or `PayloadTooLarge`, the member to branch on. See [Status codes](#status-codes).
-- `error_domain` — `input` for a refusal the caller can fix, `config` for one the deployment must.
-- `retryable` — always present, and `false`: every such refusal is a request to correct or a deployment to fix.
-- `instance` — the request's path.
-- `request_id` — as above.
-- `tree_refusal` — on a **422** `InvalidMethodFiles`, the MTHDS standard's refusal of a method tree the request sent: `{"code": "<refusal code>", "names": [...]}`, the code one of the standard's tree refusal codes, such as `invalid_tree_path`, `duplicate_key`, `excluded_name` or `malformed_entry`, and `names` the keys, paths or addresses it refuses. A name holding a code point UTF-8 cannot encode, such as a lone surrogate a JSON escape can carry, is written with that code point backslash-escaped. See [Pipe Run](pipe-run.md#sending-a-method-as-a-tree).
-- `missing_blobs` — on a **422** `MissingBlobs`, the SHA-256 hashes the request named by hash entries that this runner does not hold at their stated size, to upload through the blob routes before sending the request again. See [Sending files by hash](pipe-run.md#sending-files-by-hash).
-- `mismatched_blobs` — on a **422** `BlobMismatch` refusing a request's hash entries, each hash this runner holds at another size than its entry states, as `{"sha256": "…", "held_size": n}`: the entry's size is the one to correct, since uploading the bytes again would not change the size they are held at.
+- A field the route's rules refuse is `request.invalid`, whose `field` parameter, also its `location.field`, names the field as the request spells it, or a dotted path into the body such as `callback_urls.0`. When several fields fail at once, `errors` carries one `request.invalid` item per refused field, so a client fixes them all in one go, and the problem's own `field` is the first of them. The items stop at a bound, since a list the caller sent can fail item by item, and the operator view's `diagnostics.message`, which names each fault with pydantic's account of it, stops at the same bound and says how many more faults there were. A rule of the request model that concerns several fields together names the one to change: sending two of `mthds_contents`, `files` and `method_ref` names the second, sending none names the first, and `mthds_sources` beside a `method_ref`, or of another length than `mthds_contents`, names `mthds_sources`. Only a body that is not a JSON object names the field `body`.
+- A body, or an encoded part of one, that cannot be parsed is `request.malformed`, whose `reason` says why: `not_json`, `not_utf8`, `integer_too_long`, `bad_base64`, `bad_zip`, `too_deeply_nested` or `body_incomplete`, and `unreadable` for a `400` or a `422` the framework raised while reading the request that no check of the runner's own made first, which keeps the status it was raised with. A client's malformed request is never answered as a fault of the server.
+- Any other refusal the framework raises keeps its status and its meaning, under a code whose required parameters the runner can fill: the framework says nothing about a refusal but its status and a header, so a code whose parameters it cannot know gives way to one whose parameters it can. A `401` is `auth.missing_credential`, keeping the `WWW-Authenticate` challenge it was raised with; a `403` is `auth.invalid_credential`, since `auth.forbidden` names a `requirement` the framework does not; a `404` is `request.not_found`, and a `405` `request.method_not_allowed`, keeping its `Allow`; a `413` is `request.malformed` with the reason `too_large`, since `request.too_large` states a `limit` and a `size` the framework does not; and a `429` is `runtime.unavailable`, whose verdict invites a retry, keeping its `Retry-After`, since `account.rate_limited` states a `limit` and a `window` the framework does not. Any other `4xx`, such as a `415`, is `request.malformed` with the reason `unreadable`. Each answers with the status it was raised with, whichever status its code declares. A `5xx` the framework raises is its own fault, `runtime.unexpected`.
+- A request past one of this runner's size limits is `request.too_large`, a **413** whose `limit` and `size` parameters give the limit and what the request carried, always in bytes: an encoded value, a file of `resources` or a `bundle_b64` archive, is measured by the bytes its encoded length carries, read before it is decoded.
+- A method tree the runner refuses to read as a method is `method.package_invalid`, whose `reason` names the rule the tree breaks and whose `path` or `limit` says where or how far.
-Its `detail` is the API's own sentence about what it checked, and it reads the same in every view.
+The members the runner's refusals used to carry are gone: no refusal carries an `error_type`, `error_domain`, `retryable` or `instance`. The request's path is not echoed, since `request_id`, which the runner takes from an inbound `X-Request-ID` or mints, is what correlates a response with the server's records.
## Views chosen by identity
@@ -85,6 +82,8 @@ A failure the runtime raised is one problem seen through a view, and the identit
| `AUTH_MODE=jwt`: a caller's token | The caller view |
| `AUTH_MODE=none` without the trusted proxy, or a request refused before any authentication ran | The caller view |
+A refusal the runner authors before any authentication ran, such as a body over the size limit or a path no route serves, is answered in the caller view.
+
**The caller view** carries the code's sentences, rendered from the parameters a caller may read, and the step for the caller: for a code of the `operator` domain, whose actor is whoever runs this server, that is what the caller can do meanwhile, such as choosing another model. It never carries the error's own message, its class, a path on the host, a provider's answer or a foreign exception's text, whatever the failure. A problem this server relays with a code its own registries do not hold, such as one a newer worker built, reaches the caller with the generic step of its kind, and `report` for a code of the `operator` domain, since its recorded step was written for the operator.
**The operator view** adds the operator's step and `diagnostics`:
@@ -101,54 +100,46 @@ A failure the runtime raised is one problem seen through a view, and the identit
Every text in a problem that the runtime did not write itself, a message, a provider's answer or a parameter, is cut to a bounded length, keeping its head and ending with ` […]`.
-The catch-all, a failure no more specific handler matched, answers `runtime.unexpected` with a **500** in both views: the caller reads that code's sentences, and the operator reads the exception's class in `diagnostics`, never its text, which can carry anything of a run's data, a pydantic refusal adding its reasons without the values it refused. A traceback never reaches a response in either view.
+The catch-all, a failure no more specific handler matched, answers `runtime.unexpected` with a **500** in both views: the caller reads that code's sentences, and the operator view reads the exception's class in `diagnostics`, never its text, which can carry anything of a run's data, a pydantic refusal adding its reasons without the values it refused. A traceback never reaches a response in either view, and neither the traceback nor the exception's text reaches a log: the server's error line names the classes of the exception's chain and the frames it was raised through (see [Logging](logging.md)).
The server's own record of a failure the runtime raised is built from the operator view, whichever view the response carries, so it names the error's class, its code and what the inference provider answered (see [Logging](logging.md)).
## Structured validation errors
-When a bundle fails validation, the runtime builds one structured item per fault — the per-error diagnostics an editor maps to per-line problems — and where they surface depends on the endpoint. On the diagnostic routes (`/validate`, `/resolve`, `/codegen`, `/pipe-io`) an invalid bundle is the successful product of the call: a **200 `is_valid: false`** verdict carrying the items whole as `validation_errors` (see [Pipe Validate](pipe-validate.md)). On the run routes (`/execute`, `/start`), where an invalid bundle means the run cannot proceed, it is a **422** `method.invalid` problem carrying the same items as its `errors`, each with its own code. Built by pipelex's one shared builder, the items name the same faults at the same places wherever they appear, and the same as the agent CLI's.
+When a bundle fails validation, the runtime builds one structured item per fault — the per-error diagnostics an editor maps to per-line problems — and every surface of this server carries them as the MTHDS standard's **problem items**. On the diagnostic routes (`/validate`, `/resolve`, `/codegen`, `/pipe-io`) an invalid bundle is the successful product of the call: a **200 `is_valid: false`** verdict carrying the items as `errors` (see [Pipe Validate](pipe-validate.md)). On the run routes (`/execute`, `/start`), where an invalid bundle means the run cannot proceed, it is a **422** `method.invalid` problem carrying the same items as its `errors`. Built by pipelex's one shared builder, the items name the same faults at the same places wherever they appear, and the same as the agent CLI's. A valid verdict's `warnings` are problem items too, in the same shape.
-Each `validation_errors` item of a verdict is one categorized validation failure:
+Each item is one fault:
-| Field | Meaning |
+| Member | Meaning |
|---|---|
-| `category` | The failure family — one of `blueprint_validation`, `pipe_factory`, `pipe_validation`, `dry_run`. |
-| `message` | Human-readable description of this specific error. On a `dry_run` item it names the pipe, then the sentence the failure's code renders for a caller, never the failure's own text. |
-| `error_type` | Finer error subtype within the category, when the source error provides one. |
-| `source` | The owning file of the error, when the runtime could attribute it to one: on `blueprint_validation` and `pipe_validation` items, and on a `dry_run` item, where it is the file of the pipe whose dry run failed. On the in-memory submit path it is the matching `mthds_sources[i]` (see [Sourcing submitted files](pipe-validate.md)), so it is absent when the caller sent no sources. Absent on `pipe_factory` items and on the parse-level residual described below. Beside a server's own library directories, an item never names one of their files, nor a template file one of their `PipeDocGen` steps names. |
-| `pipe_code`, `concept_code`, `domain_code` | The pipe / concept / domain the error is about, when applicable. On a `dry_run` item they name the innermost pipe that failed, not the controller the failure passed through. |
-| `field_path`, `field_name` | The offending field within the bundle, when the error localizes to one. |
-| `variable_names`, `missing_concept_code`, `missing_pipe_code`, `declared_concepts` | Extra context for specific failure shapes (undefined variables, an unresolved concept, pipe or package reference, the set of concepts that were declared). On an `unresolved_package_dependency` item, `missing_pipe_code` is the reference as written, `<address>->domain.code`, so the package's address is the part before `->`. |
-| `line`, `column` | The 1-based position where the TOML parser stopped, on a TOML syntax error. |
-| `model_reference`, `model_type`, `suggestions` | On an `unknown_model` item — a pipe naming a model the deployment's model deck does not define — the reference as the bundle wrote it, the kind of model the pipe needs (`llm`, `extract`, …), and the deck's close matches of that kind. With exactly one suggestion the item also carries an `unsafe` `suggested_fix` renaming the model. On an `llm_setting_refused_by_model` item — a `PipeLLM` or `PipeStructure` whose model setting the model it resolves to refuses, which its worker would refuse at the first call — `field_name` and `field_path` name the `model` or `model_to_structure` field holding the setting, and `model_reference` is the preset, alias or model that field names, absent when it writes the setting inline or the pipe leaves it to the deck's override or default. |
-| `template_file`, `template_location` | On a `template_check_warning` item, which rides the valid verdict's `warnings` rather than `validation_errors`, the template file as the `PipeDocGen` step names it and the place in it the engine's finding names, in the engine's own words (a defined name, a Table, a cell, a shape, a tag); `template_location` is absent when the engine names no place. A step of the server's own library directories is named by its `pipe_code` and `domain_code` alone: its item carries no `template_file`, and its message reads `<host library file>` where it named the file. |
-| `suggested_fix` | A structured, deterministic fix for this error — present only when the fix planner derived one. See [Suggested fixes](#suggested-fixes). |
-
-Items carry only the fields that apply to their category — absent fields are omitted, not null.
+| `code` | The registry code of the fault: the code its type maps to, such as `method.input_undeclared` for an input a pipe reads but does not declare, `model.unknown` for a model the deck does not define, `method.syntax` for a TOML syntax error or `method.dependency_missing` for a package the method calls and no one supplied. A `dry_run` item's code is its failure's own, and an item no stage classified takes `method.schema_violation`, or the code of the refusal behind it. |
+| `detail` | The code's sentence, rendered from the item's parameters, or the code's title when the item lacks a parameter the sentence names. A program branches on `code`, never on a sentence. |
+| `params` | The facts the item's locators give the code, by the registry's names: the `pipe`, the `variables` it reads, the `concept` or `model` it names, the `model_type`, a `finding` quoting the validation's own account. |
+| `location` | Where the fault is: the `pipe`, the `field` within the bundle, and the `file` with its 1-based `line` and `column` when the parser stopped there. On the in-memory submit path the `file` is the matching `mthds_sources[i]` (see [Sourcing submitted files](pipe-validate.md)), so it is absent when the caller sent no sources. Beside a server's own library directories, an item never names one of their files, nor a template file one of their `PipeDocGen` steps names. |
+| `suggestions` | On a `model.unknown` item, the deck's close matches of the kind the pipe needs. |
+| `suggested_fix` | A structured, deterministic fix for this fault — present only when the fix planner derived one. See [Suggested fixes](#suggested-fixes). |
-On a `422` problem, each item becomes one `errors` entry: its `code` is the code its `error_type` maps to (`method.input_undeclared` for a `missing_input_variable`, `model.unknown` for an `unknown_model`), a `dry_run` item's is its failure's own, and an item no stage classified takes `method.schema_violation` or the code of the refusal behind it; its `detail` is that code's sentence and its `params` the facts the item's locators give it; its `location` holds the item's `pipe`, `field`, `file`, `line` and `column`; and it keeps the item's `suggestions` and `suggested_fix`.
+An item writes no member that has no value: an absent member is not `null`.
-Every invalid verdict carries a **non-empty** list of items — the structured-info invariant is total. A parse-level failure the runtime cannot attribute to a known pipe/concept/field — an empty blueprint, an elaborator failure — still becomes one `blueprint_validation` residual item carrying the failure message (no `source`, no `error_type` at this layer), so the list is never empty on an invalid verdict. A TOML syntax error is an item of the same category without an `error_type`, which carries the `line` and `column` the parser stopped at and the `source` when the caller sent one. A failing dry run is one `dry_run` item per failing pipe, located at the innermost pipe that failed. A dry run whose every failure belongs to someone other than the method's author, such as a storage outage, is no verdict about the method: it answers the failure's own code, with every failure riding its `errors`.
+Every invalid verdict carries a **non-empty** list of items — the structured-info invariant is total. A parse-level failure the runtime cannot attribute to a known pipe, concept or field — an empty blueprint, an elaborator failure — still becomes one residual item carrying the failure as its `finding`, so the list is never empty on an invalid verdict. A TOML syntax error is a `method.syntax` item whose `location` holds the `line` and `column` the parser stopped at, and the `file` when the caller sent one. A failing dry run is one item per failing pipe, located at the innermost pipe that failed. A dry run whose every failure belongs to someone other than the method's author, such as a storage outage, is no verdict about the method: it answers the failure's own code, with every failure riding its `errors`.
On the run routes, **every refusal of the bundle while it loads is this verdict**, and the load happens before any pipe runs: a misspelled concept, a wiring mismatch, an unknown model, a TOML fault or a refusal raised while a pipe is built all answer the same **422** `method.invalid` carrying the same items validating the bundle gives. None of them reaches a run as a `500`. An entry pipe the bundle does not declare answers `request.pipe_not_found`, and a bare code matching pipes in several domains `request.pipe_ambiguous`.
## Suggested fixes
-A validation error item may carry a `suggested_fix`: a deterministic repair the runtime's fix planner derived from the *typed* error data — never by parsing a message string. It rides a verdict's `validation_errors` item and a problem's `errors` item as the same object. It is optional and additive. An item the planner has no rule for simply omits the field, and a client that ignores `suggested_fix` entirely behaves exactly as before.
+A problem item may carry a `suggested_fix`: a deterministic repair the runtime's fix planner derived from the *typed* error data — never by parsing a message string. It is the MTHDS standard's fix, the same object on a verdict's item and on a problem's. It is optional and additive. An item the planner has no rule for simply omits the member, and a client that ignores `suggested_fix` entirely behaves exactly as before.
```json
{
- "category": "pipe_validation",
- "message": "Pipe 'summarize_and_translate' declares output 'Text' but its last step produces 'Translation'",
- "error_type": "inadequate_output_concept",
- "pipe_code": "summarize_and_translate",
- "source": "translate.mthds",
+ "code": "method.output_concept_mismatch",
+ "detail": "A pipe's output concept does not fit",
+ "params": { "pipe": "summarize_and_translate" },
+ "location": { "pipe": "summarize_and_translate", "file": "translate.mthds" },
"suggested_fix": {
"fix_code": "match-sequence-output",
"description": "Set output of pipe 'summarize_and_translate' to 'Translation' to match its last step",
"safety": "safe",
- "source": "translate.mthds",
+ "file": "translate.mthds",
"ops": [
{
"kind": "set_key",
@@ -166,10 +157,10 @@ A validation error item may carry a `suggested_fix`: a deterministic repair the
- `fix_code` — the kebab-case rule id that produced the fix (`match-sequence-output`, `sync-controller-inputs`, `strip-native-concept-redecl`, `strip-namespace`, `delete-redundant-dotted-input`, …). Stable; use it to allow-list or suppress rules.
- `description` — human-readable summary of what the fix does.
- `safety` — `safe` or `unsafe`. Only apply an `unsafe` fix behind an explicit opt-in: it is a likely correction, such as the one close match for an unknown model, that a person or an agent must confirm, and `pipelex fix bundle` never applies one on its own.
-- `source` — the file the ops target, when known. **An applier must only apply ops to the file they target** — in a multi-file library the ops are meaningless against any other file.
+- `file` — the file the ops target, when known. **An applier must only apply ops to the file they target** — in a multi-file library the ops are meaningless against any other file.
- `ops` — the semantic TOML patch operations, in order.
-**Ops** are addressed by `table_path` (the containing table, e.g. `["pipe", "my_seq"]` — the same addressing convention as the items' `field_path`). An op is a **union discriminated on `kind`**: read `kind` off the wire and you know exactly which other fields the op carries, because each kind is its own shape in the OpenAPI artifact rather than one open shape with everything optional.
+**Ops** are addressed by `table_path` (the containing table, e.g. `["pipe", "my_seq"]`). Each op's `kind` names its shape: read `kind` off the wire and you know exactly which other fields the op carries, because each kind is its own shape in the OpenAPI artifact rather than one open shape with everything optional. An op whose `kind` is none of those below, which a newer runtime could send, is read as an unknown op that an applier never applies.
| `kind` | Effect | Carries besides `table_path` |
|---|---|---|
@@ -233,7 +224,7 @@ The HTTP status of a failure the runtime raised is the one its code declares in
- **422** — the caller's request or method: `method.invalid` and the method's other codes, `input.missing` and the input's other codes, `request.pipe_not_found`, `request.pipe_ambiguous`, `model.unknown`, `model.content_refused`.
- **429** — `provider.rate_limited`: an upstream inference provider rate-limited the run, a retry can succeed, and `Retry-After` is set when the provider gave a delay. Only `POST /v1/execute` runs inference, so only `/execute` can produce it.
- **500** — the operator's configuration, such as `pipelex.config.variable_missing` or `pipelex.config.invalid`, and the catch-all `runtime.unexpected`.
-- **501** — something this deployment does not serve: `model.unavailable`, a model it serves no backend for; `runtime.unsupported`, async pipeline execution (`POST /v1/start`) on a deployment that does not provide it.
+- **501** — something this deployment does not serve: `model.unavailable`, a model it serves no backend for; `runtime.unsupported`, async pipeline execution (`POST /v1/start`) on a deployment that does not provide it. Nothing is broken, and a caller meets the refusal each time it asks, so its log line is a warning, never an error (see [Logging](logging.md)).
- **502** — an upstream service failed: `provider.unavailable`, `provider.failed`, `provider.quota_exhausted`, `provider.credential_refused`, `method.fetch_failed`. A **504** is `provider.timeout`.
A few runtime refusals worth knowing by their code:
@@ -242,31 +233,37 @@ A few runtime refusals worth knowing by their code:
- **409** — `pipelex.run.already_exists`: the submitted `pipeline_run_id` is already registered for a run that is still in flight on this server. Completed and failed runs free their id, so this only fires for genuinely concurrent duplicates — resubmit after the in-flight run finishes, or pick a fresh id. Only `POST /v1/start` accepts a client-supplied `pipeline_run_id`, so only `/start` can produce it.
- **422** — the `method_ref` resolution refusals the caller can fix: `request.invalid` for a reference that does not parse, `method.ambiguous`, and `method.package_invalid` for a package past its limits or carrying a symbolic link. `pipelex.deployment.python_structures_refused` is a **422** too: a method, fetched by `method_ref` or sent as a tree, 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)).
-The API's own refusals, which carry an `error_type` and no code, answer these statuses:
+The runner's own refusals answer these codes:
-- **400** — `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. `BadRequest`: the client disconnected before its request body was received in full, which only the server's logs show, at warning level, since the client is gone before the answer; or a forwarded `X-User-Id` is not a single path-safe segment.
-- **401** — `Unauthenticated`, `InvalidToken` or `TokenExpired`: a missing, invalid or expired bearer token, with `WWW-Authenticate: Bearer` set. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`), or trusts a proxy that forwarded no identity.
-- **403** — `ReadScopeForbidden`: on a `jwt` deployment, the request sent a `read_scope` that does not lie under the caller's own `user_id`, which is the only scope its token may read (see [Pipe Run](pipe-run.md#host-supplied-run-context-storage_scope-and-analytics_groups)). `OrchestrationModeOverrideForbidden`: the request asked for an `orchestration_mode` this deployment does not allow overriding per request (`allow_request_orchestration_mode_override = false`). `BlobUploadNotAuthorized`: a `PUT /v1/blobs/{sha256}` without a valid upload target, its signature missing, forged, expired, or signed for another hash or scope, so ask `POST /v1/blobs/missing` for a fresh target. `CustomCodeRequiresSandbox`: the method (a tree sent with the request, or a fetched `method_ref` package) holds custom Python `.py` files and this deployment is not sandbox-hosted, so running caller-supplied code in-process is refused.
-- **413** — `PayloadTooLarge`: the request body exceeds the configured size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default), or a part of it exceeds its own: a `bundle_b64` archive over `MAX_BUNDLE_FILES` or `MAX_BUNDLE_TOTAL_KIB`, or `resources` over `MAX_RESOURCES_PER_REQUEST`, `MAX_RESOURCE_FILE_KIB` or `MAX_RESOURCES_TOTAL_KIB`.
-- **501** — `MethodRefNotSupported`: the request selected its closure by a **registry-form** `method_ref` — not a `github.com/...` address — and no server-side method registry resolves those yet. Address-form references are fetched and resolved server-side (see [Pipe Run](pipe-run.md#running-a-method-by-address-method_ref)); use one of those, or send the method's tree in `files`. It is permanent under the current deployment — do not retry.
+- **401** — `auth.missing_credential` for a request carrying no bearer token, `auth.invalid_credential` for a token the runner refuses, and `auth.credential_expired` for an expired one, each with `WWW-Authenticate: Bearer` set. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`), or trusts a proxy, which then answers `auth.missing_credential` when it forwarded no identity, with no `WWW-Authenticate`, since that deployment reads no bearer token. A forwarded `X-User-Id` that is not a single path-safe segment is no credential of the caller's: it is a **422** `request.invalid` naming the field `X-User-Id`.
+- **403** — `auth.forbidden`, whose `requirement` names what the request lacks: `signed_upload_target` for a `PUT /v1/blobs/{sha256}` without a valid upload target, its signature missing, forged, expired, or signed for another hash or scope, so ask `POST /v1/blobs/missing` for a fresh target; `read_scope_under_caller` on a `jwt` deployment, for a request that sent a `read_scope` not lying under the caller's own `user_id`, which is the only scope its token may read (see [Pipe Run](pipe-run.md#host-supplied-run-context-storage_scope-and-analytics_groups)).
+- **404** — `request.not_found`: no route serves the request's path.
+- **405** — `request.method_not_allowed`: the route does not accept the request's HTTP method. The response carries the `Allow` header listing the methods it accepts.
+- **413** — `request.too_large`: the request body exceeds the configured size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default), or a part of it exceeds its own: an encoded `bundle_b64` archive over `MAX_BUNDLE_TOTAL_KIB`, a file in `resources` over `MAX_RESOURCE_FILE_KIB`, the files in `resources` over `MAX_RESOURCES_TOTAL_KIB`, or a blob upload over the per-file tree limit.
+- **422** — `request.invalid` for a field the route's rules refuse, `request.malformed` for a body or an encoded part that cannot be parsed, `request.unsupported` for a **registry-form** `method_ref` — not a `github.com/...` address — which no server-side method registry resolves yet (its `reason` is `registry_form_method_ref`; use an address or send the method's tree in `files`), and `pipelex.deployment.orchestration_override_forbidden`, naming the `requested_mode`, for a request asking for an `orchestration_mode` this deployment does not allow overriding per request (`allow_request_orchestration_mode_override = false`).
+- **500** — `runtime.misconfigured`: the runner's own configuration cannot serve the request, such as a missing `API_KEY` or `JWT_SECRET_KEY`, a `PUBLIC_BASE_URL` that is not an HTTP URL, or missing package metadata. Which setting is at fault is the operator's to read, in `diagnostics.params.component`, and in the `error.params.component` of the server's error line whichever view the response took. `pipelex.deployment.token_claims_invalid` is a **500** too: a token whose signature holds carries a `user_id` claim that is missing, unsafe or reserved, which its issuer, not its bearer, must fix.
+- **501** — `runtime.unsupported` naming the `capability` `asynchronous execution`: `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. `pipelex.deployment.custom_code_requires_sandbox`: the method holds custom Python `.py` files and this deployment is not sandbox-hosted, so running caller-supplied code in-process is refused; its `origin` says whether the code came in the request's `bundle` or a fetched `package`.
+- **500** — `pipelex.storage.damaged`, naming the kind of storage as `scheme`, on the routes that read files a request names by hash (`POST /v1/execute`, `POST /v1/start`, `POST /v1/validate`, `POST /v1/resolve`, `POST /v1/codegen` and `POST /v1/pipe-io`): the bytes the blob store holds under a hash do not hash to it, or are not the size it holds them at, so the object stored there is damaged. `PUT /v1/blobs/{sha256}` answers it too for an upload whose bytes hash to an object held at another size, since the runner never writes over a blob. Its verdict is not to retry, since a retry reads the same damaged object, and its step is to report it: the operator removes the object the server's line `Stored blob bytes do not match their hash` names under `blob_sha256` (see [Logging](logging.md#blob-store-lines)), after which the blob is uploaded again.
-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.
+A client that disconnects before its request body was received in full is answered `request.malformed` with the reason `body_incomplete`, which only the server's logs show, at warning level, since the client is gone before the answer.
-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.
+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** `request.malformed` whose `reason` is `too_deeply_nested`. 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 the routes that declare a typed body parse it before validating it, so the same refusals come from that step, all **422**. A body that is not valid UTF-8 or not valid JSON answers `request.malformed` with the reason `not_utf8` or `not_json`, and one holding an integer longer than Python reads from text (`sys.get_int_max_str_digits()`, 4,300 digits by default) the reason `integer_too_long`; and one that is not a JSON object `request.invalid` naming the field `body`. A body carrying, in any object at any depth, a key named `__class__` or `__module__`, or a key starting with `__kajson`, answers `pipelex.security.reserved_key`, whose `keys` parameter 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, and logs the refusal's security event. 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: `request.pipe_not_found` when the selector names no pipe, and `request.pipe_ambiguous` when a bare code, or a dependency's `alias->code`, matches pipes in several domains, naming the pipes it matched as its `candidates`. The run routes answer an unknown or ambiguous `pipe_code` that way. `POST /v1/pipe-io` answers every selection refusal that way, counting a request with no `pipe_ref` over a method that declares no `main_pipe`, or whose domains declare several, as `request.pipe_unspecified`, which names the declared ones as its `candidates`, and a manifest `main_pipe` the method lacks or declares in several domains as the method's own `method.pipe_unresolved` or `method.ref_ambiguous` (see [Pipe I/O](pipe-io.md#pipe-selection)).
-The run routes' extension fields are validated before any method is fetched or any library loaded, and a failure there is a **422** whose `error_type` names the field that failed: `InvalidCallbackUrls` for `callback_urls`, `InvalidStorageScope` for `storage_scope`, `InvalidReadScope` for `read_scope`, `InvalidAnalyticsGroups` for `analytics_groups` (see [Pipe Run](pipe-run.md#host-supplied-run-context-storage_scope-and-analytics_groups)). A storage scope that does not lie under the run's read scope, whether either was sent or defaulted, is an `InvalidReadScope` as well. A failure on another extension field, or on more than one at once, carries the generic `ValidationError`, and the `detail` names every field that failed. `POST /v1/validate` takes `analytics_groups` too and classifies it the same way: a body failing on that field alone answers `InvalidAnalyticsGroups`, and one failing on it and another field answers `ValidationError`.
+The run routes' extension fields are validated before any method is fetched or any library loaded, and a failure there is a **422** `request.invalid` naming the field that failed, `callback_urls`, `storage_scope`, `read_scope` or `analytics_groups`, or a path into it (see [Pipe Run](pipe-run.md#host-supplied-run-context-storage_scope-and-analytics_groups)). A storage scope that does not lie under the run's read scope, whether either was sent or defaulted, names `read_scope`. A body failing on several fields at once carries one item per refused field in `errors`. A callback URL whose scheme is not `http` or `https`, or whose host the SSRF rules refuse, is the security refusal `security.input_url_refused`, which logs its security event and names the class of destination it refused, never the URL. `POST /v1/validate` takes `analytics_groups` too and refuses it the same way.
-A method sent as a tree, in `files` or `bundle_b64`, is read under the MTHDS standard's tree rule before anything loads, on the run routes and `/validate` alike (see [Pipe Run](pipe-run.md#sending-a-method-as-a-tree)). A key or an entry the rule refuses, two shipped packages a reference could not tell apart, or `dependencies` that do not fit the request is a **422** `InvalidMethodFiles` carrying `tree_refusal` when the standard's reader refused it; a hash entry this runner does not hold is a **422** `MissingBlobs` carrying `missing_blobs`, and one it holds at another size than the entry states a **422** `BlobMismatch` carrying `mismatched_blobs`; a tree past `MAX_METHOD_TREE_FILES`, `MAX_METHOD_TREE_FILE_KIB` or `MAX_METHOD_TREE_TOTAL_KIB`, or a method past `MAX_METHOD_DEPENDENCIES` or `MAX_METHOD_REQUEST_TOTAL_KIB` across its trees, is a **422** `MethodTreeTooLarge`. The blob routes answer in the same vocabulary: a body whose SHA-256 is not the one its path names, or one hash listed with two sizes, is a **422** `BlobMismatch`, and a blob past the per-file limit a **422** `MethodTreeTooLarge`. Every one of these carries `retryable: false`. Bytes the blob store holds under a hash that do not hash to it, or an upload whose bytes hash to an object held at another size, are a **500** `BlobStoreCorrupted`: the deployment's storage is damaged, the runner never writes over a blob, and its operator removes the object for the blob to be uploaded again.
+A method sent as a tree, in `files` or `bundle_b64`, is read under the MTHDS standard's tree rule before anything loads, on the run routes and `/validate` alike (see [Pipe Run](pipe-run.md#sending-a-method-as-a-tree)). A key or an entry the rule refuses, two shipped packages a reference could not tell apart, or a tree past `MAX_METHOD_TREE_FILES`, `MAX_METHOD_TREE_FILE_KIB` or `MAX_METHOD_TREE_TOTAL_KIB`, or a method past `MAX_METHOD_DEPENDENCIES` or `MAX_METHOD_REQUEST_TOTAL_KIB` across its trees, is a **422** `method.package_invalid` whose `reason` names the rule: the standard's tree refusal codes, such as `invalid_tree_path`, `duplicate_key`, `excluded_name` or `path_collision`, with the `path` it refuses, or the runner's own, one per rule and one per limit: `too_many_files`, `file_too_large` and `tree_too_large` for a tree, `too_many_dependencies` and `method_too_large` for a request's trees together, `bundle_too_many_files` and `bundle_too_large` for a `bundle_b64` archive, `manifest_missing`, `manifest_invalid`, `package_name_invalid`, `dependency_address_collision` and `no_bundle`, with the `path` or the `limit` it names. A key that is not a tree path without leaving the tree, empty or holding a backslash or a colon, is `invalid_tree_path`. A path of the tree that would leave its root is the security refusal `security.input_path_refused`, naming the `rule` it broke, `absolute` or `parent_segment`, never the path. A malformed entry, or `dependencies` that do not fit the request, is a **422** `request.invalid` naming the field. A hash entry this runner does not hold is a **422** `request.blobs_missing` whose `missing_blobs` parameter lists the SHA-256 hashes to upload through the blob routes before sending the request again, and one it holds at another size than the entry states a **422** `request.invalid`: the entry's size is the one to correct, since uploading the bytes again would not change the size they are held at. The blob routes answer in the same vocabulary: a body whose SHA-256 is not the one its path names is a **422** `request.invalid` naming the field `body`, one hash listed with two sizes a **422** `request.invalid` naming `blobs`, and a blob past the per-file limit a **413** `request.too_large`. None of them invites a retry, since the same request is refused again.
-The files a request sends in `resources` are checked before the bundle loads and again once it is parsed (see [Pipe Validate](pipe-validate.md#sending-the-files-the-steps-read-resources)). A key that cannot name a file inside the bundle is a **422** `InvalidResourcePath` and a value that is not base64 a **400** `InvalidBase64`, both the API's own refusals; a file none of the bundle's steps names, and files that cannot make one method tree, such as two keys equal once case-folded, are **422** problems with the code `request.invalid`, or `security.input_path_refused` for a path the tree rule refuses, on every route, the diagnostic ones included: they are the request's fault, not the bundle's, and none invites a retry, since the same request is refused again.
+The files a request sends in `resources` are checked before the bundle loads and again once it is parsed (see [Pipe Validate](pipe-validate.md#sending-the-files-the-steps-read-resources)). A key that would leave the bundle is the security refusal `security.input_path_refused`, naming the `rule` it broke; any other key that cannot name a file inside the bundle, two keys naming the same file, more files than `MAX_RESOURCES_PER_REQUEST`, a file none of the bundle's steps names, and files that cannot make one method tree, such as two keys equal once case-folded, are **422** `request.invalid` naming the field `resources`; and a value that is not base64 is a **422** `request.malformed` with the reason `bad_base64`. They answer the same on every route, the diagnostic ones included: they are the request's fault, not the bundle's.
The HTTP status is the source of truth for success vs failure — there is no `success: true/false` field anywhere in the envelope.
Which statuses a given route can actually produce is documented per operation in the [committed OpenAPI artifact](openapi/pipelex-api.openapi.yaml), each as an `application/problem+json` `ProblemDocument`.
-**What is *not* an error status:** an invalid `.mthds` bundle. On the diagnostic routes — `/validate`, `/resolve`, `/codegen`, and `/pipe-io` — a bundle that fails validation is the *successful product* of the call, so it rides a **200** discriminated on `is_valid: false`, carrying the same `validation_errors[]` described above. Non-2xx on those routes is reserved for *no verdict could be produced*. See [Pipe Validate](pipe-validate.md).
+**What is *not* an error status:** an invalid `.mthds` bundle. On the diagnostic routes — `/validate`, `/resolve`, `/codegen`, and `/pipe-io` — a bundle that fails validation is the *successful product* of the call, so it rides a **200** discriminated on `is_valid: false`, carrying the same `errors[]` items described above. Non-2xx on those routes is reserved for *no verdict could be produced*. See [Pipe Validate](pipe-validate.md).
## The `type` URI
@@ -279,13 +276,13 @@ https://docs.pipelex.com/errors/<code> a pipelex. code, such as pipelex.con
Both families are listed on the [Error Codes](../errors/index.md) page, and `title` is the code's title. A Pipelex code's type URI names no documentation version: the documentation site answers it with the code's page in the latest release (see [The pages and the type URI](../contribute/error-registry.md#the-pages-and-the-type-uri)).
-API-authored errors (`ValidationError`, `BadRequest`, `Unauthenticated`, etc.) carry no code, and their `type` is still derived from their name, `https://docs.pipelex.com/latest/errors/<kebab-name>/`, a URL the documentation site sends to the Error Codes index.
+The runner's own refusals carry a code like every other error, so their `type` is their code's page too.
-Before every error carried its code, the `type` of an error the runtime raised was derived from its class in the same way and named a page per class. Those pages are retired, and the documentation site redirects each one to the page of its class's code, or to the Error Codes index when the class is gone or raises no single code, so a stored `type` still leads somewhere useful.
+Before every error carried its code, the `type` of an error was derived from its class or, for a refusal the API authored, from its `error_type`, and named a page per class. Those pages are retired, and the documentation site redirects each one to the page of its class's code, or to the Error Codes index when the class is gone or raises no single code, so a stored `type` still leads somewhere useful.
## Request correlation
-Every response carries `X-Request-ID`. The middleware respects an inbound `X-Request-ID` header if present, otherwise mints one. It also binds that id onto the Pipelex runtime's log context for the duration of the request, so every record emitted underneath carries it as a `request_id` field — the server's own error lines and the runtime's lines from inside a run alike. Both run routes, `POST /v1/execute` and `POST /v1/start`, also put the id on the run's metadata, so when a run is dispatched to a worker, the lines the worker writes while it runs the run's workflow and activities carry the same id. What those lines look like, which fields they carry and where the id does not reach are in [Logging](logging.md).
+Every response carries `X-Request-ID`. The middleware respects an inbound `X-Request-ID` header if present and valid, otherwise mints one, a ULID. A valid id is 1 to 128 ASCII letters, digits, `_` and `-`, the rule a run applies to the id it is handed too (`pipelex.system.job_metadata.is_valid_request_id`): the id is echoed in a header and written into log lines, where a space, a quote or an `=` could forge a field. It also binds that id onto the Pipelex runtime's log context for the duration of the request, so every record emitted underneath carries it as a `request_id` field — the server's own error lines and the runtime's lines from inside a run alike. Both run routes, `POST /v1/execute` and `POST /v1/start`, also put the id on the run's metadata, so when a run is dispatched to a worker, the lines the worker writes while it runs the run's workflow and activities carry the same id. What those lines look like, which fields they carry and where the id does not reach are in [Logging](logging.md).
When opening an issue, include the `request_id` from the response (or response headers) and the timestamp.
@@ -330,7 +327,7 @@ X-Request-ID: 9f2c1ab3-…
}
```
-The `detail` is the human summary; `errors` is the machine-readable list a client maps to per-line diagnostics. Only the run routes answer an invalid bundle with this 422 — on the diagnostic routes the same bundle is a **200 `is_valid: false`** verdict carrying the items whole as `validation_errors` — see [Structured validation errors](#structured-validation-errors) and [Sourcing submitted files](pipe-validate.md).
+The `detail` is the human summary; `errors` is the machine-readable list a client maps to per-line diagnostics. Only the run routes answer an invalid bundle with this 422 — on the diagnostic routes the same bundle is a **200 `is_valid: false`** verdict carrying the same items as `errors` — see [Structured validation errors](#structured-validation-errors) and [Sourcing submitted files](pipe-validate.md).
### 500 — deployment configuration fault
@@ -366,18 +363,62 @@ WWW-Authenticate: Bearer
X-Request-ID: 9f2c1ab3-…
{
- "type": "https://docs.pipelex.com/latest/errors/unauthenticated/",
- "title": "Unauthenticated",
+ "type": "https://mthds.ai/errors/auth.missing_credential",
+ "title": "No credential was sent",
"status": 401,
- "detail": "Missing bearer token.",
- "instance": "/v1/execute",
- "request_id": "9f2c1ab3-…",
- "error_type": "Unauthenticated",
- "error_domain": "input",
- "retryable": false
+ "detail": "This route needs a credential, and the request carried none.",
+ "code": "auth.missing_credential",
+ "domain": "account",
+ "retry": "no",
+ "next_step": {
+ "kind": "check_credentials",
+ "detail": "Send the request with a credential this runtime accepts."
+ },
+ "request_id": "9f2c1ab3-…"
+}
+```
+
+### 422 — two fields the route refuses
+
+```http
+HTTP/1.1 422 Unprocessable Entity
+Content-Type: application/problem+json
+X-Request-ID: 9f2c1ab3-…
+
+{
+ "type": "https://mthds.ai/errors/request.invalid",
+ "title": "The request does not match the route's schema",
+ "status": 422,
+ "detail": "The request's field 'storage_scope' does not match the route's schema.",
+ "code": "request.invalid",
+ "domain": "input",
+ "retry": "no",
+ "next_step": {
+ "kind": "change_input",
+ "detail": "Correct the field 'storage_scope' as the route's schema requires, then send the request again."
+ },
+ "params": { "field": "storage_scope" },
+ "location": { "field": "storage_scope" },
+ "errors": [
+ {
+ "code": "request.invalid",
+ "detail": "The request's field 'storage_scope' does not match the route's schema.",
+ "params": { "field": "storage_scope" },
+ "location": { "field": "storage_scope" }
+ },
+ {
+ "code": "request.invalid",
+ "detail": "The request's field 'analytics_groups' does not match the route's schema.",
+ "params": { "field": "analytics_groups" },
+ "location": { "field": "analytics_groups" }
+ }
+ ],
+ "request_id": "9f2c1ab3-…"
}
```
+The operator view of the same refusal adds `diagnostics`, whose `message` holds the rules each field broke, in the request model's own words, which can quote what the caller sent and so never reach a caller.
+
## Async callbacks (webhook payload)
For [async pipeline runs](pipe-run.md) registering a `callback_url`, the payload delivered to the caller's webhook **does not** use this envelope: it is a completion notice carrying `pipeline_run_id`, the delivery `state` (also sent under the legacy `status` key) and, when results were stored, `result_url`. A failed run adds its problem under an `error` key, so a non-HTTP receiver such as a queue or a log shipper reads the same `code`, `domain`, `retry`, sentences and `location` as the synchronous answer, without an HTTP status.
diff --git a/docs/api-server/index.md b/docs/api-server/index.md
index e61d98583..a5972295f 100644
--- a/docs/api-server/index.md
+++ b/docs/api-server/index.md
@@ -100,7 +100,7 @@ The `AUTH_MODE` environment variable selects how the API authenticates its calle
By default (`AUTH_MODE=none`), the API requires no authentication. This is the default for self-hosted deployments and for running behind an API Gateway that handles auth.
-If you sit this API behind a trusted reverse proxy that authenticates users and forwards the caller identity via the `X-User-Id` header, set `TRUST_FORWARDED_IDENTITY_HEADERS=true` to honor it. The runner is a generic execution engine — it does not own user metadata (email, OAuth subject, auth method), so a single opaque caller id is the entire trusted surface. The value must be a single path-safe segment (`is_safe_user_id`). **Default is off** — without this flag the API ignores `X-User-Id` entirely and the deployment is treated as single-tenant. With it on, a request arriving *without* the header is rejected with `401`: turning the flag on asserts that a proxy authenticates every caller, so a missing id means that proxy is absent, misconfigured or bypassed. Only enable it when your proxy strips any inbound copy of the header before adding its own; otherwise, any external client can spoof user identity by sending it directly.
+If you sit this API behind a trusted reverse proxy that authenticates users and forwards the caller identity via the `X-User-Id` header, set `TRUST_FORWARDED_IDENTITY_HEADERS=true` to honor it. The runner is a generic execution engine — it does not own user metadata (email, OAuth subject, auth method), so a single opaque caller id is the entire trusted surface. The value must be a single path-safe segment (`is_safe_user_id`), and one that is not is refused with a `422` `request.invalid` naming the header. **Default is off** — without this flag the API ignores `X-User-Id` entirely and the deployment is treated as single-tenant. With it on, a request arriving *without* the header is rejected with `401` `auth.missing_credential`, with no `WWW-Authenticate` challenge since the runner reads no bearer token in this mode: turning the flag on asserts that a proxy authenticates every caller, so a missing id means that proxy is absent, misconfigured or bypassed. Only enable it when your proxy strips any inbound copy of the header before adding its own; otherwise, any external client can spoof user identity by sending it directly.
### API Key Authentication
diff --git a/docs/api-server/logging.md b/docs/api-server/logging.md
index e96945e6b..7810672d8 100644
--- a/docs/api-server/logging.md
+++ b/docs/api-server/logging.md
@@ -7,12 +7,12 @@ The server writes structured logs: one JSON object per line, on **stderr**, with
An error response produces exactly one line. A caller mistake:
```json
-{"time": "2026-09-18T13:53:17.919Z", "severity": "WARNING", "logger": "pipelex_api.exception_handlers", "message": "A request ended in an error response", "request_id": "01M2TCP02W04RZG6DTM8AR508C", "url.path": "/v1/models", "error.type": "InvalidModelCategory", "error_domain": "input", "retryable": false, "http.response.status_code": 422, "detail": "Invalid model category. Valid values: extract, img_gen, judgment, llm, search"}
+{"time": "2026-10-17T13:53:17.919Z", "severity": "WARNING", "logger": "pipelex_api.exception_handlers", "message": "A request ended in an error response", "request_id": "01M2TCP02W04RZG6DTM8AR508C", "url.path": "/v1/models", "error.code": "request.invalid", "error.type": "RunnerRequestError", "error_domain": "input", "retryable": false, "http.response.status_code": 422, "error.chain": ["RunnerRequestError"]}
```
-A server fault looks the same at `ERROR`, and carries the traceback under an `exception` key.
+A fault the server has to fix looks the same at `ERROR`, and adds `error.frames`, where the deepest exception of its chain was raised.
-The `message` is the same sentence on every error line, `A request ended in an error response`, whichever failure it reports, so it is the key a query or an alert selects this server's error stream by, following the [log-call conventions](../tools/logging.md#log-call-conventions). Everything about the failure, the HTTP status and the error type included, rides a field of its own, and nothing a caller supplied ever reaches the message: the API's explanation of a refusal rides the `detail` field instead, so a body crafted with newlines or quotes cannot break the line or forge a key. Two layers keep the `detail` value safe to write. Before any sink sees a record, the Pipelex runtime's redaction processor replaces a control character in a field's value with its printable escape, so a newline a caller sent reads as `\n` in `detail`, and replaces a credential it recognises, an `Authorization` header's token or an API key, with `[REDACTED]`. The sink then escapes what it writes, so a quote or an `=` stays inside its value. The processor is configured under `[runtime.log.redaction]` and is on by default.
+The `message` is the same sentence on every error line, `A request ended in an error response`, whichever failure it reports, so it is the key a query or an alert selects this server's error stream by, following the [log-call conventions](../tools/logging.md#log-call-conventions). Everything about the failure, the HTTP status, the code and the error type included, rides a field of its own, and nothing a caller supplied ever reaches the message. **No error line carries an exception's text or its traceback**, whatever the failure: a traceback prints the text of every exception of its chain, and a foreign exception's text, a pydantic `ValidationError`'s or a method function's, can quote a run's inputs or a model's answer. The line names the classes of the chain under `error.chain` and, on an `ERROR` line, where the deepest was raised under `error.frames`, and the operator reads the error's message, cut to a bounded length, in the operator view's `diagnostics` of the response. Two layers keep the values a caller can shape, such as the `url.path`, safe to write. Before any sink sees a record, the Pipelex runtime's redaction processor replaces a control character in a field's value with its printable escape, and replaces a credential it recognises, an `Authorization` header's token or an API key, with `[REDACTED]`. The sink then escapes what it writes, so a quote or an `=` stays inside its value. The processor is configured under `[runtime.log.redaction]` and is on by default.
## The fields a line carries
@@ -38,12 +38,14 @@ The remaining keys are what the error handlers attach to an error line. The ones
| --- | --- |
| `url.path` | The request's URL path |
| `http.response.status_code` | The HTTP status actually sent, including any API-level override |
-| `error.code` | The code of the problem the response carries, on a failure the runtime raised: the body's `code` |
-| `error.type` | On a failure the runtime raised, the class of the exception that escaped, which for an exception that is not a Pipelex error is that exception's own class; on an API-authored failure, the `ErrorType` name the body carries as `error_type` |
+| `error.code` | The code of the problem the response carries: the body's `code` |
+| `error.type` | The class of the exception that escaped, which for an exception that is not a Pipelex error is that exception's own class, and for a failure a route received as a value the class its problem names. A refusal the framework raised, FastAPI's `RequestValidationError`, Starlette's `ClientDisconnect` or an `HTTPException`, is answered by one of the runner's refusals standing in for it, `RunnerRequestError` or `RunnerAuthError`, which `error.type` names and which `error.chain` follows with the framework's class |
+| `error.chain` | The classes of the exceptions the failure was raised from or while handling, by name, outermost first, as a traceback would print them, without their text |
+| `error.frames` | On an `ERROR` line alone, a fault the server has to fix, where the deepest exception of the chain was raised, as `file:line in function` from the outermost frame inward, without the source lines |
| `error_domain` | `input`, `config` or `runtime` — who fixes it. On a failure the runtime raised it is read from the problem's `domain`, the `input` and `method` domains reading `input`, and the `account` and `operator` domains `config` |
| `error_category` | The inference error category, on a failure the cause chain of which carries one |
-| `retryable` | Whether a blind retry can help: the problem's `retry` is `yes`, or the API-authored body's `retryable` |
-| `detail` | The API's own explanation, the same text the response body carries — on an API-authored failure only, see below |
+| `retryable` | Whether a blind retry can help: the problem's `retry` is `yes` |
+| `error.params.<name>` | Each parameter of the problem that the registry declares operator-only, one key per parameter, such as `error.params.component` for the setting a `runtime.misconfigured` names, or `error.params.dependency` for the service a `runtime.unavailable` could not reach. Such a parameter names the runtime's own configuration or one of its components, never a caller's content, and a caller's response leaves it out with the rest of the `diagnostics`, so the line is where the operator reads it whichever view the response took |
| `user.id` | The authenticated caller, when auth bound one. An identity the server refused, a token's `user_id` claim or a forwarded `X-User-Id` that is not a path-safe segment, is never written under it: the warning about the refusal carries the claim's type as `claim_type`, and no value at all for the header |
| `pipe_code` | The pipe the request named, on a run route whose body parsed |
| `pipeline_run_id` | The run the request named, on a run route whose body parsed |
@@ -65,13 +67,13 @@ The record took these keys when the server's lines were brought to the log-call
| `provider` | `backend_name` |
| `model` | `model_handle` |
-The other keys, `error_domain`, `error_category`, `retryable`, `detail`, `pipe_code`, `pipeline_run_id`, `provider_status_code` and `provider_request_id`, kept their names. `error.code` came later, with the problem document.
+The other keys, `error_domain`, `error_category`, `retryable`, `pipe_code`, `pipeline_run_id`, `provider_status_code` and `provider_request_id`, kept their names. `error.code` came later, with the problem document.
-`detail` and `error.code` are the two fields whose presence follows the failure's origin rather than the request's shape. A failure this API authored itself — a validation error, an unknown model category — carries `detail` on the record and no `error.code`. A failure the runtime raised, which is every domain error, every run failure and the catch-all, carries `error.code` and no `detail`: its record is built from the problem's operator view, whichever view the response carried, so `error.type` names the class of the error behind it, and the sentence the response carried is the code's, which `error.code` already names. A `5xx` from that path carries the traceback, and a `4xx` none. Build an operator query on `error.code` or `error.type`, with `url.path`, rather than on `detail`.
+Every error line carries `error.code`, since every failure, the runner's own refusals included, is answered by a problem with a registry code. The record is built from the problem's operator view, whichever view the response carried, so `error.type` names the class of the error behind it, and the sentence the response carried is the code's, which `error.code` already names. Build an operator query on `error.code` or `error.type`, with `url.path`. The error's message, which can quote what the caller sent or a foreign exception's text, never rides the line: it rides the operator view's `diagnostics` alone, which only a request the operator authenticated reads in its response (`AUTH_MODE=api_key`, or a trusted proxy's forwarded identity). A request authenticated by a caller's token reads the caller view, so for it the line is the operator's whole account: the code, the classes of the chain, the frames of a fault the server has to fix and the operator-only parameters. Two keys the line carried before the runner's refusals took codes are gone: `detail`, the explanation an API-authored refusal wrote, which `error.code` replaces, and the `exception` key holding a `5xx`'s traceback, which `error.chain` and `error.frames` replace without any exception's text.
Every field in that table is a **record attribute**, which is a different thing from the message. A structured sink — `json` here, and the OTLP sink — writes them beside the message as keys. The Rich console sink shows them after the message as a `key=value` suffix, each value on one line and cut short when long, a handled exception's `error.message` at a far more generous length, and leaves out the run identifiers (`request_id`, `pipeline_run_id`), which a person at a terminal does not need on every line, so `A request ended in an error response` is followed by the path, the status, the error type and the rest of the fields above. That rendering is for a person reading a terminal; keep `sink = "json"` wherever the lines are read by anything else.
-Disposition follows the HTTP status, not the error domain: a `4xx` is a caller mistake and logs at `WARNING` without a traceback; a `5xx` is a server fault and logs at `ERROR` with one. See [Error Responses](error-responses.md) for the response side of the same failure.
+The level says who has to act, read from the HTTP status and from the domain of the code, the registry's answer to who must act. A `4xx` is the caller's to act on, a mistake or a benign conflict, and logs at `WARNING`. A `5xx` logs at `ERROR`, with `error.frames`, only when the server has something to fix: its code's domain is `runtime` or `operator`. A `501` logs at `WARNING` without frames whatever its domain, because it states that this deployment does not offer what the request asks for, custom Python without a sandbox, `/v1/start` on a blocking-only orchestrator, a model it serves no backend for: nothing is broken, and any caller could fill the error-rate alerts by asking again. A `5xx` whose code's domain is the caller's, `input`, `method` or `account`, such as a webhook receiver of the caller's own refusing a delivery, logs at `WARNING` too. A request no route serves, a `404` for its path or a `405` for its method, logs at `DEBUG`: scanners probe for such paths by the thousand, and nobody has anything to do about them. See [Error Responses](error-responses.md) for the response side of the same failure.
## Security events
@@ -81,7 +83,7 @@ A request a security rule refused writes one more line beside its error line: th
{"time": "2026-10-17T09:12:03.512Z", "severity": "WARNING", "logger": "pipelex.errors.security_event", "message": "A security rule refused a request", "request_id": "01M2TCP02W04RZG6DTM8AR508C", "event.name": "pipelex.security.refusal", "error.code": "security.input_url_refused", "error.domain": "input", "error.type": "UriReadRefusedError", "security.target": "url", "security.target_class": "scheme", "run.extras.org_id": "org_abc"}
```
-Its keys name the refusal and never its content: the refusal's code under `error.code`, the code's domain under `error.domain`, the class of the error under `error.type`, the kind of thing refused under `security.target`, the class of destination under `security.target_class` when the rule could tell it, the run and the request under `pipeline_run_id` and `request_id`, and each of the run's extras, the body's `analytics_groups`, under a key of its own, `run.extras.<key>`. Never the URL, the path, the template or an input value, which are the caller's content or the method's. The Pipelex documentation's [error model](../under-the-hood/error-model.md#security-refusals-and-the-security-event) lists every value.
+Its keys name the refusal and never its content: the refusal's code under `error.code`, the code's domain under `error.domain`, the class of the error under `error.type`, the kind of thing refused under `security.target`, the class of destination under `security.target_class` when the rule could tell it, the run and the request under `pipeline_run_id` and `request_id`, and each of the labels the body names as `analytics_groups`, the run's extras, under a key of its own, `run.extras.<key>`. The labels are read as soon as a JSON body is parsed, before any of its fields is refused, on every route, so a diagnostic route that runs nothing, `/validate`, `/resolve`, `/codegen` or `/pipe-io`, names whose request it refused as a run route does; labels the runtime's own rules refuse are never written. Never the URL, the path, the template or an input value, which are the caller's content or the method's. The Pipelex documentation's [error model](../under-the-hood/error-model.md#security-refusals-and-the-security-event) lists every value.
The server writes it for the refusals its own boundary decides too, which keep the response they always had: a run body carrying a reserved object key (`pipelex.security.reserved_key`, `security.target` `object_key`), a callback URL whose scheme is not http or https or whose host is a loopback, private, link-local or cloud metadata address (`security.input_url_refused`, with the class of destination), and a resource path or a key of a method tree, `files` or a `bundle_b64` member, that leaves the method: absolute, naming a drive or a network share, or climbing out with a `..` segment, read with either separator, so `..\secrets\key.pem`, `C:/Windows/win.ini` and `\\server\share` are among them (`security.input_path_refused`). A refusal of the shape of a field, an empty callback URL, one with no scheme or no host, or a path that is empty or holds an empty segment, a backslash or a colon, is the caller's mistake and writes no event, under `resources` as under `files`. The event never carries a `pipeline_run_id` a body names: before any run exists, that id is the caller's claim.
@@ -116,6 +118,16 @@ pipelex = "INFO"
To change any of this for a deployment, mount a `pipelex_override.toml` into `/root/.pipelex/` with just the keys you want different — see [Configuration](configuration.md#providing-your-own-configuration-to-docker). Note that replacing the whole config directory, which that page documents as Option 2, drops the shipped `pipelex.toml` along with the three keys above and silently returns the server to Pipelex's terminal-facing defaults; a layered override does not.
+## Blob store lines
+
+A file a request names by its hash is read from the runner's blob store and checked against that hash. Bytes that do not hash to it, or are not the size the store holds the blob at, are a damaged object in the deployment's storage, and the request is answered `500` `pipelex.storage.damaged`, whose verdict is not to retry, since a retry reads the same object (see [Error Responses](error-responses.md)). Beside the request's error line, the store writes one line at `ERROR` naming the object, the one place the operator reads which object to remove, after which the blob is uploaded again:
+
+```json
+{"time": "2026-10-17T10:41:09.204Z", "severity": "ERROR", "logger": "pipelex_api.blob_store", "message": "Stored blob bytes do not match their hash", "request_id": "01M2TCP02W04RZG6DTM8AR508C", "blob_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "blob_size_bytes": 14, "read_size_bytes": 14, "storage_scheme": "s3"}
+```
+
+Its keys are the blob's hash under `blob_sha256`, the size the store holds it at under `blob_size_bytes`, the size of the bytes read under `read_size_bytes`, and the kind of storage under `storage_scheme`, `null` for a storage plugin whose kind the registry does not list. Never the bytes themselves, which are a caller's file.
+
## Uvicorn's own lines
-Uvicorn logs through its own handlers, not through the sink above, so its startup banner and its access log are plain text rather than JSON: the banner on stderr, the access log on stdout. Pass `--no-access-log` to turn the access log off, which is what the hosted deployment does; configure uvicorn's `--log-config` if you want its lines structured too.
+Uvicorn logs through its own handlers, not through the sink above, so its startup banner and its access log are plain text rather than JSON: the banner on stderr, the access log on stdout. Uvicorn also logs, with its traceback, any exception that leaves the app it runs, and Starlette's own catch-all raises the exception it answered again for that purpose; the server stops every exception there (`AnsweredErrorBarrier` in `pipelex_api/exception_handlers.py`), so uvicorn never writes an exception's text. The error line above stays the one record of a failure the catch-all answered, even one that ended a response already streaming, since Starlette runs the catch-all then too. A failure no handler recorded, the catch-all's own failure while a response was streaming, or the server's failure to send the answer the barrier built, such as to a client already gone, is written at `ERROR` before it is dropped, as `A request failed after its response had started`, with `url.path`, the status already sent under `http.response.status_code`, absent when the catch-all failed before any status was sent, and `error.type` and `error.chain` naming its classes, never any exception's text. No response answers it: the status and part of the body had already left. Pass `--no-access-log` to turn the access log off, which is what the hosted deployment does; configure uvicorn's `--log-config` if you want its lines structured too.
diff --git a/docs/api-server/models.md b/docs/api-server/models.md
index 22cecf081..7616eecf5 100644
--- a/docs/api-server/models.md
+++ b/docs/api-server/models.md
@@ -13,7 +13,7 @@ Two routes tell a client about the models a method may name on this runner: the
The MTHDS Protocol's `models` operation, tagged `x-mthds-protocol` in the [OpenAPI artifact](openapi/pipelex-api.openapi.yaml). It answers the protocol's model deck: a flat `models` list of the deck's presets, each a `{name, type}` entry whose `type` is one of the protocol's model categories, plus this implementation's routing extensions, `aliases` and `waterfalls`, keyed by category because the same alias name exists in several categories.
-The optional `type` query parameter filters the deck to one category: `llm`, `extract`, `img_gen`, `search` or `judgment`. It takes a single value, so a repeated `type` is a `422` `ValidationError`, and an unknown or empty one is a `422` `InvalidModelCategory`.
+The optional `type` query parameter filters the deck to one category: `llm`, `extract`, `img_gen`, `search` or `judgment`. It takes a single value, so a repeated `type`, and an unknown or empty one, is a `422` `request.invalid` naming the field `type`.
## Check a model reference
@@ -118,12 +118,11 @@ A preset name asked under the alias sigil:
### Refusals
-A request the route cannot produce a verdict for is a `422` `application/problem+json` in the `input` error domain, carrying no verdict:
+A request the route cannot produce a verdict for is a `422` `application/problem+json` with the code `request.invalid`, carrying no verdict, whose `field` parameter names the query parameter it refuses:
-| Cause | `error_type` |
+| Cause | `field` |
|---|---|
-| `reference` missing or given more than once, or `type` given more than once | `ValidationError` |
-| `reference` blank once trimmed, a sigil or namespace with nothing after it, or longer than 199 characters | `InvalidModelReference` |
-| `type` unknown or empty | `InvalidModelCategory` |
+| `reference` missing or given more than once, blank once trimmed, a sigil or namespace with nothing after it, or longer than 199 characters | `reference` |
+| `type` given more than once, unknown or empty | `type` |
A reference that parses and resolves nowhere is never refused: it is the `not_found` verdict, which is the successful product of the call. See [Error Responses](error-responses.md) for the problem document's shape.
diff --git a/docs/api-server/openapi/pipelex-api.openapi.yaml b/docs/api-server/openapi/pipelex-api.openapi.yaml
index 777fefd66..8737f71b7 100644
--- a/docs/api-server/openapi/pipelex-api.openapi.yaml
+++ b/docs/api-server/openapi/pipelex-api.openapi.yaml
@@ -67,8 +67,9 @@ paths:
schema:
$ref: '#/components/schemas/PipelexVersionInfo'
'500':
- description: A failure the caller cannot fix (a missing env var, a bad TOML override, a backend fault), or an unexpected
- error answered as `runtime.unexpected`. Report the `request_id`.
+ description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
+ a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
+ Report the `request_id`.'
content:
application/problem+json:
schema:
@@ -85,15 +86,17 @@ paths:
The body is the blob''s bytes and nothing else. A target whose signature does not hold, or that has expired, is a
- 403 `BlobUploadNotAuthorized`, as is a query that is not one this runner signs, such as an expiry that is not a
+ 403 `auth.forbidden` whose `requirement` is a signed upload target, as is a query that is not one this runner signs,
- decimal integer; a body past `MAX_METHOD_TREE_FILE_KIB` a 422 `MethodTreeTooLarge`; and a body whose SHA-256 is not
+ such as an expiry that is not a decimal integer; a body past `MAX_METHOD_TREE_FILE_KIB` a 413 `request.too_large`;
- the path''s a 422 `BlobMismatch`. A blob is never changed: uploading bytes the runner already holds answers 204 and
+ and a body whose SHA-256 is not the path''s a 422 `request.invalid` naming the body. A blob is never changed:
- changes nothing, and uploading bytes whose hash names an object of another size, which only damaged storage could
+ uploading bytes the runner already holds answers 204 and changes nothing, and uploading bytes whose hash names an
- hold, is a 500 `BlobStoreCorrupted` that leaves the object as it is.'
+ object of another size, which only damaged storage could hold, is a 500 `pipelex.storage.damaged` that leaves the
+
+ object as it is.'
operationId: put_blob_v1_blobs__sha256__put
parameters:
- name: sha256
@@ -139,30 +142,37 @@ paths:
'204':
description: Successful Response
'403':
- description: '`BlobUploadNotAuthorized` — the upload does not carry the signed query an upload target of `POST /v1/blobs/missing`
- names, its signature does not hold for this hash and scope, or it has expired. Ask `POST /v1/blobs/missing` again
- for a fresh target.'
+ description: '`auth.forbidden`, whose `params.requirement` is `signed_upload_target` — the upload does not carry
+ the signed query an upload target of `POST /v1/blobs/missing` names, its signature does not hold for this hash
+ and scope, or it has expired. Ask `POST /v1/blobs/missing` again for a fresh target.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
- description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
+ description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
+ byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
+ both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
- description: 'The request could not be processed: a malformed body, a field failing validation, or a pipelex error
- whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the diagnostic
- routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
+ description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
+ refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
+ or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
+ error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
+ diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
- description: A failure the caller cannot fix (a missing env var, a bad TOML override, a backend fault), or an unexpected
- error answered as `runtime.unexpected`. Report the `request_id`.
+ description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
+ a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
+ Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
+ blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
+ verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
content:
application/problem+json:
schema:
@@ -307,13 +317,14 @@ paths:
starting with a dot), and each value is the file''s UTF-8 text, `{"base64": ...}` holding its bytes, or
`{"sha256": ..., "size": ...}` naming bytes this runner already holds (uploaded with `POST /v1/blobs/missing`
then `PUT /v1/blobs/{sha256}`). The map is read from the request''s JSON text: a key given twice, a key
- the membership rule keeps out of every tree (`.mthds/` included), colliding keys and a malformed entry
- are a 422 `InvalidMethodFiles` whose `tree_refusal` names the code and the paths, and hash entries the
- runner does not hold are one 422 `MissingBlobs` whose `missing_blobs` lists every such hash. Its `.mthds`
- files are the method''s bundles and every other file is one a step may read, such as a `PipeDocGen` template
- or a `PipeFunc` module. With no `pipe_code`, the run starts at the `main_pipe` of the `METHODS.toml` at
- the tree''s root, or else at the one `main_pipe` its bundles declare. Custom `.py` is only honored on
- a sandbox-hosted deployment.'
+ the membership rule keeps out of every tree (`.mthds/` included) and colliding keys are a 422 `method.package_invalid`
+ whose `reason` is the refusal''s code and whose `path` names the first path, a key leaving the tree is
+ a 422 `security.input_path_refused`, a malformed entry is a 422 `request.invalid`, and hash entries the
+ runner does not hold are one 422 `request.blobs_missing` whose `missing_blobs` parameter lists every such
+ hash. Its `.mthds` files are the method''s bundles and every other file is one a step may read, such as
+ a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`, the run starts at the `main_pipe`
+ of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its bundles declare. Custom
+ `.py` is only honored on a sandbox-hosted deployment.'
dependencies:
anyOf:
- additionalProperties:
@@ -374,7 +385,8 @@ paths:
any other plugin-provided token are accepted; an unregistered token is refused at dispatch. The delivery
axis (blocking vs fire-and-forget) is endpoint-set, never requestable. Honored ONLY when the deployment
sets `allow_request_orchestration_mode_override = true` in its `api.toml`; otherwise a token that differs
- from the deployment default is refused with a 403. Omit it to use the deployment default.'
+ from the deployment default is refused with a 422 `pipelex.deployment.orchestration_override_forbidden`.
+ Omit it to use the deployment default.'
storage_scope:
anyOf:
- type: string
@@ -431,11 +443,13 @@ paths:
schema:
$ref: '#/components/schemas/PipelexApiExecuteResponse'
'401':
- description: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
- or `AUTH_MODE=jwt`).
+ description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
+ or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
+ or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
- description: Authentication challenge — always `Bearer`.
+ description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
+ or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
@@ -443,33 +457,37 @@ paths:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
- description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
+ description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
+ byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
+ both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
- description: 'The request could not be processed: a malformed body, a field failing validation, or a pipelex error
- whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the diagnostic
- routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
+ description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
+ refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
+ or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
+ error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
+ diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
- description: A failure the caller cannot fix (a missing env var, a bad TOML override, a backend fault), or an unexpected
- error answered as `runtime.unexpected`. Report the `request_id`.
+ description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
+ a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
+ Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
+ blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
+ verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'403':
- description: 'A deployment-policy refusal: `OrchestrationModeOverrideForbidden` — the request asked for an `orchestration_mode`
- this deployment does not allow overriding per request (`allow_request_orchestration_mode_override = false`); `CustomCodeRequiresSandbox`
- — the method (a bundle, or a fetched `method_ref` package) ships custom Python and this deployment is not sandbox-hosted;
- or `ReadScopeForbidden` — on a `jwt` deployment, the request sent a `read_scope` that does not lie under the caller''s
- own `user_id`. The refusal of a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`,
- is a 422 instead, since the method''s author changes it.'
+ description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
+ the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
+ may read.'
content:
application/problem+json:
schema:
@@ -493,6 +511,15 @@ paths:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
+ '501':
+ description: '`pipelex.deployment.custom_code_requires_sandbox` — the method (a bundle, or a fetched `method_ref`
+ package, as `params.origin` says) ships custom Python and this deployment is not sandbox-hosted. The refusal of
+ a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`, is a 422 instead,
+ since the method''s author changes it.'
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/ProblemDocument'
x-mthds-protocol: true
/v1/start:
post:
@@ -523,9 +550,9 @@ paths:
`workflow_id`. On the orchestrator-agnostic base (`orchestration_mode = "direct"`, the default)
- the in-process orchestrator is blocking-only, so `/start` is HONEST: it refuses with a `400`
+ the in-process orchestrator is blocking-only, so `/start` is HONEST: it refuses with a `501`
- (`StartRequiresAsyncOrchestration`) — use `/execute` — rather than silently blocking and acking.
+ (`runtime.unsupported`) — use `/execute` — rather than silently blocking and acking.
The completion callback (`callback_urls` / storage delivery) fires on the async path.'
operationId: start_v1_start_post
@@ -641,13 +668,14 @@ paths:
starting with a dot), and each value is the file''s UTF-8 text, `{"base64": ...}` holding its bytes, or
`{"sha256": ..., "size": ...}` naming bytes this runner already holds (uploaded with `POST /v1/blobs/missing`
then `PUT /v1/blobs/{sha256}`). The map is read from the request''s JSON text: a key given twice, a key
- the membership rule keeps out of every tree (`.mthds/` included), colliding keys and a malformed entry
- are a 422 `InvalidMethodFiles` whose `tree_refusal` names the code and the paths, and hash entries the
- runner does not hold are one 422 `MissingBlobs` whose `missing_blobs` lists every such hash. Its `.mthds`
- files are the method''s bundles and every other file is one a step may read, such as a `PipeDocGen` template
- or a `PipeFunc` module. With no `pipe_code`, the run starts at the `main_pipe` of the `METHODS.toml` at
- the tree''s root, or else at the one `main_pipe` its bundles declare. Custom `.py` is only honored on
- a sandbox-hosted deployment.'
+ the membership rule keeps out of every tree (`.mthds/` included) and colliding keys are a 422 `method.package_invalid`
+ whose `reason` is the refusal''s code and whose `path` names the first path, a key leaving the tree is
+ a 422 `security.input_path_refused`, a malformed entry is a 422 `request.invalid`, and hash entries the
+ runner does not hold are one 422 `request.blobs_missing` whose `missing_blobs` parameter lists every such
+ hash. Its `.mthds` files are the method''s bundles and every other file is one a step may read, such as
+ a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`, the run starts at the `main_pipe`
+ of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its bundles declare. Custom
+ `.py` is only honored on a sandbox-hosted deployment.'
dependencies:
anyOf:
- additionalProperties:
@@ -727,7 +755,8 @@ paths:
any other plugin-provided token are accepted; an unregistered token is refused at dispatch. The delivery
axis (blocking vs fire-and-forget) is endpoint-set, never requestable. Honored ONLY when the deployment
sets `allow_request_orchestration_mode_override = true` in its `api.toml`; otherwise a token that differs
- from the deployment default is refused with a 403. Omit it to use the deployment default.'
+ from the deployment default is refused with a 422 `pipelex.deployment.orchestration_override_forbidden`.
+ Omit it to use the deployment default.'
storage_scope:
anyOf:
- type: string
@@ -782,11 +811,13 @@ paths:
schema:
$ref: '#/components/schemas/PipelexApiStartResponse'
'401':
- description: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
- or `AUTH_MODE=jwt`).
+ description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
+ or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
+ or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
- description: Authentication challenge — always `Bearer`.
+ description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
+ or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
@@ -794,40 +825,37 @@ paths:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
- description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
+ description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
+ byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
+ both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
- description: 'The request could not be processed: a malformed body, a field failing validation, or a pipelex error
- whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the diagnostic
- routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
+ description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
+ refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
+ or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
+ error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
+ diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
- description: A failure the caller cannot fix (a missing env var, a bad TOML override, a backend fault), or an unexpected
- error answered as `runtime.unexpected`. Report the `request_id`.
- content:
- application/problem+json:
- schema:
- $ref: '#/components/schemas/ProblemDocument'
- '400':
- description: '`StartRequiresAsyncOrchestration` — this deployment''s orchestrator is blocking-only and cannot honor
- fire-and-forget delivery. Use `POST /execute` instead.'
+ description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
+ a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
+ Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
+ blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
+ verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'403':
- description: 'A deployment-policy refusal: `OrchestrationModeOverrideForbidden` — the request asked for an `orchestration_mode`
- this deployment does not allow overriding per request (`allow_request_orchestration_mode_override = false`); `CustomCodeRequiresSandbox`
- — the method (a bundle, or a fetched `method_ref` package) ships custom Python and this deployment is not sandbox-hosted;
- or `ReadScopeForbidden` — on a `jwt` deployment, the request sent a `read_scope` that does not lie under the caller''s
- own `user_id`. The refusal of a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`,
- is a 422 instead, since the method''s author changes it.'
+ description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
+ the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
+ may read.'
content:
application/problem+json:
schema:
@@ -847,8 +875,9 @@ paths:
schema:
$ref: '#/components/schemas/ProblemDocument'
'501':
- description: '`runtime.unsupported` — this deployment does not provide async pipeline execution. Permanent under
- the current deployment; do not retry.'
+ description: '`runtime.unsupported` — this deployment cannot honor fire-and-forget delivery: its orchestrator is
+ blocking-only, or its async execution is not enabled. Permanent under the current deployment; use `POST /execute`
+ instead. Or `pipelex.deployment.custom_code_requires_sandbox`, as on `POST /execute`.'
content:
application/problem+json:
schema:
@@ -877,21 +906,23 @@ paths:
\ fields, keyed like\n `pipe_io_contracts`; without a token the matching field is absent and the body is\n byte-identical\
\ to a request that omits `views`. They are separate tokens because they answer\n separate questions — a caller building\
\ a fill-in form wants the inputs, a caller rendering a\n result or registering a tool signature with a return type\
- \ wants the output.\n- **Invalid verdict (200, `is_valid: false`):** the `InvalidReport` arm — `validation_errors[]`\n\
- \ (the structured per-error diagnostics, built by pipelex's one shared builder, incl. one\n located `dry_run` item\
- \ per pipe whose dry run failed) + `message`, with the structural artifacts absent. The runner\n returns this as\
- \ a value (a `BundleValidationFailure` with `validation_errors`) regardless of backend — the\n in-process arm from\
- \ the bundle's `ValidateBundleError`, the dispatched arm recovered from the\n worker — so the route maps it to a\
- \ 200 by matching validation diagnostics, never by catching an\n exception. A returned failure without validation\
+ \ wants the output.\n- **Invalid verdict (200, `is_valid: false`):** the `InvalidReport` arm — `errors[]`, one problem\
+ \ item per\n error with its own code (incl. one located item per pipe whose dry run failed, with the failure's code),\
+ \ the\n items of the verdict's problem — + `message`, with the structural artifacts absent. The runner\n returns\
+ \ this as a value (a `BundleValidationFailure` with validation items) regardless of backend — the\n in-process arm\
+ \ from the bundle's `ValidateBundleError`, the dispatched arm recovered from the\n worker — so the route maps it\
+ \ to a 200 by matching validation diagnostics, never by catching an\n exception. A returned failure without validation\
\ diagnostics is a backend, configuration or runtime\n fault, and its problem is answered as every raised failure's\
- \ is.\n- **No verdict (non-2xx):** a malformed request body, an `mthds_sources` length mismatch, or\n both/neither\
- \ of `mthds_contents` / `method_ref` is a request-shape **422**; a forbidden\n `orchestration_mode` override is a\
- \ **403**; a host-wiring programmer error or a genuine\n orchestrator fault is a **5xx**; auth is **401/403**. A\
- \ `method_ref` **resolution failure**\n is also a no-verdict condition — never an `is_valid: false`: each answers\
- \ the status its\n code declares, such as a **422** for a malformed reference, a **502** for a failed fetch, a\n\
- \ **404** for no matching package in the repository and a **422** for the method's Python\n structure classes, and\
- \ the custom-code sandbox gate a **403**. All are\n `application/problem+json` rendered by the global handlers in\n\
- \ `pipelex_api.exception_handlers` — routes never shape them."
+ \ is.\n- **Either arm:** a member with no value is absent rather than `null`, at the arm's top level and in its\n\
+ \ problem items; the structured artifacts of the valid arm keep their own serialization.\n- **No verdict (non-2xx):**\
+ \ a malformed request body, an `mthds_sources` length mismatch, or\n both/neither of `mthds_contents` / `method_ref`\
+ \ is a request-shape **422**, and so is a forbidden\n `orchestration_mode` override; a host-wiring programmer error\
+ \ or a genuine orchestrator fault is a\n **5xx**; auth is **401/403**. A `method_ref` **resolution failure** is also\
+ \ a no-verdict condition —\n never an `is_valid: false`: each answers the status its code declares, such as a **422**\
+ \ for a\n malformed reference, a **502** for a failed fetch, a **404** for no matching package in the\n repository\
+ \ and a **422** for the method's Python structure classes, and the custom-code sandbox gate\n a **501**. All are\
+ \ `application/problem+json` documents carrying a registry `code`, rendered by the\n global handlers in `pipelex_api.exception_handlers`\
+ \ — routes never shape them."
operationId: validate_mthds_v1_validate_post
requestBody:
content:
@@ -915,11 +946,13 @@ paths:
'True': '#/components/schemas/ValidReport'
'False': '#/components/schemas/InvalidReport'
'401':
- description: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
- or `AUTH_MODE=jwt`).
+ description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
+ or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
+ or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
- description: Authentication challenge — always `Bearer`.
+ description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
+ or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
@@ -927,33 +960,37 @@ paths:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
- description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
+ description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
+ byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
+ both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
- description: 'The request could not be processed: a malformed body, a field failing validation, or a pipelex error
- whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the diagnostic
- routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
+ description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
+ refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
+ or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
+ error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
+ diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
- description: A failure the caller cannot fix (a missing env var, a bad TOML override, a backend fault), or an unexpected
- error answered as `runtime.unexpected`. Report the `request_id`.
+ description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
+ a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
+ Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
+ blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
+ verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'403':
- description: 'A deployment-policy refusal: `OrchestrationModeOverrideForbidden` — the request asked for an `orchestration_mode`
- this deployment does not allow overriding per request (`allow_request_orchestration_mode_override = false`); `CustomCodeRequiresSandbox`
- — the method (a bundle, or a fetched `method_ref` package) ships custom Python and this deployment is not sandbox-hosted;
- or `ReadScopeForbidden` — on a `jwt` deployment, the request sent a `read_scope` that does not lie under the caller''s
- own `user_id`. The refusal of a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`,
- is a 422 instead, since the method''s author changes it.'
+ description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
+ the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
+ may read.'
content:
application/problem+json:
schema:
@@ -965,6 +1002,15 @@ paths:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
+ '501':
+ description: '`pipelex.deployment.custom_code_requires_sandbox` — the method (a bundle, or a fetched `method_ref`
+ package, as `params.origin` says) ships custom Python and this deployment is not sandbox-hosted. The refusal of
+ a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`, is a 422 instead,
+ since the method''s author changes it.'
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/ProblemDocument'
x-mthds-protocol: true
/v1/resolve:
post:
@@ -978,12 +1024,13 @@ paths:
\ the MTHDS standard specifies as the Library Crate Format. It runs no dry-run sweep —\nrunnability is `/validate`'s\
\ vocabulary.\n\nResponse contract (the `/validate` discipline):\n\n- **Valid verdict (200, `is_valid: true`):** the\
\ crate on the valid arm.\n- **Invalid verdict (200, `is_valid: false`):** the library could not be parsed, loaded,\
- \ or\n validated — `validation_errors[]` from pipelex's one shared builder.\n- **No verdict (non-2xx):** a malformed\
- \ request body (neither or both method selectors) is a\n request-shape 422; a `files` map that is not a method tree\
- \ is a 422 `InvalidMethodFiles`, and\n hash entries this runner does not hold one 422 `MissingBlobs`; custom Python\
- \ on a deployment\n that is not sandbox-hosted, or a Python structure class, is a 403; a registry-form `method_ref`\n\
- \ is a 501 until server-side method registry resolution exists; auth is 401/403; server fault is\n 5xx. All RFC\
- \ 7807 `application/problem+json` via the global handlers."
+ \ or\n validated — `errors[]`, one problem item per error.\n- **No verdict (non-2xx):** a malformed request body\
+ \ (neither or both method selectors) is a\n request-shape 422 `request.invalid`; a `files` map that is not a method\
+ \ tree is a 422\n `method.package_invalid`, and hash entries this runner does not hold a 422\n `request.blobs_missing`;\
+ \ custom Python on a deployment that is not sandbox-hosted is a 501\n `pipelex.deployment.custom_code_requires_sandbox`,\
+ \ and a Python structure class a 422\n `pipelex.deployment.python_structures_refused`; a registry-form `method_ref`\
+ \ is a 422\n `request.unsupported` until server-side method registry resolution exists; auth is 401/403;\n server\
+ \ fault is 5xx. All `application/problem+json` documents with a registry `code`, via the\n global handlers."
operationId: resolve_mthds_v1_resolve_post
requestBody:
content:
@@ -1007,11 +1054,13 @@ paths:
'True': '#/components/schemas/ResolveValidReport'
'False': '#/components/schemas/CrateInvalidReport'
'401':
- description: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
- or `AUTH_MODE=jwt`).
+ description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
+ or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
+ or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
- description: Authentication challenge — always `Bearer`.
+ description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
+ or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
@@ -1019,32 +1068,37 @@ paths:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
- description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
+ description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
+ byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
+ both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
- description: 'The request could not be processed: a malformed body, a field failing validation, or a pipelex error
- whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the diagnostic
- routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
+ description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
+ refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
+ or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
+ error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
+ diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
- description: A failure the caller cannot fix (a missing env var, a bad TOML override, a backend fault), or an unexpected
- error answered as `runtime.unexpected`. Report the `request_id`.
+ description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
+ a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
+ Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
+ blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
+ verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'403':
- description: 'The run routes'' Python policy, applied to the method''s tree: `CustomCodeRequiresSandbox` — the method
- (sent in `files`, or a fetched `method_ref` package) ships custom Python and this deployment is not sandbox-hosted.
- Also `ReadScopeForbidden` — on a `jwt` deployment, the request sent a `read_scope` that does not lie under the
- caller''s own `user_id`. The refusal of a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`,
- is a 422 instead, since the method''s author changes it.'
+ description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
+ the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
+ may read.'
content:
application/problem+json:
schema:
@@ -1057,9 +1111,10 @@ paths:
schema:
$ref: '#/components/schemas/ProblemDocument'
'501':
- description: '`MethodRefNotSupported` — the request selected its method by a **registry-form** `method_ref` (not
- a `github.com/...` address), and no server-side method registry resolves those yet. Use an address-form reference
- or send the method''s tree in `files` instead.'
+ description: '`pipelex.deployment.custom_code_requires_sandbox` — the method (a bundle, or a fetched `method_ref`
+ package, as `params.origin` says) ships custom Python and this deployment is not sandbox-hosted. The refusal of
+ a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`, is a 422 instead,
+ since the method''s author changes it.'
content:
application/problem+json:
schema:
@@ -1078,13 +1133,14 @@ paths:
\ `is_runnable`, and `files` when\n `include_files` is true.\n- **Invalid verdict (200, `is_valid: false`):** the\
\ closure could not be parsed, loaded, or\n statically validated — the crate verdict, carrying no artifact, no selection\
\ and no files.\n- **No verdict (non-2xx):** a malformed body and neither or both method selectors are\n request-shape\
- \ 422s (`ValidationError`); a `files` map that is not a method tree is a 422\n `InvalidMethodFiles`, and hash entries\
- \ this runner does not hold one 422 `MissingBlobs`, as on\n `/validate`; custom Python on a deployment that is not\
- \ sandbox-hosted, or a Python structure\n class, is a 403; a selection refusal is an input 422 named for its failure,\n\
- \ `EntryPipeNotFoundError` for an unknown `pipe_ref` or a single-pipe request whose chain finds no\n entry pipe,\
- \ `EntryPipeAmbiguousError` for an ambiguous one or a chain that finds several; the\n `method_ref` fetch outcomes\
- \ are those of `/resolve` (404, 422, 501);\n an artifact that cannot be derived (`PipeIOContractError`) is a 500.\
- \ All RFC 7807\n `application/problem+json` via the global handlers."
+ \ 422s (`request.invalid`); a `files` map that is not a method tree is a 422\n `method.package_invalid`, and hash\
+ \ entries this runner does not hold a 422\n `request.blobs_missing`, as on `/validate`; custom Python on a deployment\
+ \ that is not\n sandbox-hosted is a 501 `pipelex.deployment.custom_code_requires_sandbox`, and a Python\n structure\
+ \ class a 422 `pipelex.deployment.python_structures_refused`; a selection refusal is an\n input 422 named for its\
+ \ failure, `request.pipe_not_found` for an unknown `pipe_ref` or a\n single-pipe request whose chain finds no entry\
+ \ pipe, `request.pipe_ambiguous` for an ambiguous\n one or a chain that finds several; the `method_ref` fetch outcomes\
+ \ are those of `/resolve` (404,\n 422); an artifact that cannot be derived (`PipeIOContractError`) is a 500. All\n\
+ \ `application/problem+json` documents with a registry `code`, via the global handlers."
operationId: pipe_io_v1_pipe_io_post
requestBody:
content:
@@ -1108,11 +1164,13 @@ paths:
'True': '#/components/schemas/PipeIOValidReport'
'False': '#/components/schemas/CrateInvalidReport'
'401':
- description: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
- or `AUTH_MODE=jwt`).
+ description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
+ or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
+ or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
- description: Authentication challenge — always `Bearer`.
+ description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
+ or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
@@ -1120,32 +1178,37 @@ paths:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
- description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
+ description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
+ byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
+ both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
- description: 'The request could not be processed: a malformed body, a field failing validation, or a pipelex error
- whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the diagnostic
- routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
+ description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
+ refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
+ or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
+ error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
+ diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
- description: A failure the caller cannot fix (a missing env var, a bad TOML override, a backend fault), or an unexpected
- error answered as `runtime.unexpected`. Report the `request_id`.
+ description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
+ a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
+ Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
+ blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
+ verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'403':
- description: 'The run routes'' Python policy, applied to the method''s tree: `CustomCodeRequiresSandbox` — the method
- (sent in `files`, or a fetched `method_ref` package) ships custom Python and this deployment is not sandbox-hosted.
- Also `ReadScopeForbidden` — on a `jwt` deployment, the request sent a `read_scope` that does not lie under the
- caller''s own `user_id`. The refusal of a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`,
- is a 422 instead, since the method''s author changes it.'
+ description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
+ the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
+ may read.'
content:
application/problem+json:
schema:
@@ -1158,9 +1221,10 @@ paths:
schema:
$ref: '#/components/schemas/ProblemDocument'
'501':
- description: '`MethodRefNotSupported` — the request selected its method by a **registry-form** `method_ref` (not
- a `github.com/...` address), and no server-side method registry resolves those yet. Use an address-form reference
- or send the method''s tree in `files` instead.'
+ description: '`pipelex.deployment.custom_code_requires_sandbox` — the method (a bundle, or a fetched `method_ref`
+ package, as `params.origin` says) ships custom Python and this deployment is not sandbox-hosted. The refusal of
+ a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`, is a 422 instead,
+ since the method''s author changes it.'
content:
application/problem+json:
schema:
@@ -1176,11 +1240,11 @@ paths:
\ projection\nand run the offline drift check. There is deliberately **no** server-side check route: the\ncheck is\
\ offline by design.\n\nResponse contract (the `/validate` discipline):\n\n- **Valid verdict (200, `is_valid: true`):**\
\ the artifacts + lock on the valid arm.\n- **Invalid verdict (200, `is_valid: false`):** the library could not be\
- \ parsed, loaded, or\n validated — `validation_errors[]` from pipelex's one shared builder; no artifacts exist.\n\
- - **No verdict (non-2xx):** an unknown projection `kind`/`target`, a `pipe_ref` on a\n concept-set-wide kind, or\
- \ a malformed method selector is a request-shape 422 problem+json; the\n method's tree is refused as `/resolve` refuses\
- \ it (422 `InvalidMethodFiles` or `MissingBlobs`,\n the Python policy's 403s, the `method_ref` fetch outcomes, 501\
- \ for a registry-form\n `method_ref`); auth is 401/403; server fault is 5xx."
+ \ parsed, loaded, or\n validated — `errors[]`, one problem item per error; no artifacts exist.\n- **No verdict (non-2xx):**\
+ \ an unknown projection `kind`/`target`, a `pipe_ref` on a\n concept-set-wide kind, or a malformed method selector\
+ \ is a request-shape 422 problem+json; the\n method's tree is refused as `/resolve` refuses it (a 422 `method.package_invalid`\
+ \ or\n `request.blobs_missing`, the Python policy's refusals, the `method_ref` fetch outcomes, a 422\n `request.unsupported`\
+ \ for a registry-form `method_ref`); auth is 401/403; server fault is 5xx."
operationId: codegen_mthds_v1_codegen_post
requestBody:
content:
@@ -1204,11 +1268,13 @@ paths:
'True': '#/components/schemas/CodegenValidReport'
'False': '#/components/schemas/CrateInvalidReport'
'401':
- description: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
- or `AUTH_MODE=jwt`).
+ description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
+ or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
+ or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
- description: Authentication challenge — always `Bearer`.
+ description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
+ or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
@@ -1216,32 +1282,37 @@ paths:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
- description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
+ description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
+ byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
+ both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
- description: 'The request could not be processed: a malformed body, a field failing validation, or a pipelex error
- whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the diagnostic
- routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
+ description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
+ refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
+ or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
+ error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
+ diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
- description: A failure the caller cannot fix (a missing env var, a bad TOML override, a backend fault), or an unexpected
- error answered as `runtime.unexpected`. Report the `request_id`.
+ description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
+ a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
+ Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
+ blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
+ verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'403':
- description: 'The run routes'' Python policy, applied to the method''s tree: `CustomCodeRequiresSandbox` — the method
- (sent in `files`, or a fetched `method_ref` package) ships custom Python and this deployment is not sandbox-hosted.
- Also `ReadScopeForbidden` — on a `jwt` deployment, the request sent a `read_scope` that does not lie under the
- caller''s own `user_id`. The refusal of a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`,
- is a 422 instead, since the method''s author changes it.'
+ description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
+ the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
+ may read.'
content:
application/problem+json:
schema:
@@ -1254,9 +1325,10 @@ paths:
schema:
$ref: '#/components/schemas/ProblemDocument'
'501':
- description: '`MethodRefNotSupported` — the request selected its method by a **registry-form** `method_ref` (not
- a `github.com/...` address), and no server-side method registry resolves those yet. Use an address-form reference
- or send the method''s tree in `files` instead.'
+ description: '`pipelex.deployment.custom_code_requires_sandbox` — the method (a bundle, or a fetched `method_ref`
+ package, as `params.origin` says) ships custom Python and this deployment is not sandbox-hosted. The refusal of
+ a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`, is a 422 instead,
+ since the method''s author changes it.'
content:
application/problem+json:
schema:
@@ -1287,11 +1359,13 @@ paths:
schema:
$ref: '#/components/schemas/LintResponse'
'401':
- description: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
- or `AUTH_MODE=jwt`).
+ description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
+ or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
+ or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
- description: Authentication challenge — always `Bearer`.
+ description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
+ or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
@@ -1299,22 +1373,27 @@ paths:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
- description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
+ description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
+ byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
+ both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
- description: 'The request could not be processed: a malformed body, a field failing validation, or a pipelex error
- whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the diagnostic
- routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
+ description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
+ refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
+ or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
+ error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
+ diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
- description: A failure the caller cannot fix (a missing env var, a bad TOML override, a backend fault), or an unexpected
- error answered as `runtime.unexpected`. Report the `request_id`.
+ description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
+ a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
+ Report the `request_id`.'
content:
application/problem+json:
schema:
@@ -1329,7 +1408,9 @@ paths:
Syntax errors return 200 with diagnostics and unchanged content. Malformed
- formatter options are caller input errors and return RFC 7807 422.'
+ formatter options are caller input errors and return a 422 `request.invalid`
+
+ naming `options`.'
operationId: format_mthds_v1_format_post
requestBody:
content:
@@ -1345,11 +1426,13 @@ paths:
schema:
$ref: '#/components/schemas/FormatResponse'
'401':
- description: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
- or `AUTH_MODE=jwt`).
+ description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
+ or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
+ or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
- description: Authentication challenge — always `Bearer`.
+ description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
+ or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
@@ -1357,22 +1440,27 @@ paths:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
- description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
+ description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
+ byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
+ both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
- description: 'The request could not be processed: a malformed body, a field failing validation, or a pipelex error
- whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the diagnostic
- routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
+ description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
+ refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
+ or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
+ error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
+ diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
- description: A failure the caller cannot fix (a missing env var, a bad TOML override, a backend fault), or an unexpected
- error answered as `runtime.unexpected`. Report the `request_id`.
+ description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
+ a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
+ Report the `request_id`.'
content:
application/problem+json:
schema:
@@ -1393,9 +1481,7 @@ paths:
param is a SINGLE protocol `ModelCategory` value: repeated `?type=` values
- (arity, `ValidationError`) and unknown categories (`InvalidModelCategory`) are
-
- both 422s (RFC 7807).'
+ and unknown categories are both 422 `request.invalid` naming `type`.'
operationId: get_models_v1_models_get
parameters:
- name: type
@@ -1416,11 +1502,13 @@ paths:
schema:
$ref: '#/components/schemas/PipelexModelDeck'
'401':
- description: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
- or `AUTH_MODE=jwt`).
+ description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
+ or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
+ or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
- description: Authentication challenge — always `Bearer`.
+ description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
+ or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
@@ -1428,22 +1516,27 @@ paths:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
- description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
+ description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
+ byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
+ both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
- description: 'The request could not be processed: a malformed body, a field failing validation, or a pipelex error
- whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the diagnostic
- routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
+ description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
+ refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
+ or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
+ error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
+ diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
- description: A failure the caller cannot fix (a missing env var, a bad TOML override, a backend fault), or an unexpected
- error answered as `runtime.unexpected`. Report the `request_id`.
+ description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
+ a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
+ Report the `request_id`.'
content:
application/problem+json:
schema:
@@ -1465,11 +1558,11 @@ paths:
`not_found` it carries the suggestions a failing validation of the same reference offers. A
- request that cannot produce a verdict is an input `422`: `ValidationError` for a missing or
+ request that cannot produce a verdict is an input `422` `request.invalid` naming the parameter: a
- repeated `reference` or a repeated `type`, `InvalidModelReference` for a reference that is blank,
+ missing or repeated `reference`, a repeated `type`, a reference that is blank, a sigil or a namespace
- a sigil or a namespace alone, or too long, and `InvalidModelCategory` for an unknown `type`.'
+ alone, or too long, and an unknown `type`.'
operationId: check_model_v1_models_check_get
parameters:
- name: reference
@@ -1504,11 +1597,13 @@ paths:
schema:
$ref: '#/components/schemas/ModelReferenceVerdict'
'401':
- description: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
- or `AUTH_MODE=jwt`).
+ description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
+ or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
+ or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
- description: Authentication challenge — always `Bearer`.
+ description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
+ or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
@@ -1516,22 +1611,27 @@ paths:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
- description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
+ description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
+ byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
+ both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
- description: 'The request could not be processed: a malformed body, a field failing validation, or a pipelex error
- whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the diagnostic
- routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
+ description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
+ refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
+ or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
+ error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
+ diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
- description: A failure the caller cannot fix (a missing env var, a bad TOML override, a backend fault), or an unexpected
- error answered as `runtime.unexpected`. Report the `request_id`.
+ description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
+ a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
+ Report the `request_id`.'
content:
application/problem+json:
schema:
@@ -1548,18 +1648,19 @@ paths:
at another size than the one stated is listed too, and its upload tells the two cases apart: bytes of the size held
- change nothing, and bytes of another size mean the object held is damaged, a 500 `BlobStoreCorrupted`, since nothing
+ change nothing, and bytes of another size mean the object held is damaged, a 500 `pipelex.storage.damaged`, since
- writes over a blob. When the request names the tree the blobs
+ nothing writes over a blob. When the request names the tree the blobs
make up by its `digest`, this runner has recorded that tree as held in full, which it does only after reading every
file of a tree a request sent, and every listed blob is a file of that tree, the answer is an empty list at once.
- A hash given twice with different sizes is a 422 `BlobMismatch`, and a blob or a set of blobs past this runner''s
+ A hash given twice with different sizes is a 422 `request.invalid` naming `blobs`, and a blob or a set of blobs past
- tree limits a 422 `MethodTreeTooLarge`, both refused before anything is uploaded. Each upload target is this runner''s
- own
+ this runner''s tree limits a 422 `method.package_invalid`, both refused before anything is uploaded. Each upload
+
+ target is this runner''s own
`PUT /v1/blobs/{sha256}`, at `PUBLIC_BASE_URL` when the deployment sets it, its query signed for that hash and
@@ -1592,11 +1693,13 @@ paths:
schema:
$ref: '#/components/schemas/MissingBlobsResult'
'401':
- description: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
- or `AUTH_MODE=jwt`).
+ description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
+ or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
+ or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
- description: Authentication challenge — always `Bearer`.
+ description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
+ or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
@@ -1604,29 +1707,35 @@ paths:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
- description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
+ description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
+ byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
+ both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
- description: 'The request could not be processed: a malformed body, a field failing validation, or a pipelex error
- whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the diagnostic
- routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
+ description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
+ refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
+ or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
+ error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
+ diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
- description: A failure the caller cannot fix (a missing env var, a bad TOML override, a backend fault), or an unexpected
- error answered as `runtime.unexpected`. Report the `request_id`.
+ description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
+ a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
+ Report the `request_id`.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'403':
- description: '`ReadScopeForbidden` — on a `jwt` deployment, the request sent a `read_scope` that does not lie under
- the caller''s own `user_id`, the only scope its token may read.'
+ description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
+ the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
+ may read.'
content:
application/problem+json:
schema:
@@ -2011,12 +2120,13 @@ components:
a dot), and each value is the file''s UTF-8 text, `{"base64": ...}` holding its bytes, or `{"sha256": ..., "size":
...}` naming bytes this runner already holds (uploaded with `POST /v1/blobs/missing` then `PUT /v1/blobs/{sha256}`).
The map is read from the request''s JSON text: a key given twice, a key the membership rule keeps out of every
- tree (`.mthds/` included), colliding keys and a malformed entry are a 422 `InvalidMethodFiles` whose `tree_refusal`
- names the code and the paths, and hash entries the runner does not hold are one 422 `MissingBlobs` whose `missing_blobs`
- lists every such hash. Its `.mthds` files are the method''s bundles and every other file is one a step may read,
- such as a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`, the run starts at the `main_pipe`
- of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its bundles declare. Custom `.py` is
- only honored on a sandbox-hosted deployment. Exactly one of `files` / `method_ref`.'
+ tree (`.mthds/` included) and colliding keys are a 422 `method.package_invalid` whose `reason` is the refusal''s
+ code and whose `path` names the first path, a key leaving the tree is a 422 `security.input_path_refused`, a malformed
+ entry is a 422 `request.invalid`, and hash entries the runner does not hold are one 422 `request.blobs_missing`
+ whose `missing_blobs` parameter lists every such hash. Its `.mthds` files are the method''s bundles and every
+ other file is one a step may read, such as a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`,
+ the run starts at the `main_pipe` of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its
+ bundles declare. Custom `.py` is only honored on a sandbox-hosted deployment. Exactly one of `files` / `method_ref`.'
dependencies:
anyOf:
- additionalProperties:
@@ -2042,8 +2152,8 @@ components:
title: Method Ref
description: PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — a published method by reference, instead of
its tree. Address form (`github.com/<owner>/<repo>[/<selector>][@<tag>]`) is fetched and read as a `files` tree
- is, through the same path as a `method_ref` run; the registry form stays reserved (501 until a method registry
- exists). Exactly one of `files` / `method_ref`.
+ is, through the same path as a `method_ref` run; the registry form stays reserved (a 422 `request.unsupported`
+ until a method registry exists). Exactly one of `files` / `method_ref`.
resources:
anyOf:
- additionalProperties:
@@ -2419,12 +2529,13 @@ components:
const: false
title: Is Valid
default: false
- validation_errors:
+ errors:
items:
- $ref: '#/components/schemas/ValidationErrorItem'
+ $ref: '#/components/schemas/ProblemItem'
type: array
- title: Validation Errors
- description: Per-error diagnostics, built by pipelex's one shared builder — non-empty on every invalid verdict.
+ title: Errors
+ description: One problem item per error, each with its own code, its parameters and its location — non-empty on
+ every invalid verdict. The items of the verdict's problem, as a refusal's `errors` carry them.
message:
type: string
title: Message
@@ -2432,16 +2543,16 @@ components:
default: MTHDS library could not be resolved
type: object
title: CrateInvalidReport
- description: 'The 200 **invalid** arm shared by `/resolve` and `/codegen` — the crate-verdict vocabulary.
+ description: 'The 200 **invalid** arm shared by `/resolve`, `/codegen` and `/pipe-io` — the crate-verdict vocabulary.
Same discipline as `/validate`''s `InvalidReport`: an invalid library is the *successful
product* of a diagnostic call (the request was well-formed; the library was not), so it rides
- a 200 discriminated on `is_valid`, carrying the same structured `ValidationErrorItem`s the
+ a 200 discriminated on `is_valid`, carrying the same problem items in `errors` that `/validate`
- local CLI and `/validate` emit for the identical failure.'
+ emits for the identical failure.'
DateField:
properties:
title:
@@ -2919,30 +3030,6 @@ components:
- step_role
title: ElaborationMetadata
description: Side-table entry recording how a synthetic pipe was generated by the bundle elaborator.
- EnsureTableOp:
- properties:
- table_path:
- items:
- type: string
- type: array
- minItems: 1
- title: Table Path
- kind:
- type: string
- const: ensure_table
- title: Kind
- default: ensure_table
- additionalProperties: false
- type: object
- required:
- - table_path
- title: EnsureTableOp
- description: 'Create the addressed table when it is absent, leaving an existing one untouched.
-
-
- Here ``table_path`` addresses the table to create, not its parent, so it cannot be empty:
-
- the document root always exists.'
EnumField:
properties:
title:
@@ -3129,15 +3216,6 @@ components:
not one per exception the run happened to catch. Every member but `STATE_UNCERTAIN` leaves the
file exactly as it was found; that one does not, and it says so.'
- FixSafety:
- type: string
- enum:
- - safe
- - unsafe
- title: FixSafety
- description: 'Whether a fix is safe to auto-apply (SAFE), or a likely correction that needs a person''s or an agent''s
-
- confirmation (UNSAFE), which ``pipelex fix bundle`` never applies.'
FormatRequest:
properties:
content:
@@ -3338,25 +3416,6 @@ components:
- message
title: HealthResponse
description: Body of `GET /health`.
- HintLintErrorType:
- type: string
- enum:
- - hint_unknown_key
- - hint_unknown_intent
- - hint_inapplicable_intent
- title: HintLintErrorType
- description: 'Advisory intent-hints lint findings (spec: intent-hints.md).
-
-
- Every member is advisory-only: it rides the validation report''s ``warnings`` array and never
-
- makes a verdict invalid — hints are non-normative, and well-formed unknown content is
-
- preserved, only warned about. A separate enum rather than new ``PipeValidationErrorType``
-
- members because hints attach to concepts and structure fields too, so the pipe enum is the
-
- wrong home.'
IOMultiplicity:
type: string
enum:
@@ -3683,12 +3742,13 @@ components:
const: false
title: Is Valid
default: false
- validation_errors:
+ errors:
items:
- $ref: '#/components/schemas/ValidationErrorItem'
+ $ref: '#/components/schemas/ProblemItem'
type: array
- title: Validation Errors
- description: Per-error diagnostics, built by pipelex's one shared builder — non-empty on every invalid verdict.
+ title: Errors
+ description: One problem item per error, each with its own code, its parameters and its location — non-empty on
+ every invalid verdict. The items of the verdict's problem, as a refusal's `errors` carry them.
pending_signatures:
items:
type: string
@@ -3710,7 +3770,7 @@ components:
- type: string
- type: 'null'
title: Rendered Markdown
- description: 'Opt-in Pipelex-API presentation extra: a server-rendered Markdown view of the invalid verdict''s `validation_errors`,
+ description: 'Opt-in Pipelex-API presentation extra: a server-rendered Markdown view of the invalid verdict''s errors,
present only when the request''s `render` includes `markdown`. Absent by default.'
type: object
title: InvalidReport
@@ -3727,13 +3787,15 @@ components:
(`bundle_blueprint`, `pipe_io_contracts`, `graph_spec`, `validated_pipes`) do not exist when
- load/parse/wiring failed, so this arm omits them and carries only the per-error diagnostics
+ load/parse/wiring failed, so this arm omits them and carries only the per-error diagnostics,
+
+ as the problem items of the verdict''s problem (`errors`), plus the runnability facts. The
- plus the runnability facts. The `input_form` and `output_form` views follow them into absence for
+ `input_form` and `output_form` views follow them into absence for the same reason — both derive
- the same reason — both derive from a crate that was never assembled — so neither is declared here and `views`
+ from a crate that was never assembled — so neither is declared here and `views` has no effect
- has no effect on this arm (unlike `rendered_markdown`, which rides both arms because failure
+ on this arm (unlike `rendered_markdown`, which rides both arms because failure
text is exactly what a human surface wants).'
JudgeQuestionBlueprint:
@@ -4184,12 +4246,13 @@ components:
a dot), and each value is the file''s UTF-8 text, `{"base64": ...}` holding its bytes, or `{"sha256": ..., "size":
...}` naming bytes this runner already holds (uploaded with `POST /v1/blobs/missing` then `PUT /v1/blobs/{sha256}`).
The map is read from the request''s JSON text: a key given twice, a key the membership rule keeps out of every
- tree (`.mthds/` included), colliding keys and a malformed entry are a 422 `InvalidMethodFiles` whose `tree_refusal`
- names the code and the paths, and hash entries the runner does not hold are one 422 `MissingBlobs` whose `missing_blobs`
- lists every such hash. Its `.mthds` files are the method''s bundles and every other file is one a step may read,
- such as a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`, the run starts at the `main_pipe`
- of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its bundles declare. Custom `.py` is
- only honored on a sandbox-hosted deployment. Exactly one of `files` / `method_ref`.'
+ tree (`.mthds/` included) and colliding keys are a 422 `method.package_invalid` whose `reason` is the refusal''s
+ code and whose `path` names the first path, a key leaving the tree is a 422 `security.input_path_refused`, a malformed
+ entry is a 422 `request.invalid`, and hash entries the runner does not hold are one 422 `request.blobs_missing`
+ whose `missing_blobs` parameter lists every such hash. Its `.mthds` files are the method''s bundles and every
+ other file is one a step may read, such as a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`,
+ the run starts at the `main_pipe` of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its
+ bundles declare. Custom `.py` is only honored on a sandbox-hosted deployment. Exactly one of `files` / `method_ref`.'
dependencies:
anyOf:
- additionalProperties:
@@ -4215,8 +4278,8 @@ components:
title: Method Ref
description: PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — a published method by reference, instead of
its tree. Address form (`github.com/<owner>/<repo>[/<selector>][@<tag>]`) is fetched and read as a `files` tree
- is, through the same path as a `method_ref` run; the registry form stays reserved (501 until a method registry
- exists). Exactly one of `files` / `method_ref`.
+ is, through the same path as a `method_ref` run; the registry form stays reserved (a 422 `request.unsupported`
+ until a method registry exists). Exactly one of `files` / `method_ref`.
resources:
anyOf:
- additionalProperties:
@@ -4259,9 +4322,10 @@ components:
the run routes'' fetch path: the package''s tree is read from its commit''s git objects, with the packages it ships
- under `.mthds/methods/`. The **registry form** (any non-address reference) stays reserved and answers 501 until
+ under `.mthds/methods/`. The **registry form** (any non-address reference) stays reserved, a 422
- server-side method-registry resolution exists. Either way the method is held to the run routes'' Python policy:
+ `request.unsupported`, until server-side method-registry resolution exists. Either way the method is held to the run
+ routes'' Python policy:
custom `.py` only on a sandbox-hosted deployment, and no Python structure class at all.'
MigrationErrorBlock:
@@ -5671,16 +5735,6 @@ components:
- description
- output
title: PipeExtractBlueprint
- PipeFactoryErrorType:
- type: string
- enum:
- - unknown_concept
- - unknown_factory_error
- title: PipeFactoryErrorType
- description: 'Types of pipe factory errors.
-
-
- These error types are raised during pipe creation from blueprints.'
PipeFuncBlueprint:
properties:
source:
@@ -5797,12 +5851,13 @@ components:
a dot), and each value is the file''s UTF-8 text, `{"base64": ...}` holding its bytes, or `{"sha256": ..., "size":
...}` naming bytes this runner already holds (uploaded with `POST /v1/blobs/missing` then `PUT /v1/blobs/{sha256}`).
The map is read from the request''s JSON text: a key given twice, a key the membership rule keeps out of every
- tree (`.mthds/` included), colliding keys and a malformed entry are a 422 `InvalidMethodFiles` whose `tree_refusal`
- names the code and the paths, and hash entries the runner does not hold are one 422 `MissingBlobs` whose `missing_blobs`
- lists every such hash. Its `.mthds` files are the method''s bundles and every other file is one a step may read,
- such as a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`, the run starts at the `main_pipe`
- of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its bundles declare. Custom `.py` is
- only honored on a sandbox-hosted deployment. Exactly one of `files` / `method_ref`.'
+ tree (`.mthds/` included) and colliding keys are a 422 `method.package_invalid` whose `reason` is the refusal''s
+ code and whose `path` names the first path, a key leaving the tree is a 422 `security.input_path_refused`, a malformed
+ entry is a 422 `request.invalid`, and hash entries the runner does not hold are one 422 `request.blobs_missing`
+ whose `missing_blobs` parameter lists every such hash. Its `.mthds` files are the method''s bundles and every
+ other file is one a step may read, such as a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`,
+ the run starts at the `main_pipe` of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its
+ bundles declare. Custom `.py` is only honored on a sandbox-hosted deployment. Exactly one of `files` / `method_ref`.'
dependencies:
anyOf:
- additionalProperties:
@@ -5828,8 +5883,8 @@ components:
title: Method Ref
description: PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — a published method by reference, instead of
its tree. Address form (`github.com/<owner>/<repo>[/<selector>][@<tag>]`) is fetched and read as a `files` tree
- is, through the same path as a `method_ref` run; the registry form stays reserved (501 until a method registry
- exists). Exactly one of `files` / `method_ref`.
+ is, through the same path as a `method_ref` run; the registry form stays reserved (a 422 `request.unsupported`
+ until a method registry exists). Exactly one of `files` / `method_ref`.
resources:
anyOf:
- additionalProperties:
@@ -6749,44 +6804,6 @@ components:
- PipeParallel
- PipeSequence
title: PipeType
- PipeValidationErrorType:
- type: string
- enum:
- - missing_input_variable
- - extraneous_input_variable
- - input_stuff_spec_mismatch
- - inadequate_output_concept
- - inadequate_output_multiplicity
- - llm_output_cannot_be_image
- - llm_setting_refused_by_model
- - invalid_pipe_code_syntax
- - invalid_input_name
- - unknown_pipe_type
- - missing_pipe_type
- - batch_item_name_collision
- - binding_step_invalid
- - binding_path_unresolved
- - optional_marker_invalid
- - optional_not_handled
- - optional_output_required
- - optional_input_unguarded
- - optional_branch_required_field
- - template_private_name
- - optional_force_redundant
- - input_presence_vacuous
- - native_concept_redeclaration
- - unresolved_concept
- - unresolved_pipe_dependency
- - unresolved_package_dependency
- - unexported_pipe_dependency
- - unknown_model
- - pipe_func_function_refused
- - unknown_validation_error
- title: PipeValidationErrorType
- description: 'Types of pipe validation errors.
-
-
- These error types are raised during pipe validation from Pipe/Concept classes.'
PipelexApiExecuteResponse:
properties:
pipeline_run_id:
@@ -7315,14 +7332,12 @@ components:
type:
type: string
title: Type
- description: 'Stable URI of the error''s documentation page: the page of its `code` (`https://mthds.ai/errors/<code>`
- for a core code, `https://docs.pipelex.com/errors/<code>` for a Pipelex code), or `https://docs.pipelex.com/latest/errors/<kebab-error-type>/`
- for an API-authored error, which carries no `code` yet.'
+ description: 'Stable URI of the documentation page of the error''s `code`: `https://mthds.ai/errors/<code>` for
+ a core code, `https://docs.pipelex.com/errors/<code>` for a Pipelex code.'
title:
type: string
title: Title
- description: 'Short, human-readable summary: the title of the error''s `code`, or of its `error_type` when it carries
- none.'
+ description: 'Short, human-readable summary: the title of the error''s `code`.'
status:
type: integer
title: Status
@@ -7333,23 +7348,16 @@ components:
description: 'Human-readable explanation of this specific failure, rendered from its code''s template and parameters.
Never parsed: a program branches on `code`.'
code:
- anyOf:
- - type: string
- - type: 'null'
+ type: string
title: Code
description: 'Registry code of the error, what a client branches on: a core code of the MTHDS standard (e.g. `request.invalid`)
- or a Pipelex code (e.g. `pipelex.config.invalid`). Present on every error the runtime raises; absent on an API-authored
- error.'
+ or a Pipelex code (e.g. `pipelex.config.invalid`).'
domain:
- anyOf:
- - type: string
- - type: 'null'
+ type: string
title: Domain
description: 'Who must act, the code''s domain: `input`, `method`, `account`, `operator` or `runtime`.'
retry:
- anyOf:
- - type: string
- - type: 'null'
+ type: string
title: Retry
description: 'Whether repeating the request can succeed, the code''s verdict: `yes`, `no` or `outcome_unknown`.'
retry_after:
@@ -7359,9 +7367,7 @@ components:
title: Retry After
description: Seconds to wait before a retry, when known, on a code whose verdict is `yes`.
next_step:
- anyOf:
- - $ref: '#/components/schemas/NextStep'
- - type: 'null'
+ $ref: '#/components/schemas/NextStep'
description: 'What the reader should do next: a kind and a sentence, aimed at the caller, or at the operator in
the operator view.'
params:
@@ -7382,8 +7388,9 @@ components:
type: array
- type: 'null'
title: Errors
- description: One item per fault, for a refusal with several, such as a method that does not validate. On `/validate`,
- `/resolve`, `/codegen` and `/pipe-io` an invalid bundle is a **200** verdict instead.
+ description: One item per fault, for a refusal with several, such as a request whose fields the route refuses. On
+ `/validate`, `/resolve`, `/codegen` and `/pipe-io` an invalid bundle is a **200** verdict instead, whose `errors`
+ are items of this same shape.
pipeline_run_id:
anyOf:
- type: string
@@ -7395,7 +7402,8 @@ components:
- type: string
- type: 'null'
title: Request Id
- description: Correlation id, echoed in the `X-Request-ID` response header.
+ description: 'Correlation id, echoed in the `X-Request-ID` response header: the caller''s own when valid, else one
+ the runner mints.'
diagnostics:
anyOf:
- $ref: '#/components/schemas/ProblemDiagnostics'
@@ -7403,31 +7411,6 @@ components:
description: 'What only the operator reads: the error''s class and message, its causes, the provider''s answer,
the model. Present only when the request was authenticated as the operator''s (`AUTH_MODE=api_key`, or a trusted
proxy).'
- instance:
- anyOf:
- - type: string
- - type: 'null'
- title: Instance
- description: Path of the request that failed, on an API-authored error.
- error_type:
- anyOf:
- - type: string
- - type: 'null'
- title: Error Type
- description: Stable name of an API-authored error (e.g. `Unauthenticated`).
- error_domain:
- anyOf:
- - type: string
- - type: 'null'
- title: Error Domain
- description: 'On an API-authored error: `input` (caller can fix it → 4xx) or `config` (deployment must fix it →
- 5xx).'
- retryable:
- anyOf:
- - type: boolean
- - type: 'null'
- title: Retryable
- description: 'On an API-authored error: whether retrying the same request can plausibly succeed.'
additionalProperties: true
type: object
required:
@@ -7435,21 +7418,23 @@ components:
- title
- status
- detail
+ - code
+ - domain
+ - retry
+ - next_step
title: ProblemDocument
description: 'An RFC 9457 `application/problem+json` error body — the shape of every failure response.
- A pipelex error answers its problem document: the RFC''s members (`type`, `title`, `status`, `detail`), the MTHDS
+ Every failure answers its problem document: the RFC''s members (`type`, `title`, `status`, `detail`), the MTHDS
core''s (`code`, `domain`, `retry`, `next_step`, always present, and `retry_after`, `params`, `location`, `errors`,
- `pipeline_run_id` when they hold a value) and Pipelex''s (`request_id`, and `diagnostics` in the operator view
-
- alone). An API-authored error carries no `code` yet, and is classified by `error_type`, `error_domain` and
+ `pipeline_run_id` when they hold a value) and Pipelex''s (`request_id`, always present on a response of this server,
- `retryable` instead, with its request path as `instance`. No member is ever written as `null`: a member with no
+ and `diagnostics` in the operator view alone). No member is ever written as `null`: a member with no value is
- value is absent. `extra="allow"` mirrors RFC 9457''s open-ended extension-member rule.'
+ absent. `extra="allow"` mirrors RFC 9457''s open-ended extension-member rule.'
ProblemDomain:
type: string
enum:
@@ -7759,7 +7744,7 @@ components:
- $ref: '#/components/schemas/ProblemRenameTableKeyOp'
- $ref: '#/components/schemas/ProblemMoveKeyOp'
- $ref: '#/components/schemas/ProblemRemapValueOp'
- - $ref: '#/components/schemas/UnknownFixOp'
+ - $ref: '#/components/schemas/ProblemUnknownFixOp'
type: array
minItems: 1
title: Ops
@@ -7772,6 +7757,18 @@ components:
- ops
title: SuggestedFix
description: 'A deterministic fix for one fault: operations over a bundle of the method, addressed by TOML key path.'
+ ProblemUnknownFixOp:
+ properties:
+ kind:
+ type: string
+ title: Kind
+ additionalProperties: true
+ type: object
+ required:
+ - kind
+ title: UnknownFixOp
+ description: 'The reader-side catch-all: an operation whose `kind` is none the protocol lists, which an applier never
+ applies.'
PromptImageDetail:
type: string
enum:
@@ -8187,43 +8184,6 @@ components:
- message
title: ServiceIdentity
description: Body of `GET /` — the service identity banner.
- SetKeyOp:
- properties:
- table_path:
- items:
- type: string
- type: array
- title: Table Path
- kind:
- type: string
- const: set_key
- title: Kind
- default: set_key
- key:
- type: string
- title: Key
- value:
- anyOf:
- - type: string
- - type: integer
- - type: number
- - type: boolean
- - additionalProperties:
- anyOf:
- - type: string
- - type: integer
- - type: number
- - type: boolean
- type: object
- title: Value
- additionalProperties: false
- type: object
- required:
- - table_path
- - key
- - value
- title: SetKeyOp
- description: Write ``key = value`` in the addressed table, whatever it currently holds.
SizeTier:
type: string
enum:
@@ -8343,59 +8303,6 @@ components:
required:
- pipe
title: SubPipeBlueprint
- SuggestedFix:
- properties:
- fix_code:
- type: string
- title: Fix Code
- description:
- type: string
- title: Description
- safety:
- $ref: '#/components/schemas/FixSafety'
- source:
- anyOf:
- - type: string
- - type: 'null'
- title: Source
- ops:
- items:
- oneOf:
- - $ref: '#/components/schemas/SetKeyOp'
- - $ref: '#/components/schemas/EnsureTableOp'
- - $ref: '#/components/schemas/DeleteKeyOp'
- - $ref: '#/components/schemas/DeleteTableOp'
- - $ref: '#/components/schemas/RenameTableKeyOp'
- - $ref: '#/components/schemas/MoveKeyOp'
- - $ref: '#/components/schemas/RemapValueOp'
- discriminator:
- propertyName: kind
- mapping:
- delete_key: '#/components/schemas/DeleteKeyOp'
- delete_table: '#/components/schemas/DeleteTableOp'
- ensure_table: '#/components/schemas/EnsureTableOp'
- move_key: '#/components/schemas/MoveKeyOp'
- remap_value: '#/components/schemas/RemapValueOp'
- rename_table_key: '#/components/schemas/RenameTableKeyOp'
- set_key: '#/components/schemas/SetKeyOp'
- type: array
- title: Ops
- additionalProperties: false
- type: object
- required:
- - fix_code
- - description
- - safety
- - ops
- title: SuggestedFix
- description: 'A deterministic fix for one validation error, ready for a style-preserving applier.
-
-
- ``fix_code`` is the kebab-case rule id (e.g. ``"match-sequence-output"``). ``source`` is
-
- the file the ops target, when known (multi-file libraries) — an applier must only apply
-
- ops to the file they target.'
TagStyle:
type: string
enum:
@@ -8446,25 +8353,6 @@ components:
- llm_prompt
- img_gen_prompt
title: TemplateCategory
- TemplateCheckErrorType:
- type: string
- enum:
- - template_check_warning
- title: TemplateCheckErrorType
- description: 'Advisory findings of a ``PipeDocGen`` step''s template check (the engine''s ``check_template``).
-
-
- Every member is advisory-only: it rides the validation report''s ``warnings`` array and never makes a
-
- verdict invalid. An error finding of the same check fails the step''s dry run instead, and is reported as
-
- the ``DryRunError`` item every failed dry run is. A separate enum rather than a new
-
- ``PipeValidationErrorType`` member because the finding is not the pipe''s validation: the dry run hands the
-
- step''s template file to its engine, which reads it in a way only the engine can, and reports in its own
-
- words. Its locators are the template file and the place in it the engine names.'
TemplatingStyle:
properties:
tag_style:
@@ -8829,18 +8717,6 @@ components:
- name
title: UnknownField
description: '`unknown` at a named position.'
- UnknownFixOp:
- properties:
- kind:
- type: string
- title: Kind
- additionalProperties: true
- type: object
- required:
- - kind
- title: UnknownFixOp
- description: 'The reader-side catch-all: an operation whose `kind` is none the protocol lists, which an applier never
- applies.'
UnknownItem:
properties:
title:
@@ -8941,9 +8817,11 @@ components:
default: true
warnings:
items:
- $ref: '#/components/schemas/ValidationErrorItem'
+ $ref: '#/components/schemas/ProblemItem'
type: array
title: Warnings
+ description: 'Advisory findings on the valid bundle, one problem item each, with the code the finding''s type names:
+ they never flip `is_valid`. The same item shape as the invalid arm''s `errors`.'
bundle_blueprint:
$ref: '#/components/schemas/PipelexBundleBlueprint'
pipe_io_contracts:
@@ -9011,7 +8889,7 @@ components:
run of THIS request would execute. For a method tree (`files` or a `method_ref`) it is the tree''s entry pipe
by the MTHDS protocol''s rule: the `main_pipe` of the `METHODS.toml` at its root, else the one `main_pipe` its
bundles declare. For inline `mthds_contents` it is the closure''s primary blueprint''s `main_pipe` qualified by
- its domain. `null` when no entry pipe is determined, in which case a selector-less run would be refused too.'
+ its domain. Absent when no entry pipe is determined, in which case a selector-less run would be refused too.'
rendered_markdown:
anyOf:
- type: string
@@ -9038,6 +8916,13 @@ components:
they are NOT part of the canonical report and no in-process consumer should depend on them.
+ `warnings` is re-declared as problem items: the canonical report holds the advisory findings as the validation
+
+ items the local channels render, and the wire carries each as the problem item its type''s code makes
+
+ (`pipelex.pipeline.validation_errors.warning_problem_items`), the item shape `errors` has on the invalid arm.
+
+
Two inherited fields are deliberately re-declared: `input_form` and `output_form`. The canonical
report requires both (a backend that forgets to derive one must fail loudly rather than ship an
@@ -9094,13 +8979,14 @@ components:
a dot), and each value is the file''s UTF-8 text, `{"base64": ...}` holding its bytes, or `{"sha256": ..., "size":
...}` naming bytes this runner already holds (uploaded with `POST /v1/blobs/missing` then `PUT /v1/blobs/{sha256}`).
The map is read from the request''s JSON text: a key given twice, a key the membership rule keeps out of every
- tree (`.mthds/` included), colliding keys and a malformed entry are a 422 `InvalidMethodFiles` whose `tree_refusal`
- names the code and the paths, and hash entries the runner does not hold are one 422 `MissingBlobs` whose `missing_blobs`
- lists every such hash. Its `.mthds` files are the method''s bundles and every other file is one a step may read,
- such as a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`, the run starts at the `main_pipe`
- of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its bundles declare. Custom `.py` is
- only honored on a sandbox-hosted deployment. The whole tree is validated, its Python included, by syntax. Exactly
- one of `mthds_contents` / `files` / `method_ref`.'
+ tree (`.mthds/` included) and colliding keys are a 422 `method.package_invalid` whose `reason` is the refusal''s
+ code and whose `path` names the first path, a key leaving the tree is a 422 `security.input_path_refused`, a malformed
+ entry is a 422 `request.invalid`, and hash entries the runner does not hold are one 422 `request.blobs_missing`
+ whose `missing_blobs` parameter lists every such hash. Its `.mthds` files are the method''s bundles and every
+ other file is one a step may read, such as a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`,
+ the run starts at the `main_pipe` of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its
+ bundles declare. Custom `.py` is only honored on a sandbox-hosted deployment. The whole tree is validated, its
+ Python included, by syntax. Exactly one of `mthds_contents` / `files` / `method_ref`.'
dependencies:
anyOf:
- additionalProperties:
@@ -9191,7 +9077,8 @@ components:
as `/start`). An OPEN string token: `direct` validates in-process; a `temporal` mode dispatches the whole job
to a worker; any plugin-provided token is accepted and an unregistered one is refused at dispatch. Honored only
when the deployment sets `allow_request_orchestration_mode_override = true` in its `api.toml`; otherwise a token
- that differs from the deployment default is refused with a 403. Omitted → the default.'
+ that differs from the deployment default is refused with a 422 `pipelex.deployment.orchestration_override_forbidden`.
+ Omitted → the default.'
read_scope:
anyOf:
- type: string
@@ -9212,11 +9099,11 @@ components:
file''s path relative to the submitted directory). The runner threads it onto
- `blueprint.source`, so the structured `validation_errors` on a 200 `InvalidReport` carry a real
+ `blueprint.source`, so the problem items in `errors` on a 200 `InvalidReport` carry a real
- `source` the client maps back to the owning file — without it the in-memory load path leaves
+ `location.file` the client maps back to the owning file — without it the in-memory load path
- `source` null and cross-file diagnostics misfire. Omit it and behavior is unchanged.'
+ leaves the file unknown and cross-file diagnostics misfire. Omit it and behavior is unchanged.'
ValidatedPipeEntry:
properties:
pipe_ref:
@@ -9236,217 +9123,6 @@ components:
The ``pipe_ref`` key carries the namespaced ``pipe_ref`` (``domain.code``) — never the bare code.
``status`` is a ``DryRunStatus`` (a ``StrEnum``), so it serializes to its plain string value.'
- ValidationErrorCategory:
- type: string
- enum:
- - blueprint_validation
- - pipe_factory
- - pipe_validation
- - dry_run
- title: ValidationErrorCategory
- description: 'Which validation stage produced a :class:`ValidationErrorItem`.
-
-
- Mirrors the categorized error-data lists aggregated by ``ValidateBundleError``:
-
- blueprint validation (from the interpreter), pipe-factory failures (e.g. a
-
- missing concept), pipe/concept validation (e.g. a missing input variable
-
- or a type mismatch), and ``dry_run`` — one item per pipe whose dry run failed,
-
- located at the innermost failing pipe. On the report''s advisory ``warnings``,
-
- ``dry_run`` marks a finding a dry run made without failing, such as a warning of
-
- a ``PipeDocGen`` step''s template check.'
- ValidationErrorItem:
- properties:
- category:
- $ref: '#/components/schemas/ValidationErrorCategory'
- message:
- type: string
- title: Message
- error_type:
- anyOf:
- - $ref: '#/components/schemas/PipeValidationErrorType'
- - $ref: '#/components/schemas/PipeFactoryErrorType'
- - $ref: '#/components/schemas/ValidationResidualErrorType'
- - $ref: '#/components/schemas/HintLintErrorType'
- - $ref: '#/components/schemas/TemplateCheckErrorType'
- - type: 'null'
- title: Error Type
- pipe_code:
- anyOf:
- - type: string
- - type: 'null'
- title: Pipe Code
- concept_code:
- anyOf:
- - type: string
- - type: 'null'
- title: Concept Code
- domain_code:
- anyOf:
- - type: string
- - type: 'null'
- title: Domain Code
- source:
- anyOf:
- - type: string
- - type: 'null'
- title: Source
- field_path:
- anyOf:
- - type: string
- - type: 'null'
- title: Field Path
- field_name:
- anyOf:
- - type: string
- - type: 'null'
- title: Field Name
- variable_names:
- anyOf:
- - items:
- type: string
- type: array
- - type: 'null'
- title: Variable Names
- missing_concept_code:
- anyOf:
- - type: string
- - type: 'null'
- title: Missing Concept Code
- missing_pipe_code:
- anyOf:
- - type: string
- - type: 'null'
- title: Missing Pipe Code
- declared_concepts:
- anyOf:
- - items:
- type: string
- type: array
- - type: 'null'
- title: Declared Concepts
- line:
- anyOf:
- - type: integer
- - type: 'null'
- title: Line
- column:
- anyOf:
- - type: integer
- - type: 'null'
- title: Column
- model_reference:
- anyOf:
- - type: string
- - type: 'null'
- title: Model Reference
- model_type:
- anyOf:
- - type: string
- - type: 'null'
- title: Model Type
- suggestions:
- anyOf:
- - items:
- type: string
- type: array
- - type: 'null'
- title: Suggestions
- template_file:
- anyOf:
- - type: string
- - type: 'null'
- title: Template File
- template_location:
- anyOf:
- - type: string
- - type: 'null'
- title: Template Location
- suggested_fix:
- anyOf:
- - $ref: '#/components/schemas/SuggestedFix'
- - type: 'null'
- additionalProperties: false
- type: object
- required:
- - category
- - message
- title: ValidationErrorItem
- description: 'One structured bundle-validation error, as the validation verdicts carry it.
-
-
- The typed item of an invalid verdict''s ``validation_errors``; the problem document of a refusal carries each as an
-
- ``errors`` item instead (``pipelex.pipeline.validation_errors.problem_item_of``). Its
-
- fields are the *union* across the three ``ValidateBundleError`` error-data
-
- models (``PipelexBundleBlueprintValidationErrorData``, ``PipeFactoryErrorData``,
-
- ``PipesAndConceptValidationErrorData``); a given item only populates the
-
- subset its :attr:`category` produces, and the unset fields drop out of the
-
- ``exclude_none`` wire projection.
-
-
- The error channel is built exclusively by
-
- ``pipelex.pipeline.validation_errors.build_validation_error_items``, which the agent
-
- CLI''s problem (``ValidateBundleError.problem_items``) and the API path
-
- (``ValidateBundleError.validation_error_items``) both reach — so the CLI''s structured
-
- output and the API''s invalid verdict can never drift. The same
-
- item type also carries the report''s advisory ``warnings``, built by
-
- ``pipelex.pipeline.advisory_warnings``: a warning is the same shape of
-
- diagnostic, differing only in that it does not make the verdict invalid.
-
-
- ``source`` is the declaring file path (CLI) or the per-content source the API
-
- threads onto the in-memory load path — it hands a consumer the owning file
-
- for cross-file diagnostics. Lives here rather than next to the source error-data
-
- models because ``base_exceptions`` must not import the ``pipelex.core`` error
-
- modules (which import back into this module).'
- ValidationResidualErrorType:
- type: string
- enum:
- - DryRunError
- title: ValidationResidualErrorType
- description: 'The ``error_type`` of a failure no validation stage classifies into a code.
-
-
- There is exactly one that names itself: a dry-run failure is raised as an error object, a
-
- ``DryRunError`` carrying one located failure per pipe whose dry run failed, so each of its items is
-
- tagged with that exception''s own class name.
-
-
- The items no code identifies — the parse-level residual, for a bundle that could not be turned
-
- into a blueprint at all (a TOML-syntax error, an empty blueprint, an elaborator failure), and a
-
- pydantic error no categorizer knows — carry no ``error_type`` and therefore no member here. That
-
- is not an omission: they stand for many distinct underlying errors, and inventing one code for all
-
- of them would tell a consumer it knows which fault occurred when it does not. Their message is the
-
- authoritative diagnostic.'
WaterfallMatch:
properties:
category:
diff --git a/docs/api-server/pipe-io.md b/docs/api-server/pipe-io.md
index f03b59536..345094dd1 100644
--- a/docs/api-server/pipe-io.md
+++ b/docs/api-server/pipe-io.md
@@ -20,7 +20,7 @@ The body names the method as the [crate routes](codegen.md#selecting-the-method)
- `all_pipes` (boolean, default `false`): describe every pipe the closure loads instead of the selected one.
- `include_files` (boolean, default `false`): echo the text of the method's own `.mthds` bundles on the valid arm.
- `resources` (object, optional): files the method's steps read, such as a `PipeDocGen` step's `template_file`, keyed by the path from the tree's root, each in standard base64, joining the tree as on [`/v1/validate`](pipe-validate.md#sending-the-files-the-steps-read-resources). It accompanies `files` only. A step whose template file the tree does not hold makes the method invalid.
-- `read_scope` (string, optional): **Pipelex-API extension.** The scope the request reads the method under, as on `/v1/validate`: a hash entry of `files` resolves in that scope's blob store, and only a request carrying it records the tree it read there; [a `jwt` caller may send only a scope under its own id](pipe-run.md#host-supplied-run-context-storage_scope-and-analytics_groups), else a `403 ReadScopeForbidden`.
+- `read_scope` (string, optional): **Pipelex-API extension.** The scope the request reads the method under, as on `/v1/validate`: a hash entry of `files` resolves in that scope's blob store, and only a request carrying it records the tree it read there; [a `jwt` caller may send only a scope under its own id](pipe-run.md#host-supplied-run-context-storage_scope-and-analytics_groups), else a `403` `auth.forbidden` whose `requirement` is `read_scope_under_caller`.
There is no `views` field, because the valid arm always carries all three artifacts. The hosted API also accepts a catalog `method_id`, which the platform resolves into the method's `files` before forwarding, so this server never declares it.
@@ -36,13 +36,13 @@ There is no `views` field, because the valid arm always carries all three artifa
}
```
-The tree's refusals produce no verdict, as on `/v1/validate`: an `InvalidMethodFiles`, `MissingBlobs`, `MethodTreeTooLarge` or `InvalidBundle` `422`, and the custom-Python policy's refusals (see [No verdict](#no-verdict)).
+The tree's refusals produce no verdict, as on `/v1/validate`: a `422` `method.package_invalid` naming the rule or the limit as its `reason`, `security.input_path_refused`, `request.invalid` or `request.blobs_missing`, and the custom-Python policy's refusals (see [No verdict](#no-verdict)).
## Pipe selection
The selection chain takes the request's `pipe_ref`; else the `main_pipe` of the `METHODS.toml` at the tree's root, whether the tree was fetched by `method_ref` or sent in `files`; else the closure's own `main_pipe` declaration, when exactly one domain declares one. A root `METHODS.toml` the route cannot read as a manifest, being no UTF-8 text or no valid manifest, is a `422` problem coded `method.package_invalid` when the request names no pipe. A request naming its pipe in `pipe_ref` never reads the manifest to select it, so there a manifest the route cannot read refuses nothing and only leaves `default_pipe_ref` a stated `null`. The chain stops at the first link that is present, so a manifest `main_pipe` the closure does not declare, or declares in several domains, is a failed selection rather than a fall-through to the closure's declarations.
-The closure is resolved first, so an invalid closure answers its invalid verdict whatever `pipe_ref` names. For a valid closure these selections are refused with a `422` problem whose `code` names the failure, never the `ValidationError` of a malformed request, so a client tells a selection refusal from a request-shape one by that member:
+The closure is resolved first, so an invalid closure answers its invalid verdict whatever `pipe_ref` names. For a valid closure these selections are refused with a `422` problem whose `code` names the failure, never the `request.invalid` of a malformed request, so a client tells a selection refusal from a request-shape one by that member:
- `request.pipe_not_found` for a `pipe_ref` that names no pipe of the closure, with the selection as its `pipe` parameter;
- `request.pipe_ambiguous` for a bare code that matches pipes in several domains, with the selection as its `pipe` parameter and the qualified refs to choose from as its `candidates`;
@@ -87,14 +87,14 @@ A bare `pipe_ref` that matches one pipe (`echo` where `smoke.echo` is meant) is
## Response (invalid verdict)
-An invalid closure is the `200` crate verdict `/v1/resolve` gives: `is_valid: false`, the structured `validation_errors[]` and a `message`. A call into a package nothing shipped is one, its `unresolved_package_dependency` item naming the package as `address-based dependency '<address>'`. It carries no artifacts, no `pipe_ref` or `default_pipe_ref`, no runnability facts and no `files`, whatever the request asked for.
+An invalid closure is the `200` crate verdict `/v1/resolve` gives: `is_valid: false`, the structured `errors[]` and a `message`. A call into a package nothing shipped is one, its `method.dependency_missing` item naming the package's address as its `name`. It carries no artifacts, no `pipe_ref` or `default_pipe_ref`, no runnability facts and no `files`, whatever the request asked for.
## No verdict
Every non-2xx is RFC 9457 `application/problem+json` (see [Error Responses](error-responses.md)):
-- **`422`** for a malformed body or neither or both method selectors, `ValidationError`; for a tree the runner cannot read, `InvalidMethodFiles`, `MissingBlobs`, `MethodTreeTooLarge` or `InvalidBundle`, as on [`/v1/resolve`](codegen.md#selecting-the-method); for an unreadable root manifest on a request naming no pipe, `method.package_invalid`; and for the selection refusals above, by their codes.
-- **The `method_ref` fetch outcomes**, exactly as on `/v1/resolve`: `404` `method.not_found` when no package in the fetched repository matches the address, `422` for a reference that does not parse (`request.invalid`) or a package the server cannot accept (`method.ambiguous`, `method.package_invalid`), `502` `method.fetch_failed` when the fetch itself failed, and `501` `MethodRefNotSupported` for a registry-form reference.
-- **The custom-Python policy of `/v1/validate` and the run routes**, whose tree the route loads: a `403` `CustomCodeRequiresSandbox` for a tree holding a `.py` file on a deployment that is not sandbox-hosted, where loading the library would import each `.py` declaring a structure class and run its module-level code in the server's process, and a `422` `pipelex.deployment.python_structures_refused` for one whose Python declares a structure class.
-- **`401` / `403`** for authentication, and **`413`** for a body over the size limit.
+- **`422`** for a malformed body or neither or both method selectors, `request.invalid` naming the field; for a tree the runner cannot read, `method.package_invalid`, `security.input_path_refused` or `request.blobs_missing`, as on [`/v1/resolve`](codegen.md#selecting-the-method); for an unreadable root manifest on a request naming no pipe, `method.package_invalid`; and for the selection refusals above, by their codes.
+- **The `method_ref` fetch outcomes**, exactly as on `/v1/resolve`: `404` `method.not_found` when no package in the fetched repository matches the address, `422` for a reference that does not parse (`request.invalid`) or a package the server cannot accept (`method.ambiguous`, `method.package_invalid`), `502` `method.fetch_failed` when the fetch itself failed, and `422` `request.unsupported` for a registry-form reference.
+- **The custom-Python policy of `/v1/validate` and the run routes**, whose tree the route loads: a `501` `pipelex.deployment.custom_code_requires_sandbox` for a tree holding a `.py` file on a deployment that is not sandbox-hosted, where loading the library would import each `.py` declaring a structure class and run its module-level code in the server's process, and a `422` `pipelex.deployment.python_structures_refused` for one whose Python declares a structure class.
+- **`401` / `403`** for authentication, a `403` `auth.forbidden` naming `read_scope_under_caller` among them, and **`413`** `request.too_large` for a body over the size limit.
- **`500`** when an artifact cannot be derived: a pipe whose input or output JSON Schema cannot be rendered raises `PipeIOContractError`, which answers `500` as it does on `/v1/validate` — a fault of the tool, not a verdict about the method.
diff --git a/docs/api-server/pipe-run.md b/docs/api-server/pipe-run.md
index 726968cf6..d1e228510 100644
--- a/docs/api-server/pipe-run.md
+++ b/docs/api-server/pipe-run.md
@@ -10,7 +10,7 @@ Execute a Pipelex pipeline with flexible inputs and wait for completion.
**Endpoint:** `POST /v1/execute`
-> **Backend selected by `orchestration_mode`.** `/execute` dispatches through the deployment's `orchestration_mode` (config default + optional policy-gated per-request `orchestration_mode` override), symmetric with `/start` — see [Configuration → Orchestration mode](configuration.md). On the orchestrator-agnostic base (`direct`, the default) it runs **in-process**; a `temporal` flavor dispatches the run to a worker and awaits it. `/execute` is **synchronous** (it returns the full output) and always uses `BLOCKING` delivery — wait-semantics is endpoint-set, never requestable, so there is no fire-and-forget option here (use `POST /v1/start`). A per-request backend override is honored only where the deployment sets `allow_request_orchestration_mode_override = true`; otherwise a token differing from the default is refused with a `403`.
+> **Backend selected by `orchestration_mode`.** `/execute` dispatches through the deployment's `orchestration_mode` (config default + optional policy-gated per-request `orchestration_mode` override), symmetric with `/start` — see [Configuration → Orchestration mode](configuration.md). On the orchestrator-agnostic base (`direct`, the default) it runs **in-process**; a `temporal` flavor dispatches the run to a worker and awaits it. `/execute` is **synchronous** (it returns the full output) and always uses `BLOCKING` delivery — wait-semantics is endpoint-set, never requestable, so there is no fire-and-forget option here (use `POST /v1/start`). A per-request backend override is honored only where the deployment sets `allow_request_orchestration_mode_override = true`; otherwise a token differing from the default is refused with a `422` `pipelex.deployment.orchestration_override_forbidden`.
**Request Body:**
@@ -94,7 +94,7 @@ Start a pipeline execution and get its `pipeline_run_id` back with a `202` ack.
**Endpoint:** `POST /v1/start`
-> **Fire-and-forget is a property of this endpoint, honored only by an async-capable backend.** `orchestration_mode` names only the deployment's backend; `/start` sets `FIRE_AND_FORGET` delivery and requires an orchestrator that can honor it. A Temporal deployment (`orchestration_mode = "temporal"`) enqueues the run and returns immediately with a `workflow_id`. On the orchestrator-agnostic base (`orchestration_mode = "direct"`, the default — see [Configuration → Orchestration mode](configuration.md)) the in-process orchestrator is blocking-only, so `/start` is **HONEST**: it refuses with a `400` (`StartRequiresAsyncOrchestration`) — use `POST /v1/execute` — rather than silently running blocking and acking. The completion callback fires on the async path.
+> **Fire-and-forget is a property of this endpoint, honored only by an async-capable backend.** `orchestration_mode` names only the deployment's backend; `/start` sets `FIRE_AND_FORGET` delivery and requires an orchestrator that can honor it. A Temporal deployment (`orchestration_mode = "temporal"`) enqueues the run and returns immediately with a `workflow_id`. On the orchestrator-agnostic base (`orchestration_mode = "direct"`, the default — see [Configuration → Orchestration mode](configuration.md)) the in-process orchestrator is blocking-only, so `/start` is **HONEST**: it refuses with a `501` `runtime.unsupported` naming the capability `asynchronous execution` — use `POST /v1/execute` — rather than silently running blocking and acking. The completion callback fires on the async path.
**Request Body:**
@@ -165,7 +165,7 @@ Start a pipeline execution and get its `pipeline_run_id` back with a `202` ack.
- `finished_at` (null): Always `null`; the pipeline hasn't completed.
- `main_stuff_name` (null): Always `null`; populated only on the eventual completion callback.
- `pipe_output` (null): Always `null`; the result isn't ready yet.
-- `workflow_id` (string | null): The async orchestrator's workflow ID. A `202` ack is only ever returned by an async-capable backend (e.g. a Temporal flavor), so this carries that orchestrator's id; the in-process `direct` base never acks here — it returns a `400` (`StartRequiresAsyncOrchestration`) instead.
+- `workflow_id` (string | null): The async orchestrator's workflow ID. A `202` ack is only ever returned by an async-capable backend (e.g. a Temporal flavor), so this carries that orchestrator's id; the in-process `direct` base never acks here — it returns a `501` `runtime.unsupported` instead.
- `method_provenance` (object | null): `{address, tag, commit_sha}` for a `method_ref` run — see [Running a method by address](#running-a-method-by-address-method_ref); `null` for runs from inline source or a bundle.
- `crate_fingerprint` (string | null): **Pipelex extension.** The fingerprint of the library crate the run's job was built from, as on the `/execute` result, known as soon as the run is queued, so a host records it from the acknowledgement.
@@ -183,7 +183,7 @@ Start a pipeline execution and get its `pipeline_run_id` back with a `202` ack.
}
```
-A callback URL is refused before anything runs with a **422** `InvalidCallbackUrls` when its scheme is not `http` or `https`, or when its host is one the runtime's SSRF rule refuses: `localhost`, a cloud metadata name such as `metadata.google.internal` in any case and with or without a trailing dot, or a literal address that is not publicly routable, a loopback, private, link-local, carrier-grade NAT or cloud metadata address among them. It is the rule the delivery applies again when the webhook fires, resolving the name, and such a refusal also writes a [security event](logging.md#security-events). A callback URL that is not a URL at all, empty, longer than the limit, with no scheme or naming no host, is refused with the same 422 and writes none.
+A callback URL is refused before anything runs with a **422** `security.input_url_refused` when its scheme is not `http` or `https`, or when its host is one the runtime's SSRF rule refuses: `localhost`, a cloud metadata name such as `metadata.google.internal` in any case and with or without a trailing dot, or a literal address that is not publicly routable, a loopback, private, link-local, carrier-grade NAT or cloud metadata address among them. A scheme-relative URL, such as `//169.254.169.254/latest/meta-data`, is refused the same way when its host is one the rule refuses. It is the rule the delivery applies again when the webhook fires, resolving the name, and such a refusal also writes a [security event](logging.md#security-events). A callback URL that is not a URL at all, empty, longer than the limit, with no scheme, naming no host, or opening no authority with `//`, such as `example.com:8080/hook` or `localhost:3000/cb`, is a **422** `request.invalid` naming the field `callback_urls` and writes none.
When the pipeline completes, each URL in the list receives a POST carrying:
@@ -236,17 +236,17 @@ The receiver-side secret must be the same value. In typical deployments both sid
}
```
-**One rule for every path.** The map is the tree: the runner reads it with the standard's reader and holds every key to the tree's one rule, whatever form the method came in. A key that is not a tree path (absolute, with a `.` or `..` segment, an empty segment, a backslash, a colon), a key the membership rule keeps out of every tree (a dotfile or a file under a dot directory such as `.mthds/`, `.git/` or `.env`, `__pycache__/`, `node_modules/`), one key given twice, two keys naming one file once normalized, or a file that is another entry's directory is a `422 InvalidMethodFiles` whose `tree_refusal` member gives the standard's refusal `code` and the `names` it refuses; a malformed entry, such as a size written `13.0`, is refused the same way. A zip's member names are judged by the same rule, so a name given twice in an archive is a duplicate key.
+**One rule for every path.** The map is the tree: the runner reads it with the standard's reader and holds every key to the tree's one rule, whatever form the method came in. A key that is not a tree path (absolute, with a `.` or `..` segment, an empty segment, a backslash, a colon), a key the membership rule keeps out of every tree (a dotfile or a file under a dot directory such as `.mthds/`, `.git/` or `.env`, `__pycache__/`, `node_modules/`), one key given twice, two keys naming one file once normalized, or a file that is another entry's directory is a `422` `method.package_invalid` whose `reason` is the standard's refusal code, such as `invalid_tree_path`, `excluded_name`, `duplicate_key` or `path_collision`, and whose `path` is the first name it refuses; a key that would leave the tree's root, absolute or climbing with `..`, is the security refusal `security.input_path_refused`, naming the `rule` it broke, never the path. A malformed entry, such as a size written `13.0`, is a `422` `request.invalid` naming the field. A zip's member names are judged by the same rule, so a name given twice in an archive is a duplicate key.
**The tree is written whole and loaded as the caller's.** The runner writes the tree into a temporary directory, exactly as the map holds it, and loads it as one library directory that belongs to the caller: every bundle is a member of the tree and is named by its tree path, every other file is one a step may read where the bundle sits, a `PipeDocGen` template beside its bundle or a `PipeFunc` module at the tree's import root, and a refusal of the load is the caller's `422`, or an `is_valid: false` verdict on `/validate`, naming files by their tree paths and never by the directory on the server. The directory is removed once the request returns, and the run's job names the tree by its digest, so an orchestrator that runs the job remotely reads its files from the deployment's method file store.
-**The entry pipe.** With no `pipe_code`, the run starts at the pipe the MTHDS protocol's rule names: the `main_pipe` of the `METHODS.toml` at the tree's root, in the bundle of a domain exporting it, or, in a tree with no manifest, the one `main_pipe` its bundles declare. A manifest declaring none, or bundles declaring none or several, is a `422 MethodEntryError` naming the bundles by their tree paths; name the pipe with `pipe_code` instead.
+**The entry pipe.** With no `pipe_code`, the run starts at the pipe the MTHDS protocol's rule names: the `main_pipe` of the `METHODS.toml` at the tree's root, in the bundle of a domain exporting it, or, in a tree with no manifest, the one `main_pipe` its bundles declare. A manifest declaring none, or bundles declaring none or several, is a `422` `request.pipe_unspecified`, which names the bundles' `main_pipe`s as its `candidates` when they declare several; name the pipe with `pipe_code` instead.
-**Limits.** A tree is bounded before any of its bytes is read, on the sizes its entries state, and again once read: at most `MAX_METHOD_TREE_FILES` files (default 1,000), `MAX_METHOD_TREE_FILE_KIB` per file (default 32 MiB) and `MAX_METHOD_TREE_TOTAL_KIB` in all (default 64 MiB), each tree of a request counted on its own, and, across the method's tree and the dependency trees beside it, at most `MAX_METHOD_DEPENDENCIES` dependency trees (default 32) and `MAX_METHOD_REQUEST_TOTAL_KIB` in all (default 128 MiB), refused with a `422 MethodTreeTooLarge` naming the limit. A `bundle_b64` archive is also bounded as an archive: a member-count ceiling (`MAX_BUNDLE_FILES`) and a decompressed-size ceiling (`MAX_BUNDLE_TOTAL_KIB`), each a `413 PayloadTooLarge`, its decompression bounded so a zip bomb cannot expand past the ceiling, and an oversized `bundle_b64` refused on its encoded length before it is decoded. Supplying both `bundle_b64` and `files`, an empty archive or a corrupt zip is a `422 InvalidBundle`, invalid base64 a `400 InvalidBase64`, and a tree holding no `.mthds` bundle of its own a `422 InvalidBundle`.
+**Limits.** A tree is bounded before any of its bytes is read, on the sizes its entries state, and again once read: at most `MAX_METHOD_TREE_FILES` files (default 1,000), `MAX_METHOD_TREE_FILE_KIB` per file (default 32 MiB) and `MAX_METHOD_TREE_TOTAL_KIB` in all (default 64 MiB), each tree of a request counted on its own, and, across the method's tree and the dependency trees beside it, at most `MAX_METHOD_DEPENDENCIES` dependency trees (default 32) and `MAX_METHOD_REQUEST_TOTAL_KIB` in all (default 128 MiB), refused with a `422` `method.package_invalid` whose `reason` names the limit, `too_many_files`, `file_too_large`, `tree_too_large`, `too_many_dependencies` or `method_too_large`, and whose `limit` gives it. A `bundle_b64` archive is also bounded as an archive: a member-count ceiling (`MAX_BUNDLE_FILES`) and a decompressed-size ceiling (`MAX_BUNDLE_TOTAL_KIB`), each a `422` `method.package_invalid` with the reason of its own limit, `bundle_too_many_files` or `bundle_too_large`, its decompression bounded so a zip bomb cannot expand past the ceiling, and an oversized `bundle_b64` refused on its encoded length before it is decoded, as a `413` `request.too_large`. Supplying both `bundle_b64` and `files` is a `422` `request.invalid`, invalid base64 or a corrupt zip a `422` `request.malformed` with the reason `bad_base64` or `bad_zip`, an archive holding no file a `422` `request.invalid` naming `bundle_b64`, and a tree holding no `.mthds` bundle of its own a `422` `method.package_invalid` with the reason `no_bundle`.
-**Files sent in `resources` join the tree.** Beside a tree, each file of [`resources`](pipe-validate.md#sending-the-files-the-steps-read-resources) is added at its path from the tree's root: a file the tree already holds must have the same bytes, or it is a `422 InvalidResourcePath` naming the path, and a file no step names is kept like any other file of the tree. The tree they make is held to the tree's limits again, so files that take it past one are a `422 MethodTreeTooLarge`.
+**Files sent in `resources` join the tree.** Beside a tree, each file of [`resources`](pipe-validate.md#sending-the-files-the-steps-read-resources) is added at its path from the tree's root: a file the tree already holds must have the same bytes, or it is a `422` `request.invalid` naming the field `resources`, and a file no step names is kept like any other file of the tree. The tree they make is held to the tree's limits again, so files that take it past one are a `422` `method.package_invalid` naming the limit.
-**Sandbox-hosted only for custom Python.** A tree that holds any `.py` file is honored **only on a sandbox-hosted deployment**, where the load reads the source without importing it and execution happens in an isolated sandbox. On a deployment that is not sandbox-hosted it is refused with `403 CustomCodeRequiresSandbox` before anything is written: running caller-supplied code in-process is never done implicitly. A tree without Python is accepted on any deployment.
+**Sandbox-hosted only for custom Python.** A tree that holds any `.py` file is honored **only on a sandbox-hosted deployment**, where the load reads the source without importing it and execution happens in an isolated sandbox. On a deployment that is not sandbox-hosted it is refused with a `501` `pipelex.deployment.custom_code_requires_sandbox`, whose `origin` is `bundle`, before anything is written: running caller-supplied code in-process is never done implicitly. A tree without Python is accepted on any deployment.
**No Python structure classes.** A structure class (a `StructuredContent` subclass) can only be used by importing its module into the runner's own process, which a sandbox-hosted deployment never does, so a tree whose Python declares one is refused with a `422` problem, `pipelex.deployment.python_structures_refused`, before anything is loaded; its operator view's message names each file and class. The rule is the same however the method arrives: sent as a tree, or fetched by `method_ref`. Declare the types as MTHDS concepts with inline structures instead; a PipeFunc returns them by importing the classes the sandbox generates from those concepts (`from structures import <domain>__<Concept>`). The `structures` module that `pipelex build structures` writes is accepted as long as it is left as generated, and it is not sent to the sandbox, which generates its own.
@@ -261,15 +261,15 @@ This runner keeps a **blob store**, declared by `blob_store: true` in [`GET /v1/
3. It uploads each missing blob as the answer says: the blob's bytes as the whole body of a request with the answer's `method` to its `url`, carrying exactly its `headers`.
4. It sends the run, or the validation, with a hash entry for each file it chose to send by hash.
-The answer is `{"missing": [{"sha256": "…", "size": n, "upload": {"method": "PUT", "url": "…", "headers": {"content-type": "application/octet-stream"}}}, …]}`, listing only the blobs the runner does not hold; an empty list means there is nothing to upload. Each target is the runner's own `PUT /v1/blobs/{sha256}`, its query signed for that hash and the caller's scope and valid for `BLOB_UPLOAD_URL_TTL_SECONDS` (default an hour). The target starts with `PUBLIC_BASE_URL` when the deployment sets it, the address its clients reach the API at, which a deployment behind a proxy terminating TLS or adding a path prefix sets, and otherwise with the URL the request arrived at. The upload route needs no bearer token, since the signed target is its authorization: a missing, malformed, forged or expired signature is a `403 BlobUploadNotAuthorized`, a body whose SHA-256 is not the path's a `422 BlobMismatch`, and a body past `MAX_METHOD_TREE_FILE_KIB` a `422 MethodTreeTooLarge`. A blob is written whole and never changed, so uploading bytes the runner holds answers `204` and changes nothing. On `POST /v1/blobs/missing`, one hash listed with two sizes is a `422 BlobMismatch`, and blobs past the tree limits a `422 MethodTreeTooLarge`, both before anything is uploaded.
+The answer is `{"missing": [{"sha256": "…", "size": n, "upload": {"method": "PUT", "url": "…", "headers": {"content-type": "application/octet-stream"}}}, …]}`, listing only the blobs the runner does not hold; an empty list means there is nothing to upload. Each target is the runner's own `PUT /v1/blobs/{sha256}`, its query signed for that hash and the caller's scope and valid for `BLOB_UPLOAD_URL_TTL_SECONDS` (default an hour). The target starts with `PUBLIC_BASE_URL` when the deployment sets it, the address its clients reach the API at, which a deployment behind a proxy terminating TLS or adding a path prefix sets, and otherwise with the URL the request arrived at. The upload route needs no bearer token, since the signed target is its authorization: a missing, malformed, forged or expired signature is a `403` `auth.forbidden` whose `requirement` is `signed_upload_target`, a body whose SHA-256 is not the path's a `422` `request.invalid` naming the field `body`, and a body past `MAX_METHOD_TREE_FILE_KIB` a `413` `request.too_large`. A blob is written whole and never changed, so uploading bytes the runner holds answers `204` and changes nothing. On `POST /v1/blobs/missing`, one hash listed with two sizes is a `422` `request.invalid` naming the field `blobs`, and blobs past the tree limits a `422` `method.package_invalid` naming the limit, both before anything is uploaded.
**Writes are create-only.** The runner creates a blob, or a tree's listing, only when its key holds nothing, and never replaces an object already there: on S3 the write carries `If-None-Match: *` and its SHA-256 as `x-amz-checksum-sha256`, which S3 checks against the body, on GCS it is conditional on generation 0, and on the local filesystem the file is created through a hard link, so the local storage's folder must sit on a filesystem that supports them. A key already holding an object is the object already held, the same bytes since the key is their hash, and the write succeeds without changing it. A deployment's bucket can therefore refuse every unconditional write under `blobs/` and `trees/` without refusing any of the runner's, as the hosted platform's does.
-**Sizes.** A blob is held at a size, which the runner reads from the storage's metadata without reading the bytes. `POST /v1/blobs/missing` lists a blob the runner does not hold at the size the sender states, an object held at another size included. Its upload then tells the two cases apart: bytes of the size held are the ones held, and change nothing, while bytes of another size mean the object held is damaged, which only a storage that does not publish a write whole could leave, a `500 BlobStoreCorrupted`, since nothing writes over a blob and the deployment's operator removes the object for it to be uploaded again. On a run or a validation, every hash entry is looked up by size before any byte is read: a hash the runner holds at another size than the entry states is a `422 BlobMismatch` whose `mismatched_blobs` member gives each hash with its `held_size`, since the bytes under a hash have one size and uploading them again would change nothing, so the entry's size is the one to correct. Only bytes held at the size their entry states are read, a bounded number at a time, and checked against their hash; bytes that do not hash to their key mean the deployment's storage is damaged, a `500 BlobStoreCorrupted` that its operator repairs by removing the object, for it to be uploaded again.
+**Sizes.** A blob is held at a size, which the runner reads from the storage's metadata without reading the bytes. `POST /v1/blobs/missing` lists a blob the runner does not hold at the size the sender states, an object held at another size included. Its upload then tells the two cases apart: bytes of the size held are the ones held, and change nothing, while bytes of another size mean the object held is damaged, which only a storage that does not publish a write whole could leave, a `500` `pipelex.storage.damaged` naming the kind of storage, whose verdict is not to retry, since nothing writes over a blob and the deployment's operator removes the object for it to be uploaded again. On a run or a validation, every hash entry is looked up by size before any byte is read: a hash the runner holds at another size than the entry states is a `422` `request.invalid` naming the field the entry is in, since the bytes under a hash have one size and uploading them again would change nothing, so the entry's size is the one to correct; the operator view's `diagnostics.message` names each such hash with the size it is held at. Only bytes held at the size their entry states are read, a bounded number at a time, and checked against their hash; bytes that do not hash to their key mean the storage holds a damaged object, a `500` `pipelex.storage.damaged` naming the kind of storage, whose verdict is not to retry, since a retry reads the same object. In both cases the operator repairs it by removing the object the line `Stored blob bytes do not match their hash` names under `blob_sha256`, for it to be uploaded again.
**The digest shortcut.** Once the runner has read a request's tree in full, it records the tree's listing beside its blobs, after every file it names is held, and an upload never records one. A validation records it only when its request carries a `read_scope`: without one, its scope would be the caller's own id, where a dry run must leave nothing stored. Asking `POST /v1/blobs/missing` with the digest of a recorded tree then answers an empty list in one lookup, however many files the tree has, when every blob listed is a file of that tree; a blob outside it is looked up as if no digest were sent.
-**Scopes.** Blobs live in the deployment's configured storage, under `<scope>/blobs/<sha256>`, and recorded listings under `<scope>/trees/<digest>`. The scope is the request's `read_scope`, which a multi-tenant host sends for the organization it serves (a query parameter on `POST /v1/blobs/missing`, a body field on the run and validate routes), else the caller's own id, so a hash entry resolves only in the caller's own blobs and asking whether a hash is held tells a caller nothing of another's files. On a `jwt` deployment a sent scope must lie under the caller's own id, else a `403 ReadScopeForbidden` (see [Host-supplied run context](#host-supplied-run-context-storage_scope-and-analytics_groups)). A hash entry the runner does not hold, at the size it states, is a `422 MissingBlobs` whose `missing_blobs` member lists the hashes to upload before sending the request again.
+**Scopes.** Blobs live in the deployment's configured storage, under `<scope>/blobs/<sha256>`, and recorded listings under `<scope>/trees/<digest>`. The scope is the request's `read_scope`, which a multi-tenant host sends for the organization it serves (a query parameter on `POST /v1/blobs/missing`, a body field on the run and validate routes), else the caller's own id, so a hash entry resolves only in the caller's own blobs and asking whether a hash is held tells a caller nothing of another's files. On a `jwt` deployment a sent scope must lie under the caller's own id, else a `403` `auth.forbidden` whose `requirement` is `read_scope_under_caller` (see [Host-supplied run context](#host-supplied-run-context-storage_scope-and-analytics_groups)). A hash entry the runner does not hold, at the size it states, is a `422` `request.blobs_missing` whose `missing_blobs` parameter lists the hashes to upload before sending the request again.
**Signing key.** Each process draws its own signing key unless `BLOB_UPLOAD_SIGNING_KEY` is set. A deployment serving one API through several instances must set it, the same on every instance, since an upload may reach another instance than the one that named its target.
@@ -277,7 +277,7 @@ The answer is `{"missing": [{"sha256": "…", "size": n, "upload": {"method": "P
A method can call a pipe of another method package by its address, such as `github.com/Pipelex/methods/documents->documents.extract_page_contents_and_views`. A request can carry that package with the method, so the run needs no copy installed on the server and no fetch:
-- **With `files`**, send each package in `dependencies`, a map from the package's address to the package's own map of file entries, its `METHODS.toml` at its root declaring that address. A package keyed by another address than its manifest declares is a `422 InvalidMethodFiles`; `dependencies` without `files` is a `422` `PipelexRequestError` carrying the code `request.invalid`.
+- **With `files`**, send each package in `dependencies`, a map from the package's address to the package's own map of file entries, its `METHODS.toml` at its root declaring that address. A package keyed by another address than its manifest declares is a `422` `request.invalid` naming the field `dependencies`, and so is `dependencies` without `files`.
- **In a `bundle_b64` archive**, put each package under `.mthds/methods/<name>/`, with its `METHODS.toml` at `.mthds/methods/<name>/METHODS.toml`, which is the layout of a local method store. The store's `.provenance.json` sidecar is left out of the package.
```text
@@ -292,7 +292,7 @@ bundle.mthds
- **Its Python never runs in the server's process.** A `.py` file in a shipped package counts for the sandbox gate like any other. On a sandbox-hosted deployment, a shipped package whose Python declares a structure class is refused with the same `422` `pipelex.deployment.python_structures_refused`, as a package fetched by address is.
- **A shipped bundle that does not parse refuses the run** with the `422` verdict, whose items name the file as `<address>/<path inside the package>`, never by a path on the server.
-Two shipped packages a reference could not tell apart, whose manifests declare the same address and name compared without regard to case, the name being the directory's when the manifest has none, are a `422 InvalidMethodFiles` naming the address, since nothing but their order would decide which one answers. In an archive, a package directory without a valid `METHODS.toml` is refused the same way, and any other entry under `.mthds/`, such as a file directly under `.mthds/methods/`, one under a directory whose name no package's directory can take, such as a dot directory, or a package's own `.mthds/` store, is refused by the tree's rule; a package fetched by `method_ref` holds its `.mthds/methods/` to the same rule, its other entries left out of its tree. A package whose manifest declares no name takes the last segment of its address, which must then be a name a directory can take: a dependency keyed by an address ending in `.` or `..` with a nameless manifest is a `422 InvalidMethodFiles`.
+Two shipped packages a reference could not tell apart, whose manifests declare the same address and name compared without regard to case, the name being the directory's when the manifest has none, are a `422` `method.package_invalid` with the reason `dependency_address_collision`, whose `path` is the second package's directory, since nothing but their order would decide which one answers. In an archive, a package directory without a valid `METHODS.toml` is a `422` `method.package_invalid` with the reason `manifest_missing` or `manifest_invalid`, naming the manifest's path, and any other entry under `.mthds/`, such as a file directly under `.mthds/methods/`, one under a directory whose name no package's directory can take, such as a dot directory, or a package's own `.mthds/` store, is refused by the tree's rule; a package fetched by `method_ref` holds its `.mthds/methods/` to the same rule, its other entries left out of its tree. A package whose manifest declares no name takes the last segment of its address, which must then be a name a directory can take: a dependency keyed by an address ending in `.` or `..` with a nameless manifest is a `422` `method.package_invalid` with the reason `package_name_invalid`.
The validation of a method sent as a tree, or fetched by `method_ref`, loads its shipped packages too, so `/validate` resolves a dependency the run would resolve.
@@ -317,11 +317,11 @@ Both `/execute` and `/start` accept **`method_ref`** — a globally resolvable a
**Provenance.** The response carries `method_provenance = {address, tag, commit_sha, tree_digest}` — on `/execute` only for `method_ref` runs, on the `/start` ack as a nullable field. Tags can move; the recorded SHA is what keeps a run explainable after the fact, and `tree_digest` names the exact tree the run loaded.
-**Custom Python follows the tree rules, plus one more.** What decides is *where the code would execute*: `.mthds` content is data, always acceptable. On a deployment that is **not** sandbox-hosted, a fetched package carrying any `.py` is refused with `403 CustomCodeRequiresSandbox`. On a sandbox-hosted deployment, PipeFunc `.py` is accepted (captured as text, executed in the isolated sandbox) — but a package declaring **Python structure classes** (`StructuredContent` subclasses) is refused with a `422` (`pipelex.deployment.python_structures_refused`), exactly as a tree sent with the request is: see [No Python structure classes](#sending-a-method-as-a-tree).
+**Custom Python follows the tree rules, plus one more.** What decides is *where the code would execute*: `.mthds` content is data, always acceptable. On a deployment that is **not** sandbox-hosted, a fetched package carrying any `.py` is refused with a `501` `pipelex.deployment.custom_code_requires_sandbox`, whose `origin` is `package`. On a sandbox-hosted deployment, PipeFunc `.py` is accepted (captured as text, executed in the isolated sandbox) — but a package declaring **Python structure classes** (`StructuredContent` subclasses) is refused with a `422` (`pipelex.deployment.python_structures_refused`), exactly as a tree sent with the request is: see [No Python structure classes](#sending-a-method-as-a-tree).
-**Errors.** Every resolution failure is an RFC 9457 `problem+json` named by its code, or by its `error_type` for the one refusal the API authors itself (see [Error responses](error-responses.md)):
+**Errors.** Every resolution failure is an RFC 9457 `problem+json` named by its code (see [Error responses](error-responses.md)):
-| Failure | Status | `code` or `error_type` |
+| Failure | Status | `code` |
|---|---|---|
| Reference does not match the grammar | 422 | `request.invalid` |
| Repository could not be fetched | 502 | `method.fetch_failed` |
@@ -329,13 +329,13 @@ Both `/execute` and `/start` accept **`method_ref`** — a globally resolvable a
| More than one package matches | 422 | `method.ambiguous` |
| Package exceeds the fetched-package ceilings, or contains a symlink (file or directory) | 422 | `method.package_invalid` |
| Package declares Python structure classes | 422 | `pipelex.deployment.python_structures_refused` |
-| Package ships `.py` on a non-sandbox deployment | 403 | `CustomCodeRequiresSandbox` |
+| Package ships `.py` on a non-sandbox deployment | 501 | `pipelex.deployment.custom_code_requires_sandbox` |
**The clone cache.** Fetched repositories are cached on local disk **keyed by resolved commit SHA** — never by tag. Each request first resolves the reference to its current SHA with a cheap `git ls-remote` (no clone); a cached SHA is reused, a new one (a moved tag, an advanced HEAD) triggers a fresh clone. The cache is per server instance and bounded by count, total bytes, and age, oldest first; a clone a request is still reading is never evicted, though it counts toward the bounds. That protection holds within one process, so a deployment running several worker processes gives each its own `METHOD_CACHE_DIR`.
**Environment knobs.** The cache: `MAX_METHOD_CACHE_CLONES` (default 64), `MAX_METHOD_CACHE_TOTAL_KIB` (default 512 MiB), `MAX_METHOD_CACHE_AGE_HOURS` (default 24), `METHOD_CACHE_DIR` (default: a fixed directory under the system temp dir). The fetch itself is bounded by the pipelex runtime's fetched-package ceilings: `PIPELEX_MAX_FETCHED_PACKAGE_FILES` (default 256), `PIPELEX_MAX_FETCHED_PACKAGE_TOTAL_KIB` (default 8 MiB), and the manifest-scan bounds `PIPELEX_MAX_SCANNED_MANIFESTS` (default 100 manifests considered per fetched repository) and `PIPELEX_MAX_MANIFEST_FILE_KIB` (default 256 KiB per `METHODS.toml` read during package location). All are read once at process start.
-`method_ref` also selects the method on the tooling routes: on [`POST /v1/validate`](pipe-validate.md), [`/resolve` and `/codegen`](codegen.md#selecting-the-method) and [`/pipe-io`](pipe-io.md), which read the fetched package's tree as a run does (address form resolved; on the crate routes the registry form stays a `501`).
+`method_ref` also selects the method on the tooling routes: on [`POST /v1/validate`](pipe-validate.md), [`/resolve` and `/codegen`](codegen.md#selecting-the-method) and [`/pipe-io`](pipe-io.md), which read the fetched package's tree as a run does (address form resolved; on the crate routes the registry form is a `422` `request.unsupported`).
---
@@ -353,9 +353,9 @@ Both `/execute` and `/start` accept optional fields that describe the run's tena
}
```
-**`storage_scope`** is the prefix every object the run writes lands under: one to three path-safe segments, onto which the runtime composes its own leaves (`assets/`, `generated/`, `results/`, `payloads/`). Omit it and the run is scoped to the caller's own id, which is right for a single-tenant deployment and wrong for a multi-tenant one: a host serving many tenants must send it. Each segment is one or more characters from `A-Za-z0-9_-`, so an empty segment, a leading or trailing slash, a `.` or `..`, or a fourth segment is refused with a `422` whose `error_type` is `InvalidStorageScope`.
+**`storage_scope`** is the prefix every object the run writes lands under: one to three path-safe segments, onto which the runtime composes its own leaves (`assets/`, `generated/`, `results/`, `payloads/`). Omit it and the run is scoped to the caller's own id, which is right for a single-tenant deployment and wrong for a multi-tenant one: a host serving many tenants must send it. Each segment is one or more characters from `A-Za-z0-9_-`, so an empty segment, a leading or trailing slash, a `.` or `..`, or a fourth segment is refused with a `422` `request.invalid` naming the field `storage_scope`.
-**`read_scope`** bounds what the run may read: every `pipelex-storage://` key the run reads, whether an input, a URL a pipe builds or an image it shows a model, must lie under it, and a scoped run reads no local path at all. It follows the same segment rule as `storage_scope`, and the storage scope must be the read scope or lie under it, since a run reads back what it writes: `org_acme` covers `org_acme/method_42/run_7`, while `org_other` does not. Omit it and the run is scoped to the caller's own id when the deployment identifies its callers, which is also where their writes land by default, and unscoped when the deployment is single-tenant. A host serving many tenants must send it: a host that sends its own `storage_scope` but no `read_scope` is refused, since that storage scope lies under no caller's id. A malformed read scope, a storage scope outside it, or the local storage scope `local` beside one is a `422` whose `error_type` is `InvalidReadScope`, answered before any method is fetched or library loaded. **On a `jwt` deployment the read scope is bound to the caller**: the caller reaches the runner with its own token rather than through a trusted host, so a read scope it sends must be its token's `user_id` or lie under it, else the request is a `403` whose `error_type` is `ReadScopeForbidden`, answered before anything is read. Every route taking a `read_scope` applies the same rule (`/v1/validate`, `/v1/resolve`, `/v1/codegen`, `/v1/pipe-io` and `POST /v1/blobs/missing` too), and since the storage scope must lie under the read scope, a `jwt` caller writes only under its own id as well. With `AUTH_MODE=none` and the shared `api_key`, the caller is a trusted host or a single tenant, and the scope it sends is taken as it is. A read the scope does not allow is refused when the run makes it, with the `error_type` `UriReadRefusedError`, whose message says where the URL sat without quoting it. On `/execute` it is a `422`. On `/start` it is a synchronous `422` when an input breaks the rule, and a run that ends `FAILED` with that error in its completion callback when a pipe reaches for the URL during the run.
+**`read_scope`** bounds what the run may read: every `pipelex-storage://` key the run reads, whether an input, a URL a pipe builds or an image it shows a model, must lie under it, and a scoped run reads no local path at all. It follows the same segment rule as `storage_scope`, and the storage scope must be the read scope or lie under it, since a run reads back what it writes: `org_acme` covers `org_acme/method_42/run_7`, while `org_other` does not. Omit it and the run is scoped to the caller's own id when the deployment identifies its callers, which is also where their writes land by default, and unscoped when the deployment is single-tenant. A host serving many tenants must send it: a host that sends its own `storage_scope` but no `read_scope` is refused, since that storage scope lies under no caller's id. A malformed read scope, a storage scope outside it, or the local storage scope `local` beside one is a `422` `request.invalid` naming the field `read_scope`, answered before any method is fetched or library loaded. **On a `jwt` deployment the read scope is bound to the caller**: the caller reaches the runner with its own token rather than through a trusted host, so a read scope it sends must be its token's `user_id` or lie under it, else the request is a `403` `auth.forbidden` whose `requirement` is `read_scope_under_caller`, answered before anything is read. Every route taking a `read_scope` applies the same rule (`/v1/validate`, `/v1/resolve`, `/v1/codegen`, `/v1/pipe-io` and `POST /v1/blobs/missing` too), and since the storage scope must lie under the read scope, a `jwt` caller writes only under its own id as well. With `AUTH_MODE=none` and the shared `api_key`, the caller is a trusted host or a single tenant, and the scope it sends is taken as it is. A read the scope does not allow is refused when the run makes it, as the security refusal `security.input_url_refused`, which says where the URL sat without quoting it. On `/execute` it is a `422`. On `/start` it is a synchronous `422` when an input breaks the rule, and a run that ends `FAILED` with that error in its completion callback when a pipe reaches for the URL during the run.
**`analytics_groups`** names the entities the run's telemetry belongs to, as a mapping of group type to group key. The runtime carries it on the run as its opaque `extras` and stamps it on every span of the run as the attribute `pipelex.run.extras`, so every OpenTelemetry exporter receives it, and the deployment's own PostHog stream, when `telemetry.toml` sets `mode = "identified"`, attaches it to each capture as PostHog groups. That is what lets a generation made for one of your customers appear inside that customer's organization instead of under one identity for the whole deployment. The rules are the runtime's own, imported rather than restated here:
@@ -364,7 +364,7 @@ Both `/execute` and `/start` accept optional fields that describe the run's tena
- The mapping holds **at most five** entries, since a telemetry backend registers only a small fixed number of group types per project.
- It is **optional**. Omitting it, sending `null` or sending `{}` all mean the run belongs to no group, which misattributes nothing.
-A mapping outside these rules is refused with a `422` whose `error_type` is `InvalidAnalyticsGroups`, before any method is fetched or any library loaded. A body that fails on more than one of the extension fields at once answers with the generic `ValidationError`, and its `detail` names every field that failed.
+A mapping outside these rules is refused with a `422` `request.invalid` naming the field `analytics_groups`, or a path into it, before any method is fetched or any library loaded. A body that fails on more than one of the extension fields at once carries one `request.invalid` item per refused field in its `errors`.
The caller's id is the run's person on that same stream, with one exception: a deployment with no user model attributes every run to the literal `single-tenant`, which the runtime declines as a person and replaces with the `user_id` configured in `telemetry.toml`. The groups do not depend on it, so a single-tenant deployment that sends `analytics_groups` still has them on every capture.
@@ -374,7 +374,7 @@ The caller's id is the run's person on that same stream, with one exception: a d
The `inputs` field accepts several shapes. Pipelex picks how to interpret each value from its structure — pass a string to a `Text` input and you get `TextContent`, pass a dict with `concept` and `content` keys and you get explicit concept resolution, etc. The cases below enumerate every supported form.
-**The request body is plain JSON.** The Python objects in Cases 1.3 to 1.5, and the `DictStuff` instances further down, are what a Python caller writes; a Python client of this API serializes each one to plain JSON before sending it, and the server never rebuilds a Python class from the request. The class name does not travel, so each value is read against the entry pipe's declared input. A structured object (Case 1.3) arrives as its fields and a list of them (Case 1.4) as a list of those, and both are read as intended; a `DictStuff` arrives as the Case 2 envelope. A `ListContent` wrapper (Case 1.5) arrives as `{"items": [...]}`, which the server reads as one item rather than a list, and a native `TextContent` arrives as `{"text": ...}`, which a `Text` input refuses: over HTTP, send the bare list of items or strings instead, or the `{"concept": ..., "content": [...]}` envelope of Cases 2.2, 2.4 and 2.6. A body carrying a `__class__` or `__module__` key, or a key starting with `__kajson`, in any object at any depth is refused with a `422 ReservedObjectKey` (see [Error Responses](error-responses.md#status-codes)).
+**The request body is plain JSON.** The Python objects in Cases 1.3 to 1.5, and the `DictStuff` instances further down, are what a Python caller writes; a Python client of this API serializes each one to plain JSON before sending it, and the server never rebuilds a Python class from the request. The class name does not travel, so each value is read against the entry pipe's declared input. A structured object (Case 1.3) arrives as its fields and a list of them (Case 1.4) as a list of those, and both are read as intended; a `DictStuff` arrives as the Case 2 envelope. A `ListContent` wrapper (Case 1.5) arrives as `{"items": [...]}`, which the server reads as one item rather than a list, and a native `TextContent` arrives as `{"text": ...}`, which a `Text` input refuses: over HTTP, send the bare list of items or strings instead, or the `{"concept": ..., "content": [...]}` envelope of Cases 2.2, 2.4 and 2.6. A body carrying a `__class__` or `__module__` key, or a key starting with `__kajson`, in any object at any depth is refused with a `422` `pipelex.security.reserved_key` (see [Error Responses](error-responses.md#status-codes)).
### How Input Formatting Works
diff --git a/docs/api-server/pipe-validate.md b/docs/api-server/pipe-validate.md
index 7c3301f40..3a314c4ce 100644
--- a/docs/api-server/pipe-validate.md
+++ b/docs/api-server/pipe-validate.md
@@ -20,14 +20,14 @@ Validate MTHDS content by parsing, loading, and dry-running pipes without execut
- `files` (object, optional): The method as a map of file entries, the MTHDS standard's method tree, each value the file's text, `{"base64": "…"}` or `{"sha256": "…", "size": n}`, read as on a run — see [Validating a method tree](#validating-a-method-tree). Exactly one of `mthds_contents` / `files` / `method_ref`
- `dependencies` (object, optional): **Pipelex-API extension.** The method packages the method calls by address that the runner cannot fetch, each a map of file entries keyed by its address, as on a [run](pipe-run.md#sending-the-method-packages-the-method-calls). Accompanies `files`
- `method_ref` (string, optional): **Pipelex-API extension.** Validate a published method by address — `github.com/<owner>/<repo>` plus an optional package selector and `@<tag>` — resolved by this server through the same fetch path as a [`method_ref` run](pipe-run.md#running-a-method-by-address-method_ref): the repository is fetched at the tag, the package located by manifest identity, and its tree read from the commit's git objects and validated as a tree sent in `files` is — see [Validating a method tree](#validating-a-method-tree). Exactly one of `mthds_contents` / `files` / `method_ref`; `mthds_sources` cannot accompany it. A package holding Python and a `requirements.txt` has its requirements checked on this server against the packages the deployment's PipeFunc sandbox offers for them before anything is validated, and a requirement the sandbox does not meet, or a line the standard refuses, makes the verdict `is_valid: false` with one item per line, whose `source` is `requirements.txt` and whose `line` is the line's number; a deployment refusing the requirements with its own explanation, no environment it can build holding them, makes it `is_valid: false` with one item on `requirements.txt` and no line
-- `read_scope` (string, optional): **Pipelex-API extension.** The scope the validation reads the method under, as a run's `read_scope`, which a multi-tenant host sends for the organization it serves; [a `jwt` caller may send only a scope under its own id](pipe-run.md#host-supplied-run-context-storage_scope-and-analytics_groups), else a `403 ReadScopeForbidden`. A hash entry of `files` resolves in that scope's blob store — see [Sending files by hash](pipe-run.md#sending-files-by-hash) — and the runner hands the scope to its validator, so a validation dispatched to a worker can hand it the method through that store — see [Where validation runs](#where-validation-runs). Omitted, a hash entry resolves in the caller's own id's store, but only a validation carrying it records the tree it read in the blob store, and the validator is handed no scope, so a dry run without one leaves nothing stored
+- `read_scope` (string, optional): **Pipelex-API extension.** The scope the validation reads the method under, as a run's `read_scope`, which a multi-tenant host sends for the organization it serves; [a `jwt` caller may send only a scope under its own id](pipe-run.md#host-supplied-run-context-storage_scope-and-analytics_groups), else a `403` `auth.forbidden` whose `requirement` is `read_scope_under_caller`. A hash entry of `files` resolves in that scope's blob store — see [Sending files by hash](pipe-run.md#sending-files-by-hash) — and the runner hands the scope to its validator, so a validation dispatched to a worker can hand it the method through that store — see [Where validation runs](#where-validation-runs). Omitted, a hash entry resolves in the caller's own id's store, but only a validation carrying it records the tree it read in the blob store, and the validator is handed no scope, so a dry run without one leaves nothing stored
- `allow_signatures` (boolean, optional, default `false`): controls only the **sweep mechanics** for `PipeSignature` placeholders — whether signature pipes are mock-run during the dry-run sweep and therefore listed in `validated_pipes`. It does **not** change the verdict: an unimplemented signature is never a rejection, it is a *runnability fact* reported via `pending_signatures` + `is_runnable` in both modes
- `mthds_sources` (list[str] | null, optional): per-file sources, parallel to `mthds_contents` — see [Sourcing submitted files](#sourcing-submitted-files). When present it must match `mthds_contents` in length (a mismatch is a 422 request error), and it accompanies `mthds_contents` alone, since a tree's files are named by their tree paths
- `resources` (object | null, optional): **Pipelex-API extension.** The files the bundle's steps read, such as a `PipeDocGen` step's `template_file`, as a map from the path the step names to the file's bytes in standard base64 — see [Sending the files the steps read](#sending-the-files-the-steps-read-resources). It accompanies `mthds_contents` or `files`, whose tree each file joins; beside `method_ref` it is a 422
- `render` (list[str], optional, default `[]`): opt-in *rendered text* to attach to the verdict — see [Opt-in extras](#opt-in-extras-render-and-views)
- `views` (list[str], optional, default `[]`): opt-in *structured views* to attach to the verdict — see [Opt-in extras](#opt-in-extras-render-and-views)
-- `orchestration_mode` (string | null, optional): per-request backend override for the validation dispatch — see [Where validation runs](#where-validation-runs). Honored only when the deployment allows it; a forbidden override is a 403
-- `analytics_groups` (object | null, optional): **Pipelex-API extension.** The groups the caller belongs to, as a mapping of group type to group key, with the same rules as on a run — see [Who the validation is done for](#who-the-validation-is-done-for). A mapping outside those rules is a 422 whose `error_type` is `InvalidAnalyticsGroups`
+- `orchestration_mode` (string | null, optional): per-request backend override for the validation dispatch — see [Where validation runs](#where-validation-runs). Honored only when the deployment allows it; a forbidden override is a 422 `pipelex.deployment.orchestration_override_forbidden`
+- `analytics_groups` (object | null, optional): **Pipelex-API extension.** The groups the caller belongs to, as a mapping of group type to group key, with the same rules as on a run — see [Who the validation is done for](#who-the-validation-is-done-for). A mapping outside those rules is a 422 `request.invalid` naming the field `analytics_groups`
**Response (the verdict union):**
@@ -68,9 +68,9 @@ The 200 body is one of two arms, discriminated on the mandatory `is_valid` field
- `is_valid` (`true`): the discriminant of the valid arm — always `true` on this report
- `bundle_blueprint` (object): the batch's primary blueprint — the first file declaring `main_pipe`, else the first file
- `pipe_io_contracts` (object): per-pipe input/output contracts, keyed by the namespaced `pipe_ref` (`domain.code`). Each input carries its `concept_ref`, `presence`, `multiplicity` (`single` | `variable` | `fixed`), `item_count` and the JSON Schema of its content; the output carries its fully qualified `concept_ref`, `multiplicity`, `item_count`, `optional` and the JSON Schema of its payload. `item_count` is the exact count on `fixed`, always greater than one since `Concept[1]` reads as `single`, and `null` otherwise, so an output declared `Text[3]` reports `"multiplicity": "fixed", "item_count": 3`
-- `graph_spec` (object | null): best-effort execution graph of the pipe a selector-less run of this request would execute — the pipe [`default_pipe_ref`](#the-effective-entry-pipe) names — dry-run against the validated library; `null` when no entry pipe is determined or the graph dry-run degrades
+- `graph_spec` (object, optional): best-effort execution graph of the pipe a selector-less run of this request would execute — the pipe [`default_pipe_ref`](#the-effective-entry-pipe) names — dry-run against the validated library; absent when no entry pipe is determined or the graph dry-run degrades
- `validated_pipes` (list): per-pipe sweep outcomes — `{pipe_ref, status}` entries with status `SUCCESS` | `FAILURE` | `SKIPPED`
-- `warnings` (list): advisory findings that never flip `is_valid`, each with the same shape as a `validation_errors` item, so one parser reads both. Four families, always in this order: the useless-`!` lint (`optional_force_redundant`), the entry-pipe vacuous-presence lint (`input_presence_vacuous`), the intent-hint lints (`hint_unknown_key`, `hint_unknown_intent`, `hint_inapplicable_intent`), and the warnings a `PipeDocGen` step's template check found in its office template file during the dry run (`template_check_warning`, a `dry_run` item carrying `pipe_code`, `domain_code`, `template_file` and `template_location`). Unset locators are `null` on this arm. Empty when there is nothing to report
+- `warnings` (list): advisory findings that never flip `is_valid`, each a problem item with the same shape as an item of the invalid arm's `errors`, so one parser reads both. Four families, always in this order: the useless-`!` lint (`method.optional_force_redundant`), the entry-pipe vacuous-presence lint (`method.input_presence_vacuous`), the intent-hint lints (`method.hint_invalid`, whose `reason` is `unknown_key`, `unknown_intent` or `inapplicable_intent`, whose `hint` names the hint, and whose `location` names the declaration the hint is on: `field` `concept.<Concept>` for a concept, `concept.<Concept>.structure.<field>` for a field of its structure, `pipe` and `input` for a pipe's input), and the warnings a `PipeDocGen` step's template check found in its office template file during the dry run (`pipelex.docgen.template_warning`, whose `template` names the file and `finding` says what the check found, located at the step by its `pipe`). A member an item does not have is absent, never `null`. Empty when there is nothing to report
- `pending_signatures` (list[str]): namespaced refs of pipes still declared as signatures (contract-only pipes — `inputs`/`output` with no `type` and no implementation) in the assembled library — what remains to implement
- `is_runnable` (boolean): `pending_signatures` is empty — whether the validated library is complete enough to run
@@ -78,45 +78,45 @@ The 200 body is one of two arms, discriminated on the mandatory `is_valid` field
- `mthds_contents` (list[str]): echo of the validated request contents
- `message` (string): status message
-- `default_pipe_ref` (string | null): the qualified `domain.pipe_code` a caller gets by **omitting** the pipe selector — the pipe a selector-less run of this same request would execute. See [The effective entry pipe](#the-effective-entry-pipe) below
+- `default_pipe_ref` (string, optional): the qualified `domain.pipe_code` a caller gets by **omitting** the pipe selector — the pipe a selector-less run of this same request would execute; absent when no entry pipe is determined. See [The effective entry pipe](#the-effective-entry-pipe) below
+
+A top-level member the verdict has no value for is **absent** from the body, never written as `null`.
**Response Fields (opt-in, present only when requested):**
- `input_form` (object, valid arm only, requires `views: ["input_form"]`): per-pipe input-form descriptors, keyed by the same namespaced `pipe_ref` as `pipe_io_contracts`. Each entry carries an ordered `fields` list describing what a caller must collect to run that pipe — a field's `kind` (drawn from a closed vocabulary), its `name`, whether it is `required`, whether an empty value should `gate` the run, and the per-kind detail (`choices`, `item_count`, `default_value`, nested `concept_ref`, …). It is a **projection of facts the verdict already states**, derived from what the bundle authored rather than from the emitted JSON Schema, so a client can render a run form from the verdict alone
- `output_form` (object, valid arm only, requires `views: ["output_form"]`): per-pipe output-form descriptors, keyed by the same namespaced `pipe_ref` as `pipe_io_contracts`. Each entry carries a single `field`, drawn from the same closed field vocabulary `input_form` uses, describing what that pipe produces — so a caller rendering a result, or registering a tool signature with a return type, reads the output's shape without inferring it from a value. Its JSON Schema is not here: that rides `pipe_io_contracts[…].output.json_schema`, and the pairing is the point — the descriptor states what the output IS, the schema names the property its payload arrives under
-- `rendered_markdown` (string, both arms, requires `render: ["markdown"]`): a server-rendered Markdown view of the verdict, produced by the same renderers the local CLI uses
+- `rendered_markdown` (string, both arms, requires `render: ["markdown"]`): a server-rendered Markdown view of the verdict. The valid arm's is produced by the renderer the local CLI uses; the invalid arm's presents the very items `errors` holds, in the same view, each numbered under its code's title with its code, where it is, its sentence, its suggestions and its suggested fix, so it never says what that view of the items leaves out
**Invalid arm (`is_valid: false`)** — the per-error diagnostics plus the runnability facts; the structural artifacts (`bundle_blueprint`, `pipe_io_contracts`, `graph_spec`, `validated_pipes`) and `mthds_contents` are **absent**, because they do not exist when load/parse/wiring failed:
```json
{
"is_valid": false,
- "validation_errors": [
+ "errors": [
{
- "category": "blueprint_validation",
- "message": "Value error, Invalid main pipe syntax 'Not A Valid Pipe Code!'. Must be in snake_case.",
- "error_type": "invalid_pipe_code_syntax",
- "domain_code": "broken",
- "source": "broken.mthds"
+ "code": "method.identifier_invalid",
+ "detail": "A name is not a valid identifier",
+ "location": { "file": "broken.mthds" }
}
],
"pending_signatures": [],
"is_runnable": false,
- "message": "Value error, Invalid main pipe syntax 'Not A Valid Pipe Code!'. Must be in snake_case."
+ "message": "The method does not validate."
}
```
**Response Fields (invalid arm):**
- `is_valid` (`false`): the discriminant of the invalid arm
-- `validation_errors` (list): the structured per-error diagnostics a client maps to per-line problems — built by pipelex's one shared builder, so they are byte-for-byte the same items the agent CLI emits. Each item carries a `category` (the closed set `blueprint_validation` | `pipe_factory` | `pipe_validation` | `dry_run`), a `message`, and the locators the runtime can attribute (`error_type`, `pipe_code` / `concept_code` / `domain_code`, `field_path` / `field_name`, and `source`). Absent locators are omitted, not null. An item may also carry a **`suggested_fix`** — a structured, deterministic repair (`fix_code`, `description`, `safety: safe|unsafe`, and the `ops[]` of semantic TOML patch operations to apply). It is present only when the fix planner derived one from the typed error data; a client that ignores it behaves exactly as before. See [Error Responses → Structured validation errors](error-responses.md#structured-validation-errors) and [→ Suggested fixes](error-responses.md#suggested-fixes) for every field. The array is **never empty on an invalid verdict** (the structured-info invariant is total): a failing dry run becomes one `dry_run` item per failing pipe, located at the innermost pipe that failed (its `pipe_code`, `domain_code` and, when known, `source`), a TOML syntax error carries the `line` and `column` the parser stopped at, and a parse-level failure with no attributable locator (an empty blueprint, an elaborator failure) becomes one `blueprint_validation` residual item carrying the message (no `source`). Every refusal of the bundle while it loads is an item of the verdict, never a no-verdict `5xx`: an unknown model is an `unknown_model` item on the pipe's `model` field (a reference the deck does not define, or a bare handle it serves only as another model type, such as an LLM named in a `PipeImgGen`; [`GET /v1/models/check`](models.md#check-a-model-reference) answers the same question for one reference), a model setting the model it resolves to refuses (a reasoning setting on a model that does not reason, for instance) is an `llm_setting_refused_by_model` item on the field naming the setting, a `PipeFunc` step whose function its method's files do not hold, or do not define as a top-level function marked `@pipe_func()`, is a `pipe_func_function_refused` item on its `function_name` field, and a call into a method package this runtime cannot resolve (not installed and not fetchable, or a fetch that failed) is an `unresolved_package_dependency` item on the first pipe naming the package, whose `missing_pipe_code` is the reference as written, `<address>->domain.code`
+- `errors` (list): the structured per-error diagnostics a client maps to per-line problems, each a problem item — built by pipelex's one shared builder, so they are the same findings the agent CLI reports. Each item carries the registry `code` a program branches on, the `detail` its code renders from the item's `params`, and the `location` the runtime can attribute (`pipe`, `concept`, `field`, `file`, `line`, `column`). A member an item does not have is absent, never `null`. An item may also carry a **`suggested_fix`** — a structured, deterministic repair (`fix_code`, `description`, `safety: safe|unsafe`, the `file` to apply it to, and the `ops[]` of semantic TOML patch operations to apply). It is present only when the fix planner derived one from the typed error data; a client that ignores it behaves exactly as before. See [Error Responses → Structured validation errors](error-responses.md#structured-validation-errors) and [→ Suggested fixes](error-responses.md#suggested-fixes) for every field. The array is **never empty on an invalid verdict** (the structured-info invariant is total): a failing dry run becomes one item per failing pipe, under the failure's own code, located at the innermost pipe that failed (its `pipe` and, when known, its `file`), a TOML syntax error is a `method.syntax` item carrying the `line` and `column` the parser stopped at, and a parse-level failure with no attributable locator (an empty blueprint, an elaborator failure) becomes one residual item under the code of the refusal. Every refusal of the bundle while it loads is an item of the verdict, never a no-verdict `5xx`: an unknown model is a `model.unknown` item on the pipe's `model` field, naming the `model` and its `model_type` (a reference the deck does not define, or a bare handle it serves only as another model type, such as an LLM named in a `PipeImgGen`; [`GET /v1/models/check`](models.md#check-a-model-reference) answers the same question for one reference), a model setting the model it resolves to refuses (a reasoning setting on a model that does not reason, for instance) is a `model.capability_unsupported` item on the field naming the setting, a `PipeFunc` step whose function its method's files do not hold, or do not define as a top-level function marked `@pipe_func()`, is a `method.function_invalid` item on its `function_name` field, and a call into a method package this runtime cannot resolve (not installed and not fetchable, or a fetch that failed) is a `method.dependency_missing` item on the first pipe naming the package, whose `name` is the package as the reference names it
- `pending_signatures` (list[str]): best-effort outstanding signatures (empty on the invalid arm, since no library was assembled)
- `is_runnable` (`false`): an invalid bundle is never runnable
-- `message` (string): the human-readable verdict summary: the lone item's message when there is one item, `N validation errors (first: <the first item's message>)` when there are several, and the parser's own message for a parse-level failure
+- `message` (string): the human-readable verdict summary, the sentence the refusal's code renders
## What This Endpoint Does
-The route wraps the runtime's protocol `validate`: parse → load → dry-run-sweep every pipe → build the per-pipe IO contracts → best-effort graph of the entry pipe → assemble the canonical report. The runner returns the verdict as a value — the canonical report on the valid arm, or a `BundleValidationFailure` (the refusal's problem with its validation items, a bundle the caller can fix) on the invalid arm — and the route maps the invalid verdict to the 200 invalid arm by matching the returned value, never by catching a transport error. A bundle that declares no `main_pipe`, when no manifest names one either, validates normally and simply carries `graph_spec: null` — there is no main-pipe precondition.
+The route wraps the runtime's protocol `validate`: parse → load → dry-run-sweep every pipe → build the per-pipe IO contracts → best-effort graph of the entry pipe → assemble the canonical report. The runner returns the verdict as a value — the canonical report on the valid arm, or a `BundleValidationFailure` (the refusal's problem with its validation items, a bundle the caller can fix) on the invalid arm — and the route maps the invalid verdict to the 200 invalid arm by matching the returned value, never by catching a transport error. A bundle that declares no `main_pipe`, when no manifest names one either, validates normally and simply carries no `graph_spec` — there is no main-pipe precondition.
## The effective entry pipe
@@ -125,13 +125,13 @@ The route wraps the runtime's protocol `validate`: parse → load → dry-run-sw
1. a `method_ref`'s fetched package manifest (`METHODS.toml`) `main_pipe` — the package author's declared entry pipe, qualified against the closure;
2. otherwise, and when the manifest declares none, the closure's primary blueprint's `main_pipe` (the first file declaring one), qualified by its domain.
-It is `null` when no entry pipe is determined — no blueprint declares `main_pipe`, or a manifest names a pipe the closure does not declare, or declares in several domains. In those last two cases a selector-less run by that address would fail to resolve the manifest's pipe too, so the field says nothing rather than naming the closure's pipe, which no such run would execute.
+It is absent when no entry pipe is determined — no blueprint declares `main_pipe`, or a manifest names a pipe the closure does not declare, or declares in several domains. In those last two cases a selector-less run by that address would fail to resolve the manifest's pipe too, so the field says nothing rather than naming the closure's pipe, which no such run would execute.
The field exists because the canonical report is **manifest-blind**: `bundle_blueprint` is the batch's primary blueprint, so for a package whose `METHODS.toml` entry differs from — or exists without — a bundle-level `main_pipe`, a consumer deriving the entry pipe from `bundle_blueprint.main_pipe` alone gets the wrong pipe, or none. Reading `default_pipe_ref` is how a client projects an entry signature that matches what [`POST /v1/execute`](pipe-run.md#running-a-method-by-address-method_ref) and `POST /v1/start` actually default to.
-The graph follows the same precedence: on a `method_ref` request whose manifest names a `main_pipe`, the route hands that pipe to the runtime as the graph target, so `graph_spec` draws the pipe `default_pipe_ref` names — including for a package whose bundles declare no `main_pipe` at all, whose entry pipe only the manifest states. A manifest `main_pipe` the closure does not resolve leaves both fields `null` rather than graphing the closure's own `main_pipe`, which no run by that address executes. The target travels with the dispatch, so a validation sent to a worker is graphed the same way.
+The graph follows the same precedence: on a `method_ref` request whose manifest names a `main_pipe`, the route hands that pipe to the runtime as the graph target, so `graph_spec` draws the pipe `default_pipe_ref` names — including for a package whose bundles declare no `main_pipe` at all, whose entry pipe only the manifest states. A manifest `main_pipe` the closure does not resolve leaves both fields absent rather than graphing the closure's own `main_pipe`, which no run by that address executes. The target travels with the dispatch, so a validation sent to a worker is graphed the same way.
-It states the **run** default, which is looser than the [`/pipe-io`](pipe-io.md#pipe-selection) selection chain on one point: a closure whose domains each declare a `main_pipe` cannot be defaulted on `/pipe-io` (a `422`), but `/execute` and `/start` run its first declaring blueprint happily — so this field names that pipe rather than reporting `null`.
+It states the **run** default, which is looser than the [`/pipe-io`](pipe-io.md#pipe-selection) selection chain on one point: a closure whose domains each declare a `main_pipe` cannot be defaulted on `/pipe-io` (a `422`), but `/execute` and `/start` run its first declaring blueprint happily — so this field names that pipe rather than being absent.
The field rides the valid arm only. The invalid arm assembles no library, so there is no entry pipe to name and the field is absent, like the other structural artifacts.
@@ -157,15 +157,15 @@ Neither axis is part of the verdict contract: a machine consumer branches on the
## Sourcing submitted files
-The submit path carries bundle text, not file paths, so by default the runtime cannot tell the client which file an error belongs to — `source` comes back `null`. Send `mthds_sources` parallel to `mthds_contents` to fix this: each source is the logical identity of that content (e.g. the file's path relative to the submitted directory), and the runtime threads it onto the corresponding `blueprint.source`. The source then rides back on both arms — `bundle_blueprint.source` on the valid arm, and `validation_errors[].source` on the invalid arm — so a multi-file editor client can map a cross-file diagnostic to the file that owns it. Omit `mthds_sources` (or send `null`) and behavior is exactly as before. The list, when present, must be the same length as `mthds_contents`; a mismatch is a request-shape 422 (it is the caller's wiring bug, caught before the validation sweep runs). A source is a label for diagnostics and nothing more: even one naming a real file on the server is never a directory the server reads from, so a step's template file comes from [`resources`](#sending-the-files-the-steps-read-resources) alone, and an address-based reference is not searched for above it.
+The submit path carries bundle text, not file paths, so by default the runtime cannot tell the client which file an error belongs to — an item's `location` carries no `file`. Send `mthds_sources` parallel to `mthds_contents` to fix this: each source is the logical identity of that content (e.g. the file's path relative to the submitted directory), and the runtime threads it onto the corresponding `blueprint.source`. The source then rides back on both arms — `bundle_blueprint.source` on the valid arm, and `errors[].location.file` on the invalid arm — so a multi-file editor client can map a cross-file diagnostic to the file that owns it. Omit `mthds_sources` (or send `null`) and behavior is exactly as before. The list, when present, must be the same length as `mthds_contents`; a mismatch is a request-shape 422 (it is the caller's wiring bug, caught before the validation sweep runs). A source is a label for diagnostics and nothing more: even one naming a real file on the server is never a directory the server reads from, so a step's template file comes from [`resources`](#sending-the-files-the-steps-read-resources) alone, and an address-based reference is not searched for above it.
## Validating a method tree
-A method sent in `files`, or fetched by `method_ref`, is validated whole, as it would run: the runner reads the tree under the standard's rule, writes it into a temporary directory, and validates it as one library directory of the caller's, with the packages it ships in `dependencies` (or, for a `method_ref` package, under its own `.mthds/methods/<name>/`) loaded beside it, so a call into one resolves as on a run. Every bundle is named by its tree path, so `validation_errors[].source` names the owning file, and no item names a path on the server.
+A method sent in `files`, or fetched by `method_ref`, is validated whole, as it would run: the runner reads the tree under the standard's rule, writes it into a temporary directory, and validates it as one library directory of the caller's, with the packages it ships in `dependencies` (or, for a `method_ref` package, under its own `.mthds/methods/<name>/`) loaded beside it, so a call into one resolves as on a run. Every bundle is named by its tree path, so `errors[].location.file` names the owning file, and no item names a path on the server.
-- **Python is checked by syntax.** Every `.py` file of the tree is read and compiled, never imported or run, whether or not a step names it: a file that does not parse, or is not UTF-8, makes the verdict `is_valid: false` with an item whose `source` is the file's tree path and whose `line` is the line of the error. A `PipeFunc` step's function is then located in the tree and its form checked statically. As on a run, a tree holding Python is refused with a `403` (`CustomCodeRequiresSandbox`) on a deployment that is not sandbox-hosted.
-- **The default pipe and the graph follow the tree's entry pipe.** `default_pipe_ref` is the pipe the protocol's rule names, the `main_pipe` of the root `METHODS.toml` or the one `main_pipe` its bundles declare, and the graph is drawn from it. A tree with no entry pipe validates with `default_pipe_ref: null` and `graph_spec: null`.
-- **Refusals of the tree itself produce no verdict**: a key the tree's rule refuses or a malformed entry is a **422** `InvalidMethodFiles`, a hash the runner does not hold a **422** `MissingBlobs`, and a tree past its limits a **422** `MethodTreeTooLarge`, as on a [run](pipe-run.md#sending-a-method-as-a-tree).
+- **Python is checked by syntax.** Every `.py` file of the tree is read and compiled, never imported or run, whether or not a step names it: a file that does not parse, or is not UTF-8, makes the verdict `is_valid: false` with an item whose `location.file` is the file's tree path and whose `location.line` is the line of the error. A `PipeFunc` step's function is then located in the tree and its form checked statically. As on a run, a tree holding Python is refused with a `501` `pipelex.deployment.custom_code_requires_sandbox` on a deployment that is not sandbox-hosted.
+- **The default pipe and the graph follow the tree's entry pipe.** `default_pipe_ref` is the pipe the protocol's rule names, the `main_pipe` of the root `METHODS.toml` or the one `main_pipe` its bundles declare, and the graph is drawn from it. A tree with no entry pipe validates with neither `default_pipe_ref` nor `graph_spec`.
+- **Refusals of the tree itself produce no verdict**: a key the tree's rule refuses is a **422** `method.package_invalid` naming the rule as its `reason`, or `security.input_path_refused` for a key leaving the tree's root, a malformed entry a **422** `request.invalid`, a hash the runner does not hold a **422** `request.blobs_missing`, and a tree past its limits a **422** `method.package_invalid` naming the limit, as on a [run](pipe-run.md#sending-a-method-as-a-tree).
- **The `mthds_contents` echo** holds the text of the tree's own bundles.
## Sending the files the steps read (`resources`)
@@ -179,23 +179,23 @@ A bundle sent as content has no directory, so a file one of its steps reads from
}
```
-- **Each key is the path a step names**, relative to the bundle and written with forward slashes, exactly as in its `template_file`. `.` segments and repeated slashes collapse, so `./templates/invoice.docx` names the same file; every bundle of the request is read as sitting in one directory. An empty or absolute path, a drive or a network share, a `..` segment, a backslash, a colon, or two keys naming the same file is a **422** `InvalidResourcePath`, refused before any value is decoded. A method sent as a tree may hold the file instead, beside the bundle whose step names it; beside a tree, each key of `resources` joins it at that path from the tree's root, and a file the tree already holds must have the same bytes (see [Pipe Run](pipe-run.md#sending-a-method-as-a-tree)).
-- **Each value is the file's bytes** in standard base64 (RFC 4648, with padding). A value that does not decode is a **400** `InvalidBase64`.
+- **Each key is the path a step names**, relative to the bundle and written with forward slashes, exactly as in its `template_file`. `.` segments and repeated slashes collapse, so `./templates/invoice.docx` names the same file; every bundle of the request is read as sitting in one directory. An empty or absolute path, a drive or a network share, or a `..` segment is a **422** `security.input_path_refused`, whose `rule` is `absolute` or `parent_segment`, and a backslash, a colon, or two keys naming the same file is a **422** `request.invalid` naming the field `resources`, each refused before any value is decoded. A method sent as a tree may hold the file instead, beside the bundle whose step names it; beside a tree, each key of `resources` joins it at that path from the tree's root, and a file the tree already holds must have the same bytes (see [Pipe Run](pipe-run.md#sending-a-method-as-a-tree)).
+- **Each value is the file's bytes** in standard base64 (RFC 4648, with padding). A value that does not decode is a **422** `request.malformed` whose `reason` is `bad_base64`.
- **Beside inline contents, every file must be one a step names.** A file no step of the bundle reads is a **422** problem with the code `request.invalid`, whose operator view's message lists the unnamed paths: a misspelled key fails loudly rather than leaving its step without its file. This is a request error, never an `is_valid: false` verdict. Beside a tree, a file no step names is kept like any other file of the tree.
-- **The sizes are bounded**: at most `MAX_RESOURCES_PER_REQUEST` files (32 by default), each at most `MAX_RESOURCE_FILE_KIB` once decoded (5 MiB by default), and at most `MAX_RESOURCES_TOTAL_KIB` across the request (10 MiB by default). A request over any of them is a **413** `PayloadTooLarge`, an oversized file refused on its encoded length before it is decoded. The whole body stays under `MAX_REQUEST_BODY_MIB` as well.
-- **The files make one method tree**, with the request's bundles at its root. A run names that tree by its digest, as it names the tree of a method loaded from a directory, and carries none of the files in its payloads, a remote orchestrator's included: the step that reads one reads it from the tree, through the deployment's method file store. Two files colliding in one tree, such as two keys equal once case-folded, are a **422** `BundleResourcePathError`.
+- **The sizes are bounded**: at most `MAX_RESOURCES_PER_REQUEST` files (32 by default), each at most `MAX_RESOURCE_FILE_KIB` once decoded (5 MiB by default), and at most `MAX_RESOURCES_TOTAL_KIB` across the request (10 MiB by default). Too many files is a **422** `request.invalid` naming the field `resources`, and a file or a request over its size limit a **413** `request.too_large` giving the `limit` and the `size` in bytes, an oversized file refused on the size its encoded length carries before it is decoded. The whole body stays under `MAX_REQUEST_BODY_MIB` as well.
+- **The files make one method tree**, with the request's bundles at its root. A run names that tree by its digest, as it names the tree of a method loaded from a directory, and carries none of the files in its payloads, a remote orchestrator's included: the step that reads one reads it from the tree, through the deployment's method file store. Two files colliding in one tree, such as two keys equal once case-folded, are a **422** `request.invalid` naming the field `resources`.
-The files are checked as files on disk are. An `.html` template file is checked against the step's inputs when the bundle loads, and the document engine's template check runs on an office template file in the validation's dry run, where its errors are validation errors on the step. A step whose `template_file` could not be a key, being empty or absolute, or holding a `..` segment, a backslash, a colon or a NUL character, is refused when its bundle is parsed, whatever the request sends: the verdict's one item is a `blueprint_validation` item located at the step by its `pipe_code` and by `field_path` `pipe.<code>`, whose message names the field without repeating the path. A step whose `template_file` could be a key but was not sent is refused at load, and the verdict's `validation_errors[]` says the file was not supplied with its bundle and names the key it is expected under.
+The files are checked as files on disk are. An `.html` template file is checked against the step's inputs when the bundle loads, and the document engine's template check runs on an office template file in the validation's dry run, where its errors are validation errors on the step. A step whose `template_file` could not be a key, being empty or absolute, or holding a `..` segment, a backslash, a colon or a NUL character, is refused when its bundle is parsed, whatever the request sends: the verdict's one item is located at the step by its `pipe` and by the `field` `pipe.<code>`, and its sentence names the field without repeating the path. A step whose `template_file` could be a key but was not sent is refused at load, and the verdict's `errors[]` holds a `method.resource_missing` item, located at the step, whose `file` parameter is the key the file is expected under.
## Where validation runs
-Validation is **`orchestration_mode`-aware**, the same way `/start` is: the runner resolves the effective backend (the deployment default plus the optional per-request `orchestration_mode` override) and dispatches through the bundle-validator registry. Validation is inherently blocking, so there is no delivery axis here — only the backend varies. On the orchestrator-agnostic base — and for `orchestration_mode: direct` — the whole job runs **in-process in one library load on the API side**. On an orchestrator flavor whose mode is selected (e.g. `temporal`), the whole job is **dispatched to a worker** instead, and the API side assembles the same canonical report from the worker's result without loading a library. Either way the verdict is byte-identical: the backend changes, the contract does not. A per-request override the deployment forbids is refused with a 403.
+Validation is **`orchestration_mode`-aware**, the same way `/start` is: the runner resolves the effective backend (the deployment default plus the optional per-request `orchestration_mode` override) and dispatches through the bundle-validator registry. Validation is inherently blocking, so there is no delivery axis here — only the backend varies. On the orchestrator-agnostic base — and for `orchestration_mode: direct` — the whole job runs **in-process in one library load on the API side**. On an orchestrator flavor whose mode is selected (e.g. `temporal`), the whole job is **dispatched to a worker** instead, and the API side assembles the same canonical report from the worker's result without loading a library. Either way the verdict is byte-identical: the backend changes, the contract does not. A per-request override the deployment forbids is refused with a 422 `pipelex.deployment.orchestration_override_forbidden`.
The validator is handed the request's `read_scope`, the scope a run of the same request reads under, so a validator that dispatches to a worker can hand it the method's trees through that scope's blob store and the worker read them by digest, as a run's worker reads its method's files under the run's read scope. A tree sent in `files` is already recorded there when the validator is called. A request without a `read_scope` hands the validator none, never the caller's own id, so a dispatched validation stores nothing under a prefix no host lists or erases.
> **Resource note for deployment.** When validation runs in-process (the agnostic base, or `direct` mode), the API server loads the method library to validate, so a deployment that receives large or frequent in-process `/validate` traffic should be sized for that load (memory + CPU for library assembly and the graph dry-run). On a distributed-execution flavor that dispatches validation to a worker, the library work happens worker-side; size the workers accordingly.
-The graph is best-effort: a bundle that validates but whose graph dry-run fails still returns 200 on the valid arm with `graph_spec: null`.
+The graph is best-effort: a bundle that validates but whose graph dry-run fails still returns 200 on the valid arm, with no `graph_spec`.
## Who the validation is done for
@@ -205,11 +205,11 @@ A validation is not a run, but it still emits telemetry: the sweep's `pipe_dry_r
Only conditions where the endpoint could not produce a verdict are non-2xx, rendered as [RFC 9457 problem documents](error-responses.md):
-- **422** — a malformed request body, an `mthds_sources` / `mthds_contents` length mismatch, more or fewer than one of `mthds_contents` / `files` / `method_ref`, or a malformed `analytics_groups` (`error_type` `InvalidAnalyticsGroups`) — request-shape errors caught before the runtime.
-- **422** on a method tree — a key or entry the tree's rule refuses (`InvalidMethodFiles`), a hash entry the runner does not hold (`MissingBlobs`), or a tree past its limits (`MethodTreeTooLarge`) — see [Validating a method tree](#validating-a-method-tree).
-- **422**, **413** and **400** on `resources` — a path that cannot name a file inside the bundle (`InvalidResourcePath`), a file no step names (`request.invalid`), files that cannot make one tree (`request.invalid`, or `security.input_path_refused` for a path the tree rule refuses), a file or a request over its size limit (`PayloadTooLarge`), or a value that is not base64 (`InvalidBase64`) — see [Sending the files the steps read](#sending-the-files-the-steps-read-resources).
-- **401 / 403** — unauthenticated / forbidden (including a per-request `orchestration_mode` override the deployment does not allow).
-- **`method_ref` resolution failures** — a selector that could not be resolved produced no verdict, so it is never rendered as `is_valid: false`: a malformed reference is a **422** `request.invalid`, a failed fetch a **502** `method.fetch_failed`, no matching package in the repository a **404** `method.not_found`, the sandbox gate on custom Python a **403** `CustomCodeRequiresSandbox`, and the refusal of Python structure classes a **422** `pipelex.deployment.python_structures_refused` — the same statuses and codes as on the run routes (see the [error table](pipe-run.md#running-a-method-by-address-method_ref)).
+- **422** — a malformed request body (`request.malformed`), an `mthds_sources` / `mthds_contents` length mismatch, more or fewer than one of `mthds_contents` / `files` / `method_ref`, or a malformed `analytics_groups` (`request.invalid`, naming the field), or a per-request `orchestration_mode` override the deployment does not allow (`pipelex.deployment.orchestration_override_forbidden`) — request-shape errors caught before the runtime.
+- **422** on a method tree — a key the tree's rule refuses (`method.package_invalid`, or `security.input_path_refused`), a malformed entry (`request.invalid`), a hash entry the runner does not hold (`request.blobs_missing`), or a tree past its limits (`method.package_invalid`) — see [Validating a method tree](#validating-a-method-tree).
+- **422** and **413** on `resources` — a path that cannot name a file inside the bundle (`security.input_path_refused`, or `request.invalid`), a file no step names (`request.invalid`), files that cannot make one tree (`request.invalid`), too many files (`request.invalid`), a file or a request over its size limit (`request.too_large`), or a value that is not base64 (`request.malformed`) — see [Sending the files the steps read](#sending-the-files-the-steps-read-resources).
+- **401** — unauthenticated (`auth.missing_credential`, `auth.invalid_credential`, `auth.credential_expired`).
+- **`method_ref` resolution failures** — a selector that could not be resolved produced no verdict, so it is never rendered as `is_valid: false`: a malformed reference is a **422** `request.invalid`, a failed fetch a **502** `method.fetch_failed`, no matching package in the repository a **404** `method.not_found`, the sandbox gate on custom Python a **501** `pipelex.deployment.custom_code_requires_sandbox`, and the refusal of Python structure classes a **422** `pipelex.deployment.python_structures_refused` — the same statuses and codes as on the run routes (see the [error table](pipe-run.md#running-a-method-by-address-method_ref)).
- **5xx** — a server fault (including a host-wiring programmer error, surfaced as `runtime.unexpected`).
Read it as one rule: a non-2xx on `/validate` always means "the endpoint could not produce a verdict," never "your bundle is bad."
diff --git a/docs/errors/index.md b/docs/errors/index.md
index 150218d62..09ab37b0b 100644
--- a/docs/errors/index.md
+++ b/docs/errors/index.md
@@ -66,6 +66,7 @@ Pipelex's storage addresses and uploads.
|---|---|---|---|---|
| [`pipelex.storage.uri_invalid`](pipelex/storage/uri_invalid.md) | The storage address is malformed | `input` | `no` | `422` |
| [`pipelex.storage.not_found`](pipelex/storage/not_found.md) | A stored file is gone | `runtime` | `no` | `500` |
+| [`pipelex.storage.damaged`](pipelex/storage/damaged.md) | A stored file is damaged | `runtime` | `no` | `500` |
| [`pipelex.storage.unavailable`](pipelex/storage/unavailable.md) | Storage is unavailable | `runtime` | `yes` | `503` |
| [`pipelex.storage.not_configured`](pipelex/storage/not_configured.md) | This deployment serves no storage for that address | `operator` | `no` | `500` |
| [`pipelex.storage.grant_unusable`](pipelex/storage/grant_unusable.md) | The upload grant is spent or expired | `runtime` | `yes` | `403` |
diff --git a/docs/errors/pipelex/storage/damaged.md b/docs/errors/pipelex/storage/damaged.md
new file mode 100644
index 000000000..4da3b3c89
--- /dev/null
+++ b/docs/errors/pipelex/storage/damaged.md
@@ -0,0 +1,53 @@
+---
+title: "pipelex.storage.damaged"
+description: "A stored file is damaged: what the Pipelex error code pipelex.storage.damaged means, who must act and what to do."
+---
+
+# pipelex.storage.damaged
+
+**A stored file is damaged**
+
+| | |
+|---|---|
+| Type | `https://docs.pipelex.com/errors/pipelex.storage.damaged` |
+| Family | [`pipelex.storage`](../../index.md#pipelex-storage): Pipelex's storage addresses and uploads. |
+| [Domain](https://mthds.ai/latest/spec/protocol/#domain-who-must-act) | `runtime`: nobody could have acted beforehand, so whoever made the call waits, retries or reports the problem |
+| [Retry](https://mthds.ai/latest/spec/protocol/#retry) | `no`: repeating the operation fails the same way |
+| HTTP status | `500` |
+| Raised as | a problem document, sent as the body of an HTTP response or kept in a run's record |
+
+## What it means
+
+Storage still holds an object under the file's key, but its bytes are not the ones the runtime stored: they do not hash to the key the file is stored under, or they are not the size storage holds them at. A retry reads the same damaged object, and no upload writes over it, so it stays until whoever runs the runtime removes it.
+
+## What to do
+
+Report the problem to whoever runs the runtime, with the `request_id`. Once they have removed the damaged object, upload the file again.
+
+## Next steps
+
+A problem carries the [step](https://mthds.ai/latest/spec/protocol/#next-steps) aimed at whoever reads it: the first when its reader is the domain's actor, whoever made the call, and the second for any other reader.
+
+| Reader | Kind | Detail |
+|---|---|---|
+| The domain's actor | `report` | Report this to whoever runs the runtime. |
+| Any other reader | `report` | Report this to whoever runs the runtime. |
+
+## Detail
+
+The problem's `detail` is written from this template, filled with the occurrence's parameters:
+
+> A file the runtime stored in its `{scheme}` storage no longer holds the bytes it was stored with.
+
+## Parameters
+
+Every parameter is present on every occurrence of the code.
+
+| Name | Type | Description |
+|---|---|---|
+| `scheme` | one of `local`, `s3`, `gcs`, `memory` | The kind of storage that holds the damaged file. |
+
+## See also
+
+- [The MTHDS error registry format](https://mthds.ai/latest/spec/error-registry/), which describes the members of this page
+- [Error Codes](../../index.md), every Pipelex code
diff --git a/docs/tools/logging.md b/docs/tools/logging.md
index b00124135..8e16ed026 100644
--- a/docs/tools/logging.md
+++ b/docs/tools/logging.md
@@ -560,6 +560,9 @@ What varies goes in `fields`, named by the [naming convention](#naming-conventio
| `has_blocked_steps` | boolean | Whether a stale configuration file needs a migration step that cannot be applied for the user |
| `file_count` | integer | The number of result files a delivery stored |
| `storage_key` | string | The key a delivery stores a result file under, which ends in the file's name |
+| `storage_scheme` | string or `null` | The kind of storage a deployment's storage provider is, as a `pipelex.storage.*` problem names it: `s3`, `local`; `null` for a storage plugin whose kind the registry does not list |
+| `blob_sha256` | string | The SHA-256 a blob is stored under in the API server's blob store, in lowercase hex: its content's hash, never its content |
+| `blob_size_bytes`, `read_size_bytes` | integer | The size the API server's blob store holds a blob at, and the size of the bytes a read of it returned, in bytes |
| `env_var` | string | The name of an environment variable, never its value |
| `default_value` | integer | The value a setting falls back to when its environment variable holds none it can use |
| `auth_mode` | string | The authentication mode the API server's `AUTH_MODE` names |
diff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.md
index 0d1e7835d..d217f21e4 100644
--- a/docs/under-the-hood/error-model.md
+++ b/docs/under-the-hood/error-model.md
@@ -201,7 +201,7 @@ Besides `category` and `message`, each item carries whatever identity fields its
**A verdict names no path on the host.** A caller reads the verdict, its items, their locators and its message, so none of them names where the host keeps a file. A bundle of a package the method depends on by address is named by the package's address and the bundle's path inside the package, such as `github.com/acme/harbour-methods/tides/notices/tide_notices.mthds`, never by the directory the host installed the package in: that is the `source` of an item located inside the dependency and the file a duplicate declaration inside it names, on every surface, a local one included. When submitted content is validated or run, the library directories loaded beside it are the host's (installed libraries, the defaults, `PIPELEXPATH`) unless the caller says they are its own, so the verdict names none of their files: an item located in one carries no `source`, nor a `field_path` naming it, and is found by its `pipe_code` and `domain_code`, a warning found at a pipe of theirs carries no `template_file` (the sweep withholds it, `BundleValidator`'s `source_pipe_refs`), and a message that named one, named the template file a `PipeDocGen` step of theirs names (one whose template the engine's check refuses in the dry run of a caller's pipe that runs it), or named the module a Python file of theirs was imported as (two `@pipe_func` functions of the same name, for instance), reads `<host library file>` in its place (`withholding_host_library_files` in `pipelex/pipeline/validate_bundle_translation.py`). The withheld verdict is the same answer otherwise: it keeps the code its raise site chose, such as `request.invalid` for a request naming nothing to validate, and the parameters and items its raise site gave, withheld the same way. Every item of its problem is withheld whole, its sentence, each parameter and its locators, whichever channel each came from: an item no stage classified takes the parameters of the refusal the verdict was built from, its cause, whose `finding`, `file` or `path` the withholding never rewrote otherwise. A name only counts standing on its own, never inside a longer one, and neither a source the caller submitted nor a template file its own content names is ever withheld. A method of those directories that refuses to load is not an item at all: it is the deployment's configuration failing to validate, so `reporting_host_library_faults` in the same module raises it as a `HostLibraryLoadRefusalError`, carrying `pipelex.config.invalid`, which an API answers with its code's 500, the host library's own text riding only the operator's diagnostics. A step can only name its template file relative to its bundle, so no message about one names a path on the host. A bundle validated from a file on the caller's own disk, and content validated or run against library directories that are the caller's (`library_dirs_are_callers`, an option of `validate_bundle`, of the in-process validator and of the local runtime `PipelexMTHDSProtocol`, whose `validate` and `execute` both read it), keep the full path of every file, since there the directories are the caller's own. `pipelex fix bundle --diff` leaves a dependency's address-named source as it is.
-**Every refusal of the bundle is a verdict.** A validator answers either a verdict — valid, or invalid with located items — or *no verdict could be produced*, which is reserved for a failure of the tool or its environment. So a refusal raised while loading or validating a bundle becomes an item, never a no-verdict fault. After its class-specific arms, the shared cascade (`translate_to_validate_bundle_error` in `pipelex/pipeline/validate_bundle_translation.py`) turns any other `PipelexError` whose code is the method's to fix, in the `method` domain, into a verdict with one item: `pipe_validation`, with the `pipe_code`, `domain_code` and `source`, when the library load located it on the pipe it was building, and `blueprint_validation` otherwise. That item carries no `error_type`, since a refusal with a closed code has an arm of its own, and its message is the sentence the refusal's code renders for a caller (`refusal_detail()`), never the refusal's own message, which is the operator's. The location comes from the load loop in `LibraryManager.load_from_crate`, the one place that holds a pipe's code, domain and file when building it fails: it raises such a refusal again as a `PipeLoadRefusalError` naming the pipe and the file, `from` the original. A fault whose code another actor must fix, the caller's input, the account, the operator or the runtime, a `LibraryError` among them (a library invariant of ours reads `runtime.unexpected`), a `SecurityError`, a `PipeNotFoundError` (which has its own not-found handler) and anything that is not a `PipelexError` still propagate as no verdict, and so does a missing document engine, `pipelex.docgen.engine_unavailable`, which the deployment has to install. The rule therefore reaches exactly the refusals whose code is the method's. A dry run's failures and a pipe run failing outside the sweep become a verdict on the same rule: only when at least one failure is the method's. A dry run whose every failure belongs to another actor answers its own code, the first of its failures' codes by `first_fault_code()` (a verdict `no` before a retryable one, then the method's, the operator's, the account's, the input's and the runtime's, then the first given), with every failure riding its problem's `errors`, and never reads as an invalid method. The pipe factories' refusals are: `PipeLLMFactoryError`, `PipeComposeFactoryError`, `PipeExtractFactoryError`, `PipeConditionFactoryError` and `PipeParallelFactoryError` are raised only while a pipe is built, about its own blueprint, so each declares a `method` code, `method.template_invalid` or `method.schema_violation`, and a `PipeExtract` whose input is neither an image nor a document validates to one item on that pipe, saying which input to redeclare. `PipeImgGenFactoryError` is not among them: it is raised while an image-generation pipe runs, not while it is built.
+**Every refusal of the bundle is a verdict.** A validator answers either a verdict — valid, or invalid with located items — or *no verdict could be produced*, which is reserved for a failure of the tool or its environment. So a refusal raised while loading or validating a bundle becomes an item, never a no-verdict fault. After its class-specific arms, the shared cascade (`translate_to_validate_bundle_error` in `pipelex/pipeline/validate_bundle_translation.py`) turns any other `PipelexError` whose code is the method's to fix, in the `method` domain, into a verdict with one item: `pipe_validation`, with the `pipe_code`, `domain_code` and `source`, when the library load located it on the pipe it was building, and `blueprint_validation` otherwise. That item carries no `error_type`, since a refusal with a closed code has an arm of its own, and its message is the sentence the refusal's code renders for a caller (`refusal_detail()`), never the refusal's own message, which is the operator's. The location comes from the load loop in `LibraryManager.load_from_crate`, the one place that holds a pipe's code, domain and file when building it fails: it raises such a refusal again as a `PipeLoadRefusalError` naming the pipe and the file, `from` the original. A fault whose code another actor must fix, the caller's input, the account, the operator or the runtime, a `LibraryError` among them (a library invariant of ours reads `runtime.unexpected`), a `SecurityError`, a `PipeNotFoundError` (which has its own not-found handler) and anything that is not a `PipelexError` still propagate as no verdict, and so does a missing document engine, `pipelex.docgen.engine_unavailable`, which the deployment has to install. The rule therefore reaches exactly the refusals whose code is the method's. A dry run's failures and a pipe run failing outside the sweep become a verdict on the same rule: only when at least one failure is the method's, and none is a security refusal. A refusal a security rule made is never a verdict's item, whichever arm meets it, though many security codes are the method's to fix (`security.method_path_refused`, `security.template_refused`): every arm asks the same question of a code, the method's and no security family's. A dry run meeting one, such as a template the sandbox refuses at render, answers that refusal's code, a security failure's code coming before any other among its failures, every failure riding its items; the pipe run that met it logged its security event, and the sweep marks its own error reported so no boundary logs it twice. A dry run whose every failure belongs to another actor answers its own code, the first of its failures' codes by `first_fault_code()` (a verdict `no` before a retryable one, then the method's, the operator's, the account's, the input's and the runtime's, then the first given), with every failure riding its problem's `errors`, and never reads as an invalid method. The pipe factories' refusals are: `PipeLLMFactoryError`, `PipeComposeFactoryError`, `PipeExtractFactoryError`, `PipeConditionFactoryError` and `PipeParallelFactoryError` are raised only while a pipe is built, about its own blueprint, so each declares a `method` code, `method.template_invalid` or `method.schema_violation`, and a `PipeExtract` whose input is neither an image nor a document validates to one item on that pipe, saying which input to redeclare. `PipeImgGenFactoryError` is not among them: it is raised while an image-generation pipe runs, not while it is built.
**The unknown model is the worked example.** A pipe whose model field names a handle, an alias, a preset or a waterfall the model deck does not define is refused when the pipe is built: the operator's deck check raises `ModelChoiceNotFoundError`, and the operator raises it again as a `PipeOperatorModelChoiceError` located on the pipe and on the field, to which the load adds the file. Every pipe type that names a model (`PipeLLM`, `PipeStructure`, `PipeImgGen`, `PipeExtract`, `PipeSearch`) does this through the same `PipeOperator.locating_model_choice` wrapper, so each gives the same item: `category: pipe_validation`, `error_type: unknown_model`, the `pipe_code`, `domain_code` and `source`, the `field_name` and a `field_path` of `pipe.<code>.model` (`pipe.<code>.model_to_structure` for a `PipeLLM`'s structuring model), the `model_reference` exactly as written, the `model_type` (`llm`, `text_extractor`, `img_gen` or `search`), and the deck's `suggestions` of the same kind, each spelled as a reference the field accepts. The suggestions stay in the item's `message` too, for consumers that keep only the message. When the deck offers exactly one suggestion, the item carries an `unsafe` `rename-model` fix, a `remap_value` of the field from the reference as written to that suggestion. It is unsafe because the suggestion is a fuzzy match over the deck's names, which can be a different model altogether, so `pipelex fix bundle` never applies it on its own; an author or an agent applies it deliberately. An inline setting table (`model = { model = "…", temperature = 0.2 }`) is not looked up in the deck, so it is not refused here. A default the deck names itself, which a `PipeJudge` naming no model resolves as its method loads, is not the method's: the wrapper lets its `ModelDeckChoiceUnresolvedError` through unchanged, the deployment's fault and no verdict item. On a run the same refusal stops the bundle before any pipe runs, as the same `unknown_model` item (see the next paragraph).
@@ -233,7 +233,7 @@ exc.validation_error_items() # the typed items a verdict carries as validation_
```
!!! info "Two shapes of the same items"
- A validation verdict — the `200` `is_valid: false` answer of the API's diagnostic routes, the human CLI's validation output and a validator's invalid arm — carries the `ValidationErrorItem`s whole, as `validation_errors`. A problem — the `422` answer of a run refused before any pipe ran, and the agent CLI's invalid verdict on stderr — carries them as `errors` items, each with its code. Both are built from the same items, so they name the same faults at the same places.
+ A validation verdict of the runtime — the human CLI's validation output and a validator's invalid arm — carries the `ValidationErrorItem`s whole, as `validation_errors`. A problem carries them as `errors` items, each with its code, and so does the API server's `200` `is_valid: false` answer on its diagnostic routes, whose `errors` are its refusal's problem items: the `422` answer of a run refused before any pipe ran and the agent CLI's invalid verdict on stderr are such problems. Both are built from the same items, so they name the same faults at the same places.
### `suggested_fix` — structured deterministic fixes
@@ -251,7 +251,7 @@ The **fix planner** (`pipelex/pipeline/fixes/planner.py`) translates enriched ty
Applying fixes is the runtime's job too: the **applier** (`pipelex/fix_ops/applier.py`) mutates a tomlkit DOM in place per op (guarded — an op whose target table is absent is skipped and reported, never raised) and then reflows the whole file to canonical MTHDS style, and the **convergence loop** (`pipelex/pipeline/fixes/fix_loop.py`) runs validate → apply SAFE fixes → re-validate to a fixed point, reporting non-convergence loudly. The user-facing surface is [`pipelex fix bundle`](../tools/cli/fix.md).
-On the hosted API the same payload rides the wire verbatim as `validation_errors[].suggested_fix`; how it appears in HTTP error responses is documented on the API side, in the API server's [Error Responses](../api-server/error-responses.md#suggested-fixes) page.
+On the API server the same payload rides the wire as `errors[].suggested_fix`, the problem item's fix, which names the file to apply it to as `file`; how it appears in HTTP error responses is documented on the API side, in the API server's [Error Responses](../api-server/error-responses.md#suggested-fixes) page.
---
@@ -468,21 +468,22 @@ Beside the failure, the deployment logs one **security event**, so that whoever
| `event.name` | `pipelex.security.refusal` |
| `error.code` | The refusal's code, such as `security.method_url_refused` |
| `error.domain` | The code's domain, who caused it: `input`, `method` or `runtime` |
-| `error.type` | The class of the error that carries or implies the code, such as `SsrfBlockedError`, never a wrapper above it; for a refusal the API server authors with no error class behind it, the `error_type` its response names, such as `ReservedObjectKey` |
+| `error.type` | The class of the error that carries or implies the code, such as `SsrfBlockedError`, never a wrapper above it, the API server's own refusals included, such as `ReservedObjectKeyError` |
| `security.target` | The kind of thing refused, which the code decides: `url`, `path`, `template`, `schema`, `dependency`, `object_key` or `result_location` |
| `security.target_class` | The class of destination refused, when the raise site knows it: `loopback`, `private`, `link_local`, `metadata` (a cloud metadata endpoint), `scheme` (a scheme the run does not read, a `file://` URL or a path on the server's disk among them) or `foreign_storage_key` (a storage key outside the run's read scope) |
| `pipeline_run_id`, `request_id` | The run, only when the runtime assigned it one, never a run id a request body names before any run exists, and the request, when there is one |
-| `run.extras.<key>` | Each of the run's opaque extras, one field per key, which the hosted plane fills with the organization |
+| `run.extras.<key>` | Each of the run's opaque extras, one field per key, which the hosted plane fills with the organization. The API server reads them off a request's `analytics_groups` as soon as its JSON body is parsed, whatever the route, so a refusal before any run exists, on a diagnostic route that runs none included, carries them too |
Never the URL, the path, the template, the schema, a prompt or an input value, nor the error's message, which may quote any of them, and never a traceback: the failure itself is reported where it is handled, as any other failure is. The runtime does not know organizations, so the event names one only through the run's extras, which it carries without reading.
-The class of destination is stated where the refusal is decided, with `PipelexError.with_security_target_class()`. The SSRF guard classifies the host it refused, or the first disallowed address a name resolved to, through `classify_disallowed_host` in `pipelex/tools/network/host_rules.py`, and a read the run's read scope refuses takes its class from its reason, a storage key of another tenant or a scheme the run does not read. A refusal that states no class, such as a schema or a template refusal, has no `security.target_class`.
+The class of destination is stated where the refusal is decided, with `PipelexError.with_security_target_class()`. The SSRF guard classifies the host it refused, or the first disallowed address a name resolved to, through `classify_disallowed_host` in `pipelex/tools/network/host_rules.py`, and a read the run's read scope refuses takes its class from its reason, a storage key of another tenant or a scheme the run does not read. A refusal that states no class, such as a schema or a template refusal, has no `security.target_class`. The caller's problem carries the class too, as the URL refusal's `target_class` parameter, which its code's sentence reads as a word ("points at a private target"), so it is always a value the registry lists (`SecurityTargetClass.listed_target_class`): a storage key of another tenant, which the registry lists no value for, is `private` there, while the event keeps `foreign_storage_key`.
-**Where it is logged.** `pipelex/errors/security_event.py` holds the event, and **the process that raises a refusal logs it**: whoever executes a run owns the events of the refusals raised in it, and the side that dispatched the run to another process never logs a failure it receives from there. Three boundaries call it, each with what it knows of the run:
+**Where it is logged.** `pipelex/errors/security_event.py` holds the event, and **the process that raises a refusal logs it**: whoever executes a run owns the events of the refusals raised in it, and the side that dispatched the run to another process never logs a failure it receives from there. Each of these boundaries calls it, with what it knows of the run:
- the pipe run, `PipeRun`, for a refusal raised while it executes, whether one of its pipes raised it or its tail did, such as a webhook the SSRF guard refuses at fire time, with the run's identity, its extras included;
+- the validation sweep, `BundleValidator`, for a refusal one of its dry runs meets before its pipe run starts, such as while the mock inputs are built, with the dry run's id and the caller's extras; it finds a refusal its pipe run logged already reported, and marks the `DryRunError` it raises for the sweep, which is new and reports each refusal again, as logged;
- the runner, `PipelexMTHDSProtocol.execute`, for a refusal before the run exists, at the input seam or while the method loads, with the runner's extras, and for a run's refusal raised in this process that the pipe run left unreported, with the run's identity: a pipe run that hands the job to another process can be refused here first, such as an input URL the SSRF guard refuses while it uploads the inputs before it dispatches. A refusal the pipe run logged, `PipeRun` in this process, is found reported, and so is a failure an orchestrator rebuilt from a remote worker's report, which it marks where it rebuilds it;
-- the API server's handler of every `PipelexError`, for a refusal answered before any run, and its handler of the problem responses it authors itself, for the refusals of a security rule it decides at its own boundary: a reserved object key in a run body (`pipelex.security.reserved_key`), a callback URL whose scheme or host the SSRF rule refuses (`security.input_url_refused`), and a resource path or a key of a method tree that leaves the method (`security.input_path_refused`). Both log with the extras the request body carried and no run id. One rule tells a path that leaves its root from one of the wrong shape, `root_escape_refusal` in `pipelex/core/bundle_resources/bundle_resource.py`: a path that is absolute, names a drive or a network share, or holds a `..` segment, read with either separator, leaves it, and any other refused path, empty or holding a backslash or a colon, is `request.invalid` and logs no event. It decides for a key of `resources`, a file submitted beside a method, and a key of a method tree, which the standard's reader refuses without saying why.
+- the API server's handler of every `PipelexError`, for a refusal answered before any run, and its handler of the problem responses it authors itself, for the refusals of a security rule it decides at its own boundary: a reserved object key in a run body (`pipelex.security.reserved_key`), a callback URL whose scheme or host the SSRF rule refuses (`security.input_url_refused`), and a resource path or a key of a method tree that leaves the method (`security.input_path_refused`). Both log with the extras the request body carried and no run id. One rule tells a path that leaves its root from one of the wrong shape, `root_escape_of` in `pipelex/core/bundle_resources/bundle_resource.py`, whose `RootEscape` gives both the reason a message reads and the `rule` the refusal names: a path that is absolute, names a drive or a network share, or holds a `..` segment, read with either separator, leaves it, and any other refused path, empty or holding a backslash or a colon, logs no event and is `request.invalid` as a key of `resources` or a file submitted beside a method, and `method.package_invalid` with the reason `invalid_tree_path` as a key of a method tree. It decides for each of them, the standard's reader refusing a key of a method tree without saying why.
A refusal is reported once per process, however many of these boundaries it crosses: the event marks the errors of the chain it reported, and a boundary that receives the same failure again, wrapped, finds the mark and logs nothing. The refusal is the error of the chain that carries or implies the code the failure reports, so a wrapper chained to it with `from`, which takes its code, restates it, while a new refusal is reported on its own, even of the same code, whether it was raised while a reported one was being handled or chained to one with `from`: a run whose input URL the SSRF guard refused, and whose webhook it then refuses, logs two events. Across processes, the rule above keeps it to one event whatever the transport rebuilds: a distributed orchestrator logs the refusal on the worker that raised it, at the boundary where the failure leaves that process, and marks every error it rebuilds from another process's report with `mark_security_event_emitted()`, so that neither its own boundaries nor the runner log it again, since the runner logs a run failure it finds unreported; [Orchestrator Plugins](./orchestrator-plugins.md#security-refusals-are-logged-where-they-are-raised) states what an orchestrator owes. A `/start` run, whose failure the dispatching side never receives, is covered the same way. A host that decides a refusal itself, such as a gateway's refusal of a private address or a tenant-boundary refusal of its own, logs the same record with `log_security_event()`. A program embedding the kernel without the runner (see [The Pipelex Kernel](./pipelex-kernel.md)) calls `emit_security_event()` on the refusals it receives.
@@ -578,9 +579,9 @@ Exception
├── PipelexConfigError → one of pipelex.config.invalid, .syntax, .file_missing; gives its migration as a fact
├── PipelexSetupError → inherits its cause's code, else runtime.misconfigured
├── SecurityError base_exceptions.py — abstract; the policy refusals never absorbed into a domain answer
- │ ├── UriReadRefusedError / SsrfBlockedError → security.input_url_refused, .method_url_refused (and .provider_url_refused)
+ │ ├── UriReadRefusedError / SsrfBlockedError ← security.input_url_refused, or .method_url_refused (and .provider_url_refused) where the site that knows the URL's author chooses it
│ ├── UnsafeSchemaError → security.schema_refused
- │ └── Jinja2TemplateSecurityError → security.template_refused, else runtime.unexpected on Pipelex's own template
+ │ └── Jinja2TemplateSecurityError ← the template sandbox's refusal at render time: security.template_refused, else runtime.unexpected on Pipelex's own template
├── CogtError cogt/exceptions.py — abstract; error_category, provider_metadata, problem_facts()
│ ├── LLMCompletionError ← a set the worker's classification picks from
│ ├── ImgGenGenerationError ← a set the worker's classification picks from
@@ -589,7 +590,7 @@ Exception
└── ... (one exceptions.py per package) ...
```
-`SecurityError` is the abstract base class of the policy refusals that are never absorbed into a domain answer: `UriReadRefusedError` (a read outside the run's scope), `SsrfBlockedError` (an outbound request the SSRF guard blocks), `UnsafeSchemaError` (a schema carrying Python code-generation extensions) and `Jinja2TemplateSecurityError` (a template the sandbox refuses at render time). The handlers that turn a refusal of the caller's input into a verdict, the bundle-validation cascade and the library load, let a `SecurityError` through as it is, and the cascade also lets through any refusal coded in a security family, whatever its class (`is_security_refusal` in `pipelex/errors/security_event.py`), and a host that treats this family alike, a durable-execution plugin marking it non-retryable for instance, names that base class. Not every refusal belongs to it: the template sandbox's render-budget refusal, `Jinja2TemplateBudgetError`, is a `ToolError` coded `pipe.template_budget_exceeded`, and `TemplateUrlRefusedError`, coded `security.method_path_refused`, derives from `PipelexError` directly, so each is handled by its code like any other refusal.
+`SecurityError` is the abstract base class of the policy refusals that are never absorbed into a domain answer: `UriReadRefusedError` (a read outside the run's scope), `SsrfBlockedError` (an outbound request the SSRF guard blocks), `UnsafeSchemaError` (a schema carrying Python code-generation extensions) and `Jinja2TemplateSecurityError` (a template the sandbox refuses at render time). The handlers that turn a refusal of the caller's input into a verdict, the bundle-validation cascade and the library load, let a `SecurityError` through as it is, and the cascade also lets through any refusal coded in a security family, whatever its class and whichever arm meets it, a wrapper inheriting its cause's code and a dry run's failures included (`security_target_kind` in `pipelex/errors/security_event.py`), and a host that treats this family alike, a durable-execution plugin marking it non-retryable for instance, names that base class. Not every refusal belongs to it: the template sandbox's render-budget refusal, `Jinja2TemplateBudgetError`, is a `ToolError` coded `pipe.template_budget_exceeded`, and `TemplateUrlRefusedError`, coded `security.method_path_refused`, derives from `PipelexError` directly, so each is handled by its code like any other refusal.
### Factory-time vs Runtime
diff --git a/docs/under-the-hood/pipe-func-requirements.md b/docs/under-the-hood/pipe-func-requirements.md
index 1545a3dae..7be433f46 100644
--- a/docs/under-the-hood/pipe-func-requirements.md
+++ b/docs/under-the-hood/pipe-func-requirements.md
@@ -30,7 +30,7 @@ A requirement whose marker is false in the environment is not needed there and i
Each tree declaring requirements is judged against the environment resolved for its own requirements, so when one check judges several trees, such as the library directories of one load, each gets the offer stated for it and never another tree's.
-In the `direct` mode, a method's Python is imported into the process that loads it, when its steps first bind their functions, and that is the process the check judges. A distributed orchestrator, such as our Temporal plugin, never carries a method's Python to its worker: the library crate names the step's method tree by its digest, and in a sandbox mode the call's files are read through the method file store by whoever runs it, for the sandbox to import them, never this process. A worker in the `direct` mode therefore runs only the functions its own deployment installed, whose packages are that deployment's to install, and the API server refuses a caller's Python outright unless it is sandbox-hosted (`403 CustomCodeRequiresSandbox`). So no worker needs to repeat the check.
+In the `direct` mode, a method's Python is imported into the process that loads it, when its steps first bind their functions, and that is the process the check judges. A distributed orchestrator, such as our Temporal plugin, never carries a method's Python to its worker: the library crate names the step's method tree by its digest, and in a sandbox mode the call's files are read through the method file store by whoever runs it, for the sandbox to import them, never this process. A worker in the `direct` mode therefore runs only the functions its own deployment installed, whose packages are that deployment's to install, and the API server refuses a caller's Python outright unless it is sandbox-hosted (a `501` `pipelex.deployment.custom_code_requires_sandbox`). So no worker needs to repeat the check.
## How a refusal names the method
diff --git a/docs/under-the-hood/template-sandbox.md b/docs/under-the-hood/template-sandbox.md
index ca722ab1f..a6d304747 100644
--- a/docs/under-the-hood/template-sandbox.md
+++ b/docs/under-the-hood/template-sandbox.md
@@ -44,7 +44,7 @@ Many refusals are visible in the template itself, and validation reports them be
What validation cannot see, because it depends on the values at run time (a method call, a name computed while rendering, or a bracketed key, which is legitimate on a plain dict), is refused where it happens: the render raises `Jinja2TemplateSecurityError`, with the code `security.template_refused`, whose message names the type the refused name was reached on, and the attribute or callable only when the template spells it, as in `{{ record._secret }}`. A refusal never renders as an empty string, so a prompt is never sent with a hole in it.
-`Jinja2TemplateSecurityError` is a `SecurityError`, like `UriReadRefusedError`, `SsrfBlockedError` and `UnsafeSchemaError`, the other policy refusals that are never absorbed into a domain answer. A host that treats that family alike, never retrying any of it, catches that base class, and an `except ToolError` around a render does not catch this refusal. `Jinja2TemplateSecurityError` stays a type of its own, apart from `Jinja2TemplateRenderError`, which a template that fails for any other reason raises.
+`Jinja2TemplateSecurityError` is a `SecurityError`, like `UriReadRefusedError`, `SsrfBlockedError` and `UnsafeSchemaError`, the other policy refusals that are never absorbed into a domain answer. A host that treats that family alike, never retrying any of it, catches that base class, and an `except ToolError` around a render does not catch this refusal. The sandbox's budget refusal is a separate error, `Jinja2TemplateBudgetError`, which is a `ToolError` (see below). `Jinja2TemplateSecurityError` stays a type of its own, apart from `Jinja2TemplateRenderError`, which a template that fails for any other reason raises.
A render that would overdraw its budget raises `Jinja2TemplateBudgetError`, with the code `pipe.template_budget_exceeded`, whose message names the operation that was refused and what it would have spent, never the template or a value: for example, *the operator '\*' needs about 1,000,000,000, and 134,217,062 are left*. A refused call names the method it called only when the template spells that name, as in `{{ note.center(width) }}`; a method the template reaches by a value, as in `{{ (note | attr(key))(width) }}`, is described without its name, *calling a method of a 'str' value*. A template whose macros or includes nest deeper than Python allows raises the same error. It is a `ToolError`, not a `SecurityError`: a budget is a limit on what a render may spend rather than a policy refusal, so it is handled by its code like any other fault of the method.
diff --git a/pipelex/base_exceptions.py b/pipelex/base_exceptions.py
index aaa62968e..0657da7aa 100644
--- a/pipelex/base_exceptions.py
+++ b/pipelex/base_exceptions.py
@@ -59,6 +59,29 @@ def iter_cause_chain(exc: BaseException) -> Iterator[BaseException]:
node = node.__cause__
+def iter_traceback_chain(exc: BaseException) -> Iterator[BaseException]:
+ """Yield ``exc`` and each exception a traceback of it prints, outermost first, exactly once.
+
+ The walk a traceback makes, where :func:`iter_cause_chain` follows ``__cause__`` alone: an explicit cause
+ (``raise ... from``) is followed, else the exception being handled when it was raised, ``__context__``, unless the
+ raise suppressed it (``from None``). It is for a reader that must account for everything a traceback would print
+ of a failure, such as a log record naming the chain's classes in place of the traceback, or a classifier looking
+ for a transport failure anywhere below the error it received. Cycle-guarded like :func:`iter_cause_chain`, since it
+ runs on the error path.
+ """
+ node: BaseException | None = exc
+ seen: set[int] = set()
+ while node is not None and id(node) not in seen:
+ seen.add(id(node))
+ yield node
+ if node.__cause__ is not None:
+ node = node.__cause__
+ elif node.__suppress_context__:
+ node = None
+ else:
+ node = node.__context__
+
+
def iter_pipelex_cause_chain(exc: BaseException) -> Iterator["PipelexError"]:
"""Yield ``exc`` and each Pipelex error below it along its ``__cause__`` chain, stopping at the first that is not one.
@@ -171,9 +194,9 @@ class ValidationErrorItem(BaseModel):
The error channel is built exclusively by
``pipelex.pipeline.validation_errors.build_validation_error_items``, which the agent
- CLI's problem (``ValidateBundleError.problem_items``) and the API path
- (``ValidateBundleError.validation_error_items``) both reach — so the CLI's structured
- output and the API's invalid verdict can never drift. The same
+ CLI's problem and the API's invalid verdict both reach through ``ValidateBundleError.problem_items``,
+ and a validator's invalid arm through ``ValidateBundleError.validation_error_items`` — so the CLI's
+ structured output and the API's invalid verdict can never drift. The same
item type also carries the report's advisory ``warnings``, built by
``pipelex.pipeline.advisory_warnings``: a warning is the same shape of
diagnostic, differing only in that it does not make the verdict invalid.
@@ -222,6 +245,9 @@ class ValidationErrorItem(BaseModel):
# (a defined name, a Table, a cell, a shape, a tag). Optional and additive, like ``declared_concepts``.
template_file: str | None = None
template_location: str | None = None
+ # The hint locator, carried by a hint lint item: the hint key the finding is about, elided as its message quotes it,
+ # which its problem item names as the code's ``hint`` parameter. Optional and additive, like ``declared_concepts``.
+ hint_key: str | None = None
# Structured, deterministic fix for this error, when the fix planner derived one from the
# enriched error data. Optional and additive: non-fixable items serialize unchanged under
# ``exclude_none``.
@@ -280,13 +306,13 @@ class PipelexError(Exception):
# The code the raise site chose with :meth:`with_error_code`, from the codes the class declares.
_chosen_error_code: ErrorCode | None = None
- # The class of destination a security refusal refused, stated by the raise site with
- # :meth:`with_security_target_class`; the security event carries it and nothing else about the target.
- _security_target_class: SecurityTargetClass | None = None
# The parameters the raise site gave with :meth:`with_params`.
_given_params: dict[str, Any] | None = None
# The items the raise site gave with :meth:`with_items`, one per fault of a refusal of several.
_given_items: list[ProblemItem] | None = None
+ # The class of destination a security refusal refused, stated by the raise site with
+ # :meth:`with_security_target_class`; the security event carries it and nothing else about the target.
+ _security_target_class: SecurityTargetClass | None = None
def __init_subclass__(cls, **kwargs: Any) -> None:
super().__init_subclass__(**kwargs)
@@ -328,28 +354,6 @@ class PipelexError(Exception):
self._chosen_error_code = error_code
return self
- def with_security_target_class(self, target_class: SecurityTargetClass | None) -> Self:
- """State, where a security refusal is decided, which class of destination it refused.
-
- The security event (:mod:`pipelex.errors.security_event`) names that class, a loopback or a private address,
- a cloud metadata endpoint, a scheme the runtime does not read, and never the destination itself. Only the
- raise site knows it: the SSRF guard has the address in hand, the read scope the reason. ``None`` leaves the
- class unknown, for a site that refused something it cannot classify, such as a name that resolved to nothing.
-
- Args:
- target_class: The class of destination refused, or ``None`` when the site cannot tell.
-
- Returns:
- This error, so that the raise site reads ``raise SomeError(msg).with_security_target_class(target_class)``.
- """
- self._security_target_class = target_class
- return self
-
- @property
- def security_target_class(self) -> SecurityTargetClass | None:
- """The class of destination this security refusal refused, ``None`` when nobody stated it."""
- return self._security_target_class
-
def with_params(self, **params: Any) -> Self:
"""Give, where this error is raised, the parameters its code's sentences are rendered from.
@@ -403,6 +407,28 @@ class PipelexError(Exception):
"""The parameters the raise site gave with :meth:`with_params`."""
return dict(self._given_params or {})
+ def with_security_target_class(self, target_class: SecurityTargetClass | None) -> Self:
+ """State, where a security refusal is decided, which class of destination it refused.
+
+ The security event (:mod:`pipelex.errors.security_event`) names that class, a loopback or a private address,
+ a cloud metadata endpoint, a scheme the runtime does not read, and never the destination itself. Only the
+ raise site knows it: the SSRF guard has the address in hand, the read scope the reason. ``None`` leaves the
+ class unknown, for a site that refused something it cannot classify, such as a name that resolved to nothing.
+
+ Args:
+ target_class: The class of destination refused, or ``None`` when the site cannot tell.
+
+ Returns:
+ This error, so that the raise site reads ``raise SomeError(msg).with_security_target_class(target_class)``.
+ """
+ self._security_target_class = target_class
+ return self
+
+ @property
+ def security_target_class(self) -> SecurityTargetClass | None:
+ """The class of destination this security refusal refused, ``None`` when nobody stated it."""
+ return self._security_target_class
+
@property
def own_error_code(self) -> ErrorCode | None:
"""The code this error carries by itself, ``None`` when it takes its cause's.
diff --git a/pipelex/core/bundle_resources/bundle_resource.py b/pipelex/core/bundle_resources/bundle_resource.py
index cee2a45ed..75ce62671 100644
--- a/pipelex/core/bundle_resources/bundle_resource.py
+++ b/pipelex/core/bundle_resources/bundle_resource.py
@@ -8,32 +8,64 @@ it would in a folder, and the run's crate names that tree by its digest like any
"""
from collections.abc import Mapping
+from enum import StrEnum
from pathlib import PurePosixPath, PureWindowsPath
-from mthds.protocol.problem.registry import CoreCode
+from mthds.protocol.problem.registry import CoreCode, SecurityInputPathRefusedRule
from pipelex.core.bundle_resources.exceptions import BundleResourcePathError
+# The field of a run request the files submitted with its bundles ride, which a refusal of one of their paths names.
+SUBMITTED_FILES_FIELD = "resources"
-def root_escape_refusal(*, path: str) -> str | None:
- r"""Why `path`, written relative to a root, would reach outside that root, or None when it stays below it.
+
+class RootEscape(StrEnum):
+ """How a path written relative to a root would reach outside that root."""
+
+ DRIVE = "drive"
+ ROOTED = "rooted"
+ PARENT_SEGMENT = "parent_segment"
+
+ @property
+ def desc(self) -> str:
+ """Why the path is refused, in words that never repeat it."""
+ match self:
+ case RootEscape.DRIVE:
+ return "it names a drive or a network share; write it relative to the bundle"
+ case RootEscape.ROOTED:
+ return "it is absolute; write it relative to the bundle"
+ case RootEscape.PARENT_SEGMENT:
+ return "it leaves the bundle through a '..' segment"
+
+ @property
+ def rule(self) -> SecurityInputPathRefusedRule:
+ """The rule of ``security.input_path_refused`` the path breaks: a drive or a network share is `absolute` too."""
+ match self:
+ case RootEscape.DRIVE | RootEscape.ROOTED:
+ return SecurityInputPathRefusedRule.ABSOLUTE
+ case RootEscape.PARENT_SEGMENT:
+ return SecurityInputPathRefusedRule.PARENT_SEGMENT
+
+
+def root_escape_of(*, path: str) -> RootEscape | None:
+ r"""How `path`, written relative to a root, would reach outside that root, or None when it stays below it.
The one rule telling a path that tries to leave its root, a security refusal (``security.input_path_refused`` for a
- caller's path), from a path of the wrong shape, a refusal of the request: it is held by the key of a file submitted
- with a bundle, by a file submitted beside a method, and by a key of a method tree a request carries, which the
- standard's reader refuses without saying why. The path is read with either separator, as a system that follows a
- backslash would read it: it leaves its root when it is absolute or rooted (`/etc/passwd`, `\etc`), when it names a
- drive or a network share (`C:/Windows`, `C:secrets`, `\\server\share`), or when one of its segments is `..`. Any
- other path that is refused, empty, holding a backslash, a colon or a NUL character, is of the wrong shape. The
- reason never repeats the path.
+ caller's path, naming the escape's `rule`), from a path of the wrong shape, a refusal of the request: it is held by
+ the key of a file submitted with a bundle, by a file submitted beside a method, and by a key of a method tree a
+ request carries, which the standard's reader refuses without saying why. The path is read with either separator, as
+ a system that follows a backslash would read it: it leaves its root when it names a drive or a network share
+ (`C:/Windows`, `C:secrets`, `\\server\share`), when it is absolute or rooted (`/etc/passwd`, `\etc`), or when one of
+ its segments is `..`. Any other path that is refused, empty, holding a backslash, a colon or a NUL character, is of
+ the wrong shape.
"""
windows_path = PureWindowsPath(path)
if windows_path.drive:
- return "it names a drive or a network share; write it relative to the bundle"
+ return RootEscape.DRIVE
if windows_path.root:
- return "it is absolute; write it relative to the bundle"
+ return RootEscape.ROOTED
if ".." in windows_path.parts:
- return "it leaves the bundle through a '..' segment"
+ return RootEscape.PARENT_SEGMENT
return None
@@ -42,14 +74,18 @@ def resource_path_refusal(*, path: str) -> str | None:
The one rule for a bundle-relative path, held by the key of a file submitted with a bundle and by the path a step
names, such as a `PipeDocGen` step's `template_file`, so any file a step names can be submitted with its bundle.
- A path that leaves the bundle says so first (`root_escape_refusal`). The reason never repeats the path, which a host
+ A path that leaves the bundle says so first (`root_escape_of`). The reason never repeats the path, which a host
library's step would otherwise put in front of a caller.
"""
+ return _path_refusal_reason(path=path, escape=root_escape_of(path=path))
+
+
+def _path_refusal_reason(*, path: str, escape: RootEscape | None) -> str | None:
+ """Why `path` cannot name a file inside a bundle, `escape` being how it leaves the bundle (`root_escape_of`)."""
if not path.strip():
return "it is empty"
- escape = root_escape_refusal(path=path)
if escape is not None:
- return escape
+ return escape.desc
if "\\" in path:
return "it holds a backslash; write the path with forward slashes"
if ":" in path:
@@ -80,20 +116,28 @@ def canonical_resource_path(*, path: str) -> str:
Raises:
BundleResourcePathError: the path cannot name a file inside the bundle: ``security.input_path_refused`` for a
- path that leaves it (`root_escape_refusal`), ``request.invalid`` for a path of the wrong shape.
+ path that leaves it (`root_escape_of`), ``request.invalid`` for a path of the wrong shape.
"""
- refusal = resource_path_refusal(path=path)
+ # Read once: it decides both the reason the message gives and the refusal's code and parameters.
+ escape = root_escape_of(path=path)
+ refusal = _path_refusal_reason(path=path, escape=escape)
if refusal is not None:
msg = f"The file '{path}' submitted with the bundle cannot be one of its files: {refusal}."
- raise BundleResourcePathError(msg).with_error_code(path_refusal_code(path=path))
+ raise path_refusal_error(message=msg, escape=escape)
return PurePosixPath(path).as_posix()
-def path_refusal_code(*, path: str) -> CoreCode:
- """The code of the refusal of a caller's path: a security refusal when it leaves its root, else a refusal of the request."""
- if root_escape_refusal(path=path) is not None:
- return CoreCode.SECURITY_INPUT_PATH_REFUSED
- return CoreCode.REQUEST_INVALID
+def path_refusal_error(*, message: str, escape: RootEscape | None) -> BundleResourcePathError:
+ """The refusal of a submitted file's path, `escape` being how the path leaves its root (`root_escape_of`).
+
+ A path that leaves its root is a security refusal, ``security.input_path_refused``, naming the rule it breaks and
+ never the path; any other is a refusal of the request, ``request.invalid``, naming the field the submitted files
+ ride, `resources`.
+ """
+ error = BundleResourcePathError(message)
+ if escape is not None:
+ return error.with_error_code(CoreCode.SECURITY_INPUT_PATH_REFUSED).with_params(rule=escape.rule)
+ return error.with_error_code(CoreCode.REQUEST_INVALID).with_params(field=SUBMITTED_FILES_FIELD)
def canonical_submitted_files(*, files: Mapping[str, bytes]) -> dict[str, bytes]:
@@ -107,6 +151,6 @@ def canonical_submitted_files(*, files: Mapping[str, bytes]) -> dict[str, bytes]
canonical_path = canonical_resource_path(path=path)
if canonical_path in canonical_files:
msg = f"Two files submitted with the bundle name the same file '{canonical_path}'."
- raise BundleResourcePathError(msg).with_error_code(CoreCode.REQUEST_INVALID).with_params(field="resources")
+ raise BundleResourcePathError(msg).with_error_code(CoreCode.REQUEST_INVALID).with_params(field=SUBMITTED_FILES_FIELD)
canonical_files[canonical_path] = content
return canonical_files
diff --git a/pipelex/core/bundle_resources/exceptions.py b/pipelex/core/bundle_resources/exceptions.py
index 878f26e02..f9165b549 100644
--- a/pipelex/core/bundle_resources/exceptions.py
+++ b/pipelex/core/bundle_resources/exceptions.py
@@ -14,7 +14,7 @@ class BundleResourcePathError(PipelexError):
The path is the caller's own, so the message is theirs to read, and the same request is refused again. A path that
leaves the bundle, absolute, naming a drive or climbing with `..`, is ``security.input_path_refused``; a path of
the wrong shape, and paths that each could name a file but that cannot make one tree together, choose
- ``request.invalid`` (``pipelex.core.bundle_resources.bundle_resource.path_refusal_code``).
+ ``request.invalid`` (``pipelex.core.bundle_resources.bundle_resource.path_refusal_error``).
"""
error_code = ErrorCodeSet(default=CoreCode.SECURITY_INPUT_PATH_REFUSED, others=(CoreCode.REQUEST_INVALID,))
diff --git a/pipelex/errors/registry/pipelex-error-registry.json b/pipelex/errors/registry/pipelex-error-registry.json
index 2576fbbbd..674819c91 100644
--- a/pipelex/errors/registry/pipelex-error-registry.json
+++ b/pipelex/errors/registry/pipelex-error-registry.json
@@ -674,6 +674,39 @@
"meaning": "A file the run wrote, or that the runtime handed out, is no longer in storage. A caller's own reference to something that does not exist is `input.reference_not_found` instead.",
"what_to_do": "Report the problem to whoever runs the runtime, with the run's `pipeline_run_id` when it has one."
},
+ {
+ "code": "pipelex.storage.damaged",
+ "title": "A stored file is damaged",
+ "domain": "runtime",
+ "retry": "no",
+ "raised_as": "problem",
+ "status": 500,
+ "detail": "A file the runtime stored in its {scheme} storage no longer holds the bytes it was stored with.",
+ "steps": {
+ "actor": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ },
+ "other": {
+ "kind": "report",
+ "detail": "Report this to whoever runs the runtime."
+ }
+ },
+ "params": {
+ "scheme": {
+ "type": "enum",
+ "values": [
+ "local",
+ "s3",
+ "gcs",
+ "memory"
+ ],
+ "description": "The kind of storage that holds the damaged file."
+ }
+ },
+ "meaning": "Storage still holds an object under the file's key, but its bytes are not the ones the runtime stored: they do not hash to the key the file is stored under, or they are not the size storage holds them at. A retry reads the same damaged object, and no upload writes over it, so it stays until whoever runs the runtime removes it.",
+ "what_to_do": "Report the problem to whoever runs the runtime, with the `request_id`. Once they have removed the damaged object, upload the file again."
+ },
{
"code": "pipelex.storage.unavailable",
"title": "Storage is unavailable",
diff --git a/pipelex/errors/registry/pipelex-error-registry.yaml b/pipelex/errors/registry/pipelex-error-registry.yaml
index 95e26e10c..616405443 100644
--- a/pipelex/errors/registry/pipelex-error-registry.yaml
+++ b/pipelex/errors/registry/pipelex-error-registry.yaml
@@ -367,6 +367,21 @@ codes:
meaning: "A file the run wrote, or that the runtime handed out, is no longer in storage. A caller's own reference to something that does not exist is `input.reference_not_found` instead."
what_to_do: "Report the problem to whoever runs the runtime, with the run's `pipeline_run_id` when it has one."
+ - code: pipelex.storage.damaged
+ title: "A stored file is damaged"
+ domain: runtime
+ retry: "no"
+ raised_as: problem
+ status: 500
+ detail: "A file the runtime stored in its {scheme} storage no longer holds the bytes it was stored with."
+ steps:
+ actor: {kind: report, detail: "Report this to whoever runs the runtime."}
+ other: {kind: report, detail: "Report this to whoever runs the runtime."}
+ params:
+ scheme: {type: enum, values: [local, s3, gcs, memory], description: "The kind of storage that holds the damaged file."}
+ meaning: "Storage still holds an object under the file's key, but its bytes are not the ones the runtime stored: they do not hash to the key the file is stored under, or they are not the size storage holds them at. A retry reads the same damaged object, and no upload writes over it, so it stays until whoever runs the runtime removes it."
+ what_to_do: "Report the problem to whoever runs the runtime, with the `request_id`. Once they have removed the damaged object, upload the file again."
+
- code: pipelex.storage.unavailable
title: "Storage is unavailable"
domain: runtime
diff --git a/pipelex/errors/registry/pipelex_codes.py b/pipelex/errors/registry/pipelex_codes.py
index 51c88709f..43fdb5ae3 100644
--- a/pipelex/errors/registry/pipelex_codes.py
+++ b/pipelex/errors/registry/pipelex_codes.py
@@ -37,6 +37,7 @@ class PipelexErrorCode(StrEnum):
RUN_ALREADY_EXISTS = "pipelex.run.already_exists"
STORAGE_URI_INVALID = "pipelex.storage.uri_invalid"
STORAGE_NOT_FOUND = "pipelex.storage.not_found"
+ STORAGE_DAMAGED = "pipelex.storage.damaged"
STORAGE_UNAVAILABLE = "pipelex.storage.unavailable"
STORAGE_NOT_CONFIGURED = "pipelex.storage.not_configured"
STORAGE_GRANT_UNUSABLE = "pipelex.storage.grant_unusable"
@@ -375,6 +376,20 @@ class StorageNotFoundParams(PipelexErrorParams):
scheme: Literal["local", "s3", "gcs", "memory"]
+class StorageDamagedParams(PipelexErrorParams):
+ """The parameters of `pipelex.storage.damaged`.
+
+ A stored file is damaged.
+
+ Attributes:
+ scheme: The kind of storage that holds the damaged file.
+ """
+
+ code: ClassVar[PipelexErrorCode] = PipelexErrorCode.STORAGE_DAMAGED
+
+ scheme: Literal["local", "s3", "gcs", "memory"]
+
+
class StorageUnavailableParams(PipelexErrorParams):
"""The parameters of `pipelex.storage.unavailable`.
@@ -975,6 +990,7 @@ PIPELEX_ERROR_PARAMS: dict[PipelexErrorCode, type[PipelexErrorParams]] = {
PipelexErrorCode.RUN_ALREADY_EXISTS: RunAlreadyExistsParams,
PipelexErrorCode.STORAGE_URI_INVALID: StorageUriInvalidParams,
PipelexErrorCode.STORAGE_NOT_FOUND: StorageNotFoundParams,
+ PipelexErrorCode.STORAGE_DAMAGED: StorageDamagedParams,
PipelexErrorCode.STORAGE_UNAVAILABLE: StorageUnavailableParams,
PipelexErrorCode.STORAGE_NOT_CONFIGURED: StorageNotConfiguredParams,
PipelexErrorCode.STORAGE_GRANT_UNUSABLE: StorageGrantUnusableParams,
@@ -1276,6 +1292,17 @@ PIPELEX_ERROR_ENTRIES: dict[PipelexErrorCode, PipelexErrorEntry] = {
other_step="report",
other_step_detail="Report this to whoever runs the runtime.",
),
+ PipelexErrorCode.STORAGE_DAMAGED: PipelexErrorEntry(
+ title="A stored file is damaged",
+ domain="runtime",
+ retry="no",
+ status=500,
+ detail="A file the runtime stored in its {scheme} storage no longer holds the bytes it was stored with.",
+ actor_step="report",
+ actor_step_detail="Report this to whoever runs the runtime.",
+ other_step="report",
+ other_step_detail="Report this to whoever runs the runtime.",
+ ),
PipelexErrorCode.STORAGE_UNAVAILABLE: PipelexErrorEntry(
title="Storage is unavailable",
domain="runtime",
diff --git a/pipelex/errors/security_target.py b/pipelex/errors/security_target.py
index d126086c1..68f0911bc 100644
--- a/pipelex/errors/security_target.py
+++ b/pipelex/errors/security_target.py
@@ -40,3 +40,23 @@ class SecurityTargetClass(StrEnum):
METADATA = "metadata"
SCHEME = "scheme"
FOREIGN_STORAGE_KEY = "foreign_storage_key"
+
+ @property
+ def listed_target_class(self) -> "SecurityTargetClass":
+ """The value the error registry lists for a URL refusal's ``target_class`` parameter that this class falls under.
+
+ A caller reads the parameter, and its code's sentence reads it as a word ("points at a private target"), so it
+ is always a value the registry lists. The security event keeps the class itself, which is finer: a storage key
+ outside the run's read scope, which the registry lists no value for, is someone else's private file to the caller.
+ """
+ match self:
+ case (
+ SecurityTargetClass.LOOPBACK
+ | SecurityTargetClass.PRIVATE
+ | SecurityTargetClass.LINK_LOCAL
+ | SecurityTargetClass.METADATA
+ | SecurityTargetClass.SCHEME
+ ):
+ return self
+ case SecurityTargetClass.FOREIGN_STORAGE_KEY:
+ return SecurityTargetClass.PRIVATE
diff --git a/pipelex/libraries/library_manager.py b/pipelex/libraries/library_manager.py
index 868a13a1c..babefa220 100644
--- a/pipelex/libraries/library_manager.py
+++ b/pipelex/libraries/library_manager.py
@@ -21,7 +21,7 @@ from pipelex import log
from pipelex.base_exceptions import ErrorDomain, PipelexError, SecurityError, iter_cause_chain
from pipelex.cogt.exceptions import ModelChoiceNotFoundError
from pipelex.config import is_pipe_func_sandbox_hosted
-from pipelex.core.bundle_resources.bundle_resource import canonical_submitted_files, path_refusal_code
+from pipelex.core.bundle_resources.bundle_resource import canonical_submitted_files, path_refusal_error, root_escape_of
from pipelex.core.bundle_resources.exceptions import BundleResourcePathError
from pipelex.core.concepts.concept_blueprint import ConceptBlueprint
from pipelex.core.concepts.concept_factory import ConceptFactory
@@ -638,7 +638,7 @@ class LibraryManager(LibraryManagerAbstract):
violation = tree_path_violation(path)
if violation is not None:
msg = f"The file '{path}' submitted beside the method cannot be a file of its tree: {violation}."
- raise BundleResourcePathError(msg).with_error_code(path_refusal_code(path=path))
+ raise path_refusal_error(message=msg, escape=root_escape_of(path=path))
already_held = joined.get(path)
if already_held is not None and already_held.sha256 != held_file.sha256:
msg = (
diff --git a/pipelex/pipe_run/exceptions.py b/pipelex/pipe_run/exceptions.py
index 7721400fd..1d9a2ea51 100644
--- a/pipelex/pipe_run/exceptions.py
+++ b/pipelex/pipe_run/exceptions.py
@@ -10,6 +10,7 @@ from pipelex.errors.error_code_declaration import ABSTRACT_ERROR, ErrorCodeDecla
from pipelex.errors.error_codes import ErrorCode, error_code_spec, first_fault_code
from pipelex.errors.problem import PipelexProblem, ProblemView, make_location, make_problem_item
from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
+from pipelex.errors.security_event import security_target_kind
from pipelex.pipe_run.located_failure import failure_location_of, locate_failure_message, located_problem, located_root_fault
from pipelex.system.pipe_run_mode import PipeRunMode
@@ -95,10 +96,12 @@ class DryRunError(PipelexError):
validation reports each as its own ``dry_run`` item, with the error type ``DryRunError``, the pipe's code,
domain and source, and the sentence the failure's code renders for a caller.
- With failures, its code is the one the answer takes among theirs (``first_fault_code``), its parameters are those of
- the failure that code is taken from, its pipe included, so that the problem's sentence renders whole, and its problem
- carries one item per failure; a validation answers it as an invalid verdict only when one of them is the method's.
- Raised elsewhere it may carry no failures, and then it takes the code of its cause, the failure it reports.
+ With failures, its code is the one the answer takes among theirs (``first_fault_code``), a security refusal's
+ before any other, so that a refusal a security rule made is answered under its code wherever it sits among the
+ failures; its parameters are those of the failure that code is taken from, its pipe included, so that the problem's
+ sentence renders whole, and its problem carries one item per failure; a validation answers it as an invalid verdict
+ only when one of them is the method's and none is a security refusal. Raised elsewhere it may carry no failures, and
+ then it takes the code of its cause, the failure it reports.
"""
error_code: ClassVar[ErrorCodeDeclaration] = InheritsCause(fallback=CoreCode.RUNTIME_UNEXPECTED)
@@ -108,13 +111,19 @@ class DryRunError(PipelexError):
super().__init__(message)
def _code_failure(self) -> DryRunFailureErrorData | None:
- """The failure whose code this error carries: the first of those whose code ``first_fault_code`` takes."""
- code = first_fault_code(codes=[failure.code for failure in self.failures])
+ """The failure whose code this error carries: the first whose code ``first_fault_code`` takes, among its security refusals if any."""
+ codes = self.security_failure_codes or [failure.code for failure in self.failures]
+ code = first_fault_code(codes=codes)
for failure in self.failures:
if failure.code == code:
return failure
return None
+ @property
+ def security_failure_codes(self) -> list[ErrorCode]:
+ """The codes of its failures that a security rule refused, in the order the sweep found them."""
+ return [failure.code for failure in self.failures if security_target_kind(code=failure.code) is not None]
+
@property
@override
def own_error_code(self) -> ErrorCode | None:
diff --git a/pipelex/pipeline/bundle_validator.py b/pipelex/pipeline/bundle_validator.py
index f8fb2f24d..6eee7540e 100644
--- a/pipelex/pipeline/bundle_validator.py
+++ b/pipelex/pipeline/bundle_validator.py
@@ -45,6 +45,7 @@ from pipelex.core.exceptions import DryRunFailureErrorData
from pipelex.core.pipes.exceptions import caller_refusal
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.errors.error_codes import ErrorCode
+from pipelex.errors.security_event import emit_security_event, mark_security_event_emitted
from pipelex.interpreter_hub import (
clear_current_library,
get_current_library,
@@ -585,6 +586,14 @@ class BundleValidator:
error_message = f"Skipped dry run for pipe '{pipe.pipe_ref}': unresolved dependency: {exc}"
log.verbose("A pipe's dry run was skipped for an unresolved dependency", fields={"pipe_ref": pipe.pipe_ref, **error_fields(exc=exc)})
return DryRunOutput(pipe_code=pipe.code, pipe_ref=pipe.pipe_ref, status=DryRunStatus.SKIPPED, error_message=error_message)
+ # A refusal of a security rule is logged once, where it is met: the pipe run logs the one it meets while it
+ # executes (`PipeRun.run`), which this finds marked, and this logs one met before any pipe run, such as while
+ # the mock inputs are built, which nobody else would, so the sweep's error can be marked as logged.
+ emit_security_event(
+ error=exc,
+ pipeline_run_id=dry_run_pipeline_id,
+ extras=caller_identity.extras if caller_identity is not None else None,
+ )
formatted_error = format_pydantic_validation_error(exc) if isinstance(exc, ValidationError) else str(exc)
error_message = f"Dry run failed for pipe '{pipe.pipe_ref}': {formatted_error}"
# A failure raised outside any routed pipe run (the mock-input build) is the swept pipe's own.
@@ -649,7 +658,12 @@ class BundleValidator:
met_texts = {id(output.failure): output.error_message for output in unexpected_failures.values() if output.failure is not None}
details = "\n".join(f"- {met_texts.get(id(failure)) or failure.message}" for failure in failures)
msg = f"Dry run failed for {len(failures)} pipe(s):\n{details}"
- raise DryRunError(msg, failures=failures)
+ dry_run_error = DryRunError(msg, failures=failures)
+ if dry_run_error.security_failure_codes:
+ # Each refusal's security event was logged where the sweep met it (`_run_and_classify`), and this error,
+ # which reports the first under its code, is new: marked, so the boundary it reaches does not log it twice.
+ mark_security_event_emitted(error=dry_run_error)
+ raise dry_run_error
return results
@classmethod
diff --git a/pipelex/pipeline/hint_warnings.py b/pipelex/pipeline/hint_warnings.py
index 96d44b315..07416aa0c 100644
--- a/pipelex/pipeline/hint_warnings.py
+++ b/pipelex/pipeline/hint_warnings.py
@@ -180,21 +180,24 @@ class _HintLinter:
field_name: str | None = None,
variable_names: list[str] | None = None,
) -> list[ValidationErrorItem]:
- findings: list[tuple[HintLintErrorType, str]] = []
+ # Each finding with the hint key it is about, elided as its message quotes it.
+ findings: list[tuple[HintLintErrorType, str, str]] = []
unknown_keys = [key for key in hints if key not in KNOWN_HINT_KEYS]
for key in unknown_keys[:MAX_HINT_FINDINGS_PER_SITE]:
unknown_key_message = (
f"Hint key '{elide_authored_token(token=key)}' on {site_desc} is not defined by this version of the standard "
f"(known keys: {', '.join(sorted(KNOWN_HINT_KEYS))}). The entry is preserved; consumers ignore it."
)
- findings.append((HintLintErrorType.HINT_UNKNOWN_KEY, unknown_key_message))
+ findings.append((HintLintErrorType.HINT_UNKNOWN_KEY, unknown_key_message, elide_authored_token(token=key)))
overflow = len(unknown_keys) - MAX_HINT_FINDINGS_PER_SITE
if overflow > 0:
overflow_message = (
f"...and {overflow} more hint key(s) on {site_desc} are not defined by this version of the standard. "
f"The entries are preserved; consumers ignore them."
)
- findings.append((HintLintErrorType.HINT_UNKNOWN_KEY, overflow_message))
+ # The finding stands for every key past the cap, and names the first of them.
+ first_overflow_key = elide_authored_token(token=unknown_keys[MAX_HINT_FINDINGS_PER_SITE])
+ findings.append((HintLintErrorType.HINT_UNKNOWN_KEY, overflow_message, first_overflow_key))
intent_word = hints.get(INTENT_HINT_KEY)
if intent_word is not None:
if not is_intent_word_known(intent_word):
@@ -202,7 +205,7 @@ class _HintLinter:
f"Intent word '{elide_authored_token(token=intent_word)}' on {site_desc} is not in this version's vocabulary "
f"(prose, label, rating, quantity). The entry is preserved; consumers ignore it."
)
- findings.append((HintLintErrorType.HINT_UNKNOWN_INTENT, unknown_intent_message))
+ findings.append((HintLintErrorType.HINT_UNKNOWN_INTENT, unknown_intent_message, INTENT_HINT_KEY))
elif not intent_word_applies(known_word := IntentWord(intent_word), site_kind=site_kind):
match known_word:
case IntentWord.PROSE | IntentWord.LABEL:
@@ -213,7 +216,7 @@ class _HintLinter:
f"Intent word '{elide_authored_token(token=intent_word)}' does not apply to {site_desc} (the site is not "
f"{needed_kind}-valued). The entry is preserved; consumers ignore it there."
)
- findings.append((HintLintErrorType.HINT_INAPPLICABLE_INTENT, inapplicable_message))
+ findings.append((HintLintErrorType.HINT_INAPPLICABLE_INTENT, inapplicable_message, INTENT_HINT_KEY))
return [
ValidationErrorItem(
category=ValidationErrorCategory.BLUEPRINT_VALIDATION,
@@ -224,8 +227,9 @@ class _HintLinter:
pipe_code=pipe_code,
field_name=field_name,
variable_names=variable_names,
+ hint_key=hint_key,
)
- for error_type, message in findings
+ for error_type, message, hint_key in findings
]
# ---- Site classification (spec: Applicability) ------------------------------------------------
diff --git a/pipelex/pipeline/runner.py b/pipelex/pipeline/runner.py
index c821aed1c..192950930 100644
--- a/pipelex/pipeline/runner.py
+++ b/pipelex/pipeline/runner.py
@@ -306,9 +306,9 @@ class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):
``RunMetadata.request_id`` so every log line of the run, on
whichever worker runs it, and the run's error reports carry it.
An in-process host hook, like ``delivery_assignment``, not a wire
- extension. It must be one to 128 printable ASCII characters: any
- other value is the host's bug, refused with a ``ValueError``
- before the run is set up.
+ extension. It must be one to 128 ASCII letters, digits, ``_``
+ or ``-`` (``validate_request_id``): any other value is the host's
+ bug, refused with a ``RunParameterError`` before the run is set up.
Returns:
-------
diff --git a/pipelex/pipeline/validate_bundle_translation.py b/pipelex/pipeline/validate_bundle_translation.py
index ace15cb86..6804ba3a7 100644
--- a/pipelex/pipeline/validate_bundle_translation.py
+++ b/pipelex/pipeline/validate_bundle_translation.py
@@ -32,9 +32,9 @@ from pipelex.core.pipes.exceptions import (
refusal_detail,
)
from pipelex.core.validation import report_validation_error
-from pipelex.errors.error_codes import code_is_method_domain
+from pipelex.errors.error_codes import ErrorCode, code_is_method_domain
from pipelex.errors.problem import ProblemView
-from pipelex.errors.security_event import is_security_refusal
+from pipelex.errors.security_event import security_target_kind
from pipelex.interpreter_hub import get_library_manager
from pipelex.libraries.exceptions import LibraryError, LibraryLoadingError, MethodTreeLoadError
from pipelex.libraries.library_utils import get_pipelex_mthds_files_from_dirs
@@ -103,11 +103,11 @@ def translate_to_validate_bundle_error() -> Generator[None, None, None]:
belongs to another actor, the runtime's own included, answers its own code, never that the method is
invalid. A failure of the tool or its environment, a refusal of another actor than the method's author,
anything that is not a ``PipelexError``, propagates as no verdict, along with the refusals that must
- keep their own class: ``PipeNotFoundError`` (its
- dedicated not-found handler), a security refusal, a ``SecurityError`` or any refusal coded in a security
- family (never absorbed by a domain handler), a ``ValidateBundleError`` already produced (never re-wrapped),
- and a ``BundleResourceNotNamedError`` or a ``BundleResourcePathError``, which refuse the files submitted
- with the bundle rather than the bundle.
+ keep their own class: ``PipeNotFoundError`` (its dedicated not-found handler), a security refusal, a
+ ``SecurityError`` or any refusal coded in a security family (never absorbed by a domain handler, even
+ when its code is the method's, as ``security.method_path_refused`` is), a ``ValidateBundleError``
+ already produced (never re-wrapped), and a ``BundleResourceNotNamedError`` or a
+ ``BundleResourcePathError``, which refuse the files submitted with the bundle rather than the bundle.
"""
try:
yield
@@ -161,8 +161,8 @@ def translate_to_validate_bundle_error() -> Generator[None, None, None]:
# forward them so the CLI renders the same structured detail it does for the other arms.
# A library error that is not the method's, such as an invariant of the library manager
# (`runtime.unexpected`) or library directories configured wrongly (`pipelex.config.invalid`), is no
- # verdict about the bundle, and propagates as it is.
- if not code_is_method_domain(code=library_error.resolve_error_code()):
+ # verdict about the bundle, and propagates as it is, as does a security refusal.
+ if not _code_makes_a_verdict(code=library_error.resolve_error_code()):
raise
if isinstance(library_error, LibraryLoadingError):
blueprint_validation_errors = library_error.blueprint_validation_errors
@@ -183,9 +183,9 @@ def translate_to_validate_bundle_error() -> Generator[None, None, None]:
except PipeRunError as pipe_run_error:
# A pipe run failing outside the sweep's per-pipe classification: one dry-run item on its pipe when
# its fault is the method's, whose text is the sentence its code renders for the caller who reads the
- # verdict, and otherwise the fault itself, which no verdict carries.
+ # verdict, and otherwise the fault itself, which no verdict carries, a security refusal it wraps included.
failure_code = pipe_run_error.resolve_error_code()
- if not code_is_method_domain(code=failure_code):
+ if not _code_makes_a_verdict(code=failure_code):
raise
failure_problem = caller_refusal(refusal=pipe_run_error, pipe_code=pipe_run_error.pipe_code)
failure_params = failure_problem.params.as_wire() if failure_problem.params is not None else None
@@ -206,12 +206,15 @@ def translate_to_validate_bundle_error() -> Generator[None, None, None]:
except DryRunError as dry_run_error:
# The sweep's failures, one per failing pipe, located at the innermost pipe that failed. A
# DryRunError raised elsewhere carries none, and stands for one failure, its own. They are a verdict
- # only when one of them is the method's; otherwise the dry run's fault answers its own code, every
- # failure riding its items, and never reads as an invalid method.
+ # only when one of them is the method's and none is a security refusal; otherwise the dry run's fault
+ # answers its own code, a security refusal's first (`DryRunError.own_error_code`), every failure riding
+ # its items, and never reads as an invalid method.
dry_run_failures = dry_run_error.failures or [
DryRunFailureErrorData(code=dry_run_error.resolve_error_code(), message=refusal_detail(refusal=dry_run_error))
]
- if not any(code_is_method_domain(code=failure.code) for failure in dry_run_failures):
+ if any(security_target_kind(code=failure.code) is not None for failure in dry_run_failures):
+ raise
+ if not any(_code_makes_a_verdict(code=failure.code) for failure in dry_run_failures):
raise
raise ValidateBundleError(
message=dry_run_error.message,
@@ -271,24 +274,34 @@ def reporting_host_library_faults() -> Generator[None, None, None]:
raise HostLibraryLoadRefusalError(msg) from refusal
+def _code_makes_a_verdict(*, code: ErrorCode) -> bool:
+ """Whether a refusal coded so is a verdict about the bundle: its code is the method's, and no security refusal's.
+
+ Every arm of the translation asks it, so a security refusal, many of which the method's author acts on
+ (``security.method_path_refused``, ``security.template_refused``), keeps its code and its security event on
+ whichever error carries it, never becoming a verdict's item.
+ """
+ return code_is_method_domain(code=code) and security_target_kind(code=code) is None
+
+
def _make_refusal_verdict(*, refusal: PipelexError) -> ValidateBundleError | None:
"""The one-item verdict for a refusal of the caller's input that has no arm of its own, else ``None``.
``None`` — no verdict — unless the refusal's code is the method's: a refusal another actor must act on,
the caller's input, the account, the operator or the runtime, is never the bundle's fault, and keeps
- its own code. A security refusal has no verdict either, whatever its class and its domain: a refusal coded in
- a security family, such as a step's template file that climbs out of its method tree
+ its own code. A security refusal has no verdict either, whatever its class or its domain: a refusal
+ coded in a security family, such as a step's template file that climbs out of its method tree
(``security.method_path_refused``), keeps its code and logs its security event, never a verdict's.
- The item is ``pipe_validation`` when the library load located the
- refusal on the pipe it was building (``PipeLoadRefusalError``, with the pipe's code, domain and file),
- and ``blueprint_validation`` otherwise. It carries no ``error_type``: a refusal with a closed code
- has its own arm above, and naming one here would claim a diagnosis the refusal does not make.
+ The item is ``pipe_validation`` when the library load located the refusal on the pipe it was building
+ (``PipeLoadRefusalError``, with the pipe's code, domain and file), and ``blueprint_validation`` otherwise.
+ It carries no ``error_type``: a refusal with a closed code has its own arm above, and naming one here
+ would claim a diagnosis the refusal does not make.
The item's text is the sentence the refusal's code renders for a caller, never the refusal's own message:
the verdict is read by the caller, and the message is the operator's diagnostics.
"""
- if is_security_refusal(error=refusal) or not code_is_method_domain(code=refusal.resolve_error_code()):
+ if not _code_makes_a_verdict(code=refusal.resolve_error_code()):
return None
message = refusal_detail(refusal=refusal)
if isinstance(refusal, PipeLoadRefusalError):
diff --git a/pipelex/pipeline/validation_errors.py b/pipelex/pipeline/validation_errors.py
index 0c9ccf6a2..37ce96972 100644
--- a/pipelex/pipeline/validation_errors.py
+++ b/pipelex/pipeline/validation_errors.py
@@ -9,6 +9,9 @@ structured-error surface:
agent CLI prints, and
- the agent CLI's Markdown, which renders the items themselves as prose.
+A valid report's advisory ``warnings`` are the same items, and :func:`warning_problem_items` turns them into problem
+items for a surface that speaks problem items, such as the runner's ``/validate``.
+
All of them reach it through ``ValidateBundleError.validation_error_items``, so the CLI
and API structured shapes cannot drift. It takes the error-data lists directly
rather than a ``ValidateBundleError`` instance — that keeps the dependency one-directional
@@ -18,11 +21,12 @@ is no import cycle.
from typing import Any
-from mthds.protocol.problem.models import ProblemItem
+from mthds.protocol.problem.models import ProblemItem, ProblemLocation
from mthds.protocol.problem.registry import (
CoreCode,
MethodDependencyMissingKind,
MethodDependencyMissingReason,
+ MethodHintInvalidReason,
MethodIdentifierInvalidIdentifierKind,
)
from pydantic import BaseModel, ConfigDict
@@ -38,8 +42,15 @@ from pipelex.core.pipes.exceptions import pipe_validation_error_code
from pipelex.core.qualified_ref import QualifiedRef
from pipelex.errors.error_codes import ErrorCode, error_code_spec
from pipelex.errors.problem import make_location, make_problem_item
+from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
from pipelex.pipeline.fixes.planner import plan_fix_for_blueprint_validation_error, plan_fix_for_pipe_validation_error
-from pipelex.validation_error_types import PipeFactoryErrorType, PipeValidationErrorType, ValidationResidualErrorType
+from pipelex.validation_error_types import (
+ HintLintErrorType,
+ PipeFactoryErrorType,
+ PipeValidationErrorType,
+ TemplateCheckErrorType,
+ ValidationResidualErrorType,
+)
def build_validation_error_items(
@@ -209,10 +220,50 @@ def validation_item_code(*, item: ValidationErrorItem, residual_code: ErrorCode)
return CoreCode.METHOD_CONCEPT_UNRESOLVED
case PipeFactoryErrorType.UNKNOWN_FACTORY_ERROR:
return CoreCode.METHOD_SCHEMA_VIOLATION
- # The dry-run residual, whose items take their failure's own code, and the advisory types, which only ride warnings.
+ if isinstance(error_type, HintLintErrorType):
+ return CoreCode.METHOD_HINT_INVALID
+ if isinstance(error_type, TemplateCheckErrorType):
+ return PipelexErrorCode.DOCGEN_TEMPLATE_WARNING
+ # The dry-run residual, whose items take their failure's own code.
return residual_code
+def _hint_reason(*, error_type: HintLintErrorType) -> MethodHintInvalidReason:
+ """The `reason` of `method.hint_invalid` a hint lint finding of this type gives."""
+ match error_type:
+ case HintLintErrorType.HINT_UNKNOWN_KEY:
+ return MethodHintInvalidReason.UNKNOWN_KEY
+ case HintLintErrorType.HINT_UNKNOWN_INTENT:
+ return MethodHintInvalidReason.UNKNOWN_INTENT
+ case HintLintErrorType.HINT_INAPPLICABLE_INTENT:
+ return MethodHintInvalidReason.INAPPLICABLE_INTENT
+
+
+def _hint_facts(*, item: ValidationErrorItem) -> dict[str, Any]:
+ """The hint a hint lint item is about and why it is not understood, when the item is one."""
+ if not isinstance(item.error_type, HintLintErrorType):
+ return {}
+ return {"reason": _hint_reason(error_type=item.error_type), "hint": item.hint_key}
+
+
+def warning_problem_items(*, warnings: list[ValidationErrorItem]) -> list[ProblemItem]:
+ """A valid report's advisory warnings as problem items, each with its type's code.
+
+ A warning's type names its code (:func:`validation_item_code`): an advisory pipe lint its own, a hint lint
+ `method.hint_invalid`, a template check's finding `pipelex.docgen.template_warning`. A warning no type classifies
+ takes `method.schema_violation`, as an unclassified item of an invalid verdict does.
+
+ Args:
+ warnings: The report's warnings.
+
+ Returns:
+ One problem item per warning, in order.
+ """
+ return [
+ problem_item_of(item=warning, code=validation_item_code(item=warning, residual_code=CoreCode.METHOD_SCHEMA_VIOLATION)) for warning in warnings
+ ]
+
+
# The identifier an item of these types is about, and where the item holds it: an input name among its variable names, a pipe
# code as its pipe. A main_pipe the item does not name, or a pipe code only its message quotes, gives no identifier facts.
_IDENTIFIER_KINDS: dict[PipeValidationErrorType, MethodIdentifierInvalidIdentifierKind] = {
@@ -260,6 +311,8 @@ def _item_facts(*, item: ValidationErrorItem) -> dict[str, Any]:
facts: dict[str, Any] = {
**_identifier_facts(item=item),
**_dependency_facts(item=item),
+ **_hint_facts(item=item),
+ "template": item.template_file,
"pipe": item.pipe_code,
"concept": item.missing_concept_code or item.concept_code,
"variables": item.variable_names,
@@ -297,18 +350,41 @@ def problem_item_of(*, item: ValidationErrorItem, code: ErrorCode, params: dict[
spec = error_code_spec(code)
facts = {**_item_facts(item=item), **(params or {})}
item_params = {name: value for name, value in facts.items() if name in spec.param_names}
- line = item.line if item.line is not None and item.line >= 1 else None
- column = item.column if item.column is not None and item.column >= 1 else None
- location = make_location(pipe=item.pipe_code, field=item.field_name or item.field_path or None, file=item.source, line=line, column=column)
return make_problem_item(
code=code,
params=item_params,
- location=location,
+ location=_item_location(item=item),
suggestions=item.suggestions,
suggested_fix=_problem_fix(item=item),
)
+def _item_location(*, item: ValidationErrorItem) -> ProblemLocation | None:
+ """Where in the method a validation item is: the declaration a hint lint is on, else the pipe, field and file it names."""
+ if isinstance(item.error_type, HintLintErrorType):
+ return _hint_location(item=item)
+ line = item.line if item.line is not None and item.line >= 1 else None
+ column = item.column if item.column is not None and item.column >= 1 else None
+ return make_location(pipe=item.pipe_code, field=item.field_name or item.field_path or None, file=item.source, line=line, column=column)
+
+
+def _hint_location(*, item: ValidationErrorItem) -> ProblemLocation | None:
+ """The declaration a hint lint finding is on, which neither of `method.hint_invalid`'s parameters names.
+
+ A hint sits on one of three sites (`pipelex.pipeline.hint_warnings`): an input of a pipe, located at the pipe and the
+ input; a concept, located at its bundle-root path, `concept.<Concept>`; a field of a concept's structure, at the
+ field's, `concept.<Concept>.structure.<field>`. The domain is not part of the path, as no item's is: a bundle-root
+ path is read in the bundle that declares the concept.
+ """
+ if item.pipe_code is not None:
+ input_name = item.variable_names[0] if item.variable_names else None
+ return make_location(pipe=item.pipe_code, input_name=input_name)
+ if item.concept_code is not None:
+ concept_path = f"concept.{item.concept_code}"
+ return make_location(field=f"{concept_path}.structure.{item.field_name}" if item.field_name else concept_path)
+ return None
+
+
def _problem_fix(*, item: ValidationErrorItem) -> dict[str, Any] | None:
"""An item's suggested fix in the standard's wire form, where the file it edits is ``file``, not ``source``."""
if item.suggested_fix is None:
diff --git a/pipelex/pipeline/validation_render.py b/pipelex/pipeline/validation_render.py
index c59350c0b..d4dd0de8b 100644
--- a/pipelex/pipeline/validation_render.py
+++ b/pipelex/pipeline/validation_render.py
@@ -9,16 +9,10 @@ path, so the local-CLI and API-runner Markdown share one source of truth and
cannot drift.
``format_validate_markdown`` renders the **valid-arm** result;
-``render_invalid_validation_markdown`` renders the **invalid-arm** verdict (the
-structured ``validation_errors``). Both are shared pipelex code so the local CLI
-and the API-runner cannot drift in format/structure.
-
-``format_validation_error_items_markdown`` is the markdown sibling of the human
-``display_validation_error_items`` (``cli/error_handlers.py``): it renders typed
-:class:`ValidationErrorItem`s as category-grouped prose with per-item ``💡
-Suggested fix`` lines. It backs the API runner's ``rendered_markdown`` of an
-invalid verdict, so that prose mirrors the human panel and cannot drift; the agent
-CLI's failure surfaces list the problem's items instead, as their JSON does.
+``render_invalid_verdict_markdown`` renders the **invalid-arm** verdict from its
+problem items, the ``errors`` a host answers in the view of whoever asked, so
+the Markdown says no more than the structured items it presents.
+
``build_fix_command`` is the shared builder for the copy-pasteable
``<executable> fix bundle <path>`` footer, used by both the human and agent
``validate`` surfaces so the ``-L`` / ``--allow-signatures`` echo cannot drift.
@@ -28,14 +22,21 @@ from __future__ import annotations
import shlex
from pathlib import Path
-from typing import Any, cast
+from typing import TYPE_CHECKING, Any, cast
-from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
+from pipelex.errors.error_codes import error_code_spec, parse_error_code
from pipelex.interpreter_hub import resolve_library_dirs
from pipelex.pipeline.fixes.applicability import is_safe_fix_for_load_scope, is_target_in_write_scope
from pipelex.suggested_fix import FixSafety, SuggestedFix
from pipelex.tools.misc.string_utils import count_with_noun, pascal_case_to_sentence
+if TYPE_CHECKING:
+ from collections.abc import Sequence
+
+ from mthds.protocol.problem.models import ProblemItem
+
+ from pipelex.base_exceptions import ValidationErrorItem
+
def format_validate_markdown(result: dict[str, Any]) -> str:
"""Render a validation result dict as agent-readable markdown.
@@ -125,47 +126,63 @@ def format_validate_markdown(result: dict[str, Any]) -> str:
return "\n".join(lines)
-def render_invalid_validation_markdown(report: dict[str, Any]) -> str:
- """Render an invalid validation verdict (the InvalidReport arm) as agent-readable markdown.
+def render_invalid_verdict_markdown(*, items: Sequence[ProblemItem], message: str) -> str:
+ """Render an invalid validation verdict (the InvalidReport arm) as agent-readable markdown, from its problem items.
- Reconstructs the typed :class:`ValidationErrorItem`s from the report's serialized
- ``validation_errors`` and delegates to the shared
- :func:`format_validation_error_items_markdown` — the *same* prose renderer that mirrors the
- human panel. So the markdown an agent reads through the hosted ``/validate`` (the opt-in
- ``rendered_markdown``) is the human CLI's prose in structure: category-grouped items with humanized titles, identity
- fields, the message, and per-item ``💡 Suggested fix`` lines (which the old dict-based
- renderer dropped). A ``# Validation failed`` heading frames it.
+ The items are the verdict's ``errors`` in the view of whoever asked, the caller's leaving out what only the
+ operator reads, so the Markdown a host attaches beside them (the opt-in ``rendered_markdown`` of ``/validate``)
+ says what they say and no more: each item numbered under its code's title, with its code, where it is, its
+ sentence, its suggestions and its suggested fix, labelled with its safety. A ``# Validation failed`` heading frames
+ it. It never reads a validation item's own message, which the operator's tools render and which a caller's view
+ does not carry.
- ``rendered_markdown`` is presentation, never the contract — the machine consumer branches on
- the JSON ``is_valid`` / ``validation_errors`` fields (see workspace ``CLAUDE.md`` § "Surface
- output conventions"). No CLI-command footer is emitted here: an API consumer applies fixes via
- the structured ``suggested_fix`` ops, not a ``pipelex-agent fix`` invocation.
+ ``rendered_markdown`` is presentation, never the contract: the machine consumer branches on the JSON ``is_valid``
+ and ``errors`` fields (see workspace ``CLAUDE.md`` § "Surface output conventions"). No CLI-command footer is emitted
+ here: an API consumer applies fixes through the structured ``suggested_fix`` operations.
Args:
- report: The InvalidReport-shaped dict (``is_valid: False``,
- ``validation_errors: [...]``, ``message``).
+ items: The verdict's problem items, in the view of the reader the Markdown is for.
+ message: The verdict's sentence, shown when it holds no item.
Returns:
A markdown string.
"""
- raw_items: list[dict[str, Any]] = report.get("validation_errors") or []
- items = [ValidationErrorItem.model_validate(raw_item) for raw_item in raw_items]
-
lines: list[str] = ["# Validation failed", ""]
- body = format_validation_error_items_markdown(items)
- if body:
- lines.append(body)
- else:
- # Defensive: the structured-info invariant guarantees a non-empty validation_errors[] on
- # every produced invalid verdict, so this branch should be unreachable — but a report that
- # somehow carries no items still shows its summary message rather than a bare heading.
- message = report.get("message")
- if message:
- lines.append(str(message))
-
+ if not items:
+ # Defensive: the structured-info invariant guarantees a non-empty `errors` on every produced invalid verdict,
+ # so this branch should be unreachable, but a verdict that somehow carries no item still shows its sentence.
+ lines.append(message)
+ for item_index, item in enumerate(items, 1):
+ lines += _render_problem_item_markdown(item=item, index=item_index)
+ lines.append("")
return "\n".join(lines).rstrip()
+def _render_problem_item_markdown(*, item: ProblemItem, index: int) -> list[str]:
+ """Render one problem item as prose: its code's title and its code, where it is, its sentence, suggestions and fix."""
+ code = parse_error_code(item.code)
+ title = error_code_spec(code).title if code is not None else item.code
+ lines: list[str] = [f"{index}. **{title}** (`{item.code}`)"]
+ location = item.location
+ if location is not None:
+ if location.pipe:
+ lines.append(f" - Pipe: `{location.pipe}`")
+ if location.input:
+ lines.append(f" - Input: `{location.input}`")
+ if location.field:
+ lines.append(f" - Field: `{location.field}`")
+ if location.file:
+ position = f"{location.file}:{location.line}" if location.line is not None else location.file
+ lines.append(f" - File: `{position}`")
+ lines.append(f" - {item.detail}")
+ for suggestion in item.suggestions or []:
+ lines.append(f" - {suggestion}")
+ if item.suggested_fix is not None:
+ safety = FixSafety(str(item.suggested_fix.effective_safety))
+ lines.append(f" - 💡 {fix_safety_label(safety=safety)}: {item.suggested_fix.description}")
+ return lines
+
+
def validation_item_title(*, item: ValidationErrorItem) -> str:
"""The heading of one validation item: its ``error_type`` in words, or ``Validation Error`` without one.
@@ -181,19 +198,6 @@ def validation_item_title(*, item: ValidationErrorItem) -> str:
return pascal_case_to_sentence(error_type).title()
-def _markdown_category_header(category: ValidationErrorCategory) -> str:
- """The section heading for one validation-error category — markdown sibling of the human header."""
- match category:
- case ValidationErrorCategory.BLUEPRINT_VALIDATION:
- return "Blueprint validation errors"
- case ValidationErrorCategory.PIPE_FACTORY:
- return "Pipe factory errors"
- case ValidationErrorCategory.PIPE_VALIDATION:
- return "Pipe validation errors"
- case ValidationErrorCategory.DRY_RUN:
- return "Dry run errors"
-
-
def suggested_fix_label(*, fix: SuggestedFix) -> str:
"""The label a rendered suggested fix opens with, saying whether it may be applied without asking.
@@ -204,87 +208,18 @@ def suggested_fix_label(*, fix: SuggestedFix) -> str:
show. Shared by the human panel (``cli/error_handlers.py``) and the markdown prose here, so every
surface labels a fix the same way.
"""
- match fix.safety:
+ return fix_safety_label(safety=fix.safety)
+
+
+def fix_safety_label(*, safety: FixSafety) -> str:
+ """The label a rendered suggested fix of this safety opens with (:func:`suggested_fix_label`)."""
+ match safety:
case FixSafety.SAFE:
return "Suggested fix"
case FixSafety.UNSAFE:
return "Suggested fix (unsafe, confirm before applying)"
-def _render_error_item_markdown(item: ValidationErrorItem, *, index: int) -> list[str]:
- """Render one structured item as prose: humanized title, identity fields, message, fix, locators.
-
- Markdown sibling of the human ``_display_validation_error_item`` — same fields in the same
- order, emitting ``**bold**`` / backticks instead of Rich markup.
- """
- lines: list[str] = [f"{index}. **{validation_item_title(item=item)}**"]
- if item.pipe_code:
- lines.append(f" - Pipe: `{item.pipe_code}`")
- if item.concept_code:
- lines.append(f" - Concept: `{item.concept_code}`")
- if item.domain_code:
- lines.append(f" - Domain: `{item.domain_code}`")
- if item.field_name:
- lines.append(f" - Field: `{item.field_name}`")
- if item.missing_concept_code:
- lines.append(f" - Missing concept: `{item.missing_concept_code}`")
- if item.missing_pipe_code:
- lines.append(f" - Missing pipe: `{item.missing_pipe_code}`")
- if item.declared_concepts:
- declared = ", ".join(f"`{concept_code}`" for concept_code in item.declared_concepts)
- lines.append(f" - Declared concepts: {declared}")
- if item.variable_names:
- variables = ", ".join(f"`{variable_name}`" for variable_name in item.variable_names)
- lines.append(f" - Variables: {variables}")
- lines.append(f" - {item.message}")
- if item.suggested_fix is not None:
- lines.append(f" - 💡 {suggested_fix_label(fix=item.suggested_fix)}: {item.suggested_fix.description}")
- if item.field_path:
- lines.append(f" - Path: `{item.field_path}`")
- if item.source:
- lines.append(f" - Source: `{item.source}`")
- return lines
-
-
-def format_validation_error_items_markdown(items: list[ValidationErrorItem]) -> str:
- """Render structured validation-error items grouped by category as agent-readable markdown.
-
- The markdown sibling of the human ``display_validation_error_items``
- (``cli/error_handlers.py``): same category grouping, same per-item identity fields + message
- + ``💡 Suggested fix`` line, emitting markdown instead of Rich markup. Consumes the typed
- items produced by the shared ``build_validation_error_items`` builder — the same source the
- human panel and the structured wire draw from — so the prose an agent reads cannot drift from
- what a human sees. Returns only the grouped items block (no heading, no footer); callers wrap
- it with the surface-specific framing.
-
- Args:
- items: The structured validation-error items to render, in builder order.
-
- Returns:
- A markdown string: one ``## <Category>`` section per populated category, each holding
- numbered prose items (one per failing pipe in the ``dry_run`` section).
- """
- items_by_category: dict[ValidationErrorCategory, list[ValidationErrorItem]] = {}
- for item in items:
- items_by_category.setdefault(item.category, []).append(item)
-
- lines: list[str] = []
- for category in ValidationErrorCategory:
- category_items = items_by_category.get(category, [])
- if not category_items:
- continue
- if lines:
- lines.append("")
- lines += [f"## {_markdown_category_header(category)}", ""]
- # Every category, dry run included, renders numbered items: a dry-run item is located on its
- # failing pipe like any other, so it names the pipe, the domain and the source.
- for error_index, item in enumerate(category_items, 1):
- lines += _render_error_item_markdown(item, index=error_index)
- lines.append("")
-
- return "\n".join(lines).rstrip()
-
-
def build_fix_command(*, executable: str, bundle_path: Path, library_dirs: list[Path] | None = None, allow_signatures: bool = False) -> str:
"""Build the copy-pasteable ``<executable> fix bundle <path>`` command for a fix-aware footer.
diff --git a/pipelex/system/job_metadata.py b/pipelex/system/job_metadata.py
index be6bb6dd7..ed941855e 100644
--- a/pipelex/system/job_metadata.py
+++ b/pipelex/system/job_metadata.py
@@ -13,28 +13,41 @@ from pipelex.system.telemetry.otel_context import OtelContext
from pipelex.system.trace_context import TraceContext
from pipelex.tools.log.log_context import LogContext, bind_log_context
+# The one rule of an inbound request id, which the API server's middleware applies to an `X-Request-ID` header and a run
+# applies to the id its host passes: a request id is echoed in a response header and written into log lines, plain and
+# key=value alike, so it holds letters, digits, `_` and `-` alone, the characters of a ULID or a UUID. A space, a quote, an
+# `=` or a `;` could forge a field in a key=value line or a parameter of a header, and a control character a whole line.
REQUEST_ID_MAX_LENGTH = 128
-REQUEST_ID_PATTERN = re.compile(r"[\x20-\x7E]+")
+REQUEST_ID_PATTERN = re.compile(r"[A-Za-z0-9_-]+")
+
+
+def is_valid_request_id(*, value: str) -> bool:
+ """Whether `value` is a usable inbound request id: at most `REQUEST_ID_MAX_LENGTH` of the characters the rule allows.
+
+ The rule is matched whole (`fullmatch`, which a final newline cannot slip past as it can a `$` anchor).
+ """
+ return len(value) <= REQUEST_ID_MAX_LENGTH and REQUEST_ID_PATTERN.fullmatch(value) is not None
def validate_request_id(*, value: str) -> str:
"""Return `value` if it is a usable inbound request id, else raise `RunParameterError`.
- The one statement of the constraint, which `RunMetadata` applies at construction and a
- host entry point applies before it builds a run, so both refuse exactly the same values.
+ The one statement of the constraint (`is_valid_request_id`), which `RunMetadata` applies at construction, a host
+ entry point applies before it builds a run, and the API server's middleware applies to an inbound header, so all of
+ them refuse exactly the same values.
Raises:
- RunParameterError: the value is empty, longer than `REQUEST_ID_MAX_LENGTH`, or holds a
- character outside printable ASCII.
+ RunParameterError: the value is empty, longer than `REQUEST_ID_MAX_LENGTH`, or holds a character other than an
+ ASCII letter or digit, `_` or `-`.
"""
if len(value) > REQUEST_ID_MAX_LENGTH:
msg = f"Invalid request_id: it has {len(value)} characters, and at most {REQUEST_ID_MAX_LENGTH} are allowed."
raise RunParameterError(msg)
- # `fullmatch`, not `match` with a trailing `$`, which would admit one final newline.
- if not REQUEST_ID_PATTERN.fullmatch(value):
+ if not is_valid_request_id(value=value):
+ # The value is not quoted: it is the text the rule refuses to write into a log line.
msg = (
- f"Invalid request_id {value!r}: expected one or more printable ASCII characters. "
- "The value is quoted into log lines and error reports, so a control character in it would forge one."
+ "Invalid request_id: expected one or more ASCII letters, digits, '_' or '-'. "
+ "The value is echoed in headers and written into log lines, where any other character could forge a field."
)
raise RunParameterError(msg)
return value
@@ -168,10 +181,10 @@ class RunMetadata(BaseModel):
# from :class:`pipelex.cogt.inference.error_classification.ProviderErrorMetadata.request_id`,
# which is the *provider*-side request id (OpenAI ``x-request-id`` etc.) —
# both can appear together when the API surfaces a provider failure.
- # Constrained at the wire-format boundary by `validate_request_id` (printable
- # ASCII only, max 128 chars) so an unsanitized upstream value cannot inject
- # newlines or control characters into the log lines or the problem
- # documents that quote it.
+ # Constrained at the wire-format boundary by `validate_request_id` (ASCII
+ # letters, digits, `_` and `-`, max 128 chars) so an unsanitized upstream
+ # value cannot inject a line, a field or a header parameter into the log
+ # lines, the headers or the problem documents that carry it.
request_id: str | None = None
# The opaque labels the host attaches to this run. Never read by name;
diff --git a/pipelex/tools/jinja2/exceptions.py b/pipelex/tools/jinja2/exceptions.py
index 9aee49ac1..8a7ed0653 100644
--- a/pipelex/tools/jinja2/exceptions.py
+++ b/pipelex/tools/jinja2/exceptions.py
@@ -63,8 +63,8 @@ class Jinja2TemplateSecurityError(SecurityError):
A `SecurityError`, not a `ToolError`, in the family of `UriReadRefusedError`, `SsrfBlockedError` and
`UnsafeSchemaError`, so that a host catching that family never absorbs it into a domain answer and never retries
- it. A type of its own, apart from `Jinja2TemplateRenderError`, so that the classification of render-time template
- failures tells a refusal from the rest.
+ it. A type of its own, apart from `Jinja2TemplateRenderError`, so that a refusal reads apart from a template that
+ fails for any other reason.
"""
error_code = ErrorCodeSet(default=CoreCode.SECURITY_TEMPLATE_REFUSED, others=(CoreCode.RUNTIME_UNEXPECTED,))
diff --git a/pipelex/tools/log/gcp_log_sink.py b/pipelex/tools/log/gcp_log_sink.py
index 783807a28..7ce5ca1e0 100644
--- a/pipelex/tools/log/gcp_log_sink.py
+++ b/pipelex/tools/log/gcp_log_sink.py
@@ -45,6 +45,7 @@ from typing import TYPE_CHECKING, Any, NamedTuple, Protocol, cast
from opentelemetry import trace
from typing_extensions import override
+from pipelex.base_exceptions import iter_traceback_chain
from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
from pipelex.system.exceptions import MissingDependencyError
from pipelex.system.telemetry.current_span import current_span_context_for_logs, pipelex_trace_fields_for_logs
@@ -464,22 +465,13 @@ class GcpCredentialsCheck:
def _classify(self, *, failure: Exception) -> GcpCredentialsOutcome:
"""``UNREACHABLE`` when a transport failure is anywhere on the chain the traceback would print, ``REFUSED`` otherwise."""
- seen: set[int] = set()
- current: BaseException | None = failure
- while current is not None and id(current) not in seen:
+ for current in iter_traceback_chain(failure):
if isinstance(current, self._transport_error_types):
if _carries_a_final_answer(failure=current):
return GcpCredentialsOutcome.REFUSED
return GcpCredentialsOutcome.UNREACHABLE
if getattr(current, "retryable", False) is True:
return GcpCredentialsOutcome.UNREACHABLE
- seen.add(id(current))
- if current.__cause__ is not None:
- current = current.__cause__
- elif current.__suppress_context__:
- current = None
- else:
- current = current.__context__
return GcpCredentialsOutcome.REFUSED
diff --git a/pipelex/tools/uri/exceptions.py b/pipelex/tools/uri/exceptions.py
index 816874cbd..e0590bb99 100644
--- a/pipelex/tools/uri/exceptions.py
+++ b/pipelex/tools/uri/exceptions.py
@@ -24,7 +24,7 @@ class UriReadRefusalReason(StrEnum):
return "it names a file on the server's own disk, or a URL in a scheme this runtime does not read, and a hosted run reads neither"
@property
- def security_target_class(self) -> SecurityTargetClass:
+ def target_class(self) -> SecurityTargetClass:
"""The class of destination the refusal names in its security event: another tenant's key, or a scheme the run does not read."""
match self:
case UriReadRefusalReason.FOREIGN_STORAGE_KEY:
@@ -32,15 +32,6 @@ class UriReadRefusalReason(StrEnum):
case UriReadRefusalReason.LOCAL_PATH:
return SecurityTargetClass.SCHEME
- @property
- def target_class(self) -> str:
- """The kind of target the refused URL points at, as the refusal's sentence names it."""
- match self:
- case UriReadRefusalReason.FOREIGN_STORAGE_KEY:
- return "foreign storage"
- case UriReadRefusalReason.LOCAL_PATH:
- return "local"
-
class UriReadRefusedError(SecurityError):
"""Raised when a run asks to read a URL outside what its host lets it read.
@@ -66,8 +57,11 @@ class UriReadRefusedError(SecurityError):
super().__init__(message)
self.reason = reason
# The reason is the class of destination refused, so the security event names it without the raise site saying so.
- self.with_security_target_class(reason.security_target_class)
+ self.with_security_target_class(reason.target_class)
@override
def problem_params(self) -> dict[str, Any]:
- return {"reason": self.reason.desc, "target_class": self.reason.target_class}
+ # The problem's `target_class` is a value the registry lists, which the code's sentence reads as a word ("points
+ # at a private target"): `scheme` for a local path, and `private` for another tenant's key, which the registry
+ # lists no value for. The security event names the finer class the refusal states, `foreign_storage_key`.
+ return {"reason": self.reason.desc, "target_class": self.reason.target_class.listed_target_class}
diff --git a/subject_grants.toml b/subject_grants.toml
index 816e0784b..72a872630 100644
--- a/subject_grants.toml
+++ b/subject_grants.toml
@@ -24,6 +24,10 @@ rationale = "Verb-object: iterates the exception's cause chain; single operand."
param = "exc"
rationale = "Verb-object: iterates the Pipelex part of the exception's cause chain; single operand, as iter_cause_chain."
+["pipelex/base_exceptions.py::iter_traceback_chain"]
+param = "exc"
+rationale = "Verb-object: iterates the chain a traceback of the exception prints; single operand, as iter_cause_chain."
+
["pipelex/cli/agent_cli/commands/agent_output.py::agent_argument_error"]
param = "message"
rationale = "Refuses an argument with the command's message; single operand, as agent_error."
@@ -4608,14 +4612,6 @@ rationale = "Verb-object: validates bundles from the directory; options stay key
param = "pipe_error"
rationale = "Verb-object: backfills the pipe error in place; single operand."
-["pipelex/pipeline/validation_render.py::_markdown_category_header"]
-param = "category"
-rationale = "Noun-named derivation: the header text for the category; single operand."
-
-["pipelex/pipeline/validation_render.py::_render_error_item_markdown"]
-param = "item"
-rationale = "Verb-object: renders the error item; index is context."
-
["pipelex/pipeline/validation_render.py::count_applicable_fixes"]
param = "items"
rationale = "Single-operand count over the error items; scope stays keyword."
@@ -4624,14 +4620,6 @@ rationale = "Single-operand count over the error items; scope stays keyword."
param = "result"
rationale = "Verb-object: formats the validate result; single operand."
-["pipelex/pipeline/validation_render.py::format_validation_error_items_markdown"]
-param = "items"
-rationale = "Verb-object: formats the error items; single operand."
-
-["pipelex/pipeline/validation_render.py::render_invalid_validation_markdown"]
-param = "report"
-rationale = "Verb-object: renders the validation report; single operand."
-
["pipelex/plugins/backend_extras_factory.py::BackendExtrasFactory.make_extras"]
param = "inference_model"
rationale = "Factory from source: builds the result from the inference_model; single operand."
diff --git a/tests/data/errors/foreign_raises.txt b/tests/data/errors/foreign_raises.txt
index 97841d271..67bbb37ae 100644
--- a/tests/data/errors/foreign_raises.txt
+++ b/tests/data/errors/foreign_raises.txt
@@ -8,14 +8,12 @@
# - validator: a builtin raised in a helper only pydantic validators call, which pydantic wraps;
# - private: a private class caught in the module that defines it, which no reader sees;
# - carrier: a class a library or protocol expects by type (the import system's ImportError, httpx's transport
-# errors, the standard's method tree refusal its callers translate, the runner's own ApiError) that the scan
-# cannot recognise by its name alone;
+# errors, the standard's method tree refusal its callers translate) that the scan cannot recognise by its name alone;
# - tooling: developer or release code outside the exempt directories, which only the development CLI calls;
# - caught: a builtin raised in a module that must import nothing of Pipelex, which its every caller catches by type.
#
# A new raise belongs here only when it is one of these; otherwise raise a coded PipelexError subclass.
-api/pipelex_api/errors.py | _raise_api_error | ApiError | carrier
-api/pipelex_api/openapi_schema.py | name_shared_fix_schemas | ValueError | invariant
+api/pipelex_api/openapi_schema.py | _apply_schema_renames | ValueError | invariant
api/pipelex_api/schemas/models.py | _ensure_mthds_file_within_bytes_limit | ValueError | validator
pipelex/base_exceptions.py | PipelexError.__init_subclass__ | TypeError | invariant
pipelex/base_exceptions.py | PipelexError.with_error_code | ValueError | invariant
diff --git a/tests/integration/pipelex/pipeline/test_security_refusal_event.py b/tests/integration/pipelex/pipeline/test_security_refusal_event.py
index 6ddfb7a43..c22397b3a 100644
--- a/tests/integration/pipelex/pipeline/test_security_refusal_event.py
+++ b/tests/integration/pipelex/pipeline/test_security_refusal_event.py
@@ -11,10 +11,11 @@ from mthds.protocol.problem.registry import CoreCode, ProblemDomain
from pipelex.base_exceptions import PipelexError
from pipelex.errors.error_codes import error_code_spec
-from pipelex.errors.security_event import SECURITY_EVENT_MESSAGE, SECURITY_EVENT_NAME
+from pipelex.errors.security_event import SECURITY_EVENT_MESSAGE, SECURITY_EVENT_NAME, emit_security_event
from pipelex.errors.security_target import SecurityTargetClass, SecurityTargetKind
-from pipelex.pipeline.exceptions import PipelineExecutionError
+from pipelex.pipeline.exceptions import PipelineExecutionError, ValidateBundleError
from pipelex.pipeline.runner import PipelexMTHDSProtocol
+from pipelex.pipeline.validate_bundle import validate_bundle
from pipelex.system.pipe_run_mode import PipeRunMode
from pipelex.system.storage_scope import LOCAL_STORAGE_SCOPE
from pipelex.tools.log.json_log_sink import JsonLogSink
@@ -143,6 +144,19 @@ class TestSecurityRefusalEvent:
assert "_owner" not in serialized
assert SecurityRefusalTestData.TOPIC not in serialized
+ async def test_a_template_the_sandbox_refuses_in_a_validation_sweep_is_no_verdict(self) -> None:
+ """The sweep's dry run meets the refusal: it keeps its security code and its one event, never a verdict's item."""
+ with _security_event_lines() as lines, pytest.raises(PipelexError) as exc_info:
+ await validate_bundle(mthds_contents=[_compose_bundle(template=SecurityRefusalTestData.PRIVATE_READ_TEMPLATE)])
+
+ error = exc_info.value
+ assert not isinstance(error, ValidateBundleError)
+ assert error.resolve_error_code() == CoreCode.SECURITY_TEMPLATE_REFUSED
+ (line,) = lines
+ assert line["error.code"] == CoreCode.SECURITY_TEMPLATE_REFUSED
+ # The sweep's own failure carries the refusal the dry run reported already, so no boundary reports it again.
+ assert not emit_security_event(error=error)
+
async def test_a_failure_no_security_rule_made_logs_no_event(self) -> None:
runner = PipelexMTHDSProtocol(pipe_run_mode=PipeRunMode.DRY, storage_scope=LOCAL_STORAGE_SCOPE, extras=SecurityRefusalTestData.EXTRAS)
error, lines = await _refused_run(
diff --git a/tests/unit/pipelex/core/bundle_resources/test_bundle_resource.py b/tests/unit/pipelex/core/bundle_resources/test_bundle_resource.py
index cd7989dc7..e31823f8c 100644
--- a/tests/unit/pipelex/core/bundle_resources/test_bundle_resource.py
+++ b/tests/unit/pipelex/core/bundle_resources/test_bundle_resource.py
@@ -5,9 +5,16 @@ from pipelex.core.bundle_resources.bundle_resource import (
canonical_resource_path,
canonical_resource_path_or_none,
canonical_submitted_files,
+ path_refusal_error,
+ root_escape_of,
)
from pipelex.core.bundle_resources.exceptions import BundleResourcePathError
+# The parameters of each refusal: the security rule a path leaving the bundle breaks, or the request's field.
+_ABSOLUTE = {"rule": "absolute"}
+_PARENT_SEGMENT = {"rule": "parent_segment"}
+_RESOURCES_FIELD = {"field": "resources"}
+
class TestCanonicalResourcePath:
@pytest.mark.parametrize(
@@ -26,30 +33,45 @@ class TestCanonicalResourcePath:
assert canonical_resource_path_or_none(path=path) == expected
@pytest.mark.parametrize(
- ("path", "reason", "code"),
+ ("path", "reason", "code", "params"),
[
- ("", "empty", CoreCode.REQUEST_INVALID),
- (" ", "empty", CoreCode.REQUEST_INVALID),
- (".", "names no file", CoreCode.REQUEST_INVALID),
- ("/etc/invoice.docx", "absolute", CoreCode.SECURITY_INPUT_PATH_REFUSED),
- ("\\etc\\invoice.docx", "absolute", CoreCode.SECURITY_INPUT_PATH_REFUSED),
- ("../invoice.docx", "'..' segment", CoreCode.SECURITY_INPUT_PATH_REFUSED),
- ("templates/../../invoice.docx", "'..' segment", CoreCode.SECURITY_INPUT_PATH_REFUSED),
- ("..\\secrets\\key.pem", "'..' segment", CoreCode.SECURITY_INPUT_PATH_REFUSED),
- ("C:/Windows/invoice.docx", "drive", CoreCode.SECURITY_INPUT_PATH_REFUSED),
- ("C:invoice.docx", "drive", CoreCode.SECURITY_INPUT_PATH_REFUSED),
- ("\\\\server\\share\\invoice.docx", "network share", CoreCode.SECURITY_INPUT_PATH_REFUSED),
- ("templates\\invoice.docx", "backslash", CoreCode.REQUEST_INVALID),
- ("invoice:v2.docx", "colon", CoreCode.REQUEST_INVALID),
- ("invoice\x00.docx", "NUL", CoreCode.REQUEST_INVALID),
+ ("", "empty", CoreCode.REQUEST_INVALID, _RESOURCES_FIELD),
+ (" ", "empty", CoreCode.REQUEST_INVALID, _RESOURCES_FIELD),
+ (".", "names no file", CoreCode.REQUEST_INVALID, _RESOURCES_FIELD),
+ ("/etc/invoice.docx", "absolute", CoreCode.SECURITY_INPUT_PATH_REFUSED, _ABSOLUTE),
+ ("\\etc\\invoice.docx", "absolute", CoreCode.SECURITY_INPUT_PATH_REFUSED, _ABSOLUTE),
+ ("../invoice.docx", "'..' segment", CoreCode.SECURITY_INPUT_PATH_REFUSED, _PARENT_SEGMENT),
+ ("templates/../../invoice.docx", "'..' segment", CoreCode.SECURITY_INPUT_PATH_REFUSED, _PARENT_SEGMENT),
+ ("..\\secrets\\key.pem", "'..' segment", CoreCode.SECURITY_INPUT_PATH_REFUSED, _PARENT_SEGMENT),
+ ("C:/Windows/invoice.docx", "drive", CoreCode.SECURITY_INPUT_PATH_REFUSED, _ABSOLUTE),
+ ("C:invoice.docx", "drive", CoreCode.SECURITY_INPUT_PATH_REFUSED, _ABSOLUTE),
+ ("\\\\server\\share\\invoice.docx", "network share", CoreCode.SECURITY_INPUT_PATH_REFUSED, _ABSOLUTE),
+ ("templates\\invoice.docx", "backslash", CoreCode.REQUEST_INVALID, _RESOURCES_FIELD),
+ ("invoice:v2.docx", "colon", CoreCode.REQUEST_INVALID, _RESOURCES_FIELD),
+ ("invoice\x00.docx", "NUL", CoreCode.REQUEST_INVALID, _RESOURCES_FIELD),
],
)
- def test_a_path_that_cannot_name_a_file_inside_the_bundle_is_refused(self, path: str, reason: str, code: CoreCode) -> None:
- """The message says why, the lenient form answers None, and only a path leaving the bundle is a security refusal."""
+ def test_a_path_that_cannot_name_a_file_inside_the_bundle_is_refused(
+ self, path: str, reason: str, code: CoreCode, params: dict[str, str]
+ ) -> None:
+ """The message says why, the lenient form answers None, and only a path leaving the bundle is a security refusal.
+
+ A security refusal names the rule the path broke, never the path; any other refusal names the request's field.
+ """
with pytest.raises(BundleResourcePathError) as exc_info:
canonical_resource_path(path=path)
assert reason in exc_info.value.message
assert exc_info.value.resolve_error_code() == code
+ assert exc_info.value.given_params == params
+ escape = root_escape_of(path=path)
+ # The refusal a caller of the rule builds from the same escape is the one this raised.
+ built = path_refusal_error(message="refused", escape=escape)
+ assert built.resolve_error_code() == code
+ assert built.given_params == params
+ assert (escape.rule if escape is not None else None) == params.get("rule")
+ if escape is not None:
+ # The one classifier gives both the message's reason and the security rule.
+ assert escape.desc in exc_info.value.message
assert canonical_resource_path_or_none(path=path) is None
@@ -60,5 +82,7 @@ class TestCanonicalSubmittedFiles:
assert files == {"invoice.docx": b"docx", "templates/report.html": b"<h1></h1>"}
def test_two_spellings_of_one_file_are_refused(self) -> None:
- with pytest.raises(BundleResourcePathError, match="name the same file"):
+ with pytest.raises(BundleResourcePathError, match="name the same file") as exc_info:
canonical_submitted_files(files={"invoice.docx": b"a", "./invoice.docx": b"b"})
+ assert exc_info.value.resolve_error_code() == CoreCode.REQUEST_INVALID
+ assert exc_info.value.given_params == _RESOURCES_FIELD
diff --git a/tests/unit/pipelex/errors/test_security_event.py b/tests/unit/pipelex/errors/test_security_event.py
index 2553f94f9..29bc315a1 100644
--- a/tests/unit/pipelex/errors/test_security_event.py
+++ b/tests/unit/pipelex/errors/test_security_event.py
@@ -272,11 +272,10 @@ class TestSecurityEvent:
target_class: SecurityTargetClass | None,
) -> None:
"""The failure reports the security code with the domain of whoever caused it, and its event names the same, with the run and the org."""
- problem = error.to_problem(view=ProblemView.CALLER)
+ problem = error.to_problem(view=ProblemView.OPERATOR)
assert problem.code == code
# The registry domain of the code, who caused the refusal, which the problem document carries.
assert error_code_spec(code).domain == domain
- assert problem.domain == domain
with _security_event_lines() as lines:
assert emit_security_event(error=error, pipeline_run_id="run_1", request_id="req_1", extras={"org_id": "org_abc", "plan": "pro"})
diff --git a/tests/unit/pipelex/pipeline/test_bundle_validator.py b/tests/unit/pipelex/pipeline/test_bundle_validator.py
index 5a86abf75..b8658c506 100644
--- a/tests/unit/pipelex/pipeline/test_bundle_validator.py
+++ b/tests/unit/pipelex/pipeline/test_bundle_validator.py
@@ -7,15 +7,19 @@ single collect-all aggregate (no per-pipe early abort), and the per-sweep teleme
is exercised by the integration suite.
"""
+import logging
from typing import Any
import pytest
+from mthds.protocol.problem.registry import CoreCode
from polyfactory.exceptions import FactoryException
from pydantic import BaseModel, ValidationError
from pytest_mock import MockerFixture
from pipelex.base_exceptions import PipelexError
from pipelex.core.pipes.exceptions import PipeRunError
+from pipelex.errors.security_event import SECURITY_EVENT_MESSAGE, emit_security_event
+from pipelex.errors.security_target import SecurityTargetClass
from pipelex.libraries.pipe.exceptions import PipeNotFoundError
from pipelex.pipe_run.exceptions import DryRunError, PipeRouterError
from pipelex.pipe_run.located_failure import make_unexpected_failure
@@ -24,6 +28,7 @@ from pipelex.system.caller_identity import CallerIdentity, get_current_caller_id
from pipelex.system.pipe_run_mode import PipeRunMode
from pipelex.system.storage_scope import DRY_RUN_STORAGE_SCOPE, DRY_RUN_USER_ID
from pipelex.system.telemetry.events import EventName, EventProperty
+from pipelex.tools.network.exceptions import SsrfBlockedError
_CALLER = CallerIdentity(user_id="caller-7", extras={"organization": "org_caller"})
@@ -324,3 +329,37 @@ class TestBundleValidator:
prepare_kwargs = prepare_mock.call_args.kwargs
assert prepare_kwargs["user_id"] == DRY_RUN_USER_ID
assert prepare_kwargs["extras"] is None
+
+ @pytest.mark.asyncio
+ @pytest.mark.parametrize("is_met_before_the_run", [True, False], ids=["mock_input_build", "pipe_run"])
+ async def test_a_refusal_the_sweep_meets_is_logged_once(
+ self, mocker: MockerFixture, caplog: pytest.LogCaptureFixture, is_met_before_the_run: bool
+ ) -> None:
+ """Every security refusal the sweep meets logs one event, whether a pipe run met it or the job's preparation did.
+
+ The sweep's error is marked as logged, so the boundary it reaches logs nothing more, which is only right when
+ each refusal it reports was logged where it was met: one met while the mock inputs are built reaches no pipe run.
+ """
+ validator, _telemetry, prepare_mock, pipe_run = self._patch_env(mocker)
+ refusal = SsrfBlockedError("Refusing to connect to 'files.internal.example'.").with_security_target_class(SecurityTargetClass.PRIVATE)
+ if is_met_before_the_run:
+ prepare_mock.side_effect = refusal
+ else:
+ # The pipe run logs the refusal it meets before raising it, as `PipeRun.run` does.
+ def _refusing_run(_pipe_job: Any) -> None:
+ emit_security_event(error=refusal)
+ raise refusal
+
+ pipe_run.run = mocker.AsyncMock(side_effect=_refusing_run)
+ pipe = self._make_pipe(mocker, code="reader", pipe_ref="dom.reader")
+
+ with caplog.at_level(logging.WARNING, logger="pipelex.errors.security_event"), pytest.raises(DryRunError) as exc_info:
+ await validator.validate_pipes([pipe], library_id="lib-1", caller_identity=_CALLER)
+
+ events = [vars(record) for record in caplog.records if record.getMessage() == SECURITY_EVENT_MESSAGE]
+ assert len(events) == 1
+ assert events[0]["error.type"] == "SsrfBlockedError"
+ assert events[0]["security.target_class"] == SecurityTargetClass.PRIVATE
+ assert exc_info.value.security_failure_codes == [CoreCode.SECURITY_INPUT_URL_REFUSED]
+ # The boundary the sweep's error reaches logs no second event.
+ assert not emit_security_event(error=exc_info.value)
diff --git a/tests/unit/pipelex/pipeline/test_hint_warnings.py b/tests/unit/pipelex/pipeline/test_hint_warnings.py
index 8091e8a3e..48ba7c01d 100644
--- a/tests/unit/pipelex/pipeline/test_hint_warnings.py
+++ b/tests/unit/pipelex/pipeline/test_hint_warnings.py
@@ -12,6 +12,7 @@ from pipelex.mthds_parsing.pipelex_bundle_blueprint import PipeBlueprintUnion
from pipelex.pipe_machinery.pipe_blueprint import InputSlotBlueprint
from pipelex.pipe_operators.llm.pipe_llm_blueprint import PipeLLMBlueprint
from pipelex.pipeline.hint_warnings import MAX_AUTHORED_TOKEN_LENGTH, MAX_HINT_FINDINGS_PER_SITE, build_hint_warnings
+from pipelex.pipeline.validation_errors import warning_problem_items
from pipelex.validation_error_types import HintLintErrorType
@@ -38,12 +39,16 @@ class TestHintLintFindings:
assert warning.concept_code == "Essay"
assert warning.domain_code == "docs"
assert "emphasis" in warning.message
+ # The key the finding is about, which its problem item names as `method.hint_invalid`'s `hint`.
+ assert warning.hint_key == "emphasis"
def test_unknown_intent_word_warns(self):
warnings = _lint(_crate({"docs.Essay": ConceptBlueprint(description="an essay", hints={"intent": "poetry"})}))
assert len(warnings) == 1
assert warnings[0].error_type == HintLintErrorType.HINT_UNKNOWN_INTENT
assert "poetry" in warnings[0].message
+ # An intent finding is about the `intent` key, whatever word it holds.
+ assert warnings[0].hint_key == "intent"
def test_choice_field_is_not_a_text_site(self):
"""Choices dominate the declared type (the deriver emits an enum), so a text intent on a
@@ -153,6 +158,8 @@ class TestHintLintFindings:
assert len(warnings) == MAX_HINT_FINDINGS_PER_SITE + 1
assert all(warning.error_type == HintLintErrorType.HINT_UNKNOWN_KEY for warning in warnings)
assert warnings[-1].message.startswith("...and 4 more hint key(s) on concept 'docs.Essay'")
+ # The tail stands for every key past the cap and names the first of them.
+ assert warnings[-1].hint_key == f"key_{MAX_HINT_FINDINGS_PER_SITE:02d}"
def test_exactly_the_cap_reports_every_key_with_no_tail(self):
hints = {f"key_{index:02d}": "value" for index in range(MAX_HINT_FINDINGS_PER_SITE)}
@@ -180,6 +187,8 @@ class TestHintLintFindings:
assert len(warnings) == 1
assert long_key not in warnings[0].message
assert f"'{'k' * MAX_AUTHORED_TOKEN_LENGTH}...'" in warnings[0].message
+ # The key rides elided, as the message quotes it.
+ assert warnings[0].hint_key == f"{'k' * MAX_AUTHORED_TOKEN_LENGTH}..."
def test_a_long_authored_intent_value_is_elided_in_the_message(self):
long_word = "w" * (MAX_AUTHORED_TOKEN_LENGTH + 50)
@@ -271,3 +280,42 @@ class TestHintLintOrdering:
second = [(w.error_type, w.concept_code) for w in _lint(crate)]
assert first == second
assert [code for _, code in first] == ["Alpha", "Beta"]
+
+ def test_each_finding_s_problem_item_says_which_declaration_the_hint_is_on(self):
+ """`method.hint_invalid` names the hint and why, never where it is written: its location says which declaration.
+
+ A concept is located at its bundle-root path, a field of its structure at the field's, and a pipe's input at the
+ pipe and the input.
+ """
+ warnings = _lint(
+ _crate(
+ {
+ "docs.Invoice": ConceptBlueprint(
+ description="an invoice",
+ structure={
+ "total": ConceptStructureBlueprint(
+ description="the total", type=ConceptStructureBlueprintFieldType.TEXT, hints={"typo": "x"}
+ )
+ },
+ hints={"typo": "x"},
+ )
+ },
+ {
+ "docs.summarize": PipeLLMBlueprint(
+ description="summarize",
+ inputs={"invoice": InputSlotBlueprint(concept="Invoice", hints={"typo": "x"})},
+ output="Text",
+ prompt="Summarize $invoice",
+ )
+ },
+ )
+ )
+
+ items = warning_problem_items(warnings=warnings)
+
+ dumped = [item.model_dump(mode="json", exclude_none=True) for item in items]
+ assert [(item["code"], item["params"], item.get("location")) for item in dumped] == [
+ ("method.hint_invalid", {"reason": "unknown_key", "hint": "typo"}, {"field": "concept.Invoice"}),
+ ("method.hint_invalid", {"reason": "unknown_key", "hint": "typo"}, {"field": "concept.Invoice.structure.total"}),
+ ("method.hint_invalid", {"reason": "unknown_key", "hint": "typo"}, {"pipe": "summarize", "input": "invoice"}),
+ ]
diff --git a/tests/unit/pipelex/pipeline/test_refusal_verdict_arms.py b/tests/unit/pipelex/pipeline/test_refusal_verdict_arms.py
index f7b9bbe47..dc92ef4aa 100644
--- a/tests/unit/pipelex/pipeline/test_refusal_verdict_arms.py
+++ b/tests/unit/pipelex/pipeline/test_refusal_verdict_arms.py
@@ -4,13 +4,15 @@ from mthds.protocol.problem.registry import CoreCode
from pipelex.base_exceptions import PipelexError, SecurityError, ValidationErrorCategory, ValidationErrorItem
from pipelex.cogt.model_backends.model_type import ModelType
from pipelex.core.exceptions import DryRunFailureErrorData
-from pipelex.core.pipes.exceptions import PipeLoadRefusalError, PipeOperatorModelChoiceError
+from pipelex.core.pipes.exceptions import PipeLoadRefusalError, PipeOperatorModelChoiceError, PipeRunError
from pipelex.errors.error_codes import error_code_spec
from pipelex.errors.problem import ProblemView
from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
from pipelex.libraries.exceptions import LibraryError
+from pipelex.pipe_run.exceptions import DryRunError
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.validate_bundle_translation import translate_to_validate_bundle_error
+from pipelex.system.pipe_run_mode import PipeRunMode
from pipelex.validation_error_types import PipeValidationErrorType
@@ -131,6 +133,38 @@ class TestRefusalVerdictArms:
raise fault
assert raised.value is fault
+ def test_a_pipe_run_failure_wrapping_a_security_refusal_is_no_verdict(self) -> None:
+ """The refusal is the method's to act on, yet a security rule made it: the wrapper keeps its code, never a verdict."""
+ refusal = _InputSecurityRefusalError("a template read a private name")
+ wrapper = PipeRunError("Pipe 'say' failed", run_mode=PipeRunMode.DRY, pipe_code="say")
+ wrapper.__cause__ = refusal
+
+ with pytest.raises(PipeRunError) as raised, translate_to_validate_bundle_error():
+ raise wrapper
+
+ assert raised.value is wrapper
+ assert wrapper.resolve_error_code() == CoreCode.SECURITY_TEMPLATE_REFUSED
+
+ def test_a_sweep_with_a_security_refusal_among_its_failures_is_no_verdict(self) -> None:
+ """One method fault beside one security refusal: the sweep answers the refusal's code, never an invalid verdict."""
+ sweep = DryRunError(
+ "Dry run failed for 2 pipe(s)",
+ failures=[
+ DryRunFailureErrorData(pipe_code="route_parcel", message="the round has no lane", code=CoreCode.PIPE_CONDITION_UNMATCHED),
+ DryRunFailureErrorData(pipe_code="say", message="a template was refused", code=CoreCode.SECURITY_TEMPLATE_REFUSED),
+ ],
+ )
+
+ with pytest.raises(DryRunError) as raised, translate_to_validate_bundle_error():
+ raise sweep
+
+ assert raised.value is sweep
+ assert sweep.resolve_error_code() == CoreCode.SECURITY_TEMPLATE_REFUSED
+ assert [item.code for item in sweep.to_problem(view=ProblemView.CALLER).errors or []] == [
+ CoreCode.PIPE_CONDITION_UNMATCHED,
+ CoreCode.SECURITY_TEMPLATE_REFUSED,
+ ]
+
def test_a_produced_verdict_passes_through_unwrapped(self) -> None:
verdict = ValidateBundleError(
message="already a verdict",
diff --git a/tests/unit/pipelex/pipeline/test_validation_errors.py b/tests/unit/pipelex/pipeline/test_validation_errors.py
index 375a98ac3..42bc5d19b 100644
--- a/tests/unit/pipelex/pipeline/test_validation_errors.py
+++ b/tests/unit/pipelex/pipeline/test_validation_errors.py
@@ -21,9 +21,9 @@ from pipelex.core.exceptions import (
from pipelex.errors.bundle_validation_failure import BundleValidationFailure
from pipelex.errors.problem import ProblemView
from pipelex.pipeline.exceptions import ValidateBundleError
-from pipelex.pipeline.validation_errors import build_validation_error_items
+from pipelex.pipeline.validation_errors import build_validation_error_items, warning_problem_items
from pipelex.suggested_fix import DeleteKeyOp, RenameTableKeyOp, SetKeyOp
-from pipelex.validation_error_types import PipeFactoryErrorType, PipeValidationErrorType
+from pipelex.validation_error_types import HintLintErrorType, PipeFactoryErrorType, PipeValidationErrorType, TemplateCheckErrorType
def _build_items(exc: ValidateBundleError) -> list[ValidationErrorItem]:
@@ -439,3 +439,48 @@ class TestBuildValidationErrorItems:
assert items[0].source == "instantiated.mthds"
# And the verdict lists it (it would be missing if the list were dropped).
assert [item.pipe_code for item in exc.validation_error_items()] == ["pipe_inst"]
+
+ def test_warnings_become_problem_items_under_the_code_their_type_names(self) -> None:
+ """A valid report's warnings, as a surface speaking problem items carries them: each type names its code, and a
+ warning no type classifies takes `method.schema_violation`, as an unclassified item of an invalid verdict does.
+ """
+ hint_warning = ValidationErrorItem(
+ category=ValidationErrorCategory.BLUEPRINT_VALIDATION,
+ error_type=HintLintErrorType.HINT_UNKNOWN_KEY,
+ concept_code="Essay",
+ domain_code="docs",
+ hint_key="emphasis",
+ message="Hint key 'emphasis' on concept 'docs.Essay' is not defined by this version of the standard.",
+ )
+ template_warning = ValidationErrorItem(
+ category=ValidationErrorCategory.DRY_RUN,
+ error_type=TemplateCheckErrorType.TEMPLATE_CHECK_WARNING,
+ pipe_code="print_invoice",
+ template_file="invoice.xlsx",
+ message="The name Totl matches no field.",
+ )
+ unclassified_warning = ValidationErrorItem(category=ValidationErrorCategory.BLUEPRINT_VALIDATION, message="Something to look at.")
+
+ items = warning_problem_items(warnings=[hint_warning, template_warning, unclassified_warning])
+
+ assert [item.model_dump(mode="json", exclude_none=True) for item in items] == [
+ {
+ "code": "method.hint_invalid",
+ "detail": items[0].detail,
+ "params": {"reason": "unknown_key", "hint": "emphasis"},
+ # The declaration the hint is on, which neither parameter names.
+ "location": {"field": "concept.Essay"},
+ },
+ {
+ "code": "pipelex.docgen.template_warning",
+ "detail": "The document template 'invoice.xlsx' may be faulty: The name Totl matches no field.",
+ "params": {"template": "invoice.xlsx", "finding": "The name Totl matches no field."},
+ "location": {"pipe": "print_invoice"},
+ },
+ {
+ "code": "method.schema_violation",
+ "detail": items[2].detail,
+ "params": {"finding": "Something to look at."},
+ },
+ ]
+ assert "emphasis" in items[0].detail
diff --git a/tests/unit/pipelex/pipeline/test_validation_render.py b/tests/unit/pipelex/pipeline/test_validation_render.py
index 02909a5c3..6e49b6d6e 100644
--- a/tests/unit/pipelex/pipeline/test_validation_render.py
+++ b/tests/unit/pipelex/pipeline/test_validation_render.py
@@ -5,16 +5,22 @@ from __future__ import annotations
from pathlib import Path
from typing import Any
+from mthds.protocol.problem.models import FixOp, ProblemItem, SetKeyOp
+from mthds.protocol.problem.models import SuggestedFix as WireSuggestedFix
+from mthds.protocol.problem.registry import CoreCode
+
from pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem
+from pipelex.errors.error_codes import error_code_spec
+from pipelex.pipeline.validation_errors import problem_item_of, validation_item_code
from pipelex.pipeline.validation_render import (
build_fix_command,
format_validate_markdown,
- format_validation_error_items_markdown,
- render_invalid_validation_markdown,
+ render_invalid_verdict_markdown,
suggested_fix_label,
)
from pipelex.suggested_fix import FixSafety, SuggestedFix
-from pipelex.validation_error_types import PipeValidationErrorType, ValidationResidualErrorType
+from pipelex.suggested_fix import SetKeyOp as PipelexSetKeyOp
+from pipelex.validation_error_types import PipeValidationErrorType
class TestValidationRender:
@@ -120,96 +126,44 @@ class TestValidationRender:
assert "✅" not in markdown
assert "⚠️" not in markdown
- def test_renders_invalid_report_as_prose_with_fix_lines_and_dry_run_residual(self):
- """The invalid-arm renderer reconstructs the typed items from the report and delegates to
- the shared prose renderer: category-grouped headings, humanized titles, identity fields,
- the message, per-item `💡 Suggested fix` lines, and the plain dry_run residual — the same
- prose the agent CLI and human panel show (no more dict-based `## Errors (N)` list).
+ def test_renders_an_invalid_verdict_from_its_problem_items(self):
+ """The invalid-arm renderer presents the verdict's problem items, the `errors` a host answers: each numbered under
+ its code's title with its code, where it is, its sentence and its suggested fix, and never a validation item's own
+ message, which the reader's view of the items does not carry.
"""
- report: dict[str, Any] = {
- "is_valid": False,
- "message": "MTHDS validation found errors",
- "validation_errors": [
- {
- "category": "pipe_validation",
- "error_type": "inadequate_output_multiplicity",
- "message": "Pipe references an unknown concept.",
- "pipe_code": "summarize",
- "concept_code": "Contractt",
- "field_name": "output",
- "source": "/fake/method.mthds",
- "suggested_fix": {
- "fix_code": "match-sequence-output",
- "description": "Set output of pipe 'summarize' to 'Contract'",
- "safety": "safe",
- "ops": [],
- },
- },
- {
- "category": "dry_run",
- "error_type": "DryRunError",
- "message": "Dry run failed: boom.",
- },
- ],
- }
+ validation_item = ValidationErrorItem(
+ category=ValidationErrorCategory.PIPE_VALIDATION,
+ error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY,
+ message="The operator's own wording of the fault.",
+ pipe_code="summarize",
+ field_name="output",
+ source="/fake/method.mthds",
+ line=7,
+ suggested_fix=SuggestedFix(
+ fix_code="match-sequence-output",
+ description="Set output of pipe 'summarize' to 'Contract'",
+ safety=FixSafety.SAFE,
+ ops=[PipelexSetKeyOp(table_path=["pipe", "summarize"], key="output", value="Contract")],
+ ),
+ )
+ code = validation_item_code(item=validation_item, residual_code=CoreCode.METHOD_SCHEMA_VIOLATION)
+ item = problem_item_of(item=validation_item, code=code)
- markdown = render_invalid_validation_markdown(report)
+ markdown = render_invalid_verdict_markdown(items=[item], message="MTHDS validation found errors")
assert markdown.startswith("# Validation failed")
- # Prose shape from the shared renderer: category heading + humanized title + identity fields.
- assert "## Pipe validation errors" in markdown
- assert "1. **Inadequate Output Multiplicity**" in markdown
+ assert f"1. **{error_code_spec(code).title}** (`{code}`)" in markdown
assert " - Pipe: `summarize`" in markdown
- assert " - Concept: `Contractt`" in markdown
assert " - Field: `output`" in markdown
- assert " - Pipe references an unknown concept." in markdown
+ assert " - File: `/fake/method.mthds:7`" in markdown
+ assert f" - {item.detail}" in markdown
assert " - 💡 Suggested fix: Set output of pipe 'summarize' to 'Contract'" in markdown
- assert " - Source: `/fake/method.mthds`" in markdown
- # The dry_run residual keeps its plain single-message rendering.
- assert "## Dry run error" in markdown
- assert "Dry run failed: boom." in markdown
-
- def test_format_validation_error_items_markdown_groups_categories_and_renders_fix_line(self):
- """The shared items renderer groups by category, humanizes the error_type title, renders
- the identity fields + message + `💡 Suggested fix` line, and keeps the dry_run residual plain.
- """
- items = [
- ValidationErrorItem(
- category=ValidationErrorCategory.PIPE_VALIDATION,
- error_type=PipeValidationErrorType.INADEQUATE_OUTPUT_MULTIPLICITY,
- pipe_code="brainstorm",
- domain_code="story_studio",
- source="/w/bundle.mthds",
- message="the sequence 'brainstorm' declares its output as 'StoryIdea', but its last step yields 'StoryIdea[]'.",
- suggested_fix=SuggestedFix(
- fix_code="match-sequence-output",
- description="Set output of pipe 'brainstorm' to 'StoryIdea[]' to match its last step",
- safety=FixSafety.SAFE,
- ops=[],
- ),
- ),
- ValidationErrorItem(
- category=ValidationErrorCategory.DRY_RUN,
- error_type=ValidationResidualErrorType.DRY_RUN_ERROR,
- message="Dry run failed: boom.",
- ),
- ]
+ assert "operator's own wording" not in markdown
+
+ def test_an_invalid_verdict_with_no_item_shows_its_sentence(self):
+ markdown = render_invalid_verdict_markdown(items=[], message="MTHDS validation found errors")
- markdown = format_validation_error_items_markdown(items)
-
- # Category grouping (markdown headings), humanized title, identity fields, message, fix line.
- assert "## Pipe validation errors" in markdown
- assert "1. **Inadequate Output Multiplicity**" in markdown
- assert " - Pipe: `brainstorm`" in markdown
- assert " - Domain: `story_studio`" in markdown
- assert " - the sequence 'brainstorm' declares its output as 'StoryIdea'" in markdown
- assert " - 💡 Suggested fix: Set output of pipe 'brainstorm' to 'StoryIdea[]' to match its last step" in markdown
- assert " - Source: `/w/bundle.mthds`" in markdown
- # No internal repr / Python-list-repr brackets leak (Phase 1 diseases stay cured downstream).
- assert "multiplicity=None" not in markdown
- # The dry_run residual keeps its plain single-message rendering (no numbering, no bullets).
- assert "## Dry run error" in markdown
- assert "Dry run failed: boom." in markdown
+ assert markdown == "# Validation failed\n\nMTHDS validation found errors"
def test_suggested_fix_label_says_when_a_fix_is_unsafe(self):
"""A safe fix is a plain `Suggested fix`; an unsafe one says it is unsafe and needs confirming."""
@@ -219,40 +173,30 @@ class TestValidationRender:
assert suggested_fix_label(fix=safe_fix) == "Suggested fix"
assert suggested_fix_label(fix=unsafe_fix) == "Suggested fix (unsafe, confirm before applying)"
- def test_invalid_report_markdown_marks_an_unsafe_fix(self):
+ def test_invalid_verdict_markdown_marks_an_unsafe_fix(self):
"""The hosted `rendered_markdown` path labels an unsafe wire fix, next to a safe one left plain."""
- report: dict[str, Any] = {
- "is_valid": False,
- "message": "MTHDS validation found errors",
- "validation_errors": [
- {
- "category": "pipe_validation",
- "error_type": "inadequate_output_multiplicity",
- "message": "Output mismatch.",
- "pipe_code": "summarize",
- "suggested_fix": {
- "fix_code": "match-sequence-output",
- "description": "Set output of pipe 'summarize' to 'Contract'",
- "safety": "safe",
- "ops": [],
- },
- },
- {
- "category": "pipe_validation",
- "error_type": "unknown_model",
- "message": "Model handle 'gpt-5.1' was not found in the model deck",
- "pipe_code": "write",
- "suggested_fix": {
- "fix_code": "rename-model",
- "description": "Replace model 'gpt-5.1' of pipe 'write' with 'gpt-5', its one close match in the model deck",
- "safety": "unsafe",
- "ops": [],
- },
- },
- ],
- }
+ ops: list[FixOp] = [SetKeyOp(kind="set_key", table_path=["pipe", "write"], key="model", value="gpt-5")]
+ items = [
+ ProblemItem(
+ code="method.schema_violation",
+ detail="Output mismatch.",
+ suggested_fix=WireSuggestedFix(
+ fix_code="match-sequence-output", description="Set output of pipe 'summarize' to 'Contract'", safety="safe", ops=ops
+ ),
+ ),
+ ProblemItem(
+ code="model.unknown",
+ detail="The model is not in the deck.",
+ suggested_fix=WireSuggestedFix(
+ fix_code="rename-model",
+ description="Replace model 'gpt-5.1' of pipe 'write' with 'gpt-5', its one close match in the model deck",
+ safety="unsafe",
+ ops=ops,
+ ),
+ ),
+ ]
- markdown = render_invalid_validation_markdown(report)
+ markdown = render_invalid_verdict_markdown(items=items, message="MTHDS validation found errors")
assert " - 💡 Suggested fix: Set output of pipe 'summarize' to 'Contract'" in markdown
assert " - 💡 Suggested fix (unsafe, confirm before applying): Replace model 'gpt-5.1' of pipe 'write' with 'gpt-5'" in markdown
diff --git a/tests/unit/pipelex/system/test_job_metadata_request_id.py b/tests/unit/pipelex/system/test_job_metadata_request_id.py
index 6cf00fadf..d815c49f8 100644
--- a/tests/unit/pipelex/system/test_job_metadata_request_id.py
+++ b/tests/unit/pipelex/system/test_job_metadata_request_id.py
@@ -48,15 +48,21 @@ class TestJobMetadataRequestId:
"abc\tdef", # tab (outside printable ASCII range)
"café", # non-ASCII (latin-1 supplement)
"x" * 129, # exceeds max_length=128
+ " ", # a space alone, which a header trims to nothing
+ "abc def", # a space, which splits a key=value log line
+ "abc error.code=forged", # a forged field of a key=value log line
+ 'abc"def', # a quote, which closes a quoted value
+ "abc;q=1", # a header parameter
+ "req_abc.123", # a dot: outside the one rule the API server's middleware applies too
],
)
def test_request_id_rejects_unsanitized_input(self, bad_request_id: str) -> None:
- """``request_id`` is constrained to printable ASCII (max 128 chars).
+ """``request_id`` holds ASCII letters, digits, ``_`` and ``-`` alone (max 128 chars).
Defense-in-depth: an upstream consumer of pipelex that forwards the
- ``X-Request-ID`` header without sanitization cannot inject newlines,
- ANSI escapes, or control characters into the log lines and
- problem documents that quote it.
+ ``X-Request-ID`` header without sanitization cannot inject a line, a
+ field or a header parameter into the log lines, the headers and the
+ problem documents that carry it.
"""
with pytest.raises(ValidationError):
JobMetadata(
@@ -68,12 +74,13 @@ class TestJobMetadataRequestId:
[
"abc-123",
"11111111-2222-3333-4444-555555555555", # uuid
- "req_abc.123",
+ "01JA2B3C4D5E6F7G8H9J0K1M2N", # ulid
+ "req_abc_123",
"x" * 128, # at the limit
],
)
def test_request_id_accepts_well_formed_input(self, good_request_id: str) -> None:
- """Common ``X-Request-ID`` shapes (UUID, hyphenated, dot-separated) round-trip cleanly."""
+ """Common ``X-Request-ID`` shapes (UUID, ULID, hyphenated, underscored) round-trip cleanly."""
meta = JobMetadata(
run_metadata=RunMetadata(storage_scope="test/scope", read_scope=None, user_id="u", pipeline_run_id="r", request_id=good_request_id)
)
diff --git a/tests/unit/pipelex/tools/jinja2/test_jinja2_render_owner.py b/tests/unit/pipelex/tools/jinja2/test_jinja2_render_owner.py
index 3246f876b..f22114057 100644
--- a/tests/unit/pipelex/tools/jinja2/test_jinja2_render_owner.py
+++ b/tests/unit/pipelex/tools/jinja2/test_jinja2_render_owner.py
@@ -5,8 +5,8 @@ from typing import TYPE_CHECKING, Any
import pytest
from mthds.protocol.problem.registry import CoreCode, ProblemDomain
+from pipelex.base_exceptions import PipelexError
from pipelex.errors.problem import ProblemView
-from pipelex.system.exceptions import ToolError
from pipelex.tools.jinja2.exceptions import (
Jinja2StuffError,
Jinja2TemplateBudgetError,
@@ -23,7 +23,6 @@ from pipelex.tools.templating.templating_style import TagStyle, TemplatingStyle
from pipelex.tools.templating.text_format import TextFormat
if TYPE_CHECKING:
- from pipelex.base_exceptions import PipelexError
from pipelex.errors.error_codes import ErrorCode
_TEMPLATING_STYLE = TemplatingStyle(tag_style=TagStyle.NO_TAG, text_format=TextFormat.PLAIN)
@@ -44,8 +43,8 @@ async def _render_failure(
category: TemplateCategory = TemplateCategory.LLM_PROMPT,
is_undefined_strict: bool = False,
) -> PipelexError:
- # The sandbox's refusal is a `SecurityError`, not a `ToolError`: every other render failure is a `ToolError`.
- with pytest.raises((ToolError, Jinja2TemplateSecurityError)) as exc_info:
+ # A render fails with a `ToolError`, or with the sandbox's refusal, which is a `SecurityError`.
+ with pytest.raises(PipelexError) as exc_info:
await render_jinja2_async(
template_source=template_source,
template_category=category,
diff --git a/tests/unit/pipelex/tools/uri/test_uri_read_scope.py b/tests/unit/pipelex/tools/uri/test_uri_read_scope.py
index 344e6f9f4..3485d6fee 100644
--- a/tests/unit/pipelex/tools/uri/test_uri_read_scope.py
+++ b/tests/unit/pipelex/tools/uri/test_uri_read_scope.py
@@ -1,7 +1,7 @@
"""The read scope's check: a scoped run reads only its own storage prefix, and never the local disk."""
import pytest
-from mthds.protocol.problem.registry import CoreCode, ProblemDomain
+from mthds.protocol.problem.registry import CoreCode, ProblemDomain, SecurityInputUrlRefusedTargetClass, SecurityMethodUrlRefusedTargetClass
from pipelex.errors.error_codes import error_code_spec
from pipelex.errors.problem import ProblemView
@@ -74,6 +74,42 @@ class TestAuthorizeUriRead:
# A path on the server's disk, or a scheme the run does not read, is a refused scheme to the security event.
assert exc_info.value.security_target_class == SecurityTargetClass.SCHEME
+ @pytest.mark.parametrize(
+ ("reason", "event_target_class", "listed_target_class"),
+ [
+ (UriReadRefusalReason.FOREIGN_STORAGE_KEY, SecurityTargetClass.FOREIGN_STORAGE_KEY, "private"),
+ (UriReadRefusalReason.LOCAL_PATH, SecurityTargetClass.SCHEME, "scheme"),
+ ],
+ )
+ def test_the_problem_s_target_class_is_a_value_the_registry_lists(
+ self, reason: UriReadRefusalReason, event_target_class: SecurityTargetClass, listed_target_class: str
+ ) -> None:
+ """The caller reads a `target_class` the registry lists, which its sentence reads as a word, never a Pipelex token.
+
+ The security event keeps the finer class the refusal states, which the registry lists no value for.
+ """
+ as_input = UriReadRefusedError("refused", reason=reason).with_params(input="photo")
+ as_method = UriReadRefusedError("refused", reason=reason).with_error_code(CoreCode.SECURITY_METHOD_URL_REFUSED).with_params(pipe="describe")
+
+ assert listed_target_class in {str(value) for value in SecurityInputUrlRefusedTargetClass}
+ assert listed_target_class in {str(value) for value in SecurityMethodUrlRefusedTargetClass}
+ for refusal in (as_input, as_method):
+ assert refusal.security_target_class == event_target_class
+ for view in ProblemView:
+ params = refusal.to_problem(view=view).params
+ assert params is not None
+ assert params.as_wire()["target_class"] == listed_target_class
+ assert as_input.to_problem(view=ProblemView.CALLER).detail == (
+ f"The URL of the input 'photo' points at a {listed_target_class} target, which a security rule forbids (reason: {reason.desc})."
+ )
+ assert as_method.to_problem(view=ProblemView.CALLER).detail == (
+ f"Pipe 'describe' names a URL that points at a {listed_target_class} target, which a security rule forbids (reason: {reason.desc})."
+ )
+
+ @pytest.mark.parametrize("target_class", list(SecurityTargetClass))
+ def test_every_target_class_falls_under_a_value_the_registry_lists(self, target_class: SecurityTargetClass) -> None:
+ assert str(target_class.listed_target_class) in {str(value) for value in SecurityInputUrlRefusedTargetClass}
+
def test_a_multi_segment_scope_compares_every_segment(self) -> None:
authorize_uri_read(uri="pipelex-storage://org_abc/team_1/x.png", read_scope="org_abc/team_1", position="p")
with pytest.raises(UriReadRefusedError):