@specific.dev/spectest 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./src/index.ts",

package/src/daemon.ts

@@ -24,7 +24,15 @@ import net from "node:net";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
-import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard } from "./index.js";
+import {
+  assert,
+  expect,
+  expectRaw,
+  lowerIngress,
+  dnsName as makeDnsDecl,
+  isWildcard,
+  proxy as makeProxyDecl,
+} from "./index.js";
 import type { DnsTarget, LoweredIngress } from "./index.js";
 import { openBrowser } from "./browser.js";
 import { openMobile, isMobileApp } from "./mobile.js";
@@ -1222,6 +1230,24 @@ const INGRESS_HTTP_SERVERS = new Map<number, any>();
 /** Running HTTPS servers per port (currently always {INGRESS_HTTPS_PORT}). */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const INGRESS_HTTPS_SERVERS = new Map<number, any>();
+/**
+ * Live per-port route tables, keyed by listen port (80 / 443 / fake ports).
+ * Each listener's `fetch` closure captures *this* Map object, so adding an
+ * entry takes effect immediately with no rebind — that's what lets a runtime
+ * `tls` (a `ctx.startService({ tls })`) bind a new ingress route after boot.
+ * Held at module scope so it's part of the live daemon process and forks
+ * with the snapshot, exactly like fake state / the names REGISTRY. Rebuilt on
+ * /load (cleared by {@link stopIngressServers}).
+ */
+const INGRESS_ROUTES_BY_PORT = new Map<number, Map<string, Route>>();
+/**
+ * The :443 SNI cert table: serverName → leaf. Unlike the route table, Bun's
+ * TLS config is fixed at `Bun.serve` time (reload won't add an SNI entry), so
+ * minting a cert for a *new* hostname requires rebinding the :443 listener
+ * (cheap, ~1ms — see {@link rebindHttpsListener}). A hostname already covered
+ * by an existing exact or wildcard cert needs no rebind, just a route entry.
+ */
+const HTTPS_CERT_BY_HOST = new Map<string, { cert: string; key: string }>();
 
 /**
  * Tear down listener servers between /load calls so the new project's
@@ -1246,6 +1272,8 @@ function stopIngressServers(): void {
     }
   }
   INGRESS_HTTPS_SERVERS.clear();
+  INGRESS_ROUTES_BY_PORT.clear();
+  HTTPS_CERT_BY_HOST.clear();
 }
 
 function buildIngress(project: Project): void {
@@ -1441,12 +1469,11 @@ async function startIngress(): Promise<void> {
   // before binding so the HTTPS listener has certs ready and a startup
   // failure aborts /bootstrap cleanly.
   const caPresent = existsSync(CA_PATH) && existsSync(CA_KEY_PATH);
-  const certByHost = new Map<string, { cert: string; key: string }>();
   if (caPresent) {
     for (const group of LOWERED.certificates) {
       if (group.hostnames.length === 0) continue;
       const leaf = await generateHostCert(group.hostnames[0], group.hostnames);
-      for (const h of group.hostnames) certByHost.set(h, leaf);
+      for (const h of group.hostnames) HTTPS_CERT_BY_HOST.set(h, leaf);
     }
   } else if (LOWERED.certificates.length > 0) {
     // eslint-disable-next-line no-console
@@ -1455,73 +1482,49 @@ async function startIngress(): Promise<void> {
     );
   }
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const Bun = (globalThis as any).Bun;
-  if (!Bun?.serve) {
-    throw new Error(
-      "ingress requires Bun.serve; the daemon must run under Bun (it does in-VM)",
-    );
-  }
-
-  // Resolve every ingress hostname to its handler. Fakes run an in-daemon
-  // handler; proxies reverse-proxy to a service:port. This single table
-  // drives both the HTTP and HTTPS listeners.
-  const routeByHost = new Map<string, Route>();
-  for (const fake of FAKES.values()) {
-    for (const h of fake.hostnames) routeByHost.set(h, { kind: "fake", fake });
-  }
-  for (const p of LOWERED.proxies) {
-    routeByHost.set(p.hostname, { kind: "proxy", service: p.service, port: p.port });
-  }
+  const Bun = requireBun();
 
-  // ── HTTP listeners: group routes by port, dispatch per-request by Host.
-  //    Proxies bind :80 (HTTPS, if any, is on :443); fakes use their
-  //    declared port. Skip :443 in the HTTP map — HTTPS wins.
-  const httpRoutesByPort = new Map<number, Map<string, Route>>();
+  // Resolve every ingress hostname to its handler into the live per-port
+  // route tables (module scope, so runtime `tls` can extend them later).
+  // Fakes run an in-daemon handler on their declared port; proxies
+  // reverse-proxy to a service:port and bind :80 (HTTPS, if any, is :443).
   const ensurePort = (port: number): Map<string, Route> => {
-    const m = httpRoutesByPort.get(port) ?? new Map<string, Route>();
-    httpRoutesByPort.set(port, m);
+    const m = INGRESS_ROUTES_BY_PORT.get(port) ?? new Map<string, Route>();
+    INGRESS_ROUTES_BY_PORT.set(port, m);
     return m;
   };
   for (const fake of FAKES.values()) {
     if (fake.port === INGRESS_HTTPS_PORT) continue;
     const routes = ensurePort(fake.port);
-    for (const h of fake.hostnames) routes.set(h, routeByHost.get(h)!);
+    for (const h of fake.hostnames) routes.set(h, { kind: "fake", fake });
   }
   if (LOWERED.proxies.length > 0) {
     const routes = ensurePort(INGRESS_HTTP_PORT);
-    for (const p of LOWERED.proxies) routes.set(p.hostname, routeByHost.get(p.hostname)!);
+    for (const p of LOWERED.proxies) {
+      routes.set(p.hostname, { kind: "proxy", service: p.service, port: p.port });
+    }
   }
-  for (const [port, byHost] of httpRoutesByPort) {
-    const label = `port ${port}`;
-    INGRESS_HTTP_SERVERS.set(port, bindIngressServer(Bun, port, byHost, label));
-    const hosts = [...byHost.keys()].join(", ");
-    // eslint-disable-next-line no-console
-    console.log(`[ingress] http :${port} for ${hosts}`);
+  // The :443 route table mirrors every certificated hostname's handler.
+  if (HTTPS_CERT_BY_HOST.size > 0) {
+    const httpsRoutes = ensurePort(INGRESS_HTTPS_PORT);
+    for (const h of HTTPS_CERT_BY_HOST.keys()) {
+      for (const fake of FAKES.values()) {
+        if (fake.hostnames.includes(h)) httpsRoutes.set(h, { kind: "fake", fake });
+      }
+      const proxy = LOWERED.proxies.find((p) => p.hostname === h);
+      if (proxy) httpsRoutes.set(h, { kind: "proxy", service: proxy.service, port: proxy.port });
+    }
   }
 
-  // ── HTTPS listener on INGRESS_HTTPS_PORT: SNI per certificated hostname.
-  if (certByHost.size > 0) {
-    const tlsEntries: Array<{ cert: string; key: string; serverName: string }> = [];
-    const byHostHttps = new Map<string, Route>();
-    for (const [h, leaf] of certByHost) {
-      tlsEntries.push({ cert: leaf.cert, key: leaf.key, serverName: h });
-      const route = routeByHost.get(h);
-      if (route) byHostHttps.set(h, route);
-    }
-    const label = `https :${INGRESS_HTTPS_PORT}`;
-    const server = bindIngressServer(
-      Bun,
-      INGRESS_HTTPS_PORT,
-      byHostHttps,
-      label,
-      tlsEntries,
-    );
-    INGRESS_HTTPS_SERVERS.set(INGRESS_HTTPS_PORT, server);
-    const hosts = [...byHostHttps.keys()].join(", ");
+  // ── HTTP listeners (one per non-443 port).
+  for (const [port, byHost] of INGRESS_ROUTES_BY_PORT) {
+    if (port === INGRESS_HTTPS_PORT) continue;
+    INGRESS_HTTP_SERVERS.set(port, bindIngressServer(Bun, port, byHost, `port ${port}`));
     // eslint-disable-next-line no-console
-    console.log(`[ingress] https :${INGRESS_HTTPS_PORT} for ${hosts}`);
+    console.log(`[ingress] http :${port} for ${[...byHost.keys()].join(", ")}`);
   }
+  // ── HTTPS listener on INGRESS_HTTPS_PORT: SNI per certificated hostname.
+  if (HTTPS_CERT_BY_HOST.size > 0) rebindHttpsListener(Bun);
 
   // Seed the resolver's names registry: ingress hostnames (fakes, TLS
   // proxies, dnsName(→ingress)) → bridge gateway, plus ingress-targeted
@@ -1530,6 +1533,148 @@ async function startIngress(): Promise<void> {
   await seedNamesRegistry({ servicesUp: false });
 }
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function requireBun(): any {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const Bun = (globalThis as any).Bun;
+  if (!Bun?.serve) {
+    throw new Error(
+      "ingress requires Bun.serve; the daemon must run under Bun (it does in-VM)",
+    );
+  }
+  return Bun;
+}
+
+/** Flatten {@link HTTPS_CERT_BY_HOST} into Bun's TLS-entry SNI array. */
+function tlsEntriesFromCerts(): Array<{ cert: string; key: string; serverName: string }> {
+  return [...HTTPS_CERT_BY_HOST].map(([serverName, leaf]) => ({
+    cert: leaf.cert,
+    key: leaf.key,
+    serverName,
+  }));
+}
+
+/**
+ * (Re)bind the :443 listener from the current cert table + route map. Bun's
+ * TLS config is immutable per `Bun.serve`, so adding an SNI cert means
+ * stopping the old listener and serving a fresh one — cheap (~1ms) and the
+ * window is sub-millisecond. The route Map is the persistent module object,
+ * so the new listener closes over the same table (later route additions need
+ * no rebind). No-ops to a plain rebind when only routes changed.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function rebindHttpsListener(Bun: any): void {
+  const routes = INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTPS_PORT) ?? new Map<string, Route>();
+  INGRESS_ROUTES_BY_PORT.set(INGRESS_HTTPS_PORT, routes);
+  const old = INGRESS_HTTPS_SERVERS.get(INGRESS_HTTPS_PORT);
+  if (old) {
+    try {
+      old.stop(true);
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn("[ingress] failed to stop https listener for rebind:", err);
+    }
+  }
+  const server = bindIngressServer(
+    Bun,
+    INGRESS_HTTPS_PORT,
+    routes,
+    `https :${INGRESS_HTTPS_PORT}`,
+    tlsEntriesFromCerts(),
+  );
+  INGRESS_HTTPS_SERVERS.set(INGRESS_HTTPS_PORT, server);
+  // eslint-disable-next-line no-console
+  console.log(`[ingress] https :${INGRESS_HTTPS_PORT} for ${[...routes.keys()].join(", ")}`);
+}
+
+/** True if an exact or wildcard cert already covers `hostname` for SNI. */
+function certCovers(hostname: string): boolean {
+  if (HTTPS_CERT_BY_HOST.has(hostname)) return true;
+  for (const serverName of HTTPS_CERT_BY_HOST.keys()) {
+    if (isWildcard(serverName) && hostname.endsWith(wildcardSuffix(serverName))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Bind a runtime ingress route for one `tls: [{ hostname, port }]` entry on a
+ * {@link RuntimeServiceSpec} — the runtime twin of a boot service's `tls`.
+ * Mints a leaf cert (unless one already covers the hostname), stands up a
+ * TLS-terminating reverse proxy at `https://<hostname>/` → `service:port`,
+ * also serves plain `http://<hostname>/`, and points the hostname at the
+ * daemon gateway in the resolver registry. Idempotent per hostname.
+ *
+ * Everything it mutates (the live route tables, the :443 cert table, the
+ * names REGISTRY) is daemon-process state, so the binding forks with the
+ * per-test snapshot exactly like fake state — a `dependsOn` child inherits
+ * it, siblings forked from an earlier snapshot never see it.
+ */
+async function bindRuntimeTls(hostname: string, service: string, port: number): Promise<void> {
+  // Reuse the boot primitives for validation + lowercasing; throws on a
+  // malformed hostname / upstream just like a boot `tls` would at load.
+  const decl = makeProxyDecl(hostname, { service, port });
+  const host = decl.hostname;
+  if (!existsSync(CA_PATH) || !existsSync(CA_KEY_PATH)) {
+    throw new Error(
+      `runtime tls for ${JSON.stringify(host)} requires the in-VM root CA at ${CA_PATH}`,
+    );
+  }
+  const Bun = requireBun();
+  const route: Route = { kind: "proxy", service, port };
+
+  // Plain HTTP on :80 (parity with boot `tls`, which serves both schemes).
+  let httpRoutes = INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTP_PORT);
+  if (!httpRoutes) {
+    httpRoutes = new Map<string, Route>();
+    INGRESS_ROUTES_BY_PORT.set(INGRESS_HTTP_PORT, httpRoutes);
+  }
+  httpRoutes.set(host, route);
+  if (!INGRESS_HTTP_SERVERS.has(INGRESS_HTTP_PORT)) {
+    INGRESS_HTTP_SERVERS.set(
+      INGRESS_HTTP_PORT,
+      bindIngressServer(Bun, INGRESS_HTTP_PORT, httpRoutes, `port ${INGRESS_HTTP_PORT}`),
+    );
+  }
+
+  // HTTPS on :443. A new cert forces a listener rebind; an already-covered
+  // hostname (exact dup or a boot wildcard) just needs the route entry.
+  const needCert = !certCovers(host);
+  if (needCert) {
+    HTTPS_CERT_BY_HOST.set(host, await generateHostCert(host, [host]));
+  }
+  const httpsRoutes = INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTPS_PORT) ?? new Map<string, Route>();
+  INGRESS_ROUTES_BY_PORT.set(INGRESS_HTTPS_PORT, httpsRoutes);
+  httpsRoutes.set(host, route);
+  if (needCert || !INGRESS_HTTPS_SERVERS.has(INGRESS_HTTPS_PORT)) {
+    rebindHttpsListener(Bun);
+  }
+
+  // Resolve the hostname to the daemon gateway (where :443/:80 listen).
+  const gw = await bridgeGatewayIp();
+  REGISTRY.hosts[host] = gw;
+  await writeRegistry();
+  // eslint-disable-next-line no-console
+  console.log(`[ingress] runtime https ${host} -> ${service}:${port}`);
+}
+
+/**
+ * Undo {@link bindRuntimeTls} for one hostname when its runtime service is
+ * stopped: drop the route (so it 404s) and the registry entry. The cert is
+ * left in the SNI table — harmless without a route, and removing it would
+ * mean an avoidable :443 rebind.
+ */
+async function unbindRuntimeTls(hostname: string): Promise<void> {
+  const host = hostname.toLowerCase();
+  INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTP_PORT)?.delete(host);
+  INGRESS_ROUTES_BY_PORT.get(INGRESS_HTTPS_PORT)?.delete(host);
+  if (host in REGISTRY.hosts) {
+    delete REGISTRY.hosts[host];
+    await writeRegistry();
+  }
+}
+
 /**
  * Spin up one Bun.serve listener bound to (port, optional TLS) that
  * dispatches every request to the matching Route by Host header.
@@ -2020,6 +2165,11 @@ async function startRuntimeService(spec: RuntimeServiceSpec): Promise<RuntimeSer
     await runContainer(svc, tag, flags, aliases);
     await waitForReady(svc);
     const ip = (await serviceContainerIp(svc.name)) ?? "";
+    // `tls` is the runtime twin of a boot service's: stand up a
+    // TLS-terminating reverse proxy at https://<hostname>/ → this container.
+    for (const entry of svc.tls ?? []) {
+      await bindRuntimeTls(entry.hostname, svc.name, entry.port);
+    }
     RUNTIME_SERVICES.set(svc.name, svc);
     recordEnv({
       op: "startService",
@@ -2046,8 +2196,10 @@ async function startRuntimeService(spec: RuntimeServiceSpec): Promise<RuntimeSer
 async function stopRuntimeService(name: string): Promise<void> {
   const t0 = Date.now();
   const resv = reserveEvent();
+  const svc = RUNTIME_SERVICES.get(name);
   await docker(["rm", "-f", name], 30_000);
   RUNTIME_SERVICES.delete(name);
+  for (const entry of svc?.tls ?? []) await unbindRuntimeTls(entry.hostname);
   recordEnv({ op: "stopService", service: name, durationMs: Date.now() - t0 }, resv);
 }
 

package/src/index.ts

@@ -348,22 +348,28 @@ export type ReadyCheck =
 /**
  * Spec for a service started at runtime via {@link TestContext.startService}
  * (or the `ctx` handed to a fake). It's a normal {@link ServiceConfig} plus a
- * required `name`, minus the two fields that only make sense at boot:
- *
- *  - `tls` — runtime services are reached *directly* by their own IP on
- *    `spectest-net` (like a real machine on a network), not through the
- *    daemon's HTTP ingress, so there's no proxy/cert to configure. Map a
- *    friendly DNS name onto one with {@link TestContext.dnsName}.
- *  - `dependsOn` — there is no boot DAG at runtime; the caller orders
- *    `startService` calls itself with `await`.
+ * required `name`, minus only `dependsOn` (there is no boot DAG at runtime;
+ * the caller orders `startService` calls itself with `await`).
  *
  * The container joins `spectest-net` with its own IP and is resolvable by
  * `name` (single-label, via the resolver / docker embedded DNS) and by any
  * `hostnames` (extra `--network-alias`es). Like everything else in the VM it
  * is captured by the per-test post-state snapshot, so a `dependsOn` child
  * inherits the live container while siblings never see it.
+ *
+ * `tls: [{ hostname, port }]` works exactly as it does for a boot service:
+ * the daemon mints a leaf cert from the in-VM root CA and stands up a
+ * TLS-terminating reverse proxy at `https://<hostname>/` (and plain
+ * `http://<hostname>/`) → the container's `port`, binding it onto the live
+ * `:443`/`:80` ingress listeners the moment the container is ready. The
+ * hostname resolves to the daemon gateway for tests, `ctx.browser()`, and
+ * peer containers. Because the route lives in daemon memory (and the
+ * resolver registry file), it forks with the per-test snapshot like fake
+ * state, and is torn down when the service is stopped. This lets a runtime
+ * provider mint a CA-trusted HTTPS endpoint on demand — e.g. a per-DB proxy
+ * the Neon serverless driver reaches at its *default* `https://<host>/sql`.
  */
-export interface RuntimeServiceSpec extends Omit<ServiceConfig, "tls" | "dependsOn"> {
+export interface RuntimeServiceSpec extends Omit<ServiceConfig, "dependsOn"> {
   /**
    * Container name and primary DNS name on `spectest-net`. Must be unique
    * within the current fork — generate a fresh one per provisioned instance