Adapted README and DurableConfig

Author: maschnetwork

README.md

@@ -13,6 +13,14 @@ Build resilient, long-running AWS Lambda functions that automatically checkpoint
 - **Replay Safety** – Functions deterministically resume from checkpoints after interruptions
 - **Type Safety** – Full generic type support for step results
 
+## How It Works
+
+Your durable function extends `DurableHandler<I, O>` and implements `handleRequest(I input, DurableContext ctx)`. The `DurableContext` is your interface to durable operations:
+
+- `ctx.step()` – Execute code and checkpoint the result
+- `ctx.stepAsync()` – Start concurrent operations  
+- `ctx.wait()` – Suspend execution without compute charges
+
 ## Quick Start
 
 ### Installation
@@ -183,7 +191,7 @@ protected DurableConfig createConfiguration() {
         .build();
 
     return DurableConfig.builder()
-        .withDurableExecutionClient(new LambdaDurableFunctionsClient(lambdaClient))
+        .withLambdaClient(lambdaClient)
         .withSerDes(new MyCustomSerDes())           // Custom serialization
         .withExecutorService(Executors.newFixedThreadPool(10))  // Custom thread pool
         .build();
@@ -192,7 +200,7 @@ protected DurableConfig createConfiguration() {
 
 | Option | Description | Default |
 |--------|-------------|---------|
-| `withDurableExecutionClient()` | Client for checkpoint operations | Auto-configured Lambda client |
+| `withLambdaClient()` | Custom AWS Lambda client | Auto-configured Lambda client |
 | `withSerDes()` | Serializer for step results | Jackson with default settings |
 | `withExecutorService()` | Thread pool for async step execution | Cached daemon thread pool |
 
@@ -253,6 +261,15 @@ void testOrderProcessing() {
 }
 ```
 
+You can also pass a lambda directly instead of a handler instance:
+
+```java
+var runner = LocalDurableTestRunner.create(Order.class, (order, ctx) -> {
+    var result = ctx.step("process", String.class, () -> "done");
+    return new OrderResult(order.getId(), result);
+});
+```
+
 ### Inspecting Operations
 
 ```java
@@ -304,38 +321,7 @@ assertEquals(ExecutionStatus.SUCCEEDED, result.getStatus());
 
 ## Deployment
 
-The [examples](./examples) module includes a complete SAM template and deployment instructions.
-
-```bash
-cd examples
-mvn clean package
-sam build
-sam deploy --guided
-```
-
-Key deployment requirements:
-- `DurableConfig` in SAM template with `ExecutionTimeout` and `RetentionPeriodInDays`
-- IAM permissions for `lambda:CheckpointDurableExecutions` and `lambda:GetDurableExecutionState`
-
-See [examples/template.yaml](./examples/template.yaml) and [examples/README.md](./examples/README.md) for details.
-
-## Examples
-
-| Example | Description |
-|---------|-------------|
-| [SimpleStepExample](./examples/src/main/java/com/amazonaws/lambda/durable/examples/SimpleStepExample.java) | Basic sequential steps |
-| [WaitExample](./examples/src/main/java/com/amazonaws/lambda/durable/examples/WaitExample.java) | Using wait operations |
-| [RetryExample](./examples/src/main/java/com/amazonaws/lambda/durable/examples/RetryExample.java) | Configuring retry strategies |
-| [GenericTypesExample](./examples/src/main/java/com/amazonaws/lambda/durable/examples/GenericTypesExample.java) | Working with generic types |
-| [CustomConfigExample](./examples/src/main/java/com/amazonaws/lambda/durable/examples/CustomConfigExample.java) | Custom Lambda client and SerDes |
-| [WaitAtLeastExample](./examples/src/main/java/com/amazonaws/lambda/durable/examples/WaitAtLeastExample.java) | Concurrent stepAsync() with wait() |
-| [RetryInProcessExample](./examples/src/main/java/com/amazonaws/lambda/durable/examples/RetryInProcessExample.java) | In-process retry with concurrent operations |
-| [WaitAtLeastInProcessExample](./examples/src/main/java/com/amazonaws/lambda/durable/examples/WaitAtLeastInProcessExample.java) | Wait completes before async step (no suspension) |
-
-## Requirements
-
-- Java 17+
-- AWS SDK for Java v2
+See [examples/README.md](./examples/README.md) for complete instructions on local testing, deployment, invoking functions, and running cloud integration tests.
 
 ## Documentation
 

examples/README.md

@@ -1,87 +1,94 @@
 # AWS Lambda Durable Execution SDK Examples
 
-This module contains example applications demonstrating how to use the AWS Lambda Durable Execution SDK for Java.
+Example applications demonstrating the AWS Lambda Durable Execution SDK for Java.
 
-# Running Examples with JUnit Tests
+## Prerequisites
 
-The examples demonstrate both local and cloud testing approaches using the SDK's testing utilities:
+- Java 17+
+- Maven 3.8+
+- AWS SAM CLI (for deployment)
+- Docker (for SAM build)
+- AWS credentials configured
 
-## Local Testing (Fast, No AWS Required)
+## Local Testing
 
-Use `LocalDurableTestRunner` for fast, in-memory testing without deploying to AWS Lambda:
+Run examples locally without AWS using `LocalDurableTestRunner`:
 
 ```bash
-# Run all example tests
+# First, build and install the SDK to local Maven repo (from project root)
+mvn clean install -DskipTests
+
+cd examples
+
+# Run all tests
 mvn test
 
 # Run specific test
 mvn test -Dtest=SimpleStepExampleTest
 ```
 
-The local runner skips actual wait times and runs entirely in-memory, making tests fast and suitable for CI/CD pipelines.
+The local runner executes in-memory and skips wait durations—ideal for fast iteration and CI/CD.
 
-## Cloud Testing (End-to-End)
+## Deploy to AWS
 
-Use `CloudDurableTestRunner` for end-to-end testing against deployed Lambda functions:
+```bash
+cd examples
+mvn clean package
+sam build
+sam deploy --guided
+```
 
-```java
-var runner = CloudDurableTestRunner.create(
-    "arn:aws:lambda:us-east-1:123456789012:function:MyFunction",
-    MyInput.class,
-    MyOutput.class);
+On first deploy, SAM will prompt for stack name and region. Subsequent deploys use saved config:
 
-var result = runner.run(new MyInput("test-data"));
+```bash
+sam deploy
 ```
 
-This approach tests the actual deployed function, including all AWS integrations and durable execution behavior.
+The SAM template configures:
+- `DurableConfig` with `ExecutionTimeout` and `RetentionPeriodInDays`
+- IAM permissions for `lambda:CheckpointDurableExecutions` and `lambda:GetDurableExecutionState`
 
-# Running Examples with AWS SAM locally
+## Invoke Deployed Functions
 
-**Build the project:**
-   ```bash
-   mvn clean package
-   ```
+```bash
+sam remote invoke SimpleStepExampleFunction \
+  --event '{"name":"World"}' \
+  --stack-name durable-sdk-examples
+```
 
-### Option 1: Local Lambda Endpoint
+## Cloud Integration Tests
 
-Start a local Lambda endpoint:
+Run tests against deployed functions using `CloudDurableTestRunner`:
 
 ```bash
-sam local start-lambda
+cd examples
+mvn test -Dtest=CloudBasedIntegrationTest -Dtest.cloud.enabled=true
 ```
 
-In another terminal, invoke the function:
+The tests auto-detect your AWS account and region from credentials. Override if needed:
 
 ```bash
-# Invoke SimpleStepExample
-aws lambda invoke \
-  --function-name SimpleStepExampleFunction \
-  --endpoint-url http://127.0.0.1:3001 \
-  --payload '{"name":"Alice"}' \
-  --cli-binary-format raw-in-base64-out \
-  response.json
-
-# Invoke WaitExample
-aws lambda invoke \
-  --function-name WaitExampleFunction \
-  --endpoint-url http://127.0.0.1:3001 \
-  --payload '{"name":"Bob"}' \
-  --cli-binary-format raw-in-base64-out \
-  response.json
+mvn test -Dtest=CloudBasedIntegrationTest \
+  -Dtest.cloud.enabled=true \
+  -Dtest.aws.account=123456789012 \
+  -Dtest.aws.region=us-east-1
 ```
 
-### Option 2: Direct Invocation
+## Examples
 
-Invoke the function directly:
+| Example | Description |
+|---------|-------------|
+| [SimpleStepExample](src/main/java/com/amazonaws/lambda/durable/examples/SimpleStepExample.java) | Basic sequential steps |
+| [WaitExample](src/main/java/com/amazonaws/lambda/durable/examples/WaitExample.java) | Suspend execution with `wait()` |
+| [RetryExample](src/main/java/com/amazonaws/lambda/durable/examples/RetryExample.java) | Configuring retry strategies |
+| [GenericTypesExample](src/main/java/com/amazonaws/lambda/durable/examples/GenericTypesExample.java) | Working with `List<T>` and `Map<K,V>` |
+| [CustomConfigExample](src/main/java/com/amazonaws/lambda/durable/examples/CustomConfigExample.java) | Custom Lambda client and SerDes |
+| [WaitAtLeastExample](src/main/java/com/amazonaws/lambda/durable/examples/WaitAtLeastExample.java) | Concurrent `stepAsync()` with `wait()` |
+| [RetryInProcessExample](src/main/java/com/amazonaws/lambda/durable/examples/RetryInProcessExample.java) | In-process retry with concurrent operations |
+| [WaitAtLeastInProcessExample](src/main/java/com/amazonaws/lambda/durable/examples/WaitAtLeastInProcessExample.java) | Wait completes before async step (no suspension) |
 
-```bash
-sam local invoke SimpleStepExampleFunction \
-  --event event.json
-```
+## Cleanup
 
-Create `event.json`:
-```json
-{
-  "name": "Alice"
-}
+```bash
+sam delete
 ```

sdk/src/main/java/com/amazonaws/lambda/durable/DurableConfig.java

@@ -19,7 +19,7 @@
 
 /**
  * Configuration for DurableHandler initialization. This class provides a builder pattern for configuring SDK components
- * including DurableExecutionClient, SerDes, and ExecutorService.
+ * including LambdaClient, SerDes, and ExecutorService.
  *
  * <p>Configuration is initialized once during Lambda cold start and remains immutable throughout the execution
  * lifecycle.
@@ -36,32 +36,18 @@
  * }
  * }</pre>
  *
- * <p>Example usage with custom Lambda client configuration using {@link LambdaDurableFunctionsClient}:
+ * <p>Example usage with custom Lambda client:
  *
  * <pre>{@code
  * @Override
  * protected DurableConfig createConfiguration() {
- *     // Create a custom Lambda client with specific configuration
  *     LambdaClient lambdaClient = LambdaClient.builder()
  *         .region(Region.US_WEST_2)
  *         .credentialsProvider(ProfileCredentialsProvider.create("my-profile"))
- *         .httpClient(ApacheHttpClient.builder()
- *             .connectionTimeout(Duration.ofSeconds(30))
- *             .socketTimeout(Duration.ofSeconds(60))
- *             .build())
- *         .overrideConfiguration(ClientOverrideConfiguration.builder()
- *             .retryPolicy(RetryPolicy.builder()
- *                 .numRetries(5)
- *                 .build())
- *             .build())
  *         .build();
  *
- *     // Wrap the Lambda client with LambdaDurableFunctionsClient
- *     DurableExecutionClient durableClient = new LambdaDurableFunctionsClient(lambdaClient);
- *
- *     // Configure DurableConfig with the custom client
  *     return DurableConfig.builder()
- *         .withDurableExecutionClient(durableClient)
+ *         .withLambdaClient(lambdaClient)
  *         .build();
  * }
  * }</pre>
@@ -197,8 +183,37 @@ public static final class Builder {
         private Builder() {}
 
         /**
-         * Sets a custom DurableExecutionClient. This is useful for testing with mock clients or using custom backend
-         * implementations.
+         * Sets a custom LambdaClient for production use. Use this method to customize the AWS SDK client
+         * with specific regions, credentials, timeouts, or retry policies.
+         *
+         * <p>Example:
+         * <pre>{@code
+         * LambdaClient lambdaClient = LambdaClient.builder()
+         *     .region(Region.US_WEST_2)
+         *     .credentialsProvider(ProfileCredentialsProvider.create("my-profile"))
+         *     .build();
+         *
+         * DurableConfig.builder()
+         *     .withLambdaClient(lambdaClient)
+         *     .build();
+         * }</pre>
+         *
+         * @param lambdaClient Custom LambdaClient instance
+         * @return This builder
+         * @throws NullPointerException if lambdaClient is null
+         */
+        public Builder withLambdaClient(LambdaClient lambdaClient) {
+            Objects.requireNonNull(lambdaClient, "LambdaClient cannot be null");
+            this.durableExecutionClient = new LambdaDurableFunctionsClient(lambdaClient);
+            return this;
+        }
+
+        /**
+         * Sets a custom DurableExecutionClient.
+         *
+         * <p><b>Note:</b> This method is primarily intended for testing with mock clients
+         * (e.g., {@code LocalMemoryExecutionClient}). For production use with a custom AWS SDK client,
+         * prefer {@link #withLambdaClient(LambdaClient)}.
          *
          * @param durableExecutionClient Custom DurableExecutionClient instance
          * @return This builder