@nifrajs/core 5.5.1 → 5.7.0

package/src/server/server.ts

@@ -50,7 +50,11 @@ import {
   type RouteEntry,
 } from "../internal/route-execution.ts"
 import type { ProgramValidationKind, RouteProgramStage } from "../internal/route-program.ts"
-import { compileRouteProgram, executeRouteProgram } from "../internal/route-program.ts"
+import {
+  authenticateMount,
+  compileRouteProgram,
+  executeRouteProgram,
+} from "../internal/route-program.ts"
 import { isSameOriginRequest } from "../internal/same-origin.ts"
 import type { ResponseObserverPlugin } from "../response-observer.ts"
 import {
@@ -65,10 +69,18 @@ import type {
   StandardResult,
   StandardSchemaV1,
 } from "../schema/standard.ts"
-import type { AuthenticationStage } from "./auth.ts"
+import { withAnswerSteps } from "./answer-step.ts"
+import {
+  type AuthenticationStage,
+  isAuthenticatedRequest,
+  markAuthenticatedRequest,
+} from "./auth.ts"
 import { emitRequestErrorLog, renderBareError } from "./bare-error-lane.ts"
+import { LAST_BEFORE_HANDLE } from "./before-handler.ts"
 import {
   assertByteLimit,
+  clientBodyErrorCode,
+  hasTrustedBodyFraming,
   markTransportCap,
   markTrustedBodyFraming,
   type RawBodyReaders,
@@ -151,6 +163,7 @@ import {
   type StatusResponse,
 } from "./runtime-core.ts"
 import { normalizeStaticResponseHeaders, type StaticResponseHeaders } from "./static-headers.ts"
+import { withTextSlots } from "./text-slots.ts"
 import { plainValidationError } from "./validation.ts"
 
 // NodeServeOutcome (the nifra<->node bridge render form) now lives in `./node-outcome.ts`; re-exported
@@ -184,6 +197,7 @@ import {
   NODE_NATIVE_MOUNT,
   REPORT_ERROR,
   RESOLVE_NODE_MOUNT,
+  SERVER_LIFECYCLE,
 } from "./install.ts"
 import type { EffectLedgerRuntime } from "./ledger-lane.ts"
 import { jsonLogger, type Logger } from "./logger.ts"
@@ -226,6 +240,7 @@ import type {
   RunningServer,
   ServerOptions,
   StopHook,
+  StopOptions,
   ToolAnnotations,
 } from "./server-types.ts"
 import type { SSEInit, TypedSSEStream } from "./sse.ts"
@@ -378,6 +393,8 @@ interface FetchMount<Env = unknown> {
   readonly fallbackOn404: boolean
   readonly beforeRoutes: boolean
   readonly order: number
+  /** The `authenticate()` stages registered before this mount, which gate it as they gate a route. */
+  readonly authStages: readonly RawAuthStage[]
   /** Why this child is not analyzed (`MountOptions.opaque`), checked by reflection. */
   readonly opaque: string | OpaqueMountDeclaration | undefined
   /** The mounted app (`mount()` only), for reflection to tell a composed child from an opaque one. */
@@ -563,6 +580,7 @@ export type {
   RunningServer,
   ServerOptions,
   StopHook,
+  StopOptions,
   ToolAnnotations,
 }
 
@@ -588,6 +606,8 @@ export {
 export type { IdentityPlugin }
 
 const DEFAULT_MAX_BODY_BYTES = 1_000_000
+const BODY_RESPONSE = (response: Response | ResponseResult): Response | ResponseResult => response
+const BODY_ERROR = (error: unknown): Promise<never> => Promise.reject(error)
 const DEFAULT_DRAIN_MS = 10_000
 const DRAIN_POLL_MS = 10
 const STOP_HOOK_TIMEOUT_MS = 5_000
@@ -637,18 +657,104 @@ function hasUnroutedParam(params: Record<string, string>): boolean {
  */
 const rawRequestTargets = typeof (globalThis as { Deno?: unknown }).Deno !== "undefined"
 
-/** `req` as Bun or workerd would have delivered it: the same request, its URL resolved as they parse it. */
-const withResolvedTarget = (req: Request): Request => 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: Request, url: string): Request | undefined {
+  let rebuilt: Request
+  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: Request, url: string): RequestSource {
+  const source: RequestSource = {
+    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
+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: string): boolean => {
+  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
+}
 
-// `headerOf`, not `req.headers`: on Deno that reads the Host alone instead of building every header.
-const invalidHost = (req: Request): boolean => {
+/**
+ * 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: Request): string | boolean => {
+  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: string): string {
@@ -681,12 +787,15 @@ function compareMounts<Env>(a: FetchMount<Env>, b: FetchMount<Env>): number {
   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: Request, prefix: string): Request {
   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
 }
 
 /** `ctx.set` carrying the lazy backings (`_headers`, `_cookies`) so `toResponse` can skip allocating
@@ -881,8 +990,9 @@ interface HookAuditState {
   readonly hasCustomLogger: boolean
   readonly sites: {
     readonly kind: string
-    /** Routes that captured the chain so far: merged routes excluded, they keep their own. */
-    readonly routesAtPush: number
+    /** Routes that captured the chain so far: merged routes excluded, they keep their own. -1 once a
+     * mount captured it, which no route count matches. */
+    routesAtPush: number
     readonly mergedAtPush: number
     readonly site: string | undefined
   }[]
@@ -964,6 +1074,19 @@ const recordScopedHook = (key: object, routesAtPush: number, kind: string): void
   })
 }
 
+/** `next(value)` now, or once `value` settles. */
+const thenMaybe = <T, U>(
+  value: MaybePromise<T>,
+  next: (value: T) => MaybePromise<U>,
+): MaybePromise<U> => (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: object): void => {
+  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: object, count: number): void => {
@@ -1158,8 +1281,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
   private readonly acceptInboundDeadlines: boolean
   private readonly maxInboundDeadlineMs: number
   private readonly deadlineAdmissionOptions: DeadlineAdmissionOptions
-  private readonly gracefulSignals: { readonly drainMs?: number } | undefined
+  private readonly gracefulSignals: StopOptions | undefined
   private readonly stopHooks: StopHook[]
+  private readonly stoppingHooks: StopHook[]
   private readonly fetchMounts: FetchMount<EnvOf<Ctx>>[]
   private mountOrder: number
   /** Number of composed mounts that must run before the parent route table. Keeps legacy mounts off the hot path. */
@@ -1242,15 +1366,20 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
   /** Body/raw response hooks need a framework-payload marker; keep that decision per app. */
   private responseBodyTag: object | undefined
   private readonly responseBodyOwners: Set<object>
+  // 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.
   private readonly finalizeResponse = (result: unknown, set: CtxSet, ctx?: RawContext): Response =>
-    toResponse(
-      result as HandlerResult,
-      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,
-    )
+    set === EMPTY_RESPONSE_CONTROLS && this.onResponseHooks.length === 0
+      ? fusedRespondNoSet(result, this.responseBodyTag, this.staticResponseHeaders, true)
+      : toResponse(
+          result as HandlerResult,
+          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,
+        )
   private readonly responseRequests: WeakMap<Request, Request>
   /** 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. */
@@ -1318,6 +1447,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     this.gracefulSignals =
       options.gracefulSignals === true ? {} : options.gracefulSignals || undefined
     this.stopHooks = []
+    this.stoppingHooks = []
     this.fetchMounts = []
     this.mountOrder = 0
     this.preRouteMountCount = 0
@@ -1393,10 +1523,25 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     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: StopHook): this {
+    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
@@ -1418,7 +1563,10 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       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
@@ -1474,7 +1622,10 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       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.
@@ -1533,7 +1684,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
    * (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
@@ -1603,7 +1755,12 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     fn: H,
   ): Server<R, Ctx, HookOutput | HookOutputOf<ReturnType<H>>> {
     this.assertConfigurable("beforeHandle()")
-    this.beforeHandleHooks.push(fn as unknown as RawBeforeHandle)
+    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 as unknown as RawBeforeHandle)
     if (hookAuditRuntime && process.env.NODE_ENV !== "production") {
       recordScopedHook(this, this.catalog.size + this.wsRoutes.length, "beforeHandle")
       tagHook(fn, "beforeHandle", this)
@@ -2440,6 +2597,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     schema: RouteSchema | undefined,
     handler: (context: never) => unknown,
   ): CatalogRoute {
+    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 (
@@ -2487,6 +2645,15 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       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)
     }
@@ -2514,8 +2681,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
         ? this.buildFusedBodyDeriveBeforeAfterRunner(
             handler as unknown as InternalHandler,
             this.derives[0]!,
-            this.beforeHandleHooks[0]!,
-            this.afterHandleHooks[0],
+            beforeHandle[0]!,
+            afterHandle[0],
             schema?.body as StandardSchemaV1,
             bodyLimit ?? UNLIMITED_BODY_BYTES,
           )
@@ -2523,7 +2690,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
           ? this.buildFusedDeriveBeforeRunner(
               handler as unknown as InternalHandler,
               this.derives[0]!,
-              this.beforeHandleHooks[0]!,
+              beforeHandle[0]!,
               undefined,
               schema?.query,
               bodyLimit ?? UNLIMITED_BODY_BYTES,
@@ -2532,8 +2699,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
             ? this.buildFusedDeriveBeforeRunner(
                 handler as unknown as InternalHandler,
                 this.derives[0]!,
-                this.beforeHandleHooks[0]!,
-                this.afterHandleHooks[0],
+                beforeHandle[0]!,
+                afterHandle[0],
                 schema?.query,
                 bodyLimit ?? UNLIMITED_BODY_BYTES,
               )
@@ -2559,8 +2726,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
               ? this.buildFusedBodyDeriveBeforeAfter(
                   handler as unknown as InternalHandler,
                   this.derives[0]!,
-                  this.beforeHandleHooks[0]!,
-                  this.afterHandleHooks[0],
+                  beforeHandle[0]!,
+                  afterHandle[0],
                   schema?.body as StandardSchemaV1,
                   bodyLimit ?? UNLIMITED_BODY_BYTES,
                 )
@@ -2568,7 +2735,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
                 ? this.buildFusedDeriveBefore(
                     handler as unknown as InternalHandler,
                     this.derives[0]!,
-                    this.beforeHandleHooks[0]!,
+                    beforeHandle[0]!,
                     schema?.query,
                     bodyLimit ?? UNLIMITED_BODY_BYTES,
                   )
@@ -2576,8 +2743,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
                   ? this.buildFusedDeriveBeforeAfter(
                       handler as unknown as InternalHandler,
                       this.derives[0]!,
-                      this.beforeHandleHooks[0]!,
-                      this.afterHandleHooks[0]!,
+                      beforeHandle[0]!,
+                      afterHandle[0]!,
                       schema?.query,
                       bodyLimit ?? UNLIMITED_BODY_BYTES,
                     )
@@ -2587,9 +2754,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       handler: handler as unknown as InternalHandler,
       derives: this.derives,
       authStages: compiled.authStages,
-      beforeHandle: this.beforeHandleHooks,
-      afterHandle: this.afterHandleHooks,
-      onError: this.onErrorHooks,
+      beforeHandle,
+      afterHandle,
+      onError,
       decorations: routeDecorations,
       hasDecorations,
       bodySchema: schema?.body,
@@ -2618,9 +2785,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       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,
@@ -3060,6 +3227,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     // 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)
   }
@@ -3223,9 +3391,12 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
   fetch(req: Request, platform?: Platform<EnvOf<Ctx>>): MaybePromise<Response> {
     // 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`).
@@ -3387,7 +3558,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     // 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) return undefined
+    if (mount === undefined || mount.fallbackOn404 || mount.authStages.length > 0) return undefined
     const candidate = (mount.handler as unknown as Record<symbol, unknown>)[NODE_NATIVE_MOUNT]
     return typeof candidate === "function"
       ? {
@@ -3724,11 +3895,15 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     // 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)
@@ -3844,17 +4019,19 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
           }
         }
         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: MaybePromise<WebSocketUpgradeOutcome>
-        try {
-          child = selected.resolveWebSocketUpgrade!(childRequest, platform)
-        } catch {
-          return refuse(jsonError(500, "internal_error"))
+        const mount = selected
+        const upgrade = (): MaybePromise<WebSocketUpgradeOutcome> => {
+          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: WebSocketUpgradeOutcome): MaybePromise<WebSocketUpgradeOutcome> =>
           outcome.kind === "pass" ||
@@ -3863,7 +4040,17 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
             : outcome.kind === "reject"
               ? refuse(outcome.response)
               : outcome
-        return child instanceof Promise ? child.then(settle) : settle(child)
+        const run = (): MaybePromise<WebSocketUpgradeOutcome> => {
+          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)
     }
@@ -4252,8 +4439,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     onTimeout: () => T,
     webFast: boolean,
   ): MaybePromise<T> {
-    // 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: string
     let search: string
     // Read the source's split ONCE. `urlParts` is an accessor on the Node request sources that
@@ -4272,20 +4459,11 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
         pathname = "/"
         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)
       }
@@ -4377,17 +4555,32 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
         }
       }
       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,
-        )
+      const selected = mount
+      const run = (): MaybePromise<Response> => {
+        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
       }
-      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)
   }
@@ -5857,7 +6050,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       finalize,
       responseSet,
       (e, c) => this.logRequestError(e, c),
-      () => this.internalErrorResponse(wrapResponse),
+      wrapResponse,
     )
   }
 
@@ -5993,6 +6186,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       wrapResponse,
       (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse),
       entry.schema?.body,
+      this.formOrigins,
     )
   }
 
@@ -6365,7 +6559,14 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       const checked = contract.runtime.check(contract.definition, result, ctx)
       if (checked instanceof Promise) {
         return checked.then(
-          (outcome) => this.finishContractOutcome(ctx, finalize, wrapResponse, outcome),
+          (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),
         )
       }
@@ -6428,6 +6629,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     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)
@@ -6516,6 +6719,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
         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()
   }
@@ -6538,18 +6743,23 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     // second continuation, while retaining the exact bounded-read, content-type, and poisoning
     // contracts shared by every body route.
     const validate = (parsed: unknown): MaybePromise<Response | ResponseResult | undefined> => {
-      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),
+      BODY_RESPONSE,
+      BODY_ERROR,
       bodySchema,
       this.formOrigins,
     )
@@ -6563,15 +6773,16 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     ctx: RawContext,
     kind: ProgramValidationKind,
   ): MaybePromise<Response | ResponseResult | undefined> {
-    const assign = (value: unknown): void => {
-      ;(ctx as unknown as Record<ProgramValidationKind, unknown>)[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 as unknown as Record<ProgramValidationKind, unknown>)[kind] = result.value
       return undefined
     }
     const hook = entry.schema?.onValidationError ?? this.defaultOnValidationError
     if (hook === undefined) return plainValidationError(result.issues)
+    const assign = (value: unknown): void => {
+      ;(ctx as unknown as Record<ProgramValidationKind, unknown>)[kind] = value
+    }
     const attempted = hook(result.issues, ctx as unknown as Context, kind)
     if (attempted instanceof Promise) {
       return attempted.then((recovery) =>
@@ -6618,14 +6829,34 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     // 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: Request): void => 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: FusedWebRunner | undefined =
+      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: FusedWebRunner | undefined =
       inner === undefined || bodyLimit === undefined
         ? inner
@@ -6808,7 +7039,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       }
       const paramNames = pattern.paramNames
       const fused = mayUseFusedNative ? entry.execution.fusedWeb : undefined
-      tableAt(path, pattern.segments)[method as Method] = this.compileBunNativeHandler(
+      const handler = this.compileBunNativeHandler(
         entry,
         paramNames,
         fused,
@@ -6817,6 +7048,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
         peer,
         fallback,
       )
+      // The table matched the target as sent; one `fetch` refuses or rewrites goes through it.
+      tableAt(path, pattern.segments)[method as Method] = (request, server) =>
+        requestTarget(request) ? fallback(request, server) : handler(request, server)
       count += 1
       if (paramNames.length > 0) {
         below.add(pattern.segments.length + method)
@@ -7016,11 +7250,12 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
    * 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 }: { drainMs?: number } = {}): Promise<void> {
+  async stop({ drainMs = DEFAULT_DRAIN_MS, delayMs = 0 }: StopOptions = {}): Promise<void> {
     const onSignal = this.signalHandler
     if (onSignal !== undefined) {
       this.signalHandler = undefined
@@ -7029,6 +7264,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     const server = this.bunServer
     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) for (const ws of sockets) ws.close(1001)
@@ -7038,16 +7275,28 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
       await Bun.sleep(DRAIN_POLL_MS)
     }
     server.stop(busy()) // force-close iff stragglers remain past the deadline
-    if (this.stopHooks.length === 0) return
-    const callbacks = this.stopHooks.map((hook) => Promise.resolve().then(hook))
-    const settled = Promise.allSettled(callbacks)
+    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: "stopping" | "stopped"): Promise<void> {
+    const hooks = phase === "stopping" ? this.stoppingHooks : this.stopHooks
+    if (hooks.length === 0) return
+    let timer: ReturnType<typeof setTimeout> | undefined
     await Promise.race([
-      settled,
-      new Promise<void>((resolve) => setTimeout(resolve, STOP_HOOK_TIMEOUT_MS)),
+      Promise.allSettled(hooks.map((hook) => Promise.resolve().then(hook))),
+      new Promise<void>((resolve) => {
+        timer = setTimeout(resolve, STOP_HOOK_TIMEOUT_MS)
+      }),
     ])
+    // A pending bound would hold the event loop open after every hook settled.
+    clearTimeout(timer)
   }
 
-  private installSignalHandlers(drain: { readonly drainMs?: number }): void {
+  private installSignalHandlers(drain: StopOptions): void {
     // Drain, then let the process exit naturally - the stopped server no longer
     // holds the event loop open. Opt-in (`gracefulSignals`), so taking over the
     // signals is consented; we don't force `process.exit`.