svelte-adapter-uws-extensions 0.5.4 → 0.5.6

package/package.json

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

package/redis/cursor.d.ts

@@ -74,6 +74,18 @@ export interface CursorEntry {
 	data: any;
 }
 
+/**
+ * Thrown by `attach()` when the websocket closes before `platform.subscribe`
+ * can land. Same shape as `presence.WsClosedError`; catch on `err.code ===
+ * 'WS_CLOSED'` for cross-feature handling.
+ */
+export class WsClosedError extends Error {
+	name: 'WsClosedError';
+	code: 'WS_CLOSED';
+	operation: string;
+	topic: string;
+}
+
 export interface RedisCursorTracker {
 	/**
 	 * Opt this connection into receiving cursor updates for `topic`.
@@ -84,6 +96,19 @@ export interface RedisCursorTracker {
 	 *
 	 * Without `attach`, the publishes in `update` fan out to an empty
 	 * 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 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. 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

@@ -40,6 +40,9 @@ import { stripInternal, createSensitiveWarner } from '../shared/sensitive.js';
 import { scanAndUnlink } from '../shared/redis-scan.js';
 import { MAX_CURSOR_WS, MAX_CURSOR_TOPICS } from '../shared/caps.js';
 import { createBusValidator } from '../shared/bus-validate.js';
+import { WsClosedError } from '../shared/errors.js';
+
+export { WsClosedError };
 
 /** Wire-protocol event names this module emits. */
 const EVENTS = Object.freeze({
@@ -140,13 +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 `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;
@@ -391,8 +403,16 @@ 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.
+	 * - `pendingMicroflush`: a leading-edge flush is queued for the current
+	 *   cadence slot; co-arriving broadcasts (from either local OR peer-
+	 *   relay sources) in the same JS pass append to `dirty` /
+	 *   `inboundDirty` and ship as one combined frame when the microtask
+	 *   runs. Without this, a single co-arriving cursor fired alone as a
+	 *   single-cursor UPDATE while every other cursor in the same pass
+	 *   queued for the trailing tick - 86 percent fragmentation observed at
+	 *   1000-mover load on Hetzner CCX13 with `topicThrottle: 8`.
 	 *
-	 * @type {Map<string, { dirty: Map<string, { user: any, data: any, platform: any }>, inboundDirty: Map<string, { data: any, platform: any }>, lastFlush: number }>}
+	 * @type {Map<string, { dirty: Map<string, { user: any, data: any, platform: any }>, inboundDirty: Map<string, { data: any, platform: any }>, lastFlush: number, pendingMicroflush: boolean }>}
 	 */
 	const topicFlush = new Map();
 
@@ -571,10 +591,21 @@ 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. The leading-edge
+	 * check claims the cadence slot synchronously when `topicThrottleMs` has
+	 * elapsed since the last flush, then defers the actual `flushBoth` by one
+	 * microtask. Co-arriving broadcasts in the same JS pass (from this
+	 * function OR `enqueueInbound` - they share `state.pendingMicroflush`)
+	 * see `now - state.lastFlush < topicThrottleMs` and take the trailing
+	 * path, accumulating into `state.dirty` / `state.inboundDirty`. The
+	 * microtask then flushes everything as one combined frame.
+	 *
+	 * Without this defer, the first cursor in a post-pause burst fires alone
+	 * as a single-cursor UPDATE while every co-arriving cursor in the same
+	 * pass queues for the trailing tick. Demo measured 86 percent
+	 * fragmentation (1794 single UPDATEs vs 38 BULKs in 30s) at 1000-mover
+	 * load on Hetzner CCX13 with `topicThrottle: 8`. After the defer:
+	 * single UPDATE rate collapses, BULK rate matches cycle rate.
 	 */
 	function broadcast(topic, key, user, data, platform) {
 		if (topicThrottleMs <= 0) {
@@ -584,17 +615,28 @@ 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: 0, pendingMicroflush: false };
 			topicFlush.set(topic, state);
 		}
 		state.dirty.set(key, { user, data, platform });
 
 		const now = Date.now();
 		if (now - state.lastFlush >= topicThrottleMs) {
-			// Leading-edge synchronous flush.
+			// Claim the cadence slot synchronously so subsequent broadcasts
+			// in the same JS pass take the trailing path and accumulate.
 			state.lastFlush = now;
-			flushBoth(topic, state);
 			dirtyTopics.delete(topic);
+			if (!state.pendingMicroflush) {
+				state.pendingMicroflush = true;
+				queueMicrotask(() => {
+					state.pendingMicroflush = false;
+					// flushBoth clears `dirty` and `inboundDirty` internally
+					// and early-returns on empty; this guard saves the
+					// for-of entry cost on the empty case.
+					if (state.dirty.size === 0 && state.inboundDirty.size === 0) return;
+					flushBoth(topic, state);
+				});
+			}
 			return;
 		}
 
@@ -627,16 +669,26 @@ 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: 0, pendingMicroflush: false };
 			topicFlush.set(topic, state);
 		}
 		state.inboundDirty.set(key, { data, platform });
 
 		const now = Date.now();
 		if (now - state.lastFlush >= topicThrottleMs) {
+			// Symmetric with `broadcast()`: same shared `pendingMicroflush`
+			// per topic state, so if a local broadcast already claimed the
+			// slot the peer-relay entry just appends and ships with it.
 			state.lastFlush = now;
-			flushBoth(topic, state);
 			dirtyTopics.delete(topic);
+			if (!state.pendingMicroflush) {
+				state.pendingMicroflush = true;
+				queueMicrotask(() => {
+					state.pendingMicroflush = false;
+					if (state.dirty.size === 0 && state.inboundDirty.size === 0) return;
+					flushBoth(topic, state);
+				});
+			}
 			return;
 		}
 
@@ -671,11 +723,28 @@ 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 {
-				return;
+				// 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);
 			}
+			// snapshot() itself swallows ws-closed during platform.send (the
+			// state is already committed; clients recover via the next bulk
+			// frame). Intentional asymmetry with subscribe failure above.
 			await tracker.snapshot(ws, topic, platform);
 		},
 

package/redis/presence.d.ts

@@ -51,10 +51,29 @@ export interface PresenceMetricsSnapshot {
 	staleCleanedTotal: number;
 }
 
+/**
+ * Thrown by `join()` when the websocket closes during an async gap before
+ * the join can commit. Server-side state is fully rolled back before the
+ * throw. Catch on `err.code === 'WS_CLOSED'` rather than the class - the
+ * same code is shared with `cursor.attach` and any future RPC-shaped
+ * operation in this package.
+ */
+export class WsClosedError extends Error {
+	name: 'WsClosedError';
+	code: 'WS_CLOSED';
+	operation: string;
+	topic: string;
+}
+
 export interface RedisPresenceTracker {
 	/**
 	 * Add a connection to a topic's presence.
 	 * Ignores `__`-prefixed topics. Idempotent.
+	 *
+	 * @throws {WsClosedError} (`err.code === 'WS_CLOSED'`) if the websocket
+	 *   closes during one of the internal async gaps (subscribe, Redis eval,
+	 *   snapshot fetch, ws.subscribe). Server state is rolled back before
+	 *   the throw; callers do not need to compensate.
 	 */
 	join(ws: any, topic: string, platform: Platform): Promise<void>;
 

package/redis/presence.js

@@ -47,6 +47,9 @@ import { stripInternal, createSensitiveWarner } from '../shared/sensitive.js';
 import { scanAndUnlink } from '../shared/redis-scan.js';
 import { withBreaker } from '../shared/breaker.js';
 import { MAX_PRESENCE_WS, MAX_PRESENCE_TOPICS } from '../shared/caps.js';
+import { WsClosedError } from '../shared/errors.js';
+
+export { WsClosedError };
 
 /**
  * Lua script for atomic JOIN. Sets this instance's field on the per-user
@@ -247,6 +250,7 @@ export function createPresence(client, options = {}) {
 	const m = options.metrics;
 	const mt = m?.mapTopic;
 	const mJoins = m?.counter('presence_joins_total', 'Presence join events', ['topic']);
+	const mJoinsAborted = m?.counter('presence_joins_aborted_total', 'Presence join calls that aborted before commit because the websocket closed during an async gap. Server state was rolled back before the throw. Distinct from `presence_joins_total` (commits) and from generic RPC error metrics (which bucket all throws together regardless of cause).', ['topic', 'reason']);
 	const mLeaves = m?.counter('presence_leaves_total', 'Presence leave events', ['topic']);
 	const mHeartbeats = m?.counter('presence_heartbeats_total', 'Heartbeat refresh cycles');
 	const mTotalOnline = m?.gauge('presence_total_online', 'Unique users present per topic on this instance', ['topic']);
@@ -985,6 +989,15 @@ export function createPresence(client, options = {}) {
 		}
 	}
 
+	// Throw helper for "ws closed during async gap" paths inside join(). All
+	// five callsites need the same metric label and the same typed error;
+	// inlining a helper avoids drift between them and keeps each callsite
+	// single-line.
+	function throwWsClosed(topic) {
+		mJoinsAborted?.inc({ topic: mt(topic), reason: 'ws_closed' });
+		throw new WsClosedError('presence.join', topic);
+	}
+
 	/** @type {RedisPresenceTracker} */
 	const tracker = {
 		async join(ws, topic, platform) {
@@ -1071,11 +1084,15 @@ export function createPresence(client, options = {}) {
 				throw err;
 			}
 
-			if (!wsTopics.has(ws)) return;
+			// ws closed during `await subscribeToTopic`. The close hook already
+			// ran leaveAll, which swept localCounts / wsTopics for this ws;
+			// no compensating undoJoin needed. Throw so the caller sees the
+			// abort instead of a silent success.
+			if (!wsTopics.has(ws)) throwWsClosed(topic);
 
 			try { ws.getBufferedAmount(); } catch {
 				await undoJoin(ws, topic, key, data, prevCount, prevData, false, false, platform);
-				return;
+				throwWsClosed(topic);
 			}
 
 			let didRedisWrite = false;
@@ -1108,13 +1125,14 @@ export function createPresence(client, options = {}) {
 
 				if (!wsTopics.has(ws)) {
 					// ws closed during the eval. Roll back our Redis write so
-					// the per-user hash entry does not linger past TTL.
+					// the per-user hash entry does not linger past TTL, then
+					// surface the abort to the caller.
 					await redis.eval(
 						LEAVE_SCRIPT, 2,
 						userHashKey(topic, key), topicHashKey(topic),
 						instanceId, key
 					).catch(() => {});
-					return;
+					throwWsClosed(topic);
 				}
 			} else if (prevData !== undefined && !deepEqual(prevData, data)) {
 				// Same instance, same user, different `select()` output.
@@ -1157,7 +1175,7 @@ export function createPresence(client, options = {}) {
 				ws.subscribe('__presence:' + topic);
 			} catch {
 				await undoJoin(ws, topic, key, data, prevCount, prevData, didRedisWrite, false, platform);
-				return;
+				throwWsClosed(topic);
 			}
 
 			// If ws closed after subscribe, leave() already handled
@@ -1170,7 +1188,7 @@ export function createPresence(client, options = {}) {
 						instanceId, key
 					).catch(() => {});
 				}
-				return;
+				throwWsClosed(topic);
 			}
 
 			// Commit localData and activeTopics now that the join is

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/shared/errors.js

@@ -57,3 +57,41 @@ export class IdempotencyResultTooLargeError extends Error {
 		this.maxBytes = maxBytes;
 	}
 }
+
+/**
+ * Thrown by RPC-shaped operations (`presence.join`, `cursor.attach`) when the
+ * caller's websocket closes during an async gap before the operation could
+ * commit, OR the websocket was already gone by the time the operation
+ * resumed from one of its awaits. Server-side state is fully rolled back
+ * before the throw so the caller does not need to compensate.
+ *
+ * Stable contract: `err.code === 'WS_CLOSED'`. Catch on the code, not the
+ * class - future RPC-shaped operations that hit the same pattern throw the
+ * same code. The `operation` field carries the dotted path (e.g.
+ * `'presence.join'`) for operators that want to bucket by feature without
+ * parsing the message.
+ *
+ * Pattern in callers:
+ *
+ * ```js
+ * try {
+ *   await presence.join(ws, topic, platform);
+ * } catch (err) {
+ *   if (err.code === 'WS_CLOSED') return; // ws already gone, no compensation needed
+ *   throw err;
+ * }
+ * ```
+ */
+export class WsClosedError extends Error {
+	/**
+	 * @param {string} operation - Dotted operation path, e.g. `'presence.join'`.
+	 * @param {string} topic
+	 */
+	constructor(operation, topic) {
+		super(`${operation}: websocket closed during async gap (topic="${topic}"); rolled back`);
+		this.name = 'WsClosedError';
+		this.code = 'WS_CLOSED';
+		this.operation = operation;
+		this.topic = topic;
+	}
+}

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;