continuum-task-server-sdk 1.1.0__py3-none-any.whl

continuum_task_server/exceptions.py

@@ -0,0 +1,94 @@
+"""Exception types raised by the Continuum SDK."""
+
+from __future__ import annotations
+
+
+class ContinuumError(Exception):
+    """Base exception for all Continuum SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        body: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+    def __str__(self) -> str:
+        base = super().__str__()
+        if self.status_code is not None:
+            return f"[{self.status_code}] {base}"
+        return base
+
+
+class BadRequestError(ContinuumError):
+    """HTTP / command 400."""
+
+
+class UnauthorizedError(ContinuumError):
+    """HTTP 401 - check API key type (Organization vs Worker)."""
+
+
+class ForbiddenError(ContinuumError):
+    """HTTP 403."""
+
+
+class NotFoundError(ContinuumError):
+    """HTTP 404."""
+
+
+class ConflictError(ContinuumError):
+    """HTTP 409."""
+
+
+class RateLimitError(ContinuumError):
+    """HTTP / command 429."""
+
+
+class ServerError(ContinuumError):
+    """HTTP 5xx."""
+
+
+class TransportError(ContinuumError):
+    """WebSocket / STOMP connection failed or dropped."""
+
+
+class ProtocolError(ContinuumError):
+    """Malformed STOMP frame or unexpected protocol response."""
+
+
+class CommandTimeoutError(ContinuumError):
+    """Timed out waiting for a correlated command reply."""
+
+
+class AmbiguousCommandError(TransportError):
+    """A non-idempotent command was sent but its reply was lost.
+
+    The server may or may not have applied the mutation (claim / enqueue).
+    Do not retry with the same intent without checking queue state.
+    """
+
+
+_STATUS_TO_EXC: dict[int, type[ContinuumError]] = {
+    400: BadRequestError,
+    401: UnauthorizedError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    409: ConflictError,
+    429: RateLimitError,
+}
+
+
+def error_for_status(status_code: int, body: str) -> ContinuumError:
+    """Build the appropriate exception for a non-2xx HTTP or command status."""
+    exc_cls = _STATUS_TO_EXC.get(status_code)
+    if exc_cls is None:
+        if 500 <= status_code < 600:
+            exc_cls = ServerError
+        else:
+            exc_cls = ContinuumError
+    message = body if body else f"Request failed with status {status_code}"
+    return exc_cls(message, status_code=status_code, body=body)

continuum_task_server/models.py

@@ -0,0 +1,197 @@
+"""Pydantic models mirroring the Continuum Task Server JSON shapes."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from enum import Enum
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class TaskStatus(str, Enum):
+    """Status of a queue item in the task processing lifecycle."""
+
+    OPEN = "OPEN"
+    CLAIMED = "CLAIMED"
+    STARTED = "STARTED"
+    TIMEDOUT = "TIMEDOUT"
+    CANCELLED = "CANCELLED"
+    KILLED = "KILLED"
+    ENDED = "ENDED"
+
+
+class _Base(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+
+class TaskType(_Base):
+    id: UUID | None = None
+    name: str | None = None
+    description: str | None = None
+    active_flag: bool = Field(default=False, alias="activeFlag")
+    organization_id: UUID | None = Field(default=None, alias="organizationId")
+    is_global: bool = Field(default=False, alias="isGlobal")
+    max_duration_sec: int | None = Field(default=None, alias="maxDurationSec")
+    heartbeat_timeout_sec: int | None = Field(default=None, alias="heartbeatTimeoutSec")
+
+
+class TaskItem(_Base):
+    id: UUID | None = None
+    name: str | None = None
+    organization_id: UUID | None = Field(default=None, alias="organizationId")
+    is_global: bool = Field(default=False, alias="isGlobal")
+    active_flag: bool = Field(default=False, alias="activeFlag")
+    published_version: int | None = Field(default=None, alias="publishedVersion")
+    task_type_id: UUID | None = Field(default=None, alias="taskTypeId")
+
+
+class TaskItemVersion(_Base):
+    id: UUID | None = None
+    task_item_id: UUID | None = Field(default=None, alias="taskItemId")
+    version_number: int = Field(default=0, alias="versionNumber")
+    content_url: str | None = Field(default=None, alias="contentUrl")
+    main_path: str | None = Field(default=None, alias="mainPath")
+    item_definition: str | None = Field(default=None, alias="itemDefinition")
+    active_flag: bool = Field(default=False, alias="activeFlag")
+    created_by: UUID | None = Field(default=None, alias="createdBy")
+    created_dtm: datetime | None = Field(default=None, alias="createdDtm")
+
+    @property
+    def item_definition_json(self) -> Any:
+        if not self.item_definition:
+            return None
+        try:
+            return json.loads(self.item_definition)
+        except (ValueError, TypeError):
+            return self.item_definition
+
+
+class QueueItem(_Base):
+    id: UUID
+    depth: int = 0
+    task_type_id: UUID | None = Field(default=None, alias="taskTypeId")
+    task_item_version_id: UUID | None = Field(default=None, alias="taskItemVersionId")
+    priority: int = 0
+    task_status: TaskStatus | None = Field(default=None, alias="taskStatus")
+    organization_id: UUID | None = Field(default=None, alias="organizationId")
+    created_dtm: datetime | None = Field(default=None, alias="createdDtm")
+    created_by: UUID | None = Field(default=None, alias="createdBy")
+    input_data: str | None = Field(default=None, alias="inputData")
+    output_data: str | None = Field(default=None, alias="outputData")
+
+    @property
+    def input_data_json(self) -> Any:
+        """Parse `input_data` as JSON. Returns None if input_data is None/empty,
+        or the raw string if it's not valid JSON."""
+        if not self.input_data:
+            return None
+        try:
+            return json.loads(self.input_data)
+        except (ValueError, TypeError):
+            return self.input_data
+
+    @property
+    def output_data_json(self) -> Any:
+        if not self.output_data:
+            return None
+        try:
+            return json.loads(self.output_data)
+        except (ValueError, TypeError):
+            return self.output_data
+
+
+class Content(_Base):
+    """Raw content returned from a content-store or queue-item content endpoint."""
+
+    data: bytes
+    mime_type: str = "application/octet-stream"
+
+    def as_text(self, encoding: str = "utf-8") -> str:
+        return self.data.decode(encoding)
+
+
+class TransportMode(str, Enum):
+    """How ``TaskServer`` obtains work."""
+
+    HTTP = "http"
+    WEBSOCKET = "websocket"
+
+
+class WaitMode(str, Enum):
+    """Durable completion-wait mode."""
+
+    EACH = "EACH"
+    ALL = "ALL"
+
+
+class QueueEventType(str, Enum):
+    """Wire ``eventType`` values on ``/user/queue/events``."""
+
+    WORK_AVAILABLE = "work.available"
+    COMPLETED = "queue.completed"
+
+
+class WaitTargetStatus(_Base):
+    """Per-item outcome on an ALL-mode completion summary."""
+
+    queue_item_id: UUID = Field(alias="queueItemId")
+    status: TaskStatus | str | None = None
+
+
+class QueueEvent(_Base):
+    """Compact ``work.available`` hint or durable ``queue.completed`` delivery."""
+
+    event_id: UUID = Field(alias="eventId")
+    event_version: int = Field(default=1, alias="eventVersion")
+    event_type: QueueEventType = Field(alias="eventType")
+    occurred_at: datetime | None = Field(default=None, alias="occurredAt")
+    queue_item_id: UUID | None = Field(default=None, alias="queueItemId")
+    organization_id: UUID | None = Field(default=None, alias="organizationId")
+    task_type_id: UUID | None = Field(default=None, alias="taskTypeId")
+    task_name: str | None = Field(default=None, alias="taskName")
+    status: TaskStatus | None = None
+    subscription_id: UUID | None = Field(default=None, alias="subscriptionId")
+    correlation: str | None = None
+    wait_mode: WaitMode | None = Field(default=None, alias="waitMode")
+    targets: list[WaitTargetStatus] | None = None
+
+
+class WorkSubscriptionResult(_Base):
+    """Result of ``subscribeWork`` / ``unsubscribeWork``."""
+
+    task_name: str | None = Field(default=None, alias="taskName")
+    subscribed: bool | None = None
+
+
+class WaitSubscriptionResult(_Base):
+    """Result of ``subscribeWait`` / bind-only replay."""
+
+    subscription_id: UUID | None = Field(default=None, alias="subscriptionId")
+    subscriber_id: str | None = Field(default=None, alias="subscriberId")
+    wait_mode: WaitMode | None = Field(default=None, alias="waitMode")
+    pending_count: int = Field(default=0, alias="pendingCount")
+    closed: bool = False
+    subscribed: bool | None = None
+
+
+class EventAckResult(_Base):
+    """Result of ``ackEvent``."""
+
+    subscription_id: UUID | None = Field(default=None, alias="subscriptionId")
+    closed: bool = False
+    acked: bool = True
+
+
+class EnqueueAndSubscribeWaitResult(_Base):
+    """Combined result of ``enqueueAndSubscribeWait``."""
+
+    item: QueueItem
+    subscription_id: UUID | None = Field(default=None, alias="subscriptionId")
+    subscriber_id: str | None = Field(default=None, alias="subscriberId")
+    wait_mode: WaitMode | None = Field(default=None, alias="waitMode")
+    pending_count: int = Field(default=0, alias="pendingCount")
+    closed: bool = False
+    subscribed: bool | None = None