@nifrajs/web 5.5.0 → 5.6.0

package/dist/internal/hole-runtime.js

@@ -0,0 +1,211 @@
+import { onPageRelease, PAGE_HIDE_EVENT, PAGE_SHOW_EVENT } from "./page-events.js";
+/** The error slot a failed, timed-out or refused hole shows. Constant: no thrown message reaches it. */
+export const HOLE_ERROR_HTML = '<p data-nifra-hole-error="">This section is unavailable.</p>';
+const ERROR_FRAME = { v: 1, error: true, html: HOLE_ERROR_HTML };
+/** The runtime the shell's inline script defines, when this document has one. */
+const pprRuntime = () => {
+    const runtime = Reflect.get(globalThis, "__nifraPpr");
+    return typeof runtime === "function" &&
+        "get" in runtime &&
+        "subscribe" in runtime &&
+        "put" in runtime
+        ? // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the shell's constant inline runtime defines exactly this shape.
+            runtime
+        : undefined;
+};
+let components;
+/** What `holeComponents` registers; `undefined` forgets it. */
+export function setHoleComponents(next) {
+    components = next;
+}
+const isRecord = (value) => typeof value === "object" && value !== null;
+/** A fill the server deferred: the NDJSON stream settles its promise. */
+const settledFill = (fill) => isRecord(fill) && fill.__nifra_deferred === true && fill.promise instanceof Promise
+    ? fill.promise
+    : Promise.resolve(fill);
+/**
+ * What a host renders with: a blocking render's settled fill puts the server's HTML in it, which a
+ * crawler reads with no script; any other state leaves it empty. A host reads it once, so no later
+ * render changes what the runtime put there.
+ */
+export const initialHtml = (fill) => isRecord(fill) && fill.__nifra_deferred !== true && typeof fill.html === "string" ? fill.html : "";
+/** The record of the server component a fill shows, its HTML put back, not yet checked. */
+const recordOf = (fill) => isRecord(fill.component) && typeof fill.html === "string"
+    ? { ...fill.component, html: fill.html }
+    : undefined;
+/** The error slot, built without HTML parsing, for a document with no runtime to put it. */
+const errorSlot = (host) => {
+    const slot = host.ownerDocument.createElement("p");
+    slot.setAttribute("data-nifra-hole-error", "");
+    slot.textContent = "This section is unavailable.";
+    host.replaceChildren(slot);
+    host.setAttribute("data-nifra-hole-error", "");
+};
+/**
+ * The islands of the server component in `host`: hydrated over the server's HTML, or with `fresh`,
+ * put into the host from the record. `failed` runs when they cannot mount, as when the record fails
+ * the protocol check.
+ */
+function componentRoot(host, unchecked, fresh, failed) {
+    const registered = components;
+    let current = true;
+    const valid = () => current;
+    const mounted = (async () => {
+        if (registered === undefined) {
+            throw new Error("[nifra/web] ppr: a hole shows a server component, but no holeComponents client");
+        }
+        const { client } = registered;
+        const record = registered.record(unchecked);
+        const mount = fresh ? client.create : client.hydrate;
+        if (mount === undefined)
+            throw new Error("[nifra/web] ppr: the component client cannot create");
+        const prepared = await client.prepare(record, valid, host, { records: [record] });
+        if (!current)
+            return undefined;
+        const root = await mount.call(client, host, record, prepared, valid);
+        if (!current) {
+            await root.dispose();
+            return undefined;
+        }
+        host.setAttribute("aria-busy", "false");
+        return root;
+    })().catch((error) => {
+        if (current) {
+            console.error("[nifra/web] ppr: a server component hole's islands did not mount", error);
+            failed();
+        }
+        return undefined;
+    });
+    return {
+        update: () => false,
+        dispose() {
+            current = false;
+            return mounted.then((root) => root?.dispose());
+        },
+    };
+}
+/**
+ * Drive the host of hole `name`. `hydrate` makes an interactive hole's root over the server HTML in
+ * `host`; a hole without one only ever shows server HTML, or a server component's.
+ */
+export function holeHost(name, host, hydrate) {
+    const runtime = pprRuntime();
+    let root;
+    let disposed = false;
+    let latest = 0;
+    // The kept page hiding the host, and what disposes the host if that page is dropped.
+    let hiddenBy;
+    let release;
+    const put = (frame) => {
+        if (runtime !== undefined)
+            runtime.put(name, frame, host);
+        else
+            errorSlot(host);
+        host.setAttribute("aria-busy", "false");
+    };
+    const showError = () => {
+        root = undefined;
+        put(ERROR_FRAME);
+    };
+    const start = (fill) => {
+        if (disposed || root !== undefined || fill.error)
+            return;
+        const record = recordOf({ component: fill.component, html: fill.html });
+        if (record !== undefined)
+            root = componentRoot(host, record, false, showError);
+        else if (hydrate !== undefined)
+            root = hydrate(host, fill.props);
+    };
+    const now = runtime?.get(name);
+    const unsubscribe = now === undefined && (hydrate !== undefined || components !== undefined)
+        ? runtime?.subscribe(name, start)
+        : undefined;
+    if (now !== undefined)
+        start(now);
+    // A `keepAlive` page hidden behind another has been left: the document's holes stop filling and
+    // the ones still loading are cancelled, and a refill already on its way is dropped. The page's
+    // reload when it is shown again refills the host.
+    const hidden = (event) => {
+        if (!(event.target instanceof Element) || !event.target.contains(host))
+            return;
+        hiddenBy = event.target;
+        latest++;
+        runtime?.leave?.();
+        root?.hide?.(true);
+    };
+    const shown = (event) => {
+        if (event.target !== hiddenBy)
+            return;
+        hiddenBy = undefined;
+        root?.hide?.(false);
+    };
+    host.ownerDocument.addEventListener(PAGE_HIDE_EVENT, hidden);
+    host.ownerDocument.addEventListener(PAGE_SHOW_EVENT, shown);
+    const apply = (frame, mine, inPlace) => {
+        if (!isRecord(frame))
+            return;
+        const failed = frame.error === true;
+        const record = failed ? undefined : recordOf(frame);
+        if (!failed && record === undefined && root?.update(frame.props) === true) {
+            host.setAttribute("aria-busy", "false");
+            return;
+        }
+        // An error shows the error slot, never content the action that reloaded it may have changed.
+        const gone = root?.dispose(false);
+        root = undefined;
+        const fill = () => {
+            if (disposed || mine !== latest)
+                return;
+            host.removeAttribute("data-nifra-hole-error");
+            if (record !== undefined) {
+                host.setAttribute("data-nifra-filled", "");
+                root = componentRoot(host, record, !inPlace, showError);
+                return;
+            }
+            put(frame);
+            if (!failed && hydrate !== undefined)
+                root = hydrate(host, frame.props);
+        };
+        if (gone instanceof Promise)
+            gone.then(fill, fill);
+        else
+            fill();
+    };
+    const dispose = () => {
+        disposed = true;
+        release?.();
+        release = undefined;
+        host.ownerDocument.removeEventListener(PAGE_HIDE_EVENT, hidden);
+        host.ownerDocument.removeEventListener(PAGE_SHOW_EVENT, shown);
+        unsubscribe?.();
+        Promise.resolve(root?.dispose(true)).catch(() => { });
+        root = undefined;
+    };
+    return {
+        refill(fill) {
+            // A blocking render's settled fill is the server HTML the host already shows.
+            const inPlace = latest === 0 && root === undefined && initialHtml(fill) !== "";
+            const mine = ++latest;
+            host.setAttribute("aria-busy", "true");
+            settledFill(fill).then((frame) => {
+                if (!disposed && mine === latest)
+                    apply(frame, mine, inPlace);
+            }, () => {
+                if (!disposed && mine === latest)
+                    apply(ERROR_FRAME, mine, false);
+            });
+        },
+        dispose,
+        park() {
+            if (disposed || hiddenBy === undefined)
+                return false;
+            release ??= onPageRelease(hiddenBy, dispose);
+            return true;
+        },
+        unpark() {
+            release?.();
+            release = undefined;
+        },
+    };
+}
+//# sourceMappingURL=hole-runtime.js.map

package/dist/internal/hole-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hole-runtime.js","sourceRoot":"","sources":["../../src/internal/hole-runtime.ts"],"names":[],"mappings":"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"}

package/dist/internal/identity-epoch.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The server half of the identity epoch: a response that signs a visitor in or out also rotates the
+ * readable epoch cookie, so every tab drops the pages it kept alive for the previous visitor.
+ *
+ * A header-only hook reads each response's `Set-Cookie`: when an identity cookie's value differs from
+ * the request's, or the cookie is deleted, the response also sets a fresh epoch with the same lifetime,
+ * so the epoch expires with an idle session. A rolling session re-sending the same value with a new
+ * lifetime re-sends the epoch it holds with that lifetime, so the two keep expiring together.
+ */
+import { type CookieOptions } from "@nifrajs/core/server";
+/** `createWebApp`'s `keepAlive` option: which cookies say who is signed in. */
+export interface KeepAliveServerOptions {
+    /**
+     * Cookies whose change means a different visitor, on top of the session cookies of
+     * `@nifrajs/auth`, Better Auth and Auth.js under their default names. Name a custom session cookie
+     * here, or kept pages survive a sign-in or sign-out through it.
+     */
+    readonly identityCookies?: readonly string[];
+    /** `HttpOnly` cookies that say nothing about who is signed in; development stops asking about them. */
+    readonly ignoreCookies?: readonly string[];
+}
+/** The request and response a header hook sees. */
+interface HeaderView {
+    get(name: string): string | null;
+    append(name: string, value: string): void;
+}
+interface RequestView {
+    readonly url: string;
+    header(name: string): string | null | undefined;
+}
+/**
+ * The response hook `createWebApp` installs for an app with a `keepAlive` route. With `development`,
+ * it also says once per cookie when an `HttpOnly` cookie it does not know changes.
+ */
+export declare function identityEpochHook(options: KeepAliveServerOptions, development: boolean): (headers: HeaderView, request: RequestView) => void;
+/** The response-cookie surface {@link rotateIdentityEpoch} needs: nifra's handler context. */
+export interface IdentityEpochContext {
+    readonly request: Request;
+    readonly set: {
+        cookie(name: string, value: string, options?: CookieOptions): void;
+    };
+}
+/**
+ * Rotate the identity epoch from a flow that changes who is signed in without changing a cookie
+ * `createWebApp` watches - say, a session kept server-side under a cookie whose value stays the
+ * same. Every tab then drops the pages it kept alive for the previous visitor.
+ */
+export declare function rotateIdentityEpoch(c: IdentityEpochContext): void;
+export {};
+//# sourceMappingURL=identity-epoch.d.ts.map

package/dist/internal/identity-epoch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-epoch.d.ts","sourceRoot":"","sources":["../../src/internal/identity-epoch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,KAAK,aAAa,EAAgB,MAAM,sBAAsB,CAAA;AAGvE,+EAA+E;AAC/E,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5C,uGAAuG;IACvG,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3C;AAED,mDAAmD;AACnD,UAAU,UAAU;IAClB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IAChC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1C;AACD,UAAU,WAAW;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAChD;AA8GD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,sBAAsB,EAC/B,WAAW,EAAE,OAAO,GACnB,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,KAAK,IAAI,CA4DrD;AAED,8FAA8F;AAC9F,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,GAAG,EAAE;QAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI,CAAA;KAAE,CAAA;CACrF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAYjE"}

package/dist/internal/identity-epoch.js

@@ -0,0 +1,179 @@
+/**
+ * The server half of the identity epoch: a response that signs a visitor in or out also rotates the
+ * readable epoch cookie, so every tab drops the pages it kept alive for the previous visitor.
+ *
+ * A header-only hook reads each response's `Set-Cookie`: when an identity cookie's value differs from
+ * the request's, or the cookie is deleted, the response also sets a fresh epoch with the same lifetime,
+ * so the epoch expires with an idle session. A rolling session re-sending the same value with a new
+ * lifetime re-sends the epoch it holds with that lifetime, so the two keep expiring together.
+ */
+import { parseCookies } from "@nifrajs/core/server";
+import { EPOCH_COOKIE, LOCAL_EPOCH_COOKIE } from "../identity.js";
+// Session cookies by their default names, without a `__Secure-` / `__Host-` prefix.
+const IDENTITY_DEFAULTS = [
+    "nifra_session",
+    "better-auth.session_token",
+    "authjs.session-token",
+    "next-auth.session-token",
+];
+// `HttpOnly` cookies the same integrations write that carry no identity of their own.
+const IGNORE_DEFAULTS = [
+    "better-auth.session_data",
+    "better-auth.dont_remember",
+    "authjs.csrf-token",
+    "authjs.callback-url",
+    "authjs.pkce.code_verifier",
+    "authjs.state",
+    "authjs.nonce",
+    "next-auth.csrf-token",
+    "next-auth.callback-url",
+    "next-auth.pkce.code_verifier",
+    "next-auth.state",
+    "next-auth.nonce",
+    "__nifra_draft",
+];
+// `__Secure-a.0` and `__Host-a` are the cookie `a`: a prefix, then Auth.js's chunk index.
+const baseName = (name) => name.replace(/^__(?:secure|host)-/i, "").replace(/\.\d+$/, "");
+// Splits a `Set-Cookie` list joined with ", ": only a comma followed by `name=` starts a cookie, so
+// the comma inside an `Expires` date stays where it is.
+const SPLIT = /,\s*(?=[!#$%&'*+\-.^_`|~0-9A-Za-z]+=)/;
+const parseSetCookies = (joined, now) => {
+    const cookies = [];
+    for (const line of joined.split(SPLIT)) {
+        const [pair = "", ...attributes] = line.split(";");
+        const at = pair.indexOf("=");
+        if (at <= 0)
+            continue;
+        let maxAge;
+        let expires;
+        let httpOnly = false;
+        let secure = false;
+        for (const attribute of attributes) {
+            const eq = attribute.indexOf("=");
+            const key = (eq === -1 ? attribute : attribute.slice(0, eq)).trim().toLowerCase();
+            const value = eq === -1 ? "" : attribute.slice(eq + 1).trim();
+            if (key === "max-age")
+                maxAge = value;
+            else if (key === "expires")
+                expires = value;
+            else if (key === "httponly")
+                httpOnly = true;
+            else if (key === "secure")
+                secure = true;
+        }
+        const name = pair.slice(0, at).trim();
+        const age = maxAge === undefined ? Number.NaN : Number(maxAge);
+        const until = expires === undefined ? Number.NaN : Date.parse(expires);
+        cookies.push({
+            name,
+            // Decoded as core decodes the request's cookies, so an encoded value compares equal to itself.
+            value: parseCookies(pair.trim())[name] ?? "",
+            deleted: age <= 0 || until <= now,
+            httpOnly,
+            secure: secure || /^__(?:secure|host)-/i.test(name),
+            maxAge,
+            expires,
+        });
+    }
+    return cookies;
+};
+const randomEpoch = () => {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    let hex = "";
+    for (const byte of bytes)
+        hex += byte.toString(16).padStart(2, "0");
+    return hex;
+};
+const EPOCH_VALUE = /^[0-9a-f]{32}$/;
+// A forwarded protocol only picks the cookie's name: a client that lies about it loses its own epoch.
+// A browser sends a `__Host-` cookie only over https, so carrying one says so behind a TLS proxy that
+// forwards nothing, and the client, which reads that one first, must see the new value there.
+const servedOverHttps = (request, sent) => {
+    if (request.url.startsWith("https:") || sent[EPOCH_COOKIE] !== undefined)
+        return true;
+    const forwarded = request.header("x-forwarded-proto");
+    return forwarded?.split(",")[0]?.trim().toLowerCase() === "https";
+};
+const epochCookie = (secure, value, lifetime) => {
+    let cookie = `${secure ? EPOCH_COOKIE : LOCAL_EPOCH_COOKIE}=${value}; Path=/; SameSite=Lax`;
+    if (secure)
+        cookie += "; Secure";
+    if (lifetime.maxAge !== undefined)
+        cookie += `; Max-Age=${lifetime.maxAge}`;
+    if (lifetime.expires !== undefined)
+        cookie += `; Expires=${lifetime.expires}`;
+    return cookie;
+};
+/**
+ * The response hook `createWebApp` installs for an app with a `keepAlive` route. With `development`,
+ * it also says once per cookie when an `HttpOnly` cookie it does not know changes.
+ */
+export function identityEpochHook(options, development) {
+    const identity = new Set([...IDENTITY_DEFAULTS, ...(options.identityCookies ?? []).map(baseName)]);
+    const ignored = new Set([...IGNORE_DEFAULTS, ...(options.ignoreCookies ?? []).map(baseName)]);
+    const reported = new Set();
+    return (headers, request) => {
+        const joined = headers.get("set-cookie");
+        if (joined === null || joined === "")
+            return;
+        const sent = parseCookies(request.header("cookie") ?? null);
+        let changed;
+        let renewed;
+        for (const cookie of parseSetCookies(joined, Date.now())) {
+            if (cookie.name === EPOCH_COOKIE || cookie.name === LOCAL_EPOCH_COOKIE)
+                return;
+            const now = cookie.deleted ? "" : cookie.value;
+            const base = baseName(cookie.name);
+            if (now === (sent[cookie.name] ?? "")) {
+                if (renewed === undefined &&
+                    !cookie.deleted &&
+                    (cookie.maxAge !== undefined || cookie.expires !== undefined) &&
+                    identity.has(base))
+                    renewed = cookie;
+                continue;
+            }
+            if (identity.has(base)) {
+                // The first identity cookie still set gives the lifetime; a sign-out deletes them all.
+                if (changed === undefined || (changed.deleted && !cookie.deleted))
+                    changed = cookie;
+                continue;
+            }
+            if (!development || !cookie.httpOnly || ignored.has(base) || reported.has(base))
+                continue;
+            reported.add(base);
+            console.warn(`[nifra/web] NIFRA_KEEPALIVE_IDENTITY_COOKIE: this app keeps pages alive, and a response changed the HttpOnly cookie "${cookie.name}", which nifra does not know as a sign-in cookie. If it says who is signed in, add it to createWebApp({ keepAlive: { identityCookies: ["${base}"] } }) so a sign-in or sign-out drops the pages kept for the previous visitor; if it does not, add it to keepAlive.ignoreCookies.`);
+        }
+        if (changed !== undefined) {
+            headers.append("set-cookie", epochCookie(changed.secure || servedOverHttps(request, sent), randomEpoch(), changed.deleted ? {} : { maxAge: changed.maxAge, expires: changed.expires }));
+            return;
+        }
+        if (renewed === undefined)
+            return;
+        const lifetime = { maxAge: renewed.maxAge, expires: renewed.expires };
+        for (const secure of [true, false]) {
+            const held = sent[secure ? EPOCH_COOKIE : LOCAL_EPOCH_COOKIE];
+            if (held === undefined || !EPOCH_VALUE.test(held))
+                continue;
+            headers.append("set-cookie", epochCookie(secure, held, lifetime));
+            return;
+        }
+        // An epoch that already expired, or was never set: a fresh one, so pages kept without one drop.
+        headers.append("set-cookie", epochCookie(renewed.secure || servedOverHttps(request, sent), randomEpoch(), lifetime));
+    };
+}
+/**
+ * Rotate the identity epoch from a flow that changes who is signed in without changing a cookie
+ * `createWebApp` watches - say, a session kept server-side under a cookie whose value stays the
+ * same. Every tab then drops the pages it kept alive for the previous visitor.
+ */
+export function rotateIdentityEpoch(c) {
+    const request = c.request;
+    const secure = servedOverHttps({ url: request.url, header: (name) => request.headers.get(name) }, parseCookies(request.headers.get("cookie")));
+    c.set.cookie(secure ? EPOCH_COOKIE : LOCAL_EPOCH_COOKIE, randomEpoch(), {
+        path: "/",
+        sameSite: "lax",
+        secure,
+        httpOnly: false,
+    });
+}
+//# sourceMappingURL=identity-epoch.js.map

package/dist/internal/identity-epoch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-epoch.js","sourceRoot":"","sources":["../../src/internal/identity-epoch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAsB,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACvE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAwBjE,oFAAoF;AACpF,MAAM,iBAAiB,GAAG;IACxB,eAAe;IACf,2BAA2B;IAC3B,sBAAsB;IACtB,yBAAyB;CAC1B,CAAA;AACD,sFAAsF;AACtF,MAAM,eAAe,GAAG;IACtB,0BAA0B;IAC1B,2BAA2B;IAC3B,mBAAmB;IACnB,qBAAqB;IACrB,2BAA2B;IAC3B,cAAc;IACd,cAAc;IACd,sBAAsB;IACtB,wBAAwB;IACxB,8BAA8B;IAC9B,iBAAiB;IACjB,iBAAiB;IACjB,eAAe;CAChB,CAAA;AAED,0FAA0F;AAC1F,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAU,EAAE,CACxC,IAAI,CAAC,OAAO,CAAC,sBAAsB,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAA;AAYhE,oGAAoG;AACpG,wDAAwD;AACxD,MAAM,KAAK,GAAG,uCAAuC,CAAA;AAErD,MAAM,eAAe,GAAG,CAAC,MAAc,EAAE,GAAW,EAAe,EAAE;IACnE,MAAM,OAAO,GAAgB,EAAE,CAAA;IAC/B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QACvC,MAAM,CAAC,IAAI,GAAG,EAAE,EAAE,GAAG,UAAU,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QAClD,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QAC5B,IAAI,EAAE,IAAI,CAAC;YAAE,SAAQ;QACrB,IAAI,MAA0B,CAAA;QAC9B,IAAI,OAA2B,CAAA;QAC/B,IAAI,QAAQ,GAAG,KAAK,CAAA;QACpB,IAAI,MAAM,GAAG,KAAK,CAAA;QAClB,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,MAAM,EAAE,GAAG,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;YACjC,MAAM,GAAG,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;YACjF,MAAM,KAAK,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;YAC7D,IAAI,GAAG,KAAK,SAAS;gBAAE,MAAM,GAAG,KAAK,CAAA;iBAChC,IAAI,GAAG,KAAK,SAAS;gBAAE,OAAO,GAAG,KAAK,CAAA;iBACtC,IAAI,GAAG,KAAK,UAAU;gBAAE,QAAQ,GAAG,IAAI,CAAA;iBACvC,IAAI,GAAG,KAAK,QAAQ;gBAAE,MAAM,GAAG,IAAI,CAAA;QAC1C,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;QACrC,MAAM,GAAG,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAC9D,MAAM,KAAK,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QACtE,OAAO,CAAC,IAAI,CAAC;YACX,IAAI;YACJ,+FAA+F;YAC/F,KAAK,EAAE,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE;YAC5C,OAAO,EAAE,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,GAAG;YACjC,QAAQ;YACR,MAAM,EAAE,MAAM,IAAI,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC;YACnD,MAAM;YACN,OAAO;SACR,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA;AAED,MAAM,WAAW,GAAG,GAAW,EAAE;IAC/B,MAAM,KAAK,GAAG,MAAM,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,CAAA;IACxD,IAAI,GAAG,GAAG,EAAE,CAAA;IACZ,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IACnE,OAAO,GAAG,CAAA;AACZ,CAAC,CAAA;AAED,MAAM,WAAW,GAAG,gBAAgB,CAAA;AAEpC,sGAAsG;AACtG,sGAAsG;AACtG,8FAA8F;AAC9F,MAAM,eAAe,GAAG,CAAC,OAAoB,EAAE,IAAsC,EAAW,EAAE;IAChG,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,YAAY,CAAC,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IACrF,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAA;IACrD,OAAO,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,OAAO,CAAA;AACnE,CAAC,CAAA;AAED,MAAM,WAAW,GAAG,CAClB,MAAe,EACf,KAAa,EACb,QAAyF,EACjF,EAAE;IACV,IAAI,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,kBAAkB,IAAI,KAAK,wBAAwB,CAAA;IAC3F,IAAI,MAAM;QAAE,MAAM,IAAI,UAAU,CAAA;IAChC,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS;QAAE,MAAM,IAAI,aAAa,QAAQ,CAAC,MAAM,EAAE,CAAA;IAC3E,IAAI,QAAQ,CAAC,OAAO,KAAK,SAAS;QAAE,MAAM,IAAI,aAAa,QAAQ,CAAC,OAAO,EAAE,CAAA;IAC7E,OAAO,MAAM,CAAA;AACf,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAA+B,EAC/B,WAAoB;IAEpB,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,iBAAiB,EAAE,GAAG,CAAC,OAAO,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;IAClG,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,eAAe,EAAE,GAAG,CAAC,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;IAC7F,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAA;IAClC,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE;QAC1B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;QACxC,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,EAAE;YAAE,OAAM;QAC5C,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAA;QAC3D,IAAI,OAA8B,CAAA;QAClC,IAAI,OAA8B,CAAA;QAClC,KAAK,MAAM,MAAM,IAAI,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;YACzD,IAAI,MAAM,CAAC,IAAI,KAAK,YAAY,IAAI,MAAM,CAAC,IAAI,KAAK,kBAAkB;gBAAE,OAAM;YAC9E,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAA;YAC9C,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;YAClC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;gBACtC,IACE,OAAO,KAAK,SAAS;oBACrB,CAAC,MAAM,CAAC,OAAO;oBACf,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC;oBAC7D,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;oBAElB,OAAO,GAAG,MAAM,CAAA;gBAClB,SAAQ;YACV,CAAC;YACD,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACvB,uFAAuF;gBACvF,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;oBAAE,OAAO,GAAG,MAAM,CAAA;gBACnF,SAAQ;YACV,CAAC;YACD,IAAI,CAAC,WAAW,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,SAAQ;YACzF,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;YAClB,OAAO,CAAC,IAAI,CACV,wHAAwH,MAAM,CAAC,IAAI,2IAA2I,IAAI,oIAAoI,CACvZ,CAAA;QACH,CAAC;QACD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,CAAC,MAAM,CACZ,YAAY,EACZ,WAAW,CACT,OAAO,CAAC,MAAM,IAAI,eAAe,CAAC,OAAO,EAAE,IAAI,CAAC,EAChD,WAAW,EAAE,EACb,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAC5E,CACF,CAAA;YACD,OAAM;QACR,CAAC;QACD,IAAI,OAAO,KAAK,SAAS;YAAE,OAAM;QACjC,MAAM,QAAQ,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAA;QACrE,KAAK,MAAM,MAAM,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAA;YAC7D,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,SAAQ;YAC3D,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAA;YACjE,OAAM;QACR,CAAC;QACD,gGAAgG;QAChG,OAAO,CAAC,MAAM,CACZ,YAAY,EACZ,WAAW,CAAC,OAAO,CAAC,MAAM,IAAI,eAAe,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,EAAE,EAAE,QAAQ,CAAC,CACvF,CAAA;IACH,CAAC,CAAA;AACH,CAAC;AAQD;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAuB;IACzD,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,CAAA;IACzB,MAAM,MAAM,GAAG,eAAe,CAC5B,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EACjE,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAC5C,CAAA;IACD,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,kBAAkB,EAAE,WAAW,EAAE,EAAE;QACtE,IAAI,EAAE,GAAG;QACT,QAAQ,EAAE,KAAK;QACf,MAAM;QACN,QAAQ,EAAE,KAAK;KAChB,CAAC,CAAA;AACJ,CAAC"}

package/dist/internal/invalidation-contract.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The seam between `createWebApp` and a cache wrapper for an action's invalidation: types and one
+ * symbol, so an app pays for the pipeline only once something runs it.
+ */
+import type { RevalidateResult } from "./render-document.js";
+export interface InvalidationOp {
+    /** Names the operation in logs; never key text. */
+    readonly id: string;
+    readonly paths: readonly string[];
+    readonly tags: readonly string[];
+    readonly keys: readonly string[];
+}
+/** What a `createWebApp` app hands a cache wrapper that owns its invalidation. */
+export interface InvalidationHandoff {
+    /** The operation the action behind `request` recorded, once. */
+    take(request: Request): InvalidationOp | undefined;
+    /** The app's live publish, when it configures `live`. */
+    readonly publish: ((keys: readonly string[]) => Promise<void>) | undefined;
+}
+export declare const INVALIDATION: unique symbol;
+/** The operation an action's `revalidate()` names: its paths, cache tags and live keys. */
+export declare function invalidationOf(revalidation: RevalidateResult<unknown>): InvalidationOp;
+//# sourceMappingURL=invalidation-contract.d.ts.map

package/dist/internal/invalidation-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalidation-contract.d.ts","sourceRoot":"","sources":["../../src/internal/invalidation-contract.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAE5D,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CACjC;AAED,kFAAkF;AAClF,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAAA;IAClD,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAAA;CAC3E;AAED,eAAO,MAAM,YAAY,EAAE,OAAO,MAA6C,CAAA;AAE/E,2FAA2F;AAC3F,wBAAgB,cAAc,CAAC,YAAY,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAAG,cAAc,CAStF"}

package/dist/internal/invalidation-contract.js

@@ -0,0 +1,11 @@
+export const INVALIDATION = Symbol.for("nifra.web.invalidation");
+/** The operation an action's `revalidate()` names: its paths, cache tags and live keys. */
+export function invalidationOf(revalidation) {
+    return {
+        id: crypto.randomUUID(),
+        paths: revalidation.__nifraRevalidate.filter((path) => typeof path === "string" && path.startsWith("/")),
+        tags: revalidation.__nifraInvalidate?.tags ?? [],
+        keys: revalidation.__nifraInvalidate?.keys ?? [],
+    };
+}
+//# sourceMappingURL=invalidation-contract.js.map

package/dist/internal/invalidation-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalidation-contract.js","sourceRoot":"","sources":["../../src/internal/invalidation-contract.ts"],"names":[],"mappings":"AAsBA,MAAM,CAAC,MAAM,YAAY,GAAkB,MAAM,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAA;AAE/E,2FAA2F;AAC3F,MAAM,UAAU,cAAc,CAAC,YAAuC;IACpE,OAAO;QACL,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE;QACvB,KAAK,EAAE,YAAY,CAAC,iBAAiB,CAAC,MAAM,CAC1C,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAC3D;QACD,IAAI,EAAE,YAAY,CAAC,iBAAiB,EAAE,IAAI,IAAI,EAAE;QAChD,IAAI,EAAE,YAAY,CAAC,iBAAiB,EAAE,IAAI,IAAI,EAAE;KACjD,CAAA;AACH,CAAC"}

package/dist/internal/invalidation.d.ts

@@ -0,0 +1,62 @@
+/**
+ * One invalidation pipeline for everything a write makes stale, in a fixed order: data caches (tags),
+ * then the page store (paths and tags), then the live publish (keys and tags), then the CDN. A failure
+ * in either cache stage stops before the publish: clients told to reload would read the stale data and
+ * move their watermarks past the change. Every stage is idempotent, so a retry repeats from the stage
+ * that failed.
+ *
+ * `withISR` owns the pipeline when it wraps the app; without it, `createWebApp` runs the publish
+ * stage alone. Never both.
+ */
+import type { CdnPurgeTarget, ISRPlatform } from "../isr.js";
+import type { InvalidationOp } from "./invalidation-contract.js";
+export type { InvalidationOp } from "./invalidation-contract.js";
+export type InvalidationStage = "data" | "pages" | "publish" | "cdn";
+export interface StageReport {
+    readonly stage: InvalidationStage;
+    readonly ok: boolean;
+    readonly retryable: boolean;
+    readonly error?: string;
+    /** The CDN took the purge but has not applied it yet (rate limit or retry). */
+    readonly queued?: true;
+}
+export interface InvalidationReport {
+    readonly id: string;
+    readonly ok: boolean;
+    readonly stages: readonly StageReport[];
+}
+/** What the pipeline calls on a page store: any {@link CacheStore} fits. */
+export interface PagePurge {
+    delete(key: string): Promise<void>;
+    readonly invalidateTag?: ((tag: string) => Promise<void>) | undefined;
+}
+export interface InvalidationTargets {
+    readonly dataCaches?: readonly {
+        invalidateTag(tag: string): unknown;
+    }[] | undefined;
+    readonly store?: PagePurge | undefined;
+    /** The page store key of a path, as the cache wrapper computes it; `null` when never stored. */
+    readonly keyOf?: ((path: string, req: Request) => string | null) | undefined;
+    readonly publish?: ((keys: readonly string[]) => Promise<void>) | undefined;
+    readonly cdn?: CdnPurgeTarget | undefined;
+}
+export declare const INLINE_DEADLINE_MS = 2000;
+/** Run the stages from `from` once. */
+export declare function runInvalidation(op: InvalidationOp, targets: InvalidationTargets, req: Request, platform: ISRPlatform | undefined, from?: InvalidationStage): Promise<InvalidationReport>;
+export interface SettleOptions {
+    readonly onError?: ((report: InvalidationReport) => void) | undefined;
+    /** Tests drive time; production waits on timers. */
+    readonly clock?: {
+        now(): number;
+        sleep(ms: number): Promise<void>;
+    };
+}
+/**
+ * Run the pipeline for a write; never throws and never changes the response. A retryable failure
+ * retries from the failed stage, under `waitUntil` when the platform has it, else inline until
+ * {@link INLINE_DEADLINE_MS}. A failure that remains is reported once.
+ */
+export declare function settleInvalidation(op: InvalidationOp, targets: InvalidationTargets, req: Request, platform: ISRPlatform | undefined, options?: SettleOptions): Promise<InvalidationReport>;
+/** The default report: the operation id and the stage, never a path, tag or key. */
+export declare function logInvalidation(report: InvalidationReport): void;
+//# sourceMappingURL=invalidation.d.ts.map

package/dist/internal/invalidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalidation.d.ts","sourceRoot":"","sources":["../../src/internal/invalidation.ts"],"names":[],"mappings":"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"}