@superblocksteam/sdk 2.0.157-next.4 → 2.0.157-next.5

package/src/dev-utils/fatal-process-barrier.test.mts

@@ -0,0 +1,346 @@
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { FATAL_EXIT_EVENT } from "./fatal-exit.mjs";
+import {
+  fatalAwareExitCode,
+  installFatalProcessBarrier,
+  isFatalProcessHandled,
+  type FatalProcessHost,
+} from "./fatal-process-barrier.mjs";
+
+/**
+ * Stands in for `process` so a test can emit crash events without arming the
+ * real handlers, which would take the test runner down with them.
+ */
+function fakeProcess(): FatalProcessHost & {
+  emit: (event: string, ...args: unknown[]) => void;
+  listenerCount: (event: string) => number;
+} {
+  const handlers = new Map<string, ((...args: unknown[]) => void)[]>();
+  return {
+    emit(event: string, ...args: unknown[]): void {
+      for (const handler of handlers.get(event) ?? []) {
+        handler(...args);
+      }
+    },
+    listenerCount(event: string): number {
+      return handlers.get(event)?.length ?? 0;
+    },
+    off(event: string, handler: (...args: unknown[]) => void): void {
+      handlers.set(
+        event,
+        (handlers.get(event) ?? []).filter((each) => each !== handler),
+      );
+    },
+    on(event: string, handler: (...args: unknown[]) => void): void {
+      handlers.set(event, [...(handlers.get(event) ?? []), handler]);
+    },
+  };
+}
+
+describe("installFatalProcessBarrier", () => {
+  it("logs a fatal-exit line with error meta and exits 1 when a throw happens before the server exists", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+    const crash = new TypeError("cannot read properties of null");
+
+    installFatalProcessBarrier({ exit, isWarm: false, log, process: host });
+    host.emit("uncaughtException", crash);
+
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+    expect(log).toHaveBeenCalledTimes(1);
+    const [message, meta] = log.mock.calls[0] ?? [];
+    expect(message).toContain(`event=${FATAL_EXIT_EVENT}`);
+    expect(message).toContain("handler=uncaughtException");
+    expect(message).toContain("exit_code=1");
+    expect(meta).toEqual({
+      error: {
+        kind: "TypeError",
+        message: "cannot read properties of null",
+        stack: crash.stack,
+      },
+    });
+  });
+
+  it("serializes a plain-object rejection so the message is not [object Object]", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+    const reason = { code: 8, message: "[internal] Connection closed" };
+
+    installFatalProcessBarrier({ exit, isWarm: false, log, process: host });
+    host.emit("unhandledRejection", reason);
+
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+    const [, meta] = log.mock.calls[0] ?? [];
+    expect(meta).toEqual({
+      error: {
+        kind: "Unknown Error",
+        message: JSON.stringify(reason),
+      },
+    });
+  });
+
+  it("serializes a BigInt field in a non-Error rejection and still exits 1", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+    const reason = { id: 8n, message: "closed" };
+
+    installFatalProcessBarrier({ exit, isWarm: false, log, process: host });
+    host.emit("unhandledRejection", reason);
+
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+    const [message, meta] = log.mock.calls[0] ?? [];
+    expect(String(message)).toContain(`event=${FATAL_EXIT_EVENT}`);
+    expect(meta).toEqual({
+      error: {
+        kind: "Unknown Error",
+        message: '{"id":"8","message":"closed"}',
+      },
+    });
+  });
+
+  it("still writes the fatal-exit line and exits 1 when toJSON throws", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+    const reason = {
+      toJSON() {
+        throw new Error("cannot serialize");
+      },
+    };
+
+    installFatalProcessBarrier({ exit, isWarm: false, log, process: host });
+    host.emit("unhandledRejection", reason);
+
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+    expect(log).toHaveBeenCalledTimes(1);
+    const [message, meta] = log.mock.calls[0] ?? [];
+    expect(String(message)).toContain(`event=${FATAL_EXIT_EVENT}`);
+    expect(meta).toEqual({
+      error: {
+        kind: "Unknown Error",
+        message: "[object Object]",
+      },
+    });
+    expect(isFatalProcessHandled(host)).toBe(true);
+  });
+
+  it("still exits 1 when the fatal log itself throws after the barrier is marked handled", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+
+    installFatalProcessBarrier({
+      exit,
+      isWarm: false,
+      log: () => {
+        throw new Error("logger exploded");
+      },
+      process: host,
+    });
+    host.emit("uncaughtException", new Error("boom"));
+
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+    expect(isFatalProcessHandled(host)).toBe(true);
+  });
+
+  it("labels an unhandled rejection as a rejection, not an exception", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+
+    installFatalProcessBarrier({ exit, isWarm: false, log, process: host });
+    host.emit("unhandledRejection", new Error("upstream timed out"));
+
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+    const [message] = log.mock.calls[0] ?? [];
+    expect(message).toContain("handler=unhandledRejection");
+  });
+
+  it("writes one fatal-exit line for a burst of crashes", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+
+    installFatalProcessBarrier({ exit, isWarm: false, log, process: host });
+    host.emit("uncaughtException", new Error("first"));
+    host.emit("unhandledRejection", new Error("second"));
+    host.emit("uncaughtException", new Error("third"));
+
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledTimes(1));
+    expect(log).toHaveBeenCalledTimes(1);
+    expect(String(log.mock.calls[0]?.[0])).toContain(
+      "handler=uncaughtException",
+    );
+  });
+
+  it("arms one set of handlers however many times it is installed", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+
+    installFatalProcessBarrier({ exit, isWarm: false, log, process: host });
+    installFatalProcessBarrier({ exit, isWarm: false, log, process: host });
+    host.emit("uncaughtException", new Error("boom"));
+
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledTimes(1));
+    expect(log).toHaveBeenCalledTimes(1);
+  });
+
+  it("still exits fatally when isNonFatal throws, and logs the predicate failure", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+    const predicateError = new Error("predicate exploded");
+
+    installFatalProcessBarrier({
+      exit,
+      isNonFatal: () => {
+        throw predicateError;
+      },
+      log,
+      process: host,
+    });
+    host.emit("unhandledRejection", new Error("closed"));
+
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+    expect(log).toHaveBeenCalledTimes(2);
+    const [predicateMessage, predicateMeta] = log.mock.calls[0] ?? [];
+    expect(String(predicateMessage)).not.toContain(`event=${FATAL_EXIT_EVENT}`);
+    expect(predicateMeta).toEqual({
+      error: {
+        kind: "Error",
+        message: "predicate exploded",
+        stack: predicateError.stack,
+      },
+    });
+    const [fatalMessage] = log.mock.calls[1] ?? [];
+    expect(String(fatalMessage)).toContain(`event=${FATAL_EXIT_EVENT}`);
+  });
+
+  it("keeps the process alive when isNonFatal says the reason is recoverable", () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+
+    installFatalProcessBarrier({
+      exit,
+      isNonFatal: (_handler, reason) =>
+        reason instanceof Error && reason.message === "closed",
+      log,
+      process: host,
+    });
+    host.emit("unhandledRejection", new Error("closed"));
+
+    expect(exit).not.toHaveBeenCalled();
+    expect(log).not.toHaveBeenCalled();
+  });
+
+  it("upgrades onFatal on an already-armed host without a second listener", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+    const onFatal = vi.fn();
+
+    installFatalProcessBarrier({ exit, isWarm: false, log, process: host });
+    installFatalProcessBarrier({ onFatal, process: host });
+    host.emit("uncaughtException", new Error("boom"));
+
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+    expect(onFatal).toHaveBeenCalledTimes(1);
+    expect(onFatal.mock.calls[0]?.[0]).toBe("uncaughtException");
+  });
+
+  it("reports a crash as exit code 1 so graceful shutdown cannot claim 0", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+
+    installFatalProcessBarrier({
+      exit,
+      log: () => undefined,
+      onFatal: () => undefined,
+      process: host,
+    });
+    expect(fatalAwareExitCode(host)).toBe(0);
+    host.emit("uncaughtException", new Error("boom"));
+    await vi.waitFor(() => expect(isFatalProcessHandled(host)).toBe(true));
+    expect(fatalAwareExitCode(host)).toBe(1);
+  });
+});
+
+describe("installFatalProcessBarrier across CLI module copies", () => {
+  afterEach(() => {
+    vi.resetModules();
+  });
+
+  it("shares hooks across module instances, as when bin/run.js and the esbuild bundle each load their own", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+    const onFatal = vi.fn();
+
+    const early = await import("./fatal-process-barrier.mjs");
+    early.installFatalProcessBarrier({
+      exit,
+      isWarm: false,
+      log,
+      process: host,
+    });
+    expect(host.listenerCount("uncaughtException")).toBe(1);
+    expect(host.listenerCount("unhandledRejection")).toBe(1);
+
+    vi.resetModules();
+    const later = await import("./fatal-process-barrier.mjs");
+    later.installFatalProcessBarrier({
+      exit,
+      isNonFatal: (_handler, reason) =>
+        reason instanceof Error && reason.message === "closed",
+      log,
+      onFatal,
+      process: host,
+    });
+
+    expect(host.listenerCount("uncaughtException")).toBe(1);
+    expect(host.listenerCount("unhandledRejection")).toBe(1);
+
+    host.emit("unhandledRejection", new Error("closed"));
+    expect(exit).not.toHaveBeenCalled();
+    expect(log).not.toHaveBeenCalled();
+    expect(onFatal).not.toHaveBeenCalled();
+
+    host.emit("uncaughtException", new Error("boom"));
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+    expect(onFatal).toHaveBeenCalledTimes(1);
+    expect(log).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("installEarlyFatalProcessBarrier in a real Node process", () => {
+  it("writes the fatal-exit token and stack to stderr before exiting 1", () => {
+    const fixture = fileURLToPath(
+      new URL("./fatal-process-barrier.spawn-fixture.mts", import.meta.url),
+    );
+    const require = createRequire(
+      fileURLToPath(new URL("../../package.json", import.meta.url)),
+    );
+    const tsx = require.resolve("tsx");
+    const result = spawnSync(process.execPath, ["--import", tsx, fixture], {
+      encoding: "utf8",
+      env: { ...process.env, NODE_OPTIONS: "" },
+      timeout: 30_000,
+    });
+
+    const output = `${result.stdout}${result.stderr}`;
+    expect(result.status).toBe(1);
+    expect(output).toContain(`event=${FATAL_EXIT_EVENT}`);
+    expect(output).toContain("handler=uncaughtException");
+    expect(output).toContain("spawn-fixture crash");
+    expect(output).toMatch(/TypeError/);
+  });
+});

package/src/telemetry/logging.ts

@@ -214,7 +214,7 @@ export function getErrorMeta(error: unknown): ErrorMeta {
   return {
     error: {
       kind: "Unknown Error",
-      message: safeStringify(error) ?? String(error),
+      message: safeStringify(error),
     },
   };
 }

package/src/telemetry/safe-stringify.ts

@@ -1,3 +1,11 @@
+function fallbackString(value: unknown): string {
+  try {
+    return String(value);
+  } catch {
+    return "[unserializable]";
+  }
+}
+
 export function safeStringify(obj: unknown): string {
   if (obj === null || obj === undefined) {
     return String(obj);
@@ -9,15 +17,22 @@ export function safeStringify(obj: unknown): string {
     return String(obj);
   }
 
-  const seen = new WeakSet();
-  return JSON.stringify(obj, (_key, value) => {
-    if (value === null || typeof value !== "object") {
+  const seen = new WeakSet<object>();
+  try {
+    return JSON.stringify(obj, (_key, value: unknown) => {
+      if (typeof value === "bigint") {
+        return value.toString();
+      }
+      if (value === null || typeof value !== "object") {
+        return value;
+      }
+      if (seen.has(value)) {
+        return "[Circular]";
+      }
+      seen.add(value);
       return value;
-    }
-    if (seen.has(value)) {
-      return "[Circular]";
-    }
-    seen.add(value);
-    return value;
-  });
+    });
+  } catch {
+    return fallbackString(obj);
+  }
 }

package/test/safe-stringify.test.mts

@@ -15,4 +15,29 @@ describe("safeStringify", () => {
     obj.self = obj;
     expect(safeStringify(obj)).toBe('{"a":1,"self":"[Circular]"}');
   });
+
+  it("does not throw on BigInt fields", () => {
+    expect(safeStringify({ id: 8n })).toBe('{"id":"8"}');
+  });
+
+  it("does not throw when toJSON throws", () => {
+    const obj = {
+      toJSON() {
+        throw new Error("cannot serialize");
+      },
+    };
+    expect(safeStringify(obj)).toBe("[object Object]");
+  });
+
+  it("does not throw when both toJSON and toString throw", () => {
+    const obj = {
+      toJSON() {
+        throw new Error("cannot serialize");
+      },
+      toString() {
+        throw new Error("cannot stringify");
+      },
+    };
+    expect(safeStringify(obj)).toBe("[unserializable]");
+  });
 });