@rebasepro/server-postgres 0.24.0 → 0.24.1-canary.gcb918fc

package/dist/websocket-BLGc5yhs.js

@@ -0,0 +1,1604 @@
+import { createRequire as __createRequire } from "module";
+__createRequire(import.meta.url);
+import { r as __exportAll } from "./__vite-browser-external-BnuHet1e.js";
+import { A as budgetSendBuffers, M as terminateIfBacklogged, N as assertReadRequestReadable, ct as SqlResultTooLargeError, it as effectiveSqlRole, j as reapSilentSockets, lt as isNestedPath, ot as sqlRoleRanAs, st as SQL_RESULT_BYTE_BUDGET, ut as resolveNestedPath } from "./open-rebase-CbOur0TU.js";
+import { r as BranchingUnsupportedError } from "./BranchService-Bsn2wfaj.js";
+import { ApiError, RUNTIME_DEFAULT_MAX_BODY_SIZE, assertFieldOpsValid, assertNestedWriteAllowed, assertNoFieldOpsOnCreate, assertNoUserUpsert, assertUserCreationBodyValid, assertWriteRequestValid, createUserThroughAuthCollection, decideImpersonation, declaredErrorAnswer, extractUserFromToken, getAccessModel, logger, resolveConflictTarget, resolveRequireAuth, safeCompare } from "@rebasepro/server";
+import { ANONYMOUS_USER_ID, ListLimitError, hasAdminRole, isSQLAdmin, isSchemaAdmin, resolveClientListLimit, scopeGrants, scopesForRoles } from "@rebasepro/types";
+import { UnknownFilterOperatorError, deserializeFilter, redactSqlLiterals } from "@rebasepro/common";
+import { unref } from "@rebasepro/utils";
+import { WebSocket, WebSocketServer } from "ws";
+import { inspect } from "util";
+//#region src/socket-opt-ins.ts
+/**
+* Behaviours a client opts into when it opens the socket.
+*
+* The client names them on the socket URL, `?rebase_caps=heartbeat,channel_seq,cancel_sql`,
+* and the server answers with a `hello` frame listing the ones it will honour:
+*
+* ```json
+* { "type": "hello", "capabilities": ["heartbeat", "channel_seq", "cancel_sql"], "heartbeatMs": 30000, "clientId": "client_…" }
+* ```
+*
+* Both halves are needed, so both directions of a version mismatch keep
+* working. An older client names none and gets no `hello`, no heartbeat and no
+* acknowledgement frames — nothing it would not recognise. An older server
+* ignores the query parameter and sends no `hello`, and a newer client that
+* hears none behaves as it always did.
+*
+* One list for both kinds: what the server sends (`heartbeat`, `channel_seq`)
+* and the frames it takes beyond the base protocol (`cancel_sql`). Named before
+* sign-in, so a socket that never signs in is served as one that does.
+*
+* - `heartbeat`: a `{ "type": "heartbeat" }` frame every `heartbeatMs`. A
+*   browser cannot send a WebSocket ping or see one, so a connection that went
+*   half-open — a NAT that forgot it, a laptop that slept — looks connected to
+*   it forever. With these, two missed beats tell it to redial.
+* - `channel_seq`: on a retained channel, the sender of a broadcast gets
+*   `{ "type": "broadcast_ack", "channel", "seq" }` where every other member
+*   gets the message. Its own messages then leave no hole in the sequence it
+*   watches, so a hole means a message it really missed — see
+*   `RealtimeChannel` in the SDK.
+* - `cancel_sql`: the server takes `CANCEL_SQL { requestId }`, which stops a
+*   console run (`EXECUTE_SQL`, `mode: "script"`) of the same socket. A client
+*   sends it only to a server whose `hello` listed it.
+*
+* @module
+*/
+/** The query parameter a client names its opt-ins in. */
+var SOCKET_OPT_IN_PARAM = "rebase_caps";
+/** Every behaviour this server can be asked for. */
+var SOCKET_OPT_INS = [
+	"heartbeat",
+	"channel_seq",
+	"cancel_sql"
+];
+function isSocketOptIn(name) {
+	return SOCKET_OPT_INS.includes(name);
+}
+/**
+* What the client that opened this connection asked for, from its request
+* URL: `undefined` when it named nothing (a client that predates this, which
+* is sent no `hello`), otherwise the names this server honours — possibly
+* none.
+*/
+function requestedOptIns(url) {
+	if (!url) return void 0;
+	const query = url.indexOf("?");
+	if (query === -1) return void 0;
+	const raw = new URLSearchParams(url.slice(query + 1)).get(SOCKET_OPT_IN_PARAM);
+	if (raw === null) return void 0;
+	return new Set(raw.split(",").map((name) => name.trim()).filter(isSocketOptIn));
+}
+/**
+* The `hello` frame for a client that asked for `optIns`. With `channel_seq`
+* it also names the socket's own id, the `senderId` its broadcasts carry in a
+* channel's history, so a client filling a hole from history can tell its own
+* messages (which it is never sent live) from the ones it missed.
+*/
+function helloFrame(optIns, heartbeatMs, clientId) {
+	return JSON.stringify({
+		type: "hello",
+		capabilities: [...optIns],
+		...optIns.has("heartbeat") ? { heartbeatMs } : {},
+		...optIns.has("channel_seq") ? { clientId } : {}
+	});
+}
+var HEARTBEAT_FRAME = JSON.stringify({ type: "heartbeat" });
+/**
+* Send a heartbeat every `intervalMs` to each socket `sockets()` lists. One
+* timer for the whole server, unref'd so it never holds the process open.
+*
+* @returns Stops it.
+*/
+function startHeartbeats(sockets, intervalMs) {
+	const timer = setInterval(() => {
+		for (const ws of sockets()) {
+			if (ws.readyState !== WebSocket.OPEN) continue;
+			try {
+				ws.send(HEARTBEAT_FRAME);
+			} catch {}
+		}
+	}, intervalMs);
+	unref(timer);
+	return () => clearInterval(timer);
+}
+//#endregion
+//#region src/websocket.ts
+var websocket_exports = /* @__PURE__ */ __exportAll({
+	ADMIN_PLANE_TYPES: () => ADMIN_PLANE_TYPES,
+	PUBLIC_TYPES: () => PUBLIC_TYPES,
+	SESSION_ENDED_CLOSE_CODE: () => SESSION_ENDED_CLOSE_CODE,
+	TOO_MANY_SOCKETS_CLOSE_CODE: () => TOO_MANY_SOCKETS_CLOSE_CODE,
+	createPostgresWebSocket: () => createPostgresWebSocket,
+	isSocketRealtimeService: () => isSocketRealtimeService,
+	socketRealtimeMissing: () => socketRealtimeMissing
+});
+/**
+* Narrow a bootstrapper's realtime provider to what the socket calls.
+*
+* The provider arrives typed as the engine-agnostic `RealtimeProvider`, which
+* declares none of the client-connection methods. Checked rather than cast, so
+* a provider missing one refuses at boot, naming it, instead of on a client's
+* first frame.
+*/
+function socketRealtimeMissing(provider) {
+	return [
+		"addClient",
+		"rescopeClient",
+		"handleClientMessage"
+	].filter((method) => !(method in provider) || typeof Reflect.get(provider, method) !== "function");
+}
+function isSocketRealtimeService(provider) {
+	return socketRealtimeMissing(provider).length === 0;
+}
+/** What a script run says besides its rows, which an `EXECUTE_SQL` answer carries as `result`. */
+function scriptDescription({ rows: _rows, ...description }) {
+	return description;
+}
+/**
+* The uid the service key authenticates as, here and through the built-in
+* auth adapter — which is how the socket tells that credential apart from a
+* person's session.
+*/
+var SERVICE_KEY_UID = "service";
+/** Maximum messages per client per window */
+var WS_RATE_LIMIT = 2e3;
+/** Rate limit window in milliseconds (60 seconds) */
+var WS_RATE_WINDOW_MS = 6e4;
+/**
+* Channel frames get their own budget, because they are a different workload.
+*
+* 2000/minute is 33/second, which is generous for queries and subscriptions and
+* an order of magnitude below what the documented channel idiom asks for: the
+* capacity note in `docs/backend/realtime.md` uses 60 fps cursor movement as
+* its worked example, and the presence idiom re-`track()`s on every move, so
+* one client sustaining that sends ~120 frames/second — 7200 a minute. Sharing
+* one counter meant the cursor stream ate the query budget and then froze for
+* the rest of the window.
+*
+* The number is sized to that documented workload and nothing more; it is not
+* a considered product limit (see `docs/channel-authorization.md`).
+*/
+var WS_CHANNEL_RATE_LIMIT = 7200;
+/**
+* Realtime frames that read the database as they arrive: a subscription's
+* first frame is a fetch and a count, run as the subscriber, and a history
+* request reads the channel's retained messages. Each is a data request by
+* another name, and counts in the caller's data bucket like a
+* `FETCH_COLLECTION` — past the socket's own allowance.
+*/
+var FETCHING_REALTIME_TYPES = /* @__PURE__ */ new Set([
+	"subscribe_collection",
+	"subscribe_one",
+	"channel_history"
+]);
+/**
+* How many fetching realtime frames one socket may send without counting them
+* in its caller's data bucket: at least as many as a socket may hold
+* subscriptions, so a reconnect that re-subscribes everything it held is
+* never refused, and never spends the budget the person's next request needs.
+* The default data bucket is 1,000 requests per 15 minutes, so counting a
+* reconnect against it would have refused most of one, or locked the person
+* out of the data API until the window turned.
+*/
+var SOCKET_FETCH_ALLOWANCE = 1e3;
+/**
+* How long a spent allowance takes to come back in full, in ms — the data
+* API's default window. A socket churning subscriptions gets its allowance
+* once, and then this much a quarter-hour; past that, every subscribe is a
+* request in its person's bucket, which their HTTP requests and other sockets
+* share.
+*/
+var SOCKET_FETCH_ALLOWANCE_REFILL_MS = 15 * 6e4;
+/**
+* The largest frame a socket that has not authenticated may send, in bytes.
+*
+* All such a socket can usefully say is `AUTHENTICATE` with a token — a few
+* KiB with custom claims — and everything else is answered `UNAUTHORIZED`.
+* Without this, each of those answers came after the whole frame was buffered,
+* stringified and parsed, up to the body limit: a handful of connections that
+* never signed in could hold the process's memory. A larger frame closes the
+* socket with 1009 before it is read.
+*/
+var MAX_UNAUTHENTICATED_FRAME_BYTES = 64 * 1024;
+/**
+* How often a socket that only listens has its identity re-read, in ms.
+*
+* A socket that sends frames is re-checked before each one, as an HTTP request
+* is; a socket that only receives pushes sends none, so without this a
+* subscription opened by an identity that has since signed out everywhere, been
+* demoted or deleted went on receiving rows as that identity for as long as the
+* connection lasted.
+*/
+var DEFAULT_IDENTITY_RECHECK_MS = 3e4;
+/**
+* How many auth-store lookups the sweep runs at once. It shares the pool with
+* every REST request — 20 connections by default — so it takes a few of them,
+* however many sockets are due: 5,000 sockets at ~0.3 ms a lookup is under
+* half a second of sweep, rather than a burst that held the whole pool.
+*/
+var IDENTITY_SWEEP_CONCURRENCY = 4;
+/**
+* Channel frames are re-checked at most this often, in ms. They are the
+* high-rate traffic (see `WS_CHANNEL_RATE_LIMIT`): a database read for every
+* cursor position would make realtime presence the busiest query a backend
+* runs, for a window no wider than this.
+*/
+var CHANNEL_RECHECK_MIN_MS = 1e3;
+/**
+* The close code for a socket whose identity ended: signed out, revoked,
+* demoted out of existence, deleted or expired. In the 4000–4999 range the
+* protocol leaves to applications. The SDK reconnects and authenticates with
+* whatever session it holds now — a refreshed token, or none.
+*/
+var SESSION_ENDED_CLOSE_CODE = 4001;
+/**
+* The close code for a socket refused because its user already holds
+* `REALTIME_MAX_SOCKETS_PER_USER` sockets on this server. The SDK reconnects
+* with backoff, so a tab refused this way gets in once another one closes.
+*/
+var TOO_MANY_SOCKETS_CLOSE_CODE = 4002;
+/**
+* When a JWT expires, in ms, or undefined for a credential that is not one
+* (an API key, the service key, an adapter's opaque token).
+*
+* Read without verifying, and only ever for a token that was verified a moment
+* ago by the same request: the signature is not in question, only the instant.
+*/
+function jwtExpiryMs(token) {
+	const parts = token.split(".");
+	if (parts.length !== 3) return void 0;
+	try {
+		const claims = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+		if (typeof claims !== "object" || claims === null || !("exp" in claims)) return void 0;
+		return typeof claims.exp === "number" ? claims.exp * 1e3 : void 0;
+	} catch {
+		return;
+	}
+}
+/** Everything about an identity that decides what its frames may do. */
+function identityFingerprint(user) {
+	return JSON.stringify([
+		user.uid,
+		[...user.roles].sort(),
+		user.isAdmin,
+		user.isAnonymous,
+		user.scopes ?? null,
+		user.claims ?? null,
+		user.apiKey ?? null
+	]);
+}
+/** Frames counted against the channel budget rather than the general one. */
+var CHANNEL_MESSAGE_TYPES = /* @__PURE__ */ new Set([
+	"join_channel",
+	"leave_channel",
+	"broadcast",
+	"presence_track",
+	"presence_untrack",
+	"presence_state",
+	"channel_history"
+]);
+/**
+* WebSocket message types on the admin plane, and the scope each needs.
+*
+* Exported so the test can READ it. A privileged verb added without a scope
+* check is what this list exists to make impossible: `PUBLIC_TYPES` below is
+* its counterpart, and a test asserts that every `case` this file handles
+* appears in exactly one of the two — so a verb added to neither fails rather
+* than defaulting to reachable.
+*
+* All of these run on the owner connection, outside RLS. `database:read`
+* covers the catalogue — including `FETCH_APPLICATION_ROLES`, which runs
+* `SELECT DISTINCT unnest(roles)` over the users table — and
+* `database:write` covers running SQL and creating or deleting branches.
+*/
+var ADMIN_PLANE_TYPES = /* @__PURE__ */ new Map([
+	["EXECUTE_SQL", "database:write"],
+	["CANCEL_SQL", "database:write"],
+	["CREATE_BRANCH", "database:write"],
+	["DELETE_BRANCH", "database:write"],
+	["FETCH_DATABASES", "database:read"],
+	["FETCH_ROLES", "database:read"],
+	["FETCH_APPLICATION_ROLES", "database:read"],
+	["FETCH_UNMAPPED_TABLES", "database:read"],
+	["FETCH_TABLE_METADATA", "database:read"],
+	["FETCH_CURRENT_DATABASE", "database:read"],
+	["LIST_BRANCHES", "database:read"]
+]);
+/**
+* The data scope each data verb needs, for a session whose credential narrows
+* it. A person's own session holds the whole data plane; RLS decides its rows.
+*/
+var DATA_VERB_SCOPES = /* @__PURE__ */ new Map([
+	["FETCH_COLLECTION", "data:read"],
+	["FETCH_ONE", "data:read"],
+	["COUNT", "data:read"],
+	["CHECK_UNIQUE_FIELD", "data:read"],
+	["subscribe_collection", "data:read"],
+	["subscribe_one", "data:read"],
+	["SAVE", "data:write"],
+	["DELETE", "data:delete"]
+]);
+/**
+* Message types deliberately reachable by a non-admin session.
+*
+* Data operations, gated per row by RLS and per request by the same write
+* checks the REST layer applies — not by this list. It exists so that "which
+* bucket is this verb in" is a question with an answer for every verb, and
+* adding one without answering it is a test failure.
+*/
+var PUBLIC_TYPES = /* @__PURE__ */ new Set([
+	"FETCH_COLLECTION",
+	"FETCH_ONE",
+	"COUNT",
+	"SAVE",
+	"DELETE",
+	"CHECK_UNIQUE_FIELD"
+]);
+/**
+* Refuse a path whose collection — its first segment, for a nested path — this
+* server does not have, with the answer REST gives (`NOT_FOUND`).
+*/
+function assertKnownCollection(registry, path) {
+	if (!registry || typeof path !== "string") return;
+	const root = path.split("/").find((segment) => segment !== "");
+	if (root !== void 0 && !registry.getCollectionByPath(root)) throw ApiError.notFound(`Unknown collection '${root}'.`);
+}
+/**
+* Recursively extract the deepest error message from an error's cause chain (e.g., Drizzle wrapping a PG error).
+*/
+function extractErrorMessage(error) {
+	if (!error) return "Unknown error";
+	if (error instanceof Error) {
+		if ("cause" in error && error.cause) return extractErrorMessage(error.cause);
+		return error.message;
+	}
+	if (typeof error === "object" && "message" in error && typeof error.message === "string") return error.message;
+	return String(error);
+}
+/**
+* Who a socket reads and writes as, for its request frames and its
+* subscriptions alike.
+*
+* One answer because there were two, and they disagreed about guests. The
+* subscriptions carried the session's `isAnonymous`; the request frames wrote
+* `false` for every signed-in session, so a guest read and wrote as an account
+* through `FETCH_*`, `SAVE` and `DELETE` while its subscriptions did not. And a
+* socket with no session was a guest on the request frames (`true`) but not on
+* its subscriptions or over REST: an unauthenticated caller is not a guest
+* session.
+*/
+function sessionAuthContext(session) {
+	if (!session?.user) return {
+		uid: ANONYMOUS_USER_ID,
+		roles: ["anon"],
+		isAnonymous: false
+	};
+	return {
+		uid: session.user.uid,
+		roles: session.user.roles ?? [],
+		isAnonymous: session.user.isAnonymous === true,
+		...session.user.claims ? { claims: session.user.claims } : {}
+	};
+}
+/**
+* Everything a session may do: its credential's scopes, or what its roles hold
+* in `model` — the backend's access model.
+*/
+function sessionScopes(session, model) {
+	if (!session?.user) return [];
+	return session.user.scopes ?? scopesForRoles(session.user.roles, model);
+}
+/**
+* The collection a data frame addresses, for a narrowed session's scope check.
+* A nested path (`authors/1/posts`) answers undefined: its target is a
+* relation's, not a slug on the wire, so only an unqualified scope covers it.
+*/
+function frameCollection(type, payload) {
+	if (typeof payload !== "object" || payload === null) return void 0;
+	let path = "path" in payload ? payload.path : void 0;
+	if (type === "DELETE" && "row" in payload && typeof payload.row === "object" && payload.row !== null && "path" in payload.row) path = payload.row.path;
+	if (typeof path !== "string" || path === "" || isNestedPath(path)) return void 0;
+	return path;
+}
+/**
+* A URL path with its trailing `/` dropped, so `/app` and `/app/` are one
+* path — and `/` stays `/`.
+*/
+function normalizeSocketPath(path) {
+	const trimmed = (path.startsWith("/") ? path : `/${path}`).replace(/\/+$/, "");
+	return trimmed === "" ? "/" : trimmed;
+}
+/** The path an upgrade request asks for, without its query. */
+function upgradePathOf(request) {
+	const url = request.url ?? "/";
+	const queryAt = url.indexOf("?");
+	return normalizeSocketPath(queryAt === -1 ? url : url.slice(0, queryAt));
+}
+/**
+* Answer an upgrade nobody will take with a plain HTTP 404 and close it, so
+* the client sees a refusal instead of a socket that never opens.
+*/
+function refuseUpgrade(socket) {
+	if (!socket.writable) {
+		socket.destroy();
+		return;
+	}
+	socket.once("finish", () => socket.destroy());
+	socket.end("HTTP/1.1 404 Not Found\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
+}
+/** A frame's size in bytes, however `ws` delivered it. */
+function frameBytes(data) {
+	if (Array.isArray(data)) return data.reduce((total, chunk) => total + chunk.length, 0);
+	return data.byteLength;
+}
+/**
+* Where a connection comes from, as the data API's rate limiter reads an
+* address: the upgrade request's headers (believed only as far as proxies are
+* declared) and the socket's own address.
+*/
+function connectionOrigin(request) {
+	return {
+		header: (name) => {
+			const value = request?.headers[name];
+			return Array.isArray(value) ? value.join(", ") : value;
+		},
+		socketAddress: request?.socket?.remoteAddress
+	};
+}
+/**
+* A request frame with its `filter` decoded by the codec every other door uses.
+*
+* REST, MCP and the in-process SDK read `where` through `deserializeFilter`,
+* so `{ title: ["foo", "bar"] }` is an implicit `in` and `["!!", "x"]` is
+* refused by name. The socket handed the frame's filter to the driver raw,
+* which read the first element as an operator: one filter, two meanings,
+* depending on the transport. A typed `[op, value]` tuple decodes to itself.
+*/
+function withDecodedFilter(request) {
+	if (!request?.filter) return request;
+	try {
+		return {
+			...request,
+			filter: deserializeFilter(request.filter)
+		};
+	} catch (e) {
+		if (e instanceof UnknownFilterOperatorError) throw ApiError.badRequest(e.message, e.code, e.details);
+		throw e;
+	}
+}
+/**
+* `options` carry the data API's limits, for the same rows reached through this door:
+* frames larger than its body limit close the socket with 1009 before they are
+* read, and every data frame counts in the caller's data-API bucket — the one
+* their HTTP requests count in — rather than only in a budget per connection,
+* which a caller multiplied by opening more.
+*/
+function createPostgresWebSocket(server, realtimeService, driver, authConfig, authAdapter, options) {
+	const clientSessions = /* @__PURE__ */ new Map();
+	/** The sockets that opted into heartbeats — see `socket-opt-ins.ts`. */
+	const heartbeatSockets = /* @__PURE__ */ new Set();
+	const heartbeatIntervalMs = options?.heartbeatIntervalMs ?? 3e4;
+	/** How many sockets one identity may hold here; unset is no ceiling. See `REALTIME_MAX_SOCKETS_PER_USER`. */
+	const maxSocketsPerUser = options?.maxSocketsPerUser;
+	const isProduction = process.env.NODE_ENV === "production";
+	/**
+	* Debug tracing for this socket.
+	*
+	* Through `logger.debug`, not `console.debug`. A bare console call sits
+	* outside the one level system, so `LOG_LEVEL=warn` — a line the scaffold's
+	* own `.env.example` ships — silenced every structured line in the process
+	* and left these ones printing; the deletion of the old `console.debug`
+	* override is what exposed that. It also skipped the redactor, and the
+	* extras these calls carry are rows.
+	*
+	* The production guard stays on top of the level gate rather than being
+	* replaced by it: these lines trace requests and their payloads, and
+	* `LOG_LEVEL=debug` on a deployment is not consent to put a user's row on
+	* stdout.
+	*/
+	const wsDebug = (message, ...extras) => {
+		if (isProduction) return;
+		if (extras.length === 0) logger.debug(message);
+		else logger.debug(message, { details: extras.length === 1 ? extras[0] : extras });
+	};
+	const maxPayload = options?.maxPayload ?? RUNTIME_DEFAULT_MAX_BODY_SIZE;
+	const wss = new WebSocketServer({
+		noServer: true,
+		maxPayload: maxPayload > 0 ? maxPayload : 0
+	});
+	wss.on("error", (err) => {
+		logger.error("❌ [WebSocket Server] Error", { error: err });
+	});
+	const socketPath = normalizeSocketPath(options?.path ?? "/");
+	const onUpgrade = (request, socket, head) => {
+		if (upgradePathOf(request) !== socketPath) {
+			if (server.listenerCount("upgrade") <= 1) refuseUpgrade(socket);
+			return;
+		}
+		wss.handleUpgrade(request, socket, head, (client) => wss.emit("connection", client, request));
+	};
+	if (typeof server.on === "function") {
+		server.on("upgrade", onUpgrade);
+		wss.on("close", () => server.off("upgrade", onUpgrade));
+	}
+	const requireAuth = !!authAdapter || resolveRequireAuth(authConfig);
+	const verifySessionToken = options?.verifyAccessToken ?? extractUserFromToken;
+	const accessModel = () => options?.accessModel ?? getAccessModel();
+	if (requireAuth && !authAdapter && !authConfig?.jwtSecret && !authConfig?.serviceKey) logger.warn("🔐 [WebSocket Server] Authentication is required but no adapter, jwtSecret or serviceKey is configured — no client can complete AUTH, so every realtime message will be refused with UNAUTHORIZED.");
+	/**
+	* Who a credential is, now: the same verification `AUTHENTICATE` runs, so
+	* re-asking it later answers what signing in would answer. A refusal is a
+	* value; a store that cannot answer throws.
+	*/
+	async function resolveCaller(token) {
+		if (token.startsWith("rk_")) {
+			const resolved = options?.resolveApiKey ? await options.resolveApiKey(token) : void 0;
+			if (!resolved || !("uid" in resolved)) return {
+				refused: resolved?.message ?? "API keys are not enabled on this server",
+				apiKey: true
+			};
+			return {
+				credential: "api-key",
+				user: {
+					uid: resolved.uid,
+					roles: resolved.roles,
+					isAdmin: hasAdminRole(resolved.roles),
+					isAnonymous: false,
+					scopes: resolved.scopes,
+					...resolved.apiKey ? { apiKey: {
+						id: resolved.apiKey.id,
+						rate_limit: resolved.apiKey.rate_limit
+					} } : {}
+				}
+			};
+		}
+		if (authAdapter) {
+			const adapterUser = authAdapter.verifyToken ? await authAdapter.verifyToken(token) : await authAdapter.verifyRequest(new Request("http://localhost/_ws_auth", { headers: { Authorization: `Bearer ${token}` } }));
+			if (!adapterUser) return { refused: "Invalid or expired token" };
+			return {
+				credential: adapterUser.uid === SERVICE_KEY_UID ? "service-key" : "session",
+				user: {
+					uid: adapterUser.uid,
+					roles: adapterUser.roles,
+					isAdmin: adapterUser.isAdmin,
+					isAnonymous: adapterUser.isAnonymous === true,
+					...adapterUser.claims ? { claims: adapterUser.claims } : {}
+				}
+			};
+		}
+		if (authConfig?.serviceKey && safeCompare(token, authConfig.serviceKey)) return {
+			credential: "service-key",
+			user: {
+				uid: SERVICE_KEY_UID,
+				roles: ["admin"],
+				isAdmin: true,
+				isAnonymous: false
+			}
+		};
+		const jwtPayload = await verifySessionToken(token);
+		if (!jwtPayload) return { refused: "Invalid or expired token" };
+		return {
+			credential: "session",
+			user: {
+				uid: jwtPayload.uid,
+				roles: jwtPayload.roles ?? [],
+				isAdmin: hasAdminRole(jwtPayload.roles ?? []),
+				isAnonymous: jwtPayload.isAnonymous === true,
+				claims: jwtPayload.claims
+			}
+		};
+	}
+	/**
+	* Who this socket runs as: its caller, or — when it asked to `impersonate`
+	* — the user it named, by the same decision the data API takes for
+	* `x-rebase-impersonate`. A refusal carries the code to answer with.
+	*
+	* `audit` is passed by `AUTHENTICATE` only: the re-check before every frame
+	* decides again without writing a security event each time.
+	*/
+	async function resolveIdentity(token, impersonate, audit) {
+		const caller = await resolveCaller(token);
+		if (!("user" in caller) || impersonate === void 0) return caller;
+		const decision = await decideImpersonation({
+			requestedUid: impersonate,
+			credential: caller.credential,
+			caller: caller.user,
+			resolveUser: authAdapter?.resolveUser ? authAdapter.resolveUser.bind(authAdapter) : void 0,
+			audit
+		});
+		if ("refused" in decision) return {
+			refused: decision.refused.message,
+			code: decision.refused.code
+		};
+		const target = decision.granted;
+		return { user: {
+			uid: target.uid,
+			roles: target.roles,
+			isAdmin: hasAdminRole(target.roles),
+			isAnonymous: target.isAnonymous === true,
+			...target.claims ? { claims: target.claims } : {},
+			impersonator: decision.impersonator
+		} };
+	}
+	/** Stop honouring the session at the instant its token expires. */
+	function scheduleExpiry(clientId, token) {
+		const session = clientSessions.get(clientId);
+		if (!session) return;
+		if (session.expiryTimer) clearTimeout(session.expiryTimer);
+		session.expiryTimer = void 0;
+		const expiresAt = jwtExpiryMs(token);
+		if (expiresAt === void 0) return;
+		const delay = Math.max(0, expiresAt - Date.now());
+		if (delay > 2147483647) return;
+		session.expiryTimer = setTimeout(() => {
+			if (clientSessions.get(clientId)?.credential === token) endSession(clientId, "TOKEN_EXPIRED", "The token this socket authenticated with has expired.");
+		}, delay);
+		session.expiryTimer.unref?.();
+	}
+	/**
+	* The identity this socket authenticated as is over: say so, forget it,
+	* and close. Closing rather than carrying on anonymously, because every
+	* subscription the socket holds was opened as that identity — the SDK
+	* reconnects, authenticates with whatever session it has now, and
+	* re-subscribes as that.
+	*/
+	function endSession(clientId, code, message) {
+		const session = clientSessions.get(clientId);
+		if (!session) return;
+		if (session.expiryTimer) clearTimeout(session.expiryTimer);
+		session.expiryTimer = void 0;
+		session.user = void 0;
+		session.credential = void 0;
+		session.authenticated = !requireAuth;
+		wsDebug(`[WS] ${clientId} session ended: ${code}`);
+		try {
+			session.ws.send(JSON.stringify({
+				type: "AUTH_ERROR",
+				payload: { error: {
+					code,
+					message
+				} }
+			}));
+		} catch {}
+		session.ws.close(SESSION_ENDED_CLOSE_CODE, message.slice(0, 120));
+	}
+	/**
+	* Is the identity this socket authenticated as still the one its
+	* credential names?
+	*
+	* Asked of the database, through the same verification as
+	* `AUTHENTICATE`, before each frame and by the sweep — never by an event
+	* one instance publishes to the others. A sign-out, a demotion or a
+	* deletion is written to the database by whichever instance served it;
+	* re-reading there is correct on every instance with nothing in between,
+	* where an event would reach only the instances a bus connects (and the
+	* bus is opt-in).
+	*
+	* - `"live"`: still honoured; roles or claims that changed are applied,
+	*   and the socket's subscriptions are re-scoped to them.
+	* - `"ended"`: refused — revoked, signed out, deleted, expired. The
+	*   socket is closed.
+	* - `"unavailable"`: the store could not answer. The frame is refused,
+	*   the session kept, and the next frame or sweep asks again.
+	*/
+	async function recheckIdentity(clientId, resolve = resolveIdentity) {
+		const session = clientSessions.get(clientId);
+		const credential = session?.credential;
+		if (!session?.user || !credential) return "live";
+		let outcome;
+		try {
+			outcome = await resolve(credential, session.impersonate);
+		} catch {
+			return "unavailable";
+		}
+		if (session.credential !== credential || !session.user) return session.user ? "live" : "ended";
+		session.checkedAt = Date.now();
+		if (!("user" in outcome)) {
+			if (outcome.code) endSession(clientId, outcome.code, outcome.refused);
+			else endSession(clientId, "SESSION_ENDED", "This session has ended: it was signed out, revoked, or its account changed. Authenticate again.");
+			return "ended";
+		}
+		if (identityFingerprint(outcome.user) !== identityFingerprint(session.user)) {
+			session.user = outcome.user;
+			await realtimeService.rescopeClient(clientId, sessionAuthContext(session));
+		}
+		return "live";
+	}
+	/** The per-frame check in flight on each socket, and what it asks. */
+	const frameChecks = /* @__PURE__ */ new Map();
+	/**
+	* {@link recheckIdentity} for a frame, shared by the frames of one socket
+	* that arrive while it is in flight.
+	*
+	* A client that reconnects after a deploy re-sends all its subscriptions
+	* at once, and each frame asked the auth store the same question at the
+	* same moment: a thousand clients with ten subscriptions were ten thousand
+	* lookups where a thousand answer. A frame that arrives while this
+	* socket's check of the same credential and impersonation target is under
+	* way waits for that answer instead. The answer is the flight's only:
+	* dropped as it settles, so the next frame asks afresh. What this trades
+	* is bounded by one lookup: a demotion that lands while the shared lookup
+	* runs is seen by the next frame rather than by these.
+	*/
+	function recheckIdentityForFrame(clientId) {
+		const session = clientSessions.get(clientId);
+		const credential = session?.credential;
+		if (!session || !credential) return recheckIdentity(clientId);
+		const inFlight = frameChecks.get(clientId);
+		if (inFlight && inFlight.credential === credential && inFlight.impersonate === session.impersonate) return inFlight.outcome;
+		const outcome = recheckIdentity(clientId).finally(() => {
+			if (frameChecks.get(clientId)?.outcome === outcome) frameChecks.delete(clientId);
+		});
+		frameChecks.set(clientId, {
+			credential,
+			impersonate: session.impersonate,
+			outcome
+		});
+		return outcome;
+	}
+	/**
+	* A socket's whole allowance of fetching realtime frames: the default, or
+	* the realtime service's subscription ceiling where a deployment raised
+	* it, so a full socket still re-subscribes without being charged.
+	*/
+	function fetchAllowanceCapacity() {
+		const ceiling = Reflect.get(realtimeService, "maxSubscriptionsPerSocket");
+		return typeof ceiling === "number" && Number.isFinite(ceiling) ? Math.max(SOCKET_FETCH_ALLOWANCE, ceiling) : SOCKET_FETCH_ALLOWANCE;
+	}
+	/**
+	* Take one fetching realtime frame from the socket's own allowance,
+	* topped up for the time since it was last asked. False when none is
+	* left: the frame then counts in the caller's data bucket.
+	*/
+	function spendFetchAllowance(clientId) {
+		const session = clientSessions.get(clientId);
+		if (!session) return false;
+		const now = Date.now();
+		const capacity = fetchAllowanceCapacity();
+		const refilled = Math.max(0, now - session.fetchAllowanceAt) * capacity / SOCKET_FETCH_ALLOWANCE_REFILL_MS;
+		session.fetchAllowance = Math.min(capacity, session.fetchAllowance + refilled);
+		session.fetchAllowanceAt = now;
+		if (session.fetchAllowance < 1) return false;
+		session.fetchAllowance -= 1;
+		return true;
+	}
+	const identityRecheckMs = Math.max(250, options?.identityRecheckIntervalMs ?? DEFAULT_IDENTITY_RECHECK_MS);
+	/**
+	* Re-check every socket that is due, asking the auth store once per
+	* question.
+	*
+	* Each socket used to be asked about on its own, all in the same tick: S
+	* listening sockets were S concurrent lookups on the pool REST shares,
+	* and a person with five tabs was five identical lookups of one token.
+	* Sockets are grouped by what they would ask — their credential and the
+	* user they impersonate — and each group asks once, at most
+	* {@link IDENTITY_SWEEP_CONCURRENCY} groups at a time.
+	*
+	* The answer is the group's alone, made when the group's turn comes and
+	* dropped when it is done; nothing is kept from one sweep to the next, so
+	* a credential revoked after a sweep is asked about afresh, and refused,
+	* by the next one. A socket that authenticated again while its group
+	* waited is asked about the credential it holds now — see `answerFor`.
+	*/
+	async function sweepIdentities() {
+		const now = Date.now();
+		const groups = /* @__PURE__ */ new Map();
+		for (const [id, session] of clientSessions) {
+			if (!session.user || !session.credential || now - session.checkedAt < identityRecheckMs / 2) continue;
+			const key = JSON.stringify([session.credential, session.impersonate ?? null]);
+			const group = groups.get(key);
+			if (group) group.clientIds.push(id);
+			else groups.set(key, {
+				credential: session.credential,
+				impersonate: session.impersonate,
+				clientIds: [id]
+			});
+		}
+		const queue = [...groups.values()];
+		const work = async () => {
+			for (let group = queue.shift(); group; group = queue.shift()) {
+				let answer;
+				const answerFor = (token, impersonate) => {
+					if (token !== group.credential || impersonate !== group.impersonate) return resolveIdentity(token, impersonate);
+					answer ??= resolveIdentity(token, impersonate);
+					return answer;
+				};
+				for (const id of group.clientIds) await recheckIdentity(id, answerFor).catch(() => void 0);
+			}
+		};
+		await Promise.all(Array.from({ length: Math.min(IDENTITY_SWEEP_CONCURRENCY, queue.length) }, work));
+	}
+	let sweeping = false;
+	const identitySweep = setInterval(() => {
+		if (sweeping) return;
+		sweeping = true;
+		sweepIdentities().catch(() => void 0).finally(() => {
+			sweeping = false;
+		});
+	}, identityRecheckMs);
+	identitySweep.unref?.();
+	const stopSweep = () => clearInterval(identitySweep);
+	wss.on("close", stopSweep);
+	if (typeof server.on === "function") server.on("close", stopSweep);
+	wss.on("connection", (ws, request) => {
+		const clientId = `client_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+		const origin = connectionOrigin(request);
+		wsDebug(`WebSocket client connected: ${clientId}`);
+		const optIns = requestedOptIns(request?.url);
+		if (optIns) {
+			ws.send(helloFrame(optIns, heartbeatIntervalMs, clientId));
+			realtimeService.setClientOptIns?.(clientId, optIns);
+			if (optIns.has("heartbeat")) {
+				heartbeatSockets.add(ws);
+				ws.once("close", () => heartbeatSockets.delete(ws));
+			}
+		}
+		clientSessions.set(clientId, {
+			ws,
+			authenticated: !requireAuth,
+			checkedAt: Date.now(),
+			messageCount: 0,
+			messageWindowStart: Date.now(),
+			channelMessageCount: 0,
+			channelWindowStart: Date.now(),
+			fetchAllowance: fetchAllowanceCapacity(),
+			fetchAllowanceAt: Date.now()
+		});
+		realtimeService.addClient(clientId, ws);
+		const sqlRuns = /* @__PURE__ */ new Map();
+		ws.on("close", () => {
+			wsDebug(`WebSocket client disconnected: ${clientId}`);
+			const session = clientSessions.get(clientId);
+			if (session?.expiryTimer) clearTimeout(session.expiryTimer);
+			clientSessions.delete(clientId);
+		});
+		ws.on("error", (error) => {
+			wsDebug(`WebSocket client ${clientId} error: ${error.message}`);
+		});
+		ws.on("message", async (message) => {
+			if (terminateIfBacklogged(ws, clientId)) return;
+			let requestId;
+			try {
+				if (!clientSessions.get(clientId)?.authenticated && frameBytes(message) > MAX_UNAUTHENTICATED_FRAME_BYTES) {
+					ws.close(1009, "Authenticate before sending anything larger than a token.");
+					return;
+				}
+				const { type, payload, requestId: reqId } = JSON.parse(message.toString());
+				requestId = reqId;
+				wsDebug(`[WS] ${clientId} → ${type}`, requestId ? `(${requestId})` : "");
+				const sendError = (errType, code, msg) => {
+					const channel = CHANNEL_MESSAGE_TYPES.has(type) ? payload?.channel : void 0;
+					ws.send(JSON.stringify({
+						type: errType,
+						requestId,
+						...typeof channel === "string" && { channel },
+						payload: {
+							error: {
+								message: msg,
+								code
+							},
+							...typeof channel === "string" && { channel }
+						}
+					}));
+				};
+				{
+					const session = clientSessions.get(clientId);
+					if (session) {
+						const now = Date.now();
+						if (CHANNEL_MESSAGE_TYPES.has(type)) {
+							if (now - session.channelWindowStart > WS_RATE_WINDOW_MS) {
+								session.channelMessageCount = 0;
+								session.channelWindowStart = now;
+							}
+							session.channelMessageCount++;
+							if (session.channelMessageCount > WS_CHANNEL_RATE_LIMIT) {
+								sendError("ERROR", "RATE_LIMITED", "Too many channel messages. Please slow down.");
+								return;
+							}
+						} else {
+							if (now - session.messageWindowStart > WS_RATE_WINDOW_MS) {
+								session.messageCount = 0;
+								session.messageWindowStart = now;
+							}
+							session.messageCount++;
+							if (session.messageCount > WS_RATE_LIMIT) {
+								sendError("ERROR", "RATE_LIMITED", "Too many requests. Please slow down.");
+								return;
+							}
+						}
+					}
+				}
+				if (type === "AUTHENTICATE") {
+					const { token, impersonate } = payload || {};
+					if (!token) {
+						sendError("AUTH_ERROR", "INVALID_INPUT", "Token is required");
+						return;
+					}
+					if (impersonate !== void 0 && typeof impersonate !== "string") {
+						sendError("AUTH_ERROR", "INVALID_INPUT", "impersonate must be the uid of the user to act as");
+						return;
+					}
+					let resolved;
+					try {
+						resolved = await resolveIdentity(token, impersonate, impersonate === void 0 ? void 0 : {
+							door: "socket",
+							clientId
+						});
+					} catch (error) {
+						const answer = impersonate === void 0 ? void 0 : declaredErrorAnswer(error);
+						if (answer) {
+							sendError("AUTH_ERROR", answer.code, answer.message);
+							return;
+						}
+						if (token.startsWith("rk_") || !authAdapter) throw error;
+						resolved = { refused: "Invalid or expired token" };
+					}
+					if ("refused" in resolved && (resolved.apiKey || resolved.code)) {
+						sendError("AUTH_ERROR", resolved.code ?? "INVALID_TOKEN", resolved.refused);
+						return;
+					}
+					const verifiedUser = "user" in resolved ? resolved.user : null;
+					if (verifiedUser) {
+						const session = clientSessions.get(clientId);
+						if (maxSocketsPerUser !== void 0 && session) {
+							let held = 0;
+							for (const other of clientSessions.values()) if (other !== session && other.user?.uid === verifiedUser.uid) held++;
+							if (held >= maxSocketsPerUser) {
+								logger.warn(`[WebSocket Server] Refused a socket for ${verifiedUser.uid}: ${held} already open, ceiling ${maxSocketsPerUser}`);
+								sendError("ERROR", "TOO_MANY_SOCKETS", `This user already has ${held} realtime connections open on this server, the most it allows (REALTIME_MAX_SOCKETS_PER_USER). Close another tab or client and try again.`);
+								ws.close(TOO_MANY_SOCKETS_CLOSE_CODE, "Too many realtime connections for this user");
+								return;
+							}
+						}
+						if (session) {
+							session.user = verifiedUser;
+							session.authenticated = true;
+							session.credential = token;
+							session.impersonate = impersonate;
+							session.checkedAt = Date.now();
+							scheduleExpiry(clientId, token);
+							await realtimeService.rescopeClient(clientId, sessionAuthContext(session));
+						}
+						wsDebug(`[WS] replying AUTH_SUCCESS for requestId ${requestId}`);
+						ws.send(JSON.stringify({
+							type: "AUTH_SUCCESS",
+							requestId,
+							payload: {
+								uid: verifiedUser.uid,
+								roles: verifiedUser.roles
+							}
+						}));
+						wsDebug(`🔐 [WebSocket Server] Client ${clientId} authenticated as ${verifiedUser.uid}`);
+					} else {
+						wsDebug(`[WS] replying AUTH_ERROR for requestId ${requestId} (invalid token)`);
+						sendError("AUTH_ERROR", "INVALID_TOKEN", "Invalid or expired token");
+					}
+					return;
+				}
+				{
+					const session = clientSessions.get(clientId);
+					if (session?.user && session.credential && Date.now() - session.checkedAt >= (CHANNEL_MESSAGE_TYPES.has(type) ? CHANNEL_RECHECK_MIN_MS : 0)) {
+						const outcome = await recheckIdentityForFrame(clientId);
+						if (outcome === "ended") return;
+						if (outcome === "unavailable") {
+							sendError("ERROR", "ROLE_LOOKUP_FAILED", "Could not verify your permissions. Please try again.");
+							return;
+						}
+					}
+				}
+				if (requireAuth) {
+					if (!clientSessions.get(clientId)?.authenticated) {
+						sendError("ERROR", "UNAUTHORIZED", "Authentication required");
+						return;
+					}
+				}
+				const adminScope = ADMIN_PLANE_TYPES.get(type);
+				if (adminScope) {
+					if (!scopeGrants(sessionScopes(clientSessions.get(clientId), accessModel()), adminScope)) {
+						sendError("ERROR", "SCOPE_MISSING", `This operation needs the "${adminScope}" scope`);
+						return;
+					}
+				}
+				const narrowedScopes = clientSessions.get(clientId)?.user?.scopes;
+				if (narrowedScopes) {
+					const dataScope = DATA_VERB_SCOPES.get(type);
+					if (dataScope) {
+						const collection = frameCollection(type, payload);
+						if (!scopeGrants(narrowedScopes, dataScope, collection)) {
+							sendError("ERROR", "SCOPE_MISSING", `This API key does not hold the "${collection ? `${dataScope}:${collection}` : dataScope}" scope`);
+							return;
+						}
+					} else if (CHANNEL_MESSAGE_TYPES.has(type)) {
+						sendError("ERROR", "SCOPE_MISSING", "An API key cannot use channels");
+						return;
+					}
+				}
+				if (options?.dataRateLimit && (PUBLIC_TYPES.has(type) || FETCHING_REALTIME_TYPES.has(type) && !spendFetchAllowance(clientId))) {
+					const decision = await options.dataRateLimit({
+						...origin,
+						uid: clientSessions.get(clientId)?.user?.uid,
+						apiKey: clientSessions.get(clientId)?.user?.apiKey
+					});
+					if (decision && !decision.allowed) {
+						sendError("ERROR", "RATE_LIMITED", "Too many requests, please try again later.");
+						return;
+					}
+				}
+				/**
+				* Apply the REST layer's write checks to a socket payload.
+				*
+				* Silent when the path names no registered collection: the
+				* driver decides what a path means, and refusing here would
+				* turn "unknown collection" into a validation error.
+				*/
+				const assertWriteRequest = (path, values, status) => {
+					if (!path || !values || typeof values !== "object") return;
+					const collection = driver.registry?.getCollectionByPath(path);
+					if (!collection) return;
+					assertWriteRequestValid(values, collection, {
+						viewer: { roles: clientSessions.get(clientId)?.user?.roles ?? ["anon"] },
+						status
+					});
+					assertFieldOpsValid(values, collection);
+				};
+				/**
+				* Apply the REST layer's read check to a socket request: no
+				* filter, sort, projection or uniqueness probe over a field
+				* this caller may not read. The strip keeps the value off the
+				* wire; without this a `COUNT` still answers whether a hidden
+				* value matches a pattern, one character at a time.
+				*
+				* Same viewer as `assertWriteRequest`, and silent in the same
+				* case: a path that names no registered collection is the
+				* driver's to answer.
+				*/
+				const assertReadRequest = (path, request) => {
+					if (!path) return;
+					let collection;
+					try {
+						collection = driver.registry?.getCollectionByPath(path);
+					} catch {
+						return;
+					}
+					if (!collection) return;
+					const session = clientSessions.get(clientId);
+					assertReadRequestReadable(request, collection, { roles: session?.user?.roles ?? ["anon"] });
+				};
+				/**
+				* Refuse a write through a nested path that sets a relation
+				* this caller may not write — the rule REST's nested routes
+				* apply, from the same function. The body is checked by
+				* `assertWriteRequest`; this is what the address writes.
+				*
+				* Silent for a root path, and for a nested one the registry
+				* cannot walk: the driver refuses that with its own message.
+				*/
+				const assertNestedWrite = (path, kind) => {
+					if (typeof path !== "string" || !isNestedPath(path) || !driver.registry) return;
+					let hop;
+					try {
+						hop = resolveNestedPath(path, driver.registry);
+					} catch {
+						return;
+					}
+					if (!hop) return;
+					const session = clientSessions.get(clientId);
+					assertNestedWriteAllowed(hop, kind, path, { roles: session?.user?.roles ?? ["anon"] });
+				};
+				/** The auth collection at `path`, or `undefined` for any other. */
+				const authCollectionAt = (path) => {
+					if (typeof path !== "string") return void 0;
+					let collection;
+					try {
+						collection = driver.registry?.getCollectionByPath(path);
+					} catch {
+						return;
+					}
+					const auth = collection?.auth;
+					return auth === true || !!auth && typeof auth === "object" && auth.enabled === true ? collection : void 0;
+				};
+				/**
+				* The auth collection's rows are the users, so a write to one
+				* is user administration — the auth adapter's to check, as it
+				* is on the REST routes and `/admin/users`. `undefined` for any
+				* other collection, or an adapter with nothing to say.
+				*/
+				const userAdminFor = (path) => authAdapter && authCollectionAt(path) ? authAdapter : void 0;
+				/**
+				* An upsert's options, under the rules `POST /api/data`
+				* applies to `?on_conflict=`: refused on a nested path,
+				* whose insert branch stamps the parent's key into the
+				* DO UPDATE and so moves the row it matched under this
+				* parent; and a target that is a declared unique key of
+				* the registry's collection, or a 400 naming the ones
+				* there are rather than Postgres's 42P10.
+				*/
+				const upsertOptions = (request) => {
+					if (request.upsert !== true) return {};
+					if (typeof request.path === "string" && isNestedPath(request.path)) throw ApiError.badRequest("An upsert is not accepted on a nested path: a row it matched would be moved under this parent. Send the upsert to the collection directly.", "INVALID_CONFLICT_TARGET");
+					const collection = driver.registry?.getCollectionByPath(request.path);
+					const onConflict = collection ? resolveConflictTarget(request.onConflict, collection, { where: "`onConflict`" }) : void 0;
+					return {
+						upsert: true,
+						...onConflict && { onConflict }
+					};
+				};
+				const getScopedDelegate = async () => {
+					if (typeof driver.withAuth === "function") try {
+						const who = sessionAuthContext(clientSessions.get(clientId));
+						const userForAuth = {
+							uid: who.uid,
+							displayName: null,
+							email: null,
+							photoURL: null,
+							providerId: "websocket",
+							isAnonymous: who.isAnonymous === true,
+							roles: who.roles,
+							...who.claims ? { claims: who.claims } : {}
+						};
+						return await driver.withAuth(userForAuth);
+					} catch (e) {
+						logger.error("Failed to create RLS scoped delegate for WS request", { error: e });
+						throw new Error("Internal authentication error");
+					}
+					return driver;
+				};
+				if (PUBLIC_TYPES.has(type)) assertKnownCollection(driver.registry, type === "DELETE" ? payload?.row?.path : payload?.path);
+				switch (type) {
+					case "FETCH_COLLECTION":
+						{
+							wsDebug("📋 [WebSocket Server] Processing FETCH_COLLECTION request");
+							const request = withDecodedFilter(payload);
+							assertReadRequest(request.path, request);
+							const rows = await (await getScopedDelegate()).fetchCollection({
+								...request,
+								limit: resolveClientListLimit(request.limit, { vectorSearch: !!request.vectorSearch })
+							});
+							wsDebug("📋 [WebSocket Server] FETCH_COLLECTION result - rows count:", rows.length);
+							const response = {
+								type: "FETCH_COLLECTION_SUCCESS",
+								payload: { rows },
+								requestId
+							};
+							wsDebug("📋 [WebSocket Server] Sending FETCH_COLLECTION_SUCCESS response");
+							ws.send(JSON.stringify(response));
+						}
+						break;
+					case "FETCH_ONE":
+						{
+							wsDebug("📄 [WebSocket Server] Processing FETCH_ENTITY request");
+							const request = payload;
+							const row = await (await getScopedDelegate()).fetchOne(request);
+							wsDebug("📄 [WebSocket Server] FETCH_ENTITY result:", row);
+							const response = {
+								type: "FETCH_ONE_SUCCESS",
+								payload: { row: row ?? null },
+								requestId
+							};
+							wsDebug("📄 [WebSocket Server] Sending FETCH_ENTITY_SUCCESS response");
+							ws.send(JSON.stringify(response));
+						}
+						break;
+					case "SAVE":
+						{
+							wsDebug("💾 [WebSocket Server] Processing SAVE_ENTITY request");
+							const request = payload;
+							wsDebug("💾 [WebSocket Server] Saving row with request:", inspect(request, {
+								depth: null,
+								colors: true
+							}));
+							const upsertedUsers = request.upsert === true ? authCollectionAt(request.path) : void 0;
+							if (upsertedUsers) assertNoUserUpsert(authAdapter, upsertedUsers);
+							const usersCollection = request.status !== "existing" && request.upsert !== true && authAdapter?.prepareUserCreation ? authCollectionAt(request.path) : void 0;
+							const caller = { roles: clientSessions.get(clientId)?.user?.roles ?? ["anon"] };
+							if (usersCollection) {
+								const body = request.values ?? {};
+								assertUserCreationBodyValid(authAdapter, usersCollection, body, caller);
+								assertNoFieldOpsOnCreate(body, "A create", usersCollection);
+							} else assertWriteRequest(request.path, request.values, request.status);
+							assertNestedWrite(request.path, request.id === void 0 || request.status !== "existing" ? "create" : "update");
+							const delegate = await getScopedDelegate();
+							const userAdmin = request.status === "existing" && request.id !== void 0 ? userAdminFor(request.path) : void 0;
+							const [values] = userAdmin?.prepareUserUpdates ? await userAdmin.prepareUserUpdates([{
+								uid: String(request.id),
+								values: request.values
+							}]) : [request.values];
+							const write = (toWrite) => delegate.save({
+								path: request.path,
+								...request.id !== void 0 && { id: request.id },
+								values: toWrite,
+								status: request.status,
+								...upsertOptions(request)
+							});
+							const created = usersCollection ? await createUserThroughAuthCollection(authAdapter, usersCollection, values ?? {}, caller, write) : void 0;
+							const row = created ? {
+								...created.row,
+								...created.delivery
+							} : await write(values);
+							wsDebug("💾 [WebSocket Server] SAVE_ENTITY result:", inspect(row, {
+								depth: null,
+								colors: true
+							}));
+							const response = {
+								type: "SAVE_SUCCESS",
+								payload: { row },
+								requestId
+							};
+							wsDebug("💾 [WebSocket Server] Sending SAVE_ENTITY_SUCCESS response");
+							ws.send(JSON.stringify(response));
+						}
+						break;
+					case "DELETE":
+						{
+							wsDebug("🗑️ [WebSocket Server] Processing DELETE_ENTITY request");
+							const request = payload;
+							wsDebug("🗑️ [WebSocket Server] Deleting row:", request.row);
+							assertNestedWrite(request.row?.path, "unlink");
+							const delegate = await getScopedDelegate();
+							const userAdmin = userAdminFor(request.row?.path);
+							const uids = [String(request.row.id)];
+							await userAdmin?.prepareUserDeletions?.(uids);
+							await delegate.delete({
+								row: {
+									id: request.row.id,
+									path: request.row.path
+								},
+								hard: request.hard
+							});
+							await userAdmin?.finalizeUserDeletions?.(uids);
+							wsDebug("🗑️ [WebSocket Server] DELETE_ENTITY completed successfully");
+							const response = {
+								type: "DELETE_SUCCESS",
+								payload: { success: true },
+								requestId
+							};
+							wsDebug("🗑️ [WebSocket Server] Sending DELETE_ENTITY_SUCCESS response");
+							ws.send(JSON.stringify(response));
+						}
+						break;
+					case "CHECK_UNIQUE_FIELD":
+						{
+							wsDebug("🔍 [WebSocket Server] Processing CHECK_UNIQUE_FIELD request");
+							const { path, name, value, id, collection } = payload;
+							if (typeof name === "string") assertReadRequest(path, { filter: { [name]: ["==", value] } });
+							const isUnique = await (await getScopedDelegate()).checkUniqueField(path, name, value, id, collection);
+							wsDebug("🔍 [WebSocket Server] CHECK_UNIQUE_FIELD result:", isUnique);
+							const response = {
+								type: "CHECK_UNIQUE_FIELD_SUCCESS",
+								payload: { isUnique },
+								requestId
+							};
+							wsDebug("🔍 [WebSocket Server] Sending CHECK_UNIQUE_FIELD_SUCCESS response");
+							ws.send(JSON.stringify(response));
+						}
+						break;
+					case "COUNT":
+						{
+							const request = withDecodedFilter(payload);
+							assertReadRequest(request.path, request);
+							const response = {
+								type: "COUNT_SUCCESS",
+								payload: { count: await (await getScopedDelegate()).count(request) },
+								requestId
+							};
+							ws.send(JSON.stringify(response));
+						}
+						break;
+					case "EXECUTE_SQL":
+						{
+							const { sql, options, mode } = payload;
+							const cancel = mode === "script" && typeof requestId === "string" && !sqlRuns.has(requestId) ? new AbortController() : void 0;
+							if (cancel && requestId) sqlRuns.set(requestId, cancel);
+							try {
+								const admin = (await getScopedDelegate()).admin;
+								if (!isSQLAdmin(admin)) {
+									sendError("ERROR", "NOT_SUPPORTED", "SQL execution is not available for this driver.");
+									break;
+								}
+								const script = mode === "script" && typeof admin.runSqlScript === "function" ? await admin.runSqlScript(String(sql), {
+									database: typeof options?.database === "string" ? options.database : void 0,
+									role: typeof options?.role === "string" ? options.role : void 0,
+									...cancel ? { signal: cancel.signal } : {}
+								}) : void 0;
+								const result = script ? script.rows : await admin.executeSql(sql, {
+									...options,
+									isolateSession: true,
+									maxResultBytes: SQL_RESULT_BYTE_BUDGET
+								});
+								const ranAs = typeof options?.role === "string" && options.role ? await sqlRoleRanAs(admin, options.role, typeof options?.database === "string" ? options.database : void 0) : void 0;
+								if (process.env.NODE_ENV !== "production") wsDebug(`⚡ [WebSocket Server] SQL executed. Returned ${Array.isArray(result) ? result.length : "non-array"} rows.`);
+								const auditSession = clientSessions.get(clientId);
+								logger.info("[SQL Audit] WebSocket SQL execution", {
+									sql: redactSqlLiterals(String(sql)).substring(0, 500),
+									database: options?.database,
+									role: options?.role,
+									effectiveRole: effectiveSqlRole(options?.role),
+									paramCount: Array.isArray(options?.params) ? options.params.length : 0,
+									resultRows: Array.isArray(result) ? result.length : "unknown",
+									uid: auditSession?.user?.uid ?? "unknown",
+									roles: auditSession?.user?.roles ?? [],
+									isAdmin: auditSession?.user?.isAdmin ?? false,
+									...auditSession?.user?.impersonator ? { impersonatedBy: auditSession.user.impersonator } : {},
+									requestId
+								});
+								const response = {
+									type: "EXECUTE_SQL_SUCCESS",
+									payload: {
+										...script ? {
+											...scriptDescription(script),
+											result
+										} : { result },
+										...ranAs ? { effectiveRole: ranAs } : {}
+									},
+									requestId
+								};
+								ws.send(JSON.stringify(response));
+							} catch (sqlError) {
+								if (sqlError instanceof SqlResultTooLargeError) {
+									ws.send(JSON.stringify({
+										type: "ERROR",
+										requestId,
+										payload: { error: {
+											message: sqlError.message,
+											code: "RESULT_TOO_LARGE"
+										} }
+									}));
+									break;
+								}
+								sendError("ERROR", "SQL_ERROR", extractErrorMessage(sqlError));
+							} finally {
+								if (cancel && requestId && sqlRuns.get(requestId) === cancel) sqlRuns.delete(requestId);
+							}
+						}
+						break;
+					case "CANCEL_SQL":
+						{
+							const target = payload?.requestId;
+							const run = typeof target === "string" ? sqlRuns.get(target) : void 0;
+							run?.abort();
+							ws.send(JSON.stringify({
+								type: "CANCEL_SQL_SUCCESS",
+								requestId,
+								payload: { cancelled: run !== void 0 }
+							}));
+						}
+						break;
+					case "FETCH_DATABASES":
+						{
+							wsDebug("📚 [WebSocket Server] Processing FETCH_DATABASES request");
+							const admin = (await getScopedDelegate()).admin;
+							let databases = [];
+							if (isSQLAdmin(admin) && admin.fetchAvailableDatabases) databases = await admin.fetchAvailableDatabases();
+							wsDebug(`📚 [WebSocket Server] Fetched ${databases.length} databases.`);
+							const response = {
+								type: "FETCH_DATABASES_SUCCESS",
+								payload: { databases },
+								requestId
+							};
+							ws.send(JSON.stringify(response));
+						}
+						break;
+					case "FETCH_ROLES":
+						{
+							wsDebug("👤 [WebSocket Server] Processing FETCH_ROLES request");
+							const admin = (await getScopedDelegate()).admin;
+							let roles = [];
+							if (isSQLAdmin(admin) && admin.fetchAvailableRoles) roles = await admin.fetchAvailableRoles();
+							wsDebug(`👤 [WebSocket Server] Fetched ${roles.length} roles.`);
+							const response = {
+								type: "FETCH_ROLES_SUCCESS",
+								payload: { roles },
+								requestId
+							};
+							ws.send(JSON.stringify(response));
+						}
+						break;
+					case "FETCH_APPLICATION_ROLES":
+						{
+							wsDebug("👤 [WebSocket Server] Processing FETCH_APPLICATION_ROLES request");
+							const admin = (await getScopedDelegate()).admin;
+							let roles = [];
+							if (isSQLAdmin(admin) && admin.fetchApplicationRoles) roles = await admin.fetchApplicationRoles();
+							wsDebug(`👤 [WebSocket Server] Fetched ${roles.length} application roles.`);
+							const response = {
+								type: "FETCH_APPLICATION_ROLES_SUCCESS",
+								payload: { roles },
+								requestId
+							};
+							ws.send(JSON.stringify(response));
+						}
+						break;
+					case "FETCH_CURRENT_DATABASE":
+						{
+							wsDebug("📚 [WebSocket Server] Processing FETCH_CURRENT_DATABASE request");
+							const admin = (await getScopedDelegate()).admin;
+							let database = void 0;
+							if (isSQLAdmin(admin) && admin.fetchCurrentDatabase) database = await admin.fetchCurrentDatabase();
+							const response = {
+								type: "FETCH_CURRENT_DATABASE_SUCCESS",
+								payload: { database },
+								requestId
+							};
+							ws.send(JSON.stringify(response));
+						}
+						break;
+					case "FETCH_UNMAPPED_TABLES":
+						{
+							wsDebug("📋 [WebSocket Server] Processing FETCH_UNMAPPED_TABLES request");
+							const admin = (await getScopedDelegate()).admin;
+							let tables = [];
+							if (isSchemaAdmin(admin) && admin.fetchUnmappedTables) tables = await admin.fetchUnmappedTables(payload?.mappedPaths);
+							wsDebug(`📋 [WebSocket Server] Fetched ${tables.length} unmapped tables.`);
+							const response = {
+								type: "FETCH_UNMAPPED_TABLES_SUCCESS",
+								payload: { tables },
+								requestId
+							};
+							ws.send(JSON.stringify(response));
+						}
+						break;
+					case "FETCH_TABLE_METADATA":
+						{
+							wsDebug("📋 [WebSocket Server] Processing FETCH_TABLE_METADATA request");
+							const { tableName } = payload;
+							const admin = (await getScopedDelegate()).admin;
+							let metadata;
+							if (isSchemaAdmin(admin) && admin.fetchTableMetadata) metadata = await admin.fetchTableMetadata(tableName);
+							wsDebug(`📋 [WebSocket Server] Fetched metadata for table '${tableName}'. (${metadata?.columns?.length ?? 0} columns)`);
+							const response = {
+								type: "FETCH_TABLE_METADATA_SUCCESS",
+								payload: { metadata },
+								requestId
+							};
+							ws.send(JSON.stringify(response));
+						}
+						break;
+					case "CREATE_BRANCH":
+						{
+							wsDebug("🌿 [WebSocket Server] Processing CREATE_BRANCH request");
+							const { name, options } = payload;
+							const delegate = await getScopedDelegate();
+							if (!delegate.admin?.createBranch) {
+								sendError("ERROR", "NOT_SUPPORTED", "Database branching is not available. Configure adminConnectionString.");
+								break;
+							}
+							const branch = await delegate.admin.createBranch(name, options);
+							wsDebug(`🌿 [WebSocket Server] Branch created: ${branch.name}`);
+							const response = {
+								type: "CREATE_BRANCH_SUCCESS",
+								payload: { branch },
+								requestId
+							};
+							ws.send(JSON.stringify(response));
+						}
+						break;
+					case "DELETE_BRANCH":
+						{
+							wsDebug("🗑️ [WebSocket Server] Processing DELETE_BRANCH request");
+							const { name: branchName } = payload;
+							const delegate = await getScopedDelegate();
+							if (!delegate.admin?.deleteBranch) {
+								sendError("ERROR", "NOT_SUPPORTED", "Database branching is not available.");
+								break;
+							}
+							await delegate.admin.deleteBranch(branchName);
+							wsDebug(`🗑️ [WebSocket Server] Branch deleted: ${branchName}`);
+							const response = {
+								type: "DELETE_BRANCH_SUCCESS",
+								payload: { success: true },
+								requestId
+							};
+							ws.send(JSON.stringify(response));
+						}
+						break;
+					case "LIST_BRANCHES":
+						{
+							wsDebug("🌿 [WebSocket Server] Processing LIST_BRANCHES request");
+							const delegate = await getScopedDelegate();
+							let branches = [];
+							if (delegate.admin?.listBranches) branches = await delegate.admin.listBranches();
+							wsDebug(`🌿 [WebSocket Server] Listed ${branches.length} branches.`);
+							const response = {
+								type: "LIST_BRANCHES_SUCCESS",
+								payload: { branches },
+								requestId
+							};
+							ws.send(JSON.stringify(response));
+						}
+						break;
+					case "subscribe_collection":
+					case "subscribe_one":
+					case "unsubscribe":
+					case "join_channel":
+					case "leave_channel":
+					case "broadcast":
+					case "presence_track":
+					case "presence_untrack":
+					case "presence_state":
+					case "channel_history": {
+						wsDebug("🔄 [WebSocket Server] Routing realtime message to RealtimeService:", type);
+						const authContext = sessionAuthContext(clientSessions.get(clientId));
+						await realtimeService.handleClientMessage(clientId, {
+							type,
+							payload,
+							subscriptionId: payload?.subscriptionId
+						}, authContext);
+						break;
+					}
+					default:
+						logger.warn("[WebSocket Server] Unknown message type", { detail: type });
+						throw ApiError.badRequest(`Unknown message type '${String(type)}'.`, "UNKNOWN_MESSAGE_TYPE");
+				}
+			} catch (error) {
+				if (error instanceof ListLimitError) {
+					logger.warn(`[WebSocket Server] Refused a list read: ${error.message}`);
+					ws.send(JSON.stringify({
+						type: "ERROR",
+						requestId,
+						payload: { error: {
+							message: error.message,
+							code: "INVALID_LIMIT"
+						} }
+					}));
+					return;
+				}
+				if (error instanceof BranchingUnsupportedError || error?.name === "BranchingUnsupportedError") {
+					const refusal = error;
+					logger.warn(`[WebSocket Server] Refused a branch operation: ${refusal.message}`);
+					ws.send(JSON.stringify({
+						type: "ERROR",
+						requestId,
+						payload: { error: {
+							message: refusal.message,
+							code: "BRANCHING_UNSUPPORTED"
+						} }
+					}));
+					return;
+				}
+				const answer = declaredErrorAnswer(error);
+				if (answer) {
+					const line = `[WebSocket Server] Refused: ${answer.code} ${answer.message}`;
+					if (answer.expected) logger.debug(line);
+					else logger.warn(line);
+					ws.send(JSON.stringify({
+						type: "ERROR",
+						requestId,
+						payload: { error: {
+							message: answer.message,
+							code: answer.code,
+							...answer.details !== void 0 && { details: answer.details }
+						} }
+					}));
+					return;
+				}
+				logger.error("💥 [WebSocket Server] Error handling message", { error });
+				if (error instanceof Error) logger.error("Stack trace", { detail: error.stack });
+				const errorMessage = process.env.NODE_ENV === "production" ? "An unexpected error occurred" : extractErrorMessage(error);
+				const errorResponse = {
+					type: "ERROR",
+					requestId,
+					payload: { error: {
+						message: errorMessage,
+						code: "INTERNAL_ERROR"
+					} }
+				};
+				ws.send(JSON.stringify(errorResponse));
+			}
+		});
+	});
+	const stopReaping = reapSilentSockets(wss);
+	wss.on("close", stopReaping);
+	if (typeof server.on === "function") server.on("close", stopReaping);
+	const stopBudgeting = budgetSendBuffers(wss);
+	wss.on("close", stopBudgeting);
+	if (typeof server.on === "function") server.on("close", stopBudgeting);
+	const stopHeartbeats = startHeartbeats(() => heartbeatSockets, heartbeatIntervalMs);
+	wss.on("close", stopHeartbeats);
+	if (typeof server.on === "function") server.on("close", stopHeartbeats);
+}
+//#endregion
+export { createPostgresWebSocket as a, websocket_exports as c, TOO_MANY_SOCKETS_CLOSE_CODE as i, PUBLIC_TYPES as n, isSocketRealtimeService as o, SESSION_ENDED_CLOSE_CODE as r, socketRealtimeMissing as s, ADMIN_PLANE_TYPES as t };
+
+//# sourceMappingURL=websocket-BLGc5yhs.js.map