@nifrajs/core 5.5.1 → 5.7.0

package/src/server/answer-step.ts

@@ -0,0 +1,68 @@
+import { RouteConfigError } from "../errors.ts"
+import type { RouteSchema } from "./context.ts"
+
+/**
+ * A schema's own step around what answers a route, for a schema that changes how the answer it
+ * describes is written: `t.bytes()` has every `Uint8Array` leave as base64. It sits on the schema's
+ * `validate`, so a spread copy keeps it, and is read once, at registration.
+ */
+const ANSWER_STEP = Symbol.for("nifra.schema.answerStep")
+
+/** The part of a request's context a step reads: the `c.json(...)` reply it made, and its value. */
+export interface JsonReplyContext {
+  readonly jsonReply?: Response | undefined
+  readonly jsonBody?: unknown
+  json(body: unknown, init?: ResponseInit): Response
+}
+
+/**
+ * What can answer a route: its handler, and each hook whose return value takes the handler's place -
+ * a `beforeHandle` that answers first, an `afterHandle` that replaces the answer, an `onError` that
+ * answers an error. Each takes the request's context, as a `JsonReplyContext`.
+ */
+export interface AnswerStages {
+  readonly handler: (context: never) => unknown
+  readonly beforeHandle: readonly ((context: never) => unknown)[]
+  readonly afterHandle: readonly ((result: unknown, context: never) => unknown)[]
+  readonly onError: readonly ((error: unknown, context: never) => unknown)[]
+}
+
+export interface AnswerStep {
+  /** Why the schema cannot describe a request or an event stream, and what to use there instead. */
+  readonly misplaced: string
+  /** `stages`, each wrapped so what it answers is written the schema's way. */
+  readonly wrap: <S extends AnswerStages>(stages: S) => S
+}
+
+function stepOf(schema: object | undefined): AnswerStep | undefined {
+  const validate = schema === undefined ? undefined : Reflect.get(schema, "~standard")?.validate
+  return typeof validate === "function" ? Reflect.get(validate, ANSWER_STEP) : undefined
+}
+
+const REQUEST_FIELDS = ["params", "headers", "cookies", "query", "body", "sse"] as const
+
+/** `stages` wrapped by each step its route's `response` and `errors` schemas carry. */
+export function withAnswerSteps<S extends AnswerStages>(
+  schema: RouteSchema | undefined,
+  method: string,
+  path: string,
+  stages: S,
+): S {
+  if (schema === undefined) return stages
+  for (const field of REQUEST_FIELDS) {
+    const step = stepOf(schema[field])
+    if (step !== undefined) {
+      throw new RouteConfigError(
+        "RESPONSE_ONLY_SCHEMA",
+        `route ${method} ${path}, \`${field}\`: ${step.misplaced}`,
+      )
+    }
+  }
+  const steps = new Set<AnswerStep["wrap"]>()
+  for (const answer of [schema.response, ...Object.values(schema.errors ?? {})]) {
+    const step = stepOf(answer)
+    if (step !== undefined) steps.add(step.wrap)
+  }
+  for (const wrap of steps) stages = wrap(stages)
+  return stages
+}

package/src/server/bare-error-lane.ts

@@ -17,9 +17,10 @@
  * which lane caught it. Both the generic bare lane and the fused body runner route here, so that
  * decision lives in exactly one place.
  */
-import { pathnameOf } from "./http.ts"
+import { clientBodyErrorCode } from "./body.ts"
+import { pathnameOf, plainError } from "./http.ts"
 import type { Logger } from "./logger.ts"
-import { isResponseResult } from "./runtime-core.ts"
+import { isResponseResult, type ResponseResult } from "./runtime-core.ts"
 import type { CtxSet, RawContext } from "./server.ts"
 
 /** How much of a thrown error's own text reaches the log sink. Mirrors `Server`'s option. */
@@ -31,6 +32,8 @@ export type ErrorLogDetail = "full" | "message" | "none"
  *     Either renders through the same `finalize` a RETURNED one takes, with the request's `c.set`,
  *     so a thrown one means what the return means: a `Response` ships as built, plus the cookies the
  *     request queued (the set-session-then-`throw redirect()` pattern);
+ *   - a request body the app's own `c.req.json()` or `c.req.formData()` could not parse is the
+ *     client's 400 (`invalid_json`, `invalid_form`);
  *   - anything else is a real fault: logged once, then a bodyless 500 (never the caller's error text).
  *
  * `responseSet` and `logError` are injected rather than imported so this file keeps no runtime edge
@@ -43,11 +46,13 @@ export function renderBareError<T>(
   finalize: (result: unknown, set: CtxSet, ctx: RawContext) => T,
   responseSet: (ctx: RawContext) => CtxSet,
   logError: (err: unknown, ctx: RawContext) => void,
-  internalError: () => T,
+  wrapResponse: (response: ResponseResult) => T,
 ): T {
   if (err instanceof Response || isResponseResult(err)) return finalize(err, responseSet(ctx), ctx)
+  const clientCode = clientBodyErrorCode(err)
+  if (clientCode !== undefined) return wrapResponse(plainError(400, clientCode))
   logError(err, ctx)
-  return internalError()
+  return wrapResponse(plainError(500, "internal_error"))
 }
 
 /**

package/src/server/base64-answers.ts

@@ -0,0 +1,138 @@
+/**
+ * Bytes in a JSON answer, written as base64.
+ *
+ * `JSON.stringify` writes a `Uint8Array` as `{"0":1,"1":2,...}`, and nothing about that throws, so
+ * finding one costs a walk of every answer. Only a route that asks pays for that walk: `t.bytes()` in
+ * its `response` or `errors` has core hand {@link withBase64Bytes} the route's handler and the hooks
+ * that can answer in its place, and every `Uint8Array` in what any of them returns or throws as an
+ * answer becomes a base64 string before a later hook, contract or writer sees it. Nothing in the
+ * server imports this module, so an app that never declares the field never bundles it.
+ */
+import { tagStandIn } from "../internal/hook-origins.ts"
+import type { AnswerStages, JsonReplyContext } from "./answer-step.ts"
+import { isResponseResult, status } from "./runtime-core.ts"
+
+// Deeper than any real payload.
+const MAX_DEPTH = 64
+// So `String.fromCharCode(...)` never overflows the call stack.
+const CHUNK = 0x8000
+
+function base64(bytes: Uint8Array): string {
+  let binary = ""
+  for (let i = 0; i < bytes.length; i += CHUNK)
+    binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK))
+  return btoa(binary)
+}
+
+function define(out: object, key: string, value: unknown): void {
+  // `out[key] = value` for "__proto__" would replace the prototype instead of adding the field.
+  Object.defineProperty(out, key, { value, enumerable: true, writable: true, configurable: true })
+}
+
+/**
+ * `value` with each `Uint8Array` as base64, copying only the containers above one. A container already
+ * on the walk's path is left as it is, so a cycle costs one step, as it does `JSON.stringify`, which
+ * then refuses it.
+ */
+function encoded(value: unknown, depth: number, path: Set<object>): unknown {
+  if (value instanceof Uint8Array) return base64(value)
+  if (typeof value !== "object" || value === null || depth > MAX_DEPTH || path.has(value))
+    return value
+  // A `Date` (or any value with a hook) writes itself.
+  if (typeof Reflect.get(value, "toJSON") === "function") return value
+  path.add(value)
+  try {
+    if (Array.isArray(value)) {
+      let out: unknown[] | undefined
+      for (let i = 0; i < value.length; i++) {
+        const next = encoded(value[i], depth + 1, path)
+        if (next === value[i]) continue
+        out ??= [...value]
+        out[i] = next
+      }
+      return out ?? value
+    }
+    let out: object | undefined
+    for (const key of Object.keys(value)) {
+      const item: unknown = Reflect.get(value, key)
+      const next = encoded(item, depth + 1, path)
+      if (next === item) continue
+      out ??= { ...value }
+      define(out, key, next)
+    }
+    return out ?? value
+  } finally {
+    path.delete(value)
+  }
+}
+
+const encodedBody = (body: unknown): unknown => encoded(body, 0, new Set())
+
+/** An answer with its bytes encoded. A raw `Response` is left alone; a `c.json(...)` reply is rebuilt
+ * from the value it was made from, keeping its status and headers. */
+function encodedAnswer(answer: unknown, c: JsonReplyContext): unknown {
+  if (answer instanceof Response) {
+    if (answer !== c.jsonReply) return answer
+    const body = encodedBody(c.jsonBody)
+    if (body === c.jsonBody) return answer
+    const headers = new Headers(answer.headers)
+    headers.delete("content-length")
+    return c.json(body, { status: answer.status, headers })
+  }
+  if (isResponseResult(answer)) {
+    const plain = answer.plain
+    if (plain === undefined) return answer
+    const body = encodedBody(plain.body)
+    if (body === plain.body) return answer
+    return status(
+      plain.status,
+      body,
+      plain.headers === undefined ? undefined : { headers: plain.headers },
+    )
+  }
+  return encodedBody(answer)
+}
+
+/** A thrown answer (`status(...)`, `c.json(...)`) is encoded too; any other throw passes untouched. */
+const encodedThrow = (thrown: unknown, c: JsonReplyContext): unknown =>
+  thrown instanceof Response || isResponseResult(thrown) ? encodedAnswer(thrown, c) : thrown
+
+/**
+ * `stage` with what it returns or throws as an answer encoded. Its context is argument `at`; an
+ * `undefined` return (a hook that lets the route go on) stays `undefined`.
+ */
+function encoding<F extends (...args: never[]) => unknown>(stage: F, at: 0 | 1): F {
+  const wrapped = (...args: never[]): unknown => {
+    const c: JsonReplyContext = args[at]!
+    let result: unknown
+    try {
+      result = stage(...args)
+    } catch (thrown) {
+      throw encodedThrow(thrown, c)
+    }
+    if (!(result instanceof Promise)) return encodedAnswer(result, c)
+    return result.then(
+      (answer) => encodedAnswer(answer, c),
+      (thrown) => {
+        throw encodedThrow(thrown, c)
+      },
+    )
+  }
+  // Named as the stage, so stack traces and the hook report still name the author's function.
+  Object.defineProperty(wrapped, "name", { value: stage.name })
+  tagStandIn(wrapped, stage)
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the wrapper takes `F`'s arguments and returns `unknown`, which is every stage's own return type.
+  return wrapped as F
+}
+
+/** A route's handler and answering hooks, each wrapped so every `Uint8Array` it answers leaves as
+ * base64. */
+export function withBase64Bytes<S extends AnswerStages>(stages: S): S {
+  return {
+    ...stages,
+    handler: encoding(stages.handler, 0),
+    beforeHandle: stages.beforeHandle.map((hook) => encoding(hook, 0)),
+    afterHandle: stages.afterHandle.map((hook) => encoding(hook, 1)),
+    onError: stages.onError.map((hook) => encoding(hook, 1)),
+  }
+}

package/src/server/before-handler.ts

@@ -0,0 +1,14 @@
+import type { Context } from "./context.ts"
+
+/** Hooks {@link beforeHandler} marked; the kernel keeps them after guards registered later. */
+export const LAST_BEFORE_HANDLE = new WeakSet<object>()
+
+/**
+ * Mark a `beforeHandle` hook to run just before the handler: a guard registered after it in the same
+ * scope still goes ahead of it, so it only sees requests every guard admitted. A hook that answers
+ * from stored state (an idempotency replay) needs this, or it would answer ahead of a later guard.
+ */
+export function beforeHandler<H extends (context: Context) => unknown>(hook: H): H {
+  LAST_BEFORE_HANDLE.add(hook)
+  return hook
+}

package/src/server/body-lane.ts

@@ -30,6 +30,10 @@ type FramedJsonSource = RequestSource & {
 
 const INVALID_JSON = (): ResponseResult => plainError(400, "invalid_json")
 
+// `Deno.serve`'s own `Request.json()` keeps a leading UTF-8 byte order mark that its `text()` and every
+// other runtime's `json()` drop, so it refuses a body they parse. Deno decodes the bytes itself below.
+const nativeJsonKeepsBom = "Deno" in globalThis
+
 /** Read a JSON source with the declared-length precheck, delivered-byte recheck, streaming cap, and
  * prototype-poisoning guard in one lane. */
 export function readBoundedJsonSource(
@@ -72,7 +76,7 @@ export function readBoundedJsonSource<T>(
         ? Promise.resolve(plainError(413, "payload_too_large"))
         : Promise.resolve(plainError(413, "payload_too_large")).then(onResult)
 
-    if (hasTrustedBodyFraming(req)) {
+    if (hasTrustedBodyFraming(req) && !nativeJsonKeepsBom) {
       return raw.json().then(
         (parsed) => {
           try {
@@ -156,17 +160,23 @@ export function readBoundedJsonSource<T>(
   }
 
   const body = raw.body
+  // A body off a client's connection that fails mid-read is refused as this lane's other failures
+  // are; one built in this process, or a stream the app already holds, keeps its error.
+  const refuseFailedRead = body !== null && !body.locked && hasTrustedBodyFraming(req)
   const streamed =
     body === null
       ? Promise.resolve<unknown | ResponseResult>(plainError(400, "invalid_json"))
-      : drainCapped(body, maxBytes).then((drained) => {
-          if (!drained.ok) return plainError(413, "payload_too_large")
-          try {
-            return parseJsonGuarded(TEXT_DECODER.decode(drained.bytes), protoPoisoning)
-          } catch {
-            return plainError(400, "invalid_json")
-          }
-        })
+      : drainCapped(body, maxBytes).then(
+          (drained) => {
+            if (!drained.ok) return plainError(413, "payload_too_large")
+            try {
+              return parseJsonGuarded(TEXT_DECODER.decode(drained.bytes), protoPoisoning)
+            } catch {
+              return plainError(400, "invalid_json")
+            }
+          },
+          refuseFailedRead ? INVALID_JSON : undefined,
+        )
   return onResult === undefined ? streamed : streamed.then(onResult, onError)
 }
 

package/src/server/body-parser.ts

@@ -210,11 +210,7 @@ export function bodyParser<Schema extends StandardSchemaV1>(
         : inner(source, contentType, maxBodyBytes, protoPoisoning)
     }
     const body = await readBoundedBytes(source, maxBodyBytes)
-    if (!body.ok) {
-      return body.status === 413
-        ? plainError(413, "payload_too_large")
-        : plainError(400, "invalid_content_length")
-    }
+    if (!body.ok) return plainError(body.status, body.error)
     try {
       const value = await parse(body.bytes, { mediaType, contentType })
       settle(value, protoPoisoning)

package/src/server/body.ts

@@ -12,6 +12,7 @@ import { jsonError } from "./http.ts"
 interface BodySource {
   readonly headers: Pick<Headers, "get">
   readonly body: ReadableStream<Uint8Array> | null
+  readonly bodyUsed?: boolean
   arrayBuffer(): Promise<ArrayBuffer>
   bytes?(): Promise<Uint8Array>
 }
@@ -20,6 +21,7 @@ interface BodySource {
 export interface RawBodyReaders {
   readonly headers: Pick<Headers, "get">
   readonly body: ReadableStream<Uint8Array> | null
+  readonly bodyUsed?: boolean
   arrayBuffer(): Promise<ArrayBuffer>
   /** Runtime-native exact-byte reader, when the request implementation exposes one. */
   bytes?(): Promise<Uint8Array>
@@ -65,13 +67,26 @@ export function parseContentLength(value: string): number | undefined {
   return length
 }
 
+/** Why a bounded read refused a body: the status and the error code it is answered with. */
+export type BoundedReadFailure =
+  | { ok: false; status: 413; error: "payload_too_large" }
+  | { ok: false; status: 400; error: "invalid_content_length" | "invalid_body" }
+
+const TOO_LARGE: { ok: false; status: 413; error: "payload_too_large" } = {
+  ok: false,
+  status: 413,
+  error: "payload_too_large",
+}
+const BAD_LENGTH: BoundedReadFailure = { ok: false, status: 400, error: "invalid_content_length" }
+const UNREADABLE: BoundedReadFailure = { ok: false, status: 400, error: "invalid_body" }
+
 /** The shared streaming byte-cap loop: read until done, or cancel + 413 once over `maxBytes`.
  * A single-chunk body (the common case for small chunked payloads) returns the runtime's own
  * chunk directly - no chunk array, no copy-merge. */
 export async function drainCapped(
   body: ReadableStream<Uint8Array>,
   maxBytes: number,
-): Promise<{ ok: true; bytes: Uint8Array } | { ok: false; status: 413 }> {
+): Promise<{ ok: true; bytes: Uint8Array } | typeof TOO_LARGE> {
   assertByteLimit(maxBytes)
   const reader = body.getReader()
   let first: Uint8Array | undefined
@@ -85,7 +100,7 @@ export async function drainCapped(
       // Not awaited: on a teed body (a `clone()` taken first) the cancel settles only once the other
       // branch is read or cancelled too, and nothing here ever reads it.
       reader.cancel().catch(() => {})
-      return { ok: false, status: 413 }
+      return TOO_LARGE
     }
     if (first === undefined) {
       first = value
@@ -112,38 +127,55 @@ export async function drainCapped(
  * `Content-Length` within the cap is read via native `arrayBuffer()`, then the **real** byte count
  * is checked against the declared length - a source that delivers more than it declared (a lying
  * or upstream-decoding adapter) is rejected with `413` even though its header passed the hint.
+ * A body a runtime took off a client's connection that fails while it is read - a client that hung
+ * up inside it, which only Deno hands an app - is refused `400` `invalid_body`. A body built in this
+ * process keeps its producer's error, and a reader the app spent or locked keeps its throw.
  */
 export async function readBoundedBytes(
   source: BodySource,
   maxBytes: number,
-): Promise<{ ok: true; bytes: Uint8Array } | { ok: false; status: 400 | 413 }> {
+): Promise<{ ok: true; bytes: Uint8Array } | BoundedReadFailure> {
   assertByteLimit(maxBytes)
   const req = rawBodySourceOf(source)
   const declared = req.headers.get("content-length")
+  let length: number | undefined
   if (declared !== null) {
     // A present Content-Length must be a non-negative integer (HTTP grammar: `1*DIGIT`). A non-numeric
     // / negative / fractional value is malformed → 400, rather than falling through to the streaming
     // guard (an UPPER-bound cap only, so a lying SMALLER length would otherwise be read in full).
-    const length = parseContentLength(declared)
-    if (length === undefined) return { ok: false, status: 400 }
-    if (length > maxBytes) return { ok: false, status: 413 }
-    const chunked = req.headers.get("transfer-encoding") !== null
-    if (!chunked) {
-      const bytesReader = req.bytes
-      const bytes =
-        bytesReader === undefined
-          ? new Uint8Array(await req.arrayBuffer())
-          : await bytesReader.call(req)
-      // Content-Length was the fast-reject hint, never the enforcement: a lying or buffering
-      // source (an adapter that decoded/expanded the body upstream) can hand over more bytes
-      // than it declared. `length <= maxBytes` held above, so one comparison seals the cap.
-      if (bytes.byteLength > length) return { ok: false, status: 413 }
-      return { ok: true, bytes }
+    length = parseContentLength(declared)
+    if (length === undefined) return BAD_LENGTH
+    if (length > maxBytes) return TOO_LARGE
+  }
+  const fromClient = hasTrustedBodyFraming(source) || hasTrustedBodyFraming(req)
+  if (length !== undefined && req.headers.get("transfer-encoding") === null) {
+    // Called outside the `try`: a spent reader throws synchronously, and that throw is the app's.
+    // A Request the app already read or locked rejects instead. Only a read that disturbed an unused
+    // body failed on the client's side; Bun marks a locked body used, Node and Deno leave it unused.
+    const usedBefore = req.bodyUsed
+    const bytesReader = req.bytes
+    const reading =
+      bytesReader === undefined
+        ? req.arrayBuffer().then((buffer) => new Uint8Array(buffer))
+        : bytesReader.call(req)
+    let bytes: Uint8Array
+    try {
+      bytes = await reading
+    } catch (error) {
+      if (fromClient && usedBefore !== true && req.bodyUsed !== false) return UNREADABLE
+      throw error
     }
+    // Content-Length was the fast-reject hint, never the enforcement: a lying or buffering
+    // source (an adapter that decoded/expanded the body upstream) can hand over more bytes
+    // than it declared. `length <= maxBytes` held above, so one comparison seals the cap.
+    if (bytes.byteLength > length) return TOO_LARGE
+    return { ok: true, bytes }
   }
   const body = req.body
   if (body === null) return { ok: true, bytes: new Uint8Array(0) }
-  return drainCapped(body, maxBytes)
+  const lockedByApp = body.locked
+  const draining = drainCapped(body, maxBytes)
+  return fromClient && !lockedByApp ? draining.catch(() => UNREADABLE) : draining
 }
 
 /** Key under which a transport-capped request stashes its {@link RawBodyReaders}. */
@@ -184,14 +216,37 @@ const TRANSPORT_CAPPED = new WeakSet<object>()
 
 const CAP_DECODER = new TextDecoder()
 
+// The error a capped `json()` or `formData()` raised on the request's own bytes, kept as the
+// `Request` reader rejects so app code that catches it is unchanged, with the code it answers. One
+// the app lets escape is the client's 400.
+const CLIENT_BODY_ERRORS = new WeakMap<object, "invalid_json" | "invalid_form">()
+
+/** The 400 code for a request body a capped reader could not parse, or `undefined` for any other error. */
+export const clientBodyErrorCode = (err: unknown): "invalid_json" | "invalid_form" | undefined =>
+  err instanceof Error ? CLIENT_BODY_ERRORS.get(err) : undefined
+
+function parseClientJson(bytes: Uint8Array): unknown {
+  try {
+    return JSON.parse(CAP_DECODER.decode(bytes))
+  } catch (error) {
+    if (error instanceof Error) CLIENT_BODY_ERRORS.set(error, "invalid_json")
+    throw error
+  }
+}
+
+function clientFormError(error: unknown): never {
+  if (error instanceof Error) CLIENT_BODY_ERRORS.set(error, "invalid_form")
+  throw error
+}
+
 /** Key under which the dispatcher marks a source with its route's transport byte cap. */
 const TRANSPORT_CAP = Symbol("nifra.body.transportCap")
 
 /** The transport cap's over-cap rejection: the flat error a shadowed direct reader throws (and the
  * capped `body` stream errors with). The lifecycle already treats a thrown `Response` as control
  * flow (the `c.boundedBody` contract), so an over-cap direct read answers 413 like every other cap. */
-function transportCapError(status: 400 | 413): Response {
-  return jsonError(status, status === 413 ? "payload_too_large" : "invalid_content_length")
+function transportCapError(failure: BoundedReadFailure): Response {
+  return jsonError(failure.status, failure.error)
 }
 
 /**
@@ -211,11 +266,11 @@ export function capBodyBytes(request: Request, maxBytes: number): Request {
       new TransformStream<Uint8Array, Uint8Array>({
         start(controller) {
           if (length === undefined || length > maxBytes)
-            controller.error(transportCapError(length === undefined ? 400 : 413))
+            controller.error(transportCapError(length === undefined ? BAD_LENGTH : TOO_LARGE))
         },
         transform(chunk, controller) {
           total += chunk.byteLength
-          if (total > maxBytes) controller.error(transportCapError(413))
+          if (total > maxBytes) controller.error(transportCapError(TOO_LARGE))
           else controller.enqueue(chunk)
         },
       }),
@@ -279,11 +334,11 @@ function spendRaw(raw: RawBodyReaders): void {
   Object.defineProperty(raw, "body", { get: spent })
 }
 
-/** A pass-through stream that errors (with `reject(413)`) once more than `maxBytes` flow through. */
+/** A pass-through stream that errors (with `reject` of a 413) once more than `maxBytes` flow through. */
 function cappedStreamOf(
   body: RawStream,
   maxBytes: number,
-  reject: (status: 400 | 413) => unknown,
+  reject: (failure: BoundedReadFailure) => unknown,
 ): ReadableStream<Uint8Array> {
   // The reader is acquired on first pull, and `highWaterMark: 0` defers that first pull until a
   // consumer actually reads (the default of 1 pulls eagerly at construction): merely *accessing*
@@ -312,7 +367,7 @@ function cappedStreamOf(
           // Not awaited, as in drainCapped: on a teed body the cancel settles only once the other
           // branch is read or cancelled too, and the 413 must not wait for an unread clone.
           active.cancel().catch(() => {})
-          controller.error(reject(413))
+          controller.error(reject(TOO_LARGE))
           return
         }
         controller.enqueue(value)
@@ -332,8 +387,9 @@ function cappedStreamOf(
  * pre-decoded body), and hook-observed references all survive. Nothing is read eagerly: the cap
  * only pays when user code actually reads, and framework readers bypass it through
  * {@link rawBodySourceOf} (stashed under {@link RAW_BODY_READERS}) to enforce their own caps.
- * 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`.
+ * An over-cap read rejects with the cap's flat 413 (a lying `Content-Length` with its 400, a body
+ * that fails mid-read with 400 `invalid_body`), which the lifecycle already treats as control flow -
+ * the same contract as `c.boundedBody`.
  */
 /** The request's own pre-shadow readers - the fallback surface when the source offers none. */
 function requestBodyReaders(request: Request): RawBodyReaders {
@@ -349,6 +405,9 @@ function requestBodyReaders(request: Request): RawBodyReaders {
           : (bodyDescriptor?.value ?? null)
       ) as ReadableStream<Uint8Array> | null
     },
+    get bodyUsed() {
+      return request.bodyUsed
+    },
     arrayBuffer: request.arrayBuffer.bind(request),
     json: request.json.bind(request),
   }
@@ -361,13 +420,15 @@ function capRequestBodyReads(request: Request, maxBytes: number, preset?: RawBod
   TRANSPORT_CAPPED.add(request)
   const reject = transportCapError
   const raw = preset ?? requestBodyReaders(request)
+  // The shadowed readers read through `raw`, which must still say where the body came from.
+  if (hasTrustedBodyFraming(request)) markTrustedBodyFraming(raw)
   // 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
   const cappedBytes = (): Promise<Uint8Array> => {
     if (buffered === undefined) {
       const read = readBoundedBytes(raw, maxBytes).then((result) => {
-        if (!result.ok) throw reject(result.status)
+        if (!result.ok) throw reject(result)
         return result.bytes
       })
       buffered = read
@@ -401,8 +462,7 @@ function capRequestBodyReads(request: Request, maxBytes: number, preset?: RawBod
   shadowed[RAW_BODY_READERS] = raw
   shadowed.arrayBuffer = () => cappedBytes().then(exactArrayBuffer)
   shadowed.bytes = () => cappedBytes().then((bytes) => bytes.slice())
-  shadowed.json = () =>
-    cappedBytes().then((bytes) => JSON.parse(CAP_DECODER.decode(bytes)) as unknown)
+  shadowed.json = () => cappedBytes().then(parseClientJson)
   shadowed.text = () => cappedBytes().then((bytes) => CAP_DECODER.decode(bytes))
   shadowed.blob = () =>
     cappedBytes().then(
@@ -415,7 +475,9 @@ function capRequestBodyReads(request: Request, maxBytes: number, preset?: RawBod
     cappedBytes().then((bytes) =>
       new Response(exactArrayBuffer(bytes), {
         headers: { "content-type": request.headers.get("content-type") ?? "" },
-      }).formData(),
+      })
+        .formData()
+        .catch(clientFormError),
     )
   // `clone()` must not mint an uncapped escape hatch: the clone gets the same cap.
   if (typeof request.clone === "function") {
@@ -489,10 +551,8 @@ export function applyTransportCap(source: object, request: Request): void {
   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
+  // A bodiless request is capped too: its `json()` must fail the way a capped one does, as a client
+  // input error, and Bun.serve hands over `Content-Length: 0` with no body where others give one.
   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

package/src/server/core-copies.ts

@@ -16,14 +16,17 @@ const copies = registry[COPIES]
 const here = String(import.meta.url).split("?")[0] as string
 
 if (!copies.includes(here) && copies.push(here) > 1) {
+  // The registrar marks the process when it installs; without the mark a declared singleCopy was never
+  // armed here, most often because bunfig.toml's preload line sits below a [table] header. Bun-only and
+  // behind the inline NODE_ENV literal, so a production bundle drops the hint.
   console.warn(
-    `[nifra] @nifrajs/core is loaded ${copies.length} times; \`nifra check\` names each importer:\n  ${copies.join("\n  ")}`,
+    `[nifra] @nifrajs/core is loaded ${copies.length} times; \`nifra check\` names each importer:\n  ${copies.join("\n  ")}${typeof Bun !== "undefined" && process.env.NODE_ENV !== "production" && !(Symbol.for("nifra.single-copy.active") in globalThis) ? "\n  No single-copy registrar ran in this process: bunfig.toml must preload @nifrajs/core/single-copy/register at its top level, above any [table], for bun run, and under [test] for bun test." : ""}`,
   )
 }
 
 /** This copy's version: a literal like the package root's `VERSION` (no fs on the edge), which
  * `scripts/version.ts` rewrites on every release and `check:publish` asserts. */
-const COPY_VERSION = "5.5.1"
+const COPY_VERSION = "5.7.0"
 
 /** Record this copy's version beside its URL. Called by each `server()` behind the development guard,
  * so a production bundle drops it with the version; a copy that built a server has recorded one. */

package/src/server/http.ts

@@ -114,26 +114,17 @@ export interface UrlParts {
 // Extract pathname + query WITHOUT a full WHATWG `new URL(req.url)` parse.
 // `req.url` from every supported runtime is an absolute, already-normalized URL, so the pathname is
 // the substring after `scheme://host[:port]` up to `?`/`#`. Query-schema routes also need the search
-// string; parsing both in one scanner avoids the old `pathnameOf()` + `searchOf()` double scan.
+// string; splitting both together avoids the old `pathnameOf()` + `searchOf()` repeated parsing.
 export function urlPartsOf(url: string): UrlParts {
   const schemeEnd = url.indexOf("://")
   const start = schemeEnd === -1 ? url.indexOf("/") : url.indexOf("/", schemeEnd + 3)
   if (start === -1) return { pathname: "/", search: "" }
 
-  let pathEnd = url.length
-  let searchStart = -1
-  let searchEnd = url.length
-  for (let i = start; i < url.length; i++) {
-    const c = url.charCodeAt(i)
-    if (c === 63 /* ? */ && searchStart === -1) {
-      pathEnd = i
-      searchStart = i
-    } else if (c === 35 /* # */) {
-      if (searchStart === -1) pathEnd = i
-      searchEnd = i
-      break
-    }
-  }
+  const fragment = url.indexOf("#", start)
+  const searchEnd = fragment === -1 ? url.length : fragment
+  const question = url.indexOf("?", start)
+  const searchStart = question !== -1 && question < searchEnd ? question : -1
+  const pathEnd = searchStart === -1 ? searchEnd : searchStart
 
   return {
     pathname: url.slice(start, pathEnd),