@nifrajs/core 5.6.0 → 5.8.0

package/src/server/answer-step.ts

@@ -0,0 +1,68 @@
+import { RouteConfigError } from "../errors.ts"
+import type { RouteSchema } from "./context.ts"
+
+/**
+ * A schema's own step around what answers a route, for a schema that changes how the answer it
+ * describes is written: `t.bytes()` has every `Uint8Array` leave as base64. It sits on the schema's
+ * `validate`, so a spread copy keeps it, and is read once, at registration.
+ */
+const ANSWER_STEP = Symbol.for("nifra.schema.answerStep")
+
+/** The part of a request's context a step reads: the `c.json(...)` reply it made, and its value. */
+export interface JsonReplyContext {
+  readonly jsonReply?: Response | undefined
+  readonly jsonBody?: unknown
+  json(body: unknown, init?: ResponseInit): Response
+}
+
+/**
+ * What can answer a route: its handler, and each hook whose return value takes the handler's place -
+ * a `beforeHandle` that answers first, an `afterHandle` that replaces the answer, an `onError` that
+ * answers an error. Each takes the request's context, as a `JsonReplyContext`.
+ */
+export interface AnswerStages {
+  readonly handler: (context: never) => unknown
+  readonly beforeHandle: readonly ((context: never) => unknown)[]
+  readonly afterHandle: readonly ((result: unknown, context: never) => unknown)[]
+  readonly onError: readonly ((error: unknown, context: never) => unknown)[]
+}
+
+export interface AnswerStep {
+  /** Why the schema cannot describe a request or an event stream, and what to use there instead. */
+  readonly misplaced: string
+  /** `stages`, each wrapped so what it answers is written the schema's way. */
+  readonly wrap: <S extends AnswerStages>(stages: S) => S
+}
+
+function stepOf(schema: object | undefined): AnswerStep | undefined {
+  const validate = schema === undefined ? undefined : Reflect.get(schema, "~standard")?.validate
+  return typeof validate === "function" ? Reflect.get(validate, ANSWER_STEP) : undefined
+}
+
+const REQUEST_FIELDS = ["params", "headers", "cookies", "query", "body", "sse"] as const
+
+/** `stages` wrapped by each step its route's `response` and `errors` schemas carry. */
+export function withAnswerSteps<S extends AnswerStages>(
+  schema: RouteSchema | undefined,
+  method: string,
+  path: string,
+  stages: S,
+): S {
+  if (schema === undefined) return stages
+  for (const field of REQUEST_FIELDS) {
+    const step = stepOf(schema[field])
+    if (step !== undefined) {
+      throw new RouteConfigError(
+        "RESPONSE_ONLY_SCHEMA",
+        `route ${method} ${path}, \`${field}\`: ${step.misplaced}`,
+      )
+    }
+  }
+  const steps = new Set<AnswerStep["wrap"]>()
+  for (const answer of [schema.response, ...Object.values(schema.errors ?? {})]) {
+    const step = stepOf(answer)
+    if (step !== undefined) steps.add(step.wrap)
+  }
+  for (const wrap of steps) stages = wrap(stages)
+  return stages
+}

package/src/server/base64-answers.ts

@@ -0,0 +1,138 @@
+/**
+ * Bytes in a JSON answer, written as base64.
+ *
+ * `JSON.stringify` writes a `Uint8Array` as `{"0":1,"1":2,...}`, and nothing about that throws, so
+ * finding one costs a walk of every answer. Only a route that asks pays for that walk: `t.bytes()` in
+ * its `response` or `errors` has core hand {@link withBase64Bytes} the route's handler and the hooks
+ * that can answer in its place, and every `Uint8Array` in what any of them returns or throws as an
+ * answer becomes a base64 string before a later hook, contract or writer sees it. Nothing in the
+ * server imports this module, so an app that never declares the field never bundles it.
+ */
+import { tagStandIn } from "../internal/hook-origins.ts"
+import type { AnswerStages, JsonReplyContext } from "./answer-step.ts"
+import { isResponseResult, status } from "./runtime-core.ts"
+
+// Deeper than any real payload.
+const MAX_DEPTH = 64
+// So `String.fromCharCode(...)` never overflows the call stack.
+const CHUNK = 0x8000
+
+function base64(bytes: Uint8Array): string {
+  let binary = ""
+  for (let i = 0; i < bytes.length; i += CHUNK)
+    binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK))
+  return btoa(binary)
+}
+
+function define(out: object, key: string, value: unknown): void {
+  // `out[key] = value` for "__proto__" would replace the prototype instead of adding the field.
+  Object.defineProperty(out, key, { value, enumerable: true, writable: true, configurable: true })
+}
+
+/**
+ * `value` with each `Uint8Array` as base64, copying only the containers above one. A container already
+ * on the walk's path is left as it is, so a cycle costs one step, as it does `JSON.stringify`, which
+ * then refuses it.
+ */
+function encoded(value: unknown, depth: number, path: Set<object>): unknown {
+  if (value instanceof Uint8Array) return base64(value)
+  if (typeof value !== "object" || value === null || depth > MAX_DEPTH || path.has(value))
+    return value
+  // A `Date` (or any value with a hook) writes itself.
+  if (typeof Reflect.get(value, "toJSON") === "function") return value
+  path.add(value)
+  try {
+    if (Array.isArray(value)) {
+      let out: unknown[] | undefined
+      for (let i = 0; i < value.length; i++) {
+        const next = encoded(value[i], depth + 1, path)
+        if (next === value[i]) continue
+        out ??= [...value]
+        out[i] = next
+      }
+      return out ?? value
+    }
+    let out: object | undefined
+    for (const key of Object.keys(value)) {
+      const item: unknown = Reflect.get(value, key)
+      const next = encoded(item, depth + 1, path)
+      if (next === item) continue
+      out ??= { ...value }
+      define(out, key, next)
+    }
+    return out ?? value
+  } finally {
+    path.delete(value)
+  }
+}
+
+const encodedBody = (body: unknown): unknown => encoded(body, 0, new Set())
+
+/** An answer with its bytes encoded. A raw `Response` is left alone; a `c.json(...)` reply is rebuilt
+ * from the value it was made from, keeping its status and headers. */
+function encodedAnswer(answer: unknown, c: JsonReplyContext): unknown {
+  if (answer instanceof Response) {
+    if (answer !== c.jsonReply) return answer
+    const body = encodedBody(c.jsonBody)
+    if (body === c.jsonBody) return answer
+    const headers = new Headers(answer.headers)
+    headers.delete("content-length")
+    return c.json(body, { status: answer.status, headers })
+  }
+  if (isResponseResult(answer)) {
+    const plain = answer.plain
+    if (plain === undefined) return answer
+    const body = encodedBody(plain.body)
+    if (body === plain.body) return answer
+    return status(
+      plain.status,
+      body,
+      plain.headers === undefined ? undefined : { headers: plain.headers },
+    )
+  }
+  return encodedBody(answer)
+}
+
+/** A thrown answer (`status(...)`, `c.json(...)`) is encoded too; any other throw passes untouched. */
+const encodedThrow = (thrown: unknown, c: JsonReplyContext): unknown =>
+  thrown instanceof Response || isResponseResult(thrown) ? encodedAnswer(thrown, c) : thrown
+
+/**
+ * `stage` with what it returns or throws as an answer encoded. Its context is argument `at`; an
+ * `undefined` return (a hook that lets the route go on) stays `undefined`.
+ */
+function encoding<F extends (...args: never[]) => unknown>(stage: F, at: 0 | 1): F {
+  const wrapped = (...args: never[]): unknown => {
+    const c: JsonReplyContext = args[at]!
+    let result: unknown
+    try {
+      result = stage(...args)
+    } catch (thrown) {
+      throw encodedThrow(thrown, c)
+    }
+    if (!(result instanceof Promise)) return encodedAnswer(result, c)
+    return result.then(
+      (answer) => encodedAnswer(answer, c),
+      (thrown) => {
+        throw encodedThrow(thrown, c)
+      },
+    )
+  }
+  // Named as the stage, so stack traces and the hook report still name the author's function.
+  Object.defineProperty(wrapped, "name", { value: stage.name })
+  tagStandIn(wrapped, stage)
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the wrapper takes `F`'s arguments and returns `unknown`, which is every stage's own return type.
+  return wrapped as F
+}
+
+/** A route's handler and answering hooks, each wrapped so every `Uint8Array` it answers leaves as
+ * base64. */
+export function withBase64Bytes<S extends AnswerStages>(stages: S): S {
+  return {
+    ...stages,
+    handler: encoding(stages.handler, 0),
+    beforeHandle: stages.beforeHandle.map((hook) => encoding(hook, 0)),
+    afterHandle: stages.afterHandle.map((hook) => encoding(hook, 1)),
+    onError: stages.onError.map((hook) => encoding(hook, 1)),
+  }
+}

package/src/server/core-copies.ts

@@ -16,14 +16,17 @@ const copies = registry[COPIES]
 const here = String(import.meta.url).split("?")[0] as string
 
 if (!copies.includes(here) && copies.push(here) > 1) {
+  // The registrar marks the process when it installs; without the mark a declared singleCopy was never
+  // armed here, most often because bunfig.toml's preload line sits below a [table] header. Bun-only and
+  // behind the inline NODE_ENV literal, so a production bundle drops the hint.
   console.warn(
-    `[nifra] @nifrajs/core is loaded ${copies.length} times; \`nifra check\` names each importer:\n  ${copies.join("\n  ")}`,
+    `[nifra] @nifrajs/core is loaded ${copies.length} times; \`nifra check\` names each importer:\n  ${copies.join("\n  ")}${typeof Bun !== "undefined" && process.env.NODE_ENV !== "production" && !(Symbol.for("nifra.single-copy.active") in globalThis) ? "\n  No single-copy registrar ran in this process: bunfig.toml must preload @nifrajs/core/single-copy/register at its top level, above any [table], for bun run, and under [test] for bun test." : ""}`,
   )
 }
 
 /** This copy's version: a literal like the package root's `VERSION` (no fs on the edge), which
  * `scripts/version.ts` rewrites on every release and `check:publish` asserts. */
-const COPY_VERSION = "5.6.0"
+const COPY_VERSION = "5.8.0"
 
 /** Record this copy's version beside its URL. Called by each `server()` behind the development guard,
  * so a production bundle drops it with the version; a copy that built a server has recorded one. */

package/src/server/install.ts

@@ -52,5 +52,8 @@ export const RESOLVE_NODE_MOUNT: unique symbol = Symbol.for(
   NODE_BRIDGE_MARKER_KEYS.resolveNodeMount,
 )
 
+/** @internal Run a server's `onStopping` or `onStop` hooks; see `Server.stop()`. */
+export const SERVER_LIFECYCLE: unique symbol = Symbol.for("@nifrajs/core/server-lifecycle")
+
 /** @internal Marker on a mounted handler that knows how to serve a native Node request/response. */
 export const NODE_NATIVE_MOUNT: unique symbol = Symbol.for("@nifrajs/core/node-native-mount")

package/src/server/json-response.ts

@@ -0,0 +1,13 @@
+import { retried } from "./json-text.ts"
+
+/** `Response.json`, with each `bigint` written as its decimal string, as `jsonText` writes it. */
+export function jsonResponse(value: unknown, init?: ResponseInit): Response {
+  try {
+    return Response.json(value, init)
+  } catch (error) {
+    const text = retried(value, error)
+    // Parsed back so the runtime's own `Response.json` still picks the content-type, and still
+    // throws for a value with no JSON form.
+    return Response.json(typeof text === "string" ? JSON.parse(text) : value, init)
+  }
+}

package/src/server/json-text.ts

@@ -0,0 +1,34 @@
+/**
+ * JSON has no `bigint`, and `JSON.stringify` throws on one, so a handler returning a database's 64-bit
+ * id answered a 500. Every plain JSON writer goes through this instead: a `bigint` is written as its
+ * decimal string, the encoding OpenAPI generators and protobuf's JSON mapping use for 64-bit integers.
+ * Only a first attempt that threw is retried, so a value without one costs nothing more. The Node
+ * adapter runs a generated copy (scripts/gen-node-outcome.ts), so this module imports nothing.
+ */
+
+const bigintAsText = (_key: string, value: unknown): unknown =>
+  typeof value === "bigint" ? value.toString() : value
+
+/**
+ * `JSON.stringify`, with each `bigint` written as its decimal string. Typed as the lib types
+ * `JSON.stringify`: a value with no JSON form (`undefined`, a function) still gives `undefined`.
+ */
+export function jsonText(value: unknown): string {
+  try {
+    return JSON.stringify(value)
+  } catch (error) {
+    return retried(value, error)
+  }
+}
+
+/** Write `value` again, each `bigint` as text, after `JSON.stringify(value)` threw `error`; any other
+ * failure rethrows `error`. */
+export function retried(value: unknown, error: unknown): string {
+  if (!(error instanceof TypeError)) throw error
+  try {
+    return JSON.stringify(value, bigintAsText)
+  } catch {
+    // A cycle or a throwing `toJSON` fails this pass too; the first error is the one to report.
+    throw error
+  }
+}

package/src/server/node-outcome.ts

@@ -3,6 +3,8 @@
  * conversion. Mirrors `respond.ts` but skips the undici `Response` build where the adapter can write a
  * plain-data render straight to the socket. Imports only runtime-core + respond + the spine types.
  */
+
+import { jsonText } from "./json-text.ts"
 import {
   applySetToResponse,
   applyStaticResponseHeaders,
@@ -88,7 +90,7 @@ export function toNodeOutcome(result: HandlerResult, set: CtxSet): NodeServeOutc
     return nodeOutcomeFromResponse(applySetToResponse(normalizeBodylessResponse(result), set))
   }
   const status = set.status ?? (result === undefined ? 204 : 200)
-  const body = result === undefined || isBodylessStatus(status) ? null : JSON.stringify(result)
+  const body = result === undefined || isBodylessStatus(status) ? null : jsonText(result)
   return {
     kind: "json",
     status,
@@ -109,10 +111,7 @@ export function plainNodeOutcome(plain: PlainRender, set: CtxSet): NodeServeOutc
     status: plain.status,
     headers: plainRenderHeaders(plain, set),
     cookies: set._cookies,
-    body:
-      plain.body === undefined || isBodylessStatus(plain.status)
-        ? null
-        : JSON.stringify(plain.body),
+    body: plain.body === undefined || isBodylessStatus(plain.status) ? null : jsonText(plain.body),
   }
 }
 

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

package/src/server/respond.ts

@@ -7,6 +7,8 @@
 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,
@@ -215,10 +217,11 @@ function jsonResponseWithOwnHeaders(
   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(
@@ -504,8 +508,8 @@ function tagged(
  * 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 : (JSON.stringify(result) as string | undefined)
-  return body === undefined ? Response.json(result) : new Response(body, JSON_INIT_200)
+  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. */
@@ -550,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++) {
@@ -563,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.
@@ -587,7 +591,7 @@ export function fusedRespondNoSet(
     return withBody(
       statics === undefined
         ? plainJsonResponse(result)
-        : Response.json(result, statics.responseJsonInit200()),
+        : jsonResponse(result, statics.responseJsonInit200()),
     )
   }
   return toResponse(
@@ -612,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,
@@ -626,6 +631,7 @@ export function toResponse(
   tagResponseBody: ResponseBodyTagOption = false,
   statics?: StaticResponseHeaders,
   request?: Request,
+  unstamped = false,
 ): Response {
   if (isResponseResult(result)) {
     const plain = result.plain
@@ -639,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.
@@ -671,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)
 }
 
 /**
@@ -701,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.
@@ -730,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
@@ -750,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)
@@ -778,9 +787,9 @@ function renderValue(
   if (IS_DENO && headers !== undefined && !(headers instanceof 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)
+    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:

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

@@ -59,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"
@@ -546,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,

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,6 +6,7 @@
  */
 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). */
@@ -188,7 +189,7 @@ export function status(
       const headers: Record<string, string> = { ...init?.headers }
       if (body === undefined) return new Response(null, { status: code, headers })
       headers["content-type"] ??= JSON_CONTENT_TYPE
-      return new Response(JSON.stringify(body), { status: code, headers })
+      return new Response(jsonText(body), { status: code, headers })
     },
   } as StatusResponse<number, unknown>
 }

package/src/server/server-types.ts

@@ -89,6 +89,18 @@ export interface ServerOptions {
    * untrusted input.
    */
   readonly trustBodyFraming?: boolean
+  /**
+   * Answer `400 invalid_host` on Bun to every Host that Node and Deno refuse: one sent twice, one
+   * no URL can be built on (a space, a byte past ASCII, a port past 65535, an IPv6 literal no parser
+   * takes), a percent-encoded or sub-delimiter one, and serve an HTTP/1.0 request with no Host as
+   * `localhost`. Bun serves those requests itself, building `c.req.url` on the first Host or leaving
+   * it relative, so `new URL(c.req.url)` can throw in a handler.
+   *
+   * Disabled by default: the check reads the Host on every request, which measured about 6% of a bare
+   * route on Bun. Left off, a target with `.` or `..` segments is still checked, so a dot segment is
+   * never routed raw. Node and Deno refuse these Hosts either way; the option changes nothing there.
+   */
+  readonly validateHost?: 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 up to 1.4.3 drops the
@@ -125,10 +137,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.
@@ -254,9 +265,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