svelte-adapter-uws 0.4.6 → 0.4.7

package/README.md

@@ -1237,7 +1237,7 @@ await ready();
 // connection is now open, safe to send messages
 ```
 
-In SSR (no browser WebSocket), `ready()` resolves immediately and is a no-op.
+In SSR (no browser WebSocket and no explicit `url`), `ready()` resolves immediately and is a no-op. In native app environments where `window` doesn't exist but you passed a `url` to `connect()`, `ready()` correctly waits for the connection to open.
 
 `ready()` rejects if the connection is permanently closed before it opens. This happens when the server sends a terminal close code (1008/4401/4403), retries are exhausted, or `close()` is called explicitly. If you call `ready()` in a context where permanent closure is possible, add a `.catch()` handler or use `try/await/catch`.
 
@@ -1251,6 +1251,7 @@ Most users don't need this - `on()` and `status` auto-connect. Use `connect()` w
 import { connect } from 'svelte-adapter-uws/client';
 
 const ws = connect({
+  url: 'wss://my-app.com/ws', // full URL for cross-origin / native app usage (overrides path)
   path: '/ws',               // default: '/ws'
   reconnectInterval: 3000,   // default: 3000 ms
   maxReconnectInterval: 30000, // default: 30000 ms
@@ -1294,6 +1295,22 @@ The client handles several edge cases automatically, with no configuration requi
 
 **Zombie detection**: the client checks every 30 seconds whether the server has been completely silent for more than 150 seconds (2.5x the server's idle timeout). If so, it forces a close and reconnects. This catches connections that appear open but were silently dropped by the server, which is common on mobile after wake from sleep.
 
+### Cross-origin and native app usage
+
+By default, the client derives the WebSocket URL from `window.location`. If your client runs on a different origin -- a mobile app (Svelte Native, React Native), a standalone Node.js script, or any context where the backend lives elsewhere -- pass a `url` to connect to it directly:
+
+```js
+import { connect, on } from 'svelte-adapter-uws/client';
+
+connect({ url: 'wss://my-app.com/ws' });
+
+const todos = on('todos');
+```
+
+When `url` is set, `path` is ignored and the `window` check is bypassed, so the client works in environments without a browser DOM. All other features (reconnect, backoff, batch resubscription, topic stores) work the same way.
+
+> **Note:** Your server's `allowedOrigins` config must include the origin your client connects from (or `'*'` during development). See the [origin validation](#origin-validation) section.
+
 ---
 
 ## Seeding initial state
@@ -2870,6 +2887,32 @@ Or if you're using `on()` directly (which auto-connects), call `connect()` first
 
 ---
 
+## Testing
+
+```bash
+npm test              # 711 unit tests (vitest, ~2s)
+npm run test:e2e      # 25 e2e tests (playwright, ~13s)
+npm run test:coverage # both + coverage reports (~30s)
+```
+
+Unit tests cover store patterns, adapter options, plugin logic, and client behavior using mocked WebSocket globals. They run in vitest with the `vmForks` pool.
+
+E2e tests start a real SvelteKit app (`test/fixture/`) with the adapter installed via `file:../..`. Playwright runs two projects:
+
+- **dev** -- `vite dev` with the Vite plugin. Tests SSR, static files, WebSocket pub/sub (via `ws` clients), and the real `client.js` running in Chromium.
+- **prod** -- `vite build` + `node build/index.js` through uWebSockets.js. Tests the same surface against the production runtime, plus the health check endpoint and 404 handling.
+
+The coverage script collects V8 coverage from both the Playwright server processes (vite.js, handler.js) and the browser (client.js via Chrome DevTools Protocol), then reports them alongside the vitest unit coverage.
+
+First-time setup for e2e:
+
+```bash
+cd test/fixture && npm install && cd ../..
+npx playwright install chromium
+```
+
+---
+
 ## Related projects
 
 - [svelte-adapter-uws-extensions](https://github.com/lanteanio/svelte-adapter-uws-extensions) -- Redis-backed extensions for multi-server deployments: persistent presence, distributed pub/sub, session storage, and more.

package/client.d.ts

@@ -1,6 +1,14 @@
 import type { Readable } from 'svelte/store';
 
 export interface ConnectOptions {
+	/**
+	 * Full WebSocket URL to connect to.
+	 * When set, `path` is ignored and the client connects to this URL directly.
+	 * Enables cross-origin usage (e.g. svelte-native, React Native, standalone clients).
+	 * @example 'wss://my-app.com/ws'
+	 */
+	url?: string;
+
 	/**
 	 * WebSocket endpoint path. Must match the adapter config.
 	 * @default '/ws'

package/client.js

@@ -132,9 +132,7 @@ export const status = {
  * @returns {Promise<void>}
  */
 export function ready() {
-	// In non-browser environments (SSR) there is no WebSocket and status
-	// will never reach 'open'. Resolve immediately so await ready() is a no-op.
-	if (typeof window === 'undefined') return Promise.resolve();
+	if (typeof window === 'undefined' && !(singleton && singleton._hasUrl)) return Promise.resolve();
 
 	const conn = ensureConnection();
 	return new Promise((resolve, reject) => {
@@ -506,6 +504,7 @@ const THROTTLE_CLOSE_CODES = new Set([
  */
 function createConnection(options) {
 	const {
+		url,
 		path = '/ws',
 		reconnectInterval = 3000,
 		maxReconnectInterval = 30000,
@@ -565,13 +564,14 @@ function createConnection(options) {
 	const permaClosedStore = writable(false);
 
 	function getUrl() {
+		if (url) return url;
 		if (typeof window === 'undefined') return '';
 		const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
 		return `${protocol}//${window.location.host}${path}`;
 	}
 
 	function doConnect() {
-		if (typeof window === 'undefined') return;
+		if (!url && typeof window === 'undefined') return;
 		if (ws && (ws.readyState === WebSocket.CONNECTING || ws.readyState === WebSocket.OPEN)) return;
 
 		statusStore.set('connecting');
@@ -1006,6 +1006,7 @@ function createConnection(options) {
 		events: { subscribe: eventsStore.subscribe },
 		status: { subscribe: statusStore.subscribe },
 		_permaClosed: { subscribe: permaClosedStore.subscribe },
+		_hasUrl: !!url,
 		on: onTopic,
 		_onEvent: onEvent,
 		_release: release,

package/files/handler.js

@@ -408,7 +408,7 @@ 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) + '}';
+		const envelope = envelopePrefix(topic, event) + JSON.stringify(data ?? null) + '}';
 		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
@@ -433,7 +433,7 @@ const platform = {
 	 * Wraps in the same { topic, event, data } envelope as publish().
 	 */
 	send(ws, topic, event, data) {
-		return ws.send(envelopePrefix(topic, event) + JSON.stringify(data) + '}', false, false);
+		return ws.send(envelopePrefix(topic, event) + JSON.stringify(data ?? null) + '}', false, false);
 	},
 
 	/**
@@ -442,7 +442,7 @@ const platform = {
 	 * Returns the number of connections the message was sent to.
 	 */
 	sendTo(filter, topic, event, data) {
-		const envelope = envelopePrefix(topic, event) + JSON.stringify(data) + '}';
+		const envelope = envelopePrefix(topic, event) + JSON.stringify(data ?? null) + '}';
 		let count = 0;
 		for (const ws of wsConnections) {
 			if (filter(ws.getUserData())) {
@@ -1381,8 +1381,11 @@ if (WS_ENABLED) {
 					upgradeRateMap.set(clientIp, rateEntry);
 				} else {
 					const elapsed = now - rateEntry.windowStart;
-					if (elapsed >= UPGRADE_WINDOW_MS) {
-						// Current window is complete  - rotate it into the previous slot
+					if (elapsed >= 2 * UPGRADE_WINDOW_MS) {
+						rateEntry.prev = 0;
+						rateEntry.curr = 0;
+						rateEntry.windowStart = now;
+					} else if (elapsed >= UPGRADE_WINDOW_MS) {
 						rateEntry.prev = rateEntry.curr;
 						rateEntry.curr = 0;
 						rateEntry.windowStart = now;
@@ -1423,7 +1426,7 @@ if (WS_ENABLED) {
 						const parsed = new URL(reqOrigin);
 						const requestHost = (host_header && headers[host_header]) || headers['host'];
 						if (!requestHost) {
-							allowed = true;
+							allowed = false;
 						} else {
 							const requestScheme = protocol_header
 								? (headers[protocol_header] || (is_tls ? 'https' : 'http'))

package/files/index.js

@@ -4,9 +4,19 @@ import { fileURLToPath } from 'node:url';
 import { env } from 'ENV';
 
 const host = env('HOST', '0.0.0.0');
-const port = env('PORT', '3000');
-const shutdown_timeout = parseInt(env('SHUTDOWN_TIMEOUT', '30'), 10);
-const shutdown_delay = parseInt(env('SHUTDOWN_DELAY_MS', '0'), 10);
+const port_raw = env('PORT', '3000');
+
+function parseIntEnv(name, raw, min) {
+	const trimmed = raw.trim();
+	const n = Number(trimmed);
+	if (trimmed === '' || !Number.isInteger(n)) throw new Error(`${name} must be a valid integer, got "${raw}"`);
+	if (n < min) throw new Error(`${name} must be >= ${min}, got ${n}`);
+	return n;
+}
+
+const port = parseIntEnv('PORT', port_raw, 0);
+const shutdown_timeout = parseIntEnv('SHUTDOWN_TIMEOUT', env('SHUTDOWN_TIMEOUT', '30'), 0);
+const shutdown_delay = parseIntEnv('SHUTDOWN_DELAY_MS', env('SHUTDOWN_DELAY_MS', '0'), 0);
 const cluster_workers = env('CLUSTER_WORKERS', '');
 
 const is_primary = cluster_workers && isMainThread;
@@ -126,7 +136,7 @@ if (is_primary) {
 				// Start (or resume) listening once a worker is ready to handle requests
 				if (!listening) {
 					listening = true;
-					const portNum = parseInt(port, 10);
+					const portNum = port;
 					acceptorApp.listen(host, portNum, (socket) => {
 						if (socket) {
 							listen_socket = socket;
@@ -256,13 +266,13 @@ if (is_primary) {
 
 	if (isMainThread) {
 		// Single-process mode (no clustering)
-		start(host, parseInt(port, 10));
+		start(host, port);
 	} else {
 		// 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));
+			start(host, port);
 			parentPort.postMessage({ type: 'ready' });
 		} else {
 			// Acceptor: register with the main thread's acceptor app

package/index.js

@@ -102,13 +102,23 @@ export default function (opts = {}) {
 						const allEnv = loadEnv('production', process.cwd(), '');
 						const version = builder.config.kit.version?.name ?? '';
 
+						const aliasMap = { '$lib': libDir };
+						const kitAliases = builder.config.kit.alias;
+						if (kitAliases) {
+							for (const [key, value] of Object.entries(kitAliases)) {
+								if (!(key in aliasMap)) {
+									aliasMap[key] = path.resolve(value);
+								}
+							}
+						}
+
 						await esbuild.build({
 							entryPoints: [path.resolve(handlerFile)],
 							bundle: true,
 							format: 'esm',
 							platform: 'node',
 							outfile: `${tmp}/ws-handler.js`,
-							alias: { '$lib': libDir },
+							alias: aliasMap,
 							packages: 'external',
 							plugins: [{
 								name: 'sveltekit-virtual-modules',
@@ -124,6 +134,9 @@ export default function (opts = {}) {
 										const isPublic = args.path.includes('/public');
 										const isStatic = args.path.includes('/static');
 										if (!isStatic) {
+											if (isPublic) {
+												return { contents: `export const env = new Proxy(process.env, { get(t, k) { return typeof k === 'string' && k.startsWith(${JSON.stringify(publicPrefix)}) ? t[k] : undefined; }, ownKeys(t) { return Object.keys(t).filter(k => k.startsWith(${JSON.stringify(publicPrefix)})); }, has(t, k) { return typeof k === 'string' && k.startsWith(${JSON.stringify(publicPrefix)}) && k in t; }, getOwnPropertyDescriptor(t, k) { if (typeof k === 'string' && k.startsWith(${JSON.stringify(publicPrefix)}) && k in t) return { value: t[k], enumerable: true, configurable: true }; return undefined; } });` };
+											}
 											return { contents: 'export const env = process.env;' };
 										}
 										const entries = Object.entries(allEnv).filter(([k]) =>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-adapter-uws",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "SvelteKit adapter for uWebSockets.js - high-performance C++ HTTP server with built-in WebSocket support",
   "author": "Kevin Radziszewski",
   "license": "MIT",
@@ -98,7 +98,9 @@
   ],
   "scripts": {
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "test:e2e": "npx playwright test --config test/e2e/playwright.config.js",
+    "test:coverage": "node scripts/coverage.js"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -132,8 +134,10 @@
     "websocket"
   ],
   "devDependencies": {
+    "@playwright/test": "^1.59.1",
     "@vitest/coverage-v8": "^4.0.18",
     "autocannon": "^8.0.0",
+    "c8": "^11.0.0",
     "polka": "^0.5.2",
     "socket.io": "^4.8.3",
     "socket.io-client": "^4.8.3",

package/plugins/presence/server.js

@@ -275,6 +275,11 @@ export function createPresence(options = {}) {
 			if (connTopics && connTopics.has(topic)) return;
 
 			const data = select(ws.getUserData());
+			if (!data || typeof data !== 'object') {
+				throw new TypeError(
+					`presence select() must return a plain object, got ${data === null ? 'null' : typeof data}`
+				);
+			}
 			const key = resolveKey(data);
 
 			// Track per-connection

package/plugins/replay/server.js

@@ -205,7 +205,11 @@ export function createReplay(options = {}) {
 		publish(platform, topic, event, data) {
 			const state = getTopic(topic);
 			state.seq++;
-			pushMessage(state, { seq: state.seq, topic, event, data });
+			let snapshot = data;
+			if (data != null && typeof data === 'object') {
+				try { snapshot = structuredClone(data); } catch { snapshot = JSON.parse(JSON.stringify(data)); }
+			}
+			pushMessage(state, { seq: state.seq, topic, event, data: snapshot });
 			return platform.publish(topic, event, data);
 		},
 

package/vite.js

@@ -80,12 +80,22 @@ export default function uws(options = {}) {
 			getBufferedAmount() { return rawWs.bufferedAmount || 0; },
 			getRemoteAddress() {
 				// uWS returns raw binary bytes (4 for IPv4, 16 for IPv6).
-				// Dev only handles IPv4; exotic addresses fall back to text encoding.
 				const ip = rawWs._socket?.remoteAddress || '127.0.0.1';
 				const v4 = ip.replace(/^::ffff:/, '');
 				const parts = v4.split('.');
 				if (parts.length === 4) return new Uint8Array(parts.map(Number)).buffer;
-				return new TextEncoder().encode(ip).buffer;
+				// IPv6: expand :: into zeroes, pack 8 groups into 16 bytes
+				const halves = v4.split('::');
+				const left = halves[0] ? halves[0].split(':') : [];
+				const right = halves.length > 1 && halves[1] ? halves[1].split(':') : [];
+				const pad = Array(8 - left.length - right.length).fill('0');
+				const groups = [...left, ...pad, ...right].map(g => parseInt(g, 16));
+				const buf = new Uint8Array(16);
+				for (let i = 0; i < 8; i++) {
+					buf[i * 2] = (groups[i] >> 8) & 0xff;
+					buf[i * 2 + 1] = groups[i] & 0xff;
+				}
+				return buf.buffer;
 			},
 			getRemoteAddressAsText() {
 				return new TextEncoder().encode(rawWs._socket?.remoteAddress || '127.0.0.1').buffer;
@@ -103,7 +113,7 @@ export default function uws(options = {}) {
 	 * @returns {boolean}
 	 */
 	function publish(topic, event, data, _options) {
-		const envelope = '{"topic":' + esc(topic) + ',"event":' + esc(event) + ',"data":' + JSON.stringify(data) + '}';
+		const envelope = '{"topic":' + esc(topic) + ',"event":' + esc(event) + ',"data":' + JSON.stringify(data ?? null) + '}';
 		let sent = false;
 		for (const [ws, topics] of subscriptions) {
 			if (topics.has(topic) && ws.readyState === 1) {
@@ -123,7 +133,7 @@ export default function uws(options = {}) {
 	 * @returns {number}
 	 */
 	function send(ws, topic, event, data) {
-		return ws.send('{"topic":' + esc(topic) + ',"event":' + esc(event) + ',"data":' + JSON.stringify(data) + '}', false, false) ?? 1;
+		return ws.send('{"topic":' + esc(topic) + ',"event":' + esc(event) + ',"data":' + JSON.stringify(data ?? null) + '}', false, false) ?? 1;
 	}
 
 	/**
@@ -135,7 +145,7 @@ export default function uws(options = {}) {
 	 * @returns {number}
 	 */
 	function sendTo(filter, topic, event, data) {
-		const envelope = '{"topic":' + esc(topic) + ',"event":' + esc(event) + ',"data":' + JSON.stringify(data) + '}';
+		const envelope = '{"topic":' + esc(topic) + ',"event":' + esc(event) + ',"data":' + JSON.stringify(data ?? null) + '}';
 		let count = 0;
 		for (const [, wrapped] of wsWrappers) {
 			if (filter(wrapped.getUserData())) {
@@ -198,7 +208,8 @@ export default function uws(options = {}) {
 			message: mod.message,
 			close: mod.close,
 			drain: mod.drain,
-			subscribe: mod.subscribe
+			subscribe: mod.subscribe,
+			unsubscribe: mod.unsubscribe
 		};
 	}
 
@@ -480,7 +491,8 @@ export default function uws(options = {}) {
 					mod.message !== userHandlers.message ||
 					mod.close !== userHandlers.close ||
 					mod.drain !== userHandlers.drain ||
-					mod.subscribe !== userHandlers.subscribe) {
+					mod.subscribe !== userHandlers.subscribe ||
+					mod.unsubscribe !== userHandlers.unsubscribe) {
 					applyHandlers(mod);
 					// Close existing connections so they reconnect with the new handler.
 					// 1012 = "Service Restart" - clients with auto-reconnect will reconnect.