svelte-adapter-uws-extensions 0.5.8 → 0.5.10

package/package.json

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

package/redis/cursor.js

@@ -233,6 +233,13 @@ export function createCursor(client, options = {}) {
 							enqueueInbound(parsed.topic, entry.key, entry.data, activePlatform);
 						}
 					}
+				} else if (parsed.event === EVENTS.REMOVE && parsed.payload && typeof parsed.payload.key === 'string') {
+					// Peer-relayed cursor removes are coalesced through the
+					// same tick buffer the local close path uses. Without
+					// this, a mass-disconnect on one instance produces an
+					// equally-sized O(N) immediate-publish storm on every
+					// other instance, propagating the OOM risk cluster-wide.
+					queueRemove(parsed.topic, parsed.payload.key, activePlatform);
 				} else {
 					activePlatform.publish(
 						'__cursor:' + parsed.topic,
@@ -443,6 +450,75 @@ export function createCursor(client, options = {}) {
 	let driftMax = 0;
 	let flushCount = 0;
 
+	// Pending REMOVE keys per topic, coalesced into one wire frame per
+	// subscriber per event-loop iteration. Mass-disconnect scenarios (e.g.
+	// 5K cursors closing in one tick during a stress test or browser-tab
+	// teardown of a packed board) used to fire 5K immediate publishes per
+	// topic, each fanning out to every remaining subscriber. The resulting
+	// O(N^2) uWS send queue allocations OOM-killed workers ~18s into the
+	// cleanup cascade. With this buffer, every subscriber sees one frame
+	// per topic per tick containing the full leave list, regardless of
+	// how many sockets dropped together. Symmetric to the presence
+	// `pendingDiffs` buffer.
+	//
+	// Why `setTimeout(0)` over `queueMicrotask`: uWS dispatches each WS
+	// close as its own JS task, and N-API drains microtasks at the C++/JS
+	// boundary between tasks. A microtask-deferred flush fires BEFORE the
+	// next socket's close handler runs, so cross-socket coalescing is
+	// impossible at the microtask level. `setTimeout(0)` lands in libuv's
+	// timers phase, which fires only after the poll phase has dispatched
+	// every ready socket event in the current iteration.
+	/** @type {Map<string, Set<string>>} */
+	const pendingRemoves = new Map();
+	/** @type {ReturnType<typeof setTimeout> | null} */
+	let removeFlushTimer = null;
+	/** @type {import('svelte-adapter-uws').Platform | null} */
+	let removeFlushPlatform = null;
+
+	function queueRemove(topic, key, platform) {
+		let set = pendingRemoves.get(topic);
+		if (!set) {
+			set = new Set();
+			pendingRemoves.set(topic, set);
+		}
+		set.add(key);
+		removeFlushPlatform = platform;
+		if (removeFlushTimer === null) {
+			removeFlushTimer = setTimeout(flushPendingRemoves, 0);
+			if (removeFlushTimer.unref) removeFlushTimer.unref();
+		}
+	}
+
+	function flushPendingRemoves() {
+		removeFlushTimer = null;
+		const platform = removeFlushPlatform;
+		removeFlushPlatform = null;
+		if (!platform) {
+			pendingRemoves.clear();
+			return;
+		}
+		for (const [topic, keys] of pendingRemoves) {
+			if (keys.size === 0) continue;
+			// publishBatched (adapter >= 0.5.0-next.5) bundles N events into
+			// one wire frame per subscriber. Each subscriber decodes the
+			// individual REMOVE events from the frame, so no client change
+			// is required. Fall back to per-event publishes when the
+			// adapter does not expose publishBatched.
+			if (typeof platform.publishBatched === 'function') {
+				const messages = [];
+				for (const key of keys) {
+					messages.push({ topic: '__cursor:' + topic, event: EVENTS.REMOVE, data: { key } });
+				}
+				try { platform.publishBatched(messages); } catch { /* platform unavailable mid-flight */ }
+			} else {
+				for (const key of keys) {
+					try { platform.publish('__cursor:' + topic, EVENTS.REMOVE, { key }); } catch { /* swallow */ }
+				}
+			}
+		}
+		pendingRemoves.clear();
+	}
+
 	function relay(topic, event, payload) {
 		if (b) { try { b.guard(); } catch { return; } }
 		const msg = JSON.stringify({ instanceId, topic, event, payload });
@@ -694,7 +770,7 @@ export function createCursor(client, options = {}) {
 			if (topicPending.size === 0) redisPending.delete(topic);
 		}
 
-		platform.publish('__cursor:' + topic, EVENTS.REMOVE, { key });
+		queueRemove(topic, key, platform);
 		relay(topic, EVENTS.REMOVE, { key });
 		return true;
 	}
@@ -870,7 +946,7 @@ export function createCursor(client, options = {}) {
 			}
 
 			for (const t of removedTopics) {
-				platform.publish('__cursor:' + t, EVENTS.REMOVE, { key: state.key });
+				queueRemove(t, state.key, platform);
 				const topicMap = topics.get(t);
 				if (topicMap) {
 					topicMap.delete(state.key);
@@ -961,6 +1037,9 @@ export function createCursor(client, options = {}) {
 			}
 			// Tracker-level scheduler timer + dirty-topic set.
 			if (tickTimer !== null) { clearTimeout(tickTimer); tickTimer = null; }
+			if (removeFlushTimer !== null) { clearTimeout(removeFlushTimer); removeFlushTimer = null; }
+			removeFlushPlatform = null;
+			pendingRemoves.clear();
 			dirtyTopics.clear();
 			topics.clear();
 			topicFlush.clear();
@@ -982,6 +1061,9 @@ export function createCursor(client, options = {}) {
 				}
 			}
 			if (tickTimer !== null) { clearTimeout(tickTimer); tickTimer = null; }
+			if (removeFlushTimer !== null) { clearTimeout(removeFlushTimer); removeFlushTimer = null; }
+			removeFlushPlatform = null;
+			pendingRemoves.clear();
 			dirtyTopics.clear();
 			topicFlush.clear();
 			if (subscriber) {
@@ -1048,6 +1130,16 @@ export function createCursor(client, options = {}) {
 					tracker.snapshot(ws, data.topic, platform);
 					return;
 				}
+				// Silent no-op when the caller dispatches a parsed object whose
+				// `type` is not ours. The dispatch-to-all pattern (e.g. forwarding
+				// every unhandled frame to cursor.hooks.message AND
+				// presence.hooks.message and letting each ignore frames not
+				// addressed to it) is legitimate. Only warn on shapes that
+				// indicate the wrong wiring (raw bytes, non-object) where the
+				// developer almost certainly intended a parsed envelope.
+				if (data && typeof data === 'object' && !Array.isArray(data) && typeof data.type === 'string') {
+					return;
+				}
 				_warnCursorHooksMessageShape(data);
 			},
 			close(ws, { platform }) {

package/redis/presence.js

@@ -8,9 +8,10 @@
  * Wire shape clients see on `__presence:{topic}`:
  *   - `state` (sent once on subscribe to a single connection)
  *       payload: `{[userKey]: data}` flat snapshot of current presence
- *   - `diff` (broadcast to topic subscribers, microtask-batched)
+ *   - `diff` (broadcast to topic subscribers, tick-batched)
  *       payload: `{joins: {[key]: data}, leaves: {[key]: data}}`
- *       Same-tick joins+leaves on the same key collapse: latest op wins.
+ *       Joins+leaves on the same key in one event-loop iteration
+ *       collapse: latest op wins.
  *   - `heartbeat` (broadcast to topic subscribers, per heartbeat interval)
  *       payload: array of currently-known user keys
  *
@@ -317,14 +318,29 @@ export function createPresence(client, options = {}) {
 
 	/**
 	 * Per-topic pending diff buffer: latest op per key wins. Joins and
-	 * leaves on the same key in the same microtask collapse so the wire
-	 * only sees the net change. Flushed once per microtask via
-	 * `scheduleFlush`. Mirrors the buffer model the adapter's bundled
-	 * presence plugin uses, so a single client decoder handles both.
+	 * leaves on the same key in one event-loop iteration collapse so the
+	 * wire only sees the net change. Flushed once per iteration via
+	 * `setTimeout(flushPendingDiffs, 0)` armed when the first dirty entry
+	 * lands. Mirrors the buffer model the adapter's bundled presence
+	 * plugin uses, so a single client decoder handles both.
+	 *
+	 * Why `setTimeout(0)` and not `queueMicrotask`: uWS dispatches each WS
+	 * message as its own JS task, and N-API drains microtasks at the C++/JS
+	 * boundary between tasks. A microtask-deferred flush fires BEFORE the
+	 * next socket's handler runs, so cross-socket coalescing is impossible
+	 * at the microtask level - a mass-join into a populated topic produces
+	 * O(N) one-entry publishes instead of one batched diff. `setTimeout(0)`
+	 * lands in libuv's timers phase, which fires only after the poll phase
+	 * has dispatched every ready socket message in the current iteration -
+	 * so all joins arriving together end up in one flush regardless of how
+	 * many task boundaries separate them. Same structural choice the
+	 * 0.5.7 cursor always-tick rewrite locked in.
+	 *
 	 * @type {Map<string, Map<string, { op: 'join' | 'leave', data: Record<string, any> }>>}
 	 */
 	const pendingDiffs = new Map();
-	let diffFlushScheduled = false;
+	/** @type {ReturnType<typeof setTimeout> | null} */
+	let diffFlushTimer = null;
 	/** @type {import('svelte-adapter-uws').Platform | null} */
 	let diffFlushPlatform = null;
 
@@ -339,14 +355,17 @@ export function createPresence(client, options = {}) {
 		}
 		entries.set(key, { op, data });
 		diffFlushPlatform = platform;
-		if (!diffFlushScheduled) {
-			diffFlushScheduled = true;
-			queueMicrotask(flushPendingDiffs);
+		if (diffFlushTimer === null) {
+			diffFlushTimer = setTimeout(flushPendingDiffs, 0);
+			if (diffFlushTimer.unref) diffFlushTimer.unref();
 		}
 	}
 
 	function flushPendingDiffs() {
-		diffFlushScheduled = false;
+		if (diffFlushTimer !== null) {
+			clearTimeout(diffFlushTimer);
+			diffFlushTimer = null;
+		}
 		const platform = diffFlushPlatform;
 		diffFlushPlatform = null;
 		if (!platform) {
@@ -1359,7 +1378,10 @@ export function createPresence(client, options = {}) {
 			syncObservers.clear();
 			syncCounts.clear();
 			pendingDiffs.clear();
-			diffFlushScheduled = false;
+			if (diffFlushTimer !== null) {
+				clearTimeout(diffFlushTimer);
+				diffFlushTimer = null;
+			}
 			diffFlushPlatform = null;
 			connCounter = 0;
 		},
@@ -1379,7 +1401,10 @@ export function createPresence(client, options = {}) {
 			keyspaceSubscribed = false;
 			activePlatform = null;
 			pendingDiffs.clear();
-			diffFlushScheduled = false;
+			if (diffFlushTimer !== null) {
+				clearTimeout(diffFlushTimer);
+				diffFlushTimer = null;
+			}
 			diffFlushPlatform = null;
 		},
 

package/redis/pubsub.js

@@ -120,13 +120,25 @@ export function createPubSubBus(client, options = {}) {
 	/** @type {(() => void) | null} */
 	let unsubscribeBreaker = null;
 
-	// Microtask relay batching: coalesce Redis publishes within a single
-	// event-loop tick into one pipelined round trip. Each envelope tracks
-	// its underlying message count so the relayed-messages counter stays
-	// accurate when batch envelopes carry many messages each.
+	// Tick relay batching: coalesce Redis publishes within a single
+	// event-loop iteration into one pipelined round trip. Each envelope
+	// tracks its underlying message count so the relayed-messages counter
+	// stays accurate when batch envelopes carry many messages each.
+	//
+	// Why `setTimeout(0)` and not `queueMicrotask`: uWS dispatches each WS
+	// message as its own JS task, and N-API drains microtasks at the C++/JS
+	// boundary between tasks. A microtask-deferred flush fires BEFORE the
+	// next socket's handler runs, so cross-socket coalescing is impossible
+	// at the microtask level - N publishes from N socket handlers in the
+	// same iteration produce N Redis round-trips instead of one pipelined
+	// call. `setTimeout(0)` lands in libuv's timers phase, which fires only
+	// after the poll phase has dispatched every ready socket message in the
+	// current iteration. Same structural choice the 0.5.7 cursor always-tick
+	// rewrite locked in.
 	/** @type {Array<{msg: string, count: number}>} */
 	let relayBatch = [];
-	let relayScheduled = false;
+	/** @type {ReturnType<typeof setTimeout> | null} */
+	let relayTimer = null;
 	let relayBatchWarnFired = false;
 
 	function scheduleRelay(msg, count) {
@@ -135,23 +147,26 @@ export function createPubSubBus(client, options = {}) {
 		if (relayBatch.length >= MAX_PUBSUB_RELAY_BATCH_PER_TICK && !relayBatchWarnFired) {
 			relayBatchWarnFired = true;
 			console.warn(
-				'[pubsub] microtask relay batch reached ' + relayBatch.length +
-				' entries in one tick. The batch is drained every microtask, so a ' +
+				'[pubsub] tick relay batch reached ' + relayBatch.length +
+				' entries in one iteration. The batch is drained every tick, so a ' +
 				'caller emitted a million publishes in one synchronous burst - likely ' +
 				'a publish-in-loop without yielding.\n' +
 				'  See: https://svti.me/pubsub-burst'
 			);
 		}
-		if (!relayScheduled) {
-			relayScheduled = true;
-			queueMicrotask(flushRelay);
+		if (relayTimer === null) {
+			relayTimer = setTimeout(flushRelay, 0);
+			if (relayTimer.unref) relayTimer.unref();
 		}
 	}
 
 	function flushRelay() {
 		const batch = relayBatch;
 		relayBatch = [];
-		relayScheduled = false;
+		if (relayTimer !== null) {
+			clearTimeout(relayTimer);
+			relayTimer = null;
+		}
 		if (b) {
 			try { b.guard(); } catch { return; }
 		}
@@ -380,6 +395,11 @@ export function createPubSubBus(client, options = {}) {
 				unsubscribeBreaker();
 				unsubscribeBreaker = null;
 			}
+			if (relayTimer !== null) {
+				clearTimeout(relayTimer);
+				relayTimer = null;
+			}
+			relayBatch = [];
 			if (!active || !subscriber) return;
 			active = false;
 			activePlatform = null;

package/redis/sharded-pubsub.js

@@ -107,16 +107,26 @@ export function createShardedBus(client, options = {}) {
 	/** @type {WeakMap<any, Set<string>>} ws -> set of followed topics */
 	const wsFollows = new WeakMap();
 
-	// One-shot warn flag for the per-tick microtask batch cap.
+	// One-shot warn flag for the per-tick batch cap.
 	let batchChannelsWarnFired = false;
 
-	// Per-channel microtask batch: coalesce SPUBLISHes for the same
-	// channel within one tick into a single pipelined call. Each entry
-	// tracks the underlying topic list so the relayed-messages counter
-	// stays accurate when batch envelopes carry many messages.
+	// Per-channel tick batch: coalesce SPUBLISHes for the same channel
+	// within one event-loop iteration into a single pipelined call. Each
+	// entry tracks the underlying topic list so the relayed-messages
+	// counter stays accurate when batch envelopes carry many messages.
+	//
+	// Why `setTimeout(0)` and not `queueMicrotask`: uWS dispatches each WS
+	// message as its own JS task, and N-API drains microtasks at the C++/JS
+	// boundary between tasks. A microtask-deferred flush fires BEFORE the
+	// next socket's handler runs, so cross-socket coalescing is impossible
+	// at the microtask level. `setTimeout(0)` lands in libuv's timers
+	// phase, which fires only after the poll phase has dispatched every
+	// ready socket message in the current iteration. Same structural
+	// choice the 0.5.7 cursor always-tick rewrite locked in.
 	/** @type {Map<string, Array<{msg: string, topics: string[]}>>} */
 	let channelBatches = new Map();
-	let relayScheduled = false;
+	/** @type {ReturnType<typeof setTimeout> | null} */
+	let relayTimer = null;
 
 	function scheduleRelay(channel, msg, topics) {
 		let arr = channelBatches.get(channel);
@@ -128,23 +138,26 @@ export function createShardedBus(client, options = {}) {
 		if (channelBatches.size >= MAX_SHARDED_BUS_BATCH_CHANNELS_PER_TICK && !batchChannelsWarnFired) {
 			batchChannelsWarnFired = true;
 			console.warn(
-				'[sharded-bus] microtask batch reached ' + channelBatches.size +
-				' distinct channels in one tick. The batch is drained every microtask, ' +
+				'[sharded-bus] tick batch reached ' + channelBatches.size +
+				' distinct channels in one iteration. The batch is drained every tick, ' +
 				'so reaching this size means a publisher emitted a million distinct ' +
 				'channels in one synchronous burst - likely a topic-cardinality leak.\n' +
 				'  See: https://svti.me/sharded-bus-burst'
 			);
 		}
-		if (!relayScheduled) {
-			relayScheduled = true;
-			queueMicrotask(flushRelay);
+		if (relayTimer === null) {
+			relayTimer = setTimeout(flushRelay, 0);
+			if (relayTimer.unref) relayTimer.unref();
 		}
 	}
 
 	function flushRelay() {
 		const batches = channelBatches;
 		channelBatches = new Map();
-		relayScheduled = false;
+		if (relayTimer !== null) {
+			clearTimeout(relayTimer);
+			relayTimer = null;
+		}
 		if (b) {
 			try { b.guard(); } catch { return; }
 		}
@@ -268,7 +281,10 @@ export function createShardedBus(client, options = {}) {
 			subscriber = null;
 		}
 		channelBatches = new Map();
-		relayScheduled = false;
+		if (relayTimer !== null) {
+			clearTimeout(relayTimer);
+			relayTimer = null;
+		}
 		followCounts.clear();
 		channelRefcounts.clear();
 	}