wsHandler

Accept WebSocket connections at the path of a route.ts, and decide per connection whether to keep each one.

import { broadcast, type GioSocket } from '@gio.js/core';

export function wsHandler(socket: GioSocket) {
  const room = socket.params.room ?? 'lobby';    // ws://host/chat/news → 'news'
  socket.join(room);
  socket.send(`welcome to ${room}`);
  socket.on('message', (text) => broadcast(room, String(text)));
}

The Rust server completes the WebSocket upgrade and hands each connection to the Node worker over a pipe of its own, so sockets and HTTP requests never wait on each other. The worker finds the route.ts whose pattern matches the path - with the same rules as pages: [id], [...slug], [[...slug]], (group) folders - and calls its wsHandler once for the connection.

Reference

Parameters

socket (GioSocket) is the connection:

Returns

Behavior

• Before it is accepted a socket receives no route or room broadcasts, even from rooms it already joined; its own socket.send() reaches it (to ask for a token, say).
• Early messages that arrive before any 'message' listener exists are held and delivered to the first one, in order - up to 256 messages or 1 MiB; past that the connection closes with 1008. Messages held for 10 seconds by a handler that neither listens nor finishes are dropped.
• No handler. A connection to a path whose route.ts exports no wsHandler (or with no route.ts at all) closes with 4404 no websocket handler. One to a route.ts that threw while it was imported closes with 1011 and internal error (digest ...).
• Server-side limits come from [websocket] in gio.toml: enabled, max_connections (further connections close with 1013) and ping_interval_secs. A shutdown or a worker restart closes every socket with 1001.
• Origin check. An upgrade whose Origin is another site is refused with 403 before the handler runs, unless the origin is in [security.csrf] trusted_origins or [security.websocket] check_origin = false.

Types

WsHandler is (socket: GioSocket) => void | boolean | Promise<void | boolean>. Both are exported from @gio.js/core.

Examples

Authenticate with the session cookie

import type { GioSocket } from '@gio.js/core';
import { sessions } from '../../lib/session.server.ts';
import { db } from '../../lib/db.server.ts';
import { handle } from '../../lib/live.server.ts';

export async function wsHandler(socket: GioSocket) {
  const userId = sessions.getSession(socket).get('userId');
  if (userId === undefined) return false;               // close 4401 'unauthorized'

  const user = await db.users.find(userId);
  if (user.banned) return socket.close(4403, 'forbidden');

  socket.join(`user:${userId}`);
  socket.on('message', (msg) => handle(user, msg));
}

Wait for a token message

import type { GioSocket } from '@gio.js/core';
import { verifyToken } from '../../lib/tokens.server.ts';

export async function wsHandler(socket: GioSocket) {
  const token = await new Promise<string | null>((resolve) => {
    socket.on('message', (data) => resolve(String(data)));
    setTimeout(() => resolve(null), 5_000);             // never wait forever
  });
  const user = token === null ? null : await verifyToken(token);
  if (user === null) return false;                    // close 4401 'unauthorized'

  socket.send('accepted');
  return true;
}

Publish from an HTTP request

import { broadcast, type RouteHandler } from '@gio.js/core';

export const POST: RouteHandler<'/api/rooms/:room'> = (req) => {
  const delivered = broadcast(req.params.room, JSON.stringify(req.json()));
  return { delivered };                                 // false: no WebSocket server connected
};

Good to know

• Keep an async handler to the decision: a handler that never resolves never accepts. Start long-running work without awaiting it.
• Browsers cannot set headers on a WebSocket, so a cookie (or a first message) is the credential. Avoid long-lived tokens in the URL: URLs end up in logs.
• Rooms and connections are per server instance. Across instances, relay through a shared bus (Redis, NATS, Postgres LISTEN).
• On the client, useWebSocket reconnects with backoff, but not after 1000 or a 4000-4499 close: use 4500-4999 for refusals a retry may fix.
• The same route.ts can also export HTTP method handlers.

Related

• WebSockets - the guide, with close codes
• broadcast
• useWebSocket
• [websocket] and [security.websocket]
• route.ts

Version history