@specific.dev/spectest 0.131.19 → 0.131.20

package/dist/resolver.js

@@ -1,34 +1,12 @@
-// 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.
+// Platform-owned DNS server. SDK registry v1 queries are memory-only; Docker
+// discovery below serves only older pinned SDKs until the first full registry.
+// Bind specific loopback/bridge IPs so replies have the expected source address.
 import { createSocket } from "node:dgram";
-import { isIPv4 } from "node:net";
+import { isIPv4, createServer as createTcpServer, createConnection } from "node:net";
 import { request as httpRequest } from "node:http";
 import { readFile, stat } from "node:fs/promises";
 import { lookup } from "./harness/names-registry.js";
+import { serveDnsRegistry, compileDnsRegistry } from "./harness/dns-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";
@@ -41,6 +19,7 @@ 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";
+let registryLookup;
 function dockerGet(path) {
     return new Promise((resolve) => {
         const req = httpRequest({ socketPath: DOCKER_SOCKET, path, method: "GET" }, (res) => {
@@ -61,6 +40,7 @@ function dockerGet(path) {
             });
             res.on("error", () => resolve(null));
         });
+        req.setTimeout(3_000, () => req.destroy());
         req.on("error", () => resolve(null));
         req.end();
     });
@@ -74,34 +54,53 @@ async function dockerLookupByName(name) {
     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) {
-    const filters = encodeURIComponent(JSON.stringify({ network: [NETWORK_NAME] }));
-    const list = (await dockerGet(`/containers/json?filters=${filters}`));
-    if (!Array.isArray(list))
+// Alias discovery must not use /containers/json: Docker's containerd image
+// store refreshes image metadata for that endpoint, even for a names-only list.
+// Network inspection enumerates the same endpoints without walking images.
+// Share discovery across names and A/AAAA queries. Keep its lifetime shorter
+// than our DNS TTL so runtime container changes become visible promptly.
+let aliases;
+let refreshingAliases;
+async function readAliases() {
+    const network = await dockerGet(`/networks/${encodeURIComponent(NETWORK_NAME)}`);
+    if (!network?.Containers)
         return null;
-    for (const c of list) {
-        if (!c.Id)
-            continue;
-        const info = (await dockerGet(`/containers/${c.Id}/json`));
-        const net = info?.NetworkSettings?.Networks?.[NETWORK_NAME];
-        if (!net)
-            continue;
-        if ((net.Aliases ?? []).includes(name) && net.IPAddress) {
-            return net.IPAddress;
+    const ids = Object.keys(network.Containers);
+    const hosts = new Map();
+    let failed = false;
+    // Bound concurrent inspections even for large projects.
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(8, ids.length) }, async () => {
+        while (next < ids.length) {
+            const id = ids[next++];
+            const info = await dockerGet(`/containers/${encodeURIComponent(id)}/json`);
+            if (!info) {
+                failed = true;
+                continue;
+            }
+            if (!info.State?.Running)
+                continue;
+            const net = info.NetworkSettings?.Networks?.[NETWORK_NAME];
+            if (!net?.IPAddress)
+                continue;
+            for (const alias of net.Aliases ?? [])
+                hosts.set(alias.toLowerCase(), net.IPAddress);
         }
+    }));
+    // A transient Docker failure must not become a cached negative answer.
+    return { hosts, complete: !failed };
+}
+async function dockerLookupByAlias(name) {
+    if (aliases && performance.now() < aliases.expires)
+        return aliases.hosts.get(name) ?? null;
+    if (!refreshingAliases) {
+        refreshingAliases = readAliases().then(result => {
+            if (result?.complete)
+                aliases = { hosts: result.hosts, expires: performance.now() + Math.min(1_000, TTL_SECONDS * 1_000) };
+            return result?.hosts ?? null;
+        }).finally(() => { refreshingAliases = undefined; });
     }
-    return null;
+    return (await refreshingAliases)?.get(name) ?? null;
 }
 let registryCache = { mtimeMs: 0, hosts: {}, wildcards: [] };
 async function refreshRegistry() {
@@ -135,36 +134,116 @@ async function lookupWildcard(name) {
     // format cannot drift apart.
     return lookup({ hosts: {}, wildcards: registryCache.wildcards }, name);
 }
-async function forwardUpstream(query) {
-    return new Promise((resolve) => {
-        const sock = createSocket("udp4");
+// One connected UDP socket validates the upstream source and multiplexes bounded
+// requests. Remap IDs so simultaneous clients cannot steal each other's replies.
+const upstreamSocket = createSocket("udp4");
+const upstreamPending = new Map();
+let nextUpstreamId = 0;
+const upstreamReady = new Promise(resolve => upstreamSocket.connect(UPSTREAM_PORT, UPSTREAM_DNS, resolve));
+upstreamSocket.on("error", () => {
+    for (const pending of upstreamPending.values())
+        pending.finish(null);
+});
+upstreamSocket.on("message", msg => {
+    if (msg.length < 12)
+        return;
+    const pending = upstreamPending.get(msg.readUInt16BE(0));
+    if (!pending)
+        return;
+    try {
+        const response = dnsPacket.decode(msg);
+        if (response.type !== "response" || JSON.stringify(response.questions) !== JSON.stringify(pending.query.questions))
+            return;
+        pending.finish(msg);
+    }
+    catch { /* Discard malformed or unrelated responses. */ }
+});
+const upstreamFlights = new Map();
+async function forwardUpstream(query, tcp) {
+    if (tcp)
+        return forwardTcp(query);
+    const normalized = Buffer.from(query);
+    normalized.writeUInt16BE(0, 0);
+    const key = normalized.toString("base64");
+    let flight = upstreamFlights.get(key);
+    if (!flight) {
+        flight = exchangeUdp(normalized).finally(() => { upstreamFlights.delete(key); });
+        upstreamFlights.set(key, flight);
+    }
+    const response = await flight;
+    if (!response)
+        return null;
+    const result = Buffer.from(response);
+    result.writeUInt16BE(query.readUInt16BE(0), 0);
+    return result;
+}
+async function exchangeUdp(query) {
+    if (upstreamPending.size >= 2048)
+        return null;
+    let id;
+    do {
+        id = nextUpstreamId++ & 0xffff;
+    } while (upstreamPending.has(id));
+    return new Promise(resolve => {
+        const timer = setTimeout(() => finish(null), 3_000);
+        const finish = (msg) => {
+            if (!upstreamPending.delete(id))
+                return;
+            clearTimeout(timer);
+            if (msg) {
+                msg = Buffer.from(msg);
+                msg.writeUInt16BE(query.readUInt16BE(0), 0);
+            }
+            resolve(msg);
+        };
+        upstreamPending.set(id, { query: dnsPacket.decode(query), finish });
+        const forwarded = Buffer.from(query);
+        forwarded.writeUInt16BE(id, 0);
+        void upstreamReady.then(() => {
+            if (upstreamPending.has(id))
+                upstreamSocket.send(forwarded, error => { if (error)
+                    finish(null); });
+        });
+    });
+}
+function forwardTcp(query) {
+    return new Promise(resolve => {
+        const socket = createConnection({ host: UPSTREAM_DNS, port: UPSTREAM_PORT });
+        let data = Buffer.alloc(0);
         let done = false;
-        const finish = (b) => {
+        const finish = (msg) => {
             if (done)
                 return;
             done = true;
-            try {
-                sock.close();
-            }
-            catch {
-                // ignore
-            }
-            resolve(b);
+            clearTimeout(timer);
+            socket.destroy();
+            resolve(msg);
         };
-        sock.on("message", (msg) => finish(msg));
-        sock.on("error", () => finish(null));
-        sock.send(query, UPSTREAM_PORT, UPSTREAM_DNS, (err) => {
-            if (err)
-                finish(null);
+        const timer = setTimeout(() => finish(null), 3_000);
+        socket.on("connect", () => { const size = Buffer.alloc(2); size.writeUInt16BE(query.length); socket.write(Buffer.concat([size, query])); });
+        socket.on("data", chunk => {
+            data = Buffer.concat([data, Buffer.from(chunk)]);
+            if (data.length >= 2 && data.length >= 2 + data.readUInt16BE(0)) {
+                const msg = data.subarray(2, 2 + data.readUInt16BE(0));
+                try {
+                    const response = dnsPacket.decode(msg);
+                    const request = dnsPacket.decode(query);
+                    finish(response.type === "response" && response.id === request.id && JSON.stringify(response.questions) === JSON.stringify(request.questions) ? msg : null);
+                }
+                catch {
+                    finish(null);
+                }
+            }
         });
-        setTimeout(() => finish(null), 3_000);
+        socket.on("error", () => finish(null));
+        socket.on("close", () => finish(null));
     });
 }
 function emptyAnswer(query) {
     return dnsPacket.encode({
         type: "response",
         id: query.id,
-        flags: dnsPacket.AUTHORITATIVE_ANSWER | dnsPacket.RECURSION_DESIRED,
+        flags: dnsPacket.AUTHORITATIVE_ANSWER | dnsPacket.RECURSION_AVAILABLE | ((query.flags ?? 0) & dnsPacket.RECURSION_DESIRED),
         questions: query.questions,
         answers: [],
     });
@@ -173,7 +252,7 @@ function aAnswer(query, name, ip) {
     return dnsPacket.encode({
         type: "response",
         id: query.id,
-        flags: dnsPacket.AUTHORITATIVE_ANSWER | dnsPacket.RECURSION_DESIRED,
+        flags: dnsPacket.AUTHORITATIVE_ANSWER | dnsPacket.RECURSION_AVAILABLE | ((query.flags ?? 0) & dnsPacket.RECURSION_DESIRED),
         questions: query.questions,
         answers: [{ type: "A", name, ttl: TTL_SECONDS, data: ip }],
     });
@@ -183,15 +262,28 @@ function aAnswer(query, name, ip) {
 // 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, msg, rinfo) {
+async function handleQuery(msg, tcp = false) {
     let query;
     try {
         query = dnsPacket.decode(msg);
     }
     catch {
-        return;
+        return null;
     }
+    if (query.type !== "query")
+        return null;
     const q = query.questions?.[0];
+    if (query.questions?.length !== 1)
+        return dnsPacket.encode({ type: "response", id: query.id, flags: 1, questions: query.questions });
+    if (registryLookup && q) {
+        const name = q.name.toLowerCase().replace(/\.$/, "");
+        const ip = registryLookup(name);
+        if (ip !== undefined || !name.includes(".") || name.endsWith(".internal")) {
+            return ip && q.type === "A" ? aAnswer(query, q.name, ip) : emptyAnswer(query);
+        }
+        const answer = await forwardUpstream(msg, tcp);
+        return answer ?? dnsPacket.encode({ type: "response", id: query.id, flags: dnsPacket.RECURSION_AVAILABLE | ((query.flags ?? 0) & dnsPacket.RECURSION_DESIRED) | 2, questions: query.questions });
+    }
     if (q && (q.type === "A" || q.type === "AAAA")) {
         const name = q.name.toLowerCase();
         const isSingleLabel = !name.includes(".");
@@ -208,15 +300,13 @@ async function handleQuery(sock, msg, rinfo) {
             // 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;
+            return resp;
         }
         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;
+            return emptyAnswer(query);
         }
         // Multi-label exact miss: try wildcard suffixes (e.g. *.example.com
         // → the k3s cluster) before forwarding upstream. Exact lookups above
@@ -224,16 +314,14 @@ async function handleQuery(sock, msg, rinfo) {
         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;
+            return resp;
         }
         // Still nothing — fall through and forward to upstream below.
     }
     // Anything we don't own — forward.
-    const upstream = await forwardUpstream(msg);
+    const upstream = await forwardUpstream(msg, tcp);
     if (upstream) {
-        sock.send(upstream, rinfo.port, rinfo.address);
-        return;
+        return upstream;
     }
     // Upstream unreachable; return SERVFAIL (rcode 2 in low 4 bits of flags).
     const resp = dnsPacket.encode({
@@ -242,7 +330,7 @@ async function handleQuery(sock, msg, rinfo) {
         flags: dnsPacket.RECURSION_DESIRED | 0x2,
         questions: query.questions ?? [],
     });
-    sock.send(resp, rinfo.port, rinfo.address);
+    return resp;
 }
 /** 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);
@@ -251,7 +339,8 @@ function bindListener(addr, fatalOnError) {
     return new Promise((resolve) => {
         const sock = createSocket("udp4");
         sock.on("message", (msg, rinfo) => {
-            void handleQuery(sock, msg, rinfo);
+            void handleQuery(msg).then(answer => { if (answer)
+                sock.send(answer, rinfo.port, rinfo.address); }).catch(error => console.error("[spectest-resolver] query failed", error));
         });
         sock.on("error", (err) => {
             // eslint-disable-next-line no-console
@@ -273,6 +362,44 @@ function bindListener(addr, fatalOnError) {
         });
     });
 }
+/** DNS over TCP uses the same registry and supports external truncated replies. */
+function bindTcpListener(addr, fatalOnError) {
+    const server = createTcpServer(socket => {
+        let buffered = Buffer.alloc(0);
+        let inFlight = 0;
+        socket.setTimeout(10_000, () => socket.destroy());
+        socket.on("error", () => socket.destroy());
+        socket.on("data", chunk => {
+            buffered = Buffer.concat([buffered, Buffer.from(chunk)]);
+            while (buffered.length >= 2) {
+                const size = buffered.readUInt16BE(0);
+                if (buffered.length < size + 2)
+                    break;
+                const msg = Buffer.from(buffered.subarray(2, size + 2));
+                buffered = buffered.subarray(size + 2);
+                if (++inFlight > 128) {
+                    socket.destroy();
+                    return;
+                }
+                void handleQuery(msg, true).then(answer => {
+                    if (answer && !socket.destroyed) {
+                        const prefix = Buffer.alloc(2);
+                        prefix.writeUInt16BE(answer.length);
+                        socket.write(Buffer.concat([prefix, answer]));
+                    }
+                }).catch(() => socket.destroy()).finally(() => { inFlight--; });
+            }
+        });
+    });
+    server.on("error", error => {
+        console.error(`[spectest-resolver] TCP bind ${addr}:`, error);
+        if (fatalOnError)
+            process.exit(1);
+        else
+            setTimeout(() => bindTcpListener(addr, false), 2_000).unref();
+    });
+    server.listen(LISTEN_PORT, addr);
+}
 /** 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. */
@@ -281,8 +408,10 @@ async function bridgeGatewayIp() {
     const gw = net?.IPAM?.Config?.find(c => c.Gateway && isIPv4(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);
+// Restore persisted state and open the control socket before advertising DNS.
+await serveDnsRegistry(doc => { registryLookup = compileDnsRegistry(doc); aliases = undefined; });
+await bindListener(LISTEN_ADDR, true);
+bindTcpListener(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
@@ -301,6 +430,10 @@ if (process.env.SPECTEST_RESOLVER_NO_BRIDGE !== "1") {
         bound = true;
         if (!(await bindListener(gw, false)))
             bound = false; // retry on failure
+        else {
+            bindTcpListener(gw, false);
+            clearInterval(poll);
+        }
     }, 2_000);
     // Don't keep the event loop alive solely for the poll timer.
     poll.unref?.();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.131.19",
+  "version": "0.131.20",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",