svelte-adapter-uws 0.4.13 → 0.5.0-next.1

package/README.md

@@ -887,6 +887,13 @@ sub.on('message', (channel, payload) => {
 });
 ```
 
+Every published frame is also stamped with a monotonic per-topic `seq` field in the envelope (first publish to a topic is `seq: 1`, then 2, 3, ...). Reconnecting clients can use this to detect dropped frames and resume from where they left off. Pass `{ seq: false }` to skip stamping for ephemeral or high-cardinality topics where the counter map would grow unbounded:
+
+```js
+// Skip seq for per-user cursor topics: counter map would grow with users
+platform.publish(`cursor:${userId}`, 'move', pos, { seq: false });
+```
+
 ```js
 // src/routes/todos/+page.server.js
 export const actions = {
@@ -953,6 +960,40 @@ export function message(ws, { data, platform }) {
 }
 ```
 
+### `platform.sendCoalesced(ws, { key, topic, event, data })`
+
+Send a message to a single connection with **coalesce-by-key** semantics. Each `(connection, key)` pair holds at most one pending message; if a newer call for the same `key` arrives before the previous frame drains to the wire, the older value is replaced in place.
+
+Use this for latest-value streams where intermediate values are noise -- price ticks, cursor positions, presence state, typing indicators, scroll position. Under load, this is the difference between the client lagging by a thousand stale frames and the client always seeing the most recent value.
+
+For at-least-once delivery use `platform.send()` or `platform.publish()` instead. `sendCoalesced` is explicitly drop-the-middle, keep-the-latest.
+
+```js
+// src/hooks.ws.js - cursor positions during a collaborative edit
+export function message(ws, { data, platform }) {
+  const msg = JSON.parse(Buffer.from(data).toString());
+  if (msg.event === 'cursor') {
+    const { docId, userId } = ws.getUserData();
+    // Coalesce per (connection, user) - one pending cursor frame per peer.
+    // High-frequency mousemove updates collapse cleanly under backpressure.
+    for (const peer of getPeersOf(docId)) {
+      platform.sendCoalesced(peer, {
+        key: 'cursor:' + userId,
+        topic: 'doc:' + docId,
+        event: 'cursor',
+        data: { userId, x: msg.data.x, y: msg.data.y }
+      });
+    }
+  }
+}
+```
+
+Three properties worth knowing:
+
+- **Latest value wins.** `set` on an existing key replaces the value but keeps the original slot, so coalescing one key never reorders the rest of the queue.
+- **Lazy serialization.** `data` is held as-is in the per-connection buffer and only `JSON.stringify`'d at flush time. A stream that overwrites the same key 1000 times before a single drain pays one serialization, not 1000.
+- **Auto-resume on drain.** When `maxBackpressure` is hit, pumping stops and resumes on the next uWS drain event automatically. No manual flow control.
+
 ### `platform.sendTo(filter, topic, event, data)`
 
 Send a message to all connections whose `userData` matches a filter function. Returns the number of connections the message was sent to.
@@ -1006,6 +1047,77 @@ export async function GET({ platform, params }) {
 }
 ```
 
+### `platform.pressure` and `platform.onPressure(cb)`
+
+Worker-local backpressure signal. The adapter samples once per second (configurable) and reports the most urgent active stress as a single `reason` enum, so user code can degrade with intent instead of generic panic.
+
+```js
+platform.pressure
+// {
+//   active: false,
+//   subscriberRatio: 12.4,    // total subscriptions / connections, on this worker
+//   publishRate: 240,         // platform.publish() calls/sec, last sample
+//   memoryMB: 128,            // process.memoryUsage().rss in MB
+//   reason: 'NONE'            // 'NONE' | 'PUBLISH_RATE' | 'SUBSCRIBERS' | 'MEMORY'
+// }
+```
+
+Reading `platform.pressure` is a property access -- safe in hot paths, no I/O. Use it for synchronous shed decisions in request handlers:
+
+```js
+// src/routes/api/heavy-write/+server.js
+export async function POST({ platform, request }) {
+  if (platform.pressure.reason === 'MEMORY') {
+    return new Response('Try again shortly', { status: 503 });
+  }
+  // ... normal write path
+}
+```
+
+`platform.onPressure(cb)` fires only on **transitions** (when `reason` changes between samples), not on every tick. Returns an unsubscribe function:
+
+```js
+// src/hooks.ws.js - notify the connected client when pressure state changes
+export function open(ws, { platform }) {
+  const off = platform.onPressure(({ reason, active }) => {
+    platform.send(ws, '__pressure', reason, { active });
+  });
+  ws.getUserData().__offPressure = off;
+}
+
+export function close(ws) {
+  ws.getUserData().__offPressure?.();
+}
+```
+
+**Reason precedence is fixed:** `MEMORY > PUBLISH_RATE > SUBSCRIBERS`. A worker under multiple stresses reports the most urgent one. Memory wins because the worker is approaching OOM and nothing else matters; publish rate is next because CPU saturation cascades fastest; subscriber ratio is last because heavy fan-out degrades gracefully.
+
+**Thresholds are configurable per-deployment.** Defaults are conservative -- a healthy small app should never trip them in steady state. Override via `WebSocketOptions.pressure`:
+
+```js
+// svelte.config.js
+import adapter from 'svelte-adapter-uws';
+
+export default {
+  kit: {
+    adapter: adapter({
+      websocket: {
+        pressure: {
+          memoryHeapUsedRatio: 0.9,    // default 0.85
+          publishRatePerSec: 50000,    // default 10000
+          subscriberRatio: false,      // disable this signal
+          sampleIntervalMs: 500        // default 1000; clamped to >=100
+        }
+      }
+    })
+  }
+};
+```
+
+Set any individual threshold to `false` to disable that signal. `sampleIntervalMs` is clamped to a minimum of 100 ms.
+
+> **Clustering:** `platform.pressure` is per-worker. Each worker samples its own counters and reports its own snapshot. There is no aggregate "cluster pressure" -- a hot worker should shed its own load without waiting for the rest of the cluster.
+
 ### `platform.topic(name)` - scoped helper
 
 Reduces repetition when publishing multiple events to the same topic:
@@ -2900,13 +3012,26 @@ Every message sent through `platform.publish()` or `platform.topic().created()`
 {
   "topic": "todos",
   "event": "created",
-  "data": { "id": 1, "text": "Buy milk", "done": false }
+  "data": { "id": 1, "text": "Buy milk", "done": false },
+  "seq": 42
 }
 ```
 
+The `seq` field is a monotonic per-topic sequence number stamped automatically on every `platform.publish()`. The first publish to a topic sends `seq: 1`, the next `seq: 2`, and so on; each topic has its own counter. Reconnecting clients can use the seq to detect dropped frames and resume from where they left off. Pass `{ seq: false }` to skip stamping when you don't care about gap detection or when topic cardinality is unbounded:
+
+```js
+// Standard publish - seq stamped automatically
+platform.publish('chat', 'message', msg);
+
+// Opt out for ephemeral or high-cardinality topics
+platform.publish(`cursor:${userId}`, 'move', pos, { seq: false });
+```
+
+> **Clustering:** the per-topic counter is worker-local. Each worker stamps its own publishes; relayed messages from other workers pass through with the originating worker's seq. For cluster-wide monotonic seq across all workers, wire up the Redis Lua INCR variant from the extensions package.
+
 The client store parses this automatically. When you use `on('todos')`, the store value is:
 ```js
-{ topic: 'todos', event: 'created', data: { id: 1, text: 'Buy milk', done: false } }
+{ topic: 'todos', event: 'created', data: { id: 1, text: 'Buy milk', done: false }, seq: 42 }
 ```
 
 When you use `on('todos', 'created')`, you get the payload wrapped in `{ data }`:

package/client.d.ts

@@ -17,14 +17,20 @@ export interface ConnectOptions {
 
 	/**
 	 * Base delay in ms before reconnecting after a disconnect.
-	 * Uses exponential backoff with jitter.
+	 * The actual delay grows as `base * 2.2^attempt` with a +/- 25%
+	 * jitter, capped at `maxReconnectInterval`.
 	 * @default 3000
 	 */
 	reconnectInterval?: number;
 
 	/**
-	 * Maximum delay in ms between reconnection attempts.
-	 * @default 30000
+	 * Maximum delay in ms between reconnection attempts. Once the
+	 * exponential curve hits this cap it stays there until the
+	 * connection succeeds. The default 5 minute cap is long enough
+	 * that 10K clients hammering a recovering server don't sustain the
+	 * outage, short enough that a recovered server picks up its
+	 * clients within a coffee break.
+	 * @default 300000
 	 */
 	maxReconnectInterval?: number;
 
@@ -92,6 +98,16 @@ export interface WSEvent<T = unknown> {
 	event: string;
 	/** The event payload. */
 	data: T;
+	/**
+	 * Monotonic per-topic sequence number stamped by the server on every
+	 * `platform.publish()` (omitted when the publisher opts out via
+	 * `{ seq: false }`). Each topic has an independent counter starting
+	 * at 1.
+	 *
+	 * Worker-local in clustered mode unless an extension provides a
+	 * cluster-wide source of truth (e.g. Redis Lua INCR).
+	 */
+	seq?: number;
 }
 
 // -- Scannable store ----------------------------------------------------------
@@ -335,7 +351,7 @@ export function once<T = unknown>(topic: string, event: string, options?: { time
  * the new topic and the old one is released.
  *
  * Useful when the topic depends on runtime state like a user ID, selected item,
- * or route parameter — no manual subscribe/unsubscribe lifecycle to manage.
+ * or route parameter - no manual subscribe/unsubscribe lifecycle to manage.
  *
  * @example
  * ```svelte

package/client.js

@@ -498,6 +498,62 @@ const THROTTLE_CLOSE_CODES = new Set([
 	4429, // Rate limited (custom)
 ]);
 
+/**
+ * Classify a WebSocket close code into one of three reconnect behaviors.
+ *
+ * - `'TERMINAL'`: the server has permanently rejected this client.
+ *   Reconnecting would be pointless. The client store transitions to a
+ *   permanently-closed state and stops trying. Codes: 1008 (policy
+ *   violation), 4401 (unauthorized), 4403 (forbidden).
+ * - `'THROTTLE'`: the server is rate-limiting. Reconnect is still
+ *   attempted but the client jumps ahead in the backoff curve to avoid
+ *   hammering a busy server. Code: 4429 (too many requests).
+ * - `'RETRY'`: every other code, including normal closes (1000/1001) and
+ *   abnormal ones (1006/1011/1012). The client reconnects with the
+ *   standard backoff curve.
+ *
+ * Pure: no I/O, no globals. Suitable for unit tests.
+ *
+ * @param {number | undefined} code
+ * @returns {'TERMINAL' | 'THROTTLE' | 'RETRY'}
+ */
+export function classifyCloseCode(code) {
+	if (TERMINAL_CLOSE_CODES.has(code)) return 'TERMINAL';
+	if (THROTTLE_CLOSE_CODES.has(code)) return 'THROTTLE';
+	return 'RETRY';
+}
+
+/**
+ * Compute the next reconnect delay using exponential backoff with
+ * proportional jitter.
+ *
+ * The capped delay is `min(base * 2.2^attempt, maxDelay)`. A random factor
+ * in `[0.75, 1.25]` is then applied multiplicatively, so the final delay
+ * spans +/- 25% of the capped value. Multiplicative jitter keeps spread
+ * meaningful at high attempt counts: with 10K clients all reconnecting
+ * after a server restart, additive +/- 500ms jitter clusters reconnects
+ * inside a 1 second window; proportional jitter spreads them across
+ * a window proportional to the current backoff.
+ *
+ * The 2.2 exponent with a 5 minute cap is aggressive enough to back off
+ * fast under sustained server pain (the default 3 second base hits the
+ * cap by attempt 6) and gentle enough that a brief restart resolves
+ * before the user notices.
+ *
+ * Pure: no I/O, no globals. Pass a deterministic `randFactor` for
+ * reproducible assertions in tests.
+ *
+ * @param {number} base       base interval in ms (e.g. 3000)
+ * @param {number} maxDelay   cap in ms (e.g. 300000)
+ * @param {number} attempt    zero-based attempt counter
+ * @param {number} [randFactor]  random factor in [0, 1); defaults to Math.random()
+ * @returns {number}
+ */
+export function nextReconnectDelay(base, maxDelay, attempt, randFactor = Math.random()) {
+	const capped = Math.min(base * Math.pow(2.2, attempt), maxDelay);
+	return capped * (0.75 + randFactor * 0.5);
+}
+
 /**
  * @param {import('./client.js').ConnectOptions} options
  * @returns {import('./client.js').WSConnection & { _onEvent: (topic: string, event: string) => import('svelte/store').Readable<unknown> }}
@@ -507,7 +563,7 @@ function createConnection(options) {
 		url,
 		path = '/ws',
 		reconnectInterval = 3000,
-		maxReconnectInterval = 30000,
+		maxReconnectInterval = 300000,
 		maxReconnectAttempts = Infinity,
 		debug = false,
 		auth = false
@@ -757,19 +813,19 @@ function createConnection(options) {
 			if (debug) console.log('[ws] disconnected');
 			if (intentionallyClosed) return;
 
-			if (TERMINAL_CLOSE_CODES.has(event?.code)) {
+			const cls = classifyCloseCode(event?.code);
+			if (cls === 'TERMINAL') {
 				// Server has permanently rejected this client  - do not retry.
 				// Use ws.close(4401) or ws.close(1008) on the server when credentials
 				// are invalid or the connection is forbidden, to stop the retry loop.
-				if (debug) console.warn('[ws] connection permanently closed by server (code ' + event.code + ')');
+				if (debug) console.warn('[ws] connection permanently closed by server (code ' + event?.code + ')');
 				terminalClosed = true;
 				permaClosedStore.set(true);
 				return;
 			}
 
-			if (THROTTLE_CLOSE_CODES.has(event?.code)) {
-				// Server is rate-limiting us  - jump ahead in the backoff curve
-				// to avoid hammering it with immediate reconnect attempts.
+			if (cls === 'THROTTLE') {
+				// Jump ahead in the backoff curve to avoid hammering a rate-limited server.
 				attempt = Math.max(attempt, 5);
 			}
 
@@ -789,13 +845,7 @@ function createConnection(options) {
 			permaClosedStore.set(true);
 			return;
 		}
-		// Proportional jitter (±25% of the base delay) prevents thundering herd
-		// on server restarts. With 10K clients and additive ±500ms jitter all
-		// reconnections cluster in a 1s window; proportional jitter spreads them
-		// over ~15s at higher attempt counts where the base delay is large.
-		const base = Math.min(reconnectInterval * Math.pow(1.5, attempt), maxReconnectInterval);
-		const jitter = base * 0.25 * (Math.random() * 2 - 1);
-		const delay = Math.max(0, base + jitter);
+		const delay = nextReconnectDelay(reconnectInterval, maxReconnectInterval, attempt);
 		attempt++;
 		reconnectTimer = setTimeout(() => {
 			reconnectTimer = null;

package/files/handler.js

@@ -12,7 +12,7 @@ import { manifest, prerendered, base } from 'MANIFEST';
 import { env } from 'ENV';
 import * as wsModule from 'WS_HANDLER';
 import { parseCookies, createCookies } from './cookies.js';
-import { mimeLookup, parse_as_bytes, parse_origin, writeChunkWithBackpressure } from './utils.js';
+import { mimeLookup, parse_as_bytes, parse_origin, writeChunkWithBackpressure, drainCoalesced, computePressureReason, nextTopicSeq, completeEnvelope } from './utils.js';
 
 /* global ENV_PREFIX */
 /* global PRECOMPRESS */
@@ -408,6 +408,160 @@ const wsConnections = new Set();
 // Read once at module load so it is never sampled inside a hot callback.
 const wsDebug = WS_ENABLED && env('WS_DEBUG', '') === '1';
 
+// -- Per-topic broadcast sequence numbers ------------------------------------
+// Each platform.publish() stamps a monotonic per-topic seq into the envelope
+// so reconnecting clients can detect gaps and resume from where they left
+// off. Worker-local in clustered mode: cross-worker authority requires the
+// extensions package's Lua INCR variant. See README "Sequence numbers" for
+// the cluster caveat. The map persists for process lifetime; one entry per
+// topic ever published. High-cardinality producers can opt out per-call
+// via { seq: false }.
+/** @type {Map<string, number>} */
+const topicSeqs = new Map();
+
+// -- Pressure tracking -------------------------------------------------------
+// Coarse 1 Hz sampler exposed as `platform.pressure` (snapshot) and
+// `platform.onPressure(cb)` (transition callback). State lives at module
+// scope so platform.publish() and the subscribe/unsubscribe handlers can
+// bump counters with one integer add - no allocations on the hot path.
+
+let publishCountWindow = 0;
+let totalSubscriptions = 0;
+
+/**
+ * @typedef {{
+ *   active: boolean,
+ *   subscriberRatio: number,
+ *   publishRate: number,
+ *   memoryMB: number,
+ *   reason: 'NONE' | 'PUBLISH_RATE' | 'SUBSCRIBERS' | 'MEMORY'
+ * }} PressureSnapshot
+ */
+
+/** @type {PressureSnapshot} */
+const pressureSnapshot = {
+	active: false,
+	subscriberRatio: 0,
+	publishRate: 0,
+	memoryMB: 0,
+	reason: 'NONE'
+};
+
+/** @type {Set<(snapshot: PressureSnapshot) => void>} */
+const pressureListeners = new Set();
+
+/** @type {ReturnType<typeof setInterval> | null} */
+let pressureTimer = null;
+
+/**
+ * Default pressure thresholds. Designed to be safe rather than tight: the
+ * goal is "no false positives in the steady state of a healthy small app,"
+ * not "perfectly tuned for sustained five-figure publish rates." Override
+ * per-deployment via the `pressure` field on the WebSocket options.
+ */
+const DEFAULT_PRESSURE_THRESHOLDS = {
+	memoryHeapUsedRatio: 0.85,
+	publishRatePerSec: 10000,
+	subscriberRatio: 50,
+	sampleIntervalMs: 1000
+};
+
+/**
+ * Sample once: read counters, fold them into the snapshot, fire listeners
+ * iff `reason` changed. Called by the 1 Hz timer; also extracted so a test
+ * harness can drive samples directly without spinning real timers.
+ *
+ * @param {{ memoryHeapUsedRatio: number | false, publishRatePerSec: number | false, subscriberRatio: number | false, sampleIntervalMs: number }} thresholds
+ */
+function samplePressure(thresholds) {
+	const interval = thresholds.sampleIntervalMs / 1000;
+	const publishRate = interval > 0 ? publishCountWindow / interval : 0;
+	publishCountWindow = 0;
+
+	const connections = wsConnections.size;
+	const subscriberRatio = connections > 0 ? totalSubscriptions / connections : 0;
+
+	const mem = process.memoryUsage();
+	const heapUsedRatio = mem.heapTotal > 0 ? mem.heapUsed / mem.heapTotal : 0;
+	const memoryMB = mem.rss / (1024 * 1024);
+
+	const reason = computePressureReason(
+		{ heapUsedRatio, publishRate, subscriberRatio },
+		thresholds
+	);
+
+	const transitioned = reason !== pressureSnapshot.reason;
+	pressureSnapshot.subscriberRatio = subscriberRatio;
+	pressureSnapshot.publishRate = publishRate;
+	pressureSnapshot.memoryMB = memoryMB;
+	pressureSnapshot.reason = reason;
+	pressureSnapshot.active = reason !== 'NONE';
+
+	if (transitioned) {
+		for (const cb of pressureListeners) {
+			try {
+				cb(pressureSnapshot);
+			} catch (err) {
+				console.error('[pressure] listener threw:', err);
+			}
+		}
+	}
+}
+
+/**
+ * Merge user-supplied pressure options on top of the safe defaults. Each
+ * threshold accepts `false` to disable that signal. `sampleIntervalMs` is
+ * clamped to a sane minimum to avoid pathological tight-loop sampling if
+ * a user passes 0 or a negative number.
+ *
+ * @param {{ memoryHeapUsedRatio?: number | false, publishRatePerSec?: number | false, subscriberRatio?: number | false, sampleIntervalMs?: number } | undefined} opts
+ */
+function resolvePressureThresholds(opts) {
+	const merged = { ...DEFAULT_PRESSURE_THRESHOLDS, ...(opts || {}) };
+	if (typeof merged.sampleIntervalMs !== 'number' || merged.sampleIntervalMs < 100) {
+		merged.sampleIntervalMs = DEFAULT_PRESSURE_THRESHOLDS.sampleIntervalMs;
+	}
+	return merged;
+}
+
+/**
+ * Start the 1 Hz pressure sampler. Idempotent: a second call replaces the
+ * existing timer with a new one using the supplied thresholds.
+ *
+ * @param {Parameters<typeof resolvePressureThresholds>[0]} opts
+ */
+function startPressureSampling(opts) {
+	const thresholds = resolvePressureThresholds(opts);
+	if (pressureTimer) clearInterval(pressureTimer);
+	pressureTimer = setInterval(() => samplePressure(thresholds), thresholds.sampleIntervalMs);
+	if (typeof pressureTimer.unref === 'function') pressureTimer.unref();
+}
+
+function stopPressureSampling() {
+	if (pressureTimer) {
+		clearInterval(pressureTimer);
+		pressureTimer = null;
+	}
+}
+
+/**
+ * Drain any pending coalesce-by-key messages on a single connection.
+ * Serializes lazily: only the surviving (latest) value per key pays
+ * JSON.stringify cost.
+ *
+ * @param {import('uWebSockets.js').WebSocket<any>} ws
+ */
+function flushCoalescedFor(ws) {
+	const userData = ws.getUserData();
+	const pending = userData.__coalesced;
+	if (!pending || pending.size === 0) return;
+	drainCoalesced(pending, (msg) => ws.send(
+		envelopePrefix(msg.topic, msg.event) + JSON.stringify(msg.data ?? null) + '}',
+		false,
+		false
+	));
+}
+
 /** @type {import('./index.js').Platform} */
 const platform = {
 	/**
@@ -416,7 +570,11 @@ const platform = {
 	 * No-op if no clients are subscribed - safe to call unconditionally.
 	 */
 	publish(topic, event, data, options) {
-		const envelope = envelopePrefix(topic, event) + JSON.stringify(data ?? null) + '}';
+		publishCountWindow++;
+		const seq = (options && options.seq === false)
+			? null
+			: nextTopicSeq(topicSeqs, topic);
+		const envelope = completeEnvelope(envelopePrefix(topic, event), data, seq);
 		const result = app.publish(topic, envelope, false, false);
 		// Relay to other workers via main thread (no-op in single-process mode).
 		// Pass { relay: false } when the message originates from an external
@@ -444,6 +602,38 @@ const platform = {
 		return ws.send(envelopePrefix(topic, event) + JSON.stringify(data ?? null) + '}', false, false);
 	},
 
+	/**
+	 * Send a message to a single connection with coalesce-by-key semantics.
+	 *
+	 * Each (ws, key) pair holds at most one pending message. If a newer
+	 * sendCoalesced for the same key arrives before the previous one drains
+	 * out to the wire, the older message is dropped in place: latest value
+	 * wins, original insertion order is preserved.
+	 *
+	 * Use for latest-value streams where intermediate values are noise:
+	 * price ticks, cursor positions, presence state, typing indicators,
+	 * scroll/scrub positions. For at-least-once delivery use send() or
+	 * publish() instead.
+	 *
+	 * Serialization is deferred to the actual flush, so a stream that
+	 * overwrites the same key 1000 times before a single drain pays only
+	 * one JSON.stringify, not 1000.
+	 *
+	 * The flush attempts immediately and again on every uWS drain event.
+	 * On BACKPRESSURE or DROPPED from ws.send, pumping stops and resumes
+	 * on the next drain.
+	 */
+	sendCoalesced(ws, { key, topic, event, data }) {
+		const userData = ws.getUserData();
+		let pending = userData.__coalesced;
+		if (!pending) {
+			pending = new Map();
+			userData.__coalesced = pending;
+		}
+		pending.set(key, { topic, event, data });
+		flushCoalescedFor(ws);
+	},
+
 	/**
 	 * Send a message to connections matching a filter.
 	 * The filter receives each connection's userData (from the upgrade handler).
@@ -493,6 +683,35 @@ const platform = {
 		return results;
 	},
 
+	/**
+	 * Live snapshot of worker-local backpressure signals.
+	 *
+	 * `reason` is one of `'NONE'`, `'PUBLISH_RATE'`, `'SUBSCRIBERS'`,
+	 * `'MEMORY'`. Precedence is fixed (MEMORY > PUBLISH_RATE > SUBSCRIBERS),
+	 * so a worker under multiple stresses reports the most urgent one.
+	 *
+	 * Sampled by a coarse 1 Hz timer. Reading the snapshot is a property
+	 * access; no I/O or computation per read. Use `onPressure` for
+	 * push-style reaction on transitions.
+	 */
+	get pressure() {
+		return pressureSnapshot;
+	},
+
+	/**
+	 * Register a callback fired on each pressure-state transition (when
+	 * `reason` changes between samples). Fired at most once per sample
+	 * tick. Returns an unsubscribe function.
+	 *
+	 * Callbacks are invoked synchronously inside the sampler. A throwing
+	 * listener does not break the sampler or other listeners; the error
+	 * is logged and the next listener still runs.
+	 */
+	onPressure(cb) {
+		pressureListeners.add(cb);
+		return () => pressureListeners.delete(cb);
+	},
+
 	/**
 	 * Get a scoped helper for a topic - less repetition when publishing
 	 * multiple events to the same topic.
@@ -1653,7 +1872,9 @@ if (WS_ENABLED) {
 			// no cookie parsing). Inject remoteAddress so plugins/ratelimit can
 			// key on the real client IP via ws.getUserData().remoteAddress.
 			if (!wsModule.upgrade) {
-				res.upgrade({ remoteAddress: clientIp }, secKey, secProtocol, secExtensions, context);
+				res.cork(() => {
+					res.upgrade({ remoteAddress: clientIp }, secKey, secProtocol, secExtensions, context);
+				});
 				return;
 			}
 
@@ -1723,23 +1944,25 @@ if (WS_ENABLED) {
 					}
 					const ud = userData || {};
 					if (!ud.remoteAddress) ud.remoteAddress = clientIp;
-					if (responseHeaders) {
-						maybeWarnSetCookieOnUpgrade(responseHeaders);
-						for (const [hk, hv] of Object.entries(responseHeaders)) {
-							if (Array.isArray(hv)) {
-								for (const v of hv) res.writeHeader(hk, v);
-							} else {
-								res.writeHeader(hk, hv);
+					if (responseHeaders) maybeWarnSetCookieOnUpgrade(responseHeaders);
+					res.cork(() => {
+						if (responseHeaders) {
+							for (const [hk, hv] of Object.entries(responseHeaders)) {
+								if (Array.isArray(hv)) {
+									for (const v of hv) res.writeHeader(hk, v);
+								} else {
+									res.writeHeader(hk, hv);
+								}
 							}
 						}
-					}
-					res.upgrade(
-						ud,
-						secKey,
-						secProtocol,
-						secExtensions,
-						context
-					);
+						res.upgrade(
+							ud,
+							secKey,
+							secProtocol,
+							secExtensions,
+							context
+						);
+					});
 				})
 				.catch((err) => {
 					clearTimeout(timer);
@@ -1787,14 +2010,19 @@ if (WS_ENABLED) {
 						if (wsModule.subscribe && wsModule.subscribe(ws, msg.topic, { platform }) === false) {
 							return;
 						}
+						const subs = ws.getUserData().__subscriptions;
+						const isNew = !subs.has(msg.topic);
 						ws.subscribe(msg.topic);
-						ws.getUserData().__subscriptions.add(msg.topic);
+						subs.add(msg.topic);
+						if (isNew) totalSubscriptions++;
 						if (wsDebug) console.log('[ws] subscribe topic=%s', msg.topic);
 						return;
 					}
 					if (msg.type === 'unsubscribe' && typeof msg.topic === 'string') {
 						ws.unsubscribe(msg.topic);
-						ws.getUserData().__subscriptions.delete(msg.topic);
+						if (ws.getUserData().__subscriptions.delete(msg.topic)) {
+							totalSubscriptions--;
+						}
 						if (wsDebug) console.log('[ws] unsubscribe topic=%s', msg.topic);
 						wsModule.unsubscribe?.(ws, msg.topic, { platform });
 						return;
@@ -1814,8 +2042,10 @@ if (WS_ENABLED) {
 							}
 							if (!valid) continue;
 							if (wsModule.subscribe && wsModule.subscribe(ws, topic, { platform }) === false) continue;
+							const isNew = !userData.__subscriptions.has(topic);
 							ws.subscribe(topic);
 							userData.__subscriptions.add(topic);
+							if (isNew) totalSubscriptions++;
 							subscribed++;
 						}
 						if (wsDebug) console.log('[ws] subscribe-batch count=%d', subscribed);
@@ -1829,13 +2059,19 @@ if (WS_ENABLED) {
 			wsModule.message?.(ws, { data: message, isBinary, platform });
 		},
 
-		drain: wsModule.drain ? (ws) => wsModule.drain(ws, { platform }) : undefined,
+		drain: (ws) => {
+			// Resume any sendCoalesced traffic held back by backpressure
+			// before delegating to the user's drain hook.
+			flushCoalescedFor(ws);
+			wsModule.drain?.(ws, { platform });
+		},
 
 		close: (ws, code, message) => {
 			const subscriptions = ws.getUserData().__subscriptions || new Set();
 			try {
 				wsModule.close?.(ws, { code, message, platform, subscriptions });
 			} finally {
+				totalSubscriptions -= subscriptions.size;
 				wsConnections.delete(ws);
 				if (wsDebug) console.log('[ws] close code=%d connections=%d', code, wsConnections.size);
 			}
@@ -1856,6 +2092,8 @@ if (WS_ENABLED) {
 	if (WS_PATH !== '/ws') {
 		console.log(`Client must match: connect({ path: '${WS_PATH}' })`);
 	}
+
+	startPressureSampling(wsOptions.pressure);
 }
 
 // Health check endpoint (before catch-all so it never hits SSR)
@@ -1927,6 +2165,7 @@ export function shutdown() {
 		uWS.us_listen_socket_close(listenSocket);
 		listenSocket = null;
 	}
+	stopPressureSampling();
 	for (const ws of wsConnections) {
 		ws.close(1001, 'Server shutting down');
 	}

package/files/utils.js

@@ -145,6 +145,118 @@ export function writeChunkWithBackpressure(res, value, timeoutMs = 30000) {
 	return ok ? true : /** @type {Promise<boolean>} */ (drainPromise);
 }
 
+/**
+ * Drain a coalesce-by-key buffer.
+ *
+ * Iterates entries in insertion order and calls `send` for each. Entries
+ * whose send result is SUCCESS (0) are removed from the map. The function
+ * stops on the first BACKPRESSURE (1) or DROPPED (2) result, leaving the
+ * remaining entries (and the one that just hit pressure, in the DROPPED
+ * case) for a later flush.
+ *
+ * Pure: no I/O of its own, no timers, no globals. The caller supplies
+ * `send`, which is the only side-effecting boundary, so this is unit-
+ * testable with a mock send fn.
+ *
+ * Map insertion order is preserved across overwrites: setting an existing
+ * key replaces the value but keeps the original slot. Latest value wins,
+ * order is stable.
+ *
+ * @template T
+ * @param {Map<string, T>} pending
+ * @param {(value: T) => number} send  0 SUCCESS, 1 BACKPRESSURE, 2 DROPPED
+ */
+export function drainCoalesced(pending, send) {
+	for (const [key, value] of pending) {
+		const result = send(value);
+		if (result === 2) return;
+		pending.delete(key);
+		if (result === 1) return;
+	}
+}
+
+/**
+ * Allocate the next monotonic sequence number for a topic, mutating
+ * `seqMap` in place. The first call for a topic returns 1; subsequent
+ * calls return the previous value plus one. Each topic has an
+ * independent counter.
+ *
+ * Pure with respect to inputs other than the supplied map. Suitable
+ * for unit tests that pass a fresh map per case.
+ *
+ * @param {Map<string, number>} seqMap
+ * @param {string} topic
+ * @returns {number}
+ */
+export function nextTopicSeq(seqMap, topic) {
+	const next = (seqMap.get(topic) ?? 0) + 1;
+	seqMap.set(topic, next);
+	return next;
+}
+
+/**
+ * Complete a JSON envelope started by an `envelopePrefix` builder.
+ *
+ * Appends the JSON-encoded data and an optional `seq` field, plus the
+ * closing brace. When `seq` is `null` or `undefined` the field is
+ * omitted entirely so the wire shape matches the legacy
+ * `{topic,event,data}` envelope verbatim. When `seq` is a number the
+ * resulting envelope is `{topic,event,data,seq}`.
+ *
+ * No JSON.stringify on the seq itself: numbers serialize identically
+ * via plain string concatenation, saving a stringify call on the
+ * publish hot path.
+ *
+ * @param {string} prefix  output of envelopePrefix(topic, event)
+ * @param {unknown} data
+ * @param {number | null | undefined} seq
+ * @returns {string}
+ */
+export function completeEnvelope(prefix, data, seq) {
+	const body = prefix + JSON.stringify(data ?? null);
+	return seq == null ? body + '}' : body + ',"seq":' + seq + '}';
+}
+
+/**
+ * Resolve which pressure signal (if any) is firing for a given sample.
+ *
+ * Precedence is fixed: MEMORY beats PUBLISH_RATE beats SUBSCRIBERS. Memory
+ * is the most urgent signal because the worker is approaching OOM; publish
+ * rate is next because CPU saturation cascades fastest; subscriber ratio
+ * comes last because heavy fan-out degrades gracefully.
+ *
+ * Any threshold may be `false` to disable that signal entirely. A signal
+ * fires when the corresponding sample value is greater than or equal to
+ * its threshold.
+ *
+ * Pure: no I/O, no globals. Suitable for unit tests.
+ *
+ * @param {{ heapUsedRatio: number, publishRate: number, subscriberRatio: number }} sample
+ * @param {{ memoryHeapUsedRatio: number | false, publishRatePerSec: number | false, subscriberRatio: number | false }} thresholds
+ * @returns {'NONE' | 'PUBLISH_RATE' | 'SUBSCRIBERS' | 'MEMORY'}
+ */
+export function computePressureReason(sample, thresholds) {
+	if (
+		thresholds.memoryHeapUsedRatio !== false &&
+		sample.heapUsedRatio >= thresholds.memoryHeapUsedRatio
+	) {
+		return 'MEMORY';
+	}
+	if (
+		thresholds.publishRatePerSec !== false &&
+		sample.publishRate >= thresholds.publishRatePerSec
+	) {
+		return 'PUBLISH_RATE';
+	}
+	if (
+		thresholds.subscriberRatio !== false &&
+		sample.subscriberRatio >= thresholds.subscriberRatio
+	) {
+		return 'SUBSCRIBERS';
+	}
+	return 'NONE';
+}
+
 /**
  * @param {string | undefined} value
  * @returns {string | undefined}

package/index.d.ts

@@ -211,6 +211,77 @@ export interface WebSocketOptions {
 	 * @default 10
 	 */
 	upgradeRateLimitWindow?: number;
+
+	/**
+	 * Backpressure-signal thresholds for `platform.pressure` and
+	 * `platform.onPressure(cb)`. The adapter samples the worker once per
+	 * `sampleIntervalMs` and reports the most urgent active signal.
+	 *
+	 * Any individual threshold may be set to `false` to disable that
+	 * signal entirely. The defaults are conservative: a small healthy app
+	 * should never trip them in steady state.
+	 *
+	 * @example
+	 * ```js
+	 * adapter({
+	 *   websocket: {
+	 *     pressure: {
+	 *       memoryHeapUsedRatio: 0.9,
+	 *       publishRatePerSec: 50000,
+	 *       subscriberRatio: false  // disable this signal
+	 *     }
+	 *   }
+	 * });
+	 * ```
+	 */
+	pressure?: {
+		/**
+		 * Trigger `'MEMORY'` pressure when `process.memoryUsage().heapUsed
+		 * / heapTotal` is greater than or equal to this ratio (0 to 1).
+		 *
+		 * Memory has the highest precedence: a worker approaching OOM
+		 * reports `'MEMORY'` even if publish rate or fan-out are also
+		 * elevated.
+		 *
+		 * Set to `false` to disable.
+		 *
+		 * @default 0.85
+		 */
+		memoryHeapUsedRatio?: number | false;
+
+		/**
+		 * Trigger `'PUBLISH_RATE'` pressure when `platform.publish()`
+		 * calls per second on this worker reach this value.
+		 *
+		 * Set to `false` to disable.
+		 *
+		 * @default 10000
+		 */
+		publishRatePerSec?: number | false;
+
+		/**
+		 * Trigger `'SUBSCRIBERS'` pressure when the average number of
+		 * subscriptions per active connection (total subscriptions /
+		 * connections, on the local worker) reaches this value.
+		 *
+		 * High fan-out per connection means each `publish()` does heavy
+		 * work; this signal lets a multi-tenant deployment shed
+		 * background streams before broadcast latency climbs.
+		 *
+		 * Set to `false` to disable.
+		 *
+		 * @default 50
+		 */
+		subscriberRatio?: number | false;
+
+		/**
+		 * Sample interval in milliseconds. Clamped to a minimum of 100 ms
+		 * to prevent pathological tight-loop sampling.
+		 *
+		 * @default 1000
+		 */
+		sampleIntervalMs?: number;
+	};
 }
 
 // -- User's WebSocket handler module exports ---------------------------------
@@ -462,6 +533,30 @@ export interface WebSocketHandler<UserData = unknown> {
 
 // -- Platform type for event.platform ----------------------------------------
 
+/**
+ * Snapshot returned by `platform.pressure` and supplied to
+ * `platform.onPressure(cb)` callbacks. All numbers are worker-local.
+ */
+export interface PressureSnapshot {
+	/** `true` when `reason !== 'NONE'`. Convenience flag for boolean checks. */
+	readonly active: boolean;
+	/**
+	 * Average subscriptions per connection on this worker
+	 * (`totalSubscriptions / connections`). `0` when the worker has no
+	 * connections.
+	 */
+	readonly subscriberRatio: number;
+	/** `platform.publish()` calls per second on this worker, last sample window. */
+	readonly publishRate: number;
+	/** Resident-set size in megabytes (`process.memoryUsage().rss`). */
+	readonly memoryMB: number;
+	/**
+	 * Most urgent active signal, by fixed precedence:
+	 * `MEMORY > PUBLISH_RATE > SUBSCRIBERS > NONE`.
+	 */
+	readonly reason: 'NONE' | 'PUBLISH_RATE' | 'SUBSCRIBERS' | 'MEMORY';
+}
+
 /**
  * Available on `event.platform` in server hooks, load functions, and actions.
  *
@@ -484,12 +579,29 @@ export interface Platform {
 	 * The message is automatically wrapped in a `{ topic, event, data }` envelope
 	 * that the client store (`svelte-adapter-uws/client`) understands.
 	 *
+	 * Every published frame is automatically stamped with a monotonic
+	 * per-topic `seq` field in the envelope. The first publish to a topic
+	 * sends `seq: 1`, the next `seq: 2`, and so on; each topic has an
+	 * independent counter. Reconnecting clients can use the seq to detect
+	 * gaps and resume from where they left off. Pass `{ seq: false }` to
+	 * skip stamping for high-cardinality or perf-sensitive topics where
+	 * the counter map would grow unbounded.
+	 *
+	 * In clustered mode the seq is worker-local (each worker stamps its
+	 * own publishes; relayed messages pass through with the originating
+	 * worker's seq). For cluster-wide monotonic seq, wire up the Redis
+	 * Lua INCR variant from the extensions package.
+	 *
 	 * @param topic - Topic string (e.g. `'todos'`, `'user:123'`, `'org:456'`)
 	 * @param event - Event name (e.g. `'created'`, `'updated'`, `'deleted'`)
 	 * @param data - Payload (will be JSON-serialized)
-	 * @param options - Optional. Pass `{ relay: false }` to skip cross-worker relay
-	 *   (use this when the message comes from an external pub/sub source like Redis
-	 *   or Postgres that already delivers to every process).
+	 * @param options - Optional.
+	 *   - `relay: false` skips cross-worker relay (use when the message
+	 *     comes from an external pub/sub source like Redis or Postgres
+	 *     that already delivers to every process).
+	 *   - `seq: false` skips the per-topic monotonic seq stamp (use for
+	 *     ephemeral or high-cardinality topics where the counter map
+	 *     would grow unbounded).
 	 *
 	 * @example
 	 * ```js
@@ -500,7 +612,7 @@ export interface Platform {
 	 * }
 	 * ```
 	 */
-	publish(topic: string, event: string, data?: unknown, options?: { relay?: boolean }): boolean;
+	publish(topic: string, event: string, data?: unknown, options?: { relay?: boolean; seq?: boolean }): boolean;
 
 	/**
 	 * Publish multiple messages in one call.
@@ -531,6 +643,57 @@ export interface Platform {
 	 */
 	send(ws: WebSocket<any>, topic: string, event: string, data?: unknown): number;
 
+	/**
+	 * Send a message to a single connection with coalesce-by-key semantics.
+	 *
+	 * Each `(ws, key)` pair holds at most one pending message. If a newer
+	 * `sendCoalesced` for the same `key` arrives before the previous frame
+	 * drains to the wire, the older one is dropped in place: latest value
+	 * wins. Insertion order is preserved across overwrites.
+	 *
+	 * Use for latest-value streams where intermediate values are noise -
+	 * price ticks, cursor positions, presence state, typing indicators,
+	 * scroll/scrub positions. For at-least-once delivery, use `send()` or
+	 * `publish()` instead.
+	 *
+	 * Serialization is deferred to the actual flush, so a stream that
+	 * overwrites the same `key` 1000 times before a single drain pays one
+	 * `JSON.stringify`, not 1000.
+	 *
+	 * The flush attempts immediately and again on every uWS drain event.
+	 * On backpressure or drop from the underlying socket, pumping stops
+	 * and resumes when the connection drains.
+	 *
+	 * @example
+	 * ```js
+	 * // In hooks.ws.js - cursor positions during a collaborative edit.
+	 * // Each peer sees only the latest cursor for every other user;
+	 * // intermediate positions are dropped under load.
+	 * export function message(ws, { data, platform }) {
+	 *   const msg = JSON.parse(Buffer.from(data).toString());
+	 *   if (msg.event !== 'cursor') return;
+	 *   const { docId, userId } = ws.getUserData();
+	 *   for (const peer of getPeersOf(docId)) {
+	 *     platform.sendCoalesced(peer, {
+	 *       key: 'cursor:' + userId,
+	 *       topic: 'doc:' + docId,
+	 *       event: 'cursor',
+	 *       data: { userId, x: msg.data.x, y: msg.data.y }
+	 *     });
+	 *   }
+	 * }
+	 * ```
+	 *
+	 * @param ws - The WebSocket connection.
+	 * @param message - `{ key, topic, event, data }`. `key` identifies the
+	 *   coalesce slot per connection; `topic`, `event`, `data` are the
+	 *   envelope fields the client store understands.
+	 */
+	sendCoalesced(
+		ws: WebSocket<any>,
+		message: { key: string; topic: string; event: string; data?: unknown }
+	): void;
+
 	/**
 	 * Send a message to all connections whose userData matches a filter.
 	 * Returns the number of connections the message was sent to.
@@ -539,7 +702,7 @@ export interface Platform {
 	 *
 	 * **Performance note:** `sendTo()` iterates every open connection on the local
 	 * worker to evaluate the filter. For broadcasting to large groups, prefer
-	 * `publish()` with a topic — topics are dispatched by uWS's C++ TopicTree
+	 * `publish()` with a topic - topics are dispatched by uWS's C++ TopicTree
 	 * with O(subscribers) fan-out and no JS loop. Use `sendTo()` when you need
 	 * to target connections by arbitrary runtime properties that can't be mapped
 	 * to a static topic name (e.g., filtering by session data set at upgrade time).
@@ -589,6 +752,59 @@ export interface Platform {
 	 */
 	subscribers(topic: string): number;
 
+	/**
+	 * Live snapshot of worker-local backpressure signals.
+	 *
+	 * Sampled by a coarse 1 Hz timer (configurable via
+	 * `WebSocketOptions.pressure.sampleIntervalMs`). Reading the snapshot
+	 * is a property access; no I/O or computation per read.
+	 *
+	 * `reason` is the most urgent active signal. Precedence is fixed:
+	 * `MEMORY > PUBLISH_RATE > SUBSCRIBERS`. A worker under multiple
+	 * stresses reports the highest-priority one.
+	 *
+	 * @example
+	 * ```js
+	 * export async function POST({ platform, request }) {
+	 *   if (platform.pressure.reason === 'MEMORY') {
+	 *     return new Response('Try again shortly', { status: 503 });
+	 *   }
+	 *   const todo = await db.create(await request.formData());
+	 *   platform.publish('todos', 'created', todo);
+	 *   return new Response('OK');
+	 * }
+	 * ```
+	 */
+	readonly pressure: PressureSnapshot;
+
+	/**
+	 * Register a callback fired on each pressure-state transition (when
+	 * `pressure.reason` changes between samples). Fired at most once per
+	 * sample tick. Returns an unsubscribe function.
+	 *
+	 * Use this for push-style reaction: pause background streams when the
+	 * worker is under load, resume them when it recovers.
+	 *
+	 * Callbacks run synchronously inside the sampler. A throwing listener
+	 * does not break the sampler or other listeners; the error is logged
+	 * and the next listener still runs.
+	 *
+	 * @example
+	 * ```js
+	 * export function open(ws, { platform }) {
+	 *   const off = platform.onPressure(({ reason, active }) => {
+	 *     ws.send(JSON.stringify({ topic: '__pressure', event: reason, data: { active } }));
+	 *   });
+	 *   ws.getUserData().__offPressure = off;
+	 * }
+	 *
+	 * export function close(ws) {
+	 *   ws.getUserData().__offPressure?.();
+	 * }
+	 * ```
+	 */
+	onPressure(cb: (snapshot: PressureSnapshot) => void): () => void;
+
 	/**
 	 * Get a scoped helper for a topic. Reduces repetition when publishing
 	 * multiple events to the same topic, and provides CRUD shorthand methods

package/index.js

@@ -289,7 +289,8 @@ export default function (opts = {}) {
 				allowedOrigins: websocket?.allowedOrigins ?? 'same-origin',
 				upgradeTimeout: websocket?.upgradeTimeout ?? 10,
 				upgradeRateLimit: websocket?.upgradeRateLimit ?? 10,
-				upgradeRateLimitWindow: websocket?.upgradeRateLimitWindow ?? 10
+				upgradeRateLimitWindow: websocket?.upgradeRateLimitWindow ?? 10,
+				pressure: websocket?.pressure
 			};
 
 			// Scan the bundled WS handler for `upgradeResponse(..., { 'set-cookie': ... })`

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "svelte-adapter-uws",
-  "version": "0.4.13",
+  "version": "0.5.0-next.1",
+  "publishConfig": {
+    "tag": "next"
+  },
   "description": "SvelteKit adapter for uWebSockets.js - high-performance C++ HTTP server with built-in WebSocket support",
   "author": "Kevin Radziszewski",
   "license": "MIT",

package/testing.js

@@ -1,4 +1,5 @@
 import { parseCookies } from './files/cookies.js';
+import { nextTopicSeq, completeEnvelope } from './files/utils.js';
 
 /**
  * Safely quote a string for JSON embedding. Throws on invalid characters.
@@ -23,10 +24,12 @@ function esc(s) {
  * @param {string} topic
  * @param {string} event
  * @param {unknown} [data]
+ * @param {number | null} [seq]
  * @returns {string}
  */
-function envelope(topic, event, data) {
-	return '{"topic":' + esc(topic) + ',"event":' + esc(event) + ',"data":' + JSON.stringify(data ?? null) + '}';
+function envelope(topic, event, data, seq) {
+	const prefix = '{"topic":' + esc(topic) + ',"event":' + esc(event) + ',"data":';
+	return completeEnvelope(prefix, data, seq);
 }
 
 /**
@@ -56,6 +59,9 @@ export async function createTestServer(options = {}) {
 	/** @type {Set<import('uWebSockets.js').WebSocket<any>>} */
 	const wsConnections = new Set();
 
+	/** @type {Map<string, number>} */
+	const topicSeqs = new Map();
+
 	/** @type {Array<(value: any) => void>} */
 	let connectionWaiters = [];
 
@@ -63,8 +69,11 @@ export async function createTestServer(options = {}) {
 	let messageWaiters = [];
 
 	const platform = {
-		publish(topic, event, data) {
-			const msg = envelope(topic, event, data);
+		publish(topic, event, data, options) {
+			const seq = (options && options.seq === false)
+				? null
+				: nextTopicSeq(topicSeqs, topic);
+			const msg = envelope(topic, event, data, seq);
 			return app.publish(topic, msg, false, false);
 		},
 		send(ws, topic, event, data) {
@@ -115,7 +124,9 @@ export async function createTestServer(options = {}) {
 			const rawIp = new TextDecoder().decode(res.getRemoteAddressAsText());
 
 			if (!handler.upgrade) {
-				res.upgrade({ remoteAddress: rawIp }, secKey, secProtocol, secExtensions, context);
+				res.cork(() => {
+					res.upgrade({ remoteAddress: rawIp }, secKey, secProtocol, secExtensions, context);
+				});
 				return;
 			}
 
@@ -143,16 +154,18 @@ export async function createTestServer(options = {}) {
 						userData = result || {};
 					}
 					if (!userData.remoteAddress) userData.remoteAddress = rawIp;
-					if (responseHeaders) {
-						for (const [hk, hv] of Object.entries(responseHeaders)) {
-							if (Array.isArray(hv)) {
-								for (const v of hv) res.writeHeader(hk, v);
-							} else {
-								res.writeHeader(hk, hv);
+					res.cork(() => {
+						if (responseHeaders) {
+							for (const [hk, hv] of Object.entries(responseHeaders)) {
+								if (Array.isArray(hv)) {
+									for (const v of hv) res.writeHeader(hk, v);
+								} else {
+									res.writeHeader(hk, hv);
+								}
 							}
 						}
-					}
-					res.upgrade(userData, secKey, secProtocol, secExtensions, context);
+						res.upgrade(userData, secKey, secProtocol, secExtensions, context);
+					});
 				})
 				.catch((err) => {
 					if (!aborted) {

package/vite.js

@@ -275,7 +275,7 @@ export default function uws(options = {}) {
 				return;
 			}
 
-			// E7: warn if our WS path collides with the Vite HMR WebSocket path.
+			// Warn if our WS path collides with the Vite HMR WebSocket path.
 			const hmrConfig = server.config.server?.hmr;
 			if (hmrConfig && typeof hmrConfig === 'object' && hmrConfig.path === wsPath) {
 				server.config.logger.warn(