svelte-realtime 0.4.13 → 0.4.15

package/README.md

@@ -261,7 +261,7 @@ The `merge` option on `live.stream()` controls how live pub/sub events are appli
 
 ### crud (default)
 
-Handles `created`, `updated`, `deleted` events. The store maintains an array, keyed by `id` (configurable with `key`).
+Handles `created`, `updated`, `deleted` events. The store maintains an array, keyed by `id` (configurable with `key`). Set `max` to cap the buffer size and drop the oldest items when exceeded (useful for live feeds with `prepend: true`).
 
 ```js
 // Server
@@ -361,7 +361,7 @@ Events: `update` (add/update by key), `remove` (remove by key), `set` (replace a
 | `merge` | `'crud'` | Merge strategy: `'crud'`, `'latest'`, `'set'`, `'presence'`, `'cursor'` |
 | `key` | `'id'` | Key field for `crud` mode |
 | `prepend` | `false` | Prepend new items instead of appending (`crud` mode) |
-| `max` | `50` | Max items to keep (`latest` mode) |
+| `max` | `50` / `0` | Max items to keep. Defaults to 50 for `latest`, 0 (unlimited) for `crud`. Oldest items are dropped when exceeded |
 | `replay` | `false` | Enable seq-based replay for gap-free reconnection |
 | `onSubscribe` | -- | Callback `(ctx, topic)` fired when a client subscribes |
 | `onUnsubscribe` | -- | Callback `(ctx, topic)` fired when a client disconnects |
@@ -1595,6 +1595,18 @@ export const message = createMessage({ platform: (p) => bus.wrap(p) });
 
 No changes needed in your live modules. `ctx.publish` delegates to whatever platform was passed in, so Redis wrapping is transparent.
 
+If you already run Postgres and don't need Redis, you can use the [LISTEN/NOTIFY bridge](#postgres-notify) instead for cross-instance pub/sub.
+
+### What the extensions handle
+
+When you add the Redis extensions from [svelte-adapter-uws-extensions](https://github.com/lanteanio/svelte-adapter-uws-extensions), you get:
+
+- **Cross-instance pub/sub** with echo suppression (messages from the same instance are dropped on receive) and microtask-batched Redis pipelines (multiple publishes in one event loop tick become a single Redis roundtrip)
+- **Distributed presence** with heartbeat-based zombie cleanup -- dead sockets are detected by probing `getBufferedAmount()`, and stale Redis entries are cleaned server-side by a Lua script after a configurable TTL (default 90s)
+- **Replay buffers** with atomic sequence numbering via Lua `INCR` + sorted sets -- per-topic ordering is strict, and gap detection triggers a truncation event before replaying what's available
+- **Cross-instance rate limiting** via atomic Lua scripts that use `redis.call('TIME')` to avoid clock skew between app servers
+- **Circuit breakers** with a three-state machine (healthy / broken / probing) -- when Redis goes down, the breaker trips after a configurable failure threshold, local delivery continues, and a single probe request tests recovery before resuming full traffic
+
 ### Combined: Redis + rate limiting
 
 ```js
@@ -1653,9 +1665,37 @@ export const orders = live.stream('orders', async (ctx) => {
 
 ---
 
+## Failure modes
+
+### Redis goes down
+
+All Redis extensions accept an optional circuit breaker. The breaker trips after a configurable number of consecutive failures (default 5). Once broken, cross-instance pub/sub, presence writes, replay buffering, and distributed rate limiting are skipped entirely -- no retries, no queuing, no thundering herd. Local delivery continues normally: `ctx.publish()` still reaches subscribers on the same instance and across workers. After a configurable timeout (default 30s), the breaker enters a probing state where a single request is allowed through. If it succeeds, the breaker resets to healthy and all extensions resume.
+
+### Instance crashes mid-session
+
+The distributed presence extension runs a heartbeat cycle (default 30s) that probes each tracked WebSocket with `getBufferedAmount()`. Under mass disconnect, the runtime may drop close events entirely -- the heartbeat catches these and triggers a synchronous leave. On the Redis side, stale presence entries are cleaned by a server-side Lua script that scans the hash and removes fields older than the configurable TTL (default 90s). The `LEAVE_SCRIPT` atomically checks whether the same user is still connected on another instance before broadcasting a leave event, so users don't appear to leave and rejoin when a single instance restarts.
+
+### Client reconnects after a long disconnect
+
+Reconnection uses up to three tiers depending on what's available and how large the gap is. The replay buffer (configurable, default 1000 messages per topic) fills small gaps with strict per-topic ordering via atomic Lua sequence numbering. If the gap is too large for replay, delta sync kicks in -- the client sends its last known version, and the server returns only the changes since that version (or `{unchanged: true}` if nothing changed). If neither replay nor delta sync can cover the gap, the client falls back to a full refetch of the init function. All three paths are automatic and require no client-side code changes.
+
+### Send buffer overflow
+
+Each WebSocket connection has a send buffer limit (default 1MB, configurable via `maxBackpressure` in the adapter). When the buffer is full, messages are silently dropped. In dev mode, `handleRpc` logs a warning when a response fails to deliver. For streams that produce high-frequency output, wrap the source with `live.breaker()` or use `live.throttle()` / `live.debounce()` to control the publish rate.
+
+### Batch and queue limits
+
+A single `batch()` call is capped at 50 RPC calls -- the client rejects before sending, and the server enforces the same cap as a safety net. The adapter's client-side send queue holds up to 1000 messages; when full, the oldest item is dropped. The adapter rate-limits WebSocket upgrades per IP with a sliding window (default 10 per 10s) to prevent connection floods.
+
+---
+
 ## Clustering
 
-svelte-realtime works with the adapter's `CLUSTER_WORKERS` mode.
+svelte-realtime works with the adapter's `CLUSTER_WORKERS` mode. The adapter spawns N worker threads (default: number of CPUs). On Linux, workers share the port via `SO_REUSEPORT` and the kernel distributes incoming connections. On macOS and Windows, a primary thread accepts connections and routes them to workers via uWS child app descriptors.
+
+Cross-worker `ctx.publish()` calls are batched via microtask coalescing -- all publishes within one event loop tick are bundled into a single `postMessage` to the primary thread, which fans them out to other workers. This keeps IPC overhead constant regardless of publish volume.
+
+Workers are health-checked every 10 seconds. If a worker fails to respond within 30 seconds, it is terminated and restarted with exponential backoff (starting at 100ms, max 5s, up to 50 restart attempts before the process exits). On graceful shutdown (`SIGTERM` / `SIGINT`), the primary stops accepting connections, sends a shutdown signal to all workers, and waits for them to drain in-flight requests and close WebSocket connections with code 1001 (Going Away) so clients reconnect to another instance.
 
 | Method | Cross-worker? | Safe in `live()`? |
 |---|---|---|
@@ -1669,24 +1709,40 @@ svelte-realtime works with the adapter's `CLUSTER_WORKERS` mode.
 
 ---
 
-## Limits and gotchas
+## Production limits
 
 ### maxPayloadLength (default: 16KB)
 
-If an RPC request exceeds this, the adapter closes the connection silently (uWS behavior). If your app sends large payloads, increase `maxPayloadLength` in the adapter's websocket config.
+Maximum size of a single WebSocket message. If an RPC request exceeds this, the adapter closes the connection (uWS behavior). Increase `maxPayloadLength` in the adapter's websocket config if your app sends large payloads.
 
 ### maxBackpressure (default: 1MB)
 
-If a connection's send buffer exceeds this, messages are silently dropped. `handleRpc` checks the return value of `platform.send()` and warns in dev mode if a response was not delivered.
+Per-connection send buffer. When exceeded, messages are silently dropped. `handleRpc` checks the return value of `platform.send()` and warns in dev mode when a response is not delivered.
 
-### sendQueue cap (client-side, max 1000)
+### Client send queue (max 1000)
 
-The adapter's `sendQueued()` drops the oldest item if the queue exceeds 1000. Unlikely in practice, but worth knowing for offline-heavy apps.
+The adapter's `sendQueued()` drops the oldest item when the queue exceeds 1000 messages. This queue buffers messages while the WebSocket is reconnecting.
 
-### Batch size (max 50 calls)
+### Batch size (max 50)
 
 A single `batch()` call is limited to 50 RPC calls. The client rejects before sending if the limit is exceeded, and the server enforces the same limit as a safety net. Split into multiple `batch()` calls if you need more.
 
+### Presence refs (max 10,000)
+
+The server tracks presence join/leave refcounts in memory. When the map reaches 10,000 entries, suspended entries (those with a pending leave timer) are evicted first. If the map is still full after eviction, the join is dropped silently.
+
+### Rate-limit identities (max 5,000)
+
+Per-function rate limiting (`live.rateLimit()`) tracks sliding-window buckets in memory. When the bucket map reaches 5,000 entries, stale buckets are swept first. If still full, new identities are rejected with a `RATE_LIMITED` error. Existing identities are unaffected.
+
+### Throttle/debounce timers (max 5,000)
+
+The server tracks active throttle and debounce entries globally. When at capacity, new entries bypass the timer and publish immediately so data is never silently dropped.
+
+### Topic length (max 256 characters)
+
+The adapter rejects topic names longer than 256 characters or containing control characters (byte value < 32). This applies to subscribe, unsubscribe, and batch-subscribe messages.
+
 ### ws.subscribe() vs the subscribe hook
 
 `live.stream()` calls `ws.subscribe(topic)` server-side, bypassing the adapter's `subscribe` hook entirely. This is correct -- stream topics are gated by `guard()`, not the subscribe hook.
@@ -1939,7 +1995,7 @@ The plugin resolves `$live/chat` to `src/live/chat.js`, generates client stubs,
 
 ## Benchmarks
 
-The benchmark suite measures overhead added by svelte-realtime on top of raw WebSocket messaging.
+The benchmark suite measures the full-stack overhead added by svelte-realtime on top of raw WebSocket messaging: JSON serialization, RPC path resolution, registry lookup, context construction, handler execution, and response encoding. These run in-process with mock objects and isolate the framework cost from network latency.
 
 Run with:
 
@@ -1962,7 +2018,7 @@ With high-frequency streams (e.g. 1000 cursors at 20 updates/sec), this reduces
 
 In Node/SSR (tests, `__directCall`, etc.), events apply synchronously -- no batching overhead.
 
-These benchmarks run in-process with mock objects (no real network). They isolate the framework overhead from network latency. See [bench/rpc.js](bench/rpc.js) for the full source.
+See [bench/rpc.js](bench/rpc.js) for the full source.
 
 ---
 

package/client.d.ts

@@ -1,6 +1,17 @@
 import type { Readable } from 'svelte/store';
 import type { WSEvent } from 'svelte-adapter-uws/client';
 
+/**
+ * A store that always holds `undefined`. Use as a fallback for conditional
+ * streams so you don't need to import `readable` from `svelte/store`:
+ *
+ * ```svelte
+ * import { todos, empty } from '$live/todos';
+ * const items = $derived(user ? todos(orgId) : empty);
+ * ```
+ */
+export const empty: Readable<undefined>;
+
 /**
  * Typed error for RPC failures.
  * Contains a `code` field for programmatic handling.

package/client.js

@@ -1,6 +1,9 @@
 // @ts-check
 import { connect as _connect, on, status } from 'svelte-adapter-uws/client';
-import { writable } from 'svelte/store';
+import { writable, readable } from 'svelte/store';
+
+/** @type {import('svelte/store').Readable<undefined>} */
+export const empty = readable(undefined);
 
 const _textEncoder = new TextEncoder();
 
@@ -499,7 +502,7 @@ function _createStream(path, options, dynamicArgs) {
 	let merge = options?.merge || 'crud';
 	let key = options?.key || 'id';
 	let prepend = options?.prepend || false;
-	let max = options?.max || 50;
+	let max = options?.max || (merge === 'latest' ? 50 : 0);
 
 	/** @type {any} */
 	let currentValue;
@@ -637,9 +640,18 @@ function _createStream(path, options, dynamicArgs) {
 					currentValue.unshift(data);
 					for (const [k, i] of _index) _index.set(k, i + 1);
 					_index.set(data[key], 0);
+					if (max && currentValue.length > max) {
+						const removed = currentValue.splice(max);
+						for (const item of removed) _index.delete(item[key]);
+					}
 				} else {
 					_index.set(data[key], currentValue.length);
 					currentValue.push(data);
+					if (max && currentValue.length > max) {
+						const removed = currentValue.splice(0, currentValue.length - max);
+						for (const item of removed) _index.delete(item[key]);
+						_rebuildIndex();
+					}
 				}
 			} else if (event === 'updated') {
 				const idx = _index.get(data[key]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-realtime",
-  "version": "0.4.13",
+  "version": "0.4.15",
   "description": "Realtime RPC and reactive subscriptions for SvelteKit, built on svelte-adapter-uws",
   "author": "Kevin Radziszewski",
   "license": "MIT",

package/server.d.ts

@@ -67,8 +67,10 @@ export interface StreamOptions {
 	prepend?: boolean;
 
 	/**
-	 * Maximum items to keep (latest mode only).
-	 * @default 50
+	 * Maximum items to keep. When the buffer exceeds this size, the oldest
+	 * items are dropped. Works with `crud` and `latest` merge strategies.
+	 *
+	 * For `latest`, defaults to 50. For `crud`, defaults to 0 (unlimited).
 	 */
 	max?: number;
 

package/vite.js

@@ -785,7 +785,9 @@ function _generateClientStubs(filePath, modulePath, dir) {
 		? `import { ${[...imports].join(', ')} } from 'svelte-realtime/client';\n`
 		: '';
 
-	return importLine + lines.join('\n') + '\n';
+	const reexport = `export { empty } from 'svelte-realtime/client';\n`;
+
+	return importLine + reexport + lines.join('\n') + '\n';
 }
 
 /**
@@ -1712,10 +1714,12 @@ function _generateTypeDeclarations(liveDir, dir) {
 				if (needsRpcError) clientImports.push('RpcError');
 				declarations.push(`  import type { ${clientImports.join(', ')} } from 'svelte-realtime/client';`);
 			}
+			declarations.push(`  import type { Readable } from 'svelte/store';`);
 			if (needsStreamStore || needsRpcError) {
 				declarations.push('');
 			}
 			declarations.push(...exports);
+			declarations.push(`  export const empty: Readable<undefined>;`);
 			declarations.push('}');
 			declarations.push('');
 		}