@specific.dev/spectest 0.4.0

package/src/resolver.ts

@@ -0,0 +1,351 @@
+// 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?.();
+}