@nifrajs/core 5.3.0 → 5.5.0

package/src/internal/route-program.ts

@@ -158,6 +158,36 @@ interface RouteProgramRuntime {
     finalize: (result: unknown, set: CtxSet, ctx?: RawContext) => T,
     wrapResponse: (response: Response | ResponseResult) => T,
   ): MaybePromise<T>
+  /** Installed by `idempotency()`, and present whenever a route resolved idempotency. */
+  readonly idempotencyRuntime: {
+    gate<T>(
+      entry: RouteEntry,
+      ctx: RawContext,
+      wrapResponse: (response: Response | ResponseResult) => T,
+      resume: IdempotencyResume<T>,
+      fail: (error: unknown) => MaybePromise<T>,
+    ): Promise<T>
+  }
+}
+
+/**
+ * The rest of a program after the idempotency gate. The gate continues it with the request it
+ * buffered, and with a replay entry and program when the key already holds a response.
+ */
+export type IdempotencyResume<T> = (entry: RouteEntry, program: RouteProgram) => ProgramResult<T>
+
+/** Idempotency infrastructure failures use the same boundary as the resumed route program. */
+function runIdempotencyGate<T>(
+  host: RouteProgramRuntime,
+  entry: RouteEntry,
+  ctx: RawContext,
+  finalize: (result: unknown, set: CtxSet, ctx?: RawContext) => T,
+  wrapResponse: (response: Response | ResponseResult) => T,
+  resume: IdempotencyResume<T>,
+): Promise<T> {
+  return host.idempotencyRuntime.gate(entry, ctx, wrapResponse, resume, (error) =>
+    host.handleProgramError(entry, error, ctx, finalize, wrapResponse),
+  )
 }
 
 function responseSet(ctx: RawContext): CtxSet {
@@ -278,6 +308,22 @@ function runAuthenticationStages<T>(
   validationComplete = false,
 ): ProgramResult<T> {
   if (start >= program.authStages.length) {
+    // Auth-first: the idempotency gate buffers the body, so it waits for every stage to pass. It
+    // resumes on an entry without the gate, so the program does not meet it twice.
+    if (entry.idempotent !== undefined && !validationComplete) {
+      return runIdempotencyGate(host, entry, ctx, finalize, wrapResponse, (e, p) =>
+        runAuthenticationStages(
+          host,
+          e,
+          p,
+          source,
+          ctx,
+          finalize,
+          wrapResponse,
+          p.authStages.length,
+        ),
+      )
+    }
     if (program.authFastLane) {
       const validationIndex = validationComplete ? program.validationStages.length : 0
       return runFastAuthenticatedProgram(
@@ -578,22 +624,33 @@ async function runAuthBeforeValidation<T>(
   ctx: RawContext,
   finalize: (result: unknown, set: CtxSet, ctx?: RawContext) => T,
   wrapResponse: (response: Response | ResponseResult) => T,
+  gated = false,
 ): Promise<T> {
   try {
-    if (program.hasDecorations) Object.assign(ctx, program.decorations)
+    if (!gated) {
+      if (program.hasDecorations) Object.assign(ctx, program.decorations)
 
-    for (const derive of program.derives) {
-      const result = derive(ctx)
-      const settled = result instanceof Promise ? await result : result
-      if (isEarly(settled)) return finishEarly(host, entry, ctx, settled, finalize, wrapResponse)
-      Object.assign(ctx, settled)
-    }
+      for (const derive of program.derives) {
+        const result = derive(ctx)
+        const settled = result instanceof Promise ? await result : result
+        if (isEarly(settled)) return finishEarly(host, entry, ctx, settled, finalize, wrapResponse)
+        Object.assign(ctx, settled)
+      }
 
-    for (const before of program.beforeHandle) {
-      const result = before(ctx)
-      const settled = result instanceof Promise ? await result : result
-      if (settled !== undefined)
-        return finishEarly(host, entry, ctx, settled, finalize, wrapResponse)
+      for (const before of program.beforeHandle) {
+        const result = before(ctx)
+        const settled = result instanceof Promise ? await result : result
+        if (settled !== undefined)
+          return finishEarly(host, entry, ctx, settled, finalize, wrapResponse)
+      }
+
+      // The policy hooks have passed, so the idempotency gate may buffer the body now. Not awaited:
+      // the gate reports its own failures, and one the resumed program let escape must skip this catch.
+      if (entry.idempotent !== undefined) {
+        return runIdempotencyGate(host, entry, ctx, finalize, wrapResponse, (e, p) =>
+          runAuthBeforeValidation(host, e, p, source, ctx, finalize, wrapResponse, true),
+        )
+      }
     }
 
     for (const stage of program.validationStages) {
@@ -634,6 +691,13 @@ export function executeRouteProgram<T, R extends Registry, Ctx>(
   wrapResponse: (response: Response | ResponseResult) => T,
 ): ProgramResult<T> {
   const host = runtime as unknown as RouteProgramRuntime
+  // An auth-first program meets the idempotency gate once authentication has passed, so the gate
+  // never buffers a body for a caller it would refuse. Every other program meets it first.
+  if (entry.idempotent !== undefined && !program.authBeforeValidation) {
+    return runIdempotencyGate(host, entry, ctx, finalize, wrapResponse, (e, p) =>
+      executeRouteProgram(runtime, e, p, source, ctx, finalize, wrapResponse),
+    )
+  }
   try {
     if (program.authStages.length > 0) {
       if (program.hasDecorations) Object.assign(ctx, program.decorations)

package/src/range.ts

@@ -32,6 +32,63 @@ function validSize(size: number): void {
   }
 }
 
+/**
+ * `bytes=<digits>-<digits>`, the one form clients send, answered with a single scan; `undefined`
+ * for anything else, which the general path below answers. The answers must stay the general path's:
+ * test/range.test.ts compares both against a frozen copy of it.
+ */
+function parseSingleRange(value: string, size: number): ByteRangeResult | undefined {
+  const length = value.length
+  // `| 0x20` folds only ASCII case, which is all the general path's /bytes/i matches.
+  if (
+    length < 7 ||
+    value.charCodeAt(5) !== 0x3d ||
+    (value.charCodeAt(0) | 0x20) !== 0x62 ||
+    (value.charCodeAt(1) | 0x20) !== 0x79 ||
+    (value.charCodeAt(2) | 0x20) !== 0x74 ||
+    (value.charCodeAt(3) | 0x20) !== 0x65 ||
+    (value.charCodeAt(4) | 0x20) !== 0x73
+  ) {
+    return undefined
+  }
+  let dash = -1
+  for (let index = 6; index < length; index++) {
+    const code = value.charCodeAt(index)
+    if (code === 0x2d) {
+      if (dash !== -1) return undefined
+      dash = index
+    } else if (code < 0x30 || code > 0x39) {
+      return undefined
+    }
+  }
+  if (dash === -1) return undefined
+  const leftDigits = dash - 6
+  const rightDigits = length - dash - 1
+  // INTEGER: no leading zero.
+  if (
+    (leftDigits > 1 && value.charCodeAt(6) === 0x30) ||
+    (rightDigits > 1 && value.charCodeAt(dash + 1) === 0x30)
+  ) {
+    return { kind: "none" }
+  }
+  let start: number
+  let end: number
+  if (leftDigits === 0) {
+    // A suffix with no length, or a zero one, is ignored.
+    if (rightDigits === 0 || (rightDigits === 1 && value.charCodeAt(dash + 1) === 0x30)) {
+      return { kind: "none" }
+    }
+    const suffix = Number(value.slice(dash + 1))
+    start = suffix >= size ? 0 : size - suffix
+    end = size - 1
+  } else {
+    start = Number(value.slice(6, dash))
+    end = rightDigits === 0 ? size - 1 : Math.min(Number(value.slice(dash + 1)), size - 1)
+  }
+  if (start > end || start >= size || size === 0) return { kind: "unsatisfiable" }
+  return { kind: "satisfiable", ranges: [{ start, end }] }
+}
+
 /**
  * Parse an HTTP `Range: bytes=...` header against a known representation size.
  *
@@ -45,12 +102,14 @@ export function parseByteRange(value: string | null, size: number): ByteRangeRes
   // Bound the input before the regex runs, not after: an oversized header must never reach the
   // matcher in the first place.
   if (value.length > MAX_RANGE_HEADER_LENGTH) return { kind: "none" }
+  const single = parseSingleRange(value, size)
+  if (single !== undefined) return single
   const match = /^bytes\s*=\s*(.+)$/i.exec(value)
   if (match === null) return { kind: "none" }
   const source = match[1]!
   let separators = 0
-  for (const character of source) {
-    if (character === "," && ++separators >= MAX_RANGE_SPECIFIERS) return { kind: "none" }
+  for (let comma = source.indexOf(","); comma !== -1; comma = source.indexOf(",", comma + 1)) {
+    if (++separators >= MAX_RANGE_SPECIFIERS) return { kind: "none" }
   }
 
   const ranges: ByteRange[] = []

package/src/router/router.ts

@@ -10,8 +10,18 @@ import {
   mixedSegmentShape,
 } from "./pattern.ts"
 
-/** The standard HTTP methods: the ones with a builder on the server and a call on the typed client. */
-export const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"] as const
+/** The standard HTTP methods: the ones the typed registry and the typed client know. Each has a server
+ * builder except `QUERY` (RFC 9110's safe, idempotent read with a body), which `method()` registers. */
+export const METHODS = [
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "HEAD",
+  "OPTIONS",
+  "QUERY",
+] as const
 
 export type Method = (typeof METHODS)[number]
 
@@ -37,6 +47,8 @@ export function isRegistrableMethod(method: string): boolean {
 const SLASH = 47
 export const EMPTY_PARAMS: Record<string, string> = Object.freeze({})
 const DYNAMIC_MATCH_CACHE_MAX = 2048
+// The client picks every key, so their length is bounded too: 2048 paths of 8 KiB held 16 MiB.
+const DYNAMIC_MATCH_CACHE_CHARS = 256 * 1024
 
 /**
  * Result of {@link Router.find}. The `found: false` cases deliberately separate
@@ -67,6 +79,8 @@ interface DynamicMatchCacheEntry<T> {
 
 interface DynamicMatchCacheState<T> {
   cache: Map<string, DynamicMatchCacheEntry<T>> | undefined
+  /** Total length of the cached paths. */
+  chars: number
   pendingPath: string | undefined
 }
 
@@ -79,6 +93,7 @@ function dynamicMatchCacheStateFor<T>(owner: object): DynamicMatchCacheState<T>
   }
   const state: DynamicMatchCacheState<T> = {
     cache: undefined,
+    chars: 0,
     pendingPath: undefined,
   }
   DYNAMIC_MATCH_CACHES.set(owner, state as DynamicMatchCacheState<unknown>)
@@ -476,13 +491,19 @@ export class Router<T> {
       cache = new Map<string, DynamicMatchCacheEntry<T>>()
       state.cache = cache
     }
-    if (cache.size >= DYNAMIC_MATCH_CACHE_MAX) {
-      const oldest = cache.keys().next().value
-      if (oldest !== undefined) cache.delete(oldest)
+    for (const oldest of cache.keys()) {
+      if (
+        cache.size < DYNAMIC_MATCH_CACHE_MAX &&
+        state.chars + path.length <= DYNAMIC_MATCH_CACHE_CHARS
+      )
+        break
+      cache.delete(oldest)
+      state.chars -= oldest.length
     }
     cache.set(path, {
       terminal,
       values: values.slice(0, terminal.paramNames.length),
     })
+    state.chars += path.length
   }
 }

package/src/security/baseline.ts

@@ -41,9 +41,10 @@ export interface SecurityBaselineOptions {
   readonly requireRuntimeProvenance?: boolean
 }
 
-/** A mutation is every method these leave out: POST, PUT, PATCH, DELETE and any custom method. */
-const NOT_MUTATING: readonly (Method | "WS")[] = ["GET", "HEAD", "OPTIONS", "WS"]
-const READING = ["GET", "HEAD"] as const
+/** A mutation is every method these leave out: POST, PUT, PATCH, DELETE and any custom method. QUERY
+ * reads, with a body that the generic body rule still bounds. */
+const NOT_MUTATING: readonly (Method | "WS")[] = ["GET", "HEAD", "OPTIONS", "QUERY", "WS"]
+const READING = ["GET", "HEAD", "QUERY"] as const
 /** The classification threshold above which the baseline demands authentication. */
 const SENSITIVE = "pii" as const
 

package/src/server/body-lane.ts

@@ -11,8 +11,7 @@ import { isJsonMediaType, isUrlEncodedForm, readBoundedForm } from "./query.ts"
 import {
   headerOf,
   isResponseResult,
-  PRE_DECODED_BODY,
-  type PreDecodedBody,
+  preDecodedBody,
   type ResponseResult,
   TEXT_DECODER,
 } from "./runtime-core.ts"
@@ -52,7 +51,7 @@ export function readBoundedJsonSource<T>(
   onResult?: JsonResultContinuation<T>,
   onError?: JsonErrorContinuation<T>,
 ): Promise<unknown | ResponseResult | T> {
-  const preDecoded = (req as { [PRE_DECODED_BODY]?: PreDecodedBody })[PRE_DECODED_BODY]
+  const preDecoded = preDecodedBody(req)
   if (preDecoded !== undefined) {
     const value =
       preDecoded.byteLength > maxBytes ? plainError(413, "payload_too_large") : preDecoded.value
@@ -237,7 +236,8 @@ export function readBodyFramed<T>(
   formOrigins?: FormOrigins,
 ): Promise<T> {
   const contentType = headerOf(source, "content-type") ?? ""
-  if (!isJsonMediaType(contentType)) {
+  // A body a transport codec decoded keeps its media type; the JSON lane below takes its value.
+  if (!isJsonMediaType(contentType) && preDecodedBody(source) === undefined) {
     // JSON needs a preflight, so CORS judges it; a form body reaches here from any site with cookies.
     if (isFormMediaType(contentType) && !formOriginAllowed(source, formOrigins)) {
       return Promise.resolve(wrapResponse(plainError(403, "forbidden_origin")))

package/src/server/body.ts

@@ -462,6 +462,12 @@ export function markTransportCap(source: object, maxBytes: number): void {
   ;(source as { [TRANSPORT_CAP]?: number })[TRANSPORT_CAP] = maxBytes
 }
 
+/** The cap {@link markTransportCap} set on `source`, for a copy that must keep it. */
+export function transportCapOf(source: object): number | undefined {
+  const cap: unknown = Reflect.get(source, TRANSPORT_CAP)
+  return typeof cap === "number" ? cap : undefined
+}
+
 /**
  * Enforce a marked source's transport byte cap on **direct user reads** of its request
  * (`c.req.json()`, `c.req.arrayBuffer()`, the raw `body` stream, `clone()`, ...), without swapping

package/src/server/cookies.ts

@@ -78,6 +78,9 @@ export function parseCookies(header: string | null | undefined): Record<string,
   if (!header) return out
   const len = header.length
   let pos = 0
+  // The first "=" at or after the segment, kept while it lies in a later one, so a run of bare
+  // segments does not rescan the rest of the header each time. -1: none left.
+  let eq = header.indexOf("=")
   while (pos < len) {
     let end = header.indexOf(";", pos)
     if (end === -1) end = len
@@ -86,7 +89,7 @@ export function parseCookies(header: string | null | undefined): Record<string,
     while (start < end && header.charCodeAt(start) === 32) start++
     let stop = end
     while (stop > start && header.charCodeAt(stop - 1) === 32) stop--
-    const eq = header.indexOf("=", start)
+    if (eq !== -1 && eq < start) eq = header.indexOf("=", start)
     if (eq > start && eq < stop) {
       // name: trim trailing spaces before '='; value: trim leading spaces after it
       let nameEnd = eq
@@ -125,6 +128,8 @@ export function hasDuplicateCookie(header: string | null | undefined, targetName
   let found = false
   const len = header.length
   let pos = 0
+  // Kept across segments as in parseCookies.
+  let eq = header.indexOf("=")
   while (pos < len) {
     let end = header.indexOf(";", pos)
     if (end === -1) end = len
@@ -132,7 +137,7 @@ export function hasDuplicateCookie(header: string | null | undefined, targetName
     while (start < end && header.charCodeAt(start) === 32) start++
     let stop = end
     while (stop > start && header.charCodeAt(stop - 1) === 32) stop--
-    const eq = header.indexOf("=", start)
+    if (eq !== -1 && eq < start) eq = header.indexOf("=", start)
     if (eq > start && eq < stop) {
       let nameEnd = eq
       while (nameEnd > start && header.charCodeAt(nameEnd - 1) === 32) nameEnd--

package/src/server/core-copies.ts

@@ -23,7 +23,7 @@ if (!copies.includes(here) && copies.push(here) > 1) {
 
 /** 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.3.0"
+const COPY_VERSION = "5.5.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. */