svelte-realtime 0.4.20 → 0.4.22

package/README.md

@@ -147,8 +147,6 @@ export const messages = live.stream('messages', async (ctx) => {
 
 {#if $messages === undefined}
   <p>Loading...</p>
-{:else if $messages?.error}
-  <p>Failed to load: {$messages.error.message}</p>
 {:else}
   {#each $messages as msg (msg.id)}
     <p><b>{msg.userId}:</b> {msg.text}</p>
@@ -378,21 +376,19 @@ When the WebSocket reconnects, streams automatically refetch initial data and re
 
 ## Error handling
 
-Stream stores have three states:
+The data store value never changes shape. It is always your data type or `undefined` while loading. Errors and connection status live on separate reactive stores so a network failure can never crash your UI:
 
-| Value | Meaning |
-|---|---|
-| `undefined` | Loading (initial fetch in progress) |
-| `Array` / `any` | Data loaded and receiving live updates |
-| `{ error: RpcError }` | Initial fetch failed |
+| Property | Type | Description |
+|---|---|---|
+| `$store` | `T \| undefined` | Your data. Never replaced by an error object. On failure, the last loaded value is preserved. |
+| `store.error` | `Readable<RpcError \| null>` | Current error, or `null` when healthy. |
+| `store.status` | `Readable<'loading' \| 'connected' \| 'reconnecting' \| 'error'>` | Connection status. |
 
-Handle all three in your template:
+Handle loading in your template:
 
 ```svelte
 {#if $messages === undefined}
   <p>Loading...</p>
-{:else if $messages?.error}
-  <p>Failed: {$messages.error.message}</p>
 {:else}
   {#each $messages as msg (msg.id)}
     <p>{msg.text}</p>
@@ -400,6 +396,27 @@ Handle all three in your template:
 {/if}
 ```
 
+To show errors, subscribe to the `.error` store:
+
+```svelte
+<script>
+  import { messages } from '$live/chat';
+
+  const err = messages.error;
+  const status = messages.status;
+</script>
+
+{#if $err}
+  <p>Error: {$err.message} ({$err.code})</p>
+{/if}
+
+{#if $status === 'reconnecting'}
+  <p>Reconnecting...</p>
+{/if}
+```
+
+Defensive patterns like `($store ?? []).filter(...)` work correctly because `$store` is always an array or `undefined`.
+
 For RPC calls, errors are thrown as `RpcError` with a `code` field:
 
 ```js
@@ -421,22 +438,23 @@ try {
 When the adapter's `ready()` promise rejects (terminal close codes 1008, 4401, 4403, exhausted retries, or explicit `close()`), svelte-realtime:
 
 - Rejects all pending RPCs immediately with `RpcError('CONNECTION_CLOSED', ...)`
-- Sets an `{ error }` state on all active stream stores
+- Sets `.error` on all active stream stores (the data value is preserved)
 - Drains the offline queue with errors
 
 RPCs called after a terminal close reject immediately without sending.
 
 ### Reusable error boundary component
 
-For Svelte 5, you can build a reusable boundary that handles all three stream states:
+For Svelte 5, you can build a reusable boundary that handles loading and error states:
 
 ```svelte
 <!-- src/lib/StreamView.svelte -->
 <script>
-  /** @type {{ store: import('svelte/store').Readable, children: import('svelte').Snippet, loading?: import('svelte').Snippet, error?: import('svelte').Snippet<[any]> }} */
+  /** @type {{ store: any, children: import('svelte').Snippet, loading?: import('svelte').Snippet, error?: import('svelte').Snippet<[any]> }} */
   let { store, children, loading, error } = $props();
 
   let value = $derived($store);
+  const err = store.error;
 </script>
 
 {#if value === undefined}
@@ -445,11 +463,11 @@ For Svelte 5, you can build a reusable boundary that handles all three stream st
   {:else}
     <p>Loading...</p>
   {/if}
-{:else if value?.error}
+{:else if $err}
   {#if error}
-    {@render error(value.error)}
+    {@render error($err)}
   {:else}
-    <p>Error: {value.error.message}</p>
+    <p>Error: {$err.message}</p>
   {/if}
 {:else}
   {@render children()}
@@ -492,7 +510,7 @@ With default slots, the minimal version is just:
 </StreamView>
 ```
 
-This removes the `{#if}/{:else if}/{:else}` boilerplate from every page that uses a stream.
+This removes the `{#if}/{:else}` boilerplate from every page that uses a stream.
 
 ---
 
@@ -673,6 +691,32 @@ export async function load({ platform, locals }) {
 
 The hydrated store still subscribes for live updates on first render. It keeps the SSR data visible instead of showing `undefined` during the initial fetch. Guards still run during `.load()` calls. Pass `{ user }` as the second argument if your guard or init function needs user data.
 
+For dynamic streams (streams with a topic function), call the stream first to get the store, then hydrate:
+
+```js
+// src/routes/team/[id]/+page.server.js
+export async function load({ platform, locals, params }) {
+  const { invitations } = await import('$live/invitation');
+  const data = await invitations.load(platform, { args: [params.id], user: locals.user });
+  return { invitations: data };
+}
+```
+
+```svelte
+<!-- src/routes/team/[id]/+page.svelte -->
+<script>
+  import { invitations } from '$live/invitation';
+  import { page } from '$app/state';
+  let { data } = $props();
+
+  const invites = invitations(page.params.id).hydrate(data.invitations);
+</script>
+
+{#each $invites as invite (invite.id)}
+  <p>{invite.email}</p>
+{/each}
+```
+
 ---
 
 ## Batching
@@ -890,6 +934,7 @@ Call `configure()` once at app startup. The hooks fire on state transitions only
 | Option | Description |
 |---|---|
 | `url` | Full WebSocket URL for cross-origin or native app usage (e.g. `'wss://api.example.com/ws'`) |
+| `auth` | `true` (or a custom path) to enable an HTTP preflight before each WebSocket upgrade so cookies set by the server's `authenticate` hook ride a normal HTTP response. Required behind Cloudflare Tunnel and other proxies that drop `Set-Cookie` on 101 responses. Requires `svelte-adapter-uws` >= 0.4.12. |
 | `onConnect()` | Called when the WebSocket connection opens after a reconnect |
 | `onDisconnect()` | Called when the WebSocket connection closes |
 | `beforeReconnect()` | Called before each reconnection attempt (can be async) |
@@ -941,6 +986,53 @@ The native client passes the token in the URL:
 configure({ url: 'wss://my-sveltekit-app.com/ws?token=...' });
 ```
 
+### Refreshing session cookies on connect (Cloudflare Tunnel and friends)
+
+Cloudflare Tunnel and other strict edge proxies silently drop the `Set-Cookie` header on WebSocket `101 Switching Protocols` responses. The connection appears to open server-side, then the client immediately sees `close 1006` and never receives a single frame. The classic symptom for this in production: WebSockets work locally and on a bare server, then break the moment you put Cloudflare in front.
+
+Fix it in three pieces:
+
+1. Export an `authenticate` hook from `src/hooks.ws.{js,ts}`. It runs as a normal HTTP `POST /__ws/auth` before every upgrade (including reconnects), so cookies you set ride a `204 No Content` response that proxies route correctly.
+2. Opt into the client preflight with `configure({ auth: true })`.
+3. Use `svelte-adapter-uws` >= 0.4.12.
+
+```js
+// src/hooks.ws.js
+export { message, close, unsubscribe } from 'svelte-realtime/server';
+
+export function upgrade({ cookies }) {
+  const session = validateSession(cookies.session_id);
+  return session ? { id: session.userId, name: session.name } : false;
+}
+
+export function authenticate({ cookies }) {
+  const session = validateSession(cookies.get('session_id'));
+  if (!session) return false;
+
+  if (shouldRotate(session)) {
+    cookies.set('session_id', rotate(session), {
+      httpOnly: true,
+      secure: true,
+      sameSite: 'lax',
+      path: '/'
+    });
+  }
+  return { id: session.userId, name: session.name };
+}
+```
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+  import { configure } from 'svelte-realtime/client';
+  configure({ auth: true });
+</script>
+```
+
+The client coalesces concurrent connects into a single in-flight preflight, treats `4xx` as terminal, and falls back to normal reconnect backoff on `5xx` and network errors.
+
+> **Detector:** if the client sees two consecutive WebSocket open->close cycles inside one second with no traffic, it logs a one-shot `console.warn` pointing at this section. That is the Cloudflare-Tunnel-eating-cookies fingerprint.
+
 ---
 
 ## Combine stores
@@ -2013,6 +2105,8 @@ Import from `svelte-realtime/client`.
 
 | Method/Property | Description |
 |---|---|
+| `error` | `Readable<RpcError \| null>` -- current error, or `null` when healthy |
+| `status` | `Readable<'loading' \| 'connected' \| 'reconnecting' \| 'error'>` -- connection status |
 | `optimistic(event, data)` | Apply instant UI update, returns rollback function |
 | `hydrate(initialData)` | Pre-populate with SSR data |
 | `loadMore(...extraArgs)` | Load next page (cursor-based) |

package/client.d.ts

@@ -45,7 +45,9 @@ export function __rpc(path: string): ((...args: any[]) => Promise<any>) & {
  * - `undefined` while loading
  * - The initial data once loaded
  * - Automatically updated with live pub/sub events
- * - `{ error: RpcError }` if the initial fetch fails
+ *
+ * Errors never replace the store value. On failure, the last known data
+ * is preserved and the error is available via the `.error` store.
  *
  * @param path - Stream path (e.g. `'chat/messages'`)
  * @param options - Merge strategy and options
@@ -57,6 +59,10 @@ export function __rpc(path: string): ((...args: any[]) => Promise<any>) & {
  * SSR hydration, and cursor-based pagination.
  */
 export interface StreamStore<T = any> extends Readable<T> {
+	/** Reactive store holding the current error, or null when healthy. Errors never replace the data store value. */
+	readonly error: Readable<RpcError | null>;
+	/** Reactive store holding the connection status: 'loading', 'connected', 'reconnecting', or 'error'. */
+	readonly status: Readable<'loading' | 'connected' | 'reconnecting' | 'error'>;
 	/** Apply an instant UI update. Returns a rollback function. */
 	optimistic(event: string, data: any): () => void;
 	/** Pre-populate with SSR data to avoid loading spinners. */
@@ -175,6 +181,22 @@ export function configure(config: {
 	 * @example 'wss://my-app.com/ws'
 	 */
 	url?: string;
+	/**
+	 * Run an HTTP preflight before each WebSocket upgrade so cookies set by the
+	 * server's `authenticate` hook ride a normal HTTP response (not a 101 Switching
+	 * Protocols frame). Required behind Cloudflare Tunnel and other strict edge
+	 * proxies that silently drop `Set-Cookie` on WebSocket upgrades.
+	 *
+	 * Pass `true` to use the default `/__ws/auth` path, or a string to override it
+	 * (must match the adapter's `websocket.authPath` option).
+	 *
+	 * Requires `svelte-adapter-uws` >= 0.4.12 and an `authenticate` export in
+	 * `src/hooks.ws.{js,ts}`.
+	 *
+	 * @default false
+	 * @example configure({ auth: true })
+	 */
+	auth?: boolean | string;
 	/** Called when the WebSocket connection opens (not on initial connect, only reconnects). */
 	onConnect?(): void;
 	/** Called when the WebSocket connection closes. */

package/client.js

@@ -133,22 +133,50 @@ function ensureListener() {
 /**
  * Attach a disconnect listener once.
  * Rejects all in-flight RPCs (already sent) with DISCONNECTED.
+ * Also detects the Cloudflare-Tunnel "Set-Cookie on 101" symptom: repeated
+ * fast open->close cycles with no time spent in the open state.
  */
 function ensureDisconnectListener() {
 	if (disconnectListenerAttached) return;
 	disconnectListenerAttached = true;
 
+	let lastOpenAt = 0;
+	let fastCloseCount = 0;
+	let cfTunnelWarned = false;
+
 	status.subscribe((s) => {
 		if (s === 'closed') {
-			const code = s === 'closed' ? 'DISCONNECTED' : 'CONNECTION_CLOSED';
 			for (const [id, entry] of pending) {
 				pending.delete(id);
 				if (entry.timer) clearTimeout(entry.timer);
-				entry.reject(new RpcError(code, 'WebSocket connection lost'));
+				entry.reject(new RpcError('DISCONNECTED', 'WebSocket connection lost'));
+			}
+
+			if (lastOpenAt > 0) {
+				const openDuration = Date.now() - lastOpenAt;
+				lastOpenAt = 0;
+				if (openDuration < 1000) {
+					fastCloseCount++;
+					if (fastCloseCount >= 2 && !cfTunnelWarned && !_clientConfig.auth) {
+						cfTunnelWarned = true;
+						console.warn(
+							'[svelte-realtime] WebSocket opened then closed in ' + openDuration + 'ms ' +
+							'with no traffic, repeatedly. This is the classic Cloudflare-Tunnel ' +
+							'"Set-Cookie on 101" symptom: the proxy silently drops cookies on ' +
+							'WebSocket upgrade responses.\n' +
+							'  Fix: add `configure({ auth: true })` on the client and an ' +
+							'`authenticate` hook in `hooks.ws.js` (svelte-adapter-uws >= 0.4.12).\n' +
+							'  See: https://svti.me/cf-cookies'
+						);
+					}
+				} else {
+					fastCloseCount = 0;
+				}
 			}
 		}
 		if (s === 'open') {
 			_terminated = false;
+			lastOpenAt = Date.now();
 		}
 	});
 
@@ -508,6 +536,28 @@ function _createStream(path, options, dynamicArgs) {
 	let currentValue;
 	const store = writable(undefined);
 
+	/** @type {RpcError | null} */
+	let _error = null;
+	const _errorStore = writable(null);
+
+	/** @type {'loading' | 'connected' | 'reconnecting' | 'error'} */
+	let _status = 'loading';
+	const _statusStore = writable(/** @type {'loading' | 'connected' | 'reconnecting' | 'error'} */ ('loading'));
+
+	function _setError(/** @type {RpcError} */ err) {
+		_error = err;
+		_errorStore.set(err);
+		_status = 'error';
+		_statusStore.set('error');
+	}
+
+	function _clearError() {
+		if (_error !== null) {
+			_error = null;
+			_errorStore.set(null);
+		}
+	}
+
 	/** @type {string | null} */
 	let topic = null;
 
@@ -841,7 +891,7 @@ function _createStream(path, options, dynamicArgs) {
 	function fetchAndSubscribe() {
 		if (fetching) return;
 		if (_terminated) {
-			store.set({ error: new RpcError('CONNECTION_CLOSED', 'Connection permanently closed') });
+			_setError(new RpcError('CONNECTION_CLOSED', 'Connection permanently closed'));
 			return;
 		}
 		fetching = true;
@@ -871,13 +921,13 @@ function _createStream(path, options, dynamicArgs) {
 				pending.delete(id);
 				pendingId = null;
 				fetching = false;
-				store.set({ error: new RpcError('DISCONNECTED', 'Connection interrupted (device sleep)') });
+				_setError(new RpcError('DISCONNECTED', 'Connection interrupted (device sleep)'));
 				return;
 			}
 			pending.delete(id);
 			pendingId = null;
 			fetching = false;
-			store.set({ error: new RpcError('TIMEOUT', `Stream '${path}' timed out after 30s`) });
+			_setError(new RpcError('TIMEOUT', `Stream '${path}' timed out after 30s`));
 		}, _getTimeout());
 
 		pending.set(id, {
@@ -886,6 +936,9 @@ function _createStream(path, options, dynamicArgs) {
 				fetching = false;
 				pendingId = null;
 				_reconnectAttempts = 0;
+				_clearError();
+				_status = 'connected';
+				_statusStore.set('connected');
 				topic = response.topic || null;
 
 				// Track sequence number for replay
@@ -985,7 +1038,7 @@ function _createStream(path, options, dynamicArgs) {
 			reject(err) {
 				fetching = false;
 				pendingId = null;
-				store.set({ error: err instanceof RpcError ? err : new RpcError('STREAM_ERROR', err?.message || 'Stream failed') });
+				_setError(err instanceof RpcError ? err : new RpcError('STREAM_ERROR', err?.message || 'Stream failed'));
 			},
 			timer
 		});
@@ -1035,6 +1088,10 @@ function _createStream(path, options, dynamicArgs) {
 		buffer = [];
 		currentValue = undefined;
 		store.set(undefined);
+		_error = null;
+		_errorStore.set(null);
+		_status = 'loading';
+		_statusStore.set('loading');
 		_index.clear();
 		_history = [];
 		_historyIndex = -1;
@@ -1046,6 +1103,8 @@ function _createStream(path, options, dynamicArgs) {
 	let _pendingCleanup = false;
 
 	return {
+		error: { subscribe: _errorStore.subscribe },
+		status: { subscribe: _statusStore.subscribe },
 		subscribe(fn) {
 			if (subCount++ === 0) {
 				if (_pendingCleanup) {
@@ -1064,6 +1123,8 @@ function _createStream(path, options, dynamicArgs) {
 						return;
 					}
 					if (s === 'open' && subCount > 0) {
+						_status = 'reconnecting';
+						_statusStore.set('reconnecting');
 						if (_reconnectTimer) clearTimeout(_reconnectTimer);
 						let delay;
 						if (_reconnectAttempts < 2) {
@@ -1093,7 +1154,7 @@ function _createStream(path, options, dynamicArgs) {
 					if (conn && typeof conn.ready === 'function') {
 						conn.ready().catch((/** @type {any} */ err) => {
 							if (subCount > 0) {
-								store.set({ error: new RpcError(err?.code || 'CONNECTION_CLOSED', err?.message || 'Connection permanently closed') });
+								_setError(new RpcError(err?.code || 'CONNECTION_CLOSED', err?.message || 'Connection permanently closed'));
 							}
 						});
 					}
@@ -1526,7 +1587,7 @@ function _checkArgs(path, args) {
  * @typedef {{ path: string, args: any[], queuedAt: number, resolve: Function, reject: Function }} OfflineEntry
  */
 
-/** @type {{ url?: string, onConnect?: () => void, onDisconnect?: () => void, timeout?: number, offline?: { queue?: boolean, maxQueue?: number, maxAge?: number, replay?: 'sequential' | 'batch' | ((queue: OfflineEntry[]) => OfflineEntry[]), beforeReplay?: (call: { path: string, args: any[], queuedAt: number }) => boolean, onReplayError?: (call: { path: string, args: any[], queuedAt: number }, error: any) => void } }} */
+/** @type {{ url?: string, auth?: boolean | string, onConnect?: () => void, onDisconnect?: () => void, timeout?: number, offline?: { queue?: boolean, maxQueue?: number, maxAge?: number, replay?: 'sequential' | 'batch' | ((queue: OfflineEntry[]) => OfflineEntry[]), beforeReplay?: (call: { path: string, args: any[], queuedAt: number }) => boolean, onReplayError?: (call: { path: string, args: any[], queuedAt: number }, error: any) => void } }} */
 let _clientConfig = {};
 
 /** @type {boolean} */
@@ -1544,13 +1605,17 @@ let _replayingQueue = false;
 /**
  * Configure client-side connection hooks and offline queue.
  *
- * @param {{ url?: string, onConnect?: () => void, onDisconnect?: () => void, offline?: { queue?: boolean, maxQueue?: number, maxAge?: number, replay?: 'sequential' | 'batch' | ((queue: OfflineEntry[]) => OfflineEntry[]), beforeReplay?: (call: { path: string, args: any[], queuedAt: number }) => boolean, onReplayError?: (call: { path: string, args: any[], queuedAt: number }, error: any) => void } }} config
+ * @param {{ url?: string, auth?: boolean | string, onConnect?: () => void, onDisconnect?: () => void, offline?: { queue?: boolean, maxQueue?: number, maxAge?: number, replay?: 'sequential' | 'batch' | ((queue: OfflineEntry[]) => OfflineEntry[]), beforeReplay?: (call: { path: string, args: any[], queuedAt: number }) => boolean, onReplayError?: (call: { path: string, args: any[], queuedAt: number }, error: any) => void } }} config
  */
 export function configure(config) {
 	_clientConfig = config;
 
-	if (config.url) {
-		_connect({ url: config.url });
+	if (config.url !== undefined || config.auth !== undefined) {
+		/** @type {{ url?: string, auth?: boolean | string }} */
+		const connectArgs = {};
+		if (config.url !== undefined) connectArgs.url = config.url;
+		if (config.auth !== undefined) connectArgs.auth = config.auth;
+		_connect(connectArgs);
 	}
 
 	if (!_configListenerAttached) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-realtime",
-  "version": "0.4.20",
+  "version": "0.4.22",
   "description": "Realtime RPC and reactive subscriptions for SvelteKit, built on svelte-adapter-uws",
   "author": "Kevin Radziszewski",
   "license": "MIT",
@@ -69,7 +69,7 @@
   "peerDependencies": {
     "@sveltejs/kit": "^2.0.0",
     "svelte": "^4.0.0 || ^5.0.0",
-    "svelte-adapter-uws": ">=0.4.8"
+    "svelte-adapter-uws": ">=0.4.12"
   },
   "devDependencies": {
     "vitest": "^4.0.18"