@nifrajs/node 4.0.0 → 5.0.0

package/dist/index.js

@@ -19,8 +19,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  * `Request`/`Response`, plus a Bun-`listen()`-style graceful `stop()`.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
-import { constants as FS } from "node:fs";
-import { open, realpath } from "node:fs/promises";
+import { realpath } from "node:fs/promises";
 import { createServer, STATUS_CODES, } from "node:http";
 import { createServer as createHttpsServer } from "node:https";
 import { extname, isAbsolute, relative, resolve, sep } from "node:path";
@@ -30,6 +29,7 @@ import { FastResponse } from "srvx/node";
 import { NODE_BRIDGE_MARKER_KEYS } from "./generated/bridge-markers.js";
 import { hasDotSegment, resolveDotSegments } from "./generated/request-target.js";
 import { claimableWebStream, claimNodeStream } from "./node-stream.js";
+import { openResolved } from "./open-resolved.js";
 const RESOLVE_NODE_MOUNT = Symbol.for(NODE_BRIDGE_MARKER_KEYS.resolveNodeMount);
 /**
  * The `Content-Type` the host runtime's `Response.json` emits - Node's undici uses `application/json`,
@@ -38,6 +38,15 @@ const RESOLVE_NODE_MOUNT = Symbol.for(NODE_BRIDGE_MARKER_KEYS.resolveNodeMount);
  */
 const JSON_CONTENT_TYPE = Response.json(0).headers.get("content-type") ?? "application/json";
 const INTERNAL_ERROR_BODY = '{"ok":false,"error":"internal_error"}';
+/** A handler's Response whose body was already sent: refused, since its headers were written for the
+ * request it already answered. */
+const SENT_BODY_OUTCOME = Object.freeze({
+    kind: "json",
+    status: 500,
+    headers: undefined,
+    cookies: undefined,
+    body: INTERNAL_ERROR_BODY,
+});
 const EMPTY_BUFFER = Buffer.alloc(0);
 const NODE_RESPONSE_BODY = Symbol.for(NODE_BRIDGE_MARKER_KEYS.responseBody);
 const RESPONSE_RESULT = Symbol.for(NODE_BRIDGE_MARKER_KEYS.responseResult);
@@ -82,14 +91,16 @@ const NODE_OUTCOME_RUNTIME = {
                 return {
                     kind: "body",
                     status: body.status,
-                    headers: appendCookiesToNodeHeaders(body.headers, set._cookies),
+                    headers: applySetToNodeHeaders(body.headers, body.status, set),
                     body: isBodylessStatus(body.status) ? new Uint8Array(0) : body.body,
                 };
             }
-            return nodeOutcomeFromResponse(appendCookiesToResponse(result.toResponse(), set._cookies));
+            return nodeOutcomeFromResponse(applySetToResponse(result.toResponse(), set));
         }
         if (result instanceof Response) {
-            return nodeOutcomeFromResponse(appendCookiesToResponse(result, set._cookies));
+            if (result.bodyUsed)
+                return SENT_BODY_OUTCOME;
+            return nodeOutcomeFromResponse(applySetToResponse(result, set));
         }
         const status = set.status ?? (result === undefined ? 204 : 200);
         const body = result === undefined || isBodylessStatus(status) ? null : JSON.stringify(result);
@@ -291,23 +302,65 @@ function installFastResponse() {
         return;
     globalThis.Response = DeferringResponse;
 }
-function appendCookiesToResponse(response, cookies) {
-    if (cookies === undefined || cookies.length === 0)
+/** Headers that describe a Response's body or its framing - core's list, mirrored here because the
+ * adapter does not import core: a `c.set` value for one describes a body the handler did not return. */
+const RESPONSE_OWNED_HEADERS = new Set([
+    "content-type",
+    "content-length",
+    "content-encoding",
+    "content-range",
+    "transfer-encoding",
+]);
+/**
+ * `response` with this request's `c.set` headers it lacks and its queued cookies - core's
+ * `applySetToResponse` and `writableResponse` rules, mirrored. A Response without a body can be sent
+ * any number of times, so the object a handler returns may answer other requests too and is always
+ * copied; one with a body can be sent once, so it is this request's and takes the writes in place
+ * unless its `Headers` are guarded (`Response.redirect()`, a raw `fetch()` result).
+ */
+function applySetToResponse(response, set) {
+    const ambient = response.status >= 200 ? set._headers : undefined;
+    const cookies = set._cookies ?? [];
+    const added = [];
+    if (ambient !== undefined) {
+        for (const name in ambient) {
+            if (RESPONSE_OWNED_HEADERS.has(name.toLowerCase()) || response.headers.has(name))
+                continue;
+            added.push([name, ambient[name]]);
+        }
+    }
+    if (added.length === 0 && cookies.length === 0)
         return response;
-    try {
+    const write = (target) => {
+        for (const [name, value] of added)
+            target.headers.set(name, value);
         for (const cookie of cookies)
-            response.headers.append("set-cookie", cookie);
-        return response;
+            target.headers.append("set-cookie", cookie);
+        return target;
+    };
+    if (response.body === null && response.status >= 200) {
+        return write(copiedResponse(response, new Response(null, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        })));
+    }
+    try {
+        return write(response);
     }
     catch {
-        // Guarded `Headers` (`Response.redirect()`, a raw `fetch()` result) reject every write, so the
-        // first append throws with nothing applied and the cookies land on a mutable copy instead.
-        const clone = new Response(response.body, response);
-        for (const cookie of cookies)
-            clone.headers.append("set-cookie", cookie);
-        return clone;
+        // Guarded `Headers` reject every write, so the first one throws with nothing applied and the
+        // writes land on a mutable copy instead.
+        return write(copiedResponse(response, new Response(response.body, response)));
     }
 }
+/** `copy` carrying `original`'s buffered-body marker, so the direct writer still sends those bytes. */
+function copiedResponse(original, copy) {
+    const body = Reflect.get(original, NODE_RESPONSE_BODY);
+    if (body !== undefined)
+        Object.defineProperty(copy, NODE_RESPONSE_BODY, { value: body });
+    return copy;
+}
 /** Early exits built outside the handler's finalizer - an `onRequest` hook's response, a mount's,
  * every framework error render. A plain-data carrier takes the `kind: "json"` lane a handler's plain
  * return takes, with no `Response` built and none drained; there is no `c.set` at these sites, which
@@ -408,12 +461,29 @@ function responseHeaders(response) {
     }
     return headers;
 }
-function appendCookiesToNodeHeaders(headers, cookies) {
+/** {@link applySetToResponse} for a body the direct writer sends from a header record. */
+function applySetToNodeHeaders(headers, status, set) {
+    const ambient = status >= 200 ? set._headers : undefined;
+    const cookies = set._cookies;
+    const copy = () => Object.assign(Object.create(null), headers);
+    let out;
+    if (ambient !== undefined) {
+        let own;
+        for (const name in ambient) {
+            const lower = name.toLowerCase();
+            if (RESPONSE_OWNED_HEADERS.has(lower))
+                continue;
+            own ??= new Set(headers === undefined ? [] : Object.keys(headers).map((key) => key.toLowerCase()));
+            if (own.has(lower))
+                continue;
+            own.add(lower);
+            out ??= copy();
+            out[name] = ambient[name];
+        }
+    }
     if (cookies === undefined || cookies.length === 0)
-        return headers;
-    const out = Object.create(null);
-    if (headers !== undefined)
-        Object.assign(out, headers);
+        return out ?? headers;
+    out ??= copy();
     const existing = out["set-cookie"];
     const setCookies = existing === undefined ? [] : typeof existing === "string" ? [existing] : [...existing];
     out["set-cookie"] = [...setCookies, ...cookies];
@@ -452,7 +522,8 @@ function normalizeHostAuthority(value) {
             hostname = value.slice(0, colon);
             port = value.slice(colon + 1);
         }
-        if (hostname.length === 0 || !/^[a-z0-9.-]+$/i.test(hostname))
+        // `_` is a legal reg-name character (RFC 3986) and common in container service names.
+        if (hostname.length === 0 || !/^[\w.-]+$/.test(hostname))
             return undefined;
         hostname = hostname.toLowerCase();
     }
@@ -567,6 +638,7 @@ function staticStateOf(options) {
         root,
         prefix,
         immutable: options.immutable !== false,
+        hashedFiles: options.hashedFiles === undefined ? undefined : new Set(options.hashedFiles),
         headers: staticHeadersOf(options.headers),
         denyDotfiles: options.dotfiles !== "allow",
     };
@@ -618,7 +690,8 @@ function staticMatch(state, rawUrl) {
     if (contained.startsWith("..") || isAbsolute(contained)) {
         return { reject: new Response("Forbidden", { status: 403 }) };
     }
-    return { file };
+    const immutable = state.immutable && (state.hashedFiles === undefined || state.hashedFiles.has(path));
+    return { file, immutable };
 }
 /** Strong validator from mtime + size (the nginx scheme): rewriting a file changes at least one. */
 function staticEtag(size, mtimeMs) {
@@ -693,7 +766,7 @@ function staticByteRange(headers, size, etag, lastModified) {
     const end = last === "" ? size - 1 : Math.min(Number(last), size - 1);
     return end < start ? undefined : [start, end];
 }
-async function readStatic(file, state, method, requestHeaders) {
+async function readStatic(file, immutable, state, method, requestHeaders) {
     let handle;
     try {
         // Defense-in-depth: the lexical `..` guard in staticMatch can't catch a symlink INSIDE root that
@@ -701,20 +774,20 @@ async function readStatic(file, state, method, requestHeaders) {
         // never open the requested path and re-resolve it afterwards. A local attacker who can write
         // inside the served tree wins that ordering: swap a link between the open and the lookup and the
         // descriptor already streaming refers to an external file while the lookup answers with a
-        // contained path. `O_NOFOLLOW` closes the remainder on the final component - `realpath` returned
-        // a name with no links left in it, so one appearing before the open is an attack, not a layout.
+        // contained path. openResolved closes the remainder - `realpath` returned a name with no links
+        // left in it, so one appearing in any component before the open is an attack, not a layout.
         const [realFile, realRoot] = await Promise.all([realpath(file), realpath(state.root)]);
         if (realFile !== realRoot && !realFile.startsWith(realRoot + sep)) {
             return { kind: "response", response: new Response("Forbidden", { status: 403 }) };
         }
-        handle = await open(realFile, FS.O_RDONLY | FS.O_NOFOLLOW);
+        handle = await openResolved(realFile);
         const stat = await handle.stat();
         if (!stat.isFile()) {
             await handle.close();
             return { kind: "response", response: new Response("Not Found", { status: 404 }) };
         }
         const headers = { ...state.headers };
-        if (state.immutable && headers["cache-control"] === undefined) {
+        if (immutable && headers["cache-control"] === undefined) {
             headers["cache-control"] = "public, max-age=31536000, immutable";
         }
         headers.etag ??= staticEtag(stat.size, stat.mtimeMs);
@@ -785,6 +858,13 @@ async function readStatic(file, state, method, requestHeaders) {
 // @nifrajs/core, and no-op on a handler that does not expose the seam (a plain `{ fetch }`) or one that
 // is already frozen (the per-request `resolveNodeSource` path supplies the runtime regardless).
 const INSTALL_NODE_DIRECT = Symbol.for("@nifrajs/core/install-node-direct");
+// A nifra server logs what an adapter reports through this seam, as Bun's `listen()` does; a plain
+// `{ fetch }` handler has no logger, so its failures stay a bare 500.
+const REPORT_ERROR = Symbol.for("@nifrajs/core/report-error");
+function errorReporterOf(app) {
+    const report = Reflect.get(app, REPORT_ERROR);
+    return typeof report === "function" ? (error) => report.call(app, error) : undefined;
+}
 function enableNodeDirect(app) {
     const install = app[INSTALL_NODE_DIRECT];
     if (typeof install !== "function")
@@ -837,6 +917,7 @@ function clearActiveResponseState() {
 export function serve(app, options) {
     activateAsyncContextFrame();
     enableNodeDirect(app);
+    const report = errorReporterOf(app);
     if (options.fastResponse === true)
         installFastResponse();
     let inFlight = 0;
@@ -844,6 +925,15 @@ export function serve(app, options) {
     // Upgrade sockets an HTTP route answers instead: Node's server no longer tracks them, so stop()
     // drains and closes them itself.
     const answering = new Set();
+    // Upgraded WebSockets: Node's server stops tracking a socket once `ws` takes it over.
+    const upgraded = new Set();
+    const adopt = (ws) => {
+        if (closed)
+            return false;
+        upgraded.add(ws);
+        ws.on("close", () => upgraded.delete(ws));
+        return true;
+    };
     const protocol = protocolResolver(options.protocol ?? (options.tls === undefined ? undefined : "https"));
     const hostPolicy = hostPolicyOf(options);
     const staticState = options.static !== undefined ? staticStateOf(options.static) : undefined;
@@ -855,7 +945,7 @@ export function serve(app, options) {
         const socket = nodeReq.socket;
         let responseState = socket[ACTIVE_SOCKET_STATE];
         if (responseState === undefined) {
-            responseState = { socket, active: 0, parserError: false };
+            responseState = { socket, active: 0, parserError: false, report };
             socket[ACTIVE_SOCKET_STATE] = responseState;
             socket.once("close", clearActiveResponseState);
         }
@@ -870,10 +960,11 @@ export function serve(app, options) {
             if (handled instanceof Promise) {
                 // `catch` before `finally`: a `finally` alone forwards the rejection to a promise nothing
                 // observes, and Node terminates the process on an unhandled rejection by default. Every
-                // writer already ends its own failures (`failWrite`), so anything arriving here is a fault
-                // no response can still be built from - the connection is the only thing left to end.
+                // writer already ends and reports its own failures (`failAndReport`), so anything arriving
+                // here is a fault no response can still be built from - the connection is the only thing
+                // left to end.
                 void handled
-                    .catch(() => failWrite(nodeRes))
+                    .catch((error) => failAndReport(nodeRes, error))
                     .finally(() => {
                     inFlight -= 1;
                 });
@@ -881,8 +972,8 @@ export function serve(app, options) {
             }
             inFlight -= 1;
         }
-        catch {
-            failWrite(nodeRes);
+        catch (error) {
+            failAndReport(nodeRes, error);
             inFlight -= 1;
         }
     };
@@ -910,36 +1001,48 @@ export function serve(app, options) {
     // the optional `ws` package - lazy-imported (and the server lazily built) on the FIRST real WS
     // upgrade, so a non-WS Node app never loads `ws`.
     if (resolveWs !== undefined) {
-        let wssPromise;
+        // One `ws` server per payload cap: its `maxPayload` bounds buffering before a frame is delivered,
+        // and mounted children can declare different caps.
+        const servers = new Map();
         server.on("upgrade", (nodeReq, socket, head) => {
-            void handleUpgrade(app, answering, resolveWs, protocol, hostPolicy, nodeReq, socket, head, (maxPayloadBytes) => {
-                wssPromise ??= loadWsServer(maxPayloadBytes);
-                return wssPromise;
+            void handleUpgrade(app, answering, adopt, resolveWs, protocol, hostPolicy, nodeReq, socket, head, (maxPayloadBytes) => {
+                let wss = servers.get(maxPayloadBytes);
+                if (wss === undefined) {
+                    wss = loadWsServer(maxPayloadBytes);
+                    servers.set(maxPayloadBytes, wss);
+                }
+                return wss;
             });
         });
     }
     // Opt-in: own SIGTERM/SIGINT so `docker stop` / Ctrl-C drains in-flight requests
     // before exit. `stop` is hoisted, so `onSignal` can reference it.
+    const signals = options.signals === true ? {} : options.signals || undefined;
     const onSignal = () => {
-        void stop();
+        void stop(signals);
     };
     async function stop({ drainMs = DEFAULT_DRAIN_MS } = {}) {
         if (closed)
             return; // idempotent
         closed = true;
-        if (options.signals === true) {
+        if (signals !== undefined) {
             // Remove our own handlers so repeated serve()/stop() cycles don't leak listeners.
             process.removeListener("SIGTERM", onSignal);
             process.removeListener("SIGINT", onSignal);
         }
         server.close(); // stop accepting new connections; existing requests continue
+        // A WebSocket gets a close handshake now and the drain window to finish it.
+        for (const ws of upgraded)
+            ws.close(1001, "server shutting down");
         const deadline = Date.now() + drainMs;
-        while ((inFlight > 0 || answering.size > 0) && Date.now() < deadline) {
+        while ((inFlight > 0 || answering.size > 0 || upgraded.size > 0) && Date.now() < deadline) {
             await new Promise((r) => setTimeout(r, DRAIN_POLL_MS));
         }
         server.closeAllConnections(); // force-close stragglers + idle keep-alive sockets
         for (const socket of answering)
             socket.destroy();
+        for (const ws of upgraded)
+            ws.terminate();
     }
     return new Promise((resolve) => {
         // Do not pass an explicit `undefined` hostname. Node accepts it, but Bun's Node-compatible
@@ -948,7 +1051,7 @@ export function serve(app, options) {
         const onListening = () => {
             const address = server.address();
             const port = address !== null && typeof address === "object" ? address.port : options.port;
-            if (options.signals === true) {
+            if (signals !== undefined) {
                 process.once("SIGTERM", onSignal);
                 process.once("SIGINT", onSignal);
             }
@@ -969,11 +1072,11 @@ function runNodeSource(app, source, nodeReq, nodeRes, protocol, host, platform)
         try {
             const outcome = resolveNodeSource.call(app, source, platform, NODE_OUTCOME_RUNTIME);
             return outcome instanceof Promise
-                ? outcome.then((settled) => writeOutcomeSafely(settled, nodeRes, nodeReq.method), () => failWrite(nodeRes))
+                ? outcome.then((settled) => writeOutcomeSafely(settled, nodeRes, nodeReq.method), (error) => failAndReport(nodeRes, error))
                 : writeOutcomeSafely(outcome, nodeRes, nodeReq.method);
         }
-        catch {
-            failWrite(nodeRes);
+        catch (error) {
+            failAndReport(nodeRes, error);
             return;
         }
     }
@@ -983,23 +1086,23 @@ function runNodeSource(app, source, nodeReq, nodeRes, protocol, host, platform)
         try {
             const outcome = resolveNode.call(app, request, platform);
             return outcome instanceof Promise
-                ? outcome.then((settled) => writeOutcomeSafely(settled, nodeRes, nodeReq.method), () => failWrite(nodeRes))
+                ? outcome.then((settled) => writeOutcomeSafely(settled, nodeRes, nodeReq.method), (error) => failAndReport(nodeRes, error))
                 : writeOutcomeSafely(outcome, nodeRes, nodeReq.method);
         }
-        catch {
-            failWrite(nodeRes);
+        catch (error) {
+            failAndReport(nodeRes, error);
             return;
         }
     }
     try {
         const response = app.fetch(request, platform);
         return response instanceof Promise
-            ? response.then((settled) => writeResponseSafely(settled, nodeRes, nodeReq.method), () => failWrite(nodeRes))
+            ? response.then((settled) => writeResponseSafely(settled, nodeRes, nodeReq.method), (error) => failAndReport(nodeRes, error))
             : writeResponseSafely(response, nodeRes, nodeReq.method);
     }
-    catch {
-        // The app should never throw (nifra returns a 500), but never leak a stack to the wire.
-        failWrite(nodeRes);
+    catch (error) {
+        // A request hook that throws escapes `fetch`; never leak a stack to the wire.
+        failAndReport(nodeRes, error);
         return;
     }
 }
@@ -1063,7 +1166,7 @@ function handle(app, nodeReq, nodeRes, getProtocol, staticState, hostPolicy) {
         if (matched !== "pass") {
             if ("reject" in matched)
                 return writeResponseSafely(matched.reject, nodeRes, nodeReq.method);
-            return readStatic(matched.file, staticState, nodeReq.method ?? "GET", nodeReq.headers).then((outcome) => writeOutcomeSafely(outcome, nodeRes, nodeReq.method), () => failWrite(nodeRes));
+            return readStatic(matched.file, matched.immutable, staticState, nodeReq.method ?? "GET", nodeReq.headers).then((outcome) => writeOutcomeSafely(outcome, nodeRes, nodeReq.method), () => failWrite(nodeRes));
         }
     }
     // A mounted handler may advertise a native Node lane. Core has already checked route precedence
@@ -1097,13 +1200,13 @@ function handle(app, nodeReq, nodeRes, getProtocol, staticState, hostPolicy) {
                     if (outcome instanceof Promise) {
                         return outcome.then((handled) => handled === false
                             ? runNodeSource(app, nodeSource, nodeReq, nodeRes, protocol, host, platform)
-                            : undefined, () => failWrite(nodeRes));
+                            : undefined, (error) => failAndReport(nodeRes, error));
                     }
                     if (outcome !== false)
                         return;
                 }
-                catch {
-                    failWrite(nodeRes);
+                catch (error) {
+                    failAndReport(nodeRes, error);
                     return;
                 }
             }
@@ -1116,23 +1219,23 @@ function handle(app, nodeReq, nodeRes, getProtocol, staticState, hostPolicy) {
         try {
             const outcome = resolveNode.call(app, request, platform);
             return outcome instanceof Promise
-                ? outcome.then((settled) => writeOutcomeSafely(settled, nodeRes, nodeReq.method), () => failWrite(nodeRes))
+                ? outcome.then((settled) => writeOutcomeSafely(settled, nodeRes, nodeReq.method), (error) => failAndReport(nodeRes, error))
                 : writeOutcomeSafely(outcome, nodeRes, nodeReq.method);
         }
-        catch {
-            failWrite(nodeRes);
+        catch (error) {
+            failAndReport(nodeRes, error);
             return;
         }
     }
     try {
         const response = app.fetch(request, platform);
         return response instanceof Promise
-            ? response.then((settled) => writeResponseSafely(settled, nodeRes, nodeReq.method), () => failWrite(nodeRes))
+            ? response.then((settled) => writeResponseSafely(settled, nodeRes, nodeReq.method), (error) => failAndReport(nodeRes, error))
             : writeResponseSafely(response, nodeRes, nodeReq.method);
     }
-    catch {
-        // The app should never throw (nifra returns a 500), but never leak a stack to the wire.
-        failWrite(nodeRes);
+    catch (error) {
+        // A request hook that throws escapes `fetch`; never leak a stack to the wire.
+        failAndReport(nodeRes, error);
         return;
     }
 }
@@ -1169,6 +1272,10 @@ function writeInternalError(nodeRes) {
 function failWrite(nodeRes) {
     try {
         if (!nodeRes.headersSent) {
+            // The failed write may have staged the response's own headers (cookies among them) with
+            // `setHeaders`; the 500 must not carry them.
+            for (const name of nodeRes.getHeaderNames())
+                nodeRes.removeHeader(name);
             writeInternalError(nodeRes);
             return;
         }
@@ -1178,26 +1285,43 @@ function failWrite(nodeRes) {
     }
     nodeRes.destroy();
 }
-/** {@link writeNodeOutcome} with {@link failWrite} behind it, sync throw and async rejection alike. */
+/** {@link failWrite} for a failure the app never answered, logged through the app's own logger. */
+function failAndReport(nodeRes, error) {
+    const state = Reflect.get(nodeRes, ACTIVE_RESPONSE_STATE);
+    const report = state?.report;
+    try {
+        report?.(error);
+    }
+    catch {
+        // A logger that throws must not keep the 500 from going out.
+    }
+    failWrite(nodeRes);
+}
+/** {@link writeNodeOutcome} with {@link failAndReport} behind it, sync throw and async rejection
+ * alike. */
 function writeOutcomeSafely(outcome, nodeRes, method) {
     try {
         const written = writeNodeOutcome(outcome, nodeRes, method);
-        return written instanceof Promise ? written.catch(() => failWrite(nodeRes)) : written;
+        return written instanceof Promise
+            ? written.catch((error) => failAndReport(nodeRes, error))
+            : written;
     }
-    catch {
-        failWrite(nodeRes);
+    catch (error) {
+        failAndReport(nodeRes, error);
         return;
     }
 }
-/** {@link writeNodeResponse} with {@link failWrite} behind it - same contract as
+/** {@link writeNodeResponse} with {@link failAndReport} behind it - same contract as
  * {@link writeOutcomeSafely}, for the lanes that carry a `Response`. */
 function writeResponseSafely(response, nodeRes, method) {
     try {
         const written = writeNodeResponse(response, nodeRes, method);
-        return written instanceof Promise ? written.catch(() => failWrite(nodeRes)) : written;
+        return written instanceof Promise
+            ? written.catch((error) => failAndReport(nodeRes, error))
+            : written;
     }
-    catch {
-        failWrite(nodeRes);
+    catch (error) {
+        failAndReport(nodeRes, error);
         return;
     }
 }
@@ -1896,6 +2020,9 @@ function waitForDrain(nodeRes) {
     });
 }
 function writeNodeResponse(response, nodeRes, method) {
+    // A body already sent once answered another request, with headers written for that one.
+    if (response.bodyUsed)
+        throw new TypeError("[nifra] a Response body can be sent only once");
     const isHead = method?.toUpperCase() === "HEAD";
     // `ServerResponse.setHeaders` (Node 18.14+) takes the Headers object directly and iterates its
     // native Symbol.iterator, which - unlike `Headers.forEach`/`.get()` - never comma-joins repeated
@@ -2123,11 +2250,13 @@ async function loadWsServer(maxPayloadBytes) {
     try {
         const mod = (await import(__rewriteRelativeImportExtension(WS_MODULE_SPECIFIER)));
         const Ctor = mod.WebSocketServer ?? mod.default?.WebSocketServer;
+        // `ws` reads `maxPayload: 0` as no limit, so a cap of 0 buffers at most a byte and the message
+        // check in `attachNodeWebSocket` refuses anything but an empty frame.
         return Ctor === undefined
             ? undefined
             : new Ctor(maxPayloadBytes === undefined
                 ? { noServer: true }
-                : { noServer: true, maxPayload: maxPayloadBytes });
+                : { noServer: true, maxPayload: Math.max(maxPayloadBytes, 1) });
     }
     catch {
         return undefined; // `ws` not installed - caller responds 501
@@ -2144,7 +2273,7 @@ const WS_STATUS_TEXT = {
 };
 /** Resolve a Node `upgrade` event: run the nifra upgrade guard, then either reject (write an HTTP error
  * to the raw socket) or perform the `ws` upgrade and wire the socket to the handler. */
-async function handleUpgrade(app, answering, resolveWs, getProtocol, hostPolicy, nodeReq, socket, head, getWss) {
+async function handleUpgrade(app, answering, adopt, resolveWs, getProtocol, hostPolicy, nodeReq, socket, head, getWss) {
     // A peer can reset the socket while the guard is awaited; with no listener that error ends the process.
     socket.on("error", ignoreSocketError);
     resolveTarget(nodeReq);
@@ -2201,13 +2330,20 @@ async function handleUpgrade(app, answering, resolveWs, getProtocol, hostPolicy,
         writeUpgradeRejection(socket, 501, "websocket_unavailable"); // `ws` not installed
         return;
     }
-    const { handler, data, pubsub } = outcome;
-    wss.handleUpgrade(nodeReq, socket, head, (ws) => attachNodeWebSocket(ws, handler, data, pubsub));
+    const { handler, data, pubsub, maxPayloadBytes } = outcome;
+    wss.handleUpgrade(nodeReq, socket, head, (ws) => {
+        // An upgrade still resolving when stop() ran must not outlive it.
+        if (!adopt(ws)) {
+            ws.terminate();
+            return;
+        }
+        attachNodeWebSocket(ws, handler, data, pubsub, maxPayloadBytes);
+    });
 }
 /** Wire a `ws` socket (already open in `handleUpgrade`'s callback) to a nifra WS handler. The Node copy
  * of core's `attachWebSocket` - binary frames normalize to `Uint8Array`; a thrown/rejected callback
  * routes to `error()` and never crashes the connection. */
-function attachNodeWebSocket(ws, handler, data, pubsub) {
+function attachNodeWebSocket(ws, handler, data, pubsub, maxPayloadBytes) {
     const nifra = {
         send: (payload) => ws.send(payload),
         close: (code, reason) => ws.close(code, reason),
@@ -2242,6 +2378,10 @@ function attachNodeWebSocket(ws, handler, data, pubsub) {
         }
     };
     ws.on("message", (raw, isBinary) => {
+        if (maxPayloadBytes !== undefined && raw.byteLength > maxPayloadBytes) {
+            ws.close(1009, "message too large");
+            return;
+        }
         const payload = isBinary
             ? new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength)
             : raw.toString();