@protobase/server 0.25.11 → 0.26.0

package/dist/realtime/change-hub.js

@@ -0,0 +1,100 @@
+import { callerSettings } from "../rest/caller-settings.js";
+import { changePayload, eventOf } from "./change-payload.js";
+//#region src/realtime/change-hub.ts
+const unique = (items) => [...new Set(items)];
+const watches = (binding, entry) => binding.entries.includes(entry);
+const groupChecks = (sinks, changes) => unique(changes.map((change) => change.entry)).map((entry) => {
+	const bindings = sinks.flatMap((sink) => sink.bindings).filter((binding) => watches(binding, entry));
+	const of = changes.filter((change) => change.entry === entry);
+	return {
+		entry,
+		bindings,
+		filters: [...new Map(bindings.filter((binding) => binding.conditions.length > 0).map((binding) => [binding.filter, binding.conditions])).entries()],
+		keys: unique(of.filter((change) => change.type !== "DELETE").map((change) => change.notice.key)),
+		deleted: unique(of.filter((change) => change.type === "DELETE").map((change) => change.notice.key))
+	};
+}).filter((check) => check.bindings.length > 0);
+/**
+* Where the open sockets of a process hear of changes: it follows the notice feed while any channel listens, and
+* checks each batch of notices for all channels at once, one batch at a time, so Realtime holds at most one pooled
+* connection per process, and only while a check runs. Channels whose callers have the same role and claims, such as a
+* user's tabs, are checked as one.
+*/
+const changeHub = ({ feed, check, entry, report }) => {
+	const sinks = /* @__PURE__ */ new Set();
+	let subscription;
+	let pending = [];
+	let running = false;
+	const deliver = async (notices) => {
+		const changes = notices.flatMap((notice) => {
+			const found = entry(notice.resource);
+			return found ? [{
+				notice,
+				entry: found,
+				type: eventOf(found, notice)
+			}] : [];
+		});
+		if (changes.length === 0 || sinks.size === 0) return;
+		const groups = /* @__PURE__ */ new Map();
+		for (const sink of sinks) {
+			const key = JSON.stringify(callerSettings(sink.caller()));
+			groups.set(key, [...groups.get(key) ?? [], sink]);
+		}
+		const planned = [...groups.values()].map((members) => ({
+			members,
+			checks: groupChecks(members, changes)
+		})).filter((group) => group.checks.length > 0);
+		const views = await check(planned.map(({ members, checks }) => ({
+			caller: members[0].caller(),
+			resources: checks.map(({ entry: checked, keys, deleted, filters }) => ({
+				entry: checked,
+				keys,
+				deleted,
+				filters: filters.map(([, conditions]) => conditions)
+			}))
+		})));
+		for (const { notice, entry: changed, type } of changes) planned.forEach(({ members, checks }, groupIndex) => {
+			const resourceIndex = checks.findIndex((item) => item.entry === changed);
+			if (resourceIndex < 0) return;
+			const view = views[groupIndex][resourceIndex];
+			const row = (type === "DELETE" ? view.deleted : view.rows).get(notice.key);
+			if (!row) return;
+			const { filters } = checks[resourceIndex];
+			for (const sink of members) {
+				if (!sinks.has(sink)) continue;
+				const ids = sink.bindings.filter((binding) => watches(binding, changed) && (binding.event === "*" || binding.event === type)).filter((binding) => binding.conditions.length === 0 || row.matches[filters.findIndex(([filter]) => filter === binding.filter)]).map((binding) => binding.id);
+				if (ids.length > 0) sink.send(changePayload(changed, notice, type, view.columns, row, ids));
+			}
+		});
+	};
+	const run = async () => {
+		running = true;
+		while (pending.length > 0) {
+			const batch = pending;
+			pending = [];
+			await deliver(batch).catch(report);
+		}
+		running = false;
+	};
+	const listen = (notices) => {
+		pending.push(...notices);
+		if (!running) run();
+	};
+	return { 
+	/** Sends the sink the changes it may see from now on, until the returned function removes it. */
+add: (sink) => {
+		sinks.add(sink);
+		subscription ??= feed.subscribe(listen).catch((error) => {
+			report(error);
+			subscription = void 0;
+		});
+		return () => {
+			sinks.delete(sink);
+			if (sinks.size > 0 || !subscription) return;
+			subscription.then((subscribed) => subscribed?.stop());
+			subscription = void 0;
+		};
+	} };
+};
+//#endregion
+export { changeHub };

package/dist/realtime/change-payload.js

@@ -0,0 +1,31 @@
+import { schemaOf } from "./postgres-changes.js";
+//#region src/realtime/change-payload.ts
+/**
+* What a notice is to a database client: a record created is an INSERT; one updated, undeleted or soft deleted, whose
+* row is still there, an UPDATE; one whose row is gone a DELETE.
+*/
+const eventOf = (entry, notice) => {
+	if (notice.operation === "create") return "INSERT";
+	if (notice.operation === "delete" && !entry.model.softDelete) return "DELETE";
+	return "UPDATE";
+};
+/**
+* The change for bindings `ids`. An insert or update carries the row as it is now, several changes since the last
+* poll showing its latest state each time, and `old_record` its key alone, as Supabase does without replica identity
+* full. A delete carries the key alone. `commit_timestamp` is when the change became a notice.
+*/
+const changePayload = (entry, notice, type, columns, row, ids) => ({
+	ids,
+	data: {
+		schema: schemaOf(entry),
+		table: entry.model.table.name,
+		commit_timestamp: notice.at,
+		type,
+		columns,
+		...type !== "DELETE" && { record: row.record },
+		...type !== "INSERT" && { old_record: row.oldRecord },
+		errors: null
+	}
+});
+//#endregion
+export { changePayload, eventOf };

package/dist/realtime/phoenix-message.js

@@ -0,0 +1,63 @@
+//#region src/realtime/phoenix-message.ts
+const vsnOf = (value) => {
+	if (value === void 0 || value === "2.0.0") return "2.0.0";
+	return value === "1.0.0" ? "1.0.0" : void 0;
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const text = (value) => typeof value === "string" ? value : value === null || value === void 0 ? null : String(value);
+/** A text frame as a message; `undefined` for one that is not a Phoenix message. Binary frames carry broadcasts only. */
+const decodeMessage = (vsn, frame) => {
+	let parsed;
+	try {
+		parsed = JSON.parse(frame);
+	} catch (error) {
+		if (error instanceof SyntaxError) return void 0;
+		throw error;
+	}
+	if (vsn === "2.0.0") {
+		if (!Array.isArray(parsed) || parsed.length !== 5) return void 0;
+		const [joinRef, ref, topic, event, payload] = parsed;
+		if (typeof topic !== "string" || typeof event !== "string" || !isRecord(payload)) return void 0;
+		return {
+			joinRef: text(joinRef),
+			ref: text(ref),
+			topic,
+			event,
+			payload
+		};
+	}
+	if (!isRecord(parsed) || typeof parsed.topic !== "string" || typeof parsed.event !== "string" || !isRecord(parsed.payload)) return void 0;
+	return {
+		joinRef: text(parsed.join_ref),
+		ref: text(parsed.ref),
+		topic: parsed.topic,
+		event: parsed.event,
+		payload: parsed.payload
+	};
+};
+const encodeMessage = (vsn, message) => JSON.stringify(vsn === "2.0.0" ? [
+	message.joinRef,
+	message.ref,
+	message.topic,
+	message.event,
+	message.payload
+] : {
+	join_ref: message.joinRef,
+	ref: message.ref,
+	topic: message.topic,
+	event: message.event,
+	payload: message.payload
+});
+/** The answer to a pushed message: `phx_reply` with its ref. */
+const reply = (to, status, response) => ({
+	joinRef: to.joinRef,
+	ref: to.ref,
+	topic: to.topic,
+	event: "phx_reply",
+	payload: {
+		status,
+		response
+	}
+});
+//#endregion
+export { decodeMessage, encodeMessage, reply, vsnOf };

package/dist/realtime/postgres-changes.js

@@ -0,0 +1,62 @@
+import { parseFilter } from "./change-filter.js";
+//#region src/realtime/postgres-changes.ts
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const optionalText = (value) => typeof value === "string" && value !== "" ? value : void 0;
+const eventOf = (value) => {
+	const upper = typeof value === "string" ? value.toUpperCase() : "*";
+	return upper === "INSERT" || upper === "UPDATE" || upper === "DELETE" ? upper : "*";
+};
+/** The schema a resource's table is in, `public` when it names none. */
+const schemaOf = (entry) => entry.model.table.schema ?? "public";
+const columnsOf = (entry) => new Set(Object.values(entry.model.fields).map((field) => field.column));
+const unavailable = (schema, table, filter) => `Unable to subscribe to changes with given parameters. Please check Realtime is enabled for the given connect parameters: [schema: ${schema}, table: ${table ?? "*"}, filters: ${filter ?? "[]"}]`;
+/**
+* The bindings a join asks for, each over the live resources whose table it names: by schema (`*` for any), table
+* (any when left out or `*`), event (`*` for all) and filter. A binding whose table is not live, a filter that does not
+* parse or names a column the table has not, and a `select` of columns are refused with Supabase's message, as an error
+* text.
+*/
+const parseBindings = (requested, live, nextId) => {
+	if (requested === void 0) return {
+		bindings: [],
+		replies: []
+	};
+	if (!Array.isArray(requested)) return "postgres_changes must be a list";
+	const bindings = [];
+	const replies = [];
+	for (const item of requested) {
+		if (!isRecord(item)) return "Each postgres_changes binding must be an object";
+		const schema = optionalText(item.schema) ?? "public";
+		const table = optionalText(item.table);
+		const filter = optionalText(item.filter);
+		if (item.select !== void 0) return "Not implemented: postgres_changes select; leave it out to receive every column";
+		const entries = live.filter((entry) => (schema === "*" || schemaOf(entry) === schema) && (table === void 0 || table === "*" || entry.model.table.name === table));
+		if (entries.length === 0) return unavailable(schema, table, filter);
+		const conditions = parseFilter(filter);
+		if (typeof conditions === "string") return conditions;
+		const missing = conditions.find((condition) => entries.some((entry) => !columnsOf(entry).has(condition.column)));
+		if (missing) return `invalid column for filter ${missing.column}`;
+		const id = nextId();
+		const event = eventOf(item.event);
+		bindings.push({
+			id,
+			event,
+			filter,
+			conditions,
+			entries
+		});
+		replies.push({
+			id,
+			event: typeof item.event === "string" ? item.event : "*",
+			schema,
+			...table !== void 0 && { table },
+			...filter !== void 0 && { filter }
+		});
+	}
+	return {
+		bindings,
+		replies
+	};
+};
+//#endregion
+export { parseBindings, schemaOf };

package/dist/realtime/realtime-app.js

@@ -0,0 +1,31 @@
+import { changeChecker } from "./change-checker.js";
+import { changeHub } from "./change-hub.js";
+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.
+*/
+const realtimeApp = ({ deps, feed, upgradeWebSocket, caller, report }) => {
+	const live = deps.registry.entries.filter((entry) => entry.model.live);
+	const check = changeChecker({
+		db: deps.db,
+		statementTimeoutMs: deps.statementTimeoutMs,
+		report
+	});
+	const hub = changeHub({
+		feed,
+		check,
+		entry: (resource) => live.find((entry) => entry.name === resource),
+		report
+	});
+	return realtimeRoutes({
+		upgradeWebSocket,
+		caller,
+		live,
+		hub,
+		report
+	});
+};
+//#endregion
+export { realtimeApp };

package/dist/realtime/realtime-routes.js

@@ -0,0 +1,47 @@
+import { HttpProblem } from "../problem.js";
+import { vsnOf } from "./phoenix-message.js";
+import { realtimeSocket } from "./realtime-socket.js";
+import { Hono } from "hono";
+//#region src/realtime/realtime-routes.ts
+const keyRequest = (apikey, token) => new Request("http://realtime.invalid/", { headers: {
+	apikey,
+	...token !== void 0 && { authorization: `Bearer ${token}` }
+} });
+/**
+* `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.
+*/
+const realtimeRoutes = ({ upgradeWebSocket, caller, live, hub, report }) => {
+	const app = new Hono();
+	let lastId = 0;
+	const nextId = () => ++lastId;
+	app.get("/websocket", async (c, next) => {
+		if (!vsnOf(c.req.query("vsn"))) throw new HttpProblem(400, "invalid-request", "Bad Request", "Use vsn 1.0.0 or 2.0.0");
+		await caller(keyRequest(c.req.query("apikey") ?? ""));
+		await next();
+	}, upgradeWebSocket((c) => {
+		const apikey = c.req.query("apikey");
+		let socket;
+		return {
+			onOpen: (_event, ws) => {
+				socket = realtimeSocket({
+					vsn: vsnOf(c.req.query("vsn")),
+					send: (frame) => ws.send(frame),
+					close: () => ws.close(),
+					resolve: (token) => caller(keyRequest(apikey, token)),
+					live,
+					hub,
+					nextId,
+					report
+				});
+			},
+			onMessage: (event) => {
+				if (typeof event.data === "string") socket?.message(event.data);
+			},
+			onClose: () => socket?.closed()
+		};
+	}));
+	return app;
+};
+//#endregion
+export { realtimeRoutes };

package/dist/realtime/realtime-socket.js

@@ -0,0 +1,135 @@
+import { HttpProblem } from "../problem.js";
+import { parseBindings } from "./postgres-changes.js";
+import { decodeMessage, encodeMessage, reply } from "./phoenix-message.js";
+//#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);
+const refusal = (error) => {
+	if (error instanceof HttpProblem && error.status === 401) return error.detail;
+	throw 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.
+*/
+const realtimeSocket = ({ vsn, send, close, resolve, live, hub, nextId, report, idleMs = 6e4, now = Date.now }) => {
+	const channels = /* @__PURE__ */ new Map();
+	let queue = Promise.resolve();
+	let idle;
+	const push = (message) => send(encodeMessage(vsn, message));
+	const toChannel = (topic, channel, event, payload) => push({
+		joinRef: channel.joinRef,
+		ref: null,
+		topic,
+		event,
+		payload
+	});
+	const leave = (topic) => {
+		const channel = channels.get(topic);
+		if (!channel) return;
+		channel.remove();
+		clearTimeout(channel.expiry);
+		channels.delete(topic);
+	};
+	const end = (topic, message) => {
+		const channel = channels.get(topic);
+		if (!channel) return;
+		toChannel(topic, channel, "system", {
+			extension: "system",
+			status: "error",
+			message
+		});
+		toChannel(topic, channel, "phx_close", {});
+		leave(topic);
+	};
+	const expireAt = (topic, channel) => {
+		clearTimeout(channel.expiry);
+		const exp = channel.caller.role === "authenticated" ? channel.caller.claims.exp : void 0;
+		if (exp === void 0) return;
+		channel.expiry = setTimeout(() => end(topic, "Token has expired"), Math.max(0, exp * 1e3 - now()));
+	};
+	const join = async (message) => {
+		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 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 channel = {
+			joinRef: message.joinRef,
+			caller,
+			remove: () => {}
+		};
+		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);
+		push(reply(message, "ok", { postgres_changes: parsed.replies }));
+		if (parsed.bindings.length > 0) toChannel(message.topic, channel, "system", {
+			extension: "postgres_changes",
+			status: "ok",
+			message: "Subscribed to PostgreSQL",
+			channel: message.topic.replace(/^realtime:/, "")
+		});
+	};
+	const refresh = async (message) => {
+		const caller = await resolve(tokenOf(message.payload)).catch(refusal);
+		const channel = channels.get(message.topic);
+		if (!channel) return;
+		if (typeof caller === "string") return end(message.topic, caller);
+		channel.caller = caller;
+		expireAt(message.topic, channel);
+	};
+	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" }));
+		if (message.event === "access_token") return refresh(message);
+		if (message.event === "phx_leave") {
+			leave(message.topic);
+			push(reply(message, "ok", {}));
+			return push({
+				joinRef: message.joinRef,
+				ref: message.ref,
+				topic: message.topic,
+				event: "phx_close",
+				payload: {}
+			});
+		}
+		push(reply(message, "error", { reason: `Not implemented: ${message.event}; this server has postgres_changes only` }));
+	};
+	const stayAwake = () => {
+		clearTimeout(idle);
+		idle = setTimeout(close, idleMs);
+	};
+	stayAwake();
+	return {
+		/** Handles a text frame after those before it. */
+		message: (frame) => {
+			stayAwake();
+			const message = decodeMessage(vsn, frame);
+			if (!message) return;
+			queue = queue.then(() => handle(message)).catch((error) => {
+				report(error);
+				close();
+			});
+		},
+		/** Ends every channel of a socket that closed. */
+		closed: () => {
+			clearTimeout(idle);
+			for (const topic of [...channels.keys()]) leave(topic);
+		}
+	};
+};
+//#endregion
+export { realtimeSocket };

package/dist/rest/caller-settings.js

@@ -0,0 +1,27 @@
+//#region src/rest/caller-settings.ts
+/**
+* The transaction settings a `/rest/v1` request runs with, as Supabase's PostgREST sets them: `role`, which is
+* `SET LOCAL ROLE`, to `anon` or `authenticated`, and the caller's claims in `request.jwt.claims` and its user in
+* `request.jwt.claim.sub`, which `auth.uid()`, `auth.role()` and `auth.jwt()` read. The `role` claim names the
+* database role, as on Supabase, whatever the token's own says. The app's role, of the secret key, sets no role: the
+* connection's own owns the tables. A signed-in user is the actor change capture records, when `actorSetting` is set.
+*/
+const callerSettings = (caller, actorSetting) => {
+	const role = caller.role === "app" ? "service_role" : caller.role;
+	const sub = caller.role === "authenticated" ? caller.claims.sub : void 0;
+	const actor = sub === void 0 ? void 0 : {
+		id: sub,
+		roles: []
+	};
+	return {
+		...caller.role !== "app" && { role: caller.role },
+		"request.jwt.claims": JSON.stringify({
+			...caller.claims,
+			role
+		}),
+		...sub !== void 0 && { "request.jwt.claim.sub": sub },
+		...actor && actorSetting && { [actorSetting]: JSON.stringify(actor) }
+	};
+};
+//#endregion
+export { callerSettings };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.25.11",
+  "version": "0.26.0",
   "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.25.11",
-    "@protobase/query": "0.25.11",
-    "@protobase/schema": "0.25.11",
+    "@protobase/layout": "0.26.0",
+    "@protobase/query": "0.26.0",
+    "@protobase/schema": "0.26.0",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/core": "^11.7.0",
@@ -65,6 +65,11 @@
     }
   },
   "devDependencies": {
-    "samlify": "^2.13.1"
+    "@hono/node-server": "^2.1.3",
+    "@supabase/ssr": "^0.12.7",
+    "@supabase/supabase-js": "^2.118.0",
+    "@types/ws": "^8.18.2",
+    "samlify": "^2.13.1",
+    "ws": "^8.22.0"
   }
 }