feat: native support for Websockets

documentation/docs/25-build-and-deploy/99-writing-adapters.md

@@ -58,3 +58,5 @@ Within the `adapt` method, there are a number of things that an adapter should d
 - Put the user's static files and the generated JS/CSS in the correct location for the target platform
 
 Where possible, we recommend putting the adapter output under the `build/` directory with any intermediate output placed under `.svelte-kit/[adapter-name]`.
+
+To add WebSockets to a SvelteKit adapter, you will need to handle upgrading the connection within the adapter. The crossws [adapter integration guides](https://crossws.unjs.io/adapters) may be a helpful reference.

documentation/docs/30-advanced/15-websockets.md

@@ -0,0 +1,120 @@
+---
+title: WebSockets
+---
+
+## The `socket` object
+
+[WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) provide a way to open a bidirectional communication channel between the client and server.
+
+SvelteKit accepts a `socket` object in `+server.js` files that you can use to handle WebSocket connections to different routes in your app.
+
+The shape of this socket object directly corresponds to the [Hooks](https://crossws.unjs.io/guide/hooks) type in `crossws` as this is the package being used to handle cross-platform WebSocket connections.
+
+```js
+export const socket = {
+	upgrade(req) {
+        // ...
+	},
+
+	open(peer) {
+        // ...
+	},
+
+	message(peer, message) {
+        // ...
+	},
+
+	close(peer, event) {
+		// ...
+	},
+
+	error(peer, error) {
+		// ...
+	}
+};
+```
+
+### Upgrade
+
+The `upgrade` hook is called when a WebSocket connection is established, and can be used to accept or reject the connection attempt.
+
+Additionally, SvelteKit provides a WebSocket specific `accept` helper function alongside the existing `error` function used for HTTP errors to easily accept or reject connections.
+
+```js
+import { error, accept } from "@sveltejs/kit";
+
+export const socket = {
+	upgrade(req) {
+		// Accept the WebSocket connection with a return
+		return accept();
+
+		// Reject the WebSocket connection with a standard SvelteKit error
+		error(401, 'unauthorized');
+	}
+
+    // ...
+};
+```
+
+### Open
+
+The `open` hook is called when a WebSocket connection is opened. It receives the [peer](https://crossws.unjs.io/guide/peer) WebSocket object as a parameter.
+
+```js
+export const socket = {
+	open(peer) {
+		// ...
+	}
+};
+```
+
+### Message
+
+The `message` hook is called when a message is received from the client. It receives the [peer](https://crossws.unjs.io/guide/peer) WebSocket object and the [message](https://crossws.unjs.io/guide/message) as parameters.
+
+```js
+export const socket = {
+	message(peer, message) {
+		// ...
+	}
+};
+```
+
+### Close
+
+The `close` hook is called when a WebSocket connection is closed. It receives the [peer](https://crossws.unjs.io/guide/peer) WebSocket object and the close event as parameters.
+
+```js
+export const socket = {
+	close(peer, event) {
+		// ...
+	}
+};
+```
+
+### Error
+
+The `error` hook is called when a WebSocket connection error occurs. It receives the [peer](https://crossws.unjs.io/guide/peer) WebSocket object and the error as parameters.
+
+```js
+export const socket = {
+	error(peer, error) {
+		// ...
+	}
+};
+```
+
+## Connecting from the client
+
+To connect to a WebSocket endpoint in SvelteKit, you can use the native `WebSocket` class in the browser.
+
+```js
+// To connect to src/routes/ws/+server.js
+const socket = new WebSocket(`/ws`);
+```
+
+See [the WebSocket documentation on MDN](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket) for more details.
+
+## Compatibility
+
+SvelteKit uses [`unjs/crossws`](https://crossws.unjs.io) to handle WebSocket connections. Please refer to their [compatibility table](https://crossws.unjs.io/guide/peer#compatibility) for the peer object in different runtime environments.

packages/adapter-cloudflare-workers/files/entry.js

@@ -2,6 +2,8 @@ import { Server } from 'SERVER';
 import { manifest, prerendered, base_path } from 'MANIFEST';
 import { getAssetFromKV, mapRequestToAsset } from '@cloudflare/kv-asset-handler';
 import static_asset_manifest_json from '__STATIC_CONTENT_MANIFEST';
+import crossws from 'crossws/adapters/cloudflare';
+
 const static_asset_manifest = JSON.parse(static_asset_manifest_json);
 
 const server = new Server(manifest);
@@ -20,6 +22,14 @@ export default {
 	async fetch(req, env, context) {
 		await server.init({ env });
 
+		const ws = crossws({
+			resolve: server.resolve()
+		});
+
+		if (req.headers.get('upgrade') === 'websocket') {
+			return ws.handleUpgrade(req, env, context);
+		}
+
 		const url = new URL(req.url);
 
 		// static assets

packages/adapter-cloudflare-workers/package.json

@@ -40,6 +40,7 @@
 	"dependencies": {
 		"@cloudflare/workers-types": "^4.20231121.0",
 		"@iarna/toml": "^2.2.5",
+		"crossws": "^0.3.2",
 		"esbuild": "^0.24.0"
 	},
 	"devDependencies": {

packages/adapter-cloudflare/package.json

@@ -41,6 +41,7 @@
 	},
 	"dependencies": {
 		"@cloudflare/workers-types": "^4.20241106.0",
+		"crossws": "^0.3.2",
 		"esbuild": "^0.24.0",
 		"worktop": "0.8.0-next.18"
 	},

packages/adapter-cloudflare/src/worker.js

@@ -1,6 +1,7 @@
 import { Server } from 'SERVER';
 import { manifest, prerendered, base_path } from 'MANIFEST';
 import * as Cache from 'worktop/cfw.cache';
+import crossws from 'crossws/adapters/cloudflare';
 
 const server = new Server(manifest);
 
@@ -14,6 +15,15 @@ const worker = {
 	async fetch(req, env, context) {
 		// @ts-ignore
 		await server.init({ env });
+
+		const ws = crossws({
+			resolve: server.resolve()
+		});
+
+		if (req.headers.get('upgrade') === 'websocket') {
+			return ws.handleUpgrade(req, env, context);
+		}
+
 		// skip cache if "cache-control: no-cache" in request
 		let pragma = req.headers.get('cache-control') || '';
 		let res = !pragma.includes('no-cache') && (await Cache.lookup(req));

packages/adapter-node/package.json

@@ -47,6 +47,7 @@
 		"@sveltejs/vite-plugin-svelte": "^5.0.1",
 		"@types/node": "^18.19.48",
 		"polka": "^1.0.0-next.28",
+		"crossws": "^0.3.2",
 		"sirv": "^3.0.0",
 		"typescript": "^5.3.3",
 		"vitest": "^3.0.1"

packages/adapter-node/src/handler.js

@@ -212,3 +212,5 @@ export const handler = sequence(
 		ssr
 	].filter(Boolean)
 );
+
+export const resolve = server.resolve;

packages/adapter-node/src/index.js

@@ -1,7 +1,9 @@
 import process from 'node:process';
-import { handler } from 'HANDLER';
+import { handler, resolve } from 'HANDLER';
 import { env } from 'ENV';
 import polka from 'polka';
+import http from 'node:http';
+import crossws from 'crossws/adapters/node';
 
 export const path = env('SOCKET_PATH', false);
 export const host = env('HOST', '0.0.0.0');
@@ -31,7 +33,16 @@ let shutdown_timeout_id;
 /** @type {NodeJS.Timeout | void} */
 let idle_timeout_id;
 
-const server = polka().use(handler);
+const httpServer = http.createServer();
+const server = polka({ server: httpServer }).use(handler);
+
+const ws = crossws({
+	resolve: resolve()
+});
+
+httpServer.on('upgrade', (req, socket, head) => {
+	ws.handleUpgrade(req, socket, head);
+});
 
 if (socket_activation) {
 	server.listen({ fd: SD_LISTEN_FDS_START }, () => {

packages/kit/package.json

@@ -20,6 +20,7 @@
 	"dependencies": {
 		"@types/cookie": "^0.6.0",
 		"cookie": "^0.6.0",
+		"crossws": "^0.3.3",
 		"devalue": "^5.1.0",
 		"esm-env": "^1.2.2",
 		"import-meta-resolve": "^4.1.0",

packages/kit/src/exports/index.js

@@ -110,6 +110,18 @@ export function redirect(status, location) {
 	);
 }
 
+export const acceptResponse = new Response(null, {
+	status: 200
+});
+
+/**
+ * Accepts a websocket upgrade request. When called during request handling, SvelteKit will accept the websocket upgrade request.
+ * @return {Response} This response instructs SvelteKit to accept the websocket upgrade request.
+ */
+export function accept() {
+	return acceptResponse;
+}
+
 /**
  * Checks whether this is a redirect thrown by {@link redirect}.
  * @param {unknown} e The object to check.

packages/kit/src/exports/public.d.ts

@@ -19,6 +19,7 @@ import {
 } from '../types/private.js';
 import { BuildData, SSRNodeLoader, SSRRoute, ValidatedConfig } from 'types';
 import type { PluginOptions } from '@sveltejs/vite-plugin-svelte';
+import { ResolveHooks } from 'crossws';
 
 export { PrerenderOption } from '../types/private.js';
 
@@ -1277,6 +1278,7 @@ export class Server {
 	constructor(manifest: SSRManifest);
 	init(options: ServerInitOptions): Promise<void>;
 	respond(request: Request, options: RequestOptions): Promise<Response>;
+	resolve(): ResolveHooks;
 }
 
 export interface ServerInitOptions {

packages/kit/src/exports/vite/dev/index.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
 import { URL } from 'node:url';
+import crossws from 'crossws/adapters/node';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import colors from 'kleur';
 import sirv from 'sirv';
@@ -418,7 +419,7 @@ export async function dev(vite, vite_config, svelte_config) {
 	const env = loadEnv(vite_config.mode, svelte_config.kit.env.dir, '');
 	const emulator = await svelte_config.kit.adapter?.emulate?.();
 
-	return () => {
+	return async () => {
 		const serve_static_middleware = vite.middlewares.stack.find(
 			(middleware) =>
 				/** @type {function} */ (middleware.handle).name === 'viteServeStaticMiddleware'
@@ -428,6 +429,36 @@ export async function dev(vite, vite_config, svelte_config) {
 		// serving routes with those names. See https://github.com/vitejs/vite/issues/7363
 		remove_static_middlewares(vite.middlewares);
 
+		// we have to import `Server` before calling `set_assets`
+		const { Server } = /** @type {import('types').ServerModule} */ (
+			await vite.ssrLoadModule(`${runtime_base}/server/index.js`, { fixStacktrace: true })
+		);
+
+		const { set_fix_stack_trace } = await vite.ssrLoadModule(`${runtime_base}/shared-server.js`);
+		set_fix_stack_trace(fix_stack_trace);
+
+		const { set_assets } = await vite.ssrLoadModule('__sveltekit/paths');
+		set_assets(assets);
+
+		const server = new Server(manifest);
+
+		// we have to initialize the server before we can call the resolve function to populate the webhook resolver in the websocket handler
+		await server.init({
+			env,
+			read: (file) => createReadableStream(from_fs(file))
+		});
+
+		/** @type {import('crossws/adapters/node').NodeAdapter} */
+		const ws = crossws({
+			resolve: server.resolve()
+		});
+
+		vite.httpServer?.on('upgrade', (req, socket, head) => {
+			if (req.headers['sec-websocket-protocol'] !== 'vite-hmr') {
+				ws.handleUpgrade(req, socket, head);
+			}
+		});
+
 		vite.middlewares.use(async (req, res) => {
 			// Vite's base middleware strips out the base path. Restore it
 			const original_url = req.url;
@@ -471,26 +502,6 @@ export async function dev(vite, vite_config, svelte_config) {
 					return;
 				}
 
-				// we have to import `Server` before calling `set_assets`
-				const { Server } = /** @type {import('types').ServerModule} */ (
-					await vite.ssrLoadModule(`${runtime_base}/server/index.js`, { fixStacktrace: true })
-				);
-
-				const { set_fix_stack_trace } = await vite.ssrLoadModule(
-					`${runtime_base}/shared-server.js`
-				);
-				set_fix_stack_trace(fix_stack_trace);
-
-				const { set_assets } = await vite.ssrLoadModule('__sveltekit/paths');
-				set_assets(assets);
-
-				const server = new Server(manifest);
-
-				await server.init({
-					env,
-					read: (file) => createReadableStream(from_fs(file))
-				});
-
 				const request = await getRequest({
 					base,
 					request: req

packages/kit/src/runtime/control.js

@@ -12,6 +12,9 @@ export class HttpError {
 		} else {
 			this.body = { message: `Error: ${status}` };
 		}
+		this.response = new Response(this.toString(), {
+			status: this.status
+		});
 	}
 
 	toString() {