procproxy 0.1.0__py3-none-any.whl

proxycore/types.py

@@ -0,0 +1,165 @@
+"""ProcProxy 核心数据结构。
+
+类型名、字段名、默认值都是对外契约，不得改名；扩展只能加字段。
+"""
+
+from __future__ import annotations
+
+import contextlib
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class Proto(Enum):
+    TCP = "tcp"
+    UDP = "udp"
+
+
+class Action(Enum):
+    DIRECT = "direct"  # 直连（不走代理）
+    PROXY = "proxy"  # 走代理
+    BLOCK = "block"  # 丢弃（连接失败 / 数据报丢弃）
+
+
+@dataclass(frozen=True, slots=True)
+class Endpoint:
+    addr: str  # 点分/冒分格式，不含端口
+    port: int
+    is_v6: bool = False
+
+    def __str__(self) -> str:
+        if self.is_v6:
+            return f"[{self.addr}]:{self.port}"
+        return f"{self.addr}:{self.port}"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"addr": self.addr, "port": self.port, "is_v6": self.is_v6}
+
+    @classmethod
+    def from_dict(cls, doc: dict[str, Any]) -> Endpoint:
+        return cls(addr=str(doc["addr"]), port=int(doc["port"]), is_v6=bool(doc.get("is_v6", False)))
+
+
+@dataclass(slots=True)
+class ProcInfo:
+    pid: int
+    name: str  # "chrome.exe"（无路径）
+    path: str  # "C:\\Program Files\\...\\chrome.exe"（可能为空：受保护进程）
+    session_id: int = 0  # Windows 会话 ID；Linux 为 0；macOS 为 0
+    user: str = ""  # 可空
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "pid": self.pid,
+            "name": self.name,
+            "path": self.path,
+            "session_id": self.session_id,
+            "user": self.user,
+        }
+
+    @classmethod
+    def from_dict(cls, doc: dict[str, Any]) -> ProcInfo:
+        return cls(
+            pid=int(doc.get("pid", 0)),
+            name=str(doc.get("name", "")),
+            path=str(doc.get("path", "")),
+            session_id=int(doc.get("session_id", 0)),
+            user=str(doc.get("user", "")),
+        )
+
+
+@dataclass(slots=True)
+class ConnRequest:
+    """后端交给核心的一条"待决策连接"。"""
+
+    proc: ProcInfo
+    proto: Proto
+    src: Endpoint
+    dst: Endpoint
+    backend_id: int = 0  # 后端上下文（路线 A: 客户端源端口）
+    redirect_supported: bool = True  # UDP 在部分后端为 False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "proc": self.proc.to_dict(),
+            "proto": self.proto.value,
+            "src": self.src.to_dict(),
+            "dst": self.dst.to_dict(),
+            "backend_id": self.backend_id,
+            "redirect_supported": self.redirect_supported,
+        }
+
+
+@dataclass(slots=True)
+class Decision:
+    action: Action
+    rule_id: str = ""  # 命中的规则（用于日志/统计）
+    upstream: str = ""  # 上游别名（PROXY 时必填）
+    reason: str = ""  # "rule:proxy-chrome" / "self-pid" / "loop-breaker" ...
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "action": self.action.value,
+            "rule_id": self.rule_id,
+            "upstream": self.upstream,
+            "reason": self.reason,
+        }
+
+
+@dataclass(slots=True)
+class Session:
+    id: int
+    proc: ProcInfo
+    proto: Proto
+    original: Endpoint  # 真实目标（未改道前的）
+    upstream: str
+    rule_id: str
+    started_at: float
+    bytes_up: int = 0  # 客户端 → 目标
+    bytes_down: int = 0
+    state: str = "connecting"  # connecting|relaying|closed|failed
+    error: str = ""
+
+    @property
+    def duration_ms(self) -> float:
+        import time
+
+        return (time.time() - self.started_at) * 1000.0
+
+    def to_dict(self) -> dict[str, Any]:
+        import time
+
+        return {
+            "session_id": self.id,
+            "pid": self.proc.pid,
+            "proc": self.proc.name,
+            "proto": self.proto.value,
+            "original": str(self.original),
+            "upstream": self.upstream,
+            "rule": self.rule_id,
+            "state": self.state,
+            "bytes_up": self.bytes_up,
+            "bytes_down": self.bytes_down,
+            "started_at": self.started_at,
+            "duration_ms": round((time.time() - self.started_at) * 1000.0, 3),
+            "error": self.error,
+        }
+
+
+@dataclass(slots=True)
+class UdpAssociation:
+    """`UpstreamDialer.dial_udp()` 的返回值。"""
+
+    relay: Endpoint  # 中继地址（BND.ADDR/BND.PORT）
+    control_sock: Any = None  # 控制用 TCP 连接（SOCKS5 UDP ASSOCIATE 用）
+    upstream: str = ""
+    created_at: float = 0.0
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def close(self) -> None:
+        sock = self.control_sock
+        if sock is not None:
+            with contextlib.suppress(OSError):  # 关闭失败无补救
+                sock.close()
+        self.control_sock = None

proxycore/upstream/__init__.py

@@ -0,0 +1,52 @@
+"""上游客户端：SOCKS5（含 UDP ASSOCIATE）、SOCKS4/4a、HTTP CONNECT（含 Basic）、跳链。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .base import (
+    AuthFailed,
+    BaseDialer,
+    TargetRefused,
+    UnsupportedAuth,
+    UpstreamDialer,
+    UpstreamDown,
+    UpstreamError,
+)
+
+KIND_TO_DIALER = {
+    "socks5": ("proxycore.upstream.socks5", "Socks5Dialer"),
+    "socks4": ("proxycore.upstream.socks4", "Socks4Dialer"),
+    "http": ("proxycore.upstream.http_connect", "HttpConnectDialer"),
+    "https": ("proxycore.upstream.http_connect", "HttpConnectDialer"),
+}
+
+
+def make_dialer(upstream: Any, *, timeout: float = 15.0, resolver: Any = None) -> UpstreamDialer:
+    """按 `upstream.kind` 构造 dialer；`chain` 非空时套一层跳链。
+
+    `resolver(alias) -> Upstream` 用于跳链解析（调用方注入 `profile.upstreams`）。
+    """
+    kind = str(getattr(upstream, "kind", "socks5")).lower()
+    module_name, class_name = KIND_TO_DIALER.get(kind, KIND_TO_DIALER["socks5"])
+    module = __import__(module_name, fromlist=[class_name])
+    dialer_cls = getattr(module, class_name)
+    dialer = dialer_cls(upstream, timeout=timeout, resolver=resolver)
+    chain = list(getattr(upstream, "chain", []) or [])
+    if chain:
+        from .chain import ChainDialer
+
+        return ChainDialer(dialer, chain, timeout=timeout, resolver=resolver)
+    return dialer
+
+
+__all__ = [
+    "AuthFailed",
+    "BaseDialer",
+    "TargetRefused",
+    "UnsupportedAuth",
+    "UpstreamDialer",
+    "UpstreamDown",
+    "UpstreamError",
+    "make_dialer",
+]

proxycore/upstream/base.py

@@ -0,0 +1,150 @@
+"""上游抽象。
+
+`UpstreamDialer` 的语义硬约束：
+* `hostname` 非空时必须使用远端解析（SOCKS5 `ATYP=0x03` / SOCKS4a / HTTP CONNECT 原样传域名）；
+* 认证失败 / 目标不可达必须抛出区分明确的异常：`AuthFailed`、`TargetRefused`、`UpstreamDown`，
+  统计口径不同（`E_UPSTREAM_AUTH` / `E_UPSTREAM_DOWN` / `E_TARGET_REFUSED`）。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import socket
+from typing import Any, Protocol, runtime_checkable
+
+from ..types import Endpoint
+
+
+class UpstreamError(RuntimeError):
+    """上游相关错误的基类（带 `code`，便于统计与测试断言）。"""
+
+    code = "E_UPSTREAM_DOWN"
+
+
+class AuthFailed(UpstreamError):
+    """认证失败（对应 `E_UPSTREAM_AUTH`）。"""
+
+    code = "E_UPSTREAM_AUTH"
+
+
+class TargetRefused(UpstreamError):
+    """目标拒绝/不可达（对应 `E_TARGET_REFUSED`）。"""
+
+    code = "E_TARGET_REFUSED"
+
+
+class UpstreamDown(UpstreamError):
+    """上游不可达（对应 `E_UPSTREAM_DOWN`）。禁止在此情况下改为直连。"""
+
+    code = "E_UPSTREAM_DOWN"
+
+
+class UnsupportedAuth(UpstreamError):
+    """该平台/该协议不支持所选认证方式（例如非 Windows 上的 NTLM）。"""
+
+    code = "E_UPSTREAM_AUTH"
+
+
+@runtime_checkable
+class UpstreamDialer(Protocol):
+    async def dial_tcp(self, dst: Endpoint, hostname: str | None) -> socket.socket: ...
+
+    async def dial_udp(self, dst: Endpoint) -> Any: ...
+
+    def supports_udp(self) -> bool: ...
+
+    def dial_tcp_sync(self, dst: Endpoint, hostname: str | None = None) -> socket.socket: ...
+
+
+class BaseDialer:
+    """公共逻辑：域名透传判定、错误映射、超时。"""
+
+    kind = "base"
+    supports_udp_flag = False
+
+    def __init__(self, upstream: Any, *, timeout: float = 15.0) -> None:
+        self.upstream = upstream
+        self.timeout = timeout
+
+    @property
+    def alias(self) -> str:
+        return str(getattr(self.upstream, "alias", ""))
+
+    def supports_udp(self) -> bool:
+        return bool(self.supports_udp_flag and getattr(self.upstream, "udp", False))
+
+    # ------------------------------------------------------------ 工具 -----
+    def _connect_upstream(self) -> socket.socket:
+        host = str(getattr(self.upstream, "host", ""))
+        port = int(getattr(self.upstream, "port", 0))
+        return tcp_connect(host, port, timeout=self.timeout)
+
+    def dial_tcp_sync(self, dst: Endpoint, hostname: str | None = None) -> socket.socket:
+        raise NotImplementedError
+
+    def tunnel_over(
+        self, sock: socket.socket, dst: Endpoint, hostname: str | None = None
+    ) -> socket.socket:
+        """在已建立的连接之上再开一条隧道（跳链用）。
+
+        默认实现：直接返回原 socket（表示"这一跳不需要额外握手"）。
+        """
+        return sock
+
+    async def dial_tcp(self, dst: Endpoint, hostname: str | None = None) -> socket.socket:
+        """契约里的 async 形式。
+
+        底层是阻塞 socket：必须丢到线程里，否则调用方的事件循环会被握手
+        和 DNS 阻塞（本仓库当前没有 await 调用者，但这是对外 API）。
+        """
+        return await asyncio.to_thread(self.dial_tcp_sync, dst, hostname)
+
+    async def dial_udp(self, dst: Endpoint) -> Any:
+        raise NotImplementedError("该上游不支持 UDP ASSOCIATE")
+
+
+def tcp_connect(host: str, port: int, *, timeout: float = 15.0) -> socket.socket:
+    """连上游；把 OSError 映射成 `UpstreamDown`（绝不静默直连）。"""
+    try:
+        sock = socket.create_connection((host, port), timeout=timeout)
+    except TimeoutError as exc:
+        raise UpstreamDown(f"连接上游 {host}:{port} 超时（{timeout}s）") from exc
+    except socket.gaierror as exc:
+        raise UpstreamDown(f"上游域名解析失败 {host}: {exc}") from exc
+    except OSError as exc:
+        raise UpstreamDown(f"连接上游 {host}:{port} 失败: {exc}") from exc
+    sock.settimeout(timeout)
+    return sock
+
+
+def recv_exact(sock: socket.socket, n: int) -> bytes:
+    """读满 n 字节；不足即视为上游断开。"""
+    buf = bytearray()
+    while len(buf) < n:
+        try:
+            chunk = sock.recv(n - len(buf))
+        except TimeoutError as exc:
+            raise UpstreamDown("读取上游响应超时") from exc
+        except OSError as exc:
+            raise UpstreamDown(f"读取上游失败: {exc}") from exc
+        if not chunk:
+            raise UpstreamDown(f"上游提前关闭（期望 {n} 字节，实际 {len(buf)}）")
+        buf.extend(chunk)
+    return bytes(buf)
+
+
+def pack_port(port: int) -> bytes:
+    return port.to_bytes(2, "big")
+
+
+def parse_port(raw: bytes) -> int:
+    return int.from_bytes(raw, "big")
+
+
+def optional_hostname(dst: Endpoint, hostname: str | None) -> str | None:
+    """只有"确实是域名"时才透传（IP 字面量不算域名）。"""
+    if not hostname:
+        return None
+    if hostname == dst.addr:
+        return None
+    return hostname

proxycore/upstream/chain.py

@@ -0,0 +1,92 @@
+"""跳链（上游 A → 上游 B → 目标），逐跳认证。
+
+语义：
+* `chain: [B, C]` 表示"先连到 B，再由 B 连 C，最后由 C 连目标"；
+* 每一跳都用自己那套凭据完成握手（不共享认证状态）；
+* 链成环或跳数 > 8 在配置校验阶段（V3）就被拒绝，本模块只做执行。
+"""
+
+from __future__ import annotations
+
+import contextlib
+import socket
+from typing import Any
+
+from ..types import Endpoint
+from .base import BaseDialer, UpstreamDown
+from .http_connect import HttpConnectDialer
+from .socks4 import Socks4Dialer
+from .socks5 import Socks5Dialer
+
+_DIALERS: dict[str, type[BaseDialer]] = {
+    "socks5": Socks5Dialer,
+    "socks4": Socks4Dialer,
+    "http": HttpConnectDialer,
+    "https": HttpConnectDialer,
+}
+
+
+class ChainDialer(BaseDialer):
+    """把"最后一跳"的拨号替换为"逐跳建立隧道"。"""
+
+    def __init__(
+        self,
+        dialer: BaseDialer,
+        chain: list[str],
+        *,
+        timeout: float = 15.0,
+        resolver: Any = None,
+    ) -> None:
+        super().__init__(dialer.upstream, timeout=timeout)
+        self._tail = dialer
+        self._chain = list(chain)
+        self._resolver = resolver if resolver is not None else getattr(dialer, "resolve_alias", None)
+
+    def supports_udp(self) -> bool:
+        return False  # 链式 UDP 需要逐跳 ASSOCIATE，本期不做
+
+    def dial_tcp_sync(self, dst: Endpoint, hostname: str | None = None) -> socket.socket:
+        hops = self._resolve_hops()
+        if not hops:
+            return self._tail.dial_tcp_sync(dst, hostname)
+
+        # 逐跳：第一跳用自身 dialer，后续每跳用各自的 dialer 连"下一跳的地址"
+        first = hops[0]
+        sock = self._tail.dial_tcp_sync(
+            Endpoint(addr=first.host, port=first.port), hostname=None
+        )
+        try:
+            for hop in hops[1:]:
+                hop_dialer = self._make(hop)
+                # 在已建立的隧道之上，用下一跳的协议连它的地址
+                sock = hop_dialer.tunnel_over(sock, Endpoint(addr=hop.host, port=hop.port))
+            final = self._make(hops[-1]) if len(hops) > 1 else self._tail
+            return final.tunnel_over(sock, dst, hostname)
+        except BaseException:
+            # 不只 UpstreamError：`tunnel_over()` 里的 sendall/OSError 也要关掉，
+            # 否则半开的隧道会一直占着文件描述符。
+            _safe_close(sock)
+            raise
+
+    def _make(self, upstream: Any) -> BaseDialer:
+        cls = _DIALERS.get(str(getattr(upstream, "kind", "socks5")).lower())
+        if cls is None:
+            raise UpstreamDown(f"链式跳不支持的上游类型 {getattr(upstream, 'alias', '?')}")
+        return cls(upstream, timeout=self.timeout)
+
+    def _resolve_hops(self) -> list[Any]:
+        """把别名列表解析成 `Upstream` 对象（由上游工厂注入的解析器完成）。"""
+        if self._resolver is None:
+            raise UpstreamDown("链式代理缺少别名解析器（make_dialer 必须注入 resolver）")
+        hops = []
+        for alias in self._chain:
+            upstream = self._resolver(alias)
+            if upstream is None:
+                raise UpstreamDown(f"链式跳引用了未定义的上游 {alias!r}")
+            hops.append(upstream)
+        return hops
+
+
+def _safe_close(sock: socket.socket) -> None:
+    with contextlib.suppress(OSError):
+        sock.close()

proxycore/upstream/http_connect.py

@@ -0,0 +1,148 @@
+"""HTTP CONNECT 上游（含 Basic；NTLM 尚未实现，配置校验期拒绝）。
+
+NTLM 需要 407 挑战 + 多轮 SSPI，本仓库尚未接线。`auth: ntlm` 会在
+`Config.load()` 阶段被拒绝；下面的 `_sspi_ntlm_token()` 只是防御性兜底
+（手工构造 `Upstream` 时仍会明确抛 `UnsupportedAuth`，绝不假装成功）。
+
+本实现：
+* `auth: basic` → `Proxy-Authorization: Basic ...`；
+* `auth: ntlm` → `UnsupportedAuth`（配置加载期已拒绝）；
+* 任意非 200 响应 → 按状态码映射错误（407 → `AuthFailed`）。
+"""
+
+from __future__ import annotations
+
+import base64
+import contextlib
+import os
+import socket
+import threading
+from typing import Any
+
+from ..types import Endpoint
+from .base import AuthFailed, BaseDialer, TargetRefused, UnsupportedAuth, UpstreamDown, optional_hostname
+
+MAX_HEADER = 65536
+NTLM_SIGNATURE = b"NTLMSSP\x00"
+
+
+class HttpConnectDialer(BaseDialer):
+    kind = "http"
+    supports_udp_flag = False
+
+    def __init__(self, upstream: Any, *, timeout: float = 15.0, resolver: Any = None) -> None:
+        super().__init__(upstream, timeout=timeout)
+        self.resolve_alias = resolver
+        self._sspi_lock = threading.Lock()
+
+    # ------------------------------------------------------------ 认证 ----
+    def _auth_header(self, sock: socket.socket) -> bytes:
+        auth = str(getattr(self.upstream, "auth", "none") or "none").lower()
+        user = str(getattr(self.upstream, "user", "") or "")
+        password = str(getattr(self.upstream, "password", "") or "")
+        if auth == "basic" or (user and auth == "none"):
+            token = base64.b64encode(f"{user}:{password}".encode()).decode("ascii")
+            return f"Proxy-Authorization: Basic {token}\r\n".encode("ascii")
+        if auth == "ntlm":
+            return self._ntlm_auth(sock)
+        if auth == "unsupported":
+            raise UnsupportedAuth(f"上游 {self.alias}: 配置标注该认证方式不受支持")
+        return b""
+
+    def _ntlm_auth(self, sock: socket.socket) -> bytes:
+        if os.name != "nt":
+            raise UnsupportedAuth(
+                f"上游 {self.alias}: NTLM 仅支持 Windows（SSPI）；"
+                "非 Windows 请在配置里标注 ntlm=unsupported 并改用 basic"
+            )
+        with self._sspi_lock:
+            token = _sspi_ntlm_token(
+                str(getattr(self.upstream, "user", "") or ""),
+                str(getattr(self.upstream, "password", "") or ""),
+                str(getattr(self.upstream, "host", "") or ""),
+            )
+        return b"Proxy-Authorization: NTLM " + base64.b64encode(token) + b"\r\n"
+
+    # ------------------------------------------------------------ 隧道 ----
+    def tunnel_over(self, sock: socket.socket, dst: Endpoint, hostname: str | None = None) -> socket.socket:
+        address = optional_hostname(dst, hostname) or dst.addr
+        sock.settimeout(self.timeout)
+        self._send_connect(sock, address, dst.port)
+        return sock
+
+    def _send_connect(self, sock: socket.socket, host: str, port: int) -> None:
+        target = f"{host}:{port}"
+        try:
+            target.encode("ascii")
+        except UnicodeEncodeError:
+            raise UpstreamDown(f"非 ASCII 域名无法用于 HTTP CONNECT: {host}") from None
+        head = (
+            f"CONNECT {target} HTTP/1.1\r\n"
+            f"Host: {target}\r\n"
+            f"Proxy-Connection: Keep-Alive\r\n"
+        ).encode("ascii")
+        sock.sendall(head + self._auth_header(sock) + b"\r\n")
+        status, _headers = _read_response(sock)
+        if status == 200:
+            return
+        if status == 407:
+            raise AuthFailed(f"上游认证失败（HTTP 407）{target}")
+        if status in {403, 405, 502, 503}:
+            raise TargetRefused(f"目标不可达（经 HTTP 代理）{target}: HTTP {status}")
+        raise UpstreamDown(f"HTTP CONNECT 失败 {target}: HTTP {status}")
+
+    def dial_tcp_sync(self, dst: Endpoint, hostname: str | None = None) -> socket.socket:
+        remote = optional_hostname(dst, hostname) or dst.addr
+        sock = self._connect_upstream()
+        try:
+            self._send_connect(sock, remote, dst.port)
+        except BaseException:
+            with contextlib.suppress(OSError):
+                sock.close()
+            raise
+        sock.settimeout(None)
+        return sock
+
+
+def _read_response(sock: socket.socket) -> tuple[int, dict[str, str]]:
+    """读到空行为止；返回 `(status, headers)`。"""
+    buf = bytearray()
+    while b"\r\n\r\n" not in buf:
+        try:
+            chunk = sock.recv(4096)
+        except TimeoutError as exc:
+            raise UpstreamDown("读取 HTTP 代理响应超时") from exc
+        except OSError as exc:
+            raise UpstreamDown(f"读取 HTTP 代理响应失败: {exc}") from exc
+        if not chunk:
+            raise UpstreamDown("HTTP 代理在响应未完成时关闭连接")
+        buf.extend(chunk)
+        if len(buf) > MAX_HEADER:
+            raise UpstreamDown(f"HTTP 代理响应头超过 {MAX_HEADER} 字节")
+
+    head, _, _rest = bytes(buf).partition(b"\r\n\r\n")
+    lines = head.split(b"\r\n")
+    try:
+        parts = lines[0].split()
+        status = int(parts[1])
+    except (IndexError, ValueError) as exc:
+        raise UpstreamDown(f"HTTP 代理响应行非法: {lines[0]!r}") from exc
+    headers: dict[str, str] = {}
+    for line in lines[1:]:
+        key, _, value = line.partition(b":")
+        headers[key.decode("latin1").strip().lower()] = value.decode("latin1").strip()
+    return status, headers
+
+
+def _sspi_ntlm_token(user: str, password: str, target: str = "") -> bytes:
+    """Windows SSPI NTLM 类型 1 消息。
+
+    完整 NTLM 需要 `AcquireCredentialsHandle` + 多轮 `InitializeSecurityContext`；
+    在接线完成前，本函数按契约要求明确标注 unsupported（绝不假装成功）。
+    """
+    if os.name != "nt":  # pragma: no cover - 调用方已拦截
+        raise UnsupportedAuth("NTLM 需要 Windows SSPI")
+    raise UnsupportedAuth(
+        "NTLM 尚未接线：请在配置里使用 auth=basic，"
+        "或把该上游标注为 ntlm=unsupported"
+    )