@rsc-kit/core 0.30.43 → 0.30.45

package/dist/pageCache.d.ts

@@ -1,3 +1,4 @@
+import type { CacheStore } from "./cache.js";
 /** What a request for a `revalidate` page carries from the moment it arrives. */
 export interface PageCaching {
     /** Seconds a shared cache may keep the page. */
@@ -56,3 +57,29 @@ export declare function finishCacheable(request: Request, response: Response, en
  * it - but a not-found one is kept no longer than a 404.
  */
 saidNotFound?: () => boolean): Promise<Response>;
+/**
+ * Pages kept in this process, by the size of what they hold: a page is tens
+ * or hundreds of KB, so a count says nothing about memory. Least recently
+ * used goes first.
+ */
+export declare function pageMemoryStore(maxBytes?: number): CacheStore;
+/** A kept answer, and whether it is past its time: served, while one render replaces it. */
+export interface KeptAnswer {
+    response: Response;
+    stale: boolean;
+}
+export interface PageCache {
+    /** The kept answer for this request, or null to render it now. */
+    lookup(key: string, request: Request): Promise<KeptAnswer | null>;
+    /** Whether a render for this key is running in this process. */
+    busy(key: string): boolean;
+    /** Keep the answer, when finishCacheable() sent it public. */
+    keep(key: string, answer: Response): Promise<void>;
+    /** Run one render per key at a time: a burst for a page nobody has kept waits for the first. */
+    once<T>(key: string, render: () => Promise<T>): Promise<{
+        led: boolean;
+        value?: T;
+    }>;
+}
+/** The engine's page cache, over a store: the app's, or one of its own in memory. */
+export declare function createPageCache(store: CacheStore): PageCache;

package/dist/pageCache.js

@@ -29,7 +29,8 @@
 // by the backend on every call does not make every page private.
 import { HEADER, PER_CLIENT } from "./headers.js";
 import { PAYLOAD_PARAM, payloadKey, withoutPayloadKey } from "./js/payloadKey.js";
-import { cacheTagsRead, renderFailed, visitorReads } from "./request.js";
+import { cacheTagsRead, cacheTagVersionsRead, renderFailed, visitorReads } from "./request.js";
+import { versionSource } from "./changed.js";
 /** A 404 is kept no longer than this, however long its page may be. */
 const NOT_FOUND_LIMIT = 60;
 /** How long a cache may serve a stale page while one request refreshes it, or while the origin is failing. */
@@ -196,10 +197,167 @@ saidNotFound = () => false) {
     const tags = cacheTagHeader(cacheTagsRead());
     if (tags)
         headers.set("Cache-Tag", tags);
+    const kept = { status: response.status, body, versions: cacheTagVersionsRead(), revalidate: entry.revalidate, notFound: saidNotFound() };
     if (response.status === 200 && matches(request.headers.get("If-None-Match"), etag)) {
         headers.delete("Content-Length");
-        return new Response(null, { status: 304, headers });
+        const answer = new Response(null, { status: 304, headers });
+        keepable.set(answer, kept);
+        return answer;
     }
-    return new Response(request.method === "HEAD" ? null : body, { status: response.status, statusText: response.statusText, headers });
+    const answer = new Response(request.method === "HEAD" ? null : body, { status: response.status, statusText: response.statusText, headers });
+    keepable.set(answer, kept);
+    return answer;
+}
+const keepable = new WeakMap();
+/** Headers that belong to one answer, never to the kept page. */
+const NOT_KEPT = new Set(["date", "set-cookie", "content-length", "x-rsc-kit", "x-powered-by", "age"]);
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+/**
+ * Pages kept in this process, by the size of what they hold: a page is tens
+ * or hundreds of KB, so a count says nothing about memory. Least recently
+ * used goes first.
+ */
+export function pageMemoryStore(maxBytes = 64 * 1024 * 1024) {
+    const entries = new Map();
+    let bytes = 0;
+    const drop = (key) => {
+        const entry = entries.get(key);
+        if (!entry)
+            return;
+        entries.delete(key);
+        bytes -= entry.value.length;
+    };
+    return {
+        get(key) {
+            const entry = entries.get(key);
+            if (!entry)
+                return undefined;
+            if (entry.until <= Date.now()) {
+                drop(key);
+                return undefined;
+            }
+            // Re-inserted, so the Map's order is least recently used first.
+            entries.delete(key);
+            entries.set(key, entry);
+            return entry.value;
+        },
+        set(key, value, ttl) {
+            drop(key);
+            if (value.length > maxBytes)
+                return;
+            entries.set(key, { value, until: Date.now() + ttl * 1000 });
+            bytes += value.length;
+            while (bytes > maxBytes)
+                drop(entries.keys().next().value);
+        },
+    };
+}
+let warnedPageStore = false;
+/** A store that fails is a render, not a broken page: said once. */
+function pageStoreFailed(error) {
+    if (warnedPageStore)
+        return;
+    warnedPageStore = true;
+    console.warn("[rsc-kit] the page cache's store failed, so pages are being rendered each time instead:", error);
+}
+/** The engine's page cache, over a store: the app's, or one of its own in memory. */
+export function createPageCache(store) {
+    const inFlight = new Map();
+    return {
+        async lookup(key, request) {
+            let raw;
+            try {
+                raw = await store.get(`rsc-page|${key}`);
+            }
+            catch (error) {
+                pageStoreFailed(error);
+                return null;
+            }
+            if (!raw)
+                return null;
+            let kept;
+            try {
+                kept = JSON.parse(raw);
+            }
+            catch {
+                return null;
+            }
+            const now = Date.now();
+            const age = now - kept.at;
+            // The store may keep it longer than asked; the age is checked here.
+            // Past its time it is still served, for a while, as the stale copy a
+            // render in the background replaces: no visitor waits on an expiry.
+            if (age >= (kept.r + (kept.w ?? 0)) * 1000)
+                return null;
+            // A tag that moved is never served stale: whoever changed it is
+            // looking for the change, so this request renders.
+            if (Object.keys(kept.v).length > 0) {
+                try {
+                    const moved = await versionSource().changed(kept.v, 0);
+                    if (Object.keys(moved).some((tag) => moved[tag] !== kept.v[tag]))
+                        return null;
+                }
+                catch {
+                    // Not knowing whether it changed is not knowing it did not.
+                    return null;
+                }
+            }
+            const headers = new Headers(kept.h);
+            headers.set("Age", String(Math.floor((now - kept.at) / 1000)));
+            const etag = headers.get("ETag");
+            const stale = age >= kept.r * 1000;
+            if (kept.s === 200 && etag && matches(request.headers.get("If-None-Match"), etag)) {
+                return { response: new Response(null, { status: 304, headers }), stale };
+            }
+            return { response: new Response(request.method === "HEAD" ? null : kept.b, { status: kept.s, headers }), stale };
+        },
+        busy(key) {
+            return inFlight.has(key);
+        },
+        async keep(key, answer) {
+            const kept = keepable.get(answer);
+            if (!kept)
+                return;
+            let body;
+            try {
+                body = utf8.decode(kept.body);
+            }
+            catch {
+                // Not text: sent, never kept.
+                return;
+            }
+            const headers = [];
+            answer.headers.forEach((value, name) => {
+                if (!NOT_KEPT.has(name.toLowerCase()))
+                    headers.push([name, value]);
+            });
+            const notFound = kept.status === 404 || kept.notFound;
+            const revalidate = notFound ? Math.min(kept.revalidate, NOT_FOUND_LIMIT) : kept.revalidate;
+            // The same windows the answer's Cache-Control gives a CDN.
+            const window = notFound ? NOT_FOUND_LIMIT : STALE_WINDOW;
+            const page = { s: kept.status, h: headers, b: body, v: kept.versions, at: Date.now(), r: revalidate, w: window };
+            try {
+                await store.set(`rsc-page|${key}`, JSON.stringify(page), Math.ceil(revalidate + window));
+            }
+            catch (error) {
+                pageStoreFailed(error);
+            }
+        },
+        async once(key, render) {
+            const pending = inFlight.get(key);
+            if (pending) {
+                await pending.catch(() => { });
+                return { led: false };
+            }
+            const work = render();
+            inFlight.set(key, work);
+            try {
+                return { led: true, value: await work };
+            }
+            finally {
+                inFlight.delete(key);
+            }
+        },
+    };
 }
 //# sourceMappingURL=pageCache.js.map

package/dist/pageCache.js.map

@@ -1 +1 @@
-{"version":3,"file":"pageCache.js","sourceRoot":"","sources":["../src/pageCache.ts"],"names":[],"mappings":"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","sourcesContent":["// A page a shared cache may keep: `export const revalidate = N`.\n//\n// The page is rendered whole, judged, then sent. Public only when every check\n// passed for that render; otherwise `private, no-store`, exactly as before,\n// with `Cache-Status: rsc-kit; fwd=bypass; detail=<check>` saying which one\n// failed and a line in the log saying where. Cache-Control is the contract a\n// host caches by; Cache-Status is for counting and for the developer asking\n// why a page was not kept.\n//\n// The checks, in the order they can be made:\n//\n//   1. payload-url - a GET or HEAD, and a payload asked for at its own `?_rsc=<key>` url, and a\n//                    document never at one: a cache that ignores Vary keys on\n//                    the url alone, so either the other way round hands one\n//                    kind of answer to a request for the other\n//   2. the render read nothing that belongs to one visitor: cookies(),\n//      headers(), request(), connection() - in the page, a layout, a\n//      Suspense'd child, metadata or middleware.ts\n//   3. host-middleware - Laravel route middleware runs against the session\n//   4. set-cookie  - nothing set a cookie\n//   5. nonce       - no CSP nonce, which a shared copy would give everyone\n//   6. status      - 200 or 404; a redirect, a 5xx or a render React reported\n//                    as failed inside the payload (failed-render) never is\n//\n// A public answer carries `Cache-Tag`: the tags of every cache() answer the\n// render used, so a CDN can purge the copy when one of them changes.\n//\n// Backends render as nobody - see renderAsNobody() - so a session cookie set\n// by the backend on every call does not make every page private.\n\nimport { HEADER, PER_CLIENT } from \"./headers.js\";\nimport { PAYLOAD_PARAM, payloadKey, withoutPayloadKey } from \"./js/payloadKey.js\";\nimport { cacheTagsRead, renderFailed, visitorReads } from \"./request.js\";\n\n/** What a request for a `revalidate` page carries from the moment it arrives. */\nexport interface PageCaching {\n  /** Seconds a shared cache may keep the page. */\n  revalidate: number;\n  /** The url path, for the log line. */\n  path: string;\n  /** A check that failed before anything rendered, or after the page said notFound(). */\n  refused: string | null;\n}\n\n/** A 404 is kept no longer than this, however long its page may be. */\nconst NOT_FOUND_LIMIT = 60;\n\n/** How long a cache may serve a stale page while one request refreshes it, or while the origin is failing. */\nconst STALE_WINDOW = 86_400;\n\nconst caching = new WeakMap<Request, PageCaching>();\n\n/**\n * Decide, for a request as it arrived, whether its answer may be judged at all.\n *\n * Null for anything but a GET or HEAD of a page that exports revalidate - the\n * answer is then what it always was. Keyed by the request the app sees, so the\n * entry in front, which renders a 404, finds it again.\n */\nexport function cachingFor(arrived: Request, revalidate: number | undefined): PageCaching | null {\n  // A post is never kept, and its answer already says so.\n  if (!revalidate || revalidate <= 0 || (arrived.method !== \"GET\" && arrived.method !== \"HEAD\")) return null;\n\n  const url = new URL(arrived.url);\n  const entry: PageCaching = { revalidate, path: url.pathname, refused: urlRefusal(arrived, url) };\n\n  caching.set(withoutPayloadKey(arrived), entry);\n\n  return entry;\n}\n\n/** What cachingFor() decided for this request, if anything. */\nexport function cachingOf(request: Request): PageCaching | null {\n  return caching.get(withoutPayloadKey(request)) ?? null;\n}\n\n/**\n * Check 1. A payload answers at `?_rsc=<key>`, with the key its headers give;\n * a document never answers there. Either way round, a cache keying on the url\n * alone would hand a request one kind of answer for the other.\n */\nfunction urlRefusal(arrived: Request, url: URL): string | null {\n  const key = url.searchParams.get(PAYLOAD_PARAM);\n  const payload = arrived.headers.get(HEADER.rsc) !== null;\n\n  if (payload ? key !== payloadKey(arrived.headers) : key !== null) return \"payload-url\";\n\n  return null;\n}\n\n/**\n * Note what the render has read so far, for an answer that will be finished\n * somewhere else: the page said notFound(), and the entry in front renders\n * not-found.tsx in a scope of its own, where these reads are gone.\n */\nexport function noteReadsSoFar(entry: PageCaching): void {\n  entry.refused ??= readRefusal();\n}\n\nfunction readRefusal(): string | null {\n  if (renderFailed()) return \"failed-render\";\n\n  const read = visitorReads()[0];\n\n  return read ?? null;\n}\n\n/** The detail token a read is reported under: `cookies() in Header` is `cookies`. */\nfunction detailOf(refused: string): string {\n  return refused.replace(/\\(.*$/, \"\").replace(/[^a-z-]/gi, \"-\");\n}\n\nconst logged = new Set<string>();\n\nconst REASONS: Record<string, string> = {\n  \"payload-url\":\n    \"a payload was asked for without its ?_rsc= key, or a document with one. The router always adds it; this was another client.\",\n  \"host-middleware\": \"the route has host middleware, which runs against the visitor's session.\",\n  \"set-cookie\": \"the answer set a cookie.\",\n  nonce: \"the answer carries a CSP nonce, which a shared copy would give every visitor.\",\n  status: \"only a 200 or a 404 is kept.\",\n  \"failed-render\": \"React reported a failure inside the payload.\",\n};\n\n/** Once per page and reason: a page refused on every request says so once. */\nfunction logRefusal(entry: PageCaching, refused: string): void {\n  const key = `${entry.path}\\n${refused}`;\n\n  if (logged.has(key) || logged.size > 500) return;\n\n  logged.add(key);\n\n  // A read names what read, and where: `cookies() in Header`.\n  const why = REASONS[refused] ?? `${refused} reads this visitor.`;\n\n  console.warn(`[rsc-kit] ${entry.path} exports revalidate, and was sent private: ${why}`);\n}\n\nfunction bypass(response: Response, body: BodyInit | null, entry: PageCaching, refused: string): Response {\n  const headers = new Headers(response.headers);\n\n  headers.set(\"Cache-Control\", PER_CLIENT);\n  headers.set(\"Cache-Status\", `rsc-kit; fwd=bypass; detail=${detailOf(refused)}`);\n  headers.delete(\"ETag\");\n  logRefusal(entry, refused);\n\n  return new Response(body, { status: response.status, statusText: response.statusText, headers });\n}\n\n/**\n * What a public answer says: kept by shared caches for N seconds, refreshed\n * in the background for a day after that, never by the browser. A 404 for at\n * most a minute, so a scanner walking random urls cannot hold pages out.\n *\n * stale-if-error says the same window outright for an origin that is down,\n * erroring or mid-deploy: a cache left to choose may serve the error instead,\n * or a copy older than the page would ever have been kept for.\n */\nexport function publicCacheControl(revalidate: number, status: number): string {\n  return status === 404\n    ? `public, max-age=0, s-maxage=${Math.min(revalidate, NOT_FOUND_LIMIT)}, stale-while-revalidate=${NOT_FOUND_LIMIT}, stale-if-error=${NOT_FOUND_LIMIT}`\n    : `public, max-age=0, s-maxage=${revalidate}, stale-while-revalidate=${STALE_WINDOW}, stale-if-error=${STALE_WINDOW}`;\n}\n\n/** A tag a Cache-Tag list can carry: visible ASCII, no comma, which separates them. */\nconst TAG = /^[\\x21-\\x2b\\x2d-\\x7e]+$/;\n\nlet warnedTag = false;\n\n/**\n * The tags of every cache() answer a kept page used, as a CDN reads them:\n * `Cache-Tag: pages,post:1`. A purge by any of them drops the copy. A tag the\n * header cannot carry is left out, and said once: the copy then goes stale on\n * its own time, not on that change.\n */\nexport function cacheTagHeader(tags: readonly string[]): string | null {\n  const kept = tags.filter((tag) => TAG.test(tag));\n\n  if (kept.length < tags.length && !warnedTag) {\n    warnedTag = true;\n    const bad = tags.find((tag) => !TAG.test(tag));\n    console.warn(\n      `[rsc-kit] cache() tag ${JSON.stringify(bad)} cannot go in a Cache-Tag header (a comma, a space or a non-ASCII letter), so a CDN cannot purge by it.`,\n    );\n  }\n\n  return kept.length ? kept.join(\",\") : null;\n}\n\nasync function etagOf(body: ArrayBuffer): Promise<string> {\n  const digest = new Uint8Array(await crypto.subtle.digest(\"SHA-256\", body));\n  let hex = \"\";\n\n  for (let i = 0; i < 12; i++) hex += digest[i].toString(16).padStart(2, \"0\");\n\n  return `\"${hex}\"`;\n}\n\nfunction matches(ifNoneMatch: string | null, etag: string): boolean {\n  if (!ifNoneMatch) return false;\n\n  return ifNoneMatch\n    .split(\",\")\n    .map((tag) => tag.trim().replace(/^W\\//, \"\"))\n    .some((tag) => tag === etag || tag === \"*\");\n}\n\n/**\n * Finish the answer to a `revalidate` page: rendered whole, then judged.\n *\n * Called inside the request's scope, after every header the request will get\n * is on the answer - cookies included - so what it judges is what is sent.\n * Reading the body to its end is what waits for the render: a Suspense'd\n * child that reads cookies() is still running when the headers exist.\n */\nexport async function finishCacheable(\n  request: Request,\n  response: Response,\n  entry: PageCaching,\n  /**\n   * Whether the answer turned out to be not-found.tsx, asked once the body is\n   * read: a page can say notFound() in the middle of its stream, after a 200\n   * went out. A payload is a 200 either way - the router reads the page from\n   * it - but a not-found one is kept no longer than a 404.\n   */\n  saidNotFound: () => boolean = () => false,\n): Promise<Response> {\n  if (entry.refused) return bypass(response, response.body, entry, entry.refused);\n\n  if (response.status !== 200 && response.status !== 404) return bypass(response, response.body, entry, \"status\");\n\n  const type = response.headers.get(\"Content-Type\") ?? \"\";\n\n  if (!type.startsWith(\"text/html\") && !type.startsWith(\"text/x-component\")) {\n    return bypass(response, response.body, entry, \"status\");\n  }\n\n  const body = await response.arrayBuffer();\n  const refused =\n    readRefusal() ??\n    (response.headers.getSetCookie().length > 0 ? \"set-cookie\" : null) ??\n    (/'nonce-/.test(response.headers.get(\"Content-Security-Policy\") ?? \"\") ? \"nonce\" : null);\n\n  if (refused) return bypass(response, body, entry, refused);\n\n  const headers = new Headers(response.headers);\n  const etag = await etagOf(body);\n\n  headers.set(\"Cache-Control\", publicCacheControl(entry.revalidate, saidNotFound() ? 404 : response.status));\n  headers.set(\"ETag\", etag);\n\n  const tags = cacheTagHeader(cacheTagsRead());\n\n  if (tags) headers.set(\"Cache-Tag\", tags);\n\n  if (response.status === 200 && matches(request.headers.get(\"If-None-Match\"), etag)) {\n    headers.delete(\"Content-Length\");\n\n    return new Response(null, { status: 304, headers });\n  }\n\n  return new Response(request.method === \"HEAD\" ? null : body, { status: response.status, statusText: response.statusText, headers });\n}\n"]}
+{"version":3,"file":"pageCache.js","sourceRoot":"","sources":["../src/pageCache.ts"],"names":[],"mappings":"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","sourcesContent":["// A page a shared cache may keep: `export const revalidate = N`.\n//\n// The page is rendered whole, judged, then sent. Public only when every check\n// passed for that render; otherwise `private, no-store`, exactly as before,\n// with `Cache-Status: rsc-kit; fwd=bypass; detail=<check>` saying which one\n// failed and a line in the log saying where. Cache-Control is the contract a\n// host caches by; Cache-Status is for counting and for the developer asking\n// why a page was not kept.\n//\n// The checks, in the order they can be made:\n//\n//   1. payload-url - a GET or HEAD, and a payload asked for at its own `?_rsc=<key>` url, and a\n//                    document never at one: a cache that ignores Vary keys on\n//                    the url alone, so either the other way round hands one\n//                    kind of answer to a request for the other\n//   2. the render read nothing that belongs to one visitor: cookies(),\n//      headers(), request(), connection() - in the page, a layout, a\n//      Suspense'd child, metadata or middleware.ts\n//   3. host-middleware - Laravel route middleware runs against the session\n//   4. set-cookie  - nothing set a cookie\n//   5. nonce       - no CSP nonce, which a shared copy would give everyone\n//   6. status      - 200 or 404; a redirect, a 5xx or a render React reported\n//                    as failed inside the payload (failed-render) never is\n//\n// A public answer carries `Cache-Tag`: the tags of every cache() answer the\n// render used, so a CDN can purge the copy when one of them changes.\n//\n// Backends render as nobody - see renderAsNobody() - so a session cookie set\n// by the backend on every call does not make every page private.\n\nimport { HEADER, PER_CLIENT } from \"./headers.js\";\nimport { PAYLOAD_PARAM, payloadKey, withoutPayloadKey } from \"./js/payloadKey.js\";\nimport { cacheTagsRead, cacheTagVersionsRead, renderFailed, visitorReads } from \"./request.js\";\nimport type { CacheStore } from \"./cache.js\";\nimport { versionSource } from \"./changed.js\";\n\n/** What a request for a `revalidate` page carries from the moment it arrives. */\nexport interface PageCaching {\n  /** Seconds a shared cache may keep the page. */\n  revalidate: number;\n  /** The url path, for the log line. */\n  path: string;\n  /** A check that failed before anything rendered, or after the page said notFound(). */\n  refused: string | null;\n}\n\n/** A 404 is kept no longer than this, however long its page may be. */\nconst NOT_FOUND_LIMIT = 60;\n\n/** How long a cache may serve a stale page while one request refreshes it, or while the origin is failing. */\nconst STALE_WINDOW = 86_400;\n\nconst caching = new WeakMap<Request, PageCaching>();\n\n/**\n * Decide, for a request as it arrived, whether its answer may be judged at all.\n *\n * Null for anything but a GET or HEAD of a page that exports revalidate - the\n * answer is then what it always was. Keyed by the request the app sees, so the\n * entry in front, which renders a 404, finds it again.\n */\nexport function cachingFor(arrived: Request, revalidate: number | undefined): PageCaching | null {\n  // A post is never kept, and its answer already says so.\n  if (!revalidate || revalidate <= 0 || (arrived.method !== \"GET\" && arrived.method !== \"HEAD\")) return null;\n\n  const url = new URL(arrived.url);\n  const entry: PageCaching = { revalidate, path: url.pathname, refused: urlRefusal(arrived, url) };\n\n  caching.set(withoutPayloadKey(arrived), entry);\n\n  return entry;\n}\n\n/** What cachingFor() decided for this request, if anything. */\nexport function cachingOf(request: Request): PageCaching | null {\n  return caching.get(withoutPayloadKey(request)) ?? null;\n}\n\n/**\n * Check 1. A payload answers at `?_rsc=<key>`, with the key its headers give;\n * a document never answers there. Either way round, a cache keying on the url\n * alone would hand a request one kind of answer for the other.\n */\nfunction urlRefusal(arrived: Request, url: URL): string | null {\n  const key = url.searchParams.get(PAYLOAD_PARAM);\n  const payload = arrived.headers.get(HEADER.rsc) !== null;\n\n  if (payload ? key !== payloadKey(arrived.headers) : key !== null) return \"payload-url\";\n\n  return null;\n}\n\n/**\n * Note what the render has read so far, for an answer that will be finished\n * somewhere else: the page said notFound(), and the entry in front renders\n * not-found.tsx in a scope of its own, where these reads are gone.\n */\nexport function noteReadsSoFar(entry: PageCaching): void {\n  entry.refused ??= readRefusal();\n}\n\nfunction readRefusal(): string | null {\n  if (renderFailed()) return \"failed-render\";\n\n  const read = visitorReads()[0];\n\n  return read ?? null;\n}\n\n/** The detail token a read is reported under: `cookies() in Header` is `cookies`. */\nfunction detailOf(refused: string): string {\n  return refused.replace(/\\(.*$/, \"\").replace(/[^a-z-]/gi, \"-\");\n}\n\nconst logged = new Set<string>();\n\nconst REASONS: Record<string, string> = {\n  \"payload-url\":\n    \"a payload was asked for without its ?_rsc= key, or a document with one. The router always adds it; this was another client.\",\n  \"host-middleware\": \"the route has host middleware, which runs against the visitor's session.\",\n  \"set-cookie\": \"the answer set a cookie.\",\n  nonce: \"the answer carries a CSP nonce, which a shared copy would give every visitor.\",\n  status: \"only a 200 or a 404 is kept.\",\n  \"failed-render\": \"React reported a failure inside the payload.\",\n};\n\n/** Once per page and reason: a page refused on every request says so once. */\nfunction logRefusal(entry: PageCaching, refused: string): void {\n  const key = `${entry.path}\\n${refused}`;\n\n  if (logged.has(key) || logged.size > 500) return;\n\n  logged.add(key);\n\n  // A read names what read, and where: `cookies() in Header`.\n  const why = REASONS[refused] ?? `${refused} reads this visitor.`;\n\n  console.warn(`[rsc-kit] ${entry.path} exports revalidate, and was sent private: ${why}`);\n}\n\nfunction bypass(response: Response, body: BodyInit | null, entry: PageCaching, refused: string): Response {\n  const headers = new Headers(response.headers);\n\n  headers.set(\"Cache-Control\", PER_CLIENT);\n  headers.set(\"Cache-Status\", `rsc-kit; fwd=bypass; detail=${detailOf(refused)}`);\n  headers.delete(\"ETag\");\n  logRefusal(entry, refused);\n\n  return new Response(body, { status: response.status, statusText: response.statusText, headers });\n}\n\n/**\n * What a public answer says: kept by shared caches for N seconds, refreshed\n * in the background for a day after that, never by the browser. A 404 for at\n * most a minute, so a scanner walking random urls cannot hold pages out.\n *\n * stale-if-error says the same window outright for an origin that is down,\n * erroring or mid-deploy: a cache left to choose may serve the error instead,\n * or a copy older than the page would ever have been kept for.\n */\nexport function publicCacheControl(revalidate: number, status: number): string {\n  return status === 404\n    ? `public, max-age=0, s-maxage=${Math.min(revalidate, NOT_FOUND_LIMIT)}, stale-while-revalidate=${NOT_FOUND_LIMIT}, stale-if-error=${NOT_FOUND_LIMIT}`\n    : `public, max-age=0, s-maxage=${revalidate}, stale-while-revalidate=${STALE_WINDOW}, stale-if-error=${STALE_WINDOW}`;\n}\n\n/** A tag a Cache-Tag list can carry: visible ASCII, no comma, which separates them. */\nconst TAG = /^[\\x21-\\x2b\\x2d-\\x7e]+$/;\n\nlet warnedTag = false;\n\n/**\n * The tags of every cache() answer a kept page used, as a CDN reads them:\n * `Cache-Tag: pages,post:1`. A purge by any of them drops the copy. A tag the\n * header cannot carry is left out, and said once: the copy then goes stale on\n * its own time, not on that change.\n */\nexport function cacheTagHeader(tags: readonly string[]): string | null {\n  const kept = tags.filter((tag) => TAG.test(tag));\n\n  if (kept.length < tags.length && !warnedTag) {\n    warnedTag = true;\n    const bad = tags.find((tag) => !TAG.test(tag));\n    console.warn(\n      `[rsc-kit] cache() tag ${JSON.stringify(bad)} cannot go in a Cache-Tag header (a comma, a space or a non-ASCII letter), so a CDN cannot purge by it.`,\n    );\n  }\n\n  return kept.length ? kept.join(\",\") : null;\n}\n\nasync function etagOf(body: ArrayBuffer): Promise<string> {\n  const digest = new Uint8Array(await crypto.subtle.digest(\"SHA-256\", body));\n  let hex = \"\";\n\n  for (let i = 0; i < 12; i++) hex += digest[i].toString(16).padStart(2, \"0\");\n\n  return `\"${hex}\"`;\n}\n\nfunction matches(ifNoneMatch: string | null, etag: string): boolean {\n  if (!ifNoneMatch) return false;\n\n  return ifNoneMatch\n    .split(\",\")\n    .map((tag) => tag.trim().replace(/^W\\//, \"\"))\n    .some((tag) => tag === etag || tag === \"*\");\n}\n\n/**\n * Finish the answer to a `revalidate` page: rendered whole, then judged.\n *\n * Called inside the request's scope, after every header the request will get\n * is on the answer - cookies included - so what it judges is what is sent.\n * Reading the body to its end is what waits for the render: a Suspense'd\n * child that reads cookies() is still running when the headers exist.\n */\nexport async function finishCacheable(\n  request: Request,\n  response: Response,\n  entry: PageCaching,\n  /**\n   * Whether the answer turned out to be not-found.tsx, asked once the body is\n   * read: a page can say notFound() in the middle of its stream, after a 200\n   * went out. A payload is a 200 either way - the router reads the page from\n   * it - but a not-found one is kept no longer than a 404.\n   */\n  saidNotFound: () => boolean = () => false,\n): Promise<Response> {\n  if (entry.refused) return bypass(response, response.body, entry, entry.refused);\n\n  if (response.status !== 200 && response.status !== 404) return bypass(response, response.body, entry, \"status\");\n\n  const type = response.headers.get(\"Content-Type\") ?? \"\";\n\n  if (!type.startsWith(\"text/html\") && !type.startsWith(\"text/x-component\")) {\n    return bypass(response, response.body, entry, \"status\");\n  }\n\n  const body = await response.arrayBuffer();\n  const refused =\n    readRefusal() ??\n    (response.headers.getSetCookie().length > 0 ? \"set-cookie\" : null) ??\n    (/'nonce-/.test(response.headers.get(\"Content-Security-Policy\") ?? \"\") ? \"nonce\" : null);\n\n  if (refused) return bypass(response, body, entry, refused);\n\n  const headers = new Headers(response.headers);\n  const etag = await etagOf(body);\n\n  headers.set(\"Cache-Control\", publicCacheControl(entry.revalidate, saidNotFound() ? 404 : response.status));\n  headers.set(\"ETag\", etag);\n\n  const tags = cacheTagHeader(cacheTagsRead());\n\n  if (tags) headers.set(\"Cache-Tag\", tags);\n\n  const kept: Keepable = { status: response.status, body, versions: cacheTagVersionsRead(), revalidate: entry.revalidate, notFound: saidNotFound() };\n\n  if (response.status === 200 && matches(request.headers.get(\"If-None-Match\"), etag)) {\n    headers.delete(\"Content-Length\");\n\n    const answer = new Response(null, { status: 304, headers });\n\n    keepable.set(answer, kept);\n\n    return answer;\n  }\n\n  const answer = new Response(request.method === \"HEAD\" ? null : body, { status: response.status, statusText: response.statusText, headers });\n\n  keepable.set(answer, kept);\n\n  return answer;\n}\n\n// The engine's own copy of a public page: ISR on every host.\n//\n// A kept page is versioned, not purged. Its entry carries the version of\n// every tag its cache() answers were read under, and a lookup asks the\n// version source whether any moved since. changed(tag) bumps a version every\n// instance reads, so every pod misses at its next request with nothing sent\n// to it - and a render that was running when the change landed is stored\n// under the older version, so it is never served. Correctness needs only a\n// version source every instance shares; the store decides how often a page\n// is rendered, never whether a stale one is served.\n\n/** What finishCacheable() sent public, kept beside the answer for the page cache to store. */\ninterface Keepable {\n  status: number;\n  body: ArrayBuffer;\n  versions: Record<string, number>;\n  revalidate: number;\n  /** A not-found page, kept no longer than a 404. */\n  notFound: boolean;\n}\n\nconst keepable = new WeakMap<Response, Keepable>();\n\n/** A kept page, as the store holds it. */\ninterface KeptPage {\n  /** Status. */\n  s: number;\n  /** Headers, as name and value pairs. */\n  h: [string, string][];\n  /** Body, as text: HTML and Flight both are. */\n  b: string;\n  /** Tag versions it was rendered under. */\n  v: Record<string, number>;\n  /** When it was rendered, in ms. */\n  at: number;\n  /** Seconds it is fresh for. */\n  r: number;\n  /** Seconds past that it may still be served while one render replaces it. */\n  w: number;\n}\n\n/** Headers that belong to one answer, never to the kept page. */\nconst NOT_KEPT = new Set([\"date\", \"set-cookie\", \"content-length\", \"x-rsc-kit\", \"x-powered-by\", \"age\"]);\n\nconst utf8 = new TextDecoder(\"utf-8\", { fatal: true });\n\n/**\n * Pages kept in this process, by the size of what they hold: a page is tens\n * or hundreds of KB, so a count says nothing about memory. Least recently\n * used goes first.\n */\nexport function pageMemoryStore(maxBytes = 64 * 1024 * 1024): CacheStore {\n  const entries = new Map<string, { value: string; until: number }>();\n  let bytes = 0;\n\n  const drop = (key: string) => {\n    const entry = entries.get(key);\n\n    if (!entry) return;\n\n    entries.delete(key);\n    bytes -= entry.value.length;\n  };\n\n  return {\n    get(key) {\n      const entry = entries.get(key);\n\n      if (!entry) return undefined;\n\n      if (entry.until <= Date.now()) {\n        drop(key);\n\n        return undefined;\n      }\n\n      // Re-inserted, so the Map's order is least recently used first.\n      entries.delete(key);\n      entries.set(key, entry);\n\n      return entry.value;\n    },\n    set(key, value, ttl) {\n      drop(key);\n\n      if (value.length > maxBytes) return;\n\n      entries.set(key, { value, until: Date.now() + ttl * 1000 });\n      bytes += value.length;\n\n      while (bytes > maxBytes) drop(entries.keys().next().value!);\n    },\n  };\n}\n\n/** A kept answer, and whether it is past its time: served, while one render replaces it. */\nexport interface KeptAnswer {\n  response: Response;\n  stale: boolean;\n}\n\nexport interface PageCache {\n  /** The kept answer for this request, or null to render it now. */\n  lookup(key: string, request: Request): Promise<KeptAnswer | null>;\n  /** Whether a render for this key is running in this process. */\n  busy(key: string): boolean;\n  /** Keep the answer, when finishCacheable() sent it public. */\n  keep(key: string, answer: Response): Promise<void>;\n  /** Run one render per key at a time: a burst for a page nobody has kept waits for the first. */\n  once<T>(key: string, render: () => Promise<T>): Promise<{ led: boolean; value?: T }>;\n}\n\nlet warnedPageStore = false;\n\n/** A store that fails is a render, not a broken page: said once. */\nfunction pageStoreFailed(error: unknown): void {\n  if (warnedPageStore) return;\n  warnedPageStore = true;\n  console.warn(\"[rsc-kit] the page cache's store failed, so pages are being rendered each time instead:\", error);\n}\n\n/** The engine's page cache, over a store: the app's, or one of its own in memory. */\nexport function createPageCache(store: CacheStore): PageCache {\n  const inFlight = new Map<string, Promise<unknown>>();\n\n  return {\n    async lookup(key, request) {\n      let raw: string | null | undefined;\n\n      try {\n        raw = await store.get(`rsc-page|${key}`);\n      } catch (error) {\n        pageStoreFailed(error);\n\n        return null;\n      }\n\n      if (!raw) return null;\n\n      let kept: KeptPage;\n\n      try {\n        kept = JSON.parse(raw);\n      } catch {\n        return null;\n      }\n\n      const now = Date.now();\n      const age = now - kept.at;\n\n      // The store may keep it longer than asked; the age is checked here.\n      // Past its time it is still served, for a while, as the stale copy a\n      // render in the background replaces: no visitor waits on an expiry.\n      if (age >= (kept.r + (kept.w ?? 0)) * 1000) return null;\n\n      // A tag that moved is never served stale: whoever changed it is\n      // looking for the change, so this request renders.\n      if (Object.keys(kept.v).length > 0) {\n        try {\n          const moved = await versionSource().changed(kept.v, 0);\n\n          if (Object.keys(moved).some((tag) => moved[tag] !== kept.v[tag])) return null;\n        } catch {\n          // Not knowing whether it changed is not knowing it did not.\n          return null;\n        }\n      }\n\n      const headers = new Headers(kept.h);\n\n      headers.set(\"Age\", String(Math.floor((now - kept.at) / 1000)));\n\n      const etag = headers.get(\"ETag\");\n\n      const stale = age >= kept.r * 1000;\n\n      if (kept.s === 200 && etag && matches(request.headers.get(\"If-None-Match\"), etag)) {\n        return { response: new Response(null, { status: 304, headers }), stale };\n      }\n\n      return { response: new Response(request.method === \"HEAD\" ? null : kept.b, { status: kept.s, headers }), stale };\n    },\n\n    busy(key) {\n      return inFlight.has(key);\n    },\n\n    async keep(key, answer) {\n      const kept = keepable.get(answer);\n\n      if (!kept) return;\n\n      let body: string;\n\n      try {\n        body = utf8.decode(kept.body);\n      } catch {\n        // Not text: sent, never kept.\n        return;\n      }\n\n      const headers: [string, string][] = [];\n\n      answer.headers.forEach((value, name) => {\n        if (!NOT_KEPT.has(name.toLowerCase())) headers.push([name, value]);\n      });\n\n      const notFound = kept.status === 404 || kept.notFound;\n      const revalidate = notFound ? Math.min(kept.revalidate, NOT_FOUND_LIMIT) : kept.revalidate;\n      // The same windows the answer's Cache-Control gives a CDN.\n      const window = notFound ? NOT_FOUND_LIMIT : STALE_WINDOW;\n      const page: KeptPage = { s: kept.status, h: headers, b: body, v: kept.versions, at: Date.now(), r: revalidate, w: window };\n\n      try {\n        await store.set(`rsc-page|${key}`, JSON.stringify(page), Math.ceil(revalidate + window));\n      } catch (error) {\n        pageStoreFailed(error);\n      }\n    },\n\n    async once(key, render) {\n      const pending = inFlight.get(key);\n\n      if (pending) {\n        await pending.catch(() => {});\n\n        return { led: false };\n      }\n\n      const work = render();\n\n      inFlight.set(key, work);\n\n      try {\n        return { led: true, value: await work };\n      } finally {\n        inFlight.delete(key);\n      }\n    },\n  };\n}\n"]}

package/dist/purge.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Telling a CDN that kept pages changed.
+ *
+ * A `revalidate` page goes out with `Cache-Tag`, and a CDN that purges by tag
+ * can drop it the moment one of those tags changes, rather than waiting out
+ * `s-maxage`. What calls the purge is the app's: every CDN has its own API, so
+ * the engine has one hook, `installPurge()`, and `changed(tag)` calls it with
+ * the names that changed - after the answer has gone, through `after()`, so a
+ * slow CDN never holds up the action that made the change.
+ *
+ * Homeport is the one installed for you: with `HOMEPORT_PURGE_URL` set, the
+ * hook is `homeportPurge()` unless the app installed another.
+ *
+ * A Laravel or Go backend changes its names itself (`Rsc::changed()`,
+ * `rsckit.Changed()`), and the engine never hears of it, so each backend
+ * purges for its own changes. This hook covers `changed()` called here.
+ */
+/** What a purge drops: pages carrying any of these tags, pages at these paths, or everything. */
+export interface Purge {
+    tags?: readonly string[];
+    paths?: readonly string[];
+    all?: boolean;
+}
+/** Sends a purge to a CDN. A rejection is logged; it never fails the change. */
+export type Purger = (purge: Purge) => Promise<void> | void;
+/** Install the app's purge. `null` takes it out, and Homeport's default with it. */
+export declare function installPurge(purger: Purger | null): void;
+/** The purge in use: the app's, else Homeport's when its url is set, else none. */
+export declare function installedPurge(): Purger | null;
+/**
+ * @internal For changed(): purge these tags once the answer has gone, or at
+ * once outside a request. Does nothing when no purge is installed.
+ */
+export declare function purgeLater(tags: readonly string[]): void;
+/**
+ * Send a purge now, through the installed purge. For an app's own use - a
+ * deploy step, a webhook - as well as changed()'s. Never throws: the change
+ * it follows is already made, and a CDN that missed it still drops the copy
+ * at `s-maxage`. The first failure is logged.
+ */
+export declare function purge(what: Purge): Promise<void>;
+/** Homeport takes at most this many tags, and this many paths, per call. */
+export declare const HOMEPORT_PURGE_LIMIT = 100;
+export interface HomeportPurgeOptions {
+    /** Where to post. Default `HOMEPORT_PURGE_URL`, which Homeport sets. */
+    url?: string;
+    /** For tests. */
+    fetch?: typeof fetch;
+}
+/**
+ * Homeport's purge: `POST {tags, paths, all}` to the url Homeport gives the
+ * app, no token - it is reachable only from inside the app's own network.
+ * Split into calls of 100 tags and 100 paths. A 429 is tried once more after
+ * its `Retry-After` (at most five seconds); anything else that is not a 2xx
+ * rejects.
+ */
+export declare function homeportPurge(options?: HomeportPurgeOptions): Purger;

package/dist/purge.js

@@ -0,0 +1,147 @@
+/**
+ * Telling a CDN that kept pages changed.
+ *
+ * A `revalidate` page goes out with `Cache-Tag`, and a CDN that purges by tag
+ * can drop it the moment one of those tags changes, rather than waiting out
+ * `s-maxage`. What calls the purge is the app's: every CDN has its own API, so
+ * the engine has one hook, `installPurge()`, and `changed(tag)` calls it with
+ * the names that changed - after the answer has gone, through `after()`, so a
+ * slow CDN never holds up the action that made the change.
+ *
+ * Homeport is the one installed for you: with `HOMEPORT_PURGE_URL` set, the
+ * hook is `homeportPurge()` unless the app installed another.
+ *
+ * A Laravel or Go backend changes its names itself (`Rsc::changed()`,
+ * `rsckit.Changed()`), and the engine never hears of it, so each backend
+ * purges for its own changes. This hook covers `changed()` called here.
+ */
+function hooks() {
+    return (globalThis[Symbol.for("rsc-kit.after")] ?? {
+        after: (work) => void Promise.resolve().then(work),
+        requestKey: () => null,
+    });
+}
+// On the global, like the cache store: an app installs through its own copy
+// of the package, and the engine's copy is the one that calls it.
+const PURGER = Symbol.for("rsc-kit.purger");
+const globals = globalThis;
+/** Install the app's purge. `null` takes it out, and Homeport's default with it. */
+export function installPurge(purger) {
+    globals[PURGER] = purger;
+}
+/** The purge in use: the app's, else Homeport's when its url is set, else none. */
+export function installedPurge() {
+    const installed = globals[PURGER];
+    if (installed !== undefined)
+        return installed;
+    const url = homeportPurgeUrl();
+    return url ? homeportPurge({ url }) : null;
+}
+function homeportPurgeUrl() {
+    return globalThis.process?.env?.HOMEPORT_PURGE_URL || undefined;
+}
+// The names an action changed go out as one purge when its answer has gone:
+// three changed() calls send one request, not three. Gathered per request,
+// so a request whose after() work never ran cannot hold back another's.
+const pendingFor = new WeakMap();
+/**
+ * @internal For changed(): purge these tags once the answer has gone, or at
+ * once outside a request. Does nothing when no purge is installed.
+ */
+export function purgeLater(tags) {
+    if (tags.length === 0 || !installedPurge())
+        return;
+    const { after, requestKey } = hooks();
+    const key = requestKey();
+    if (!key) {
+        after(() => purge({ tags }));
+        return;
+    }
+    let pending = pendingFor.get(key);
+    if (pending) {
+        for (const tag of tags)
+            pending.add(tag);
+        return;
+    }
+    pending = new Set(tags);
+    pendingFor.set(key, pending);
+    const gathered = pending;
+    after(() => {
+        pendingFor.delete(key);
+        return purge({ tags: [...gathered] });
+    });
+}
+let warnedPurge = false;
+/**
+ * Send a purge now, through the installed purge. For an app's own use - a
+ * deploy step, a webhook - as well as changed()'s. Never throws: the change
+ * it follows is already made, and a CDN that missed it still drops the copy
+ * at `s-maxage`. The first failure is logged.
+ */
+export async function purge(what) {
+    const purger = installedPurge();
+    if (!purger)
+        return;
+    try {
+        await purger(what);
+    }
+    catch (error) {
+        if (!warnedPurge) {
+            warnedPurge = true;
+            console.warn("[rsc-kit] purging the CDN failed; its copy is dropped at s-maxage instead: " +
+                (error instanceof Error ? error.message : String(error)));
+        }
+    }
+}
+/** Homeport takes at most this many tags, and this many paths, per call. */
+export const HOMEPORT_PURGE_LIMIT = 100;
+/**
+ * Homeport's purge: `POST {tags, paths, all}` to the url Homeport gives the
+ * app, no token - it is reachable only from inside the app's own network.
+ * Split into calls of 100 tags and 100 paths. A 429 is tried once more after
+ * its `Retry-After` (at most five seconds); anything else that is not a 2xx
+ * rejects.
+ */
+export function homeportPurge(options = {}) {
+    return async (what) => {
+        const url = options.url ?? homeportPurgeUrl();
+        if (!url)
+            throw new Error("homeportPurge() has no url: HOMEPORT_PURGE_URL is not set.");
+        const send = options.fetch ?? fetch;
+        const tags = [...(what.tags ?? [])];
+        const paths = [...(what.paths ?? [])];
+        const bodies = [];
+        if (what.all)
+            bodies.push({ all: true });
+        while (tags.length > 0 || paths.length > 0) {
+            const body = {};
+            const someTags = tags.splice(0, HOMEPORT_PURGE_LIMIT);
+            const somePaths = paths.splice(0, HOMEPORT_PURGE_LIMIT);
+            if (someTags.length > 0)
+                body.tags = someTags;
+            if (somePaths.length > 0)
+                body.paths = somePaths;
+            bodies.push(body);
+        }
+        for (const body of bodies) {
+            await post(send, url, body);
+        }
+    };
+}
+async function post(send, url, body, retried = false) {
+    const response = await send(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    await response.body?.cancel();
+    if (response.ok)
+        return;
+    if (response.status === 429 && !retried) {
+        const seconds = Math.min(Number(response.headers.get("Retry-After")) || 1, 5);
+        await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
+        return post(send, url, body, true);
+    }
+    throw new Error(`Homeport answered ${response.status} to a purge of ${JSON.stringify(body)}.`);
+}
+//# sourceMappingURL=purge.js.map

package/dist/purge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"purge.js","sourceRoot":"","sources":["../src/purge.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Telling a CDN that kept pages changed.\n *\n * A `revalidate` page goes out with `Cache-Tag`, and a CDN that purges by tag\n * can drop it the moment one of those tags changes, rather than waiting out\n * `s-maxage`. What calls the purge is the app's: every CDN has its own API, so\n * the engine has one hook, `installPurge()`, and `changed(tag)` calls it with\n * the names that changed - after the answer has gone, through `after()`, so a\n * slow CDN never holds up the action that made the change.\n *\n * Homeport is the one installed for you: with `HOMEPORT_PURGE_URL` set, the\n * hook is `homeportPurge()` unless the app installed another.\n *\n * A Laravel or Go backend changes its names itself (`Rsc::changed()`,\n * `rsckit.Changed()`), and the engine never hears of it, so each backend\n * purges for its own changes. This hook covers `changed()` called here.\n */\n\n// Not imported: @rsc-kit/core/changed reaches this file and a client component\n// may import that, so request.ts - server-only - is found through the global\n// it sets when the server loads it. Without it, there is no request to wait\n// for, and a purge goes out at once.\ntype AfterHooks = { after: (work: () => unknown) => void; requestKey: () => object | null };\n\nfunction hooks(): AfterHooks {\n  return (\n    ((globalThis as Record<symbol, unknown>)[Symbol.for(\"rsc-kit.after\")] as AfterHooks | undefined) ?? {\n      after: (work) => void Promise.resolve().then(work),\n      requestKey: () => null,\n    }\n  );\n}\n\n/** What a purge drops: pages carrying any of these tags, pages at these paths, or everything. */\nexport interface Purge {\n  tags?: readonly string[];\n  paths?: readonly string[];\n  all?: boolean;\n}\n\n/** Sends a purge to a CDN. A rejection is logged; it never fails the change. */\nexport type Purger = (purge: Purge) => Promise<void> | void;\n\n// On the global, like the cache store: an app installs through its own copy\n// of the package, and the engine's copy is the one that calls it.\nconst PURGER = Symbol.for(\"rsc-kit.purger\");\nconst globals = globalThis as unknown as Record<symbol, Purger | null | undefined>;\n\n/** Install the app's purge. `null` takes it out, and Homeport's default with it. */\nexport function installPurge(purger: Purger | null): void {\n  globals[PURGER] = purger;\n}\n\n/** The purge in use: the app's, else Homeport's when its url is set, else none. */\nexport function installedPurge(): Purger | null {\n  const installed = globals[PURGER];\n\n  if (installed !== undefined) return installed;\n\n  const url = homeportPurgeUrl();\n\n  return url ? homeportPurge({ url }) : null;\n}\n\nfunction homeportPurgeUrl(): string | undefined {\n  return (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env?.HOMEPORT_PURGE_URL || undefined;\n}\n\n// The names an action changed go out as one purge when its answer has gone:\n// three changed() calls send one request, not three. Gathered per request,\n// so a request whose after() work never ran cannot hold back another's.\nconst pendingFor = new WeakMap<object, Set<string>>();\n\n/**\n * @internal For changed(): purge these tags once the answer has gone, or at\n * once outside a request. Does nothing when no purge is installed.\n */\nexport function purgeLater(tags: readonly string[]): void {\n  if (tags.length === 0 || !installedPurge()) return;\n\n  const { after, requestKey } = hooks();\n  const key = requestKey();\n\n  if (!key) {\n    after(() => purge({ tags }));\n\n    return;\n  }\n\n  let pending = pendingFor.get(key);\n\n  if (pending) {\n    for (const tag of tags) pending.add(tag);\n\n    return;\n  }\n\n  pending = new Set(tags);\n  pendingFor.set(key, pending);\n\n  const gathered = pending;\n\n  after(() => {\n    pendingFor.delete(key);\n\n    return purge({ tags: [...gathered] });\n  });\n}\n\nlet warnedPurge = false;\n\n/**\n * Send a purge now, through the installed purge. For an app's own use - a\n * deploy step, a webhook - as well as changed()'s. Never throws: the change\n * it follows is already made, and a CDN that missed it still drops the copy\n * at `s-maxage`. The first failure is logged.\n */\nexport async function purge(what: Purge): Promise<void> {\n  const purger = installedPurge();\n\n  if (!purger) return;\n\n  try {\n    await purger(what);\n  } catch (error) {\n    if (!warnedPurge) {\n      warnedPurge = true;\n      console.warn(\n        \"[rsc-kit] purging the CDN failed; its copy is dropped at s-maxage instead: \" +\n          (error instanceof Error ? error.message : String(error)),\n      );\n    }\n  }\n}\n\n/** Homeport takes at most this many tags, and this many paths, per call. */\nexport const HOMEPORT_PURGE_LIMIT = 100;\n\nexport interface HomeportPurgeOptions {\n  /** Where to post. Default `HOMEPORT_PURGE_URL`, which Homeport sets. */\n  url?: string;\n  /** For tests. */\n  fetch?: typeof fetch;\n}\n\n/**\n * Homeport's purge: `POST {tags, paths, all}` to the url Homeport gives the\n * app, no token - it is reachable only from inside the app's own network.\n * Split into calls of 100 tags and 100 paths. A 429 is tried once more after\n * its `Retry-After` (at most five seconds); anything else that is not a 2xx\n * rejects.\n */\nexport function homeportPurge(options: HomeportPurgeOptions = {}): Purger {\n  return async (what) => {\n    const url = options.url ?? homeportPurgeUrl();\n\n    if (!url) throw new Error(\"homeportPurge() has no url: HOMEPORT_PURGE_URL is not set.\");\n\n    const send = options.fetch ?? fetch;\n    const tags = [...(what.tags ?? [])];\n    const paths = [...(what.paths ?? [])];\n    const bodies: Purge[] = [];\n\n    if (what.all) bodies.push({ all: true });\n\n    while (tags.length > 0 || paths.length > 0) {\n      const body: Purge = {};\n      const someTags = tags.splice(0, HOMEPORT_PURGE_LIMIT);\n      const somePaths = paths.splice(0, HOMEPORT_PURGE_LIMIT);\n\n      if (someTags.length > 0) body.tags = someTags;\n      if (somePaths.length > 0) body.paths = somePaths;\n      bodies.push(body);\n    }\n\n    for (const body of bodies) {\n      await post(send, url, body);\n    }\n  };\n}\n\nasync function post(send: typeof fetch, url: string, body: Purge, retried = false): Promise<void> {\n  const response = await send(url, {\n    method: \"POST\",\n    headers: { \"Content-Type\": \"application/json\" },\n    body: JSON.stringify(body),\n  });\n\n  await response.body?.cancel();\n\n  if (response.ok) return;\n\n  if (response.status === 429 && !retried) {\n    const seconds = Math.min(Number(response.headers.get(\"Retry-After\")) || 1, 5);\n\n    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));\n\n    return post(send, url, body, true);\n  }\n\n  throw new Error(`Homeport answered ${response.status} to a purge of ${JSON.stringify(body)}.`);\n}\n"]}

package/dist/request.d.ts

@@ -216,7 +216,9 @@ export declare function renderingAsNobody(): boolean;
  * everyone: the kept copy is stale when any of them changes, and its Cache-Tag
  * lets a CDN purge it then. A no-op anywhere else.
  */
-export declare function noteCacheTags(tags: readonly string[]): void;
+export declare function noteCacheTags(tags: readonly string[], versions?: Record<string, number>): void;
+/** The version of each tag noteCacheTags() collected, as it was first read. */
+export declare function cacheTagVersionsRead(): Record<string, number>;
 /** The tags noteCacheTags() collected in the render that is open, in order. */
 export declare function cacheTagsRead(): string[];
 /** What read the visitor in a render renderAsNobody() marked, in order. */
@@ -268,6 +270,12 @@ export declare function noteFallback(text: string): void;
  * gone. Outside a request - a build - the work runs at once.
  */
 export declare function after(work: () => unknown): void;
+/**
+ * @internal The request being answered, as an object to key per-request
+ * state on - null outside one. For work that gathers itself into one after():
+ * a purge of every name an action changed.
+ */
+export declare function requestKey(): object | null;
 /**
  * @internal For the host: the work `after()` collected for this request, as
  * one promise that never rejects. Taken once; a second call has nothing.

package/dist/request.js

@@ -632,14 +632,24 @@ export function renderingAsNobody() {
  * everyone: the kept copy is stale when any of them changes, and its Cache-Tag
  * lets a CDN purge it then. A no-op anywhere else.
  */
-export function noteCacheTags(tags) {
+export function noteCacheTags(tags, versions = {}) {
     const store = scope()?.getStore();
     if (!store?.request || !store.asNobody || tags.length === 0)
         return;
     const list = (store.tags ??= []);
-    for (const tag of tags)
+    const seen = (store.tagVersions ??= {});
+    for (const tag of tags) {
         if (!list.includes(tag))
             list.push(tag);
+        // The first read wins: a tag that moved mid-render leaves the older
+        // version on the kept page, so the next lookup sees the move and misses.
+        if (!(tag in seen))
+            seen[tag] = versions[tag] ?? 0;
+    }
+}
+/** The version of each tag noteCacheTags() collected, as it was first read. */
+export function cacheTagVersionsRead() {
+    return { ...(scope()?.getStore()?.tagVersions ?? {}) };
 }
 /** The tags noteCacheTags() collected in the render that is open, in order. */
 export function cacheTagsRead() {
@@ -732,6 +742,18 @@ export function after(work) {
     }
     store.after.push(work);
 }
+/**
+ * @internal The request being answered, as an object to key per-request
+ * state on - null outside one. For work that gathers itself into one after():
+ * a purge of every name an action changed.
+ */
+export function requestKey() {
+    const store = scope()?.getStore();
+    return store?.request ? store : null;
+}
+// For purge.ts, which @rsc-kit/core/changed brings into client code and so
+// cannot import this file: the two calls it needs, on the global.
+globalThis[Symbol.for("rsc-kit.after")] = { after, requestKey };
 function reportAfter(error) {
     console.error("[rsc-kit] after() work failed:", error);
 }