WorkspaceAccessHost/docs/connection-protocol.md

连接与会话协议

本文定义传输集成时应遵守的行为契约。当前共享核心实现控制权仲裁，消息编码和端点处于集成阶段。

连接状态

Authenticated → Authorized → Acquired → Attached
                                ↑          ↓
                             Reconnect ← Detached

host 工作区归属随创建建立，随显式结束释放。连接断开只改变附着状态。

控制权

• 首次授权连接取得控制权。
• 同身份第二连接提交显式 takeover 请求后，原连接失效。
• 其他身份得到 host 已被占用的响应。
• 每次控制权获取生成新的连接 ID 和递增 generation。
• 每个 broker 实例另有独立 epoch；IPC 集成使用 (epoch, generation, connectionId) 标识控制权。
• WebSocket 关闭、心跳超时或授权失效时，按连接标识撤销控制权。

HostConnectionGate 使用进程内不可伪造的 lease 对象。TryDispatch 在同一临界区中完成校验与同步入队，接管与输入接受存在确定顺序。接管完成后旧 lease 的输入、关闭与释放均被拒绝；接管前已接受的输入按队列顺序执行。真正传输集成应把控制消息与输入交由同一有序派发路径处理。

消息职责

消息	内容与行为
Attach	目标工作区、协议版本、显式接管意图
Input	二进制终端输入，绑定已验证连接与控制权
Resize	有界列数与行数，绑定当前控制权
Output	二进制终端输出与递增序列号
Snapshot	屏幕、光标、终端模式、历史边界和输出序列号
Heartbeat	检测失效连接并触发释放
Detach	结束传输，保留工作区
Terminate	授权后结束工作区进程并释放归属

终端数据按字节传输，控制消息使用独立类型。输入限制、输出缓冲上限、快照一致性和客户端尺寸变化由协议实现和测试固定。传输入口先完成认证授权，再允许升级及访问工作区。