svelte-adapter-uws-extensions 0.1.2

package/postgres/replay.js

@@ -0,0 +1,279 @@
+/**
+ * Postgres-backed replay buffer for svelte-adapter-uws.
+ *
+ * Same API as the core createReplay plugin, but stores messages in a
+ * Postgres table for durable history that survives restarts.
+ *
+ * Table schema (auto-created if autoMigrate is true):
+ *   ws_replay (
+ *     ws_replay_id BIGSERIAL PRIMARY KEY,
+ *     topic        TEXT        NOT NULL,
+ *     seq          BIGINT      NOT NULL,
+ *     event        TEXT        NOT NULL,
+ *     data         JSONB,
+ *     created_date TIMESTAMPTZ DEFAULT now()
+ *   )
+ *   + index on (topic, seq)
+ *
+ *   ws_replay_seq (
+ *     topic TEXT   PRIMARY KEY,
+ *     seq   BIGINT NOT NULL DEFAULT 0
+ *   )
+ *
+ * Sequences are generated atomically via the _seq table using
+ * INSERT ... ON CONFLICT DO UPDATE, so they are safe across multiple
+ * server instances without races.
+ *
+ * @module svelte-adapter-uws-extensions/postgres/replay
+ */
+
+/**
+ * @typedef {Object} PgReplayOptions
+ * @property {string} [table='ws_replay'] - Table name
+ * @property {number} [size=1000] - Max messages per topic
+ * @property {number} [ttl=0] - TTL in seconds (0 = no expiry). Rows older than this are cleaned up periodically.
+ * @property {boolean} [autoMigrate=true] - Auto-create table on first use
+ * @property {number} [cleanupInterval=60000] - How often to run cleanup (ms). 0 to disable.
+ */
+
+/**
+ * @typedef {Object} PgReplayBuffer
+ * @property {(platform: import('svelte-adapter-uws').Platform, topic: string, event: string, data?: unknown) => Promise<boolean>} publish
+ * @property {(topic: string) => Promise<number>} seq
+ * @property {(topic: string, since: number) => Promise<Array<{seq: number, topic: string, event: string, data: unknown}>>} since
+ * @property {(ws: any, topic: string, sinceSeq: number, platform: import('svelte-adapter-uws').Platform) => Promise<void>} replay
+ * @property {() => Promise<void>} clear
+ * @property {(topic: string) => Promise<void>} clearTopic
+ * @property {() => void} destroy - Stop cleanup timer
+ */
+
+/**
+ * Create a Postgres-backed replay buffer.
+ *
+ * @param {import('./index.js').PgClient} client
+ * @param {PgReplayOptions} [options]
+ * @returns {PgReplayBuffer}
+ */
+export function createReplay(client, options = {}) {
+	if (options.size !== undefined) {
+		if (typeof options.size !== 'number' || options.size < 1 || !Number.isInteger(options.size)) {
+			throw new Error(`postgres replay: size must be a positive integer, got ${options.size}`);
+		}
+	}
+	if (options.ttl !== undefined) {
+		if (typeof options.ttl !== 'number' || options.ttl < 0 || !Number.isInteger(options.ttl)) {
+			throw new Error(`postgres replay: ttl must be a non-negative integer, got ${options.ttl}`);
+		}
+	}
+
+	const table = options.table || 'ws_replay';
+	const seqTable = table + '_seq';
+	const pkCol = table + '_id';
+	const maxSize = options.size || 1000;
+	const ttl = options.ttl || 0;
+	const autoMigrate = options.autoMigrate !== false;
+	const cleanupInterval = options.cleanupInterval !== undefined ? options.cleanupInterval : 60000;
+
+	// Validate table name to prevent SQL injection (alphanumeric + underscore only)
+	if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(table)) {
+		throw new Error(`postgres replay: invalid table name "${table}"`);
+	}
+
+	let migrated = false;
+
+	async function ensureTable() {
+		if (migrated || !autoMigrate) return;
+		await client.query(`
+			CREATE TABLE IF NOT EXISTS ${table} (
+				${pkCol} BIGSERIAL   PRIMARY KEY,
+				topic    TEXT        NOT NULL,
+				seq      BIGINT      NOT NULL,
+				event    TEXT        NOT NULL,
+				data     JSONB,
+				created_date TIMESTAMPTZ DEFAULT now()
+			)
+		`);
+		await client.query(`
+			CREATE INDEX IF NOT EXISTS idx_${table}_topic_seq ON ${table} (topic, seq)
+		`);
+		// Atomic per-topic sequence counter table
+		await client.query(`
+			CREATE TABLE IF NOT EXISTS ${seqTable} (
+				topic TEXT   PRIMARY KEY,
+				seq   BIGINT NOT NULL DEFAULT 0
+			)
+		`);
+		migrated = true;
+	}
+
+	/**
+	 * Atomically get the next sequence number for a topic.
+	 * Uses INSERT ... ON CONFLICT DO UPDATE for cross-instance safety.
+	 */
+	async function nextSeq(topic) {
+		const res = await client.query(
+			`INSERT INTO ${seqTable} (topic, seq)
+			      VALUES ($1, 1)
+			 ON CONFLICT (topic)
+			   DO UPDATE
+			         SET seq = ${seqTable}.seq + 1
+			   RETURNING seq`,
+			[topic]
+		);
+		return parseInt(res.rows[0].seq, 10);
+	}
+
+	// Local publish counter per topic -- avoids COUNT(*) on every publish
+	/** @type {Map<string, number>} */
+	const publishCounts = new Map();
+
+	// Periodic cleanup
+	let cleanupTimer = null;
+	if (cleanupInterval > 0) {
+		cleanupTimer = setInterval(async () => {
+			try {
+				await ensureTable();
+
+				// Trim by size: for each topic, keep only the newest `maxSize` rows
+				await client.query(`
+					DELETE FROM ${table}
+					 WHERE ${pkCol} IN (
+					       SELECT ${pkCol}
+					         FROM (SELECT ${pkCol},
+					                      ROW_NUMBER() OVER (PARTITION BY topic ORDER BY seq DESC) AS row_num
+					                 FROM ${table}) ranked
+					        WHERE row_num > $1)
+				`, [maxSize]);
+
+				// Trim by TTL
+				if (ttl > 0) {
+					await client.query(
+						`DELETE FROM ${table}
+						  WHERE created_date < now() - interval '1 second' * $1`,
+						[ttl]
+					);
+				}
+
+				// Reset local counters after cleanup
+				publishCounts.clear();
+			} catch {
+				// Cleanup failures are non-fatal
+			}
+		}, cleanupInterval);
+		if (cleanupTimer.unref) cleanupTimer.unref();
+	}
+
+	return {
+		async publish(platform, topic, event, data) {
+			await ensureTable();
+			const seq = await nextSeq(topic);
+
+			await client.query(
+				`INSERT INTO ${table} (topic, seq, event, data)
+				      VALUES ($1, $2, $3, $4)`,
+				[topic, seq, event, JSON.stringify(data)]
+			);
+
+			// Inline trim: use local counter to avoid COUNT(*) on every publish.
+			// On first publish per topic in this process, seed from the database
+			// so a fresh/restarted instance trims correctly.
+			let count;
+			if (publishCounts.has(topic)) {
+				count = publishCounts.get(topic) + 1;
+			} else {
+				const res = await client.query(
+					`SELECT COUNT(*)::int AS message_count
+					   FROM ${table}
+					  WHERE topic = $1`,
+					[topic]
+				);
+				count = parseInt(res.rows[0].message_count, 10);
+			}
+			publishCounts.set(topic, count);
+			if (count > maxSize) {
+				await client.query(`
+					DELETE FROM ${table}
+					 WHERE topic = $1
+					   AND ${pkCol} NOT IN (
+					       SELECT ${pkCol}
+					         FROM ${table}
+					        WHERE topic = $1
+					        ORDER BY seq DESC
+					        LIMIT $2)
+				`, [topic, maxSize]);
+				publishCounts.set(topic, maxSize);
+			}
+
+			return platform.publish(topic, event, data);
+		},
+
+		async seq(topic) {
+			await ensureTable();
+			const res = await client.query(
+				`SELECT COALESCE(MAX(seq), 0)::int AS max_seq
+				   FROM ${table}
+				  WHERE topic = $1`,
+				[topic]
+			);
+			return parseInt(res.rows[0].max_seq, 10);
+		},
+
+		async since(topic, since) {
+			await ensureTable();
+			const res = await client.query(
+				`SELECT seq, topic, event, data
+				   FROM ${table}
+				  WHERE topic = $1
+				    AND seq > $2
+				  ORDER BY seq ASC`,
+				[topic, since]
+			);
+			return res.rows.map((row) => ({
+				seq: parseInt(row.seq, 10),
+				topic: row.topic,
+				event: row.event,
+				data: row.data
+			}));
+		},
+
+		async replay(ws, topic, sinceSeq, platform) {
+			const missed = await this.since(topic, sinceSeq);
+			const replayTopic = '__replay:' + topic;
+
+			for (let i = 0; i < missed.length; i++) {
+				const msg = missed[i];
+				platform.send(ws, replayTopic, 'msg', {
+					seq: msg.seq,
+					event: msg.event,
+					data: msg.data
+				});
+			}
+			platform.send(ws, replayTopic, 'end', null);
+		},
+
+		async clear() {
+			await ensureTable();
+			await client.query(`DELETE FROM ${table}`);
+			await client.query(`DELETE FROM ${seqTable}`);
+			publishCounts.clear();
+		},
+
+		async clearTopic(topic) {
+			await ensureTable();
+			await client.query(
+				`DELETE FROM ${table}
+				  WHERE topic = $1`, [topic]);
+			await client.query(
+				`DELETE FROM ${seqTable}
+				  WHERE topic = $1`, [topic]);
+			publishCounts.delete(topic);
+		},
+
+		destroy() {
+			if (cleanupTimer) {
+				clearInterval(cleanupTimer);
+				cleanupTimer = null;
+			}
+		}
+	};
+}

package/redis/cursor.d.ts

@@ -0,0 +1,65 @@
+import type { Platform } from 'svelte-adapter-uws';
+import type { RedisClient } from './index.js';
+
+export interface RedisCursorOptions {
+	/**
+	 * Minimum ms between broadcasts per user per topic.
+	 * Trailing-edge timer ensures the final position is always sent.
+	 * @default 50
+	 */
+	throttle?: number;
+
+	/**
+	 * Extract user-identifying data from userData.
+	 * Broadcast alongside cursor data so other clients know who the cursor belongs to.
+	 * @default identity
+	 */
+	select?: (userData: any) => any;
+
+	/**
+	 * TTL in seconds for Redis hash entries.
+	 * Entries are refreshed on every broadcast. Stale cursors from crashed
+	 * instances are cleaned up automatically after this period.
+	 * @default 30
+	 */
+	ttl?: number;
+}
+
+export interface CursorEntry {
+	/** Unique connection key. */
+	key: string;
+	/** Selected user data. */
+	user: any;
+	/** Latest cursor/position data. */
+	data: any;
+}
+
+export interface RedisCursorTracker {
+	/**
+	 * Broadcast a cursor position update. Throttled per user per topic.
+	 * Call this from your `message` hook when you receive cursor data.
+	 */
+	update(ws: any, topic: string, data: any, platform: Platform): void;
+
+	/**
+	 * Remove a connection's cursor state from a specific topic, or all topics if omitted.
+	 * Call this from your `close` hook.
+	 */
+	remove(ws: any, platform: Platform, topic?: string): Promise<void>;
+
+	/**
+	 * Get current cursor positions for a topic across all instances.
+	 */
+	list(topic: string): Promise<CursorEntry[]>;
+
+	/** Clear all cursor state (local and Redis). */
+	clear(): Promise<void>;
+
+	/** Stop the Redis subscriber and clear local timers. */
+	destroy(): void;
+}
+
+/**
+ * Create a Redis-backed cursor tracker.
+ */
+export function createCursor(client: RedisClient, options?: RedisCursorOptions): RedisCursorTracker;

package/redis/cursor.js

@@ -0,0 +1,365 @@
+/**
+ * Redis-backed cursor / ephemeral state plugin for svelte-adapter-uws.
+ *
+ * Same API as the core createCursor plugin, but cursor positions are shared
+ * across instances via Redis. Each instance throttles locally (same
+ * leading/trailing edge logic as the core), then relays broadcasts through
+ * Redis pub/sub so subscribers on other instances see cursor updates.
+ *
+ * Storage layout:
+ *   - Hash `{prefix}cursor:{topic}` - field = connectionKey, value = JSON { user, data }
+ *   - Channel `{prefix}cursor:events` - pub/sub for update/remove relay
+ *
+ * Hash entries expire via TTL so stale cursors from crashed instances
+ * get cleaned up automatically.
+ *
+ * @module svelte-adapter-uws-extensions/redis/cursor
+ */
+
+import { randomBytes } from 'node:crypto';
+
+/**
+ * @typedef {Object} RedisCursorOptions
+ * @property {number} [throttle=50] - Minimum ms between broadcasts per user per topic.
+ *   Trailing-edge timer fires to ensure the final position is always sent.
+ * @property {(userData: any) => any} [select] - Extract user-identifying data from userData.
+ *   Defaults to the full userData.
+ * @property {number} [ttl=30] - TTL in seconds for hash entries. Should be longer than
+ *   the expected gap between updates. Entries are refreshed on every broadcast.
+ */
+
+/**
+ * @typedef {Object} CursorEntry
+ * @property {string} key - Unique connection key.
+ * @property {any} user - Selected user data.
+ * @property {any} data - Latest cursor/position data.
+ */
+
+/**
+ * @typedef {Object} RedisCursorTracker
+ * @property {(ws: any, topic: string, data: any, platform: import('svelte-adapter-uws').Platform) => void} update
+ * @property {(ws: any, platform: import('svelte-adapter-uws').Platform, topic?: string) => Promise<void>} remove
+ * @property {(topic: string) => Promise<CursorEntry[]>} list
+ * @property {() => Promise<void>} clear
+ * @property {() => void} destroy - Stop the Redis subscriber
+ */
+
+/**
+ * Create a Redis-backed cursor tracker.
+ *
+ * @param {import('./index.js').RedisClient} client
+ * @param {RedisCursorOptions} [options]
+ * @returns {RedisCursorTracker}
+ */
+export function createCursor(client, options = {}) {
+	const throttleMs = options.throttle ?? 50;
+	const select = options.select || ((userData) => userData);
+	const cursorTtl = options.ttl || 30;
+
+	if (typeof throttleMs !== 'number' || !Number.isFinite(throttleMs) || throttleMs < 0) {
+		throw new Error('redis cursor: throttle must be a non-negative number');
+	}
+	if (typeof select !== 'function') {
+		throw new Error('redis cursor: select must be a function');
+	}
+
+	const instanceId = randomBytes(8).toString('hex');
+	const redis = client.redis;
+	const channel = client.key('cursor:events');
+
+	let connCounter = 0;
+
+	/**
+	 * Per-ws state: their key and which topics they have cursor state on.
+	 * @type {Map<any, { key: string, user: any, topics: Set<string> }>}
+	 */
+	const wsState = new Map();
+
+	/**
+	 * Per-topic cursor positions (local throttle state).
+	 * @type {Map<string, Map<string, { user: any, data: any, lastBroadcast: number, timer: any }>>}
+	 */
+	const topics = new Map();
+
+	// Redis subscriber for cross-instance relay
+	/** @type {import('ioredis').Redis | null} */
+	let subscriber = null;
+	/** @type {import('svelte-adapter-uws').Platform | null} */
+	let activePlatform = null;
+	let subscriberReady = false;
+
+	function ensureSubscriber(platform) {
+		activePlatform = platform;
+		if (subscriber) return;
+		const sub = client.duplicate({ enableReadyCheck: false });
+		subscriber = sub;
+		sub.on('message', (ch, message) => {
+			if (ch !== channel) return;
+			try {
+				const parsed = JSON.parse(message);
+				if (parsed.instanceId === instanceId) return;
+				// relay: false -- each worker has its own subscriber,
+				// so no need to IPC-relay to sibling workers.
+				if (activePlatform) {
+					activePlatform.publish(
+						'__cursor:' + parsed.topic,
+						parsed.event,
+						parsed.payload,
+						{ relay: false }
+					);
+				}
+			} catch {
+				// Malformed, skip
+			}
+		});
+		sub.subscribe(channel).then(() => {
+			subscriberReady = true;
+		}).catch(() => {
+			// Subscribe failed -- clean up so the next call can retry
+			sub.quit().catch(() => sub.disconnect());
+			if (subscriber === sub) {
+				subscriber = null;
+				subscriberReady = false;
+			}
+		});
+	}
+
+	const cursorTtlMs = cursorTtl * 1000;
+
+	// Track topics with local activity for periodic stale field cleanup
+	/** @type {Set<string>} */
+	const activeTopics = new Set();
+
+	// Periodic cleanup: remove stale fields from dead instances
+	const cleanupInterval = Math.max(cursorTtlMs, 10000);
+	const cleanupTimer = setInterval(() => {
+		const now = Date.now();
+		for (const topic of activeTopics) {
+			redis.hgetall(client.key('cursor:' + topic)).then((all) => {
+				if (!all) return;
+				for (const [field, v] of Object.entries(all)) {
+					try {
+						const parsed = JSON.parse(v);
+						if (parsed.ts && (now - parsed.ts) > cursorTtlMs) {
+							redis.hdel(client.key('cursor:' + topic), field).catch(() => {});
+						}
+					} catch {
+						redis.hdel(client.key('cursor:' + topic), field).catch(() => {});
+					}
+				}
+			}).catch(() => {});
+		}
+	}, cleanupInterval);
+	if (cleanupTimer.unref) cleanupTimer.unref();
+
+	function hashKey(topic) {
+		return client.key('cursor:' + topic);
+	}
+
+	function getWsState(ws) {
+		let state = wsState.get(ws);
+		if (!state) {
+			state = {
+				key: instanceId + ':' + (++connCounter),
+				user: select(typeof ws.getUserData === 'function' ? ws.getUserData() : {}),
+				topics: new Set()
+			};
+			wsState.set(ws, state);
+		}
+		return state;
+	}
+
+	/**
+	 * Broadcast locally + relay to other instances via Redis.
+	 */
+	function broadcast(topic, key, user, data, platform) {
+		// Local broadcast
+		platform.publish('__cursor:' + topic, 'update', { key, user, data });
+
+		// Persist to Redis hash with timestamp for per-entry staleness detection
+		const now = Date.now();
+		redis.hset(hashKey(topic), key, JSON.stringify({ user, data, ts: now })).catch(() => {});
+		redis.expire(hashKey(topic), cursorTtl).catch(() => {});
+
+		// Relay to other instances
+		const msg = JSON.stringify({
+			instanceId,
+			topic,
+			event: 'update',
+			payload: { key, user, data }
+		});
+		redis.publish(channel, msg).catch(() => {});
+	}
+
+	function broadcastRemove(topic, key, platform) {
+		platform.publish('__cursor:' + topic, 'remove', { key });
+
+		redis.hdel(hashKey(topic), key).catch(() => {});
+
+		const msg = JSON.stringify({
+			instanceId,
+			topic,
+			event: 'remove',
+			payload: { key }
+		});
+		redis.publish(channel, msg).catch(() => {});
+	}
+
+	return {
+		update(ws, topic, data, platform) {
+			ensureSubscriber(platform);
+
+			const state = getWsState(ws);
+			state.topics.add(topic);
+			activeTopics.add(topic);
+
+			let topicMap = topics.get(topic);
+			if (!topicMap) {
+				topicMap = new Map();
+				topics.set(topic, topicMap);
+			}
+
+			let entry = topicMap.get(state.key);
+			const now = Date.now();
+
+			if (!entry) {
+				entry = { user: state.user, data, lastBroadcast: 0, timer: null };
+				topicMap.set(state.key, entry);
+			}
+
+			// Always store latest data
+			entry.data = data;
+			entry.user = state.user;
+
+			// Leading edge: broadcast immediately if throttle window passed
+			if (now - entry.lastBroadcast >= throttleMs) {
+				if (entry.timer) {
+					clearTimeout(entry.timer);
+					entry.timer = null;
+				}
+				entry.lastBroadcast = now;
+				broadcast(topic, state.key, state.user, data, platform);
+				return;
+			}
+
+			// Trailing edge: schedule a broadcast for the end of the window
+			if (!entry.timer) {
+				const key = state.key;
+				const user = state.user;
+				entry.timer = setTimeout(() => {
+					const e = topicMap.get(key);
+					if (e) {
+						e.lastBroadcast = Date.now();
+						e.timer = null;
+						broadcast(topic, key, user, e.data, platform);
+					}
+				}, throttleMs - (now - entry.lastBroadcast));
+			}
+		},
+
+		async remove(ws, platform, topic) {
+			const state = wsState.get(ws);
+			if (!state) return;
+
+			if (topic !== undefined) {
+				// --- Per-topic remove ---
+				if (!state.topics.has(topic)) return;
+				state.topics.delete(topic);
+
+				const topicMap = topics.get(topic);
+				if (topicMap) {
+					const entry = topicMap.get(state.key);
+					if (entry) {
+						if (entry.timer) clearTimeout(entry.timer);
+						topicMap.delete(state.key);
+						if (topicMap.size === 0) {
+							topics.delete(topic);
+							activeTopics.delete(topic);
+						}
+						broadcastRemove(topic, state.key, platform);
+					}
+				}
+
+				if (state.topics.size === 0) wsState.delete(ws);
+				return;
+			}
+
+			// --- Remove from all topics ---
+			for (const topic of state.topics) {
+				const topicMap = topics.get(topic);
+				if (!topicMap) continue;
+
+				const entry = topicMap.get(state.key);
+				if (entry) {
+					if (entry.timer) clearTimeout(entry.timer);
+					topicMap.delete(state.key);
+					if (topicMap.size === 0) {
+						topics.delete(topic);
+						activeTopics.delete(topic);
+					}
+					broadcastRemove(topic, state.key, platform);
+				}
+			}
+
+			wsState.delete(ws);
+		},
+
+		async list(topic) {
+			const all = await redis.hgetall(hashKey(topic));
+			const result = [];
+			const now = Date.now();
+			const ttlMs = cursorTtl * 1000;
+			for (const [key, v] of Object.entries(all)) {
+				try {
+					const parsed = JSON.parse(v);
+					// Filter out stale entries from crashed instances
+					if (parsed.ts && (now - parsed.ts) > ttlMs) continue;
+					result.push({ key, user: parsed.user, data: parsed.data });
+				} catch {
+					// Corrupted entry, skip
+				}
+			}
+			return result;
+		},
+
+		async clear() {
+			// Clear all timers
+			for (const [, topicMap] of topics) {
+				for (const [, entry] of topicMap) {
+					if (entry.timer) clearTimeout(entry.timer);
+				}
+			}
+			topics.clear();
+			wsState.clear();
+			activeTopics.clear();
+			connCounter = 0;
+
+			// Clear Redis keys
+			const pattern = client.key('cursor:*');
+			let cursor = '0';
+			do {
+				const [nextCursor, keys] = await redis.scan(cursor, 'MATCH', pattern, 'COUNT', 100);
+				cursor = nextCursor;
+				if (keys.length > 0) {
+					await redis.del(...keys);
+				}
+			} while (cursor !== '0');
+		},
+
+		destroy() {
+			// Clear all timers
+			clearInterval(cleanupTimer);
+			for (const [, topicMap] of topics) {
+				for (const [, entry] of topicMap) {
+					if (entry.timer) clearTimeout(entry.timer);
+				}
+			}
+			if (subscriber) {
+				subscriber.quit().catch(() => subscriber.disconnect());
+				subscriber = null;
+			}
+			subscriberReady = false;
+			activePlatform = null;
+		}
+	};
+}