websockets

WebSockets

One socket per client app, typed end to end. The backend declares events with SocketRouter, the type bridge in src/types/hono/hono-ws-converter.ts turns those declarations into WsSocketSdk, and the client consumes them through socketSdk. No topic string is written twice and nothing is wired by hand.

How a connection works

• src/api/client.ts opens the socket once, at import time, next to the HTTP client: new Socket({ url: \${wsProtocol}://${wsHost}/ws` }). Admin opens a second one on /ws/admin. HyperFetch reconnects on its own. Never hand-roll new WebSocket` or a retry loop.
• Every frame is JSON { topic, data }. Topics are <prefix>/<event> (notification/new, board/op): the prefix comes from .socket("/notification", ...), the event from .emitter() or .listener().
• The backend serves the upgrade at /ws (createWsRoutes) and calls authenticate(headers) in onOpen. null closes the socket with code 4001. The browser sends the session cookie with the upgrade, so socket auth reuses the HTTP session and nothing goes in the URL.
• Connections live in a ConnectionManager per namespace (appWsManager for /ws, adminWsManager for /ws/admin), keyed by user id with the organization id alongside. That registry is what toUser, toOrganization, and broadcast walk. Namespaces never see each other's connections.
• initWebSocket(app) runs before the routes and serveWebsockets(server) after serve() in main.ts. Both are already there. Do not add a second createNodeWebSocket.

Backend: declare events

Event definitions live in src/sockets/<domain>/index.ts, next to but separate from HTTP routes:

import { createSocketRouter } from "@backend/libs/websocket/socket-router";
import { wsValidate } from "@backend/libs/websocket/ws-validate";
import { z } from "zod";

export type WsNotificationPayload = { id: string; title: string; readAt: string | null };

export const notificationSockets = createSocketRouter()
  .emitter("new")<WsNotificationPayload>()
  .listener("mark-read", wsValidate(z.object({ notificationId: z.string() })), async (c) => {
    await markRead({ notificationId: c.data.notificationId, userId: c.userId });
  });