@superblocksteam/sdk 2.0.118 → 2.0.119-next.0

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

@@ -0,0 +1,252 @@
+/**
+ * Dev-server connection-phase metrics.
+ *
+ * Records counters and histograms for the dev-server endpoints that the editor
+ * and SABS hit during a live-edit connection: `/_sb_health`, `/_sb_connect`,
+ * `/_sb_activate`, `/_sb_disconnect`, `/_sb_status`, `/_sb_activity`, plus
+ * WebSocket upgrades, Vite eager-init, and warm-standby activation.
+ *
+ * Metrics are scoped to the dev-server's existing OTel pipeline. When telemetry
+ * has not yet initialized (warm-standby pre-activation), record calls are
+ * buffered and replayed by `flush()` once `configureTelemetry` completes, so
+ * warm-standby observations are not silently dropped into the no-op meter.
+ */
+
+import { isTelemetryInitialized } from "@superblocksteam/telemetry";
+
+import { getMeter } from "../telemetry/index.js";
+
+/** Dev-server endpoints that produce per-request metrics. */
+export type DevServerEndpoint =
+  | "_sb_health"
+  | "_sb_connect"
+  | "_sb_activate"
+  | "_sb_disconnect"
+  | "_sb_status"
+  | "_sb_activity"
+  | "_sb_persist"
+  | "_sb_ready";
+
+/**
+ * Allowlisted HTTP methods recorded as the `method` metric label. Anything
+ * outside this set — `req.method` is client-controlled, and `/_sb_health` is
+ * unauthenticated — is bucketed as `'OTHER'` to keep label cardinality bounded.
+ */
+const ALLOWED_METHODS: ReadonlySet<string> = new Set([
+  "GET",
+  "HEAD",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "OPTIONS",
+]);
+
+function sanitizeMethod(method: string): string {
+  const upper = method.toUpperCase();
+  return ALLOWED_METHODS.has(upper) ? upper : "OTHER";
+}
+
+/**
+ * Coarse failure type for dev-server endpoint outcomes. Distinct from raw HTTP
+ * status so dashboards can filter by reason without high-cardinality labels.
+ */
+export type DevServerFailureType =
+  | "none"
+  | "auth"
+  | "validation"
+  | "branch_mismatch"
+  | "vite_init"
+  | "internal";
+
+/**
+ * Outcome of the warm-standby activation handshake.
+ *
+ *   accepted  - 200 OK, transitioning to full server
+ *   rejected  - 400/413 (validation, body too large)
+ *   error     - JSON parse / unexpected exception
+ */
+export type WarmActivationOutcome = "accepted" | "rejected" | "error";
+
+/**
+ * Soft cap on buffered pre-init events. Warm-standby reasonably emits ~1
+ * `recordWarmPrewarm` + ~1 `recordWarmActivation` before activation, so the
+ * cap is generously above the expected load — it exists only to bound memory
+ * if `flush()` is somehow never called.
+ */
+const MAX_BUFFERED_EVENTS = 256;
+
+/**
+ * Records dev-server connection-phase metrics.
+ *
+ * Calls made before `configureTelemetry` completes are queued and replayed by
+ * `flush()` once telemetry is online. Without this, warm-standby observations
+ * are routed through `getMeter()`'s no-op fallback meter and silently dropped
+ * — defeating the metric's purpose, since warm activation is exactly the path
+ * we want to observe. The buffer is bounded to bound memory; instruments are
+ * still NOT cached, so each replayed call resolves a fresh meter.
+ */
+class DevServerMetrics {
+  /**
+   * Pre-init replay queue. Entries are bound `() => void` recorders that close
+   * over their args at call time, so labels are captured even if the buffer is
+   * drained much later.
+   */
+  private bufferedRecorders: Array<() => void> = [];
+
+  /**
+   * Routes a recorder to the live OTel meter when telemetry is up, or buffers
+   * it for replay when telemetry has not yet initialized.
+   */
+  private record(recorder: () => void): void {
+    if (isTelemetryInitialized()) {
+      recorder();
+      return;
+    }
+    if (this.bufferedRecorders.length >= MAX_BUFFERED_EVENTS) {
+      // Drop the oldest event rather than the new one — the most recent
+      // observations are typically the most informative for an investigator.
+      this.bufferedRecorders.shift();
+    }
+    this.bufferedRecorders.push(recorder);
+  }
+
+  /**
+   * Replays buffered recorders against the (now-initialized) meter and clears
+   * the queue. Idempotent — safe to call multiple times. Callers should invoke
+   * this immediately after `configureTelemetry()` resolves.
+   *
+   * No-ops if telemetry did not actually come up (e.g., `configureTelemetry`
+   * returned `false` due to a missing config or an internal init failure).
+   * Draining the buffer through a still-no-op meter would silently lose every
+   * observation AND clear the queue, so a later successful re-init via
+   * `onTokenReceived` could not recover them. Keeping the buffer intact lets
+   * a subsequent `flush()` call replay them once telemetry is genuinely live.
+   */
+  flush(): void {
+    if (!isTelemetryInitialized()) {
+      return;
+    }
+    if (this.bufferedRecorders.length === 0) {
+      return;
+    }
+    const events = this.bufferedRecorders;
+    this.bufferedRecorders = [];
+    for (const e of events) {
+      e();
+    }
+  }
+
+  /**
+   * Records the outcome of a dev-server HTTP endpoint request.
+   */
+  recordEndpoint(
+    endpoint: DevServerEndpoint,
+    method: string,
+    status: number,
+    durationMs: number,
+    failureType: DevServerFailureType = "none",
+  ): void {
+    const labels = {
+      endpoint,
+      method: sanitizeMethod(method),
+      status: String(status),
+      failure_type: failureType,
+    };
+    this.record(() => {
+      const meter = getMeter();
+      meter
+        .createCounter("dev_server_endpoint_requests_total", {
+          description:
+            "Count of dev-server endpoint requests by endpoint, status, and failure type.",
+        })
+        .add(1, labels);
+      meter
+        .createHistogram("dev_server_endpoint_duration_ms", {
+          description:
+            "Latency of dev-server endpoint requests in milliseconds.",
+          unit: "ms",
+        })
+        .record(durationMs, labels);
+    });
+  }
+
+  /**
+   * Records a WebSocket upgrade attempt against the dev-server's HTTP socket.
+   */
+  recordSocketUpgrade(outcome: "accepted" | "rejected"): void {
+    this.record(() => {
+      getMeter()
+        .createCounter("dev_server_socket_upgrade_total", {
+          description:
+            "Count of WebSocket upgrade attempts against the dev-server HTTP socket.",
+        })
+        .add(1, { outcome });
+    });
+  }
+
+  /**
+   * Records the duration and outcome of Vite eager-init (the call that creates
+   * the user-facing Vite server during /_sb_connect ramp-up).
+   */
+  recordViteEagerInit(durationMs: number, outcome: "success" | "error"): void {
+    this.record(() => {
+      getMeter()
+        .createHistogram("dev_server_vite_eager_init_duration_ms", {
+          description:
+            "Duration of eager Vite server initialization in milliseconds.",
+          unit: "ms",
+        })
+        .record(durationMs, { outcome });
+    });
+  }
+
+  /**
+   * Records the duration and outcome of warm-pod Vite dep-cache pre-warm.
+   */
+  recordWarmPrewarm(durationMs: number, outcome: "success" | "error"): void {
+    this.record(() => {
+      getMeter()
+        .createHistogram("dev_server_warm_prewarm_duration_ms", {
+          description:
+            "Duration of warm-standby Vite dep-cache pre-warm in milliseconds.",
+          unit: "ms",
+        })
+        .record(durationMs, { outcome });
+    });
+  }
+
+  /**
+   * Records a warm-standby activation request outcome.
+   */
+  recordWarmActivation(outcome: WarmActivationOutcome): void {
+    this.record(() => {
+      getMeter()
+        .createCounter("dev_server_warm_activation_total", {
+          description:
+            "Count of warm-standby /_sb_activate requests by outcome.",
+        })
+        .add(1, { outcome });
+    });
+  }
+
+  /**
+   * Records the time from receiving a successful /_sb_activate POST to the
+   * full Express dev-server being attached to the warm HTTP server (the
+   * "no-port-gap" handoff window — gateways see 502s if this stretches).
+   */
+  recordWarmHandoff(durationMs: number): void {
+    this.record(() => {
+      getMeter()
+        .createHistogram("dev_server_warm_activation_handoff_duration_ms", {
+          description:
+            "Time from /_sb_activate acceptance to full dev server attached, in milliseconds.",
+          unit: "ms",
+        })
+        .record(durationMs);
+    });
+  }
+}
+
+/** Process-wide dev-server metrics singleton. */
+export const devServerMetrics = new DevServerMetrics();

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

@@ -1,8 +1,11 @@
 import type * as NodeChildProcess from "node:child_process";
 import { EventEmitter } from "node:events";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { PassThrough } from "node:stream";
 
-import { describe, expect, it, vi } from "vitest";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
 
 const { spawnMock } = vi.hoisted(() => ({
   spawnMock: vi.fn(),
@@ -22,6 +25,14 @@ vi.mock("node:child_process", async () => {
   };
 });
 
+// Use a static import so the slow `dev-server.mjs` module graph (vite, react
+// plugin, workspace deps) loads during file evaluation rather than inside each
+// test, where the cold-import cost easily exceeds the default 5s test timeout.
+import {
+  createWorkspacePersistArchive,
+  getSuperblocksTarExcludes,
+} from "./dev-server.mjs";
+
 function createMockProcess() {
   return Object.assign(new EventEmitter(), {
     stdin: new PassThrough(),
@@ -30,8 +41,53 @@ function createMockProcess() {
   });
 }
 
+describe("getSuperblocksTarExcludes", () => {
+  let tempRoot: string;
+
+  beforeAll(() => {
+    tempRoot = mkdtempSync(join(tmpdir(), "persist-test-"));
+  });
+
+  afterAll(() => {
+    rmSync(tempRoot, { recursive: true, force: true });
+  });
+
+  it("excludes .superblocks entirely when the directory does not exist", () => {
+    const result = getSuperblocksTarExcludes(tempRoot);
+    expect(result).toEqual(["--exclude", ".superblocks"]);
+  });
+
+  it("excludes subdirs not in the safelist and keeps context/drafts", () => {
+    const sb = join(tempRoot, ".superblocks");
+    mkdirSync(sb);
+    mkdirSync(join(sb, "context"));
+    mkdirSync(join(sb, "drafts"));
+    mkdirSync(join(sb, "recordings"));
+    mkdirSync(join(sb, "scratch"));
+    mkdirSync(join(sb, "system-skills"));
+
+    const result = getSuperblocksTarExcludes(tempRoot);
+
+    // Safelisted dirs must NOT appear
+    expect(result).not.toContain(".superblocks/context");
+    expect(result).not.toContain(".superblocks/drafts");
+
+    // Non-safelisted dirs must be excluded
+    expect(result).toContain(".superblocks/recordings");
+    expect(result).toContain(".superblocks/scratch");
+    expect(result).toContain(".superblocks/system-skills");
+
+    // Each excluded dir has a preceding --exclude flag
+    for (const name of ["recordings", "scratch", "system-skills"]) {
+      const idx = result.indexOf(`.superblocks/${name}`);
+      expect(idx).toBeGreaterThan(0);
+      expect(result[idx - 1]).toBe("--exclude");
+    }
+  });
+});
+
 describe("createWorkspacePersistArchive", () => {
-  it("excludes node_modules from the tar archive", async () => {
+  it("archive respects excludes", async () => {
     const tarProc = createMockProcess();
     const zstdProc = createMockProcess();
     spawnMock.mockImplementation((command: string) => {
@@ -47,27 +103,17 @@ describe("createWorkspacePersistArchive", () => {
       return zstdProc;
     });
 
-    const { createWorkspacePersistArchive } = await import("./dev-server.mjs");
-
     await expect(createWorkspacePersistArchive("/workspace")).resolves.toEqual(
       Buffer.from("archive"),
     );
 
     const tarCall = spawnMock.mock.calls.find(([command]) => command === "tar");
     expect(tarCall).toBeDefined();
-    expect(tarCall?.[1]).toEqual([
-      "cf",
-      "-",
-      "--exclude",
-      ".git",
-      "--exclude",
-      "node_modules",
-      "--exclude",
-      ".superblocks",
-      "-C",
-      "/workspace",
-      ".",
-    ]);
+    const args: string[] = tarCall?.[1];
+
+    // Standard excludes are always present
+    expect(args).toContain(".git");
+    expect(args).toContain("node_modules");
   });
 
   it("rejects if tar fails after zstd closes successfully", async () => {
@@ -87,10 +133,115 @@ describe("createWorkspacePersistArchive", () => {
       return zstdProc;
     });
 
-    const { createWorkspacePersistArchive } = await import("./dev-server.mjs");
-
     await expect(
       createWorkspacePersistArchive("/workspace"),
     ).rejects.toThrowError(/^tar archival failed \(code 2\): tar failed$/);
   });
 });
+
+describe("createWorkspacePersistUploadHeaders", () => {
+  it("forwards presigned upload headers and adds the archive content length", async () => {
+    const { createWorkspacePersistUploadHeaders } =
+      await import("./dev-server.mjs");
+
+    expect(
+      createWorkspacePersistUploadHeaders(123, {
+        "Content-Type": "application/custom-zstd",
+        "x-amz-server-side-encryption": "AES256",
+      }),
+    ).toEqual({
+      "content-length": "123",
+      "content-type": "application/custom-zstd",
+      "x-amz-server-side-encryption": "AES256",
+    });
+  });
+
+  it("normalizes presigned upload header names case-insensitively", async () => {
+    const { createWorkspacePersistUploadHeaders } =
+      await import("./dev-server.mjs");
+
+    expect(
+      createWorkspacePersistUploadHeaders(789, {
+        "content-type": "application/custom-zstd",
+        "content-length": "1",
+        "x-amz-server-side-encryption": "AES256",
+      }),
+    ).toEqual({
+      "content-length": "789",
+      "content-type": "application/custom-zstd",
+      "x-amz-server-side-encryption": "AES256",
+    });
+  });
+
+  it("keeps the legacy content headers when SABS sends only a URL", async () => {
+    const { createWorkspacePersistUploadHeaders } =
+      await import("./dev-server.mjs");
+
+    expect(createWorkspacePersistUploadHeaders(456)).toEqual({
+      "content-length": "456",
+      "content-type": "application/zstd",
+    });
+  });
+});
+
+describe("isWorkspacePersistUploadHeaders", () => {
+  it("accepts undefined (legacy SABS payloads with no uploadHeaders)", async () => {
+    const { isWorkspacePersistUploadHeaders } =
+      await import("./dev-server.mjs");
+
+    expect(isWorkspacePersistUploadHeaders(undefined)).toBe(true);
+  });
+
+  it("accepts a valid string map", async () => {
+    const { isWorkspacePersistUploadHeaders } =
+      await import("./dev-server.mjs");
+
+    expect(
+      isWorkspacePersistUploadHeaders({
+        "content-type": "application/zstd",
+        "x-amz-server-side-encryption": "AES256",
+      }),
+    ).toBe(true);
+  });
+
+  it("rejects null, arrays, and non-string values", async () => {
+    const { isWorkspacePersistUploadHeaders } =
+      await import("./dev-server.mjs");
+
+    expect(isWorkspacePersistUploadHeaders(null)).toBe(false);
+    expect(isWorkspacePersistUploadHeaders([])).toBe(false);
+    expect(isWorkspacePersistUploadHeaders({ "x-foo": 1 })).toBe(false);
+  });
+
+  it("rejects case-insensitive duplicate keys", async () => {
+    const { isWorkspacePersistUploadHeaders } =
+      await import("./dev-server.mjs");
+
+    expect(
+      isWorkspacePersistUploadHeaders({
+        "Content-Type": "application/zstd",
+        "content-type": "application/custom-zstd",
+      }),
+    ).toBe(false);
+  });
+
+  it("rejects header names with illegal characters", async () => {
+    const { isWorkspacePersistUploadHeaders } =
+      await import("./dev-server.mjs");
+
+    // Spaces are not allowed in HTTP token names.
+    expect(isWorkspacePersistUploadHeaders({ "bad header": "value" })).toBe(
+      false,
+    );
+  });
+
+  it("rejects header values with illegal characters", async () => {
+    const { isWorkspacePersistUploadHeaders } =
+      await import("./dev-server.mjs");
+
+    // CR/LF in header values is not allowed (header injection guard).
+    expect(isWorkspacePersistUploadHeaders({ "x-foo": "bad\r\nvalue" })).toBe(
+      false,
+    );
+  });
+});