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/Execute-request-id-seam · L-260927-135cc1 (#1285)
Louis Choquelab3fc0ca66a0
diff --git a/.badges/tests.json b/.badges/tests.jsonindex 4f5e63aff..a789a0c05 100644--- a/.badges/tests.json+++ b/.badges/tests.json@@ -1,7 +1,7 @@{"schemaVersion": 1,"label": "tests",- "message": "12752",+ "message": "12781","color": "blue","cacheSeconds": 300}diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ad4958291..afa030e1d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,7 @@- **`PipelexKernel.log_context()` and `JobMetadata.log_context()`**: `JobMetadata.log_context()` binds a job's `request_id`, `pipeline_run_id` and `pipe_run_id` onto the log context in one call, and `PipelexKernel.log_context()` binds a kernel run's `request_id` and `pipeline_run_id`, which a host wraps its run in so the lines it emits between kernel calls name the run.- **`PipelexKernel.make` takes `request_id` and `pipeline_run_id`**: a kernel-driven run can now carry the inbound request id a hosted deployment filters its logs on, and name itself with an id the host chooses. A host inside a replay-based executor passes a `pipeline_run_id` or a trace context, since the default `uuid4` changes on every replay; a trace context and a `pipeline_run_id` that disagree, or an empty `pipeline_run_id`, raise `ValueError`.+- **`PipelexMTHDSProtocol.execute` takes `request_id`**: a host running `execute` passes the inbound request id, which the run's `RunMetadata` carries, so the log lines of a run dispatched to a distributed orchestrator's workers carry `request_id` as a direct run's do. A value that is not one to 128 printable ASCII characters is refused with a `ValueError` before the run is set up, where it used to surface as a `PipeExecutionError` blaming the caller's input; the constraint is stated once, as `validate_request_id` in `pipelex.system.job_metadata`, which `RunMetadata` applies too.### Fixeddiff --git a/docs/tools/logging.md b/docs/tools/logging.mdindex d194494a1..66e8bda81 100644--- a/docs/tools/logging.md+++ b/docs/tools/logging.md@@ -109,7 +109,7 @@ The identifiers travel in the payload, and the contextvar is in-process plumbing- **Every pipe run**: `live_run_pipe` mints the pipe run's id and binds `pipe_run_id` around the whole of the run, the line announcing it, its span lines and its failure included, so every record emitted during a pipe's run names the run it belongs to, a nested pipe rebinding its own and the outer id coming back when it returns, however it returns. A pipe lifted for absent optional inputs does not run and has no id: its skip line carries the enclosing binding, the parent pipe's or none. This is the binding every orchestration shares, direct or distributed.- **Every kernel step**: each kernel function that takes a `job_metadata` — `run_llm_text`, `run_llm_object`, `generate_object_content`, `run_extract`, `run_search` and `run_img_gen` — binds it for the length of its call, so a program driving the kernel directly gets lines naming the run and the step. Inside the interpreter the operator hands the kernel the `pipe_run_id` that `live_run_pipe` already bound, so this nested binding changes nothing there.- **A kernel-driven run**: the host wraps its run in `PipelexKernel.log_context()`, which binds `request_id` and `pipeline_run_id` and no step. The kernel has no run boundary of its own, so this binding is the host's, and each step's binding merges over it. See [The Pipelex Kernel](../under-the-hood/pipelex-kernel.md#the-log-context).-- **An API request**: the runner's request middleware is where `request_id` is bound from the inbound request, for the request's duration.+- **An API request**: the runner's request middleware is where `request_id` is bound from the inbound request, for the request's duration. The runner then puts the same id on the run's `RunMetadata`, by passing it as `request_id` to `PipelexMTHDSProtocol.execute` or to `pipeline_run_setup`, so the payload carries it to whichever process runs the pipes, and each of them binds it from there.- **A durable-execution activity or workflow**: the entry is where the identifiers are bound from the payload the orchestrator handed it.The last two are the runner's and the orchestration plugin's to bind, beside the payload they read. The runtime provides `log.context` for any identifiers, and `JobMetadata.log_context()` to bind the three a `JobMetadata` carries in one call.diff --git a/pipelex/pipeline/runner.py b/pipelex/pipeline/runner.pyindex fb1be9e42..6aa47dc3a 100644--- a/pipelex/pipeline/runner.py+++ b/pipelex/pipeline/runner.py@@ -32,6 +32,7 @@ from pipelex.pipeline.pipeline_run_setup import pipeline_run_setupfrom pipelex.pipeline.validate_in_process import validate_bundles_in_processfrom pipelex.runtime_hub import get_report_delegate, get_telemetry_managerfrom pipelex.system.caller_identity import CallerIdentity+from pipelex.system.job_metadata import validate_request_idfrom pipelex.system.storage_scope import LOCAL_STORAGE_SCOPE, LOCAL_USER_IDfrom pipelex.system.telemetry.events import EventName, EventProperty, Outcomefrom pipelex.tools.typing.pydantic_utils import format_pydantic_validation_error@@ -169,6 +170,7 @@ class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):dynamic_output_concept_ref: str | None = None,extra: dict[str, Any] | None = None,delivery_assignment: DeliveryAssignment | None = None,+ request_id: str | None = None,) -> PipelexRunResultExecute:"""Execute a pipeline and wait for its completion.@@ -204,6 +206,14 @@ class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):delivery_assignment:Internal delivery hook used by the API layer (in-process, not awire extension).+ request_id:+ The inbound request id the host is serving, put on the run's+ ``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.Returns:-------@@ -217,6 +227,10 @@ class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):if extra:msg = f"The local runtime defines no extension args; got {sorted(extra)}."raise PipelineRequestError(msg)+ # Refused here, before the `try`: `RunMetadata` would refuse it inside the setup, where the+ # `ValidationError` arm below would report the host's bug as the caller's invalid input.+ if request_id is not None:+ validate_request_id(value=request_id)created_at = datetime.now(UTC).isoformat()@@ -254,6 +268,7 @@ class PipelexMTHDSProtocol(MTHDSProtocol["PipeOutput"]):extras=self.extras,inputs_base_dir=self.inputs_base_dir,library_dirs_are_callers=self.library_dirs_are_callers,+ request_id=request_id,)effective_pipe_run = self._pipe_run or get_pipe_run()pipe_output = await effective_pipe_run.run(pipe_job, delivery_assignment=delivery_assignment)diff --git a/pipelex/system/job_metadata.py b/pipelex/system/job_metadata.pyindex 5e3942dbc..a10b9f88e 100644--- a/pipelex/system/job_metadata.py+++ b/pipelex/system/job_metadata.py@@ -1,3 +1,4 @@+import refrom contextlib import AbstractContextManagerfrom datetime import datetimefrom enum import StrEnum@@ -11,6 +12,32 @@ from pipelex.system.telemetry.otel_context import OtelContextfrom pipelex.system.trace_context import TraceContextfrom pipelex.tools.log.log_context import LogContext, bind_log_context+REQUEST_ID_MAX_LENGTH = 128+REQUEST_ID_PATTERN = re.compile(r"[\x20-\x7E]+")+++def validate_request_id(*, value: str) -> str:+ """Return `value` if it is a usable inbound request id, else raise `ValueError`.++ 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.++ Raises:+ ValueError: the value is empty, longer than `REQUEST_ID_MAX_LENGTH`, or holds a+ character outside printable ASCII.+ """+ 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 ValueError(msg)+ # `fullmatch`, not `match` with a trailing `$`, which would admit one final newline.+ if not REQUEST_ID_PATTERN.fullmatch(value):+ 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."+ )+ raise ValueError(msg)+ return value+class SpecialPipelineId(StrEnum):"""The reserved `pipeline_run_id` values, for runs that have no id of their own.@@ -115,10 +142,11 @@ 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 (printable ASCII only, max 128- # chars) so an unsanitized upstream value cannot inject newlines or control- # characters into the log lines or ``ErrorReport`` envelopes that quote it.- request_id: str | None = Field(default=None, max_length=128, pattern=r"^[\x20-\x7E]+$")+ # 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 ``ErrorReport``+ # envelopes that quote it.+ request_id: str | None = None# The opaque labels the host attaches to this run. Never read by name;# telemetry forwards the whole mapping as the groups of each capture@@ -148,6 +176,14 @@ class RunMetadata(BaseModel):"""return validate_storage_scope(value=value)+ @field_validator("request_id")+ @classmethod+ def _validate_request_id(cls, value: str | None) -> str | None:+ """Refuse a request id that would forge a log line, at construction."""+ if value is None:+ return None+ return validate_request_id(value=value)+@field_validator("extras")@classmethoddef _validate_run_extras(cls, value: dict[str, str]) -> dict[str, str]:diff --git a/tests/integration/pipelex/pipeline/test_data.py b/tests/integration/pipelex/pipeline/test_data.pyindex f796bfd02..a621f819c 100644--- a/tests/integration/pipelex/pipeline/test_data.py+++ b/tests/integration/pipelex/pipeline/test_data.py@@ -393,3 +393,21 @@ inputs = { tide_times = "Text" }output = "Text"prompt = "Write a short notice for the harbour board from these tide times: $tide_times""""+++class ExecuteRequestIdTestData:+ """A bundle that runs without inference, to see which job `execute` hands its `PipeRunProtocol`."""++ REQUEST_ID: ClassVar[str] = "req-execute-7f3a"++ COMPOSE_MTHDS: ClassVar[str] = """+domain = "execute_request_id"+description = "A single compose step, which runs without calling a model"++[pipe.restate]+type = "PipeCompose"+description = "Restate the topic"+inputs = { topic = "Text" }+output = "Text"+template = "About {{ topic }}"+"""diff --git a/tests/integration/pipelex/pipeline/test_execute_request_id.py b/tests/integration/pipelex/pipeline/test_execute_request_id.pynew file mode 100644index 000000000..89089590b--- /dev/null+++ b/tests/integration/pipelex/pipeline/test_execute_request_id.py@@ -0,0 +1,72 @@+from __future__ import annotations++from typing import TYPE_CHECKING++import pytest+from typing_extensions import override++from pipelex.interpreter_hub import get_pipe_run+from pipelex.pipe_run.pipe_run_protocol import PipeRunProtocol+from pipelex.pipeline.runner import PipelexMTHDSProtocol+from tests.integration.pipelex.pipeline.test_data import ExecuteRequestIdTestData++if TYPE_CHECKING:+ from pipelex.core.pipes.pipe_output import PipeOutput+ from pipelex.pipe_run.delivery_assignment import DeliveryAssignment+ from pipelex.pipe_run.pipe_job import PipeJob+++class _RecordingPipeRun(PipeRunProtocol):+ """Record the job `execute` hands over, then run it as the process's own `PipeRun` would."""++ def __init__(self) -> None:+ self.pipe_jobs: list[PipeJob] = []++ @override+ async def run(self, pipe_job: PipeJob, *, delivery_assignment: DeliveryAssignment | None = None) -> PipeOutput:+ self.pipe_jobs.append(pipe_job)+ return await get_pipe_run().run(pipe_job, delivery_assignment=delivery_assignment)++[email protected](loop_scope="class")+class TestExecuteRequestId:+ async def test_request_id_rides_the_job_handed_to_the_pipe_run(self) -> None:+ """The host's inbound request id reaches the run metadata a distributed worker binds its log context from."""+ pipe_run = _RecordingPipeRun()+ runner = PipelexMTHDSProtocol(pipe_run=pipe_run)++ await runner.execute(+ pipe_code="restate",+ mthds_contents=[ExecuteRequestIdTestData.COMPOSE_MTHDS],+ inputs={"topic": "cats"},+ request_id=ExecuteRequestIdTestData.REQUEST_ID,+ )++ assert len(pipe_run.pipe_jobs) == 1+ assert pipe_run.pipe_jobs[0].job_metadata.run_metadata.request_id == ExecuteRequestIdTestData.REQUEST_ID++ async def test_omitted_request_id_leaves_none(self) -> None:+ pipe_run = _RecordingPipeRun()+ runner = PipelexMTHDSProtocol(pipe_run=pipe_run)++ await runner.execute(pipe_code="restate", mthds_contents=[ExecuteRequestIdTestData.COMPOSE_MTHDS], inputs={"topic": "cats"})++ assert len(pipe_run.pipe_jobs) == 1+ assert pipe_run.pipe_jobs[0].job_metadata.run_metadata.request_id is None++ @pytest.mark.parametrize("bad_request_id", ["forged\nline", "", "x" * 129])+ async def test_malformed_request_id_is_the_hosts_bug_refused_before_the_run(self, bad_request_id: str) -> None:+ """Refused as a `ValueError`, not relabelled as the caller's invalid input, and no job is set up."""+ pipe_run = _RecordingPipeRun()+ runner = PipelexMTHDSProtocol(pipe_run=pipe_run)++ with pytest.raises(ValueError, match="Invalid request_id") as exc_info:+ await runner.execute(+ pipe_code="restate",+ mthds_contents=[ExecuteRequestIdTestData.COMPOSE_MTHDS],+ inputs={"topic": "cats"},+ request_id=bad_request_id,+ )++ assert type(exc_info.value) is ValueError+ assert pipe_run.pipe_jobs == []diff --git a/tests/unit/pipelex/system/test_job_metadata_request_id.py b/tests/unit/pipelex/system/test_job_metadata_request_id.pyindex e78411139..30b993051 100644--- a/tests/unit/pipelex/system/test_job_metadata_request_id.py+++ b/tests/unit/pipelex/system/test_job_metadata_request_id.py@@ -35,6 +35,8 @@ class TestJobMetadataRequestId:"bad_request_id",["abc\ndef", # newline (CRLF log injection)+ "abc\n", # trailing newline (a `$` anchor under `re.match` would admit it)+ "", # empty"abc\rdef", # carriage return"abc\x1b[31mfake", # ANSI escape (log forgery)"abc\x00def", # NUL byte