discord-rpg-concept/tickets/2026-01-07-websocket-realtime-data.md

2026-01-07-websocket-realtime-data

Status: Done Created: 2026-01-07 Tags: feature, websocket, realtime, research

1. Context & User Story

• As a: Developer
• I want to: implement a WebSocket connection between the frontend and the Aurora server
• So that: I can stream real-time data (profiling, logs, events) to the dashboard without manual page refreshes.

2. Technical Requirements

Data Model Changes

• N/A

API / Interface

• Endpoint: /ws (Upgrade Upgrade: websocket).
• Protocol: Define a simple JSON message format (e.g., { type: "UPDATE", data: { ... } }).

3. Constraints & Validations (CRITICAL)

• Bun Support: Use Bun's native Bun.serve({ websocket: { ... } }) capabilities if possible.
• Security: Ensure that the WebSocket endpoint is not publicly abusable (consider simple token or origin check if necessary, though internal usage is primary context for now).
• Performance: Do not flood the client. Throttle updates if necessary.

4. Acceptance Criteria

1. Server accepts WebSocket connections on /ws.
2. Client (script.js) successfully connects to the WebSocket.
3. Server sends a "Hello" or "Ping" packet.
4. Client receives and logs the packet.
5. (Stretch) Stream basic uptime or heartbeat every 5 seconds.

5. Implementation Plan

• Modify src/web/server.ts to handle websocket upgrade in Bun.serve.
• Create a message handler object/function to manage connected clients.
• Update src/web/public/script.js to initialize WebSocket.
• Test connection stability.

Implementation Notes

• Enabled websocket in Bun.serve within src/web/server.ts.
• Implemented a heartbeat mechanism broadcasting HEARTBEAT events every 5s.
• Updated script.js to auto-connect, handle reconnects, and update a visual "online" indicator.
• Added src/web/websocket.test.ts to verify protocol upgrades and messaging.