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

continuum_task_server/__init__.py

@@ -0,0 +1,74 @@
+"""Continuum Task Server SDK for Python."""
+
+from __future__ import annotations
+
+from .client import ContinuumClient
+from .exceptions import (
+    AmbiguousCommandError,
+    BadRequestError,
+    CommandTimeoutError,
+    ConflictError,
+    ContinuumError,
+    ForbiddenError,
+    NotFoundError,
+    ProtocolError,
+    RateLimitError,
+    ServerError,
+    TransportError,
+    UnauthorizedError,
+)
+from .models import (
+    Content,
+    EnqueueAndSubscribeWaitResult,
+    EventAckResult,
+    QueueEvent,
+    QueueEventType,
+    QueueItem,
+    TaskItem,
+    TaskItemVersion,
+    TaskStatus,
+    TaskType,
+    TransportMode,
+    WaitMode,
+    WaitSubscriptionResult,
+    WaitTargetStatus,
+    WorkSubscriptionResult,
+)
+from .server import TaskServer
+from .websocket import ContinuumWebSocketClient, WebSocketOptions
+
+__all__ = [
+    "AmbiguousCommandError",
+    "BadRequestError",
+    "CommandTimeoutError",
+    "ConflictError",
+    "Content",
+    "ContinuumClient",
+    "ContinuumError",
+    "ContinuumWebSocketClient",
+    "EnqueueAndSubscribeWaitResult",
+    "EventAckResult",
+    "ForbiddenError",
+    "NotFoundError",
+    "ProtocolError",
+    "QueueEvent",
+    "QueueEventType",
+    "QueueItem",
+    "RateLimitError",
+    "ServerError",
+    "TaskItem",
+    "TaskItemVersion",
+    "TaskServer",
+    "TaskStatus",
+    "TaskType",
+    "TransportError",
+    "TransportMode",
+    "UnauthorizedError",
+    "WaitMode",
+    "WaitSubscriptionResult",
+    "WaitTargetStatus",
+    "WebSocketOptions",
+    "WorkSubscriptionResult",
+]
+
+__version__ = "0.1.0"

continuum_task_server/_http.py

@@ -0,0 +1,142 @@
+"""Internal HTTP wrapper. Handles Api-Key auth, JSON (de)serialization, and error mapping."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+import httpx
+
+from .exceptions import ContinuumError, error_for_status
+
+logger = logging.getLogger("continuum_task_server")
+
+
+def _normalize_base_url(url: str) -> str:
+    return url[:-1] if url.endswith("/") else url
+
+
+class HttpClient:
+    """Thin httpx wrapper. Not part of the public API."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        connect_timeout: float = 10.0,
+        request_timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        if not base_url:
+            raise ValueError("base_url must not be empty")
+        if not api_key:
+            raise ValueError("api_key must not be empty")
+        self.base_url = _normalize_base_url(base_url)
+        self.api_key = api_key
+        timeout = httpx.Timeout(request_timeout, connect=connect_timeout)
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={"Api-Key": api_key},
+            transport=transport,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> HttpClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        if response.status_code >= 400:
+            body = response.text
+            logger.error(
+                "HTTP %s on %s %s: %s",
+                response.status_code,
+                response.request.method,
+                response.request.url,
+                body,
+            )
+            raise error_for_status(response.status_code, body)
+
+    def get_json(self, path: str) -> Any:
+        try:
+            response = self._client.get(path, headers={"Content-Type": "application/json"})
+        except httpx.HTTPError as e:
+            raise ContinuumError(f"Request failed: {e}") from e
+        self._raise_for_status(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    def get_bytes(self, path: str) -> tuple[bytes, str] | None:
+        """Returns (data, content_type) tuple, or None on 204."""
+        try:
+            response = self._client.get(path)
+        except httpx.HTTPError as e:
+            raise ContinuumError(f"Request failed: {e}") from e
+        if response.status_code == 204:
+            return None
+        self._raise_for_status(response)
+        mime = response.headers.get("Content-Type", "application/octet-stream")
+        return response.content, mime
+
+    def post_json(self, path: str, body: Any) -> Any:
+        payload = json.dumps(body, default=_json_default) if body is not None else "{}"
+        try:
+            response = self._client.post(
+                path,
+                content=payload,
+                headers={"Content-Type": "application/json"},
+            )
+        except httpx.HTTPError as e:
+            raise ContinuumError(f"Request failed: {e}") from e
+        self._raise_for_status(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    def post_optional(self, path: str, body: Any) -> Any | None:
+        """POST that may return 204 No Content (e.g. claim)."""
+        return self.post_json(path, body)
+
+    def patch_json(self, path: str, body: Any) -> Any:
+        payload = json.dumps(body, default=_json_default) if body is not None else "{}"
+        try:
+            response = self._client.request(
+                "PATCH",
+                path,
+                content=payload,
+                headers={"Content-Type": "application/json"},
+            )
+        except httpx.HTTPError as e:
+            raise ContinuumError(f"Request failed: {e}") from e
+        self._raise_for_status(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+
+def _json_default(obj: Any) -> Any:
+    """Fallback JSON encoder for UUIDs, datetimes, enums."""
+    import datetime as _dt
+    import enum as _enum
+    import uuid as _uuid
+
+    if isinstance(obj, _uuid.UUID):
+        return str(obj)
+    if isinstance(obj, _dt.datetime):
+        return obj.isoformat()
+    if isinstance(obj, _enum.Enum):
+        return obj.value
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+
+def drop_none(d: dict[str, Any]) -> dict[str, Any]:
+    """Strip None values from a dict (mirrors @JsonInclude.NON_NULL)."""
+    return {k: v for k, v in d.items() if v is not None}

continuum_task_server/_stomp.py

@@ -0,0 +1,137 @@
+"""STOMP 1.2 frame codec. Internal."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+NULL = "\x00"
+LF = "\n"
+
+_ESCAPE = {
+    "\\": "\\\\",
+    "\r": "\\r",
+    "\n": "\\n",
+    ":": "\\c",
+}
+_UNESCAPE = {
+    "\\\\": "\\",
+    "\\r": "\r",
+    "\\n": "\n",
+    "\\c": ":",
+}
+
+
+@dataclass
+class StompFrame:
+    command: str
+    headers: dict[str, str] = field(default_factory=dict)
+    body: str = ""
+
+
+def encode_frame(frame: StompFrame) -> str:
+    """Serialize a STOMP frame including the terminating NUL."""
+    lines = [frame.command]
+    headers = dict(frame.headers)
+    body = frame.body or ""
+    if body and "content-length" not in {k.lower() for k in headers}:
+        headers["content-length"] = str(len(body.encode("utf-8")))
+    for key, value in headers.items():
+        lines.append(f"{_escape(key)}:{_escape(value)}")
+    return LF.join(lines) + LF + LF + body + NULL
+
+
+def encode_heartbeat() -> str:
+    return LF
+
+
+def _escape(text: str) -> str:
+    out: list[str] = []
+    for ch in text:
+        out.append(_ESCAPE.get(ch, ch))
+    return "".join(out)
+
+
+def _unescape(text: str) -> str:
+    out: list[str] = []
+    i = 0
+    while i < len(text):
+        if text[i] == "\\" and i + 1 < len(text):
+            pair = text[i : i + 2]
+            if pair in _UNESCAPE:
+                out.append(_UNESCAPE[pair])
+                i += 2
+                continue
+        out.append(text[i])
+        i += 1
+    return "".join(out)
+
+
+class StompDecoder:
+    """Incremental decoder for one or more STOMP frames, including heartbeats."""
+
+    def __init__(self) -> None:
+        self._buffer = ""
+
+    def feed(self, data: str | bytes) -> list[StompFrame | None]:
+        """Return complete frames. ``None`` entries are heartbeat newlines."""
+        if isinstance(data, bytes):
+            chunk = data.decode("utf-8")
+        else:
+            chunk = data
+        self._buffer += chunk
+        frames: list[StompFrame | None] = []
+        while self._buffer:
+            if self._buffer[0] in "\r\n":
+                if self._buffer.startswith("\r\n"):
+                    self._buffer = self._buffer[2:]
+                else:
+                    self._buffer = self._buffer[1:]
+                frames.append(None)
+                continue
+            nul = self._buffer.find(NULL)
+            if nul < 0:
+                break
+            raw = self._buffer[:nul]
+            self._buffer = self._buffer[nul + 1 :]
+            if raw.startswith("\r\n"):
+                raw = raw[2:]
+            elif raw.startswith("\n"):
+                raw = raw[1:]
+            if raw == "":
+                frames.append(None)
+                continue
+            frames.append(_parse_frame(raw))
+        return frames
+
+
+def _parse_frame(raw: str) -> StompFrame:
+    header_end = raw.find("\n\n")
+    if header_end < 0:
+        header_block = raw
+        body = ""
+    else:
+        header_block = raw[:header_end]
+        body = raw[header_end + 2 :]
+    lines = header_block.split("\n")
+    command = lines[0].strip()
+    headers: dict[str, str] = {}
+    content_length: int | None = None
+    for line in lines[1:]:
+        if not line:
+            continue
+        idx = line.find(":")
+        if idx < 0:
+            continue
+        key = _unescape(line[:idx])
+        value = _unescape(line[idx + 1 :])
+        if key.lower() == "content-length":
+            try:
+                content_length = int(value)
+            except ValueError:
+                content_length = None
+        if key not in headers:
+            headers[key] = value
+    if content_length is not None:
+        encoded = body.encode("utf-8")
+        body = encoded[:content_length].decode("utf-8")
+    return StompFrame(command=command, headers=headers, body=body)

continuum_task_server/client.py

@@ -0,0 +1,351 @@
+"""ContinuumClient - pythonic mirror of the Java SDK."""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any
+from urllib.parse import quote
+from uuid import UUID
+
+import httpx
+
+from ._http import HttpClient, drop_none
+from .models import Content, QueueItem, TaskItem, TaskItemVersion, TaskStatus, TaskType
+
+
+def _encode_input(data: Any) -> str | None:
+    """Accept dict/list/str/None and return a JSON string (or None)."""
+    if data is None:
+        return None
+    if isinstance(data, str):
+        return data
+    return json.dumps(data)
+
+
+class TaskTypesApi:
+    _PATH = "/api/management/task-types"
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self) -> list[TaskType]:
+        data = self._http.get_json(self._PATH) or []
+        return [TaskType.model_validate(item) for item in data]
+
+    def get_by_id(self, task_type_id: UUID | str) -> TaskType:
+        return TaskType.model_validate(self._http.get_json(f"{self._PATH}/{task_type_id}"))
+
+    def get_by_name(self, name: str) -> TaskType:
+        return TaskType.model_validate(
+            self._http.get_json(f"{self._PATH}/by-name?name={quote(name)}")
+        )
+
+    def save(
+        self,
+        *,
+        id: UUID | str | None = None,
+        name: str | None = None,
+        description: str | None = None,
+        active_flag: bool | None = None,
+        organization_id: UUID | str | None = None,
+        is_core: bool | None = None,
+        max_duration_sec: int | None = None,
+        heartbeat_timeout_sec: int | None = None,
+    ) -> TaskType:
+        """Create (no id) or update (with id) a task type."""
+        body = drop_none(
+            {
+                "id": str(id) if id else None,
+                "name": name,
+                "description": description,
+                "activeFlag": active_flag,
+                "organizationId": str(organization_id) if organization_id else None,
+                "isCore": is_core,
+                "maxDurationSec": max_duration_sec,
+                "heartbeatTimeoutSec": heartbeat_timeout_sec,
+            }
+        )
+        return TaskType.model_validate(self._http.post_json(self._PATH, body))
+
+    def create(
+        self,
+        name: str,
+        *,
+        organization_id: UUID | str | None = None,
+        is_core: bool = False,
+        **kwargs: Any,
+    ) -> TaskType:
+        return self.save(
+            name=name,
+            organization_id=organization_id,
+            is_core=is_core,
+            **kwargs,
+        )
+
+
+class TaskItemVersionsApi:
+    _PATH = "/api/management/task-items"
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self, task_item_id: UUID | str) -> list[TaskItemVersion]:
+        data = self._http.get_json(f"{self._PATH}/{task_item_id}/versions") or []
+        return [TaskItemVersion.model_validate(item) for item in data]
+
+    def get_by_id(self, version_id: UUID | str) -> TaskItemVersion:
+        return TaskItemVersion.model_validate(
+            self._http.get_json(f"{self._PATH}/versions/{version_id}")
+        )
+
+    def create(
+        self,
+        task_item_id: UUID | str,
+        *,
+        main_path: str,
+        item_definition: str | dict | list | None = None,
+        content: bytes | None = None,
+        mime_type: str | None = None,
+    ) -> TaskItemVersion:
+        body: dict[str, Any] = {"mainPath": main_path}
+        if item_definition is not None:
+            body["itemDefinition"] = (
+                item_definition if isinstance(item_definition, str) else json.dumps(item_definition)
+            )
+        if content is not None:
+            body["contentBytes"] = base64.b64encode(content).decode("ascii")
+            if mime_type:
+                body["mimeType"] = mime_type
+        elif mime_type:
+            body["mimeType"] = mime_type
+
+        return TaskItemVersion.model_validate(
+            self._http.post_json(f"{self._PATH}/{task_item_id}/versions", body)
+        )
+
+    def update(
+        self,
+        task_item_id: UUID | str,
+        version_id: UUID | str,
+        *,
+        main_path: str | None = None,
+        item_definition: str | dict | list | None = None,
+        active_flag: bool | None = None,
+    ) -> TaskItemVersion:
+        body = drop_none(
+            {
+                "mainPath": main_path,
+                "itemDefinition": (
+                    item_definition
+                    if item_definition is None or isinstance(item_definition, str)
+                    else json.dumps(item_definition)
+                ),
+                "activeFlag": active_flag,
+            }
+        )
+        return TaskItemVersion.model_validate(
+            self._http.post_json(f"{self._PATH}/versions/{version_id}", body)
+        )
+
+    def deactivate(self, task_item_id: UUID | str, version_id: UUID | str) -> TaskItemVersion:
+        return self.update(task_item_id, version_id, active_flag=False)
+
+
+class TaskItemsApi:
+    _PATH = "/api/management/task-items"
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+        self.versions = TaskItemVersionsApi(http)
+
+    def list(self) -> list[TaskItem]:
+        data = self._http.get_json(self._PATH) or []
+        return [TaskItem.model_validate(item) for item in data]
+
+    def get_by_id(self, task_item_id: UUID | str) -> TaskItem:
+        return TaskItem.model_validate(self._http.get_json(f"{self._PATH}/{task_item_id}"))
+
+    def get_by_name(self, name: str) -> TaskItem:
+        return TaskItem.model_validate(
+            self._http.get_json(f"{self._PATH}/by-name?name={quote(name)}")
+        )
+
+    def create(
+        self,
+        name: str,
+        *,
+        organization_id: UUID | str | None = None,
+        task_type_id: UUID | str | None = None,
+        is_core: bool = False,
+    ) -> TaskItem:
+        body = drop_none(
+            {
+                "name": name,
+                "isCore": is_core,
+                "organizationId": str(organization_id) if organization_id else None,
+                "taskTypeId": str(task_type_id) if task_type_id else None,
+            }
+        )
+        return TaskItem.model_validate(self._http.post_json(self._PATH, body))
+
+    def update(
+        self,
+        task_item_id: UUID | str,
+        *,
+        name: str | None = None,
+        active_flag: bool | None = None,
+        task_type_id: UUID | str | None = None,
+    ) -> TaskItem:
+        body = drop_none(
+            {
+                "name": name,
+                "activeFlag": active_flag,
+                "taskTypeId": str(task_type_id) if task_type_id else None,
+            }
+        )
+        return TaskItem.model_validate(self._http.post_json(f"{self._PATH}/{task_item_id}", body))
+
+    def publish_version(self, task_item_id: UUID | str, version_id: UUID | str) -> TaskItem:
+        return TaskItem.model_validate(
+            self._http.post_json(
+                f"{self._PATH}/{task_item_id}/publish",
+                {"versionId": str(version_id)},
+            )
+        )
+
+
+class QueueApi:
+    _MGMT = "/api/management/queue-items"
+    _QUEUE = "/api/queue"
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def add(
+        self,
+        *,
+        task_name: str | None = None,
+        task_item_name: str | None = None,
+        input_data: Any = None,
+        priority: int | None = None,
+        parent_id: UUID | str | None = None,
+        idempotency_token: str | None = None,
+    ) -> QueueItem:
+        """Add a queue item. At least one of task_name or task_item_name is required."""
+        if task_name is None and task_item_name is None:
+            raise ValueError("at least one of task_name or task_item_name is required")
+        body = drop_none(
+            {
+                "parent_id": str(parent_id) if parent_id else None,
+                "taskName": task_name,
+                "taskItemName": task_item_name,
+                "priority": priority,
+                "inputData": _encode_input(input_data),
+                "idempotencyToken": idempotency_token,
+            }
+        )
+        return QueueItem.model_validate(self._http.post_json(self._MGMT, body))
+
+    def get_by_id(self, queue_item_id: UUID | str) -> QueueItem:
+        return QueueItem.model_validate(self._http.get_json(f"{self._MGMT}/{queue_item_id}"))
+
+    def get_content(self, queue_item_id: UUID | str) -> Content | None:
+        result = self._http.get_bytes(f"{self._QUEUE}/queue-items/{queue_item_id}/content")
+        if result is None:
+            return None
+        data, mime = result
+        return Content(data=data, mime_type=mime)
+
+    def claim(self, task_name: str) -> QueueItem | None:
+        """Claim one OPEN queue item for the given task name. Returns None if none available."""
+        result = self._http.post_optional(f"{self._QUEUE}/claim", {"taskName": task_name})
+        if result is None:
+            return None
+        return QueueItem.model_validate(result)
+
+    def heartbeat(self, queue_item_id: UUID | str) -> QueueItem:
+        return QueueItem.model_validate(
+            self._http.post_json(f"{self._QUEUE}/queue-items/{queue_item_id}/heartbeat", {})
+        )
+
+    def update_status(
+        self,
+        queue_item_id: UUID | str,
+        status: TaskStatus,
+        *,
+        output_data: Any = None,
+    ) -> QueueItem:
+        # Server expects `status` on this endpoint (not `taskStatus` on queue item JSON).
+        body: dict[str, Any] = {"status": status.value}
+        encoded = _encode_input(output_data)
+        if encoded is not None:
+            body["outputData"] = encoded
+        return QueueItem.model_validate(
+            self._http.post_json(f"{self._QUEUE}/queue-items/{queue_item_id}/status", body)
+        )
+
+
+class ContentStoreApi:
+    _PATH = "/api/management/content-store"
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def get_by_id(self, content_id: UUID | str) -> Content | None:
+        result = self._http.get_bytes(f"{self._PATH}/{content_id}")
+        if result is None:
+            return None
+        data, mime = result
+        return Content(data=data, mime_type=mime)
+
+    def get_by_url(self, content_url: str) -> Content | None:
+        result = self._http.get_bytes(f"{self._PATH}?url={quote(content_url, safe='')}")
+        if result is None:
+            return None
+        data, mime = result
+        return Content(data=data, mime_type=mime)
+
+
+class ContinuumClient:
+    """Client for the Continuum Task Server.
+
+    Example:
+        >>> client = ContinuumClient(base_url="http://localhost:8080", api_key="...")
+        >>> task_types = client.task_types.list()
+        >>> item = client.queue.claim("echo")
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        connect_timeout: float = 10.0,
+        request_timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._http = HttpClient(
+            base_url=base_url,
+            api_key=api_key,
+            connect_timeout=connect_timeout,
+            request_timeout=request_timeout,
+            transport=transport,
+        )
+        self.task_types = TaskTypesApi(self._http)
+        self.task_items = TaskItemsApi(self._http)
+        self.queue = QueueApi(self._http)
+        self.content_store = ContentStoreApi(self._http)
+
+    @property
+    def base_url(self) -> str:
+        return self._http.base_url
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> ContinuumClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()