svelte-adapter-uws 0.4.9 → 0.4.10

package/README.md

@@ -9,6 +9,7 @@ I've been loving Svelte and SvelteKit for a long time. I always wanted to expand
 - **HTTP & HTTPS** - native TLS via uWebSockets.js `SSLApp`, no reverse proxy needed
 - **WebSocket & WSS** - built-in pub/sub with a reactive Svelte client store
 - **In-memory static file cache** - assets loaded once at startup, served from RAM with precompressed brotli/gzip variants
+- **Dynamic response compression** - SSR HTML and API JSON compressed on the fly with brotli or gzip
 - **Backpressure handling** - streaming responses that won't blow up memory
 - **Graceful shutdown** - waits for in-flight requests before exiting
 - **Health check endpoint** - `/healthz` out of the box
@@ -725,6 +726,8 @@ export async function upgrade({ cookies }) {
   if (!user) return false; // -> 401, expired or invalid session
 
   // Attach user data to the socket - available via ws.getUserData()
+  // To also set response headers on the 101 (e.g. refresh session cookie):
+  // return upgradeResponse({ userId: user.id }, { 'set-cookie': '...' });
   return { userId: user.id, name: user.name, role: user.role };
 }
 
@@ -2925,12 +2928,12 @@ Or if you're using `on()` directly (which auto-connects), call `connect()` first
 ## Testing
 
 ```bash
-npm test              # 711 unit tests (vitest, ~2s)
+npm test              # 777 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.
+Unit tests cover store patterns, adapter options, plugin logic, client behavior, and the WebSocket test harness. 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:
 
@@ -2946,6 +2949,51 @@ cd test/fixture && npm install && cd ../..
 npx playwright install chromium
 ```
 
+### Test harness for WebSocket handlers
+
+The `svelte-adapter-uws/testing` entry point provides `createTestServer()` for integration-testing your `hooks.ws` handlers against a real uWebSockets.js server:
+
+```js
+import { createTestServer } from 'svelte-adapter-uws/testing';
+import { WebSocket } from 'ws';
+import { describe, it, expect, afterEach } from 'vitest';
+import * as myHandler from '../src/hooks.ws.js';
+
+let server;
+afterEach(() => server?.close());
+
+it('rejects unauthenticated upgrades', async () => {
+  server = await createTestServer({ handler: myHandler });
+
+  const ws = new WebSocket(server.wsUrl);
+  const code = await new Promise((resolve) => {
+    ws.on('unexpected-response', (_, res) => resolve(res.statusCode));
+    ws.on('open', () => resolve('open'));
+  });
+  expect(code).toBe(401);
+});
+
+it('publishes to subscribers', async () => {
+  server = await createTestServer({ handler: myHandler });
+
+  const ws = new WebSocket(server.wsUrl, {
+    headers: { cookie: 'session=valid-token' }
+  });
+  await new Promise(r => ws.on('open', r));
+
+  ws.send(JSON.stringify({ type: 'subscribe', topic: 'todos' }));
+  await new Promise(r => setTimeout(r, 10));
+
+  const msg = new Promise(r => ws.on('message', d => r(JSON.parse(d.toString()))));
+  server.platform.publish('todos', 'created', { id: 1 });
+  expect(await msg).toMatchObject({ topic: 'todos', event: 'created' });
+
+  ws.close();
+});
+```
+
+The test server starts on a random port (typically in ~2ms), uses the same subscribe/unsubscribe protocol as production, and exposes the full Platform API (`publish`, `send`, `sendTo`, `topic`, `connections`, `subscribers`).
+
 ---
 
 ## Related projects

package/files/handler.js

@@ -3,6 +3,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Readable } from 'node:stream';
+import { performance } from 'node:perf_hooks';
+import { brotliCompressSync, gzipSync, constants as zlibConstants } from 'node:zlib';
 import { parentPort } from 'node:worker_threads';
 import uWS from 'uWebSockets.js';
 import { Server } from 'SERVER';
@@ -281,8 +283,10 @@ function cacheDir(dir, urlPrefix, immutable) {
 const clientDir = path.join(__dirname, 'client');
 const prerenderedDir = path.join(__dirname, 'prerendered');
 
+const _t_static = performance.now();
 cacheDir(path.join(clientDir, base), base, true);
 cacheDir(path.join(prerenderedDir, base), base, false);
+console.log(`Static files indexed in ${(performance.now() - _t_static).toFixed(1)}ms (${staticCache.size} entries)`);
 
 // -- TLS config (must be before origin warning) ------------------------------
 
@@ -354,14 +358,17 @@ function resolveClientIp(rawIp, headers) {
 
 const asset_dir = `${__dirname}/client${base}`;
 
+const _t_init = performance.now();
 const server = new Server(manifest);
 await server.init({
 	env: /** @type {Record<string, string>} */ (process.env),
 	read: (file) => /** @type {ReadableStream} */ (Readable.toWeb(fs.createReadStream(`${asset_dir}/${file}`)))
 });
+console.log(`SvelteKit server initialized in ${(performance.now() - _t_init).toFixed(1)}ms`);
 
 // -- uWS App -----------------------------------------------------------------
 
+const _t_app = performance.now();
 const app = is_tls
 	? uWS.SSLApp({ cert_file_name: ssl_cert, key_file_name: ssl_key })
 	: uWS.App();
@@ -578,6 +585,18 @@ const ssrInflight = new Map();
 // separate Buffer per chunk. Reduces GC pressure for typical form/JSON bodies.
 const SMALL_BODY_THRESHOLD = 65536; // 64 KB
 
+// Dynamic response compression: only compress text content types above a threshold.
+// Static files use build-time precompression and are never affected by this.
+const COMPRESS_MIN_SIZE = 1024;
+const COMPRESSIBLE_TYPES = new Set([
+	'text/html', 'text/css', 'text/plain', 'text/xml', 'text/javascript',
+	'text/csv', 'text/markdown',
+	'application/json', 'application/xml', 'application/javascript',
+	'application/xhtml+xml', 'application/ld+json', 'application/manifest+json',
+	'application/rss+xml', 'application/atom+xml',
+	'image/svg+xml'
+]);
+
 /**
  * @param {import('uWebSockets.js').HttpResponse} res
  * @param {number} limit
@@ -998,7 +1017,8 @@ async function handleSSR(res, method, url, headers, remoteAddress, state) {
 							statusText: shared.statusText,
 							headers: shared.headers
 						}),
-						state
+						state,
+						headers['accept-encoding']
 					);
 					return;
 				}
@@ -1024,7 +1044,7 @@ async function handleSSR(res, method, url, headers, remoteAddress, state) {
 					// leader's content to waiters that may legitimately differ.
 					if (response.headers.has('set-cookie') || !response.body) {
 						resolveShared(null);
-						await writeResponse(res, response, state);
+						await writeResponse(res, response, state, headers['accept-encoding']);
 						return;
 					}
 					const varyHeader = response.headers.get('vary');
@@ -1034,7 +1054,7 @@ async function handleSSR(res, method, url, headers, remoteAddress, state) {
 						);
 						if (personalized) {
 							resolveShared(null);
-							await writeResponse(res, response, state);
+							await writeResponse(res, response, state, headers['accept-encoding']);
 							return;
 						}
 					}
@@ -1062,7 +1082,8 @@ async function handleSSR(res, method, url, headers, remoteAddress, state) {
 							statusText: response.statusText,
 							headers: response.headers
 						}),
-						state
+						state,
+						headers['accept-encoding']
 					);
 				} catch (err) {
 					resolveShared(null);
@@ -1075,7 +1096,7 @@ async function handleSSR(res, method, url, headers, remoteAddress, state) {
 		// Normal (non-dedup) path
 		const response = await server.respond(request, { platform, getClientAddress });
 		if (state.aborted) return;
-		await writeResponse(res, response, state);
+		await writeResponse(res, response, state, headers['accept-encoding']);
 	} catch (err) {
 		if (state.aborted) return;
 		if (err instanceof PayloadTooLargeError) {
@@ -1109,8 +1130,9 @@ function writeHeaders(res, response) {
  * @param {import('uWebSockets.js').HttpResponse} res
  * @param {Response} response
  * @param {{ aborted: boolean }} state
+ * @param {string} [acceptEncoding]
  */
-async function writeResponse(res, response, state) {
+async function writeResponse(res, response, state, acceptEncoding) {
 	// No body - write headers + end in a single cork (one syscall).
 	// For HEAD responses SvelteKit sets Content-Length to the full body size;
 	// pass it to endWithoutBody() so the client knows the entity size.
@@ -1153,9 +1175,34 @@ async function writeResponse(res, response, state) {
 		if (second.done || state.aborted) {
 			// Single-chunk response (common for SSR) - one cork, one syscall
 			if (!state.aborted) {
+				let body = first.value;
+				let encoding = '';
+				if (acceptEncoding && body.byteLength >= COMPRESS_MIN_SIZE &&
+					!response.headers.has('content-encoding')) {
+					const ctRaw = response.headers.get('content-type') || '';
+					const semi = ctRaw.indexOf(';');
+					const ct = semi === -1 ? ctRaw : ctRaw.slice(0, semi).trimEnd();
+					if (COMPRESSIBLE_TYPES.has(ct)) {
+						const useBr = acceptEncoding.includes('br');
+						const useGz = !useBr && acceptEncoding.includes('gzip');
+						if (useBr || useGz) {
+							const compressed = useBr
+								? brotliCompressSync(body, { params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 4 } })
+								: gzipSync(body, { level: 6 });
+							if (compressed.byteLength < body.byteLength) {
+								body = compressed;
+								encoding = useBr ? 'br' : 'gzip';
+							}
+						}
+					}
+				}
 				res.cork(() => {
 					writeHeaders(res, response);
-					res.end(first.value);
+					if (encoding) {
+						res.writeHeader('content-encoding', encoding);
+						res.writeHeader('vary', 'Accept-Encoding');
+					}
+					res.end(body);
 				});
 			}
 			return;
@@ -1497,10 +1544,10 @@ if (WS_ENABLED) {
 			}
 
 			Promise.resolve(wsModule.upgrade({ headers, cookies, url, remoteAddress: clientIp }))
-				.then((userData) => {
+				.then((result) => {
 					clearTimeout(timer);
 					if (aborted || timedOut) return;
-					if (userData === false) {
+					if (result === false) {
 						res.cork(() => {
 							res.writeStatus('401 Unauthorized');
 							res.writeHeader('content-type', 'text/plain');
@@ -1508,6 +1555,15 @@ if (WS_ENABLED) {
 						});
 						return;
 					}
+					// Unpack upgradeResponse() wrapper if present
+					let responseHeaders = null;
+					let userData;
+					if (result && result.__upgradeResponse === true) {
+						userData = result.userData || {};
+						responseHeaders = result.headers;
+					} else {
+						userData = result || {};
+					}
 					// Warn once per unique key name about potentially sensitive data in userData.
 					// userData is readable by every server-side handler via ws.getUserData().
 					if (userData && typeof userData === 'object') {
@@ -1525,12 +1581,18 @@ if (WS_ENABLED) {
 							}
 						}
 					}
-					// Ensure remoteAddress is in userData so plugins (e.g. ratelimit)
-					// can key on the real client IP without requiring the app to
-					// manually copy it from the upgrade callback arguments.
 					const ud = userData || {};
 					if (!ud.remoteAddress) ud.remoteAddress = clientIp;
 					res.cork(() => {
+						if (responseHeaders) {
+							for (const [hk, hv] of Object.entries(responseHeaders)) {
+								if (Array.isArray(hv)) {
+									for (const v of hv) res.writeHeader(hk, v);
+								} else {
+									res.writeHeader(hk, hv);
+								}
+							}
+						}
 						res.upgrade(
 							ud,
 							secKey,
@@ -1705,7 +1767,8 @@ export function start(host, port) {
 	app.listen(host, port, (socket) => {
 		if (socket) {
 			listenSocket = socket;
-			console.log(`Listening on ${is_tls ? 'https' : 'http'}://${host}:${port}`);
+			const startup = (performance.now() - _t_app).toFixed(0);
+			console.log(`Listening on ${is_tls ? 'https' : 'http'}://${host}:${port} (ready in ${startup}ms)`);
 		} else {
 			console.error(`Failed to listen on ${host}:${port}`);
 			process.exit(1);

package/index.d.ts

@@ -303,7 +303,10 @@ export interface WebSocketHandler<UserData = unknown> {
 	 *
 	 * May be async.
 	 */
-	upgrade?: (ctx: UpgradeContext) => UserData | false | Promise<UserData | false>;
+	upgrade?: (ctx: UpgradeContext) =>
+		| UserData | false
+		| ReturnType<typeof upgradeResponse<UserData>>
+		| Promise<UserData | false | ReturnType<typeof upgradeResponse<UserData>>>;
 
 	/** Called when a WebSocket connection is established. */
 	open?: (ws: WebSocket<UserData>, ctx: OpenContext) => void;
@@ -533,4 +536,27 @@ export interface TopicHelper {
 	decrement(amount?: number): void;
 }
 
+/**
+ * Wrap upgrade hook return value to include response headers on the 101
+ * Switching Protocols response (e.g. `Set-Cookie` for session refresh).
+ *
+ * @example
+ * ```js
+ * import { upgradeResponse } from 'svelte-adapter-uws';
+ *
+ * export function upgrade({ cookies }) {
+ *   const session = validateSession(cookies.session_id);
+ *   if (!session) return false;
+ *   return upgradeResponse(
+ *     { userId: session.userId },
+ *     { 'set-cookie': refreshSessionCookie(session) }
+ *   );
+ * }
+ * ```
+ */
+export function upgradeResponse<UserData>(
+	userData: UserData,
+	headers: Record<string, string | string[]>
+): { __upgradeResponse: true; userData: UserData; headers: Record<string, string | string[]> };
+
 export default function adapter(options?: AdapterOptions): Adapter;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-adapter-uws",
-  "version": "0.4.9",
+  "version": "0.4.10",
   "description": "SvelteKit adapter for uWebSockets.js - high-performance C++ HTTP server with built-in WebSocket support",
   "author": "Kevin Radziszewski",
   "license": "MIT",
@@ -18,6 +18,10 @@
       "types": "./index.d.ts",
       "default": "./index.js"
     },
+    "./upgrade-response": {
+      "types": "./index.d.ts",
+      "default": "./upgrade-response.js"
+    },
     "./client": {
       "types": "./client.d.ts",
       "default": "./client.js"
@@ -26,6 +30,10 @@
       "types": "./vite.d.ts",
       "default": "./vite.js"
     },
+    "./testing": {
+      "types": "./testing.d.ts",
+      "default": "./testing.js"
+    },
     "./plugins/replay": {
       "types": "./plugins/replay/server.d.ts",
       "default": "./plugins/replay/server.js"
@@ -87,6 +95,9 @@
   "files": [
     "index.js",
     "index.d.ts",
+    "upgrade-response.js",
+    "testing.js",
+    "testing.d.ts",
     "client.js",
     "client.d.ts",
     "vite.js",

package/testing.d.ts

@@ -0,0 +1,77 @@
+import type { WebSocket } from 'uWebSockets.js';
+import type { Platform, WebSocketHandler, UpgradeContext } from './index.js';
+
+export interface TestServerOptions {
+	/** Port to listen on. Defaults to 0 (random available port). */
+	port?: number;
+	/** WebSocket endpoint path. @default '/ws' */
+	wsPath?: string;
+	/** WebSocket handler hooks (same shape as hooks.ws.ts exports). */
+	handler?: Partial<WebSocketHandler>;
+}
+
+export interface TestServer {
+	/** HTTP URL of the test server (e.g. 'http://localhost:12345'). */
+	url: string;
+	/** WebSocket URL of the test server (e.g. 'ws://localhost:12345/ws'). */
+	wsUrl: string;
+	/** The port the server is listening on. */
+	port: number;
+	/** Platform API for publishing, sending, and querying connections. */
+	platform: Platform;
+	/** Stop the server and close all connections. */
+	close(): void;
+	/** Wait for a WebSocket client to connect. */
+	waitForConnection(timeout?: number): Promise<void>;
+	/** Wait for the next WebSocket message (after subscribe/unsubscribe handling). */
+	waitForMessage(timeout?: number): Promise<{ data: string; isBinary: boolean }>;
+}
+
+/**
+ * Create a lightweight test server backed by a real uWebSockets.js instance.
+ *
+ * Starts on a random port and provides a Platform-compatible API for
+ * publishing, sending, and asserting on WebSocket behavior. The server
+ * uses the same subscribe/unsubscribe protocol as the production handler.
+ *
+ * @example
+ * ```js
+ * import { createTestServer } from 'svelte-adapter-uws/testing';
+ * import { describe, it, expect, afterEach } from 'vitest';
+ *
+ * let server;
+ * afterEach(() => server?.close());
+ *
+ * it('rejects unauthenticated upgrades', async () => {
+ *   server = await createTestServer({
+ *     handler: {
+ *       upgrade({ cookies }) {
+ *         return cookies.session ? { id: 'user-1' } : false;
+ *       }
+ *     }
+ *   });
+ *
+ *   const res = await fetch(server.wsUrl, {
+ *     headers: { upgrade: 'websocket', connection: 'upgrade' }
+ *   });
+ *   expect(res.status).toBe(401);
+ * });
+ *
+ * it('broadcasts to subscribers', async () => {
+ *   server = await createTestServer();
+ *   const ws = new WebSocket(server.wsUrl);
+ *   await server.waitForConnection();
+ *
+ *   ws.send(JSON.stringify({ type: 'subscribe', topic: 'chat' }));
+ *   // small delay for subscribe to process
+ *   await new Promise(r => setTimeout(r, 10));
+ *
+ *   server.platform.publish('chat', 'new-message', { text: 'hello' });
+ *   const msg = await server.waitForMessage();
+ *   expect(JSON.parse(msg.data)).toMatchObject({
+ *     topic: 'chat', event: 'new-message', data: { text: 'hello' }
+ *   });
+ * });
+ * ```
+ */
+export function createTestServer(options?: TestServerOptions): Promise<TestServer>;

package/testing.js

@@ -0,0 +1,267 @@
+import { parseCookies } from './files/cookies.js';
+
+/**
+ * Safely quote a string for JSON embedding. Throws on invalid characters.
+ * @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 + '"';
+}
+
+/**
+ * Build a JSON envelope string matching the production wire format.
+ * @param {string} topic
+ * @param {string} event
+ * @param {unknown} [data]
+ * @returns {string}
+ */
+function envelope(topic, event, data) {
+	return '{"topic":' + esc(topic) + ',"event":' + esc(event) + ',"data":' + JSON.stringify(data ?? null) + '}';
+}
+
+/**
+ * Create a lightweight test server backed by a real uWebSockets.js instance.
+ *
+ * Starts on a random port and provides a Platform-compatible API for
+ * publishing, sending, and asserting on WebSocket behavior.
+ *
+ * @param {import('./testing.js').TestServerOptions} [options]
+ * @returns {Promise<import('./testing.js').TestServer>}
+ */
+export async function createTestServer(options = {}) {
+	const { port = 0, wsPath = '/ws', handler = {} } = options;
+
+	let uWS;
+	try {
+		uWS = (await import('uWebSockets.js')).default;
+	} catch {
+		throw new Error(
+			'createTestServer requires uWebSockets.js to be installed.\n' +
+			'  npm install uNetworking/uWebSockets.js#v20.60.0'
+		);
+	}
+
+	const app = uWS.App();
+
+	/** @type {Set<import('uWebSockets.js').WebSocket<any>>} */
+	const wsConnections = new Set();
+
+	/** @type {Array<(value: any) => void>} */
+	let connectionWaiters = [];
+
+	/** @type {Array<{ resolve: (value: any) => void, timer: ReturnType<typeof setTimeout> }>} */
+	let messageWaiters = [];
+
+	const platform = {
+		publish(topic, event, data) {
+			const msg = envelope(topic, event, data);
+			return app.publish(topic, msg, false, false);
+		},
+		send(ws, topic, event, data) {
+			return ws.send(envelope(topic, event, data), false, false);
+		},
+		sendTo(filter, topic, event, data) {
+			const msg = envelope(topic, event, data);
+			let count = 0;
+			for (const ws of wsConnections) {
+				if (filter(ws.getUserData())) {
+					ws.send(msg, false, false);
+					count++;
+				}
+			}
+			return count;
+		},
+		get connections() { return wsConnections.size; },
+		subscribers(topic) { return app.numSubscribers(topic); },
+		batch(messages) {
+			return messages.map(({ topic, event, data }) => platform.publish(topic, event, data));
+		},
+		topic(name) {
+			return {
+				publish: (event, data) => platform.publish(name, event, data),
+				created: (data) => platform.publish(name, 'created', data),
+				updated: (data) => platform.publish(name, 'updated', data),
+				deleted: (data) => platform.publish(name, 'deleted', data),
+				set: (value) => platform.publish(name, 'set', value),
+				increment: (amount = 1) => platform.publish(name, 'increment', amount),
+				decrement: (amount = 1) => platform.publish(name, 'decrement', amount)
+			};
+		}
+	};
+
+	app.ws(wsPath, {
+		maxPayloadLength: 64 * 1024,
+		idleTimeout: 120,
+		sendPingsAutomatically: true,
+
+		upgrade(res, req, context) {
+			const headers = {};
+			req.forEach((k, v) => { headers[k] = v; });
+			const secKey = req.getHeader('sec-websocket-key');
+			const secProtocol = req.getHeader('sec-websocket-protocol');
+			const secExtensions = req.getHeader('sec-websocket-extensions');
+			const query = req.getQuery();
+			const url = query ? req.getUrl() + '?' + query : req.getUrl();
+			const rawIp = new TextDecoder().decode(res.getRemoteAddressAsText());
+
+			if (!handler.upgrade) {
+				res.cork(() => {
+					res.upgrade({ remoteAddress: rawIp }, secKey, secProtocol, secExtensions, context);
+				});
+				return;
+			}
+
+			let aborted = false;
+			res.onAborted(() => { aborted = true; });
+
+			const cookies = parseCookies(headers['cookie']);
+			Promise.resolve(handler.upgrade({ headers, cookies, url, remoteAddress: rawIp }))
+				.then((result) => {
+					if (aborted) return;
+					if (result === false) {
+						res.cork(() => {
+							res.writeStatus('401 Unauthorized');
+							res.writeHeader('content-type', 'text/plain');
+							res.end('Unauthorized');
+						});
+						return;
+					}
+					let userData;
+					let responseHeaders = null;
+					if (result && result.__upgradeResponse === true) {
+						userData = result.userData || {};
+						responseHeaders = result.headers;
+					} else {
+						userData = result || {};
+					}
+					if (!userData.remoteAddress) userData.remoteAddress = rawIp;
+					res.cork(() => {
+						if (responseHeaders) {
+							for (const [hk, hv] of Object.entries(responseHeaders)) {
+								if (Array.isArray(hv)) {
+									for (const v of hv) res.writeHeader(hk, v);
+								} else {
+									res.writeHeader(hk, hv);
+								}
+							}
+						}
+						res.upgrade(userData, secKey, secProtocol, secExtensions, context);
+					});
+				})
+				.catch((err) => {
+					if (!aborted) {
+						res.cork(() => {
+							res.writeStatus('500 Internal Server Error');
+							res.writeHeader('content-type', 'text/plain');
+							res.end('Internal Server Error');
+						});
+					}
+				});
+		},
+
+		open(ws) {
+			ws.getUserData().__subscriptions = new Set();
+			wsConnections.add(ws);
+			handler.open?.(ws, { platform });
+			for (const resolve of connectionWaiters) resolve(undefined);
+			connectionWaiters = [];
+		},
+
+		message(ws, message, isBinary) {
+			// Handle subscribe/unsubscribe from client store
+			if (!isBinary && message.byteLength < 8192) {
+				const bytes = new Uint8Array(message);
+				if (bytes[3] === 0x79) {
+					try {
+						const msg = JSON.parse(Buffer.from(message).toString());
+						if (msg.type === 'subscribe' && typeof msg.topic === 'string') {
+							if (msg.topic.length === 0 || msg.topic.length > 256) return;
+							if (handler.subscribe && handler.subscribe(ws, msg.topic, { platform }) === false) return;
+							ws.subscribe(msg.topic);
+							ws.getUserData().__subscriptions?.add(msg.topic);
+							return;
+						}
+						if (msg.type === 'unsubscribe' && typeof msg.topic === 'string') {
+							ws.unsubscribe(msg.topic);
+							ws.getUserData().__subscriptions?.delete(msg.topic);
+							handler.unsubscribe?.(ws, msg.topic, { platform });
+							return;
+						}
+						if (msg.type === 'subscribe-batch' && Array.isArray(msg.topics)) {
+							for (const topic of msg.topics.slice(0, 256)) {
+								if (typeof topic !== 'string' || topic.length === 0 || topic.length > 256) continue;
+								if (handler.subscribe && handler.subscribe(ws, topic, { platform }) === false) continue;
+								ws.subscribe(topic);
+								ws.getUserData().__subscriptions?.add(topic);
+							}
+							return;
+						}
+					} catch {}
+				}
+			}
+
+			for (const waiter of messageWaiters) {
+				clearTimeout(waiter.timer);
+				waiter.resolve({ data: Buffer.from(message).toString(), isBinary });
+			}
+			messageWaiters = [];
+
+			handler.message?.(ws, { data: message, isBinary, platform });
+		},
+
+		close(ws, code, message) {
+			const subs = ws.getUserData()?.__subscriptions || new Set();
+			handler.close?.(ws, { code, message, platform, subscriptions: subs });
+			wsConnections.delete(ws);
+		}
+	});
+
+	return new Promise((resolve, reject) => {
+		app.listen(port, (listenSocket) => {
+			if (!listenSocket) return reject(new Error('Failed to listen'));
+			const boundPort = uWS.us_socket_local_port(listenSocket);
+			resolve({
+				url: `http://localhost:${boundPort}`,
+				wsUrl: `ws://localhost:${boundPort}${wsPath}`,
+				port: boundPort,
+				platform,
+				close() {
+					for (const ws of wsConnections) ws.close(1001, 'Test server closing');
+					wsConnections.clear();
+					uWS.us_listen_socket_close(listenSocket);
+				},
+				waitForConnection(timeout = 5000) {
+					return new Promise((resolve, reject) => {
+						const timer = setTimeout(
+							() => reject(new Error('waitForConnection timed out')),
+							timeout
+						);
+						connectionWaiters.push(() => { clearTimeout(timer); resolve(undefined); });
+					});
+				},
+				waitForMessage(timeout = 5000) {
+					return new Promise((resolve, reject) => {
+						const timer = setTimeout(
+							() => {
+								messageWaiters = messageWaiters.filter(w => w.timer !== timer);
+								reject(new Error('waitForMessage timed out'));
+							},
+							timeout
+						);
+						messageWaiters.push({ resolve(v) { clearTimeout(timer); resolve(v); }, timer });
+					});
+				}
+			});
+		});
+	});
+}

package/upgrade-response.js

@@ -0,0 +1,12 @@
+/**
+ * Wrap upgrade hook return value to include response headers on the 101
+ * Switching Protocols response (e.g. Set-Cookie for session refresh).
+ *
+ * @template T
+ * @param {T} userData - Data attached to ws.getUserData()
+ * @param {Record<string, string | string[]>} headers - Headers for the 101 response
+ * @returns {{ __upgradeResponse: true, userData: T, headers: Record<string, string | string[]> }}
+ */
+export function upgradeResponse(userData, headers) {
+	return { __upgradeResponse: true, userData, headers };
+}

package/vite.js

@@ -367,7 +367,14 @@ export default function uws(options = {}) {
 							socket.destroy();
 							return;
 						}
-						userData = result || {};
+						if (result && result.__upgradeResponse === true) {
+							userData = result.userData || {};
+							if (result.headers && Object.keys(result.headers).length > 0) {
+								console.warn('[adapter-uws] upgrade() returned response headers — these are only applied in production (uWS). The ws library used in dev does not support custom 101 headers.');
+							}
+						} else {
+							userData = result || {};
+						}
 					} catch (err) {
 						console.error('[adapter-uws] WebSocket upgrade error:', err);
 						socket.write('HTTP/1.1 500 Internal Server Error\r\nContent-Type: text/plain\r\n\r\nInternal Server Error');