@protobase/server 0.58.7 → 0.59.0

package/dist/channels/channel-socket.js

@@ -0,0 +1,253 @@
+import { fitsFrame } from "../realtime/broadcast-frame.js";
+import { realtimeLimits } from "../realtime/realtime-limits.js";
+import { fixedWindow, fixedWindows } from "../realtime/fixed-window.js";
+import { channelRefusals } from "./channel-refusals.js";
+import { channelBounds } from "./channel-bounds.js";
+import { decodeClientMessage } from "./channel-protocol.js";
+import { entriesOf, entryDiff } from "./presence-entries.js";
+import { senderOf } from "./sent.js";
+import { randomUUID } from "node:crypto";
+import { Buffer } from "node:buffer";
+//#region src/channels/channel-socket.ts
+const messageTooBig = 1009;
+const policyViolation = 1008;
+const frameBytes = (frame) => {
+	if (typeof frame === "string") return Buffer.byteLength(frame);
+	if (frame instanceof ArrayBuffer || ArrayBuffer.isView(frame)) return frame.byteLength;
+	if (frame instanceof Blob) return frame.size;
+	return NaN;
+};
+const userOf = (session) => session.anonymous ? null : session.user.id;
+/**
+* One WebSocket of `/api/channels`: channels named by records, which a caller joins only while it may read the record,
+* with presence and broadcasts between the connections on each. Messages are handled one at a time, in order. Every
+* presence and broadcast carries the session's user, never one the client names. The session and each channel's read
+* access are checked again every `channelBounds.recheckMs`, and a send or track trusts the last check for
+* `channelBounds.readCacheMs`: a channel whose record the caller may no longer read is closed, and a session that signs
+* in nobody, or someone else, closes the socket. A socket silent for `channelBounds.idleMs` is closed, and a close
+* leaves every channel, its presences with it. The limits are `realtimeLimits`, as on `/api/sb/realtime/v1`.
+*/
+const channelSocket = ({ send, buffered, close, session: first, reauthenticate, record, readable, broadcasts, presences, report, now = Date.now }) => {
+	const channels = /* @__PURE__ */ new Map();
+	let session = first;
+	let token;
+	let queue = Promise.resolve();
+	let queuedMessages = 0;
+	let queuedBytes = 0;
+	let idle;
+	let open = true;
+	const events = fixedWindow(realtimeLimits.eventsPerSecond, 1e3, now);
+	const joins = fixedWindow(realtimeLimits.joinsPerSecond, 1e3, now);
+	const presenceRate = fixedWindows(realtimeLimits.presencePerWindow, realtimeLimits.presenceWindowMs, now);
+	const leaveAll = () => {
+		open = false;
+		clearTimeout(idle);
+		clearInterval(recheck);
+		for (const name of [...channels.keys()]) leave(name);
+	};
+	const shut = (code) => {
+		if (!open) return;
+		open = false;
+		clearTimeout(idle);
+		clearInterval(recheck);
+		close(code);
+		Promise.resolve().then(leaveAll).catch(report);
+	};
+	const push = (message) => {
+		if (!open) return;
+		if (!(buffered() <= realtimeLimits.maxUnsentBytes)) return shut(policyViolation);
+		send(JSON.stringify(message));
+	};
+	const ok = (ref, channel) => {
+		if (ref === void 0) return;
+		push({
+			type: "reply",
+			ref,
+			ok: true,
+			...channel !== void 0 && { channel }
+		});
+	};
+	const refuse = (ref, error) => {
+		if (ref === void 0) return push({
+			type: "error",
+			error
+		});
+		push({
+			type: "reply",
+			ref,
+			ok: false,
+			error
+		});
+	};
+	const leave = (name) => {
+		channels.get(name)?.remove();
+		channels.delete(name);
+	};
+	const end = (name, error) => {
+		if (!channels.has(name)) return;
+		leave(name);
+		push({
+			type: "closed",
+			channel: name,
+			error
+		});
+	};
+	const join = async (message) => {
+		if (!joins()) return refuse(message.ref, channelRefusals.tooManyJoins);
+		const found = record(message.resource, message.key);
+		if (found === "too-long") return refuse(message.ref, channelRefusals.nameTooLong);
+		if (found && channels.has(found.name)) return refuse(message.ref, channelRefusals.alreadyJoined);
+		if (channels.size >= realtimeLimits.channelsPerSocket) return refuse(message.ref, channelRefusals.tooManyChannels);
+		if (!found || !await readable(session, found)) return refuse(message.ref, channelRefusals.notFound);
+		await presences.ready();
+		if (!open || channels.has(found.name)) return;
+		const { name } = found;
+		const member = {
+			self: false,
+			private: false,
+			receive: (event, payload) => hear(name, event, payload)
+		};
+		const seat = presences.join(name, {
+			key: randomUUID(),
+			private: false,
+			listens: true,
+			receive: (diff) => push({
+				type: "presence_diff",
+				channel: name,
+				...entryDiff(diff)
+			})
+		});
+		const offBroadcast = broadcasts.join(name, member);
+		channels.set(name, {
+			record: found,
+			member,
+			seat,
+			checkedAt: now(),
+			remove: () => (offBroadcast(), seat.leave())
+		});
+		ok(message.ref, name);
+		push({
+			type: "presence",
+			channel: name,
+			entries: entriesOf(seat.state())
+		});
+	};
+	const hear = (name, event, sent) => {
+		if (!channels.has(name)) return;
+		push({
+			type: "broadcast",
+			channel: name,
+			event,
+			payload: sent.payload,
+			...senderOf(sent)
+		});
+	};
+	const stillReadable = async (name, channel) => {
+		if (now() - channel.checkedAt < channelBounds.readCacheMs) return true;
+		const allowed = await readable(session, channel.record);
+		if (channels.get(name) !== channel) return false;
+		if (!allowed) {
+			end(name, channelRefusals.notFound);
+			return false;
+		}
+		channel.checkedAt = now();
+		return true;
+	};
+	const sendBroadcast = async (message, channel) => {
+		if (!events()) return refuse(message.ref, channelRefusals.tooManyMessages);
+		if (!fitsFrame(message.event)) return refuse(message.ref, channelRefusals.eventTooLong);
+		if (!await stillReadable(message.channel, channel)) return refuse(message.ref, channelRefusals.notFound);
+		const sent = {
+			user: userOf(session),
+			payload: message.payload
+		};
+		if (!await broadcasts.send(message.channel, channel.member, message.event, sent)) return refuse(message.ref, channelRefusals.channelTooBusy);
+		if (message.self === true) hear(message.channel, message.event, sent);
+		if (message.ack === true) ok(message.ref);
+	};
+	const updatePresence = async (message, channel) => {
+		if (!events()) return refuse(message.ref, channelRefusals.tooManyMessages);
+		if (!presenceRate(message.channel)) return refuse(message.ref, channelRefusals.tooManyPresenceUpdates);
+		if (message.type === "untrack") {
+			channel.seat.untrack();
+			return ok(message.ref);
+		}
+		if (Buffer.byteLength(JSON.stringify(message.state) ?? "") > realtimeLimits.maxPresenceBytes) return refuse(message.ref, channelRefusals.presenceTooLarge);
+		if (!await stillReadable(message.channel, channel)) return refuse(message.ref, channelRefusals.notFound);
+		channel.seat.track({
+			user: userOf(session),
+			state: message.state
+		});
+		ok(message.ref);
+	};
+	const handle = async (message) => {
+		if (!open) return;
+		if (message.type === "ping") return push({ type: "pong" });
+		if (message.type === "token") {
+			token = message.token;
+			return;
+		}
+		if (message.type === "join") return join(message);
+		const channel = channels.get(message.channel);
+		if (!channel) return refuse(message.ref, channelRefusals.notJoined);
+		if (message.type === "send") return sendBroadcast(message, channel);
+		if (message.type === "track" || message.type === "untrack") return updatePresence(message, channel);
+		leave(message.channel);
+		ok(message.ref);
+	};
+	const checkAgain = async () => {
+		const again = await reauthenticate(token).then((next) => next, () => void 0);
+		if (!open) return;
+		if (!again || userOf(again) !== userOf(session)) return shut(policyViolation);
+		session = again;
+		for (const [name, channel] of [...channels]) {
+			const allowed = await readable(session, channel.record);
+			if (channels.get(name) !== channel) continue;
+			if (!allowed) end(name, channelRefusals.notFound);
+			else channel.checkedAt = now();
+		}
+	};
+	let rechecking = false;
+	const recheck = setInterval(() => {
+		if (rechecking || !open) return;
+		rechecking = true;
+		checkAgain().catch(fail).finally(() => rechecking = false);
+	}, channelBounds.recheckMs);
+	const stayAwake = () => {
+		clearTimeout(idle);
+		idle = setTimeout(() => shut(), channelBounds.idleMs);
+	};
+	stayAwake();
+	const fail = (error) => {
+		report(error);
+		shut();
+	};
+	return {
+		/**
+		* Handles a text frame after those before it; a binary one, or one that is not a message, gets an error. A frame
+		* over the size cap, or of a kind whose size is unknown, closes the socket.
+		*/
+		message: (frame) => {
+			if (!open) return;
+			const size = frameBytes(frame);
+			if (!(size <= realtimeLimits.maxFrameBytes)) return shut(messageTooBig);
+			stayAwake();
+			const message = typeof frame === "string" ? decodeClientMessage(frame) : void 0;
+			if (!message) return push({
+				type: "error",
+				error: channelRefusals.invalidMessage
+			});
+			queuedMessages += 1;
+			queuedBytes += size;
+			if (queuedMessages > realtimeLimits.maxQueuedMessages || queuedBytes > realtimeLimits.maxQueuedBytes) return shut(policyViolation);
+			queue = queue.then(() => handle(message)).catch(fail).finally(() => {
+				queuedMessages -= 1;
+				queuedBytes -= size;
+			});
+		},
+		/** Ends every channel of a socket that closed. */
+		closed: leaveAll
+	};
+};
+//#endregion
+export { channelSocket };

package/dist/channels/presence-entries.js

@@ -0,0 +1,24 @@
+//#region src/channels/presence-entries.ts
+/** The hub's presences as entries: each key is one connection on the channel, so it holds one presence at most. */
+const entriesOf = (state) => Object.entries(state).flatMap(([id, { metas }]) => metas.map(({ user, state: tracked }) => ({
+	id,
+	user,
+	state: tracked
+})));
+/**
+* A hub diff as joins, updates and leaves: a key that left and joined in one diff tracked again, an update. A key
+* that joins without the leave of its old state, as from another process whose leave this one never saw, is a join.
+*/
+const entryDiff = (diff) => {
+	const joined = entriesOf(diff.joins);
+	const left = entriesOf(diff.leaves);
+	const joinedIds = new Set(joined.map((entry) => entry.id));
+	const leftIds = new Set(left.map((entry) => entry.id));
+	return {
+		joins: joined.filter((entry) => !leftIds.has(entry.id)),
+		updates: joined.filter((entry) => leftIds.has(entry.id)),
+		leaves: left.filter((entry) => !joinedIds.has(entry.id))
+	};
+};
+//#endregion
+export { entriesOf, entryDiff };

package/dist/channels/record-readable.js

@@ -0,0 +1,28 @@
+import { HttpProblem } from "../problem.js";
+import { requestAccess } from "../request-access.js";
+import { readTransaction } from "../transactions.js";
+import { fetchReadable } from "../fetch-readable.js";
+//#region src/channels/record-readable.ts
+const refusedStatuses = /* @__PURE__ */ new Set([
+	401,
+	403,
+	404
+]);
+/**
+* Whether the caller may read the record, as `GET /api/<resource>/<key>` decides it: the resource's read access, the
+* tenant, the row filter, the parents read and a record-level read rule. A soft-deleted record is not readable.
+*/
+const recordReadable = async (deps, session, { entry, key }) => {
+	const read = async () => {
+		const access = await requestAccess(deps, entry, session);
+		if (!access.resolved.operations.read) return false;
+		const primary = access.full.fields[access.full.primaryKey[0]];
+		return await readTransaction(deps.db, deps.statementTimeoutMs, (trx) => fetchReadable(trx, access, key, "hide", { fields: [primary] })) !== void 0;
+	};
+	return read().catch((error) => {
+		if (error instanceof HttpProblem && refusedStatuses.has(error.status)) return false;
+		throw error;
+	});
+};
+//#endregion
+export { recordReadable };

package/dist/channels/sent.js

@@ -0,0 +1,8 @@
+//#region src/channels/sent.ts
+/** The sender as a broadcast message names it. */
+const senderOf = (sent) => ({
+	user: sent.user,
+	...sent.server && { server: true }
+});
+//#endregion
+export { senderOf };

package/dist/create-admin.js

@@ -16,8 +16,11 @@ import { apiCors, readCorsOrigins, withMobileOrigins } from "./api-cors.js";
 import { apiKeySettings } from "./api-keys/api-key-settings.js";
 import { apiKeyCaller } from "./api-keys/resolve-caller.js";
 import { jwtVerifier } from "./auth/jwt.js";
-import { relayed } from "./realtime/relay/realtime-options.js";
 import { realtimeApp } from "./realtime/realtime-app.js";
+import { relayed } from "./realtime/relay/realtime-options.js";
+import { realtimeHubs } from "./realtime/realtime-hubs.js";
+import { channelSender } from "./channels/channel-sender.js";
+import { channelRoutes } from "./channels/channel-routes.js";
 import { startRealtimePrune } from "./realtime/realtime-prune.js";
 import { restRoutes } from "./rest/rest-routes.js";
 import { storageRoutes } from "./storage/storage-routes.js";
@@ -376,6 +379,8 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 		}
 	});
 	const decryptField = fieldDecrypter(deps);
+	const hubs = realtimeHubs(deps, realtime, report);
+	const channels = channelSender(registry, hubs.records.broadcasts);
 	app.route("/", functionRoutes({
 		basePath: `${systemPath}/functions`,
 		functions: apiFunctions,
@@ -383,6 +388,7 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 		access: deps.accessOptions,
 		db,
 		records: (session) => callerRecords(deps, session),
+		channels,
 		decryptField,
 		onError,
 		wake: () => wakeDispatch(deps),
@@ -391,6 +397,19 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 		...calls && { calls },
 		report
 	}));
+	if (upgradeWebSocket) {
+		const visitors = (caller) => withAnonymous(caller, options.roles);
+		app.route(systemPath || "/", channelRoutes({
+			deps,
+			upgradeWebSocket,
+			authenticate: visitors(authenticate),
+			authenticateUpgrade: visitors(upgradeAuthenticate),
+			onError,
+			hubs: hubs.records,
+			follow: hubs.follow,
+			report
+		}));
+	}
 	const verifyGoTrue = auth ? jwtVerifier(goTrueTokens({ auth })) : () => Promise.reject(unauthorized("This app signs no user tokens"));
 	app.route("/", supabaseFunctionRoutes({
 		functions: apiFunctions,
@@ -435,7 +454,7 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 			upgradeWebSocket,
 			caller,
 			report,
-			...realtime && { options: realtime }
+			hubs
 		}));
 		if (files?.storage) {
 			const storage = {
@@ -462,6 +481,7 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 		deps,
 		subscriptions,
 		functions: apiFunctions,
+		channels,
 		schema: changes,
 		log: (line) => console.log(line),
 		...table && { table }

package/dist/functions/define-function.d.ts

@@ -3,6 +3,7 @@ import { Session } from "../types.js";
 import { Caller } from "../api-keys/resolve-caller.js";
 import { SocketEvents } from "./function-socket.js";
 import { CallsAccess } from "../calls/calls-access.js";
+import { ChannelSender } from "../channels/channel-sender.js";
 import { FunctionRecords } from "./records.js";
 import { Capability } from "@protobase/schema";
 import { Db } from "@protobase/query";
@@ -13,6 +14,8 @@ export type PublicFunctionContext = {
   name: string;
   /** The database itself, with no access rules, row filters or tenant scope: privileged work only. */
   db: Db;
+  /** Broadcasts to the channel of a record, as the server, to whoever is on it (see `/api/channels`). */
+  channels: ChannelSender;
   /** The caller, through the app's own `authenticate`: rejects with a 401 problem when the request carries no valid token. */
   caller: () => Promise<FunctionCaller>;
   /**

package/dist/functions/routes.js

@@ -24,7 +24,7 @@ const isUpgrade = (request) => request.headers.get("upgrade")?.toLowerCase() ===
 * A function may answer an upgrade with a socket, only once it returned. While it is open, its caller is checked again
 * every minute: a protected function's always, a public one's once `caller()` resolved.
 */
-const functionRoutes = ({ basePath, functions, authenticate, access, db, records, decryptField, onError, wake, upgradeWebSocket, upgradeAuthenticate = authenticate, calls: callsOptions, report }) => {
+const functionRoutes = ({ basePath, functions, authenticate, access, db, records, channels, decryptField, onError, wake, upgradeWebSocket, upgradeAuthenticate = authenticate, calls: callsOptions, report }) => {
 	const calls = callsAccess(callsOptions);
 	const app = new Hono().basePath(basePath);
 	app.onError(onError);
@@ -68,6 +68,7 @@ const functionRoutes = ({ basePath, functions, authenticate, access, db, records
 				const context = {
 					name,
 					db,
+					channels,
 					caller: resolveCaller,
 					acceptWebSocket: acceptor.accept,
 					calls
@@ -95,6 +96,7 @@ const functionRoutes = ({ basePath, functions, authenticate, access, db, records
 			const context = {
 				name,
 				db,
+				channels,
 				...caller,
 				caller: async () => caller,
 				decryptField: decryptField(reader),

package/dist/index.d.ts

@@ -32,6 +32,7 @@ import { FunctionSocket, SocketEvents } from "./functions/function-socket.js";
 import { CallMember } from "./calls/call-member.js";
 import { CallsAccess } from "./calls/calls-access.js";
 import { ResourceSource, configExports } from "./resource-source.js";
+import { ChannelBroadcast, ChannelSender } from "./channels/channel-sender.js";
 import { ErrorReportingOptions, ErrorReportingSettings, errorReportingSettings, errorReportingVariable } from "./error-reporting/error-reporting-settings.js";
 import { ChatMessage, ChatTextPart, Completion, CompletionOptions, ModelError, ModelSettings, ReasoningDetail, ReasoningEffort, ToolCall, ToolSpec, streamChatCompletion } from "./assistant/chat-completions.js";
 import { CleanupEntry, CleanupSchedule, ScheduledDelete, storageCleanupSchedule } from "./files/cleanup-schedule.js";
@@ -174,4 +175,4 @@ import { DrainResult, JobsRuntime, StartJobsOptions, startJobs } from "./jobs/ru
 import { jobsDrainApp } from "./jobs/drain-route.js";
 import { checkJobsSchema, jobsSchema, jobsSchemaMigration } from "./jobs/schema.js";
 import { AdminAuth, CreateAuthOptions, UserCreatedHook, normalizeRoles } from "./better-auth/create-auth.js";
-export { type Admin, type AdminAuth, type AdminOptions, type AggregateParams, type ApiFunction, type ApiKeys, type ApiKeysOptions, type ApnsEnvironment, type AppIcons, type AppIdentity, type AppPoolConfig, type ApplyOptions, type ApplyResult, type ApprovalAnswer, type ApprovalRequest, type ArgumentsPayload, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type AuthHooks, type AuthSettings, type AuthenticateSettings, type Authenticator, type BaseToolContext, type BatchOperation, type BatchResult, type BetterAuthAuthenticator, type BetterAuthAuthenticatorOptions, type CallBackend, type CallMember, type Caller, type CallerOptions, type CallsAccess, type CallsOptions, type CapturedRow, type CascadingKey, type ChatMessage, type ChatTextPart, type CheckAiInput, type CleanupEntry, type CleanupReport, type CleanupSchedule, type CoalescedChange, type CommentItem, type CommentToolsInput, type CommentUsers, type Completion, type CompletionOptions, ConnectionsBusy, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CorsOptions, type CorsOrigins, type CreateAdminInput, type CreateAuthOptions, type DecryptField, type Device, type DeviceColumn, type DeviceKind, type DeviceStore, DeviceStoreError, type DrainResult, type EmailComponent, type EmailOptions, type EmailTemplate, type EncryptionStatus, type EncryptionTools, type EncryptionToolsInput, type EnqueueJob, type EnqueueOptions, type ErrorReporter, type ErrorReportingOptions, type ErrorReportingSettings, type EventData, type EventsOptions, FatalJobError, type FieldApplied, type FieldDecrypter, type FieldReader, type FieldStatus, type FileCleanupInput, type FileLimits, type FileObject, type FileProvider, type FileProviderSettings, type FileRef, type FileStore, type FileVariantObject, type FilesOptions, type FunctionApp, type FunctionCaller, type FunctionContext, type FunctionEnv, type FunctionHandler, type FunctionOptions, type FunctionRecords, type FunctionSocket, type FunctionSource, type HistoryColumn, type HistoryOptions, type HistoryPosition, type HistoryStore, HistoryStoreError, type HookContext, HttpProblem, type IssueTokenOptions, type JobContext, type JobDeclaration, type JobDefinition, type JobName, type JobOptions, type JobPayload, type JobRun, type JobsRuntime, type JsonObject, type JsonValue, type JwtOptions, type JwtVerifyOptions, type KeyFunctionContext, type LinkedAccount, type ListParams, type LiveKitBackend, type LocalFilesOptions, type MailMessage, type Mailer, type MapLayer, type MapOptions, type MapSettings, type McpApprovals, type McpGateInput, type McpHandlerInput, type McpRoutesInput, type McpServerInput, type McpToolsInput, type McpWrites, type MemberInput, type Membership, MissingCredentials, type MobileConfig, ModelError, type ModelSettings, type NewDevice, type NewNotification, type NewOrganization, type NewUser, type NotificationRecipients, NotificationSendError, type NotificationsOptions, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PgModule, type PipelineHook, type PlatformSignIn, type PluginOption, type PluginRef, type PngIcon, type ProtectedFunctionOptions, type PublicFunctionContext, type PublicFunctionEnv, type PublicFunctionHandler, type PublicFunctionOptions, type PushAnswer, type PushMessage, PushMessageError, type PushSender, type QueryOptions, type QueryResult, type ReadableResources, type RealtimeOptions, type RealtimePrune, type ReasoningDetail, type ReasoningEffort, type RebindOption, type RecordGroups, type RecordKey, type RecordKeyInput, type RecordPage, type RenderedEmail, type ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RunContext, type RuntimeOptions, type S3Bucket, type S3FilesOptions, type S3ListPage, type S3Object, type ScanGuardMode, type ScheduledDelete, type SendNotification, type Session, type SessionOrganization, type Sharp, type SignInPolicy, type SignInRule, type SignatureOptions, type SocketEvents, type SourceOption, type SourceRef, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StartJobsOptions, type StoreFileInput, type StoredMember, type StoredNotification, type StoredObject, type StoredOrganization, type StoredUser, type StrayValues, type SubscriptionDefinition, type SubscriptionEvent, type SubscriptionOptions, type TenantValue, type ToolAnnotations, type ToolCall, type ToolComment, type ToolCommentPage, type ToolComments, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TrustedApp, type TurnOptions, type UnreadableEntry, type Urgency, type User, type UserCreatedHook, type VapidSettings, type ViewSource, type WebPushFields, type WebPushOptions, type WebhooksOptions, type WidgetOptions, type WriteEvent, type WriteOperation, type WriteRecordToolsInput, addAppRoleToOwners, addCommentTool, addMember, apiKeyCaller, apiKeySettings, apiKeyVariables, appNameOver, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaDrift, authSchemaMigration, authStoreTables, backgroundSettled, badRequest, batchWriteTool, beforeSignInPluginsVariable, betterAuthTokens, capSocketMessages, changesMigration, checkAi, checkAuthSchema, checkChanges, checkComments, checkComputed, checkJobsSchema, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkSourceNames, checkViewQueries, checkWebhooksSchema, coalesce, commentTools, commentsMigration, computedMigration, configExports, consoleAuditQueue, conversationKey, countRecordsTool, createAdmin, createConversations, createEncryptionTools, createFileCleanup, createOrganization, createRecordTool, createUser, defaultAppName, defaultHistoryPage, defaultSignInPolicy, defineEmail, defineFunction, defineJob, defineTool, deleteRecordTool, deleteUser, describeResourceTool, deviceIdParam, deviceStore, devicesPath, enqueueJob, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, generateVapidKeys, getRecordTool, goTruePath, handleDroppedConnections, hasUsers, historyIdParam, historyIdPattern, historyLimits, historyPath, historyStore, honorSocketMessageCaps, imageSize, isBackgroundWork, isCaptured, isJobDefinition, isOAuthWellKnownPath, isSchedule, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, jwtVerifier, limitedFileStore, listCommentsTool, listOrganizations, listRecordsTool, listResourcesTool, listUsers, localFileStore, longQueryTimeoutMs, mapSettings, mapStyleUrl, mapStyleVariable, maxDevicesPerUser, maxHistoryPage, maxMessageBytes, maxRecipients, maxTokenTtlSeconds, maxTtlSeconds, maxUnreadCount, maxWidgetPropsBytes, mcpApprovals, mcpGate, mcpHandler, mcpIcons, mcpInstructions, mcpRoutes, mcpServer, mcpToolContext, mcpTools, migrationCommand, newWebhookSecret, normalizeRoles, notFound, notificationSenders, notificationsMigration, oauthWellKnownPaths, objectKey, parseColumns, parseRoles, passwordLength, pluginOptions, pluginsBeforeSignIn, pluginsFor, pluginsVariable, pngIcons, poolWaitMs, postgresDeviceStore, postgresHistoryStore, processor, pushMessage, queryRunnerMigration, readDbConnections, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readRecordTools, readVapidSettings, readWriteQueryTool, readableResources, realtimeLimits, realtimeRelayMigration, recordOf, refusalOf, refused, relayed, removeDevicesWithUsers, removeHistoryWithUsers, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runInBackground, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, seesAssistant, seesRuntime, sendNotification, sessionOf, setMemberRoles, setUserBanned, setUserRole, shownAppName, signInPolicyMethods, socketMessageCapOf, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storageProvider, storeFile, storeUsage, streamChatCompletion, subscription, supabasePath, thumbHash, unauthorized, updateRecordTool, urgencies, vapidPrivateKeyVariable, vapidPublicKeyVariable, vapidSubjectVariable, variantPath, verifySignature, verifyStandardWebhook, waitUntil, wantsLongQueries, webManifestPath, webPushSender, webauthnPath, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps, writeRecordTools };
+export { type Admin, type AdminAuth, type AdminOptions, type AggregateParams, type ApiFunction, type ApiKeys, type ApiKeysOptions, type ApnsEnvironment, type AppIcons, type AppIdentity, type AppPoolConfig, type ApplyOptions, type ApplyResult, type ApprovalAnswer, type ApprovalRequest, type ArgumentsPayload, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type AuthHooks, type AuthSettings, type AuthenticateSettings, type Authenticator, type BaseToolContext, type BatchOperation, type BatchResult, type BetterAuthAuthenticator, type BetterAuthAuthenticatorOptions, type CallBackend, type CallMember, type Caller, type CallerOptions, type CallsAccess, type CallsOptions, type CapturedRow, type CascadingKey, type ChannelBroadcast, type ChannelSender, type ChatMessage, type ChatTextPart, type CheckAiInput, type CleanupEntry, type CleanupReport, type CleanupSchedule, type CoalescedChange, type CommentItem, type CommentToolsInput, type CommentUsers, type Completion, type CompletionOptions, ConnectionsBusy, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CorsOptions, type CorsOrigins, type CreateAdminInput, type CreateAuthOptions, type DecryptField, type Device, type DeviceColumn, type DeviceKind, type DeviceStore, DeviceStoreError, type DrainResult, type EmailComponent, type EmailOptions, type EmailTemplate, type EncryptionStatus, type EncryptionTools, type EncryptionToolsInput, type EnqueueJob, type EnqueueOptions, type ErrorReporter, type ErrorReportingOptions, type ErrorReportingSettings, type EventData, type EventsOptions, FatalJobError, type FieldApplied, type FieldDecrypter, type FieldReader, type FieldStatus, type FileCleanupInput, type FileLimits, type FileObject, type FileProvider, type FileProviderSettings, type FileRef, type FileStore, type FileVariantObject, type FilesOptions, type FunctionApp, type FunctionCaller, type FunctionContext, type FunctionEnv, type FunctionHandler, type FunctionOptions, type FunctionRecords, type FunctionSocket, type FunctionSource, type HistoryColumn, type HistoryOptions, type HistoryPosition, type HistoryStore, HistoryStoreError, type HookContext, HttpProblem, type IssueTokenOptions, type JobContext, type JobDeclaration, type JobDefinition, type JobName, type JobOptions, type JobPayload, type JobRun, type JobsRuntime, type JsonObject, type JsonValue, type JwtOptions, type JwtVerifyOptions, type KeyFunctionContext, type LinkedAccount, type ListParams, type LiveKitBackend, type LocalFilesOptions, type MailMessage, type Mailer, type MapLayer, type MapOptions, type MapSettings, type McpApprovals, type McpGateInput, type McpHandlerInput, type McpRoutesInput, type McpServerInput, type McpToolsInput, type McpWrites, type MemberInput, type Membership, MissingCredentials, type MobileConfig, ModelError, type ModelSettings, type NewDevice, type NewNotification, type NewOrganization, type NewUser, type NotificationRecipients, NotificationSendError, type NotificationsOptions, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PgModule, type PipelineHook, type PlatformSignIn, type PluginOption, type PluginRef, type PngIcon, type ProtectedFunctionOptions, type PublicFunctionContext, type PublicFunctionEnv, type PublicFunctionHandler, type PublicFunctionOptions, type PushAnswer, type PushMessage, PushMessageError, type PushSender, type QueryOptions, type QueryResult, type ReadableResources, type RealtimeOptions, type RealtimePrune, type ReasoningDetail, type ReasoningEffort, type RebindOption, type RecordGroups, type RecordKey, type RecordKeyInput, type RecordPage, type RenderedEmail, type ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RunContext, type RuntimeOptions, type S3Bucket, type S3FilesOptions, type S3ListPage, type S3Object, type ScanGuardMode, type ScheduledDelete, type SendNotification, type Session, type SessionOrganization, type Sharp, type SignInPolicy, type SignInRule, type SignatureOptions, type SocketEvents, type SourceOption, type SourceRef, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StartJobsOptions, type StoreFileInput, type StoredMember, type StoredNotification, type StoredObject, type StoredOrganization, type StoredUser, type StrayValues, type SubscriptionDefinition, type SubscriptionEvent, type SubscriptionOptions, type TenantValue, type ToolAnnotations, type ToolCall, type ToolComment, type ToolCommentPage, type ToolComments, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TrustedApp, type TurnOptions, type UnreadableEntry, type Urgency, type User, type UserCreatedHook, type VapidSettings, type ViewSource, type WebPushFields, type WebPushOptions, type WebhooksOptions, type WidgetOptions, type WriteEvent, type WriteOperation, type WriteRecordToolsInput, addAppRoleToOwners, addCommentTool, addMember, apiKeyCaller, apiKeySettings, apiKeyVariables, appNameOver, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaDrift, authSchemaMigration, authStoreTables, backgroundSettled, badRequest, batchWriteTool, beforeSignInPluginsVariable, betterAuthTokens, capSocketMessages, changesMigration, checkAi, checkAuthSchema, checkChanges, checkComments, checkComputed, checkJobsSchema, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkSourceNames, checkViewQueries, checkWebhooksSchema, coalesce, commentTools, commentsMigration, computedMigration, configExports, consoleAuditQueue, conversationKey, countRecordsTool, createAdmin, createConversations, createEncryptionTools, createFileCleanup, createOrganization, createRecordTool, createUser, defaultAppName, defaultHistoryPage, defaultSignInPolicy, defineEmail, defineFunction, defineJob, defineTool, deleteRecordTool, deleteUser, describeResourceTool, deviceIdParam, deviceStore, devicesPath, enqueueJob, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, generateVapidKeys, getRecordTool, goTruePath, handleDroppedConnections, hasUsers, historyIdParam, historyIdPattern, historyLimits, historyPath, historyStore, honorSocketMessageCaps, imageSize, isBackgroundWork, isCaptured, isJobDefinition, isOAuthWellKnownPath, isSchedule, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, jwtVerifier, limitedFileStore, listCommentsTool, listOrganizations, listRecordsTool, listResourcesTool, listUsers, localFileStore, longQueryTimeoutMs, mapSettings, mapStyleUrl, mapStyleVariable, maxDevicesPerUser, maxHistoryPage, maxMessageBytes, maxRecipients, maxTokenTtlSeconds, maxTtlSeconds, maxUnreadCount, maxWidgetPropsBytes, mcpApprovals, mcpGate, mcpHandler, mcpIcons, mcpInstructions, mcpRoutes, mcpServer, mcpToolContext, mcpTools, migrationCommand, newWebhookSecret, normalizeRoles, notFound, notificationSenders, notificationsMigration, oauthWellKnownPaths, objectKey, parseColumns, parseRoles, passwordLength, pluginOptions, pluginsBeforeSignIn, pluginsFor, pluginsVariable, pngIcons, poolWaitMs, postgresDeviceStore, postgresHistoryStore, processor, pushMessage, queryRunnerMigration, readDbConnections, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readRecordTools, readVapidSettings, readWriteQueryTool, readableResources, realtimeLimits, realtimeRelayMigration, recordOf, refusalOf, refused, relayed, removeDevicesWithUsers, removeHistoryWithUsers, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runInBackground, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, seesAssistant, seesRuntime, sendNotification, sessionOf, setMemberRoles, setUserBanned, setUserRole, shownAppName, signInPolicyMethods, socketMessageCapOf, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storageProvider, storeFile, storeUsage, streamChatCompletion, subscription, supabasePath, thumbHash, unauthorized, updateRecordTool, urgencies, vapidPrivateKeyVariable, vapidPublicKeyVariable, vapidSubjectVariable, variantPath, verifySignature, verifyStandardWebhook, waitUntil, wantsLongQueries, webManifestPath, webPushSender, webauthnPath, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps, writeRecordTools };

package/dist/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.58.7";
+var version = "0.59.0";
 //#endregion
 export { version };

package/dist/realtime/broadcast-hub.js

@@ -1,5 +1,5 @@
-import { fixedWindows } from "./fixed-window.js";
 import { realtimeLimits } from "./realtime-limits.js";
+import { fixedWindows } from "./fixed-window.js";
 //#region src/realtime/broadcast-hub.ts
 /**
 * The channels of a process by topic, which hear each other's broadcasts in-process; with several processes,

package/dist/realtime/broadcast-request.js

@@ -1,6 +1,6 @@
 import { HttpProblem } from "../problem.js";
-import { realtimeLimits } from "./realtime-limits.js";
 import { fitsFrame } from "./broadcast-frame.js";
+import { realtimeLimits } from "./realtime-limits.js";
 //#region src/realtime/broadcast-request.ts
 /** A refused broadcast request; `message` too, which realtime-js's `httpSend` reads as the error. */
 const broadcastProblem = (status, slug, title, detail) => new HttpProblem(status, slug, title, detail, { message: detail });

package/dist/realtime/database-broadcasts.js

@@ -1,6 +1,6 @@
 import { writeTransaction } from "../transactions.js";
-import { realtimeLimits } from "./realtime-limits.js";
 import { fitsFrame } from "./broadcast-frame.js";
+import { realtimeLimits } from "./realtime-limits.js";
 import { sql } from "kysely";
 import { Buffer } from "node:buffer";
 //#region src/realtime/database-broadcasts.ts

package/dist/realtime/realtime-app.js

@@ -1,26 +1,10 @@
-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 { filterCheck } from "./filter-check.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 on a topic, of this
@@ -28,7 +12,7 @@ const hubsOf = (deps, options, report) => {
 * 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, options }) => {
+const realtimeApp = ({ deps, feed, upgradeWebSocket, caller, report, hubs }) => {
 	const live = deps.registry.entries.filter((entry) => entry.model.live);
 	const check = changeChecker({
 		db: deps.db,
@@ -49,7 +33,7 @@ const realtimeApp = ({ deps, feed, upgradeWebSocket, caller, report, options })
 		db: deps.db,
 		statementTimeoutMs: deps.statementTimeoutMs
 	});
-	const { broadcasts, presences, follow } = hubsOf(deps, options, report);
+	const { topics: { broadcasts, presences }, follow } = hubs;
 	const database = databaseBroadcasts({
 		db: deps.db,
 		statementTimeoutMs: deps.statementTimeoutMs,

package/dist/realtime/realtime-hubs.js

@@ -0,0 +1,30 @@
+import { broadcastHub } from "./broadcast-hub.js";
+import { presenceHub } from "./presence-hub.js";
+import { relayed } from "./relay/realtime-options.js";
+import { relayedHubs } from "./relay/relayed-hubs.js";
+//#region src/realtime/realtime-hubs.ts
+/**
+* The broadcast and presence hubs of a process: those of the topic channels of `/api/sb/realtime/v1`, and apart from
+* them those of the record channels of `/api/channels`, so neither hears the other. With `processes: 'many'` both go
+* through the one relay, which `follow` reads while a socket of either is open.
+*/
+const realtimeHubs = (deps, options, report) => {
+	if (relayed(options)) return relayedHubs({
+		db: deps.db,
+		statementTimeoutMs: deps.statementTimeoutMs,
+		report
+	});
+	return {
+		topics: {
+			broadcasts: broadcastHub(),
+			presences: presenceHub()
+		},
+		records: {
+			broadcasts: broadcastHub(),
+			presences: presenceHub()
+		},
+		follow: () => () => {}
+	};
+};
+//#endregion
+export { realtimeHubs };

package/dist/realtime/realtime-socket.js

@@ -1,12 +1,12 @@
 import { HttpProblem } from "../problem.js";
-import { fixedWindow, fixedWindows } from "./fixed-window.js";
-import { realtimeLimits } from "./realtime-limits.js";
 import { callerSettings } from "../rest/caller-settings.js";
 import { parseBindings } from "./postgres-changes.js";
 import "./filter-check.js";
 import { decodeBroadcastPush, encodeBroadcast, fitsFrame } from "./broadcast-frame.js";
+import { realtimeLimits } from "./realtime-limits.js";
 import { decodeMessage, encodeMessage, reply } from "./phoenix-message.js";
 import { privateGate, publicGate, readRefusalText } from "./channel-gate.js";
+import { fixedWindow, fixedWindows } from "./fixed-window.js";
 import { randomUUID } from "node:crypto";
 import { Buffer } from "node:buffer";
 //#region src/realtime/realtime-socket.ts

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

@@ -1,5 +1,5 @@
 //#region src/realtime/relay/realtime-options.d.ts
-/** How `/api/sb/realtime/v1` is served (`realtime` in `protobase.config.ts`). */
+/** How `/api/channels` and `/api/sb/realtime/v1` are 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.

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

@@ -95,9 +95,9 @@ const realtimeRelay = ({ db, statementTimeoutMs, heard, loaded, tracked, report,
 		/** 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),
+		broadcast: (space, publications) => admitBroadcasts(db, statementTimeoutMs, self, space, publications),
 		/** Writes a change of this process's presences, after those before it. */
-		changed: (change) => void inTurn(() => writePresence(db, self, change))
+		changed: (space, change) => void inTurn(() => writePresence(db, self, space, change))
 	};
 };
 //#endregion