看板WebSocket协议¶
GET /data-dashboards/ws 经过产品身份适配和Upgrade。工作区由workspace_id查询参数或X-Workspace-ID头指定,二者并存须相同,不允许重复或首尾空白。消息内不能切换工作区。
原生客户端可使用认证头;浏览器通过会话或moi-api-key / moi-bearer凭据子协议,另可带经校验的moi-role-id候选。服务端只回显协议名或角色候选,不回显秘密值。无Origin时要求认证头;有Origin时必须单个http/https来源、与请求Host一致且无路径/用户信息/query/fragment。完整握手策略与反向代理行为待环境验证。
消息封套严格只含id、message_type、data;id非空、最多128字节、无Unicode空白或控制字符。以下是源码定义的业务动作:
请求类型 |
data |
对应成功类型 |
|---|---|---|
dashboard_preview_execute |
dashboard_id、sql_text,可选chart_id |
dashboard_preview_result |
dashboard_chart_create |
dashboard_id及图表mutation字段,不能带非空chart_id |
dashboard_chart_create_result |
dashboard_chart_update |
dashboard_id、chart_id及图表mutation字段 |
dashboard_chart_update_result |
ping |
无业务输入 |
pong,回显id |
preclose |
无业务输入 |
关闭连接 |
成功data分别复用SQL预览或图表DTO,不是HTTP code/msg/data封套。
一个连接只运行一个业务动作,独立reader处理心跳与断线。不同id并发请求收到error,data含status=409、code=ErrDataDashboardOperationActive、msg;相同在途id会关闭连接以免混淆终态。不会按id建立持久化去重表,不能用重连后的同id实现幂等。错误消息为message_type=error,data中status为整数、code/msg为字符串;每个业务消息重新建立请求授权上下文。
断线取消上下文,写响应有10秒预算。更新成功后回读失败可直接关闭连接;服务端写入或提交后未收到确认不能断言操作失败。前端将已发送mutation的断线/超时记为结果未知,要求重新读看板详情,不自动重放保存;预览读操作与mutation分开处理。
前端当前握手15秒、心跳30秒、pong等待10秒、业务等待360秒;这些是客户端配置,不是服务端完成时限或生产SLA。