Dashboard WebSocket protocol¶
GET /data-dashboards/ws passes product identity adaptation and Upgrade. Select the Workspace through workspace_id query or X-Workspace-ID header; if both are present, they must match. Duplicates or surrounding whitespace are forbidden. Messages cannot switch Workspaces.
Native clients may use authentication headers. Browsers use sessions or moi-api-key / moi-bearer credential subprotocols, optionally with a validated moi-role-id candidate. The server echoes only protocol names or role candidates, never secret values. Without Origin, authentication headers are required. With Origin, it must be one http/https origin matching request Host, without path/user information/query/fragment. Full handshake policy and reverse-proxy behavior require environment verification.
Message envelopes strictly contain only id, message_type, and data. id must be nonempty, at most 128 bytes, without Unicode whitespace/control characters. Source-defined business actions follow:
Request type |
data |
Corresponding success type |
|---|---|---|
dashboard_preview_execute |
dashboard_id, sql_text, and optional chart_id |
dashboard_preview_result |
dashboard_chart_create |
dashboard_id and chart mutation fields; no nonempty chart_id |
dashboard_chart_create_result |
dashboard_chart_update |
dashboard_id, chart_id, and chart mutation fields |
dashboard_chart_update_result |
ping |
No business input |
pong, echoing id |
preclose |
No business input |
Close connection |
Successful data reuses SQL preview or chart DTOs respectively, not an HTTP code/msg/data envelope.
A connection runs one business operation at a time, with an independent reader for heartbeats/disconnection. Concurrent requests with different IDs receive error with status=409, code=ErrDataDashboardOperationActive, and msg in data. Reusing an in-flight ID closes the connection to avoid ambiguous terminal results. IDs have no persistent deduplication table; reconnecting with the same ID is not idempotency. Errors use message_type=error, with integer status and string code/msg in data. Every business message rebuilds request authorization context.
Disconnection cancels context; response writes have a 10-second budget. A read-back failure after a successful update may directly close the connection. Missing confirmation after a server write/commit does not establish failure. The frontend treats disconnection/timeouts after sent mutations as unknown outcomes and requires dashboard detail rereads, without automatically replaying saves. Handle preview reads separately from mutations.
Current frontend configuration uses a 15-second handshake, 30-second heartbeat, 10-second pong wait, and 360-second business wait. These are client settings, not server completion limits or production SLAs.