fix(util-waiter): fix for circular refs in waiter debug logs (#1756)

Author: kuhe

.changeset/serious-chairs-accept.md

@@ -0,0 +1,5 @@
+---
+"@smithy/util-waiter": patch
+---
+
+handle circular refs in debug messages

packages/util-waiter/src/circularReplacer.spec.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+
+import { getCircularReplacer } from "./circularReplacer";
+
+describe("getCircularReplacer", () => {
+  it("should handle nested circular references", () => {
+    const x = {
+      a: 1,
+      b: 2,
+      c: {
+        d: {
+          e: -1,
+          f: 3,
+          g: {
+            h: -1,
+          },
+        },
+      },
+    } as any;
+
+    x.c.d.e = x;
+    x.c.d.g.h = x;
+
+    expect(
+      JSON.parse(
+        JSON.stringify(
+          {
+            x,
+          },
+          getCircularReplacer()
+        )
+      )
+    ).toEqual({
+      x: {
+        a: 1,
+        b: 2,
+        c: {
+          d: {
+            e: "[Circular]",
+            f: 3,
+            g: {
+              h: "[Circular]",
+            },
+          },
+        },
+      },
+    });
+  });
+});

packages/util-waiter/src/circularReplacer.ts

@@ -0,0 +1,17 @@
+/**
+ * Helper for JSON stringification debug logging.
+ *
+ * @internal
+ */
+export const getCircularReplacer = () => {
+  const seen = new WeakSet();
+  return (key: any, value: any) => {
+    if (typeof value === "object" && value !== null) {
+      if (seen.has(value)) {
+        return "[Circular]";
+      }
+      seen.add(value);
+    }
+    return value;
+  };
+};

packages/util-waiter/src/poller.ts

@@ -1,3 +1,4 @@
+import { getCircularReplacer } from "./circularReplacer";
 import { sleep } from "./utils/sleep";
 import type { WaiterOptions, WaiterResult } from "./waiter";
 import { WaiterState } from "./waiter";
@@ -21,7 +22,7 @@ const randomInRange = (min: number, max: number) => min + Math.random() * (max -
  * @param params - options passed to the waiter.
  * @param client - AWS SDK Client
  * @param input - client input
- * @param stateChecker - function that checks the acceptor states on each poll.
+ * @param acceptorChecks - function that checks the acceptor states on each poll.
  */
 export const runPolling = async <Client, Input>(
   { minDelay, maxDelay, maxWaitTime, abortController, client, abortSignal }: WaiterOptions<Client>,
@@ -96,5 +97,5 @@ const createMessageFromResponse = (reason: any): string => {
     return `${reason.$metadata.httpStatusCode}: OK`;
   }
   // is an unknown object.
-  return String(reason?.message ?? JSON.stringify(reason) ?? "Unknown");
+  return String(reason?.message ?? JSON.stringify(reason, getCircularReplacer()) ?? "Unknown");
 };

packages/util-waiter/src/waiter.ts

@@ -1,5 +1,7 @@
 import type { WaiterConfiguration as WaiterConfiguration__ } from "@smithy/types";
 
+import { getCircularReplacer } from "./circularReplacer";
+
 /**
  * @internal
  */
@@ -57,24 +59,30 @@ export type WaiterResult = {
 export const checkExceptions = (result: WaiterResult): WaiterResult => {
   if (result.state === WaiterState.ABORTED) {
     const abortError = new Error(
-      `${JSON.stringify({
-        ...result,
-        reason: "Request was aborted",
-      })}`
+      `${JSON.stringify(
+        {
+          ...result,
+          reason: "Request was aborted",
+        },
+        getCircularReplacer()
+      )}`
     );
     abortError.name = "AbortError";
     throw abortError;
   } else if (result.state === WaiterState.TIMEOUT) {
     const timeoutError = new Error(
-      `${JSON.stringify({
-        ...result,
-        reason: "Waiter has timed out",
-      })}`
+      `${JSON.stringify(
+        {
+          ...result,
+          reason: "Waiter has timed out",
+        },
+        getCircularReplacer()
+      )}`
     );
     timeoutError.name = "TimeoutError";
     throw timeoutError;
   } else if (result.state !== WaiterState.SUCCESS) {
-    throw new Error(`${JSON.stringify(result)}`);
+    throw new Error(`${JSON.stringify(result, getCircularReplacer())}`);
   }
   return result;
 };