@rsc-kit/core 0.28.0 → 0.29.0

package/dist/changed.d.ts

@@ -123,7 +123,7 @@ 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:
      *
@@ -180,8 +180,12 @@ export interface VersionStore {
      * 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;
 }
@@ -202,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;
 }
 /**
@@ -223,7 +227,25 @@ export declare function postgresVersions(sql: PostgresClient, options?: {
     table?: string;
     channel?: string;
     poll?: number;
+    /**
+     * 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.
@@ -232,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. */
@@ -298,7 +320,12 @@ export declare const CHANGES_WAIT_MS = 5000;
  * a backend that answers at once is asked again every 30 seconds as a safety
  * net instead of every two.
  */
-export declare function wakeOn(listen: (wake: () => void) => unknown): void;
+/** 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], …]`.
  *
@@ -314,3 +341,9 @@ 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";
+/**
+ * The changes endpoint: a tab's stream here, or - with a hub - in the hub,
+ * where every tab's is. The hub itself answers what isolates forward to it:
+ * a stream to hold, or a poke to ask now.
+ */
+export declare function serveChanges(request: Request): Promise<Response>;

package/dist/changed.js

@@ -261,7 +261,8 @@ export function createVersions(store, options = {}) {
     // 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);
+    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])
@@ -270,8 +271,15 @@ export function createVersions(store, options = {}) {
     // 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)
-        wakeOn(store.listen);
+    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)
@@ -302,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);
                 });
@@ -334,7 +342,8 @@ export function createVersions(store, options = {}) {
  */
 export function postgresVersions(sql, options = {}) {
     const channel = options.channel ?? "rsc_versions";
-    const listen = sql.listen?.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({
@@ -344,9 +353,38 @@ export function postgresVersions(sql, options = {}) {
         channel,
         table: options.table,
         poll: options.poll,
-        listen: listen ? (wake) => listen(channel, wake) : 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");
@@ -368,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)
@@ -385,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.");
         }
     }
@@ -405,6 +448,9 @@ export function versionSource() {
  */
 export async function changed(...names) {
     await versionSource().bump(names);
+    // On Workers with a hub, the tabs are held by the hub, not this isolate:
+    // tell it, so they hear now rather than at the hub's next read.
+    await pokeHub();
 }
 // ── Tokens ───────────────────────────────────────────────────────────────────
 //
@@ -592,19 +638,6 @@ function wakers() {
         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);
@@ -616,8 +649,20 @@ export function wakeOn(listen) {
  * 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))
+        .then(() => listen(signal, health))
         .catch((error) => {
         if (failures === 0) {
             console.warn("[rsc-kit] a wakeOn listener failed to start, trying again: " +
@@ -820,6 +865,7 @@ export function rememberedNames() {
     return known.size;
 }
 export function resetChanges() {
+    warnedHub = false;
     delete globals[WAKERS];
     streams.clear();
     known.clear();
@@ -828,4 +874,115 @@ export function resetChanges() {
 }
 /** The url a tab opens to watch, for the client. */
 export const CHANGES_PATH = HEADER.changesPath;
+// ── The hub ──────────────────────────────────────────────────────────────────
+//
+// On Workers each isolate watches for the tabs it happens to hold, which is
+// often one: an ask per tab per interval, a listener per isolate. A Durable
+// Object is one place every isolate can reach. With RSC_CHANGES_HUB naming
+// its binding, every tab's stream is forwarded to one instance of it, which
+// runs the shared ask above for all of them - one ask an interval for the
+// whole deployment, one listener, and a changed() anywhere wakes it at once.
+//
+// Opt-in, by name: the binding is the app's, declared in its wrangler config,
+// and nothing here guesses that a Durable Object is there to use.
+/** Marks a request the hub sent itself; its value is signed, so a browser cannot. */
+const HUB_HEADER = "x-rsc-changes-hub";
+/** The one instance every isolate's streams go to. */
+const HUB_INSTANCE = "rsc-kit-changes";
+/** What the header's value is the signature of. */
+const HUB_PROOF = "rsc-kit:changes-hub";
+let warnedHub = false;
+/** The hub's stub, when RSC_CHANGES_HUB names a Durable Object binding; null otherwise. */
+async function hubStub(request) {
+    const binding = env("RSC_CHANGES_HUB");
+    if (!binding)
+        return null;
+    let bindings = request?.runtime?.cloudflare?.env;
+    // Nitro's Workers entry keeps the bindings here for code with no request -
+    // changed() from a webhook's handler.
+    bindings ??= globalThis.__env__;
+    if (!bindings) {
+        try {
+            // Computed, so neither the bundler nor tsc looks for a module only the
+            // Workers runtime has.
+            const specifier = "cloudflare:workers";
+            bindings = (await import(/* @vite-ignore */ specifier)).env;
+        }
+        catch {
+            bindings = undefined;
+        }
+    }
+    const namespace = bindings?.[binding];
+    if (!namespace || typeof namespace.idFromName !== "function") {
+        if (!warnedHub) {
+            warnedHub = true;
+            console.warn(`[rsc-kit] RSC_CHANGES_HUB names ${JSON.stringify(binding)}, which is not a Durable Object binding ` +
+                "here: each isolate watches for its own tabs. Declare the binding in wrangler config: " +
+                "https://docs.rsc-kit.dev/guides/live-data#one-hub-on-workers");
+        }
+        return null;
+    }
+    return namespace.get(namespace.idFromName(HUB_INSTANCE));
+}
+/** Whether this request came from an isolate forwarding to the hub. */
+async function fromIsolate(request) {
+    const proof = request.headers.get(HUB_HEADER);
+    return proof !== null && (await verify(HUB_PROOF, proof));
+}
+/** Tell the hub something changed, so the tabs it holds hear at once. */
+async function pokeHub() {
+    let stub;
+    try {
+        stub = await hubStub();
+    }
+    catch {
+        return;
+    }
+    if (!stub)
+        return;
+    try {
+        await stub.fetch(new Request("https://hub" + HEADER.changesPath, {
+            method: "POST",
+            headers: { [HUB_HEADER]: await sign(HUB_PROOF) },
+        }));
+    }
+    catch (error) {
+        // The change is in the store; the hub reads it at its next ask.
+        if (!warnedHub) {
+            warnedHub = true;
+            console.warn("[rsc-kit] telling the changes hub failed; its tabs hear at its next read: " +
+                (error instanceof Error ? error.message : String(error)));
+        }
+    }
+}
+/**
+ * The changes endpoint: a tab's stream here, or - with a hub - in the hub,
+ * where every tab's is. The hub itself answers what isolates forward to it:
+ * a stream to hold, or a poke to ask now.
+ */
+export async function serveChanges(request) {
+    // Forwarded, but not with this key: never forwarded again, which would be
+    // a loop - the hub reaching itself - and never served as if from the hub.
+    if (request.headers.has(HUB_HEADER) && !(await fromIsolate(request))) {
+        return new Response("Not from this deployment's isolates.", { status: 403 });
+    }
+    if (request.headers.has(HUB_HEADER)) {
+        if (request.method === "POST") {
+            signal();
+            return new Response(null, { status: 204 });
+        }
+        return await changes(request);
+    }
+    if (request.method !== "GET")
+        return new Response("Method not allowed.", { status: 405 });
+    const stub = await hubStub(request);
+    if (!stub)
+        return await changes(request);
+    const headers = new Headers(request.headers);
+    headers.set(HUB_HEADER, await sign(HUB_PROOF));
+    const held = await stub.fetch(new Request(request.url, { method: "GET", headers, signal: request.signal }));
+    // A stub's response has immutable headers, and the response is still the
+    // app's to finish - the server adds its own on the way out.
+    return new Response(held.body, held);
+}
 //# sourceMappingURL=changed.js.map