@specific.dev/spectest 0.39.0 → 0.41.0

package/src/redis.ts

@@ -0,0 +1,202 @@
+// `RedisClient` — a drop-in for `Bun.RedisClient` (`Bun.redis`) that records
+// every command on the test event log and returns its reply inspect-wrapped,
+// so `expect(await client.get("k"))` links the assertion back to the command in
+// the timeline (same provenance mechanism as the wrapped `fetch` / `SQL`). Swap
+// `new Bun.RedisClient(url)` → `new RedisClient(url)` and nothing else changes
+// at the call site; replies come back `Wrapped<T>` (that wrapper is what carries
+// provenance), so `.unwrap()` before a `===` or before feeding a value onward.
+//
+// Reach for it in service `helpers` when you stand up a redis/valkey yourself,
+// or directly in a test against a connection string a fake handed back.
+
+import { recordRedis, reserveEvent, safeSerialize } from "./recorder.js";
+import { wrap } from "./inspect.js";
+import type { Wrapped } from "./inspect.js";
+
+/**
+ * Structural type for the parts of `Bun.RedisClient` we use, declared locally
+ * so user projects don't need `@types/bun`. The real implementation comes from
+ * Bun at runtime via `globalThis.Bun.RedisClient`. Commands resolve to their
+ * reply; lifecycle methods (`connect`/`close`/`subscribe`/…) are passed through
+ * un-instrumented.
+ */
+interface RawRedisClient {
+  send(command: string, args: string[]): Promise<unknown>;
+  close?(): void;
+  [method: string]: unknown;
+}
+
+/** The instrumented Redis surface — same shape as `Bun.RedisClient`, but every
+ *  command resolves to a {@link Wrapped} reply recorded as a `redis` event.
+ *  Indexable so every Bun command method is reachable without re-declaring the
+ *  whole (large) surface; the common ones are typed for ergonomics. */
+export interface RedisClientLike {
+  get(key: string): Promise<Wrapped<string | null>>;
+  set(key: string, value: string): Promise<Wrapped<string>>;
+  del(...keys: string[]): Promise<Wrapped<number>>;
+  exists(...keys: string[]): Promise<Wrapped<number>>;
+  incr(key: string): Promise<Wrapped<number>>;
+  hgetall(key: string): Promise<Wrapped<Record<string, string>>>;
+  /** Run an arbitrary command — `client.send("SET", ["k", "v"])`. */
+  send(command: string, args: string[]): Promise<Wrapped<unknown>>;
+  close(): void;
+  [method: string]: (...args: any[]) => any;
+}
+
+/** Options accepted by the {@link RedisClient} constructor beyond Bun's own. */
+export interface RedisOptions {
+  /** Label shown on each recorded `redis` event (the timeline step's tag).
+   *  Defaults to the connection URL's host (usually the service name). */
+  label?: string;
+}
+
+interface BunGlobal {
+  RedisClient: new (url?: string, options?: unknown) => RawRedisClient;
+}
+
+interface RedisConstructor {
+  new (url?: string, opts?: RedisOptions): RedisClientLike;
+  (url?: string, opts?: RedisOptions): RedisClientLike;
+}
+
+// Long-lived / connection-management methods that don't map to a single
+// request→reply step — passed straight through, never recorded.
+const REDIS_PASSTHROUGH = new Set([
+  "connect",
+  "close",
+  "disconnect",
+  "duplicate",
+  "subscribe",
+  "unsubscribe",
+  "psubscribe",
+  "punsubscribe",
+  "ssubscribe",
+  "sunsubscribe",
+  "onclose",
+  "ref",
+  "unref",
+]);
+
+const MAX_RESULT_BYTES = 2048;
+
+/**
+ * Open an instrumented Redis client against `url` (default: Bun's own
+ * `REDIS_URL`/`VALKEY_URL`). Usable with or without `new`. Requires the Bun
+ * runtime — it runs inside the spectest daemon.
+ */
+export const RedisClient = function RedisClient(
+  url?: string,
+  opts?: RedisOptions,
+): RedisClientLike {
+  const bun = (globalThis as unknown as { Bun?: BunGlobal }).Bun;
+  if (!bun?.RedisClient) {
+    throw new Error(
+      "RedisClient requires the Bun runtime (Bun >= 1.2.9) — it runs inside the spectest daemon.",
+    );
+  }
+  const raw = url !== undefined ? new bun.RedisClient(url, opts) : new bun.RedisClient();
+  return instrumentRedis(raw, opts?.label ?? hostLabel(url));
+} as unknown as RedisConstructor;
+
+function hostLabel(url?: string): string {
+  if (!url) return "redis";
+  try {
+    return new URL(url).hostname || "redis";
+  } catch {
+    return "redis";
+  }
+}
+
+/**
+ * Proxy a `Bun.RedisClient` so each command method (and `send(...)`) emits a
+ * `redis` event when its promise settles and resolves to a {@link Wrapped}
+ * reply. Lifecycle methods and non-function properties pass through.
+ *
+ * Exported so a client built another way can opt into the same instrumentation.
+ */
+export function instrumentRedis(raw: RawRedisClient, label: string): RedisClientLike {
+  const run = (
+    command: string,
+    key: string | undefined,
+    extra: unknown[],
+    invoke: () => unknown,
+  ): Promise<unknown> => {
+    const started = Date.now();
+    const resv = reserveEvent();
+    return Promise.resolve(invoke()).then(
+      (value) => {
+        const { preview, truncated } = capValue(value);
+        const seq = recordRedis(
+          {
+            service: label,
+            command,
+            key,
+            args: extra.length > 0 ? extra.map(safeSerialize) : undefined,
+            result: preview,
+            resultTruncated: truncated,
+            durationMs: Date.now() - started,
+          },
+          resv,
+        );
+        return wrap(value, seq);
+      },
+      (err) => {
+        const e = err as Error;
+        recordRedis(
+          {
+            service: label,
+            command,
+            key,
+            args: extra.length > 0 ? extra.map(safeSerialize) : undefined,
+            durationMs: Date.now() - started,
+            error: e?.message ?? String(err),
+          },
+          resv,
+        );
+        throw err;
+      },
+    );
+  };
+
+  const handler: ProxyHandler<RawRedisClient> = {
+    get(target, prop, receiver) {
+      if (typeof prop !== "string") return Reflect.get(target, prop, receiver);
+      const v = Reflect.get(target, prop, receiver);
+      if (typeof v !== "function") return v;
+      const fn = v as (...a: unknown[]) => unknown;
+      if (REDIS_PASSTHROUGH.has(prop)) return fn.bind(target);
+      // `send(command, args)` carries the real command in its first arg.
+      if (prop === "send") {
+        return (command: string, args: string[] = []) =>
+          run(String(command).toUpperCase(), args[0], args.slice(1), () =>
+            fn.call(target, command, args),
+          );
+      }
+      return (...args: unknown[]) =>
+        run(
+          prop.toUpperCase(),
+          typeof args[0] === "string" ? args[0] : undefined,
+          args.slice(1),
+          () => fn.apply(target, args),
+        );
+    },
+  };
+  return new Proxy(raw, handler) as unknown as RedisClientLike;
+}
+
+/** Best-effort JSON-safe preview of a reply, capped at {@link MAX_RESULT_BYTES}. */
+function capValue(value: unknown): { preview?: unknown; truncated?: boolean } {
+  if (value === null || value === undefined) return {};
+  const safe = safeSerialize(value);
+  const json = (() => {
+    try {
+      return JSON.stringify(safe);
+    } catch {
+      return undefined;
+    }
+  })();
+  if (json !== undefined && json.length > MAX_RESULT_BYTES) {
+    return { preview: `${json.slice(0, MAX_RESULT_BYTES)}…`, truncated: true };
+  }
+  return { preview: safe };
+}

package/src/replay-bundle.ts

@@ -0,0 +1,108 @@
+// Replay-bundle encoding: a case's rrweb sessions → one gzipped JSON blob
+// with large inlined assets deduplicated.
+//
+// Why this exists: recordings must NOT ride the `/run` response. The
+// vm-agent proxies daemon HTTP through a 16 MB response cap, and a
+// browser-heavy case blows straight past it — rrweb's `inlineImages`
+// re-inlines every image into every full snapshot, and animation-heavy
+// apps (e.g. Reanimated's per-frame inline-style writes) emit mutation
+// streams in the tens of MB. The daemon parks the encoded bundle in
+// memory instead and the control plane pulls it in chunks via
+// `POST /replay-chunk` (see daemon.ts), each chunk sized under the cap.
+//
+// Inside the bundle, every large base64 `data:` URI is extracted into an
+// `assets` table keyed by content hash and replaced with a
+// `data:x-spectest-asset/<hash>` token — the N re-inlined copies of one
+// image collapse to one asset plus N short tokens. The dashboard's case
+// viewer substitutes the real URI back into the raw JSON text before
+// parsing (mirror of this file's token format lives in
+// `web/case_viewer.rs::rehydrateAssets`). Only base64 URIs are extracted:
+// their charset needs no JSON escaping, so plain text substitution in
+// either direction cannot corrupt the surrounding JSON document.
+
+import { createHash } from "node:crypto";
+import { gzipSync } from "node:zlib";
+
+/** Minimum data: URI payload length (chars) worth extracting. Below this
+ * the token + asset-table overhead rivals the URI itself. */
+const ASSET_MIN_BASE64_CHARS = 1024;
+
+/** Base64 `data:` URIs, ≥1 KiB of payload. Mediatype + parameters are
+ * restricted to charsets that never need JSON escaping — a match taken
+ * from serialized JSON text is therefore byte-identical to the logical
+ * string value it sits inside. */
+const ASSET_RX = new RegExp(
+  "data:[A-Za-z0-9.+-]+/[A-Za-z0-9.+-]+(?:;[A-Za-z0-9.=+-]+)*;base64," +
+    `[A-Za-z0-9+/=]{${ASSET_MIN_BASE64_CHARS},}`,
+  "g",
+);
+
+/** Token an extracted asset is replaced with. Still a syntactically valid
+ * data: URI so anything that merely carries it along stays well-formed;
+ * it never renders (the viewer rehydrates before the events reach rrweb). */
+export function assetToken(hash: string): string {
+  return `data:x-spectest-asset/${hash}`;
+}
+
+/**
+ * Serialize `sessions` and pull every large base64 data: URI out into a
+ * content-addressed asset table. Returns the deduplicated sessions as a
+ * JSON *string* (already serialized — splice it into the bundle document
+ * verbatim) plus the asset table.
+ */
+export function extractReplayAssets(sessions: unknown): {
+  sessionsJson: string;
+  assets: Record<string, string>;
+} {
+  const assets: Record<string, string> = {};
+  const raw = JSON.stringify(sessions);
+  const sessionsJson = raw.replace(ASSET_RX, (uri) => {
+    // 16 hex chars (64 bits) of SHA-256: collision-safe at replay-asset
+    // scale (dozens of assets per case), and short enough that a token is
+    // negligible next to the URI it replaces.
+    const hash = createHash("sha256").update(uri).digest("hex").slice(0, 16);
+    assets[hash] = uri;
+    return assetToken(hash);
+  });
+  return { sessionsJson, assets };
+}
+
+/**
+ * Encode a case's sessions as the gzipped replay-bundle document the
+ * control plane archives to S3 verbatim:
+ * `{ caseId, sessions: [...], assets: { <hash>: <dataUri> } }` — the
+ * shape of `storage.rs::CaseReplayBundle`.
+ */
+export function encodeReplayBundle(caseId: string, sessions: unknown): Buffer {
+  const { sessionsJson, assets } = extractReplayAssets(sessions);
+  const doc = `{"caseId":${JSON.stringify(caseId)},"sessions":${sessionsJson},"assets":${JSON.stringify(assets)}}`;
+  return gzipSync(Buffer.from(doc));
+}
+
+/** Per-chunk raw-byte ceiling for `/replay-chunk` replies. Base64 inflates
+ * 4/3× and the JSON reply must clear the vm-agent's 16 MB response cap
+ * with headroom. The control plane's `fetch_replay_bundle` requests
+ * exactly this much per round trip. */
+export const REPLAY_CHUNK_MAX_BYTES = 6 * 1024 * 1024;
+
+/**
+ * One `/replay-chunk` reply: base64 of `gz[offset, offset+limit)`, with
+ * offset/limit clamped to sane values (never more than
+ * `REPLAY_CHUNK_MAX_BYTES` raw bytes). An out-of-range offset yields an
+ * empty `b64`, which the control plane treats as an error — it only ever
+ * asks for offsets below the advertised total.
+ */
+export function replayChunk(
+  gz: Buffer,
+  offsetIn: unknown,
+  limitIn: unknown,
+): { total: number; offset: number; b64: string } {
+  const offset = Math.max(0, Math.floor(Number(offsetIn) || 0));
+  const wanted = Math.floor(Number(limitIn) || REPLAY_CHUNK_MAX_BYTES);
+  const limit = Math.min(Math.max(1, wanted), REPLAY_CHUNK_MAX_BYTES);
+  return {
+    total: gz.length,
+    offset,
+    b64: gz.subarray(offset, offset + limit).toString("base64"),
+  };
+}

package/src/resolver.ts

@@ -0,0 +1,348 @@
+// spectest-resolver: a tiny DNS server that mirrors Docker's embedded
+// DNS, but from the VM host instead of from inside a container.
+//
+// Single-label lookups (no dots, e.g. `api`) hit the Docker socket by
+// container name. Multi-label lookups (e.g. `api.stripe.com`) scan
+// containers on `spectest-net` for one whose network aliases include the
+// queried name — set via service `hostnames` in env.ts. Anything we
+// can't resolve from Docker is forwarded to an upstream DNS server
+// (default 1.1.1.1). The daemon and any test code running on the VM
+// host can do `fetch("http://api:8000")` or `fetch("http://api.stripe.com")`
+// exactly like a container on the same bridge would.
+//
+// Designed to be tiny: one process, no caching beyond DNS TTL (5s), no
+// docker event subscription — every query asks Docker fresh. The latency
+// is ~1ms per query and the failure mode (Docker socket down) is rare
+// enough that simplicity wins.
+//
+// Listens on two *specific* addresses (never 0.0.0.0 — see the bind logic
+// at the bottom): 127.0.0.53, the nameserver the VM's /etc/resolv.conf
+// points at (daemon, host-side test code, and dockerd's embedded DNS as
+// its ExtServer all use it), and the spectest-net bridge gateway IP,
+// which is how an in-cluster k3s pod reaches us (k3s CoreDNS is pointed
+// there; see components/k3s.ts). Binding the specific gateway IP rather
+// than 0.0.0.0 matters: a 0.0.0.0 socket replies to a 127.0.0.53 query
+// from a kernel-chosen source (127.0.0.1), and glibc's resolver drops the
+// answer because its source doesn't match the queried server.
+
+import { createSocket, type RemoteInfo } from "node:dgram";
+import { request as httpRequest } from "node:http";
+import { readFile, stat } from "node:fs/promises";
+import { lookup } from "./harness/names-registry.js";
+import * as dnsPacket from "dns-packet";
+
+const NETWORK_NAME = process.env.SPECTEST_NETWORK ?? "spectest-net";
+const DOCKER_SOCKET = process.env.DOCKER_SOCKET ?? "/var/run/docker.sock";
+const UPSTREAM_DNS = process.env.SPECTEST_UPSTREAM_DNS ?? "1.1.1.1";
+const UPSTREAM_PORT = Number(process.env.SPECTEST_UPSTREAM_PORT ?? "53");
+// Primary listen address: the loopback nameserver in the VM's
+// /etc/resolv.conf. Always bound at startup.
+const LISTEN_ADDR = process.env.SPECTEST_RESOLVER_ADDR ?? "127.0.0.53";
+const LISTEN_PORT = Number(process.env.SPECTEST_RESOLVER_PORT ?? "53");
+const TTL_SECONDS = Number(process.env.SPECTEST_RESOLVER_TTL ?? "5");
+/** Path the harness writes when it brings fakes up. */
+const FAKES_REGISTRY_PATH =
+  process.env.SPECTEST_FAKES_REGISTRY ?? "/run/spectest-fakes.json";
+
+function dockerGet(path: string): Promise<unknown | null> {
+  return new Promise((resolve) => {
+    const req = httpRequest(
+      { socketPath: DOCKER_SOCKET, path, method: "GET" },
+      (res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          resolve(null);
+          return;
+        }
+        const chunks: Buffer[] = [];
+        res.on("data", (c) => chunks.push(c));
+        res.on("end", () => {
+          try {
+            resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+          } catch {
+            resolve(null);
+          }
+        });
+        res.on("error", () => resolve(null));
+      },
+    );
+    req.on("error", () => resolve(null));
+    req.end();
+  });
+}
+
+/**
+ * Single-label lookup: ask Docker for the container with this exact name
+ * and read its IP on spectest-net. Cheap — one container fetch.
+ */
+async function dockerLookupByName(name: string): Promise<string | null> {
+  const body = (await dockerGet(`/containers/${encodeURIComponent(name)}/json`)) as
+    | { NetworkSettings?: { Networks?: Record<string, { IPAddress?: string }> } }
+    | null;
+  const ip = body?.NetworkSettings?.Networks?.[NETWORK_NAME]?.IPAddress;
+  return ip && ip.length > 0 ? ip : null;
+}
+
+/**
+ * Multi-label lookup: scan containers on spectest-net for one whose
+ * Aliases include `name`. Aliases are set with `--network-alias` at
+ * `docker run` time (see runContainer in daemon.ts).
+ *
+ * `/containers/json` returns `Aliases: null` in many Docker versions
+ * even when --network-alias was set, so we use it only to enumerate
+ * container IDs and then inspect each one — inspect reliably surfaces
+ * the alias list. The fan-out is bounded by service count (~handful),
+ * so the extra roundtrips are cheap.
+ */
+async function dockerLookupByAlias(name: string): Promise<string | null> {
+  const filters = encodeURIComponent(JSON.stringify({ network: [NETWORK_NAME] }));
+  const list = (await dockerGet(`/containers/json?filters=${filters}`)) as
+    | Array<{ Id?: string }>
+    | null;
+  if (!Array.isArray(list)) return null;
+  for (const c of list) {
+    if (!c.Id) continue;
+    const info = (await dockerGet(`/containers/${c.Id}/json`)) as
+      | { NetworkSettings?: { Networks?: Record<string, { Aliases?: string[]; IPAddress?: string }> } }
+      | null;
+    const net = info?.NetworkSettings?.Networks?.[NETWORK_NAME];
+    if (!net) continue;
+    if ((net.Aliases ?? []).includes(name) && net.IPAddress) {
+      return net.IPAddress;
+    }
+  }
+  return null;
+}
+
+// Cache the names registry file by mtime so we re-read only when the
+// daemon has rewritten it (at /bootstrap, and live whenever a test calls
+// ctx.dnsName). A miss returns empty tables — the registry is optional,
+// and the daemon may not have written the file yet on a fresh boot.
+//
+// `hosts` are exact hostname → IP (fakes, TLS proxies, dnsName(→ingress),
+// dynamic exact registrations). `wildcards` are suffix → IP, e.g.
+// `*.example.com` stored as `{ suffix: ".example.com", ip }`; matched only
+// after exact lookups (registry + docker) miss, so an exact name always
+// wins over a wildcard.
+interface RegistryCache {
+  mtimeMs: number;
+  hosts: Record<string, string>;
+  wildcards: Array<{ suffix: string; ip: string }>;
+}
+let registryCache: RegistryCache = { mtimeMs: 0, hosts: {}, wildcards: [] };
+
+async function refreshRegistry(): Promise<void> {
+  try {
+    const st = await stat(FAKES_REGISTRY_PATH);
+    if (st.mtimeMs !== registryCache.mtimeMs) {
+      const raw = await readFile(FAKES_REGISTRY_PATH, "utf8");
+      const parsed = JSON.parse(raw) as {
+        hosts?: Record<string, string>;
+        wildcards?: Array<{ suffix: string; ip: string }>;
+      };
+      registryCache = {
+        mtimeMs: st.mtimeMs,
+        hosts: parsed.hosts ?? {},
+        wildcards: parsed.wildcards ?? [],
+      };
+    }
+  } catch {
+    // File missing or unreadable — treat as empty.
+    registryCache = { mtimeMs: 0, hosts: {}, wildcards: [] };
+  }
+}
+
+/** Exact names-registry lookup. */
+async function lookupFake(name: string): Promise<string | null> {
+  await refreshRegistry();
+  return registryCache.hosts[name] ?? null;
+}
+
+/** Wildcard suffix lookup — consulted only after an exact miss. The
+ *  longest (most specific) matching suffix wins. */
+async function lookupWildcard(name: string): Promise<string | null> {
+  await refreshRegistry();
+  // Same module the harness writes with, so the two halves of this file
+  // format cannot drift apart.
+  return lookup({ hosts: {}, wildcards: registryCache.wildcards }, name);
+}
+
+async function forwardUpstream(query: Buffer): Promise<Buffer | null> {
+  return new Promise((resolve) => {
+    const sock = createSocket("udp4");
+    let done = false;
+    const finish = (b: Buffer | null) => {
+      if (done) return;
+      done = true;
+      try {
+        sock.close();
+      } catch {
+        // ignore
+      }
+      resolve(b);
+    };
+    sock.on("message", (msg) => finish(msg));
+    sock.on("error", () => finish(null));
+    sock.send(query, UPSTREAM_PORT, UPSTREAM_DNS, (err) => {
+      if (err) finish(null);
+    });
+    setTimeout(() => finish(null), 3_000);
+  });
+}
+
+function emptyAnswer(query: dnsPacket.Packet): Buffer {
+  return dnsPacket.encode({
+    type: "response",
+    id: query.id,
+    flags: dnsPacket.AUTHORITATIVE_ANSWER | dnsPacket.RECURSION_DESIRED,
+    questions: query.questions,
+    answers: [],
+  });
+}
+
+function aAnswer(query: dnsPacket.Packet, name: string, ip: string): Buffer {
+  return dnsPacket.encode({
+    type: "response",
+    id: query.id,
+    flags: dnsPacket.AUTHORITATIVE_ANSWER | dnsPacket.RECURSION_DESIRED,
+    questions: query.questions,
+    answers: [{ type: "A", name, ttl: TTL_SECONDS, data: ip }],
+  });
+}
+
+// Shared query handler. Replies are sent back through the *same* socket
+// the query arrived on so the reply's source address matches the address
+// the client sent to — which is why each listener is bound to a specific
+// IP rather than 0.0.0.0 (glibc drops answers whose source differs from
+// the queried server).
+async function handleQuery(
+  sock: ReturnType<typeof createSocket>,
+  msg: Buffer,
+  rinfo: RemoteInfo,
+): Promise<void> {
+  let query: dnsPacket.Packet;
+  try {
+    query = dnsPacket.decode(msg);
+  } catch {
+    return;
+  }
+  const q = query.questions?.[0];
+  if (q && (q.type === "A" || q.type === "AAAA")) {
+    const name = q.name.toLowerCase();
+    const isSingleLabel = !name.includes(".");
+
+    // Fakes win over docker — they're explicitly registered by the
+    // daemon and a fake's hostname (e.g. api.stripe.com) might collide
+    // with a real upstream we don't want to call.
+    const fakeIp = isSingleLabel ? null : await lookupFake(name);
+    const ip = fakeIp
+      ?? (isSingleLabel
+        ? await dockerLookupByName(name)
+        : await dockerLookupByAlias(name));
+
+    if (ip) {
+      // For AAAA we still answer empty — Docker bridges are IPv4 only, but
+      // we own this name so libc should fall back to A instead of chasing
+      // a stray upstream AAAA for the real public hostname.
+      const resp = q.type === "A" ? aAnswer(query, q.name, ip) : emptyAnswer(query);
+      sock.send(resp, rinfo.port, rinfo.address);
+      return;
+    }
+
+    if (isSingleLabel) {
+      // Bare hostname we don't own — reply NOERROR with no answers so the
+      // resolver moves on quickly. Forwarding bare hostnames upstream just
+      // causes timeouts.
+      sock.send(emptyAnswer(query), rinfo.port, rinfo.address);
+      return;
+    }
+    // Multi-label exact miss: try wildcard suffixes (e.g. *.example.com
+    // → the k3s cluster) before forwarding upstream. Exact lookups above
+    // always win, so a specific alias beats a covering wildcard.
+    const wildIp = await lookupWildcard(name);
+    if (wildIp) {
+      const resp = q.type === "A" ? aAnswer(query, q.name, wildIp) : emptyAnswer(query);
+      sock.send(resp, rinfo.port, rinfo.address);
+      return;
+    }
+    // Still nothing — fall through and forward to upstream below.
+  }
+  // Anything we don't own — forward.
+  const upstream = await forwardUpstream(msg);
+  if (upstream) {
+    sock.send(upstream, rinfo.port, rinfo.address);
+    return;
+  }
+  // Upstream unreachable; return SERVFAIL (rcode 2 in low 4 bits of flags).
+  const resp = dnsPacket.encode({
+    type: "response",
+    id: query.id,
+    flags: dnsPacket.RECURSION_DESIRED | 0x2,
+    questions: query.questions ?? [],
+  });
+  sock.send(resp, rinfo.port, rinfo.address);
+}
+
+/** Bind one UDP listener on `addr`, wired to the shared handler. A bind
+ * error on the primary loopback address is fatal (DNS is fully down);
+ * on the secondary bridge address it's logged and retried by the caller. */
+function bindListener(addr: string, fatalOnError: boolean): Promise<boolean> {
+  return new Promise((resolve) => {
+    const sock = createSocket("udp4");
+    sock.on("message", (msg: Buffer, rinfo: RemoteInfo) => {
+      void handleQuery(sock, msg, rinfo);
+    });
+    sock.on("error", (err) => {
+      // eslint-disable-next-line no-console
+      console.error(`[spectest-resolver] socket error on ${addr}:`, err);
+      if (fatalOnError) process.exit(1);
+      try {
+        sock.close();
+      } catch {
+        // ignore
+      }
+      resolve(false);
+    });
+    sock.bind(LISTEN_PORT, addr, () => {
+      // eslint-disable-next-line no-console
+      console.log(
+        `[spectest-resolver] listening on ${addr}:${LISTEN_PORT} (network=${NETWORK_NAME}, upstream=${UPSTREAM_DNS}:${UPSTREAM_PORT})`,
+      );
+      resolve(true);
+    });
+  });
+}
+
+/** Read the spectest-net bridge gateway IP from Docker — the address an
+ * in-cluster k3s pod (or any off-bridge client routed through the node)
+ * uses to reach the VM host. Null until the network exists. */
+async function bridgeGatewayIp(): Promise<string | null> {
+  const net = (await dockerGet(`/networks/${encodeURIComponent(NETWORK_NAME)}`)) as
+    | { IPAM?: { Config?: Array<{ Gateway?: string }> } }
+    | null;
+  const gw = net?.IPAM?.Config?.find((c) => c.Gateway)?.Gateway;
+  return gw && gw.length > 0 ? gw : null;
+}
+
+// Primary listener: the loopback nameserver. Fatal if it can't bind.
+void bindListener(LISTEN_ADDR, true);
+
+// Secondary listener: the spectest-net bridge gateway, for k3s pods.
+// The network is created by the daemon at /load — after this process
+// starts and after it's captured into the base snapshot — so poll until
+// the gateway appears, bind once, then stop. The gateway is stable for a
+// VM's life (the daemon only creates the network when it's missing), so a
+// single successful bind survives snapshot/restore/fork. Opt out with
+// SPECTEST_RESOLVER_NO_BRIDGE=1.
+if (process.env.SPECTEST_RESOLVER_NO_BRIDGE !== "1") {
+  let bound = false;
+  const poll = setInterval(async () => {
+    if (bound) return;
+    const gw = await bridgeGatewayIp().catch(() => null);
+    if (!gw) return;
+    bound = true;
+    if (!(await bindListener(gw, false))) bound = false; // retry on failure
+  }, 2_000);
+  // Don't keep the event loop alive solely for the poll timer.
+  poll.unref?.();
+}