@specific.dev/spectest 0.39.0 → 0.43.0

package/src/harness/main.ts

@@ -0,0 +1,196 @@
+/**
+ * The harness process.
+ *
+ * Started by the supervisor (`crates/spectest-vm-agent/src/supervisor.rs`)
+ * from the app dir's `node_modules`, so it is the *user's* SDK version
+ * that runs the user's project. It dials the socket the supervisor
+ * already bound, completes the `hello` handshake, and then serves
+ * requests until told to shut down.
+ *
+ * ## This process is long-lived and is never restarted
+ *
+ * It holds the state that makes forking a product feature — fake `state`,
+ * the ingress listeners with their per-fork route and certificate tables,
+ * the DNS registry, containers started mid-test, live browser sessions,
+ * the recorder. The supervisor deliberately has no respawn path: if this
+ * process dies, the environment is dead and says so, rather than silently
+ * coming back empty.
+ *
+ * So the rules here are: never call `process.exit` on a request failure
+ * (answer with an error instead), and never let an unhandled rejection
+ * take the process down.
+ *
+ * ## One implementation, two transports
+ *
+ * Everything this serves comes from the same method table the legacy HTTP
+ * daemon serves (`METHODS`, built in `daemon.ts`). That is deliberate and
+ * temporary: during the cutover both transports are live, and the failure
+ * being designed out is the one where a fix lands on the transport that is
+ * being replaced and never reaches the new one.
+ *
+ * The table is built **once** per process, so the mutual-exclusion slots
+ * that stop two tests running at the same time are shared across both
+ * transports. Two tables would each enforce the rule and together break it.
+ */
+
+import net from "node:net";
+
+import { METHODS } from "../daemon";
+import { codeOf } from "./methods";
+import {
+  PROTOCOL_VERSION,
+  decodeFrame,
+  encodeFrame,
+  fail,
+  ok,
+  type Frame,
+  type RequestFrame,
+} from "./protocol";
+
+/** Capabilities this build announces. Empty is fine — the slot is what
+ *  matters, so a later release has something to negotiate against. */
+const CAPABILITIES: string[] = [];
+
+type Handler = (params: Record<string, unknown>) => Promise<unknown>;
+
+/** Methods this build can serve. Everything else is answered with an
+ *  error naming the method, which is far easier to diagnose than a
+ *  request that hangs. */
+export function handlers(
+  sdkVersion: string,
+  onShutdown: () => void,
+  methods: Record<string, Handler> = METHODS as Record<string, Handler>,
+): Record<string, Handler> {
+  return {
+    // Everything the environment actually does.
+    ...methods,
+    // Transport-level methods, which the method table has no business
+    // knowing about: they concern this connection, not this environment.
+    // Declared after the spread so the table can never shadow them — a
+    // `shutdown` that didn't shut down would be an unkillable environment.
+    hello: async () => ({
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: CAPABILITIES,
+      sdkVersion,
+    }),
+    shutdown: async () => {
+      // Reply first, exit after — the supervisor is waiting on this
+      // response, and dropping the connection instead would surface as a
+      // transport error rather than a clean stop.
+      queueMicrotask(onShutdown);
+      return {};
+    },
+  };
+}
+
+/**
+ * Serve one connection until it closes.
+ *
+ * Split from `main` so it can be driven over any duplex stream in tests.
+ */
+export function serve(
+  socket: NodeJS.ReadWriteStream,
+  registry: Record<string, Handler>,
+): void {
+  let buffered = "";
+  const send = (frame: Frame) => socket.write(encodeFrame(frame));
+
+  const dispatch = async (req: RequestFrame): Promise<void> => {
+    const handler = registry[req.method];
+    if (!handler) {
+      send(
+        fail(
+          req.id,
+          `harness does not implement ${JSON.stringify(req.method)}`,
+          "unimplemented",
+        ),
+      );
+      return;
+    }
+    try {
+      send(ok(req.id, (await handler(req.params ?? {})) as Record<string, unknown>));
+    } catch (err) {
+      // A failing request must not take the process down: the harness holds
+      // the environment's live state, so its death is unrecoverable.
+      //
+      // A refusal the method meant to make (an unknown case, a second test
+      // while one is running) reports its own kind and just its message. An
+      // unexpected throw is a bug in the method and carries the stack,
+      // which is the only place that information exists.
+      const e = err as Error;
+      const code = codeOf(err);
+      const detail =
+        code === "handler_error" ? (e?.stack ?? e?.message ?? String(err)) : e.message;
+      send(fail(req.id, detail, code));
+    }
+  };
+
+  socket.on("data", (chunk: Buffer | string) => {
+    buffered += chunk.toString();
+    // NDJSON: a chunk can hold several frames, or half of one.
+    for (;;) {
+      const nl = buffered.indexOf("\n");
+      if (nl === -1) break;
+      const line = buffered.slice(0, nl);
+      buffered = buffered.slice(nl + 1);
+      if (!line.trim()) continue;
+      let frame: Frame;
+      try {
+        frame = decodeFrame(line);
+      } catch (e) {
+        // Unroutable — no id to answer on. Log and keep serving rather
+        // than dropping a connection that is otherwise healthy.
+        console.error(`harness: ${(e as Error).message}`);
+        continue;
+      }
+      if (frame.kind === "request") void dispatch(frame);
+      // Responses to our own up-calls and events are handled elsewhere;
+      // ignoring them here keeps this loop about serving.
+    }
+  });
+}
+
+/** Read the SDK's own version, for the handshake. */
+async function sdkVersion(): Promise<string> {
+  try {
+    const pkg = await import("../../package.json", { with: { type: "json" } });
+    return (pkg as { default?: { version?: string } }).default?.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+export async function main(): Promise<void> {
+  const path = process.env.SPECTEST_HARNESS_SOCKET;
+  if (!path) {
+    console.error("harness: SPECTEST_HARNESS_SOCKET is not set");
+    process.exit(2);
+  }
+
+  // An unhandled rejection anywhere in user code must not kill the
+  // environment — report it and keep serving.
+  process.on("unhandledRejection", (reason) => {
+    console.error("harness: unhandled rejection:", reason);
+  });
+
+  const version = await sdkVersion();
+  const socket = net.createConnection(path);
+
+  socket.on("error", (e) => {
+    console.error(`harness: socket error: ${e.message}`);
+    process.exit(1);
+  });
+  socket.on("close", () => {
+    // The supervisor went away; there is nothing left to serve.
+    process.exit(0);
+  });
+
+  await new Promise<void>((resolve) => socket.once("connect", () => resolve()));
+  serve(socket, handlers(version, () => socket.end(() => process.exit(0))));
+}
+
+// Only run when executed directly, so importing this module in a test
+// doesn't try to dial a socket.
+if (import.meta.main) {
+  void main();
+}

package/src/harness/methods.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  HarnessError,
+  badRequest,
+  codeOf,
+  conflict,
+  notFound,
+  requireString,
+  type MethodTable,
+} from "./methods";
+
+const table = (names: string[]): MethodTable =>
+  Object.fromEntries(names.map((n) => [n, async () => ({})]));
+
+describe("error kinds", () => {
+
+  test("the constructors carry their kind", () => {
+    expect(badRequest("x").code).toBe("bad_request");
+    expect(notFound("x").code).toBe("not_found");
+    expect(conflict("x").code).toBe("conflict");
+  });
+
+  /** A method body that throws an ordinary Error is a bug in the method,
+   *  not a statement about the request — reporting it as a 400 would blame
+   *  the caller for our own failure. */
+  test("an ordinary error is a handler failure, not a bad request", () => {
+    expect(codeOf(new Error("boom"))).toBe("handler_error");
+    expect(codeOf("a string")).toBe("handler_error");
+    expect(codeOf(new HarnessError("conflict", "busy"))).toBe("conflict");
+  });
+
+  test("the message survives, since it is all the caller gets", () => {
+    expect(conflict("another test is already running").message).toBe(
+      "another test is already running",
+    );
+  });
+});
+
+describe("requireString", () => {
+  test("returns the value when present", () => {
+    expect(requireString({ code: "1+1" }, "code")).toBe("1+1");
+  });
+
+  /** An empty string is not a usable snippet or case id, and letting it
+   *  through would fail deeper in with a worse message. */
+  test("rejects missing, empty and wrong-typed values", () => {
+    expect(() => requireString({}, "code")).toThrow(/code \(string\) is required/);
+    expect(() => requireString({ code: "" }, "code")).toThrow();
+    expect(() => requireString({ code: 42 }, "code")).toThrow();
+  });
+
+  test("the failure is a bad request, not a handler error", () => {
+    try {
+      requireString({}, "caseId", "caseId");
+      throw new Error("should have thrown");
+    } catch (e) {
+      expect(codeOf(e)).toBe("bad_request");
+      expect((e as Error).message).toBe("caseId is required");
+    }
+  });
+});
+

package/src/harness/methods.ts

@@ -0,0 +1,92 @@
+/**
+ * What the harness can be asked to do, independent of how it was asked.
+ *
+ * The daemon grew as an HTTP server, so every operation was written against
+ * `IncomingMessage`/`ServerResponse`: parsing a body, choosing a status
+ * code, and writing a reply were tangled up with deciding what to actually
+ * do. That is the coupling this module removes. A method here takes plain
+ * params and returns a plain object; a *transport* — the legacy HTTP router,
+ * or the supervisor's frame protocol — adapts to it.
+ *
+ * The point is that both transports run the **same** implementation. During
+ * the cutover the two are live at once, and the failure this design refuses
+ * to allow is the one where a fix lands on the transport that is being
+ * replaced and quietly doesn't reach the new one.
+ *
+ * ## Errors carry a kind, not a status code
+ *
+ * HTTP status codes were the daemon's error vocabulary: 400 for a bad body,
+ * 404 for an unknown case, 409 for "already running". The frame protocol has
+ * no statuses, so the kind is named ({@link HarnessErrorCode}) and each
+ * transport renders it — the frame protocol carries it as the error's
+ * `code`. Naming them also makes the one that matters legible: `conflict` is
+ * not a client mistake, it is the harness refusing to run two tests in one
+ * process at once, which is a correctness property rather than a validation
+ * failure.
+ */
+
+/** The kinds of failure a method can report. */
+export type HarnessErrorCode =
+  /** The request itself was malformed — missing or wrong-typed params. */
+  | "bad_request"
+  /** The thing named does not exist here (an unknown case id). */
+  | "not_found"
+  /** Refused because something incompatible is already running. */
+  | "conflict"
+  /** The method ran and threw. */
+  | "handler_error";
+
+/** An error a transport can render without knowing what failed. */
+export class HarnessError extends Error {
+  readonly code: HarnessErrorCode;
+
+  constructor(code: HarnessErrorCode, message: string) {
+    super(message);
+    this.name = "HarnessError";
+    this.code = code;
+  }
+}
+
+export const badRequest = (m: string) => new HarnessError("bad_request", m);
+export const notFound = (m: string) => new HarnessError("not_found", m);
+export const conflict = (m: string) => new HarnessError("conflict", m);
+
+/** One operation: plain params in, plain result out. */
+export type Method = (params: Record<string, unknown>) => Promise<unknown>;
+
+/** Everything the harness can serve, by method name. */
+export type MethodTable = Record<string, Method>;
+
+/** How a transport that speaks HTTP renders an error kind. */
+function unusedHttpStatusFor(code: HarnessErrorCode): number {
+  switch (code) {
+    case "bad_request":
+      return 400;
+    case "not_found":
+      return 404;
+    case "conflict":
+      return 409;
+    case "handler_error":
+      return 500;
+  }
+}
+
+/** The kind to report for a value thrown from a method body. Anything that
+ *  isn't already a {@link HarnessError} is an unexpected failure inside the
+ *  method, not a statement about the request. */
+export function codeOf(err: unknown): HarnessErrorCode {
+  return err instanceof HarnessError ? err.code : "handler_error";
+}
+
+/** Require a non-empty string param, with the message the caller had. */
+export function requireString(
+  params: Record<string, unknown>,
+  name: string,
+  label = `${name} (string)`,
+): string {
+  const v = params[name];
+  if (typeof v !== "string" || v.length === 0) {
+    throw badRequest(`${label} is required`);
+  }
+  return v;
+}

package/src/harness/names-registry.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  decodeRegistry,
+  encodeRegistry,
+  lookup,
+  suffixOf,
+  upsert,
+  type RegistryDoc,
+} from "./names-registry";
+
+const doc = (d: Partial<RegistryDoc> = {}): RegistryDoc => ({
+  hosts: {},
+  wildcards: [],
+  ...d,
+});
+
+describe("encode/decode round-trip", () => {
+  test("survives a round-trip", () => {
+    const d = doc({
+      hosts: { "api.stripe.com": "10.42.0.1" },
+      wildcards: [{ suffix: ".example.com", ip: "10.42.0.2" }],
+    });
+    const back = decodeRegistry(encodeRegistry(d, 123));
+    expect(back.hosts).toEqual(d.hosts);
+    expect(back.wildcards).toEqual(d.wildcards);
+    expect(back.updatedAt).toBe(123);
+  });
+
+  /** The resolver reads this on a hot path while the harness may be
+   *  rewriting it. Throwing would take out DNS for the WHOLE environment,
+   *  not just the name being added; degrading to "no custom names" is
+   *  recoverable and the next read restores everything. */
+  test("a truncated file yields an empty registry, not an exception", () => {
+    expect(() => decodeRegistry('{"hosts":{"a":')).not.toThrow();
+    expect(decodeRegistry('{"hosts":{"a":')).toEqual({ hosts: {}, wildcards: [] });
+  });
+
+  test("garbage and empty input are both survivable", () => {
+    expect(decodeRegistry("")).toEqual({ hosts: {}, wildcards: [] });
+    expect(decodeRegistry("null")).toEqual({ hosts: {}, wildcards: [] });
+    expect(decodeRegistry("[]")).toEqual({ hosts: {}, wildcards: [] });
+  });
+
+  test("malformed wildcard entries are dropped, not propagated", () => {
+    const parsed = decodeRegistry(
+      JSON.stringify({ hosts: {}, wildcards: [{ suffix: ".ok.com", ip: "1.2.3.4" }, { suffix: 5 }, null] }),
+    );
+    expect(parsed.wildcards).toEqual([{ suffix: ".ok.com", ip: "1.2.3.4" }]);
+  });
+});
+
+describe("lookup precedence", () => {
+  test("an exact name wins over a wildcard that also matches", () => {
+    const d = doc({
+      hosts: { "api.example.com": "10.0.0.1" },
+      wildcards: [{ suffix: ".example.com", ip: "10.0.0.2" }],
+    });
+    expect(lookup(d, "api.example.com")).toBe("10.0.0.1");
+  });
+
+  test("the longest matching suffix wins", () => {
+    const d = doc({
+      wildcards: [
+        { suffix: ".example.com", ip: "10.0.0.1" },
+        { suffix: ".eu.example.com", ip: "10.0.0.2" },
+      ],
+    });
+    expect(lookup(d, "a.eu.example.com")).toBe("10.0.0.2");
+    expect(lookup(d, "a.us.example.com")).toBe("10.0.0.1");
+  });
+
+  test("order in the file does not decide the winner", () => {
+    const a = doc({
+      wildcards: [
+        { suffix: ".eu.example.com", ip: "long" },
+        { suffix: ".example.com", ip: "short" },
+      ],
+    });
+    const b = doc({ wildcards: [...a.wildcards].reverse() });
+    expect(lookup(a, "x.eu.example.com")).toBe("long");
+    expect(lookup(b, "x.eu.example.com")).toBe("long");
+  });
+
+  /** A wildcard here matches any depth — unlike a certificate, which
+   *  covers exactly one label. Same asymmetry as the ingress routes. */
+  test("a wildcard matches any depth of subdomain", () => {
+    const d = doc({ wildcards: [{ suffix: ".amazonaws.com", ip: "10.0.0.9" }] });
+    expect(lookup(d, "states.us-east-1.amazonaws.com")).toBe("10.0.0.9");
+  });
+
+  test("an unmatched name yields null, so the caller falls through to DNS", () => {
+    expect(lookup(doc(), "nothing.test")).toBeNull();
+  });
+
+  test("a name that merely ends similarly does not match", () => {
+    const d = doc({ wildcards: [{ suffix: ".example.com", ip: "10.0.0.1" }] });
+    // ".example.com" does not suffix-match "notexample.com".
+    expect(lookup(d, "notexample.com")).toBeNull();
+  });
+});
+
+describe("upsert", () => {
+  test("adds an exact host", () => {
+    expect(upsert(doc(), "a.test", "1.1.1.1").hosts["a.test"]).toBe("1.1.1.1");
+  });
+
+  test("re-registering an exact host replaces it", () => {
+    let d = upsert(doc(), "a.test", "1.1.1.1");
+    d = upsert(d, "a.test", "2.2.2.2");
+    expect(d.hosts["a.test"]).toBe("2.2.2.2");
+    expect(Object.keys(d.hosts)).toHaveLength(1);
+  });
+
+  test("stores a wildcard by its suffix form", () => {
+    const d = upsert(doc(), "*.example.com", "1.1.1.1");
+    expect(d.wildcards).toEqual([{ suffix: ".example.com", ip: "1.1.1.1" }]);
+    expect(suffixOf("*.example.com")).toBe(".example.com");
+  });
+
+  /** Re-registering must replace, not append: ctx.dnsName allows it and a
+   *  re-run setup hook does it, so appending would grow the list without
+   *  bound and leave two entries racing on equal suffix length. */
+  test("re-registering a wildcard replaces rather than appends", () => {
+    let d = upsert(doc(), "*.example.com", "1.1.1.1");
+    d = upsert(d, "*.example.com", "2.2.2.2");
+    expect(d.wildcards).toHaveLength(1);
+    expect(lookup(d, "x.example.com")).toBe("2.2.2.2");
+  });
+
+  test("exact and wildcard registrations coexist", () => {
+    let d = upsert(doc(), "*.example.com", "1.1.1.1");
+    d = upsert(d, "api.example.com", "3.3.3.3");
+    expect(lookup(d, "api.example.com")).toBe("3.3.3.3");
+    expect(lookup(d, "other.example.com")).toBe("1.1.1.1");
+  });
+});

package/src/harness/names-registry.ts

@@ -0,0 +1,108 @@
+/**
+ * The DNS names registry: the file the harness writes and
+ * `spectest-resolver` reads.
+ *
+ * Ported out of `daemon.ts`. The point of a shared module is that this
+ * format had **two independent implementations** — the writer here and
+ * the reader in `resolver.ts` — with nothing keeping them in step. That
+ * is the same shape as the `config.rs` ↔ SDK drift the harness split
+ * exists to remove, just inside one language.
+ *
+ * The registry answers names that Docker's own DNS cannot:
+ *  - fake hostnames (`api.stripe.com` → the bridge gateway),
+ *  - names bound at runtime by `ctx.dnsName`,
+ *  - **wildcards** (`*.us-east-1.amazonaws.com`), which have no
+ *    `--add-host` or `--network-alias` equivalent and therefore *only*
+ *    exist here.
+ *
+ * Lookup is exact-first, then longest matching suffix — the same
+ * precedence the ingress routes and the SNI cert table use.
+ */
+
+export interface RegistryDoc {
+  /** Exact name → IP. */
+  hosts: Record<string, string>;
+  /** Suffix (with leading dot) → IP, longest match wins. */
+  wildcards: Array<{ suffix: string; ip: string }>;
+  /** Written by the harness; the resolver re-reads on mtime change, so
+   *  this is diagnostic rather than load-bearing. */
+  updatedAt?: number;
+}
+
+export const EMPTY_REGISTRY: RegistryDoc = { hosts: {}, wildcards: [] };
+
+/** Serialise for the resolver. */
+export function encodeRegistry(doc: RegistryDoc, now: number): string {
+  return JSON.stringify({
+    hosts: doc.hosts,
+    wildcards: doc.wildcards,
+    updatedAt: now,
+  });
+}
+
+/**
+ * Parse a registry file.
+ *
+ * Deliberately total: a truncated or malformed file yields an **empty**
+ * registry rather than throwing. The resolver reads this on a hot path
+ * while the harness may be rewriting it, and a parse error there would
+ * take out DNS for the whole environment — every name, not just the one
+ * being added. Degrading to "no custom names" is recoverable; the next
+ * successful read restores everything.
+ */
+export function decodeRegistry(text: string): RegistryDoc {
+  try {
+    const raw = JSON.parse(text) as Partial<RegistryDoc>;
+    const hosts =
+      raw.hosts && typeof raw.hosts === "object" ? (raw.hosts as Record<string, string>) : {};
+    const wildcards = Array.isArray(raw.wildcards)
+      ? raw.wildcards.filter(
+          (w): w is { suffix: string; ip: string } =>
+            !!w && typeof w.suffix === "string" && typeof w.ip === "string",
+        )
+      : [];
+    return { hosts, wildcards, updatedAt: raw.updatedAt };
+  } catch {
+    return { hosts: {}, wildcards: [] };
+  }
+}
+
+/** `"*.example.com"` → `".example.com"`, the form stored in `wildcards`. */
+export function suffixOf(pattern: string): string {
+  return pattern.startsWith("*.") ? pattern.slice(1) : pattern;
+}
+
+/**
+ * Resolve a name: exact entry first, then the longest matching wildcard
+ * suffix. Returns `null` when nothing matches, which is the resolver's
+ * signal to fall through to Docker's DNS and then upstream.
+ */
+export function lookup(doc: RegistryDoc, name: string): string | null {
+  const exact = doc.hosts[name];
+  if (exact) return exact;
+  let best: { suffix: string; ip: string } | null = null;
+  for (const w of doc.wildcards) {
+    if (name.endsWith(w.suffix) && (!best || w.suffix.length > best.suffix.length)) {
+      best = w;
+    }
+  }
+  return best?.ip ?? null;
+}
+
+/**
+ * Add or replace a name.
+ *
+ * A wildcard replaces any existing entry for the same suffix rather than
+ * appending, so re-registering a name (which `ctx.dnsName` allows, and
+ * which a re-run of a `setup` hook does) cannot grow the list without
+ * bound or leave two entries racing on equal suffix length.
+ */
+export function upsert(doc: RegistryDoc, hostname: string, ip: string): RegistryDoc {
+  if (hostname.startsWith("*.")) {
+    const suffix = suffixOf(hostname);
+    const wildcards = doc.wildcards.filter((w) => w.suffix !== suffix);
+    wildcards.push({ suffix, ip });
+    return { ...doc, wildcards };
+  }
+  return { ...doc, hosts: { ...doc.hosts, [hostname]: ip } };
+}