feat(sdk): improve serdes resilience for external dependencies (#90)

*Description of changes:*
- Change SerializationFailedError and DeserializationFailedError to
extend UnrecoverableInvocationError instead of
UnrecoverableExecutionError
- Update error handling in withDurableFunctions to throw
UnrecoverableInvocationError instead of returning error envelope
- Consolidate error handling logic to use single
isUnrecoverableInvocationError check
- Add comprehensive test coverage for both UnrecoverableInvocationError
and UnrecoverableExecutionError handling
    
This enables automatic recovery from temporary failures in external
services used by custom serdes implementations (e.g., S3, DynamoDB) by
terminating the current Lambda invocation for retry rather than
permanently failing the execution.

By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice.

Co-authored-by: Pooya Paridel <parpooya@amazon.com>

Author: ParidelPooya

packages/aws-durable-execution-sdk-js/src/errors/serdes-errors/serdes-errors.test.ts

@@ -7,9 +7,9 @@ import {
 } from "./serdes-errors";
 import {
   UnrecoverableError,
-  UnrecoverableExecutionError,
+  UnrecoverableInvocationError,
   isUnrecoverableError,
-  isUnrecoverableExecutionError,
+  isUnrecoverableInvocationError,
 } from "../unrecoverable-error/unrecoverable-error";
 import { TerminationReason } from "../../termination-manager/types";
 import { TerminationManager } from "../../termination-manager/termination-manager";
@@ -26,17 +26,17 @@ describe("Serdes Errors", () => {
       );
 
       expect(error.name).toBe("SerializationFailedError");
-      expect(error.message).toContain("[Unrecoverable Execution]");
+      expect(error.message).toContain("[Unrecoverable Invocation]");
       expect(error.message).toContain(
         'Serialization failed for step "test-step" (step-1)',
       );
       expect(error.message).toContain("JSON.stringify failed");
       expect(error.terminationReason).toBe(TerminationReason.CUSTOM);
       expect(error.isUnrecoverable).toBe(true);
-      expect(error.isUnrecoverableExecution).toBe(true);
+      expect(error.isUnrecoverableInvocation).toBe(true);
       expect(error.originalError).toBe(originalError);
       expect(error).toBeInstanceOf(UnrecoverableError);
-      expect(error).toBeInstanceOf(UnrecoverableExecutionError);
+      expect(error).toBeInstanceOf(UnrecoverableInvocationError);
     });
 
     it("should create error without step name", () => {
@@ -61,7 +61,7 @@ describe("Serdes Errors", () => {
     it("should create error without originalError", () => {
       const error = new SerializationFailedError("step-1", "test-step");
 
-      expect(error.message).toContain("[Unrecoverable Execution]");
+      expect(error.message).toContain("[Unrecoverable Invocation]");
       expect(error.message).toContain(
         'Serialization failed for step "test-step" (step-1)',
       );
@@ -77,7 +77,7 @@ describe("Serdes Errors", () => {
         originalError,
       );
 
-      expect(error.message).toContain("[Unrecoverable Execution]");
+      expect(error.message).toContain("[Unrecoverable Invocation]");
       expect(error.message).toContain(
         'Serialization failed for step "test-step" (step-1)',
       );
@@ -96,17 +96,17 @@ describe("Serdes Errors", () => {
       );
 
       expect(error.name).toBe("DeserializationFailedError");
-      expect(error.message).toContain("[Unrecoverable Execution]");
+      expect(error.message).toContain("[Unrecoverable Invocation]");
       expect(error.message).toContain(
         'Deserialization failed for step "test-step" (step-1)',
       );
       expect(error.message).toContain("JSON.parse failed");
       expect(error.terminationReason).toBe(TerminationReason.CUSTOM);
       expect(error.isUnrecoverable).toBe(true);
-      expect(error.isUnrecoverableExecution).toBe(true);
+      expect(error.isUnrecoverableInvocation).toBe(true);
       expect(error.originalError).toBe(originalError);
       expect(error).toBeInstanceOf(UnrecoverableError);
-      expect(error).toBeInstanceOf(UnrecoverableExecutionError);
+      expect(error).toBeInstanceOf(UnrecoverableInvocationError);
     });
 
     it("should create error without step name", () => {
@@ -121,7 +121,7 @@ describe("Serdes Errors", () => {
     it("should create error without originalError", () => {
       const error = new DeserializationFailedError("step-1", "test-step");
 
-      expect(error.message).toContain("[Unrecoverable Execution]");
+      expect(error.message).toContain("[Unrecoverable Invocation]");
       expect(error.message).toContain(
         'Deserialization failed for step "test-step" (step-1)',
       );
@@ -137,7 +137,7 @@ describe("Serdes Errors", () => {
         originalError,
       );
 
-      expect(error.message).toContain("[Unrecoverable Execution]");
+      expect(error.message).toContain("[Unrecoverable Invocation]");
       expect(error.message).toContain(
         'Deserialization failed for step "test-step" (step-1)',
       );
@@ -174,13 +174,13 @@ describe("Serdes Errors", () => {
     it("should return true for SerializationFailedError", () => {
       const error = new SerializationFailedError("step-1");
       expect(isUnrecoverableError(error)).toBe(true);
-      expect(isUnrecoverableExecutionError(error)).toBe(true);
+      expect(isUnrecoverableInvocationError(error)).toBe(true);
     });
 
     it("should return true for DeserializationFailedError", () => {
       const error = new DeserializationFailedError("step-1");
       expect(isUnrecoverableError(error)).toBe(true);
-      expect(isUnrecoverableExecutionError(error)).toBe(true);
+      expect(isUnrecoverableInvocationError(error)).toBe(true);
     });
   });
 

packages/aws-durable-execution-sdk-js/src/errors/serdes-errors/serdes-errors.ts

@@ -1,15 +1,15 @@
 import { TerminationReason } from "../../termination-manager/types";
 import { TerminationManager } from "../../termination-manager/termination-manager";
-import { UnrecoverableExecutionError } from "../unrecoverable-error/unrecoverable-error";
+import { UnrecoverableInvocationError } from "../unrecoverable-error/unrecoverable-error";
 import { log } from "../../utils/logger/logger";
 import { SerdesContext } from "../../utils/serdes/serdes";
 
 /**
  * Error thrown when serialization fails
- * This is an unrecoverable execution error that will terminate the entire execution
+ * This is an unrecoverable invocation error that will terminate the current Lambda invocation
  * because data corruption or incompatible formats indicate a fundamental problem
  */
-export class SerializationFailedError extends UnrecoverableExecutionError {
+export class SerializationFailedError extends UnrecoverableInvocationError {
   readonly terminationReason = TerminationReason.CUSTOM;
 
   constructor(stepId: string, stepName?: string, originalError?: Error) {
@@ -20,10 +20,10 @@ export class SerializationFailedError extends UnrecoverableExecutionError {
 
 /**
  * Error thrown when deserialization fails
- * This is an unrecoverable execution error that will terminate the entire execution
+ * This is an unrecoverable invocation error that will terminate the current Lambda invocation
  * because data corruption or incompatible formats indicate a fundamental problem
  */
-export class DeserializationFailedError extends UnrecoverableExecutionError {
+export class DeserializationFailedError extends UnrecoverableInvocationError {
   readonly terminationReason = TerminationReason.CUSTOM;
 
   constructor(stepId: string, stepName?: string, originalError?: Error) {
@@ -34,7 +34,7 @@ export class DeserializationFailedError extends UnrecoverableExecutionError {
 
 /**
  * Type guard to check if an error is a Serdes error
- * @deprecated Use isUnrecoverableExecutionError instead for broader error detection
+ * @deprecated Use isUnrecoverableInvocationError instead for broader error detection
  */
 export function isSerdesError(
   error: unknown,

packages/aws-durable-execution-sdk-js/src/with-durable-functions.test.ts

@@ -2,6 +2,11 @@ import { withDurableFunctions } from "./with-durable-functions";
 import { initializeExecutionContext } from "./context/execution-context/execution-context";
 import { createDurableContext } from "./context/durable-context/durable-context";
 import { CheckpointFailedError } from "./errors/checkpoint-errors/checkpoint-errors";
+import { 
+  UnrecoverableInvocationError, 
+  UnrecoverableExecutionError 
+} from "./errors/unrecoverable-error/unrecoverable-error";
+import { SerializationFailedError } from "./errors/serdes-errors/serdes-errors";
 import { TerminationReason } from "./termination-manager/types";
 import { Context } from "aws-lambda";
 import { log } from "./utils/logger/logger";
@@ -383,6 +388,81 @@ describe("withDurableFunctions", () => {
     );
   });
 
+  it("should throw error when handler throws UnrecoverableInvocationError", async () => {
+    // Setup
+    const serdesError = new SerializationFailedError("step-1", "test-step");
+    const mockHandler = jest.fn().mockRejectedValue(serdesError);
+    mockTerminationManager.getTerminationPromise.mockReturnValue(
+      new Promise(() => {}),
+    ); // Never resolves
+
+    // Execute & Verify
+    const wrappedHandler = withDurableFunctions(mockHandler);
+    await expect(wrappedHandler(mockEvent, mockContext)).rejects.toThrow(
+      SerializationFailedError,
+    );
+    expect(mockHandler).toHaveBeenCalledWith(
+      mockCustomerHandlerEvent,
+      mockDurableContext,
+    );
+  });
+
+  it("should throw error when handler throws custom UnrecoverableInvocationError", async () => {
+    // Setup - Create a custom UnrecoverableInvocationError
+    class CustomInvocationError extends UnrecoverableInvocationError {
+      readonly terminationReason = TerminationReason.CUSTOM;
+      constructor(message: string) {
+        super(message);
+      }
+    }
+    
+    const customError = new CustomInvocationError("Custom invocation error");
+    const mockHandler = jest.fn().mockRejectedValue(customError);
+    mockTerminationManager.getTerminationPromise.mockReturnValue(
+      new Promise(() => {}),
+    ); // Never resolves
+
+    // Execute & Verify
+    const wrappedHandler = withDurableFunctions(mockHandler);
+    await expect(wrappedHandler(mockEvent, mockContext)).rejects.toThrow(
+      CustomInvocationError,
+    );
+    expect(mockHandler).toHaveBeenCalledWith(
+      mockCustomerHandlerEvent,
+      mockDurableContext,
+    );
+  });
+
+  it("should return error response when handler throws UnrecoverableExecutionError", async () => {
+    // Setup - Create a custom UnrecoverableExecutionError
+    class CustomExecutionError extends UnrecoverableExecutionError {
+      readonly terminationReason = TerminationReason.CUSTOM;
+      constructor(message: string) {
+        super(message);
+      }
+    }
+    
+    const executionError = new CustomExecutionError("Custom execution error");
+    const mockHandler = jest.fn().mockRejectedValue(executionError);
+    mockTerminationManager.getTerminationPromise.mockReturnValue(
+      new Promise(() => {}),
+    ); // Never resolves
+
+    // Execute
+    const wrappedHandler = withDurableFunctions(mockHandler);
+    const response = await wrappedHandler(mockEvent, mockContext);
+
+    // Verify - UnrecoverableExecutionError should be returned as failed invocation, not thrown
+    expect(mockHandler).toHaveBeenCalledWith(
+      mockCustomerHandlerEvent,
+      mockDurableContext,
+    );
+    expect(response).toEqual({
+      Status: InvocationStatus.FAILED,
+      Error: createErrorObjectFromError(executionError),
+    });
+  });
+
   it("should call deleteCheckpoint when initializing durable function", async () => {
     // Setup
     const mockResult = { success: true };

packages/aws-durable-execution-sdk-js/src/with-durable-functions.ts

@@ -4,6 +4,7 @@ import { createDurableContext } from "./context/durable-context/durable-context"
 
 import { initializeExecutionContext } from "./context/execution-context/execution-context";
 import { CheckpointFailedError } from "./errors/checkpoint-errors/checkpoint-errors";
+import { isUnrecoverableInvocationError } from "./errors/unrecoverable-error/unrecoverable-error";
 import {
   createCheckpoint,
   deleteCheckpoint,
@@ -183,12 +184,12 @@ async function runHandler<Input, Output>(
   } catch (error) {
     log(executionContext.isVerbose, "❌", "Handler threw an error:", error);
 
-    // Check if this is a checkpoint failure
-    if (error instanceof CheckpointFailedError) {
+    // Check if this is an unrecoverable invocation error (includes checkpoint failures and serdes errors)
+    if (isUnrecoverableInvocationError(error)) {
       log(
         executionContext.isVerbose,
         "🛑",
-        "Checkpoint failed - terminating Lambda execution",
+        "Unrecoverable invocation error - terminating Lambda execution",
       );
       throw error; // Re-throw the error to terminate Lambda execution
     }