@rsc-kit/core 0.25.0 → 0.27.0

package/dist/changed.js

@@ -0,0 +1,605 @@
+/**
+ * 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.");
+        },
+    };
+}
+/**
+ * Versions in a table every instance shares: the web servers, and the worker
+ * that finishes a job and says so. The same table and columns Go's
+ * `SQLVersions` uses, so a Go service and a JavaScript worker can share one.
+ *
+ *     installVersionSource(sqlVersions({
+ *       query: (text, params) => sql.unsafe(text, params),
+ *       placeholder: (n) => '$' + n,
+ *       listen: (wake) => sql.listen('rsc_versions', wake),
+ *       notify: () => sql.notify('rsc_versions', ''),
+ *     }))
+ *
+ * Written with an UPDATE and, the first time, an INSERT - two statements any
+ * SQL dialect has - rather than an upsert each spells differently. Takes the
+ * app's own driver, so the engine has no database dependency of its own.
+ */
+export function sqlVersions(options) {
+    const { query } = options;
+    const table = options.table ?? "rsc_versions";
+    const mark = options.placeholder ?? (() => "?");
+    return createVersions({
+        async read(names) {
+            const rows = await query(`SELECT name, version FROM ${table} WHERE name IN (${names.map((_, i) => mark(i + 1)).join(", ")})`, names);
+            // A BIGINT comes back as a string from most drivers.
+            return Object.fromEntries(rows.map((row) => [String(row.name), Number(row.version)]));
+        },
+        async bump(names) {
+            const update = `UPDATE ${table} SET version = version + 1 WHERE name = ${mark(1)}`;
+            const insert = `INSERT INTO ${table} (name, version) VALUES (${mark(1)}, 1)`;
+            for (const name of names) {
+                // The row count is not something every driver reports the same way,
+                // so ask: a name with no row yet gets one.
+                const [exists] = await query(`SELECT 1 AS found FROM ${table} WHERE name = ${mark(1)}`, [name]);
+                if (exists) {
+                    await query(update, [name]);
+                    continue;
+                }
+                try {
+                    await query(insert, [name]);
+                }
+                catch {
+                    // Another instance inserted it first: bump that one.
+                    await query(update, [name]);
+                }
+            }
+        },
+        listen: options.listen,
+        notify: options.notify,
+    }, { poll: options.poll });
+}
+/**
+ * A version source over any store: SQL through any driver or ORM - Drizzle,
+ * Prisma, Kysely, Knex - or Redis, or anything with a read and an increment.
+ *
+ *     installVersionSource(createVersions({ read, bump, listen, notify }))
+ *
+ * rsc-kit owns the rest: an ask waits up to the time it was given for a
+ * version to differ, reading every `poll` ms (1000 by default) or the moment
+ * `listen` wakes it, and a bump in this process wakes this process's asks at
+ * once whatever the store.
+ */
+export function createVersions(store, options = {}) {
+    const poll = options.poll ?? 1_000;
+    const waiters = new Set();
+    const wakeAll = () => {
+        for (const wake of [...waiters])
+            wake();
+    };
+    if (store.listen)
+        void Promise.resolve(store.listen(wakeAll)).catch(() => { });
+    const read = async (names) => {
+        if (names.length === 0)
+            return {};
+        const found = await store.read(names);
+        return Object.fromEntries(names.map((name) => [name, Number(found[name] ?? 0)]));
+    };
+    return {
+        async changed(since, wait) {
+            const names = Object.keys(since);
+            const deadline = Date.now() + Math.max(0, wait);
+            for (;;) {
+                const versions = await read(names);
+                const differ = {};
+                for (const name of names)
+                    if (versions[name] !== since[name])
+                        differ[name] = versions[name] ?? 0;
+                const remaining = deadline - Date.now();
+                if (Object.keys(differ).length > 0 || remaining <= 0)
+                    return differ;
+                await new Promise((resolve) => {
+                    const done = () => {
+                        clearTimeout(timer);
+                        waiters.delete(done);
+                        resolve();
+                    };
+                    const timer = setTimeout(done, Math.min(poll, remaining));
+                    timer.unref?.();
+                    waiters.add(done);
+                });
+            }
+        },
+        async bump(names) {
+            const unique = [...new Set(names)];
+            if (unique.length === 0)
+                return;
+            await store.bump(unique);
+            wakeAll();
+            if (store.notify)
+                await store.notify();
+        },
+    };
+}
+/**
+ * Versions in Postgres, from the client the app already has:
+ *
+ *     installVersionSource(postgresVersions(sql))
+ *
+ * `sqlVersions` with Postgres's placeholders, and - when the client can
+ * LISTEN, as postgres.js can - a change on one instance wakes the waiting asks
+ * on every other at once, rather than on their next read of the table.
+ * Without it (`Bun.sql`), the table is read once a second while an ask waits.
+ *
+ *     CREATE TABLE rsc_versions (name TEXT PRIMARY KEY, version BIGINT NOT NULL)
+ */
+export function postgresVersions(sql, options = {}) {
+    const channel = options.channel ?? "rsc_versions";
+    const listen = sql.listen?.bind(sql);
+    const notify = sql.notify?.bind(sql);
+    return sqlVersions({
+        query: async (text, params) => await sql.unsafe(text, params),
+        placeholder: (n) => "$" + n,
+        table: options.table,
+        poll: options.poll,
+        listen: listen ? (wake) => listen(channel, wake) : undefined,
+        notify: listen && notify ? () => notify(channel, "") : undefined,
+    });
+}
+const SOURCE = Symbol.for("rsc-kit.version-source");
+const BACKEND_SOURCE = Symbol.for("rsc-kit.backend-version-source");
+const LOCAL_SOURCE = Symbol.for("rsc-kit.local-version-source");
+const globals = globalThis;
+/**
+ * Install where versions are read from - a table, Redis, any store - for this
+ * process; `null` takes it out again.
+ *
+ * The app's choice wins over the backend's: with a Go or Laravel backend that
+ * writes its versions to a store this process can read too, reading it here
+ * means watching costs the backend nothing.
+ */
+export function installVersionSource(source) {
+    globals[SOURCE] = source;
+}
+/** The engine's, when a backend is installed: its versions, read through it. Not for apps. */
+export function installBackendVersionSource(source) {
+    globals[BACKEND_SOURCE] = source;
+}
+/** The source in use: the app's, else the backend's, else this process's own. */
+export function versionSource() {
+    return (globals[SOURCE] ??
+        globals[BACKEND_SOURCE] ??
+        (globals[LOCAL_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.
+/** Thrown when a production server has no key to sign names with. */
+export class MissingSigningSecret extends Error {
+    constructor() {
+        super("refreshOn needs a signing secret in production, the same on every instance: set RSC_SIGNING_SECRET " +
+            "to a long random string. Without one, each instance would sign with its own random key, and a tab " +
+            "served by one would be refused by the next.");
+        this.name = "MissingSigningSecret";
+    }
+}
+// On the global rather than in this module: an app imports this file through
+// its own copy of the package, and a key configured there must be the key the
+// engine's copy signs and verifies with.
+const KEY = Symbol.for("rsc-kit.signing-key");
+function keying() {
+    return (globals[KEY] ??= {
+        secret: null,
+        keyed: null,
+        signatures: new Map(),
+    });
+}
+const env = (name) => globalThis
+    .process?.env?.[name] || undefined;
+const production = () => env("NODE_ENV") === "production";
+/**
+ * The secret names are signed with, when it does not come from the
+ * environment. Normally it does: `RSC_SIGNING_SECRET`, the same on every
+ * instance, or a tab served by one is refused by another.
+ *
+ * Its own secret, not the backend's host-call secret: that one authorises
+ * calls between the renderer and a backend, and an app with no backend has
+ * no reason to have it. Two jobs, two keys - one leaking does not hand out
+ * the other.
+ */
+export function configureChanged(options) {
+    const state = keying();
+    state.secret = options.secret ?? null;
+    state.keyed = null;
+    state.signatures.clear();
+}
+/** The secret in use: configured, or from the environment; null when there is none. */
+function secretInUse() {
+    const state = keying();
+    return state.secret ?? env("RSC_SIGNING_SECRET") ?? null;
+}
+/**
+ * Refuse, in production, to sign with a key nobody else has.
+ *
+ * A random key is right for one process - a dev server - and silently wrong
+ * for two: every tab served by one instance is refused by the next, and never
+ * refreshes. The server calls this on its first request when the app uses
+ * refreshOn, so the misconfiguration is an error at once rather than a page
+ * that quietly stops updating.
+ */
+export function assertSigningSecret() {
+    if (!secretInUse() && production())
+        throw new MissingSigningSecret();
+}
+let warnedRandom = false;
+async function key() {
+    const state = keying();
+    return (state.keyed ??= (async () => {
+        const secret = secretInUse();
+        let raw;
+        if (secret)
+            raw = new TextEncoder().encode(secret);
+        else if (production())
+            throw new MissingSigningSecret();
+        else {
+            if (!warnedRandom) {
+                warnedRandom = true;
+                console.warn("[rsc-kit] refreshOn is signing with a random key, which is fine for one dev server. " +
+                    "Set RSC_SIGNING_SECRET before running more than one instance.");
+            }
+            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) {
+    const { signatures } = keying();
+    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;
+    delete globals[LOCAL_SOURCE];
+}
+/** The url a tab opens to watch, for the client. */
+export const CHANGES_PATH = HEADER.changesPath;
+//# sourceMappingURL=changed.js.map