# 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
- [x] **Endpoint:** `/ws` (Upgrade Upgrade: websocket).
- [x] **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. [x] Server accepts WebSocket connections on `/ws`.
2. [x] Client (`script.js`) successfully connects to the WebSocket.
3. [x] Server sends a "Hello" or "Ping" packet.
4. [x] Client receives and logs the packet.
5. [x] (Stretch) Stream basic uptime or heartbeat every 5 seconds.

## 5. Implementation Plan
- [x] Modify `src/web/server.ts` to handle `websocket` upgrade in `Bun.serve`.
- [x] Create a message handler object/function to manage connected clients.
- [x] Update `src/web/public/script.js` to initialize `WebSocket`.
- [x] 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.