svelte-adapter-uws 0.3.4 → 0.3.6

package/README.md

@@ -419,6 +419,7 @@ If you set `envPrefix: 'MY_APP_'` in the adapter config, all variables are prefi
 | `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 threads (or `auto` for CPU count) |
+| `CLUSTER_MODE` | *(auto)* | `reuseport` (Linux default) or `acceptor` (other platforms) |
 
 ### Graceful shutdown
 
@@ -2130,7 +2131,7 @@ docker run -p 3000:3000 \
 
 ## Clustering
 
-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).
+The adapter supports multi-core scaling with two modes, auto-selected based on platform.
 
 Set the `CLUSTER_WORKERS` environment variable to enable it:
 
@@ -2147,6 +2148,21 @@ 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.
 
+### Clustering modes
+
+**`reuseport`** (Linux default) -- each worker binds to the same port via `SO_REUSEPORT`. The kernel distributes incoming connections across all listening workers. There is no single-threaded acceptor bottleneck and no single point of failure -- one worker crashing does not affect the others.
+
+**`acceptor`** (macOS/Windows default) -- a primary thread creates an acceptor app that receives all connections and distributes them to worker threads via uWS child app descriptors. Works on all platforms.
+
+The mode is auto-detected. Override it explicitly if needed:
+
+```bash
+# Force acceptor mode on Linux (e.g. for debugging)
+CLUSTER_MODE=acceptor CLUSTER_WORKERS=auto node build
+```
+
+Setting `CLUSTER_MODE=reuseport` on non-Linux platforms is an error (SO_REUSEPORT is not reliable outside Linux).
+
 ### 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.
@@ -2158,6 +2174,35 @@ Per-worker limitations (acceptable for most apps):
 - `platform.subscribers(topic)`  - returns the count for the local worker only
 - `platform.sendTo(filter, ...)`  - only reaches connections on the local worker
 
+### Docker / multi-process deployments (Linux)
+
+On Linux, `SO_REUSEPORT` is set on every `app.listen()` call -- including single-process mode. This means multiple independent `node build` processes can bind to the same port without any adapter-level clustering. The kernel distributes connections across them.
+
+If you already have external pub/sub (Redis, Postgres LISTEN/NOTIFY) handling cross-process messaging, you do not need `CLUSTER_WORKERS` at all. Just run multiple replicas and let your infrastructure handle the rest:
+
+```yaml
+# docker-compose.yml
+services:
+  app:
+    build: .
+    command: node build
+    network_mode: host
+    environment:
+      - PORT=443
+      - SSL_CERT=/certs/cert.pem
+      - SSL_KEY=/certs/key.pem
+    deploy:
+      replicas: 4
+```
+
+Each replica is a plain single-process `node build`. No coordinator thread, no built-in relay. Docker handles restarts, Redis handles cross-process messaging, the kernel handles port sharing.
+
+With `network_mode: host`, containers share the host network stack directly -- no port mapping needed, and services like Postgres and Redis are reachable via `127.0.0.1`. This avoids Docker bridge DNS and gives the best network performance.
+
+**When to use what:**
+- **`CLUSTER_WORKERS`** -- single-machine deployments without Docker/k8s/systemd managing processes for you
+- **Docker replicas** -- production deployments where your infrastructure already handles process management and you have external pub/sub for cross-process messaging
+
 ---
 
 ## Performance

package/files/index.js

@@ -1,5 +1,5 @@
 import process from 'node:process';
-import { isMainThread, parentPort, threadId, Worker } from 'node:worker_threads';
+import { isMainThread, parentPort, threadId, Worker, workerData } from 'node:worker_threads';
 import { fileURLToPath } from 'node:url';
 import { env } from 'ENV';
 
@@ -11,10 +11,9 @@ const cluster_workers = env('CLUSTER_WORKERS', '');
 const is_primary = cluster_workers && isMainThread;
 
 if (is_primary) {
-	// ── Primary thread: accept connections, distribute to worker threads ──
+	// ── Primary thread: spawn workers, coordinate shutdown ──
 
 	const { availableParallelism } = await import('node:os');
-	const uWS = (await import('uWebSockets.js')).default;
 
 	const num = cluster_workers === 'auto'
 		? availableParallelism()
@@ -25,16 +24,40 @@ if (is_primary) {
 		process.exit(1);
 	}
 
-	// Acceptor app must match worker SSL mode
+	// On Linux, uWS sets SO_REUSEPORT by default so each worker can bind
+	// to the same port independently and the kernel distributes connections.
+	// No single-threaded acceptor bottleneck, no single point of failure.
+	// On other platforms, fall back to the acceptor model (main thread
+	// accepts connections and distributes them to workers via descriptors).
+	const cluster_mode = env('CLUSTER_MODE', process.platform === 'linux' ? 'reuseport' : 'acceptor');
+
+	if (cluster_mode === 'reuseport' && process.platform !== 'linux') {
+		console.error(
+			`CLUSTER_MODE=reuseport requires Linux (SO_REUSEPORT is not reliable on ${process.platform}). ` +
+			'Remove CLUSTER_MODE to use the default acceptor mode.'
+		);
+		process.exit(1);
+	}
+
+	if (cluster_mode !== 'reuseport' && cluster_mode !== 'acceptor') {
+		console.error(`Invalid CLUSTER_MODE: '${cluster_mode}'. Use 'reuseport' or 'acceptor'.`);
+		process.exit(1);
+	}
+
+	// Acceptor mode needs a uWS app to receive and distribute connections
 	const ssl_cert = env('SSL_CERT', '');
 	const ssl_key = env('SSL_KEY', '');
 	const is_tls = !!(ssl_cert && ssl_key);
 
-	const acceptorApp = is_tls
-		? uWS.SSLApp({ cert_file_name: ssl_cert, key_file_name: ssl_key })
-		: uWS.App();
+	let uWS, acceptorApp;
+	if (cluster_mode === 'acceptor') {
+		uWS = (await import('uWebSockets.js')).default;
+		acceptorApp = is_tls
+			? uWS.SSLApp({ cert_file_name: ssl_cert, key_file_name: ssl_key })
+			: uWS.App();
+	}
 
-	console.log(`Primary thread starting ${num} workers...`);
+	console.log(`Primary thread starting ${num} workers (${cluster_mode} mode)...`);
 
 	/** @type {Map<import('node:worker_threads').Worker, any>} */
 	const workers = new Map();
@@ -51,11 +74,13 @@ if (is_primary) {
 	const restart_timers = new Set();
 
 	function spawn_worker() {
-		const worker = new Worker(fileURLToPath(import.meta.url));
+		const worker = new Worker(fileURLToPath(import.meta.url), {
+			workerData: { mode: cluster_mode }
+		});
 		workers.set(worker, null);
 
 		worker.on('message', (msg) => {
-			if (msg.type === 'descriptor') {
+			if (msg.type === 'descriptor' && cluster_mode === 'acceptor') {
 				workers.set(worker, msg.descriptor);
 				acceptorApp.addChildAppDescriptor(msg.descriptor);
 				console.log(`Worker thread ${worker.threadId} registered`);
@@ -78,6 +103,12 @@ if (is_primary) {
 						}
 					});
 				}
+			} else if (msg.type === 'ready' && cluster_mode === 'reuseport') {
+				console.log(`Worker thread ${worker.threadId} listening on :${port}`);
+				restart_delay = 0;
+				restart_attempts = 0;
+				for (const t of restart_timers) clearTimeout(t);
+				restart_timers.clear();
 			} else if (msg.type === 'publish') {
 				// Relay pub/sub to all OTHER workers
 				for (const [w] of workers) {
@@ -87,20 +118,26 @@ if (is_primary) {
 		});
 
 		worker.on('exit', (code) => {
-			const descriptor = workers.get(worker);
-			if (descriptor) {
-				try { acceptorApp.removeChildAppDescriptor(descriptor); } catch {}
+			if (cluster_mode === 'acceptor') {
+				const descriptor = workers.get(worker);
+				if (descriptor) {
+					try { acceptorApp.removeChildAppDescriptor(descriptor); } catch {}
+				}
 			}
 			workers.delete(worker);
 			if (!shutting_down) {
-				// If no workers have descriptors, stop accepting connections so
+				// In acceptor mode, stop accepting when all workers are down so
 				// clients get a clean connection-refused instead of an empty app.
-				const has_live_worker = [...workers.values()].some(d => d !== null);
-				if (!has_live_worker && listen_socket) {
-					uWS.us_listen_socket_close(listen_socket);
-					listen_socket = null;
-					listening = false;
-					console.log('All workers down, acceptor paused until a replacement is ready');
+				// In reuseport mode, each worker owns its listen socket -- when
+				// it dies, the kernel stops routing to it automatically.
+				if (cluster_mode === 'acceptor') {
+					const has_live_worker = [...workers.values()].some(d => d !== null);
+					if (!has_live_worker && listen_socket) {
+						uWS.us_listen_socket_close(listen_socket);
+						listen_socket = null;
+						listening = false;
+						console.log('All workers down, acceptor paused until a replacement is ready');
+					}
 				}
 				restart_attempts++;
 				if (restart_attempts > RESTART_MAX_ATTEMPTS) {
@@ -139,8 +176,8 @@ if (is_primary) {
 		for (const t of restart_timers) clearTimeout(t);
 		restart_timers.clear();
 
-		// Stop accepting new connections
-		if (listen_socket) {
+		// Stop accepting new connections (acceptor mode only)
+		if (cluster_mode === 'acceptor' && listen_socket) {
 			uWS.us_listen_socket_close(listen_socket);
 			listen_socket = null;
 		}
@@ -168,8 +205,16 @@ if (is_primary) {
 		// Single-process mode (no clustering)
 		start(host, parseInt(port, 10));
 	} else {
-		// Worker thread  - register with acceptor, don't listen
-		parentPort.postMessage({ type: 'descriptor', descriptor: getDescriptor() });
+		// Worker thread startup depends on clustering mode
+		if (workerData?.mode === 'reuseport') {
+			// Reuseport: each worker listens on the shared port directly.
+			// The kernel distributes incoming connections via SO_REUSEPORT.
+			start(host, parseInt(port, 10));
+			parentPort.postMessage({ type: 'ready' });
+		} else {
+			// Acceptor: register with the main thread's acceptor app
+			parentPort.postMessage({ type: 'descriptor', descriptor: getDescriptor() });
+		}
 
 		parentPort.on('message', (msg) => {
 			if (msg.type === 'shutdown') {

package/index.d.ts

@@ -21,6 +21,7 @@ import type { WebSocket } from 'uWebSockets.js';
  * | `BODY_SIZE_LIMIT` | `512K` | Max request body size (`K`, `M`, `G` suffixes) |
  * | `SHUTDOWN_TIMEOUT` | `30` | Seconds to wait during graceful shutdown |
  * | `CLUSTER_WORKERS` | - | Number of worker threads (`'auto'` for CPU count) |
+ * | `CLUSTER_MODE` | *(auto)* | `'reuseport'` (Linux default) or `'acceptor'` (other platforms) |
  *
  * All variables respect the `envPrefix` option (e.g. `MY_APP_PORT` if `envPrefix: 'MY_APP_'`).
  *
@@ -31,8 +32,17 @@ import type { WebSocket } from 'uWebSockets.js';
  * CLUSTER_WORKERS=4 node build       # fixed 4 workers
  * ```
  *
- * Uses uWebSockets.js worker thread distribution (acceptor app + child app descriptors).
- * Works on **all platforms** (Linux, macOS, Windows). Workers auto-restart on crash.
+ * Two clustering modes are available:
+ *
+ * - **`reuseport`** (Linux default) - each worker binds to the same port via `SO_REUSEPORT`.
+ *   The kernel distributes incoming connections across workers. No single-threaded acceptor
+ *   bottleneck, no single point of failure. One worker crashing does not affect others.
+ *
+ * - **`acceptor`** (macOS/Windows default) - a primary thread accepts all connections and
+ *   distributes them to workers via uWS child app descriptors. Works on all platforms.
+ *
+ * The mode is auto-detected from the platform. Override with `CLUSTER_MODE=acceptor` or
+ * `CLUSTER_MODE=reuseport` (reuseport requires Linux). Workers auto-restart on crash.
  *
  * **WebSocket + clustering:** `publish()` is automatically relayed across all workers.
  * `sendTo()`, `connections`, and `subscribers()` operate on the local worker only.

package/package.json

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