durable-workflow 2.4.1__tar.gz → 2.4.3__tar.gz

{durable_workflow-2.4.1/src/durable_workflow.egg-info → durable_workflow-2.4.3}/PKG-INFO

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

{durable_workflow-2.4.1 → durable_workflow-2.4.3}/pyproject.toml

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

{durable_workflow-2.4.1 → durable_workflow-2.4.3}/src/durable_workflow/__init__.py

@@ -95,6 +95,7 @@ from .errors import (
     ServerError,
     SignalFailed,
     Unauthorized,
+    UpdateFailed,
     UpdateRejected,
     UpdateValidationFailed,
     WorkflowAlreadyStarted,
@@ -385,6 +386,7 @@ __all__ = [
     "SignalFailed",
     "TransportRetryPolicy",
     "Unauthorized",
+    "UpdateFailed",
     "UpdateRejected",
     "UpdateValidationFailed",
     "WorkflowAlreadyStarted",

{durable_workflow-2.4.1 → durable_workflow-2.4.3}/src/durable_workflow/client.py

@@ -4349,7 +4349,9 @@ class Client:
         :class:`~durable_workflow.errors.UpdateRejected` when the workflow's
         validator rejects the update, or
         :class:`~durable_workflow.errors.UpdateValidationFailed` when the
-        declared validation boundary cannot be enforced.
+        declared validation boundary cannot be enforced. An accepted update
+        whose handler fails raises :class:`~durable_workflow.errors.UpdateFailed`
+        with the failure message, Server response and durable identities.
         """
         await self._require_update_wait_stage(wait_for or "accepted")
         body: dict[str, Any] = {}
@@ -5115,11 +5117,23 @@ class Client:
 
         Worker-plane endpoint, called by :class:`~durable_workflow.Worker`.
         ``commands`` is the list of serialized commands the workflow yielded
-        for this task.
+        for this task. An empty list acknowledges waiting for already scheduled
+        history without reporting a workflow failure or scheduling another operation.
         """
         if (message_stream_cursors or message_stream_waits) and not _worker_protocol_supports_message_streams():
             raise ValueError("message stream completion metadata requires worker protocol 1.15 or newer")
 
+        if not commands:
+            if message_stream_cursors or message_stream_waits:
+                raise ValueError("Message stream completion metadata requires nonempty commands.")
+            return await self.fail_workflow_task(
+                task_id=task_id,
+                lease_owner=lease_owner,
+                workflow_task_attempt=workflow_task_attempt,
+                message="Workflow task waiting for scheduled history.",
+                failure_type="WorkflowTaskWaitingForHistory",
+            )
+
         body: dict[str, Any] = {
             "lease_owner": lease_owner,
             "workflow_task_attempt": workflow_task_attempt,

{durable_workflow-2.4.1 → durable_workflow-2.4.3}/src/durable_workflow/errors.py

@@ -453,6 +453,29 @@ class NonDeterministicReplayError(DurableWorkflowError):
         self.recorded_event_types = list(recorded_event_types)
 
 
+class UpdateFailed(InvalidArgument):
+    """An accepted workflow update failed during handler execution.
+
+    ``body`` preserves the Server response, including its durable failure
+    identity. This inherits from :class:`InvalidArgument` to preserve catches
+    written for earlier SDK versions that mapped all HTTP 422 responses there.
+    """
+
+    def __init__(self, message: str, *, status: int, body: dict[str, Any]) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body
+        self.workflow_id = self._identity(body, "workflow_id")
+        self.run_id = self._identity(body, "run_id")
+        self.update_id = self._identity(body, "update_id")
+        self.failure_id = self._identity(body, "failure_id")
+
+    @staticmethod
+    def _identity(body: dict[str, Any], name: str) -> str | None:
+        value = body.get(name)
+        return value if isinstance(value, str) and value.strip() else None
+
+
 class UpdateRejected(DurableWorkflowError):
     """A workflow update was rejected by the workflow's validator."""
 
@@ -859,6 +882,13 @@ def _raise_for_status(status: int, body: object, *, context: str = "") -> None:
             raise signal_failed("signal argument validation failed")
         if reason == "invalid_query_arguments":
             raise query_failed("query argument validation failed")
+        if isinstance(body, dict) and body.get("update_status") == "failed":
+            failure_message = body.get("failure_message")
+            if not isinstance(failure_message, str) or not failure_message.strip():
+                failure_message = message
+            if not isinstance(failure_message, str) or not failure_message.strip():
+                failure_message = "workflow update failed"
+            raise UpdateFailed(failure_message, status=status, body=body)
         errors = None
         if isinstance(body, dict):
             errors = body.get("errors") or body.get("validation_errors")

{durable_workflow-2.4.1 → durable_workflow-2.4.3/src/durable_workflow.egg-info}/PKG-INFO

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

{durable_workflow-2.4.1 → durable_workflow-2.4.3}/tests/test_client.py

@@ -30,6 +30,7 @@ from durable_workflow.errors import (
     ServerError,
     SignalFailed,
     Unauthorized,
+    UpdateFailed,
     UpdateRejected,
     WorkflowAlreadyStarted,
     WorkflowNotFound,
@@ -2903,6 +2904,25 @@ class TestFailWorkflowTask:
         assert mock.call_args.args[:2] == (fixture["request"]["method"], f"/api{fixture['request']['path']}")
         assert mock.call_args.kwargs["json"] == fixture["request"]["body"]
 
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize("metadata", [
+        {"message_stream_cursors": [{"stream_name": "input", "sequence": 7}]},
+        {"message_stream_waits": [{"stream_name": "input"}]},
+    ])
+    async def test_empty_completion_does_not_discard_message_stream_metadata(
+        self, client: Client, metadata: dict
+    ) -> None:
+        with (
+            patch.object(client._http, "request", new_callable=AsyncMock,
+                         return_value=_mock_response(200, {"completed": True})) as mock,
+            pytest.raises(ValueError, match="nonempty commands"),
+        ):
+            await client.complete_workflow_task(
+                task_id="task", lease_owner="owner", workflow_task_attempt=3,
+                commands=[], **metadata,
+            )
+        mock.assert_not_awaited()
+
     @pytest.mark.asyncio
     async def test_fail_workflow_task_matches_polyglot_fixture(self, client: Client) -> None:
         fixture_path = Path(__file__).parent / "fixtures" / "control-plane" / "workflow-task-fail-parity.json"
@@ -3071,6 +3091,34 @@ class TestHeartbeatActivityTask:
 
 
 class TestUpdateWorkflow:
+    @pytest.mark.asyncio
+    async def test_failed_update_retries_preserve_failure_identity(self, client: Client) -> None:
+        body = {
+            "update_status": "failed", "accepted": True,
+            "failure_message": "inventory unavailable", "workflow_id": "wf-1",
+            "run_id": "run-1", "update_id": "update-1", "failure_id": "failure-1",
+        }
+        with patch.object(
+            client._http, "request", new_callable=AsyncMock, return_value=_mock_response(422, body),
+        ) as request:
+            failures = []
+            for _ in range(2):
+                with pytest.raises(UpdateFailed) as exc_info:
+                    await client.update_workflow(
+                        "wf-1", "reserve", wait_for="completed", request_id="request-1",
+                    )
+                failures.append(exc_info.value)
+            assert request.await_count == 2
+            assert all(call.kwargs["json"]["request_id"] == "request-1"
+                       for call in request.await_args_list)
+        for error in failures:
+            assert str(error) == "inventory unavailable"
+            assert error.status == 422
+            assert error.body == body
+            assert (error.workflow_id, error.run_id, error.update_id, error.failure_id) == (
+                "wf-1", "run-1", "update-1", "failure-1",
+            )
+
     @pytest.mark.asyncio
     async def test_unsupported_wait_stage_raises_typed_error_before_update(self) -> None:
         client = Client("http://localhost:8080", token="test-token")

{durable_workflow-2.4.1 → durable_workflow-2.4.3}/tests/test_errors.py

@@ -13,6 +13,7 @@ from durable_workflow.errors import (
     ServerError,
     SignalFailed,
     Unauthorized,
+    UpdateFailed,
     UpdateRejected,
     UpdateValidationFailed,
     WorkflowAlreadyStarted,
@@ -102,6 +103,56 @@ class TestRaiseForStatus:
         with pytest.raises(InvalidArgument) as exc_info:
             _raise_for_status(422, {"message": "bad", "errors": {"f": ["req"]}})
         assert exc_info.value.errors == {"f": ["req"]}
+        assert type(exc_info.value) is InvalidArgument
+
+    def test_422_accepted_update_failure_preserves_diagnostics_and_legacy_catch(self) -> None:
+        body = {
+            "update_status": "failed", "accepted": True,
+            "failure_message": "inventory unavailable", "message": "generic failure",
+            "workflow_id": "wf-1", "run_id": "run-1", "update_id": "update-1",
+            "failure_id": "failure-1",
+        }
+        with pytest.raises(InvalidArgument) as exc_info:
+            _raise_for_status(422, body)
+        error = exc_info.value
+        assert isinstance(error, UpdateFailed)
+        assert str(error) == "inventory unavailable"
+        assert error.status == 422
+        assert error.body is body
+        assert error.errors is None
+        assert (error.workflow_id, error.run_id, error.update_id, error.failure_id) == (
+            "wf-1", "run-1", "update-1", "failure-1",
+        )
+
+    @pytest.mark.parametrize("failure_message", [None, "", "  ", 42])
+    @pytest.mark.parametrize("message", ["handler failed", None, "", "  ", 42])
+    def test_update_failure_message_fallback(self, failure_message: object, message: object) -> None:
+        with pytest.raises(UpdateFailed) as exc_info:
+            _raise_for_status(422, {
+                "update_status": "failed", "failure_message": failure_message, "message": message,
+            })
+        assert str(exc_info.value) == (
+            message if message == "handler failed" else "workflow update failed"
+        )
+
+    def test_update_failure_missing_or_malformed_identities_remain_absent(self) -> None:
+        with pytest.raises(UpdateFailed) as exc_info:
+            _raise_for_status(422, {
+                "update_status": "failed", "workflow_id": 42, "run_id": " ", "update_id": None,
+            })
+        error = exc_info.value
+        assert (error.workflow_id, error.run_id, error.update_id, error.failure_id) == (
+            None, None, None, None,
+        )
+
+    def test_rejected_update_arguments_are_not_handler_failure(self) -> None:
+        with pytest.raises(InvalidArgument) as exc_info:
+            _raise_for_status(422, {
+                "update_status": "rejected", "message": "invalid arguments",
+                "validation_errors": {"quantity": ["must be positive"]},
+            })
+        assert type(exc_info.value) is InvalidArgument
+        assert exc_info.value.errors == {"quantity": ["must be positive"]}
 
     def test_422_update_validator_rejected_is_typed(self) -> None:
         with pytest.raises(UpdateRejected) as exc_info:
@@ -109,6 +160,7 @@ class TestRaiseForStatus:
                 422,
                 {
                     "reason": "update_validator_rejected",
+                    "update_status": "failed",
                     "message": "approval required",
                     "validation_errors": {"approved": ["must be true"]},
                 },
@@ -132,6 +184,7 @@ class TestRaiseForStatus:
                 status,
                 {
                     "reason": reason,
+                    "update_status": "failed",
                     "message": "validation could not complete",
                     "retryable": retryable,
                 },

{durable_workflow-2.4.1 → durable_workflow-2.4.3}/tests/test_pending_operation_replay.py

@@ -2,10 +2,12 @@
 from __future__ import annotations
 
 from typing import Any
+from unittest.mock import AsyncMock, patch
 
+import httpx
 import pytest
 
-from durable_workflow import serializer, workflow
+from durable_workflow import Client, Worker, serializer, workflow
 from durable_workflow.errors import NonDeterministicReplayError
 from durable_workflow.workflow import CompleteWorkflow, WorkflowContext, query_state, replay
 
@@ -78,6 +80,43 @@ def test_signal_replay_does_not_reschedule_pending_operation(kind: str) -> None:
         )
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("kind", OPENINGS)
+async def test_worker_acknowledges_pending_signal_replay_with_original_lease(kind: str) -> None:
+    history = initial_history() + [OPENINGS[kind], {
+        "event_type": "SignalReceived", "payload": {
+            "signal_name": "increment", "arguments": serializer.envelope([7]),
+        },
+    }]
+    requests = []
+
+    async def server(method, path, **kwargs):  # type: ignore[no-untyped-def]
+        body = kwargs["json"]
+        requests.append((method, path, body, kwargs["headers"]["Authorization"]))
+        if path.endswith("/complete") and not body["commands"]:
+            return httpx.Response(422, json={"message": "The commands field is required."},
+                                  request=httpx.Request(method, "http://test" + path))
+        assert path.endswith("/fail")
+        return httpx.Response(200, json={"outcome": "waiting_for_history", "recorded": True},
+                              request=httpx.Request(method, "http://test" + path))
+
+    async with Client("http://test", worker_token="worker-token") as client:
+        worker = Worker(client, task_queue="queue", worker_id="original-owner", workflows=[PendingOperation])
+        with patch.object(client._http, "request", new=AsyncMock(side_effect=server)):
+            commands = await worker._run_workflow_task({
+                "task_id": "original-task", "workflow_task_attempt": 4, "run_id": "original-run",
+                "workflow_type": "tests.replay.pending-operation", "history_events": history,
+                "payload_codec": "avro", "arguments": serializer.envelope([kind]),
+            })
+
+    assert commands == []
+    assert requests == [("POST", "/api/worker/workflow-tasks/original-task/fail", {
+        "lease_owner": "original-owner", "workflow_task_attempt": 4,
+        "failure": {"message": "Workflow task waiting for scheduled history.",
+                    "type": "WorkflowTaskWaitingForHistory"},
+    }, "Bearer worker-token")]
+
+
 @pytest.mark.parametrize("kind", OPENINGS)
 def test_new_operation_is_still_scheduled(kind: str) -> None:
     outcome = replay(PendingOperation, initial_history(), [kind])

{durable_workflow-2.4.1 → durable_workflow-2.4.3}/tests/test_sync.py

@@ -9,7 +9,7 @@ from unittest.mock import AsyncMock, patch
 import httpx
 import pytest
 
-from durable_workflow import serializer
+from durable_workflow import InvalidArgument, UpdateFailed, serializer
 from durable_workflow.client import WorkflowHandle
 from durable_workflow.external_storage import ExternalPayloadCache, LocalFilesystemExternalStorage
 from durable_workflow.sync import Client, SyncStandaloneActivityHandle, SyncWorkflowHandle
@@ -581,6 +581,34 @@ class TestSyncClientMaintenance:
 
 
 class TestSyncClientUpdate:
+    def test_failed_update_preserves_diagnostics(self) -> None:
+        body = {
+            "update_status": "failed", "failure_message": "inventory unavailable",
+            "workflow_id": "wf-1", "run_id": "run-1", "update_id": "update-1",
+            "failure_id": "failure-1",
+        }
+        with Client("http://localhost:8080") as client:
+            client._async._cluster_info = {
+                "control_plane": {"request_contract": {"operations": {"update": {
+                    "fields": {"wait_for": {"canonical_values": ["accepted", "completed"]}},
+                }}}},
+            }
+            with (
+                patch.object(client._async._http, "request", new_callable=AsyncMock,
+                             return_value=_mock_response(422, body)) as request,
+                pytest.raises(InvalidArgument) as exc_info,
+            ):
+                client.update_workflow("wf-1", "reserve", request_id="request-1")
+            error = exc_info.value
+            assert isinstance(error, UpdateFailed)
+            assert str(error) == "inventory unavailable"
+            assert error.status == 422
+            assert error.body == body
+            assert (error.workflow_id, error.run_id, error.update_id, error.failure_id) == (
+                "wf-1", "run-1", "update-1", "failure-1",
+            )
+            assert request.call_args.kwargs["json"]["request_id"] == "request-1"
+
     def test_update(self) -> None:
         client = Client("http://localhost:8080")
         client._async._cluster_info = {