Harden waitForSettledDOM stalled request diagnostics

Co-authored-by: Shri Sukhani <shrisukhani@users.noreply.github.com>

Author: cursoragent

src/utils/waitForSettledDOM.test.ts

@@ -0,0 +1,118 @@
+import { waitForSettledDOM } from "@/utils/waitForSettledDOM";
+import type { CDPClient, CDPSession } from "@/cdp";
+
+jest.mock("@/cdp", () => ({
+  getCDPClient: jest.fn(),
+  getOrCreateFrameContextManager: jest.fn(),
+}));
+
+jest.mock("@/debug/options", () => ({
+  getDebugOptions: jest.fn(() => ({
+    enabled: true,
+    traceWait: true,
+  })),
+}));
+
+const { getCDPClient, getOrCreateFrameContextManager } = jest.requireMock(
+  "@/cdp"
+) as {
+  getCDPClient: jest.Mock;
+  getOrCreateFrameContextManager: jest.Mock;
+};
+
+type EventHandler = (...args: unknown[]) => void;
+
+function createSessionWithEvents(): {
+  session: CDPSession;
+  emit: (event: string, payload: unknown) => void;
+} {
+  const handlers = new Map<string, Set<EventHandler>>();
+  const session: CDPSession = {
+    send: async <T = unknown>(): Promise<T> => ({} as T),
+    on: <TPayload extends unknown[]>(
+      event: string,
+      handler: (...payload: TPayload) => void
+    ) => {
+      const eventHandler = handler as EventHandler;
+      const existing = handlers.get(event);
+      if (existing) {
+        existing.add(eventHandler);
+      } else {
+        handlers.set(event, new Set([eventHandler]));
+      }
+    },
+    off: <TPayload extends unknown[]>(
+      event: string,
+      handler: (...payload: TPayload) => void
+    ) => {
+      handlers.get(event)?.delete(handler as EventHandler);
+    },
+    detach: async () => undefined,
+    id: "session-1",
+  };
+
+  const emit = (event: string, payload: unknown): void => {
+    handlers.get(event)?.forEach((handler) => {
+      handler(payload);
+    });
+  };
+
+  return { session, emit };
+}
+
+describe("waitForSettledDOM diagnostics", () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+    jest.clearAllMocks();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it("sanitizes and truncates stalled-request warning diagnostics", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    const { session, emit } = createSessionWithEvents();
+    const cdpClient: CDPClient = {
+      rootSession: session,
+      createSession: async () => session,
+      acquireSession: async () => session,
+      dispose: async () => undefined,
+    };
+    getCDPClient.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManager.mockReturnValue({
+      setDebug: jest.fn(),
+    });
+
+    const page = {
+      context: () => ({}),
+    } as never;
+
+    try {
+      const waitPromise = waitForSettledDOM(page, 5_000);
+      await Promise.resolve();
+      await Promise.resolve();
+
+      emit("Network.requestWillBeSent", {
+        requestId: `req\u0000\n${"x".repeat(600)}`,
+        type: "Document",
+        request: {
+          url: `https://example.com/path\u0000\n${"y".repeat(2_000)}`,
+        },
+      });
+
+      await jest.advanceTimersByTimeAsync(3_100);
+      await waitPromise;
+
+      const warning = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+      expect(warning.length).toBeLessThan(900);
+    } finally {
+      warnSpy.mockRestore();
+      logSpy.mockRestore();
+    }
+  });
+});

src/utils/waitForSettledDOM.ts

@@ -24,10 +24,53 @@ import { getDebugOptions } from "@/debug/options";
 const NETWORK_IDLE_THRESHOLD_MS = 500;
 const STALLED_REQUEST_MS = 2000;
 const STALLED_SWEEP_INTERVAL_MS = 500;
+const MAX_WAIT_DIAGNOSTIC_CHARS = 400;
+const MAX_WAIT_IDENTIFIER_CHARS = 200;
 const ENV_TRACE_WAIT =
   process.env.HYPERAGENT_TRACE_WAIT === "1" ||
   process.env.HYPERAGENT_TRACE_WAIT === "true";
 
+function sanitizeWaitDiagnosticText(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+}
+
+function truncateWaitDiagnostic(value: string, maxChars: number): string {
+  if (value.length <= maxChars) {
+    return value;
+  }
+  const omittedChars = value.length - maxChars;
+  return `${value.slice(0, maxChars)}... [truncated ${omittedChars} chars]`;
+}
+
+function formatWaitIdentifier(value: unknown): string {
+  if (typeof value !== "string") {
+    return "unknown";
+  }
+  const normalized = sanitizeWaitDiagnosticText(value);
+  if (normalized.length === 0) {
+    return "unknown";
+  }
+  return truncateWaitDiagnostic(normalized, MAX_WAIT_IDENTIFIER_CHARS);
+}
+
+function formatWaitUrl(value: unknown): string {
+  if (typeof value !== "string") {
+    return "unknown";
+  }
+  const normalized = sanitizeWaitDiagnosticText(value);
+  if (normalized.length === 0) {
+    return "unknown";
+  }
+  return truncateWaitDiagnostic(normalized, MAX_WAIT_DIAGNOSTIC_CHARS);
+}
+
 export interface LifecycleOptions {
   waitUntil?: Array<"domcontentloaded" | "load" | "networkidle">;
   timeoutMs?: number;
@@ -211,7 +254,11 @@ async function waitForNetworkIdle(
             stats.forcedDrops += 1;
             if (trace) {
               console.warn(
-                `[waitForSettledDOM] Forcing completion of stalled request ${id} (age=${now - meta.start}ms url=${meta.url ?? "unknown"})`
+                `[waitForSettledDOM] Forcing completion of stalled request ${formatWaitIdentifier(
+                  id
+                )} (age=${now - meta.start}ms url=${formatWaitUrl(
+                  meta.url
+                )})`
               );
             }
             requestMeta.delete(id);