@nifrajs/core 5.5.1 → 5.7.0

package/src/server/repeated-prefix.ts

@@ -0,0 +1,25 @@
+/** What {@link markRepeatedPrefix} recorded for a chunk. */
+export interface RepeatedPrefix {
+  /** Bytes the producer sends again in later responses and never changes. */
+  readonly source: Uint8Array
+  /** How many of `source`'s leading bytes the chunk starts with. */
+  readonly length: number
+}
+
+const prefixes = new WeakMap<Uint8Array, RepeatedPrefix>()
+
+/**
+ * Record that `chunk` starts with the first `length` bytes of `source`: bytes its producer sends again
+ * in later responses and never changes, such as a cached page shell. A response observer that
+ * transforms streamed bodies may keep its work on those bytes, keyed by `source`, and reuse it. It must
+ * check that the chunk still holds them, since a later reader may have written into the chunk.
+ */
+export function markRepeatedPrefix(chunk: Uint8Array, source: Uint8Array, length: number): void {
+  if (!Number.isSafeInteger(length) || length <= 0) return
+  if (length > chunk.byteLength || length > source.byteLength) return
+  prefixes.set(chunk, { source, length })
+}
+
+/** The repeated prefix {@link markRepeatedPrefix} recorded for `chunk`, if any. */
+export const repeatedPrefixOf = (chunk: Uint8Array): RepeatedPrefix | undefined =>
+  prefixes.get(chunk)

package/src/server/request-context.ts

@@ -12,6 +12,8 @@ import type { Platform } from "./context.ts"
 import { type CookieOptions, cookieNamePrefix, parseCookies, serializeCookie } from "./cookies.ts"
 import { headerObjectOf } from "./headers.ts"
 import { plainError } from "./http.ts"
+import { jsonResponse } from "./json-response.ts"
+import { jsonText } from "./json-text.ts"
 import type { ProtoPoisoning } from "./proto-guard.ts"
 import { searchOf } from "./query.ts"
 import { residentText, responseJsonContentType } from "./respond.ts"
@@ -342,14 +344,14 @@ export class RequestContext implements RawContext {
       // (`undefined`, a function, a symbol) - exactly the case where `Response.json` throws, so it
       // gets the throw rather than an invented body. The content-type is the runtime's own, read
       // off `Response.json` once, so a deferred response carries the same one byte for byte.
-      const text = defer === undefined ? undefined : (JSON.stringify(body) as string | undefined)
+      const text = defer === undefined ? undefined : (jsonText(body) as string | undefined)
       const headers =
         text === undefined ? undefined : ownHeaderRecord(i?.headers, responseJsonContentType())
       if (defer !== undefined && text !== undefined && headers !== undefined) {
         reply = defer(text, i?.status ?? 200, headers)
       }
     }
-    reply ??= markResidentBody(Response.json(body, i))
+    reply ??= markResidentBody(jsonResponse(body, i))
     // Remembered so a response contract holds the value to the route's schema: this is the
     // framework's JSON helper, not a raw-Response escape hatch.
     this.jsonBody = body
@@ -433,9 +435,7 @@ async function readBoundedBodyOrThrow(
 ): Promise<Uint8Array> {
   const r = await readBoundedBytes(req, maxBytes ?? maxBodyBytes)
   if (r.ok) return r.bytes
-  throw r.status === 413
-    ? plainError(413, "payload_too_large")
-    : plainError(400, "invalid_content_length")
+  throw plainError(r.status, r.error)
 }
 
 /** Backs `c.boundedJson`: `readBoundedJsonSource`, throwing its flat 400/413 on failure. */

package/src/server/respond.ts

@@ -7,12 +7,15 @@
 import { hasResidentBody, markResidentBody, residentBodiesRecorded } from "../mount.ts"
 import { NODE_BRIDGE_MARKER_KEYS } from "./bridge-markers.ts"
 import { plainError } from "./http.ts"
+import { jsonResponse } from "./json-response.ts"
+import { jsonText } from "./json-text.ts"
 import {
   CONTEXT_REQUEST,
   CONTEXT_SET,
   EMPTY_RESPONSE_CONTROLS,
   type HandlerResult,
   isResponseResult,
+  JSON_CONTENT_TYPE,
   type PlainRender,
   plainRenderHeaders,
   type ResponseResult,
@@ -41,10 +44,9 @@ function plainRenderSet(plain: PlainRender, set: CtxSet): CtxSet {
   } as CtxSet
 }
 
-// Keep the fast JSON respond path byte-identical to `Response.json` without probing it at module
-// scope: workerd forbids `Response.json()` during startup. A shared `Headers` is safe to reuse
-// across responses: the Response constructor copies `init.headers` into its own list.
-const JSON_CONTENT_TYPE = "application/json;charset=utf-8"
+// Keep the fast JSON respond path byte-identical to `Response.json` (see `JSON_CONTENT_TYPE`). A
+// shared `Headers` is safe to reuse across responses: the Response constructor copies
+// `init.headers` into its own list.
 const JSON_CT_HEADERS = new Headers({ "content-type": JSON_CONTENT_TYPE })
 const JSON_INIT_200: ResponseInit = { status: 200, headers: JSON_CT_HEADERS }
 
@@ -212,13 +214,14 @@ function denoResponseWithJsonBody(
  * it exactly as `withJsonContentType` did.
  */
 function jsonResponseWithOwnHeaders(
-  result: object,
+  result: unknown,
   status: number,
   headers: Record<string, string>,
+  unstamped: boolean,
 ): Response {
-  const response = status === 200 ? Response.json(result) : Response.json(result, { status })
+  const response = jsonResponse(result, status === 200 ? undefined : { status })
   for (const name of Object.keys(headers)) response.headers.set(name, headers[name]!)
-  return withBody(response)
+  return withBody(response, unstamped)
 }
 
 // The framework-buffered-body marker shared with the Node adapter: a Response carrying it exposes
@@ -254,9 +257,9 @@ export function rememberRenderedResponse(response: Response, hasBody: boolean):
   return response
 }
 
-/** `rememberRenderedResponse` for a Response the framework built around a body it serialized. */
-function withBody(response: Response): Response {
-  return markResidentBody(response)
+/** Record serialized bodies when response hooks or an in-process client can consume the mark. */
+function withBody(response: Response, unstamped = false): Response {
+  return unstamped && !residentBodiesRecorded ? response : markResidentBody(response)
 }
 
 const HEADER_MUTABILITY_PROBE = "x-nifra-header-probe"
@@ -488,8 +491,9 @@ function tagged(
   response: Response,
   body: string,
   tagResponseBody: ResponseBodyTagOption,
+  unstamped = false,
 ): Response {
-  withBody(response)
+  withBody(response, unstamped)
   return tagResponseBody === false || tagResponseBody === undefined
     ? response
     : markTaggedResponse(
@@ -499,9 +503,16 @@ function tagged(
       )
 }
 
-/** 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. */
+/** A plain 200 JSON response. On Bun and Deno the native `Response.json` beats a hand-inlined
+ * stringify + Response construction; on Node undici's is 18-26% slower than stringify into the
+ * prebuilt init. Both keep the exact body/content-type contract. */
+function plainJsonResponse(result: object): Response {
+  // `undefined` from stringify (a `toJSON` returning nothing) keeps `Response.json`'s TypeError.
+  const body = IS_BUN || IS_DENO ? undefined : (jsonText(result) as string | undefined)
+  return body === undefined ? jsonResponse(result) : new Response(body, JSON_INIT_200)
+}
+
+/** Fused-lane respond when `c.set` is untouched; keep the generic fallback for non-JSON values. */
 export function fusedRespondNoSet(
   result: unknown,
   tagResponseBody: ResponseBodyTagOption = false,
@@ -527,7 +538,7 @@ export function fusedRespondNoSet(
     !(result instanceof Response) &&
     !isResponseResult(result)
   ) {
-    const response = Response.json(result)
+    const response = plainJsonResponse(result)
     return residentBodiesRecorded ? markResidentBody(response) : response
   }
   if (
@@ -543,7 +554,7 @@ export function fusedRespondNoSet(
     // Deno the tier's only saving here is the response walk itself; every other runtime keeps the
     // one-call prebuilt init below.
     if (statics !== undefined && IS_DENO && !tagResponseBody) {
-      const response = Response.json(result)
+      const response = jsonResponse(result)
       // Indexed for the same reason as `applyStaticDefaults`: pair destructuring is a second
       // iterator walk per header.
       for (let i = 0; i < statics.entries.length; i++) {
@@ -556,7 +567,7 @@ export function fusedRespondNoSet(
     // content-type, so this lane still constructs the response in one call - the whole point of
     // declaring headers statically instead of writing them per response.
     if (tagResponseBody || statics !== undefined) {
-      const body = JSON.stringify(result) as string | undefined
+      const body = jsonText(result) as string | undefined
       // Each shape carries the content-type of the lane it stands in for: the framework's own for the
       // tagging path this branch already owned, and `Response.json`'s for the construction below that
       // the static tier replaces. They differ on Deno, and a declared header must not change one.
@@ -579,8 +590,8 @@ export function fusedRespondNoSet(
     }
     return withBody(
       statics === undefined
-        ? Response.json(result)
-        : Response.json(result, statics.responseJsonInit200()),
+        ? plainJsonResponse(result)
+        : jsonResponse(result, statics.responseJsonInit200()),
     )
   }
   return toResponse(
@@ -605,13 +616,14 @@ export function fusedRespond(
   const request = unstamped ? undefined : ctx[CONTEXT_REQUEST]
   if (set === undefined)
     return fusedRespondNoSet(result, tagResponseBody, statics, unstamped, request)
-  return toResponse(result as HandlerResult, set, tagResponseBody, statics, request)
+  return toResponse(result as HandlerResult, set, tagResponseBody, statics, request, unstamped)
 }
 
 /**
  * Render a handler's result. `request` is the request being answered, given when response hooks will
  * write next: a copy or body-less response built here is then recorded as that request's own, so the
  * hooks write it in place instead of copying it again.
+ * `unstamped` is the caller's proof that no response hook follows; unknown callers keep the mark.
  */
 export function toResponse(
   result: HandlerResult,
@@ -619,6 +631,7 @@ export function toResponse(
   tagResponseBody: ResponseBodyTagOption = false,
   statics?: StaticResponseHeaders,
   request?: Request,
+  unstamped = false,
 ): Response {
   if (isResponseResult(result)) {
     const plain = result.plain
@@ -632,6 +645,7 @@ export function toResponse(
         tagResponseBody,
         statics,
         request,
+        unstamped,
       )
     }
     // A buffered page is built from the body it reports, so the bytes its hooks see are the ones sent.
@@ -664,7 +678,7 @@ export function toResponse(
       typeof tagResponseBody === "object" ? tagResponseBody : undefined,
     )
   }
-  return renderValue(result, set, tagResponseBody, statics, request)
+  return renderValue(result, set, tagResponseBody, statics, request, unstamped)
 }
 
 /**
@@ -694,6 +708,7 @@ function renderValue(
   tagResponseBody: ResponseBodyTagOption,
   statics: StaticResponseHeaders | undefined,
   request: Request | undefined,
+  unstamped = false,
 ): Response {
   // The static tier only changes WHICH prebuilt header shape the branches below reach for: the
   // request's own headers are folded on top of the declared defaults once, here.
@@ -723,14 +738,14 @@ function renderValue(
     typeof result === "object" &&
     result !== null
   ) {
-    return jsonResponseWithOwnHeaders(result, status, own)
+    return jsonResponseWithOwnHeaders(result, status, own, unstamped)
   }
   if (own === undefined && result !== undefined) {
     // Fast respond (profiled ~50 ns/req faster on every plain-JSON return): `JSON.stringify` + a
     // prebuilt init beats `Response.json`'s internal init handling. Output is byte-identical -
     // same body bytes, same probed content-type. `undefined` from stringify (a function/symbol
     // result) delegates to Response.json so its TypeError contract stays the single source.
-    const body = JSON.stringify(result) as string | undefined
+    const body = jsonText(result) as string | undefined
     if (body !== undefined) {
       const init: ResponseInit =
         status === 200
@@ -743,13 +758,14 @@ function renderValue(
           : staticJsonResponse(body, status, statics, JSON_CONTENT_TYPE, init),
         body,
         tagResponseBody,
+        unstamped,
       )
     }
   }
   const init: ResponseInit = headers === undefined ? { status } : { status, headers }
   if (result === undefined) return ownedBy(new Response(null, init), request)
   if (tagResponseBody) {
-    const body = JSON.stringify(result) as string | undefined
+    const body = jsonText(result) as string | undefined
     if (body !== undefined) {
       const response =
         IS_DENO && !(headers instanceof Headers)
@@ -757,7 +773,7 @@ function renderValue(
               body,
               status,
               headers as Record<string, string>,
-              JSON_CT_HEADERS.get("content-type") ?? "application/json;charset=utf-8",
+              JSON_CONTENT_TYPE,
             )
           : // lgtm [js/stack-trace-exposure] the serialized body is not a caught error stack.
             new Response(body, { status, headers: withJsonContentType(headers) })
@@ -769,10 +785,11 @@ function renderValue(
     }
   }
   if (IS_DENO && headers !== undefined && !(headers instanceof Headers)) {
-    const body = JSON.stringify(result) as string | undefined
-    if (body !== undefined) return withBody(denoResponseWithJsonBody(body, status, headers))
+    // Deno's own `Response.json` then header writes measured ~10% under stringify, construction and
+    // the same writes plus a content-type one; a declared content-type still overrides the default.
+    return jsonResponseWithOwnHeaders(result, status, headers, unstamped)
   }
-  return withBody(Response.json(result, init))
+  return withBody(jsonResponse(result, init), unstamped)
 }
 
 // Add a JSON content-type without pre-building a `Headers` instance just to check-and-set one key:
@@ -787,12 +804,12 @@ function withJsonContentType(
 ): Record<string, string> | Headers {
   if (headers === undefined) return JSON_CT_HEADERS
   if (headers instanceof Headers) {
-    if (!headers.has("content-type")) headers.set("content-type", "application/json;charset=utf-8")
+    if (!headers.has("content-type")) headers.set("content-type", JSON_CONTENT_TYPE)
     return headers
   }
   return Object.hasOwn(headers, "content-type")
     ? headers
-    : { ...headers, "content-type": "application/json;charset=utf-8" }
+    : { ...headers, "content-type": JSON_CONTENT_TYPE }
 }
 
 /** Headers that describe a Response's body or its framing: a `c.set` value for one describes a body

package/src/server/response-contract-lane.ts

@@ -32,13 +32,23 @@
  * carries its JSON Schema as `jsonSchema` (every `t` schema does) CAN list its declared keys, so for
  * those the payload is projected onto the declared shape before it is validated.
  *
+ * ## What is judged is what is written
+ *
+ * `JSON.stringify` writes what a `toJSON` hook returns, not the fields a validator reads off the
+ * object. So a value's hooks are applied first, as the serializer would, and that result is validated
+ * and sent: a class whose `toJSON` adds a private field fails a closed schema instead of passing on its
+ * public ones. `strip` keeps the declared fields of what the hook writes, so a hook that writes `id`
+ * from private state keeps it. A `Date` is the exception; it stays a `Date` for a date schema and is
+ * written as its ISO string.
+ *
  * ## What enforcement costs
  *
  * Less than it looks like it should. With a compiled validator (`@nifrajs/schema`'s `t` compiles at
  * construction; zod/valibot equivalents are similarly cheap), the check itself measures in the
  * ~100ns-per-response range - on a realistic middleware-carrying route, enforce mode benchmarks
- * within measurement noise of the same route with no contract at all, on Bun and Node alike. The
- * one real cost is structural: a contracted route cannot take the bare-route fused lane, because
+ * within measurement noise of the same route with no contract at all, on Bun and Node alike. Looking
+ * for `toJSON` hooks visits every object in the payload, about 13 ns each, so a 50-row list pays near
+ * 0.7 us. The other cost is structural: a contracted route cannot take the bare-route fused lane, because
  * the check needs the handler's VALUE before it becomes bytes. A route with any middleware, derive,
  * or lifecycle hook has already left that lane, so for the routes that look like production the
  * contract is effectively free - declare it.
@@ -49,6 +59,7 @@ import {
   type StandardSchemaV1,
 } from "../schema/standard.ts"
 import { INSTALL_RESPONSE_CONTRACT } from "./install.ts"
+import { jsonText } from "./json-text.ts"
 import type { IdentityPlugin } from "./plugin.ts"
 import { isResponseResult, status } from "./runtime-core.ts"
 import type { AnyServer } from "./server.ts"
@@ -166,7 +177,12 @@ function compileProjector(node: unknown): Projector | undefined {
     const item = Array.isArray(items) ? undefined : compileProjector(items)
     return item === undefined
       ? undefined
-      : (value) => (Array.isArray(value) ? value.map(item) : value)
+      : (value) => {
+          if (!Array.isArray(value)) return value
+          const out: unknown[] = []
+          for (let i = 0; i < value.length; i++) out.push(item(writtenAt(value[i], i)))
+          return out
+        }
   }
   if (type !== "object") return undefined
   const properties = objectField(schema, "properties") ?? {}
@@ -196,7 +212,7 @@ function compileProjector(node: unknown): Projector | undefined {
     for (const key of closed ? keys : nested.keys()) {
       if (!hasField(value, key)) continue
       const projector = nested.get(key)
-      define(out, key, projector === undefined ? value[key] : projector(value[key]))
+      define(out, key, projector === undefined ? value[key] : projector(writtenAt(value[key], key)))
     }
     if (patterns.length > 0) projectPatternKeys(value, out, declared, patterns, closed)
     return out
@@ -340,7 +356,8 @@ function projectPatternKeys(
         matches++
       }
     if (matches === 0) continue
-    if (matches === 1 && projector !== undefined) define(out, key, projector(value[key]))
+    if (matches === 1 && projector !== undefined)
+      define(out, key, projector(writtenAt(value[key], key)))
     else if (closed) define(out, key, value[key])
   }
 }
@@ -352,6 +369,101 @@ function define(out: Record<string, unknown>, key: string, value: unknown): void
   else out[key] = value
 }
 
+const DATE_TO_JSON = Date.prototype.toJSON
+
+// Deeper than this, the copying walk takes over with its own cycle check.
+const MAX_HOOK_SCAN_DEPTH = 64
+
+/** Whether `value` holds a `toJSON` hook other than a `Date`'s. Allocates nothing: most payloads
+ * have none, and this is the price every contracted response pays. */
+function hasHook(value: object, depth: number): boolean {
+  if (depth > MAX_HOOK_SCAN_DEPTH) return true
+  const hook: unknown = Reflect.get(value, "toJSON")
+  if (typeof hook === "function") return !(hook === DATE_TO_JSON && value instanceof Date)
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      const item: unknown = value[i]
+      if (typeof item === "object" && item !== null && hasHook(item, depth + 1)) return true
+    }
+    return false
+  }
+  // Inherited enumerable keys are scanned too; that only ever sends a value to the copying walk.
+  for (const key in value) {
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: `key` was enumerated from `value`; `Reflect.get` here halves the speed of this for-in.
+    const field: unknown = (value as Record<string, unknown>)[key]
+    if (typeof field === "object" && field !== null && hasHook(field, depth + 1)) return true
+  }
+  return false
+}
+
+/**
+ * What `JSON.stringify` writes for `value`: every `toJSON` hook applied as the serializer applies it,
+ * so the contract judges the bytes that go out rather than fields a hook then replaces. Copies only the
+ * containers above a hook. A `Date` keeps its object, since its own hook writes nothing but the ISO
+ * string a date schema declares.
+ */
+const wireValueOf = (value: unknown): unknown =>
+  typeof value === "object" && value !== null && hasHook(value, 0)
+    ? wireValue(value, "", [])
+    : value
+
+const wireValue = (value: unknown, key: string | number, path: object[]): unknown =>
+  wireChildren(writtenAt(value, key), path)
+
+/** `value` as the serializer takes it under `key`: its own hook applied, its fields still as they are. */
+function writtenAt(value: unknown, key: string | number): unknown {
+  if (typeof value !== "object" || value === null) return value
+  const hook: unknown = Reflect.get(value, "toJSON")
+  if (typeof hook !== "function" || (hook === DATE_TO_JSON && value instanceof Date)) return value
+  return fieldsOf(Reflect.apply(hook, value, [String(key)]))
+}
+
+/**
+ * The serializer calls one hook per value, so a hook's result that has a hook of its own is written
+ * by its fields. Copying them out keeps that second hook from running when the checked value is sent.
+ */
+function fieldsOf(value: unknown): unknown {
+  if (typeof value !== "object" || value === null) return value
+  if (typeof Reflect.get(value, "toJSON") !== "function") return value
+  if (Array.isArray(value)) return Array.from({ length: value.length }, (_, i): unknown => value[i])
+  const fields: Record<string, unknown> = {}
+  for (const name of Object.keys(value))
+    if (name !== "toJSON") define(fields, name, Reflect.get(value, name))
+  return fields
+}
+
+function wireChildren(value: unknown, path: object[]): unknown {
+  // A cycle is left as it is for `JSON.stringify` to refuse.
+  if (typeof value !== "object" || value === null || path.includes(value)) return value
+  path.push(value)
+  if (Array.isArray(value)) {
+    let items: unknown[] | undefined
+    for (let i = 0; i < value.length; i++) {
+      const item: unknown = value[i]
+      const written = wireValue(item, i, path)
+      if (written !== item) items ??= value.slice(0, i)
+      if (items !== undefined) items[i] = written
+    }
+    path.pop()
+    return items ?? value
+  }
+  const keys = Object.keys(value)
+  let out: Record<string, unknown> | undefined
+  let index = 0
+  for (const name of keys) {
+    const field: unknown = Reflect.get(value, name)
+    const written = wireValue(field, name, path)
+    if (written !== field && out === undefined) {
+      out = {}
+      for (const earlier of keys.slice(0, index)) define(out, earlier, Reflect.get(value, earlier))
+    }
+    if (out !== undefined) define(out, name, written)
+    index++
+  }
+  path.pop()
+  return out ?? value
+}
+
 const MAX_STRIPPED_NAMES = 20
 const MAX_NAME_LENGTH = 64
 const MAX_REPORTED_SETS = 32
@@ -435,7 +547,7 @@ const schemaFor = (definition: ResponseContractDefinition, code: number) =>
 function reserialize(reply: Response, value: unknown): Response {
   const headers = new Headers(reply.headers)
   headers.delete("content-length")
-  return new Response(JSON.stringify(value), {
+  return new Response(jsonText(value), {
     status: reply.status,
     statusText: reply.statusText,
     headers,
@@ -523,10 +635,21 @@ function validateContract(
   replace: (value: unknown) => unknown,
 ): ResponseContractOutcome | Promise<ResponseContractOutcome> {
   const project = policy.strip ? projectorOf(schema) : undefined
-  const settled = schema["~standard"].validate(project === undefined ? payload : project(payload))
+  // Naming what was stripped compares against everything the payload writes, so it walks it whole.
+  const before =
+    project === undefined || policy.report !== undefined || mode === "warn"
+      ? wireValueOf(payload)
+      : payload
+  // The projection applies the hook of each value it descends into and reads only declared fields,
+  // so a quiet strip never enumerates the payload's own keys. What it copies whole is walked after.
+  const sent = project === undefined ? before : wireValueOf(project(writtenAt(before, "")))
+  const settled = schema["~standard"].validate(sent)
+  // When hooks wrote the payload, `warn` sends what they wrote here rather than calling them again,
+  // so a hook that answers differently on a second call cannot send what was not judged.
+  const shown = mode === "warn" && before !== payload ? replace(before) : served
   return settled instanceof Promise
-    ? settled.then((r) => interpret(r, payload, served, mode, replace, policy.report))
-    : interpret(settled, payload, served, mode, replace, policy.report)
+    ? settled.then((r) => interpret(r, before, shown, mode, replace, policy.report))
+    : interpret(settled, before, shown, mode, replace, policy.report)
 }
 
 function interpret(

package/src/server/route-template.ts

@@ -0,0 +1,24 @@
+import { type Method, Router } from "../router/router.ts"
+import type { RouteDescriptor } from "./server-types.ts"
+
+/**
+ * A request's matched route template (`/users/:id`, never `/users/42`), or `undefined` when no route
+ * serves it. The matcher is built on first use: by serving time every route is registered, so
+ * `app.routes()` is complete, where building it when a plugin is applied would miss later routes.
+ */
+export function routeTemplateOf(app: {
+  routes(): ReadonlyArray<RouteDescriptor>
+}): (method: string, path: string) => string | undefined {
+  let matcher: Router<string> | undefined
+  return (method, path) => {
+    if (matcher === undefined) {
+      matcher = new Router<string>()
+      for (const route of app.routes()) {
+        // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: every registered route's method is one this router already accepted when the app registered it.
+        matcher.add(route.method as Method, route.path, route.path)
+      }
+    }
+    const found = matcher.find(method, path)
+    return found.found ? found.payload : undefined
+  }
+}

package/src/server/runtime-core.ts

@@ -6,11 +6,21 @@
  */
 import { createUnboundedRequestBudget, type RequestBudget } from "../budget.ts"
 import { NODE_BRIDGE_MARKER_KEYS } from "./bridge-markers.ts"
+import { jsonText } from "./json-text.ts"
 import type { CtxSet, RequestSource } from "./server.ts"
 
 /** A handler returns a `Response` (used as-is) or any value (serialized to JSON). */
 export type HandlerResult = Response | unknown
 
+/**
+ * The Content-Type the runtime's own `Response.json` writes, which every JSON nifra renders on the Web
+ * lanes carries too, so a handler's JSON and the framework's envelopes (built with `Response.json`)
+ * agree on one runtime. Bun adds `;charset=utf-8`; Deno, workerd and undici do not. Named rather than
+ * probed: workerd forbids `Response.json()` while a module loads.
+ */
+export const JSON_CONTENT_TYPE =
+  "Bun" in globalThis ? "application/json;charset=utf-8" : "application/json"
+
 export const RESPONSE_RESULT = Symbol.for(NODE_BRIDGE_MARKER_KEYS.responseResult)
 export const CONTEXT_SET = Symbol("nifra.context.set")
 export const CONTEXT_SEARCH = Symbol("nifra.context.search")
@@ -178,8 +188,8 @@ export function status(
     toResponse(): Response {
       const headers: Record<string, string> = { ...init?.headers }
       if (body === undefined) return new Response(null, { status: code, headers })
-      headers["content-type"] ??= "application/json;charset=utf-8"
-      return new Response(JSON.stringify(body), { status: code, headers })
+      headers["content-type"] ??= JSON_CONTENT_TYPE
+      return new Response(jsonText(body), { status: code, headers })
     },
   } as StatusResponse<number, unknown>
 }

package/src/server/server-types.ts

@@ -91,8 +91,9 @@ export interface ServerOptions {
   readonly trustBodyFraming?: boolean
   /**
    * Max inbound WebSocket message size (bytes). A larger message never reaches the handler and the
-   * socket closes with `1009`; when Bun's own frame limit refuses it, Bun drops the connection and the
-   * client sees `1006`, while the `close` handler still gets `1009`. Default: `maxBodyBytes` (1 MB).
+   * socket closes with `1009`; when Bun's own frame limit refuses it, Bun up to 1.4.3 drops the
+   * connection (the client sees `1006`) and Bun 1.4.4 sends `1009`, while the `close` handler gets
+   * `1009` either way. Default: `maxBodyBytes` (1 MB).
    * Bun and Node stop buffering at the cap, so a huge frame is never held in memory; on Bun a mounted
    * app's smaller cap, and on Deno and Workers every cap, is checked after the runtime has buffered
    * the whole message.
@@ -124,10 +125,9 @@ export interface ServerOptions {
   readonly maxInboundDeadlineMs?: number
   /**
    * When `listen()`ing, install SIGTERM/SIGINT handlers that gracefully `stop()`. Default false.
-   * `{ drainMs }` sets how long in-flight requests get to finish before the stop forces them closed
-   * (default 10_000) - keep it under the platform's kill grace period (`docker stop` waits 10 s).
+   * The object form is passed to `stop()`: see {@link StopOptions}.
    */
-  readonly gracefulSignals?: boolean | { readonly drainMs?: number }
+  readonly gracefulSignals?: boolean | StopOptions
   /**
    * 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.
@@ -253,9 +253,21 @@ export interface MountFetchOptions {
   readonly opaque?: string | OpaqueMountDeclaration
 }
 
-/** A callback awaited after the Bun server has drained and stopped. */
+/** A callback a server awaits while it stops: `onStopping` when it begins, `onStop` after the drain. */
 export type StopHook = () => MaybePromise<void>
 
+/** How `stop()` winds a listening server down. */
+export interface StopOptions {
+  /** How long in-flight requests get to finish before the stop forces them closed. Default 10_000. */
+  readonly drainMs?: number
+  /**
+   * How long the server keeps serving after `stop()` began, before it drains: the time a load
+   * balancer takes to see readiness fail and route elsewhere. Default 0. Keep `delayMs + drainMs`
+   * under the platform's kill grace period (`docker stop` waits 10 s, Kubernetes 30 s).
+   */
+  readonly delayMs?: number
+}
+
 /**
  * MCP tool safety hints, surfaced in `tools/list`, that tell an agent how risky a `.tool()` call is - so it
  * can decide whether to auto-invoke or confirm first. All optional; an omitted hint means "unknown". Mirrors