durable-workflow 2.9.1__tar.gz → 2.10.0__tar.gz

{durable_workflow-2.9.1/src/durable_workflow.egg-info → durable_workflow-2.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: durable-workflow
-Version: 2.9.1
+Version: 2.10.0
 Summary: Python client and worker SDK for Durable Workflow Cloud and self-hosted Server
 Author: Durable Workflow Contributors
 License-Expression: MIT

{durable_workflow-2.9.1 → durable_workflow-2.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "durable-workflow"
-version = "2.9.1"
+version = "2.10.0"
 description = "Python client and worker SDK for Durable Workflow Cloud and self-hosted Server"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -76,8 +76,8 @@ durable-workflow-replay-conformance = "durable_workflow.replay_conformance:main"
 durable-workflow-workflow-updates-conformance = "durable_workflow.workflow_updates_conformance:main"
 
 [tool.durable-workflow]
-product-train = "2.9.1"
-registry-version = "2.9.1"
+product-train = "2.10.0"
+registry-version = "2.10.0"
 supported-server-versions = "2.8.0"
 worker-protocol-version = "1.20"
 control-plane-version = "2"

durable_workflow-2.10.0/src/durable_workflow/_metric_routes.py

@@ -0,0 +1,57 @@
+"""Bound request labels to reviewed SDK operations, never arbitrary URL values."""
+
+from __future__ import annotations
+
+_ROUTES = (
+    "/", "/health", "/cluster/info", "/activities", "/activities/{activity_id}",
+    "/namespaces", "/namespaces/{name}", "/namespaces/{name}/external-storage",
+    "/search-attributes", "/search-attributes/{name}", "/storage/test",
+    "/task-queues", "/task-queues/{task_queue}", "/task-queues/{task_queue}/build-ids",
+    *(f"/task-queues/{{task_queue}}/build-ids/{action}" for action in ("drain", "promote", "resume")),
+    *(f"/system/{operation}{suffix}" for operation in ("activity-timeouts", "repair", "retention")
+      for suffix in ("", "/pass")),
+    "/workers", "/workers/{worker_id}",
+    "/worker/register", "/worker/heartbeat", "/worker/registrations/{worker_id}",
+    "/worker/sessions", "/worker/sessions/{session_id}", "/worker/sessions/{session_id}/heartbeat",
+    *(f"/worker/{kind}-tasks/poll" for kind in ("workflow", "activity", "query", "update-validation")),
+    *(f"/worker/{kind}-tasks/{{task_id}}/{action}" for kind, actions in (
+        ("workflow", ("complete", "fail", "heartbeat", "history", "deliver-cancellation")),
+        ("activity", ("complete", "fail", "heartbeat", "status", "renew-lease", "acknowledge-cancellation")),
+        ("query", ("complete", "fail", "status")),
+        ("update-validation", ("approve", "reject")),
+    ) for action in actions),
+    *(f"/worker/workflow-tasks/{{task_id}}/cancellation-scopes/{action}"
+      for action in ("open", "prepare", "deliver")),
+    *(f"/worker/workflow-tasks/{{task_id}}/local-activities/{action}"
+      for action in ("checkpoint", "checkpoint-group", "prepare", "recover")),
+    *(f"/worker/workflow-tasks/{{task_id}}/local-activities/{{activity_attempt_id}}/{action}"
+      for action in ("control", "heartbeat", "outcome", "acknowledge-cancellation")),
+    "/workflows", "/workflows/{workflow_id}",
+    *(f"/workflows/{{workflow_id}}/{action}"
+      for action in ("archive", "cancel", "repair", "terminate", "request-cancellation", "runs")),
+    *(f"/workflows/{{workflow_id}}/{action}/{{name}}" for action in ("signal", "query", "update")),
+    "/workflows/{workflow_id}/message-streams/{name}/messages",
+    "/workflows/{workflow_id}/runs/{run_id}",
+    *(f"/workflows/{{workflow_id}}/runs/{{run_id}}/{action}"
+      for action in ("history", "history/export", "redrive", "request-cancellation", "streams")),
+    "/workflows/{workflow_id}/runs/{run_id}/streams/{name}",
+    *(f"/workflows/{{workflow_id}}/runs/{{run_id}}/streams/{{name}}/{action}" for action in ("items", "close")),
+    "/schedules", "/schedules/{schedule_id}",
+    *(f"/schedules/{{schedule_id}}/{action}" for action in ("backfill", "pause", "resume", "trigger", "history")),
+    "/bridge-adapters/webhook/{adapter}",
+    "/service-endpoints/{endpoint_name}/services/{service_name}/operations/{operation_name}/execute",
+)
+_TEMPLATES = tuple((route, tuple(route.strip("/").split("/"))) for route in _ROUTES)
+
+
+def route_for_metrics(path: str) -> str:
+    """Return a supported operation template or the single bounded fallback."""
+    clean_path = path.split("?", 1)[0].split("#", 1)[0]
+    parts = tuple(clean_path.strip("/").split("/"))
+    for route, template in _TEMPLATES:
+        if len(parts) == len(template) and all(
+            expected == actual or expected.startswith("{") and bool(actual)
+            for actual, expected in zip(parts, template, strict=True)
+        ):
+            return route
+    return "unknown"

{durable_workflow-2.9.1 → durable_workflow-2.10.0}/src/durable_workflow/client.py

@@ -26,6 +26,7 @@ import json as json_module
 import math
 import os
 import re
+import ssl
 import time
 import uuid
 import warnings
@@ -47,6 +48,7 @@ from ._cancellation_scope_history import (
     scope_timestamp,
 )
 from ._cooperative_cancellation import CancellationDelivery, CancellationRequest
+from ._metric_routes import route_for_metrics as _route_for_metrics
 from ._query_task_authority import QueryTaskAuthority, current_query_authority
 from .errors import (
     REQUEST_ID_CONFLICT,
@@ -289,38 +291,6 @@ def _command_request_failure(exc: Exception, *, command: str, request_id: str) -
     return exc
 
 
-def _route_for_metrics(path: str) -> str:
-    clean_path = path.split("?", 1)[0]
-    parts = [part for part in clean_path.strip("/").split("/") if part]
-    if not parts:
-        return "/"
-
-    if parts[0] == "workflows" and len(parts) >= 2:
-        parts[1] = "{workflow_id}"
-        if len(parts) >= 4 and parts[2] in {"signal", "query", "update"}:
-            parts[3] = "{name}"
-        if len(parts) >= 4 and parts[2] == "runs":
-            parts[3] = "{run_id}"
-    elif parts[0] == "schedules" and len(parts) >= 2:
-        parts[1] = "{schedule_id}"
-    elif parts[0] in {"namespaces", "search-attributes"} and len(parts) >= 2:
-        parts[1] = "{name}"
-    elif parts[0] == "workers" and len(parts) >= 2:
-        parts[1] = "{worker_id}"
-    elif parts[:2] == ["worker", "registrations"] and len(parts) >= 3:
-        parts[2] = "{worker_id}"
-    elif parts[:2] == ["bridge-adapters", "webhook"] and len(parts) >= 3:
-        parts[2] = "{adapter}"
-    elif (
-        parts[:2] == ["worker", "workflow-tasks"]
-        or parts[:2] == ["worker", "activity-tasks"]
-        or parts[:2] == ["worker", "query-tasks"]
-    ) and len(parts) >= 3:
-        parts[2] = "{task_id}"
-
-    return "/" + "/".join(parts)
-
-
 def _resolve_namespace_name(
     name: str | None,
     namespace_alias: str | None,
@@ -1631,6 +1601,10 @@ class Client:
 
     The client owns one `httpx.AsyncClient` connection pool. Use it as an async
     context manager or call `aclose()` when finished.
+
+    ``tls_context`` selects an explicit trust configuration. It must require
+    certificate and hostname verification. Treat the context as read-only after
+    construction; worker query clones and Nexus namespace views reuse it.
     """
 
     def __init__(
@@ -1642,6 +1616,7 @@ class Client:
         worker_token: str | None = None,
         namespace: str = "default",
         timeout: float = 60.0,
+        tls_context: ssl.SSLContext | None = None,
         retry_policy: TransportRetryPolicy | None = None,
         metrics: MetricsRecorder | None = None,
         payload_size_limit_bytes: int = serializer.DEFAULT_PAYLOAD_SIZE_BYTES,
@@ -1652,6 +1627,11 @@ class Client:
         external_storage_cache: ExternalPayloadCache | None = None,
         telemetry: ExecutionTelemetry | None = None,
     ) -> None:
+        if tls_context is not None:
+            if not isinstance(tls_context, ssl.SSLContext):
+                raise TypeError("tls_context must be an ssl.SSLContext")
+            if tls_context.verify_mode != ssl.CERT_REQUIRED or not tls_context.check_hostname:
+                raise ValueError("tls_context must enable certificate and hostname verification")
         self.base_url = _normalize_base_url(base_url)
         self.token = token
         self.control_token = control_token
@@ -1660,8 +1640,9 @@ class Client:
         self.telemetry = telemetry
         self._observability_capability = False
         self.timeout = timeout
+        self._tls_context = tls_context
         self.retry_policy = retry_policy or TransportRetryPolicy()
-        self.metrics = metrics or NOOP_METRICS
+        self.metrics = metrics if metrics is not None else NOOP_METRICS
         self.payload_size_warning_config = (
             serializer.PayloadSizeWarningConfig(
                 limit_bytes=payload_size_limit_bytes,
@@ -1679,7 +1660,9 @@ class Client:
             if external_storage_cache is not None
             else ExternalPayloadCache()
         )
-        self._http = httpx.AsyncClient(base_url=self.base_url, timeout=timeout)
+        self._http = httpx.AsyncClient(
+            base_url=self.base_url, timeout=timeout, verify=tls_context if tls_context is not None else True,
+        )
         self._cluster_info: dict[str, Any] | None = None
         self._cluster_info_lock = asyncio.Lock()
         self._runtime_external_payload_transport_cache: (
@@ -1688,6 +1671,11 @@ class Client:
         self._runtime_external_payload_transport_resolved = False
         self._workflow_payload_observers: dict[str, Callable[[dict[str, Any]], Awaitable[None]]] = {}
 
+    @property
+    def tls_context(self) -> ssl.SSLContext | None:
+        """The explicit TLS context, or ``None`` for httpx's default trust selection."""
+        return self._tls_context
+
     async def aclose(self) -> None:
         """Close the underlying ``httpx`` connection pool.
 
@@ -1993,6 +1981,9 @@ class Client:
                 await query_authority.confirm()
             outcome = "ok"
             return result
+        except asyncio.CancelledError:
+            outcome = "CancelledError"
+            raise
         except Exception as exc:
             if outcome == "pending":
                 outcome = type(exc).__name__
@@ -2679,6 +2670,9 @@ class Client:
                 )
             outcome = "bridge_rejected" if resp.status_code == 422 else "ok"
             return data
+        except asyncio.CancelledError:
+            outcome = "CancelledError"
+            raise
         except Exception as exc:
             if outcome == "pending":
                 outcome = type(exc).__name__

{durable_workflow-2.9.1 → durable_workflow-2.10.0}/src/durable_workflow/history_bundle_verify.py

@@ -23,11 +23,15 @@ a workflow-php verdict, so promotion gates can compare them directly.
 from __future__ import annotations
 
 import argparse
+import base64
 import hashlib
 import hmac
 import json
+import math
+import re
 import sys
 from collections.abc import Mapping, Sequence
+from decimal import Decimal
 from pathlib import Path
 from typing import Any
 
@@ -37,7 +41,9 @@ REPORT_SCHEMA = "durable-workflow.v2.history-bundle-verification"
 REPORT_SCHEMA_VERSION = 1
 
 BUNDLE_SCHEMA = "durable-workflow.v2.history-export"
+# Retained for callers that construct the supported legacy format.
 BUNDLE_SCHEMA_VERSION = 1
+SUPPORTED_BUNDLE_SCHEMA_VERSIONS = frozenset({1, 2})
 
 STATUS_OK = "ok"
 STATUS_WARNING = "warning"
@@ -138,13 +144,14 @@ def _check_envelope(bundle: Mapping[str, Any], findings: list[dict[str, Any]]) -
                 "Bundle is missing the [schema_version] field.",
             )
         )
-    elif bundle["schema_version"] != BUNDLE_SCHEMA_VERSION:
+    elif (type(bundle["schema_version"]) is not int
+          or bundle["schema_version"] not in SUPPORTED_BUNDLE_SCHEMA_VERSIONS):
         findings.append(
             _finding(
                 "bundle.schema_version_unsupported",
                 SEVERITY_ERROR,
                 f"Bundle schema_version [{bundle['schema_version']!s}] is unsupported; "
-                f"expected {BUNDLE_SCHEMA_VERSION}.",
+                "expected integer 1 or 2.",
                 {"observed": bundle["schema_version"]},
             )
         )
@@ -230,6 +237,9 @@ def _check_workflow(bundle: Mapping[str, Any], findings: list[dict[str, Any]]) -
             )
         )
 
+    if type(bundle.get("schema_version")) is int and bundle["schema_version"] == 2:
+        _check_v2_memo(bundle, workflow, findings)
+
     declared = _int_or_none(workflow.get("last_history_sequence"))
     events = bundle.get("history_events")
     if declared is not None and isinstance(events, list) and events:
@@ -253,6 +263,85 @@ def _check_workflow(bundle: Mapping[str, Any], findings: list[dict[str, Any]]) -
             )
 
 
+def _check_v2_memo(
+    bundle: Mapping[str, Any], workflow: Mapping[str, Any], findings: list[dict[str, Any]],
+) -> None:
+    redaction = bundle.get("redaction")
+    paths = redaction.get("paths") if isinstance(redaction, Mapping) else None
+    paths = paths if isinstance(paths, list) else []
+    if "workflow.memo_payload" in paths:
+        return
+
+    payload = workflow.get("memo_payload")
+    if not isinstance(payload, dict):
+        findings.append(_finding(
+            "workflow.memo_payload_missing", SEVERITY_ERROR,
+            "Schema-2 workflow.memo_payload must contain the lossless portable Avro memo authority.",
+        ))
+        return
+    try:
+        entries = _decode_memo_entries(payload)
+    except (TypeError, ValueError) as exc:
+        findings.append(_finding(
+            "workflow.memo_payload_invalid", SEVERITY_ERROR,
+            f"workflow.memo_payload is not a valid portable Avro memo map: {exc}",
+        ))
+        return
+    if "workflow.memo" in paths:
+        return
+
+    # MemoPayload::decodeEntries normalizes the top-level map to a PHP array;
+    # its empty display projection is [], while nested empty maps retain an
+    # explicit map adapter. Compare JSON kinds as well as values (True != 1).
+    projection = {key: _memo_value_projection(value) for key, value in entries.items()} if entries else []
+    try:
+        projection_matches = json.dumps(workflow.get("memo"), sort_keys=True) == json.dumps(projection, sort_keys=True)
+    except (TypeError, ValueError):
+        projection_matches = False
+    if not projection_matches:
+        findings.append(_finding(
+            "workflow.memo_projection_mismatch", SEVERITY_ERROR,
+            "workflow.memo does not match the JSON-safe projection of workflow.memo_payload.",
+        ))
+
+
+def _decode_memo_entries(payload: dict[str, Any]) -> dict[str, Any]:
+    if set(payload) != {"codec", "blob"} or payload["codec"] != "avro":
+        raise ValueError("expected exactly the codec=avro and blob fields")
+    if not isinstance(payload["blob"], str) or not payload["blob"]:
+        raise ValueError("blob must be a non-empty base64 string")
+    entries = _avro.decode(payload["blob"])
+    if not isinstance(entries, dict):
+        raise ValueError("memo authority must decode to a string-keyed map")
+    for key in entries:
+        if not re.fullmatch(r"[A-Za-z0-9_.:-]{1,64}", key) or re.fullmatch(r"-?\d+", key, flags=re.ASCII):
+            raise ValueError(f"invalid portable memo key: {key!r}")
+    return entries
+
+
+def _memo_value_projection(value: Any) -> Any:
+    if isinstance(value, bytes):
+        return {"$type": "bytes", "base64": base64.b64encode(value).decode("ascii")}
+    if isinstance(value, list):
+        return [_memo_value_projection(item) for item in value]
+    if isinstance(value, dict):
+        # PHP uses AvroMapValue for empty maps and maps containing keys that
+        # its native arrays would coerce to signed 64-bit integers.
+        if not value or any(_php_integer_key(key) for key in value):
+            return {"$type": "map", "entries": [
+                {"key": key, "value": _memo_value_projection(item)} for key, item in value.items()
+            ]}
+        return {key: _memo_value_projection(item) for key, item in value.items()}
+    return value
+
+
+def _php_integer_key(key: str) -> bool:
+    # PHP numeric array keys use ASCII digits; Unicode decimal digits remain strings.
+    if len(key) > 20 or not re.fullmatch(r"0|-?[1-9]\d*", key, flags=re.ASCII):
+        return False
+    return -(2**63) <= int(key) <= 2**63 - 1
+
+
 def _check_history_events(bundle: Mapping[str, Any], findings: list[dict[str, Any]]) -> None:
     events = bundle.get("history_events")
     if not isinstance(events, list):
@@ -664,7 +753,57 @@ def _check_integrity(
 def _canonicalize(bundle: Mapping[str, Any]) -> str:
     cloned = {k: v for k, v in bundle.items() if k != "integrity"}
     canonical = _canonicalize_value(cloned)
-    return json.dumps(canonical, separators=(",", ":"), ensure_ascii=False, sort_keys=False)
+    return _canonical_json_value(canonical)
+
+
+def _canonical_json_value(value: Any) -> str:
+    """Encode the existing PHP json-recursive-ksort-v1 byte representation."""
+    if isinstance(value, dict):
+        if not all(isinstance(key, str) for key in value):
+            raise TypeError("History bundle JSON object keys must be strings")
+        return "{" + ",".join(_canonical_json_string(key) + ":" + _canonical_json_value(item)
+                              for key, item in value.items()) + "}"
+    if isinstance(value, list):
+        return "[" + ",".join(_canonical_json_value(item) for item in value) + "]"
+    if isinstance(value, str):
+        return _canonical_json_string(value)
+    if isinstance(value, float):
+        return _canonical_json_float(value)
+    return json.dumps(value, separators=(",", ":"), allow_nan=False)
+
+
+def _canonical_json_string(value: str) -> str:
+    # PHP escapes non-ASCII characters as UTF-16 code units while leaving
+    # ASCII DEL unescaped. Start with standard JSON quoting, then escape only
+    # its non-ASCII characters. Invalid surrogate strings fail encoding.
+    encoded = json.dumps(value, ensure_ascii=False)
+    if encoded.isascii():
+        return encoded
+    return "".join(character if ord(character) < 128 else _json_utf16_escape(character) for character in encoded)
+
+
+def _json_utf16_escape(character: str) -> str:
+    units = character.encode("utf-16-be").hex()
+    return "".join("\\u" + units[offset:offset + 4] for offset in range(0, len(units), 4))
+
+
+def _canonical_json_float(value: float) -> str:
+    if not math.isfinite(value):
+        raise ValueError("History bundle JSON numbers must be finite")
+    text = float.__repr__(value)
+    mantissa, separator, exponent_text = text.partition("e")
+    if not separator:
+        return text
+    exponent = int(exponent_text)
+    # PHP uses fixed notation through exponent 16 and preserves a decimal
+    # fraction for floats. Both runtimes otherwise use shortest-roundtrip
+    # digits, but PHP omits exponent leading zeros and writes 1.0e rather than 1e.
+    if -4 <= exponent < 17:
+        fixed = format(Decimal(text), "f")
+        return fixed if "." in fixed else fixed + ".0"
+    if "." not in mantissa:
+        mantissa += ".0"
+    return f"{mantissa}e{exponent:+d}"
 
 
 def _canonicalize_value(value: Any) -> Any:
@@ -846,6 +985,7 @@ __all__ = [
     "REPORT_SCHEMA_VERSION",
     "BUNDLE_SCHEMA",
     "BUNDLE_SCHEMA_VERSION",
+    "SUPPORTED_BUNDLE_SCHEMA_VERSIONS",
     "STATUS_OK",
     "STATUS_WARNING",
     "STATUS_FAILED",

{durable_workflow-2.9.1 → durable_workflow-2.10.0}/src/durable_workflow/sync.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import ssl
 from collections.abc import Coroutine
 from typing import Any, TypeVar
 
@@ -266,6 +267,9 @@ class Client:
 
     The client keeps one event loop for its lifetime so its async HTTP connection
     pool and returned handles always run on the loop that owns them.
+
+    ``tls_context`` forwards the same verified trust configuration accepted by
+    the async client. Treat the supplied context as read-only during use.
     """
 
     def __init__(
@@ -277,6 +281,7 @@ class Client:
         worker_token: str | None = None,
         namespace: str = "default",
         timeout: float = 60.0,
+        tls_context: ssl.SSLContext | None = None,
         retry_policy: TransportRetryPolicy | None = None,
         metrics: MetricsRecorder | None = None,
         external_storage: ExternalStorageDriver | None = None,
@@ -290,6 +295,7 @@ class Client:
             worker_token=worker_token,
             namespace=namespace,
             timeout=timeout,
+            tls_context=tls_context,
             retry_policy=retry_policy,
             metrics=metrics,
             external_storage=external_storage,