@protobase/server 0.51.2 → 0.52.0

package/dist/realtime/realtime-app.js

@@ -1,14 +1,33 @@
+import { broadcastHub } from "./broadcast-hub.js";
 import { changeChecker } from "./change-checker.js";
 import { changeHub } from "./change-hub.js";
 import { channelAccess } from "./channel-access.js";
+import { databaseBroadcasts } from "./database-broadcasts.js";
+import { presenceHub } from "./presence-hub.js";
 import { realtimeRoutes } from "./realtime-routes.js";
+import { relayed } from "./relay/realtime-options.js";
+import { relayedHubs } from "./relay/relayed-hubs.js";
 //#region src/realtime/realtime-app.ts
+const hubsOf = (deps, options, report) => {
+	if (relayed(options)) return relayedHubs({
+		db: deps.db,
+		statementTimeoutMs: deps.statementTimeoutMs,
+		report
+	});
+	return {
+		broadcasts: broadcastHub(),
+		presences: presenceHub(),
+		follow: () => () => {}
+	};
+};
 /**
 * `/api/sb/realtime/v1`: the `postgres_changes` of the live resources, each checked under the subscriber's role, claims and
-* the tables' RLS policies before it is sent, and broadcasts and presence between the channels of the process, on a
-* private channel as the policies on `realtime.messages` allow.
+* the tables' RLS policies before it is sent, and broadcasts and presence between the channels on a topic, of this
+* process or, with `processes: 'many'`, of every process serving the app, on a
+* private channel as the policies on `realtime.messages` allow, and the broadcasts the database sends with
+* `realtime.send()`.
 */
-const realtimeApp = ({ deps, feed, upgradeWebSocket, caller, report }) => {
+const realtimeApp = ({ deps, feed, upgradeWebSocket, caller, report, options }) => {
 	const live = deps.registry.entries.filter((entry) => entry.model.live);
 	const check = changeChecker({
 		db: deps.db,
@@ -25,11 +44,28 @@ const realtimeApp = ({ deps, feed, upgradeWebSocket, caller, report }) => {
 		db: deps.db,
 		statementTimeoutMs: deps.statementTimeoutMs
 	});
+	const { broadcasts, presences, follow } = hubsOf(deps, options, report);
+	const database = databaseBroadcasts({
+		db: deps.db,
+		statementTimeoutMs: deps.statementTimeoutMs,
+		broadcasts,
+		report
+	});
 	return realtimeRoutes({
 		upgradeWebSocket,
 		caller,
 		live,
 		hub,
+		broadcasts,
+		presences,
+		database: { follow: () => {
+			const unfollowRelay = follow();
+			const unfollowDatabase = database.follow();
+			return () => {
+				unfollowDatabase();
+				unfollowRelay();
+			};
+		} },
 		access,
 		report
 	});

package/dist/realtime/realtime-routes.js

@@ -1,9 +1,7 @@
 import { HttpProblem } from "../problem.js";
 import { broadcastApi } from "./broadcast-api.js";
-import { broadcastHub } from "./broadcast-hub.js";
 import { bufferedOf } from "./buffered-amount.js";
 import { vsnOf } from "./phoenix-message.js";
-import { presenceHub } from "./presence-hub.js";
 import { realtimeSocket } from "./realtime-socket.js";
 import { Hono } from "hono";
 //#region src/realtime/realtime-routes.ts
@@ -13,15 +11,14 @@ const keyRequest = (apikey, token) => new Request("http://realtime.invalid/", {
 } });
 /**
 * `GET /api/sb/realtime/v1/websocket?apikey=…&vsn=…`: Supabase Realtime's socket, for `postgres_changes` of the live
-* resources, and broadcasts and presence between the sockets of this process (see `realtimeSocket`). A missing or wrong
+* resources, and broadcasts and presence between the channels on a topic (see `realtimeSocket`). A missing or wrong
 * key is refused before the upgrade, with 401. A socket whose raw socket is not one of npm `ws`, such as Bun's own `ws`
 * shim's, is closed at once with 1011, since its unsent bytes cannot be counted (`realtimeLimits.maxUnsentBytes`).
-* `POST /api/sb/realtime/v1/api/broadcast` sends to the same channels without a socket (see `broadcastApi`).
+* `POST /api/sb/realtime/v1/api/broadcast` sends to the same channels without a socket (see `broadcastApi`), and so
+* does the database (see `databaseBroadcasts`).
 */
-const realtimeRoutes = ({ upgradeWebSocket, caller, live, hub, access, report }) => {
+const realtimeRoutes = ({ upgradeWebSocket, caller, live, hub, broadcasts, presences, database, access, report }) => {
 	const app = new Hono();
-	const broadcasts = broadcastHub();
-	const presences = presenceHub();
 	let lastId = 0;
 	const nextId = () => ++lastId;
 	app.route("/api/broadcast", broadcastApi({
@@ -37,12 +34,18 @@ const realtimeRoutes = ({ upgradeWebSocket, caller, live, hub, access, report })
 	}, upgradeWebSocket((c) => {
 		const apikey = c.req.query("apikey");
 		let socket;
+		let unfollow = () => {};
+		const closed = () => {
+			socket?.closed();
+			unfollow();
+		};
 		return {
 			onOpen: (_event, ws) => {
 				if (bufferedOf(ws.raw) === void 0) {
 					report(/* @__PURE__ */ new Error("Not implemented: realtime needs WebSockets of npm ws, which count unsent bytes; on Bun, load npm ws by its path rather than Bun's ws shim, or run on Node"));
 					return ws.close(1011);
 				}
+				unfollow = database.follow();
 				socket = realtimeSocket({
 					vsn: vsnOf(c.req.query("vsn")),
 					send: (frame) => ws.send(frame),
@@ -59,8 +62,8 @@ const realtimeRoutes = ({ upgradeWebSocket, caller, live, hub, access, report })
 				});
 			},
 			onMessage: (event) => socket?.message(event.data),
-			onError: () => socket?.closed(),
-			onClose: () => socket?.closed()
+			onError: closed,
+			onClose: closed
 		};
 	}));
 	return app;

package/dist/realtime/realtime-socket.js

@@ -1,8 +1,8 @@
 import { HttpProblem } from "../problem.js";
+import { fixedWindow, fixedWindows } from "./fixed-window.js";
+import { realtimeLimits } from "./realtime-limits.js";
 import { parseBindings } from "./postgres-changes.js";
 import { decodeBroadcastPush, encodeBroadcast, fitsFrame } from "./broadcast-frame.js";
-import { realtimeLimits } from "./realtime-limits.js";
-import { fixedWindow, fixedWindows } from "./fixed-window.js";
 import { decodeMessage, encodeMessage, reply } from "./phoenix-message.js";
 import { privateGate, publicGate, readRefusalText } from "./channel-gate.js";
 import { randomUUID } from "node:crypto";
@@ -72,14 +72,15 @@ const realtimeSocket = ({ vsn, send, buffered, close, resolve, live, hub, broadc
 		event,
 		payload
 	});
-	const hear = (topic, channel, event, payload) => {
+	const hear = (topic, channel, event, payload, meta) => {
 		if (!channel.gate.hears("broadcast")) return;
-		if (vsn === "2.0.0") return deliver(encodeBroadcast(topic, event, payload));
+		if (vsn === "2.0.0") return deliver(encodeBroadcast(topic, event, payload, meta));
 		if (payload instanceof ArrayBuffer) return;
 		toChannel(topic, channel, "broadcast", {
 			type: "broadcast",
 			event,
-			payload
+			payload,
+			...meta && { meta }
 		});
 	};
 	const leave = (topic) => {
@@ -122,13 +123,15 @@ const realtimeSocket = ({ vsn, send, buffered, close, resolve, live, hub, broadc
 		const refused = await gate.authorize(caller);
 		if (!open) return;
 		if (refused) return push(reply(message, "error", { reason: `Unauthorized: ${readRefusalText(message.topic, refused)}` }));
+		await presences.ready();
+		if (!open) return;
 		const parsed = parseBindings(config.postgres_changes, live, nextId);
 		if (typeof parsed === "string") return push(reply(message, "error", { reason: parsed }));
 		const { topic } = message;
 		const member = {
 			self: broadcast.self === true,
 			private: config.private === true,
-			receive: (event, payload) => hear(topic, channel, event, payload)
+			receive: (event, payload, meta) => hear(topic, channel, event, payload, meta)
 		};
 		const key = typeof presence.key === "string" && presence.key !== "" ? presence.key : randomUUID();
 		const seat = presences.join(topic, {
@@ -188,7 +191,7 @@ const realtimeSocket = ({ vsn, send, buffered, close, resolve, live, hub, broadc
 		const allowed = await channel.gate.mayWrite(channel.caller, "broadcast");
 		if (channels.get(message.topic) !== channel) return;
 		if (!allowed) return push(reply(message, "error", { error: "unauthorized" }));
-		if (!broadcasts.send(message.topic, channel.member, event, payload)) return push(reply(message, "error", { reason: `${tooFast} on this topic` }));
+		if (!await broadcasts.send(message.topic, channel.member, event, payload)) return push(reply(message, "error", { reason: `${tooFast} on this topic` }));
 		if (channel.ack) push(reply(message, "ok", {}));
 	};
 	const updatePresence = async (message, channel) => {

package/dist/realtime/relay/frame-cursor.js

@@ -0,0 +1,38 @@
+//#region src/realtime/relay/frame-cursor.ts
+/** How long an id below the newest one read is asked for again: a frame another process has not committed yet. */
+const gapMs = 2e3;
+/** The most ids asked for again at once. */
+const maxGaps = 1e3;
+/**
+* Where a process is in the frames: every id up to `after` read, except the `gaps`. Processes take ids before they
+* commit, so a frame can commit after one with a higher id: an id skipped is asked for again for `gapMs`, and then given
+* up, as an id a failed insert took and never used.
+*/
+const frameCursor = (after, visible = [], now = () => Date.now()) => {
+	let cursor = after;
+	const gaps = /* @__PURE__ */ new Map();
+	const read = (ids) => {
+		const at = now();
+		const seen = new Set(ids);
+		for (const id of ids) gaps.delete(id);
+		const newest = ids.reduce((max, id) => id > max ? id : max, cursor);
+		for (let id = newest - 1n; id > cursor && gaps.size < maxGaps; id -= 1n) if (!seen.has(id)) gaps.set(id, at);
+		cursor = newest;
+		for (const [id, since] of gaps) if (at - since > gapMs) gaps.delete(id);
+	};
+	if (visible.length > 0) {
+		cursor = visible.reduce((min, id) => id < min ? id : min) - 1n;
+		read(visible);
+	}
+	return {
+		/** What to read next: ids after `after`, and the `gaps`. */
+		next: () => ({
+			after: cursor,
+			gaps: [...gaps.keys()]
+		}),
+		/** Takes the ids just read. */
+		read
+	};
+};
+//#endregion
+export { frameCursor };

package/dist/realtime/relay/presence-replica.js

@@ -0,0 +1,57 @@
+//#region src/realtime/relay/presence-replica.ts
+const topicKey = (topic, isPrivate) => `${isPrivate ? "private" : "public"}:${topic}`;
+/**
+* The other processes' presences by topic and ref, as frames tell them: what `presence_state` adds to this process's
+* own. It holds what they track now, so it is bounded by the presences of the app.
+*/
+const presenceReplica = () => {
+	let topics = /* @__PURE__ */ new Map();
+	const add = (topic, isPrivate, key, meta) => {
+		const name = topicKey(topic, isPrivate);
+		const refs = topics.get(name) ?? /* @__PURE__ */ new Map();
+		if (refs.has(meta.phx_ref)) return false;
+		topics.set(name, refs.set(meta.phx_ref, {
+			key,
+			meta
+		}));
+		return true;
+	};
+	const remove = (topic, isPrivate, ref) => {
+		const name = topicKey(topic, isPrivate);
+		const refs = topics.get(name);
+		if (!refs?.delete(ref)) return false;
+		if (refs.size === 0) topics.delete(name);
+		return true;
+	};
+	const filtered = (state, keep) => {
+		const kept = Object.create(null);
+		for (const [key, { metas }] of Object.entries(state)) {
+			const left = metas.filter((meta) => keep(key, meta));
+			if (left.length > 0) kept[key] = { metas: left };
+		}
+		return Object.keys(kept).length > 0 ? kept : void 0;
+	};
+	return {
+		/** Starts over from the presences a snapshot read. */
+		load: (tracked) => {
+			topics = /* @__PURE__ */ new Map();
+			for (const presence of tracked) add(presence.topic, presence.private, presence.key, presence.meta);
+		},
+		/**
+		* Takes a frame's diff, and returns what it changed: the leaves of presences that were there and the joins of those
+		* that were not, so a frame read twice tells nothing twice; `undefined` when it changed nothing.
+		*/
+		apply: (topic, isPrivate, diff) => {
+			const leaves = filtered(diff.leaves, (_key, meta) => remove(topic, isPrivate, meta.phx_ref));
+			const joins = filtered(diff.joins, (key, meta) => add(topic, isPrivate, key, meta));
+			if (!leaves && !joins) return void 0;
+			return {
+				joins: joins ?? {},
+				leaves: leaves ?? {}
+			};
+		},
+		state: (topic, isPrivate) => [...topics.get(topicKey(topic, isPrivate))?.values() ?? []].map(({ key, meta }) => [key, meta])
+	};
+};
+//#endregion
+export { presenceReplica };

package/dist/realtime/relay/realtime-options.d.ts

@@ -0,0 +1,13 @@
+//#region src/realtime/relay/realtime-options.d.ts
+/** How `/api/sb/realtime/v1` is served (`realtime` in `protobase.config.ts`). */
+export type RealtimeOptions = {
+  /**
+   * `'one'`, the default, when one process serves the app: broadcasts and presence go between its channels in memory.
+   * `'many'` when several processes serve it behind one address: they go between the processes through the
+   * `realtime_relay` schema of the app's database, which `protobase migration` writes.
+   */
+  processes?: 'one' | 'many';
+};
+/** Whether the options share broadcasts and presence between processes. */
+export declare const relayed: (options?: RealtimeOptions) => boolean;
+//#endregion

package/dist/realtime/relay/realtime-options.js

@@ -0,0 +1,9 @@
+//#region src/realtime/relay/realtime-options.ts
+/** Whether the options share broadcasts and presence between processes. */
+const relayed = (options = {}) => {
+	if (options.processes === void 0 || options.processes === "one") return false;
+	if (options.processes === "many") return true;
+	throw new Error(`Invalid realtime.processes "${String(options.processes)}": use "one" or "many"`);
+};
+//#endregion
+export { relayed };

package/dist/realtime/relay/realtime-relay.js

@@ -0,0 +1,104 @@
+import { waitUntil } from "../../functions/wait-until.js";
+import { frameCursor } from "./frame-cursor.js";
+import { admitBroadcasts, pruneFrames, readFrames } from "./relay-frame-sql.js";
+import { beat, presenceSnapshot, restorePresences, retireSelf, retireStale, writePresence } from "./relay-presence-sql.js";
+import { randomUUID } from "node:crypto";
+//#region src/realtime/relay/realtime-relay.ts
+/**
+* Broadcasts and presence between the processes serving an app, through the `realtime_relay` schema: each process adds
+* what its channels, the broadcast API and the database send as frames, and, while one of its sockets is open, reads
+* the others' every `intervalMs`, from a snapshot of their presences taken when the first socket opens. The broadcasts
+* into a topic are counted in the database, every process's together. A process marks itself every `beatMs`, and one
+* that has not for `staleSeconds`, as when it was killed, has its presences removed, with a leave for each. A process
+* that stops, its last socket closed, removes its own; graceful shutdown waits for these writes (`backgroundSettled`).
+*/
+const realtimeRelay = ({ db, statementTimeoutMs, heard, loaded, tracked, report, intervalMs = 100, beatMs = 5e3, staleSeconds = 15, now = () => Date.now() }) => {
+	const self = randomUUID();
+	let followers = 0;
+	let run;
+	let queue = Promise.resolve();
+	const inTurn = (work) => {
+		const next = queue.then(work).catch(report);
+		queue = next;
+		waitUntil(next);
+		return next;
+	};
+	const load = async (current) => {
+		await beat(db, self);
+		const snapshot = await presenceSnapshot(db, statementTimeoutMs, self);
+		if (current.stopped) return;
+		loaded(snapshot.presences);
+		current.cursor = frameCursor(snapshot.newest, snapshot.visible, now);
+		current.beaten = now();
+	};
+	const read = async (current, cursor) => {
+		for (;;) {
+			const { after, gaps } = cursor.next();
+			const batch = await readFrames(db, self, after, gaps);
+			if (current.stopped) return;
+			cursor.read(batch.ids);
+			for (const frame of batch.frames) heard(frame);
+			if (!batch.full) return;
+		}
+	};
+	const keepAlive = async (current) => {
+		if (current.stopped || now() - current.beaten < beatMs) return;
+		current.beaten = now();
+		if (await beat(db, self)) inTurn(() => restorePresences(db, self, tracked()));
+		await retireStale(db, staleSeconds);
+		await pruneFrames(db);
+	};
+	const step = async (current) => {
+		if (!current.cursor) await load(current);
+		if (!current.cursor || current.stopped) return;
+		await read(current, current.cursor);
+		await keepAlive(current);
+	};
+	const tick = async (current) => {
+		if (current.stopped) return;
+		const done = await step(current).then(() => true, (error) => {
+			report(error);
+			return false;
+		});
+		setTimeout(() => void tick(current), done ? intervalMs : beatMs);
+	};
+	const start = () => {
+		const current = {
+			stopped: false,
+			beaten: 0,
+			ready: Promise.resolve()
+		};
+		current.ready = inTurn(() => load(current)).then(() => void setTimeout(() => void tick(current), intervalMs));
+		return current;
+	};
+	const stop = (current) => {
+		current.stopped = true;
+		run = void 0;
+		loaded([]);
+		inTurn(() => retireSelf(db, self));
+	};
+	return {
+		/** The process, as its frames and presences name it. */
+		id: self,
+		/** Reads the other processes' frames from now on, until the returned function is called; once for each call. */
+		follow: () => {
+			followers += 1;
+			if (!run) run = start();
+			let following = true;
+			return () => {
+				if (!following) return;
+				following = false;
+				followers -= 1;
+				if (followers === 0 && run) stop(run);
+			};
+		},
+		/** Resolves once the other processes' presences are read, or their snapshot failed. */
+		ready: () => run?.ready ?? Promise.resolve(),
+		/** Counts and adds the broadcasts as frames, all of them or, over a topic's rate, none: `false` then. */
+		broadcast: (publications) => admitBroadcasts(db, statementTimeoutMs, self, publications),
+		/** Writes a change of this process's presences, after those before it. */
+		changed: (change) => void inTurn(() => writePresence(db, self, change))
+	};
+};
+//#endregion
+export { realtimeRelay };

package/dist/realtime/relay/relay-frame-sql.js

@@ -0,0 +1,82 @@
+import { writeTransaction } from "../../transactions.js";
+import { realtimeLimits } from "../realtime-limits.js";
+import { sql } from "kysely";
+import { Buffer } from "node:buffer";
+//#region src/realtime/relay/relay-frame-sql.ts
+/** Frames read in one query at most. */
+const frameBatch = 1e3;
+var Refused = class extends Error {};
+const bytesOf = (payload) => payload instanceof ArrayBuffer ? Buffer.from(payload).toString("base64") : null;
+const jsonOf = (payload) => payload instanceof ArrayBuffer ? null : JSON.stringify(payload) ?? null;
+/**
+* Counts the broadcasts into each topic's second, every process's together, and adds them as frames, all of them or,
+* when a topic would take more than its broadcasts for this second, none: `false` then.
+*/
+const admitBroadcasts = async (db, statementTimeoutMs, self, publications) => {
+	if (publications.length === 0) return true;
+	const takes = /* @__PURE__ */ new Map();
+	for (const { topic } of publications) takes.set(topic, (takes.get(topic) ?? 0) + 1);
+	return writeTransaction(db, statementTimeoutMs, async (trx) => {
+		const { rows } = await sql`insert into realtime_relay.rates as r (topic, second, count)
+        select topic, extract(epoch from now())::bigint, n from unnest(${[...takes.keys()]}::text[], ${[...takes.values()]}::int[]) as t(topic, n)
+        where n <= ${realtimeLimits.topicBroadcastsPerSecond}
+      on conflict (topic) do update set second = excluded.second, count = case when r.second = excluded.second then r.count + excluded.count else excluded.count end
+        where r.second <> excluded.second or r.count + excluded.count <= ${realtimeLimits.topicBroadcastsPerSecond}
+      returning topic`.execute(trx);
+		if (rows.length < takes.size) throw new Refused();
+		await sql`insert into realtime_relay.frames (process, kind, topic, private, event, payload, bytes, meta)
+      select ${self}::uuid, 'broadcast', topic, private, event, payload::json, decode(bytes, 'base64'), meta::json
+      from unnest(${publications.map((p) => p.topic)}::text[], ${publications.map((p) => p.private)}::boolean[], ${publications.map((p) => p.event)}::text[],
+        ${publications.map((p) => jsonOf(p.payload))}::text[], ${publications.map((p) => bytesOf(p.payload))}::text[], ${publications.map((p) => p.meta ? JSON.stringify(p.meta) : null)}::text[])
+        with ordinality as f(topic, private, event, payload, bytes, meta, position)
+      order by position`.execute(trx);
+		return true;
+	}).catch((error) => {
+		if (error instanceof Refused) return false;
+		throw error;
+	});
+};
+const frameOf = (row) => {
+	const id = BigInt(row.id);
+	if (row.kind === "presence") return {
+		id,
+		kind: "presence",
+		topic: row.topic,
+		private: row.private,
+		diff: row.payload
+	};
+	const payload = row.bytes ? new Uint8Array(row.bytes).buffer : row.payload;
+	return {
+		id,
+		kind: "broadcast",
+		publication: {
+			topic: row.topic,
+			event: row.event,
+			payload,
+			private: row.private,
+			...row.meta && { meta: row.meta }
+		}
+	};
+};
+/**
+* At most `frameBatch` frames after `after` or among `gaps`, in order: the ids of all of them, to move on from, and the
+* other processes' frames, to deliver.
+*/
+const readFrames = async (db, self, after, gaps) => {
+	const { rows } = await sql`select id::text as id, process = ${self}::uuid as own, kind, topic, private, event,
+      case when process <> ${self}::uuid then payload end as payload, case when process <> ${self}::uuid then bytes end as bytes, meta
+    from realtime_relay.frames where id > ${String(after)}::bigint or id = any(${gaps.map(String)}::bigint[])
+    order by id limit ${frameBatch}`.execute(db);
+	return {
+		ids: rows.map((row) => BigInt(row.id)),
+		frames: rows.filter((row) => !row.own).map(frameOf),
+		full: rows.length === frameBatch
+	};
+};
+/** Deletes the frames older than a minute and the counts of seconds before it. */
+const pruneFrames = async (db) => {
+	await sql`delete from realtime_relay.frames where at < now() - interval '1 minute'`.execute(db);
+	await sql`delete from realtime_relay.rates where second < extract(epoch from now())::bigint - 60`.execute(db);
+};
+//#endregion
+export { admitBroadcasts, frameBatch, pruneFrames, readFrames };

package/dist/realtime/relay/relay-presence-sql.js

@@ -0,0 +1,71 @@
+import { sql } from "kysely";
+//#region src/realtime/relay/relay-presence-sql.ts
+const stateOf = (key, meta) => meta ? { [key]: { metas: [meta] } } : {};
+/** The change as the `presence_diff` the other processes' channels hear. */
+const diffOf = (change) => ({
+	joins: stateOf(change.key, change.joined),
+	leaves: stateOf(change.key, change.left)
+});
+const leaveFrame = sql.raw(`json_build_object('joins', '{}'::json, 'leaves', json_build_object(key, json_build_object('metas', json_build_array(meta))))`);
+const joinFrame = sql.raw(`json_build_object('joins', json_build_object(key, json_build_object('metas', json_build_array(meta))), 'leaves', '{}'::json)`);
+/**
+* Keeps the change in `presences` and adds its frame, in one statement: a leave alone is sent only when the presence
+* was there, as a process that was taken for stopped had its presences removed already.
+*/
+const writePresence = async (db, self, change) => {
+	const ref = change.joined?.phx_ref ?? null;
+	await sql`with gone as (delete from realtime_relay.presences where process = ${self}::uuid and ref = ${change.left?.phx_ref ?? null}::text returning ref),
+      added as (insert into realtime_relay.presences (process, ref, topic, private, key, meta)
+        select ${self}::uuid, ${ref}::text, ${change.topic}::text, ${change.private}::boolean, ${change.key}::text, ${JSON.stringify(change.joined ?? null)}::json where ${ref}::text is not null)
+    insert into realtime_relay.frames (process, kind, topic, private, payload)
+    select ${self}::uuid, 'presence', ${change.topic}::text, ${change.private}::boolean, ${JSON.stringify(diffOf(change))}::json
+    where ${ref}::text is not null or exists (select from gone)`.execute(db);
+};
+/** Adds the presences back, with their joins, for a process that was taken for stopped while it was not. */
+const restorePresences = async (db, self, tracked) => {
+	if (tracked.length === 0) return;
+	await sql`with added as (insert into realtime_relay.presences (process, ref, topic, private, key, meta)
+        select ${self}::uuid, ref, topic, private, key, meta::json from unnest(${tracked.map((t) => t.meta.phx_ref)}::text[], ${tracked.map((t) => t.topic)}::text[],
+          ${tracked.map((t) => t.private)}::boolean[], ${tracked.map((t) => t.key)}::text[], ${tracked.map((t) => JSON.stringify(t.meta))}::text[]) as t(ref, topic, private, key, meta)
+        on conflict do nothing returning process, topic, private, key, meta)
+    insert into realtime_relay.frames (process, kind, topic, private, payload) select process, 'presence', topic, private, ${joinFrame} from added`.execute(db);
+};
+/**
+* Marks this process as running, by the database's clock: `true` when its row was not there, as at its start or once
+* another process took it for stopped.
+*/
+const beat = async (db, self) => {
+	const { rows } = await sql`insert into realtime_relay.processes (id) values (${self}::uuid)
+    on conflict (id) do update set seen_at = now() returning (xmax = 0) as inserted`.execute(db);
+	return rows[0].inserted;
+};
+const retire = (db, dead) => sql`with dead as (delete from realtime_relay.processes where ${dead} returning id),
+      gone as (delete from realtime_relay.presences p where p.process in (select id from dead) or not exists (select from realtime_relay.processes q where q.id = p.process)
+        returning process, topic, private, key, meta)
+    insert into realtime_relay.frames (process, kind, topic, private, payload) select process, 'presence', topic, private, ${leaveFrame} from gone`.execute(db);
+/** Removes the processes that have not beaten for `staleSeconds`, and their presences. */
+const retireStale = async (db, staleSeconds) => {
+	await retire(db, sql`seen_at < now() - make_interval(secs => ${staleSeconds})`);
+};
+/** Removes this process and its presences, as it stops. */
+const retireSelf = async (db, self) => {
+	await retire(db, sql`id = ${self}::uuid`);
+};
+/**
+* In one snapshot, the other processes' presences and where their frames stand: the newest id, and every id from the
+* first of the last two seconds on, below which a frame not committed yet is unlikely.
+*/
+const presenceSnapshot = (db, statementTimeoutMs, self) => db.transaction().setIsolationLevel("repeatable read").execute(async (trx) => {
+	await sql`select set_config('statement_timeout', ${String(statementTimeoutMs)}, true)`.execute(trx);
+	const presences = await sql`select topic, private, key, meta from realtime_relay.presences where process <> ${self}::uuid`.execute(trx);
+	const newest = await sql`select coalesce(max(id), 0)::text as id from realtime_relay.frames`.execute(trx);
+	const recent = await sql`select id::text as id from realtime_relay.frames
+      where id >= (select min(id) from realtime_relay.frames where at > now() - interval '2 seconds') order by id`.execute(trx);
+	return {
+		presences: presences.rows,
+		newest: BigInt(newest.rows[0].id),
+		visible: recent.rows.map((row) => BigInt(row.id))
+	};
+});
+//#endregion
+export { beat, diffOf, presenceSnapshot, restorePresences, retireSelf, retireStale, writePresence };

package/dist/realtime/relay/relay-schema-sql.js

@@ -0,0 +1,55 @@
+//#region src/realtime/relay/relay-schema-sql.ts
+/** The schema that carries broadcasts and presence between the processes serving an app. */
+const relaySchema = "realtime_relay";
+/** The tables the relay needs; `json`, not `jsonb`, so a payload reaches the other processes as it was sent. */
+const relayTables = [
+	"frames",
+	"presences",
+	"processes",
+	"rates"
+];
+/**
+* - `frames`: what a process sends, a broadcast or a presence diff, read by the others and pruned after a minute.
+* - `presences`: what each process's channels track, which a process that starts reads.
+* - `processes`: each process's last heartbeat; a process silent too long has its presences removed.
+* - `rates`: each topic's broadcasts in the current second, every process's together.
+*/
+const relaySchemaSql = `create schema if not exists ${relaySchema};
+
+create table if not exists ${relaySchema}.frames (
+  id bigint generated always as identity primary key,
+  process uuid not null,
+  kind text not null check (kind in ('broadcast', 'presence')),
+  topic text not null,
+  private boolean not null,
+  event text,
+  payload json,
+  bytes bytea,
+  meta json,
+  at timestamptz not null default now()
+);
+
+create index if not exists frames_at on ${relaySchema}.frames (at);
+
+create table if not exists ${relaySchema}.processes (
+  id uuid primary key,
+  seen_at timestamptz not null default now()
+);
+
+create table if not exists ${relaySchema}.presences (
+  process uuid not null,
+  ref text not null,
+  topic text not null,
+  private boolean not null,
+  key text not null,
+  meta json not null,
+  primary key (process, ref)
+);
+
+create table if not exists ${relaySchema}.rates (
+  topic text primary key,
+  second bigint not null,
+  count integer not null
+);`;
+//#endregion
+export { relaySchema, relaySchemaSql, relayTables };

package/dist/realtime/relay/relay-schema.d.ts

@@ -0,0 +1,7 @@
+import { Db } from "@protobase/query";
+//#region src/realtime/relay/relay-schema.d.ts
+/** The SQL that adds the `realtime_relay` schema `realtime: { processes: 'many' }` needs; `undefined` when it is there. */
+export declare const realtimeRelayMigration: (db: Db) => Promise<"create schema if not exists realtime_relay;\n\ncreate table if not exists realtime_relay.frames (\n  id bigint generated always as identity primary key,\n  process uuid not null,\n  kind text not null check (kind in ('broadcast', 'presence')),\n  topic text not null,\n  private boolean not null,\n  event text,\n  payload json,\n  bytes bytea,\n  meta json,\n  at timestamptz not null default now()\n);\n\ncreate index if not exists frames_at on realtime_relay.frames (at);\n\ncreate table if not exists realtime_relay.processes (\n  id uuid primary key,\n  seen_at timestamptz not null default now()\n);\n\ncreate table if not exists realtime_relay.presences (\n  process uuid not null,\n  ref text not null,\n  topic text not null,\n  private boolean not null,\n  key text not null,\n  meta json not null,\n  primary key (process, ref)\n);\n\ncreate table if not exists realtime_relay.rates (\n  topic text primary key,\n  second bigint not null,\n  count integer not null\n);" | undefined>;
+/** Refuses to go on while the `realtime_relay` schema is missing; the project's migrations add it. */
+export declare const checkRealtimeRelay: (db: Db) => Promise<void>;
+//#endregion

package/dist/realtime/relay/relay-schema.js

@@ -0,0 +1,18 @@
+import { migrationCommand } from "../../changes/capture-schema.js";
+import { relaySchema, relaySchemaSql, relayTables } from "./relay-schema-sql.js";
+import { sql } from "kysely";
+//#region src/realtime/relay/relay-schema.ts
+const relayCurrent = async (db) => {
+	const names = relayTables.map((table) => `${relaySchema}.${table}`);
+	const { rows } = await sql`select bool_and(to_regclass(name) is not null) as found from unnest(${names}::text[]) as name`.execute(db);
+	return rows[0].found;
+};
+/** The SQL that adds the `realtime_relay` schema `realtime: { processes: 'many' }` needs; `undefined` when it is there. */
+const realtimeRelayMigration = async (db) => await relayCurrent(db) ? void 0 : relaySchemaSql;
+/** Refuses to go on while the `realtime_relay` schema is missing; the project's migrations add it. */
+const checkRealtimeRelay = async (db) => {
+	if (await relayCurrent(db)) return;
+	throw new Error(`The ${relaySchema} schema that realtime.processes "many" needs is missing. Write it as a migration with \`${migrationCommand}\`, apply it with the project's migrations, then start again.`);
+};
+//#endregion
+export { checkRealtimeRelay, realtimeRelayMigration };