svelte-adapter-uws-extensions 0.4.1 → 0.4.2

package/README.md

@@ -849,6 +849,32 @@ Every Redis and Postgres extension accepts an optional `breaker` option -- a sha
 
 The breaker is a three-state machine: **healthy** (all requests pass through) -> **broken** after N consecutive failures (all requests fail fast via `CircuitBrokenError`) -> **probing** after a timeout (one request is allowed through to test recovery) -> back to **healthy** on success. See [Circuit breaker](#circuit-breaker) for configuration.
 
+#### Notifying clients of degradation
+
+When Redis pub/sub fails, live streams on other replicas stop receiving updates. Connected clients continue showing stale data with no indication that the stream is degraded. Use the `onStateChange` callback to publish a system-level event so clients can surface this:
+
+```js
+import { createCircuitBreaker } from 'svelte-adapter-uws-extensions/breaker';
+
+let distributed; // the bus.wrap(platform) reference
+
+export const breaker = createCircuitBreaker({
+  failureThreshold: 5,
+  resetTimeout: 30000,
+  onStateChange: (from, to) => {
+    if (!distributed) return;
+    if (to === 'broken') {
+      // Local-only publish -- Redis is down, but local clients still receive it
+      distributed.publish('__system', 'degraded', { reason: 'backend unavailable' });
+    } else if (from === 'broken' && to === 'healthy') {
+      distributed.publish('__system', 'recovered', null);
+    }
+  }
+});
+```
+
+On the client side, subscribe to `__system` and show a banner when the `degraded` event fires. On `recovered`, dismiss the banner and refetch stale data.
+
 ---
 
 ## Circuit breaker
@@ -953,6 +979,57 @@ npm test
 
 Tests use in-memory mocks for Redis and Postgres, no running services needed.
 
+### Testing your own code
+
+The `svelte-adapter-uws-extensions/testing` entry point exports the same in-memory mocks used by the extensions' own test suite. Use them to test your extension-consuming code without running Redis or Postgres:
+
+```js
+import { mockRedisClient, mockPlatform, mockWs } from 'svelte-adapter-uws-extensions/testing';
+import { createPresence } from 'svelte-adapter-uws-extensions/redis/presence';
+import { createRateLimit } from 'svelte-adapter-uws-extensions/redis/ratelimit';
+import { describe, it, expect } from 'vitest';
+
+describe('presence', () => {
+  it('tracks users across topics', async () => {
+    const client = mockRedisClient();
+    const platform = mockPlatform();
+    const presence = createPresence(client, { key: 'id' });
+
+    const ws = mockWs({ id: 'user-1', name: 'Alice' });
+    await presence.join(ws, 'room:lobby', platform);
+
+    expect(await presence.count('room:lobby')).toBe(1);
+    expect(platform.published.some(p => p.event === 'join')).toBe(true);
+
+    presence.destroy();
+  });
+});
+
+describe('rate limiting', () => {
+  it('blocks after exhausting points', async () => {
+    const client = mockRedisClient();
+    const limiter = createRateLimit(client, { points: 3, interval: 10000 });
+    const ws = mockWs({ remoteAddress: '1.2.3.4' });
+
+    for (let i = 0; i < 3; i++) {
+      expect((await limiter.consume(ws)).allowed).toBe(true);
+    }
+    expect((await limiter.consume(ws)).allowed).toBe(false);
+  });
+});
+```
+
+#### Available mocks
+
+| Export | What it mocks | Supports |
+|---|---|---|
+| `mockRedisClient(prefix?)` | `createRedisClient()` | Strings, hashes, sorted sets, pub/sub, pipelines, scan, Lua eval for all extension scripts |
+| `mockPlatform()` | Platform API | `publish()`, `send()`, `batch()`, `topic()` -- records all calls in `.published` and `.sent` |
+| `mockWs(userData?)` | uWS WebSocket | `subscribe()`, `unsubscribe()`, `getUserData()`, `getBufferedAmount()`, `close()` |
+| `mockPgClient()` | `createPgClient()` | SQL parsing for replay buffer operations, sequence counters |
+
+The circuit breaker (`createCircuitBreaker()`) is pure logic with no I/O -- use it directly in tests, no mock needed.
+
 ---
 
 ## Related projects

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-adapter-uws-extensions",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Redis and Postgres extensions for svelte-adapter-uws - distributed pub/sub, replay buffers, presence tracking, rate limiting, groups, and DB change notifications",
   "author": "Kevin Radziszewski",
   "license": "MIT",
@@ -61,6 +61,10 @@
     "./breaker": {
       "types": "./shared/breaker.d.ts",
       "default": "./shared/breaker.js"
+    },
+    "./testing": {
+      "types": "./testing/index.d.ts",
+      "default": "./testing/index.js"
     }
   },
   "files": [
@@ -68,6 +72,7 @@
     "postgres",
     "prometheus",
     "shared",
+    "testing",
     "LICENSE",
     "README.md"
   ],

package/postgres/notify.js

@@ -131,8 +131,11 @@ export function createNotifyBridge(client, options) {
 			} else if (!result && isDefaultParser) {
 				mParseErrors?.inc({ channel });
 			}
-		} catch {
+		} catch (err) {
 			mParseErrors?.inc({ channel });
+			if (!isDefaultParser) {
+				console.warn(`[postgres/notify] parse error on "${channel}":`, err.message || err);
+			}
 		}
 	}
 

package/redis/ratelimit.js

@@ -154,6 +154,11 @@ export function createRateLimit(client, options) {
 
 	const redis = client.redis;
 
+	// Version prefix for Redis keys. Different script versions use different
+	// key spaces so rolling deployments with algorithm changes don't produce
+	// inconsistent rate limiting. Old-version keys expire naturally via TTL.
+	const SCRIPT_VERSION = 'v1';
+
 	const b = options.breaker;
 	const m = options.metrics;
 	const mAllowed = m?.counter('ratelimit_allowed_total', 'Requests allowed');
@@ -190,7 +195,7 @@ export function createRateLimit(client, options) {
 	}
 
 	function bucketKey(key) {
-		return client.key('ratelimit:' + key);
+		return client.key(SCRIPT_VERSION + ':ratelimit:' + key);
 	}
 
 	return {
@@ -272,7 +277,7 @@ export function createRateLimit(client, options) {
 		async clear() {
 			if (b) b.guard();
 			try {
-				const pattern = client.key('ratelimit:*');
+				const pattern = client.key(SCRIPT_VERSION + ':ratelimit:*');
 				let cursor = '0';
 				do {
 					const [nextCursor, keys] = await redis.scan(cursor, 'MATCH', pattern, 'COUNT', 100);

package/testing/index.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Test utilities for svelte-adapter-uws-extensions.
+ *
+ * In-memory mocks for Redis, Postgres, Platform, and WebSocket that mirror
+ * the real APIs closely enough to test extension-consuming code without
+ * running any infrastructure.
+ *
+ * @module svelte-adapter-uws-extensions/testing
+ */
+
+import type { RedisClient } from '../redis/index.js';
+import type { PgClient } from '../postgres/index.js';
+
+// -- Mock Redis ---------------------------------------------------------------
+
+export interface MockRedisClient extends RedisClient {
+	/** Direct access to the string store (key -> value). */
+	readonly _store: Map<string, string>;
+	/** Direct access to sorted sets (key -> Array<{score, member}>). */
+	readonly _sortedSets: Map<string, Array<{ score: number; member: string }>>;
+	/** Direct access to hashes (key -> Map<field, value>). */
+	readonly _hashes: Map<string, Map<string, string>>;
+}
+
+/**
+ * Create an in-memory Redis client mock.
+ * Supports strings, hashes, sorted sets, pub/sub, pipelines, scan,
+ * and Lua script evaluation for all extension scripts.
+ */
+export function mockRedisClient(keyPrefix?: string): MockRedisClient;
+
+// -- Mock Platform ------------------------------------------------------------
+
+export interface MockPlatform {
+	/** All `publish()` calls recorded as `{ topic, event, data, options }`. */
+	published: Array<{ topic: string; event: string; data: any; options?: any }>;
+	/** All `send()` calls recorded as `{ ws, topic, event, data }`. */
+	sent: Array<{ ws: any; topic: string; event: string; data: any }>;
+	connections: number;
+	publish(topic: string, event: string, data?: any, options?: any): boolean;
+	send(ws: any, topic: string, event: string, data?: any): number;
+	batch(messages: Array<{ topic: string; event: string; data?: any }>): boolean[];
+	sendTo(filter: any, topic: string, event: string, data?: any): number;
+	subscribers(topic: string): number;
+	topic(t: string): {
+		publish(event: string, data?: any): void;
+		created(data?: any): void;
+		updated(data?: any): void;
+		deleted(data?: any): void;
+		set(value?: any): void;
+		increment(amount?: number): void;
+		decrement(amount?: number): void;
+	};
+	/** Clear all recorded publish/send calls. */
+	reset(): void;
+}
+
+/**
+ * Create an in-memory Platform mock that records all publish/send calls.
+ */
+export function mockPlatform(): MockPlatform;
+
+// -- Mock WebSocket -----------------------------------------------------------
+
+export interface MockWs<T extends Record<string, any> = Record<string, any>> {
+	getUserData(): T;
+	subscribe(topic: string): boolean;
+	unsubscribe(topic: string): boolean;
+	isSubscribed(topic: string): boolean;
+	getBufferedAmount(): number;
+	/** Simulate socket close. After this, subscribe/unsubscribe/getBufferedAmount throw. */
+	close(): void;
+	/** Whether close() has been called. */
+	readonly _closed: boolean;
+	/** Currently subscribed topics. */
+	readonly _topics: Set<string>;
+}
+
+/**
+ * Create an in-memory WebSocket mock. Throws after close(), matching uWS behavior.
+ */
+export function mockWs<T extends Record<string, any> = Record<string, any>>(userData?: T): MockWs<T>;
+
+// -- Mock Postgres ------------------------------------------------------------
+
+export interface MockPgClient {
+	readonly pool: {};
+	query(textOrObj: string | { text: string; values?: any[] }, values?: any[]): Promise<{ rows: any[]; rowCount: number }>;
+	end(): Promise<void>;
+	/** Get all stored rows (Postgres replay mock). */
+	_getRows(): any[];
+	/** Get sequence counters by topic (Postgres replay mock). */
+	_getSeqCounters(): Map<string, number>;
+	/** Reset all state. */
+	_reset(): void;
+}
+
+/**
+ * Create an in-memory Postgres client mock.
+ * Parses SQL to simulate the replay buffer table operations.
+ */
+export function mockPgClient(): MockPgClient;

package/testing/index.js

@@ -0,0 +1,14 @@
+/**
+ * Test utilities for svelte-adapter-uws-extensions.
+ *
+ * In-memory mocks for Redis, Postgres, Platform, and WebSocket that mirror
+ * the real APIs closely enough to test extension-consuming code without
+ * running any infrastructure.
+ *
+ * @module svelte-adapter-uws-extensions/testing
+ */
+
+export { mockRedisClient } from './mock-redis.js';
+export { mockPlatform } from './mock-platform.js';
+export { mockWs } from './mock-ws.js';
+export { mockPgClient } from './mock-pg.js';

package/testing/mock-pg.js

@@ -0,0 +1,214 @@
+/**
+ * In-memory mock that implements the PgClient interface.
+ * Parses SQL enough to simulate the ws_replay table operations
+ * and the ws_replay_seq table for atomic sequence generation.
+ */
+export function mockPgClient() {
+	/** @type {Array<{ws_replay_id: number, topic: string, seq: number, event: string, data: any, created_date: Date}>} */
+	let rows = [];
+	let nextId = 1;
+	let tableCreated = false;
+
+	/** @type {Map<string, number>} topic -> seq */
+	const seqCounters = new Map();
+
+	return {
+		pool: {},
+
+		async query(textOrObj, values) {
+			if (typeof textOrObj === 'object' && textOrObj !== null) {
+				values = textOrObj.values || [];
+				textOrObj = textOrObj.text;
+			}
+			if (!values) values = [];
+			const sql = textOrObj.trim().replace(/\s+/g, ' ');
+
+			// CREATE TABLE
+			if (sql.startsWith('CREATE TABLE')) {
+				tableCreated = true;
+				return { rows: [], rowCount: 0 };
+			}
+
+			// CREATE INDEX
+			if (sql.startsWith('CREATE INDEX')) {
+				return { rows: [], rowCount: 0 };
+			}
+
+			// CTE publish: atomic seq increment + insert in one query
+			if (sql.includes('WITH new_seq') && sql.includes('ON CONFLICT') && sql.includes('RETURNING seq')) {
+				const topic = values[0];
+				const current = seqCounters.get(topic) || 0;
+				const next = current + 1;
+				seqCounters.set(topic, next);
+				const row = {
+					ws_replay_id: nextId++,
+					topic,
+					seq: next,
+					event: values[1],
+					data: typeof values[2] === 'string' ? JSON.parse(values[2]) : values[2],
+					created_date: new Date()
+				};
+				rows.push(row);
+				return { rows: [{ seq: String(next) }], rowCount: 1 };
+			}
+
+			// INSERT INTO *_seq (atomic sequence generation)
+			if (sql.includes('ON CONFLICT') && sql.includes('RETURNING seq')) {
+				const topic = values[0];
+				const current = seqCounters.get(topic) || 0;
+				const next = current + 1;
+				seqCounters.set(topic, next);
+				return { rows: [{ seq: String(next) }], rowCount: 1 };
+			}
+
+			// INSERT
+			if (sql.startsWith('INSERT INTO')) {
+				const row = {
+					ws_replay_id: nextId++,
+					topic: values[0],
+					seq: parseInt(values[1], 10),
+					event: values[2],
+					data: typeof values[3] === 'string' ? JSON.parse(values[3]) : values[3],
+					created_date: new Date()
+				};
+				rows.push(row);
+				return { rows: [row], rowCount: 1 };
+			}
+
+			// SELECT COALESCE(seq, 0) FROM _seq table
+			if (sql.includes('current_seq') && sql.includes('_seq')) {
+				const topic = values[0];
+				const seq = seqCounters.get(topic);
+				if (seq !== undefined) {
+					return { rows: [{ current_seq: String(seq) }], rowCount: 1 };
+				}
+				return { rows: [], rowCount: 0 };
+			}
+
+			// SELECT COALESCE(MAX(seq)
+			if (sql.includes('MAX(seq)')) {
+				const topic = values[0];
+				const topicRows = rows.filter((r) => r.topic === topic);
+				const maxSeq = topicRows.reduce((max, r) => Math.max(max, r.seq), 0);
+				return { rows: [{ max_seq: String(maxSeq) }], rowCount: 1 };
+			}
+
+			// SELECT COUNT
+			if (sql.includes('COUNT(*)')) {
+				const topic = values[0];
+				const message_count = rows.filter((r) => r.topic === topic).length;
+				return { rows: [{ message_count }], rowCount: 1 };
+			}
+
+			// SELECT seq, topic, event, data ... WHERE topic = $1 AND seq > $2
+			if (sql.includes('SELECT seq, topic, event, data')) {
+				const topic = values[0];
+				const since = parseInt(values[1], 10);
+				const result = rows
+					.filter((r) => r.topic === topic && r.seq > since)
+					.sort((a, b) => a.seq - b.seq)
+					.map((r) => ({
+						seq: String(r.seq),
+						topic: r.topic,
+						event: r.event,
+						data: r.data
+					}));
+				return { rows: result, rowCount: result.length };
+			}
+
+			// Seq-based inline trim: DELETE WHERE topic = $1 AND seq <= $2
+			if (sql.includes('DELETE FROM') && sql.includes('seq <=') && !sql.includes('OFFSET') && !sql.includes('cutoff_seq')) {
+				const topic = values[0];
+				const cutoffSeq = parseInt(values[1], 10);
+				const before = rows.length;
+				rows = rows.filter((r) => r.topic !== topic || r.seq > cutoffSeq);
+				return { rows: [], rowCount: before - rows.length };
+			}
+
+			// Range-based inline trim: DELETE WHERE topic = $1 AND seq <= (SELECT ... OFFSET $2 LIMIT 1)
+			if (sql.includes('DELETE FROM') && sql.includes('seq <=') && sql.includes('OFFSET')) {
+				const topic = values[0];
+				const offset = parseInt(values[1], 10);
+				const topicRows = rows
+					.filter((r) => r.topic === topic)
+					.sort((a, b) => b.seq - a.seq);
+				if (offset < topicRows.length) {
+					const cutoffSeq = topicRows[offset].seq;
+					const before = rows.length;
+					rows = rows.filter((r) => r.topic !== topic || r.seq > cutoffSeq);
+					return { rows: [], rowCount: before - rows.length };
+				}
+				return { rows: [], rowCount: 0 };
+			}
+
+			// Range-based periodic cleanup: DELETE using OFFSET-based cutoff per topic
+			if (sql.includes('DELETE FROM') && sql.includes('cutoff_seq') && sql.includes('DISTINCT topic')) {
+				const offset = parseInt(values[0], 10);
+				const topics = [...new Set(rows.map((r) => r.topic))];
+				let totalRemoved = 0;
+				for (const topic of topics) {
+					const topicRows = rows
+						.filter((r) => r.topic === topic)
+						.sort((a, b) => b.seq - a.seq);
+					if (offset < topicRows.length) {
+						const cutoffSeq = topicRows[offset].seq;
+						const before = rows.length;
+						rows = rows.filter((r) => r.topic !== topic || r.seq > cutoffSeq);
+						totalRemoved += before - rows.length;
+					}
+				}
+				return { rows: [], rowCount: totalRemoved };
+			}
+
+			// DELETE FROM table WHERE topic = $1 AND ws_replay_id NOT IN (... LIMIT $2)
+			if (sql.includes('DELETE FROM') && sql.includes('NOT IN') && sql.includes('LIMIT')) {
+				const topic = values[0];
+				const limit = parseInt(values[1], 10);
+				const topicRows = rows
+					.filter((r) => r.topic === topic)
+					.sort((a, b) => b.seq - a.seq);
+				const keepIds = new Set(topicRows.slice(0, limit).map((r) => r.ws_replay_id));
+				const before = rows.length;
+				rows = rows.filter((r) => r.topic !== topic || keepIds.has(r.ws_replay_id));
+				return { rows: [], rowCount: before - rows.length };
+			}
+
+			// DELETE FROM *_seq WHERE topic = $1
+			if (sql.includes('DELETE FROM') && sql.includes('_seq') && sql.includes('WHERE topic')) {
+				const topic = values[0];
+				seqCounters.delete(topic);
+				return { rows: [], rowCount: 1 };
+			}
+
+			// DELETE FROM table WHERE topic = $1
+			if (sql.includes('DELETE FROM') && sql.includes('WHERE topic')) {
+				const topic = values[0];
+				const before = rows.length;
+				rows = rows.filter((r) => r.topic !== topic);
+				return { rows: [], rowCount: before - rows.length };
+			}
+
+			// DELETE FROM *_seq (clear all sequences)
+			if (sql.includes('DELETE FROM') && sql.includes('_seq')) {
+				seqCounters.clear();
+				return { rows: [], rowCount: 0 };
+			}
+
+			// DELETE FROM table (clear all)
+			if (sql.startsWith('DELETE FROM')) {
+				const before = rows.length;
+				rows = [];
+				return { rows: [], rowCount: before };
+			}
+
+			return { rows: [], rowCount: 0 };
+		},
+
+		async end() {},
+
+		// Test helpers
+		_getRows() { return rows; },
+		_getSeqCounters() { return seqCounters; },
+		_reset() { rows = []; nextId = 1; tableCreated = false; seqCounters.clear(); }
+	};
+}

package/testing/mock-platform.js

@@ -0,0 +1,44 @@
+/**
+ * Create a mock platform that records publish/send calls.
+ * Matches the core svelte-adapter-uws Platform interface.
+ */
+export function mockPlatform() {
+	const p = {
+		published: [],
+		sent: [],
+		connections: 0,
+		publish(topic, event, data, options) {
+			p.published.push({ topic, event, data, options });
+			return true;
+		},
+		send(ws, topic, event, data) {
+			p.sent.push({ ws, topic, event, data });
+			return 1;
+		},
+		batch(messages) {
+			return messages.map((m) => p.publish(m.topic, m.event, m.data));
+		},
+		sendTo(filter, topic, event, data) {
+			return 0;
+		},
+		subscribers(topic) {
+			return 0;
+		},
+		topic(t) {
+			return {
+				publish(event, data) { p.publish(t, event, data); },
+				created(data) { p.publish(t, 'created', data); },
+				updated(data) { p.publish(t, 'updated', data); },
+				deleted(data) { p.publish(t, 'deleted', data); },
+				set(value) { p.publish(t, 'set', value); },
+				increment(amount) { p.publish(t, 'increment', amount); },
+				decrement(amount) { p.publish(t, 'decrement', amount); }
+			};
+		},
+		reset() {
+			p.published.length = 0;
+			p.sent.length = 0;
+		}
+	};
+	return p;
+}

package/testing/mock-redis.js

@@ -0,0 +1,561 @@
+/**
+ * In-memory mock that implements the subset of ioredis used by the extensions.
+ * No real Redis connection needed.
+ */
+export function mockRedisClient(keyPrefix = '') {
+	const store = new Map();       // key -> value (string)
+	const sortedSets = new Map();  // key -> [{score, member}]
+	const hashes = new Map();      // key -> Map<field, value>
+	const pubsubHandlers = [];     // {channel, handler}
+
+	function mockRedis() {
+		const listeners = new Map();
+		const subscribedChannels = new Set();
+
+		const r = {
+			// String ops
+			async get(key) { return store.get(key) || null; },
+			async set(key, val) { store.set(key, String(val)); return 'OK'; },
+			async incr(key) {
+				const v = parseInt(store.get(key) || '0', 10) + 1;
+				store.set(key, String(v));
+				return v;
+			},
+			async del(...keys) {
+				let count = 0;
+				for (const k of keys) {
+					if (store.delete(k)) count++;
+					if (sortedSets.delete(k)) count++;
+					if (hashes.delete(k)) count++;
+				}
+				return count;
+			},
+			async unlink(...keys) {
+				return r.del(...keys);
+			},
+			async expire() { return 1; },
+			async pexpire() { return 1; },
+
+			// Sorted set ops
+			async zadd(key, score, member) {
+				if (!sortedSets.has(key)) sortedSets.set(key, []);
+				const set = sortedSets.get(key);
+				set.push({ score: Number(score), member });
+				set.sort((a, b) => a.score - b.score);
+				return 1;
+			},
+			async zcard(key) {
+				const set = sortedSets.get(key);
+				return set ? set.length : 0;
+			},
+			async zrangebyscore(key, min, max, ...extra) {
+				const set = sortedSets.get(key);
+				if (!set) return [];
+				const lo = min === '-inf' ? -Infinity : Number(min);
+				const hi = max === '+inf' ? Infinity : Number(max);
+				let result = set.filter((e) => e.score >= lo && e.score <= hi).map((e) => e.member);
+				const limitIdx = extra.indexOf('LIMIT');
+				if (limitIdx !== -1) {
+					const offset = Number(extra[limitIdx + 1]);
+					const count = Number(extra[limitIdx + 2]);
+					result = result.slice(offset, offset + count);
+				}
+				return result;
+			},
+			async zremrangebyrank(key, start, stop) {
+				const set = sortedSets.get(key);
+				if (!set) return 0;
+				const removed = set.splice(start, stop - start + 1);
+				return removed.length;
+			},
+
+			// Hash ops
+			async hset(key, field, value) {
+				if (!hashes.has(key)) hashes.set(key, new Map());
+				hashes.get(key).set(String(field), String(value));
+				return 1;
+			},
+			async hmset(key, ...args) {
+				if (!hashes.has(key)) hashes.set(key, new Map());
+				const h = hashes.get(key);
+				// hmset(key, field, value, field, value, ...)
+				// or hmset(key, { field: value, ... })
+				if (typeof args[0] === 'object' && args[0] !== null) {
+					for (const [f, v] of Object.entries(args[0])) {
+						h.set(String(f), String(v));
+					}
+				} else {
+					for (let i = 0; i < args.length; i += 2) {
+						h.set(String(args[i]), String(args[i + 1]));
+					}
+				}
+				return 'OK';
+			},
+			async hget(key, field) {
+				const h = hashes.get(key);
+				return h ? (h.get(field) || null) : null;
+			},
+			async hmget(key, ...fields) {
+				const h = hashes.get(key);
+				return fields.map((f) => (h ? (h.get(String(f)) ?? null) : null));
+			},
+			async hgetall(key) {
+				const h = hashes.get(key);
+				if (!h) return {};
+				const result = {};
+				for (const [k, v] of h) result[k] = v;
+				return result;
+			},
+			async hdel(key, ...fields) {
+				const h = hashes.get(key);
+				if (!h) return 0;
+				let count = 0;
+				for (const f of fields) {
+					if (h.delete(f)) count++;
+				}
+				if (h.size === 0) hashes.delete(key);
+				return count;
+			},
+			async hlen(key) {
+				const h = hashes.get(key);
+				return h ? h.size : 0;
+			},
+			async hkeys(key) {
+				const h = hashes.get(key);
+				return h ? [...h.keys()] : [];
+			},
+
+			// Pub/sub
+			async publish(channel, message) {
+				for (const handler of pubsubHandlers) {
+					if (handler.channels.has(channel)) {
+						const msgListener = handler.listeners.get('message');
+						if (msgListener) msgListener(channel, message);
+					}
+				}
+				return 1;
+			},
+			async subscribe(channel) {
+				subscribedChannels.add(channel);
+				return 1;
+			},
+			async unsubscribe(channel) {
+				subscribedChannels.delete(channel);
+				return 1;
+			},
+
+			// Eval - dispatches based on script content
+			async eval(script, numKeys, ...args) {
+				// Ban script (atomic ban with Redis TIME)
+				if (script.includes('defaultPoints') && script.includes('defaultInterval')) {
+					return evalBanScript(args);
+				}
+				// Rate limit script (token bucket)
+				if (script.includes('bannedUntil')) {
+					return evalRateLimit(args);
+				}
+				// Replay publish script (atomic incr + zadd + trim)
+				if (script.includes('zremrangebyrank') && script.includes('cjson.encode')) {
+					return evalReplayPublish(numKeys, args);
+				}
+				// Presence join script (hset + expire, no dedup scan)
+				if (script.includes('hset') && script.includes('expire') && !script.includes('hdel') && !script.includes('suffix')) {
+					return evalPresenceJoin(args);
+				}
+				// Presence leave script (hdel + check remaining by suffix)
+				if (script.includes('hdel') && script.includes('suffix')) {
+					return evalPresenceLeave(args);
+				}
+				// Stale field cleanup script (server-side HGETALL + HDEL)
+				if (script.includes('CLEANUP_STALE')) {
+					return evalCleanupStale(args);
+				}
+				// Count dedup script (presence: deduplicated by userKey via | separator)
+				if (script.includes('seen[userKey] = true') && script.includes('pairs(seen)')) {
+					return evalCountDedupScript(args);
+				}
+				// Count script (server-side live entry count)
+				if (script.includes('count = count + 1') && !script.includes('hdel') && !script.includes('hset')) {
+					return evalCountScript(args);
+				}
+				// List script (server-side presence list with dedup)
+				if (script.includes('seen[userKey]') && script.includes('best[userKey]')) {
+					return evalListScript(args);
+				}
+				// Group join script (atomic capacity check + insert)
+				if (script.includes('cjson.decode') && script.includes('liveCount')) {
+					return evalGroupJoin(numKeys, args);
+				}
+				throw new Error('mock-redis: unrecognized eval script');
+			},
+
+			// Scan
+			async scan(cursor, ...args) {
+				// Simple mock: return all matching keys in one go
+				const matchIdx = args.indexOf('MATCH');
+				const pattern = matchIdx !== -1 ? args[matchIdx + 1] : '*';
+				const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$');
+
+				const allKeys = [...store.keys(), ...sortedSets.keys(), ...hashes.keys()];
+				const matched = allKeys.filter((k) => regex.test(k));
+				return ['0', matched];
+			},
+
+			// Pipeline support for batched commands
+			pipeline() {
+				const commands = [];
+				const p = new Proxy({}, {
+					get(_, method) {
+						if (method === 'exec') {
+							return async () => {
+								const results = [];
+								for (const { method: m, args } of commands) {
+									try {
+										const result = await r[m](...args);
+										results.push([null, result]);
+									} catch (err) {
+										results.push([err, null]);
+									}
+								}
+								return results;
+							};
+						}
+						return (...args) => {
+							commands.push({ method, args });
+							return p;
+						};
+					}
+				});
+				return p;
+			},
+
+			// Lifecycle
+			duplicate(/* overrides */) {
+				const dup = mockRedis();
+				// Register this duplicate as a pub/sub receiver
+				pubsubHandlers.push({
+					channels: dup._subscribedChannels,
+					listeners: dup._listeners
+				});
+				return dup;
+			},
+			async quit() {},
+			disconnect() {},
+
+			// Event handling
+			on(event, fn) {
+				listeners.set(event, fn);
+				return r;
+			},
+
+			defineCommand(name, { lua }) {
+				r[name] = async (numKeys, ...args) => r.eval(lua, numKeys, ...args);
+			},
+
+			_subscribedChannels: subscribedChannels,
+			_listeners: listeners
+		};
+
+		// Rate limit Lua script simulation
+		function evalRateLimit(args) {
+			const key = args[0];
+			const maxPoints = Number(args[1]);
+			const interval = Number(args[2]);
+			const cost = Number(args[3]);
+			const blockDuration = Number(args[4]);
+			const now = Date.now(); // Simulates Redis TIME command
+
+			if (!hashes.has(key)) hashes.set(key, new Map());
+			const h = hashes.get(key);
+
+			let pts = h.has('points') ? Number(h.get('points')) : null;
+			let resetAt = h.has('resetAt') ? Number(h.get('resetAt')) : null;
+			let bannedUntil = h.has('bannedUntil') ? Number(h.get('bannedUntil')) : null;
+
+			if (pts === null) {
+				pts = maxPoints;
+				resetAt = now + interval;
+				bannedUntil = 0;
+			}
+
+			if (bannedUntil > now) {
+				return [0, 0, bannedUntil - now];
+			}
+
+			if (resetAt <= now) {
+				pts = maxPoints;
+				resetAt = now + interval;
+			}
+
+			if (pts >= cost) {
+				pts -= cost;
+				h.set('points', String(pts));
+				h.set('resetAt', String(resetAt));
+				h.set('bannedUntil', String(bannedUntil));
+				return [1, pts, resetAt - now];
+			}
+
+			if (blockDuration > 0) {
+				bannedUntil = now + blockDuration;
+				h.set('points', String(pts));
+				h.set('resetAt', String(resetAt));
+				h.set('bannedUntil', String(bannedUntil));
+				return [0, 0, blockDuration];
+			}
+
+			h.set('points', String(pts));
+			h.set('resetAt', String(resetAt));
+			h.set('bannedUntil', String(bannedUntil));
+			return [0, Math.max(0, pts), resetAt - now];
+		}
+
+		// Ban Lua script simulation
+		function evalBanScript(args) {
+			const key = args[0];
+			const duration = Number(args[1]);
+			const defaultPoints = Number(args[2]);
+			const defaultInterval = Number(args[3]);
+			const now = Date.now();
+
+			if (!hashes.has(key)) hashes.set(key, new Map());
+			const h = hashes.get(key);
+
+			const pts = h.get('points') ?? String(defaultPoints);
+			const rst = h.get('resetAt') ?? String(now + defaultInterval);
+
+			h.set('points', String(pts));
+			h.set('resetAt', String(rst));
+			h.set('bannedUntil', String(now + duration));
+			return 1;
+		}
+
+		// Presence join Lua script simulation
+		// HSET + EXPIRE, always returns 1.  Cross-instance dedup was removed
+		// from the real Lua script (O(N) scan per join was the bottleneck).
+		function evalPresenceJoin(args) {
+			const key = args[0];
+			const field = args[1];
+			const value = args[2];
+			// args[3] = ttlSec (for EXPIRE, no-op in mock)
+
+			if (!hashes.has(key)) hashes.set(key, new Map());
+			hashes.get(key).set(field, value);
+
+			return 1;
+		}
+
+		// Presence leave Lua script simulation
+		function evalPresenceLeave(args) {
+			const key = args[0];
+			const field = args[1];
+			const suffix = args[2];
+			const now = Number(args[3]);
+			const ttlMs = Number(args[4]);
+
+			// hdel
+			const h = hashes.get(key);
+			if (h) {
+				h.delete(field);
+				if (h.size === 0) hashes.delete(key);
+			}
+
+			// Check remaining fields for suffix match, ignoring stale entries
+			const remaining = hashes.get(key);
+			if (remaining) {
+				for (const [f, v] of remaining) {
+					if (f.length >= suffix.length && f.slice(-suffix.length) === suffix) {
+						try {
+							const parsed = JSON.parse(v);
+							if (parsed.ts && (now - parsed.ts) <= ttlMs) {
+								return 0; // User still present on another live instance
+							}
+						} catch { /* skip */ }
+					}
+				}
+			}
+			return 1; // User is gone
+		}
+
+		// Group join Lua script simulation (2 keys: members, closed)
+		function evalGroupJoin(numKeys, args) {
+			const key = args[0];
+			const closedFlag = numKeys >= 2 ? args[1] : null;
+			const argOffset = numKeys;
+			const maxMembers = Number(args[argOffset]);
+			const memberId = args[argOffset + 1];
+			const memberData = args[argOffset + 2];
+			const now = Number(args[argOffset + 3]);
+			const memberTtlMs = Number(args[argOffset + 4]);
+
+			if (closedFlag && store.get(closedFlag) === '1') {
+				return [-1];
+			}
+
+			if (!hashes.has(key)) hashes.set(key, new Map());
+			const h = hashes.get(key);
+
+			let liveCount = 0;
+			const toRemove = [];
+			const live = [];
+			for (const [f, v] of h) {
+				try {
+					const val = JSON.parse(v);
+					if (val.ts && (now - val.ts) <= memberTtlMs) {
+						liveCount++;
+						live.push(v);
+					} else {
+						toRemove.push(f);
+					}
+				} catch {
+					toRemove.push(f);
+				}
+			}
+			for (const f of toRemove) h.delete(f);
+
+			if (liveCount >= maxMembers) {
+				return [0];
+			}
+			h.set(memberId, memberData);
+			live.push(memberData);
+			return [1, ...live];
+		}
+
+		// Replay publish Lua script simulation
+		// args layout: [seqKey, bufKey, topic, event, dataJson, maxSize, ttl]
+		function evalReplayPublish(numKeys, args) {
+			const seqKey = args[0];
+			const bufKey = args[1];
+			const topic = args[2];
+			const event = args[3];
+			const dataJson = args[4];
+			const maxSize = Number(args[5]);
+
+			// Increment seq
+			const v = parseInt(store.get(seqKey) || '0', 10) + 1;
+			store.set(seqKey, String(v));
+			const seq = v;
+
+			// zadd
+			const data = JSON.parse(dataJson);
+			const payload = JSON.stringify({ seq, topic, event, data });
+			if (!sortedSets.has(bufKey)) sortedSets.set(bufKey, []);
+			const set = sortedSets.get(bufKey);
+			set.push({ score: seq, member: payload });
+			set.sort((a, b) => a.score - b.score);
+
+			// Trim
+			if (set.length > maxSize) {
+				set.splice(0, set.length - maxSize);
+			}
+
+			return seq;
+		}
+
+		// Count dedup Lua script simulation (presence: deduplicated by userKey)
+		function evalCountDedupScript(args) {
+			const key = args[0];
+			const now = Number(args[1]);
+			const ttlMs = Number(args[2]);
+			const h = hashes.get(key);
+			if (!h) return 0;
+			const seen = new Set();
+			for (const [field, v] of h) {
+				try {
+					const parsed = JSON.parse(v);
+					if (parsed.ts && (now - parsed.ts) <= ttlMs) {
+						const sep = field.indexOf('|');
+						const userKey = sep !== -1 ? field.slice(sep + 1) : field;
+						seen.add(userKey);
+					}
+				} catch { /* skip */ }
+			}
+			return seen.size;
+		}
+
+		// Count Lua script simulation
+		function evalCountScript(args) {
+			const key = args[0];
+			const now = Number(args[1]);
+			const ttlMs = Number(args[2]);
+			const h = hashes.get(key);
+			if (!h) return 0;
+			let count = 0;
+			for (const [, v] of h) {
+				try {
+					const parsed = JSON.parse(v);
+					if (parsed.ts && (now - parsed.ts) <= ttlMs) count++;
+				} catch { /* skip */ }
+			}
+			return count;
+		}
+
+		// List Lua script simulation (presence list with per-user dedup)
+		function evalListScript(args) {
+			const key = args[0];
+			const now = Number(args[1]);
+			const ttlMs = Number(args[2]);
+			const h = hashes.get(key);
+			if (!h) return [];
+			const seen = new Map();
+			for (const [field, v] of h) {
+				try {
+					const parsed = JSON.parse(v);
+					if (parsed.ts && (now - parsed.ts) <= ttlMs) {
+						const sep = field.indexOf('|');
+						const userKey = sep !== -1 ? field.slice(sep + 1) : field;
+						const existing = seen.get(userKey);
+						if (!existing || parsed.ts > existing.ts) {
+							seen.set(userKey, { ts: parsed.ts, json: v });
+						}
+					}
+				} catch { /* skip */ }
+			}
+			const out = [];
+			for (const [k, v] of seen) {
+				out.push(k, v.json);
+			}
+			return out;
+		}
+
+		// Stale field cleanup Lua script simulation
+		function evalCleanupStale(args) {
+			const key = args[0];
+			const now = Number(args[1]);
+			const ttlMs = Number(args[2]);
+
+			const h = hashes.get(key);
+			if (!h) return 0;
+
+			const toRemove = [];
+			for (const [f, v] of h) {
+				try {
+					const parsed = JSON.parse(v);
+					if (!parsed.ts || (now - parsed.ts) > ttlMs) {
+						toRemove.push(f);
+					}
+				} catch {
+					toRemove.push(f);
+				}
+			}
+			for (const f of toRemove) h.delete(f);
+			if (h.size === 0) hashes.delete(key);
+			return toRemove.length;
+		}
+
+		return r;
+	}
+
+	const redis = mockRedis();
+
+	return {
+		redis,
+		keyPrefix,
+		key(k) { return keyPrefix + k; },
+		duplicate(overrides) { return redis.duplicate(overrides); },
+		async quit() {},
+		// Test helpers
+		_store: store,
+		_sortedSets: sortedSets,
+		_hashes: hashes
+	};
+}

package/testing/mock-ws.js

@@ -0,0 +1,23 @@
+/**
+ * Create a mock WebSocket that mimics the uWS/vite wrapper API.
+ * Call ws.close() to simulate a dead socket whose close handler never fired.
+ * After close(), subscribe/unsubscribe/getBufferedAmount throw, matching uWS.
+ * @param {Record<string, any>} [userData]
+ */
+export function mockWs(userData = {}) {
+	const topics = new Set();
+	let closed = false;
+	function assertOpen() {
+		if (closed) throw new Error('WebSocket is closed');
+	}
+	return {
+		getUserData: () => userData,
+		subscribe: (topic) => { assertOpen(); topics.add(topic); return true; },
+		unsubscribe: (topic) => { assertOpen(); topics.delete(topic); return true; },
+		isSubscribed: (topic) => topics.has(topic),
+		getBufferedAmount: () => { assertOpen(); return 0; },
+		close: () => { closed = true; },
+		get _closed() { return closed; },
+		_topics: topics
+	};
+}