WebSocket、错误处理与兼容性

WebSocket 地址

实时矿工 Stratum 数据使用：

ws://主机:端口/{安全路径}/api/ws
wss://主机:端口/{安全路径}/api/ws

HTTPS 页面必须使用 wss://。安全路径的拼接规则与 HTTP API 相同。

订阅和心跳

订阅矿工组：

{
  "type": "subscribe",
  "group_id": "<矿工 gid>"
}

前端每 10 秒发送一次心跳：

{
  "type": "ping"
}

服务端可以返回字符串 pong、{ "type": "pong" }，或在 body 中包含 pong。

取消订阅和关闭：

{
  "type": "unsubscribe",
  "group_id": "<矿工 gid>"
}

{
  "type": "close"
}

消息可能是字符串、JSON 对象，或 { type, body } 包装结构。矿工标识可能位于 workerID、workerId、worker_id、sid 或 id。

HTTP 错误处理

调用端至少应处理：

修改 Web 端口、安全路径、TLS 或证书时，服务重启可能让当前请求没有响应。此类接口需要结合新地址是否可访问判断最终状态。

当前前端定义但未调用

这些接口不能仅凭前端常量判断 HTTP 方法、权限和响应结构，因此本版文档不把它们列为稳定接口。只有在目标实例的实际响应确认后再使用。

版本兼容建议

• 启动时先调用 /api/local/version，按版本启用可选功能。
• 对新增响应字段保持宽松解析，不依赖字段顺序。
• 不要把 GET、POST、DELETE 相同路径视为同一操作。
• 币种、协议和状态枚举应从 /api/currency/config 或当前响应读取。
• API Key、Access Token、观察者 TOKEN 和群控 API 应分别管理。

响应兼容处理

建议按以下顺序解析 HTTP 响应：

1. 先检查 HTTP 状态和 Content-Type，但允许标量 JSON 和纯文本。
2. 若对象同时含 status 和 data，按 PoolNode 包装处理；status !== 0 时读取 error。
3. 普通对象错误优先读取 message，其次 error，最后保留脱敏后的原始文本。
4. 数组接口在无数据时应接受 []；不能把空数组当作请求失败。
5. 图表数值和时间点允许为 null；分页接口以响应的 page、size、pages、total 为准。
6. 写操作若因端口、TLS、证书或路径切换而无响应，先以新地址执行只读验证，不要立即重复提交。

客户端应保存请求方法、路径模板、HTTP 状态和业务状态用于诊断，但不得记录 Access Token、观察者 TOKEN、群控 TOKEN、钱包、证书私钥或完整收益数据。