procproxy 0.1.0__py3-none-any.whl

proxycore/runtime.py

@@ -0,0 +1,654 @@
+"""数据面运行时：把配置 + 后端 + 规则引擎 + 会话表 + sink 装配成一个可运行对象。
+
+职责：
+* 数据面只跑在服务进程里；CLI 只读状态；
+* 拦截/决策路径禁止阻塞（决策函数只做纯计算 + 记账 + 改道）；
+* 热重载原子替换 Profile，不中断已有会话；
+* `backend=null` 时不监听 sink，只提供 decide 与状态输出；
+  其余后端接入 `tunnel/sink.py` 与 `tunnel/relay.py`。
+"""
+
+from __future__ import annotations
+
+import contextlib
+import dataclasses
+import json
+import os
+import signal
+import threading
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from .backend import Backend
+from .backend.base import BackendUnavailable
+from .config import Config, ConfigError, ConfigManager
+from .dns.modes import MODE_BYPASS, MODE_LOCAL, build_dns_policy
+from .dns.udp import UdpForwarder, UdpPolicyResolver, UdpSessionTable
+from .log import EventLogger, get_logger
+from .proc import current_pid, get_proc_info, is_alive
+from .rules import GuardSet, LoopBreaker, fallback_decision, stats_snapshot
+from .tunnel.sessions import SessionTable
+from .types import Action, ConnRequest, Decision, Endpoint
+
+if TYPE_CHECKING:
+    from .tunnel.sink import Sink
+
+LOG = get_logger("proxycore.runtime")
+
+# RFC 1928：`UDP ASSOCIATE` 的 DST.ADDR/DST.PORT 用 0.0.0.0:0 表示"还不知道目标"
+UDP_ASSOCIATE_ANY = Endpoint(addr="0.0.0.0", port=0)
+
+# 已知限制：建立 UDP 关联要跟上游做一次 TCP 握手，是阻塞调用，而
+# `decide_udp()` 跑在后端的事件线程上（那条线程同时负责 TCP 决策，
+# classify 只有 200ms 预算）。所以这里用一个独立上限把它掐住，避免默认 15s 的
+# `upstream_timeout_s` 把整条决策线程拖死。
+# 正确做法是改成本地"先丢首个数据报、后台线程建关联"的两段式。
+UDP_ASSOCIATE_TIMEOUT_S = 3.0
+
+
+class Runtime:
+    """进程级数据面。生命周期：`start()` → `serve_forever()` → `stop()`。"""
+
+    def __init__(self, manager: ConfigManager, backend: Backend) -> None:
+        self.manager = manager
+        self.backend = backend
+        self.log = EventLogger(LOG)
+        self.sessions = SessionTable(
+            max_sessions=manager.config.service.max_sessions,
+            log=self.log,
+        )
+        self.breaker = LoopBreaker(
+            window_s=manager.config.service.loop_breaker.window_s,
+            threshold=manager.config.service.loop_breaker.threshold,
+        )
+        self.guards = GuardSet(
+            self_pids=set(),
+            breaker=self.breaker,
+            on_unknown_pid=manager.config.service.on_unknown_pid,
+        )
+        self.sink: Sink | None = None
+        self._stop_event = threading.Event()
+        self._maintenance: threading.Thread | None = None
+        self._reload_watch: threading.Thread | None = None
+        self._started_at = 0.0
+        self._backend_error: str = ""
+
+        # DNS 三模式由 Runtime 持有，三处消费：
+        # ① 守卫 G3 白名单（local 模式的 DNS 服务器）；
+        # ② `guards.name_resolver` → `dst_name` 规则；③ sink dial 时的解析计划。
+        self.dns_policy = build_dns_policy(manager.config.profile)
+        self._dns_revision = -1
+
+        # UDP 数据面。只有 `supports_udp` 的后端才会注册，
+        # 否则 `on_udp()` 会抛 `NotImplementedError`（windivert 就是这种）。
+        self.udp_sessions = UdpSessionTable(idle_timeout_s=manager.config.service.udp_idle_timeout_s)
+        self.udp_policy = UdpPolicyResolver(manager.config.udp_policy)
+        self.udp = UdpForwarder(
+            policy=self.udp_policy,
+            sessions=self.udp_sessions,
+            dialer_factory=self._make_udp_association,
+        )
+        self._udp_registered = False
+        self._refresh_guards()
+
+    # ------------------------------------------------------------ 生命周期 --
+    @property
+    def config(self) -> Config:
+        return self.manager.config
+
+    def start(self, *, sink_test_target: str = "", upstream_alias: str = "") -> None:
+        self._started_at = time.time()
+        self._refresh_guards()
+        self.backend.set_decider(self.decide)
+        # `Runtime.decide()` 自己会记 captured/direct/blocked（见 `_count`），
+        # 后端必须停手，否则同一个包两边各记一次 = 双倍（docs：验收里这两个数
+        # 是要给人看的，翻倍等于把"抓了多少"误导成两倍）。
+        self.backend.counts_decisions = False
+        self._register_udp()
+        try:
+            self.backend.start()
+        except BackendUnavailable as exc:
+            self._backend_error = str(exc)
+            raise
+
+        manual_mode = bool(sink_test_target or upstream_alias)
+        if sink_test_target:
+            self.sessions.set_test_target(sink_test_target)
+        if upstream_alias:
+            self.sessions.force_upstream = upstream_alias
+
+        if self.backend.name != "null" or manual_mode:
+            self._start_sink()
+        if self.backend.name == "null":
+            self.log.warn(
+                "backend_null",
+                "backend=null：不抓包、不改道，仅联调",
+                sink_test_target=sink_test_target or "-",
+                forced_upstream=upstream_alias or "-",
+            )
+
+        self._maintenance = threading.Thread(target=self._maintenance_loop, name="ppx-maintenance", daemon=True)
+        self._maintenance.start()
+        self.log.info(
+            "runtime_started",
+            backend=self.backend.name,
+            sink=f"{self.config.service.sink.host}:{self.config.service.sink.port}",
+            rules=len(self.config.profile.rules),
+            dns_mode=self.dns_policy.mode,
+        )
+        if self.dns_policy.mode in {MODE_LOCAL, MODE_BYPASS}:
+            # local 模式会在本地查 DNS，查询本身可能直连出去。
+            # 这是用户选的模式（不是缺陷），但必须显式告知，不能让人以为没泄漏。
+            self.log.warn(
+                "dns_local_mode_leaks",
+                mode=self.dns_policy.mode,
+                local_transport=self.dns_policy.local_transport,
+                dns_server=self.dns_policy.local_server or "(system)",
+                hint="local/bypass 会在本地解析域名：本地 DNS 查询可能直连出去",
+            )
+
+    def stop(self, *, reason: str = "shutdown") -> None:
+        self._stop_event.set()
+        try:
+            self.backend.stop()  # 契约：stop() 后 2s 内不再回调 decide
+            self._await_backend_quiet()
+            if self.sink is not None:
+                self.sink.stop()
+                self.sink = None
+        finally:
+            # 停掉 UDP 后台建关联的 worker。放在 backend.stop() 之后：这之后不会
+            # 再有新的 `decide_udp()` 进来，worker 手里的活做完就退出，不会边关边建。
+            with contextlib.suppress(Exception):
+                self.udp.close()
+            # 已建好的会话（控制连接 + 中继通道）也要释放，否则 socket 一直开着
+            self.udp_sessions.close_all()
+        self._write_state(reason=reason)
+        self.log.info("runtime_stopped", reason=reason, sessions=self.sessions.count())
+
+    def serve_forever(self, *, reload_watch: bool = True, poll_s: float = 1.0) -> None:
+        if reload_watch:
+            self._reload_watch = threading.Thread(target=self._watch_config, name="ppx-reload", daemon=True)
+            self._reload_watch.start()
+        self._install_signal_handlers()
+        try:
+            while not self._stop_event.wait(poll_s):
+                pass
+        finally:
+            if self.sink is not None:
+                self.sink.stop()
+
+    def _install_signal_handlers(self) -> None:
+        def handler(signum: int, _frame: Any) -> None:  # pragma: no cover - 信号路径
+            self.log.warn("signal_received", signum=signum)
+            self._stop_event.set()
+
+        for name in ("SIGINT", "SIGTERM"):
+            sig = getattr(signal, name, None)
+            if sig is None:
+                continue
+            with contextlib.suppress(ValueError, OSError):  # 非主线程/平台限制
+                signal.signal(sig, handler)
+
+    def _await_backend_quiet(self, timeout: float | None = None) -> None:
+        """契约：`stop()` 后 2 秒内不再回调 `decide`。"""
+        from .backend.base import STOP_QUIESCE_SECONDS
+
+        deadline = time.monotonic() + (timeout or STOP_QUIESCE_SECONDS)
+        while time.monotonic() < deadline:
+            if not getattr(self.backend, "running", False):
+                return
+            time.sleep(0.05)
+        self.log.warn("backend_quiet_timeout", backend=self.backend.name)
+
+    # -------------------------------------------------------------- 决策 ----
+    def _count(self, key: str, delta: int = 1) -> None:
+        """后端计数（`count()` 是 BaseBackend 的便利方法，Protocol 未强制）。"""
+        counter = getattr(self.backend, "count", None)
+        if callable(counter):
+            counter(key, delta)
+
+    def decide(self, conn: ConnRequest) -> Decision:
+        """后端回调入口。只做纯计算 + 记账，不得阻塞。"""
+        from .rules import decide as rules_decide
+
+        try:
+            # "抓到一条连接"是既成事实，与后面判成什么无关，放在最前面，
+            # 免得决策引擎抛异常时连 captured 都丢了。
+            self._count("captured")
+            if conn.proc.pid <= 0 and self.backend.supports_pid_native:
+                self.log.warn("unknown_pid_from_native_backend", backend=self.backend.name)
+            elif conn.proc.pid > 0 and not conn.proc.name:
+                info = get_proc_info(conn.proc.pid)
+                conn.proc.name = info.name
+                conn.proc.path = conn.proc.path or info.path
+                conn.proc.session_id = conn.proc.session_id or info.session_id
+
+            decision = rules_decide(conn, self.config.profile, self.sessions, self.guards)
+            self.breaker.note(conn.proc.pid, conn.dst)
+
+            if decision.action is Action.DIRECT:
+                self._count("direct")
+            elif decision.action is Action.BLOCK:
+                self._count("blocked")
+            if decision.reason == "loop-breaker":
+                self.log.warn(
+                    "loop_breaker_tripped",
+                    pid=conn.proc.pid,
+                    proc=conn.proc.name,
+                    dst=str(conn.dst),
+                    window_s=self.breaker.window_s,
+                    threshold=self.breaker.threshold,
+                )
+            self.sessions.record_decision(conn, decision)
+            return decision
+        except Exception as exc:  # 决策路径不允许把异常抛回抓包线程（BLE001 已按文件豁免）
+            self.log.error("decide_failed", pid=conn.proc.pid, dst=str(conn.dst), error=str(exc))
+            # 异常 = "不知道自己该干什么"。默认 block 而不是 direct：
+            # 改道失败禁止静默直连，决策失败同理，放行等于漏真实 IP。
+            try:
+                policy = self.config.service.on_decide_error
+                fallback = fallback_decision(policy, self.config.profile, reason="decide-error")
+            except Exception as nested:  # 兜底自己再失败也绝不外抛：这条分支的意义就是"不逃"
+                self.log.error("decide_fallback_failed", error=str(nested))
+                return Decision(Action.BLOCK, reason="decide-error:block")
+            self._count("blocked" if fallback.action is Action.BLOCK else "direct")
+            return fallback
+
+    # --------------------------------------------------------------- UDP ----
+    def _register_udp(self) -> None:
+        """把 UDP 处理器挂到后端。
+
+        `supports_udp=False` 的后端（路线 A 的 windivert）完全没有 UDP 路径：
+        它的两个句柄过滤器都以 `tcp` 开头，UDP 报文压根不进用户态。所以
+        `udp_policy`（含 `by_port: {443: block}`）在该后端上是纯配置、零效果：
+        既不做 proxy，也不做 block，QUIC 走的是系统默认路由。
+        这里不打补丁、不吞异常，只记一条信息就跳过；试图注册会抛
+        `NotImplementedError`，而被它挡住的是"整条启动流程"，不值得。
+        """
+        if not getattr(self.backend, "supports_udp", False):
+            self.log.info(
+                "udp_unsupported_backend",
+                backend=getattr(self.backend, "name", "?"),
+                hint="该后端不捕获 UDP，udp_policy 不会生效（QUIC 直连）",
+            )
+            return
+        self.backend.on_udp(self.decide_udp)
+        self._udp_registered = True
+        policy = self.udp_policy.describe()
+        self.log.info(
+            "udp_registered",
+            backend=getattr(self.backend, "name", "?"),
+            default=policy["default"],
+            by_port=policy["by_port"],
+        )
+        if self.udp_policy.leaks_ip():
+            # 显式告知：`direct` 会让支持 QUIC 的应用绕过代理
+            self.log.warn(
+                "udp_policy_leaks_ip",
+                default=policy["default"],
+                hint="udp_policy 含 direct → 支持 QUIC 的应用会绕过代理并泄漏真实 IP",
+            )
+
+    def _make_udp_association(self, alias: str) -> Any:
+        """`UdpForwarder.dialer_factory`：按别名建立一条 SOCKS5 UDP 关联。
+
+        返回的是 `UdpAssociation`（不是 dialer），这是 forwarder 的契约：
+        `assoc = factory(alias)`。按 RFC 1928，`UDP ASSOCIATE` 请求里的
+        DST.ADDR/DST.PORT 填 `0.0.0.0:0`，表示"客户端此刻还不知道要发去哪儿"。
+
+        返回 `None` 的语义是"没有可用的上游" → forwarder 丢弃数据报并记
+        `E_UPSTREAM_DOWN`。
+        """
+        if not alias:
+            return None
+        upstream = self.config.profile.upstreams.get(alias)
+        if upstream is None:
+            return None
+        from .upstream import make_dialer
+
+        dialer = make_dialer(
+            upstream,
+            timeout=min(self.config.service.upstream_timeout_s, UDP_ASSOCIATE_TIMEOUT_S),
+            resolver=self.config.profile.upstreams.get,
+        )
+        if not dialer.supports_udp():
+            # SOCKS4 / HTTP CONNECT 永远不支持 UDP；SOCKS5 需要 upstream.udp=true
+            return None
+        sync_udp = getattr(dialer, "dial_udp_sync", None)
+        if sync_udp is None:
+            # `UpstreamDialer` 只声明了异步 `dial_udp`；
+            # 同步入口是各 dialer 自己提供的（目前只有 Socks5Dialer 有）。
+            self.log.error(
+                "udp_dialer_has_no_sync_path",
+                upstream=alias,
+                kind=getattr(dialer, "kind", "?"),
+                code="E_UPSTREAM_DOWN",
+            )
+            return None
+        return sync_udp(UDP_ASSOCIATE_ANY)
+
+    def decide_udp(self, conn: ConnRequest, payload: bytes = b"") -> Action:
+        """`backend.on_udp` 回调：一条 UDP 数据报该怎么办。
+
+        与 TCP 路径的分工：后端已经带着同一个 `conn` 走过 `decide()`（规则 +
+        三重守卫）。但那条判定会被后端用本函数的返回值覆盖，所以守卫必须在这里
+        再挡一次，否则 `udp_policy.default=proxy` 就能把环路流量塞进代理。
+
+        顺序（任何一步命中即返回，不再往下走）：
+
+        1. 环路防护（不可配置）：自身 PID / 上游与 DNS 端点 /
+           私网回环 / 熔断 → `DIRECT`（放行原包，不接管）；
+        2. PID 未知 → 按 `on_unknown_pid`，默认 `DIRECT`（路线 A 竞态兜底）；
+        3. 规则：进程本身没被判为 PROXY 的（DIRECT/BLOCK）原样返回；
+           `udp_policy` 只管"已经要走代理的进程"的 UDP，不改变直连进程的行为；
+        4. `udp_policy`：`direct` | `block` | `proxy`。
+        """
+        try:
+            return self._decide_udp_inner(conn, payload)
+        except Exception as exc:  # 回调不允许异常逃回抓包线程（与 decide 同策略）
+            self.log.error("decide_udp_failed", pid=conn.proc.pid, dst=str(conn.dst), error=str(exc))
+            return Action.BLOCK  # 失败即失败：既不直连，也不假装成功
+
+    def _decide_udp_inner(self, conn: ConnRequest, payload: bytes) -> Action:
+        from .rules import decide as rules_decide
+
+        g = self.guards
+        if g.is_self_pid(conn.proc.pid):
+            return Action.DIRECT
+        if g.is_upstream_endpoint(conn.dst):
+            return Action.DIRECT
+        if g.is_private(conn.dst.addr):
+            # 私网/回环默认直连（默认放行回环/私网）；UDP 没有"改道"，
+            # 接管后只能注入，且没有规则可依据，所以一律不接管。
+            return Action.DIRECT
+        if self.breaker.check(conn.proc.pid, conn.dst):
+            # `check()` 是只读版本（不记账）， UDP 是包级的，按数据报计一次数
+            # 会让 5s/50 次的阈值被任何视频流瞬间打爆，所以只读检查。
+            self.log.warn(
+                "loop_breaker_tripped",
+                pid=conn.proc.pid,
+                proc=conn.proc.name,
+                dst=str(conn.dst),
+                proto="udp",
+            )
+            return Action.DIRECT
+
+        # 规则探测（含 PID 未知时按 `on_unknown_pid` 的兜底，与 TCP 路径同一套逻辑）：
+        # 用不带熔断器的守卫副本，避免 `breaker_tripped()` 重复记账
+        # （熔断已在上面用只读 `check()` 处理过）。`rules.decide` 除了这条计数之外
+        # 是纯函数，这里只取它的 action/upstream，不重复记账、不重复建会话。
+        probe_guards = dataclasses.replace(g, breaker=None, track_unknown_pid=False)
+        rule_decision = rules_decide(conn, self.config.profile, self.sessions, probe_guards)
+        if rule_decision.action is not Action.PROXY:
+            return rule_decision.action
+
+        action = self.udp_policy.action_for(conn.dst.port)
+        if action is Action.DIRECT:
+            self.log.debug("udp_direct", pid=conn.proc.pid, dst=str(conn.dst), leak=True)
+            return Action.DIRECT
+        if action is Action.BLOCK:
+            self.log.debug("udp_blocked", pid=conn.proc.pid, dst=str(conn.dst))
+            return Action.BLOCK
+
+        if not payload:
+            # 临时闸门：后端目前只报事件、不上报载荷（事件里传的是 `b""`）。
+            # 0 字节 UDP 报文在协议上合法，所以这个判断编码的是"载荷没送到用户态"
+            # 这一事实，不是"报文为空"。后端补上载荷后必须换成显式标志。
+            self.udp_sessions.note_dropped("no-payload")
+            self.log.error(
+                "udp_payload_unavailable",
+                pid=conn.proc.pid,
+                dst=str(conn.dst),
+                code="E_UPSTREAM_DOWN",
+                hint="UDP 载荷尚未从驱动上报到用户态，无法转发 → 丢弃（不直连）",
+            )
+            return Action.BLOCK
+        return self.udp.handle(
+            conn.proc.pid,
+            conn.src.port,
+            conn.dst,
+            payload,
+            upstream_alias=rule_decision.upstream,
+        )
+
+    # ------------------------------------------------------------ sink ------
+    def _start_sink(self) -> None:
+        from .tunnel.sink import Sink
+
+        self.sink = Sink(
+            backend=self.backend,
+            sessions=self.sessions,
+            config=self.config,
+            log=self.log,
+            dns=self.dns_policy,
+        )
+        self.sink.start()
+
+    # ---------------------------------------------------------- 维护线程 ---
+    def _maintenance_loop(self) -> None:
+        while not self._stop_event.wait(1.0):
+            try:
+                self._tick()
+            except Exception as exc:  # 维护线程必须活下来（BLE001 已按文件豁免）
+                self.log.error("maintenance_failed", error=str(exc))
+
+    def _tick(self) -> None:
+        now = time.time()
+        self._refresh_dns_names()
+        removed = self.sessions.reap(now=now)
+        if removed:
+            self.log.debug("sessions_reaped", count=removed, active=self.sessions.count())
+        # UDP：60s 空闲回收。进程退出立即回收在下面和 PID 一起做。
+        udp_removed = self.udp_sessions.reap(now=now)
+        if udp_removed:
+            self.log.debug(
+                "udp_sessions_reaped", count=udp_removed, active=self.udp_sessions.count()
+            )
+        # 进程退出后清理粘性
+        dead = [pid for pid in self.sessions.sticky_pids() if not is_alive(pid)]
+        for pid in dead:
+            self.sessions.forget_pid(pid)
+        # UDP 关联没有"等它自己超时"的理由：进程一死，它的 (pid, src_port) 永远不会再来。
+        # 只能传"确实还活着的 PID"，`prune_pids` 会把不在集合里的全部删掉，
+        # 传一个残缺的白名单等于误杀活会话。
+        udp_alive = {pid for pid in self.udp_sessions.pids() if is_alive(pid)}
+        udp_pruned = self.udp_sessions.prune_pids(udp_alive)
+        if udp_pruned:
+            self.log.debug("udp_sessions_pruned", count=udp_pruned)
+        if int(time.time()) % 5 == 0:
+            self._write_state(reason="periodic")
+
+    def _write_state(self, *, reason: str) -> None:
+        path = self._state_path()
+        backend_stats = self.backend.stats() if self.backend else {}
+        payload = {
+            "pid": current_pid(),
+            "backend": getattr(self.backend, "name", "?"),
+            "started_at": self._started_at,
+            "updated_at": time.time(),
+            "reason": reason,
+            "sink": f"{self.config.service.sink.host}:{self.config.service.sink.port}",
+            "config": self.config.path,
+            "config_generation": self.manager.generation,
+            "active_sessions": self.sessions.count(),
+            "loop_breaker_trips": self.breaker.trips_total,
+            "unknown_pid": self.guards.unknown_pid,
+            "dns_mode": self.dns_policy.mode,
+            "dns_cache_entries": self.dns_policy.cache.stats()["entries"],
+            **{k: v for k, v in backend_stats.items() if isinstance(v, (int, str))},
+        }
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            tmp = path.with_suffix(".json.tmp")
+            tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+            os.replace(tmp, path)
+        except OSError as exc:  # pragma: no cover - 权限/磁盘问题
+            self.log.warn("state_write_failed", path=str(path), error=str(exc))
+
+    def _state_path(self) -> Path:
+        override = os.environ.get("PROCPROXY_RUNTIME_DIR")
+        if override:
+            return Path(override) / "state.json"
+        if os.name == "nt":
+            base = os.environ.get("PROGRAMDATA", r"C:\ProgramData")
+            return Path(base) / "ProcProxy" / "state.json"
+        return Path.home() / ".procproxy" / "state.json"
+
+    # ------------------------------------------------------------ 热重载 ---
+    def apply_profile(self) -> None:
+        """热重载后的唯一收口：把所有由 Profile 派生的运行时状态一次性换掉。
+
+        两个入口共用它：文件监视器（`_watch_config`）与 `api.ProxyHandle.reload()`。
+        同一个动作只保留一套实现，否则两条路会分叉（API 那条曾经漏掉 UDP/DNS 刷新）。
+        新增"由 Profile 派生"的状态时只改这里。
+
+        DNS 策略是原地 `configure()`：`Sink` 持有同一个对象、worker 线程随时在读，
+        换对象就得同步改 `sink.dns`，漏掉一处就是"热重载后 DNS 静默不生效"。
+        缓存刻意保留，改配置不该把 DNS 记录扔光。
+        """
+        self.dns_policy.configure(self.config.profile)
+        self._refresh_guards()
+        self.udp_policy = UdpPolicyResolver(self.config.udp_policy)
+        self.udp.policy = self.udp_policy  # forwarder 持有的是同一个对象，必须同换
+        self.udp_sessions.idle_timeout_s = float(self.config.service.udp_idle_timeout_s)
+        self.sessions.on_profile_reload(self.config.profile)
+
+    def _watch_config(self) -> None:
+        path = self.config.path
+        if not path:
+            return
+        last_mtime = _mtime(path)
+        control_path = self._state_path().with_name("control.json")
+        while not self._stop_event.wait(1.0):
+            action = _consume_control(control_path)
+            if action is not None:
+                # 控制文件是"一次性指令"：先删再停，否则残留的 panic 会让
+                # 下一次启动在第一秒又把自己停掉。
+                event = "panic_stop_requested" if action == "panic" else "stop_requested"
+                self.log.warn(event, path=str(control_path))
+                self._stop_event.set()
+                return
+            current = _mtime(path)
+            if current and current != last_mtime:
+                last_mtime = current
+                try:
+                    new = self.manager.reload(path)  # 校验失败 → 抛异常并保留旧配置
+                    self.apply_profile()
+                    self.log.info(
+                        "config_reloaded",
+                        rules=len(new.profile.rules),
+                        udp_default=self.udp_policy.default,
+                        dns_mode=self.dns_policy.mode,
+                    )
+                except ConfigError as exc:
+                    self.log.error("config_reload_rejected", code=exc.code, message=exc.message)
+
+    def _refresh_guards(self) -> None:
+        """重建守卫集合。"""
+        cfg = self.config
+        self.guards.self_pids = set(self.sessions.self_pids()) | {current_pid()}
+        self.guards.upstream_endpoints = cfg.profile.upstream_endpoints()
+        self.guards.on_unknown_pid = cfg.service.on_unknown_pid
+        self.guards.breaker = self.breaker
+        self._refresh_dns_guards()
+
+    def _refresh_dns_guards(self) -> None:
+        """DNS 相关的守卫与规则输入（三处，全部来自 `dns_policy`）。
+
+        ① `name_resolver`，`dst_name` 规则的唯一数据来源。**不接上，
+        `dst_name` 规则就永远是死规则**（`GuardSet.name_for_ip` 直接返回 None）；
+        ② `inferred_names`，命中推断映射时日志要打 `name-inferred`
+        ，同时 BLOCK 规则禁用推断映射（`rules.decide`）；
+        ③ G3 白名单，`local` 模式下本地 DNS 服务器必须直连，否则 DNS 查询
+        自己会被代理并形成环路。
+        """
+        policy = self.dns_policy
+        self.guards.name_resolver = policy.name_for
+        self.guards.inferred_names = policy.inferred_names()
+        self._dns_revision = policy.revision()
+        self.guards.local_dns_servers = set()
+        if policy.mode in {MODE_LOCAL, MODE_BYPASS} and policy.local_server:
+            self.guards.local_dns_servers.add(policy.local_server)
+            self.guards.upstream_endpoints.update(policy.guard_endpoints())
+
+    def _refresh_dns_names(self) -> None:
+        """缓存变了才重算 `inferred_names`（它最长 20000 条，不能每次 tick 都算）。"""
+        policy = self.dns_policy
+        revision = policy.revision()
+        if revision == self._dns_revision:
+            return
+        self._dns_revision = revision
+        self.guards.inferred_names = policy.inferred_names()
+
+    # ------------------------------------------------------------- 快照 ----
+    # --------------------------------------------------------------- DNS ----
+    def note_dns_answer(
+        self, addr: str, name: str, *, ttl_s: float | None = None, inferred: bool = True
+    ) -> None:
+        """记录一条 IP→域名映射，这是 `dst_name` 规则唯一的名字来源。
+
+        `inferred=True`（默认）表示来自 DNS 嗅探，只用于近似匹配：日志打
+        `name-inferred`，不参与 dial、不参与 BLOCK。
+        `inferred=False` 表示权威来源（应用真的连的就是这个域名），可以交给上游远端解析。
+
+        目前没有后端会调用它：路线 A 的过滤器以 `tcp` 开头，DNS 报文不进用户态；
+        而且抓包式后端本来就拿不到主机名（内核只给地址），所以"权威域名"
+        在这条路线上不存在。接口保留但不做假实现：没有嗅探就是没有名字，
+        不假装能匹配 `dst_name`。
+
+        这带来一条结构性限制：在透明捕获类后端上，`dns_mode=remote` 防不住 DNS 泄漏。
+        等我们看到那条连接时，应用早已 `getaddrinfo` 完成，泄漏已经发生。
+        """
+        self.dns_policy.note_answer(addr, name, ttl_s=ttl_s, inferred=inferred)
+        self._refresh_dns_names()
+
+    def on_network_change(self, *, flush_system: bool = False) -> dict[str, Any]:
+        """网络接口变化 → 清推断映射。
+
+        方法体在 `dns.cache.on_network_change`，这里只负责接线 + 记账：
+        清了多少条、刷没刷系统缓存，都要留下一条可查的日志。
+        """
+        from .dns.cache import on_network_change as _flush
+
+        result = _flush(self.dns_policy.cache, flush_system=flush_system)
+        self._refresh_dns_names()
+        self.log.info("dns_cache_flushed", **result)
+        return result
+
+    def snapshot(self) -> dict[str, Any]:
+        return {
+            "backend": self.backend.stats(),
+            "rules": stats_snapshot(self.config.profile, self.guards),
+            "sessions": self.sessions.stats(),
+            "breaker": self.breaker.stats(),
+            "udp": self.udp_sessions.stats(),
+            "dns": self.dns_policy.describe(),
+        }
+
+
+def _mtime(path: str) -> float:
+    try:
+        return os.path.getmtime(path)
+    except OSError:
+        return 0.0
+
+
+def _consume_control(path: Path) -> str | None:
+    """读取并删除一次性的控制指令（`stop` / `panic`）。
+
+    删除必须发生在返回之前：控制文件表示"执行一次"，留下了就会影响下一次启动。
+    非法内容/未知指令返回 None 且不删除（可能是别人正在写的文件）。
+    """
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(payload, dict):
+        return None
+    action = str(payload.get("action", "")).strip().lower()
+    if action not in {"stop", "panic"}:
+        return None
+    with contextlib.suppress(OSError):
+        path.unlink()
+    return action