WS Control Protocol

WS 控制通道协议

UTF-8 JSON 文本帧（非二进制）。call 与 HTTP POST 同 path、同 body；另支持事件订阅。

前提： control_enabled: true 且 control_transport: ws。

版本	握手鉴权
2.5 main	?key=<control_token> 或 X-Control-Token
2.6 preview	Authorization: Bearer 或 X-SLDataAPI-Key（无 URL token）

路径：ws://<host>:8081/control（别名 /ws/control）。

control_transport: http 时握手 404 + {"code":"transport_mismatch","use":"http"}。

---

连接示例

2.6：

const ws = new WebSocket("ws://127.0.0.1:8081/control", {
  headers: { Authorization: "Bearer YOUR_API_KEY" }
});
// 浏览器无法自定义头时，用支持头的客户端（Node/wscat 等）

2.5：

const ws = new WebSocket("ws://127.0.0.1:8081/control?key=YOUR_CONTROL_TOKEN");

---

消息类型

hello（S→C）

{"type":"hello","server":"SLDataAPI","version":"2.6.0.0","endpoints":"/control/*"}

ping / pong

建议每 25s 发 {"type":"ping"}；90s 无入站消息断连。

call / result

{"type":"call","reqId":"c1","path":"/control/console/command","body":{"command":"help"}}

2.5 path 示例：/control/command。2.6 见 Preview-HTTP-API。

成功：

{"type":"result","reqId":"c1","ok":true,"status":200,
 "data":{"success":true,"message":"已执行","data":{...}}}

业务失败：ok:false，status 为 HTTP 语义（400/403/404…）。并发超限：status:429。

reqId 连接内唯一；结果可乱序。

协议错误：

{"type":"error","message":"未知消息类型: xxx（支持 ping / subscribe_events / call）"}

subscribe_events / unsubscribe_events

{"type":"subscribe_events"}

确认：events_subscribed / events_unsubscribed。
2.6 需 Key 含 ws:subscribe_events 权限。

event（S→C）

{"type":"event","event":"round_started","utc":"...","data":{...}}

event	data 要点
round_started / round_ended	started_at / leading_team 等
player_joined / player_left	nickname, userid
player_died	old_role, 可选攻击者
elevator_used	elevator_group
door_opened	door, can_open

断开期间事件不补发；重连后需重新订阅。

---

限制

项	值
全局连接	8
单连接并发 call	4
单消息	256KB
空闲	90s
分片组装	30s

握手 / 关闭码

码	含义
HTTP 401	鉴权失败 / 锁定
HTTP 403	2.6：Key 无 WS 权限等
HTTP 404	未启用 / HTTP 模式互斥
HTTP 503	连接满
WS 1008	分片超时
WS 1009	消息过大