feat: native support for Websockets #12973
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| --- | ||
| '@sveltejs/adapter-cloudflare': minor | ||
| '@sveltejs/adapter-node': minor | ||
| '@sveltejs/kit': minor | ||
| --- | ||
|
|
||
| feat: add support for WebSockets |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| --- | ||
| '@sveltejs/adapter-auto': patch | ||
| --- | ||
|
|
||
| fix: add error message when using WebSockets as they are unsupported |
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,137 @@ | ||||||
| --- | ||||||
| title: WebSockets | ||||||
| --- | ||||||
|
|
||||||
| [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. SvelteKit uses [`crossws`](https://crossws.unjs.io/) to provide a consistent interface across different platforms. | ||||||
|
|
||||||
| ## Hooks | ||||||
|
|
||||||
| A `+server.js` file can export a `socket` object with [hooks](https://crossws.unjs.io/guide/hooks), all optional, to handle the different stages of the WebSocket lifecycle. | ||||||
|
|
||||||
| ```js | ||||||
| /** @type {import('./$types').Socket} **/ | ||||||
| export const socket = { | ||||||
LukeHagar marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| upgrade(event) { | ||||||
| // ... | ||||||
| }, | ||||||
| open(peer) { | ||||||
| // ... | ||||||
| }, | ||||||
| message(peer, message) { | ||||||
| // ... | ||||||
| }, | ||||||
| close(peer, details) { | ||||||
| // ... | ||||||
| }, | ||||||
| error(peer, error) { | ||||||
| // ... | ||||||
| } | ||||||
| }; | ||||||
| ``` | ||||||
|
|
||||||
| ### upgrade | ||||||
|
|
||||||
| The `upgrade` hook is called before a WebSocket connection is established. It receives a [`RequestEvent`](@sveltejs-kit#RequestEvent) object that has an additional [`context`](https://crossws.unjs.io/guide/peer#peercontext) property to store abitrary information that is shared with that connection's [`Peer`](https://crossws.unjs.io/guide/peer) object. | ||||||
|
|
||||||
| 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('./$types').Socket} **/ | ||||||
| export const socket = { | ||||||
| upgrade({ request }) { | ||||||
| if (request.headers.get('origin') !== 'my_allowed_origin') { | ||||||
eltigerchino marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| // 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 a [`Peer`](https://crossws.unjs.io/guide/peer) object to allow interacting with connected clients. | ||||||
|
|
||||||
| ```js | ||||||
| /** @type {import('./$types').Socket} **/ | ||||||
| export const socket = { | ||||||
| open(peer) { | ||||||
|
There was a problem hiding this comment. It would be a deviation from the crossws API but if we used this signature instead we would be able to access the
Suggested change
Similarly for There was a problem hiding this comment. I love the experience this destructing provides, and love it today with the existing parts of kit |
||||||
| // ... | ||||||
| } | ||||||
| }; | ||||||
| ``` | ||||||
|
|
||||||
| ### 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 which contains data from the client. | ||||||
|
|
||||||
| ```js | ||||||
| /** @type {import('./$types').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 details object which contains the [WebSocket connection close code](https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent/code#value) and reason. | ||||||
|
|
||||||
| ```js | ||||||
| /** @type {import('./$types').Socket} **/ | ||||||
| export const socket = { | ||||||
| close(peer, details) { | ||||||
| // ... | ||||||
| } | ||||||
| }; | ||||||
| ``` | ||||||
|
|
||||||
| ### 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. | ||||||
|
|
||||||
| ```js | ||||||
| /** @type {import('./$types').Socket} **/ | ||||||
| export const socket = { | ||||||
| error(peer, error) { | ||||||
| // ... | ||||||
| } | ||||||
| }; | ||||||
| ``` | ||||||
|
|
||||||
| ## Accessing `RequestEvent` through `Peer` | ||||||
|
|
||||||
| The [`Peer`](https://crossws.unjs.io/guide/peer) object has been extended to include the [`RequestEvent`](@sveltejs-kit#RequestEvent) object from the initial upgrade request. It can be accessed through the `peer.event` property. | ||||||
|
Comment on lines
+104
to
+106
There was a problem hiding this comment. see prior note on tweaking the |
||||||
|
|
||||||
| ## `getPeers` and `publish` | ||||||
|
|
||||||
| The [`getPeers`]($app-server#getPeers) and [`publish`]($app-server#publish) functions from `$app/server` can be used to interact with your WebSocket connections from anywhere on the server. | ||||||
|
Comment on lines
+108
to
+110
There was a problem hiding this comment. I don't quite understand these functions — aren't they specific to a socket? There was a problem hiding this comment. Ok @eltigerchino has educated me here on how these work. My feeling is that we shouldn't expose Instead I think we should probably encourage people to handle peers manually, if you want to interact with them from outside the socket handlers: // src/lib/topics/foo.ts
export const peers = new Set();// src/routes/foo/+server.ts
import { peers } from '$lib/topics/foo';
export const socket = {
open({ peer }) {
peers.add(peer);
peer.send('hello');
},
close({ peer }) {
peers.delete(peer);
}
};// src/routes/elsewhere/+server.ts
import { peers } from '$lib/topics/foo';
export async function POST({ request }) {
const message = await request.json();
for (const peer of peers) {
peer.send(message);
}
}One question we're not too sure about: will this work with Durable Objects, or is there some magic for saving/restoring that we don't have access to? There was a problem hiding this comment. Durable objects have internal persistent state. As either Sqlite like db or KV. It also has in memory store. In example bellow I think sessions is in memory. https://github.com/cloudflare/workers-chat-demo/blob/master/src/chat.mjs Often I want to store state in the DO so new joiners get the current state from the DO the incremental state via WS. So very helpful if DO can be exposed on platform.env. There was a problem hiding this comment. Helpful if there is a general way to package DOs with Sveltekit through adapter-cloudflare as there are many nice DO things: MCP servers, partykit. I'd really like to be able to put HelloWorld.durableObject.ts in a route folder and have it added to the worker output by the build. |
||||||
|
|
||||||
| ## 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 | ||||||
|
|
||||||
| Please refer to the crossws [`Peer` object compatibility table](https://crossws.unjs.io/guide/peer#compatibility) and [`Message` object compatibility table](https://crossws.unjs.io/guide/message#adapter-support) to know what is supported in different runtime environments. | ||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
more a note to self as i work through the PR than anything, but: the description here is identical to the one for
socket. Are there cases where one would be supported but not the other? If so it might be helpful if the descriptions explain the difference