@nifrajs/web 5.2.0 → 5.4.0

package/src/public-dir.ts

@@ -12,11 +12,20 @@
  * Distinct from `publicPath` in `build.ts`, which is the URL prefix for content-hashed bundle chunks.
  * The names collide and the concepts do not: `publicPath` never covers user-authored files.
  */
-import { realpath } from "node:fs/promises"
-import { extname, normalize, resolve, sep } from "node:path"
+import { createHash } from "node:crypto"
+import { type FileHandle, realpath } from "node:fs/promises"
+import { normalize, resolve, sep } from "node:path"
 import { Readable } from "node:stream"
 import { parseByteRange } from "@nifrajs/core/range"
 import { pathnameOf } from "@nifrajs/core/server"
+import {
+  contentTags,
+  contentTypeOf,
+  ifRangeAllowsPartial,
+  isHiddenPath,
+  isNotModified,
+  lastModifiedOf,
+} from "@nifrajs/core/static-file"
 import { openResolved } from "./open-resolved.ts"
 
 /** How long each subtree may be cached. Content-hashed bundle output can be immutable; a
@@ -49,91 +58,40 @@ export const IMMUTABLE = "public, max-age=31536000, immutable"
 export const ONE_DAY = "public, max-age=86400"
 
 /**
- * Media types by extension. A table rather than `Bun.file(path).type`: this handler also runs on the
- * Node and Deno adapters, where `Bun` does not exist and every hit would throw. Unknown extensions
- * (and extensionless files such as ACME tokens) are served as `application/octet-stream`, which
- * together with `nosniff` keeps the browser from guessing a more dangerous type.
+ * Whether a confined path crosses a hidden segment ({@link isHiddenPath}). Checked on the
+ * resolved path, so `%2e` encodings are covered, and again on the real target, so a visible name
+ * linking to `.env` is refused too.
  */
-export const CONTENT_TYPES: Readonly<Record<string, string>> = {
-  ".html": "text/html; charset=utf-8",
-  ".htm": "text/html; charset=utf-8",
-  ".css": "text/css; charset=utf-8",
-  ".js": "text/javascript; charset=utf-8",
-  ".mjs": "text/javascript; charset=utf-8",
-  ".cjs": "text/javascript; charset=utf-8",
-  ".json": "application/json; charset=utf-8",
-  ".map": "application/json; charset=utf-8",
-  ".webmanifest": "application/manifest+json",
-  ".txt": "text/plain; charset=utf-8",
-  ".md": "text/markdown; charset=utf-8",
-  ".csv": "text/csv; charset=utf-8",
-  ".xml": "application/xml",
-  ".rss": "application/rss+xml",
-  ".atom": "application/atom+xml",
-  ".svg": "image/svg+xml",
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-  ".avif": "image/avif",
-  ".ico": "image/x-icon",
-  ".bmp": "image/bmp",
-  ".woff": "font/woff",
-  ".woff2": "font/woff2",
-  ".ttf": "font/ttf",
-  ".otf": "font/otf",
-  ".wasm": "application/wasm",
-  ".pdf": "application/pdf",
-  ".zip": "application/zip",
-  ".mp4": "video/mp4",
-  ".webm": "video/webm",
-  ".ogg": "audio/ogg",
-  ".mp3": "audio/mpeg",
-  ".wav": "audio/wav",
-  ".m4a": "audio/mp4",
-  ".vtt": "text/vtt; charset=utf-8",
+function hiddenUnder(root: string, abs: string): boolean {
+  return abs !== root && isHiddenPath(abs.slice(root.length + 1))
 }
 
-/**
- * Whether a confined path crosses a dot-segment other than `.well-known`. The build copies `public/`
- * with dotfiles included, so an editor or VCS artifact (`.env`, `.git/`, `.DS_Store`) dropped there
- * would otherwise be downloadable. Checked on the resolved path, so `%2e` encodings are covered.
- */
-function isHiddenPath(root: string, abs: string): boolean {
-  for (const segment of abs.slice(root.length + 1).split(sep)) {
-    if (segment.startsWith(".") && segment !== ".well-known") return true
-  }
-  return false
-}
+// Up to this many bytes are read whole through the pinned descriptor, which then closes before the
+// response leaves: on Bun a 200 KB asset is served in 0.17 ms against 0.28 ms through a node:fs
+// stream. A larger body streams, so a video holds a stream's buffer per request rather than the file.
+const BUFFERED_BODY_MAX = 256 * 1024
+// Bun.serve drops the declared length of any stream body and sends it chunked, and a Bun.file body
+// would need this descriptor open for a send nothing reports the end of. So on Bun a body up to 1 MiB
+// is read whole as well: a slow client then holds ~1 MB, against ~0.6 MB through Bun's stream sink.
+const BUN_BUFFERED_BODY_MAX = 1024 * 1024
 
-/** HTTP dates carry second precision; comparing raw milliseconds makes every file look stale. */
-function seconds(time: number): number {
-  return Math.floor(time / 1000)
-}
+// One per process: the tag of a file served by any handler is remembered by its real path.
+const TAGS = contentTags(createHash)
 
-/**
- * `If-Range` decides whether a range request is still safe to answer partially. The only validator
- * this handler publishes is `last-modified`, so an entity-tag form can never match and the whole
- * representation is sent instead - which is the conformant outcome, not a fallback. Dates use strong
- * comparison (RFC 9110 13.1.5): a file modified since the client's copy invalidates its byte offsets.
- */
-function ifRangeMatches(value: string | null, lastModified: number | undefined): boolean {
-  if (value === null) return true
-  if (lastModified === undefined) return false
-  const item = value.trim()
-  if (item.startsWith('"') || item.startsWith("W/")) return false
-  const parsed = Date.parse(item)
-  return Number.isFinite(parsed) && seconds(parsed) === seconds(lastModified)
-}
-
-/** `If-Modified-Since` freshness. No ETag is published, so there is no `If-None-Match` precedence. */
-function isNotModified(request: Request, lastModified: number | undefined): boolean {
-  if (lastModified === undefined) return false
-  const since = request.headers.get("if-modified-since")
-  if (since === null) return false
-  const parsed = Date.parse(since)
-  return Number.isFinite(parsed) && seconds(parsed) >= seconds(lastModified)
+/** `length` bytes of `handle` from `start`; fewer when the file shrank since its stat. */
+async function readPinned(
+  handle: FileHandle,
+  start: number,
+  length: number,
+): Promise<Uint8Array<ArrayBuffer>> {
+  const bytes = new Uint8Array(length)
+  let offset = 0
+  while (offset < length) {
+    const { bytesRead } = await handle.read(bytes, offset, length - offset, start + offset)
+    if (bytesRead === 0) break
+    offset += bytesRead
+  }
+  return offset === length ? bytes : bytes.subarray(0, offset)
 }
 
 /**
@@ -166,6 +124,10 @@ export function resolvePublicPath(root: string, pathname: string): string | unde
  * never shadow a route. That ordering is also why a `routes/robots.txt.tsx` beats a
  * `public/robots.txt` only if the caller checks routes first; the documented precedence is that the
  * static probe runs first, so `public/` wins, and an app wanting the route should not ship both.
+ *
+ * A file is sent with a strong `ETag` from its bytes, the tag `@nifrajs/node`'s `static` reader and
+ * the Deno entry send, and with `Last-Modified` only while its mtime is that of its own last change,
+ * so a replacement that keeps a file's size and timestamps is never judged current or resumed into.
  */
 export function servePublicDir(
   options: ServePublicDirOptions,
@@ -176,6 +138,7 @@ export function servePublicDir(
   const hashedFiles = options.hashedFiles
   const hashed = options.cache?.hashed ?? IMMUTABLE
   const assets = options.cache?.assets ?? ONE_DAY
+  const bufferedMax = typeof Bun === "undefined" ? BUFFERED_BODY_MAX : BUN_BUFFERED_BODY_MAX
 
   return async (request: Request): Promise<Response | undefined> => {
     if (request.method !== "GET" && request.method !== "HEAD") return undefined
@@ -186,7 +149,7 @@ export function servePublicDir(
     // A production manifest can reject page routes without touching the filesystem.
     if (options.files !== undefined && !options.files.has(pathname)) return undefined
     const abs = resolvePublicPath(root, pathname)
-    if (abs === undefined || isHiddenPath(root, abs)) return undefined
+    if (abs === undefined || hiddenUnder(root, abs)) return undefined
     const [resolvedRoot, resolvedFile] = await Promise.all([
       rootReal,
       realpath(abs).catch(() => undefined),
@@ -194,7 +157,8 @@ export function servePublicDir(
     if (
       resolvedRoot === undefined ||
       resolvedFile === undefined ||
-      (resolvedFile !== resolvedRoot && !resolvedFile.startsWith(resolvedRoot + sep))
+      (resolvedFile !== resolvedRoot && !resolvedFile.startsWith(resolvedRoot + sep)) ||
+      hiddenUnder(resolvedRoot, resolvedFile)
     ) {
       return undefined
     }
@@ -204,13 +168,15 @@ export function servePublicDir(
     // symlink; the descriptor then pins the bytes for the lifetime of the response.
     let handle: Awaited<ReturnType<typeof openResolved>> | undefined
     try {
+      let file: FileHandle
       try {
-        handle = await openResolved(resolvedFile)
+        file = await openResolved(resolvedFile)
       } catch {
         // A name refused or gone since realpath falls through, as a failed realpath does.
         return undefined
       }
-      const stat = await handle.stat()
+      handle = file
+      const stat = await file.stat()
       if (!stat.isFile()) return undefined
       const size = stat.size
       const headers = new Headers({
@@ -228,24 +194,42 @@ export function servePublicDir(
         // rendered as HTML, say). The declared type below is authoritative.
         "x-content-type-options": "nosniff",
         // Set explicitly rather than inferred from the body, so HEAD (a null body) carries it too.
-        "content-type":
-          CONTENT_TYPES[extname(resolvedFile).toLowerCase()] ?? "application/octet-stream",
+        "content-type": contentTypeOf(resolvedFile),
       })
-      const lastModified =
-        Number.isFinite(stat.mtimeMs) && stat.mtimeMs > 0 ? stat.mtimeMs : undefined
+      // The whole file, when tagging it had to read it: the response is then served from these bytes.
+      let whole: Uint8Array<ArrayBuffer> | undefined
+      let etag = TAGS.cached(resolvedFile, stat)
+      if (etag === undefined && size <= bufferedMax) {
+        whole = await readPinned(file, 0, size)
+        etag = TAGS.ofBytes(resolvedFile, stat, whole)
+      }
+      etag ??= await TAGS.ofFile(resolvedFile, stat, async (bytes, position) => {
+        return (await file.read(bytes, 0, bytes.byteLength, position)).bytesRead
+      })
+      if (etag !== undefined) headers.set("etag", etag)
+      const lastModified = lastModifiedOf(stat)
       if (lastModified !== undefined) {
         headers.set("last-modified", new Date(lastModified).toUTCString())
       }
       const head = request.method === "HEAD"
 
-      if (isNotModified(request, lastModified)) {
+      if (
+        isNotModified(
+          request.headers.get("if-none-match"),
+          request.headers.get("if-modified-since"),
+          etag,
+          lastModified,
+        )
+      ) {
         headers.delete("content-type")
         return new Response(null, { status: 304, headers })
       }
 
-      const rangeHeader = request.headers.get("range")
+      // Range applies to GET only (RFC 9110 section 14.2); HEAD reports the whole representation.
+      const rangeHeader = head ? null : request.headers.get("range")
       const range =
-        rangeHeader !== null && ifRangeMatches(request.headers.get("if-range"), lastModified)
+        rangeHeader !== null &&
+        ifRangeAllowsPartial(request.headers.get("if-range"), etag, lastModified)
           ? parseByteRange(rangeHeader, size)
           : ({ kind: "none" } as const)
 
@@ -255,8 +239,20 @@ export function servePublicDir(
         return new Response(null, { status: 416, headers })
       }
 
-      const body = (start?: number, end?: number): ReadableStream<Uint8Array> => {
-        const stream = handle!.createReadStream({ start, end })
+      const body = async (
+        start: number,
+        end: number,
+      ): Promise<Uint8Array<ArrayBuffer> | ReadableStream<Uint8Array>> => {
+        const length = end - start + 1
+        if (length <= bufferedMax) {
+          const bytes =
+            whole === undefined
+              ? await readPinned(file, start, length)
+              : whole.subarray(start, start + length)
+          headers.set("content-length", String(bytes.byteLength))
+          return bytes
+        }
+        const stream = file.createReadStream({ start, end })
         // FileHandle.createReadStream owns closing the descriptor after EOF/abort.
         handle = undefined
         return Readable.toWeb(stream) as unknown as ReadableStream<Uint8Array>
@@ -266,14 +262,14 @@ export function servePublicDir(
         const { start, end } = range.ranges[0]!
         headers.set("content-range", `bytes ${start}-${end}/${size}`)
         headers.set("content-length", String(end - start + 1))
-        return new Response(head ? null : body(start, end), { status: 206, headers })
+        return new Response(head ? null : await body(start, end), { status: 206, headers })
       }
 
       // Multiple ranges would require assembling `multipart/byteranges`, and doing that for a file on
       // disk means buffering the whole representation to serve a request that asked for less of it.
       // RFC 9110 lets a server ignore Range entirely, so the full body is the conformant answer here.
       headers.set("content-length", String(size))
-      return new Response(head ? null : body(), { headers })
+      return new Response(head || size === 0 ? null : await body(0, size - 1), { headers })
     } finally {
       if (handle !== undefined) {
         try {
@@ -285,3 +281,68 @@ export function servePublicDir(
     }
   }
 }
+
+export interface PrerenderedPageReaderOptions {
+  /** Absolute path of the directory the build wrote the prerendered pages into. */
+  readonly dir: string
+  /** Each page path mapped to its file, relative to `dir`. */
+  readonly files: Readonly<Record<string, string>>
+  /** Bytes of HTML kept in memory once read (default 32 MiB); a page past the budget is read per request. */
+  readonly cacheBytes?: number
+}
+
+/**
+ * Read a self-hosted build's prerendered pages for `createWebApp`'s `prerenderedPages`. Only the build's
+ * own files are reachable, each opened only once its real path is inside `dir`, so a link planted in the
+ * deployed tree cannot point a page elsewhere. A deploy's files do not change while it runs, so a page
+ * is kept after its first read; `undefined` (a missing or refused file) renders the page on demand.
+ */
+export function prerenderedPageReader(
+  options: PrerenderedPageReaderOptions,
+): (pathname: string) => Promise<string | undefined> {
+  const root = resolve(options.dir)
+  const rootReal = realpath(root).catch(() => undefined)
+  const files = new Map(Object.entries(options.files))
+  const budget = options.cacheBytes ?? 32 * 1024 * 1024
+  const cache = new Map<string, string>()
+  let cachedBytes = 0
+  return async (pathname) => {
+    const cached = cache.get(pathname)
+    if (cached !== undefined) return cached
+    const rel = files.get(pathname)
+    if (rel === undefined) return undefined
+    const abs = resolve(root, rel)
+    if (!abs.startsWith(root + sep) || hiddenUnder(root, abs)) return undefined
+    const [resolvedRoot, resolvedFile] = await Promise.all([
+      rootReal,
+      realpath(abs).catch(() => undefined),
+    ])
+    if (
+      resolvedRoot === undefined ||
+      resolvedFile === undefined ||
+      !resolvedFile.startsWith(resolvedRoot + sep)
+    ) {
+      return undefined
+    }
+    let handle: FileHandle
+    try {
+      handle = await openResolved(resolvedFile)
+    } catch {
+      return undefined
+    }
+    try {
+      if (!(await handle.stat()).isFile()) return undefined
+      const bytes = await handle.readFile()
+      const html = bytes.toString("utf8")
+      if (!cache.has(pathname) && cachedBytes + bytes.byteLength <= budget) {
+        cache.set(pathname, html)
+        cachedBytes += bytes.byteLength
+      }
+      return html
+    } catch {
+      return undefined
+    } finally {
+      await handle.close().catch(() => undefined)
+    }
+  }
+}

package/src/render-seam.ts

@@ -155,13 +155,16 @@ export interface RenderAdapter {
   ): ReadableStream<Uint8Array> | Promise<ReadableStream<Uint8Array>>
   /**
    * Render the chain to a complete HTML string when no content is deferred. `options.nonce` is the
-   * document's CSP nonce, for any inline script the renderer emits (Solid's hydration data).
+   * document's CSP nonce, for any inline script the renderer emits (Solid's hydration data); a
+   * document that sends a policy keeps the nonce only when the returned HTML carries it. Return
+   * `undefined` when the render suspended on something only `renderToStream` waits for (React's
+   * `use` or `lazy` inside `<Suspense>`): the page is then streamed instead.
    */
   renderToString?(
     chain: readonly unknown[],
     props: RenderProps,
     options?: RenderStreamOptions,
-  ): string | Promise<string>
+  ): string | undefined | Promise<string | undefined>
   /** Per-document bootstrap markup injected into `<head>` for client hydration. */
   hydrationHead(nonce?: string): string
   /**

package/src/search.ts

@@ -107,6 +107,7 @@ function encodeValue(value: unknown): string {
 /** The default JSON-first codec. Repeated keys (`?t=a&t=b`) decode to an array; single keys to a value. */
 const jsonCodec: SearchCodec = {
   parse(raw, limits) {
+    if (raw === "" || raw === "?") return {}
     const usp = new URLSearchParams(raw.startsWith("?") ? raw.slice(1) : raw)
     // Two passes instead of the old `Set(keys) + getAll(key)` shape, which rescanned the complete
     // URLSearchParams list once per distinct key (O(keys²)). Admission must be decided BEFORE any

package/src/vite.ts

@@ -11,7 +11,7 @@
  * Vite's `middlewares` are Connect-style - it runs fine under Bun.
  */
 
-import { type Dirent, readdirSync, writeFileSync } from "node:fs"
+import { type Dirent, existsSync, readdirSync, realpathSync, writeFileSync } from "node:fs"
 import {
   createServer as createHttpServer,
   type IncomingMessage,
@@ -19,6 +19,7 @@ import {
 } from "node:http"
 import { dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path"
 import { singleCopyPackageNames } from "@nifrajs/core/single-copy"
+import { isHiddenPath } from "@nifrajs/core/static-file"
 import { CLIENT_BATCH_MAX_BYTES } from "./dev-client.ts"
 import { DEV_REQUEST_ID_HEADER, DEV_SERVER_FILES } from "./dev-feed.ts"
 import { listenOrExplain } from "./dev-port.ts"
@@ -77,6 +78,8 @@ interface ViteLike {
   ssrFixStacktrace(err: Error): void
   /** The module graph, used to invalidate a changed file AND its transitive importers before reload. */
   readonly moduleGraph?: ViteModuleGraph
+  /** The resolved config: `publicDir` is absolute, or `""` when the public directory is off. */
+  readonly config?: { readonly publicDir?: string }
   readonly watcher: {
     on(event: "change" | "add" | "unlink", cb: (path: string) => void): void
     on(event: "ready", cb: () => void): void
@@ -251,8 +254,13 @@ function toWebRequest(req: IncomingMessage, body: Buffer | undefined): Request {
 
 /** The bits of a Node ServerResponse `pipeWebBodyToNode` touches - structural, to avoid a node:http dep here. */
 interface NodeResLike {
+  /** Set once the socket is gone: `close` has fired, and a write returns `false` for good. */
+  readonly destroyed?: boolean
   flushHeaders?(): void
   on(event: "close", cb: () => void): void
+  // Optional so a bare sink still fits; without them a full buffer is not waited out.
+  once?(event: "drain", cb: () => void): void
+  off?(event: "close" | "drain", cb: () => void): void
   write(chunk: Uint8Array): boolean
   end(): void
 }
@@ -282,6 +290,8 @@ export function applyResponseHeaders(headers: Headers, res: NodeHeaderSink): voi
  * `arrayBuffer()`) waits for the stream to END - which an open-ended SSE (`text/event-stream`) body never
  * does, so it hung `nifra dev` (the Bun production server streamed it fine). This flushes each chunk as it
  * arrives and cancels the reader if the client disconnects; a finite body just streams its chunk(s) + ends.
+ * A write the socket can't take yet is waited out (`drain`) before the next read, so a slow client
+ * holds one chunk rather than the whole body.
  */
 export async function pipeWebBodyToNode(
   body: ReadableStream<Uint8Array> | null,
@@ -291,17 +301,48 @@ export async function pipeWebBodyToNode(
     res.end()
     return
   }
+  // A call, so the check after an await is not narrowed by the one before it.
+  const destroyed = (): boolean => res.destroyed === true
+  // The client left while the app ran: `close` fired before anyone listened, and no `drain` comes.
+  if (destroyed()) {
+    await body.cancel().catch(() => {})
+    return
+  }
   const reader = body.getReader()
   res.flushHeaders?.()
-  res.on("close", () => void reader.cancel().catch(() => {}))
+  let closed = false
+  let wake: (() => void) | undefined
+  const onClose = (): void => {
+    closed = true
+    void reader.cancel().catch(() => {})
+    wake?.()
+  }
+  res.on("close", onClose)
   try {
     for (;;) {
       const { done, value } = await reader.read()
       if (done) break
-      res.write(value)
+      if (!res.write(value) && !closed && res.once !== undefined) {
+        if (destroyed()) {
+          onClose()
+          break
+        }
+        let drain!: () => void
+        const drained = new Promise<void>((resolve) => {
+          drain = resolve
+        })
+        wake = drain
+        res.once("drain", drain)
+        await drained
+        res.off?.("drain", drain)
+        wake = undefined
+      }
     }
   } catch {
     // client disconnected mid-stream - the `close` handler already cancelled the reader
+  } finally {
+    res.off?.("close", onClose)
+    reader.releaseLock()
   }
   res.end()
 }
@@ -416,7 +457,38 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
     handleWithVite(req, res)
   })
 
+  // Vite's public middleware serves every file under the public directory, dotfiles included. A
+  // build ships no hidden file and the Bun pipeline's `servePublicDir` refuses one, so a request for
+  // `/.env` or `/.git/config` goes to the app here too, as it does in production.
+  function isHiddenPublicFile(url: string): boolean {
+    const configured = vite.config?.publicDir
+    if (configured === undefined || configured === "") return false
+    // Vite writes the path with `/`; resolved, it uses the platform's separator like `file`.
+    const publicDir = resolvePath(configured)
+    let rel: string
+    try {
+      rel = decodeURIComponent(new URL(url, "http://localhost").pathname).slice(1)
+    } catch {
+      return false
+    }
+    const file = resolvePath(publicDir, rel)
+    if (!file.startsWith(publicDir + sep) || !existsSync(file)) return false
+    if (isHiddenPath(rel)) return true
+    // A visible name linking to a hidden file is refused too, as `servePublicDir` refuses it.
+    try {
+      const real = realpathSync(file)
+      const realRoot = realpathSync(publicDir)
+      return real.startsWith(realRoot + sep) && isHiddenPath(real.slice(realRoot.length + 1))
+    } catch {
+      return false
+    }
+  }
+
   function handleWithVite(req: IncomingMessage, res: ServerResponse): void {
+    if (isHiddenPublicFile(req.url ?? "/")) {
+      handleWithApp(req, res)
+      return
+    }
     vite.middlewares(req, res, (error) => {
       // In middleware mode Vite reports a module's transform error to the overlay and passes the
       // request on. A request naming a source file was for a module, never a page: it gets the error,
@@ -437,60 +509,64 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
         return
       }
       // Not a Vite asset → nifra SSR. (`next` runs after Vite declines, so the body is still readable.)
-      void (async () => {
-        try {
-          const body = await readNodeBody(req)
-          const webRequest = toWebRequest(req, body)
-          let overlay = false
-          const nifraRes = await session.track(webRequest, async () => {
-            try {
-              return await app.fetch(webRequest)
-            } catch (err) {
-              // Source-map the stack first (Vite maps the bundled frames back to your `.ts`), then render
-              // the readable dev overlay instead of a bare text dump. Dev-only - production maps to `_error`.
-              if (err instanceof Error) vite.ssrFixStacktrace(err)
-              overlay = true
-              return new Response(
-                session.failure(err, { method: req.method ?? "GET", url: req.url ?? "/" }),
-                { status: 500, headers: { "content-type": "text/html; charset=utf-8" } },
-              )
-            }
-          })
-          const contentType = nifraRes.headers.get("content-type") ?? ""
-          res.statusCode = nifraRes.status
-          const requestId = nifraRes.headers.get(DEV_REQUEST_ID_HEADER)
-          if (requestId !== null) res.setHeader(DEV_REQUEST_ID_HEADER, requestId)
-          if (overlay || session.isOverlay(nifraRes)) {
-            res.setHeader("content-type", "text/html; charset=utf-8")
-            res.end(await nifraRes.text())
-            return
-          }
-          if (!contentType.includes("text/html")) {
-            // Data / redirect / asset response - pass through untouched, streamed (SSE-safe). Set-Cookie is
-            // emitted per-header so multi-cookie responses (e.g. better-auth sessions) aren't collapsed.
-            applyResponseHeaders(nifraRes.headers, res)
-            await pipeWebBodyToNode(nifraRes.body, res)
-            return
+      handleWithApp(req, res)
+    })
+  }
+
+  function handleWithApp(req: IncomingMessage, res: ServerResponse): void {
+    void (async () => {
+      try {
+        const body = await readNodeBody(req)
+        const webRequest = toWebRequest(req, body)
+        let overlay = false
+        const nifraRes = await session.track(webRequest, async () => {
+          try {
+            return await app.fetch(webRequest)
+          } catch (err) {
+            // Source-map the stack first (Vite maps the bundled frames back to your `.ts`), then render
+            // the readable dev overlay instead of a bare text dump. Dev-only - production maps to `_error`.
+            if (err instanceof Error) vite.ssrFixStacktrace(err)
+            overlay = true
+            return new Response(
+              session.failure(err, { method: req.method ?? "GET", url: req.url ?? "/" }),
+              { status: 500, headers: { "content-type": "text/html; charset=utf-8" } },
+            )
           }
-          // Inject Vite's HMR client + the framework's refresh preamble into the SSR'd HTML, keeping the
-          // app's headers (cookies, CSP, cache-control) as the Bun pipeline does.
-          const headers = new Headers(nifraRes.headers)
-          headers.delete("content-length") // the body grows with Vite's tags
-          const page = session.decorateHtml(webRequest, await nifraRes.text(), headers, requestId)
-          const html = admitViteTags(await vite.transformIndexHtml(req.url ?? "/", page), headers)
-          applyResponseHeaders(headers, res)
+        })
+        const contentType = nifraRes.headers.get("content-type") ?? ""
+        res.statusCode = nifraRes.status
+        const requestId = nifraRes.headers.get(DEV_REQUEST_ID_HEADER)
+        if (requestId !== null) res.setHeader(DEV_REQUEST_ID_HEADER, requestId)
+        if (overlay || session.isOverlay(nifraRes)) {
           res.setHeader("content-type", "text/html; charset=utf-8")
-          res.end(html)
-        } catch (err) {
-          // A failure past the app (reading the body, Vite's HTML transform): same overlay, same feed.
-          if (err instanceof Error) vite.ssrFixStacktrace(err)
-          const html = session.failure(err, { method: req.method ?? "GET", url: req.url ?? "/" })
-          res.statusCode = 500
-          res.setHeader("content-type", "text/html; charset=utf-8")
-          res.end(html)
+          res.end(await nifraRes.text())
+          return
         }
-      })()
-    })
+        if (!contentType.includes("text/html")) {
+          // Data / redirect / asset response - pass through untouched, streamed (SSE-safe). Set-Cookie is
+          // emitted per-header so multi-cookie responses (e.g. better-auth sessions) aren't collapsed.
+          applyResponseHeaders(nifraRes.headers, res)
+          await pipeWebBodyToNode(nifraRes.body, res)
+          return
+        }
+        // Inject Vite's HMR client + the framework's refresh preamble into the SSR'd HTML, keeping the
+        // app's headers (cookies, CSP, cache-control) as the Bun pipeline does.
+        const headers = new Headers(nifraRes.headers)
+        headers.delete("content-length") // the body grows with Vite's tags
+        const page = session.decorateHtml(webRequest, await nifraRes.text(), headers, requestId)
+        const html = admitViteTags(await vite.transformIndexHtml(req.url ?? "/", page), headers)
+        applyResponseHeaders(headers, res)
+        res.setHeader("content-type", "text/html; charset=utf-8")
+        res.end(html)
+      } catch (err) {
+        // A failure past the app (reading the body, Vite's HTML transform): same overlay, same feed.
+        if (err instanceof Error) vite.ssrFixStacktrace(err)
+        const html = session.failure(err, { method: req.method ?? "GET", url: req.url ?? "/" })
+        res.statusCode = 500
+        res.setHeader("content-type", "text/html; charset=utf-8")
+        res.end(html)
+      }
+    })()
   }
 
   // `conditions: ["bun"]` makes Vite resolve nifra's workspace packages (`@nifrajs/web-react/client`, …) to