# 心跳与断线重连

心跳方式，重连触发条件，退避与整段重放的语义。

来源：https://open.shengzhiai.com/sdk/v2/api/ws-reconnect/

## 心跳

| 端 | 方式 |
|---|---|
| Java，安卓，iOS | 协议层 ping，每 15 秒一次，30 秒收不到 pong 视为断线 |
| 网页，小程序 | 应用层心跳，连接后与开始后每 15 秒发 `{"cmd": "ping"}`，服务端回 `{"event": "pong", "ts": <毫秒>}`，不改变会话状态 |

发出结束帧后服务端在评测，期间不再发应用层心跳，改由终评等待时长判断，默认 300 秒。

## 断线重连语义

服务端不支持会话续传，一个连接就是一个服务端会话。SDK 用新会话加整段重放实现等效续传：

1. 连接意外断开，心跳超时，连接超时，终评超时，或收到可重试的错误帧时，会话进入重连中，按退避等待后建立新连接。
2. 新连接上重发相同参数与同一个幂等键的开始帧，重放这一轮已发的全部音频，补发断线期间排队的音频，结束帧已发出时一并重发。
3. 服务端按幂等键识别重发：首次评测已完成时直接重放首次结果，首次评测仍在进行时最多等 30 秒后重放，不重复评测，不重复计费。
4. 默认连续重连 8 次，等待依次为 0.5，1，2，4，4，4，4，4 秒，约 23 秒内网络恢复即可接上，次数可配置。重连次数用尽时会话以错误结束，错误码 90006。

音频缓冲策略由调用方选择：

| 策略 | 行为 |
|---|---|
| REPLAY，默认 | 缓冲这一轮的全部音频，上限 10 MB，重连后整段重放，评分覆盖全部音频 |
| DROP | 不缓冲，重连期间送入的音频丢弃，新会话只评重连之后的音频 |
| FAIL | 不重连，断线即以错误结束 |

会话状态与回调：

| 状态 | 含义 |
|---|---|
| IDLE | 未连接 |
| CONNECTING | 建立连接中 |
| CONNECTED | 已连接，服务端已发 connected |
| STARTED | 服务端已回 started，可以送音频 |
| ENDING | 结束帧已发出，等待终评 |
| RECONNECTING | 断线后等待重连 |
| COMPLETED | 已收到终评 |
| FAILED | 以错误结束 |
| CANCELLED | 调用方取消 |
| CLOSED | 连接已关闭，会话结束 |

每个会话只触发终评回调与错误回调中的一个，最多一次。调用方主动取消时两者都不触发。连接关闭回调总在最后。任一时刻查询会话状态得到的值，与最近一次状态变化回调给出的新状态一致。

## 重连时序

1. SDK 实时会话 到 开放平台：二进制音频帧
2. 应用代码 到 SDK 实时会话：end()
3. SDK 实时会话 到 开放平台：{"cmd":"end"}
4. 开放平台 到 SDK 实时会话：连接断开，终评未送达，未送达
5. SDK 实时会话 到 应用代码：onStateChanged(RECONNECTING)
6. 说明：退避等待 0.5，1，2，4 秒，最多连续 8 次
7. SDK 实时会话 到 开放平台：新握手，幂等键不变
8. 开放平台 到 SDK 实时会话：{"event":"connected"}
9. SDK 实时会话 到 开放平台：开始帧，参数与幂等键不变
10. 开放平台 到 SDK 实时会话：{"event":"started"}
11. SDK 实时会话 到 开放平台：重放这一轮的全部音频
12. SDK 实时会话 到 开放平台：{"cmd":"end"}
13. 说明：平台按幂等键重放首次结果，不重复评测，不重复计费
14. 开放平台 到 SDK 实时会话：{"event":"result",…,"replayed":true}
15. SDK 实时会话 到 应用代码：onResult(result)

## 会话状态机

- IDLE 到 CONNECTING：调用 streamEvaluate 后建立连接，iOS 为调用 start 后。
- CONNECTING 到 CONNECTED：平台发来 connected，SDK 随即发出开始帧。
- CONNECTED 到 STARTED：平台回 started，开始送音频。
- STARTED 到 ENDING：调用 end，结束帧已发出。
- ENDING 到 COMPLETED：收到终评。
- CONNECTING，CONNECTED，STARTED，ENDING 到 RECONNECTING：断线，心跳超时，连接超时，终评超时或收到可重试的错误帧。
- RECONNECTING 到 CONNECTING：退避等待后重新连接。
- 任一活动状态到 FAILED：不可重试的错误，或重连次数用尽，错误码 90006。
- 任一活动状态到 CANCELLED：调用方取消或关闭客户端。
- COMPLETED，FAILED，CANCELLED 到 CLOSED：连接释放，会话结束。