feat: native support for Websockets

.changeset/tricky-drinks-develop.md

@@ -0,0 +1,8 @@
+---
+'@sveltejs/adapter-cloudflare-workers': minor
+'@sveltejs/adapter-cloudflare': minor
+'@sveltejs/adapter-node': minor
+'@sveltejs/kit': minor
+---
+
+feat: add support for WebSockets

.changeset/two-islands-sleep.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/adapter-auto': patch
+---
+
+fix: better error message when exporting `socket`

documentation/docs/25-build-and-deploy/40-adapter-node.md

@@ -241,12 +241,12 @@ WantedBy=sockets.target
 
 The adapter creates two files in your build directory — `index.js` and `handler.js`. Running `index.js` — e.g. `node build`, if you use the default build directory — will start a server on the configured port.
 
-Alternatively, you can import the `handler.js` file, which exports a handler suitable for use with [Express](https://github.com/expressjs/express), [Connect](https://github.com/senchalabs/connect) or [Polka](https://github.com/lukeed/polka) (or even just the built-in [`http.createServer`](https://nodejs.org/dist/latest/docs/api/http.html#httpcreateserveroptions-requestlistener)) and set up your own server:
+Alternatively, you can import the `handler.js` file, which exports handlers suitable for use with [Express](https://github.com/expressjs/express), [Connect](https://github.com/senchalabs/connect) or [Polka](https://github.com/lukeed/polka) (or even just the built-in [`http.createServer`](https://nodejs.org/dist/latest/docs/api/http.html#httpcreateserveroptions-requestlistener)) and set up your own server:
 
 ```js
 // @errors: 2307 7006
 /// file: my-server.js
-import { handler } from './build/handler.js';
+import { handler, upgradeHandler } from './build/handler.js';
 import express from 'express';
 
 const app = express();
@@ -256,10 +256,13 @@ app.get('/healthcheck', (req, res) => {
 	res.end('ok');
 });
 
-// let SvelteKit handle everything else, including serving prerendered pages and static assets
+// let SvelteKit handle serving prerendered pages, static assets, and SSR
 app.use(handler);
 
-app.listen(3000, () => {
+const server = app.listen(3000, () => {
 	console.log('listening on port 3000');
 });
+
+// let SvelteKit handle protocol upgrades for WebSocket connections
+server.on('upgrade', upgradeHandler);
 ```

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

@@ -34,6 +34,11 @@ export default function (options) {
 				// Return `true` if the route with the given `config` can use `read`
 				// from `$app/server` in production, return `false` if it can't.
 				// Or throw a descriptive error describing how to configure the deployment
+			},
+			webSockets: () => {
+				// Return `true` if the production environment supports WebSockets,
+				// return `false` if it can't.
+				// Or throw a descriptive error describing how to configure the deployment
 			}
 		}
 	};
@@ -58,3 +63,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]`.
+
+If your environment supports WebSockets, you will need to handle upgrading a HTTP request to a WebSocket connection. You can do this by listening for requests from the platform that have an `Upgrade: websocket` header, calling the `server.getWebSocketHooksResolver({ getClientAddress })` function to get the WebSocket hooks resolver and passing it to the crossws adapter `resolve` option. The [crossws Adapters section](https://crossws.unjs.io/adapters) provides examples of creating this integration within various environments.

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

@@ -0,0 +1,133 @@
+---
+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 a client and a server.
+
+A `+server.js` file can export a `socket` object to handle WebSocket connections. It uses [crossws](https://crossws.unjs.io/) to provide a consistent interface across different platforms. You can define [hooks](https://crossws.unjs.io/guide/hooks), all optional, to handle the different stages of the WebSocket lifecycle.
+
+```js
+/** @type {import('@sveltejs/kit').Socket} **/
+export const socket = {
+	upgrade(req) {
+        // ...
+	},
+
+	open(peer) {
+        // ...
+	},
+
+	message(peer, message) {
+        // ...
+	},
+
+	close(peer, event) {
+		// ...
+	},
+
+	error(peer, error) {
+		// ...
+	}
+};
+```
+
+### upgrade
+
+The `upgrade` hook is called before a WebSocket connection is established. It receives the [request](https://developer.mozilla.org/docs/Web/API/Request) object as a parameter.
+
+You can use the [`error`](@sveltejs-kit#error) function imported from `@sveltejs/kit` to easily reject connections. Requests will be auto-accepted if the `upgrade` hook is not defined or does not `error`.
+
+```js
+import { error } from "@sveltejs/kit";
+
+/** @type {import('@sveltejs/kit').Socket} **/
+export const socket = {
+	upgrade(request) {
+		if (request.headers.get('origin') !== 'allowed_origin') {
+			// Reject the WebSocket connection by throwing an error
+			error(403, 'Forbidden');
+		}
+	}
+};
+```
+
+### open
+
+The `open` hook is called when a WebSocket connection is opened. It receives the [peer](https://crossws.unjs.io/guide/peer) object, to allow interacting with connected clients, as a parameter.
+
+```js
+/** @type {import('@sveltejs/kit').Socket} **/
+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) object, to allow interacting with connected clients, and the [message](https://crossws.unjs.io/guide/message) object, containing data from the client, as parameters.
+
+```js
+/** @type {import('@sveltejs/kit').Socket} **/
+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) object, to allow interacting with connected clients, and the close event object, containing the [WebSocket connection close code](https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent/code#value) and reason, as parameters.
+
+```js
+/** @type {import('@sveltejs/kit').Socket} **/
+export const socket = {
+	close(peer, event) {
+		// ...
+	}
+};
+```
+
+### error
+
+The `error` hook is called when a connection with a WebSocket has been closed due to an error. It receives the [peer](https://crossws.unjs.io/guide/peer) object, to allow interacting with connected clients, and the error, as parameters.
+
+```js
+/** @type {import('@sveltejs/kit').Socket} **/
+export const socket = {
+	error(peer, error) {
+		// ...
+	}
+};
+```
+
+## Connecting from the client
+
+To connect to a WebSocket endpoint, you can use the [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket) constructor in the browser.
+
+```svelte
+<script>
+	import { onMount } from 'svelte';
+
+	onMount(() => {
+		// To connect to src/routes/ws/+server.js
+		const socket = new WebSocket(`/ws`);
+
+		socket.addEventListener("open", (event) => {
+			socket.send("Hello Server!");
+		});
+
+		// ...
+	});
+</script>
+```
+
+See [the WebSocket documentation on MDN](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) for more details.
+
+## Compatibility
+
+SvelteKit uses [`crossws`](https://crossws.unjs.io) to handle cross-platform WebSocket connections. Please refer to their [compatibility table](https://crossws.unjs.io/guide/peer#compatibility) for the `peer` object in different runtime environments.

documentation/docs/30-advanced/20-hooks.md

@@ -106,7 +106,7 @@ Note that `resolve(...)` will never throw an error, it will always return a `Pro
 
 ### handleFetch
 
-This function allows you to modify (or replace) a `fetch` request that happens inside a `load` or `action` function that runs on the server (or during pre-rendering).
+This function allows you to modify (or replace) a `fetch` request that happens inside a `load`, `action`, or `handle` function that runs on the server (or during prerendering).
 
 For example, your `load` function might make a request to a public URL like `https://api.yourapp.com` when the user performs a client-side navigation to the respective page, but during SSR it might make sense to hit the API directly (bypassing whatever proxies and load balancers sit between it and the public internet).
 
@@ -153,7 +153,7 @@ The following can be added to `src/hooks.server.js` _and_ `src/hooks.client.js`:
 
 ### handleError
 
-If an [unexpected error](errors#Unexpected-errors) is thrown during loading or rendering, this function will be called with the `error`, `event`, `status` code and `message`. This allows for two things:
+If an [unexpected error](errors#Unexpected-errors) is thrown during loading, rendering, or from an endpoint, this function will be called with the `error`, `event`, `status` code and `message`. This allows for two things:
 
 - you can log the error
 - you can generate a custom representation of the error that is safe to show to users, omitting sensitive details like messages and stack traces. The returned value, which defaults to `{ message }`, becomes the value of `$page.error`.

packages/adapter-auto/index.js

@@ -125,6 +125,11 @@ export default () => ({
 			throw new Error(
 				"The read function imported from $app/server only works in certain environments. Since you're using @sveltejs/adapter-auto, SvelteKit cannot determine whether it will work when your app is deployed. Please replace it with an adapter tailored to your target environment."
 			);
+		},
+		webSockets: () => {
+			throw new Error(
+				"The socket export that creates a WebSocket server only works in certain environments. Since you're using @sveltejs/adapter-auto, SvelteKit cannot determine whether it will work when your app is deployed. Please replace it with an adapter tailored to your target environment."
+			);
 		}
 	}
 });

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

@@ -2,6 +2,9 @@ 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';
+// TODO: allow WebSocket integration with Durable Objects using crossws/adapters/cloudflare-durable
+import crossws from 'crossws/adapters/cloudflare';
+
 const static_asset_manifest = JSON.parse(static_asset_manifest_json);
 
 const server = new Server(manifest);
@@ -11,15 +14,53 @@ const app_path = `/${manifest.appPath}`;
 const immutable = `${app_path}/immutable/`;
 const version_file = `${app_path}/version.json`;
 
+/** @type {import('crossws').ResolveHooks} */
+let resolve_websocket_hooks;
+/** @type {import('crossws/adapters/cloudflare').CloudflareAdapter} */
+let ws;
+
+if (server.getWebSocketHooksResolver) {
+	ws = crossws({
+		resolve: (req) => resolve_websocket_hooks(req)
+	});
+}
+
 export default {
 	/**
 	 * @param {Request} req
 	 * @param {any} env
 	 * @param {any} context
 	 */
 	async fetch(req, env, context) {
+		const options = {
+			platform: {
+				env,
+				context,
+				// lib.dom is interfering with workers-types
+				caches,
+				// req is actually a Cloudflare request not a standard request
+				cf: req.cf
+			},
+			getClientAddress() {
+				return req.headers.get('cf-connecting-ip');
+			}
+		};
+
 		await server.init({ env });
 
+		if (req.headers.get('upgrade') === 'websocket' && ws) {
+			resolve_websocket_hooks = server.getWebSocketHooksResolver(
+				// @ts-ignore
+				options
+			);
+			return ws.handleUpgrade(
+				// @ts-ignore wtf is Cloudflare doing to these types
+				req,
+				env,
+				context
+			);
+		}
+
 		const url = new URL(req.url);
 
 		// static assets
@@ -90,19 +131,11 @@ export default {
 		}
 
 		// dynamically-generated pages
-		return await server.respond(req, {
-			platform: {
-				env,
-				context,
-				// @ts-expect-error lib.dom is interfering with workers-types
-				caches,
-				// @ts-expect-error req is actually a Cloudflare request not a standard request
-				cf: req.cf
-			},
-			getClientAddress() {
-				return req.headers.get('cf-connecting-ip');
-			}
-		});
+		return await server.respond(
+			req,
+			// @ts-ignore
+			options
+		);
 	}
 };
 

packages/adapter-cloudflare-workers/index.js

@@ -182,6 +182,9 @@ export default function ({ config = 'wrangler.toml', platformProxy = {} } = {})
 					return prerender ? emulated.prerender_platform : emulated.platform;
 				}
 			};
+		},
+		supports: {
+			webSockets: () => true
 		}
 	};
 }

packages/adapter-cloudflare-workers/package.json

@@ -38,8 +38,9 @@
 		"check": "tsc --skipLibCheck"
 	},
 	"dependencies": {
-		"@cloudflare/workers-types": "^4.20231121.0",
+		"@cloudflare/workers-types": "^4.20250129.0",
 		"@iarna/toml": "^2.2.5",
+		"crossws": "^0.3.4",
 		"esbuild": "^0.24.0"
 	},
 	"devDependencies": {

packages/adapter-cloudflare/index.js

@@ -100,6 +100,9 @@ export default function (options = {}) {
 					return prerender ? emulated.prerender_platform : emulated.platform;
 				}
 			};
+		},
+		supports: {
+			webSockets: () => true
 		}
 	};
 }

packages/adapter-cloudflare/package.json

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