svelte-adapter-uws-extensions 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-adapter-uws-extensions",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Redis and Postgres extensions for svelte-adapter-uws - distributed pub/sub, replay buffers, presence tracking, rate limiting, groups, and DB change notifications",
   "author": "Kevin Radziszewski",
   "license": "MIT",

package/redis/cursor.d.ts

@@ -9,6 +9,15 @@ export interface RedisCursorOptions {
 	 */
 	throttle?: number;
 
+	/**
+	 * Minimum ms between aggregate broadcasts per topic, across all
+	 * connections. Caps total Redis writes regardless of connection count.
+	 * Set to ~16 (60 broadcasts/sec) to prevent Redis saturation under
+	 * high concurrency. 0 disables the aggregate throttle.
+	 * @default 0
+	 */
+	topicThrottle?: number;
+
 	/**
 	 * Extract user-identifying data from userData.
 	 * Broadcast alongside cursor data so other clients know who the cursor belongs to.

package/redis/cursor.js

@@ -49,6 +49,9 @@ return removed
  * @typedef {Object} RedisCursorOptions
  * @property {number} [throttle=50] - Minimum ms between broadcasts per user per topic.
  *   Trailing-edge timer fires to ensure the final position is always sent.
+ * @property {number} [topicThrottle=0] - Minimum ms between aggregate broadcasts per
+ *   topic. Caps total Redis writes regardless of connection count. 0 = no limit.
+ *   Set to ~16 (60/sec) to prevent Redis saturation under high concurrency.
  * @property {(userData: any) => any} [select] - Extract user-identifying data from userData.
  *   Defaults to the full userData.
  * @property {number} [ttl=30] - TTL in seconds for hash entries. Should be longer than
@@ -80,6 +83,7 @@ return removed
  */
 export function createCursor(client, options = {}) {
 	const throttleMs = options.throttle ?? 50;
+	const topicThrottleMs = options.topicThrottle ?? 0;
 	const select = options.select || ((userData) => userData);
 	const cursorTtl = options.ttl || 30;
 
@@ -189,7 +193,16 @@ export function createCursor(client, options = {}) {
 	/**
 	 * Broadcast locally + relay to other instances via Redis.
 	 */
-	function broadcast(topic, key, user, data, platform) {
+	/**
+	 * Per-topic aggregate throttle state.
+	 * When topicThrottleMs > 0, excess broadcasts are coalesced and
+	 * flushed on a trailing-edge timer so total Redis load per topic
+	 * is capped regardless of connection count.
+	 * @type {Map<string, { lastFlush: number, timer: any, dirty: Map<string, { user: any, data: any, platform: any }> }>}
+	 */
+	const topicFlush = new Map();
+
+	function doBroadcast(topic, key, user, data, platform) {
 		// Local broadcast
 		platform.publish('__cursor:' + topic, 'update', { key, user, data });
 
@@ -208,6 +221,97 @@ export function createCursor(client, options = {}) {
 		redis.publish(channel, msg).catch(() => {});
 	}
 
+	/**
+	 * Flush all coalesced entries for a topic as a single "bulk" event.
+	 * The client receives one event with all cursor positions instead of
+	 * N individual events landing in the same microtask. This turns N
+	 * store updates per frame into one, and reduces Redis PUBLISH calls
+	 * from N to 1 per flush window.
+	 *
+	 * Each entry is still persisted individually to the Redis hash so
+	 * the per-key TTL and staleness detection work unchanged.
+	 */
+	function flushBulk(topic, dirty) {
+		const entries = [];
+		const now = Date.now();
+		let flushPlatform = null;
+
+		for (const [k, v] of dirty) {
+			entries.push({ key: k, user: v.user, data: v.data });
+			flushPlatform = v.platform;
+			// Persist each entry individually to Redis hash
+			redis.hset(hashKey(topic), k, JSON.stringify({ user: v.user, data: v.data, ts: now })).catch(() => {});
+		}
+
+		redis.expire(hashKey(topic), cursorTtl).catch(() => {});
+
+		if (flushPlatform) {
+			// Single local broadcast with all positions
+			flushPlatform.publish('__cursor:' + topic, 'bulk', entries);
+
+			// Single relay to other instances
+			const msg = JSON.stringify({
+				instanceId,
+				topic,
+				event: 'bulk',
+				payload: entries
+			});
+			redis.publish(channel, msg).catch(() => {});
+		}
+	}
+
+	function broadcast(topic, key, user, data, platform) {
+		if (topicThrottleMs <= 0) {
+			doBroadcast(topic, key, user, data, platform);
+			return;
+		}
+
+		// Per-topic aggregate throttle
+		let state = topicFlush.get(topic);
+		if (!state) {
+			state = { lastFlush: 0, timer: null, dirty: new Map() };
+			topicFlush.set(topic, state);
+		}
+
+		// Always store the latest data per key
+		state.dirty.set(key, { user, data, platform });
+
+		const now = Date.now();
+
+		// Leading edge: flush immediately if window has passed
+		if (now - state.lastFlush >= topicThrottleMs) {
+			if (state.timer) { clearTimeout(state.timer); state.timer = null; }
+			state.lastFlush = now;
+			if (state.dirty.size === 1) {
+				// Single entry: use normal event so the client does not
+				// need to handle bulk for the common non-contended case.
+				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();
+			return;
+		}
+
+		// Trailing edge: schedule flush at end of window
+		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));
+		}
+	}
+
 	function broadcastRemove(topic, key, platform) {
 		platform.publish('__cursor:' + topic, 'remove', { key });
 
@@ -346,7 +450,11 @@ export function createCursor(client, options = {}) {
 					if (entry.timer) clearTimeout(entry.timer);
 				}
 			}
+			for (const [, state] of topicFlush) {
+				if (state.timer) clearTimeout(state.timer);
+			}
 			topics.clear();
+			topicFlush.clear();
 			wsState.clear();
 			activeTopics.clear();
 			connCounter = 0;
@@ -371,6 +479,10 @@ export function createCursor(client, options = {}) {
 					if (entry.timer) clearTimeout(entry.timer);
 				}
 			}
+			for (const [, state] of topicFlush) {
+				if (state.timer) clearTimeout(state.timer);
+			}
+			topicFlush.clear();
 			if (subscriber) {
 				subscriber.quit().catch(() => subscriber.disconnect());
 				subscriber = null;

package/redis/presence.js

@@ -60,11 +60,17 @@ for i = 1, #all, 2 do
   end
 end
 
-local result = {isFirst}
-for i = 1, #all do
-  result[#result + 1] = all[i]
+-- For small hashes return entries inline (saves a round trip).
+-- For large hashes return only the flag; the caller fetches the
+-- list via a coalesced HGETALL shared across concurrent joiners.
+if #all <= 200 then
+  local result = {isFirst}
+  for i = 1, #all do
+    result[#result + 1] = all[i]
+  end
+  return result
 end
-return result
+return {isFirst}
 `;
 
 /**
@@ -268,6 +274,22 @@ export function createPresence(client, options = {}) {
 	/** @type {Set<string>} */
 	const activeTopics = new Set();
 	const heartbeatTimer = setInterval(() => {
+		// Detect dead connections whose close handler never fired.
+		// Under mass disconnect, the runtime may drop close events.
+		// Probe each tracked ws; if the probe throws the socket is
+		// dead and we synchronously purge it from local state so the
+		// refresh loop below never touches it.
+		if (activePlatform) {
+			const dead = [];
+			for (const [ws] of wsTopics) {
+				try { ws.getBufferedAmount(); } catch { dead.push(ws); }
+			}
+			for (const ws of dead) {
+				// Full leave (sync Phase 1 + async Phase 2 fire-and-forget)
+				tracker.leave(ws, activePlatform).catch(() => {});
+			}
+		}
+
 		const now = Date.now();
 		for (const topic of activeTopics) {
 			const data = localData.get(topic);
@@ -385,15 +407,14 @@ export function createPresence(client, options = {}) {
 			// cleaned local state -- undo any Redis write and bail out.
 			if (!wsTopics.has(ws)) return;
 
-			// all will hold the raw hash entries for the initial list.
-			// When prevCount === 0 the Lua script returns them inline
-			// (no separate HGETALL needed). Otherwise we coalesce so
-			// N connections joining the same topic share one round trip.
 			let all;
 
 			if (prevCount === 0) {
 				// New user on this instance -- single Lua call does
-				// HSET + EXPIRE + dedup check + returns all entries.
+				// HSET + EXPIRE + dedup check.  For small hashes the
+				// script returns all entries inline (1 round trip).
+				// For large hashes it returns only the dedup flag and
+				// we fetch the list via coalesceHgetall below.
 				const now = Date.now();
 				const field = compoundField(key);
 				const value = JSON.stringify({ data, ts: now });
@@ -410,11 +431,14 @@ export function createPresence(client, options = {}) {
 					return;
 				}
 
-				// Parse result: [isFirst, field1, val1, field2, val2, ...]
 				const isFirstGlobally = result[0];
-				all = {};
-				for (let i = 1; i < result.length; i += 2) {
-					all[result[i]] = result[i + 1];
+
+				if (result.length > 1) {
+					// Small hash: entries returned inline
+					all = {};
+					for (let i = 1; i < result.length; i += 2) {
+						all[result[i]] = result[i + 1];
+					}
 				}
 
 				if (isFirstGlobally === 1) {
@@ -422,7 +446,12 @@ export function createPresence(client, options = {}) {
 					platform.publish('__presence:' + topic, 'join', payload);
 					await publishEvent(topic, 'join', payload);
 				}
-			} else {
+			}
+
+			// Fetch initial list via coalesced HGETALL when the script
+			// did not return entries inline (large hash or dedup join).
+			// Concurrent joiners share a single Redis round trip.
+			if (!all) {
 				all = await coalesceHgetall(topic);
 			}
 
@@ -574,23 +603,39 @@ export function createPresence(client, options = {}) {
 
 			// Phase 2: Async Redis cleanup. Local state is already clean so
 			// the heartbeat will not refresh any of these entries.
-			for (const { topic, key, data, needsUnsub } of pendingLeaves) {
+			// Use a pipeline to batch all LEAVE_SCRIPT EVALs into a single
+			// Redis round trip. Under mass disconnect (1000+ connections)
+			// this avoids overwhelming the Redis command queue.
+			for (const { needsUnsub, topic } of pendingLeaves) {
 				if (needsUnsub) {
 					await unsubscribeFromTopic(topic);
 				}
+			}
 
+			const now = Date.now();
+			const pipe = redis.pipeline();
+			for (const { topic, key } of pendingLeaves) {
 				const field = compoundField(key);
 				const suffix = '|' + key;
-				const now = Date.now();
-				const userGone = await redis.eval(
-					LEAVE_SCRIPT, 1, hashKey(topic), field, suffix, now, presenceTtlMs
-				);
+				pipe.eval(LEAVE_SCRIPT, 1, hashKey(topic), field, suffix, now, presenceTtlMs);
+			}
 
-				if (userGone === 1) {
-					const payload = { key, data };
-					platform.publish('__presence:' + topic, 'leave', payload);
-					await publishEvent(topic, 'leave', payload);
-				}
+			let results;
+			try {
+				results = await pipe.exec();
+			} catch {
+				// Pipeline failed -- CLEANUP_SCRIPT will handle stale entries via TTL
+				return;
+			}
+
+			// Broadcast leave events for users that are completely gone
+			for (let i = 0; i < pendingLeaves.length; i++) {
+				const [err, userGone] = results[i];
+				if (err || userGone !== 1) continue;
+				const { topic, key, data } = pendingLeaves[i];
+				const payload = { key, data };
+				platform.publish('__presence:' + topic, 'leave', payload);
+				await publishEvent(topic, 'leave', payload);
 			}
 
 			// Async unsubscribe for sync-only observer topics