@superblocksteam/sdk 2.0.110 → 2.0.111

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

@@ -1,3 +1,5 @@
+import * as child_process from "node:child_process";
+import { existsSync } from "node:fs";
 import type http from "node:http";
 import net from "node:net";
 import os from "node:os";
@@ -8,7 +10,7 @@ import cors from "cors";
 import express from "express";
 import type { IRouter, RequestHandler } from "express";
 import { createLogger, createServer, loadEnv } from "vite";
-import type { HmrOptions } from "vite";
+import type { HmrOptions, Plugin, UserConfig } from "vite";
 import type { ViteDevServer } from "vite";
 import tsconfigPaths from "vite-tsconfig-paths";
 
@@ -51,6 +53,72 @@ import { ddRumPlugin } from "./vite-plugin-dd-rum.mjs";
 
 const tracer = getTracer();
 
+function reactPlugin() {
+  return react({
+    babel: {
+      plugins: [
+        [
+          import.meta.resolve("@babel/plugin-proposal-decorators"),
+          { version: "2023-11" },
+        ],
+      ],
+    },
+  });
+}
+
+/**
+ * Shared `optimizeDeps` config for both pre-warm and activation Vite servers.
+ *
+ * Vite includes the stringified `optimizeDeps` config in its dep cache hash,
+ * so both servers must use identical config or activation will discard the
+ * pre-warmed cache and re-run full dependency optimization.
+ */
+const OPTIMIZE_DEPS_CONFIG: UserConfig["optimizeDeps"] = {
+  esbuildOptions: {
+    supported: {
+      destructuring: true,
+    },
+  },
+};
+
+/**
+ * Builds the Vite plugin list shared by both pre-warm and activation.
+ *
+ * Vite hashes plugin names to validate the dep optimization cache, so
+ * both paths must produce the same list. Call `fileSyncVitePlugin()`
+ * with no args for the noop version during pre-warm.
+ */
+function vitePlugins(
+  root: string,
+  opts: {
+    fileSync: Plugin[];
+    ddRum?: {
+      clientToken: string;
+      applicationId: string;
+      env: string;
+      version: string;
+    };
+  },
+) {
+  return [
+    tsconfigPaths(),
+    sdkApiEntryPointPlugin(root),
+    customComponentsPlugin(),
+    opts.fileSync,
+    buildManifestStubPlugin(),
+    reactPlugin(),
+    createLucideReactImportOptimizer(),
+    ddRumPlugin(
+      opts.ddRum ?? {
+        clientToken: "",
+        applicationId: "",
+        env: "",
+        version: "",
+      },
+    ),
+  ];
+}
+
 export const RESTART_EXIT_CODE = 98;
 
 function getJwksUriWithBaseUrl(superblocksBaseUrl?: string): string {
@@ -112,6 +180,13 @@ interface CreateDevServerOptions {
   sdk?: SuperblocksSdk;
   /** Explicitly provided base URL from the CLI; preferred over auth-file reads. */
   superblocksBaseUrl?: string;
+  /**
+   * Pre-existing HTTP server from warm standby mode. When provided, the dev
+   * server attaches its Express app as a request handler on this server instead
+   * of creating a new one and calling listen(). This avoids the port gap that
+   * causes 502s from the gateway during the warm -> full server transition.
+   */
+  existingServer?: http.Server;
 }
 
 let httpServer: http.Server;
@@ -131,6 +206,7 @@ export async function createDevServer({
   port,
   sdk,
   superblocksBaseUrl: explicitBaseUrl,
+  existingServer,
 }: CreateDevServerOptions) {
   const logger = getLogger(loggerOverride);
   if (httpServer) {
@@ -167,6 +243,12 @@ export async function createDevServer({
     viteResolve = resolve;
     viteReject = reject;
   });
+  // Attach a no-op catch so that if viteReject() fires before any request
+  // handler awaits vitePromise (e.g. Vite fails during eager init, before
+  // /_sb_connect), the process doesn't crash with UnhandledPromiseRejection.
+  // The actual error is still logged via the .then(_, onRejected) handler
+  // attached at the viteStartPromise call site.
+  vitePromise.catch(() => {});
 
   async function gracefulShutdown({
     logger,
@@ -384,50 +466,21 @@ export async function createDevServer({
       }
     }
 
-    logger.info("Initializing dev server...");
-    if (isViteServerInitialized) {
-      logger.info("Dev server already initialized");
+    logger.info("Received connect request, waiting for vite server...");
+    // Vite is started eagerly after HTTP server listen (see below).
+    // Wait for it to be ready before responding.
+    try {
+      await vitePromise;
       res.send(JSON.stringify(healthResponse));
-      return;
+    } catch (e) {
+      logger.error(
+        "Vite server failed to initialize",
+        getErrorMeta(e as Error),
+      );
+      res
+        .status(500)
+        .send(JSON.stringify({ error: "Dev server failed to initialize" }));
     }
-    logger.info("Starting dev server");
-    isViteServerInitialized = true;
-
-    const featureFlags = await sdk?.getFeatureFlagsForCurrentUser();
-
-    // TODO(code-mode): should this include any validation checks, such as getting a token?
-
-    startVite({
-      port,
-      app,
-      root,
-      mode,
-      fsOperationQueue,
-      syncService,
-      lockService,
-      aiService,
-      gitService,
-      activateGitService,
-      snapshotManager,
-      checkAuthorization,
-      logger: loggerOverride,
-      httpServer,
-      superblocksBaseUrl: explicitBaseUrl || localToken?.superblocksBaseUrl,
-      features: {
-        enableSessionRecording: featureFlags?.enableSessionRecording() ?? false,
-      },
-    }).then(
-      (result) => {
-        logger.info("Dev server initialized");
-        viteResolve();
-        viteCreationResults = result;
-        res.send(JSON.stringify(healthResponse));
-      },
-      (e) => {
-        logger.error("Error initializing dev server", getErrorMeta(e));
-        viteReject(e);
-      },
-    );
   });
 
   app.post("/_sb_disconnect", authHandler, async (req, res) => {
@@ -457,6 +510,7 @@ export async function createDevServer({
             viteResolve = resolve;
             viteReject = reject;
           });
+          vitePromise.catch(() => {});
           isViteServerInitialized = false;
         }
         res.send("ok");
@@ -500,8 +554,143 @@ export async function createDevServer({
         timeSinceLastActivityMs: lockService.timeSinceLastActivity,
       });
     } else {
-      logger.error("Lock service not found, rejecting request");
-      viteReject(new Error("Lock service not found, rejecting request"));
+      // Lock service may be undefined during warm pool activation (sync is
+      // deferred until the first /_sb_connect). Return a safe default instead
+      // of rejecting vitePromise which would crash the server.
+      // Use MAX_SAFE_INTEGER so idle-detection callers don't mistake this for recent activity.
+      res.json({
+        isUserActive: false,
+        connectedUsers: [],
+        timeSinceLastActivityMs: Number.MAX_SAFE_INTEGER,
+      });
+    }
+  });
+
+  // /_sb_persist: SABS POSTs a presigned S3 upload URL at teardown.
+  // This endpoint creates a tar+zstd archive of the workspace and uploads
+  // it directly to S3 via the presigned PUT URL. Registered on the Express
+  // app so it's available on ALL dev server instances (warm and cold-start, D-24).
+  let persistInProgress = false;
+  app.post("/_sb_persist", authHandler, async (req, res) => {
+    if (persistInProgress) {
+      res.status(409).json({ error: "persist already in progress" });
+      return;
+    }
+    persistInProgress = true;
+    const persistStart = Date.now();
+    try {
+      const { uploadURL } = req.body as { uploadURL: string };
+      if (!uploadURL) {
+        res.status(400).json({ error: "uploadURL required" });
+        return;
+      }
+
+      logger.info("/_sb_persist: archiving and uploading workspace to S3...");
+
+      // Create tar+zstd archive excluding .git/ and node_modules/.cache/
+      // then stream directly to S3 via presigned PUT URL.
+      const archive = await new Promise<Buffer>(
+        (resolveArchive, rejectArchive) => {
+          const tarProc = child_process.spawn(
+            "tar",
+            [
+              "cf",
+              "-",
+              "--exclude",
+              ".git",
+              "--exclude",
+              "node_modules/.cache",
+              "--exclude",
+              ".superblocks",
+              "-C",
+              process.cwd(),
+              ".",
+            ],
+            { stdio: ["ignore", "pipe", "pipe"] },
+          );
+          const zstdProc = child_process.spawn(
+            "zstd",
+            ["-1", "--no-progress"],
+            {
+              stdio: ["pipe", "pipe", "pipe"],
+            },
+          );
+
+          tarProc.stdout.pipe(zstdProc.stdin);
+
+          // Attach error handlers on the piped stdin. ChildProcess-level 'error'
+          // events don't catch stream errors like EPIPE from writing to a closed
+          // pipe if the downstream process crashes.
+          zstdProc.stdin.on("error", (err) => {
+            rejectArchive(new Error(`zstd stdin stream error: ${err.message}`));
+          });
+
+          const chunks: Buffer[] = [];
+          zstdProc.stdout.on("data", (chunk: Buffer) => chunks.push(chunk));
+
+          let stderr = "";
+          tarProc.stderr.on("data", (chunk: Buffer) => {
+            stderr += chunk.toString();
+          });
+          zstdProc.stderr.on("data", (chunk: Buffer) => {
+            stderr += chunk.toString();
+          });
+
+          let tarExitCode: number | null = null;
+          tarProc.on("close", (code) => {
+            tarExitCode = code;
+          });
+
+          zstdProc.on("close", (code) => {
+            if (code !== 0) {
+              rejectArchive(
+                new Error(`zstd compression failed (code ${code}): ${stderr}`),
+              );
+            } else if (tarExitCode !== null && tarExitCode !== 0) {
+              rejectArchive(
+                new Error(
+                  `tar archival failed (code ${tarExitCode}): ${stderr}`,
+                ),
+              );
+            } else {
+              resolveArchive(Buffer.concat(chunks));
+            }
+          });
+          tarProc.on("error", rejectArchive);
+          zstdProc.on("error", rejectArchive);
+        },
+      );
+
+      logger.info(
+        `/_sb_persist: archive created (${(archive.length / 1024 / 1024).toFixed(1)}MB) in ${Date.now() - persistStart}ms, uploading...`,
+      );
+
+      const uploadStart = Date.now();
+      const uploadResp = await fetch(uploadURL, {
+        method: "PUT",
+        body: archive,
+        headers: {
+          "Content-Type": "application/zstd",
+          "Content-Length": String(archive.length),
+        },
+        signal: AbortSignal.timeout(30_000),
+      });
+
+      if (!uploadResp.ok) {
+        throw new Error(
+          `S3 upload failed: ${uploadResp.status} ${uploadResp.statusText}`,
+        );
+      }
+
+      logger.info(
+        `/_sb_persist: uploaded in ${Date.now() - uploadStart}ms (total ${Date.now() - persistStart}ms)`,
+      );
+      res.status(200).json({ status: "uploaded" });
+    } catch (error) {
+      logger.error(`/_sb_persist failed: ${error}`);
+      res.status(500).json({ error: String(error) });
+    } finally {
+      persistInProgress = false;
     }
   });
 
@@ -533,9 +722,72 @@ export async function createDevServer({
     );
   });
 
-  logger.info(`Starting HTTP server on port ${port}`);
-  httpServer = await app.listen(port);
-  logger.info(`HTTP server started successfully on port ${port}`);
+  if (existingServer) {
+    // Warm standby mode: reuse the pre-existing HTTP server to avoid a port gap.
+    // Replace the warm server's request handler with the full Express app.
+    existingServer.removeAllListeners("request");
+    existingServer.on("request", app);
+    httpServer = existingServer;
+    logger.info(
+      `Attached full dev server to existing HTTP server on port ${port}`,
+    );
+  } else {
+    logger.info(`Starting HTTP server on port ${port}`);
+    httpServer = await app.listen(port);
+    logger.info(`HTTP server started successfully on port ${port}`);
+  }
+
+  // Start vite eagerly so it's ready (or nearly ready) by the time the editor
+  // connects via /_sb_connect. Previously vite was started lazily on first
+  // /_sb_connect, adding ~5s to perceived connection time.
+  if (!isViteServerInitialized) {
+    isViteServerInitialized = true;
+    logger.info("Eagerly starting vite server...");
+
+    const featureFlags = await sdk
+      ?.getFeatureFlagsForCurrentUser()
+      .catch((err: unknown) => {
+        logger.warn(`Failed to fetch feature flags, using defaults: ${err}`);
+        return undefined;
+      });
+
+    const viteStartPromise = startVite({
+      port,
+      app,
+      root,
+      mode,
+      fsOperationQueue,
+      syncService,
+      lockService,
+      aiService,
+      gitService,
+      activateGitService,
+      snapshotManager,
+      checkAuthorization,
+      logger: loggerOverride,
+      httpServer,
+      superblocksBaseUrl: explicitBaseUrl || localToken?.superblocksBaseUrl,
+      features: {
+        enableSessionRecording: featureFlags?.enableSessionRecording() ?? false,
+      },
+    });
+    // Note: vitePromise itself gets a no-op .catch() at its construction site
+    // (see lines ~179 / ~443) to prevent UnhandledPromiseRejection if Vite
+    // fails before any request awaits vitePromise. The actual error is logged
+    // below via the rejection branch of .then().
+    viteStartPromise.then(
+      (result) => {
+        logger.info("Vite server initialized eagerly");
+        viteResolve();
+        viteCreationResults = result;
+      },
+      (e) => {
+        logger.error("Error initializing vite server", getErrorMeta(e));
+        viteReject(e);
+      },
+    );
+  }
+
   return httpServer;
 }
 
@@ -653,13 +905,7 @@ async function startVite({
               mode,
               clearScreen: process.env.SUPERBLOCKS_CLI_ENV !== "local",
               customLogger: viteLogger,
-              optimizeDeps: {
-                esbuildOptions: {
-                  supported: {
-                    destructuring: true,
-                  },
-                },
-              },
+              optimizeDeps: OPTIMIZE_DEPS_CONFIG,
               server: {
                 middlewareMode: true,
                 watch: {
@@ -685,30 +931,9 @@ async function startVite({
                     )
                   : "undefined",
               },
-              plugins: [
-                tsconfigPaths(),
-                sdkApiEntryPointPlugin(root),
-                customComponentsPlugin(),
-                fileSyncPluginCreator.plugin,
-                // Add a virtual "stub" module for the build manifest
-                buildManifestStubPlugin(),
-                react({
-                  babel: {
-                    plugins: [
-                      // We will bring this back later
-                      // "babel-plugin-react-compiler",
-                      [
-                        import.meta
-                          .resolve("@babel/plugin-proposal-decorators"),
-                        {
-                          version: "2023-11",
-                        },
-                      ],
-                    ],
-                  },
-                }),
-                createLucideReactImportOptimizer(),
-                ddRumPlugin({
+              plugins: vitePlugins(root, {
+                fileSync: fileSyncPluginCreator.plugin,
+                ddRum: {
                   clientToken: env.SUPERBLOCKS_LIBRARY_DD_CLIENT_TOKEN ?? "",
                   applicationId:
                     env.SUPERBLOCKS_LIBRARY_DD_APPLICATION_ID ?? "",
@@ -717,8 +942,8 @@ async function startVite({
                   // CLI auto-upgrade still works - the caching changes in this PR only affect detection speed.
                   // Replace with dynamic library version injection once available.
                   version: "1.0.0",
-                }),
-              ],
+                },
+              }),
             });
             return server;
           } finally {
@@ -744,6 +969,58 @@ async function startVite({
   });
 }
 
+/**
+ * Pre-warm the Vite dependency cache by creating and immediately closing a
+ * minimal Vite server. This populates `node_modules/.vite/deps` with
+ * pre-bundled dependencies so that `createDevServer` starts ~1-2s faster.
+ *
+ * Call this during warm standby phase while waiting for activation. The
+ * K8s startup probe (`/_sb_ready`) gates on this resolving.
+ *
+ * Any failure (timeout, createServer throw, unexpected error) is fatal:
+ * we log it and `process.exit(1)`. Warm pods have `RestartPolicy: Never`,
+ * so the process exit fails the pod, and the reconciler replaces it
+ * within seconds. Letting the probe kill the container instead would
+ * add ~2min of idle time. We don't call `server.close()` on failure —
+ * for the timeout case esbuild is still running and close crashes Node
+ * anyway, and for other cases `process.exit` reaps everything cleanly.
+ */
+const PRE_WARM_TIMEOUT_MS = 60_000;
+
+export async function preWarmViteCache(root: string): Promise<void> {
+  const start = Date.now();
+  console.log("[warm] Pre-warming Vite dependency cache...");
+  try {
+    const server = await createServer({
+      root,
+      mode: "development",
+      server: { middlewareMode: true, hmr: false },
+      plugins: vitePlugins(root, { fileSync: fileSyncVitePlugin().plugin }),
+      logLevel: "warn",
+      optimizeDeps: OPTIMIZE_DEPS_CONFIG,
+    });
+    const depsDir = path.join(root, "node_modules", ".vite", "deps");
+    const pollMs = 100;
+    const deadline = Date.now() + PRE_WARM_TIMEOUT_MS;
+    while (!existsSync(depsDir)) {
+      if (Date.now() > deadline) {
+        throw new Error(
+          `Vite dep cache not created after ${PRE_WARM_TIMEOUT_MS}ms; optimizer likely hung`,
+        );
+      }
+      await new Promise((r) => setTimeout(r, pollMs));
+    }
+    await server.close();
+    console.log(`[warm] Vite cache warmed in ${Date.now() - start}ms`);
+  } catch (error) {
+    console.error(
+      `[warm] Vite cache pre-warm failed (${Date.now() - start}ms) — exiting for fast pod recycle:`,
+      error,
+    );
+    process.exit(1);
+  }
+}
+
 const DEFAULT_HMR_PORT = 24678;
 
 function getFreePort() {

package/src/index.ts

@@ -64,7 +64,7 @@ export {
 export { AUTO_UPGRADE_EXIT_CODE } from "./cli-replacement/automatic-upgrades.js";
 export { RESTART_EXIT_CODE } from "./dev-utils/dev-server.mjs";
 
-export { createDevServer } from "./dev-utils/dev-server.mjs";
+export { createDevServer, preWarmViteCache } from "./dev-utils/dev-server.mjs";
 
 export { TokenManager } from "./dev-utils/token-manager.js";