@specific.dev/spectest 0.26.0 → 0.28.0

package/src/redis.ts

@@ -1,202 +0,0 @@
-// `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/resolver.ts

@@ -1,351 +0,0 @@
-// 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 * 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 spectest-daemon 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();
-  let best: { suffix: string; ip: string } | null = null;
-  for (const w of registryCache.wildcards) {
-    if (name.endsWith(w.suffix) && (!best || w.suffix.length > best.suffix.length)) {
-      best = w;
-    }
-  }
-  return best?.ip ?? null;
-}
-
-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?.();
-}