@specific.dev/spectest 0.53.0 → 0.54.0

package/dist/daemon.js

@@ -1305,6 +1305,44 @@ const INGRESS_HTTP_SERVERS = new Map();
 /** 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();
+/**
+ * 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}).
+ */
+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,
+        });
+    }
+}
 /**
  * The live ingress tables — per-port routes and the :443 SNI cert table.
  *
@@ -1627,6 +1665,23 @@ function rebindHttpsListener(Bun) {
             // 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?.();
         }
         catch (err) {
             // eslint-disable-next-line no-console
@@ -1766,7 +1821,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),
+        fetch: (req, server) => dispatchIngress(req, server, byHost, listenerLabel, proto).then((res) => withDrainClose(server, res)),
         websocket: {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             async open(ws) {
@@ -3308,6 +3363,26 @@ function describeRequestBody(input, init) {
     }
     return { body: `[non-text body: ${body.constructor?.name ?? typeof body}]` };
 }
+/**
+ * Marks an error thrown by the instrumented fetch as *transport-level* —
+ * the connection itself failed (refused, unresolvable, reset) before any
+ * HTTP reply existed. `fetch` never rejects for an HTTP status, so every
+ * rejection short of an abort is transport. `Symbol.for` so a duplicated
+ * SDK module instance (the bun hardlink landmine) still recognises it.
+ *
+ * Why it exists: `ctx.poll` waits for convergence, and right after a fork
+ * restore the guest can serve a ~10 s window where a connect or a DNS
+ * lookup fails once and then heals (measured 2026-08-21: a poll's first
+ * fetch hung 12 s in resolution, threw, and killed a 60 s poll on attempt
+ * 1 while attempt 2 would have passed). During a poll, a dead connection
+ * is just "not ready yet"; outside one it stays a hard error.
+ */
+const TRANSPORT_ERROR = Symbol.for("spectest.transportError");
+function isTransportError(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err[TRANSPORT_ERROR] === true);
+}
 /**
  * Install a fetch wrapper on `globalThis` that emits HTTP events into the
  * active recorder. Returns a restore function. Calls outside of a running
@@ -3378,6 +3453,20 @@ function installFetchWrapper() {
                 durationMs: Date.now() - start,
                 error: e?.message ?? String(err),
             }, resv);
+            // Tag transport failures for ctx.poll (see TRANSPORT_ERROR). An abort
+            // is the caller's own signal (their AbortController or their
+            // AbortSignal.timeout) — their semantics, never retried for them.
+            if (typeof err === "object" &&
+                err !== null &&
+                e?.name !== "AbortError" &&
+                e?.name !== "TimeoutError") {
+                try {
+                    err[TRANSPORT_ERROR] = true;
+                }
+                catch {
+                    /* frozen error object — stays a hard error */
+                }
+            }
             throw err;
         }
     };
@@ -3589,6 +3678,7 @@ async function pollCall(description, fn, opts) {
     let value;
     let success = false;
     let predicateError;
+    let lastTransportError;
     // Record all iterations normally, but keep only the newest one: a new
     // attempt drops the events the previous attempt emitted, so the timeline
     // never fills with polling noise. Whichever attempt is last when the loop
@@ -3618,8 +3708,19 @@ async function pollCall(description, fn, opts) {
             }
         }
         catch (err) {
-            predicateError = err;
-            break;
+            // A transport-level fetch failure (connection refused, DNS miss —
+            // see TRANSPORT_ERROR) is "not ready yet", not a verdict: polls wait
+            // for convergence, and services legitimately refuse connections
+            // while they come up. Keep polling; the kept last attempt's http
+            // event carries the error for the timeline. Anything else — an
+            // assertion, a TypeError, a user abort — stays fatal on attempt 1.
+            if (isTransportError(err)) {
+                lastTransportError = err;
+            }
+            else {
+                predicateError = err;
+                break;
+            }
         }
         if (Date.now() - start + intervalMs > timeoutMs)
             break;
@@ -3629,7 +3730,9 @@ async function pollCall(description, fn, opts) {
         ? (predicateError?.message ?? String(predicateError))
         : success
             ? undefined
-            : `timed out after ${timeoutMs}ms`;
+            : lastTransportError !== undefined
+                ? `timed out after ${timeoutMs}ms (last attempt: ${lastTransportError?.message ?? String(lastTransportError)})`
+                : `timed out after ${timeoutMs}ms`;
     const seq = recordWait({
         description,
         attempts,
@@ -3648,7 +3751,10 @@ async function pollCall(description, fn, opts) {
     if (success) {
         return wrap(value, seq);
     }
-    throw new Error(`poll ${JSON.stringify(description)} timed out after ${timeoutMs}ms (${attempts} attempts)`);
+    const lastAttempt = lastTransportError !== undefined
+        ? `; last attempt: ${lastTransportError?.message ?? String(lastTransportError)}`
+        : "";
+    throw new Error(`poll ${JSON.stringify(description)} timed out after ${timeoutMs}ms (${attempts} attempts${lastAttempt})`);
 }
 function captureConsole(chunks) {
     const methods = ["log", "info", "warn", "error", "debug"];

package/package.json

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

package/src/daemon.ts

@@ -1677,6 +1677,43 @@ 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>();
+/**
+ * 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}).
+ */
+const DRAINING_INGRESS = new WeakSet<object>();
+/** 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: any, res: Response): Response {
+  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,
+    });
+  }
+}
 /**
  * The live ingress tables — per-port routes and the :443 SNI cert table.
  *
@@ -2033,6 +2070,22 @@ function rebindHttpsListener(Bun: any): void {
       // 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 as any).unref?.();
     } catch (err) {
       // eslint-disable-next-line no-console
       console.warn("[ingress] failed to drain the previous https listener:", err);
@@ -2191,7 +2244,9 @@ function bindIngressServer(
     idleTimeout: 0,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     fetch: (req: Request, server: any): Response | Promise<Response> =>
-      dispatchIngress(req, server, byHost, listenerLabel, proto),
+      dispatchIngress(req, server, byHost, listenerLabel, proto).then((res) =>
+        withDrainClose(server, res),
+      ),
     websocket: {
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       async open(ws: any) {
@@ -4090,6 +4145,30 @@ function describeRequestBody(
   return { body: `[non-text body: ${body.constructor?.name ?? typeof body}]` };
 }
 
+/**
+ * Marks an error thrown by the instrumented fetch as *transport-level* —
+ * the connection itself failed (refused, unresolvable, reset) before any
+ * HTTP reply existed. `fetch` never rejects for an HTTP status, so every
+ * rejection short of an abort is transport. `Symbol.for` so a duplicated
+ * SDK module instance (the bun hardlink landmine) still recognises it.
+ *
+ * Why it exists: `ctx.poll` waits for convergence, and right after a fork
+ * restore the guest can serve a ~10 s window where a connect or a DNS
+ * lookup fails once and then heals (measured 2026-08-21: a poll's first
+ * fetch hung 12 s in resolution, threw, and killed a 60 s poll on attempt
+ * 1 while attempt 2 would have passed). During a poll, a dead connection
+ * is just "not ready yet"; outside one it stays a hard error.
+ */
+const TRANSPORT_ERROR = Symbol.for("spectest.transportError");
+
+function isTransportError(err: unknown): boolean {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    (err as Record<symbol, unknown>)[TRANSPORT_ERROR] === true
+  );
+}
+
 /**
  * Install a fetch wrapper on `globalThis` that emits HTTP events into the
  * active recorder. Returns a restore function. Calls outside of a running
@@ -4159,6 +4238,21 @@ function installFetchWrapper(): () => void {
         durationMs: Date.now() - start,
         error: e?.message ?? String(err),
       }, resv);
+      // Tag transport failures for ctx.poll (see TRANSPORT_ERROR). An abort
+      // is the caller's own signal (their AbortController or their
+      // AbortSignal.timeout) — their semantics, never retried for them.
+      if (
+        typeof err === "object" &&
+        err !== null &&
+        e?.name !== "AbortError" &&
+        e?.name !== "TimeoutError"
+      ) {
+        try {
+          (err as Record<symbol, unknown>)[TRANSPORT_ERROR] = true;
+        } catch {
+          /* frozen error object — stays a hard error */
+        }
+      }
       throw err;
     }
   };
@@ -4410,6 +4504,7 @@ async function pollCall<T>(
   let value: T | undefined;
   let success = false;
   let predicateError: unknown;
+  let lastTransportError: unknown;
 
   // Record all iterations normally, but keep only the newest one: a new
   // attempt drops the events the previous attempt emitted, so the timeline
@@ -4440,8 +4535,18 @@ async function pollCall<T>(
         break;
       }
     } catch (err) {
-      predicateError = err;
-      break;
+      // A transport-level fetch failure (connection refused, DNS miss —
+      // see TRANSPORT_ERROR) is "not ready yet", not a verdict: polls wait
+      // for convergence, and services legitimately refuse connections
+      // while they come up. Keep polling; the kept last attempt's http
+      // event carries the error for the timeline. Anything else — an
+      // assertion, a TypeError, a user abort — stays fatal on attempt 1.
+      if (isTransportError(err)) {
+        lastTransportError = err;
+      } else {
+        predicateError = err;
+        break;
+      }
     }
     if (Date.now() - start + intervalMs > timeoutMs) break;
     await new Promise((r) => setTimeout(r, intervalMs));
@@ -4452,7 +4557,11 @@ async function pollCall<T>(
       ? ((predicateError as Error)?.message ?? String(predicateError))
       : success
         ? undefined
-        : `timed out after ${timeoutMs}ms`;
+        : lastTransportError !== undefined
+          ? `timed out after ${timeoutMs}ms (last attempt: ${
+              (lastTransportError as Error)?.message ?? String(lastTransportError)
+            })`
+          : `timed out after ${timeoutMs}ms`;
   const seq = recordWait({
     description,
     attempts,
@@ -4472,8 +4581,12 @@ async function pollCall<T>(
   if (success) {
     return wrap(value as T, seq) as T;
   }
+  const lastAttempt =
+    lastTransportError !== undefined
+      ? `; last attempt: ${(lastTransportError as Error)?.message ?? String(lastTransportError)}`
+      : "";
   throw new Error(
-    `poll ${JSON.stringify(description)} timed out after ${timeoutMs}ms (${attempts} attempts)`,
+    `poll ${JSON.stringify(description)} timed out after ${timeoutMs}ms (${attempts} attempts${lastAttempt})`,
   );
 }