durable-workflow 2.5.3__tar.gz → 2.5.4__tar.gz

{durable_workflow-2.5.3/src/durable_workflow.egg-info → durable_workflow-2.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: durable-workflow
-Version: 2.5.3
+Version: 2.5.4
 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.3 → durable_workflow-2.5.4}/pyproject.toml

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

{durable_workflow-2.5.3 → durable_workflow-2.5.4}/src/durable_workflow/__init__.py

@@ -70,6 +70,7 @@ from .errors import (
     ChildWorkflowCancelled,
     ChildWorkflowFailed,
     ChildWorkflowTerminated,
+    DuplicateRegistrationError,
     DurableOperationCancelled,
     DurableWorkflowError,
     ExternalPayloadError,
@@ -370,6 +371,7 @@ __all__ = [
     "NexusOperationResult",
     "NexusServiceCall",
     "NonDeterministicReplayError",
+    "DuplicateRegistrationError",
     "InvalidWorkflowDefinition",
     "NoopMetrics",
     "QueryFailed",

{durable_workflow-2.5.3 → durable_workflow-2.5.4}/src/durable_workflow/errors.py

@@ -31,6 +31,30 @@ class InvalidWorkflowDefinition(DurableWorkflowError, ValueError):
     """Workflow authoring uses an unsupported entry point or result."""
 
 
+class DuplicateRegistrationError(DurableWorkflowError, ValueError):
+    """One registration scope assigns a wire name to multiple definitions."""
+
+    def __init__(
+        self, registration_kind: str, wire_name: str,
+        first_definition: object, second_definition: object,
+    ) -> None:
+        def label(definition: object) -> str:
+            if isinstance(definition, str):
+                return definition
+            module = getattr(definition, "__module__", type(definition).__module__)
+            name = getattr(definition, "__qualname__", type(definition).__qualname__)
+            return f"{module}.{name}"
+
+        self.registration_kind = registration_kind
+        self.wire_name = wire_name
+        self.first_definition = label(first_definition)
+        self.second_definition = label(second_definition)
+        super().__init__(
+            f"duplicate {registration_kind} name {wire_name!r}: "
+            f"{self.first_definition} conflicts with {self.second_definition}"
+        )
+
+
 class DurableOperationCancelled(DurableWorkflowError):
     """A durable selection member was explicitly cancelled."""
 

{durable_workflow-2.5.3 → durable_workflow-2.5.4}/src/durable_workflow/testing.py

@@ -39,7 +39,7 @@ from pathlib import Path
 from typing import Any
 
 from . import serializer
-from .errors import WorkflowCancelled, WorkflowFailed, WorkflowTerminated
+from .errors import DuplicateRegistrationError, WorkflowCancelled, WorkflowFailed, WorkflowTerminated
 from .workflow import (
     CompleteWorkflow,
     ContinueAsNew,
@@ -52,6 +52,7 @@ from .workflow import (
     StartTimer,
     UpsertSearchAttributes,
     _validate_workflow_entrypoint,
+    _workflow_handler_registries,
     registry,
     replay,
 )
@@ -136,6 +137,9 @@ class WorkflowEnvironment:
                 "decorate it with @workflow.defn(name=...) first."
             )
         _validate_workflow_entrypoint(workflow_cls)
+        _workflow_handler_registries(workflow_cls)
+        if name in self._registered_workflows and self._registered_workflows[name] is not workflow_cls:
+            raise DuplicateRegistrationError("workflow", name, self._registered_workflows[name], workflow_cls)
         self._registered_workflows[name] = workflow_cls
 
     def signal(

{durable_workflow-2.5.3 → durable_workflow-2.5.4}/src/durable_workflow/worker.py

@@ -66,6 +66,7 @@ from .errors import (
     ActivityCancelled,
     ActivityFailed,
     AvroNotInstalledError,
+    DuplicateRegistrationError,
     DurableWorkflowError,
     ExternalPayloadError,
     InvalidArgument,
@@ -106,6 +107,7 @@ from .workflow import (
     StartChildWorkflow,
     UpsertMemo,
     _validate_workflow_entrypoint,
+    _workflow_handler_registries,
     apply_update,
     commands_to_server_commands,
     query_state,
@@ -1028,7 +1030,11 @@ class Worker:
         self.workflows: dict[str, type] = {}
         for definition in workflows:
             _validate_workflow_entrypoint(definition)
-            self.workflows[_workflow_name(definition)] = definition
+            _workflow_handler_registries(definition)
+            name = _workflow_name(definition)
+            if name in self.workflows:
+                raise DuplicateRegistrationError("workflow", name, self.workflows[name], definition)
+            self.workflows[name] = definition
         self.workflow_definition_fingerprints = {
             workflow_type: _workflow_definition_fingerprint(workflow_cls)
             for workflow_type, workflow_cls in self.workflows.items()
@@ -1037,7 +1043,12 @@ class Worker:
             workflow_type: _workflow_command_contract(workflow_cls)
             for workflow_type, workflow_cls in self.workflows.items()
         }
-        self.activities = {_activity_name(a): a for a in activities}
+        self.activities: dict[str, Callable[..., Any]] = {}
+        for activity_definition in activities:
+            name = _activity_name(activity_definition)
+            if name in self.activities:
+                raise DuplicateRegistrationError("activity", name, self.activities[name], activity_definition)
+            self.activities[name] = activity_definition
         self.capabilities = tuple(dict.fromkeys(capability.strip() for capability in capabilities))
         self._sticky_cache = StickyWorkflowCache(
             sticky_cache_capacity, sticky_cache_max_bytes, sticky_cache_ttl_seconds,

{durable_workflow-2.5.3 → durable_workflow-2.5.4}/src/durable_workflow/workflow.py

@@ -58,6 +58,7 @@ from .errors import (
     ChildWorkflowCancelled,
     ChildWorkflowFailed,
     ChildWorkflowTerminated,
+    DuplicateRegistrationError,
     DurableOperationCancelled,
     InvalidWorkflowDefinition,
     NexusOperationFailed,
@@ -124,6 +125,29 @@ def _validate_workflow_result(value: Any, cls: type) -> None:
         )
 
 
+def _workflow_handler_registries(
+    cls: type,
+) -> tuple[dict[str, str], dict[str, str], dict[str, str], dict[str, str]]:
+    handlers: dict[str, dict[str, str]] = {kind: {} for kind in ("signal", "query", "update", "update_validator")}
+    for attr in dir(cls):
+        if attr.startswith("_"):
+            continue
+        member = getattr(cls, attr, None)
+        for kind, registry in handlers.items():
+            wire_name = getattr(member, f"__{kind}_name__", None)
+            if not isinstance(wire_name, str) or not wire_name:
+                continue
+            if kind == "signal" and wire_name == MESSAGE_STREAM_SIGNAL:
+                raise ValueError(f"signal name {wire_name!r} is reserved by the workflow runtime")
+            if wire_name in registry:
+                owner = f"{cls.__module__}.{cls.__qualname__}"
+                raise DuplicateRegistrationError(
+                    kind, wire_name, f"{owner}.{registry[wire_name]}", f"{owner}.{attr}",
+                )
+            registry[wire_name] = attr
+    return handlers["signal"], handlers["query"], handlers["update"], handlers["update_validator"]
+
+
 def defn(*, name: str) -> Callable[[type[_WorkflowT]], type[_WorkflowT]]:
     """Register a class as a workflow type under a language-neutral name.
 
@@ -136,28 +160,7 @@ def defn(*, name: str) -> Callable[[type[_WorkflowT]], type[_WorkflowT]]:
     def wrap(cls: type[_WorkflowT]) -> type[_WorkflowT]:
         cls.__workflow_name__ = name  # type: ignore[attr-defined]
         _validate_workflow_entrypoint(cls)
-        signals: dict[str, str] = {}
-        queries: dict[str, str] = {}
-        updates: dict[str, str] = {}
-        update_validators: dict[str, str] = {}
-        for attr in dir(cls):
-            if attr.startswith("_"):
-                continue
-            member = getattr(cls, attr, None)
-            signal_name = getattr(member, "__signal_name__", None)
-            if isinstance(signal_name, str) and signal_name:
-                if signal_name == MESSAGE_STREAM_SIGNAL:
-                    raise ValueError(f"signal name {signal_name!r} is reserved by the workflow runtime")
-                signals[signal_name] = attr
-            query_name = getattr(member, "__query_name__", None)
-            if isinstance(query_name, str) and query_name:
-                queries[query_name] = attr
-            update_name = getattr(member, "__update_name__", None)
-            if isinstance(update_name, str) and update_name:
-                updates[update_name] = attr
-            update_validator_name = getattr(member, "__update_validator_name__", None)
-            if isinstance(update_validator_name, str) and update_validator_name:
-                update_validators[update_validator_name] = attr
+        signals, queries, updates, update_validators = _workflow_handler_registries(cls)
         cls.__workflow_signals__ = signals  # type: ignore[attr-defined]
         cls.__workflow_queries__ = queries  # type: ignore[attr-defined]
         cls.__workflow_updates__ = updates  # type: ignore[attr-defined]
@@ -2578,9 +2581,12 @@ class Replayer:
     def __init__(self, *, workflows: Iterable[type]) -> None:
         self._workflows: dict[str, type] = {}
         for workflow_cls in workflows:
+            _workflow_handler_registries(workflow_cls)
             workflow_type = str(getattr(workflow_cls, "__workflow_name__", workflow_cls.__name__))
             if workflow_type in self._workflows:
-                raise ValueError(f"duplicate workflow type registered with Replayer: {workflow_type!r}")
+                raise DuplicateRegistrationError(
+                    "workflow", workflow_type, self._workflows[workflow_type], workflow_cls,
+                )
             self._workflows[workflow_type] = workflow_cls
         if not self._workflows:
             raise ValueError("Replayer requires at least one workflow class")

{durable_workflow-2.5.3 → durable_workflow-2.5.4/src/durable_workflow.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: durable-workflow
-Version: 2.5.3
+Version: 2.5.4
 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.3 → durable_workflow-2.5.4}/src/durable_workflow.egg-info/SOURCES.txt

@@ -95,6 +95,7 @@ tests/test_python_conformance.py
 tests/test_queries.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_conformance.py

durable_workflow-2.5.4/tests/test_registration_ambiguity.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+from unittest.mock import AsyncMock
+
+import pytest
+
+from durable_workflow import Client, DuplicateRegistrationError, DurableWorkflowError, Worker, activity, workflow
+from durable_workflow.testing import WorkflowEnvironment
+
+
+def run(self: Any, ctx: Any) -> int:
+    return 1
+
+
+def first(self: Any, *args: Any) -> None:
+    pass
+
+
+def second(self: Any, *args: Any) -> None:
+    pass
+
+
+def definition(name: str, cls_name: str, members: dict[str, Any] | None = None, bases: tuple[type, ...] = ()) -> type:
+    return workflow.defn(name=name)(type(cls_name, bases, {"run": run, **(members or {})}))
+
+
+@pytest.mark.parametrize("consumer", ["worker", "replayer", "environment"])
+def test_conflicting_workflow_names_report_both_definitions(consumer: str) -> None:
+    first_cls = definition("shared-workflow", "FirstWorkflow")
+    second_cls = definition("shared-workflow", "SecondWorkflow")
+    client = AsyncMock(spec=Client)
+    with pytest.raises(ValueError) as captured:
+        if consumer == "worker":
+            Worker(client, task_queue="registration", workflows=iter([first_cls, second_cls]))
+        elif consumer == "replayer":
+            workflow.Replayer(workflows=iter([first_cls, second_cls]))
+        else:
+            env = WorkflowEnvironment()
+            env.register_workflow(first_cls)
+            env.register_workflow(second_cls)
+    assert captured.value.registration_kind == "workflow"  # type: ignore[attr-defined]
+    assert captured.value.wire_name == "shared-workflow"  # type: ignore[attr-defined]
+    assert "FirstWorkflow" in str(captured.value)
+    assert "SecondWorkflow" in str(captured.value)
+    assert client.mock_calls == []
+
+
+@pytest.mark.parametrize("same_definition", [False, True])
+def test_worker_rejects_duplicate_activities_before_network(same_definition: bool) -> None:
+    first_activity = activity.defn(name="shared-activity")(first)
+    second_activity = first_activity if same_definition else activity.defn(name="shared-activity")(second)
+    client = AsyncMock(spec=Client)
+    with pytest.raises(ValueError) as captured:
+        Worker(client, task_queue="registration", activities=iter([first_activity, second_activity]))
+    assert captured.value.registration_kind == "activity"  # type: ignore[attr-defined]
+    assert captured.value.wire_name == "shared-activity"  # type: ignore[attr-defined]
+    assert "first" in str(captured.value)
+    assert ("first" if same_definition else "second") in str(captured.value)
+    assert client.mock_calls == []
+
+
+@pytest.mark.parametrize("consumer", ["worker", "replayer"])
+def test_duplicate_list_entry_is_rejected(consumer: str) -> None:
+    cls = definition("same-entry", "RepeatedWorkflow")
+    with pytest.raises(ValueError, match="same-entry"):
+        if consumer == "worker":
+            Worker(AsyncMock(spec=Client), task_queue="registration", workflows=[cls, cls])
+        else:
+            workflow.Replayer(workflows=[cls, cls])
+
+
+@pytest.mark.parametrize("kind", ["signal", "query", "update", "update_validator"])
+@pytest.mark.parametrize("inherited", [False, True])
+def test_conflicting_handler_names_are_rejected_at_decoration(kind: str, inherited: bool) -> None:
+    decorate: Callable[..., Any] = getattr(workflow, kind)
+    # Use distinct functions so metadata from one handler kind cannot bleed
+    # into the next parameterized definition.
+    def first_handler(self: Any, *args: Any) -> None:
+        pass
+
+    def second_handler(self: Any, *args: Any) -> None:
+        pass
+
+    bases = ()
+    members = {"first_handler": decorate("approve")(first_handler)}
+    if inherited:
+        base = definition(f"base-{kind}", "BaseWorkflow", members)
+        bases = (base,)
+        members = {}
+    members["second_handler"] = decorate("approve")(second_handler)
+    with pytest.raises(ValueError) as captured:
+        definition(f"ambiguous-{kind}", "AmbiguousWorkflow", members, bases)
+    assert captured.value.registration_kind == kind  # type: ignore[attr-defined]
+    assert captured.value.wire_name == "approve"  # type: ignore[attr-defined]
+    assert "first_handler" in str(captured.value)
+    assert "second_handler" in str(captured.value)
+
+
+@pytest.mark.parametrize("kind", ["signal", "query", "update", "update_validator"])
+def test_overriding_the_same_python_attribute_is_unambiguous(kind: str) -> None:
+    decorate: Callable[..., Any] = getattr(workflow, kind)
+    def original(self: Any) -> str:
+        return "original"
+
+    def replacement(self: Any) -> str:
+        return "replacement"
+
+    base = definition(f"override-base-{kind}", "OverrideBase", {"handler": decorate("approve")(original)})
+    child = definition(
+        f"override-child-{kind}", "OverrideChild", {"handler": decorate("approve")(replacement)}, (base,),
+    )
+    assert child().handler() == "replacement"
+
+
+@pytest.mark.parametrize("kind", ["signal", "query", "update", "update_validator"])
+@pytest.mark.parametrize("consumer", ["worker", "replayer", "environment"])
+def test_programmatic_workflow_admission_cannot_bypass_handler_validation(kind: str, consumer: str) -> None:
+    decorate: Callable[..., Any] = getattr(workflow, kind)
+    def first_handler(self: Any) -> None:
+        pass
+
+    def second_handler(self: Any) -> None:
+        pass
+
+    cls = type("ProgrammaticWorkflow", (), {
+        "__workflow_name__": "programmatic-workflow", "run": run,
+        "first_handler": decorate("approve")(first_handler),
+        "second_handler": decorate("approve")(second_handler),
+    })
+    client = AsyncMock(spec=Client)
+    with pytest.raises(DuplicateRegistrationError) as captured:
+        if consumer == "worker":
+            Worker(client, task_queue="registration", workflows=[cls])
+        elif consumer == "replayer":
+            workflow.Replayer(workflows=[cls])
+        else:
+            WorkflowEnvironment().register_workflow(cls)
+    assert captured.value.registration_kind == kind
+    assert captured.value.wire_name == "approve"
+    assert client.mock_calls == []
+
+
+def test_handler_names_are_scoped_by_kind() -> None:
+    cls = definition("scoped-handlers", "ScopedHandlers", {
+        "signal": workflow.signal("approve")(lambda self: None),
+        "query": workflow.query("approve")(lambda self: None),
+        "update": workflow.update("approve")(lambda self: None),
+        "validator": workflow.update_validator("approve")(lambda self: None),
+    })
+    assert cls.__workflow_signals__ == {"approve": "signal"}
+    assert cls.__workflow_queries__ == {"approve": "query"}
+    assert cls.__workflow_updates__ == {"approve": "update"}
+    assert cls.__workflow_update_validators__ == {"approve": "validator"}
+
+
+def test_distinct_names_and_separate_workers_remain_supported() -> None:
+    first_cls = definition("one", "FirstDistinct")
+    second_cls = definition("two", "SecondDistinct")
+    alternative = definition("one", "AlternativeDefinition")
+    client = AsyncMock(spec=Client)
+    worker = Worker(client, task_queue="registration", workflows=iter([first_cls, second_cls]))
+    assert worker.workflows == {"one": first_cls, "two": second_cls}
+    assert Worker(client, task_queue="other", workflows=[alternative]).workflows == {"one": alternative}
+    assert workflow.Replayer(workflows=[first_cls, second_cls]).replay([], workflow_type="one").commands[0].result == 1
+    assert client.mock_calls == []
+
+
+def test_environment_registration_is_idempotent_for_automatic_execution() -> None:
+    cls = definition("environment-idempotent", "EnvironmentWorkflow")
+    env = WorkflowEnvironment()
+    env.register_workflow(cls)
+    env.register_workflow(cls)
+    assert env.execute_workflow(cls) == 1
+    assert env.execute_workflow(cls) == 1
+
+
+def test_mock_replacement_is_an_explicit_test_setting() -> None:
+    env = WorkflowEnvironment()
+    env.register_activity("mock", lambda: "first")
+    env.register_activity("mock", lambda: "second")
+    assert env._activity_fns["mock"]() == "second"
+
+
+def test_duplicate_error_is_a_public_structured_sdk_error() -> None:
+    error = DuplicateRegistrationError("workflow", "duplicate", run, first)
+    assert isinstance(error, DurableWorkflowError)
+    assert isinstance(error, ValueError)
+    assert error.registration_kind == "workflow"
+    assert error.wire_name == "duplicate"
+    assert error.first_definition.endswith(".run")
+    assert error.second_definition.endswith(".first")

{durable_workflow-2.5.3 → durable_workflow-2.5.4}/tests/test_replay_regression_corpus.py

@@ -368,8 +368,18 @@ def _execute_fixture(fixture: dict[str, Any]) -> list[dict[str, Any]]:
 
     query = workflow.get("query")
     query_result: Any = None
+    registered_workflows = [WORKFLOW_TYPES[workflow_type]]
+    worker_registrations = workflow.get("worker_registrations")
+    if worker_registrations is not None:
+        assert isinstance(worker_registrations, list) and worker_registrations
+        assert all(isinstance(name, str) and name in WORKFLOW_TYPES for name in worker_registrations)
+        worker = Worker(
+            AsyncMock(spec=Client), task_queue="regression-corpus",
+            workflows=[WORKFLOW_TYPES[name] for name in worker_registrations],
+        )
+        registered_workflows = list(worker.workflows.values())
     if query is None:
-        outcome = Replayer(workflows=[WORKFLOW_TYPES[workflow_type]]).replay(
+        outcome = Replayer(workflows=registered_workflows).replay(
             history,
             start_input,
             workflow_type=workflow_type,