ringo-task-queue 0.1.0.dev6__py3-none-win_amd64.whl → 0.1.0.dev7__py3-none-win_amd64.whl

ringo_task_queue/models.py

@@ -1,364 +1,449 @@
-"""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]
+"""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
+    history_id: int = 0
+
+    @classmethod
+    def from_proto(cls, msg: queue_pb2.Attempt) -> "Attempt":
+        return cls(
+            number=msg.number,
+            worker_id=msg.worker_id,
+            started_at=_pb.ts_to_dt(msg.started_at) if msg.HasField("started_at") else None,
+            finished_at=_pb.ts_to_dt(msg.finished_at)
+            if msg.HasField("finished_at")
+            else None,
+            outcome=msg.outcome,
+            error=msg.error,
+            error_truncated=msg.error_truncated,
+            history_id=getattr(msg, "history_id", 0),
+        )
+
+
+@dataclass
+class AttemptPage:
+    """Oldest-first durable history page within the initial high-water mark.
+
+    A page may contain fewer records than requested due to the byte budget.
+    Start again without a cursor to include attempts appended after this read.
+    """
+
+    attempts: list[Attempt]
+    next_cursor: str | None = None
+
+    @classmethod
+    def from_proto(cls, msg: queue_pb2.GetTaskAttemptsResponse) -> "AttemptPage":
+        return cls(
+            attempts=[Attempt.from_proto(a) for a in msg.attempts],
+            next_cursor=msg.next_cursor or None,
+        )
+
+
+@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
+    #: True means ``attempts`` is only a bounded recent preview.
+    attempts_truncated: bool = False
+
+    @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.from_proto(a) for a in msg.attempts],
+            attempts_truncated=getattr(msg, "attempts_truncated", False),
+            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]
+
+
+# ---------------------------------------------------------------------------
+# Queue statistics (protocol minor >= 4, additive GetQueueStats)
+
+
+def _optional_ts(msg: Any, field: str) -> datetime | None:
+    """Read an optional ``Timestamp`` field from a protobuf message.
+
+    Tolerates light stand-ins used by unit tests that expose the attribute
+    but no ``HasField``.
+    """
+    has_field = getattr(msg, "HasField", None)
+    if callable(has_field):
+        try:
+            if not has_field(field):
+                return None
+        except (AttributeError, ValueError):
+            return None
+    value = getattr(msg, field, None)
+    return _pb.ts_to_dt(value) if value is not None else None
+
+
+@dataclass
+class QueueStats:
+    """Point-in-time per-status task counts for one queue.
+
+    Counts always cover all six canonical task statuses, including zero
+    values, for the queue and optional task-type scope that was requested.
+    Timestamps are timezone-aware UTC datetimes; ``None`` means the server
+    had no matching observation (for example no READY task for
+    ``oldest_ready_at``, or a queue without recorded activity yet).
+    """
+
+    scheduled: int
+    ready: int
+    leased: int
+    succeeded: int
+    dead: int
+    cancelled: int
+    observed_at: datetime | None
+    oldest_ready_at: datetime | None
+    last_activity_at: datetime | None
+
+    @property
+    def active(self) -> int:
+        """Tasks still in flight: ``SCHEDULED + READY + LEASED``."""
+        return self.scheduled + self.ready + self.leased
+
+    @classmethod
+    def from_proto(cls, msg: Any) -> QueueStats:
+        return cls(
+            scheduled=msg.scheduled_count,
+            ready=msg.ready_count,
+            leased=msg.leased_count,
+            succeeded=msg.succeeded_count,
+            dead=msg.dead_count,
+            cancelled=msg.cancelled_count,
+            observed_at=_optional_ts(msg, "observed_at"),
+            oldest_ready_at=_optional_ts(msg, "oldest_ready_at"),
+            last_activity_at=_optional_ts(msg, "last_activity_at"),
+        )