@nifrajs/core 3.1.0 → 3.2.0

package/src/server/contract.ts

@@ -5,9 +5,11 @@ import { METHODS, type Method } from "../router/router.ts"
 import type { InferInput, InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
 import { assertByteLimit } from "./body.ts"
 import type { Context, IdempotencyConfig, Params, RouteSchema } from "./context.ts"
-import type { EmptyRegistry, OutputOf, Registry } from "./registry.ts"
+import type { EmptyRegistry, OutputOf, Registry, RouteInfoFor } from "./registry.ts"
 import { Server } from "./server.ts"
 
+type EmptyResponseMap = NonNullable<unknown>
+
 /** An additional (non-success) response a contract operation can document, e.g. a `404`. */
 export interface ResponseDef {
   readonly description?: string
@@ -88,7 +90,9 @@ type OpErrorBodies<Rs extends Record<string, ResponseDef>> = {
   [K in keyof Rs as K extends `2${string}`
     ? never
     : K extends `${infer N extends number}`
-      ? N
+      ? Rs[K] extends { schema: StandardSchemaV1 }
+        ? N
+        : never
       : never]: Rs[K] extends {
     schema: infer S extends StandardSchemaV1
   }
@@ -106,6 +110,26 @@ type OpErrors<O extends OperationDef> = O extends {
     : OpErrorBodies<Rs>
   : unknown
 
+/** The schema-bearing status map a contract consumer can use for success and failure narrowing. */
+type OpAdditionalResponseMap<O extends OperationDef> = O extends {
+  responses: infer Rs extends Record<string, ResponseDef>
+}
+  ? {
+      [K in keyof Rs as K extends `${infer N extends number}`
+        ? Rs[K] extends { schema: StandardSchemaV1 }
+          ? N
+          : never
+        : never]: Rs[K] extends { schema: infer S extends StandardSchemaV1 }
+        ? InferOutput<S>
+        : never
+    }
+  : EmptyResponseMap
+
+type OpResponseMap<O extends OperationDef> = Omit<OpAdditionalResponseMap<O>, 200> &
+  (O extends { response: infer R extends StandardSchemaV1 }
+    ? { 200: InferOutput<R> }
+    : EmptyResponseMap)
+
 /**
  * RouteInfo as a *decoupled consumer* sees it from the contract alone: the
  * `output` is the declared `response` schema's type, or `unknown` when none is
@@ -118,6 +142,7 @@ type RouteInfoForOp<O extends OperationDef> = {
   readonly query: OpQuery<O>
   readonly body: OpBody<O>
   readonly output: OpResponse<O>
+  readonly responses: OpResponseMap<O>
   // The error union from the op's non-2xx `responses` - so a decoupled contract client sees typed error
   // bodies, just like an inline route's `errors`. `unknown` when the op declares no error responses.
   readonly errors: OpErrors<O>
@@ -143,6 +168,25 @@ type SchemaForOp<O extends OperationDef> = (O extends { body: infer B extends St
     : Record<never, never>) &
   (O extends { params: infer P extends StandardSchemaV1 } ? { params: P } : Record<never, never>)
 
+type OpResponseSchemas<O extends OperationDef> = O extends {
+  responses: infer Rs extends Record<string, ResponseDef>
+}
+  ? {
+      [K in keyof Rs as K extends `2${string}`
+        ? never
+        : Rs[K] extends { schema: StandardSchemaV1 }
+          ? K extends `${infer N extends number}`
+            ? N
+            : never
+          : never]: Rs[K] extends { schema: infer S extends StandardSchemaV1 } ? S : never
+    }
+  : EmptyResponseMap
+
+type RouteSchemaForOp<O extends OperationDef> = SchemaForOp<O> &
+  RouteSchema &
+  (O extends { response: infer R extends StandardSchemaV1 } ? { response: R } : EmptyResponseMap) &
+  (keyof OpResponseSchemas<O> extends never ? EmptyResponseMap : { errors: OpResponseSchemas<O> })
+
 /**
  * The handler context for an op - identical to the inline `Context<Path, S>`, so a
  * handler written for an inline route type-checks unchanged under `implement`
@@ -245,23 +289,12 @@ export type RegistryFromImpl<
   C extends ContractShape,
   H extends HandlersFor<C, Ctx>,
   Ctx = NonNullable<unknown>,
+  HookOutput = never,
 > = {
   [P in C[keyof C]["path"]]: {
-    [K in keyof C as C[K]["path"] extends P ? C[K]["method"] : never]: {
-      readonly params: Params<C[K]["path"]>
-      readonly query: OpQuery<C[K]>
-      readonly body: OpBody<C[K]>
-      readonly output: C[K] extends { response: infer R extends StandardSchemaV1 }
-        ? InferOutput<R>
-        : H[K] extends AnyFn
-          ? OutputOf<H[K]>
-          : unknown
-      // The error union from the op's non-2xx `responses` (see OpErrors) - a graduated contract client sees
-      // the same typed error bodies as the inline `errors` path.
-      readonly errors: OpErrors<C[K]>
-      // Mirrors RouteInfoForOp: no SSE contract on contract ops (yet) - mode conformance holds.
-      readonly sse: never
-    }
+    [K in keyof C as C[K]["path"] extends P ? C[K]["method"] : never]: H[K] extends AnyFn
+      ? RouteInfoFor<C[K]["path"], RouteSchemaForOp<C[K]>, OutputOf<H[K]>, HookOutput>
+      : RouteInfoFor<C[K]["path"], RouteSchemaForOp<C[K]>, unknown, HookOutput>
   }
 }
 
@@ -290,9 +323,24 @@ export function implement<
   H extends HandlersFor<C, Ctx>,
   R extends Registry = EmptyRegistry,
   Ctx = NonNullable<unknown>,
->(contract: C, handlers: H, app?: Server<R, Ctx>): Server<R & RegistryFromImpl<C, H, Ctx>, Ctx> {
-  const target = (app ?? new Server()) as Server<R, Ctx>
+  HookOutput = never,
+>(
+  contract: C,
+  handlers: H,
+  app?: Server<R, Ctx, HookOutput>,
+): Server<R & RegistryFromImpl<C, H, Ctx, HookOutput>, Ctx, HookOutput> {
+  const target = (app ?? new Server()) as Server<R, Ctx, HookOutput>
   const routes = Object.entries(contract).map(([name, op]) => {
+    const errors =
+      op.responses === undefined
+        ? undefined
+        : Object.fromEntries(
+            Object.entries(op.responses)
+              .filter(
+                ([status, response]) => !status.startsWith("2") && response.schema !== undefined,
+              )
+              .map(([status, response]) => [Number(status), response.schema!]),
+          )
     // body/query are validated at the request boundary; `response` is a type + introspection contract
     // ONLY - never validated at runtime and never read on the request hot path (the lifecycle reads
     // schema.body/query by name; the `bare`/bodyOnly/queryOnly fast-path gates ignore `response`). Built
@@ -304,6 +352,7 @@ export function implement<
       op.body !== undefined ||
       op.query !== undefined ||
       op.response !== undefined ||
+      (errors !== undefined && Object.keys(errors).length > 0) ||
       op.capabilities !== undefined ||
       op.idempotency !== undefined ||
       op.bodyLimit !== undefined ||
@@ -316,6 +365,7 @@ export function implement<
             ...(op.body !== undefined ? { body: op.body } : {}),
             ...(op.query !== undefined ? { query: op.query } : {}),
             ...(op.response !== undefined ? { response: op.response } : {}),
+            ...(errors !== undefined && Object.keys(errors).length > 0 ? { errors } : {}),
             ...(op.capabilities !== undefined ? { capabilities: op.capabilities } : {}),
             ...(op.idempotency !== undefined ? { idempotency: op.idempotency } : {}),
             ...(op.bodyLimit !== undefined ? { bodyLimit: op.bodyLimit } : {}),
@@ -335,5 +385,5 @@ export function implement<
   target.registerBatch(routes)
   // Runtime registered exactly the contract's routes through the inline path; the
   // registry type is computed from the contract inputs + handler return types.
-  return target as unknown as Server<R & RegistryFromImpl<C, H, Ctx>, Ctx>
+  return target as unknown as Server<R & RegistryFromImpl<C, H, Ctx, HookOutput>, Ctx, HookOutput>
 }

package/src/server/cookies.ts

@@ -202,11 +202,25 @@ const toBase64Url = (buf: ArrayBuffer): string => {
   return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
 }
 
+const BASE64URL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
+const BASE64URL_RE = /^[A-Za-z0-9_-]+$/
+
 // Returns `Uint8Array<ArrayBuffer>` (not the generic `Uint8Array<ArrayBufferLike>`) so it satisfies
-// WebCrypto's `BufferSource` parameter under TS 5.7+'s typed-array generics.
+// WebCrypto's `BufferSource` parameter under TS 5.7+'s typed-array generics. Reject non-canonical
+// encodings: base64 decoders otherwise accept alternate final characters whose unused padding bits
+// decode to the same bytes, which lets a visibly changed signed cookie verify as if it were original.
 const fromBase64Url = (s: string): Uint8Array<ArrayBuffer> | null => {
+  if (s.length === 0 || s.length % 4 === 1 || !BASE64URL_RE.test(s)) return null
+  const remainder = s.length % 4
+  const last = BASE64URL_ALPHABET.indexOf(s[s.length - 1]!)
+  // Two or three base64 characters leave four or two unused low bits respectively. The encoder above
+  // always emits those bits as zero; accepting anything else creates a second spelling of the same
+  // byte sequence.
+  if ((remainder === 2 && (last & 0x0f) !== 0) || (remainder === 3 && (last & 0x03) !== 0))
+    return null
   try {
-    const bin = atob(s.replace(/-/g, "+").replace(/_/g, "/"))
+    const padded = s + "=".repeat((4 - remainder) % 4)
+    const bin = atob(padded.replace(/-/g, "+").replace(/_/g, "/"))
     const bytes = new Uint8Array(bin.length)
     for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i)
     return bytes

package/src/server/plugin.ts

@@ -23,7 +23,9 @@ export type NifraPlugin<In extends AnyServer = AnyServer, Out extends AnyServer
  * server type it receives, preserving the caller's typed registry and context across `.use()` while
  * still allowing the plugin to register runtime hooks or handlers.
  */
-export type IdentityPlugin = (<S extends AnyServer>(app: S) => S) & {
+export type IdentityPlugin<AddedHookOutput = never> = (<R extends Registry, Ctx, HookOutput>(
+  app: Server<R, Ctx, HookOutput>,
+) => Server<R, Ctx, HookOutput | AddedHookOutput>) & {
   readonly pluginName?: string
 }
 
@@ -142,11 +144,15 @@ export function definePlugin(
  * const api = server().get("/a", h).use(audit).get("/b", h) // /a AND /b stay typed
  * ```
  */
-export function defineIdentityPlugin(
+export function defineIdentityPlugin<AddedHookOutput = never>(
   name: string,
-  apply: <S extends AnyServer>(app: S) => S,
-): IdentityPlugin {
-  return Object.assign(apply, { pluginName: name }) as IdentityPlugin
+  // The runtime identity plugin may install lifecycle hooks whose richer type is intentionally not
+  // threaded through this legacy identity seam. Accept the resulting server here so existing
+  // middleware remains source-compatible; direct typed hooks and future typed middleware can use the
+  // concrete Server return type without forcing every identity plugin to become response-aware.
+  apply: <S extends AnyServer>(app: S) => S | AnyServer,
+): IdentityPlugin<AddedHookOutput> {
+  return Object.assign(apply, { pluginName: name }) as IdentityPlugin<AddedHookOutput>
 }
 
 /**

package/src/server/registry.ts

@@ -1,6 +1,7 @@
 import type { BinaryResponse, RawResponse } from "../binary.ts"
 import type { InferInput, InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
 import type { Params, RouteSchema } from "./context.ts"
+import type { StatusResponse } from "./runtime-core.ts"
 
 /**
  * One route's input/output shape as the **client** will consume it. `query`/`body`
@@ -17,6 +18,8 @@ export interface RouteInfo {
   readonly query: unknown
   readonly body: unknown
   readonly output: unknown
+  /** The complete inferred/declared status-keyed response map. */
+  readonly responses?: unknown
   /** The route's declared error bodies as a status-keyed record (from `schema.errors`, e.g.
    * `{ 404: NotFound }`); `unknown` when the route declares none. The typed client turns this into
    * a status-discriminated failure union. */
@@ -48,22 +51,73 @@ type RegistryQuery<S extends RouteSchema> = S extends { query: infer Q extends S
   ? InferInput<Q>
   : never
 
-/** The client-visible output: the declared `response` contract when present (so the client sees the
- * contract, not the handler's incidental return), otherwise the inferred handler output. */
-type RegistryOutput<S extends RouteSchema, Output> = S extends {
+type StatusCodeOf<Output> =
+  Output extends StatusResponse<infer Code, unknown> ? (number extends Code ? never : Code) : never
+
+type StatusBodyAt<Output, Code extends number> =
+  Output extends StatusResponse<infer Actual, infer Body>
+    ? Code extends Actual
+      ? Body
+      : never
+    : never
+
+type IsSuccessCode<Code extends number> = `${Code}` extends `2${string}` ? true : false
+
+type EmptyResponseMap = NonNullable<unknown>
+
+type StatusBodies<Output, Codes extends number = StatusCodeOf<Output>> = [Codes] extends [never]
+  ? EmptyResponseMap
+  : { [Code in Codes]: StatusBodyAt<Output, Code> }
+
+/** A dynamic status code cannot be classified as success or failure; expose an opaque success arm
+ * rather than guessing a status or body schema. Explicit route schemas still override this fallback. */
+type DynamicStatusResponses<Output> =
+  Output extends StatusResponse<infer Code, unknown>
+    ? number extends Code
+      ? { 200: unknown }
+      : EmptyResponseMap
+    : EmptyResponseMap
+
+type InferredResponses<Output> = (Exclude<
+  Output,
+  StatusResponse<number, unknown> | Response
+> extends never
+  ? EmptyResponseMap
+  : { 200: Exclude<Output, StatusResponse<number, unknown> | Response> }) &
+  StatusBodies<Output> &
+  DynamicStatusResponses<Output>
+
+type ExplicitResponses<S extends RouteSchema> = (S extends {
   response: infer R extends StandardSchemaV1
 }
-  ? InferOutput<R>
-  : Output
-
-/** A route's declared error-response body types as a STATUS-KEYED record (`schema.errors` →
- * `{ 404: NotFound, 409: Conflict }`), so the typed client can discriminate the failure body by
- * `status`, not just surface a union. `unknown` when the route declares no `errors`. */
-type RegistryErrors<S extends RouteSchema> = S extends {
-  errors: infer E extends Record<number, StandardSchemaV1>
+  ? { 200: InferOutput<R> }
+  : EmptyResponseMap) &
+  (S extends { errors: infer E extends Record<number, StandardSchemaV1> }
+    ? { [K in keyof E]: E[K] extends StandardSchemaV1 ? InferOutput<E[K]> : never }
+    : EmptyResponseMap)
+
+type MergeResponseMaps<Inferred, Explicit> = Omit<Inferred, keyof Explicit> & Explicit
+
+type ResponseMap<S extends RouteSchema, Output> = MergeResponseMaps<
+  InferredResponses<Output>,
+  ExplicitResponses<S>
+>
+
+/** Public type seam for build-time consumers that need the complete route response map. */
+export type ResponseMapFor<S extends RouteSchema, Output> = ResponseMap<S, Output>
+
+type ResponseErrors<M> = {
+  [K in keyof M as K extends number ? (IsSuccessCode<K> extends true ? never : K) : never]: M[K]
 }
-  ? { [K in keyof E]: E[K] extends StandardSchemaV1 ? InferOutput<E[K]> : never }
-  : unknown
+
+type ResponseSuccessBodies<M> = {
+  [K in keyof M]: K extends number ? (IsSuccessCode<K> extends true ? M[K] : never) : never
+}[keyof M]
+
+type NonEmptyOrUnknown<M> = keyof M extends never ? unknown : M
+
+/** The client-visible output is the union of all inferred/declared 2xx bodies. */
+type RegistryOutput<S extends RouteSchema, Output> = ResponseSuccessBodies<ResponseMap<S, Output>>
 
 /** The SSE event payload type from a route's `sse` schema; `never` for ordinary routes. */
 type RegistrySse<S extends RouteSchema> = S extends { sse: infer E extends StandardSchemaV1 }
@@ -71,12 +125,13 @@ type RegistrySse<S extends RouteSchema> = S extends { sse: infer E extends Stand
   : never
 
 /** Build a {@link RouteInfo} from a route's path, schema, and handler output type. */
-export type RouteInfoFor<Path extends string, S extends RouteSchema, Output> = {
+export type RouteInfoFor<Path extends string, S extends RouteSchema, Output, HookOutput = never> = {
   readonly params: Params<Path>
   readonly query: RegistryQuery<S>
   readonly body: RegistryBody<S>
-  readonly output: RegistryOutput<S, Output>
-  readonly errors: RegistryErrors<S>
+  readonly output: RegistryOutput<S, Output | HookOutput>
+  readonly responses?: ResponseMapFor<S, Output | HookOutput>
+  readonly errors: NonEmptyOrUnknown<ResponseErrors<ResponseMapFor<S, Output | HookOutput>>>
   readonly sse: RegistrySse<S>
 }
 

package/src/server/request-context.ts

@@ -5,20 +5,14 @@
  * sits below the server module in the graph.
  */
 import type { RequestBudget } from "../budget.ts"
-import {
-  applyTransportCap,
-  drainCapped,
-  hasTrustedBodyFraming,
-  parseContentLength,
-  RAW_BODY_READERS,
-  readBoundedBytes,
-} from "./body.ts"
+import { applyTransportCap, readBoundedBytes } from "./body.ts"
+import { readBoundedJsonSource } from "./body-lane.ts"
 import type { Platform } from "./context.ts"
 import { type CookieOptions, cookieNamePrefix, parseCookies, serializeCookie } from "./cookies.ts"
 import { headerObjectOf } from "./headers.ts"
 import { plainError } from "./http.ts"
-import { guardParsedValue, type ProtoPoisoning, parseJsonGuarded } from "./proto-guard.ts"
-import { isUrlEncodedForm, readBoundedForm, searchOf } from "./query.ts"
+import type { ProtoPoisoning } from "./proto-guard.ts"
+import { searchOf } from "./query.ts"
 import { responseJsonContentType } from "./respond.ts"
 import {
   CONTEXT_SEARCH,
@@ -28,13 +22,11 @@ import {
   getUnboundedRequestBudget,
   headerOf,
   isResponseResult,
-  PRE_DECODED_BODY,
-  type PreDecodedBody,
-  type ResponseResult,
   requestOf,
-  TEXT_DECODER,
 } from "./runtime-core.ts"
-import type { CtxSet, MaybePromise, RawContext, RequestSource } from "./server.ts"
+import type { CtxSet, RawContext, RequestSource } from "./server.ts"
+
+export { readBodyFramed, readBoundedJsonSource } from "./body-lane.ts"
 
 /** A fixed past instant for cookie deletion (`Expires`). A literal epoch - deterministic, unlike an
  * argless `new Date()`. */
@@ -428,250 +420,3 @@ async function readBoundedJsonBodyOrThrow<T>(
  * with an in-cap `Content-Length` take the runtime's fused `json()` and walk the parsed value;
  * chunked or length-less requests fall back to the streaming byte-cap guard.
  */
-/**
- * Deliberately **not** `async`: the framed lane is the hot path for every JSON POST, and an async
- * wrapper costs a coroutine frame, a wrapper promise, and an extra microtask hop on top of the one
- * the body read already pays (~90ns/request on Node, measured). The lane returns the body read's
- * 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 | ResponseResult) => T | Promise<T>
-type JsonErrorContinuation<T> = (error: unknown) => T | Promise<T>
-type FramedJsonSource = RequestSource & {
-  readonly bytes?: () => Promise<Uint8Array>
-  readonly jsonWithByteLength?: () => Promise<{
-    readonly value: unknown
-    readonly byteLength: number
-  }>
-}
-
-export function readBoundedJsonSource(
-  req: RequestSource,
-  maxBytes: number,
-  protoPoisoning?: ProtoPoisoning,
-): Promise<unknown | ResponseResult>
-export function readBoundedJsonSource<T>(
-  req: RequestSource,
-  maxBytes: number,
-  protoPoisoning: ProtoPoisoning,
-  onResult: JsonResultContinuation<T>,
-  onError: JsonErrorContinuation<T>,
-): Promise<T>
-export function readBoundedJsonSource<T>(
-  req: RequestSource,
-  maxBytes: number,
-  protoPoisoning: ProtoPoisoning = "reject",
-  onResult?: JsonResultContinuation<T>,
-  onError?: JsonErrorContinuation<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.
-  const preDecoded = (req as { [PRE_DECODED_BODY]?: PreDecodedBody })[PRE_DECODED_BODY]
-  if (preDecoded !== undefined) {
-    return onResult === undefined
-      ? Promise.resolve(preDecoded.value)
-      : Promise.resolve(preDecoded.value).then(onResult)
-  }
-  // Read through the pre-cap readers when the request is transport-capped: this lane enforces its
-  // own `maxBytes` (which may exceed the route's transport cap), so the shadowed user-facing
-  // readers must not narrow it.
-  // Keep the source's header dispatch local: the normal Node source exposes a direct `header`
-  // lookup, while a Web Request only exposes `Headers.get`. Rechecking that optional method through
-  // `headerOf` twice per body is measurable on the framed lane. The raw-reader shadow is still
-  // bypassed for reads, but header authority remains the original source (same semantics as before).
-  const raw = ((req as { [RAW_BODY_READERS]?: RequestSource })[RAW_BODY_READERS] ??
-    req) as FramedJsonSource
-  const sourceHeader = req.header
-  const declared =
-    sourceHeader === undefined
-      ? req.headers.get("content-length")
-      : sourceHeader.call(req, "content-length")
-  if (declared !== null) {
-    // A present Content-Length must be a non-negative integer (HTTP grammar: `1*DIGIT`). A
-    // non-numeric / negative / fractional / exponential value (`Number()` would happily accept
-    // "abc"->NaN, "-5", "1.5", "1e3", "0x10") is malformed -> 400, rather than silently falling
-    // through to the streaming guard - which is an UPPER-bound cap only, so a lying SMALLER length
-    // would otherwise be read in full. Real HTTP servers only hand us a valid framed length; this
-    // hardens hand-built Requests (tests, the in-process client) and crafted input.
-    const length = parseContentLength(declared)
-    if (length === undefined)
-      return onResult === undefined
-        ? Promise.resolve(plainError(400, "invalid_content_length"))
-        : Promise.resolve(plainError(400, "invalid_content_length")).then(onResult)
-    if (length > maxBytes)
-      return onResult === undefined
-        ? 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) {
-      const jsonWithByteLength = raw.jsonWithByteLength
-      if (jsonWithByteLength !== undefined) {
-        return jsonWithByteLength.call(raw).then(
-          ({ value, byteLength }) => {
-            if (byteLength > length || byteLength > maxBytes) {
-              return onResult === undefined
-                ? plainError(413, "payload_too_large")
-                : onResult(plainError(413, "payload_too_large"))
-            }
-            let guarded: unknown
-            try {
-              guarded = guardParsedValue(value, 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 bytesReader = raw.bytes
-      if (bytesReader !== undefined) {
-        return bytesReader.call(raw).then(
-          (bytes) => {
-            if (bytes.byteLength > length || bytes.byteLength > maxBytes) {
-              return onResult === undefined
-                ? plainError(413, "payload_too_large")
-                : onResult(plainError(413, "payload_too_large"))
-            }
-            try {
-              const parsed = parseJsonGuarded(TEXT_DECODER.decode(bytes), protoPoisoning)
-              return onResult === undefined ? parsed : onResult(parsed)
-            } catch {
-              return onResult === undefined
-                ? plainError(400, "invalid_json")
-                : onResult(plainError(400, "invalid_json"))
-            }
-          },
-          () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON())),
-        )
-      }
-      // Read the actual framed bytes before parsing. A declared length is only a hint on Web
-      // Requests and adapter-shaped sources: a caller can construct a Request (or an adapter can
-      // decode/expand a body) whose header claims fewer bytes than the delivered payload. Calling
-      // native `json()` here would accept that understatement and bypass the cap. The byte lane
-      // already owns this post-read check; keeping the JSON lane on the same raw-byte read makes the
-      // trust boundary consistent. `Uint8Array(buffer)` is a view, not a copy.
-      return raw.arrayBuffer().then(
-        (buffer) => {
-          const bytes = new Uint8Array(buffer)
-          if (bytes.byteLength > length || bytes.byteLength > maxBytes) {
-            return onResult === undefined
-              ? plainError(413, "payload_too_large")
-              : onResult(plainError(413, "payload_too_large"))
-          }
-          let parsed: unknown
-          try {
-            parsed = parseJsonGuarded(TEXT_DECODER.decode(bytes), protoPoisoning)
-          } catch {
-            return onResult === undefined
-              ? plainError(400, "invalid_json")
-              : onResult(plainError(400, "invalid_json"))
-          }
-          return onResult === undefined ? parsed : onResult(parsed)
-        },
-        () => (onResult === undefined ? INVALID_JSON() : onResult(INVALID_JSON())),
-      )
-    }
-  }
-  const streamed = readStreamedJsonSource(raw, maxBytes, protoPoisoning)
-  return onResult === undefined ? streamed : streamed.then(onResult, onError)
-}
-
-/** 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 = (): 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 | ResponseResult> {
-  const body = raw.body
-  if (body === null) return plainError(400, "invalid_json")
-  const drained = await drainCapped(body, maxBytes)
-  if (!drained.ok) return plainError(413, "payload_too_large")
-  try {
-    return parseJsonGuarded(TEXT_DECODER.decode(drained.bytes), protoPoisoning)
-  } catch {
-    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))
-  }
-}