@nifrajs/web 5.5.1 → 5.7.0

package/src/internal/ppr/shell-store.ts

@@ -0,0 +1,152 @@
+/**
+ * Shells and shared hole frames in a store shared by processes (Workers KV, Redis): a second level
+ * behind the in-process map. Whoever can write the store could put script into every visitor's page,
+ * so each entry is signed with the app's secret over its key, deployment and contents; anything that
+ * fails the check is a miss.
+ */
+import type { CachedResponse, CacheStore } from "../../isr.ts"
+import { DATE_TAG } from "../revive-dates.ts"
+import { storeSigner } from "../store-signature.ts"
+import { wireDate } from "../wire-date.ts"
+
+/** A shell or a shared hole's frame as the shared store holds it: everything a process needs to
+ * serve it. */
+export interface StoredEntry {
+  readonly routeId: string
+  /** A shell's document up to the request script's end, with room for the token at `tokenAt`
+   * (bytes); or a hole's frame. */
+  readonly html: string
+  readonly tokenAt: number
+  readonly data: unknown
+  readonly builtAt: number
+  readonly tags: readonly string[]
+  /** A shared hole's live keys. */
+  readonly keys?: readonly string[]
+  /** The shell loader's `notFound()`. */
+  readonly notFound: boolean
+}
+
+export interface SharedShellStore {
+  get(key: string): Promise<StoredEntry | undefined>
+  /** Skipped by the store when the key or one of its tags was purged after `fence`. */
+  set(
+    key: string,
+    entry: StoredEntry,
+    keepSeconds: number,
+    fence: number | undefined,
+  ): Promise<void>
+  fence(): Promise<number | undefined>
+  /** Absent when the store cannot drop entries by tag. */
+  readonly invalidateTag: ((tag: string) => Promise<void>) | undefined
+}
+
+const MAC_HEADER = "x-nifra-ppr-mac"
+
+const isStrings = (value: unknown): value is readonly string[] =>
+  Array.isArray(value) && value.every((item) => typeof item === "string")
+
+const field = (value: object, name: string): unknown => Reflect.get(value, name)
+
+const isStoredEntry = (value: unknown): value is StoredEntry => {
+  if (typeof value !== "object" || value === null) return false
+  const tokenAt = field(value, "tokenAt")
+  const keys = field(value, "keys")
+  return (
+    typeof field(value, "routeId") === "string" &&
+    typeof field(value, "html") === "string" &&
+    typeof tokenAt === "number" &&
+    Number.isSafeInteger(tokenAt) &&
+    typeof field(value, "builtAt") === "number" &&
+    isStrings(field(value, "tags")) &&
+    (keys === undefined || isStrings(keys)) &&
+    typeof field(value, "notFound") === "boolean"
+  )
+}
+
+/** Read and write signed deployment-scoped PPR entries, treating malformed data as cache misses. */
+export function sharedShellStore(
+  store: CacheStore,
+  secret: string,
+  deployment: string,
+): SharedShellStore {
+  const signer = storeSigner(secret)
+  const invalidateTag = store.invalidateTag
+  return {
+    async get(entryKey) {
+      const cached = await store.get(entryKey)
+      if (cached === undefined) return undefined
+      // One part, where ISR signs two: under a shared secret neither entry verifies as the other.
+      if (!(await signer.verify([cached.body], cached.headers[MAC_HEADER]))) {
+        console.error("[nifra/web] ppr: a shared store entry failed its signature check", {
+          key: entryKey,
+        })
+        return undefined
+      }
+      let payload: unknown
+      try {
+        // Match page-data revival, but keep the server's tagged toJSON for subsequent responses.
+        // JSON.parse defines own properties (including __proto__) without invoking setters.
+        payload = JSON.parse(cached.body, (_key, value: unknown) => {
+          if (typeof value !== "object" || value === null) return value
+          const tagged: unknown = Reflect.get(value, DATE_TAG)
+          if (typeof tagged !== "string" || Object.keys(value).length !== 1) return value
+          const time = Date.parse(tagged)
+          // An invalid wireDate would throw later from toJSON, outside this cache-miss boundary.
+          if (!Number.isFinite(time)) throw new RangeError("invalid cached date tag")
+          return wireDate(time)
+        })
+      } catch {
+        return undefined
+      }
+      if (typeof payload !== "object" || payload === null) return undefined
+      // The key and deployment are signed too, so an entry copied to another key or kept from
+      // another deployment never verifies as this one.
+      if (
+        field(payload, "v") !== 1 ||
+        field(payload, "key") !== entryKey ||
+        field(payload, "deployment") !== deployment
+      ) {
+        return undefined
+      }
+      const entry = field(payload, "entry")
+      return isStoredEntry(entry) ? entry : undefined
+    },
+    async set(entryKey, entry, keepSeconds, fence) {
+      const body = JSON.stringify({ v: 1, key: entryKey, deployment, entry })
+      const mac = await signer.sign([body])
+      const value: CachedResponse = {
+        body,
+        status: entry.notFound ? 404 : 200,
+        headers: { [MAC_HEADER]: mac },
+        storedAt: entry.builtAt,
+        revalidate: keepSeconds * 1000,
+        tags: entry.tags,
+        fence,
+      }
+      await store.set(entryKey, value)
+    },
+    async fence() {
+      return store.fence === undefined ? undefined : await store.fence()
+    },
+    invalidateTag:
+      invalidateTag === undefined ? undefined : (tag) => invalidateTag.call(store, tag),
+  }
+}
+
+/**
+ * A short, stable digest of `text` (FNV-1a, 64 bits as hex). It names a deployment inside cache keys;
+ * nothing an attacker controls goes into it, so it needs no collision resistance.
+ */
+export function digest(text: string): string {
+  let high = 0xcbf29ce4
+  let low = 0x84222325
+  for (let at = 0; at < text.length; at++) {
+    low = (low ^ text.charCodeAt(at)) >>> 0
+    // Multiply the 64-bit value by the FNV prime 0x100000001b3 in two 32-bit halves.
+    const lowProduct = low * 0x1b3
+    const carry = Math.floor(lowProduct / 0x100000000)
+    high = (high * 0x1b3 + low * 0x100 + carry) >>> 0
+    low = lowProduct >>> 0
+  }
+  return high.toString(16).padStart(8, "0") + low.toString(16).padStart(8, "0")
+}

package/src/internal/prerendered-pages.ts

@@ -1,5 +1,6 @@
 import { pathnameOf } from "@nifrajs/core/server"
 import { isDraftEnabled } from "../draft.ts"
+import { SWAP_HEADER } from "../render-seam.ts"
 import { DATA_HEADER } from "../router.ts"
 
 /**
@@ -21,10 +22,11 @@ const REPLAYED = [
   "content-language",
   "content-security-policy",
   "content-security-policy-report-only",
+  "vary",
 ]
-// Vary values a file still answers correctly: compression is negotiated by the host, and a data request
-// never reaches the file.
-const STATIC_VARY = new Set(["accept-encoding", DATA_HEADER])
+// Vary values a file still answers correctly: compression is negotiated by the host, and a data or
+// slot-swap request never reaches the file.
+const STATIC_VARY = new Set(["accept-encoding", DATA_HEADER, SWAP_HEADER])
 
 /**
  * The headers a self-hosted server replays with a prerendered page, or `undefined` when its build-time
@@ -84,7 +86,7 @@ export function servablePrerenderedPages(
 /**
  * Wrap a page route's GET handler so a plain document request for a prerendered path is answered from
  * its file. Anything a file cannot answer the way a render would renders on demand: a query string, a
- * navigation data or component request, a draft-mode visitor, or a file the reader cannot return.
+ * navigation data, component or slot-swap request, a draft-mode visitor, or a file the reader cannot return.
  */
 export function servePrerenderedPages(
   prerendered: PrerenderedPages,
@@ -102,6 +104,7 @@ export function servePrerenderedPages(
       req.url.includes("?") ||
       req.headers.has(DATA_HEADER) ||
       req.headers.has("x-nifra-component") ||
+      req.headers.has(SWAP_HEADER) ||
       (draftSecret !== undefined && (await isDraftEnabled(req, draftSecret)))
     ) {
       return render(c)

package/src/internal/present.ts

@@ -0,0 +1,20 @@
+/**
+ * How a client navigation's page swap reaches the screen. The router loads a page first and hands only
+ * the swap here, so the history layer can wrap the swap alone in a view transition rather than the
+ * whole load. Module-scoped: one app per page; unset on the server and without `installHistory`.
+ */
+export type Presenter = (swap: () => void) => Promise<void>
+
+let presenter: Presenter | undefined
+
+/** Set (or clear, with `undefined`) the presenter - called by `installHistory`. */
+export function setPresenter(next: Presenter | undefined): void {
+  presenter = next
+}
+
+/** Run `swap` through the presenter, or at once when none is set. */
+export function present(swap: () => void): Promise<void> | undefined {
+  if (presenter !== undefined) return presenter(swap)
+  swap()
+  return undefined
+}

package/src/internal/query-digest.ts

@@ -0,0 +1,34 @@
+/**
+ * The digest a live load gives each granted key for query hooks: HMAC-SHA-256 under a salt fresh per
+ * load, the first 16 bytes in base64url. A page's queries name the keys they read and find the load's
+ * tag for each one without the load ever sending key text. Shared by the server and the browser.
+ */
+
+const TEXT = new TextEncoder()
+const DIGEST_BYTES = 16
+const SALT_BYTES = 16
+
+export function querySalt(): string {
+  return base64url(crypto.getRandomValues(new Uint8Array(SALT_BYTES)))
+}
+
+/** Digests keys under one salt, importing the salt once. */
+export async function queryDigester(salt: string): Promise<(key: string) => Promise<string>> {
+  const secret = await crypto.subtle.importKey(
+    "raw",
+    TEXT.encode(salt),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  )
+  return async (key) =>
+    base64url(
+      new Uint8Array(await crypto.subtle.sign("HMAC", secret, TEXT.encode(key)), 0, DIGEST_BYTES),
+    )
+}
+
+function base64url(bytes: Uint8Array): string {
+  let binary = ""
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
+}

package/src/internal/query-runtime.ts

@@ -1,4 +1,4 @@
-import type { QueryClient, QueryState } from "../query.ts"
+import type { QueryClient, QueryHandle, QueryState } from "../query.ts"
 import { createQueryClient } from "../query.ts"
 
 /** Stable idle state shared by every framework query binding. */
@@ -23,6 +23,19 @@ export function getQueryClientSingleton(): QueryClient | undefined {
   return singleton
 }
 
+export const noop = (): void => {}
+
+/** Stable no-op subscription for a binding with no client (server, pre-hydration). */
+export const noopSubscribe = (): (() => void) => noop
+
+/** A binding's fetch on mount. A failed fetch shows as the query's `error`, so its promise is let go. */
+export const fetchOnMount = (handle: QueryHandle<unknown> | undefined): (() => void) =>
+  handle === undefined
+    ? noop
+    : () => {
+        handle.fetch().catch(noop)
+      }
+
 /** Create the refetch fallback used when a binding has no client-side query cache. */
 export function createNoClientRefetch<T>(tag: string, operation: string): () => Promise<T> {
   return async () => {

package/src/internal/query-seam.ts

@@ -0,0 +1,48 @@
+/**
+ * What a query client tells the live client. `@nifrajs/web/live-client` installs the seam; a page
+ * without live refresh never does, so its queries keep no live state and ship none of it.
+ */
+import type { QueryClient } from "../query.ts"
+
+export interface LiveQuery {
+  /** The live keys its data depends on, as the page's loaders declare them. */
+  keys(): readonly string[]
+  /** The {@link QuerySeam.tick} its data was asked for at: the start of the fetch in flight, else of
+   * the fetch that produced it. */
+  tick(): number
+  /** Drop its data's freshness and refetch, superseding a fetch in flight. */
+  refresh(): void
+}
+
+export interface QuerySeam {
+  /** The live tick now, read as each fetch starts. */
+  tick(): number
+  /** A query was mounted or unmounted; only a mounted one with live keys is watched. */
+  track(query: LiveQuery, mounted: boolean): void
+}
+
+// On the global, so a query engine and a live client from two copies of the package still meet.
+const SEAM = Symbol.for("nifra.web.querySeam")
+const CLIENTS = Symbol.for("nifra.web.queryClients")
+
+export const querySeam = (): QuerySeam | undefined => Reflect.get(globalThis, SEAM)
+
+export function installQuerySeam(seam: QuerySeam): void {
+  if (querySeam() === undefined) Reflect.set(globalThis, SEAM, seam)
+}
+
+/**
+ * The browser query clients the page made, held weakly: a viewer switch clears each one still alive,
+ * whether it was made before or after the live client loaded.
+ */
+export const queryClients = (): readonly WeakRef<QueryClient>[] =>
+  Reflect.get(globalThis, CLIENTS) ?? []
+
+export function adoptClient(client: QueryClient): void {
+  // A server builds a client per request; none of them outlives it or sees a viewer switch.
+  if (typeof Reflect.get(globalThis, "window") === "undefined") return
+  // Each new client sheds the ones the page let go, so the list never outgrows the live clients.
+  const clients = queryClients().filter((ref) => ref.deref() !== undefined)
+  clients.push(new WeakRef(client))
+  Reflect.set(globalThis, CLIENTS, clients)
+}