38 lines
No EOL
2.3 KiB
Markdown
38 lines
No EOL
2.3 KiB
Markdown
# Lessons Learned
|
||
|
||
_This document captures the key takeaways and implementation details from today's troubleshooting session._
|
||
|
||
## 1. API Routing & Proxy Configuration
|
||
- **API_BASE constant**: The frontend (`static/script.js`) uses a base path `API_BASE` (default `/api`) to prefix all HTTP and WebSocket calls. Always update this to match your proxy mount point.
|
||
- **Nginx WebSocket forwarding**: To proxy WebSockets, you must forward the `Upgrade` and `Connection` headers:
|
||
```nginx
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
proxy_set_header Connection "upgrade";
|
||
```
|
||
Without these, the WS handshake downgrades to a normal HTTP GET, resulting in 404s.
|
||
|
||
## 2. Debugging WebSocket Traffic
|
||
- Logged all incoming WS frames in `main.py`:
|
||
- `[WS-PLUGIN RX] <client>: <raw>` for messages on `/ws/position`
|
||
- `[WS-LIVE RX] <client>: <parsed-json>` for messages on `/ws/live`
|
||
- These prints surface registration, telemetry, chat, and command packets, aiding root-cause analysis.
|
||
|
||
## 3. Data Serialization Fix
|
||
- Python `datetime` objects are not JSON-serializable by default. We wrapped outbound payloads via FastAPI’s `jsonable_encoder` in `_broadcast_to_browser_clients` so that:
|
||
```python
|
||
data = jsonable_encoder(snapshot)
|
||
await ws.send_json(data)
|
||
```
|
||
This ensures ISO8601 strings for timestamps and eliminates `TypeError: Object of type datetime is not JSON serializable`.
|
||
|
||
## 4. Frontend Adjustments
|
||
- **Chat input positioning**: Moved the `.chat-form` to `position: absolute; bottom: 0;` so the input always sticks to the bottom of its window.
|
||
- **Text color**: Forced the input text and placeholder to white (`.chat-input, .chat-input::placeholder { color: #fff; }`) and forcibly set all incoming messages to white via `.chat-messages div { color: #fff !important; }`.
|
||
- **Padding for messages**: Added `padding-bottom` to `.chat-messages` to avoid new messages being hidden behind the fixed input bar.
|
||
|
||
## 5. General Best Practices
|
||
- Clear browser cache after updating static assets to avoid stale JS/CSS.
|
||
- Keep patches targeted: fix the source of issues (e.g., JSON encoding or missing headers) rather than applying superficial workarounds.
|
||
- Use consistent CSS variables for theming (e.g., `--text`, `--bg-main`).
|
||
|
||
By consolidating these lessons, we can onboard faster next time and avoid repeating these pitfalls. |