@nifrajs/core 2.8.2 → 2.9.0

package/src/server/respond.ts

@@ -11,6 +11,7 @@ import {
   isResponseResult,
 } from "./runtime-core.ts"
 import type { CtxSet, RawContext } from "./server.ts"
+import { mergeStaticHeaderRecord, type StaticResponseHeaders } from "./static-headers.ts"
 
 /** Build the response headers init. The common path (no `c.set`) returns `undefined` so `Response`
  * gets no `headers` at all. Cookies force a `Headers` object - multiple `Set-Cookie`s can't live in a
@@ -26,15 +27,273 @@ function headersInit(set: CtxSet): Record<string, string> | Headers | undefined
 // Keep the fast JSON respond path byte-identical to `Response.json` without probing it at module
 // scope: workerd forbids `Response.json()` during startup. A shared `Headers` is safe to reuse
 // across responses: the Response constructor copies `init.headers` into its own list.
-const JSON_CT_HEADERS = new Headers({
-  "content-type": "application/json;charset=utf-8",
-})
+const JSON_CONTENT_TYPE = "application/json;charset=utf-8"
+const JSON_CT_HEADERS = new Headers({ "content-type": JSON_CONTENT_TYPE })
 const JSON_INIT_200: ResponseInit = { status: 200, headers: JSON_CT_HEADERS }
 
+/**
+ * Build the per-server shapes for a validated static header record. The JSON init is prebuilt once
+ * here so a static-middleware app's fused JSON lane pays a shared init read instead of a header write
+ * per declared name per request - the same reuse the hook-free lane already gets from
+ * {@link JSON_INIT_200}.
+ */
+export function buildStaticResponseHeaders(
+  record: Readonly<Record<string, string>>,
+): StaticResponseHeaders {
+  const frozen = Object.freeze({ ...record })
+  const jsonHeaders = new Headers({ ...frozen, "content-type": JSON_CONTENT_TYPE })
+  let responseJson: ResponseInit | undefined
+  return {
+    record: frozen,
+    entries: Object.freeze(Object.entries(frozen)),
+    jsonHeaders,
+    jsonInit200: { status: 200, headers: jsonHeaders },
+    responseJsonInit200: () => {
+      responseJson ??= {
+        status: 200,
+        headers: new Headers({ ...frozen, "content-type": responseJsonContentType() }),
+      }
+      return responseJson
+    },
+  }
+}
+
+/**
+ * Apply the static defaults to an ALREADY-BUILT response - the framework's error/404/timeout renders
+ * and a handler-returned `Response`, none of which go through the header init below. Defaults, so a
+ * name the response already carries is left alone. A guarded `Headers` (a raw `fetch()` result a
+ * handler returned) rejects every write, so the first `set` throws with nothing applied and the
+ * retry lands on a mutable copy.
+ */
+export function applyStaticResponseHeaders(
+  response: Response,
+  statics: StaticResponseHeaders,
+): Response {
+  const headers = response.headers
+  if (knownMutableHeaders(headers)) {
+    applyStaticDefaults(headers, statics)
+    return response
+  }
+  try {
+    applyStaticDefaults(headers, statics)
+  } catch {
+    const clone = new Response(response.body, response)
+    applyStaticDefaults(clone.headers, statics)
+    return stamped(clone)
+  }
+  rememberMutableHeaders(headers)
+  return response
+}
+
+/**
+ * Build a JSON response carrying the declared headers, the cheapest way this runtime allows.
+ *
+ * Everywhere but Deno that is one constructor call with the prebuilt init. Deno charges far more to
+ * ingest a header init than to mutate a built response's `Headers` - the same asymmetry the
+ * caller-set-headers path above already routes around - and handing it the prebuilt init measured
+ * 15% BELOW writing the same headers from a response hook, which would make declaring them a
+ * pessimization on that runtime.
+ */
+function staticJsonResponse(
+  body: string,
+  status: number,
+  statics: StaticResponseHeaders,
+  contentType: string,
+  init: ResponseInit,
+): Response {
+  if (IS_DENO) {
+    return denoResponseWithJsonBody(
+      body,
+      status,
+      statics.record as Record<string, string>,
+      contentType,
+    )
+  }
+  return new Response(body, init)
+}
+
+function withStatics(response: Response, statics: StaticResponseHeaders | undefined): Response {
+  return statics === undefined ? response : applyStaticResponseHeaders(response, statics)
+}
+
+function applyStaticDefaults(headers: Headers, statics: StaticResponseHeaders): void {
+  for (const [name, value] of statics.entries) {
+    if (!headers.has(name)) headers.set(name, value)
+  }
+}
+
+/** Fold the static defaults under whatever shape the request's own headers took. */
+function withStaticHeaderInit(
+  own: Record<string, string> | Headers | undefined,
+  statics: StaticResponseHeaders,
+): Record<string, string> | Headers {
+  if (own === undefined) return statics.record
+  if (own instanceof Headers) {
+    // Freshly built by `headersInit` for the cookies case, so mutating it in place is safe.
+    applyStaticDefaults(own, statics)
+    return own
+  }
+  return mergeStaticHeaderRecord(statics.record, own) as Record<string, string>
+}
+
+// Deno's Response/Headers implementation ingests a plain header record much more slowly than it
+// mutates an already-created response (the difference is material on realistic middleware routes
+// that add several security/CORS headers). Bun is faster on the record constructor, so keep the
+// portable constructor path there and select the Deno-specific shape only for Web responses that
+// carry a plain record. The first request lazily probes Deno's native JSON content-type so this
+// preserves the runtime's Response.json contract instead of baking in Bun's charset suffix.
+const IS_DENO = typeof (globalThis as { Deno?: unknown }).Deno !== "undefined"
+let denoJsonContentType: string | undefined
+
+function responseJsonContentType(): string {
+  if (denoJsonContentType === undefined) {
+    denoJsonContentType = Response.json(0).headers.get("content-type") ?? "application/json"
+  }
+  return denoJsonContentType
+}
+
+function denoResponseWithJsonBody(
+  body: string,
+  status: number,
+  headers: Record<string, string>,
+  defaultContentType = responseJsonContentType(),
+): Response {
+  const response = new Response(body, { status })
+  let hasContentType = false
+  for (const [name, value] of Object.entries(headers)) {
+    response.headers.set(name, value)
+    if (name.toLowerCase() === "content-type") {
+      hasContentType = true
+    }
+  }
+  if (!hasContentType) response.headers.set("content-type", defaultContentType)
+  return response
+}
+
+// The framework-buffered-body marker shared with the Node adapter: a Response carrying it exposes
+// its already-serialized bytes without draining. On the Web serving paths it exists ONLY when a
+// registered body/raw hook needs it, so hook-less apps pay nothing.
+const RESPONSE_BODY = Symbol.for("nifra.response.body")
+
+/**
+ * Headers objects the framework itself constructed - guaranteed mutable, no guard. Response
+ * middleware adapters consult this before falling back to a mutability probe, so the hot path
+ * (every framework-rendered response) never pays per-request `Headers` operations to learn what
+ * construction already knew; only a handler-returned foreign `Response` (a raw `fetch()` result,
+ * whose headers are guarded immutable) reaches the probe.
+ */
+const MUTABLE_RESPONSE_HEADERS = new WeakSet<Headers>()
+
+export function knownMutableHeaders(headers: Headers): boolean {
+  return MUTABLE_RESPONSE_HEADERS.has(headers)
+}
+
+export function rememberMutableHeaders(headers: Headers): void {
+  MUTABLE_RESPONSE_HEADERS.add(headers)
+}
+
+/** Stamp a framework-constructed Response's headers as known-mutable, and return it. */
+function stamped(response: Response): Response {
+  MUTABLE_RESPONSE_HEADERS.add(response.headers)
+  return response
+}
+
+function isBodylessStatus(status: number): boolean {
+  return status === 204 || status === 205 || status === 304
+}
+
+/** Normalize handler-produced bodyless responses before response middleware sees them. */
+export function normalizeBodylessResponse(response: Response): Response {
+  if (!isBodylessStatus(response.status)) return response
+  if (response.body === null && !response.headers.has("content-length")) return response
+  const headers = new Headers(response.headers)
+  headers.delete("content-length")
+  return stamped(
+    new Response(null, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    }),
+  )
+}
+
+type TaggedResponseMarker = {
+  readonly body: string | Uint8Array
+  readonly owner?: object
+}
+
+type ResponseBodyTagOption = false | true | object | undefined
+
+/** The framework-serialized bytes riding a tagged Response, or `undefined` for raw/streamed ones. */
+export function taggedResponseBody(
+  response: Response,
+  owners?: ReadonlySet<object>,
+): string | Uint8Array | undefined {
+  const marker = (response as { [RESPONSE_BODY]?: string | Uint8Array | TaggedResponseMarker })[
+    RESPONSE_BODY
+  ]
+  if (owners !== undefined) {
+    // A Web response is framework-buffered only when this app (or an intentionally merged app) put
+    // the marker on it. The legacy primitive marker remains readable by the Node bridge, but must
+    // not let an arbitrary response impersonate a local framework body on the Web hook path.
+    if (
+      typeof marker !== "object" ||
+      marker === null ||
+      marker instanceof Uint8Array ||
+      marker.owner === undefined ||
+      !owners.has(marker.owner)
+    ) {
+      return undefined
+    }
+    return marker.body
+  }
+  if (typeof marker === "string" || marker instanceof Uint8Array) return marker
+  return marker?.body
+}
+
+export function taggedResponseOwner(response: Response): object | undefined {
+  const marker = (response as { [RESPONSE_BODY]?: string | Uint8Array | TaggedResponseMarker })[
+    RESPONSE_BODY
+  ]
+  return typeof marker === "object" && marker !== null && "owner" in marker
+    ? marker.owner
+    : undefined
+}
+
+export function markTaggedResponse(
+  response: Response,
+  body: string | Uint8Array,
+  owner?: object,
+): Response {
+  Object.defineProperty(response, RESPONSE_BODY, {
+    value: owner === undefined ? body : ({ body, owner } satisfies TaggedResponseMarker),
+  })
+  return response
+}
+
+function tagged(
+  response: Response,
+  body: string,
+  tagResponseBody: ResponseBodyTagOption,
+): Response {
+  stamped(response)
+  return tagResponseBody === false || tagResponseBody === undefined
+    ? response
+    : markTaggedResponse(
+        response,
+        body,
+        typeof tagResponseBody === "object" ? tagResponseBody : undefined,
+      )
+}
+
 /** Fused-lane respond when `c.set` is untouched. Bun 1.3's native `Response.json` now beats the
  * older hand-inlined stringify + Response construction on this lane while preserving the exact
  * body/content-type contract; keep the generic fallback for non-JSON values. */
-export function fusedRespondNoSet(result: unknown): Response {
+export function fusedRespondNoSet(
+  result: unknown,
+  tagResponseBody: ResponseBodyTagOption = false,
+  statics?: StaticResponseHeaders,
+): Response {
   if (
     result !== undefined &&
     !(result instanceof Response) &&
@@ -42,43 +301,153 @@ export function fusedRespondNoSet(result: unknown): Response {
     result !== null &&
     !isResponseResult(result)
   ) {
-    return Response.json(result)
+    // Deno's cheapest shape for this lane is its own `Response.json` (which fuses serialization and
+    // construction natively, and sets the content-type natively) followed by post-construction header
+    // writes - NOT a header init, which measured 15% below writing the same names from a hook. So on
+    // 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)
+      for (const [name, value] of statics.entries) response.headers.set(name, value)
+      return stamped(response)
+    }
+    // With declared static headers the prebuilt init already carries them plus the JSON
+    // 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
+      // 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.
+      if (body !== undefined)
+        return tagged(
+          statics === undefined
+            ? new Response(body, JSON_INIT_200)
+            : tagResponseBody
+              ? staticJsonResponse(body, 200, statics, JSON_CONTENT_TYPE, statics.jsonInit200)
+              : staticJsonResponse(
+                  body,
+                  200,
+                  statics,
+                  responseJsonContentType(),
+                  statics.responseJsonInit200(),
+                ),
+          body,
+          tagResponseBody,
+        )
+    }
+    return stamped(
+      statics === undefined
+        ? Response.json(result)
+        : Response.json(result, statics.responseJsonInit200()),
+    )
   }
-  return toResponse(result as HandlerResult, EMPTY_RESPONSE_CONTROLS)
+  return toResponse(result as HandlerResult, EMPTY_RESPONSE_CONTROLS, tagResponseBody, statics)
 }
 
 /** Fused-lane respond with a context: read `c.set` once; untouched (the common case) -> the fast
  * JSON respond; touched -> the generic `toResponse` with those controls (statuses, headers, cookies). */
-export function fusedRespond(result: unknown, ctx: RawContext): Response {
+export function fusedRespond(
+  result: unknown,
+  ctx: RawContext,
+  tagResponseBody: ResponseBodyTagOption = false,
+  statics?: StaticResponseHeaders,
+): Response {
   const set = ctx[CONTEXT_SET]()
-  if (set === undefined) return fusedRespondNoSet(result)
-  return toResponse(result as HandlerResult, set)
+  if (set === undefined) return fusedRespondNoSet(result, tagResponseBody, statics)
+  return toResponse(result as HandlerResult, set, tagResponseBody, statics)
 }
 
-export function toResponse(result: HandlerResult, set: CtxSet): Response {
+export function toResponse(
+  result: HandlerResult,
+  set: CtxSet,
+  tagResponseBody: ResponseBodyTagOption = false,
+  statics?: StaticResponseHeaders,
+): Response {
   if (isResponseResult(result)) {
-    return appendCookiesToResponse(result.toResponse(), set)
+    return withStatics(
+      appendCookiesToResponse(normalizeBodylessResponse(result.toResponse()), set),
+      statics,
+    )
   }
   if (result instanceof Response) {
-    return appendCookiesToResponse(result, set)
+    return withStatics(appendCookiesToResponse(normalizeBodylessResponse(result), set), statics)
   }
-  const headers = headersInit(set)
+  // 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.
+  const own = headersInit(set)
+  const headers = statics === undefined ? own : withStaticHeaderInit(own, statics)
+  const jsonCtHeaders = statics === undefined ? JSON_CT_HEADERS : statics.jsonHeaders
   const status = set.status ?? (result === undefined ? 204 : 200)
-  if (headers === undefined && result !== undefined) {
+  if (status === 204 || status === 205 || status === 304) {
+    return stamped(new Response(null, headers === undefined ? { status } : { status, headers }))
+  }
+  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
     if (body !== undefined) {
-      return new Response(
+      const init: ResponseInit =
+        status === 200
+          ? (statics?.jsonInit200 ?? JSON_INIT_200)
+          : { status, headers: jsonCtHeaders }
+      return tagged(
+        statics === undefined
+          ? new Response(body, init)
+          : staticJsonResponse(body, status, statics, JSON_CONTENT_TYPE, init),
         body,
-        status === 200 ? JSON_INIT_200 : { status, headers: JSON_CT_HEADERS },
+        tagResponseBody,
       )
     }
   }
   const init: ResponseInit = headers === undefined ? { status } : { status, headers }
-  return result === undefined ? new Response(null, init) : Response.json(result, init)
+  if (result === undefined) return stamped(new Response(null, init))
+  if (tagResponseBody) {
+    const body = JSON.stringify(result) as string | undefined
+    if (body !== undefined) {
+      const response =
+        IS_DENO && !(headers instanceof Headers)
+          ? denoResponseWithJsonBody(
+              body,
+              status,
+              headers as Record<string, string>,
+              JSON_CT_HEADERS.get("content-type") ?? "application/json;charset=utf-8",
+            )
+          : new Response(body, { status, headers: withJsonContentType(headers) })
+      return tagged(
+        response,
+        body,
+        typeof tagResponseBody === "object" ? tagResponseBody : undefined,
+      )
+    }
+  }
+  if (IS_DENO && headers !== undefined && !(headers instanceof Headers)) {
+    const body = JSON.stringify(result) as string | undefined
+    if (body !== undefined) return stamped(denoResponseWithJsonBody(body, status, headers))
+  }
+  return stamped(Response.json(result, init))
+}
+
+// Add a JSON content-type without pre-building a `Headers` instance just to check-and-set one key:
+// `new Headers(record)` measured ~8us/call on V8 (Deno) for a handful of header entries - it's a
+// full parse-and-validate of every entry, done here only to ask "is content-type present," when
+// `new Response(body, { headers })` a few lines up already does that same ingestion once, for free,
+// on whatever shape is handed to it. A plain `Record` (the common case - no cookies queued) gets a
+// shallow copy; an existing `Headers` (the cookies case - freshly built by `headersInit`, not
+// exposed elsewhere) is mutated in place, same as before.
+function withJsonContentType(
+  headers: Record<string, string> | Headers | undefined,
+): Record<string, string> | Headers {
+  if (headers === undefined) return JSON_CT_HEADERS
+  if (headers instanceof Headers) {
+    if (!headers.has("content-type")) headers.set("content-type", "application/json;charset=utf-8")
+    return headers
+  }
+  return Object.hasOwn(headers, "content-type")
+    ? headers
+    : { ...headers, "content-type": "application/json;charset=utf-8" }
 }
 
 export function appendCookiesToResponse(response: Response, set: CtxSet): Response {

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

@@ -29,6 +29,17 @@
  * That is not an inconsistency to paper over: a strict schema has already declared that extra fields
  * are an error, and a stripping one has declared they are ignorable. Enforcement honours what the
  * author wrote rather than overriding it.
+ *
+ * ## What enforcement costs
+ *
+ * Less than it looks like it should. With a compiled validator (`@nifrajs/schema`'s `t` compiles at
+ * construction; zod/valibot equivalents are similarly cheap), the check itself measures in the
+ * ~100ns-per-response range - on a realistic middleware-carrying route, enforce mode benchmarks
+ * within measurement noise of the same route with no contract at all, on Bun and Node alike. The
+ * one real cost is structural: a contracted route cannot take the bare-route fused lane, because
+ * the check needs the handler's VALUE before it becomes bytes. A route with any middleware, derive,
+ * or lifecycle hook has already left that lane, so for the routes that look like production the
+ * contract is effectively free - declare it.
  */
 import type { StandardIssue, StandardResult, StandardSchemaV1 } from "../schema/standard.ts"
 import { INSTALL_RESPONSE_CONTRACT } from "./install.ts"
@@ -147,9 +158,12 @@ interface ResponseContractInstallable {
  * Install it before the routes it should cover - like `idempotency()`, the decision is made per route
  * at registration, so routes registered earlier are not retroactively covered.
  *
- * A contracted route leaves the fused and native fast paths, because the check needs the handler's
- * value before it becomes bytes. That is the same trade an idempotent route makes, and the reason this
- * is opt-in rather than always on.
+ * The check itself is cheap - with a compiled validator it measures in the ~100ns-per-response
+ * range, within benchmark noise of an uncontracted route on any route that carries middleware or a
+ * derive. What a contracted route does give up is the bare-route fused lane (the check needs the
+ * handler's value before it becomes bytes), which only a route with NO other lifecycle steps was
+ * taking anyway. Opt-in because not installing the plugin keeps the lane out of the bundle, not
+ * because enforcement is expensive.
  */
 export function responseContract(mode: ResponseContractMode = "warn"): IdentityPlugin {
   const runtime: ResponseContractRuntime = {

package/src/server/server-types.ts

@@ -9,6 +9,12 @@ import type { Method } from "../router/router.ts"
 import type { ClientIpTrust } from "./client-ip.ts"
 import type { Context, Platform, RouteSchema } from "./context.ts"
 import type { Logger } from "./logger.ts"
+import type {
+  NodeRequestHook,
+  NodeResponseHook,
+  ResponseBodyHook,
+  ResponseHeadersHook,
+} from "./node-outcome-hook.ts"
 import type { MaybePromise, OnRequestResult } from "./server.ts"
 
 /**
@@ -187,10 +193,46 @@ export interface RunningServer {
 export interface Middleware {
   readonly name?: string
   readonly onRequest?: (req: Request, platform?: Platform) => MaybePromise<OnRequestResult>
+  /** Allocation-light Node equivalent of `onRequest` for header-only hooks. */
+  readonly onNodeRequest?: NodeRequestHook
   readonly around?: <T>(context: Context, next: () => MaybePromise<T>) => MaybePromise<T>
   readonly beforeHandle?: (context: Context) => MaybePromise<unknown>
   readonly afterHandle?: (result: unknown, context: Context) => MaybePromise<unknown>
   readonly onResponse?: (response: Response, req: Request) => MaybePromise<Response>
+  /**
+   * Header-only equivalent of `onResponse` for the Node-direct serializer. It is used only when every
+   * response hook in the app supplies this paired native implementation; arbitrary response transforms
+   * continue through the Web Response path.
+   */
+  readonly onNodeResponse?: NodeResponseHook
+  /**
+   * Response headers with NO per-request decision behind them. Declared here instead of written by a
+   * hook, they are folded into response construction, so a bundle that only sets static headers does
+   * not cost the app its fused/native lanes (see {@link Server.responseHeaders}). They are defaults:
+   * anything the request produced wins. Reach for `onResponseHeaders` the moment a value depends on
+   * the request, the route, or the response.
+   */
+  readonly responseHeaders?: Readonly<Record<string, string>>
+  /**
+   * PORTABLE header-only response hook - the recommended shape when the middleware only reads or
+   * writes headers. One implementation runs on every runtime: inside the Web `onResponse` walk
+   * against the response's own `Headers`, and on Node as a self-paired native hook against the
+   * outcome record - so it never forces the Node adapter off its direct writer. Use `onResponse` +
+   * an optional `onNodeResponse` twin only when the hook must see a real `Response`.
+   */
+  readonly onResponseHeaders?: ResponseHeadersHook
+  /**
+   * PORTABLE post-serialization body hook - the payload tier. Receives the final
+   * framework-serialized bytes (already resident on every runtime; no stream is drained) plus the
+   * header view and status, and may return replacement bytes. Raw handler-returned `Response`s
+   * (proxies, SSE, streamed SSR) are skipped by contract - transforming those needs `onResponse`.
+   */
+  readonly onResponseBody?: ResponseBodyHook
+  /**
+   * Response transform for untagged/raw responses (streams, proxied fetches, and framework errors).
+   * Framework-serialized payloads use `onResponseBody` and remain on the Node direct lane.
+   */
+  readonly onResponseRaw?: (response: Response, req: Request) => MaybePromise<Response>
   readonly onResponseFinalized?: (outcome: ResponseFinalization, req: Request) => MaybePromise<void>
   readonly onError?: (error: unknown, context: Context) => MaybePromise<unknown>
 }