@specific.dev/spectest 0.38.0 → 0.41.0

package/src/harness/ingress-table.ts

@@ -0,0 +1,186 @@
+/**
+ * The live ingress tables: which hostname reaches which upstream, and
+ * which certificate serves the TLS handshake for it.
+ *
+ * Ported out of `daemon.ts` as part of the harness split. This module owns
+ * the *tables and the decisions*; the listeners themselves (`Bun.serve`)
+ * stay with the process that binds them, because a socket is not something
+ * you can hand across a module boundary usefully.
+ *
+ * ## Why this state is special
+ *
+ * These tables are ordinary module-scope objects, and that is the whole
+ * design. They live in the harness process, so they are captured by the
+ * memory snapshot and **fork with it** — exactly like fake state and the
+ * names registry. A `dependsOn` child inherits every route its parent
+ * bound; a sibling forked from an earlier snapshot never sees them. That
+ * is what lets a fake provision a real service mid-test and hand the app a
+ * CA-trusted `https://…` endpoint that only that branch of the test DAG
+ * can reach.
+ *
+ * The failure mode to design against is therefore *silence*: a route that
+ * fails to survive doesn't raise anything, it just isn't inherited, and
+ * the test that depended on it fails somewhere else entirely.
+ *
+ * ## The two rules worth stating
+ *
+ * **A route table is identified by its object, not its contents.** Every
+ * listener's request handler closes over the `Map` it was bound with, so
+ * adding an entry takes effect with no rebind — that is what makes a
+ * runtime route possible at all. Replacing the `Map` (rather than mutating
+ * it) silently orphans every listener still holding the old one, and the
+ * routes added afterwards go nowhere. {@link routesFor} is the only way to
+ * reach a table so that this can't be done by accident.
+ *
+ * **A rebind is not free, so it must be earned.** Bun fixes a server's TLS
+ * config at `Bun.serve` time — `reload` will not add an SNI entry — so a
+ * genuinely new certificate means stopping and re-serving :443. It's cheap
+ * (~1 ms) but it is a real interruption of live traffic, and a hostname
+ * already covered by an existing exact or wildcard cert needs nothing but a
+ * route entry. {@link planBind} is that judgement, separated from the
+ * mutation so it can be tested without a network stack.
+ */
+
+import { certCovers, isWildcard, wildcardSuffix } from "./hostmatch";
+
+/**
+ * One hostname's upstream: a fake handled in-process, or a container.
+ *
+ * Generic in the fake's runtime record so the harness keeps its own type
+ * through the tables — the alternative, `unknown` plus a cast at each
+ * dispatch site, would trade a real type for a comment.
+ */
+export type Route<F = unknown> =
+  | { kind: "fake"; fake: F }
+  | { kind: "proxy"; service: string; port: number };
+
+/** A PEM leaf + key, as handed to `Bun.serve`'s TLS config. */
+export interface Leaf {
+  cert: string;
+  key: string;
+}
+
+/**
+ * The mutable ingress state of one harness process.
+ *
+ * Held by the caller rather than this module so there is no hidden
+ * singleton: tests build one per case, and the harness holds exactly one.
+ */
+export interface IngressTables<F = unknown> {
+  /** Listen port → (hostname → route). Values are mutated in place. */
+  routesByPort: Map<number, Map<string, Route<F>>>;
+  /** SNI server name → leaf. Adding to this is what forces a rebind. */
+  certByHost: Map<string, Leaf>;
+}
+
+/** Fixed HTTPS port shared by every TLS route (fakes + service `tls`). */
+export const INGRESS_HTTPS_PORT = 443;
+/** Fixed HTTP port, always bound alongside :443 so both schemes work. */
+export const INGRESS_HTTP_PORT = 80;
+
+export function emptyTables<F = unknown>(): IngressTables<F> {
+  return { routesByPort: new Map(), certByHost: new Map() };
+}
+
+/**
+ * The route table for `port`, creating it if absent.
+ *
+ * Always returns the *same* object for a given port for as long as the
+ * tables live. Callers must mutate what they get back and must never swap
+ * in a replacement — see the module header for what that breaks.
+ */
+export function routesFor<F>(tables: IngressTables<F>, port: number): Map<string, Route<F>> {
+  let routes = tables.routesByPort.get(port);
+  if (!routes) {
+    routes = new Map<string, Route<F>>();
+    tables.routesByPort.set(port, routes);
+  }
+  return routes;
+}
+
+/** What binding `hostname` will require, before anything is mutated. */
+export interface BindPlan {
+  /** No existing cert covers the hostname, so a leaf must be minted. */
+  needsCert: boolean;
+  /** The :443 listener must be stopped and re-served. */
+  needsHttpsRebind: boolean;
+}
+
+/**
+ * Decide what binding `hostname` for TLS costs.
+ *
+ * A rebind is needed when a new certificate is going into the SNI table,
+ * or when :443 isn't listening yet. It is deliberately *not* needed for a
+ * hostname an existing wildcard already covers — the common case when a
+ * component claims a whole domain up front and services appear under it
+ * later, and the reason a fake can mint endpoints in a loop without
+ * restarting the listener once per iteration.
+ */
+export function planBind<F>(
+  tables: IngressTables<F>,
+  hostname: string,
+  opts: { httpsListening: boolean },
+): BindPlan {
+  const needsCert = !certCovers(tables.certByHost.keys(), hostname);
+  return { needsCert, needsHttpsRebind: needsCert || !opts.httpsListening };
+}
+
+/**
+ * Point `hostname` at `route` on both :80 and :443.
+ *
+ * Boot `tls` serves both schemes, and runtime `tls` matches it — a service
+ * reachable only over https would differ from its boot-time twin in a way
+ * nothing declares.
+ */
+export function bindRoute<F>(tables: IngressTables<F>, hostname: string, route: Route<F>): void {
+  routesFor(tables, INGRESS_HTTP_PORT).set(hostname, route);
+  routesFor(tables, INGRESS_HTTPS_PORT).set(hostname, route);
+}
+
+/**
+ * Drop `hostname`'s routes, so it 404s.
+ *
+ * The certificate is deliberately left in the SNI table: it is harmless
+ * without a route, and removing it would force an otherwise unnecessary
+ * :443 rebind at exactly the moment a service is going away.
+ */
+export function unbindRoute<F>(tables: IngressTables<F>, hostname: string): void {
+  tables.routesByPort.get(INGRESS_HTTP_PORT)?.delete(hostname);
+  tables.routesByPort.get(INGRESS_HTTPS_PORT)?.delete(hostname);
+}
+
+/** The SNI entries for `Bun.serve`'s TLS config. */
+export function certEntries<F>(
+  tables: IngressTables<F>,
+): Array<{ cert: string; key: string; serverName: string }> {
+  return [...tables.certByHost].map(([serverName, leaf]) => ({
+    cert: leaf.cert,
+    key: leaf.key,
+    serverName,
+  }));
+}
+
+/** Clear every table — used between `/load` calls so a new project's
+ *  routes bind against a clean slate rather than the old project's. */
+export function clearTables<F>(tables: IngressTables<F>): void {
+  tables.routesByPort.clear();
+  tables.certByHost.clear();
+}
+
+/**
+ * Point a hostname at an IP in a names registry document, choosing the
+ * exact or wildcard table by the hostname's shape.
+ *
+ * A wildcard has no `--add-host` or `--network-alias` equivalent, so the
+ * resolver's suffix table is the only place it can exist; an exact name
+ * could live in either, and goes in the exact table so it keeps winning
+ * over any wildcard that also matches.
+ */
+export function registryTarget(hostname: string): { wildcard: true; suffix: string } | {
+  wildcard: false;
+  host: string;
+} {
+  return isWildcard(hostname)
+    ? { wildcard: true, suffix: wildcardSuffix(hostname) }
+    : { wildcard: false, host: hostname };
+}

package/src/harness/log-delta.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, test } from "bun:test";
+
+import { capMiddle, streamDelta } from "./log-delta";
+
+describe("capMiddle", () => {
+  test("leaves short text alone", () => {
+    expect(capMiddle("hello", 100)).toEqual({ value: "hello", truncated: false });
+  });
+
+  /** Both ends are kept on purpose: the head has the startup banner, the
+   *  tail has whatever just failed. A tail-only cap loses the half that
+   *  usually explains the problem. */
+  test("keeps both ends and elides the middle", () => {
+    const s = "A".repeat(50) + "MIDDLE" + "Z".repeat(50);
+    const out = capMiddle(s, 20);
+    expect(out.truncated).toBe(true);
+    expect(out.value.startsWith("AAAA")).toBe(true);
+    expect(out.value.endsWith("ZZZZ")).toBe(true);
+    expect(out.value).not.toContain("MIDDLE");
+    expect(out.value).toContain("bytes elided");
+  });
+
+  test("reports how much was dropped", () => {
+    const out = capMiddle("x".repeat(1000), 100);
+    expect(out.value).toContain(`${1000 - 100} bytes elided`);
+  });
+
+  test("text exactly at the limit is not truncated", () => {
+    const out = capMiddle("x".repeat(100), 100);
+    expect(out.truncated).toBe(false);
+    expect(out.value).toHaveLength(100);
+  });
+});
+
+describe("streamDelta", () => {
+  test("a first read returns everything", () => {
+    const out = streamDelta("a\nb\nc\n", 0);
+    expect(out.delta).toBe("a\nb\nc\n");
+    expect(out.total).toBe(3);
+    expect(out.reset).toBe(false);
+  });
+
+  test("a later read returns only the new lines", () => {
+    const out = streamDelta("a\nb\nc\n", 2);
+    expect(out.delta).toBe("c\n");
+    expect(out.total).toBe(3);
+  });
+
+  test("no new lines yields an empty delta, not a repeat", () => {
+    const out = streamDelta("a\nb\n", 2);
+    expect(out.delta).toBe("");
+    expect(out.total).toBe(2);
+    expect(out.reset).toBe(false);
+  });
+
+  /** Docker's log can be read mid-write. Emitting a partial line would
+   *  corrupt the delta AND make the next capture repeat the other half,
+   *  because the marker counts whole lines. */
+  test("a partial trailing line is held back until it completes", () => {
+    const first = streamDelta("a\nb\npartial", 0);
+    expect(first.delta).toBe("a\nb\n");
+    expect(first.total).toBe(2);
+
+    const second = streamDelta("a\nb\npartial line now done\n", first.total);
+    expect(second.delta).toBe("partial line now done\n");
+    expect(second.total).toBe(3);
+  });
+
+  test("a log with no newline at all yields nothing", () => {
+    const out = streamDelta("no newline yet", 0);
+    expect(out.delta).toBe("");
+    expect(out.total).toBe(0);
+  });
+
+  /** A shorter log than the marker means the container restarted or the
+   *  log rotated: line N is no longer the line N we saw, so the whole
+   *  thing is new. */
+  test("a shrunken log is reported as a reset and replayed in full", () => {
+    const out = streamDelta("fresh\n", 10);
+    expect(out.reset).toBe(true);
+    expect(out.delta).toBe("fresh\n");
+    expect(out.total).toBe(1);
+  });
+
+  test("a marker beyond the end yields nothing rather than throwing", () => {
+    // Equal to total: nothing new, and not a reset.
+    const out = streamDelta("a\nb\n", 2);
+    expect(out.delta).toBe("");
+    expect(out.reset).toBe(false);
+  });
+
+  test("an empty log is handled", () => {
+    const out = streamDelta("", 0);
+    expect(out.delta).toBe("");
+    expect(out.total).toBe(0);
+    expect(out.reset).toBe(false);
+  });
+
+  test("blank lines are counted like any other", () => {
+    const out = streamDelta("a\n\n\nb\n", 1);
+    expect(out.delta).toBe("\n\nb\n");
+    expect(out.total).toBe(4);
+  });
+
+  test("successive captures never overlap or drop a line", () => {
+    let marker = 0;
+    let log = "";
+    const seen: string[] = [];
+    for (const chunk of [["l1", "l2"], ["l3"], [], ["l4", "l5", "l6"]]) {
+      log += chunk.map((l) => `${l}\n`).join("");
+      const out = streamDelta(log, marker);
+      marker = out.total;
+      if (out.delta) seen.push(out.delta);
+    }
+    expect(seen.join("")).toBe("l1\nl2\nl3\nl4\nl5\nl6\n");
+  });
+
+  test("a very large delta is truncated but still reports the true total", () => {
+    const big = "x".repeat(5 * 1024 * 1024) + "\n";
+    const out = streamDelta(big, 0);
+    expect(out.truncated).toBe(true);
+    expect(out.total).toBe(1);
+    expect(out.delta.length).toBeLessThan(big.length);
+  });
+});

package/src/harness/log-delta.ts

@@ -0,0 +1,100 @@
+/**
+ * Per-case service-log deltas.
+ *
+ * A container's log is cumulative, but the dashboard shows each test case
+ * only the lines *it* produced — the branch's full log is reconstructed by
+ * concatenating the deltas along the `dependsOn` chain. So every capture
+ * records how far it read (a line marker), and the next capture returns
+ * only what came after.
+ *
+ * The markers live in harness process memory, which means they fork with
+ * the snapshot exactly like fake state: a `dependsOn` child continues from
+ * where its parent stopped, and a sibling forked from an earlier snapshot
+ * sees the parent's lines again — which is correct, because for that
+ * sibling they *are* new.
+ *
+ * Ported out of `daemon.ts`; pure, so the boundary cases below are
+ * testable rather than inferred.
+ */
+
+/** Cap on one delta. Beyond this the middle is elided, not the tail. */
+export const LOG_DELTA_MAX_BYTES = 2 * 1024 * 1024;
+
+/**
+ * Truncate from the **middle**, keeping both ends.
+ *
+ * Deliberately not a tail cap: the head of a service log carries the
+ * startup banner (bind address, version, config errors) and the tail
+ * carries whatever just failed. Dropping either loses the half that
+ * usually explains the problem.
+ */
+export function capMiddle(s: string, max: number): { value: string; truncated: boolean } {
+  if (s.length <= max) return { value: s, truncated: false };
+  const half = Math.floor(max / 2);
+  const elided = s.length - 2 * half;
+  return {
+    value: `${s.slice(0, half)}\n… [${elided} bytes elided] …\n${s.slice(s.length - half)}`,
+    truncated: true,
+  };
+}
+
+export interface StreamDelta {
+  /** The new lines, possibly middle-elided. */
+  delta: string;
+  /** Line count after this capture — the next call's marker. */
+  total: number;
+  /**
+   * The stream got *shorter* than the marker, so the container was
+   * restarted or its log rotated. The delta is then the whole log rather
+   * than a suffix, because line N is no longer the line N we saw.
+   */
+  reset: boolean;
+  truncated: boolean;
+}
+
+/**
+ * The portion of `full` after line `marker`.
+ *
+ * Only **complete** lines are returned. A partial trailing line is held
+ * back deliberately: docker's log stream can be read mid-write, and
+ * emitting half a line would both corrupt the delta and mean the next
+ * capture repeats the other half, since the marker counts lines.
+ */
+export function streamDelta(full: string, marker: number): StreamDelta {
+  const lastNl = full.lastIndexOf("\n");
+  const complete = lastNl < 0 ? "" : full.slice(0, lastNl + 1);
+
+  let total = 0;
+  for (let i = 0; i < complete.length; i++) {
+    if (complete.charCodeAt(i) === 10) total++;
+  }
+
+  // Fewer lines than we had already read means this is not the same log.
+  let reset = false;
+  let startLine = marker;
+  if (total < marker) {
+    reset = true;
+    startLine = 0;
+  }
+
+  let delta: string;
+  if (startLine <= 0) {
+    delta = complete;
+  } else if (startLine >= total) {
+    delta = "";
+  } else {
+    // Byte offset just past the `startLine`-th newline.
+    let seen = 0;
+    let off = 0;
+    for (let i = 0; i < complete.length; i++) {
+      if (complete.charCodeAt(i) === 10 && ++seen === startLine) {
+        off = i + 1;
+        break;
+      }
+    }
+    delta = complete.slice(off);
+  }
+
+  const capped = capMiddle(delta, LOG_DELTA_MAX_BYTES);
+  return { delta: capped.value, total, reset, truncated: capped.truncated };
+}

package/src/harness/main.test.ts

@@ -0,0 +1,211 @@
+/**
+ * The frame transport, driven over a real duplex stream.
+ *
+ * `handlers()` takes its method table as a parameter so these can run
+ * without importing `daemon.ts`, which would pull in dockerd clients, a
+ * browser and an HTTP listener to test a dispatch loop.
+ */
+import { describe, expect, test } from "bun:test";
+
+import { handlers, serve } from "./main";
+import { conflict, notFound, type MethodTable } from "./methods";
+import { PROTOCOL_VERSION, encodeFrame, type Frame } from "./protocol";
+
+/**
+ * Drive `serve` over a stand-in socket and collect what it writes back.
+ *
+ * The two directions have to stay separate: a duplex whose write side feeds
+ * its own read side would echo every request straight back as if it were a
+ * reply, and every assertion below would be reading its own input.
+ */
+function harness(methods: MethodTable, onShutdown = () => {}) {
+  const readers: Array<(chunk: Buffer | string) => void> = [];
+  const frames: Frame[] = [];
+  const socket = {
+    on(event: string, cb: (chunk: Buffer | string) => void) {
+      if (event === "data") readers.push(cb);
+      return socket;
+    },
+    write(chunk: string) {
+      for (const line of chunk.split("\n")) {
+        if (line.trim()) frames.push(JSON.parse(line) as Frame);
+      }
+      return true;
+    },
+  } as unknown as NodeJS.ReadWriteStream;
+
+  serve(socket, handlers("9.9.9", onShutdown, methods as never));
+
+  return {
+    send: (frame: Frame | string) => {
+      const line = typeof frame === "string" ? `${frame}\n` : encodeFrame(frame);
+      for (const r of readers) r(line);
+    },
+    frames,
+    /** Wait for the reply to `id`, so tests never race the event loop. */
+    async reply(id: string): Promise<any> {
+      for (let i = 0; i < 200; i++) {
+        const f = frames.find((x) => (x as { id?: string }).id === id);
+        if (f) return f;
+        await Bun.sleep(1);
+      }
+      throw new Error(`no reply for ${id}; got ${JSON.stringify(frames)}`);
+    },
+  };
+}
+
+const request = (id: string, method: string, params: Record<string, unknown> = {}) =>
+  ({ kind: "request", id, method, params }) as unknown as Frame;
+
+describe("dispatch", () => {
+  test("serves a method from the table and returns its result", async () => {
+    const h = harness({ cases: async () => ({ cases: [{ id: "a" }] }) });
+    h.send(request("1", "cases"));
+    expect(await h.reply("1")).toMatchObject({
+      kind: "response",
+      ok: true,
+      result: { cases: [{ id: "a" }] },
+    });
+  });
+
+  test("passes params through", async () => {
+    const h = harness({ run: async (p) => ({ ran: p.caseId }) });
+    h.send(request("1", "run", { caseId: "case-7" }));
+    expect((await h.reply("1")).result).toEqual({ ran: "case-7" });
+  });
+
+  test("answers the handshake without touching the table", async () => {
+    const h = harness({});
+    h.send(request("1", "hello"));
+    expect((await h.reply("1")).result).toMatchObject({
+      protocolVersion: PROTOCOL_VERSION,
+      sdkVersion: "9.9.9",
+    });
+  });
+
+  /** An unknown method must answer, not hang. A request that never gets a
+   *  reply is indistinguishable from a wedged environment. */
+  test("an unknown method is refused by name", async () => {
+    const h = harness({});
+    h.send(request("1", "nonesuch"));
+    const r = await h.reply("1");
+    expect(r).toMatchObject({ ok: false, error: { code: "unimplemented" } });
+    expect(r.error.message).toContain("nonesuch");
+  });
+
+  test("replies are correlated, so concurrent requests can't be confused", async () => {
+    const h = harness({
+      slow: async () => {
+        await Bun.sleep(20);
+        return { which: "slow" };
+      },
+      fast: async () => ({ which: "fast" }),
+    });
+    h.send(request("slow-1", "slow"));
+    h.send(request("fast-1", "fast"));
+    expect((await h.reply("fast-1")).result).toEqual({ which: "fast" });
+    expect((await h.reply("slow-1")).result).toEqual({ which: "slow" });
+  });
+
+  test("several frames arriving in one chunk are all served", async () => {
+    const h = harness({ ping: async () => ({ pong: true }) });
+    h.send(request("1", "ping"));
+    h.send(request("2", "ping"));
+    expect((await h.reply("1")).ok).toBe(true);
+    expect((await h.reply("2")).ok).toBe(true);
+  });
+});
+
+describe("failures", () => {
+  /** A refusal the method meant to make carries its kind, so the control
+   *  plane can tell "you asked for something that isn't here" from "the
+   *  harness broke". */
+  test("a deliberate refusal keeps its kind and message", async () => {
+    const h = harness({
+      run: async () => {
+        throw notFound("unknown caseId: nope");
+      },
+    });
+    h.send(request("1", "run"));
+    expect(await h.reply("1")).toMatchObject({
+      ok: false,
+      error: { code: "not_found", message: "unknown caseId: nope" },
+    });
+  });
+
+  test("a conflict is reported as such, not as a crash", async () => {
+    const h = harness({
+      run: async () => {
+        throw conflict("another test is already running");
+      },
+    });
+    h.send(request("1", "run"));
+    expect(await h.reply("1")).toMatchObject({ ok: false, error: { code: "conflict" } });
+  });
+
+  /** An unexpected throw is a bug in the method, and the stack is the only
+   *  place that information exists — the control plane cannot get it any
+   *  other way once the fork is gone. */
+  test("an unexpected error carries its stack", async () => {
+    const h = harness({
+      run: async () => {
+        throw new Error("boom");
+      },
+    });
+    h.send(request("1", "run"));
+    const r = await h.reply("1");
+    expect(r.error.code).toBe("handler_error");
+    expect(r.error.message).toContain("boom");
+    expect(r.error.message).toContain("at ");
+  });
+
+  /** The harness holds the environment's only copy of its live state, so a
+   *  failing request must never be allowed to end the process. */
+  test("a failing method leaves the harness serving", async () => {
+    const h = harness({
+      bad: async () => {
+        throw new Error("boom");
+      },
+      good: async () => ({ fine: true }),
+    });
+    h.send(request("1", "bad"));
+    await h.reply("1");
+    h.send(request("2", "good"));
+    expect((await h.reply("2")).result).toEqual({ fine: true });
+  });
+
+  /** Garbage on the wire has no id to answer on, so the only safe thing is
+   *  to keep serving the connection rather than tear it down. */
+  test("an undecodable frame does not break the connection", async () => {
+    const h = harness({ good: async () => ({ fine: true }) });
+    h.send("{not json");
+    h.send(request("2", "good"));
+    expect((await h.reply("2")).result).toEqual({ fine: true });
+  });
+});
+
+describe("transport methods cannot be shadowed", () => {
+  /** A method table that could override `shutdown` would produce an
+   *  environment the supervisor cannot stop. */
+  test("a table's shutdown does not replace the real one", async () => {
+    let stopped = false;
+    const h = harness(
+      { shutdown: async () => ({ hijacked: true }) },
+      () => {
+        stopped = true;
+      },
+    );
+    h.send(request("1", "shutdown"));
+    expect((await h.reply("1")).result).toEqual({});
+    await Bun.sleep(5);
+    expect(stopped).toBe(true);
+  });
+
+  test("a table's hello does not replace the handshake", async () => {
+    const h = harness({ hello: async () => ({ protocolVersion: 999 }) });
+    h.send(request("1", "hello"));
+    expect((await h.reply("1")).result).toMatchObject({
+      protocolVersion: PROTOCOL_VERSION,
+    });
+  });
+});