procproxy 0.1.0__py3-none-any.whl

proxycore/rules.py

@@ -0,0 +1,730 @@
+"""规则引擎。
+
+`decide()` 的匹配顺序严格不得调整：
+
+    1. 全局白名单：回环/私网/链路本地 → DIRECT（除非规则显式覆盖 keep_private_proxied）
+    2. 自身进程（服务/拦截器/上游代理进程） → DIRECT  （reason="self-pid"）
+    3. 上游代理端点（含 DNS 服务器，若走本地解析） → DIRECT （reason="upstream-endpoint"）
+    4. 熔断器：同 (pid, dst) 5s 内计数超阈值 → DIRECT + 告警（reason="loop-breaker"）
+    5. Profile.rules 自上而下，首个命中生效 → 返回其 action/upstream
+    6. 未命中 → profile.default_action（默认 DIRECT）
+
+性能红线：O(规则数)、单次 < 20µs（1000 条 < 100µs）；
+禁止在 `decide()` 里做 DNS 解析、日志格式化、文件读取，因此规则表达式会在
+`CompiledProfile` 里预编译（导入期/热重载期各一次）。
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import ipaddress
+import re
+import time
+import weakref
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from .config import Profile, Rule
+from .types import Action, ConnRequest, Decision, Endpoint, Proto
+
+
+class StickySessions(Protocol):
+    """`decide()` 只需要一个粘性上游查询接口（`SessionTable` / 测试替身都满足）。"""
+
+    def sticky_upstream(self, pid: int, rule_id: str, *, default: str = "") -> str: ...
+
+# --------------------------------------------------- 默认放行的地址集合 ------
+# 默认放行 127/8、10/8、172.16/12、192.168/16、169.254/16、fe80::/10
+DEFAULT_PRIVATE_NETS: tuple[str, ...] = (
+    "127.0.0.0/8",
+    "10.0.0.0/8",
+    "172.16.0.0/12",
+    "192.168.0.0/16",
+    "169.254.0.0/16",
+    "fe80::/10",
+    "::1/128",
+    "fc00::/7",  # ULA
+)
+
+REASON_GUARD_PRIVATE = "guard-private"
+REASON_SELF_PID = "self-pid"
+REASON_UPSTREAM_ENDPOINT = "upstream-endpoint"
+REASON_LOOP_BREAKER = "loop-breaker"
+REASON_DEFAULT = "default"
+REASON_UNKNOWN_PID = "unknown-pid"
+REASON_NAME_INFERRED = "name-inferred"
+
+_WILDCARD_CHARS = re.compile(r"[*?\[]")
+
+
+# ============================================================ 匹配原语 ======
+def wildcard_match(pattern: str, value: str, *, case_sensitive: bool = False) -> bool:
+    """`*`/`?`/`[]` 通配匹配（大小写不敏感为默认）。
+
+    无通配符的模式走精确比较（`decide()` 热路径上比 fnmatch 快一个量级）。
+    """
+    if pattern == "*":
+        return True
+    if not case_sensitive:
+        pattern, value = pattern.lower(), value.lower()
+    if not has_wildcard(pattern):
+        return pattern == value
+    return fnmatch.fnmatchcase(value, pattern)
+
+
+def match_process(targets: str, proc_name: str, proc_path: str) -> bool:
+    """`targets` 的进程匹配语义：
+
+    * 多值用 `;` 分隔；
+    * 大小写不敏感；`*`/`?` 通配；
+    * 含 `\\` 或 `/` 的模式按完整路径匹配，否则按文件名匹配；
+    * 路径为空（受保护进程）时降级为按名称匹配（受保护进程拿不到路径）。
+    """
+    name = proc_name or ""
+    path = proc_path or ""
+    for pattern in _split(targets, ";"):
+        if not pattern:
+            continue
+        if "\\" in pattern or "/" in pattern:
+            if not path:
+                # 只有模式本身不带目录时，才允许缺路径降级
+                base = _basename(pattern)
+                if base and wildcard_match(base, name):
+                    return True
+                continue
+            if wildcard_match(pattern, path):
+                return True
+        elif wildcard_match(pattern, name):
+            return True
+    return False
+
+
+def match_proto(expr: str, proto: Proto) -> bool:
+    expr = (expr or "*").strip().lower()
+    return expr in {"*", proto.value}
+
+
+def match_port(expr: str, port: int) -> bool:
+    """`443` | `80,443` | `1000-2000` | `*`（端口段含边界）。"""
+    expr = (expr or "*").strip()
+    if expr in {"", "*"}:
+        return True
+    for item in _split(expr, ","):
+        item = item.strip()
+        if not item or item == "*":
+            return True
+        if "-" in item:
+            lo_s, _, hi_s = item.partition("-")
+            try:
+                lo, hi = int(lo_s), int(hi_s)
+            except ValueError:
+                continue
+            if lo <= port <= hi:
+                return True
+        else:
+            try:
+                if int(item) == port:
+                    return True
+            except ValueError:
+                continue
+    return False
+
+
+def match_ip(expr: str, addr: str) -> bool:
+    """CIDR 或具体 IP，多值逗号分隔；v4/v6 都支持。"""
+    expr = (expr or "*").strip()
+    if expr in {"", "*"}:
+        return True
+    try:
+        target = ipaddress.ip_address(addr)
+    except ValueError:
+        return False
+    for item in _split(expr, ","):
+        item = item.strip()
+        if not item or item == "*":
+            return True
+        try:
+            net = ipaddress.ip_network(item, strict=False)
+        except ValueError:
+            continue
+        if target.version == net.version and target in net:
+            return True
+    return False
+
+
+def match_name(expr: str, name: str | None) -> bool:
+    """域名规则：仅在域名已知时匹配。
+
+    通过 DNS 嗅探推断出来的映射属于近似匹配，日志必须打 `name-inferred`。
+    """
+    if name is None:
+        return False
+    expr = (expr or "*").strip()
+    if expr in {"", "*"}:
+        return True
+    for pattern in _split(expr, ","):
+        pattern = pattern.strip()
+        if not pattern:
+            continue
+        if wildcard_match(pattern, name):
+            return True
+    return False
+
+
+def _split(value: str, seps: str) -> list[str]:
+    """按分隔符切分（不用 re.split，热路径更快）。"""
+    out: list[str] = []
+    buf = ""
+    for ch in value:
+        if ch in seps:
+            out.append(buf)
+            buf = ""
+        else:
+            buf += ch
+    out.append(buf)
+    return out
+
+
+def _basename(pattern: str) -> str:
+    return pattern.replace("\\", "/").rstrip("/").rsplit("/", 1)[-1]
+
+
+def _parse_ip(addr: str) -> Any:
+    """解析 IP（失败返回 None，绝不抛异常）；热路径只解析一次。"""
+    try:
+        return ipaddress.ip_address(addr)
+    except ValueError:
+        return None
+
+
+def has_wildcard(pattern: str) -> bool:
+    return bool(_WILDCARD_CHARS.search(pattern))
+
+
+# ============================================================ 守卫集合 ======
+@dataclass(slots=True)
+class GuardSet:
+    """三重环路防护 + 全局白名单的输入集合。
+
+    * `self_pids`：第一重：自身进程白名单；
+    * `upstream_endpoints` / `local_dns_servers`，第二重：上游与 DNS 端点；
+    * `breaker`：第三重：同 (pid, dst) 的抖动熔断（见 `LoopBreaker`）。
+    """
+
+    self_pids: set[int] = field(default_factory=set)
+    upstream_endpoints: set[tuple[str, int]] = field(default_factory=set)
+    local_dns_servers: set[str] = field(default_factory=set)
+    private_nets: tuple[ipaddress.IPv4Network | ipaddress.IPv6Network, ...] = field(
+        default_factory=lambda: tuple(ipaddress.ip_network(n) for n in DEFAULT_PRIVATE_NETS)
+    )
+    breaker: LoopBreaker | None = None
+    on_unknown_pid: str = "direct"
+    name_resolver: Callable[[str], str | None] | None = None
+    # 推断出来的域名（DNS 嗅探）→ 命中时日志要带 name-inferred
+    inferred_names: set[str] = field(default_factory=set)
+    track_unknown_pid: bool = True
+    unknown_pid: int = 0
+
+    # ------------------------------------------------------------ 子判定 --
+    def is_private(self, addr: str) -> bool:
+        try:
+            ip = ipaddress.ip_address(addr)
+        except ValueError:
+            return False
+        return any(ip.version == net.version and ip in net for net in self.private_nets)
+
+    def is_self_pid(self, pid: int) -> bool:
+        return pid in self.self_pids
+
+    def is_upstream_endpoint(self, dst: Endpoint) -> bool:
+        if (dst.addr, dst.port) in self.upstream_endpoints:
+            return True
+        return dst.addr in self.local_dns_servers and dst.port == 53
+
+    def name_for_ip(self, addr: str) -> str | None:
+        if self.name_resolver is None:
+            return None
+        return self.name_resolver(addr)
+
+    def breaker_tripped(self, pid: int, dst: Endpoint) -> bool:
+        if self.breaker is None:
+            return False
+        return self.breaker.tripped(pid, dst)
+
+    def note(self, pid: int, dst: Endpoint) -> None:
+        if self.breaker is not None:
+            self.breaker.note(pid, dst)
+
+    def note_unknown_pid(self) -> None:
+        """路线 A 的 `unknown_pid` 计数。"""
+        if self.track_unknown_pid:
+            self.unknown_pid += 1
+
+
+# ============================================================ 熔断器 ========
+class LoopBreaker:
+    """环路防护第三重：同 `(pid, dst)` 在 `window_s` 内超过 `threshold` 次即熔断。
+
+    语义：计数在判定之前检查、判定之后记账，
+    因此当阈值 N=50 时，第 51 次连接起返回 DIRECT + 告警。
+
+    实现：单调时钟环形缓冲，每次查询先淘汰窗口外的样本（O(窗口内次数)）。
+    """
+
+    def __init__(
+        self,
+        window_s: float = 5.0,
+        threshold: int = 50,
+        *,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.window_s = float(window_s)
+        self.threshold = int(threshold)
+        self._clock = clock
+        self._hits: dict[tuple[int, str, int], list[float]] = {}
+        self._trips: dict[tuple[int, str, int], int] = {}
+        self.trips_total = 0
+
+    def _prune(self, key: tuple[int, str, int], now: float) -> list[float]:
+        stamps = self._hits.get(key)
+        if stamps is None:
+            return []
+        cutoff = now - self.window_s
+        # 列表是时间递增的，从头切片即可
+        idx = 0
+        for stamp in stamps:
+            if stamp >= cutoff:
+                break
+            idx += 1
+        if idx:
+            del stamps[:idx]
+            if not stamps:
+                del self._hits[key]
+                return []
+        return stamps
+
+    def count(self, pid: int, dst: Endpoint) -> int:
+        key = (pid, dst.addr, dst.port)
+        now = self._clock()
+        return len(self._prune(key, now))
+
+    def check(self, pid: int, dst: Endpoint) -> bool:
+        """只读检查（不记账）：是否已达熔断阈值。"""
+        key = (pid, dst.addr, dst.port)
+        return len(self._prune(key, self._clock())) >= self.threshold
+
+    def tripped(self, pid: int, dst: Endpoint) -> bool:
+        key = (pid, dst.addr, dst.port)
+        if len(self._prune(key, self._clock())) >= self.threshold:
+            self._trips[key] = self._trips.get(key, 0) + 1
+            self.trips_total += 1
+            return True
+        return False
+
+    def note(self, pid: int, dst: Endpoint) -> None:
+        key = (pid, dst.addr, dst.port)
+        now = self._clock()
+        self._prune(key, now)
+        self._hits.setdefault(key, []).append(now)
+
+    def reset(self, pid: int | None = None) -> None:
+        """熔断复位（维护线程定期调用，或 `cli stop --panic` 后清空）。"""
+        if pid is None:
+            self._hits.clear()
+            self._trips.clear()
+            return
+        for key in [k for k in self._hits if k[0] == pid]:
+            del self._hits[key]
+        for key in [k for k in self._trips if k[0] == pid]:
+            del self._trips[key]
+
+    def stats(self) -> dict[str, int]:
+        return {"tracked": len(self._hits), "trips_total": self.trips_total}
+
+
+# ============================================================ 预编译 ========
+def _fold(text: str) -> str:
+    """ASCII 快速小写。
+
+    `str.lower()` 对纯小写字符串会返回同一个对象（CPython 的优化），
+    所以这里不需要自己做"是否含大写"的判断，判断本身比调用更贵。
+    """
+    if text.islower():
+        return text
+    return text.lower()
+
+
+def compile_one_matcher(
+    patterns: tuple[str, ...],
+) -> Callable[[str, str], bool]:
+    """把一组进程模式编译成一个 `(folded_name, folded_path) -> bool` 谓词。
+
+    * 无通配符的模式 → 预建 `frozenset`（名字）/ 集合（路径），O(1) 命中；
+    * 有通配符的模式 → fnmatch（只在必要时走正则）；
+    * 大小写不敏感由调用方每条连接只折叠一次（`prepare()`）来保证，
+      因此这里收到的已经是小写键，热路径上零转换开销。
+    """
+    names: list[str] = []
+    paths: list[str] = []
+    name_wild: list[str] = []
+    path_wild: list[str] = []
+    for pattern in patterns:
+        if pattern == "*":
+            return _match_any
+        wild = has_wildcard(pattern)
+        normalized = pattern if wild else pattern.lower()
+        if "\\" in pattern or "/" in pattern:
+            (path_wild if wild else paths).append(normalized)
+        else:
+            (name_wild if wild else names).append(normalized)
+
+    if not names and not name_wild and not paths and not path_wild:
+        return _match_none
+
+    name_exact = frozenset(names)
+    path_set = frozenset(paths)
+    name_wild_t = tuple(name_wild)
+    path_wild_t = tuple(path_wild)
+    path_base_pairs = tuple((p, _basename(p)) for p in (*paths, *path_wild_t) if _basename(p))
+    any_path_only = not name_exact and not name_wild_t and bool(paths or path_wild_t)
+
+    def matcher(name_key: str, path_key: str) -> bool:
+        if name_exact and name_key in name_exact:
+            return True
+        if path_set and path_key in path_set:
+            return True
+        if name_wild_t and any(wildcard_match(p, name_key) for p in name_wild_t):
+            return True
+        if path_wild_t:
+            if path_key:
+                if any(wildcard_match(p, path_key) for p in path_wild_t):
+                    return True
+            # 受保护进程拿不到路径 → 降级按文件名匹配（受保护进程拿不到路径）
+            elif any(wildcard_match(base, name_key) for _p, base in path_base_pairs):
+                return True
+        if not any_path_only:
+            return False
+        if not path_key:
+            # 纯路径模式 + 无路径 → 只能按文件名兜底
+            return any(wildcard_match(base, name_key) for _p, base in path_base_pairs)
+        return False
+
+    return matcher
+
+
+def _match_any(_name: str, _path: str) -> bool:
+    return True
+
+
+def _match_none(_name: str, _path: str) -> bool:
+    return False
+
+
+@dataclass(slots=True)
+class CompiledRule:
+    rule: Rule
+    matcher: Callable[[str, str], bool]
+    proto: str
+    ports: tuple[tuple[int, int], ...] | None  # None = 任意
+    nets: tuple[ipaddress.IPv4Network | ipaddress.IPv6Network, ...] | None  # None = 任意
+    dst_names: tuple[str, ...]
+    any_dst_name: bool
+    # 从 `rule` 里摊平出来的热路径字段（避免每条规则两次 dataclass 属性访问）
+    enabled: bool
+    action: Action
+    keep_private_proxied: bool
+    upstream: str
+    rule_id: str
+
+    def prepare(self, conn: ConnRequest) -> tuple[str, str]:
+        """每条连接只做一次的大小写归一化（热路径预算的关键）。"""
+        proc = conn.proc
+        return _fold(proc.name or ""), _fold(proc.path or "")
+
+    def match(self, conn: ConnRequest, name: str | None, ip: Any = None, keys: tuple[str, str] | None = None) -> bool:
+        """热路径：不进 `decide()` 的规则在这里被快速排除。
+
+        `ip` 是调用方预先解析好的 `ipaddress` 对象（避免每条规则重复解析）；
+        `keys` 是 `prepare()` 的结果（避免每条规则重复折叠大小写）。
+        """
+        if keys is None:
+            keys = self.prepare(conn)
+        if not self.matcher(keys[0], keys[1]):
+            return False
+
+        if self.proto != "*" and self.proto != conn.proto.value:
+            return False
+
+        if self.ports is not None and not any(lo <= conn.dst.port <= hi for lo, hi in self.ports):
+            return False
+
+        if self.nets is not None:
+            if ip is None:
+                return False
+            if not any(ip.version == n.version and ip in n for n in self.nets):
+                return False
+
+        if not self.any_dst_name:
+            if name is None:
+                return False  # 域名未知 → 该规则不适用（不做近似猜测）
+            if not any(wildcard_match(p, name) for p in self.dst_names):
+                return False
+        return True
+
+
+@dataclass(slots=True)
+class CompiledProfile:
+    profile: Profile
+    rules: list[CompiledRule]
+
+    @classmethod
+    def build(cls, profile: Profile) -> CompiledProfile:
+        return cls(profile=profile, rules=[compile_rule(r) for r in profile.rules])
+
+
+def compile_rule(rule: Rule) -> CompiledRule:
+    targets = tuple(p for p in (t.strip() for t in _split(rule.targets, ";")) if p)
+
+    ports: list[tuple[int, int]] = []
+    ports_any = False
+    for item in (p.strip() for p in _split(rule.dst_port or "*", ",")):
+        if not item or item == "*":
+            ports_any = True
+            continue
+        if "-" in item:
+            lo_s, _, hi_s = item.partition("-")
+            try:
+                ports.append((int(lo_s), int(hi_s)))
+            except ValueError:
+                continue
+        else:
+            try:
+                port = int(item)
+            except ValueError:
+                continue
+            ports.append((port, port))
+
+    nets: list[ipaddress.IPv4Network | ipaddress.IPv6Network] = []
+    nets_any = False
+    for item in (p.strip() for p in _split(rule.dst_ip or "*", ",")):
+        if not item or item == "*":
+            nets_any = True
+            continue
+        try:
+            nets.append(ipaddress.ip_network(item, strict=False))
+        except ValueError:
+            continue
+
+    dst_names = tuple(p for p in (t.strip() for t in _split(rule.dst_name or "*", ",")) if p)
+    any_dst_name = not dst_names or "*" in dst_names
+
+    return CompiledRule(
+        rule=rule,
+        matcher=compile_one_matcher(targets),
+        proto=(rule.proto or "*").strip().lower(),
+        ports=None if (ports_any or not ports) else tuple(ports),
+        nets=None if (nets_any or not nets) else tuple(nets),
+        dst_names=tuple(n for n in dst_names if n != "*"),
+        any_dst_name=any_dst_name,
+        enabled=rule.enabled,
+        action=rule.action,
+        keep_private_proxied=rule.keep_private_proxied,
+        upstream=rule.upstream,
+        rule_id=rule.id,
+    )
+
+
+_COMPILED_CACHE: weakref.WeakKeyDictionary[Profile, CompiledProfile] = weakref.WeakKeyDictionary()
+
+
+def compiled(profile: Profile) -> CompiledProfile:
+    """取（并缓存）预编译结果。热重载会换掉整个 `Profile` 对象 → 旧缓存自然失效。"""
+    try:
+        cached = _COMPILED_CACHE.get(profile)
+        if cached is not None:
+            return cached
+        built = CompiledProfile.build(profile)
+        _COMPILED_CACHE[profile] = built
+        return built
+    except TypeError:
+        # Profile 不可弱引用（或临时对象）时退化为每次编译
+        return CompiledProfile.build(profile)
+
+
+# ============================================================ 主入口 ========
+def decide(
+    conn: ConnRequest,
+    profile: Profile,
+    sessions: StickySessions | None = None,
+    guards: GuardSet | None = None,
+) -> Decision:
+    """按固定顺序做决策（纯函数；不阻塞、不做 IO）。"""
+    g = guards if guards is not None else GuardSet()
+    sessions = sessions if sessions is not None else NullSessions()
+
+    # ---- 未知 PID 处置----
+    if conn.proc.pid <= 0:
+        g.note_unknown_pid()
+        return fallback_decision(g.on_unknown_pid or "direct", profile, reason=REASON_UNKNOWN_PID)
+
+    # ---- 守卫 G1：回环/私网/链路本地 ----
+    private = g.is_private(conn.dst.addr)
+    dst_ip = _parse_ip(conn.dst.addr)
+
+    # ---- 守卫 G2：自身进程 ----
+    if g.is_self_pid(conn.proc.pid):
+        return Decision(Action.DIRECT, reason=REASON_SELF_PID)
+
+    # ---- 守卫 G3：上游/DNS 端点 ----
+    if g.is_upstream_endpoint(conn.dst):
+        return Decision(Action.DIRECT, reason=REASON_UPSTREAM_ENDPOINT)
+
+    # ---- 守卫 G4：熔断 ----
+    if g.breaker_tripped(conn.proc.pid, conn.dst):
+        return Decision(Action.DIRECT, reason=REASON_LOOP_BREAKER)
+
+    # ---- 规则匹配（自上而下，首个命中生效）----
+    name = g.name_for_ip(conn.dst.addr)
+    sticky = sessions.sticky_upstream if profile.sticky_per_pid else None
+    pid = conn.proc.pid
+    rules = compiled(profile).rules
+    keys = rules[0].prepare(conn) if rules else ("", "")
+    proto_value = conn.proto.value
+    port = conn.dst.port
+    for cr in rules:
+        if not cr.enabled:
+            continue
+        action = cr.action
+        if private and not cr.keep_private_proxied and action is Action.PROXY:
+            # 私网/回环默认直连（默认放行回环/私网）：
+            # 只有"显式要求代理私网"的规则才能代理私网，其余 proxy 规则不适用。
+            continue
+        if not cr.matcher(keys[0], keys[1]):
+            continue
+        proto = cr.proto
+        if proto != "*" and proto != proto_value:
+            continue
+        ports = cr.ports
+        if ports is not None and not any(lo <= port <= hi for lo, hi in ports):
+            continue
+        nets = cr.nets
+        if nets is not None and (
+            dst_ip is None or not any(dst_ip.version == n.version and dst_ip in n for n in nets)
+        ):
+            continue
+        name_inferred = False
+        if not cr.any_dst_name:
+            if name is None or not any(wildcard_match(p, name) for p in cr.dst_names):
+                continue
+            name_inferred = name in g.inferred_names
+        if name_inferred and action is Action.BLOCK:
+            # 红线：DNS 嗅探来的 IP→域名映射只是
+            # 近似（TTL 内有效，CDN 会误判），不得用于 BLOCK 决策
+            # 猜错域名就断掉一条本来正常的连接，代价远大于收益。
+            # 近似匹配只对 proxy/direct 开放，且日志里带 `name-inferred` 标记。
+            continue
+        upstream = cr.upstream
+        if action is Action.PROXY and sticky is not None:
+            upstream = sticky(pid, cr.rule_id, default=upstream)
+        reason = f"rule:{cr.rule_id}"
+        if name_inferred:
+            reason = f"rule:{cr.rule_id};{REASON_NAME_INFERRED}"
+        return Decision(action, rule_id=cr.rule_id, upstream=upstream, reason=reason)
+
+    if private:
+        # 私网未命中任何 keep_private_proxied 规则 → 直连（理由可解释）
+        fallback = profile.default_action
+        if fallback is Action.PROXY:
+            return Decision(Action.DIRECT, reason=REASON_GUARD_PRIVATE)
+        return Decision(fallback, reason=REASON_GUARD_PRIVATE)
+
+    return Decision(profile.default_action, reason=REASON_DEFAULT)
+
+
+def _first_proxy_rule(cp: CompiledProfile) -> CompiledRule | None:
+    for cr in cp.rules:
+        if cr.enabled and cr.action is Action.PROXY:
+            return cr
+    return None
+
+
+def fallback_decision(policy: str, profile: Profile | None, *, reason: str) -> Decision:
+    """把 `direct | proxy | block` 策略串翻成一条 `Decision`。
+
+    两处"我们不知道该怎么办"的兜底共用它，语义必须一致：
+
+    * PID 未知（`service.on_unknown_pid`，路线 A 的查表竞态）；
+    * 决策路径抛异常（`service.on_decide_error`）。
+
+    `proxy` 需要一个上游，取第一条 `action=proxy` 的启用规则（沿用同一约定）；
+    一条都没有时退化成 `BLOCK`，不静默直连。
+    """
+    name = (policy or "").strip().lower()
+    if name == "proxy":
+        cr = _first_proxy_rule(compiled(profile)) if profile is not None else None
+        if cr is None:
+            return Decision(Action.BLOCK, reason=f"{reason}:proxy-no-upstream")
+        return Decision(
+            Action.PROXY, rule_id=cr.rule.id, upstream=cr.rule.upstream, reason=f"{reason}:proxy"
+        )
+    if name == "block":
+        return Decision(Action.BLOCK, reason=f"{reason}:block")
+    return Decision(Action.DIRECT, reason=f"{reason}:direct")
+
+
+class NullSessions:
+    """无会话表时的粘性退化实现（单测/纯决策路径用）。"""
+
+    def sticky_upstream(self, pid: int, rule_id: str, *, default: str = "") -> str:
+        return default
+
+
+# ------------------------------------------------------------ 可观测辅助 ----
+def explain(conn: ConnRequest, profile: Profile, guards: GuardSet | None = None) -> list[dict[str, Any]]:
+    """`cli rules --trace` 用：打印逐条规则的判定链路（不用于热路径）。"""
+    g = guards if guards is not None else GuardSet()
+    name = g.name_for_ip(conn.dst.addr)
+    trace: list[dict[str, Any]] = [
+        {"stage": "G1", "check": "private", "value": g.is_private(conn.dst.addr)},
+        {"stage": "G2", "check": "self-pid", "value": g.is_self_pid(conn.proc.pid)},
+        {"stage": "G3", "check": "upstream-endpoint", "value": g.is_upstream_endpoint(conn.dst)},
+        {"stage": "G4", "check": "loop-breaker", "value": g.breaker_tripped(conn.proc.pid, conn.dst)},
+        {"stage": "name", "check": "dst_name", "value": name},
+    ]
+    ip = _parse_ip(conn.dst.addr)
+    private = g.is_private(conn.dst.addr)
+    for cr in compiled(profile).rules:
+        private_block = private and cr.action is Action.PROXY and not cr.keep_private_proxied
+        # 与 `decide()` 保持同一语义：带 `dst_ip` 的规则需要预先解析好的 IP，
+        # 禁用规则不参与判定，推断域名不得触发 BLOCK。
+        hit = cr.enabled and cr.match(conn, name, ip) and not private_block
+        if hit and not cr.any_dst_name and cr.action is Action.BLOCK and name in g.inferred_names:
+            hit = False
+        trace.append(
+            {
+                "stage": "rule",
+                "id": cr.rule_id,
+                "action": cr.action.value,
+                "matched": hit,
+                "enabled": cr.enabled,
+            }
+        )
+    return trace
+
+
+def stats_snapshot(profile: Profile, guards: GuardSet | None = None) -> dict[str, Any]:
+    g = guards if guards is not None else GuardSet()
+    out: dict[str, Any] = {
+        "rules": len(profile.rules),
+        "enabled_rules": sum(1 for r in profile.rules if r.enabled),
+        "upstreams": sorted(profile.upstreams),
+        "default_action": profile.default_action.value,
+        "self_pids": sorted(g.self_pids),
+        "upstream_endpoints": sorted(f"{h}:{p}" for h, p in g.upstream_endpoints),
+        "local_dns_servers": sorted(g.local_dns_servers),
+        "unknown_pid": g.unknown_pid,
+    }
+    if g.breaker is not None:
+        out["loop_breaker"] = g.breaker.stats()
+    return out