Build Charac server and client with OIDC, SSH sessions, and packages

2026-10-05 14:02:50 +08:00
parent 4bc3552167
commit 0ea679932e
185 changed files with 10653 additions and 772 deletions
@@ -1,39 +1,18 @@
 # 连接与会话协议

-本文定义传输集成时应遵守的行为契约。当前共享核心实现控制权仲裁，消息编码和端点处于集成阶段。
+Server 按工作区管理一个后端 SSH 会话与一个当前输入控制者。CLI 通过 OIDC 登录和 HTTPS 创建工作区，再通过 WebSocket 附着。现已实现一次性 `ls` 验收路径和基本输入、尺寸、输出消息；完整交互终端、屏幕快照和断线自动重连尚未完成。路径见[单域名入口](client-server-transport.md)。

-## 连接状态
+工作区创建时绑定外部身份、目标机器和系统账户。WebSocket 断开只解除附着和输入控制权；运行中的 Server 继续读取 SSH 输出并按有界策略保存状态。同身份可重连；显式接管后旧连接的输入必须被拒绝。其他身份不能附着已有工作区。显式结束或后端 SSH 退出时释放工作区。

-```text
-Authenticated → Authorized → Acquired → Attached
-                                ↑          ↓
-                             Reconnect ← Detached
-```
+`SshWorkspaceManager` 为每个工作区持有 `WorkspaceConnectionGate` 和 SSH 会话；不可伪造的 lease 标识控制权，接管与输入入队在同一临界区排序。独立后台任务持续读取 SSH 输出，最多保留最近 256 KiB、256 个输出块；附着时回放并继续发送。附着客户端的队列有界，满时对 SSH 读取施加背压，避免静默丢失 VT 控制序列；CLI 同时检查输出序号。断线期间的有限历史不是屏幕快照，重新附着后的完整画面恢复尚未实现。客户端 WebSocket 断开只解除附着，不关闭 SSH。

-host 工作区归属随创建建立，随显式结束释放。连接断开只改变附着状态。
-
-## 控制权
-
- 首次授权连接取得控制权。
- 同身份第二连接提交显式 takeover 请求后，原连接失效。
- 其他身份得到 host 已被占用的响应。
- 每次控制权获取生成新的连接 ID 和递增 generation。
- 每个 broker 实例另有独立 epoch；IPC 集成使用 `(epoch, generation, connectionId)` 标识控制权。
- WebSocket 关闭、心跳超时或授权失效时，按连接标识撤销控制权。
-
-`HostConnectionGate` 使用进程内不可伪造的 lease 对象。`TryDispatch` 在同一临界区中完成校验与同步入队，接管与输入接受存在确定顺序。接管完成后旧 lease 的输入、关闭与释放均被拒绝；接管前已接受的输入按队列顺序执行。真正传输集成应把控制消息与输入交由同一有序派发路径处理。
-
-## 消息职责
-
-| 消息 | 内容与行为 |
+| 消息 | 目标行为 |
 | --- | --- |
-| Attach | 目标工作区、协议版本、显式接管意图 |
-| Input | 二进制终端输入，绑定已验证连接与控制权 |
-| Resize | 有界列数与行数，绑定当前控制权 |
-| Output | 二进制终端输出与递增序列号 |
-| Snapshot | 屏幕、光标、终端模式、历史边界和输出序列号 |
-| Heartbeat | 检测失效连接并触发释放 |
-| Detach | 结束传输，保留工作区 |
-| Terminate | 授权后结束工作区进程并释放归属 |
+| Attach / Takeover | 选择工作区并取得或显式接管控制权 |
+| Input / Resize | 经当前 lease 验证后写入 SSH channel，尺寸设定有边界 |
+| Output | 从 SSH channel 持续读取并携带序列号 |
+| Snapshot | 恢复屏幕、光标与历史边界；具体编码待确定 |
+| Heartbeat / Detach | 检测失效连接并解除附着，保持后端 SSH |
+| Terminate | 授权后关闭 SSH 会话及工作区 |

-终端数据按字节传输，控制消息使用独立类型。输入限制、输出缓冲上限、快照一致性和客户端尺寸变化由协议实现和测试固定。传输入口先完成认证授权，再允许升级及访问工作区。
+Server 重启或后端 SSH 连接中断不能仅靠 WebSocket 重连恢复原终端；若需要跨 Server 生命周期的持久终端，应另行设计目标侧会话设施。