gemi 0.122.0 → 0.123.0

package/dist/chunks/{ThemeProvider-BLI4zpLu.js → ThemeProvider-CgK2mmVV.js}

@@ -726,6 +726,580 @@ function toVariantKey(search) {
 	return searchParams.toString();
 }
 //#endregion
+//#region services/broadcast/protocol.ts
+/**
+* The `gemi.v1` WebSocket protocol, shared by the server transport
+* (`SocketHub`) and the browser client (`gemi/client`'s connection manager).
+* Types and constants only: this module is imported by the browser bundle, so
+* it must never import a server module.
+*
+* Every frame is a JSON text frame. Binary frames are refused.
+*
+* From the client:
+*
+* - `{op:"sub", id, ch, p?}`: subscribe `id` (chosen by the client, unique per
+*   socket) to the channel pattern `ch` with params `p`. The server builds
+*   the topic and authorizes it.
+* - `{op:"unsub", id}`
+* - `{op:"ping"}`: answered with `pong`. The client sends one every
+*   `heartbeatMs` and reconnects when it hears nothing for twice that.
+*
+* From the server:
+*
+* - `{op:"hello", socketId, tag, heartbeatMs}`: the first frame. `socketId`
+*   goes in the `X-Gemi-Socket` header of the client's own requests (for
+*   `Broadcast.toOthers`); it is never shown to anyone else. `tag` is what
+*   an event frame's `x` carries when it skips this socket.
+* - `{op:"subscribed", id, t}`: `id` joined topic `t`. Sent only once this
+*   process receives the topic's events, so the resync the client runs on it
+*   cannot miss one.
+* - `{op:"denied", id, code}`: `id` was refused, or later revoked.
+* - `{op:"ev", t, ev, d?, x?}`: an event on topic `t`. Dropped by the socket
+*   whose `tag` is `x`.
+* - `{op:"gap"}`: events may have been lost for this socket; resync all.
+* - `{op:"pong"}`
+* - `{op:"bye", code, retryAfter}`: the server is going away (a restart).
+*   Reconnect after `retryAfter` ms.
+*/
+/** The WebSocket subprotocol. */
+var BROADCAST_PROTOCOL = "gemi.v1";
+/** The request header a client sends its socket id in, for `toOthers`. */
+var SOCKET_ID_HEADER = "x-gemi-socket";
+/**
+* Close codes the server uses. 1012 and 1013 are the standard "restart" and
+* "try again later"; the 4xxx ones are gemi's own.
+*/
+var CloseCode = {
+	/** The client went away (tab closed, socket released). */
+	Normal: 1e3,
+	/** A frame that was not JSON text, or not a known op. */
+	UnsupportedData: 1003,
+	/** Too many frames, or a frame over the size limit. */
+	PolicyViolation: 1008,
+	/** The server is restarting; `bye` said when to come back. */
+	Restart: 1012,
+	/** The socket fell too far behind; reconnect and resync. */
+	TryAgainLater: 1013,
+	/** The socket's user was signed out or its access revoked. */
+	Revoked: 4001
+};
+/**
+* Whether a refusal is final for this socket's session: resubscribing will
+* get the same answer, so the client does not retry it on its own.
+*/
+function isPermanentDenial(code) {
+	return code === "unknown_channel" || code === "invalid_params" || code === "invalid";
+}
+//#endregion
+//#region client/realtime/RealtimeClient.ts
+/** The minimum gap between two resyncs of one subscription. */
+var RESYNC_COALESCE_MS = 2e3;
+/** How long the socket stays open after its last subscription goes. */
+var IDLE_CLOSE_MS = 5e3;
+/**
+* How long a subscription outlives its last listener. A hook that remounts
+* within it (StrictMode's double mount, a route change back, a list that
+* re-renders its rows) picks the same subscription up again: no `unsub`, no
+* new `sub`, nothing counted against the server's rate limit.
+*/
+var RELEASE_LINGER_MS = 1500;
+/** The least wait before resending a `sub` denied with `rate_limited`. */
+var RATE_LIMITED_RETRY_MS = 5e3;
+var MIN_BACKOFF_MS = 1e3;
+var MAX_BACKOFF_MS = 3e4;
+var DEFAULT_HEARTBEAT_MS = 25e3;
+var DEFAULT_HIDDEN_DISCONNECT_MS = 6e4;
+/** `pattern` and its params, canonical: two hooks on one channel share a `sub`. */
+function channelKey(pattern, params) {
+	const sorted = Object.keys(params).sort().map((key) => [key, String(params[key])]);
+	return `${pattern}\u0000${JSON.stringify(sorted)}`;
+}
+/**
+* The tab's one WebSocket to the app (`gemi.v1`), multiplexing every channel
+* the mounted hooks subscribe to.
+*
+* Opened by the first subscription and closed a few seconds after the last
+* one goes. Reconnects with full-jitter backoff (1 to 30 s), or after the
+* server's `bye.retryAfter`, at once on `online`; resubscribes everything
+* then. A tab hidden for `hiddenDisconnectMs` disconnects, and reconnects
+* when shown. Every `subscribed` ack and every `gap` resyncs the
+* subscription (coalesced to one per 2 s), because events are volatile: a
+* client that may have missed one refetches over HTTP.
+*/
+var RealtimeClient = class {
+	options;
+	internals;
+	ws = null;
+	entries = /* @__PURE__ */ new Map();
+	byId = /* @__PURE__ */ new Map();
+	topics = /* @__PURE__ */ new Map();
+	nextId = 1;
+	attempt = 0;
+	tag = null;
+	socketIdValue = null;
+	heartbeatMs = DEFAULT_HEARTBEAT_MS;
+	reconnectTimer = null;
+	idleTimer = null;
+	hiddenTimer = null;
+	pingTimer = null;
+	livenessTimer = null;
+	retryAfter = null;
+	revoked = false;
+	pausedWhileHidden = false;
+	listening = false;
+	constructor(options = {}, internals = {}) {
+		this.options = withDefaults(options);
+		this.internals = internals;
+	}
+	configure(options) {
+		this.options = withDefaults({
+			...this.options,
+			...options
+		});
+	}
+	/** The id to send as `X-Gemi-Socket`, while the socket is open. */
+	get socketId() {
+		return this.socketIdValue;
+	}
+	subscribe(pattern, params, listener) {
+		const key = channelKey(pattern, params);
+		let entry = this.entries.get(key);
+		if (!entry) {
+			entry = {
+				key,
+				id: String(this.nextId++),
+				pattern,
+				params: { ...params },
+				listeners: /* @__PURE__ */ new Set(),
+				status: "closed",
+				code: null,
+				permanent: false,
+				topic: null,
+				lastResyncAt: 0,
+				resyncTimer: null,
+				lingerTimer: null,
+				retryTimer: null,
+				retries: 0
+			};
+			this.entries.set(key, entry);
+			this.byId.set(entry.id, entry);
+			if (this.isOpen()) this.sendSub(entry);
+		}
+		if (entry.lingerTimer) {
+			clearTimeout(entry.lingerTimer);
+			entry.lingerTimer = null;
+		}
+		entry.listeners.add(listener);
+		listener.onStatus?.(entry.status, entry.code);
+		this.cancelIdleClose();
+		this.listen();
+		if (!this.ws && !this.reconnectTimer && !this.pausedWhileHidden) this.connect();
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			this.release(entry, listener);
+		};
+	}
+	release(entry, listener) {
+		entry.listeners.delete(listener);
+		if (entry.listeners.size > 0 || entry.lingerTimer) return;
+		entry.lingerTimer = setTimeout(() => {
+			entry.lingerTimer = null;
+			if (entry.listeners.size === 0) this.drop(entry);
+		}, RELEASE_LINGER_MS);
+	}
+	drop(entry) {
+		if (entry.resyncTimer) clearTimeout(entry.resyncTimer);
+		this.clearRetry(entry);
+		this.entries.delete(entry.key);
+		this.byId.delete(entry.id);
+		this.dropTopic(entry);
+		if (this.isOpen() && (entry.status === "open" || entry.status === "connecting")) this.send({
+			op: "unsub",
+			id: entry.id
+		});
+		if (this.entries.size === 0) this.scheduleIdleClose();
+	}
+	isOpen() {
+		return this.ws !== null && this.ws.readyState === 1;
+	}
+	connect() {
+		if (typeof window === "undefined") return;
+		if (this.entries.size === 0) return;
+		const Impl = this.internals.WebSocket ?? globalThis.WebSocket;
+		if (!Impl) return;
+		this.clearReconnect();
+		let ws;
+		try {
+			ws = new Impl(this.url(), [BROADCAST_PROTOCOL]);
+		} catch {
+			this.scheduleReconnect();
+			return;
+		}
+		this.ws = ws;
+		for (const entry of this.entries.values()) if (!entry.permanent) this.setStatus(entry, "connecting", null);
+		ws.onopen = () => {
+			if (this.ws !== ws) return;
+			this.touch();
+			for (const entry of this.entries.values()) if (!entry.permanent) this.sendSub(entry);
+		};
+		ws.onmessage = (event) => {
+			if (this.ws !== ws) return;
+			this.touch();
+			let frame;
+			try {
+				frame = JSON.parse(String(event.data));
+			} catch {
+				return;
+			}
+			this.handle(frame);
+		};
+		ws.onclose = (event) => {
+			if (this.ws !== ws) return;
+			this.onClosed(event.code);
+		};
+		ws.onerror = () => {};
+	}
+	url() {
+		if (this.internals.url) return this.internals.url;
+		const { protocol, host } = window.location;
+		return `${protocol === "https:" ? "wss:" : "ws:"}//${host}${this.options.path}`;
+	}
+	sendSub(entry) {
+		this.setStatus(entry, "connecting", null);
+		const frame = {
+			op: "sub",
+			id: entry.id,
+			ch: entry.pattern
+		};
+		if (Object.keys(entry.params).length > 0) frame.p = entry.params;
+		this.send(frame);
+	}
+	send(frame) {
+		if (!this.isOpen()) return;
+		try {
+			this.ws.send(JSON.stringify(frame));
+		} catch {}
+	}
+	handle(frame) {
+		switch (frame.op) {
+			case "hello":
+				this.socketIdValue = frame.socketId;
+				this.tag = frame.tag;
+				this.attempt = 0;
+				this.revoked = false;
+				if (frame.heartbeatMs > 0) this.heartbeatMs = frame.heartbeatMs;
+				this.startHeartbeat();
+				return;
+			case "subscribed": {
+				const entry = this.byId.get(frame.id);
+				if (!entry) return;
+				this.dropTopic(entry);
+				entry.topic = frame.t;
+				let ids = this.topics.get(frame.t);
+				if (!ids) this.topics.set(frame.t, ids = /* @__PURE__ */ new Set());
+				ids.add(entry.id);
+				this.clearRetry(entry);
+				entry.retries = 0;
+				this.setStatus(entry, "open", null);
+				this.resync(entry);
+				return;
+			}
+			case "denied": {
+				const entry = this.byId.get(frame.id);
+				if (!entry) return;
+				this.dropTopic(entry);
+				entry.permanent = isPermanentDenial(frame.code);
+				this.setStatus(entry, "denied", frame.code);
+				this.scheduleRetry(entry, frame.code);
+				return;
+			}
+			case "ev": {
+				if (frame.x !== void 0 && frame.x === this.tag) return;
+				const ids = this.topics.get(frame.t);
+				if (!ids) return;
+				for (const id of Array.from(ids)) {
+					const entry = this.byId.get(id);
+					if (!entry) continue;
+					for (const listener of Array.from(entry.listeners)) try {
+						listener.onEvent?.(frame.ev, frame.d);
+					} catch (error) {
+						reportListenerError(error);
+					}
+				}
+				return;
+			}
+			case "gap":
+				for (const entry of this.entries.values()) if (entry.status === "open") this.resync(entry);
+				return;
+			case "bye":
+				this.retryAfter = Math.max(0, Number(frame.retryAfter) || 0);
+				return;
+			case "pong": return;
+		}
+	}
+	onClosed(code) {
+		this.ws = null;
+		this.socketIdValue = null;
+		this.tag = null;
+		this.stopHeartbeat();
+		this.topics.clear();
+		for (const entry of this.entries.values()) {
+			entry.topic = null;
+			this.clearRetry(entry);
+			if (!entry.permanent) this.setStatus(entry, "closed", null);
+		}
+		if (code === CloseCode.Revoked) this.revoked = true;
+		if (this.entries.size > 0 && !this.pausedWhileHidden) this.scheduleReconnect();
+	}
+	scheduleReconnect() {
+		this.clearReconnect();
+		let delay;
+		if (this.retryAfter !== null) {
+			delay = this.retryAfter;
+			this.retryAfter = null;
+		} else if (this.revoked) {
+			this.revoked = false;
+			delay = Math.floor(this.random() * 500);
+		} else delay = backoffDelay(this.attempt, this.random());
+		this.attempt++;
+		this.reconnectTimer = setTimeout(() => {
+			this.reconnectTimer = null;
+			this.connect();
+		}, delay);
+	}
+	clearReconnect() {
+		if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+		this.reconnectTimer = null;
+	}
+	random() {
+		return (this.internals.random ?? Math.random)();
+	}
+	startHeartbeat() {
+		this.stopHeartbeat();
+		this.pingTimer = setInterval(() => this.send({ op: "ping" }), this.heartbeatMs);
+		this.touch();
+	}
+	stopHeartbeat() {
+		if (this.pingTimer) clearInterval(this.pingTimer);
+		if (this.livenessTimer) clearTimeout(this.livenessTimer);
+		this.pingTimer = null;
+		this.livenessTimer = null;
+	}
+	/** Anything from the server proves the socket alive. */
+	touch() {
+		if (this.livenessTimer) clearTimeout(this.livenessTimer);
+		const ws = this.ws;
+		this.livenessTimer = setTimeout(() => {
+			if (this.ws !== ws || !ws) return;
+			try {
+				ws.close();
+			} catch {}
+			this.onClosed(1006);
+		}, this.heartbeatMs * 2);
+	}
+	setStatus(entry, status, code) {
+		if (entry.status === status && entry.code === code) return;
+		entry.status = status;
+		entry.code = code;
+		for (const listener of Array.from(entry.listeners)) try {
+			listener.onStatus?.(status, code);
+		} catch (error) {
+			reportListenerError(error);
+		}
+	}
+	/** At most one resync per subscription per 2 s; a later one is deferred, not dropped. */
+	resync(entry) {
+		if (entry.resyncTimer) return;
+		const now = Date.now();
+		const wait = entry.lastResyncAt + RESYNC_COALESCE_MS - now;
+		const fire = () => {
+			entry.resyncTimer = null;
+			entry.lastResyncAt = Date.now();
+			for (const listener of Array.from(entry.listeners)) try {
+				listener.onResync?.();
+			} catch (error) {
+				reportListenerError(error);
+			}
+		};
+		if (entry.lastResyncAt === 0 || wait <= 0) fire();
+		else entry.resyncTimer = setTimeout(fire, wait);
+	}
+	/**
+	* A transient denial (`rate_limited`, `error`, `limit`) is retried on the
+	* same socket, with backoff: a healthy socket may never reconnect. `denied`
+	* and `revoked` are the channel's answer for this session, so they wait for
+	* the next connection (a sign-in reconnects), and a permanent one is never
+	* resent.
+	*/
+	scheduleRetry(entry, code) {
+		if (code !== "rate_limited" && code !== "error" && code !== "limit") return;
+		this.clearRetry(entry);
+		const delay = Math.max(code === "rate_limited" ? RATE_LIMITED_RETRY_MS : MIN_BACKOFF_MS, backoffDelay(entry.retries, this.random()));
+		entry.retries++;
+		entry.retryTimer = setTimeout(() => {
+			entry.retryTimer = null;
+			if (this.entries.get(entry.key) !== entry || entry.status !== "denied") return;
+			if (this.isOpen()) this.sendSub(entry);
+		}, delay);
+	}
+	clearRetry(entry) {
+		if (entry.retryTimer) clearTimeout(entry.retryTimer);
+		entry.retryTimer = null;
+	}
+	dropTopic(entry) {
+		if (!entry.topic) return;
+		const ids = this.topics.get(entry.topic);
+		ids?.delete(entry.id);
+		if (ids && ids.size === 0) this.topics.delete(entry.topic);
+		entry.topic = null;
+	}
+	scheduleIdleClose() {
+		this.cancelIdleClose();
+		this.idleTimer = setTimeout(() => {
+			this.idleTimer = null;
+			if (this.entries.size > 0) return;
+			this.clearReconnect();
+			this.close();
+		}, IDLE_CLOSE_MS);
+	}
+	cancelIdleClose() {
+		if (this.idleTimer) clearTimeout(this.idleTimer);
+		this.idleTimer = null;
+	}
+	/** Closes the socket without reconnecting. */
+	close() {
+		const ws = this.ws;
+		if (!ws) return;
+		this.ws = null;
+		try {
+			ws.close(CloseCode.Normal);
+		} catch {}
+		this.onClosed(CloseCode.Normal);
+	}
+	listen() {
+		if (this.listening || typeof window === "undefined") return;
+		this.listening = true;
+		window.addEventListener("online", this.onOnline);
+		if (typeof document !== "undefined") document.addEventListener("visibilitychange", this.onVisibility);
+	}
+	onOnline = () => {
+		if (this.entries.size === 0 || this.ws || this.pausedWhileHidden) return;
+		this.attempt = 0;
+		this.connect();
+	};
+	onVisibility = () => {
+		if (document.visibilityState === "hidden") {
+			if (this.hiddenTimer) return;
+			this.hiddenTimer = setTimeout(() => {
+				this.hiddenTimer = null;
+				if (document.visibilityState !== "hidden") return;
+				this.pausedWhileHidden = true;
+				this.clearReconnect();
+				this.close();
+			}, this.options.hiddenDisconnectMs);
+			return;
+		}
+		if (this.hiddenTimer) clearTimeout(this.hiddenTimer);
+		this.hiddenTimer = null;
+		if (this.pausedWhileHidden) {
+			this.pausedWhileHidden = false;
+			this.attempt = 0;
+			this.connect();
+		}
+	};
+	/**
+	* Drops the socket and opens a new one at once, when anything is
+	* subscribed. A socket keeps the session it was opened with (the upgrade's
+	* cookies), so signing in or out in this tab reconnects it: every channel
+	* is then authorized as the new session, and the acks resync.
+	*/
+	reconnect() {
+		this.close();
+		this.clearReconnect();
+		this.attempt = 0;
+		if (this.entries.size > 0 && !this.pausedWhileHidden) this.connect();
+	}
+	/** For tests: drops the socket, timers and listeners. */
+	dispose() {
+		this.clearReconnect();
+		this.cancelIdleClose();
+		if (this.hiddenTimer) clearTimeout(this.hiddenTimer);
+		for (const entry of this.entries.values()) {
+			if (entry.resyncTimer) clearTimeout(entry.resyncTimer);
+			if (entry.lingerTimer) clearTimeout(entry.lingerTimer);
+			this.clearRetry(entry);
+		}
+		this.entries.clear();
+		this.byId.clear();
+		this.close();
+		if (this.listening && typeof window !== "undefined") {
+			window.removeEventListener("online", this.onOnline);
+			document?.removeEventListener("visibilitychange", this.onVisibility);
+			this.listening = false;
+		}
+	}
+};
+/** Full jitter, 1 to 30 s: `max(1 s, random × min(30 s, 1 s × 2^attempt))`. */
+function backoffDelay(attempt, random) {
+	const cap = Math.min(MAX_BACKOFF_MS, MIN_BACKOFF_MS * 2 ** Math.min(attempt, 10));
+	return Math.max(MIN_BACKOFF_MS, Math.floor(random * cap));
+}
+function withDefaults(options) {
+	return {
+		path: options.path ?? "/__gemi/socket",
+		hiddenDisconnectMs: options.hiddenDisconnectMs ?? DEFAULT_HIDDEN_DISCONNECT_MS
+	};
+}
+function reportListenerError(error) {
+	setTimeout(() => {
+		throw error;
+	});
+}
+var configured = {};
+var instance = null;
+/**
+* Sets the socket options (`init({ realtime })` calls it). Takes effect on
+* the next connection.
+*/
+function configureRealtime(options = {}) {
+	configured = {
+		...configured,
+		...options
+	};
+	instance?.configure(configured);
+}
+/** The tab's client, created on first use. `null` on the server. */
+function getRealtimeClient() {
+	if (typeof window === "undefined") return null;
+	instance ??= new RealtimeClient(configured);
+	return instance;
+}
+/**
+* Reconnects the tab's socket, if it has one, so its channels are authorized
+* as the current session. The auth hooks call it after signing in or out.
+* Never creates the client.
+*/
+function reconnectRealtime() {
+	instance?.reconnect();
+}
+/**
+* The open socket's id, for the `X-Gemi-Socket` header, or `null`. Never
+* creates the client.
+*/
+function currentSocketId() {
+	return instance?.socketId ?? null;
+}
+//#endregion
+//#region client/realtime/RealtimeContext.ts
+/**
+* The socket the channel hooks subscribe through. `null` (the default) is the
+* tab's own `RealtimeClient`, created on first use in the browser; `<Page>`
+* in `gemi/testing` provides a `FakeSocket`.
+*/
+var RealtimeContext = createContext(null);
+//#endregion
 //#region ../../node_modules/.bun/@babel+runtime@7.29.2/node_modules/@babel/runtime/helpers/esm/extends.js
 function _extends() {
 	return _extends = Object.assign ? Object.assign.bind() : function(n) {
@@ -3408,6 +3982,6 @@ function useTheme() {
 	return context;
 }
 //#endregion
-export { useLocation as A, QueryManagerProvider as B, useRoute as C, I18nProvider as D, I18nContext as E, createMemoryHistory as F, retryDelayFor as G, pickDefined as H, toVariantKey as I, Subject as J, shouldRetryQuery as K, applyParams as L, isAbsoluteUrl as M, ProgressManager as N, ServerDataContext as O, Action as P, QueryConfigContext as R, routeDataUrl as S, useNavigate as T, DEFAULT_STALE_TIME as U, USER_QUERY_CONFIG_KEYS as V, isRetryableQueryError as W, loadDictionary as _, useRouteTransition as a, setActiveLocale as b, ComponentsContext as c, loadViewModule as d, subscribeViewModules as f, recoverFromChunkLoadError as g, isChunkLoadError as h, RouteTransitionProvider as i, domainUrl as j, ServerDataProvider as k, ComponentsProvider as l, configureChunkLoadRecovery as m, useTheme as n, ClientRouterContext as o, CHUNK_RELOAD_MARKER as p, QueryError as q, m as r, ClientRouterProvider as s, ThemeProvider as t, initialViewModulesReady as u, loadDictionaryForRender as v, useSearchParams as w, readRoutePayload as x, registerDictionary as y, QueryManagerContext as z };
+export { shouldRetryQuery as $, useLocation as A, getRealtimeClient as B, useRoute as C, I18nProvider as D, I18nContext as E, createMemoryHistory as F, QueryConfigContext as G, SOCKET_ID_HEADER as H, RealtimeContext as I, USER_QUERY_CONFIG_KEYS as J, QueryManagerContext as K, channelKey as L, isAbsoluteUrl as M, ProgressManager as N, ServerDataContext as O, Action as P, retryDelayFor as Q, configureRealtime as R, routeDataUrl as S, useNavigate as T, toVariantKey as U, reconnectRealtime as V, applyParams as W, DEFAULT_STALE_TIME as X, pickDefined as Y, isRetryableQueryError as Z, loadDictionary as _, useRouteTransition as a, setActiveLocale as b, ComponentsContext as c, loadViewModule as d, QueryError as et, subscribeViewModules as f, recoverFromChunkLoadError as g, isChunkLoadError as h, RouteTransitionProvider as i, domainUrl as j, ServerDataProvider as k, ComponentsProvider as l, configureChunkLoadRecovery as m, useTheme as n, ClientRouterContext as o, CHUNK_RELOAD_MARKER as p, QueryManagerProvider as q, m as r, ClientRouterProvider as s, ThemeProvider as t, Subject as tt, initialViewModulesReady as u, loadDictionaryForRender as v, useSearchParams as w, readRoutePayload as x, registerDictionary as y, currentSocketId as z };
 
-//# sourceMappingURL=ThemeProvider-BLI4zpLu.js.map
+//# sourceMappingURL=ThemeProvider-CgK2mmVV.js.map