@nifrajs/web 5.5.0 → 5.6.0

package/src/internal/share-data.ts

@@ -0,0 +1,136 @@
+const isPlain = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype
+
+const TOO_DEEP = Symbol("data too deep")
+
+// Client loaders may return graphs, unlike JSON. Check the whole graph before comparing: a cycle
+// inside a new subtree or beyond the array sample must not acquire copied parents. Shared references
+// and accessors also keep the fresh result intact, rather than changing aliases or invoking getters.
+function isTree(value: unknown, seen: Set<object>, depth: number): boolean {
+  if (!Array.isArray(value) && !isPlain(value)) return true
+  if (depth >= 128 || seen.has(value)) return false
+  seen.add(value)
+  for (const key of Reflect.ownKeys(value)) {
+    const field = Object.getOwnPropertyDescriptor(value, key)
+    if (
+      field === undefined ||
+      !("value" in field) ||
+      (!field.enumerable && !(Array.isArray(value) && key === "length")) ||
+      !isTree(field.value, seen, depth + 1)
+    )
+      return false
+  }
+  return true
+}
+
+/**
+ * Structural sharing for reloaded route data. Plain objects and arrays compare by content and Dates
+ * by time; other values and symbol-bearing objects come from `next`. Non-tree client data stays
+ * intact. `plainJson` is only for freshly parsed JSON, before any client-loader transformation.
+ *
+ * Array elements with an `id` pair by it before position, preserving unchanged rows on a prepend or
+ * reorder. An array whose first 32 elements keep nothing is taken whole, without a full old-row index.
+ */
+export function shareData<T>(prev: unknown, next: T, plainJson?: boolean): T
+export function shareData(prev: unknown, next: unknown, plainJson = false): unknown {
+  if (Object.is(prev, next)) return prev
+  if (!plainJson && !isTree(next, new Set(), 0)) return next
+  try {
+    return share(prev, next, 0, plainJson)
+  } catch (error) {
+    if (error === TOO_DEEP) return next
+    throw error
+  }
+}
+
+// Client loaders can attach metadata that an enumerable-string-key copy would lose. Parsed JSON has
+// no symbol keys, and the check would cost a third of a reload that changed one row.
+const hasSymbols = (a: object, b: object): boolean =>
+  Object.getOwnPropertySymbols(a).length > 0 || Object.getOwnPropertySymbols(b).length > 0
+
+function share(prev: unknown, next: unknown, depth: number, json: boolean): unknown {
+  if (Object.is(prev, next)) return prev
+  if (prev instanceof Date)
+    return next instanceof Date && prev.getTime() === next.getTime() ? prev : next
+  if (Array.isArray(next)) {
+    if (!Array.isArray(prev) || (!json && hasSymbols(prev, next))) return next
+    if (depth >= 128) throw TOO_DEEP
+    const out: unknown[] = []
+    let same = prev.length === next.length
+    let byId: Map<unknown, number> | undefined
+    let completeIndex = false
+    // Which old elements a new one took, from the first id lookup on: each pairs at most once, so
+    // duplicate ids never put one old object at two places. Every element before that lookup took
+    // its own position.
+    let taken: Uint8Array | undefined
+    let kept = 0
+    let i = 0
+    for (const item of next) {
+      let old: unknown = taken?.[i] === 1 ? undefined : prev[i]
+      const id = isPlain(item) ? item.id : undefined
+      if (id !== undefined && !(isPlain(old) && old.id === id)) {
+        if (taken === undefined) {
+          taken = new Uint8Array(prev.length)
+          taken.fill(1, 0, i)
+        }
+        if (byId === undefined || (i >= 32 && !completeIndex)) {
+          // Index only IDs needed by the sample until a kept row makes a full index worthwhile.
+          const wanted =
+            i < 32
+              ? new Set(next.slice(0, 32).map((value) => (isPlain(value) ? value.id : undefined)))
+              : undefined
+          completeIndex = wanted === undefined
+          let min = Number.POSITIVE_INFINITY
+          let max = Number.NEGATIVE_INFINITY
+          for (const key of wanted ?? []) {
+            if (typeof key !== "number" || Number.isNaN(key)) {
+              min = Number.NEGATIVE_INFINITY
+              max = Number.POSITIVE_INFINITY
+              break
+            }
+            min = Math.min(min, key)
+            max = Math.max(max, key)
+          }
+          byId = new Map()
+          for (let at = 0; at < prev.length; at++) {
+            const entry = prev[at]
+            if (!isPlain(entry)) continue
+            const entryId = entry.id
+            if (
+              wanted === undefined ||
+              ((typeof entryId !== "number" || !(entryId < min || entryId > max)) &&
+                wanted.has(entryId))
+            )
+              byId.set(entryId, at)
+          }
+        }
+        const at = byId.get(id)
+        old = at === undefined || taken[at] === 1 ? undefined : prev[at]
+        if (at !== undefined) taken[at] = 1
+      } else if (taken !== undefined && i < taken.length && old !== undefined) {
+        taken[i] = 1
+      }
+      const value = share(old, item, depth + 1, json)
+      out.push(value)
+      if (value === old) kept++
+      else if (i === 31 && kept === 0) return next
+      if (value !== prev[i]) same = false
+      i++
+    }
+    return same ? prev : out
+  }
+  if (!isPlain(prev) || !isPlain(next) || (!json && hasSymbols(prev, next))) return next
+  if (depth >= 128) throw TOO_DEEP
+  const keys = Object.keys(next)
+  let same = keys.length === Object.keys(prev).length
+  const out: Record<string, unknown> = {}
+  for (const key of keys) {
+    // A parsed payload can own a `__proto__` key, which a copy would turn into its prototype.
+    if (key === "__proto__") return next
+    const old = prev[key]
+    const value = share(old, next[key], depth + 1, json)
+    if (value !== old || (old === undefined && !Object.hasOwn(prev, key))) same = false
+    out[key] = value
+  }
+  return same ? prev : out
+}

package/src/internal/store-signature.ts

@@ -0,0 +1,149 @@
+/**
+ * Signatures on entries kept in a store other processes share (Workers KV, Redis). Whoever can write
+ * such a store could hand every visitor a page this app never built, so each entry carries an
+ * HMAC-SHA-256 under the app's secret, and an entry that fails the check reads as a miss.
+ */
+import type * as NodeCrypto from "node:crypto"
+import { timingSafeEqual } from "./timing-safe-equal.ts"
+
+const TEXT = new TextEncoder()
+const MAC_HEX = /^[0-9a-f]{64}$/
+// Code units of signed text a signer remembers as proven. A hot page then costs a comparison per
+// hit, not a hash: about 1.5 ns a byte to hash against a fraction of that to compare.
+const MAX_PROVEN_CHARS = 2 * 1024 * 1024
+const MAX_SIGNERS = 4
+
+/** Below this, a secret is too short to sign with. */
+export const MIN_STORE_SECRET_LENGTH = 32
+
+export const isStoreSecret = (value: unknown): value is string =>
+  typeof value === "string" && value.length >= MIN_STORE_SECRET_LENGTH
+
+/**
+ * Signs a list of strings. Each part is hashed behind its length, so no two lists hash the same
+ * bytes, whatever the parts hold.
+ */
+export interface StoreSigner {
+  /** The parts' MAC, as lowercase hex. */
+  sign(parts: readonly string[]): Promise<string>
+  /** Whether `mac` is the parts' MAC under this secret. Anything but 64 lowercase hex digits is not. */
+  verify(parts: readonly string[], mac: unknown): Promise<boolean>
+}
+
+type CreateHmac = typeof NodeCrypto.createHmac
+
+interface Hasher {
+  sign(parts: readonly string[]): Promise<string>
+  /** `mac` is already 64 lowercase hex digits. */
+  matches(parts: readonly string[], mac: string): Promise<boolean>
+}
+
+// Looked up, never imported: a Worker without nodejs_compat cannot load node:crypto. Where it exists
+// it is the cheaper path: Web Crypto answers on another thread, about 20 us a call on Bun, Node and
+// Deno, more than hashing a 16 KB page.
+function nodeCreateHmac(): CreateHmac | undefined {
+  const createHmac = globalThis.process?.getBuiltinModule?.("node:crypto")?.createHmac
+  return typeof createHmac === "function" ? createHmac : undefined
+}
+
+const sameParts = (a: readonly string[], b: readonly string[]): boolean =>
+  a.length === b.length && a.every((part, at) => part === b[at])
+
+const lengthOf = (parts: readonly string[]): number =>
+  parts.reduce((sum, part) => sum + part.length, 0)
+
+// One signer per secret for the process, so a handler built per request (a Worker reads its bindings
+// in `fetch`) still finds the pages earlier requests proved.
+const signers = new Map<string, StoreSigner>()
+
+export function storeSigner(secret: string): StoreSigner {
+  const existing = signers.get(secret)
+  if (existing !== undefined) return existing
+  const signer = provingSigner(hasher(secret))
+  for (const oldest of signers.keys()) {
+    if (signers.size < MAX_SIGNERS) break
+    signers.delete(oldest)
+  }
+  signers.set(secret, signer)
+  return signer
+}
+
+function provingSigner(hashing: Hasher): StoreSigner {
+  // MAC to the parts this signer signed or verified, oldest first.
+  const proven = new Map<string, readonly string[]>()
+  let provenChars = 0
+  const remember = (mac: string, parts: readonly string[]): void => {
+    const length = lengthOf(parts)
+    if (length > MAX_PROVEN_CHARS / 8) return
+    const had = proven.get(mac)
+    if (had !== undefined) {
+      proven.delete(mac)
+      provenChars -= lengthOf(had)
+    }
+    proven.set(mac, parts)
+    provenChars += length
+    for (const [oldest, kept] of proven) {
+      if (provenChars <= MAX_PROVEN_CHARS) break
+      proven.delete(oldest)
+      provenChars -= lengthOf(kept)
+    }
+  }
+  return {
+    async sign(parts) {
+      const mac = await hashing.sign(parts)
+      remember(mac, parts)
+      return mac
+    },
+    async verify(parts, mac) {
+      if (typeof mac !== "string" || !MAC_HEX.test(mac)) return false
+      const known = proven.get(mac)
+      if (known !== undefined && sameParts(known, parts)) return true
+      if (!(await hashing.matches(parts, mac))) return false
+      remember(mac, parts)
+      return true
+    },
+  }
+}
+
+function hasher(secret: string): Hasher {
+  const createHmac = nodeCreateHmac()
+  if (createHmac !== undefined) {
+    const hex = (parts: readonly string[]): string => {
+      const hmac = createHmac("sha256", secret)
+      for (const part of parts) hmac.update(`${part.length}:`).update(part)
+      return hmac.digest("hex")
+    }
+    return {
+      sign: async (parts) => hex(parts),
+      matches: async (parts, mac) => timingSafeEqual(hex(parts), mac),
+    }
+  }
+  let signingKey: Promise<CryptoKey> | undefined
+  const key = (): Promise<CryptoKey> => {
+    signingKey ??= crypto.subtle.importKey(
+      "raw",
+      TEXT.encode(secret),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign", "verify"],
+    )
+    return signingKey
+  }
+  const bytes = (parts: readonly string[]): Uint8Array<ArrayBuffer> =>
+    TEXT.encode(parts.map((part) => `${part.length}:${part}`).join(""))
+  return {
+    async sign(parts) {
+      const mac = new Uint8Array(await crypto.subtle.sign("HMAC", await key(), bytes(parts)))
+      let hex = ""
+      for (const byte of mac) hex += byte.toString(16).padStart(2, "0")
+      return hex
+    },
+    async matches(parts, mac) {
+      const expected = new Uint8Array(mac.length / 2)
+      for (let at = 0; at < expected.length; at++) {
+        expected[at] = Number.parseInt(mac.slice(at * 2, at * 2 + 2), 16)
+      }
+      return crypto.subtle.verify("HMAC", await key(), expected, bytes(parts))
+    },
+  }
+}

package/src/internal/vite-plugin-compat.ts

@@ -23,8 +23,8 @@ const isRecord = (value: unknown): value is Record<string, unknown> =>
  * Only a plugin's `config` hook output is rewritten, never mutated, and only under rolldown-vite.
  * Non-rolldown Vite is passed through verbatim.
  *
- * FLATTEN FIRST: a Vite plugin factory may return an ARRAY of plugins - `@vitejs/plugin-react`'s `react()`
- * returns `[vite:react-babel, vite:react-refresh]`, and it's `react:react-babel`'s `config` hook that emits
+ * FLATTEN FIRST: a plugin factory may return an ARRAY of plugins - `@vitejs/plugin-react@4.x`'s `react()`
+ * returns `[vite:react-babel, vite:react-refresh]`, and it's `vite:react-babel`'s `config` hook that emits
  * the offending `optimizeDeps.rollupOptions.jsx`. `nifra.config.ts` writes `vitePlugins = [react()]`, so the
  * plugin list arrives NESTED (`[[babel, refresh]]`). Without flattening, `.map` sees the inner array (which
  * has no `config`), leaves it untouched, and Vite - which flattens plugin arrays itself before running them

package/src/internal/web-app.ts

@@ -10,8 +10,9 @@ import {
   NIFRA_BACKEND_WS_RUNTIME,
   preRouteMountPaths,
 } from "@nifrajs/core/mount"
+import { withResponseObserver } from "@nifrajs/core/response-observer"
 import type { MountableApp, MountOptions } from "@nifrajs/core/server"
-import { type ServerOptions, server } from "@nifrajs/core/server"
+import { replacedRequestOf, type ServerOptions, server } from "@nifrajs/core/server"
 import { type CspPolicy, cspNonceResolver, DOCUMENT_POLICY, isCspPolicy } from "../csp.ts"
 import type { CssLoadingMode } from "../css-contract.ts"
 import {
@@ -26,9 +27,14 @@ import type { Manifest } from "../manifest.ts"
 import type { RenderAdapter } from "../render-seam.ts"
 import { createMatcher, PRERENDERED_LIST_PATH } from "../router.ts"
 import type { EvidenceAncestry } from "./evidence-traversal.ts"
+import { identityEpochHook, type KeepAliveServerOptions } from "./identity-epoch.ts"
+import { INVALIDATION, type InvalidationOp, invalidationOf } from "./invalidation-contract.ts"
+import { LIVE_ATTACH, type LiveAttachment, type LiveRuntimeHandle } from "./live-contract.ts"
 import { formatShadowedPages, shadowedPages } from "./mount-shadow.ts"
 import { createPageRequestExecutor, type NonceResolver, type PageI18n } from "./page-execution.ts"
+import { PPR_SERVER, PPR_SETUP, type PprSetup } from "./ppr/contract.ts"
 import { type PrerenderedPages, servePrerenderedPages } from "./prerendered-pages.ts"
+import type { RevalidateResult } from "./render-document.ts"
 import { requestPattern } from "./route-path.ts"
 
 export type { NonceResolver } from "./page-execution.ts"
@@ -101,6 +107,15 @@ export interface CreateWebAppOptions<Env = unknown> {
    * and stays cacheable by `withISR` or a CDN. `meta` still receives a nonce to name.
    */
   readonly csp?: CspPolicy
+  /** Experimental and unstable: features whose API may change in any release. */
+  readonly experimental?: {
+    /**
+     * Partial prerendering, from `partialPrerendering()` in `@nifrajs/web/ppr`. A route whose backend
+     * half exports `shellLoader` streams a shell shared by every visitor, then each `dynamic` boundary
+     * as it settles. Needs `csp` (hashes), not `nonce`.
+     */
+    readonly ppr?: PprSetup
+  }
   /**
    * Options for the underlying `server()` - `requestTimeoutMs`, `admission`, `gracefulSignals`, and
    * the rest of {@link ServerOptions}.
@@ -221,6 +236,11 @@ export interface CreateWebAppOptions<Env = unknown> {
    * signed `__nifra_draft` cookie gets `ctx.draft === true` in loaders/actions (else always `false`).
    * Pair with `withISR({ draftSecret })` so editors bypass the cache. Omit to disable draft mode. */
   readonly draftSecret?: string
+  /**
+   * Live data refresh, from `live()` in `@nifrajs/web/live`. Loaders declare keys with `ctx.live()`;
+   * the app answers live loads at the runtime's load endpoint. Omit and nothing live is loaded.
+   */
+  readonly live?: LiveRuntimeHandle
   /** Per-route chunk URLs (`buildClient`'s `BuildManifest.routes`) - `routeId → [layout chunks…, own
    * chunk]`. When present, each page `modulepreload`s its matched route's chunks alongside the entry,
    * so the route code downloads in parallel (no entry→route-chunk waterfall). Omit ⇒ entry-only. */
@@ -276,6 +296,14 @@ export interface CreateWebAppOptions<Env = unknown> {
    * server entry, before its static files too. A refused path answers the policy's refusal.
    */
   readonly hostPolicy?: HostPolicy
+  /**
+   * Which cookies say who is signed in, for an app with a `keepAlive` route. A response that changes
+   * or deletes one rotates the readable identity epoch cookie, and every tab drops the pages it kept
+   * for the previous visitor. The session cookies of `@nifrajs/auth`, Better Auth and Auth.js count
+   * under their default names; name any other in `identityCookies`. Development reports, once per
+   * name, an `HttpOnly` cookie that changes and is in neither list (`NIFRA_KEEPALIVE_IDENTITY_COOKIE`).
+   */
+  readonly keepAlive?: KeepAliveServerOptions
   /**
    * The files the build emitted, by request path: `buildAssets` from the generated server manifest.
    * A {@link hostPolicy} rule's `buildAssets` token matches exactly these. `nifra dev` serves the
@@ -330,6 +358,16 @@ export interface CreateWebAppOptions<Env = unknown> {
  * The `Request` is rebuilt rather than mutated (`url` is read-only), preserving method, headers, body,
  * and duplex streaming - the body is passed through unread, so a large or streamed upload is untouched.
  */
+/** Publish what a write named, for an app with `live` and no cache wrapper to run the pipeline. */
+async function publishOwn(
+  op: InvalidationOp,
+  request: Request,
+  publish: (keys: readonly string[]) => Promise<void>,
+): Promise<void> {
+  const { settleInvalidation } = await import("./invalidation.ts")
+  await settleInvalidation(op, { publish }, request, undefined)
+}
+
 /**
  * Resolve the explicit symbol-keyed backend mount interface. The symbol seam forwards platform
  * context without making web depend on client.
@@ -421,15 +459,23 @@ export function createWebApp<Env = unknown>(
     }
     app.use(hostPolicyGate(options.hostPolicy, options.buildAssets))
   }
+  // Before every app hook: a live load becomes the target page's GET here, so each hook, middleware,
+  // gate and loader sees that path once, as a navigation would.
+  const liveAttachment: LiveAttachment | undefined = options.live?.[LIVE_ATTACH]({
+    matchRoute: (path) => pageExecutor.matchRoute(path),
+    app,
+  })
+  if (liveAttachment !== undefined) app.onRequest(liveAttachment.onRequest)
   // Before the mount hooks and before every page route, so the order-scoped hooks (`derive`,
   // `beforeHandle`, assurance evidence) actually bind to them - see the `use` option. A caller
   // cannot do this after the fact: by the time this function returns, the routes are declared.
   options.use?.(app)
   if (options.serverComponents !== undefined) {
     const runtime = options.serverComponents
+    // A route whose holes show server components is one visitor's too.
     const match = createMatcher(
       manifest.routes
-        .filter((route) => runtime.owns(route.id))
+        .filter((route) => runtime.owns(route.id) || runtime.hosts?.(route.id) === true)
         .map((route) => ({ routeId: route.id, pattern: route.pattern })),
     )
     const privateRoute = (request: Request): boolean =>
@@ -473,6 +519,44 @@ export function createWebApp<Env = unknown>(
       cacheChannel.enabled = true
     },
   })
+  // One owner per write. A cache wrapper that opened the channel runs the whole pipeline and takes
+  // the operation here, by the request it passed in; without one, the app publishes the write's keys
+  // and tags itself, and a write with nothing to publish needs nothing at all.
+  const handedOver = new WeakMap<Request, InvalidationOp>()
+  const live = options.live
+  const publish =
+    live === undefined ? undefined : (keys: readonly string[]) => live.publish(...keys)
+  Object.defineProperty(app, INVALIDATION, {
+    value: {
+      take: (request: Request): InvalidationOp | undefined => {
+        const op = handedOver.get(request)
+        handedOver.delete(request)
+        return op
+      },
+      publish,
+    },
+  })
+  const invalidate = (
+    revalidation: RevalidateResult<unknown>,
+    request: Request,
+  ): Promise<void> | undefined => {
+    if (cacheChannel.enabled) {
+      const op = invalidationOf(revalidation)
+      // Every request in a hook's replacement chain: the wrapper holds the first one.
+      for (
+        let held: Request | undefined = request;
+        held !== undefined;
+        held = replacedRequestOf(held)
+      )
+        handedOver.set(held, op)
+      return undefined
+    }
+    // Paths alone refresh only the submitting page, which the response header already does.
+    const named = revalidation.__nifraInvalidate
+    if (publish === undefined || named === undefined || named.keys.length + named.tags.length === 0)
+      return undefined
+    return publishOwn(invalidationOf(revalidation), request, publish)
+  }
   // Mount the in-process backend over HTTP at `apiPrefix`, when one is given, BEFORE page routing.
   // Core's pre-route mount seam runs before the page wildcard `/*`; parent request hooks run first,
   // child request hooks run inside the mount, and parent response hooks still wrap the result.
@@ -511,6 +595,14 @@ export function createWebApp<Env = unknown>(
   const prerenderedList = ownPatterns.has(PRERENDERED_LIST_PATH)
     ? undefined
     : servedPrerenderedList(options.prerenderedPaths)
+  const ppr = options.experimental?.ppr?.[PPR_SETUP]({
+    adapter,
+    // biome-ignore lint/plugin/noConditionalEmptyObjectSpread: partial prerendering lists its scripts by hash only under an app's own policy.
+    ...(options.csp === undefined ? {} : { csp: options.csp }),
+    // The content-hashed entry changes with every client build; the store is per process.
+    deployment: clientEntry,
+    perRequestNonce: options.nonce !== undefined,
+  })
   const pageExecutor = createPageRequestExecutor<Env>({
     ...(options.cacheRouteModules === undefined
       ? {}
@@ -558,7 +650,17 @@ export function createWebApp<Env = unknown>(
     ...(options.onLoaderError === undefined ? {} : { onLoaderError: options.onLoaderError }),
     logBoundaryError: boundaryErrorLog(options.server),
     cacheChannel,
+    // biome-ignore lint/plugin/noConditionalEmptyObjectSpread: the executor takes a route's shell path only when partial prerendering is set up.
+    ...(ppr === undefined ? {} : { ppr }),
+    invalidate,
+    liveLoadOf: liveAttachment?.loadOf,
   })
+  if (ppr !== undefined) {
+    Object.defineProperty(app, PPR_SERVER, { value: ppr.server })
+    app.register("POST", ppr.cancelPath, undefined, (c: { readonly req: Request }) =>
+      ppr.cancel(c.req),
+    )
+  }
 
   // A nonce app's documents authorize their scripts per request, which a file rendered once cannot.
   const prerendered =
@@ -573,7 +675,8 @@ export function createWebApp<Env = unknown>(
     app.register(
       "GET",
       pattern,
-      options.serverComponents?.owns(route.id)
+      options.serverComponents?.owns(route.id) ||
+        options.serverComponents?.hosts?.(route.id) === true
         ? { capabilities: options.serverComponents.capabilities(route.id) }
         : undefined,
       prerendered === undefined ? render : prerendered(render),
@@ -632,6 +735,21 @@ export function createWebApp<Env = unknown>(
   // and the router refuses a second `/*` under another param name.
   if (!ownsRootCatchAll) app.register("GET", "/*", undefined, pageExecutor.fallback)
 
+  // Last, after every hook the caller's `use` added: a cookie any of them sets is seen here.
+  if (manifest.routes.some((route) => route.keepAlive === true)) {
+    // As for error details: only a run that says it is development or test reports, and an unset
+    // NODE_ENV (an unbuilt `bun app.ts`, a Worker) counts as production.
+    const nodeEnv = typeof process === "undefined" ? undefined : process.env?.NODE_ENV
+    app.use(
+      withResponseObserver({
+        onResponseHeaders: identityEpochHook(
+          options.keepAlive ?? {},
+          nodeEnv === "development" || nodeEnv === "test",
+        ),
+      }),
+    )
+  }
+
   const evidenceProvider: ComposedEvidenceProvider = async (passed) => {
     const { traverseEvidence } = await import("./evidence-traversal.ts")
     return traverseEvidence(evidenceProvider, passed, async (ancestry) => {