@rsc-kit/core 0.27.1 → 0.28.1

package/dist/changed.js

@@ -28,12 +28,50 @@
  */
 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,25 +257,30 @@ 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.
+    let listening = Boolean(store.listen);
+    const poll = () => options.poll ?? (listening ? LISTENING_POLL_MS : 1_000);
     const waiters = new Set();
     const wakeAll = () => {
         for (const wake of [...waiters])
             wake();
     };
-    // Listening opens a connection, and an open connection keeps a process
-    // alive: started here, a store installed in register() - which a build
-    // runs too - held the build open for ever. So it starts with the first
-    // ask that waits, which only a server with a tab watching ever makes.
-    let listening = false;
-    const listen = () => {
-        if (listening || !store.listen)
-            return;
-        listening = true;
-        void Promise.resolve(store.listen(wakeAll)).catch(() => {
-            listening = false;
-        });
-    };
+    // 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) {
+        const listen = store.listen.bind(store);
+        wakeOn((wake, health) => listen(wake, {
+            deaf: (reason) => {
+                listening = false;
+                health.deaf(reason);
+            },
+        }));
+    }
+    wakers().sleepers.add(wakeAll);
     const read = async (names) => {
         if (names.length === 0)
             return {};
@@ -196,8 +289,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)
-                listen();
+                startWakers();
             const names = Object.keys(since);
             const deadline = Date.now() + Math.max(0, wait);
             for (;;) {
@@ -215,7 +310,7 @@ export function createVersions(store, options = {}) {
                         waiters.delete(done);
                         resolve();
                     };
-                    const timer = setTimeout(done, Math.min(poll, remaining));
+                    const timer = setTimeout(done, Math.min(poll(), remaining));
                     timer.unref?.();
                     waiters.add(done);
                 });
@@ -238,25 +333,58 @@ 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);
+    const listener = options.listenWith ?? sql;
+    const listenOn = options.listen === false ? undefined : listener.listen?.bind(listener);
+    // 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,
+        listen: listenOn
+            ? async (wake, health) => {
+                // A probe, sent the way a change is - through `sql` - and listened
+                // for on the listening connection. Behind a transaction-mode pooler
+                // the LISTEN lands on a connection the pooler takes back, sending
+                // still works, and nothing says the listener is deaf: changes from
+                // other instances would wait for the safety-net read. The probe
+                // not arriving is how that is found out - once, as listening starts.
+                const probe = "rsc-kit:probe:" + crypto.randomUUID();
+                let heard = false;
+                await listenOn(channel, (payload) => {
+                    if (payload === probe)
+                        heard = true;
+                    else
+                        wake();
+                });
+                await sql.unsafe("SELECT pg_notify($1, $2)", [channel, probe]);
+                const timer = setTimeout(() => {
+                    if (heard)
+                        return;
+                    health.deaf("listening on Postgres receives no notifications - is the connection going through a pooler " +
+                        "in transaction mode (PgBouncer; DigitalOcean, Supabase or Neon pooled connections)? " +
+                        "Pass a direct or session-mode connection: postgresVersions(sql, { listenWith }). " +
+                        "Reading every second meanwhile.");
+                }, LISTEN_PROBE_MS);
+                timer.unref?.();
+            }
+            : undefined,
     });
 }
+/** How long a listener's probe may take to come back before it counts as deaf. */
+export const LISTEN_PROBE_MS = 5_000;
 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");
@@ -278,6 +406,11 @@ export function installBackendVersionSource(source) {
 }
 /** The source in use: the app's, else the backend's, else this process's own. */
 export function versionSource() {
+    // A factory, made into the store on first use: a store made in register()
+    // would make its database client in the build too, which runs register()
+    // without the database's settings.
+    if (typeof globals[SOURCE] === "function")
+        globals[SOURCE] = globals[SOURCE]();
     const chosen = globals[SOURCE] ??
         globals[BACKEND_SOURCE];
     if (chosen)
@@ -295,7 +428,7 @@ export function versionSource() {
                 "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 " +
+                "https://docs.rsc-kit.dev/guides/live-data#where-the-versions-live. For a deploy that is one " +
                 "instance, installVersionSource(memoryVersions()) says so.");
         }
     }
@@ -459,6 +592,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 = {};
@@ -467,11 +620,84 @@ 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(),
+    });
+}
+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) {
+    const health = {
+        deaf: (reason) => {
+            const state = wakers();
+            const at = state.listens.indexOf(listen);
+            // No longer counted: the renderer goes back to asking on the shorter
+            // interval, as it does with nothing to wake it.
+            if (at === -1)
+                return;
+            state.listens.splice(at, 1);
+            console.warn("[rsc-kit] " + reason);
+        },
+    };
+    void Promise.resolve()
+        .then(() => listen(signal, health))
+        .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))
@@ -486,8 +712,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);
@@ -579,7 +808,7 @@ export async function changes(request) {
             streams.add(me);
             const end = () => {
                 clearInterval(keepalive);
-                streams.delete(me);
+                close(me);
                 try {
                     sink.close();
                 }
@@ -614,7 +843,7 @@ export async function changes(request) {
         },
         cancel() {
             if (stream)
-                streams.delete(stream);
+                close(stream);
         },
     });
     return new Response(body, {
@@ -628,7 +857,12 @@ export async function changes(request) {
     });
 }
 /** 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;