durable-workflow 2.1.2__tar.gz → 2.2.0__tar.gz

{durable_workflow-2.1.2/src/durable_workflow.egg-info → durable_workflow-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: durable-workflow
-Version: 2.1.2
+Version: 2.2.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.1.2 → durable_workflow-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "durable-workflow"
-version = "2.1.2"
+version = "2.2.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.1.2"
-registry-version = "2.1.2"
+product-train = "2.2.0"
+registry-version = "2.2.0"
 supported-server-versions = "2.4.0"
 worker-protocol-version = "1.19"
 control-plane-version = "2"

{durable_workflow-2.1.2 → durable_workflow-2.2.0}/src/durable_workflow/activity.py

@@ -2,7 +2,7 @@
 from __future__ import annotations
 
 import contextvars
-from collections.abc import Callable
+from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
 
@@ -38,9 +38,11 @@ class ActivityContext:
         *,
         info: ActivityInfo,
         client: Client,
+        heartbeat_callback: Callable[[dict[str, Any] | None], Awaitable[None]] | None = None,
     ) -> None:
         self._info = info
         self._client = client
+        self._heartbeat_callback = heartbeat_callback
         self._cancel_requested = False
 
     @property
@@ -65,6 +67,13 @@ class ActivityContext:
         owning workflow has requested cancellation, so the activity can exit
         cleanly at its next natural break point.
         """
+        if self._heartbeat_callback is not None:
+            try:
+                await self._heartbeat_callback(details)
+            except ActivityCancelled:
+                self._cancel_requested = True
+                raise
+            return
         resp = await self._client.heartbeat_activity_task(
             task_id=self._info.task_id,
             activity_attempt_id=self._info.activity_attempt_id,

{durable_workflow-2.1.2 → durable_workflow-2.2.0}/src/durable_workflow/client.py

@@ -66,9 +66,9 @@ PROTOCOL_VERSION = "1.19"
 CONTROL_PLANE_VERSION = "2"
 PORTABLE_WORKER_AFFINITY_CAPABILITY_MANIFEST: dict[str, dict[str, str | bool]] = {
     "local_activities": {
-        "supported": False,
+        "supported": True,
         "minimum_protocol_version": "1.18",
-        "reason": "python_worker_does_not_execute_record_local_activity",
+        "implementation": "record_local_activity",
     },
     "worker_sessions": {
         "supported": False,
@@ -1316,7 +1316,7 @@ class WorkflowHandle:
         return await self._client.query_workflow(self.workflow_id, query_name, args=args)
 
     async def cancel(self, *, reason: str | None = None) -> None:
-        """Request graceful cancellation of this workflow. See :meth:`Client.cancel_workflow`."""
+        """Close this workflow's current run as cancelled. See :meth:`Client.cancel_workflow`."""
         await self._client.cancel_workflow(self.workflow_id, reason=reason)
 
     async def terminate(self, *, reason: str | None = None) -> None:
@@ -4114,11 +4114,13 @@ class Client:
         )
 
     async def cancel_workflow(self, workflow_id: str, *, reason: str | None = None) -> None:
-        """Request graceful cancellation of a workflow's current run.
+        """Close the current run as cancelled immediately.
 
-        Cancellation is cooperative: the server delivers a cancellation signal
-        that the workflow can observe and handle (e.g. to roll back via a
-        saga). Compare with :meth:`terminate_workflow`, which is forceful.
+        Server cancels open tasks and timers; it does not resume workflow code
+        to run saga or ``finally`` cleanup. :meth:`terminate_workflow` also
+        closes immediately, with a distinct terminal outcome. Embedded
+        Laravel's cooperative ``requestCancellation()`` is not yet available
+        through this service-mode API.
         """
         body: dict[str, Any] = {}
         if reason is not None:
@@ -4126,10 +4128,11 @@ class Client:
         await self._request("POST", f"/workflows/{workflow_id}/cancel", json=body, context=workflow_id)
 
     async def terminate_workflow(self, workflow_id: str, *, reason: str | None = None) -> None:
-        """Forcefully stop a workflow without giving it a chance to clean up.
+        """Close the current run as terminated immediately.
 
-        Prefer :meth:`cancel_workflow` when the workflow code can implement
-        graceful shutdown. Termination is an operator escape hatch.
+        Like :meth:`cancel_workflow`, this does not resume workflow code for
+        cleanup. Use the distinct terminal outcome when termination is the
+        appropriate operator action.
         """
         body: dict[str, Any] = {}
         if reason is not None:
@@ -4964,6 +4967,24 @@ class Client:
             "POST", f"/worker/workflow-tasks/{task_id}/fail", worker=True, json=body
         )
 
+    async def heartbeat_workflow_task(
+        self,
+        *,
+        task_id: str,
+        lease_owner: str,
+        workflow_task_attempt: int,
+    ) -> Any:
+        """Renew a leased workflow task while in-process work is running."""
+        return await self._request(
+            "POST",
+            f"/worker/workflow-tasks/{task_id}/heartbeat",
+            worker=True,
+            json={
+                "lease_owner": lease_owner,
+                "workflow_task_attempt": workflow_task_attempt,
+            },
+        )
+
     async def workflow_task_history(
         self,
         *,

{durable_workflow-2.1.2 → durable_workflow-2.2.0}/src/durable_workflow/errors.py

@@ -581,7 +581,8 @@ class ActivityFailed(DurableWorkflowError):
 class WorkflowTerminated(DurableWorkflowError):
     """A workflow was terminated by operator action.
 
-    Termination is non-gracious and skips normal cleanup, unlike cancellation.
+    Like terminal cancellation, termination does not resume workflow cleanup.
+    It records a distinct terminal outcome.
     """
 
     def __init__(self, message: str = "workflow was terminated") -> None:
@@ -643,8 +644,9 @@ class ActivityCancelled(BaseException):
     """An in-flight activity was cancelled.
 
     Raised inside :meth:`durable_workflow.ActivityContext.heartbeat` when the
-    server reports that the owning workflow has asked for cancellation, so the
-    activity can exit cleanly on its next heartbeat.
+    server reports that the task was revoked or its run was cancelled, so the
+    activity can exit on its next heartbeat. This permits local activity cleanup,
+    not durable workflow compensation after the run closes.
 
     Inherits from :class:`BaseException` — not :class:`Exception` — so that a
     user ``except Exception:`` block inside the activity function cannot

{durable_workflow-2.1.2 → durable_workflow-2.2.0}/src/durable_workflow/external_storage.py

@@ -12,7 +12,12 @@ from pathlib import Path
 from typing import Any, Protocol
 from urllib.parse import quote, unquote, urlparse
 
-from .errors import ExternalPayloadIntegrityMismatch, ExternalPayloadUnsupported
+from .errors import (
+    ExternalPayloadError,
+    ExternalPayloadIntegrityMismatch,
+    ExternalPayloadUnavailable,
+    ExternalPayloadUnsupported,
+)
 
 EXTERNAL_PAYLOAD_REFERENCE_SCHEMA = "durable-workflow.v2.external-payload-reference.v1"
 RUNTIME_EXTERNAL_PAYLOAD_REFERENCE_SCHEMA = (
@@ -556,7 +561,12 @@ def store_external_payload(
     if expires_at is not None:
         _validate_rfc3339(expires_at)
     sha256 = hashlib.sha256(data).hexdigest()
-    uri = driver.put(data, sha256=sha256, codec=codec)
+    try:
+        uri = driver.put(data, sha256=sha256, codec=codec)
+    except ExternalPayloadError:
+        raise
+    except Exception as exc:
+        raise ExternalPayloadUnavailable("external payload storage upload failed") from exc
     return ExternalPayloadReference(
         uri=uri,
         sha256=sha256,