ledgence-client 0.1.1__py3-none-any.whl

ledgence/client/__init__.py

@@ -0,0 +1,52 @@
+"""Asynchronous task orchestration client for Ledgence (MIT)."""
+from ._version import __version__
+from .client import AsyncClient
+from .errors import (
+    CancellationUncertain, ClientClosed, Conflict, InputError, LedgenceError, NotFound,
+    ProtocolError, RequestTimeout, ServiceError, SubmissionUncertain, TaskCancelled,
+    TaskFailed, TransportError, Unavailable, WaitTimeout,
+)
+from .models import (
+    ApplicationFailure, AttemptLost, Cancelled, ErrorDetail, ExecutionFailure, Failed,
+    Quiescence, RetryPolicy, Scope, Submission, Succeeded, TaskResult, TaskState,
+    TaskPage, TaskStatus, TraceContext,
+)
+from .tasks import TaskHandle
+
+__all__ = [
+    "__version__", "AsyncClient", "TaskHandle", "Submission", "Scope", "RetryPolicy", "TraceContext",
+    "TaskState", "TaskStatus", "TaskPage", "TaskResult", "Quiescence", "Succeeded", "Failed", "Cancelled",
+    "ApplicationFailure", "ExecutionFailure", "AttemptLost", "ErrorDetail", "LedgenceError",
+    "InputError", "NotFound", "Conflict", "ServiceError", "TransportError", "ProtocolError",
+    "Unavailable", "RequestTimeout", "SubmissionUncertain", "CancellationUncertain",
+    "WaitTimeout", "TaskFailed", "TaskCancelled", "ClientClosed",
+]
+
+from .errors import (
+    WorkflowCancellationUncertain, WorkflowCancelled, WorkflowEventUncertain, WorkflowFailed, WorkflowWaitTimeout,
+)
+from .workflow_models import (
+    WorkflowCancellation, WorkflowFailure, WorkflowResult, WorkflowState, WorkflowStatus,
+    WorkflowSubmission, WorkflowSucceeded, WorkflowEventCommand, WorkflowEventReceipt,
+)
+from .workflows import WorkflowHandle
+
+__all__ += [
+    "WorkflowHandle", "WorkflowSubmission", "WorkflowState", "WorkflowStatus", "WorkflowResult",
+    "WorkflowSucceeded", "WorkflowFailure", "WorkflowCancellation", "WorkflowFailed",
+    "WorkflowCancelled", "WorkflowWaitTimeout", "WorkflowCancellationUncertain",
+    "WorkflowEventCommand", "WorkflowEventReceipt", "WorkflowEventUncertain",
+]
+
+from .completion_models import (
+    CompletionRetryCommand, CompletionState, CompletionSubscribeCommand,
+    CompletionSubscription, CompletionTarget,
+)
+from .completions import CompletionSubscriptionHandle
+from .errors import CompletionRetryUncertain, CompletionSubscriptionUncertain
+
+__all__ += [
+    "CompletionTarget", "CompletionState", "CompletionSubscribeCommand", "CompletionRetryCommand",
+    "CompletionSubscription", "CompletionSubscriptionHandle", "CompletionSubscriptionUncertain",
+    "CompletionRetryUncertain",
+]

ledgence/client/_version.py

@@ -0,0 +1,3 @@
+"""Distribution version shared by public diagnostics and tracing."""
+
+__version__ = "0.1.1"

ledgence/client/client.py

@@ -0,0 +1,84 @@
+"""One explicitly owned asynchronous client for a scoped Ledgence endpoint."""
+from __future__ import annotations
+
+from urllib.parse import urlsplit, urlunsplit
+
+from . import codec
+from .errors import ClientClosed, InputError
+from .models import Scope
+from .transport import _Transport
+
+
+def _endpoint(value: str) -> str:
+    if type(value) is not str or any(ord(c) <= 0x20 or ord(c) == 0x7F for c in value):
+        raise InputError("base_url must be an HTTP(S) endpoint")
+    try:
+        parsed = urlsplit(value)
+        if parsed.scheme not in ("http", "https") or not parsed.hostname or parsed.username is not None:
+            raise ValueError("invalid endpoint")
+        if parsed.query or parsed.fragment:
+            raise ValueError("endpoint cannot contain query or fragment")
+        host = parsed.hostname.encode("idna").decode("ascii").lower()
+        if ":" in host:
+            host = f"[{host}]"
+        port = parsed.port
+        if port is not None and port != (80 if parsed.scheme == "http" else 443):
+            host += f":{port}"
+        return urlunsplit((parsed.scheme, host, parsed.path.rstrip("/"), "", ""))
+    except (ValueError, UnicodeError) as exc:
+        raise InputError("invalid base_url") from exc
+
+
+class AsyncClient:
+    """Async task and workflow client. Open with async with; all use stays on one event loop."""
+
+    def __init__(self, base_url: str, *, tenant: str, namespace: str,
+                 request_timeout: float = 30.0):
+        from .tasks import Tasks
+        from .workflows import Workflows
+        from .completions import Completions
+        self._base_url = _endpoint(base_url)
+        self._scope = Scope(tenant, namespace)
+        self._request_timeout = codec.duration(request_timeout, "request_timeout", 30.0)
+        self.tasks = Tasks(self)
+        self.workflows = Workflows(self)
+        self.completions = Completions(self)
+        self._transport: _Transport | None = None
+        self._closed = False
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    @property
+    def scope(self) -> Scope:
+        return self._scope
+
+    @property
+    def request_timeout(self) -> float:
+        return self._request_timeout
+
+    async def __aenter__(self) -> AsyncClient:
+        if self._closed or self._transport is not None:
+            raise ClientClosed("client cannot be reopened or entered twice")
+        self._transport = _Transport(self.base_url)
+        return self
+
+    async def __aexit__(self, exc_type, exc, traceback):
+        await self.close()
+
+    async def close(self) -> None:
+        """Release owned operations; remote tasks continue independently.
+
+        Running codec jobs retain ownership until complete. Cancellation of this
+        await leaves one owned close operation; await close() again to join it.
+        """
+        self._closed = True
+        if self._transport is not None:
+            await self._transport.close()
+
+    def _require_transport(self) -> _Transport:
+        if self._closed or self._transport is None:
+            raise ClientClosed("use the client inside an async with block")
+        self._transport.check_open()
+        return self._transport

ledgence/client/cloud_events.py

@@ -0,0 +1,158 @@
+"""Portable CloudEvent validation for external workflow events (MIT)."""
+import calendar
+import ipaddress
+import re
+import unicodedata
+
+from . import codec
+from .errors import InputError
+
+EVENT_LIMIT = 64 * 1024
+EVENT_COMMAND_LIMIT = 70 * 1024
+
+
+def _validate_event_uri(value, *, absolute=False):
+    """Validate RFC 3986 URI references without rewriting their identity."""
+    atom = r"(?:[A-Za-z0-9._~!$&'()*+,;=\-]|%[0-9A-Fa-f]{2})"
+    pchar = rf"(?:{atom}|[:@])"
+    path_query, fragment_mark, fragment = value.partition("#")
+    if absolute and fragment_mark:
+        raise InputError("dataschema must be an absolute URI without a fragment")
+    path, query_mark, query = path_query.partition("?")
+    if not re.fullmatch(rf"(?:{pchar}|[/?])*", fragment) or not re.fullmatch(rf"(?:{pchar}|[/?])*", query):
+        raise InputError("invalid CloudEvent URI query or fragment")
+    scheme = re.match(r"[A-Za-z][A-Za-z0-9+.-]*:", path)
+    if absolute and scheme is None:
+        raise InputError("dataschema must be an absolute URI")
+    if scheme is not None:
+        path = path[scheme.end():]
+    authority = path.startswith("//")
+    if authority:
+        host, slash, rest = path[2:].partition("/")
+        path = slash + rest
+        if "@" in host:
+            user, _, host = host.partition("@")
+            if not re.fullmatch(rf"(?:{atom}|:)*", user):
+                raise InputError("invalid CloudEvent URI user information")
+        if host.startswith("["):
+            address, close, port = host[1:].partition("]")
+            if not close or (port and not re.fullmatch(r":[0-9]*", port)):
+                raise InputError("invalid CloudEvent URI host")
+            if re.fullmatch(r"v[0-9A-Fa-f]+\.[A-Za-z0-9._~!$&'()*+,;=:\-]+", address, re.IGNORECASE) is None:
+                try:
+                    if "%" in address:
+                        raise ValueError("zone identifier is not an RFC3986 address")
+                    ipaddress.IPv6Address(address)
+                except ValueError as exc:
+                    raise InputError("invalid CloudEvent URI address") from exc
+        else:
+            name, colon, port = host.partition(":")
+            if not re.fullmatch(rf"{atom}*", name) or (colon and not re.fullmatch(r"[0-9]*", port)):
+                raise InputError("invalid CloudEvent URI host or port")
+    if not re.fullmatch(rf"(?:{pchar}|/)*", path):
+        raise InputError("invalid CloudEvent URI path")
+    if scheme is None and not authority and ":" in path.partition("/")[0]:
+        raise InputError("relative CloudEvent URI first segment cannot contain a colon")
+
+
+def _validate_event_trace(event):
+    trace = event.get("traceparent")
+    if trace is not None and (type(trace) is not str
+            or not re.fullmatch(r"00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}", trace)
+            or trace[3:35] == "0" * 32 or trace[36:52] == "0" * 16):
+        raise InputError("invalid CloudEvent traceparent")
+    if "tracestate" not in event:
+        return
+    state = event["tracestate"]
+    if trace is None or type(state) is not str or not state.isascii() or len(state) > 512:
+        raise InputError("invalid CloudEvent tracestate")
+    members = state.split(",")
+    if len(members) > 32:
+        raise InputError("too many CloudEvent tracestate members")
+    seen = set()
+    for member in members:
+        member = member.strip(" ")
+        if not member:
+            continue
+        key, equal, item = member.partition("=")
+        if (not equal or not item or len(item) > 256 or key in seen
+                or not re.fullmatch(r"(?:[a-z][a-z0-9_*/-]{0,255}|[a-z0-9][a-z0-9_*/-]{0,240}@[a-z][a-z0-9_*/-]{0,13})", key)
+                or any(not 0x20 <= ord(char) <= 0x7e or char in ",=" for char in item)):
+            raise InputError("invalid CloudEvent tracestate member")
+        seen.add(key)
+
+
+def _valid_event_leap_second(year, month, day, hour, minute, offset_minutes):
+    # Match time's final-UTC-second-of-a-month stand-in. Integer/calendar
+    # arithmetic preserves year0000 and rollover into UTC year-1, unlike datetime.
+    day_change, utc_minute = divmod(hour * 60 + minute - offset_minutes, 24 * 60)
+    if utc_minute != 23 * 60 + 59:
+        return False
+    day += day_change
+    if day < 1:
+        month -= 1
+        if month == 0:
+            year, month = year - 1, 12
+        day += calendar.monthrange(year, month)[1]
+    elif day > calendar.monthrange(year, month)[1]:
+        day -= calendar.monthrange(year, month)[1]
+        month += 1
+        if month == 13:
+            year, month = year + 1, 1
+    return -9999 <= year <= 9999 and day == calendar.monthrange(year, month)[1]
+
+
+def _validate_event_context(value):
+    # Keep this portable common profile aligned with worker-api's borrowed
+    # CloudEvent validator. Execution identity requirements do not apply here.
+    if type(value) is not dict:
+        raise InputError("CloudEvent must be an object")
+    for name, item in value.items():
+        if name == "data":
+            continue
+        if re.fullmatch(r"[a-z0-9]+", name) is None:
+            raise InputError("invalid CloudEvent context name")
+        if type(item) is str:
+            if any(unicodedata.category(c) == "Cc" or 0xFDD0 <= ord(c) <= 0xFDEF
+                   or ord(c) & 0xFFFE == 0xFFFE for c in item):
+                raise InputError("invalid CloudEvent context string")
+        elif type(item) is not bool and (type(item) is not int or not -(1 << 31) <= item < (1 << 31)):
+            raise InputError("invalid CloudEvent context value")
+    if value.get("specversion") != "1.0":
+        raise InputError("CloudEvent requires version1.0")
+    for name in ("id", "source", "type"):
+        if type(value.get(name)) is not str or not value[name]:
+            raise InputError(f"CloudEvent requires nonempty {name}")
+    _validate_event_uri(value["source"])
+    for name in ("subject", "dataschema", "time"):
+        if name in value and (type(value[name]) is not str or not value[name]):
+            raise InputError(f"CloudEvent {name} must be a nonempty string")
+    if "dataschema" in value:
+        _validate_event_uri(value["dataschema"], absolute=True)
+    if "time" in value:
+        match = re.fullmatch(r"([0-9]{4})-([0-9]{2})-([0-9]{2})[Tt]([0-9]{2}):([0-9]{2}):([0-9]{2})(?:\.[0-9]+)?(?:[Zz]|([+-])([0-9]{2}):([0-9]{2}))", value["time"])
+        if match is None:
+            raise InputError("CloudEvent time must be RFC3339")
+        year, month, day, hour, minute, second = map(int, match.groups()[:6])
+        if (not 1 <= month <= 12 or not 1 <= day <= calendar.monthrange(year, month)[1]
+                or hour > 23 or minute > 59 or second > 60
+                or (match[7] is not None and (int(match[8]) > 23 or int(match[9]) > 59))):
+            raise InputError("invalid CloudEvent RFC3339 timestamp")
+        offset = 0 if match[7] is None else (int(match[8]) * 60 + int(match[9]))
+        if match[7] == "-":
+            offset = -offset
+        if second == 60 and not _valid_event_leap_second(year, month, day, hour, minute, offset):
+            raise InputError("CloudEvent leap second must be the final UTC second of a month")
+    _validate_event_trace(value)
+    return value
+
+
+def validate_event(value):
+    codec.encode(value, EVENT_LIMIT, max_depth=96)
+    _validate_event_context(value)
+    if value.get("datacontenttype") != "application/json" or "data" not in value:
+        raise InputError("CloudEvent requires JSON data")
+    if len(value["id"].encode("utf-8")) > 128 or len(value["source"].encode("utf-8")) > 2048:
+        raise InputError("CloudEvent id/source exceed their UTF-8 byte limits")
+    codec.encode(value["data"], EVENT_LIMIT, max_depth=64)
+    return value

ledgence/client/codec.py

@@ -0,0 +1,199 @@
+"""Strict bounded JSON matching the Rust wire profile; no user coercion hooks."""
+from __future__ import annotations
+
+import json
+import math
+import unicodedata
+
+from .errors import InputError, ProtocolError
+
+DATA_LIMIT = 1024 * 1024
+CONTROL_LIMIT = 2 * 1024 * 1024
+RESPONSE_LIMIT = 16 * 1024 * 1024
+STATUS_LIMIT = 16 * 1024
+TASK_PAGE_LIMIT = 2 * 1024 * 1024
+MAX_DEPTH = 64
+# Registered controller results allow 96 metadata containers plus HTTP wrappers.
+# Endpoint parsers still enforce each application value's independent depth64.
+MAX_RESPONSE_DEPTH = 108
+# Milliseconds through the last instant with a four-digit RFC3339 year.
+MAX_TIMESTAMP = 253402300799999
+
+
+def text(value, name: str, maximum: int = 128, *, empty: bool = False,
+         noncharacters: bool = False) -> str:
+    if type(value) is not str:
+        raise InputError(f"{name} must be a string")
+    try:
+        raw = value.encode("utf-8")
+    except UnicodeError as exc:
+        raise InputError(f"{name} must contain Unicode scalar values") from exc
+    if (not empty and not raw) or len(raw) > maximum or any(
+        unicodedata.category(c) == "Cc" or (
+            not noncharacters and (0xFDD0 <= ord(c) <= 0xFDEF or ord(c) & 0xFFFE == 0xFFFE)
+        ) for c in value
+    ):
+        raise InputError(f"invalid {name}")
+    return value
+
+
+def integer(value, name: str, low: int = 0, high: int = (1 << 64) - 1) -> int:
+    if type(value) is not int or not low <= value <= high:
+        raise InputError(f"{name} must be an integer from {low} through {high}")
+    return value
+
+
+def duration(value, name: str, maximum: float | None = None) -> float:
+    if type(value) not in (int, float):
+        raise InputError(f"{name} must be a positive finite number")
+    try:
+        result = float(value)
+    except OverflowError as exc:
+        raise InputError(f"{name} is too large") from exc
+    if not math.isfinite(result) or result <= 0 or (maximum is not None and result > maximum):
+        raise InputError(f"invalid {name}")
+    return result
+
+
+def validate(value, limit: int, *, max_depth: int = MAX_DEPTH) -> None:
+    """Bound traversal as well as the eventual bytes, accepting plain JSON types."""
+    _validate(value, limit, max_depth=max_depth)
+
+
+def _validate(value, limit: int, *, max_depth: int, authoritative: bool = False) -> int:
+    remaining = limit
+    float_slack = 0
+    ancestors: set[int] = set()
+
+    def visit(item, depth):
+        nonlocal remaining, float_slack
+        remaining -= 1
+        if remaining < 0:
+            raise InputError("JSON value exceeds its byte limit")
+        kind = type(item)
+        if item is None or kind is bool:
+            return
+        if kind is str:
+            if len(item) > remaining:
+                raise InputError("JSON string exceeds its byte limit")
+            try:
+                remaining -= len(item.encode("utf-8"))
+            except UnicodeError as exc:
+                raise InputError("JSON strings must contain Unicode scalar values") from exc
+        elif kind is int:
+            integer(item, "JSON integer", -(1 << 63), (1 << 64) - 1)
+        elif kind is float:
+            if not math.isfinite(item):
+                raise InputError("JSON floating-point numbers must be finite")
+            if authoritative:
+                # Rust's finite float token uses at least three bytes. CPython
+                # may use longer text for the same value (1e-08 versus 1e-8).
+                # Bound each accepted token's possible expansion separately.
+                width = len(repr(item))
+                if width > 32:
+                    raise InputError("unsupported floating-point representation")
+                float_slack += max(0, width - 3)
+        elif kind in (dict, list, tuple):
+            if depth >= max_depth:
+                raise InputError("JSON value exceeds its container depth limit")
+            identity = id(item)
+            if identity in ancestors:
+                raise InputError("JSON value contains a cycle")
+            ancestors.add(identity)
+            try:
+                if kind is dict:
+                    for key, child in item.items():
+                        if type(key) is not str:
+                            raise InputError("JSON object keys must be strings")
+                        visit(key, depth + 1)
+                        visit(child, depth + 1)
+                else:
+                    for child in item:
+                        visit(child, depth + 1)
+            finally:
+                ancestors.remove(identity)
+        else:
+            raise InputError("value must contain only plain JSON-compatible types")
+        if remaining < 0:
+            raise InputError("JSON value exceeds its byte limit")
+
+    visit(value, 0)
+    return float_slack
+
+
+def validate_authoritative(value, limit: int, *, max_depth: int = MAX_DEPTH) -> None:
+    """Check accepted Rust JSON without rejecting Python float text expansion.
+
+    Transport bounds the response bytes before decoding. Original numeric tokens
+    are no longer available here, so only inbound observations receive a bounded
+    per-float allowance. Structural, string, finite-number and depth checks remain
+    unchanged. Authored commands must continue to use strict encode().
+    """
+    slack = _validate(value, limit, max_depth=max_depth, authoritative=True)
+    for _ in _encoded_chunks(value, limit + slack):
+        pass
+
+
+def encode(value, limit: int = CONTROL_LIMIT, *, max_depth: int = MAX_DEPTH + 8) -> bytes:
+    validate(value, limit, max_depth=max_depth)
+    return b"".join(_encoded_chunks(value, limit))
+
+
+def _encoded_chunks(value, limit: int):
+    length = 0
+    encoder = json.JSONEncoder(ensure_ascii=False, allow_nan=False, separators=(",", ":"))
+    for part in encoder.iterencode(value):
+        chunk = part.encode("utf-8")
+        length += len(chunk)
+        if length > limit:
+            raise InputError("encoded JSON exceeds its byte limit")
+        yield chunk
+
+
+def _pairs(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("duplicate JSON object key")
+        result[key] = value
+    return result
+
+
+def _int(token):
+    if token == "-0":
+        return -0.0
+    if len(token) > 20:
+        raise ValueError("integer token exceeds i64/u64")
+    result = int(token)
+    if not -(1 << 63) <= result <= (1 << 64) - 1:
+        raise ValueError("integer token exceeds i64/u64")
+    return result
+
+
+def _float(token):
+    result = float(token)
+    if not math.isfinite(result):
+        raise ValueError("nonfinite JSON number")
+    return result
+
+
+def _constant(_):
+    raise ValueError("nonfinite JSON number")
+
+
+def decode(raw: bytes, limit: int = RESPONSE_LIMIT):
+    if len(raw) > limit:
+        raise ProtocolError("response exceeds its byte limit")
+    try:
+        value = json.loads(raw.decode("utf-8", errors="strict"), object_pairs_hook=_pairs,
+                           parse_int=_int, parse_float=_float, parse_constant=_constant)
+        validate(value, limit, max_depth=MAX_RESPONSE_DEPTH)
+        return value
+    except (ValueError, UnicodeError, RecursionError) as exc:
+        raise ProtocolError("response is not valid Ledgence JSON") from exc
+
+
+def fields(value, required: set[str], optional: set[str] = frozenset()):
+    if type(value) is not dict or set(value) - required - optional or required - set(value):
+        raise InputError("invalid object fields")
+    return value