procproxy 0.1.0__tar.gz → 0.1.2__tar.gz

{procproxy-0.1.0/src/procproxy.egg-info → procproxy-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: procproxy
-Version: 0.1.0
+Version: 0.1.2
 Summary: ProcProxy —— 进程级代理：按进程决定哪条连接走哪个上游代理
 Author: Longersking
 License-Expression: MIT
@@ -68,8 +68,26 @@ python procproxy.py doctor | rules | sessions | ...  # 子命令（等价于 pyt
 
 需要 **Python 3.10+**。
 
+### 从 PyPI 安装（推荐）
+
+```bash
+pip install procproxy
+procproxy init          # 生成 ~/.procproxy/config.yaml
+procproxy doctor        # 环境自检
+procproxy forward WeChat.exe --port 8848   # 真实转发（需管理员）
+```
+
+安装后直接运行 `procproxy` 会显示首次使用指引，不依赖任何样例文件。
+Python SDK 也一样：`start_proxy()` 不传配置即可启动（内置 `backend=null`），
+不需要先跑 `init`；`init` 只用于生成可编辑配置。
+
+非管理员：WinDivert 抓包必须管理员；可以用 `--backend null` 做转发链路联调，
+或在服务已启动、且配置了 `service.ipc_allow_group` 时读取状态。
+
+### 源码开发安装
+
 ```bash
-pip install -e .
+pip install -e ".[dev]"
 # 或者不装（零依赖方式，往 site-packages 写一个 .pth，让 python -m proxycore 全局可用）
 python procproxy.py install-path
 ```
@@ -77,7 +95,7 @@ python procproxy.py install-path
 数据面依赖（要用真抓包就必需）：
 
 ```bash
-pip install pydivert psutil
+pip install "procproxy[windivert]"
 ```
 
 > `pydivert` 自带**已签名**的 `WinDivert64.sys` —— 所以**不需要**开测试签名、不需要自己签驱动。
@@ -328,24 +346,151 @@ rules:                                      # 自上而下，**首个命中生
 
 ## 编程接口
 
+`proxycore.api` 是与 CLI 共用同一套配置、规则引擎和会话表的 SDK。
+完整教程见 [`docs/15-编程接口与SDK.md`](docs/15-编程接口与SDK.md)。
+
+### 30 秒：零配置启动
+
 ```python
-from proxycore import api
+from proxycore.api import start_proxy
 
-# 上下文管理器：退出自动停
-with api.start_proxy("samples/profiles/dev.yaml") as handle:
-    print(handle.status())
+with start_proxy() as ppx:          # 不需要任何配置文件
+    print(ppx.config_source)        # "packaged"
+    print(ppx.config_path)          # .../proxycore/data/default.yaml
+    print(ppx.status())             # 后端 / 规则 / 会话 / UDP / 配置来源
+```
+
+不传配置时的来源优先级：
 
-# 测试模式：sink 把所有连接转发到固定目标（不做抓包）
-with api.start_proxy("samples/profiles/dev.yaml", backend="null",
-                     sink_test_target="127.0.0.1:8080") as handle:
+| 优先级 | 来源 | 说明 |
+|---|---|---|
+| 1 | `start_proxy(path)` | 显式路径（也接受内存中的 `Config` 对象） |
+| 2 | `PROCPROXY_CONFIG` | 指向不存在文件会直接报错，不回退 |
+| 3 | `~/.procproxy/config.yaml` | `procproxy init` 生成的用户配置 |
+| 4 | 包内 `data/default.yaml` | `backend=null`，不抓包、不改道 |
+
+内置配置**不会**监听 sink，也**不会**创建任何文件。它适合装配、规则决策、
+状态查询和联调；要真实抓包请用 `backend="windivert"`（需管理员）或
+`procproxy init` 生成自己的配置。
+
+### 显式配置与测试转发
+
+```python
+from proxycore.api import start_proxy
+
+# 显式路径 + 真实抓包（需要管理员）
+with start_proxy(r"D:\cfg\procproxy.yaml", backend="windivert") as ppx:
+    print(ppx.sink)                 # sink 监听地址
+    print(ppx.sessions(limit=20))
+
+# 联调模式：backend=null + 把 sink 收到的连接固定转发到目标
+with start_proxy(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
+```
+
+### 在代码里构建配置
+
+可以从字典构造 `Config`，也可以先落盘再按路径加载：
 
-# 只要规则决策，不要监听
-runtime = api.make_runtime("samples/profiles/dev.yaml", backend="null")
+```python
+from proxycore.config import Config, atomic_write
+from proxycore.api import start_proxy
+
+doc = {
+    "version": 1,
+    "service": {"sink": {"host": "127.0.0.1", "port": 19080}, "backend": "null"},
+    "profile": {
+        "name": "myapp",
+        "default_action": "direct",
+        "dns_mode": "remote",
+        "rules": [
+            {"id": "r1", "action": "proxy", "upstream": "office",
+             "targets": "chrome.exe;msedge.exe", "dst_port": "443,80"},
+        ],
+    },
+    "upstreams": [
+        {"alias": "office", "kind": "socks5", "host": "127.0.0.1", "port": 1080},
+    ],
+}
+
+cfg = Config.from_dict(doc)
+cfg.validate()                       # from_dict 只解析，不校验
+atomic_write(cfg, "myconfig.yaml")   # 临时文件 → 校验 → 原子替换
+
+with start_proxy("myconfig.yaml") as ppx:
+    ...
+```
+
+> `Config.from_dict()` 不会解析 `password_ref`；需要凭据时请用
+> `Config.load()` / `start_proxy(path)`，或自己给 `upstream.password` 赋值。
+
+### 只做决策，不启动数据面
+
+```python
+from proxycore.api import make_runtime
+
+runtime = make_runtime()             # 默认用内置配置，backend=null
 decision = runtime.decide(conn_request)
+print(decision.action, decision.reason)
+```
+
+### 生命周期与句柄
+
+```python
+ppx = start_proxy()
+try:
+    print(ppx.status())
+finally:
+    ppx.stop()                       # 幂等；with 退出时也会自动调用
+```
+
+| 成员 | 说明 |
+|---|---|
+| `status()` | 后端、规则、会话、熔断、DNS、UDP、sink、`config_path`、`config_source` |
+| `sessions(limit=50)` / `active_sessions()` | 会话明细 / 活跃数 |
+| `reload(path="")` | 热重载；不传路径则重读当前文件。`sink.port`/`backend` 变更需重启 |
+| `decide(conn)` | 只问规则引擎，不抓包、不改道 |
+| `profile` | 当前生效的 `Profile` |
+| `config_path` / `config_source` | 当前配置的绝对路径与来源 |
+| `running` | 是否仍在运行 |
+
+`start_proxy()` 会启动后台维护线程；`run_forever()` 会阻塞到 Ctrl+C。
+请在主线程使用，并在退出时 `stop()`（或使用 `with`）。
+
+### 错误处理
+
+配置 / 后端 / 启动失败统一抛 `ProxyStartError`，`code` 是稳定的机器可读标识：
+
+```python
+from proxycore.api import ProxyStartError, start_proxy
+
+try:
+    start_proxy("missing.yaml")
+except ProxyStartError as exc:
+    print(exc.code)                  # config_not_found
 ```
 
-跑 `python tests/tools/api_demo.py` 看三种用法的完整演示。
+| code | 含义 |
+|---|---|
+| `config_not_found` | 配置文件不存在（显式路径 / 环境变量不会回退） |
+| `config_unreadable` | 文件存在但读不了（权限、目录等） |
+| `config_parse_invalid` | YAML 语法错误 / 根节点非映射 / 非 UTF-8 |
+| `config_version_unsupported` | `version != 1` |
+| `rule_upstream_missing` 等 | 规则或上游校验失败（完整列表见文档） |
+| `E_BACKEND_UNAVAILABLE` | 后端不可用（未知后端、WinDivert 不可加载等） |
+
+`api.load_config()` 同样抛 `ProxyStartError`，不是 `ConfigError`。
+
+### 环境变量
+
+| 变量 | 作用 |
+|---|---|
+| `PROCPROXY_CONFIG` | 配置文件路径；显式路径之后、用户配置之前生效 |
+| `PROCPROXY_RUNTIME_DIR` | 运行时状态/日志目录（CLI 与服务使用） |
+
+跑 `python tests/tools/api_demo.py` 看完整演示。
 
 ---
 
@@ -390,12 +535,13 @@ src/proxycore/          核心包
   ├── tunnel/           sink + relay（本地落地与双向转发）
   ├── upstream/         SOCKS5 / SOCKS4 / HTTP CONNECT / 跳链
   ├── dns/              DNS 三模式与 UDP
+  ├── config_source.py  配置来源解析（显式 / env / 用户 / 样例 / 内置）
   ├── forward.py        ← procproxy.py <进程名> 的实现
   ├── canproxy.py / checkroute.py / probe.py / pathsetup.py  ← 其余子命令
   └── service/ ipc.py   Windows 服务 + 命名管道
 samples/                mock 服务 + 示例配置
-docs/                   文档（00 架构与阅读路线 / 07 规则语义 / 11 排错 / 14 转发到抓包工具）
-tests/                  测试套件（555 passed）
+docs/                   文档（00 架构 / 07 规则 / 11 排错 / 14 抓包 / 15 SDK）
+tests/                  测试套件（619 passed / 4 skipped）
   └── tools/            验证脚本（run_demo / run_e2e / bench / …）
 ```
 
@@ -426,7 +572,7 @@ tests/                  测试套件（555 passed）
 
 ```bash
 pip install -e ".[dev]"
-python -m pytest -q tests/                     # 555 passed / 4 skipped（非管理员 Windows）
+python -m pytest -q tests/                     # 619 passed / 4 skipped（非管理员 Windows）
 python -m ruff check src tests
 python -m mypy src/proxycore
 ```

{procproxy-0.1.0 → procproxy-0.1.2}/README.md

@@ -29,8 +29,26 @@ python procproxy.py doctor | rules | sessions | ...  # 子命令（等价于 pyt
 
 需要 **Python 3.10+**。
 
+### 从 PyPI 安装（推荐）
+
+```bash
+pip install procproxy
+procproxy init          # 生成 ~/.procproxy/config.yaml
+procproxy doctor        # 环境自检
+procproxy forward WeChat.exe --port 8848   # 真实转发（需管理员）
+```
+
+安装后直接运行 `procproxy` 会显示首次使用指引，不依赖任何样例文件。
+Python SDK 也一样：`start_proxy()` 不传配置即可启动（内置 `backend=null`），
+不需要先跑 `init`；`init` 只用于生成可编辑配置。
+
+非管理员：WinDivert 抓包必须管理员；可以用 `--backend null` 做转发链路联调，
+或在服务已启动、且配置了 `service.ipc_allow_group` 时读取状态。
+
+### 源码开发安装
+
 ```bash
-pip install -e .
+pip install -e ".[dev]"
 # 或者不装（零依赖方式，往 site-packages 写一个 .pth，让 python -m proxycore 全局可用）
 python procproxy.py install-path
 ```
@@ -38,7 +56,7 @@ python procproxy.py install-path
 数据面依赖（要用真抓包就必需）：
 
 ```bash
-pip install pydivert psutil
+pip install "procproxy[windivert]"
 ```
 
 > `pydivert` 自带**已签名**的 `WinDivert64.sys` —— 所以**不需要**开测试签名、不需要自己签驱动。
@@ -289,24 +307,151 @@ rules:                                      # 自上而下，**首个命中生
 
 ## 编程接口
 
+`proxycore.api` 是与 CLI 共用同一套配置、规则引擎和会话表的 SDK。
+完整教程见 [`docs/15-编程接口与SDK.md`](docs/15-编程接口与SDK.md)。
+
+### 30 秒：零配置启动
+
 ```python
-from proxycore import api
+from proxycore.api import start_proxy
 
-# 上下文管理器：退出自动停
-with api.start_proxy("samples/profiles/dev.yaml") as handle:
-    print(handle.status())
+with start_proxy() as ppx:          # 不需要任何配置文件
+    print(ppx.config_source)        # "packaged"
+    print(ppx.config_path)          # .../proxycore/data/default.yaml
+    print(ppx.status())             # 后端 / 规则 / 会话 / UDP / 配置来源
+```
+
+不传配置时的来源优先级：
 
-# 测试模式：sink 把所有连接转发到固定目标（不做抓包）
-with api.start_proxy("samples/profiles/dev.yaml", backend="null",
-                     sink_test_target="127.0.0.1:8080") as handle:
+| 优先级 | 来源 | 说明 |
+|---|---|---|
+| 1 | `start_proxy(path)` | 显式路径（也接受内存中的 `Config` 对象） |
+| 2 | `PROCPROXY_CONFIG` | 指向不存在文件会直接报错，不回退 |
+| 3 | `~/.procproxy/config.yaml` | `procproxy init` 生成的用户配置 |
+| 4 | 包内 `data/default.yaml` | `backend=null`，不抓包、不改道 |
+
+内置配置**不会**监听 sink，也**不会**创建任何文件。它适合装配、规则决策、
+状态查询和联调；要真实抓包请用 `backend="windivert"`（需管理员）或
+`procproxy init` 生成自己的配置。
+
+### 显式配置与测试转发
+
+```python
+from proxycore.api import start_proxy
+
+# 显式路径 + 真实抓包（需要管理员）
+with start_proxy(r"D:\cfg\procproxy.yaml", backend="windivert") as ppx:
+    print(ppx.sink)                 # sink 监听地址
+    print(ppx.sessions(limit=20))
+
+# 联调模式：backend=null + 把 sink 收到的连接固定转发到目标
+with start_proxy(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
+```
+
+### 在代码里构建配置
+
+可以从字典构造 `Config`，也可以先落盘再按路径加载：
 
-# 只要规则决策，不要监听
-runtime = api.make_runtime("samples/profiles/dev.yaml", backend="null")
+```python
+from proxycore.config import Config, atomic_write
+from proxycore.api import start_proxy
+
+doc = {
+    "version": 1,
+    "service": {"sink": {"host": "127.0.0.1", "port": 19080}, "backend": "null"},
+    "profile": {
+        "name": "myapp",
+        "default_action": "direct",
+        "dns_mode": "remote",
+        "rules": [
+            {"id": "r1", "action": "proxy", "upstream": "office",
+             "targets": "chrome.exe;msedge.exe", "dst_port": "443,80"},
+        ],
+    },
+    "upstreams": [
+        {"alias": "office", "kind": "socks5", "host": "127.0.0.1", "port": 1080},
+    ],
+}
+
+cfg = Config.from_dict(doc)
+cfg.validate()                       # from_dict 只解析，不校验
+atomic_write(cfg, "myconfig.yaml")   # 临时文件 → 校验 → 原子替换
+
+with start_proxy("myconfig.yaml") as ppx:
+    ...
+```
+
+> `Config.from_dict()` 不会解析 `password_ref`；需要凭据时请用
+> `Config.load()` / `start_proxy(path)`，或自己给 `upstream.password` 赋值。
+
+### 只做决策，不启动数据面
+
+```python
+from proxycore.api import make_runtime
+
+runtime = make_runtime()             # 默认用内置配置，backend=null
 decision = runtime.decide(conn_request)
+print(decision.action, decision.reason)
+```
+
+### 生命周期与句柄
+
+```python
+ppx = start_proxy()
+try:
+    print(ppx.status())
+finally:
+    ppx.stop()                       # 幂等；with 退出时也会自动调用
+```
+
+| 成员 | 说明 |
+|---|---|
+| `status()` | 后端、规则、会话、熔断、DNS、UDP、sink、`config_path`、`config_source` |
+| `sessions(limit=50)` / `active_sessions()` | 会话明细 / 活跃数 |
+| `reload(path="")` | 热重载；不传路径则重读当前文件。`sink.port`/`backend` 变更需重启 |
+| `decide(conn)` | 只问规则引擎，不抓包、不改道 |
+| `profile` | 当前生效的 `Profile` |
+| `config_path` / `config_source` | 当前配置的绝对路径与来源 |
+| `running` | 是否仍在运行 |
+
+`start_proxy()` 会启动后台维护线程；`run_forever()` 会阻塞到 Ctrl+C。
+请在主线程使用，并在退出时 `stop()`（或使用 `with`）。
+
+### 错误处理
+
+配置 / 后端 / 启动失败统一抛 `ProxyStartError`，`code` 是稳定的机器可读标识：
+
+```python
+from proxycore.api import ProxyStartError, start_proxy
+
+try:
+    start_proxy("missing.yaml")
+except ProxyStartError as exc:
+    print(exc.code)                  # config_not_found
 ```
 
-跑 `python tests/tools/api_demo.py` 看三种用法的完整演示。
+| code | 含义 |
+|---|---|
+| `config_not_found` | 配置文件不存在（显式路径 / 环境变量不会回退） |
+| `config_unreadable` | 文件存在但读不了（权限、目录等） |
+| `config_parse_invalid` | YAML 语法错误 / 根节点非映射 / 非 UTF-8 |
+| `config_version_unsupported` | `version != 1` |
+| `rule_upstream_missing` 等 | 规则或上游校验失败（完整列表见文档） |
+| `E_BACKEND_UNAVAILABLE` | 后端不可用（未知后端、WinDivert 不可加载等） |
+
+`api.load_config()` 同样抛 `ProxyStartError`，不是 `ConfigError`。
+
+### 环境变量
+
+| 变量 | 作用 |
+|---|---|
+| `PROCPROXY_CONFIG` | 配置文件路径；显式路径之后、用户配置之前生效 |
+| `PROCPROXY_RUNTIME_DIR` | 运行时状态/日志目录（CLI 与服务使用） |
+
+跑 `python tests/tools/api_demo.py` 看完整演示。
 
 ---
 
@@ -351,12 +496,13 @@ src/proxycore/          核心包
   ├── tunnel/           sink + relay（本地落地与双向转发）
   ├── upstream/         SOCKS5 / SOCKS4 / HTTP CONNECT / 跳链
   ├── dns/              DNS 三模式与 UDP
+  ├── config_source.py  配置来源解析（显式 / env / 用户 / 样例 / 内置）
   ├── forward.py        ← procproxy.py <进程名> 的实现
   ├── canproxy.py / checkroute.py / probe.py / pathsetup.py  ← 其余子命令
   └── service/ ipc.py   Windows 服务 + 命名管道
 samples/                mock 服务 + 示例配置
-docs/                   文档（00 架构与阅读路线 / 07 规则语义 / 11 排错 / 14 转发到抓包工具）
-tests/                  测试套件（555 passed）
+docs/                   文档（00 架构 / 07 规则 / 11 排错 / 14 抓包 / 15 SDK）
+tests/                  测试套件（619 passed / 4 skipped）
   └── tools/            验证脚本（run_demo / run_e2e / bench / …）
 ```
 
@@ -387,7 +533,7 @@ tests/                  测试套件（555 passed）
 
 ```bash
 pip install -e ".[dev]"
-python -m pytest -q tests/                     # 555 passed / 4 skipped（非管理员 Windows）
+python -m pytest -q tests/                     # 619 passed / 4 skipped（非管理员 Windows）
 python -m ruff check src tests
 python -m mypy src/proxycore
 ```

{procproxy-0.1.0 → procproxy-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "procproxy"
-version = "0.1.0"
+version = "0.1.2"
 description = "ProcProxy —— 进程级代理：按进程决定哪条连接走哪个上游代理"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -51,6 +51,9 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+"proxycore" = ["data/*.yaml"]
+
 # ---------------------------------------------------------------- pytest ----
 [tool.pytest.ini_options]
 minversion = "7.4"