@nifrajs/web 5.5.1 → 5.7.0

package/src/internal/hole-runtime.ts

@@ -0,0 +1,286 @@
+/**
+ * The browser side of a partially prerendered page's holes, shared by every adapter's `Hole`: the
+ * host's first fill from the document, and each refill a data request brings when the page on screen
+ * reloads. An adapter supplies only how an interactive hole's own root hydrates, updates and goes. A
+ * hole that shows a server component mounts the client islands inside it through the component
+ * client the app registered with `holeComponents` (`@nifrajs/web/server-components/client`).
+ */
+import type { ComponentClientAdapter, ComponentClientRoot } from "../server-components/client.ts"
+import type { ComponentRecord } from "../server-components/types.ts"
+import { onPageRelease, PAGE_HIDE_EVENT, PAGE_SHOW_EVENT } from "./page-events.ts"
+
+/** One hole's fill, as the PPR runtime keeps it. */
+export interface HoleFill {
+  readonly props?: unknown
+  readonly error: boolean
+  /** The record of the server component the hole shows, without its HTML. */
+  readonly component?: unknown
+  /** That component's HTML. */
+  readonly html?: string
+}
+
+/** The shell's inline runtime (internal/ppr/runtime.ts). */
+interface PprRuntime {
+  get(name: string): HoleFill | undefined
+  subscribe(name: string, callback: (fill: HoleFill) => void): () => void
+  put(name: string, frame: unknown, host: Element): void
+  /** Stop filling holes from the document, and cancel the ones still loading on the server. */
+  leave?(): void
+}
+
+/** The error slot a failed, timed-out or refused hole shows. Constant: no thrown message reaches it. */
+export const HOLE_ERROR_HTML = '<p data-nifra-hole-error="">This section is unavailable.</p>'
+
+const ERROR_FRAME = { v: 1, error: true, html: HOLE_ERROR_HTML } as const
+
+/** The runtime the shell's inline script defines, when this document has one. */
+const pprRuntime = (): PprRuntime | undefined => {
+  const runtime: unknown = Reflect.get(globalThis, "__nifraPpr")
+  return typeof runtime === "function" &&
+    "get" in runtime &&
+    "subscribe" in runtime &&
+    "put" in runtime
+    ? // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the shell's constant inline runtime defines exactly this shape.
+      (runtime as PprRuntime)
+    : undefined
+}
+
+/** How the islands inside a hole that shows a server component mount: the app's component client,
+ * and the protocol check the component's record passes first. */
+export interface HoleComponents {
+  readonly client: ComponentClientAdapter
+  record(value: unknown): ComponentRecord
+}
+
+let components: HoleComponents | undefined
+
+/** What `holeComponents` registers; `undefined` forgets it. */
+export function setHoleComponents(next: HoleComponents | undefined): void {
+  components = next
+}
+
+/** An interactive hole's own root, as its adapter made it. */
+export interface HoleRoot {
+  /** Render new props into the root, keeping its state; `false` when it has to be made again. */
+  update(props: unknown): boolean
+  /** `leaving`: the page is unmounting the host, so the adapter may defer the work. A promise means
+   * the host is not free until it settles. */
+  dispose(leaving: boolean): void | Promise<void>
+  /** The kept page holding the host is hidden (`true`) or shown again: a root whose framework can
+   * pause what it runs keeps its state either way. */
+  hide?(hidden: boolean): void
+}
+
+export interface HoleHost {
+  /** Apply a data request's fill once it arrives, unless a newer one is given first. Without the
+   * shell's runtime, only a server component's fill or the error slot can be put. A first fill the
+   * host was rendered with (`initialHtml`) hydrates its islands over that HTML. */
+  refill(fill: unknown): void
+  dispose(): void
+  /**
+   * For an adapter whose hidden page cleans its effects up (React's `Activity`): while a kept page
+   * hides the host, keep it, root and all, for the page's return, and dispose it only if the page is
+   * dropped. `false` when nothing hides the host, and disposing is the adapter's.
+   */
+  park(): boolean
+  /** The parked host is the adapter's again. */
+  unpark(): void
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null
+
+/** A fill the server deferred: the NDJSON stream settles its promise. */
+const settledFill = (fill: unknown): Promise<unknown> =>
+  isRecord(fill) && fill.__nifra_deferred === true && fill.promise instanceof Promise
+    ? fill.promise
+    : Promise.resolve(fill)
+
+/**
+ * What a host renders with: a blocking render's settled fill puts the server's HTML in it, which a
+ * crawler reads with no script; any other state leaves it empty. A host reads it once, so no later
+ * render changes what the runtime put there.
+ */
+export const initialHtml = (fill: unknown): string =>
+  isRecord(fill) && fill.__nifra_deferred !== true && typeof fill.html === "string" ? fill.html : ""
+
+/** The record of the server component a fill shows, its HTML put back, not yet checked. */
+const recordOf = (fill: Record<string, unknown>): Record<string, unknown> | undefined =>
+  isRecord(fill.component) && typeof fill.html === "string"
+    ? { ...fill.component, html: fill.html }
+    : undefined
+
+/** The error slot, built without HTML parsing, for a document with no runtime to put it. */
+const errorSlot = (host: Element): void => {
+  const slot = host.ownerDocument.createElement("p")
+  slot.setAttribute("data-nifra-hole-error", "")
+  slot.textContent = "This section is unavailable."
+  host.replaceChildren(slot)
+  host.setAttribute("data-nifra-hole-error", "")
+}
+
+/**
+ * The islands of the server component in `host`: hydrated over the server's HTML, or with `fresh`,
+ * put into the host from the record. `failed` runs when they cannot mount, as when the record fails
+ * the protocol check.
+ */
+function componentRoot(
+  host: Element,
+  unchecked: Record<string, unknown>,
+  fresh: boolean,
+  failed: () => void,
+): HoleRoot {
+  const registered = components
+  let current = true
+  const valid = (): boolean => current
+  const mounted: Promise<ComponentClientRoot | undefined> = (async () => {
+    if (registered === undefined) {
+      throw new Error(
+        "[nifra/web] ppr: a hole shows a server component, but no holeComponents client",
+      )
+    }
+    const { client } = registered
+    const record = registered.record(unchecked)
+    const mount = fresh ? client.create : client.hydrate
+    if (mount === undefined) throw new Error("[nifra/web] ppr: the component client cannot create")
+    const prepared = await client.prepare(record, valid, host, { records: [record] })
+    if (!current) return undefined
+    const root = await mount.call(client, host, record, prepared, valid)
+    if (!current) {
+      await root.dispose()
+      return undefined
+    }
+    host.setAttribute("aria-busy", "false")
+    return root
+  })().catch((error: unknown) => {
+    if (current) {
+      console.error("[nifra/web] ppr: a server component hole's islands did not mount", error)
+      failed()
+    }
+    return undefined
+  })
+  return {
+    update: () => false,
+    dispose() {
+      current = false
+      return mounted.then((root) => root?.dispose())
+    },
+  }
+}
+
+/**
+ * Drive the host of hole `name`. `hydrate` makes an interactive hole's root over the server HTML in
+ * `host`; a hole without one only ever shows server HTML, or a server component's.
+ */
+export function holeHost(
+  name: string,
+  host: Element,
+  hydrate: ((host: Element, props: unknown) => HoleRoot) | undefined,
+): HoleHost {
+  const runtime = pprRuntime()
+  let root: HoleRoot | undefined
+  let disposed = false
+  let latest = 0
+  // The kept page hiding the host, and what disposes the host if that page is dropped.
+  let hiddenBy: Element | undefined
+  let release: (() => void) | undefined
+  const put = (frame: Record<string, unknown>): void => {
+    if (runtime !== undefined) runtime.put(name, frame, host)
+    else errorSlot(host)
+    host.setAttribute("aria-busy", "false")
+  }
+  const showError = (): void => {
+    root = undefined
+    put(ERROR_FRAME)
+  }
+  const start = (fill: HoleFill): void => {
+    if (disposed || root !== undefined || fill.error) return
+    const record = recordOf({ component: fill.component, html: fill.html })
+    if (record !== undefined) root = componentRoot(host, record, false, showError)
+    else if (hydrate !== undefined) root = hydrate(host, fill.props)
+  }
+  const now = runtime?.get(name)
+  const unsubscribe =
+    now === undefined && (hydrate !== undefined || components !== undefined)
+      ? runtime?.subscribe(name, start)
+      : undefined
+  if (now !== undefined) start(now)
+  // A `keepAlive` page hidden behind another has been left: the document's holes stop filling and
+  // the ones still loading are cancelled, and a refill already on its way is dropped. The page's
+  // reload when it is shown again refills the host.
+  const hidden = (event: Event): void => {
+    if (!(event.target instanceof Element) || !event.target.contains(host)) return
+    hiddenBy = event.target
+    latest++
+    runtime?.leave?.()
+    root?.hide?.(true)
+  }
+  const shown = (event: Event): void => {
+    if (event.target !== hiddenBy) return
+    hiddenBy = undefined
+    root?.hide?.(false)
+  }
+  host.ownerDocument.addEventListener(PAGE_HIDE_EVENT, hidden)
+  host.ownerDocument.addEventListener(PAGE_SHOW_EVENT, shown)
+  const apply = (frame: unknown, mine: number, inPlace: boolean): void => {
+    if (!isRecord(frame)) return
+    const failed = frame.error === true
+    const record = failed ? undefined : recordOf(frame)
+    if (!failed && record === undefined && root?.update(frame.props) === true) {
+      host.setAttribute("aria-busy", "false")
+      return
+    }
+    // An error shows the error slot, never content the action that reloaded it may have changed.
+    const gone = root?.dispose(false)
+    root = undefined
+    const fill = (): void => {
+      if (disposed || mine !== latest) return
+      host.removeAttribute("data-nifra-hole-error")
+      if (record !== undefined) {
+        host.setAttribute("data-nifra-filled", "")
+        root = componentRoot(host, record, !inPlace, showError)
+        return
+      }
+      put(frame)
+      if (!failed && hydrate !== undefined) root = hydrate(host, frame.props)
+    }
+    if (gone instanceof Promise) gone.then(fill, fill)
+    else fill()
+  }
+  const dispose = (): void => {
+    disposed = true
+    release?.()
+    release = undefined
+    host.ownerDocument.removeEventListener(PAGE_HIDE_EVENT, hidden)
+    host.ownerDocument.removeEventListener(PAGE_SHOW_EVENT, shown)
+    unsubscribe?.()
+    Promise.resolve(root?.dispose(true)).catch(() => {})
+    root = undefined
+  }
+  return {
+    refill(fill) {
+      // A blocking render's settled fill is the server HTML the host already shows.
+      const inPlace = latest === 0 && root === undefined && initialHtml(fill) !== ""
+      const mine = ++latest
+      host.setAttribute("aria-busy", "true")
+      settledFill(fill).then(
+        (frame) => {
+          if (!disposed && mine === latest) apply(frame, mine, inPlace)
+        },
+        () => {
+          if (!disposed && mine === latest) apply(ERROR_FRAME, mine, false)
+        },
+      )
+    },
+    dispose,
+    park() {
+      if (disposed || hiddenBy === undefined) return false
+      release ??= onPageRelease(hiddenBy, dispose)
+      return true
+    },
+    unpark() {
+      release?.()
+      release = undefined
+    },
+  }
+}

package/src/internal/identity-epoch.ts

@@ -0,0 +1,239 @@
+/**
+ * The server half of the identity epoch: a response that signs a visitor in or out also rotates the
+ * readable epoch cookie, so every tab drops the pages it kept alive for the previous visitor.
+ *
+ * A header-only hook reads each response's `Set-Cookie`: when an identity cookie's value differs from
+ * the request's, or the cookie is deleted, the response also sets a fresh epoch with the same lifetime,
+ * so the epoch expires with an idle session. A rolling session re-sending the same value with a new
+ * lifetime re-sends the epoch it holds with that lifetime, so the two keep expiring together.
+ */
+import { type CookieOptions, parseCookies } from "@nifrajs/core/server"
+import { EPOCH_COOKIE, LOCAL_EPOCH_COOKIE } from "../identity.ts"
+
+/** `createWebApp`'s `keepAlive` option: which cookies say who is signed in. */
+export interface KeepAliveServerOptions {
+  /**
+   * Cookies whose change means a different visitor, on top of the session cookies of
+   * `@nifrajs/auth` and Auth.js under their default names and Better Auth's under any `cookiePrefix`.
+   * Name a custom session cookie here, or kept pages survive a sign-in or sign-out through it.
+   */
+  readonly identityCookies?: readonly string[]
+  /** `HttpOnly` cookies that say nothing about who is signed in; development stops asking about them. */
+  readonly ignoreCookies?: readonly string[]
+}
+
+/** The request and response a header hook sees. */
+interface HeaderView {
+  get(name: string): string | null
+  append(name: string, value: string): void
+}
+interface RequestView {
+  readonly url: string
+  header(name: string): string | null | undefined
+}
+
+// Session cookies by their default names, without a `__Secure-` / `__Host-` prefix.
+const IDENTITY_DEFAULTS = ["nifra_session", "authjs.session-token", "next-auth.session-token"]
+// `HttpOnly` cookies the same integrations write that carry no identity of their own.
+const IGNORE_DEFAULTS = [
+  "authjs.csrf-token",
+  "authjs.callback-url",
+  "authjs.pkce.code_verifier",
+  "authjs.state",
+  "authjs.nonce",
+  "next-auth.csrf-token",
+  "next-auth.callback-url",
+  "next-auth.pkce.code_verifier",
+  "next-auth.state",
+  "next-auth.nonce",
+  "__nifra_draft",
+]
+
+// Better Auth names its cookies `<advanced.cookiePrefix>.<name>`, "better-auth" unless the app sets
+// one, so these count under any prefix.
+const BETTER_AUTH_SESSION = ".session_token"
+const BETTER_AUTH_IGNORED = [".session_data", ".dont_remember"]
+
+// `__Secure-a.0` and `__Host-a` are the cookie `a`: a prefix, then Auth.js's chunk index.
+const baseName = (name: string): string =>
+  name.replace(/^__(?:secure|host)-/i, "").replace(/\.\d+$/, "")
+
+interface SetCookie {
+  readonly name: string
+  readonly value: string
+  readonly deleted: boolean
+  readonly httpOnly: boolean
+  readonly secure: boolean
+  readonly maxAge: string | undefined
+  readonly expires: string | undefined
+}
+
+// Splits a `Set-Cookie` list joined with ", ": only a comma followed by `name=` starts a cookie, so
+// the comma inside an `Expires` date stays where it is.
+const SPLIT = /,\s*(?=[!#$%&'*+\-.^_`|~0-9A-Za-z]+=)/
+
+const parseSetCookies = (joined: string, now: number): SetCookie[] => {
+  const cookies: SetCookie[] = []
+  for (const line of joined.split(SPLIT)) {
+    const [pair = "", ...attributes] = line.split(";")
+    const at = pair.indexOf("=")
+    if (at <= 0) continue
+    let maxAge: string | undefined
+    let expires: string | undefined
+    let httpOnly = false
+    let secure = false
+    for (const attribute of attributes) {
+      const eq = attribute.indexOf("=")
+      const key = (eq === -1 ? attribute : attribute.slice(0, eq)).trim().toLowerCase()
+      const value = eq === -1 ? "" : attribute.slice(eq + 1).trim()
+      if (key === "max-age") maxAge = value
+      else if (key === "expires") expires = value
+      else if (key === "httponly") httpOnly = true
+      else if (key === "secure") secure = true
+    }
+    const name = pair.slice(0, at).trim()
+    const age = maxAge === undefined ? Number.NaN : Number(maxAge)
+    const until = expires === undefined ? Number.NaN : Date.parse(expires)
+    cookies.push({
+      name,
+      // Decoded as core decodes the request's cookies, so an encoded value compares equal to itself.
+      value: parseCookies(pair.trim())[name] ?? "",
+      deleted: age <= 0 || until <= now,
+      httpOnly,
+      secure: secure || /^__(?:secure|host)-/i.test(name),
+      maxAge,
+      expires,
+    })
+  }
+  return cookies
+}
+
+const randomEpoch = (): string => {
+  const bytes = crypto.getRandomValues(new Uint8Array(16))
+  let hex = ""
+  for (const byte of bytes) hex += byte.toString(16).padStart(2, "0")
+  return hex
+}
+
+const EPOCH_VALUE = /^[0-9a-f]{32}$/
+
+// A forwarded protocol only picks the cookie's name: a client that lies about it loses its own epoch.
+// A browser sends a `__Host-` cookie only over https, so carrying one says so behind a TLS proxy that
+// forwards nothing, and the client, which reads that one first, must see the new value there.
+const servedOverHttps = (request: RequestView, sent: Readonly<Record<string, string>>): boolean => {
+  if (request.url.startsWith("https:") || sent[EPOCH_COOKIE] !== undefined) return true
+  const forwarded = request.header("x-forwarded-proto")
+  return forwarded?.split(",")[0]?.trim().toLowerCase() === "https"
+}
+
+const epochCookie = (
+  secure: boolean,
+  value: string,
+  lifetime: { readonly maxAge?: string | undefined; readonly expires?: string | undefined },
+): string => {
+  let cookie = `${secure ? EPOCH_COOKIE : LOCAL_EPOCH_COOKIE}=${value}; Path=/; SameSite=Lax`
+  if (secure) cookie += "; Secure"
+  if (lifetime.maxAge !== undefined) cookie += `; Max-Age=${lifetime.maxAge}`
+  if (lifetime.expires !== undefined) cookie += `; Expires=${lifetime.expires}`
+  return cookie
+}
+
+/**
+ * The response hook `createWebApp` installs for an app with a `keepAlive` route. With `development`,
+ * it also says once per cookie when an `HttpOnly` cookie it does not know changes.
+ */
+export function identityEpochHook(
+  options: KeepAliveServerOptions,
+  development: boolean,
+): (headers: HeaderView, request: RequestView) => void {
+  const named = new Set([...IDENTITY_DEFAULTS, ...(options.identityCookies ?? []).map(baseName)])
+  const told = new Set((options.ignoreCookies ?? []).map(baseName))
+  const ignored = new Set([...IGNORE_DEFAULTS, ...told])
+  // An app's own `ignoreCookies` entry outranks the Better Auth suffix, never a name it listed.
+  const isIdentity = (base: string): boolean =>
+    named.has(base) || (base.endsWith(BETTER_AUTH_SESSION) && !told.has(base))
+  const isIgnored = (base: string): boolean =>
+    ignored.has(base) || BETTER_AUTH_IGNORED.some((suffix) => base.endsWith(suffix))
+  const reported = new Set<string>()
+  return (headers, request) => {
+    const joined = headers.get("set-cookie")
+    if (joined === null || joined === "") return
+    const sent = parseCookies(request.header("cookie") ?? null)
+    let changed: SetCookie | undefined
+    let renewed: SetCookie | undefined
+    for (const cookie of parseSetCookies(joined, Date.now())) {
+      if (cookie.name === EPOCH_COOKIE || cookie.name === LOCAL_EPOCH_COOKIE) return
+      const now = cookie.deleted ? "" : cookie.value
+      const base = baseName(cookie.name)
+      if (now === (sent[cookie.name] ?? "")) {
+        if (
+          renewed === undefined &&
+          !cookie.deleted &&
+          (cookie.maxAge !== undefined || cookie.expires !== undefined) &&
+          isIdentity(base)
+        )
+          renewed = cookie
+        continue
+      }
+      if (isIdentity(base)) {
+        // The first identity cookie still set gives the lifetime; a sign-out deletes them all.
+        if (changed === undefined || (changed.deleted && !cookie.deleted)) changed = cookie
+        continue
+      }
+      if (!development || !cookie.httpOnly || isIgnored(base) || reported.has(base)) continue
+      reported.add(base)
+      console.warn(
+        `[nifra/web] NIFRA_KEEPALIVE_IDENTITY_COOKIE: this app keeps pages alive, and a response changed the HttpOnly cookie "${cookie.name}", which nifra does not know as a sign-in cookie. If it says who is signed in, name it in keepAlive: { identityCookies: ["${base}"] } so a sign-in or sign-out drops the pages kept for the previous visitor; if it does not, in keepAlive.ignoreCookies. An app run by \`nifra dev\` and \`nifra build\` exports keepAlive from backend/framework.ts; a server you write passes it to createWebApp.`,
+      )
+    }
+    if (changed !== undefined) {
+      headers.append(
+        "set-cookie",
+        epochCookie(
+          changed.secure || servedOverHttps(request, sent),
+          randomEpoch(),
+          changed.deleted ? {} : { maxAge: changed.maxAge, expires: changed.expires },
+        ),
+      )
+      return
+    }
+    if (renewed === undefined) return
+    const lifetime = { maxAge: renewed.maxAge, expires: renewed.expires }
+    for (const secure of [true, false]) {
+      const held = sent[secure ? EPOCH_COOKIE : LOCAL_EPOCH_COOKIE]
+      if (held === undefined || !EPOCH_VALUE.test(held)) continue
+      headers.append("set-cookie", epochCookie(secure, held, lifetime))
+      return
+    }
+    // An epoch that already expired, or was never set: a fresh one, so pages kept without one drop.
+    headers.append(
+      "set-cookie",
+      epochCookie(renewed.secure || servedOverHttps(request, sent), randomEpoch(), lifetime),
+    )
+  }
+}
+
+/** The response-cookie surface {@link rotateIdentityEpoch} needs: nifra's handler context. */
+export interface IdentityEpochContext {
+  readonly request: Request
+  readonly set: { cookie(name: string, value: string, options?: CookieOptions): void }
+}
+
+/**
+ * Rotate the identity epoch from a flow that changes who is signed in without changing a cookie
+ * `createWebApp` watches - say, a session kept server-side under a cookie whose value stays the
+ * same. Every tab then drops the pages it kept alive for the previous visitor.
+ */
+export function rotateIdentityEpoch(c: IdentityEpochContext): void {
+  const request = c.request
+  const secure = servedOverHttps(
+    { url: request.url, header: (name) => request.headers.get(name) },
+    parseCookies(request.headers.get("cookie")),
+  )
+  c.set.cookie(secure ? EPOCH_COOKIE : LOCAL_EPOCH_COOKIE, randomEpoch(), {
+    path: "/",
+    sameSite: "lax",
+    secure,
+    httpOnly: false,
+  })
+}

package/src/internal/invalidation-contract.ts

@@ -0,0 +1,35 @@
+/**
+ * The seam between `createWebApp` and a cache wrapper for an action's invalidation: types and one
+ * symbol, so an app pays for the pipeline only once something runs it.
+ */
+import type { RevalidateResult } from "./render-document.ts"
+
+export interface InvalidationOp {
+  /** Names the operation in logs; never key text. */
+  readonly id: string
+  readonly paths: readonly string[]
+  readonly tags: readonly string[]
+  readonly keys: readonly string[]
+}
+
+/** What a `createWebApp` app hands a cache wrapper that owns its invalidation. */
+export interface InvalidationHandoff {
+  /** The operation the action behind `request` recorded, once. */
+  take(request: Request): InvalidationOp | undefined
+  /** The app's live publish, when it configures `live`. */
+  readonly publish: ((keys: readonly string[]) => Promise<void>) | undefined
+}
+
+export const INVALIDATION: unique symbol = Symbol.for("nifra.web.invalidation")
+
+/** The operation an action's `revalidate()` names: its paths, cache tags and live keys. */
+export function invalidationOf(revalidation: RevalidateResult<unknown>): InvalidationOp {
+  return {
+    id: crypto.randomUUID(),
+    paths: revalidation.__nifraRevalidate.filter(
+      (path) => typeof path === "string" && path.startsWith("/"),
+    ),
+    tags: revalidation.__nifraInvalidate?.tags ?? [],
+    keys: revalidation.__nifraInvalidate?.keys ?? [],
+  }
+}