244 lines
13 KiB
Markdown
244 lines
13 KiB
Markdown
# LSP Core 生命周期、调度与传输设计
|
||
|
||
## 背景
|
||
|
||
`lsp.core.server` 当前用两个布尔值表达服务器生命周期，导致初始化前可以
|
||
`shutdown`、可以重复 `initialize`，且 `shutdown` 响应后立即结束主循环，
|
||
没有按 LSP 要求等待 `exit`。普通请求在输入线程同步执行，因此服务器执行
|
||
Provider 时无法读取 `$/cancelRequest`；现有取消入口没有实际取消逻辑。
|
||
|
||
消息入口和 Dispatcher 还存在几类协议边界问题：非法 JSON 与非法请求只记录
|
||
日志，Provider 异常没有生成请求错误响应，依赖缺失或序列化失败使用 `"{}"`
|
||
伪响应，`Content-Length` 解析宽松且没有消息大小上限。生命周期 callback 在
|
||
锁内执行，也允许重入死锁。诊断发布器虽然暂未启用，但会把 Tree-sitter 的
|
||
UTF-8 字节列直接作为 LSP UTF-16 character。
|
||
|
||
本设计直接建立严格、单一的 LSP 3.17 行为，不保留原 API、旧生命周期行为、
|
||
宽松 framing、Provider 形式的 `exit`/`$/cancelRequest` 或任何兼容适配层。
|
||
|
||
## 目标
|
||
|
||
- 用显式状态机约束 `initialize`、`shutdown` 与 `exit`。
|
||
- 正常关闭等待 `exit`，并向进程入口返回准确退出码。
|
||
- 让输入线程在普通请求执行期间继续读取取消通知。
|
||
- 按请求实例精确取消，区分整数 ID 与字符串 ID。
|
||
- 为请求解析、状态、Provider 异常和取消生成规范 JSON-RPC 错误。
|
||
- 让 Dispatcher 构造后立即有效，不存在后注入依赖或伪响应。
|
||
- 严格验证 LSP framing，遇到不可恢复的传输错误立即终止。
|
||
- 删除已无必要的生命周期 callback 及其锁内调用路径。
|
||
- 将诊断位置转换为 LSP UTF-16 坐标。
|
||
- 删除无调用函数、重复错误构造和无效兜底代码。
|
||
|
||
## 非目标
|
||
|
||
- 不兼容旧的 `LspServer::Run()`、Dispatcher 默认构造或依赖 setter。
|
||
- 不接受非 LSP 3.17 framing，也不尝试从流错位中恢复。
|
||
- 不为已删除的 `shutdown`、`exit`、`cancelRequest` Provider 保留转发层。
|
||
- 不保证强制中断任意 Provider；运行中取消仍遵循 `std::stop_token` 的协作式
|
||
语义。
|
||
- 不启用当前关闭的诊断发布能力，只保证其坐标在以后启用时正确。
|
||
|
||
## 生命周期所有权
|
||
|
||
生命周期只由 `LspServer` 管理，不再由 Provider 通过 callback 间接修改。
|
||
删除 `ServerLifecycleEvent`、`LifecycleCallback`、Dispatcher 的生命周期 callback
|
||
注册与通知，以及 `ExecutionContext::TriggerLifecycleEvent`。`initialize` 的
|
||
Provider 只负责初始化参数、manager 状态和能力响应；`shutdown`、`exit` 与
|
||
`$/cancelRequest` 都由 core 直接处理，不再注册为 Provider。
|
||
|
||
服务器使用以下状态：
|
||
|
||
```cpp
|
||
enum class ServerState
|
||
{
|
||
kUninitialized,
|
||
kRunning,
|
||
kShutdownRequested,
|
||
kExiting,
|
||
};
|
||
```
|
||
|
||
状态只在输入线程修改，因此不使用原子布尔值：
|
||
|
||
| 当前状态 | 输入 | 行为 | 新状态 |
|
||
| --- | --- | --- | --- |
|
||
| `kUninitialized` | `initialize` | 同步执行并发送成功响应 | `kRunning` |
|
||
| `kUninitialized` | 其他请求 | `ServerNotInitialized` | 不变 |
|
||
| `kUninitialized` | `exit` | 结束主循环，返回 1 | `kExiting` |
|
||
| `kRunning` | 重复 `initialize` | `InvalidRequest` | 不变 |
|
||
| `kRunning` | `shutdown` | 取消并等待普通请求，关闭 manager，发送响应 | `kShutdownRequested` |
|
||
| `kRunning` | `exit` | 结束主循环，返回 1 | `kExiting` |
|
||
| `kShutdownRequested` | `exit` | 结束主循环，返回 0 | `kExiting` |
|
||
| `kShutdownRequested` | 请求 | `InvalidRequest` | 不变 |
|
||
| `kShutdownRequested` | 其他通知 | 忽略并记录 | 不变 |
|
||
|
||
`initialize` 只有在 Provider 正常返回并成功发送响应后才转换状态；异常或错误
|
||
响应不推进状态。`shutdown` 完成请求排空和 manager shutdown 并成功发送响应后
|
||
才转换状态。`initialized` 只在 `kRunning` 接受。EOF、短消息体和 framing 错误
|
||
均属于非正常退出，返回 1。
|
||
|
||
`LspServer::Run()` 改为返回 `int`。launcher 直接使用该退出码，不再在
|
||
`Run()` 返回后无条件报告“正常停止”。`exit` Provider 中的 sleep 和
|
||
`std::exit()` 被删除，进程退出统一沿 `Run()` → launcher → `main()` 返回。
|
||
无论收到正常或异常 `exit`，core 都先取消并等待仍活动的普通请求，再从
|
||
`Run()` 返回；异常 EOF/framing 路径执行相同的任务收尾，但不把它误报为正常
|
||
关闭。
|
||
|
||
## 请求执行与取消
|
||
|
||
`initialize`、`shutdown` 在输入线程同步执行，因为它们改变全局生命周期。
|
||
普通请求提交给 `AsyncExecutor`。`exit` 与 `$/cancelRequest` 是 core 控制消息，
|
||
在输入线程立即处理；其他通知仍按输入顺序同步分发，避免 `didOpen`、
|
||
`didChange` 与后续请求发生人为重排。
|
||
|
||
请求键保留 ID 类型：
|
||
|
||
- 整数 ID `1` 映射为 `i:1`。
|
||
- 字符串 ID `"1"` 映射为 `s:1`。
|
||
|
||
任务 ID 使用 core 专属前缀，例如 `lsp-request:i:1`，避免与 Provider 自己提交
|
||
的后台任务冲突。服务器在 mutex 保护的映射中保存
|
||
`request key -> shared request state`，其中包含该请求的 `TaskHandle`。输入线程
|
||
先登记 request state，再调用 `Submit`，并在重新读取输入前绑定返回的 handle；
|
||
完成 callback 按 state 身份注销映射。这样快速完成或同步提交失败都不会造成
|
||
“callback 先注销、输入线程后插入”的陈旧句柄，也不需要持有映射锁调用
|
||
`Submit`。同一类型、同一 ID 尚未完成时再次出现，按 `InvalidRequest` 拒绝，
|
||
不替换或误取消旧请求。
|
||
|
||
异步任务调用 Dispatcher 并返回序列化响应。callback 根据 `TaskResult` 统一
|
||
收尾：
|
||
|
||
- `kCompleted`：发送 Provider 响应。
|
||
- `kCancelled`：发送 `RequestCancelled`。
|
||
- `kFailed`：记录原始异常并发送 `InternalError`。
|
||
|
||
`$/cancelRequest` 严格反序列化 `CancelParams`，按带类型的键查找当前句柄并
|
||
调用 `TaskHandle::Cancel()`。找不到或任务已经完成时只记录，不生成通知响应。
|
||
Dispatcher 将当前请求的 `std::stop_token` 放入 `ExecutionContext`；可协作
|
||
取消的 Provider 和 manager 从 context 取得并向长循环传递。任务开始前、
|
||
Provider 返回后都由 `AsyncExecutor` 再检查停止状态，保证已取消请求不会发送
|
||
成功结果。
|
||
|
||
收到合法 `shutdown` 时，服务器先复制全部活动请求句柄，在锁外逐个请求取消
|
||
并等待 callback 完成，再直接调用 `ManagerHub::Shutdown()` 并构造 null result
|
||
响应。这样 manager shutdown 不会与普通请求继续访问共享状态并发发生。等待
|
||
期间不持有请求映射锁或输出锁。
|
||
|
||
## Dispatcher 与错误构造
|
||
|
||
`RequestDispatcher` 构造函数强制接收 `AsyncExecutor&` 和 `ManagerHub&`。
|
||
`LspServer` 按 `ManagerHub`、`AsyncExecutor`、Dispatcher 的依赖顺序声明和构造
|
||
成员。删除默认构造、`SetRequestScheduler`、`SetManagerHub`、空指针检查和
|
||
`"{}"` 返回值。
|
||
|
||
Dispatcher 只负责查找 Provider、创建 `ExecutionContext` 并调用 Provider：
|
||
|
||
- 未注册请求生成 `MethodNotFound`。
|
||
- 未注册通知只记录日志。
|
||
- Provider 异常不在 Dispatcher 中吞掉，交给请求任务 callback 转换为
|
||
`InternalError`；通知入口捕获异常并只记录日志。
|
||
|
||
错误响应由一个公共构造函数生成，接收可选 Request ID、错误码和消息。
|
||
Provider 与 server 共用该实现，删除 `SendError` 与
|
||
`BuildErrorResponseMessage` 的重复组装逻辑。已识别请求回显其 ID；无法识别
|
||
ID 时序列化为 `null`。
|
||
|
||
错误响应自身序列化失败视为内部不变量破坏并抛出，不返回 `"{}"`、手写固定
|
||
JSON 或空字符串。外层只在能够构造规范响应时继续运行，不增加第二套序列化
|
||
兜底。
|
||
|
||
## JSON-RPC 消息验证
|
||
|
||
`HandleMessage` 先区分 JSON 语法错误与消息结构错误：
|
||
|
||
| 输入 | 处理 |
|
||
| --- | --- |
|
||
| 非法 JSON | `ParseError`，ID 为 `null` |
|
||
| 合法 JSON，但顶层不是对象 | `InvalidRequest`，ID 为 `null` |
|
||
| JSON 对象但不满足 JSON-RPC 2.0 消息结构 | `InvalidRequest` |
|
||
| 请求可识别 ID，但 Request 反序列化失败 | `InvalidRequest`，回显有效 ID |
|
||
| 合法请求的 Provider 抛异常 | `InternalError`，回显请求 ID |
|
||
| 合法通知的 Provider 抛异常 | 只记录，不发送响应 |
|
||
| 合法客户端响应 | 记录或交给现有响应入口，不回送响应 |
|
||
|
||
请求、通知和响应必须显式携带 `"jsonrpc":"2.0"`。Request ID 只接受协议已
|
||
定义的整数或字符串。响应必须恰好包含 `result` 或 `error` 之一。无法可靠
|
||
分类为请求的非法客户端响应不触发响应，避免形成 response-to-response 循环。
|
||
|
||
## 严格 framing
|
||
|
||
输入只接受 LSP 3.17 header/body framing：
|
||
|
||
- header 行和 header 结束符必须使用 `\r\n`。
|
||
- 必须且只能出现一个 `Content-Length`。
|
||
- 长度使用 `std::from_chars` 解析十进制数字，并要求完整消费字段值。
|
||
- 长度必须大于 0 且不超过 16 MiB。
|
||
- 可接受规范定义的可选
|
||
`Content-Type: application/vscode-jsonrpc; charset=utf-8`；未知、重复或格式
|
||
错误字段视为 framing 错误，不接受旧 charset 拼写。
|
||
- 消息体必须精确读满声明长度。
|
||
|
||
读取结果明确区分“完整消息”“EOF”和“致命 framing 错误”。EOF 或致命错误
|
||
立即退出主循环，不 sleep、不继续扫描、不尝试重新同步流。输出继续由单一
|
||
mutex 串行写入并检查 stream 状态；同步写失败直接向 launcher 传播，异步
|
||
callback 写失败记录 fatal I/O 状态，主循环在下一控制点以 1 退出。
|
||
|
||
## Diagnostics 坐标
|
||
|
||
`lsp.utils.text_coordinates` 增加 Tree-sitter UTF-8 字节点位到 LSP UTF-16
|
||
`Position` 的反向转换。转换按目标行扫描完整 UTF-8 字符，并累计 UTF-16 code
|
||
unit；目标字节列落在多字节字符内部时收敛到该字符起点，超过行尾时收敛到
|
||
行尾。
|
||
|
||
`PublishDiagnostics` 使用该接口分别转换语法错误起止位置，不再直接复制
|
||
`start_column`/`end_column`。转换复用已有 UTF-8 解码规则，不在 server 中
|
||
维护第二套编码逻辑。
|
||
|
||
## 清理范围
|
||
|
||
- 删除 `RequiresSyncProcessing` 与 `CanProcessRequest`，状态策略只保留一个
|
||
实际调用入口。
|
||
- 删除 Dispatcher 生命周期 callback 及其 mutex。
|
||
- 删除不再注册且由 core 直接处理的 `provider/shutdown`、`provider/exit`、
|
||
`provider/cancel_request` Module，并同步 Provider registry 与 CMake Module
|
||
列表。
|
||
- 删除 initialize Provider 的生命周期事件代码。
|
||
- 合并错误响应构造，删除 `"{}"`、固定 JSON、空响应和 sleep 重试兜底。
|
||
- `SetupLogger` 保持独立函数；它职责明确，不属于本次 core 重构。
|
||
|
||
## 测试设计
|
||
|
||
测试遵循 TDD，每项先在旧实现上观察预期失败：
|
||
|
||
- initialize 前普通请求返回 `ServerNotInitialized`。
|
||
- initialize 前 shutdown 被拒绝；重复 initialize 被拒绝。
|
||
- shutdown 响应后仍等待 exit。
|
||
- `shutdown -> exit` 返回 0，直接 exit、shutdown 后 EOF 和普通 EOF 返回 1。
|
||
- 非法 JSON 返回 `ParseError`，非法 JSON-RPC 对象返回 `InvalidRequest`。
|
||
- 未注册请求返回 `MethodNotFound`。
|
||
- 抛异常请求返回 `InternalError`；抛异常通知不产生响应。
|
||
- 普通请求不会阻塞主循环读取 `$/cancelRequest`。
|
||
- 取消整数 ID 与字符串 ID 不冲突，取消只影响对应请求实例。
|
||
- 已取消请求返回 `RequestCancelled`，完成请求不会被迟到取消改写。
|
||
- shutdown 取消并等待所有活动普通请求。
|
||
- 缺失、重复、非数字、部分数字、零、超限 `Content-Length` 和短消息体导致
|
||
非零退出；规范消息仍可连续读取。
|
||
- callback 重入不再存在死锁路径，因为生命周期 callback 机制已删除。
|
||
- 中文和 emoji 前后的 diagnostic character 使用 UTF-16 code unit。
|
||
|
||
优先扩展 `test_provider` 和服务器进程级 JSON 测试，直接验证真实 framing、
|
||
响应和退出码。完成后构建 `tsl-server`，运行 scheduler、provider 与 LSP JSON
|
||
相关测试。已知无关的 AST、symbol、semantic 脚本失败不作为本任务的通过依据。
|
||
|
||
## 完成条件
|
||
|
||
- 生命周期只能沿设计表转换，退出码与关闭顺序一致。
|
||
- 普通请求异步执行，取消通知能在请求运行期间被读取并精确定位任务。
|
||
- 所有请求错误都产生合法 JSON-RPC 响应，通知错误不产生响应。
|
||
- Dispatcher 不存在无效中间状态或伪响应。
|
||
- framing 错误不会进入 sleep/重试/继续读取分支。
|
||
- diagnostics 使用 UTF-16 character。
|
||
- core 中不存在原两个状态 bool、未使用检查函数、空取消分支、生命周期 callback
|
||
或 `"{}"`/固定 JSON 兜底。
|
||
- 相关构建和测试通过，并完成一次针对无效兜底与临时兼容层的专项复审。
|