durable-workflow 2.6.0rc2__tar.gz → 2.6.1__tar.gz

{durable_workflow-2.6.0rc2/src/durable_workflow.egg-info → durable_workflow-2.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: durable-workflow
-Version: 2.6.0rc2
+Version: 2.6.1
 Summary: Python client and worker SDK for Durable Workflow Cloud and self-hosted Server
 Author: Durable Workflow Contributors
 License-Expression: MIT
@@ -40,6 +40,7 @@ Dynamic: license-file
 
 # Durable Workflow Python SDK
 
+[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=durable-workflow_sdk-python&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=durable-workflow_sdk-python)
 [![CI](https://github.com/durable-workflow/sdk-python/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/durable-workflow/sdk-python/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/durable-workflow.svg)](https://pypi.org/project/durable-workflow/)
 [![Python](https://img.shields.io/pypi/pyversions/durable-workflow.svg)](https://pypi.org/project/durable-workflow/)
@@ -138,6 +139,7 @@ for the complete cross-SDK contract.
 - [Python SDK guide](https://durable-workflow.com/docs/2.0/polyglot/python/)
 - [Complete SDK reference](docs/sdk-reference.md)
 - [Runnable examples](examples/)
+- [Separate workflow and activity worker processes](docs/guides/separate-workers.md)
 - [Symmetric SDK playground](https://github.com/durable-workflow/sample-app#symmetric-sdk-playground)
 
 ## Runtime choices
@@ -155,16 +157,26 @@ capabilities with Server at startup. Use stable `2.x` SDK and Server channels
 for new applications. The [compatibility guide](https://durable-workflow.com/docs/2.0/compatibility/)
 documents protocol and upgrade guarantees.
 
-## Cooperative cancellation release candidate
+## Worker protocol and cooperative cancellation
+
+Workers use protocol 1.20 by default. For a Server that supports only 1.19, set
+`DURABLE_WORKFLOW_WORKER_PROTOCOL_VERSION=1.19`. This changes the request protocol
+without enabling optional worker features.
 
 Use `request_cancellation()` for bounded, replayable workflow cleanup. Opt in
 against a Server that advertises protocol 1.20 and the required capabilities:
-set `DURABLE_WORKFLOW_WORKER_PROTOCOL_VERSION=1.20` and include
-`cooperative_cancellation` in the Worker's `capabilities`. Durable local callback
+include `cooperative_cancellation` in the Worker's `capabilities`. Durable local callback
 admission also needs `prepared_local_activities`, with
 `prepared_local_activity_cancellation_policies` for explicit local policies.
 Independently cancellable scopes remain disabled.
 
+For synchronous Nexus completion waits, the cooperative worker also negotiates
+`nexus_cooperative_cancellation` when Server advertises the installed
+`workflow_run` binding. Owned target cleanup keeps the caller pending until the
+Server commits delivery at the original call. Async and acceptance-only calls
+keep their admission behavior. Existing terminal results and recorded legacy
+Nexus histories retain their replay semantics.
+
 The cooperative worker supervises async and synchronous activity callbacks
 independently of application heartbeats. Existing terminal cancellation remains
 available. See the [cancellation guide](docs/cooperative-cancellation-design.md)
@@ -172,6 +184,14 @@ for immutable context, operation policies, shielded cleanup and recovery.
 
 ## Development
 
+The installed `durable-workflow-replay-conformance` command runs an offline
+Python replay shard. Its `sdk-python` artifact pin must match the installed
+distribution version reported by `importlib.metadata.version("durable-workflow")`.
+The report records that installed identity separately from the declared platform
+tuple and fails if metadata is missing or the SDK pin differs. Replay success
+does not prove installation or execution of the other declared artifacts; the
+aggregate runner supplies its own verified installation receipts.
+
 ```bash
 pip install -e '.[dev]'
 ruff check src/ tests/
@@ -196,11 +216,10 @@ to true. CI verifies that checkout, builds the candidate Server, enables protoco
 authority and exact source provenance. An optional exact `native_commit` mounts
 that public Native checkout read-only into the test stack. The image's published
 Composer authority stays intact and the evidence identifies the source overlay.
-These are source qualification runs. For a local
-candidate, set `DURABLE_WORKFLOW_WORKER_PROTOCOL_VERSION=1.20` before starting
-Compose and `DURABLE_WORKFLOW_COOPERATIVE_QUALIFICATION=1` for pytest. These cases
-fail if the runtime does not discover the required capability. Ordinary CI
-keeps protocol 1.19 and skips this unpublished feature's connected cases.
+These are source qualification runs. For a local candidate, set
+`DURABLE_WORKFLOW_COOPERATIVE_QUALIFICATION=1` for pytest. These cases fail if the
+runtime does not discover the required capability. Ordinary CI uses the SDK's
+default protocol and skips the optional connected cooperative cases.
 
 ## License
 

{durable_workflow-2.6.0rc2 → durable_workflow-2.6.1}/README.md

@@ -1,5 +1,6 @@
 # Durable Workflow Python SDK
 
+[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=durable-workflow_sdk-python&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=durable-workflow_sdk-python)
 [![CI](https://github.com/durable-workflow/sdk-python/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/durable-workflow/sdk-python/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/durable-workflow.svg)](https://pypi.org/project/durable-workflow/)
 [![Python](https://img.shields.io/pypi/pyversions/durable-workflow.svg)](https://pypi.org/project/durable-workflow/)
@@ -98,6 +99,7 @@ for the complete cross-SDK contract.
 - [Python SDK guide](https://durable-workflow.com/docs/2.0/polyglot/python/)
 - [Complete SDK reference](docs/sdk-reference.md)
 - [Runnable examples](examples/)
+- [Separate workflow and activity worker processes](docs/guides/separate-workers.md)
 - [Symmetric SDK playground](https://github.com/durable-workflow/sample-app#symmetric-sdk-playground)
 
 ## Runtime choices
@@ -115,16 +117,26 @@ capabilities with Server at startup. Use stable `2.x` SDK and Server channels
 for new applications. The [compatibility guide](https://durable-workflow.com/docs/2.0/compatibility/)
 documents protocol and upgrade guarantees.
 
-## Cooperative cancellation release candidate
+## Worker protocol and cooperative cancellation
+
+Workers use protocol 1.20 by default. For a Server that supports only 1.19, set
+`DURABLE_WORKFLOW_WORKER_PROTOCOL_VERSION=1.19`. This changes the request protocol
+without enabling optional worker features.
 
 Use `request_cancellation()` for bounded, replayable workflow cleanup. Opt in
 against a Server that advertises protocol 1.20 and the required capabilities:
-set `DURABLE_WORKFLOW_WORKER_PROTOCOL_VERSION=1.20` and include
-`cooperative_cancellation` in the Worker's `capabilities`. Durable local callback
+include `cooperative_cancellation` in the Worker's `capabilities`. Durable local callback
 admission also needs `prepared_local_activities`, with
 `prepared_local_activity_cancellation_policies` for explicit local policies.
 Independently cancellable scopes remain disabled.
 
+For synchronous Nexus completion waits, the cooperative worker also negotiates
+`nexus_cooperative_cancellation` when Server advertises the installed
+`workflow_run` binding. Owned target cleanup keeps the caller pending until the
+Server commits delivery at the original call. Async and acceptance-only calls
+keep their admission behavior. Existing terminal results and recorded legacy
+Nexus histories retain their replay semantics.
+
 The cooperative worker supervises async and synchronous activity callbacks
 independently of application heartbeats. Existing terminal cancellation remains
 available. See the [cancellation guide](docs/cooperative-cancellation-design.md)
@@ -132,6 +144,14 @@ for immutable context, operation policies, shielded cleanup and recovery.
 
 ## Development
 
+The installed `durable-workflow-replay-conformance` command runs an offline
+Python replay shard. Its `sdk-python` artifact pin must match the installed
+distribution version reported by `importlib.metadata.version("durable-workflow")`.
+The report records that installed identity separately from the declared platform
+tuple and fails if metadata is missing or the SDK pin differs. Replay success
+does not prove installation or execution of the other declared artifacts; the
+aggregate runner supplies its own verified installation receipts.
+
 ```bash
 pip install -e '.[dev]'
 ruff check src/ tests/
@@ -156,11 +176,10 @@ to true. CI verifies that checkout, builds the candidate Server, enables protoco
 authority and exact source provenance. An optional exact `native_commit` mounts
 that public Native checkout read-only into the test stack. The image's published
 Composer authority stays intact and the evidence identifies the source overlay.
-These are source qualification runs. For a local
-candidate, set `DURABLE_WORKFLOW_WORKER_PROTOCOL_VERSION=1.20` before starting
-Compose and `DURABLE_WORKFLOW_COOPERATIVE_QUALIFICATION=1` for pytest. These cases
-fail if the runtime does not discover the required capability. Ordinary CI
-keeps protocol 1.19 and skips this unpublished feature's connected cases.
+These are source qualification runs. For a local candidate, set
+`DURABLE_WORKFLOW_COOPERATIVE_QUALIFICATION=1` for pytest. These cases fail if the
+runtime does not discover the required capability. Ordinary CI uses the SDK's
+default protocol and skips the optional connected cooperative cases.
 
 ## License
 

{durable_workflow-2.6.0rc2 → durable_workflow-2.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "durable-workflow"
-version = "2.6.0-rc.2"
+version = "2.6.1"
 description = "Python client and worker SDK for Durable Workflow Cloud and self-hosted Server"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -71,10 +71,10 @@ 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.6.0-rc.2"
-registry-version = "2.6.0rc2"
-supported-server-versions = "2.5.16"
-worker-protocol-version = "1.19"
+product-train = "2.6.1"
+registry-version = "2.6.1"
+supported-server-versions = "2.8.0"
+worker-protocol-version = "1.20"
 control-plane-version = "2"
 durable-selection = true
 durable-selection-minimum-worker-protocol-version = "1.19"

{durable_workflow-2.6.0rc2 → durable_workflow-2.6.1}/src/durable_workflow/__init__.py

@@ -88,6 +88,7 @@ from .errors import (
     NonDeterministicReplayError,
     NonRetryableError,
     QueryFailed,
+    QueryTaskAuthorityLost,
     RuntimeCapabilityUnsupported,
     RuntimeDiscoveryUnavailable,
     SagaCompensationFailed,
@@ -375,6 +376,7 @@ __all__ = [
     "InvalidWorkflowDefinition",
     "NoopMetrics",
     "QueryFailed",
+    "QueryTaskAuthorityLost",
     "RuntimeCapabilityUnsupported",
     "RuntimeDiscoveryUnavailable",
     "RuntimeExternalPayloadReference",

{durable_workflow-2.6.0rc2 → durable_workflow-2.6.1}/src/durable_workflow/_cooperative_cancellation.py

@@ -16,7 +16,10 @@ from .errors import NonDeterministicReplayError
 
 REQUEST_EVENT = "CooperativeCancellationRequested"
 DELIVERY_EVENT = "CooperativeCancellationDelivered"
-_CALL_KINDS = {"activity", "local_activity", "timer", "condition", "signal", "child", "parallel", "selection_handle"}
+_CALL_KINDS = {
+    "activity", "local_activity", "timer", "condition", "signal", "child", "parallel", "selection_handle",
+    "service_operation",
+}
 _RESOLUTION_EVENTS = {
     "ActivityCompleted",
     "ActivityFailed",
@@ -31,6 +34,9 @@ _RESOLUTION_EVENTS = {
     "ChildRunFailed",
     "ChildRunCancelled",
     "ChildRunTerminated",
+    "ServiceCallCompleted",
+    "ServiceCallFailed",
+    "ServiceCallCancelled",
 }
 
 
@@ -265,6 +271,8 @@ def read_cancellation_history(
                 "ChildRunFailed",
                 "ChildRunCancelled",
                 "ChildRunTerminated",
+                "ServiceCallFailed",
+                "ServiceCallCancelled",
             }:
                 failed.add(sequence)
     state = CancellationHistory(

durable_workflow-2.6.1/src/durable_workflow/_query_task_authority.py

@@ -0,0 +1,153 @@
+"""A query delivery's original, non-renewing execution budget."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import time
+from collections.abc import Awaitable, Callable, Mapping
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, TypeVar
+
+from .errors import QueryTaskAuthorityLost
+
+_T = TypeVar("_T")
+_UTC6 = re.compile(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}Z\Z")
+_OBSERVATION_INTERVAL_SECONDS = 5.0
+
+
+def _timestamp(value: Any, *, canonical: bool) -> datetime:
+    if not isinstance(value, str) or (canonical and _UTC6.fullmatch(value) is None):
+        raise ValueError("missing or malformed query timing")
+    parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    if parsed.tzinfo is None:
+        raise ValueError("query timing must include a timezone")
+    return parsed
+
+
+@dataclass
+class QueryTaskAuthority:
+    client: object
+    namespace: str
+    task_id: str
+    attempt: int
+    owner: str
+    observed: bool
+    timing: dict[str, str]
+    until: float
+    identity: dict[str, Any]
+    observer: Callable[[], Awaitable[Mapping[str, Any]]] | None = field(default=None, repr=False)
+
+    @classmethod
+    def delivery(cls, client: object, namespace: str, task: Mapping[str, Any], *,
+                 owner: str, task_queue: str, observed: bool) -> QueryTaskAuthority:
+        task_id, attempt = task.get("query_task_id"), task.get("query_task_attempt")
+        if (not isinstance(owner, str) or not owner or not isinstance(task_queue, str) or not task_queue
+                or not isinstance(task_id, str) or not task_id or type(attempt) is not int or attempt < 1
+                or task.get("lease_owner") != owner or task.get("task_queue") != task_queue
+                or task.get("namespace", namespace) != namespace):
+            raise QueryTaskAuthorityLost(str(task_id or ""), "invalid_query_claim")
+        try:
+            lease = _timestamp(task.get("lease_expires_at"), canonical=observed)
+            timing = {"lease_expires_at": task["lease_expires_at"]}
+            bounds = [lease]
+            if observed or "query_admitted_at" in task or "query_deadline_at" in task:
+                admitted = _timestamp(task.get("query_admitted_at"), canonical=True)
+                deadline = _timestamp(task.get("query_deadline_at"), canonical=True)
+                if deadline < admitted or (observed and lease > deadline):
+                    raise ValueError("inconsistent original query timing")
+                timing.update({"query_admitted_at": task["query_admitted_at"],
+                               "query_deadline_at": task["query_deadline_at"]})
+                bounds.append(deadline)
+            # Legacy compatibility has no non-renewing observation. Its local
+            # clock check cannot establish an undisclosed caller deadline.
+            reference = (_timestamp(task.get("server_time"), canonical=True) if observed
+                         else datetime.now(timezone.utc))
+            until = time.monotonic() + (min(bounds) - reference).total_seconds()
+        except (ValueError, TypeError, OverflowError) as error:
+            raise QueryTaskAuthorityLost(task_id, "invalid_query_timing") from error
+        result = cls(client, namespace, task_id, attempt, owner, observed, timing, until,
+                     {key: task.get(key) for key in ("workflow_id", "run_id", "task_queue")})
+        result.remaining()
+        return result
+
+    def matches(self, client: object, namespace: str, task: Mapping[str, Any], owner: str) -> bool:
+        return (self.client is client and self.namespace == namespace and self.owner == owner
+                and task.get("query_task_id") == self.task_id
+                and type(task.get("query_task_attempt")) is int and task.get("query_task_attempt") == self.attempt
+                and task.get("lease_owner") == owner
+                and all(task.get(key) == value for key, value in self.identity.items())
+                and all(task.get(key) == value for key, value in self.timing.items()))
+
+    def remaining(self) -> float:
+        remaining = self.until - time.monotonic()
+        if remaining <= 0:
+            raise QueryTaskAuthorityLost(self.task_id, "query_execution_budget_expired")
+        return remaining
+
+    async def confirm(self) -> None:
+        remaining = self.remaining()
+        if not self.observed:
+            return
+        started = time.monotonic()
+        try:
+            if self.observer is None:
+                raise ValueError("query authority observer is unavailable")
+            reply = await asyncio.wait_for(self.observer(), timeout=min(5.0, remaining))
+            if (not isinstance(reply, Mapping) or reply.get("query_task_id") != self.task_id
+                    or type(reply.get("query_task_attempt")) is not int
+                    or reply.get("query_task_attempt") != self.attempt or reply.get("lease_owner") != self.owner
+                    or any(reply.get(key) != value for key, value in self.timing.items())):
+                raise ValueError("query authority observation changed its original claim")
+            if (reply.get("can_continue") is not True or reply.get("query_task_status") != "leased"
+                    or reply.get("reason") is not None):
+                raise QueryTaskAuthorityLost(self.task_id, str(reply.get("reason") or "query_claim_unavailable"))
+            server_time = _timestamp(reply.get("server_time"), canonical=True)
+            bound = min(_timestamp(value, canonical=True) for key, value in self.timing.items()
+                        if key != "query_admitted_at")
+            # Charging the entire observation round trip is conservative. A
+            # later observation may shorten this bound but can never reset it.
+            self.until = min(self.until, started + (bound - server_time).total_seconds())
+        except QueryTaskAuthorityLost:
+            raise
+        except Exception as error:
+            raise QueryTaskAuthorityLost(self.task_id, "query_authority_unavailable") from error
+        self.remaining()
+
+    async def run(self, operation: Callable[[], Awaitable[_T]], *, observe: bool = True,
+                  confirm_after: bool = True) -> _T:
+        await self.confirm()
+        execution = asyncio.ensure_future(operation())
+
+        async def watch() -> None:
+            while True:
+                await asyncio.sleep(min(_OBSERVATION_INTERVAL_SECONDS, self.remaining()))
+                await self.confirm()
+
+        observation = asyncio.create_task(watch()) if observe and self.observed else None
+        pending: set[asyncio.Future[Any]] = {execution}
+        if observation is not None:
+            pending.add(observation)
+        try:
+            done, _ = await asyncio.wait(pending, timeout=self.remaining(), return_when=asyncio.FIRST_COMPLETED)
+            if not done:
+                raise QueryTaskAuthorityLost(self.task_id, "query_execution_budget_expired")
+            if observation is not None and observation in done:
+                await observation
+                raise QueryTaskAuthorityLost(self.task_id, "query_authority_unavailable")
+            result = await execution
+            if confirm_after:
+                await self.confirm()
+            return result
+        finally:
+            for future in pending:
+                future.cancel()
+            await asyncio.gather(*pending, return_exceptions=True)
+
+
+# Async task creation copies this context. Each dispatched query keeps the
+# loading budget without adding private fields to the public wire dictionary
+# or retaining an unbounded task-ID registry on Client/Worker.
+current_query_authority: ContextVar[QueryTaskAuthority | None] = ContextVar("query_task_authority", default=None)