@protobase/server 0.26.0 → 0.26.2

package/dist/create-admin.js

@@ -270,27 +270,25 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 	app.route("/", batchRoute(deps, authenticate, meta));
 	app.route("/", fileRoutes(deps, authenticate));
 	if (forms) app.route(`${systemPath}/forms`, formRoutes(deps, forms));
-	if (appModels.some((model) => model.live)) {
-		const report = options.onUnhandledError ?? ((error) => console.error(error));
-		const feed = tableFeed({
-			db,
-			schema: changes,
+	const report = options.onUnhandledError ?? ((error) => console.error(error));
+	const feed = tableFeed({
+		db,
+		schema: changes,
+		report
+	});
+	if (appModels.some((model) => model.live)) app.route(systemPath || "/", guarded((live) => void live.route("/", liveRoutes(feed, (session) => visibleNotices(deps, session))), withAnonymous(authenticate, options.roles)));
+	if (upgradeWebSocket && (apiKeys.publishable || apiKeys.secret)) {
+		const verify = verifyToken ?? (auth ? jwtVerifier(betterAuthTokens({ auth })) : () => Promise.reject(unauthorized("This app signs no user tokens")));
+		app.route("/realtime/v1", realtimeApp({
+			deps,
+			feed,
+			upgradeWebSocket,
+			caller: apiKeyCaller({
+				keys: apiKeys,
+				verify
+			}),
 			report
-		});
-		app.route(systemPath || "/", guarded((live) => void live.route("/", liveRoutes(feed, (session) => visibleNotices(deps, session))), withAnonymous(authenticate, options.roles)));
-		if (upgradeWebSocket && (apiKeys.publishable || apiKeys.secret)) {
-			const verify = verifyToken ?? (auth ? jwtVerifier(betterAuthTokens({ auth })) : () => Promise.reject(unauthorized("This app signs no user tokens")));
-			app.route("/realtime/v1", realtimeApp({
-				deps,
-				feed,
-				upgradeWebSocket,
-				caller: apiKeyCaller({
-					keys: apiKeys,
-					verify
-				}),
-				report
-			}));
-		}
+		}));
 	}
 	app.route(basePath, api);
 	app.route(`${deps.systemPath}/meta`, metaApp);

package/dist/realtime/broadcast-frame.js

@@ -0,0 +1,71 @@
+//#region src/realtime/broadcast-frame.ts
+const userBroadcastPush = 3;
+const userBroadcast = 4;
+const binaryEncoding = 0;
+const jsonEncoding = 1;
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+/**
+* A binary frame as the `broadcast` push it carries: a header of kind, the byte lengths of join ref, ref, topic, user
+* event and metadata, and the payload's encoding, then those fields and the payload. The metadata is dropped, as only
+* keys the server knows go in it. `undefined` for a frame of another kind or one cut short.
+*/
+const decodeBroadcastPush = (frame) => {
+	const bytes = new Uint8Array(frame);
+	if (bytes.length < 7 || bytes[0] !== userBroadcastPush) return void 0;
+	const [joinRefSize, refSize, topicSize, eventSize, metadataSize, encoding] = bytes.subarray(1, 7);
+	let offset = 7;
+	const field = (size) => decoder.decode(bytes.subarray(offset, offset += size));
+	const joinRef = field(joinRefSize);
+	const ref = field(refSize);
+	const topic = field(topicSize);
+	const event = field(eventSize);
+	offset += metadataSize;
+	if (offset > bytes.length) return void 0;
+	const body = frame.slice(offset);
+	let payload = body;
+	if (encoding === jsonEncoding) try {
+		payload = JSON.parse(decoder.decode(body));
+	} catch (error) {
+		if (error instanceof SyntaxError) return void 0;
+		throw error;
+	}
+	return {
+		joinRef: joinRef || null,
+		ref: ref || null,
+		topic,
+		event: "broadcast",
+		payload: {
+			type: "broadcast",
+			event,
+			payload
+		}
+	};
+};
+/** Whether a topic or event fits a binary frame's one-byte length. */
+const fitsFrame = (text) => encoder.encode(text).length <= 255;
+/**
+* A broadcast as the binary frame realtime-js reads: kind, topic, user event and metadata lengths, encoding, fields,
+* payload. A payload is JSON, or the bytes of a binary broadcast.
+*/
+const encodeBroadcast = (topic, event, payload) => {
+	const topicBytes = encoder.encode(topic);
+	const eventBytes = encoder.encode(event);
+	const binary = payload instanceof ArrayBuffer;
+	const body = binary ? new Uint8Array(payload) : encoder.encode(JSON.stringify(payload ?? {}));
+	if (topicBytes.length > 255 || eventBytes.length > 255) throw new Error("A broadcast topic and event are at most 255 bytes each");
+	const frame = new Uint8Array(5 + topicBytes.length + eventBytes.length + body.length);
+	frame.set([
+		userBroadcast,
+		topicBytes.length,
+		eventBytes.length,
+		0,
+		binary ? binaryEncoding : jsonEncoding
+	]);
+	frame.set(topicBytes, 5);
+	frame.set(eventBytes, 5 + topicBytes.length);
+	frame.set(body, 5 + topicBytes.length + eventBytes.length);
+	return frame.buffer;
+};
+//#endregion
+export { decodeBroadcastPush, encodeBroadcast, fitsFrame };

package/dist/realtime/broadcast-hub.js

@@ -0,0 +1,25 @@
+//#region src/realtime/broadcast-hub.ts
+/**
+* The channels of a process by topic, which hear each other's broadcasts in-process: a cloud app runs as one process,
+* so channels of other processes are not reached.
+*/
+const broadcastHub = () => {
+	const topics = /* @__PURE__ */ new Map();
+	return {
+		/** Puts the member on the topic until the returned function takes it off. */
+		join: (topic, member) => {
+			const members = topics.get(topic) ?? /* @__PURE__ */ new Set();
+			topics.set(topic, members.add(member));
+			return () => {
+				members.delete(member);
+				if (members.size === 0 && topics.get(topic) === members) topics.delete(topic);
+			};
+		},
+		/** Sends a broadcast to the topic's members, the sender only when it hears its own. */
+		send: (topic, from, event, payload) => {
+			for (const member of topics.get(topic) ?? []) if (member !== from || member.self) member.receive(event, payload);
+		}
+	};
+};
+//#endregion
+export { broadcastHub };

package/dist/realtime/presence-hub.js

@@ -0,0 +1,59 @@
+//#region src/realtime/presence-hub.ts
+const stateOf = (tracked) => {
+	const state = Object.create(null);
+	for (const [key, meta] of tracked) (state[key] ??= { metas: [] }).metas.push(meta);
+	return state;
+};
+/**
+* The presences of a process by topic, in-process like broadcasts: each joined channel tracks at most one, under its
+* key, and channels that listen hear every join and leave on their topic, their own included, as Phoenix Presence
+* sends them. Tracking again replaces the presence: a leave of the old one and a join of the new. Refs count up, unique
+* in the process.
+*/
+const presenceHub = () => {
+	const topics = /* @__PURE__ */ new Map();
+	let lastRef = 0;
+	const tell = (members, diff) => {
+		for (const member of members.keys()) if (member.listens) member.receive(diff);
+	};
+	return { 
+	/** Puts the member on the topic, with what it may do there until it leaves. */
+join: (topic, member) => {
+		const members = topics.get(topic) ?? /* @__PURE__ */ new Map();
+		topics.set(topic, members.set(member, void 0));
+		const untrack = () => {
+			const old = members.get(member);
+			if (!old) return;
+			members.set(member, void 0);
+			tell(members, {
+				joins: {},
+				leaves: stateOf([[member.key, old]])
+			});
+		};
+		return {
+			/** The topic's presences now, for `presence_state`. */
+			state: () => stateOf([...members].flatMap(([{ key }, meta]) => meta ? [[key, meta]] : [])),
+			track: (payload) => {
+				const old = members.get(member);
+				const meta = {
+					...payload,
+					phx_ref: String(++lastRef),
+					...old && { phx_ref_prev: old.phx_ref }
+				};
+				members.set(member, meta);
+				tell(members, {
+					joins: stateOf([[member.key, meta]]),
+					leaves: old ? stateOf([[member.key, old]]) : {}
+				});
+			},
+			untrack,
+			leave: () => {
+				untrack();
+				members.delete(member);
+				if (members.size === 0 && topics.get(topic) === members) topics.delete(topic);
+			}
+		};
+	} };
+};
+//#endregion
+export { presenceHub };

package/dist/realtime/realtime-app.js

@@ -4,7 +4,7 @@ import { realtimeRoutes } from "./realtime-routes.js";
 //#region src/realtime/realtime-app.ts
 /**
 * `/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.
+* the tables' RLS policies before it is sent, and broadcasts and presence between the channels of the process.
 */
 const realtimeApp = ({ deps, feed, upgradeWebSocket, caller, report }) => {
 	const live = deps.registry.entries.filter((entry) => entry.model.live);

package/dist/realtime/realtime-routes.js

@@ -1,5 +1,7 @@
 import { HttpProblem } from "../problem.js";
+import { broadcastHub } from "./broadcast-hub.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
@@ -9,10 +11,13 @@ const keyRequest = (apikey, token) => new Request("http://realtime.invalid/", {
 } });
 /**
 * `GET /realtime/v1/websocket?apikey=…&vsn=…`: Supabase Realtime's socket, for `postgres_changes` of the live
-* resources (see `realtimeSocket`). A missing or wrong key is refused before the upgrade, with 401.
+* resources, and broadcasts and presence between the sockets of this process (see `realtimeSocket`). A missing or wrong
+* key is refused before the upgrade, with 401.
 */
 const realtimeRoutes = ({ upgradeWebSocket, caller, live, hub, report }) => {
 	const app = new Hono();
+	const broadcasts = broadcastHub();
+	const presences = presenceHub();
 	let lastId = 0;
 	const nextId = () => ++lastId;
 	app.get("/websocket", async (c, next) => {
@@ -31,12 +36,14 @@ const realtimeRoutes = ({ upgradeWebSocket, caller, live, hub, report }) => {
 					resolve: (token) => caller(keyRequest(apikey, token)),
 					live,
 					hub,
+					broadcasts,
+					presences,
 					nextId,
 					report
 				});
 			},
 			onMessage: (event) => {
-				if (typeof event.data === "string") socket?.message(event.data);
+				if (typeof event.data === "string" || event.data instanceof ArrayBuffer) socket?.message(event.data);
 			},
 			onClose: () => socket?.closed()
 		};

package/dist/realtime/realtime-socket.js

@@ -1,6 +1,8 @@
 import { HttpProblem } from "../problem.js";
 import { parseBindings } from "./postgres-changes.js";
 import { decodeMessage, encodeMessage, reply } from "./phoenix-message.js";
+import { decodeBroadcastPush, encodeBroadcast, fitsFrame } from "./broadcast-frame.js";
+import { randomUUID } from "node:crypto";
 //#region src/realtime/realtime-socket.ts
 const tokenOf = (payload) => typeof payload.access_token === "string" && payload.access_token !== "" ? payload.access_token : void 0;
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -10,11 +12,11 @@ const refusal = (error) => {
 };
 /**
 * One WebSocket of `/realtime/v1`, speaking Phoenix channels as realtime-js expects: heartbeats, channel joins with
-* `postgres_changes` bindings and an access token, token refreshes on an open channel, and leaves. A channel's token
-* ends it when it expires, unless a newer one came first. Messages are handled one at a time, in order. Broadcast,
-* presence and private channels are refused for now.
+* `postgres_changes` bindings and an access token, token refreshes on an open channel, broadcasts with their `self`
+* and `ack` options, presence tracking, and leaves. A channel's token ends it when it expires, unless a newer one came
+* first. Messages are handled one at a time, in order. Private channels are refused for now.
 */
-const realtimeSocket = ({ vsn, send, close, resolve, live, hub, nextId, report, idleMs = 6e4, now = Date.now }) => {
+const realtimeSocket = ({ vsn, send, close, resolve, live, hub, broadcasts, presences, nextId, report, idleMs = 6e4, now = Date.now }) => {
 	const channels = /* @__PURE__ */ new Map();
 	let queue = Promise.resolve();
 	let idle;
@@ -26,6 +28,15 @@ const realtimeSocket = ({ vsn, send, close, resolve, live, hub, nextId, report,
 		event,
 		payload
 	});
+	const hear = (topic, channel, event, payload) => {
+		if (vsn === "2.0.0") return send(encodeBroadcast(topic, event, payload));
+		if (payload instanceof ArrayBuffer) return;
+		toChannel(topic, channel, "broadcast", {
+			type: "broadcast",
+			event,
+			payload
+		});
+	};
 	const leave = (topic) => {
 		const channel = channels.get(topic);
 		if (!channel) return;
@@ -54,24 +65,46 @@ const realtimeSocket = ({ vsn, send, close, resolve, live, hub, nextId, report,
 		leave(message.topic);
 		const config = isRecord(message.payload.config) ? message.payload.config : {};
 		if (config.private === true) return push(reply(message, "error", { reason: "Not implemented: private channels" }));
-		if (isRecord(config.presence) && config.presence.enabled === true) return push(reply(message, "error", { reason: "Not implemented: presence" }));
+		const broadcast = isRecord(config.broadcast) ? config.broadcast : {};
+		const presence = isRecord(config.presence) ? config.presence : {};
 		const caller = await resolve(tokenOf(message.payload)).catch(refusal);
 		if (typeof caller === "string") return push(reply(message, "error", { reason: caller }));
 		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,
+			receive: (event, payload) => hear(topic, channel, event, payload)
+		};
+		const key = typeof presence.key === "string" && presence.key !== "" ? presence.key : randomUUID();
+		const listens = presence.enabled === true;
+		const seat = presences.join(topic, {
+			key,
+			listens,
+			receive: (diff) => toChannel(topic, channel, "presence_diff", diff)
+		});
+		const offBroadcast = broadcasts.join(topic, member);
+		const offChanges = parsed.bindings.length > 0 ? hub.add({
+			caller: () => channel.caller,
+			bindings: parsed.bindings,
+			send: (payload) => toChannel(topic, channel, "postgres_changes", payload)
+		}) : () => {};
 		const channel = {
 			joinRef: message.joinRef,
 			caller,
-			remove: () => {}
+			ack: broadcast.ack === true,
+			member,
+			presence: seat,
+			remove: () => {
+				offChanges();
+				offBroadcast();
+				seat.leave();
+			}
 		};
-		if (parsed.bindings.length > 0) channel.remove = hub.add({
-			caller: () => channel.caller,
-			bindings: parsed.bindings,
-			send: (payload) => toChannel(message.topic, channel, "postgres_changes", payload)
-		});
-		channels.set(message.topic, channel);
-		expireAt(message.topic, channel);
+		channels.set(topic, channel);
+		expireAt(topic, channel);
 		push(reply(message, "ok", { postgres_changes: parsed.replies }));
+		if (listens) toChannel(topic, channel, "presence_state", seat.state());
 		if (parsed.bindings.length > 0) toChannel(message.topic, channel, "system", {
 			extension: "postgres_changes",
 			status: "ok",
@@ -87,14 +120,31 @@ const realtimeSocket = ({ vsn, send, close, resolve, live, hub, nextId, report,
 		channel.caller = caller;
 		expireAt(message.topic, channel);
 	};
+	const sendBroadcast = (message, channel) => {
+		const { event, payload } = message.payload;
+		if (typeof event !== "string") return push(reply(message, "error", { reason: "A broadcast needs an event" }));
+		if (!fitsFrame(message.topic) || !fitsFrame(event)) return push(reply(message, "error", { reason: "A broadcast topic and event are at most 255 bytes each" }));
+		broadcasts.send(message.topic, channel.member, event, payload);
+		if (channel.ack) push(reply(message, "ok", {}));
+	};
+	const updatePresence = (message, channel) => {
+		const { event, payload } = message.payload;
+		if (event === "track" && isRecord(payload)) channel.presence.track(payload);
+		else if (event === "untrack") channel.presence.untrack();
+		else return push(reply(message, "error", { reason: "A presence message tracks an object or untracks" }));
+		push(reply(message, "ok", {}));
+	};
 	const handle = async (message) => {
 		if (message.topic === "phoenix") {
 			if (message.event === "heartbeat") push(reply(message, "ok", {}));
 			return;
 		}
 		if (message.event === "phx_join") return join(message);
-		if (!channels.has(message.topic)) return push(reply(message, "error", { reason: "unmatched topic" }));
+		const channel = channels.get(message.topic);
+		if (!channel) return push(reply(message, "error", { reason: "unmatched topic" }));
 		if (message.event === "access_token") return refresh(message);
+		if (message.event === "broadcast") return sendBroadcast(message, channel);
+		if (message.event === "presence") return updatePresence(message, channel);
 		if (message.event === "phx_leave") {
 			leave(message.topic);
 			push(reply(message, "ok", {}));
@@ -106,7 +156,7 @@ const realtimeSocket = ({ vsn, send, close, resolve, live, hub, nextId, report,
 				payload: {}
 			});
 		}
-		push(reply(message, "error", { reason: `Not implemented: ${message.event}; this server has postgres_changes only` }));
+		push(reply(message, "error", { reason: `Not implemented: ${message.event}` }));
 	};
 	const stayAwake = () => {
 		clearTimeout(idle);
@@ -114,10 +164,10 @@ const realtimeSocket = ({ vsn, send, close, resolve, live, hub, nextId, report,
 	};
 	stayAwake();
 	return {
-		/** Handles a text frame after those before it. */
+		/** Handles a frame after those before it: text, or binary for a broadcast. */
 		message: (frame) => {
 			stayAwake();
-			const message = decodeMessage(vsn, frame);
+			const message = typeof frame === "string" ? decodeMessage(vsn, frame) : decodeBroadcastPush(frame);
 			if (!message) return;
 			queue = queue.then(() => handle(message)).catch((error) => {
 				report(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.26.0",
+  "version": "0.26.2",
   "description": "The Protobase REST API as a Hono app, with Better Auth sign-in.",
   "license": "Apache-2.0",
   "repository": {
@@ -32,9 +32,9 @@
   "dependencies": {
     "@better-auth/passkey": "^1.7.7",
     "@better-auth/sso": "^1.7.7",
-    "@protobase/layout": "0.26.0",
-    "@protobase/query": "0.26.0",
-    "@protobase/schema": "0.26.0",
+    "@protobase/layout": "0.26.2",
+    "@protobase/query": "0.26.2",
+    "@protobase/schema": "0.26.2",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/core": "^11.7.0",