svelte-adapter-uws-extensions 0.4.0 → 0.4.2

package/README.md

@@ -42,6 +42,7 @@ The core adapter keeps everything in-process memory. That works great for single
 - [Prometheus metrics](#prometheus-metrics)
 
 **Reliability**
+- [Failure handling](#failure-handling)
 - [Circuit breaker](#circuit-breaker)
 
 **Operations**
@@ -144,7 +145,9 @@ export const pg = createPgClient({
 
 ## Pub/sub bus
 
-Distributes `platform.publish()` calls across multiple server instances via Redis pub/sub. Each instance publishes locally AND to Redis. Incoming Redis messages are forwarded to the local platform with echo suppression (messages from the same instance are ignored).
+Distributes `platform.publish()` calls across multiple server instances via Redis pub/sub. Each instance publishes locally AND to Redis. Incoming Redis messages are forwarded to the local platform with echo suppression (messages originating from the same instance are dropped on receive, keyed by a per-process instance ID).
+
+Multiple `publish()` calls within the same event-loop tick are coalesced into a single Redis pipeline via microtask batching. This means a form action that publishes to three topics results in one pipelined round trip, not three independent commands.
 
 #### Setup
 
@@ -198,6 +201,10 @@ export function message(ws, { data, platform }) {
 
 Same API as the core `createReplay` plugin, but backed by Redis sorted sets. Messages survive restarts and are shared across instances.
 
+Sequence numbers are incremented atomically via a Lua script (`INCR` + `ZADD` + trim in a single `EVAL`), so concurrent publishes from multiple instances produce strictly ordered, gap-free sequences per topic. When the buffer exceeds `size`, the oldest entries are removed inside the same Lua script -- no second round trip required.
+
+When a client requests replay, the buffer checks whether the client's last-seen sequence is older than the oldest buffered entry. If it is (the buffer was trimmed past the client's position), a `truncated` event fires on `__replay:{topic}` before any `msg` events, so the client knows it missed messages and can do a full reload. This also fires when the buffer is completely empty but the sequence counter has advanced past the client's position (e.g. all entries expired via TTL).
+
 #### Setup
 
 ```js
@@ -269,6 +276,12 @@ All methods are async (they hit Redis). The API otherwise matches the core plugi
 
 Same API as the core `createPresence` plugin, but backed by Redis hashes. Presence state is shared across instances with cross-instance join/leave notifications via Redis pub/sub.
 
+Joins are staged with full rollback on failure: local state is set up first, then the Redis hash field is written, then the WebSocket is subscribed. If any step fails (circuit breaker trips, Redis is down, WebSocket closed during an async gap), all prior steps are undone -- local maps, the Redis field, and any broadcast join event are reversed. This prevents ghost entries that would show a user as online when they never fully connected.
+
+Leaves use an atomic Lua script (`LEAVE_SCRIPT`) that removes this instance's field from the hash and then scans remaining fields for the same user key, ignoring stale entries. Leave is only broadcast when no other instance holds a live entry for that user, preventing premature "user left" notifications in multi-instance deployments.
+
+Zombie cleanup runs on the heartbeat interval. Each tick, every tracked WebSocket is probed via `getBufferedAmount()` -- if the call throws, the socket is dead and its presence is removed synchronously before the heartbeat writes to Redis. The heartbeat then refreshes timestamps on all live entries via a Redis pipeline and runs a server-side Lua cleanup script (`CLEANUP_SCRIPT`) that scans the hash and removes any fields whose timestamp exceeds the TTL. This handles crashed instances whose close handlers never fired.
+
 #### Setup
 
 ```js
@@ -527,7 +540,11 @@ export function close(ws, { platform }) {
 
 ## Replay buffer (Postgres)
 
-Same API as the Redis replay buffer, but backed by a Postgres table. Best suited for durable audit trails or history that needs to survive longer than Redis TTLs. Sequence numbers are generated atomically via a dedicated `_seq` table, so they are safe across multiple server instances.
+Same API as the Redis replay buffer, but backed by a Postgres table. Best suited for durable audit trails or history that needs to survive longer than Redis TTLs. Sequence numbers are generated atomically via a dedicated `_seq` table using `INSERT ... ON CONFLICT DO UPDATE`, so concurrent publishes from multiple instances produce strictly ordered sequences with no duplicates or gaps.
+
+Buffer trimming runs after each publish by deleting rows with `seq <= currentSeq - maxSize`. If the trim query fails, the publish still succeeds -- the periodic background cleanup (configurable via `cleanupInterval`) catches any excess rows later.
+
+Same gap detection behavior as the Redis replay buffer: if the client's last-seen sequence is older than the oldest buffered row, or the buffer is empty but the sequence counter has advanced, a `truncated` event fires before replay.
 
 #### Setup
 
@@ -669,10 +686,14 @@ The client side needs no changes -- the core `crud('messages')` store already ha
 
 #### Limitations
 
-- Payload is limited to 8KB by Postgres. For large rows, send the row ID in the notification and let the client fetch the full row.
+- **Payload is hard-limited to ~8000 bytes by Postgres** (`pg_notify` silently truncates or errors above this). This is a Postgres constraint, not a library limitation. The bridge warns at 7500 bytes. For large rows, send the row ID in the notification and let the client fetch the full row via an API call.
 - Only fires from triggers. Changes made outside your app (manual SQL, migrations) are invisible unless you add triggers for those tables too.
 - This is not logical replication. It is simpler, works on every Postgres provider, and needs no extensions or superuser access.
 
+#### When to use this instead of Redis pub/sub
+
+If your real-time events are driven by database writes and you do not need Redis for other extensions (presence, rate limiting, groups, cursors), the LISTEN/NOTIFY bridge is a simpler deployment: no Redis infrastructure, no separate pub/sub channel management, and your notifications are inherently tied to committed transactions. Use the Redis pub/sub bus when you need to broadcast events that do not originate from database writes, or when you are already running Redis for other extensions.
+
 ---
 
 **Observability**
@@ -812,6 +833,50 @@ const metrics = createMetrics({
 
 **Reliability**
 
+## Failure handling
+
+Every Redis and Postgres extension accepts an optional `breaker` option -- a shared [circuit breaker](#circuit-breaker) that tracks backend health across all extensions wired to it. When the breaker trips, each extension degrades differently depending on whether the operation is critical or best-effort:
+
+| Extension | Awaited operations (join, consume, publish) | Fire-and-forget operations |
+|---|---|---|
+| **Pub/sub bus** | `wrap().publish()` queues to local platform only; relay to Redis is skipped silently | Microtask relay flush is skipped entirely |
+| **Presence** | `join()` / `leave()` throw `CircuitBrokenError` | Heartbeat refresh and stale cleanup are skipped |
+| **Replay buffer** | `publish()` / `replay()` / `seq()` throw `CircuitBrokenError` | -- |
+| **Rate limiting** | `consume()` throws `CircuitBrokenError` (fail-closed -- requests are blocked, not allowed through) | -- |
+| **Broadcast groups** | `join()` / `leave()` throw `CircuitBrokenError` | Heartbeat refresh is skipped |
+| **Cursor** | -- | Hash writes and cross-instance relay are skipped; local throttle continues |
+| **LISTEN/NOTIFY** | `activate()` throws; auto-reconnect retries on its own interval | -- |
+
+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
 
 Prevents thundering herd when a backend goes down. When Redis or Postgres becomes unreachable, every extension that uses the breaker fails fast instead of queueing up timeouts, and fire-and-forget operations (heartbeats, relay flushes, cursor broadcasts) are skipped entirely.
@@ -914,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.0",
+  "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/redis/replay.js

@@ -164,7 +164,6 @@ export function createReplay(client, options = {}) {
 			let rawAll;
 			try {
 				rawAll = await redis.zrangebyscore(bufKey(topic), '-inf', '+inf');
-				b?.success();
 			} catch (err) {
 				b?.failure(err);
 				throw err;
@@ -192,6 +191,21 @@ export function createReplay(client, options = {}) {
 				} catch { /* skip corrupted */ }
 			}
 
+			if (oldestSeq === null && sinceSeq > 0 && missed.length === 0) {
+				try {
+					const val = await redis.get(seqKey(topic));
+					const currentSeq = val ? parseInt(val, 10) : 0;
+					if (currentSeq > sinceSeq) {
+						mTruncations?.inc({ topic: mt(topic) });
+						platform.send(ws, replayTopic, 'truncated', null);
+					}
+				} catch (err) {
+					b?.failure(err);
+					throw err;
+				}
+			}
+			b?.success();
+
 			for (let i = 0; i < missed.length; i++) {
 				const msg = missed[i];
 				platform.send(ws, replayTopic, 'msg', {

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