svelte-adapter-uws 0.4.7 → 0.4.9

package/README.md

@@ -404,6 +404,16 @@ adapter({
 })
 ```
 
+### Backpressure and connection limits
+
+These options control how the server handles misbehaving or slow clients at the WebSocket level:
+
+**`maxPayloadLength`** (default: 16 KB) -- the maximum size of a single incoming WebSocket message. If a client sends a message larger than this, uWS closes the connection immediately (not just the message -- the entire connection is dropped). Set this based on the largest message your application expects to receive.
+
+**`maxBackpressure`** (default: 1 MB) -- the per-connection outbound send buffer. When a client reads slower than the server writes, messages queue up in this buffer. Once it overflows, subsequent `send()` and `publish()` calls for that connection silently drop the message. The `drain` hook fires when the buffer empties again. Lower this if you expect many slow consumers to avoid per-connection memory bloat.
+
+**`upgradeRateLimit`** (default: 10 per 10s window) -- sliding-window rate limit on WebSocket upgrade requests per client IP. Clients exceeding the limit get a `429 Too Many Requests` response. The IP rate map is capped at 10,000 entries with LRU eviction by activity score, so sustained connection floods from many IPs don't cause unbounded memory growth.
+
 ### Static file behavior
 
 All static assets (from the `client/` and `prerendered/` output directories) are loaded once at startup and served directly from RAM. Each response automatically includes:
@@ -610,6 +620,22 @@ export function drain(ws, { platform }) {
 }
 ```
 
+### Message protocol
+
+The adapter uses a JSON envelope format for all pub/sub messages: `{ topic, event, data }`. Control messages from the client store (`subscribe`, `unsubscribe`, `subscribe-batch`) use `{ type, topic }` or `{ type, topics }`.
+
+To avoid JSON-parsing every incoming message, the handler uses a byte-prefix discriminator: control messages start with `{"type"` (byte 3 is `y`), while user envelopes start with `{"topic"` (byte 3 is `o`). A single byte comparison skips `JSON.parse` entirely for user messages. Messages over 8 KB are also skipped (generous ceiling for `subscribe-batch` with many topics, well above any realistic control message).
+
+### Topic validation
+
+Topics submitted by clients are validated before being accepted:
+
+- Must be between 1 and 256 characters
+- Must not contain control characters (code points below 32)
+- `subscribe-batch` accepts at most 256 topics per message (the client only sends what it was subscribed to before a reconnect)
+
+Topics prefixed with `__` are reserved for adapter plugins (presence uses `__presence:*`, replay uses `__replay:*`). They are not blocked at the protocol level because plugins subscribe to them from the client, but application code should not use the `__` prefix for its own topics.
+
 ### Explicit handler path
 
 If your handler is somewhere other than `src/hooks.ws.js`:
@@ -630,7 +656,7 @@ The `upgrade` function receives an `UpgradeContext`:
 {
   headers: { 'cookie': '...', 'host': 'localhost:3000', ... },  // all lowercase
   cookies: { session_id: 'abc123', theme: 'dark' },             // parsed from Cookie header
-  url: '/ws',                                                    // request path
+  url: '/ws?token=abc',                                           // request path + query string
   remoteAddress: '127.0.0.1'                                     // client IP
 }
 ```
@@ -2292,7 +2318,9 @@ CLUSTER_WORKERS=4 node build
 CLUSTER_WORKERS=auto PORT=8080 ORIGIN=https://example.com node build
 ```
 
-If a worker crashes, it is automatically restarted with exponential backoff. On `SIGTERM`/`SIGINT`, the primary tells all workers to drain in-flight requests and shut down gracefully.
+If a worker crashes, it is automatically restarted with exponential backoff (100ms initial, doubling up to 5s, max 50 attempts before the primary exits). On `SIGTERM`/`SIGINT`, the primary tells all workers to drain in-flight requests and shut down gracefully.
+
+The primary thread monitors worker health with a 10-second heartbeat interval. If a worker fails to acknowledge a heartbeat within 30 seconds (stuck event loop, deadlock), the primary terminates it and the restart policy kicks in.
 
 ### Clustering modes
 
@@ -2311,14 +2339,14 @@ Setting `CLUSTER_MODE=reuseport` on non-Linux platforms is an error (SO_REUSEPOR
 
 ### WebSocket + clustering
 
-`platform.publish()` is automatically relayed across all workers via the primary thread, so subscribers on any worker receive the message. This is built in -- no external pub/sub needed.
+`platform.publish()` is automatically relayed across all workers via the primary thread, so subscribers on any worker receive the message. This is built in -- no external pub/sub needed. The relay is microtask-batched: a SvelteKit action that calls `publish()` multiple times sends a single IPC message per microtask instead of one per call.
 
 If you add your own cross-process messaging (Redis, Postgres LISTEN/NOTIFY, etc.), pass `{ relay: false }` to prevent duplicate delivery -- your external source already fans out to every worker, so the built-in relay would double it.
 
 Per-worker limitations (acceptable for most apps):
 - `platform.connections`  - returns the count for the local worker only
 - `platform.subscribers(topic)`  - returns the count for the local worker only
-- `platform.sendTo(filter, ...)`  - only reaches connections on the local worker
+- `platform.sendTo(filter, ...)`  - iterates the local worker's connections only, no cross-worker relay
 
 ### Docker / multi-process deployments (Linux)
 
@@ -2498,6 +2526,13 @@ uWS native pub/sub delivered 3.5M messages/s with exact 50x fan-out. The adapter
 - No per-request stream allocation for static files (in-memory Buffer, not `fs.createReadStream`)
 - No Node.js `http.IncomingMessage` shim (we construct `Request` directly from uWS)
 
+### Internal optimizations
+
+The adapter applies several allocation and caching strategies to stay off the GC's radar on the hot path:
+
+- **Request state pooling** -- SSR requests need a `{ aborted: false }` state object. Instead of allocating one per request (which promotes to V8's old generation and stays there), the adapter maintains a pool of up to 256 reusable state objects. Eliminates young-gen GC churn under sustained load.
+- **Envelope prefix cache** -- `platform.publish()` and `platform.send()` wrap data in a `{"topic":"...","event":"...","data":...}` envelope. The prefix up to `"data":` is cached in a 256-entry LRU map keyed by topic+event. Repeated publishes to the same topic/event (the common case) skip 4 string concatenations and the character validation scan. The cache is trimmed every 60 seconds to reclaim stale entries from shifted traffic patterns.
+
 ### SSR request deduplication
 
 When multiple concurrent requests arrive for the same anonymous (no cookie/auth) GET or HEAD URL, only one is dispatched to SvelteKit. The others wait for the result and reconstruct their own response from the shared buffer. This prevents redundant rendering work during traffic spikes, a common pattern when a post goes viral or a cron job hits a popular page at the same time as real users.

package/files/handler.js

@@ -1471,7 +1471,8 @@ if (WS_ENABLED) {
 			}
 
 			// -- User upgrade handler path (may be async) --
-			const url = req.getUrl();
+			const query = req.getQuery();
+			const url = query ? req.getUrl() + '?' + query : req.getUrl();
 
 			let aborted = false;
 			res.onAborted(() => {

package/index.d.ts

@@ -209,7 +209,7 @@ export interface UpgradeContext {
 	headers: Record<string, string>;
 	/** Parsed cookies from the Cookie header. */
 	cookies: Record<string, string>;
-	/** The request URL path. */
+	/** The request URL path, including query string if present (e.g. '/ws?token=abc'). */
 	url: string;
 	/** Remote IP address. */
 	remoteAddress: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-adapter-uws",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "SvelteKit adapter for uWebSockets.js - high-performance C++ HTTP server with built-in WebSocket support",
   "author": "Kevin Radziszewski",
   "license": "MIT",

package/vite.js

@@ -358,7 +358,7 @@ export default function uws(options = {}) {
 							userHandlers.upgrade({
 								headers,
 								cookies: parseCookies(headers['cookie']),
-								url: pathname,
+								url: req.url || pathname,
 								remoteAddress: req.socket?.remoteAddress || ''
 							})
 						);