feat(sdk): add configureLogger method with modeAware option (#253)

Replace setCustomLogger() with configureLogger() that accepts
LoggerConfig
object with customLogger and modeAware options. The modeAware flag
controls
    whether logs are suppressed during replay mode (default: true).
    
BREAKING CHANGE: Removed setCustomLogger() method in favor of
configureLogger().
This is acceptable as the SDK has not been launched yet and there are no
existing users.
    
    Changes:
    - Add configureLogger(config: LoggerConfig) method to DurableContext
- Add LoggerConfig interface with customLogger and modeAware properties
    - Update createModeAwareLogger to accept modeAwareEnabled parameter
- Change default modeAware behavior to true (suppress logs during
replay)
- Fix replay mode switching for backend-completed operations (wait,
invoke,
createCallback, waitForCallback) by calling checkAndUpdateReplayMode()
after completion
- Update all tests to reflect new default behavior and mode switching
fix
- Add logger-test examples with file-based logging (local-only tests)
    - Update documentation: README, API_SPECIFICATION.md with new API
    - Add TSDoc comments for Logger types and configureLogger method
    - Remove old logger-example with outdated information

**Limitation**:
Integration tests are against local runner and we have a issue to add it
to Cloud mode:
#255


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

Author: ParidelPooya

packages/aws-durable-execution-sdk-js-examples/src/examples/logger-example/logger-example.test.ts

@@ -0,0 +1,132 @@
+import { handler } from "./logger-after-callback";
+import { createTests } from "../../../utils/test-helper";
+import {
+  InvocationType,
+  WaitingOperationStatus,
+} from "@aws/durable-execution-sdk-js-testing";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { randomUUID } from "crypto";
+
+createTests({
+  name: "logger-after-callback",
+  functionName: "logger-after-callback",
+  handler,
+  invocationType: InvocationType.Event,
+  tests: (runner, isCloud) => {
+    if (!isCloud) {
+      it("should log correctly with modeAware=true", async () => {
+        const logFilePath = path.join(
+          os.tmpdir(),
+          `logger-test-${randomUUID()}.log`,
+        );
+
+        if (fs.existsSync(logFilePath)) {
+          fs.unlinkSync(logFilePath);
+        }
+
+        try {
+          const executionPromise = runner.run({
+            payload: { logFilePath, modeAware: true },
+          });
+
+          const callbackOp = runner.getOperationByIndex(0);
+          await callbackOp.waitForData(WaitingOperationStatus.STARTED);
+          await callbackOp.sendCallbackSuccess("test-result");
+
+          const execution = await executionPromise;
+
+          const result = execution.getResult() as any;
+          expect(result.message).toBe("Success");
+          expect(result.callbackId).toBeDefined();
+          expect(result.result).toBe("test-result");
+
+          const logContent = fs.readFileSync(logFilePath, "utf-8");
+          const logLines = logContent
+            .trim()
+            .split("\n")
+            .map((line) => JSON.parse(line));
+
+          const beforeCallbackLogs = logLines.filter(
+            (log) => log.message === "Before createCallback",
+          );
+          const afterCallbackLogs = logLines.filter(
+            (log) => log.message === "After createCallback",
+          );
+
+          // With modeAware: true:
+          // - "Before createCallback" appears once (execution mode only, suppressed during replay)
+          // - "After createCallback" appears once (after callback resolves, in execution mode)
+          expect(beforeCallbackLogs.length).toBe(1);
+          expect(afterCallbackLogs.length).toBe(1);
+        } finally {
+          if (fs.existsSync(logFilePath)) {
+            fs.unlinkSync(logFilePath);
+          }
+        }
+      });
+
+      it("should log correctly with modeAware=false", async () => {
+        const logFilePath = path.join(
+          os.tmpdir(),
+          `logger-test-${randomUUID()}.log`,
+        );
+
+        if (fs.existsSync(logFilePath)) {
+          fs.unlinkSync(logFilePath);
+        }
+
+        try {
+          const executionPromise = runner.run({
+            payload: { logFilePath, modeAware: false },
+          });
+
+          const callbackOp = runner.getOperationByIndex(0);
+          await callbackOp.waitForData(WaitingOperationStatus.STARTED);
+          await callbackOp.sendCallbackSuccess("test-result");
+
+          const execution = await executionPromise;
+
+          const result = execution.getResult() as any;
+          expect(result.message).toBe("Success");
+
+          const logContent = fs.readFileSync(logFilePath, "utf-8");
+          const logLines = logContent
+            .trim()
+            .split("\n")
+            .map((line) => JSON.parse(line));
+
+          const beforeCallbackLogs = logLines.filter(
+            (log) => log.message === "Before createCallback",
+          );
+          const afterCallbackLogs = logLines.filter(
+            (log) => log.message === "After createCallback",
+          );
+
+          // With modeAware: false:
+          // - "Before createCallback" appears twice (execution + replay)
+          // - "After createCallback" appears once (after callback resolves)
+          expect(beforeCallbackLogs.length).toBe(2);
+          expect(afterCallbackLogs.length).toBe(1);
+        } finally {
+          if (fs.existsSync(logFilePath)) {
+            fs.unlinkSync(logFilePath);
+          }
+        }
+      });
+    }
+
+    it("should execute successfully", async () => {
+      const executionPromise = runner.run();
+
+      const callbackOp = runner.getOperationByIndex(0);
+      await callbackOp.waitForData(WaitingOperationStatus.STARTED);
+      await callbackOp.sendCallbackSuccess("test-result");
+
+      const execution = await executionPromise;
+      const result = execution.getResult() as any;
+      expect(result.message).toBe("Success");
+    });
+  },
+});

packages/aws-durable-execution-sdk-js-examples/src/examples/logger-example/logger-example.ts

@@ -0,0 +1,70 @@
+import { withDurableExecution, Logger } from "@aws/durable-execution-sdk-js";
+import { ExampleConfig } from "../../../types";
+import * as fs from "fs";
+
+export const config: ExampleConfig = {
+  name: "Logger After Callback",
+  description: "Test logger mode switching after createCallback operation",
+};
+
+interface LoggerTestEvent {
+  logFilePath?: string;
+  modeAware?: boolean;
+}
+
+export const handler = withDurableExecution(
+  async (event: LoggerTestEvent, context) => {
+    if (event.logFilePath) {
+      const fileLogger: Logger = {
+        log: (level, message, data) => {
+          fs.appendFileSync(
+            event.logFilePath!,
+            JSON.stringify({ level, message, data }) + "\n",
+          );
+        },
+        info: (message, data) => {
+          fs.appendFileSync(
+            event.logFilePath!,
+            JSON.stringify({ level: "info", message, data }) + "\n",
+          );
+        },
+        error: (message, error, data) => {
+          fs.appendFileSync(
+            event.logFilePath!,
+            JSON.stringify({ level: "error", message, error, data }) + "\n",
+          );
+        },
+        warn: (message, data) => {
+          fs.appendFileSync(
+            event.logFilePath!,
+            JSON.stringify({ level: "warn", message, data }) + "\n",
+          );
+        },
+        debug: (message, data) => {
+          fs.appendFileSync(
+            event.logFilePath!,
+            JSON.stringify({ level: "debug", message, data }) + "\n",
+          );
+        },
+      };
+
+      context.configureLogger({
+        customLogger: fileLogger,
+        modeAware: event.modeAware ?? true,
+      });
+    } else {
+      context.configureLogger({ modeAware: event.modeAware ?? true });
+    }
+
+    context.logger.info("Before createCallback");
+
+    const [callbackPromise, callbackId] =
+      await context.createCallback<string>();
+
+    const result = await callbackPromise;
+
+    context.logger.info("After createCallback");
+
+    return { message: "Success", callbackId, result };
+  },
+);

packages/aws-durable-execution-sdk-js-examples/src/examples/logger-test/after-callback/logger-after-callback.test.ts

@@ -0,0 +1,60 @@
+import { handler } from "./logger-after-wait";
+import { createTests } from "../../../utils/test-helper";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { randomUUID } from "crypto";
+
+createTests({
+  name: "logger-after-wait",
+  functionName: "logger-after-wait",
+  handler,
+  tests: (runner, isCloud) => {
+    if (!isCloud) {
+      it("should log after wait in execution mode with modeAware=true", async () => {
+        const logFilePath = path.join(
+          os.tmpdir(),
+          `logger-test-${randomUUID()}.log`,
+        );
+
+        if (fs.existsSync(logFilePath)) {
+          fs.unlinkSync(logFilePath);
+        }
+
+        try {
+          const execution = await runner.run({
+            payload: { logFilePath, modeAware: true },
+          });
+
+          expect(execution.getResult()).toEqual({ message: "Success" });
+
+          const logContent = fs.readFileSync(logFilePath, "utf-8");
+          const logLines = logContent
+            .trim()
+            .split("\n")
+            .map((line) => JSON.parse(line));
+
+          const beforeWaitLogs = logLines.filter(
+            (log) => log.message === "Before wait",
+          );
+          const afterWaitLogs = logLines.filter(
+            (log) => log.message === "After wait",
+          );
+
+          // With modeAware: true, both logs appear once (execution mode only)
+          expect(beforeWaitLogs.length).toBe(1);
+          expect(afterWaitLogs.length).toBe(1);
+        } finally {
+          if (fs.existsSync(logFilePath)) {
+            fs.unlinkSync(logFilePath);
+          }
+        }
+      });
+    }
+
+    it("should execute successfully", async () => {
+      const execution = await runner.run();
+      expect(execution.getResult()).toEqual({ message: "Success" });
+    });
+  },
+});