@classytic/arc-next 0.15.1 → 0.16.0

package/dist/sse.d.ts

@@ -101,6 +101,22 @@ interface EventStreamOptions<TData = unknown> extends SubscribeToEventsOptions<T
    * high-volume streams that don't read it.
    */
   trackEventCount?: boolean;
+  /**
+   * Hold ONE connection per browser rather than one per tab. Default: true.
+   *
+   * Browsers allow ~6 concurrent connections per origin on HTTP/1.1, so a
+   * per-tab stream lets a user starve their own app with a handful of tabs, and
+   * multiplies every reconnect against one server-side limit. The elected tab
+   * connects and relays events and connection state over `BroadcastChannel`;
+   * followers apply both without a socket.
+   *
+   * React-only — {@link subscribeToEvents} stays a plain per-caller connection,
+   * because tab coordination is a browser lifecycle concern and that function is
+   * the Node-capable core.
+   *
+   * Set false for a stream that must be per-tab.
+   */
+  shareAcrossTabs?: boolean;
 }
 interface EventStreamResult<TData = unknown> {
   isConnected: boolean;

package/dist/sse.js

@@ -1,8 +1,9 @@
 "use client";
 
 import { ArcApiError, _getAuthErrorHandler, _runAuthRecovery, buildStreamUrl, getAuthMode } from "./client.js";
+import { useTabLeader } from "./tab-leader.js";
 import { useQueryClient } from "@tanstack/react-query";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 
 //#region src/sse.ts
 /**
@@ -31,7 +32,24 @@ function buildSseUrl(path, params = {}) {
 * `Range: bytes=0-0` for servers that 405 on HEAD. Either way, the body
 * is never read — only the status code matters.
 */
-async function probeForAuthFailure(url, retryOn403) {
+/** `Retry-After` is delta-seconds or an HTTP-date. Unparseable ⇒ no opinion. */
+function parseRetryAfter(value) {
+	if (!value) return void 0;
+	const seconds = Number(value);
+	if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+	const at = Date.parse(value);
+	return Number.isNaN(at) ? void 0 : Math.max(0, at - Date.now());
+}
+/**
+* Learn WHY the stream failed, since `EventSource` will not say.
+*
+* 429 matters as much as 401 and fails worse: a rate-limited stream that
+* reconnects on the backoff schedule spends a token per attempt, so the window
+* never drains and the client locks itself out indefinitely. The probe is a
+* plain `fetch`, so unlike the stream it can read both the status and
+* `Retry-After`.
+*/
+async function probeConnectionFailure(url, retryOn403) {
 	try {
 		let res = await fetch(url, {
 			method: "HEAD",
@@ -42,11 +60,15 @@ async function probeForAuthFailure(url, retryOn403) {
 			credentials: "include",
 			headers: { Range: "bytes=0-0" }
 		});
-		if (res.status === 401) return "auth-failure";
-		if (retryOn403 && res.status === 403) return "auth-failure";
-		return "not-auth";
+		if (res.status === 401) return { kind: "auth-failure" };
+		if (retryOn403 && res.status === 403) return { kind: "auth-failure" };
+		if (res.status === 429) return {
+			kind: "rate-limited",
+			retryAfterMs: parseRetryAfter(res.headers.get("retry-after"))
+		};
+		return { kind: "not-auth" };
 	} catch {
-		return "not-auth";
+		return { kind: "not-auth" };
 	}
 }
 /**
@@ -129,11 +151,29 @@ function subscribeToEvents(options) {
 			connected = false;
 			options.onConnectionChange?.(false);
 			if (manualClose) return;
+			/**
+			* The probe runs whether or not an auth handler is registered.
+			*
+			* It was gated on `handler`, so a deployment with no `onAuthError` never
+			* learned WHY the stream failed and fell straight to backoff — including
+			* for 429, the one status where backing off on the wrong schedule is
+			* self-defeating rather than merely slow.
+			*/
 			const { handler, retryOn403, maxAuthRetries } = _getAuthErrorHandler();
-			if (handler && sseAuthRetries < maxAuthRetries) {
-				sseAuthRetries += 1;
-				probeForAuthFailure(buildUrl(), retryOn403).then(async (status) => {
-					if (status === "auth-failure") {
+			if (sseProbes < maxAuthRetries) {
+				sseProbes += 1;
+				if (handler) sseAuthRetries += 1;
+				probeConnectionFailure(buildUrl(), retryOn403).then(async ({ kind, retryAfterMs }) => {
+					if (kind === "rate-limited") {
+						/**
+						* Honour the server's own number. Falling back to a full window
+						* rather than the 3s-based curve: retrying inside the window
+						* cannot succeed and each attempt refills the bucket.
+						*/
+						scheduleReconnect(retryAfterMs ?? 6e4);
+						return;
+					}
+					if (kind === "auth-failure" && handler && sseAuthRetries <= maxAuthRetries) {
 						const { decision } = await _runAuthRecovery(handler, {
 							error: new ArcApiError("SSE pre-flight auth failure", {
 								status: 401,
@@ -163,15 +203,21 @@ function subscribeToEvents(options) {
 			scheduleReconnect();
 		};
 	};
-	/** Standard backoff-reconnect — shared between non-auth errors and skipped recoveries. */
-	const scheduleReconnect = () => {
+	/**
+	* Standard backoff-reconnect — shared between non-auth errors and skipped
+	* recoveries. `explicitDelayMs` overrides the curve when the SERVER stated a
+	* wait (`Retry-After`); its number beats any local guess.
+	*/
+	const scheduleReconnect = (explicitDelayMs) => {
 		if (reconnectAttempts < maxReconnectAttempts) {
 			reconnectAttempts += 1;
-			const delay = Math.min(reconnectDelay * 1.5 ** (reconnectAttempts - 1), 3e4);
+			const delay = explicitDelayMs ?? Math.min(reconnectDelay * 1.5 ** (reconnectAttempts - 1), 3e4);
 			reconnectTimer = setTimeout(connect, delay);
 		}
 	};
 	let sseAuthRetries = 0;
+	/** Probes attempted for THIS subscription — bounds the extra fetch per failure. */
+	let sseProbes = 0;
 	connect();
 	return {
 		close: () => {
@@ -214,7 +260,7 @@ function subscribeToEvents(options) {
 * });
 */
 function useEventStream(options) {
-	const { url, resource, path, enabled = true, trackLastEvent = true, trackEventCount = true } = options;
+	const { url, resource, path, enabled = true, trackLastEvent = true, trackEventCount = true, shareAcrossTabs = true } = options;
 	const queryClient = useQueryClient();
 	const [isConnected, setIsConnected] = useState(false);
 	const [lastEvent, setLastEvent] = useState(null);
@@ -230,12 +276,72 @@ function useEventStream(options) {
 	const eventTypesKey = JSON.stringify(options.eventTypes ?? null);
 	const patterns = useMemo(() => options.patterns, [patternsKey]);
 	const eventTypes = useMemo(() => options.eventTypes, [eventTypesKey]);
+	/**
+	* The single place an event is applied, whether it arrived over this tab's
+	* socket or was relayed by the leader. Two copies would drift.
+	*/
+	const applyEvent = useCallback((event) => {
+		if (trackLastEvent) setLastEvent(event);
+		if (trackEventCount) setEventCount((n) => n + 1);
+		onEventRef.current?.(event);
+		for (const key of invalidateKeysRef.current) queryClient.invalidateQueries({ queryKey: key });
+	}, [
+		queryClient,
+		trackLastEvent,
+		trackEventCount
+	]);
+	/**
+	* Stream identity shared by every tab pointing at it — the election key and
+	* the channel name. Derived from the ENDPOINT, not the built URL, so a
+	* per-tab token or org param cannot split one stream into several elections.
+	*/
+	const channelName = `arc-next.sse.${resource ?? path ?? url ?? "/events/stream"}`;
+	const isLeaderTab = useTabLeader({
+		key: channelName,
+		enabled: enabled && shareAcrossTabs
+	});
+	const connectedRef = useRef(false);
 	useEffect(() => {
 		if (!enabled) {
 			handleRef.current?.close();
 			handleRef.current = null;
 			return;
 		}
+		/**
+		* FOLLOWER — no socket. It mirrors the leader's events and connection
+		* state, so its cache, badge and polling decision stay correct at zero
+		* connection cost.
+		*/
+		if (shareAcrossTabs && !isLeaderTab) {
+			handleRef.current?.close();
+			handleRef.current = null;
+			if (typeof BroadcastChannel === "undefined") return;
+			const channel = new BroadcastChannel(channelName);
+			channel.onmessage = (ev) => {
+				const msg = ev.data;
+				if (msg?.kind === "event") applyEvent(msg.event);
+				else if (msg?.kind === "state") {
+					setIsConnected(msg.connected);
+					onConnectionChangeRef.current?.(msg.connected);
+				}
+			};
+			channel.postMessage({ kind: "hello" });
+			return () => {
+				channel.close();
+				setIsConnected(false);
+			};
+		}
+		let channel = null;
+		if (shareAcrossTabs && typeof BroadcastChannel !== "undefined") {
+			channel = new BroadcastChannel(channelName);
+			channel.onmessage = (ev) => {
+				if (ev.data?.kind !== "hello") return;
+				channel?.postMessage({
+					kind: "state",
+					connected: connectedRef.current
+				});
+			};
+		}
 		const handle = subscribeToEvents({
 			url,
 			resource,
@@ -246,20 +352,29 @@ function useEventStream(options) {
 			maxReconnectAttempts: options.maxReconnectAttempts,
 			withCredentials: options.withCredentials,
 			onConnectionChange: (c) => {
+				connectedRef.current = c;
 				setIsConnected(c);
 				onConnectionChangeRef.current?.(c);
+				channel?.postMessage({
+					kind: "state",
+					connected: c
+				});
 			},
 			onEvent: (event) => {
-				if (trackLastEvent) setLastEvent(event);
-				if (trackEventCount) setEventCount((n) => n + 1);
-				onEventRef.current?.(event);
-				for (const key of invalidateKeysRef.current) queryClient.invalidateQueries({ queryKey: key });
+				channel?.postMessage({
+					kind: "event",
+					event
+				});
+				applyEvent(event);
 			}
 		});
 		handleRef.current = handle;
 		return () => {
 			handle.close();
 			handleRef.current = null;
+			channel?.close();
+			channel = null;
+			connectedRef.current = false;
 		};
 	}, [
 		enabled,
@@ -273,7 +388,11 @@ function useEventStream(options) {
 		options.withCredentials,
 		trackLastEvent,
 		trackEventCount,
-		queryClient
+		queryClient,
+		shareAcrossTabs,
+		isLeaderTab,
+		channelName,
+		applyEvent
 	]);
 	return {
 		isConnected,

package/dist/tab-leader.d.ts

@@ -0,0 +1,14 @@
+//#region src/tab-leader.d.ts
+/**
+ * `true` in exactly one tab at a time (per `key`).
+ *
+ * When storage is unavailable every tab reports leader. That is deliberate: a
+ * degraded browser must not lose the feature entirely, and the server-side
+ * concurrency cap is the backstop for the duplicate connections it allows.
+ */
+declare function useTabLeader(options: {
+  key: string;
+  enabled?: boolean;
+}): boolean;
+//#endregion
+export { useTabLeader };

package/dist/tab-leader.js

@@ -0,0 +1,111 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+//#region src/tab-leader.ts
+/**
+* Elect ONE leader tab per browser, so a shared resource is held once.
+*
+* A browser allows only ~6 concurrent connections per origin on HTTP/1.1, so a
+* per-tab stream lets a user with several tabs starve their own app — and it
+* multiplies every reconnect against one server-side limit.
+*
+* Modelled on Odoo's `multi_tab_fallback_service` (addons/bus): the leader
+* writes a heartbeat on an interval, any tab may claim leadership once that
+* heartbeat goes stale, and a closing tab releases it immediately. localStorage
+* is the coordination channel because it is synchronous, origin-scoped and
+* present everywhere — a SharedWorker is tidier but absent in several browsers,
+* which is why Odoo keeps this path too.
+*/
+/** Leader refresh interval. Comfortably under STALE_MS so a live leader is never displaced. */
+const HEARTBEAT_MS = 1500;
+/** A heartbeat older than this means the holder is gone (crashed tab, killed process). */
+const STALE_MS = 5e3;
+/** How often a follower checks whether leadership is up for grabs. */
+const CHECK_MS = 2e3;
+function readRecord(key) {
+	try {
+		const raw = localStorage.getItem(key);
+		if (!raw) return null;
+		const parsed = JSON.parse(raw);
+		return typeof parsed?.id === "string" && typeof parsed?.ts === "number" ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+function writeRecord(key, record) {
+	try {
+		localStorage.setItem(key, JSON.stringify(record));
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* `true` in exactly one tab at a time (per `key`).
+*
+* When storage is unavailable every tab reports leader. That is deliberate: a
+* degraded browser must not lose the feature entirely, and the server-side
+* concurrency cap is the backstop for the duplicate connections it allows.
+*/
+function useTabLeader(options) {
+	const { key, enabled = true } = options;
+	const [isLeader, setIsLeader] = useState(false);
+	useEffect(() => {
+		if (!enabled || typeof window === "undefined" || typeof localStorage === "undefined") {
+			setIsLeader(false);
+			return;
+		}
+		const storageKey = `arc-next.leader.${key}`;
+		const tabId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+		let leading = false;
+		let timer = null;
+		const claimOrRenew = () => {
+			const now = Date.now();
+			const held = readRecord(storageKey);
+			const vacant = !held || now - held.ts > STALE_MS;
+			if (held?.id === tabId || vacant) {
+				/**
+				* Last write wins. Two tabs can claim a vacant slot in the same tick;
+				* the loser observes a foreign id on its next pass and steps down, so
+				* the overlap is bounded by one interval rather than persisting.
+				*/
+				if (writeRecord(storageKey, {
+					id: tabId,
+					ts: now
+				})) {
+					const won = readRecord(storageKey)?.id === tabId;
+					if (won !== leading) {
+						leading = won;
+						setIsLeader(won);
+					}
+				} else if (!leading) {
+					leading = true;
+					setIsLeader(true);
+				}
+			} else if (leading) {
+				leading = false;
+				setIsLeader(false);
+			}
+			timer = setTimeout(claimOrRenew, leading ? HEARTBEAT_MS : CHECK_MS);
+		};
+		/** Release immediately so a sibling promotes now rather than after STALE_MS. */
+		const release = () => {
+			if (!leading) return;
+			if (readRecord(storageKey)?.id === tabId) try {
+				localStorage.removeItem(storageKey);
+			} catch {}
+		};
+		claimOrRenew();
+		window.addEventListener("pagehide", release);
+		return () => {
+			if (timer) clearTimeout(timer);
+			release();
+			window.removeEventListener("pagehide", release);
+		};
+	}, [key, enabled]);
+	return isLeader;
+}
+
+//#endregion
+export { useTabLeader };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc-next",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "React + TanStack Query SDK for Arc resources",
   "type": "module",
   "sideEffects": false,
@@ -78,6 +78,10 @@
       "types": "./dist/sse.d.ts",
       "default": "./dist/sse.js"
     },
+    "./tab-leader": {
+      "types": "./dist/tab-leader.d.ts",
+      "default": "./dist/tab-leader.js"
+    },
     "./ws": {
       "types": "./dist/ws.d.ts",
       "default": "./dist/ws.js"