Merge branch 'pagejep/generic-serdes' into 'main'

feat(serdes): Add support for Generic types to SerDes interface and default Jackson implementation.

See merge request mxschell/aws-durable-execution-sdk-java!12

Author: phipag

.gitignore

@@ -38,4 +38,5 @@ Thumbs.db
 
 # SAM
 .aws-sam/
+samconfig.toml
 samconfig.toml.bak

examples/README.md

@@ -4,7 +4,11 @@ This module contains example applications demonstrating how to use the AWS Lambd
 
 # Running Examples with JUnit Tests
 
-The examples use the SDK's `LocalDurableTestRunner` to run without deploying to AWS Lambda:
+The examples demonstrate both local and cloud testing approaches using the SDK's testing utilities:
+
+## Local Testing (Fast, No AWS Required)
+
+Use `LocalDurableTestRunner` for fast, in-memory testing without deploying to AWS Lambda:
 
 ```bash
 # Run all example tests
@@ -14,6 +18,23 @@ mvn 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.
+
+## Cloud Testing (End-to-End)
+
+Use `CloudDurableTestRunner` for end-to-end testing against deployed Lambda functions:
+
+```java
+var runner = CloudDurableTestRunner.create(
+    "arn:aws:lambda:us-east-1:123456789012:function:MyFunction",
+    MyInput.class,
+    MyOutput.class);
+
+var result = runner.run(new MyInput("test-data"));
+```
+
+This approach tests the actual deployed function, including all AWS integrations and durable execution behavior.
+
 # Running Examples with AWS SAM locally
 
 **Build the project:**
@@ -63,4 +84,4 @@ Create `event.json`:
 {
   "name": "Alice"
 }
-```
+```

examples/samconfig.toml

@@ -0,0 +1,93 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package com.amazonaws.lambda.durable.examples;
+
+import com.amazonaws.lambda.durable.DurableContext;
+import com.amazonaws.lambda.durable.DurableHandler;
+import com.amazonaws.lambda.durable.StepConfig;
+import com.amazonaws.lambda.durable.TypeToken;
+import com.amazonaws.lambda.durable.retry.RetryStrategies;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * Example demonstrating TypeToken support for complex generic types.
+ *
+ * <p>This example shows how to use TypeToken to work with generic types like List<String>, Map<String, Object>, and
+ * nested generics that cannot be represented by simple Class objects.
+ */
+public class GenericTypesExample extends DurableHandler<GenericTypesExample.Input, GenericTypesExample.Output> {
+
+    private static final Logger logger = LoggerFactory.getLogger(GenericTypesExample.class);
+
+    public static class Input {
+        public String userId;
+
+        public Input() {}
+
+        public Input(String userId) {
+            this.userId = userId;
+        }
+    }
+
+    public static class Output {
+        public List<String> items;
+        public Map<String, Integer> counts;
+        public Map<String, List<String>> categories;
+
+        public Output() {}
+
+        public Output(List<String> items, Map<String, Integer> counts, Map<String, List<String>> categories) {
+            this.items = items;
+            this.counts = counts;
+            this.categories = categories;
+        }
+    }
+
+    @Override
+    protected Output handleRequest(Input input, DurableContext context) {
+        logger.info("Starting generic types example for user: {}", input.userId);
+
+        // Step 1: Fetch a list of items (List<String>)
+        List<String> items = context.step("fetch-items", new TypeToken<List<String>>() {}, () -> {
+            logger.info("Fetching items for user: {}", input.userId);
+            return List.of("item1", "item2", "item3", "item4");
+        });
+        logger.info("Fetched {} items", items.size());
+
+        // Step 2: Count items by category (Map<String, Integer>)
+        Map<String, Integer> counts =
+                context.step("count-by-category", new TypeToken<Map<String, Integer>>() {}, () -> {
+                    logger.info("Counting items by category");
+                    var result = new HashMap<String, Integer>();
+                    result.put("electronics", 2);
+                    result.put("books", 1);
+                    result.put("clothing", 1);
+                    return result;
+                });
+        logger.info("Counted {} categories", counts.size());
+
+        // Step 3: Fetch nested generic type with retry (Map<String, List<String>>)
+        Map<String, List<String>> categories = context.step(
+                "fetch-categories",
+                new TypeToken<Map<String, List<String>>>() {},
+                () -> {
+                    logger.info("Fetching category details");
+                    var result = new HashMap<String, List<String>>();
+                    result.put("electronics", List.of("laptop", "phone"));
+                    result.put("books", List.of("fiction"));
+                    result.put("clothing", List.of("shirt"));
+                    return result;
+                },
+                StepConfig.builder()
+                        .retryStrategy(RetryStrategies.Presets.DEFAULT)
+                        .build());
+        logger.info("Fetched {} category details", categories.size());
+
+        logger.info("Generic types example completed successfully");
+        return new Output(items, counts, categories);
+    }
+}

examples/src/main/java/com/amazonaws/lambda/durable/examples/GenericTypesExample.java

@@ -1,17 +1,18 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
 package com.amazonaws.lambda.durable.examples;
 
+import static org.junit.jupiter.api.Assertions.*;
+
 import com.amazonaws.lambda.durable.model.ExecutionStatus;
 import com.amazonaws.lambda.durable.testing.CloudDurableTestRunner;
+import java.util.Map;
 import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.condition.EnabledIf;
 import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
 import software.amazon.awssdk.services.sts.StsClient;
 
-import java.util.Map;
-
-import static org.junit.jupiter.api.Assertions.*;
-
 @EnabledIf("isEnabled")
 public class CloudBasedIntegrationTest {
 
@@ -21,7 +22,7 @@ public class CloudBasedIntegrationTest {
     static boolean isEnabled() {
         var enabled = "true".equals(System.getProperty("test.cloud.enabled"));
         if (!enabled) {
-            System.out.println("⚠️  Cloud integration tests disabled. Enable with -Dtest.cloud.enabled=true");
+            System.out.println("⚠️ Cloud integration tests disabled. Enable with -Dtest.cloud.enabled=true");
         }
         return enabled;
     }
@@ -40,10 +41,11 @@ static void setup() {
         if (account == null || region == null) {
             var sts = StsClient.create();
             if (account == null) account = sts.getCallerIdentity().account();
-            if (region == null) region = sts.serviceClientConfiguration().region().id();
+            if (region == null)
+                region = sts.serviceClientConfiguration().region().id();
         }
 
-        System.out.println("☁️  Running cloud integration tests against account " + account + " in " + region);
+        System.out.println("☁️ Running cloud integration tests against account " + account + " in " + region);
     }
 
     private static String arn(String functionName) {
@@ -141,7 +143,8 @@ void testWaitAtLeastExample() {
 
     @Test
     void testWaitAtLeastInProcessExample() {
-        var runner = CloudDurableTestRunner.create(arn("wait-at-least-in-process-example"), GreetingRequest.class, String.class);
+        var runner = CloudDurableTestRunner.create(
+                arn("wait-at-least-in-process-example"), GreetingRequest.class, String.class);
         var result = runner.run(new GreetingRequest("TestUser"));
 
         assertEquals(ExecutionStatus.SUCCEEDED, result.getStatus());
@@ -154,4 +157,41 @@ void testWaitAtLeastInProcessExample() {
         assertNotNull(asyncOp);
         assertTrue(asyncOp.getStepResult(String.class).contains("Processed: TestUser"));
     }
+
+    @Test
+    void testGenericTypesExample() {
+        var runner = CloudDurableTestRunner.create(
+                arn("generic-types-example"), GenericTypesExample.Input.class, GenericTypesExample.Output.class);
+        var result = runner.run(new GenericTypesExample.Input("user123"));
+
+        assertEquals(ExecutionStatus.SUCCEEDED, result.getStatus());
+
+        GenericTypesExample.Output output = result.getResult(GenericTypesExample.Output.class);
+        assertNotNull(output);
+
+        // Verify items list
+        assertNotNull(output.items);
+        assertEquals(4, output.items.size());
+        assertTrue(output.items.contains("item1"));
+        assertTrue(output.items.contains("item4"));
+
+        // Verify counts map
+        assertNotNull(output.counts);
+        assertEquals(3, output.counts.size());
+        assertEquals(2, output.counts.get("electronics"));
+        assertEquals(1, output.counts.get("books"));
+        assertEquals(1, output.counts.get("clothing"));
+
+        // Verify categories nested map
+        assertNotNull(output.categories);
+        assertEquals(3, output.categories.size());
+        assertEquals(2, output.categories.get("electronics").size());
+        assertTrue(output.categories.get("electronics").contains("laptop"));
+        assertTrue(output.categories.get("electronics").contains("phone"));
+
+        // Verify operations were executed
+        assertNotNull(runner.getOperation("fetch-items"));
+        assertNotNull(runner.getOperation("count-by-category"));
+        assertNotNull(runner.getOperation("fetch-categories"));
+    }
 }

examples/src/test/java/com/amazonaws/lambda/durable/examples/CloudBasedIntegrationTest.java

@@ -0,0 +1,70 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package com.amazonaws.lambda.durable.examples;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import com.amazonaws.lambda.durable.testing.LocalDurableTestRunner;
+import org.junit.jupiter.api.Test;
+
+class GenericTypesExampleTest {
+
+    @Test
+    void testGenericTypesExample() {
+        var handler = new GenericTypesExample();
+        var runner = LocalDurableTestRunner.create(GenericTypesExample.Input.class, handler::handleRequest)
+                .withSkipTime(true);
+
+        var input = new GenericTypesExample.Input("user123");
+        var result = runner.run(input);
+
+        assertNotNull(result);
+        GenericTypesExample.Output output = result.getResult(GenericTypesExample.Output.class);
+        assertNotNull(output);
+
+        // Verify items list
+        assertNotNull(output.items);
+        assertEquals(4, output.items.size());
+        assertTrue(output.items.contains("item1"));
+        assertTrue(output.items.contains("item4"));
+
+        // Verify counts map
+        assertNotNull(output.counts);
+        assertEquals(3, output.counts.size());
+        assertEquals(2, output.counts.get("electronics"));
+        assertEquals(1, output.counts.get("books"));
+        assertEquals(1, output.counts.get("clothing"));
+
+        // Verify categories nested map
+        assertNotNull(output.categories);
+        assertEquals(3, output.categories.size());
+        assertEquals(2, output.categories.get("electronics").size());
+        assertTrue(output.categories.get("electronics").contains("laptop"));
+        assertTrue(output.categories.get("electronics").contains("phone"));
+        assertEquals(1, output.categories.get("books").size());
+        assertTrue(output.categories.get("books").contains("fiction"));
+    }
+
+    @Test
+    void testOperationTracking() {
+        var handler = new GenericTypesExample();
+        var runner = LocalDurableTestRunner.create(GenericTypesExample.Input.class, handler::handleRequest)
+                .withSkipTime(true);
+
+        var input = new GenericTypesExample.Input("user456");
+        var result = runner.run(input);
+
+        // Verify all operations were executed
+        var fetchItems = result.getOperation("fetch-items");
+        assertNotNull(fetchItems);
+        assertEquals("fetch-items", fetchItems.getName());
+
+        var countByCategory = result.getOperation("count-by-category");
+        assertNotNull(countByCategory);
+        assertEquals("count-by-category", countByCategory.getName());
+
+        var fetchCategories = result.getOperation("fetch-categories");
+        assertNotNull(fetchCategories);
+        assertEquals("fetch-categories", fetchCategories.getName());
+    }
+}

examples/src/test/java/com/amazonaws/lambda/durable/examples/GenericTypesExampleTest.java

@@ -142,6 +142,28 @@ Resources:
       DockerContext: ../
       DockerTag: durable-examples
 
+  GenericTypesExampleFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      PackageType: Image
+      FunctionName: generic-types-example
+      ImageConfig:
+        Command: ["com.amazonaws.lambda.durable.examples.GenericTypesExample::handleRequest"]
+      DurableConfig:
+        ExecutionTimeout: 300
+        RetentionPeriodInDays: 7
+      Policies:
+        - Statement:
+            - Effect: Allow
+              Action:
+                - lambda:CheckpointDurableExecutions
+                - lambda:GetDurableExecutionState
+              Resource: !Sub "arn:aws:lambda:${AWS::Region}:${AWS::AccountId}:function:generic-types-example"
+    Metadata:
+      Dockerfile: examples/Dockerfile
+      DockerContext: ../
+      DockerTag: durable-examples
+
 Outputs:
   SimpleStepExampleFunction:
     Description: Simple Step Example Function ARN
@@ -190,3 +212,11 @@ Outputs:
   RetryInProcessExampleFunctionName:
     Description: Retry In Process Example Function Name
     Value: !Ref RetryInProcessExampleFunction
+
+  GenericTypesExampleFunction:
+    Description: Generic Types Example Function ARN
+    Value: !GetAtt GenericTypesExampleFunction.Arn
+
+  GenericTypesExampleFunctionName:
+    Description: Generic Types Example Function Name
+    Value: !Ref GenericTypesExampleFunction