aws-durable-execution-sdk-python-testing 1.2.1__py3-none-any.whl → 1.3.0__py3-none-any.whl

aws_durable_execution_sdk_python_testing/model.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import datetime
+
+from aws_durable_execution_sdk_python_testing.clock import real_now
 import json
 from dataclasses import dataclass, replace
 from enum import Enum
@@ -35,8 +37,6 @@ from aws_durable_execution_sdk_python.lambda_service import (
 from aws_durable_execution_sdk_python.types import (
     LambdaContext as LambdaContextProtocol,
 )
-from dateutil.tz import UTC
-
 from aws_durable_execution_sdk_python_testing.exceptions import (
     InvalidParameterValueException,
 )
@@ -279,6 +279,26 @@ class GetDurableExecutionResponse:
         return result
 
 
+LATEST_PUBLISHED_QUALIFIER = "$LATEST.PUBLISHED"
+
+
+def executed_version(qualifier: str | None) -> str:
+    """The function version an invocation runs, as Lambda reports it.
+
+    The service records the version Lambda executed: a numeric qualifier
+    names it, ``$LATEST.PUBLISHED`` is reported as itself, and an alias
+    resolves to the version it points at. The runner keeps no published
+    versions or aliases. So a numeric qualifier and ``$LATEST.PUBLISHED``
+    are reported as given, and no qualifier, ``$LATEST`` or an alias is
+    reported as ``$LATEST``.
+    """
+    if qualifier is not None and (
+        qualifier.isdigit() or qualifier == LATEST_PUBLISHED_QUALIFIER
+    ):
+        return qualifier
+    return "$LATEST"
+
+
 @dataclass(frozen=True)
 class Execution:
     """Execution summary structure from Smithy model."""
@@ -317,18 +337,22 @@ class Execution:
         return result
 
     @classmethod
-    def from_execution(cls, execution, status: str) -> Execution:
-        """Create ExecutionSummary from Execution object."""
+    def from_execution(cls, execution, status: str, default_region: str) -> Execution:
+        """Create ExecutionSummary from Execution object.
+
+        ``default_region`` serves an execution stored before the runner
+        recorded regions; every other execution reports its own.
+        """
 
         execution_op = execution.get_operation_execution_started()
         return cls(
             durable_execution_arn=execution.durable_execution_arn,
             durable_execution_name=execution.start_input.execution_name,
-            function_arn=f"arn:aws:lambda:us-east-1:123456789012:function:{execution.start_input.function_name}",
+            function_arn=execution.function_arn(default_region),
             status=status,
             start_timestamp=execution_op.start_timestamp
             if execution_op.start_timestamp
-            else datetime.datetime.now(datetime.UTC),
+            else real_now(),
             end_timestamp=execution_op.end_timestamp
             if execution_op.end_timestamp
             else None,
@@ -1004,46 +1028,39 @@ class StepFailedDetails:
 
 
 @dataclass(frozen=True)
-class ChainedInvokePendingDetails:
-    """Chained Invoke Pending event details."""
+class ChainedInvokeStartedDetails:
+    """Chained invoke started event details.
+
+    ExecutedVersion is omitted: the local runner performs no function
+    version resolution, so it has no resolved version to report.
+    """
 
-    input: EventInput | None = None
     function_name: str | None = None
+    tenant_id: str | None = None
+    input: EventInput | None = None
+    durable_execution_arn: str | None = None
 
     @classmethod
-    def from_dict(cls, data: dict) -> ChainedInvokePendingDetails:
+    def from_dict(cls, data: dict) -> ChainedInvokeStartedDetails:
         input_data = None
         if input_dict := data.get("Input"):
             input_data = EventInput.from_dict(input_dict)
 
         return cls(
-            input=input_data,
             function_name=data.get("FunctionName"),
+            tenant_id=data.get("TenantId"),
+            input=input_data,
+            durable_execution_arn=data.get("DurableExecutionArn"),
         )
 
     def to_dict(self) -> dict[str, Any]:
         result: dict[str, Any] = {}
-        if self.input is not None:
-            result["Input"] = self.input.to_dict()
         if self.function_name is not None:
             result["FunctionName"] = self.function_name
-        return result
-
-
-@dataclass(frozen=True)
-class ChainedInvokeStartedDetails:
-    """Chained invoke started event details."""
-
-    durable_execution_arn: str | None = None
-
-    @classmethod
-    def from_dict(cls, data: dict) -> ChainedInvokeStartedDetails:
-        return cls(
-            durable_execution_arn=data.get("DurableExecutionArn"),
-        )
-
-    def to_dict(self) -> dict[str, Any]:
-        result: dict[str, Any] = {}
+        if self.tenant_id is not None:
+            result["TenantId"] = self.tenant_id
+        if self.input is not None:
+            result["Input"] = self.input.to_dict()
         if self.durable_execution_arn is not None:
             result["DurableExecutionArn"] = self.durable_execution_arn
         return result
@@ -1288,6 +1305,7 @@ class EventCreationContext:
     durable_execution_invocation_output: DurableExecutionInvocationOutput | None = None
     operation_update: OperationUpdate | None = None
     include_execution_data: bool = False  # noqa: FBT001, FBT002
+    child_execution_arn: str | None = None
 
     @classmethod
     def create(
@@ -1335,7 +1353,7 @@ class EventCreationContext:
         return (
             self.operation.start_timestamp
             if self.operation.start_timestamp is not None
-            else datetime.datetime.now(UTC)
+            else real_now()
         )
 
     @property
@@ -1343,7 +1361,7 @@ class EventCreationContext:
         return (
             self.operation.end_timestamp
             if self.operation.end_timestamp is not None
-            else datetime.datetime.now(UTC)
+            else real_now()
         )
 
 
@@ -1373,7 +1391,6 @@ class Event:
     step_started_details: StepStartedDetails | None = None
     step_succeeded_details: StepSucceededDetails | None = None
     step_failed_details: StepFailedDetails | None = None
-    chained_invoke_pending_details: ChainedInvokePendingDetails | None = None
     chained_invoke_started_details: ChainedInvokeStartedDetails | None = None
     chained_invoke_succeeded_details: ChainedInvokeSucceededDetails | None = None
     chained_invoke_failed_details: ChainedInvokeFailedDetails | None = None
@@ -1448,12 +1465,6 @@ class Event:
         if details_data := data.get("StepFailedDetails"):
             step_failed_details = StepFailedDetails.from_dict(details_data)
 
-        chained_invoke_pending_details = None
-        if details_data := data.get("ChainedInvokePendingDetails"):
-            chained_invoke_pending_details = ChainedInvokePendingDetails.from_dict(
-                details_data
-            )
-
         chained_invoke_started_details = None
         if details_data := data.get("ChainedInvokeStartedDetails"):
             chained_invoke_started_details = ChainedInvokeStartedDetails.from_dict(
@@ -1530,7 +1541,6 @@ class Event:
             step_started_details=step_started_details,
             step_succeeded_details=step_succeeded_details,
             step_failed_details=step_failed_details,
-            chained_invoke_pending_details=chained_invoke_pending_details,
             chained_invoke_started_details=chained_invoke_started_details,
             chained_invoke_succeeded_details=chained_invoke_succeeded_details,
             chained_invoke_failed_details=chained_invoke_failed_details,
@@ -1589,10 +1599,6 @@ class Event:
             result["StepSucceededDetails"] = self.step_succeeded_details.to_dict()
         if self.step_failed_details is not None:
             result["StepFailedDetails"] = self.step_failed_details.to_dict()
-        if self.chained_invoke_pending_details is not None:
-            result["ChainedInvokePendingDetails"] = (
-                self.chained_invoke_pending_details.to_dict()
-            )
         if self.chained_invoke_started_details is not None:
             result["ChainedInvokeStartedDetails"] = (
                 self.chained_invoke_started_details.to_dict()
@@ -2010,31 +2016,20 @@ class Event:
     # endregion step
 
     # region chained_invoke
-    @classmethod
-    def create_chained_invoke_event_pending(
-        cls, context: EventCreationContext
-    ) -> Event:
-        input: EventInput = EventInput.from_start_durable_execution_input(
-            context.start_durable_execution_input, context.include_execution_data
-        )
-        return cls(
-            event_type=EventType.CHAINED_INVOKE_STARTED.value,
-            event_timestamp=context.start_timestamp,
-            sub_type=context.sub_type,
-            event_id=context.event_id,
-            operation_id=context.operation.operation_id,
-            name=context.operation.name,
-            parent_id=context.operation.parent_id,
-            chained_invoke_pending_details=ChainedInvokePendingDetails(
-                input=input,
-                function_name=context.start_durable_execution_input.function_name,
-            ),
-        )
-
     @classmethod
     def create_chained_invoke_event_started(
         cls, context: EventCreationContext
     ) -> Event:
+        update: OperationUpdate | None = context.operation_update
+        function_name: str | None = None
+        payload: str | None = None
+        if update is not None:
+            payload = update.payload
+            if update.chained_invoke_options is not None:
+                function_name = update.chained_invoke_options.function_name
+        # The API shape has TenantId here; the service's history does not
+        # return it for this event. The runner matches the service, so a
+        # history assertion that passes locally passes against it.
         return cls(
             event_type=EventType.CHAINED_INVOKE_STARTED.value,
             event_timestamp=context.start_timestamp,
@@ -2044,7 +2039,16 @@ class Event:
             name=context.operation.name,
             parent_id=context.operation.parent_id,
             chained_invoke_started_details=ChainedInvokeStartedDetails(
-                durable_execution_arn=context.durable_execution_arn
+                function_name=function_name,
+                # No stored input, as for a target the runner could not
+                # resolve, means no Input on the event, as at the service.
+                input=EventInput(
+                    payload=payload if context.include_execution_data else None,
+                    truncated=not context.include_execution_data,
+                )
+                if payload is not None
+                else None,
+                durable_execution_arn=context.child_execution_arn,
             ),
         )
 
@@ -2157,7 +2161,7 @@ class Event:
         """Create chained invoke event based on action."""
         match context.operation.status:
             case OperationStatus.PENDING:
-                return cls.create_chained_invoke_event_pending(context)
+                return cls.create_chained_invoke_event_started(context)
             case OperationStatus.STARTED:
                 return cls.create_chained_invoke_event_started(context)
             case OperationStatus.SUCCEEDED:
@@ -2357,7 +2361,6 @@ class Event:
             step_started_details=event.step_started_details,
             step_succeeded_details=event.step_succeeded_details,
             step_failed_details=event.step_failed_details,
-            chained_invoke_pending_details=event.chained_invoke_pending_details,
             chained_invoke_started_details=event.chained_invoke_started_details,
             chained_invoke_succeeded_details=event.chained_invoke_succeeded_details,
             chained_invoke_failed_details=event.chained_invoke_failed_details,
@@ -2664,7 +2667,7 @@ def events_to_operations(events: list[Event]) -> list[Operation]:
             name=event.name,
             parent_id=event.parent_id,
             sub_type=sub_type,
-            start_timestamp=datetime.datetime.now(tz=datetime.timezone.utc),
+            start_timestamp=event.event_timestamp,
         )
 
         # Merge with previous operation if it exists
@@ -3219,9 +3222,12 @@ class CheckpointDurableExecutionRequest:
 
 @dataclass(frozen=True)
 class CheckpointDurableExecutionResponse:
-    """Response from checkpointing a durable execution."""
+    """Response from checkpointing a durable execution.
 
-    checkpoint_token: str
+    ``checkpoint_token`` is None when this invocation may checkpoint no further
+    """
+
+    checkpoint_token: str | None
     new_execution_state: CheckpointUpdatedExecutionState | None = None
 
     @classmethod
@@ -3231,12 +3237,14 @@ class CheckpointDurableExecutionResponse:
             new_execution_state = CheckpointUpdatedExecutionState.from_dict(state_data)
 
         return cls(
-            checkpoint_token=data["CheckpointToken"],
+            checkpoint_token=data.get("CheckpointToken"),
             new_execution_state=new_execution_state,
         )
 
     def to_dict(self) -> dict[str, Any]:
-        result: dict[str, Any] = {"CheckpointToken": self.checkpoint_token}
+        result: dict[str, Any] = {}
+        if self.checkpoint_token is not None:
+            result["CheckpointToken"] = self.checkpoint_token
         if self.new_execution_state is not None:
             result["NewExecutionState"] = self.new_execution_state.to_dict()
         return result

aws_durable_execution_sdk_python_testing/observer.py

@@ -1,31 +1,48 @@
-"""Checkpoint processors can notify the Execution of notable event state changes. Observer pattern."""
+"""Execution lifecycle effects: collection and application.
+
+While a batch of checkpoint updates is applied, the per-type processors
+record lifecycle effects (completion, failure, callback creation) on an
+:class:`ExecutionNotifier`. The checkpoint orchestrator then hands the
+collected effects to :func:`apply_effects`, which drives them onto an
+:class:`ExecutionObserver` after the write completes. Collecting first
+and applying afterwards keeps effect handling out of the write itself.
+"""
 
 from __future__ import annotations
 
-import threading
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING
 
-from aws_durable_execution_sdk_python_testing.token import CallbackToken
+from aws_durable_execution_sdk_python_testing.checkpoint.effects import (
+    CallbackCreated,
+    ChainedInvokeStarted,
+    Completed,
+    Failed,
+)
 
 if TYPE_CHECKING:
-    from collections.abc import Callable
+    from collections.abc import Iterable
 
     from aws_durable_execution_sdk_python.lambda_service import (
-        ErrorObject,
         CallbackOptions,
+        ErrorObject,
+    )
+
+    from aws_durable_execution_sdk_python_testing.checkpoint.effects import (
+        CheckpointEffect,
     )
+    from aws_durable_execution_sdk_python_testing.token import CallbackToken
 
 
 class ExecutionObserver(ABC):
-    """Observer for execution lifecycle events."""
+    """Receives execution lifecycle events."""
 
     @abstractmethod
     def on_completed(self, execution_arn: str, result: str | None = None) -> None:
         """Called when execution completes successfully."""
 
     @abstractmethod
-    def on_failed(self, execution_arn: str, error: ErrorObject) -> None:
+    def on_failed(self, execution_arn: str, error: ErrorObject | None) -> None:
         """Called when execution fails."""
 
     @abstractmethod
@@ -36,18 +53,6 @@ class ExecutionObserver(ABC):
     def on_stopped(self, execution_arn: str, error: ErrorObject) -> None:
         """Called when execution is stopped."""
 
-    @abstractmethod
-    def on_wait_timer_scheduled(
-        self, execution_arn: str, operation_id: str, delay: float
-    ) -> None:
-        """Called when wait timer scheduled."""
-
-    @abstractmethod
-    def on_step_retry_scheduled(
-        self, execution_arn: str, operation_id: str, delay: float
-    ) -> None:
-        """Called when step retry scheduled."""
-
     @abstractmethod
     def on_callback_created(
         self,
@@ -56,74 +61,37 @@ class ExecutionObserver(ABC):
         callback_options: CallbackOptions | None,
         callback_token: CallbackToken,
     ) -> None:
-        """Called when callback is created."""
-
+        """Called when a callback is created."""
 
-class ExecutionNotifier:
-    """Notifies observers about execution events. Thread-safe."""
+    @abstractmethod
+    def on_chained_invoke_started(
+        self,
+        execution_arn: str,
+        operation_id: str,
+        function_name: str,
+        tenant_id: str | None,
+        payload: str | None,
+    ) -> None:
+        """Called when a chained invoke is accepted and must be dispatched."""
 
-    def __init__(self) -> None:
-        self._observers: list[ExecutionObserver] = []
-        self._lock = threading.RLock()
-
-    def add_observer(self, observer: ExecutionObserver) -> None:
-        """Add an observer to be notified of execution events."""
-        with self._lock:
-            self._observers.append(observer)
-
-    def _notify_observers(self, method: Callable, *args, **kwargs) -> None:
-        """Notify all observers by calling the specified method."""
-        with self._lock:
-            observers = self._observers.copy()
-        for observer in observers:
-            getattr(observer, method.__name__)(*args, **kwargs)
-
-    # region event emitters
-    def notify_completed(self, execution_arn: str, result: str | None = None) -> None:
-        """Notify observers about execution completion."""
-        self._notify_observers(
-            ExecutionObserver.on_completed, execution_arn=execution_arn, result=result
-        )
 
-    def notify_failed(self, execution_arn: str, error: ErrorObject) -> None:
-        """Notify observers about execution failure."""
-        self._notify_observers(
-            ExecutionObserver.on_failed, execution_arn=execution_arn, error=error
-        )
+class ExecutionNotifier:
+    """Collects lifecycle effects raised while applying checkpoint updates.
 
-    def notify_timed_out(self, execution_arn: str, error: ErrorObject) -> None:
-        """Notify observers about execution timeout."""
-        self._notify_observers(
-            ExecutionObserver.on_timed_out, execution_arn=execution_arn, error=error
-        )
+    Processors record an effect here instead of acting on it; the
+    orchestrator reads :attr:`effects` once the updates are applied.
+    """
 
-    def notify_stopped(self, execution_arn: str, error: ErrorObject) -> None:
-        """Notify observers about execution being stopped."""
-        self._notify_observers(
-            ExecutionObserver.on_stopped, execution_arn=execution_arn, error=error
-        )
+    def __init__(self) -> None:
+        self.effects: list[CheckpointEffect] = []
 
-    def notify_wait_timer_scheduled(
-        self, execution_arn: str, operation_id: str, delay: float
-    ) -> None:
-        """Notify observers about wait timer scheduling."""
-        self._notify_observers(
-            ExecutionObserver.on_wait_timer_scheduled,
-            execution_arn=execution_arn,
-            operation_id=operation_id,
-            delay=delay,
-        )
+    def notify_completed(self, execution_arn: str, result: str | None = None) -> None:
+        """Record that the execution completed successfully."""
+        self.effects.append(Completed(execution_arn=execution_arn, result=result))
 
-    def notify_step_retry_scheduled(
-        self, execution_arn: str, operation_id: str, delay: float
-    ) -> None:
-        """Notify observers about step retry scheduling."""
-        self._notify_observers(
-            ExecutionObserver.on_step_retry_scheduled,
-            execution_arn=execution_arn,
-            operation_id=operation_id,
-            delay=delay,
-        )
+    def notify_failed(self, execution_arn: str, error: ErrorObject | None) -> None:
+        """Record that the execution failed."""
+        self.effects.append(Failed(execution_arn=execution_arn, error=error))
 
     def notify_callback_created(
         self,
@@ -132,13 +100,57 @@ class ExecutionNotifier:
         callback_options: CallbackOptions | None,
         callback_token: CallbackToken,
     ) -> None:
-        """Notify observers about callback creation."""
-        self._notify_observers(
-            ExecutionObserver.on_callback_created,
-            execution_arn=execution_arn,
-            operation_id=operation_id,
-            callback_options=callback_options,
-            callback_token=callback_token,
+        """Record that a callback was created."""
+        self.effects.append(
+            CallbackCreated(
+                execution_arn=execution_arn,
+                operation_id=operation_id,
+                callback_options=callback_options,
+                callback_token=callback_token,
+            )
         )
 
-    # endregion event emitters
+    def notify_chained_invoke_started(
+        self,
+        execution_arn: str,
+        operation_id: str,
+        function_name: str,
+        tenant_id: str | None,
+        payload: str | None,
+    ) -> None:
+        """Record that a chained invoke was accepted."""
+        self.effects.append(
+            ChainedInvokeStarted(
+                execution_arn=execution_arn,
+                operation_id=operation_id,
+                function_name=function_name,
+                tenant_id=tenant_id,
+                payload=payload,
+            )
+        )
+
+
+def apply_effects(
+    effects: Iterable[CheckpointEffect], observer: ExecutionObserver
+) -> None:
+    """Drive each collected effect onto ``observer``."""
+    for effect in effects:
+        if isinstance(effect, Completed):
+            observer.on_completed(effect.execution_arn, effect.result)
+        elif isinstance(effect, Failed):
+            observer.on_failed(effect.execution_arn, effect.error)
+        elif isinstance(effect, CallbackCreated):
+            observer.on_callback_created(
+                effect.execution_arn,
+                effect.operation_id,
+                effect.callback_options,
+                effect.callback_token,
+            )
+        elif isinstance(effect, ChainedInvokeStarted):
+            observer.on_chained_invoke_started(
+                effect.execution_arn,
+                effect.operation_id,
+                effect.function_name,
+                effect.tenant_id,
+                effect.payload,
+            )