@agentunion/kite 1.3.1 → 1.4.0

package/extensions/services/watchdog/entry.py

@@ -20,7 +20,113 @@ import websockets
 
 
 # ── Module configuration ──
-MODULE_NAME = "watchdog"
+
+def _load_module_config() -> dict:
+    """Load module configuration from module.md frontmatter.
+
+    Returns:
+        Dict with keys: name, preferred_port, advertise_ip
+
+    Raises:
+        SystemExit: If module.md is invalid or name is non-compliant
+    """
+    _this_dir = os.path.dirname(os.path.abspath(__file__))
+    module_md = os.path.join(_this_dir, "module.md")
+
+    # Calculate relative path for error messages
+    project_root = os.environ.get("KITE_PROJECT", "")
+    if project_root and _this_dir.startswith(project_root):
+        rel_path = os.path.relpath(_this_dir, project_root)
+    else:
+        rel_path = _this_dir
+
+    # Default values (will be overridden if valid config exists)
+    result = {
+        "name": "",
+        "preferred_port": 0,
+        "advertise_ip": "0.0.0.0"
+    }
+
+    # Check if module.md exists
+    if not os.path.exists(module_md):
+        print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+        print(f"  Path: {rel_path}/module.md")
+        print(f"  Reason: File not found")
+        sys.exit(1)
+
+    try:
+        with open(module_md, encoding="utf-8") as f:
+            text = f.read()
+
+        # Extract YAML frontmatter (between --- markers)
+        import re
+        m = re.match(r'^---\s*\n(.*?)\n---', text, re.DOTALL)
+        if not m:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Missing YAML frontmatter")
+            sys.exit(1)
+
+        # Parse YAML frontmatter
+        try:
+            import yaml
+            fm = yaml.safe_load(m.group(1)) or {}
+        except ImportError:
+            print(f"[{rel_path}] ERROR: PyYAML not installed, cannot parse module.md")
+            sys.exit(1)
+        except Exception as e:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: YAML parse error: {e}")
+            sys.exit(1)
+
+        # Validate 'name' field (required)
+        if "name" not in fm:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Missing 'name' field")
+            sys.exit(1)
+
+        raw_name = str(fm["name"]).strip()
+
+        if not raw_name:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Empty module name")
+            sys.exit(1)
+
+        # Validate name characters
+        sanitized = re.sub(r'[^a-zA-Z0-9_\-]', '', raw_name)
+
+        if sanitized != raw_name:
+            invalid_chars = ''.join(sorted(set(c for c in raw_name if c not in sanitized)))
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Invalid characters in name '{raw_name}': {repr(invalid_chars)}")
+            sys.exit(1)
+
+        result["name"] = sanitized
+
+        # Extract optional fields
+        if "preferred_port" in fm:
+            try:
+                result["preferred_port"] = int(fm["preferred_port"])
+            except (ValueError, TypeError):
+                pass
+
+        if "advertise_ip" in fm:
+            result["advertise_ip"] = str(fm["advertise_ip"])
+
+    except SystemExit:
+        raise  # Re-raise exit to prevent catching by outer except
+    except Exception as e:
+        print(f"[{rel_path}] ERROR: Failed to read module.md: {e}")
+        sys.exit(1)
+
+    return result
+
+_module_config = _load_module_config()
+MODULE_NAME = _module_config["name"]
 
 
 def _fmt_elapsed(t0: float) -> str:
@@ -265,11 +371,26 @@ def _read_stdin_kite_message(expected_type: str, timeout: float = 10) -> dict |
 
 # Global WS reference for publish_event callback
 _ws_global = None
+_shutting_down = False
+_exit_code = 0  # Exit code for main() to use
+_monitor = None
+_monitor_task = None
+
+# RPC request-response infrastructure
+_rpc_waiters: dict[str, asyncio.Event] = {}   # rpc_id -> Event
+_rpc_results: dict[str, dict] = {}             # rpc_id -> response dict
 
 
+def _is_auth_failure(e: Exception) -> bool:
+    """Check if a WebSocket exception indicates authentication failure."""
+    if hasattr(e, 'rcvd') and e.rcvd is not None:
+        code = e.rcvd.code if hasattr(e.rcvd, 'code') else 0
+        return code in (4001, 4003)
+    return False
+
 
 async def main():
-    global _ws_global
+    global _ws_global, _shutting_down, _monitor
     # Initialize log file paths
     global _log_dir, _log_latest_path, _crash_log_path
     module_data = os.environ.get("KITE_MODULE_DATA")
@@ -321,57 +442,128 @@ async def main():
 
     print(f"[watchdog] Token received ({len(token)} chars), kernel port: {kernel_port} ({_fmt_elapsed(_t0)})")
 
-    # Connect to Kernel WebSocket
-    ws_url = f"ws://127.0.0.1:{kernel_port}/ws?token={token}&id=watchdog"
-    print(f"[watchdog] Connecting to Kernel: {ws_url}")
+    # Create monitor (once, persists across reconnects)
+    _monitor = HealthMonitor(
+        own_token=token,
+        kernel_port=kernel_port,
+    )
 
-    try:
-        async with websockets.connect(ws_url, open_timeout=5, ping_interval=None, ping_timeout=None, close_timeout=10) as ws:
-            _ws_global = ws
-            print(f"[watchdog] Connected to Kernel ({_fmt_elapsed(_t0)})")
-
-            # Subscribe to events
-            await _rpc_call(ws, "event.subscribe", {
-                "events": [
-                    "system.ready",
-                    "module.started",
-                    "module.stopped",
-                    "module.exiting",
-                    "module.ready",
-                    "module.shutdown",
-                ],
-            })
-            print(f"[watchdog] Subscribed to events ({_fmt_elapsed(_t0)})")
-
-            # Register to Kernel Registry via RPC
-            await _rpc_call(ws, "registry.register", {
-                "module_id": "watchdog",
-                "module_type": "service",
-                "events_publish": {
-                    "watchdog.module.unhealthy": {},
-                    "watchdog.module.recovered": {},
-                    "watchdog.alert": {},
-                },
-                "events_subscribe": [
-                    "system.ready",
-                    "module.started",
-                    "module.stopped",
-                    "module.exiting",
-                    "module.ready",
-                    "module.shutdown",
-                ],
-            })
-            print(f"[watchdog] Registered to Kernel ({_fmt_elapsed(_t0)})")
+    # Start reconnect loop
+    await _ws_loop(token, kernel_port, _t0)
 
-            # Create monitor with RPC callback
-            monitor = HealthMonitor(
-                own_token=token,
-                kernel_port=kernel_port,
-            )
-            monitor.publish_event = lambda event: asyncio.create_task(_publish_event(ws, event))
-            monitor.rpc_call = lambda method, params: _rpc_call(ws, method, params)
 
-            # Publish module.ready
+async def _ws_loop(token: str, kernel_port: int, _t0: float):
+    """Connect to Kernel with exponential backoff reconnection."""
+    global _shutting_down, _exit_code
+    retry_delay = 0.3
+    max_delay = 5.0
+    max_retries = 10
+    attempt = 0
+    while not _shutting_down:
+        try:
+            await _ws_connect(token, kernel_port, _t0)
+            retry_delay = 0.3
+            attempt = 0
+        except asyncio.CancelledError:
+            return
+        except Exception as e:
+            attempt += 1
+            if _is_auth_failure(e):
+                print(f"[watchdog] Kernel 认证失败，退出")
+                _exit_code = 1
+                _shutting_down = True
+                return
+            if attempt >= max_retries:
+                print(f"[watchdog] 重连失败 {max_retries} 次，退出")
+                _exit_code = 1
+                _shutting_down = True
+                return
+            _write_crash(type(e), e, e.__traceback__, severity="error", handled=True)
+            print(f"[watchdog] 连接错误: {e}, {retry_delay:.1f}s 后重试 ({attempt}/{max_retries})")
+            if attempt == 5:
+                print(f"\033[33m[watchdog] 提示: 已连续 {attempt} 次无法连接 Kernel (端口 {kernel_port})")
+                if kernel_port < 1024:
+                    print(f"[watchdog] ⚠ 端口 {kernel_port} 异常偏低，可能是 Kernel 端口绑定失败或配置错误")
+                print(f"[watchdog] 请检查: 1) Kernel 进程是否存活  2) kernel/module.md 中 preferred_port 配置是否正确\033[0m")
+        _ws_global_clear()
+        if _shutting_down:
+            return
+        await asyncio.sleep(retry_delay)
+        retry_delay = min(retry_delay * 2, max_delay)
+
+
+def _ws_global_clear():
+    global _ws_global
+    _ws_global = None
+
+
+async def _ws_connect(token: str, kernel_port: int, _t0: float):
+    """Single WebSocket session: connect → subscribe → register → ready → receive loop."""
+    global _ws_global, _monitor, _monitor_task
+
+    ws_url = f"ws://127.0.0.1:{kernel_port}/ws?token={token}&id=watchdog"
+    print(f"[watchdog] Connecting to Kernel: {ws_url}")
+
+    async with websockets.connect(ws_url, open_timeout=5, ping_interval=20, ping_timeout=20, close_timeout=10) as ws:
+        _ws_global = ws
+        print(f"[watchdog] Connected to Kernel ({_fmt_elapsed(_t0)})")
+
+        # Subscribe to events
+        await _rpc_call(ws, "event.subscribe", {
+            "events": [
+                "system.ready",
+                "module.started",
+                "module.stopped",
+                "module.exiting",
+                "module.ready",
+                "module.shutdown",
+                "module.offline",
+            ],
+        })
+        print(f"[watchdog] Subscribed to events ({_fmt_elapsed(_t0)})")
+
+        # Register to Kernel Registry via RPC
+        await _rpc_call(ws, "registry.register", {
+            "module_id": "watchdog",
+            "module_type": "service",
+            "tools": {
+                "rpc": {
+                    "module": {
+                        "health": {"method": "health", "description": "健康检查"},
+                        "status": {"method": "status", "description": "状态查询"}
+                    }
+                }
+            },
+            "events_publish": {
+                "watchdog": {
+                    "module": {
+                        "unhealthy": {"description": "模块不健康"},
+                        "recovered": {"description": "模块恢复"},
+                        "resource_critical": {"description": "资源严重不足"},
+                        "resource_warning": {"description": "资源警告"},
+                        "resource_recovered": {"description": "资源恢复正常"}
+                    },
+                    "alert": {"description": "监控告警"}
+                }
+            },
+            "events_subscribe": [
+                "system.ready",
+                "module.started",
+                "module.stopped",
+                "module.exiting",
+                "module.ready",
+                "module.shutdown",
+                "module.offline",
+            ],
+        })
+        print(f"[watchdog] Registered to Kernel ({_fmt_elapsed(_t0)})")
+
+        # Set up monitor callbacks (reconnect-safe)
+        _monitor.publish_event = lambda event: asyncio.create_task(_publish_event(ws, event))
+        _monitor.rpc_call = lambda method, params: _rpc_call_with_response(ws, method, params)
+
+        # Publish module.ready (every reconnect)
+        if not _shutting_down:
             await _rpc_call(ws, "event.publish", {
                 "event_id": str(uuid.uuid4()),
                 "event": "module.ready",
@@ -382,34 +574,43 @@ async def main():
             })
             print(f"[watchdog] module.ready published ({_fmt_elapsed(_t0)})")
 
-            # Start monitor loop in background
-            monitor_task = asyncio.create_task(monitor.run())
-
-            # Message loop: handle incoming RPC + events
-            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
-
-                    if has_method and not has_id:
-                        # Event Notification
-                        await _handle_event_notification(msg, monitor)
-                    elif has_method and has_id:
-                        # Incoming RPC request
-                        await _handle_rpc_request(ws, msg, monitor)
-                    # Ignore RPC responses (we don't await them in this simple impl)
-                except Exception as e:
-                    print(f"[watchdog] 消息处理异常（已忽略）: {e}")
+        # Start monitor loop if not already running
+        if _monitor_task is None or _monitor_task.done():
+            _monitor_task = asyncio.create_task(_monitor.run())
 
-    except Exception as e:
-        _write_crash(type(e), e, e.__traceback__, severity="critical", handled=True)
-        _print_crash_summary(type(e), e.__traceback__)
-        sys.exit(1)
+        # Start heartbeat loop
+        heartbeat_task = asyncio.create_task(_heartbeat_loop(ws))
+
+        # Message loop: handle incoming RPC + events
+        # CRITICAL: RPC 死锁防范
+        # - 入站 RPC 请求必须用 create_task() 异步执行，不可 await
+        # - 原因：如果 handler 内部调用 rpc_call_with_response() 发出站请求，出站响应需要本接收循环来分发
+        # - 如果接收循环被 await handler 阻塞，出站响应永远收不到 → 超时死锁
+        # - 事件通知和 RPC 响应可以同步处理（它们不会反向调用 rpc_call）
+        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
+
+                if has_method and not has_id:
+                    # Event Notification
+                    await _handle_event_notification(msg, _monitor)
+                elif has_method and has_id:
+                    # Incoming RPC request — run in background to prevent deadlock
+                    asyncio.create_task(_handle_rpc_request(ws, msg, _monitor))
+                elif has_id and not has_method:
+                    # RPC response — route to waiter
+                    msg_id = msg["id"]
+                    if msg_id in _rpc_waiters:
+                        _rpc_results[msg_id] = msg
+                        _rpc_waiters[msg_id].set()
+            except Exception as e:
+                print(f"[watchdog] 消息处理异常（已忽略）: {e}")
 
 
 
@@ -421,6 +622,40 @@ async def _rpc_call(ws, method: str, params: dict = None):
     await ws.send(json.dumps(msg))
 
 
+async def _heartbeat_loop(ws):
+    """Send registry.heartbeat every 30 seconds to prevent TTL expiration."""
+    while True:
+        try:
+            await asyncio.sleep(30)
+            if not _shutting_down:
+                await _rpc_call(ws, "registry.heartbeat", {"module_id": "watchdog"})
+        except Exception as e:
+            print(f"[watchdog] Heartbeat error: {e}")
+            break
+
+
+async def _rpc_call_with_response(ws, method: str, params: dict = None, timeout: float = 5) -> dict:
+    """Send a JSON-RPC 2.0 request and await the response."""
+    rpc_id = str(uuid.uuid4())
+    msg = {"jsonrpc": "2.0", "id": rpc_id, "method": method}
+    if params:
+        msg["params"] = params
+
+    evt = asyncio.Event()
+    _rpc_waiters[rpc_id] = evt
+
+    await ws.send(json.dumps(msg))
+
+    try:
+        await asyncio.wait_for(evt.wait(), timeout=timeout)
+        return _rpc_results.pop(rpc_id, {})
+    except asyncio.TimeoutError:
+        return {"error": {"code": -32000, "message": f"RPC timeout: {method}"}}
+    finally:
+        _rpc_waiters.pop(rpc_id, None)
+        _rpc_results.pop(rpc_id, None)
+
+
 async def _publish_event(ws, event: dict):
     """Publish an event via RPC event.publish."""
     await _rpc_call(ws, "event.publish", {
@@ -436,13 +671,17 @@ async def _handle_event_notification(msg: dict, monitor: HealthMonitor):
     event_type = params.get("event", "")
     data = params.get("data", {})
 
-    # Special handling for module.shutdown targeting watchdog
-    if event_type == "module.shutdown" and data.get("module_id") == "watchdog":
-        await _handle_shutdown(monitor)
-        return
+    # Debug: log all shutdown events
+    if event_type == "module.shutdown":
+        target = data.get("module_id", "")
+        reason = data.get("reason", "")
+        # Handle both targeted shutdown (module_id == "watchdog") and broadcast shutdown (no module_id or launcher_lost)
+        if target == "watchdog" or not target or reason == "launcher_lost":
+            await _handle_shutdown(monitor)
+            return
 
-    # Forward to monitor
-    await monitor.handle_event(msg)
+    # Forward to monitor (extract params from JSON-RPC notification)
+    await monitor.handle_event(params)
 
 
 async def _handle_rpc_request(ws, msg: dict, monitor: HealthMonitor):
@@ -489,23 +728,38 @@ async def _rpc_status(monitor: HealthMonitor) -> dict:
 
 
 async def _handle_shutdown(monitor: HealthMonitor):
-    """Handle module.shutdown event — ack, cleanup, ready, exit."""
+    """Handle module.shutdown event — ack → exiting → cleanup → ready → exit."""
+    global _shutting_down
     print("[watchdog] Received shutdown request")
-    # Step 1: Send ack
+    _shutting_down = True
+    # Step 1: Send ack (立即确认收到)
     await _publish_event(_ws_global, {
         "event": "module.shutdown.ack",
-        "data": {"module_id": "watchdog", "estimated_cleanup": 2},
+        "data": {"module_id": "watchdog"},
+    })
+    # Step 2: Send module.exiting (开始清理)
+    await _publish_event(_ws_global, {
+        "event": "module.exiting",
+        "data": {
+            "module_id": "watchdog",
+            "type": "passive",
+            "reason": "shutdown_requested",
+            "restart": "auto",
+            "action": "none",
+            "timeout": 2.0,
+            "restart_delay": 0.0,
+        },
     })
-    # Step 2: Cleanup
+    # Step 3: Cleanup
     monitor.stop()
-    # Step 3: Send ready
+    # Step 4: Send ready (清理完成)
     await _publish_event(_ws_global, {
         "event": "module.shutdown.ready",
         "data": {"module_id": "watchdog"},
     })
     print("[watchdog] Shutdown ready, exiting")
-    # Step 4: Exit
-    sys.exit(0)
+    # Step 5: Exit
+    sys.exit(_exit_code)
 
 
 if __name__ == "__main__":