@nifrajs/core 2.12.0 → 2.13.0

package/src/server/body.ts

@@ -256,10 +256,8 @@ function cappedStreamOf(
  * An over-cap read rejects with `reject(413)` (a lying `Content-Length` with `reject(400)`), which
  * the lifecycle already treats as control flow - the same contract as `c.boundedBody`.
  */
-function capRequestBodyReads(request: Request, maxBytes: number): void {
-  if (TRANSPORT_CAPPED.has(request)) return
-  TRANSPORT_CAPPED.add(request)
-  const reject = transportCapError
+/** The request's own pre-shadow readers - the fallback surface when the source offers none. */
+function requestBodyReaders(request: Request): RawBodyReaders {
   const bodyDescriptor = descriptorOf(request, "body")
   const raw: RawBodyReaders = {
     get headers() {
@@ -276,6 +274,14 @@ function capRequestBodyReads(request: Request, maxBytes: number): void {
     json: request.json.bind(request),
   }
   if (typeof request.bytes === "function") raw.bytes = request.bytes.bind(request)
+  return raw
+}
+
+function capRequestBodyReads(request: Request, maxBytes: number, preset?: RawBodyReaders): void {
+  if (TRANSPORT_CAPPED.has(request)) return
+  TRANSPORT_CAPPED.add(request)
+  const reject = transportCapError
+  const raw = preset ?? requestBodyReaders(request)
   // One bounded buffer backs every shadowed reader; a second read replays it instead of failing
   // with "body already used" (a strict superset of the native one-shot contract).
   let buffered: Promise<Uint8Array> | undefined
@@ -350,13 +356,24 @@ export function markTransportCap(source: object, maxBytes: number): void {
  * lane's pre-decoded body), and hook-observed references all survive. Framework readers bypass the
  * shadow through {@link rawBodySourceOf} and enforce their own caps - `c.boundedBody(explicit)`
  * still overrides in either direction. An unmarked source (`bodyLimit: "unlimited"`) is untouched.
+ *
+ * A source that owns its transport bytes directly (Node's lazy source reads the socket itself)
+ * supplies them through `RequestSource.rawBodyReaders`: the capped readers then buffer off the
+ * socket instead of routing every read back through a runtime `Request` the source was still
+ * deferring. The cap is identical either way - the same {@link readBoundedBytes} enforces it.
  */
 export function applyTransportCap(source: object, request: Request): void {
   const maxBytes = (source as { [TRANSPORT_CAP]?: number })[TRANSPORT_CAP]
-  // The capped check comes BEFORE the body-null check: post-cap, `request.body` is the shadowed
-  // getter, and re-reading it on every `c.req` access would rebuild capped state for nothing.
-  if (maxBytes === undefined || TRANSPORT_CAPPED.has(request) || request.body === null) return
-  capRequestBodyReads(request, maxBytes)
+  // The capped check comes BEFORE the body probe: post-cap, `request.body` is the shadowed getter,
+  // and re-reading it on every `c.req` access would rebuild capped state for nothing.
+  if (maxBytes === undefined || TRANSPORT_CAPPED.has(request)) return
+  const provide = (source as { rawBodyReaders?: () => RawBodyReaders }).rawBodyReaders
+  const preset = provide === undefined ? undefined : provide.call(source)
+  // The null-body shortcut is only worth its probe when there is no cheaper surface: on a source
+  // that defers its `Request`, reading `request.body` would materialize the very object the preset
+  // readers exist to avoid. Capping a bodiless request costs nothing but the shadowing itself.
+  if (preset === undefined && request.body === null) return
+  capRequestBodyReads(request, maxBytes, preset)
   // A wrapper source (Node's lazy source) delegates its own body readers to the request once it
   // materializes - which are now the shadowed ones. Mirror the raw-reader stash onto the source so
   // framework readers (`rawBodySourceOf(source)`) keep reading pre-shadow there too.

package/src/server/request-context.ts

@@ -19,6 +19,7 @@ import { headerObjectOf } from "./headers.ts"
 import { jsonError } from "./http.ts"
 import { guardParsedValue, type ProtoPoisoning, parseJsonGuarded } from "./proto-guard.ts"
 import { searchOf } from "./query.ts"
+import { responseJsonContentType } from "./respond.ts"
 import {
   CONTEXT_SEARCH,
   CONTEXT_SET,
@@ -88,6 +89,80 @@ function statusInit(init?: ResponseInit | number): ResponseInit | undefined {
   return typeof init === "number" ? { status: init } : init
 }
 
+/**
+ * Whether a body built here should be deferred instead of turned into a `Response` on the spot.
+ *
+ * Only the Node bridge can use a deferred body: it writes status + headers + bytes straight to the
+ * socket, so the undici `Response` those two helpers used to build (~2us, about a quarter of the
+ * request budget on a small text response) was pure loss. Bun and Deno hand the `Response` to their
+ * native server, where nothing reads the deferral. Probed once at module load, not per response.
+ */
+const DEFERS_RESPONSE =
+  typeof (globalThis as { Deno?: unknown }).Deno === "undefined" &&
+  typeof (globalThis as { Bun?: unknown }).Bun === "undefined" &&
+  typeof (globalThis as { process?: { versions?: { node?: unknown } } }).process?.versions?.node ===
+    "string"
+
+/**
+ * The Node adapter's deferred-response factory, received over the shared-symbol seam rather than a
+ * package import - `@nifrajs/node` stays dependency-free from core's runtime and talks to it only
+ * through `Symbol.for` marks, so the stand-in it builds (and the ~0.4 KB gzip the class costs) never
+ * ships in a Bun/Deno bundle that will never run this branch. `c.json`/`c.text` route the Node fast
+ * lane through it: given a status, an owned header record, and the bytes, it returns a `Response`-shaped
+ * value the bridge writes straight to the socket (no undici `Response` built, no body stream drained).
+ * Absent - no adapter loaded - the two helpers fall back to a real `Response`. Cached on first read;
+ * the adapter registers at its own module load, before any request reaches a handler.
+ */
+const DEFERRED_RESPONDER_KEY = Symbol.for("nifra.deferred.responder")
+type DeferredResponder = (body: string, status: number, headers: Record<string, string>) => Response
+let deferredResponder: DeferredResponder | undefined
+function deferredResponderFor(): DeferredResponder | undefined {
+  if (deferredResponder === undefined) {
+    deferredResponder = (globalThis as unknown as Record<symbol, DeferredResponder | undefined>)[
+      DEFERRED_RESPONDER_KEY
+    ]
+  }
+  return deferredResponder
+}
+
+/**
+ * A header record the deferred response can own outright - a fresh object with lowercase names, since
+ * the Node writer mutates it in place to declare `content-length`. `undefined` means the caller's
+ * shape (a `Headers`, an entries array) is not worth walking here: those take the `Response` path.
+ */
+function ownHeaderRecord(
+  // `unknown`: the lib's `ResponseInit.headers` is a runtime-specific `HeadersInit` (Bun's vs
+  // undici's differ), and this only needs to recognize the plain-record case anyway.
+  headers: unknown,
+  contentType: string,
+): Record<string, string> | undefined {
+  if (headers === undefined) return { "content-type": contentType }
+  if (typeof headers !== "object" || headers === null || Array.isArray(headers)) return undefined
+  if (headers instanceof Headers) return undefined
+  const record: Record<string, string> = {}
+  let hasContentType = false
+  for (const name of Object.keys(headers)) {
+    const lower = name.toLowerCase()
+    if (lower === "content-type") hasContentType = true
+    record[lower] = (headers as Record<string, string>)[name] as string
+  }
+  if (!hasContentType) record["content-type"] = contentType
+  return record
+}
+
+/** The content-type the runtime's own `Response` puts on a string body, read off it once. A deferred
+ * text response fills it in itself, so it must fill in exactly what the `Response` would have. */
+let stringBodyContentType: string | undefined
+function responseTextContentType(): string {
+  stringBodyContentType ??=
+    new Response("").headers.get("content-type") ?? "text/plain;charset=UTF-8"
+  return stringBodyContentType
+}
+
+/** `c.text`'s own default, unchanged: the explicit one nifra has always declared when the caller
+ * passes no headers of their own. */
+const TEXT_CONTENT_TYPE = "text/plain; charset=utf-8"
+
 export class RequestContext implements RawContext {
   // `declare` keeps TypeScript's class-field emit from first writing `undefined` to every slot; the
   // constructor initializes only the eager request state, while lazy fields remain absent until used.
@@ -234,15 +309,53 @@ export class RequestContext implements RawContext {
     this.headersValue = value
   }
 
+  /**
+   * Return a JSON body. Prefer this (and {@link text}) over a hand-rolled `return new Response(...)`:
+   * on Node these helpers hand the adapter a status, a header record, and the bytes directly, so the
+   * Web `Response` is deferred and the reply lands on the fastest write lane. A raw `new Response` is
+   * fully supported and returns identical bytes, but it is the last-resort lane - the adapter has to
+   * drain its body stream, which no direct-write helper pays.
+   */
   json(body: unknown, init?: ResponseInit | number): Response {
-    return Response.json(body, statusInit(init))
+    const i = statusInit(init)
+    if (!DEFERS_RESPONSE) return Response.json(body, i)
+    const defer = deferredResponderFor()
+    if (defer === undefined) return Response.json(body, i)
+    // The same bytes `Response.json` would produce, kept one step short of it so the direct writer
+    // can have them. `JSON.stringify` returns `undefined` for a value with no JSON form (`undefined`,
+    // a function, a symbol) - exactly the case where `Response.json` throws, so hand it back the
+    // throw rather than inventing a 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 = JSON.stringify(body) as string | undefined
+    if (text === undefined) return Response.json(body, i)
+    const headers = ownHeaderRecord(i?.headers, responseJsonContentType())
+    if (headers === undefined) return Response.json(body, i)
+    return defer(text, i?.status ?? 200, headers)
   }
 
+  /**
+   * Return a text body. The fast lane on Node - see {@link json}. Reach for a raw `return new
+   * Response(body)` only when you need a Response shape these helpers do not build; it costs the
+   * adapter a body-stream drain that this path skips.
+   */
   text(body: string, init?: ResponseInit | number): Response {
     const i = statusInit(init)
+    if (DEFERS_RESPONSE) {
+      const defer = deferredResponderFor()
+      if (defer !== undefined) {
+        // The content-type each shape would have ended up with: nifra's declared default when the
+        // caller brought no headers, the runtime's own string-body default when they did (there the
+        // caller owns the content-type, and only fills in for one they did not set).
+        const headers = ownHeaderRecord(
+          i?.headers,
+          i?.headers === undefined ? TEXT_CONTENT_TYPE : responseTextContentType(),
+        )
+        if (headers !== undefined) return defer(body, i?.status ?? 200, headers)
+      }
+    }
     // Default to text/plain; if the caller passes their own headers, they own the content-type.
     if (i?.headers !== undefined) return new Response(body, i)
-    return new Response(body, { ...i, headers: { "content-type": "text/plain; charset=utf-8" } })
+    return new Response(body, { ...i, headers: { "content-type": TEXT_CONTENT_TYPE } })
   }
 
   get query(): unknown {

package/src/server/respond.ts

@@ -150,7 +150,7 @@ function withStaticHeaderInit(
 const IS_DENO = typeof (globalThis as { Deno?: unknown }).Deno !== "undefined"
 let denoJsonContentType: string | undefined
 
-function responseJsonContentType(): string {
+export function responseJsonContentType(): string {
   if (denoJsonContentType === undefined) {
     denoJsonContentType = Response.json(0).headers.get("content-type") ?? "application/json"
   }

package/src/server/server.ts

@@ -49,7 +49,12 @@ import type {
   StandardResult,
   StandardSchemaV1,
 } from "../schema/standard.ts"
-import { assertByteLimit, markTransportCap, markTrustedBodyFraming } from "./body.ts"
+import {
+  assertByteLimit,
+  markTransportCap,
+  markTrustedBodyFraming,
+  type RawBodyReaders,
+} from "./body.ts"
 import { type ClientIpTrust, resolveClientIp } from "./client-ip.ts"
 import type { Context, Platform, ResponseControls, RouteSchema } from "./context.ts"
 import {
@@ -285,6 +290,11 @@ export interface RequestSource {
   /** Present only when materializing a `Request` is non-trivial (the Node lazy source); for a real
    * `Request` passed as the source it's absent and {@link requestOf} returns the source itself. */
   readonly request?: Request
+  /** Optional pre-`Request` reader surface for the transport cap. A source that reads its own
+   * transport bytes (the Node lazy source reads the socket) exposes them here so a capped direct
+   * read (`c.req.json()`) buffers off the transport instead of routing through the deferred
+   * `Request`. `body` must stay the live stream - the cap still guards a chunked body mid-flight. */
+  rawBodyReaders?(): RawBodyReaders
 }
 
 /** The empty context extension. `NonNullable<unknown>` is `{}` without tripping noBannedTypes. */
@@ -2841,7 +2851,12 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     // never direct-reads pays nothing. Framework readers bypass the shadow (`rawBodySourceOf`) and
     // keep their own caps, so `c.boundedBody(explicit)` still overrides upward.
     // `bodyLimit: "unlimited"` (undefined here) skips the cap entirely.
-    if (entry.bodyLimit !== undefined) {
+    // A schema route consumes and validates the body through `readBodyInput` before any derive or
+    // handler can reach `c.req`; that lane already enforces `entry.bodyLimit`. Installing the full
+    // direct-reader cap on `c.req` here would allocate bound readers, closures, and a stream wrapper
+    // for a body that is already consumed. Keep the lazy transport cap for raw-body routes, where a
+    // user read is the only framework-owned body boundary.
+    if (entry.bodyLimit !== undefined && entry.schema?.body === undefined) {
       const method = source.method
       if (method !== "GET" && method !== "HEAD") markTransportCap(source, entry.bodyLimit)
     }
@@ -4701,7 +4716,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     // The fused native lane bypasses `runMatched`, so the route's transport byte cap must be
     // marked here too - otherwise a Bun `listen()` fused route would leave direct `c.req` body
     // reads uncapped. The non-fused branches go through `fetchMatched` -> `runMatched`, which marks.
-    const bodyLimit = entry.bodyLimit
+    const bodyLimit = entry.schema?.body === undefined ? entry.bodyLimit : undefined
     const inner = fused
     const capped: FusedWebRunner | undefined =
       inner === undefined || bodyLimit === undefined