43 lines
1.9 KiB
Markdown
43 lines
1.9 KiB
Markdown
# 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.
|