feat(sdk): log AWS Lambda backend errors to developer logger (#250)

Add optional logger parameter to storage layer methods (getStepData and
checkpoint) to enable logging of AWS Lambda backend errors to the
developer's context logger in addition to internal debug logs.

Changes:
- Updated ExecutionState interface to accept optional Logger parameter
- Modified ApiStorage to log errors with requestId to developer logger
- Created initialization logger in execution-context using existing
createContextLoggerFactory for early error logging
- Updated CheckpointHandler to pass logger through to storage layer
- Fixed test assertions to expect new logger parameter
- Fixed TSDoc lint warning by escaping @ symbol

Author: ParidelPooya

packages/aws-durable-execution-sdk-js/src/context/durable-context/durable-context.ts

@@ -73,6 +73,7 @@ class DurableContextImpl implements DurableContext {
       executionContext,
       checkpointToken || "",
       this.operationsEmitter,
+      this.contextLogger || undefined,
     );
     this.durableExecutionMode = durableExecutionMode;
 

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

@@ -14,6 +14,15 @@ jest.mock("../../utils/logger/logger");
 jest.mock("../../termination-manager/termination-manager");
 
 describe("initializeExecutionContext", () => {
+  // Matcher for Logger interface
+  const expectLogger = expect.objectContaining({
+    log: expect.any(Function),
+    info: expect.any(Function),
+    error: expect.any(Function),
+    warn: expect.any(Function),
+    debug: expect.any(Function),
+  });
+
   // Setup common test variables
   const mockCheckpointToken = "test-checkpoint-token";
   const mockDurableExecutionArn = "test-durable-execution-arn";
@@ -195,6 +204,7 @@ describe("initializeExecutionContext", () => {
       mockCheckpointToken,
       "test-durable-execution-arn",
       "token1",
+      expectLogger,
     );
     expect(result.executionContext._stepData).toEqual({
       step1: mockInitialOperations[1],
@@ -250,11 +260,13 @@ describe("initializeExecutionContext", () => {
       mockCheckpointToken,
       "test-durable-execution-arn",
       "token1",
+      expectLogger,
     );
     expect(mockExecutionState.getStepData).toHaveBeenCalledWith(
       mockCheckpointToken,
       "test-durable-execution-arn",
       "token2",
+      expectLogger,
     );
     expect(result.executionContext._stepData).toEqual({
       step1: mockInitialOperations[1],
@@ -300,12 +312,14 @@ describe("initializeExecutionContext", () => {
       mockCheckpointToken,
       "test-durable-execution-arn",
       "token1",
+      expectLogger,
     );
 
     expect(mockExecutionState.getStepData).toHaveBeenCalledWith(
       mockCheckpointToken,
       "test-durable-execution-arn",
       "token2",
+      expectLogger,
     );
 
     expect(result.executionContext._stepData).toEqual({
@@ -337,6 +351,7 @@ describe("initializeExecutionContext", () => {
       mockCheckpointToken,
       "test-durable-execution-arn",
       "token1",
+      expectLogger,
     );
     expect(mockExecutionState.getStepData).toHaveBeenCalledTimes(1); // Should only be called once
     expect(result.executionContext._stepData).toEqual({
@@ -372,6 +387,7 @@ describe("initializeExecutionContext", () => {
       mockCheckpointToken,
       "test-durable-execution-arn",
       "token1",
+      expectLogger,
     );
     expect(result.executionContext._stepData).toEqual({});
   });
@@ -413,6 +429,7 @@ describe("initializeExecutionContext", () => {
       mockCheckpointToken,
       "test-durable-execution-arn",
       "token1",
+      expectLogger,
     );
     expect(result.executionContext._stepData).toEqual({
       step1: mockInitialOperations[1], // Only the initial operations should be present

packages/aws-durable-execution-sdk-js/src/context/execution-context/execution-context.ts

@@ -8,6 +8,8 @@ import {
 } from "../../types";
 import { log } from "../../utils/logger/logger";
 import { getStepData as getStepDataUtil } from "../../utils/step-id-utils/step-id-utils";
+import { createContextLoggerFactory } from "../../utils/logger/context-logger";
+import { createDefaultLogger } from "../../utils/logger/default-logger";
 
 export const initializeExecutionContext = async (
   event: DurableExecutionInvocationInput,
@@ -24,6 +26,13 @@ export const initializeExecutionContext = async (
 
   const state = getExecutionState();
 
+  // Create logger for initialization errors using existing logger factory
+  const tempContext = { durableExecutionArn } as ExecutionContext;
+  const initLogger = createContextLoggerFactory(
+    tempContext,
+    createDefaultLogger,
+  )("");
+
   const operationsArray = [...(event.InitialExecutionState.Operations || [])];
   let nextMarker = event.InitialExecutionState.NextMarker;
 
@@ -32,6 +41,7 @@ export const initializeExecutionContext = async (
       checkpointToken,
       durableExecutionArn,
       nextMarker,
+      initLogger,
     );
     operationsArray.push(...(response.Operations || []));
     nextMarker = response.NextMarker || "";

packages/aws-durable-execution-sdk-js/src/storage/api-storage.test.ts

@@ -243,4 +243,75 @@ describe("ApiStorage", () => {
       }),
     );
   });
+
+  test("should log getStepData errors to developer logger when provided", async () => {
+    const mockError = {
+      message: "GetDurableExecutionState failed",
+      $metadata: { requestId: "test-request-id-789" },
+    };
+    mockLambdaClient.send.mockRejectedValue(mockError);
+
+    const mockLogger = {
+      error: jest.fn(),
+      info: jest.fn(),
+      warn: jest.fn(),
+      debug: jest.fn(),
+      log: jest.fn(),
+    };
+
+    try {
+      await apiStorage.getStepData(
+        "checkpoint-token",
+        "test-execution-arn",
+        "next-marker",
+        mockLogger,
+      );
+    } catch (_error) {
+      // Expected to throw
+    }
+
+    expect(mockLogger.error).toHaveBeenCalledWith(
+      "Failed to get durable execution state",
+      mockError,
+      { requestId: "test-request-id-789" },
+    );
+  });
+
+  test("should log checkpoint errors to developer logger when provided", async () => {
+    const mockError = {
+      message: "CheckpointDurableExecution failed",
+      $metadata: { requestId: "test-request-id-999" },
+    };
+    mockLambdaClient.send.mockRejectedValue(mockError);
+
+    const mockLogger = {
+      error: jest.fn(),
+      info: jest.fn(),
+      warn: jest.fn(),
+      debug: jest.fn(),
+      log: jest.fn(),
+    };
+
+    const checkpointData: CheckpointDurableExecutionRequest = {
+      DurableExecutionArn: "test-execution-arn",
+      CheckpointToken: "",
+      Updates: [],
+    };
+
+    try {
+      await apiStorage.checkpoint(
+        "checkpoint-token",
+        checkpointData,
+        mockLogger,
+      );
+    } catch (_error) {
+      // Expected to throw
+    }
+
+    expect(mockLogger.error).toHaveBeenCalledWith(
+      "Failed to checkpoint durable execution",
+      mockError,
+      { requestId: "test-request-id-999" },
+    );
+  });
 });

packages/aws-durable-execution-sdk-js/src/storage/api-storage.ts

@@ -8,6 +8,7 @@ import {
 } from "@aws-sdk/client-lambda";
 import { ExecutionState } from "./storage";
 import { log } from "../utils/logger/logger";
+import { Logger } from "../types";
 
 /**
  * Implementation of ExecutionState that uses the new \@aws-sdk/client-lambda
@@ -23,12 +24,14 @@ export class ApiStorage implements ExecutionState {
    * Gets step data from the durable execution
    * @param checkpointToken - The checkpoint token
    * @param nextMarker - The pagination token
+   * @param logger - Optional developer logger for error reporting
    * @returns Response with operations data
    */
   async getStepData(
     checkpointToken: string,
     durableExecutionArn: string,
     nextMarker: string,
+    logger?: Logger,
   ): Promise<GetDurableExecutionStateResponse> {
     try {
       const response = await this.client.send(
@@ -42,6 +45,7 @@ export class ApiStorage implements ExecutionState {
 
       return response;
     } catch (error) {
+      // Internal debug logging
       log("❌", "GetDurableExecutionState failed", {
         error,
         requestId: (error as { $metadata?: { requestId?: string } })?.$metadata
@@ -50,6 +54,15 @@ export class ApiStorage implements ExecutionState {
         CheckpointToken: checkpointToken,
         Marker: nextMarker,
       });
+
+      // Developer logging if logger provided
+      if (logger) {
+        logger.error("Failed to get durable execution state", error as Error, {
+          requestId: (error as { $metadata?: { requestId?: string } })
+            ?.$metadata?.requestId,
+        });
+      }
+
       throw error;
     }
   }
@@ -58,11 +71,13 @@ export class ApiStorage implements ExecutionState {
    * Checkpoints the durable execution with operation updates
    * @param checkpointToken - The checkpoint token
    * @param data - The checkpoint data
+   * @param logger - Optional developer logger for error reporting
    * @returns Checkpoint response
    */
   async checkpoint(
     checkpointToken: string,
     data: CheckpointDurableExecutionRequest,
+    logger?: Logger,
   ): Promise<CheckpointDurableExecutionResponse> {
     try {
       const response = await this.client.send(
@@ -75,6 +90,7 @@ export class ApiStorage implements ExecutionState {
       );
       return response;
     } catch (error) {
+      // Internal debug logging
       log("❌", "CheckpointDurableExecution failed", {
         error,
         requestId: (error as { $metadata?: { requestId?: string } })?.$metadata
@@ -83,6 +99,15 @@ export class ApiStorage implements ExecutionState {
         CheckpointToken: checkpointToken,
         ClientToken: data.ClientToken,
       });
+
+      // Developer logging if logger provided
+      if (logger) {
+        logger.error("Failed to checkpoint durable execution", error as Error, {
+          requestId: (error as { $metadata?: { requestId?: string } })
+            ?.$metadata?.requestId,
+        });
+      }
+
       throw error;
     }
   }

packages/aws-durable-execution-sdk-js/src/storage/storage.ts

@@ -4,16 +4,19 @@ import {
   GetDurableExecutionStateResponse,
 } from "@aws-sdk/client-lambda";
 import { ApiStorage } from "./api-storage";
+import { Logger } from "../types";
 
 export interface ExecutionState {
   getStepData(
     taskToken: string,
     durableExecutionArn: string,
     nextToken: string,
+    logger?: Logger,
   ): Promise<GetDurableExecutionStateResponse>;
   checkpoint(
     taskToken: string,
     data: CheckpointDurableExecutionRequest,
+    logger?: Logger,
   ): Promise<CheckpointDurableExecutionResponse>;
 }
 

packages/aws-durable-execution-sdk-js/src/utils/checkpoint/checkpoint-integration.test.ts

@@ -145,6 +145,7 @@ describe("Checkpoint Integration Tests", () => {
           }),
         ]),
       }),
+      undefined, // logger parameter
     );
   });
 
@@ -178,6 +179,7 @@ describe("Checkpoint Integration Tests", () => {
           ),
         ),
       }),
+      undefined, // logger parameter
     );
   });
 

packages/aws-durable-execution-sdk-js/src/utils/checkpoint/checkpoint.test.ts

@@ -87,6 +87,7 @@ describe("CheckpointHandler", () => {
             },
           ],
         },
+        undefined, // logger parameter
       );
     });
   });
@@ -598,6 +599,7 @@ describe("CheckpointHandler", () => {
             },
           ],
         },
+        undefined, // logger parameter
       );
     });
   });
@@ -819,11 +821,15 @@ describe("deleteCheckpointHandler", () => {
 
       await checkpoint.force();
 
-      expect(mockState1.checkpoint).toHaveBeenCalledWith("test-token", {
-        DurableExecutionArn: "test-durable-execution-arn-1",
-        CheckpointToken: "test-token",
-        Updates: [],
-      });
+      expect(mockState1.checkpoint).toHaveBeenCalledWith(
+        "test-token",
+        {
+          DurableExecutionArn: "test-durable-execution-arn-1",
+          CheckpointToken: "test-token",
+          Updates: [],
+        },
+        undefined,
+      );
     });
 
     it("should not make additional checkpoint call when force is called during ongoing checkpoint", async () => {
@@ -873,17 +879,21 @@ describe("deleteCheckpointHandler", () => {
 
       // Should still only have made one API call total (the force request piggybacked)
       expect(mockState1.checkpoint).toHaveBeenCalledTimes(1);
-      expect(mockState1.checkpoint).toHaveBeenCalledWith("test-token", {
-        DurableExecutionArn: "test-durable-execution-arn-1",
-        CheckpointToken: "test-token",
-        Updates: [
-          {
-            Type: OperationType.STEP,
-            Action: OperationAction.START,
-            Id: hashId("step1"),
-          },
-        ],
-      });
+      expect(mockState1.checkpoint).toHaveBeenCalledWith(
+        "test-token",
+        {
+          DurableExecutionArn: "test-durable-execution-arn-1",
+          CheckpointToken: "test-token",
+          Updates: [
+            {
+              Type: OperationType.STEP,
+              Action: OperationAction.START,
+              Id: hashId("step1"),
+            },
+          ],
+        },
+        undefined,
+      );
     });
 
     it("should terminate execution when force checkpoint fails", async () => {
@@ -979,6 +989,7 @@ describe("createCheckpointHandler", () => {
           }),
         ]),
       }),
+      undefined, // logger parameter
     );
   });