@rangojs/router 0.21.0 → 0.22.0

package/src/prerender/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Public on-demand prerender surface (`@rangojs/router/prerender`).
+ *
+ * Store contracts, config/result/target types, and the in-memory store (usable
+ * as a durable overlay in single-process node/Vercel functions, and as a test
+ * fake). The Cloudflare KV adapter lives in `@rangojs/router/prerender/cloudflare`.
+ */
+
+export { PrerenderError } from "./create-prerender-trigger.js";
+
+export {
+  createMemoryPrerenderStore,
+  type MemoryPrerenderStore,
+  type MemoryPrerenderStoreOptions,
+} from "./memory-prerender-store.js";
+
+export {
+  serializePrerenderKey,
+  type PrerenderKey,
+  type PrerenderStoredEntry,
+  type WritablePrerenderStore,
+} from "./writable-store.js";
+
+export type {
+  OnDemandOption,
+  OnDemandRouteConfig,
+  PrerenderConfig,
+  PrerenderFn,
+  PrerenderResult,
+  PrerenderWarmCaches,
+  PrerenderManyOptions,
+  PrerenderRunner,
+  PrerenderRunOptions,
+  PrerenderRuntime,
+  PrerenderTarget,
+  PrerenderTargetObject,
+} from "./on-demand.js";
+
+export type { PrerenderEntry } from "./store.js";

package/src/prerender/memory-prerender-store.ts

@@ -0,0 +1,115 @@
+/**
+ * In-memory writable prerender store.
+ *
+ * Backs the zero-config dev overlay and the `@rangojs/router/testing` fake.
+ * A plain Map — no per-isolate null memoization (a later set() must be visible
+ * after an earlier miss), no React/RSC deps.
+ */
+
+import {
+  lowerStoredEntryStaleAt,
+  serializePrerenderKey,
+  type PrerenderKey,
+  type PrerenderStoredEntry,
+  type WritablePrerenderStore,
+} from "./writable-store.js";
+
+export interface MemoryPrerenderStore extends WritablePrerenderStore {
+  delete(key: PrerenderKey): Promise<void>;
+  markStale(routerId: string, tags: string[]): Promise<void>;
+  /** Synchronous read by structured key (tests). */
+  peek(key: PrerenderKey): PrerenderStoredEntry | null;
+  /** All stored [serializedKey, entry] pairs (tests). */
+  entries(): [string, PrerenderStoredEntry][];
+  /** Drop every entry. */
+  clear(): void;
+  readonly size: number;
+}
+
+export interface MemoryPrerenderStoreOptions {
+  /** Injectable clock for `markStale` in deterministic tests. Defaults to Date.now. */
+  now?: () => number;
+}
+
+/**
+ * Create an in-memory {@link WritablePrerenderStore} with test-inspection
+ * helpers. Invalidation is mark-stale (sets `staleAt`), never delete — matching
+ * the durable v1 contract so the entry keeps serving until refreshed.
+ */
+export function createMemoryPrerenderStore(
+  options: MemoryPrerenderStoreOptions = {},
+): MemoryPrerenderStore {
+  const now = options.now ?? (() => Date.now());
+  // The owning router per entry: the serialized key cannot be split back.
+  const map = new Map<
+    string,
+    { routerId: string; stored: PrerenderStoredEntry }
+  >();
+
+  // routerId -> tag -> when markStale() last named it. A held entry is marked
+  // in place; this covers a write that was rendered before the mark and set
+  // after it.
+  const marks = new Map<string, Map<string, number>>();
+
+  return {
+    async get(key: PrerenderKey): Promise<PrerenderStoredEntry | null> {
+      return map.get(serializePrerenderKey(key))?.stored ?? null;
+    },
+
+    async set(key: PrerenderKey, stored: PrerenderStoredEntry): Promise<void> {
+      // Strictly after storedAt, unlike the KV read (cloudflare.ts, `>=`): in
+      // one process a mark and a render start can share a millisecond with the
+      // mark first, which `>=` would read as invalidating that render. KV's
+      // marker write is I/O, so a same-millisecond marker there is ambiguous.
+      // Marks, never refuses: a stale entry keeps serving.
+      const routerMarks = marks.get(key.routerId);
+      if (routerMarks) {
+        for (const tag of stored.meta.tags) {
+          const at = routerMarks.get(tag);
+          if (at != null && at > stored.meta.storedAt) {
+            lowerStoredEntryStaleAt(stored, at);
+          }
+        }
+      }
+      map.set(serializePrerenderKey(key), { routerId: key.routerId, stored });
+    },
+
+    async delete(key: PrerenderKey): Promise<void> {
+      map.delete(serializePrerenderKey(key));
+    },
+
+    async markStale(routerId: string, tags: string[]): Promise<void> {
+      if (tags.length === 0) return;
+      const tagSet = new Set(tags);
+      const at = now();
+      let routerMarks = marks.get(routerId);
+      if (!routerMarks) marks.set(routerId, (routerMarks = new Map()));
+      for (const tag of tags) routerMarks.set(tag, at);
+      for (const entry of map.values()) {
+        if (
+          entry.routerId === routerId &&
+          entry.stored.meta.tags.some((t) => tagSet.has(t))
+        ) {
+          lowerStoredEntryStaleAt(entry.stored, at);
+        }
+      }
+    },
+
+    peek(key: PrerenderKey): PrerenderStoredEntry | null {
+      return map.get(serializePrerenderKey(key))?.stored ?? null;
+    },
+
+    entries(): [string, PrerenderStoredEntry][] {
+      return [...map].map(([k, v]) => [k, v.stored]);
+    },
+
+    clear(): void {
+      map.clear();
+      marks.clear();
+    },
+
+    get size(): number {
+      return map.size;
+    },
+  };
+}

package/src/prerender/on-demand.ts

@@ -0,0 +1,339 @@
+/**
+ * Public type surface for on-demand (ISR-style) prerender: the router
+ * `prerender` config option, the `router.prerender({ env, ctx })` runner, its typed
+ * target, and the inspectable result union.
+ *
+ * Types only — safe to import from router options, the public interfaces, the
+ * testing barrel, and platform adapters without pulling RSC deps.
+ */
+
+import type { ExecutionContext } from "../types/request-scope.js";
+import type { IsEmptyObject, ParamsFor } from "../reverse.js";
+import type { WritablePrerenderStore } from "./writable-store.js";
+import type { ShellCaptureRefusal } from "../rsc/shell-capture-constants.js";
+
+declare const prerenderTargetBrand: unique symbol;
+
+/**
+ * The target `onRevalidate` receives: a plain `{ route, params }` that goes
+ * straight into a queue message. The type-only brand (never present at
+ * runtime) lets the runner (`router.prerender({ env })(target)` / `.many()`) accepts it with no cast on a
+ * router typed with named routes, while a hand-written `{ route: "typo" }`
+ * stays a type error there. After a JSON round trip, assert it back:
+ * `JSON.parse(raw) as PrerenderTargetObject`.
+ */
+export interface PrerenderTargetObject {
+  route: string;
+  params: Record<string, string>;
+  readonly [prerenderTargetBrand]: true;
+}
+
+/**
+ * Route map used to type the object target. When the fluent `TRoutes` phantom is
+ * empty (the common `createRouter().routes(...)` case leaves it `{}`), fall back
+ * to the generated global route map — the same fallback `Prerender<"name">` and
+ * `reverse` use — so `router.prerender({ route, params })` stays typed without an
+ * explicit route-type parameter.
+ */
+type PrerenderRouteMap<TRoutes> = keyof TRoutes extends never
+  ? keyof Rango.GeneratedRouteMap extends never
+    ? {}
+    : Rango.GeneratedRouteMap
+  : TRoutes;
+
+/**
+ * Typed object target, derived from the router's route map the same way
+ * `reverse` is. No-param routes may omit `params`.
+ */
+type PrerenderRouteTarget<TRoutes> = {
+  [TName in keyof PrerenderRouteMap<TRoutes> & string]: IsEmptyObject<
+    ParamsFor<PrerenderRouteMap<TRoutes>, TName>
+  > extends true
+    ? { route: TName; params?: Record<string, never> }
+    : { route: TName; params: ParamsFor<PrerenderRouteMap<TRoutes>, TName> };
+}[keyof PrerenderRouteMap<TRoutes> & string];
+
+/**
+ * A prerender target: a typed named-route object, a path-like string/URL
+ * (`router.reverse()` output composes for free), or the `onRevalidate` target.
+ */
+export type PrerenderTarget<TRoutes = {}> =
+  | string
+  | URL
+  | PrerenderRouteTarget<TRoutes>
+  | PrerenderTargetObject;
+
+/** Env + platform capabilities bound once by `router.prerender({ env, ctx })`. */
+export interface PrerenderRuntime<TEnv = any> {
+  /** The live env: the producer's `ctx.env` (not the build's `buildEnv`). */
+  env: TEnv;
+  /** Cloudflare `ExecutionContext`; absent on node/Vercel. */
+  ctx?: ExecutionContext;
+  /**
+   * The origin a warm requests a path or `{ route, params }` target on, for
+   * example `"https://shop.example"`. Cache keys carry the host, so a warm
+   * must request the host visitors use. A full-URL target uses its own
+   * origin; without this option the runner uses the origin of the request it
+   * is called from (an action, a route handler, `onRevalidate`), and with
+   * neither a warm returns `skipped-no-origin`. An on-demand route's
+   * requestless render never needs it.
+   */
+  origin?: string;
+}
+
+/** Per-call options of the bound runner. */
+export interface PrerenderRunOptions {
+  /** Throw on failure instead of returning an `{ ok: false }` result. */
+  throwOnError?: boolean;
+  /**
+   * Only refresh what is cold or stale (cron-sweep opt-in), and the only
+   * path that can return `already-fresh`. On an on-demand route the stored
+   * entry is rendered only when stale. On any other route the warm reads its
+   * caches normally instead of forcing misses, so a fresh entry is left
+   * alone, a stale one refreshes and a missing one is written.
+   */
+  onlyIfStale?: boolean;
+}
+
+/** Per-call options of the bound runner's `.many()`. */
+export interface PrerenderManyOptions extends PrerenderRunOptions {
+  /** Max concurrent renders in a batch (default 1; any invalid value is 1). */
+  concurrency?: number;
+}
+
+/**
+ * What a warm request wrote, by cache. On a result of the warm path, and on
+ * an on-demand result whose route was also warmed.
+ */
+export interface PrerenderWarmCaches {
+  /**
+   * Store writes that landed, by store family: `record` (route `cache()`),
+   * `item` (`"use cache"` and loader `cache()`), `response` (the document
+   * cache and response routes), `shell` (the `ppr` shell).
+   */
+  writes: { record: number; item: number; response: number; shell: number };
+  /**
+   * The `ppr` shell; absent on a route without `ppr`. `fresh` is
+   * `onlyIfStale` finding a servable shell; `not-eligible` is a request the
+   * shell path passed on (an active nonce, a store without shells, the
+   * route's own `cache()` opt-out, a buffered response).
+   */
+  shell?:
+    | "stored"
+    | "fresh"
+    | "refused"
+    | "no-shell"
+    | "not-eligible"
+    | "skipped-capacity"
+    | "skipped-queue-timeout"
+    | "error";
+  /** Why the capture refused to store the shell. */
+  refusal?: ShellCaptureRefusal;
+  /** The document cache, when `createDocumentCacheMiddleware` ran. */
+  document?: "stored" | "not-cacheable";
+}
+
+/**
+ * Inspectable result, one per target. The trigger does not force callers
+ * into try/catch; `throwOnError: true` opts into throwing for admin/CI
+ * endpoints. `path` says what ran: `on-demand` is the requestless render of a
+ * `Prerender(..., { onDemand })` route into the prerender store, `warm` is a
+ * request through the router's handler that rewrites the route's runtime
+ * caches.
+ */
+export type PrerenderResult =
+  | {
+      ok: true;
+      path: "on-demand";
+      /**
+       * `already-fresh` only occurs with `onlyIfStale: true`.
+       *
+       * `removed`: a "removed" marker is stored in place of the page, and
+       * requests no longer get the page or its build-time entry. It is
+       * `ok: true`, so count it in sweep results. Written by
+       * `prerender.remove()` (permanent until a refresh without
+       * `onlyIfStale`; `tags` empty, no `ttl`), or by a refresh in which a
+       * `notFound()` was the only thing that went wrong, anywhere in the
+       * render: the route handler, a layout or parallel slot handler, any
+       * server component. That marker has the route's `tags` and `ttl` and is
+       * rechecked like a page. `onlyIfStale` finding a fresh marker reports
+       * `removed` too. When the data source may be failing, throw anything
+       * else: that is `render-failed` and keeps the page.
+       */
+      status: "rendered" | "already-fresh" | "removed";
+      target: string;
+      routeName: string;
+      /** Opaque, for debugging/logs only — not a stable format. */
+      key: string;
+      tags: string[];
+      /** Absent = never stale. */
+      ttl?: number;
+      /**
+       * The warm request that followed the store write. Absent when the app
+       * store is not shared, no origin resolved, or nothing was rendered.
+       */
+      caches?: PrerenderWarmCaches;
+    }
+  | {
+      ok: true;
+      path: "warm";
+      /** `already-fresh` only occurs with `onlyIfStale: true`. */
+      status: "warmed" | "already-fresh";
+      /** The absolute URL that was requested. */
+      target: string;
+      routeName: string;
+      /** The warm response's HTTP status. */
+      responseStatus: number;
+      caches: PrerenderWarmCaches;
+    }
+  | {
+      ok: false;
+      /** Absent when no route matched: every other result is past the match. */
+      path?: "on-demand" | "warm";
+      status:
+        | "no-match"
+        // No prerender store (on-demand), or no `createRouter({ cache })` (warm).
+        | "no-store"
+        | "skipped-personalized"
+        | "skipped-unsupported-target"
+        // The route (a Passthrough + onDemand route) returned ctx.passthrough()
+        // for this param set: no shared payload to persist. The "removed"
+        // marker is stored instead, so the live handler serves it and not a
+        // page stored or baked earlier.
+        | "skipped-passthrough"
+        // prerender.remove() on a route that is not on-demand: it has no page
+        // in the prerender store. (A refresh of such a route is a warm.)
+        | "skipped-not-on-demand"
+        // The app store's entries are not readable beyond the place the call
+        // runs (SegmentCacheStore.scope), so a warm would serve no one else.
+        | "skipped-store-not-shared"
+        // A path or { route, params } target with no origin to request it on.
+        | "skipped-no-origin"
+        // A ppr route whose shell was not stored (caches.shell says why).
+        | "shell-not-stored"
+        // The request rendered and no cache wrote anything.
+        | "skipped-uncached"
+        | "render-failed"
+        | "store-failed";
+      target: string;
+      routeName?: string;
+      /** The warm response's HTTP status, when a warm request ran. */
+      responseStatus?: number;
+      caches?: PrerenderWarmCaches;
+      error?: unknown;
+    };
+
+/**
+ * Per-route on-demand opt-in, carried inside `PrerenderOptions.onDemand`. Any
+ * truthy spelling works (literal, spread, imported const): producer retention
+ * is driven by the evaluated route manifest, not a textual scan of the call.
+ */
+export interface OnDemandRouteConfig {
+  /** Soft TTL (seconds) for entries refreshed for this route. Overrides the router `ttl`. */
+  ttl?: number;
+  /**
+   * Tags stamped on the stored entry, addressable via
+   * the runner's `markStale()`. A separate namespace from `cacheTag()` /
+   * `updateTag()` / `revalidateTag()`, which never reach the prerender store.
+   */
+  tags?: string[] | ((target: { params: Record<string, string> }) => string[]);
+}
+
+export type OnDemandOption = boolean | OnDemandRouteConfig;
+
+/**
+ * Env-resolved prerender store configuration. Same union shape as the `cache`
+ * option: a plain object or a factory resolved per request/per call, never at
+ * `createRouter()` time.
+ */
+export interface PrerenderConfig<TEnv = any> {
+  store: WritablePrerenderStore;
+  /**
+   * Default soft TTL (seconds) for a route whose `onDemand` sets none. Absent
+   * = never stale. Soft: a stale entry keeps serving; staleness only decides
+   * whether `onRevalidate` is scheduled. Entries never expire.
+   */
+  ttl?: number;
+  /**
+   * Stale-while-revalidate: its presence is the opt-in. Scheduled through
+   * `waitUntil` on a stale overlay hit (the stale entry still serves) with
+   * the JSON-serializable target and the live env. Runs at most once per
+   * stale key per isolate while one is in flight (one running longer than
+   * 15 s counts as finished, so a hung call cannot block the key), so
+   * `(target, env, ctx) => router.prerender({ env, ctx })(target, { onlyIfStale: true })`
+   * is safe in a single process; across isolates, point it at a queue, which
+   * owns dedup. Pass `onlyIfStale` in the call that runs later: a job queued
+   * for a page that `prerender.remove()` then removed finds the marker and
+   * renders nothing, where a plain refresh would bring the page back.
+   */
+  onRevalidate?: (
+    target: PrerenderTargetObject,
+    env: TEnv,
+    /** The stale request's execution context; absent where none exists. */
+    ctx?: ExecutionContext,
+  ) => void | Promise<void>;
+}
+
+/**
+ * @internal Per-request resolution of the prerender config plus the key
+ * version. Threaded onto the request context by the RSC handler and read by
+ * the serve-path overlay lookup.
+ */
+export interface ResolvedPrerender<TEnv = any> {
+  /** The resolved config; the store is `config.store`. */
+  config: PrerenderConfig<TEnv>;
+  routerId: string;
+  /** The router's cache version for overlay keys (resolvePrerenderVersion). */
+  version: string;
+}
+
+/**
+ * The runner `router.prerender({ env, ctx })` returns: callable per target,
+ * plus `.many` / `.remove` / `.markStale`. Typing rides the phantom `TRoutes`
+ * accumulator, like `reverse`.
+ */
+export interface PrerenderRunner<TRoutes = {}> {
+  (
+    target: PrerenderTarget<TRoutes>,
+    options?: PrerenderRunOptions,
+  ): Promise<PrerenderResult>;
+  many(
+    targets: ReadonlyArray<PrerenderTarget<TRoutes>>,
+    options?: PrerenderManyOptions,
+  ): Promise<PrerenderResult[]>;
+  /**
+   * Remove an on-demand route's page without rendering: a "removed" marker is
+   * stored in place of it. Requests then get a 404 (a `Passthrough` route: its
+   * live handler), never the build-time entry. Permanent: no `ttl`, no
+   * `onRevalidate`, left by `onlyIfStale`, until a `prerender(target)`
+   * without `onlyIfStale` renders the page again. It is a write like a
+   * refresh's, and the last write wins. `{ ok: true, status: "removed" }`; a
+   * route that is not on-demand is `skipped-not-on-demand`. `.many` is the
+   * batch form.
+   */
+  remove: {
+    (
+      target: PrerenderTarget<TRoutes>,
+      options?: Pick<PrerenderRunOptions, "throwOnError">,
+    ): Promise<PrerenderResult>;
+    many(
+      targets: ReadonlyArray<PrerenderTarget<TRoutes>>,
+      options?: Omit<PrerenderManyOptions, "onlyIfStale">,
+    ): Promise<PrerenderResult[]>;
+  };
+  /**
+   * Mark this router's stored entries carrying one of `tags` stale. Marking only: the
+   * entries keep serving, and a stale hit schedules `onRevalidate` when one is
+   * configured. Nothing is deleted or re-rendered here.
+   */
+  markStale(tags: string[]): Promise<void>;
+}
+
+/**
+ * The `router.prerender` function: binds the runtime (`env`, `ctx`) and returns
+ * the {@link PrerenderRunner}. Binding does no work; the config factory is
+ * resolved per call.
+ */
+export type PrerenderFn<TEnv = any, TRoutes = {}> = (
+  runtime: PrerenderRuntime<TEnv>,
+) => PrerenderRunner<TRoutes>;

package/src/prerender/producer-guard.ts

@@ -0,0 +1,66 @@
+/**
+ * Requestless-prerender guard.
+ *
+ * The on-demand producer renders a route with only route params + env — never
+ * the triggering request's cookies, headers, geo, or session (see the design's
+ * Producer Semantics). Personalized reads during a producer render would bake
+ * one visitor's data into a payload shared with everyone for that route.
+ *
+ * The producer marks its own request context with `_onDemandProducer: true`. The
+ * standalone request-scoped helpers a handler reaches for — `cookies()`,
+ * `headers()`, `invalidateClientCache()`, `keepClientCache()` — call
+ * {@link assertNotInsidePrerenderProducer}, which throws
+ * {@link PrerenderPersonalizationError}; the producer catches it and maps to a
+ * `skipped-personalized` result, leaving any existing entry untouched. (The
+ * producer context's own `ctx.cookie`/`header`/etc. remain the pre-existing
+ * build-time no-op stubs over empty synthetic state — the guard covers the
+ * standalone helpers, which are the reads that would otherwise see real request
+ * data.)
+ */
+
+/** Thrown when a producer render touches request-specific state. */
+export class PrerenderPersonalizationError extends Error {
+  /** Cross-realm-safe brand (instanceof can fail across bundle/realm boundaries). */
+  readonly isPrerenderPersonalizationError = true as const;
+
+  constructor(api: string) {
+    super(
+      `${api} cannot be used during on-demand prerender. The prerender producer ` +
+        `is requestless: it renders with route params and env only, and its output ` +
+        `is a shared payload keyed by route + params. Reading request-scoped state ` +
+        `(cookies, headers) or mutating the response here would leak one visitor's ` +
+        `data to every later visitor. This route was skipped as personalized.`,
+    );
+    this.name = "PrerenderPersonalizationError";
+  }
+}
+
+export function isPrerenderPersonalizationError(
+  value: unknown,
+): value is PrerenderPersonalizationError {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    (value as PrerenderPersonalizationError).isPrerenderPersonalizationError ===
+      true
+  );
+}
+
+/**
+ * Throw {@link PrerenderPersonalizationError} when `ctx` is a requestless
+ * on-demand producer context. A no-op for the live request path and the
+ * build/dev prerender paths (which do not set `_onDemandProducer`), so existing
+ * callers are unaffected.
+ */
+export function assertNotInsidePrerenderProducer(
+  ctx: unknown,
+  api: string,
+): void {
+  if (
+    ctx != null &&
+    typeof ctx === "object" &&
+    (ctx as { _onDemandProducer?: boolean })._onDemandProducer === true
+  ) {
+    throw new PrerenderPersonalizationError(api);
+  }
+}

package/src/prerender/shell-manifest-key.ts

@@ -1,20 +1,15 @@
 /**
- * Build shell manifest key, shared by the producer (the build's shell
- * prerender phase, vite/discovery/shell-prerender-phase.ts) and the consumer
- * (the runtime read-through, rsc/shell-build-manifest.ts) so the format
- * cannot drift. Dependency-free: the producer runs node-side in the plugin,
- * the consumer in the RSC runtime.
- *
- * PATHNAME-ONLY by design. Host-free because the build knows no request
- * host. Router-free because the router id ($$id) is a hash of
- * filePath:lineNumber of the TRANSFORMED source, which differs between the
- * discovery temp server's dev-style transform chain and the main build's —
- * a temp-realm router id can never be looked up by the shipped worker. The
- * producer instead detects pathname collisions across routers at build time
- * and declines both entries (loudly), keeping the key unambiguous. This is
- * a manifest namespace, never a store keyspace: the runtime shell key
- * (host + pathname + search + ":shell") stays untouched.
+ * Build-time shell manifest key, `{routerId}@{pathname}`: the ONE derivation
+ * shared by the producer (vite/discovery/shell-prerender-phase.ts) and the
+ * consumer (rsc/shell-build-manifest.ts) so the two sides cannot drift. The
+ * router part follows the router rule (cache-key-utils.ts). Host-free (the
+ * build knows no request host); a manifest namespace, never a store keyspace.
  */
-export function buildShellManifestKey(pathname: string): string {
-  return pathname;
+import { routerKeyPrefix } from "../cache/cache-key-utils.js";
+
+export function buildShellManifestKey(
+  routerId: string,
+  pathname: string,
+): string {
+  return `${routerKeyPrefix(routerId)}${pathname}`;
 }