OMI Multiplayer

OMI was built to put real-time networking, secure backend design, WebSocket communication, deployment, and cloud infrastructure into practice on a project a real person actually plays, not a toy exercise. Underneath a traditional Sri Lankan trick-taking card game sits a Node.js and Express server holding the authoritative game state, a Socket.IO transport layer, a modular service layer, a swappable persistence layer, and a continuous-deployment pipeline running behind Cloudflare on Northflank.

The game itself (2, 3, and 4 player modes, bots, a real persistent shuffled deck, a live leaderboard) is genuine and fully playable at omi.nodenull.org. But the engineering underneath, the same code path that has to survive a reverse proxy, a hostile Origin header, a flooding client, and a redeploy without dropping a single in-progress match, is the actual subject of this case study.

Socket.IO connection flow. A browser opens GET /socket.io/ with an Upgrade: websocket header, which Cloudflare and Northflank both proxy through unmodified. Before the handshake completes, the server's own allowRequest() checks the request's Host and Origin headers; only after both pass does the connection receive 101 Switching Protocols and become a live socket.

Server broadcasts vs. client-specific state. Public state (whose turn it is, the cards on the table, the score) is broadcast to the whole room; each player's hand is emitted only to that player's own socket. The client never receives, and therefore cannot leak or tamper with, another player's cards.

Reverse proxy awareness. Every request Express sees technically originates from Northflank's internal network, not the player's browser, so the app has to be told which hop to trust for the real client address and protocol. app.set('trust proxy', TRUST_PROXY) (default 1) tells Express how many proxy hops to trust when reading X-Forwarded-For and X-Forwarded-Proto. Getting this wrong in either direction breaks something real: too few hops trusted and every player appears to share Northflank's own IP (rate limiting punishes everyone together); too many and a spoofed forwarded header would be trusted blindly.

LAN address detection. For LAN hosting, the server has to find its own reachable address without being told one. A lot of dev machines carry several network interfaces at once (Wi-Fi, Ethernet, plus virtual adapters from VirtualBox, VMware, Hyper-V, WSL, Docker, and VPN clients), and the naive "first non-internal IPv4" approach often picks a virtual adapter that no other device on the network can actually reach.

QR-code joining. When the host opens the lobby, a QR code encoding the join URL is generated on the spot (the terminal also prints a scannable code and the link when the server starts). In production, the QR encodes the configured PUBLIC_URL instead of a detected LAN address, and a friendlier hostname.local (mDNS) address is offered as a fallback where the network supports it.

Host header validation stops DNS rebinding: a malicious page could resolve its own domain to a LAN IP and script requests straight at the server. Every request is checked before anything else runs.

WebSocket origin validation stops cross-site WebSocket hijacking: raw WebSockets ignore CORS entirely, so without this check any page on the internet could open a socket straight into a live game.

Continuous deployment. The app deploys straight from the GitHub repository with no Dockerfile: Northflank's buildpack detects Node.js from package.json (the engines.node field pins the version), installs dependencies, and runs npm start. Every push to main triggers an automatic rebuild and redeploy.

Trusting the reverse proxy. Cloudflare adds X-Forwarded-For and X-Forwarded-Proto before handing the request to Northflank's own proxy; Express reads those headers only because app.set('trust proxy', TRUST_PROXY) tells it exactly how many hops to trust, which is what lets req.ip resolve to the real client address and req.protocol correctly report https even though the last hop inside Northflank's private network is plain HTTP.

The portfolio and the game coexist under the same root domain purely through subdomain routing: Cloudflare's DNS and TLS layer is shared, but the two are otherwise independent deployments with independent infrastructure, so a redeploy of one never touches the other.

The separation is deliberate: game logic (game.js) has zero knowledge of Socket.IO, transport (gameManager.js) has zero knowledge of SQL, and persistence (database/) is swappable behind a three-method interface (submit, top, close) that both the SQLite and JSON-file backends implement identically, which is exactly what makes the planned move to Turso a storage-layer change only (see Limitation below).