@nifrajs/web 5.5.1 → 5.6.0

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

@@ -0,0 +1,139 @@
+/**
+ * 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 { storeSigner } from "../store-signature.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"
+  )
+}
+
+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 {
+        payload = JSON.parse(cached.body)
+      } 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/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)
+}

package/src/internal/render-document.ts

@@ -24,6 +24,7 @@ import type {
   PageLocales,
   RenderAdapter,
   RenderProps,
+  RenderStreamOptions,
 } from "../render-seam.ts"
 import {
   ACTION_GLOBAL,
@@ -36,10 +37,12 @@ import {
   LOCALES_GLOBAL,
   ROOT_ATTRIBUTE,
   ROUTE_GLOBAL,
+  SWAP_HEADER,
 } from "../render-seam.ts"
 import { PRERENDERED_GLOBAL } from "../router.ts"
 import { trustedHeadAttributes } from "./head-attributes.ts"
 import { isStaticMeta, mergeHeads } from "./head-merge.ts"
+import { reportDeferredRejection } from "./request-abort.ts"
 import { PRE_HYDRATION_GUARD } from "./runtime-contract.ts"
 import { EXECUTABLE_SCRIPT_TYPES, INERT_SCRIPT_TYPES } from "./script-types.ts"
 
@@ -171,6 +174,14 @@ export interface RenderPageOptions {
   readonly matchChain?: MatchChain
   /** HTTP status for the response (default 200; e.g. 404 for a not-found page). */
   readonly status?: number
+  /**
+   * The slot an `x-nifra-swap` request names. When the adapter renders slots and nothing is
+   * deferred, the response is that slot's HTML alone; otherwise the whole document.
+   */
+  readonly swapSlot?: string
+  /** Chain indices the adapter renders inside the slot wrappers of a kept page (`keepAlive`), so the
+   * browser can keep the page this document shows without remounting it. */
+  readonly slots?: readonly number[]
   /** Extra response headers - e.g. the `cache-control` a terminal status page wants. `content-type`
    * is ignored (the document is always HTML) and the ISR freshness header is applied after these,
    * so neither can be overridden from here. */
@@ -205,6 +216,11 @@ export interface RenderPageOptions {
   /** CSP nonce applied to every framework-owned executable script in this document. Nonce-bearing
    * documents are marked `private, no-store` so a request-specific nonce is never replayed. */
   readonly nonce?: string
+  /** The request's abort signal. A deferred value that rejects because it aborted is the client
+   * leaving, not a failure, so the server log skips it. Omit ⇒ every rejection is logged. */
+  readonly signal?: AbortSignal
+  /** Where a rejected deferred value is logged: the app's error log. Omit ⇒ the console. */
+  readonly logError?: ((error: unknown) => void) | undefined
   /**
    * A hash-based Content-Security-Policy from `createCspPolicy`. The document then carries `nonce`
    * only when it needs one (it defers a value, or a head tag names the nonce); otherwise it renders
@@ -262,6 +278,18 @@ export function renderPage(options: RenderPageInput): MaybePromise<Response> {
   return page instanceof Promise ? page.then((p) => p.toResponse()) : page.toResponse()
 }
 
+// Every option of an adapter call, for a render with slot wrappers (only a keep-alive app's).
+const streamOptions = (
+  nonce: string | undefined,
+  parts: DocumentParts | undefined,
+  slots: readonly number[],
+): RenderStreamOptions => {
+  const options: { -readonly [K in keyof RenderStreamOptions]: RenderStreamOptions[K] } = { slots }
+  if (nonce !== undefined) options.nonce = nonce
+  if (parts !== undefined) options.parts = parts
+  return options
+}
+
 export function renderPageResult(options: RenderPageInput): MaybePromise<RenderedPage> {
   const { csp } = options
   if (csp !== undefined) {
@@ -512,6 +540,8 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
       if (name !== "content-type") headers[name] = value
     }
   }
+  if (adapter.renderSlot !== undefined)
+    headers.vary = headers.vary === undefined ? SWAP_HEADER : `${headers.vary}, ${SWAP_HEADER}`
   // ISR: advertise the route's freshness so a `withISR` wrapper can set this page's cache TTL. A
   // dedicated header (not the action-revalidation `x-nifra-revalidate`) so the TTL channel never aliases
   // the client's path-list channel.
@@ -551,6 +581,17 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     ...(locale === undefined ? {} : { locale }),
   }
 
+  const { swapSlot, ...documentOptions } = options
+  const slots = options.slots
+  if (swapSlot !== undefined && allDeferred.length === 0 && adapter.renderSlot !== undefined) {
+    const slotPage = (slotHtml: string | undefined): MaybePromise<RenderedPage> =>
+      slotHtml === undefined
+        ? renderPageResult(documentOptions)
+        : new BufferedRenderedPage(slotHtml, status, swapHeaders(headers, swapSlot))
+    const out = adapter.renderSlot(chain, renderProps, swapSlot)
+    return out instanceof Promise ? out.then(slotPage) : slotPage(out)
+  }
+
   // Fast path: nothing `defer()`s and the adapter can render synchronously to a string → buffer the
   // whole document in one pass. Progressive streaming only benefits pages with deferred boundaries
   // (those take the streaming path below); for a plain page the streaming pipeline + the framework's
@@ -571,6 +612,9 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
       headers,
       streamNonce,
       streamNonce === nonce ? nonceAttr : ` nonce="${escapeAttr(streamNonce ?? "")}"`,
+      options.signal,
+      options.slots,
+      options.logError,
     ).then((response) => new ResponseRenderedPage(response))
   const last = chain[chain.length - 1]
   const leaf = isWeakKey(last) ? last : undefined
@@ -596,15 +640,17 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
       return streamed(renderNonce)
     }
     const out =
-      parts !== undefined
-        ? adapter.renderToString(
-            chain,
-            renderProps,
-            renderNonce === undefined ? { parts } : { nonce: renderNonce, parts },
-          )
-        : renderNonce === undefined
-          ? adapter.renderToString(chain, renderProps)
-          : adapter.renderToString(chain, renderProps, { nonce: renderNonce })
+      slots !== undefined
+        ? adapter.renderToString(chain, renderProps, streamOptions(renderNonce, parts, slots))
+        : parts !== undefined
+          ? adapter.renderToString(
+              chain,
+              renderProps,
+              renderNonce === undefined ? { parts } : { nonce: renderNonce, parts },
+            )
+          : renderNonce === undefined
+            ? adapter.renderToString(chain, renderProps)
+            : 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`
@@ -643,6 +689,9 @@ async function renderStreamedPage(
   headers: Record<string, string>,
   nonce: string | undefined,
   nonceAttr: string,
+  signal: AbortSignal | undefined,
+  slots: readonly number[] | undefined,
+  logError: ((error: unknown) => void) | undefined,
 ): Promise<Response> {
   // Streaming path - required for `defer()` (progressive `<Await>` resolution) and used by any adapter
   // that doesn't implement `renderToString`. Awaiting `renderToStream` resolves on shell-readiness
@@ -652,21 +701,54 @@ async function renderStreamedPage(
   const closeRoot = enc.encode(closeRootHtml)
   const tail = enc.encode(tailHtml)
   const appStream =
-    parts !== undefined
-      ? await adapter.renderToStream(
-          chain,
-          renderProps,
-          nonce === undefined ? { parts } : { nonce, parts },
-        )
-      : nonce === undefined
-        ? await adapter.renderToStream(chain, renderProps)
-        : await adapter.renderToStream(chain, renderProps, { nonce })
+    slots !== undefined
+      ? await adapter.renderToStream(chain, renderProps, streamOptions(nonce, parts, slots))
+      : parts !== undefined
+        ? await adapter.renderToStream(
+            chain,
+            renderProps,
+            nonce === undefined ? { parts } : { nonce, parts },
+          )
+        : nonce === undefined
+          ? await adapter.renderToStream(chain, renderProps)
+          : await adapter.renderToStream(chain, renderProps, { nonce })
   // After the render: an adapter fills its document parts before handing back the stream.
   const shell = enc.encode(shellOf())
-  const body = streamDocument(shell, appStream, closeRoot, allDeferred, tail, enc, nonceAttr)
+  const body = streamDocument(
+    shell,
+    appStream,
+    closeRoot,
+    allDeferred,
+    tail,
+    enc,
+    nonceAttr,
+    signal,
+    logError,
+  )
   return new Response(body, { status, headers })
 }
 
+// A swap response shares its URL with the document, so like a data response it is never stored: a
+// cache keyed on the URL alone would serve one slot in place of the page. A slot joins a page that
+// already runs under its own policy, so the CSP header belongs to the document alone.
+const DOCUMENT_ONLY_HEADERS = new Set([
+  ISR_REVALIDATE_HEADER,
+  ISR_REVALIDATE_TAGS_HEADER,
+  "content-security-policy",
+])
+
+function swapHeaders(
+  document: Readonly<Record<string, string>>,
+  slot: string,
+): Record<string, string> {
+  const headers: Record<string, string> = {}
+  for (const [name, value] of Object.entries(document))
+    if (!DOCUMENT_ONLY_HEADERS.has(name)) headers[name] = value
+  headers["cache-control"] = "private, no-store"
+  headers[SWAP_HEADER] = slot
+  return headers
+}
+
 class BufferedRenderedPage implements RenderedPage {
   readonly [RESPONSE_RESULT] = true
   private readonly body: string
@@ -732,6 +814,8 @@ function streamDocument(
   tail: Uint8Array,
   enc: TextEncoder,
   nonceAttr: string,
+  signal: AbortSignal | undefined,
+  logError: ((error: unknown) => void) | undefined,
 ): ReadableStream<Uint8Array> {
   const reader = stream.getReader()
   // A client that goes away cancels the body: the renderer stops, and nothing more is written.
@@ -756,7 +840,7 @@ function streamDocument(
         // 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)
+        reportDeferredRejection(signal, err, logError)
         return `<script${nonceAttr}>window.__nifraReject(${d.id},${serializeData(DEFERRED_ERROR_CODE)})</script>`
       }),
   )
@@ -1071,6 +1155,42 @@ export function statusPage(status: number, options: StatusPageOptions = {}): nev
 export interface RevalidateResult<T> {
   readonly __nifraRevalidate: readonly string[]
   readonly data: T
+  /** What else the write made stale: cache tags and live keys. */
+  readonly __nifraInvalidate?: {
+    readonly tags: readonly string[]
+    readonly keys: readonly string[]
+  }
+}
+
+/** `value` is what {@link revalidate} returned. */
+export function isRevalidateResult(value: unknown): value is RevalidateResult<unknown> {
+  return typeof value === "object" && value !== null && "__nifraRevalidate" in value
+}
+
+/** Cache tags and live keys an action's write made stale, beside its paths. */
+export interface RevalidateOptions {
+  /** Cache tags: data caches, the page store and the CDN drop entries carrying them; live pages watching a tag as a key reload. */
+  readonly tags?: readonly string[]
+  /** Live keys (`ctx.live`): every open page watching one reloads it. */
+  readonly keys?: readonly string[]
+}
+
+const INVALIDATION_NAME = /^[A-Za-z][A-Za-z0-9._:/-]{0,127}$/
+const MAX_INVALIDATION_NAMES = 64
+
+function invalidationNames(names: readonly string[] | undefined, kind: string): readonly string[] {
+  if (names === undefined) return []
+  if (!Array.isArray(names) || names.length > MAX_INVALIDATION_NAMES) {
+    throw new TypeError(`[nifra/web] revalidate() takes at most ${MAX_INVALIDATION_NAMES} ${kind}`)
+  }
+  for (const name of names) {
+    if (typeof name !== "string" || !INVALIDATION_NAME.test(name)) {
+      throw new TypeError(
+        `[nifra/web] revalidate() ${kind} are a letter followed by up to 127 of A-Z a-z 0-9 . _ : / -`,
+      )
+    }
+  }
+  return [...new Set(names)]
 }
 
 /**
@@ -1080,8 +1200,15 @@ export interface RevalidateResult<T> {
  * so a mutation can refresh views beyond the one that was submitted. `data` is still surfaced to the
  * component as `actionData` (the wrapper is transparent to `ActionData<typeof action>`).
  */
-export function revalidate<T>(paths: readonly string[], data: T): RevalidateResult<T> {
-  return { __nifraRevalidate: paths, data }
+export function revalidate<T>(
+  paths: readonly string[],
+  data: T,
+  options?: RevalidateOptions,
+): RevalidateResult<T> {
+  if (options === undefined) return { __nifraRevalidate: paths, data }
+  const tags = invalidationNames(options.tags, "tags")
+  const keys = invalidationNames(options.keys, "keys")
+  return { __nifraRevalidate: paths, data, __nifraInvalidate: { tags, keys } }
 }
 
 /**

package/src/internal/request-abort.ts

@@ -0,0 +1,26 @@
+/** Whether `error` is a load giving up because its request was aborted - the client went away - rather
+ * than a failure: nobody reads the outcome, so there is nothing to report. */
+export function isRequestAbort(signal: AbortSignal | undefined, error: unknown): boolean {
+  return (
+    signal?.aborted === true &&
+    (error === signal.reason || (error instanceof Error && error.name === "AbortError"))
+  )
+}
+
+/** Report a deferred value's rejection to `log`, the app's error log, or to the console without
+ * one or when it throws: both callers stream an opaque error code after this, which a failing
+ * logger must not cut off. A rejection the client's leaving caused is not reported. */
+export function reportDeferredRejection(
+  signal: AbortSignal | undefined,
+  error: unknown,
+  log: ((error: unknown) => void) | undefined,
+): void {
+  if (isRequestAbort(signal, error)) return
+  if (log !== undefined) {
+    try {
+      log(error)
+      return
+    } catch {}
+  }
+  console.error("[nifra/web] deferred value rejected:", error)
+}

package/src/internal/server-boundary.ts

@@ -12,6 +12,8 @@
 
 /** Modules whose exports become client stubs: `todos.fn.ts`, `x.fn.mjs`, or the extensionless `foo.fn`. */
 export const SERVER_FN_MODULE = /\.fn(\.[cm]?[jt]sx?)?$/
+/** A server-function namespace: lowercase, dot/dash separated, so a mount cannot invent a path. */
+export const SERVER_FN_NAMESPACE = /^[a-z0-9]+(?:[-.][a-z0-9]+)*$/
 
 import { jsStringLiteral } from "./js-string.ts"
 import { DATE_TAG, REVIVE_DATES_SOURCE } from "./revive-dates.ts"
@@ -105,7 +107,14 @@ function stringEnd(source: string, start: number): number {
  */
 export function serverFnNamespace(filePath: string): string {
   const base = filePath.replaceAll("\\", "/").split("/").pop() ?? ""
-  return base.replace(SERVER_FN_MODULE, "")
+  const namespace = base.replace(SERVER_FN_MODULE, "")
+  // `serverFunctions()` refuses this namespace, so a stub calling it could never reach a function.
+  if (!SERVER_FN_NAMESPACE.test(namespace)) {
+    throw new Error(
+      `[nifra/fn] ${base} names the server-function namespace ${JSON.stringify(namespace)}, which serverFunctions() refuses - name the file in lowercase dot/dash segments (todo-items.fn.ts).`,
+    )
+  }
+  return namespace
 }
 
 /** The server functions a module declares, in source order. */