svelte-adapter-uws 0.4.14 → 0.5.0-next.2

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.
@@ -1791,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;
@@ -1818,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);
@@ -1833,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);
 			}
@@ -1860,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)
@@ -1931,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');
 	}