pipelex-api 0.93.1__tar.gz → 0.95.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/PKG-INFO +2 -2
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/exceptions.py +30 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/main.py +5 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/method_tree_request.py +70 -8
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/routes/pipelex/pipeline.py +78 -73
- pipelex_api-0.95.0/pipelex_api/run_webhooks.py +225 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/schemas/models.py +28 -18
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/.gitignore +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/LICENSE +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/README.md +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/hatch_build.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/__init__.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/api.toml +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/api_config.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/blob_store.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/blob_upload.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/bundle.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/bundle_resources.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/exception_handlers.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/json_body.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/limits.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/method_cache.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/method_source.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/middleware.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/openapi_responses.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/openapi_schema.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/problem_document.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/problem_view.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/py.typed +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/request_refusals.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/routes/__init__.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/routes/blob_upload.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/routes/health.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/routes/pipelex/__init__.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/routes/pipelex/agent/__init__.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/routes/pipelex/agent/models.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/routes/pipelex/blobs.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/routes/pipelex/codegen.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/routes/pipelex/crate_ops.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/routes/pipelex/method_selection.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/routes/pipelex/pipe_io.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/routes/pipelex/resolve.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/routes/pipelex/tools.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/routes/pipelex/utils.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/routes/pipelex/validate.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/routes/version.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/run_extras_binding.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/schemas/__init__.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pipelex_api/security.py +0 -0
- {pipelex_api-0.93.1 → pipelex_api-0.95.0}/pyproject.toml +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: pipelex-api
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.95.0
|
|
4
4
|
Summary: Pipelex API
|
|
5
5
|
Project-URL: Homepage, https://pipelex.com
|
|
6
6
|
Project-URL: Repository, https://github.com/Pipelex/pipelex
|
|
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.13
|
|
|
16
16
|
Classifier: Programming Language :: Python :: 3.14
|
|
17
17
|
Requires-Python: <3.15,>=3.11
|
|
18
18
|
Requires-Dist: fastapi<0.142,>=0.118.0
|
|
19
|
-
Requires-Dist: pipelex[anthropic,bedrock,fal,google,google-genai,mistralai]==0.
|
|
19
|
+
Requires-Dist: pipelex[anthropic,bedrock,fal,google,google-genai,mistralai]==0.95.0
|
|
20
20
|
Requires-Dist: pyjwt>=2.10.1
|
|
21
21
|
Requires-Dist: uvicorn>=0.37.0
|
|
22
22
|
Provides-Extra: dev
|
|
@@ -96,6 +96,36 @@ class CallbackUrlRefusedError(PipelexError, ValueError):
|
|
|
96
96
|
return make_location(field="callback_urls")
|
|
97
97
|
|
|
98
98
|
|
|
99
|
+
class CallerWebhookSecretNotConfiguredError(PipelexError):
|
|
100
|
+
"""A request registering callback URLs on a runner whose operator configured no secret to sign its webhooks with.
|
|
101
|
+
|
|
102
|
+
The runner signs every call it makes to a caller's webhook, so it refuses the request before running anything rather
|
|
103
|
+
than send calls nobody can verify. Its code, ``pipelex.webhook.secret_not_configured``, names the ``setting`` to the
|
|
104
|
+
caller too, since it is the deployment's to set and the caller's to ask for, and the problem is located at the field
|
|
105
|
+
``callback_urls``.
|
|
106
|
+
"""
|
|
107
|
+
|
|
108
|
+
error_code = PipelexErrorCode.WEBHOOK_SECRET_NOT_CONFIGURED
|
|
109
|
+
|
|
110
|
+
def __init__(self, message: str, *, setting: str) -> None:
|
|
111
|
+
"""Build the refusal.
|
|
112
|
+
|
|
113
|
+
Args:
|
|
114
|
+
message: What the runner lacks, for the operator's diagnostics.
|
|
115
|
+
setting: The setting that holds the signing secret, the environment variable's name.
|
|
116
|
+
"""
|
|
117
|
+
super().__init__(message)
|
|
118
|
+
self.setting = setting
|
|
119
|
+
|
|
120
|
+
@override
|
|
121
|
+
def problem_params(self) -> dict[str, Any]:
|
|
122
|
+
return {"setting": self.setting}
|
|
123
|
+
|
|
124
|
+
@override
|
|
125
|
+
def problem_location(self) -> ProblemLocation | None:
|
|
126
|
+
return make_location(field="callback_urls")
|
|
127
|
+
|
|
128
|
+
|
|
99
129
|
class RunnerRequestError(PipelexError):
|
|
100
130
|
"""A request the runner refuses at its own boundary, before it reads a method or runs anything.
|
|
101
131
|
|
|
@@ -33,6 +33,7 @@ from pipelex_api.routes import router as api_router
|
|
|
33
33
|
from pipelex_api.routes.blob_upload import router as blob_upload_router
|
|
34
34
|
from pipelex_api.routes.health import router as health_router
|
|
35
35
|
from pipelex_api.routes.version import router as version_router
|
|
36
|
+
from pipelex_api.run_webhooks import ensure_completion_target_configured
|
|
36
37
|
from pipelex_api.security import get_auth_dependency
|
|
37
38
|
|
|
38
39
|
|
|
@@ -55,6 +56,10 @@ async def lifespan(_app: FastAPI) -> AsyncGenerator[None]:
|
|
|
55
56
|
# only needs `runtime_manager.environment` (from PIPELEX_ENV), which resolves without a
|
|
56
57
|
# live singleton. get_api_config() is @cache'd, so the warm here is reused everywhere.
|
|
57
58
|
boot_orchestrator = resolve_boot_orchestrator(get_api_config())
|
|
59
|
+
# A malformed completion target, or one without its signing secret, stops the boot too, rather than failing every
|
|
60
|
+
# `/start` once the server is up. The caller-webhook secret is not checked here: a runner without one serves every
|
|
61
|
+
# request but those with callback_urls.
|
|
62
|
+
ensure_completion_target_configured()
|
|
58
63
|
Pipelex.make(integration_mode=IntegrationMode.FASTAPI, boot_orchestrator=boot_orchestrator)
|
|
59
64
|
try:
|
|
60
65
|
yield
|
|
@@ -15,20 +15,25 @@ What this module does, in order:
|
|
|
15
15
|
1. Every limit of this runner on a tree (`MAX_METHOD_TREE_FILES`, `MAX_METHOD_TREE_TOTAL_KIB`,
|
|
16
16
|
`MAX_METHOD_TREE_FILE_KIB`) is checked on the sizes the entries state, before any blob is read: a 422
|
|
17
17
|
`method.package_invalid` whose `reason` names the limit and whose `limit` gives it.
|
|
18
|
-
2.
|
|
19
|
-
|
|
18
|
+
2. A map naming bytes by hash is read once holding no bytes, which applies every rule of the standard but the last: a
|
|
19
|
+
map breaking any other rule is refused, as step 4 answers it, before the blob store is read. The standard checks a
|
|
20
|
+
map's keys, then the entries of the keys it admits, and whether the runner holds the bytes a hash entry names last,
|
|
21
|
+
never for a key it refuses (MTHDS Protocol 2.0.1, "Method files"), so what the blob store holds never decides the
|
|
22
|
+
refusal of a map the standard refuses for anything else.
|
|
23
|
+
3. The bytes of every hash entry are read from the runner's blob store, under the caller's scope, at once.
|
|
24
|
+
4. The map is read (`read_file_map`): a refusal of the standard is a 422 `method.package_invalid` whose `reason` is the
|
|
20
25
|
refusal's code and whose `path` is the first path it names, except a key leaving the tree, which is the security
|
|
21
26
|
refusal `security.input_path_refused`, and an entry of the wrong shape, which is `request.invalid`; hash entries the
|
|
22
27
|
store does not hold at their stated size are one 422 `request.blobs_missing` whose `missing_blobs` parameter lists
|
|
23
28
|
every such hash.
|
|
24
|
-
|
|
29
|
+
5. The files `resources` sends join the tree (`with_resources`), the same bytes under a path the tree holds or a new
|
|
25
30
|
file at a tree path; other bytes under a path the tree holds are a 422 `request.invalid` naming `resources`.
|
|
26
|
-
|
|
31
|
+
6. Python is honored only on a sandbox-hosted deployment: a method holding a `.py` file is refused with a 501
|
|
27
32
|
`pipelex.deployment.custom_code_requires_sandbox` before anything is written, and on a sandbox-hosted deployment a
|
|
28
33
|
tree declaring a Python structure class is refused (`MethodStructuresRefusedError`, a 422).
|
|
29
|
-
|
|
34
|
+
7. Each tree read in full is recorded in the blob store, its files then its listing, so the next request can send it
|
|
30
35
|
by hash, and `POST /v1/blobs/missing` answers its digest with one lookup.
|
|
31
|
-
|
|
36
|
+
8. The trees are written out into a temporary directory and held as written (`pipelex.libraries.written_trees`), so
|
|
32
37
|
the load reads them back as written and names their files by their tree paths, then removed when the request ends.
|
|
33
38
|
"""
|
|
34
39
|
|
|
@@ -418,6 +423,63 @@ def _refuse_map(*, refusal_error: MethodTreeRefusedError, label: str, field: str
|
|
|
418
423
|
raise RequestMethodError(msg, file=first_name).with_params(reason=refusal.code, path=first_name) from refusal_error
|
|
419
424
|
|
|
420
425
|
|
|
426
|
+
def _refuse_source(*, source_error: TreeSourceError, label: str, field: str) -> NoReturn:
|
|
427
|
+
"""Answer a map the standard's reader cannot take as a source of a tree, such as one nested too deep, as `request.invalid`."""
|
|
428
|
+
msg = f"{label} is not a method tree. {source_error.message}"
|
|
429
|
+
raise RunnerRequestError(msg, field=field) from source_error
|
|
430
|
+
|
|
431
|
+
|
|
432
|
+
def _is_only_missing_bytes(*, code: TreeRefusalCode) -> bool:
|
|
433
|
+
"""Whether a refusal of a map read holding no bytes says the map breaks no rule but the bytes its hash entries name."""
|
|
434
|
+
match code:
|
|
435
|
+
case TreeRefusalCode.MISSING_BLOB:
|
|
436
|
+
return True
|
|
437
|
+
case (
|
|
438
|
+
TreeRefusalCode.SYMBOLIC_LINK
|
|
439
|
+
| TreeRefusalCode.SPECIAL_FILE
|
|
440
|
+
| TreeRefusalCode.INVALID_TREE_PATH
|
|
441
|
+
| TreeRefusalCode.NORMALIZATION_COLLISION
|
|
442
|
+
| TreeRefusalCode.PATH_COLLISION
|
|
443
|
+
| TreeRefusalCode.EMPTY_TREE
|
|
444
|
+
| TreeRefusalCode.LONE_FILE_EXCLUDED
|
|
445
|
+
| TreeRefusalCode.GITIGNORE_NOT_UTF8
|
|
446
|
+
| TreeRefusalCode.DUPLICATE_KEY
|
|
447
|
+
| TreeRefusalCode.EXCLUDED_NAME
|
|
448
|
+
| TreeRefusalCode.MALFORMED_ENTRY
|
|
449
|
+
| TreeRefusalCode.REFERENCE_INVALID
|
|
450
|
+
| TreeRefusalCode.REFERENCE_LEAVES_TREE
|
|
451
|
+
| TreeRefusalCode.REFERENCE_NOT_A_TREE_PATH
|
|
452
|
+
| TreeRefusalCode.REFERENCE_NOT_IN_TREE
|
|
453
|
+
| TreeRefusalCode.REFERENCE_IN_ONE_FILE_TREE
|
|
454
|
+
| TreeRefusalCode.FUNCTION_NAME_WITHOUT_MODULE
|
|
455
|
+
| TreeRefusalCode.FUNCTION_NAME_INVALID_SEGMENT
|
|
456
|
+
| TreeRefusalCode.MODULE_NOT_IN_TREE
|
|
457
|
+
| TreeRefusalCode.MODULE_AMBIGUOUS
|
|
458
|
+
):
|
|
459
|
+
return False
|
|
460
|
+
|
|
461
|
+
|
|
462
|
+
def _refuse_map_before_its_bytes(*, document: str, label: str, field: str) -> None:
|
|
463
|
+
"""Refuse a map that names bytes by hash for any rule it breaks but the holding of those bytes, before any is read.
|
|
464
|
+
|
|
465
|
+
The standard checks a map's keys, then the entries of the keys it admits, and whether the receiver holds the bytes
|
|
466
|
+
each hash entry names last, only for a map that breaks no other rule (MTHDS Protocol 2.0.1, "Method files", and the
|
|
467
|
+
method tree's "The File Entry"). Reading the blobs first would let what the blob store holds decide the refusal of a
|
|
468
|
+
map the standard refuses for a key or an entry: a hash held at another size than its entry states would answer
|
|
469
|
+
`request.invalid`, and a damaged blob a 500, for a map holding `inputs.json`. So the map is read once holding no
|
|
470
|
+
bytes, which applies every check but the last: a refusal for missing blobs says the map breaks no other rule, and
|
|
471
|
+
any other refusal is answered here, before the blob store is read. The map is parsed twice, which costs less than
|
|
472
|
+
the reads it spares a map refused anyway.
|
|
473
|
+
"""
|
|
474
|
+
try:
|
|
475
|
+
read_file_map(document)
|
|
476
|
+
except MethodTreeRefusedError as exc:
|
|
477
|
+
if not _is_only_missing_bytes(code=exc.refusal.code):
|
|
478
|
+
_refuse_map(refusal_error=exc, label=label, field=field)
|
|
479
|
+
except TreeSourceError as exc:
|
|
480
|
+
_refuse_source(source_error=exc, label=label, field=field)
|
|
481
|
+
|
|
482
|
+
|
|
421
483
|
async def _held_blobs(*, blob_store: RunnerBlobStore, stated_sizes: dict[str, set[int]], label: str, field: str) -> BlobStore:
|
|
422
484
|
"""The bytes a map's hash entries name that the blob store holds, each read in one request bounded by its stated size.
|
|
423
485
|
|
|
@@ -469,14 +531,14 @@ async def read_request_tree(
|
|
|
469
531
|
label=label,
|
|
470
532
|
)
|
|
471
533
|
if census.stated_sizes and blob_store is not None:
|
|
534
|
+
_refuse_map_before_its_bytes(document=document, label=label, field=field)
|
|
472
535
|
held = await _held_blobs(blob_store=blob_store, stated_sizes=census.stated_sizes, label=label, field=field)
|
|
473
536
|
try:
|
|
474
537
|
reading = read_file_map(document, blob_store=held)
|
|
475
538
|
except MethodTreeRefusedError as exc:
|
|
476
539
|
_refuse_map(refusal_error=exc, label=label, field=field)
|
|
477
540
|
except TreeSourceError as exc:
|
|
478
|
-
|
|
479
|
-
raise RunnerRequestError(msg, field=field) from exc
|
|
541
|
+
_refuse_source(source_error=exc, label=label, field=field)
|
|
480
542
|
request_tree = RequestTree(tree=reading.tree, contents=reading.contents)
|
|
481
543
|
ensure_tree_within_limits(tree=request_tree, label=label)
|
|
482
544
|
return request_tree
|
|
@@ -1,8 +1,6 @@
|
|
|
1
1
|
from __future__ import annotations
|
|
2
2
|
|
|
3
3
|
import asyncio
|
|
4
|
-
import hashlib
|
|
5
|
-
import hmac
|
|
6
4
|
from contextlib import asynccontextmanager
|
|
7
5
|
from pathlib import Path
|
|
8
6
|
from typing import TYPE_CHECKING, Annotated, Any, NamedTuple, cast
|
|
@@ -16,22 +14,21 @@ from pipelex.core.pipes.pipe_output import PipeOutput
|
|
|
16
14
|
from pipelex.errors.bundle_validation_failure import BundleValidationFailure
|
|
17
15
|
from pipelex.errors.problem import ProblemView
|
|
18
16
|
from pipelex.errors.registry.pipelex_codes import PipelexErrorCode
|
|
17
|
+
from pipelex.interpreter_hub import get_current_library_id_or_none
|
|
19
18
|
from pipelex.libraries.method_load_threads import run_method_load
|
|
20
19
|
from pipelex.libraries.method_requirements import ensure_served_method_requirements_met
|
|
21
20
|
from pipelex.libraries.method_tree_listing import MethodTreeListing, scoped_tree_listing
|
|
22
|
-
from pipelex.pipe_run.delivery_assignment import DeliveryAssignment, StorageTarget, WebhookTarget
|
|
23
21
|
from pipelex.pipe_run.exceptions import AsyncExecutionNotEnabledError
|
|
24
22
|
from pipelex.pipe_run.pipe_run_protocol import PipeRunProtocol
|
|
25
23
|
from pipelex.pipeline.exceptions import ValidateBundleError
|
|
26
24
|
from pipelex.pipeline.pipeline_response import PipelexRunResultExecute, PipelexRunResultStart, RunState
|
|
27
|
-
from pipelex.pipeline.pipeline_run_setup import pipeline_run_setup
|
|
25
|
+
from pipelex.pipeline.pipeline_run_setup import pipeline_run_setup, release_run_setup
|
|
28
26
|
from pipelex.pipeline.runner import PipelexMTHDSProtocol, refuse_method_files
|
|
29
27
|
from pipelex.pipeline.validate_bundle_translation import translate_to_validate_bundle_error
|
|
30
28
|
from pipelex.reporting.usage_records import apply_tokens_usage_wire_shape
|
|
31
29
|
from pipelex.runtime_bridge.exceptions import MissingBundleValidatorError, MissingOrchestratorError
|
|
32
30
|
from pipelex.runtime_bridge.primitives.hydration import hydrate_working_memory
|
|
33
31
|
from pipelex.runtime_hub import get_bundle_validator_registry, get_orchestrator_registry
|
|
34
|
-
from pipelex.system.environment import get_required_env
|
|
35
32
|
from pipelex.system.storage_scope import LOCAL_STORAGE_SCOPE, SINGLE_TENANT_USER_ID, validate_storage_scope_within_read_scope
|
|
36
33
|
from pydantic import ValidationError
|
|
37
34
|
from typing_extensions import override
|
|
@@ -66,10 +63,17 @@ from pipelex_api.openapi_responses import (
|
|
|
66
63
|
PROBLEM_501_RUN_POLICY,
|
|
67
64
|
PROBLEM_501_START,
|
|
68
65
|
)
|
|
69
|
-
from pipelex_api.problem_view import problem_view_of
|
|
70
66
|
from pipelex_api.request_refusals import WHOLE_BODY_FIELD, callback_url_refusal_in, refused_request_error
|
|
71
67
|
from pipelex_api.routes.pipelex.utils import get_current_iso_timestamp
|
|
72
68
|
from pipelex_api.run_extras_binding import bind_run_extras
|
|
69
|
+
from pipelex_api.run_webhooks import (
|
|
70
|
+
caller_webhook_urls,
|
|
71
|
+
ensure_caller_webhooks_signable,
|
|
72
|
+
ensure_completion_target_configured,
|
|
73
|
+
execute_delivery_assignment,
|
|
74
|
+
start_caller_webhook_urls,
|
|
75
|
+
start_delivery_assignment,
|
|
76
|
+
)
|
|
73
77
|
from pipelex_api.schemas.models import (
|
|
74
78
|
PipelexApiExecuteRequest,
|
|
75
79
|
PipelexApiExecuteResponse,
|
|
@@ -89,6 +93,7 @@ if TYPE_CHECKING:
|
|
|
89
93
|
from mthds.protocol.working_memory import WorkingMemoryAbstract
|
|
90
94
|
from pipelex.core.memory.working_memory import WorkingMemory
|
|
91
95
|
from pipelex.methods.fetching import MethodProvenance
|
|
96
|
+
from pipelex.pipe_run.delivery_assignment import DeliveryAssignment
|
|
92
97
|
from pipelex.pipe_run.pipe_job import PipeJob
|
|
93
98
|
from pipelex.pipeline.validation_report import PipelexValidationReport
|
|
94
99
|
from pipelex.plugins.orchestrator_registry import OrchestratorProtocol
|
|
@@ -231,21 +236,6 @@ def _resolve_run_scopes(request: Request, *, extras: PipelineApiExtras) -> _RunS
|
|
|
231
236
|
return _RunScopes(storage_scope=storage_scope, read_scope=read_scope)
|
|
232
237
|
|
|
233
238
|
|
|
234
|
-
def _completion_signature(pipeline_run_id: str) -> str:
|
|
235
|
-
"""Compute the HMAC-SHA256 signature for an async completion callback.
|
|
236
|
-
|
|
237
|
-
The signer (this server) and the verifier (your callback receiver) must
|
|
238
|
-
share the same `COMPLETION_CALLBACK_SECRET`. The signature is per-run and
|
|
239
|
-
the secret never travels — only the one-way hash does.
|
|
240
|
-
"""
|
|
241
|
-
secret = get_required_env("COMPLETION_CALLBACK_SECRET")
|
|
242
|
-
return hmac.new(
|
|
243
|
-
secret.encode("utf-8"),
|
|
244
|
-
pipeline_run_id.encode("utf-8"),
|
|
245
|
-
hashlib.sha256,
|
|
246
|
-
).hexdigest()
|
|
247
|
-
|
|
248
|
-
|
|
249
239
|
def _pipe_output_from_run_output(run_output: PipelexPipeRunOutput) -> PipeOutput:
|
|
250
240
|
"""Rehydrate an orchestrator's JSON-safe `PipelexPipeRunOutput` into a typed `PipeOutput`.
|
|
251
241
|
|
|
@@ -357,6 +347,8 @@ class ApiRunner(PipelexMTHDSProtocol):
|
|
|
357
347
|
delivery_assignment: DeliveryAssignment | None = None,
|
|
358
348
|
request_id: str | None = None,
|
|
359
349
|
tree_listing: MethodTreeListing | None = None,
|
|
350
|
+
pipeline_run_id: str | None = None,
|
|
351
|
+
callback_urls: list[str] | None = None,
|
|
360
352
|
requested_orchestration_mode: str | None = None,
|
|
361
353
|
) -> PipelexRunResultExecute:
|
|
362
354
|
"""Execute a method synchronously, dispatching by the resolved `orchestration_mode`.
|
|
@@ -383,11 +375,19 @@ class ApiRunner(PipelexMTHDSProtocol):
|
|
|
383
375
|
|
|
384
376
|
The method's trees are listed once for the request: the check of its requirements lists them through
|
|
385
377
|
`tree_listing`, or a listing of its own when none is given, and the run loads them from that same listing.
|
|
378
|
+
|
|
379
|
+
`pipeline_run_id` is the run's id when the caller chose it, honored as `start` honors it: a run still in
|
|
380
|
+
flight under the same id refuses this one with a 409 `pipelex.run.already_exists`. `callback_urls` are the
|
|
381
|
+
caller's webhooks (`pipelex_api.run_webhooks`): each receives the run's signed `run.finished` event when the run
|
|
382
|
+
ends, before this call returns, and a runner whose operator configured no signing secret refuses them with a
|
|
383
|
+
422 `pipelex.webhook.secret_not_configured` before anything loads. Their delivery never changes the run's outcome.
|
|
386
384
|
"""
|
|
387
385
|
# The route resolves a method sent as `files` into a written tree before it calls this runner, which takes it
|
|
388
386
|
# as its library directory, so the map reaches the runner only from in-process code, and is refused as the
|
|
389
387
|
# base runner refuses it, before any backend is looked up.
|
|
390
388
|
refuse_method_files(files=files)
|
|
389
|
+
caller_urls = caller_webhook_urls(callback_urls=callback_urls)
|
|
390
|
+
ensure_caller_webhooks_signable(caller_urls=caller_urls)
|
|
391
391
|
# Resolve the effective orchestration mode FIRST — a per-request override the deployment
|
|
392
392
|
# policy forbids is refused (422) here, before any library load / run registration. Mirrors start().
|
|
393
393
|
api_config = get_api_config()
|
|
@@ -412,9 +412,10 @@ class ApiRunner(PipelexMTHDSProtocol):
|
|
|
412
412
|
output_multiplicity=output_multiplicity,
|
|
413
413
|
dynamic_output_concept_ref=dynamic_output_concept_ref,
|
|
414
414
|
extra=extra,
|
|
415
|
-
delivery_assignment=delivery_assignment,
|
|
415
|
+
delivery_assignment=execute_delivery_assignment(caller_urls=caller_urls, delivery_assignment=delivery_assignment),
|
|
416
416
|
request_id=request_id,
|
|
417
417
|
tree_listing=listing,
|
|
418
|
+
pipeline_run_id=pipeline_run_id,
|
|
418
419
|
)
|
|
419
420
|
|
|
420
421
|
@override
|
|
@@ -433,7 +434,6 @@ class ApiRunner(PipelexMTHDSProtocol):
|
|
|
433
434
|
callback_urls: list[str] | None = None,
|
|
434
435
|
request_id: str | None = None,
|
|
435
436
|
requested_orchestration_mode: str | None = None,
|
|
436
|
-
callback_problem_view: ProblemView = ProblemView.CALLER,
|
|
437
437
|
) -> PipelexRunResultStart:
|
|
438
438
|
"""Start a method execution asynchronously without waiting for completion.
|
|
439
439
|
|
|
@@ -456,11 +456,12 @@ class ApiRunner(PipelexMTHDSProtocol):
|
|
|
456
456
|
`pipeline_run_id` is the client-supplied run identifier — this source-available runner
|
|
457
457
|
honors it (protocol: implementations MAY decline it, but then MUST 422;
|
|
458
458
|
we accept it, and `StartAck.pipeline_run_id` echoes it back as authoritative).
|
|
459
|
-
`callback_urls` is THIS server's extension (
|
|
460
|
-
layer validates it (`PipelineApiExtras`) and passes it here by name.
|
|
461
|
-
`
|
|
462
|
-
|
|
463
|
-
|
|
459
|
+
`callback_urls` is THIS server's extension (the caller's webhooks) — the wire
|
|
460
|
+
layer validates it (`PipelineApiExtras`) and passes it here by name. Each URL receives the
|
|
461
|
+
run's signed `run.finished` event, a failed run's problem in the caller's view, and a runner
|
|
462
|
+
whose operator configured no signing secret refuses them with a 422 before anything loads.
|
|
463
|
+
The deployment's own completion target, `COMPLETION_CALLBACK_URL`, is notified beside them,
|
|
464
|
+
with its own notice and signature (`pipelex_api.run_webhooks`).
|
|
464
465
|
`extra` is the protocol's generic extension slot; this runner's wire
|
|
465
466
|
extras are parsed by the route layer, so nothing reaches it — a
|
|
466
467
|
non-empty value is an in-process misuse and is rejected. `request_id`
|
|
@@ -478,6 +479,11 @@ class ApiRunner(PipelexMTHDSProtocol):
|
|
|
478
479
|
# value here is a fault of the in-process code calling this runner, never the caller's.
|
|
479
480
|
msg = f"ApiRunner defines no extension args beyond its named ones; got {sorted(extra)}."
|
|
480
481
|
raise PipelexUnexpectedError(msg)
|
|
482
|
+
# The caller's webhooks this runner cannot sign, and a completion target it cannot sign, are refused before
|
|
483
|
+
# anything else is looked up or loaded.
|
|
484
|
+
caller_urls = start_caller_webhook_urls(callback_urls=callback_urls, pipeline_run_id=pipeline_run_id)
|
|
485
|
+
ensure_caller_webhooks_signable(caller_urls=caller_urls)
|
|
486
|
+
ensure_completion_target_configured()
|
|
481
487
|
# Resolve the effective orchestration mode FIRST — a per-request override the deployment
|
|
482
488
|
# policy forbids is refused (422) here. Then look up the orchestrator and check its async
|
|
483
489
|
# capability: `/start` is fire-and-forget, so a blocking-only orchestrator (direct on the
|
|
@@ -502,9 +508,11 @@ class ApiRunner(PipelexMTHDSProtocol):
|
|
|
502
508
|
pipelex_inputs: PipelineInputs | WorkingMemory | None = cast("PipelineInputs | WorkingMemory | None", inputs)
|
|
503
509
|
|
|
504
510
|
execution_config = self.execution_config or get_config().interpreter.pipeline_execution
|
|
511
|
+
# The caller's current library, which a run that is not dispatched gives back.
|
|
512
|
+
prev_library_id = get_current_library_id_or_none()
|
|
505
513
|
# Wire and runtime share the `pipeline_run_id` name (master D1 as
|
|
506
514
|
# revised — the id rename was reversed).
|
|
507
|
-
pipe_job, resolved_pipeline_run_id,
|
|
515
|
+
pipe_job, resolved_pipeline_run_id, run_library_id = await pipeline_run_setup(
|
|
508
516
|
execution_config=execution_config,
|
|
509
517
|
library_id=self.library_id,
|
|
510
518
|
library_dirs=self.library_dirs,
|
|
@@ -534,42 +542,26 @@ class ApiRunner(PipelexMTHDSProtocol):
|
|
|
534
542
|
tree_listing=tree_listing,
|
|
535
543
|
)
|
|
536
544
|
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
#
|
|
545
|
-
# and
|
|
546
|
-
#
|
|
547
|
-
# `
|
|
548
|
-
#
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
headers={"X-Completion-Signature": _completion_signature(resolved_pipeline_run_id)},
|
|
558
|
-
problem_view=callback_problem_view,
|
|
559
|
-
)
|
|
560
|
-
for url in callback_urls
|
|
561
|
-
]
|
|
562
|
-
if callback_urls
|
|
563
|
-
else [],
|
|
564
|
-
)
|
|
565
|
-
|
|
566
|
-
# Dispatch the locally-built job through the resolved mode's orchestrator (looked up and
|
|
567
|
-
# capability-checked above) via its fire-and-forget `start` arm — the same final dispatch
|
|
568
|
-
# `run_pipe_via_bridge` performs, but fed the rich PipeJob instead of the lossy
|
|
569
|
-
# `PipelexPipeRunInput` (which carries no request_id / output_multiplicity /
|
|
570
|
-
# dynamic_output_concept_ref and skips run registration + telemetry). `start` genuinely
|
|
571
|
-
# enqueues the job and returns a `PipelexPipeDispatchAck` (ids only) immediately.
|
|
572
|
-
dispatch_ack = await orchestrator.start(pipe_job=pipe_job, delivery_assignment=delivery_assignment)
|
|
545
|
+
# Its results stored (with NO `key_prefix`: the runtime owns the `results/` leaf), the deployment's completion
|
|
546
|
+
# target notified, then the caller's webhooks sent their event. The completion URL is dropped from the caller's
|
|
547
|
+
# again now that the run's id is resolved, since the deployment's URL may name it.
|
|
548
|
+
dispatched = False
|
|
549
|
+
try:
|
|
550
|
+
delivery_assignment = start_delivery_assignment(caller_urls=caller_urls, pipeline_run_id=resolved_pipeline_run_id)
|
|
551
|
+
|
|
552
|
+
# Dispatch the locally-built job through the resolved mode's orchestrator (looked up and
|
|
553
|
+
# capability-checked above) via its fire-and-forget `start` arm — the same final dispatch
|
|
554
|
+
# `run_pipe_via_bridge` performs, but fed the rich PipeJob instead of the lossy
|
|
555
|
+
# `PipelexPipeRunInput` (which carries no request_id / output_multiplicity /
|
|
556
|
+
# dynamic_output_concept_ref and skips run registration + telemetry). `start` genuinely
|
|
557
|
+
# enqueues the job and returns a `PipelexPipeDispatchAck` (ids only) immediately.
|
|
558
|
+
dispatch_ack = await orchestrator.start(pipe_job=pipe_job, delivery_assignment=delivery_assignment)
|
|
559
|
+
dispatched = True
|
|
560
|
+
finally:
|
|
561
|
+
if not dispatched:
|
|
562
|
+
# The run never left this process: what its setup registered is released, its id first of all, so the
|
|
563
|
+
# caller can submit it again, and the failure propagates.
|
|
564
|
+
release_run_setup(pipe_job=pipe_job, library_id=run_library_id, prev_library_id=prev_library_id)
|
|
573
565
|
|
|
574
566
|
return PipelexRunResultStart(
|
|
575
567
|
pipeline_run_id=resolved_pipeline_run_id,
|
|
@@ -978,19 +970,19 @@ async def _run_source(*, run_request: RunRequest, body: bytes, blob_scope: str)
|
|
|
978
970
|
response_model=PipelexApiExecuteResponse,
|
|
979
971
|
# On top of the composite router's shared 401/413/422/500: a `read_scope` outside the caller's own (403), the
|
|
980
972
|
# `method_ref` package-not-found 404, the provider rate-limit passthrough (429) — `/execute` is the only route that runs inference, so
|
|
981
|
-
# it is the only one that can be rate-limited upstream —
|
|
982
|
-
#
|
|
983
|
-
#
|
|
984
|
-
# in-flight run. Its 500 names, beside the shared one's codes, a damaged blob a `files` map names by hash.
|
|
973
|
+
# it is the only one that can be rate-limited upstream — the 409 of a client-supplied `pipeline_run_id`
|
|
974
|
+
# still registered for an in-flight run, as on `/start`, and the custom-code sandbox gate's 501 on a
|
|
975
|
+
# bundle or a fetched package. Its 500 names, beside the shared one's codes, a damaged blob a `files` map names by hash.
|
|
985
976
|
responses={
|
|
986
977
|
403: PROBLEM_403_READ_SCOPE,
|
|
987
978
|
404: PROBLEM_404_METHOD_PACKAGE,
|
|
979
|
+
409: PROBLEM_409_DUPLICATE_RUN,
|
|
988
980
|
429: PROBLEM_429,
|
|
989
981
|
500: PROBLEM_500_HELD_BLOBS,
|
|
990
982
|
501: PROBLEM_501_RUN_POLICY,
|
|
991
983
|
},
|
|
992
|
-
# Documented body = the protocol's RunRequest plus THIS server's own
|
|
993
|
-
# `orchestration_mode`
|
|
984
|
+
# Documented body = the protocol's RunRequest plus THIS server's own extensions:
|
|
985
|
+
# `pipeline_run_id`, `callback_urls` and `orchestration_mode` (a policy-gated per-request override). The
|
|
994
986
|
# body is read through the raw Request (plain JSON with the reserved-key
|
|
995
987
|
# refusal — see `_parse_request`), so FastAPI cannot infer a typed body parameter;
|
|
996
988
|
# document it explicitly so the committed OpenAPI artifact (and protocol
|
|
@@ -1013,8 +1005,13 @@ async def execute(request: Request) -> JSONResponse:
|
|
|
1013
1005
|
regardless of backend (wait-semantics is endpoint-set, never requestable). Pipelex domain
|
|
1014
1006
|
failures propagate untouched: the global `PipelexError` handler in `pipelex_api.exception_handlers`
|
|
1015
1007
|
turns them into an RFC 7807 problem response.
|
|
1008
|
+
|
|
1009
|
+
A client-supplied `pipeline_run_id` is honored as `/start` honors it. Each of the `callback_urls` receives the run's
|
|
1010
|
+
signed `run.finished` event before the response is sent; their delivery never changes the response.
|
|
1016
1011
|
"""
|
|
1017
1012
|
run_request, extras, body = await _parse_request(request)
|
|
1013
|
+
# Webhooks this runner cannot sign are refused before the method is fetched or written.
|
|
1014
|
+
ensure_caller_webhooks_signable(caller_urls=caller_webhook_urls(callback_urls=extras.callback_urls))
|
|
1018
1015
|
scopes = _resolve_run_scopes(request, extras=extras)
|
|
1019
1016
|
blob_scope = resolve_blob_scope(request, read_scope=scopes.read_scope)
|
|
1020
1017
|
async with _run_source(run_request=run_request, body=body, blob_scope=blob_scope) as source:
|
|
@@ -1036,6 +1033,8 @@ async def execute(request: Request) -> JSONResponse:
|
|
|
1036
1033
|
output_multiplicity=run_request.output_multiplicity,
|
|
1037
1034
|
dynamic_output_concept_ref=run_request.dynamic_output_concept_ref,
|
|
1038
1035
|
request_id=request_id_of(request),
|
|
1036
|
+
pipeline_run_id=extras.pipeline_run_id,
|
|
1037
|
+
callback_urls=extras.callback_urls,
|
|
1039
1038
|
requested_orchestration_mode=extras.orchestration_mode,
|
|
1040
1039
|
)
|
|
1041
1040
|
# The response dump carries the full internal usage models on
|
|
@@ -1104,9 +1103,16 @@ async def start(
|
|
|
1104
1103
|
`workflow_id`. On the orchestrator-agnostic base (`orchestration_mode = "direct"`, the default)
|
|
1105
1104
|
the in-process orchestrator is blocking-only, so `/start` is HONEST: it refuses with a `501`
|
|
1106
1105
|
(`runtime.unsupported`) — use `/execute` — rather than silently blocking and acking.
|
|
1107
|
-
The completion
|
|
1106
|
+
The run's delivery (its results stored, the deployment's completion target, the caller's `callback_urls`) runs on the
|
|
1107
|
+
async path when the run ends.
|
|
1108
1108
|
"""
|
|
1109
1109
|
run_request, extras, body = parsed
|
|
1110
|
+
# Webhooks this runner cannot sign, the caller's or the completion target's, are refused before the method is
|
|
1111
|
+
# fetched or written.
|
|
1112
|
+
ensure_caller_webhooks_signable(
|
|
1113
|
+
caller_urls=start_caller_webhook_urls(callback_urls=extras.callback_urls, pipeline_run_id=extras.pipeline_run_id),
|
|
1114
|
+
)
|
|
1115
|
+
ensure_completion_target_configured()
|
|
1110
1116
|
scopes = _resolve_run_scopes(request, extras=extras)
|
|
1111
1117
|
blob_scope = resolve_blob_scope(request, read_scope=scopes.read_scope)
|
|
1112
1118
|
# The run source is written out only for the synchronous setup phase: `start` builds the
|
|
@@ -1139,7 +1145,6 @@ async def start(
|
|
|
1139
1145
|
callback_urls=extras.callback_urls,
|
|
1140
1146
|
request_id=request_id_of(request),
|
|
1141
1147
|
requested_orchestration_mode=extras.orchestration_mode,
|
|
1142
|
-
callback_problem_view=problem_view_of(request),
|
|
1143
1148
|
)
|
|
1144
1149
|
# The ack plus this server's provenance extension: `(address, tag, commit_sha, tree_digest,
|
|
1145
1150
|
# display_name)` for a `method_ref` run, null otherwise — the caller (and, on hosted, the
|
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
"""The webhooks a run is delivered to: the deployment's own completion target, and the caller's `callback_urls`.
|
|
2
|
+
|
|
3
|
+
The two are different hops and never mix:
|
|
4
|
+
|
|
5
|
+
- **The deployment's completion target** is the operator's: the URL `COMPLETION_CALLBACK_URL` configures, which may name
|
|
6
|
+
the run's id with one `{pipeline_run_id}` placeholder. A `/start` run notifies it with the completion notice, in the
|
|
7
|
+
operator's view, signed with `X-Completion-Signature`, the HMAC-SHA256 of the run's id under
|
|
8
|
+
`COMPLETION_CALLBACK_SECRET`. It never receives a caller's event.
|
|
9
|
+
- **A caller's webhooks** are the `callback_urls` of a `/start` or an `/execute` request. Each receives the signed
|
|
10
|
+
`run.finished` event of the caller-webhook contract (`pipelex.pipe_run.caller_webhook_delivery`), never the completion
|
|
11
|
+
notice nor its signature. The runner signs them under `CALLER_WEBHOOK_SECRET`, so a request carrying any is refused
|
|
12
|
+
with a `422` `pipelex.webhook.secret_not_configured` on a runner whose operator configured none, before anything runs.
|
|
13
|
+
|
|
14
|
+
On `/start`, a `callback_urls` entry equal to the completion target's URL for the run is the deployment's own hop, sent
|
|
15
|
+
there by a host that also forwards it, and is dropped from the caller's: the target is notified once, with its own
|
|
16
|
+
notice. An `/execute` run notifies no completion target, so there every entry is a caller's webhook.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
import hashlib
|
|
20
|
+
import hmac
|
|
21
|
+
from collections.abc import Sequence
|
|
22
|
+
from urllib.parse import quote, unquote, urlsplit
|
|
23
|
+
|
|
24
|
+
from pipelex.errors.problem import ProblemView
|
|
25
|
+
from pipelex.pipe_run.caller_webhook_delivery import CALLER_WEBHOOK_SECRET_ENV, caller_webhook_secret_keys, is_caller_webhook_secret_set
|
|
26
|
+
from pipelex.pipe_run.delivery_assignment import CallerWebhookTarget, DeliveryAssignment, StorageTarget, WebhookTarget
|
|
27
|
+
from pipelex.system.environment import get_optional_env, get_required_env
|
|
28
|
+
|
|
29
|
+
from pipelex_api.exceptions import CallerWebhookSecretNotConfiguredError, RunnerMisconfiguredError
|
|
30
|
+
|
|
31
|
+
COMPLETION_CALLBACK_URL_ENV = "COMPLETION_CALLBACK_URL"
|
|
32
|
+
"""The environment variable naming the deployment's own completion target."""
|
|
33
|
+
|
|
34
|
+
COMPLETION_CALLBACK_SECRET_ENV = "COMPLETION_CALLBACK_SECRET"
|
|
35
|
+
"""The environment variable holding the secret the completion target's `X-Completion-Signature` is computed under."""
|
|
36
|
+
|
|
37
|
+
COMPLETION_SIGNATURE_HEADER = "X-Completion-Signature"
|
|
38
|
+
"""The header carrying the completion target's signature, which no caller webhook ever receives."""
|
|
39
|
+
|
|
40
|
+
PIPELINE_RUN_ID_PLACEHOLDER = "{pipeline_run_id}"
|
|
41
|
+
"""The placeholder `COMPLETION_CALLBACK_URL` may hold once, replaced with the run's id."""
|
|
42
|
+
|
|
43
|
+
_ALLOWED_COMPLETION_SCHEMES = frozenset({"http", "https"})
|
|
44
|
+
|
|
45
|
+
_PLACEHOLDER_SENTINEL = "pipelexrunidplaceholder"
|
|
46
|
+
"""What the placeholder stands as while the template is parsed: letters a host name may hold, so it shows where it lands."""
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def completion_callback_template() -> str | None:
|
|
50
|
+
"""The deployment's completion target as configured, or None when `COMPLETION_CALLBACK_URL` is unset or empty.
|
|
51
|
+
|
|
52
|
+
Read at each use, and once when the server starts, so a malformed value stops the boot.
|
|
53
|
+
|
|
54
|
+
Raises:
|
|
55
|
+
RunnerMisconfiguredError: The value is not an absolute http or https URL naming a host, holds a fragment, holds
|
|
56
|
+
the `{pipeline_run_id}` placeholder more than once, or anywhere but in its path or its query, since a run's id
|
|
57
|
+
may be the caller's choice (a 500 `runtime.misconfigured` naming the variable).
|
|
58
|
+
"""
|
|
59
|
+
configured = get_optional_env(COMPLETION_CALLBACK_URL_ENV)
|
|
60
|
+
if not configured:
|
|
61
|
+
return None
|
|
62
|
+
if configured.count(PIPELINE_RUN_ID_PLACEHOLDER) > 1:
|
|
63
|
+
msg = f"Server configuration error: {COMPLETION_CALLBACK_URL_ENV} may hold the placeholder {PIPELINE_RUN_ID_PLACEHOLDER} once at most."
|
|
64
|
+
raise RunnerMisconfiguredError(msg, component=COMPLETION_CALLBACK_URL_ENV)
|
|
65
|
+
parts = urlsplit(configured.replace(PIPELINE_RUN_ID_PLACEHOLDER, _PLACEHOLDER_SENTINEL))
|
|
66
|
+
if _PLACEHOLDER_SENTINEL in parts.scheme.lower() or _PLACEHOLDER_SENTINEL in parts.netloc.lower():
|
|
67
|
+
# The run's id may be the caller's choice, so it never decides which host the notice, and its signature, go to.
|
|
68
|
+
msg = (
|
|
69
|
+
f"Server configuration error: {COMPLETION_CALLBACK_URL_ENV} may hold the placeholder {PIPELINE_RUN_ID_PLACEHOLDER} "
|
|
70
|
+
"in its path or its query only, never in its scheme, host, port or user."
|
|
71
|
+
)
|
|
72
|
+
raise RunnerMisconfiguredError(msg, component=COMPLETION_CALLBACK_URL_ENV)
|
|
73
|
+
if parts.scheme not in _ALLOWED_COMPLETION_SCHEMES or not parts.hostname or parts.fragment:
|
|
74
|
+
msg = (
|
|
75
|
+
f"Server configuration error: {COMPLETION_CALLBACK_URL_ENV} must be an absolute http or https URL without a fragment, "
|
|
76
|
+
f"such as https://ops.example.com/runs/complete/{PIPELINE_RUN_ID_PLACEHOLDER}."
|
|
77
|
+
)
|
|
78
|
+
raise RunnerMisconfiguredError(msg, component=COMPLETION_CALLBACK_URL_ENV)
|
|
79
|
+
return configured
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def ensure_completion_target_configured() -> None:
|
|
83
|
+
"""Refuse a completion target this server cannot sign or cannot reach: checked at boot, and before a run is set up.
|
|
84
|
+
|
|
85
|
+
Raises:
|
|
86
|
+
RunnerMisconfiguredError: `COMPLETION_CALLBACK_URL` is malformed, or it is set and `COMPLETION_CALLBACK_SECRET`
|
|
87
|
+
holds no secret to sign its notices with (a 500 `runtime.misconfigured` naming the variable to the operator).
|
|
88
|
+
"""
|
|
89
|
+
if completion_callback_template() is None:
|
|
90
|
+
return
|
|
91
|
+
if not get_optional_env(COMPLETION_CALLBACK_SECRET_ENV):
|
|
92
|
+
msg = (
|
|
93
|
+
f"Server configuration error: {COMPLETION_CALLBACK_URL_ENV} is set, and {COMPLETION_CALLBACK_SECRET_ENV} holds no "
|
|
94
|
+
"secret to sign its completion notices with."
|
|
95
|
+
)
|
|
96
|
+
raise RunnerMisconfiguredError(msg, component=COMPLETION_CALLBACK_SECRET_ENV)
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def completion_callback_url(*, pipeline_run_id: str | None) -> str | None:
|
|
100
|
+
"""The completion target's URL for a run, or None when the deployment has none, or names the run's id and it is unknown.
|
|
101
|
+
|
|
102
|
+
The id replaces the placeholder percent-encoded, so an id the caller chose cannot add a path segment or a query.
|
|
103
|
+
"""
|
|
104
|
+
template = completion_callback_template()
|
|
105
|
+
if template is None:
|
|
106
|
+
return None
|
|
107
|
+
if PIPELINE_RUN_ID_PLACEHOLDER not in template:
|
|
108
|
+
return template
|
|
109
|
+
if pipeline_run_id is None:
|
|
110
|
+
return None
|
|
111
|
+
return template.replace(PIPELINE_RUN_ID_PLACEHOLDER, quote(pipeline_run_id, safe=""))
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
def completion_signature(*, pipeline_run_id: str) -> str:
|
|
115
|
+
"""The completion target's `X-Completion-Signature`: the hex HMAC-SHA256 of the run's id under `COMPLETION_CALLBACK_SECRET`.
|
|
116
|
+
|
|
117
|
+
The signer (this server) and the verifier (the deployment's completion receiver) share the secret; only the per-run
|
|
118
|
+
MAC travels.
|
|
119
|
+
|
|
120
|
+
Raises:
|
|
121
|
+
EnvVarNotFoundError: `COMPLETION_CALLBACK_SECRET` is not set (a 500 `pipelex.config.variable_missing`).
|
|
122
|
+
"""
|
|
123
|
+
secret = get_required_env(COMPLETION_CALLBACK_SECRET_ENV)
|
|
124
|
+
return hmac.new(secret.encode("utf-8"), pipeline_run_id.encode("utf-8"), hashlib.sha256).hexdigest()
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
def caller_webhook_urls(*, callback_urls: Sequence[str] | None) -> list[str]:
|
|
128
|
+
"""The caller's webhooks of an `/execute` request: each of its `callback_urls` once, in order.
|
|
129
|
+
|
|
130
|
+
An `/execute` run notifies no completion target, so every URL it lists is a caller's webhook, the completion target's
|
|
131
|
+
own URL included: a host that lists it there is sent the caller's event.
|
|
132
|
+
|
|
133
|
+
Args:
|
|
134
|
+
callback_urls: The request's `callback_urls`, already validated by the request model.
|
|
135
|
+
"""
|
|
136
|
+
if not callback_urls:
|
|
137
|
+
return []
|
|
138
|
+
return list(dict.fromkeys(callback_urls))
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
def start_caller_webhook_urls(*, callback_urls: Sequence[str] | None, pipeline_run_id: str | None) -> list[str]:
|
|
142
|
+
"""The caller's webhooks of a `/start` request: each of its `callback_urls` once, in order, without the completion URL.
|
|
143
|
+
|
|
144
|
+
A `/start` run notifies the deployment's completion target, so a URL equal to the target's URL for the run is the
|
|
145
|
+
host forwarding its own hop, which the target's notice reaches, and never a caller's webhook.
|
|
146
|
+
|
|
147
|
+
Args:
|
|
148
|
+
callback_urls: The request's `callback_urls`, already validated by the request model.
|
|
149
|
+
pipeline_run_id: The run's id, when it is known, which the completion target's URL may name.
|
|
150
|
+
"""
|
|
151
|
+
completion_url = completion_callback_url(pipeline_run_id=pipeline_run_id)
|
|
152
|
+
return [url for url in caller_webhook_urls(callback_urls=callback_urls) if not _is_completion_url(url=url, completion_url=completion_url)]
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def _is_completion_url(*, url: str, completion_url: str | None) -> bool:
|
|
156
|
+
"""Whether a callback URL is the completion target's own, compared as URLs rather than as texts.
|
|
157
|
+
|
|
158
|
+
The target's URL holds the run's id percent-encoded, while a host forwarding it may write the id as it is, so the
|
|
159
|
+
two are compared with their scheme and host in lower case and their path and query decoded: `order 42` and
|
|
160
|
+
`order%2042` name the same hop.
|
|
161
|
+
"""
|
|
162
|
+
if completion_url is None:
|
|
163
|
+
return False
|
|
164
|
+
return _comparable_url(url) == _comparable_url(completion_url)
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
def _comparable_url(url: str) -> tuple[str, str, str, str, str]:
|
|
168
|
+
parts = urlsplit(url)
|
|
169
|
+
return (parts.scheme.lower(), parts.netloc.lower(), unquote(parts.path), unquote(parts.query), unquote(parts.fragment))
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def ensure_caller_webhooks_signable(*, caller_urls: Sequence[str]) -> None:
|
|
173
|
+
"""Refuse a request with caller webhooks this runner cannot sign, before anything is fetched, loaded or run.
|
|
174
|
+
|
|
175
|
+
Raises:
|
|
176
|
+
CallerWebhookSecretNotConfiguredError: `CALLER_WEBHOOK_SECRET` holds no secret (a 422 naming the setting).
|
|
177
|
+
CallerWebhookSecretError: It holds a value that is not a `whsec_` secret (a 500 `runtime.misconfigured`, the
|
|
178
|
+
operator's to fix, naming the variable to the operator alone).
|
|
179
|
+
"""
|
|
180
|
+
if not caller_urls:
|
|
181
|
+
return
|
|
182
|
+
if not is_caller_webhook_secret_set():
|
|
183
|
+
msg = f"The request registers callback URLs, and {CALLER_WEBHOOK_SECRET_ENV} holds no secret to sign their calls with."
|
|
184
|
+
raise CallerWebhookSecretNotConfiguredError(msg, setting=CALLER_WEBHOOK_SECRET_ENV)
|
|
185
|
+
caller_webhook_secret_keys()
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
def start_delivery_assignment(*, caller_urls: Sequence[str], pipeline_run_id: str) -> DeliveryAssignment:
|
|
189
|
+
"""The delivery of a `/start` run: its results stored, the deployment's completion target, then the caller's webhooks.
|
|
190
|
+
|
|
191
|
+
No `key_prefix`: the runtime owns the `results/` leaf, under the run's storage scope.
|
|
192
|
+
|
|
193
|
+
Raises:
|
|
194
|
+
EnvVarNotFoundError: A completion target is configured and `COMPLETION_CALLBACK_SECRET` is not set.
|
|
195
|
+
"""
|
|
196
|
+
completion_url = completion_callback_url(pipeline_run_id=pipeline_run_id)
|
|
197
|
+
webhooks: list[WebhookTarget] = []
|
|
198
|
+
if completion_url is not None:
|
|
199
|
+
# The operator's hop: the completion notice in the operator's view, whoever started the run. Its payload's wire
|
|
200
|
+
# fields are written per delivery by pipelex's DeliveryExecutor, so nothing is injected here.
|
|
201
|
+
webhooks.append(
|
|
202
|
+
WebhookTarget(
|
|
203
|
+
url=completion_url,
|
|
204
|
+
headers={COMPLETION_SIGNATURE_HEADER: completion_signature(pipeline_run_id=pipeline_run_id)},
|
|
205
|
+
problem_view=ProblemView.OPERATOR,
|
|
206
|
+
)
|
|
207
|
+
)
|
|
208
|
+
return DeliveryAssignment(
|
|
209
|
+
storage=StorageTarget(),
|
|
210
|
+
webhooks=webhooks,
|
|
211
|
+
caller_webhooks=[CallerWebhookTarget(url=url) for url in caller_urls if not _is_completion_url(url=url, completion_url=completion_url)],
|
|
212
|
+
)
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
def execute_delivery_assignment(*, caller_urls: Sequence[str], delivery_assignment: DeliveryAssignment | None) -> DeliveryAssignment | None:
|
|
216
|
+
"""The delivery of an `/execute` run: the caller's webhooks, beside whatever an in-process host assigned.
|
|
217
|
+
|
|
218
|
+
An `/execute` run answers with its output, so nothing is stored and no completion target is notified for it: its
|
|
219
|
+
delivery is the caller's webhooks alone, and none at all when it has none.
|
|
220
|
+
"""
|
|
221
|
+
if not caller_urls:
|
|
222
|
+
return delivery_assignment
|
|
223
|
+
base_assignment = delivery_assignment or DeliveryAssignment()
|
|
224
|
+
caller_webhooks = [*base_assignment.caller_webhooks, *(CallerWebhookTarget(url=url) for url in caller_urls)]
|
|
225
|
+
return base_assignment.model_copy(update={"caller_webhooks": caller_webhooks})
|
|
@@ -351,6 +351,24 @@ class StartRequest(RunRequest):
|
|
|
351
351
|
pipeline_run_id: str | None = Field(default=None, max_length=128)
|
|
352
352
|
|
|
353
353
|
|
|
354
|
+
_CALLBACK_URLS_DESCRIPTION = (
|
|
355
|
+
"PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the caller's webhooks. When the run ends, the runner "
|
|
356
|
+
"POSTs the run.finished event to each URL, signed in the Standard Webhooks format under the secret its operator "
|
|
357
|
+
"configures (webhook-id, webhook-timestamp and webhook-signature headers): `type`, `timestamp` (when the run "
|
|
358
|
+
"ended), `attempt`, and `data`, the run as the protocol's status read serves it (`pipeline_run_id`, `status` "
|
|
359
|
+
"`completed` or `failed`, and a failed run's `error`, a problem without `status`). It does not carry the run's "
|
|
360
|
+
"output. Each URL is delivered on its own, with a short retry and no redirect followed, and its failure never "
|
|
361
|
+
"changes the run. A runner whose operator configured no signing secret refuses a request carrying any with a 422 "
|
|
362
|
+
"`pipelex.webhook.secret_not_configured`. http/https only; private, loopback, link-local and cloud-metadata hosts "
|
|
363
|
+
"are rejected."
|
|
364
|
+
)
|
|
365
|
+
|
|
366
|
+
_EXECUTE_PIPELINE_RUN_ID_DESCRIPTION = (
|
|
367
|
+
"PIPELEX-API EXTENSION (not part of the MTHDS Protocol on `/execute`) — the run's id, chosen by the caller, as "
|
|
368
|
+
"`/start` takes it: the run and its webhooks' events carry it, and a run still in flight under the same id "
|
|
369
|
+
"refuses this one with a 409 `pipelex.run.already_exists`. Omit it and the runner generates one."
|
|
370
|
+
)
|
|
371
|
+
|
|
354
372
|
_STORAGE_SCOPE_DESCRIPTION = (
|
|
355
373
|
"PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the host-supplied prefix every object "
|
|
356
374
|
"this run writes lands under. One to three path-safe segments (e.g. `tenant/run` or "
|
|
@@ -448,10 +466,11 @@ def _refused_host_error(*, host: str) -> CallbackUrlRefusedError:
|
|
|
448
466
|
class PipelineApiExtras(BaseModel):
|
|
449
467
|
"""Validates the API-server-only fields on `/execute` and `/start` requests.
|
|
450
468
|
|
|
451
|
-
`pipeline_run_id` is the protocol's optional start arg
|
|
452
|
-
THIS server's extension
|
|
453
|
-
|
|
454
|
-
|
|
469
|
+
`pipeline_run_id` is the protocol's optional start arg, which this server honors
|
|
470
|
+
on `/execute` too; `callback_urls` is THIS server's extension, the caller's
|
|
471
|
+
webhooks (the MTHDS Protocol defines no completion channel — extension args
|
|
472
|
+
are defined and handled by the implementation that owns them). The upstream
|
|
473
|
+
protocol models don't know about `callback_urls`.
|
|
455
474
|
|
|
456
475
|
`storage_scope`, `read_scope` and `analytics_groups` are the host-computed run
|
|
457
476
|
context: data a multi-tenant host knows about its own tenancy and sends in the
|
|
@@ -566,18 +585,7 @@ class PipelexApiStartRequest(StartRequest):
|
|
|
566
585
|
ones it implements itself. Wire validation happens in `PipelineApiExtras`.
|
|
567
586
|
"""
|
|
568
587
|
|
|
569
|
-
callback_urls: list[str] | None = Field(
|
|
570
|
-
default=None,
|
|
571
|
-
description=(
|
|
572
|
-
"PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — completion webhooks. "
|
|
573
|
-
"When the run finishes, the runner POSTs a completion notice to each URL, with an "
|
|
574
|
-
"X-Completion-Signature header holding the HMAC-SHA256 of the run id (not of the body). "
|
|
575
|
-
"The body carries `pipeline_run_id`, `state` (with the legacy `status` alias), `result_url` "
|
|
576
|
-
"(the storage key prefix of the stored results, when results were stored) and `error` on "
|
|
577
|
-
"failure; it does not carry the run's output. http/https only; private, loopback, link-local "
|
|
578
|
-
"and cloud-metadata hosts are rejected."
|
|
579
|
-
),
|
|
580
|
-
)
|
|
588
|
+
callback_urls: list[str] | None = Field(default=None, description=_CALLBACK_URLS_DESCRIPTION)
|
|
581
589
|
orchestration_mode: str | None = Field(default=None, description=_ORCHESTRATION_MODE_DESCRIPTION)
|
|
582
590
|
storage_scope: str | None = Field(default=None, description=_STORAGE_SCOPE_DESCRIPTION)
|
|
583
591
|
read_scope: str | None = Field(default=None, description=_READ_SCOPE_DESCRIPTION)
|
|
@@ -589,10 +597,12 @@ class PipelexApiExecuteRequest(RunRequest):
|
|
|
589
597
|
|
|
590
598
|
Used only to publish the OpenAPI request schema: `/execute` reads the body through the raw
|
|
591
599
|
`Request` (plain JSON, parsed by the route), so FastAPI cannot infer the body type; this model documents the
|
|
592
|
-
extensions the route actually honors (`
|
|
593
|
-
all parsed by `PipelineApiExtras`).
|
|
600
|
+
extensions the route actually honors (`pipeline_run_id`, `callback_urls`, `orchestration_mode`, `storage_scope`,
|
|
601
|
+
`read_scope`, `analytics_groups`, all parsed by `PipelineApiExtras`).
|
|
594
602
|
"""
|
|
595
603
|
|
|
604
|
+
pipeline_run_id: str | None = Field(default=None, max_length=128, description=_EXECUTE_PIPELINE_RUN_ID_DESCRIPTION)
|
|
605
|
+
callback_urls: list[str] | None = Field(default=None, description=_CALLBACK_URLS_DESCRIPTION)
|
|
596
606
|
orchestration_mode: str | None = Field(default=None, description=_ORCHESTRATION_MODE_DESCRIPTION)
|
|
597
607
|
storage_scope: str | None = Field(default=None, description=_STORAGE_SCOPE_DESCRIPTION)
|
|
598
608
|
read_scope: str | None = Field(default=None, description=_READ_SCOPE_DESCRIPTION)
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|