@rsc-kit/core 0.24.3 → 0.26.0

package/dist/changed.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Names: a name for data a page depends on, so whatever changes it can say so
+ * from anywhere - a webhook, a job, another visitor's action - and every open
+ * tab showing it refreshes.
+ *
+ *     // a section says what it depends on
+ *     export default section('repos', Repos, { refreshOn: ({ params }) => [`team:${params.team}:repos`] })
+ *
+ *     // and whatever changes it says so
+ *     changed(`team:${team}:repos`)           // here, from a route.ts or an action
+ *     rsckit.Changed(ctx, "team:1:repos")     // or the backend, from its webhook
+ *     Rsc::changed("team:$team:repos");       // Laravel
+ *
+ * A name has a version: a number that moves whenever something says the name
+ * changed. Nothing else - not what changed, not the data. A page learns the
+ * versions at render; one stream per open tab watches them; when one moves,
+ * the sections carrying that name ask for themselves again, the way refresh()
+ * does. Data is never pushed, which is what keeps this working on a host that
+ * cannot hold state: a version is a read.
+ *
+ * Where versions live is the source's business. Without a backend they are in
+ * this process, which is one instance. With one, the backend keeps them - in
+ * its cache or a table, shared by every instance it runs - and answers
+ * `__rsc.changed`: given the versions a watcher holds, the ones that differ now.
+ * A backend that can wait holds the call until one does; one that cannot
+ * answers at once, and the watcher asks again on its interval. The protocol
+ * is the same either way, and so is the page.
+ */
+/** The reserved name a backend answers name versions on. */
+export declare const CHANGED_FUNCTION = "__rsc.changed";
+/** What `__rsc.changed` is asked. */
+export interface ChangedQuery {
+    /** The versions the asker holds. A name never changed is 0; -1 asks for every current version. */
+    since: Record<string, number>;
+    /** How long the backend may hold the call waiting for one to differ, in ms. It may answer at once. */
+    wait?: number;
+}
+/** What `__rsc.changed` answers: the versions among `since` that differ now. */
+export interface ChangedAnswer {
+    versions: Record<string, number>;
+}
+/**
+ * Where name versions are read from, and - when they live here - bumped.
+ *
+ * `changed` answers the versions among `since` that differ now, and may wait
+ * up to `wait` ms for one to. Nothing else is required of it, which is why a
+ * backend's cache, a table, this process's memory, or a pub/sub that answers
+ * the moment a name moves all fit behind it.
+ */
+export interface VersionSource {
+    changed(since: Record<string, number>, wait: number): Promise<Record<string, number>>;
+    /** Say these names changed. Only a source that holds its own versions can. */
+    bump(names: string[]): void | Promise<void>;
+}
+/** Versions kept in this process: the source without a backend, and the one tests use. */
+export declare function memoryVersions(): VersionSource;
+type HostFn = (name: string, ...args: unknown[]) => Promise<unknown>;
+/**
+ * Versions kept by the backend, read through `__rsc.changed`.
+ *
+ * A backend that has not got the function - an adapter from before names, or
+ * a host of plain rpc functions - is answered from this process instead,
+ * found out on the first ask and remembered, so a page with names still works
+ * on it: one instance, versions bumped by `changed()` here.
+ */
+export declare function backendVersions(call: HostFn): VersionSource;
+/** Install where versions are read from; `null` restores this process's own. */
+export declare function installVersionSource(source: VersionSource | null): void;
+/** The source in use: the backend's when a host is installed, this process's otherwise. */
+export declare function versionSource(): VersionSource;
+/**
+ * Say these names changed, so every open tab showing them refreshes.
+ *
+ *     export async function POST(request: Request) {   // a webhook, in a route.ts
+ *       const { team } = await request.json()
+ *       changed(`team:${team}:repos`)
+ *       return new Response(null, { status: 204 })
+ *     }
+ *
+ * For an app that keeps its versions here. With a backend the versions are
+ * its, and so is the call: `rsckit.Changed`, `Rsc::changed`.
+ */
+export declare function changed(...names: string[]): Promise<void>;
+/**
+ * The key names are signed with. Set from `RSC_HOST_CALL_SECRET` when it is
+ * read; otherwise random, which is right for one process and wrong for two -
+ * a tab served by one instance presents its names to another and is refused.
+ */
+export declare function configureChanged(options: {
+    secret?: string | null;
+}): void;
+/** A name's signature: the first 16 bytes of an HMAC, base64url, which is what rides in a url. */
+export declare function sign(name: string): Promise<string>;
+/** What a page hands the client for one name: its version at render, and its signature. */
+export type SignedName = [version: number, signature: string];
+/** How often the source is asked, when it answered at once. */
+export declare const CHANGES_INTERVAL_MS = 2000;
+/** How long the source may hold one ask. Bounds how long a new tab waits to join the shared ask. */
+export declare const CHANGES_WAIT_MS = 5000;
+/**
+ * The stream a tab watches its names on: `GET /_rsc/changes?w=[[name, version, signature], …]`.
+ *
+ * One `data:` line per version that moved, `{ name, version }`, from the moment
+ * the stream opens - a name that moved between the render and now is reported
+ * at once, so nothing that happened in the gap is missed. Keepalives as an
+ * events() route sends them; ends when the browser goes away.
+ */
+export declare function changes(request: Request): Promise<Response>;
+/** For tests: forget every stream and version this process has seen. */
+export declare function resetChanges(): void;
+/** The url a tab opens to watch, for the client. */
+export declare const CHANGES_PATH: "/_rsc/changes";
+export {};

package/dist/changed.js

@@ -0,0 +1,399 @@
+/**
+ * Names: a name for data a page depends on, so whatever changes it can say so
+ * from anywhere - a webhook, a job, another visitor's action - and every open
+ * tab showing it refreshes.
+ *
+ *     // a section says what it depends on
+ *     export default section('repos', Repos, { refreshOn: ({ params }) => [`team:${params.team}:repos`] })
+ *
+ *     // and whatever changes it says so
+ *     changed(`team:${team}:repos`)           // here, from a route.ts or an action
+ *     rsckit.Changed(ctx, "team:1:repos")     // or the backend, from its webhook
+ *     Rsc::changed("team:$team:repos");       // Laravel
+ *
+ * A name has a version: a number that moves whenever something says the name
+ * changed. Nothing else - not what changed, not the data. A page learns the
+ * versions at render; one stream per open tab watches them; when one moves,
+ * the sections carrying that name ask for themselves again, the way refresh()
+ * does. Data is never pushed, which is what keeps this working on a host that
+ * cannot hold state: a version is a read.
+ *
+ * Where versions live is the source's business. Without a backend they are in
+ * this process, which is one instance. With one, the backend keeps them - in
+ * its cache or a table, shared by every instance it runs - and answers
+ * `__rsc.changed`: given the versions a watcher holds, the ones that differ now.
+ * A backend that can wait holds the call until one does; one that cannot
+ * answers at once, and the watcher asks again on its interval. The protocol
+ * is the same either way, and so is the page.
+ */
+import { KEEPALIVE_MS, frame } from "./events.js";
+import { HEADER } from "./headers.js";
+/** The reserved name a backend answers name versions on. */
+export const CHANGED_FUNCTION = "__rsc.changed";
+/** Versions kept in this process: the source without a backend, and the one tests use. */
+export function memoryVersions() {
+    const versions = new Map();
+    const waiters = new Set();
+    const differing = (since) => {
+        const out = {};
+        for (const [name, held] of Object.entries(since)) {
+            const current = versions.get(name) ?? 0;
+            if (current !== held)
+                out[name] = current;
+        }
+        return out;
+    };
+    return {
+        async changed(since, wait) {
+            const now = differing(since);
+            if (Object.keys(now).length > 0 || wait <= 0)
+                return now;
+            await new Promise((resolve) => {
+                const done = () => {
+                    clearTimeout(timer);
+                    waiters.delete(done);
+                    resolve();
+                };
+                const timer = setTimeout(done, wait);
+                // A test or a build must not be held open by a watcher's wait.
+                timer.unref?.();
+                waiters.add(done);
+            });
+            return differing(since);
+        },
+        bump(names) {
+            for (const name of names)
+                versions.set(name, (versions.get(name) ?? 0) + 1);
+            for (const wake of [...waiters])
+                wake();
+        },
+    };
+}
+/**
+ * Versions kept by the backend, read through `__rsc.changed`.
+ *
+ * A backend that has not got the function - an adapter from before names, or
+ * a host of plain rpc functions - is answered from this process instead,
+ * found out on the first ask and remembered, so a page with names still works
+ * on it: one instance, versions bumped by `changed()` here.
+ */
+export function backendVersions(call) {
+    let local = null;
+    // A backend's "no such function", or the test host's "no handler for".
+    const unknown = (error) => /no host function named|has no handler for/i.test(error instanceof Error ? error.message : String(error));
+    return {
+        async changed(since, wait) {
+            if (local)
+                return local.changed(since, wait);
+            try {
+                const answer = (await call(CHANGED_FUNCTION, {
+                    since,
+                    wait,
+                }));
+                return answer?.versions ?? {};
+            }
+            catch (error) {
+                if (!unknown(error))
+                    throw error;
+                local = memoryVersions();
+                return local.changed(since, wait);
+            }
+        },
+        bump(names) {
+            if (local)
+                return local.bump(names);
+            throw new Error("changed() bumps versions this process keeps, and a backend keeps these: say the name changed there - " +
+                "rsckit.Changed(ctx, ...) in Go, Rsc::changed(...) in Laravel.");
+        },
+    };
+}
+const SOURCE = Symbol.for("rsc-kit.version-source");
+const globals = globalThis;
+/** Install where versions are read from; `null` restores this process's own. */
+export function installVersionSource(source) {
+    globals[SOURCE] = source;
+}
+/** The source in use: the backend's when a host is installed, this process's otherwise. */
+export function versionSource() {
+    return (globals[SOURCE] ??= memoryVersions());
+}
+/**
+ * Say these names changed, so every open tab showing them refreshes.
+ *
+ *     export async function POST(request: Request) {   // a webhook, in a route.ts
+ *       const { team } = await request.json()
+ *       changed(`team:${team}:repos`)
+ *       return new Response(null, { status: 204 })
+ *     }
+ *
+ * For an app that keeps its versions here. With a backend the versions are
+ * its, and so is the call: `rsckit.Changed`, `Rsc::changed`.
+ */
+export async function changed(...names) {
+    await versionSource().bump(names);
+}
+// ── Tokens ───────────────────────────────────────────────────────────────────
+//
+// A tab may watch exactly the names its page was rendered with. Rather than
+// remembering what each tab was given - state, which a Worker cannot keep
+// between requests - every name goes to the client signed, and comes back
+// with its signature. Verified, not looked up, so a watch request is
+// stateless, and a browser cannot make up a name to watch.
+let secret = null;
+let keyed = null;
+const signatures = new Map();
+/**
+ * The key names are signed with. Set from `RSC_HOST_CALL_SECRET` when it is
+ * read; otherwise random, which is right for one process and wrong for two -
+ * a tab served by one instance presents its names to another and is refused.
+ */
+export function configureChanged(options) {
+    secret = options.secret ?? null;
+    keyed = null;
+    signatures.clear();
+}
+async function key() {
+    return (keyed ??= (async () => {
+        let raw;
+        if (!secret && typeof process !== "undefined") {
+            secret = process.env?.RSC_HOST_CALL_SECRET ?? null;
+        }
+        if (secret)
+            raw = new TextEncoder().encode(secret);
+        else
+            raw = crypto.getRandomValues(new Uint8Array(32));
+        return await crypto.subtle.importKey("raw", raw, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    })());
+}
+/** A name's signature: the first 16 bytes of an HMAC, base64url, which is what rides in a url. */
+export function sign(name) {
+    let pending = signatures.get(name);
+    if (!pending) {
+        pending = (async () => {
+            const mac = await crypto.subtle.sign("HMAC", await key(), new TextEncoder().encode(name));
+            return base64url(new Uint8Array(mac).slice(0, 16));
+        })();
+        // Bounded: a name with a visitor's id in it is a new entry per visitor.
+        if (signatures.size > 10_000)
+            signatures.clear();
+        signatures.set(name, pending);
+    }
+    return pending;
+}
+async function verify(name, signature) {
+    const expected = await sign(name);
+    if (expected.length !== signature.length)
+        return false;
+    let differ = 0;
+    for (let i = 0; i < expected.length; i++)
+        differ |= expected.charCodeAt(i) ^ signature.charCodeAt(i);
+    return differ === 0;
+}
+function base64url(bytes) {
+    let text = "";
+    for (const byte of bytes)
+        text += String.fromCharCode(byte);
+    return btoa(text).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+// ── Watching ─────────────────────────────────────────────────────────────────
+//
+// One stream per open tab, and one ask of the source per process: every
+// stream's names are asked about together, on an interval, and a version that
+// moved is written to every stream holding its name. A thousand tabs on a
+// long-lived server cost the backend one call per interval, not a thousand.
+// On a host that answers each request in its own isolate the sharing is
+// whatever the isolate serves at once, and a lone stream asks for itself -
+// the same code, degrading to one small call per tab per interval.
+/** How often the source is asked, when it answered at once. */
+export const CHANGES_INTERVAL_MS = 2_000;
+/** How long the source may hold one ask. Bounds how long a new tab waits to join the shared ask. */
+export const CHANGES_WAIT_MS = 5_000;
+const streams = new Set();
+/** The latest version seen for each name any stream holds. */
+const known = new Map();
+let running = false;
+let wake = null;
+let warned = false;
+function observe(name, version) {
+    if (known.get(name) === version)
+        return;
+    known.set(name, version);
+    for (const stream of streams)
+        if (stream.names.has(name))
+            stream.send(name, version);
+}
+/** Mapped to this process's set of streams: what to ask about, relative to what is known. */
+function sinceAll() {
+    const since = {};
+    for (const stream of streams)
+        for (const name of stream.names)
+            since[name] = known.get(name) ?? 0;
+    return since;
+}
+async function loop() {
+    running = true;
+    try {
+        while (streams.size > 0) {
+            const started = Date.now();
+            try {
+                const moved = await versionSource().changed(sinceAll(), CHANGES_WAIT_MS);
+                for (const [name, version] of Object.entries(moved))
+                    observe(name, version);
+            }
+            catch (error) {
+                // A backend blip is not the end of watching. Said once, not per interval.
+                if (!warned) {
+                    warned = true;
+                    console.warn("[rsc-kit] asking the backend for name versions failed: " +
+                        (error instanceof Error ? error.message : String(error)));
+                }
+            }
+            // A source that waited used the interval; one that answered at once is
+            // asked again after it. A stream opening meanwhile wakes this early.
+            const remaining = CHANGES_INTERVAL_MS - (Date.now() - started);
+            if (remaining > 0 && streams.size > 0) {
+                await new Promise((resolve) => {
+                    const timer = setTimeout(resolve, remaining);
+                    timer.unref?.();
+                    wake = () => {
+                        clearTimeout(timer);
+                        resolve();
+                    };
+                });
+                wake = null;
+            }
+        }
+    }
+    finally {
+        running = false;
+        // A stream that opened as the loop was ending starts it again.
+        if (streams.size > 0)
+            void loop();
+    }
+}
+function parseWatch(url) {
+    const raw = url.searchParams.get("w");
+    if (!raw)
+        return null;
+    let entries;
+    try {
+        entries = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(entries) || entries.length === 0 || entries.length > 200)
+        return null;
+    const parsed = [];
+    for (const entry of entries) {
+        if (!Array.isArray(entry) || entry.length !== 3)
+            return null;
+        const [name, version, signature] = entry;
+        if (typeof name !== "string" ||
+            typeof version !== "number" ||
+            typeof signature !== "string")
+            return null;
+        parsed.push({ name, version, signature });
+    }
+    return parsed;
+}
+/**
+ * The stream a tab watches its names on: `GET /_rsc/changes?w=[[name, version, signature], …]`.
+ *
+ * One `data:` line per version that moved, `{ name, version }`, from the moment
+ * the stream opens - a name that moved between the render and now is reported
+ * at once, so nothing that happened in the gap is missed. Keepalives as an
+ * events() route sends them; ends when the browser goes away.
+ */
+export async function changes(request) {
+    const entries = parseWatch(new URL(request.url));
+    if (!entries)
+        return new Response("Bad watch request.", { status: 400 });
+    for (const { name, signature } of entries) {
+        if (!(await verify(name, signature))) {
+            return new Response("Not a name this page was rendered with.", {
+                status: 403,
+            });
+        }
+    }
+    const since = {};
+    for (const { name, version } of entries)
+        since[name] = version;
+    const encoder = new TextEncoder();
+    let stream = null;
+    const body = new ReadableStream({
+        start(sink) {
+            const write = (text) => {
+                try {
+                    sink.enqueue(encoder.encode(text));
+                }
+                catch {
+                    // Closed under us; the cancel below ends the rest.
+                }
+            };
+            write("retry: 2000\n\n");
+            const keepalive = setInterval(() => write(": keepalive\n\n"), KEEPALIVE_MS);
+            keepalive.unref?.();
+            const me = {
+                names: new Set(Object.keys(since)),
+                send: (name, version) => write(frame({ name, version })),
+            };
+            stream = me;
+            streams.add(me);
+            const end = () => {
+                clearInterval(keepalive);
+                streams.delete(me);
+                try {
+                    sink.close();
+                }
+                catch {
+                    // Already closed.
+                }
+            };
+            request.signal.addEventListener("abort", end, { once: true });
+            // What is known already answers at once; what is not is seeded with
+            // what this tab holds, so the shared ask compares against it.
+            for (const [name, version] of Object.entries(since)) {
+                const seen = known.get(name);
+                if (seen === undefined)
+                    known.set(name, version);
+                else if (seen !== version)
+                    me.send(name, seen);
+            }
+            // This tab's own first ask, holding as long as the source will: the
+            // shared ask may be mid-wait on an older set of names, and a name moving
+            // in the seconds before this one joins it must not go unnoticed.
+            void versionSource()
+                .changed(since, CHANGES_WAIT_MS)
+                .then((moved) => {
+                for (const [name, version] of Object.entries(moved))
+                    observe(name, version);
+            })
+                .catch(() => { });
+            if (!running)
+                void loop();
+            else
+                wake?.();
+        },
+        cancel() {
+            if (stream)
+                streams.delete(stream);
+        },
+    });
+    return new Response(body, {
+        headers: {
+            "Content-Type": "text/event-stream; charset=utf-8",
+            "Cache-Control": "no-store",
+            "X-Accel-Buffering": "no",
+        },
+    });
+}
+/** For tests: forget every stream and version this process has seen. */
+export function resetChanges() {
+    streams.clear();
+    known.clear();
+    warned = false;
+}
+/** The url a tab opens to watch, for the client. */
+export const CHANGES_PATH = HEADER.changesPath;
+//# sourceMappingURL=changed.js.map

package/dist/changed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changed.js","sourceRoot":"","sources":["../src/changed.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Names: a name for data a page depends on, so whatever changes it can say so\n * from anywhere - a webhook, a job, another visitor's action - and every open\n * tab showing it refreshes.\n *\n *     // a section says what it depends on\n *     export default section('repos', Repos, { refreshOn: ({ params }) => [`team:${params.team}:repos`] })\n *\n *     // and whatever changes it says so\n *     changed(`team:${team}:repos`)           // here, from a route.ts or an action\n *     rsckit.Changed(ctx, \"team:1:repos\")     // or the backend, from its webhook\n *     Rsc::changed(\"team:$team:repos\");       // Laravel\n *\n * A name has a version: a number that moves whenever something says the name\n * changed. Nothing else - not what changed, not the data. A page learns the\n * versions at render; one stream per open tab watches them; when one moves,\n * the sections carrying that name ask for themselves again, the way refresh()\n * does. Data is never pushed, which is what keeps this working on a host that\n * cannot hold state: a version is a read.\n *\n * Where versions live is the source's business. Without a backend they are in\n * this process, which is one instance. With one, the backend keeps them - in\n * its cache or a table, shared by every instance it runs - and answers\n * `__rsc.changed`: given the versions a watcher holds, the ones that differ now.\n * A backend that can wait holds the call until one does; one that cannot\n * answers at once, and the watcher asks again on its interval. The protocol\n * is the same either way, and so is the page.\n */\n\nimport { KEEPALIVE_MS, frame } from \"./events.js\";\nimport { HEADER } from \"./headers.js\";\n\n/** The reserved name a backend answers name versions on. */\nexport const CHANGED_FUNCTION = \"__rsc.changed\";\n\n/** What `__rsc.changed` is asked. */\nexport interface ChangedQuery {\n  /** The versions the asker holds. A name never changed is 0; -1 asks for every current version. */\n  since: Record<string, number>;\n  /** How long the backend may hold the call waiting for one to differ, in ms. It may answer at once. */\n  wait?: number;\n}\n\n/** What `__rsc.changed` answers: the versions among `since` that differ now. */\nexport interface ChangedAnswer {\n  versions: Record<string, number>;\n}\n\n/**\n * Where name versions are read from, and - when they live here - bumped.\n *\n * `changed` answers the versions among `since` that differ now, and may wait\n * up to `wait` ms for one to. Nothing else is required of it, which is why a\n * backend's cache, a table, this process's memory, or a pub/sub that answers\n * the moment a name moves all fit behind it.\n */\nexport interface VersionSource {\n  changed(\n    since: Record<string, number>,\n    wait: number,\n  ): Promise<Record<string, number>>;\n  /** Say these names changed. Only a source that holds its own versions can. */\n  bump(names: string[]): void | Promise<void>;\n}\n\n/** Versions kept in this process: the source without a backend, and the one tests use. */\nexport function memoryVersions(): VersionSource {\n  const versions = new Map<string, number>();\n  const waiters = new Set<() => void>();\n\n  const differing = (since: Record<string, number>): Record<string, number> => {\n    const out: Record<string, number> = {};\n\n    for (const [name, held] of Object.entries(since)) {\n      const current = versions.get(name) ?? 0;\n\n      if (current !== held) out[name] = current;\n    }\n\n    return out;\n  };\n\n  return {\n    async changed(since, wait) {\n      const now = differing(since);\n\n      if (Object.keys(now).length > 0 || wait <= 0) return now;\n\n      await new Promise<void>((resolve) => {\n        const done = () => {\n          clearTimeout(timer);\n          waiters.delete(done);\n          resolve();\n        };\n        const timer = setTimeout(done, wait);\n\n        // A test or a build must not be held open by a watcher's wait.\n        (timer as { unref?: () => void }).unref?.();\n        waiters.add(done);\n      });\n\n      return differing(since);\n    },\n    bump(names) {\n      for (const name of names) versions.set(name, (versions.get(name) ?? 0) + 1);\n      for (const wake of [...waiters]) wake();\n    },\n  };\n}\n\ntype HostFn = (name: string, ...args: unknown[]) => Promise<unknown>;\n\n/**\n * Versions kept by the backend, read through `__rsc.changed`.\n *\n * A backend that has not got the function - an adapter from before names, or\n * a host of plain rpc functions - is answered from this process instead,\n * found out on the first ask and remembered, so a page with names still works\n * on it: one instance, versions bumped by `changed()` here.\n */\nexport function backendVersions(call: HostFn): VersionSource {\n  let local: VersionSource | null = null;\n\n  // A backend's \"no such function\", or the test host's \"no handler for\".\n  const unknown = (error: unknown): boolean =>\n    /no host function named|has no handler for/i.test(\n      error instanceof Error ? error.message : String(error),\n    );\n\n  return {\n    async changed(since, wait) {\n      if (local) return local.changed(since, wait);\n\n      try {\n        const answer = (await call(CHANGED_FUNCTION, {\n          since,\n          wait,\n        } satisfies ChangedQuery)) as Partial<ChangedAnswer> | null;\n\n        return answer?.versions ?? {};\n      } catch (error) {\n        if (!unknown(error)) throw error;\n\n        local = memoryVersions();\n\n        return local.changed(since, wait);\n      }\n    },\n    bump(names) {\n      if (local) return local.bump(names);\n\n      throw new Error(\n        \"changed() bumps versions this process keeps, and a backend keeps these: say the name changed there - \" +\n          \"rsckit.Changed(ctx, ...) in Go, Rsc::changed(...) in Laravel.\",\n      );\n    },\n  };\n}\n\nconst SOURCE = Symbol.for(\"rsc-kit.version-source\");\nconst globals = globalThis as Record<symbol, unknown>;\n\n/** Install where versions are read from; `null` restores this process's own. */\nexport function installVersionSource(source: VersionSource | null): void {\n  globals[SOURCE] = source;\n}\n\n/** The source in use: the backend's when a host is installed, this process's otherwise. */\nexport function versionSource(): VersionSource {\n  return ((globals[SOURCE] as VersionSource | undefined) ??= memoryVersions());\n}\n\n/**\n * Say these names changed, so every open tab showing them refreshes.\n *\n *     export async function POST(request: Request) {   // a webhook, in a route.ts\n *       const { team } = await request.json()\n *       changed(`team:${team}:repos`)\n *       return new Response(null, { status: 204 })\n *     }\n *\n * For an app that keeps its versions here. With a backend the versions are\n * its, and so is the call: `rsckit.Changed`, `Rsc::changed`.\n */\nexport async function changed(...names: string[]): Promise<void> {\n  await versionSource().bump(names);\n}\n\n// ── Tokens ───────────────────────────────────────────────────────────────────\n//\n// A tab may watch exactly the names its page was rendered with. Rather than\n// remembering what each tab was given - state, which a Worker cannot keep\n// between requests - every name goes to the client signed, and comes back\n// with its signature. Verified, not looked up, so a watch request is\n// stateless, and a browser cannot make up a name to watch.\n\nlet secret: string | null = null;\nlet keyed: Promise<CryptoKey> | null = null;\nconst signatures = new Map<string, Promise<string>>();\n\n/**\n * The key names are signed with. Set from `RSC_HOST_CALL_SECRET` when it is\n * read; otherwise random, which is right for one process and wrong for two -\n * a tab served by one instance presents its names to another and is refused.\n */\nexport function configureChanged(options: { secret?: string | null }): void {\n  secret = options.secret ?? null;\n  keyed = null;\n  signatures.clear();\n}\n\nasync function key(): Promise<CryptoKey> {\n  return (keyed ??= (async () => {\n    let raw: Uint8Array<ArrayBuffer>;\n\n    if (!secret && typeof process !== \"undefined\") {\n      secret = process.env?.RSC_HOST_CALL_SECRET ?? null;\n    }\n\n    if (secret) raw = new TextEncoder().encode(secret);\n    else raw = crypto.getRandomValues(new Uint8Array(32));\n\n    return await crypto.subtle.importKey(\n      \"raw\",\n      raw,\n      { name: \"HMAC\", hash: \"SHA-256\" },\n      false,\n      [\"sign\"],\n    );\n  })());\n}\n\n/** A name's signature: the first 16 bytes of an HMAC, base64url, which is what rides in a url. */\nexport function sign(name: string): Promise<string> {\n  let pending = signatures.get(name);\n\n  if (!pending) {\n    pending = (async () => {\n      const mac = await crypto.subtle.sign(\n        \"HMAC\",\n        await key(),\n        new TextEncoder().encode(name),\n      );\n\n      return base64url(new Uint8Array(mac).slice(0, 16));\n    })();\n\n    // Bounded: a name with a visitor's id in it is a new entry per visitor.\n    if (signatures.size > 10_000) signatures.clear();\n    signatures.set(name, pending);\n  }\n\n  return pending;\n}\n\nasync function verify(name: string, signature: string): Promise<boolean> {\n  const expected = await sign(name);\n\n  if (expected.length !== signature.length) return false;\n\n  let differ = 0;\n\n  for (let i = 0; i < expected.length; i++)\n    differ |= expected.charCodeAt(i) ^ signature.charCodeAt(i);\n\n  return differ === 0;\n}\n\nfunction base64url(bytes: Uint8Array): string {\n  let text = \"\";\n\n  for (const byte of bytes) text += String.fromCharCode(byte);\n\n  return btoa(text).replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\");\n}\n\n/** What a page hands the client for one name: its version at render, and its signature. */\nexport type SignedName = [version: number, signature: string];\n\n// ── Watching ─────────────────────────────────────────────────────────────────\n//\n// One stream per open tab, and one ask of the source per process: every\n// stream's names are asked about together, on an interval, and a version that\n// moved is written to every stream holding its name. A thousand tabs on a\n// long-lived server cost the backend one call per interval, not a thousand.\n// On a host that answers each request in its own isolate the sharing is\n// whatever the isolate serves at once, and a lone stream asks for itself -\n// the same code, degrading to one small call per tab per interval.\n\n/** How often the source is asked, when it answered at once. */\nexport const CHANGES_INTERVAL_MS = 2_000;\n\n/** How long the source may hold one ask. Bounds how long a new tab waits to join the shared ask. */\nexport const CHANGES_WAIT_MS = 5_000;\n\ninterface Stream {\n  names: Set<string>;\n  send(name: string, version: number): void;\n}\n\nconst streams = new Set<Stream>();\n\n/** The latest version seen for each name any stream holds. */\nconst known = new Map<string, number>();\n\nlet running = false;\nlet wake: (() => void) | null = null;\nlet warned = false;\n\nfunction observe(name: string, version: number): void {\n  if (known.get(name) === version) return;\n\n  known.set(name, version);\n\n  for (const stream of streams)\n    if (stream.names.has(name)) stream.send(name, version);\n}\n\n/** Mapped to this process's set of streams: what to ask about, relative to what is known. */\nfunction sinceAll(): Record<string, number> {\n  const since: Record<string, number> = {};\n\n  for (const stream of streams)\n    for (const name of stream.names) since[name] = known.get(name) ?? 0;\n\n  return since;\n}\n\nasync function loop(): Promise<void> {\n  running = true;\n\n  try {\n    while (streams.size > 0) {\n      const started = Date.now();\n\n      try {\n        const moved = await versionSource().changed(\n          sinceAll(),\n          CHANGES_WAIT_MS,\n        );\n\n        for (const [name, version] of Object.entries(moved))\n          observe(name, version);\n      } catch (error) {\n        // A backend blip is not the end of watching. Said once, not per interval.\n        if (!warned) {\n          warned = true;\n          console.warn(\n            \"[rsc-kit] asking the backend for name versions failed: \" +\n              (error instanceof Error ? error.message : String(error)),\n          );\n        }\n      }\n\n      // A source that waited used the interval; one that answered at once is\n      // asked again after it. A stream opening meanwhile wakes this early.\n      const remaining = CHANGES_INTERVAL_MS - (Date.now() - started);\n\n      if (remaining > 0 && streams.size > 0) {\n        await new Promise<void>((resolve) => {\n          const timer = setTimeout(resolve, remaining);\n\n          (timer as { unref?: () => void }).unref?.();\n          wake = () => {\n            clearTimeout(timer);\n            resolve();\n          };\n        });\n        wake = null;\n      }\n    }\n  } finally {\n    running = false;\n    // A stream that opened as the loop was ending starts it again.\n    if (streams.size > 0) void loop();\n  }\n}\n\nfunction parseWatch(\n  url: URL,\n): { name: string; version: number; signature: string }[] | null {\n  const raw = url.searchParams.get(\"w\");\n\n  if (!raw) return null;\n\n  let entries: unknown;\n\n  try {\n    entries = JSON.parse(raw);\n  } catch {\n    return null;\n  }\n\n  if (!Array.isArray(entries) || entries.length === 0 || entries.length > 200)\n    return null;\n\n  const parsed: { name: string; version: number; signature: string }[] = [];\n\n  for (const entry of entries) {\n    if (!Array.isArray(entry) || entry.length !== 3) return null;\n\n    const [name, version, signature] = entry as unknown[];\n\n    if (\n      typeof name !== \"string\" ||\n      typeof version !== \"number\" ||\n      typeof signature !== \"string\"\n    )\n      return null;\n\n    parsed.push({ name, version, signature });\n  }\n\n  return parsed;\n}\n\n/**\n * The stream a tab watches its names on: `GET /_rsc/changes?w=[[name, version, signature], …]`.\n *\n * One `data:` line per version that moved, `{ name, version }`, from the moment\n * the stream opens - a name that moved between the render and now is reported\n * at once, so nothing that happened in the gap is missed. Keepalives as an\n * events() route sends them; ends when the browser goes away.\n */\nexport async function changes(request: Request): Promise<Response> {\n  const entries = parseWatch(new URL(request.url));\n\n  if (!entries) return new Response(\"Bad watch request.\", { status: 400 });\n\n  for (const { name, signature } of entries) {\n    if (!(await verify(name, signature))) {\n      return new Response(\"Not a name this page was rendered with.\", {\n        status: 403,\n      });\n    }\n  }\n\n  const since: Record<string, number> = {};\n\n  for (const { name, version } of entries) since[name] = version;\n\n  const encoder = new TextEncoder();\n  let stream: Stream | null = null;\n\n  const body = new ReadableStream<Uint8Array>({\n    start(sink) {\n      const write = (text: string) => {\n        try {\n          sink.enqueue(encoder.encode(text));\n        } catch {\n          // Closed under us; the cancel below ends the rest.\n        }\n      };\n\n      write(\"retry: 2000\\n\\n\");\n\n      const keepalive = setInterval(\n        () => write(\": keepalive\\n\\n\"),\n        KEEPALIVE_MS,\n      );\n\n      (keepalive as { unref?: () => void }).unref?.();\n\n      const me: Stream = {\n        names: new Set(Object.keys(since)),\n        send: (name, version) => write(frame({ name, version })),\n      };\n\n      stream = me;\n      streams.add(me);\n\n      const end = () => {\n        clearInterval(keepalive);\n        streams.delete(me);\n\n        try {\n          sink.close();\n        } catch {\n          // Already closed.\n        }\n      };\n\n      request.signal.addEventListener(\"abort\", end, { once: true });\n\n      // What is known already answers at once; what is not is seeded with\n      // what this tab holds, so the shared ask compares against it.\n      for (const [name, version] of Object.entries(since)) {\n        const seen = known.get(name);\n\n        if (seen === undefined) known.set(name, version);\n        else if (seen !== version) me.send(name, seen);\n      }\n\n      // This tab's own first ask, holding as long as the source will: the\n      // shared ask may be mid-wait on an older set of names, and a name moving\n      // in the seconds before this one joins it must not go unnoticed.\n      void versionSource()\n        .changed(since, CHANGES_WAIT_MS)\n        .then((moved) => {\n          for (const [name, version] of Object.entries(moved))\n            observe(name, version);\n        })\n        .catch(() => {});\n\n      if (!running) void loop();\n      else wake?.();\n    },\n    cancel() {\n      if (stream) streams.delete(stream);\n    },\n  });\n\n  return new Response(body, {\n    headers: {\n      \"Content-Type\": \"text/event-stream; charset=utf-8\",\n      \"Cache-Control\": \"no-store\",\n      \"X-Accel-Buffering\": \"no\",\n    },\n  });\n}\n\n/** For tests: forget every stream and version this process has seen. */\nexport function resetChanges(): void {\n  streams.clear();\n  known.clear();\n  warned = false;\n}\n\n/** The url a tab opens to watch, for the client. */\nexport const CHANGES_PATH = HEADER.changesPath;\n"]}

package/dist/conformance.d.ts

@@ -44,6 +44,8 @@ export declare const CASES: {
     readonly 'Conformance.fail': 'Fail unexpectedly: an ordinary error, not a refusal.';
     readonly 'Conformance.authorization': "Return the request's Authorization header, as the renderer forwarded it.";
     readonly '__rsc.middleware': 'Guards: "conformance-allow" passes; "conformance-deny" refuses; a name with no guard refuses.';
+    readonly 'Conformance.change': 'Say the name "conformance:changed" changed, the way the adapter does from a webhook, and return "ok".';
+    readonly '__rsc.changed': string;
 };
 /**
  * Run the suite against a client. Every case runs; none stops another.

package/dist/conformance.js

@@ -46,6 +46,9 @@ export const CASES = {
     'Conformance.fail': 'Fail unexpectedly: an ordinary error, not a refusal.',
     'Conformance.authorization': "Return the request's Authorization header, as the renderer forwarded it.",
     '__rsc.middleware': 'Guards: "conformance-allow" passes; "conformance-deny" refuses; a name with no guard refuses.',
+    'Conformance.change': 'Say the name "conformance:changed" changed, the way the adapter does from a webhook, and return "ok".',
+    '__rsc.changed': 'Given { since: { name: version }, wait }: answer { versions } with every name whose version differs from since now. ' +
+        'A name never changed is at 0. May hold the call up to wait ms for one to differ; may answer at once.',
 };
 const INSTANT = Date.parse('2026-01-02T03:04:05Z');
 const ECHOES = [null, 0, -1.5, 'héllo ✓ "quoted"', [1, 'a', null], { a: { b: [true, false] }, c: '' }];
@@ -180,6 +183,31 @@ export async function conformance(call, options) {
         const value = await call('__rsc.middleware', ['conformance-nobody-registered-this']).catch((e) => e);
         expect(value !== true, 'it answered true');
     });
+    const versionsOf = async (query) => {
+        const answer = (await call('__rsc.changed', query));
+        expect(typeof answer?.versions === 'object' && answer.versions !== null, 'got ' + JSON.stringify(answer));
+        return answer.versions;
+    };
+    await check('a name nobody changed is at version 0, and unchanged from 0', async () => {
+        const all = await versionsOf({ since: { 'conformance:never': -1 } });
+        expect(all['conformance:never'] === 0, 'from -1: ' + JSON.stringify(all));
+        const none = await versionsOf({ since: { 'conformance:never': 0 } });
+        expect(Object.keys(none).length === 0, 'from 0: ' + JSON.stringify(none));
+    });
+    await check('saying a name changed moves its version', async () => {
+        const before = (await versionsOf({ since: { 'conformance:changed': -1 } }))['conformance:changed'] ?? 0;
+        const value = await call('Conformance.change');
+        expect(value === 'ok', 'got ' + JSON.stringify(value));
+        const moved = await versionsOf({ since: { 'conformance:changed': before } });
+        expect(typeof moved['conformance:changed'] === 'number' && moved['conformance:changed'] !== before, 'from ' + before + ': ' + JSON.stringify(moved));
+    });
+    await check('waiting for a name to change is bounded by wait', async () => {
+        const started = Date.now();
+        const none = await versionsOf({ since: { 'conformance:never': 0 }, wait: 300 });
+        const took = Date.now() - started;
+        expect(Object.keys(none).length === 0, 'got ' + JSON.stringify(none));
+        expect(took < 3_000, 'took ' + took + 'ms');
+    });
     if (wrongSecret) {
         await check('a call with the wrong secret is refused', async () => {
             const value = await wrongSecret('Conformance.echo', 'should not run').catch((e) => e);