@nifrajs/core 5.8.0 → 5.10.0

package/src/server/bare-error-lane.ts

@@ -31,7 +31,8 @@ export type ErrorLogDetail = "full" | "message" | "none"
  *   - a `Response` or a `status(...)` is control flow - the app answering directly, or plain data.
  *     Either renders through the same `finalize` a RETURNED one takes, with the request's `c.set`,
  *     so a thrown one means what the return means: a `Response` ships as built, plus the cookies the
- *     request queued (the set-session-then-`throw redirect()` pattern);
+ *     request queued (the set-session-then-`throw redirect()` pattern); one whose body cannot render
+ *     is a fault like any other, never a rejected request;
  *   - a request body the app's own `c.req.json()` or `c.req.formData()` could not parse is the
  *     client's 400 (`invalid_json`, `invalid_form`);
  *   - anything else is a real fault: logged once, then a bodyless 500 (never the caller's error text).
@@ -48,7 +49,15 @@ export function renderBareError<T>(
   logError: (err: unknown, ctx: RawContext) => void,
   wrapResponse: (response: ResponseResult) => T,
 ): T {
-  if (err instanceof Response || isResponseResult(err)) return finalize(err, responseSet(ctx), ctx)
+  if (err instanceof Response || isResponseResult(err)) {
+    try {
+      return finalize(err, responseSet(ctx), ctx)
+    } catch (renderErr) {
+      // A thrown answer whose body cannot render (a `toJSON` that throws) is a fault, not control flow.
+      logError(renderErr, ctx)
+      return wrapResponse(plainError(500, "internal_error"))
+    }
+  }
   const clientCode = clientBodyErrorCode(err)
   if (clientCode !== undefined) return wrapResponse(plainError(400, clientCode))
   logError(err, ctx)

package/src/server/base64-answers.ts

@@ -10,6 +10,7 @@
  */
 import { tagStandIn } from "../internal/hook-origins.ts"
 import type { AnswerStages, JsonReplyContext } from "./answer-step.ts"
+import { define } from "./json-shared.ts"
 import { isResponseResult, status } from "./runtime-core.ts"
 
 // Deeper than any real payload.
@@ -24,11 +25,6 @@ function base64(bytes: Uint8Array): string {
   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
@@ -52,7 +48,7 @@ function encoded(value: unknown, depth: number, path: Set<object>): unknown {
       }
       return out ?? value
     }
-    let out: object | undefined
+    let out: Record<string, unknown> | undefined
     for (const key of Object.keys(value)) {
       const item: unknown = Reflect.get(value, key)
       const next = encoded(item, depth + 1, path)

package/src/server/body-lane.ts

@@ -22,16 +22,25 @@ type JsonErrorContinuation<T> = (error: unknown) => T | Promise<T>
 
 type FramedJsonSource = RequestSource & {
   readonly bytes?: () => Promise<Uint8Array>
+  readonly text?: () => Promise<string>
   readonly jsonWithByteLength?: () => Promise<{
     readonly value: unknown
     readonly byteLength: number
   }>
 }
 
+// Every lane calls `onResult` outside its parse guard: a throw from the continuation is the app's,
+// and must never come back to the client as `invalid_json`.
 const INVALID_JSON = (): ResponseResult => plainError(400, "invalid_json")
+// A parameter, not a closure over the caller's `settle`: capturing it there costs every call a scope object.
+const fromBuffer =
+  <T>(settle: (bytes: Uint8Array) => T) =>
+  (buffer: ArrayBuffer): T =>
+    settle(new Uint8Array(buffer))
 
 // `Deno.serve`'s own `Request.json()` keeps a leading UTF-8 byte order mark that its `text()` and every
-// other runtime's `json()` drop, so it refuses a body they parse. Deno decodes the bytes itself below.
+// other runtime's `json()` drop, so it refuses a body they parse. Deno uses `text()` for an
+// untouched, runtime-framed request, or decodes the checked bytes below for other sources.
 const nativeJsonKeepsBom = "Deno" in globalThis
 
 /** Read a JSON source with the declared-length precheck, delivered-byte recheck, streaming cap, and
@@ -76,17 +85,39 @@ export function readBoundedJsonSource<T>(
         ? Promise.resolve(plainError(413, "payload_too_large"))
         : Promise.resolve(plainError(413, "payload_too_large")).then(onResult)
 
+    // A trusted runtime frame makes Content-Length the byte bound. Wrapped or untrusted sources
+    // must keep the delivered-byte check below, and chunked bodies must keep the streaming cap.
+    if (
+      nativeJsonKeepsBom &&
+      raw === req &&
+      hasTrustedBodyFraming(req) &&
+      raw.text !== undefined &&
+      headerOf(req, "transfer-encoding") === null
+    ) {
+      return raw.text().then(
+        (text) => {
+          let parsed: unknown
+          try {
+            parsed = parseJsonGuarded(text, protoPoisoning)
+          } catch {
+            parsed = INVALID_JSON()
+          }
+          return onResult === undefined ? parsed : onResult(parsed)
+        },
+        () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON())),
+      )
+    }
+
     if (hasTrustedBodyFraming(req) && !nativeJsonKeepsBom) {
       return raw.json().then(
         (parsed) => {
+          let guarded: unknown
           try {
-            const guarded = guardParsedValue(parsed, protoPoisoning)
-            return onResult === undefined ? guarded : onResult(guarded)
+            guarded = guardParsedValue(parsed, protoPoisoning)
           } catch {
-            return onResult === undefined
-              ? plainError(400, "invalid_json")
-              : onResult(plainError(400, "invalid_json"))
+            guarded = INVALID_JSON()
           }
+          return onResult === undefined ? guarded : onResult(guarded)
         },
         () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON())),
       )
@@ -102,60 +133,36 @@ export function readBoundedJsonSource<T>(
                 ? plainError(413, "payload_too_large")
                 : onResult(plainError(413, "payload_too_large"))
             }
+            let guarded: unknown
             try {
-              const guarded = guardParsedValue(value, protoPoisoning)
-              return onResult === undefined ? guarded : onResult(guarded)
+              guarded = guardParsedValue(value, protoPoisoning)
             } catch {
-              return onResult === undefined
-                ? plainError(400, "invalid_json")
-                : onResult(plainError(400, "invalid_json"))
+              guarded = INVALID_JSON()
             }
+            return onResult === undefined ? guarded : onResult(guarded)
           },
           () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON())),
         )
       }
 
-      const bytesReader = raw.bytes
-      if (bytesReader !== undefined) {
-        return bytesReader.call(raw).then(
-          (bytes) => {
-            if (bytes.byteLength > length || bytes.byteLength > maxBytes) {
-              return onResult === undefined
-                ? plainError(413, "payload_too_large")
-                : onResult(plainError(413, "payload_too_large"))
-            }
-            try {
-              const parsed = parseJsonGuarded(TEXT_DECODER.decode(bytes), protoPoisoning)
-              return onResult === undefined ? parsed : onResult(parsed)
-            } catch {
-              return onResult === undefined
-                ? plainError(400, "invalid_json")
-                : onResult(plainError(400, "invalid_json"))
-            }
-          },
-          () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON())),
-        )
+      const settle = (bytes: Uint8Array) => {
+        if (bytes.byteLength > length || bytes.byteLength > maxBytes) {
+          return onResult === undefined
+            ? plainError(413, "payload_too_large")
+            : onResult(plainError(413, "payload_too_large"))
+        }
+        let parsed: unknown
+        try {
+          parsed = parseJsonGuarded(TEXT_DECODER.decode(bytes), protoPoisoning)
+        } catch {
+          parsed = INVALID_JSON()
+        }
+        return onResult === undefined ? parsed : onResult(parsed)
       }
-
-      return raw.arrayBuffer().then(
-        (buffer) => {
-          const bytes = new Uint8Array(buffer)
-          if (bytes.byteLength > length || bytes.byteLength > maxBytes) {
-            return onResult === undefined
-              ? plainError(413, "payload_too_large")
-              : onResult(plainError(413, "payload_too_large"))
-          }
-          try {
-            const parsed = parseJsonGuarded(TEXT_DECODER.decode(bytes), protoPoisoning)
-            return onResult === undefined ? parsed : onResult(parsed)
-          } catch {
-            return onResult === undefined
-              ? plainError(400, "invalid_json")
-              : onResult(plainError(400, "invalid_json"))
-          }
-        },
-        () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON())),
-      )
+      const refuse = () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON()))
+      const bytesReader = raw.bytes
+      if (bytesReader !== undefined) return bytesReader.call(raw).then(settle, refuse)
+      return raw.arrayBuffer().then(fromBuffer(settle), refuse)
     }
   }
 

package/src/server/body.ts

@@ -8,6 +8,7 @@
  */
 
 import { jsonError } from "./http.ts"
+import { carryToCopy } from "./request-local.ts"
 
 interface BodySource {
   readonly headers: Pick<Headers, "get">
@@ -277,7 +278,9 @@ export function capBodyBytes(request: Request, maxBytes: number): Request {
     ),
     duplex: "half",
   }
-  return new Request(request, init)
+  const capped = new Request(request, init)
+  carryToCopy(request, capped)
+  return capped
 }
 
 /** First matching own-or-inherited descriptor, so instance shadows and prototype accessors both resolve. */

package/src/server/bridge-markers.ts

@@ -4,7 +4,7 @@
  * Each entry names a symbol looked up with `Symbol.for(...)`, so the two packages agree ONLY by the
  * string. A rename on one side and not the other is a silent protocol break - no type error, just a
  * symbol that never matches and a body that stops taking the direct-write lane. This module is the
- * single source: core defines its own symbols from these literals, and `scripts/gen-node-outcome.ts`
+ * single source: core defines its own symbols from these literals, and `scripts/gen-vendored.ts`
  * copies the map verbatim into the adapter's generated contract, so @nifrajs/node reads the identical
  * strings without a runtime dependency on core (the same deployment shape the generated outcome type
  * preserves).

package/src/server/cookies.ts

@@ -247,7 +247,10 @@ const toBase64Url = (buf: ArrayBuffer): string => {
   let bin = ""
   const bytes = new Uint8Array(buf)
   for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]!)
-  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
+  return btoa(bin)
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/={1,2}$/, "")
 }
 
 const BASE64URL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"

package/src/server/core-copies.ts

@@ -26,7 +26,7 @@ if (!copies.includes(here) && copies.push(here) > 1) {
 
 /** 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.8.0"
+const COPY_VERSION = "5.10.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/http.ts

@@ -5,39 +5,7 @@
  */
 import { type ResponseResult, status as statusResult } from "./runtime-core.ts"
 
-/**
- * Is `value` a destination that stays on this origin?
- *
- * True only for an absolute path: one leading `/`, never `//` (protocol-relative → another origin),
- * and free of any character a URL parser turns into an origin escape. A leading `/` alone is not
- * enough: under a special scheme `\` parses as `/`, and tab/CR/LF are STRIPPED before parsing, so
- * `/\evil.example` and `/<TAB>/evil.example` both resolve to the external host `evil.example` while
- * passing a `//` test. Rejecting CR/LF here also keeps a validated destination out of the
- * response-splitting sink it usually flows into.
- *
- * One implementation, because every caller is the same open-redirect gate: `redirect()` in
- * `@nifrajs/web`, the `redirectTo` of the `@nifrajs/auth` and `@nifrajs/better-auth` guards. Three
- * copies of a security predicate is three chances for one of them to be hardened alone.
- *
- * It answers about a PATH, not a URL: an absolute `https://this.host/x` is false even for the
- * current origin, because the whole point is that the value never got to name a host.
- */
-export function isSameOriginPath(value: string): boolean {
-  if (!value.startsWith("/") || value.startsWith("//")) return false
-  // Scanned by character code rather than matched by regex: no control characters have to be written
-  // into a pattern, and the check is a single pass over a short string.
-  for (let i = 1; i < value.length; i++) {
-    const code = value.charCodeAt(i)
-    if (code === 0x5c /* \ */ || code <= 0x1f || code === 0x7f) return false
-  }
-  // `/.//host` and `/a/..//host` (or their `%2e` forms) resolve to the path `//host`, which any
-  // relative reference later built from that path - a client router's redirect - reads as a host.
-  // A path-absolute reference against a valid base always parses, so this cannot throw.
-  return (
-    !(value.includes(".") || value.includes("%")) ||
-    !new URL(value, "http://n.invalid").pathname.startsWith("//")
-  )
-}
+export { isSameOriginPath } from "../router/same-origin-path.ts"
 
 /**
  * Whether `method` is a token a route can be registered under: uppercase ASCII letters, digits and
@@ -150,3 +118,15 @@ export function pathnameOf(url: string): string {
   }
   return url.slice(start, end)
 }
+
+/**
+ * A `Vary` header value (`null` when the response has none) that names each of `names` once, matched
+ * without regard to case. `Vary: *` already covers every request header, so it comes back unchanged.
+ */
+export function varyOn(value: string | null, names: readonly string[]): string {
+  if (value === null || value.trim() === "") return names.join(", ")
+  const fields = value.split(",").map((field) => field.trim().toLowerCase())
+  if (fields.includes("*")) return value
+  const missing = names.filter((name) => !fields.includes(name.toLowerCase()))
+  return missing.length === 0 ? value : `${value}, ${missing.join(", ")}`
+}

package/src/server/idempotency-lane.ts

@@ -35,6 +35,7 @@ import { markTransportCap, readBoundedBytes, transportCapOf, UNLIMITED_BODY_BYTE
 import type { Platform, RouteSchema } from "./context.ts"
 import { jsonError, urlPartsOf } from "./http.ts"
 import { INSTALL_IDEMPOTENCY } from "./install.ts"
+import { carryToCopy } from "./request-local.ts"
 import { CONTEXT_REQUEST, PRE_DECODED_BODY, preDecodedBody, requestOf } from "./runtime-core.ts"
 import type { AnyServer, IdentityPlugin, RawContext, RequestSource } from "./server.ts"
 
@@ -467,6 +468,7 @@ function prepareRequest(source: RequestSource, platform: Platform | undefined):
       duplex: "half",
     }
     prepared = new Request(request.url, init)
+    carryToCopy(request, prepared)
     const decoded = preDecodedBody(request)
     if (decoded !== undefined) Object.defineProperty(prepared, PRE_DECODED_BODY, { value: decoded })
   } catch (error) {

package/src/server/idle-timeout.ts

@@ -0,0 +1,107 @@
+/**
+ * `withIdleTimeout()`: one request's own idle timeout on a Bun `listen()` server, held while slow
+ * work runs and put back before the response goes out.
+ */
+import type { Context } from "./context.ts"
+import { CONTEXT_IDLE_TIMEOUT, getNeverAbortSignal } from "./runtime-core.ts"
+
+type MaybePromise<T> = T | Promise<T>
+
+type IdleTimeoutControl = (this: unknown, seconds: number | undefined) => boolean
+
+/** The `seconds` of every scope still running on a context. Deleted when the last one ends or the
+ * request is aborted, which also tells a scope ending after an abort to leave the socket alone. */
+const scopesOf = new WeakMap<object, number[]>()
+
+const longest = (scopes: readonly number[]): number =>
+  scopes.includes(0) ? 0 : Math.max(...scopes)
+
+/**
+ * Run `work` with the idle timeout of the request's connection set to `seconds` (`0` turns it off),
+ * then put back the listener's.
+ *
+ * Bun closes a connection that moves no bytes for `listen()`'s `idleTimeoutSec` seconds (10 by
+ * default), and a handler that is still working sends none, so an export or a long upstream call is
+ * cut mid-flight. Raising `idleTimeoutSec` raises it for every connection, idle keep-alive ones
+ * included; this raises it for one request. The listener's value is back before the response goes
+ * out because Bun keeps the last value on the socket for the requests that follow on it, so a value
+ * left in place would hold an idle connection open.
+ *
+ * The request's deadline (`requestTimeoutMs`, an inbound deadline) still bounds the response: when it
+ * fires, the 503 is sent with the listener's timeout back and `c.signal` aborts, but `work`
+ * keeps running unless it stops on that signal. Scopes nest: while several run on one request the
+ * longest applies, and `0` outlasts any number. `seconds` runs from 0 to 255, the longest Bun holds
+ * an idle connection; work that may idle longer takes `0`.
+ *
+ * A streamed response is sent after the handler returns, so call this inside the stream's producer
+ * to hold it until the last chunk. Off `listen()` - another adapter, `app.fetch` in a test - it runs
+ * `work` unchanged.
+ *
+ * @example
+ * ```ts
+ * import { withIdleTimeout } from "@nifrajs/core/idle-timeout"
+ *
+ * app.post("/exports", (c) => withIdleTimeout(c, 0, () => buildExport(c.body)))
+ * // Every route declared after this one:
+ * app.around((c, next) => withIdleTimeout(c, 120, next))
+ * ```
+ */
+export function withIdleTimeout<T>(
+  c: Context,
+  seconds: number,
+  work: () => MaybePromise<T>,
+): MaybePromise<T> {
+  if (!Number.isSafeInteger(seconds) || seconds < 0 || seconds > 255) {
+    throw new RangeError("withIdleTimeout: seconds must be an integer from 0 to 255")
+  }
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: only RequestContext defines this key, with this signature; any other context leaves it undefined.
+  const control = (c as Context & { [CONTEXT_IDLE_TIMEOUT]?: IdleTimeoutControl })[
+    CONTEXT_IDLE_TIMEOUT
+  ]
+  const signal = c.signal
+  if (control === undefined || signal.aborted) return work()
+  const set = (value: number | undefined): void => {
+    control.call(c, value)
+  }
+  let scopes = scopesOf.get(c)
+  if (scopes === undefined) {
+    scopes = []
+    scopesOf.set(c, scopes)
+  }
+  const own = scopes
+  own.push(seconds)
+  set(longest(own))
+  // An abort is the deadline's 503 or a closed client: either way the response is final, so the
+  // listener's timeout goes back now rather than when the abandoned work settles.
+  const abort = (): void => {
+    if (scopesOf.get(c) !== own) return
+    scopesOf.delete(c)
+    set(undefined)
+  }
+  // The never-abort signal is one object shared by every request without a deadline.
+  const listens = signal !== getNeverAbortSignal()
+  if (listens) signal.addEventListener("abort", abort, { once: true })
+  const end = (): void => {
+    if (listens) signal.removeEventListener("abort", abort)
+    if (scopesOf.get(c) !== own) return
+    own.splice(own.indexOf(seconds), 1)
+    if (own.length > 0) {
+      set(longest(own))
+      return
+    }
+    scopesOf.delete(c)
+    set(undefined)
+  }
+  let result: MaybePromise<T>
+  try {
+    result = work()
+  } catch (err) {
+    end()
+    throw err
+  }
+  if (!(result instanceof Promise)) {
+    end()
+    return result
+  }
+  return result.finally(end)
+}

package/src/server/json-shared.ts

@@ -0,0 +1,38 @@
+/**
+ * What core's JSON walks share besides the writer: the `Date` hooks the response contract reads, the
+ * `__proto__`-safe field setter, and the plain-record tests canonical JSON uses. Apart from
+ * `json-text.ts` so the Node adapter's generated copy of that module holds only the writer.
+ */
+
+export const DATE_TO_JSON = Date.prototype.toJSON
+// What `Date.prototype.toJSON` reads a `Date`'s time value through.
+const DATE_TO_PRIMITIVE = Date.prototype[Symbol.toPrimitive]
+const DATE_VALUE_OF = Date.prototype.valueOf
+
+/**
+ * Whether `date` reaches the `@@toPrimitive` and `valueOf` that `Date.prototype.toJSON` reads its time
+ * value through as they ship, on itself, its class or `Date.prototype`. Then its steps, taken by the
+ * caller, give what the call would: `null` for a time value that is not finite, else what its
+ * `toISOString` answers, called through it as `toJSON` calls it.
+ */
+export const readsShippedTime = (date: Date): boolean =>
+  date[Symbol.toPrimitive] === DATE_TO_PRIMITIVE && date.valueOf === DATE_VALUE_OF
+
+/** Sets `key` on `out` as an own field, `__proto__` included, which an assignment takes as the prototype. */
+export 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
+}
+
+// biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the member is optional, so an engine without JSON.rawJSON leaves it undefined.
+export const isRawJson = (JSON as JSON & { readonly isRawJSON?: (value: unknown) => boolean })
+  .isRawJSON
+
+/**
+ * Whether `proto` is a plain record's prototype: `Object.prototype`, `null`, or any prototype whose own
+ * prototype is null, which admits another realm's plain object. A boxed primitive's or a class's is
+ * not. A `JSON.rawJSON` value's is `null` too, so a caller tells one apart first.
+ */
+export const isPlainPrototype = (proto: unknown): boolean =>
+  proto === null || proto === Object.prototype || Object.getPrototypeOf(proto) === null

package/src/server/json-text.ts

@@ -3,7 +3,7 @@
  * 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.
+ * adapter runs a generated copy (scripts/gen-vendored.ts), so this module imports nothing.
  */
 
 const bigintAsText = (_key: string, value: unknown): unknown =>

package/src/server/node-outcome.ts

@@ -109,7 +109,7 @@ export function plainNodeOutcome(plain: PlainRender, set: CtxSet): NodeServeOutc
   return {
     kind: "json",
     status: plain.status,
-    headers: plainRenderHeaders(plain, set),
+    headers: plainRenderHeaders(plain.headers, set._headers),
     cookies: set._cookies,
     body: plain.body === undefined || isBodylessStatus(plain.status) ? null : jsonText(plain.body),
   }

package/src/server/request-context.ts

@@ -17,7 +17,12 @@ import { jsonText } from "./json-text.ts"
 import type { ProtoPoisoning } from "./proto-guard.ts"
 import { searchOf } from "./query.ts"
 import { residentText, responseJsonContentType } from "./respond.ts"
+import type {
+  ResponseContractDefinition,
+  ResponseContractRuntime,
+} from "./response-contract-lane.ts"
 import {
+  CONTEXT_IDLE_TIMEOUT,
   CONTEXT_REQUEST,
   CONTEXT_SEARCH,
   CONTEXT_SET,
@@ -166,8 +171,40 @@ const TEXT_CONTENT_TYPE = "text/plain; charset=utf-8"
  * handler never reads it costs the adapter neither a lookup nor a platform object of its own. */
 export const PLATFORM_PEER = Symbol()
 
+/** Where a Bun listener leaves the idle timeout of a request's connection: called with the request
+ * and the seconds to allow, or `undefined` to put back the listener's own. */
+export const PLATFORM_IDLE_TIMEOUT = Symbol()
+
+/** The request the adapter received, on a platform made for one request: the routed source may be a
+ * rewritten or stripped copy, which Bun does not know. */
+export const PLATFORM_REQUEST = Symbol()
+
 export type PeerPlatform = Platform & {
   readonly [PLATFORM_PEER]?: (source: RequestSource) => string | undefined
+  readonly [PLATFORM_IDLE_TIMEOUT]?: (source: RequestSource, seconds: number | undefined) => void
+  readonly [PLATFORM_REQUEST]?: RequestSource
+}
+
+/**
+ * Whether merging `decorations` into a context can complete. A decoration named for a read-only
+ * accessor of the context (`req`, `set`, `signal`) makes `Object.assign` throw on every request, a
+ * failure the general program routes to the route's error hooks and a fused lane would not.
+ */
+export function decorationsAssignable(decorations: Record<PropertyKey, unknown>): boolean {
+  for (const key of Reflect.ownKeys(decorations)) {
+    for (
+      let proto: object | null = RequestContext.prototype;
+      proto !== null && proto !== Object.prototype;
+      proto = Object.getPrototypeOf(proto)
+    ) {
+      const descriptor = Object.getOwnPropertyDescriptor(proto, key)
+      if (descriptor === undefined) continue
+      if (descriptor.get !== undefined && descriptor.set === undefined) return false
+      if (descriptor.writable === false) return false
+      break
+    }
+  }
+  return true
 }
 
 export class RequestContext implements RawContext {
@@ -190,6 +227,13 @@ export class RequestContext implements RawContext {
   private declare cookiesValue: Readonly<Record<string, string>> | undefined
   declare jsonReply: Response | undefined
   declare jsonBody: unknown
+  /** The route's response contract, if it has one, for {@link json} to write by. */
+  declare jsonContract:
+    | {
+        readonly runtime: ResponseContractRuntime
+        readonly definition: ResponseContractDefinition
+      }
+    | undefined
   private declare readonly source: RequestSource
   private declare readonly maxBodyBytes: number
   private declare readonly protoPoisoning: ProtoPoisoning
@@ -264,6 +308,14 @@ export class RequestContext implements RawContext {
     return requestOf(this.source)
   }
 
+  [CONTEXT_IDLE_TIMEOUT](seconds: number | undefined): boolean {
+    const platform = this.platformValue
+    const set = platform?.[PLATFORM_IDLE_TIMEOUT]
+    if (set === undefined) return false
+    set(platform?.[PLATFORM_REQUEST] ?? this.source, seconds)
+    return true
+  }
+
   get [CONTEXT_SEARCH](): string {
     this.searchValue ??= searchOf(this.source.url)
     return this.searchValue
@@ -336,6 +388,13 @@ export class RequestContext implements RawContext {
    */
   json(body: unknown, init?: ResponseInit | number): Response {
     const i = statusInit(init)
+    // A contracted route's value is written here once, as its contract judges it: the bytes and the
+    // check share one call of each `toJSON` hook, a `Date`'s included.
+    const contract = this.jsonContract
+    const value =
+      contract?.runtime.write === undefined
+        ? body
+        : contract.runtime.write(contract.definition, body, i?.status)
     let reply: Response | undefined
     if (DEFERS_RESPONSE) {
       const defer = deferredResponderFor()
@@ -344,17 +403,17 @@ 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 : (jsonText(body) as string | undefined)
+      const text = defer === undefined ? undefined : (jsonText(value) 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(jsonResponse(body, i))
+    reply ??= markResidentBody(jsonResponse(value, 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
+    this.jsonBody = value
     this.jsonReply = reply
     return reply
   }