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

async_task_api_worker/protocol/envelope.py

@@ -0,0 +1,103 @@
+"""Inbound side of the protocol: the task envelope the API publishes on ``<service>_queue_in``.
+
+Parsing only. Every model ignores unknown fields so that additive protocol changes never break a worker.
+"""
+
+import json
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Final
+
+from pydantic import AnyHttpUrl, BaseModel, ConfigDict, Field, ValidationError
+
+from async_task_api_worker.protocol.json_types import JsonValue
+
+_KEY_TASK_ID: Final[str] = "task_id"
+_KEY_DATA: Final[str] = "data"
+_KEY_BODY: Final[str] = "body"
+_DEFAULT_MESSAGE_TYPE: Final[str] = "submission"
+
+
+class InputRef(BaseModel):
+    """A presigned input the API hands to the worker (optional; ignored when absent)."""
+
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    url: AnyHttpUrl
+    size_bytes: int | None = Field(default=None, ge=0)
+    content_type: str | None = None
+
+
+class EnvelopeContext(BaseModel):
+    """``data.context``: optional, absent unless the API provides it."""
+
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    client_id: str | None = None
+    input_refs: dict[str, InputRef] = Field(default_factory=dict)
+
+
+class SubmissionData(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    # Optional in the protocol; defaults to ``submission``. A missing value must not turn a task into poison.
+    message_type: str = _DEFAULT_MESSAGE_TYPE
+    body: dict[str, JsonValue]
+    context: EnvelopeContext | None = None
+
+
+class TaskEnvelope(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    task_id: str = Field(min_length=1)
+    data: SubmissionData
+
+
+class PoisonReason(StrEnum):
+    """Why a delivery cannot be turned into a task. Replaying it would never help, so it is acked."""
+
+    NOT_UTF8 = "NOT_UTF8"
+    NOT_JSON = "NOT_JSON"
+    NOT_AN_OBJECT = "NOT_AN_OBJECT"
+    NO_TASK_ID = "NO_TASK_ID"
+    NO_DATA = "NO_DATA"
+    NO_BODY = "NO_BODY"
+    MALFORMED = "MALFORMED"
+
+
+@dataclass(frozen=True, slots=True)
+class PoisonDelivery:
+    """A delivery that cannot become a task.
+
+    ``task_id`` is kept whenever it could be read, for logging. It comes from an untrusted body (any length, may
+    contain control characters): bound and escape it before it reaches a log line.
+    """
+
+    reason: PoisonReason
+    task_id: str | None = None
+
+
+def decode_envelope(raw: bytes) -> TaskEnvelope | PoisonDelivery:  # noqa: PLR0911 - one early return per poison reason
+    """Decode a delivery body. Total: every failure is a ``PoisonDelivery``, nothing is ever raised."""
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        return PoisonDelivery(PoisonReason.NOT_UTF8)
+    try:
+        loaded: object = json.loads(text)
+    except (ValueError, RecursionError):
+        return PoisonDelivery(PoisonReason.NOT_JSON)
+    if not isinstance(loaded, dict):
+        return PoisonDelivery(PoisonReason.NOT_AN_OBJECT)
+    task_id = loaded.get(_KEY_TASK_ID)
+    if not isinstance(task_id, str) or not task_id:
+        return PoisonDelivery(PoisonReason.NO_TASK_ID)
+    data = loaded.get(_KEY_DATA)
+    if not isinstance(data, dict):
+        return PoisonDelivery(PoisonReason.NO_DATA, task_id)
+    if not isinstance(data.get(_KEY_BODY), dict):
+        return PoisonDelivery(PoisonReason.NO_BODY, task_id)
+    try:
+        return TaskEnvelope.model_validate(loaded)
+    except ValidationError:
+        return PoisonDelivery(PoisonReason.MALFORMED, task_id)

async_task_api_worker/protocol/json_types.py

@@ -0,0 +1,7 @@
+"""JSON value aliases shared by the protocol models and the public API."""
+
+from collections.abc import Mapping
+
+type JsonValue = str | int | float | bool | list[JsonValue] | dict[str, JsonValue] | None
+type JsonObject = dict[str, JsonValue]
+type ProgressPayload = Mapping[str, JsonValue]

async_task_api_worker/protocol/messages.py

@@ -0,0 +1,121 @@
+"""Outbound side of the protocol: what a worker publishes on ``<service>_queue_out``.
+
+Every byte goes through :class:`MessageEncoder`. The serialization is ``json.dumps`` of the model dump, with
+the default separators and ``ensure_ascii``, which is the wire format of the protocol. It is **not**
+``model_dump_json()``, whose compact separators would change the bytes (the golden tests pin this).
+"""
+
+import json
+import math
+import socket
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Final, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from async_task_api_worker.errors import DEFAULT_PUBLIC_MESSAGES, ErrorCode, WorkerError, validate_public_message
+from async_task_api_worker.protocol.json_types import JsonObject, JsonValue, ProgressPayload
+
+# A progress fraction lives in [0, 1): the terminal success or failure message is the "100%".
+_PROGRESS_UPPER_BOUND: Final[float] = 1.0
+
+
+class InvalidProgressError(ValueError):
+    """The progress fraction is not a finite number in ``[0, 1)``."""
+
+
+class _OutModel(BaseModel):
+    model_config = ConfigDict(frozen=True, allow_inf_nan=False)
+
+
+class StartedData(_OutModel):
+    message_type: Literal["started"] = "started"
+    hostname: str
+    started_at: str
+
+
+class ProgressData(_OutModel):
+    message_type: Literal["progress"] = "progress"
+    progress: float
+    response: JsonObject | None
+
+
+class SuccessData(_OutModel):
+    message_type: Literal["success"] = "success"
+    response: JsonObject
+    ended_at: str
+
+
+class ErrorDetail(_OutModel):
+    """Structured failure. The listener also accepts extra keys, which the SDK never sends."""
+
+    code: str
+    message: str
+
+
+class FailureData(_OutModel):
+    message_type: Literal["failure"] = "failure"
+    error_message: ErrorDetail
+    ended_at: str
+
+
+class OutMessage(_OutModel):
+    task_id: str
+    data: StartedData | ProgressData | SuccessData | FailureData = Field(discriminator="message_type")
+
+
+def _utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+@dataclass(frozen=True, slots=True)
+class MessageEncoder:
+    """Builds the exact bytes of every outbound message.
+
+    The worker dates its own messages (UTC, ``isoformat()``): the listener may process them out of order.
+    """
+
+    clock: Callable[[], datetime] = _utc_now
+    hostname: str = field(default_factory=socket.gethostname)
+
+    def _timestamp(self) -> str:
+        return self.clock().astimezone(UTC).isoformat()
+
+    @staticmethod
+    def _encode(message: OutMessage) -> bytes:
+        # ``allow_nan=False``: NaN and Infinity are not JSON, strict consumers downstream would choke on them.
+        return json.dumps(message.model_dump(mode="python"), allow_nan=False).encode()
+
+    def started(self, task_id: str) -> bytes:
+        data = StartedData(hostname=self.hostname, started_at=self._timestamp())
+        return self._encode(OutMessage(task_id=task_id, data=data))
+
+    def progress(self, task_id: str, fraction: float, payload: ProgressPayload | None) -> bytes:
+        """Encode a progress message. ``fraction`` must be finite and in ``[0, 1)``; it is always sent as a float."""
+        if isinstance(fraction, bool) or not math.isfinite(fraction) or not 0.0 <= fraction < _PROGRESS_UPPER_BOUND:
+            msg = f"progress must be a finite number in [0, {_PROGRESS_UPPER_BOUND}), got {fraction!r}"
+            raise InvalidProgressError(msg)
+        response: Mapping[str, JsonValue] | None = payload
+        data = ProgressData(progress=float(fraction), response=None if response is None else dict(response))
+        return self._encode(OutMessage(task_id=task_id, data=data))
+
+    def success(self, task_id: str, response: Mapping[str, JsonValue]) -> bytes:
+        data = SuccessData(response=dict(response), ended_at=self._timestamp())
+        return self._encode(OutMessage(task_id=task_id, data=data))
+
+    def failure(self, task_id: str, error: WorkerError | ErrorCode, message: str | None = None) -> bytes:
+        """Encode a failure from a ``WorkerError``, or from an SDK ``ErrorCode`` with its fixed public text."""
+        if isinstance(error, WorkerError):
+            if message is not None:
+                msg = "message cannot be combined with a WorkerError: it carries its own public message"
+                raise ValueError(msg)
+            detail = ErrorDetail(code=error.code, message=error.public_message)
+        else:
+            if message is None:
+                message = DEFAULT_PUBLIC_MESSAGES[error]
+            validate_public_message(message)
+            detail = ErrorDetail(code=error.value, message=message)
+        data = FailureData(error_message=detail, ended_at=self._timestamp())
+        return self._encode(OutMessage(task_id=task_id, data=data))

async_task_api_worker/protocol/version.py

@@ -0,0 +1,11 @@
+"""Wire protocol version spoken by this SDK.
+
+- ``0.1.0``: failure ``error_message`` is either the ``{"code", "message"}`` object (what the SDK sends) or a
+  ``"<CODE>: <message>"`` string (accepted from other producers).
+
+The protocol stays in 0.x until the contract is validated in production.
+"""
+
+from typing import Final
+
+PROTOCOL_VERSION: Final[str] = "0.1.0"

async_task_api_worker/settings.py

@@ -0,0 +1,127 @@
+"""Worker settings, read from the environment. The variable names are the SDK configuration contract."""
+
+from enum import StrEnum
+from typing import Final, Self
+
+from pydantic import Field, ModelWrapValidatorHandler, SecretStr, ValidationError, field_validator, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from async_task_api_worker.errors import WorkerConfigurationError
+
+DEFAULT_WORKER_CONCURRENCY: Final[int] = 1
+DEFAULT_HEALTH_CHECK_HOST: Final[str] = "0.0.0.0"  # noqa: S104 - the probe must be reachable from the pod network
+DEFAULT_HEALTH_CHECK_PORT: Final[int] = 8083
+MAX_TCP_PORT: Final[int] = 65535
+DEFAULT_SHUTDOWN_GRACE_S: Final[float] = 25.0
+# Mirrors ``rebut.deliveryLimit`` in ``helm/values.yaml``; calibrated against the broker policy in a later PR.
+DEFAULT_DELIVERY_LIMIT: Final[int] = 5
+# Mirrors ``rebut.consumerTimeoutMs`` (30 minutes) in ``helm/values.yaml``.
+DEFAULT_CONSUMER_TIMEOUT_S: Final[float] = 1800.0
+DEFAULT_RETRY_BACKOFF_BASE_S: Final[float] = 2.0
+DEFAULT_RETRY_BACKOFF_MAX_S: Final[float] = 30.0
+DEFAULT_PROBE_TIMEOUT_S: Final[float] = 3.0
+DEFAULT_PROGRESS_MIN_INTERVAL_S: Final[float] = 1.0
+DEFAULT_TASK_OVERRUN_GRACE_S: Final[float] = 60.0
+DEFAULT_BROKER_RECONNECT_INTERVAL_S: Final[float] = 5.0
+# One budget for all the shutdown hooks together (not one per hook, which would depend on how many there are): it is a
+# term of the shutdown bound documented in ADR 0005.
+DEFAULT_SHUTDOWN_HOOKS_TIMEOUT_S: Final[float] = 5.0
+DEFAULT_JOB_MAX_TASKS: Final[int] = 1
+# The queue held a message when the Job was created, and a ready message is dispatched within milliseconds of the
+# consumer registering: a longer wait only keeps an idle pod (and its resources) alive. See ADR 0005.
+DEFAULT_JOB_IDLE_TIMEOUT_S: Final[float] = 10.0
+# Job mode only: how long the broker may stay unreachable before the pod gives up and exits non-zero, so that the Job's
+# ``backoffLimit`` applies. Several reconnect attempts, short of what a broker restart usually takes. See ADR 0005.
+DEFAULT_JOB_CONNECT_TIMEOUT_S: Final[float] = 30.0
+# In job mode a pod takes one delivery at a time, whatever ``WORKER_CONCURRENCY`` says.
+JOB_PREFETCH: Final[int] = 1
+
+
+class LogLevel(StrEnum):
+    DEBUG = "DEBUG"
+    INFO = "INFO"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+    CRITICAL = "CRITICAL"
+
+
+class WorkerMode(StrEnum):
+    """How a deployment runs the same worker: a long-lived consumer, or a one-shot Job."""
+
+    SERVICE = "service"
+    JOB = "job"
+
+
+class WorkerSettings(BaseSettings):
+    """Environment-driven settings. An invalid value raises ``WorkerConfigurationError``: the worker must not start.
+
+    Each field is read from the upper-cased environment variable of the same name (``broker_url`` ->
+    ``BROKER_URL``). No ``.env`` file is read by default.
+    """
+
+    model_config = SettingsConfigDict(extra="ignore", frozen=True)
+
+    broker_url: SecretStr = Field(min_length=1)
+    in_queue_name: str = Field(min_length=1)
+    out_queue_name: str = Field(min_length=1)
+    worker_concurrency: int = Field(default=DEFAULT_WORKER_CONCURRENCY, ge=1)
+    health_check_host: str = DEFAULT_HEALTH_CHECK_HOST
+    health_check_port: int = Field(default=DEFAULT_HEALTH_CHECK_PORT, ge=1, le=MAX_TCP_PORT)
+    log_level: LogLevel = LogLevel.INFO
+    worker_task_timeout_s: float | None = Field(default=None, gt=0)
+    worker_shutdown_grace_s: float = Field(default=DEFAULT_SHUTDOWN_GRACE_S, ge=0)
+    worker_delivery_limit: int = Field(default=DEFAULT_DELIVERY_LIMIT, ge=1)
+    worker_consumer_timeout_s: float = Field(default=DEFAULT_CONSUMER_TIMEOUT_S, gt=0)
+    worker_retry_backoff_base_s: float = Field(default=DEFAULT_RETRY_BACKOFF_BASE_S, gt=0)
+    worker_retry_backoff_max_s: float = Field(default=DEFAULT_RETRY_BACKOFF_MAX_S, gt=0)
+    worker_probe_timeout_s: float = Field(default=DEFAULT_PROBE_TIMEOUT_S, gt=0)
+    worker_progress_min_interval_s: float = Field(default=DEFAULT_PROGRESS_MIN_INTERVAL_S, ge=0)
+    worker_task_overrun_grace_s: float = Field(default=DEFAULT_TASK_OVERRUN_GRACE_S, ge=0)
+    worker_broker_reconnect_interval_s: float = Field(default=DEFAULT_BROKER_RECONNECT_INTERVAL_S, gt=0)
+    worker_shutdown_hooks_timeout_s: float = Field(default=DEFAULT_SHUTDOWN_HOOKS_TIMEOUT_S, gt=0)
+    worker_mode: WorkerMode = WorkerMode.SERVICE
+    worker_job_max_tasks: int = Field(default=DEFAULT_JOB_MAX_TASKS, ge=1)
+    worker_job_idle_timeout_s: float = Field(default=DEFAULT_JOB_IDLE_TIMEOUT_S, gt=0)
+    worker_job_connect_timeout_s: float = Field(default=DEFAULT_JOB_CONNECT_TIMEOUT_S, gt=0)
+
+    @property
+    def is_job(self) -> bool:
+        return self.worker_mode is WorkerMode.JOB
+
+    @property
+    def prefetch(self) -> int:
+        """How many unacknowledged deliveries the broker may hand this process."""
+        return JOB_PREFETCH if self.is_job else self.worker_concurrency
+
+    @field_validator("worker_mode", mode="before")
+    @classmethod
+    def _lowercase_worker_mode(cls, value: object) -> object:
+        return value.strip().lower() if isinstance(value, str) else value
+
+    @field_validator("log_level", mode="before")
+    @classmethod
+    def _uppercase_log_level(cls, value: object) -> object:
+        return value.strip().upper() if isinstance(value, str) else value
+
+    @model_validator(mode="after")
+    def _backoff_base_must_not_exceed_max(self) -> Self:
+        if self.worker_retry_backoff_base_s > self.worker_retry_backoff_max_s:
+            msg = "WORKER_RETRY_BACKOFF_BASE_S must not exceed WORKER_RETRY_BACKOFF_MAX_S"
+            raise ValueError(msg)
+        return self
+
+    @model_validator(mode="wrap")
+    @classmethod
+    def _refuse_to_start_on_invalid_settings(cls, data: object, handler: ModelWrapValidatorHandler[Self]) -> Self:
+        try:
+            return handler(data)
+        except ValidationError as error:
+            # Never echo ``input`` or the raw error: BROKER_URL carries credentials.
+            problems = "; ".join(
+                f"{location}: {issue['msg']}"
+                if (location := ".".join(map(str, issue["loc"])).upper())
+                else issue["msg"]
+                for issue in error.errors()
+            )
+            msg = f"Invalid worker settings: {problems}"
+            raise WorkerConfigurationError(msg) from None

async_task_api_worker/testing/__init__.py

@@ -0,0 +1,27 @@
+"""Test a worker without a broker.
+
+- :class:`WorkerHarness` runs a worker's task in memory through the real engine and returns what it published and
+  what it did to the delivery (:class:`TaskRun`, :class:`Outcome`).
+- :func:`make_task_context` and :func:`make_sync_task_context` build the context a handler receives, to call a handler
+  directly; :class:`ProgressRecorder` collects what it reports.
+
+This is the first part of the testing kit: the conformance suite extends it in later releases.
+"""
+
+from async_task_api_worker.testing._context import (
+    ProgressRecorder,
+    ProgressUpdate,
+    make_sync_task_context,
+    make_task_context,
+)
+from async_task_api_worker.testing._harness import Outcome, TaskRun, WorkerHarness
+
+__all__ = [
+    "Outcome",
+    "ProgressRecorder",
+    "ProgressUpdate",
+    "TaskRun",
+    "WorkerHarness",
+    "make_sync_task_context",
+    "make_task_context",
+]

async_task_api_worker/testing/_context.py

@@ -0,0 +1,93 @@
+"""Build the context a handler receives, to call a handler directly in a unit test."""
+
+import logging
+import threading
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Final, NamedTuple
+
+from async_task_api_worker.context import SyncTaskContext, TaskContext
+from async_task_api_worker.protocol.envelope import InputRef
+from async_task_api_worker.protocol.json_types import ProgressPayload
+
+DEFAULT_TASK_ID: Final[str] = "test-task"
+DEFAULT_TIMEOUT_S: Final[float] = 60.0
+_LOGGER_NAME: Final[str] = "async_task_api_worker.testing"
+
+
+class ProgressUpdate(NamedTuple):
+    """One call of ``ctx.progress``."""
+
+    fraction: float
+    payload: ProgressPayload | None
+
+
+@dataclass(slots=True)
+class ProgressRecorder:
+    """Collects what a handler reports through ``ctx.progress``, untouched: no throttling, no validation."""
+
+    updates: list[ProgressUpdate] = field(default_factory=list)
+
+    async def _record(self, fraction: float, payload: ProgressPayload | None = None) -> None:
+        self.updates.append(ProgressUpdate(fraction, payload))
+
+    def _record_from_thread(self, fraction: float, payload: ProgressPayload | None = None) -> None:
+        self.updates.append(ProgressUpdate(fraction, payload))
+
+
+def _logger(task_id: str, attempt: int) -> logging.LoggerAdapter[logging.Logger]:
+    return logging.LoggerAdapter(logging.getLogger(_LOGGER_NAME), {"task_id": task_id, "attempt": attempt})
+
+
+def make_task_context(
+    *,
+    task_id: str = DEFAULT_TASK_ID,
+    client_id: str | None = None,
+    attempt: int = 1,
+    timeout_s: float = DEFAULT_TIMEOUT_S,
+    inputs: Mapping[str, InputRef] | None = None,
+    recorder: ProgressRecorder | None = None,
+) -> TaskContext:
+    """The context of an ``async def`` handler, to call it directly.
+
+    ``timeout_s`` sets ``ctx.remaining()``; ``recorder`` collects the progress updates the handler reports (a recorder
+    of its own is used when none is given).
+    """
+    sink = recorder if recorder is not None else ProgressRecorder()
+    return TaskContext(
+        task_id,
+        client_id,
+        attempt,
+        time.monotonic() + timeout_s,
+        _logger(task_id, attempt),
+        dict(inputs or {}),
+        sink._record,
+    )
+
+
+def make_sync_task_context(
+    *,
+    task_id: str = DEFAULT_TASK_ID,
+    client_id: str | None = None,
+    attempt: int = 1,
+    timeout_s: float = DEFAULT_TIMEOUT_S,
+    inputs: Mapping[str, InputRef] | None = None,
+    recorder: ProgressRecorder | None = None,
+    cancel_event: threading.Event | None = None,
+) -> SyncTaskContext:
+    """The context of a ``def`` handler, to call it directly.
+
+    Set ``cancel_event`` to make ``ctx.cancelled()`` true, as a timeout or a shutdown would.
+    """
+    sink = recorder if recorder is not None else ProgressRecorder()
+    return SyncTaskContext(
+        task_id,
+        client_id,
+        attempt,
+        time.monotonic() + timeout_s,
+        _logger(task_id, attempt),
+        dict(inputs or {}),
+        sink._record_from_thread,
+        cancel_event if cancel_event is not None else threading.Event(),
+    )