@specific.dev/spectest 0.68.0 → 0.70.0

package/dist/browser.js

@@ -1406,7 +1406,7 @@ function buildBackend(holder, recorder, buildOpts) {
             }, { wrap: true });
         },
         async waitForFunction(description, fn, arg, options = {}) {
-            const timeoutMs = options.timeout ?? 5_000;
+            const timeoutMs = options.timeout ?? DEFAULT_ACTION_TIMEOUT_MS;
             const intervalMs = options.polling ?? 100;
             const src = typeof fn === "string" ? fn : fn.toString();
             const t = truncateUtf8(src);

package/dist/daemon.js

@@ -45,8 +45,9 @@ import { isTextualContentType, looksBinary, omittedBody, parseContentLength, } f
 import { encodeRegistry } from "./harness/names-registry.js";
 import { InterceptRegistry, parseTarget, runChain, } from "./harness/intercept.js";
 import { HOP_BY_HOP_HEADERS, augmentCorsResponse, corsPreflightResponse, isCorsPreflight, } from "./harness/http-proxy.js";
-import { certCovers as hostmatchCertCovers, hostWithoutPort, matchRoute, wildcardSuffix, } from "./harness/hostmatch.js";
-import { INGRESS_HTTPS_PORT, INGRESS_HTTP_PORT, bindRoute, certEntries, clearTables, emptyTables, planBind, registryTarget, routesFor, unbindRoute, } from "./harness/ingress-table.js";
+import { certCovers as hostmatchCertCovers, hostWithoutPort, matchRoute, selectCertName, wildcardSuffix, } from "./harness/hostmatch.js";
+import { INGRESS_HTTPS_PORT, INGRESS_HTTP_PORT, bindRoute, clearTables, emptyTables, planBind, registryTarget, routesFor, unbindRoute, } from "./harness/ingress-table.js";
+import { startTlsTerminator } from "./harness/tls-terminator.js";
 import { runContainerArgs } from "./harness/container-run.js";
 import { assertAbsolute, certificateHostnames, defaultKeyMode, expandServiceToken, isNoopChown, mountFlag, needsIdTables, numericId, resolveChownIds, } from "./harness/file-mounts.js";
 import { conflict, notFound, requireString, } from "./harness/methods.js";
@@ -1356,43 +1357,29 @@ const INGRESS_HTTP_SERVERS = new Map();
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const INGRESS_HTTPS_SERVERS = new Map();
 /**
- * Servers replaced by a rebind and now draining. On Bun 1.3.14 a request
- * arriving on a kept-alive connection of a `stop(false)`-drained server
- * dispatches into freed per-server state and can SEGFAULT the process
- * (use-after-free class fixed upstream by oven-sh/bun#36790, first in Bun
- * 1.4.0; observed here as `panic: Segmentation fault at address 0xA` in
- * `server.zig onRequestFor` on ~2-3 % of runtime-TLS rebinds). Until the
- * Bun bump lands, shrink the number of requests a drained server can ever
- * see: every response it still serves carries `Connection: close` (one
- * more request per surviving connection, not unlimited), and a grace timer
- * force-closes whatever is left ({@link REBIND_DRAIN_GRACE_MS}).
+ * The :443 TLS terminator, once per harness process.
+ *
+ * There is deliberately no draining machinery beside it any more. :443
+ * used to be a `Bun.serve` that had to be swapped for every new
+ * certificate, and no swap can be made safe: `stop(false)` FINs an idle
+ * kept-alive connection within 1-2 ms, so a client that wrote a request in
+ * that instant failed with `SocketError: other side closed` — in whatever
+ * unrelated test happened to be talking through the ingress.
+ * {@link startTlsTerminator} chooses the leaf per handshake instead, so
+ * the listener is bound once and lives as long as the project does.
  */
-const DRAINING_INGRESS = new WeakSet();
-/** How long a drained listener may keep serving in-flight work before its
- *  remaining connections are force-closed. Long enough for a slow proxied
- *  response to finish, short enough to bound the 1.3.14 UAF window. */
-const REBIND_DRAIN_GRACE_MS = 15_000;
-/** Stamp `Connection: close` on a response served by a draining listener so
- *  the kept-alive connection retires instead of lingering as a UAF trigger.
- *  Proxied responses can carry immutable headers; rewrap when needed. */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function withDrainClose(server, res) {
-    if (!DRAINING_INGRESS.has(server))
-        return res;
-    try {
-        res.headers.set("connection", "close");
-        return res;
-    }
-    catch {
-        const headers = new Headers(res.headers);
-        headers.set("connection", "close");
-        return new Response(res.body, {
-            status: res.status,
-            statusText: res.statusText,
-            headers,
-        });
-    }
-}
+let HTTPS_TERMINATOR;
+/**
+ * The in-flight first bind of :443, if one is running.
+ *
+ * {@link ensureHttpsIngress} is async where the swap it replaced was
+ * synchronous, and that reintroduces an interleaving the old code could
+ * not have: two `ctx.startService({ tls })` calls issued together by a
+ * fake handler would both find :443 absent and both try to bind it, and
+ * the loser gets EADDRINUSE — a provisioning failure in place of the
+ * dropped connection this change exists to remove. One promise, shared.
+ */
+let HTTPS_INGRESS_STARTING;
 /**
  * The live ingress tables — per-port routes and the :443 SNI cert table.
  *
@@ -1441,6 +1428,12 @@ function stopIngressServers() {
         }
     }
     INGRESS_HTTPS_SERVERS.clear();
+    // Force-closed for the same reason the listeners are: the containers
+    // behind these routes are going away, so a connection still riding them
+    // has nothing left to reach.
+    HTTPS_TERMINATOR?.close();
+    HTTPS_TERMINATOR = undefined;
+    HTTPS_INGRESS_STARTING = undefined;
     clearTables(INGRESS);
 }
 function buildIngress(project) {
@@ -1655,7 +1648,7 @@ async function startIngress() {
     }
     // ── HTTPS listener on INGRESS_HTTPS_PORT: SNI per certificated hostname.
     if (INGRESS.certByHost.size > 0)
-        rebindHttpsListener(Bun);
+        await ensureHttpsIngress(Bun);
     // Seed the resolver's names registry: ingress hostnames (fakes, TLS
     // proxies, dnsName(→ingress)) → bridge gateway, plus ingress-targeted
     // wildcards. Service-targeted wildcards wait for the post-container pass
@@ -1671,81 +1664,85 @@ function requireBun() {
     }
     return Bun;
 }
-/** Flatten the live SNI cert table into Bun's TLS-entry array. */
-function tlsEntriesFromCerts() {
-    return certEntries(INGRESS);
-}
 /**
- * (Re)bind the :443 listener from the current cert table + route map.
+ * Bring :443 up, once.
  *
- * Bun fixes a server's TLS config at `Bun.serve` time — `reload()` accepts a
- * new `tls` option and silently keeps serving the old certificates (measured
- * on Bun 1.3.14: after reloading with a second SNI entry, the new hostname
- * still gets the first one's leaf). So adding a certificate really does mean
- * a second listener.
+ * Two pieces: a plaintext `Bun.serve` on an ephemeral loopback port that
+ * carries the HTTPS route table (and therefore all the routing, fake
+ * dispatch, interception, reverse-proxying and `server.upgrade()`
+ * WebSocket bridging that :80 already gets, unchanged), and the TLS
+ * terminator in front of it on :443.
  *
- * **Bind the new one before stopping the old one.** Doing it the other way
- * round — which is what this used to do, with `stop(true)` — has two teeth:
- * the force-close kills every established connection on :443, and the gap
- * before the new listener binds refuses new ones. Neither is limited to the
- * hostname being added; they hit all the unrelated traffic the listener is
- * carrying. On a project that mints a certificate per provisioned database
- * while deploys stream through the same port, that surfaced as the app under
- * test dying with `SocketError: other side closed` or `ECONNREFUSED
- * <gateway>:443` — a different test each run, and nothing pointing at
- * ingress.
+ * **This is idempotent, and that is the feature.** Adding a certificate
+ * mutates {@link IngressTables.certByHost} and nothing else: the
+ * terminator reads that table on every handshake, so the new hostname is
+ * served by the next connection and no established connection is
+ * disturbed. The listener this replaced had to be stopped and re-served
+ * for each new certificate, and every such swap severed the idle
+ * kept-alive connections it was carrying — see
+ * `harness/tls-terminator.ts` for the measurements and the history.
  *
- * Overlapping the two needs SO_REUSEPORT on both sockets ({@link
- * bindIngressServer} sets it unconditionally for that reason), after which
- * the old listener is drained with `stop(false)` so requests in flight
- * finish. During the overlap the kernel may hand a new connection to either
- * socket, which is safe: the only hostname the two disagree about is the one
- * being added, and it does not resolve until the caller writes the names
- * registry after this returns.
+ * The route `Map` is the persistent module object, so the plaintext
+ * server closes over the same table and later route additions need no
+ * restart either.
  *
- * The route Map is the persistent module object, so the new listener closes
- * over the same table and later route additions need no rebind at all.
+ * The loopback port is ephemeral rather than fixed so it can never
+ * collide with a fake's declared port; it is bound on 127.0.0.1, which no
+ * container can reach (containers arrive at the bridge gateway), so the
+ * only way in is through the terminator.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-function rebindHttpsListener(Bun) {
-    // The *same* table object the previous listener closed over: the new
-    // listener must serve the routes bound since, and any bound later.
+async function ensureHttpsIngress(Bun) {
+    if (INGRESS_HTTPS_SERVERS.has(INGRESS_HTTPS_PORT))
+        return;
+    if (!HTTPS_INGRESS_STARTING) {
+        // Cleared on both outcomes: once bound, the check above short-circuits
+        // every later caller, and a failed bind must be retryable rather than
+        // remembered as a rejection for the life of the project.
+        HTTPS_INGRESS_STARTING = startHttpsIngress(Bun).finally(() => {
+            HTTPS_INGRESS_STARTING = undefined;
+        });
+    }
+    return HTTPS_INGRESS_STARTING;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function startHttpsIngress(Bun) {
     const routes = routesFor(INGRESS, INGRESS_HTTPS_PORT);
-    const old = INGRESS_HTTPS_SERVERS.get(INGRESS_HTTPS_PORT);
-    const server = bindIngressServer(Bun, INGRESS_HTTPS_PORT, routes, `https :${INGRESS_HTTPS_PORT}`, tlsEntriesFromCerts());
-    if (old) {
+    // `proto` is passed rather than inferred: this listener speaks plain
+    // HTTP, but everything reaching it arrived over TLS, so X-Forwarded-Proto
+    // must say https.
+    const plain = bindIngressServer(Bun, 0, routes, `https :${INGRESS_HTTPS_PORT}`, {
+        proto: "https",
+        hostname: "127.0.0.1",
+    });
+    INGRESS_HTTPS_SERVERS.set(INGRESS_HTTPS_PORT, plain);
+    try {
+        HTTPS_TERMINATOR = await startTlsTerminator({
+            port: INGRESS_HTTPS_PORT,
+            hostname: "0.0.0.0",
+            upstreamPort: plain.port,
+            certFor: (serverName) => {
+                if (serverName === undefined)
+                    return INGRESS.certByHost.values().next().value;
+                const name = selectCertName(INGRESS.certByHost.keys(), serverName.toLowerCase());
+                return name === undefined ? undefined : INGRESS.certByHost.get(name);
+            },
+        });
+    }
+    catch (err) {
+        // Leave nothing half-built: a registered plaintext server with no
+        // terminator would make `planBind` believe :443 is up.
+        INGRESS_HTTPS_SERVERS.delete(INGRESS_HTTPS_PORT);
         try {
-            // Graceful: stop accepting, let in-flight requests finish. The old
-            // server stays alive until they do, which is the point — a long
-            // upload through ingress must not be collateral damage of another
-            // service being provisioned.
-            old.stop(false);
-            // Bun 1.3.14 landmine: a request arriving later on one of the old
-            // server's kept-alive connections dispatches into freed state and can
-            // segfault the daemon (see {@link DRAINING_INGRESS}). Mark it so any
-            // response it still serves closes its connection, and force-close the
-            // stragglers once in-flight work has had a fair window to finish.
-            DRAINING_INGRESS.add(old);
-            const graceTimer = setTimeout(() => {
-                try {
-                    old.stop(true);
-                }
-                catch {
-                    /* already fully stopped */
-                }
-            }, REBIND_DRAIN_GRACE_MS);
-            // Don't let the grace timer keep the process alive on shutdown.
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            graceTimer.unref?.();
+            plain.stop(true);
         }
-        catch (err) {
-            // eslint-disable-next-line no-console
-            console.warn("[ingress] failed to drain the previous https listener:", err);
+        catch {
+            /* already gone */
         }
+        throw err;
     }
-    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(", ")}`);
+    console.log(`[ingress] https :${INGRESS_HTTPS_PORT} (tls terminator -> :${plain.port}) for ${[...routes.keys()].join(", ")}`);
 }
 /**
  * RFC 6125 wildcard match: `*.example.com` covers `api.example.com` but NOT
@@ -1800,10 +1797,13 @@ async function bindRuntimeTls(hostname, service, port) {
         INGRESS_HTTP_SERVERS.set(INGRESS_HTTP_PORT, bindIngressServer(Bun, INGRESS_HTTP_PORT, routesFor(INGRESS, INGRESS_HTTP_PORT), `port ${INGRESS_HTTP_PORT}`));
     }
     if (plan.needsCert) {
+        // The terminator reads this table on every handshake, so the leaf is
+        // live the moment it lands — no listener is touched, and no connection
+        // already on :443 notices.
         INGRESS.certByHost.set(host, await generateHostCert(host, [host]));
     }
-    if (plan.needsHttpsRebind)
-        rebindHttpsListener(Bun);
+    if (plan.needsHttpsListener)
+        await ensureHttpsIngress(Bun);
     // Resolve the hostname to the daemon gateway (where :443/:80 listen).
     // A wildcard can only live in the resolver's suffix table.
     const gw = await bridgeGatewayIp();
@@ -1851,20 +1851,26 @@ async function unbindRuntimeTls(hostname) {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function bindIngressServer(
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-Bun, port, byHost, listenerLabel, tlsEntries) {
-    // A TLS listener terminates https; everything else is plain http. Used
-    // to stamp X-Forwarded-Proto so upstreams that build absolute URLs or
-    // redirect see the scheme the client actually used, not our http hop.
-    const proto = tlsEntries ? "https" : "http";
+Bun, port, byHost, listenerLabel, 
+// Every ingress listener speaks plain HTTP now — the one behind :443
+// sits under the TLS terminator. So the scheme a client actually used
+// can no longer be inferred from the socket and is declared instead; it
+// stamps X-Forwarded-Proto, which upstreams that build absolute URLs or
+// redirect depend on.
+serve = { proto: "http" }) {
+    const proto = serve.proto;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const opts = {
         port,
-        hostname: "0.0.0.0",
-        // SO_REUSEPORT on every ingress listener, so a replacement can be bound
-        // while the old one is still serving. That overlap is the only way to
-        // add an SNI certificate without a gap — see {@link rebindHttpsListener}
-        // — and it only works if *both* sockets opt in: a second plain bind
-        // fails with "Is port 443 in use?".
+        hostname: serve.hostname ?? "0.0.0.0",
+        // SO_REUSEPORT on every ingress listener. It was introduced so a
+        // replacement :443 could overlap the original during a certificate
+        // swap; the terminator removed that swap, and this stays for the
+        // remaining case — the `/load` teardown force-closes and rebinds, and
+        // a socket the kernel has not finished releasing would otherwise fail
+        // the next bind with "Is port 443 in use?". Note the flip side, which
+        // {@link stopIngressServers} depends on: a half-alive listener shares
+        // the port silently instead of colliding loudly.
         reusePort: true,
         // Bun.serve defaults to a 10s idleTimeout, which kills any proxied
         // request whose upstream takes >10s to produce bytes — under parallel
@@ -1876,7 +1882,7 @@ Bun, port, byHost, listenerLabel, tlsEntries) {
         // short-lived, leaked-connection risk is bounded by the fork.
         idleTimeout: 0,
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        fetch: (req, server) => dispatchIngress(req, server, byHost, listenerLabel, proto).then((res) => withDrainClose(server, res)),
+        fetch: (req, server) => dispatchIngress(req, server, byHost, listenerLabel, proto),
         websocket: {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             async open(ws) {
@@ -1953,8 +1959,6 @@ Bun, port, byHost, listenerLabel, tlsEntries) {
             },
         },
     };
-    if (tlsEntries)
-        opts.tls = tlsEntries;
     return Bun.serve(opts);
 }
 /**
@@ -2018,6 +2022,28 @@ server, byHost, listenerLabel, proto) {
         : await runChain(chain, req, upstream, recordInterceptedRequest);
     return augmentCorsResponse(req, res);
 }
+/**
+ * The address to report as the client's in `X-Forwarded-For`.
+ *
+ * On :80 that is simply the socket's peer. On :443 the peer is the TLS
+ * terminator on loopback, so the real address has to be recovered from it:
+ * the terminator keys `source port -> client address` for the life of each
+ * upstream connection, and the source port is what `requestIP` reports
+ * here. Gated on `proto === "https"` so a genuinely loopback caller on :80
+ * can never pick up an unrelated terminator connection's port.
+ *
+ * Falling back to the socket's own address means the worst case is the
+ * pre-terminator answer for a plain HTTP hop, never a wrong tenant.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function ingressClientIp(server, req, proto) {
+    const peer = server.requestIP?.(req);
+    if (!peer?.address)
+        return undefined;
+    if (proto !== "https")
+        return peer.address;
+    return HTTPS_TERMINATOR?.clientIpFor(peer.port) ?? peer.address;
+}
 /**
  * Reverse-proxy a request to `http://<service>:<port>` on
  * `spectest-net`. Handles plain HTTP/1.1 + 2 and WebSocket upgrades:
@@ -2067,7 +2093,7 @@ server, service, port, listenerLabel, proto) {
     // Standard reverse-proxy provenance headers: the upstream sees the
     // public scheme/host it was reached through and the client's address,
     // even though we rewrite Host below to the service-net name.
-    const clientIp = server.requestIP?.(req)?.address;
+    const clientIp = ingressClientIp(server, req, proto);
     const priorXff = req.headers.get("x-forwarded-for");
     const xff = clientIp ? (priorXff ? `${priorXff}, ${clientIp}` : clientIp) : priorXff;
     if (xff)

package/dist/harness/hostmatch.d.ts

@@ -48,6 +48,23 @@ export declare function wildcardCoversHost(pattern: string, hostname: string): b
  * `HTTPS_CERT_BY_HOST.keys()`.
  */
 export declare function certCovers(serverNames: Iterable<string>, hostname: string): boolean;
+/**
+ * Pick the certificate server name that should serve `hostname`'s TLS
+ * handshake: the exact entry first, then the longest matching wildcard.
+ *
+ * This is the same precedence {@link matchRoute} applies to routes and the
+ * resolver applies to DNS — but over the *certificate* rule, so a wildcard
+ * covers exactly one label ({@link wildcardCoversHost}) rather than any
+ * depth.
+ *
+ * It exists because the SNI lookup is now ours to make. Until the :443
+ * listener stopped being rebuilt for every new certificate, Bun performed
+ * this match internally from the `tls` array it was served with; the
+ * terminator picks a certificate per handshake instead, so the rule has to
+ * be written down — and, being written down, it is testable, which Bun's
+ * internal version never was.
+ */
+export declare function selectCertName(serverNames: Iterable<string>, hostname: string): string | undefined;
 /**
  * Pick the route for `host`: exact match first, then the longest matching
  * wildcard suffix.

package/dist/harness/hostmatch.js

@@ -65,6 +65,39 @@ export function certCovers(serverNames, hostname) {
         return true;
     return names.some((n) => isWildcard(n) && wildcardCoversHost(n, hostname));
 }
+/**
+ * Pick the certificate server name that should serve `hostname`'s TLS
+ * handshake: the exact entry first, then the longest matching wildcard.
+ *
+ * This is the same precedence {@link matchRoute} applies to routes and the
+ * resolver applies to DNS — but over the *certificate* rule, so a wildcard
+ * covers exactly one label ({@link wildcardCoversHost}) rather than any
+ * depth.
+ *
+ * It exists because the SNI lookup is now ours to make. Until the :443
+ * listener stopped being rebuilt for every new certificate, Bun performed
+ * this match internally from the `tls` array it was served with; the
+ * terminator picks a certificate per handshake instead, so the rule has to
+ * be written down — and, being written down, it is testable, which Bun's
+ * internal version never was.
+ */
+export function selectCertName(serverNames, hostname) {
+    const names = [...serverNames];
+    if (names.includes(hostname))
+        return hostname;
+    let best;
+    let bestLen = -1;
+    for (const name of names) {
+        if (!isWildcard(name) || !wildcardCoversHost(name, hostname))
+            continue;
+        const len = wildcardSuffix(name).length;
+        if (len > bestLen) {
+            best = name;
+            bestLen = len;
+        }
+    }
+    return best;
+}
 /**
  * Pick the route for `host`: exact match first, then the longest matching
  * wildcard suffix.

package/dist/harness/ingress-table.d.ts

@@ -32,13 +32,14 @@
  * routes added afterwards go nowhere. {@link routesFor} is the only way to
  * reach a table so that this can't be done by accident.
  *
- * **A rebind is not free, so it must be earned.** Bun fixes a server's TLS
- * config at `Bun.serve` time — `reload` will not add an SNI entry — so a
- * genuinely new certificate means stopping and re-serving :443. It's cheap
- * (~1 ms) but it is a real interruption of live traffic, and a hostname
- * already covered by an existing exact or wildcard cert needs nothing but a
- * route entry. {@link planBind} is that judgement, separated from the
- * mutation so it can be tested without a network stack.
+ * **Adding a certificate no longer touches the listener.** :443 is
+ * terminated by `harness/tls-terminator.ts`, which chooses a leaf per TLS
+ * handshake, so a new certificate is a `Map` entry and nothing more. It
+ * used to mean stopping and re-serving :443, and that swap severed every
+ * idle kept-alive connection the listener was carrying — an unrelated
+ * test's request, failing with `SocketError: other side closed`. The only
+ * thing {@link planBind} still has to say is whether the listener exists
+ * yet.
  */
 /**
  * One hostname's upstream: a fake handled in-process, or a container.
@@ -89,18 +90,21 @@ export declare function routesFor<F>(tables: IngressTables<F>, port: number): Ma
 export interface BindPlan {
     /** No existing cert covers the hostname, so a leaf must be minted. */
     needsCert: boolean;
-    /** The :443 listener must be stopped and re-served. */
-    needsHttpsRebind: boolean;
+    /** The :443 listener does not exist yet and must be started. */
+    needsHttpsListener: boolean;
 }
 /**
  * Decide what binding `hostname` for TLS costs.
  *
- * A rebind is needed when a new certificate is going into the SNI table,
- * or when :443 isn't listening yet. It is deliberately *not* needed for a
- * hostname an existing wildcard already covers — the common case when a
- * component claims a whole domain up front and services appear under it
- * later, and the reason a fake can mint endpoints in a loop without
- * restarting the listener once per iteration.
+ * Minting is still earned — a hostname an existing exact or wildcard cert
+ * already covers needs nothing but a route, which is why a component can
+ * claim a whole domain up front and have services appear under it for
+ * free.
+ *
+ * Starting the listener, on the other hand, is now a once-per-process
+ * event: it is needed when :443 is not up yet, and never again. A new
+ * certificate does **not** imply it. That is the whole point of the
+ * terminator — see the module header.
  */
 export declare function planBind<F>(tables: IngressTables<F>, hostname: string, opts: {
     httpsListening: boolean;
@@ -117,11 +121,18 @@ export declare function bindRoute<F>(tables: IngressTables<F>, hostname: string,
  * Drop `hostname`'s routes, so it 404s.
  *
  * The certificate is deliberately left in the SNI table: it is harmless
- * without a route, and removing it would force an otherwise unnecessary
- * :443 rebind at exactly the moment a service is going away.
+ * without a route, and a leaf nobody asks for costs one unused `Map`
+ * entry. (Before the terminator, removing it would also have forced a
+ * :443 rebind at exactly the moment a service was going away.)
  */
 export declare function unbindRoute<F>(tables: IngressTables<F>, hostname: string): void;
-/** The SNI entries for `Bun.serve`'s TLS config. */
+/**
+ * The SNI table flattened to entries.
+ *
+ * This was `Bun.serve`'s `tls` array. The terminator selects per handshake
+ * instead ({@link import("./hostmatch").selectCertName}), so this survives
+ * as the readable projection of the table — for diagnostics and tests.
+ */
 export declare function certEntries<F>(tables: IngressTables<F>): Array<{
     cert: string;
     key: string;

package/dist/harness/ingress-table.js

@@ -32,13 +32,14 @@
  * routes added afterwards go nowhere. {@link routesFor} is the only way to
  * reach a table so that this can't be done by accident.
  *
- * **A rebind is not free, so it must be earned.** Bun fixes a server's TLS
- * config at `Bun.serve` time — `reload` will not add an SNI entry — so a
- * genuinely new certificate means stopping and re-serving :443. It's cheap
- * (~1 ms) but it is a real interruption of live traffic, and a hostname
- * already covered by an existing exact or wildcard cert needs nothing but a
- * route entry. {@link planBind} is that judgement, separated from the
- * mutation so it can be tested without a network stack.
+ * **Adding a certificate no longer touches the listener.** :443 is
+ * terminated by `harness/tls-terminator.ts`, which chooses a leaf per TLS
+ * handshake, so a new certificate is a `Map` entry and nothing more. It
+ * used to mean stopping and re-serving :443, and that swap severed every
+ * idle kept-alive connection the listener was carrying — an unrelated
+ * test's request, failing with `SocketError: other side closed`. The only
+ * thing {@link planBind} still has to say is whether the listener exists
+ * yet.
  */
 import { certCovers, isWildcard, wildcardSuffix } from "./hostmatch";
 /** Fixed HTTPS port shared by every TLS route (fakes + service `tls`). */
@@ -66,16 +67,19 @@ export function routesFor(tables, port) {
 /**
  * Decide what binding `hostname` for TLS costs.
  *
- * A rebind is needed when a new certificate is going into the SNI table,
- * or when :443 isn't listening yet. It is deliberately *not* needed for a
- * hostname an existing wildcard already covers — the common case when a
- * component claims a whole domain up front and services appear under it
- * later, and the reason a fake can mint endpoints in a loop without
- * restarting the listener once per iteration.
+ * Minting is still earned — a hostname an existing exact or wildcard cert
+ * already covers needs nothing but a route, which is why a component can
+ * claim a whole domain up front and have services appear under it for
+ * free.
+ *
+ * Starting the listener, on the other hand, is now a once-per-process
+ * event: it is needed when :443 is not up yet, and never again. A new
+ * certificate does **not** imply it. That is the whole point of the
+ * terminator — see the module header.
  */
 export function planBind(tables, hostname, opts) {
     const needsCert = !certCovers(tables.certByHost.keys(), hostname);
-    return { needsCert, needsHttpsRebind: needsCert || !opts.httpsListening };
+    return { needsCert, needsHttpsListener: !opts.httpsListening };
 }
 /**
  * Point `hostname` at `route` on both :80 and :443.
@@ -92,14 +96,21 @@ export function bindRoute(tables, hostname, route) {
  * Drop `hostname`'s routes, so it 404s.
  *
  * The certificate is deliberately left in the SNI table: it is harmless
- * without a route, and removing it would force an otherwise unnecessary
- * :443 rebind at exactly the moment a service is going away.
+ * without a route, and a leaf nobody asks for costs one unused `Map`
+ * entry. (Before the terminator, removing it would also have forced a
+ * :443 rebind at exactly the moment a service was going away.)
  */
 export function unbindRoute(tables, hostname) {
     tables.routesByPort.get(INGRESS_HTTP_PORT)?.delete(hostname);
     tables.routesByPort.get(INGRESS_HTTPS_PORT)?.delete(hostname);
 }
-/** The SNI entries for `Bun.serve`'s TLS config. */
+/**
+ * The SNI table flattened to entries.
+ *
+ * This was `Bun.serve`'s `tls` array. The terminator selects per handshake
+ * instead ({@link import("./hostmatch").selectCertName}), so this survives
+ * as the readable projection of the table — for diagnostics and tests.
+ */
 export function certEntries(tables) {
     return [...tables.certByHost].map(([serverName, leaf]) => ({
         cert: leaf.cert,

package/dist/harness/tls-terminator.d.ts

@@ -0,0 +1,32 @@
+import type { Leaf } from "./ingress-table";
+export interface TlsTerminatorOptions {
+    /** Public port to accept TLS on (443 in the harness). */
+    port: number;
+    /** Interface to accept on. */
+    hostname: string;
+    /** Loopback port of the plaintext ingress server to pipe into. */
+    upstreamPort: number;
+    /**
+     * The leaf to serve for an SNI server name, read live on every
+     * handshake — this is what lets a certificate be added with no restart.
+     * `undefined` server name means the client sent no SNI.
+     */
+    certFor(serverName: string | undefined): Leaf | undefined;
+    /** Non-fatal diagnostics (a handshake a client aborted, a pipe error). */
+    onWarning?(message: string, err: unknown): void;
+}
+export interface TlsTerminator {
+    /** The port actually bound. */
+    readonly port: number;
+    /**
+     * The real client address behind an upstream connection, keyed by the
+     * source port the plaintext server sees. `undefined` for a port this
+     * terminator did not open.
+     */
+    clientIpFor(upstreamPort: number | undefined): string | undefined;
+    /** Open TLS connections right now (diagnostics and tests). */
+    connectionCount(): number;
+    /** Stop accepting and force-close every connection. */
+    close(): void;
+}
+export declare function startTlsTerminator(opts: TlsTerminatorOptions): Promise<TlsTerminator>;