svelte-adapter-uws 0.1.0

package/files/index.js

@@ -0,0 +1,116 @@
+import process from 'node:process';
+import { env } from 'ENV';
+
+/* global WS_ENABLED */
+
+const host = env('HOST', '0.0.0.0');
+const port = env('PORT', '3000');
+const shutdown_timeout = parseInt(env('SHUTDOWN_TIMEOUT', '30'), 10);
+const cluster_workers = env('CLUSTER_WORKERS', '');
+
+const is_primary = cluster_workers
+	&& process.platform === 'linux'
+	&& !WS_ENABLED
+	&& process.env.__UWS_WORKER !== '1';
+
+if (is_primary) {
+	// ── Primary process: fork workers, monitor, restart ─────────────────────
+
+	const { availableParallelism } = await import('node:os');
+	const { fork } = await import('node:child_process');
+
+	const num = cluster_workers === 'auto'
+		? availableParallelism()
+		: parseInt(cluster_workers, 10);
+
+	if (isNaN(num) || num < 1) {
+		console.error(`Invalid CLUSTER_WORKERS value: '${cluster_workers}'. Use a positive integer or 'auto'.`);
+		process.exit(1);
+	}
+
+	console.log(`Primary process ${process.pid} starting ${num} workers...`);
+
+	/** @type {Set<import('node:child_process').ChildProcess>} */
+	const workers = new Set();
+	let shutting_down = false;
+
+	function spawn_worker() {
+		const worker = fork(process.argv[1], {
+			env: { ...process.env, __UWS_WORKER: '1' }
+		});
+		workers.add(worker);
+		worker.on('exit', (code) => {
+			workers.delete(worker);
+			if (!shutting_down) {
+				console.log(`Worker ${worker.pid} exited with code ${code}, restarting...`);
+				spawn_worker();
+			}
+		});
+	}
+
+	for (let i = 0; i < num; i++) {
+		spawn_worker();
+	}
+
+	/** @param {'SIGINT' | 'SIGTERM'} reason */
+	function graceful_shutdown(reason) {
+		if (shutting_down) return;
+		shutting_down = true;
+		console.log(`Primary received ${reason}, shutting down ${workers.size} workers...`);
+		for (const worker of workers) {
+			worker.kill(reason);
+		}
+		setTimeout(() => {
+			for (const worker of workers) {
+				worker.kill('SIGKILL');
+			}
+			process.exit(0);
+		}, shutdown_timeout * 1000).unref();
+	}
+
+	process.on('SIGTERM', () => graceful_shutdown('SIGTERM'));
+	process.on('SIGINT', () => graceful_shutdown('SIGINT'));
+} else {
+	// ── Worker (single-process or forked child) ─────────────────────────────
+
+	if (cluster_workers && !WS_ENABLED && process.platform !== 'linux') {
+		console.warn(
+			`Warning: CLUSTER_WORKERS is only supported on Linux (current platform: ${process.platform}).\n` +
+			'Starting in single-process mode.'
+		);
+	}
+	if (cluster_workers && WS_ENABLED) {
+		console.warn(
+			'Warning: CLUSTER_WORKERS is ignored when WebSocket is enabled.\n' +
+			'uWS pub/sub is per-process - clustering would cause missed messages.\n' +
+			'Starting in single-process mode.'
+		);
+	}
+
+	const { start, shutdown, drain } = await import('HANDLER');
+
+	start(host, parseInt(port, 10));
+
+	let shutting_down = false;
+
+	/** @param {'SIGINT' | 'SIGTERM'} reason */
+	async function graceful_shutdown(reason) {
+		if (shutting_down) return;
+		shutting_down = true;
+		console.log(`Received ${reason}, shutting down gracefully...`);
+		shutdown();
+		// @ts-expect-error custom events cannot be typed
+		process.emit('sveltekit:shutdown', reason);
+		await Promise.race([
+			drain(),
+			new Promise((resolve) => setTimeout(resolve, shutdown_timeout * 1000).unref())
+		]);
+		console.log('Shutdown complete, exiting.');
+		process.exit(0);
+	}
+
+	process.on('SIGTERM', () => graceful_shutdown('SIGTERM'));
+	process.on('SIGINT', () => graceful_shutdown('SIGINT'));
+}
+
+export { host, port };

package/files/shims.js

@@ -0,0 +1,21 @@
+import buffer from 'node:buffer';
+import { webcrypto } from 'node:crypto';
+
+const File = /** @type {import('node:buffer') & { File?: File}} */ (buffer).File;
+
+/** @type {Record<string, any>} */
+const globals = {
+	crypto: webcrypto,
+	File
+};
+
+for (const name in globals) {
+	if (name in globalThis) continue;
+
+	Object.defineProperty(globalThis, name, {
+		enumerable: true,
+		configurable: true,
+		writable: true,
+		value: globals[name]
+	});
+}

package/files/utils.js

@@ -0,0 +1,136 @@
+// ── MIME types ──────────────────────────────────────────────────────────────────
+
+export const mimes = {
+	"3g2": "video/3gpp2", "3gp": "video/3gpp", "3gpp": "video/3gpp", "3mf": "model/3mf",
+	"aac": "audio/aac", "apng": "image/apng", "avif": "image/avif",
+	"bin": "application/octet-stream", "bmp": "image/bmp",
+	"cjs": "application/node", "css": "text/css", "csv": "text/csv",
+	"eot": "application/vnd.ms-fontobject", "epub": "application/epub+zip",
+	"gif": "image/gif", "glb": "model/gltf-binary", "gltf": "model/gltf+json",
+	"gz": "application/gzip",
+	"heic": "image/heic", "heif": "image/heif", "htm": "text/html", "html": "text/html",
+	"ico": "image/x-icon", "ics": "text/calendar",
+	"jar": "application/java-archive", "jpeg": "image/jpeg", "jpg": "image/jpeg",
+	"js": "text/javascript", "json": "application/json", "jsonld": "application/ld+json",
+	"map": "application/json", "md": "text/markdown", "mid": "audio/midi", "midi": "audio/midi",
+	"mjs": "text/javascript", "mp3": "audio/mpeg", "mp4": "video/mp4", "mpeg": "video/mpeg",
+	"oga": "audio/ogg", "ogg": "audio/ogg", "ogv": "video/ogg", "opus": "audio/ogg",
+	"otf": "font/otf",
+	"pdf": "application/pdf", "png": "image/png",
+	"rtf": "text/rtf",
+	"svg": "image/svg+xml", "svgz": "image/svg+xml",
+	"tif": "image/tiff", "tiff": "image/tiff", "toml": "application/toml",
+	"ts": "video/mp2t", "ttc": "font/collection", "ttf": "font/ttf", "txt": "text/plain",
+	"vtt": "text/vtt",
+	"wasm": "application/wasm", "wav": "audio/wav", "weba": "audio/webm",
+	"webm": "video/webm", "webmanifest": "application/manifest+json", "webp": "image/webp",
+	"woff": "font/woff", "woff2": "font/woff2",
+	"xhtml": "application/xhtml+xml", "xml": "text/xml",
+	"yaml": "text/yaml", "yml": "text/yaml", "zip": "application/zip"
+};
+
+/**
+ * @param {string} name
+ * @returns {string}
+ */
+export function mimeLookup(name) {
+	const idx = name.lastIndexOf('.');
+	return mimes[idx !== -1 ? name.substring(idx + 1).toLowerCase() : ''] || 'application/octet-stream';
+}
+
+// ── splitCookiesString ───────────────────────────────────────────────────────
+// Adapted from set-cookie-parser (https://github.com/nfriedly/set-cookie-parser)
+// Copyright (c) Nathan Friedly - MIT License
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function splitCookiesString(cookiesString) {
+	if (Array.isArray(cookiesString)) return cookiesString;
+	if (typeof cookiesString !== 'string') return [];
+
+	const cookiesStrings = [];
+	let pos = 0;
+	let start, ch, lastComma, nextStart, cookiesSeparatorFound;
+
+	function skipWhitespace() {
+		while (pos < cookiesString.length && /\s/.test(cookiesString.charAt(pos))) pos++;
+		return pos < cookiesString.length;
+	}
+
+	function notSpecialChar() {
+		ch = cookiesString.charAt(pos);
+		return ch !== '=' && ch !== ';' && ch !== ',';
+	}
+
+	while (pos < cookiesString.length) {
+		start = pos;
+		cookiesSeparatorFound = false;
+
+		while (skipWhitespace()) {
+			ch = cookiesString.charAt(pos);
+			if (ch === ',') {
+				lastComma = pos;
+				pos++;
+				skipWhitespace();
+				nextStart = pos;
+				while (pos < cookiesString.length && notSpecialChar()) pos++;
+				if (pos < cookiesString.length && cookiesString.charAt(pos) === '=') {
+					cookiesSeparatorFound = true;
+					pos = nextStart;
+					cookiesStrings.push(cookiesString.substring(start, lastComma));
+					start = pos;
+				} else {
+					pos = lastComma + 1;
+				}
+			} else {
+				pos++;
+			}
+		}
+
+		if (!cookiesSeparatorFound || pos >= cookiesString.length) {
+			cookiesStrings.push(cookiesString.substring(start, cookiesString.length));
+		}
+	}
+
+	return cookiesStrings;
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * @param {string} value
+ * @returns {number}
+ */
+export function parse_as_bytes(value) {
+	const str = value.trim();
+	const last = str[str.length - 1]?.toUpperCase();
+	// Strip trailing 'B' (e.g. "512KB" → "512K")
+	const normalized = last === 'B' ? str.slice(0, -1) : str;
+	const suffix = normalized[normalized.length - 1]?.toUpperCase();
+	const multiplier =
+		{ K: 1024, M: 1024 * 1024, G: 1024 * 1024 * 1024 }[suffix] ?? 1;
+	return Number(multiplier !== 1 ? normalized.slice(0, -1) : normalized) * multiplier;
+}
+
+/**
+ * @param {string | undefined} value
+ * @returns {string | undefined}
+ */
+export function parse_origin(value) {
+	if (value === undefined) return undefined;
+	const trimmed = value.trim();
+	let url;
+	try {
+		url = new URL(trimmed);
+	} catch (error) {
+		throw new Error(
+			`Invalid ORIGIN: '${trimmed}'. ORIGIN must be a valid URL with http:// or https:// protocol.`,
+			{ cause: error }
+		);
+	}
+	if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+		throw new Error(
+			`Invalid ORIGIN: '${trimmed}'. Only http:// and https:// protocols are supported.`
+		);
+	}
+	return url.origin;
+}

package/index.d.ts

@@ -0,0 +1,396 @@
+import type { Adapter } from '@sveltejs/kit';
+import type { WebSocket } from 'uWebSockets.js';
+
+/**
+ * ## Environment variables (runtime)
+ *
+ * These are set at runtime, not in the adapter config:
+ *
+ * | Variable | Default | Description |
+ * |---|---|---|
+ * | `HOST` | `0.0.0.0` | Bind address |
+ * | `PORT` | `3000` | Listen port |
+ * | `ORIGIN` | *(derived)* | Fixed origin (e.g. `https://example.com`) |
+ * | `SSL_CERT` | - | Path to TLS certificate file (enables HTTPS/WSS natively) |
+ * | `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`) |
+ * | `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) |
+ * | `SHUTDOWN_TIMEOUT` | `30` | Seconds to wait during graceful shutdown |
+ *
+ * All variables respect the `envPrefix` option (e.g. `MY_APP_PORT` if `envPrefix: 'MY_APP_'`).
+ *
+ * ### Native TLS (no proxy needed)
+ *
+ * ```sh
+ * SSL_CERT=/path/to/cert.pem SSL_KEY=/path/to/key.pem node build
+ * ```
+ *
+ * This uses uWebSockets.js `SSLApp` - HTTPS and WSS with zero proxy overhead.
+ */
+export interface AdapterOptions {
+	/**
+	 * Output directory for the build.
+	 * @default 'build'
+	 */
+	out?: string;
+
+	/**
+	 * Precompress static assets with gzip and brotli.
+	 * @default true
+	 */
+	precompress?: boolean;
+
+	/**
+	 * Prefix for environment variables.
+	 * @default ''
+	 */
+	envPrefix?: string;
+
+	/**
+	 * Health check endpoint path. Set to `false` to disable.
+	 * @default '/healthz'
+	 */
+	healthCheckPath?: string | false;
+
+	/**
+	 * Enable WebSocket support.
+	 *
+	 * - `true` - enable with built-in pub/sub handler (**no auth, no per-topic
+	 *   authorization** - any connected client can subscribe to any topic.
+	 *   Use a custom handler with `upgrade` for auth gating)
+	 * - `WebSocketOptions` - enable with custom config and/or auth handler
+	 *
+	 * @example
+	 * ```js
+	 * // Simplest - just turn it on:
+	 * adapter({ websocket: true })
+	 *
+	 * // With auth:
+	 * adapter({
+	 *   websocket: {
+	 *     handler: './src/lib/server/websocket.js'
+	 *   }
+	 * })
+	 * ```
+	 */
+	websocket?: boolean | WebSocketOptions;
+}
+
+export interface WebSocketOptions {
+	/**
+	 * Path to a JS module that exports WebSocket handler functions
+	 * (`upgrade`, `open`, `message`, `close`).
+	 *
+	 * **Optional.** The adapter auto-discovers `src/hooks.ws.js` (or `.ts`, `.mjs`)
+	 * if it exists - no config needed. If neither a handler path nor a hooks file
+	 * is found, a built-in handler is used that accepts all connections and handles
+	 * subscribe/unsubscribe messages from the client store.
+	 *
+	 * Only specify this if your handler lives at a non-standard path.
+	 *
+	 * @example './src/lib/server/websocket.js'
+	 */
+	handler?: string;
+
+	/**
+	 * URL path to serve WebSocket connections on.
+	 * @default '/ws'
+	 */
+	path?: string;
+
+	/**
+	 * Max message size in bytes. Connections sending larger messages are closed.
+	 * @default 16384 (16 KB)
+	 */
+	maxPayloadLength?: number;
+
+	/**
+	 * Seconds of inactivity before the connection is closed.
+	 * @default 120
+	 */
+	idleTimeout?: number;
+
+	/**
+	 * Max bytes of backpressure before messages are dropped.
+	 * @default 1048576 (1 MB)
+	 */
+	maxBackpressure?: number;
+
+	/**
+	 * Enable per-message deflate compression.
+	 * Pass `true` for `SHARED_COMPRESSOR`, or a uWS compression constant
+	 * (e.g. `uWS.DEDICATED_COMPRESSOR_4KB`) for finer control.
+	 * @default false
+	 */
+	compression?: boolean | number;
+
+	/**
+	 * Automatically send pings to keep the connection alive.
+	 * @default true
+	 */
+	sendPingsAutomatically?: boolean;
+
+	/**
+	 * Allowed origins for WebSocket connections.
+	 *
+	 * - `'same-origin'` - only accept connections where Origin matches Host *(default)*
+	 * - `'*'` - accept connections from any origin
+	 * - `string[]` - whitelist of allowed origin URLs (e.g. `['https://example.com']`)
+	 *
+	 * Non-browser clients (no Origin header) are always allowed.
+	 *
+	 * @default 'same-origin'
+	 */
+	allowedOrigins?: 'same-origin' | '*' | string[];
+}
+
+// ── User's WebSocket handler module exports ─────────────────────────────────
+
+/**
+ * Context passed to the `upgrade` handler.
+ */
+export interface UpgradeContext {
+	/** Request headers (all lowercase keys). */
+	headers: Record<string, string>;
+	/** Parsed cookies from the Cookie header. */
+	cookies: Record<string, string>;
+	/** The request URL path. */
+	url: string;
+	/** Remote IP address. */
+	remoteAddress: string;
+}
+
+/**
+ * Shape of the user's WebSocket handler module.
+ *
+ * Create a file (e.g. `src/lib/server/websocket.js`) and export any
+ * of these functions. All are optional - the built-in handler already
+ * handles subscribe/unsubscribe for the client store.
+ *
+ * @example
+ * ```js
+ * // src/hooks.ws.js - auto-discovered, no config needed
+ *
+ * export function upgrade({ cookies }) {
+ *   if (!cookies.session_id) return false; // reject with 401
+ *   const user = await validateSession(cookies.session_id);
+ *   if (!user) return false;
+ *   return { userId: user.id }; // attach data to socket
+ * }
+ *
+ * export function open(ws) {
+ *   ws.subscribe(`user:${ws.getUserData().userId}`);
+ * }
+ * ```
+ */
+export interface WebSocketHandler<UserData = unknown> {
+	/**
+	 * Called during the HTTP upgrade handshake.
+	 *
+	 * - Return an object to accept - it becomes `ws.getUserData()`.
+	 * - Return `false` to reject with 401.
+	 * - Omit this export to accept all connections with `{}` as user data.
+	 *
+	 * May be async.
+	 */
+	upgrade?: (ctx: UpgradeContext) => UserData | false | Promise<UserData | false>;
+
+	/** Called when a WebSocket connection is established. */
+	open?: (ws: WebSocket<UserData>) => void;
+
+	/**
+	 * Called when a message is received.
+	 *
+	 * **Note:** subscribe/unsubscribe messages from the client store are
+	 * handled automatically before this is called. You only need this for
+	 * custom application-level messages.
+	 */
+	message?: (ws: WebSocket<UserData>, data: ArrayBuffer, isBinary: boolean) => void;
+
+	/**
+	 * Called when a client tries to subscribe to a topic.
+	 *
+	 * - Return `false` to deny the subscription (silently ignored on the client).
+	 * - Return anything else (or omit this export) to allow.
+	 *
+	 * Use this for per-topic authorization - e.g. only let admins subscribe to `'admin'`.
+	 *
+	 * @example
+	 * ```js
+	 * export function subscribe(ws, topic) {
+	 *   const { role } = ws.getUserData();
+	 *   if (topic.startsWith('admin') && role !== 'admin') return false;
+	 * }
+	 * ```
+	 */
+	subscribe?: (ws: WebSocket<UserData>, topic: string) => boolean | void;
+
+	/**
+	 * Called when backpressure has drained (buffered data was sent).
+	 * Use this for flow control when sending large or frequent messages.
+	 */
+	drain?: (ws: WebSocket<UserData>) => void;
+
+	/** Called when the connection closes. */
+	close?: (ws: WebSocket<UserData>, code: number, message: ArrayBuffer) => void;
+}
+
+// ── Platform type for event.platform ────────────────────────────────────────
+
+/**
+ * Available on `event.platform` in server hooks, load functions, and actions.
+ *
+ * To get type-checking, add this to your `src/app.d.ts`:
+ *
+ * ```ts
+ * import type { Platform as AdapterPlatform } from 'svelte-adapter-uws';
+ *
+ * declare global {
+ *   namespace App {
+ *     interface Platform extends AdapterPlatform {}
+ *   }
+ * }
+ * ```
+ */
+export interface Platform {
+	/**
+	 * Publish a message to all WebSocket clients subscribed to a topic.
+	 *
+	 * The message is automatically wrapped in a `{ topic, event, data }` envelope
+	 * that the client store (`svelte-adapter-uws/client`) understands.
+	 *
+	 * @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)
+	 *
+	 * @example
+	 * ```js
+	 * // In a form action or API route:
+	 * export async function POST({ platform }) {
+	 *   const todo = await db.save(data);
+	 *   platform.publish('todos', 'created', todo);
+	 * }
+	 * ```
+	 */
+	publish(topic: string, event: string, data?: unknown): boolean;
+
+	/**
+	 * Send a message to a single WebSocket connection.
+	 * Wraps in the same `{ topic, event, data }` envelope as `publish()`.
+	 *
+	 * @example
+	 * ```js
+	 * // In hooks.ws.js - reply to sender:
+	 * export function message(ws, rawData) {
+	 *   const msg = JSON.parse(Buffer.from(rawData).toString());
+	 *   ws.send(JSON.stringify({ topic: 'echo', event: 'reply', data: { got: msg } }));
+	 * }
+	 * ```
+	 */
+	send(ws: WebSocket<any>, topic: string, event: string, data?: unknown): number;
+
+	/**
+	 * Send a message to all connections whose userData matches a filter.
+	 * Returns the number of connections the message was sent to.
+	 *
+	 * The filter receives each connection's userData (whatever `upgrade()` returned).
+	 *
+	 * @example
+	 * ```js
+	 * // Send to a specific user (no need to maintain your own Map):
+	 * export async function POST({ platform, request }) {
+	 *   const { targetUserId, message } = await request.json();
+	 *   platform.sendTo(
+	 *     (userData) => userData.userId === targetUserId,
+	 *     'dm', 'new-message', { message }
+	 *   );
+	 * }
+	 *
+	 * // Send to all admins:
+	 * platform.sendTo(
+	 *   (userData) => userData.role === 'admin',
+	 *   'alerts', 'warning', { message: 'Server load high' }
+	 * );
+	 * ```
+	 */
+	sendTo(filter: (userData: any) => boolean, topic: string, event: string, data?: unknown): number;
+
+	/**
+	 * Number of active WebSocket connections.
+	 *
+	 * @example
+	 * ```js
+	 * export async function GET({ platform }) {
+	 *   return json({ online: platform.connections });
+	 * }
+	 * ```
+	 */
+	readonly connections: number;
+
+	/**
+	 * Number of clients subscribed to a specific topic.
+	 *
+	 * @example
+	 * ```js
+	 * export async function GET({ platform, params }) {
+	 *   return json({ viewers: platform.subscribers(`page:${params.id}`) });
+	 * }
+	 * ```
+	 */
+	subscribers(topic: string): number;
+
+	/**
+	 * Get a scoped helper for a topic. Reduces repetition when publishing
+	 * multiple events to the same topic, and provides CRUD shorthand methods
+	 * that pair with the client's `crud()` helper.
+	 *
+	 * @param topic - Topic string (e.g. `'todos'`, `'user:123'`)
+	 *
+	 * @example
+	 * ```js
+	 * // In a form action:
+	 * export async function POST({ platform, request }) {
+	 *   const todos = platform.topic('todos');
+	 *   const todo = await db.create(await request.formData());
+	 *   todos.created(todo);   // clients see 'created' event
+	 * }
+	 *
+	 * export const actions = {
+	 *   update: async ({ platform, request }) => {
+	 *     const todos = platform.topic('todos');
+	 *     const todo = await db.update(await request.formData());
+	 *     todos.updated(todo); // clients see 'updated' event
+	 *   },
+	 *   delete: async ({ platform, request }) => {
+	 *     const todos = platform.topic('todos');
+	 *     const id = (await request.formData()).get('id');
+	 *     await db.delete(id);
+	 *     todos.deleted({ id }); // clients see 'deleted' event
+	 *   }
+	 * };
+	 * ```
+	 */
+	topic(topic: string): TopicHelper;
+}
+
+export interface TopicHelper {
+	/** Publish a custom event to this topic. */
+	publish(event: string, data?: unknown): void;
+	/** Shorthand for `.publish('created', data)`. Pairs with `crud()` / `lookup()`. */
+	created(data?: unknown): void;
+	/** Shorthand for `.publish('updated', data)`. Pairs with `crud()` / `lookup()`. */
+	updated(data?: unknown): void;
+	/** Shorthand for `.publish('deleted', data)`. Pairs with `crud()` / `lookup()`. */
+	deleted(data?: unknown): void;
+	/** Shorthand for `.publish('set', value)`. Pairs with `count()`. */
+	set(value: number): void;
+	/** Shorthand for `.publish('increment', amount)`. Pairs with `count()`. */
+	increment(amount?: number): void;
+	/** Shorthand for `.publish('decrement', amount)`. Pairs with `count()`. */
+	decrement(amount?: number): void;
+}
+
+export default function adapter(options?: AdapterOptions): Adapter;