@nifrajs/core 2.8.2 → 2.9.1

package/src/server/node-outcome-hook.ts

@@ -1,9 +1,323 @@
 /** Lazy Node-direct renderer seam. The base server retains the typed method but not its renderer. */
+
+import type { Platform } from "./context.ts"
 import type { NodeServeOutcome } from "./node-outcome.ts"
-import type { CtxSet } from "./server.ts"
+import type { CtxSet, MaybePromise } from "./server.ts"
+
+/**
+ * Allocation-light request view used by Node-native header middleware.
+ *
+ * Identity contract: within one request, the SAME object is passed to every `onNodeRequest` hook
+ * and every `onNodeResponse` hook (the native lanes engage together - see the server's gate), so a
+ * middleware may use it as a `WeakMap` key to carry per-request state from its request twin to its
+ * response twin.
+ */
+export interface NodeRequestContext {
+  readonly method: string
+  readonly url: string
+  readonly header: (name: string) => string | null
+}
+
+/**
+ * The mutable, case-insensitive header surface a portable {@link ResponseHeadersHook} writes
+ * through. Deliberately the subset of the Web `Headers` interface every runtime can satisfy
+ * natively: on the Web paths the hook receives the response's own `Headers` object directly (which
+ * structurally implements this), and on the Node direct-writer path it receives a thin view over
+ * the outcome's plain header record - so ONE hook implementation is fast everywhere.
+ */
+export interface ResponseHeadersView {
+  get(name: string): string | null
+  has(name: string): boolean
+  set(name: string, value: string): void
+  append(name: string, value: string): void
+  delete(name: string): void
+}
+
+/**
+ * A portable header-only response hook - the recommended shape for response middleware that only
+ * reads or writes headers (security headers, CORS reflection, cache directives, negotiation). It
+ * runs on every runtime from one implementation: the server adapts it into the Web `onResponse`
+ * walk AND the Node-native response lane, so registering one never forces the Node adapter off its
+ * direct socket writer the way a full `onResponse(res: Response)` hook does. It cannot replace the
+ * response or touch the body - middleware needing that keeps the full `onResponse` contract and
+ * its cost.
+ */
+export type ResponseHeadersHook = (
+  headers: ResponseHeadersView,
+  req: NodeRequestContext,
+  status: number,
+) => MaybePromise<void>
+
+/** Native equivalent of a paired `onRequest` hook. It may short-circuit, but cannot rewrite a request. */
+export type NodeRequestHook = (
+  request: NodeRequestContext,
+  platform?: Platform,
+) => MaybePromise<Response | undefined>
+
+/**
+ * Response view used by Node-direct middleware. Header hooks mutate `headers`; a BODY hook
+ * (adapted from the portable `onResponseBody`) may replace `body` - the already-serialized bytes
+ * the direct writer is about to send - and, through its structured replacement, the status
+ * (an ETag 304 being the canonical case).
+ */
+export interface NodeResponseContext {
+  /** Mutable ONLY through a body hook's replacement object (e.g. an ETag 304); header hooks read. */
+  status: number
+  headers: Record<string, string | readonly string[]> | undefined
+  readonly cookies: readonly string[] | undefined
+  /** The framework-serialized body bytes (`null` for a bodiless render). Replaceable by body hooks. */
+  body: string | Uint8Array | null
+}
+
+/** A body hook's structured replacement: new bytes (or `null` to drop the body) and/or a status. */
+export interface ResponseBodyReplacement {
+  readonly body?: string | Uint8Array | null
+  readonly status?: number
+}
+
+/**
+ * A portable post-serialization body hook - the Fastify-`onSend`-shaped tier. The hook receives
+ * the FINAL framework-serialized bytes plus the header view, and may return replacement bytes
+ * (`undefined` keeps the body unchanged). It runs at the framework's cheapest point on every
+ * runtime: the bytes are already resident before any Web `Response` exists, so no body stream is
+ * ever drained. A handler-returned raw `Response` (a proxied fetch, SSE, streamed SSR) is SKIPPED
+ * by definition - transforming those is exactly what the full `onResponse` contract is for.
+ */
+export type ResponseBodyHook = (
+  body: string | Uint8Array,
+  headers: ResponseHeadersView,
+  req: NodeRequestContext,
+  status: number,
+) => MaybePromise<string | Uint8Array | ResponseBodyReplacement | undefined>
+
+/** Native equivalent of a paired `onResponse` hook. It must preserve the Web hook's header semantics. */
+export type NodeResponseHook = (
+  response: NodeResponseContext,
+  req: NodeRequestContext,
+) => MaybePromise<void>
+
+/**
+ * A {@link ResponseHeadersView} over a Node outcome's plain header record - the direct-writer
+ * counterpart of handing a Web hook the response's `Headers`. Mutations write lowercase names (the
+ * wire form every runtime emits) and reads are case-insensitive across whatever casing earlier
+ * writers used; repeated values join with `", "` on read, matching `Headers.get`. A class with
+ * prototype methods (not per-call closures), memoized per context, so a request running several
+ * portable hooks allocates ONE small view total.
+ *
+ * Name resolution is prepared ONCE, the first time this view touches the record, rather than per
+ * operation. Resolving each name by scanning the record - the straightforward way to stay
+ * case-insensitive - allocates an `Object.keys` array and lowercases every stored key on every
+ * get/set, and that is paid per header, so a middleware writing a handful of them (security
+ * headers, CORS) paid it several times per request: profiling a realistic Node route put that scan
+ * at roughly a fifth of the framework's own CPU time. Instead one pass records an alias only for
+ * keys whose casing differs from their lowercase form - none, for the records the framework itself
+ * builds - after which every operation is a direct property access and the common all-lowercase
+ * record allocates no index at all. Stored casing is left exactly as the writer chose it.
+ */
+class RecordHeadersView implements ResponseHeadersView {
+  readonly #target: NodeResponseContext
+  #prepared = false
+  /** lowercase name -> the differently-cased key actually stored. Absent when none differ. */
+  #alias: Map<string, string> | undefined
+
+  constructor(target: NodeResponseContext) {
+    this.#target = target
+  }
+
+  #prepare(record: Record<string, string | readonly string[]>): void {
+    this.#prepared = true
+    // `Object.keys`, not `for...in`: the record is a `{}`-prototype literal on the render paths, and
+    // a for-in would let an enumerable `Object.prototype` property become a header on the wire.
+    const keys = Object.keys(record)
+    for (let i = 0; i < keys.length; i++) {
+      const key = keys[i] as string
+      // `key.toLowerCase() !== key` answers this too, but pays a runtime call plus a string compare
+      // for EVERY key on EVERY request, and the answer is almost always "already lowercase" - the
+      // framework, `c.set`, and middleware twins all write the wire spelling. An inline ASCII scan
+      // answers the common case without leaving the loop, and only a genuinely mixed-case key (a
+      // hand-written `X-Foo`) pays for the lowercase copy and the alias entry.
+      if (!RecordHeadersView.#hasUpperAscii(key)) continue
+      if (this.#alias === undefined) this.#alias = new Map()
+      this.#alias.set(key.toLowerCase(), key)
+    }
+  }
+
+  /** True when the name contains an ASCII `A`-`Z`, i.e. is not already the wire spelling. */
+  static #hasUpperAscii(name: string): boolean {
+    for (let i = 0; i < name.length; i++) {
+      const code = name.charCodeAt(i)
+      if (code >= 65 && code <= 90) return true
+    }
+    return false
+  }
+
+  /** The wire spelling of a header name, without paying `toLowerCase` when it already is one. */
+  static #lower(name: string): string {
+    return RecordHeadersView.#hasUpperAscii(name) ? name.toLowerCase() : name
+  }
+
+  /** The stored key for an already-lowercased name. Resolution is the prepared index ONLY - a
+   * lowercase own-property check, then the alias map - never a per-operation key scan: a rescan on
+   * every miss (and setting a NEW header is always a miss) walked and lowercased the whole record
+   * per write, which measured as the single largest cost of a portable hook walk on JSC. The alias
+   * index is complete for the record as first touched and for every write made through this view;
+   * a raw record write from a custom native twin uses lowercase names (the wire form the record
+   * documents), so it stays visible without a scan. */
+  #actual(lower: string): string {
+    const record = this.#target.headers
+    if (record !== undefined && Object.hasOwn(record, lower)) return lower
+    const known = this.#alias?.get(lower)
+    if (known !== undefined && record !== undefined && Object.hasOwn(record, known)) return known
+    return lower
+  }
+
+  /** The backing record if the outcome has one, prepared on first touch; `undefined` otherwise. */
+  #readable(): Record<string, string | readonly string[]> | undefined {
+    const existing = this.#target.headers
+    if (existing === undefined) return undefined
+    if (!this.#prepared) this.#prepare(existing)
+    return existing
+  }
+
+  /** As {@link #readable}, but creates the record when the outcome has none. A literal record from
+   * the render path is used AS-IS - values are strings/arrays, and assigning those through the
+   * inherited `__proto__` setter is a spec-level no-op, so the record cannot be polluted through
+   * this view; the one name that setter would swallow is stored via `defineProperty` in
+   * {@link set}/{@link append} instead. Copying to a null-prototype object here would demote every
+   * hook-carrying request's record to V8's dictionary mode (~2% of route throughput). */
+  #writable(): Record<string, string | readonly string[]> {
+    const existing = this.#target.headers
+    if (existing === undefined) {
+      const fresh: Record<string, string | readonly string[]> = {}
+      this.#target.headers = fresh
+      this.#prepared = true
+      return fresh
+    }
+    if (!this.#prepared) this.#prepare(existing)
+    return existing
+  }
+
+  /** Store under an attacker-influenceable name. `__proto__` (any casing is already lowercased)
+   * must not go through plain assignment - the inherited setter would silently swallow it - so it
+   * is defined as an own data property; every other name takes the fast plain store. */
+  static #store(
+    record: Record<string, string | readonly string[]>,
+    lower: string,
+    value: string | readonly string[],
+  ): void {
+    if (lower === "__proto__") {
+      Object.defineProperty(record, lower, {
+        value,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+      })
+      return
+    }
+    record[lower] = value
+  }
+
+  get(name: string): string | null {
+    const headers = this.#readable()
+    if (headers === undefined) return null
+    const value = headers[this.#actual(RecordHeadersView.#lower(name))]
+    if (value === undefined) return null
+    return typeof value === "string" ? value : (value.join(", ") ?? null)
+  }
+
+  has(name: string): boolean {
+    const headers = this.#readable()
+    return (
+      headers !== undefined && headers[this.#actual(RecordHeadersView.#lower(name))] !== undefined
+    )
+  }
+
+  set(name: string, value: string): void {
+    const headers = this.#writable()
+    const lower = RecordHeadersView.#lower(name)
+    // The common response record is already lowercase (framework middleware and c.set use the wire
+    // spelling). A set cannot need to replace a differently-cased key in that shape, so skip the
+    // own-property/alias lookup that reads and deletes pay for. Mixed-case records were indexed by
+    // #prepare and retain the full case-insensitive replacement semantics below.
+    if (this.#alias === undefined) {
+      RecordHeadersView.#store(headers, lower, value)
+      return
+    }
+    const actual = this.#actual(lower)
+    if (actual !== lower) {
+      delete headers[actual]
+      this.#alias?.delete(lower)
+    }
+    RecordHeadersView.#store(headers, lower, value)
+  }
+
+  append(name: string, value: string): void {
+    const headers = this.#writable()
+    const lower = RecordHeadersView.#lower(name)
+    if (this.#alias === undefined) {
+      const current = Object.hasOwn(headers, lower) ? headers[lower] : undefined
+      if (current === undefined) {
+        RecordHeadersView.#store(headers, lower, value)
+        return
+      }
+      RecordHeadersView.#store(
+        headers,
+        lower,
+        typeof current === "string" ? [current, value] : [...current, value],
+      )
+      return
+    }
+    const actual = this.#actual(lower)
+    const current = Object.hasOwn(headers, actual) ? headers[actual] : undefined
+    if (current === undefined) {
+      RecordHeadersView.#store(headers, lower, value)
+      return
+    }
+    if (actual !== lower) {
+      delete headers[actual]
+      this.#alias?.delete(lower)
+    }
+    RecordHeadersView.#store(
+      headers,
+      lower,
+      typeof current === "string" ? [current, value] : [...current, value],
+    )
+  }
+
+  delete(name: string): void {
+    const headers = this.#readable()
+    if (headers === undefined) return
+    const lower = RecordHeadersView.#lower(name)
+    if (this.#alias === undefined) {
+      delete headers[lower]
+      return
+    }
+    const actual = this.#actual(lower)
+    delete headers[actual]
+    if (actual !== lower) this.#alias?.delete(lower)
+  }
+}
+
+const RECORD_VIEW = Symbol("nifra.record-headers-view")
+
+export function recordHeadersView(target: NodeResponseContext): ResponseHeadersView {
+  const holder = target as NodeResponseContext & { [RECORD_VIEW]?: ResponseHeadersView }
+  let view = holder[RECORD_VIEW]
+  if (view === undefined) {
+    view = new RecordHeadersView(target)
+    holder[RECORD_VIEW] = view
+  }
+  return view
+}
 
 export interface NodeOutcomeRuntime {
   toOutcome(result: unknown, set: CtxSet): NodeServeOutcome
+  /** Materialize a buffered outcome for a Web response hook without losing its direct-write marker. */
+  toResponse(outcome: NodeServeOutcome): Response
   fromResponse(response: Response): NodeServeOutcome
   timeout(): NodeServeOutcome
+  /** The `Content-Type` this runtime's json render writes implicitly. The native hook walk
+   * materializes it into the hook-visible header record so a body hook's content-type checks see
+   * what will actually ship (the writer's own value - the wire is unchanged). */
+  readonly jsonContentType?: string
 }

package/src/server/node-outcome.ts

@@ -3,9 +3,25 @@
  * 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 { appendCookiesToResponse } from "./respond.ts"
+import {
+  appendCookiesToResponse,
+  applyStaticResponseHeaders,
+  markTaggedResponse,
+  normalizeBodylessResponse,
+  rememberMutableHeaders,
+  taggedResponseBody,
+} from "./respond.ts"
 import { type HandlerResult, isResponseResult } from "./runtime-core.ts"
 import type { CtxSet } from "./server.ts"
+import {
+  mergeStaticHeaderRecord,
+  type StaticResponseHeaders,
+  staticHeaderRecordCopy,
+} from "./static-headers.ts"
+
+function isBodylessStatus(status: number): boolean {
+  return status === 204 || status === 205 || status === 304
+}
 
 /**
  * What {@link Server.resolveNode} returns: either a plain-data render the `@nifrajs/node` adapter writes
@@ -19,8 +35,8 @@ export type NodeServeOutcome =
   | {
       readonly kind: "json"
       readonly status: number
-      /** `c.set.headers` backing, or `undefined` when the handler never set a header. */
-      readonly headers: Readonly<Record<string, string>> | undefined
+      /** Header record after native hooks; repeated values are retained as arrays. */
+      readonly headers: Readonly<Record<string, string | readonly string[]>> | undefined
       /** Queued `Set-Cookie` lines, or `undefined`; the adapter emits one header line each. */
       readonly cookies: readonly string[] | undefined
       /** The JSON body already stringified, or `null` for an empty (204) response. */
@@ -48,27 +64,98 @@ export function toNodeOutcome(result: HandlerResult, set: CtxSet): NodeServeOutc
         kind: "body",
         status: body.status,
         headers: appendCookiesToNodeHeaders(body.headers, set._cookies),
-        body: body.body,
+        body: isBodylessStatus(body.status) ? new Uint8Array(0) : body.body,
       }
     }
-    return nodeOutcomeFromResponse(appendCookiesToResponse(result.toResponse(), set))
+    return nodeOutcomeFromResponse(
+      appendCookiesToResponse(normalizeBodylessResponse(result.toResponse()), set),
+    )
   }
   if (result instanceof Response) {
-    return nodeOutcomeFromResponse(appendCookiesToResponse(result, set))
+    return nodeOutcomeFromResponse(appendCookiesToResponse(normalizeBodylessResponse(result), set))
   }
   const status = set.status ?? (result === undefined ? 204 : 200)
+  const body = result === undefined || isBodylessStatus(status) ? null : JSON.stringify(result)
   return {
     kind: "json",
     status,
     headers: set._headers,
     cookies: set._cookies,
-    body: result === undefined ? null : JSON.stringify(result),
+    body,
+  }
+}
+
+/**
+ * Materialize a buffered node outcome only when a Web `onResponse` hook needs to see a real
+ * `Response`. The marker lets an in-place hook (`response.headers.set(...); return response`) go back
+ * to the direct socket writer without draining the body through a Web stream. A hook that replaces,
+ * consumes, or otherwise changes the response naturally loses the marker and stays on the portable
+ * response path.
+ */
+export function nodeOutcomeToResponse(outcome: NodeServeOutcome): Response {
+  if (outcome.kind === "response") return outcome.response
+  // A prebuilt `Headers` on purpose: undici's Response constructor takes a fast clone path for a
+  // `Headers` instance, which measured cheaper than handing it a pairs list to fill (pairs pay a
+  // webidl sequence conversion per entry).
+  const headers = new Headers()
+  if (outcome.headers !== undefined) {
+    for (const [name, value] of Object.entries(outcome.headers)) {
+      if (typeof value !== "string") {
+        for (const item of value) headers.append(name, item)
+      } else {
+        headers.set(name, value as string)
+      }
+    }
   }
+  if (outcome.kind === "json") {
+    if (outcome.cookies !== undefined) {
+      for (const cookie of outcome.cookies) headers.append("set-cookie", cookie)
+    }
+    if (outcome.body !== null && headers.get("content-type") === null) {
+      headers.set("content-type", "application/json;charset=utf-8")
+    }
+  }
+  if (isBodylessStatus(outcome.status)) headers.delete("content-length")
+  const body = isBodylessStatus(outcome.status) ? null : outcome.body
+  // `Uint8Array<ArrayBufferLike>` vs the lib's body-init generic - runtime-accepted everywhere,
+  // only the type narrows wrong under the DOM-free lib set (same idiom as the Headers cast in
+  // transport-codec.ts).
+  const response = new Response(body as ConstructorParameters<typeof Response>[0], {
+    status: outcome.status,
+    headers,
+  })
+  if (body !== null) markTaggedResponse(response, body)
+  rememberMutableHeaders(response.headers)
+  return response
 }
 
-const NODE_RESPONSE_BODY = Symbol.for("nifra.response.body")
+/**
+ * Fold declared static headers into a resolved outcome, ONCE, before any native response hook runs -
+ * so a header or body twin sees the declared values through its view exactly as it would see values
+ * a hook had written, and so the no-hook direct-writer path (which never calls the finish step) still
+ * ships them.
+ *
+ * The record handed over is always a fresh copy: the Node writers mutate the outcome's record in
+ * place (content-type, content-length, cookies), and the static record is shared by every request.
+ * Its names are already lowercase, so the writer's all-lowercase fast path still holds.
+ */
+export function withStaticNodeHeaders(
+  outcome: NodeServeOutcome,
+  statics: StaticResponseHeaders,
+): NodeServeOutcome {
+  if (outcome.kind === "response") {
+    return { kind: "response", response: applyStaticResponseHeaders(outcome.response, statics) }
+  }
+  const own = outcome.headers
+  const headers =
+    own === undefined
+      ? staticHeaderRecordCopy(statics)
+      : mergeStaticHeaderRecord(statics.record, own)
+  return { ...outcome, headers }
+}
 
 export function nodeOutcomeFromResponse(response: Response): NodeServeOutcome {
+  response = normalizeBodylessResponse(response)
   const body = nodeResponseBody(response)
   return body === undefined
     ? { kind: "response", response }
@@ -77,8 +164,7 @@ export function nodeOutcomeFromResponse(response: Response): NodeServeOutcome {
 
 function nodeResponseBody(response: Response): string | Uint8Array | undefined {
   if (response.bodyUsed) return undefined
-  const body = (response as { readonly [NODE_RESPONSE_BODY]?: unknown })[NODE_RESPONSE_BODY]
-  return typeof body === "string" || body instanceof Uint8Array ? body : undefined
+  return taggedResponseBody(response)
 }
 
 function responseHeadersForNode(
@@ -86,12 +172,12 @@ function responseHeadersForNode(
 ): Readonly<Record<string, string | readonly string[]>> | undefined {
   let headers: Record<string, string | readonly string[]> | undefined
   response.headers.forEach((value, key) => {
-    headers ??= {}
+    headers ??= Object.create(null) as Record<string, string | readonly string[]>
     headers[key] = value
   })
   const setCookies = response.headers.getSetCookie?.()
   if (setCookies !== undefined && setCookies.length > 0) {
-    headers ??= {}
+    headers ??= Object.create(null) as Record<string, string | readonly string[]>
     headers["set-cookie"] = setCookies
   }
   return headers
@@ -102,8 +188,8 @@ function appendCookiesToNodeHeaders(
   cookies: readonly string[] | undefined,
 ): Readonly<Record<string, string | readonly string[]>> | undefined {
   if (cookies === undefined || cookies.length === 0) return headers
-  const out: Record<string, string | readonly string[]> =
-    headers === undefined ? {} : { ...headers }
+  const out = Object.create(null) as Record<string, string | readonly string[]>
+  if (headers !== undefined) Object.assign(out, headers)
   const existing = out["set-cookie"]
   const setCookies =
     existing === undefined ? [] : typeof existing === "string" ? [existing] : [...existing]

package/src/server/query.ts

@@ -22,11 +22,36 @@ export function searchOf(url: string): string {
  * (an explicit 400 beats silently picking one). */
 export type QueryValue = string | string[]
 
+// V8 stores a FRESHLY-SLICED string key on a dictionary-mode (null-prototype) record ~13x slower
+// than an already-internalized one - the store internalizes the fresh string every time (measured
+// ~300ns vs ~22ns for a literal key; it was the single largest slice of query parsing on Node).
+// JSC has no such cliff (~2.5ns either way), so the whole scheme is bypassed there. Interning
+// repeated keys through a small bounded map hands every later request the SAME first-seen (and by
+// then internalized) string, so the store takes the fast path. Query/cookie key sets in a real app
+// are tiny and stable; a hostile high-cardinality caller stops being cached at the cap and an
+// oversized key never enters, so both degrade to exactly today's uncached behavior - the returned
+// key is always value-equal to the input, cached or not.
+const FRESH_KEY_STORE_IS_CHEAP = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined"
+const PARSE_KEY_INTERN = new Map<string, string>()
+const PARSE_KEY_INTERN_CAP = 2048
+const PARSE_KEY_MAX_LENGTH = 64
+
+/** Return a value-equal, likely-internalized copy of a parsed record key. See the note above. */
+export function internParseKey(key: string): string {
+  if (FRESH_KEY_STORE_IS_CHEAP) return key
+  const hit = PARSE_KEY_INTERN.get(key)
+  if (hit !== undefined) return hit
+  if (key.length > PARSE_KEY_MAX_LENGTH || PARSE_KEY_INTERN.size >= PARSE_KEY_INTERN_CAP) return key
+  PARSE_KEY_INTERN.set(key, key)
+  return key
+}
+
 /** Accumulate into a NULL-PROTOTYPE record (every call site below creates one): with no inherited
  * `constructor`/`toString`/`__proto__` accessors, a hostile key is just an own data key - the
  * promotion logic can't collide with `Object.prototype` members, and `__proto__` needs no special
  * case (direct assignment on a null-proto object creates an own property). */
-function setQueryValue(out: Record<string, QueryValue>, key: string, value: string): void {
+function setQueryValue(out: Record<string, QueryValue>, rawKey: string, value: string): void {
+  const key = internParseKey(rawKey)
   const existing = out[key]
   if (existing === undefined) {
     out[key] = value

package/src/server/request-context.ts

@@ -32,6 +32,13 @@ class LazyResponseControls implements CtxSet {
   _cookies?: string[]
 
   get headers(): Record<string, string> {
+    // A plain literal record on purpose: values here are strings, and assigning a STRING through
+    // the inherited `__proto__` setter is a silent no-op by spec - it cannot mutate the record's
+    // prototype - so a literal object is not pollutable through header writes. The trade is that a
+    // header literally named "__proto__" is dropped rather than stored (the sinks that accept
+    // attacker-influenced names guard that name explicitly); in exchange the record stays in V8's
+    // fast property mode, which a null-prototype object never enters - measured at ~2% of
+    // throughput on a realistic middleware route on BOTH V8 and JSC.
     this._headers ??= {}
     return this._headers
   }
@@ -114,12 +121,23 @@ export class RequestContext implements RawContext {
     this.maxBodyBytes = maxBodyBytes as number
   }
 
+  /**
+   * The no-timeout context: `c.signal`/`c.budget` fall back to the never-abort signal and the
+   * unbounded budget, which is exactly what the request would have been handed, so the two slots
+   * are left unwritten instead of initialized. `search` carries the router's already-split query
+   * string when it has one; `undefined` leaves `c.query` to re-scan the URL lazily.
+   */
   static native(
     source: RequestSource,
     params: Record<string, string>,
+    search: string | undefined,
     maxBodyBytes: number,
+    platform?: Platform,
   ): RequestContext {
-    return new RequestContext(source, params, maxBodyBytes)
+    const context = new RequestContext(source, params, maxBodyBytes)
+    if (search !== undefined) context.searchValue = search
+    if (platform !== undefined) context.platformValue = platform
+    return context
   }
 
   [CONTEXT_SET](): CtxSet | undefined {
@@ -166,6 +184,10 @@ export class RequestContext implements RawContext {
     return requestOf(this.source)
   }
 
+  header(name: string): string | null {
+    return headerOf(this.source, name)
+  }
+
   json(body: unknown, init?: ResponseInit | number): Response {
     return Response.json(body, statusInit(init))
   }