async-task-api-worker 0.1.0rc2__py3-none-any.whl

async_task_api_worker/testing/_harness.py

@@ -0,0 +1,251 @@
+"""Run a worker's task in memory, through the real engine.
+
+``WorkerHarness`` feeds the engine the exact envelope the API publishes and hands back what the worker published and
+what it did to the delivery, with no broker and no Docker. The engine is the production one (decoding, timeouts,
+retries, error mapping, ack discipline): only the transport is replaced.
+"""
+
+import json
+import weakref
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from itertools import count
+from types import TracebackType
+from typing import Final, Literal, Self
+
+from pydantic_settings import BaseSettings, PydanticBaseSettingsSource
+
+from async_task_api_worker._runtime.engine import Engine
+from async_task_api_worker._runtime.lifecycle import check_time_budget
+from async_task_api_worker.errors import WorkerConfigurationError
+from async_task_api_worker.protocol.envelope import InputRef, decode_envelope
+from async_task_api_worker.protocol.json_types import JsonObject, JsonValue
+from async_task_api_worker.settings import WorkerSettings
+from async_task_api_worker.testing._memory_broker import InMemoryBroker, MemoryDelivery
+from async_task_api_worker.worker import Worker
+
+_KEY_TASK_ID: Final[str] = "task_id"
+_KEY_DATA: Final[str] = "data"
+_MESSAGE_TYPE: Final[str] = "message_type"
+_TERMINAL_TYPES: Final[frozenset[str]] = frozenset({"success", "failure"})
+_TYPE_SUCCESS: Final[str] = "success"
+_TYPE_FAILURE: Final[str] = "failure"
+_TEST_BROKER_URL: Final[str] = "amqp://guest:guest@localhost:5672/"
+# A retry must not make a test wait for the production backoff.
+_NEGLIGIBLE_BACKOFF_S: Final[float] = 0.001
+type MessageName = Literal["started", "progress", "success", "failure"]
+
+
+class Outcome(StrEnum):
+    """What the worker did to the delivery."""
+
+    ACKED = "acked"
+    NACKED_REQUEUE = "nacked_requeue"
+    REJECTED = "rejected"
+
+
+@dataclass(frozen=True, slots=True)
+class TaskRun:
+    """What one submitted message produced."""
+
+    task_id: str | None
+    messages: tuple[JsonObject, ...]
+    raw: tuple[bytes, ...]
+    outcome: Outcome
+
+    @property
+    def message_types(self) -> tuple[str, ...]:
+        """The ``message_type`` of each published message, in order."""
+        return tuple(str(_data(message).get(_MESSAGE_TYPE)) for message in self.messages)
+
+    @property
+    def terminal(self) -> JsonObject | None:
+        """The ``data`` of the success or failure message, ``None`` when there is none."""
+        for message in reversed(self.messages):
+            if _data(message).get(_MESSAGE_TYPE) in _TERMINAL_TYPES:
+                return _data(message)
+        return None
+
+    @property
+    def response(self) -> JsonObject | None:
+        """The result of a successful task."""
+        terminal = self.terminal
+        if terminal is None or terminal.get(_MESSAGE_TYPE) != _TYPE_SUCCESS:
+            return None
+        response = terminal.get("response")
+        return response if isinstance(response, dict) else None
+
+    @property
+    def error(self) -> JsonObject | None:
+        """The ``{"code", "message"}`` of a failed task."""
+        terminal = self.terminal
+        if terminal is None or terminal.get(_MESSAGE_TYPE) != _TYPE_FAILURE:
+            return None
+        error = terminal.get("error_message")
+        return error if isinstance(error, dict) else None
+
+    def assert_succeeded(self) -> None:
+        """Raise ``AssertionError`` unless the task started, succeeded (progress may come between) and was acked."""
+        types = self.message_types
+        if types[:1] != ("started",) or types[-1:] != (_TYPE_SUCCESS,) or self.outcome is not Outcome.ACKED:
+            msg = f"Expected started, success and an ack, got {types} and {self.outcome.value}"
+            raise AssertionError(msg)
+
+    def assert_failed(self, *, code: str | None = None) -> None:
+        """Raise ``AssertionError`` unless the task concluded as a failure (with ``code`` when given) and was acked."""
+        error = self.error
+        if error is None or self.outcome is not Outcome.ACKED:
+            msg = f"Expected a failure and an ack, got {self.message_types} and {self.outcome.value}"
+            raise AssertionError(msg)
+        if code is not None and error.get("code") != code:
+            msg = f"Expected the failure code {code!r}, got {error.get('code')!r}"
+            raise AssertionError(msg)
+
+
+def _data(message: JsonObject) -> JsonObject:
+    data = message.get(_KEY_DATA)
+    return data if isinstance(data, dict) else {}
+
+
+class _IsolatedSettings(WorkerSettings):
+    """The worker settings from the values given and nothing else: never the environment of the test machine."""
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        del settings_cls, env_settings, dotenv_settings, file_secret_settings  # only the values given count
+        return (init_settings,)
+
+
+class WorkerHarness:
+    """Runs a :class:`~async_task_api_worker.Worker` in memory, through the real engine.
+
+    ``settings_overrides`` are :class:`~async_task_api_worker.WorkerSettings` field names (``worker_delivery_limit``,
+    ``worker_task_timeout_s``...). No environment variable is read; the broker settings are placeholders. The defaults
+    are the production ones, except that the retry backoffs are negligible (a millisecond), so that a retry does not
+    make a test wait. The time budget is checked as at startup.
+
+    Use it as ``async with WorkerHarness(worker) as harness`` (or call :meth:`aclose`): the engine's thread pool for
+    ``def`` handlers is released then, and otherwise when the harness is garbage collected.
+    """
+
+    def __init__(self, worker: Worker, *, settings_overrides: Mapping[str, object] | None = None) -> None:
+        values: dict[str, object] = {
+            "broker_url": _TEST_BROKER_URL,
+            "in_queue_name": f"{worker.service}_queue_in",
+            "out_queue_name": f"{worker.service}_queue_out",
+            "worker_retry_backoff_base_s": _NEGLIGIBLE_BACKOFF_S,
+            "worker_retry_backoff_max_s": _NEGLIGIBLE_BACKOFF_S,
+            **(settings_overrides or {}),
+        }
+        unknown = sorted(set(values) - set(WorkerSettings.model_fields))
+        if unknown:
+            # The settings ignore unknown fields, which would hide a typo in a test.
+            msg = f"Unknown settings in settings_overrides: {', '.join(unknown)}"
+            raise WorkerConfigurationError(msg)
+        self.settings: WorkerSettings = _IsolatedSettings.model_validate(values)
+        definition = worker._require_definition()
+        timeout_s = self.settings.worker_task_timeout_s or definition.timeout_s
+        check_time_budget(self.settings, timeout_s)
+        self._broker = InMemoryBroker()
+        self._engine = Engine(
+            definition=definition,
+            service=worker.service,
+            settings=self.settings,
+            publisher=self._broker,
+        )
+        self._finalizer = weakref.finalize(self, self._engine.close)
+        self._task_ids = count(1)
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Release the engine's resources. Safe to call twice."""
+        self._finalizer()
+
+    def fail_next_publish(self, message_type: MessageName | None = None) -> None:
+        """Make the next publish fail, as a broker outage would: of ``message_type``, or of any type."""
+
+        def fault(message: JsonObject) -> Exception | None:
+            published = _data(message).get(_MESSAGE_TYPE)
+            if message_type is not None and published != message_type:
+                return None
+            self._broker.publish_fault = None
+            return ConnectionError("The in-memory broker was told to fail this publish")
+
+        self._broker.publish_fault = fault
+
+    async def submit(
+        self,
+        body: Mapping[str, JsonValue],
+        *,
+        task_id: str | None = None,
+        client_id: str | None = None,
+        input_refs: Mapping[str, InputRef] | None = None,
+        delivery_count: int | None = None,
+        redelivered: bool = False,
+    ) -> TaskRun:
+        """Submit a task as the API would, and wait for the worker to settle the delivery.
+
+        ``delivery_count`` is the broker's ``x-delivery-count``: how many times the message was already handed out
+        (``None`` for a first delivery, and for a queue that has no counter).
+        """
+        identifier = task_id if task_id is not None else f"task-{next(self._task_ids):04d}"
+        data: dict[str, object] = {_MESSAGE_TYPE: "submission", "body": dict(body)}
+        context: dict[str, object] = {}
+        if client_id is not None:
+            context["client_id"] = client_id
+        if input_refs:
+            context["input_refs"] = {name: ref.model_dump(mode="json") for name, ref in input_refs.items()}
+        if context:
+            data["context"] = context
+        raw = json.dumps({_KEY_TASK_ID: identifier, _KEY_DATA: data}).encode()
+        return await self.submit_raw(raw, delivery_count=delivery_count, redelivered=redelivered)
+
+    async def submit_raw(
+        self,
+        raw: bytes,
+        *,
+        delivery_count: int | None = None,
+        redelivered: bool = False,
+    ) -> TaskRun:
+        """Deliver ``raw`` bytes as they are (a poison message, say), and wait for the delivery to be settled.
+
+        ``TaskRun.task_id`` is the one in the envelope when the bytes carry one, otherwise ``None``.
+        """
+        already_published = len(self._broker.published)
+        delivery = self._broker.delivery(raw, delivery_count=delivery_count, redelivered=redelivered)
+        await self._engine.process_delivery(delivery)
+        published = tuple(self._broker.published[already_published:])
+        return TaskRun(
+            task_id=decode_envelope(raw).task_id,
+            messages=tuple(json.loads(body) for body in published),
+            raw=published,
+            outcome=_outcome_of(delivery),
+        )
+
+
+def _outcome_of(delivery: MemoryDelivery) -> Outcome:
+    """What the worker did to the delivery. A delivery must be settled exactly once: anything else is an engine bug."""
+    if delivery.settlements != 1:
+        msg = f"The delivery was settled {delivery.settlements} times (acks: {delivery.ack_count}), expected once"
+        raise AssertionError(msg)
+    if delivery.ack_count:
+        return Outcome.ACKED
+    return Outcome.NACKED_REQUEUE if delivery.nack_requeue_values[0] else Outcome.REJECTED

async_task_api_worker/testing/_memory_broker.py

@@ -0,0 +1,162 @@
+"""An in-memory broker implementing the runtime transport, with delivery counts and fault injection."""
+
+import asyncio
+import json
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from enum import StrEnum
+
+from async_task_api_worker._runtime.transport import OnDelivery, Publisher, TransportUnavailableError
+from async_task_api_worker.protocol.json_types import JsonObject
+
+
+class EventKind(StrEnum):
+    PUBLISH = "publish"
+    ACK = "ack"
+    NACK = "nack"
+
+
+@dataclass(frozen=True, slots=True)
+class BrokerEvent:
+    """One thing that happened on the broker, in order. ``body`` is set for a publish, ``requeue`` for a nack."""
+
+    kind: EventKind
+    body: bytes | None = None
+    requeue: bool | None = None
+
+
+type PublishFault = Callable[[JsonObject], Exception | None]
+
+
+class MemoryDelivery:
+    """A delivery that records its ack and nack on the broker's ordered event log."""
+
+    def __init__(self, broker: "InMemoryBroker", body: bytes, *, delivery_count: int | None, redelivered: bool) -> None:
+        self._broker = broker
+        self._body = body
+        self._delivery_count = delivery_count
+        self._redelivered = redelivered
+        self.ack_count = 0
+        self.nack_requeue_values: list[bool] = []
+
+    @property
+    def body(self) -> bytes:
+        return self._body
+
+    @property
+    def delivery_count(self) -> int | None:
+        return self._delivery_count
+
+    @property
+    def redelivered(self) -> bool:
+        return self._redelivered
+
+    @property
+    def nack_count(self) -> int:
+        return len(self.nack_requeue_values)
+
+    @property
+    def settlements(self) -> int:
+        """Acks plus nacks: exactly one for a delivery the engine has finished with."""
+        return self.ack_count + self.nack_count
+
+    async def ack(self) -> None:
+        self.ack_count += 1
+        self._broker.events.append(BrokerEvent(EventKind.ACK))
+        if self._broker.ack_error is not None:
+            raise self._broker.ack_error
+
+    async def nack(self, *, requeue: bool) -> None:
+        self.nack_requeue_values.append(requeue)
+        self._broker.events.append(BrokerEvent(EventKind.NACK, requeue=requeue))
+        if self._broker.nack_hook is not None:
+            await self._broker.nack_hook()
+        if self._broker.nack_error is not None:
+            raise self._broker.nack_error
+
+
+class InMemoryBroker:
+    """Publisher and delivery factory. ``events`` is the ordered log of publishes, acks and nacks."""
+
+    def __init__(self) -> None:
+        self.events: list[BrokerEvent] = []
+        self.publish_fault: PublishFault | None = None
+        self.ack_error: Exception | None = None
+        self.nack_error: Exception | None = None
+        self.nack_hook: Callable[[], Awaitable[None]] | None = None
+
+    def delivery(self, body: bytes, *, delivery_count: int | None = None, redelivered: bool = False) -> MemoryDelivery:
+        return MemoryDelivery(self, body, delivery_count=delivery_count, redelivered=redelivered)
+
+    async def publish(self, body: bytes) -> None:
+        if self.publish_fault is not None:
+            error = self.publish_fault(json.loads(body))
+            if error is not None:
+                raise error
+        self.events.append(BrokerEvent(EventKind.PUBLISH, body=body))
+
+    @property
+    def published(self) -> list[bytes]:
+        return [event.body for event in self.events if event.kind is EventKind.PUBLISH and event.body is not None]
+
+    def published_messages(self) -> list[JsonObject]:
+        """Published messages, decoded."""
+        return [json.loads(body) for body in self.published]
+
+
+class MemoryTransport:
+    """A transport on an :class:`InMemoryBroker`: ``deliver`` feeds the consumer like the real broker would."""
+
+    def __init__(self, broker: InMemoryBroker | None = None) -> None:
+        self.broker = broker or InMemoryBroker()
+        self.unavailable_attempts = 0
+        self.start_attempts = 0
+        self.consuming = False
+        self.started = False
+        self.closed = False
+        self.calls: list[str] = []
+        self._on_delivery: OnDelivery | None = None
+
+    @property
+    def publisher(self) -> Publisher:
+        return self.broker
+
+    async def start(self, on_delivery: OnDelivery) -> None:
+        self.start_attempts += 1
+        if self.unavailable_attempts > 0:
+            self.unavailable_attempts -= 1
+            msg = "The broker is unreachable"
+            raise TransportUnavailableError(msg)
+        self._on_delivery = on_delivery
+        self.consuming = True
+        self.started = True
+        self.calls.append("start")
+
+    async def ping(self, timeout_s: float) -> bool:
+        del timeout_s
+        return self.started and not self.closed
+
+    async def stop_consuming(self) -> None:
+        self.consuming = False
+        # Like the real broker, the cancel is a round trip: other tasks run meanwhile.
+        await asyncio.sleep(0)
+        self.calls.append("stop_consuming")
+
+    async def close(self) -> None:
+        self.closed = True
+        self.calls.append("close")
+
+    def deliver(
+        self,
+        body: bytes,
+        *,
+        delivery_count: int | None = None,
+        redelivered: bool = False,
+    ) -> MemoryDelivery:
+        """Hand a new delivery to the consumer. Raises when the transport is not consuming."""
+        if not self.consuming or self._on_delivery is None:
+            msg = "The transport is not consuming"
+            raise RuntimeError(msg)
+        delivery = self.broker.delivery(body, delivery_count=delivery_count, redelivered=redelivered)
+        self._on_delivery(delivery)
+        return delivery

async_task_api_worker/worker.py

@@ -0,0 +1,254 @@
+"""``Worker``: declares one task and its models. The runtime that consumes the queue is built from it."""
+
+import asyncio
+import inspect
+import math
+import re
+import time
+import typing
+from collections.abc import Awaitable, Callable
+from typing import Final, NoReturn
+
+from pydantic import BaseModel
+
+from async_task_api_worker._runtime.engine import AsyncHandler, Engine, SyncHandler, TaskDefinition
+from async_task_api_worker._runtime.lifecycle import Lifecycle, run_blocking
+from async_task_api_worker._runtime.observer import RuntimeObserver
+from async_task_api_worker._runtime.progress import Clock, Sleep
+from async_task_api_worker._runtime.transport import Publisher, Transport
+from async_task_api_worker.context import SyncTaskContext, TaskContext
+from async_task_api_worker.errors import WorkerDefinitionError
+from async_task_api_worker.observability.health import Component
+from async_task_api_worker.protocol.messages import MessageEncoder
+from async_task_api_worker.settings import WorkerSettings
+
+_SERVICE_PATTERN: Final[re.Pattern[str]] = re.compile(r"^[a-z][a-z0-9-]*$")
+_PROBE_PATTERN: Final[re.Pattern[str]] = re.compile(r"^[a-z][a-z0-9_]*$")
+_RESERVED_PROBE_NAMES: Final[frozenset[str]] = frozenset(component.value for component in Component)
+_HANDLER_PARAMETERS: Final[int] = 2
+_RETURN_KEY: Final[str] = "return"
+_JSON_SCHEMA_TYPE_KEY: Final[str] = "type"
+_JSON_SCHEMA_OBJECT: Final[str] = "object"
+_POSITIONAL_KINDS: Final[frozenset[int]] = frozenset(
+    {inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD},
+)
+
+type Hook = Callable[[], Awaitable[None]]
+
+
+def _model_annotation(annotation: object, role: str) -> type[BaseModel]:
+    if not (isinstance(annotation, type) and issubclass(annotation, BaseModel)):
+        msg = f"The handler {role} must be annotated with a pydantic BaseModel subclass, got {annotation!r}"
+        raise WorkerDefinitionError(msg)
+    return annotation
+
+
+def _build_definition(handler: Callable[..., object], timeout_s: float) -> TaskDefinition:
+    """Read the input and output models from the handler's annotations."""
+    parameters = list(inspect.signature(handler).parameters.values())
+    if len(parameters) != _HANDLER_PARAMETERS or any(p.kind not in _POSITIONAL_KINDS for p in parameters):
+        msg = "A task handler takes exactly two positional parameters: the input model and the task context"
+        raise WorkerDefinitionError(msg)
+    try:
+        hints = typing.get_type_hints(handler)
+    except Exception as error:
+        msg = f"The handler annotations cannot be resolved: {error}"
+        raise WorkerDefinitionError(msg) from error
+    input_name, context_name = (parameter.name for parameter in parameters)
+    for name in (input_name, context_name, _RETURN_KEY):
+        if name not in hints:
+            msg = f"The handler is missing the annotation of {name!r}"
+            raise WorkerDefinitionError(msg)
+
+    is_async = inspect.iscoroutinefunction(handler)
+    expected_context = TaskContext if is_async else SyncTaskContext
+    if hints[context_name] is not expected_context:
+        kind = "async def" if is_async else "def"
+        msg = (
+            f"A {kind} handler takes exactly a {expected_context.__name__} as second parameter "
+            f"(an exact annotation, no subclass or wrapper), got {hints[context_name]!r}"
+        )
+        raise WorkerDefinitionError(msg)
+
+    input_model = _model_annotation(hints[input_name], "input")
+    output_model = _model_annotation(hints[_RETURN_KEY], "return value")
+    try:
+        output_type = output_model.model_json_schema().get(_JSON_SCHEMA_TYPE_KEY)
+    except Exception as error:
+        msg = f"The JSON schema of {output_model.__name__} cannot be generated: {error}"
+        raise WorkerDefinitionError(msg) from error
+    if output_type != _JSON_SCHEMA_OBJECT:
+        msg = f"The output model {output_model.__name__} must have a JSON object schema, got {output_type!r}"
+        raise WorkerDefinitionError(msg)
+    return TaskDefinition(
+        handler=typing.cast("AsyncHandler | SyncHandler", handler),
+        is_async=is_async,
+        input_model=input_model,
+        output_model=output_model,
+        timeout_s=timeout_s,
+    )
+
+
+def _require_coroutine_function(function: Callable[..., object], role: str) -> None:
+    if not inspect.iscoroutinefunction(function):
+        msg = f"The {role} must be an async def function, got {function!r}"
+        raise WorkerDefinitionError(msg)
+
+
+class Worker:
+    """One service, one task.
+
+    ``settings=None`` reads :class:`WorkerSettings` from the environment the first time it is needed, so that
+    importing the module that declares the worker never fails on a missing variable.
+    """
+
+    def __init__(self, service: str, *, settings: WorkerSettings | None = None) -> None:
+        if not _SERVICE_PATTERN.fullmatch(service):
+            msg = f"Invalid service name {service!r}: expected {_SERVICE_PATTERN.pattern}"
+            raise WorkerDefinitionError(msg)
+        self._service = service
+        self._settings = settings
+        self._definition: TaskDefinition | None = None
+        self._probes: dict[str, Hook] = {}
+        self._startup_hooks: list[Hook] = []
+        self._shutdown_hooks: list[Hook] = []
+
+    @property
+    def service(self) -> str:
+        return self._service
+
+    @property
+    def settings(self) -> WorkerSettings:
+        if self._settings is None:
+            self._settings = WorkerSettings()
+        return self._settings
+
+    def task[F: Callable[..., object]](self, *, timeout: float) -> Callable[[F], F]:
+        """Declare the task handler: ``async def`` runs on the loop, ``def`` in the SDK thread pool.
+
+        The second parameter must be annotated exactly ``TaskContext`` (``async def``) or ``SyncTaskContext``
+        (``def``): the check is an identity one, a subclass or a wrapper such as ``Annotated`` is rejected.
+
+        The input and output models are read from the annotations (``def handle(inp: In, ctx: TaskContext) -> Out``).
+        ``timeout`` is in seconds; ``WORKER_TASK_TIMEOUT_S`` overrides it. The function is returned unchanged.
+        """
+        if not math.isfinite(timeout) or timeout <= 0:
+            msg = f"timeout must be a positive number of seconds, got {timeout!r}"
+            raise WorkerDefinitionError(msg)
+
+        def decorator(handler: F) -> F:
+            if self._definition is not None:
+                msg = "A worker declares exactly one task"
+                raise WorkerDefinitionError(msg)
+            self._definition = _build_definition(handler, timeout)
+            return handler
+
+        return decorator
+
+    def readiness_probe(self, name: str) -> Callable[[Hook], Hook]:
+        """Register a dependency probe: it raises to signal "not ready"."""
+        if not _PROBE_PATTERN.fullmatch(name) or name in _RESERVED_PROBE_NAMES:
+            reserved = ", ".join(sorted(_RESERVED_PROBE_NAMES))
+            msg = f"Invalid probe name {name!r}: expected {_PROBE_PATTERN.pattern}, and not one of: {reserved}"
+            raise WorkerDefinitionError(msg)
+
+        def decorator(probe: Hook) -> Hook:
+            _require_coroutine_function(probe, f"probe {name!r}")
+            if name in self._probes:
+                msg = f"Probe {name!r} is already registered"
+                raise WorkerDefinitionError(msg)
+            self._probes[name] = probe
+            return probe
+
+        return decorator
+
+    def on_startup(self, hook: Hook) -> Hook:
+        """Run before consuming, in registration order."""
+        _require_coroutine_function(hook, "startup hook")
+        self._startup_hooks.append(hook)
+        return hook
+
+    def on_shutdown(self, hook: Hook) -> Hook:
+        """Run after the drain, in reverse registration order."""
+        _require_coroutine_function(hook, "shutdown hook")
+        self._shutdown_hooks.append(hook)
+        return hook
+
+    @property
+    def input_model(self) -> type[BaseModel]:
+        return self._require_definition().input_model
+
+    @property
+    def output_model(self) -> type[BaseModel]:
+        return self._require_definition().output_model
+
+    def run(self) -> NoReturn:
+        """Serve until SIGTERM or SIGINT, then exit: code 0 after a clean drain, 2 on a configuration error.
+
+        With ``WORKER_MODE=job`` it also exits 0 once ``WORKER_JOB_MAX_TASKS`` deliveries are settled, or when none
+        arrives within ``WORKER_JOB_IDLE_TIMEOUT_S``.
+        """
+        raise SystemExit(run_blocking(self))
+
+    async def serve(self) -> None:
+        """Serve until SIGTERM or SIGINT (or, in job mode, until the job is done), for embedding: returns after a drain.
+
+        Reads and validates the settings first, so a bad configuration fails before the first delivery. The probe and
+        metrics server runs on ``HEALTH_CHECK_HOST:HEALTH_CHECK_PORT`` for as long as it serves, embedded or not.
+        """
+        await self._serve_report()
+
+    async def _serve_report(
+        self,
+        transport: Transport | None = None,
+        *,
+        serve_probes: bool | None = None,
+    ) -> tuple[str, ...]:
+        """Serve like :meth:`serve`, and return the task ids of sync handlers still running after the drain.
+
+        ``transport`` is for the tests: the broker transport is built from the settings by default, and the probe
+        server then runs (``serve_probes`` overrides it, so that a test never binds the probe port).
+        """
+        settings = self.settings
+        if serve_probes is None:
+            serve_probes = transport is None
+        if transport is None:
+            from async_task_api_worker._runtime.amqp_transport import AmqpTransport  # noqa: PLC0415
+
+            transport = AmqpTransport(
+                url=settings.broker_url.get_secret_value(),
+                in_queue=settings.in_queue_name,
+                out_queue=settings.out_queue_name,
+                prefetch=settings.prefetch,
+                reconnect_interval_s=settings.worker_broker_reconnect_interval_s,
+            )
+        lifecycle = Lifecycle(self, transport, serve_probes=serve_probes)
+        await lifecycle.run()
+        return lifecycle.overrunning
+
+    def _require_definition(self) -> TaskDefinition:
+        if self._definition is None:
+            msg = "No task declared: decorate the handler with @worker.task(timeout=...)"
+            raise WorkerDefinitionError(msg)
+        return self._definition
+
+    def _create_engine(
+        self,
+        publisher: Publisher,
+        *,
+        encoder: MessageEncoder | None = None,
+        observer: RuntimeObserver | None = None,
+        clock: Clock | None = None,
+        sleep: Sleep | None = None,
+    ) -> Engine:
+        """Build the engine for this worker. Internal: used by the runtime and the conformance kit."""
+        return Engine(
+            definition=self._require_definition(),
+            service=self._service,
+            settings=self.settings,
+            publisher=publisher,
+            encoder=encoder,
+            observer=observer,
+            clock=clock or time.monotonic,
+            sleep=sleep or asyncio.sleep,
+        )