@rsc-kit/core 0.27.0 → 0.28.0

package/dist/changed.js

@@ -26,14 +26,52 @@
  * 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 { frame, keepaliveMs } from "./events.js";
 import { HEADER } from "./headers.js";
+import { listenToBroadcast } from "./broadcast.js";
+export { listenToBroadcast } from "./broadcast.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() {
+/**
+ * The version a name moves to: the larger of one past where it was and the
+ * current time in milliseconds.
+ *
+ * A counter would do for "it moved", but a counter repeats once its row is
+ * gone - deleted to keep the store small, a name starts again from 0 and
+ * climbs back to a value some tab is still holding, and that tab misses the
+ * change. A time never comes round again, so a name may be forgotten at any
+ * moment: a tab holding the old value sees a different one, and at worst
+ * refreshes once for nothing. It is also when the name last moved, which is
+ * all cleanup needs. Every store bumps with it; one that writes `+ 1` still
+ * works, it is just not safe to prune.
+ */
+export function nextVersion(current = 0) {
+    return Math.max(current + 1, Date.now());
+}
+/** The safety-net read of a store that listens: longer than any ask waits, so once per ask. */
+export const LISTENING_POLL_MS = 30_000;
+/** How long a name nobody changes is kept, by the stores that forget on their own. */
+export const VERSIONS_KEPT_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * Versions kept in this process: the source without a backend, and the one
+ * tests use. A name not changed in `forgetAfter` ms (30 days) is forgotten,
+ * swept at most once an hour, so a process up for months does not hold every
+ * name it ever saw.
+ */
+export function memoryVersions(options = {}) {
+    const forgetAfter = options.forgetAfter ?? VERSIONS_KEPT_MS;
     const versions = new Map();
     const waiters = new Set();
+    let swept = Date.now();
+    const sweep = () => {
+        const now = Date.now();
+        if (now - swept < Math.min(forgetAfter, 60 * 60 * 1000))
+            return;
+        swept = now;
+        for (const [name, version] of versions)
+            if (version < now - forgetAfter)
+                versions.delete(name);
+    };
     const differing = (since) => {
         const out = {};
         for (const [name, held] of Object.entries(since)) {
@@ -62,8 +100,9 @@ export function memoryVersions() {
             return differing(since);
         },
         bump(names) {
+            sweep();
             for (const name of names)
-                versions.set(name, (versions.get(name) ?? 0) + 1);
+                versions.set(name, nextVersion(versions.get(name)));
             for (const wake of [...waiters])
                 wake();
         },
@@ -123,39 +162,88 @@ export function backendVersions(call) {
  * 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.
  */
+/**
+ * One statement that moves every name to nextVersion: an upsert, in the
+ * dialect's own words, and on Postgres the NOTIFY with it. A name is either
+ * inserted at `now` or moved to the larger of one more and `now`.
+ */
+function upsert(dialect, table, mark, names, now, channel) {
+    if (dialect === "postgres") {
+        // $1 is now, the names follow; the channel, if any, comes last.
+        const rows = names.map((_, i) => `(${mark(i + 2)}, ${mark(1)})`).join(", ");
+        const insert = `INSERT INTO ${table} (name, version) VALUES ${rows} ` +
+            `ON CONFLICT (name) DO UPDATE SET version = GREATEST(${table}.version + 1, EXCLUDED.version)`;
+        if (!channel)
+            return [insert, [now, ...names]];
+        // A NOTIFY is delivered when the transaction commits, so a listener is
+        // never woken before the change it is told about can be read.
+        return [
+            `WITH moved AS (${insert} RETURNING 1) SELECT pg_notify(${mark(names.length + 2)}, '') FROM (SELECT count(*) FROM moved) AS done`,
+            [now, ...names, channel],
+        ];
+    }
+    const rows = names.map(() => `(${mark(1)}, ${mark(1)})`).join(", ");
+    const params = names.flatMap((name) => [name, now]);
+    return dialect === "mysql"
+        ? [
+            `INSERT INTO ${table} (name, version) VALUES ${rows} ON DUPLICATE KEY UPDATE version = GREATEST(version + 1, VALUES(version))`,
+            params,
+        ]
+        : [
+            `INSERT INTO ${table} (name, version) VALUES ${rows} ON CONFLICT (name) DO UPDATE SET version = MAX(version + 1, excluded.version)`,
+            params,
+        ];
+}
 export function sqlVersions(options) {
     const { query } = options;
     const table = options.table ?? "rsc_versions";
     const mark = options.placeholder ?? (() => "?");
-    return createVersions({
+    const source = 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)`;
+            if (options.dialect) {
+                await query(...upsert(options.dialect, table, mark, names, Date.now(), options.channel));
+                return;
+            }
+            // nextVersion, in SQL every dialect has: CASE rather than GREATEST,
+            // which SQLite spells MAX. The time is this process's, passed in, so
+            // the database's clock never has to agree with it.
+            const update = `UPDATE ${table} SET version = CASE WHEN version + 1 > ${mark(1)} THEN version + 1 ELSE ${mark(2)} END ` +
+                `WHERE name = ${mark(3)}`;
+            const insert = `INSERT INTO ${table} (name, version) VALUES (${mark(1)}, ${mark(2)})`;
             for (const name of names) {
+                const now = Date.now();
                 // 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]);
+                    await query(update, [now, now, name]);
                     continue;
                 }
                 try {
-                    await query(insert, [name]);
+                    await query(insert, [name, now]);
                 }
                 catch {
                     // Another instance inserted it first: bump that one.
-                    await query(update, [name]);
+                    await query(update, [now, now, name]);
                 }
             }
         },
         listen: options.listen,
         notify: options.notify,
     }, { poll: options.poll });
+    return {
+        ...source,
+        async prune(olderThan = VERSIONS_KEPT_MS) {
+            await query(`DELETE FROM ${table} WHERE version < ${mark(1)}`, [
+                Date.now() - olderThan,
+            ]);
+        },
+    };
 }
 /**
  * A version source over any store: SQL through any driver or ORM - Drizzle,
@@ -169,14 +257,22 @@ export function sqlVersions(options) {
  * once whatever the store.
  */
 export function createVersions(store, options = {}) {
-    const poll = options.poll ?? 1_000;
+    // A store that listens is woken the moment a version moves, so reading the
+    // table on a timer is only a safety net - for a listening connection that
+    // dropped without a word. Once an ask is enough: about every five seconds
+    // per server, where one that cannot listen reads every second.
+    const poll = options.poll ?? (store.listen ? LISTENING_POLL_MS : 1_000);
     const waiters = new Set();
     const wakeAll = () => {
         for (const wake of [...waiters])
             wake();
     };
+    // A store that can listen wakes the renderer the way anything else does -
+    // through wakeOn, which starts it with the first watching tab and never in
+    // a build. A wake also ends an ask this store is holding.
     if (store.listen)
-        void Promise.resolve(store.listen(wakeAll)).catch(() => { });
+        wakeOn(store.listen);
+    wakers().sleepers.add(wakeAll);
     const read = async (names) => {
         if (names.length === 0)
             return {};
@@ -185,6 +281,10 @@ export function createVersions(store, options = {}) {
     };
     return {
         async changed(since, wait) {
+            // Only a server with a tab watching asks with a wait - never a build -
+            // so this is a safe moment to start listening, as is the first tab.
+            if (wait > 0)
+                startWakers();
             const names = Object.keys(since);
             const deadline = Date.now() + Math.max(0, wait);
             for (;;) {
@@ -225,23 +325,26 @@ export function createVersions(store, options = {}) {
  *     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.
+ * LISTEN, as postgres.js and `Bun.sql` (Bun 1.4+) 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, 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);
+    // One statement per change: the upsert of every name, and the NOTIFY that
+    // wakes every listening server - this one included - when it commits.
     return sqlVersions({
         query: async (text, params) => await sql.unsafe(text, params),
         placeholder: (n) => "$" + n,
+        dialect: "postgres",
+        channel,
         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");
@@ -265,9 +368,28 @@ export function installBackendVersionSource(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()));
+    const chosen = globals[SOURCE] ??
+        globals[BACKEND_SOURCE];
+    if (chosen)
+        return chosen;
+    let local = globals[LOCAL_SOURCE];
+    if (!local) {
+        local = globals[LOCAL_SOURCE] = memoryVersions();
+        // The fallback works in development and in tests, which are one process,
+        // and fails silently in production with two: a change on one instance
+        // never reaches the tabs on another. Said once, at the first use. An app
+        // that really is one instance installs memoryVersions() itself, which is
+        // a choice rather than a fallback, and is not warned.
+        if (production()) {
+            console.warn("[rsc-kit] refreshOn versions are kept in this process only: a change made on another " +
+                "instance, or in a worker, will not reach the tabs this one serves. Install a store every " +
+                "process shares with installVersionSource() in instrumentation.ts - sqlVersions for MySQL " +
+                "or SQLite, postgresVersions for Postgres, createVersions for anything else: " +
+                "https://docs.rsc-kit.dev/guides/sections#where-the-versions-live. For a deploy that is one " +
+                "instance, installVersionSource(memoryVersions()) says so.");
+        }
+    }
+    return local;
 }
 /**
  * Say these names changed, so every open tab showing them refreshes.
@@ -427,6 +549,26 @@ function observe(name, version) {
         if (stream.names.has(name))
             stream.send(name, version);
 }
+/**
+ * A stream gone: and with it every name no other stream holds, which this
+ * process has no reason to remember. Kept, the latest version of every name
+ * any tab ever watched piled up for as long as the server ran.
+ */
+function close(stream) {
+    if (!streams.delete(stream))
+        return;
+    for (const name of stream.names) {
+        let held = false;
+        for (const other of streams) {
+            if (other.names.has(name)) {
+                held = true;
+                break;
+            }
+        }
+        if (!held)
+            known.delete(name);
+    }
+}
 /** Mapped to this process's set of streams: what to ask about, relative to what is known. */
 function sinceAll() {
     const since = {};
@@ -435,11 +577,85 @@ function sinceAll() {
             since[name] = known.get(name) ?? 0;
     return since;
 }
+// ── Waking ───────────────────────────────────────────────────────────────────
+//
+// A backend that cannot hold a question open - PHP - is asked again on an
+// interval. Something that can say "a version moved" the moment it does -
+// a broadcast, a Redis channel - makes that interval a safety net: the
+// renderer asks the moment it is woken, and otherwise rarely.
+const WAKERS = Symbol.for("rsc-kit.wakers");
+function wakers() {
+    return (globals[WAKERS] ??= {
+        listens: [],
+        started: false,
+        pending: false,
+        sleepers: new Set(),
+    });
+}
+/**
+ * Wake the renderer when a version may have moved, so it asks then rather
+ * than on its next interval.
+ *
+ *     wakeOn(listenToBroadcast({ url, key }))           // a broadcast server
+ *     wakeOn((wake) => subscriber.subscribe('rsc', wake)) // a Redis channel
+ *
+ * `listen` is given a function to call - it carries no names and no data;
+ * the renderer asks wherever the versions live, as always. It is started
+ * when the first tab starts watching, never in a build. With one installed,
+ * a backend that answers at once is asked again every 30 seconds as a safety
+ * net instead of every two.
+ */
+export function wakeOn(listen) {
+    const state = wakers();
+    state.listens.push(listen);
+    if (state.started)
+        start(listen);
+}
+/**
+ * Start one listener; one that fails - a database not up yet - is tried
+ * again, backing off to thirty seconds. Until it is up the timer stands in.
+ */
+function start(listen, failures = 0) {
+    void Promise.resolve()
+        .then(() => listen(signal))
+        .catch((error) => {
+        if (failures === 0) {
+            console.warn("[rsc-kit] a wakeOn listener failed to start, trying again: " +
+                (error instanceof Error ? error.message : String(error)));
+        }
+        const retry = setTimeout(() => start(listen, failures + 1), Math.min(30_000, 1000 * 2 ** failures));
+        retry.unref?.();
+    });
+}
+/** Something said a version may have moved: ask now, and end any ask a store is holding. */
+function signal() {
+    const state = wakers();
+    state.pending = true;
+    wake?.();
+    for (const sleeper of [...state.sleepers])
+        sleeper();
+}
+function startWakers() {
+    const state = wakers();
+    if (state.started)
+        return;
+    state.started = true;
+    // Set in the environment, not guessed: a broadcast server to listen to.
+    const url = env("RSC_BROADCAST_URL");
+    const key = env("RSC_BROADCAST_KEY");
+    if (url && key)
+        state.listens.push(listenToBroadcast({ url, key }));
+    for (const listen of state.listens)
+        start(listen);
+}
 async function loop() {
     running = true;
+    startWakers();
     try {
         while (streams.size > 0) {
             const started = Date.now();
+            const state = wakers();
+            state.pending = false;
             try {
                 const moved = await versionSource().changed(sinceAll(), CHANGES_WAIT_MS);
                 for (const [name, version] of Object.entries(moved))
@@ -454,8 +670,11 @@ async function loop() {
                 }
             }
             // 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);
+            // asked again after it - or, with something to wake it, only as a
+            // safety net. A stream opening, or a wake, ends the wait early; a wake
+            // that came during the ask is answered at once.
+            const interval = state.listens.length > 0 ? LISTENING_POLL_MS : CHANGES_INTERVAL_MS;
+            const remaining = state.pending ? 0 : interval - (Date.now() - started);
             if (remaining > 0 && streams.size > 0) {
                 await new Promise((resolve) => {
                     const timer = setTimeout(resolve, remaining);
@@ -537,7 +756,7 @@ export async function changes(request) {
                 }
             };
             write("retry: 2000\n\n");
-            const keepalive = setInterval(() => write(": keepalive\n\n"), KEEPALIVE_MS);
+            const keepalive = setInterval(() => write(": keepalive\n\n"), keepaliveMs());
             keepalive.unref?.();
             const me = {
                 names: new Set(Object.keys(since)),
@@ -547,7 +766,7 @@ export async function changes(request) {
             streams.add(me);
             const end = () => {
                 clearInterval(keepalive);
-                streams.delete(me);
+                close(me);
                 try {
                     sink.close();
                 }
@@ -582,19 +801,26 @@ export async function changes(request) {
         },
         cancel() {
             if (stream)
-                streams.delete(stream);
+                close(stream);
         },
     });
     return new Response(body, {
         headers: {
             "Content-Type": "text/event-stream; charset=utf-8",
-            "Cache-Control": "no-store",
+            // no-transform: a proxy or CDN in front must not compress or buffer
+            // it either - Cloudflare compresses text unless told not to.
+            "Cache-Control": "no-store, no-transform",
             "X-Accel-Buffering": "no",
         },
     });
 }
 /** For tests: forget every stream and version this process has seen. */
+/** For tests: how many names this process remembers for its open streams. */
+export function rememberedNames() {
+    return known.size;
+}
 export function resetChanges() {
+    delete globals[WAKERS];
     streams.clear();
     known.clear();
     warned = false;