debug-control-plane 0.1.0__py3-none-any.whl

debug_control_plane/device_discovery/endpoint.py

@@ -0,0 +1,317 @@
+"""Endpoint parsing and /hello probing for network targets."""
+
+from __future__ import annotations
+
+import json
+import re
+import socket
+import subprocess
+import urllib.error
+import urllib.request
+from collections.abc import Callable, Iterable
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass
+from ipaddress import IPv4Address, IPv4Network
+
+from .protocol import NetworkTarget
+
+UrlOpen = Callable[[urllib.request.Request, float], object]
+LocalIpv4Provider = Callable[[], list[str]]
+CommandRunner = Callable[[list[str], float], str]
+
+
+@dataclass(frozen=True)
+class Endpoint:
+    host: str
+    port: int = 18080
+
+    @property
+    def base_url(self) -> str:
+        return f"http://{self.host}:{self.port}"
+
+    @classmethod
+    def parse(cls, value: str, default_port: int = 18080) -> Endpoint:
+        raw = value.strip()
+        if raw.startswith("http://"):
+            raw = raw[len("http://") :]
+        if raw.startswith("https://"):
+            raw = raw[len("https://") :]
+        raw = raw.split("/", 1)[0]
+        if not raw:
+            raise ValueError("endpoint is empty")
+        if ":" in raw:
+            host, port_text = raw.rsplit(":", 1)
+            if not host:
+                raise ValueError("endpoint host is empty")
+            return cls(host=host, port=int(port_text))
+        return cls(host=raw, port=default_port)
+
+
+def default_urlopen(request: urllib.request.Request, timeout: float) -> object:
+    return urllib.request.urlopen(request, timeout=timeout)
+
+
+def probe_hello(
+    endpoint: Endpoint,
+    *,
+    timeout: float = 1.0,
+    urlopen: UrlOpen = default_urlopen,
+) -> NetworkTarget | None:
+    request = urllib.request.Request(
+        f"{endpoint.base_url}/hello",
+        method="GET",
+        headers={"Accept": "application/json"},
+    )
+    try:
+        with urlopen(request, timeout) as response:
+            body = response.read().decode("utf-8")
+    except (OSError, urllib.error.URLError, TimeoutError, ValueError):
+        return None
+    try:
+        data = json.loads(body)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(data, dict):
+        return None
+    return NetworkTarget.from_hello(data, host=endpoint.host, port=endpoint.port)
+
+
+def local_ipv4_addresses() -> list[str]:
+    return sorted(_default_route_ipv4_addresses())
+
+
+def discover_default_endpoints(
+    *,
+    local_ipv4_addresses: LocalIpv4Provider = local_ipv4_addresses,
+    default_port: int = 18080,
+) -> list[Endpoint]:
+    endpoints: list[Endpoint] = []
+    seen: set[str] = set()
+    for address in local_ipv4_addresses():
+        if not _is_lan_ipv4(address):
+            continue
+        network = IPv4Network(f"{address}/24", strict=False)
+        for host in network.hosts():
+            host_text = str(host)
+            if host_text == address or host_text in seen:
+                continue
+            seen.add(host_text)
+            endpoints.append(Endpoint(host_text, default_port))
+    return endpoints
+
+
+def discover_targets(
+    endpoints: Iterable[Endpoint],
+    *,
+    timeout: float = 1.0,
+    urlopen: UrlOpen = default_urlopen,
+    max_workers: int = 64,
+) -> list[NetworkTarget]:
+    endpoint_list = list(endpoints)
+    if not endpoint_list:
+        return []
+    if len(endpoint_list) == 1:
+        target = probe_hello(endpoint_list[0], timeout=timeout, urlopen=urlopen)
+        return [target] if target is not None else []
+
+    targets_by_endpoint: dict[Endpoint, NetworkTarget] = {}
+    with ThreadPoolExecutor(
+        max_workers=min(max_workers, len(endpoint_list))
+    ) as executor:
+        futures = {
+            executor.submit(
+                probe_hello,
+                endpoint,
+                timeout=timeout,
+                urlopen=urlopen,
+            ): endpoint
+            for endpoint in endpoint_list
+        }
+        for future in as_completed(futures):
+            endpoint = futures[future]
+            try:
+                target = future.result()
+            except Exception:
+                target = None
+            if target is not None:
+                targets_by_endpoint[endpoint] = target
+    targets: list[NetworkTarget] = []
+    for endpoint in endpoint_list:
+        target = targets_by_endpoint.get(endpoint)
+        if target is not None:
+            targets.append(target)
+    return targets
+
+
+def _is_lan_ipv4(address: str) -> bool:
+    try:
+        ip = IPv4Address(address)
+    except ValueError:
+        return False
+    return ip.is_private and not ip.is_loopback and not ip.is_link_local
+
+
+def _default_route_ipv4_addresses() -> set[str]:
+    addresses: set[str] = set()
+    for probe_host in ("1.1.1.1", "8.8.8.8"):
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
+                sock.connect((probe_host, 80))
+                address = sock.getsockname()[0]
+        except OSError:
+            continue
+        if _is_lan_ipv4(address):
+            addresses.add(address)
+    return addresses
+
+
+# ---------------------------------------------------------------------------
+# R020-BF002: VPN-immune LAN CIDR discovery (route-table based).
+#
+# 新增独立函数,不改任何旧签名(旧 _default_route_ipv4_addresses/
+# local_ipv4_addresses/discover_default_endpoints 保持原状供 GUI 复用)。
+# 供 R020 mcp_debug_bridge/discovery 经 sys.path 复用。
+# 设计见 .dev-flow/R020/analysis/2026-08-08--mcp-bridge-device-discovery-backend.md §5.4
+# ---------------------------------------------------------------------------
+
+
+def _run_command_default(command: list[str], timeout: float) -> str:
+    """Run a system command and return stdout (raises OSError on failure)."""
+    try:
+        result = subprocess.run(
+            command,
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired as error:
+        output = error.stdout or ""
+        if isinstance(output, bytes):
+            return output.decode("utf-8", errors="replace")
+        return output
+    if result.returncode != 0:
+        raise OSError(result.stderr.strip() or f"command failed: {' '.join(command)}")
+    return result.stdout
+
+
+def _default_route_interface(
+    run_command: CommandRunner = _run_command_default,
+) -> str | None:
+    """`route -n get default` → interface name (e.g. en0).
+
+    macOS-only; returns None if route command unavailable or no default route.
+    网段来源改读路由表(替代旧 socket 出口法),避开全局 VPN TUN 污染:
+    TUN 接口(utun1024 等)绑定具体 198.18.x.x IP,默认出口接口仍是物理 en0。
+    """
+    try:
+        output = run_command(["route", "-n", "get", "default"], 3.0)
+    except OSError:
+        return None
+    match = re.search(r"^\s*interface:\s*(\S+)\s*$", output, re.MULTILINE)
+    return match.group(1) if match else None
+
+
+def _interface_ipv4(
+    interface: str,
+    run_command: CommandRunner = _run_command_default,
+) -> str | None:
+    """`ipconfig getifaddr <interface>` → IPv4 address."""
+    try:
+        output = run_command(["ipconfig", "getifaddr", interface], 3.0)
+    except OSError:
+        return None
+    address = output.strip()
+    return address if _is_lan_ipv4(address) else None
+
+
+def vpn_immune_lan_cidrs(
+    *,
+    run_command: CommandRunner = _run_command_default,
+    cidr_prefix_len: int = 24,
+) -> list[str]:
+    """VPN-immune LAN CIDRs via route table (R020-BF002).
+
+    流程:
+    1. `route -n get default` → 默认出口接口(物理 en0,非 utun)
+    2. `ipconfig getifaddr <if>` → 接口 IPv4(真实 LAN,非 198.18.x VPN TUN)
+    3. /<prefix> CIDR
+
+    任一步失败 → fallback 旧 `_default_route_ipv4_addresses()`(socket 出口法)。
+
+    Args:
+        run_command: 可注入命令执行器(默认 subprocess.run),便于 mock 测试
+        cidr_prefix_len: CIDR 前缀长度(默认 /24,与 discover_default_endpoints 一致)
+
+    Returns:
+        CIDR 字符串列表(如 ["192.168.1.0/24"]);空列表表示无 LAN 可达
+    """
+    cidrs, _source = _resolve_lan_cidrs(
+        run_command=run_command, cidr_prefix_len=cidr_prefix_len
+    )
+    return cidrs
+
+
+def vpn_immune_lan_cidrs_traced(
+    *,
+    run_command: CommandRunner = _run_command_default,
+    cidr_prefix_len: int = 24,
+) -> tuple[list[str], str]:
+    """VPN-immune LAN CIDRs + source 标记 (R020-BF003 可观测性变体)。
+
+    与 :func:`vpn_immune_lan_cidrs` 同源 (都委托 :func:`_resolve_lan_cidrs`),
+    额外返回 source 字符串供上层服务 (VpnImmune) 记录 fallback 事件。
+
+    Args:
+        run_command: 可注入命令执行器(默认 subprocess.run)
+        cidr_prefix_len: CIDR 前缀长度(默认 /24)
+
+    Returns:
+        (cidrs, source) 元组:
+          - cidrs: CIDR 字符串列表(与 vpn_immune_lan_cidrs 完全一致)
+          - source: ``"route_table"`` (路由表成功) 或
+                    ``"socket_fallback"`` (路由表失败, 回退 socket 出口法,
+                    可能受 VPN TUN 污染)
+    """
+    return _resolve_lan_cidrs(
+        run_command=run_command, cidr_prefix_len=cidr_prefix_len
+    )
+
+
+def _resolve_lan_cidrs(
+    *,
+    run_command: CommandRunner,
+    cidr_prefix_len: int,
+) -> tuple[list[str], str]:
+    """VPN-immune LAN CIDR 解析核心 (R020-BF002/BF003 共享实现).
+
+    返回 (cidrs, source), source 标记走了哪条路径:
+
+    * ``route_table`` — 路由表 + ipconfig 成功(真实 LAN, VPN TUN 不污染)
+    * ``socket_fallback`` — 任一步失败回退旧 socket 出口法(可能受 VPN TUN 污染)
+
+    旧 :func:`vpn_immune_lan_cidrs` 和新 :func:`vpn_immune_lan_cidrs_traced`
+    都委托本函数 — 保证两条调用路径输出完全一致(零破坏 BF002 测试).
+    """
+    interface = _default_route_interface(run_command)
+    if interface is None:
+        return _fallback_lan_cidrs(cidr_prefix_len), "socket_fallback"
+
+    address = _interface_ipv4(interface, run_command)
+    if address is None:
+        return _fallback_lan_cidrs(cidr_prefix_len), "socket_fallback"
+
+    network = IPv4Network(f"{address}/{cidr_prefix_len}", strict=False)
+    return [str(network)], "route_table"
+
+
+def _fallback_lan_cidrs(cidr_prefix_len: int) -> list[str]:
+    """VPN-immune 失败时回退旧 socket 出口法 (design §5.4 fallback)。"""
+    addresses = _default_route_ipv4_addresses()
+    cidrs: list[str] = []
+    for address in addresses:
+        network = IPv4Network(f"{address}/{cidr_prefix_len}", strict=False)
+        cidr = str(network)
+        if cidr not in cidrs:
+            cidrs.append(cidr)
+    return cidrs

debug_control_plane/device_discovery/protocol.py

@@ -0,0 +1,230 @@
+"""DTO parsing for the App debug controller HTTP/SSE protocol."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+JsonMap = dict[str, Any]
+
+
+def _string(data: JsonMap, key: str, default: str = "") -> str:
+    value = data.get(key, default)
+    return value if isinstance(value, str) else default
+
+
+def _bool(data: JsonMap, key: str, default: bool = False) -> bool:
+    value = data.get(key, default)
+    return value if isinstance(value, bool) else default
+
+
+def _int(data: JsonMap, key: str, default: int = 0) -> int:
+    value = data.get(key, default)
+    return value if isinstance(value, int) else default
+
+
+def _strings(data: JsonMap, key: str) -> tuple[str, ...]:
+    value = data.get(key, [])
+    if not isinstance(value, list):
+        return ()
+    return tuple(item for item in value if isinstance(item, str) and item)
+
+
+def _opt_string(data: JsonMap, key: str) -> str | None:
+    """Optional string: returns None when key missing or value not a str.
+
+    Used for R020 FF001 bridge fields (hardwareName/machineId) that older
+    /hello responses may omit — backward compatible.
+    """
+    value = data.get(key)
+    return value if isinstance(value, str) and value else None
+
+
+def _opt_json_list(data: JsonMap, key: str) -> tuple[JsonMap, ...] | None:
+    """Optional list-of-objects: returns None when key missing/invalid.
+
+    Used for R020 FF002 ``registeredCapabilities`` — older /hello without
+    FF001/FF002 returns None; valid array of objects returns a frozen tuple
+    of dict copies (immutable snapshot). Non-list or non-object items are
+    filtered; an explicitly empty array yields ``()`` (present-but-empty).
+    """
+    if key not in data:
+        return None
+    value = data.get(key)
+    if not isinstance(value, list):
+        return None
+    items: list[JsonMap] = []
+    for item in value:
+        if isinstance(item, dict):
+            items.append(dict(item))
+    return tuple(items)
+
+
+@dataclass(frozen=True)
+class NetworkTarget:
+    device_id: str
+    device_name: str
+    platform: str
+    host: str
+    port: int
+    protocol_version: int
+    capabilities: frozenset[str]
+    active_source: str
+    virtual_connected: bool
+    profile_id: str | None
+    real_controller_active: bool
+    last_error: str | None
+    profile_revision: int
+    app: str = ""
+    server_host: str = ""
+    server_port: int = 0
+    local_ips: tuple[str, ...] = ()
+    events_endpoint: str = "/events"
+    # --- R020 FF001/FF002 bridge fields (optional, backward compatible) ---
+    # Older /hello responses omit these; they default to None so existing GUI
+    # / R019 contract behavior is unchanged. Consumed by mcp_debug_bridge
+    # BF005 LanCandidate / BF006 cross_identify for device disambiguation.
+    hardware_name: str | None = None
+    machine_id: str | None = None
+    registered_capabilities: tuple[JsonMap, ...] | None = None
+
+    @classmethod
+    def from_hello(cls, data: JsonMap, *, host: str, port: int) -> NetworkTarget:
+        capabilities = data.get("capabilities", [])
+        if not isinstance(capabilities, list):
+            capabilities = []
+        profile_id = data.get("profileId")
+        last_error = data.get("lastError")
+        return cls(
+            device_id=_string(data, "deviceId", f"{host}:{port}"),
+            device_name=_string(data, "deviceName", f"{host}:{port}"),
+            platform=_string(data, "platform", "unknown"),
+            host=host,
+            port=port,
+            protocol_version=_int(data, "protocolVersion", 0),
+            capabilities=frozenset(str(item) for item in capabilities),
+            active_source=_string(data, "activeSource", "none"),
+            virtual_connected=_bool(data, "virtualConnected"),
+            profile_id=profile_id if isinstance(profile_id, str) else None,
+            real_controller_active=_bool(data, "realControllerActive"),
+            last_error=last_error if isinstance(last_error, str) else None,
+            profile_revision=_int(data, "profileRevision", 0),
+            app=_string(data, "app"),
+            server_host=_string(data, "serverHost", host),
+            server_port=_int(data, "serverPort", port),
+            local_ips=_strings(data, "localIps"),
+            events_endpoint=_string(data, "eventsEndpoint", "/events"),
+            hardware_name=_opt_string(data, "hardwareName"),
+            machine_id=_opt_string(data, "machineId"),
+            registered_capabilities=_opt_json_list(data, "registeredCapabilities"),
+        )
+
+
+@dataclass(frozen=True)
+class NetworkState:
+    active_source: str
+    virtual_connected: bool
+    profile_id: str | None
+    real_controller_active: bool
+    last_error: str | None
+    profile_revision: int
+
+    @classmethod
+    def from_json(cls, data: JsonMap) -> NetworkState:
+        profile_id = data.get("profileId")
+        last_error = data.get("lastError")
+        return cls(
+            active_source=_string(data, "activeSource", "none"),
+            virtual_connected=_bool(data, "virtualConnected"),
+            profile_id=profile_id if isinstance(profile_id, str) else None,
+            real_controller_active=_bool(data, "realControllerActive"),
+            last_error=last_error if isinstance(last_error, str) else None,
+            profile_revision=_int(data, "profileRevision", 0),
+        )
+
+
+@dataclass(frozen=True)
+class DebugEvent:
+    event_type: str
+    sequence: int
+    active_source: str | None = None
+    real_controller_active: bool | None = None
+    virtual_connected: bool | None = None
+    profile_id: str | None = None
+    profile_revision: int | None = None
+    error_code: str | None = None
+
+    @classmethod
+    def from_json(cls, data: JsonMap) -> DebugEvent:
+        return cls(
+            event_type=_string(data, "type", "unknown"),
+            sequence=_int(data, "sequence", 0),
+            active_source=data.get("activeSource") if isinstance(data.get("activeSource"), str) else None,
+            real_controller_active=data.get("realControllerActive") if isinstance(data.get("realControllerActive"), bool) else None,
+            virtual_connected=data.get("virtualConnected") if isinstance(data.get("virtualConnected"), bool) else None,
+            profile_id=data.get("profileId") if isinstance(data.get("profileId"), str) else None,
+            profile_revision=data.get("profileRevision") if isinstance(data.get("profileRevision"), int) else None,
+            error_code=data.get("errorCode") if isinstance(data.get("errorCode"), str) else None,
+        )
+
+
+@dataclass(frozen=True)
+class ControllerActionPayload:
+    action_id: str
+    display_label: str
+    capabilities: frozenset[str]
+    frame: JsonMap
+
+    @classmethod
+    def from_json(cls, action_id: str, data: JsonMap) -> ControllerActionPayload:
+        capabilities = data.get("capabilities", [])
+        if not isinstance(capabilities, list):
+            capabilities = []
+        frame = data.get("frame", {})
+        if not isinstance(frame, dict):
+            frame = {}
+        return cls(
+            action_id=_string(data, "actionId", action_id),
+            display_label=_string(data, "displayLabel", action_id),
+            capabilities=frozenset(str(item) for item in capabilities),
+            frame=dict(frame),
+        )
+
+
+@dataclass(frozen=True)
+class ControllerProfile:
+    profile_id: str
+    name: str
+    platform: str
+    connection_mode: str
+    created_at: str
+    actions: dict[str, ControllerActionPayload]
+
+    @classmethod
+    def from_json(cls, data: JsonMap) -> ControllerProfile:
+        actions_raw = data.get("actions", {})
+        actions: dict[str, ControllerActionPayload] = {}
+        if isinstance(actions_raw, dict):
+            for action_id, payload in actions_raw.items():
+                if isinstance(action_id, str) and isinstance(payload, dict):
+                    actions[action_id] = ControllerActionPayload.from_json(action_id, payload)
+        return cls(
+            profile_id=_string(data, "id"),
+            name=_string(data, "name"),
+            platform=_string(data, "platform"),
+            connection_mode=_string(data, "connectionMode"),
+            created_at=_string(data, "createdAt"),
+            actions=actions,
+        )
+
+
+# ---------------------------------------------------------------------------
+# AD-B9: DeviceUnreachable 下沉 (device_discovery 网络平面异常)
+# ---------------------------------------------------------------------------
+#: BF006 自 ``mcp_debug_bridge/bridge_client.py:99`` 下沉至此。原继承 ``BridgeError``
+#: (MCP 协议层基类),下沉后直继承 ``Exception`` 脱离 mcp_plane 反向依赖 —— 本属
+#: 网络平面异常 (设备不可达/设备池未识别 device_id)。BF007 删 ``bridge_client.py:99``
+#: 旧定义 + 改 ``from debug_control_plane.device_discovery.protocol import DeviceUnreachable``
+#: 正向 import;BF006 后双定义中间态 (不同类/不同基类/不同模块路径) 语义不冲突。
+class DeviceUnreachable(Exception):
+    """The device_id is unknown to the pool (连手机失败, 网络平面异常)."""

debug_control_plane/mcp_plane/__init__.py

@@ -0,0 +1,47 @@
+"""mcp_plane — MCP 适配平面(server/bridge_client/capability_mirror).
+
+BF007 迁入(自旧 mcp_debug_bridge):
+  - server.py(MCP stdio server, R019 8 端点 handler 字节级不变;★ 边界 1
+    gamepad import 降级,保 AC-B6, BF008-010 收尾)
+  - bridge_client.py(HTTP + SSE 客户端;AD-B9 DeviceUnreachable 改 forward
+    import from device_discovery.protocol, 直继承 Exception 脱 BridgeError)
+  - capability_mirror.py(Capability 镜像;AD-B1 剥 gamepad 常量 +
+    _parse_schemas E 方案 sentinel 通用化, 平面零 gamepad 业务知识)
+  - semantic_provider.py(BF002 SemanticProvider Protocol, 字符串前向引用)
+
+零业务依赖: 不 import gamepad / host4 / launcher / semantic_tools(留业务).
+mcp_plane → device_discovery 单向正向依赖(AD-B9 下沉 DeviceUnreachable 后).
+"""
+from .bridge_client import (
+    BridgeClient,
+    BridgeError,
+    DeviceHttpError,
+    DeviceStale,
+)
+from .capability_mirror import (
+    CapabilityMirror,
+    CapabilitySchema,
+    CommandDecl,
+    ResourceDecl,
+    ToolSpec,
+)
+from .semantic_provider import SemanticProvider
+from .server import McpServer
+
+__all__ = [
+    # bridge_client
+    "BridgeClient",
+    "BridgeError",
+    "DeviceHttpError",
+    "DeviceStale",
+    # capability_mirror
+    "CapabilityMirror",
+    "CapabilitySchema",
+    "CommandDecl",
+    "ResourceDecl",
+    "ToolSpec",
+    # semantic_provider (BF002)
+    "SemanticProvider",
+    # server
+    "McpServer",
+]