svelte-adapter-uws-extensions 0.5.4 → 0.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-adapter-uws-extensions",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "publishConfig": {
     "tag": "latest"
   },

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,14 @@ 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 `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
+	 *   when this throws. Snapshot-send failures on an already-subscribed
+	 *   connection are NOT thrown - cursor frames are self-recovering via
+	 *   the next bulk tick.
 	 */
 	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,6 +143,7 @@ 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 warnSensitive = createSensitiveWarner('redis/cursor');
 
@@ -674,8 +678,17 @@ export function createCursor(client, options = {}) {
 			try {
 				platform.subscribe(ws, '__cursor:' + topic);
 			} catch {
-				return;
+				// 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.
+				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/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;
+	}
+}