@nifrajs/core 1.8.0 → 1.9.1

package/src/server/server.ts

@@ -1,3 +1,11 @@
+import {
+  admitDeadline,
+  createRequestBudget,
+  createUnboundedRequestBudget,
+  type DeadlineAdmissionOptions,
+  NIFRA_DEADLINE_HEADER,
+  type RequestBudget,
+} from "@nifrajs/budget"
 import { FrameworkError, RouteConfigError } from "../errors.ts"
 import {
   type AssuranceDeclaration,
@@ -115,6 +123,7 @@ interface RawContext {
   readonly [CONTEXT_SET]: () => CtxSet | undefined
   readonly [CONTEXT_SEARCH]: string
   readonly signal: AbortSignal
+  readonly budget: RequestBudget
   readonly env: unknown
   readonly waitUntil: (promise: Promise<unknown>) => void
   readonly boundedBody: (maxBytes?: number) => Promise<Uint8Array>
@@ -192,9 +201,11 @@ interface RouteEntry {
 type FusedWebRunner = (
   source: RequestSource,
   params: Record<string, string>,
-  search: string,
+  search: string | undefined,
   signal: AbortSignal,
+  budget: RequestBudget,
   platform: Platform | undefined,
+  nativeContext: boolean,
 ) => MaybePromise<Response>
 
 /** A registered WebSocket route — just its handler; matching reuses {@link Router} under the GET verb. */
@@ -207,6 +218,11 @@ interface BunUpgradeServer {
   upgrade(request: Request, options?: { data?: BunWsData }): boolean
 }
 
+type BunNativeHandler = (request: Request) => MaybePromise<Response>
+type BunNativeMethodTable = Partial<Record<Method, BunNativeHandler>>
+type BunNativeRoutes = Record<string, BunNativeMethodTable>
+type BunRequestWithParams = Request & { readonly params?: Record<string, string> }
+
 const WS_PASS: WebSocketUpgradeOutcome = { kind: "pass" }
 
 /** `app.ws()` (and everything downstream of it) needs the runtime `@nifrajs/core/ws` registers. */
@@ -238,6 +254,27 @@ export type Handler<
   Ctx = EmptyContext,
 > = (ctx: Context<Path, S> & Ctx) => MaybePromise<ResponseOf<S>>
 
+/**
+ * The outcome of a capacity-admission decision. `admitted` requests carry a `release` the server calls
+ * exactly once when the response is finalized; a shed request carries a ready `429` Response.
+ */
+export type AdmissionDecision =
+  | { readonly admitted: true; release(): void }
+  | { readonly admitted: false; readonly response: Response }
+
+/**
+ * A capacity-admission gate. Decides, per request, whether the instance has capacity to run it now —
+ * bounding *concurrency*, which rate limits (frequency) and deadlines (duration) do not. Provide an
+ * implementation (see `@nifrajs/middleware`'s `createAdmissionController`) as {@link ServerOptions.admission}.
+ *
+ * Enabling it trades the fused native-route lane for native matching + this gate (the gate cannot be a
+ * per-request `onRequest` hook without disabling native routes entirely); when unset, the request path
+ * is untouched.
+ */
+export interface AdmissionController {
+  admit(req: Request): AdmissionDecision | Promise<AdmissionDecision>
+}
+
 export interface ServerOptions {
   /**
    * Max request body size (bytes), enforced **only when a route declares a body schema** — the cap
@@ -255,8 +292,27 @@ export interface ServerOptions {
   readonly wsMaxPayloadBytes?: number
   /** Per-request timeout (ms): a slower request gets a 503 and `ctx.signal` aborts. 0 disables (default). */
   readonly requestTimeoutMs?: number
+  /**
+   * Admit the public `x-nifra-deadline` header and let it shorten local work. Disabled by default:
+   * services that participate in trusted cross-service deadline propagation opt in explicitly,
+   * while ordinary/public HTTP routes pay no header-admission tax and ignore hostile client values.
+   */
+  readonly acceptInboundDeadlines?: boolean
+  /**
+   * Maximum time accepted from an inbound `x-nifra-deadline`, in milliseconds. An incoming absolute
+   * deadline may shorten this cap (and `requestTimeoutMs`, when configured), never extend it.
+   * Default 30_000; applies only when `acceptInboundDeadlines` is enabled and the header is present.
+   */
+  readonly maxInboundDeadlineMs?: number
   /** When `listen()`ing, install SIGTERM/SIGINT handlers that gracefully `stop()`. Default false. */
   readonly gracefulSignals?: boolean
+  /**
+   * Capacity-admission gate (see {@link AdmissionController}). Bounds concurrent in-flight work so a
+   * healthy instance sheds load (`429` + `Retry-After`) instead of accepting more than it can finish.
+   * Off by default. Enabling it disables the fused native-route fast path (requests route through the
+   * shared matched lane where the gate runs); when unset, the request path pays nothing.
+   */
+  readonly admission?: AdmissionController
   /** Structured logger for framework events (redacts secrets). Default: JSON to stderr. */
   readonly logger?: Logger
   /**
@@ -475,10 +531,15 @@ const TEXT_DECODER = new TextDecoder()
  * reused at zero per-request cost.
  */
 let neverAbortSignal: AbortSignal | undefined
+let unboundedRequestBudget: RequestBudget | undefined
 const getNeverAbortSignal = (): AbortSignal => {
   neverAbortSignal ??= new AbortController().signal
   return neverAbortSignal
 }
+const getUnboundedRequestBudget = (): RequestBudget => {
+  unboundedRequestBudget ??= createUnboundedRequestBudget(getNeverAbortSignal())
+  return unboundedRequestBudget
+}
 
 function jsonError(status: number, error: string, headers?: Record<string, string>): Response {
   return Response.json(
@@ -679,6 +740,13 @@ function decodeParams(raw: Record<string, string>): Record<string, string> | nul
   return out ?? raw
 }
 
+function hasReplacementParam(params: Record<string, string>): boolean {
+  for (const key in params) {
+    if (params[key]!.includes("\uFFFD")) return true
+  }
+  return false
+}
+
 /** `ctx.set` carrying the lazy backings (`_headers`, `_cookies`) so `toResponse` can skip allocating
  * anything when no handler touched `c.set.*`. Server-internal. */
 type CtxSet = ResponseControls & {
@@ -742,51 +810,92 @@ function statusInit(init?: ResponseInit | number): ResponseInit | undefined {
 }
 
 class RequestContext implements RawContext {
-  readonly params: Record<string, string>
-  readonly signal: AbortSignal
-  readonly env: unknown
-  readonly waitUntil: (promise: Promise<unknown>) => void
-  body: unknown
-  readonly [CONTEXT_SEARCH]: string
-
-  private setValue: CtxSet | undefined
-  private queryValue: unknown
-  private queryReady: boolean
-  private cookiesValue: Readonly<Record<string, string>> | undefined
-  private readonly source: RequestSource
-  private readonly maxBodyBytes: number
-
+  // `declare` keeps TypeScript's class-field emit from first writing `undefined` to every slot; the
+  // constructor initializes only the eager request state, while lazy fields remain absent until used.
+  declare readonly params: Record<string, string>
+  declare body: unknown
+  private declare searchValue: string | undefined
+  private declare signalValue: AbortSignal | undefined
+  private declare budgetValue: RequestBudget | undefined
+  private declare platformValue: Platform | undefined
+
+  private declare setValue: CtxSet | undefined
+  private declare queryValue: unknown
+  private declare queryReady: boolean
+  private declare cookiesValue: Readonly<Record<string, string>> | undefined
+  private declare readonly source: RequestSource
+  private declare readonly maxBodyBytes: number
+
+  constructor(source: RequestSource, params: Record<string, string>, maxBodyBytes: number)
   constructor(
     source: RequestSource,
     params: Record<string, string>,
-    search: string,
+    search: string | undefined,
     signal: AbortSignal,
+    budget: RequestBudget,
     platform: Platform | undefined,
     maxBodyBytes: number,
+  )
+  constructor(
+    source: RequestSource,
+    params: Record<string, string>,
+    searchOrMaxBodyBytes: string | number | undefined,
+    signal?: AbortSignal,
+    budget?: RequestBudget,
+    platform?: Platform,
+    maxBodyBytes?: number,
   ) {
     this.source = source
     this.params = params
-    this[CONTEXT_SEARCH] = search
-    this.signal = signal
-    this.env = platform?.env
-    this.waitUntil = platform?.waitUntil ?? fallbackWaitUntil
-    this.maxBodyBytes = maxBodyBytes
-    this.setValue = undefined
-    this.body = undefined
-    this.queryValue = undefined
-    this.queryReady = false
-    this.cookiesValue = undefined
+    if (typeof searchOrMaxBodyBytes === "number") {
+      this.maxBodyBytes = searchOrMaxBodyBytes
+      return
+    }
+    if (searchOrMaxBodyBytes !== undefined) this.searchValue = searchOrMaxBodyBytes
+    this.signalValue = signal
+    this.budgetValue = budget
+    if (platform !== undefined) this.platformValue = platform
+    this.maxBodyBytes = maxBodyBytes as number
+  }
+
+  static native(
+    source: RequestSource,
+    params: Record<string, string>,
+    maxBodyBytes: number,
+  ): RequestContext {
+    return new RequestContext(source, params, maxBodyBytes)
   }
 
   [CONTEXT_SET](): CtxSet | undefined {
     return this.setValue
   }
 
+  get [CONTEXT_SEARCH](): string {
+    this.searchValue ??= searchOf(this.source.url)
+    return this.searchValue
+  }
+
   get set(): CtxSet {
     this.setValue ??= new LazyResponseControls()
     return this.setValue
   }
 
+  get signal(): AbortSignal {
+    return this.signalValue ?? getNeverAbortSignal()
+  }
+
+  get budget(): RequestBudget {
+    return this.budgetValue ?? getUnboundedRequestBudget()
+  }
+
+  get env(): unknown {
+    return this.platformValue?.env
+  }
+
+  get waitUntil(): (promise: Promise<unknown>) => void {
+    return this.platformValue?.waitUntil ?? fallbackWaitUntil
+  }
+
   get req(): Request {
     return requestOf(this.source)
   }
@@ -922,8 +1031,9 @@ const JSON_CT_HEADERS = new Headers({
 })
 const JSON_INIT_200: ResponseInit = { status: 200, headers: JSON_CT_HEADERS }
 
-/** Fused-lane respond when the handler ran with NO context (so `c.set` can't exist): the fast
- * JSON respond directly, with `toResponse` + the empty controls as the exact-semantics fallback. */
+/** Fused-lane respond when `c.set` is untouched. Bun 1.3's native `Response.json` now beats the
+ * older hand-inlined stringify + Response construction on this lane while preserving the exact
+ * body/content-type contract; keep the generic fallback for non-JSON values. */
 function fusedRespondNoSet(result: unknown): Response {
   if (
     result !== undefined &&
@@ -932,8 +1042,7 @@ function fusedRespondNoSet(result: unknown): Response {
     result !== null &&
     !isResponseResult(result)
   ) {
-    const body = JSON.stringify(result) as string | undefined
-    if (body !== undefined) return new Response(body, JSON_INIT_200)
+    return Response.json(result)
   }
   return toResponse(result as HandlerResult, EMPTY_RESPONSE_CONTROLS)
 }
@@ -1118,7 +1227,12 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   private readonly maxBodyBytes: number
   private readonly wsMaxPayloadBytes: number
   private readonly requestTimeoutMs: number
+  private readonly acceptInboundDeadlines: boolean
+  private readonly maxInboundDeadlineMs: number
+  private readonly deadlineAdmissionOptions: DeadlineAdmissionOptions
   private readonly gracefulSignals: boolean
+  /** Capacity-admission gate; `undefined` = off (the request path pays nothing). */
+  private readonly capacityGate: AdmissionController | undefined
   private readonly logger: Logger
   /** App-wide validation-error fallback; a route's own `schema.onValidationError` takes precedence. */
   private readonly defaultOnValidationError?: RouteSchema["onValidationError"]
@@ -1165,7 +1279,20 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     this.maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES
     this.wsMaxPayloadBytes = options.wsMaxPayloadBytes ?? this.maxBodyBytes
     this.requestTimeoutMs = options.requestTimeoutMs ?? 0
+    this.acceptInboundDeadlines = options.acceptInboundDeadlines ?? false
+    this.maxInboundDeadlineMs = options.maxInboundDeadlineMs ?? 30_000
+    this.deadlineAdmissionOptions = Object.freeze({
+      localTimeoutMs: this.requestTimeoutMs,
+      maxInboundDeadlineMs: this.maxInboundDeadlineMs,
+    })
+    if (!Number.isFinite(this.requestTimeoutMs) || this.requestTimeoutMs < 0) {
+      throw new RangeError("requestTimeoutMs must be a finite non-negative number")
+    }
+    if (!Number.isFinite(this.maxInboundDeadlineMs) || this.maxInboundDeadlineMs <= 0) {
+      throw new RangeError("maxInboundDeadlineMs must be a finite positive number")
+    }
     this.gracefulSignals = options.gracefulSignals ?? false
+    this.capacityGate = options.admission
     this.logger = options.logger ?? jsonLogger()
     this.defaultOnValidationError = options.onValidationError
     this.bunServer = undefined
@@ -1759,6 +1886,15 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   private fetchSource(
     source: RequestSource,
     platform?: Platform<EnvOf<Ctx>>,
+  ): MaybePromise<Response> {
+    // Off path (default): straight through — one property check, no closure, no promise.
+    if (this.capacityGate === undefined) return this.fetchSourceInner(source, platform)
+    return this.admitGated(requestOf(source), () => this.fetchSourceInner(source, platform))
+  }
+
+  private fetchSourceInner(
+    source: RequestSource,
+    platform?: Platform<EnvOf<Ctx>>,
   ): MaybePromise<Response> {
     // Non-`async` on purpose: `dispatch` may return a `Response` *synchronously* (the bare-route fast
     // path, see RouteEntry.bare), and an `async fetch` would wrap every such result in a redundant
@@ -1784,6 +1920,88 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       : this.applyOnResponseAndFinalize(outcome, this.takeResponseRequest(source))
   }
 
+  /** Web response path when Bun already matched the route. The lifecycle and response hooks remain
+   * exactly the same as {@link fetchSource}; only portable URL scanning + trie lookup are skipped. */
+  private fetchMatched(
+    source: RequestSource,
+    entry: RouteEntry,
+    params: Record<string, string>,
+  ): MaybePromise<Response> {
+    if (this.capacityGate === undefined) return this.fetchMatchedInner(source, entry, params)
+    return this.admitGated(requestOf(source), () => this.fetchMatchedInner(source, entry, params))
+  }
+
+  private fetchMatchedInner(
+    source: RequestSource,
+    entry: RouteEntry,
+    params: Record<string, string>,
+  ): MaybePromise<Response> {
+    const outcome = this.runMatched(
+      source,
+      undefined,
+      entry,
+      params,
+      undefined,
+      toResponse,
+      IDENTITY_RESPONSE,
+      RESPONSE_TIMEOUT,
+      true,
+    )
+    if (this.onResponseHooks.length === 0 && this.onResponseFinalizedHooks.length === 0) {
+      return outcome
+    }
+    return outcome instanceof Promise
+      ? outcome.then((response) => this.applyOnResponseAndFinalize(response, requestOf(source)))
+      : this.applyOnResponseAndFinalize(outcome, requestOf(source))
+  }
+
+  /**
+   * Run `produce` under the capacity gate: admit → run → release exactly once when the response is
+   * produced (or the run throws). Only reached when {@link capacityGate} is set, so the off path pays
+   * nothing. The slot is held for the duration of handler execution, not the streaming of the body —
+   * capacity here bounds concurrent *work*, matching how in-flight is counted.
+   */
+  private admitGated(req: Request, produce: () => MaybePromise<Response>): MaybePromise<Response> {
+    const decision = (this.capacityGate as AdmissionController).admit(req)
+    return decision instanceof Promise
+      ? decision.then((settled) => this.runAdmitted(settled, produce))
+      : this.runAdmitted(decision, produce)
+  }
+
+  private runAdmitted(
+    decision: AdmissionDecision,
+    produce: () => MaybePromise<Response>,
+  ): MaybePromise<Response> {
+    if (!decision.admitted) return decision.response // shed: ready 429, no slot held
+    let released = false
+    const release = (): void => {
+      if (released) return
+      released = true
+      decision.release()
+    }
+    let outcome: MaybePromise<Response>
+    try {
+      outcome = produce()
+    } catch (error) {
+      release()
+      throw error
+    }
+    if (outcome instanceof Promise) {
+      return outcome.then(
+        (response) => {
+          release()
+          return response
+        },
+        (error) => {
+          release()
+          throw error
+        },
+      )
+    }
+    release()
+    return outcome
+  }
+
   /**
    * Like {@link fetch}, but renders a plain-data result **without** building a Web `Response` — the
    * `@nifrajs/node` adapter serializes the returned primitives straight to the socket, skipping the undici
@@ -1801,8 +2019,13 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     source: RequestSource,
     platform?: Platform<EnvOf<Ctx>>,
   ): MaybePromise<NodeServeOutcome> {
-    // onResponse hooks transform a Response, so they force the Web path; wrap its result.
-    if (this.onResponseHooks.length > 0 || this.onResponseFinalizedHooks.length > 0) {
+    // onResponse hooks transform a Response, and the capacity gate wraps the Web response path — both
+    // force the Web path here (the gated `fetchSource` admits/sheds/releases); wrap its result.
+    if (
+      this.onResponseHooks.length > 0 ||
+      this.onResponseFinalizedHooks.length > 0 ||
+      this.capacityGate !== undefined
+    ) {
       const response = this.fetchSource(source, platform)
       return response instanceof Promise
         ? response.then((settled) => ({ kind: "response", response: settled }))
@@ -1838,10 +2061,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     const url = urlPartsOf(req.url)
     const match = this.wsRouter.find("GET", url.pathname)
     if (!match.found) return WS_PASS // upgrade header, no WS route here → normal routing decides
-    const params =
-      match.params === EMPTY_PARAMS || !url.pathname.includes("%")
-        ? match.params
-        : decodeParams(match.params)
+    // Inspect only captured values for escapes. Scanning the full pathname repeated work the router
+    // already did and made every plain dynamic route pay for unrelated static path bytes.
+    const params = match.params === EMPTY_PARAMS ? match.params : decodeParams(match.params)
     if (params === null) return { kind: "reject", response: jsonError(400, "malformed_path") }
     const handler = match.payload.handler
     // Non-null: wsRouteCount > 0 ⇒ ws() ran ⇒ the runtime created the registry.
@@ -1866,11 +2088,13 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     if (handler.upgrade === undefined) {
       return { kind: "upgrade", handler, data: undefined, pubsub }
     }
+    const upgradeSignal = getNeverAbortSignal()
     const ctx = new RequestContext(
       req,
       params,
       url.search,
-      getNeverAbortSignal(),
+      upgradeSignal,
+      createUnboundedRequestBudget(upgradeSignal),
       platform,
       this.maxBodyBytes,
     )
@@ -2042,38 +2266,95 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       return wrapResponse(jsonError(404, "not_found"))
     }
 
-    const params =
-      match.params === EMPTY_PARAMS || !url.pathname.includes("%")
-        ? match.params
-        : decodeParams(match.params)
+    // Inspect only captured values for escapes. Scanning the full pathname repeated work the router
+    // already did and made every plain dynamic route pay for unrelated static path bytes.
+    const params = match.params === EMPTY_PARAMS ? match.params : decodeParams(match.params)
     if (params === null) {
       return wrapResponse(jsonError(400, "malformed_path"))
     }
 
-    const entry = match.payload
-    // A per-request cancellation signal. Only allocate a real controller when a
-    // timeout is armed; otherwise share a never-aborting signal so the (common)
-    // no-timeout path pays nothing.
+    return this.runMatched(
+      source,
+      platform,
+      match.payload,
+      params,
+      url.search,
+      finalize,
+      wrapResponse,
+      onTimeout,
+      webFast,
+    )
+  }
+
+  /** Run a route that has already been matched by the runtime or Nifra's portable router. */
+  private runMatched<T>(
+    source: RequestSource,
+    platform: Platform | undefined,
+    entry: RouteEntry,
+    params: Record<string, string>,
+    search: string | undefined,
+    finalize: (result: unknown, set: CtxSet) => T,
+    wrapResponse: (response: Response) => T,
+    onTimeout: () => T,
+    webFast: boolean,
+  ): MaybePromise<T> {
+    // Translate the absolute wire deadline once, clamp it to local policy, then use the resulting
+    // duration for both c.signal and c.budget. A client can only shorten work, never extend it.
+    // Most requests have neither a local timeout nor a propagated deadline. Detect that case with
+    // one header lookup and skip policy validation, wall-clock sampling, and admission objects. A
+    // present wire deadline still goes through the full fail-closed parser/clamp below.
+    const admission = !this.acceptInboundDeadlines
+      ? this.requestTimeoutMs === 0
+        ? undefined
+        : {
+            ok: true as const,
+            inherited: false,
+            timeoutMs: this.requestTimeoutMs,
+            deadline: Math.floor(Date.now() + this.requestTimeoutMs),
+          }
+      : this.requestTimeoutMs === 0 && headerOf(source, NIFRA_DEADLINE_HEADER) === null
+        ? undefined
+        : admitDeadline(source.headers, this.deadlineAdmissionOptions)
+    if (admission !== undefined && !admission.ok) {
+      return wrapResponse(jsonError(admission.status, admission.reason))
+    }
+    const effectiveTimeoutMs = admission?.timeoutMs ?? 0
+
+    // Only allocate a controller for a finite budget; the historical no-timeout path remains
+    // allocation-light and exposes an unbounded budget that is never propagated on the wire.
     let controller: AbortController | undefined
     let signal = getNeverAbortSignal()
-    if (this.requestTimeoutMs > 0) {
+    if (effectiveTimeoutMs > 0) {
       controller = new AbortController()
       signal = controller.signal
     }
+    const budget =
+      controller === undefined
+        ? getUnboundedRequestBudget()
+        : createRequestBudget({ deadline: admission!.deadline as number, signal })
     // A bare route runs synchronously (no schema/derives/hooks); everything else keeps the full async
     // lifecycle. `runBare` returns a value directly for a sync handler — no promise.
     let outcome: MaybePromise<T>
     if (webFast && entry.fusedWeb !== undefined) {
       // Fused Web lane (bare route, no around): one closure end to end. Sound cast — webFast is
       // passed only by the `fetch` path, where T = Response by construction.
-      outcome = entry.fusedWeb(source, params, url.search, signal, platform) as MaybePromise<T>
+      outcome = entry.fusedWeb(
+        source,
+        params,
+        search,
+        signal,
+        budget,
+        platform,
+        false,
+      ) as MaybePromise<T>
     } else if (entry.contextlessBare) {
       outcome = this.runContextlessBare(
         entry,
         source,
         params,
-        url.search,
+        search,
         signal,
+        budget,
         platform,
         finalize,
         wrapResponse,
@@ -2084,8 +2365,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       const ctx = new RequestContext(
         source,
         params,
-        url.search,
+        search,
         signal,
+        budget,
         platform,
         this.maxBodyBytes,
       )
@@ -2118,7 +2400,16 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     // The request timeout only bounds work that is actually pending — a synchronous (bare) result is
     // already complete and can't time out, so it's returned as-is (no 503 race, no promise).
     if (controller !== undefined && outcome instanceof Promise) {
-      return this.withTimeout(outcome, controller, onTimeout)
+      const timedOut =
+        admission?.inherited === true
+          ? () => wrapResponse(jsonError(504, "deadline_exceeded"))
+          : onTimeout
+      return this.withTimeout(
+        outcome,
+        controller,
+        timedOut,
+        Math.max(0, Math.ceil(budget.remaining())),
+      )
     }
     return outcome
   }
@@ -2129,8 +2420,9 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     entry: RouteEntry,
     source: RequestSource,
     params: Record<string, string>,
-    search: string,
+    search: string | undefined,
     signal: AbortSignal,
+    budget: RequestBudget,
     platform: Platform | undefined,
     finalize: (result: unknown, set: CtxSet) => T,
     wrapResponse: (response: Response) => T,
@@ -2139,13 +2431,31 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     try {
       result = (entry.handler as unknown as ContextlessHandler)()
     } catch (err) {
-      return this.contextlessBareError(err, source, params, search, signal, platform, wrapResponse)
+      return this.contextlessBareError(
+        err,
+        source,
+        params,
+        search,
+        signal,
+        budget,
+        platform,
+        wrapResponse,
+      )
     }
     if (result instanceof Promise) {
       return result.then(
         (value) => finalize(value, EMPTY_RESPONSE_CONTROLS),
         (err) =>
-          this.contextlessBareError(err, source, params, search, signal, platform, wrapResponse),
+          this.contextlessBareError(
+            err,
+            source,
+            params,
+            search,
+            signal,
+            budget,
+            platform,
+            wrapResponse,
+          ),
       )
     }
     return finalize(result, EMPTY_RESPONSE_CONTROLS)
@@ -2155,13 +2465,22 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     err: unknown,
     source: RequestSource,
     params: Record<string, string>,
-    search: string,
+    search: string | undefined,
     signal: AbortSignal,
+    budget: RequestBudget,
     platform: Platform | undefined,
     wrapResponse: (response: Response) => T,
   ): T {
     if (err instanceof Response) return wrapResponse(err)
-    const ctx = new RequestContext(source, params, search, signal, platform, this.maxBodyBytes)
+    const ctx = new RequestContext(
+      source,
+      params,
+      search,
+      signal,
+      budget,
+      platform,
+      this.maxBodyBytes,
+    )
     this.logRequestError(err, ctx)
     return wrapResponse(jsonError(500, "internal_error"))
   }
@@ -2221,29 +2540,43 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       // `() => ...` can't observe the context — skip allocating one entirely (errors still build
       // one for the structured log, exactly like runContextlessBare).
       const contextlessHandler = handler as unknown as ContextlessHandler
-      return (source, params, search, signal, platform) => {
+      return (source, params, search, signal, budget, platform, nativeContext) => {
         let result: unknown
         try {
           result = contextlessHandler()
         } catch (err) {
           return logError(
             err,
-            new RequestContext(source, params, search, signal, platform, maxBodyBytes),
+            nativeContext
+              ? RequestContext.native(source, params, maxBodyBytes)
+              : new RequestContext(source, params, search, signal, budget, platform, maxBodyBytes),
           )
         }
         if (result instanceof Promise) {
           return result.then(fusedRespondNoSet, (err) =>
             logError(
               err,
-              new RequestContext(source, params, search, signal, platform, maxBodyBytes),
+              nativeContext
+                ? RequestContext.native(source, params, maxBodyBytes)
+                : new RequestContext(
+                    source,
+                    params,
+                    search,
+                    signal,
+                    budget,
+                    platform,
+                    maxBodyBytes,
+                  ),
             ),
           )
         }
         return fusedRespondNoSet(result)
       }
     }
-    return (source, params, search, signal, platform) => {
-      const ctx = new RequestContext(source, params, search, signal, platform, maxBodyBytes)
+    return (source, params, search, signal, budget, platform, nativeContext) => {
+      const ctx = nativeContext
+        ? RequestContext.native(source, params, maxBodyBytes)
+        : new RequestContext(source, params, search, signal, budget, platform, maxBodyBytes)
       if (decorations !== undefined) Object.assign(ctx, decorations)
       let result: unknown
       try {
@@ -2688,13 +3021,14 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     work: Promise<T>,
     controller: AbortController,
     onTimeout: () => T,
+    timeoutMs: number,
   ): Promise<T> {
     let timer: ReturnType<typeof setTimeout> | undefined
     const timeout = new Promise<T>((resolve) => {
       timer = setTimeout(() => {
         controller.abort()
         resolve(onTimeout())
-      }, this.requestTimeoutMs)
+      }, timeoutMs)
     })
     try {
       return await Promise.race([work, timeout])
@@ -2853,6 +3187,166 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     return readBoundedJsonSource(req, this.maxBodyBytes)
   }
 
+  /** Compile portable route registrations into Bun's native route table. Apps with request-rewrite
+   * hooks or WebSockets retain the single portable dispatcher because those features must run before
+   * route selection/upgrade. Named wildcards also stay on the fallback until Bun exposes their raw
+   * capture semantics; static and `:param` routes take the native lane. */
+  private buildBunNativeRoutes(): BunNativeRoutes | undefined {
+    if (this.onRequestHooks.length > 0 || this.wsRouteCount > 0) return undefined
+
+    const routes: BunNativeRoutes = Object.create(null) as BunNativeRoutes
+    const mayUseFusedNative =
+      this.requestTimeoutMs === 0 &&
+      this.onResponseHooks.length === 0 &&
+      this.onResponseFinalizedHooks.length === 0 &&
+      // The capacity gate must wrap every request; the fused lane bypasses fetchMatched, so enabling
+      // admission drops fusion (native matching stays) and routes through the gated matched lane.
+      this.capacityGate === undefined
+    const unboundedSignal = mayUseFusedNative ? getNeverAbortSignal() : undefined
+    const unboundedBudget = mayUseFusedNative ? getUnboundedRequestBudget() : undefined
+    let count = 0
+    for (const { method, path, entry } of this.rawEntries) {
+      if (path.includes("*")) continue
+      let methods = routes[path]
+      if (methods === undefined) {
+        methods = Object.create(null) as BunNativeMethodTable
+        routes[path] = methods
+      }
+      const paramNames = path
+        .split("/")
+        .filter((segment) => segment.charCodeAt(0) === 58 /* : */)
+        .map((segment) => segment.slice(1))
+      const fused = mayUseFusedNative ? entry.fusedWeb : undefined
+
+      if (fused !== undefined) {
+        // Deliberately choose deadline-aware vs zero-admission closures HERE instead of branching on
+        // `acceptInboundDeadlines` per request. JSC can then flatten the default closure through the
+        // handler + Response.json; retaining that route-invariant branch cost ~7% on a dynamic GET.
+        if (paramNames.length === 0) {
+          methods[method] = this.acceptInboundDeadlines
+            ? (request) =>
+                request.headers.get(NIFRA_DEADLINE_HEADER) !== null
+                  ? this.fetchMatched(request, entry, EMPTY_PARAMS)
+                  : fused(
+                      request,
+                      EMPTY_PARAMS,
+                      undefined,
+                      unboundedSignal as AbortSignal,
+                      unboundedBudget as RequestBudget,
+                      undefined,
+                      true,
+                    )
+            : (request) =>
+                fused(
+                  request,
+                  EMPTY_PARAMS,
+                  undefined,
+                  unboundedSignal as AbortSignal,
+                  unboundedBudget as RequestBudget,
+                  undefined,
+                  true,
+                )
+        } else if (paramNames.length === 1) {
+          const paramName = paramNames[0]!
+          const handler = entry.handler
+          const decorations = entry.hasDecorations ? entry.decorations : undefined
+          const fail = (error: unknown, ctx: RawContext): Response => {
+            if (error instanceof Response) return error
+            this.logRequestError(error, ctx)
+            return jsonError(500, "internal_error")
+          }
+          methods[method] = this.acceptInboundDeadlines
+            ? (request) => {
+                const params = (request as BunRequestWithParams).params ?? EMPTY_PARAMS
+                if (params[paramName]?.includes("\uFFFD") === true) return this.fetchSource(request)
+                if (request.headers.get(NIFRA_DEADLINE_HEADER) !== null) {
+                  return this.fetchMatched(request, entry, params)
+                }
+                const ctx = RequestContext.native(request, params, this.maxBodyBytes)
+                if (decorations !== undefined) Object.assign(ctx, decorations)
+                let result: unknown
+                try {
+                  result = handler(ctx)
+                } catch (error) {
+                  return fail(error, ctx)
+                }
+                return result instanceof Promise
+                  ? result.then(
+                      (value) => fusedRespond(value, ctx),
+                      (error) => fail(error, ctx),
+                    )
+                  : fusedRespond(result, ctx)
+              }
+            : (request) => {
+                const params = (request as BunRequestWithParams).params ?? EMPTY_PARAMS
+                if (params[paramName]?.includes("\uFFFD") === true) return this.fetchSource(request)
+                const ctx = RequestContext.native(request, params, this.maxBodyBytes)
+                if (decorations !== undefined) Object.assign(ctx, decorations)
+                let result: unknown
+                try {
+                  result = handler(ctx)
+                } catch (error) {
+                  return fail(error, ctx)
+                }
+                return result instanceof Promise
+                  ? result.then(
+                      (value) => fusedRespond(value, ctx),
+                      (error) => fail(error, ctx),
+                    )
+                  : fusedRespond(result, ctx)
+              }
+        } else {
+          methods[method] = this.acceptInboundDeadlines
+            ? (request) => {
+                const params = (request as BunRequestWithParams).params ?? EMPTY_PARAMS
+                if (hasReplacementParam(params)) return this.fetchSource(request)
+                return request.headers.get(NIFRA_DEADLINE_HEADER) !== null
+                  ? this.fetchMatched(request, entry, params)
+                  : fused(
+                      request,
+                      params,
+                      undefined,
+                      unboundedSignal as AbortSignal,
+                      unboundedBudget as RequestBudget,
+                      undefined,
+                      true,
+                    )
+              }
+            : (request) => {
+                const params = (request as BunRequestWithParams).params ?? EMPTY_PARAMS
+                if (hasReplacementParam(params)) return this.fetchSource(request)
+                return fused(
+                  request,
+                  params,
+                  undefined,
+                  unboundedSignal as AbortSignal,
+                  unboundedBudget as RequestBudget,
+                  undefined,
+                  true,
+                )
+              }
+        }
+      } else if (paramNames.length === 0) {
+        methods[method] = (request) => this.fetchMatched(request, entry, EMPTY_PARAMS)
+      } else if (paramNames.length === 1) {
+        const paramName = paramNames[0]!
+        methods[method] = (request) => {
+          const params = (request as BunRequestWithParams).params ?? EMPTY_PARAMS
+          if (params[paramName]?.includes("\uFFFD") === true) return this.fetchSource(request)
+          return this.fetchMatched(request, entry, params)
+        }
+      } else {
+        methods[method] = (request) => {
+          const params = (request as BunRequestWithParams).params ?? EMPTY_PARAMS
+          if (hasReplacementParam(params)) return this.fetchSource(request)
+          return this.fetchMatched(request, entry, params)
+        }
+      }
+      count += 1
+    }
+    return count === 0 ? undefined : routes
+  }
+
   /**
    * Start a `Bun.serve` instance bound to `port` (use `0` for an ephemeral port).
    *
@@ -2889,8 +3383,14 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         ? undefined
         : (getWsRuntime() as WsRuntime).bunHandlers(this.topics as TopicRegistry)
     const reusePort = options?.reusePort === true
+    const nativeRoutes = wsHandlers === undefined ? this.buildBunNativeRoutes() : undefined
     const running = (wsHandlers === undefined
-      ? Bun.serve({ port, reusePort, fetch: (req: Request) => this.fetch(req) })
+      ? Bun.serve({
+          port,
+          reusePort,
+          ...(nativeRoutes === undefined ? {} : { routes: nativeRoutes }),
+          fetch: (req: Request) => this.fetch(req),
+        })
       : Bun.serve<BunWsData>({
           port,
           reusePort,