@agentunion/kite 1.3.2 → 1.4.0

package/extensions/services/backup/entry.py

@@ -19,11 +19,126 @@ import uuid
 import websockets
 
 
+# System broadcast events (received by all modules, may not need handling)
+SYSTEM_BROADCAST_EVENTS = {
+    "module.ready", "module.registered", "module.started", "module.stopped",
+    "module.crashed", "module.exiting", "module.offline",
+    "module.shutdown.ack", "module.shutdown.ready",
+    "system.ready", "registry.updated",
+}
+
+
 # ── Safe stdout/stderr: ignore BrokenPipeError after Launcher closes stdio ──
 
 
 # ── Module configuration ──
-MODULE_NAME = "backup"
+
+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"]
 
 
 class _SafeWriter:
@@ -264,6 +379,7 @@ 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
 
 
 def _is_auth_failure(e: Exception) -> bool:
@@ -333,7 +449,7 @@ async def main():
 
 async def _ws_loop(token: str, kernel_port: int, _t0: float):
     """Connect to Kernel with exponential backoff reconnection."""
-    global _shutting_down
+    global _shutting_down, _exit_code
     retry_delay = 0.3
     max_delay = 5.0
     max_retries = 10
@@ -349,10 +465,14 @@ async def _ws_loop(token: str, kernel_port: int, _t0: float):
             attempt += 1
             if _is_auth_failure(e):
                 print(f"[backup] Kernel 认证失败，退出")
-                sys.exit(1)
+                _exit_code = 1
+                _shutting_down = True
+                return
             if attempt >= max_retries:
                 print(f"[backup] 重连失败 {max_retries} 次，退出")
-                sys.exit(1)
+                _exit_code = 1
+                _shutting_down = True
+                return
             _write_crash(type(e), e, e.__traceback__, severity="error", handled=True)
             print(f"[backup] 连接错误: {e}, {retry_delay:.1f}s 后重试 ({attempt}/{max_retries})")
         _ws_global_clear()
@@ -374,7 +494,7 @@ async def _ws_connect(token: str, kernel_port: int, _t0: float):
     ws_url = f"ws://127.0.0.1:{kernel_port}/ws?token={token}&id=backup"
     print(f"[backup] Connecting to Kernel: {ws_url}")
 
-    async with websockets.connect(ws_url, open_timeout=5, ping_interval=None, ping_timeout=None, close_timeout=10) as ws:
+    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"[backup] Connected to Kernel ({_fmt_elapsed(_t0)})")
 
@@ -392,8 +512,24 @@ async def _ws_connect(token: str, kernel_port: int, _t0: float):
         await _rpc_call(ws, "registry.register", {
             "module_id": "backup",
             "module_type": "service",
+            "launcher_id": "launcher",  # 声明归属的 Launcher
+            "tools": {
+                "rpc": {
+                    "module": {
+                        "health": {"method": "health", "description": "健康检查"},
+                        "status": {"method": "status", "description": "状态查询"},
+                        "config": {
+                            "get": {"method": "get_settings", "description": "获取配置"},
+                            "update": {"method": "update_settings", "description": "更新配置"},
+                            "reset": {"method": "reset_settings", "description": "恢复默认配置"},
+                        }
+                    }
+                }
+            },
             "events_publish": {
-                "backup.test": {"description": "Test event from backup module"},
+                "backup": {
+                    "test": {"description": "Test event from backup module"},
+                }
             },
             "events_subscribe": [
                 "module.started",
@@ -418,7 +554,15 @@ async def _ws_connect(token: str, kernel_port: int, _t0: float):
         # Start test event loop in background
         test_task = asyncio.create_task(_test_event_loop(ws))
 
+        # 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() 发出站请求，出站响应需要本接收循环来分发
+        # - 如果接收循环被 await handler 阻塞，出站响应永远收不到 → 超时死锁
+        # - 事件通知和 RPC 响应可以同步处理（它们不会反向调用 rpc_call）
         async for raw in ws:
             try:
                 msg = json.loads(raw)
@@ -433,8 +577,8 @@ async def _ws_connect(token: str, kernel_port: int, _t0: float):
                     # Event Notification
                     await _handle_event_notification(msg)
                 elif has_method and has_id:
-                    # Incoming RPC request
-                    await _handle_rpc_request(ws, msg)
+                    # Incoming RPC request — run in background to prevent deadlock
+                    asyncio.create_task(_handle_rpc_request(ws, msg))
                 # Ignore RPC responses (we don't await them in this simple impl)
             except Exception as e:
                 print(f"[backup] 消息处理异常（已忽略）: {e}")
@@ -448,6 +592,18 @@ 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": "backup"})
+        except Exception as e:
+            print(f"[backup] Heartbeat error: {e}")
+            break
+
+
 async def _publish_event(ws, event: dict):
     """Publish an event via RPC event.publish."""
     await _rpc_call(ws, "event.publish", {
@@ -472,8 +628,13 @@ async def _handle_event_notification(msg: dict):
             await _handle_shutdown()
             return
 
-    # Log other events
-    print(f"[backup] Event received: {event_type}")
+    # Layer 2: 忽略系统广播事件
+    if event_type in SYSTEM_BROADCAST_EVENTS:
+        return
+
+    # Layer 3: 警告未知事件（仅开发环境）
+    if os.environ.get("KITE_ENV") == "development":
+        print(f"[backup] Debug: Unhandled event: {event_type}")
 
 
 async def _handle_rpc_request(ws, msg: dict):
@@ -485,6 +646,9 @@ async def _handle_rpc_request(ws, msg: dict):
     handlers = {
         "health": lambda p: _rpc_health(),
         "status": lambda p: _rpc_status(),
+        "get_settings": lambda p: _rpc_get_settings(p),
+        "update_settings": lambda p: _rpc_update_settings(p),
+        "reset_settings": lambda p: _rpc_reset_settings(p),
     }
     handler = handlers.get(method)
     if handler:
@@ -522,30 +686,144 @@ async def _rpc_status() -> dict:
     }
 
 
+# ── Configuration management helpers ──
+
+def _read_module_md() -> tuple[dict, str]:
+    """读取 module.md，返回 (frontmatter, body)"""
+    from pathlib import Path
+    md_path = Path(__file__).parent / "module.md"
+    text = md_path.read_text(encoding="utf-8")
+
+    # 提取 YAML frontmatter (--- ... ---)
+    m = re.match(r'^---\s*\n(.*?)\n---\s*\n?(.*)', text, re.DOTALL)
+    if not m:
+        return {}, text
+
+    import yaml
+    frontmatter = yaml.safe_load(m.group(1)) or {}
+    body = m.group(2)
+    return frontmatter, body
+
+
+def _write_module_md(frontmatter: dict, body: str):
+    """写入 module.md"""
+    from pathlib import Path
+    import yaml
+    md_path = Path(__file__).parent / "module.md"
+    fm_str = yaml.dump(frontmatter, allow_unicode=True, sort_keys=False, default_flow_style=False).rstrip()
+    content = f"---\n{fm_str}\n---\n{body}"
+    md_path.write_text(content, encoding="utf-8")
+
+
+# ── RPC handlers for configuration management ──
+
+async def _rpc_get_settings(params: dict) -> dict:
+    """RPC handler for backup.get_settings — 获取模块的所有设置"""
+    frontmatter, _ = _read_module_md()
+    return {
+        "name": frontmatter.get("name", "backup"),
+        "display_name": frontmatter.get("display_name", ""),
+        "type": frontmatter.get("type", ""),
+        "state": frontmatter.get("state", "enabled"),
+        "version": frontmatter.get("version", ""),
+        "runtime": frontmatter.get("runtime", ""),
+        "entry": frontmatter.get("entry", ""),
+        "preferred_port": frontmatter.get("preferred_port"),
+        "advertise_ip": frontmatter.get("advertise_ip"),
+        "monitor": frontmatter.get("monitor"),
+        "events": frontmatter.get("events"),
+        "subscriptions": frontmatter.get("subscriptions"),
+        "depends_on": frontmatter.get("depends_on"),
+        "has_config": False,  # backup 模块暂无 config.yaml
+        "config": None,
+    }
+
+
+async def _rpc_update_settings(params: dict) -> dict:
+    """RPC handler for backup.update_settings — 更新模块设置"""
+    metadata = params.get("metadata", {})
+    config = params.get("config", {})
+
+    # 更新 module.md frontmatter
+    if metadata:
+        frontmatter, body = _read_module_md()
+        for key, value in metadata.items():
+            frontmatter[key] = value
+        _write_module_md(frontmatter, body)
+
+    # 更新 config.yaml（如果需要）
+    if config:
+        # backup 模块暂无 config.yaml，此处预留接口
+        pass
+
+    # 返回更新后的完整设置
+    return await _rpc_get_settings({})
+
+
+async def _rpc_reset_settings(params: dict) -> dict:
+    """RPC handler for backup.reset_settings — 恢复默认值"""
+    fields = params.get("fields", [])
+    reset_all = params.get("all", False)
+
+    # 默认值定义
+    defaults = {
+        "state": "enabled",
+        "preferred_port": 20000,
+        "advertise_ip": "127.0.0.1",
+        "monitor": True,
+    }
+
+    frontmatter, body = _read_module_md()
+
+    if reset_all:
+        # 恢复所有字段
+        for key, value in defaults.items():
+            frontmatter[key] = value
+    else:
+        # 恢复指定字段
+        for field in fields:
+            if field in defaults:
+                frontmatter[field] = defaults[field]
+
+    _write_module_md(frontmatter, body)
+
+    # 返回恢复后的设置
+    return await _rpc_get_settings({})
+
+
+
 async def _handle_shutdown():
-    """Handle module.shutdown event — exiting → ack → cleanup → ready → exit."""
+    """Handle module.shutdown event — ack → exiting → cleanup → ready → exit."""
     global _shutting_down
     print("[backup] Received shutdown request")
     _shutting_down = True
-    # Step 0: Send module.exiting
+    # Step 1: Send ack (立即确认收到)
     await _publish_event(_ws_global, {
-        "event": "module.exiting",
-        "data": {"module_id": "backup", "action": "none"},
+        "event": "module.shutdown.ack",
+        "data": {"module_id": "backup"},
     })
-    # Step 1: Send ack
+    # Step 2: Send module.exiting (开始清理)
     await _publish_event(_ws_global, {
-        "event": "module.shutdown.ack",
-        "data": {"module_id": "backup", "estimated_cleanup": 2},
+        "event": "module.exiting",
+        "data": {
+            "module_id": "backup",
+            "type": "passive",
+            "reason": "shutdown_requested",
+            "restart": "auto",
+            "action": "none",
+            "timeout": 2.0,
+            "restart_delay": 0.0,
+        },
     })
-    # Step 2: Cleanup (nothing to clean up for backup)
-    # Step 3: Send ready
+    # Step 3: Cleanup (nothing to clean up for backup)
+    # Step 4: Send ready (清理完成)
     await _publish_event(_ws_global, {
         "event": "module.shutdown.ready",
         "data": {"module_id": "backup"},
     })
     print("[backup] Shutdown ready, exiting")
-    # Step 4: Exit
-    sys.exit(0)
+    # Step 5: Exit
+    sys.exit(_exit_code)
 
 
 async def _test_event_loop(ws):

package/extensions/services/backup/module.md

@@ -1,22 +1,24 @@
----
-name: backup
-display_name: Backup
-version: "1.0"
-type: service
-state: enabled
-runtime: python
-entry: entry.py
-events:
-  - backup.test
-subscriptions:
-  - module.started
-  - module.stopped
-  - module.shutdown
----
-
-# Backup（备份模块）
-
-自动备份工程代码和数据的扩展模块。
-
-- 定时备份 — 按配置周期自动备份指定目录
-- 事件通知 — 通过 Event Hub 发布备份状态事件
+---
+name: backup
+display_name: Backup
+version: '1.0'
+type: service
+state: enabled
+runtime: python
+entry: entry.py
+events:
+- backup.test
+subscriptions:
+- module.started
+- module.stopped
+- module.shutdown
+preferred_port: 20000
+advertise_ip: 127.0.0.1
+monitor: true
+---
+# Backup（备份模块）
+
+自动备份工程代码和数据的扩展模块。
+
+- 定时备份 — 按配置周期自动备份指定目录
+- 事件通知 — 通过 Event Hub 发布备份状态事件