procproxy 0.1.0__py3-none-any.whl

proxycore/api.py

@@ -0,0 +1,226 @@
+"""编程式启动接口：在 Python 里直接起 ProcProxy（不需要 CLI / 不需要 PowerShell）。
+
+三种用法：
+
+```python
+# ① 最简：起服务，拿到句柄，自己用
+from proxycore.api import start_proxy
+
+with start_proxy("samples/profiles/dev.yaml", backend="null") as ppx:
+    print(ppx.status())          # 后端/规则/会话统计
+    print(ppx.sessions())        # 活跃会话
+    print(ppx.proxy.of("127.0.0.1:8081"))   # sink 地址
+
+# ② 只想验证转发链路（不做抓包）：把 sink 收到的连接转发到固定目标
+from proxycore.api import start_proxy
+with start_proxy("samples/profiles/smoke.yaml", backend="null",
+                 sink_test_target="127.0.0.1:8080", upstream="local-mock") as ppx:
+    ...
+    # 此时 curl -x http://127.0.0.1:19080 http://any/ 会被转发到 127.0.0.1:8080
+
+# ③ 内嵌到自己的程序里：自己喂连接、自己看决策
+from proxycore.api import make_runtime
+rt = make_runtime("samples/profiles/dev.yaml", backend="null")
+decision = rt.decide(conn_request)      # 纯决策，不抓包
+```
+
+`start_proxy()` 返回的 `ProxyHandle` 支持 `with`（退出时自动 stop），
+也可以手动 `handle.stop()`。
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any
+
+from .config import Config, ConfigError, ConfigManager
+from .log import EventLogger, build_logger, get_logger
+from .runtime import Runtime
+from .types import ConnRequest, Decision
+
+LOG = EventLogger(get_logger("proxycore.api"))
+
+
+class ProxyStartError(RuntimeError):
+    """启动失败（配置非法 / 后端不可用 / sink 端口占用）。"""
+
+
+def _coerce_config(config: Config | str | os.PathLike[str], *, check_sink: bool = False) -> Config:
+    if isinstance(config, Config):
+        return config
+    return load_config(os.fspath(config), check_sink=check_sink)
+
+
+def load_config(path: str | os.PathLike[str], *, check_sink: bool = False) -> Config:
+    """读配置（含 V1–V10 校验）。失败抛 `ProxyStartError`。"""
+    try:
+        return Config.load(path, check_sink=check_sink)
+    except ConfigError as exc:
+        raise ProxyStartError(f"配置无效：[{exc.code}] {exc.message}") from exc
+
+
+def make_runtime(
+    config: Config | str | os.PathLike[str],
+    *,
+    backend: str = "",
+    log_level: str = "INFO",
+    log_jsonl: str = "",
+) -> Runtime:
+    """只装配 Runtime（不 start），便于在测试/嵌入场景里自己控制生命周期。"""
+    config = _coerce_config(config)
+    if backend:
+        config.service.backend = backend
+    if log_level:
+        config.service.log_level = log_level
+    if log_jsonl:
+        config.service.log_jsonl = log_jsonl
+
+    build_logger("proxycore", level=config.service.log_level, jsonl_path=config.service.log_jsonl or None)
+
+    from .backend import BackendUnavailable, make_backend
+
+    try:
+        backend_obj = make_backend(config.service.backend, config=config)
+    except BackendUnavailable as exc:
+        # 绝不静默直连，启动失败就明确失败
+        raise ProxyStartError(
+            f"后端不可用（{getattr(exc, 'code', 'E_BACKEND_UNAVAILABLE')}）：{exc}"
+        ) from exc
+
+    return Runtime(ConfigManager(config), backend_obj)
+
+
+@dataclass
+class ProxyHandle:
+    """已启动的 ProcProxy 句柄。"""
+
+    runtime: Runtime
+    sink: str
+    backend: str
+    _stopped: bool = False
+
+    # ------------------------------------------------------------ 控制 -----
+    def stop(self, *, reason: str = "api-stop") -> None:
+        if self._stopped:
+            return
+        self.runtime.stop(reason=reason)
+        self._stopped = True
+
+    def __enter__(self) -> ProxyHandle:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.stop()
+
+    @property
+    def running(self) -> bool:
+        return not self._stopped
+
+    # ------------------------------------------------------------ 查询 -----
+    def status(self) -> dict[str, Any]:
+        snapshot = self.runtime.snapshot()
+        return {
+            "name": self.backend,          # 后端名（"null" | "windivert"）
+            "backend": snapshot["backend"],  # 后端计数字典
+            "rules": snapshot["rules"],
+            "sessions": snapshot["sessions"],
+            "breaker": snapshot["breaker"],
+            "dns": snapshot["dns"],
+            "sink": self.sink,
+            "running": self.running,
+        }
+
+    def sessions(self, limit: int = 50) -> list[dict[str, Any]]:
+        return [s.to_dict() for s in self.runtime.sessions.all()][-limit:]
+
+    def active_sessions(self) -> int:
+        return self.runtime.sessions.count()
+
+    def reload(self, path: str = "") -> int:
+        """热重载配置，返回新的 generation（失败抛 `ProxyStartError`）。"""
+        target = path or self.runtime.config.path
+        try:
+            self.runtime.manager.reload(target)
+        except ConfigError as exc:
+            raise ProxyStartError(f"热重载被拒绝：[{exc.code}] {exc.message}") from exc
+        # 与文件监视器走同一个收口（DNS/UDP 策略 + 守卫 + 粘性迁移），
+        # 否则这条入口会悄悄少刷新几样东西。
+        self.runtime.apply_profile()
+        return self.runtime.manager.generation
+
+    def decide(self, conn: ConnRequest) -> Decision:
+        """直接问规则引擎"这条连接怎么处理"（不抓包、不改道）。"""
+        return self.runtime.decide(conn)
+
+    @property
+    def profile(self) -> Any:
+        return self.runtime.config.profile
+
+    def __repr__(self) -> str:
+        return f"<ProxyHandle backend={self.backend} sink={self.sink} running={self.running}>"
+
+
+def start_proxy(
+    config: Config | str | os.PathLike[str] = "samples/profiles/dev.yaml",
+    *,
+    backend: str = "",
+    sink_test_target: str = "",
+    upstream: str = "",
+    log_level: str = "INFO",
+    log_jsonl: str = "",
+) -> ProxyHandle:
+    """启动 ProcProxy 数据面（sink 监听 + 后端 + 规则 + 会话表）。
+
+    * 返回的 `ProxyHandle` 支持 `with`，退出会自动 stop；
+    * `backend=""` 用配置里的 backend；`backend="null"` 用于联调（不抓包）；
+    * `sink_test_target` 非空 = 测试模式：sink 把所有连接转发到该固定目标；
+    * 后端不可用（WinDivert 不可加载/非管理员）→ 抛 `ProxyStartError`，不会静默直连。
+    """
+    config_obj = _coerce_config(config)
+    runtime = make_runtime(
+        config_obj,
+        backend=backend,
+        log_level=log_level,
+        log_jsonl=log_jsonl,
+    )
+    try:
+        runtime.start(sink_test_target=sink_test_target, upstream_alias=upstream)
+    except Exception as exc:  # 启动失败要保证不留半开的监听
+        runtime.stop(reason="start-failed")
+        raise ProxyStartError(f"启动失败：{exc}") from exc
+
+    sink_cfg = runtime.config.service.sink
+    LOG.info(
+        "api_started",
+        backend=runtime.backend.name,
+        sink=f"{sink_cfg.host}:{sink_cfg.port}",
+        test_target=sink_test_target or "-",
+    )
+    return ProxyHandle(
+        runtime=runtime,
+        sink=f"{sink_cfg.host}:{sink_cfg.port}",
+        backend=runtime.backend.name,
+    )
+
+
+def run_forever(config: Config | str | os.PathLike[str] = "samples/profiles/dev.yaml", **kwargs: Any) -> int:
+    """启动并阻塞（等价于 `cli run`），Ctrl+C 退出。返回进程退出码。"""
+    handle = start_proxy(config, **kwargs)
+    try:
+        handle.runtime.serve_forever(reload_watch=True)
+    except KeyboardInterrupt:
+        print("\n收到 Ctrl+C，正在停止…")
+    finally:
+        handle.stop(reason="signal")
+    return 0
+
+
+__all__ = [
+    "ProxyHandle",
+    "ProxyStartError",
+    "load_config",
+    "make_runtime",
+    "run_forever",
+    "start_proxy",
+]

proxycore/backend/__init__.py

@@ -0,0 +1,49 @@
+"""后端工厂。
+
+当前只包含两条实现：
+
+* `windivert`：路线 A，用户态 WinDivert（pydivert 自带已签名的 `WinDivert64.sys`）；
+* `null`：联调用的空后端：不抓包、不改道，只提供 `decide()` 与状态输出。
+
+硬性约束：后端不可用时必须明确报错退出，禁止静默直连
+（用户会以为在走代理，实际是把真实 IP 漏出去了）。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .base import (
+    Backend,
+    BackendUnavailable,
+    OriginalDstUnknown,
+    RedirectFailed,
+)
+from .null import NullBackend
+
+SUPPORTED_BACKENDS = ("null", "windivert")
+
+__all__ = [
+    "SUPPORTED_BACKENDS",
+    "Backend",
+    "BackendUnavailable",
+    "NullBackend",
+    "OriginalDstUnknown",
+    "RedirectFailed",
+    "make_backend",
+]
+
+
+def make_backend(name: str, *, config: Any = None, **kwargs: Any) -> Backend:
+    """按名字构造后端；不可用时抛 `BackendUnavailable`（绝不静默返回直连实现）。"""
+    backend = (name or "null").strip().lower()
+
+    if backend == "null":
+        return NullBackend()
+
+    if backend == "windivert":
+        from .windivert import WinDivertBackend
+
+        return WinDivertBackend(config=config, **kwargs)
+
+    raise BackendUnavailable(f"未知后端 {name!r}（可选：{', '.join(SUPPORTED_BACKENDS)}）")

proxycore/backend/base.py

@@ -0,0 +1,159 @@
+"""Backend 抽象（硬约束：改道失败不得静默直连）。
+
+各后端实现必须满足的语义：
+* `redirect()` 返回 `False` = 改道失败 → 核心必须记录并关闭该连接
+  （对 TCP 表示丢弃 SYN → 客户端超时；禁止"失败了就直连"）；
+* `lookup_original()` 必须能区分"没有重定向记录"（返回 None）与"查询出错"（抛异常）；
+* 所有后端必须支持热停：`stop()` 后 2 秒内不再回调 `decide`。
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from typing import Any, Protocol, runtime_checkable
+
+from ..types import Action, ConnRequest, Decision, Endpoint
+
+# 后端起停的硬性时限
+STOP_QUIESCE_SECONDS = 2.0
+
+
+class BackendUnavailable(RuntimeError):
+    """后端不可用（对应错误码 `E_BACKEND_UNAVAILABLE`）。"""
+
+    code = "E_BACKEND_UNAVAILABLE"
+
+
+class OriginalDstUnknown(LookupError):
+    """无法恢复原始目标（对应错误码 `E_ORIGINAL_DST_UNKNOWN`）。
+
+    `lookup_original()` 的契约：没有记录 → 返回 None；查询出错 → 抛本异常。
+    """
+
+    code = "E_ORIGINAL_DST_UNKNOWN"
+
+
+class RedirectFailed(RuntimeError):
+    """改道失败（对应错误码 `E_REDIRECT_FAILED`）。"""
+
+    code = "E_REDIRECT_FAILED"
+
+
+@runtime_checkable
+class Backend(Protocol):
+    name: str  # "windivert" | "null"
+    supports_udp: bool
+    supports_pid_native: bool  # True=后端自身能给出可靠 PID；False=需查表
+    counts_decisions: bool  # 决策类计数归谁记；`Runtime.start()` 会置 False（见 BaseBackend）
+
+    def start(self) -> None:
+        """打开句柄 / 注册过滤器。失败抛 BackendUnavailable。"""
+
+    def stop(self) -> None:
+        """卸载过滤器、销毁句柄、等待在途请求结束。幂等。"""
+
+    def set_decider(self, decide: Callable[[ConnRequest], Decision]) -> None:
+        """核心把决策函数注册给后端。后端在捕获到连接时调用。"""
+
+    def redirect(self, conn: ConnRequest, sink: Endpoint) -> bool:
+        """把这条连接（conn）改道到 sink。
+
+        WinDivert 后端：改写报文头并回注。
+        必须在 `set_decider` 的返回之前完成（同步语义）。
+        """
+
+    def lookup_original(self, client_socket: object, backend_ctx: int) -> Endpoint | None:
+        """sink accept 之后调用：恢复原始目标。
+
+        WinDivert 后端：用 `backend_ctx`(=客户端源端口) 查本地表。
+        路线A: 用 `backend_ctx`(=客户端源端口) 查本地表
+        返回 None 时 sink 必须关闭该连接并记 ERROR 日志。
+        """
+
+    def stats(self) -> dict[str, Any]:
+        """`{"captured": n, "redirected": n, "active_flows": n, "active_redirects": n}`"""
+
+    def on_udp(self, handler: Callable[[ConnRequest, bytes], Action]) -> None:
+        """可选：UDP 数据报到达（不支持的后端抛 NotImplementedError）。"""
+
+
+class BaseBackend:
+    """后端公共基类：统一计数、决策回调登记、线程安全停止。
+
+    不做平台相关的事情；平台后端继承它并实现 `start/stop/redirect/lookup_original`。
+    """
+
+    name: str = "base"
+    supports_udp: bool = False
+    supports_pid_native: bool = False
+
+    def __init__(self) -> None:
+        self._decider: Callable[[ConnRequest], Decision] | None = None
+        self._udp_handler: Callable[[ConnRequest, bytes], Action] | None = None
+        self._stopped = True
+        self._lock = threading.RLock()
+        self._counters: dict[str, int] = {"captured": 0, "redirected": 0, "direct": 0, "blocked": 0, "failed": 0}
+        self._active_flows = 0
+        self._active_redirects = 0
+
+    # ------------------------------------------------------------ 生命周期 --
+    def start(self) -> None:
+        self._stopped = False
+
+    def stop(self) -> None:
+        self._stopped = True
+
+    @property
+    def running(self) -> bool:
+        return not self._stopped
+
+    # --------------------------------------------------------------- 决策 ---
+    def set_decider(self, decide: Callable[[ConnRequest], Decision]) -> None:
+        self._decider = decide
+
+    def decide(self, conn: ConnRequest) -> Decision:
+        """后端在捕获到连接时调用（`redirect()` 必须在返回前完成）。"""
+        if self._decider is None:  # pragma: no cover - 启动顺序错误
+            raise RedirectFailed("set_decider() 尚未注册决策函数")
+        return self._decider(conn)
+
+    def on_udp(self, handler: Callable[[ConnRequest, bytes], Action]) -> None:
+        if not self.supports_udp:
+            raise NotImplementedError(f"{self.name} 后端不支持 UDP")
+        self._udp_handler = handler
+
+    # --------------------------------------------------------------- 计数 ---
+    #: 决策类计数（`captured`/`direct`/`blocked`）由谁来记。
+    #:
+    #: 后端可以脱离 `Runtime` 独立使用（单测、手工投喂联调），那时它得自己记。
+    #: 但一旦核心通过 `set_decider()` 接管，`Runtime.decide()` 自己就会记这三个键。
+    #: 后端再记一遍就是双倍（实测：喂 1 个包，`captured` 变 2）。
+    #: `Runtime.start()` 会把它置 `False`，那是这个关系的建立点，一眼能看见。
+    #:
+    #: 区分原则：决策计数归核心，传输计数（`redirected`/`failed`/`injected`）
+    #: 归后端：后者只有后端知道（改道是否真的发出去了）。
+    counts_decisions: bool = True
+
+    def count(self, key: str, delta: int = 1) -> None:
+        with self._lock:
+            self._counters[key] = self._counters.get(key, 0) + delta
+
+    def count_decision(self, key: str, delta: int = 1) -> None:
+        """记一个决策类计数；核心接管后是空操作（见 `counts_decisions`）。"""
+        if self.counts_decisions:
+            self.count(key, delta)
+
+    def set_active(self, flows: int | None = None, redirects: int | None = None) -> None:
+        with self._lock:
+            if flows is not None:
+                self._active_flows = flows
+            if redirects is not None:
+                self._active_redirects = redirects
+
+    def stats(self) -> dict[str, Any]:
+        with self._lock:
+            out = dict(self._counters)
+            out["active_flows"] = self._active_flows
+            out["active_redirects"] = self._active_redirects
+            return out

proxycore/backend/null.py

@@ -0,0 +1,51 @@
+"""`null` 后端：不做任何抓包/改道，只提供手工把连接送进 sink 的能力。
+
+用途：
+* 联调与测试（`--backend null --sink-test-target host:port`）；
+* L2 后端契约一致性测试的基准实现。
+
+它不会代理任何真实流量，这是刻意的，避免"看起来在走代理其实没走"。
+"""
+
+from __future__ import annotations
+
+from ..types import ConnRequest, Endpoint
+from .base import BaseBackend
+
+
+class NullBackend(BaseBackend):
+    name = "null"
+    supports_udp = True
+    supports_pid_native = False
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._origins: dict[int, Endpoint] = {}
+        self._next_id = 1
+        self._sink: Endpoint | None = None
+
+    # ------------------------------------------------------------ 生命周期 --
+    def start(self) -> None:
+        super().start()
+
+    def stop(self) -> None:
+        super().stop()
+        self._origins.clear()
+
+    # --------------------------------------------------------------- 改道 ---
+    def redirect(self, conn: ConnRequest, sink: Endpoint) -> bool:
+        if not self.running:
+            self.count("failed")
+            return False
+        self._sink = sink
+        # 先记账再"发包"
+        self._origins[conn.backend_id or (self._next_id)] = conn.dst
+        self._next_id += 1
+        self.count("redirected")
+        self.set_active(redirects=len(self._origins))
+        return True
+
+    def lookup_original(self, client_socket: object, backend_ctx: int) -> Endpoint | None:
+        return self._origins.get(backend_ctx)
+
+    # ------------------------------------------------------- 手工投喂（测试）--