svelte-adapter-uws 0.2.0 → 0.2.2

package/README.md

@@ -33,7 +33,7 @@ I've been loving Svelte and SvelteKit for a long time. I always wanted to expand
 - [TypeScript setup](#typescript-setup)
 - [Svelte 4 support](#svelte-4-support)
 - [Deploying with Docker](#deploying-with-docker)
-- [Clustering (Linux)](#clustering-linux)
+- [Clustering](#clustering)
 - [Performance](#performance)
 - [Troubleshooting](#troubleshooting)
 - [License](#license)
@@ -383,7 +383,7 @@ If you set `envPrefix: 'MY_APP_'` in the adapter config, all variables are prefi
 | `XFF_DEPTH` | `1` | Position from right in `X-Forwarded-For` |
 | `BODY_SIZE_LIMIT` | `512K` | Max request body size (supports `K`, `M`, `G` suffixes) |
 | `SHUTDOWN_TIMEOUT` | `30` | Seconds to wait during graceful shutdown |
-| `CLUSTER_WORKERS` | - | Number of worker processes (or `auto` for CPU count). Linux only, HTTP only |
+| `CLUSTER_WORKERS` | - | Number of worker threads (or `auto` for CPU count) |
 
 ### Graceful shutdown
 
@@ -657,7 +657,9 @@ Available in server hooks, load functions, form actions, and API routes.
 
 ### `platform.publish(topic, event, data)`
 
-Send a message to all WebSocket clients subscribed to a topic:
+Send a message to all WebSocket clients subscribed to a topic.
+
+Topic and event names are validated before being written into the JSON envelope -- quotes, backslashes, and control characters will throw. This prevents JSON injection when names are built from dynamic values like user IDs (`platform.publish(\`user:\${id}\`, ...)`). The validation is a single-pass char scan and adds no measurable overhead.
 
 ```js
 // src/routes/todos/+page.server.js
@@ -1170,9 +1172,9 @@ docker run -p 3000:3000 \
 
 ---
 
-## Clustering (Linux)
+## Clustering
 
-On Linux, multiple processes can share the same port via `SO_REUSEPORT` - the kernel load-balances incoming connections across workers. This gives you near-linear scaling for HTTP/SSR workloads with zero coordination overhead.
+The adapter supports multi-core scaling via uWebSockets.js worker thread distribution. A primary thread creates an acceptor app that distributes incoming connections across worker threads, each running their own uWS instance. This works on **all platforms** (Linux, macOS, Windows).
 
 Set the `CLUSTER_WORKERS` environment variable to enable it:
 
@@ -1187,12 +1189,16 @@ CLUSTER_WORKERS=4 node build
 CLUSTER_WORKERS=auto PORT=8080 ORIGIN=https://example.com node build
 ```
 
-The primary process forks N workers, each running their own uWS server on the same port. If a worker crashes, it is automatically restarted. On `SIGTERM`/`SIGINT`, the primary forwards the signal to all workers for graceful shutdown.
+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.
+
+### WebSocket + clustering
 
-### Limitations
+`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.
 
-- **Linux only** - `SO_REUSEPORT` is a Linux kernel feature. On other platforms, the variable is ignored with a warning.
-- **HTTP/SSR only** - clustering is automatically disabled when WebSocket is enabled (`websocket: true` or `websocket: { ... }`). uWS pub/sub is per-process, so messages published in one worker would not reach clients connected to another worker. If you need clustered WebSocket, bring an external pub/sub backend (Redis, NATS, etc.) and manage multi-process coordination yourself.
+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
 
 ---
 
@@ -1200,31 +1206,75 @@ The primary process forks N workers, each running their own uWS server on the sa
 
 ### Why uWebSockets.js?
 
-uWebSockets.js is a C++ HTTP and WebSocket server compiled to a native V8 addon. In benchmarks it consistently outperforms Node.js' built-in `http` module, Express, Fastify, and every other JavaScript HTTP server by a significant margin - often 5-10x more requests per second.
+uWebSockets.js is a C++ HTTP and WebSocket server compiled to a native V8 addon. It consistently outperforms Node.js' built-in `http` module, Express, Fastify, and every other JavaScript HTTP server by a significant margin.
+
+We ran a comprehensive benchmark suite isolating every layer of overhead - from barebones uWS through the full adapter pipeline - and compared against `@sveltejs/adapter-node` (Node http + Polka + sirv) and the most popular WebSocket libraries (`socket.io`, `ws`). The benchmark code is in the [`bench/`](bench/) directory so you can reproduce it yourself.
 
-### Our overhead vs barebones uWS
+### HTTP: adapter-uws vs adapter-node
 
-A barebones uWebSockets.js "hello world" can handle 500k+ requests per second on a single core. This adapter adds overhead that is unavoidable for what it does:
+Tested with a trivial SvelteKit handler (isolates adapter overhead from your app code):
 
-1. **SvelteKit SSR** - every non-static request goes through SvelteKit's `server.respond()`, which runs your load functions, renders components, and produces HTML. This is the biggest cost and it's the whole point of using SvelteKit.
+| | adapter-uws | adapter-node | Multiplier |
+|---|---|---|---|
+| **Static files** | 135,300 req/s | 20,100 req/s | **6.7x faster** |
+| **SSR** | 125,100 req/s | 53,900 req/s | **2.3x faster** |
 
-2. **Static file cache** - on startup we walk the build output and load every static file into memory with its precompressed variants. This is a one-time cost. Serving static files is then a single `Map.get()` plus a `res.cork()` + `res.end()` - about as fast as it gets without sendfile.
+<sup>100 connections, 10 pipelining, 10s, 2 runs averaged. Node v24, Windows 11.</sup>
 
-3. **Request construction** - we build a standard `Request` object from uWS' stack-allocated `HttpRequest`. This means reading all headers synchronously (uWS requirement) and constructing a URL string. We read headers lazily for static files (only `accept-encoding` and `if-none-match`), but SSR requires the full set.
+The static file gap is the largest because `adapter-node` uses sirv which calls `fs.createReadStream().pipe(res)` per request, while we serve from an in-memory `Map` with a single `res.cork()` + `res.end()`. The SSR gap comes from uWS's C++ HTTP parsing and batched writes vs Node's async drain event cycle.
 
-4. **Response streaming** - we read from the `Response.body` ReadableStream and write chunks through uWS with backpressure support (`onWritable`). Single-chunk responses (most SSR pages) are optimized into a single `res.cork()` + `res.end()` call.
+### WebSocket: uWS vs socket.io vs ws
 
-5. **WebSocket envelope** - every pub/sub message is wrapped in `JSON.stringify({ topic, event, data })`. This is a few microseconds per message. The tradeoff is a clean, standardized format that the client store understands without configuration.
+50 connected clients, 10 senders, burst mode, 8 seconds:
+
+| Server | Messages delivered/s | vs adapter-uws |
+|---|---|---|
+| **uWS native** (barebones) | 3,625,000 | 1.0x |
+| **adapter-uws** (full handler) | 3,642,000 | baseline |
+| **socket.io** | 177,200 | **20.5x slower** |
+| **ws** library | 164,500 | **22.1x slower** |
+
+uWS native pub/sub delivered 3.6M messages/s with perfect 50x fan-out. After optimization, the adapter matches it -- the byte-prefix check and string template envelope add near-zero overhead to the hot path. `socket.io` and `ws` both collapsed under the same load, delivering less than 1x fan-out (massive message loss/queueing).
+
+### Where the overhead goes
+
+**HTTP (SSR path) - 23% total overhead vs barebones uWS:**
+
+| Layer | Cost | Notes |
+|---|---|---|
+| `res.cork()` + status + headers | 11.4% | Writing a proper HTTP response - unavoidable |
+| `new Request()` construction | 9.7% | Required by SvelteKit's `server.respond()` contract |
+| Response body reader loop | ~2% | `getReader()` + `read()` + async scheduling |
+| Header collection, AbortController | ~0% | Measured at 0.08us and 0.004us per request |
+
+**WebSocket - optimized down from 27% to ~4% overhead vs barebones uWS pub/sub:**
+
+The two largest WebSocket costs were `JSON.parse()` on every message for the subscribe/unsubscribe check (15%) and `JSON.stringify()` for envelope wrapping (8%). Both have been optimized:
+
+| Layer | Before | After | How |
+|---|---|---|---|
+| Subscribe/unsubscribe check | ~15% | ~0% | Byte-prefix discriminator: control messages start with `{"ty` (byte[3]=`y`), user envelopes start with `{"to` (byte[3]=`o`). A single byte comparison skips `JSON.parse` for all regular messages -- from 0.39us to 0.001us per message. |
+| Envelope wrapping | ~8% | ~4.5% | String template with `esc()` validation instead of `JSON.stringify` on a wrapper object. Topic and event names are validated with a fast char scan (~10ns) that throws on quotes, backslashes, or control characters — only `data` is stringified. From 0.135us to ~0.085us per publish. |
+| Connection tracking | ~2% | ~2% | Unchanged |
+| Origin validation, upgrade headers | ~2% | ~2% | Unchanged |
 
 **What we don't add:**
-- No middleware chain
-- No routing layer (uWS' native routing + SvelteKit's router)
-- No per-request allocations beyond what's needed
+- No middleware chain (no Polka, no Express)
+- No routing layer (uWS native routing + SvelteKit's router)
+- 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)
 
 ### The bottom line
 
-For static files, performance is very close to barebones uWS. For SSR, the bottleneck is your Svelte components and load functions, not the adapter. The adapter's job is to get out of the way as fast as possible - and it does.
+The adapter retains 77% of raw uWS HTTP throughput and ~96% of raw uWS WebSocket throughput. The HTTP overhead is dominated by things SvelteKit requires (`new Request()`, proper HTTP headers). The WebSocket overhead is now almost entirely the `JSON.stringify` of your `data` payload -- the adapter's own machinery costs near zero. In a real app, your load functions and component rendering will dwarf all of this -- the adapter's job is to get out of the way, and it does.
+
+To run the benchmarks yourself:
+
+```bash
+npm install  # installs uWebSockets.js, autocannon, etc.
+node bench/run.mjs          # adapter overhead breakdown
+node bench/run-compare.mjs  # full comparison vs adapter-node + socket.io
+```
 
 ---
 
@@ -1455,7 +1505,7 @@ const todos = on('todo');      // 'todo'  - WRONG, singular vs plural
 
 ### "How do I see what the message envelope looks like?"
 
-Every message sent through `platform.publish()` or `platform.topic().created()` arrives as JSON with this shape:
+Every message sent through `platform.publish()` or `platform.topic().created()` arrives as JSON with this shape. The envelope is constructed with string concatenation for speed, but `topic` and `event` are validated first -- if either contains a quote, backslash, or control character, the call throws instead of producing malformed JSON:
 
 ```json
 {

package/files/handler.js

@@ -24,6 +24,26 @@ class PayloadTooLargeError extends Error {
 	constructor() { super('Payload too large'); }
 }
 
+/**
+ * Safely quote a string for JSON embedding. Topics and events are
+ * developer-defined identifiers — a quote, backslash, or control character
+ * is always a bug, so we throw instead of silently escaping.
+ * @param {string} s
+ * @returns {string} JSON-quoted string, e.g. '"todos"'
+ */
+function esc(s) {
+	for (let i = 0; i < s.length; i++) {
+		const c = s.charCodeAt(i);
+		if (c < 32 || c === 34 || c === 92) {
+			throw new Error(
+				`Topic/event name contains invalid character at index ${i}: '${s}'. ` +
+				'Names must not contain quotes, backslashes, or control characters.'
+			);
+		}
+	}
+	return '"' + s + '"';
+}
+
 // -- In-memory static file cache ---------------------------------------------
 
 /**
@@ -174,7 +194,7 @@ const platform = {
 	 * No-op if no clients are subscribed - safe to call unconditionally.
 	 */
 	publish(topic, event, data) {
-		const envelope = JSON.stringify({ topic, event, data });
+		const envelope = '{"topic":' + esc(topic) + ',"event":' + esc(event) + ',"data":' + JSON.stringify(data) + '}';
 		const result = app.publish(topic, envelope, false, false);
 		// Relay to other workers via main thread (no-op in single-process mode)
 		if (parentPort) {
@@ -188,7 +208,7 @@ const platform = {
 	 * Wraps in the same { topic, event, data } envelope as publish().
 	 */
 	send(ws, topic, event, data) {
-		return ws.send(JSON.stringify({ topic, event, data }), false, false);
+		return ws.send('{"topic":' + esc(topic) + ',"event":' + esc(event) + ',"data":' + JSON.stringify(data) + '}', false, false);
 	},
 
 	/**
@@ -197,7 +217,7 @@ const platform = {
 	 * Returns the number of connections the message was sent to.
 	 */
 	sendTo(filter, topic, event, data) {
-		const envelope = JSON.stringify({ topic, event, data });
+		const envelope = '{"topic":' + esc(topic) + ',"event":' + esc(event) + ',"data":' + JSON.stringify(data) + '}';
 		let count = 0;
 		for (const ws of wsConnections) {
 			if (filter(ws.getUserData())) {
@@ -382,7 +402,7 @@ function serveStatic(res, entry, acceptEncoding, ifNoneMatch, headOnly = false)
  * @param {string} ifNoneMatch
  * @returns {boolean}
  */
-function tryPrerendered(res, pathname, search, acceptEncoding, ifNoneMatch) {
+function tryPrerendered(res, pathname, search, acceptEncoding, ifNoneMatch, headOnly = false) {
 	// Fast path: skip decodeURIComponent when there are no encoded characters
 	const needsDecode = pathname.includes('%');
 	let decoded;
@@ -404,7 +424,7 @@ function tryPrerendered(res, pathname, search, acceptEncoding, ifNoneMatch) {
 	if (prerendered.has(decoded)) {
 		const entry = staticCache.get(decoded);
 		if (entry) {
-			serveStatic(res, entry, acceptEncoding, ifNoneMatch);
+			serveStatic(res, entry, acceptEncoding, ifNoneMatch, headOnly);
 			return true;
 		}
 	}
@@ -651,7 +671,7 @@ function handleRequest(res, req) {
 	// Lightweight: only 2 header reads, no full collection, no remoteAddress decode
 	if (METHOD === 'GET' || METHOD === 'HEAD') {
 		if (tryPrerendered(res, pathname, query ? `?${query}` : '',
-			req.getHeader('accept-encoding'), req.getHeader('if-none-match'))) {
+			req.getHeader('accept-encoding'), req.getHeader('if-none-match'), METHOD === 'HEAD')) {
 			return;
 		}
 	}
@@ -821,8 +841,12 @@ if (WS_ENABLED) {
 
 		message: (ws, message, isBinary) => {
 			// Built-in: handle subscribe/unsubscribe from the client store.
-			// Only parse small text messages - sub/unsub envelopes are always < 512 bytes.
-			if (!isBinary && message.byteLength < 512) {
+			// Control messages are JSON text: {"type":"subscribe","topic":"..."}
+			// Byte-prefix check: {"type" has byte[3]='y' (0x79), while user
+			// envelopes {"topic" have byte[3]='o' (0x6F). Only JSON.parse when
+			// the prefix matches - skips parsing for 99%+ of messages.
+			if (!isBinary && message.byteLength < 512 &&
+				(new Uint8Array(message))[3] === 0x79 /* 'y' in {"type" */) {
 				try {
 					const msg = JSON.parse(Buffer.from(message).toString());
 					if (msg.type === 'subscribe' && typeof msg.topic === 'string') {

package/files/index.js

@@ -41,6 +41,12 @@ if (is_primary) {
 	let shutting_down = false;
 	let listen_socket = null;
 
+	// Exponential backoff for crash-looping workers
+	let restart_delay = 0;
+	const RESTART_DELAY_MAX = 5000;
+	/** @type {ReturnType<typeof setTimeout> | null} */
+	let backoff_reset_timer = null;
+
 	function spawn_worker() {
 		const worker = new Worker(fileURLToPath(import.meta.url));
 		workers.set(worker, null);
@@ -50,6 +56,9 @@ if (is_primary) {
 				workers.set(worker, msg.descriptor);
 				acceptorApp.addChildAppDescriptor(msg.descriptor);
 				console.log(`Worker thread ${worker.threadId} registered`);
+				// Worker started successfully — reset backoff
+				restart_delay = 0;
+				if (backoff_reset_timer) { clearTimeout(backoff_reset_timer); backoff_reset_timer = null; }
 			} else if (msg.type === 'publish') {
 				// Relay pub/sub to all OTHER workers
 				for (const [w] of workers) {
@@ -65,8 +74,13 @@ if (is_primary) {
 			}
 			workers.delete(worker);
 			if (!shutting_down) {
-				console.log(`Worker thread ${worker.threadId} exited with code ${code}, restarting...`);
-				spawn_worker();
+				restart_delay = restart_delay ? Math.min(restart_delay * 2, RESTART_DELAY_MAX) : 100;
+				console.log(`Worker thread ${worker.threadId} exited with code ${code}, restarting in ${restart_delay}ms...`);
+				backoff_reset_timer = setTimeout(() => { spawn_worker(); }, restart_delay);
+			}
+			// If shutting down and all workers have exited, exit immediately
+			if (shutting_down && workers.size === 0) {
+				process.exit(0);
 			}
 		});
 

package/index.d.ts

@@ -15,6 +15,7 @@ import type { WebSocket } from 'uWebSockets.js';
  * | `SSL_KEY` | - | Path to TLS private key file |
  * | `PROTOCOL_HEADER` | - | Header for protocol detection (e.g. `x-forwarded-proto`) |
  * | `HOST_HEADER` | - | Header for host detection (e.g. `x-forwarded-host`) |
+ * | `PORT_HEADER` | - | Header for port override (e.g. `x-forwarded-port`) |
  * | `ADDRESS_HEADER` | - | Header for client IP (e.g. `x-forwarded-for`) |
  * | `XFF_DEPTH` | `1` | Position from right in `X-Forwarded-For` |
  * | `BODY_SIZE_LIMIT` | `512K` | Max request body size (`K`, `M`, `G` suffixes) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-adapter-uws",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "SvelteKit adapter for uWebSockets.js - high-performance C++ HTTP server with built-in WebSocket support",
   "author": "Kevin Radziszewski",
   "license": "MIT",
@@ -49,7 +49,6 @@
   "peerDependencies": {
     "@sveltejs/kit": "^2.0.0",
     "svelte": "^4.0.0 || ^5.0.0",
-    "uWebSockets.js": "uNetworking/uWebSockets.js#v20.60.0",
     "ws": "^8.0.0"
   },
   "peerDependenciesMeta": {
@@ -76,6 +75,14 @@
     "websocket"
   ],
   "devDependencies": {
-    "vitest": "^4.0.18"
+    "autocannon": "^8.0.0",
+    "polka": "^0.5.2",
+    "socket.io": "^4.8.3",
+    "socket.io-client": "^4.8.3",
+    "vitest": "^4.0.18",
+    "ws": "^8.19.0"
+  },
+  "optionalDependencies": {
+    "uWebSockets.js": "github:uNetworking/uWebSockets.js#v20.60.0"
   }
 }

package/vite.js

@@ -3,6 +3,25 @@ import path from 'node:path';
 import { existsSync } from 'node:fs';
 import { parseCookies } from './files/cookies.js';
 
+/**
+ * Safely quote a string for JSON embedding. Throws on invalid characters
+ * (quotes, backslashes, control chars) — these are always bugs in topic/event names.
+ * @param {string} s
+ * @returns {string}
+ */
+function esc(s) {
+	for (let i = 0; i < s.length; i++) {
+		const c = s.charCodeAt(i);
+		if (c < 32 || c === 34 || c === 92) {
+			throw new Error(
+				`Topic/event name contains invalid character at index ${i}: '${s}'. ` +
+				'Names must not contain quotes, backslashes, or control characters.'
+			);
+		}
+	}
+	return '"' + s + '"';
+}
+
 /**
  * Vite plugin that provides WebSocket support during development.
  *
@@ -78,7 +97,7 @@ export default function uwsDev(options = {}) {
 	 * @returns {boolean}
 	 */
 	function publish(topic, event, data) {
-		const envelope = JSON.stringify({ topic, event, data });
+		const envelope = '{"topic":' + esc(topic) + ',"event":' + esc(event) + ',"data":' + JSON.stringify(data) + '}';
 		let sent = false;
 		for (const [ws, topics] of subscriptions) {
 			if (topics.has(topic) && ws.readyState === 1) {
@@ -98,7 +117,7 @@ export default function uwsDev(options = {}) {
 	 * @returns {number}
 	 */
 	function send(ws, topic, event, data) {
-		return ws.send(JSON.stringify({ topic, event, data }), false, false) ?? 1;
+		return ws.send('{"topic":' + esc(topic) + ',"event":' + esc(event) + ',"data":' + JSON.stringify(data) + '}', false, false) ?? 1;
 	}
 
 	/**
@@ -110,7 +129,7 @@ export default function uwsDev(options = {}) {
 	 * @returns {number}
 	 */
 	function sendTo(filter, topic, event, data) {
-		const envelope = JSON.stringify({ topic, event, data });
+		const envelope = '{"topic":' + esc(topic) + ',"event":' + esc(event) + ',"data":' + JSON.stringify(data) + '}';
 		let count = 0;
 		for (const [, wrapped] of wsWrappers) {
 			if (filter(wrapped.getUserData())) {
@@ -264,7 +283,9 @@ export default function uwsDev(options = {}) {
 					const arrayBuffer = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
 
 					// Handle subscribe/unsubscribe from client store
-					if (!isBinary && buf.byteLength < 512) {
+				// Byte-prefix check: {"type" has byte[3]='y' (0x79), user envelopes
+				// {"topic" have byte[3]='o' - skip JSON.parse for non-control messages.
+					if (!isBinary && buf.byteLength < 512 && buf[3] === 0x79) {
 						try {
 							const msg = JSON.parse(buf.toString());
 							if (msg.type === 'subscribe' && typeof msg.topic === 'string') {