@rangojs/router 0.21.0 → 0.22.0

package/src/prerender/create-prerender-trigger.ts

@@ -0,0 +1,780 @@
+/**
+ * `router.prerender()` trigger factory.
+ *
+ * Builds the `router.prerender` binder: `(runtime) => runner`, the runner being
+ * the per-target callable (plus `.many` / `.remove` / `.markStale`) from router-supplied
+ * deps. Pure and testable: all router internals (reverse, match, the producer,
+ * the request handler) arrive as injected functions, so this module has no RSC
+ * imports and can be unit-tested with fakes.
+ *
+ * One verb, dispatched by route after the match:
+ * - A `Prerender(..., { onDemand })` route takes the requestless render into
+ *   the prerender store (docs/design/ondemand-prerender.md), then, when the
+ *   app cache store is shared and an origin resolves, a warm request that
+ *   rebuilds the runtime caches on top of the new entry.
+ * - Every other route is warmed: a cookie-free GET through the router's own
+ *   handler in which every runtime cache read misses and every write replaces
+ *   the entry (docs/design/prerender-every-route.md).
+ *
+ * Contract highlights:
+ * - Requestless: the producer render never inherits the caller's request state.
+ * - A refresh always renders and replaces; `onlyIfStale` is the cron-sweep
+ *   opt-in and the only path that returns `already-fresh`.
+ * - A failed render/store keeps the previous entry (replace-on-success).
+ * - A `notFound()` in the render is not a failure: it stores a "removed"
+ *   marker in place of the page, stamped with the route's ttl and tags so it
+ *   is rechecked like a page. `prerender.remove()` stores one without
+ *   rendering, which never goes stale. A Passthrough build handler that
+ *   declines (`ctx.passthrough()`) stores one too, so its live handler answers.
+ * - A page and a render's marker (a `notFound()` or a decline) carry the
+ *   render's start as `storedAt`, so a `markStale()` that lands during the
+ *   render marks the result; `staleAt` counts the ttl from the write. A
+ *   `remove()` marker renders nothing and carries its write time.
+ * - An on-demand target is path-only (its key carries no search); a warm
+ *   target keeps its search params, which cache keys carry.
+ * - A warm writes only to a store shared beyond the place the call runs.
+ */
+
+import type { SerializedSegmentData } from "../cache/types.js";
+import { isReservedSearchParam } from "../cache/cache-key-utils.js";
+import { resolveWarmStoreScope } from "../cache/store-scope.js";
+import type { HandlerCacheConfig } from "../rsc/types.js";
+import type { ExecutionContext } from "../types/request-scope.js";
+import { createCollectingExecutionContext } from "../cache/background-task.js";
+import { composeWarmResult, runWarmRequest } from "./warm.js";
+import { hashParams } from "./param-hash.js";
+import { isPrerenderPersonalizationError } from "./producer-guard.js";
+import { normalizeTagList } from "../cache/cache-policy.js";
+import {
+  composeStoredEntry,
+  composeStoredTombstone,
+  isStoredEntryStale,
+  readVerifiedStoredEntry,
+  serializePrerenderKey,
+  type PrerenderKey,
+  type PrerenderStoredEntry,
+} from "./writable-store.js";
+import type {
+  OnDemandRouteConfig,
+  PrerenderConfig,
+  PrerenderFn,
+  PrerenderManyOptions,
+  PrerenderResult,
+  PrerenderRunner,
+  PrerenderRunOptions,
+  PrerenderRuntime,
+  PrerenderTarget,
+} from "./on-demand.js";
+
+/** Route metadata the trigger needs, resolved from a pathname by the router. */
+export interface PrerenderMatchInfo {
+  routeName: string;
+  params: Record<string, string>;
+  /** True when the route opted into on-demand (Prerender(..., { onDemand })). */
+  isOnDemand: boolean;
+  /** True when the route is wrapped in Passthrough(). */
+  isPassthrough: boolean;
+}
+
+/**
+ * Raw producer output (matchForPrerender's main-variant shape). `onDemandConfig`
+ * is the route's `onDemand: { ttl, tags }` object (the `tags` callback can't
+ * ride the serialized trie), read from the loaded route entry during production.
+ */
+export interface ProducerOutput {
+  segments: SerializedSegmentData[];
+  handles: string;
+  routeName: string;
+  params: Record<string, string>;
+  passthrough?: true;
+  /** The render hit `notFound()` and nothing else failed: no page to store. */
+  notFound?: true;
+  onDemandConfig?: OnDemandRouteConfig;
+}
+
+export interface PrerenderTriggerDeps<TEnv = any> {
+  routerId: string;
+  /**
+   * The key version: the router's data version (resolvePrerenderVersion),
+   * resolved per refresh (once per `.many()` batch), as the request handler
+   * resolves it per request.
+   */
+  resolveVersion: () => string;
+  /** True when running under Vite dev (drives the producer context's `dev`). */
+  isDev: () => boolean;
+  /**
+   * True under the Vite dev server (isViteDevServer): the one place the
+   * memory store counts as shared, and so where the not-shared warning fires.
+   */
+  isViteDevServer: () => boolean;
+  /** Load the per-router manifest/trie before matching, as router.fetch does. */
+  ensureManifest: () => Promise<void>;
+  /** Resolve the env-scoped prerender config (factory or object); undefined when unconfigured. */
+  resolveConfig: (
+    env: TEnv,
+    ctx: ExecutionContext | undefined,
+  ) => PrerenderConfig<TEnv> | undefined;
+  /** Reverse an object target to a pathname; undefined when the route name is unknown. */
+  reverse: (
+    route: string,
+    params: Record<string, string>,
+  ) => string | undefined;
+  /** Match a pathname to route metadata; null when nothing matches. */
+  matchRoute: (
+    pathname: string,
+  ) => PrerenderMatchInfo | null | Promise<PrerenderMatchInfo | null>;
+  /** Run the requestless producer (matchForPrerender with onDemand). May throw. */
+  runProducer: (input: {
+    pathname: string;
+    isPassthrough: boolean;
+    env: TEnv;
+    dev: boolean;
+  }) => Promise<ProducerOutput | null>;
+  /**
+   * Resolve `createRouter({ cache })` (factory or object) for a warm;
+   * undefined when the router has none. May throw, like the prerender factory.
+   */
+  resolveCacheConfig: (
+    env: TEnv,
+    ctx: ExecutionContext,
+  ) => HandlerCacheConfig | undefined;
+  /** The router's own request handler (`router.fetch`): where a warm is dispatched. */
+  fetch: (
+    request: Request,
+    input: { env: TEnv; ctx: ExecutionContext },
+  ) => Promise<Response>;
+  /** The origin of the request the runner is called from, when there is one. */
+  ambientOrigin: () => string | undefined;
+}
+
+/** Thrown by the trigger when `throwOnError: true` and the operation did not succeed. */
+export class PrerenderError extends Error {
+  readonly result: Extract<PrerenderResult, { ok: false }>;
+  /** `operation` is the runner call that failed; the message names it. */
+  constructor(
+    result: Extract<PrerenderResult, { ok: false }>,
+    operation: "prerender" | "remove" = "prerender",
+  ) {
+    const call =
+      operation === "remove" ? "prerender.remove" : "router.prerender";
+    super(
+      `${call}("${result.target}") failed: ${result.status}` +
+        (result.error instanceof Error ? ` — ${result.error.message}` : ""),
+    );
+    this.name = "PrerenderError";
+    this.result = result;
+    if (result.error !== undefined) this.cause = result.error;
+  }
+}
+
+interface ResolvedTarget {
+  /** Path with no search/hash, ready to match. */
+  pathname?: string;
+  /** Display form used in the result's `target` field. */
+  display: string;
+  /** Set when the target does not parse as an http(s) URL or a path. */
+  unsupported?: boolean;
+  /** The target's own origin: a full-URL string or a URL. */
+  origin?: string;
+  /** `?`-prefixed search, or "". */
+  search: string;
+  /** The target carries a hash, or a search param the router reserves. */
+  hashOrReserved: boolean;
+}
+
+/** Stands in for the origin while a path target is parsed; never requested. */
+const PATH_BASE = "http://prerender.local";
+
+function resolveTarget<TRoutes>(
+  target: PrerenderTarget<TRoutes>,
+  reverse: PrerenderTriggerDeps["reverse"],
+): ResolvedTarget {
+  if (typeof target === "string") {
+    return fromUrlLike(target, target);
+  }
+  if (target instanceof URL) {
+    return fromUrlLike(target.href, target.pathname);
+  }
+  // Object target { route, params? }
+  const route = (target as { route: string }).route;
+  const params = ((target as { params?: Record<string, string> }).params ??
+    {}) as Record<string, string>;
+  const pathname = reverse(route, params);
+  if (pathname === undefined) {
+    // Unknown route name — surfaced as no-match downstream.
+    return { display: route, search: "", hashOrReserved: false };
+  }
+  return fromUrlLike(pathname, pathname);
+}
+
+function fromUrlLike(raw: string, display: string): ResolvedTarget {
+  let url: URL;
+  try {
+    // A relative path resolves against the stand-in base; a full URL keeps
+    // its own origin, which a warm requests (cache keys carry the host).
+    url = new URL(raw, PATH_BASE);
+  } catch {
+    return { display, unsupported: true, search: "", hashOrReserved: false };
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    return { display, unsupported: true, search: "", hashOrReserved: false };
+  }
+  // The params that switch the handler's mode (`_rsc*`, `__no_cache`) are not
+  // a page a visitor requests.
+  const reserved = [...url.searchParams.keys()].some(isReservedSearchParam);
+  return {
+    pathname: url.pathname,
+    display: url.pathname,
+    ...(url.origin !== PATH_BASE ? { origin: url.origin } : {}),
+    search: url.search,
+    hashOrReserved: url.hash !== "" || reserved,
+  };
+}
+
+/**
+ * Create the `router.prerender` callable. See {@link PrerenderTriggerDeps}.
+ */
+export function createPrerenderTrigger<TEnv = any, TRoutes = {}>(
+  deps: PrerenderTriggerDeps<TEnv>,
+): PrerenderFn<TEnv, TRoutes> {
+  /** One target: a refresh, or with `removing` a removal (`prerender.remove`). */
+  async function refresh(
+    target: PrerenderTarget<TRoutes>,
+    runtime: PrerenderRuntime<TEnv>,
+    options: PrerenderRunOptions = {},
+    version: string = deps.resolveVersion(),
+    removing = false,
+  ): Promise<PrerenderResult> {
+    const result = await run(target, runtime, options, version, removing);
+    if (!result.ok && options.throwOnError) {
+      throw new PrerenderError(result, removing ? "remove" : "prerender");
+    }
+    return result;
+  }
+
+  async function run(
+    target: PrerenderTarget<TRoutes>,
+    runtime: PrerenderRuntime<TEnv>,
+    options: PrerenderRunOptions,
+    version: string,
+    removing: boolean,
+  ): Promise<PrerenderResult> {
+    const resolved = resolveTarget(target, deps.reverse);
+    const display = resolved.display;
+
+    if (resolved.unsupported) {
+      return {
+        ok: false,
+        status: "skipped-unsupported-target",
+        target: display,
+      };
+    }
+    if (resolved.pathname === undefined) {
+      return { ok: false, status: "no-match", target: display };
+    }
+
+    await deps.ensureManifest();
+
+    const match = await deps.matchRoute(resolved.pathname);
+    if (!match) {
+      return { ok: false, status: "no-match", target: display };
+    }
+    if (removing && !match.isOnDemand) {
+      // Only an on-demand route has a page in the prerender store. Never the
+      // warm a refresh of this route would be.
+      return {
+        ok: false,
+        path: "on-demand",
+        status: "skipped-not-on-demand",
+        target: display,
+        routeName: match.routeName,
+      };
+    }
+    if (resolved.hashOrReserved) {
+      return {
+        ok: false,
+        path: match.isOnDemand ? "on-demand" : "warm",
+        status: "skipped-unsupported-target",
+        target: display,
+        routeName: match.routeName,
+      };
+    }
+    if (!match.isOnDemand) {
+      return warm(
+        resolved,
+        match,
+        runtime,
+        options.onlyIfStale ? "fill" : "replace",
+      );
+    }
+
+    if (resolved.search) {
+      // An on-demand key is route + params: a search would silently persist
+      // (or remove the page) under the base key.
+      return {
+        ok: false,
+        path: "on-demand",
+        status: "skipped-unsupported-target",
+        target: display,
+        routeName: match.routeName,
+      };
+    }
+    const result = await renderOnDemand(
+      resolved.pathname,
+      display,
+      match,
+      runtime,
+      options,
+      version,
+      removing,
+    );
+    // Then the request handler, on top of the entry just stored: the route's
+    // loaders' own cache() and the document cache are rebuilt on it. A
+    // Passthrough param the producer declined is served by the live handler
+    // (the marker renderOnDemand stored for it keeps a page stored or baked
+    // earlier from answering the warm), whose caches are warmed the same way.
+    // Quiet: the refresh is complete without it. Never after `removed`: there
+    // is no page to rebuild a cache on, and a Passthrough route's live handler
+    // may still render the removed page from a data source that has not
+    // caught up, which the warm would then write to its caches.
+    if (
+      result.status === "rendered" ||
+      result.status === "skipped-passthrough"
+    ) {
+      const warmed = await warm(resolved, match, runtime, "replace", true);
+      if (warmed.caches) return { ...result, caches: warmed.caches };
+    }
+    return result;
+  }
+
+  let warnedNotShared = false;
+
+  /**
+   * Warm one matched route: a GET of the URL a visitor requests, through the
+   * router's own handler. `followUp` is the warm after an on-demand render:
+   * its refusals are not worth a warning, the render already did its job.
+   */
+  async function warm(
+    resolved: ResolvedTarget,
+    match: PrerenderMatchInfo,
+    runtime: PrerenderRuntime<TEnv>,
+    mode: "replace" | "fill",
+    followUp = false,
+  ): Promise<PrerenderResult> {
+    const refused = (
+      status: Extract<PrerenderResult, { ok: false }>["status"],
+      target: string = resolved.display,
+      error?: unknown,
+    ): PrerenderResult => ({
+      ok: false,
+      path: "warm",
+      status,
+      target,
+      routeName: match.routeName,
+      ...(error !== undefined ? { error } : {}),
+    });
+
+    // Cache keys carry the host, so the warm requests the host visitors use:
+    // the target's own, the binding's, else the calling request's.
+    let origin: string | undefined;
+    try {
+      origin =
+        resolved.origin ??
+        (runtime.origin !== undefined
+          ? new URL(runtime.origin).origin
+          : deps.ambientOrigin());
+    } catch (error) {
+      return refused("skipped-no-origin", resolved.display, error);
+    }
+    if (!origin) return refused("skipped-no-origin");
+    const url = new URL(resolved.pathname + resolved.search, origin);
+
+    // Resolved with the collecting context, so a store's own background
+    // writes are waited for too. A factory throw maps to no-store.
+    const ctx = createCollectingExecutionContext(runtime.ctx);
+    let cacheConfig: HandlerCacheConfig | undefined;
+    let configError: unknown;
+    try {
+      cacheConfig = deps.resolveCacheConfig(runtime.env, ctx);
+    } catch (error) {
+      configError = error;
+    }
+    if (!cacheConfig?.store || cacheConfig.enabled === false) {
+      return refused("no-store", url.href, configError);
+    }
+
+    const devServer = deps.isViteDevServer();
+    if (resolveWarmStoreScope(cacheConfig.store, devServer) === "local") {
+      if (!followUp && devServer && !warnedNotShared) {
+        warnedNotShared = true;
+        const name = cacheConfig.store.constructor?.name;
+        console.warn(
+          `[rango] router.prerender("${resolved.display}") did not warm: the ` +
+            `cache store${name && name !== "Object" ? ` (${name})` : ""} ` +
+            `declares ${
+              cacheConfig.store.scope === undefined
+                ? "no scope"
+                : `scope "${String(cacheConfig.store.scope)}"`
+            }, so entries written here serve no other process, isolate or ` +
+            "edge location. Warming needs a store whose scope is " +
+            '"global" or "regional" (CFCacheStore with kv, ' +
+            "VercelCacheStore), or a custom store that declares one.",
+        );
+      }
+      return refused("skipped-store-not-shared", url.href);
+    }
+
+    const outcome = await runWarmRequest({
+      url,
+      mode,
+      cacheConfig,
+      env: runtime.env,
+      ctx,
+      fetch: deps.fetch,
+    });
+    return composeWarmResult(outcome, url.href, match.routeName);
+  }
+
+  /**
+   * The requestless render of an on-demand route into the prerender store
+   * (#640), or with `removing` the write of its "removed" marker (#1060).
+   */
+  async function renderOnDemand(
+    pathname: string,
+    display: string,
+    match: PrerenderMatchInfo,
+    runtime: PrerenderRuntime<TEnv>,
+    options: PrerenderRunOptions,
+    version: string,
+    removing: boolean,
+  ): Promise<PrerenderResult> {
+    // The prerender factory is user code like tags()/store.set: a throw (e.g.
+    // a missing binding tripping store construction) must map to a result, not
+    // escape run() — which would reject refresh() despite throwOnError: false
+    // and abort a many() batch with no per-target results. A throw leaves
+    // config undefined, so it funnels into the same no-store return.
+    let config: PrerenderConfig<TEnv> | undefined;
+    let configError: unknown;
+    try {
+      config = deps.resolveConfig(runtime.env, runtime.ctx);
+    } catch (err) {
+      configError = err;
+    }
+    if (!config?.store) {
+      return {
+        ok: false,
+        path: "on-demand",
+        status: "no-store",
+        target: display,
+        routeName: match.routeName,
+        ...(configError !== undefined ? { error: configError } : {}),
+      };
+    }
+
+    const key: PrerenderKey = {
+      routerId: deps.routerId,
+      version,
+      routeName: match.routeName,
+      paramHash: hashParams(match.params),
+    };
+    const keyStr = serializePrerenderKey(key);
+    const store = config.store;
+    /** What the store holds for the page, as a result reports it. */
+    const held = (
+      status: "already-fresh" | "removed",
+      meta: PrerenderStoredEntry["meta"],
+    ): PrerenderResult => ({
+      ok: true,
+      path: "on-demand",
+      status,
+      target: display,
+      routeName: match.routeName,
+      key: keyStr,
+      tags: meta.tags,
+      // The configured ttl, not staleAt - storedAt: storedAt is the render's
+      // start and a markStale() lowers staleAt, so the difference is neither.
+      ...(meta.ttl != null ? { ttl: meta.ttl } : {}),
+    });
+    // Replace-on-success: a failed write leaves the prior durable entry (and
+    // the bundled manifest fallback) in place.
+    const storeFailed = (error: unknown): PrerenderResult => ({
+      ok: false,
+      path: "on-demand",
+      status: "store-failed",
+      target: display,
+      routeName: match.routeName,
+      error,
+    });
+
+    if (removing) {
+      // The "removed" marker in place of the page. Not store.delete(): that
+      // would bring a baked param's build-time entry back. No ttl and no
+      // tags: it never goes stale and markStale() cannot reach it, so only a
+      // refresh without onlyIfStale brings the page back.
+      const marker = composeStoredTombstone(
+        key,
+        { tags: [], params: match.params },
+        Date.now(),
+      );
+      try {
+        await store.set(key, marker);
+      } catch (error) {
+        return storeFailed(error);
+      }
+      return held("removed", marker.meta);
+    }
+
+    // onlyIfStale: the cron-sweep opt-in. A CMS webhook (default) always renders,
+    // because it fires precisely when content changed. This is the only path that
+    // returns already-fresh, reported with the existing entry's ttl/tags.
+    if (options.onlyIfStale) {
+      // An unreadable or unverifiable entry is "couldn't confirm fresh":
+      // render, never throw (one result per target, many() keeps going).
+      const existing = await readVerifiedStoredEntry(store, key, match.params);
+      // A fresh marker is left like a fresh page; a stale one (a notFound()
+      // past its ttl, or marked stale) is rendered again below.
+      if (existing && !isStoredEntryStale(existing, Date.now())) {
+        return held(
+          existing.removed === true ? "removed" : "already-fresh",
+          existing.meta,
+        );
+      }
+    }
+
+    // The entry's storedAt (#1072): a markStale() while the render runs must
+    // mark it, and the stores compare their tag marker with storedAt.
+    const startedAt = Date.now();
+    let produced: ProducerOutput | null;
+    try {
+      produced = await deps.runProducer({
+        pathname,
+        isPassthrough: match.isPassthrough,
+        env: runtime.env,
+        dev: deps.isDev(),
+      });
+    } catch (err) {
+      if (isPrerenderPersonalizationError(err)) {
+        return {
+          ok: false,
+          path: "on-demand",
+          status: "skipped-personalized",
+          target: display,
+          routeName: match.routeName,
+        };
+      }
+      // #587: matchForPrerender already threads throwOnError so a render throw
+      // surfaces here rather than baking a frozen error page. Keep the old entry.
+      return {
+        ok: false,
+        path: "on-demand",
+        status: "render-failed",
+        target: display,
+        routeName: match.routeName,
+        error: err,
+      };
+    }
+
+    if (!produced) {
+      return {
+        ok: false,
+        path: "on-demand",
+        status: "no-match",
+        target: display,
+        routeName: match.routeName,
+      };
+    }
+    // No page to store: the render hit notFound() (the page no longer
+    // exists; keeping the old entry would serve a deleted item until the next
+    // deploy), or a Passthrough build handler declined the param (the live
+    // handler is to answer, which it only does once nothing in a prerender
+    // store does). Both store the "removed" marker, stamped below with the
+    // route's ttl and tags like a page, so the outcome is rechecked like one.
+    const noPage = produced.notFound === true || produced.passthrough === true;
+
+    // Resolve soft TTL + tags from the route's onDemand config (read off the
+    // loaded route entry by the producer), falling back to the router default.
+    const ttl = produced.onDemandConfig?.ttl ?? config.ttl;
+    let tags: string[] = [];
+    try {
+      // The user-supplied tags callback runs here; a throw from it must not
+      // escape run() (which would bypass the result contract and abort a many()
+      // batch) — keep it inside the store guard so it maps to store-failed.
+      const routeTags = produced.onDemandConfig?.tags;
+      const rawTags =
+        typeof routeTags === "function"
+          ? routeTags({ params: match.params })
+          : (routeTags ?? []);
+      // Same normalization as cache({ tags }): trimmed, no empties, no duplicates.
+      tags =
+        normalizeTagList(
+          [...rawTags].filter((t): t is string => typeof t === "string"),
+        ) ?? [];
+      const stamp = {
+        ...(ttl != null ? { ttl } : {}),
+        tags,
+        params: match.params,
+      };
+      if (!noPage) {
+        // A marker stored after this render started is not overwritten by its
+        // page: a remove() (stamped with its write time) always qualifies. A
+        // render's own marker carries that render's start, so only a render
+        // that started later than this one wins; an older render's notFound()
+        // does not (this one read newer data). This narrows the race, it
+        // cannot close it: the read and the write are two store calls, and KV
+        // is eventually consistent. Otherwise last write wins.
+        const current = await readVerifiedStoredEntry(store, key, match.params);
+        if (current?.removed === true && current.meta.storedAt > startedAt) {
+          return held("removed", current.meta);
+        }
+      }
+      // The router composes the envelope; the store only persists it.
+      const writtenAt = Date.now();
+      await store.set(
+        key,
+        noPage
+          ? composeStoredTombstone(key, stamp, startedAt, writtenAt)
+          : composeStoredEntry(
+              key,
+              { segments: produced.segments, handles: produced.handles },
+              stamp,
+              startedAt,
+              writtenAt,
+            ),
+      );
+    } catch (err) {
+      return storeFailed(err);
+    }
+
+    if (produced.passthrough) {
+      return {
+        ok: false,
+        path: "on-demand",
+        status: "skipped-passthrough",
+        target: display,
+        routeName: match.routeName,
+      };
+    }
+    return {
+      ok: true,
+      path: "on-demand",
+      status: produced.notFound ? "removed" : "rendered",
+      target: display,
+      routeName: match.routeName,
+      key: keyStr,
+      tags,
+      ...(ttl != null ? { ttl } : {}),
+    };
+  }
+
+  let warnedNoStore = false;
+  let warnedNoRevalidate = false;
+
+  async function many(
+    runtime: PrerenderRuntime<TEnv>,
+    targets: ReadonlyArray<PrerenderTarget<TRoutes>>,
+    options: PrerenderManyOptions = {},
+    removing = false,
+  ): Promise<PrerenderResult[]> {
+    // Default to 1 for any invalid concurrency (undefined, NaN, < 1). Without
+    // this, Math.floor(NaN) -> NaN spawns zero workers and many() resolves to an
+    // array of holes that reports nothing.
+    const raw = options.concurrency;
+    const concurrency =
+      typeof raw === "number" && Number.isFinite(raw) && raw >= 1
+        ? Math.floor(raw)
+        : 1;
+    const version = deps.resolveVersion();
+    return runWithConcurrency(targets, concurrency, (target) =>
+      // throwOnError propagates per-item so the batch stops on the first failure;
+      // without it, every target yields a result.
+      refresh(target, runtime, options, version, removing),
+    );
+  }
+
+  async function markStale(
+    runtime: PrerenderRuntime<TEnv>,
+    tags: string[],
+  ): Promise<void> {
+    if (tags.length === 0) return;
+    const config = deps.resolveConfig(runtime.env, runtime.ctx);
+    if (!config?.store.markStale) {
+      // A void return makes a misconfigured caller (no store, or a store
+      // without tag support) look like success: a dead CMS webhook.
+      if (deps.isDev() && !warnedNoStore) {
+        warnedNoStore = true;
+        console.warn(
+          "[rango] prerender.markStale() is a no-op: " +
+            (config?.store
+              ? "the configured store does not implement markStale."
+              : "no prerender store is configured."),
+        );
+      }
+      return;
+    }
+    if (!config.onRevalidate && deps.isDev() && !warnedNoRevalidate) {
+      warnedNoRevalidate = true;
+      console.warn(
+        "[rango] prerender.markStale() marked entries stale, but no " +
+          "onRevalidate is configured, so a stale hit schedules nothing. The " +
+          "entries keep serving until router.prerender() re-renders them " +
+          "(for example a sweep with { onlyIfStale: true }).",
+      );
+    }
+    await config.store.markStale(deps.routerId, tags);
+  }
+
+  // Binding does no work: the config factory, version and manifest resolve per
+  // call. The warn-once flags live on the trigger, shared by every bound runner.
+  return (runtime: PrerenderRuntime<TEnv>): PrerenderRunner<TRoutes> => {
+    const runner = ((target, options) =>
+      refresh(target, runtime, options)) as PrerenderRunner<TRoutes>;
+    runner.many = (targets, options) => many(runtime, targets, options);
+    const remove = ((target, options) =>
+      refresh(
+        target,
+        runtime,
+        options,
+        undefined,
+        true,
+      )) as PrerenderRunner<TRoutes>["remove"];
+    remove.many = (targets, options) => many(runtime, targets, options, true);
+    runner.remove = remove;
+    runner.markStale = (tags) => markStale(runtime, tags);
+    return runner;
+  };
+}
+
+/**
+ * Bounded-concurrency map preserving input order. Rejects on the first task
+ * error (used so `many({ throwOnError })` stops the batch). The abort flag is
+ * load-bearing: Promise.all rejects on the first worker error while the other
+ * workers are mid-await — without it they would drain the entire remaining
+ * batch (rendering and writing, results discarded) after the caller has
+ * already seen the throw. In-flight items still settle; no new item starts.
+ */
+async function runWithConcurrency<T, R>(
+  items: ReadonlyArray<T>,
+  concurrency: number,
+  task: (item: T) => Promise<R>,
+): Promise<R[]> {
+  const results = new Array<R>(items.length);
+  let next = 0;
+  let aborted = false;
+  async function worker(): Promise<void> {
+    while (!aborted && next < items.length) {
+      const i = next++;
+      try {
+        results[i] = await task(items[i]);
+      } catch (err) {
+        aborted = true;
+        throw err;
+      }
+    }
+  }
+  const workers = Array.from(
+    { length: Math.min(concurrency, items.length) },
+    () => worker(),
+  );
+  await Promise.all(workers);
+  return results;
+}