@ultimat3/render 27.7.0 → 27.8.1

package/src/render-isr-store.ts

@@ -30,7 +30,34 @@ export interface IsrEntry {
   readonly status?: number;
 }
 
+/**
+ * A fence the STORE holds, for a store more than one process writes. A process's own fence
+ * (`@ultimat3/cache`'s) only knows the busts that process heard: a replica that began a render
+ * before a purge, and has not yet been told of it, would write the purged page straight back —
+ * and with the bus down it stayed for the page's whole `ttl`. So the purge moves a generation in
+ * the store itself, and a write that read an older one is refused there.
+ *
+ * Keyed by tag ENTITY (`post` for `post` and `post:1` alike), which is coarser than a tag and
+ * errs the safe way: an unrelated row's bust refuses a write, and the next request renders again.
+ * A custom store implements all three over its own backend; `setIfCurrent` must be ATOMIC there
+ * (a transaction, a Lua script, a conditional put) — a read-then-write is the race over again.
+ */
+export interface IsrTagFence {
+  /** An opaque reading of these entities' generations, taken before a render reads its rows. */
+  sample(entities: readonly string[]): string;
+  /** A bust of these entities happened: every reading taken before this call is void. */
+  bump(entities: readonly string[]): void;
+  /** `set(entry)` only while `sampled` is still the reading. `false`: refused, nothing written. */
+  setIfCurrent(entry: IsrEntry, entities: readonly string[], sampled: string): boolean;
+}
+
 export interface IsrStore {
+  /**
+   * Present on a store that is safe to SHARE between processes under `onInvalidate: 'purge'`.
+   * `memoryIsrStore` has it. A store handed to the boot without one is refused there when any
+   * route purges (`X_ROUTE_MODE_INVALID`), rather than left to re-fill a purged page in silence.
+   */
+  readonly tagFence?: IsrTagFence;
   get(path: string): IsrEntry | undefined;
   set(entry: IsrEntry): void;
   /**
@@ -66,19 +93,36 @@ export function memoryIsrStore(options: MemoryIsrStoreOptions = {}): IsrStore {
     options.maxEntries ?? DEFAULT_ISR_MAX_ENTRIES,
   );
   const map = new Map<string, IsrEntry>();
+  // One counter per tag entity ever busted — bounded by the entities an app declares.
+  const generations = new Map<string, number>();
+  const reading = (entities: readonly string[]): string =>
+    entities.map((entity) => String(generations.get(entity) ?? 0)).join(',');
+  const set = (entry: IsrEntry): void => {
+    // Re-inserted rather than overwritten, so the Map's iteration order IS generation order and
+    // the first key is the least recently generated page.
+    map.delete(entry.path);
+    map.set(entry.path, entry);
+    while (map.size > maxEntries) {
+      const oldest = map.keys().next();
+      if (oldest.done === true) break;
+      map.delete(oldest.value);
+    }
+  };
   return {
-    get: (path) => map.get(path),
-    set: (entry) => {
-      // Re-inserted rather than overwritten, so the Map's iteration order IS generation order and
-      // the first key is the least recently generated page.
-      map.delete(entry.path);
-      map.set(entry.path, entry);
-      while (map.size > maxEntries) {
-        const oldest = map.keys().next();
-        if (oldest.done === true) break;
-        map.delete(oldest.value);
-      }
+    tagFence: {
+      sample: reading,
+      bump: (entities) => {
+        for (const entity of entities) generations.set(entity, (generations.get(entity) ?? 0) + 1);
+      },
+      // One synchronous step in one process, so the compare and the write cannot be interleaved.
+      setIfCurrent: (entry, entities, sampled) => {
+        if (reading(entities) !== sampled) return false;
+        set(entry);
+        return true;
+      },
     },
+    get: (path) => map.get(path),
+    set,
     // In place: `map.set` on a key the Map already holds keeps its position, and that position is
     // the eviction order. Never `delete` + `set` here — that is the bug this method exists to fix.
     markStale: (path) => {

package/src/render-isr-types.ts

@@ -0,0 +1,102 @@
+/**
+ * The ISR controller's contract: what a render hands it, what a request gets back, what it can be
+ * built with and what it offers. Declarations only — `render-isr.ts` is the controller.
+ */
+
+import type { CacheFence, CacheTag, FenceScope } from '@ultimat3/cache';
+import type { Scheduler } from '@ultimat3/core';
+import type { RouteDescriptor } from './registry';
+import type { IsrEntry, IsrState, IsrStore } from './render-isr-store';
+import type { RenderResult } from './route';
+
+/**
+ * A render that also answers a status — what a loader's `withStatus(404, …)` becomes once the
+ * document is built. A bare string is the 200 every render before this one was: the union is
+ * additive, and a render function that never learned the object shape keeps compiling.
+ */
+export interface IsrRendered {
+  readonly html: string;
+  readonly status: number;
+  /**
+   * The render's own "do not keep this answer" — what a loader's `noStore(data)` becomes. Served to
+   * the request that asked, `private, no-store`, and never written to the store. A 5xx needs no
+   * flag: it is never stored whatever this says.
+   */
+  readonly noStore?: boolean;
+}
+
+/** One regeneration's outcome: the entry it rendered, and whether that entry was kept. */
+export interface Generation {
+  readonly entry: IsrEntry;
+  readonly cacheable: boolean;
+  /**
+   * A page that WOULD have been kept, refused because something invalidated it while it rendered.
+   * The request that led the render predates that and is answered it, uncached; a request that
+   * merely joined may have arrived after, so it renders for itself (`serve`).
+   */
+  readonly fenced: boolean;
+}
+
+/**
+ * The process fence a controller samples and marks — `@ultimat3/cache`'s, by default. A seam so
+ * two controllers in one test can stand for two PROCESSES: sharing the real one made every
+ * shared-store test pass on a fence two replicas never share.
+ */
+export interface IsrFence {
+  sample(scope: FenceScope): CacheFence;
+  mark(scope: FenceScope): void;
+}
+
+export type IsrRenderFn = (path: string) => string | IsrRendered | Promise<string | IsrRendered>;
+
+export interface IsrServeResult {
+  readonly state: IsrState;
+  readonly entry: IsrEntry;
+  readonly result: RenderResult;
+  /** True when this request started a background regeneration. */
+  readonly regenerating: boolean;
+}
+
+export interface IsrControllerOptions {
+  readonly store?: IsrStore;
+  readonly buildId?: string;
+  readonly now?: () => number;
+  /** Route table provider — defaults to the real registry. */
+  readonly routes?: () => readonly RouteDescriptor[];
+  /** ISR-route dependents for a tag set; defaults to `@ultimat3/cache`'s graph. */
+  readonly isrDependents?: (tags: readonly CacheTag[]) => readonly string[];
+  /**
+   * How long one regeneration may hold its path, in whole ms (≥ 1). Defaults to
+   * `DEFAULT_ISR_REGENERATE_DEADLINE_MS`. There is no "forever": that is the bug it bounds.
+   */
+  readonly regenerateDeadlineMs?: number | undefined;
+  /** Injected so the deadline is provable without waiting one out. */
+  readonly schedule?: Scheduler | undefined;
+  /** See `IsrFence`. Defaults to the process's own. */
+  readonly fence?: IsrFence | undefined;
+  /**
+   * How long a 5xx render answers the requests behind it instead of each rendering again, in
+   * whole ms. Defaults to `DEFAULT_ISR_FAILURE_COOLDOWN_MS`; `0` renders on every request.
+   */
+  readonly failureCooldownMs?: number | undefined;
+}
+
+export interface IsrController {
+  serve(path: string, render: IsrRenderFn): Promise<IsrServeResult>;
+  /** Single-flight: concurrent callers for the same path share one render. */
+  regenerate(path: string, render: IsrRenderFn): Promise<IsrEntry>;
+  markStale(path: string): boolean;
+  /**
+   * Invalidate every ISR page carrying one of these tags — the ones the cache graph knows AND the
+   * ones only the store holds — as each page's route declared: marked stale, or purged.
+   */
+  revalidateByTags(tags: readonly CacheTag[]): readonly string[];
+  inflight(): number;
+  store(): IsrStore;
+  /**
+   * Register this controller as the framework's revalidator, so
+   * `action({ cache: { invalidates: [tag.post] } })` reaches ISR in the same hop as
+   * memo, LRU, Redis and the CDN. Returns a detach function for tests and reloads.
+   */
+  attach(): () => void;
+}