ringo-task-queue 0.1.0.dev0__py3-none-win_amd64.whl

ringo_task_queue/models.py

@@ -0,0 +1,364 @@
+"""Public data model for the Ringo Task Queue Python SDK.
+
+Dataclasses here mirror the frozen ``ringo.v1`` protobuf contract but expose
+plain Python values (timezone-aware datetimes, timedeltas, arbitrary JSON
+payloads). Conversion to/from wire messages lives in :mod:`._pb`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from enum import Enum
+import json
+import math
+from typing import Any
+
+from . import _pb
+from ._proto.ringo.v1 import queue_pb2
+from .errors import InternalError, InvalidArgumentError
+
+# ---------------------------------------------------------------------------
+# Enums
+
+
+class TaskStatus(str, Enum):
+    SCHEDULED = "SCHEDULED"
+    READY = "READY"
+    LEASED = "LEASED"
+    SUCCEEDED = "SUCCEEDED"
+    DEAD = "DEAD"
+    CANCELLED = "CANCELLED"
+
+
+class RetryStrategy(str, Enum):
+    FIXED = "FIXED"
+    EXPONENTIAL = "EXPONENTIAL"
+
+
+@dataclass(frozen=True, slots=True)
+class SQLiteStorage:
+    """Use the embedded daemon's SQLite database in ``data_dir``."""
+
+
+@dataclass(frozen=True, slots=True)
+class PostgresStorage:
+    """Connect the embedded daemon to user-managed PostgreSQL."""
+
+    dsn: str = field(repr=False)
+
+    def __post_init__(self) -> None:
+        if not self.dsn.strip():
+            raise InvalidArgumentError("PostgreSQL DSN is required")
+
+
+_STATUS_FROM_PROTO = {
+    queue_pb2.TASK_STATUS_SCHEDULED: TaskStatus.SCHEDULED,
+    queue_pb2.TASK_STATUS_READY: TaskStatus.READY,
+    queue_pb2.TASK_STATUS_LEASED: TaskStatus.LEASED,
+    queue_pb2.TASK_STATUS_SUCCEEDED: TaskStatus.SUCCEEDED,
+    queue_pb2.TASK_STATUS_DEAD: TaskStatus.DEAD,
+    queue_pb2.TASK_STATUS_CANCELLED: TaskStatus.CANCELLED,
+}
+
+_STRATEGY_TO_PROTO = {
+    RetryStrategy.FIXED: queue_pb2.RETRY_STRATEGY_FIXED,
+    RetryStrategy.EXPONENTIAL: queue_pb2.RETRY_STRATEGY_EXPONENTIAL,
+}
+
+_STRATEGY_FROM_PROTO = {value: key for key, value in _STRATEGY_TO_PROTO.items()}
+
+#: Maximum encoded JSON payload size (docs/contracts/defaults.md), measured
+#: in UTF-8 bytes exactly like the server enforces it.
+_MAX_PAYLOAD_BYTES = 1_048_576
+
+
+def _status_from_proto(value: int) -> TaskStatus:
+    status = _STATUS_FROM_PROTO.get(value)
+    if status is None:
+        raise InternalError(f"server returned unknown task status enum {value}")
+    return status
+
+
+def _strategy_from_proto(value: int) -> RetryStrategy:
+    strategy = _STRATEGY_FROM_PROTO.get(value)
+    if strategy is None:
+        raise InternalError(f"server returned unknown retry strategy enum {value}")
+    return strategy
+
+
+# ---------------------------------------------------------------------------
+# Producer-facing spec types
+
+
+@dataclass
+class RetryPolicy:
+    """Retry configuration; ``None`` fields fall back to server defaults."""
+
+    max_attempts: int = 3
+    strategy: RetryStrategy = RetryStrategy.EXPONENTIAL
+    initial_delay: timedelta = timedelta(seconds=1)
+    max_delay: timedelta = timedelta(seconds=60)
+    multiplier: float = 2.0
+    jitter: float = 0.2
+    decrease_priority: bool = False
+
+    def to_proto(self) -> queue_pb2.RetryPolicy:
+        # Mirrors internal/domain/retry.go Validate exactly.
+        if self.max_attempts < 1 or self.max_attempts > 32:
+            raise InvalidArgumentError("max_attempts must be between 1 and 32")
+        if not isinstance(self.strategy, RetryStrategy):
+            raise InvalidArgumentError(f"unknown retry strategy {self.strategy!r}")
+        if self.initial_delay < timedelta(0) or self.max_delay < self.initial_delay:
+            raise InvalidArgumentError(
+                "retry delays are invalid: initial_delay must be >= 0 and"
+                " max_delay must be >= initial_delay"
+            )
+        if (
+            math.isnan(self.multiplier)
+            or math.isinf(self.multiplier)
+            or (self.strategy is RetryStrategy.EXPONENTIAL and self.multiplier < 1.0)
+        ):
+            raise InvalidArgumentError(
+                "exponential retry multiplier must be finite and at least one"
+            )
+        if (
+            math.isnan(self.jitter)
+            or math.isinf(self.jitter)
+            or not 0.0 <= self.jitter <= 1.0
+        ):
+            raise InvalidArgumentError("jitter must be finite and between zero and one")
+        return queue_pb2.RetryPolicy(
+            max_attempts=self.max_attempts,
+            strategy=_STRATEGY_TO_PROTO[self.strategy],
+            initial_delay=_pb.td_to_dur(self.initial_delay),
+            max_delay=_pb.td_to_dur(self.max_delay),
+            multiplier=self.multiplier,
+            jitter=self.jitter,
+            decrease_priority=self.decrease_priority,
+        )
+
+    @classmethod
+    def from_proto(cls, msg: queue_pb2.RetryPolicy) -> "RetryPolicy":
+        return cls(
+            max_attempts=msg.max_attempts,
+            strategy=_strategy_from_proto(msg.strategy),
+            initial_delay=_pb.dur_to_td(msg.initial_delay) or timedelta(0),
+            max_delay=_pb.dur_to_td(msg.max_delay) or timedelta(0),
+            multiplier=msg.multiplier,
+            jitter=msg.jitter,
+            decrease_priority=msg.decrease_priority,
+        )
+
+
+def _check_payload_size(payload: Any) -> None:
+    """Client-side precheck of the 1 MiB encoded-JSON payload ceiling.
+
+    Mirrors the server contract: the limit is measured in UTF-8 encoded
+    bytes. The server remains the authoritative enforcer; this catches the
+    common case without a round trip and without diverging semantics.
+    """
+    try:
+        encoded = json.dumps(
+            payload, ensure_ascii=False, separators=(",", ":"), allow_nan=False
+        ).encode("utf-8")
+    except (TypeError, ValueError) as exc:
+        raise InvalidArgumentError(f"payload is not JSON-serializable: {exc}") from exc
+    if len(encoded) > _MAX_PAYLOAD_BYTES:
+        raise InvalidArgumentError(
+            f"encoded payload is {len(encoded)} bytes, exceeding the"
+            f" {_MAX_PAYLOAD_BYTES}-byte limit"
+        )
+
+
+class _UnsetType:
+    def __repr__(self) -> str:  # pragma: no cover
+        return "UNSET"
+
+
+#: Sentinel distinguishing "payload not supplied" (INVALID_ARGUMENT) from an
+#: explicit JSON ``None`` payload.
+UNSET = _UnsetType()
+
+
+@dataclass
+class TaskSpec:
+    """Producer-supplied task fields only.
+
+    Internal lifecycle fields (status, attempt, lease, ...) are server-owned
+    and intentionally absent here; the wire contract rejects enqueueing them.
+    """
+
+    unique_key: str
+    task_type: str
+    payload: Any = UNSET
+    priority: int = 0
+    retry_policy: RetryPolicy | None = None
+    available_at: datetime | None = None
+
+    def to_proto(self) -> queue_pb2.TaskSpec:
+        if not self.unique_key:
+            raise InvalidArgumentError("unique_key is required")
+        if not self.task_type:
+            raise InvalidArgumentError("task_type is required")
+        if self.payload is UNSET:
+            raise InvalidArgumentError(
+                "payload is required; pass None explicitly for a JSON null payload"
+            )
+        if not -(2**31) <= self.priority < 2**31:
+            raise InvalidArgumentError("priority must fit in a signed 32-bit integer")
+        _check_payload_size(self.payload)
+        msg = queue_pb2.TaskSpec(
+            unique_key=self.unique_key,
+            type=self.task_type,
+            payload=_pb.py_to_value(self.payload),
+            priority=self.priority,
+        )
+        if self.retry_policy is not None:
+            msg.retry_policy.CopyFrom(self.retry_policy.to_proto())
+        if self.available_at is not None:
+            msg.available_at.CopyFrom(_pb.dt_to_ts(self.available_at))
+        return msg
+
+
+# ---------------------------------------------------------------------------
+# Server-facing read models
+
+
+@dataclass
+class Attempt:
+    number: int
+    worker_id: str
+    started_at: datetime | None
+    finished_at: datetime | None
+    outcome: str
+    error: str
+    error_truncated: bool
+
+
+@dataclass
+class Progress:
+    current: float
+    total: float
+    message: str
+    updated_at: datetime | None
+
+
+@dataclass
+class LeaseInfo:
+    attempt: int
+    worker_id: str
+    until: datetime | None
+
+
+@dataclass
+class Task:
+    id: str
+    queue: str
+    unique_key: str
+    task_type: str
+    payload: Any
+    priority: int
+    status: TaskStatus
+    attempt: int
+    max_attempts: int
+    available_at: datetime | None
+    created_at: datetime | None
+    updated_at: datetime | None
+    completed_at: datetime | None
+    last_error: str
+    last_error_truncated: bool
+    attempts: list[Attempt] = field(default_factory=list)
+    progress: Progress | None = None
+    current_lease: LeaseInfo | None = None
+
+    @classmethod
+    def from_proto(cls, msg: queue_pb2.Task) -> "Task":
+        return cls(
+            id=msg.id,
+            queue=msg.queue,
+            unique_key=msg.unique_key,
+            task_type=msg.type,
+            payload=_pb.value_to_py(msg.payload),
+            priority=msg.priority,
+            status=_status_from_proto(msg.status),
+            attempt=msg.attempt,
+            max_attempts=msg.max_attempts,
+            available_at=_pb.ts_to_dt(msg.available_at)
+            if msg.HasField("available_at")
+            else None,
+            created_at=_pb.ts_to_dt(msg.created_at)
+            if msg.HasField("created_at")
+            else None,
+            updated_at=_pb.ts_to_dt(msg.updated_at)
+            if msg.HasField("updated_at")
+            else None,
+            completed_at=_pb.ts_to_dt(msg.completed_at)
+            if msg.HasField("completed_at")
+            else None,
+            last_error=msg.last_error,
+            last_error_truncated=msg.last_error_truncated,
+            attempts=[
+                Attempt(
+                    number=a.number,
+                    worker_id=a.worker_id,
+                    started_at=_pb.ts_to_dt(a.started_at)
+                    if a.HasField("started_at")
+                    else None,
+                    finished_at=_pb.ts_to_dt(a.finished_at)
+                    if a.HasField("finished_at")
+                    else None,
+                    outcome=a.outcome,
+                    error=a.error,
+                    error_truncated=a.error_truncated,
+                )
+                for a in msg.attempts
+            ],
+            progress=Progress(
+                current=msg.progress.current,
+                total=msg.progress.total,
+                message=msg.progress.message,
+                updated_at=_pb.ts_to_dt(msg.progress.updated_at)
+                if msg.progress.HasField("updated_at")
+                else None,
+            )
+            if msg.HasField("progress")
+            else None,
+            current_lease=LeaseInfo(
+                attempt=msg.current_lease.attempt,
+                worker_id=msg.current_lease.worker_id,
+                until=_pb.ts_to_dt(msg.current_lease.until)
+                if msg.current_lease.HasField("until")
+                else None,
+            )
+            if msg.HasField("current_lease")
+            else None,
+        )
+
+
+@dataclass
+class EnqueueResult:
+    task_id: str
+    created: bool
+    task: Task | None = None
+
+    @classmethod
+    def from_proto(cls, msg: queue_pb2.EnqueueResult) -> "EnqueueResult":
+        return cls(
+            task_id=msg.task_id,
+            created=msg.created,
+            task=Task.from_proto(msg.task) if msg.HasField("task") else None,
+        )
+
+
+@dataclass
+class BatchResult:
+    """Per-item results for a batch enqueue; never loses per-task meaning."""
+
+    results: list[EnqueueResult]
+    created_count: int
+    duplicate_count: int
+
+    @property
+    def task_ids(self) -> list[str]:
+        return [r.task_id for r in self.results]