@nifrajs/core 2.13.0 → 3.1.0

package/src/server/node-outcome.ts

@@ -11,7 +11,14 @@ import {
   rememberMutableHeaders,
   taggedResponseBody,
 } from "./respond.ts"
-import { type HandlerResult, isResponseResult } from "./runtime-core.ts"
+import {
+  EMPTY_RESPONSE_CONTROLS,
+  type HandlerResult,
+  isResponseResult,
+  type PlainRender,
+  plainRenderHeaders,
+  type ResponseResult,
+} from "./runtime-core.ts"
 import type { CtxSet } from "./server.ts"
 import {
   mergeStaticHeaderRecord,
@@ -58,6 +65,8 @@ export type NodeServeOutcome =
  */
 export function toNodeOutcome(result: HandlerResult, set: CtxSet): NodeServeOutcome {
   if (isResponseResult(result)) {
+    const plain = result.plain
+    if (plain !== undefined) return plainNodeOutcome(plain, set)
     const body = result.toNodeBody?.()
     if (body !== undefined) {
       return {
@@ -85,6 +94,24 @@ export function toNodeOutcome(result: HandlerResult, set: CtxSet): NodeServeOutc
   }
 }
 
+/**
+ * A `status(...)` (or any other {@link PlainRender} carrier) on the node lane: the same `kind: "json"`
+ * outcome a handler's plain return produces, so an early exit is written to the socket by the same
+ * direct writer, with a `content-length`, and never builds a `Response`.
+ */
+export function plainNodeOutcome(plain: PlainRender, set: CtxSet): NodeServeOutcome {
+  return {
+    kind: "json",
+    status: plain.status,
+    headers: plainRenderHeaders(plain, set),
+    cookies: set._cookies,
+    body:
+      plain.body === undefined || isBodylessStatus(plain.status)
+        ? null
+        : JSON.stringify(plain.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
@@ -162,8 +189,22 @@ export function withStaticNodeHeaders(
   return { ...outcome, headers }
 }
 
-export function nodeOutcomeFromResponse(response: Response): NodeServeOutcome {
-  response = normalizeBodylessResponse(response)
+/**
+ * The node lane's `wrapResponse`: what an early exit built OUTSIDE the handler's finalizer renders as
+ * - an `onRequest` hook's `Response`, a mount's, and every framework error render.
+ *
+ * A plain-data carrier ({@link plainError}, `status(...)`) takes the same `kind: "json"` lane a
+ * handler's plain return takes: no `Response` built, and none drained. `EMPTY_RESPONSE_CONTROLS`
+ * rather than the request's `c.set` on purpose - these renders happen where no context exists (before
+ * routing, or after it was abandoned), which is exactly why they are wrapped rather than finalized.
+ */
+export function nodeOutcomeFromResponse(result: Response | ResponseResult): NodeServeOutcome {
+  if (!(result instanceof Response)) {
+    const plain = result.plain
+    if (plain !== undefined) return plainNodeOutcome(plain, EMPTY_RESPONSE_CONTROLS)
+    return nodeOutcomeFromResponse(result.toResponse())
+  }
+  const response = normalizeBodylessResponse(result)
   const body = nodeResponseBody(response)
   return body === undefined
     ? { kind: "response", response }

package/src/server/plugin.ts

@@ -86,7 +86,7 @@ export interface PluginTypeCollapsed {
  * every route type flowing through it is about to be widened away.
  */
 // biome-ignore lint/suspicious/noExplicitAny: matches any Server shape to inspect its Registry alone
-type ServerTypeUnpinned<S> = [S] extends [Server<infer R, any>]
+export type ServerTypeUnpinned<S> = [S] extends [Server<infer R, any>]
   ? 0 extends 1 & R
     ? true
     : false

package/src/server/query.ts

@@ -4,7 +4,8 @@
  * and the byte-capped HTML-form reader. Split out of the server kernel so the file stays one domain.
  */
 import { readBoundedBytes } from "./body.ts"
-import { jsonError, urlPartsOf } from "./http.ts"
+import { plainError, urlPartsOf } from "./http.ts"
+import type { ResponseResult } from "./runtime-core.ts"
 import type { RequestSource } from "./server.ts"
 
 // The query string ("?a=1", or "" when absent) - for lazily building `c.query` only when read.
@@ -123,16 +124,21 @@ const FORM_DECODER = new TextDecoder()
  * Read an HTML-form body (urlencoded) into the plain object a body schema validates - same byte
  * cap as the JSON path (a lying/absent Content-Length can't force an oversized buffer), same
  * repeated-key -> `string[]` promotion as query parsing, same `__proto__` guard.
+ *
+ * A rejection is a `ResponseResult`, not a built `Response`, matching the JSON reader: the cap is a
+ * framework render, and answering one on the plain lane costs what a handler's plain return costs
+ * (see `plainError`). The distinction is observable on the Node adapter - a `Response` there is
+ * untagged, so its body drains through a Web stream and the answer goes out chunked.
  */
 export async function readBoundedForm(
   req: RequestSource,
   maxBytes: number,
-): Promise<Record<string, QueryValue> | Response> {
+): Promise<Record<string, QueryValue> | ResponseResult> {
   const read = await readBoundedBytes(req, maxBytes)
   if (!read.ok) {
     return read.status === 413
-      ? jsonError(413, "payload_too_large")
-      : jsonError(400, "invalid_content_length")
+      ? plainError(413, "payload_too_large")
+      : plainError(400, "invalid_content_length")
   }
   const out: Record<string, QueryValue> = Object.create(null) as Record<string, QueryValue>
   // URLSearchParams owns the format's quirks (`+` as space, percent-decoding, empty keys);

package/src/server/registry.ts

@@ -1,3 +1,4 @@
+import type { BinaryResponse, RawResponse } from "../binary.ts"
 import type { InferInput, InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
 import type { Params, RouteSchema } from "./context.ts"
 
@@ -79,12 +80,26 @@ export type RouteInfoFor<Path extends string, S extends RouteSchema, Output> = {
   readonly sse: RegistrySse<S>
 }
 
-/** The client-visible output of a handler: its awaited return, minus raw `Response`. */
-export type OutputOf<H extends (...args: never[]) => unknown> = Exclude<
-  Awaited<ReturnType<H>>,
-  Response
+/**
+ * The client-visible output of a handler: its awaited return, with an UNbranded raw `Response` removed
+ * (a route returning a bare `Response` has no describable body). A response branded by `bytes()`
+ * ({@link BinaryResponse}) or `raw()` ({@link RawResponse}) is KEPT, so the brand reaches the client's
+ * `Jsonify` and types `data` as `Blob` / `Jsonify<T>` rather than collapsing to `never`.
+ */
+export type OutputOf<H extends (...args: never[]) => unknown> = KeepBrandedResponse<
+  Awaited<ReturnType<H>>
 >
 
+/** Preserve a `bytes()`/`raw()`-branded response; drop only a bare `Response`. Distributes over a
+ * union return, so `Foo | BinaryResponse` keeps both arms. */
+type KeepBrandedResponse<O> = O extends BinaryResponse
+  ? O
+  : O extends RawResponse<unknown>
+    ? O
+    : O extends Response
+      ? never
+      : O
+
 /**
  * The registry entry for a WebSocket route (stored under the pseudo-method key `"WS"`, so WS routes
  * ride the same path → method map as HTTP routes - no extra Server generic). `in` is the client →

package/src/server/request-context.ts

@@ -16,9 +16,9 @@ import {
 import type { Platform } from "./context.ts"
 import { type CookieOptions, cookieNamePrefix, parseCookies, serializeCookie } from "./cookies.ts"
 import { headerObjectOf } from "./headers.ts"
-import { jsonError } from "./http.ts"
+import { plainError } from "./http.ts"
 import { guardParsedValue, type ProtoPoisoning, parseJsonGuarded } from "./proto-guard.ts"
-import { searchOf } from "./query.ts"
+import { isUrlEncodedForm, readBoundedForm, searchOf } from "./query.ts"
 import { responseJsonContentType } from "./respond.ts"
 import {
   CONTEXT_SEARCH,
@@ -27,12 +27,14 @@ import {
   getNeverAbortSignal,
   getUnboundedRequestBudget,
   headerOf,
+  isResponseResult,
   PRE_DECODED_BODY,
   type PreDecodedBody,
+  type ResponseResult,
   requestOf,
   TEXT_DECODER,
 } from "./runtime-core.ts"
-import type { CtxSet, RawContext, RequestSource } from "./server.ts"
+import type { CtxSet, MaybePromise, RawContext, RequestSource } from "./server.ts"
 
 /** A fixed past instant for cookie deletion (`Expires`). A literal epoch - deterministic, unlike an
  * argless `new Date()`. */
@@ -390,7 +392,7 @@ export class RequestContext implements RawContext {
   }
 }
 
-/** Backs `c.boundedBody`: bounded byte read that throws a flat 413/400 `Response` (caught by
+/** Backs `c.boundedBody`: bounded byte read that throws a flat 413/400 plain render (caught by
  * `runLifecycle` as control flow, like `throw redirect(...)`), so a handler can't ignore the cap.
  * The byte-cap itself lives in `./body.ts` (shared with the schema path and `verifyWebhook`). */
 async function readBoundedBodyOrThrow(
@@ -401,8 +403,8 @@ async function readBoundedBodyOrThrow(
   const r = await readBoundedBytes(req, maxBytes ?? maxBodyBytes)
   if (r.ok) return r.bytes
   throw r.status === 413
-    ? jsonError(413, "payload_too_large")
-    : jsonError(400, "invalid_content_length")
+    ? plainError(413, "payload_too_large")
+    : plainError(400, "invalid_content_length")
 }
 
 /** Backs `c.boundedJson`: `readBoundedJsonSource`, throwing its flat 400/413 on failure. */
@@ -413,7 +415,9 @@ async function readBoundedJsonBodyOrThrow<T>(
   maxBytes?: number,
 ): Promise<T> {
   const parsed = await readBoundedJsonSource(req, maxBytes ?? maxBodyBytes, protoPoisoning)
-  if (parsed instanceof Response) throw parsed
+  // The lane's own failures are the only branded values it can produce: a parsed JSON body is
+  // `JSON.parse` output, which carries string keys only and so can never answer to a symbol brand.
+  if (isResponseResult(parsed)) throw parsed
   return parsed as T
 }
 
@@ -431,7 +435,7 @@ async function readBoundedJsonBodyOrThrow<T>(
  * own promise chain instead, and only the streaming fallback - which is already doing IO in a loop
  * - runs as an async function. Callers that `await` the result are unaffected.
  */
-type JsonResultContinuation<T> = (result: unknown | Response) => T | Promise<T>
+type JsonResultContinuation<T> = (result: unknown | ResponseResult) => T | Promise<T>
 type JsonErrorContinuation<T> = (error: unknown) => T | Promise<T>
 type FramedJsonSource = RequestSource & {
   readonly bytes?: () => Promise<Uint8Array>
@@ -445,7 +449,7 @@ export function readBoundedJsonSource(
   req: RequestSource,
   maxBytes: number,
   protoPoisoning?: ProtoPoisoning,
-): Promise<unknown | Response>
+): Promise<unknown | ResponseResult>
 export function readBoundedJsonSource<T>(
   req: RequestSource,
   maxBytes: number,
@@ -459,7 +463,7 @@ export function readBoundedJsonSource<T>(
   protoPoisoning: ProtoPoisoning = "reject",
   onResult?: JsonResultContinuation<T>,
   onError?: JsonErrorContinuation<T>,
-): Promise<unknown | Response | T> {
+): Promise<unknown | ResponseResult | T> {
   // A pre-parsing hook (the transport-codec lane) may have decoded the body already - its stash
   // is taken verbatim: the stasher enforced its own byte cap and poisoning policy on text this
   // lane never sees. One symbol read; a miss on ordinary requests costs a cache-line, not a parse.
@@ -493,53 +497,56 @@ export function readBoundedJsonSource<T>(
     const length = parseContentLength(declared)
     if (length === undefined)
       return onResult === undefined
-        ? Promise.resolve(jsonError(400, "invalid_content_length"))
-        : Promise.resolve(jsonError(400, "invalid_content_length")).then(onResult)
+        ? Promise.resolve(plainError(400, "invalid_content_length"))
+        : Promise.resolve(plainError(400, "invalid_content_length")).then(onResult)
     if (length > maxBytes)
       return onResult === undefined
-        ? Promise.resolve(jsonError(413, "payload_too_large"))
-        : Promise.resolve(jsonError(413, "payload_too_large")).then(onResult)
+        ? Promise.resolve(plainError(413, "payload_too_large"))
+        : Promise.resolve(plainError(413, "payload_too_large")).then(onResult)
+    // Trusted framing (Bun's native route table, Deno.serve): the runtime's HTTP parser already
+    // delimited the bytes, so the declared length IS the transport frame and chunked routing is
+    // moot - the over-cap 413 above already enforced the byte cap. Take the runtime's fused
+    // decode+parse straight away, before the transfer-encoding probe that only exists to route
+    // *untrusted* Node/adapter sources to the streaming lane. Skipping that probe drops one
+    // `Headers.get()` from every Bun/Deno JSON POST; Node/adapter sources are never marked and fall
+    // through below. The parsed-value poisoning walk still applies.
+    if (hasTrustedBodyFraming(req)) {
+      return raw.json().then(
+        (parsed) => {
+          let guarded: unknown
+          try {
+            guarded = guardParsedValue(parsed, protoPoisoning)
+          } catch {
+            return onResult === undefined
+              ? plainError(400, "invalid_json")
+              : onResult(plainError(400, "invalid_json"))
+          }
+          return onResult === undefined ? guarded : onResult(guarded)
+        },
+        () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON())),
+      )
+    }
     const chunked =
       (sourceHeader === undefined
         ? req.headers.get("transfer-encoding")
         : sourceHeader.call(req, "transfer-encoding")) !== null
     if (!chunked) {
-      // Bun's compiled native route table receives a Request whose bytes were already delimited by
-      // Bun's HTTP parser. Keep the exact-byte path for every portable/adapted source, but preserve
-      // Bun's fused decode+parse on this trusted ingress; the declared length is the transport frame
-      // there, not an attacker-controlled hint. The parsed-value poisoning walk still applies.
-      if (hasTrustedBodyFraming(req)) {
-        return raw.json().then(
-          (parsed) => {
-            let guarded: unknown
-            try {
-              guarded = guardParsedValue(parsed, protoPoisoning)
-            } catch {
-              return onResult === undefined
-                ? jsonError(400, "invalid_json")
-                : onResult(jsonError(400, "invalid_json"))
-            }
-            return onResult === undefined ? guarded : onResult(guarded)
-          },
-          () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON())),
-        )
-      }
       const jsonWithByteLength = raw.jsonWithByteLength
       if (jsonWithByteLength !== undefined) {
         return jsonWithByteLength.call(raw).then(
           ({ value, byteLength }) => {
             if (byteLength > length || byteLength > maxBytes) {
               return onResult === undefined
-                ? jsonError(413, "payload_too_large")
-                : onResult(jsonError(413, "payload_too_large"))
+                ? plainError(413, "payload_too_large")
+                : onResult(plainError(413, "payload_too_large"))
             }
             let guarded: unknown
             try {
               guarded = guardParsedValue(value, protoPoisoning)
             } catch {
               return onResult === undefined
-                ? jsonError(400, "invalid_json")
-                : onResult(jsonError(400, "invalid_json"))
+                ? plainError(400, "invalid_json")
+                : onResult(plainError(400, "invalid_json"))
             }
             return onResult === undefined ? guarded : onResult(guarded)
           },
@@ -552,16 +559,16 @@ export function readBoundedJsonSource<T>(
           (bytes) => {
             if (bytes.byteLength > length || bytes.byteLength > maxBytes) {
               return onResult === undefined
-                ? jsonError(413, "payload_too_large")
-                : onResult(jsonError(413, "payload_too_large"))
+                ? 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
-                ? jsonError(400, "invalid_json")
-                : onResult(jsonError(400, "invalid_json"))
+                ? plainError(400, "invalid_json")
+                : onResult(plainError(400, "invalid_json"))
             }
           },
           () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON())),
@@ -578,16 +585,16 @@ export function readBoundedJsonSource<T>(
           const bytes = new Uint8Array(buffer)
           if (bytes.byteLength > length || bytes.byteLength > maxBytes) {
             return onResult === undefined
-              ? jsonError(413, "payload_too_large")
-              : onResult(jsonError(413, "payload_too_large"))
+              ? plainError(413, "payload_too_large")
+              : onResult(plainError(413, "payload_too_large"))
           }
           let parsed: unknown
           try {
             parsed = parseJsonGuarded(TEXT_DECODER.decode(bytes), protoPoisoning)
           } catch {
             return onResult === undefined
-              ? jsonError(400, "invalid_json")
-              : onResult(jsonError(400, "invalid_json"))
+              ? plainError(400, "invalid_json")
+              : onResult(plainError(400, "invalid_json"))
           }
           return onResult === undefined ? parsed : onResult(parsed)
         },
@@ -602,21 +609,69 @@ export function readBoundedJsonSource<T>(
 /** The shared rejection handler for a body read that never completed (client abort, socket error,
  * malformed framing): the same flat 400 a syntactically invalid body gets. Hoisted so the framed
  * lane allocates no per-request closure for it. */
-const INVALID_JSON = (): Response => jsonError(400, "invalid_json")
+const INVALID_JSON = (): ResponseResult => plainError(400, "invalid_json")
 
 /** The chunked / length-less fallback: drain under the streaming byte cap, then parse guarded. */
 async function readStreamedJsonSource(
   raw: RequestSource,
   maxBytes: number,
   protoPoisoning: ProtoPoisoning,
-): Promise<unknown | Response> {
+): Promise<unknown | ResponseResult> {
   const body = raw.body
-  if (body === null) return jsonError(400, "invalid_json")
+  if (body === null) return plainError(400, "invalid_json")
   const drained = await drainCapped(body, maxBytes)
-  if (!drained.ok) return jsonError(413, "payload_too_large")
+  if (!drained.ok) return plainError(413, "payload_too_large")
   try {
     return parseJsonGuarded(TEXT_DECODER.decode(drained.bytes), protoPoisoning)
   } catch {
-    return jsonError(400, "invalid_json")
+    return plainError(400, "invalid_json")
+  }
+}
+
+/**
+ * The shared bounded body framing/parser: the single trust-boundary enforcement point every body
+ * lane routes through. Content-type dispatch, the urlencoded-form cap, and the JSON path
+ * (`Content-Length` pre-reject -> streaming cap -> prototype-poisoning guard, all inside
+ * `readBoundedJsonSource`) live here so the fused body runner, the generic body-only lane, and a
+ * compact edge entrypoint all enforce the same boundary from one definition. `protoPoisoning` is a
+ * parameter, not read off a server instance, so this stays free of any dependency on the class.
+ *
+ * `onParsed` receives the decoded, guard-screened value; a framing rejection (`Content-Length` over
+ * the cap, a lying length caught mid-stream, malformed JSON, an unsupported media type) is rendered
+ * through `wrapResponse`; a read that never completed (client abort, socket error) reaches `onError`.
+ */
+export function readBodyFramed<T>(
+  source: RequestSource,
+  maxBodyBytes: number,
+  protoPoisoning: ProtoPoisoning,
+  onParsed: (parsed: unknown) => MaybePromise<T>,
+  wrapResponse: (response: Response | ResponseResult) => T,
+  onError: (err: unknown) => MaybePromise<T>,
+): Promise<T> {
+  const contentType = headerOf(source, "content-type") ?? ""
+  if (contentType !== "application/json" && !contentType.includes("application/json")) {
+    if (isUrlEncodedForm(contentType)) {
+      return readBoundedForm(source, maxBodyBytes).then(
+        (form) => (isResponseResult(form) ? wrapResponse(form) : onParsed(form)),
+        onError,
+      ) as Promise<T>
+    }
+    // multipart/form-data (file uploads) stays 415 on the schema path by design - files don't fit a
+    // value schema; use a schema-less route + @nifrajs/uploads helpers for those.
+    return Promise.resolve(wrapResponse(plainError(415, "unsupported_media_type")))
+  }
+  // All JSON bodies go through readBoundedJsonSource - the single enforcement point for the framed
+  // fast path (post-read byte re-check), the streaming cap, and the prototype-poisoning guard. A
+  // separate inlined native-json() fast path here would fork the trust boundary in two.
+  try {
+    return readBoundedJsonSource(
+      source,
+      maxBodyBytes,
+      protoPoisoning,
+      (parsed) => (isResponseResult(parsed) ? wrapResponse(parsed) : onParsed(parsed)),
+      onError,
+    )
+  } catch (err) {
+    return Promise.resolve(onError(err))
   }
 }

package/src/server/respond.ts

@@ -4,11 +4,14 @@
  * spine types, so the wire-response format lives in one module distinct from the request engine.
  */
 
+import { NODE_BRIDGE_MARKER_KEYS } from "./bridge-markers.ts"
 import {
   CONTEXT_SET,
   EMPTY_RESPONSE_CONTROLS,
   type HandlerResult,
   isResponseResult,
+  type PlainRender,
+  plainRenderHeaders,
 } from "./runtime-core.ts"
 import type { CtxSet, RawContext } from "./server.ts"
 import { mergeStaticHeaderRecord, type StaticResponseHeaders } from "./static-headers.ts"
@@ -24,6 +27,16 @@ function headersInit(set: CtxSet): Record<string, string> | Headers | undefined
   return headers
 }
 
+/** The `c.set` a plain render stands for: its status and headers, carrying over the request's queued
+ * cookies so `set.cookie(...)` then an early exit still ships them. */
+function plainRenderSet(plain: PlainRender, set: CtxSet): CtxSet {
+  return {
+    status: plain.status,
+    _headers: plainRenderHeaders(plain, set),
+    _cookies: set._cookies,
+  } as CtxSet
+}
+
 // 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.
@@ -178,7 +191,7 @@ function denoResponseWithJsonBody(
 // 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")
+const RESPONSE_BODY = Symbol.for(NODE_BRIDGE_MARKER_KEYS.responseBody)
 
 /**
  * Headers objects the framework itself constructed - guaranteed mutable, no guard. Response
@@ -396,6 +409,18 @@ export function toResponse(
   statics?: StaticResponseHeaders,
 ): Response {
   if (isResponseResult(result)) {
+    const plain = result.plain
+    if (plain !== undefined) {
+      // Rendered as the value it is, on the branches below, rather than through `toResponse()`: the
+      // status and headers fold into a `set` and the body takes the ordinary JSON lane. One level
+      // only - a plain render's body is a user value, never another response carrier.
+      return toResponse(
+        plain.body as HandlerResult,
+        plainRenderSet(plain, set),
+        tagResponseBody,
+        statics,
+      )
+    }
     return withStatics(
       appendCookiesToResponse(normalizeBodylessResponse(result.toResponse()), set),
       statics,

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

@@ -48,6 +48,7 @@ import {
 } from "../schema/standard.ts"
 import { INSTALL_RESPONSE_CONTRACT } from "./install.ts"
 import type { IdentityPlugin } from "./plugin.ts"
+import { isResponseResult } from "./runtime-core.ts"
 import type { AnyServer } from "./server.ts"
 
 /**
@@ -91,8 +92,11 @@ export function checkResponseContract(
   mode: "warn" | "enforce",
 ): ResponseContractOutcome | Promise<ResponseContractOutcome> {
   // A handler may return a raw Response as deliberate control flow (a redirect, a stream). There is no
-  // JSON payload to hold to the contract, and re-serializing one would corrupt it.
-  if (result instanceof Response || result === undefined) return { kind: "ok", value: result }
+  // JSON payload to hold to the contract, and re-serializing one would corrupt it. A `status(...)` is
+  // the same control flow in plain-data form: the contract describes the route's SUCCESS payload, so
+  // holding an early exit (a 401 body, say) to it would fail every guarded route that declares one.
+  if (result instanceof Response || result === undefined || isResponseResult(result))
+    return { kind: "ok", value: result }
   const settled = schema["~standard"].validate(result)
   return settled instanceof Promise
     ? settled.then((r) => interpret(r, result, mode))

package/src/server/response-observer-runtime.ts

@@ -0,0 +1,135 @@
+import type {
+  NodeRequestContext,
+  NodeResponseHook,
+  ResponseBodyHook,
+  ResponseHeadersHook,
+  ResponseHeadersView,
+} from "./node-outcome-hook.ts"
+import { recordHeadersView } from "./node-outcome-hook.ts"
+import { knownMutableHeaders, rememberMutableHeaders, taggedResponseBody } from "./respond.ts"
+import { applyBodyReplacement, withReplacedBody } from "./response-hooks.ts"
+
+type MaybePromise<T> = T | Promise<T>
+type WebResponseHook = (response: Response, req: Request) => MaybePromise<Response>
+
+export type { ResponseBodyHook, ResponseHeadersHook } from "./node-outcome-hook.ts"
+
+export interface ResponseObserverHost {
+  assertConfigurable(operation: string): void
+  addResponseHook(web: WebResponseHook, node: NodeResponseHook | undefined): void
+  enableResponseBodyTagging(): object
+  responseBodyOwners(): ReadonlySet<object>
+}
+
+export interface ResponseObserverMethods {
+  onResponseHeaders(fn: ResponseHeadersHook): this
+  onResponseBody(fn: ResponseBodyHook): this
+  onResponseRaw(fn: (response: Response, req: Request) => MaybePromise<Response>): this
+}
+
+export interface ResponseObserverRuntime {
+  install(host: ResponseObserverHost): ResponseObserverMethods
+}
+
+const HEADER_MUTABILITY_PROBE = "x-nifra-header-probe"
+const GUARDED_RESPONSE_HEADERS = new WeakSet<Headers>()
+
+function hasMutableResponseHeaders(headers: Headers): boolean {
+  if (knownMutableHeaders(headers)) return true
+  if (GUARDED_RESPONSE_HEADERS.has(headers)) return false
+  let previous: string | null = null
+  try {
+    previous = headers.get(HEADER_MUTABILITY_PROBE)
+    headers.set(HEADER_MUTABILITY_PROBE, "1")
+    if (previous === null) headers.delete(HEADER_MUTABILITY_PROBE)
+    else headers.set(HEADER_MUTABILITY_PROBE, previous)
+    rememberMutableHeaders(headers)
+    return true
+  } catch {
+    try {
+      if (previous === null) headers.delete(HEADER_MUTABILITY_PROBE)
+      else headers.set(HEADER_MUTABILITY_PROBE, previous)
+    } catch {
+      // A guarded response rejected the probe and the clone path is authoritative.
+    }
+    GUARDED_RESPONSE_HEADERS.add(headers)
+    return false
+  }
+}
+
+function webRequestView(req: Request): NodeRequestContext {
+  return { method: req.method, url: req.url, header: (name) => req.headers.get(name) }
+}
+
+function webHeadersView(
+  response: Response,
+  req: Request,
+): {
+  readonly response: Response
+  readonly headers: ResponseHeadersView
+  readonly request: NodeRequestContext
+} {
+  const request = webRequestView(req)
+  if (!hasMutableResponseHeaders(response.headers)) {
+    const clone = new Response(response.body, response)
+    return { response: clone, headers: clone.headers, request }
+  }
+  return { response, headers: response.headers, request }
+}
+
+export function createResponseObserverRuntime(): ResponseObserverRuntime {
+  return {
+    install(host) {
+      return {
+        onResponseHeaders(this: ResponseObserverMethods, fn): ResponseObserverMethods {
+          host.assertConfigurable("onResponseHeaders()")
+          host.addResponseHook(
+            (response, req) => {
+              const view = webHeadersView(response, req)
+              const out = fn(view.headers, view.request, response.status)
+              return out instanceof Promise ? out.then(() => view.response) : view.response
+            },
+            (response, req) => fn(recordHeadersView(response), req, response.status),
+          )
+          return this
+        },
+        onResponseBody(this: ResponseObserverMethods, fn): ResponseObserverMethods {
+          host.assertConfigurable("onResponseBody()")
+          host.enableResponseBodyTagging()
+          host.addResponseHook(
+            (response, req) => {
+              const body = taggedResponseBody(response, host.responseBodyOwners())
+              if (body === undefined) return response
+              const view = webHeadersView(response, req)
+              const out = fn(body, view.headers, view.request, response.status)
+              return out instanceof Promise
+                ? out.then((replaced) => withReplacedBody(response, replaced))
+                : withReplacedBody(response, out)
+            },
+            (response, req) => {
+              if (response.body === null) return undefined
+              const out = fn(response.body, recordHeadersView(response), req, response.status)
+              if (out instanceof Promise)
+                return out.then((replaced) => applyBodyReplacement(response, replaced))
+              applyBodyReplacement(response, out)
+              return undefined
+            },
+          )
+          return this
+        },
+        onResponseRaw(this: ResponseObserverMethods, fn): ResponseObserverMethods {
+          host.assertConfigurable("onResponseRaw()")
+          host.enableResponseBodyTagging()
+          host.addResponseHook(
+            (response, req) =>
+              taggedResponseBody(response, host.responseBodyOwners()) === undefined
+                ? fn(response, req)
+                : response,
+            () => undefined,
+          )
+          return this
+        },
+      }
+    },
+  }
+}