@nifrajs/core 4.0.0 → 5.0.0

package/src/server/body.ts

@@ -194,6 +194,37 @@ function transportCapError(status: 400 | 413): Response {
   return jsonError(status, status === 413 ? "payload_too_large" : "invalid_content_length")
 }
 
+/**
+ * A copy of `request` whose body errors with the transport cap's `413` once more than `maxBytes`
+ * arrive, or as soon as it is read when the declared Content-Length is over the cap (`413`) or
+ * malformed (`400`). The compact form of {@link applyTransportCap} for a server that hands the
+ * handler its own `Request` and has no identity to preserve; nothing is read until the handler reads.
+ */
+export function capBodyBytes(request: Request, maxBytes: number): Request {
+  const body = request.body
+  if (body === null) return request
+  const declared = request.headers.get("content-length")
+  const length = declared === null ? 0 : parseContentLength(declared)
+  let total = 0
+  const init: RequestInit & { duplex: "half" } = {
+    body: body.pipeThrough(
+      new TransformStream<Uint8Array, Uint8Array>({
+        start(controller) {
+          if (length === undefined || length > maxBytes)
+            controller.error(transportCapError(length === undefined ? 400 : 413))
+        },
+        transform(chunk, controller) {
+          total += chunk.byteLength
+          if (total > maxBytes) controller.error(transportCapError(413))
+          else controller.enqueue(chunk)
+        },
+      }),
+    ),
+    duplex: "half",
+  }
+  return new Request(request, init)
+}
+
 /** First matching own-or-inherited descriptor, so instance shadows and prototype accessors both resolve. */
 function descriptorOf(target: object, key: string): PropertyDescriptor | undefined {
   let current: object | null = target
@@ -278,7 +309,9 @@ function cappedStreamOf(
         }
         total += value.byteLength
         if (total > maxBytes) {
-          await active.cancel().catch(() => {})
+          // 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))
           return
         }

package/src/server/client-ip.ts

@@ -22,6 +22,9 @@
  * - `{ header: name }` - trust a single named header's first value (e.g. a CDN that overwrites it at
  *   the edge). Only declare this when the app is reachable **exclusively** through that edge; a
  *   directly-reachable app lets any client forge the header.
+ *
+ * A hop count that is not a non-negative integer throws when the server is created; an invalid
+ * header name fails on the first request that reads `c.clientIp`.
  */
 export type ClientIpTrust = { readonly trustedHops: number } | { readonly header: string }
 

package/src/server/context.ts

@@ -31,7 +31,8 @@ export interface IdempotencyConfig {
    * Required server-owned key namespace. Use a tenant/subject-scoped opaque token for authenticated
    * routes so two principals choosing the same header key never collide. A static namespace is an
    * explicit shared/public scope and is safe only when the response is principal-independent. The
-   * resolver receives a clone and must not derive identity from unauthenticated client input.
+   * resolver receives the request's method, URL and headers, never its body, and must not derive
+   * identity from unauthenticated client input.
    */
   readonly namespace:
     | string

package/src/server/idempotency-lane.ts

@@ -4,8 +4,9 @@
  * `server()` tree-shakes the whole dedupe machinery out.
  *
  * The kernel resolves a route's declared idempotency at registration (via {@link IdempotencyRuntime.resolve})
- * and, on the request path, hands a matched idempotent route to {@link IdempotencyRuntime.run}. Everything
- * server-specific is supplied through {@link IdempotencyHost} so this module depends on no server internals.
+ * and, on the request path, hands a matched idempotent route to {@link IdempotencyRuntime.run}. Server
+ * execution is supplied through {@link IdempotencyHost}; the opt-in module adapts the matched
+ * route's program for replay without adding replay preparation to the shared server kernel.
  */
 import { RouteConfigError } from "../errors.ts"
 import {
@@ -28,6 +29,11 @@ import {
   requestEffectEvidence,
   requestIsSafeToRetry,
 } from "../internal/effect-execution.ts"
+import {
+  compileRouteExecutionPlan,
+  type InternalHandler,
+  type RouteEntry,
+} from "../internal/route-execution.ts"
 import { readBoundedBytes } from "./body.ts"
 import type { Platform, RouteSchema } from "./context.ts"
 import { jsonError, urlPartsOf } from "./http.ts"
@@ -42,6 +48,17 @@ const HANDLER_ENTERED = new WeakSet<Request>()
  * owned effect begun, releases its key, so a refused caller cannot hold a store entry for the TTL. */
 const REFUSALS = new Set([401, 403, 408, 409, 425, 429])
 
+// Compile once in the opt-in plugin. The around runner also handles an empty hook list.
+const REPLAY_EXECUTION = compileRouteExecutionPlan({
+  lane: "lifecycle",
+  contextless: false,
+  hasAround: true,
+  hasLedger: false,
+  fusedWeb: undefined,
+  fusedBody: undefined,
+  fusedLane: undefined,
+})
+
 /** Registration-resolved idempotency for a route: the config with its store + defaults pinned. */
 export interface ResolvedIdempotency {
   readonly store: IdempotencyStore
@@ -55,7 +72,8 @@ export interface ResolvedIdempotency {
 
 /**
  * What the dedupe lane needs from the server to run a fresh key: the app-wide body cap and a way to
- * run the buffered request through the route's normal lanes to a concrete `Response`.
+ * run the buffered request through the route's normal lanes to a concrete `Response`. The replay
+ * path supplies an entry with the stored response replacing the handler and stored transformations.
  */
 export interface IdempotencyHost {
   readonly maxBodyBytes: number
@@ -65,7 +83,7 @@ export interface IdempotencyHost {
     entry: unknown,
     params: Record<string, string>,
     search: string | undefined,
-  ): Promise<Response>
+  ): Response | Promise<Response>
 }
 
 /** The injected idempotency implementation the kernel calls through when the plugin is installed. */
@@ -101,7 +119,9 @@ interface IdempotencyInstallable {
 
 /**
  * Enable request idempotency. Routes that declare `schema.idempotency` get the dedupe lane: a repeat
- * `Idempotency-Key` replays the stored response instead of re-running the handler. Without this plugin,
+ * `Idempotency-Key` rechecks the current route prerequisites (authentication, validation and policy
+ * hooks) before replaying the stored response. The handler, effect ledger and stored response
+ * transformations run only for the fresh request. Without this plugin,
  * declaring `schema.idempotency` is a registration error (the safety gate can never be silently
  * dropped). `store` is the app-wide default backing routes that do not pin their own; omit it for a
  * shared in-process store (development/tests only - inject a durable store in production).
@@ -231,7 +251,10 @@ export function createIdempotencyRuntime(options?: IdempotencyPluginOptions): Id
       }
       const namespace =
         typeof config.namespace === "function"
-          ? await config.namespace(req.clone(), platform)
+          ? await config.namespace(
+              { method: req.method, url: req.url, headers: req.headers },
+              platform,
+            )
           : config.namespace
       if (!validIdempotencyNamespace(namespace)) {
         return wrapResponse(jsonError(500, "idempotency_namespace_invalid"))
@@ -250,6 +273,13 @@ export function createIdempotencyRuntime(options?: IdempotencyPluginOptions): Id
         canonicalBody,
         req.headers.get("content-type") ?? "",
       )
+      const buffered = new Request(req.url, {
+        method: req.method,
+        headers: req.headers,
+        signal: req.signal,
+        // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: readBoundedBytes owns this byte view; Request accepts the same bytes on every supported runtime.
+        body: read.bytes.byteLength ? (read.bytes as NonNullable<RequestInit["body"]>) : null,
+      })
 
       const pendingTtlMs = config.pendingTtlMs
       const begin = await config.store.begin({
@@ -259,11 +289,6 @@ export function createIdempotencyRuntime(options?: IdempotencyPluginOptions): Id
         ttlMs: config.ttlMs,
         pendingTtlMs,
       })
-      if (begin.state === "replay") {
-        return wrapResponse(
-          responseFromStored(begin.response, { maxBytes: config.maxResponseBytes }),
-        )
-      }
       if (begin.state === "mismatch") return wrapResponse(jsonError(409, "idempotency_key_reused"))
       if (begin.state === "in-flight") {
         return wrapResponse(jsonError(409, "idempotency_in_progress", { "Retry-After": "1" }))
@@ -271,6 +296,21 @@ export function createIdempotencyRuntime(options?: IdempotencyPluginOptions): Id
       if (begin.state === "capacity") {
         return wrapResponse(jsonError(503, "idempotency_store_capacity", { "Retry-After": "1" }))
       }
+      beginRequestEffectTracking(buffered)
+      if (begin.state === "replay") {
+        return wrapResponse(
+          await host.runLanes(
+            buffered,
+            platform,
+            replayEntry(
+              entry,
+              responseFromStored(begin.response, { maxBytes: config.maxResponseBytes }),
+            ),
+            params,
+            search,
+          ),
+        )
+      }
       const reservation = begin.reservation
       let heartbeat: ReturnType<typeof setInterval> | undefined
       if (pendingTtlMs !== undefined) {
@@ -286,17 +326,6 @@ export function createIdempotencyRuntime(options?: IdempotencyPluginOptions): Id
         ;(heartbeat as { unref?: () => void }).unref?.()
       }
       try {
-        // Fresh key: re-expose the buffered body as a Request so the normal lanes can read + validate it,
-        // then run those lanes to a concrete Response.
-        const bufferedInit: RequestInit = {
-          method: req.method,
-          headers: req.headers,
-          signal: req.signal,
-        }
-        if (read.bytes.byteLength > 0)
-          bufferedInit.body = read.bytes as NonNullable<RequestInit["body"]>
-        const buffered = new Request(req.url, bufferedInit)
-        beginRequestEffectTracking(buffered)
         // The handler threw, or its response body failed while being captured: no response to store.
         const settleThrown = async (err: unknown): Promise<ReturnType<typeof wrapResponse>> => {
           if (!requestEffectEvidence(buffered).began) {
@@ -394,3 +423,16 @@ export function createIdempotencyRuntime(options?: IdempotencyPluginOptions): Id
     },
   }
 }
+
+function replayEntry(entry: unknown, response: Response): RouteEntry {
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the kernel supplies its matched RouteEntry through this internal opaque install seam.
+  const route = entry as RouteEntry
+  const handler: InternalHandler = () => response
+  return {
+    ...route,
+    handler,
+    responseContract: undefined,
+    program: { ...route.program, handler, afterHandle: [] },
+    execution: REPLAY_EXECUTION,
+  }
+}

package/src/server/install.ts

@@ -25,6 +25,9 @@ export const INSTALL_SSE: unique symbol = Symbol.for("@nifrajs/core/install-sse"
 /** @internal Install the Node-direct renderer on a server (called by the `nodeDirect()` plugin). */
 export const INSTALL_NODE_DIRECT: unique symbol = Symbol.for("@nifrajs/core/install-node-direct")
 
+/** @internal Log an error an adapter caught past `fetch`, through the app's own logger. */
+export const REPORT_ERROR: unique symbol = Symbol.for("@nifrajs/core/report-error")
+
 /** @internal Install the not-found lane on a server (called by the `notFound()` plugin). */
 export const INSTALL_NOT_FOUND: unique symbol = Symbol.for("@nifrajs/core/install-not-found")
 

package/src/server/logger.ts

@@ -57,7 +57,9 @@ export interface RedactOptions {
 export const commonSecretPatterns: ReadonlyArray<RegExp> = [
   /Bearer\s+[A-Za-z0-9._~+/-]+=*/gi, // Authorization: Bearer <token>
   /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, // JWT (header.payload.signature)
-  /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g, // email
+  // Email. The lookbehind starts a match only where a run of address characters starts; `\b` would
+  // restart inside `a.a.a.` at every `a` and rescan the run each time, quadratic in its length.
+  /(?<![A-Za-z0-9._%+-])[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
   /\b[sprk]k_(?:live|test)_[A-Za-z0-9]{8,}/g, // Stripe-style secret/restricted keys
   /\bgh[pousr]_[A-Za-z0-9]{20,}/g, // GitHub personal/OAuth/refresh tokens
   /\bAKIA[0-9A-Z]{16}\b/g, // AWS access key id

package/src/server/methods.ts

@@ -9,6 +9,7 @@ import type { MethodRoutesPlugin } from "./plugin.ts"
 import type { OutputOf } from "./registry.ts"
 import type { Handler } from "./server.ts"
 
+export { isRegistrableMethod } from "../router/router.ts"
 export type { MethodRoutesPlugin } from "./plugin.ts"
 
 /** The part of a server these plugins use: one atomic batch registration. */

package/src/server/node-outcome.ts

@@ -4,11 +4,13 @@
  * plain-data render straight to the socket. Imports only runtime-core + respond + the spine types.
  */
 import {
-  appendCookiesToResponse,
+  applySetToResponse,
   applyStaticResponseHeaders,
   markTaggedResponse,
   normalizeBodylessResponse,
-  rememberMutableHeaders,
+  RESPONSE_OWNED_HEADERS,
+  rememberRenderedResponse,
+  SENT_BODY,
   taggedResponseBody,
 } from "./respond.ts"
 import {
@@ -72,16 +74,17 @@ export function toNodeOutcome(result: HandlerResult, set: CtxSet): NodeServeOutc
       return {
         kind: "body",
         status: body.status,
-        headers: appendCookiesToNodeHeaders(body.headers, set._cookies),
+        headers: applySetToNodeHeaders(body.headers, body.status, set),
         body: isBodylessStatus(body.status) ? new Uint8Array(0) : body.body,
       }
     }
     return nodeOutcomeFromResponse(
-      appendCookiesToResponse(normalizeBodylessResponse(result.toResponse()), set),
+      applySetToResponse(normalizeBodylessResponse(result.toResponse()), set),
     )
   }
   if (result instanceof Response) {
-    return nodeOutcomeFromResponse(appendCookiesToResponse(normalizeBodylessResponse(result), set))
+    if (result.bodyUsed) return plainNodeOutcome(SENT_BODY.plain!, EMPTY_RESPONSE_CONTROLS)
+    return nodeOutcomeFromResponse(applySetToResponse(normalizeBodylessResponse(result), set))
   }
   const status = set.status ?? (result === undefined ? 204 : 200)
   const body = result === undefined || isBodylessStatus(status) ? null : JSON.stringify(result)
@@ -152,8 +155,7 @@ export function nodeOutcomeToResponse(outcome: NodeServeOutcome): Response {
     headers,
   })
   if (body !== null) markTaggedResponse(response, body)
-  rememberMutableHeaders(response.headers)
-  return response
+  return rememberRenderedResponse(response, body !== null)
 }
 
 /**
@@ -232,13 +234,33 @@ function responseHeadersForNode(
   return headers
 }
 
-function appendCookiesToNodeHeaders(
+/** {@link applySetToResponse} for a body the node lane writes from a header record. */
+function applySetToNodeHeaders(
   headers: Readonly<Record<string, string | readonly string[]>> | undefined,
-  cookies: readonly string[] | undefined,
+  status: number,
+  set: CtxSet,
 ): Readonly<Record<string, string | readonly string[]>> | undefined {
-  if (cookies === undefined || cookies.length === 0) return headers
-  const out = Object.create(null) as Record<string, string | readonly string[]>
-  if (headers !== undefined) Object.assign(out, headers)
+  const ambient = status >= 200 ? set._headers : undefined
+  const cookies = set._cookies
+  const copy = (): Record<string, string | readonly string[]> =>
+    Object.assign(Object.create(null) as Record<string, string | readonly string[]>, headers)
+  let out: Record<string, string | readonly string[]> | undefined
+  if (ambient !== undefined) {
+    let own: Set<string> | undefined
+    for (const name in ambient) {
+      const lower = name.toLowerCase()
+      if (RESPONSE_OWNED_HEADERS.has(lower)) continue
+      own ??= new Set(
+        headers === undefined ? [] : Object.keys(headers).map((key) => key.toLowerCase()),
+      )
+      if (own.has(lower)) continue
+      own.add(lower)
+      out ??= copy()
+      out[name] = ambient[name]!
+    }
+  }
+  if (cookies === undefined || cookies.length === 0) return out ?? headers
+  out ??= copy()
   const existing = out["set-cookie"]
   const setCookies =
     existing === undefined ? [] : typeof existing === "string" ? [existing] : [...existing]

package/src/server/platform-adapters.ts

@@ -67,8 +67,9 @@ function absoluteUrl(
       // Fall through to the structured event fields.
     }
   }
-  const host = headers.get("host") ?? "nifra.invalid"
-  const url = new URL(path || "/", `https://${host}`)
+  const url = new URL(`https://${headers.get("host") ?? "nifra.invalid"}`)
+  // Assigned, not resolved against the origin: resolving reads `//evil.example/admin` as a host.
+  url.pathname = path || "/"
   if (query !== undefined && query !== "") url.search = query.startsWith("?") ? query : `?${query}`
   return url.toString()
 }

package/src/server/request-context.ts

@@ -15,6 +15,7 @@ import type { ProtoPoisoning } from "./proto-guard.ts"
 import { searchOf } from "./query.ts"
 import { responseJsonContentType } from "./respond.ts"
 import {
+  CONTEXT_REQUEST,
   CONTEXT_SEARCH,
   CONTEXT_SET,
   fallbackWaitUntil,
@@ -256,6 +257,10 @@ export class RequestContext implements RawContext {
     return this.setValue
   }
 
+  get [CONTEXT_REQUEST](): Request {
+    return requestOf(this.source)
+  }
+
   get [CONTEXT_SEARCH](): string {
     this.searchValue ??= searchOf(this.source.url)
     return this.searchValue