aws-durable-execution-sdk-python-testing 1.0.0__py3-none-any.whl

aws_durable_execution_sdk_python_testing/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2025-present Amazon.com, Inc. or its affiliates.
+#
+# SPDX-License-Identifier: Apache-2.0
+__version__ = "1.0.0"

aws_durable_execution_sdk_python_testing/__init__.py

@@ -0,0 +1,20 @@
+"""DurableExecutionsPythonTestingLibrary module."""
+
+from aws_durable_execution_sdk_python_testing.runner import (
+    DurableChildContextTestRunner,
+    DurableFunctionCloudTestRunner,
+    DurableFunctionTestResult,
+    DurableFunctionTestRunner,
+    WebRunner,
+    WebRunnerConfig,
+)
+
+
+__all__ = [
+    "DurableChildContextTestRunner",
+    "DurableFunctionCloudTestRunner",
+    "DurableFunctionTestResult",
+    "DurableFunctionTestRunner",
+    "WebRunner",
+    "WebRunnerConfig",
+]

aws_durable_execution_sdk_python_testing/checkpoint/__init__.py

@@ -0,0 +1 @@
+"""Checkpoint processing module for handling OperationUpdate transformations."""

aws_durable_execution_sdk_python_testing/checkpoint/processor.py

@@ -0,0 +1,101 @@
+"""Main checkpoint processor that orchestrates operation transformations."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from aws_durable_execution_sdk_python.lambda_service import (
+    CheckpointOutput,
+    CheckpointUpdatedExecutionState,
+    OperationUpdate,
+    StateOutput,
+)
+
+from aws_durable_execution_sdk_python_testing.checkpoint.transformer import (
+    OperationTransformer,
+)
+from aws_durable_execution_sdk_python_testing.checkpoint.validators.checkpoint import (
+    CheckpointValidator,
+)
+from aws_durable_execution_sdk_python_testing.exceptions import (
+    InvalidParameterValueException,
+)
+from aws_durable_execution_sdk_python_testing.observer import ExecutionNotifier
+from aws_durable_execution_sdk_python_testing.token import CheckpointToken
+
+
+if TYPE_CHECKING:
+    from aws_durable_execution_sdk_python_testing.execution import Execution
+    from aws_durable_execution_sdk_python_testing.scheduler import Scheduler
+    from aws_durable_execution_sdk_python_testing.stores.base import ExecutionStore
+
+
+class CheckpointProcessor:
+    """Handle OperationUpdate transformations and execution state updates."""
+
+    def __init__(self, store: ExecutionStore, scheduler: Scheduler):
+        self._store = store
+        self._scheduler = scheduler
+        self._notifier = ExecutionNotifier()
+        self._transformer = OperationTransformer()
+
+    def add_execution_observer(self, observer) -> None:
+        """Add observer for execution events."""
+        self._notifier.add_observer(observer)
+
+    def process_checkpoint(
+        self,
+        checkpoint_token: str,
+        updates: list[OperationUpdate],
+        client_token: str | None,  # noqa: ARG002
+    ) -> CheckpointOutput:
+        """Process checkpoint updates and return result with updated execution state."""
+        # 1. Get current execution state
+        token: CheckpointToken = CheckpointToken.from_str(checkpoint_token)
+        execution: Execution = self._store.load(token.execution_arn)
+
+        # 2. Validate checkpoint token
+        if execution.is_complete or token.token_sequence != execution.token_sequence:
+            msg: str = "Invalid checkpoint token"
+
+            raise InvalidParameterValueException(msg)
+
+        # 3. Validate all updates, state transitions are valid, sizes etc.
+        CheckpointValidator.validate_input(updates, execution)
+
+        # 4. Transform OperationUpdate -> Operation and schedule future replays
+        updated_operations, all_updates = self._transformer.process_updates(
+            updates=updates,
+            current_operations=execution.operations,
+            notifier=self._notifier,
+            execution_arn=token.execution_arn,
+        )
+
+        # 5. Generate a new checkpoint token and save updated operations
+        new_checkpoint_token = execution.get_new_checkpoint_token()
+        execution.operations = updated_operations
+        execution.updates.extend(all_updates)
+        self._store.update(execution)
+
+        # 6. Return checkpoint result
+        return CheckpointOutput(
+            checkpoint_token=new_checkpoint_token,
+            new_execution_state=CheckpointUpdatedExecutionState(
+                operations=execution.get_navigable_operations(), next_marker=None
+            ),
+        )
+
+    def get_execution_state(
+        self,
+        checkpoint_token: str,
+        next_marker: str,  # noqa: ARG002
+        max_items: int = 1000,  # noqa: ARG002
+    ) -> StateOutput:
+        """Get current execution state."""
+        token: CheckpointToken = CheckpointToken.from_str(checkpoint_token)
+        execution: Execution = self._store.load(token.execution_arn)
+
+        # TODO: paging when size or max
+        return StateOutput(
+            operations=execution.get_navigable_operations(), next_marker=None
+        )

aws_durable_execution_sdk_python_testing/checkpoint/processors/__init__.py

@@ -0,0 +1 @@
+"""Checkpoint processors module."""

aws_durable_execution_sdk_python_testing/checkpoint/processors/base.py

@@ -0,0 +1,199 @@
+"""Base processor class for operation transformations."""
+
+from __future__ import annotations
+
+import datetime
+from datetime import timedelta
+from typing import TYPE_CHECKING
+
+from aws_durable_execution_sdk_python.lambda_service import (
+    CallbackDetails,
+    ChainedInvokeDetails,
+    ContextDetails,
+    ExecutionDetails,
+    Operation,
+    OperationAction,
+    OperationStatus,
+    OperationType,
+    OperationUpdate,
+    StepDetails,
+    WaitDetails,
+)
+
+
+if TYPE_CHECKING:
+    from aws_durable_execution_sdk_python_testing.observer import ExecutionNotifier
+
+
+class OperationProcessor:
+    """Base class for processing OperationUpdate to Operation transformations."""
+
+    def process(
+        self,
+        update: OperationUpdate,
+        current_op: Operation | None,
+        notifier: ExecutionNotifier,
+        execution_arn: str,
+    ) -> Operation | None:
+        """Process an operation update and return the transformed operation."""
+        raise NotImplementedError
+
+    def _get_start_time(
+        self, current_operation: Operation | None
+    ) -> datetime.datetime | None:
+        start_time: datetime.datetime | None = (
+            current_operation.start_timestamp
+            if current_operation
+            else datetime.datetime.now(tz=datetime.UTC)
+        )
+        return start_time
+
+    def _get_end_time(
+        self, current_operation: Operation | None, status: OperationStatus
+    ) -> datetime.datetime | None:
+        """Get end timestamp for operation based on current state and status."""
+        if current_operation and current_operation.end_timestamp:
+            return current_operation.end_timestamp
+        if status in {
+            OperationStatus.SUCCEEDED,
+            OperationStatus.FAILED,
+            OperationStatus.CANCELLED,
+            OperationStatus.TIMED_OUT,
+            OperationStatus.STOPPED,
+        }:
+            return datetime.datetime.now(tz=datetime.UTC)
+        return None
+
+    def _create_execution_details(
+        self, update: OperationUpdate
+    ) -> ExecutionDetails | None:
+        """Create ExecutionDetails from OperationUpdate."""
+        return (
+            ExecutionDetails(input_payload=update.payload)
+            if update.operation_type == OperationType.EXECUTION
+            else None
+        )
+
+    def _create_context_details(self, update: OperationUpdate) -> ContextDetails | None:
+        """Create ContextDetails from OperationUpdate."""
+        return (
+            ContextDetails(
+                result=update.payload,
+                error=update.error,
+                replay_children=update.context_options.replay_children
+                if update.context_options
+                else False,
+            )
+            if update.operation_type == OperationType.CONTEXT
+            else None
+        )
+
+    def _create_step_details(
+        self,
+        update: OperationUpdate,
+        current_operation: Operation | None = None,
+    ) -> StepDetails | None:
+        """Create StepDetails from OperationUpdate.
+
+        Automatically increments attempt count for RETRY, SUCCEED, and FAIL actions.
+        """
+
+        attempt: int = 0
+        next_attempt_timestamp: datetime.datetime | None = None
+
+        if update.operation_type is OperationType.STEP:
+            if current_operation and current_operation.step_details:
+                attempt = current_operation.step_details.attempt
+                next_attempt_timestamp = (
+                    current_operation.step_details.next_attempt_timestamp
+                )
+            # Increment attempt for RETRY, SUCCEED, and FAIL actions
+            if update.action in {
+                OperationAction.RETRY,
+                OperationAction.SUCCEED,
+                OperationAction.FAIL,
+            }:
+                attempt += 1
+            return StepDetails(
+                attempt=attempt,
+                next_attempt_timestamp=next_attempt_timestamp,
+                result=update.payload,
+                error=update.error,
+            )
+
+        return None
+
+    def _create_callback_details(
+        self, update: OperationUpdate
+    ) -> CallbackDetails | None:
+        """Create CallbackDetails from OperationUpdate."""
+        return (
+            CallbackDetails(
+                callback_id="placeholder", result=update.payload, error=update.error
+            )
+            if update.operation_type == OperationType.CALLBACK
+            else None
+        )
+
+    def _create_invoke_details(
+        self, update: OperationUpdate
+    ) -> ChainedInvokeDetails | None:
+        """Create ChainedInvokeDetails from OperationUpdate."""
+        if (
+            update.operation_type == OperationType.CHAINED_INVOKE
+            and update.chained_invoke_options
+        ):
+            return ChainedInvokeDetails(result=update.payload, error=update.error)
+        return None
+
+    def _translate_update_to_operation(
+        self,
+        update: OperationUpdate,
+        current_operation: Operation | None,
+        status: OperationStatus,
+    ) -> Operation:
+        """Transform OperationUpdate to Operation, always creating new Operation."""
+        start_time: datetime.datetime | None = self._get_start_time(current_operation)
+        end_time: datetime.datetime | None = self._get_end_time(
+            current_operation, status
+        )
+
+        execution_details = self._create_execution_details(update)
+        context_details = self._create_context_details(update)
+        step_details = self._create_step_details(update, current_operation)
+        callback_details = self._create_callback_details(update)
+        invoke_details = self._create_invoke_details(update)
+        wait_details = self._create_wait_details(update, current_operation)
+
+        return Operation(
+            operation_id=update.operation_id,
+            parent_id=update.parent_id,
+            name=update.name,
+            start_timestamp=start_time,
+            end_timestamp=end_time,
+            operation_type=update.operation_type,
+            status=status,
+            sub_type=update.sub_type,
+            execution_details=execution_details,
+            context_details=context_details,
+            step_details=step_details,
+            callback_details=callback_details,
+            chained_invoke_details=invoke_details,
+            wait_details=wait_details,
+        )
+
+    def _create_wait_details(
+        self, update: OperationUpdate, current_operation: Operation | None
+    ) -> WaitDetails | None:
+        """Create WaitDetails from OperationUpdate."""
+        if update.operation_type == OperationType.WAIT and update.wait_options:
+            if current_operation and current_operation.wait_details:
+                scheduled_end_timestamp = (
+                    current_operation.wait_details.scheduled_end_timestamp
+                )
+            else:
+                scheduled_end_timestamp = datetime.datetime.now(
+                    tz=datetime.UTC
+                ) + timedelta(seconds=update.wait_options.wait_seconds)
+            return WaitDetails(scheduled_end_timestamp=scheduled_end_timestamp)
+        return None

aws_durable_execution_sdk_python_testing/checkpoint/processors/callback.py

@@ -0,0 +1,89 @@
+"""Callback operation processor for handling CALLBACK operation updates."""
+
+from __future__ import annotations
+
+import datetime
+from typing import TYPE_CHECKING
+
+from aws_durable_execution_sdk_python.lambda_service import (
+    Operation,
+    OperationAction,
+    OperationStatus,
+    OperationUpdate,
+    CallbackDetails,
+    OperationType,
+    CallbackOptions,
+)
+from aws_durable_execution_sdk_python_testing.checkpoint.processors.base import (
+    OperationProcessor,
+)
+from aws_durable_execution_sdk_python_testing.exceptions import (
+    InvalidParameterValueException,
+)
+from aws_durable_execution_sdk_python_testing.token import CallbackToken
+
+if TYPE_CHECKING:
+    from aws_durable_execution_sdk_python_testing.observer import ExecutionNotifier
+
+
+class CallbackProcessor(OperationProcessor):
+    """Processes CALLBACK operation updates with activity scheduling."""
+
+    def process(
+        self,
+        update: OperationUpdate,
+        current_op: Operation | None,
+        notifier: ExecutionNotifier,  # noqa: ARG002
+        execution_arn: str,  # noqa: ARG002
+    ) -> Operation:
+        """Process CALLBACK operation update with scheduler integration for activities."""
+        match update.action:
+            case OperationAction.START:
+                callback_token: CallbackToken = CallbackToken(
+                    execution_arn=execution_arn,
+                    operation_id=update.operation_id,
+                )
+
+                callback_id: str = callback_token.to_str()
+
+                callback_details: CallbackDetails | None = (
+                    CallbackDetails(
+                        callback_id=callback_id,
+                        result=update.payload,
+                        error=update.error,
+                    )
+                    if update.operation_type == OperationType.CALLBACK
+                    else None
+                )
+
+                status: OperationStatus = OperationStatus.STARTED
+
+                start_time: datetime.datetime | None = self._get_start_time(current_op)
+
+                end_time: datetime.datetime | None = self._get_end_time(
+                    current_op, status
+                )
+
+                operation: Operation = Operation(
+                    operation_id=update.operation_id,
+                    parent_id=update.parent_id,
+                    name=update.name,
+                    start_timestamp=start_time,
+                    end_timestamp=end_time,
+                    operation_type=update.operation_type,
+                    status=status,
+                    sub_type=update.sub_type,
+                    callback_details=callback_details,
+                )
+                callback_options: CallbackOptions | None = update.callback_options
+
+                notifier.notify_callback_created(
+                    execution_arn=execution_arn,
+                    operation_id=update.operation_id,
+                    callback_options=callback_options,
+                    callback_token=callback_token,
+                )
+                return operation
+            case _:
+                msg: str = "Invalid action for CALLBACK operation."
+                raise InvalidParameterValueException(msg)

aws_durable_execution_sdk_python_testing/checkpoint/processors/context.py

@@ -0,0 +1,59 @@
+"""Context operation processor for handling CONTEXT operation updates."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from aws_durable_execution_sdk_python.lambda_service import (
+    Operation,
+    OperationAction,
+    OperationStatus,
+    OperationUpdate,
+)
+
+from aws_durable_execution_sdk_python_testing.checkpoint.processors.base import (
+    OperationProcessor,
+)
+from aws_durable_execution_sdk_python_testing.exceptions import (
+    InvalidParameterValueException,
+)
+
+
+if TYPE_CHECKING:
+    from aws_durable_execution_sdk_python_testing.observer import ExecutionNotifier
+
+
+class ContextProcessor(OperationProcessor):
+    """Processes CONTEXT operation updates for execution context management."""
+
+    def process(
+        self,
+        update: OperationUpdate,
+        current_op: Operation | None,
+        notifier: ExecutionNotifier,  # noqa: ARG002
+        execution_arn: str,  # noqa: ARG002
+    ) -> Operation:
+        """Process CONTEXT operation update for context state transitions."""
+        match update.action:
+            case OperationAction.START:
+                # TODO: check for "Cannot start a CONTEXT operation that already exists."
+                return self._translate_update_to_operation(
+                    update=update,
+                    current_operation=current_op,
+                    status=OperationStatus.STARTED,
+                )
+            case OperationAction.SUCCEED:
+                return self._translate_update_to_operation(
+                    update=update,
+                    current_operation=current_op,
+                    status=OperationStatus.SUCCEEDED,
+                )
+            case OperationAction.FAIL:
+                return self._translate_update_to_operation(
+                    update=update,
+                    current_operation=current_op,
+                    status=OperationStatus.FAILED,
+                )
+            case _:
+                msg: str = "Invalid action for CONTEXT operation."
+                raise InvalidParameterValueException(msg)

aws_durable_execution_sdk_python_testing/checkpoint/processors/execution.py

@@ -0,0 +1,52 @@
+"""Execution operation processor for handling EXECUTION operation updates."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from aws_durable_execution_sdk_python.lambda_service import (
+    ErrorObject,
+    Operation,
+    OperationAction,
+    OperationUpdate,
+)
+
+from aws_durable_execution_sdk_python_testing.checkpoint.processors.base import (
+    OperationProcessor,
+)
+
+
+if TYPE_CHECKING:
+    from aws_durable_execution_sdk_python_testing.observer import ExecutionNotifier
+
+
+class ExecutionProcessor(OperationProcessor):
+    """Processes EXECUTION operation updates for workflow completion."""
+
+    def process(
+        self,
+        update: OperationUpdate,
+        current_op: Operation | None,  # noqa: ARG002
+        notifier: ExecutionNotifier,
+        execution_arn: str,
+    ) -> Operation | None:
+        """Process EXECUTION operation update for workflow completion/failure."""
+        match update.action:
+            case OperationAction.SUCCEED:
+                notifier.notify_completed(
+                    execution_arn=execution_arn, result=update.payload
+                )
+            case _:
+                # intentional. actual service will fail any EXECUTION update that is not SUCCEED.
+                error = (
+                    update.error
+                    if update.error
+                    else ErrorObject.from_message(
+                        "There is no error details but EXECUTION checkpoint action is not SUCCEED."
+                    )
+                )
+                # All EXECUTION failures go through normal fail path
+                # Timeout/Stop status is set by executor based on the operation that caused it
+                notifier.notify_failed(execution_arn=execution_arn, error=error)
+        # TODO: Svc doesn't actually create checkpoint for EXECUTION. might have to for localrunner though.
+        return None

aws_durable_execution_sdk_python_testing/checkpoint/processors/step.py

@@ -0,0 +1,124 @@
+"""Step operation processor for handling STEP operation updates."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING
+
+from aws_durable_execution_sdk_python.lambda_service import (
+    Operation,
+    OperationAction,
+    OperationStatus,
+    OperationUpdate,
+    StepDetails,
+)
+
+from aws_durable_execution_sdk_python_testing.checkpoint.processors.base import (
+    OperationProcessor,
+)
+from aws_durable_execution_sdk_python_testing.exceptions import (
+    InvalidParameterValueException,
+)
+
+
+if TYPE_CHECKING:
+    from aws_durable_execution_sdk_python_testing.observer import ExecutionNotifier
+
+
+class StepProcessor(OperationProcessor):
+    """Processes STEP operation updates with retry scheduling."""
+
+    def process(
+        self,
+        update: OperationUpdate,
+        current_op: Operation | None,
+        notifier: ExecutionNotifier,
+        execution_arn: str,
+    ) -> Operation:
+        """Process STEP operation update with scheduler integration for retries."""
+        match update.action:
+            case OperationAction.START:
+                return self._translate_update_to_operation(
+                    update=update,
+                    current_operation=current_op,
+                    status=OperationStatus.STARTED,
+                )
+            case OperationAction.RETRY:
+                # set Status=PENDING, next attempt time, attempt count + 1
+                delay = (
+                    update.step_options.next_attempt_delay_seconds
+                    if update.step_options
+                    else 0
+                )
+                next_attempt_time = datetime.now(UTC) + timedelta(seconds=delay)
+
+                # Build new step_details with incremented attempt
+                current_attempt = (
+                    current_op.step_details.attempt
+                    if current_op and current_op.step_details
+                    else 0
+                )
+                new_step_details = StepDetails(
+                    attempt=current_attempt + 1,
+                    next_attempt_timestamp=next_attempt_time,
+                    result=(
+                        current_op.step_details.result
+                        if current_op and current_op.step_details
+                        else None
+                    ),
+                    error=(
+                        current_op.step_details.error
+                        if current_op and current_op.step_details
+                        else None
+                    ),
+                )
+
+                # Create new operation with updated step_details
+                retry_operation = Operation(
+                    operation_id=update.operation_id,
+                    operation_type=update.operation_type,
+                    status=OperationStatus.PENDING,
+                    parent_id=update.parent_id,
+                    name=update.name,
+                    start_timestamp=(
+                        current_op.start_timestamp if current_op else datetime.now(UTC)
+                    ),
+                    end_timestamp=None,
+                    sub_type=update.sub_type,
+                    execution_details=current_op.execution_details
+                    if current_op
+                    else None,
+                    context_details=current_op.context_details if current_op else None,
+                    step_details=new_step_details,
+                    wait_details=current_op.wait_details if current_op else None,
+                    callback_details=current_op.callback_details
+                    if current_op
+                    else None,
+                    chained_invoke_details=current_op.chained_invoke_details
+                    if current_op
+                    else None,
+                )
+
+                # Schedule step retry timer to fire after delay
+                notifier.notify_step_retry_scheduled(
+                    execution_arn=execution_arn,
+                    operation_id=update.operation_id,
+                    delay=delay,
+                )
+                return retry_operation
+            case OperationAction.SUCCEED:
+                return self._translate_update_to_operation(
+                    update=update,
+                    current_operation=current_op,
+                    status=OperationStatus.SUCCEEDED,
+                )
+            case OperationAction.FAIL:
+                return self._translate_update_to_operation(
+                    update=update,
+                    current_operation=current_op,
+                    status=OperationStatus.FAILED,
+                )
+            case _:
+                msg: str = "Invalid action for STEP operation."
+
+                raise InvalidParameterValueException(msg)