durable-workflow 2.5.15__tar.gz → 2.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: durable-workflow
-Version: 2.5.15
+Version: 2.6.0
 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/)
@@ -168,6 +169,13 @@ 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)

{durable_workflow-2.5.15 → durable_workflow-2.6.0}/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/)
@@ -128,6 +129,13 @@ 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)

{durable_workflow-2.5.15 → durable_workflow-2.6.0}/pyproject.toml

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

{durable_workflow-2.5.15 → durable_workflow-2.6.0}/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.5.15 → durable_workflow-2.6.0}/src/durable_workflow/client.py

@@ -302,8 +302,8 @@ def _contains_inline_payload_envelope(value: object) -> bool:
         if set(value) == {"codec", "blob"} and isinstance(value.get("blob"), str):
             return True
         if (
-            value.get("type") == "record_side_effect"
-            and isinstance(value.get("result"), str)
+            (value.get("type") == "record_side_effect" and isinstance(value.get("result"), str))
+            or (value.get("type") == "start_service_operation" and isinstance(value.get("request_payload"), str))
         ):
             return True
         return any(_contains_inline_payload_envelope(item) for item in value.values())
@@ -2097,21 +2097,23 @@ class Client:
         slot: tuple[str | int, ...] = (),
     ) -> Any:
         if isinstance(value, dict):
-            if (
-                value.get("type") == "record_side_effect"
-                and isinstance(value.get("result"), str)
-            ):
+            command_type = value.get("type")
+            blob_key = (
+                {"record_side_effect": "result", "start_service_operation": "request_payload"}.get(command_type)
+                if isinstance(command_type, str) else None
+            )
+            if blob_key is not None and isinstance(value.get(blob_key), str):
                 normalized_command = dict(value)
                 externalized_result = await self._externalize_runtime_payloads(
-                    {"codec": serializer.AVRO_CODEC, "blob": value["result"]},
+                    {"codec": value.get("payload_codec", serializer.AVRO_CODEC), "blob": value[blob_key]},
                     worker=worker,
                     transport=transport,
                     uploaded=uploaded,
                     completion=completion,
-                    slot=(*slot, "result"),
+                    slot=(*slot, blob_key),
                 )
                 if "external_payload" in externalized_result:
-                    normalized_command["result"] = externalized_result
+                    normalized_command[blob_key] = externalized_result
                 value = normalized_command
 
             if set(value) == {"codec", "blob"} and isinstance(value.get("blob"), str):

{durable_workflow-2.5.15 → durable_workflow-2.6.0}/src/durable_workflow/worker.py

@@ -101,10 +101,8 @@ from .workflow import (
     Command,
     FailWorkflow,
     LocalActivityExecutionAborted,
-    NexusServiceCall,
     PreparedLocalActivityCall,
     RecordLocalActivity,
-    RecordSideEffect,
     ReplayOutcome,
     ScheduleActivity,
     StartChildWorkflow,
@@ -169,7 +167,6 @@ _WORKFLOW_TASK_COMPLETION_AMBIGUOUS_REJECTION_REASONS = {
 }
 _WORKFLOW_TASK_COMPLETION_MAX_ATTEMPTS = 3
 _WORKFLOW_TASK_COMPLETION_RETRY_DELAYS = (0.05, 0.2)
-_WORKFLOW_TASK_NEXUS_RESOLUTION_LIMIT = 100
 _LOCAL_ACTIVITY_REPORT_LIMIT = 1000
 _WORKER_WORKFLOW_FINGERPRINTS: dict[tuple[str, str], str] = {}
 _P = ParamSpec("_P")
@@ -1072,6 +1069,7 @@ class Worker:
         if "sticky_execution" in self.capabilities and not self._sticky_cache.enabled:
             raise ValueError("sticky_execution requires a positive sticky_cache_capacity")
         self._cooperative_cancellation_supported = False
+        self._nexus_cooperative_cancellation_supported = False
         self._prepared_local_activities_supported = False
         self._prepared_local_activity_groups_supported = False
         self._allow_cancellation_scope_authoring = False
@@ -1087,6 +1085,9 @@ class Worker:
             raise ValueError("prepared local groups require prepared_local_activities capability")
         if "prepared_local_activities" in self.capabilities and "cooperative_cancellation" not in self.capabilities:
             raise ValueError("prepared local activities require cooperative_cancellation capability")
+        if ("nexus_cooperative_cancellation" in self.capabilities
+                and "cooperative_cancellation" not in self.capabilities):
+            raise ValueError("Nexus cooperative cancellation requires cooperative_cancellation capability")
         if any(not capability for capability in self.capabilities):
             raise ValueError("worker capabilities must be non-empty strings")
         self.worker_id = worker_id or f"py-worker-{uuid.uuid4().hex[:8]}"
@@ -1272,6 +1273,17 @@ class Worker:
         )
         if "cooperative_cancellation" in self.capabilities and not self._cooperative_cancellation_supported:
             raise RuntimeError("cooperative cancellation requires explicit compatible runtime and worker protocol 1.20")
+        self._nexus_cooperative_cancellation_supported = (
+            self._cooperative_cancellation_supported
+            and isinstance(server_capabilities, Mapping)
+            and server_capabilities.get("nexus_cooperative_cancellation") is True
+            and isinstance(server_capabilities.get("nexus_cooperative_cancellation_binding_kinds"), list)
+            and "workflow_run" in server_capabilities["nexus_cooperative_cancellation_binding_kinds"]
+        )
+        if "nexus_cooperative_cancellation" in self.capabilities and not self._nexus_cooperative_cancellation_supported:
+            raise RuntimeError(
+                "nexus_cooperative_cancellation_not_supported: Server must advertise its installed workflow_run bridge",
+            )
         self._prepared_local_activities_supported = (
             "prepared_local_activities" in self.capabilities and self._cooperative_cancellation_supported
             and isinstance(server_capabilities, Mapping)
@@ -1342,6 +1354,8 @@ class Worker:
             capabilities.append(WORKFLOW_UPDATES_CAPABILITY)
         capabilities.append(MESSAGE_STREAMS_CAPABILITY)
         capabilities.extend(self.capabilities)
+        if self._nexus_cooperative_cancellation_supported and "nexus_cooperative_cancellation" not in capabilities:
+            capabilities.append("nexus_cooperative_cancellation")
         if (
             self._local_activity_cancellation_policies
             and "prepared_local_activity_cancellation_policies" not in capabilities
@@ -1373,6 +1387,11 @@ class Worker:
             capabilities=capabilities,
             capability_manifest={
                 **affinity_manifest,
+                **({"nexus_cooperative_cancellation": {
+                    "supported": True, "minimum_protocol_version": "1.20",
+                    "implementation": "owned_workflow_run_canonical_delivery",
+                    "binding_kinds": ["workflow_run"],
+                }} if self._nexus_cooperative_cancellation_supported else {}),
                 **({"prepared_local_activities": {
                     "supported": True, "minimum_protocol_version": "1.20",
                     "implementation": "durable_sequential_admission",
@@ -1452,86 +1471,6 @@ class Worker:
 
         return await handler(context)
 
-    async def _resolve_workflow_nexus_commands(
-        self,
-        workflow_cls: type,
-        history: list[dict[str, Any]],
-        start_input: list[Any],
-        task: dict[str, Any],
-        *,
-        payload_codec: str | None,
-        command_codec: str,
-        initial_commands: list[Command],
-    ) -> list[Command]:
-        events = list(history)
-        commands: list[Command] = list(initial_commands)
-        recorded_commands: list[RecordSideEffect] = []
-
-        for _ in range(_WORKFLOW_TASK_NEXUS_RESOLUTION_LIMIT):
-            nexus_commands = [command for command in commands if isinstance(command, NexusServiceCall)]
-            if not nexus_commands:
-                return recorded_commands + commands
-            if len(nexus_commands) != len(commands):
-                raise RuntimeError("Nexus service calls must be yielded one at a time")
-
-            for command in nexus_commands:
-                result = await self.client.execute_nexus_operation(
-                    command.endpoint_name,
-                    command.service_name,
-                    command.operation_name,
-                    command.arguments,
-                    mode=command.mode,
-                    wait_for=command.wait_for,
-                    wait_timeout_seconds=command.wait_timeout_seconds,
-                    idempotency_key=command.idempotency_key,
-                    payload_codec=command.payload_codec,
-                    caller_namespace=command.caller_namespace,
-                    target_namespace=command.target_namespace,
-                    caller_workflow_instance_id=_string_or_none(task.get("workflow_id")),
-                    caller_workflow_run_id=_string_or_none(task.get("run_id")),
-                    service_sdk_language=command.service_sdk_language,
-                    artifact_tuple=command.artifact_tuple,
-                    published_artifact_worker_execution=command.published_artifact_worker_execution,
-                    target_workflow_instance_id=command.target_workflow_instance_id,
-                    target_workflow_run_id=command.target_workflow_run_id,
-                    connection=command.connection,
-                    queue=command.queue,
-                    business_key=command.business_key,
-                    labels=command.labels,
-                    memo=command.memo,
-                    search_attributes=command.search_attributes,
-                    duplicate_start_policy=command.duplicate_start_policy,
-                    raise_on_failure=False,
-                )
-                recorded_payload = result.to_recorded_payload()
-                recorded_commands.append(RecordSideEffect(recorded_payload))
-                events.append({
-                    "event_type": "SideEffectRecorded",
-                    "payload": {
-                        "payload_codec": command_codec,
-                        "result": serializer.encode(recorded_payload, codec=command_codec),
-                    },
-                })
-
-            outcome = replay(
-                workflow_cls,
-                events,
-                start_input,
-                workflow_id=task.get("workflow_id"),
-                run_id=_string_or_none(task.get("run_id")) or "",
-                workflow_command_id=(
-                    _string_or_none(task.get("workflow_command_id"))
-                    or _string_or_none(task.get("task_id"))
-                ),
-                payload_codec=payload_codec,
-                external_storage=self.external_storage,
-                external_storage_cache=self.external_storage_cache,
-                cancel_requested=bool(task.get("cancel_requested", False)),
-            )
-            commands = list(outcome.commands)
-
-        raise RuntimeError("workflow yielded too many consecutive Nexus service calls")
-
     async def _renew_workflow_payload_lease(self, task: dict[str, Any]) -> None:
         if self._stop.is_set() or self._local_activity_shutdown.is_set():
             raise LocalActivityExecutionAborted("worker shutdown stopped its workflow payload transfer")
@@ -1852,6 +1791,11 @@ class Worker:
                 # Earlier authored commands must commit on this claim first.
                 # Completion releases the claim; a successor replays their durable results.
                 return outcome, history
+            if intent.call_kind == "service_operation" and not self._nexus_cooperative_cancellation_supported:
+                raise LocalActivityExecutionAborted(
+                    "nexus_cooperative_cancellation_not_supported: "
+                    "delivery requires installed Server discovery and a cooperative protocol 1.20 worker",
+                )
             delivery_attempts += 1
             if delivery_attempts > 3:
                 raise LocalActivityExecutionAborted("cancellation replay did not converge on its canonical delivery")
@@ -1866,7 +1810,20 @@ class Worker:
                     operation_sequence_span=intent.operation_sequence_span,
                 )
                 if delivery_reply.get("delivered") is False:
-                    raise _WorkflowClaimDeferred("parent awaits canonical child cleanup on a new claim")
+                    pending_reasons = {
+                        "service_operation": {"cancellation_waiting_for_service_operation"},
+                        "child": {"cancellation_waiting_for_child"},
+                        "activity": {"cancellation_waiting_for_activity"},
+                        "local_activity": {"cancellation_waiting_for_activity"},
+                        "parallel": {"cancellation_waiting_for_child", "cancellation_waiting_for_activity"},
+                        "selection_handle": {"cancellation_waiting_for_child", "cancellation_waiting_for_activity"},
+                    }.get(intent.call_kind, set())
+                    if (delivery_reply.get("reason") not in pending_reasons
+                            or delivery_reply.get("claim_released") is not True
+                            or delivery_reply.get("task_id") != task["task_id"]
+                            or delivery_reply.get("workflow_run_id") != task["run_id"]):
+                        raise LocalActivityExecutionAborted("pending cancellation lacks this claim's release receipt")
+                    raise _WorkflowClaimDeferred("pending cancellation: target cleanup continues on a new claim")
             except _WorkflowClaimDeferred:
                 raise
             except Exception as error:
@@ -2675,45 +2632,7 @@ class Worker:
                 log.warning("failed to report replay failure: %s", fe)
             return None
 
-        try:
-            workflow_commands = await self._resolve_workflow_nexus_commands(
-                cls,
-                list(history),
-                start_input,
-                task,
-                payload_codec=codec,
-                command_codec=command_codec,
-                initial_commands=list(outcome.commands),
-            )
-        except Exception as e:
-            log.exception("workflow Nexus service call resolution failed")
-            last_local = max(
-                (index for index, command in enumerate(outcome.commands)
-                 if isinstance(command, RecordLocalActivity) and command.outcome is not None),
-                default=-1,
-            )
-            if last_local >= 0:
-                workflow_commands = [
-                    *outcome.commands[:last_local + 1],
-                    FailWorkflow(
-                        f"Nexus resolution after local activity failed: {e}",
-                        exception_type=type(e).__name__,
-                        non_retryable=True,
-                    ),
-                ]
-            else:
-                try:
-                    await self.client.fail_workflow_task(
-                        task_id=task_id,
-                        lease_owner=self.worker_id,
-                        workflow_task_attempt=attempt,
-                        message=f"workflow Nexus service call resolution failed: {e}",
-                        failure_type=type(e).__name__,
-                        stack_trace=traceback.format_exc(),
-                    )
-                except Exception as fe:
-                    log.warning("failed to report workflow Nexus resolution failure: %s", fe)
-                return None
+        workflow_commands = list(outcome.commands)
 
         if (
             any(isinstance(command, UpsertMemo) for command in workflow_commands)