svelte-adapter-uws-extensions 0.5.5 → 0.5.7

package/package.json

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

package/redis/cursor.d.ts

@@ -98,12 +98,17 @@ export interface RedisCursorTracker {
 	 * subscriber set and no client ever sees a cursor frame.
 	 *
 	 * @throws {WsClosedError} (`err.code === 'WS_CLOSED'`) if the websocket
-	 *   has already closed by the time `platform.subscribe` runs. No state
-	 *   to roll back (`wsState` is only created on `update`); callers do
-	 *   not need to compensate. The follow-up `snapshot()` call is skipped
+	 *   has already closed by the time the underlying `ws.subscribe` runs.
+	 *   No state to roll back (`wsState` is only created on `update`); callers
+	 *   do not need to compensate. The follow-up `snapshot()` call is skipped
 	 *   when this throws. Snapshot-send failures on an already-subscribed
 	 *   connection are NOT thrown - cursor frames are self-recovering via
-	 *   the next bulk tick.
+	 *   the next bulk tick. Note: this module uses the uWS-native
+	 *   `ws.subscribe` for `__cursor:*` topics (mirroring presence's
+	 *   `__presence:*` path), not `platform.subscribe` - as of adapter 0.5.5
+	 *   `platform.subscribe` swallows closed-ws throws and returns the same
+	 *   sentinel on success and on close, which would silently break this
+	 *   throw contract.
 	 */
 	attach(ws: any, topic: string, platform: Platform): Promise<void>;
 

package/redis/cursor.js

@@ -143,14 +143,22 @@ export function createCursor(client, options = {}) {
 	const mUpdates = m?.counter('cursor_updates_total', 'Cursor update calls', ['topic']);
 	const mBroadcasts = m?.counter('cursor_broadcasts_total', 'Cursor broadcasts sent', ['topic']);
 	const mThrottled = m?.counter('cursor_throttled_total', 'Cursor updates deferred by throttle', ['topic']);
-	const mAttachesAborted = m?.counter('cursor_attaches_aborted_total', 'Cursor attach calls that aborted because the websocket closed before `platform.subscribe` could complete. Symmetric with `presence_joins_aborted_total`; same `WS_CLOSED` cause.', ['topic', 'reason']);
+	const mAttachesAborted = m?.counter('cursor_attaches_aborted_total', 'Cursor attach calls that aborted because the websocket closed before `ws.subscribe` could complete. Symmetric with `presence_joins_aborted_total`; same `WS_CLOSED` cause.', ['topic', 'reason']);
 
 	const warnSensitive = createSensitiveWarner('redis/cursor');
 
 	let connCounter = 0;
 
 	function safeUserData(ws) {
-		const raw = typeof ws.getUserData === 'function' ? ws.getUserData() : {};
+		// Closed-WS race: getWsState (called from `update`) may reach here
+		// after an `await` that outlasted the socket; `ws.getUserData()`
+		// throws on a freed native handle. Fall back to an empty userData
+		// rather than crashing the worker. Matches adapter 0.5.5's
+		// `plugins/cursor/server.js getWsState` guard.
+		let raw = {};
+		if (typeof ws.getUserData === 'function') {
+			try { raw = ws.getUserData(); } catch { raw = {}; }
+		}
 		if (!raw || typeof raw !== 'object') return {};
 		const { __subscriptions, remoteAddress, ...safeData } = raw;
 		return safeData;
@@ -395,6 +403,9 @@ export function createCursor(client, options = {}) {
 	 * - `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.
+	 *   Initialized to `Date.now() - topicThrottleMs` so the first broadcast
+	 *   on a new topic is "cycle ready" without polluting drift stats with
+	 *   the full `Date.now()` lateness an init of 0 would imply.
 	 *
 	 * @type {Map<string, { dirty: Map<string, { user: any, data: any, platform: any }>, inboundDirty: Map<string, { data: any, platform: any }>, lastFlush: number }>}
 	 */
@@ -554,9 +565,10 @@ export function createCursor(client, options = {}) {
 				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.
+				// Multi-cycle backlog collapse to `now` so the next
+				// broadcast's `Date.now() - lastFlush >= topicThrottleMs`
+				// delay computation does not fire every queued cycle on
+				// this turn.
 				state.lastFlush = drift < topicThrottleMs ? deadline : now;
 			} else if (deadline < nextDeadline) {
 				nextDeadline = deadline;
@@ -575,10 +587,31 @@ export function createCursor(client, options = {}) {
 	}
 
 	/**
-	 * 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).
+	 * Schedule a local cursor for the next coalesced flush. Always-tick: every
+	 * call appends to `state.dirty`, adds the topic to `dirtyTopics`, and arms
+	 * the tracker-wide tick timer. NO leading-edge synchronous fire and NO
+	 * microtask defer.
+	 *
+	 * Why: uWS dispatches each WS message as its own JS task, and N-API
+	 * drains microtasks at the C++/JS boundary between dispatches. A
+	 * `queueMicrotask`-deferred flush fires BEFORE the next socket's message
+	 * handler runs, so cross-socket coalescing is impossible at the microtask
+	 * level. `setTimeout(0)` is in libuv's timers phase and fires only after
+	 * the poll phase processes every ready message on every socket - so all
+	 * broadcasts dispatched in the same loop iteration end up in one flush
+	 * regardless of how many task boundaries separate them.
+	 *
+	 * 0.5.5/0.5.6 shipped a `queueMicrotask` + `pendingMicroflush` variant
+	 * built on the wrong dispatch-model assumption (that co-arriving
+	 * broadcasts share a JS task). Demo measured ~99% single-cursor UPDATE /
+	 * ~1% BULK at 1000-mover load on the deployed 0.5.6 - essentially the
+	 * pre-fix shape. The bench validated the assumed input shape (all
+	 * broadcasts in one synchronous task) instead of the input shape uWS
+	 * actually produces (per-message tasks separated by microtask drains).
+	 *
+	 * First-cursor latency cost of always-tick: up to `topicThrottleMs` (16ms
+	 * default, one frame budget) before fanout. Below the perceptual floor
+	 * for cursors. Same trade-off the adapter's bundled cursor plugin makes.
 	 */
 	function broadcast(topic, key, user, data, platform) {
 		if (topicThrottleMs <= 0) {
@@ -588,23 +621,19 @@ export function createCursor(client, options = {}) {
 
 		let state = topicFlush.get(topic);
 		if (!state) {
-			state = { dirty: new Map(), inboundDirty: new Map(), lastFlush: 0 };
+			// Anchor `lastFlush` one cycle in the past so the first broadcast
+			// is treated as "cycle ready" with zero drift on the very first
+			// tick. Without this, `Date.now() - 0` would be a huge "lateness"
+			// that pollutes the drift stats forever.
+			state = { dirty: new Map(), inboundDirty: new Map(), lastFlush: Date.now() - topicThrottleMs };
 			topicFlush.set(topic, state);
 		}
 		state.dirty.set(key, { user, data, platform });
-
-		const now = Date.now();
-		if (now - state.lastFlush >= topicThrottleMs) {
-			// Leading-edge synchronous flush.
-			state.lastFlush = now;
-			flushBoth(topic, state);
-			dirtyTopics.delete(topic);
-			return;
-		}
-
-		// Within window: trailing-edge flush via the scheduler tick.
 		dirtyTopics.add(topic);
-		armTick(Math.max(0, topicThrottleMs - (now - state.lastFlush)));
+
+		const elapsed = Date.now() - state.lastFlush;
+		const delay = elapsed >= topicThrottleMs ? 0 : topicThrottleMs - elapsed;
+		armTick(delay);
 	}
 
 	/**
@@ -631,21 +660,19 @@ export function createCursor(client, options = {}) {
 
 		let state = topicFlush.get(topic);
 		if (!state) {
-			state = { dirty: new Map(), inboundDirty: new Map(), lastFlush: 0 };
+			state = { dirty: new Map(), inboundDirty: new Map(), lastFlush: Date.now() - topicThrottleMs };
 			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)));
+
+		// Symmetric with `broadcast()` always-tick: both source paths share
+		// the same `state` and the same tracker-wide tick timer, so a local
+		// broadcast and a peer-relayed inbound landing in the same loop
+		// iteration ship together as one combined frame at the next tick.
+		const elapsed = Date.now() - state.lastFlush;
+		const delay = elapsed >= topicThrottleMs ? 0 : topicThrottleMs - elapsed;
+		armTick(delay);
 	}
 
 	async function broadcastRemove(topic, key, platform) {
@@ -675,14 +702,22 @@ export function createCursor(client, options = {}) {
 	/** @type {RedisCursorTracker} */
 	const tracker = {
 		async attach(ws, topic, platform) {
+			// Raw `ws.subscribe` (uWS-native) NOT `platform.subscribe`. As of
+			// adapter 0.5.5 `platform.subscribe` swallows uWS's "closed
+			// websocket" throw and returns the same `null` sentinel it returns
+			// on success, so a try/catch around `platform.subscribe` cannot
+			// distinguish closed-ws from success without racing on
+			// `platform.closedWsAborts`. uWS-native `ws.subscribe` still throws
+			// on closed-ws, so the throw-WsClosedError contract holds. Mirrors
+			// what `presence.join` already does with `ws.subscribe('__presence:...')`.
 			try {
-				platform.subscribe(ws, '__cursor:' + topic);
+				ws.subscribe('__cursor:' + topic);
 			} catch {
-				// ws closed before subscribe could land. No state to roll back
-				// (no wsState entry exists yet; that is only created on update).
-				// Throw so the caller can distinguish a no-op-and-rollback from
-				// a successful attach; without this the RPC metric reports
-				// status=ok for connections that never received cursor frames.
+				// No state to roll back (no `wsState` entry exists yet; that
+				// is only created on `update`). Throw so the caller can
+				// distinguish a no-op-and-rollback from a successful attach;
+				// without this the RPC metric reports `status=ok` for
+				// connections that never received cursor frames.
 				mAttachesAborted?.inc({ topic: mt(topic), reason: 'ws_closed' });
 				throw new WsClosedError('cursor.attach', topic);
 			}

package/redis/pubsub.js

@@ -242,6 +242,7 @@ export function createPubSubBus(client, options = {}) {
 				checkSubscribe: platform.checkSubscribe.bind(platform),
 				get maxPayloadLength() { return platform.maxPayloadLength; },
 				bufferedAmount: platform.bufferedAmount.bind(platform),
+				get closedWsAborts() { return platform.closedWsAborts ?? 0; },
 				// Framework conventions stashed on the source platform by
 				// app init code (e.g. `platform.replay = createReplay(...)`,
 				// `platform.redis = ioredisClient`) must survive the wrap so

package/redis/registry.js

@@ -1008,9 +1008,17 @@ export function createConnectionRegistry(client, options) {
 		hooks: {
 			async open(ws, ctx) {
 				await ensureSubscriber(ctx?.platform);
-				const userId = identify(ws);
-				if (!userId) return;
-				const ud = ws.getUserData ? ws.getUserData() : {};
+				// Closed-WS race: the ws may have closed during the
+				// `await ensureSubscriber` above. `identify(ws)` and the
+				// subsequent `ws.getUserData()` both throw on a freed
+				// native handle; bail silently rather than crashing the
+				// worker. No state to roll back yet.
+				let userId, ud;
+				try {
+					userId = identify(ws);
+					if (!userId) return;
+					ud = ws.getUserData ? ws.getUserData() : {};
+				} catch { return; }
 				// Read the session id via the adapter's slot symbol.
 				const sessionId = sessionIdFromUserData(ud);
 				if (!sessionId) return;

package/redis/sharded-pubsub.js

@@ -531,6 +531,7 @@ export function createShardedBus(client, options = {}) {
 				checkSubscribe: platform.checkSubscribe.bind(platform),
 				get maxPayloadLength() { return platform.maxPayloadLength; },
 				bufferedAmount: platform.bufferedAmount.bind(platform),
+				get closedWsAborts() { return platform.closedWsAborts ?? 0; },
 				// Framework conventions stashed on the source platform by
 				// app init code (e.g. `platform.replay = createReplay(...)`)
 				// must survive the wrap so downstream framework auto-routing

package/testing/mock-platform.js

@@ -16,7 +16,8 @@ export const PLATFORM_KEYS = Object.freeze([
 	'pressure', 'onPressure', 'onPublishRate',
 	'subscribers', 'subscribe', 'unsubscribe', 'checkSubscribe',
 	'topic',
-	'maxPayloadLength', 'bufferedAmount'
+	'maxPayloadLength', 'bufferedAmount',
+	'closedWsAborts'
 ]);
 
 /**
@@ -76,6 +77,12 @@ export function mockPlatform() {
 		bufferedAmount(_ws) {
 			return 0;
 		},
+		// Mirrors adapter 0.5.5's `platform.closedWsAborts` counter.
+		// Tests that want to simulate a non-zero value can reassign
+		// `p.closedWsAborts` directly; the default zero matches a healthy
+		// worker and keeps the parity-test surface symmetric with the
+		// adapter's real platform shape.
+		closedWsAborts: 0,
 		publish(topic, event, data, options) {
 			p.published.push({ topic, event, data, options });
 			return true;