@plitzi/sdk-server 0.37.2 → 0.37.4

package/dist/modules/realtime/handlers.js

@@ -0,0 +1,224 @@
+import onAbort from "../../helpers/onAbort.js";
+import { openEventStream } from "../../core/http/sse.js";
+import { accessRefusal } from "@plitzi/sdk-shared/actions";
+import { randomBytes, randomUUID } from "node:crypto";
+import { PRESENCE_TYPE, channelLimits, matchChannel } from "@plitzi/sdk-shared/realtime";
+//#region src/modules/realtime/handlers.ts
+/** Topics one connection may hold. A page shows a handful; past this it is somebody enumerating. */
+var MAX_TOPICS = 8;
+/** A type a page may send: its own vocabulary, never one of the channel's `$` types but `$presence`. */
+var TYPE = /^[A-Za-z0-9_.:-]{1,64}$/;
+/** How long a disconnected client waits before trying again — ours reconnects itself; this is for anyone else's. */
+var RETRY_MS = 3e3;
+var answer = (res, { status, ...payload }) => {
+	res.setStatus(status);
+	res.setHeader("Content-Type", "application/json; charset=utf-8");
+	res.setHeader("Cache-Control", "no-store");
+	res.send(JSON.stringify(payload));
+};
+var listOf = (query, name) => [...new Set((Object.hasOwn(query, name) ? query[name] : "").split(",").map((item) => item.trim()).filter(Boolean))];
+/** The one of the grants the page sent (`?grants=g1,g2`) that opens `topic` — or none. */
+var grantFor = async (grants, space, topic, offered) => {
+	for (const grant of offered) if (await grants.opens(space, topic, grant)) return grant;
+};
+/**
+* Which of the topics a page asked for (`?topics=a,b`) it may open: each checked against the channels the space
+* declares and against the visitor's access. One that fails is reported, not a reason to refuse the rest; all failing
+* is a `403`.
+*/
+var admit = async (req, resolveChannels, grants) => {
+	const { environment = "main", spaceId, revision } = req.ctx.spaceDeployment ?? {};
+	if (typeof spaceId !== "number") return {
+		ok: false,
+		answer: {
+			status: 404,
+			error: "No space is served here",
+			reason: "not_found"
+		}
+	};
+	const requested = listOf(req.query, "topics");
+	const offered = listOf(req.query, "grants").slice(0, MAX_TOPICS);
+	if (requested.length === 0 || requested.length > MAX_TOPICS) return {
+		ok: false,
+		answer: {
+			status: 422,
+			error: `Name between 1 and ${MAX_TOPICS} topics: ?topics=a,b`,
+			reason: "invalid_input"
+		}
+	};
+	const channels = await resolveChannels(spaceId, environment, revision);
+	const accepted = /* @__PURE__ */ new Map();
+	const granted = /* @__PURE__ */ new Map();
+	const refused = [];
+	const space = {
+		spaceId,
+		environment
+	};
+	for (const topic of requested) {
+		const match = matchChannel(topic, channels);
+		const refusal = match ? accessRefusal(match.declaration.access, req.ctx.user) : "undeclared";
+		const grant = match && !refusal && match.declaration.grant === true ? await grantFor(grants, space, topic, offered) : void 0;
+		if (!match || refusal) refused.push({
+			topic,
+			reason: refusal ?? "undeclared"
+		});
+		else if (match.declaration.grant === true && grant === void 0) refused.push({
+			topic,
+			reason: "ungranted"
+		});
+		else {
+			accepted.set(topic, match.declaration);
+			if (grant !== void 0) granted.set(topic, grant);
+		}
+	}
+	if (accepted.size === 0) return {
+		ok: false,
+		answer: {
+			status: 403,
+			error: "None of these topics may be opened here",
+			reason: "forbidden",
+			refused
+		}
+	};
+	const { user } = req.ctx;
+	return {
+		ok: true,
+		space,
+		...user ? { user: {
+			id: user.id,
+			name: user.username
+		} } : {},
+		accepted,
+		granted,
+		refused
+	};
+};
+/** A new connection for what was admitted, speaking through `send`. */
+var connectionFor = (admission, send, end) => ({
+	id: randomUUID(),
+	token: randomBytes(24).toString("base64url"),
+	space: admission.space,
+	...admission.user ? { user: admission.user } : {},
+	topics: admission.accepted,
+	grants: admission.granted,
+	announced: /* @__PURE__ */ new Set(),
+	sent: /* @__PURE__ */ new Map(),
+	send,
+	end
+});
+/** Whether this connection may send one more message on `topic` this second. */
+var withinRate = (connection, topic, perSecond) => {
+	const second = Math.floor(Date.now() / 1e3);
+	const sent = connection.sent.get(topic);
+	const count = sent?.second === second ? sent.count + 1 : 1;
+	connection.sent.set(topic, {
+		second,
+		count
+	});
+	return count <= perSecond;
+};
+/**
+* A page publishing, whichever way it arrived: only on a topic its connection subscribed to, only on a channel pages
+* may send on, within its size and its rate — and stamped by the server with who sent it and when, whatever the
+* message said.
+*/
+var publishFrom = async (hub, connection, { topic, type, data }) => {
+	const name = typeof topic === "string" ? topic : "";
+	const declaration = connection.topics.get(name);
+	if (!declaration) return {
+		status: 403,
+		error: `This connection did not subscribe to "${name}"`,
+		reason: "not_subscribed"
+	};
+	if (declaration.publish === "server") return {
+		status: 403,
+		error: `Only the server publishes on "${name}"`,
+		reason: "server_only"
+	};
+	const kind = typeof type === "string" ? type : "";
+	const presence = kind === PRESENCE_TYPE && declaration.presence === true;
+	if (!presence && !TYPE.test(kind)) return {
+		status: 422,
+		error: "A message type is 1-64 of A-Z a-z 0-9 _ . : -",
+		reason: "invalid_input"
+	};
+	const limits = channelLimits(declaration);
+	const value = data ?? null;
+	if (Buffer.byteLength(JSON.stringify(value)) > limits.maxMessageBytes) return {
+		status: 413,
+		error: `A message on "${name}" is at most ${limits.maxMessageBytes} bytes`,
+		reason: "too_large"
+	};
+	if (!withinRate(connection, name, limits.messagesPerSecond)) return {
+		status: 429,
+		error: `At most ${limits.messagesPerSecond} messages a second`,
+		reason: "rate_limited"
+	};
+	if (presence) connection.announced.add(name);
+	await hub.publish(connection.space, hub.from(connection, name, kind, value));
+	return { status: 204 };
+};
+/**
+* `GET /_realtime?topics=a,b` (and `&grants=g1,g2` for the topics of a `grant: true` channel) — one Server-Sent Events connection for every topic a page listens to.
+*
+* The first event, `ready`, tells the page its public name (`from`) and the secret its publishes carry. Resolves when
+* the page goes.
+*/
+var handleRealtimeSubscribe = async ({ req, res, raw, signal, hub, resolveChannels, grants }) => {
+	const admission = await admit(req, resolveChannels, grants);
+	if (!admission.ok) {
+		answer(res, admission.answer);
+		return;
+	}
+	let finish = () => void 0;
+	const gone = new Promise((resolve) => {
+		finish = resolve;
+	});
+	const stream = openEventStream(raw, {
+		onAbort: () => finish(),
+		retryMs: RETRY_MS
+	});
+	const connection = connectionFor(admission, stream.send, () => finish());
+	const release = onAbort(signal, () => finish());
+	stream.send("ready", {
+		connection: connection.id,
+		token: connection.token,
+		topics: [...admission.accepted.keys()],
+		refused: admission.refused
+	});
+	await hub.connect(connection);
+	await gone;
+	release();
+	stream.close();
+	await hub.disconnect(connection);
+};
+var parseBody = (body) => {
+	try {
+		const value = body ? JSON.parse(body) : void 0;
+		return typeof value === "object" && value !== null ? value : void 0;
+	} catch {
+		return;
+	}
+};
+/** `POST /_realtime` `{ token, topic, type, data }` — a page on a Server-Sent Events connection, publishing. */
+var handleRealtimePublish = async ({ req, res, hub }) => {
+	const body = parseBody(req.body);
+	const connection = typeof body?.token === "string" ? hub.find(body.token) : void 0;
+	if (!body || !connection) {
+		answer(res, {
+			status: 401,
+			error: "Not connected: open /_realtime first and publish with its token",
+			reason: "not_connected"
+		});
+		return;
+	}
+	const result = await publishFrom(hub, connection, body);
+	if (result.status === 204) {
+		res.setStatus(204);
+		res.send("");
+		return;
+	}
+	answer(res, result);
+};
+//#endregion
+export { admit, answer, connectionFor, handleRealtimePublish, handleRealtimeSubscribe, publishFrom };

package/dist/modules/realtime/hub.d.ts

@@ -0,0 +1,62 @@
+import { ChannelDeclaration, PubSubAdapter, RealtimeMessage, RealtimeSender } from '@plitzi/sdk-shared';
+/** The space a connection belongs to: its topics are that space's and no other's. */
+export type RealtimeSpace = {
+    spaceId: number;
+    environment: string;
+};
+/** One page, connected. */
+export type RealtimeConnection = {
+    /** Its public name — the `from` of everything it sends. */
+    id: string;
+    /** Its secret: what a publish proves it comes from this connection with. Never sent to anyone else. */
+    token: string;
+    space: RealtimeSpace;
+    user?: RealtimeSender['user'];
+    /** The topics it subscribed to, with the channel each falls under. */
+    topics: Map<string, ChannelDeclaration>;
+    /** The grant each topic of a `grant: true` channel was opened with — what a revoke names. */
+    grants: Map<string, string>;
+    /** The topics it announced itself on, which hear `$leave` when it goes. */
+    announced: Set<string>;
+    /** Messages sent this second, by topic — the rate a channel allows is per connection, and a connection is here. */
+    sent: Map<string, {
+        second: number;
+        count: number;
+    }>;
+    send: (event: string, data: unknown) => void;
+    /** Closes it from the server's side — the server is going away. Its own `close` then lets it go as any other. */
+    end: () => void;
+};
+/** A space's topic, as the adapter knows it: namespaced, so two spaces never hear each other. */
+export declare const adapterTopic: ({ spaceId, environment }: RealtimeSpace, topic: string) => string;
+export type RealtimeHub = ReturnType<typeof createRealtimeHub>;
+/**
+ * This process's connections, and the ONE adapter subscription per topic they share.
+ *
+ * A hundred pages on one board are a hundred connections here and a single subscription to the adapter: a message
+ * arrives once and is written to each of them. The last one to leave a topic unsubscribes it.
+ */
+export declare const createRealtimeHub: (pubsub: PubSubAdapter) => {
+    publish: (space: RealtimeSpace, message: RealtimeMessage) => Promise<void>;
+    from: (connection: RealtimeConnection, topic: string, type: string, data: unknown) => RealtimeMessage;
+    find: (token: string) => RealtimeConnection | undefined;
+    /**
+     * Lets go of `topic` every connection, on every replica, that opened it with `grant` — or with any grant, naming
+     * none. What stops a grant that is already in use; `grants.revoke` is what stops it being used again.
+     */
+    revoke: (space: RealtimeSpace, topic: string, grant?: string) => Promise<void>;
+    /** Subscribes a new connection to its topics, and tells the members of each presence channel it arrived. */
+    connect: (connection: RealtimeConnection) => Promise<void>;
+    /** Unsubscribes a connection that went away, and tells the channels it announced itself on. */
+    disconnect: (connection: RealtimeConnection) => Promise<void>;
+    /**
+     * Every connection closed from here: the server is shutting down. An open socket or event stream is a request that
+     * never ends, so a server waiting for them to finish waited for ever — each is told to go, and goes the way it
+     * goes when its page leaves.
+     */
+    closeAll: () => void;
+    /** How many connections this process holds — for tests and for a health endpoint. */
+    readonly connectionCount: number;
+    /** How many topics this process holds a subscription for — for tests and for a health endpoint. */
+    readonly topicCount: number;
+};

package/dist/modules/realtime/hub.js

@@ -0,0 +1,141 @@
+import { JOIN_TYPE, LEAVE_TYPE, REVOKED_TYPE } from "@plitzi/sdk-shared/realtime";
+//#region src/modules/realtime/hub.ts
+/** A space's topic, as the adapter knows it: namespaced, so two spaces never hear each other. */
+var adapterTopic = ({ spaceId, environment }, topic) => `${spaceId}/${environment}/${topic}`;
+/**
+* Said between the servers, never to a page: every connection opened with the grant it names — or, naming none, with
+* any grant for the topic — is let go of it. On the topic's own adapter channel, so it reaches every replica holding
+* the topic, and only them. A page cannot send it: the types a page or a flow may use have no `$` but `$presence`.
+*/
+var REVOKE_TYPE = "$revoke";
+var revokedGrant = (data) => typeof data === "object" && data !== null && "grant" in data && typeof data.grant === "string" ? data.grant : void 0;
+/** A message as the adapter carried it — written by this module, but read from a transport that is not. */
+var isMessage = (value) => typeof value === "object" && value !== null && "topic" in value && typeof value.topic === "string" && "type" in value && typeof value.type === "string" && "from" in value && typeof value.from === "string" && "at" in value && typeof value.at === "number";
+var parse = (raw) => {
+	try {
+		const value = JSON.parse(raw);
+		return isMessage(value) ? value : void 0;
+	} catch {
+		return;
+	}
+};
+/**
+* This process's connections, and the ONE adapter subscription per topic they share.
+*
+* A hundred pages on one board are a hundred connections here and a single subscription to the adapter: a message
+* arrives once and is written to each of them. The last one to leave a topic unsubscribes it.
+*/
+var createRealtimeHub = (pubsub) => {
+	const byToken = /* @__PURE__ */ new Map();
+	const local = /* @__PURE__ */ new Map();
+	const publish = (space, message) => pubsub.publish(adapterTopic(space, message.topic), JSON.stringify(message));
+	const join = async (connection, topic) => {
+		const key = adapterTopic(connection.space, topic);
+		let entry = local.get(key);
+		if (!entry) {
+			const connections = /* @__PURE__ */ new Set();
+			entry = {
+				connections,
+				release: pubsub.subscribe(key, (raw) => {
+					const message = parse(raw);
+					if (message?.type === REVOKE_TYPE) {
+						const grant = revokedGrant(message.data);
+						[...connections].filter((member) => {
+							const opened = member.grants.get(message.topic);
+							return opened !== void 0 && (grant === void 0 || opened === grant);
+						}).forEach((member) => void releaseTopic(member, message.topic));
+					} else if (message) connections.forEach((member) => member.send("message", message));
+				})
+			};
+			local.set(key, entry);
+		}
+		entry.connections.add(connection);
+		await entry.release;
+	};
+	const leave = async (connection, topic) => {
+		const key = adapterTopic(connection.space, topic);
+		const entry = local.get(key);
+		if (!entry) return;
+		entry.connections.delete(connection);
+		if (entry.connections.size === 0) {
+			local.delete(key);
+			await (await entry.release)();
+		}
+	};
+	/** A stamped message from this connection: `from` and `user` are the server's, whatever was sent. */
+	const from = (connection, topic, type, data) => ({
+		topic,
+		type,
+		data,
+		from: connection.id,
+		...connection.user ? { user: connection.user } : {},
+		at: Date.now()
+	});
+	/**
+	* Lets `connection` go of `topic`: it is told, the others on a presence channel hear it leave, and it no longer
+	* hears the topic or may send on it.
+	*/
+	const releaseTopic = async (connection, topic) => {
+		connection.send("message", {
+			topic,
+			type: REVOKED_TYPE,
+			data: null,
+			from: "server",
+			at: Date.now()
+		});
+		connection.topics.delete(topic);
+		connection.grants.delete(topic);
+		await leave(connection, topic);
+		if (connection.announced.delete(topic)) await publish(connection.space, from(connection, topic, LEAVE_TYPE, null));
+	};
+	return {
+		publish,
+		from,
+		find: (token) => byToken.get(token),
+		/**
+		* Lets go of `topic` every connection, on every replica, that opened it with `grant` — or with any grant, naming
+		* none. What stops a grant that is already in use; `grants.revoke` is what stops it being used again.
+		*/
+		revoke: (space, topic, grant) => publish(space, {
+			topic,
+			type: REVOKE_TYPE,
+			data: grant === void 0 ? null : { grant },
+			from: "server",
+			at: Date.now()
+		}),
+		/** Subscribes a new connection to its topics, and tells the members of each presence channel it arrived. */
+		connect: async (connection) => {
+			byToken.set(connection.token, connection);
+			for (const [topic, declaration] of connection.topics) {
+				await join(connection, topic);
+				if (declaration.presence) await publish(connection.space, from(connection, topic, JOIN_TYPE, null));
+			}
+		},
+		/** Unsubscribes a connection that went away, and tells the channels it announced itself on. */
+		disconnect: async (connection) => {
+			byToken.delete(connection.token);
+			for (const topic of connection.topics.keys()) {
+				if (connection.announced.has(topic)) await publish(connection.space, from(connection, topic, LEAVE_TYPE, null));
+				await leave(connection, topic);
+			}
+		},
+		/**
+		* Every connection closed from here: the server is shutting down. An open socket or event stream is a request that
+		* never ends, so a server waiting for them to finish waited for ever — each is told to go, and goes the way it
+		* goes when its page leaves.
+		*/
+		closeAll: () => {
+			[...byToken.values()].forEach((connection) => connection.end());
+		},
+		/** How many connections this process holds — for tests and for a health endpoint. */
+		get connectionCount() {
+			return byToken.size;
+		},
+		/** How many topics this process holds a subscription for — for tests and for a health endpoint. */
+		get topicCount() {
+			return local.size;
+		}
+	};
+};
+//#endregion
+export { adapterTopic, createRealtimeHub };

package/dist/modules/realtime/index.d.ts

@@ -0,0 +1,51 @@
+import { ChannelResolver } from './declarations';
+import { RealtimeGrants } from './grants';
+import { RealtimeHub } from './hub';
+import { RealtimeTransport, SSRServerConfig } from '@plitzi/sdk-shared';
+export { createMemoryPubSub } from './memoryPubSub';
+export { handleRealtimePublish, handleRealtimeSubscribe } from './handlers';
+export { handleRealtimeSocket } from './socket';
+export type RealtimeModule = {
+    hub: RealtimeHub;
+    path: string;
+    /** What pages are told to connect with. Both are served whatever this says. */
+    transport: RealtimeTransport;
+    /** Origins besides the server's own whose pages may open a socket. */
+    allowedOrigins: readonly string[];
+    resolveChannels: ChannelResolver;
+    /** The grants issued for topics of channels declared `grant: true`, and the check a subscription makes. */
+    grants: RealtimeGrants;
+    /** Closes every connection this process holds: the server is shutting down (`HttpServerParts.onClosing`). */
+    close: () => void;
+    /**
+     * Publishes from the server — what a flow's `realtime.publish` does. Checked against the space's channels like a
+     * page's publish, and sent `from: 'server'`: the one sender a page cannot be.
+     */
+    publish: (space: {
+        spaceId: number;
+        environment: string;
+    }, topic: string, type: string, data: unknown) => Promise<void>;
+    /**
+     * A grant for one topic of a channel declared `grant: true` — what a flow's `realtime.grant` hands a page, once it
+     * has decided the visitor may be there. Refused for a topic of any other channel: a grant it would never ask for
+     * is a mistake in the flow, not a key to hand out.
+     */
+    grant: (space: {
+        spaceId: number;
+        environment: string;
+    }, topic: string, ttlSeconds?: number) => Promise<string>;
+    /**
+     * `grant` no longer opens `topic` — or, naming none, no grant issued for it until now does: nobody who holds one gets
+     * in again, and whoever is on the topic with one, on any replica, is let go of it (`$revoked`). A page kept out asks
+     * the action that lets it in for a new grant, if it still may.
+     */
+    revoke: (space: {
+        spaceId: number;
+        environment: string;
+    }, topic: string, grant?: string) => Promise<void>;
+};
+/**
+ * The server's realtime channels, built once per config — or `undefined` when they are off or cannot be: without the
+ * space's documents (`getOfflineData`) there is nothing to say which channels a space declares, so none is opened.
+ */
+export declare const realtimeModuleFor: (config: SSRServerConfig) => RealtimeModule | undefined;

package/dist/modules/realtime/index.js

@@ -0,0 +1,62 @@
+import { fleetStore } from "../../core/server/fleet/link.js";
+import { KV_METHODS, createMemoryKv } from "../actions/runtime/memoryKv.js";
+import { createRealtimeGrants } from "./grants.js";
+import { createChannelResolver } from "./declarations.js";
+import { createRealtimeHub } from "./hub.js";
+import { createMemoryPubSub } from "./memoryPubSub.js";
+import { handleRealtimePublish, handleRealtimeSubscribe } from "./handlers.js";
+import { handleRealtimeSocket } from "./socket.js";
+import { matchChannel } from "@plitzi/sdk-shared/realtime";
+//#region src/modules/realtime/index.ts
+/** A type a flow publishes: its own vocabulary — the `$` types are the channel's. */
+var SERVER_TYPE = /^[A-Za-z0-9_.:-]{1,64}$/;
+var modules = /* @__PURE__ */ new WeakMap();
+/**
+* The server's realtime channels, built once per config — or `undefined` when they are off or cannot be: without the
+* space's documents (`getOfflineData`) there is nothing to say which channels a space declares, so none is opened.
+*/
+var realtimeModuleFor = (config) => {
+	const getOfflineData = config.adapters.getOfflineData;
+	if (config.realtime === false || !getOfflineData) return;
+	const existing = modules.get(config);
+	if (existing) return existing;
+	const hub = createRealtimeHub(config.realtime?.pubsub ?? createMemoryPubSub());
+	const resolveChannels = createChannelResolver(getOfflineData);
+	const grants = createRealtimeGrants(config.action?.kv ?? fleetStore("realtime.grants", KV_METHODS) ?? createMemoryKv());
+	const module = {
+		hub,
+		path: config.realtime?.path ?? "/_realtime",
+		transport: config.realtime?.transport ?? "sse",
+		allowedOrigins: config.realtime?.allowedOrigins ?? [],
+		resolveChannels,
+		grants,
+		close: () => hub.closeAll(),
+		publish: async (space, topic, type, data) => {
+			const channels = await resolveChannels(space.spaceId, space.environment);
+			if (!matchChannel(topic, channels)) throw new Error(`No channel of this space matches "${topic}": declare it in the space's \`channels\``);
+			if (!SERVER_TYPE.test(type)) throw new Error("A message type is 1-64 of A-Z a-z 0-9 _ . : -");
+			await hub.publish(space, {
+				topic,
+				type,
+				data,
+				from: "server",
+				at: Date.now()
+			});
+		},
+		grant: async (space, topic, ttlSeconds) => {
+			const match = matchChannel(topic, await resolveChannels(space.spaceId, space.environment));
+			if (!match) throw new Error(`No channel of this space matches "${topic}": declare it in the space's \`channels\``);
+			if (match.declaration.grant !== true) throw new Error(`"${match.pattern}" is open to anyone its access lets in, so it takes no grant: declare it \`grant: true\` to make its topics private`);
+			return grants.issue(space, topic, ttlSeconds);
+		},
+		revoke: async (space, topic, grant) => {
+			if (matchChannel(topic, await resolveChannels(space.spaceId, space.environment))?.declaration.grant !== true) throw new Error(`"${topic}" is not a topic of a private (\`grant: true\`) channel of this space: it has no grants to revoke`);
+			await grants.revoke(space, topic, grant);
+			await hub.revoke(space, topic, grant);
+		}
+	};
+	modules.set(config, module);
+	return module;
+};
+//#endregion
+export { handleRealtimePublish, handleRealtimeSocket, handleRealtimeSubscribe, realtimeModuleFor };

package/dist/modules/realtime/memoryPubSub.d.ts

@@ -0,0 +1,10 @@
+import { PubSubAdapter } from '@plitzi/sdk-shared';
+/**
+ * The default pub/sub: in this process, and across its workers.
+ *
+ * A page connected to one worker must hear what another worker published, so a publish is delivered here AND sent to
+ * the rest of the fleet as a broadcast, which each process delivers to its own listeners. Without workers the
+ * broadcast goes nowhere and this is a Map of listeners. A second REPLICA shares nothing with this one: a deployment
+ * that runs several hands the server an adapter over something shared (Redis, NATS…).
+ */
+export declare const createMemoryPubSub: () => PubSubAdapter;

package/dist/modules/realtime/memoryPubSub.js

@@ -0,0 +1,43 @@
+import { broadcast, channelName, onBroadcast } from "../../core/server/fleet/link.js";
+//#region src/modules/realtime/memoryPubSub.ts
+var isRelayed = (value) => typeof value === "object" && value !== null && "topic" in value && typeof value.topic === "string" && "message" in value && typeof value.message === "string";
+/**
+* The default pub/sub: in this process, and across its workers.
+*
+* A page connected to one worker must hear what another worker published, so a publish is delivered here AND sent to
+* the rest of the fleet as a broadcast, which each process delivers to its own listeners. Without workers the
+* broadcast goes nowhere and this is a Map of listeners. A second REPLICA shares nothing with this one: a deployment
+* that runs several hands the server an adapter over something shared (Redis, NATS…).
+*/
+var createMemoryPubSub = () => {
+	const topics = /* @__PURE__ */ new Map();
+	const fleet = channelName("realtime.pubsub");
+	const deliver = (topic, message) => {
+		for (const listener of topics.get(topic) ?? []) listener(message);
+	};
+	onBroadcast(fleet, (payload) => {
+		if (isRelayed(payload)) deliver(payload.topic, payload.message);
+	});
+	return {
+		publish: (topic, message) => {
+			deliver(topic, message);
+			broadcast(fleet, {
+				topic,
+				message
+			});
+			return Promise.resolve();
+		},
+		subscribe: (topic, listener) => {
+			const listeners = topics.get(topic) ?? /* @__PURE__ */ new Set();
+			listeners.add(listener);
+			topics.set(topic, listeners);
+			return Promise.resolve(() => {
+				listeners.delete(listener);
+				if (listeners.size === 0) topics.delete(topic);
+				return Promise.resolve();
+			});
+		}
+	};
+};
+//#endregion
+export { createMemoryPubSub };

package/dist/modules/realtime/realtime.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/realtime/redisPubSub.d.ts

@@ -0,0 +1,24 @@
+import { PubSubAdapter } from '@plitzi/sdk-shared';
+/**
+ * The two Redis connections pub/sub needs, by shape — `ioredis` fits as it is, and so does anything answering the same
+ * calls. A connection in subscriber mode can do nothing else, which is why it is a second one.
+ */
+export type RedisPubSubClients = {
+    publisher: {
+        publish: (channel: string, message: string) => Promise<unknown>;
+    };
+    subscriber: {
+        subscribe: (channel: string) => Promise<unknown>;
+        unsubscribe: (channel: string) => Promise<unknown>;
+        on: (event: 'message', listener: (channel: string, message: string) => void) => unknown;
+    };
+    /** Prefixed onto every channel, so the realtime topics cannot collide with anything else on the server. */
+    prefix?: string;
+};
+/**
+ * Pub/sub over Redis: what a deployment of several replicas hands `createServer({ realtime: { pubsub } })`.
+ *
+ * One Redis subscription per topic per process, however many pages of that process listen to it: the listeners are
+ * kept here, and the channel is subscribed on the first and unsubscribed with the last.
+ */
+export declare const createRedisPubSub: ({ publisher, subscriber, prefix }: RedisPubSubClients) => PubSubAdapter;

package/dist/modules/realtime/redisPubSub.js

@@ -0,0 +1,36 @@
+//#region src/modules/realtime/redisPubSub.ts
+/**
+* Pub/sub over Redis: what a deployment of several replicas hands `createServer({ realtime: { pubsub } })`.
+*
+* One Redis subscription per topic per process, however many pages of that process listen to it: the listeners are
+* kept here, and the channel is subscribed on the first and unsubscribed with the last.
+*/
+var createRedisPubSub = ({ publisher, subscriber, prefix = "plitzi:rt:" }) => {
+	const listeners = /* @__PURE__ */ new Map();
+	subscriber.on("message", (channel, message) => {
+		if (!channel.startsWith(prefix)) return;
+		listeners.get(channel.slice(prefix.length))?.forEach((listener) => listener(message));
+	});
+	return {
+		publish: async (topic, message) => {
+			await publisher.publish(`${prefix}${topic}`, message);
+		},
+		subscribe: async (topic, listener) => {
+			const set = listeners.get(topic) ?? /* @__PURE__ */ new Set();
+			if (!set.size) {
+				listeners.set(topic, set);
+				await subscriber.subscribe(`${prefix}${topic}`);
+			}
+			set.add(listener);
+			return async () => {
+				set.delete(listener);
+				if (!set.size) {
+					listeners.delete(topic);
+					await subscriber.unsubscribe(`${prefix}${topic}`);
+				}
+			};
+		}
+	};
+};
+//#endregion
+export { createRedisPubSub };

package/dist/modules/realtime/redisPubSub.test.d.ts

@@ -0,0 +1 @@
+export {};