@nifrajs/core 5.8.0 → 5.10.0

package/src/server/request-local.ts

@@ -0,0 +1,109 @@
+/**
+ * Request-local state: a value tied to one request that follows it through the copies made of it.
+ * A `WeakMap<Request, T>` loses its value at the first `new Request(url, req)`, and nifra itself
+ * rebuilds a request when a mount strips its prefix, when a WebSocket pass is reused for HTTP, and
+ * when a target is resolved. Every such copy joins the request's scope, so each reads and writes
+ * the same values.
+ */
+
+/** One request-local slot from {@link requestLocal}. */
+export interface RequestLocal<T> {
+  /** The value set through `request` or any request in its scope, else `undefined`. */
+  get(request: Request): T | undefined
+  /** Set the value for `request`'s whole scope. */
+  set(request: Request, value: T): void
+  has(request: Request): boolean
+  /** Remove the value from `request`'s scope; `true` when there was one. */
+  delete(request: Request): boolean
+}
+
+type Values = Map<object, unknown>
+
+/**
+ * A copy maps to the request it was made from, and the end of that chain (the anchor) to its
+ * scope's values once one is set. Keyed in the global symbol registry so two copies of core keep
+ * one table, and weak, so a scope lives exactly as long as a request in it.
+ */
+type Links = WeakMap<Request, Request | Values>
+
+// biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion lint/plugin/noChainedTypeAssertions: only this module writes the slot, and only a Links table.
+const shared = globalThis as unknown as Record<symbol, Links | undefined>
+const LINKS = Symbol.for("nifra.requestLocals")
+
+const linksOf = (): Links => (shared[LINKS] ??= new WeakMap())
+
+/** The request at the end of `request`'s chain of copies. */
+function anchorOf(links: Links, request: Request): Request {
+  let anchor = request
+  let link = links.get(anchor)
+  while (link !== undefined && !(link instanceof Map)) {
+    anchor = link
+    link = links.get(anchor)
+  }
+  return anchor
+}
+
+/** `to` was just built from `from`, with nothing set on it: it joins `from`'s scope. Until a first
+ * slot makes the table there is no scope to join, and a copy records nothing. */
+export function carryToCopy(from: Request, to: Request): void {
+  shared[LINKS]?.set(to, from)
+}
+
+/**
+ * Join `to` to `from`'s request-local scope: each then reads every value set through either, now
+ * and later. nifra does this wherever it rebuilds a request itself; call it where a wrapper or an
+ * `onRequest` hook rebuilds one, right after `new Request(url, req)`. A value `to` already holds is
+ * kept where `from` has none.
+ */
+export function carryRequestLocals(from: Request, to: Request): void {
+  const links = shared[LINKS]
+  if (links === undefined) return
+  const target = anchorOf(links, from)
+  const joining = anchorOf(links, to)
+  if (target === joining) return
+  const own = links.get(joining)
+  links.set(joining, target)
+  if (!(own instanceof Map)) return
+  const held = links.get(target)
+  if (!(held instanceof Map)) links.set(target, own)
+  else for (const [key, value] of own) if (!held.has(key)) held.set(key, value)
+}
+
+function valuesOf(request: Request, create: boolean): Values | undefined {
+  const links = linksOf()
+  const anchor = anchorOf(links, request)
+  const held = links.get(anchor)
+  if (held instanceof Map || !create) return held instanceof Map ? held : undefined
+  const fresh: Values = new Map()
+  links.set(anchor, fresh)
+  return fresh
+}
+
+/**
+ * A slot for one per-request value - a verified client IP, a request id, an auth decision - that
+ * survives the request copies nifra makes (a mount's prefix strip, a WebSocket pass reused for HTTP,
+ * target resolution) and the ones a wrapper makes with {@link carryRequestLocals}. A copy made any
+ * other way starts empty. Values are held weakly and never cross requests. Make slots at startup, as
+ * below: copies are linked only once a first slot exists, so a request copied before then starts
+ * empty.
+ *
+ * ```ts
+ * const clientIp = requestLocal<string>()
+ * app.onRequest((req, platform) => { clientIp.set(req, platform?.clientIp ?? "") })
+ * // ... in a mounted child app, after the prefix strip:
+ * clientIp.get(c.req)
+ * ```
+ */
+export function requestLocal<T>(): RequestLocal<T> {
+  linksOf()
+  const key = {}
+  return {
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: only `set` below writes `key`, and only a T.
+    get: (request) => valuesOf(request, false)?.get(key) as T | undefined,
+    set: (request, value) => {
+      valuesOf(request, true)?.set(key, value)
+    },
+    has: (request) => valuesOf(request, false)?.has(key) === true,
+    delete: (request) => valuesOf(request, false)?.delete(key) === true,
+  }
+}

package/src/server/respond.ts

@@ -39,7 +39,7 @@ function headersInit(set: CtxSet): Record<string, string> | Headers | undefined
 function plainRenderSet(plain: PlainRender, set: CtxSet): CtxSet {
   return {
     status: plain.status,
-    _headers: plainRenderHeaders(plain, set),
+    _headers: plainRenderHeaders(plain.headers, set._headers),
     _cookies: set._cookies,
   } as CtxSet
 }

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

@@ -38,8 +38,10 @@
  * 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.
+ * from private state keeps it. A `Date` is judged as the ISO string its own hook writes too, so a
+ * `t.string({ format: "date-time" })` or `t.date()` field holding a database timestamp passes: a
+ * schema that carries its JSON Schema is checked as JSON carries it. A schema without one (zod,
+ * valibot) cannot say which place expects a string, so it is shown every `Date` as one.
  *
  * ## What enforcement costs
  *
@@ -53,12 +55,15 @@
  * or lifecycle hook has already left that lane, so for the routes that look like production the
  * contract is effectively free - declare it.
  */
+
+import { isRecord } from "../internal/record.ts"
 import {
   formatStandardIssues,
   type StandardResult,
   type StandardSchemaV1,
 } from "../schema/standard.ts"
 import { INSTALL_RESPONSE_CONTRACT } from "./install.ts"
+import { DATE_TO_JSON, define, readsShippedTime } from "./json-shared.ts"
 import { jsonText } from "./json-text.ts"
 import type { IdentityPlugin } from "./plugin.ts"
 import { isResponseResult, status } from "./runtime-core.ts"
@@ -141,18 +146,14 @@ export type ResponseContractOutcome =
   /** `enforce` only: the payload cannot be reconciled with the contract, so it must not be sent. */
   | { readonly kind: "violation"; readonly message: string }
 
-const isPlainObject = (v: unknown): v is Record<string, unknown> =>
-  typeof v === "object" && v !== null && !Array.isArray(v)
-
 /** Rebuilds a value with only what its schema declares; absent when the schema can strip nothing. */
 type Projector = (value: unknown) => unknown
 
 const projectors = new WeakMap<object, Projector | null>()
 
-/** The projector for a schema's JSON Schema, compiled once per schema. */
-function projectorOf(schema: StandardSchemaV1): Projector | undefined {
-  const node: unknown = Reflect.get(schema, "jsonSchema")
-  if (typeof node !== "object" || node === null) return undefined
+/** The projector for a schema's JSON Schema, compiled once per schema. It writes each `Date` as it
+ * descends, as every schema that carries its JSON Schema is judged. */
+function projectorOf(node: object): Projector | undefined {
   let found = projectors.get(node)
   if (found === undefined) {
     found = compileProjector(node) ?? null
@@ -161,6 +162,12 @@ function projectorOf(schema: StandardSchemaV1): Projector | undefined {
   return found ?? undefined
 }
 
+/** The JSON Schema a schema carries as `jsonSchema` (every `@nifrajs/schema` `t` schema), if any. */
+function jsonSchemaOf(schema: StandardSchemaV1): object | undefined {
+  const node: unknown = Reflect.get(schema, "jsonSchema")
+  return typeof node === "object" && node !== null ? node : undefined
+}
+
 const objectField = (node: object, key: string): object | undefined => {
   const value: unknown = Reflect.get(node, key)
   return typeof value === "object" && value !== null ? value : undefined
@@ -180,7 +187,7 @@ function compileProjector(node: unknown): Projector | undefined {
       : (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)))
+          for (let i = 0; i < value.length; i++) out.push(item(writtenAt(value[i], i, true)))
           return out
         }
   }
@@ -207,12 +214,16 @@ function compileProjector(node: unknown): Projector | undefined {
     return undefined
   const declared = new Set(keys)
   return (value) => {
-    if (!isPlainObject(value)) return value
+    if (!isRecord(value)) return value
     const out: Record<string, unknown> = closed ? {} : { ...value }
     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(writtenAt(value[key], key)))
+      define(
+        out,
+        key,
+        projector === undefined ? value[key] : projector(writtenAt(value[key], key, true)),
+      )
     }
     if (patterns.length > 0) projectPatternKeys(value, out, declared, patterns, closed)
     return out
@@ -243,7 +254,7 @@ function compileUnion(branches: readonly unknown[]): Projector | undefined {
   if (forArray === undefined && forObject === undefined) return undefined
   return (value) => {
     if (Array.isArray(value)) return forArray === undefined ? value : forArray(value)
-    return forObject !== undefined && isPlainObject(value) ? forObject(value) : value
+    return forObject !== undefined && isRecord(value) ? forObject(value) : value
   }
 }
 
@@ -290,7 +301,7 @@ function compileDiscriminated(branches: readonly object[]): Projector | undefine
     })
     if (!disjoint) continue
     return (value) => {
-      if (!isPlainObject(value) || !hasField(value, key)) return value
+      if (!isRecord(value) || !hasField(value, key)) return value
       const projector = byTag.get(value[key])
       return projector === undefined ? value : projector(value)
     }
@@ -357,33 +368,31 @@ function projectPatternKeys(
       }
     if (matches === 0) continue
     if (matches === 1 && projector !== undefined)
-      define(out, key, projector(writtenAt(value[key], key)))
+      define(out, key, projector(writtenAt(value[key], key, true)))
     else if (closed) define(out, key, value[key])
   }
 }
 
 /** `__proto__` is a declared name like any other here; plain assignment would set the prototype. */
-function define(out: Record<string, unknown>, key: string, value: unknown): void {
-  if (key === "__proto__")
-    Object.defineProperty(out, key, { value, enumerable: true, writable: true, configurable: true })
-  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 {
+const isDate = (value: object, hook: unknown): value is Date =>
+  hook === DATE_TO_JSON && value instanceof Date
+
+/**
+ * Whether `value` holds a `toJSON` hook, a `Date`'s only when `dates` writes them. Stops at the first
+ * and allocates nothing: most payloads have none, and this is the price every contracted response
+ * pays.
+ */
+function hasHook(value: object, depth: number, dates: boolean): 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 (typeof hook === "function") return dates || !isDate(value, hook)
   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
+      if (typeof item === "object" && item !== null && hasHook(item, depth + 1, dates)) return true
     }
     return false
   }
@@ -391,7 +400,7 @@ function hasHook(value: object, depth: number): boolean {
   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
+    if (typeof field === "object" && field !== null && hasHook(field, depth + 1, dates)) return true
   }
   return false
 }
@@ -399,22 +408,26 @@ function hasHook(value: object, depth: number): boolean {
 /**
  * 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.
+ * containers above a hook. A `Date` keeps its object unless `dates`.
  */
-const wireValueOf = (value: unknown): unknown =>
-  typeof value === "object" && value !== null && hasHook(value, 0)
-    ? wireValue(value, "", [])
+const wireValueOf = (value: unknown, dates: boolean): unknown =>
+  typeof value === "object" && value !== null && hasHook(value, 0, dates)
+    ? wireValue(value, "", [], dates)
     : value
 
-const wireValue = (value: unknown, key: string | number, path: object[]): unknown =>
-  wireChildren(writtenAt(value, key), path)
+const wireValue = (value: unknown, key: string | number, path: object[], dates: boolean): unknown =>
+  wireChildren(writtenAt(value, key, dates), path, dates)
 
 /** `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 {
+function writtenAt(value: unknown, key: string | number, dates: boolean): 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
+  if (typeof hook !== "function") return value
+  if (isDate(value, hook)) {
+    if (!dates) return value
+    if (readsShippedTime(value))
+      return Number.isFinite(value.valueOf()) ? value.toISOString() : null
+  }
   return fieldsOf(Reflect.apply(hook, value, [String(key)]))
 }
 
@@ -432,33 +445,36 @@ function fieldsOf(value: unknown): unknown {
   return fields
 }
 
-function wireChildren(value: unknown, path: object[]): unknown {
+/** `value` with each of its fields written; a container is copied once, when a first field changes. */
+function wireChildren(value: unknown, path: object[], dates: boolean): 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)
+  // A primitive is written as it is, so only an object field is walked.
   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
+      if (typeof item !== "object" || item === null) continue
+      const written = wireValue(item, i, path, dates)
+      if (written === item) continue
+      items ??= value.slice()
+      items[i] = written
     }
     path.pop()
     return items ?? value
   }
-  const keys = Object.keys(value)
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: every key read below comes from `Object.keys(value)`; `Reflect.get` costs a call per field.
+  const record = value as Record<string, unknown>
   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++
+  for (const name of Object.keys(record)) {
+    const field = record[name]
+    if (typeof field !== "object" || field === null) continue
+    const written = wireValue(field, name, path, dates)
+    if (written === field) continue
+    // A spread copies the own enumerable fields JSON writes, faster than one assignment each.
+    out ??= { ...record }
+    define(out, name, written)
   }
   path.pop()
   return out ?? value
@@ -480,7 +496,7 @@ function collectStripped(sent: unknown, kept: unknown, path: string, out: Set<st
     }
     return
   }
-  if (!isPlainObject(sent) || !isPlainObject(kept)) return
+  if (!isRecord(sent) || !isRecord(kept)) return
   for (const key of Object.keys(sent)) {
     const short = key.length > MAX_NAME_LENGTH ? `${key.slice(0, MAX_NAME_LENGTH)}...` : key
     const name = path === "" ? short : `${path}.${short}`
@@ -520,7 +536,7 @@ function strippedMessage(fields: readonly string[]): string {
 
 /** Top-level keys present in the handler's result but absent from the validated value. */
 function droppedKeys(result: unknown, value: unknown): string[] {
-  if (!isPlainObject(result) || !isPlainObject(value)) return []
+  if (!isRecord(result) || !isRecord(value)) return []
   return Object.keys(result).filter((k) => !(k in value))
 }
 
@@ -587,6 +603,14 @@ interface ContractPolicy {
 const STRIP: ContractPolicy = { strip: true, report: undefined }
 const KEEP: ContractPolicy = { strip: false, report: undefined }
 
+/** Set by `@nifrajs/schema` on the validate of a `t` schema with a `t.date()`: the check for a value
+ * as JSON writes it. */
+const VALIDATE_WIRE: unique symbol = Symbol.for("nifra.schema.validateWire")
+
+type ContractValidate = StandardSchemaV1["~standard"]["validate"] & {
+  readonly [VALIDATE_WIRE]?: unknown
+}
+
 function checkContract(
   definition: ResponseContractDefinition,
   result: unknown,
@@ -634,19 +658,32 @@ function validateContract(
   policy: ContractPolicy,
   replace: (value: unknown) => unknown,
 ): ResponseContractOutcome | Promise<ResponseContractOutcome> {
-  const project = policy.strip ? projectorOf(schema) : undefined
+  const node = jsonSchemaOf(schema)
+  // A `Date` is a hook like any other for a schema that carries its JSON Schema: one walk writes them.
+  const dates = node !== undefined
+  const project = policy.strip && node !== undefined ? projectorOf(node) : undefined
   // 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
+  const hooks =
+    (project === undefined || policy.report !== undefined || mode === "warn") &&
+    typeof payload === "object" &&
+    payload !== null &&
+    hasHook(payload, 0, dates)
+  const before = hooks ? wireValue(payload, "", [], dates) : 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
+  const sent =
+    project === undefined ? before : wireValueOf(project(writtenAt(before, "", true)), true)
+  // A `t` schema's check for a value as JSON carries it: its `t.date()` strings stay strings, where
+  // the plain validate would hand back the `Date`s a request's handler receives.
+  const validate: ContractValidate = schema["~standard"].validate
+  const wire = validate[VALIDATE_WIRE]
+  const settled: StandardResult<unknown> | Promise<StandardResult<unknown>> =
+    typeof wire === "function" ? wire(sent) : schema["~standard"].validate(sent)
+  // When hooks wrote the payload, `warn` sends what they wrote here rather than calling them again:
+  // a hook that answers differently on a second call cannot send what was not judged, and the
+  // serializer does not write a `Date` twice. A contracted route's `c.json` reply has none left, as
+  // `write` applied them when the reply was built.
+  const shown = mode === "warn" && hooks ? replace(before) : served
   return settled instanceof Promise
     ? settled.then((r) => interpret(r, before, shown, mode, replace, policy.report))
     : interpret(settled, before, shown, mode, replace, policy.report)
@@ -702,6 +739,12 @@ export interface ResponseContractRuntime {
       readonly jsonBody?: unknown
     },
   ): ResponseContractOutcome | Promise<ResponseContractOutcome>
+  /**
+   * What a `c.json(body)` reply with this status writes, each `toJSON` hook applied as `check` judges
+   * it, so the reply's bytes and its check share one call of each. Without it, as from a plugin of
+   * an older copy of core, the reply writes `body` as given.
+   */
+  write?(definition: ResponseContractDefinition, body: unknown, status: number | undefined): unknown
 }
 
 interface ResponseContractInstallable {
@@ -772,6 +815,10 @@ export function responseContract(
   }
   const runtime: ResponseContractRuntime = {
     mode,
+    write: (definition, body, status) => {
+      const schema = schemaFor(definition, status ?? 200)
+      return schema === undefined ? body : wireValueOf(body, jsonSchemaOf(schema) !== undefined)
+    },
     check: (definition, result, context) => {
       const jsonReply =
         result instanceof Response && result === context?.jsonReply

package/src/server/runtime-core.ts

@@ -26,6 +26,9 @@ export const CONTEXT_SET = Symbol("nifra.context.set")
 export const CONTEXT_SEARCH = Symbol("nifra.context.search")
 /** The request a context answers, read without the transport cap `req` applies for user code. */
 export const CONTEXT_REQUEST = Symbol("nifra.context.request")
+/** Sets the idle timeout of the connection a context's request arrived on (`undefined` puts back
+ * the listener's own); `false` when the serving adapter has none to set. */
+export const CONTEXT_IDLE_TIMEOUT = Symbol()
 
 /**
  * A transport codec (or other pre-parsing hook) that already decoded the body stashes the value
@@ -114,21 +117,20 @@ export function isResponseResult(value: unknown): value is ResponseResult {
 }
 
 /**
- * The headers a plain render ships: its own on top of whatever the request left in `c.set.headers`,
- * so an ambient header (a request id, say) survives an early exit the way it survives an ordinary
- * return, and a header named at the exit site still wins.
+ * The headers a plain render ships: its `own` on top of the `ambient` ones the request left in
+ * `c.set.headers`, so an ambient header (a request id, say) survives an early exit the way it
+ * survives an ordinary return, and a header named at the exit site still wins.
  *
  * Always a fresh object when the render has headers of its own: the node writers mutate the record
  * they are handed (content-type, content-length, cookies), and a `status(...)` value is commonly
  * hoisted to module scope and answered from on every request.
  */
 export function plainRenderHeaders(
-  plain: PlainRender,
-  set: CtxSet,
+  own: Readonly<Record<string, string>> | undefined,
+  ambient: Record<string, string> | undefined,
 ): Record<string, string> | undefined {
-  const own = plain.headers
-  if (own === undefined) return set._headers
-  return set._headers === undefined ? { ...own } : { ...set._headers, ...own }
+  if (own === undefined) return ambient
+  return ambient === undefined ? { ...own } : { ...ambient, ...own }
 }
 
 /**

package/src/server/server-types.ts

@@ -90,17 +90,32 @@ export interface ServerOptions {
    */
   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.
+   * Answer `400 invalid_host` for Hosts the request target cannot safely be built on: one sent
+   * twice, one with a space or byte past ASCII, a port past 65535, an IPv6 literal no URL parser
+   * takes, a percent-encoded or sub-delimiter Host, or an authority that can change Deno's route.
+   * Bun may leave `c.req.url` relative or build it on the first Host, 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.
+   * Disabled by default: checking Host on every request measured about 6% of a bare route on Bun.
+   * Deno builds `Request.url` from Host; without this check, a malformed Host can change the routed
+   * path. Enable it when Deno receives requests with an untrusted Host header.
    */
   readonly validateHost?: boolean
+  /**
+   * Route a Deno request on the path a WHATWG parser would give it. Bun and workerd deliver a parsed
+   * URL, so `/public/../admin` reaches the app as `/admin`; Deno hands over the target as sent. Off,
+   * Deno routes the text received, as most frameworks do: a guard on `/admin` does not see
+   * `/public/../admin`, and a proxy that normalizes paths before forwarding disagrees with the app
+   * about which route a request is for. On, dot segments (`.`, `..`, `%2e`), backslashes and the
+   * characters a parser percent-encodes are resolved before routing, so every runtime routes the
+   * same path.
+   *
+   * Disabled by default: the check reads and scans the whole URL of every request, measured at about
+   * 3% of a bare route on Deno. Enable it when path guards, or a path-normalizing proxy, sit in
+   * front of or inside the app. Bun already delivers parsed targets and is unaffected; `@nifrajs/node`
+   * has the same option on `serve()`.
+   */
+  readonly normalizeTarget?: 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