@nifrajs/web 5.5.1 → 5.7.0

package/src/internal/status-page.ts

@@ -0,0 +1,95 @@
+/**
+ * The terminal-status helpers and their brand, free of server imports: `@nifrajs/web/client` re-exports
+ * them for route helpers the browser also loads, which the root entry would drag `node:crypto` into.
+ */
+
+/** Derived from the `Headers` constructor rather than the DOM lib's `HeadersInit`: `@nifrajs/web`
+ * is consumed from DOM-free programs (the root tsconfig runs `types: ["bun"]`), and naming the DOM
+ * type here would break their build. Same workaround as `SSEInit.headers` in core. */
+export type HeadersLike = ConstructorParameters<typeof Headers>[0]
+
+/**
+ * Brand marking a `Response` as a **terminal-status signal** rather than a response to serve verbatim.
+ *
+ * A loader that throws a bare `Response` has always been passed straight through - that is how
+ * `throw redirect(...)` works, and apps rely on it. So "render the `_404` boundary at 404" cannot be
+ * expressed by throwing a plain `Response`: the framework would have no way to tell it apart from a
+ * hand-rolled body the app wants served exactly as written. The brand is that distinction, and
+ * checking it *before* the pass-through is what keeps every existing throw working unchanged.
+ *
+ * `Symbol.for` matches core's `RESPONSE_RESULT`: a registry symbol survives two copies of this module,
+ * which a `unique symbol` would not - and a duplicate-install turning a 404 into a raw 404 body would
+ * be a maddening bug to trace.
+ */
+export const STATUS_SIGNAL = Symbol.for("nifra.web.status-signal")
+
+export interface StatusSignal extends Response {
+  readonly [STATUS_SIGNAL]: { readonly status: number; readonly headers?: HeadersLike }
+}
+
+export function isStatusSignal(value: unknown): value is StatusSignal {
+  return value instanceof Response && STATUS_SIGNAL in value
+}
+
+function statusSignal(status: number, options: StatusPageOptions): never {
+  if (!Number.isInteger(status) || status < 400 || status > 599) {
+    throw new Error(
+      `[nifra/web] statusPage(${JSON.stringify(status)}) must be an integer 4xx or 5xx status. Use redirect() for 3xx, and return data for a successful render.`,
+    )
+  }
+  const response = new Response(null, { status })
+  // Non-enumerable so the brand never lands in a structured clone or a JSON log of the response.
+  Object.defineProperty(response, STATUS_SIGNAL, {
+    value: { status, ...(options.headers !== undefined ? { headers: options.headers } : {}) },
+    enumerable: false,
+  })
+  throw response
+}
+
+/** Options shared by {@link notFound}, {@link gone}, and {@link statusPage}. */
+export interface StatusPageOptions {
+  /**
+   * Extra headers for the rendered response - `cache-control` above all.
+   *
+   * The defaults differ by status for a reason: a 404 may be a race with publication, so it wants a
+   * short TTL, while a 410 is a promise that the URL is permanently gone and can be cached hard.
+   * Getting this wrong is the difference between a crawler dropping a dead URL and re-fetching it
+   * for weeks.
+   */
+  readonly headers?: HeadersLike
+}
+
+/**
+ * Render the nearest `_404` page at status **404**. `throw` it from a loader when the record does not
+ * exist.
+ *
+ * This is the fix for the soft 404: a matched route whose loader finds nothing has otherwise no way to
+ * answer 404, so the path of least resistance is to return empty data and render "not found" inside a
+ * **200**. That looks correct in a browser and is invisible in review, which is why it ships and stays
+ * shipped - while search engines penalise it and keep the dead URL indexed.
+ *
+ * Returns `never`: these throw, so a loader narrows without a redundant `return`, and the type states
+ * the thing the "loaders `throw` redirect, actions `return` it" rule already trips people on.
+ */
+export function notFound(options: StatusPageOptions = {}): never {
+  return statusSignal(404, options)
+}
+
+/**
+ * Render a terminal page at status **410 Gone**. `throw` it from a loader for a record that existed and
+ * was deliberately removed - a withdrawn listing, a deleted post.
+ *
+ * 410 is not a pedantic 404: it tells a crawler to **drop** the URL rather than re-fetch it for weeks
+ * on the assumption the 404 was transient. Uses `_410.tsx` if the app has one, otherwise `_404`.
+ */
+export function gone(options: StatusPageOptions = {}): never {
+  return statusSignal(410, options)
+}
+
+/**
+ * Render a terminal page at any 4xx/5xx status - the escape hatch behind {@link notFound} and
+ * {@link gone} (402, 451, …). Uses `_<status>.tsx` if present, otherwise `_404`.
+ */
+export function statusPage(status: number, options: StatusPageOptions = {}): never {
+  return statusSignal(status, options)
+}

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,15 @@ 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` and Auth.js count under their
+   * default names, Better Auth's under any `cookiePrefix`; name any other in `identityCookies`. An app
+   * run by `nifra dev` and `nifra build` exports this from `backend/framework.ts`. 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 +359,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 +460,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 +520,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 +596,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 +651,18 @@ 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,
+    liveSeedOf: liveAttachment?.seedOf,
   })
+  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 +677,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 +737,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) => {