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.

6.6 KB
Raw Blame
"""`/start` is HONEST about fire-and-forget: it acks only when the resolved backend is async-capable.

Fire-and-forget vs blocking is the ENDPOINT's delivery axis, never configured: `/execute` and
`/validate` dispatch with `BLOCKING`, while `/start` dispatches with `FIRE_AND_FORGET`. So `/start`
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 `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).
"""

from fastapi import FastAPI
from fastapi.testclient import TestClient
from pipelex.pipe_run.delivery_assignment import DeliveryAssignment
from pipelex.pipe_run.pipe_job import PipeJob
from pipelex.plugins.orchestrator_registry import OrchestratorRegistry
from pipelex.runtime_bridge.payloads import PipelexPipeDispatchAck, PipelexPipeRunOutput
from pytest_mock import MockerFixture

from pipelex_api.api_config import ApiConfig
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"


class _RecordingStub:
    """Stand-in orchestrator that records its dispatch and returns the configured `workflow_id`.

    `supports_fire_and_forget` is the capability `/start` reads BEFORE dispatch: a True stub models
    an async-capable backend (Temporal) that acks immediately with a `workflow_id`; a False stub
    models a blocking-only backend (`direct`) that `/start` must refuse honestly. `start` records its
    dispatch and returns the `PipelexPipeDispatchAck` (ids only) an async backend acks with; `execute`
    (the blocking arm) is present only to satisfy the protocol — `/start` never drives it.
    """

    def __init__(self, *, workflow_id: str, supports_fire_and_forget: bool) -> None:
        self.calls: list[dict[str, object]] = []
        self._workflow_id = workflow_id
        self.supports_fire_and_forget = supports_fire_and_forget

    async def execute(self, *, pipe_job: PipeJob, delivery_assignment: DeliveryAssignment | None) -> PipelexPipeRunOutput:
        msg = "/start drives the fire-and-forget `start` arm; `execute` must not be reached."
        raise NotImplementedError(msg)

    async def start(self, *, pipe_job: PipeJob, delivery_assignment: DeliveryAssignment | None) -> PipelexPipeDispatchAck:
        self.calls.append(
            {
                "delivery_assignment": delivery_assignment,
                "crate_fingerprint": pipe_job.job_metadata.run_metadata.crate_fingerprint,
            }
        )
        return PipelexPipeDispatchAck(
            pipeline_run_id=pipe_job.job_metadata.run_metadata.pipeline_run_id,
            workflow_id=self._workflow_id,
        )


def _build_client() -> TestClient:
    app = FastAPI()
    app.include_router(api_router, prefix="/v1")
    register_exception_handlers(app)
    return TestClient(app)


def _force_config(mocker: MockerFixture, *, mode: str) -> None:
    config = ApiConfig(orchestration_mode=mode, allow_request_orchestration_mode_override=False)
    mocker.patch(f"{_PIPELINE_NS}.get_api_config", return_value=config)


def _register_stub(mocker: MockerFixture, *, mode: str, stub: _RecordingStub) -> None:
    mocker.patch(f"{_PIPELINE_NS}.get_orchestrator_registry", return_value=OrchestratorRegistry({mode: stub}))


class TestStartCapabilityGate:
    """End-to-end: `POST /start` acks only when the resolved backend can honor fire-and-forget."""

    def test_start_acks_when_orchestrator_is_async_capable(self, mocker: MockerFixture) -> None:
        # A `temporal` deployment whose orchestrator is async-capable: /start drives the fire-and-forget
        # `start` arm and acks 202 with the workflow_id the orchestrator returns immediately.
        _force_config(mocker, mode="temporal")
        stub = _RecordingStub(workflow_id="wf-123", supports_fire_and_forget=True)
        _register_stub(mocker, mode="temporal", stub=stub)

        response = _build_client().post(
            "/v1/start",
            json={"pipe_code": "echo", "mthds_contents": [VALID_MTHDS], "inputs": {"text": "hello"}},
        )

        assert response.status_code == 202, response.text
        body = response.json()
        assert body["state"] == "STARTED"
        assert body["workflow_id"] == "wf-123"
        # /start drives the fire-and-forget `start` arm exactly once — the caller never chooses delivery.
        assert len(stub.calls) == 1
        # The ack reports the crate the dispatched job was built from, which a host records on its run.
        fingerprint = stub.calls[0]["crate_fingerprint"]
        assert isinstance(fingerprint, str)
        assert fingerprint
        assert body["crate_fingerprint"] == fingerprint

    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
        # 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"}},
        )

        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