@spooky-sync/core 0.0.1-canary.21 → 0.0.1-canary.211

package/dist/tabs-broker-worker.js

@@ -0,0 +1,472 @@
+//#region src/services/tabs/tabs-broker-worker.ts
+const PING_INTERVAL_MS = 5e3;
+const PONG_TIMEOUT_MS = 15e3;
+/** How long a tab has to answer `become-leader` with `leader-ready`. A tab
+*  that hangs mid-promotion sends neither `leader-ready` nor `leader-failed`,
+*  and keeps answering pings, so nothing else here would notice: the
+*  namespace would keep a leader that is not `ready`, mint no follower ports,
+*  and refuse to re-elect (`electIfNeeded` bails while `ns.leader` is set)
+*  until every tab was reloaded. Treat the silence as a failed promotion. */
+const PROMOTION_TIMEOUT_MS = 2e4;
+const FORCE_TAKEOVER_TIMEOUT_MS = 1e3;
+const LEADER_FAILURE_BACKOFF_MS = 1e3;
+const FAILED_CYCLES_BEFORE_MEMORY = 3;
+const brokerInstanceId = typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : `bk_${Math.random().toString(36).slice(2)}`;
+const namespaces = /* @__PURE__ */ new Map();
+/** Reverse index: which namespace a port belongs to (for pong routing). */
+const portTab = /* @__PURE__ */ new Map();
+/** The FIRST fingerprint wins for the whole broker instance; a tab from a
+*  different build gets `unsupported` and runs solo. Bucket ids may differ. */
+let canonicalFingerprint = null;
+let pingTimer = null;
+function post(port, msg, transfer) {
+	try {
+		if (transfer) port.postMessage(msg, transfer);
+		else port.postMessage(msg);
+	} catch {}
+}
+function nsKey(fingerprint, bucketId) {
+	return `${fingerprint}::${bucketId}`;
+}
+function getNamespace(fingerprint, bucketId) {
+	const key = nsKey(fingerprint, bucketId);
+	let ns = namespaces.get(key);
+	if (!ns) {
+		ns = {
+			key,
+			fingerprint,
+			bucketId,
+			tabs: /* @__PURE__ */ new Map(),
+			leader: null,
+			failedUntil: /* @__PURE__ */ new Map(),
+			failedCycles: 0,
+			electing: false,
+			attachRetry: /* @__PURE__ */ new Map(),
+			tabLockMonitor: null,
+			promotionTimer: null
+		};
+		namespaces.set(key, ns);
+	}
+	return ns;
+}
+let nextLeadershipId = 0;
+/** Duplicated from protocol.ts selectLeaderCandidate; keep in sync. */
+function pickCandidate(ns) {
+	const now = Date.now();
+	const eligible = [...ns.tabs.values()].filter((t) => {
+		if ((ns.failedUntil.get(t.tabId) ?? 0) > now) return false;
+		ns.failedUntil.delete(t.tabId);
+		return true;
+	});
+	if (eligible.length === 0) return null;
+	const holding = eligible.filter((t) => t.heldLeadership !== null);
+	const base = holding.length > 0 ? holding : eligible;
+	const visible = base.filter((t) => t.visibility === "visible");
+	return (visible.length > 0 ? visible : base).reduce((best, t) => {
+		if (t.lastVisibleAt !== best.lastVisibleAt) return t.lastVisibleAt > best.lastVisibleAt ? t : best;
+		return t.tabId > best.tabId ? t : best;
+	});
+}
+function clearLeader(ns, opts) {
+	const leader = ns.leader;
+	if (!leader) return null;
+	ns.leader = null;
+	clearPromotionTimer(ns);
+	ns.tabLockMonitor?.abort();
+	ns.tabLockMonitor = null;
+	const tab = ns.tabs.get(leader.tabId);
+	const workerLock = tab?.heldLeadership?.workerLockName ?? null;
+	if (tab && opts.demote) post(tab.port, {
+		type: "demote",
+		brokerInstanceId,
+		leadershipId: leader.leadershipId
+	});
+	if (opts.removeTab && tab) removeTab(ns, leader.tabId, { notifyLeader: false });
+	for (const t of ns.tabs.values()) if (t.tabId !== leader.tabId) post(t.port, {
+		type: "close-follower-ports",
+		brokerInstanceId,
+		leadershipId: leader.leadershipId
+	});
+	for (const [, retry] of ns.attachRetry) if (retry.timer) clearTimeout(retry.timer);
+	ns.attachRetry.clear();
+	return {
+		tabId: leader.tabId,
+		leadershipId: leader.leadershipId,
+		workerLock
+	};
+}
+function clearPromotionTimer(ns) {
+	if (ns.promotionTimer) clearTimeout(ns.promotionTimer);
+	ns.promotionTimer = null;
+}
+/**
+* A promotion did not work out: back the tab off, clear the leadership, and
+* re-elect. Shared by the tab's own `leader-failed` report and by the
+* {@link PROMOTION_TIMEOUT_MS} deadline, so a tab that hangs mid-promotion
+* costs the namespace the same 1s backoff as one that fails loudly, instead of
+* owning it forever.
+*
+* Every reason counts toward `failedCycles`. Gating that on 'opfs-unavailable'
+* left any other recurring failure (e.g. a tab lock nobody frees) looping at
+* the backoff interval forever, with allowMemoryFallback never granted, so
+* every tab timed out in start() and booted solo - each one then contending
+* for the OPFS pool on its own, which is exactly what shared-tabs exists to
+* stop.
+*/
+function failPromotion(ns, tabId, leadershipId, opts) {
+	if (ns.leader?.tabId !== tabId || ns.leader.leadershipId !== leadershipId) return;
+	ns.failedCycles += 1;
+	ns.failedUntil.set(tabId, Date.now() + LEADER_FAILURE_BACKOFF_MS);
+	const previous = clearLeader(ns, {
+		demote: false,
+		removeTab: false
+	});
+	const tab = ns.tabs.get(tabId);
+	if (tab) tab.heldLeadership = null;
+	electIfNeeded(ns, opts.timedOut && previous ? {
+		...previous,
+		workerLock: `sp00ky-tabs:${ns.fingerprint}:${ns.bucketId}:worker:${leadershipId}`
+	} : previous);
+}
+/**
+* Fast crash detection: queue a Web Lock request on the leader's tab lock.
+* Locks release the instant their holder's tab dies, so being GRANTED means
+* the leader is gone; release immediately (return from the callback) and
+* re-elect. The leadershipId guard drops stale grants after a normal handoff.
+*/
+function startTabLockMonitor(ns, leadershipId) {
+	const locks = navigator.locks;
+	if (!locks) return;
+	ns.tabLockMonitor?.abort();
+	const controller = new AbortController();
+	ns.tabLockMonitor = controller;
+	const name = `sp00ky-tabs:${ns.fingerprint}:${ns.bucketId}:tab`;
+	locks.request(name, {
+		mode: "exclusive",
+		signal: controller.signal
+	}, () => {
+		if (ns.leader?.leadershipId !== leadershipId) return;
+		electIfNeeded(ns, clearLeader(ns, {
+			demote: true,
+			removeTab: true
+		}));
+	}).catch(() => {});
+}
+/** Probe whether a lock name is free by acquiring-and-releasing it. */
+async function lockIsFree(name) {
+	const locks = navigator.locks;
+	if (!locks) return true;
+	try {
+		return await locks.request(name, {
+			mode: "exclusive",
+			ifAvailable: true
+		}, (lock) => Promise.resolve(lock !== null));
+	} catch {
+		return true;
+	}
+}
+async function stealLock(name) {
+	const locks = navigator.locks;
+	if (!locks) return;
+	try {
+		await locks.request(name, {
+			mode: "exclusive",
+			steal: true
+		}, () => Promise.resolve());
+	} catch {}
+}
+/**
+* Before promoting a replacement, give the previous leader's locks a chance to
+* free naturally (dead tab: released instantly; frozen tab: never). Returns
+* whether a steal was needed, which the new leader passes to its worker open.
+*/
+async function waitForPreviousLeaderLocks(previous) {
+	if (!previous?.workerLock) return false;
+	if (await lockIsFree(previous.workerLock)) return false;
+	await new Promise((r) => setTimeout(r, FORCE_TAKEOVER_TIMEOUT_MS));
+	if (await lockIsFree(previous.workerLock)) return false;
+	await stealLock(previous.workerLock);
+	return true;
+}
+function electIfNeeded(ns, previous = null) {
+	if (ns.electing || ns.leader || ns.tabs.size === 0) return;
+	ns.electing = true;
+	(async () => {
+		try {
+			const forceTakeover = await waitForPreviousLeaderLocks(previous);
+			if (ns.leader || ns.tabs.size === 0) return;
+			const candidate = pickCandidate(ns);
+			if (!candidate) {
+				const soonest = Math.min(...[...ns.failedUntil.values()], Date.now() + LEADER_FAILURE_BACKOFF_MS);
+				setTimeout(() => electIfNeeded(ns), Math.max(50, soonest - Date.now()));
+				return;
+			}
+			const resumeHeld = candidate.heldLeadership !== null;
+			const leadershipId = ++nextLeadershipId;
+			ns.leader = {
+				tabId: candidate.tabId,
+				leadershipId,
+				ready: false
+			};
+			post(candidate.port, {
+				type: "become-leader",
+				brokerInstanceId,
+				leadershipId,
+				forceTakeover,
+				allowMemoryFallback: ns.failedCycles >= FAILED_CYCLES_BEFORE_MEMORY,
+				resumeHeld
+			});
+			clearPromotionTimer(ns);
+			ns.promotionTimer = setTimeout(() => {
+				ns.promotionTimer = null;
+				failPromotion(ns, candidate.tabId, leadershipId, { timedOut: true });
+			}, PROMOTION_TIMEOUT_MS);
+		} finally {
+			ns.electing = false;
+		}
+	})();
+}
+function assignFollowerPorts(ns) {
+	const leader = ns.leader;
+	if (!leader || !leader.ready) return;
+	const leaderTab = ns.tabs.get(leader.tabId);
+	if (!leaderTab) return;
+	for (const tab of ns.tabs.values()) {
+		if (tab.tabId === leader.tabId) continue;
+		if (ns.attachRetry.has(tab.tabId)) continue;
+		mintPorts(ns, leaderTab, tab, leader.leadershipId);
+	}
+}
+function mintPorts(ns, leaderTab, follower, leadershipId) {
+	const db = new MessageChannel();
+	const sync = new MessageChannel();
+	post(leaderTab.port, {
+		type: "attach-follower-ports",
+		brokerInstanceId,
+		leadershipId,
+		followerTabId: follower.tabId
+	}, [db.port1, sync.port1]);
+	post(follower.port, {
+		type: "use-follower-ports",
+		brokerInstanceId,
+		leadershipId,
+		leaderTabId: leaderTab.tabId
+	}, [db.port2, sync.port2]);
+	const state = ns.attachRetry.get(follower.tabId) ?? {
+		count: 0,
+		timer: null
+	};
+	const delay = Math.min(1e3 * 2 ** state.count, 3e4);
+	state.count += 1;
+	state.timer = setTimeout(() => {
+		const cur = ns.attachRetry.get(follower.tabId);
+		if (!cur) return;
+		cur.timer = null;
+		const stillLeader = ns.leader && ns.leader.leadershipId === leadershipId && ns.leader.ready;
+		const stillHere = ns.tabs.get(follower.tabId);
+		const leaderNow = stillLeader ? ns.tabs.get(ns.leader.tabId) : void 0;
+		if (stillLeader && stillHere && leaderNow) mintPorts(ns, leaderNow, stillHere, leadershipId);
+		else ns.attachRetry.delete(follower.tabId);
+	}, delay);
+	ns.attachRetry.set(follower.tabId, state);
+}
+function followerAttached(ns, followerTabId) {
+	const retry = ns.attachRetry.get(followerTabId);
+	if (retry?.timer) clearTimeout(retry.timer);
+	ns.attachRetry.delete(followerTabId);
+}
+function ensurePingTimer() {
+	if (pingTimer) return;
+	pingTimer = setInterval(() => {
+		const now = Date.now();
+		for (const ns of namespaces.values()) for (const tab of [...ns.tabs.values()]) {
+			if (now - tab.lastPongAt > PONG_TIMEOUT_MS) {
+				evictTab(ns, tab.tabId, "missed pongs");
+				continue;
+			}
+			post(tab.port, {
+				type: "ping",
+				brokerInstanceId
+			});
+		}
+		stopPingTimerIfIdle();
+	}, PING_INTERVAL_MS);
+}
+function stopPingTimerIfIdle() {
+	if (pingTimer && [...namespaces.values()].every((ns) => ns.tabs.size === 0)) {
+		clearInterval(pingTimer);
+		pingTimer = null;
+		namespaces.clear();
+		canonicalFingerprint = null;
+	}
+}
+function removeTab(ns, tabId, opts) {
+	const tab = ns.tabs.get(tabId);
+	if (!tab) return;
+	ns.tabs.delete(tabId);
+	portTab.delete(tab.port);
+	if (opts.closePort !== false) try {
+		tab.port.close();
+	} catch {}
+	const retry = ns.attachRetry.get(tabId);
+	if (retry?.timer) clearTimeout(retry.timer);
+	ns.attachRetry.delete(tabId);
+	if (opts.notifyLeader && ns.leader && ns.leader.tabId !== tabId) {
+		const leaderTab = ns.tabs.get(ns.leader.tabId);
+		if (leaderTab) post(leaderTab.port, {
+			type: "close-follower-ports",
+			brokerInstanceId,
+			leadershipId: ns.leader.leadershipId
+		});
+	}
+}
+function evictTab(ns, tabId, reason, opts = {}) {
+	const wasLeader = ns.leader?.tabId === tabId;
+	const previous = wasLeader ? clearLeader(ns, {
+		demote: true,
+		removeTab: false
+	}) : null;
+	removeTab(ns, tabId, {
+		notifyLeader: !wasLeader,
+		closePort: opts.closePort
+	});
+	if (wasLeader) electIfNeeded(ns, previous);
+	stopPingTimerIfIdle();
+}
+function handleTabMessage(port, msg, ports) {
+	if (msg.type === "hello") {
+		if (canonicalFingerprint === null) canonicalFingerprint = msg.fingerprint;
+		if (msg.fingerprint !== canonicalFingerprint) {
+			post(port, {
+				type: "unsupported",
+				brokerInstanceId,
+				reason: "fingerprint-mismatch"
+			});
+			return;
+		}
+		const ns = getNamespace(msg.fingerprint, msg.bucketId);
+		for (const other of [...namespaces.values()]) if (other.tabs.has(msg.tabId)) evictTab(other, msg.tabId, "rehello", { closePort: false });
+		const tab = {
+			port,
+			tabId: msg.tabId,
+			fingerprint: msg.fingerprint,
+			bucketId: msg.bucketId,
+			visibility: msg.visibility,
+			lastVisibleAt: msg.visibility === "visible" ? Date.now() : 0,
+			lastPongAt: Date.now(),
+			heldLeadership: msg.heldLeadership
+		};
+		ns.tabs.set(msg.tabId, tab);
+		portTab.set(port, {
+			ns,
+			tabId: msg.tabId
+		});
+		ensurePingTimer();
+		post(port, {
+			type: "broker-hello",
+			brokerInstanceId
+		});
+		if (ns.leader?.ready) {
+			post(port, {
+				type: "leader-ready",
+				brokerInstanceId,
+				leadershipId: ns.leader.leadershipId,
+				leaderTabId: ns.leader.tabId
+			});
+			assignFollowerPorts(ns);
+		} else electIfNeeded(ns);
+		return;
+	}
+	const entry = portTab.get(port);
+	if (!entry) return;
+	const { ns } = entry;
+	switch (msg.type) {
+		case "pong": {
+			const tab = ns.tabs.get(msg.tabId);
+			if (tab) tab.lastPongAt = Date.now();
+			break;
+		}
+		case "visibility": {
+			const tab = ns.tabs.get(msg.tabId);
+			if (tab) {
+				tab.visibility = msg.visibility;
+				if (msg.visibility === "visible") tab.lastVisibleAt = Date.now();
+				tab.lastPongAt = Date.now();
+			}
+			break;
+		}
+		case "leader-ready": {
+			if (ns.leader?.tabId !== msg.tabId || ns.leader.leadershipId !== msg.leadershipId) {
+				post(port, {
+					type: "demote",
+					brokerInstanceId,
+					leadershipId: msg.leadershipId
+				});
+				break;
+			}
+			ns.leader.ready = true;
+			ns.failedCycles = 0;
+			clearPromotionTimer(ns);
+			startTabLockMonitor(ns, msg.leadershipId);
+			const tab = ns.tabs.get(msg.tabId);
+			if (tab) tab.heldLeadership = {
+				leadershipId: msg.leadershipId,
+				workerLockName: `sp00ky-tabs:${ns.fingerprint}:${ns.bucketId}:worker:${msg.leadershipId}`
+			};
+			for (const t of ns.tabs.values()) post(t.port, {
+				type: "leader-ready",
+				brokerInstanceId,
+				leadershipId: msg.leadershipId,
+				leaderTabId: msg.tabId
+			});
+			assignFollowerPorts(ns);
+			break;
+		}
+		case "leader-failed":
+			failPromotion(ns, msg.tabId, msg.leadershipId, { timedOut: false });
+			break;
+		case "follower-port-attached":
+			if (ns.leader?.tabId === msg.tabId && ns.leader.leadershipId === msg.leadershipId) followerAttached(ns, msg.followerTabId);
+			break;
+		case "follower-port-closed": {
+			if (ns.leader?.tabId !== msg.tabId) break;
+			followerAttached(ns, msg.followerTabId);
+			const leaderTab = ns.tabs.get(ns.leader.tabId);
+			const follower = ns.tabs.get(msg.followerTabId);
+			if (leaderTab && follower && ns.leader.ready) mintPorts(ns, leaderTab, follower, ns.leader.leadershipId);
+			break;
+		}
+		case "shutdown":
+			evictTab(ns, msg.tabId, "shutdown");
+			break;
+	}
+}
+/** Attach a connecting tab's port. Exported for the node test harness, which
+*  drives the broker with fake MessagePort pairs instead of a SharedWorker. */
+function handleConnect(port) {
+	port.onmessage = (ev) => {
+		handleTabMessage(port, ev.data, ev.ports ?? []);
+	};
+	port.onmessageerror = () => {
+		const entry = portTab.get(port);
+		if (entry) evictTab(entry.ns, entry.tabId, "messageerror");
+	};
+	port.start?.();
+}
+/** Test-only: wipe module state so each test starts with a fresh broker. */
+function __resetBrokerForTests() {
+	if (pingTimer) clearInterval(pingTimer);
+	pingTimer = null;
+	for (const ns of namespaces.values()) for (const [, retry] of ns.attachRetry) if (retry.timer) clearTimeout(retry.timer);
+	namespaces.clear();
+	portTab.clear();
+	canonicalFingerprint = null;
+	nextLeadershipId = 0;
+}
+if (typeof self !== "undefined") self.onconnect = (event) => {
+	const port = event.ports[0];
+	if (port) handleConnect(port);
+};
+
+//#endregion
+export { __resetBrokerForTests, handleConnect };