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 creates the socket once, at import time, next to the HTTP client: new Socket({ url: \${wsProtocol}://${wsHost}/ws` }). Admin creates a second one on /ws/admin. HyperFetch connects at startup and reconnects on its own. Never hand-roll new WebSocket` or a retry loop.
• The auth starter binds the socket to the session in features/auth/modules/session-socket/session-socket.ts. Its socket.onConnect interceptor runs before every connection attempt (first connect, automatic and manual reconnect) and calls users/me first: the upgrade authenticates with the session cookie, and only an HTTP request through the auth middleware can rotate an expired access token, so without this a reconnect after an idle hour is refused with 4001 and retried every five seconds for good. A 401 or 403 from that request throws, which abandons the attempt instead of looping for a signed-out visitor. The (private) route guard calls connectSessionSocket in onEnter and disconnectSessionSocket in onLeave (the mobile private layout does the same from an effect), so signing in opens the socket and signing out closes it.
• 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. The upgrade never refreshes that cookie; that is what the session-socket interceptor above is for.
• 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.