WebSockets@rhythmjs/ws
Routes and ws.data
Each route decides its connection's typed ws.data: the route params by default, or whatever upgrade(ctx) returns.
On this page
Declaring routes#
.ws(path, handlers) registers a GET upgrade endpoint and returns the instance, so calls chain. Paths use the router's rou3 patterns (:param, *, **), must start with / (a TypeError otherwise), and a static segment always beats a param segment regardless of registration order: /rooms/lobby wins over /rooms/:id. URL-encoded params are decoded; a malformed encoding makes the request pass through unmatched.
import { RhythmWs } from "@rhythmjs/ws";
const ws = new RhythmWs()
.ws("/ws/rooms/lobby", { open: (peer) => void peer.send("welcome to the lobby") })
.ws("/ws/rooms/:id", { open: (peer) => void peer.send(`room ${peer.data.id}`) });The handlers object carries Bun's WebSocketHandler members with Bun's exact signatures, all optional:
open(ws)#- The connection opened.
message(ws, message)#- A message arrived;
messageisstring | Buffer. drain(ws)#- The socket is writable again after backpressure.
close(ws, code, reason)#- The connection closed.
ping(ws, data) / pong(ws, data)#- A ping or pong frame arrived;
datais aBuffer.
Two more members run at upgrade time, before the socket exists: upgrade and headers, covered below.
The params default#
Without an upgrade hook, ws.data is the route params, typed from the path. /rooms/:id gives peer.data.id as a string, and a param that is not in the path is a type error:
new RhythmWs().ws("/ws/rooms/:id", {
open(peer) {
peer.subscribe(`room:${peer.data.id}`);
},
});Computing ws.data with upgrade#
upgrade(ctx) runs once per handshake and returns this connection's ws.data: any object, sync or async. The returned type flows into every lifecycle member, so there is nothing to annotate. ctx is the full request context: ctx.request, ctx.params typed from the path, ctx.server, and everything earlier middleware derived onto it.
const ws = new RhythmWs().ws("/ws/rooms/:id", {
upgrade(ctx) {
const token = new URL(ctx.request.url).searchParams.get("name");
return { room: ctx.params.id, name: token ?? "guest" };
},
open(peer) {
peer.data.name; // string
// peer.data.id is a type error: params are not part of the data this hook returns
},
});Returning nothing falls back to the params, so a hook that only sometimes computes data keeps working. When you want the params as well, spread them in: { ...ctx.params, name }.
Each connection finds its route's handlers by the identity of its ws.data object, which is how one websocket serves every RhythmWs in the process. upgrade must therefore return a new object every time. Returning a shared object throws a TypeError. The default params object, and any object literal, is already fresh.
Rejecting a handshake#
Refuse by writing the response, exactly as an HTTP handler would: error(ctx, status, message?), or any json(ctx) / text(ctx) call. After upgrade returns, the pipeline checks whether a response was written and, if so, skips the upgrade and sends it. Throwing also refuses the handshake and goes through the app's normal error handling.
new RhythmWs().ws("/ws/rooms/:id", {
upgrade(ctx) {
const user = ctx.request.headers.get("x-user");
if (!user) return error(ctx, 401);
if (!canJoin(user, ctx.params.id)) return error(ctx, 403, "Not your room");
return { user, room: ctx.params.id };
},
});error(ctx) returns void, so return error(ctx, 401) keeps ws.data inferred from the object you return: handlers still see { user: string; room: string }. Write return error(ctx, ...) rather than a bare return; after it, which would widen the data type to object.
Handshake headers and subprotocols#
The optional headers member adds headers to the 101 Switching Protocols response: a HeadersInit, or a function of the request context (async allowed) when the value depends on the connection. Subprotocol negotiation and upgrade-time cookies live here:
new RhythmWs().ws("/ws/feed", {
headers: (ctx) => ({
"sec-websocket-protocol": ctx.request.headers.get("sec-websocket-protocol")?.split(",")[0]?.trim() ?? "",
}),
open(peer) {
peer.send("ready");
},
});
// new WebSocket(url, ["json", "text"]) negotiates socket.protocol === "json"The function runs after upgrade, and a response written there rejects the handshake just like in upgrade.
Mutable connection state#
ws.data is one plain object per connection and handlers share it, so it doubles as connection-scoped state. Declare the shape in the hook and mutate it later:
upgrade: () => ({ room: undefined as string | undefined }),
message(peer, message) {
peer.data.room = String(message); // allowed: the field is typed as string | undefined
},The rooms page builds its join-by-message pattern on exactly this.