@nifrajs/web 4.0.0 → 5.0.0

package/dist/isr.js

@@ -6,6 +6,7 @@
  *
  * This module is the store primitive; the SWR wrapper (`withISR`) builds on it next.
  */
+import { isAuthenticatedRequest, writableResponse } from "@nifrajs/core/server";
 import { isDraftEnabled } from "./draft.js";
 import { assertTokenSecret, timingSafeEqual } from "./internal/timing-safe-equal.js";
 const ISR_TAG_PATTERN = /^[A-Za-z][A-Za-z0-9._:/-]{0,127}$/;
@@ -81,6 +82,10 @@ export class MemoryCacheStore {
     cache = new Map();
     max;
     tagEpoch = new Map();
+    // Purge order: `fence` reads it; each purge advances it and records where, per key and per tag.
+    order = 0;
+    purgedKeys = new Map();
+    purgedTags = new Map();
     constructor(options = {}) {
         const isProd = typeof process !== "undefined" && process.env?.NODE_ENV === "production";
         if (options.allowInProduction !== true && isProd) {
@@ -113,8 +118,13 @@ export class MemoryCacheStore {
         }
         return Promise.resolve(value);
     }
+    fence() {
+        return this.order;
+    }
     set(key, value) {
         const tags = normalizeTags(value.tags);
+        if (value.fence !== undefined && this.purgedAfter(key, tags, value.fence))
+            return Promise.resolve();
         const tagEpochs = {};
         for (const tag of tags)
             tagEpochs[tag] = this.tagEpoch.get(tag) ?? "0";
@@ -131,12 +141,14 @@ export class MemoryCacheStore {
     }
     delete(key) {
         this.cache.delete(key);
+        this.markPurged(this.purgedKeys, key);
         this.pruneTagEpochs();
         return Promise.resolve();
     }
     invalidateTag(tag) {
         normalizeTag(tag);
         this.tagEpoch.set(tag, crypto.randomUUID());
+        this.markPurged(this.purgedTags, tag);
         // This store is bounded and local, so eagerly remove matching rows. It keeps invalidation
         // immediate and lets us discard epoch keys that no retained entry references anymore.
         for (const [key, row] of this.cache) {
@@ -146,6 +158,22 @@ export class MemoryCacheStore {
         this.pruneTagEpochs();
         return Promise.resolve();
     }
+    purgedAfter(key, tags, fence) {
+        if ((this.purgedKeys.get(key) ?? 0) > fence)
+            return true;
+        return tags.some((tag) => (this.purgedTags.get(tag) ?? 0) > fence);
+    }
+    markPurged(marks, name) {
+        marks.delete(name);
+        marks.set(name, ++this.order);
+        // Bounded like the entries: a mark matters only to a render still in flight.
+        while (marks.size > this.max) {
+            const oldest = marks.keys().next().value;
+            if (oldest === undefined)
+                break;
+            marks.delete(oldest);
+        }
+    }
     pruneTagEpochs() {
         if (this.tagEpoch.size === 0)
             return;
@@ -169,12 +197,21 @@ const isCachedResponse = (value) => {
     if (typeof value !== "object" || value === null)
         return false;
     const v = value;
+    // Everything a replay hands to `new Response` must be legal there, or a corrupt record would throw
+    // on every hit instead of reading as a miss.
     if (typeof v.body !== "string" ||
         typeof v.status !== "number" ||
+        !Number.isInteger(v.status) ||
+        v.status < 200 ||
+        v.status > 599 ||
         typeof v.storedAt !== "number" ||
+        !Number.isFinite(v.storedAt) ||
         typeof v.revalidate !== "number" ||
+        !Number.isFinite(v.revalidate) ||
+        v.revalidate < 0 ||
         typeof v.headers !== "object" ||
-        v.headers === null) {
+        v.headers === null ||
+        Array.isArray(v.headers)) {
         return false;
     }
     if (v.tags !== undefined) {
@@ -187,13 +224,55 @@ const isCachedResponse = (value) => {
             return false;
         }
     }
-    for (const headerValue of Object.values(v.headers)) {
+    const headers = {};
+    for (const [name, headerValue] of Object.entries(v.headers)) {
         if (typeof headerValue !== "string")
             return false;
+        headers[name] = headerValue;
+    }
+    try {
+        new Headers(headers);
+    }
+    catch {
+        return false;
     }
     return true;
 };
 const KV_TAG_EPOCH_PREFIX = "__nifra_isr_tag_v1:";
+const KV_PURGED_AT = "__nifraPurgedAt";
+/** When a KV page key was purged, from the marker `delete` leaves; `-Infinity` for a page or nothing. */
+function kvPurgedAt(raw) {
+    if (raw === null || !raw.includes(KV_PURGED_AT))
+        return Number.NEGATIVE_INFINITY;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" && parsed !== null && KV_PURGED_AT in parsed) {
+            const at = parsed[KV_PURGED_AT];
+            if (typeof at === "number")
+                return at;
+        }
+    }
+    catch {
+        // Not a marker.
+    }
+    return Number.NEGATIVE_INFINITY;
+}
+/** When a tag epoch was written (`<time>:<uuid>`); an epoch from before epochs carried a time is older
+ * than any render. */
+function kvEpochTime(epoch) {
+    const at = epoch.indexOf(":");
+    const time = at === -1 ? Number.NaN : Number(epoch.slice(0, at));
+    return Number.isFinite(time) ? time : Number.NEGATIVE_INFINITY;
+}
+let lastKvTime = 0;
+/** Wall-clock ms, strictly increasing per process so a purge orders after a render it follows. Not
+ * `timeOrigin + performance.now()`: that clock stops while the host sleeps, so a purge from a process
+ * that slept would order before renders other instances began earlier. */
+const kvClock = () => {
+    const now = Date.now();
+    lastKvTime = now > lastKvTime ? now : lastKvTime + 0.001;
+    return lastKvTime;
+};
 /**
  * A {@link CacheStore} backed by a **Cloudflare Workers KV** namespace (or any {@link KVNamespaceLike}
  * binding) - the production-grade shared/durable store ISR wants: cached pages and on-demand purges
@@ -256,29 +335,42 @@ export class KVCacheStore {
         const { __nifraTagEpochs: _ignored, ...value } = parsed;
         return value;
     }
+    /** Wall-clock time, so purges on any instance order against it. KV is eventually consistent, so the
+     * fence holds only for purges this location has already seen. */
+    fence() {
+        return kvClock();
+    }
     async set(key, value) {
-        const tags = normalizeTags(value.tags);
+        const { fence, ...entry } = value;
+        if (fence !== undefined && kvPurgedAt(await this.kv.get(key)) > fence)
+            return;
+        const tags = normalizeTags(entry.tags);
         if (tags.length === 0) {
-            await this.kv.put(key, JSON.stringify(value), this.putOptions);
+            await this.kv.put(key, JSON.stringify(entry), this.putOptions);
             return;
         }
         const epochs = Object.fromEntries(await Promise.all(tags.map(async (tag) => [tag, (await this.kv.get(this.tagKey(tag))) ?? "0"])));
+        if (fence !== undefined && Object.values(epochs).some((epoch) => kvEpochTime(epoch) > fence)) {
+            return;
+        }
         const stored = {
-            ...value,
+            ...entry,
             tags,
             __nifraTagEpochs: epochs,
         };
         await this.kv.put(key, JSON.stringify(stored), this.putOptions);
     }
+    /** Leaves a marker rather than removing the key, so `set` can refuse a render that began before
+     * the purge. The marker reads as a miss. */
     async delete(key) {
-        await this.kv.delete(key);
+        await this.kv.put(key, JSON.stringify({ [KV_PURGED_AT]: kvClock() }), this.putOptions);
     }
     async invalidateTag(tag) {
         normalizeTag(tag);
         // Epoch invalidation avoids KV key enumeration and remains bounded for a tag with millions of
         // pages. Epoch keys intentionally have no expiration: an expired epoch would resurrect entries
-        // written before the invalidation when their page key still exists.
-        await this.kv.put(this.tagKey(tag), crypto.randomUUID());
+        // written before the invalidation when their page key still exists. The time orders it for `set`.
+        await this.kv.put(this.tagKey(tag), `${kvClock()}:${crypto.randomUUID()}`);
     }
     tagKey(tag) {
         return `${KV_TAG_EPOCH_PREFIX}${encodeURIComponent(tag)}`;
@@ -310,18 +402,30 @@ export function withoutCacheChannel(res) {
     if (!res.headers.has(ISR_REVALIDATE_HEADER) && !res.headers.has(ISR_REVALIDATE_TAGS_HEADER)) {
         return res;
     }
+    const target = writableResponse(res);
+    target.headers.delete(ISR_REVALIDATE_HEADER);
+    target.headers.delete(ISR_REVALIDATE_TAGS_HEADER);
+    return target;
+}
+const STORE_FAILED = Symbol("nifra.isr.store-failed");
+const STORE_REPORT_INTERVAL_MS = 60_000;
+const STORE_REPORT_DETAIL_CHARS = 200;
+/** The error's own words with the cache key cut out, since a store may name the key it failed on. */
+function storeErrorDetail(error, key) {
+    const text = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+    let path;
     try {
-        res.headers.delete(ISR_REVALIDATE_HEADER);
-        res.headers.delete(ISR_REVALIDATE_TAGS_HEADER);
-        return res;
+        path = new URL(key).pathname;
     }
     catch {
-        // A `fetch()` response has immutable headers: rebuild it around the same body instead.
-        const headers = new Headers(res.headers);
-        headers.delete(ISR_REVALIDATE_HEADER);
-        headers.delete(ISR_REVALIDATE_TAGS_HEADER);
-        return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+        path = undefined;
     }
+    let redacted = text.split(key).join("<key>");
+    if (path !== undefined && path.length > 1)
+        redacted = redacted.split(path).join("<key>");
+    return redacted.length > STORE_REPORT_DETAIL_CHARS
+        ? `${redacted.slice(0, STORE_REPORT_DETAIL_CHARS)}...`
+        : redacted;
 }
 /** `createWebApp`'s marker for how its documents meet a CSP (see `DOCUMENT_POLICY` in ./csp.ts). Read
  * through the global symbol registry so a cache wrapper never imports the CSP module. */
@@ -376,7 +480,18 @@ const cacheControlHas = (headers, names) => {
     return names.some((name) => directives.includes(name));
 };
 const hasSetCookie = (headers) => headers.has("set-cookie") || (headers.getSetCookie?.().length ?? 0) > 0;
-const requestCarriesPrivateState = (req) => req.headers.has("authorization") || req.headers.has("cookie");
+/** Whether every cookie in a `Cookie` header is named in `names`. */
+const cookieNamesWithin = (header, names) => {
+    for (const pair of header.split(";")) {
+        const name = pair.split("=", 1)[0]?.trim() ?? "";
+        if (name !== "" && !names.has(name))
+            return false;
+    }
+    return true;
+};
+// An authentication stage may read any header, so a request it accepted is private whatever carried
+// the credential. The mark is set on the request the app was handed, which is why this runs after it.
+const requestCarriesPrivateState = (req) => req.headers.has("authorization") || req.headers.has("cookie") || isAuthenticatedRequest(req);
 const responseIsExplicitlyPublic = (res) => cacheControlHas(res.headers, ["public"]);
 // `x-nifra-data` alone is not a variation the URL key misses: a navigation data request never reads
 // or writes the store, so every stored entry is the document.
@@ -394,7 +509,8 @@ const responseDeclaresVary = (res) => {
 /**
  * Whether `res` may be stored by a shared cache and served to anyone requesting `req`'s URL: a
  * full-document `GET` 200 `text/html` with no Set-Cookie, no `private`/`no-store`, no `Vary` beyond
- * the data header, and, for a request carrying a cookie or Authorization, an explicit `public`.
+ * the data header, and, for a request carrying a cookie or Authorization or accepted by an
+ * authentication stage, an explicit `public`.
  * The one rule both `withISR` and `@nifrajs/web/cdn` cache by.
  */
 export const isCacheablePage = (req, res) => {
@@ -471,7 +587,21 @@ function sanitizeCachedHeaders(headers) {
     }
     return out;
 }
-const isInvalidationResponse = (res) => res.status === 404 || res.status === 410 || (res.status >= 300 && res.status < 400);
+/**
+ * Whether a regeneration's answer withdraws the stored page: it is gone or moved, or, rendered for a
+ * request with no cookie or Authorization, refused (401, 403) or declared `private`/`no-store`. A
+ * signed-in visitor's own 403 or private copy says nothing about the shared page. A 5xx or 429 keeps
+ * serving the stale copy.
+ */
+const isInvalidationResponse = (req, res) => {
+    if (res.status === 404 || res.status === 410 || (res.status >= 300 && res.status < 400))
+        return true;
+    if (requestCarriesPrivateState(req))
+        return false;
+    return (res.status === 401 ||
+        res.status === 403 ||
+        (res.status >= 200 && res.status < 300 && cacheControlHas(res.headers, ["private", "no-store"])));
+};
 /**
  * Wrap a nifra app with **Incremental Static Regeneration**: a cacheable page is served from
  * {@link CacheStore} when fresh, served **stale while a fresh copy regenerates in the background**
@@ -486,8 +616,77 @@ const isInvalidationResponse = (res) => res.status === 404 || res.status === 410
 export function withISR(app, options) {
     const { store, now } = options;
     assertRevalidate(options.revalidate, "revalidate");
+    const storeTimeoutMs = options.storeTimeoutMs;
+    if (storeTimeoutMs !== undefined && !(Number.isFinite(storeTimeoutMs) && storeTimeoutMs > 0)) {
+        throw new RangeError("[nifra/web] ISR storeTimeoutMs must be a positive finite number");
+    }
+    const lastReport = new Map();
+    const reportStoreError = (op, key, error) => {
+        try {
+            if (options.onStoreError !== undefined) {
+                options.onStoreError(error, { op });
+                return;
+            }
+            const last = lastReport.get(op);
+            const at = now();
+            if (last !== undefined && at - last < STORE_REPORT_INTERVAL_MS)
+                return;
+            lastReport.set(op, at);
+            console.error(`[nifra/web] ISR store ${op} failed; serving without the cache (${storeErrorDetail(error, key)})`);
+        }
+        catch {
+            // A failing reporter must not turn a served page into an error.
+        }
+    };
+    // Runs one store call; a throw, a rejection or a timeout is reported and answered with STORE_FAILED.
+    const attempt = async (op, key, call) => {
+        let timer;
+        try {
+            const pending = call();
+            if (storeTimeoutMs === undefined)
+                return await pending;
+            const timeout = new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    const error = new Error(`ISR store ${op} exceeded storeTimeoutMs (${storeTimeoutMs} ms)`);
+                    error.name = "TimeoutError";
+                    reject(error);
+                }, storeTimeoutMs);
+            });
+            return await Promise.race([pending, timeout]);
+        }
+        catch (error) {
+            reportStoreError(op, key, error);
+            return STORE_FAILED;
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    };
+    // A store without purge order, or one whose fence failed, stores the render unfenced.
+    const fenceFor = async (key) => {
+        const { fence } = store;
+        if (fence === undefined)
+            return undefined;
+        const taken = await attempt("fence", key, async () => fence.call(store));
+        return taken === STORE_FAILED ? undefined : taken;
+    };
     const keyOf = options.key ?? requestKeyOf(urlKeyOf(options.query));
     const draftSecret = options.draftSecret;
+    const anonymousCookies = new Set(options.anonymousCookies ?? []);
+    // A request whose cookies are all anonymous is judged for storage as if it carried none.
+    const judged = (req) => {
+        if (anonymousCookies.size === 0 ||
+            req.headers.has("authorization") ||
+            isAuthenticatedRequest(req))
+            return req;
+        const cookie = req.headers.get("cookie");
+        if (cookie === null || !cookieNamesWithin(cookie, anonymousCookies))
+            return req;
+        const headers = new Headers(req.headers);
+        headers.delete("cookie");
+        return new Request(req.url, { method: req.method, headers });
+    };
     const regenerating = new Set();
     openCacheChannel(app);
     // An outer cache layer (`withCdn`) opens this wrapper's own channel: cached responses then carry how
@@ -531,10 +730,12 @@ export function withISR(app, options) {
         const safeSeconds = Number.isFinite(seconds) && seconds >= 0 ? seconds : options.revalidate;
         return safeSeconds * 1000;
     };
-    const render = async (req, platform, key) => {
+    const render = async (req, platform, key, remember, stored) => {
+        const fence = await fenceFor(key);
         const res = await app.fetch(req, platform);
-        if (!isCacheablePage(req, res)) {
-            rememberUncacheable(key, res);
+        if (!isCacheablePage(judged(req), res)) {
+            if (remember)
+                rememberUncacheable(key, res);
             return withoutCacheChannel(res);
         }
         uncacheable.delete(key);
@@ -547,14 +748,44 @@ export function withISR(app, options) {
             storedAt: now(),
             revalidate: ttlMs(res),
             ...(tags.length === 0 ? {} : { tags }),
+            fence,
         };
-        await store.set(key, entry);
-        const fresh = new Response(body, {
-            status: res.status,
+        // A failed write still answers with the page, and still hands it to concurrent misses: whether it
+        // may be shared was decided above, not by the store.
+        await attempt("set", key, () => store.set(key, entry));
+        stored?.(entry);
+        return fresh(entry);
+    };
+    const fresh = (entry) => {
+        const res = new Response(entry.body, {
+            status: entry.status,
             headers: { ...entry.headers, [ISR_STATUS_HEADER]: "miss" },
         });
-        advertise(fresh.headers, entry.revalidate, tags);
-        return fresh;
+        advertise(res.headers, entry.revalidate, entry.tags ?? []);
+        return res;
+    };
+    // Cold misses in flight per key. Concurrent misses wait for the first one's stored entry instead
+    // of each rendering the page; a render that is not stored (private, failed) sends each waiter to
+    // render for itself, so a waiter never receives a page that was not safe to share.
+    const coldRenders = new Map();
+    const renderCold = async (req, platform, key) => {
+        const pending = coldRenders.get(key);
+        if (pending !== undefined) {
+            const entry = await pending;
+            return entry === undefined ? render(req, platform, key, true) : fresh(entry);
+        }
+        const shared = Promise.withResolvers();
+        coldRenders.set(key, shared.promise);
+        let entry;
+        try {
+            return await render(req, platform, key, true, (stored) => {
+                entry = stored;
+            });
+        }
+        finally {
+            coldRenders.delete(key);
+            shared.resolve(entry);
+        }
     };
     // Background regeneration (single-flight per key) - a failed regen keeps the stale entry; the next
     // stale hit retries. Never throws (it runs detached / under waitUntil).
@@ -563,23 +794,27 @@ export function withISR(app, options) {
             return;
         regenerating.add(key);
         try {
+            const fence = await fenceFor(key);
             const res = await app.fetch(req, platform);
-            if (isCacheablePage(req, res)) {
+            if (isCacheablePage(judged(req), res)) {
                 const tags = tagsOf(res);
-                await store.set(key, {
+                const entry = {
                     body: await res.text(),
                     status: res.status,
                     headers: headersOf(res),
                     storedAt: now(),
                     revalidate: ttlMs(res),
                     ...(tags.length === 0 ? {} : { tags }),
-                });
+                    fence,
+                };
+                await attempt("set", key, () => store.set(key, entry));
             }
-            else if (isInvalidationResponse(res)) {
-                // A successful deletion or redirect is authoritative. Keeping the old entry would make a
-                // withdrawn page stay publicly visible forever because every stale request would retry the same
-                // non-cacheable response while continuing to serve the old body.
-                await store.delete(key);
+            else if (isInvalidationResponse(judged(req), res)) {
+                // A withdrawal is authoritative. Keeping the old entry would make a withdrawn page stay
+                // publicly visible forever, because every stale request would retry the same non-cacheable
+                // response while continuing to serve the old body.
+                await res.body?.cancel();
+                await attempt("delete", key, () => store.delete(key));
             }
             else {
                 await res.body?.cancel();
@@ -596,7 +831,14 @@ export function withISR(app, options) {
         // A data-mode soft-nav GET bypasses the cache entirely: entries are full HTML documents keyed
         // by URL, and serving one to a loader-data fetch would hand the client HTML where it expects
         // the loader payload. (The write path already refuses to cache data-mode responses.)
-        const key = req.method === "GET" && req.headers.get("x-nifra-data") === null ? keyOf(req) : null;
+        const privateRoute = Reflect.get(app, Symbol.for("nifra.web.private-route"));
+        const ownsPrivate = typeof privateRoute === "function" && privateRoute(req) === true;
+        const key = req.method === "GET" &&
+            req.headers.get("x-nifra-data") === null &&
+            !req.headers.has("x-nifra-component") &&
+            !ownsPrivate
+            ? keyOf(req)
+            : null;
         if (key === null)
             return withoutCacheChannel(await app.fetch(req, platform));
         // Draft/preview: an editor (valid signed cookie) always renders fresh and is never cached, so
@@ -604,13 +846,17 @@ export function withISR(app, options) {
         if (draftSecret !== undefined && (await isDraftEnabled(req, draftSecret))) {
             return withoutCacheChannel(await app.fetch(req, platform));
         }
+        // A cookie or Authorization request may be personalized: under the default key it never reads
+        // the store, and its private render never marks the URL uncacheable for everyone else.
+        const personal = options.key === undefined && requestCarriesPrivateState(judged(req));
         const until = uncacheable.get(key);
         if (until !== undefined) {
             if (now() < until)
-                return render(req, platform, key);
+                return render(req, platform, key, !personal);
             uncacheable.delete(key);
         }
-        const hit = await store.get(key);
+        const read = personal ? undefined : await attempt("get", key, () => store.get(key));
+        const hit = read === STORE_FAILED ? undefined : read;
         if (hit !== undefined) {
             if (now() - hit.storedAt < hit.revalidate)
                 return served(hit, "hit");
@@ -622,7 +868,7 @@ export function withISR(app, options) {
                 void task.catch(() => { });
             return served(hit, "stale");
         }
-        return render(req, platform, key);
+        return personal ? render(req, platform, key, false) : renderCold(req, platform, key);
     };
     Object.defineProperty(handler, CACHE_CHANNEL, {
         value: () => {
@@ -723,6 +969,17 @@ export function revalidateEndpoint(options) {
         if (tags.length > 0 && invalidateTag === undefined) {
             return jsonError(501, "tag_invalidation_not_supported");
         }
+        if (tags.length > 0 && options.dataCaches !== undefined) {
+            try {
+                for (const cache of options.dataCaches) {
+                    for (const candidate of tags)
+                        await cache.invalidateTag(candidate);
+                }
+            }
+            catch {
+                return Response.json({ ok: false, error: "data_cache_invalidation_failed" }, { status: 500 });
+            }
+        }
         for (const key of keys)
             await options.store.delete(key);
         for (const candidate of tags)