workhold-client-core 1.0.0__py3-none-any.whl

_workhold_client_core/__init__.py

@@ -0,0 +1,115 @@
+"""Private shared Queue client primitives (not a public role API surface)."""
+
+from __future__ import annotations
+
+from _workhold_client_core.capabilities import Capabilities
+from _workhold_client_core.codecs import (
+    PayloadDecodeError,
+    PayloadDecoder,
+    PayloadEncoder,
+    TypedClaimView,
+    TypedTaskView,
+    decode_payload,
+    encode_payload,
+    measure_json_bytes,
+)
+from _workhold_client_core.errors import (
+    AuthenticationError,
+    ErrorCode,
+    LeaseLostError,
+    MalformedResponseError,
+    ProtocolError,
+    QueueClientError,
+    RequestCancelledError,
+    TerminalConflictError,
+    TimeoutError,
+    TransportError,
+    raise_for_protocol_status,
+)
+from _workhold_client_core.models import (
+    AckCancelResult,
+    CancelResponse,
+    ClaimSummary,
+    CompleteResult,
+    EnqueueResponse,
+    FailResult,
+    HeartbeatResult,
+    ProtocolErrorBody,
+    ResolveSubmissionResponse,
+    Task,
+    TaskState,
+)
+from _workhold_client_core.priority import (
+    PRIORITY_DEFAULT,
+    PRIORITY_MAX,
+    PRIORITY_MIN,
+    validate_priority,
+)
+from _workhold_client_core.redaction import (
+    REDACTED,
+    redact_headers,
+    redact_text,
+    sanitize_for_diagnostics,
+)
+from _workhold_client_core.config import ClientConfig
+from _workhold_client_core.requests import PreparedRequest, prepare_json_request
+from _workhold_client_core.transport import (
+    AsyncTransport,
+    HttpJsonTransport,
+    SyncTransport,
+    TransportResponse,
+    encode_path_segment,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "AckCancelResult",
+    "AsyncTransport",
+    "AuthenticationError",
+    "CancelResponse",
+    "Capabilities",
+    "ClientConfig",
+    "ClaimSummary",
+    "CompleteResult",
+    "EnqueueResponse",
+    "ErrorCode",
+    "FailResult",
+    "HeartbeatResult",
+    "HttpJsonTransport",
+    "LeaseLostError",
+    "PayloadDecodeError",
+    "PayloadDecoder",
+    "PayloadEncoder",
+    "PreparedRequest",
+    "MalformedResponseError",
+    "PRIORITY_DEFAULT",
+    "PRIORITY_MAX",
+    "PRIORITY_MIN",
+    "ProtocolError",
+    "ProtocolErrorBody",
+    "QueueClientError",
+    "RequestCancelledError",
+    "SyncTransport",
+    "REDACTED",
+    "ResolveSubmissionResponse",
+    "Task",
+    "TaskState",
+    "TerminalConflictError",
+    "TimeoutError",
+    "TransportError",
+    "TransportResponse",
+    "TypedClaimView",
+    "TypedTaskView",
+    "decode_payload",
+    "encode_path_segment",
+    "encode_payload",
+    "measure_json_bytes",
+    "prepare_json_request",
+    "raise_for_protocol_status",
+    "redact_headers",
+    "redact_text",
+    "sanitize_for_diagnostics",
+    "validate_priority",
+    "__version__",
+]

_workhold_client_core/async_transport.py

@@ -0,0 +1,68 @@
+"""Compatibility shim: URL-based async transport for 20-02 role clients."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from _workhold_client_core.config import ClientConfig
+from _workhold_client_core.transport import AsyncTransport, TransportResponse
+from _workhold_client_core.transport_async import HttpxAsyncTransport as _CoreHttpx
+
+__all__ = ["AsyncTransport", "HttpxAsyncTransport"]
+
+
+class HttpxAsyncTransport:
+    """Adapter over core ``HttpxAsyncTransport`` using a public base URL."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        timeout_s: float = 30.0,
+        client: object | None = None,
+        config: ClientConfig | None = None,
+    ) -> None:
+        if config is None:
+            config = ClientConfig(
+                public_base_url=base_url,
+                read_timeout_s=timeout_s,
+                total_timeout_s=timeout_s,
+            )
+        self._inner = _CoreHttpx(config, client=client)
+        self._timeout_s = timeout_s
+
+    @property
+    def timeout_s(self) -> float:
+        return self._timeout_s
+
+    @property
+    def config(self) -> ClientConfig:
+        return self._inner.config
+
+    async def aclose(self) -> None:
+        await self._inner.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        json_body: object | None = None,
+        query: Mapping[str, str] | None = None,
+        expect_body: bool = True,
+        read_timeout_s: float | None = None,
+        total_timeout_s: float | None = None,
+        cancellation: object | None = None,
+    ) -> TransportResponse:
+        return await self._inner.request(
+            method,
+            path,
+            headers=headers,
+            json_body=json_body,
+            query=query,
+            expect_body=expect_body,
+            read_timeout_s=read_timeout_s,
+            total_timeout_s=total_timeout_s,
+            cancellation=cancellation,
+        )

_workhold_client_core/capabilities.py

@@ -0,0 +1,135 @@
+"""Tolerant OpenAPI ``Capabilities`` wire parsing."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Final
+
+_REQUIRED: Final[frozenset[str]] = frozenset(
+    {
+        "protocol_major",
+        "protocol_version",
+        "schema_revision",
+        "scheduling",
+        "priority",
+        "delivery_events",
+        "batch_claim",
+        "long_polling",
+        "max_claim_tasks",
+        "max_wait_seconds",
+        "payload_runtime_max_bytes",
+        "payload_hard_max_bytes",
+        "enqueue_dedup_ttl_seconds",
+        "enqueue_dedup_ttl_min_seconds",
+        "enqueue_dedup_ttl_max_seconds",
+        "terminal_replay_ttl_seconds",
+        "terminal_replay_ttl_min_seconds",
+        "terminal_replay_ttl_max_seconds",
+        "admin_replay_ttl_seconds",
+        "admin_replay_ttl_min_seconds",
+        "admin_replay_ttl_max_seconds",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Capabilities:
+    """Capabilities resource; additive fields land in ``extra``."""
+
+    protocol_major: int
+    protocol_version: str
+    schema_revision: str
+    scheduling: bool
+    priority: bool
+    delivery_events: bool
+    batch_claim: bool
+    long_polling: bool
+    max_claim_tasks: int
+    max_wait_seconds: int
+    payload_runtime_max_bytes: int
+    payload_hard_max_bytes: int
+    enqueue_dedup_ttl_seconds: int
+    enqueue_dedup_ttl_min_seconds: int
+    enqueue_dedup_ttl_max_seconds: int
+    terminal_replay_ttl_seconds: int
+    terminal_replay_ttl_min_seconds: int
+    terminal_replay_ttl_max_seconds: int
+    admin_replay_ttl_seconds: int
+    admin_replay_ttl_min_seconds: int
+    admin_replay_ttl_max_seconds: int
+    extra: Mapping[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def parse(cls, raw: object) -> Capabilities:
+        if not isinstance(raw, Mapping):
+            raise ValueError("capabilities must be an object")
+        missing = sorted(_REQUIRED - set(raw))
+        if missing:
+            raise ValueError(f"capabilities missing required fields: {missing}")
+
+        extra = {k: v for k, v in raw.items() if k not in _REQUIRED}
+        return cls(
+            protocol_major=_require_int(raw["protocol_major"], "protocol_major"),
+            protocol_version=_require_str(raw["protocol_version"], "protocol_version"),
+            schema_revision=_require_str(raw["schema_revision"], "schema_revision"),
+            scheduling=_require_bool(raw["scheduling"], "scheduling"),
+            priority=_require_bool(raw["priority"], "priority"),
+            delivery_events=_require_bool(raw["delivery_events"], "delivery_events"),
+            batch_claim=_require_bool(raw["batch_claim"], "batch_claim"),
+            long_polling=_require_bool(raw["long_polling"], "long_polling"),
+            max_claim_tasks=_require_int(raw["max_claim_tasks"], "max_claim_tasks"),
+            max_wait_seconds=_require_int(raw["max_wait_seconds"], "max_wait_seconds"),
+            payload_runtime_max_bytes=_require_int(
+                raw["payload_runtime_max_bytes"], "payload_runtime_max_bytes"
+            ),
+            payload_hard_max_bytes=_require_int(
+                raw["payload_hard_max_bytes"], "payload_hard_max_bytes"
+            ),
+            enqueue_dedup_ttl_seconds=_require_int(
+                raw["enqueue_dedup_ttl_seconds"], "enqueue_dedup_ttl_seconds"
+            ),
+            enqueue_dedup_ttl_min_seconds=_require_int(
+                raw["enqueue_dedup_ttl_min_seconds"], "enqueue_dedup_ttl_min_seconds"
+            ),
+            enqueue_dedup_ttl_max_seconds=_require_int(
+                raw["enqueue_dedup_ttl_max_seconds"], "enqueue_dedup_ttl_max_seconds"
+            ),
+            terminal_replay_ttl_seconds=_require_int(
+                raw["terminal_replay_ttl_seconds"], "terminal_replay_ttl_seconds"
+            ),
+            terminal_replay_ttl_min_seconds=_require_int(
+                raw["terminal_replay_ttl_min_seconds"], "terminal_replay_ttl_min_seconds"
+            ),
+            terminal_replay_ttl_max_seconds=_require_int(
+                raw["terminal_replay_ttl_max_seconds"], "terminal_replay_ttl_max_seconds"
+            ),
+            admin_replay_ttl_seconds=_require_int(
+                raw["admin_replay_ttl_seconds"], "admin_replay_ttl_seconds"
+            ),
+            admin_replay_ttl_min_seconds=_require_int(
+                raw["admin_replay_ttl_min_seconds"], "admin_replay_ttl_min_seconds"
+            ),
+            admin_replay_ttl_max_seconds=_require_int(
+                raw["admin_replay_ttl_max_seconds"], "admin_replay_ttl_max_seconds"
+            ),
+            extra=dict(extra),
+        )
+
+
+def _require_str(value: object, name: str) -> str:
+    if not isinstance(value, str):
+        raise ValueError(f"{name} must be a string")
+    return value
+
+
+def _require_int(value: object, name: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(f"{name} must be an integer")
+    return value
+
+
+def _require_bool(value: object, name: str) -> bool:
+    if not isinstance(value, bool):
+        raise ValueError(f"{name} must be a boolean")
+    return value

_workhold_client_core/capability_guard.py

@@ -0,0 +1,92 @@
+"""Fail-closed capability gates for reserved protocol features."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from _workhold_client_core.capabilities import Capabilities
+
+__all__ = [
+    "require_batch_claim",
+    "require_delivery_events",
+    "require_long_polling",
+]
+
+
+def require_long_polling(capabilities: Capabilities, wait_seconds: int) -> None:
+    """Require authenticated live long-polling for positive waits.
+
+    ``wait_seconds == 0`` bypasses the feature guard (immediate claim).
+    Malformed waits and incomplete advertisements fail closed before HTTP.
+    """
+
+    if isinstance(wait_seconds, bool) or type(wait_seconds) is not int:
+        raise ValueError("wait_seconds must be an integer")
+    if wait_seconds < 0:
+        raise ValueError("wait_seconds must be >= 0")
+    if wait_seconds == 0:
+        return
+    if not capabilities.long_polling:
+        raise ValueError("long_polling capability is not enabled")
+    if capabilities.max_wait_seconds <= 0:
+        raise ValueError(
+            "max_wait_seconds must be positive when long_polling is enabled"
+        )
+    if wait_seconds > capabilities.max_wait_seconds:
+        raise ValueError(
+            f"wait_seconds {wait_seconds} exceeds max_wait_seconds "
+            f"{capabilities.max_wait_seconds}"
+        )
+
+
+def require_batch_claim(capabilities: Capabilities, max_tasks: int) -> None:
+    """Fail closed for ``max_tasks>1`` unless live ``batch_claim`` advertises it.
+
+    ``max_tasks == 1`` is always the MVP path and does not require batch_claim.
+    """
+
+    if isinstance(max_tasks, bool) or type(max_tasks) is not int:
+        raise ValueError("max_tasks must be an integer")
+    if max_tasks < 1:
+        raise ValueError("max_tasks must be >= 1")
+    if max_tasks == 1:
+        if not capabilities.batch_claim and capabilities.max_claim_tasks != 1:
+            raise ValueError("max_claim_tasks must be 1 while batch_claim is disabled")
+        if capabilities.batch_claim and capabilities.max_claim_tasks < 1:
+            raise ValueError(
+                "max_claim_tasks must be positive when batch_claim is enabled"
+            )
+        return
+    if not capabilities.batch_claim:
+        raise ValueError("batch_claim capability is not enabled")
+    if capabilities.max_claim_tasks < 1:
+        raise ValueError("max_claim_tasks must be positive when batch_claim is enabled")
+    if max_tasks > capabilities.max_claim_tasks:
+        raise ValueError(
+            f"max_tasks {max_tasks} exceeds max_claim_tasks "
+            f"{capabilities.max_claim_tasks}"
+        )
+
+
+def require_delivery_events(
+    capabilities: Capabilities,
+    events: Sequence[Mapping[str, Any]] | None,
+) -> None:
+    """Fail closed for non-empty ``complete.events[]`` unless advertised.
+
+    Empty/omitted ``events`` bypasses the guard (MVP complete without events).
+    When enabled, each event must be a JSON object (reserved OpenAPI shape).
+    """
+
+    if events is None:
+        return
+    if not isinstance(events, Sequence) or isinstance(events, (str, bytes, bytearray)):
+        raise ValueError("events must be a sequence of objects")
+    if len(events) == 0:
+        return
+    if not capabilities.delivery_events:
+        raise ValueError("delivery_events capability is not enabled")
+    for index, event in enumerate(events):
+        if not isinstance(event, Mapping):
+            raise ValueError(f"events[{index}] must be an object")

_workhold_client_core/codecs.py

@@ -0,0 +1,182 @@
+"""Opt-in typed payload codecs that preserve opaque JSON wire values."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Generic, Protocol, TypeVar
+
+from _workhold_client_core.errors import QueueClientError
+from _workhold_client_core.models import Task
+
+__all__ = [
+    "PayloadDecodeError",
+    "PayloadDecoder",
+    "PayloadEncoder",
+    "TypedClaimView",
+    "TypedTaskView",
+    "decode_payload",
+    "encode_payload",
+    "measure_json_bytes",
+]
+
+T = TypeVar("T")
+T_contra = TypeVar("T_contra", contravariant=True)
+T_co = TypeVar("T_co", covariant=True)
+
+
+class PayloadEncoder(Protocol[T_contra]):
+    """Encode an application value into a JSON-serializable wire payload."""
+
+    @property
+    def codec_name(self) -> str: ...
+
+    def encode(self, value: T_contra) -> Any: ...
+
+
+class PayloadDecoder(Protocol[T_co]):
+    """Decode an opaque JSON wire payload into an application value."""
+
+    @property
+    def codec_name(self) -> str: ...
+
+    @property
+    def value_type(self) -> str: ...
+
+    def decode(self, raw: Any) -> T_co: ...
+
+
+class PayloadDecodeError(QueueClientError):
+    """Bounded decode failure: codec/type metadata only; raw kept for recovery."""
+
+    def __init__(
+        self,
+        *,
+        codec_name: str,
+        value_type: str,
+        raw: Any,
+        reason: str = "decode_failed",
+    ) -> None:
+        self.codec_name = codec_name
+        self.value_type = value_type
+        self._raw = raw
+        self.reason = reason
+        super().__init__(reason)
+
+    @property
+    def raw(self) -> Any:
+        """Explicit recovery access to the opaque wire value (never logged here)."""
+
+        return self._raw
+
+    def __str__(self) -> str:
+        return (
+            f"PayloadDecodeError(codec_name={self.codec_name!r}, "
+            f"value_type={self.value_type!r}, reason={self.reason!r})"
+        )
+
+    def __repr__(self) -> str:
+        return self.__str__()
+
+
+def measure_json_bytes(value: Any) -> int:
+    """Byte size of a JSON value using the same compact encoding as admission."""
+
+    return len(
+        json.dumps(
+            value,
+            ensure_ascii=False,
+            separators=(",", ":"),
+            allow_nan=False,
+            sort_keys=True,
+        ).encode("utf-8")
+    )
+
+
+def encode_payload(
+    value: Any,
+    encoder: PayloadEncoder[Any] | None = None,
+    *,
+    max_bytes: int | None = None,
+) -> Any:
+    """Encode (optional) then enforce payload size before the HTTP request body.
+
+    Default ``encoder is None`` keeps the application value as the opaque wire
+    JSON payload unchanged.
+    """
+
+    wire = value if encoder is None else encoder.encode(value)
+    if max_bytes is not None:
+        if isinstance(max_bytes, bool) or type(max_bytes) is not int or max_bytes < 1:
+            raise ValueError("max_bytes must be a positive integer")
+        try:
+            size = measure_json_bytes(wire)
+        except (TypeError, ValueError) as exc:
+            raise ValueError("payload must be a JSON value") from exc
+        if size > max_bytes:
+            raise ValueError(
+                f"payload exceeds max_bytes ({size} > {max_bytes})"
+            )
+    return wire
+
+
+def decode_payload(
+    raw: Any,
+    decoder: PayloadDecoder[T] | None = None,
+) -> Any:
+    """Decode an opaque wire payload; default returns the raw JSON value."""
+
+    if decoder is None:
+        return raw
+    try:
+        return decoder.decode(raw)
+    except PayloadDecodeError:
+        raise
+    except Exception as exc:
+        raise PayloadDecodeError(
+            codec_name=decoder.codec_name,
+            value_type=decoder.value_type,
+            raw=raw,
+            reason=type(exc).__name__,
+        ) from exc
+
+
+@dataclass(frozen=True, slots=True)
+class TypedTaskView(Generic[T]):
+    """Task plus decoded application payload; ``raw_payload`` is the wire value."""
+
+    task: Task
+    payload: T
+    raw_payload: Any
+
+    @classmethod
+    def from_task(cls, task: Task, decoder: PayloadDecoder[T]) -> TypedTaskView[T]:
+        raw = task.payload
+        return cls(task=task, payload=decode_payload(raw, decoder), raw_payload=raw)
+
+
+@dataclass(frozen=True, slots=True)
+class TypedClaimView(Generic[T]):
+    """Claim handle plus decoded application payload; wire value preserved."""
+
+    claim: Any
+    payload: T
+    raw_payload: Any
+
+    @classmethod
+    def from_claim(
+        cls,
+        claim: Any,
+        decoder: PayloadDecoder[T] | None = None,
+    ) -> TypedClaimView[T]:
+        raw = claim.task.payload
+        active = decoder
+        if active is None:
+            active = getattr(claim, "payload_decoder", None)
+        if active is None:
+            raise ValueError("payload_decoder is required when claim has none")
+        return cls(
+            claim=claim,
+            payload=decode_payload(raw, active),
+            raw_payload=raw,
+        )