@agentunion/kite 1.4.0 → 1.6.0

package/docs/WebSocket/346/216/245/346/224/266/345/276/252/347/216/257/346/255/273/351/224/201/351/230/262/350/214/203/350/247/204/350/214/203.md

@@ -0,0 +1,357 @@
+# WebSocket 接收循环死锁防范规范
+
+**适用范围**：所有 Kite 模块（Python / Node.js / Binary）
+**优先级**：🔴 最高（架构安全）
+**更新时间**：2026-03-10
+
+---
+
+## 问题描述
+
+WebSocket 接收循环中存在一个**经典的死锁陷阱**：
+
+```
+接收循环同步处理消息 → 消息处理函数调用 RPC → 等待 RPC 响应
+→ RPC 响应需要接收循环处理 → 接收循环被阻塞 → 死锁
+```
+
+**症状**：
+- RPC 调用超时（通常 5-10 秒）
+- `system.ping` 响应延迟
+- 模块间通信卡顿
+- 日志显示 "RPC timeout waiting for xxx"
+
+---
+
+## 核心原则（跨语言通用）
+
+### ✅ 必须遵守
+
+**所有消息处理必须异步执行，不可阻塞接收循环**
+
+- **事件通知**（Notification，无 `id`）→ 异步处理
+- **RPC 请求**（Request，有 `id`）→ 异步处理
+- **RPC 响应**（Response，有 `id` + `result`/`error`）→ 同步处理（仅设置 Future/Promise）
+
+### ❌ 严格禁止
+
+- 在接收循环中 `await` / `wait` 任何可能调用 RPC 的函数
+- 在接收循环中执行任何耗时操作（I/O、计算、睡眠）
+- 假设"事件通知不会调用 RPC"（实际上 `system.ping` 会调用 `event.publish`）
+
+---
+
+## 实现模式
+
+### Python (asyncio)
+
+```python
+async def _ws_receiver(self, ws):
+    """WebSocket 接收循环"""
+    async for raw in ws:
+        try:
+            msg = json.loads(raw)
+        except (json.JSONDecodeError, TypeError):
+            continue
+
+        try:
+            has_method = "method" in msg
+            has_id = "id" in msg
+            has_result_or_error = "result" in msg or "error" in msg
+
+            if has_method and not has_id:
+                # 事件通知 — 异步处理（关键！）
+                asyncio.create_task(self._handle_event_notification(msg))
+
+            elif has_method and has_id:
+                # RPC 请求 — 异步处理（关键！）
+                asyncio.create_task(self._handle_rpc_request(ws, msg))
+
+            elif has_id and has_result_or_error:
+                # RPC 响应 — 同步处理（仅设置 Future）
+                rpc_id = msg.get("id")
+                if rpc_id in self._rpc_futures:
+                    self._rpc_futures[rpc_id].set_result(msg)
+
+        except Exception as e:
+            print(f"[module] 消息处理异常（已忽略）: {e}")
+```
+
+**关键点**：
+- 使用 `asyncio.create_task()` 创建后台任务
+- 不要使用 `await handler(msg)`
+- RPC 响应处理只设置 Future，不执行业务逻辑
+
+---
+
+### Node.js (async/await)
+
+```javascript
+async function wsReceiver(ws) {
+  for await (const raw of ws) {
+    let msg;
+    try {
+      msg = JSON.parse(raw);
+    } catch (e) {
+      continue;
+    }
+
+    try {
+      const hasMethod = "method" in msg;
+      const hasId = "id" in msg;
+      const hasResultOrError = "result" in msg || "error" in msg;
+
+      if (hasMethod && !hasId) {
+        // 事件通知 — 异步处理（关键！）
+        handleEventNotification(msg).catch(err => {
+          console.error(`[module] Event handler error: ${err}`);
+        });
+      }
+      else if (hasMethod && hasId) {
+        // RPC 请求 — 异步处理（关键！）
+        handleRpcRequest(ws, msg).catch(err => {
+          console.error(`[module] RPC handler error: ${err}`);
+        });
+      }
+      else if (hasId && hasResultOrError) {
+        // RPC 响应 — 同步处理（仅 resolve Promise）
+        const rpcId = msg.id;
+        if (rpcPending.has(rpcId)) {
+          const { resolve, reject } = rpcPending.get(rpcId);
+          if (msg.error) {
+            reject(new Error(msg.error.message));
+          } else {
+            resolve(msg.result);
+          }
+          rpcPending.delete(rpcId);
+        }
+      }
+    } catch (e) {
+      console.error(`[module] Message handling error (ignored): ${e}`);
+    }
+  }
+}
+```
+
+**关键点**：
+- 调用异步函数但不 `await`，立即添加 `.catch()` 处理错误
+- 不要使用 `await handleEventNotification(msg)`
+- RPC 响应处理只 resolve/reject Promise
+
+---
+
+### Go (goroutines)
+
+```go
+func wsReceiver(ws *websocket.Conn) {
+    for {
+        var msg map[string]interface{}
+        err := ws.ReadJSON(&msg)
+        if err != nil {
+            break
+        }
+
+        _, hasMethod := msg["method"]
+        _, hasId := msg["id"]
+        _, hasResult := msg["result"]
+        _, hasError := msg["error"]
+        hasResultOrError := hasResult || hasError
+
+        if hasMethod && !hasId {
+            // 事件通知 — 异步处理（关键！）
+            go func(m map[string]interface{}) {
+                if err := handleEventNotification(m); err != nil {
+                    log.Printf("[module] Event handler error: %v", err)
+                }
+            }(msg)
+        } else if hasMethod && hasId {
+            // RPC 请求 — 异步处理（关键！）
+            go func(m map[string]interface{}) {
+                if err := handleRpcRequest(ws, m); err != nil {
+                    log.Printf("[module] RPC handler error: %v", err)
+                }
+            }(msg)
+        } else if hasId && hasResultOrError {
+            // RPC 响应 — 同步处理（仅发送到 channel）
+            rpcId := msg["id"].(string)
+            if ch, ok := rpcPending[rpcId]; ok {
+                ch <- msg
+                delete(rpcPending, rpcId)
+            }
+        }
+    }
+}
+```
+
+**关键点**：
+- 使用 `go func()` 启动 goroutine
+- 不要直接调用 `handleEventNotification(msg)`
+- RPC 响应处理只发送到 channel
+
+---
+
+### Rust (tokio)
+
+```rust
+async fn ws_receiver(mut ws: WebSocket) {
+    while let Some(msg) = ws.next().await {
+        let msg = match msg {
+            Ok(Message::Text(text)) => match serde_json::from_str(&text) {
+                Ok(json) => json,
+                Err(_) => continue,
+            },
+            _ => continue,
+        };
+
+        let has_method = msg.get("method").is_some();
+        let has_id = msg.get("id").is_some();
+        let has_result_or_error = msg.get("result").is_some() || msg.get("error").is_some();
+
+        if has_method && !has_id {
+            // 事件通知 — 异步处理（关键！）
+            tokio::spawn(async move {
+                if let Err(e) = handle_event_notification(msg).await {
+                    eprintln!("[module] Event handler error: {}", e);
+                }
+            });
+        } else if has_method && has_id {
+            // RPC 请求 — 异步处理（关键！）
+            let ws_clone = ws.clone();
+            tokio::spawn(async move {
+                if let Err(e) = handle_rpc_request(ws_clone, msg).await {
+                    eprintln!("[module] RPC handler error: {}", e);
+                }
+            });
+        } else if has_id && has_result_or_error {
+            // RPC 响应 — 同步处理（仅发送到 channel）
+            if let Some(rpc_id) = msg.get("id").and_then(|v| v.as_str()) {
+                if let Some(tx) = rpc_pending.lock().unwrap().remove(rpc_id) {
+                    let _ = tx.send(msg);
+                }
+            }
+        }
+    }
+}
+```
+
+**关键点**：
+- 使用 `tokio::spawn()` 创建异步任务
+- 不要使用 `handle_event_notification(msg).await`
+- RPC 响应处理只发送到 channel
+
+---
+
+## 常见错误模式
+
+### ❌ 错误：同步处理事件通知
+
+```python
+# Python
+if has_method and not has_id:
+    await self._handle_event_notification(msg)  # 死锁风险！
+```
+
+```javascript
+// Node.js
+if (hasMethod && !hasId) {
+    await handleEventNotification(msg);  // 死锁风险！
+}
+```
+
+**问题**：如果 `_handle_event_notification` 内部调用了 RPC（如 `event.publish`），会阻塞接收循环。
+
+---
+
+### ❌ 错误：假设事件通知不会调用 RPC
+
+```python
+# 错误的注释
+# 事件通知和 RPC 响应可以同步处理（它们不会反向调用 rpc_call）
+await self._handle_event_notification(msg)
+```
+
+**问题**：`system.ping` 事件处理会调用 `event.publish` 发送 `system.pong`，这是一个 RPC 调用。
+
+---
+
+### ❌ 错误：在接收循环中执行耗时操作
+
+```python
+if has_method and not has_id:
+    # 直接在接收循环中处理业务逻辑
+    event_type = msg["params"]["event"]
+    if event_type == "system.ping":
+        await self._rpc_call("event.publish", {...})  # 死锁！
+```
+
+**问题**：接收循环被阻塞，无法处理 RPC 响应。
+
+---
+
+## 调试方法
+
+### 1. 检查日志中的超时错误
+
+```
+[module] RPC timeout waiting for event.publish
+[module] RPC timeout waiting for launcher.request_client_token
+```
+
+**原因**：接收循环被阻塞，无法处理 RPC 响应。
+
+---
+
+### 2. 检查 system.ping 延迟
+
+```
+[kernel] Pong from module has mismatched ping_time (expected 1773076610.64, got 1773076605.63)
+```
+
+**原因**：模块的 pong 响应延迟了 5 秒，说明事件处理被阻塞。
+
+---
+
+### 3. 添加调试日志
+
+```python
+async def _ws_receiver(self, ws):
+    async for raw in ws:
+        print(f"[DEBUG] Received message: {raw[:100]}")  # 截断显示
+        # ... 处理逻辑
+        print(f"[DEBUG] Message processed")
+```
+
+如果看到 "Received message" 但长时间没有 "Message processed"，说明处理被阻塞。
+
+---
+
+## 检查清单
+
+在实现 WebSocket 接收循环时，确保：
+
+- [ ] 事件通知处理使用异步执行（Python: `create_task`, Node.js: 不 `await`, Go: `go`, Rust: `spawn`）
+- [ ] RPC 请求处理使用异步执行
+- [ ] RPC 响应处理只设置 Future/Promise/Channel，不执行业务逻辑
+- [ ] 接收循环中没有 `await` / `wait` 任何可能调用 RPC 的函数
+- [ ] 接收循环中没有耗时操作（I/O、计算、睡眠）
+- [ ] 异步任务有错误处理（catch / recover）
+- [ ] 测试了 `system.ping` 响应延迟（应 < 100ms）
+- [ ] 测试了并发 RPC 调用（应不超时）
+
+---
+
+## 参考实现
+
+**推荐参考**：
+- `launcher/entry.py` — Launcher 的接收循环（已修复）
+- `extensions/services/watchdog/entry.py` — Watchdog 的接收循环（已修复）
+
+**注意**：这些模块的注释中可能仍有"事件通知可以同步处理"的错误说法，请忽略注释，以实际代码为准。
+
+---
+
+## 总结
+
+**一句话规则**：接收循环只负责分发消息，所有业务逻辑都必须异步执行。
+
+**记住**：如果你在接收循环中使用了 `await` / `wait`（除了 `await ws.recv()` 本身），你可能正在制造一个死锁。