svelte-adapter-uws-extensions 0.1.2

package/redis/pubsub.js

@@ -0,0 +1,153 @@
+/**
+ * Redis pub/sub bus for svelte-adapter-uws.
+ *
+ * Distributes WebSocket publishes across multiple server instances via Redis.
+ * Each instance publishes to Redis AND locally. Incoming Redis messages are
+ * forwarded to the local platform.publish() with a flag to prevent re-publishing
+ * back to Redis (relay loop prevention).
+ *
+ * @module svelte-adapter-uws-extensions/redis/pubsub
+ */
+
+import { randomBytes } from 'node:crypto';
+
+/**
+ * @typedef {Object} PubSubBusOptions
+ * @property {string} [channel='uws:pubsub'] - Redis channel name for pub/sub messages
+ */
+
+/**
+ * @typedef {Object} PubSubBus
+ * @property {(platform: import('svelte-adapter-uws').Platform) => import('svelte-adapter-uws').Platform} wrap -
+ *   Returns a new Platform whose publish() sends to Redis + local.
+ *   Use this wrapped platform everywhere you call publish().
+ * @property {(platform: import('svelte-adapter-uws').Platform) => Promise<void>} activate -
+ *   Start the Redis subscriber. Incoming messages are forwarded to the
+ *   original platform.publish(). Call this once at startup (e.g. in your open hook).
+ * @property {() => Promise<void>} deactivate -
+ *   Stop the Redis subscriber and clean up.
+ */
+
+/**
+ * Create a Redis-backed pub/sub bus.
+ *
+ * @param {import('./index.js').RedisClient} client - Redis client from createRedisClient
+ * @param {PubSubBusOptions} [options]
+ * @returns {PubSubBus}
+ *
+ * @example
+ * ```js
+ * import { createRedisClient } from 'svelte-adapter-uws-extensions/redis';
+ * import { createPubSubBus } from 'svelte-adapter-uws-extensions/redis/pubsub';
+ *
+ * const redis = createRedisClient({ url: 'redis://localhost:6379' });
+ * const bus = createPubSubBus(redis);
+ *
+ * // In your open hook:
+ * export function open(ws, { platform }) {
+ *   bus.activate(platform); // idempotent, only subscribes once
+ * }
+ *
+ * // Use the wrapped platform for publishing:
+ * const distributed = bus.wrap(platform);
+ * distributed.publish('chat', 'message', { text: 'hello' });
+ * ```
+ */
+export function createPubSubBus(client, options = {}) {
+	const channel = options.channel || 'uws:pubsub';
+	const instanceId = randomBytes(8).toString('hex');
+
+	/** @type {import('ioredis').Redis | null} */
+	let subscriber = null;
+
+	/** @type {boolean} */
+	let active = false;
+
+	/** @type {import('svelte-adapter-uws').Platform | null} */
+	let activePlatform = null;
+
+	return {
+		wrap(platform) {
+			const wrapped = {
+				publish(topic, event, data, options) {
+					// Publish locally, forwarding options as-is
+					const result = platform.publish(topic, event, data, options);
+
+					// Only relay to Redis if the caller did not suppress relay.
+					// When relay is explicitly false the message is local-only
+					// (e.g. it already came from Redis on another instance).
+					if (!options || options.relay !== false) {
+						const msg = JSON.stringify({ instanceId, topic, event, data });
+						client.redis.publish(channel, msg).catch(() => {
+							// Fire-and-forget: ioredis auto-reconnects.
+							// Swallowing here prevents unhandled rejections on transient disconnects.
+						});
+					}
+
+					return result;
+				},
+				send: platform.send.bind(platform),
+				sendTo: platform.sendTo.bind(platform),
+				get connections() { return platform.connections; },
+				subscribers: platform.subscribers.bind(platform),
+				topic(t) {
+					return {
+						publish(event, data) { wrapped.publish(t, event, data); },
+						created(data) { wrapped.publish(t, 'created', data); },
+						updated(data) { wrapped.publish(t, 'updated', data); },
+						deleted(data) { wrapped.publish(t, 'deleted', data); },
+						set(value) { wrapped.publish(t, 'set', value); },
+						increment(amount) { wrapped.publish(t, 'increment', amount); },
+						decrement(amount) { wrapped.publish(t, 'decrement', amount); }
+					};
+				}
+			};
+			return wrapped;
+		},
+
+		async activate(platform) {
+			// Always update the platform reference so remote messages
+			// are forwarded through the latest platform, even if a
+			// previous activate() already started the subscriber.
+			activePlatform = platform;
+			if (active) return;
+
+			subscriber = client.duplicate({ enableReadyCheck: false });
+
+			subscriber.on('message', (ch, message) => {
+				if (ch !== channel) return;
+				try {
+					const parsed = JSON.parse(message);
+					// Skip messages from this instance (echo suppression)
+					if (parsed.instanceId === instanceId) return;
+					// Forward to local platform only -- relay: false prevents the
+					// adapter from IPC-relaying to sibling workers, since each
+					// worker has its own Redis subscriber already receiving this.
+					activePlatform.publish(parsed.topic, parsed.event, parsed.data, { relay: false });
+				} catch {
+					// Malformed message, skip
+				}
+			});
+
+			try {
+				await subscriber.subscribe(channel);
+				active = true;
+			} catch (err) {
+				// Clean up so the next activate() call can retry
+				activePlatform = null;
+				subscriber.quit().catch(() => subscriber.disconnect());
+				subscriber = null;
+				throw err;
+			}
+		},
+
+		async deactivate() {
+			if (!active || !subscriber) return;
+			active = false;
+			activePlatform = null;
+			await subscriber.unsubscribe(channel).catch(() => {});
+			await subscriber.quit().catch(() => subscriber.disconnect());
+			subscriber = null;
+		}
+	};
+}

package/redis/ratelimit.d.ts

@@ -0,0 +1,39 @@
+import type { RedisClient } from './index.js';
+
+export interface RedisRateLimitOptions {
+	/** Tokens available per interval. Must be a positive integer. */
+	points: number;
+	/** Refill interval in milliseconds. Must be positive. */
+	interval: number;
+	/** Auto-ban duration in ms when exhausted. 0 = no ban. @default 0 */
+	blockDuration?: number;
+	/** Key extraction mode. @default 'ip' */
+	keyBy?: 'ip' | 'connection' | ((ws: any) => string);
+}
+
+export interface ConsumeResult {
+	/** Whether the request was permitted. */
+	allowed: boolean;
+	/** Tokens left in the bucket (0 if banned or exhausted). */
+	remaining: number;
+	/** Milliseconds until the bucket refills or the ban expires. */
+	resetMs: number;
+}
+
+export interface RedisRateLimiter {
+	/** Attempt to consume tokens. */
+	consume(ws: any, cost?: number): Promise<ConsumeResult>;
+	/** Clear the bucket for a key. */
+	reset(key: string): Promise<void>;
+	/** Manually ban a key. */
+	ban(key: string, duration?: number): Promise<void>;
+	/** Remove a ban. */
+	unban(key: string): Promise<void>;
+	/** Reset all state. */
+	clear(): Promise<void>;
+}
+
+/**
+ * Create a Redis-backed rate limiter using atomic Lua scripts.
+ */
+export function createRateLimit(client: RedisClient, options: RedisRateLimitOptions): RedisRateLimiter;

package/redis/ratelimit.js

@@ -0,0 +1,223 @@
+/**
+ * Redis-backed rate limiter for svelte-adapter-uws.
+ *
+ * Same API as the core createRateLimit plugin, but stores bucket state
+ * in Redis so rate limits are enforced across all server instances.
+ *
+ * Uses a Lua script for atomic token consumption to avoid race conditions.
+ * The Lua script runs entirely on the Redis server, so there is exactly
+ * one roundtrip per consume() call.
+ *
+ * @module svelte-adapter-uws-extensions/redis/ratelimit
+ */
+
+/**
+ * Lua script for atomic token bucket consumption.
+ *
+ * KEYS[1] = bucket key (hash with fields: points, resetAt, bannedUntil)
+ * ARGV[1] = max points
+ * ARGV[2] = interval (ms)
+ * ARGV[3] = cost
+ * ARGV[4] = now (ms)
+ * ARGV[5] = blockDuration (ms)
+ *
+ * Returns: [allowed (0/1), remaining, resetMs]
+ */
+const CONSUME_SCRIPT = `
+local key = KEYS[1]
+local maxPoints = tonumber(ARGV[1])
+local interval = tonumber(ARGV[2])
+local cost = tonumber(ARGV[3])
+local now = tonumber(ARGV[4])
+local blockDuration = tonumber(ARGV[5])
+
+local points = tonumber(redis.call('hget', key, 'points'))
+local resetAt = tonumber(redis.call('hget', key, 'resetAt'))
+local bannedUntil = tonumber(redis.call('hget', key, 'bannedUntil'))
+
+-- Initialize if missing
+if points == nil then
+  points = maxPoints
+  resetAt = now + interval
+  bannedUntil = 0
+end
+
+-- Check ban
+if bannedUntil > now then
+  return {0, 0, bannedUntil - now}
+end
+
+-- Refill if interval elapsed
+if resetAt <= now then
+  points = maxPoints
+  resetAt = now + interval
+end
+
+-- Try to consume
+if points >= cost then
+  points = points - cost
+  redis.call('hmset', key, 'points', points, 'resetAt', resetAt, 'bannedUntil', bannedUntil)
+  -- Set TTL to avoid stale keys: interval + blockDuration + buffer
+  local ttlMs = interval + blockDuration + 60000
+  redis.call('pexpire', key, ttlMs)
+  return {1, points, resetAt - now}
+end
+
+-- Exhausted
+if blockDuration > 0 then
+  bannedUntil = now + blockDuration
+  redis.call('hmset', key, 'points', points, 'resetAt', resetAt, 'bannedUntil', bannedUntil)
+  local ttlMs = blockDuration + 60000
+  redis.call('pexpire', key, ttlMs)
+  return {0, 0, blockDuration}
+end
+
+redis.call('hmset', key, 'points', points, 'resetAt', resetAt, 'bannedUntil', bannedUntil)
+local ttlMs = interval + 60000
+redis.call('pexpire', key, ttlMs)
+return {0, math.max(0, points), resetAt - now}
+`;
+
+/**
+ * @typedef {Object} RedisRateLimitOptions
+ * @property {number} points - Tokens available per interval. Must be a positive integer.
+ * @property {number} interval - Refill interval in milliseconds. Must be positive.
+ * @property {number} [blockDuration=0] - Auto-ban duration in ms when exhausted. 0 = no ban.
+ * @property {'ip' | 'connection' | ((ws: any) => string)} [keyBy='ip'] - Key extraction mode.
+ */
+
+/**
+ * @typedef {Object} ConsumeResult
+ * @property {boolean} allowed
+ * @property {number} remaining
+ * @property {number} resetMs
+ */
+
+/**
+ * @typedef {Object} RedisRateLimiter
+ * @property {(ws: any, cost?: number) => Promise<ConsumeResult>} consume
+ * @property {(key: string) => Promise<void>} reset
+ * @property {(key: string, duration?: number) => Promise<void>} ban
+ * @property {(key: string) => Promise<void>} unban
+ * @property {() => Promise<void>} clear
+ */
+
+/**
+ * Create a Redis-backed rate limiter.
+ *
+ * @param {import('./index.js').RedisClient} client
+ * @param {RedisRateLimitOptions} options
+ * @returns {RedisRateLimiter}
+ */
+export function createRateLimit(client, options) {
+	if (!options || typeof options !== 'object') {
+		throw new Error('redis ratelimit: options object is required');
+	}
+
+	const { points, interval, blockDuration = 0, keyBy = 'ip' } = options;
+
+	if (!Number.isInteger(points) || points <= 0) {
+		throw new Error('redis ratelimit: points must be a positive integer');
+	}
+	if (typeof interval !== 'number' || !Number.isFinite(interval) || interval <= 0) {
+		throw new Error('redis ratelimit: interval must be a positive number');
+	}
+	if (typeof blockDuration !== 'number' || !Number.isFinite(blockDuration) || blockDuration < 0) {
+		throw new Error('redis ratelimit: blockDuration must be a non-negative number');
+	}
+	if (keyBy !== 'ip' && keyBy !== 'connection' && typeof keyBy !== 'function') {
+		throw new Error("redis ratelimit: keyBy must be 'ip', 'connection', or a function");
+	}
+
+	const redis = client.redis;
+
+	// Per-connection keying uses a WeakMap to avoid leaks
+	const wsKeys = new WeakMap();
+	let connCounter = 0;
+
+	function resolveKey(ws) {
+		if (typeof keyBy === 'function') return keyBy(ws);
+		if (keyBy === 'connection') {
+			let k = wsKeys.get(ws);
+			if (!k) {
+				k = '__conn:' + (++connCounter);
+				wsKeys.set(ws, k);
+			}
+			return k;
+		}
+		const ud = typeof ws.getUserData === 'function' ? ws.getUserData() : null;
+		if (ud) {
+			return String(ud.remoteAddress || ud.ip || ud.address || 'unknown');
+		}
+		return 'unknown';
+	}
+
+	function bucketKey(key) {
+		return client.key('ratelimit:' + key);
+	}
+
+	return {
+		async consume(ws, cost = 1) {
+			if (typeof cost !== 'number' || !Number.isInteger(cost) || cost < 1) {
+				throw new Error('redis ratelimit: cost must be a positive integer');
+			}
+			const key = resolveKey(ws);
+			const now = Date.now();
+
+			const result = await redis.eval(
+				CONSUME_SCRIPT,
+				1,
+				bucketKey(key),
+				points,
+				interval,
+				cost,
+				now,
+				blockDuration
+			);
+
+			return {
+				allowed: result[0] === 1,
+				remaining: result[1],
+				resetMs: result[2]
+			};
+		},
+
+		async reset(key) {
+			await redis.del(bucketKey(key));
+		},
+
+		async ban(key, duration) {
+			const dur = duration ?? (blockDuration || 60000);
+			const now = Date.now();
+			const bk = bucketKey(key);
+			// Preserve existing points (if any) so unban restores the bucket
+			const existingPoints = await redis.hget(bk, 'points');
+			const existingResetAt = await redis.hget(bk, 'resetAt');
+			await redis.hmset(
+				bk,
+				'points', existingPoints ?? points,
+				'resetAt', existingResetAt ?? (now + interval),
+				'bannedUntil', now + dur
+			);
+			await redis.pexpire(bk, dur + 60000);
+		},
+
+		async unban(key) {
+			const bk = bucketKey(key);
+			await redis.hset(bk, 'bannedUntil', 0);
+		},
+
+		async clear() {
+			const pattern = client.key('ratelimit:*');
+			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');
+			connCounter = 0;
+		}
+	};
+}

package/redis/replay.d.ts

@@ -0,0 +1,47 @@
+import type { Platform } from 'svelte-adapter-uws';
+import type { RedisClient } from './index.js';
+
+export interface RedisReplayOptions {
+	/** Max messages per topic. @default 1000 */
+	size?: number;
+	/** TTL in seconds for replay keys (0 = no expiry). @default 0 */
+	ttl?: number;
+}
+
+export interface BufferedMessage {
+	seq: number;
+	topic: string;
+	event: string;
+	data: unknown;
+}
+
+export interface RedisReplayBuffer {
+	/**
+	 * Publish a message through the buffer. Stores it in Redis with a
+	 * sequence number, then calls platform.publish() as normal.
+	 */
+	publish(platform: Platform, topic: string, event: string, data?: unknown): Promise<boolean>;
+
+	/** Get the current sequence number for a topic. Returns 0 if unknown. */
+	seq(topic: string): Promise<number>;
+
+	/** Get all buffered messages after a given sequence number. */
+	since(topic: string, since: number): Promise<BufferedMessage[]>;
+
+	/**
+	 * Send buffered messages to a single connection. Sends each missed
+	 * message on `__replay:{topic}`, then an end marker.
+	 */
+	replay(ws: any, topic: string, sinceSeq: number, platform: Platform): Promise<void>;
+
+	/** Clear all replay buffers. */
+	clear(): Promise<void>;
+
+	/** Clear the buffer for a single topic. */
+	clearTopic(topic: string): Promise<void>;
+}
+
+/**
+ * Create a Redis-backed replay buffer.
+ */
+export function createReplay(client: RedisClient, options?: RedisReplayOptions): RedisReplayBuffer;

package/redis/replay.js

@@ -0,0 +1,156 @@
+/**
+ * Redis-backed replay buffer for svelte-adapter-uws.
+ *
+ * Same API as the core createReplay plugin, but stores messages in Redis
+ * sorted sets so they survive restarts and are shared across instances.
+ *
+ * Storage layout per topic:
+ *   - Key `{prefix}replay:seq:{topic}` - INCR counter for sequence numbers
+ *   - Key `{prefix}replay:buf:{topic}` - sorted set (score = seq, member = JSON payload)
+ *
+ * @module svelte-adapter-uws-extensions/redis/replay
+ */
+
+/**
+ * @typedef {Object} RedisReplayOptions
+ * @property {number} [size=1000] - Max messages per topic
+ * @property {number} [ttl=0] - TTL in seconds for replay keys (0 = no expiry)
+ */
+
+/**
+ * @typedef {Object} RedisReplayBuffer
+ * @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
+ */
+
+/**
+ * Lua script for atomic publish: increment seq, store message, trim buffer.
+ *
+ * KEYS[1] = seq key
+ * KEYS[2] = buf key (sorted set)
+ * ARGV[1] = topic
+ * ARGV[2] = event
+ * ARGV[3] = data (JSON-encoded)
+ * ARGV[4] = maxSize
+ * ARGV[5] = ttl (seconds, 0 = no expiry)
+ *
+ * Returns the new sequence number.
+ */
+const PUBLISH_SCRIPT = `
+local seqKey = KEYS[1]
+local bufKey = KEYS[2]
+local topic = ARGV[1]
+local event = ARGV[2]
+local data = ARGV[3]
+local maxSize = tonumber(ARGV[4])
+local ttl = tonumber(ARGV[5])
+
+local seq = redis.call('incr', seqKey)
+local payload = cjson.encode({seq = seq, topic = topic, event = event, data = cjson.decode(data)})
+redis.call('zadd', bufKey, seq, payload)
+
+local count = redis.call('zcard', bufKey)
+if count > maxSize then
+  redis.call('zremrangebyrank', bufKey, 0, count - maxSize - 1)
+end
+
+if ttl > 0 then
+  redis.call('expire', seqKey, ttl)
+  redis.call('expire', bufKey, ttl)
+end
+
+return seq
+`;
+
+/**
+ * Create a Redis-backed replay buffer.
+ *
+ * @param {import('./index.js').RedisClient} client
+ * @param {RedisReplayOptions} [options]
+ * @returns {RedisReplayBuffer}
+ */
+export function createReplay(client, options = {}) {
+	if (options.size !== undefined) {
+		if (typeof options.size !== 'number' || options.size < 1 || !Number.isInteger(options.size)) {
+			throw new Error(`redis 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(`redis replay: ttl must be a non-negative integer, got ${options.ttl}`);
+		}
+	}
+
+	const maxSize = options.size || 1000;
+	const ttl = options.ttl || 0;
+	const redis = client.redis;
+
+	function seqKey(topic) {
+		return client.key('replay:seq:' + topic);
+	}
+
+	function bufKey(topic) {
+		return client.key('replay:buf:' + topic);
+	}
+
+	return {
+		async publish(platform, topic, event, data) {
+			const sk = seqKey(topic);
+			const bk = bufKey(topic);
+
+			await redis.eval(
+				PUBLISH_SCRIPT, 2, sk, bk,
+				topic, event, JSON.stringify(data ?? null), maxSize, ttl
+			);
+
+			return platform.publish(topic, event, data);
+		},
+
+		async seq(topic) {
+			const val = await redis.get(seqKey(topic));
+			return val ? parseInt(val, 10) : 0;
+		},
+
+		async since(topic, since) {
+			// Get all entries with score > since
+			const raw = await redis.zrangebyscore(bufKey(topic), since + 1, '+inf');
+			return raw.map((entry) => JSON.parse(entry));
+		},
+
+		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() {
+			// Find and delete all replay keys with our prefix
+			const pattern = client.key('replay:*');
+			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');
+		},
+
+		async clearTopic(topic) {
+			await redis.del(seqKey(topic), bufKey(topic));
+		}
+	};
+}

package/shared/errors.js

@@ -0,0 +1,33 @@
+/**
+ * Thrown when a connection to an external service (Redis, Postgres) fails.
+ */
+export class ConnectionError extends Error {
+	/**
+	 * @param {string} service - e.g. 'redis', 'postgres'
+	 * @param {string} detail
+	 * @param {Error} [cause]
+	 */
+	constructor(service, detail, cause) {
+		super(`${service}: ${detail}`);
+		this.name = 'ConnectionError';
+		this.service = service;
+		if (cause) this.cause = cause;
+	}
+}
+
+/**
+ * Thrown when an operation times out.
+ */
+export class TimeoutError extends Error {
+	/**
+	 * @param {string} service
+	 * @param {string} operation
+	 * @param {number} ms
+	 */
+	constructor(service, operation, ms) {
+		super(`${service}: ${operation} timed out after ${ms}ms`);
+		this.name = 'TimeoutError';
+		this.service = service;
+		this.ms = ms;
+	}
+}