# 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.
