refactor: protocol-agnostic relay server

Replace game-specific protocol (join/state/chat/snapshot) with a
universal relay model. Server manages rooms and connections but treats
game data as opaque payloads — any msgpack client works.

- Auto-join on WebSocket connect (no handshake required)
- Relay messages immediately to peers (no server-side tick loop)
- Remove SNAPSHOT_HZ env var
- New message types: welcome, peer_joined, peer_left, relay, ping/pong

Author: mavisakalyan

.env.example

@@ -4,9 +4,6 @@ PORT=8080
 # Comma-separated allowed origins for WebSocket connections (* = allow all)
 ALLOWED_ORIGINS=*
 
-# Server tick rate — snapshots broadcast per second (20 = 50ms between ticks)
-SNAPSHOT_HZ=20
-
 # WebSocket keepalive ping interval in milliseconds
 KEEPALIVE_MS=30000
 

README.md

@@ -1,6 +1,6 @@
 # bun-ws-gameserver
 
-Production-grade Bun-native WebSocket game server with room-based architecture, binary protocol (msgpack), server-authoritative tick loop, and per-client rate limiting. 5-8x faster than Node.js `ws` — same protocol, same clients.
+Protocol-agnostic Bun-native WebSocket relay server with room-based architecture, binary protocol (msgpack), and per-client rate limiting. 5-8x faster than Node.js `ws` — same protocol, same clients.
 
 [![Deploy on Alternate Futures](https://app.alternatefutures.ai/badge/deploy.svg)](https://app.alternatefutures.ai/deploy/bun-ws-gameserver)
 
@@ -10,9 +10,9 @@ Production-grade Bun-native WebSocket game server with room-based architecture,
 
 - **Bun-native WebSocket** — Uses `Bun.serve()` built-in WebSocket (5-8x faster than Node.js `ws`)
 - **Room-based architecture** — `/ws/:roomId` with auto-created rooms and configurable player caps
+- **Protocol-agnostic relay** — Server relays any msgpack message between peers without inspecting payloads
 - **Binary protocol (msgpack)** — ~40% smaller payloads than JSON
-- **Server-authoritative tick loop** — Configurable Hz for snapshot broadcasting
-- **Player state sync** — Position, rotation, action, and timestamp per player
+- **Instant relay** — Messages forwarded immediately to peers (no server-side batching)
 - **Bun pub/sub** — Built-in topic-based broadcasting for efficient room messages
 - **Zero-allocation per-connection state** — `ws.data` pattern for per-client metadata
 - **Per-client rate limiting** — Sliding window algorithm
@@ -51,31 +51,55 @@ docker run -p 8080:8080 bun-ws-gameserver
 |----------|---------|-------------|
 | `PORT` | `8080` | Server listen port |
 | `ALLOWED_ORIGINS` | `*` | Comma-separated allowed origins |
-| `SNAPSHOT_HZ` | `20` | Tick rate (snapshots/sec) |
 | `KEEPALIVE_MS` | `30000` | Idle timeout (ms) |
 | `MAX_MESSAGES_PER_SECOND` | `60` | Per-client rate limit |
 | `MAX_PLAYERS_PER_ROOM` | `50` | Room capacity |
 
 ## Protocol
 
-Both [`node-ws-gameserver`](https://github.com/alternatefutures/node-ws-gameserver) and `bun-ws-gameserver` use the same **msgpack binary protocol**, so clients are backend-agnostic.
+Both [`node-ws-gameserver`](https://github.com/mavisakalyan/node-ws-gameserver) and `bun-ws-gameserver` use the same **msgpack binary relay protocol**, so clients are backend-agnostic.
 
-### Client → Server
+The server is **protocol-agnostic** — it manages rooms and connections, but treats game data as opaque payloads. Any client that speaks msgpack can use it: multiplayer games, collaborative tools, IoT dashboards, chat apps, etc.
+
+### Connection Flow
+
+1. Client connects to `ws://host/ws/:roomId`
+2. Server auto-assigns a `playerId` and sends `welcome` with list of existing peers
+3. Client sends any msgpack messages — server wraps each in a `relay` envelope and forwards to all other peers
+4. When peers join/leave, server notifies all remaining peers
+
+### Server → Client
 
 ```typescript
-{ type: "join",  payload: { displayName: string } }
-{ type: "state", payload: { position: {x,y,z}, rotation: {x,y,z,w}, action: string } }
-{ type: "chat",  payload: { message: string } }
+// Sent on connect
+{ type: "welcome", playerId: string, peers: string[] }
+
+// Peer lifecycle
+{ type: "peer_joined", peerId: string }
+{ type: "peer_left",   peerId: string }
+
+// Relayed game data from another peer (data is passed through untouched)
+{ type: "relay", from: string, data: any }
+
+// Keepalive response
+{ type: "pong", nonce: string, serverTime: number }
+
+// Errors (rate limit, room full, bad message)
+{ type: "error", code: string, message: string }
 ```
 
-### Server → Client
+### Client → Server
 
 ```typescript
-{ type: "snapshot",      payload: { players: Record<id, PlayerState>, timestamp: number } }
-{ type: "player_joined", payload: { id: string, displayName: string } }
-{ type: "player_left",   payload: { id: string } }
-{ type: "chat",          payload: { id: string, message: string } }
-{ type: "error",         payload: { code: string, message: string } }
+// Optional keepalive
+{ type: "ping", nonce: string }
+
+// ANYTHING ELSE is relayed to all other peers in the room.
+// The server does not inspect or validate your game data.
+// Examples:
+{ type: "position", x: 1.5, y: 0, z: -3.2 }
+{ type: "chat", text: "hello" }
+{ type: "snapshot", pos: [0, 1, 0], rotY: 3.14, locomotion: "run" }
 ```
 
 ### Example Client (browser)
@@ -86,28 +110,38 @@ import { encode, decode } from '@msgpack/msgpack';
 const ws = new WebSocket('ws://localhost:8080/ws/lobby');
 ws.binaryType = 'arraybuffer';
 
-ws.onopen = () => {
-  ws.send(encode({ type: 'join', payload: { displayName: 'Player1' } }));
-};
+let myId: string;
 
 ws.onmessage = (event) => {
   const msg = decode(new Uint8Array(event.data));
-  if (msg.type === 'snapshot') {
-    // Update game state with msg.payload.players
+
+  switch (msg.type) {
+    case 'welcome':
+      myId = msg.playerId;
+      console.log(`Joined as ${myId}, peers:`, msg.peers);
+      break;
+    case 'peer_joined':
+      console.log(`${msg.peerId} joined`);
+      break;
+    case 'peer_left':
+      console.log(`${msg.peerId} left`);
+      break;
+    case 'relay':
+      // msg.from = peer ID, msg.data = whatever they sent
+      handlePeerData(msg.from, msg.data);
+      break;
   }
 };
 
-// Send player state at 30fps
+// Send your game state (any shape you want)
 setInterval(() => {
   ws.send(encode({
-    type: 'state',
-    payload: {
-      position: { x: 0, y: 0, z: 0 },
-      rotation: { x: 0, y: 0, z: 0, w: 1 },
-      action: 'idle',
-    },
+    type: 'position',
+    x: Math.random() * 10,
+    y: 0,
+    z: Math.random() * 10,
   }));
-}, 33);
+}, 50);
 ```
 
 ## Why Bun?
@@ -126,7 +160,7 @@ Same protocol, same clients, same API — just faster.
 
 | Path | Method | Description |
 |------|--------|-------------|
-| `/ws/:roomId` | WS | WebSocket game connection (default room: "lobby") |
+| `/ws/:roomId` | WS | WebSocket connection (default room: "lobby") |
 | `/health` | GET | Health check — status, rooms, connections, uptime |
 | `/metrics` | GET | Detailed metrics — memory, messages/sec per room |
 

docker-compose.yml

@@ -8,7 +8,6 @@ services:
     environment:
       - PORT=8080
       - ALLOWED_ORIGINS=${ALLOWED_ORIGINS:-*}
-      - SNAPSHOT_HZ=${SNAPSHOT_HZ:-20}
       - KEEPALIVE_MS=${KEEPALIVE_MS:-30000}
       - MAX_MESSAGES_PER_SECOND=${MAX_MESSAGES_PER_SECOND:-60}
       - MAX_PLAYERS_PER_ROOM=${MAX_PLAYERS_PER_ROOM:-50}

src/health.ts

@@ -10,7 +10,7 @@ export interface HealthInfo {
 
 export interface MetricsInfo {
   uptime: number;
-  rooms: Record<string, { players: number; messagesPerSecond: number; running: boolean }>;
+  rooms: Record<string, { players: number; messagesPerSecond: number }>;
   totalConnections: number;
   memory: {
     rss: number;
@@ -50,11 +50,10 @@ export function getMetricsResponse(rooms: Map<string, Room>): Response {
 
   for (const [id, room] of rooms) {
     totalConnections += room.playerCount;
-    roomMetrics[id] = {
-      players: room.playerCount,
-      messagesPerSecond: room.messagesPerSecond,
-      running: room.isRunning,
-    };
+      roomMetrics[id] = {
+        players: room.playerCount,
+        messagesPerSecond: room.messagesPerSecond,
+      };
   }
 
   const metrics: MetricsInfo = {

src/index.ts

@@ -7,7 +7,6 @@ import { getHealthResponse, getMetricsResponse } from './health';
 
 const PORT = Number(process.env.PORT) || 8080;
 const ALLOWED_ORIGINS = (process.env.ALLOWED_ORIGINS || '*').split(',').map(s => s.trim());
-const SNAPSHOT_HZ = Number(process.env.SNAPSHOT_HZ) || 20;
 const KEEPALIVE_MS = Number(process.env.KEEPALIVE_MS) || 30000;
 const MAX_MESSAGES_PER_SECOND = Number(process.env.MAX_MESSAGES_PER_SECOND) || 60;
 const MAX_PLAYERS_PER_ROOM = Number(process.env.MAX_PLAYERS_PER_ROOM) || 50;
@@ -21,13 +20,12 @@ const rateLimiter = new RateLimiter(MAX_MESSAGES_PER_SECOND);
 export interface WSData {
   clientId: string;
   roomId: string;
-  joined: boolean;
 }
 
 function getOrCreateRoom(roomId: string): Room {
   let room = rooms.get(roomId);
   if (!room) {
-    room = new Room(roomId, MAX_PLAYERS_PER_ROOM, SNAPSHOT_HZ);
+    room = new Room(roomId, MAX_PLAYERS_PER_ROOM);
     rooms.set(roomId, room);
   }
   return room;
@@ -65,7 +63,7 @@ const server = Bun.serve<WSData>({
       const clientId = crypto.randomUUID();
 
       const upgraded = server.upgrade(req, {
-        data: { clientId, roomId, joined: false } satisfies WSData,
+        data: { clientId, roomId } satisfies WSData,
       });
 
       if (!upgraded) {
@@ -88,7 +86,13 @@ const server = Bun.serve<WSData>({
     sendPings: true,
 
     open(ws) {
-      // Connection opened — waiting for "join" message
+      // Auto-join room on connect
+      const { clientId, roomId } = ws.data;
+      const room = getOrCreateRoom(roomId);
+      const joined = room.join(clientId, ws);
+      if (!joined) {
+        ws.close(1013, 'Room full');
+      }
     },
 
     message(ws, message) {
@@ -98,7 +102,8 @@ const server = Bun.serve<WSData>({
       if (!rateLimiter.allow(clientId)) {
         ws.sendBinary(encodeMessage({
           type: 'error',
-          payload: { code: ErrorCodes.RATE_LIMITED, message: 'Rate limited' },
+          code: ErrorCodes.RATE_LIMITED,
+          message: 'Rate limited',
         }));
         return;
       }
@@ -112,41 +117,26 @@ const server = Bun.serve<WSData>({
       if (!decoded) {
         ws.sendBinary(encodeMessage({
           type: 'error',
-          payload: { code: ErrorCodes.INVALID_MESSAGE, message: 'Invalid message format' },
+          code: ErrorCodes.INVALID_MESSAGE,
+          message: 'Invalid message format',
         }));
         return;
       }
 
-      const room = getOrCreateRoom(roomId);
-
-      switch (decoded.type) {
-        case 'join': {
-          if (ws.data.joined) break;
-          const displayName = (decoded.payload.displayName || 'Anonymous').slice(0, 32);
-          const success = room.join(clientId, ws, displayName);
-          if (success) {
-            ws.data.joined = true;
-          }
-          break;
-        }
-
-        case 'state': {
-          if (!ws.data.joined) {
-            ws.sendBinary(encodeMessage({
-              type: 'error',
-              payload: { code: ErrorCodes.NOT_JOINED, message: 'Send a "join" message first' },
-            }));
-            break;
-          }
-          room.updatePlayerState(clientId, decoded.payload);
-          break;
-        }
+      // Handle ping
+      if (decoded.type === 'ping' && typeof decoded.nonce === 'string') {
+        ws.sendBinary(encodeMessage({
+          type: 'pong',
+          nonce: decoded.nonce,
+          serverTime: Date.now(),
+        }));
+        return;
+      }
 
-        case 'chat': {
-          if (!ws.data.joined) break;
-          room.chat(clientId, decoded.payload.message);
-          break;
-        }
+      // Everything else is game data — relay to peers
+      const room = rooms.get(roomId);
+      if (room) {
+        room.relay(clientId, decoded);
       }
     },
 
@@ -167,6 +157,14 @@ const server = Bun.serve<WSData>({
   },
 });
 
+// ─── Periodic metrics update ─────────────────────────────────────
+
+setInterval(() => {
+  for (const room of rooms.values()) {
+    room.updateMetrics();
+  }
+}, 1000);
+
 // ─── Rate limiter cleanup ────────────────────────────────────────
 
 setInterval(() => {
@@ -179,4 +177,4 @@ console.log(`[bun-ws-gameserver] Listening on port ${server.port}`);
 console.log(`[bun-ws-gameserver] WebSocket endpoint: ws://localhost:${server.port}/ws/:roomId`);
 console.log(`[bun-ws-gameserver] Health: http://localhost:${server.port}/health`);
 console.log(`[bun-ws-gameserver] Metrics: http://localhost:${server.port}/metrics`);
-console.log(`[bun-ws-gameserver] Config: ${SNAPSHOT_HZ}Hz tick, ${MAX_PLAYERS_PER_ROOM} max/room, ${MAX_MESSAGES_PER_SECOND} msg/s limit`);
+console.log(`[bun-ws-gameserver] Config: ${MAX_PLAYERS_PER_ROOM} max/room, ${MAX_MESSAGES_PER_SECOND} msg/s limit`);