svelte-adapter-uws-extensions 0.5.2 → 0.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-adapter-uws-extensions",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "publishConfig": {
     "tag": "latest"
   },
@@ -154,7 +154,7 @@
     "node": ">=22.0.0"
   },
   "peerDependencies": {
-    "svelte-adapter-uws": "^0.5.2"
+    "svelte-adapter-uws": "^0.5.4"
   },
   "dependencies": {
     "ioredis": "^5.0.0"

package/redis/cursor.d.ts

@@ -127,6 +127,32 @@ export interface RedisCursorTracker {
 	/** Stop the Redis subscriber and clear local timers. */
 	destroy(): void;
 
+	/**
+	 * Snapshot of scheduler health. Always available, near-zero cost.
+	 *
+	 * - `flushes`: total tick-driven flushes since tracker creation.
+	 * - `driftMeanMs`: mean (target_deadline - actual_fire_time) across
+	 *   all tick-driven flushes. 0 means perfect cadence; values >
+	 *   `topicThrottle` indicate sustained event-loop saturation or CPU
+	 *   contention (consider a dedicated-CPU instance, or raise
+	 *   `topicThrottle`).
+	 * - `driftMaxMs`: largest single observed late fire. Useful for
+	 *   spotting one-off GC pauses vs. sustained drift.
+	 * - `dirtyTopicsCurrent`: topics with pending coalesced entries right
+	 *   now. Should hover near zero in healthy operation.
+	 * - `activeTopicsTotal`: topics with at least one local cursor.
+	 *
+	 * Leading-edge synchronous flushes are not counted in drift stats -
+	 * they fire on the call thread, not via the scheduler.
+	 */
+	stats(): {
+		flushes: number;
+		driftMeanMs: number;
+		driftMaxMs: number;
+		dirtyTopicsCurrent: number;
+		activeTopicsTotal: number;
+	};
+
 	/**
 	 * Ready-made WebSocket hooks for cursor tracking.
 	 *

package/redis/cursor.js

@@ -91,6 +91,7 @@ const EVENTS = Object.freeze({
  * @property {(topic: string) => Promise<CursorEntry[]>} list
  * @property {() => Promise<void>} clear
  * @property {() => void} destroy - Stop the Redis subscriber
+ * @property {() => { flushes: number, driftMeanMs: number, driftMaxMs: number, dirtyTopicsCurrent: number, activeTopicsTotal: number }} stats - Scheduler health snapshot
  */
 
 /**
@@ -198,7 +199,29 @@ export function createCursor(client, options = {}) {
 				const parsed = JSON.parse(message);
 				if (parsed.instanceId === instanceId) return;
 				if (!validator.acceptEnvelope(parsed.topic, parsed.event)) return;
-				if (activePlatform) {
+				if (!activePlatform) return;
+
+				// Receiver-side coalescing for high-frequency cursor-position
+				// events. UPDATE / BULK enqueue into the local topic's
+				// inboundDirty map so the NEXT local flush emits one combined
+				// frame covering local + peer cursors. Pre-change, peer-
+				// relayed frames published immediately on receive, producing
+				// tight doublets at subscribers (one frame per worker per
+				// cycle, ms apart). Now one frame per subscriber per cycle
+				// regardless of worker count.
+				//
+				// CATALOG / JOIN / REMOVE stay immediate: low-frequency
+				// roster events where coalescing would add latency without
+				// smoothness benefit.
+				if (parsed.event === EVENTS.UPDATE && parsed.payload && typeof parsed.payload.key === 'string') {
+					enqueueInbound(parsed.topic, parsed.payload.key, parsed.payload.data, activePlatform);
+				} else if (parsed.event === EVENTS.BULK && Array.isArray(parsed.payload)) {
+					for (const entry of parsed.payload) {
+						if (entry && typeof entry.key === 'string') {
+							enqueueInbound(parsed.topic, entry.key, entry.data, activePlatform);
+						}
+					}
+				} else {
 					activePlatform.publish(
 						'__cursor:' + parsed.topic,
 						parsed.event,
@@ -358,11 +381,53 @@ export function createCursor(client, options = {}) {
 	}
 
 	/**
-	 * Per-topic aggregate throttle state.
-	 * @type {Map<string, { lastFlush: number, timer: any, dirty: Map<string, { user: any, data: any, platform: any }> }>}
+	 * Per-topic aggregate flush state.
+	 *
+	 * - `dirty`: locally-originated cursors. Flushed locally AND relayed.
+	 * - `inboundDirty`: cursors received from peer instances via Redis pub/sub.
+	 *   Flushed locally ONLY (re-relaying would loop). Kept separate from
+	 *   `dirty` so the relay payload is structurally a subset of the local
+	 *   flush, not a per-entry origin check.
+	 * - `lastFlush`: target-anchored timestamp of the most recent flush.
+	 *   Advanced by `topicThrottleMs` per cycle (not to actual fire time) so
+	 *   a single late tick does not compound drift on subsequent cycles.
+	 *
+	 * @type {Map<string, { dirty: Map<string, { user: any, data: any, platform: any }>, inboundDirty: Map<string, { data: any, platform: any }>, lastFlush: number }>}
 	 */
 	const topicFlush = new Map();
 
+	/**
+	 * Single scheduler-driven set: topics with at least one dirty entry
+	 * awaiting flush. Bounded by mover count, not topic count, so the
+	 * per-tick walk does not scan idle topics. Updated synchronously on
+	 * `broadcast()` / `enqueueInbound()` and on every tick.
+	 *
+	 * @type {Set<string>}
+	 */
+	const dirtyTopics = new Set();
+
+	/**
+	 * Single timer for the whole tracker. Always points at the next earliest
+	 * topic deadline (or null when idle). Replaces the previous per-topic
+	 * setTimeout pattern: N pending timers -> 1 pending timer regardless of
+	 * topic count. Scheduling overhead is O(dirty topics), not O(active
+	 * topics), and a single late fire affects exactly one cycle (target-
+	 * anchored, no drift compounding).
+	 *
+	 * @type {ReturnType<typeof setTimeout> | null}
+	 */
+	let tickTimer = null;
+
+	/**
+	 * Drift accounting for observability. Updated on every flush in `tick()`.
+	 * Exposed via the `stats()` accessor; optional `metrics` integration
+	 * (Prometheus histogram) is wired separately.
+	 */
+	let driftSum = 0;
+	let driftCount = 0;
+	let driftMax = 0;
+	let flushCount = 0;
+
 	function relay(topic, event, payload) {
 		if (b) { try { b.guard(); } catch { return; } }
 		const msg = JSON.stringify({ instanceId, topic, event, payload });
@@ -388,24 +453,129 @@ export function createCursor(client, options = {}) {
 	}
 
 	/**
-	 * Flush all coalesced entries for a topic as a single `bulk` event.
-	 * Entries carry `{key, data}` only; `user` lives on the catalog channel.
-	 * Per-entry Redis snapshot writes are coalesced through `queueSnapshot`
-	 * onto the snapshot timer.
+	 * Flush a topic's `dirty` + `inboundDirty` maps as a single wire frame to
+	 * local subscribers, then relay the local-origin slice to peers.
+	 *
+	 * - Local subscribers see one combined frame per cycle covering this
+	 *   worker's own cursors PLUS any cursors received from peers since the
+	 *   last flush. Pre-change, peer-relayed cursors emitted as a separate
+	 *   frame immediately on receive, producing tight doublets at subscribers.
+	 * - Peers receive only the local-origin slice (relay payload is built
+	 *   from `dirty`, not from `inboundDirty`). Re-relaying inbound cursors
+	 *   would loop: filtered at the receiver via `instanceId`, but still
+	 *   wastes Redis pub/sub bandwidth.
+	 * - `queueSnapshot` runs for local-origin only. The originating worker
+	 *   owns the Redis HSET for its cursors; receivers must not re-write
+	 *   what the origin already wrote (would double the HSET storm).
+	 *
+	 * Single-entry vs. multi-entry choice mirrors the existing wire shape:
+	 * one cursor -> `update {key, data}`, many -> `bulk [{key, data}, ...]`.
+	 * Subscribers handle both as cursor-position frames.
 	 */
-	function flushBulk(topic, dirty) {
+	function flushBoth(topic, state) {
 		const entries = [];
 		let flushPlatform = null;
-		for (const [k, v] of dirty) {
+		let localCount = 0;
+
+		// Local-origin slice first so we can take a prefix for the relay.
+		for (const [k, v] of state.dirty) {
 			entries.push({ key: k, data: v.data });
 			flushPlatform = v.platform;
 			queueSnapshot(topic, k, v.user, v.data);
+			localCount++;
+		}
+		for (const [k, v] of state.inboundDirty) {
+			entries.push({ key: k, data: v.data });
+			flushPlatform ||= v.platform;
 		}
+
+		state.dirty.clear();
+		state.inboundDirty.clear();
+
 		if (!flushPlatform || entries.length === 0) return;
-		flushPlatform.publish('__cursor:' + topic, EVENTS.BULK, entries);
-		relay(topic, EVENTS.BULK, entries);
+
+		mBroadcasts?.inc({ topic: mt(topic) });
+		flushCount++;
+
+		// Single local publish covering all entries (local + inbound).
+		if (entries.length === 1) {
+			flushPlatform.publish('__cursor:' + topic, EVENTS.UPDATE, entries[0]);
+		} else {
+			flushPlatform.publish('__cursor:' + topic, EVENTS.BULK, entries);
+		}
+
+		// Relay LOCAL-ORIGIN slice only; never re-relay what came from peers.
+		if (localCount > 0) {
+			if (localCount === 1) {
+				relay(topic, EVENTS.UPDATE, entries[0]);
+			} else {
+				relay(topic, EVENTS.BULK, entries.slice(0, localCount));
+			}
+		}
 	}
 
+	/**
+	 * Scheduler tick. Walks `dirtyTopics`, flushes any topic whose deadline
+	 * (`lastFlush + topicThrottleMs`) has passed, and re-arms `tickTimer`
+	 * for the next earliest pending deadline. Topics whose deadline has not
+	 * yet passed stay in `dirtyTopics` for the next tick.
+	 *
+	 * Target-anchored advance: on flush, `lastFlush` is set to the deadline
+	 * (not the actual fire time) so a single late tick does not compound
+	 * drift on subsequent cycles. If we fell behind by more than one cycle
+	 * (event loop saturation > `topicThrottleMs`), `lastFlush` resets to
+	 * `now` to avoid queueing phantom catch-up fires that would all hit the
+	 * next event loop turn.
+	 */
+	function tick() {
+		tickTimer = null;
+		const now = Date.now();
+		let nextDeadline = Infinity;
+
+		for (const topic of dirtyTopics) {
+			const state = topicFlush.get(topic);
+			if (!state) { dirtyTopics.delete(topic); continue; }
+			if (state.dirty.size === 0 && state.inboundDirty.size === 0) {
+				dirtyTopics.delete(topic);
+				continue;
+			}
+			const deadline = state.lastFlush + topicThrottleMs;
+			if (deadline <= now) {
+				const drift = now - deadline;
+				driftSum += drift;
+				driftCount++;
+				if (drift > driftMax) driftMax = drift;
+
+				flushBoth(topic, state);
+				dirtyTopics.delete(topic);
+
+				// Target-anchored: advance lastFlush by the cadence amount.
+				// Multi-cycle backlog collapse to `now` so the next leading-
+				// edge check `(now - lastFlush) >= topicThrottleMs` works as
+				// expected without firing every queued cycle on this turn.
+				state.lastFlush = drift < topicThrottleMs ? deadline : now;
+			} else if (deadline < nextDeadline) {
+				nextDeadline = deadline;
+			}
+		}
+
+		if (nextDeadline !== Infinity) {
+			tickTimer = setTimeout(tick, Math.max(0, nextDeadline - Date.now()));
+		}
+		// else: scheduler goes idle until next broadcast() / enqueueInbound().
+	}
+
+	function armTick(delay) {
+		if (tickTimer !== null) return;
+		tickTimer = setTimeout(tick, delay);
+	}
+
+	/**
+	 * Schedule a local cursor for the next coalesced flush. The leading-
+	 * edge check fires synchronously when `topicThrottleMs` has elapsed
+	 * since the last flush (preserves the contract that the first call on
+	 * an idle topic publishes immediately, without a setTimeout(0) detour).
+	 */
 	function broadcast(topic, key, user, data, platform) {
 		if (topicThrottleMs <= 0) {
 			doBroadcast(topic, key, user, data, platform);
@@ -414,42 +584,64 @@ export function createCursor(client, options = {}) {
 
 		let state = topicFlush.get(topic);
 		if (!state) {
-			state = { lastFlush: 0, timer: null, dirty: new Map() };
+			state = { dirty: new Map(), inboundDirty: new Map(), lastFlush: 0 };
 			topicFlush.set(topic, state);
 		}
-
 		state.dirty.set(key, { user, data, platform });
 
 		const now = Date.now();
-
 		if (now - state.lastFlush >= topicThrottleMs) {
-			if (state.timer) { clearTimeout(state.timer); state.timer = null; }
+			// Leading-edge synchronous flush.
 			state.lastFlush = now;
-			if (state.dirty.size === 1) {
-				const [k, v] = state.dirty.entries().next().value;
-				doBroadcast(topic, k, v.user, v.data, v.platform);
-			} else {
-				flushBulk(topic, state.dirty);
-			}
-			state.dirty.clear();
+			flushBoth(topic, state);
+			dirtyTopics.delete(topic);
 			return;
 		}
 
-		if (!state.timer) {
-			state.timer = setTimeout(() => {
-				const s = topicFlush.get(topic);
-				if (!s) return;
-				s.timer = null;
-				s.lastFlush = Date.now();
-				if (s.dirty.size === 1) {
-					const [k, v] = s.dirty.entries().next().value;
-					doBroadcast(topic, k, v.user, v.data, v.platform);
-				} else {
-					flushBulk(topic, s.dirty);
-				}
-				s.dirty.clear();
-			}, topicThrottleMs - (now - state.lastFlush));
+		// Within window: trailing-edge flush via the scheduler tick.
+		dirtyTopics.add(topic);
+		armTick(Math.max(0, topicThrottleMs - (now - state.lastFlush)));
+	}
+
+	/**
+	 * Schedule a peer-relayed cursor for the next coalesced flush. Symmetric
+	 * to `broadcast()`: same leading/trailing edge semantics, but inbound
+	 * entries route through `state.inboundDirty` so they are visible to
+	 * local subscribers on the next flush WITHOUT being re-relayed to peers
+	 * (which would loop) and WITHOUT being written to Redis (origin owns
+	 * the HSET).
+	 *
+	 * The peer's cross-replica end-to-end latency gains up to one
+	 * `topicThrottleMs` of coalescing delay on the receiver side. Cursors
+	 * are already throttled in the 8-16ms range; adding 8-16ms is well
+	 * below the ~50-100ms human perception threshold for cursor lag. The
+	 * smoothness win (one frame per subscriber per cycle instead of two)
+	 * is the structural benefit.
+	 */
+	function enqueueInbound(topic, key, data, platform) {
+		if (topicThrottleMs <= 0) {
+			// Legacy immediate mode (matches old receiver behavior).
+			platform.publish('__cursor:' + topic, EVENTS.UPDATE, { key, data }, { relay: false });
+			return;
+		}
+
+		let state = topicFlush.get(topic);
+		if (!state) {
+			state = { dirty: new Map(), inboundDirty: new Map(), lastFlush: 0 };
+			topicFlush.set(topic, state);
+		}
+		state.inboundDirty.set(key, { data, platform });
+
+		const now = Date.now();
+		if (now - state.lastFlush >= topicThrottleMs) {
+			state.lastFlush = now;
+			flushBoth(topic, state);
+			dirtyTopics.delete(topic);
+			return;
 		}
+
+		dirtyTopics.add(topic);
+		armTick(Math.max(0, topicThrottleMs - (now - state.lastFlush)));
 	}
 
 	async function broadcastRemove(topic, key, platform) {
@@ -580,6 +772,7 @@ export function createCursor(client, options = {}) {
 							topics.delete(topic);
 							activeTopics.delete(topic);
 							topicFlush.delete(topic);
+							dirtyTopics.delete(topic);
 							redisPending.delete(topic);
 							stopCleanupTimer();
 						}
@@ -637,6 +830,7 @@ export function createCursor(client, options = {}) {
 						topics.delete(t);
 						activeTopics.delete(t);
 						topicFlush.delete(t);
+						dirtyTopics.delete(t);
 						redisPending.delete(t);
 					}
 				}
@@ -717,9 +911,9 @@ export function createCursor(client, options = {}) {
 					if (entry.timer) clearTimeout(entry.timer);
 				}
 			}
-			for (const [, state] of topicFlush) {
-				if (state.timer) clearTimeout(state.timer);
-			}
+			// Tracker-level scheduler timer + dirty-topic set.
+			if (tickTimer !== null) { clearTimeout(tickTimer); tickTimer = null; }
+			dirtyTopics.clear();
 			topics.clear();
 			topicFlush.clear();
 			wsState.clear();
@@ -739,9 +933,8 @@ export function createCursor(client, options = {}) {
 					if (entry.timer) clearTimeout(entry.timer);
 				}
 			}
-			for (const [, state] of topicFlush) {
-				if (state.timer) clearTimeout(state.timer);
-			}
+			if (tickTimer !== null) { clearTimeout(tickTimer); tickTimer = null; }
+			dirtyTopics.clear();
 			topicFlush.clear();
 			if (subscriber) {
 				subscriber.quit().catch(() => subscriber.disconnect());
@@ -750,6 +943,37 @@ export function createCursor(client, options = {}) {
 			activePlatform = null;
 		},
 
+		/**
+		 * Snapshot of scheduler health. Always available, near-zero cost.
+		 *
+		 * - `flushes`: total tick-driven flushes since tracker creation.
+		 * - `driftMeanMs`: mean (target_deadline - actual_fire_time) across
+		 *   all tick-driven flushes. 0 means perfect cadence; values >
+		 *   `topicThrottle` indicate sustained event-loop saturation or
+		 *   CPU contention.
+		 * - `driftMaxMs`: largest single observed late fire. Useful for
+		 *   spotting one-off GC pauses vs. sustained drift.
+		 * - `dirtyTopicsCurrent`: topics with pending coalesced entries
+		 *   right now. Should hover near zero in healthy operation; growth
+		 *   means tick is falling behind.
+		 * - `activeTopicsTotal`: topics with at least one local cursor.
+		 *
+		 * Leading-edge synchronous flushes (first call on an idle topic)
+		 * are not counted in drift stats - they fire on the call thread,
+		 * not via the scheduler.
+		 *
+		 * @returns {{ flushes: number, driftMeanMs: number, driftMaxMs: number, dirtyTopicsCurrent: number, activeTopicsTotal: number }}
+		 */
+		stats() {
+			return {
+				flushes: flushCount,
+				driftMeanMs: driftCount > 0 ? driftSum / driftCount : 0,
+				driftMaxMs: driftMax,
+				dirtyTopicsCurrent: dirtyTopics.size,
+				activeTopicsTotal: topics.size
+			};
+		},
+
 		hooks: {
 			subscribe(ws, topic, { platform }) {
 				if (topic.startsWith('__cursor:')) {
@@ -760,7 +984,23 @@ export function createCursor(client, options = {}) {
 			message(ws, { data, platform }) {
 				if (data && data.type === 'cursor' && data.topic && data.data !== undefined) {
 					tracker.update(ws, data.topic, data.data, platform);
+					return;
+				}
+				// Client-initiated reconnect-snapshot. The cursor plugin client
+				// sends `{type:'cursor-snapshot', topic}` on every status==='open'
+				// (initial connect + reconnect). Pre-fix, this text frame had no
+				// server handler and was a dead wire frame; the snapshot path
+				// only fired through `hooks.subscribe` -> `tracker.snapshot` when
+				// the ws subscribed to the `__cursor:{topic}` channel. With this
+				// branch, the snapshot also re-emits on the explicit frame so a
+				// reconnecting tab that resubscribes via `subscribe-batch` (which
+				// the adapter dedups when the topic is already in the user data
+				// set) still gets a fresh catalog + bulk.
+				if (data && data.type === 'cursor-snapshot' && typeof data.topic === 'string') {
+					tracker.snapshot(ws, data.topic, platform);
+					return;
 				}
+				_warnCursorHooksMessageShape(data);
 			},
 			close(ws, { platform }) {
 				return tracker.remove(ws, platform);
@@ -770,3 +1010,40 @@ export function createCursor(client, options = {}) {
 
 	return tracker;
 }
+
+/**
+ * One-time dev-warn dedup for `cursor.hooks.message` shape misuse. The most
+ * common cause is wiring the hook against `createMessage({ onUnhandled })`
+ * which passes raw bytes, not a parsed envelope. The fix is to switch to
+ * `createMessage({ onJsonMessage(ws, msg, platform) { ... } })` (svelte-
+ * realtime >= 0.5.9 + svelte-adapter-uws >= 0.5.3), which forwards the
+ * parsed object directly.
+ */
+let _cursorHooksMessageBadShapeWarned = false;
+
+/**
+ * @param {any} data
+ */
+function _warnCursorHooksMessageShape(data) {
+	if (_cursorHooksMessageBadShapeWarned) return;
+	_cursorHooksMessageBadShapeWarned = true;
+	const got = data instanceof ArrayBuffer
+		? 'ArrayBuffer (raw bytes -- did you wire this from createMessage({onUnhandled}) ?)'
+		: Array.isArray(data)
+			? 'Array'
+			: data === null
+				? 'null'
+				: typeof data === 'object'
+					? 'object with data.type=' + String(data.type)
+					: typeof data;
+	console.warn(
+		'[redis/cursor] hooks.message called with unexpected shape (' + got + '). ' +
+		'Expected a parsed object {type:"cursor", topic, data} or ' +
+		'{type:"cursor-snapshot", topic}. ' +
+		'If you wired this from `createMessage({ onUnhandled })` and got raw bytes, ' +
+		'switch to `createMessage({ onJsonMessage(ws, msg, platform) { ... } })` ' +
+		'which forwards the parsed JSON envelope. ' +
+		'This warning fires once per process.\n' +
+		'  See: https://svti.me/cursor-hooks-message'
+	);
+}

package/redis/presence.js

@@ -522,8 +522,22 @@ export function createPresence(client, options = {}) {
 					pipe.hpexpire(topicHash, presenceTtlMs, 'FIELDS', 1, userKey);
 				}
 				if (activePlatform) {
-					const keys = [...data.keys()];
-					activePlatform.publish('__presence:' + topic, 'heartbeat', keys);
+					// Publish a `{userKey: data}` map (instead of a key-only
+					// array) so a client whose entry aged out between
+					// heartbeats can re-add it from the heartbeat alone.
+					// Pre-fix, the wire carried only `keys` and the client
+					// handler could only refresh `existing` entries; an
+					// entry the client swept (cross-replica relay latency,
+					// brief backpressure, JS thread saturation) could never
+					// be recovered without a presence_diff for that user.
+					// Older clients fall back gracefully: they see an
+					// object instead of an array and skip the legacy
+					// "refresh-existing" branch, but the next presence_diff
+					// or presence_state still reconciles them.
+					/** @type {Record<string, any>} */
+					const dataMap = {};
+					for (const [userKey, entry] of data) dataMap[userKey] = entry.data;
+					activePlatform.publish('__presence:' + topic, 'heartbeat', dataMap);
 				}
 			}
 		}
@@ -1360,6 +1374,26 @@ export function createPresence(client, options = {}) {
 				}
 				await tracker.join(ws, topic, platform);
 			},
+			message(ws, { data, platform }) {
+				// Client-initiated reconnect-snapshot. The presence plugin
+				// client sends `{type:'presence-snapshot', topic}` on every
+				// status==='open' (initial connect + reconnect). Re-emits
+				// `presence_state` to the requesting ws via `tracker.sync`,
+				// which is the same path that fires on a fresh subscribe.
+				// Symmetric to cursor's `cursor-snapshot` text frame.
+				//
+				// Without this, board-scoped presence stayed stale across
+				// reconnects: a tab that had joined via an RPC saw no
+				// presence_diff during the disconnect window, and on
+				// reconnect its in-memory map was whatever it last knew.
+				// Global presence accidentally self-healed because most
+				// apps call `presence.join('global')` from the `open` hook
+				// which fires on every reconnect; per-board presence does
+				// not have an equivalent auto-rejoin.
+				if (data && data.type === 'presence-snapshot' && typeof data.topic === 'string') {
+					tracker.sync(ws, data.topic, platform).catch(() => { /* surfaced via breaker */ });
+				}
+			},
 			async unsubscribe(ws, topic, { platform }) {
 				if (topic.startsWith('__presence:')) {
 					const realTopic = topic.slice('__presence:'.length);