svelte-realtime 0.4.21 → 0.4.23

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
@@ -1171,22 +1219,51 @@ export const message = createMessage({
 
 Opt-in instrumentation for RPC calls, stream subscriptions, and cron executions. Zero overhead if not called.
 
+`live.metrics(registry)` is a one-time setup call. The top of `src/hooks.ws.{js,ts}` is a natural place, since it loads once when the server boots. Pair it with the `createMetrics()` registry from `svelte-adapter-uws-extensions/prometheus`:
+
 ```js
+// src/hooks.ws.js
 import { live } from 'svelte-realtime/server';
-import { createMetricsRegistry } from 'svelte-adapter-uws-extensions/prometheus';
+import { createMetrics } from 'svelte-adapter-uws-extensions/prometheus';
+
+const metrics = createMetrics();
+
+live.metrics({
+  counter:   ({ name, help, labelNames }) => metrics.counter(name, help, labelNames),
+  histogram: ({ name, help, labelNames }) => metrics.histogram(name, help, labelNames),
+  gauge:     ({ name, help, labelNames }) => metrics.gauge(name, help, labelNames)
+});
 
-const registry = createMetricsRegistry();
-live.metrics(registry);
+export { message, close, unsubscribe } from 'svelte-realtime/server';
+```
+
+Mount the metrics endpoint on your uWS app (typically in `svelte.config.js` or wherever you build the app):
+
+```js
+app.get('/metrics', metrics.handler);
 ```
 
-This registers counters/histograms for:
+The six-line shim adapts realtime's options-object call shape to the extensions registry's positional create methods. Once a metric is registered, every increment, observation, and gauge update flows directly to the extensions registry, so the emitted Prometheus output is exactly what `metrics.serialize()` produces.
+
+### Registered metrics
+
 - `svelte_realtime_rpc_total` -- RPC call count by path and status
 - `svelte_realtime_rpc_duration_seconds` -- RPC latency by path
 - `svelte_realtime_rpc_errors_total` -- RPC errors by path and code
-- `svelte_realtime_stream_subscriptions` -- active stream subscription gauge by topic
+- `svelte_realtime_stream_subscriptions` -- active stream subscription gauge
 - `svelte_realtime_cron_total` -- cron execution count by path and status
 - `svelte_realtime_cron_errors_total` -- cron errors by path
 
+### Registry shape
+
+`live.metrics()` accepts any object exposing:
+
+- `counter({ name, help, labelNames }) -> { inc(labels?) }`
+- `histogram({ name, help, labelNames }) -> { observe(labels, valueSeconds) }`
+- `gauge({ name, help }) -> { inc(), dec() }`
+
+If you prefer `prom-client`, wire it the same way: `counter: ({ name, help, labelNames }) => new client.Counter({ name, help, labelNames, registers: [register] })`, and likewise for `Histogram` and `Gauge`.
+
 ---
 
 ## Circuit breaker

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.23",
   "description": "Realtime RPC and reactive subscriptions for SvelteKit, built on svelte-adapter-uws",
   "author": "Kevin Radziszewski",
   "license": "MIT",
@@ -69,9 +69,10 @@
   "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": {
+    "svelte-adapter-uws-extensions": "^0.4.2",
     "vitest": "^4.0.18"
   },
   "keywords": [

package/server.d.ts

@@ -182,6 +182,25 @@ export interface CreateMessageOptions {
 	onUnhandled?(ws: WebSocket<any>, data: ArrayBuffer, platform: Platform): void;
 }
 
+/**
+ * Shape accepted by `live.metrics()`. Any object matching this contract works
+ * (hand-rolled, prom-client adapter, or the `createMetrics()` registry from
+ * `svelte-adapter-uws-extensions/prometheus` wrapped to forward options as
+ * positional args -- see the README "Prometheus metrics" section).
+ */
+export interface MetricsRegistry {
+	counter(opts: { name: string; help: string; labelNames?: string[] }): {
+		inc(labels?: Record<string, string | number>): void;
+	};
+	histogram(opts: { name: string; help: string; labelNames?: string[]; buckets?: number[] }): {
+		observe(labels: Record<string, string | number>, valueSeconds: number): void;
+	};
+	gauge(opts: { name: string; help: string; labelNames?: string[] }): {
+		inc(): void;
+		dec(): void;
+	};
+}
+
 /**
  * Mark a function as RPC-callable over WebSocket.
  *
@@ -561,21 +580,29 @@ export namespace live {
 	function webhook(topic: string, config: WebhookConfig): WebhookHandler;
 
 	/**
-	 * Opt-in Prometheus metrics integration.
-	 * Accepts a MetricsRegistry from `svelte-adapter-uws-extensions/prometheus`
-	 * and instruments RPC calls, stream subscriptions, and cron executions.
+	 * Opt-in Prometheus metrics integration. Instruments RPC calls, stream
+	 * subscriptions, and cron executions. Zero overhead if never called.
 	 *
-	 * Zero overhead if never called.
+	 * Call once at server start (e.g. the top of `src/hooks.ws.{js,ts}`).
+	 * See the README "Prometheus metrics" section for a working example
+	 * that pairs this with `createMetrics()` from
+	 * `svelte-adapter-uws-extensions/prometheus`.
 	 *
-	 * @param registry - A MetricsRegistry instance with counter(), histogram(), gauge()
+	 * @param registry - Object matching the {@link MetricsRegistry} shape
 	 *
 	 * @example
 	 * ```js
-	 * import { createRegistry } from 'svelte-adapter-uws-extensions/prometheus';
-	 * live.metrics(createRegistry());
+	 * import { createMetrics } from 'svelte-adapter-uws-extensions/prometheus';
+	 *
+	 * const metrics = createMetrics();
+	 * live.metrics({
+	 *   counter:   ({ name, help, labelNames }) => metrics.counter(name, help, labelNames),
+	 *   histogram: ({ name, help, labelNames }) => metrics.histogram(name, help, labelNames),
+	 *   gauge:     ({ name, help, labelNames }) => metrics.gauge(name, help, labelNames)
+	 * });
 	 * ```
 	 */
-	function metrics(registry: any): void;
+	function metrics(registry: MetricsRegistry): void;
 
 	/**
 	 * Wrap a stream initFn call with a circuit breaker.

package/server.js

@@ -1338,13 +1338,20 @@ live.room = function room(config) {
 let _metricsInstruments = null;
 
 /**
- * Opt-in Prometheus metrics integration.
- * Accepts a MetricsRegistry from `svelte-adapter-uws-extensions/prometheus`
- * and instruments RPC calls, stream subscriptions, and cron executions.
+ * Opt-in Prometheus metrics integration. Instruments RPC calls, stream
+ * subscriptions, and cron executions. Zero overhead if never called.
  *
- * Zero overhead if never called.
+ * Call once at server start (e.g. the top of `src/hooks.ws.{js,ts}`).
  *
- * @param {any} registry - A MetricsRegistry instance with counter(), histogram(), gauge()
+ * The registry is any object exposing:
+ *   counter({ name, help, labelNames }) -> { inc(labels?) }
+ *   histogram({ name, help, labelNames }) -> { observe(labels, valueSeconds) }
+ *   gauge({ name, help }) -> { inc(), dec() }
+ *
+ * See the README "Prometheus metrics" section for a working example that
+ * pairs this with `createMetrics()` from `svelte-adapter-uws-extensions/prometheus`.
+ *
+ * @param {any} registry - Object with counter, histogram, and gauge factories
  */
 live.metrics = function metrics(registry) {
 	_metricsInstruments = {