看板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。

最后更新于