@rsc-kit/core 0.27.1 → 0.28.1

package/dist/broadcast.d.ts

@@ -0,0 +1,22 @@
+/** Where the broadcast server is, and which channel and event mean "a version moved". */
+export interface BroadcastOptions {
+    /** The server: `wss://ws.example.com` or `http://localhost:8080` (http is read as ws). */
+    url: string;
+    /** The app key the server knows this app by (Laravel: REVERB_APP_KEY, or PUSHER_APP_KEY). */
+    key: string;
+    /** Default `rsc-versions`, the channel Laravel's Rsc::changed() broadcasts on. */
+    channel?: string;
+    /** Default `rsc.changed`, the event it broadcasts. */
+    event?: string;
+}
+/**
+ * A `wakeOn` listener for a broadcast server:
+ *
+ *     wakeOn(listenToBroadcast({ url: 'wss://ws.example.com', key: process.env.REVERB_APP_KEY! }))
+ *
+ * or, with no code, `RSC_BROADCAST_URL` and `RSC_BROADCAST_KEY` in the
+ * renderer's environment. Uses the runtime's own WebSocket - Bun, Node 22,
+ * Deno - and reconnects with backoff when the connection drops, waking once
+ * it is back, since anything announced while it was gone was lost.
+ */
+export declare function listenToBroadcast(options: BroadcastOptions): (wake: () => void) => () => void;

package/dist/broadcast.js

@@ -0,0 +1,109 @@
+// Waking on a broadcast: the renderer subscribes to one channel on a
+// broadcast server - one speaking the Pusher protocol, which Laravel's
+// Reverb, Pusher and Soketi all do - and is woken whenever a change is
+// announced on it.
+//
+// The announcement carries nothing: no names, no data. Anyone may subscribe
+// to a public channel, so what goes over it must be safe for anyone to see;
+// "something changed" is. The renderer then asks wherever the versions live
+// - the backend, through __rsc.changed - which answers for its visitor's
+// names alone, as it always has.
+const PING_MS = 60_000;
+/**
+ * A `wakeOn` listener for a broadcast server:
+ *
+ *     wakeOn(listenToBroadcast({ url: 'wss://ws.example.com', key: process.env.REVERB_APP_KEY! }))
+ *
+ * or, with no code, `RSC_BROADCAST_URL` and `RSC_BROADCAST_KEY` in the
+ * renderer's environment. Uses the runtime's own WebSocket - Bun, Node 22,
+ * Deno - and reconnects with backoff when the connection drops, waking once
+ * it is back, since anything announced while it was gone was lost.
+ */
+export function listenToBroadcast(options) {
+    const channel = options.channel ?? "rsc-versions";
+    const event = options.event ?? "rsc.changed";
+    const base = options.url.replace(/^http/, "ws").replace(/\/+$/, "");
+    const url = `${base}/app/${encodeURIComponent(options.key)}?protocol=7&client=rsc-kit&version=1&flash=false`;
+    return (wake) => {
+        let socket = null;
+        let stopped = false;
+        let failures = 0;
+        let retry;
+        let ping;
+        let warned = false;
+        const send = (message) => {
+            try {
+                socket?.send(JSON.stringify(message));
+            }
+            catch {
+                // Closing; the close handler reconnects.
+            }
+        };
+        const connect = () => {
+            if (stopped)
+                return;
+            const WebSocketImpl = globalThis
+                .WebSocket;
+            if (!WebSocketImpl) {
+                console.warn("[rsc-kit] listenToBroadcast needs a runtime with WebSocket (Bun, Node 22+): not listening.");
+                return;
+            }
+            const ws = new WebSocketImpl(url);
+            socket = ws;
+            ws.onmessage = (message) => {
+                let frame;
+                try {
+                    frame = JSON.parse(String(message.data));
+                }
+                catch {
+                    return;
+                }
+                if (frame.event === "pusher:connection_established") {
+                    send({ event: "pusher:subscribe", data: { channel } });
+                }
+                else if (frame.event === "pusher_internal:subscription_succeeded") {
+                    failures = 0;
+                    // Connected again after a drop: whatever was announced meanwhile is
+                    // gone, so ask now.
+                    wake();
+                }
+                else if (frame.event === "pusher:ping") {
+                    send({ event: "pusher:pong", data: {} });
+                }
+                else if (frame.event === "pusher:error") {
+                    if (!warned) {
+                        warned = true;
+                        console.warn("[rsc-kit] the broadcast server refused: " +
+                            JSON.stringify(frame.data));
+                    }
+                }
+                else if (frame.event === event && frame.channel === channel) {
+                    wake();
+                }
+            };
+            ws.onclose = () => {
+                clearInterval(ping);
+                if (socket === ws)
+                    socket = null;
+                if (stopped)
+                    return;
+                retry = setTimeout(connect, Math.min(30_000, 1000 * 2 ** failures++));
+                retry.unref?.();
+            };
+            ws.onerror = () => {
+                // The close that follows reconnects.
+            };
+            // Some proxies drop a connection that only listens.
+            ping = setInterval(() => send({ event: "pusher:ping", data: {} }), PING_MS);
+            ping.unref?.();
+        };
+        connect();
+        return () => {
+            stopped = true;
+            clearTimeout(retry);
+            clearInterval(ping);
+            socket?.close();
+        };
+    };
+}
+//# sourceMappingURL=broadcast.js.map

package/dist/broadcast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"broadcast.js","sourceRoot":"","sources":["../src/broadcast.ts"],"names":[],"mappings":"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","sourcesContent":["// Waking on a broadcast: the renderer subscribes to one channel on a\n// broadcast server - one speaking the Pusher protocol, which Laravel's\n// Reverb, Pusher and Soketi all do - and is woken whenever a change is\n// announced on it.\n//\n// The announcement carries nothing: no names, no data. Anyone may subscribe\n// to a public channel, so what goes over it must be safe for anyone to see;\n// \"something changed\" is. The renderer then asks wherever the versions live\n// - the backend, through __rsc.changed - which answers for its visitor's\n// names alone, as it always has.\n\n/** Where the broadcast server is, and which channel and event mean \"a version moved\". */\nexport interface BroadcastOptions {\n  /** The server: `wss://ws.example.com` or `http://localhost:8080` (http is read as ws). */\n  url: string;\n  /** The app key the server knows this app by (Laravel: REVERB_APP_KEY, or PUSHER_APP_KEY). */\n  key: string;\n  /** Default `rsc-versions`, the channel Laravel's Rsc::changed() broadcasts on. */\n  channel?: string;\n  /** Default `rsc.changed`, the event it broadcasts. */\n  event?: string;\n}\n\nconst PING_MS = 60_000;\n\n/**\n * A `wakeOn` listener for a broadcast server:\n *\n *     wakeOn(listenToBroadcast({ url: 'wss://ws.example.com', key: process.env.REVERB_APP_KEY! }))\n *\n * or, with no code, `RSC_BROADCAST_URL` and `RSC_BROADCAST_KEY` in the\n * renderer's environment. Uses the runtime's own WebSocket - Bun, Node 22,\n * Deno - and reconnects with backoff when the connection drops, waking once\n * it is back, since anything announced while it was gone was lost.\n */\nexport function listenToBroadcast(\n  options: BroadcastOptions,\n): (wake: () => void) => () => void {\n  const channel = options.channel ?? \"rsc-versions\";\n  const event = options.event ?? \"rsc.changed\";\n  const base = options.url.replace(/^http/, \"ws\").replace(/\\/+$/, \"\");\n  const url = `${base}/app/${encodeURIComponent(options.key)}?protocol=7&client=rsc-kit&version=1&flash=false`;\n\n  return (wake) => {\n    let socket: WebSocket | null = null;\n    let stopped = false;\n    let failures = 0;\n    let retry: ReturnType<typeof setTimeout> | undefined;\n    let ping: ReturnType<typeof setInterval> | undefined;\n    let warned = false;\n\n    const send = (message: unknown) => {\n      try {\n        socket?.send(JSON.stringify(message));\n      } catch {\n        // Closing; the close handler reconnects.\n      }\n    };\n\n    const connect = () => {\n      if (stopped) return;\n\n      const WebSocketImpl = (globalThis as { WebSocket?: typeof WebSocket })\n        .WebSocket;\n\n      if (!WebSocketImpl) {\n        console.warn(\n          \"[rsc-kit] listenToBroadcast needs a runtime with WebSocket (Bun, Node 22+): not listening.\",\n        );\n        return;\n      }\n\n      const ws = new WebSocketImpl(url);\n\n      socket = ws;\n\n      ws.onmessage = (message: MessageEvent) => {\n        let frame: { event?: string; channel?: string; data?: unknown };\n\n        try {\n          frame = JSON.parse(String(message.data)) as typeof frame;\n        } catch {\n          return;\n        }\n\n        if (frame.event === \"pusher:connection_established\") {\n          send({ event: \"pusher:subscribe\", data: { channel } });\n        } else if (frame.event === \"pusher_internal:subscription_succeeded\") {\n          failures = 0;\n          // Connected again after a drop: whatever was announced meanwhile is\n          // gone, so ask now.\n          wake();\n        } else if (frame.event === \"pusher:ping\") {\n          send({ event: \"pusher:pong\", data: {} });\n        } else if (frame.event === \"pusher:error\") {\n          if (!warned) {\n            warned = true;\n            console.warn(\n              \"[rsc-kit] the broadcast server refused: \" +\n                JSON.stringify(frame.data),\n            );\n          }\n        } else if (frame.event === event && frame.channel === channel) {\n          wake();\n        }\n      };\n\n      ws.onclose = () => {\n        clearInterval(ping);\n        if (socket === ws) socket = null;\n        if (stopped) return;\n\n        retry = setTimeout(connect, Math.min(30_000, 1000 * 2 ** failures++));\n        (retry as { unref?: () => void }).unref?.();\n      };\n\n      ws.onerror = () => {\n        // The close that follows reconnects.\n      };\n\n      // Some proxies drop a connection that only listens.\n      ping = setInterval(\n        () => send({ event: \"pusher:ping\", data: {} }),\n        PING_MS,\n      );\n      (ping as { unref?: () => void }).unref?.();\n    };\n\n    connect();\n\n    return () => {\n      stopped = true;\n      clearTimeout(retry);\n      clearInterval(ping);\n      socket?.close();\n    };\n  };\n}\n"]}

package/dist/changed.d.ts

@@ -26,6 +26,7 @@
  * answers at once, and the watcher asks again on its interval. The protocol
  * is the same either way, and so is the page.
  */
+export { listenToBroadcast, type BroadcastOptions } from "./broadcast.js";
 /** The reserved name a backend answers name versions on. */
 export declare const CHANGED_FUNCTION = "__rsc.changed";
 /** What `__rsc.changed` is asked. */
@@ -52,8 +53,33 @@ export interface VersionSource {
     /** 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;
+/**
+ * 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 declare function nextVersion(current?: number): number;
+/** The safety-net read of a store that listens: longer than any ask waits, so once per ask. */
+export declare const LISTENING_POLL_MS = 30000;
+/** How long a name nobody changes is kept, by the stores that forget on their own. */
+export declare const VERSIONS_KEPT_MS: number;
+/**
+ * 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 declare function memoryVersions(options?: {
+    forgetAfter?: number;
+}): VersionSource;
 type HostFn = (name: string, ...args: unknown[]) => Promise<unknown>;
 /**
  * Versions kept by the backend, read through `__rsc.changed`.
@@ -67,6 +93,17 @@ export declare function backendVersions(call: HostFn): VersionSource;
 /** Runs one statement with positional parameters and resolves to its rows. */
 export type SqlQuery = (text: string, params: unknown[]) => Promise<readonly Record<string, unknown>[]>;
 export interface SqlVersionsOptions {
+    /**
+     * Which database, so a change is one statement - an upsert of every name
+     * it moves - rather than a read and a write per name. Left out, the store
+     * uses only SQL every database has, at the cost of those extra queries.
+     */
+    dialect?: "postgres" | "mysql" | "sqlite";
+    /**
+     * Postgres only: NOTIFY this channel in the same statement as the upsert,
+     * so a listening server wakes - and only once the write commits.
+     */
+    channel?: string;
     /**
      * Your driver, as a function of SQL text and parameters:
      *
@@ -86,33 +123,30 @@ export interface SqlVersionsOptions {
      *
      * Without it, a waiting ask reads the table every `poll` ms.
      */
-    listen?: (wake: () => void) => unknown;
+    listen?: (wake: () => void, health: ListenerHealth) => unknown;
     /**
      * Run after every bump, to tell the other instances - Postgres's NOTIFY:
      *
      *     notify: () => sql.notify('rsc_versions', '')
      */
     notify?: () => unknown;
-    /** How often a waiting ask reads the table. Default 1000ms. */
+    /**
+     * How often a waiting ask reads the table: every second by default, or,
+     * with `listen`, only as a safety net - about once per ask.
+     */
     poll?: number;
 }
-/**
- * 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 declare function sqlVersions(options: SqlVersionsOptions): VersionSource;
+/** A store whose old names can be cleared out: the SQL ones. */
+export interface PrunableVersions extends VersionSource {
+    /**
+     * Delete every name not changed in `olderThan` ms (30 days by default).
+     * Always safe: a version is a time and never comes round again, so a tab
+     * still holding a pruned name sees it differ and refreshes once. Run it
+     * from a scheduled job - a daily one is plenty.
+     */
+    prune(olderThan?: number): Promise<void>;
+}
+export declare function sqlVersions(options: SqlVersionsOptions): PrunableVersions;
 /**
  * Where versions are kept, as the app writes it for its own database: the
  * three things rsc-kit cannot know about your storage, and nothing else.
@@ -134,14 +168,24 @@ export declare function sqlVersions(options: SqlVersionsOptions): VersionSource;
 export interface VersionStore {
     /** The current version of each name asked for. A name it has never seen may be left out: it is 0. */
     read(names: string[]): Promise<Record<string, number>>;
-    /** Move each name's version - by one, or to anything new: watchers compare, they do not count. */
+    /**
+     * Move each name's version to `nextVersion(current)` - one past where it
+     * was, or the current time in ms if that is larger. Watchers only compare,
+     * so any new value works; this one never repeats, which is what makes it
+     * safe to delete a name later. A plain `+ 1` works too, until a row is
+     * deleted.
+     */
     bump(names: string[]): Promise<void>;
     /**
      * Called once with a function that wakes every waiting ask, when the store
      * can say the moment a version moved - Postgres LISTEN, Redis SUBSCRIBE.
      * Without it a waiting ask reads again every `poll` ms.
+     *
+     * Given `health` too: a store that finds it hears nothing - a Postgres
+     * listener behind a pooler in transaction mode - calls `health.deaf(why)`,
+     * and rsc-kit says so and goes back to reading every second.
      */
-    listen?(wake: () => void): unknown;
+    listen?(wake: () => void, health: ListenerHealth): unknown;
     /** Run after a bump, to tell the other instances listening: Postgres NOTIFY, Redis PUBLISH. */
     notify?(): unknown;
 }
@@ -162,8 +206,8 @@ export declare function createVersions(store: VersionStore, options?: {
 /** The parts of a Postgres client `postgresVersions` uses: postgres.js and `Bun.sql` both have them. */
 export interface PostgresClient {
     unsafe(text: string, params?: unknown[]): PromiseLike<readonly Record<string, unknown>[]>;
-    /** postgres.js has it; with it, a waiting ask hears another instance at once. */
-    listen?(channel: string, onNotify: () => void): unknown;
+    /** postgres.js and Bun.sql have it; with it, a waiting ask hears another instance at once. */
+    listen?(channel: string, onNotify: (payload?: string) => void): unknown;
     notify?(channel: string, payload: string): unknown;
 }
 /**
@@ -172,9 +216,10 @@ export interface PostgresClient {
  *     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)
  */
@@ -182,7 +227,25 @@ export declare function postgresVersions(sql: PostgresClient, options?: {
     table?: string;
     channel?: string;
     poll?: number;
-}): VersionSource;
+    /**
+     * A client to listen on, when `sql` goes through a connection pooler in
+     * transaction mode - PgBouncer, or DigitalOcean's, Supabase's or Neon's
+     * pooled connection - which hands the server connection back after each
+     * statement, so a LISTEN on it hears nothing. A direct or session-mode
+     * connection; reads and writes stay on `sql`. One connection per process.
+     */
+    listenWith?: PostgresClient;
+    /**
+     * `false`: do not listen - read every second instead, on purpose. For a
+     * database whose direct connections are too few to spend one per process
+     * on, behind a pooler that cannot listen. No listener, so no probe and no
+     * warning about one. A change made in this process still reaches its own
+     * tabs at once; one made elsewhere within about a second.
+     */
+    listen?: boolean;
+}): PrunableVersions;
+/** How long a listener's probe may take to come back before it counts as deaf. */
+export declare const LISTEN_PROBE_MS = 5000;
 /**
  * Install where versions are read from - a table, Redis, any store - for this
  * process; `null` takes it out again.
@@ -191,7 +254,7 @@ export declare function postgresVersions(sql: PostgresClient, options?: {
  * writes its versions to a store this process can read too, reading it here
  * means watching costs the backend nothing.
  */
-export declare function installVersionSource(source: VersionSource | null): void;
+export declare function installVersionSource(source: VersionSource | (() => VersionSource) | null): void;
 /** The engine's, when a backend is installed: its versions, read through it. Not for apps. */
 export declare function installBackendVersionSource(source: VersionSource | null): void;
 /** The source in use: the app's, else the backend's, else this process's own. */
@@ -244,6 +307,25 @@ export type SignedName = [version: number, signature: string];
 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;
+/**
+ * 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.
+ */
+/** What a listener is told besides how to wake: how to say it hears nothing. */
+export interface ListenerHealth {
+    /** This listener will never wake anything: say why, once, and stop counting on it. */
+    deaf(reason: string): void;
+}
+export declare function wakeOn(listen: (wake: () => void, health: ListenerHealth) => unknown): void;
 /**
  * The stream a tab watches its names on: `GET /_rsc/changes?w=[[name, version, signature], …]`.
  *
@@ -254,7 +336,8 @@ export declare const CHANGES_WAIT_MS = 5000;
  */
 export declare function changes(request: Request): Promise<Response>;
 /** For tests: forget every stream and version this process has seen. */
+/** For tests: how many names this process remembers for its open streams. */
+export declare function rememberedNames(): number;
 export declare function resetChanges(): void;
 /** The url a tab opens to watch, for the client. */
 export declare const CHANGES_PATH: "/_rsc/changes";
-export {};