@nifrajs/core 5.5.1 → 5.7.0

package/dist/server/server.js

@@ -6,12 +6,15 @@ import { assuranceDeclarationsOf, assuranceEvidenceFor, NIFRA_ASSURANCE_IDS, } f
 import { RouteCatalog } from "../internal/route-catalog.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 { authenticateMount, compileRouteProgram, executeRouteProgram, } from "../internal/route-program.js";
 import { isSameOriginRequest } from "../internal/same-origin.js";
 import { decodeRouteParams, expandOptionalParams, } from "../router/pattern.js";
 import { EMPTY_PARAMS, METHODS, Router } from "../router/router.js";
+import { withAnswerSteps } from "./answer-step.js";
+import { isAuthenticatedRequest, markAuthenticatedRequest, } from "./auth.js";
 import { emitRequestErrorLog, renderBareError } from "./bare-error-lane.js";
-import { assertByteLimit, markTransportCap, markTrustedBodyFraming, UNLIMITED_BODY_BYTES, } from "./body.js";
+import { LAST_BEFORE_HANDLE } from "./before-handler.js";
+import { assertByteLimit, clientBodyErrorCode, hasTrustedBodyFraming, markTransportCap, markTrustedBodyFraming, UNLIMITED_BODY_BYTES, } from "./body.js";
 import { NIFRA_PLATFORM_CLIENT_IP_DERIVED, resolveClientIp, } from "./client-ip.js";
 import { mergeRefusal, recordCopyVersion } from "./core-copies.js";
 import { hasLowercaseHeaderKeysMark, headerKeysAllLowercase, markLowercaseHeaderKeys, } from "./header-case.js";
@@ -25,9 +28,10 @@ import { needsResolving, resolveDotSegments } from "./request-target.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 { withTextSlots } from "./text-slots.js";
 import { plainValidationError } from "./validation.js";
 import { NIFRA_BACKEND_WS_RUNTIME } from "../mount.js";
-import { GET_WS_RUNTIME, INSTALL_EFFECT_LEDGER, INSTALL_IDEMPOTENCY, INSTALL_MCP, INSTALL_NODE_DIRECT, INSTALL_NOT_FOUND, INSTALL_RESPONSE_CONTRACT, INSTALL_RESPONSE_OBSERVER, INSTALL_SSE, INSTALL_WS, NODE_NATIVE_MOUNT, REPORT_ERROR, RESOLVE_NODE_MOUNT, } from "./install.js";
+import { GET_WS_RUNTIME, INSTALL_EFFECT_LEDGER, INSTALL_IDEMPOTENCY, INSTALL_MCP, INSTALL_NODE_DIRECT, INSTALL_NOT_FOUND, INSTALL_RESPONSE_CONTRACT, INSTALL_RESPONSE_OBSERVER, INSTALL_SSE, INSTALL_WS, NODE_NATIVE_MOUNT, REPORT_ERROR, RESOLVE_NODE_MOUNT, SERVER_LIFECYCLE, } from "./install.js";
 import { jsonLogger } from "./logger.js";
 // CORS uses this marker to say its request hook only handles OPTIONS preflight. Bun can keep
 // ordinary registered routes on its native table and send unmatched OPTIONS requests through the
@@ -129,6 +133,8 @@ function requireMcpRuntime(runtime) {
 // existing importers keep resolving them from the server module.
 export { defineContextPlugin, defineIdentityPlugin, definePlugin, defineRouterPlugin, } from "./plugin.js";
 const DEFAULT_MAX_BODY_BYTES = 1_000_000;
+const BODY_RESPONSE = (response) => response;
+const BODY_ERROR = (error) => Promise.reject(error);
 const DEFAULT_DRAIN_MS = 10_000;
 const DRAIN_POLL_MS = 10;
 const STOP_HOOK_TIMEOUT_MS = 5_000;
@@ -171,16 +177,106 @@ function hasUnroutedParam(params) {
  * Bun, workerd and every `new Request()` parse it first. Only there does `fetch` read the URL up front.
  */
 const rawRequestTargets = typeof globalThis.Deno !== "undefined";
-/** `req` as Bun or workerd would have delivered it: the same request, its URL resolved as they parse it. */
-const withResolvedTarget = (req) => new Request(resolveDotSegments(req.url), req);
+/**
+ * Bun parses the target only when it can read the Host. Otherwise `Request.url` is the target as sent:
+ * relative for a Host with a space or a byte past ASCII or for no Host at all, the raw authority
+ * for a port past 65535, and `new URL(req.url)` throws in the app. So Bun is held to the Host check
+ * Deno runs.
+ */
+const unparsedBunTargets = typeof Bun !== "undefined";
+/**
+ * `req` as Bun or workerd would have delivered it: the same request, its URL resolved as they parse it.
+ * `undefined` when the `Request` constructor refuses what the wire carried - a TRACE, CONNECT or TRACK,
+ * a lower-case `get` with a body - which {@link resolvedSource} routes instead.
+ */
+function withResolvedTarget(req, url) {
+    let rebuilt;
+    try {
+        rebuilt = new Request(url, req);
+    }
+    catch {
+        return undefined;
+    }
+    // The same body, so the same framing: a runtime still delimited it.
+    if (hasTrustedBodyFraming(req))
+        markTrustedBodyFraming(rebuilt);
+    return rebuilt;
+}
+/**
+ * A request no `Request` can be rebuilt from, as a source carrying its resolved URL: it is routed on that
+ * URL and gets the 404 or 405 the other runtimes give, where rebuilding it threw out of `fetch`. A
+ * handler that reads `c.req` gets the request as Deno delivered it.
+ */
+function resolvedSource(req, url) {
+    const source = {
+        method: req.method,
+        url,
+        get headers() {
+            return req.headers;
+        },
+        header: (name) => headerOf(req, name),
+        get body() {
+            return req.body;
+        },
+        arrayBuffer: () => req.arrayBuffer(),
+        json: () => req.json(),
+        bytes: () => req.bytes(),
+        request: req,
+    };
+    if (hasTrustedBodyFraming(req))
+        markTrustedBodyFraming(source);
+    return source;
+}
 // A Host as RFC 9110 allows it: a reg-name or an IP literal, then an optional port. Deno builds
 // `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_AUTHORITY = /^(?:\[[0-9a-f:.%]+\]|[\w.-]+)(?::(\d{1,5}))?$/i;
+// Clients repeat one Host on every request; comparing to the last valid one is ~7x cheaper than the regex.
+let lastValidHost = "";
+// A port past 65535, or an IPv6 literal no URL parser takes (`[1:2]`), is refused as Node refuses it:
+// no URL can be built on either, so resolving a dot segment against one threw out of `fetch`.
+const invalidHost = (host) => {
+    if (host === lastValidHost)
+        return false;
+    const authority = HOST_AUTHORITY.exec(host);
+    if (authority === null)
+        return true;
+    if (authority[1] !== undefined && Number(authority[1]) > 65_535)
+        return true;
+    if (host.charCodeAt(0) === 91 /* [ */ && !URL.canParse(`http://${host}/`))
+        return true;
+    lastValidHost = host;
+    return false;
+};
+/**
+ * What a request is routed on in place of `req.url`, before anything reads it: `true` refuses its
+ * Host (400), a URL replaces the target, `false` keeps it. Deno hands the target over as sent, so
+ * its dot segments are resolved; so does Bun when HTTP/1.0 leaves the Host out, and its route table
+ * matched `/files/..` raw. Such a request is served as `localhost`, as Node and Deno serve it.
+ * `headerOf`, not `req.headers`: on Deno that reads the Host alone instead of building every
+ * header.
+ */
+const requestTarget = (req) => {
+    if (!rawRequestTargets && !unparsedBunTargets)
+        return false;
     const host = headerOf(req, "host");
-    return host !== null && !HOST_AUTHORITY.test(host);
+    if (host !== null && invalidHost(host)) {
+        if (rawRequestTargets)
+            return true;
+        // Bun served it anyway: it could not read the Host, so it left the target unparsed, or it
+        // built the URL on it - sent twice (joined with ", ", the URL on the first; RFC 9112 section
+        // 3.2 answers 400), percent-encoded (`%61.example` routed as `a.example`), or with a
+        // sub-delimiter (`a!b`). A request built in process keeps the URL its caller built, unless Bun
+        // would have built it so.
+        const routed = URL.parse(req.url)?.host;
+        return routed === undefined || URL.parse(`//${host.split(", ")[0]}`, req.url)?.host === routed;
+    }
+    if (rawRequestTargets)
+        return needsResolving(req.url) && resolveDotSegments(req.url);
+    // A request built in process carries an absolute URL whatever its headers say.
+    return (host === null &&
+        req.url.charCodeAt(0) === 47 /* / */ &&
+        resolveDotSegments(`http://localhost${req.url}`));
 };
 function normalizeMountPrefix(path) {
     if (!path.startsWith("/") || path.includes("?") || path.includes("#")) {
@@ -210,13 +306,17 @@ function mountPriorityOf(priority) {
 function compareMounts(a, b) {
     return b.priority - a.priority || b.path.length - a.path.length || a.order - b.order;
 }
+/** Rebase a mounted request's path without losing the authentication mark used by child caches. */
 function stripMountPrefix(request, prefix) {
     if (prefix === "/")
         return request;
     const url = new URL(request.url);
     const rest = url.pathname.slice(prefix.length);
     url.pathname = rest === "" ? "/" : rest;
-    return new Request(url.href, request);
+    const childRequest = new Request(url.href, request);
+    if (isAuthenticatedRequest(request))
+        markAuthenticatedRequest(childRequest);
+    return childRequest;
 }
 function responseSet(ctx) {
     return ctx[CONTEXT_SET]() ?? EMPTY_RESPONSE_CONTROLS;
@@ -403,6 +503,17 @@ const recordScopedHook = (key, routesAtPush, kind) => {
         site: captureCallerSite(),
     });
 };
+/** `next(value)` now, or once `value` settles. */
+const thenMaybe = (value, next) => (value instanceof Promise ? value.then(next) : next(value));
+/** A mount registered after an `authenticate()` stage runs it, so the stage covers something. */
+const noteAuthenticatedMount = (key) => {
+    const state = hookAudit.get(key);
+    if (state === undefined)
+        return;
+    for (const site of state.sites)
+        if (site.kind === "authenticate")
+            site.routesAtPush = -1;
+};
 /** 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) => {
@@ -555,6 +666,7 @@ export class Server {
     deadlineAdmissionOptions;
     gracefulSignals;
     stopHooks;
+    stoppingHooks;
     fetchMounts;
     mountOrder;
     /** Number of composed mounts that must run before the parent route table. Keeps legacy mounts off the hot path. */
@@ -632,9 +744,13 @@ export class Server {
     /** Body/raw response hooks need a framework-payload marker; keep that decision per app. */
     responseBodyTag;
     responseBodyOwners;
-    finalizeResponse = (result, set, ctx) => toResponse(result, set, this.responseBodyTag, this.staticResponseHeaders, 
-    // Response hooks write next, and they run for this same request object.
-    ctx !== undefined && this.onResponseHooks.length > 0 ? ctx[CONTEXT_REQUEST] : undefined);
+    // General lifecycles need no extra response bookkeeping when neither controls nor observers
+    // use it. Share the fused renderer after the lifecycle, including on body/write routes.
+    finalizeResponse = (result, set, ctx) => set === EMPTY_RESPONSE_CONTROLS && this.onResponseHooks.length === 0
+        ? fusedRespondNoSet(result, this.responseBodyTag, this.staticResponseHeaders, true)
+        : toResponse(result, set, this.responseBodyTag, this.staticResponseHeaders, 
+        // Response hooks write next, and they run for this same request object.
+        ctx !== undefined && this.onResponseHooks.length > 0 ? ctx[CONTEXT_REQUEST] : undefined, this.onResponseHooks.length === 0);
     responseRequests;
     /** A request the WebSocket handshake check ran the onRequest hooks on and then passed to HTTP →
      * what the hooks returned, so `fetch` routes that instead of running the hooks a second time. */
@@ -700,6 +816,7 @@ export class Server {
         this.gracefulSignals =
             options.gracefulSignals === true ? {} : options.gracefulSignals || undefined;
         this.stopHooks = [];
+        this.stoppingHooks = [];
         this.fetchMounts = [];
         this.mountOrder = 0;
         this.preRouteMountCount = 0;
@@ -770,10 +887,25 @@ export class Server {
         this.stopHooks.push(fn);
         return this;
     }
+    /**
+     * Register a callback awaited as soon as `stop()` begins, while the server still serves: readiness
+     * should fail from here, and work that outlives a request (a poller, a queue consumer) should stop
+     * taking more. Hung callbacks are bounded.
+     */
+    onStopping(fn) {
+        this.assertConfigurable("onStopping()");
+        if (typeof fn !== "function")
+            throw new TypeError("onStopping callback must be a function");
+        this.stoppingHooks.push(fn);
+        return this;
+    }
     /**
      * 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.
+     * Mounted responses are outside Nifra's typed route and response-contract checks. An
+     * `authenticate()` stage registered before the mount, or a required auth plugin built on one
+     * (`bearer()`, `jwt()`, `basicAuth()`, `apiKey()`), refuses a request before the handler sees it;
+     * mount before the stage to keep the legacy surface public.
      *
      * 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
@@ -792,7 +924,10 @@ export class Server {
             beforeRoutes: false,
             order: this.mountOrder++,
             opaque: options.opaque,
+            authStages: [...this.authStages],
         };
+        if (hookAuditRuntime && process.env.NODE_ENV !== "production" && this.authStages.length > 0)
+            noteAuthenticatedMount(this);
         this.fetchMounts.push(mount);
         this.fetchMounts.sort(compareMounts);
         return this;
@@ -846,7 +981,10 @@ export class Server {
             order: this.mountOrder++,
             opaque: options.opaque,
             app,
+            authStages: [...this.authStages],
         };
+        if (hookAuditRuntime && process.env.NODE_ENV !== "production" && this.authStages.length > 0)
+            noteAuthenticatedMount(this);
         // Mounts run before routes: a request under this prefix that no mount on the way strips comes back
         // here unchanged until the stack overflows, which takes the process down. Dev-time only, like the
         // hook audit: a production define folds this away, and the first dev request would hit it anyway.
@@ -888,7 +1026,8 @@ export class Server {
      * (see {@link ServerOptions.unusedScopedHooks}).
      */
     /**
-     * Register a dedicated authentication stage for subsequent routes.
+     * Register a dedicated authentication stage for subsequent routes, and for the `mount()` and
+     * `mountFetch()` handlers registered after it: a request it refuses never reaches them.
      *
      * 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
@@ -950,7 +1089,13 @@ export class Server {
      */
     beforeHandle(fn) {
         this.assertConfigurable("beforeHandle()");
-        this.beforeHandleHooks.push(fn);
+        const hooks = this.beforeHandleHooks;
+        let at = hooks.length;
+        if (!LAST_BEFORE_HANDLE.has(fn)) {
+            while (at > 0 && LAST_BEFORE_HANDLE.has(hooks[at - 1]))
+                at--;
+        }
+        hooks.splice(at, 0, fn);
         if (hookAuditRuntime && process.env.NODE_ENV !== "production") {
             recordScopedHook(this, this.catalog.size + this.wsRoutes.length, "beforeHandle");
             tagHook(fn, "beforeHandle", this);
@@ -1451,6 +1596,7 @@ 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) {
+        schema = withTextSlots(schema);
         // 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 &&
@@ -1480,6 +1626,15 @@ export class Server {
             defaultOnValidationError: this.defaultOnValidationError,
         }, method, path, schema, handler);
         const { pattern, bodyLimit, capabilities, routeDecorations, hasDecorations, idempotent, ledgered, responseContract, lanes, routeAssurance, } = compiled;
+        // A schema that writes its answer its own way (`t.bytes()`) wraps every stage that can answer.
+        const stages = withAnswerSteps(schema, method, path, {
+            handler,
+            beforeHandle: this.beforeHandleHooks,
+            afterHandle: this.afterHandleHooks,
+            onError: this.onErrorHooks,
+        });
+        handler = stages.handler;
+        const { beforeHandle, afterHandle, onError } = stages;
         if (idempotent !== undefined && this.idempotencyRuntime !== undefined) {
             handler = this.idempotencyRuntime.wrapHandler(handler);
         }
@@ -1498,11 +1653,11 @@ export class Server {
         const fusedBodyRunner = fusedBody
             ? this.buildFusedBodyRunner(handler, schema?.body, hasDecorations ? routeDecorations : undefined, bodyLimit ?? UNLIMITED_BODY_BYTES)
             : isFusedBodyLifecycle
-                ? this.buildFusedBodyDeriveBeforeAfterRunner(handler, this.derives[0], this.beforeHandleHooks[0], this.afterHandleHooks[0], schema?.body, bodyLimit ?? UNLIMITED_BODY_BYTES)
+                ? this.buildFusedBodyDeriveBeforeAfterRunner(handler, this.derives[0], beforeHandle[0], afterHandle[0], schema?.body, bodyLimit ?? UNLIMITED_BODY_BYTES)
                 : isFusedLifecycle && lifecycleHookLane === "derive-before"
-                    ? this.buildFusedDeriveBeforeRunner(handler, this.derives[0], this.beforeHandleHooks[0], undefined, schema?.query, bodyLimit ?? UNLIMITED_BODY_BYTES)
+                    ? this.buildFusedDeriveBeforeRunner(handler, this.derives[0], beforeHandle[0], undefined, schema?.query, bodyLimit ?? UNLIMITED_BODY_BYTES)
                     : isFusedLifecycle && lifecycleHookLane === "derive-before-after"
-                        ? this.buildFusedDeriveBeforeRunner(handler, this.derives[0], this.beforeHandleHooks[0], this.afterHandleHooks[0], schema?.query, bodyLimit ?? UNLIMITED_BODY_BYTES)
+                        ? this.buildFusedDeriveBeforeRunner(handler, this.derives[0], beforeHandle[0], afterHandle[0], schema?.query, bodyLimit ?? UNLIMITED_BODY_BYTES)
                         : undefined;
         const fusedWeb = bare && this.aroundHooks.length === 0
             ? this.buildFusedWeb(handler, hasDecorations ? routeDecorations : undefined, isContextlessNoArgArrow(handler), bodyLimit ?? UNLIMITED_BODY_BYTES)
@@ -1511,20 +1666,20 @@ export class Server {
                 : fusedBody
                     ? this.buildFusedBodyWeb(fusedBodyRunner)
                     : isFusedBodyLifecycle
-                        ? this.buildFusedBodyDeriveBeforeAfter(handler, this.derives[0], this.beforeHandleHooks[0], this.afterHandleHooks[0], schema?.body, bodyLimit ?? UNLIMITED_BODY_BYTES)
+                        ? this.buildFusedBodyDeriveBeforeAfter(handler, this.derives[0], beforeHandle[0], afterHandle[0], schema?.body, bodyLimit ?? UNLIMITED_BODY_BYTES)
                         : isFusedLifecycle && lifecycleHookLane === "derive-before"
-                            ? this.buildFusedDeriveBefore(handler, this.derives[0], this.beforeHandleHooks[0], schema?.query, bodyLimit ?? UNLIMITED_BODY_BYTES)
+                            ? this.buildFusedDeriveBefore(handler, this.derives[0], beforeHandle[0], schema?.query, bodyLimit ?? UNLIMITED_BODY_BYTES)
                             : isFusedLifecycle && lifecycleHookLane === "derive-before-after"
-                                ? this.buildFusedDeriveBeforeAfter(handler, this.derives[0], this.beforeHandleHooks[0], this.afterHandleHooks[0], schema?.query, bodyLimit ?? UNLIMITED_BODY_BYTES)
+                                ? this.buildFusedDeriveBeforeAfter(handler, this.derives[0], beforeHandle[0], afterHandle[0], schema?.query, bodyLimit ?? UNLIMITED_BODY_BYTES)
                                 : undefined;
         const program = compileRouteProgram({
             schema,
             handler: handler,
             derives: this.derives,
             authStages: compiled.authStages,
-            beforeHandle: this.beforeHandleHooks,
-            afterHandle: this.afterHandleHooks,
-            onError: this.onErrorHooks,
+            beforeHandle,
+            afterHandle,
+            onError,
             decorations: routeDecorations,
             hasDecorations,
             bodySchema: schema?.body,
@@ -1552,9 +1707,9 @@ export class Server {
             authStages: [...compiled.authStages],
             decorations: routeDecorations,
             hasDecorations,
-            beforeHandle: [...this.beforeHandleHooks],
-            afterHandle: [...this.afterHandleHooks],
-            onError: [...this.onErrorHooks],
+            beforeHandle: [...beforeHandle],
+            afterHandle: [...afterHandle],
+            onError: [...onError],
             lifecycleHookLane: lanes.lifecycleHookLane,
             around: [...this.aroundHooks],
             execution,
@@ -1940,6 +2095,7 @@ export class Server {
         // Cleanup the source registered (a pool, a queue consumer) belongs to the server that now runs
         // its routes; dropping it would leak the resource past `stop()`.
         this.stopHooks.push(...source.stopHooks);
+        this.stoppingHooks.push(...source.stoppingHooks);
         this.mcpResourceList.push(...source.mcpResourceList);
         this.mcpPromptList.push(...source.mcpPromptList);
     }
@@ -2029,11 +2185,14 @@ export class Server {
     fetch(req, platform) {
         // Deno's `Request.url` is the target as sent; Bun, workerd and every `new Request()` parse it.
         // Route what the parsed URL says, so `/users/../admin` is `/admin` on every runtime.
-        if (rawRequestTargets) {
-            if (invalidHost(req))
-                return jsonError(400, "invalid_host");
-            if (needsResolving(req.url))
-                req = withResolvedTarget(req);
+        const target = requestTarget(req);
+        if (target === true)
+            return jsonError(400, "invalid_host");
+        if (target !== false) {
+            const rebuilt = withResolvedTarget(req, target);
+            if (rebuilt === undefined)
+                return this.fetchSource(resolvedSource(req, target), platform);
+            req = rebuilt;
         }
         // An edge deployment whose only ingress is this method declares its requests runtime-framed at
         // construction; everything else stays on the delivered-byte check (see `trustBodyFraming`).
@@ -2151,7 +2310,7 @@ export class Server {
         // The mount the ordinary path reaches first: every `mount()` runs before any `mountFetch()`,
         // whatever their prefix lengths. A 404 fallthrough chain stays on the ordinary path.
         const mount = this.firstMountUnder(parts.pathname, true) ?? this.firstMountUnder(parts.pathname, false);
-        if (mount === undefined || mount.fallbackOn404)
+        if (mount === undefined || mount.fallbackOn404 || mount.authStages.length > 0)
             return undefined;
         const candidate = mount.handler[NODE_NATIVE_MOUNT];
         return typeof candidate === "function"
@@ -2435,12 +2594,16 @@ export class Server {
         // The adapter answers a pass by handing this same object to `fetch`.
         const received = req;
         // The handshake routes the path `fetch` would: Host checked, dot segments resolved (see `fetch`).
-        if (rawRequestTargets) {
-            if (invalidHost(req)) {
-                return { kind: "reject", response: this.wrapWebResponse(jsonError(400, "invalid_host")) };
-            }
-            if (needsResolving(req.url))
-                req = withResolvedTarget(req);
+        const target = requestTarget(req);
+        if (target === true) {
+            return { kind: "reject", response: this.wrapWebResponse(jsonError(400, "invalid_host")) };
+        }
+        if (target !== false) {
+            // A GET carrying a body cannot be rebuilt; `fetch` routes it as the ordinary request it is.
+            const rebuilt = withResolvedTarget(req, target);
+            if (rebuilt === undefined)
+                return WS_PASS;
+            req = rebuilt;
         }
         // The handshake's caller is the one `fetch` derives: hooks and `upgrade()` see the trusted IP.
         platform = this.trustedPlatform(req, platform);
@@ -2545,26 +2708,35 @@ export class Server {
                 }
                 if (selected === undefined)
                     return WS_PASS;
-                let childRequest = request;
-                if (selected.stripPrefix) {
-                    childRequest = stripMountPrefix(request, selected.path);
-                    selected.wsPassed ??= new WeakMap();
-                    selected.wsPassed.set(request, childRequest);
-                }
-                let child;
-                try {
-                    child = selected.resolveWebSocketUpgrade(childRequest, platform);
-                }
-                catch {
-                    return refuse(jsonError(500, "internal_error"));
-                }
+                const mount = selected;
+                const upgrade = () => {
+                    let childRequest = request;
+                    if (mount.stripPrefix) {
+                        childRequest = stripMountPrefix(request, mount.path);
+                        mount.wsPassed ??= new WeakMap();
+                        mount.wsPassed.set(request, childRequest);
+                    }
+                    try {
+                        return mount.resolveWebSocketUpgrade(childRequest, platform);
+                    }
+                    catch {
+                        return refuse(jsonError(500, "internal_error"));
+                    }
+                };
                 const settle = (outcome) => outcome.kind === "pass" ||
                     (outcome.kind === "reject" && outcome.response.status === 404 && selected.fallbackOn404)
                     ? dispatch(selectedIndex + 1)
                     : outcome.kind === "reject"
                         ? refuse(outcome.response)
                         : outcome;
-                return child instanceof Promise ? child.then(settle) : settle(child);
+                const run = () => {
+                    const child = upgrade();
+                    return child instanceof Promise ? child.then(settle) : settle(child);
+                };
+                // Only a child's miss may fall through, never an authentication refusal.
+                return mount.authStages.length === 0
+                    ? run()
+                    : thenMaybe(authenticateMount(mount.authStages, request, platform, this.logger), (refusal) => (refusal === undefined ? run() : refuse(refusal)));
             };
             return dispatch(0);
         };
@@ -2857,8 +3029,8 @@ export class Server {
      * routes with validation/hooks keep the full compiled route program, unchanged.
      */
     routeAndRun(source, platform, finalize, wrapResponse, onTimeout, webFast) {
-        // Routing only needs the pathname. Scan the URL once but keep the two slices in locals instead
-        // of allocating the `{ pathname, search }` pair returned by the public helper on every request.
+        // Native delimiter searches keep path/query splitting out of a character-by-character JS loop.
+        // Keep the slices in locals instead of allocating the public helper's pathname/search pair.
         let pathname;
         let search;
         // Read the source's split ONCE. `urlParts` is an accessor on the Node request sources that
@@ -2879,22 +3051,11 @@ export class Server {
                 search = "";
             }
             else {
-                let pathEnd = rawUrl.length;
-                let searchStart = -1;
-                let searchEnd = rawUrl.length;
-                for (let i = start; i < rawUrl.length; i++) {
-                    const c = rawUrl.charCodeAt(i);
-                    if (c === 63 /* ? */ && searchStart === -1) {
-                        pathEnd = i;
-                        searchStart = i;
-                    }
-                    else if (c === 35 /* # */) {
-                        if (searchStart === -1)
-                            pathEnd = i;
-                        searchEnd = i;
-                        break;
-                    }
-                }
+                const fragment = rawUrl.indexOf("#", start);
+                const searchEnd = fragment === -1 ? rawUrl.length : fragment;
+                const question = rawUrl.indexOf("?", start);
+                const searchStart = question !== -1 && question < searchEnd ? question : -1;
+                const pathEnd = searchStart === -1 ? searchEnd : searchStart;
                 pathname = rawUrl.slice(start, pathEnd);
                 search = searchStart === -1 ? "" : rawUrl.slice(searchStart, searchEnd);
             }
@@ -2967,16 +3128,28 @@ export class Server {
             }
             if (mount === undefined)
                 return fallback ?? jsonError(404, "not_found");
-            const childRequest = mount.stripPrefix
-                ? (mount.wsPassed?.get(request) ?? stripMountPrefix(request, mount.path))
-                : request;
-            const outcome = mount.handler(childRequest, platform);
-            if (!replayable || !mount.fallbackOn404)
-                return outcome;
-            if (outcome instanceof Promise) {
-                return outcome.then((response) => response.status === 404 ? dispatch(index + 1, response) : response);
-            }
-            return outcome.status === 404 ? dispatch(index + 1, outcome) : outcome;
+            const selected = mount;
+            const run = () => {
+                const reused = selected.stripPrefix ? selected.wsPassed?.get(request) : undefined;
+                const childRequest = selected.stripPrefix
+                    ? (reused ?? stripMountPrefix(request, selected.path))
+                    : request;
+                // HTTP authentication may have marked the original since the WebSocket pass.
+                if (reused !== undefined && isAuthenticatedRequest(request)) {
+                    markAuthenticatedRequest(reused);
+                }
+                const outcome = selected.handler(childRequest, platform);
+                if (!replayable || !selected.fallbackOn404)
+                    return outcome;
+                if (outcome instanceof Promise) {
+                    return outcome.then((response) => response.status === 404 ? dispatch(index + 1, response) : response);
+                }
+                return outcome.status === 404 ? dispatch(index + 1, outcome) : outcome;
+            };
+            // Keep gate refusals outside the child's 404 fallthrough path.
+            return mount.authStages.length === 0
+                ? run()
+                : thenMaybe(authenticateMount(mount.authStages, request, platform, this.logger), (refusal) => refusal ?? run());
         };
         return dispatch(first);
     }
@@ -3861,7 +4034,7 @@ export class Server {
         // The thrown-value contract lives in `bare-error-lane.ts`, one source of truth for both this
         // lane and the fused body runner. `responseSet` and the logger are injected because they reach
         // into class state; the closure is allocated only on the throw path, never on the hot lane.
-        return renderBareError(err, ctx, finalize, responseSet, (e, c) => this.logRequestError(e, c), () => this.internalErrorResponse(wrapResponse));
+        return renderBareError(err, ctx, finalize, responseSet, (e, c) => this.logRequestError(e, c), wrapResponse);
     }
     /**
      * Keep the ordinary thrown-error response independent from the caught value. Deliberate Response
@@ -3939,7 +4112,7 @@ export class Server {
     }
     // @ts-expect-error TS6133 -- invoked structurally by compiled plans (internal/route-execution.ts)
     runBodyOnly(entry, source, ctx, finalize, wrapResponse) {
-        return readBodyFramed(source, entry.bodyLimit ?? UNLIMITED_BODY_BYTES, this.protoPoisoning, (parsed) => this.finishBodyOnly(entry, parsed, ctx, finalize, wrapResponse), wrapResponse, (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse), entry.schema?.body);
+        return readBodyFramed(source, entry.bodyLimit ?? UNLIMITED_BODY_BYTES, this.protoPoisoning, (parsed) => this.finishBodyOnly(entry, parsed, ctx, finalize, wrapResponse), wrapResponse, (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse), entry.schema?.body, this.formOrigins);
     }
     /** Validate + run the handler for the bodyOnly path - shared by the inline fast path and the
      * streaming fallback. A method (not per-request closures) so the hot path allocates nothing
@@ -4193,7 +4366,15 @@ export class Server {
                 return finalize(result, responseSet(ctx), ctx);
             const checked = contract.runtime.check(contract.definition, result, ctx);
             if (checked instanceof Promise) {
-                return checked.then((outcome) => this.finishContractOutcome(ctx, finalize, wrapResponse, outcome), (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
+                return checked.then((outcome) => {
+                    // The render runs outside the try below: a throw (a BigInt, a cycle) must still reach onError.
+                    try {
+                        return this.finishContractOutcome(ctx, finalize, wrapResponse, outcome);
+                    }
+                    catch (err) {
+                        return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+                    }
+                }, (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
             }
             return this.finishContractOutcome(ctx, finalize, wrapResponse, checked);
         }
@@ -4238,6 +4419,9 @@ export class Server {
         if (err instanceof Response || isResponseResult(err))
             return this.finishLifecycleContract(entry, ctx, finalize, wrapResponse, err);
         if (entry.onError.length === 0) {
+            const clientCode = clientBodyErrorCode(err);
+            if (clientCode !== undefined)
+                return wrapResponse(plainError(400, clientCode));
             // 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);
@@ -4297,6 +4481,9 @@ export class Server {
                 return wrapResponse(plainError(500, "internal_error"));
             }
         }
+        const clientCode = clientBodyErrorCode(err);
+        if (clientCode !== undefined)
+            return wrapResponse(plainError(400, clientCode));
         this.logRequestError(err, ctx);
         return fallback === undefined ? wrapResponse(plainError(500, "internal_error")) : fallback();
     }
@@ -4311,27 +4498,35 @@ export class Server {
         // second continuation, while retaining the exact bounded-read, content-type, and poisoning
         // contracts shared by every body route.
         const validate = (parsed) => {
-            const validation = bodySchema["~standard"].validate(parsed);
-            return validation instanceof Promise
-                ? validation.then((result) => this.applyLifecycleValidation(entry, result, ctx, "body"))
-                : this.applyLifecycleValidation(entry, validation, ctx, "body");
+            // Reject outside the parser's JSON catch so a custom validator throw reaches onError.
+            try {
+                const validation = bodySchema["~standard"].validate(parsed);
+                return validation instanceof Promise
+                    ? validation.then((result) => this.applyLifecycleValidation(entry, result, ctx, "body"))
+                    : this.applyLifecycleValidation(entry, validation, ctx, "body");
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
         };
-        return readBodyFramed(req, bodyLimit ?? UNLIMITED_BODY_BYTES, this.protoPoisoning, validate, (response) => response, (error) => Promise.reject(error), bodySchema, this.formOrigins);
+        return readBodyFramed(req, bodyLimit ?? UNLIMITED_BODY_BYTES, this.protoPoisoning, validate, BODY_RESPONSE, BODY_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. */
     applyLifecycleValidation(entry, result, ctx, kind) {
-        const assign = (value) => {
-            ;
-            ctx[kind] = value;
-        };
         if (result.issues === undefined) {
-            assign(result.value);
+            // biome-ignore lint/plugin/noChainedTypeAssertions lint/plugin/requireSafetyCommentForTypeAssertion: RawContext carries every ProgramValidationKind slot; this instruction assigns its validated value before handlers run.
+            ;
+            ctx[kind] = result.value;
             return undefined;
         }
         const hook = entry.schema?.onValidationError ?? this.defaultOnValidationError;
         if (hook === undefined)
             return plainValidationError(result.issues);
+        const assign = (value) => {
+            ;
+            ctx[kind] = value;
+        };
         const attempted = hook(result.issues, ctx, kind);
         if (attempted instanceof Promise) {
             return attempted.then((recovery) => this.finishLifecycleValidationRecovery(entry, kind, result.issues, recovery, assign));
@@ -4364,13 +4559,19 @@ export class Server {
         // the HTTP framing, so the JSON lane may retain its native fused `json()` parse without weakening
         // the portable/adapted source contract (those sources are never marked).
         const markFramed = (request) => markTrustedBodyFraming(request);
-        // The fused native lane bypasses `runMatched`, so the route's transport byte cap must be
+        // The direct native lanes bypass `runMatched`, so the route's transport byte cap must be
         // marked here too - otherwise a Bun `listen()` fused route would leave direct `c.req` body
-        // reads uncapped. The non-fused branches go through `fetchMatched` -> `runMatched`, which marks.
+        // reads uncapped. The fallback branches go through `fetchMatched` -> `runMatched`, which marks.
         const bodyLimit = entry.schema?.body === undefined || entry.program.authBeforeValidation
             ? entry.bodyLimit
             : undefined;
-        const inner = fused;
+        // The complete plan already preserves general validation, hooks, recovery, around, and ledgers.
+        // When native admission is safe, use it directly even if the route has no closed-shape fusion.
+        // Idempotency still needs runMatched's request preparation and is excluded from the table.
+        const inner = fused ??
+            (signal && budget
+                ? (source, params, search, activeSignal, activeBudget, platform, nativeContext) => entry.execution.run(this, entry, source, params, search, activeSignal, activeBudget, platform, nativeContext, this.finalizeResponse, this.wrapWebResponse)
+                : undefined);
         const capped = inner === undefined || bodyLimit === undefined
             ? inner
             : (source, params, search, fusedSignal, fusedBudget, platform, nativeContext) => {
@@ -4530,7 +4731,9 @@ export class Server {
             }
             const paramNames = pattern.paramNames;
             const fused = mayUseFusedNative ? entry.execution.fusedWeb : undefined;
-            tableAt(path, pattern.segments)[method] = this.compileBunNativeHandler(entry, paramNames, fused, unboundedSignal, unboundedBudget, peer, fallback);
+            const handler = this.compileBunNativeHandler(entry, paramNames, fused, unboundedSignal, unboundedBudget, peer, fallback);
+            // The table matched the target as sent; one `fetch` refuses or rewrites goes through it.
+            tableAt(path, pattern.segments)[method] = (request, server) => requestTarget(request) ? fallback(request, server) : handler(request, server);
             count += 1;
             if (paramNames.length > 0) {
                 below.add(pattern.segments.length + method);
@@ -4713,11 +4916,12 @@ export class Server {
      * The Bun semantics: poll `pendingRequests` (awaiting
      * `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. Open WebSockets
-     * get a 1001 close at once and the same window to finish it, before any `onStop` hook runs.
+     * New connections may be accepted during the drain window; `delayMs` is the time a load balancer
+     * gets to stop routing here first. The `onStopping` hooks run before that delay, the `onStop`
+     * hooks after the drain. Open WebSockets get a 1001 close when the drain starts and the same
+     * window to finish it; a socket opened after `stop()` began is closed at once.
      */
-    async stop({ drainMs = DEFAULT_DRAIN_MS } = {}) {
+    async stop({ drainMs = DEFAULT_DRAIN_MS, delayMs = 0 } = {}) {
         const onSignal = this.signalHandler;
         if (onSignal !== undefined) {
             this.signalHandler = undefined;
@@ -4727,6 +4931,9 @@ export class Server {
         if (server === undefined)
             return;
         this.bunServer = undefined;
+        await this[SERVER_LIFECYCLE]("stopping");
+        if (delayMs > 0)
+            await Bun.sleep(delayMs);
         const sockets = this.bunSockets;
         this.bunSockets = undefined;
         if (sockets !== undefined)
@@ -4738,14 +4945,25 @@ export class Server {
             await Bun.sleep(DRAIN_POLL_MS);
         }
         server.stop(busy()); // force-close iff stragglers remain past the deadline
-        if (this.stopHooks.length === 0)
+        await this[SERVER_LIFECYCLE]("stopped");
+    }
+    /**
+     * @internal Run the `onStopping` or the `onStop` hooks, each bounded. A runtime adapter that drains
+     * its own listener calls it on either side of the drain, as `stop()` does here.
+     */
+    async [SERVER_LIFECYCLE](phase) {
+        const hooks = phase === "stopping" ? this.stoppingHooks : this.stopHooks;
+        if (hooks.length === 0)
             return;
-        const callbacks = this.stopHooks.map((hook) => Promise.resolve().then(hook));
-        const settled = Promise.allSettled(callbacks);
+        let timer;
         await Promise.race([
-            settled,
-            new Promise((resolve) => setTimeout(resolve, STOP_HOOK_TIMEOUT_MS)),
+            Promise.allSettled(hooks.map((hook) => Promise.resolve().then(hook))),
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, STOP_HOOK_TIMEOUT_MS);
+            }),
         ]);
+        // A pending bound would hold the event loop open after every hook settled.
+        clearTimeout(timer);
     }
     installSignalHandlers(drain) {
         // Drain, then let the process exit naturally - the stopped server no longer