@ultimat3/render 27.6.1 → 27.8.0

package/src/revalidate-shape.ts

@@ -0,0 +1,100 @@
+/**
+ * The invariants of `revalidate`'s keys beyond "it has a trigger": `onInvalidate`, `maxStale` and
+ * `query`, checked where `modes.ts` checks the trigger, and `tags` as purge keys, checked where
+ * the registry knows the file. Each is a declaration the ISR controller acts on per request, so
+ * one it cannot act on is refused up front, with the edit, rather than read as its permissive
+ * default for the life of the process.
+ */
+
+import type { CacheTag } from '@ultimat3/cache';
+import { serializeTag, surrogateKeys } from '@ultimat3/cache';
+import { isUltimateError, renderCauseValue, renderFixLiteral } from '@ultimat3/core';
+import { parseStaleMs, parseTtlMs } from './duration';
+import { RouteModeInvalidError } from './errors';
+import type { RevalidateConfig } from './route';
+import { INVALIDATE_MODES } from './route';
+
+/** The framework's own key dimensions ride in parameters spelled this way (`ISR_LOCALE_PARAM`). */
+const RESERVED_QUERY_PREFIX = '__x_';
+
+export function assertRevalidateShape(revalidate: RevalidateConfig): void {
+  const { onInvalidate, maxStale, query } = revalidate;
+  if (onInvalidate !== undefined && !INVALIDATE_MODES.includes(onInvalidate)) {
+    throw new RouteModeInvalidError(
+      `revalidate.onInvalidate: ${renderCauseValue(onInvalidate)} is not an invalidation mode`,
+      `onInvalidate: '${INVALIDATE_MODES.join("' | '")}'`,
+    );
+  }
+  if (onInvalidate === 'purge' && (revalidate.tags === undefined || revalidate.tags.length === 0)) {
+    throw new RouteModeInvalidError(
+      "revalidate.onInvalidate: 'purge' deletes a page when one of its tags is busted, but revalidate declares no tags",
+      "revalidate: { tags: [tag.post], onInvalidate: 'purge' }   // or drop onInvalidate",
+    );
+  }
+  // The purge reaches a replica through the invalidation broadcast, and a broadcast can be lost.
+  // The ttl is what bounds the copy on a replica that never heard it; with none, that copy is
+  // the withdrawn page for the life of the process.
+  if (onInvalidate === 'purge' && parseTtlMs(revalidate.ttl) === null) {
+    throw new RouteModeInvalidError(
+      "revalidate.onInvalidate: 'purge' needs a ttl: a replica that misses the purge serves its copy until the ttl, and a tag-only page has none",
+      "revalidate: { tags: [tag.post], ttl: '10m', onInvalidate: 'purge' }   // the ttl is the longest a missed purge can last",
+    );
+  }
+  if (maxStale !== undefined) {
+    if (parseStaleMs(maxStale) === null) {
+      throw new RouteModeInvalidError(
+        `revalidate.maxStale: ${renderCauseValue(maxStale)} is not a duration`,
+        "maxStale: '1h'   // '30s', '5m', '7d', a number of milliseconds, or 0 for never",
+      );
+    }
+    // It is counted from the TTL's expiry, and a tag-only page has no clock to count from.
+    if (parseTtlMs(revalidate.ttl) === null) {
+      throw new RouteModeInvalidError(
+        'revalidate.maxStale bounds how long past its ttl a page is served stale, but revalidate declares no ttl',
+        "revalidate: { ttl: '10m', maxStale: '1h' }   // maxStale counts from the ttl's expiry",
+      );
+    }
+  }
+  if (query === undefined) return;
+  if (!Array.isArray(query)) {
+    throw new RouteModeInvalidError(
+      `revalidate.query: ${renderCauseValue(query)} is not a list of parameter names`,
+      "query: ['page']   // or [] for a page that varies on no parameter",
+    );
+  }
+  for (const name of query) {
+    if (typeof name !== 'string' || name === '') {
+      throw new RouteModeInvalidError(
+        `revalidate.query names ${renderCauseValue(name)}, which is not a query parameter name`,
+        "query: ['page']   // each parameter the page varies on, as a non-empty string",
+      );
+    }
+    if (name.startsWith(RESERVED_QUERY_PREFIX)) {
+      throw new RouteModeInvalidError(
+        `revalidate.query names ${renderCauseValue(name)}, and ${RESERVED_QUERY_PREFIX}* is the framework's own part of a stored page's key`,
+        `query: ['page']   // rename it: a name starting with ${RESERVED_QUERY_PREFIX} is never the app's`,
+      );
+    }
+  }
+}
+
+/**
+ * A `revalidate.tags` entry goes out as a purge key on every response of the route
+ * (`render-isr.ts`), so one a CDN would split is refused at registration, naming the file. Asked of
+ * `@ultimat3/cache`'s own screen rather than restated: found at serve time it is a 500 on a
+ * public page, found at purge time it is a document nothing can clear.
+ */
+export function assertPurgeableTags(file: string, tags: readonly CacheTag[] | undefined): void {
+  for (const owned of tags ?? []) {
+    try {
+      surrogateKeys([owned], file);
+    } catch (error) {
+      if (!isUltimateError(error) || error.code !== 'X_CACHE_PURGE_FAILED') throw error;
+      const wire = renderFixLiteral(serializeTag(owned), '<the tag>');
+      throw new RouteModeInvalidError(
+        `${file} declares revalidate tag ${wire}, which cannot be a CDN purge key — a key is split on whitespace and commas and capped at 1024 bytes, so every response of the route would carry one no purge can name`,
+        `edit revalidate.tags in ${file}: replace ${wire} with a tag whose entity and id carry no whitespace or comma`,
+      );
+    }
+  }
+}

package/src/route-status.ts

@@ -68,5 +68,26 @@ export function routeStatusOf(data: unknown): number {
   return status === undefined ? DEFAULT_ROUTE_STATUS : status;
 }
 
+const UNSTORED = new WeakSet<object>();
+
+/**
+ * "Do not keep this answer": the loader's own word that this render is for this request only — a
+ * preview, a page built from a read that came back degraded. Rides on the data by identity, as
+ * `withStatus` does, and composes with it: `noStore(withStatus(404, data))`.
+ *
+ * Read by `isr`, the one mode that keeps a document: the page is served `private, no-store` and
+ * never written to the store, and a stored copy of it is dropped. A 5xx needs no mark — `isr`
+ * never stores one. `isr` only: an `ssr` page's cache is its route's `cache` key (`'no-store'`),
+ * decided per route because the document's principal scope is decided with it.
+ */
+export function noStore<TData extends object>(data: TData): TData {
+  UNSTORED.add(data);
+  return data;
+}
+
+/** Whether `noStore` marked this data. TOTAL over `unknown`, as `routeStatusOf` is. */
+export const routeNoStoreOf = (data: unknown): boolean =>
+  canCarryStatus(data) && UNSTORED.has(data);
+
 /** A 4xx or 5xx: a document a crawler must forget, whatever its `meta` said. */
 export const isErrorStatus = (status: number): boolean => status >= 400;

package/src/route.ts

@@ -43,11 +43,40 @@ export const DEFAULT_ISLAND_HYDRATE: HydrateStrategy = 'interaction';
 export type RouteParams = Readonly<Record<string, string>>;
 export type RouteData = Readonly<Record<string, unknown>>;
 
+/**
+ * What a tag bust does to a stored `isr` page. `'stale'` keeps the copy and answers it once more
+ * while a fresh one renders behind the request; `'purge'` deletes it, on every replica, so the
+ * next request renders and waits — for a page that must come DOWN, not merely catch up.
+ */
+export type InvalidateMode = 'stale' | 'purge';
+
+export const INVALIDATE_MODES: readonly InvalidateMode[] = ['stale', 'purge'];
+
 /** ISR trigger. At least one of `tags` / `ttl` is required by `modes.ts`. */
 export interface RevalidateConfig {
   readonly tags?: readonly CacheTag[];
   /** `'5m'`, `'1h'`, `'7d'` or milliseconds. */
   readonly ttl?: string | number;
+  /**
+   * `'stale'` when omitted. `'purge'` needs `tags` (what it purges by) and a `ttl` (what bounds a
+   * replica the purge never reached), and serves nothing stale past that ttl unless `maxStale` says so.
+   */
+  readonly onInvalidate?: InvalidateMode;
+  /**
+   * How long PAST its `ttl` a stored page may still be answered stale — `'1h'`, milliseconds, or
+   * `0` for never. Older than that, it is rendered again and the request waits. Omitted, there is
+   * no bound (a page nobody asked for in a week answers its next visitor once with last week's
+   * document) — except under `onInvalidate: 'purge'`, where omitted is `0`.
+   */
+  readonly maxStale?: string | number;
+  /**
+   * The query parameters this page varies on. ONLY these are part of the stored page's key and
+   * of the `url` / `query` that `load`, `meta` and the page are given; every other parameter is
+   * dropped before either, so `?utm_source=…` is the same stored page and no visitor can mint one.
+   * `[]` is "none", and what most pages want. OMITTED, the key is the whole query string — any
+   * visitor can then mint stored pages (`x verify` says so) — until the next major makes it `[]`.
+   */
+  readonly query?: readonly string[];
 }
 
 /**

package/src/server.ts

@@ -39,22 +39,30 @@ export {
 // ---- the render pipeline: one entry point per mode ----------------------------------------------
 export type { RenderHtmlOptions } from './render-html';
 export { ROOT_ELEMENT_ID, renderComponent, renderToHtml } from './render-html';
-export type {
-  IsrController,
-  IsrControllerOptions,
-  IsrRendered,
-  IsrRenderFn,
-  IsrServeResult,
-} from './render-isr';
+
 export {
   DEFAULT_ISR_REGENERATE_DEADLINE_MS,
-  ISR_LOCALE_PARAM,
   invalidateAndRevalidate,
   isrController,
-  isrKey,
 } from './render-isr';
-export type { IsrEntry, IsrState, IsrStore, MemoryIsrStoreOptions } from './render-isr-store';
+export { DEFAULT_ISR_FAILURE_COOLDOWN_MS } from './render-isr-cooldown';
+export { ISR_LOCALE_PARAM, isrKey, isrRequestUrl, undeclaredQuery } from './render-isr-key';
+export type {
+  IsrEntry,
+  IsrState,
+  IsrStore,
+  IsrTagFence,
+  MemoryIsrStoreOptions,
+} from './render-isr-store';
 export { DEFAULT_ISR_MAX_ENTRIES, memoryIsrStore } from './render-isr-store';
+export type {
+  IsrController,
+  IsrControllerOptions,
+  IsrFence,
+  IsrRendered,
+  IsrRenderFn,
+  IsrServeResult,
+} from './render-isr-types';
 export type { SsrOptions, SsrRenderFn, SsrRenderInput } from './render-ssr';
 export { renderSsr, ssrHeaders } from './render-ssr';
 export type { StaticArtifact, StaticBuildOptions, StaticRenderFn } from './render-static';