@rsc-kit/core 0.26.0 → 0.27.1

package/dist/changed.d.ts

@@ -64,9 +64,137 @@ type HostFn = (name: string, ...args: unknown[]) => Promise<unknown>;
  * on it: one instance, versions bumped by `changed()` here.
  */
 export declare function backendVersions(call: HostFn): VersionSource;
-/** Install where versions are read from; `null` restores this process's own. */
+/** 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 {
+    /**
+     * Your driver, as a function of SQL text and parameters:
+     *
+     *     query: (text, params) => sql.unsafe(text, params)            // postgres.js, Bun.sql
+     *     query: async (text, params) => (await pool.query(text, params)).rows   // node-postgres
+     */
+    query: SqlQuery;
+    /** The table: `CREATE TABLE rsc_versions (name TEXT PRIMARY KEY, version BIGINT NOT NULL)`. */
+    table?: string;
+    /** How the n-th parameter is written (1-based). Default `?`; Postgres is `(n) => '$' + n`. */
+    placeholder?: (n: number) => string;
+    /**
+     * Called once with a function that wakes every waiting ask, for a database
+     * that can say the moment a version moved - Postgres's LISTEN:
+     *
+     *     listen: (wake) => sql.listen('rsc_versions', wake)
+     *
+     * Without it, a waiting ask reads the table every `poll` ms.
+     */
+    listen?: (wake: () => void) => 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. */
+    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;
+/**
+ * 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.
+ * `createVersions` does the rest - comparing, waiting, waking.
+ *
+ *     // Drizzle
+ *     read: async (names) => Object.fromEntries(
+ *       (await db.select().from(rscVersions).where(inArray(rscVersions.name, names)))
+ *         .map((r) => [r.name, Number(r.version)])),
+ *     bump: async (names) => { for (const name of names) await db.insert(rscVersions)
+ *       .values({ name, version: 1 })
+ *       .onConflictDoUpdate({ target: rscVersions.name, set: { version: sql`${rscVersions.version} + 1` } }) },
+ *
+ *     // Redis
+ *     read: async (names) => Object.fromEntries((await redis.mget(names.map(k)))
+ *       .map((v, i) => [names[i], Number(v ?? 0)])),
+ *     bump: async (names) => { await Promise.all(names.map((n) => redis.incr(k(n)))) },
+ */
+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. */
+    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.
+     */
+    listen?(wake: () => void): unknown;
+    /** Run after a bump, to tell the other instances listening: Postgres NOTIFY, Redis PUBLISH. */
+    notify?(): unknown;
+}
+/**
+ * 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 declare function createVersions(store: VersionStore, options?: {
+    poll?: number;
+}): VersionSource;
+/** 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;
+    notify?(channel: string, payload: string): unknown;
+}
+/**
+ * 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 declare function postgresVersions(sql: PostgresClient, options?: {
+    table?: string;
+    channel?: string;
+    poll?: number;
+}): VersionSource;
+/**
+ * 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 declare function installVersionSource(source: VersionSource | null): void;
-/** The source in use: the backend's when a host is installed, this process's otherwise. */
+/** 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. */
 export declare function versionSource(): VersionSource;
 /**
  * Say these names changed, so every open tab showing them refreshes.
@@ -81,14 +209,33 @@ export declare function versionSource(): VersionSource;
  * its, and so is the call: `rsckit.Changed`, `Rsc::changed`.
  */
 export declare function changed(...names: string[]): Promise<void>;
+/** Thrown when a production server has no key to sign names with. */
+export declare class MissingSigningSecret extends Error {
+    constructor();
+}
 /**
- * The key names are signed with. Set from `RSC_HOST_CALL_SECRET` when it is
- * read; otherwise random, which is right for one process and wrong for two -
- * a tab served by one instance presents its names to another and is refused.
+ * 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 declare function configureChanged(options: {
     secret?: string | null;
 }): void;
+/**
+ * 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 declare function assertSigningSecret(): void;
 /** A name's signature: the first 16 bytes of an HMAC, base64url, which is what rides in a url. */
 export declare function sign(name: string): Promise<string>;
 /** What a page hands the client for one name: its version at render, and its signature. */

package/dist/changed.js

@@ -26,7 +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.
  */
-import { KEEPALIVE_MS, frame } from "./events.js";
+import { frame, keepaliveMs } from "./events.js";
 import { HEADER } from "./headers.js";
 /** The reserved name a backend answers name versions on. */
 export const CHANGED_FUNCTION = "__rsc.changed";
@@ -107,15 +107,199 @@ export function backendVersions(call) {
         },
     };
 }
+/**
+ * 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();
+    };
+    // 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;
+        });
+    };
+    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) {
+            if (wait > 0)
+                listen();
+            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; `null` restores this process's own. */
+/**
+ * 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 source in use: the backend's when a host is installed, this process's otherwise. */
+/** 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] ??= 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.
@@ -139,34 +323,87 @@ export async function changed(...names) {
 // 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.
-let secret = null;
-let keyed = null;
-const signatures = new Map();
+/** 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 key names are signed with. Set from `RSC_HOST_CALL_SECRET` when it is
- * read; otherwise random, which is right for one process and wrong for two -
- * a tab served by one instance presents its names to another and is refused.
+ * 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) {
-    secret = options.secret ?? null;
-    keyed = null;
-    signatures.clear();
+    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() {
-    return (keyed ??= (async () => {
+    const state = keying();
+    return (state.keyed ??= (async () => {
+        const secret = secretInUse();
         let raw;
-        if (!secret && typeof process !== "undefined") {
-            secret = process.env?.RSC_HOST_CALL_SECRET ?? null;
-        }
         if (secret)
             raw = new TextEncoder().encode(secret);
-        else
+        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 () => {
@@ -332,7 +569,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)),
@@ -383,7 +620,9 @@ export async function changes(request) {
     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",
         },
     });
@@ -393,6 +632,7 @@ 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;