@nifrajs/core 5.0.0 → 5.2.0

package/dist/server/server.js

@@ -1,10 +1,10 @@
 import { admitDeadline, createRequestBudget, createUnboundedRequestBudget, NIFRA_DEADLINE_HEADER, } from "../budget.js";
 import { FrameworkError, RouteConfigError } from "../errors.js";
 import { DEFAULT_CAPABILITY_INTERCEPTOR_TIMEOUT_MS, } from "../internal/capability-runtime.js";
-import { adoptStaticTags, enterPlugin, leavePlugin, tagAdoption, tagHook, tagScoped, tagStatic, } from "../internal/hook-origins.js";
-import { assuranceDeclarationsOf, assuranceEvidenceFor, } from "../internal/route-assurance.js";
+import { adoptStaticTags, enterPlugin, leavePlugin, tagAdoption, tagHook, tagMergeAuthGap, tagRouteSite, tagScoped, tagStatic, } from "../internal/hook-origins.js";
+import { assuranceDeclarationsOf, assuranceEvidenceFor, NIFRA_ASSURANCE_IDS, } from "../internal/route-assurance.js";
 import { RouteCatalog } from "../internal/route-catalog.js";
-import { compileRouteOptions } from "../internal/route-compiler.js";
+import { adoptRouteRuntimes, compileRouteOptions } from "../internal/route-compiler.js";
 import { compileRouteExecutionPlan, } from "../internal/route-execution.js";
 import { compileRouteProgram, executeRouteProgram } from "../internal/route-program.js";
 import { isSameOriginRequest } from "../internal/same-origin.js";
@@ -13,9 +13,9 @@ 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";
 import { NIFRA_PLATFORM_CLIENT_IP_DERIVED, resolveClientIp, } from "./client-ip.js";
-import "./core-copies.js";
+import { mergeRefusal, recordCopyVersion } from "./core-copies.js";
 import { hasLowercaseHeaderKeysMark, headerKeysAllLowercase, markLowercaseHeaderKeys, } from "./header-case.js";
-import { headerObjectOf } from "./headers.js";
+import { declaredHeaders, headerObjectOf } from "./headers.js";
 import { isRoutableMethod, jsonError, pathnameOf, plainError, urlPartsOf, } from "./http.js";
 import { withStaticNodeHeaders } from "./node-outcome.js";
 import { queryObjectOf, searchOf } from "./query.js";
@@ -285,6 +285,7 @@ const RESPONSE_TIMEOUT = () => jsonError(503, "request_timeout");
 // node-compat `process`, so `typeof process` does NOT gate it out there, yet reading `process.env`
 // throws `NotCapable` without `--allow-env`. The flag short-circuits before the env read on Deno (audit
 // off) while a production define still folds `<flag> && false` to `false` on every other runtime.
+// It must live in this module: imported from another, Bun leaves `<flag>,` at every folded guard.
 const hookAuditRuntime = typeof globalThis.Deno === "undefined";
 // This module's own path, captured once from a sentinel stack. Every internal frame of an
 // order-scoped hook push (the public method, its `use()`-bundle dispatcher, the recorder) lives here,
@@ -293,9 +294,10 @@ const SERVER_MODULE_PATH = /* @__PURE__ */ (() => {
     const frame = new Error().stack?.split("\n")[1];
     return frame?.match(/\(?([^()\s]+):\d+:\d+\)?\s*$/)?.[1];
 })();
-/** One `file:line:col` frame for the caller of an order-scoped hook method, for the unused-hook
- * report. Only ever called behind the `unusedScopedHooks !== "off"` guard, so the `Error` (the sole
- * non-trivial cost) is never constructed when the check is disabled. */
+/** One `file:line:col` frame for the caller of an order-scoped hook method or a route registration,
+ * for the unused-hook report and route provenance. Only ever called behind a development guard that
+ * also requires the feature to be on, so the `Error` (the sole non-trivial cost) is never constructed
+ * otherwise. */
 const captureCallerSite = () => {
     const stack = new Error().stack;
     if (stack === undefined)
@@ -328,7 +330,14 @@ 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) => {
-    hookAudit.set(key, { policy, hasCustomLogger, sites: [], checked: false });
+    hookAudit.set(key, {
+        policy,
+        hasCustomLogger,
+        sites: [],
+        lateInstalls: [],
+        merged: 0,
+        checked: false,
+    });
 };
 /** Record one order-scoped hook push: the route count at that moment (so `routesAtPush === total` at
  * seal means no route was declared after it) and the caller's frame. Hooks a WebSocket handshake runs
@@ -342,7 +351,52 @@ const recordScopedHook = (key, routesAtPush, kind) => {
     const state = hookAudit.get(key);
     if (state === undefined || state.policy === "off")
         return;
-    state.sites.push({ kind, routesAtPush, site: captureCallerSite() });
+    state.sites.push({
+        kind,
+        routesAtPush: routesAtPush - state.merged,
+        mergedAtPush: state.merged,
+        site: captureCallerSite(),
+    });
+};
+/** Count routes a `merge()` adopted: they never run this server's order-scoped hooks, so a hook
+ * followed only by merges covers nothing. */
+const noteMergedRoutes = (key, count) => {
+    const state = hookAudit.get(key);
+    if (state !== undefined)
+        state.merged += count;
+};
+/** Record a `merge()` whose server authenticates none of its routes while this server's order-scoped
+ * auth - `authenticate()` stages, or `authenticated` evidence scoped to subsequent routes - would
+ * cover some of them. A server that authenticates any of its own routes chose its own auth, so its
+ * unauthenticated routes are taken as public on purpose. `nifra check` reports what this records. */
+const noteMergeAuthGap = (target, authStages, active, routes, sourceGlobal) => {
+    const parentAuth = active.filter((item) => item.id === NIFRA_ASSURANCE_IDS.AUTHENTICATED);
+    if (authStages.length === 0 && parentAuth.length === 0)
+        return;
+    const authenticates = (route) => route.assurance.some((item) => item.id === NIFRA_ASSURANCE_IDS.AUTHENTICATED) ||
+        assuranceEvidenceFor(sourceGlobal, route.method, route.path).some((item) => item.id === NIFRA_ASSURANCE_IDS.AUTHENTICATED);
+    if (routes.some(authenticates))
+        return;
+    const covered = routes.filter((route) => authStages.length > 0 ||
+        assuranceEvidenceFor(parentAuth, route.method, route.path).length > 0);
+    if (covered.length === 0)
+        return;
+    tagMergeAuthGap(target, {
+        site: captureCallerSite(),
+        auth: [
+            ...authStages.map((stage) => `authenticate(${stage.id})`),
+            ...new Set(parentAuth.map((item) => item.source)),
+        ],
+        routes: covered.map((route) => `${route.method} ${route.path}`),
+    });
+};
+/** Record a registration-time plugin (`responseContract()`, `effectLedger()`) installed after routes
+ * it would have covered, named as `METHOD /path`. Reported with the dead hooks at seal. */
+const recordLateInstall = (key, plugin, routes) => {
+    const state = hookAudit.get(key);
+    if (state === undefined || state.policy === "off" || routes.length === 0)
+        return;
+    state.lateInstalls.push({ plugin, site: captureCallerSite(), routes });
 };
 /** Hook provenance for an adoption (dev only, see `internal/hook-origins.ts`): which scope each
  * wrapper just appended to a hook list gates its hook by. `pairs` holds each source list with the target list it
@@ -368,17 +422,37 @@ const sealHookAudit = (key, total, sockets, logger) => {
     state.checked = true;
     if (state.policy === "off" || total + sockets === 0)
         return;
+    const own = total - state.merged;
     const dead = state.sites.filter((hook) => hook.routesAtPush ===
         (hook.kind === "around" || hook.kind === "aroundCapability" || hook.kind === "afterHandle"
-            ? total
-            : total + sockets));
-    if (dead.length === 0)
+            ? own
+            : own + sockets));
+    const parts = [];
+    if (dead.length > 0) {
+        const mergedAfter = (hook) => state.merged > hook.mergedAtPush;
+        const detail = dead
+            .map((hook) => `  ${hook.kind}()  at ${hook.site ?? "<unknown>"}${mergedAfter(hook) ? "  (only merge()d routes follow it)" : ""}`)
+            .join("\n");
+        parts.push(`[nifra] ${dead.length} order-scoped hook(s) apply to no route - they were added after the ` +
+            `last route was registered, and register() snapshots the chain into each route as it is ` +
+            `declared:\n${detail}\nMove them before the routes they should cover. App-global hooks ` +
+            `(onRequest/onResponse) are not order-scoped and can be added at any time.` +
+            (dead.some(mergedAfter)
+                ? " A merge()d route keeps the hooks of the server that declared it and never runs this " +
+                    "server's: wire the hook on the merged server, or declare those routes in a group()."
+                : ""));
+    }
+    for (const late of state.lateInstalls) {
+        const shown = late.routes.slice(0, 5).join(", ");
+        const more = late.routes.length > 5 ? ` and ${late.routes.length - 5} more` : "";
+        parts.push(`[nifra] ${late.plugin}() at ${late.site ?? "<unknown>"} was installed after ` +
+            `${late.routes.length} route(s) it would have covered: ${shown}${more}. It is decided per ` +
+            `route at registration and merge(), so those routes run without it. Install it before the ` +
+            `routes and merge() calls it should cover.`);
+    }
+    if (parts.length === 0)
         return;
-    const detail = dead.map((hook) => `  ${hook.kind}()  at ${hook.site ?? "<unknown>"}`).join("\n");
-    const message = `[nifra] ${dead.length} order-scoped hook(s) apply to no route - they were added after the ` +
-        `last route was registered, and register() snapshots the chain into each route as it is ` +
-        `declared:\n${detail}\nMove them before the routes they should cover. App-global hooks ` +
-        `(onRequest/onResponse) are not order-scoped and can be added at any time.`;
+    const message = parts.join("\n");
     if (state.policy === "error")
         throw new FrameworkError("UNUSED_SCOPED_HOOKS", message);
     if (state.hasCustomLogger)
@@ -419,6 +493,7 @@ export class Server {
     nativePublish;
     maxBodyBytes;
     protoPoisoning;
+    formOrigins;
     /** `trustBodyFraming`: mark every `app.fetch` request as runtime-framed (see ServerOptions). */
     trustBodyFraming;
     wsMaxPayloadBytes;
@@ -543,6 +618,7 @@ export class Server {
         const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
         assertByteLimit(maxBodyBytes, "maxBodyBytes");
         this.protoPoisoning = options.protoPoisoning ?? "reject";
+        this.formOrigins = options.formOrigins;
         this.trustBodyFraming = options.trustBodyFraming ?? false;
         const wsMaxPayloadBytes = options.wsMaxPayloadBytes ?? maxBodyBytes;
         assertByteLimit(wsMaxPayloadBytes, "wsMaxPayloadBytes");
@@ -598,6 +674,7 @@ export class Server {
         // for the bundler to eliminate; a non-bundled production run skips it the same way.
         if (hookAuditRuntime && process.env.NODE_ENV !== "production") {
             beginHookAudit(this, options.unusedScopedHooks ?? "warn", options.logger !== undefined);
+            recordCopyVersion();
         }
         this.derives = [];
         this.authStages = [];
@@ -648,6 +725,10 @@ export class Server {
      * Mount a legacy fetch handler under a literal path prefix. Mounted handlers sit behind typed
      * routes, so routes can move one at a time while the remaining legacy surface stays live.
      * Mounted responses are outside Nifra's typed route and response-contract checks.
+     *
+     * It carries HTTP only: a WebSocket upgrade under the prefix reaches the handler as an ordinary
+     * request and never becomes a socket. Serve that path's sockets with `app.ws()` routes or a
+     * mounted child app, or keep the legacy server running beside this one for them.
      */
     mountFetch(path, handler, options = {}) {
         this.assertConfigurable("mountFetch()");
@@ -763,6 +844,11 @@ export class Server {
      * Unlike `derive`, this stage receives a body-blind authentication capsule and is compiled before
      * route validation. Keeping it separate prevents an unrelated derive from accidentally becoming a
      * security gate and lets the route compiler retain a protected fast lane.
+     *
+     * A stage that throws, or returns anything but `authenticated(principal)` or `rejected(...)`, fails
+     * closed with 503 `{ ok: false, error: "auth_unavailable" }`. The cause goes where a handler's error
+     * goes: to `onError`, whose response replaces the 503, and when no hook answers, to the logger. A
+     * thrown `Response` or `status(...)` is sent as thrown, as it is from a handler.
      */
     authenticate(stage) {
         this.assertConfigurable("authenticate()");
@@ -779,8 +865,10 @@ export class Server {
             throw new TypeError('authenticate() stage mode must be "sync" or "async"');
         }
         this.authStages.push(stage);
-        if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+        if (hookAuditRuntime && process.env.NODE_ENV !== "production") {
+            recordScopedHook(this, this.catalog.size + this.wsRoutes.length, "authenticate");
             tagHook(stage, "authenticate", this);
+        }
         return this;
     }
     decorate(key, value) {
@@ -877,9 +965,10 @@ export class Server {
         }
         return this;
     }
-    /** Handle a thrown error; a non-`undefined` return becomes the response (else the default 500).
-     * Order-scoped: captured by routes declared *after* this call, none before; one added after the last
-     * route reaches nothing (see {@link ServerOptions.unusedScopedHooks}). */
+    /** 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}). */
     onError(fn) {
         this.assertConfigurable("onError()");
         this.onErrorHooks.push(fn);
@@ -1311,6 +1400,15 @@ export class Server {
         throw new RouteConfigError("INVALID_PATH", `group(${JSON.stringify(prefix)}) route path must start with "/": ${JSON.stringify(path)}`);
     }
     prepareRoute(method, path, schema, handler) {
+        // Route provenance for the CLI's capability walk, which sets NIFRA_ROUTE_SITES while it loads the
+        // app: the module that registered the route, read where a static scan cannot see the path.
+        if (hookAuditRuntime &&
+            process.env.NODE_ENV !== "production" &&
+            process.env.NIFRA_ROUTE_SITES === "1") {
+            const site = captureCallerSite();
+            if (site !== undefined)
+                tagRouteSite(this, `${method.toUpperCase()} ${path}`, site);
+        }
         const compiled = compileRouteOptions({
             maxBodyBytes: this.maxBodyBytes,
             activeAssurance: this.activeAssurance,
@@ -1434,6 +1532,12 @@ export class Server {
     [INSTALL_RESPONSE_CONTRACT](runtime) {
         this.assertConfigurable("responseContract()");
         this.responseContractRuntime = runtime;
+        if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+            recordLateInstall(this, "responseContract", this.catalog
+                .entries()
+                .filter(({ entry }) => entry.responseContract === undefined &&
+                (entry.schema?.response !== undefined || entry.schema?.errors !== undefined))
+                .map((route) => `${route.method} ${route.path}`));
     }
     /** @internal Symbol-keyed install seam for the response observer plugin. */
     [INSTALL_RESPONSE_OBSERVER](runtime) {
@@ -1555,13 +1659,40 @@ export class Server {
      * registered before a `derive`). Fail closed: a path+method collision throws
      * `RouteConfigError` at merge time, and a group with WebSocket routes or mounts is refused
      * (register those on the parent).
+     *
+     * What this server's `.use()`, made BEFORE the merge, covers on a merged route versus a
+     * `group()` route:
+     *
+     *   | installed on this server                   | group() route | merge()d route                 |
+     *   | ------------------------------------------ | ------------- | ------------------------------ |
+     *   | derive/decorate/beforeHandle/afterHandle,  | yes           | no - wire it on the merged     |
+     *   | onError/around, authenticate, route-scoped |               | server                         |
+     *   | assurance                                  |               |                                |
+     *   | onRequest/onResponse/responseHeaders hooks | yes           | yes (app-wide)                 |
+     *   | responseContract()                         | yes           | yes, when the route declares a |
+     *   |                                            |               | response and its own server    |
+     *   |                                            |               | installed no contract          |
+     *   | effectLedger()                             | yes           | yes, when the route declares   |
+     *   |                                            |               | capabilities and has no ledger |
+     *   | idempotency()                              | yes           | the merged server's own; a     |
+     *   |                                            |               | route declaring it without one |
+     *   |                                            |               | is refused at registration     |
+     *
+     * The response contract and the ledger can only add a check or a record, so a merged route is
+     * recompiled under them. A runtime installed AFTER the merge covers neither kind of route.
+     *
+     * In development, {@link ServerOptions.unusedScopedHooks} reports a hook followed only by merges and
+     * a contract or ledger installed after the routes it would cover; `nifra check` reports a merge whose
+     * server authenticates none of its routes under this server's `authenticate()` (NF-C043).
      */
     merge(other) {
         this.assertConfigurable("merge()");
         if (!(other instanceof Server)) {
             // A server from another copy of this package reaches this copy's private request state through
             // symbols it does not share, and would fail per request. The boot warning names the copies.
-            throw new TypeError("merge() requires a server() from this copy of @nifrajs/core");
+            throw new TypeError(hookAuditRuntime && process.env.NODE_ENV !== "production"
+                ? mergeRefusal()
+                : "merge() requires a server() from this copy of @nifrajs/core");
         }
         if (this.routePrefix !== "") {
             // The merged routes were compiled under their own paths; adopting them here would publish them
@@ -1572,7 +1703,11 @@ export class Server {
         if (source.wsRoutes.length > 0 || source.fetchMounts.length > 0) {
             throw new RouteConfigError("INVALID_PATH", "merge() does not carry WebSocket routes or mounts - register them on the parent server");
         }
+        if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+            noteMergeAuthGap(this, this.authStages, this.activeAssurance, source.catalog.entries(), source.globalAssurance);
         this.adopt(source, undefined, 0);
+        if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+            noteMergedRoutes(this, source.catalog.size);
         return this;
     }
     /**
@@ -1590,7 +1725,7 @@ export class Server {
      * The builder receives a scope that INHERITS this server's route chain as it stands at the call
      * (`derive`/`decorate`/`authenticate`/`beforeHandle`/`afterHandle`/`onError`/`around`, assurance,
      * capability interceptors, installed runtimes, applied plugins), exactly as a route declared here
-     * would. A plugin this server already applied is in effect for the group: the group's `use()` of
+     * would. {@link merge} documents how that differs for a merged server. A plugin this server already applied is in effect for the group: the group's `use()` of
      * that same instance does nothing, and its `use()` of another instance under the same name throws a
      * `RouteConfigError` (`PLUGIN_RECONFIGURED`), because that instance could never replace the parent's.
      * A plugin the group applies still shares the parent's copy of a dependency it `use()`s itself.
@@ -1684,7 +1819,7 @@ export class Server {
                 assurance: [...route.assurance, ...ownGlobal],
             })
             : (route) => route;
-        this.catalog.addBatch(sourceRoutes.map((route) => this.bindFusedRuntime(foldedAssurance(route))));
+        this.catalog.addBatch(sourceRoutes.map((route) => this.bindFusedRuntime(foldedAssurance(adoptRouteRuntimes(route, this.responseContractRuntime, this.effectLedgerRuntime)))));
         // Resolved idempotency/ledger route entries carry their own store/sink configuration, while the
         // runtime object supplies the generic execution machinery. If the parent already has a runtime,
         // either implementation can execute every resolved entry because route-specific options were
@@ -2310,6 +2445,7 @@ export class Server {
                         pubsub,
                         attach: runtime.attach,
                         maxPayloadBytes: this.wsMaxPayloadBytes,
+                        sender: runtime.sender,
                     };
             };
             const wrap = (response) => finalize(response, EMPTY_RESPONSE_CONTROLS);
@@ -2410,9 +2546,8 @@ export class Server {
                 return this.fetch(req, bunPeerPlatform(server, req));
             if (o.kind === "reject")
                 return o.response;
-            return server.upgrade(req, {
-                data: { handler: o.handler, data: o.data, pubsub: o.pubsub },
-            })
+            // A copy: the Bun socket keeps per-connection state on it, and a hand-built outcome may be shared.
+            return server.upgrade(req, { data: { ...o } })
                 ? undefined
                 : jsonError(426, "upgrade_required");
         };
@@ -2845,6 +2980,11 @@ export class Server {
     [INSTALL_EFFECT_LEDGER](runtime) {
         this.assertConfigurable("effectLedger()");
         this.effectLedgerRuntime = runtime;
+        if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+            recordLateInstall(this, "effectLedger", this.catalog
+                .entries()
+                .filter(({ entry, descriptor }) => entry.ledgered === undefined && (descriptor.capabilities?.length ?? 0) > 0)
+                .map((route) => `${route.method} ${route.path}`));
     }
     /** The narrowest bare route: a syntactic `() => ...` handler cannot observe the context argument, so
      * successful requests can skip allocating `RequestContext`. Errors still allocate one for logging. */
@@ -3053,7 +3193,7 @@ export class Server {
                 ? RequestContext.native(source, params, search, maxBodyBytes, platform, this.protoPoisoning)
                 : new RequestContext(source, params, search, signal, budget, platform, maxBodyBytes, this.protoPoisoning);
             const finish = (value) => runParsed(value, ctx, finalize, wrapResponse);
-            return readBodyFramed(source, maxBodyBytes, this.protoPoisoning, finish, wrapResponse, (err) => logError(err, ctx, finalize, wrapResponse), bodySchema);
+            return readBodyFramed(source, maxBodyBytes, this.protoPoisoning, finish, wrapResponse, (err) => logError(err, ctx, finalize, wrapResponse), bodySchema, this.formOrigins);
         };
     }
     /** Web adapter wrapper for the shared body runner. Node passes its native finalizer directly through
@@ -3340,7 +3480,7 @@ export class Server {
                 ctx.body = validation.value;
                 return runHandlerValidated();
             };
-            return readBodyFramed(source, maxBodyBytes, this.protoPoisoning, onParsed, (response) => this.wrapWebResponse(response), (err) => Promise.resolve(logError(err, ctx)), bodySchema);
+            return readBodyFramed(source, maxBodyBytes, this.protoPoisoning, onParsed, (response) => this.wrapWebResponse(response), (err) => Promise.resolve(logError(err, ctx)), bodySchema, this.formOrigins);
         };
     }
     /**
@@ -3620,7 +3760,7 @@ export class Server {
             const ctx = nativeContext
                 ? RequestContext.native(source, params, search, maxBodyBytes, platform, this.protoPoisoning)
                 : new RequestContext(source, params, search, signal, budget, platform, maxBodyBytes, this.protoPoisoning);
-            return readBodyFramed(source, maxBodyBytes, this.protoPoisoning, (parsed) => onParsed(parsed, ctx, finalize, wrapResponse), wrapResponse, (err) => logError(err, ctx, finalize, wrapResponse), bodySchema);
+            return readBodyFramed(source, maxBodyBytes, this.protoPoisoning, (parsed) => onParsed(parsed, ctx, finalize, wrapResponse), wrapResponse, (err) => logError(err, ctx, finalize, wrapResponse), bodySchema, this.formOrigins);
         };
     }
     bareError(err, ctx, finalize, wrapResponse) {
@@ -3660,7 +3800,9 @@ export class Server {
         if (stage.kind === "body")
             return this.readProgramBody(entry, source, ctx);
         const input = stage.kind === "headers"
-            ? headerObjectOf(source.headers)
+            ? stage.names === undefined
+                ? headerObjectOf(source.headers)
+                : declaredHeaders(source.headers, stage.names)
             : stage.kind === "query"
                 ? queryObjectOf(ctx[CONTEXT_SEARCH])
                 : ctx[stage.kind];
@@ -3678,8 +3820,8 @@ export class Server {
     }
     /** Keep thrown Response/status and redacted 500 semantics in one existing error boundary. */
     // @ts-expect-error TS6133 -- invoked structurally by the general route program
-    handleProgramError(entry, error, ctx, finalize, wrapResponse) {
-        return this.handleLifecycleError(entry, error, ctx, finalize, wrapResponse);
+    handleProgramError(entry, error, ctx, finalize, wrapResponse, fallback) {
+        return this.handleLifecycleError(entry, error, ctx, finalize, wrapResponse, fallback);
     }
     /** Finish a successful program result through response-contract enforcement and finalization. */
     // @ts-expect-error TS6133 -- invoked structurally by the general route program
@@ -3988,7 +4130,9 @@ export class Server {
      * result a microtask even when every branch it takes returns immediately, which is the common case
      * here - a thrown `status(...)`/`Response`, or a route with no `onError` hook at all. Only the hook
      * loop, which may await, drops into {@link runErrorHooks}. */
-    handleLifecycleError(entry, err, ctx, finalize, wrapResponse) {
+    handleLifecycleError(entry, err, ctx, finalize, wrapResponse, 
+    // The answer when no hook does; the default 500 unless a stage owns a different fail-closed status.
+    fallback) {
         // A *thrown* Response is deliberate control flow, not an error - a guard throws a redirect/401,
         // an action throws an error page. Send it as the same Response returned would be sent (Remix/
         // SvelteKit semantics): as built, plus the cookies the request queued, so a session set or
@@ -4003,13 +4147,13 @@ export class Server {
             // Never crash the server or leak internals. The client gets a flat 500; the detail goes to the
             // (redacting) logger. Body-read failures and around-hook failures land here too.
             this.logRequestError(err, ctx);
-            return wrapResponse(plainError(500, "internal_error"));
+            return fallback === undefined ? wrapResponse(plainError(500, "internal_error")) : fallback();
         }
-        return this.runErrorHooks(entry, err, ctx, finalize, wrapResponse);
+        return this.runErrorHooks(entry, err, ctx, finalize, wrapResponse, fallback);
     }
     /** 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) {
+    async runErrorHooks(entry, 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++) {
@@ -4031,7 +4175,7 @@ export class Server {
             }
         }
         this.logRequestError(err, ctx);
-        return wrapResponse(plainError(500, "internal_error"));
+        return fallback === undefined ? wrapResponse(plainError(500, "internal_error")) : fallback();
     }
     /** Log an unhandled request error to the (redacting) logger - shared by the compiled route program and the
      * bare fast path ({@link bareError}) so both record the same fields. Never throws; never leaks. */
@@ -4049,7 +4193,7 @@ export class Server {
                 ? validation.then((result) => this.applyLifecycleValidation(entry, result, ctx, "body"))
                 : this.applyLifecycleValidation(entry, validation, ctx, "body");
         };
-        return readBodyFramed(req, bodyLimit ?? UNLIMITED_BODY_BYTES, this.protoPoisoning, validate, (response) => response, (error) => Promise.reject(error), bodySchema);
+        return readBodyFramed(req, bodyLimit ?? UNLIMITED_BODY_BYTES, this.protoPoisoning, validate, (response) => response, (error) => Promise.reject(error), bodySchema, this.formOrigins);
     }
     /** Apply validation and its recovery hook on the generic lifecycle lane. Recovery is completed
      * before derives/beforeHandle run, matching the body-only and query-only execution lanes. */
@@ -4356,7 +4500,7 @@ export class Server {
         // that registry in the upgrade outcome instead of accidentally broadcasting child sockets through
         // the parent.
         const nativePubsub = this.wsRoutes.length > 0 && !this.mountsTakeUpgrades() && !this.wsHasValidatedSend;
-        const wsHandlers = wsRuntime?.bunHandlers(this.topics ?? wsRuntime.createTopics(), nativePubsub);
+        const wsHandlers = wsRuntime?.bunHandlers(this.topics ?? wsRuntime.createTopics(), nativePubsub, this);
         // Spread rather than pass `hostname: undefined` (or an undefined idle timeout or TLS) - Bun treats
         // an explicit undefined as a value on some option paths, and omitting is what selects its own
         // defaults, 0.0.0.0 among them.
@@ -4402,8 +4546,9 @@ export class Server {
                 // `unknown` params bridge a TS structural-variance quirk. Round-trip covered by websocket.test.ts.
                 websocket: {
                     // Cap inbound frames so a huge message can't be buffered/JSON-parsed into memory; the runtime
-                    // closes an over-cap connection before the handler runs. Default 1 MB (maxBodyBytes).
-                    maxPayloadLength: this.wsMaxPayloadBytes,
+                    // 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),
                     message: (ws, message) => wsHandlers.message(ws, message),
                     close: (ws, code, reason) => wsHandlers.close(ws, code, reason),