svelte-realtime 0.5.2 → 0.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-realtime",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "publishConfig": {
     "tag": "latest"
   },
@@ -89,12 +89,12 @@
   "peerDependencies": {
     "@sveltejs/kit": "^2.0.0",
     "svelte": "^4.0.0 || ^5.0.0",
-    "svelte-adapter-uws": "^0.5.0"
+    "svelte-adapter-uws": "^0.5.1"
   },
   "devDependencies": {
     "@playwright/test": "^1.59.1",
     "fast-check": "^4.7.0",
-    "svelte-adapter-uws-extensions": "^0.5.0",
+    "svelte-adapter-uws-extensions": "^0.5.1",
     "vitest": "^4.0.18"
   },
   "keywords": [

package/server.d.ts

@@ -619,6 +619,23 @@ export const combineMerge: <T extends object>(...buckets: Array<T | undefined>)
  */
 export const MAX_AGGREGATE_BUCKETS: number;
 
+/**
+ * Maximum entries in the per-userId connection registry that backs
+ * `live.push({ userId })` / `live.notify`. Saturation behaviour is
+ * WARN-once and skip new registrations; existing entries continue to
+ * route. Default 10,000,000.
+ */
+export const MAX_PUSH_REGISTRY: number;
+
+/**
+ * Maximum entries in the in-memory presence-ref map that backs
+ * `live.room({ presence })` on the single-instance / dev path. When
+ * `platform.presence.list` is wired (e.g. via the Redis presence
+ * extension), this cap is bypassed. Saturation behaviour is WARN-once
+ * and skip new entries. Default 1,000,000.
+ */
+export const MAX_PRESENCE_REF: number;
+
 export type TopicEntry = string | ((...args: any[]) => string);
 
 /**

package/server.js

@@ -982,8 +982,16 @@ const _publishRateConfig = {
 const _publishRateWarned = new Set();
 /** @type {WeakMap<any, ReturnType<typeof setInterval>>} */
 const _publishRateSamplers = new WeakMap();
-/** @type {Set<any>} Tracks platforms with active samplers so reset can clear them. */
-const _publishRateActivePlatforms = new Set();
+/**
+ * Bumped by `_resetPublishRateWarning` and by `live.publishRateWarning(false)`.
+ * Each sampler captures its activation-time epoch and self-clears on the next
+ * fire when the epoch no longer matches. Pattern used in place of the prior
+ * strong-reference `Set<platform>` because that Set held every dev-mode
+ * platform alive across the process lifetime, defeating the WeakMap above and
+ * leaking the platform + all captured helpers/closures on every per-call
+ * wrap pattern (e.g. cron tick wrapping a fresh `bus.wrap(platform)` per fire).
+ */
+let _publishRateEpoch = 0;
 
 /**
  * Activate the dev-mode publish-rate warning sampler for one platform.
@@ -993,6 +1001,15 @@ const _publishRateActivePlatforms = new Set();
  * underscore prefix so tests can drive activation deterministically
  * without going through the async RPC path.
  *
+ * The sampler closure must NOT strongly capture `platform`. Node's timer
+ * queue holds the `setInterval` Timer alive until clearInterval fires; if
+ * the closure captured `platform` directly, every platform ever passed in
+ * would stay reachable forever, leaking the entire helpers+closures graph.
+ * The `WeakRef` wrapper here breaks that retention: on each tick the
+ * sampler derefs, and a null deref (platform GC'd elsewhere) self-clears
+ * the timer. Net effect: at most one stale tick after platform GC, then
+ * the entry vanishes.
+ *
  * @param {any} platform
  */
 export function _activatePublishRateWarning(platform) {
@@ -1000,8 +1017,22 @@ export function _activatePublishRateWarning(platform) {
 	if (!_publishRateConfig.enabled) return;
 	if (_publishRateSamplers.has(platform)) return;
 	if (typeof platform?.pressure !== 'object' || platform.pressure === null) return;
+	const platformRef = new WeakRef(platform);
+	const epoch = _publishRateEpoch;
 	const sampler = setInterval(() => {
-		const top = platform.pressure?.topPublishers;
+		// Self-clear on disable / reset / platform-GC. Any of the three
+		// makes the sampler stale; clearInterval here lets Node drop the
+		// Timer from the queue on the next event-loop turn.
+		if (!_publishRateConfig.enabled || epoch !== _publishRateEpoch) {
+			clearInterval(sampler);
+			return;
+		}
+		const p = platformRef.deref();
+		if (!p) {
+			clearInterval(sampler);
+			return;
+		}
+		const top = p.pressure?.topPublishers;
 		if (!Array.isArray(top)) return;
 		for (const entry of top) {
 			if (!entry || typeof entry.topic !== 'string') continue;
@@ -1029,24 +1060,24 @@ export function _activatePublishRateWarning(platform) {
 	}, _publishRateConfig.intervalMs);
 	if (typeof sampler.unref === 'function') sampler.unref();
 	_publishRateSamplers.set(platform, sampler);
-	_publishRateActivePlatforms.add(platform);
 }
 
 /**
  * Reset the dev-mode publish-rate warning state. Tests only. Clears the
- * one-shot warned set, stops every active sampler, and removes the
- * activation marker so the next ctx-helpers cache miss for a previously
- * seen platform re-attaches a sampler. Does NOT reset config back to
- * defaults - tests that mutate config should restore it themselves.
+ * one-shot warned set and bumps the per-process epoch so every existing
+ * sampler self-clears on its next fire. Stale samplers stop within one
+ * `intervalMs` of the reset (default 5s); a same-platform re-activation
+ * after reset gets a fresh sampler because the old WeakMap entry's
+ * sampler will self-clear on its next tick and never write state again.
+ *
+ * If a test needs synchronous teardown (e.g. to assert no extra warns
+ * fire after reset within the same tick), call this AND assert that
+ * `_publishRateConfig.enabled` is false; samplers short-circuit on the
+ * disabled flag without doing any work.
  */
 export function _resetPublishRateWarning() {
 	_publishRateWarned.clear();
-	for (const platform of _publishRateActivePlatforms) {
-		const sampler = _publishRateSamplers.get(platform);
-		if (sampler) clearInterval(sampler);
-		_publishRateSamplers.delete(platform);
-	}
-	_publishRateActivePlatforms.clear();
+	_publishRateEpoch++;
 }
 
 /**
@@ -2183,13 +2214,13 @@ export function _resetRateLimits() {
 live.publishRateWarning = function publishRateWarning(config) {
 	if (config === false) {
 		_publishRateConfig.enabled = false;
-		// Stop active samplers so disable takes effect immediately.
-		for (const platform of _publishRateActivePlatforms) {
-			const sampler = _publishRateSamplers.get(platform);
-			if (sampler) clearInterval(sampler);
-			_publishRateSamplers.delete(platform);
-		}
-		_publishRateActivePlatforms.clear();
+		// Existing samplers self-clear on their next fire via the
+		// `_publishRateConfig.enabled` check at the top of the callback.
+		// Bumping the epoch is belt-and-suspenders: a sampler whose
+		// callback is in flight when the flag flips still sees the
+		// epoch mismatch on its NEXT scheduled fire. Worst case is one
+		// stale interval (default 5s) before the timer goes idle.
+		_publishRateEpoch++;
 		return;
 	}
 	if (config === undefined || config === true) {
@@ -4518,6 +4549,131 @@ export function _getIdentityKey(ctx) {
 	return guestId;
 }
 
+/**
+ * Cluster-shared presence-ref store. Used by `live.room({ presence })` when
+ * `platform.redis` is wired by the host app (raw ioredis-shaped client with
+ * hincrby / hset / hdel / hgetall / expire). Falls back to the in-process
+ * `_presenceRef` Map when absent, preserving zero-config dev behavior.
+ *
+ * Storage layout (one Redis HASH per topic):
+ *   key:    `__live-presence:{topic}`
+ *   fields: 'c:{userKey}' -> integer (cluster-wide subscriber count)
+ *           'd:{userKey}' -> JSON-stringified presence data
+ *
+ * Cluster semantics:
+ * - First replica to take a user's count from 0->1 publishes 'join' (cluster-
+ *   wide isFirst). Subsequent replicas just increment.
+ * - Last replica to take a user's count from 1->0 publishes 'leave'.
+ * - Loader returns the full HGETALL view so any replica's new subscriber sees
+ *   all users from all replicas, not just the locally-attached ones.
+ *
+ * Per-replica refcount (multiple tabs of the same user on the same replica)
+ * and grace-timer behavior stay in the existing _presenceRef Map. The cluster
+ * helpers only fire at the local 0<->1 transitions, so a quick reconnect
+ * burst on a single replica doesn't churn the cluster counter.
+ */
+const _PRESENCE_KEY_PREFIX = '__live-presence:';
+const _PRESENCE_TTL_SEC = 3600;
+
+/**
+ * Bump the cluster-wide count for (topic, key). Returns isFirst=true when
+ * this acquire took the count from 0 to 1 cluster-wide, signaling that the
+ * caller should publish a 'join' event. Falls through to a no-op stub when
+ * platform.redis is missing (single-replica dev path).
+ */
+async function _clusterPresenceAcquire(platform, topic, key, data) {
+	const redis = platform && platform.redis;
+	if (!redis || typeof redis.hincrby !== 'function') return { isFirst: true };
+	const hKey = _PRESENCE_KEY_PREFIX + topic;
+	const countField = 'c:' + key;
+	const dataField = 'd:' + key;
+	let serialized;
+	try { serialized = JSON.stringify(data); } catch { serialized = 'null'; }
+	try {
+		// Write the data field BEFORE bumping the count. A concurrent
+		// `_clusterPresenceList` (e.g. the same user's own :presence stream
+		// loader racing the data stream's acquire) reads data fields only;
+		// if HINCRBY ran first the loader could observe a count without a
+		// data field and return an empty roster, missing the user's own
+		// entry. Writing data first guarantees the loader sees the entry
+		// as soon as the count is visible.
+		await redis.hset(hKey, dataField, serialized);
+		const count = await redis.hincrby(hKey, countField, 1);
+		if (count === 1) {
+			await redis.expire(hKey, _PRESENCE_TTL_SEC);
+			return { isFirst: true };
+		}
+		// Refresh TTL on activity so the hash doesn't expire under a busy room.
+		try { await redis.expire(hKey, _PRESENCE_TTL_SEC); } catch { /* best-effort */ }
+		return { isFirst: false };
+	} catch {
+		// Redis blip: treat as first so we publish a join. Worst case a duplicate
+		// 'join' merges idempotently by key on the client.
+		return { isFirst: true };
+	}
+}
+
+/**
+ * Decrement the cluster-wide count for (topic, key). Returns isLast=true when
+ * this release took the count from 1 to 0 cluster-wide, signaling that the
+ * caller should publish a 'leave' event. Falls through to isLast=true when
+ * platform.redis is missing (single-replica dev path treats every grace-timer
+ * expiry as the final leave).
+ */
+async function _clusterPresenceRelease(platform, topic, key) {
+	const redis = platform && platform.redis;
+	if (!redis || typeof redis.hincrby !== 'function') return { isLast: true };
+	const hKey = _PRESENCE_KEY_PREFIX + topic;
+	const countField = 'c:' + key;
+	const dataField = 'd:' + key;
+	try {
+		const count = await redis.hincrby(hKey, countField, -1);
+		if (count <= 0) {
+			await redis.hdel(hKey, countField, dataField);
+			return { isLast: true };
+		}
+		return { isLast: false };
+	} catch {
+		// Redis blip: assume last so we publish a leave. A late observer reading
+		// HGETALL might still see the stale field until the next acquire repairs
+		// the count (or the hash TTL expires).
+		return { isLast: true };
+	}
+}
+
+/**
+ * Return the cluster-wide presence roster for a topic as `[{key, data}, ...]`.
+ * Falls through to the local _presenceRef iteration when platform.redis is
+ * missing.
+ */
+async function _clusterPresenceList(platform, topic) {
+	const redis = platform && platform.redis;
+	if (!redis || typeof redis.hgetall !== 'function') {
+		const prefix = topic + '\0';
+		const out = [];
+		for (const [refKey, ref] of _presenceRef) {
+			if (!refKey.startsWith(prefix)) continue;
+			if (ref.data == null) continue;
+			out.push({ key: refKey.slice(prefix.length), data: ref.data });
+		}
+		return out;
+	}
+	const hKey = _PRESENCE_KEY_PREFIX + topic;
+	try {
+		const all = await redis.hgetall(hKey);
+		const out = [];
+		for (const field of Object.keys(all)) {
+			if (field.length < 3 || field[0] !== 'd' || field[1] !== ':') continue;
+			const key = field.slice(2);
+			try { out.push({ key, data: JSON.parse(all[field]) }); }
+			catch { /* skip corrupt entry */ }
+		}
+		return out;
+	} catch {
+		return [];
+	}
+}
+
 live.room = function room(config) {
 	const {
 		topic: topicFn,
@@ -4562,7 +4718,7 @@ live.room = function room(config) {
 	}, {
 		merge: mergeMode,
 		key: keyField,
-		onSubscribe: presenceFn ? (ctx, topic) => {
+		onSubscribe: presenceFn ? async (ctx, topic) => {
 			const userId = _getIdentityKey(ctx);
 			const refKey = topic + '\0' + userId;
 
@@ -4582,7 +4738,13 @@ live.room = function room(config) {
 					if (r.timer) {
 						clearTimeout(r.timer);
 						const [t, u] = k.split('\0');
-						ctx.publish(t + ':presence', 'leave', { key: u });
+						// Cluster release runs eagerly here too: an evicted entry
+						// would otherwise leak a phantom counter on Redis.
+						_clusterPresenceRelease(ctx.platform, t, u).then((res) => {
+							if (res.isLast) {
+								ctx.publish(t + ':presence', 'leave', { key: u });
+							}
+						}).catch(() => {});
 						if (onLeave) {
 							Promise.resolve().then(() => onLeave(ctx, t)).catch(() => {});
 						}
@@ -4595,7 +4757,7 @@ live.room = function room(config) {
 						console.warn(
 							"[svelte-realtime] presence-ref map reached MAX_PRESENCE_REF=" + _maxPresenceRef +
 							"; new joiners will not appear in any subscriber's roster until existing entries clear.\n" +
-							"  For multi-instance deploys, wire `platform.presence` (e.g. svelte-adapter-uws-extensions/presence) so this in-memory fallback is bypassed.\n" +
+							"  For multi-instance deploys, wire `platform.redis` (raw ioredis client) so the cluster-shared Redis presence is bypasses the in-memory cap.\n" +
 							"  See: https://svti.me/presence"
 						);
 					}
@@ -4609,8 +4771,14 @@ live.room = function room(config) {
 			// to the :presence topic.
 			const presenceData = presenceFn(ctx);
 			_presenceRef.set(refKey, { count: 1, timer: null, data: presenceData });
+			// Cluster transition: bump shared count; only the first replica to
+			// reach 1 publishes 'join'. With no platform.redis the helper
+			// returns isFirst=true unconditionally, matching the in-memory path.
 			if (presenceData) {
-				ctx.publish(topic + ':presence', 'join', { key: userId, data: presenceData });
+				const { isFirst } = await _clusterPresenceAcquire(ctx.platform, topic, userId, presenceData);
+				if (isFirst) {
+					ctx.publish(topic + ':presence', 'join', { key: userId, data: presenceData });
+				}
 			}
 		} : undefined,
 		onUnsubscribe: presenceFn ? (ctx, topic) => {
@@ -4623,11 +4791,17 @@ live.room = function room(config) {
 			ref.count--;
 			if (ref.count > 0) return;
 
-			// On rollback (failed stream init), skip grace and leave immediately
+			// On rollback (failed stream init), skip grace and release
+			// immediately. Cluster release decides whether this was the LAST
+			// subscriber across the cluster - only then do we publish 'leave'.
 			if (ctx.ws && _rollingBack.has(ctx.ws)) {
 				if (ref.timer) clearTimeout(ref.timer);
 				_presenceRef.delete(refKey);
-				ctx.publish(topic + ':presence', 'leave', { key: userId });
+				_clusterPresenceRelease(ctx.platform, topic, userId).then((res) => {
+					if (res.isLast) {
+						ctx.publish(topic + ':presence', 'leave', { key: userId });
+					}
+				}).catch(() => {});
 				if (onLeave) {
 					Promise.resolve().then(() => onLeave(ctx, topic)).catch(() => {});
 				}
@@ -4636,7 +4810,11 @@ live.room = function room(config) {
 
 			ref.timer = setTimeout(() => {
 				_presenceRef.delete(refKey);
-				ctx.publish(topic + ':presence', 'leave', { key: userId });
+				_clusterPresenceRelease(ctx.platform, topic, userId).then((res) => {
+					if (res.isLast) {
+						ctx.publish(topic + ':presence', 'leave', { key: userId });
+					}
+				}).catch(() => {});
 				if (onLeave) {
 					Promise.resolve().then(() => onLeave(ctx, topic)).catch(() => {});
 				}
@@ -4658,24 +4836,12 @@ live.room = function room(config) {
 			async (ctx, ...args) => {
 				if (guardFn) await guardFn(ctx, ...args);
 				const dataTopic = topicFn(ctx, ...args);
-				if (ctx.platform.presence && typeof ctx.platform.presence.list === 'function') {
-					return ctx.platform.presence.list(dataTopic + ':presence');
-				}
-				// In-memory fallback (zero-config dev path). Without this,
-				// the data stream's onSubscribe publishes the join BEFORE the
-				// user subscribes to :presence, so a user alone in a room
-				// would never see its own join. Reconstructs the roster from
-				// `_presenceRef`. Production wires `platform.presence.list`
-				// (Redis-backed) for cluster-wide consistency and bypasses
-				// this branch.
-				const prefix = dataTopic + '\0';
-				const result = [];
-				for (const [refKey, ref] of _presenceRef) {
-					if (!refKey.startsWith(prefix)) continue;
-					if (ref.data == null) continue;
-					result.push({ key: refKey.slice(prefix.length), data: ref.data });
-				}
-				return result;
+				// Cluster-shared roster when `platform.redis` is wired; falls
+				// back to the local _presenceRef iteration otherwise. The
+				// loader reconstructs the roster even when this user's join
+				// was published before they subscribed to :presence (the live
+				// merge takes over from here).
+				return _clusterPresenceList(ctx.platform, dataTopic);
 			},
 			{ merge: 'presence' }
 		);
@@ -7561,10 +7727,10 @@ function _respond(ws, platform, correlationId, payload) {
 	if (_IS_DEV) {
 		// Estimate size without double-serialization.
 		const data = payload.data;
-		if ((Array.isArray(data) && data.length > 100) || (typeof data === 'string' && data.length > 12000)) {
+		if ((Array.isArray(data) && data.length > 5000) || (typeof data === 'string' && data.length > 800_000)) {
 			console.warn(
 				`[svelte-realtime] RPC response for '${correlationId}' contains ${data.length} items - ` +
-				'large responses may exceed maxPayloadLength (16KB). Increase maxPayloadLength in adapter config if needed.\n  See: https://svti.me/adapter-config'
+				"large responses may exceed maxPayloadLength (default 1 MB; raise `websocket.maxPayloadLength` in svelte.config.js if needed).\n  See: https://svti.me/adapter-config"
 			);
 		}
 	}