@specific.dev/spectest 0.38.0 → 0.41.0

package/src/harness/service-graph.ts

@@ -0,0 +1,97 @@
+/**
+ * The `dependsOn` graph: validation, and the traversal order bring-up
+ * uses.
+ *
+ * Ported out of `daemon.ts`. Validation runs before anything starts, so
+ * the DAG runner can assume a clean graph — an unknown dependency or a
+ * cycle must be a clear error at load, not a container that never becomes
+ * ready and eventually times out with no explanation.
+ */
+
+export interface GraphNode {
+  name: string;
+  dependsOn?: readonly string[];
+}
+
+/**
+ * Check the graph and return the name→node map used to walk it.
+ *
+ * Rejects a dependency on a service that doesn't exist, and any cycle.
+ */
+export function validateServiceGraph<T extends GraphNode>(services: readonly T[]): Map<string, T> {
+  const byName = new Map(services.map((s) => [s.name, s]));
+
+  // A duplicate name would silently shadow one definition and make the
+  // graph lie about what is running. The old code built the map without
+  // checking, so the second service simply replaced the first.
+  if (byName.size !== services.length) {
+    const seen = new Set<string>();
+    const dupe = services.find((s) => !seen.add(s.name))?.name;
+    throw new Error(`duplicate service name ${JSON.stringify(dupe)}`);
+  }
+
+  for (const s of services) {
+    for (const d of s.dependsOn ?? []) {
+      if (!byName.has(d)) {
+        throw new Error(`service ${s.name} depends on unknown service ${d}`);
+      }
+      if (d === s.name) {
+        throw new Error(`service ${s.name} depends on itself`);
+      }
+    }
+  }
+
+  // Cycle detection by DFS colouring: white = unseen, gray = on the
+  // current stack (so meeting gray again is a cycle), black = finished.
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = new Map<string, number>(services.map((s) => [s.name, WHITE]));
+  const stack: string[] = [];
+  const visit = (name: string): void => {
+    color.set(name, GRAY);
+    stack.push(name);
+    for (const d of byName.get(name)!.dependsOn ?? []) {
+      const c = color.get(d);
+      if (c === GRAY) {
+        // Naming the cycle matters: "service dependency cycle" alone
+        // leaves the user to find it by eye in a large services map.
+        const from = stack.indexOf(d);
+        const loop = [...stack.slice(from), d].join(" → ");
+        throw new Error(`service dependency cycle: ${loop}`);
+      }
+      if (c === WHITE) visit(d);
+    }
+    stack.pop();
+    color.set(name, BLACK);
+  };
+  for (const s of services) if (color.get(s.name) === WHITE) visit(s.name);
+
+  return byName;
+}
+
+/**
+ * Services in an order where every node follows its dependencies.
+ *
+ * Bring-up itself does **not** walk levels — each service starts the
+ * moment its own dependencies are ready, so an unrelated slow probe never
+ * holds back a branch that is ready. This ordering is for the places that
+ * genuinely need a sequence (teardown, reporting), and for asserting the
+ * graph is walkable at all.
+ */
+export function topologicalOrder<T extends GraphNode>(services: readonly T[]): T[] {
+  const byName = validateServiceGraph(services);
+  const out: T[] = [];
+  const done = new Set<string>();
+  const visit = (name: string): void => {
+    if (done.has(name)) return;
+    const node = byName.get(name)!;
+    for (const d of node.dependsOn ?? []) visit(d);
+    done.add(name);
+    out.push(node);
+  };
+  // Declaration order among independent services, so the result is stable
+  // rather than dependent on Map iteration incidentals.
+  for (const s of services) visit(s.name);
+  return out;
+}

package/src/harness/volume-paths.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  CACHE_ROOT,
+  resolveHostPath,
+  sanitizeSegment,
+  survivesTeardown,
+} from "./volume-paths";
+
+const WS = "/workspace";
+
+describe("sanitizeSegment", () => {
+  test("strips leading slashes and replaces unsafe characters", () => {
+    expect(sanitizeSegment("/var/lib/postgresql/data")).toBe("var-lib-postgresql-data");
+  });
+
+  test("trims the dashes left at the edges", () => {
+    expect(sanitizeSegment("/data/")).toBe("data");
+  });
+
+  /** `.` is not in the allowed set, so `..` cannot survive — a target or a
+   *  volume name can never escape its root. */
+  test("path traversal cannot survive", () => {
+    const out = sanitizeSegment("../../etc/shadow");
+    expect(out).not.toContain("..");
+    expect(out).not.toContain("/");
+  });
+
+  test("keeps letters, digits, underscore and dash", () => {
+    expect(sanitizeSegment("pg_data-01")).toBe("pg_data-01");
+  });
+});
+
+describe("resolveHostPath", () => {
+  test("an unnamed volume derives its directory from the target", () => {
+    expect(resolveHostPath("db", { target: "/var/lib/postgresql/data" }, WS)).toBe(
+      "/workspace/.spectest/volumes/db/var-lib-postgresql-data",
+    );
+  });
+
+  test("a relative source resolves under the service's directory", () => {
+    expect(resolveHostPath("db", { source: "pgdata", target: "/data" }, WS)).toBe(
+      "/workspace/.spectest/volumes/db/pgdata",
+    );
+  });
+
+  test("an absolute source is used verbatim", () => {
+    expect(resolveHostPath("db", { source: "/mnt/big", target: "/data" }, WS)).toBe("/mnt/big");
+  });
+
+  test("two services mounting the same name share one directory", () => {
+    const a = resolveHostPath("storage", { name: "media", target: "/x" }, WS);
+    const b = resolveHostPath("imgproxy", { name: "media", target: "/y" }, WS);
+    expect(a).toBe(b);
+    expect(a).toContain("_shared/media");
+  });
+
+  test("different names do not collide", () => {
+    const a = resolveHostPath("s", { name: "media", target: "/x" }, WS);
+    const b = resolveHostPath("s", { name: "other", target: "/x" }, WS);
+    expect(a).not.toBe(b);
+  });
+
+  test("the same target on two services stays separate", () => {
+    const a = resolveHostPath("one", { target: "/data" }, WS);
+    const b = resolveHostPath("two", { target: "/data" }, WS);
+    expect(a).not.toBe(b);
+  });
+});
+
+describe("cache volumes and delta teardown", () => {
+  /** The whole point of the flag: teardown does `rm -rf /workspace`, so a
+   *  cache volume must be rooted outside it or it does not survive. */
+  test("a cache volume is rooted outside the workspace", () => {
+    const host = resolveHostPath("bun", { target: "/root/.bun/install/cache", cache: true }, WS);
+    expect(host.startsWith(CACHE_ROOT)).toBe(true);
+    expect(host.startsWith(WS)).toBe(false);
+  });
+
+  test("a non-cache volume is inside the workspace, so teardown wipes it", () => {
+    const host = resolveHostPath("db", { target: "/data" }, WS);
+    expect(host.startsWith(`${WS}/`)).toBe(true);
+  });
+
+  test("a shared volume honours the cache flag too", () => {
+    const cached = resolveHostPath("a", { name: "layers", target: "/x", cache: true }, WS);
+    const plain = resolveHostPath("a", { name: "layers", target: "/x" }, WS);
+    expect(cached.startsWith(CACHE_ROOT)).toBe(true);
+    expect(plain.startsWith(`${WS}/`)).toBe(true);
+    expect(cached).not.toBe(plain);
+  });
+
+  test("survivesTeardown agrees with where the path landed", () => {
+    expect(survivesTeardown({ target: "/data" }, "db", WS)).toBe(false);
+    expect(survivesTeardown({ target: "/data", cache: true }, "db", WS)).toBe(true);
+    // An absolute source outside /workspace also survives — worth knowing,
+    // because it is a way to keep state by accident.
+    expect(survivesTeardown({ source: "/mnt/big", target: "/d" }, "db", WS)).toBe(true);
+    // …but an absolute source inside /workspace does not.
+    expect(survivesTeardown({ source: "/workspace/keep", target: "/d" }, "db", WS)).toBe(false);
+  });
+});

package/src/harness/volume-paths.ts

@@ -0,0 +1,112 @@
+/**
+ * Where a service's volume is backed on the VM's filesystem.
+ *
+ * Ported out of `daemon.ts`. Pure path arithmetic, but it decides
+ * something with real consequences: **which volumes survive a
+ * delta-restore teardown**.
+ *
+ * Teardown wipes `/workspace` to give a restored environment fresh-state
+ * semantics. Anything that must survive it therefore has to live outside
+ * `/workspace` — and that is exactly what `cache: true` selects, by
+ * rooting the directory under `/var/cache/spectest/volumes` instead.
+ *
+ * The flag is only ever correct for **content-addressed accelerator
+ * data**: package stores, layer caches — data whose presence can change
+ * how *fast* something runs but never *what* it does. It is wrong for any
+ * real state, because a restored environment would then start with a
+ * previous run's data and stop being reproducible. (Counter-example worth
+ * remembering: `k3s()` deliberately does not cache its containerd store —
+ * a fresh cluster over an un-cleanly-killed store wedged the apiserver.)
+ */
+
+import path from "node:path";
+
+/** Root of the per-environment state tree. Wiped by delta teardown. */
+export const DEFAULT_WORKSPACE = "/workspace";
+
+/** Root of the cache tree. Deliberately outside the workspace. */
+export const CACHE_ROOT = "/var/cache/spectest/volumes";
+
+/** Directory holding named shared volumes, under whichever root applies. */
+export const SHARED_DIR = "_shared";
+
+export interface VolumeSpec {
+  /** Named shared volume — every service mounting this name gets the same
+   *  directory. Mutually exclusive with `source`. */
+  name?: string;
+  /** Host path. Absolute paths are used as-is; relative ones resolve under
+   *  the service's own directory. */
+  source?: string;
+  /** Path inside the container. Used to derive a directory when neither
+   *  `name` nor `source` is given. */
+  target: string;
+  /** Survive the delta-restore teardown. Content-addressed data only. */
+  cache?: boolean;
+}
+
+/**
+ * Make an arbitrary string safe as a single path segment.
+ *
+ * Strips leading slashes, replaces anything outside `[A-Za-z0-9_-]`, and
+ * trims the dashes that leaves at the edges. The character filter also
+ * removes `.`, so `..` cannot survive — a volume name or target can't
+ * escape its root.
+ */
+export function sanitizeSegment(p: string): string {
+  return p
+    .replace(/^\/+/, "")
+    .replace(/[^A-Za-z0-9_-]/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * The host directory backing one volume mount.
+ *
+ * Resolution order:
+ *  1. `name` — a shared directory under `_shared`, so two services
+ *     mounting the same name genuinely share one directory.
+ *  2. An **absolute** `source` — used verbatim. The project asked for a
+ *     specific path, so it gets it.
+ *  3. A relative `source`, or nothing at all — under the service's own
+ *     directory, derived from `target` when `source` is absent.
+ *
+ * `workspace` is a parameter rather than a module constant so the rule is
+ * testable without touching the filesystem.
+ */
+export function resolveHostPath(
+  service: string,
+  vol: VolumeSpec,
+  workspace: string = DEFAULT_WORKSPACE,
+): string {
+  const stateRoot = [workspace, ".spectest", "volumes"];
+
+  if (vol.name) {
+    const root = vol.cache ? [CACHE_ROOT, SHARED_DIR] : [...stateRoot, SHARED_DIR];
+    return path.join(...root, sanitizeSegment(vol.name));
+  }
+
+  // An absolute source is the project's own path; `cache` doesn't apply
+  // because the location was already chosen explicitly.
+  if (vol.source && vol.source.startsWith("/")) return vol.source;
+
+  const root = vol.cache ? [CACHE_ROOT, service] : [...stateRoot, service];
+  if (vol.source) {
+    return path.join(...root, vol.source.replace(/^\/+/, ""));
+  }
+  return path.join(...root, sanitizeSegment(vol.target));
+}
+
+/**
+ * Does this volume survive a delta-restore teardown?
+ *
+ * True for cache-flagged volumes and for absolute sources outside the
+ * workspace — the two ways a directory ends up beyond `rm -rf /workspace`.
+ */
+export function survivesTeardown(
+  vol: VolumeSpec,
+  service: string,
+  workspace: string = DEFAULT_WORKSPACE,
+): boolean {
+  const host = resolveHostPath(service, vol, workspace);
+  return !host.startsWith(`${workspace}/`) && host !== workspace;
+}

package/src/ids.ts

@@ -0,0 +1,89 @@
+// Stripe-style resource ids minted in-VM — format-compatible with the
+// control plane's `crates/control-plane/src/ids.rs` (`generate`):
+// `<prefix>_0<20 chars>` where the chars are Crockford base32 (lowercase,
+// minus the ambiguous i/l/o/u) and the `0` after the underscore is the
+// format-version digit. If the scheme changes there, change it here in
+// lockstep (`env.rs::valid_artifact_id` checks this exact shape at the
+// trust boundary).
+//
+// LANDMINE — why the entropy here is NOT just `crypto.getRandomValues`:
+// Bun serves those from a userspace pool that is FROZEN into snapshots, so
+// sibling forks of one snapshot draw identical bytes (verified 2026-07-14:
+// two forks' first screenshot() minted the same id). We therefore hash
+// together, per mint:
+//   - 16 bytes read straight off /dev/urandom (bypasses Bun's pool; the
+//     guest kernel CRNG reseeds across restores — see the VM-determinism
+//     notes — so forks diverge),
+//   - Date.now() (wall clock is re-synced per post-mortem fork start) and
+//     performance.now() (sub-ms), which de-collide even if the kernel pool
+//     hasn't diverged yet,
+//   - a process-local counter (multiple mints in one tick).
+// This makes duplicates practically impossible, but the control plane
+// still treats an id here as untrusted: shape-validated, and a duplicate
+// insert is flagged per-artifact rather than clobbering anything.
+
+import { createHash } from "node:crypto";
+import { closeSync, openSync, readSync } from "node:fs";
+
+/** Crockford base32, lowercased, minus `i`/`l`/`o`/`u` — mirrors ids.rs. */
+const ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+
+/** Random base32 chars after the version digit (100 bits of entropy). */
+const RANDOM_LEN = 20;
+
+let mintCounter = 0;
+
+/** Mint a fresh id, e.g. `generateId("art")` → `art_0c3k9mpq…`. */
+export function generateId(prefix: string): string {
+  const digest = createHash("sha256")
+    .update(urandom(16))
+    .update(String(Date.now()))
+    .update(String(performance.now()))
+    .update(String(mintCounter++))
+    .digest();
+  return `${prefix}_0${base32Crockford(digest.subarray(0, 16)).slice(0, RANDOM_LEN)}`;
+}
+
+/** Read `n` bytes directly from /dev/urandom (NOT Bun's cached pool). */
+function urandom(n: number): Uint8Array {
+  const buf = new Uint8Array(n);
+  try {
+    const fd = openSync("/dev/urandom", "r");
+    try {
+      let off = 0;
+      while (off < n) {
+        const read = readSync(fd, buf, off, n - off, null);
+        if (read <= 0) break;
+        off += read;
+      }
+    } finally {
+      closeSync(fd);
+    }
+  } catch {
+    // Non-Linux host (SDK types compiled locally) or exotic failure — the
+    // clock + counter inputs still make the hash unique in practice.
+    crypto.getRandomValues(buf);
+  }
+  return buf;
+}
+
+/** Encode bytes as Crockford base32 (no padding). 16 bytes → 26 chars. */
+function base32Crockford(bytes: Uint8Array): string {
+  let out = "";
+  let acc = 0;
+  let bits = 0;
+  for (const b of bytes) {
+    acc = (acc << 8) | b;
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      out += ALPHABET[(acc >> bits) & 0x1f];
+    }
+    // Keep the accumulator within 32-bit safe range for the `<<` operator.
+    acc &= (1 << bits) - 1;
+  }
+  if (bits > 0) {
+    out += ALPHABET[(acc << (5 - bits)) & 0x1f];
+  }
+  return out;
+}