WebSocket server: attach ws upgrade to Express #33

New issue

Open

opened 2026-04-19 07:23:36 +00:00 by forgejo-lila · 0 comments

forgejo-lila commented

2026-04-19 07:23:36 +00:00

Owner

Context

Multiplayer requires real-time bidirectional communication. The project uses the ws library (not Socket.io) — see documentation/decisions.md.

What to do

Attach a WebSocket upgrade handler to the existing Express HTTP server.

Files to change

apps/api/src/server.ts — change app.listen() to use createServer(app). Attach ws.Server via the upgrade event.
apps/api/src/ws/index.ts — new file. WebSocket server setup.
apps/api/package.json — add ws and @types/ws.

Implementation outline

import { WebSocketServer } from 'ws';
import { createServer } from 'http';

const server = createServer(app);
const wss = new WebSocketServer({ noServer: true });

server.on('upgrade', (request, socket, head) => {
  // Auth validation happens here (see WS auth middleware issue)
  wss.handleUpgrade(request, socket, head, (ws) => {
    wss.emit('connection', ws, request);
  });
});

server.listen(PORT);

Acceptance criteria

WebSocket connections can be established to wss://api.lilastudy.com
Existing REST API continues working on the same port
Connection/disconnection events are logged
WebSocket server is exported for use by handlers

Notes

Caddy automatically proxies WebSocket connections — no config change needed. When Caddy sees an Upgrade: websocket header, it forwards it.

## Context Multiplayer requires real-time bidirectional communication. The project uses the `ws` library (not Socket.io) — see `documentation/decisions.md`. ## What to do Attach a WebSocket upgrade handler to the existing Express HTTP server. ## Files to change - `apps/api/src/server.ts` — change `app.listen()` to use `createServer(app)`. Attach `ws.Server` via the `upgrade` event. - `apps/api/src/ws/index.ts` — new file. WebSocket server setup. - `apps/api/package.json` — add `ws` and `@types/ws`. ## Implementation outline ```typescript import { WebSocketServer } from 'ws'; import { createServer } from 'http'; const server = createServer(app); const wss = new WebSocketServer({ noServer: true }); server.on('upgrade', (request, socket, head) => { // Auth validation happens here (see WS auth middleware issue) wss.handleUpgrade(request, socket, head, (ws) => { wss.emit('connection', ws, request); }); }); server.listen(PORT); ``` ## Acceptance criteria - WebSocket connections can be established to `wss://api.lilastudy.com` - Existing REST API continues working on the same port - Connection/disconnection events are logged - WebSocket server is exported for use by handlers ## Notes Caddy automatically proxies WebSocket connections — no config change needed. When Caddy sees an `Upgrade: websocket` header, it forwards it.