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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: durable-workflow
-Version: 2.1.2
+Version: 2.3.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.3.0}/pyproject.toml

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

{durable_workflow-2.1.2 → durable_workflow-2.3.0}/src/durable_workflow/__init__.py

@@ -210,6 +210,7 @@ from .serializer import (
     to_avro_payload_values,
 )
 from .worker import Worker
+from .worker_session import WorkerSession, WorkerSessionOptions
 from .workflow import (
     ActivityRetryPolicy,
     ChildWorkflowRetryPolicy,
@@ -290,6 +291,8 @@ __all__ = [
     "TaskQueueQueryAdmission",
     "TaskQueueTaskAdmission",
     "Worker",
+    "WorkerSession",
+    "WorkerSessionOptions",
     "WorkerInterceptor",
     "WorkflowCommandResult",
     "WorkflowExecution",

{durable_workflow-2.1.2 → durable_workflow-2.3.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.3.0}/src/durable_workflow/client.py

@@ -31,7 +31,7 @@ from collections.abc import AsyncIterator, Callable, Mapping, Sequence
 from dataclasses import dataclass
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as _pkg_version
-from typing import Any
+from typing import Any, cast
 from urllib.parse import quote, unquote, urlencode, urlsplit
 
 import httpx
@@ -61,19 +61,20 @@ from .external_storage import (
 from .metrics import CLIENT_REQUEST_DURATION_SECONDS, CLIENT_REQUESTS, NOOP_METRICS, MetricsRecorder
 from .nexus import NexusOperationResult, nexus_request_payload
 from .retry_policy import TransportRetryPolicy
+from .worker_session import WorkerSessionOptions
 
 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,
+        "supported": True,
         "minimum_protocol_version": "1.18",
-        "reason": "python_worker_has_no_typed_session_lifecycle",
+        "implementation": "typed_worker_session",
     },
     "sticky_execution": {
         "supported": False,
@@ -1316,7 +1317,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 +4115,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 +4129,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:
@@ -4667,6 +4671,7 @@ class Client:
         supported_activity_types: list[str] | None = None,
         max_concurrent_workflow_tasks: int | None = None,
         max_concurrent_activity_tasks: int | None = None,
+        max_concurrent_worker_sessions: int | None = None,
         runtime: str = "python",
         sdk_version: str | None = None,
         build_id: str | None = None,
@@ -4690,6 +4695,8 @@ class Client:
             raise ValueError("max_concurrent_workflow_tasks must be at least 1")
         if max_concurrent_activity_tasks is not None and max_concurrent_activity_tasks < 1:
             raise ValueError("max_concurrent_activity_tasks must be at least 1")
+        if max_concurrent_worker_sessions is not None and max_concurrent_worker_sessions < 1:
+            raise ValueError("max_concurrent_worker_sessions must be at least 1")
         if (
             capabilities
             and _MESSAGE_STREAMS_CAPABILITY in capabilities
@@ -4718,6 +4725,8 @@ class Client:
             body["max_concurrent_workflow_tasks"] = max_concurrent_workflow_tasks
         if max_concurrent_activity_tasks is not None:
             body["max_concurrent_activity_tasks"] = max_concurrent_activity_tasks
+        if max_concurrent_worker_sessions is not None:
+            body["max_concurrent_worker_sessions"] = max_concurrent_worker_sessions
         if task_slots is not None:
             body["task_slots"] = task_slots
         if process_metrics is not None:
@@ -4726,6 +4735,32 @@ class Client:
             body["heartbeat_interval_seconds"] = heartbeat_interval_seconds
         return await self._request("POST", "/worker/register", worker=True, json=body)
 
+    async def create_worker_session(
+        self, worker_id: str, options: WorkerSessionOptions
+    ) -> dict[str, Any]:
+        return cast(dict[str, Any], await self._request(
+            "POST", "/worker/sessions", worker=True,
+            json={"worker_id": worker_id, **options.to_wire()},
+        ))
+
+    async def renew_worker_session(
+        self, worker_id: str, session_id: str, lease_seconds: int
+    ) -> dict[str, Any]:
+        if lease_seconds < 1:
+            raise ValueError("worker session lease_seconds must be positive")
+        return cast(dict[str, Any], await self._request(
+            "POST", f"/worker/sessions/{quote(session_id, safe='')}/heartbeat", worker=True,
+            json={"worker_id": worker_id, "lease_seconds": lease_seconds},
+        ))
+
+    async def close_worker_session(
+        self, worker_id: str, session_id: str, reason: str = "worker_shutdown"
+    ) -> dict[str, Any]:
+        return cast(dict[str, Any], await self._request(
+            "DELETE", f"/worker/sessions/{quote(session_id, safe='')}", worker=True,
+            json={"worker_id": worker_id, "reason": reason},
+        ))
+
     async def deregister_worker_registration(self, worker_id: str) -> dict[str, Any]:
         """Remove this runtime's successful worker-plane registration.
 
@@ -4964,6 +4999,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.3.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.3.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,