@nifrajs/core 5.4.0 → 5.5.0

package/src/server/multipart.ts

@@ -71,6 +71,8 @@ const FALLBACK_FILE_NAME = "file"
 const MAX_FILE_NAME_LENGTH = 255
 
 const DASH = 45
+const CR = 13
+const LF = 10
 const QUOTE = 34
 const BACKSLASH = 92
 const SLASH = 47
@@ -148,41 +150,74 @@ function failureTable(pattern: Uint8Array): Uint8Array {
   return table
 }
 
-/** What a scan for `--boundary` found: how many, and whether the last one closes the body. */
+/**
+ * What a scan for `--boundary` found: how many, how many of them close a part with no content, and
+ * whether the last one closes the body.
+ */
 interface Delimiters {
   readonly count: number
+  readonly empty: number
   readonly closed: boolean
 }
 
+/** The most delimiters a scan counts: past either budget the body is refused unparsed. */
+interface DelimiterLimits {
+  readonly filled: number
+  readonly empty: number
+}
+
 /** `end` is the index after the last delimiter, or -1 when there was none. */
-function delimiters(bytes: Uint8Array, count: number, end: number): Delimiters {
-  return { count, closed: end !== -1 && bytes[end] === DASH && bytes[end + 1] === DASH }
+function delimiters(bytes: Uint8Array, count: number, empty: number, end: number): Delimiters {
+  return { count, empty, closed: end !== -1 && bytes[end] === DASH && bytes[end + 1] === DASH }
+}
+
+/**
+ * Whether the delimiter at `at` closes a part with no content: the blank line ending the part's
+ * headers is followed at once by the CRLF that opens the delimiter. A part whose own content ends
+ * in a blank line reads the same, which only spends the empty budget instead of the filled one.
+ */
+function closesEmptyPart(bytes: Uint8Array, at: number): boolean {
+  return (
+    at >= 6 &&
+    bytes[at - 1] === LF &&
+    bytes[at - 2] === CR &&
+    bytes[at - 3] === LF &&
+    bytes[at - 4] === CR &&
+    bytes[at - 5] === LF &&
+    bytes[at - 6] === CR
+  )
 }
 
+const overLimits = (count: number, empty: number, limits: DelimiterLimits): boolean =>
+  count - empty > limits.filled || empty > limits.empty
+
 /** Knuth-Morris-Pratt from `start`: linear in the input whatever the pattern repeats. */
 function scanFrom(
   bytes: Uint8Array,
   pattern: Uint8Array,
   start: number,
   counted: number,
+  countedEmpty: number,
   lastEnd: number,
-  limit: number,
+  limits: DelimiterLimits,
 ): Delimiters {
   const table = failureTable(pattern)
   const size = pattern.length
   let count = counted
+  let empty = countedEmpty
   let end = lastEnd
   for (let i = start, k = 0; i < bytes.length; i++) {
     const byte = bytes[i]
     while (k > 0 && byte !== pattern[k]) k = table[k - 1]!
     if (byte === pattern[k]) k++
     if (k === size) {
+      if (count > 0 && closesEmptyPart(bytes, i + 1 - size)) empty++
       end = i + 1
-      if (++count > limit) break
+      if (overLimits(++count, empty, limits)) break
       k = 0
     }
   }
-  return delimiters(bytes, count, end)
+  return delimiters(bytes, count, empty, end)
 }
 
 /**
@@ -194,10 +229,15 @@ function scanFrom(
  * the verify loop re-read the same bytes (dashes against a boundary of dashes) spends a budget of
  * one pass over the input, then the scan continues with the linear matcher.
  */
-function scanDelimiters(bytes: Uint8Array, pattern: Uint8Array, limit: number): Delimiters {
+function scanDelimiters(
+  bytes: Uint8Array,
+  pattern: Uint8Array,
+  limits: DelimiterLimits,
+): Delimiters {
   const size = pattern.length
   const last = bytes.length - size
   let count = 0
+  let empty = 0
   let end = -1
   let work = 0
   let i = 0
@@ -207,16 +247,17 @@ function scanDelimiters(bytes: Uint8Array, pattern: Uint8Array, limit: number):
     let k = 1
     while (k < size && bytes[i + k] === pattern[k]) k++
     if (k === size) {
+      if (count > 0 && closesEmptyPart(bytes, i)) empty++
       i += size
       end = i
-      if (++count > limit) break
+      if (overLimits(++count, empty, limits)) break
       continue
     }
     work += k
-    if (work > bytes.length) return scanFrom(bytes, pattern, i, count, end, limit)
+    if (work > bytes.length) return scanFrom(bytes, pattern, i, count, empty, end, limits)
     i++
   }
-  return delimiters(bytes, count, end)
+  return delimiters(bytes, count, empty, end)
 }
 
 /** True when `value` takes more than `max` bytes as UTF-8. */
@@ -308,8 +349,13 @@ function createReader(
   const maxFiles = limitOf(limits.maxFiles, DEFAULT_MAX_FILES, "maxFiles")
   const maxFieldBytes = limitOf(limits.maxFieldBytes, DEFAULT_MAX_FIELD_BYTES, "maxFieldBytes")
   const maxFileBytes = limitOf(limits.maxFileBytes, UNLIMITED_BODY_BYTES, "maxFileBytes")
-  // Every part sits between two delimiters, and the last delimiter closes the body.
-  const maxDelimiters = maxFields + maxFiles + 1
+  // Every part sits between two delimiters, and the last delimiter closes the body. A part with no
+  // content - a file input left empty, which is dropped below - spends a budget of its own, so an
+  // untouched optional input does not count against the parts that carry something.
+  const delimiterLimits: DelimiterLimits = {
+    filled: maxFields + maxFiles + 1,
+    empty: maxFields + maxFiles,
+  }
 
   const read: SchemaBodyReader = async (source, contentType, maxBodyBytes, protoPoisoning) => {
     const boundary = boundaryOf(contentType)
@@ -335,8 +381,10 @@ function createReader(
     delimiter[0] = DASH
     delimiter[1] = DASH
     for (let i = 0; i < boundary.length; i++) delimiter[i + 2] = boundary.charCodeAt(i)
-    const found = scanDelimiters(bytes, delimiter, maxDelimiters)
-    if (found.count > maxDelimiters) return plainError(413, "too_many_parts")
+    const found = scanDelimiters(bytes, delimiter, delimiterLimits)
+    if (overLimits(found.count, found.empty, delimiterLimits)) {
+      return plainError(413, "too_many_parts")
+    }
     // A body is over when `--boundary--` says so. One that stops short is refused here, because a
     // parser that tolerates it hands back the parts it saw as if they were the whole form.
     if (!found.closed) return INVALID()

package/src/server/node-outcome.ts

@@ -10,6 +10,7 @@ import {
   normalizeBodylessResponse,
   RESPONSE_OWNED_HEADERS,
   rememberRenderedResponse,
+  responseBodyUsed,
   SENT_BODY,
   taggedResponseBody,
 } from "./respond.ts"
@@ -83,7 +84,7 @@ export function toNodeOutcome(result: HandlerResult, set: CtxSet): NodeServeOutc
     )
   }
   if (result instanceof Response) {
-    if (result.bodyUsed) return plainNodeOutcome(SENT_BODY.plain!, EMPTY_RESPONSE_CONTROLS)
+    if (responseBodyUsed(result)) return plainNodeOutcome(SENT_BODY.plain!, EMPTY_RESPONSE_CONTROLS)
     return nodeOutcomeFromResponse(applySetToResponse(normalizeBodylessResponse(result), set))
   }
   const status = set.status ?? (result === undefined ? 204 : 200)

package/src/server/query.ts

@@ -98,8 +98,10 @@ export function queryObjectOf(search: string): Record<string, QueryValue> {
     const amp = search.indexOf("&", pos)
     const end = amp === -1 ? search.length : amp
     if (end > pos) {
-      const eq = search.indexOf("=", pos)
-      const split = eq !== -1 && eq < end ? eq : end
+      // Bounded by the segment, so a run of bare segments (`a&a&a...`) stays linear; keys are short,
+      // so the loop also beats an `indexOf` call.
+      let split = pos
+      while (split < end && search.charCodeAt(split) !== 61 /* = */) split++
       const key = search.slice(pos, split)
       const value = split === end ? "" : search.slice(split + 1, end)
       setQueryValue(out, key, value)
@@ -159,12 +161,17 @@ export function isJsonMediaType(contentType: string): boolean {
   )
 }
 
-/** `application/x-www-form-urlencoded`, with or without a charset suffix. */
+/** `application/x-www-form-urlencoded`, with or without parameters, in any case (RFC 9110 8.3.1). */
 export function isUrlEncodedForm(contentType: string): boolean {
-  return (
+  if (
     contentType === "application/x-www-form-urlencoded" ||
     contentType.startsWith("application/x-www-form-urlencoded;")
-  )
+  ) {
+    return true
+  }
+  const semi = contentType.indexOf(";")
+  const essence = (semi === -1 ? contentType : contentType.slice(0, semi)).trim().toLowerCase()
+  return essence === "application/x-www-form-urlencoded"
 }
 
 const FORM_DECODER = new TextDecoder()

package/src/server/request-context.ts

@@ -14,7 +14,7 @@ import { headerObjectOf } from "./headers.ts"
 import { plainError } from "./http.ts"
 import type { ProtoPoisoning } from "./proto-guard.ts"
 import { searchOf } from "./query.ts"
-import { responseJsonContentType } from "./respond.ts"
+import { residentText, responseJsonContentType } from "./respond.ts"
 import {
   CONTEXT_REQUEST,
   CONTEXT_SEARCH,
@@ -378,9 +378,12 @@ export class RequestContext implements RawContext {
       }
     }
     // Default to text/plain; if the caller passes their own headers, they own the content-type.
-    if (i?.headers !== undefined) return markResidentBody(new Response(body, i))
+    if (i?.headers !== undefined) return markResidentBody(residentText(new Response(body, i), body))
     return markResidentBody(
-      new Response(body, { ...i, headers: { "content-type": TEXT_CONTENT_TYPE } }),
+      residentText(
+        new Response(body, { ...i, headers: { "content-type": TEXT_CONTENT_TYPE } }),
+        body,
+      ),
     )
   }
 

package/src/server/respond.ts

@@ -314,6 +314,37 @@ export function writableResponse(response: Response, request?: Request): Respons
   return copiedResponse(response, new Response(response.body, response), true)
 }
 
+// Body-bearing responses a hook handed over as a request's answer. The Node writer sends a buffered
+// body without reading it, so `bodyUsed` alone does not show that one was already sent.
+const HANDED_OVER = new WeakSet<Response>()
+
+/**
+ * Whether `response`, handed over by a hook as this request's answer, may be sent: not when its body
+ * already answered a request or was handed over for one. A body-bearing response is claimed here.
+ */
+export function claimHandedOver(response: Response): boolean {
+  if (responseBodyUsed(response) || HANDED_OVER.has(response)) return false
+  if (
+    hasResidentBody(response) ||
+    WRITABLE_BODY_RESPONSES.has(response) ||
+    response.body !== null
+  ) {
+    HANDED_OVER.add(response)
+  }
+  return true
+}
+
+/**
+ * `writableResponse` for a Response a hook hands back in place of the one it was given, with the
+ * single-use check a handler's result gets: a reused body is the internal error a reused handler
+ * result is, carrying none of its earlier request's headers.
+ */
+export function handedBackResponse(response: Response, request: Request): Response {
+  return claimHandedOver(response)
+    ? writableResponse(response, request)
+    : toResponse(SENT_BODY, EMPTY_RESPONSE_CONTROLS, false, undefined, request)
+}
+
 /** `copy`, recorded and carrying `original`'s buffered-body marker: the Node writer still sends the
  * serialized bytes directly, and a marked body-less Response keeps the body only the marker holds. */
 function copiedResponse(original: Response, copy: Response, hasBody: boolean): Response {
@@ -385,6 +416,63 @@ export function taggedResponseOwner(response: Response): object | undefined {
     : undefined
 }
 
+// The text each c.text() response was built from; null once adopted by the body tier. A hook can
+// substitute its body without consuming the original stream, but that source is still single-use.
+const RESIDENT_TEXTS = new WeakMap<Response, string | null>()
+let residentTextsRecorded = false
+
+/** From now on, keep the string of each `c.text()` response for the body tier. */
+export function recordResidentTexts(): void {
+  residentTextsRecorded = true
+}
+
+/** `response`, which `c.text()` built from `body`. */
+export function residentText(response: Response, body: string): Response {
+  if (residentTextsRecorded) RESIDENT_TEXTS.set(response, body)
+  return response
+}
+
+/** Whether the actual body, or its body-tier substitute, has already been handed to a request. */
+export function responseBodyUsed(response: Response): boolean {
+  return response.bodyUsed || RESIDENT_TEXTS.get(response) === null
+}
+
+/** `response` tagged with the text it was built from, so this app's body-tier hooks get the string. */
+function withResidentText(
+  response: Response,
+  source: Response,
+  owner: object | undefined,
+): Response {
+  if (owner === undefined) return response
+  const text = RESIDENT_TEXTS.get(source)
+  if (text === undefined || text === null) return response
+  RESIDENT_TEXTS.set(source, null)
+  return taggedResponseBody(response) !== undefined
+    ? response
+    : markTaggedResponse(response, text, owner)
+}
+
+/** A buffered page built from the body it reports, tagged for this app's body-tier hooks. */
+function bufferedPageResponse(
+  page: {
+    readonly status: number
+    readonly headers: Readonly<Record<string, string | readonly string[]>> | undefined
+    readonly body: string
+  },
+  owner: object,
+): Response {
+  const headers = new Headers()
+  for (const [name, value] of Object.entries(page.headers ?? {})) {
+    if (typeof value === "string") headers.set(name, value)
+    else for (const item of value) headers.append(name, item)
+  }
+  return markTaggedResponse(
+    withBody(new Response(page.body, { status: page.status, headers })),
+    page.body,
+    owner,
+  )
+}
+
 export function markTaggedResponse(
   response: Response,
   body: string | Uint8Array,
@@ -546,20 +634,34 @@ export function toResponse(
         request,
       )
     }
+    // A buffered page is built from the body it reports, so the bytes its hooks see are the ones sent.
+    const owner = typeof tagResponseBody === "object" ? tagResponseBody : undefined
+    const page = owner === undefined ? undefined : result.toNodeBody?.()
+    const response =
+      owner !== undefined &&
+      page !== undefined &&
+      typeof page.body === "string" &&
+      !isBodylessStatus(page.status)
+        ? bufferedPageResponse({ ...page, body: page.body }, owner)
+        : result.toResponse()
     return withStatics(
-      applySetToResponse(normalizeBodylessResponse(result.toResponse(), request), set, request),
+      applySetToResponse(normalizeBodylessResponse(response, request), set, request),
       statics,
       request,
     )
   }
   if (result instanceof Response) {
-    if (result.bodyUsed) {
+    if (responseBodyUsed(result)) {
       return toResponse(SENT_BODY, EMPTY_RESPONSE_CONTROLS, false, statics, request)
     }
-    return withStatics(
-      applySetToResponse(normalizeBodylessResponse(result, request), set, request),
-      statics,
-      request,
+    return withResidentText(
+      withStatics(
+        applySetToResponse(normalizeBodylessResponse(result, request), set, request),
+        statics,
+        request,
+      ),
+      result,
+      typeof tagResponseBody === "object" ? tagResponseBody : undefined,
     )
   }
   return renderValue(result, set, tagResponseBody, statics, request)

package/src/server/runtime-core.ts

@@ -31,6 +31,16 @@ export interface PreDecodedBody {
   readonly value: unknown
   /** The encoded size, so the route's own body limit still applies to a body decoded before routing. */
   readonly byteLength: number
+  /** The bytes as sent and their media type: the stand-in body is not the payload, so an
+   * idempotency fingerprint must be taken over these. */
+  readonly encoded: Uint8Array
+  readonly contentType: string
+}
+
+/** The stash a transport codec left on a request, if one decoded its body. */
+export function preDecodedBody(request: object): PreDecodedBody | undefined {
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: only the codec lane and the idempotency prepare step define this key, each with a PreDecodedBody.
+  return (request as { [PRE_DECODED_BODY]?: PreDecodedBody })[PRE_DECODED_BODY]
 }
 
 /**
@@ -181,12 +191,55 @@ export function requestOf(source: RequestSource): Request {
   return source.request ?? (source as unknown as Request)
 }
 
+// On Deno, reading `headers` builds the request's whole header list: ~4% of a bare route's
+// throughput for one header. A `Deno.serve` request's inner record (Deno's own "request" slot)
+// reads one header off the parsed request: the value `headers.get` would return, except that a name
+// no header can carry reads as absent instead of throwing, as on the Node source. It is used only
+// while the `Headers` are unbuilt (Deno's "headers cache" slot is empty), so the two never disagree;
+// on a closed request both throw Deno's "Request closed". A request Deno did not parse - constructed,
+// cloned, rebuilt - reads `headers`, as before.
+const denoSlots = "Deno" in globalThis ? denoRequestSlots(new Request("http://x/")) : undefined
+
+/** @internal Deno's own slots on a `Request`, found by the names Deno gives them. */
+export interface DenoSlots {
+  readonly inner: symbol
+  readonly headers: symbol
+}
+
+/** @internal */
+export function denoRequestSlots(request: object): DenoSlots | undefined {
+  let inner: symbol | undefined
+  let headers: symbol | undefined
+  for (const key of Object.getOwnPropertySymbols(request)) {
+    if (key.description === "request") inner = key
+    else if (key.description === "headers cache") headers = key
+  }
+  return inner === undefined || headers === undefined ? undefined : { inner, headers }
+}
+
+/** @internal The header as received, or `undefined` when only `headers` can answer. */
+export function denoWireHeader(
+  request: object,
+  slots: DenoSlots,
+  name: string,
+): string | null | undefined {
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: only the two symbol slots are read, and each value is checked before it is used.
+  const slotted = request as Record<symbol, { readonly header?: unknown } | undefined>
+  if (slotted[slots.headers] !== undefined) return undefined
+  const inner = slotted[slots.inner]
+  if (typeof inner?.header !== "function") return undefined
+  const value: unknown = inner.header(name)
+  return value === null || typeof value === "string" ? value : undefined
+}
+
 /** Read one request header. `header()` answers authoritatively when the source implements it - its
  * `null` means ABSENT, not "ask `headers` instead". Falling through on `null` would materialize the
  * lazy sources' full `Headers` object on every absent-header probe (measured at ~4% of request CPU
  * on the Node POST lane, which checks `transfer-encoding` on every request). */
 export function headerOf(source: RequestSource, name: string): string | null {
-  return source.header !== undefined ? source.header(name) : source.headers.get(name)
+  if (source.header !== undefined) return source.header(name)
+  const wire = denoSlots === undefined ? undefined : denoWireHeader(source, denoSlots, name)
+  return wire !== undefined ? wire : source.headers.get(name)
 }
 
 /** Off-edge `waitUntil`: run the background work fire-and-forget, never leaking an unhandled