@nifrajs/core 5.3.0 → 5.5.0

package/dist/server/server.js

@@ -8,7 +8,7 @@ import { adoptRouteRuntimes, compileRouteOptions } from "../internal/route-compi
 import { compileRouteExecutionPlan, } from "../internal/route-execution.js";
 import { compileRouteProgram, executeRouteProgram } from "../internal/route-program.js";
 import { isSameOriginRequest } from "../internal/same-origin.js";
-import { decodeRouteParams, expandOptionalParams } from "../router/pattern.js";
+import { decodeRouteParams, expandOptionalParams, } from "../router/pattern.js";
 import { EMPTY_PARAMS, METHODS, Router } from "../router/router.js";
 import { emitRequestErrorLog, renderBareError } from "./bare-error-lane.js";
 import { assertByteLimit, markTransportCap, markTrustedBodyFraming, UNLIMITED_BODY_BYTES, } from "./body.js";
@@ -22,7 +22,7 @@ import { queryObjectOf, searchOf } from "./query.js";
 import { PLATFORM_PEER, RequestContext, readBodyFramed, } from "./request-context.js";
 import { recordRequestReplacement } from "./request-lineage.js";
 import { needsResolving, resolveDotSegments } from "./request-target.js";
-import { applyStaticResponseHeaders, buildStaticResponseHeaders, fusedRespond, fusedRespondNoSet, toResponse, writableResponse, } from "./respond.js";
+import { applyStaticResponseHeaders, buildStaticResponseHeaders, claimHandedOver, fusedRespond, fusedRespondNoSet, handedBackResponse, recordResidentTexts, toResponse, writableResponse, } from "./respond.js";
 import { CONTEXT_REQUEST, CONTEXT_SEARCH, CONTEXT_SET, EMPTY_RESPONSE_CONTROLS, getNeverAbortSignal, getUnboundedRequestBudget, headerOf, isResponseResult, requestOf, } from "./runtime-core.js";
 import { normalizeStaticResponseHeaders } from "./static-headers.js";
 import { plainValidationError } from "./validation.js";
@@ -54,6 +54,9 @@ function bunPeerPlatform(server, req) {
         },
     };
 }
+// Bun's route table has a slot for each of these; a QUERY entry is ignored and the request falls
+// through to the table's fetch, so QUERY routes stay on the portable dispatcher.
+const BUN_TABLE_METHODS = METHODS.filter((method) => method !== "QUERY");
 /**
  * Whether the portable router gives `other` a request that `route` also matches: the two patterns can
  * match one path, and `other` is the more specific at the first segment where they differ. `route`
@@ -80,6 +83,23 @@ function outranks(other, route) {
     }
     return ahead && other.length === route.length;
 }
+/**
+ * The key Bun's route table holds `path` under. Bun refuses one with a character outside printable
+ * ASCII, so such a path is spelled as the portable router matches it: percent-encoded static
+ * segments and `:name` parameters. `segments` holds static and `:param` segments only.
+ */
+function bunTablePath(path, segments) {
+    if (!/[^ -~]/.test(path))
+        return path;
+    let key = "";
+    for (const segment of segments) {
+        if (segment.kind === "static")
+            key += `/${segment.value}`;
+        else if (segment.kind === "param")
+            key += `/:${segment.name}`;
+    }
+    return key;
+}
 const WS_PASS = { kind: "pass" };
 const DEFAULT_WS_UPGRADE_TIMEOUT_MS = 10_000;
 /** Counts `ws()` routes and `mount()`s across every app in this copy of core: the only
@@ -157,8 +177,9 @@ const withResolvedTarget = (req) => new Request(resolveDotSegments(req.url), req
 // `Request.url` by appending the target to the Host as received, so `Host: x/admin#` turned a
 // request for `/public` into one for `/admin`. Node refuses such a Host before routing; so does this.
 const HOST_AUTHORITY = /^(?:\[[0-9a-f:.%]+\]|[\w.-]+)(?::\d{1,5})?$/i;
+// `headerOf`, not `req.headers`: on Deno that reads the Host alone instead of building every header.
 const invalidHost = (req) => {
-    const host = req.headers.get("host");
+    const host = headerOf(req, "host");
     return host !== null && !HOST_AUTHORITY.test(host);
 };
 function normalizeMountPrefix(path) {
@@ -287,6 +308,12 @@ const SERVER_RUNTIMES = [
 // Stable module-level finalizers so `fetch`/`resolveNode` allocate no per-request closures.
 const IDENTITY_RESPONSE = (response) => webResponseOf(response);
 const RESPONSE_TIMEOUT = () => jsonError(503, "request_timeout");
+/** An `onRequest` hook's answer, held to the single-use check a handler's result gets. */
+function earlyAnswer(answer, wrapResponse) {
+    return answer instanceof Response && !claimHandedOver(answer)
+        ? wrapResponse(plainError(500, "internal_error"))
+        : wrapResponse(answer);
+}
 // The unused-order-scoped-hook audit (recorder, seal check, stack capture, message) is a dev-time
 // diagnostic. Every guard below keeps the INLINE literal `process.env.NODE_ENV !== "production"` at the
 // branch - never a shared const holding the folded boolean - because a bundler's `process.env.NODE_ENV`
@@ -327,6 +354,9 @@ const captureCallerSite = () => {
     return undefined;
 };
 const hookAudit = /* @__PURE__ */ new WeakMap();
+// Audits begun and not yet sealed. Zero outside development, so a request tests it before the
+// NODE_ENV literal and never reads `process.env` (a native call of ~130 ns on Node).
+let unsealedHookAudits = 0;
 /** Whether `from` reaches `target` through mounts that keep the path and take a request under `path`.
  * Module-level, not a `Server` method, so a production bundle drops it with its dev-only caller. */
 function mountLeadsBack(from, target, path, mountsOf, seen) {
@@ -344,6 +374,7 @@ function mountLeadsBack(from, target, path, mountsOf, seen) {
 const PAGES_DECLARED = /* @__PURE__ */ Symbol.for("nifra.web.pagesDeclared");
 /** Start tracking one server's order-scoped hook pushes (once, from the constructor). */
 const beginHookAudit = (key, policy, hasCustomLogger) => {
+    unsealedHookAudits++;
     hookAudit.set(key, {
         policy,
         hasCustomLogger,
@@ -434,6 +465,7 @@ const sealHookAudit = (key, total, sockets, logger) => {
     if (state === undefined || state.checked)
         return;
     state.checked = true;
+    unsealedHookAudits--;
     if (state.policy === "off" || total + sockets === 0)
         return;
     const own = total - state.merged;
@@ -554,6 +586,9 @@ export class Server {
     /** App-wide validation-error fallback; a route's own `schema.onValidationError` takes precedence. */
     defaultOnValidationError;
     bunServer;
+    // Bun's `pendingRequests` leaves out upgraded sockets, so `stop()` closes these itself.
+    bunSockets;
+    signalHandler;
     sealed;
     derives;
     /** Dedicated authentication stages captured by subsequent routes. */
@@ -895,7 +930,8 @@ export class Server {
     /**
      * Run before routing on the raw request. Return a `Response` or a `status()` result to
      * short-circuit, or a replacement `Request` to continue routing with a rewritten method/URL/headers.
-     * Global.
+     * Global. A throw or rejection goes to every registered {@link onError} (route-less context), then
+     * the logged default 500.
      */
     onRequest(fn) {
         this.assertConfigurable("onRequest()");
@@ -981,8 +1017,8 @@ export class Server {
     }
     /** Handle a thrown error; a non-`undefined` return becomes the response (else the default 500, or 503
      * `auth_unavailable` for a failed {@link authenticate} stage). Order-scoped: captured by routes
-     * declared *after* this call, none before; one added after the last route reaches nothing (see
-     * {@link ServerOptions.unusedScopedHooks}). */
+     * declared *after* this call, none before; one added after the last route reaches no route (see
+     * {@link ServerOptions.unusedScopedHooks}). Every one answers an {@link onRequest} failure. */
     onError(fn) {
         this.assertConfigurable("onError()");
         this.onErrorHooks.push(fn);
@@ -1075,6 +1111,7 @@ export class Server {
         if (this.responseBodyTag === undefined) {
             this.responseBodyTag = Object.freeze({});
             this.responseBodyOwners.add(this.responseBodyTag);
+            recordResidentTexts();
         }
         return this.responseBodyTag;
     }
@@ -1572,6 +1609,7 @@ export class Server {
                 if (this.responseBodyTag === undefined) {
                     this.responseBodyTag = Object.freeze({});
                     this.responseBodyOwners.add(this.responseBodyTag);
+                    recordResidentTexts();
                 }
                 return this.responseBodyTag;
             },
@@ -2007,8 +2045,8 @@ export class Server {
     }
     fetchSource(source, platform) {
         // Seal once on the first request so test servers (no `listen()`) still get the dead-hook check.
-        // After that it is a single boolean read - the per-request cost the option promises to keep at zero.
-        if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+        // After that it is one integer compare; the literal stays so a production define drops the branch.
+        if (unsealedHookAudits !== 0 && process.env.NODE_ENV !== "production")
             sealHookAudit(this, this.catalog.size, this.wsRoutes.length, this.logger);
         // Off path (default): straight through - one property check, no closure, no promise.
         if (this.capacityGate === undefined)
@@ -2093,6 +2131,9 @@ export class Server {
      * a path whose registered route rejects this method.
      */
     [RESOLVE_NODE_MOUNT](source) {
+        // Node asks before every dispatch; an app with no mounts cannot select a native handler.
+        if (this.fetchMounts.length === 0)
+            return undefined;
         if (this.onRequestHooks.length > 0 ||
             this.onResponseHooks.length > 0 ||
             this.onResponseFinalizedHooks.length > 0 ||
@@ -2141,7 +2182,7 @@ export class Server {
     }
     resolveNodeSource(source, platform, suppliedRuntime) {
         // Seal once on the Node-direct lane too - it can bypass `fetchSource` entirely (hookless outcome).
-        if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+        if (unsealedHookAudits !== 0 && process.env.NODE_ENV !== "production")
             sealHookAudit(this, this.catalog.size, this.wsRoutes.length, this.logger);
         // A paired header-only native hook can preserve the Node-direct JSON/body outcome for successful
         // responses. Arbitrary onResponse transforms need a real Web Response, but a buffered outcome can
@@ -2381,11 +2422,11 @@ export class Server {
         }
     }
     resolveWebSocketUpgrade(req, platform) {
-        // Before any header is read: Deno only materializes a request's headers when asked, and that
-        // costs a plain request measurably.
+        // Before any header is read, and then through `headerOf`: Deno builds a request's whole header
+        // list when `headers` is read, which costs every plain request of an app with sockets measurably.
         if (this.wsRoutes.length === 0 && !this.mountsTakeUpgrades())
             return WS_PASS;
-        if (req.headers.get("upgrade")?.toLowerCase() !== "websocket")
+        if (headerOf(req, "upgrade")?.toLowerCase() !== "websocket")
             return WS_PASS;
         // A WebSocket handshake is a GET (RFC 6455 section 4.1). Any other method with an Upgrade header
         // is an ordinary request: its HTTP route answers it, and normal routing refuses an unknown token.
@@ -2547,17 +2588,24 @@ export class Server {
             this.wsHookedPasses.set(received, request);
             return resolveWithDeadline(request);
         };
+        // The same boundary as an HTTP request's hooks; the answer is already wrapped, so it is not refused.
+        const failed = (err) => {
+            const answer = this.onRequestFailure(err, req, platform, this.finalizeResponse, this.wrapWebResponse);
+            return answer instanceof Promise
+                ? answer.then((response) => ({ kind: "reject", response }))
+                : { kind: "reject", response: answer };
+        };
         let hooked;
         try {
             hooked = this.runWebSocketRequestHooks(req, platform);
         }
-        catch {
-            return refuse(jsonError(500, "internal_error"));
+        catch (err) {
+            return failed(err);
         }
         if (!(hooked instanceof Promise)) {
             return hooked instanceof Response ? refuse(hooked) : resolveHooked(hooked);
         }
-        const pending = hooked.then((result) => (result instanceof Response ? refuse(result) : resolveHooked(result)), () => refuse(jsonError(500, "internal_error")));
+        const pending = hooked.then((result) => (result instanceof Response ? refuse(result) : resolveHooked(result)), failed);
         return bounded(Promise.resolve(pending).then((result) => result), onTimeout);
     }
     /** Bun `fetch` when WS routes exist: try a WS upgrade first, else run the normal HTTP lifecycle.
@@ -2632,24 +2680,36 @@ export class Server {
         const request = this.nodeRequestContextOf(source);
         for (let i = 0; i < hooks.length; i++) {
             const hook = hooks[i];
-            const outcome = hook(request, platform);
+            let outcome;
+            try {
+                outcome = hook(request, platform);
+            }
+            catch (err) {
+                return this.onRequestFailure(err, source, platform, finalize, wrapResponse);
+            }
             if (outcome instanceof Promise) {
-                return outcome.then((early) => this.continueNodeRequest(early, i + 1, request, source, platform, finalize, wrapResponse, onTimeout));
+                return outcome.then((early) => this.continueNodeRequest(early, i + 1, request, source, platform, finalize, wrapResponse, onTimeout), (err) => this.onRequestFailure(err, source, platform, finalize, wrapResponse));
             }
             if (outcome !== undefined)
-                return wrapResponse(outcome);
+                return earlyAnswer(outcome, wrapResponse);
         }
         return this.routeAndRun(source, platform, finalize, wrapResponse, onTimeout, false);
     }
     async continueNodeRequest(first, nextIndex, request, source, platform, finalize, wrapResponse, onTimeout) {
         if (first !== undefined)
-            return wrapResponse(first);
+            return earlyAnswer(first, wrapResponse);
         for (let i = nextIndex; i < this.onNodeRequestHooks.length; i++) {
             const hook = this.onNodeRequestHooks[i];
-            const outcome = hook(request, platform);
-            const early = outcome instanceof Promise ? await outcome : outcome;
+            let early;
+            try {
+                const outcome = hook(request, platform);
+                early = outcome instanceof Promise ? await outcome : outcome;
+            }
+            catch (err) {
+                return this.onRequestFailure(err, source, platform, finalize, wrapResponse);
+            }
             if (early !== undefined)
-                return wrapResponse(early);
+                return earlyAnswer(early, wrapResponse);
         }
         return this.routeAndRun(source, platform, finalize, wrapResponse, onTimeout, false);
     }
@@ -2674,9 +2734,15 @@ export class Server {
         let current = source;
         for (let i = 0; i < hooks.length; i++) {
             const seen = requestOf(current);
-            const outcome = hooks[i](seen, platform);
+            let outcome;
+            try {
+                outcome = hooks[i](seen, platform);
+            }
+            catch (err) {
+                return this.onRequestFailure(err, current, platform, finalize, wrapResponse);
+            }
             if (outcome instanceof Promise) {
-                return outcome.then((early) => this.continueOnRequest(early, i + 1, originalRequest, current, platform, finalize, wrapResponse, onTimeout, webFast));
+                return outcome.then((early) => this.continueOnRequest(early, i + 1, originalRequest, current, platform, finalize, wrapResponse, onTimeout, webFast), (err) => this.onRequestFailure(err, current, platform, finalize, wrapResponse));
             }
             if (outcome instanceof Request) {
                 if (outcome !== seen)
@@ -2687,7 +2753,7 @@ export class Server {
                 continue;
             }
             if (outcome !== undefined)
-                return wrapResponse(outcome);
+                return earlyAnswer(outcome, wrapResponse);
         }
         return this.routeAndRun(current, platform, finalize, wrapResponse, onTimeout, webFast);
     }
@@ -2707,13 +2773,18 @@ export class Server {
                     this.responseRequests.set(originalRequest, early);
             }
             else if (early !== undefined) {
-                return wrapResponse(early);
+                return earlyAnswer(early, wrapResponse);
             }
             if (index >= this.onRequestHooks.length)
                 break;
             seen = requestOf(current);
-            const outcome = this.onRequestHooks[index](seen, platform);
-            early = outcome instanceof Promise ? await outcome : outcome;
+            try {
+                const outcome = this.onRequestHooks[index](seen, platform);
+                early = outcome instanceof Promise ? await outcome : outcome;
+            }
+            catch (err) {
+                return this.onRequestFailure(err, current, platform, finalize, wrapResponse);
+            }
             index++;
         }
         return this.routeAndRun(current, platform, finalize, wrapResponse, onTimeout, webFast);
@@ -2928,14 +2999,14 @@ export class Server {
             if (method !== "GET" && method !== "HEAD")
                 markTransportCap(source, entry.bodyLimit);
         }
-        // An idempotency route runs its dedupe lane first; on a fresh key it delegates to the normal lanes
-        // (with the body buffered). All non-idempotent routes skip straight to the lanes - no added cost.
+        // An idempotency route meets its dedupe gate inside the program, so the gate runs after
+        // authentication and under the request deadline. Its lanes render a `Response`, which the gate
+        // stores. Non-idempotent routes skip straight to the lanes - no added cost.
         // The runtime is always present when a route resolved idempotency (enforced at registration).
         if (entry.idempotent !== undefined && this.idempotencyRuntime !== undefined) {
-            return this.idempotencyRuntime.run(entry.idempotent, requestOf(source), platform, entry, params, search, wrapResponse, {
-                maxBodyBytes: entry.bodyLimit ?? UNLIMITED_BODY_BYTES,
-                runLanes: (buffered, plat, ent, prm, srch) => this.runMatchedLanes(buffered, plat, ent, prm, srch, this.finalizeResponse, this.wrapWebResponse, this.webResponseTimeout, false),
-            });
+            return this.idempotencyRuntime
+                .run(source, platform, (prepared) => this.runMatchedLanes(prepared, platform, entry, params, search, this.finalizeResponse, this.wrapWebResponse, this.webResponseTimeout, false))
+                .then(wrapResponse);
         }
         return this.runMatchedLanes(source, platform, entry, params, search, finalize, wrapResponse, onTimeout, webFast);
     }
@@ -4026,7 +4097,7 @@ export class Server {
                 const handed = current;
                 return next.then((settled) => this.continueOnResponse(settled, i + 1, req, handed));
             }
-            current = next === current ? next : writableResponse(next, req);
+            current = next === current ? next : handedBackResponse(next, req);
         }
         return current;
     }
@@ -4086,11 +4157,11 @@ export class Server {
     }
     /** Async tail of {@link applyOnResponse}: runs the remaining hooks once one has gone async. */
     async continueOnResponse(response, nextIndex, req, handed) {
-        let current = response === handed ? response : writableResponse(response, req);
+        let current = response === handed ? response : handedBackResponse(response, req);
         for (let i = nextIndex; i < this.onResponseHooks.length; i++) {
             const next = this.onResponseHooks[i](current, req);
             const settled = next instanceof Promise ? await next : next;
-            current = settled === current ? settled : writableResponse(settled, req);
+            current = settled === current ? settled : handedBackResponse(settled, req);
         }
         return current;
     }
@@ -4172,28 +4243,57 @@ export class Server {
             this.logRequestError(err, ctx);
             return fallback === undefined ? wrapResponse(plainError(500, "internal_error")) : fallback();
         }
-        return this.runErrorHooks(entry, err, ctx, finalize, wrapResponse, fallback);
+        return this.runErrorHooks(entry.onError, entry.responseContract, err, ctx, finalize, wrapResponse, fallback);
+    }
+    /** An `onRequest` hook threw or rejected. No route has matched, so every `onError` the app holds
+     * answers it, with a route-less context; otherwise the logged default 500, as for a handler. */
+    onRequestFailure(err, source, platform, finalize, wrapResponse) {
+        if (err instanceof Response || isResponseResult(err))
+            return wrapResponse(err);
+        const ctx = new RequestContext(source, EMPTY_PARAMS, undefined, getNeverAbortSignal(), getUnboundedRequestBudget(), platform, this.maxBodyBytes, this.protoPoisoning);
+        if (this.onErrorHooks.length === 0) {
+            this.logRequestError(err, ctx);
+            return this.internalErrorResponse(wrapResponse);
+        }
+        Object.assign(ctx, this.decorations);
+        return this.runErrorHooks(this.onErrorHooks, undefined, err, ctx, finalize, wrapResponse);
     }
     /** The `onError` chain, split off {@link handleLifecycleError} so its `await` costs only the routes
-     * that registered a hook. A hook may return a custom response; otherwise the default 500 stands. */
-    async runErrorHooks(entry, err, ctx, finalize, wrapResponse, fallback) {
+     * that registered a hook. A hook may return a custom response; otherwise the default 500 stands.
+     * Never rejects: nothing outside it re-enters `onError`, so a hook that throws, or an answer that
+     * cannot be rendered, is logged and answered here. */
+    async runErrorHooks(hooks, contract, err, ctx, finalize, wrapResponse, fallback) {
         // Indexed for the same reason as the `beforeHandle` chain above: the iterator would outlive
         // the `await` and stay heap-allocated on both engines.
-        for (let i = 0; i < entry.onError.length; i++) {
-            const outcome = entry.onError[i](err, ctx);
-            const handled = outcome instanceof Promise ? await outcome : outcome;
+        for (let i = 0; i < hooks.length; i++) {
+            let handled;
+            try {
+                const outcome = hooks[i](err, ctx);
+                handled = outcome instanceof Promise ? await outcome : outcome;
+            }
+            catch (hookError) {
+                // A thrown Response or status() is the hook's answer, as from beforeHandle.
+                if (!(hookError instanceof Response) && !isResponseResult(hookError)) {
+                    this.logRequestError(err, ctx);
+                    this.logRequestError(hookError, ctx);
+                    return fallback === undefined
+                        ? wrapResponse(plainError(500, "internal_error"))
+                        : fallback();
+                }
+                handled = hookError;
+            }
             if (handled === undefined)
                 continue;
-            const contract = entry.responseContract;
-            if (contract === undefined || (handled !== ctx.jsonReply && !isResponseResult(handled)))
-                return finalize(handled, responseSet(ctx), ctx);
-            // Checked here, not through finishLifecycleContract: a throwing schema must not re-enter onError.
+            // Awaited so an asynchronous finalize's rejection lands in the catch too.
             try {
+                if (contract === undefined || (handled !== ctx.jsonReply && !isResponseResult(handled)))
+                    return await finalize(handled, responseSet(ctx), ctx);
+                // Checked here, not through finishLifecycleContract: a throwing schema must not re-enter onError.
                 const checked = await contract.runtime.check(contract.definition, handled, ctx);
-                return this.finishContractOutcome(ctx, finalize, wrapResponse, checked);
+                return await this.finishContractOutcome(ctx, finalize, wrapResponse, checked);
             }
-            catch (checkError) {
-                this.logRequestError(checkError, ctx);
+            catch (finishError) {
+                this.logRequestError(finishError, ctx);
                 return wrapResponse(plainError(500, "internal_error"));
             }
         }
@@ -4408,9 +4508,10 @@ export class Server {
         // Where Bun could pass a request down: the methods served natively on a path with a parameter,
         // as segment count + method. Two table paths match one request only at the same segment count.
         const below = new Set();
-        const tableAt = (path) => {
-            routes[path] ??= Object.create(null);
-            return routes[path];
+        const tableAt = (path, segments) => {
+            const key = bunTablePath(path, segments);
+            routes[key] ??= Object.create(null);
+            return routes[key];
         };
         for (let i = 0; i < all.length; i++) {
             const { method, path, pattern, entry } = all[i];
@@ -4422,14 +4523,14 @@ export class Server {
             // the platform the table shares could not answer `c.clientIp` there.
             if (run === undefined ||
                 entry.idempotent !== undefined ||
-                !METHODS.includes(method) ||
+                !BUN_TABLE_METHODS.includes(method) ||
                 (preflightOnFallback && method === "OPTIONS") ||
                 under.get(run)?.some((other) => outranks(other.pattern.segments, pattern.segments))) {
                 continue;
             }
             const paramNames = pattern.paramNames;
             const fused = mayUseFusedNative ? entry.execution.fusedWeb : undefined;
-            tableAt(path)[method] = this.compileBunNativeHandler(entry, paramNames, fused, unboundedSignal, unboundedBudget, peer, fallback);
+            tableAt(path, pattern.segments)[method] = this.compileBunNativeHandler(entry, paramNames, fused, unboundedSignal, unboundedBudget, peer, fallback);
             count += 1;
             if (paramNames.length > 0) {
                 below.add(pattern.segments.length + method);
@@ -4456,9 +4557,9 @@ export class Server {
             if (lead[i] === undefined)
                 continue;
             const { path, pattern } = all[i];
-            for (const method of METHODS) {
+            for (const method of BUN_TABLE_METHODS) {
                 if (below.has(pattern.segments.length + method))
-                    tableAt(path)[method] ??= fallback;
+                    tableAt(path, pattern.segments)[method] ??= fallback;
             }
         }
         return routes;
@@ -4555,6 +4656,8 @@ export class Server {
             [PLATFORM_PEER]: (request) => running.requestIP(request)?.address,
         };
         const nativeRoutes = wsHandlers === undefined ? this.buildBunNativeRoutes(fallback, peer) : undefined;
+        const sockets = new Set();
+        this.bunSockets = sockets;
         const running = (wsHandlers === undefined
             ? Bun.serve({
                 ...listening,
@@ -4572,9 +4675,18 @@ export class Server {
                     // closes an over-cap connection before the handler runs. Default 1 MB (maxBodyBytes). One
                     // limit per listener: the largest cap among this app and the apps mounted on it.
                     maxPayloadLength: wsHandlers.maxPayloadLength,
-                    open: (ws) => wsHandlers.open(ws),
+                    open: (ws) => {
+                        sockets.add(ws);
+                        wsHandlers.open(ws);
+                        // An upgrade accepted while `stop()` drains gets the close the earlier sockets got.
+                        if (this.bunServer !== running)
+                            ws.close(1001);
+                    },
                     message: (ws, message) => wsHandlers.message(ws, message),
-                    close: (ws, code, reason) => wsHandlers.close(ws, code, reason),
+                    close: (ws, code, reason) => {
+                        sockets.delete(ws);
+                        wsHandlers.close(ws, code, reason);
+                    },
                 },
             }));
         this.bunServer = running;
@@ -4602,18 +4714,30 @@ export class Server {
      * `stop()`'s promise drops in-flight requests), and decide graceful-vs-forced in
      * ONE call (Bun can't escalate an already-graceful `stop()` to a forced close).
      * New connections may be accepted during the drain window; in a real deploy the
-     * load balancer has already stopped routing here, and `drainMs` bounds it.
+     * load balancer has already stopped routing here, and `drainMs` bounds it. Open WebSockets
+     * get a 1001 close at once and the same window to finish it, before any `onStop` hook runs.
      */
     async stop({ drainMs = DEFAULT_DRAIN_MS } = {}) {
+        const onSignal = this.signalHandler;
+        if (onSignal !== undefined) {
+            this.signalHandler = undefined;
+            process.off("SIGTERM", onSignal).off("SIGINT", onSignal);
+        }
         const server = this.bunServer;
         if (server === undefined)
             return;
         this.bunServer = undefined;
+        const sockets = this.bunSockets;
+        this.bunSockets = undefined;
+        if (sockets !== undefined)
+            for (const ws of sockets)
+                ws.close(1001);
+        const busy = () => server.pendingRequests + (sockets?.size ?? 0) > 0;
         const deadline = Date.now() + drainMs;
-        while (server.pendingRequests > 0 && Date.now() < deadline) {
+        while (busy() && Date.now() < deadline) {
             await Bun.sleep(DRAIN_POLL_MS);
         }
-        server.stop(server.pendingRequests > 0); // force-close iff stragglers remain past the deadline
+        server.stop(busy()); // force-close iff stragglers remain past the deadline
         if (this.stopHooks.length === 0)
             return;
         const callbacks = this.stopHooks.map((hook) => Promise.resolve().then(hook));
@@ -4630,6 +4754,7 @@ export class Server {
         const onSignal = () => {
             void this.stop(drain);
         };
+        this.signalHandler = onSignal;
         process.once("SIGTERM", onSignal);
         process.once("SIGINT", onSignal);
     }