Scott.Idem/OSIT-AE-API-FastAPI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

V3 WebSocket: wire auth dependency, add heartbeat presence refresh, update frontend guide (wss://, auth query params, schema clarifications)

Browse Source
This commit is contained in:
Scott Idem
2026-03-11 15:21:19 -04:00
parent 8c7263fdbf
commit 32b519c507
2 changed files with 60 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
documentation/GUIDE__AE_API_V3_for_Frontend_websockets.md
View File

@@ -22,14 +22,33 @@ This guide explains how to implement real-time communication using the **Aether
The V3 WebSocket path requires both a `group_id` and a `client_id` (using **Vision ID** random strings).
```text
ws://[api_domain]/v3/ws/group/{group_id}/client/{client_id}
wss://[api_domain]/v3/ws/group/{group_id}/client/{client_id}
```
### B. Connection Example (TypeScript)
> Use `ws://` for local development and `wss://` in production (any HTTPS site). The Nginx config must include the Upgrade block — see Section 6.
### B. Authentication
Browsers **cannot** set custom HTTP headers on WebSocket connections. Pass the API Key and account context as **query parameters** instead:
| Parameter | Purpose | Example |
| :--- | :--- | :--- |
| `api_key` | Entry Ticket (machine auth) | `?api_key=<your_app_key>` |
| `jwt` | Visa (user / account context) | `&jwt=<token>` |
| `x_account_id` | Alt account context | `&x_account_id=<account_id>` |
**Full example URL:**
```text
wss://dev-api.oneskyit.com/v3/ws/group/{group_id}/client/{client_id}?api_key=<key>&jwt=<token>
```
### C. Connection Example (TypeScript)
```ts
const group_id = "group_abc123"; // Random ID
const client_id = "device_xyz789"; // Random ID
const ws_url = `ws://api.oneskyit.com/v3/ws/group/${group_id}/client/${client_id}`;
const group_id = "group_abc123"; // Random Vision ID
const client_id = "device_xyz789"; // Random Vision ID
const api_key = import.meta.env.VITE_API_KEY;
const jwt = getSessionToken(); // your JWT helper
const ws_url = `wss://dev-api.oneskyit.com/v3/ws/group/${group_id}/client/${client_id}?api_key=${api_key}&jwt=${jwt}`;
const socket = new WebSocket(ws_url);
@@ -47,16 +66,18 @@ All messages sent and received over V3 must follow the standardized **WS_Message
### Message Fields
| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `version` | string | Auto | Always `"3"`. |
| `version` | string | Auto | Always `"3"`. Set by server. |
| `msg_type` | string | Yes | `'msg'`, `'cmd'`, `'heartbeat'`, `'presence'` |
| `target` | string | Yes | `'direct'`, `'group'`, `'broadcast'`, `'echo'` |
| `from_id` | string | No* | Client ID of sender (Auto-filled by server if omitted). |
| `to_id` | string | No | Target Client ID (Required for `target: 'direct'`). |
| `group_id` | string | No* | Target Group ID (Auto-filled by server if omitted). |
| `from_id` | string | Auto | **Server fills this from the URL path** — do not send. |
| `to_id` | string | Conditional | Target Client ID. Required when `target` is `'direct'`. |
| `group_id` | string | Auto | **Server fills this from the URL path** — do not send. |
| `cmd` | string | No | Specific action keyword (e.g., `'RELOAD'`). |
| `msg` | string | No | Human-readable text content. |
| `payload` | object | No | Flexible key-value data. |
| `sent_at` | string | Auto | ISO 8601 Timestamp. |
| `sent_at` | string | Auto | ISO 8601 Timestamp. Set by server. |
> **Frontend tip:** Only send `msg_type`, `target`, and whatever content fields you need (`msg`, `cmd`, `payload`, `to_id`). The server enforces `from_id`, `group_id`, and `sent_at` from the connection context, preventing spoofing.
---
@@ -121,7 +142,12 @@ Used for remote control or orchestration.
```
### Heartbeats (`heartbeat`)
Keep the connection alive and refresh presence in the backend. Should be sent every 30-60 seconds.
Keep the connection alive and **refresh presence** in the backend. Should be sent every 30-60 seconds.
- The server intercepts `heartbeat` messages and refreshes the Redis presence TTL (1 hour window) before echoing back.
- Without periodic heartbeats, a client idle for >1 hour may disappear from the presence set even while still connected.
- Use `target: 'echo'` so the server sends the heartbeat straight back — useful for measuring round-trip latency.
```json
{
"msg_type": "heartbeat",