@nifrajs/web 5.2.0 → 5.4.0

package/src/internal/render-document.ts

@@ -1,6 +1,12 @@
 import { isSameOriginPath, type ResponseResult, status as statusResult } from "@nifrajs/core/server"
 import type { BoundaryRegistration, BoundaryStates } from "../boundary.ts"
-import { type CspPolicy, cspDocumentNonce, cspHeaderValue, prepareCspPolicy } from "../csp.ts"
+import {
+  type CspPolicy,
+  cspCandidateNonce,
+  cspDocumentNonce,
+  cspHeaderValue,
+  prepareCspPolicy,
+} from "../csp.ts"
 import { type CssLoadingMode, DEFAULT_CSS_LOADING, normalizeCssLoading } from "../css-contract.ts"
 import { DEFERRED_ERROR_CODE, DEFERRED_RUNTIME, prepareDeferred } from "../deferred.ts"
 import { ISR_REVALIDATE_HEADER, ISR_REVALIDATE_TAGS_HEADER, serializeISRTags } from "../isr.ts"
@@ -54,6 +60,13 @@ const SCRIPT_ESCAPE_MAP: Readonly<Record<string, string>> = {
   [LINE_SEP]: "\\u2028",
   [PARA_SEP]: "\\u2029",
 }
+// Pages (the chain's last entry) whose string render suspended, with how many more requests go
+// straight to the stream instead of rendering the whole tree twice. The count runs out so a page
+// that suspended only once (a cold `lazy`) gets its buffered render back.
+const SUSPENDING_PAGES = new WeakMap<object, number>()
+const SUSPENDED_STREAMS = 32
+const isWeakKey = (value: unknown): value is object =>
+  (typeof value === "object" && value !== null) || typeof value === "function"
 const NODE_RESPONSE_BODY = Symbol.for("nifra.response.body")
 const RESPONSE_RESULT = Symbol.for("nifra.response.result")
 
@@ -544,43 +557,77 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
   // streaming renderer are pure overhead vs a single sync render + concat. A buffered string body also
   // gets an automatic Content-Length. A render throw surfaces here exactly as the streaming path's
   // shell-readiness `await` does, so the `_error` boundary still maps it to a status.
+  const streamed = (streamNonce: string | undefined): Promise<RenderedPage> =>
+    renderStreamedPage(
+      adapter,
+      chain,
+      renderProps,
+      shellOf,
+      parts,
+      closeRootHtml,
+      allDeferred,
+      tailHtml,
+      status,
+      headers,
+      streamNonce,
+      streamNonce === nonce ? nonceAttr : ` nonce="${escapeAttr(streamNonce ?? "")}"`,
+    ).then((response) => new ResponseRenderedPage(response))
+  const last = chain[chain.length - 1]
+  const leaf = isWeakKey(last) ? last : undefined
   if (allDeferred.length === 0 && adapter.renderToString !== undefined) {
+    // Under a CSP a render can still write a script for this request alone (Solid's serialized
+    // error boundary, React's streamed Suspense reveal): it is handed a nonce, which the document
+    // keeps only when the render used it, so every other document stays nonce-free and cacheable.
+    const renderNonce =
+      nonce ?? (csp === undefined ? undefined : cspCandidateNonce(csp, requestedNonce))
+    const adoptNonce = (): void => {
+      if (renderNonce === nonce || csp === undefined || renderNonce === undefined) return
+      headers["cache-control"] = "private, no-store"
+      const policy = cspHeaderValue(csp, adapter, renderNonce)
+      if (policy !== undefined) headers["content-security-policy"] = policy
+    }
+    // A page whose string render suspended before goes straight to the stream: the string pass
+    // would render the whole tree only to be thrown away again.
+    const skips = leaf === undefined ? undefined : SUSPENDING_PAGES.get(leaf)
+    if (leaf !== undefined && skips !== undefined) {
+      if (skips > 1) SUSPENDING_PAGES.set(leaf, skips - 1)
+      else SUSPENDING_PAGES.delete(leaf)
+      adoptNonce()
+      return streamed(renderNonce)
+    }
     const out =
       parts !== undefined
         ? adapter.renderToString(
             chain,
             renderProps,
-            nonce === undefined ? { parts } : { nonce, parts },
+            renderNonce === undefined ? { parts } : { nonce: renderNonce, parts },
           )
-        : nonce === undefined
+        : renderNonce === undefined
           ? adapter.renderToString(chain, renderProps)
-          : adapter.renderToString(chain, renderProps, { nonce })
-    return typeof out === "string"
-      ? new BufferedRenderedPage(shellOf() + out + closeRootHtml + tailHtml, status, headers)
-      : out.then(
-          (bodyHtml) =>
-            new BufferedRenderedPage(
-              shellOf() + bodyHtml + closeRootHtml + tailHtml,
-              status,
-              headers,
-            ),
-        )
+          : adapter.renderToString(chain, renderProps, { nonce: renderNonce })
+    const page = (bodyHtml: string | undefined): MaybePromise<RenderedPage> => {
+      if (bodyHtml === undefined) {
+        // The render suspended on something only the streaming renderer waits for (React's `use`
+        // in a `<Suspense>`): stream the page, so the boundary resolves on the server.
+        if (leaf !== undefined) SUSPENDING_PAGES.set(leaf, SUSPENDED_STREAMS)
+        if (parts !== undefined) {
+          parts.head = ""
+          parts.body = ""
+        }
+        adoptNonce()
+        return streamed(renderNonce)
+      }
+      if (renderNonce !== undefined && bodyHtml.includes(`nonce="${renderNonce}"`)) adoptNonce()
+      return new BufferedRenderedPage(
+        shellOf() + bodyHtml + closeRootHtml + tailHtml,
+        status,
+        headers,
+      )
+    }
+    return out instanceof Promise ? out.then(page) : page(out)
   }
 
-  return renderStreamedPage(
-    adapter,
-    chain,
-    renderProps,
-    shellOf,
-    parts,
-    closeRootHtml,
-    allDeferred,
-    tailHtml,
-    status,
-    headers,
-    nonce,
-    nonceAttr,
-  ).then((response) => new ResponseRenderedPage(response))
+  return streamed(nonce)
 }
 
 async function renderStreamedPage(
@@ -673,6 +720,9 @@ function htmlResponse(body: string, init: ResponseInit): Response {
  * script per deferred value (emitted once its promise settles - by now the app stream has awaited
  * the same Suspense boundaries - and placed OUTSIDE `#root`) → `tail`. A mid-stream app error errors
  * the result (the body breaks) rather than silently truncating a 200.
+ *
+ * The app stream is read one chunk per pull, so a client that stops reading stops the renderer
+ * too: a stalled connection holds a chunk, not the whole rendered body.
  */
 function streamDocument(
   shell: Uint8Array,
@@ -687,45 +737,59 @@ function streamDocument(
   // A client that goes away cancels the body: the renderer stops, and nothing more is written.
   let cancelled = false
   let released = false
+  const release = (): void => {
+    if (released) return
+    released = true
+    reader.releaseLock()
+  }
+  // Settled into scripts now, not when the app stream ends: a rejection a stalled client never
+  // reads up to is still handled (and logged) rather than left unhandled.
+  const scripts = deferred.map((d) =>
+    d.promise
+      .then(
+        (value) =>
+          // `serializeData` JSON-serializes the value and escapes `<`, `>`, and Unicode line
+          // separators before this framework-owned script is emitted.
+          `<script${nonceAttr}>window.__nifraResolve(${d.id},${serializeData(value)})</script>`, // nosemgrep: javascript.lang.security.audit.unknown-value-with-script-tag.unknown-value-with-script-tag
+      )
+      .catch((err: unknown) => {
+        // A rejected (or unserializable) deferred streams __nifraReject (the client `<Await>`
+        // surfaces it) - it must not break the whole body. Redact: stream a stable opaque code,
+        // never the raw error text; log the real reason server-side.
+        console.error("[nifra/web] deferred value rejected:", err)
+        return `<script${nonceAttr}>window.__nifraReject(${d.id},${serializeData(DEFERRED_ERROR_CODE)})</script>`
+      }),
+  )
   return new ReadableStream({
-    async start(controller) {
+    start(controller) {
+      controller.enqueue(shell)
+    },
+    async pull(controller) {
       try {
-        controller.enqueue(shell)
-        for (;;) {
+        if (!released) {
           const { done, value } = await reader.read()
           if (cancelled) return
-          if (done) break
-          controller.enqueue(value)
+          if (!done) {
+            controller.enqueue(value)
+            return
+          }
+          release()
+          controller.enqueue(closeRoot)
         }
-        controller.enqueue(closeRoot)
         // Stream each resolution as ITS OWN promise settles - NOT in array order. A slow
         // defer() must not block a faster one; each script self-addresses by id, so order is irrelevant.
         await Promise.all(
-          deferred.map(async (d) => {
-            let script: string
-            try {
-              const value = serializeData(await d.promise)
-              // `serializeData` JSON-serializes the value and escapes `<`, `>`, and Unicode line
-              // separators before this framework-owned script is emitted.
-              script = `<script${nonceAttr}>window.__nifraResolve(${d.id},${value})</script>` // nosemgrep: javascript.lang.security.audit.unknown-value-with-script-tag.unknown-value-with-script-tag
-            } catch (err) {
-              // A rejected deferred streams __nifraReject (the client `<Await>` surfaces it) - it must
-              // not break the whole body. Redact: stream a stable opaque code, never the raw error
-              // text; log the real reason server-side.
-              console.error("[nifra/web] deferred value rejected:", err)
-              script = `<script${nonceAttr}>window.__nifraReject(${d.id},${serializeData(DEFERRED_ERROR_CODE)})</script>`
-            }
-            if (!cancelled) controller.enqueue(enc.encode(script))
+          scripts.map(async (script) => {
+            const html = await script
+            if (!cancelled) controller.enqueue(enc.encode(html))
           }),
         )
         if (cancelled) return
         controller.enqueue(tail)
         controller.close()
       } catch (err) {
+        release()
         if (!cancelled) controller.error(err)
-      } finally {
-        released = true
-        reader.releaseLock()
       }
     },
     cancel(reason) {

package/src/internal/request-url.ts

@@ -12,3 +12,27 @@ export function urlPartsFor(request: Request): UrlParts {
   REQUEST_URL_PARTS.set(request, parts)
   return parts
 }
+
+// The origin depends only on the text before the path, which repeats across requests, so each
+// distinct prefix is parsed once instead of every request's whole URL. Cleared when full: a client
+// can vary the Host header without bound.
+const ORIGINS = new Map<string, string>()
+
+/** `new URL(request.url).origin`, or `""` for a URL that does not parse. */
+export function originFor(request: { readonly url: string }): string {
+  const url = request.url
+  const schemeEnd = url.indexOf("://")
+  const pathStart = schemeEnd === -1 ? -1 : url.indexOf("/", schemeEnd + 3)
+  const prefix = pathStart === -1 ? url : url.slice(0, pathStart)
+  let origin = ORIGINS.get(prefix)
+  if (origin === undefined) {
+    try {
+      origin = new URL(prefix).origin
+    } catch {
+      origin = ""
+    }
+    if (ORIGINS.size >= 64) ORIGINS.clear()
+    ORIGINS.set(prefix, origin)
+  }
+  return origin
+}

package/src/internal/secret-scan.ts

@@ -694,10 +694,18 @@ export function createRedactor(
 export const buildEnvironment = (): Readonly<Record<string, string | undefined>> =>
   (typeof Bun !== "undefined" ? Bun.env : undefined) ?? process.env
 
+/** A build artifact holds a secret. Its own class so a step that tolerates other failures still stops. */
+export class SecretScanError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "SecretScanError"
+  }
+}
+
 /** Scan and throw the build-failing message on any finding. */
 export function assertNoSecrets(input: SecretScanInput): void {
   const message = formatSecretFindings(scanForSecrets(input))
-  if (message !== undefined) throw new Error(message)
+  if (message !== undefined) throw new SecretScanError(message)
 }
 
 /** The build-failing message for secret findings, or `undefined` when there are none. */

package/src/internal/web-app.ts

@@ -22,6 +22,7 @@ import { createMatcher, PRERENDERED_LIST_PATH } from "../router.ts"
 import type { EvidenceAncestry } from "./evidence-traversal.ts"
 import { formatShadowedPages, shadowedPages } from "./mount-shadow.ts"
 import { createPageRequestExecutor, type NonceResolver, type PageI18n } from "./page-execution.ts"
+import { type PrerenderedPages, servePrerenderedPages } from "./prerendered-pages.ts"
 import { requestPattern } from "./route-path.ts"
 
 export type { NonceResolver } from "./page-execution.ts"
@@ -73,6 +74,8 @@ export interface CreateWebAppOptions<Env = unknown> {
   readonly serverComponents?: import("../server-components/types.ts").ServerComponentRuntime
   readonly adapter: RenderAdapter
   readonly manifest: Manifest
+  /** Cache production module imports and layout preparation, never request data. Defaults to NODE_ENV === "production"; disable for a mutable manifest. */
+  readonly cacheRouteModules?: boolean
   /** URL of the built client entry (module script) injected into every page. */
   readonly clientEntry: string
   /** Default document title for all pages. */
@@ -252,6 +255,14 @@ export interface CreateWebAppOptions<Env = unknown> {
    * 4 KB of JSON is served once from `/__nifra/prerendered.json?v=<version>`, cacheable for good, and
    * pages hand over only that URL; `prerenderRoutes` writes the file into a static output. */
   readonly prerenderedPaths?: readonly string[]
+  /**
+   * Pages a self-hosted build prerendered, answered from their file instead of rendered. `nifra build
+   * --target bun|node` wires this from its prerender pass. The page is served from the page route,
+   * so `use` middleware and every request hook run first; a request with a query string, a navigation
+   * data or component request, or a draft-mode visitor renders on demand as before. Ignored with
+   * {@link nonce}, whose documents need a nonce minted for their request.
+   */
+  readonly prerenderedPages?: PrerenderedPages
   /** Publish the project's `AGENTS.md` inside `/llms.txt` and `/llms-full.txt`. **Off by default**:
    * those endpoints are public and unauthenticated, while `AGENTS.md` is a repo file written for the
    * team - unreleased feature names, internal hostnames, and "don't touch X yet" notes live there
@@ -475,6 +486,9 @@ export function createWebApp<Env = unknown>(
     ? undefined
     : servedPrerenderedList(options.prerenderedPaths)
   const pageExecutor = createPageRequestExecutor<Env>({
+    ...(options.cacheRouteModules === undefined
+      ? {}
+      : { cacheRouteModules: options.cacheRouteModules }),
     ...(options.serverComponents === undefined
       ? {}
       : { serverComponents: options.serverComponents }),
@@ -520,17 +534,23 @@ export function createWebApp<Env = unknown>(
     cacheChannel,
   })
 
+  // A nonce app's documents authorize their scripts per request, which a file rendered once cannot.
+  const prerendered =
+    options.prerenderedPages === undefined || options.nonce !== undefined
+      ? undefined
+      : servePrerenderedPages(options.prerenderedPages, options.draftSecret)
   let ownsRootCatchAll = false
   for (const route of manifest.routes) {
     const pattern = requestPattern(route.pattern)
     if (pattern.startsWith("/*")) ownsRootCatchAll = true
+    const render = pageExecutor.get(route)
     app.register(
       "GET",
       pattern,
       options.serverComponents?.owns(route.id)
         ? { capabilities: options.serverComponents.capabilities(route.id) }
         : undefined,
-      pageExecutor.get(route),
+      prerendered === undefined ? render : prerendered(render),
     )
     app.register("POST", pattern, undefined, pageExecutor.post(route))
   }

package/src/isr.ts

@@ -161,6 +161,8 @@ export class MemoryCacheStore implements CacheStore {
   private order = 0
   private readonly purgedKeys = new Map<string, number>()
   private readonly purgedTags = new Map<string, number>()
+  // The newest purge order whose mark was evicted. A render fenced before it may predate that purge.
+  private purgeFloor = 0
 
   constructor(options: MemoryCacheStoreOptions = {}) {
     const isProd = typeof process !== "undefined" && process.env?.NODE_ENV === "production"
@@ -246,8 +248,8 @@ export class MemoryCacheStore implements CacheStore {
   }
 
   private purgedAfter(key: string, tags: readonly string[], fence: number): boolean {
-    if ((this.purgedKeys.get(key) ?? 0) > fence) return true
-    return tags.some((tag) => (this.purgedTags.get(tag) ?? 0) > fence)
+    if ((this.purgedKeys.get(key) ?? this.purgeFloor) > fence) return true
+    return tags.some((tag) => (this.purgedTags.get(tag) ?? this.purgeFloor) > fence)
   }
 
   private markPurged(marks: Map<string, number>, name: string): void {
@@ -255,9 +257,10 @@ export class MemoryCacheStore implements CacheStore {
     marks.set(name, ++this.order)
     // Bounded like the entries: a mark matters only to a render still in flight.
     while (marks.size > this.max) {
-      const oldest = marks.keys().next().value
+      const oldest = marks.entries().next().value
       if (oldest === undefined) break
-      marks.delete(oldest)
+      marks.delete(oldest[0])
+      this.purgeFloor = Math.max(this.purgeFloor, oldest[1])
     }
   }
 

package/src/prerender.ts

@@ -10,6 +10,7 @@
  */
 import { mkdirSync, writeFileSync } from "node:fs"
 import { dirname, join, resolve, sep } from "node:path"
+import { prerenderedDocumentHeaders } from "./internal/prerendered-pages.ts"
 import { assertNoSecrets, buildEnvironment, type SecretExemption } from "./internal/secret-scan.ts"
 import { fillRoutePattern, type RouteEntry } from "./manifest.ts"
 import { DATA_HEADER, PRERENDERED_GLOBAL, PRERENDERED_LIST_PATH } from "./router.ts"
@@ -52,6 +53,10 @@ export interface PrerenderEntry {
   /** The loader-data file written alongside (`<path>/_data.json`) so a client soft-nav INTO this
    * route skips the worker. Absent when the data-mode response is NDJSON (a deferred loader). */
   readonly dataFile?: string
+  /** The document headers a self-hosted server sends with this file (its `content-language` and CSP).
+   * Absent when the render was specific to its request - it set a cookie, was private or no-store, or
+   * varied on a request header - so a server keeps rendering this path on demand. */
+  readonly serveHeaders?: Readonly<Record<string, string>>
 }
 
 export interface PrerenderResult {
@@ -184,7 +189,14 @@ export async function prerenderRoutes(options: PrerenderOptions): Promise<Preren
       await dataRes.body?.cancel() // not emitting (non-OK or NDJSON) - release the stream
     }
 
-    prerendered.push({ path, file, bytes: html.length, ...(dataFile ? { dataFile } : {}) })
+    const serveHeaders = prerenderedDocumentHeaders(res.status, res.headers)
+    prerendered.push({
+      path,
+      file,
+      bytes: html.length,
+      ...(dataFile ? { dataFile } : {}),
+      ...(serveHeaders ? { serveHeaders } : {}),
+    })
   }
 
   for (const route of options.routes) {