procproxy 0.1.0__py3-none-any.whl

proxycore/ipc.py

@@ -0,0 +1,637 @@
+"""CLI/GUI ↔ 服务 的 IPC。
+
+Windows：命名管道 `\\\\.\\pipe\\ProcProxy`（ACL 只允许 Administrators + 本机）。
+Unix：`~/.procproxy/procproxy.sock`（AF_UNIX，目录权限 0700）。
+
+设计约束：
+* 管道安全描述符只允许 Administrators + 本机 → 低权用户连接必须失败；
+* 服务侧对每条命令做来源校验（`GetNamedPipeClientProcessId`）并在审计日志里留痕；
+* 协议用一行 JSON（`{"cmd": ...}` → `{"ok": bool, ...}`），便于 CLI 与 GUI 复用。
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import socket
+import threading
+import time
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from typing import Any
+
+from .log import EventLogger, get_logger
+from .proc import IS_WINDOWS, current_pid
+
+LOG = EventLogger(get_logger("proxycore.ipc"))
+
+PIPE_NAME_WINDOWS = r"\\.\pipe\ProcProxy"
+UNIX_SOCKET_NAME = "procproxy.sock"
+MAX_REQUEST = 65536
+#: 服务端读取一条请求的最长等待（秒）。客户端连上后不发送请求不能拖死整个 IPC。
+PIPE_READ_TIMEOUT_S = 5.0
+#: Windows ERROR_PIPE_BUSY：命名管道实例都被占用时 CreateFile 返回它。
+_ERROR_PIPE_BUSY = 231
+
+# AF_UNIX 在部分 Windows Python 构建里不存在 → 显式解析一次，避免 getattr 的 Optional 类型污染
+AF_UNIX = int(getattr(socket, "AF_UNIX", 0))
+
+CMD_STATUS = "status"
+CMD_SESSIONS = "sessions"
+CMD_RULES = "rules"
+CMD_RELOAD = "reload"
+CMD_STOP = "stop"
+CMD_PANIC = "panic"
+VALID_COMMANDS = {CMD_STATUS, CMD_SESSIONS, CMD_RULES, CMD_RELOAD, CMD_STOP, CMD_PANIC}
+
+#: 默认 DACL：只允许管理员 + SYSTEM（Everyone 的 `...GRGWGX;;;WD` 不在其中）。
+PIPE_SDDL = "D:P(A;;GA;;;SY)(A;;GA;;;BA)"
+
+# ---- 按命令的权限分离 --------------------------------------------------------
+# 管道 ACL 是整体授权：要让人能发命令，就必须给他写权限。所以"能不能改规则"
+# 这件事表达不到 ACL 上，必须由服务侧按命令再判一次。
+#: 只读命令：被放行的组可以调。
+READ_COMMANDS = frozenset({CMD_STATUS, CMD_SESSIONS, CMD_RULES})
+#: 变更类命令：只有管理员能调。
+#: `reload` 能把别人的流量导到另一个上游；`stop` / `panic` 能让服务停摆。
+#: 这两类都不该交给"只是想看状态"的普通用户。
+ADMIN_ONLY_COMMANDS = frozenset({CMD_RELOAD, CMD_STOP, CMD_PANIC})
+
+
+def build_pipe_sddl(allow_sids: Iterable[str] = ()) -> str:
+    """构造命名管道的 DACL。
+
+    * `allow_sids` 为空 = 现状：只给 SYSTEM 与 Administrators `GA`；
+    * 传了 SID 则额外授予它们 `GRGW`（读+写）而不是 `GA`：管道是双工的，要发命令就必须能写；但不该把 `WRITE_DAC` / `WRITE_OWNER`
+      也交出去（那等于连管道自己的 ACL 都能改）。
+
+    `sid` 可以是 `S-1-5-21-...` 字面量，也可以用别名（`IU` / `BU` / `WD`）。
+    自定义组请传 SID 字符串（组名要先解析，见 `resolve_group_sid()`）。
+    """
+    aces = ["(A;;GA;;;SY)", "(A;;GA;;;BA)"]
+    aces += [f"(A;;GRGW;;;{sid})" for sid in allow_sids if sid]
+    return "D:P" + "".join(aces)
+
+
+def resolve_group_sid(name: str) -> str:
+    """把本地组名解析成 SID 字符串；解析不了返回 `""`（调用方按"不放行"处理）。
+
+    已经是 `S-1-...` 形式则原样返回。只在 Windows 上可行。
+    """
+    name = (name or "").strip()
+    if not name:
+        return ""
+    if name.upper().startswith("S-1-"):
+        return name
+    if os.name != "nt":
+        return ""
+    try:
+        import win32security
+
+        sid, _domain, _type = win32security.LookupAccountName(None, name)
+        return str(win32security.ConvertSidToStringSid(sid))
+    except Exception as exc:  # 组不存在 / 无权限查询，一律不放行
+        LOG.warn("ipc_allow_group_unresolved", group=name, error=str(exc))
+        return ""
+
+
+@dataclass(slots=True)
+class IpcRequest:
+    cmd: str
+    args: dict[str, Any] = field(default_factory=dict)
+    client_pid: int = 0
+
+    @classmethod
+    def loads(cls, raw: bytes | str) -> IpcRequest:
+        text = raw.decode("utf-8") if isinstance(raw, bytes) else raw
+        doc = json.loads(text)
+        if not isinstance(doc, dict):
+            raise ValueError("IPC 请求必须是 JSON 对象")
+        cmd = str(doc.get("cmd", "")).strip().lower()
+        if cmd not in VALID_COMMANDS:
+            raise ValueError(f"未知命令 {cmd!r}（可选：{', '.join(sorted(VALID_COMMANDS))}）")
+        args = doc.get("args") or {}
+        if not isinstance(args, dict):
+            raise ValueError("args 必须是对象")
+        return cls(cmd=cmd, args=args, client_pid=int(doc.get("pid", 0)))
+
+    def dumps(self) -> bytes:
+        return (json.dumps({"cmd": self.cmd, "args": self.args, "pid": self.client_pid}) + "\n").encode("utf-8")
+
+
+def encode_response(ok: bool, **fields: Any) -> bytes:
+    payload = {"ok": bool(ok), "ts": time.time(), **fields}
+    return (json.dumps(payload, ensure_ascii=False) + "\n").encode("utf-8")
+
+
+class IpcServer:
+    """服务侧：把命令分发给 handler。"""
+
+    def __init__(self, handlers: dict[str, Callable[[IpcRequest], dict[str, Any]]] | None = None) -> None:
+        self.handlers: dict[str, Callable[[IpcRequest], dict[str, Any]]] = dict(handlers or {})
+        self._stop = threading.Event()
+        self._threads: list[threading.Thread] = []
+        self._server: Any = None
+        self._audit: list[dict[str, Any]] = []
+        self.served = 0
+        self.rejected = 0
+
+    def start(self) -> None:
+        """启动 IPC 监听（子类实现；基类默认不监听，便于纯逻辑测试）。"""
+
+    def stop(self) -> None:
+        self._stop.set()
+
+    def register(self, cmd: str, handler: Callable[[IpcRequest], dict[str, Any]]) -> None:
+        if cmd not in VALID_COMMANDS:
+            raise ValueError(f"未知命令 {cmd!r}")
+        self.handlers[cmd] = handler
+
+    # ------------------------------------------------------------ 分发 -----
+    def dispatch(
+        self,
+        request: IpcRequest,
+        *,
+        client_pid: int = 0,
+        client_is_admin: bool = True,
+    ) -> dict[str, Any]:
+        """分发一条命令。
+
+        `client_is_admin` 由传输层给出（Windows 命名管道查客户端令牌；Unix
+        socket 靠目录 0700）。基类默认 `True`，因为默认的管道 ACL 本身就只放行
+        管理员，那时再判一次是多余的。一旦放行了普通组（`allow_sids`），
+        这个参数就必须由 `WindowsPipeServer` 真实计算，否则变更类命令会被
+        任何能被 ACL 放行的人调走。
+        """
+        self._audit.append(
+            {"ts": time.time(), "cmd": request.cmd, "client_pid": client_pid, "admin": client_is_admin}
+        )
+        if len(self._audit) > 1000:
+            del self._audit[:500]
+        if request.cmd in ADMIN_ONLY_COMMANDS and not client_is_admin:
+            self.rejected += 1
+            LOG.warn("ipc_command_denied_not_admin", cmd=request.cmd, client_pid=client_pid)
+            return {"ok": False, "error": f"命令 {request.cmd} 需要管理员权限", "code": "E_IPC_NOT_ADMIN"}
+        handler = self.handlers.get(request.cmd)
+        if handler is None:
+            self.rejected += 1
+            LOG.warn("ipc_command_unhandled", cmd=request.cmd, client_pid=client_pid)
+            return {"ok": False, "error": f"命令 {request.cmd} 未被实现"}
+        try:
+            result = handler(request)
+            self.served += 1
+            return {"ok": True, **result}
+        except Exception as exc:  # 服务侧不能因单条命令崩溃
+            LOG.error("ipc_handler_failed", cmd=request.cmd, error=str(exc))
+            return {"ok": False, "error": str(exc)}
+
+    def handle_raw(self, raw: bytes, *, client_pid: int = 0, client_is_admin: bool = True) -> bytes:
+        try:
+            request = IpcRequest.loads(raw)
+        except (ValueError, json.JSONDecodeError) as exc:
+            self.rejected += 1
+            return encode_response(False, error=f"请求非法：{exc}")
+        return encode_response(
+            **self.dispatch(request, client_pid=client_pid, client_is_admin=client_is_admin)
+        )
+
+    def audit_log(self) -> list[dict[str, Any]]:
+        return list(self._audit)
+
+    def stats(self) -> dict[str, int]:
+        return {"served": self.served, "rejected": self.rejected, "audit_entries": len(self._audit)}
+
+
+# ---------------------------------------------------------- Windows 实现 ----
+class WindowsPipeServer(IpcServer):
+    """命名管道服务（`pywin32` 可用时走真实管道；否则退化为"未安装依赖"）。"""
+
+    def __init__(
+        self,
+        *args: Any,
+        allow_sids: Iterable[str] = (),
+        pipe_name: str = PIPE_NAME_WINDOWS,
+        read_timeout_s: float = PIPE_READ_TIMEOUT_S,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        #: 额外放行的 SID（只给读写）。为空 = 只允许管理员 + SYSTEM（默认，保持原行为）。
+        self.allow_sids: tuple[str, ...] = tuple(s for s in allow_sids if s)
+        #: 管道名可注入：测试用独立名字，避免撞上正在运行的真实服务。
+        self.pipe_name = pipe_name or PIPE_NAME_WINDOWS
+        self.read_timeout_s = max(0.05, float(read_timeout_s))
+        self.available = False
+        self.error = ""
+
+    def start(self) -> None:  # pragma: no cover - 需要 Windows + pywin32
+        if not IS_WINDOWS:
+            raise RuntimeError("命名管道只在 Windows 可用")
+        try:
+            import win32security  # noqa: F401  # 仅探测可用性
+        except ImportError as exc:
+            self.error = f"需要 pywin32 才能提供命名管道 IPC：{exc}"
+            LOG.warn("ipc_pipe_unavailable", error=self.error)
+            return
+        self.available = True
+        self._threads.append(threading.Thread(target=self._serve_loop, daemon=True, name="ppx-ipc"))
+        self._threads[-1].start()
+
+    def stop(self) -> None:
+        self._stop.set()
+
+    def _serve_loop(self) -> None:  # pragma: no cover - Windows only
+        import win32file
+        import win32pipe
+        import win32security
+
+        sddl = build_pipe_sddl(self.allow_sids)
+        if self.allow_sids:
+            # 放行了非管理员 → 变更类命令改为"按命令判"（见 ADMIN_ONLY_COMMANDS）。
+            # 这条日志很重要：它说明这台机器的 IPC 不再是管理员专属。
+            LOG.warn("ipc_pipe_open_to_group", sids=list(self.allow_sids),
+                     hint="这些 SID 能连管道；变更类命令仍需管理员令牌")
+        try:
+            sd = win32security.ConvertStringSecurityDescriptorToSecurityDescriptor(
+                sddl, win32security.SDDL_REVISION_1
+            )
+            sa = win32security.SECURITY_ATTRIBUTES()
+            sa.SECURITY_DESCRIPTOR = sd
+        except Exception as exc:
+            self.error = f"构造管道安全描述符失败：{exc}"
+            LOG.error("ipc_sddl_failed", error=self.error)
+            return
+
+        while not self._stop.is_set():
+            try:
+                handle = win32pipe.CreateNamedPipe(
+                    self.pipe_name,
+                    win32pipe.PIPE_ACCESS_DUPLEX,
+                    win32pipe.PIPE_TYPE_MESSAGE | win32pipe.PIPE_READMODE_MESSAGE | win32pipe.PIPE_WAIT,
+                    8,
+                    MAX_REQUEST,
+                    MAX_REQUEST,
+                    0,
+                    sa,
+                )
+            except Exception as exc:
+                # 常见原因：已有实例占用同名管道 / 权限不足。明确记录并退出循环，
+                # 不让异常冒到线程外（否则 pytest/服务日志里会出现"未处理线程异常"）。
+                self.error = f"创建命名管道失败：{exc}（是否已有另一个服务实例在跑？）"
+                LOG.error("ipc_pipe_create_failed", error=self.error)
+                return
+            try:
+                win32pipe.ConnectNamedPipe(handle, None)
+                # `ReadFile`/`WriteFile` 在 win32file 里，不在 win32pipe。
+                # 写错会抛 AttributeError，被下面的 except 吞掉并关掉实例，
+                # 客户端只看到"233 管道的另一端上无任何进程"，很难联想到这里。
+                # 读取必须带超时：客户端连上后一个字节都不发，不能让唯一的
+                # 管道实例永远挂在这里（放行了普通组的机器上就是一次 DoS）。
+                data = self._read_request(handle)
+                if data is None:
+                    continue
+                client_pid = self._client_pid(handle)
+                client_is_admin = self._client_is_admin(client_pid)
+                win32file.WriteFile(
+                    handle,
+                    self.handle_raw(data, client_pid=client_pid, client_is_admin=client_is_admin),
+                )
+            except Exception as exc:  # 单连接失败不影响服务
+                LOG.error("ipc_pipe_error", error=str(exc))
+            finally:
+                with contextlib.suppress(Exception):
+                    win32pipe.DisconnectNamedPipe(handle)
+                with contextlib.suppress(Exception):
+                    win32pipe.CloseHandle(handle)
+
+    def _read_request(self, handle: Any) -> bytes | None:  # pragma: no cover - Windows only
+        """带超时地读一条请求；超时返回 None（调用方关闭该实例并重建）。"""
+        import win32file
+
+        result: dict[str, Any] = {}
+
+        def worker() -> None:
+            try:
+                _hr, data = win32file.ReadFile(handle, MAX_REQUEST)
+                result["data"] = data
+            except Exception as exc:  # 取消/断连都是正常收尾
+                result["error"] = exc
+
+        thread = threading.Thread(target=worker, daemon=True, name="ppx-ipc-read")
+        thread.start()
+        thread.join(self.read_timeout_s)
+        if thread.is_alive():
+            _cancel_sync_io(thread.ident or 0)
+            thread.join(1.0)
+            LOG.warn(
+                "ipc_pipe_read_timeout",
+                timeout_s=self.read_timeout_s,
+                hint="客户端连接后未发送请求，已关闭该管道实例",
+            )
+            return None
+        if "data" in result:
+            return result["data"]
+        if "error" in result:
+            raise result["error"]
+        return None
+
+    def _client_pid(self, handle: Any) -> int:  # pragma: no cover - Windows only
+        try:
+            import win32pipe
+
+            return int(win32pipe.GetNamedPipeClientProcessId(handle))
+        except Exception:
+            return 0
+
+    def _client_is_admin(self, pid: int) -> bool:  # pragma: no cover - Windows only
+        """管道的这个客户端本次能否执行管理操作。
+
+        判据是"令牌里的 Administrators 组已启用"，不是 `TokenElevation`。
+
+        本机实测（`runas /trustlevel:0x20000` 造的受限令牌）：
+
+            令牌          TokenElevation   Administrators 属性
+            提权管理员      1               0xf  （SE_GROUP_ENABLED）
+            受限令牌        1               0x10 （SE_GROUP_USE_FOR_DENY_ONLY）
+                            ^^^ 两者都是 1，所以 TokenElevation 区分不出来，
+                                受限令牌会被误判成管理员（实测确实被放行了）
+
+        `CheckTokenMembership(token, Administrators)` 也不行：pywin32 对主令牌
+        返回 `1309 ERROR_NO_IMPERSONATION_TOKEN`（它要的是线程的模仿令牌）。
+
+        改用组属性：`SE_GROUP_ENABLED(0x4)` 置位、且
+        `SE_GROUP_USE_FOR_DENY_ONLY(0x10)` 未置位，才算管理员。
+        这与管道 ACL 对 `BA` 的判定同源，受限令牌之所以连默认管道都连不上，
+        正是因为它的 BA 是 deny-only。
+
+        SYSTEM 单独放行：它的令牌里根本没有 Administrators 组，但管道 ACL 给了 `SY`。
+
+        任何异常一律按 False（fail-closed），绝不让"查不出来"变成"当作管理员"。
+        """
+        if pid <= 0 or os.name != "nt":
+            return False
+        # WinNT.h：组属性位
+        se_group_enabled = 0x00000004
+        se_group_use_for_deny_only = 0x00000010
+        local_system = "S-1-5-18"
+        handle = None
+        token = None
+        try:
+            import win32api
+            import win32con
+            import win32security
+
+            handle = win32api.OpenProcess(win32con.PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
+            token = win32security.OpenProcessToken(handle, win32security.TOKEN_QUERY)
+            to_str = win32security.ConvertSidToStringSid
+
+            user = to_str(win32security.GetTokenInformation(token, win32security.TokenUser)[0])
+            if user == local_system:
+                return True
+
+            admins = to_str(
+                win32security.CreateWellKnownSid(win32security.WinBuiltinAdministratorsSid)
+            )
+            for sid, attributes in win32security.GetTokenInformation(token, win32security.TokenGroups):
+                if to_str(sid) != admins:
+                    continue
+                return bool(attributes & se_group_enabled) and not bool(
+                    attributes & se_group_use_for_deny_only
+                )
+            return False
+        except Exception as exc:
+            LOG.warn("ipc_client_admin_probe_failed", pid=pid, error=str(exc))
+            return False
+        finally:
+            for obj in (token, handle):
+                if obj is not None:
+                    with contextlib.suppress(Exception):
+                        obj.Close()
+
+
+# ------------------------------------------------------------ Unix 实现 ----
+class UnixSocketServer(IpcServer):
+    """AF_UNIX 服务端（目录 0700，仅服务账户可访问）。"""
+
+    def __init__(self, *args: Any, path: str = "", **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.path = path or default_socket_path()
+
+    def start(self) -> None:
+        os.makedirs(os.path.dirname(self.path), exist_ok=True)
+        with _suppress_os_error():
+            os.unlink(self.path)
+        server = socket.socket(AF_UNIX, socket.SOCK_STREAM)
+        server.bind(self.path)
+        os.chmod(os.path.dirname(self.path), 0o700)
+        server.listen(8)
+        server.settimeout(0.5)
+        self._server = server
+        self._threads.append(threading.Thread(target=self._accept_loop, daemon=True, name="ppx-ipc"))
+        self._threads[-1].start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        server, self._server = self._server, None
+        if server is not None:
+            with _suppress_os_error():
+                server.close()
+        with _suppress_os_error():
+            os.unlink(self.path)
+
+    def _accept_loop(self) -> None:
+        while not self._stop.is_set():
+            server = self._server
+            if server is None:
+                return
+            try:
+                conn, _ = server.accept()
+            except TimeoutError:
+                continue
+            except OSError:
+                return
+            with conn:
+                try:
+                    raw = conn.recv(MAX_REQUEST)
+                except OSError:
+                    continue
+                if raw:
+                    conn.sendall(self.handle_raw(raw))
+
+
+def default_socket_path() -> str:
+    runtime = os.environ.get("PROCPROXY_RUNTIME_DIR")
+    base = runtime or (os.path.join(os.environ.get("PROGRAMDATA", r"C:\ProgramData"), "ProcProxy") if IS_WINDOWS else os.path.join(os.path.expanduser("~"), ".procproxy"))
+    return os.path.join(base, UNIX_SOCKET_NAME)
+
+
+def make_server(
+    *,
+    handlers: dict[str, Callable[[IpcRequest], dict[str, Any]]] | None = None,
+    path: str = "",
+    allow_sids: Iterable[str] = (),
+) -> IpcServer:
+    """按平台造一个 IPC 服务端。
+
+    `allow_sids` 只对 Windows 命名管道有意义（额外放行哪些 SID 连管道）；
+    Unix socket 靠目录 0700，天然只有服务账户能连。
+    """
+    if IS_WINDOWS:
+        return WindowsPipeServer(handlers, allow_sids=allow_sids)
+    return UnixSocketServer(handlers, path=path)
+
+
+# ------------------------------------------------------------ 客户端 --------
+class IpcClient:
+    """CLI 侧：连服务（Windows 走命名管道，Unix 走 socket）。"""
+
+    def __init__(self, *, path: str = "", timeout: float = 5.0) -> None:
+        self.path = path or (PIPE_NAME_WINDOWS if IS_WINDOWS else default_socket_path())
+        self.timeout = timeout
+
+    def call(self, cmd: str, **args: Any) -> dict[str, Any]:
+        request = IpcRequest(cmd=cmd, args=args, client_pid=current_pid())
+        if IS_WINDOWS:
+            return self._call_pipe(request)
+        return self._call_socket(request)
+
+    def _call_pipe(self, request: IpcRequest) -> dict[str, Any]:  # pragma: no cover - Windows only
+        try:
+            import win32file
+            import win32pipe
+        except ImportError:
+            return {"ok": False, "error": "需要 pywin32 才能连接服务的命名管道"}
+        try:
+            handle = self._open_pipe(win32file, win32pipe)
+        except Exception as exc:
+            return {"ok": False, "error": f"连接服务失败：{exc}"}
+        try:
+            return _pipe_exchange(handle, request.dumps(), timeout=self.timeout)
+        finally:
+            with _suppress_os_error():
+                handle.Close()
+
+    def _open_pipe(self, win32file: Any, win32pipe: Any) -> Any:  # pragma: no cover - Windows only
+        """打开管道；实例全忙时等到 `timeout`，而不是立刻报错。"""
+        deadline = time.monotonic() + max(0.05, self.timeout)
+        while True:
+            try:
+                return win32file.CreateFile(
+                    self.path,
+                    win32file.GENERIC_READ | win32file.GENERIC_WRITE,
+                    0,
+                    None,
+                    win32file.OPEN_EXISTING,
+                    0,
+                    None,
+                )
+            except Exception as exc:
+                if getattr(exc, "winerror", None) != _ERROR_PIPE_BUSY:
+                    raise
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise
+                win32pipe.WaitNamedPipe(self.path, max(1, int(remaining * 1000)))
+
+    def _call_socket(self, request: IpcRequest) -> dict[str, Any]:
+        try:
+            with socket.socket(AF_UNIX, socket.SOCK_STREAM) as sock:
+                sock.settimeout(self.timeout)
+                sock.connect(self.path)
+                sock.sendall(request.dumps())
+                raw = sock.recv(MAX_REQUEST)
+        except OSError as exc:
+            return {"ok": False, "error": f"连接服务失败：{exc}"}
+        try:
+            return json.loads(raw.decode("utf-8"))
+        except json.JSONDecodeError:
+            return {"ok": False, "error": "服务返回了非法 JSON"}
+
+
+def _pipe_exchange(handle: Any, payload: bytes, *, timeout: float) -> dict[str, Any]:
+    """在后台线程里完成"写请求 + 读响应"，超时用 CancelSynchronousIo 取消。
+
+    命名管道没有 socket 那样的读超时；同步 `ReadFile` 一旦对端不响应就会
+    永久阻塞。取消必须由另一个线程发起（`CancelSynchronousIo`），因此这里
+    把整段交换放进 worker，主线程按 `timeout` 收口。
+    """
+    import win32file  # pragma: no cover - Windows only
+
+    result: dict[str, Any] = {}
+
+    def worker() -> None:  # pragma: no cover - Windows only
+        try:
+            win32file.WriteFile(handle, payload)
+            _data, raw = win32file.ReadFile(handle, MAX_REQUEST)
+            result["payload"] = json.loads(raw.decode("utf-8"))
+        except Exception as exc:  # 取消/断连都归到调用方返回
+            result["error"] = f"与服务通信失败：{exc}"
+
+    thread = threading.Thread(target=worker, daemon=True, name="ppx-ipc-client")
+    thread.start()
+    thread.join(max(0.05, timeout))
+    if thread.is_alive():
+        _cancel_sync_io(thread.ident or 0)
+        thread.join(1.0)
+        return {"ok": False, "error": f"与服务通信超时（{timeout:g}s）"}
+    if "payload" in result:
+        return result["payload"]
+    return {"ok": False, "error": result.get("error", "与服务通信失败：未收到响应")}
+
+
+def _cancel_sync_io(thread_id: int) -> None:
+    """取消目标线程上挂起的同步 I/O（Windows）。失败只记日志，不抛。"""
+    if not IS_WINDOWS or thread_id <= 0:
+        return
+    try:
+        import ctypes
+        from ctypes import wintypes
+
+        k32 = ctypes.WinDLL("kernel32", use_last_error=True)
+        k32.OpenThread.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+        k32.OpenThread.restype = wintypes.HANDLE
+        k32.CancelSynchronousIo.argtypes = [wintypes.HANDLE]
+        k32.CancelSynchronousIo.restype = wintypes.BOOL
+        k32.CloseHandle.argtypes = [wintypes.HANDLE]
+        k32.CloseHandle.restype = wintypes.BOOL
+        handle = k32.OpenThread(0x0001, False, thread_id)  # THREAD_TERMINATE
+        if not handle:
+            return
+        try:
+            k32.CancelSynchronousIo(handle)
+        finally:
+            k32.CloseHandle(handle)
+    except Exception as exc:  # 取消失败时由句柄关闭兜底
+        LOG.warn("ipc_cancel_sync_io_failed", thread_id=thread_id, error=str(exc))
+
+
+def _suppress_os_error() -> Any:
+    import contextlib
+
+    return contextlib.suppress(OSError)
+
+
+__all__ = [
+    "ADMIN_ONLY_COMMANDS",
+    "AF_UNIX",
+    "CMD_PANIC",
+    "CMD_RELOAD",
+    "CMD_RULES",
+    "CMD_SESSIONS",
+    "CMD_STATUS",
+    "CMD_STOP",
+    "PIPE_NAME_WINDOWS",
+    "PIPE_SDDL",
+    "READ_COMMANDS",
+    "VALID_COMMANDS",
+    "IpcClient",
+    "IpcRequest",
+    "IpcServer",
+    "UnixSocketServer",
+    "WindowsPipeServer",
+    "build_pipe_sddl",
+    "default_socket_path",
+    "encode_response",
+    "make_server",
+    "resolve_group_sid",
+]