durable-workflow 2.13.1__tar.gz → 2.14.0__tar.gz

{durable_workflow-2.13.1/src/durable_workflow.egg-info → durable_workflow-2.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: durable-workflow
-Version: 2.13.1
+Version: 2.14.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.13.1 → durable_workflow-2.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "durable-workflow"
-version = "2.13.1"
+version = "2.14.0"
 description = "Python client and worker SDK for Durable Workflow Cloud and self-hosted Server"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -79,8 +79,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.13.1"
-registry-version = "2.13.1"
+product-train = "2.14.0"
+registry-version = "2.14.0"
 supported-server-versions = "2.8.0"
 supported-server-release-baselines = { "2" = "2.8.0", "3" = "3.0.0" }
 worker-protocol-version = "1.20"

{durable_workflow-2.13.1 → durable_workflow-2.14.0}/src/durable_workflow/__init__.py

@@ -98,6 +98,7 @@ from .errors import (
     ScheduleNotFound,
     ServerError,
     SignalFailed,
+    TypedValueError,
     Unauthorized,
     UpdateFailed,
     UpdateRejected,
@@ -280,6 +281,7 @@ __all__ = [
     "AuthCompositionContract",
     "AuthCompositionContractError",
     "NonRetryableError",
+    "TypedValueError",
     "ReplayOutcome",
     "Replayer",
     "Saga",

{durable_workflow-2.13.1 → durable_workflow-2.14.0}/src/durable_workflow/_cancellation_scope_history.py

@@ -122,10 +122,15 @@ def _cleanup_operation(event: dict[str, Any], prefix: Sequence[dict[str, Any]],
         "authority_deadline_at": _canonical_time(authority),
     }
     sequence = payload.get("sequence")
+    # Only an explicit null reads as one call, as in Core; any other value
+    # that is not a positive integer is refused, never narrowed.
+    span = 1 if recorded.get("sequence_span") is None else recorded["sequence_span"]
+    if not _positive(span) or not _positive(recorded.get("sequence")):
+        raise _invalid(operation + " follows a delivery without a canonical sequence span")
     deadline = scope_timestamp(expected["authority_deadline_at"])
     timestamp = scope_timestamp(event.get("timestamp", event.get("recorded_at")))
     if (snapshot != expected or scope_id != context.scope_id
-        or not _positive(sequence) or sequence < recorded["sequence"] + recorded["sequence_span"]
+        or not _positive(sequence) or sequence < recorded["sequence"] + span
         or not _positive(event.get("sequence")) or delivery["sequence"] >= event["sequence"]
         or timestamp < scope_timestamp(delivery.get("timestamp", delivery.get("recorded_at")))
         or timestamp >= deadline or not local and (

{durable_workflow-2.13.1 → durable_workflow-2.14.0}/src/durable_workflow/_cooperative_cancellation.py

@@ -112,7 +112,9 @@ class CancellationDelivery:
         request_id = _text(payload.get("workflow_command_id"), "workflow_command_id")
         sequence = _positive(payload.get("sequence"), "sequence")
         kind = _text(payload.get("call_kind"), "call_kind")
-        span = _positive(payload.get("sequence_span", 1), "sequence_span", maximum=1000)
+        # Absent and null both mean one call, as Core's WorkflowStepHistory reads it.
+        recorded_span = payload.get("sequence_span")
+        span = _positive(1 if recorded_span is None else recorded_span, "sequence_span", maximum=1000)
         operation = payload.get("operation_sequence")
         operation_span = _positive(payload.get("operation_sequence_span", 1), "operation_sequence_span", maximum=1000)
         if kind not in _CALL_KINDS or (kind != "parallel" and span != 1):

durable_workflow-2.14.0/src/durable_workflow/_typed_values.py

@@ -0,0 +1,311 @@
+"""Opt-in conversion between neutral payload values and annotated Python types.
+
+The wire format stays the neutral Avro Value: a dataclass travels as the
+string-keyed map of its fields and an ``Enum`` as its value, exactly as
+``dataclasses.asdict()`` and ``.value`` would produce by hand. Decoding is
+driven only by the receiver's own annotations, so no class name, tag or
+pickled object ever enters durable history.
+
+Decoding follows payload-evolution rules for rolling deploys: keys a target
+dataclass does not declare are ignored, and a missing field takes its
+default. A value that cannot be converted raises
+:class:`~durable_workflow.errors.TypedValueError`, which names the field path
+and the expected type but never the value.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import functools
+import inspect
+import types
+from collections.abc import Callable
+from enum import Enum
+from typing import Any, Union, cast, get_args, get_origin, get_type_hints
+
+from .errors import TypedValueError
+
+_SCALARS: tuple[type, ...] = (str, int, float, bool, bytes)
+_PASS_THROUGH = (Any, object, inspect.Parameter.empty)
+
+
+def _type_name(annotation: Any) -> str:
+    """A short, module-free name for diagnostics, such as ``list[Item]``."""
+    if annotation is type(None) or annotation is None:
+        return "None"
+    if _is_union(annotation):
+        options = get_args(annotation)
+        concrete = [option for option in options if option is not type(None)]
+        if len(concrete) == 1 and len(options) == 2:
+            return f"Optional[{_type_name(concrete[0])}]"
+        return " | ".join(_type_name(option) for option in options)
+    origin = get_origin(annotation)
+    if origin is not None:
+        arguments = ", ".join(_type_name(argument) for argument in get_args(annotation))
+        name = getattr(origin, "__name__", repr(origin).replace("typing.", ""))
+        return f"{name}[{arguments}]" if arguments else name
+    if isinstance(annotation, type):
+        return annotation.__qualname__
+    return repr(annotation).replace("typing.", "")
+
+
+def _json_kind(value: Any) -> str:
+    """The neutral kind of a received value, never the value itself."""
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, int):
+        return "integer"
+    if isinstance(value, float):
+        return "number"
+    if isinstance(value, str):
+        return "string"
+    if isinstance(value, bytes):
+        return "bytes"
+    if isinstance(value, list):
+        return "array"
+    if isinstance(value, dict):
+        return "object"
+    return type(value).__name__
+
+
+def _optional_member(annotation: Any) -> Any:
+    """Return T for Optional[T]; refuse every other union as ambiguous."""
+    options = get_args(annotation)
+    concrete = [option for option in options if option is not type(None)]
+    if len(concrete) != 1 or len(concrete) == len(options):
+        raise TypeError(
+            f"typed values support only Optional[T] unions; {_type_name(annotation)} is ambiguous"
+        )
+    return concrete[0]
+
+
+def _is_union(annotation: Any) -> bool:
+    return get_origin(annotation) in (Union, types.UnionType)
+
+
+def _dataclass_hints(cls: type) -> dict[str, Any]:
+    try:
+        return get_type_hints(cls)
+    except (NameError, TypeError) as error:
+        raise TypeError(f"typed values cannot resolve the annotations of {cls.__qualname__}: {error}") from None
+
+
+def validate_annotation(annotation: Any, where: str, _seen: frozenset[type] = frozenset()) -> None:
+    """Refuse an annotation this contract cannot decode unambiguously.
+
+    Called when a typed activity is declared or a ``result_type`` is given, so
+    an unsupported type fails at definition time instead of passing a plain
+    value through silently.
+    """
+    if annotation in _PASS_THROUGH or annotation is None or annotation is type(None):
+        return
+    if _is_union(annotation):
+        validate_annotation(_optional_member(annotation), where, _seen)
+        return
+    origin = get_origin(annotation)
+    if annotation is list or origin is list:
+        for item in get_args(annotation):
+            validate_annotation(item, where, _seen)
+        return
+    if annotation is dict or origin is dict:
+        arguments = get_args(annotation)
+        if arguments:
+            if arguments[0] is not str:
+                raise TypeError(f"{where}: typed maps need str keys, not {_type_name(arguments[0])}")
+            validate_annotation(arguments[1], where, _seen)
+        return
+    if isinstance(annotation, type) and issubclass(annotation, Enum):
+        for member in annotation:
+            if not isinstance(member.value, str | int | float):
+                raise TypeError(
+                    f"{where}: {annotation.__qualname__} members must have str, int or float values"
+                )
+        return
+    if isinstance(annotation, type) and dataclasses.is_dataclass(annotation):
+        if annotation in _seen:
+            return
+        hints = _dataclass_hints(annotation)
+        for item in dataclasses.fields(annotation):
+            if item.init:
+                validate_annotation(hints.get(item.name, Any), f"{where}.{item.name}", _seen | {annotation})
+        return
+    if isinstance(annotation, type) and annotation in _SCALARS:
+        return
+    raise TypeError(f"{where}: typed values do not support {_type_name(annotation)}")
+
+
+def decode_payload_value(value: Any, annotation: Any, path: str = "value") -> Any:
+    """Decode an untrusted payload value; every refusal is a TypedValueError."""
+    try:
+        return from_payload_value(value, annotation, path)
+    except RecursionError:
+        raise TypedValueError(path, _type_name(annotation), "the value is nested too deeply") from None
+
+
+def from_payload_value(value: Any, annotation: Any, path: str = "value") -> Any:
+    """Return *value* converted to *annotation*, which must be validated."""
+    if annotation in _PASS_THROUGH:
+        return value
+    if annotation is None or annotation is type(None):
+        if value is not None:
+            raise TypedValueError(path, "None", f"got {_json_kind(value)}")
+        return None
+    if _is_union(annotation):
+        if value is None:
+            return None
+        return from_payload_value(value, _optional_member(annotation), path)
+    if value is None:
+        raise TypedValueError(path, _type_name(annotation), "got null")
+
+    origin = get_origin(annotation)
+    if annotation is list or origin is list:
+        if not isinstance(value, list):
+            raise TypedValueError(path, _type_name(annotation), f"got {_json_kind(value)}")
+        (item_type,) = get_args(annotation) or (Any,)
+        return [from_payload_value(item, item_type, f"{path}[{index}]") for index, item in enumerate(value)]
+
+    if annotation is dict or origin is dict:
+        if not isinstance(value, dict):
+            raise TypedValueError(path, _type_name(annotation), f"got {_json_kind(value)}")
+        _, item_type = get_args(annotation) or (str, Any)
+        # Map keys are user data (for example email addresses), so a path names
+        # an entry by its position, never by its key.
+        return {
+            key: from_payload_value(item, item_type, f"{path}[entry {index}]")
+            for index, (key, item) in enumerate(value.items())
+        }
+
+    if isinstance(annotation, type) and issubclass(annotation, Enum):
+        return _enum_from_payload(value, annotation, path)
+
+    if isinstance(annotation, type) and dataclasses.is_dataclass(annotation):
+        return _dataclass_from_payload(value, annotation, path)
+
+    if annotation is float and isinstance(value, int) and not isinstance(value, bool):
+        return float(value)
+    if annotation is int and isinstance(value, bool):
+        raise TypedValueError(path, "int", "got boolean")
+    if isinstance(annotation, type) and annotation in _SCALARS:
+        if not isinstance(value, annotation):
+            raise TypedValueError(path, annotation.__qualname__, f"got {_json_kind(value)}")
+        return value
+    raise TypeError(f"{path}: typed values do not support {_type_name(annotation)}")
+
+
+def _enum_from_payload(value: Any, cls: type[Enum], path: str) -> Enum:
+    if isinstance(value, cls):
+        return value
+    for member in cls:
+        expected = member.value
+        same_kind = type(expected) is type(value) or (type(expected) is float and type(value) is int)
+        if same_kind and expected == value:
+            return member
+    # The diagnostic must not echo the received value.
+    raise TypedValueError(path, cls.__qualname__, f"the {_json_kind(value)} is not a member")
+
+
+def _dataclass_from_payload(value: Any, cls: type, path: str) -> Any:
+    if isinstance(value, cls):
+        return value
+    if not isinstance(value, dict):
+        raise TypedValueError(path, cls.__qualname__, f"got {_json_kind(value)}")
+    hints = _dataclass_hints(cls)
+    arguments: dict[str, Any] = {}
+    for item in dataclasses.fields(cls):
+        if not item.init:
+            # Computed fields are derived again by the dataclass itself.
+            continue
+        field_path = f"{path}.{item.name}"
+        annotation = hints.get(item.name, Any)
+        if item.name in value:
+            arguments[item.name] = from_payload_value(value[item.name], annotation, field_path)
+        elif item.default is dataclasses.MISSING and item.default_factory is dataclasses.MISSING:
+            raise TypedValueError(field_path, _type_name(annotation), "the field is missing")
+    # Keys the receiver does not declare are ignored for rolling deploys.
+    try:
+        return cls(**arguments)
+    except ValueError:
+        # A __post_init__ check refused the decoded fields. Its message can
+        # carry the values, so it is not repeated here.
+        raise TypedValueError(path, cls.__qualname__, "the dataclass refused the decoded fields") from None
+
+
+def to_payload_value(value: Any) -> Any:
+    """Return the neutral value for dataclass and ``Enum`` values, recursively.
+
+    Every other value is returned unchanged, so the codec keeps refusing what
+    it refuses today (for example datetimes and tuples). The result encodes
+    to the same bytes as ``dataclasses.asdict()`` with each ``Enum`` replaced
+    by its ``.value``.
+    """
+    if isinstance(value, Enum):
+        return to_payload_value(value.value)
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return {item.name: to_payload_value(getattr(value, item.name)) for item in dataclasses.fields(value)}
+    if isinstance(value, list):
+        return [to_payload_value(item) for item in value]
+    if isinstance(value, dict):
+        return {key: to_payload_value(item) for key, item in value.items()}
+    return value
+
+
+def to_payload_values(values: list[Any]) -> list[Any]:
+    return [to_payload_value(value) for value in values]
+
+
+def typed_callable(fn: Callable[..., Any]) -> Callable[..., Any]:
+    """Wrap *fn* so positional arguments decode to its annotations.
+
+    Annotations are validated here, so an unsupported type fails when the
+    activity is declared. The wrapper keeps *fn*'s module and qualified name:
+    the decorator binds that name to the wrapper, so supervised callbacks that
+    pickle by reference resolve to it.
+    """
+    signature = inspect.signature(fn)
+    try:
+        hints = get_type_hints(fn)
+    except (NameError, TypeError) as error:
+        raise TypeError(f"typed activity {fn.__qualname__} has unresolvable annotations: {error}") from None
+    positional: list[tuple[str, Any]] = []
+    variadic: tuple[str, Any] | None = None
+    for parameter in signature.parameters.values():
+        annotation = hints.get(parameter.name, Any)
+        if parameter.kind in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD):
+            validate_annotation(annotation, parameter.name)
+            positional.append((parameter.name, annotation))
+        elif parameter.kind is inspect.Parameter.VAR_POSITIONAL:
+            validate_annotation(annotation, parameter.name)
+            variadic = (parameter.name, annotation)
+
+    def convert(args: tuple[Any, ...]) -> list[Any]:
+        converted: list[Any] = []
+        for index, value in enumerate(args):
+            if index < len(positional):
+                name, annotation = positional[index]
+                converted.append(decode_payload_value(value, annotation, name))
+            elif variadic is not None:
+                name, annotation = variadic
+                converted.append(decode_payload_value(value, annotation, f"{name}[{index - len(positional)}]"))
+            else:
+                converted.append(value)
+        return converted
+
+    wrapper: Any
+    if inspect.iscoroutinefunction(fn):
+
+        @functools.wraps(fn)
+        async def typed_async(*args: Any, **kwargs: Any) -> Any:
+            return to_payload_value(await fn(*convert(args), **kwargs))
+
+        wrapper = typed_async
+    else:
+
+        @functools.wraps(fn)
+        def typed_sync(*args: Any, **kwargs: Any) -> Any:
+            return to_payload_value(fn(*convert(args), **kwargs))
+
+        wrapper = typed_sync
+    wrapper.__typed_activity__ = fn
+    return cast(Callable[..., Any], wrapper)

{durable_workflow-2.13.1 → durable_workflow-2.14.0}/src/durable_workflow/activity.py

@@ -206,10 +206,25 @@ def _set_context(ctx: ActivityContext | None) -> contextvars.Token[ActivityConte
     return _current_context.set(ctx)
 
 
-def defn(*, name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
-    """Register a callable as an activity type under a language-neutral name."""
+def defn(*, name: str, typed: bool = False) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Register a callable as an activity type under a language-neutral name.
+
+    With ``typed=True``, positional arguments are decoded to the callable's
+    parameter annotations: dataclasses, ``Enum`` (including ``IntEnum`` and
+    ``StrEnum``), ``Optional[T]``, ``list[T]``, ``dict[str, T]`` and the
+    scalars ``str``, ``int``, ``float``, ``bool`` and ``bytes``. Keys a
+    dataclass does not declare are ignored and missing fields take their
+    defaults. A value that does not match fails the activity without retries
+    with :class:`~durable_workflow.errors.TypedValueError`. An annotation
+    outside this list raises ``TypeError`` here, when the activity is
+    declared. Untyped activities keep receiving plain values.
+    """
 
     def wrap(fn: Callable[..., Any]) -> Callable[..., Any]:
+        if typed:
+            from ._typed_values import typed_callable
+
+            fn = typed_callable(fn)
         fn.__activity_name__ = name  # type: ignore[attr-defined]
         _REGISTRY[name] = fn
         return fn

{durable_workflow-2.13.1 → durable_workflow-2.14.0}/src/durable_workflow/errors.py

@@ -881,6 +881,26 @@ class NonRetryableError(DurableWorkflowError):
         self.__cause__ = cause
 
 
+class TypedValueError(NonRetryableError, TypeError):
+    """A payload value does not match the receiver's declared type.
+
+    Raised by opt-in typed values: a ``typed=True`` activity's arguments, or an
+    activity result decoded to ``result_type``. ``path`` names the field (for
+    example ``order.items[2].sku``) and ``expected`` the declared type. The
+    message never contains the received value. An activity whose arguments do
+    not match fails without retries, because a retry cannot change the payload.
+    """
+
+    def __init__(self, path: str, expected: str, detail: str) -> None:
+        self.path = path
+        self.expected = expected
+        self.detail = detail
+        super().__init__(f"{path}: expected {expected}; {detail}")
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        return (type(self), (self.path, self.expected, self.detail))
+
+
 class AvroNotInstalledError(DurableWorkflowError, ImportError):
     """Raised when the core ``avro`` runtime dependency is unavailable."""
 

{durable_workflow-2.13.1 → durable_workflow-2.14.0}/src/durable_workflow/testing.py

@@ -400,8 +400,19 @@ class WorkflowEnvironment:
                     }
                 )
             elif isinstance(cmd, UpsertSearchAttributes):
+                # Record the JSON wire form, as the Server does; replay
+                # checks the workflow's update against it.
                 history.append(
-                    {"event_type": "SearchAttributesUpserted", "payload": {}}
+                    {
+                        "event_type": "SearchAttributesUpserted",
+                        "payload": {
+                            # Every recorded event but a signal is a step.
+                            "sequence": 1 + sum(
+                                event["event_type"] != "SignalReceived" for event in history
+                            ),
+                            "attributes": json.loads(json.dumps(cmd.attributes)),
+                        },
+                    }
                 )
             elif isinstance(cmd, RecordVersionMarker):
                 history.append(

{durable_workflow-2.13.1 → durable_workflow-2.14.0}/src/durable_workflow/worker.py

@@ -49,6 +49,7 @@ from ._failure_reporting import REQUEST_BYTES, exception_message, normalize_loca
 from ._prepared_local_activity import PreparedAttempt, PreparedCancellationObserved, PreparedLocalRunner
 from ._query_task_authority import QueryTaskAuthority, current_query_authority
 from ._sticky_workflow_cache import CacheKey, StickyWorkflowCache, complete_history
+from ._typed_values import to_payload_value
 from .activity import ActivityContext, ActivityInfo, _set_context
 from .auth_composition import (
     AUTH_COMPOSITION_CONTRACT_SCHEMA,
@@ -2505,6 +2506,9 @@ class Worker:
                     "duration_ms": max(0, round((time.monotonic() - attempt_started_at) * 1000)),
                     "heartbeats": heartbeats,
                 })
+                # The workflow receives the same neutral value on this first
+                # run as on replay of the recorded result.
+                result = to_payload_value(result)
                 try:
                     inline_result = serializer.envelope(result, codec=payload_codec)
                 except Exception:
@@ -3270,6 +3274,7 @@ class Worker:
         finally:
             _set_context(None)
 
+        result = to_payload_value(result)
         log.info("completing activity task %s (%s) -> %r", task_id, activity_type, result)
         try:
             await self.client.complete_activity_task(