@nifrajs/middleware 2.8.2 → 2.9.0

package/src/powered-by.ts

@@ -1,5 +1,4 @@
 import type { Middleware } from "@nifrajs/core/server"
-import { withHeaders } from "./_utils.ts"
 
 export interface PoweredByOptions {
   /** Header name. Default `"x-powered-by"`. */
@@ -21,11 +20,16 @@ export function poweredBy(options: PoweredByOptions = {}): Middleware {
   if (header.trim() === "") throw new Error("poweredBy: header is empty")
   if (/[\r\n]/.test(value)) throw new Error("poweredBy: value contains a newline")
 
+  // Respecting an existing value IS the static tier's contract (declared headers are defaults), so
+  // the default configuration declares the header instead of writing it per response and leaves the
+  // app on its fused/native lanes. Overwriting is a decision about the response, so it stays a hook.
+  if (respectExisting) {
+    return { name: "powered-by", responseHeaders: { [header]: value } }
+  }
   return {
     name: "powered-by",
-    onResponse(res) {
-      if (respectExisting && res.headers.has(header)) return res
-      return withHeaders(res, (headers) => headers.set(header, value))
+    onResponseHeaders(headers) {
+      headers.set(header, value)
     },
   }
 }

package/src/pretty-json.ts

@@ -1,4 +1,4 @@
-import { definePlugin } from "@nifrajs/core/server"
+import { definePlugin, type NodeRequestContext } from "@nifrajs/core/server"
 
 export interface PrettyJsonOptions {
   /** JSON indentation spaces. Default `2`. */
@@ -9,8 +9,10 @@ export interface PrettyJsonOptions {
   readonly newline?: boolean
   /** Optional query toggle. When set, pretty printing runs only when the parameter is present. */
   readonly query?: string | false
-  /** Only pretty-print matching requests. Default `true`. */
-  readonly enabled?: boolean | ((request: Request) => boolean)
+  /** Only pretty-print matching requests (the predicate receives the portable request view -
+   * `{ method, url, header(name) }` - so the check runs without materializing a `Request`).
+   * Default `true`. */
+  readonly enabled?: boolean | ((request: NodeRequestContext) => boolean)
 }
 
 const JSON_TYPE = /^(?:application\/json|[^/]+\/[^;]+\+json)(?:\s*;|$)/i
@@ -19,25 +21,21 @@ function isJson(contentType: string): boolean {
   return JSON_TYPE.test(contentType)
 }
 
-function parseLength(value: string | null): number | undefined {
-  if (value === null) return undefined
-  if (!/^(?:0|[1-9]\d*)$/.test(value)) return undefined
-  return Number(value)
-}
-
-/**
- * The two reader methods this file uses, structurally.
- *
- * Named by use rather than imported: `lib.dom`'s `ReadableStreamDefaultReader` and Bun's augmented one
- * are not mutually assignable (Bun adds `readMany`), and `ReturnType<…getReader>` resolves to the BYOB
- * overload, whose `read` requires an argument. A structural shape sidesteps all of it without a cast.
- */
 interface ChunkReader {
   read(): Promise<{ readonly done: boolean; readonly value?: Uint8Array }>
   cancel(reason?: unknown): Promise<void>
 }
 
-/** Re-emit the bytes already pulled, then the untouched remainder of the same reader. */
+const concat = (chunks: readonly Uint8Array[], total: number): Uint8Array => {
+  const out = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    out.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return out
+}
+
 function replayFrom(res: Response, chunks: readonly Uint8Array[], reader: ChunkReader): Response {
   const stream = new ReadableStream<Uint8Array>({
     start(controller) {
@@ -46,12 +44,9 @@ function replayFrom(res: Response, chunks: readonly Uint8Array[], reader: ChunkR
     async pull(controller) {
       try {
         const { done, value } = await reader.read()
-        // No value and not done cannot happen for a byte stream, but it means the same thing here:
-        // there is nothing further to emit.
         if (done || value === undefined) controller.close()
         else controller.enqueue(value)
       } catch (error) {
-        // The upstream body failed; surface that to the client rather than truncating silently.
         controller.error(error)
       }
     },
@@ -64,37 +59,26 @@ function replayFrom(res: Response, chunks: readonly Uint8Array[], reader: ChunkR
   })
 }
 
-type Peeked = { readonly text: string } | { readonly response: Response }
+type Peeked =
+  | { readonly text: string; readonly bytes: Uint8Array }
+  | { readonly response: Response }
 
-/**
- * Read up to `maxBytes` of a response, without disturbing it when the answer is "pass through".
- *
- * `Response.clone()` is the obvious way to peek and is a trap here. Cancelling the clone's reader once
- * the cap is exceeded also stalls the ORIGINAL body in Bun, so an oversized streamed response hung the
- * client instead of passing through - a hang, from a middleware whose entire job is cosmetic. (A clone
- * read to completion is fine; only the cancel breaks it, which is why every buffered case passed and
- * only a streamed one failed.) Abandoning the clone rather than cancelling it trades the hang for
- * buffering the whole oversized body, which is the exact cost the cap exists to avoid.
- *
- * So the body is read directly and, when it proves too large, replayed: the bytes already pulled are
- * re-emitted ahead of the rest of the same reader. No tee, nothing buffered past the cap, and the
- * response the client receives is byte-for-byte the one the handler produced.
- */
 async function peekText(res: Response, maxBytes: number): Promise<Peeked> {
   const body = res.body
   if (body === null) return { response: res }
-  const reader = body.getReader()
+  const reader = body.getReader() as unknown as ChunkReader
   const chunks: Uint8Array[] = []
   let total = 0
   try {
     while (true) {
       const { done, value } = await reader.read()
       if (done) {
-        const decoder = new TextDecoder()
+        const decoder = new TextDecoder("utf-8", { fatal: true })
         let text = ""
         for (const chunk of chunks) text += decoder.decode(chunk, { stream: true })
-        return { text: text + decoder.decode() }
+        return { text: text + decoder.decode(), bytes: concat(chunks, total) }
       }
+      if (value === undefined) return { response: replayFrom(res, chunks, reader) }
       chunks.push(value)
       total += value.byteLength
       if (total > maxBytes) return { response: replayFrom(res, chunks, reader) }
@@ -104,6 +88,10 @@ async function peekText(res: Response, maxBytes: number): Promise<Peeked> {
   }
 }
 
+function requestView(request: Request): NodeRequestContext {
+  return { method: request.method, url: request.url, header: (name) => request.headers.get(name) }
+}
+
 /**
  * Pretty-print JSON responses for debugging and developer-facing APIs. It only touches JSON content,
  * skips encoded responses, caps inspection size, and leaves invalid JSON untouched.
@@ -114,8 +102,8 @@ export function prettyJson(options: PrettyJsonOptions = {}) {
     throw new Error("prettyJson: spaces must be an integer from 0 to 10")
   }
   const maxBytes = options.maxBytes ?? 1_000_000
-  if (!Number.isInteger(maxBytes) || maxBytes < 0) {
-    throw new Error("prettyJson: maxBytes must be a non-negative integer")
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
+    throw new Error("prettyJson: maxBytes must be a non-negative safe integer")
   }
   const newline = options.newline !== false
   const query = options.query ?? false
@@ -123,37 +111,74 @@ export function prettyJson(options: PrettyJsonOptions = {}) {
   const enabled = options.enabled ?? true
   const isEnabled = typeof enabled === "function" ? enabled : enabled ? () => true : () => false
 
+  const decoder = new TextDecoder()
+  const encoder = new TextEncoder()
   return definePlugin("prettyJson", (app) =>
-    app.onResponse(async (res, req) => {
-      if (!isEnabled(req)) return res
-      if (query !== false && !new URL(req.url).searchParams.has(query)) return res
-      if (res.body === null || res.headers.has("content-encoding")) return res
-      if (!isJson(res.headers.get("content-type") ?? "")) return res
-      const declared = parseLength(res.headers.get("content-length"))
-      if (declared !== undefined && declared > maxBytes) return res
-
-      const peeked = await peekText(res, maxBytes)
-      if ("response" in peeked) return peeked.response
-      let parsed: unknown
-      try {
-        parsed = JSON.parse(peeked.text)
-      } catch {
-        // The body was read to decide that, so `res` can no longer be returned as-is. Rebuild it from
-        // the text: re-encoding UTF-8 reproduces the original bytes, so `content-length` still holds.
-        return new Response(peeked.text, {
-          status: res.status,
-          statusText: res.statusText,
-          headers: res.headers,
-        })
-      }
-
-      const headers = new Headers(res.headers)
-      headers.delete("content-length")
-      return new Response(`${JSON.stringify(parsed, null, spaces)}${newline ? "\n" : ""}`, {
-        status: res.status,
-        statusText: res.statusText,
-        headers,
-      })
+    app.use({
+      onResponseBody(body, headers, req) {
+        if (!isEnabled(req)) return undefined
+        if (query !== false && !new URL(req.url).searchParams.has(query)) return undefined
+        if (headers.has("content-encoding")) return undefined
+        if (!isJson(headers.get("content-type") ?? "")) return undefined
+        const text = typeof body === "string" ? body : decoder.decode(body)
+        if (
+          (typeof body === "string" ? encoder.encode(body).byteLength : body.byteLength) > maxBytes
+        ) {
+          return undefined
+        }
+        let parsed: unknown
+        try {
+          parsed = JSON.parse(text)
+        } catch {
+          return undefined
+        }
+        return `${JSON.stringify(parsed, null, spaces)}${newline ? "\n" : ""}`
+      },
+      onResponseRaw(response, req) {
+        if (!isEnabled(requestView(req))) return response
+        if (query !== false && !new URL(req.url).searchParams.has(query)) return response
+        if (
+          response.body === null ||
+          response.status === 204 ||
+          response.status === 205 ||
+          response.status === 304 ||
+          response.headers.has("content-encoding")
+        )
+          return response
+        if (!isJson(response.headers.get("content-type") ?? "")) return response
+        const declared = response.headers.get("content-length")
+        if (declared !== null && /^(?:0|[1-9]\d*)$/.test(declared) && Number(declared) > maxBytes) {
+          return response
+        }
+        return prettyRawResponse(response, maxBytes, spaces, newline)
+      },
     }),
   )
 }
+
+async function prettyRawResponse(
+  response: Response,
+  maxBytes: number,
+  spaces: number,
+  newline: boolean,
+): Promise<Response> {
+  const peeked = await peekText(response, maxBytes)
+  if ("response" in peeked) return peeked.response
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(peeked.text)
+  } catch {
+    return new Response(peeked.bytes, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers,
+    })
+  }
+  const headers = new Headers(response.headers)
+  headers.delete("content-length")
+  return new Response(`${JSON.stringify(parsed, null, spaces)}${newline ? "\n" : ""}`, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  })
+}

package/src/rate-limit.ts

@@ -1,5 +1,6 @@
 import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
-import type { Middleware } from "@nifrajs/core/server"
+import type { Middleware, NodeRequestContext, NodeResponseContext } from "@nifrajs/core/server"
+import { withHeaders, withNodeHeaders } from "./_utils.ts"
 
 export interface RateLimitResult {
   /** Hits recorded in the current window, including this one. */
@@ -184,6 +185,28 @@ function defaultKey(
   return allowGlobalKey ? "global" : null
 }
 
+/** {@link defaultKey} against the allocation-light native request view - same logic, same order. */
+function nativeKey(
+  req: NodeRequestContext,
+  trustedProxies: number,
+  header: string | undefined,
+  allowGlobalKey: boolean,
+): string | null {
+  if (header !== undefined) {
+    const ip = req.header(header)
+    if (ip !== null && ip.trim() !== "") return ip.trim()
+  }
+  if (trustedProxies > 0) {
+    const xff = req.header("x-forwarded-for")
+    if (xff !== null) {
+      const parts = xff.split(",")
+      const ip = parts[parts.length - trustedProxies]?.trim()
+      if (ip !== undefined && ip !== "") return ip
+    }
+  }
+  return allowGlobalKey ? "global" : null
+}
+
 /**
  * Rate limiting as a {@link Middleware}. Runs in `onRequest` (before routing, so it
  * also covers 404s); over the limit → `429` + `Retry-After`. Every response carries
@@ -216,35 +239,78 @@ export function rateLimit(options: RateLimitOptions): Middleware {
   const keyOf =
     options.key ?? ((req: Request) => defaultKey(req, trustedProxies, header, allowGlobalKey))
   const quota = new WeakMap<Request, { remaining: number; resetSeconds: number }>()
+  // State for the Node twins, keyed by the NodeRequestContext identity (the same object is passed
+  // to the request and response twins - the core identity contract that replaces `Request` keying).
+  const nativeQuota = new WeakMap<object, { remaining: number; resetSeconds: number }>()
 
-  const middleware: Middleware = {
-    name: "rate-limit",
-    async onRequest(req) {
-      const key = keyOf(req)
-      if (typeof key !== "string" || key.trim() === "") {
-        return Response.json({ ok: false, error: "rate_limit_key_unavailable" }, { status: 500 })
-      }
-      const { count, resetAt } = await store.hit(key, windowMs)
-      const resetSeconds = Math.max(0, Math.ceil((resetAt - Date.now()) / 1000))
-      quota.set(req, { remaining: Math.max(0, max - count), resetSeconds })
-      if (count > max) {
-        return new Response(JSON.stringify({ ok: false, error: "rate_limited" }), {
+  interface QuotaInfo {
+    readonly remaining: number
+    readonly resetSeconds: number
+  }
+
+  const hitStore = async (
+    key: string | null,
+  ): Promise<{ info: QuotaInfo; reject: Response | undefined } | Response> => {
+    if (typeof key !== "string" || key.trim() === "") {
+      return Response.json({ ok: false, error: "rate_limit_key_unavailable" }, { status: 500 })
+    }
+    const { count, resetAt } = await store.hit(key, windowMs)
+    const resetSeconds = Math.max(0, Math.ceil((resetAt - Date.now()) / 1000))
+    const info = { remaining: Math.max(0, max - count), resetSeconds }
+    if (count > max) {
+      return {
+        info,
+        reject: new Response(JSON.stringify({ ok: false, error: "rate_limited" }), {
           status: 429,
           headers: { "content-type": "application/json", "retry-after": String(resetSeconds) },
-        })
+        }),
       }
-      return undefined
+    }
+    return { info, reject: undefined }
+  }
+
+  const middleware: Middleware = {
+    name: "rate-limit",
+    async onRequest(req) {
+      const outcome = await hitStore(keyOf(req))
+      if (outcome instanceof Response) return outcome
+      quota.set(req, outcome.info)
+      return outcome.reject
     },
     onResponse(res, req) {
       const info = quota.get(req)
       if (info === undefined) return res
       quota.delete(req)
-      const headers = new Headers(res.headers)
-      headers.set("RateLimit-Limit", String(max))
-      headers.set("RateLimit-Remaining", String(info.remaining))
-      headers.set("RateLimit-Reset", String(info.resetSeconds))
-      return new Response(res.body, { status: res.status, statusText: res.statusText, headers })
+      return withHeaders(res, (headers) => {
+        headers.set("RateLimit-Limit", String(max))
+        headers.set("RateLimit-Remaining", String(info.remaining))
+        headers.set("RateLimit-Reset", String(info.resetSeconds))
+      })
     },
+    // Node twins exist only for the built-in header/XFF key derivation - a custom `key` callback
+    // takes a real `Request`, which is exactly the object the native lane avoids building.
+    ...(options.key === undefined
+      ? {
+          onNodeRequest: async (req: NodeRequestContext) => {
+            const outcome = await hitStore(nativeKey(req, trustedProxies, header, allowGlobalKey))
+            if (outcome instanceof Response) return outcome
+            nativeQuota.set(req, outcome.info)
+            return outcome.reject
+          },
+          onNodeResponse: (res: NodeResponseContext, req: NodeRequestContext) => {
+            const info = nativeQuota.get(req)
+            if (info === undefined) return
+            nativeQuota.delete(req)
+            withNodeHeaders(res, (headers) => {
+              // Lowercase on purpose: the Web path's `Headers` lowercases names on the wire, so
+              // this is byte-identical output.
+              headers["ratelimit-limit"] = String(max)
+              headers["ratelimit-remaining"] = String(info.remaining)
+              headers["ratelimit-reset"] = String(info.resetSeconds)
+            })
+          },
+        }
+      : {}),
   }
   return withRouteAssurance(middleware, {
     id: NIFRA_ASSURANCE.RATE_LIMITED,

package/src/request-id.ts

@@ -22,7 +22,7 @@ export function requestId(options: RequestIdOptions = {}) {
   const generate = options.generate ?? (() => crypto.randomUUID())
   return definePlugin("requestId", (app) =>
     app.derive((c) => {
-      const id = c.req.headers.get(header) ?? generate()
+      const id = c.header(header) ?? generate()
       c.set.headers[header] = id // echo on the response (route handlers)
       return { requestId: id }
     }),

package/src/security-headers.ts

@@ -1,6 +1,5 @@
 import { NIFRA_ASSURANCE, withRouteAssurance } from "@nifrajs/core/assurance"
 import type { Middleware } from "@nifrajs/core/server"
-import { withHeaders } from "./_utils.ts"
 
 export interface SecurityHeadersOptions {
   /** `Strict-Transport-Security`. Off by default - opt in once you're sure you're HTTPS-only. */
@@ -18,10 +17,14 @@ export interface SecurityHeadersOptions {
 }
 
 /**
- * A safe-by-default set of response security headers (`onResponse`, so they cover
- * errors and 404s too): `X-Content-Type-Options: nosniff`, `X-Frame-Options`, and
- * `Referrer-Policy` always; `Strict-Transport-Security` and `Content-Security-Policy`
- * only when configured (both are environment-/app-specific).
+ * A safe-by-default set of response security headers, covering errors and 404s too:
+ * `X-Content-Type-Options: nosniff`, `X-Frame-Options`, and `Referrer-Policy` always;
+ * `Strict-Transport-Security` and `Content-Security-Policy` only when configured (both are
+ * environment-/app-specific).
+ *
+ * Every value is fixed at construction, so these are declared statically rather than written by a
+ * response hook: an app whose response middleware is only this keeps the fused native lanes. A route
+ * that sets one of these names itself keeps its own value.
  */
 export function securityHeaders(options: SecurityHeadersOptions = {}): Middleware {
   const frameOptions = options.frameOptions ?? "DENY"
@@ -36,19 +39,18 @@ export function securityHeaders(options: SecurityHeadersOptions = {}): Middlewar
     hstsValue = parts.join("; ")
   }
 
+  const declared: Record<string, string> = {
+    "x-content-type-options": "nosniff",
+    "x-frame-options": frameOptions,
+    "referrer-policy": referrerPolicy,
+  }
+  if (hstsValue !== undefined) declared["strict-transport-security"] = hstsValue
+  if (csp !== undefined) declared["content-security-policy"] = csp
+
   return withRouteAssurance<Middleware>(
     {
       name: "security-headers",
-      // Mutate in place on the common (mutable-headers) response; clone only for an immutable one
-      // (see withHeaders - the old always-clone was ~3% of a realistic request).
-      onResponse: (res) =>
-        withHeaders(res, (headers) => {
-          headers.set("X-Content-Type-Options", "nosniff")
-          headers.set("X-Frame-Options", frameOptions)
-          headers.set("Referrer-Policy", referrerPolicy)
-          if (hstsValue !== undefined) headers.set("Strict-Transport-Security", hstsValue)
-          if (csp !== undefined) headers.set("Content-Security-Policy", csp)
-        }),
+      responseHeaders: declared,
     },
     {
       id: NIFRA_ASSURANCE.SECURITY_HEADERS,