durable-workflow 2.5.11__tar.gz → 2.5.13__tar.gz

{durable_workflow-2.5.11/src/durable_workflow.egg-info → durable_workflow-2.5.13}/PKG-INFO

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

{durable_workflow-2.5.11 → durable_workflow-2.5.13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "durable-workflow"
-version = "2.5.11"
+version = "2.5.13"
 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.11"
-registry-version = "2.5.11"
+product-train = "2.5.13"
+registry-version = "2.5.13"
 supported-server-versions = "2.5.16"
 worker-protocol-version = "1.20"
 control-plane-version = "2"

{durable_workflow-2.5.11 → durable_workflow-2.5.13}/src/durable_workflow/client.py

@@ -4323,7 +4323,9 @@ class Client:
         Queries are synchronous and non-mutating. The server runs the named
         query handler inside the workflow process and returns the decoded
         result. Raises :class:`~durable_workflow.errors.QueryFailed` if the
-        query was rejected or the handler errored.
+        query was rejected, the handler errored, or the original query timed
+        out. A canonical query timeout is surfaced without automatically
+        admitting another query.
         """
         await self._require_query_support()
         body: dict[str, Any] = {}

{durable_workflow-2.5.11 → durable_workflow-2.5.13}/src/durable_workflow/retry_policy.py

@@ -17,6 +17,7 @@ import contextvars
 import json
 import logging
 import random
+import re
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
 from typing import TypeVar
@@ -34,6 +35,24 @@ _worker_storage_admission_stop: contextvars.ContextVar[Callable[[], bool] | None
 )
 
 
+def _query_timeout_refusal(exc: httpx.HTTPStatusError) -> bool:
+    request = exc.request
+    if (exc.response.status_code != 504 or request.method != "POST"
+            or request.headers.get("X-Durable-Workflow-Control-Plane-Version") != "2"
+            or re.search(r"/api/workflows/[^/]+/query/[^/]+$", request.url.path) is None):
+        return False
+    try:
+        body = exc.response.json()
+    except ValueError:
+        return False
+    # This response ends an admitted query. Another POST creates a new task,
+    # rather than retrying the original task or its remaining caller budget.
+    reason = body.get("reason") if isinstance(body, dict) else None
+    return isinstance(reason, str) and reason in {
+        "query_worker_timeout", "query_worker_execution_timeout", "query_task_not_claimed",
+    }
+
+
 def _storage_refusal(exc: Exception) -> tuple[ServerError, str | None] | None:
     if not isinstance(exc, httpx.HTTPStatusError):
         return None
@@ -194,6 +213,8 @@ class TransportRetryPolicy:
     :class:`durable_workflow.workflow.ChildWorkflowRetryPolicy`.
 
     Uses exponential backoff with jitter to avoid thundering herd.
+    Canonical query timeouts end the original query and are surfaced without
+    another query admission; unrelated transient HTTP failures still retry.
     """
 
     max_attempts: int = 3
@@ -213,7 +234,7 @@ class TransportRetryPolicy:
 
         # Retry 5xx server errors and 429 rate limit
         if isinstance(exc, httpx.HTTPStatusError):
-            if _poll_capacity_refusal(exc):
+            if _query_timeout_refusal(exc) or _poll_capacity_refusal(exc):
                 return False
             return exc.response.status_code >= 500 or exc.response.status_code == 429
 

{durable_workflow-2.5.11 → durable_workflow-2.5.13}/src/durable_workflow/workflow.py

@@ -1937,10 +1937,14 @@ class WorkflowContext:
         workflow_command_id: str | None = None,
         cancel_requested: bool = False,
         allow_cancellation_scope_authoring: bool = False,
+        _allow_wall_clock: bool = True,
     ) -> None:
         self._workflow_id = workflow_id
         self._run_id = run_id
-        self._current_time = current_time or datetime.now(timezone.utc)
+        self._current_time = current_time
+        if self._current_time is None and _allow_wall_clock:
+            self._current_time = datetime.now(timezone.utc)
+        self._replay_clock_error: str | None = None
         self._workflow_command_id = workflow_command_id or run_id or workflow_id
         self._cancel_requested = bool(cancel_requested)
         self._cancellation_request_id: str | None = None
@@ -2538,6 +2542,12 @@ class WorkflowContext:
         return ContinueAsNew(workflow_type=workflow_type, arguments=list(args), task_queue=task_queue)
 
     def now(self) -> datetime:
+        """Return the persisted workflow-start time, fixed during replay."""
+        if self._current_time is None:
+            raise NonDeterministicReplayError(
+                0, "persisted workflow-start clock", [],
+                detail=self._replay_clock_error or "Workflow replay clock unavailable: missing persisted start time",
+            )
         return self._current_time
 
     def random(self) -> random.Random:
@@ -2548,7 +2558,7 @@ class WorkflowContext:
         return uuid.UUID(bytes=rand_bytes, version=4)
 
     def uuid7(self) -> uuid.UUID:
-        timestamp_ms = int(self._current_time.timestamp() * 1000)
+        timestamp_ms = int(self.now().timestamp() * 1000)
         if timestamp_ms < 0 or timestamp_ms >= (1 << 48):
             raise ValueError("ctx.uuid7() requires ctx.now() within the UUIDv7 timestamp range")
 
@@ -4276,13 +4286,22 @@ def _replay_state(
             resolved_sequences.add(sequence)
 
     workflow_start_time: datetime | None = None
+    replay_clock_error = "Workflow replay clock unavailable: missing WorkflowStarted persisted start time"
     for ev in events:
         etype = _history_event_type(ev)
         if etype == "WorkflowStarted":
-            ts = (ev.get("payload") or {}).get("timestamp")
-            if ts:
-                with contextlib.suppress(ValueError, TypeError):
-                    workflow_start_time = datetime.fromisoformat(str(ts).replace("Z", "+00:00"))
+            start_payload = ev.get("payload")
+            if not isinstance(start_payload, Mapping):
+                start_payload = {}
+            explicit_time = "timestamp" in start_payload
+            ts = start_payload.get("timestamp") if explicit_time else ev.get("recorded_at")
+            clock_source = "payload.timestamp" if explicit_time else "recorded_at"
+            replay_clock_error = f"Workflow replay clock unavailable: invalid or missing WorkflowStarted.{clock_source}"
+            if isinstance(ts, str):
+                with contextlib.suppress(ValueError):
+                    parsed_time = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+                    if parsed_time.tzinfo is not None and parsed_time.utcoffset() is not None:
+                        workflow_start_time = parsed_time
             break
 
     for sequence, membership in scope_history.memberships.items():
@@ -4298,7 +4317,9 @@ def _replay_state(
         workflow_command_id=workflow_command_id,
         cancel_requested=cancel_requested,
         allow_cancellation_scope_authoring=allow_cancellation_scope_authoring,
+        _allow_wall_clock=not events,
     )
+    ctx._replay_clock_error = replay_clock_error if workflow_start_time is None else None
     # Continue-as-new cursor checkpoints describe instance state that predates
     # this run. Seed them before the workflow opens its first stream wait so
     # both the durable wait key and worker acknowledgement use the global

{durable_workflow-2.5.11 → durable_workflow-2.5.13/src/durable_workflow.egg-info}/PKG-INFO

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

{durable_workflow-2.5.11 → durable_workflow-2.5.13}/src/durable_workflow.egg-info/SOURCES.txt

@@ -95,11 +95,13 @@ tests/test_public_boundary_scanner.py
 tests/test_pypi_project_surface.py
 tests/test_python_conformance.py
 tests/test_queries.py
+tests/test_query_timeout_retry.py
 tests/test_readme_quickstart.py
 tests/test_redrive_replay.py
 tests/test_registration_ambiguity.py
 tests/test_release_metadata.py
 tests/test_replay.py
+tests/test_replay_clock.py
 tests/test_replay_conformance.py
 tests/test_replay_regression_corpus.py
 tests/test_replay_verify.py

durable_workflow-2.5.13/tests/test_query_timeout_retry.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import httpx
+import pytest
+
+from durable_workflow import Client
+from durable_workflow.errors import QueryFailed
+from durable_workflow.retry_policy import TransportRetryPolicy
+
+
+@pytest.mark.parametrize("protocol", ["1.20", "1.19"])
+@pytest.mark.parametrize("reason", [
+    "query_worker_execution_timeout", "query_task_not_claimed", "query_worker_timeout",
+])
+@pytest.mark.parametrize("prefix", ["", "/api/runtime/v1/namespaces/example"])
+async def test_query_exposes_original_canonical_timeout_without_another_admission(
+    monkeypatch: pytest.MonkeyPatch, protocol: str, reason: str, prefix: str,
+) -> None:
+    monkeypatch.setenv("DURABLE_WORKFLOW_WORKER_PROTOCOL_VERSION", protocol)
+    original = {"reason": reason, "message": "Original query ended.",
+                "control_plane": {"operation": "query", "reason": reason}}
+    admissions = 0
+    discovery_protocols = []
+
+    def handle(request: httpx.Request) -> httpx.Response:
+        nonlocal admissions
+        if request.url.path.endswith("/api/cluster/info"):
+            discovery_protocols.append(request.headers["X-Durable-Workflow-Protocol-Version"])
+            return httpx.Response(200, json={
+                "worker_protocol": {"server_capabilities": {"query_tasks": True}},
+            })
+        assert request.url.path == prefix + "/api/workflows/original/query/total"
+        assert request.headers["X-Durable-Workflow-Control-Plane-Version"] == "2"
+        admissions += 1
+        if admissions == 1:
+            return httpx.Response(504, json=original)
+        # The old policy hides the original failure behind a distinct admission.
+        return httpx.Response(200, json={"result": "replacement-query"})
+
+    async with Client("https://runtime.example" + prefix, worker_token="worker", control_token="control",
+                      retry_policy=TransportRetryPolicy(initial_backoff_seconds=0, jitter=False)) as client:
+        await client._http.aclose()
+        client._http = httpx.AsyncClient(base_url=client.base_url, transport=httpx.MockTransport(handle))
+        with pytest.raises(QueryFailed) as failure:
+            await client.query_workflow("original", "total")
+    assert admissions == 1
+    assert discovery_protocols == [protocol]
+    assert failure.value.status == 504 and failure.value.reason == reason
+    assert failure.value.body == original
+
+
+@pytest.mark.parametrize(("method", "path", "status", "body", "headers"), [
+    ("POST", "/api/workflows/w/query/q", 504, {"reason": "gateway_timeout"},
+     {"X-Durable-Workflow-Control-Plane-Version": "2"}),
+    ("POST", "/api/workflows/w/query/q", 503, {"reason": "query_worker_timeout"},
+     {"X-Durable-Workflow-Control-Plane-Version": "2"}),
+    ("GET", "/api/workflows/w/query/q", 504, {"reason": "query_worker_timeout"},
+     {"X-Durable-Workflow-Control-Plane-Version": "2"}),
+    ("POST", "/api/workflows/w/signals/q", 504, {"reason": "query_worker_timeout"},
+     {"X-Durable-Workflow-Control-Plane-Version": "2"}),
+    ("POST", "/api/workflows/w/query/q", 504, {"reason": "query_worker_timeout"}, {}),
+    ("POST", "/api/workflows/w/query/q", 504, [],
+     {"X-Durable-Workflow-Control-Plane-Version": "2"}),
+    ("POST", "/api/workflows/w/query/q", 504, {"reason": []},
+     {"X-Durable-Workflow-Control-Plane-Version": "2"}),
+])
+def test_other_transport_failures_keep_existing_retry_policy(
+    method: str, path: str, status: int, body: object, headers: dict[str, str],
+) -> None:
+    request = httpx.Request(method, "https://runtime.example" + path, headers=headers)
+    response = httpx.Response(status, request=request, json=body)
+    error = httpx.HTTPStatusError("transport failure", request=request, response=response)
+    assert TransportRetryPolicy().should_retry(error, 0) is True

durable_workflow-2.5.13/tests/test_replay_clock.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from datetime import datetime
+from typing import Any
+from uuid import UUID
+
+import pytest
+
+from durable_workflow import workflow
+from durable_workflow.errors import NonDeterministicReplayError
+from durable_workflow.workflow import CompleteWorkflow, WorkflowContext, replay
+
+
+@workflow.defn(name="tests.replay.persisted-clock")
+class PersistedClockWorkflow:
+    def run(self, ctx: WorkflowContext) -> str:
+        return ctx.now().isoformat(timespec="microseconds")
+
+
+@workflow.defn(name="tests.replay.persisted-uuid7")
+class PersistedUUID7Workflow:
+    def run(self, ctx: WorkflowContext) -> str:
+        return str(ctx.uuid7())
+
+
+@workflow.defn(name="tests.replay.marker-clock")
+class MarkerClockWorkflow:
+    def run(self, ctx: WorkflowContext):  # type: ignore[no-untyped-def]
+        before = ctx.now().isoformat(timespec="microseconds")
+        version = yield ctx.get_version("clock-case", 0, 7)
+        after = ctx.now().isoformat(timespec="microseconds")
+        return [before, version, after, str(ctx.uuid7())]
+
+
+def result(workflow_cls: type, history: list[dict[str, Any]]) -> Any:
+    outcome = replay(workflow_cls, history, [], run_id="original-clock-run", payload_codec="avro")
+    assert len(outcome.commands) == 1
+    command = outcome.commands[0]
+    assert isinstance(command, CompleteWorkflow)
+    return command.result
+
+
+def test_recorded_start_time_survives_repeated_cold_reads_and_later_marker() -> None:
+    history = [
+        {"event_type": "WorkflowStarted", "recorded_at": "2026-06-01T12:00:00.123456Z", "payload": {}},
+        {"event_type": "VersionMarkerRecorded", "recorded_at": "2026-06-01T12:00:03.987654Z",
+         "payload": {"sequence": 1, "change_id": "clock-case", "version": 7,
+                     "min_supported": 0, "max_supported": 7}},
+    ]
+    original = deepcopy(history)
+    first = result(MarkerClockWorkflow, history)
+    second = result(MarkerClockWorkflow, history)
+    assert first == second
+    assert first[:3] == ["2026-06-01T12:00:00.123456+00:00", 7, "2026-06-01T12:00:00.123456+00:00"]
+    assert UUID(first[3]).int >> 80 == int(datetime.fromisoformat(first[0]).timestamp() * 1000)
+    assert history == original
+
+
+def test_explicit_payload_time_retains_precedence() -> None:
+    history = [{"event_type": "WorkflowStarted", "recorded_at": "2026-06-01T12:00:00.123456Z",
+                "payload": {"timestamp": "2026-06-01T14:01:02.654321+02:00"}}]
+    assert result(PersistedClockWorkflow, history) == "2026-06-01T14:01:02.654321+02:00"
+
+
+@pytest.mark.parametrize("invalid", [None, False, 123, "", "not-a-time", "2026-06-01T12:00:00"])
+@pytest.mark.parametrize("explicit", [False, True])
+@pytest.mark.parametrize("workflow_cls", [PersistedClockWorkflow, PersistedUUID7Workflow])
+def test_clock_helpers_refuse_invalid_time_without_fallback(
+    invalid: Any, explicit: bool, workflow_cls: type,
+) -> None:
+    event: dict[str, Any] = {"event_type": "WorkflowStarted", "payload": {}}
+    if explicit:
+        event["recorded_at"] = "2026-06-01T12:00:00.123456Z"
+        event["payload"]["timestamp"] = invalid
+    else:
+        event["recorded_at"] = invalid
+    with pytest.raises(NonDeterministicReplayError, match="Workflow replay clock unavailable"):
+        result(workflow_cls, [event])
+
+
+@pytest.mark.parametrize("history", [
+    [{"event_type": "WorkflowStarted", "payload": {}}],
+    [{"event_type": "SignalReceived", "payload": {"signal_name": "unhandled"}}],
+])
+def test_missing_replay_time_is_explicit(history: list[dict[str, Any]]) -> None:
+    with pytest.raises(NonDeterministicReplayError, match="Workflow replay clock unavailable"):
+        result(PersistedClockWorkflow, history)
+
+
+def test_empty_local_authoring_remains_available() -> None:
+    assert datetime.fromisoformat(result(PersistedClockWorkflow, [])).tzinfo is not None
+    assert UUID(result(PersistedUUID7Workflow, [])).version == 7

{durable_workflow-2.5.11 → durable_workflow-2.5.13}/tests/test_replay_regression_corpus.py

@@ -34,6 +34,7 @@ from tests.test_patch_history import (
     RepeatedPatchWorkflow,
 )
 from tests.test_pending_operation_replay import PendingOperation
+from tests.test_replay_clock import PersistedClockWorkflow
 from tests.test_update_signal_condition_replay import (
     PostConditionReceiversWorkflow,
     UpdateSignalConditionTimerWorkflow,
@@ -278,6 +279,7 @@ class NexusTargetWorkflow:
 
 
 WORKFLOWS = [
+    PersistedClockWorkflow,
     NexusTargetWorkflow,
     UnsupportedAsyncWorkflow,
     ChildPolicyAuthorWorkflow,