svelte-adapter-uws-extensions 0.5.3 → 0.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-adapter-uws-extensions",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "publishConfig": {
     "tag": "latest"
   },
@@ -154,7 +154,7 @@
     "node": ">=22.0.0"
   },
   "peerDependencies": {
-    "svelte-adapter-uws": "^0.5.3"
+    "svelte-adapter-uws": "^0.5.4"
   },
   "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,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>;
 
@@ -127,6 +147,32 @@ export interface RedisCursorTracker {
 	/** Stop the Redis subscriber and clear local timers. */
 	destroy(): void;
 
+	/**
+	 * Snapshot of scheduler health. Always available, near-zero cost.
+	 *
+	 * - `flushes`: total tick-driven flushes since tracker creation.
+	 * - `driftMeanMs`: mean (target_deadline - actual_fire_time) across
+	 *   all tick-driven flushes. 0 means perfect cadence; values >
+	 *   `topicThrottle` indicate sustained event-loop saturation or CPU
+	 *   contention (consider a dedicated-CPU instance, or raise
+	 *   `topicThrottle`).
+	 * - `driftMaxMs`: largest single observed late fire. Useful for
+	 *   spotting one-off GC pauses vs. sustained drift.
+	 * - `dirtyTopicsCurrent`: topics with pending coalesced entries right
+	 *   now. Should hover near zero in healthy operation.
+	 * - `activeTopicsTotal`: topics with at least one local cursor.
+	 *
+	 * Leading-edge synchronous flushes are not counted in drift stats -
+	 * they fire on the call thread, not via the scheduler.
+	 */
+	stats(): {
+		flushes: number;
+		driftMeanMs: number;
+		driftMaxMs: number;
+		dirtyTopicsCurrent: number;
+		activeTopicsTotal: number;
+	};
+
 	/**
 	 * Ready-made WebSocket hooks for cursor tracking.
 	 *

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({
@@ -91,6 +94,7 @@ const EVENTS = Object.freeze({
  * @property {(topic: string) => Promise<CursorEntry[]>} list
  * @property {() => Promise<void>} clear
  * @property {() => void} destroy - Stop the Redis subscriber
+ * @property {() => { flushes: number, driftMeanMs: number, driftMaxMs: number, dirtyTopicsCurrent: number, activeTopicsTotal: number }} stats - Scheduler health snapshot
  */
 
 /**
@@ -139,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');
 
@@ -198,7 +203,29 @@ export function createCursor(client, options = {}) {
 				const parsed = JSON.parse(message);
 				if (parsed.instanceId === instanceId) return;
 				if (!validator.acceptEnvelope(parsed.topic, parsed.event)) return;
-				if (activePlatform) {
+				if (!activePlatform) return;
+
+				// Receiver-side coalescing for high-frequency cursor-position
+				// events. UPDATE / BULK enqueue into the local topic's
+				// inboundDirty map so the NEXT local flush emits one combined
+				// frame covering local + peer cursors. Pre-change, peer-
+				// relayed frames published immediately on receive, producing
+				// tight doublets at subscribers (one frame per worker per
+				// cycle, ms apart). Now one frame per subscriber per cycle
+				// regardless of worker count.
+				//
+				// CATALOG / JOIN / REMOVE stay immediate: low-frequency
+				// roster events where coalescing would add latency without
+				// smoothness benefit.
+				if (parsed.event === EVENTS.UPDATE && parsed.payload && typeof parsed.payload.key === 'string') {
+					enqueueInbound(parsed.topic, parsed.payload.key, parsed.payload.data, activePlatform);
+				} else if (parsed.event === EVENTS.BULK && Array.isArray(parsed.payload)) {
+					for (const entry of parsed.payload) {
+						if (entry && typeof entry.key === 'string') {
+							enqueueInbound(parsed.topic, entry.key, entry.data, activePlatform);
+						}
+					}
+				} else {
 					activePlatform.publish(
 						'__cursor:' + parsed.topic,
 						parsed.event,
@@ -358,11 +385,53 @@ export function createCursor(client, options = {}) {
 	}
 
 	/**
-	 * Per-topic aggregate throttle state.
-	 * @type {Map<string, { lastFlush: number, timer: any, dirty: Map<string, { user: any, data: any, platform: any }> }>}
+	 * Per-topic aggregate flush state.
+	 *
+	 * - `dirty`: locally-originated cursors. Flushed locally AND relayed.
+	 * - `inboundDirty`: cursors received from peer instances via Redis pub/sub.
+	 *   Flushed locally ONLY (re-relaying would loop). Kept separate from
+	 *   `dirty` so the relay payload is structurally a subset of the local
+	 *   flush, not a per-entry origin check.
+	 * - `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.
+	 *
+	 * @type {Map<string, { dirty: Map<string, { user: any, data: any, platform: any }>, inboundDirty: Map<string, { data: any, platform: any }>, lastFlush: number }>}
 	 */
 	const topicFlush = new Map();
 
+	/**
+	 * Single scheduler-driven set: topics with at least one dirty entry
+	 * awaiting flush. Bounded by mover count, not topic count, so the
+	 * per-tick walk does not scan idle topics. Updated synchronously on
+	 * `broadcast()` / `enqueueInbound()` and on every tick.
+	 *
+	 * @type {Set<string>}
+	 */
+	const dirtyTopics = new Set();
+
+	/**
+	 * Single timer for the whole tracker. Always points at the next earliest
+	 * topic deadline (or null when idle). Replaces the previous per-topic
+	 * setTimeout pattern: N pending timers -> 1 pending timer regardless of
+	 * topic count. Scheduling overhead is O(dirty topics), not O(active
+	 * topics), and a single late fire affects exactly one cycle (target-
+	 * anchored, no drift compounding).
+	 *
+	 * @type {ReturnType<typeof setTimeout> | null}
+	 */
+	let tickTimer = null;
+
+	/**
+	 * Drift accounting for observability. Updated on every flush in `tick()`.
+	 * Exposed via the `stats()` accessor; optional `metrics` integration
+	 * (Prometheus histogram) is wired separately.
+	 */
+	let driftSum = 0;
+	let driftCount = 0;
+	let driftMax = 0;
+	let flushCount = 0;
+
 	function relay(topic, event, payload) {
 		if (b) { try { b.guard(); } catch { return; } }
 		const msg = JSON.stringify({ instanceId, topic, event, payload });
@@ -388,24 +457,129 @@ export function createCursor(client, options = {}) {
 	}
 
 	/**
-	 * Flush all coalesced entries for a topic as a single `bulk` event.
-	 * Entries carry `{key, data}` only; `user` lives on the catalog channel.
-	 * Per-entry Redis snapshot writes are coalesced through `queueSnapshot`
-	 * onto the snapshot timer.
+	 * Flush a topic's `dirty` + `inboundDirty` maps as a single wire frame to
+	 * local subscribers, then relay the local-origin slice to peers.
+	 *
+	 * - Local subscribers see one combined frame per cycle covering this
+	 *   worker's own cursors PLUS any cursors received from peers since the
+	 *   last flush. Pre-change, peer-relayed cursors emitted as a separate
+	 *   frame immediately on receive, producing tight doublets at subscribers.
+	 * - Peers receive only the local-origin slice (relay payload is built
+	 *   from `dirty`, not from `inboundDirty`). Re-relaying inbound cursors
+	 *   would loop: filtered at the receiver via `instanceId`, but still
+	 *   wastes Redis pub/sub bandwidth.
+	 * - `queueSnapshot` runs for local-origin only. The originating worker
+	 *   owns the Redis HSET for its cursors; receivers must not re-write
+	 *   what the origin already wrote (would double the HSET storm).
+	 *
+	 * Single-entry vs. multi-entry choice mirrors the existing wire shape:
+	 * one cursor -> `update {key, data}`, many -> `bulk [{key, data}, ...]`.
+	 * Subscribers handle both as cursor-position frames.
 	 */
-	function flushBulk(topic, dirty) {
+	function flushBoth(topic, state) {
 		const entries = [];
 		let flushPlatform = null;
-		for (const [k, v] of dirty) {
+		let localCount = 0;
+
+		// Local-origin slice first so we can take a prefix for the relay.
+		for (const [k, v] of state.dirty) {
 			entries.push({ key: k, data: v.data });
 			flushPlatform = v.platform;
 			queueSnapshot(topic, k, v.user, v.data);
+			localCount++;
 		}
+		for (const [k, v] of state.inboundDirty) {
+			entries.push({ key: k, data: v.data });
+			flushPlatform ||= v.platform;
+		}
+
+		state.dirty.clear();
+		state.inboundDirty.clear();
+
 		if (!flushPlatform || entries.length === 0) return;
-		flushPlatform.publish('__cursor:' + topic, EVENTS.BULK, entries);
-		relay(topic, EVENTS.BULK, entries);
+
+		mBroadcasts?.inc({ topic: mt(topic) });
+		flushCount++;
+
+		// Single local publish covering all entries (local + inbound).
+		if (entries.length === 1) {
+			flushPlatform.publish('__cursor:' + topic, EVENTS.UPDATE, entries[0]);
+		} else {
+			flushPlatform.publish('__cursor:' + topic, EVENTS.BULK, entries);
+		}
+
+		// Relay LOCAL-ORIGIN slice only; never re-relay what came from peers.
+		if (localCount > 0) {
+			if (localCount === 1) {
+				relay(topic, EVENTS.UPDATE, entries[0]);
+			} else {
+				relay(topic, EVENTS.BULK, entries.slice(0, localCount));
+			}
+		}
 	}
 
+	/**
+	 * Scheduler tick. Walks `dirtyTopics`, flushes any topic whose deadline
+	 * (`lastFlush + topicThrottleMs`) has passed, and re-arms `tickTimer`
+	 * for the next earliest pending deadline. Topics whose deadline has not
+	 * yet passed stay in `dirtyTopics` for the next tick.
+	 *
+	 * Target-anchored advance: on flush, `lastFlush` is set to the deadline
+	 * (not the actual fire time) so a single late tick does not compound
+	 * drift on subsequent cycles. If we fell behind by more than one cycle
+	 * (event loop saturation > `topicThrottleMs`), `lastFlush` resets to
+	 * `now` to avoid queueing phantom catch-up fires that would all hit the
+	 * next event loop turn.
+	 */
+	function tick() {
+		tickTimer = null;
+		const now = Date.now();
+		let nextDeadline = Infinity;
+
+		for (const topic of dirtyTopics) {
+			const state = topicFlush.get(topic);
+			if (!state) { dirtyTopics.delete(topic); continue; }
+			if (state.dirty.size === 0 && state.inboundDirty.size === 0) {
+				dirtyTopics.delete(topic);
+				continue;
+			}
+			const deadline = state.lastFlush + topicThrottleMs;
+			if (deadline <= now) {
+				const drift = now - deadline;
+				driftSum += drift;
+				driftCount++;
+				if (drift > driftMax) driftMax = drift;
+
+				flushBoth(topic, state);
+				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.
+				state.lastFlush = drift < topicThrottleMs ? deadline : now;
+			} else if (deadline < nextDeadline) {
+				nextDeadline = deadline;
+			}
+		}
+
+		if (nextDeadline !== Infinity) {
+			tickTimer = setTimeout(tick, Math.max(0, nextDeadline - Date.now()));
+		}
+		// else: scheduler goes idle until next broadcast() / enqueueInbound().
+	}
+
+	function armTick(delay) {
+		if (tickTimer !== null) return;
+		tickTimer = setTimeout(tick, delay);
+	}
+
+	/**
+	 * 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).
+	 */
 	function broadcast(topic, key, user, data, platform) {
 		if (topicThrottleMs <= 0) {
 			doBroadcast(topic, key, user, data, platform);
@@ -414,42 +588,64 @@ export function createCursor(client, options = {}) {
 
 		let state = topicFlush.get(topic);
 		if (!state) {
-			state = { lastFlush: 0, timer: null, dirty: new Map() };
+			state = { dirty: new Map(), inboundDirty: new Map(), lastFlush: 0 };
 			topicFlush.set(topic, state);
 		}
-
 		state.dirty.set(key, { user, data, platform });
 
 		const now = Date.now();
-
 		if (now - state.lastFlush >= topicThrottleMs) {
-			if (state.timer) { clearTimeout(state.timer); state.timer = null; }
+			// Leading-edge synchronous flush.
 			state.lastFlush = now;
-			if (state.dirty.size === 1) {
-				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();
+			flushBoth(topic, state);
+			dirtyTopics.delete(topic);
 			return;
 		}
 
-		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));
+		// Within window: trailing-edge flush via the scheduler tick.
+		dirtyTopics.add(topic);
+		armTick(Math.max(0, topicThrottleMs - (now - state.lastFlush)));
+	}
+
+	/**
+	 * Schedule a peer-relayed cursor for the next coalesced flush. Symmetric
+	 * to `broadcast()`: same leading/trailing edge semantics, but inbound
+	 * entries route through `state.inboundDirty` so they are visible to
+	 * local subscribers on the next flush WITHOUT being re-relayed to peers
+	 * (which would loop) and WITHOUT being written to Redis (origin owns
+	 * the HSET).
+	 *
+	 * The peer's cross-replica end-to-end latency gains up to one
+	 * `topicThrottleMs` of coalescing delay on the receiver side. Cursors
+	 * are already throttled in the 8-16ms range; adding 8-16ms is well
+	 * below the ~50-100ms human perception threshold for cursor lag. The
+	 * smoothness win (one frame per subscriber per cycle instead of two)
+	 * is the structural benefit.
+	 */
+	function enqueueInbound(topic, key, data, platform) {
+		if (topicThrottleMs <= 0) {
+			// Legacy immediate mode (matches old receiver behavior).
+			platform.publish('__cursor:' + topic, EVENTS.UPDATE, { key, data }, { relay: false });
+			return;
 		}
+
+		let state = topicFlush.get(topic);
+		if (!state) {
+			state = { dirty: new Map(), inboundDirty: new Map(), lastFlush: 0 };
+			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)));
 	}
 
 	async function broadcastRemove(topic, key, platform) {
@@ -482,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);
 		},
 
@@ -580,6 +785,7 @@ export function createCursor(client, options = {}) {
 							topics.delete(topic);
 							activeTopics.delete(topic);
 							topicFlush.delete(topic);
+							dirtyTopics.delete(topic);
 							redisPending.delete(topic);
 							stopCleanupTimer();
 						}
@@ -637,6 +843,7 @@ export function createCursor(client, options = {}) {
 						topics.delete(t);
 						activeTopics.delete(t);
 						topicFlush.delete(t);
+						dirtyTopics.delete(t);
 						redisPending.delete(t);
 					}
 				}
@@ -717,9 +924,9 @@ export function createCursor(client, options = {}) {
 					if (entry.timer) clearTimeout(entry.timer);
 				}
 			}
-			for (const [, state] of topicFlush) {
-				if (state.timer) clearTimeout(state.timer);
-			}
+			// Tracker-level scheduler timer + dirty-topic set.
+			if (tickTimer !== null) { clearTimeout(tickTimer); tickTimer = null; }
+			dirtyTopics.clear();
 			topics.clear();
 			topicFlush.clear();
 			wsState.clear();
@@ -739,9 +946,8 @@ export function createCursor(client, options = {}) {
 					if (entry.timer) clearTimeout(entry.timer);
 				}
 			}
-			for (const [, state] of topicFlush) {
-				if (state.timer) clearTimeout(state.timer);
-			}
+			if (tickTimer !== null) { clearTimeout(tickTimer); tickTimer = null; }
+			dirtyTopics.clear();
 			topicFlush.clear();
 			if (subscriber) {
 				subscriber.quit().catch(() => subscriber.disconnect());
@@ -750,6 +956,37 @@ export function createCursor(client, options = {}) {
 			activePlatform = null;
 		},
 
+		/**
+		 * Snapshot of scheduler health. Always available, near-zero cost.
+		 *
+		 * - `flushes`: total tick-driven flushes since tracker creation.
+		 * - `driftMeanMs`: mean (target_deadline - actual_fire_time) across
+		 *   all tick-driven flushes. 0 means perfect cadence; values >
+		 *   `topicThrottle` indicate sustained event-loop saturation or
+		 *   CPU contention.
+		 * - `driftMaxMs`: largest single observed late fire. Useful for
+		 *   spotting one-off GC pauses vs. sustained drift.
+		 * - `dirtyTopicsCurrent`: topics with pending coalesced entries
+		 *   right now. Should hover near zero in healthy operation; growth
+		 *   means tick is falling behind.
+		 * - `activeTopicsTotal`: topics with at least one local cursor.
+		 *
+		 * Leading-edge synchronous flushes (first call on an idle topic)
+		 * are not counted in drift stats - they fire on the call thread,
+		 * not via the scheduler.
+		 *
+		 * @returns {{ flushes: number, driftMeanMs: number, driftMaxMs: number, dirtyTopicsCurrent: number, activeTopicsTotal: number }}
+		 */
+		stats() {
+			return {
+				flushes: flushCount,
+				driftMeanMs: driftCount > 0 ? driftSum / driftCount : 0,
+				driftMaxMs: driftMax,
+				dirtyTopicsCurrent: dirtyTopics.size,
+				activeTopicsTotal: topics.size
+			};
+		},
+
 		hooks: {
 			subscribe(ws, topic, { platform }) {
 				if (topic.startsWith('__cursor:')) {

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;
+	}
+}