svelte-realtime 0.4.21 → 0.4.22

package/README.md

@@ -934,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) |
@@ -985,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

package/client.d.ts

@@ -181,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();
 		}
 	});
 
@@ -1559,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} */
@@ -1577,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.21",
+  "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"