aws-durable-execution-sdk-python-testing 1.2.1__tar.gz → 1.3.0__tar.gz

{aws_durable_execution_sdk_python_testing-1.2.1 → aws_durable_execution_sdk_python_testing-1.3.0}/.gitignore

@@ -9,11 +9,13 @@ __pycache__/
 *$py.class
 *.egg-info/
 
+*.coverage
 /.coverage
 /.coverage.*
 /.cache
 /.pytest_cache
 /.mypy_cache
+/.vscode
 
 /doc/_apidoc/
 /build
@@ -25,13 +27,13 @@ __pycache__/
 
 dist/
 
-.vscode/
-.kiro/
 .idea
-.env
-.env*
 
-.durable_executions
+.kiro/
 
-durable-executions.db*
-.coverage
+**/build/
+**/*.zip
+.aws-sam/
+**/template.generated.json
+
+.env

{aws_durable_execution_sdk_python_testing-1.2.1 → aws_durable_execution_sdk_python_testing-1.3.0}/PKG-INFO

@@ -1,14 +1,12 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: aws-durable-execution-sdk-python-testing
-Version: 1.2.1
+Version: 1.3.0
 Summary: AWS Durable Execution Testing SDK for Python
 Project-URL: Documentation, https://github.com/aws/aws-durable-execution-sdk-python-testing#readme
 Project-URL: Issues, https://github.com/aws/aws-durable-execution-sdk-python-testing/issues
 Project-URL: Source, https://github.com/aws/aws-durable-execution-sdk-python-testing
 Author-email: AWS durable-execution-dev <durable-execution-dev@amazon.com>
 License-Expression: Apache-2.0
-License-File: LICENSE
-License-File: NOTICE
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3.11
@@ -18,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Requires-Python: >=3.11
-Requires-Dist: aws-durable-execution-sdk-python>=1.0.0
+Requires-Dist: aws-durable-execution-sdk-python>=2.1.0
 Requires-Dist: boto3>=1.42.1
 Description-Content-Type: text/markdown
 
@@ -36,6 +34,7 @@ Description-Content-Type: text/markdown
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
+- [Testing functions that invoke other functions](#testing-functions-that-invoke-other-functions)
 - [Architecture](#architecture)
 - [Documentation](#documentation)
 - [Developer Guide](#developers)
@@ -135,67 +134,60 @@ def test_my_durable_functions():
     three_result: StepOperation = result.get_step("three")
     assert three_result.result == '"5 6"'
 ```
-## Architecture
-![Durable Functions Python Test Framework Architecture](/assets/dar-python-test-framework-architecture.svg)
-
-## Event Flow
-![Event Flow Sequence Diagram](/assets/dar-python-test-framework-event-flow.svg)
-
-1. **DurableTestRunner** starts execution via **Executor**
-2. **Executor** creates **Execution** and schedules initial invocation
-3. During execution, checkpoints are processed by **CheckpointProcessor**
-4. **Individual Processors** transform operation updates and may trigger events
-5. **ExecutionNotifier** broadcasts events to **Executor** (observer)
-6. **Executor** updates **Execution** state based on events
-7. **Execution** completion triggers final event notifications
-8. **DurableTestRunner** run() blocks until it receives completion event, and then returns `DurableFunctionTestResult`.
+## Testing functions that invoke other functions
 
-## Major Components
+A durable function can call another function with `context.invoke`. The
+runner needs to know each target's kind: a durable target runs as a
+child durable execution with its own history, while a plain (non-durable)
+target is one invocation whose return value is the result. An unknown
+target fails the operation with `ResourceNotFoundException`.
 
-### Core Execution Flow
-- **DurableTestRunner** - Main entry point that orchestrates test execution
-- **Executor** - Manages execution lifecycle. Mutates Execution.
-- **Execution** - Represents the state and operations of a single durable execution
+### In-process runner
 
-### Service Client Integration
-- **InMemoryServiceClient** - Replaces AWS Lambda service client for local testing. Injected into SDK via `DurableExecutionInvocationInputWithClient`
+Register each target with the runner. `register_durable_function` marks a
+durable target, and takes its execution timeout and retention;
+`register_function` marks a plain one. The runner has one handler per
+registered name, not versions: an invoke of `child:prod` runs the handler
+registered as `child:prod` if there is one, otherwise the one registered
+as `child`.
 
-### Checkpoint Processing Pipeline
-- **CheckpointProcessor** - Orchestrates operation transformations and validation
-- **Individual Validators** - Validate operation updates and state transitions
-- **Individual Processors** - Transform operation updates into operations (step, wait, callback, context, execution)
-
-### Execution status changes (Observer Pattern)
-- **ExecutionNotifier** - Notifies observers of execution events
-- **ExecutionObserver** - Interface for receiving execution lifecycle events
-- **Executor** implements `ExecutionObserver` to handle completion events
-
-## Component Relationships
+```python
+from aws_durable_execution_sdk_python.context import DurableContext
+from aws_durable_execution_sdk_python.execution import durable_execution
+from aws_durable_execution_sdk_python_testing.runner import DurableFunctionTestRunner
 
-### 1. DurableTestRunner → Executor → Execution
-- **DurableTestRunner** serves as the main API entry point and sets up all components
-- **Executor** manages the execution lifecycle, handling invocations and state transitions
-- **Execution** maintains the state of operations and completion status
+@durable_execution
+def process_payment(event: dict, context: DurableContext) -> dict:
+    return {"charged": event["amount"]}
 
-### 2. Service Client Injection
-- **DurableTestRunner** creates **InMemoryServiceClient** with **CheckpointProcessor**
-- **InProcessInvoker** injects the service client into SDK via `DurableExecutionInvocationInputWithClient`
-- When durable functions call checkpoint operations, they're intercepted by **InMemoryServiceClient**
-- **InMemoryServiceClient** delegates to **CheckpointProcessor** for local processing
+def lookup_price(event: dict, context) -> dict:
+    return {"price": 25}
 
-### 3. CheckpointProcessor → Individual Validators → Individual Processors
-- **CheckpointProcessor** orchestrates the checkpoint processing pipeline
-- **Individual Validators** (CheckpointValidator, TransitionsValidator, and operation-specific validators) ensure operation updates are valid
-- **Individual Processors** (StepProcessor, WaitProcessor, etc.) transform `OperationUpdate` into `Operation`
+@durable_execution
+def place_order(event: dict, context: DurableContext) -> dict:
+    price = context.invoke("lookup-price", {"sku": event["sku"]}, name="price")
+    payment = context.invoke(
+        "process-payment", {"amount": price["price"]}, name="payment"
+    )
+    return {"sku": event["sku"], "charged": payment["charged"]}
+
+def test_place_order_invokes_both_functions():
+    with DurableFunctionTestRunner(handler=place_order) as runner:
+        runner.register_durable_function(
+            "process-payment", process_payment, execution_timeout=60
+        )
+        runner.register_function("lookup-price", lookup_price)
+        result = runner.run(input='{"sku": "book-1"}')
+
+    assert result.result == '{"sku": "book-1", "charged": 25}'
+    assert result.get_invoke("payment").status.value == "SUCCEEDED"
+```
 
-### 4. Observer Pattern Flow
-The observer pattern enables loose coupling between checkpoint processing and execution management:
+## Architecture
 
-1. **CheckpointProcessor** processes operation updates
-2. **Individual Processors** detect state changes (completion, failures, timer scheduling)
-3. **ExecutionNotifier** broadcasts events to registered observers
-4. **Executor** (as ExecutionObserver) receives notifications and updates **Execution** state
-5. **Execution** complete_* methods finalize the execution state
+See [docs/architecture.md](docs/architecture.md) for framework
+internals. It covers the components, the worker model, the checkpoint
+flow, pagination, and a map of the code.
 
 
 ## Documentation
@@ -220,4 +212,4 @@ tldr; use `hatch` and it will manage virtual envs and dependencies for you, so y
 
 ## License
 
-This project is licensed under the [Apache-2.0 License](LICENSE).
+This project is licensed under the [Apache-2.0 License](https://github.com/aws/aws-durable-execution-sdk-python/blob/main/LICENSE).

{aws_durable_execution_sdk_python_testing-1.2.1 → aws_durable_execution_sdk_python_testing-1.3.0}/README.md

@@ -12,6 +12,7 @@
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
+- [Testing functions that invoke other functions](#testing-functions-that-invoke-other-functions)
 - [Architecture](#architecture)
 - [Documentation](#documentation)
 - [Developer Guide](#developers)
@@ -111,67 +112,60 @@ def test_my_durable_functions():
     three_result: StepOperation = result.get_step("three")
     assert three_result.result == '"5 6"'
 ```
-## Architecture
-![Durable Functions Python Test Framework Architecture](/assets/dar-python-test-framework-architecture.svg)
-
-## Event Flow
-![Event Flow Sequence Diagram](/assets/dar-python-test-framework-event-flow.svg)
-
-1. **DurableTestRunner** starts execution via **Executor**
-2. **Executor** creates **Execution** and schedules initial invocation
-3. During execution, checkpoints are processed by **CheckpointProcessor**
-4. **Individual Processors** transform operation updates and may trigger events
-5. **ExecutionNotifier** broadcasts events to **Executor** (observer)
-6. **Executor** updates **Execution** state based on events
-7. **Execution** completion triggers final event notifications
-8. **DurableTestRunner** run() blocks until it receives completion event, and then returns `DurableFunctionTestResult`.
+## Testing functions that invoke other functions
 
-## Major Components
+A durable function can call another function with `context.invoke`. The
+runner needs to know each target's kind: a durable target runs as a
+child durable execution with its own history, while a plain (non-durable)
+target is one invocation whose return value is the result. An unknown
+target fails the operation with `ResourceNotFoundException`.
 
-### Core Execution Flow
-- **DurableTestRunner** - Main entry point that orchestrates test execution
-- **Executor** - Manages execution lifecycle. Mutates Execution.
-- **Execution** - Represents the state and operations of a single durable execution
+### In-process runner
 
-### Service Client Integration
-- **InMemoryServiceClient** - Replaces AWS Lambda service client for local testing. Injected into SDK via `DurableExecutionInvocationInputWithClient`
+Register each target with the runner. `register_durable_function` marks a
+durable target, and takes its execution timeout and retention;
+`register_function` marks a plain one. The runner has one handler per
+registered name, not versions: an invoke of `child:prod` runs the handler
+registered as `child:prod` if there is one, otherwise the one registered
+as `child`.
 
-### Checkpoint Processing Pipeline
-- **CheckpointProcessor** - Orchestrates operation transformations and validation
-- **Individual Validators** - Validate operation updates and state transitions
-- **Individual Processors** - Transform operation updates into operations (step, wait, callback, context, execution)
-
-### Execution status changes (Observer Pattern)
-- **ExecutionNotifier** - Notifies observers of execution events
-- **ExecutionObserver** - Interface for receiving execution lifecycle events
-- **Executor** implements `ExecutionObserver` to handle completion events
-
-## Component Relationships
+```python
+from aws_durable_execution_sdk_python.context import DurableContext
+from aws_durable_execution_sdk_python.execution import durable_execution
+from aws_durable_execution_sdk_python_testing.runner import DurableFunctionTestRunner
 
-### 1. DurableTestRunner → Executor → Execution
-- **DurableTestRunner** serves as the main API entry point and sets up all components
-- **Executor** manages the execution lifecycle, handling invocations and state transitions
-- **Execution** maintains the state of operations and completion status
+@durable_execution
+def process_payment(event: dict, context: DurableContext) -> dict:
+    return {"charged": event["amount"]}
 
-### 2. Service Client Injection
-- **DurableTestRunner** creates **InMemoryServiceClient** with **CheckpointProcessor**
-- **InProcessInvoker** injects the service client into SDK via `DurableExecutionInvocationInputWithClient`
-- When durable functions call checkpoint operations, they're intercepted by **InMemoryServiceClient**
-- **InMemoryServiceClient** delegates to **CheckpointProcessor** for local processing
+def lookup_price(event: dict, context) -> dict:
+    return {"price": 25}
 
-### 3. CheckpointProcessor → Individual Validators → Individual Processors
-- **CheckpointProcessor** orchestrates the checkpoint processing pipeline
-- **Individual Validators** (CheckpointValidator, TransitionsValidator, and operation-specific validators) ensure operation updates are valid
-- **Individual Processors** (StepProcessor, WaitProcessor, etc.) transform `OperationUpdate` into `Operation`
+@durable_execution
+def place_order(event: dict, context: DurableContext) -> dict:
+    price = context.invoke("lookup-price", {"sku": event["sku"]}, name="price")
+    payment = context.invoke(
+        "process-payment", {"amount": price["price"]}, name="payment"
+    )
+    return {"sku": event["sku"], "charged": payment["charged"]}
+
+def test_place_order_invokes_both_functions():
+    with DurableFunctionTestRunner(handler=place_order) as runner:
+        runner.register_durable_function(
+            "process-payment", process_payment, execution_timeout=60
+        )
+        runner.register_function("lookup-price", lookup_price)
+        result = runner.run(input='{"sku": "book-1"}')
+
+    assert result.result == '{"sku": "book-1", "charged": 25}'
+    assert result.get_invoke("payment").status.value == "SUCCEEDED"
+```
 
-### 4. Observer Pattern Flow
-The observer pattern enables loose coupling between checkpoint processing and execution management:
+## Architecture
 
-1. **CheckpointProcessor** processes operation updates
-2. **Individual Processors** detect state changes (completion, failures, timer scheduling)
-3. **ExecutionNotifier** broadcasts events to registered observers
-4. **Executor** (as ExecutionObserver) receives notifications and updates **Execution** state
-5. **Execution** complete_* methods finalize the execution state
+See [docs/architecture.md](docs/architecture.md) for framework
+internals. It covers the components, the worker model, the checkpoint
+flow, pagination, and a map of the code.
 
 
 ## Documentation
@@ -196,4 +190,4 @@ tldr; use `hatch` and it will manage virtual envs and dependencies for you, so y
 
 ## License
 
-This project is licensed under the [Apache-2.0 License](LICENSE).
+This project is licensed under the [Apache-2.0 License](https://github.com/aws/aws-durable-execution-sdk-python/blob/main/LICENSE).

{aws_durable_execution_sdk_python_testing-1.2.1 → aws_durable_execution_sdk_python_testing-1.3.0}/aws_durable_execution_sdk_python_testing/__about__.py

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

aws_durable_execution_sdk_python_testing-1.3.0/aws_durable_execution_sdk_python_testing/checkpoint/core.py

@@ -0,0 +1,171 @@
+"""The shared checkpoint write-transaction.
+
+Both checkpoint entry points apply a batch of updates and compute the
+delta of operations the handler has not yet seen. :class:`CheckpointCore`
+holds that common logic so the two callers differ only in their gate,
+locking, and response type.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, NamedTuple
+
+from aws_durable_execution_sdk_python_testing.checkpoint.validators.checkpoint import (
+    CheckpointValidator,
+)
+from aws_durable_execution_sdk_python_testing.execution import (
+    CheckpointIdempotencyRecord,
+    OperationPaginatorState,
+)
+from aws_durable_execution_sdk_python_testing.token import CheckpointToken
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+    from aws_durable_execution_sdk_python.lambda_service import (
+        Operation,
+        OperationUpdate,
+    )
+
+    from aws_durable_execution_sdk_python_testing.checkpoint.effects import (
+        CheckpointEffect,
+    )
+    from aws_durable_execution_sdk_python_testing.checkpoint.transformer import (
+        CheckpointRequestDispatcher,
+    )
+    from aws_durable_execution_sdk_python_testing.execution import Execution
+
+
+class CheckpointResult(NamedTuple):
+    """Outcome of applying a checkpoint: the new token, the operations to
+    return to the handler this round, and the lifecycle effects raised.
+
+    ``checkpoint_token`` is None when the execution is paused and the token
+    is withheld, telling the SDK this invocation may checkpoint no further.
+    """
+
+    checkpoint_token: str | None
+    operations: list[Operation]
+    effects: list[CheckpointEffect]
+
+
+class CheckpointCore:
+    """The checkpoint write-transaction shared by both entry points."""
+
+    @staticmethod
+    def match_cached(
+        execution: Execution,
+        checkpoint_token: str,
+        client_token: str | None,
+    ) -> CheckpointIdempotencyRecord | None:
+        """Return the cached idempotency record when the incoming
+        ``(client_token, checkpoint_token)`` matches the last checkpoint,
+        else ``None``.
+
+        A missing ``client_token`` cannot replay: idempotency requires an
+        explicit client identifier. The caller builds its own response
+        type from the returned record.
+        """
+        if not client_token:
+            return None
+        cached: CheckpointIdempotencyRecord | None = execution.last_checkpoint
+        if cached is None:
+            return None
+        if (
+            cached.client_token != client_token
+            or cached.inbound_checkpoint_token != checkpoint_token
+        ):
+            return None
+        return cached
+
+    @staticmethod
+    def apply(
+        execution: Execution,
+        checkpoint_token: str,
+        updates: list[OperationUpdate],
+        client_token: str | None,
+        dispatcher: CheckpointRequestDispatcher,
+        now: datetime,
+    ) -> CheckpointResult:
+        """Apply ``updates`` to ``execution`` and compute the response delta.
+
+        Advances ``token_sequence`` exactly once, returns the full set of
+        operations the handler has not yet seen unless paused, advances
+        ``handler_seen_seq`` only for returned operations, and records an
+        idempotency entry for a byte-identical replay of a retried call
+        only when returning a checkpoint token.
+
+        The caller is responsible for the invocation gate, locking,
+        persistence, and applying the returned effects.
+
+        ``now`` is the checkpoint's single source of "now", resolved from
+        the execution's clock, so all timestamps stamped by this apply
+        advance with modeled time under a skip clock.
+
+        Before computing the delta, completes every wait and step retry
+        whose scheduled moment has passed, so those transitions are
+        delivered in this response and a suspended branch resumes within
+        the running invocation instead of waiting for the next one.
+        """
+        effects: list[CheckpointEffect] = []
+        if updates:
+            CheckpointValidator.validate_input(updates, execution)
+            effects = dispatcher.apply_updates(
+                execution=execution,
+                updates=updates,
+                client_token=client_token,
+                touch=execution.touch_operation,
+                now=now,
+            )
+
+        new_token_sequence: int = execution.advance_token_sequence()
+
+        # Pick up scheduler-due completions before pinning the paginator:
+        # each transition touches its operation, so it lands in this
+        # response's unseen delta and the handler sees it immediately.
+        execution.complete_due_operations(now)
+
+        paginator: OperationPaginatorState = OperationPaginatorState.pin(execution)
+        # The checkpoint response returns the full unseen delta in a single
+        # response. Advance handler_seen_seq to cover every returned op so
+        # the next delta carries only operations touched after this response.
+        # Paused checkpoints persist updates without delivering any state.
+        response_ops: list[Operation] = (
+            [] if execution.is_paused else paginator.unseen_operations()
+        )
+        if response_ops:
+            highest_delivered_seq: int = max(
+                execution.operation_last_touched_seq[op.operation_id]
+                for op in response_ops
+            )
+            paginator.advance_handler_seen(highest_delivered_seq)
+
+        new_token: str = CheckpointToken(
+            execution_arn=execution.durable_execution_arn,
+            token_sequence=new_token_sequence,
+            invocation_id=execution.current_invocation_id,
+        ).to_str()
+
+        # A paused execution registers this checkpoint's updates but withholds
+        # the token: a response without one tells the SDK this invocation may
+        # checkpoint no further, so it reports PENDING at its next checkpoint
+        # rather than continuing, and owes a re-invoke once resumed.
+        #
+        # Checkpoints that were interrupted by a pause are not added to the
+        # idempotency record. A retry of this checkpoint will fail rather than be
+        # answered again.
+
+        outbound_token: str | None = new_token
+        if execution.is_paused:
+            outbound_token = None
+            execution.defer_invocation()
+        else:
+            execution.last_checkpoint = CheckpointIdempotencyRecord(
+                client_token=client_token or "",
+                inbound_checkpoint_token=checkpoint_token,
+                outbound_checkpoint_token=outbound_token,
+                operations=list(response_ops),
+                next_marker=None,
+            )
+
+        return CheckpointResult(outbound_token, response_ops, effects)

aws_durable_execution_sdk_python_testing-1.3.0/aws_durable_execution_sdk_python_testing/checkpoint/effects.py

@@ -0,0 +1,61 @@
+"""Lifecycle effects produced by applying checkpoint updates.
+
+Applying a batch of operation updates can imply actions on the execution
+beyond the state change itself: the execution completed, it failed, or a
+callback was created and now needs a timeout. These are returned as data
+so the caller can act on them after the write finishes, rather than
+triggering them in the middle of it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from aws_durable_execution_sdk_python.lambda_service import (
+        CallbackOptions,
+        ErrorObject,
+    )
+
+    from aws_durable_execution_sdk_python_testing.token import CallbackToken
+
+
+@dataclass(frozen=True)
+class Completed:
+    """The execution completed successfully with ``result``."""
+
+    execution_arn: str
+    result: str | None = None
+
+
+@dataclass(frozen=True)
+class Failed:
+    """The execution failed with ``error``."""
+
+    execution_arn: str
+    error: ErrorObject | None
+
+
+@dataclass(frozen=True)
+class CallbackCreated:
+    """A callback was created and its timeout (if any) must be scheduled."""
+
+    execution_arn: str
+    operation_id: str
+    callback_options: CallbackOptions | None
+    callback_token: CallbackToken
+
+
+@dataclass(frozen=True)
+class ChainedInvokeStarted:
+    """A chained invoke was accepted and its target must be dispatched."""
+
+    execution_arn: str
+    operation_id: str
+    function_name: str
+    tenant_id: str | None
+    payload: str | None
+
+
+CheckpointEffect = Completed | Failed | CallbackCreated | ChainedInvokeStarted