@superblocksteam/sdk 2.0.132 → 2.0.133

package/dist/dev-utils/fatal-exit.test.mjs

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { buildFatalExitLog, FATAL_EXIT_EVENT, parseIsWarm, } from "./fatal-exit.mjs";
+import { buildFatalExitLog, FATAL_EXIT_EVENT, isRecoverableShutdownError, parseIsWarm, } from "./fatal-exit.mjs";
 describe("parseIsWarm", () => {
     it("treats the same truthy spellings as the entrypoint shell", () => {
         for (const value of ["true", "1", "yes", "on", "TRUE", "Yes", " on "]) {
@@ -65,4 +65,41 @@ describe("buildFatalExitLog", () => {
         expect(line).toBe("Dev server fatal exit event=dev_server_fatal_exit handler=uncaughtException exit_code=1 signal=none is_warm=false");
     });
 });
+describe("isRecoverableShutdownError", () => {
+    it("matches the connection-closed SocketError codes (8 and 10)", () => {
+        // The exact object socket.ts rejects pending requests with on an abnormal
+        // close, plus the SocketErrorException shape for a request-after-close.
+        expect(isRecoverableShutdownError({
+            code: 8,
+            message: "[internal] Connection closed",
+        })).toBe(true);
+        expect(isRecoverableShutdownError({
+            code: 10,
+            message: "[internal] Connection closed",
+        })).toBe(true);
+    });
+    it("matches Vite's ERR_CLOSED_SERVER (a string code, raced against close)", () => {
+        expect(isRecoverableShutdownError({
+            code: "ERR_CLOSED_SERVER",
+            message: "The server is being restarted or closed.",
+        })).toBe(true);
+    });
+    it("does not match other socket error codes (those are genuine faults)", () => {
+        // 2 = unknown method, 3 = handler exception, 7 = no-response timeout.
+        for (const code of [2, 3, 7]) {
+            expect(isRecoverableShutdownError({ code, message: "boom" })).toBe(false);
+        }
+    });
+    it("does not match plain errors or non-error shapes", () => {
+        expect(isRecoverableShutdownError(new Error("boom"))).toBe(false);
+        expect(isRecoverableShutdownError(undefined)).toBe(false);
+        expect(isRecoverableShutdownError(null)).toBe(false);
+        expect(isRecoverableShutdownError("Connection closed")).toBe(false);
+        expect(isRecoverableShutdownError({ message: "no code" })).toBe(false);
+        // A numeric code as a string ("8") is not our socket code, and an unrelated
+        // string code is not Vite's — neither is recoverable.
+        expect(isRecoverableShutdownError({ code: "8" })).toBe(false);
+        expect(isRecoverableShutdownError({ code: "ERR_OTHER" })).toBe(false);
+    });
+});
 //# sourceMappingURL=fatal-exit.test.mjs.map

package/dist/dev-utils/fatal-exit.test.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"fatal-exit.test.mjs","sourceRoot":"","sources":["../../src/dev-utils/fatal-exit.test.mts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fatal-exit.test.mjs","sourceRoot":"","sources":["../../src/dev-utils/fatal-exit.test.mts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superblocksteam/sdk",
-  "version": "2.0.132",
+  "version": "2.0.133",
   "description": "Superblocks JS SDK",
   "homepage": "https://www.superblocks.com",
   "license": "Superblocks Community Software License",
@@ -48,11 +48,11 @@
     "vite-tsconfig-paths": "^6.0.4",
     "winston": "^3.17.0",
     "yaml": "^2.7.1",
-    "@superblocksteam/library-shared": "2.0.132",
-    "@superblocksteam/shared": "0.9593.0",
-    "@superblocksteam/telemetry": "2.0.132",
-    "@superblocksteam/vite-plugin-file-sync": "2.0.132",
-    "@superblocksteam/util": "2.0.132"
+    "@superblocksteam/library-shared": "2.0.133",
+    "@superblocksteam/shared": "0.9594.0",
+    "@superblocksteam/telemetry": "2.0.133",
+    "@superblocksteam/vite-plugin-file-sync": "2.0.133",
+    "@superblocksteam/util": "2.0.133"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",

package/src/dev-utils/dev-server-metrics.mts

@@ -96,6 +96,40 @@ export function normalizeBootKindTag(
     : "other";
 }
 
+/**
+ * Where a recoverable shutdown error was caught and suppressed instead of
+ * exiting the process. A closed enum so the `handler` label on
+ * `dev_server_recoverable_shutdown_error_total` stays low-cardinality.
+ */
+export type RecoverableShutdownHandler =
+  | "uncaughtException"
+  | "unhandledRejection"
+  | "vite_teardown";
+
+/**
+ * Allowlist of the close codes `isRecoverableShutdownError` matches: socket
+ * codes 8/10 (`packages/shared/src/socket/socket.ts`) and Vite's
+ * `ERR_CLOSED_SERVER`. Bounds the `code` metric label so the series count stays
+ * fixed even if the predicate ever lets an unexpected code through.
+ */
+const RECOVERABLE_SHUTDOWN_CODE_TAGS = new Set<string>([
+  "8",
+  "10",
+  "ERR_CLOSED_SERVER",
+]);
+
+/**
+ * Normalize a recoverable-shutdown error's `code` into a bounded metric-label
+ * value: known close codes pass through (keeping the diagnostic facet),
+ * anything else collapses to `"other"`, and a missing/non-primitive code maps
+ * to `"none"`.
+ */
+export function normalizeRecoverableShutdownCodeTag(code: unknown): string {
+  if (typeof code !== "number" && typeof code !== "string") return "none";
+  const tag = String(code);
+  return RECOVERABLE_SHUTDOWN_CODE_TAGS.has(tag) ? tag : "other";
+}
+
 /** Dev-server endpoints that produce per-request metrics. */
 export type DevServerEndpoint =
   | "_sb_health"
@@ -408,6 +442,39 @@ class DevServerMetrics {
     });
   }
 
+  /**
+   * Records a recoverable shutdown error that was suppressed (logged at warn,
+   * process left alive) instead of triggering a fatal exit. This is the
+   * alertable replacement for the `dev_server_fatal_exit` log token the old
+   * fatal path emitted: without it, the only way to see these errors (or notice
+   * their rate regressing) is a log search.
+   *
+   * Both labels are low-cardinality: `handler` is a closed enum, and the error's
+   * `code` is normalized to the known socket / Vite close codes (or
+   * `other`/`none`).
+   */
+  recordRecoverableShutdownError(
+    handler: RecoverableShutdownHandler,
+    reason: unknown,
+  ): void {
+    const code =
+      typeof reason === "object" && reason !== null && "code" in reason
+        ? (reason as { code: unknown }).code
+        : undefined;
+    const labels = {
+      handler,
+      code: normalizeRecoverableShutdownCodeTag(code),
+    };
+    this.record(() => {
+      getMeter()
+        .createCounter("dev_server_recoverable_shutdown_error_total", {
+          description:
+            "Count of recoverable shutdown errors suppressed instead of exiting, by handler and close code.",
+        })
+        .add(1, labels);
+    });
+  }
+
   /**
    * Records an ENOSPC disk-recovery attempt and its outcome. Lets dashboards
    * and alerts answer "how often is the live-edit PVC filling up, and is

package/src/dev-utils/dev-server-metrics.test.mts

@@ -3,6 +3,7 @@ import { describe, it, expect } from "vitest";
 import {
   normalizeBootKindTag,
   normalizeNpmErrorCodeTag,
+  normalizeRecoverableShutdownCodeTag,
 } from "./dev-server-metrics.mjs";
 
 describe("normalizeBootKindTag (metric cardinality bound)", () => {
@@ -59,3 +60,28 @@ describe("normalizeNpmErrorCodeTag (metric cardinality bound)", () => {
     expect(normalizeNpmErrorCodeTag("")).toBe("none");
   });
 });
+
+describe("normalizeRecoverableShutdownCodeTag (metric cardinality bound)", () => {
+  it("passes through the known socket / Vite close codes", () => {
+    // Numeric socket codes and Vite's string code are stringified for the label.
+    expect(normalizeRecoverableShutdownCodeTag(8)).toBe("8");
+    expect(normalizeRecoverableShutdownCodeTag(10)).toBe("10");
+    expect(normalizeRecoverableShutdownCodeTag("ERR_CLOSED_SERVER")).toBe(
+      "ERR_CLOSED_SERVER",
+    );
+  });
+
+  it("maps any other code to 'other' (cardinality guard)", () => {
+    // Should the predicate ever let an unexpected code through, the label must
+    // not mint a new time series per distinct value.
+    expect(normalizeRecoverableShutdownCodeTag(7)).toBe("other");
+    expect(normalizeRecoverableShutdownCodeTag("ECONNRESET")).toBe("other");
+    expect(normalizeRecoverableShutdownCodeTag("`;rm -rf /#")).toBe("other");
+  });
+
+  it("maps a missing or non-primitive code to 'none'", () => {
+    expect(normalizeRecoverableShutdownCodeTag(undefined)).toBe("none");
+    expect(normalizeRecoverableShutdownCodeTag(null)).toBe("none");
+    expect(normalizeRecoverableShutdownCodeTag({})).toBe("none");
+  });
+});

package/src/dev-utils/dev-server.mts

@@ -65,7 +65,11 @@ import {
   type DevServerFailureType,
   devServerMetrics,
 } from "./dev-server-metrics.mjs";
-import { buildFatalExitLog, parseIsWarm } from "./fatal-exit.mjs";
+import {
+  buildFatalExitLog,
+  isRecoverableShutdownError,
+  parseIsWarm,
+} from "./fatal-exit.mjs";
 import {
   formatViteDevServerStartedLog,
   logViteBuildError,
@@ -626,7 +630,7 @@ export async function createDevServer({
   let isViteServerInitialized = false;
   let viteResolve: (value: void | PromiseLike<void>) => void;
   let viteReject: (reason?: any) => void;
-  let vitePromise = new Promise((resolve, reject) => {
+  const vitePromise = new Promise((resolve, reject) => {
     viteResolve = resolve;
     viteReject = reject;
   });
@@ -661,6 +665,68 @@ export async function createDevServer({
     },
   });
 
+  // Single authoritative Vite teardown. Both the graceful-shutdown path and the
+  // /_sb_disconnect restart path go through here so the ordering that prevents
+  // ERR_CLOSED_SERVER / socket-close races lives in one place: stop new work
+  // FIRST (flip the initialized flag so the request gate rejects, drop the Vite
+  // middleware from the router, cancel pending sync), THEN close. Nothing calls
+  // into Vite after close() that way, so it cannot throw "request after close".
+  // A recoverable close error is logged, not rethrown — the global fatal handler
+  // treats the same shapes as non-fatal, but swallowing here keeps a benign
+  // teardown race off the error path entirely (APPS-4797).
+  //
+  // Single-flight guard: a SIGTERM graceful shutdown can land while a
+  // /_sb_disconnect restart is already awaiting close(), and both reach the
+  // worker with viteCreationResults still set (it is nulled only after close()
+  // resolves). Without the guard both would close() and dispose() the same Vite
+  // instance: the second close() throws ERR_CLOSED_SERVER and dispose() runs
+  // twice. Sharing one in-flight promise makes the second caller await the first
+  // teardown instead of starting its own.
+  let viteClosePromise: Promise<void> | null = null;
+  function closeViteServer(): Promise<void> {
+    if (!viteClosePromise) {
+      viteClosePromise = teardownViteServer().finally(() => {
+        viteClosePromise = null;
+      });
+    }
+    return viteClosePromise;
+  }
+
+  async function teardownViteServer(): Promise<void> {
+    if (!viteCreationResults) {
+      return;
+    }
+    const { viteServer, dispose, routeIndex } = viteCreationResults;
+    isViteServerInitialized = false;
+    if (routeIndex !== -1) {
+      // Remove the Vite middleware so express stops handing requests to a server
+      // we are about to close. `app._router` is untyped express internals; this
+      // cast matches the existing usage in this file.
+      (app._router as IRouter).stack.splice(routeIndex, 1);
+    }
+    // Cancel pending file sync as part of teardown. This only runs when Vite is
+    // up (the guard above early-returns otherwise). The restart path used to call
+    // this unconditionally, but it exits the process immediately afterward, so an
+    // uncancelled in-flight sync cannot persist; when viteCreationResults is
+    // already null the skipped call would have been a no-op anyway.
+    syncService?.cancelPendingSync();
+    try {
+      await viteServer.close();
+    } catch (e) {
+      if (!isRecoverableShutdownError(e)) {
+        throw e;
+      }
+      logger.warn(
+        "Ignoring recoverable error during Vite teardown",
+        getErrorMeta(e),
+      );
+      devServerMetrics.recordRecoverableShutdownError("vite_teardown", e);
+    } finally {
+      dispose();
+      viteCreationResults = null;
+    }
+  }
+
   async function runGracefulShutdown({
     logger,
     serverInitiated,
@@ -688,13 +754,7 @@ export async function createDevServer({
       });
       // Cleanup AI service cache
       await aiService?.removeIntegrationCache();
-      // Cleanup the vite server
-      if (viteCreationResults) {
-        await viteCreationResults.viteServer?.close();
-        viteCreationResults.dispose();
-        viteCreationResults = null;
-        isViteServerInitialized = false;
-      }
+      await closeViteServer();
     } catch (e) {
       logger.error(`Error during graceful shutdown: ${e}`);
     } finally {
@@ -960,28 +1020,13 @@ export async function createDevServer({
       if (isRestart) {
         logger.info("Pausing dev server while restarting");
         lockService?.setIsRestarting();
-        syncService?.cancelPendingSync();
         // Invalidate chat session cache to reload fresh chat messages after checkpoint restore
         aiService?.chatSessionStore.invalidateCache();
-        if (viteCreationResults) {
-          const index = viteCreationResults.routeIndex;
-          if (index !== -1) {
-            // Remove the vite server middleware from the express app - this is a workaround to avoid
-            // the vite server middleware being called after the dev server is closed
-            (app._router as IRouter).stack.splice(index, 1);
-          }
-
-          await viteCreationResults.viteServer?.close();
-          viteCreationResults.dispose();
-          viteCreationResults = null;
-          vitePromise = new Promise((resolve, reject) => {
-            viteResolve = resolve;
-            viteReject = reject;
-          });
-          vitePromise.catch(() => {});
-          isViteServerInitialized = false;
-        }
+        await closeViteServer();
         res.send("ok");
+        // RESTART_EXIT_CODE tells the supervisor to respawn, and this runs
+        // synchronously below (no await), so the next /_sb_connect is served by
+        // the fresh process. There is nothing to re-arm in this dying one.
         process.exit(RESTART_EXIT_CODE);
       } else {
         logger.info("Shutting down dev server");
@@ -1159,6 +1204,26 @@ export async function createDevServer({
     if (fatalExitHandled) {
       return;
     }
+    // A connection or server we depend on closing mid-flight (socket code 8/10,
+    // or Vite's ERR_CLOSED_SERVER from a call racing an in-place restart) is
+    // expected and recoverable, so it must not kill the pod. See
+    // isRecoverableShutdownError for the shapes and why their owning paths
+    // already treat them as non-fatal.
+    if (isRecoverableShutdownError(error)) {
+      logger.warn(
+        "Ignoring recoverable shutdown error (uncaughtException)",
+        getErrorMeta(error),
+      );
+      // Keep an alertable signal. Suppressing the fatal exit drops the
+      // dev_server_fatal_exit log token, so this counter is the only
+      // dashboard-queryable way to see these (and catch a regression in their
+      // rate) without a log search.
+      devServerMetrics.recordRecoverableShutdownError(
+        "uncaughtException",
+        error,
+      );
+      return;
+    }
     fatalExitHandled = true;
     // Write the fatal-exit line first, and synchronously, so the reason reaches
     // the logs before anything else runs. Shutdown below may finish first and
@@ -1193,6 +1258,22 @@ export async function createDevServer({
     if (fatalExitHandled) {
       return;
     }
+    // See the uncaughtException handler above: a connection/server close racing
+    // an in-place restart (socket code 8/10 or Vite's ERR_CLOSED_SERVER) is
+    // recoverable and must not wedge the pod (APPS-4797).
+    if (isRecoverableShutdownError(reason)) {
+      logger.warn(
+        "Ignoring recoverable shutdown rejection (unhandledRejection)",
+        getErrorMeta(reason),
+      );
+      // Alertable signal in place of the suppressed dev_server_fatal_exit log
+      // token; see the uncaughtException handler above.
+      devServerMetrics.recordRecoverableShutdownError(
+        "unhandledRejection",
+        reason,
+      );
+      return;
+    }
     fatalExitHandled = true;
     logger.error(
       buildFatalExitLog({ handler: "unhandledRejection", exitCode: 1, isWarm }),

package/src/dev-utils/fatal-exit.mts

@@ -111,3 +111,54 @@ export function buildFatalExitLog(fields: FatalExitFields): string {
     `is_warm=${fields.isWarm}`,
   ].join(" ");
 }
+
+/**
+ * Error `code`s that mean "a connection or server we depend on was torn down
+ * while a request was in flight", not "the process is broken". They are
+ * expected during an in-place dev-server restart / reconnect and are
+ * recoverable, so the process-level fatal handler must not kill the pod for
+ * them. Two layers throw two different shapes, both benign here:
+ *
+ *   8                    `packages/shared/src/socket/socket.ts` rejects every
+ *                        pending request with `{ code: 8, message: '[internal]
+ *                        Connection closed' }` when the server WebSocket closes
+ *                        unexpectedly (server-side teardown, abnormal 1006).
+ *   10                   a socket `request()` issued after the close handshake.
+ *   "ERR_CLOSED_SERVER"  Vite throws this from `transformRequest` / module-graph
+ *                        work that lands after `ViteDevServer.close()`. Our
+ *                        in-place restart closes Vite, so an in-flight
+ *                        file-sync/HMR call can race the close. Note the string
+ *                        code: it comes from Vite, not from our socket layer.
+ *
+ * The editor/library socket path and Vite's own request path already treat
+ * these as expected; the fire-and-forget callers that reach the process-level
+ * handler do not, which is why this predicate exists (APPS-4797 / APPS-4667).
+ *
+ * Load-bearing assumption: this is a purely structural `code` match, so it
+ * trusts that the numeric codes 8 and 10 are produced ONLY by our socket layer
+ * (`packages/shared/src/socket/socket.ts`) and are not reused by another source
+ * for an unrelated, genuinely-fatal error. libuv/Node system error codes are
+ * negative or string (`EPIPE`, `-32`), so they never collide. gRPC status codes
+ * DO collide numerically (8 = RESOURCE_EXHAUSTED, 10 = ABORTED), but this
+ * process runs only the socket client and Vite, with no gRPC rejection path
+ * reaching the process-level handler, so the match is safe today. If a gRPC
+ * client is ever added here, gate the numeric codes on a discriminating field
+ * (e.g. the `'[internal]'` message prefix) instead of widening the set. The
+ * string `ERR_CLOSED_SERVER` is already Vite-specific.
+ */
+const RECOVERABLE_SHUTDOWN_CODES = new Set<number | string>([
+  8,
+  10,
+  "ERR_CLOSED_SERVER",
+]);
+
+export function isRecoverableShutdownError(reason: unknown): boolean {
+  if (typeof reason !== "object" || reason === null || !("code" in reason)) {
+    return false;
+  }
+  const { code } = reason as { code: unknown };
+  if (typeof code !== "number" && typeof code !== "string") {
+    return false;
+  }
+  return RECOVERABLE_SHUTDOWN_CODES.has(code);
+}

package/src/dev-utils/fatal-exit.test.mts

@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";
 import {
   buildFatalExitLog,
   FATAL_EXIT_EVENT,
+  isRecoverableShutdownError,
   parseIsWarm,
 } from "./fatal-exit.mjs";
 
@@ -79,3 +80,50 @@ describe("buildFatalExitLog", () => {
     );
   });
 });
+
+describe("isRecoverableShutdownError", () => {
+  it("matches the connection-closed SocketError codes (8 and 10)", () => {
+    // The exact object socket.ts rejects pending requests with on an abnormal
+    // close, plus the SocketErrorException shape for a request-after-close.
+    expect(
+      isRecoverableShutdownError({
+        code: 8,
+        message: "[internal] Connection closed",
+      }),
+    ).toBe(true);
+    expect(
+      isRecoverableShutdownError({
+        code: 10,
+        message: "[internal] Connection closed",
+      }),
+    ).toBe(true);
+  });
+
+  it("matches Vite's ERR_CLOSED_SERVER (a string code, raced against close)", () => {
+    expect(
+      isRecoverableShutdownError({
+        code: "ERR_CLOSED_SERVER",
+        message: "The server is being restarted or closed.",
+      }),
+    ).toBe(true);
+  });
+
+  it("does not match other socket error codes (those are genuine faults)", () => {
+    // 2 = unknown method, 3 = handler exception, 7 = no-response timeout.
+    for (const code of [2, 3, 7]) {
+      expect(isRecoverableShutdownError({ code, message: "boom" })).toBe(false);
+    }
+  });
+
+  it("does not match plain errors or non-error shapes", () => {
+    expect(isRecoverableShutdownError(new Error("boom"))).toBe(false);
+    expect(isRecoverableShutdownError(undefined)).toBe(false);
+    expect(isRecoverableShutdownError(null)).toBe(false);
+    expect(isRecoverableShutdownError("Connection closed")).toBe(false);
+    expect(isRecoverableShutdownError({ message: "no code" })).toBe(false);
+    // A numeric code as a string ("8") is not our socket code, and an unrelated
+    // string code is not Vite's — neither is recoverable.
+    expect(isRecoverableShutdownError({ code: "8" })).toBe(false);
+    expect(isRecoverableShutdownError({ code: "ERR_OTHER" })).toBe(false);
+  });
+});