diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
new file mode 100644
index 0000000..990e2c1
--- /dev/null
+++ b/.github/workflows/test.yml
@@ -0,0 +1,24 @@
+name: Tests
+
+on:
+ pull_request:
+ push:
+ branches: [main]
+
+permissions:
+ contents: read
+
+jobs:
+ test:
+ runs-on: windows-2025
+ timeout-minutes: 30
+ steps:
+ - uses: actions/checkout@v7
+ - uses: dtolnay/rust-toolchain@stable
+ - uses: ilammy/msvc-dev-cmd@v1
+ with:
+ arch: x64
+ - name: Build default features
+ run: cargo build --locked --all-targets
+ - name: Unit tests
+ run: cargo test --locked --all-features --all-targets
diff --git a/AGENTS.md b/AGENTS.md
index b31b22d..1ac348c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
# Project Overview
-VCore is a standalone Rust proxy core. The current public contract is Invoke API v5 with internal schema revision 12. Runtime configuration uses the strict schema documented in `docs/config.yaml` and is passed inline as `configYaml` / `configYamls`; YAML contains neither `configVersion` nor `default-proxy`. Public lifecycle state is runtime-local and single-instance.
+VCore is a standalone Rust proxy core. The current public contract is Invoke API v5 with internal schema revision 13. Runtime configuration uses the strict schema documented in `docs/config.yaml` and is passed inline as `configYaml` / `configYamls`; YAML contains neither `configVersion` nor `default-proxy`. Public lifecycle state is runtime-local and single-instance.
Apple and Android use host-owned TUN fds through the Unix `rust-tun` adapter. Windows uses `windows-rs` / `Windows.Networking.Vpn`; the packaged ARM64 foreground, AppContainer provider, per-session full-trust runtime, lifecycle, pressure, and packet-channel gates pass on Windows 11. Windows 10, native x64, physical IPv6, WACK, and Store publishing remain release gates. Linux remains unsupported.
@@ -11,9 +11,9 @@ Current source, tests, and the public contract documents under `docs/` define im
Read the relevant document completely before changing that area:
- FFI, lifecycle, Android protect, or config delivery: `docs/invoke-api.md` and `src/ffi/`.
-- YAML, proxy graph, DNS, rules, or sniffer: `docs/config.yaml`, `docs/tun-icmp-dns.md`, and `src/config/`.
+- YAML, proxy graph, proxy groups, DNS, rules, or sniffer: `docs/config.yaml`, `docs/tun-icmp-dns.md`, and `src/config/`.
- AnyTLS: `docs/anytls.md`.
-- TUN traffic metrics: `docs/controller-api.md`.
+- Runtime Controller, proxy-group selection, or TUN traffic metrics: `docs/controller-api.md` and `src/controller.rs`.
- GeoData: `docs/geodata.md`.
- REALITY or the GitHub rustls fork: `docs/reality-wire-protocol.md` and `docs/rustls-reality-release.md`.
- Unix TUN fd ownership or packet I/O: `docs/tun-platform.md`.
@@ -28,6 +28,7 @@ Read the relevant document completely before changing that area:
- `src/tun_runtime.rs` connects platform raw-IP I/O to `vcore-netstack` and dispatches TCP, UDP, DNS, ICMP, and sniffing.
- `src/platform/` contains platform adapters. Keep Windows callback semantics here instead of simulating a Unix fd.
- `src/dialer.rs` is the shared physical TCP/UDP socket seam. Fix socket protection or Windows `(source IP, interface index)` binding once here rather than in each outbound.
+- Static `select` proxy groups are mutable Running Session route targets at the routing `Dispatcher` seam. Keep `dialer-proxy` and `measureDelay` node-only, and do not move group selection into the immutable outbound connector graph.
- `crates/vcore-netstack` is platform-independent raw-IP state and must not depend on WinRT, JNI, Swift, or host UI frameworks.
- Core runtime lifecycle does not infer App, extension, service, or daemon roles and does not implement cross-process state or IPC. The Windows-only host Invoke is the explicit package integration seam for profile/status/Session Snapshot/StartupTask operations and an optional bounded `sessionBackend`; its Session Host owns backend process liveness without interpreting arguments, files, ports, or protocols. Provider runtime state remains process-local.
diff --git a/CONTEXT.md b/CONTEXT.md
index d21066b..1c752e0 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -13,8 +13,8 @@ The VCore runtime serving one active Windows tunnel session inside the Windows s
_Avoid_: Foreground runtime, provider runtime, external core
**Windows session host**:
-The hidden packaged full-trust Application that owns one Windows session runtime and its optional Windows session backend independently of the foreground host.
-_Avoid_: Foreground process, provider host, external-core host
+The packaged full-trust process registered under the product's single Application that owns one Windows session runtime and its optional Windows session backend independently of the foreground host.
+_Avoid_: Helper Application, foreground process, provider host, external-core host
**Windows session backend**:
The optional ordered set of package-local processes whose lifetime is owned by one Windows session host. VCore supervises process liveness but does not interpret their arguments, files, ports, or protocols.
@@ -51,3 +51,19 @@ _Avoid_: Proxy traffic, transport traffic, per-node traffic
**Local SOCKS5 outbound**:
A normal VCore SOCKS5 outbound to a loopback server. The server may be managed outside VCore or happen to run in a Windows session backend; SOCKS5 readiness and protocol health remain outside the backend contract.
_Avoid_: Managed core, child core, URI configuration
+
+**Proxy node**:
+A named, concrete outbound protocol path that can be selected as a route target or referenced by another proxy node through `dialer-proxy`.
+_Avoid_: Proxy when a proxy group or route target is intended, server profile
+
+**Proxy group**:
+A named route target whose current group selection identifies one direct member route target.
+_Avoid_: Folder, provider, subscription
+
+**Route target**:
+A proxy node, proxy group, or reserved built-in target that routing rules, the final `MATCH`, and DNS routes can select.
+_Avoid_: Proxy when the distinction between a node and group matters, dialer
+
+**Group selection**:
+The running-session state identifying the direct member route target currently chosen by a proxy group.
+_Avoid_: Variant, configuration switch, active profile
diff --git a/Cargo.toml b/Cargo.toml
index 14c5db9..f072eca 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -102,7 +102,6 @@ windows = { version = "=0.62.2", optional = true, features = [
"Win32_Networking_WinSock",
"Win32_Security",
"Win32_Security_Isolation",
- "Win32_System_Com",
"Win32_System_JobObjects",
"Win32_System_RemoteDesktop",
"Win32_System_Threading",
diff --git a/README.md b/README.md
index cdf4170..0888ae6 100644
--- a/README.md
+++ b/README.md
@@ -4,12 +4,13 @@
English · 简体中文 · Русский
-VCore is a standalone, host-agnostic Rust client proxy core. It provides proxy graphs, DNS, routing rules, GeoData, an HTTP listener, a TUN data plane, and traffic statistics through strict YAML configuration and Invoke API v5. The internal configuration schema revision is 12; the revision appears only in the `version` response and `buildIdentity`, not in YAML.
+VCore is a standalone, host-agnostic Rust client proxy core. It provides proxy graphs, static `select` proxy groups, DNS, routing rules, GeoData, an HTTP listener, a TUN data plane, and a loopback Controller through strict YAML configuration and Invoke API v5. The internal configuration schema revision is 13; the revision appears only in the `version` response and `buildIdentity`, not in YAML.
## Features
- Outbounds: VLESS + XHTTP + TLS/REALITY, SOCKS5 CONNECT/UDP ASSOCIATE, AnyTLS TCP/UoT, and DIRECT.
- Proxy chains: `dialer-proxy` forms a directed acyclic graph of arbitrary length. If node A points to B, the physical path is `client -> B -> A -> target`.
+- Proxy groups: static `select` groups keep ordered members, including concrete nodes, nested groups, `DIRECT`, and `REJECT`; their current-session selection can be changed live through the Controller. `dialer-proxy` remains node-only.
- Routing: ordered `DOMAIN`, `DOMAIN-SUFFIX`, `DOMAIN-KEYWORD`, `GEOSITE`, `GEOIP`, `IP-CIDR`, `IP-CIDR6`, `DST-PORT`, `NETWORK`, and final `MATCH` rules.
- DNS: fixed-IP UDP/TCP nameservers, explicit outbounds, ordered policy/failover, typed and opaque caches, singleflight, and TUN UDP/TCP port 53 interception.
- TUN: raw IPv4/IPv6, TCP/UDP, local ICMPv4/ICMPv6 Echo replies, HTTP/TLS/QUIC sniffing, and four per-session traffic counters.
@@ -23,9 +24,10 @@ VCore is a standalone, host-agnostic Rust client proxy core. It provides proxy g
- YAML is limited to 256 KiB and rejects unknown fields, anchors, aliases, custom tags, and obsolete structures.
- The top level must contain at least one proxy and either `port` or an enabled `tun`.
-- Proxy `name` values are case-sensitive and unique; every reference must exist, and the proxy graph must be acyclic.
-- `rules` is required and must end with exactly one `MATCH` targeting a real proxy name.
-- `DIRECT` and `REJECT` are built-in actions; every other action must be a real proxy name.
+- Proxy and group definition names share one exact, case-sensitive namespace. Names are 1–64 UTF-8 bytes, reject surrounding Unicode whitespace, controls, `, # / ? & = % \`, `.` and `..`, and reserve `DIRECT`, `REJECT`, and `RULES`; internal ordinary spaces, CJK, and emoji are allowed.
+- `proxy-groups` accepts only `select`. Member order and duplicates are preserved; an omitted `default-selected` selects the first member, while an explicit value must name a direct member. Proxy chains and nested groups must each be acyclic.
+- `rules` is required and must end with exactly one `MATCH` targeting a configured proxy node or proxy group.
+- `DIRECT` and `REJECT` are built-in actions and group members; every other route target must be a configured proxy node or proxy group. DNS alone also reserves `RULES`.
- Configuration is delivered inline through `configYaml` / `configYamls`; VCore does not read host configuration paths.
- Runtime values such as the Controller, TUN fd, Controller port, and secret are generated by the host and are not stored in user RAW YAML.
@@ -57,14 +59,18 @@ initialize
`instanceId` is a generation token that is never reused by the current runtime. Commands for the same instance fail fast when another command is active; pure `validateConfig` calls may run concurrently. See [`docs/invoke-api.md`](docs/invoke-api.md) for the complete envelope, methods, fd ownership, and Android protect contract.
-TUN traffic is queried through a session-local loopback Controller:
+Runtime state is exposed through a session-local loopback Controller:
```http
GET /traffic
+GET /group
+GET /group/{name}
+GET /proxies/{name}
+PUT /proxies/{name}
Authorization: Bearer
```
-The response is a one-time `up/down/upTotal/downTotal` snapshot, not a continuous stream. See [`docs/controller-api.md`](docs/controller-api.md).
+`GET /traffic` is a one-time `up/down/upTotal/downTotal` TUN snapshot. The group endpoints expose and change the selected direct member of static `select` groups; a successful change affects only new physical TCP, UDP, and DNS transports in the current session. It does not migrate existing connections, UDP associations, DNS state, or pooled TCP transports, and it never performs automatic failover. A Controller that manages groups requires one Bearer secret for all routes and may run without TUN. See [`docs/controller-api.md`](docs/controller-api.md).
## Platforms
@@ -103,7 +109,7 @@ TCP sessions, ordinary UDP associations, half-open connections, outbound handsha
- [AnyTLS outbound](docs/anytls.md)
- [REALITY V1 client protocol](docs/reality-wire-protocol.md)
- [rustls REALITY dependency and release requirements](docs/rustls-reality-release.md)
-- [TUN traffic Controller](docs/controller-api.md)
+- [Runtime Controller](docs/controller-api.md)
- [TUN ICMP and DNS](docs/tun-icmp-dns.md)
- [GeoData rules and assets](docs/geodata.md)
- [TUN platform layer](docs/tun-platform.md)
diff --git a/docs/README.md b/docs/README.md
index 48bc21e..d809a4d 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,12 +4,12 @@
## 公共契约
-1. [配置协议](config.yaml)：配置修订版 12 的完整 YAML 示例和严格字段边界。
+1. [配置协议](config.yaml)：配置修订版 13 的完整 YAML 示例、静态 `select` 代理组和严格字段边界。
2. [Invoke API](invoke-api.md)：API v5 的请求格式、生命周期和平台回调。
3. [AnyTLS 出站](anytls.md)：TLS、会话复用、填充、TCP/UoT 和清理语义。
4. [REALITY V1 协议](reality-wire-protocol.md)：握手、认证、连接状态和失败边界。
-5. [TUN 流量 Controller](controller-api.md)：Bearer 鉴权和四字段流量快照。
-6. [DNS 与 ICMP](tun-icmp-dns.md)：TUN DNS、缓存、故障转移和本地 Echo Reply。
+5. [运行时 Controller](controller-api.md)：Bearer 鉴权、实时代理组选择和四字段 TUN 流量快照。
+6. [DNS 与 ICMP](tun-icmp-dns.md)：TUN DNS、代理组出口、缓存、故障转移和本地 Echo Reply。
7. [GeoData](geodata.md)：规则、资产更新、匹配器和资源上限。
8. [TUN 平台层](tun-platform.md)：文件描述符、原始 IP 包和平台所有权。
diff --git a/docs/acceptance.md b/docs/acceptance.md
index 8a3b3a9..68807bf 100644
--- a/docs/acceptance.md
+++ b/docs/acceptance.md
@@ -18,14 +18,14 @@
当前测试覆盖以下公共边界：
- Invoke API v5 envelope、严格 payload、单实例生命周期、panic 隔离和同步清理；
-- 配置修订版 12、IPv6 总开关、代理图、节点测速配置和未知字段拒绝；
+- 配置修订版 13、IPv6 总开关、代理图、静态 `select` 代理组、节点测速配置和未知字段拒绝；
- VLESS/XHTTP/TLS/REALITY、SOCKS5、AnyTLS 和代理链；
- DNS wire、缓存、singleflight、policy、故障转移和 TCP 复用；
- 规则、GeoData、HTTP/TLS/QUIC 嗅探；
- ICMPv4/ICMPv6 Echo、校验和、分片、MTU 和队列满；
- Apple/Android TUN 帧格式、文件描述符副本和关闭所有权；
-- Windows 控制/数据协议、Session Snapshot v2、会合记录、包队列、批量写入、物理网络绑定和 Job Object 多进程监督；
-- Controller 鉴权、速率和累计流量语义。
+- Windows 单 Application manifest、Provider/Session Host token 绑定、控制/数据协议、Session Snapshot v2、会合记录、包队列、批量写入、物理网络绑定和 Job Object 多进程监督；
+- Controller 鉴权、速率和累计流量语义，以及代理组查询、实时选择和有界请求处理。
常用命令：
@@ -70,6 +70,7 @@ Windows 11 ARM64 开发验收的环境、命令、结果和适用范围保存在
| DNS / rules / GeoData / sniffer | 已覆盖 | 本地 DNS 与代理 fixture | Windows ARM64 已覆盖 |
| ICMPv4 / ICMPv6 Echo | 已覆盖 | 不适用 | Windows ARM64 已覆盖 |
| Controller 四字段流量 | 已覆盖 | HTTP fixture | Windows ARM64 已覆盖 |
+| Controller `select` 代理组控制 | 已覆盖 | HTTP fixture | 物理设备未验证 |
“本地互操作”只证明当前双方在受控配置下可以通信，不代表所有公网服务或配置组合。
@@ -93,7 +94,20 @@ Windows 11 ARM64 开发验收的环境、命令、结果和适用范围保存在
## Windows VPN
-已验证范围限于 Windows 11 ARM64 开发签名安装包：
+单 Application 可行性在当前 Windows 11 ARM64 build 26200.9278 机器的 Developer Mode loose-package spike 上验证。该 spike 以 `042919ab5ead6af719ae68564244966e95003b58` 为基线，并包含后来收敛为 `d9018a2dfb75ab1f55c593023cbaa60951165eb5` 的未提交目标改动；基线 SHA 本身不能复现该结果。实际执行路径为：
+
+```powershell
+Add-AppxPackage -Register \AppxManifest.xml
+vcore-uwp-demo.exe environment
+vcore-uwp-demo.exe status
+vcore-uwp-demo.exe start
+vcore-uwp-demo.exe status
+vcore-uwp-demo.exe stop
+```
+
+观察结果是 manifest 只有一个 Application，Provider 是 AppContainer，Provider 通过无参数 `FullTrustProcessLauncher` 启动具有同一 package identity 的 medium-integrity Session Host，connect/stop 与 rendezvous 清理通过。该记录只证明本机可行性，不作为其他系统、架构、签名包、WACK 或 Store 的验证结论。
+
+此前 Windows 11 ARM64 开发签名包的数据面证据覆盖：
- `Windows.Networking.Vpn` Provider 激活；
- 完全信任前台宿主、AppContainer Provider 和完全信任 Session Host 的进程边界；
@@ -103,13 +117,13 @@ Windows 11 ARM64 开发验收的环境、命令、结果和适用范围保存在
- 非回环 socket 的物理源地址与接口索引绑定；
- Controller、外部回环 SOCKS5 和前台宿主退出后的会话延续；
- Provider/Session Host 退出、管道错误和网络变化时的失败关闭；
-- 快速重连、持续压力、零队列丢弃和显式 Stop 清理；
-- 断开状态下的安装包原位升级和签名校验。
+- 快速重连、持续压力、零队列丢弃和显式 Stop 清理。
Windows 路由必须保留两条 `/1`。在安装包环境中，单条 VPN `/0` 会使按产品要求绑定物理源地址和接口的外层 socket 返回 `WSAENETUNREACH`；两条 `/1` 不会产生该问题。
-尚未验证或完成：
+以下项目由发布开发者在对应机器或服务中验证，不阻塞上述本机可行性结论：
+- 单 Application test-signed MSIX 安装；
- Windows 10 20H2；
- 原生 x64 Windows；
- 真实物理 IPv6；
diff --git a/docs/adr/0003-run-windows-runtime-in-a-full-trust-session-host.md b/docs/adr/0003-run-windows-runtime-in-a-full-trust-session-host.md
index e052264..cebc736 100644
--- a/docs/adr/0003-run-windows-runtime-in-a-full-trust-session-host.md
+++ b/docs/adr/0003-run-windows-runtime-in-a-full-trust-session-host.md
@@ -1,5 +1,5 @@
---
-status: accepted
+status: superseded by ADR-0007
---
# ADR 0003：在完全信任的 Session Host 中运行 Windows 会话
diff --git a/docs/adr/0005-model-select-proxy-groups-as-session-route-targets.md b/docs/adr/0005-model-select-proxy-groups-as-session-route-targets.md
new file mode 100644
index 0000000..b52000b
--- /dev/null
+++ b/docs/adr/0005-model-select-proxy-groups-as-session-route-targets.md
@@ -0,0 +1,11 @@
+---
+status: accepted
+---
+
+# ADR 0005：将 select 代理组建模为会话路由目标
+
+VCore 把首版 `select` 代理组建模为位于不可变代理节点与 `dialer-proxy` 图之上的命名路由目标。组拥有一个有序、非空的直接成员列表，成员可以是代理节点、嵌套 `select` 组、`DIRECT` 或 `REJECT`；省略 `default-selected` 时选择第一项，显式值必须精确命中一个直接成员。普通规则、最终 `MATCH` 和 DNS 路由可以引用组，`dialer-proxy` 与 `measureDelay` 仍然只接受代理节点。
+
+组选择只属于当前 VCore 运行会话，由调用方在下一次配置中重新提供。每次 `connect_tcp` 或 `open_datagram` 进入组时只读取一次选择；成功切换只影响提交后才进入组的新调用，不迁移已有 TCP、不替换已有 UDP transport，也不清理 DNS cache 或已有 DNS TCP connection。已经读取旧选择但仍在建链的调用继续使用旧成员；被选成员失败时原样返回错误，不在组内隐式 failover。
+
+代理组位于 `Dispatcher` seam，具体协议节点及其 `dialer-proxy` graph 继续由 `OutboundConnector` 实现。这个边界避免让运行时选择渗入协议建链，并使“组不能作为 `dialer-proxy`”成为明确、可验证的约束。
diff --git a/docs/adr/0006-control-live-proxy-group-selection-through-controller.md b/docs/adr/0006-control-live-proxy-group-selection-through-controller.md
new file mode 100644
index 0000000..8fd361a
--- /dev/null
+++ b/docs/adr/0006-control-live-proxy-group-selection-through-controller.md
@@ -0,0 +1,11 @@
+---
+status: accepted
+---
+
+# ADR 0006：只通过 Controller 控制代理组的实时选择
+
+VCore 首版只通过 Controller 暴露代理组的实时选择，不新增 Invoke 方法，也不扩展 Windows 控制管道。Controller 采用 mihomo `select` 的核心调用形状：`GET /group`、`GET /group/{name}`、`GET /proxies/{name}` 和 `PUT /proxies/{name}`；PUT body 为 `{"name":"member"}`，成功返回空的 `204`。组状态只承诺 `name`、`type`、`all`、`now`，不宣称兼容完整 mihomo Dashboard API。
+
+Windows 的实际运行时位于独立 Session Host，Apple 与 Android 的运行时位于 Invoke owner 背后；Controller 是现有平台中唯一能统一到达实际运行会话的 Adapter。组路由可以在无 TUN 的本地代理运行时中使用，`/traffic` 仍只在存在 TUN 统计时提供。
+
+配置同时包含代理组和 Controller 时，必须为整个 Controller 配置 Bearer secret。请求使用精确名称和严格、有界的 JSON，任何失败都不得改变选择。没有 Controller 的代理组配置仍然有效，但本次会话中没有公开的实时切换入口；调用方在成功切换后自行持久化下一次启动所需的 `default-selected`，持久化失败不回滚已经成功的运行时选择。
diff --git a/docs/adr/0007-activate-windows-session-host-from-vpn-provider.md b/docs/adr/0007-activate-windows-session-host-from-vpn-provider.md
new file mode 100644
index 0000000..873344e
--- /dev/null
+++ b/docs/adr/0007-activate-windows-session-host-from-vpn-provider.md
@@ -0,0 +1,7 @@
+---
+status: accepted
+---
+
+# Activate the Windows Session Host from the VPN Provider
+
+A package has one Application but keeps separate full-trust foreground, AppContainer Provider, and full-trust Session Host processes. The Provider launches the Session Host through parameterless `FullTrustProcessLauncher`; the rendezvous token remains untrusted until the Provider binds it to the profile token during the existing handshake, preserving Windows 10 support without another protocol or compatibility path.
diff --git a/docs/config.yaml b/docs/config.yaml
index 7b2aeac..76680aa 100644
--- a/docs/config.yaml
+++ b/docs/config.yaml
@@ -1,6 +1,6 @@
-# VCore 配置修订版 12 的完整示例。
+# VCore 配置修订版 13 的完整示例。
#
-# `version.configVersion` 返回的 12 是二进制报告值，不是 YAML 字段。配置只接受
+# `version.configVersion` 返回的 13 是二进制报告值，不是 YAML 字段。配置只接受
# 本文列出的结构；未知字段、anchor、alias 和自定义 tag 都会失败。
#
# 宿主先通过 Invoke API v5 调用 initialize({dataDir})，再通过 configYaml 内联
@@ -14,7 +14,8 @@ ipv6: true
# GeoData 下载配置可省略；出现时三项必须齐全。URL 必须是以域名为主机、无
# userinfo/fragment 的绝对 HTTPS URL，更新周期固定为 24 小时。validateConfig 和
# measureDelay 不下载。公共实例启动后，只有实际规则需要资产且自动更新已启用时
-# 才后台检查。下载使用最终 MATCH 选中的完整代理链，不回退 DIRECT。
+# 才后台检查。下载使用最终 MATCH route target 在创建新物理 transport 时解析到的
+# 当前节点、DIRECT 或 REJECT；代理组不自动故障转移，也不回退 DIRECT。
geox-url:
geoip: https://assets.example.com/geoip.dat
geosite: https://assets.example.com/geosite.dat
@@ -28,9 +29,12 @@ port: 1080
authentication:
- "probe-user:probe-password"
-# 可选的 TUN 流量 Controller。只允许配合 tun.enable: true 使用，地址必须是
-# 回环地址。secret 省略时不鉴权，出现时必须非空。只支持 `GET /traffic` 返回
-# 一次 up/down/upTotal/downTotal 快照；它不属于 Invoke API。
+# 可选的运行时 Controller，地址必须是回环 IP 和显式非零端口。它可服务于启用
+# TUN 的配置或含 proxy-groups 的配置；整个运行配置仍必须包含 port 或启用 TUN。
+# 只要 Controller 管理 proxy-groups，secret 就必填；仅有 TUN 流量接口时可省略。
+# secret 出现时必须为 1–255 UTF-8 字节，并作为全部 Controller 路由的 Bearer token。
+# Controller 提供 GET /traffic、GET /group、GET /group/{name}、
+# GET /proxies/{name} 和 PUT /proxies/{name}，不属于 Invoke API。
external-controller: 127.0.0.1:9090
secret: "vcore-runtime-secret"
@@ -54,10 +58,15 @@ sniffer:
QUIC:
ports: [443, 8443]
-# 至少配置一个平铺代理。name 大小写敏感且必须唯一；dialer-proxy 必须引用另一个
-# 实际 name。未知引用、自引用和环都会失败。代理数量和链深没有独立上限，仍受
-# YAML 256 KiB、名称唯一和全图无环约束。物理首跳需要连接本机服务时，server 必须
-# 显式使用 127.0.0.0/8 范围内的 IPv4 字面量或 ::1；域名解析到回环地址会失败关闭。
+# 至少配置一个具体代理节点。节点和代理组定义名共享同一大小写敏感的命名空间，
+# 引用精确匹配且不做 Unicode normalization 或大小写折叠。名称必须为 1–64 UTF-8
+# 字节，首尾不能是任何 Unicode 空白字符，不能含控制字符，也不能包含逗号、井号、
+# 斜杠、问号、`&`、`=`、`%`、反斜杠，或使用 `.`、`..`、`DIRECT`、`REJECT`、
+# `RULES`；内部普通空格、CJK 和 emoji 可用。dialer-proxy 必须引用另一个具体节点，
+# 不能引用代理组。未知引用、自引用和环都会失败。代理数量和链深没有独立上限，
+# 仍受 YAML 256 KiB、名称唯一和
+# 全图无环约束。物理首跳需要连接本机服务时，server 必须显式使用 127.0.0.0/8
+# 范围内的 IPv4 字面量或 ::1；域名解析到回环地址会失败关闭。
#
# VLESS 子集：
# - type 固定 vless，network 固定 xhttp，tls 必须为 true；
@@ -138,38 +147,66 @@ proxies:
sni: anytls.example.com
udp: true
+# 可选的静态 `select` 代理组。字段外形是严格 Mihomo 子集：每组只接受 name、
+# type、proxies 和可选 default-selected，type 只能是 select，proxies 至少一项。
+# 成员可精确引用具体节点、另一个 select 组、DIRECT 或 REJECT；RULES 不是成员。
+# 组声明顺序、成员顺序和重复成员全部保留，嵌套组图必须无环；组数、成员数和嵌套
+# 深度没有独立上限，仍受 256 KiB 配置总大小和 O(V+E) 无环校验约束。
+#
+# default-selected 省略时选中第一项；显式值必须是当前组的直接成员。重复名称按
+# 第一项命中。没有 Controller 时，该初始选择在本次 session 内固定；有 Controller
+# 时可实时切换。选择只存于 VCore 当前 session 内存，VCore 不写回 YAML；宿主若需
+# 跨 session 保留，必须持久化选择并在下次配置中注入 default-selected。
+#
+# 切换只影响之后新建的物理 TCP 连接、UDP association/transport 和 DNS transport；
+# 既有 TCP 连接、UDP association、DNS cache/singleflight、DNS TCP pool 和其中的
+# transport 不迁移、不清空。选中成员失败时原样失败，代理组不自动换成员。
+proxy-groups:
+ - name: fallback-select
+ type: select
+ proxies: [socks-hop, DIRECT]
+
+ - name: main-select
+ type: select
+ proxies: [vless-edge, fallback-select, DIRECT, REJECT, vless-edge]
+ default-selected: vless-edge
+
# 运行时 DNS 可省略；enable: true 时主 nameserver 必须有 1–4 项。ipv6 省略时
# 默认为 true；false 时直接 AAAA 查询返回空结果，域名解析不查询 AAAA。nameserver
# 只接受裸 IP、udp://IP[:port] 或 tcp://IP[:port]。没有 fragment 时固定 DIRECT；
-# fragment 只接受 DIRECT、RULES 或实际代理名。`PROXY`/`#PROXY` 没有默认出口
-# 含义，只有存在同名代理时才有效。nameserver-policy 按顺序匹配
+# fragment 只接受 DIRECT、RULES、实际节点名或代理组名。`PROXY`/`#PROXY` 没有
+# 默认出口含义，只有存在同名 route target 时才有效。DNS route 选中代理组后，
+# 仅新建物理 transport 解析当前成员；cache 与既有 TCP pool 不随切换清空。
+# nameserver-policy 按顺序匹配
# `geosite:[,...]`，命中后只在当前组内顺序故障转移。
dns:
enable: true
ipv6: true
nameserver:
- - "tcp://1.1.1.1:53#vless-edge"
+ - "tcp://1.1.1.1:53#main-select"
nameserver-policy:
"geosite:private,cn,apple":
- "tcp://223.5.5.5:53#DIRECT"
- - "tcp://1.1.1.1:53#vless-edge"
+ - "tcp://1.1.1.1:53#main-select"
# rules 是运行配置必填项，按顺序首条命中。DIRECT 与 REJECT 是内置动作，其他
-# 动作必须精确使用实际代理名。`PROXY` 没有特殊别名。rules 不能为空，必须恰好
-# 以一个指向实际代理的 MATCH 结束；不存在隐式 MATCH 或 DIRECT 回退。
+# 动作必须精确使用实际节点名或代理组名。`PROXY` 没有特殊别名。rules 不能为空，
+# 必须恰好以一个指向实际节点或代理组的 MATCH 结束；不存在隐式 MATCH 或 DIRECT
+# 回退。选中组时使用当前成员，组本身不做 health check、测速或自动 failover。
rules:
- GEOSITE,category-ads-all,REJECT
- GEOSITE,cn,DIRECT
- GEOIP,CN,DIRECT,no-resolve
- DOMAIN-SUFFIX,anytls.example,anytls-edge
- NETWORK,UDP,anytls-edge
- - MATCH,vless-edge
+ - MATCH,main-select
-# measureDelay 使用独立的节点配置：顶层只能包含 proxies。节点字段和代理图校验
-# 与上文一致，但不能出现 port/authentication、tun、sniffer、Controller、DNS、
-# rules 或 GeoData。VCore 从“未被任何 dialer-proxy 引用”的节点推导唯一链头，
-# 且该链必须覆盖全部节点。测速不创建监听器、公共实例、TUN/protect 租约、DNS、
-# 规则引擎或 GeoData 注册。
+# measureDelay 使用独立的 node-only 配置：顶层只能包含 proxies，不能包含
+# proxy-groups。节点字段和代理图校验与上文一致，但不能出现 port/authentication、
+# tun、sniffer、Controller、DNS、rules 或 GeoData；dialer-proxy 同样只能引用具体
+# 节点。VCore 从“未被任何 dialer-proxy 引用”的节点推导唯一链头，且该链必须覆盖
+# 全部节点。测速不创建监听器、公共实例、TUN/protect 租约、DNS、规则引擎、代理组
+# 或 GeoData 注册。
#
# 最小测速示例：
# proxies:
diff --git a/docs/controller-api.md b/docs/controller-api.md
index 838c50f..88a3f03 100644
--- a/docs/controller-api.md
+++ b/docs/controller-api.md
@@ -1,26 +1,25 @@
-# TUN 流量 Controller API
+# 运行时 Controller API
-Controller 只提供当前 TUN 会话的单次 HTTP 流量快照，不提供持续推送、连接明细、配置修改或其他管理接口。
+Controller 是当前 Running Session 的回环 HTTP 接口。它提供一次性 TUN 流量快照，以及静态 `select` 代理组的状态查询和实时选择；它不是 Invoke API，也不承诺完整 Mihomo Dashboard 兼容。
-## 配置
+## 配置与生命周期
```yaml
external-controller: 127.0.0.1:9090
secret: "vcore-runtime-secret"
```
-- 省略 `external-controller` 表示不启动 Controller，此时不能单独配置 `secret`。
-- `external-controller` 只接受回环地址，并且只能与 `tun.enable: true` 一起使用。
-- `secret` 可省略；一旦出现就必须是非空 Bearer token。
-- `measureDelay` 的节点配置不能包含这两个字段。
-- `validateConfig` 只校验字段；`prepare` 不监听端口；`start` 绑定端口，绑定失败则启动失败。
-- `stop` 和 `destroyInstance` 关闭监听器。
+- 省略 `external-controller` 表示不启动 Controller，此时不能单独配置 `secret`。含代理组但没有 Controller 的配置合法，组在本次 session 内保持初始选择。
+- `external-controller` 只接受带显式非零端口的回环 IP 地址。它要求启用 TUN 或至少定义一个 `proxy-groups`；非 TUN 配置仍须通过 `port` 满足运行配置的入站要求。
+- 只要同时配置代理组与 Controller，`secret` 就必填；仅有 TUN 流量接口时可省略。`secret` 出现时必须为 1–255 UTF-8 字节，并保护本文定义的全部路由。
+- `measureDelay` 的 node-only 配置不能包含 Controller 或代理组字段。
+- `validateConfig` 只校验字段；`prepare` 不监听端口；`start` 绑定端口，绑定失败则启动失败。`stop` 和 `destroyInstance` 关闭监听器。
-Controller 与 TUN 会话同生共灭。每次会话启动都会新建统计状态并把全部计数清零。宿主应为每次运行选择专用端口和随机密钥，密钥不得写入日志或错误正文。
+Controller 与公共运行时 session 同生共灭。代理组选择只保存在 VCore 当前 session 的内存中；VCore 不写回配置。宿主如需跨 session 保留选择，必须自行持久化，并在下次 `configYaml` 中提供对应的 `default-selected`。
## Bearer 鉴权
-配置 `secret` 后，请求必须携带：
+配置 `secret` 后，每个请求都必须携带：
```http
Authorization: Bearer vcore-runtime-secret
@@ -28,12 +27,10 @@ Authorization: Bearer vcore-runtime-secret
要求：
-- scheme 必须是 `Bearer`；
-- token 必须与当前会话配置完全一致；
-- 缺失、格式错误或不匹配都返回 `401 Unauthorized`；
-- 比较过程不能通过日志、响应或明显的提前返回时序泄漏 token。
-
-未配置 `secret` 时不要求 `Authorization`。Controller 不使用 HTTP Basic；顶层 `authentication` 只属于可选 HTTP 代理监听器。
+- scheme 必须精确为 `Bearer`，token 必须与当前 session 配置完全一致；
+- 缺失、重复、格式错误或不匹配都返回 `401 Unauthorized`；
+- 比较过程不能通过日志、响应或明显的提前返回时序泄漏 token；
+- 未配置 `secret` 时不要求 `Authorization`；Controller 不使用 HTTP Basic，顶层 `authentication` 只属于 HTTP 代理 listener。
## `GET /traffic`
@@ -52,15 +49,99 @@ Authorization: Bearer vcore-runtime-secret
- `up`：最近一个完整的一秒窗口内，从宿主 TUN 进入 VCore 的原始 IP 包字节数；
- `down`：最近一个完整的一秒窗口内，由 VCore 写回宿主 TUN 的原始 IP 包字节数；
-- `upTotal`：本次 TUN 会话的累计上行字节数；
-- `downTotal`：本次 TUN 会话的累计下行字节数。
+- `upTotal`：本次 TUN session 的累计上行字节数；
+- `downTotal`：本次 TUN session 的累计下行字节数。
Apple utun 的四字节包信息头不计入统计。统计只覆盖跨过 TUN L3 边界的包，包括 TUN DNS 和 ICMP；不重复计算 TLS、XHTTP 或其他代理封装，也不包含 HTTP 代理入站、GeoData 下载、Controller 请求和 `measureDelay`。
-请求不会等待下一次采样，不保持分块响应，不升级 WebSocket，也不为调用方保存“上次读取”状态。首个采样窗口完成前和空闲窗口内，`up`/`down` 为 0；累计值在同一会话内单调不减并采用饱和语义。
+请求不会等待下一次采样，不保持分块响应，不升级 WebSocket，也不为调用方保存“上次读取”状态。首个采样窗口完成前和空闲窗口内，`up`/`down` 为 0；累计值在同一 session 内单调不减并采用饱和语义。没有 TUN 的代理组 Controller 对该路由返回 `404 Not Found`。
+
+## 代理组查询
+
+`GET /group` 按 YAML 声明顺序返回全部代理组：
+
+```json
+{
+ "proxies": [
+ {
+ "name": "main-select",
+ "type": "Selector",
+ "all": ["edge-a", "fallback-select", "DIRECT", "edge-a"],
+ "now": "edge-a"
+ }
+ ]
+}
+```
+
+以下两个请求返回同一个组状态对象：
+
+```http
+GET /group/{name}
+GET /proxies/{name}
+```
+
+- `name` 是组定义名，`type` 固定为 `Selector`；
+- `all` 是配置中的直接成员，严格保留顺序和重复项；
+- `now` 是当前选中的直接成员名。若该成员是嵌套组，`now` 仍返回组名，不展开为最终叶节点；
+- 名称和值大小写敏感并精确匹配，不做大小写折叠或 Unicode normalization。
+
+## `PUT /proxies/{name}`
+
+切换组的当前直接成员：
+
+```http
+PUT /proxies/main-select HTTP/1.1
+Authorization: Bearer vcore-runtime-secret
+Content-Type: application/json
+Content-Length: 26
+
+{"name":"fallback-select"}
+```
+
+成功返回 `204 No Content` 和空正文。`name` 必须是该组 `all` 中的直接成员；重复名称命中第一项。请求不接受传递成员、数组、索引、CAS/version 或其他字段。
+
+请求正文边界：
+
+- `Content-Type` 必须是唯一且不带参数的 `application/json`；
+- 必须有且只有一个十进制 `Content-Length`，不接受 `Transfer-Encoding` 或 chunked；
+- 正文最大 1 KiB，读取 header 和 body 各有 5 秒期限；
+- JSON 必须是 UTF-8 对象并且恰好包含一个字符串字段 `name`；缺失、未知或重复字段、malformed JSON 和尾随 JSON 都会失败；
+- 未知组、未知成员和任何无效请求都不得改变当前选择。
+
+同一组的成功写入是线性化的，最后一个成功提交的请求胜出；不同组独立更新，不提供跨组事务或 CAS。
+
+## 名称与路径
+
+节点和代理组定义名共享一个命名空间。名称必须为 1–64 UTF-8 字节，首尾不能是任何 Unicode 空白字符，不能含控制字符或 `, # / ? & = % \\`，也不能是 `.` 或 `..`。定义名额外保留 `DIRECT`、`REJECT` 和 `RULES`；前两者仍可作为组成员，`RULES` 只作为 DNS sentinel。内部普通空格、CJK 和 emoji 可以使用。
+
+路径中的 `{name}` 必须是单个 segment。Controller 对 percent-encoding 严格解码一次，再执行相同的 UTF-8 和名称校验；无效 `%`、无效 UTF-8、解码后的 `/`、二次编码形式、query 和 fragment 都会失败。客户端应对非 ASCII 或路径保留字节执行一次标准 percent-encoding；`+` 不会被当作空格。
+
+## 选择生效边界
+
+代理组成员列表在配置期固定，只有当前选择可在 Running Session 内改变：
+
+- 新建的物理 TCP 连接使用切换后的当前叶节点；既有 TCP 连接保持原路径；
+- 新建的 UDP association/物理 transport 使用切换后的当前叶节点；既有 association 不迁移；
+- 新建的 DNS transport 使用切换后的当前叶节点；DNS cache、singleflight 状态和已在池中的 TCP transport 不清空、不迁移；
+- 切换不主动断开连接、不刷新缓存、不重启运行时，也不修改 YAML 或下一次 session 的默认值；
+- 选中节点、`DIRECT` 或 `REJECT` 时按原样执行；选中嵌套组时继续解析其当前成员。失败按原样返回，不自动选择其他成员。
+
+## HTTP 状态与协议边界
-## 边界
+| 状态 | 含义 |
+| --- | --- |
+| `200 OK` | 查询成功，返回 `application/json` |
+| `204 No Content` | 选择成功，正文为空 |
+| `400 Bad Request` | 路径、JSON、长度格式或成员无效 |
+| `401 Unauthorized` | Bearer 鉴权失败 |
+| `403 Forbidden` | 请求来源不是回环地址 |
+| `404 Not Found` | 路由、组或当前 session 中的 TUN 流量资源不存在 |
+| `405 Method Not Allowed` | 路由存在但方法不允许 |
+| `408 Request Timeout` | header 或 body 读取超时 |
+| `411 Length Required` | PUT 缺少 `Content-Length` |
+| `413 Payload Too Large` | PUT 正文超过 1 KiB |
+| `415 Unsupported Media Type` | PUT 不是严格 `application/json` |
-Windows 的 TUN 运行时位于独立 Session Host 时，App 通过回环 HTTP 访问 Controller。流量查询不是 `VCoreInvoke` 方法，不携带 `instanceId`，也不占用 Invoke 命令锁。
+第一版不提供 provider/`use`、health check、自动 failover、`url-test`/`fallback`/`load-balance`、delay 测试、连接管理、配置修改、WebSocket 推送、Controller 版本协商或完整 Dashboard response。除 `GET /traffic`、`GET /group`、`GET /group/{name}`、`GET /proxies/{name}` 和 `PUT /proxies/{name}` 外，其他路径和方法均不属于公共协议。
-当前协议只定义符合鉴权要求的 `GET /traffic`。其他路径和方法均不属于公共协议。
+Windows 的完整运行时和 Controller 位于独立 Session Host。App 通过回环 HTTP 直接访问实际 Running Session；组查询和切换不经过 `VCoreInvoke`、Windows bridge 或 Provider 控制管道，不携带 `instanceId`，也不占用 Invoke 命令锁。
diff --git a/docs/geodata.md b/docs/geodata.md
index 9936de5..eb2d9d5 100644
--- a/docs/geodata.md
+++ b/docs/geodata.md
@@ -10,7 +10,7 @@ rules:
- GEOSITE,cn,DIRECT
- GEOIP,PRIVATE,DIRECT,no-resolve
- GEOIP,CN,DIRECT
- - MATCH,vless-edge
+ - MATCH,main-select
```
语法：
@@ -20,12 +20,12 @@ GEOSITE,,
GEOIP,,[,no-resolve]
```
-- 规则类型和 `code` 不区分 ASCII 大小写，代理目标名称大小写敏感。
-- `target` 只能是 `DIRECT`、`REJECT` 或实际代理名。
+- 规则类型和 `code` 不区分 ASCII 大小写，route target 名称大小写敏感并精确匹配。
+- `target` 只能是 `DIRECT`、`REJECT`、实际代理节点名或静态 `select` 组名。
- `code` 必须匹配 `[A-Za-z0-9][A-Za-z0-9._+!-]{0,63}`，按 ASCII 大小写折叠后判重。
- `GEOSITE` 恰好三段；`GEOIP` 只允许可选且大小写敏感的 `no-resolve`。
- 不支持反选、属性选择器、单条规则多个 code、源地址 GeoIP 或隐式局域网分类。
-- 规则按顺序首条命中，最终 `MATCH` 必须指向实际代理。
+- 规则按顺序首条命中，最终 `MATCH` 必须指向实际代理节点或代理组。
DNS `nameserver-policy` 中的 `geosite:[,...]` 与业务规则共享同一份分类需求和匹配器。
@@ -59,7 +59,7 @@ geo-update-interval: 24
- `geox-url` 只能包含 `geoip` 和 `geosite`；URL 必须是以域名为主机、无 userinfo/fragment 的绝对 HTTPS URL。
- `geo-update-interval` 只接受整数 `24`。
- `validateConfig` 和 `prepare` 不下载。实例启动后，只有自动更新已开启且规则实际需要资产时才运行更新任务。
-- 下载固定使用最终 `MATCH` 选中的完整代理链，不回退 DIRECT 或系统代理。
+- 下载固定使用最终 `MATCH` route target。若它是代理组，每次新建下载物理 transport 时沿嵌套组解析到当时选中的具体节点、`DIRECT` 或 `REJECT`；失败不自动换成员，也不隐式回退 DIRECT 或系统代理。
- 缺失资产立即检查；失败后按 1 分钟、5 分钟、15 分钟、1 小时退避，之后保持 1 小时上限。成功后恢复 24 小时周期。
- ETag、SHA-256、源 URL 和下次检查时间保存在 VCore 管理的状态中。合法 304 只推进调度。
- 下载写入同目录暂存文件，通过大小、hash、wire、需求和资源校验后原子替换。失败保留上一份有效资产。
@@ -111,6 +111,7 @@ geo-update-interval: 24
- `prepare` 注册去重后的需求并读取当时可用的本地快照，不等待更新。
- Manager 只为当前公共实例构建匹配器；停止或销毁实例时释放需求和快照。
- 后台更新通过完整校验后原子发布不可变快照。新流使用新快照，已经完成的选路不回溯。
+- Controller 切换代理组不会重启正在进行的下载或迁移既有连接；只有之后新建的 GeoData 下载物理 transport 使用新选择。
- `measureDelay` 不注册 GeoData、匹配器或更新任务。
## 资源上限
diff --git a/docs/invoke-api.md b/docs/invoke-api.md
index 4e089df..665c2ba 100644
--- a/docs/invoke-api.md
+++ b/docs/invoke-api.md
@@ -1,6 +1,6 @@
# VCore Invoke API
-业务接口版本为 5，配置结构修订版为 12。配置只通过内联的 `configYaml` 或 `configYamls` 传入；每份已加载的 VCore 运行时最多拥有一个公共实例。
+业务接口版本为 5，配置结构修订版为 13。配置只通过内联的 `configYaml` 或 `configYamls` 传入；每份已加载的 VCore 运行时最多拥有一个公共实例。代理组实时选择沿用 Controller，不增加 Invoke method 或版本协商。
## C ABI
@@ -89,7 +89,7 @@ stopped -> preparing -> prepared -> starting -> running
- 同一实例一次只执行一个生命周期命令，重叠命令立即失败。
- `validateConfig` 是可并发的纯校验方法。
- `measureDelay` 使用独立批次和私有工作器，不进入公共实例表。
-- 不支持热重载；切换配置需要 `stop -> prepare -> start`。
+- 不支持配置热重载；切换配置需要 `stop -> prepare -> start`。唯一的运行期路由变更是通过 Controller 修改静态 `select` 组的当前选择，它不修改已 prepare 的配置。
- `stop` 在 stopped 状态幂等；`destroyInstance` 是最终同步清理屏障。
## 方法
@@ -107,8 +107,8 @@ stopped -> preparing -> prepared -> starting -> running
```json
{
"apiVersion": 5,
- "buildIdentity": "VCore;engine=rust;coreVersion=0.1.0;invokeApiVersion=5;configVersion=12",
- "configVersion": 12,
+ "buildIdentity": "VCore;engine=rust;coreVersion=0.1.0;invokeApiVersion=5;configVersion=13",
+ "configVersion": 13,
"engine": "rust",
"version": "0.1.0"
}
@@ -193,7 +193,7 @@ stopped -> preparing -> prepared -> starting -> running
}
```
-完成大小、YAML、结构、引用、代理图和字段组合校验。不创建实例、不解析远端域名、不联网，也不读取 GeoData。资产缺失不影响纯配置校验。
+完成大小、YAML、结构、共享 route-target 命名空间、引用、具体节点 `dialer-proxy` 图、代理组 DAG 和字段组合校验。不创建实例、不解析远端域名、不联网，也不读取 GeoData。资产缺失不影响纯配置校验。
### `prepare`
@@ -210,6 +210,7 @@ stopped -> preparing -> prepared -> starting -> running
- 读取当时可用的本地 GeoData，不启动或等待下载。
- 只为直接访问物理网络的代理根节点执行引导 DNS；代理链上的域名交给下一跳。
+- 校验每个静态 `select` 组的初始选择；省略 `default-selected` 时使用第一项，显式值必须是直接成员。可变的 session 选择状态到 `start` 时才创建。
- 成功进入 prepared；失败释放临时资源并回到 stopped。
- 含 TUN 的配置从 preparing 起持有运行时本地的 TUN/protect 租约，直到停止或销毁。
- Android 只有在实际启用 TUN 时才要求事先注册 protect controller。
@@ -232,6 +233,7 @@ Android 使用 `rawIp`。非 TUN 配置必须省略 `tunFd` 和 `tunFraming`。
- `tunFd` 由宿主借用，宿主必须预先设置 nonblocking。
- VCore 校验后建立带 `CLOEXEC` 的副本，只关闭副本。
- Apple 只接受 `utun`，Android 只接受 `rawIp`。
+- 从 prepared 配置创建本次 session 的代理组选择状态。
- 所有监听器和关键数据面成功后才进入 running。
- GeoData 更新只在启动后按需后台运行，不属于启动关键路径。
- Windows 系统 VPN 使用安装包桥接接口，不使用文件描述符启动参数。
@@ -242,7 +244,7 @@ Android 使用 `rawIp`。非 TUN 配置必须省略 `tunFd` 和 `tunFraming`。
{"apiVersion":5,"method":"stop","instanceId":"1","payload":{}}
```
-同步取消并等待监听器、TUN、netstack、DNS、会话、出站和更新任务，关闭 VCore 持有的文件描述符副本并释放平台回调租约。返回后不得继续产生数据包或调用 protect callback。
+同步取消并等待监听器、Controller、TUN、netstack、DNS、会话、出站和更新任务，关闭 VCore 持有的文件描述符副本并释放平台回调租约。返回后不得继续产生数据包或调用 protect callback；本次 session 的代理组选择随之销毁。
### `getState`
@@ -287,7 +289,7 @@ Android 使用 `rawIp`。非 TUN 配置必须省略 `tunFd` 和 `tunFraming`。
- `configYamls` 接受 1–5 份非空节点配置，`timeout` 为 1–30 秒。
- 同一运行时一次只允许一个测速批次，最多并发五个私有工作器。
-- 节点配置顶层只允许 `proxies`。VCore 推导唯一链头，且该链必须覆盖全部节点。
+- 节点配置顶层只允许 `proxies`，不接受 `proxy-groups`；`dialer-proxy` 也只能引用具体节点。VCore 推导唯一链头，且该链必须覆盖全部节点。
- 工作器只准备出站图并执行 TCP、可选 TLS 和 HTTP/1.1 HEAD；不创建公共实例、监听器、TUN、DNS、规则、嗅探器或 GeoData。
- URL 必须是无 userinfo 和 fragment 的绝对 HTTP/HTTPS URL；HTTPS 使用发布信任根。
- 任意合法 HTTP 状态都表示探测成功；不跟随重定向、不读取正文。
@@ -310,7 +312,9 @@ ProtectFd(fd) -> bool
## Controller
-配置 `external-controller` 后，TUN 运行时提供回环 `GET /traffic`。该查询不是 Invoke 方法，不携带 `instanceId`。完整语义见 [Controller API](controller-api.md)。
+配置 `external-controller` 后，运行时可提供回环 `GET /traffic`、`GET /group`、`GET /group/{name}`、`GET /proxies/{name}` 和 `PUT /proxies/{name}`。代理组 Controller 可以在非 TUN 的本地 HTTP 配置中运行；此时 `/traffic` 不存在。只要 Controller 管理代理组，`secret` 就必填并保护全部路由。
+
+组成员列表是配置期固定的，选择只存于当前 Running Session。成功切换只影响之后新建的物理 TCP、UDP 和 DNS transport，不迁移既有连接、UDP association、DNS 状态或 TCP pool，也不触发 failover。Controller 查询不携带 `instanceId`，不进入 Invoke 命令锁；完整语义见 [Controller API](controller-api.md)。
## Windows 安装包桥接
@@ -355,7 +359,7 @@ ProtectFd(fd) -> bool
桥接把 YAML、进程顺序、路径和参数发布为 `vcore-session-v2:` Session Snapshot。参数引用的文件由调用方保持存在且不可变，VCore 不读取或摘要其内容。`getVpnStatus.data.snapshotToken` 返回该完整 Session token。
-桥接请求最大 1 MiB。它负责安装包身份、单一 VPN profile、不可变 Session Snapshot、Session Host 激活和系统 VPN 状态；不公开 profile CRUD、内部文件路径、backend 描述、参数、PID、管道名称或 Snapshot 维护。数据包、Controller 查询和业务生命周期不经过该 JSON 桥接。
+桥接请求最大 1 MiB。它负责安装包身份、单一 VPN profile、不可变 Session Snapshot、连接/断开命令和系统 VPN 状态；Provider 负责激活 Session Host。桥接不公开 profile CRUD、内部文件路径、backend 描述、参数、PID、管道名称或 Snapshot 维护。数据包、Controller 流量查询、代理组查询/切换和业务生命周期不经过该 JSON 桥接。
## 编码与安全边界
@@ -363,4 +367,5 @@ ProtectFd(fd) -> bool
- 配置、错误和日志按 UTF-8 字节计数并受固定上限约束。
- TUN 原始数据包最大 1,500 字节；最终代理 UDP 负载最大 1,452 字节。
- 嵌套 UDP 协议可以增加有界帧头，但解封装后的最终负载仍受 1,452 字节限制。
+- 节点和代理组定义名共享大小写敏感的严格 UTF-8 命名空间；`DIRECT`、`REJECT` 和 `RULES` 不能用作定义名。
- Secret、password、UUID、REALITY key、short ID、目标地址和完整配置不得进入日志。
diff --git a/docs/runtime-resource-policy.md b/docs/runtime-resource-policy.md
index d278d2a..b4f3667 100644
--- a/docs/runtime-resource-policy.md
+++ b/docs/runtime-resource-policy.md
@@ -59,7 +59,7 @@ GeoData 分配容量 8 MiB
- 不设置固定的活动请求或活动传输总许可数。
- 相同 key 的 cache miss 使用 singleflight；leader 取消后 follower 重新选举。
- UDP 传输属于单次请求，同一尝试的重发复用当前传输。
-- 显式 TCP nameserver 按 endpoint 和最终出口复用；一条连接同时只处理一个查询。
+- 显式 TCP nameserver 按 endpoint 和配置的 route target 复用；一条连接同时只处理一个查询。
- 活动 TCP 不设固定数量上限；空闲连接总数最多 4，同 key 最多 2，空闲超时 30 秒。
- 查询、单次尝试和 UDP 重发期限分别为 5 秒、3 秒和 1 秒。
- 响应最多扫描 64 条记录，类型化缓存和提示最多保留 16 个唯一 IP。
@@ -67,6 +67,16 @@ GeoData 分配容量 8 MiB
完整语义见 [TUN ICMP 与 DNS](tun-icmp-dns.md)。
+## 代理组与 Controller
+
+- 静态 `select` 组只拥有不可变的有序成员和每组一个可原子替换的当前索引，不拥有协议连接、后台任务、队列、缓存或独立 worker。
+- 组数、每组成员数、重复成员数和嵌套深度没有独立固定上限，统一受 256 KiB YAML 上限约束；配置期使用 O(V+E) 的迭代 DAG 校验，运行时也以迭代方式解析当前叶节点。
+- 同组成功选择是线性化的，不同组独立；选择失败不改变状态，也不创建重试或自动 failover 任务。
+- 切换不扫描或迁移现有 TCP、UDP、DNS transport，不刷新 DNS cache/singleflight 或 TCP pool；资源仍由原所有者按既有 timeout、EOF、取消和 stop 语义回收。
+- Controller 同时最多跟踪 8 个连接任务。请求 header 和 PUT body 各有 5 秒读取期限，PUT body 最大 1 KiB；超时、超限和解析失败只终止当前请求。
+
+完整接口见 [运行时 Controller](controller-api.md)。
+
## GeoData
- GeoSite 与 GeoIP 共享 8 MiB 分配容量。
diff --git a/docs/tun-icmp-dns.md b/docs/tun-icmp-dns.md
index e188cf0..c946cdf 100644
--- a/docs/tun-icmp-dns.md
+++ b/docs/tun-icmp-dns.md
@@ -53,7 +53,7 @@ dns:
enable: true
ipv6: true
nameserver:
- - "tcp://1.1.1.1:53#vless-edge"
+ - "tcp://1.1.1.1:53#main-select"
nameserver-policy:
"geosite:private,cn":
- "tcp://223.5.5.5:53#DIRECT"
@@ -66,10 +66,12 @@ dns:
- `dns.ipv6: false` 不限制 IPv6 nameserver；顶层 `ipv6: false` 会阻止通过 DIRECT（含 `RULES` 选中 DIRECT）的 IPv6 nameserver 在本机物理建链，并继续当前组的故障转移。
- Endpoint 必须是 IP 字面量，不支持 hostname、system 或 DHCP resolver。
- 无 fragment 时固定使用 DIRECT。
-- Fragment 只接受 `DIRECT`、`RULES` 或实际代理名。
+- Fragment 只接受 `DIRECT`、`RULES`、实际代理节点名或静态 `select` 组名。
- `#RULES` 只按 nameserver endpoint 和传输执行业务规则，不把 DNS question 当作选路域名。
- 规则结果为 `REJECT` 时，当前尝试失败并继续当前组下一项。
+代理组成员可以是具体节点、嵌套组、`DIRECT` 或 `REJECT`。DNS exchange 需要新建物理 transport 时解析当时的当前叶节点；选中成员失败不会使代理组自动改选，但 nameserver 列表仍按本节已有故障转移语义继续下一项。
+
### Policy
`nameserver-policy` 是有序映射：
@@ -132,13 +134,15 @@ A/AAAA 缓存最多 256 项，从空容量按需增长。TUN 域名提示存储
显式 TCP nameserver 使用每运行时独立连接池：
-- Key 为 endpoint 和最终出口；
+- Key 为 endpoint 和配置的 route target；
- 一条连接同时只处理一个查询，不做 pipeline；
- 活动连接不设固定业务数量上限；空闲连接总数最多 4、同 key 最多 2、超时 30 秒；
- 完成帧和响应校验后才能归还连接；
- 复用连接遇到 EOF、I/O、reset 或响应不匹配时，在原尝试期限内最多新建一次连接；
- 非法、截断或超限响应不重试、不归还连接。
+Controller 切换代理组后，只在后续需要创建新 DNS transport 时使用新选择。类型化/原始响应 cache、singleflight 状态和已经位于 TCP pool 中的 transport 不清空、不迁移；因此命中 cache 或复用既有 TCP transport 时，不会为切换单独建链。停止 session 才统一释放这些状态。
+
## 队列与生命周期
| 队列 | 容量 |
@@ -157,7 +161,7 @@ DNS 和普通 UDP 响应使用不同队列，但共享 netstack UDP 入站接收
- 真实 ICMP 转发、ICMP error、Traceroute、ICMP 选路规则或 ICMP 测速；
- DoH、DoT、DoQ、hostname/system/DHCP nameserver；
-- 代理组、并行 nameserver 竞速、DNS fallback group、fake IP 和 hosts；
+- 代理组 provider/health check/自动 failover、并行 nameserver 竞速、DNS fallback group、fake IP 和 hosts；
- 用户可配置的缓存容量、超时、重试或并发度；
- 使用 DNS question 执行业务规则，或用 DNS 出口改写后续业务动作。
diff --git a/docs/windows-session-runtime.md b/docs/windows-session-runtime.md
index 5bc38fa..8680523 100644
--- a/docs/windows-session-runtime.md
+++ b/docs/windows-session-runtime.md
@@ -1,6 +1,6 @@
# Windows 会话运行时
-Windows 每个 VPN 会话由一个隐藏的完全信任 Session Host 独占完整 VCore 运行时。AppContainer Provider 只负责 Windows VPN 平台资源、原始包转发和失败关闭；系统中不存在 Provider 内嵌运行时的备用路径。
+Windows package 只有一个主 Application，但每个 VPN 会话仍由独立的完全信任 Session Host 独占完整 VCore 运行时。AppContainer Provider 只负责 Windows VPN 平台资源、原始包转发和失败关闭；系统中不存在 Provider 内嵌运行时的备用路径。
## 参与者与所有权
@@ -8,32 +8,33 @@ Windows 每个 VPN 会话由一个隐藏的完全信任 Session Host 独占完
前台宿主（完全信任）
├─ VCoreInvoke
└─ VCoreWindowsVpnInvoke
- │ 激活
- ▼
+ ├─ Session Snapshot / profile
+ └─ ConnectProfileAsync
+ │ Windows 激活
+ ▼
+vcore-windows-vpn-host.exe + vcore.dll（AppContainer）
+ ├─ VpnChannel / 路由 / DNS / 物理网络
+ ├─ VpnPacketBuffer / 有界回调队列 / 失败关闭
+ └─ FullTrustProcessLauncher
+ │ 无参数激活
+ ▼
vcore-windows-session-host.exe
├─ 校验不可变 Session Snapshot
├─ 可选 Windows session backend / Job Object
├─ PreparedCore / RunningCore
- ├─ DNS / 规则 / GeoData / 嗅探器
+ ├─ DNS / 规则 / GeoData / 嗅探器 / select 代理组
├─ VLESS / SOCKS5 / AnyTLS / DIRECT
- └─ 已鉴权流量 Controller
- ▲
- │ 同包控制管道 + 数据管道
- ▼
-vcore-windows-vpn-host.exe + vcore.dll（AppContainer）
- ├─ VpnChannel 生命周期
- ├─ 路由 / DNS / 物理网络
- ├─ VpnPacketBuffer 所有权
- ├─ 有界回调队列
- └─ 失败关闭
+ └─ 运行时 Controller（TUN 流量 / 代理组选择）
+ ▲
+ └─ 同包控制管道 + 数据管道
```
| 参与者 | 拥有 | 不拥有 |
| --- | --- | --- |
| 前台宿主 | 用户命令、会话记录、UI 状态 | TUN 运行时、包通道、Provider 状态 |
-| Windows 桥接 | Session Snapshot、profile、Session Host 激活与回滚 | 数据包、代理流 |
+| Windows 桥接 | Session Snapshot、profile、连接/断开命令 | 数据包、代理流、Session Host 进程 |
| Session Host | 单次 VCore 运行时、可选 session backend、Controller、GeoData、包客户端 | `VpnChannel`、路由、进程业务配置 |
-| Provider | `VpnChannel`、WinRT 缓冲区、路由、物理绑定、管道服务端、网络监控 | YAML、代理图、Controller、GeoData、backend 描述 |
+| Provider | `VpnChannel`、WinRT 缓冲区、路由、物理绑定、管道服务端、网络监控、Session Host 激活 | YAML、代理图、Controller、GeoData、backend 描述 |
| SOCKS 服务 | 自身监听器、外层 socket 和绕过策略 | VCore 代理图和 Windows profile |
Session Host 每次连接新建一个进程，不常驻、不复用运行时，也不处理 URI 或 StartupTask。
@@ -48,7 +49,7 @@ Session Host 每次连接新建一个进程，不常驻、不复用运行时，
LocalState/vcore/windows/sessions/.json
```
-- Snapshot revision 2 保存完整 VCore YAML，以及可选的有序 `sessionBackend.processes`；每项只有规范 package-relative executable path 和 argv 数组。
+- Snapshot revision 2 保存完整 VCore YAML（包括代理组及其 `default-selected`），以及可选的有序 `sessionBackend.processes`；每项只有规范 package-relative executable path 和 argv 数组。
- token 覆盖 YAML、进程顺序、路径和参数。参数引用的文件由调用方保持存在且不可变，VCore 不读取或摘要其内容。
- profile custom configuration 是最大 1 KiB 的严格 JSON，包含修订版 3、规范 Session token、顶层 IPv6 开关和 TUN/DNS 的 IPv4/IPv6 地址。
- custom configuration 不包含 YAML、backend 描述、Controller secret、PID 或管道路径。
@@ -61,21 +62,21 @@ Session Host 每次连接新建一个进程，不常驻、不复用运行时，
1. 前台宿主调用 `startVpn(configYaml, networkSettings, sessionBackend?)`。
2. 桥接验证配置、四个地址和进程描述，发布不可变 Session Snapshot，并把解析后的顶层 IPv6 开关写入 profile configuration。
-3. 桥接通过 `IApplicationActivationManager` 激活隐藏 Session Host，只传 `--session-token `。
-4. 桥接持有激活返回的精确进程句柄。
-5. 桥接写入单一 VPN profile 并调用 `ConnectProfileAsync`。
-6. Windows 激活 Provider。
-7. Provider 在安装路由前选择物理网络绑定，并创建控制/数据管道服务端；顶层 `ipv6: false` 时不安装 IPv6 地址、路由或 DNS。
-8. Provider 原子发布会合记录。
-9. Session Host 校验命令行令牌和会合记录，构造限定对象路径并连接两条管道。
-10. Session Host 发送 `SessionHello`；Provider 返回 `ProviderHello` 和不可变物理绑定。
-11. Session Host 读取 Snapshot；若存在 backend，则用一个 kill-on-close Job Object 按顺序启动全部进程。
-12. Session Host 准备并启动完整 VCore 运行时和 Controller。
+3. 桥接写入单一 VPN profile 并调用 `ConnectProfileAsync`；它不启动或持有 Session Host。
+4. Windows 激活 AppContainer Provider。
+5. Provider 从 profile configuration 取得权威 token，选择物理网络绑定并准备基础资源。
+6. Provider 清理陈旧会合记录，通过无参数 `FullTrustProcessLauncher` 激活 Session Host。
+7. Session Host 不读取动态命令行参数，等待 Provider 会合记录。
+8. Provider 创建控制/数据管道服务端并原子发布会合记录。
+9. Session Host 严格解析会合记录，把其中的 token 作为候选值，构造限定对象路径并连接两条管道。
+10. Session Host 发送 `SessionHello`；Provider 把候选 token 与 profile token 精确比较后返回 `ProviderHello` 和不可变物理绑定。
+11. Session Host 验证 `ProviderHello` 回传同一 token，之后才读取 Snapshot；若存在 backend，则用一个 kill-on-close Job Object 按顺序启动全部进程。
+12. Session Host 准备并启动完整 VCore 运行时、静态代理组状态和 Controller。
13. Session Host 确认受管进程尚未退出后返回 `RuntimeReady`。
14. Provider 调用 `StartWithMainTransport` 并启动失败关闭监视器。
15. 连接成功后，桥接向前台宿主返回当前系统 VPN 状态。
-任一步失败都必须关闭包通道、终止本次精确 Session Host、收敛为 Disconnected，并只返回有界脱敏错误。
+任一步失败都必须关闭包通道并收敛为 Disconnected，只返回有界脱敏错误；未完成握手的 Session Host 最多等待 15 秒后退出。
## 会合记录
@@ -93,8 +94,8 @@ Session Host 每次连接新建一个进程，不常驻、不复用运行时，
- Provider 是唯一发布者和清理者；
- 使用同目录暂存文件和原子重命名；
-- 只接受规范 AppContainer 相对路径、固定 leaf 和匹配令牌；
-- 非普通文件、reparse point、超限、未知字段和令牌不匹配都会失败关闭；
+- 只接受规范 token、AppContainer 相对路径和固定 leaf；
+- 非普通文件、reparse point、超限或未知字段都会失败关闭；候选 token 与 profile token 的绑定只在双向握手中完成；
- 握手完成后删除，新连接前清理断开状态下的陈旧记录。
## 控制协议
@@ -193,9 +194,13 @@ Provider 订阅网络变化，等待 2 秒消抖后复验适配器、地址和 i
- Controller 由 Session Host 监听完全信任的回环地址；
- `RuntimeReady` 前必须完成绑定，失败则连接失败；
-- 前台宿主持有配置中的端口和 secret，并调用 `GET /traffic`；
+- 前台宿主持有配置中的端口和 secret，并调用 `GET /traffic`、`GET /group`、`GET /group/{name}`、`GET /proxies/{name}` 或 `PUT /proxies/{name}`；
+- 配置代理组与 Controller 时 secret 必填并保护全部路由；仅有 TUN 流量 Controller 时 secret 仍可省略；
+- 代理组选择属于 Session Host 中实际 Running Session 的内存状态，不经过 Windows bridge、Provider 控制管道或 Session Snapshot 写回；
+- 成功切换只影响之后新建的物理 TCP、UDP 和 DNS transport，不迁移既有连接、UDP association、DNS 状态或 TCP pool，也不执行自动 failover；
+- 宿主如需跨 VPN session 保留选择，必须自行持久化，并在下次 `startVpn` 的 YAML 中注入对应 `default-selected`；
- 前台宿主退出后 Controller 和运行时继续，重新启动后恢复查询；
-- Stop 关闭 Controller，下一会话从零计数；
+- Stop 关闭 Controller，销毁本次代理组选择；下一会话重新采用 YAML 初始选择并从零计数；
- 回环 SOCKS5 是普通 VCore 出站；其服务可以由外部宿主管理，也可以恰好运行在 session backend 中，但 VCore 不从 backend 描述推断端口或 readiness；
- 单个 SOCKS 流失败不停止 VPN。
@@ -213,8 +218,9 @@ Provider 订阅网络变化，等待 2 秒消抖后复验适配器、地址和 i
| 显式 Stop | Disconnect -> Stop -> 有界确认 -> channel Stop |
| 本地 SOCKS 流失败且服务进程仍存活 | 只失败当前流 |
| Controller 绑定失败 | 启动失败，profile 不进入 Connected |
+| Controller 切换代理组 | 当前 Session Host 原子更新选择；既有 transport 保持原路径 |
-桥接回滚只终止本次激活返回的精确进程句柄，不按进程名扫描或清理。
+桥接不持有或终止 Session Host 进程；启动失败由 Provider 的 Connect 清理路径收敛，显式 Stop 通过系统 profile 断开。
## 安装包契约
diff --git a/docs/windows-vpn.md b/docs/windows-vpn.md
index d8c2902..239ab22 100644
--- a/docs/windows-vpn.md
+++ b/docs/windows-vpn.md
@@ -9,7 +9,7 @@ Windows 数据面只使用官方 `Windows.Networking.Vpn` 和 `windows-rs`，不
- 分发形式：具有 package identity 的 MSIX。
- 前台：调用 Windows 桥接接口的完全信任宿主。
- Provider：同 package family 的 AppContainer 应用。
-- Session Host：同 package 中隐藏的完全信任应用，每个 VPN 会话一个进程，可选拥有同包 session backend。
+- Session Host：同一主 Application 的完全信任 extension，每个 VPN 会话一个独立进程，可选拥有同包 session backend。
- Windows 依赖：`windows = 0.62.2`。
- Manifest：包含 `networkingVpnProvider` 和 `runFullTrust`，不配置产品级 loopback exemption。
@@ -130,7 +130,7 @@ Provider 是物理网络状态的唯一权威，并订阅 `NetworkStatusChanged`
- Provider 创建 AppContainer 本地控制管道和数据管道；
- `GetAppContainerNamedObjectPath` 提供限定对象路径；
-- `IApplicationActivationManager` 激活隐藏 Session Host；
+- Provider 通过无参数 `FullTrustProcessLauncher` 激活同一 Application 的 Session Host；
- Session Host 使用当前 Windows session ID 构造限定路径并连接；
- 前台宿主退出不停止 Provider 或 Session Host，重新启动后从系统 profile 恢复状态。
@@ -155,8 +155,9 @@ vcore-windows-vpn-host.exe
vcore-windows-session-host.exe
```
-- 三个可执行参与者相互独立；
-- Session Host 不显示在应用列表，也不注册 StartupTask 或 URI；
+- manifest 只有一个主 Application，三个可执行参与者相互独立；
+- Session Host 是 `windows.fullTrustProcess` extension，不显示在应用列表，也不注册 StartupTask 或 URI；
+- Provider 的 `windows.backgroundTasks` extension 显式使用 `windowsApp + appContainer`；
- Provider activation class 来自 `vcore.dll`；
- 同一 package 只维护一个 `VCore` VPN profile；
- custom configuration 是最大 1 KiB 的严格 JSON，只含修订版 3、Session token、顶层 IPv6 开关和四个网络地址；
@@ -176,7 +177,7 @@ vcore-windows-session-host.exe
| 受管进程退出 | 清理同 Job 进程并停止当前 VPN |
| 本地 SOCKS 流失败且服务进程仍存活 | 只失败当前流 |
| 显式 Stop | 有界确认后清理路由、记录、Controller 和会话进程 |
-| 启动失败 | 终止本次精确 Session Host 进程并收敛为 Disconnected |
+| 启动失败 | Provider Connect 失败；未完成握手的 Session Host 最多等待 15 秒后退出 |
当前实测范围和未完成平台门禁见 [验收矩阵](acceptance.md)。
@@ -187,5 +188,5 @@ vcore-windows-session-host.exe
- [`VpnChannel.AssociateTransport`](https://learn.microsoft.com/uwp/api/windows.networking.vpn.vpnchannel.associatetransport)
- [`VpnPacketBuffer`](https://learn.microsoft.com/uwp/api/windows.networking.vpn.vpnpacketbuffer)
- [`VpnManagementAgent`](https://learn.microsoft.com/uwp/api/windows.networking.vpn.vpnmanagementagent)
-- [`IApplicationActivationManager`](https://learn.microsoft.com/windows/win32/api/shobjidl_core/nn-shobjidl_core-iapplicationactivationmanager)
+- [`FullTrustProcessLauncher`](https://learn.microsoft.com/uwp/api/windows.applicationmodel.fulltrustprocesslauncher)
- [Package identity](https://learn.microsoft.com/windows/apps/desktop/modernize/package-identity-overview)
diff --git a/example/windows-uwp/AppxManifest.xml.in b/example/windows-uwp/AppxManifest.xml.in
index b729c84..b4f4b2b 100644
--- a/example/windows-uwp/AppxManifest.xml.in
+++ b/example/windows-uwp/AppxManifest.xml.in
@@ -3,9 +3,11 @@
xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
xmlns:uap5="http://schemas.microsoft.com/appx/manifest/uap/windows10/5"
+ xmlns:uap10="http://schemas.microsoft.com/appx/manifest/uap/windows10/10"
+ xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10"
xmlns:desktop4="http://schemas.microsoft.com/appx/manifest/desktop/windows10/4"
xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
- IgnorableNamespaces="uap uap5 desktop4 rescap">
+ IgnorableNamespaces="uap uap5 uap10 desktop desktop4 rescap">
VCore UWP VPN Demo
@@ -19,7 +21,7 @@
-
+
-
+
-
-
-
-
-
-
-
-
-
+
+
+
+
diff --git a/example/windows-uwp/README.md b/example/windows-uwp/README.md
index 5b53153..93d5372 100644
--- a/example/windows-uwp/README.md
+++ b/example/windows-uwp/README.md
@@ -2,7 +2,7 @@
本示例演示如何把 VCore 的 `Windows.Networking.Vpn` Provider、每会话完全信任运行时和一个最小命令行前台打进同一个 MSIX，并通过 `VCoreWindowsVpnInvoke` 创建、连接、查询和停止系统 VPN。
-> 这里的 “UWP” 指 Windows 的 UWP VPN Provider 模型。VCore **不支持纯 AppContainer 前台直接承载完整集成**：profile/snapshot 管理和 Session Host 激活必须由同包的完全信任进程执行。已有纯 UWP UI 时，应增加一个完全信任 broker；不要从 UWP UI 直接调用桥接接口。
+> 这里的 “UWP” 指 Windows 的 UWP VPN Provider 模型。VCore **不支持纯 AppContainer 前台直接承载完整集成**：profile/snapshot 管理必须由同包的完全信任进程执行，Session Host 则由 Provider 激活。已有纯 UWP UI 时，应增加一个完全信任 broker；不要从 UWP UI 直接调用桥接接口。
## 最小架构
@@ -11,13 +11,13 @@ VCoreUwpDemo.exe（完全信任前台）
└─ VCoreWindowsVpnInvoke
├─ 发布不可变配置快照
├─ 创建/更新同包 VPN profile
- └─ 激活 SessionHost
-
-vcore-windows-session-host.exe（每次连接一个完全信任进程）
- └─ 完整 VCore：netstack / DNS / rules / outbounds
+ └─ ConnectProfileAsync
vcore-windows-vpn-host.exe + vcore.dll（AppContainer Provider）
- └─ VpnChannel / routes / DNS assignment / packet buffers / physical network
+ ├─ VpnChannel / routes / DNS assignment / packet buffers / physical network
+ └─ FullTrustProcessLauncher
+ └─ vcore-windows-session-host.exe（每次连接一个完全信任进程）
+ └─ 完整 VCore：netstack / DNS / rules / outbounds
```
前台退出不会停止 VPN。Provider 或 Session Host 退出、管道损坏、非法 frame 或物理网络变化会失败关闭当前 VPN。
@@ -180,17 +180,17 @@ VCore 会校验 YAML、发布 `vcore-session-v2:` 内容寻址 Session Snapshot
| Manifest 项 | 必须值/规则 |
| --- | --- |
-| Session Host Application Id | `SessionHost` |
-| Session Host executable | `vcore-windows-session-host.exe` |
+| Application 数量 | `1` |
+| Session Host extension | `windows.fullTrustProcess` / `vcore-windows-session-host.exe` |
| Provider executable | `vcore-windows-vpn-host.exe` |
-| Provider Application EntryPoint | `VCore.VpnHost.App` |
| Provider background EntryPoint | `VCore.VpnBackgroundTask` |
+| Provider runtime / trust | `windowsApp` / `appContainer` |
| in-process server path | `vcore.dll` |
| activatable class | `VCore.VpnBackgroundTask`，`ThreadingModel="both"` |
| capabilities | `internetClientServer`、`privateNetworkClientServer`、`runFullTrust`、`networkingVpnProvider` |
| minimum desktop OS | `10.0.19042.0` |
-可以修改 identity、publisher、版本、前台 Application Id/EXE、显示名称、图标和 app execution alias。除非同步修改 VCore 源码，否则不要修改 `SessionHost` 和 `VCore.VpnBackgroundTask`。桥接还固定使用 profile 名 `VCore`，可选 StartupTask 固定使用 `VCoreStartup`；两者都按 package family 隔离。
+可以修改 identity、publisher、版本、主 Application Id/EXE、显示名称、图标和 app execution alias。不要删除 Session Host/Provider extensions 或修改 `VCore.VpnBackgroundTask`。桥接还固定使用 profile 名 `VCore`，可选 StartupTask 固定使用 `VCoreStartup`；两者都按 package family 隔离。
三项 VCore 文件必须位于 package 根目录：
diff --git a/readme/README.ru.md b/readme/README.ru.md
index 174ed85..481cffe 100644
--- a/readme/README.ru.md
+++ b/readme/README.ru.md
@@ -4,12 +4,13 @@
English · 简体中文 · Русский
-VCore — независимое клиентское прокси-ядро на Rust, не привязанное к конкретному хост-приложению. Через строгую YAML-конфигурацию и Invoke API v5 оно предоставляет граф прокси, DNS, правила маршрутизации, GeoData, HTTP listener, плоскость данных TUN и статистику трафика. Внутренняя ревизия схемы конфигурации — 12; она присутствует только в ответе `version` и `buildIdentity`, но не записывается в YAML.
+VCore — независимое клиентское прокси-ядро на Rust, не привязанное к конкретному хост-приложению. Через строгую YAML-конфигурацию и Invoke API v5 оно предоставляет граф прокси, статические группы `select`, DNS, правила маршрутизации, GeoData, HTTP listener, плоскость данных TUN и loopback Controller. Внутренняя ревизия схемы конфигурации — 13; она присутствует только в ответе `version` и `buildIdentity`, но не записывается в YAML.
## Возможности
- Исходящие подключения: VLESS + XHTTP + TLS/REALITY, SOCKS5 CONNECT/UDP ASSOCIATE, AnyTLS TCP/UoT и DIRECT.
- Цепочки прокси: `dialer-proxy` образует ориентированный ациклический граф произвольной длины. Если узел A указывает на B, физический путь имеет вид `client -> B -> A -> target`.
+- Группы прокси: статические группы `select` сохраняют порядок участников; участниками могут быть конкретные узлы, вложенные группы, `DIRECT` и `REJECT`. Выбор текущей session можно менять через Controller. `dialer-proxy` по-прежнему принимает только конкретный узел.
- Маршрутизация: последовательно применяются `DOMAIN`, `DOMAIN-SUFFIX`, `DOMAIN-KEYWORD`, `GEOSITE`, `GEOIP`, `IP-CIDR`, `IP-CIDR6`, `DST-PORT`, `NETWORK` и завершающее правило `MATCH`.
- DNS: UDP/TCP nameserver с фиксированным IP, явный outbound, последовательные policy/failover, typed/opaque cache, singleflight и перехват UDP/TCP-порта 53 в TUN.
- TUN: raw IPv4/IPv6, TCP/UDP, локальные ответы ICMPv4/ICMPv6 Echo, HTTP/TLS/QUIC sniffer и четыре счётчика трафика на session.
@@ -23,9 +24,10 @@ VCore — независимое клиентское прокси-ядро на
- Размер YAML ограничен 256 KiB; неизвестные поля, anchors, aliases, пользовательские tags и устаревшие структуры отклоняются.
- На верхнем уровне должен быть хотя бы один proxy, а также `port` или включённый `tun`.
-- Значения proxy `name` чувствительны к регистру и уникальны; все ссылки должны существовать, а граф прокси должен быть ациклическим.
-- `rules` обязателен и должен завершаться ровно одним `MATCH`, указывающим на реальное имя proxy.
-- `DIRECT` и `REJECT` — встроенные actions; любой другой action должен быть реальным именем proxy.
+- Имена proxy и proxy group используют общее пространство имён с точным совпадением и учётом регистра. Имя занимает 1–64 байта UTF-8; запрещены окружающие Unicode-пробелы, управляющие символы, `, # / ? & = % \`, `.` и `..`, а `DIRECT`, `REJECT` и `RULES` зарезервированы. Внутренние обычные пробелы, CJK и emoji разрешены.
+- `proxy-groups` принимает только `select`. Порядок и повторы участников сохраняются; без `default-selected` выбирается первый участник, а явное значение должно быть прямым участником. Цепочки proxy и вложенные группы должны быть ациклическими.
+- `rules` обязателен и должен завершаться ровно одним `MATCH`, указывающим на настроенный proxy node или proxy group.
+- `DIRECT` и `REJECT` — встроенные actions и участники групп; любой другой route target должен быть настроенным proxy node или proxy group. `RULES` зарезервирован только для DNS.
- Конфигурация передаётся inline через `configYaml` / `configYamls`; VCore не читает пути конфигурации хоста.
- Runtime-значения, включая Controller, TUN fd, порт и secret Controller, создаются хостом и не сохраняются в пользовательском RAW YAML.
@@ -57,14 +59,18 @@ initialize
`instanceId` — generation token, который не используется повторно текущим runtime. Команды одного экземпляра завершаются fail-fast, если другая команда уже выполняется; чистые вызовы `validateConfig` могут выполняться параллельно. Полный envelope, методы, владение fd и контракт Android protect описаны в [`docs/invoke-api.md`](../docs/invoke-api.md).
-Трафик TUN запрашивается через session-local loopback Controller:
+Состояние runtime доступно через session-local loopback Controller:
```http
GET /traffic
+GET /group
+GET /group/{name}
+GET /proxies/{name}
+PUT /proxies/{name}
Authorization: Bearer
```
-Ответ представляет собой одноразовый snapshot `up/down/upTotal/downTotal`, а не непрерывный stream. Подробности — в [`docs/controller-api.md`](../docs/controller-api.md).
+`GET /traffic` возвращает одноразовый TUN snapshot `up/down/upTotal/downTotal`. Конечные точки групп читают и изменяют выбранного прямого участника статической группы `select`; успешное изменение влияет только на новые физические TCP-, UDP- и DNS-transports текущей session. Оно не переносит существующие соединения, UDP associations, состояние DNS или pooled TCP transports и не выполняет автоматический failover. Controller, управляющий группами, требует один Bearer secret для всех маршрутов и может работать без TUN. Подробности — в [`docs/controller-api.md`](../docs/controller-api.md).
## Платформы
@@ -103,7 +109,7 @@ TCP sessions, обычные UDP associations, half-open connections, outbound h
- [AnyTLS outbound](../docs/anytls.md)
- [Клиентский протокол REALITY V1](../docs/reality-wire-protocol.md)
- [Зависимость rustls REALITY и требования к выпуску](../docs/rustls-reality-release.md)
-- [Controller трафика TUN](../docs/controller-api.md)
+- [Runtime Controller](../docs/controller-api.md)
- [ICMP и DNS в TUN](../docs/tun-icmp-dns.md)
- [Правила и assets GeoData](../docs/geodata.md)
- [Платформенный слой TUN](../docs/tun-platform.md)
diff --git a/readme/README.zh_CN.md b/readme/README.zh_CN.md
index 7b3e8ff..4ea5862 100644
--- a/readme/README.zh_CN.md
+++ b/readme/README.zh_CN.md
@@ -4,12 +4,13 @@
English · 简体中文 · Русский
-VCore 是独立且不绑定特定宿主应用的 Rust 客户端代理 core。它通过严格 YAML 配置和 Invoke API v5 提供代理图、DNS、规则、GeoData、HTTP listener、TUN 数据面与流量统计。内部配置 schema revision 为 12；revision 只出现在 `version` 响应和 `buildIdentity` 中，不写入 YAML。
+VCore 是独立且不绑定特定宿主应用的 Rust 客户端代理 core。它通过严格 YAML 配置和 Invoke API v5 提供代理图、静态 `select` 代理组、DNS、规则、GeoData、HTTP listener、TUN 数据面与回环 Controller。内部配置 schema revision 为 13；revision 只出现在 `version` 响应和 `buildIdentity` 中，不写入 YAML。
## 能力
- Outbound：VLESS + XHTTP + TLS/REALITY、SOCKS5 CONNECT/UDP ASSOCIATE、AnyTLS TCP/UoT、DIRECT。
- 代理链：`dialer-proxy` 组成任意长度的有向无环图；节点 A 指向 B 时，物理路径为 `client -> B -> A -> target`。
+- 代理组：静态 `select` 组保留有序成员，可包含具体节点、嵌套组、`DIRECT` 与 `REJECT`；当前 session 的选择可通过 Controller 实时修改。`dialer-proxy` 仍然只能引用具体节点。
- 路由：顺序执行 `DOMAIN`、`DOMAIN-SUFFIX`、`DOMAIN-KEYWORD`、`GEOSITE`、`GEOIP`、`IP-CIDR`、`IP-CIDR6`、`DST-PORT`、`NETWORK` 和最终 `MATCH`。
- DNS：固定 IP 的 UDP/TCP nameserver、显式出口、顺序 policy/failover、typed/opaque cache、singleflight、TUN UDP/TCP 53 劫持。
- TUN：raw IPv4/IPv6、TCP/UDP、ICMPv4/ICMPv6 Echo 本地响应、HTTP/TLS/QUIC sniffer、每 session 四字段流量统计。
@@ -23,9 +24,10 @@ VCore 是独立且不绑定特定宿主应用的 Rust 客户端代理 core。它
- YAML 最大 256 KiB，拒绝未知字段、anchor、alias、自定义 tag 和历史结构。
- 顶层至少包含一个 proxy，以及 `port` 或启用的 `tun`。
-- proxy `name` 大小写敏感且唯一；引用必须存在，代理图必须无环。
-- `rules` 必填，必须恰好以一个指向实际 proxy name 的 `MATCH` 结束。
-- `DIRECT` 和 `REJECT` 是内置 action；其他 action 必须是实际 proxy name。
+- proxy 与 proxy group 定义名共享一个精确且大小写敏感的命名空间。名称为 1–64 UTF-8 字节，拒绝首尾 Unicode 空白、控制字符、`, # / ? & = % \`、`.`、`..`，并保留 `DIRECT`、`REJECT` 与 `RULES`；内部普通空格、CJK 和 emoji 可用。
+- `proxy-groups` 只接受 `select`。成员顺序与重复项均保留；省略 `default-selected` 时选择第一项，显式值必须是直接成员。代理链和嵌套组分别必须无环。
+- `rules` 必填，必须恰好以一个指向已配置 proxy node 或 proxy group 的 `MATCH` 结束。
+- `DIRECT` 和 `REJECT` 是内置 action 与组成员；其他 route target 必须是已配置 proxy node 或 proxy group。`RULES` 只由 DNS 保留。
- 配置通过 `configYaml` / `configYamls` 内联交付；VCore 不读取宿主配置路径。
- Controller、TUN fd、Controller 端口/secret 等运行时值由宿主生成，不进入用户保存的 RAW YAML。
@@ -57,14 +59,18 @@ initialize
`instanceId` 是当前 runtime 内不可复用的 generation token。同实例命令 fail-fast；纯 `validateConfig` 可并发执行。完整 envelope、method、fd 所有权和 Android protect 契约见 [`docs/invoke-api.md`](../docs/invoke-api.md)。
-TUN 流量通过 session-local loopback Controller 查询：
+运行时状态通过 session-local loopback Controller 访问：
```http
GET /traffic
+GET /group
+GET /group/{name}
+GET /proxies/{name}
+PUT /proxies/{name}
Authorization: Bearer
```
-响应为一次 `up/down/upTotal/downTotal` snapshot，不是持续 stream。详见 [`docs/controller-api.md`](../docs/controller-api.md)。
+`GET /traffic` 返回一次 TUN `up/down/upTotal/downTotal` snapshot。代理组端点读取或修改静态 `select` 组的当前直接成员；成功切换只影响当前 session 后续新建的物理 TCP、UDP 与 DNS transport，不迁移既有连接、UDP association、DNS 状态或 TCP 连接池，也不自动故障转移。Controller 管理代理组时，全部路由必须共用一个 Bearer secret，并且可以不启用 TUN。详见 [`docs/controller-api.md`](../docs/controller-api.md)。
## 平台
@@ -103,7 +109,7 @@ TCP session、普通 UDP association、half-open、outbound handshake 和 active
- [AnyTLS 出站](../docs/anytls.md)
- [REALITY V1 客户端协议](../docs/reality-wire-protocol.md)
- [rustls REALITY 依赖与发布要求](../docs/rustls-reality-release.md)
-- [TUN 流量 Controller](../docs/controller-api.md)
+- [运行时 Controller](../docs/controller-api.md)
- [TUN ICMP 与 DNS](../docs/tun-icmp-dns.md)
- [GeoData 规则与资产](../docs/geodata.md)
- [TUN 平台层](../docs/tun-platform.md)
diff --git a/scripts/README.md b/scripts/README.md
index d6632f7..961a7ad 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -19,8 +19,8 @@ uv run --project scripts --locked vcore-scripts build windows
- Apple 命令只能在 macOS 运行，输出 `dist/apple/LibVCore.xcframework`。
- Android 命令在 macOS/Linux 运行，默认输出 `dist/android/{arm64-v8a,x86_64}/libvcore.so`。
-- Windows 命令只能在已安装 Visual Studio C++ 工具的 Windows 运行；命令从系统注册表读取原生 ARM64/x64 处理器架构，通过 `vswhere` 加载对应的 MSVC 环境，并输出 `dist/windows/` 下的 DLL、Provider Host 和 Session Host。
-- 所有构建都使用 `Cargo.lock`，并检查产物内的 Invoke API v5/config revision 12 身份。
+- Windows 命令只能在已安装 Visual Studio C++ 工具的 Windows 运行；命令从系统注册表读取原生 ARM64/x64 处理器架构，通过 `vswhere` 加载对应的 MSVC 环境，验证三项 PE 的 machine type 后输出 `dist/windows/` 下的 DLL、Provider Host、Session Host 和记录 package integration revision、架构及三项 SHA-256 的 `vcore-windows-artifacts.json`。
+- 所有构建都使用 `Cargo.lock`，并检查产物内的 Invoke API v5/config revision 13 身份。
Apple/Android 继续接受现有环境变量：
diff --git a/scripts/src/vcore_scripts/builds.py b/scripts/src/vcore_scripts/builds.py
index 197ed67..269cf96 100644
--- a/scripts/src/vcore_scripts/builds.py
+++ b/scripts/src/vcore_scripts/builds.py
@@ -1,6 +1,7 @@
from __future__ import annotations
import hashlib
+import json
import locale
import mmap
import os
@@ -12,7 +13,7 @@
CORE_DIR = Path(__file__).resolve().parents[3]
EXPECTED_IDENTITY = (
- b"VCore;engine=rust;coreVersion=0.1.0;invokeApiVersion=5;configVersion=12"
+ b"VCore;engine=rust;coreVersion=0.1.0;invokeApiVersion=5;configVersion=13"
)
DEFAULT_FEATURES = "ffi,tun,inbound-http,outbound-vless"
@@ -77,6 +78,25 @@ def _cargo_build(
)
+def _require_windows_architecture(artifact: Path, architecture: str) -> None:
+ with artifact.open("rb") as file:
+ if file.read(2) != b"MZ":
+ raise RuntimeError(f"invalid Windows PE artifact: {artifact}")
+ file.seek(0x3C)
+ offset = file.read(4)
+ if len(offset) != 4:
+ raise RuntimeError(f"invalid Windows PE artifact: {artifact}")
+ file.seek(int.from_bytes(offset, "little"))
+ if file.read(4) != b"PE\0\0":
+ raise RuntimeError(f"invalid Windows PE artifact: {artifact}")
+ machine = file.read(2)
+ if len(machine) != 2:
+ raise RuntimeError(f"invalid Windows PE artifact: {artifact}")
+ expected = {"arm64": 0xAA64, "x64": 0x8664}[architecture]
+ if int.from_bytes(machine, "little") != expected:
+ raise RuntimeError(f"VCore Windows artifact has wrong architecture: {artifact}")
+
+
def _require_identity(artifact: Path, platform_name: str) -> None:
found = False
if artifact.stat().st_size:
@@ -352,6 +372,9 @@ def build_windows() -> None:
if os.name != "nt":
raise RuntimeError("Windows artifacts must be built on Windows")
architecture = _windows_architecture()
+ output = CORE_DIR / "dist" / "windows" / architecture
+ shutil.rmtree(output, ignore_errors=True)
+ output.mkdir(parents=True)
targets = {
"arm64": "aarch64-pc-windows-msvc",
"x64": "x86_64-pc-windows-msvc",
@@ -378,14 +401,29 @@ def build_windows() -> None:
"vcore-windows-vpn-host.exe",
"vcore-windows-session-host.exe",
]
+ for name in artifacts:
+ _require_windows_architecture(release / name, architecture)
_require_identity(release / "vcore.dll", "Windows")
- output = CORE_DIR / "dist" / "windows" / architecture
- shutil.rmtree(output, ignore_errors=True)
- output.mkdir(parents=True)
for name in artifacts:
shutil.copy2(release / name, output / name)
+ digests = {}
for name in artifacts:
artifact = output / name
with artifact.open("rb") as file:
- digest = hashlib.file_digest(file, "sha256").hexdigest()
- print(f"{digest} {artifact}")
+ digests[name] = hashlib.file_digest(file, "sha256").hexdigest()
+ print(f"{digests[name]} {artifact}")
+ (output / "vcore-windows-artifacts.json").write_text(
+ json.dumps(
+ {
+ "formatVersion": 1,
+ "windowsPackageIntegrationRevision": 2,
+ "architecture": architecture,
+ "buildIdentity": EXPECTED_IDENTITY.decode("ascii"),
+ "artifacts": digests,
+ },
+ indent=2,
+ sort_keys=True,
+ )
+ + "\n",
+ encoding="utf-8",
+ )
diff --git a/scripts/tests/test_scripts.py b/scripts/tests/test_scripts.py
index e9819ea..2e58a45 100644
--- a/scripts/tests/test_scripts.py
+++ b/scripts/tests/test_scripts.py
@@ -3,6 +3,7 @@
import json
import tempfile
import unittest
+import xml.etree.ElementTree as ET
from pathlib import Path
from types import SimpleNamespace
from unittest.mock import MagicMock, patch
@@ -17,6 +18,16 @@
from vcore_scripts.tun2socks import derive_xray_config
+def _windows_pe(machine: int) -> bytes:
+ contents = bytearray(512)
+ contents[:2] = b"MZ"
+ contents[0x3C:0x40] = (0x80).to_bytes(4, "little")
+ contents[0x80:0x84] = b"PE\0\0"
+ contents[0x84:0x86] = machine.to_bytes(2, "little")
+ contents[0x100 : 0x100 + len(EXPECTED_IDENTITY)] = EXPECTED_IDENTITY
+ return bytes(contents)
+
+
class ScriptTest(unittest.TestCase):
def test_cli_dispatches_windows_build_without_architecture(self):
with patch("vcore_scripts.cli.build_windows") as build:
@@ -39,6 +50,35 @@ def test_windows_architecture_uses_native_processor_registry(self):
key, "PROCESSOR_ARCHITECTURE"
)
+ def test_windows_example_uses_one_application_with_isolated_hosts(self):
+ root = ET.parse(
+ builds.CORE_DIR / "example/windows-uwp/AppxManifest.xml.in"
+ ).getroot()
+ foundation = "http://schemas.microsoft.com/appx/manifest/foundation/windows10"
+ desktop = "http://schemas.microsoft.com/appx/manifest/desktop/windows10"
+ uap10 = "http://schemas.microsoft.com/appx/manifest/uap/windows10/10"
+ applications = root.findall(
+ f"{{{foundation}}}Applications/{{{foundation}}}Application"
+ )
+
+ self.assertEqual(len(applications), 1)
+ self.assertFalse(
+ any("AppListEntry" in element.attrib for element in root.iter())
+ )
+ extensions = applications[0].find(f"{{{foundation}}}Extensions")
+ full_trust = extensions.find(
+ f"{{{desktop}}}Extension[@Category='windows.fullTrustProcess']"
+ )
+ provider = extensions.find(
+ f"{{{foundation}}}Extension[@Category='windows.backgroundTasks']"
+ )
+ self.assertEqual(
+ full_trust.attrib["Executable"], "vcore-windows-session-host.exe"
+ )
+ self.assertEqual(provider.attrib["Executable"], "vcore-windows-vpn-host.exe")
+ self.assertEqual(provider.attrib[f"{{{uap10}}}RuntimeBehavior"], "windowsApp")
+ self.assertEqual(provider.attrib[f"{{{uap10}}}TrustLevel"], "appContainer")
+
def test_android_target_mapping_is_strict(self):
self.assertEqual(
_android_target("aarch64-linux-android", "24"),
@@ -61,12 +101,13 @@ def test_windows_release_build_uses_production_features_and_checks_identity(self
root = Path(directory)
release = root / "target/aarch64-pc-windows-msvc/release"
release.mkdir(parents=True)
- for name in (
+ artifacts = (
"vcore.dll",
"vcore-windows-vpn-host.exe",
"vcore-windows-session-host.exe",
- ):
- (release / name).write_bytes(EXPECTED_IDENTITY)
+ )
+ for name in artifacts:
+ (release / name).write_bytes(_windows_pe(0xAA64))
with (
patch.object(builds, "CORE_DIR", root),
@@ -92,7 +133,43 @@ def test_windows_release_build_uses_production_features_and_checks_identity(self
"--bins",
],
)
- (release / "vcore.dll").write_bytes(b"wrong")
+ manifest = json.loads(
+ (
+ root / "dist/windows/arm64/vcore-windows-artifacts.json"
+ ).read_text()
+ )
+ expected_digest = (
+ "93dd534a99e69369e9dc435101dce44d5b0be4fb43c82abec500e1bb4fb88444"
+ )
+ self.assertEqual(
+ manifest,
+ {
+ "architecture": "arm64",
+ "artifacts": {
+ "vcore-windows-session-host.exe": expected_digest,
+ "vcore-windows-vpn-host.exe": expected_digest,
+ "vcore.dll": expected_digest,
+ },
+ "buildIdentity": EXPECTED_IDENTITY.decode("ascii"),
+ "formatVersion": 1,
+ "windowsPackageIntegrationRevision": 2,
+ },
+ )
+
+ provider = release / "vcore-windows-vpn-host.exe"
+ provider.write_bytes(_windows_pe(0x8664))
+ with self.assertRaisesRegex(RuntimeError, "wrong architecture"):
+ builds.build_windows()
+ self.assertFalse(
+ (root / "dist/windows/arm64/vcore-windows-artifacts.json").exists()
+ )
+
+ provider.write_bytes(_windows_pe(0xAA64))
+ dll = bytearray(_windows_pe(0xAA64))
+ dll[0x100 : 0x100 + len(EXPECTED_IDENTITY)] = bytes(
+ len(EXPECTED_IDENTITY)
+ )
+ (release / "vcore.dll").write_bytes(dll)
with self.assertRaisesRegex(RuntimeError, "incompatible Rust identity"):
builds.build_windows()
diff --git a/src/config/measure.rs b/src/config/measure.rs
index 76b8b39..c684fb1 100644
--- a/src/config/measure.rs
+++ b/src/config/measure.rs
@@ -137,6 +137,7 @@ proxies:
"geo-auto-update: false",
"configVersion: 9",
"default-proxy: proxy",
+ "proxy-groups: []",
] {
let yaml = NODE.replacen("proxies:", &format!("{extra}\nproxies:"), 1);
assert!(
diff --git a/src/config/mod.rs b/src/config/mod.rs
index 8517311..4cc8ab8 100644
--- a/src/config/mod.rs
+++ b/src/config/mod.rs
@@ -1,7 +1,7 @@
//! Strict parsing for the current VCore YAML configuration.
use std::{
- collections::HashMap,
+ collections::{HashMap, VecDeque},
net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr},
str::FromStr,
};
@@ -40,7 +40,8 @@ pub const GEO_UPDATE_INTERVAL_HOURS: u64 = 24;
pub struct Config {
pub ipv6: bool,
pub proxies: Vec,
- pub default_proxy: ProxyId,
+ pub proxy_groups: Vec,
+ pub default_route_target: RouteTargetId,
pub geodata_update: Option,
pub external_controller: Option,
pub inbounds: Vec,
@@ -153,7 +154,7 @@ pub enum DnsTransport {
pub enum DnsRoute {
Direct,
Rules,
- Proxy(ProxyId),
+ Route(RouteTargetId),
}
#[derive(Debug, Clone, PartialEq, Eq)]
@@ -178,7 +179,7 @@ pub enum RuleKind {
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RuleAction {
- Proxy(ProxyId),
+ Route(RouteTargetId),
Direct,
Reject,
}
@@ -204,6 +205,53 @@ impl ProxyId {
type ProxyIdsByTag = HashMap;
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct ProxyGroupId(usize);
+
+impl ProxyGroupId {
+ #[must_use]
+ pub const fn new(index: usize) -> Option {
+ Some(Self(index))
+ }
+
+ #[must_use]
+ pub const fn index(self) -> usize {
+ self.0
+ }
+
+ fn from_index(index: usize) -> Self {
+ Self(index)
+ }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum RouteTargetId {
+ Proxy(ProxyId),
+ Group(ProxyGroupId),
+}
+
+type RouteTargetsByName = HashMap;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ProxyGroupMemberTarget {
+ Route(RouteTargetId),
+ Direct,
+ Reject,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProxyGroupMemberConfig {
+ pub name: String,
+ pub target: ProxyGroupMemberTarget,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SelectProxyGroupConfig {
+ pub name: String,
+ pub members: Vec,
+ pub initial_member: usize,
+}
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct IpCidr {
pub network: IpAddr,
@@ -434,11 +482,32 @@ struct RawVCoreConfig {
#[serde(default, deserialize_with = "deserialize_present_option")]
sniffer: Option,
proxies: Vec,
+ #[serde(
+ rename = "proxy-groups",
+ default,
+ deserialize_with = "deserialize_non_null_vec"
+ )]
+ proxy_groups: Vec,
#[serde(default, deserialize_with = "deserialize_present_option")]
dns: Option,
rules: Vec,
}
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct RawProxyGroup {
+ name: String,
+ #[serde(rename = "type")]
+ kind: String,
+ proxies: Vec,
+ #[serde(
+ rename = "default-selected",
+ default,
+ deserialize_with = "deserialize_present_option"
+ )]
+ default_selected: Option,
+}
+
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct RawGeoDataUrls {
@@ -735,6 +804,15 @@ where
T::deserialize(deserializer).map(Some)
}
+fn deserialize_non_null_vec<'de, D, T>(deserializer: D) -> std::result::Result, D::Error>
+where
+ D: Deserializer<'de>,
+ T: Deserialize<'de>,
+{
+ Option::>::deserialize(deserializer)?
+ .ok_or_else(|| serde::de::Error::custom("sequence must not be null"))
+}
+
impl Config {
pub fn parse_yaml(input: &[u8]) -> Result {
if input.len() > MAX_CONFIG_BYTES {
@@ -784,8 +862,6 @@ impl RawVCoreConfig {
if tun.mtu != default_mtu() {
return invalid("TUN only supports mtu: 1500");
}
- let external_controller =
- normalize_external_controller(self.external_controller, self.secret, tun.enable)?;
if self.port.is_none() && !tun.enable {
return invalid("configuration requires port or tun.enable: true");
}
@@ -797,15 +873,28 @@ impl RawVCoreConfig {
if self.proxies.is_empty() {
return invalid("proxies must contain at least 1 entry");
}
- let (proxies, proxy_ids) = normalize_proxy_graph(self.proxies)?;
- let default_proxy = derive_default_proxy_from_rules(&self.rules, &proxy_ids)?;
+ let (raw_proxy_groups, proxy_group_ids) =
+ normalize_proxy_group_declarations(self.proxy_groups)?;
+ let (proxies, proxy_ids) =
+ normalize_proxy_graph_with_groups(self.proxies, &proxy_group_ids)?;
+ let route_targets = collect_route_targets(&proxy_ids, &proxy_group_ids);
+ let proxy_groups = normalize_proxy_groups(raw_proxy_groups, &route_targets)?;
+ let default_route_target =
+ derive_default_route_target_from_rules(&self.rules, &route_targets)?;
+ let external_controller = normalize_external_controller(
+ self.external_controller,
+ self.secret,
+ tun.enable,
+ !proxy_groups.is_empty(),
+ )?;
let mut dns = self
.dns
- .map_or_else(DnsConfig::disabled, |dns| dns.normalize(&proxy_ids))?;
+ .map_or_else(DnsConfig::disabled, |dns| dns.normalize(&route_targets))?;
dns.ipv6 &= self.ipv6;
- let rules = normalize_rules(self.rules, &proxy_ids)?;
+ let rules = normalize_rules(self.rules, &route_targets)?;
drop(proxy_ids);
+ drop(route_targets);
let mut inbounds = Vec::with_capacity(2);
if let (Some(port), Some((username, password))) = (self.port, http_authentication) {
@@ -828,7 +917,8 @@ impl RawVCoreConfig {
Ok(Config {
ipv6: self.ipv6,
proxies,
- default_proxy,
+ proxy_groups,
+ default_route_target,
geodata_update,
external_controller,
inbounds,
@@ -845,6 +935,7 @@ fn normalize_external_controller(
listen: Option,
secret: Option,
tun_enabled: bool,
+ has_proxy_groups: bool,
) -> Result> {
let Some(listen) = listen else {
if secret.is_some() {
@@ -852,8 +943,11 @@ fn normalize_external_controller(
}
return Ok(None);
};
- if !tun_enabled {
- return invalid("external-controller requires tun.enable: true");
+ if !tun_enabled && !has_proxy_groups {
+ return invalid("external-controller requires tun.enable: true or proxy-groups");
+ }
+ if has_proxy_groups && secret.is_none() {
+ return invalid("secret is required when external-controller manages proxy-groups");
}
let listen = listen.parse::().map_err(|_| {
VCoreError::InvalidConfig(
@@ -1162,6 +1256,13 @@ fn validate_proxy_graph(
fn normalize_proxy_graph(
raw_proxies: Vec,
+) -> Result<(Vec, ProxyIdsByTag)> {
+ normalize_proxy_graph_with_groups(raw_proxies, &HashMap::new())
+}
+
+fn normalize_proxy_graph_with_groups(
+ raw_proxies: Vec,
+ proxy_group_ids: &HashMap,
) -> Result<(Vec, ProxyIdsByTag)> {
if raw_proxies.is_empty() {
return invalid("proxies must contain at least 1 entry");
@@ -1172,6 +1273,12 @@ fn normalize_proxy_graph(
.collect::>>()?;
let mut proxy_ids = ProxyIdsByTag::with_capacity(pending.len());
for (index, proxy) in pending.iter().enumerate() {
+ if proxy_group_ids.contains_key(&proxy.tag) {
+ return invalid(format!(
+ "route target name `{}` is used by both a proxy and a proxy group",
+ proxy.tag
+ ));
+ }
if proxy_ids
.insert(proxy.tag.clone(), ProxyId::from_index(index))
.is_some()
@@ -1186,6 +1293,12 @@ fn normalize_proxy_graph(
.dialer_proxy
.as_deref()
.map(|tag| {
+ if proxy_group_ids.contains_key(tag) {
+ return invalid(format!(
+ "proxy `{}` dialer-proxy `{tag}` must reference a concrete proxy, not a proxy group",
+ proxy.tag
+ ));
+ }
proxy_ids.get(tag).copied().ok_or_else(|| {
VCoreError::InvalidConfig(format!(
"proxy `{}` dialer-proxy `{tag}` does not reference a configured proxy name",
@@ -1211,6 +1324,152 @@ fn normalize_proxy_graph(
Ok((proxies, proxy_ids))
}
+fn normalize_proxy_group_declarations(
+ raw_groups: Vec,
+) -> Result<(Vec, HashMap)> {
+ let mut group_ids = HashMap::with_capacity(raw_groups.len());
+ for (index, group) in raw_groups.iter().enumerate() {
+ if group.kind != "select" {
+ return invalid(format!(
+ "proxy group `{}` type must be exactly `select`",
+ group.name
+ ));
+ }
+ validate_route_target_definition_name(&group.name, "proxy group name")?;
+ if group.proxies.is_empty() {
+ return invalid(format!(
+ "proxy group `{}` proxies must contain at least 1 entry",
+ group.name
+ ));
+ }
+ if group_ids
+ .insert(group.name.clone(), ProxyGroupId::from_index(index))
+ .is_some()
+ {
+ return invalid(format!("duplicate proxy group name `{}`", group.name));
+ }
+ }
+ Ok((raw_groups, group_ids))
+}
+
+fn collect_route_targets(
+ proxy_ids: &ProxyIdsByTag,
+ proxy_group_ids: &HashMap,
+) -> RouteTargetsByName {
+ let mut targets = RouteTargetsByName::with_capacity(proxy_ids.len() + proxy_group_ids.len());
+ targets.extend(
+ proxy_ids
+ .iter()
+ .map(|(name, id)| (name.clone(), RouteTargetId::Proxy(*id))),
+ );
+ targets.extend(
+ proxy_group_ids
+ .iter()
+ .map(|(name, id)| (name.clone(), RouteTargetId::Group(*id))),
+ );
+ targets
+}
+
+fn normalize_proxy_groups(
+ raw_groups: Vec,
+ route_targets: &RouteTargetsByName,
+) -> Result> {
+ let groups = raw_groups
+ .into_iter()
+ .map(|group| {
+ let members = group
+ .proxies
+ .into_iter()
+ .map(|name| {
+ validate_route_target_name(&name, "proxy group member")?;
+ let target = match name.as_str() {
+ "DIRECT" => ProxyGroupMemberTarget::Direct,
+ "REJECT" => ProxyGroupMemberTarget::Reject,
+ "RULES" => {
+ return invalid(format!(
+ "proxy group `{}` cannot use reserved DNS target `RULES` as a member",
+ group.name
+ ));
+ }
+ _ => route_targets
+ .get(&name)
+ .copied()
+ .map(ProxyGroupMemberTarget::Route)
+ .ok_or_else(|| {
+ VCoreError::InvalidConfig(format!(
+ "proxy group `{}` member `{name}` does not reference a configured proxy, proxy group, DIRECT, or REJECT",
+ group.name
+ ))
+ })?,
+ };
+ Ok(ProxyGroupMemberConfig { name, target })
+ })
+ .collect::>>()?;
+ let initial_member = match group.default_selected {
+ Some(default) => members
+ .iter()
+ .position(|member| member.name == default)
+ .ok_or_else(|| {
+ VCoreError::InvalidConfig(format!(
+ "proxy group `{}` default-selected `{default}` must name a direct member",
+ group.name
+ ))
+ })?,
+ None => 0,
+ };
+ Ok(SelectProxyGroupConfig {
+ name: group.name,
+ members,
+ initial_member,
+ })
+ })
+ .collect::>>()?;
+ validate_proxy_group_dag(&groups)?;
+ Ok(groups)
+}
+
+fn validate_proxy_group_dag(groups: &[SelectProxyGroupConfig]) -> Result<()> {
+ let mut dependency_counts = vec![0_usize; groups.len()];
+ let mut dependents = vec![Vec::::new(); groups.len()];
+ for (group_index, group) in groups.iter().enumerate() {
+ for member in &group.members {
+ if let ProxyGroupMemberTarget::Route(RouteTargetId::Group(dependency)) = member.target {
+ let dependency_index = dependency.index();
+ dependency_counts[group_index] += 1;
+ dependents[dependency_index].push(group_index);
+ }
+ }
+ }
+
+ let mut ready = dependency_counts
+ .iter()
+ .enumerate()
+ .filter_map(|(index, count)| (*count == 0).then_some(index))
+ .collect::>();
+ let mut visited = 0_usize;
+ while let Some(group_index) = ready.pop_front() {
+ visited += 1;
+ for &dependent in &dependents[group_index] {
+ dependency_counts[dependent] -= 1;
+ if dependency_counts[dependent] == 0 {
+ ready.push_back(dependent);
+ }
+ }
+ }
+ if visited != groups.len() {
+ let blocked = dependency_counts
+ .iter()
+ .enumerate()
+ .filter_map(|(index, count)| (*count != 0).then_some(groups[index].name.as_str()))
+ .collect::>()
+ .join(", ");
+ return invalid(format!(
+ "proxy groups contain a circular member dependency involving: {blocked}"
+ ));
+ }
+ Ok(())
+}
+
impl RawOutbound {
fn normalize(self) -> Result {
let (tag, dialer_proxy, udp, protocol) = match self {
@@ -1277,9 +1536,9 @@ impl RawOutbound {
ProxyProtocol::AnyTls(normalize_anytls(server, port, password, sni)?),
),
};
- validate_proxy_tag(&tag)?;
+ validate_route_target_definition_name(&tag, "proxy name")?;
if let Some(dialer_proxy) = &dialer_proxy {
- validate_tag_syntax(dialer_proxy, "dialer-proxy")?;
+ validate_route_target_name(dialer_proxy, "dialer-proxy")?;
}
Ok(PendingProxyConfig {
tag,
@@ -1600,7 +1859,7 @@ impl DnsConfig {
}
impl RawDnsConfig {
- fn normalize(self, proxy_ids: &ProxyIdsByTag) -> Result {
+ fn normalize(self, route_targets: &RouteTargetsByName) -> Result {
if !self.enable {
if !self.nameserver.is_empty() || !self.nameserver_policies.is_empty() {
return invalid(
@@ -1624,10 +1883,13 @@ impl RawDnsConfig {
let nameservers = self
.nameserver
.iter()
- .map(|nameserver| parse_dns_nameserver(nameserver, proxy_ids, default_route))
+ .map(|nameserver| parse_dns_nameserver(nameserver, route_targets, default_route))
.collect::>>()?;
- let nameserver_policies =
- normalize_dns_nameserver_policies(self.nameserver_policies, proxy_ids, default_route)?;
+ let nameserver_policies = normalize_dns_nameserver_policies(
+ self.nameserver_policies,
+ route_targets,
+ default_route,
+ )?;
Ok(DnsConfig {
enable: true,
@@ -1640,7 +1902,7 @@ impl RawDnsConfig {
fn normalize_dns_nameserver_policies(
raw_policies: Vec,
- proxy_ids: &ProxyIdsByTag,
+ route_targets: &RouteTargetsByName,
default_route: DnsRoute,
) -> Result> {
if raw_policies.len() > MAX_DNS_NAMESERVER_POLICIES {
@@ -1697,7 +1959,7 @@ fn normalize_dns_nameserver_policies(
let nameservers = raw_policy
.nameservers
.iter()
- .map(|nameserver| parse_dns_nameserver(nameserver, proxy_ids, default_route))
+ .map(|nameserver| parse_dns_nameserver(nameserver, route_targets, default_route))
.collect::>>()?;
normalized.push(DnsNameserverPolicy {
geosite_codes: geosite_codes.into_boxed_slice(),
@@ -1709,13 +1971,13 @@ fn normalize_dns_nameserver_policies(
fn parse_dns_nameserver(
input: &str,
- proxy_ids: &ProxyIdsByTag,
+ route_targets: &RouteTargetsByName,
default_route: DnsRoute,
) -> Result {
let (endpoint, route) = match input.split_once('#') {
Some((endpoint, fragment)) => (
endpoint,
- parse_dns_route_fragment(input, fragment, proxy_ids)?,
+ parse_dns_route_fragment(input, fragment, route_targets)?,
),
None => (input, default_route),
};
@@ -1756,7 +2018,7 @@ fn parse_dns_nameserver(
fn parse_dns_route_fragment(
input: &str,
fragment: &str,
- proxy_ids: &ProxyIdsByTag,
+ route_targets: &RouteTargetsByName,
) -> Result {
if fragment.is_empty() {
return invalid(format!(
@@ -1771,13 +2033,13 @@ fn parse_dns_route_fragment(
match fragment {
"DIRECT" => Ok(DnsRoute::Direct),
"RULES" => Ok(DnsRoute::Rules),
- fragment => proxy_ids
+ fragment => route_targets
.get(fragment)
.copied()
- .map(DnsRoute::Proxy)
+ .map(DnsRoute::Route)
.ok_or_else(|| {
VCoreError::InvalidConfig(format!(
- "invalid DNS nameserver `{input}`; route fragment must be exactly DIRECT, RULES, or a configured proxy name"
+ "invalid DNS nameserver `{input}`; route fragment must be exactly DIRECT, RULES, or a configured proxy or proxy group name"
))
}),
}
@@ -1808,10 +2070,13 @@ fn parse_dns_endpoint(endpoint: &str) -> Option<(IpAddr, u16)> {
Some((endpoint.ip(), endpoint.port()))
}
-fn derive_default_proxy_from_rules(rules: &[String], proxy_ids: &ProxyIdsByTag) -> Result {
+fn derive_default_route_target_from_rules(
+ rules: &[String],
+ route_targets: &RouteTargetsByName,
+) -> Result {
let final_rule = rules.last().ok_or_else(|| {
VCoreError::InvalidConfig(
- "rules must end with MATCH targeting an exact proxy name".to_owned(),
+ "rules must end with MATCH targeting an exact proxy or proxy group name".to_owned(),
)
})?;
let fields = final_rule
@@ -1819,17 +2084,20 @@ fn derive_default_proxy_from_rules(rules: &[String], proxy_ids: &ProxyIdsByTag)
.map(trim_ascii_whitespace)
.collect::>();
if fields.len() != 2 || !fields[0].eq_ignore_ascii_case("MATCH") {
- return invalid("rules must end with MATCH targeting an exact proxy name");
+ return invalid("rules must end with MATCH targeting an exact proxy or proxy group name");
}
- proxy_ids.get(fields[1]).copied().ok_or_else(|| {
+ route_targets.get(fields[1]).copied().ok_or_else(|| {
VCoreError::InvalidConfig(format!(
- "final MATCH target must be an exact configured proxy name; found `{}`",
+ "final MATCH target must be an exact configured proxy or proxy group name; found `{}`",
fields[1]
))
})
}
-fn normalize_rules(rules: Vec, proxy_ids: &ProxyIdsByTag) -> Result> {
+fn normalize_rules(
+ rules: Vec,
+ route_targets: &RouteTargetsByName,
+) -> Result> {
if rules.is_empty() {
return invalid("rules must not be empty");
}
@@ -1853,7 +2121,7 @@ fn normalize_rules(rules: Vec, proxy_ids: &ProxyIdsByTag) -> Result, proxy_ids: &ProxyIdsByTag) -> Result Result {
+fn parse_rule(input: &str, route_targets: &RouteTargetsByName) -> Result {
if input.is_empty() {
return invalid("rule must not be empty");
}
@@ -1890,7 +2158,7 @@ fn parse_rule(input: &str, proxy_ids: &ProxyIdsByTag) -> Result {
require_rule_field_count(&fields, 2, "MATCH")?;
Ok(RuleSpec {
kind: RuleKind::Match,
- action: parse_rule_action(fields[1], proxy_ids)?,
+ action: parse_rule_action(fields[1], route_targets)?,
no_resolve: false,
})
}
@@ -1909,7 +2177,7 @@ fn parse_rule(input: &str, proxy_ids: &ProxyIdsByTag) -> Result {
};
Ok(RuleSpec {
kind,
- action: parse_rule_action(fields[2], proxy_ids)?,
+ action: parse_rule_action(fields[2], route_targets)?,
no_resolve: false,
})
}
@@ -1937,7 +2205,7 @@ fn parse_rule(input: &str, proxy_ids: &ProxyIdsByTag) -> Result {
};
Ok(RuleSpec {
kind,
- action: parse_rule_action(fields[2], proxy_ids)?,
+ action: parse_rule_action(fields[2], route_targets)?,
no_resolve,
})
}
@@ -1958,17 +2226,17 @@ fn require_rule_field_count(fields: &[&str], expected: usize, rule_type: &str) -
Ok(())
}
-fn parse_rule_action(action: &str, proxy_ids: &ProxyIdsByTag) -> Result {
+fn parse_rule_action(action: &str, route_targets: &RouteTargetsByName) -> Result {
match action {
"DIRECT" => Ok(RuleAction::Direct),
"REJECT" => Ok(RuleAction::Reject),
- tag => proxy_ids
+ tag => route_targets
.get(tag)
.copied()
- .map(RuleAction::Proxy)
+ .map(RuleAction::Route)
.ok_or_else(|| {
VCoreError::InvalidConfig(format!(
- "rule target must be exactly DIRECT, REJECT, or a configured proxy name; found `{action}`"
+ "rule target must be exactly DIRECT, REJECT, or a configured proxy or proxy group name; found `{action}`"
))
}),
}
@@ -2090,26 +2358,31 @@ fn parse_network(input: &str) -> Result {
}
}
-fn validate_tag_syntax(tag: &str, field: &str) -> Result<()> {
- let bytes = tag.as_bytes();
- if bytes.is_empty()
- || bytes.len() > 64
- || !bytes[0].is_ascii_alphanumeric()
- || !bytes[1..]
- .iter()
- .all(|byte| byte.is_ascii_alphanumeric() || matches!(*byte, b'.' | b'_' | b'-'))
+pub(crate) fn validate_route_target_name(name: &str, field: &str) -> Result<()> {
+ let mut characters = name.chars();
+ let first = characters.next();
+ let last = characters.next_back().or(first);
+ if name.is_empty()
+ || name.len() > 64
+ || first.is_some_and(char::is_whitespace)
+ || last.is_some_and(char::is_whitespace)
+ || name.chars().any(|character| {
+ character.is_control()
+ || matches!(character, ',' | '#' | '/' | '?' | '&' | '=' | '%' | '\\')
+ })
+ || matches!(name, "." | "..")
{
return invalid(format!(
- "{field} must match [A-Za-z0-9][A-Za-z0-9._-]{{0,63}}"
+ "{field} must be 1-64 UTF-8 bytes without surrounding whitespace, control characters, path separators, or reserved delimiters"
));
}
Ok(())
}
-fn validate_proxy_tag(tag: &str) -> Result<()> {
- validate_tag_syntax(tag, "proxy name")?;
- if matches!(tag, "DIRECT" | "REJECT" | "RULES") {
- return invalid(format!("proxy name `{tag}` is reserved"));
+fn validate_route_target_definition_name(name: &str, field: &str) -> Result<()> {
+ validate_route_target_name(name, field)?;
+ if matches!(name, "DIRECT" | "REJECT" | "RULES") {
+ return invalid(format!("{field} `{name}` is reserved"));
}
Ok(())
}
@@ -2352,6 +2625,14 @@ proxies:
format!("{}{SOCKS_PROXY_ENTRY}", current_yaml(fields))
}
+ fn with_proxy_groups(groups: &str, fields: &str) -> String {
+ current_yaml(fields).replacen(
+ "\nproxies:",
+ &format!("\nproxy-groups:\n{groups}\nproxies:"),
+ 1,
+ )
+ }
+
fn second_vless_entry() -> String {
CURRENT_PROXY
.strip_prefix("\nproxies:\n")
@@ -2433,7 +2714,10 @@ proxies:
assert_eq!(config.inbounds.len(), 2);
assert_eq!(config.proxies[0].tag, "proxy");
assert!(config.proxies[0].udp);
- assert_eq!(config.default_proxy, ProxyId::new(0).unwrap());
+ assert_eq!(
+ config.default_route_target,
+ RouteTargetId::Proxy(ProxyId::new(0).unwrap())
+ );
assert_eq!(first_vless(&config).address, "203.0.113.1");
assert!(matches!(
&first_vless(&config).security,
@@ -3319,7 +3603,10 @@ authentication:
#[test]
fn parses_the_strict_anytls_subset() {
let config = Config::parse_yaml(CURRENT_ANYTLS.as_bytes()).unwrap();
- assert_eq!(config.default_proxy, ProxyId::new(0).unwrap());
+ assert_eq!(
+ config.default_route_target,
+ RouteTargetId::Proxy(ProxyId::new(0).unwrap())
+ );
let proxy = &config.proxies[0];
assert_eq!(proxy.tag, "anytls-node");
assert!(!proxy.udp);
@@ -3356,7 +3643,10 @@ authentication:
" password: private-anytls-password\n dialer-proxy: socks-hop",
);
let config = Config::parse_yaml(yaml.as_bytes()).unwrap();
- assert_eq!(config.default_proxy, ProxyId::new(1).unwrap());
+ assert_eq!(
+ config.default_route_target,
+ RouteTargetId::Proxy(ProxyId::new(1).unwrap())
+ );
assert_eq!(
config.proxies[1].dialer_proxy,
ProxyId::new(0),
@@ -3703,7 +3993,7 @@ authentication:
config.rules,
[RuleSpec {
kind: RuleKind::Match,
- action: RuleAction::Proxy(ProxyId::new(0).unwrap()),
+ action: RuleAction::Route(RouteTargetId::Proxy(ProxyId::new(0).unwrap())),
no_resolve: false,
}]
);
@@ -3795,7 +4085,10 @@ authentication:
);
let config = Config::parse_yaml(yaml.as_bytes()).unwrap();
assert_eq!(config.proxies.len(), 2);
- assert_eq!(config.default_proxy, ProxyId::new(1).unwrap());
+ assert_eq!(
+ config.default_route_target,
+ RouteTargetId::Proxy(ProxyId::new(1).unwrap())
+ );
let ProxyProtocol::Socks5(socks5) = &config.proxies[1].protocol else {
panic!("expected SOCKS5 proxy");
};
@@ -3939,12 +4232,21 @@ authentication:
let config = Config::parse_yaml(yaml.as_bytes()).unwrap();
let first = ProxyId::new(0).unwrap();
let second = ProxyId::new(1).unwrap();
- assert_eq!(config.default_proxy, second);
+ assert_eq!(config.default_route_target, RouteTargetId::Proxy(second));
assert_eq!(config.proxies[0].dialer_proxy, Some(second));
assert_eq!(config.proxies[1].dialer_proxy, None);
- assert_eq!(config.rules[0].action, RuleAction::Proxy(first));
- assert_eq!(config.rules[1].action, RuleAction::Proxy(second));
- assert_eq!(config.rules[2].action, RuleAction::Proxy(second));
+ assert_eq!(
+ config.rules[0].action,
+ RuleAction::Route(RouteTargetId::Proxy(first))
+ );
+ assert_eq!(
+ config.rules[1].action,
+ RuleAction::Route(RouteTargetId::Proxy(second))
+ );
+ assert_eq!(
+ config.rules[2].action,
+ RuleAction::Route(RouteTargetId::Proxy(second))
+ );
let proxy_default = two_proxy_yaml(
"port: 1080
@@ -3956,12 +4258,186 @@ authentication:
config.rules,
[RuleSpec {
kind: RuleKind::Match,
- action: RuleAction::Proxy(first),
+ action: RuleAction::Route(RouteTargetId::Proxy(first)),
no_resolve: false,
}]
);
}
+ #[test]
+ fn normalizes_select_groups_in_declaration_order() {
+ let yaml = with_proxy_groups(
+ r#" - name: 主线路
+ type: select
+ proxies: [proxy, 备用线路, DIRECT, REJECT, proxy]
+ default-selected: 备用线路
+ - name: 备用线路
+ type: select
+ proxies: [proxy, proxy, DIRECT]
+ default-selected: proxy"#,
+ r#"port: 1080
+authentication:
+ - measure:secret
+dns:
+ enable: true
+ nameserver: ["tcp://1.1.1.1:53#主线路"]
+rules:
+ - DOMAIN-SUFFIX,example.com,备用线路
+ - MATCH,主线路"#,
+ );
+ let config = Config::parse_yaml(yaml.as_bytes()).unwrap();
+ let main = ProxyGroupId::new(0).unwrap();
+ let backup = ProxyGroupId::new(1).unwrap();
+
+ assert_eq!(config.proxy_groups.len(), 2);
+ assert_eq!(config.proxy_groups[0].name, "主线路");
+ assert_eq!(config.proxy_groups[0].initial_member, 1);
+ assert_eq!(
+ config.proxy_groups[0]
+ .members
+ .iter()
+ .map(|member| member.name.as_str())
+ .collect::>(),
+ ["proxy", "备用线路", "DIRECT", "REJECT", "proxy"]
+ );
+ assert_eq!(
+ config.proxy_groups[0].members[1].target,
+ ProxyGroupMemberTarget::Route(RouteTargetId::Group(backup))
+ );
+ assert_eq!(
+ config.proxy_groups[0].members[2].target,
+ ProxyGroupMemberTarget::Direct
+ );
+ assert_eq!(
+ config.proxy_groups[0].members[3].target,
+ ProxyGroupMemberTarget::Reject
+ );
+ assert_eq!(config.proxy_groups[1].initial_member, 0);
+ assert_eq!(
+ config.proxy_groups[1]
+ .members
+ .iter()
+ .map(|member| member.name.as_str())
+ .collect::>(),
+ ["proxy", "proxy", "DIRECT"]
+ );
+ assert_eq!(config.default_route_target, RouteTargetId::Group(main));
+ assert_eq!(
+ config.rules[0].action,
+ RuleAction::Route(RouteTargetId::Group(backup))
+ );
+ assert_eq!(
+ config.dns.nameservers[0].route,
+ DnsRoute::Route(RouteTargetId::Group(main))
+ );
+ }
+
+ #[test]
+ fn strictly_rejects_invalid_select_group_shapes_and_graphs() {
+ let fields = "port: 1080\nauthentication:\n - measure:secret\nrules:\n - MATCH,主线路";
+ for groups in [
+ r#" - name: 主线路
+ type: url-test
+ proxies: [proxy]"#,
+ r#" - name: 主线路
+ type: select
+ proxies: []"#,
+ r#" - name: 主线路
+ type: select
+ proxies: [proxy]
+ default-selected: missing"#,
+ r#" - name: 主线路
+ type: select
+ proxies: [missing]"#,
+ r#" - name: 主线路
+ type: select
+ proxies: [RULES]"#,
+ r#" - name: 主线路
+ type: select
+ proxies: [proxy]
+ url: https://example.com"#,
+ r#" - name: 主线路
+ type: select
+ proxies: [proxy]
+ default-selected: null"#,
+ ] {
+ let yaml = with_proxy_groups(groups, fields);
+ assert!(Config::parse_yaml(yaml.as_bytes()).is_err(), "{yaml}");
+ }
+
+ let cycle = with_proxy_groups(
+ r#" - name: 主线路
+ type: select
+ proxies: [备用线路]
+ - name: 备用线路
+ type: select
+ proxies: [主线路]"#,
+ fields,
+ );
+ let error = Config::parse_yaml(cycle.as_bytes()).unwrap_err();
+ assert!(error.to_string().contains("circular member dependency"));
+
+ let duplicate = with_proxy_groups(
+ r#" - name: 主线路
+ type: select
+ proxies: [proxy]
+ - name: 主线路
+ type: select
+ proxies: [DIRECT]"#,
+ fields,
+ );
+ assert!(Config::parse_yaml(duplicate.as_bytes()).is_err());
+
+ let shared_name = with_proxy_groups(
+ r#" - name: proxy
+ type: select
+ proxies: [DIRECT]"#,
+ "port: 1080\nauthentication:\n - measure:secret\nrules:\n - MATCH,proxy",
+ );
+ assert!(Config::parse_yaml(shared_name.as_bytes()).is_err());
+
+ let null_groups = current_yaml("port: 1080\nauthentication:\n - measure:secret").replacen(
+ "\nproxies:",
+ "\nproxy-groups: null\nproxies:",
+ 1,
+ );
+ assert!(Config::parse_yaml(null_groups.as_bytes()).is_err());
+ }
+
+ #[test]
+ fn keeps_dialer_proxy_node_only_and_secures_group_controller() {
+ let groups = r#" - name: 主线路
+ type: select
+ proxies: [proxy, DIRECT]"#;
+ let dialer_group = with_proxy_groups(
+ groups,
+ "port: 1080\nauthentication:\n - measure:secret\nrules:\n - MATCH,主线路",
+ )
+ .replacen(
+ " server: edge.example.com\n",
+ " dialer-proxy: 主线路\n server: edge.example.com\n",
+ 1,
+ );
+ let error = Config::parse_yaml(dialer_group.as_bytes()).unwrap_err();
+ assert!(error.to_string().contains("concrete proxy"), "{error}");
+
+ let no_controller = with_proxy_groups(
+ groups,
+ "port: 1080\nauthentication:\n - measure:secret\nrules:\n - MATCH,主线路",
+ );
+ assert!(Config::parse_yaml(no_controller.as_bytes()).is_ok());
+
+ let controller = with_proxy_groups(
+ groups,
+ "port: 1080\nauthentication:\n - measure:secret\nexternal-controller: '127.0.0.1:19090'\nsecret: token\nrules:\n - MATCH,主线路",
+ );
+ assert!(Config::parse_yaml(controller.as_bytes()).is_ok());
+
+ let missing_secret = controller.replace("secret: token\n", "");
+ let error = Config::parse_yaml(missing_secret.as_bytes()).unwrap_err();
+ assert!(error.to_string().contains("secret is required"), "{error}");
+ }
+
#[test]
fn accepts_many_proxies_and_resolves_rule_and_dns_tags() {
let yaml = format!(
@@ -3986,7 +4462,10 @@ proxies:
let config = Config::parse_yaml(yaml.as_bytes()).unwrap();
assert_eq!(config.proxies.len(), 4);
- assert_eq!(config.default_proxy.index(), 3);
+ assert_eq!(
+ config.default_route_target,
+ RouteTargetId::Proxy(ProxyId::from_index(3))
+ );
assert_eq!(
config
.dns
@@ -3995,10 +4474,10 @@ proxies:
.map(|nameserver| nameserver.route)
.collect::>(),
[
- DnsRoute::Proxy(ProxyId::from_index(0)),
- DnsRoute::Proxy(ProxyId::from_index(1)),
- DnsRoute::Proxy(ProxyId::from_index(2)),
- DnsRoute::Proxy(ProxyId::from_index(3)),
+ DnsRoute::Route(RouteTargetId::Proxy(ProxyId::from_index(0))),
+ DnsRoute::Route(RouteTargetId::Proxy(ProxyId::from_index(1))),
+ DnsRoute::Route(RouteTargetId::Proxy(ProxyId::from_index(2))),
+ DnsRoute::Route(RouteTargetId::Proxy(ProxyId::from_index(3))),
]
);
assert_eq!(
@@ -4008,9 +4487,9 @@ proxies:
.map(|rule| rule.action)
.collect::>(),
[
- RuleAction::Proxy(ProxyId::from_index(1)),
- RuleAction::Proxy(ProxyId::from_index(2)),
- RuleAction::Proxy(ProxyId::from_index(3)),
+ RuleAction::Route(RouteTargetId::Proxy(ProxyId::from_index(1))),
+ RuleAction::Route(RouteTargetId::Proxy(ProxyId::from_index(2))),
+ RuleAction::Route(RouteTargetId::Proxy(ProxyId::from_index(3))),
]
);
}
@@ -4025,7 +4504,10 @@ proxies:
assert!(yaml.len() <= MAX_CONFIG_BYTES);
let config = Config::parse_yaml(yaml.as_bytes()).unwrap();
assert_eq!(config.proxies.len(), 300);
- assert_eq!(config.default_proxy.index(), 299);
+ assert_eq!(
+ config.default_route_target,
+ RouteTargetId::Proxy(ProxyId::from_index(299))
+ );
assert_eq!(
config.proxies[299]
.dialer_proxy
@@ -4053,15 +4535,31 @@ proxies:
#[test]
fn rejects_invalid_proxy_tags_references_and_cycles() {
for tag in [
- "DIRECT", "REJECT", "RULES", "-edge", "edge,one", "edge#one", "节点",
+ "DIRECT",
+ "REJECT",
+ "RULES",
+ "edge,one",
+ "edge#one",
+ "edge/one",
+ "edge?one",
+ "edge&one",
+ "edge=one",
+ "edge%one",
+ "edge\\one",
+ ".",
+ "..",
+ " edge",
+ "edge ",
] {
let yaml = CURRENT_TLS.replace("name: proxy", &format!("name: '{tag}'"));
assert!(Config::parse_yaml(yaml.as_bytes()).is_err(), "{yaml}");
}
- let literal_proxy = CURRENT_TLS
- .replace("name: proxy", "name: PROXY")
- .replace("MATCH,proxy", "MATCH,PROXY");
- assert!(Config::parse_yaml(literal_proxy.as_bytes()).is_ok());
+ for tag in ["PROXY", "-edge", "节点", "♻️ 自动选择", "+"] {
+ let yaml = CURRENT_TLS
+ .replace("name: proxy", &format!("name: '{tag}'"))
+ .replace("MATCH,proxy", &format!("MATCH,{tag}"));
+ assert!(Config::parse_yaml(yaml.as_bytes()).is_ok(), "{yaml}");
+ }
let long_tag = "a".repeat(65);
let yaml = CURRENT_TLS.replace("name: proxy", &format!("name: {long_tag}"));
assert!(Config::parse_yaml(yaml.as_bytes()).is_err());
@@ -4086,7 +4584,7 @@ authentication:
);
assert!(Config::parse_yaml(unknown.as_bytes()).is_err());
- for invalid_reference in ["''", "null", "'-bad'"] {
+ for invalid_reference in ["''", "null", "'bad#name'"] {
let yaml = two_proxy_yaml(
"port: 1080
authentication:
@@ -4256,7 +4754,7 @@ dns:
DnsRoute::Direct,
DnsRoute::Direct,
DnsRoute::Rules,
- DnsRoute::Proxy(ProxyId::new(0).unwrap()),
+ DnsRoute::Route(RouteTargetId::Proxy(ProxyId::new(0).unwrap())),
]
);
@@ -4277,7 +4775,7 @@ authentication:
let config = Config::parse_yaml(yaml.as_bytes()).unwrap();
assert_eq!(
config.dns.nameservers[0].route,
- DnsRoute::Proxy(ProxyId::new(0).unwrap())
+ DnsRoute::Route(RouteTargetId::Proxy(ProxyId::new(0).unwrap()))
);
let yaml = two_proxy_yaml(
@@ -4294,8 +4792,8 @@ authentication:
.map(|nameserver| nameserver.route)
.collect::>(),
[
- DnsRoute::Proxy(ProxyId::new(0).unwrap()),
- DnsRoute::Proxy(ProxyId::new(1).unwrap()),
+ DnsRoute::Route(RouteTargetId::Proxy(ProxyId::new(0).unwrap())),
+ DnsRoute::Route(RouteTargetId::Proxy(ProxyId::new(1).unwrap())),
DnsRoute::Rules,
]
);
@@ -4321,7 +4819,7 @@ dns:
let dns = config.dns;
assert_eq!(
dns.nameservers[0].route,
- DnsRoute::Proxy(config.default_proxy)
+ DnsRoute::Route(config.default_route_target)
);
assert_eq!(dns.nameserver_policies.len(), 2);
assert_eq!(&*dns.nameserver_policies[0].geosite_codes, ["apple", "cn"]);
@@ -4341,7 +4839,10 @@ dns:
.iter()
.map(|nameserver| nameserver.route)
.collect::>(),
- [DnsRoute::Direct, DnsRoute::Proxy(ProxyId::new(0).unwrap())]
+ [
+ DnsRoute::Direct,
+ DnsRoute::Route(RouteTargetId::Proxy(ProxyId::new(0).unwrap()))
+ ]
);
}
diff --git a/src/controller.rs b/src/controller.rs
new file mode 100644
index 0000000..47f8600
--- /dev/null
+++ b/src/controller.rs
@@ -0,0 +1,770 @@
+use std::{io, net::SocketAddr, sync::Arc, time::Duration};
+
+use serde::{Deserialize, Serialize};
+use tokio::{
+ io::{AsyncReadExt, AsyncWriteExt},
+ net::{TcpListener, TcpStream},
+ task::JoinSet,
+ time::timeout,
+};
+use tokio_util::sync::CancellationToken;
+
+use crate::{
+ config::{ExternalControllerConfig, MAX_CONTROLLER_SECRET_BYTES, validate_route_target_name},
+ routing::{ProxyGroupError, ProxyGroupState, ProxyGroups},
+ traffic::TunTrafficStats,
+};
+
+const CONTROLLER_HEADER_TIMEOUT: Duration = Duration::from_secs(5);
+const CONTROLLER_BODY_TIMEOUT: Duration = Duration::from_secs(5);
+const MAX_CONTROLLER_CONNECTIONS: usize = 8;
+const MAX_CONTROLLER_BODY_BYTES: usize = 1024;
+
+pub(crate) struct RuntimeController {
+ listener: TcpListener,
+ secret: Option>,
+ traffic: Option>,
+ proxy_groups: Arc,
+}
+
+impl std::fmt::Debug for RuntimeController {
+ fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ formatter
+ .debug_struct("RuntimeController")
+ .field("local_addr", &self.listener.local_addr().ok())
+ .field("authenticated", &self.secret.is_some())
+ .field("has_traffic", &self.traffic.is_some())
+ .finish_non_exhaustive()
+ }
+}
+
+impl RuntimeController {
+ pub(crate) async fn bind(
+ config: &ExternalControllerConfig,
+ traffic: Option>,
+ proxy_groups: Arc,
+ ) -> io::Result {
+ Ok(Self {
+ listener: TcpListener::bind(config.listen).await?,
+ secret: config.secret.as_deref().map(Arc::from),
+ traffic,
+ proxy_groups,
+ })
+ }
+
+ #[cfg(test)]
+ pub(crate) fn local_addr(&self) -> io::Result {
+ self.listener.local_addr()
+ }
+
+ pub(crate) async fn serve(self, cancellation: CancellationToken) -> io::Result<()> {
+ let mut tasks = JoinSet::new();
+ loop {
+ tokio::select! {
+ biased;
+ () = cancellation.cancelled() => break,
+ joined = tasks.join_next(), if !tasks.is_empty() => {
+ if let Some(Err(error)) = joined {
+ tracing::warn!(
+ cancelled = error.is_cancelled(),
+ panicked = error.is_panic(),
+ "controller connection task failed"
+ );
+ }
+ }
+ accepted = self.listener.accept(), if tasks.len() < MAX_CONTROLLER_CONNECTIONS => {
+ let (stream, peer) = accepted?;
+ let secret = self.secret.clone();
+ let traffic = self.traffic.clone();
+ let proxy_groups = self.proxy_groups.clone();
+ let child = cancellation.clone();
+ tasks.spawn(async move {
+ if let Err(error) = handle_connection(
+ stream,
+ peer,
+ secret,
+ traffic,
+ proxy_groups,
+ child,
+ )
+ .await
+ {
+ tracing::debug!(
+ error_kind = ?error.kind(),
+ "controller request failed"
+ );
+ }
+ });
+ }
+ }
+ }
+ tasks.abort_all();
+ while tasks.join_next().await.is_some() {}
+ Ok(())
+ }
+}
+
+async fn handle_connection(
+ mut stream: TcpStream,
+ peer: SocketAddr,
+ secret: Option>,
+ traffic: Option>,
+ proxy_groups: Arc,
+ cancellation: CancellationToken,
+) -> io::Result<()> {
+ if !peer.ip().is_loopback() {
+ return write_error(&mut stream, 403, "Forbidden", &[]).await;
+ }
+
+ let request = tokio::select! {
+ biased;
+ () = cancellation.cancelled() => return Ok(()),
+ result = timeout(
+ CONTROLLER_HEADER_TIMEOUT,
+ crate::inbound::http::read_request_head(
+ &mut stream,
+ crate::inbound::DEFAULT_HEADER_LIMIT,
+ ),
+ ) => match result {
+ Ok(Ok(request)) => request,
+ Ok(Err(error)) => {
+ write_error(&mut stream, 400, "Bad request", &[]).await?;
+ return Err(error);
+ }
+ Err(_) => {
+ write_error(&mut stream, 408, "Timeout", &[]).await?;
+ return Err(io::Error::new(
+ io::ErrorKind::TimedOut,
+ "controller request head timed out",
+ ));
+ }
+ },
+ };
+
+ if !authorized(&request.headers, secret.as_deref()) {
+ return write_error(
+ &mut stream,
+ 401,
+ "Unauthorized",
+ &[("WWW-Authenticate", "Bearer")],
+ )
+ .await;
+ }
+
+ if request.target.contains(['?', '#']) {
+ return write_error(&mut stream, 400, "Bad request", &[]).await;
+ }
+
+ if request.target == "/traffic" {
+ if request.method != "GET" {
+ return write_error(&mut stream, 405, "Method not allowed", &[("Allow", "GET")]).await;
+ }
+ return match traffic {
+ Some(traffic) => write_json(&mut stream, 200, &traffic.snapshot(), &[]).await,
+ None => write_error(&mut stream, 404, "Resource not found", &[]).await,
+ };
+ }
+
+ if request.target == "/group" {
+ if request.method != "GET" {
+ return write_error(&mut stream, 405, "Method not allowed", &[("Allow", "GET")]).await;
+ }
+ let proxies = proxy_groups
+ .list_states()
+ .into_iter()
+ .map(GroupResponse::from)
+ .collect();
+ return write_json(&mut stream, 200, &GroupListResponse { proxies }, &[]).await;
+ }
+
+ if let Some(raw_name) = request.target.strip_prefix("/group/") {
+ if request.method != "GET" {
+ return write_error(&mut stream, 405, "Method not allowed", &[("Allow", "GET")]).await;
+ }
+ let name = match decode_group_name(raw_name) {
+ Ok(name) => name,
+ Err(()) => return write_error(&mut stream, 400, "Bad request", &[]).await,
+ };
+ return match proxy_groups.state(&name) {
+ Ok(state) => write_json(&mut stream, 200, &GroupResponse::from(state), &[]).await,
+ Err(ProxyGroupError::UnknownGroup) => {
+ write_error(&mut stream, 404, "Resource not found", &[]).await
+ }
+ Err(ProxyGroupError::UnknownMember) => unreachable!("state does not select a member"),
+ };
+ }
+
+ if let Some(raw_name) = request.target.strip_prefix("/proxies/") {
+ let name = match decode_group_name(raw_name) {
+ Ok(name) => name,
+ Err(()) => return write_error(&mut stream, 400, "Bad request", &[]).await,
+ };
+ return match request.method.as_str() {
+ "GET" => match proxy_groups.state(&name) {
+ Ok(state) => write_json(&mut stream, 200, &GroupResponse::from(state), &[]).await,
+ Err(_) => write_error(&mut stream, 404, "Resource not found", &[]).await,
+ },
+ "PUT" => {
+ handle_select(
+ &mut stream,
+ &request.headers,
+ request.buffered,
+ &name,
+ &proxy_groups,
+ cancellation,
+ )
+ .await
+ }
+ _ => {
+ write_error(
+ &mut stream,
+ 405,
+ "Method not allowed",
+ &[("Allow", "GET, PUT")],
+ )
+ .await
+ }
+ };
+ }
+
+ write_error(&mut stream, 404, "Resource not found", &[]).await
+}
+
+async fn handle_select(
+ stream: &mut TcpStream,
+ headers: &[(String, String)],
+ mut body: Vec,
+ group: &str,
+ proxy_groups: &ProxyGroups,
+ cancellation: CancellationToken,
+) -> io::Result<()> {
+ if header_values(headers, "transfer-encoding").next().is_some() {
+ return write_error(stream, 400, "Body invalid", &[]).await;
+ }
+
+ let mut content_types = header_values(headers, "content-type");
+ let valid_content_type = content_types
+ .next()
+ .is_some_and(|value| value.eq_ignore_ascii_case("application/json"))
+ && content_types.next().is_none();
+ if !valid_content_type {
+ return write_error(stream, 415, "Unsupported media type", &[]).await;
+ }
+
+ let mut content_lengths = header_values(headers, "content-length");
+ let Some(content_length) = content_lengths.next() else {
+ return write_error(stream, 411, "Length required", &[]).await;
+ };
+ if content_lengths.next().is_some()
+ || content_length.is_empty()
+ || !content_length.bytes().all(|byte| byte.is_ascii_digit())
+ {
+ return write_error(stream, 400, "Body invalid", &[]).await;
+ }
+ let Ok(content_length) = content_length.parse::() else {
+ return write_error(stream, 400, "Body invalid", &[]).await;
+ };
+ if content_length > MAX_CONTROLLER_BODY_BYTES {
+ return write_error(stream, 413, "Payload too large", &[]).await;
+ }
+ if body.len() > content_length {
+ return write_error(stream, 400, "Body invalid", &[]).await;
+ }
+
+ let buffered = body.len();
+ body.resize(content_length, 0);
+ if buffered != content_length {
+ let read = tokio::select! {
+ biased;
+ () = cancellation.cancelled() => return Ok(()),
+ result = timeout(
+ CONTROLLER_BODY_TIMEOUT,
+ stream.read_exact(&mut body[buffered..]),
+ ) => result,
+ };
+ match read {
+ Ok(Ok(_)) => {}
+ Ok(Err(error)) => {
+ write_error(stream, 400, "Body invalid", &[]).await?;
+ return Err(error);
+ }
+ Err(_) => {
+ write_error(stream, 408, "Timeout", &[]).await?;
+ return Err(io::Error::new(
+ io::ErrorKind::TimedOut,
+ "controller request body timed out",
+ ));
+ }
+ }
+ }
+
+ let request = match serde_json::from_slice::(&body) {
+ Ok(request) => request,
+ Err(_) => return write_error(stream, 400, "Body invalid", &[]).await,
+ };
+ match proxy_groups.select(group, &request.name) {
+ Ok(()) => write_response(stream, 204, &[], b"").await,
+ Err(ProxyGroupError::UnknownGroup) => {
+ write_error(stream, 404, "Resource not found", &[]).await
+ }
+ Err(ProxyGroupError::UnknownMember) => {
+ write_error(
+ stream,
+ 400,
+ "Selector update error: route target not found",
+ &[],
+ )
+ .await
+ }
+ }
+}
+
+fn header_values<'a>(
+ headers: &'a [(String, String)],
+ expected: &'a str,
+) -> impl Iterator- {
+ headers
+ .iter()
+ .filter(move |(name, _)| name.eq_ignore_ascii_case(expected))
+ .map(|(_, value)| value.as_str())
+}
+
+fn authorized(headers: &[(String, String)], secret: Option<&str>) -> bool {
+ let Some(secret) = secret else {
+ return true;
+ };
+ let mut authorization = header_values(headers, "authorization");
+ let Some(value) = authorization.next() else {
+ return false;
+ };
+ if authorization.next().is_some() {
+ return false;
+ }
+ value
+ .strip_prefix("Bearer ")
+ .is_some_and(|token| controller_token_eq(token.as_bytes(), secret.as_bytes()))
+}
+
+fn controller_token_eq(candidate: &[u8], secret: &[u8]) -> bool {
+ let mut difference = candidate.len() ^ secret.len();
+ for index in 0..MAX_CONTROLLER_SECRET_BYTES {
+ let candidate = candidate.get(index).copied().unwrap_or_default();
+ let secret = secret.get(index).copied().unwrap_or_default();
+ difference |= usize::from(candidate ^ secret);
+ }
+ difference == 0
+}
+
+fn decode_group_name(raw: &str) -> Result {
+ if raw.is_empty() || raw.contains('/') {
+ return Err(());
+ }
+ let bytes = raw.as_bytes();
+ let mut decoded = Vec::with_capacity(bytes.len());
+ let mut index = 0;
+ while index < bytes.len() {
+ if bytes[index] == b'%' {
+ let high = bytes
+ .get(index + 1)
+ .copied()
+ .and_then(hex_value)
+ .ok_or(())?;
+ let low = bytes
+ .get(index + 2)
+ .copied()
+ .and_then(hex_value)
+ .ok_or(())?;
+ decoded.push((high << 4) | low);
+ index += 3;
+ } else {
+ decoded.push(bytes[index]);
+ index += 1;
+ }
+ }
+ let name = String::from_utf8(decoded).map_err(|_| ())?;
+ validate_route_target_name(&name, "controller group name").map_err(|_| ())?;
+ Ok(name)
+}
+
+fn hex_value(byte: u8) -> Option {
+ match byte {
+ b'0'..=b'9' => Some(byte - b'0'),
+ b'a'..=b'f' => Some(byte - b'a' + 10),
+ b'A'..=b'F' => Some(byte - b'A' + 10),
+ _ => None,
+ }
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct SelectRequest {
+ name: String,
+}
+
+#[derive(Serialize)]
+struct GroupListResponse {
+ proxies: Vec,
+}
+
+#[derive(Serialize)]
+struct GroupResponse {
+ name: String,
+ #[serde(rename = "type")]
+ kind: &'static str,
+ all: Vec,
+ now: String,
+}
+
+impl From for GroupResponse {
+ fn from(state: ProxyGroupState) -> Self {
+ Self {
+ name: state.name,
+ kind: "Selector",
+ all: state.all,
+ now: state.now,
+ }
+ }
+}
+
+async fn write_json(
+ stream: &mut TcpStream,
+ status: u16,
+ value: &T,
+ headers: &[(&str, &str)],
+) -> io::Result<()> {
+ let body = serde_json::to_vec(value).map_err(io::Error::other)?;
+ let mut response_headers = Vec::with_capacity(headers.len() + 1);
+ response_headers.push(("Content-Type", "application/json"));
+ response_headers.extend_from_slice(headers);
+ write_response(stream, status, &response_headers, &body).await
+}
+
+async fn write_error(
+ stream: &mut TcpStream,
+ status: u16,
+ message: &'static str,
+ headers: &[(&str, &str)],
+) -> io::Result<()> {
+ #[derive(Serialize)]
+ struct ErrorResponse {
+ message: &'static str,
+ }
+ write_json(stream, status, &ErrorResponse { message }, headers).await
+}
+
+async fn write_response(
+ stream: &mut TcpStream,
+ status: u16,
+ headers: &[(&str, &str)],
+ body: &[u8],
+) -> io::Result<()> {
+ let reason = match status {
+ 200 => "OK",
+ 204 => "No Content",
+ 400 => "Bad Request",
+ 401 => "Unauthorized",
+ 403 => "Forbidden",
+ 404 => "Not Found",
+ 405 => "Method Not Allowed",
+ 408 => "Request Timeout",
+ 411 => "Length Required",
+ 413 => "Payload Too Large",
+ 415 => "Unsupported Media Type",
+ 500 => "Internal Server Error",
+ _ => "Error",
+ };
+ let mut response = format!(
+ "HTTP/1.1 {status} {reason}\r\nContent-Length: {}\r\nConnection: close\r\nCache-Control: no-store\r\n",
+ body.len()
+ );
+ for (name, value) in headers {
+ response.push_str(name);
+ response.push_str(": ");
+ response.push_str(value);
+ response.push_str("\r\n");
+ }
+ response.push_str("\r\n");
+ stream.write_all(response.as_bytes()).await?;
+ stream.write_all(body).await?;
+ stream.shutdown().await
+}
+
+#[cfg(test)]
+mod tests {
+ use async_trait::async_trait;
+ use serde_json::Value;
+
+ use super::*;
+ use crate::{
+ config::{
+ ProxyGroupMemberConfig, ProxyGroupMemberTarget, ProxyId, RouteTargetId,
+ SelectProxyGroupConfig,
+ },
+ dispatch::{BoxStream, DatagramTransport, DispatchError, Dispatcher},
+ session::{DatagramSession, StreamSession},
+ };
+
+ struct UnusedDispatcher;
+
+ #[async_trait]
+ impl Dispatcher for UnusedDispatcher {
+ async fn connect_tcp(&self, _session: StreamSession) -> Result {
+ Err(DispatchError::NotAllowed)
+ }
+
+ async fn open_datagram(
+ &self,
+ _session: DatagramSession,
+ ) -> Result, DispatchError> {
+ Err(DispatchError::NotAllowed)
+ }
+ }
+
+ fn test_groups() -> Arc {
+ let dispatcher: Arc = Arc::new(UnusedDispatcher);
+ ProxyGroups::new(
+ &[SelectProxyGroupConfig {
+ name: "主线路".to_owned(),
+ members: vec![
+ ProxyGroupMemberConfig {
+ name: "node-a".to_owned(),
+ target: ProxyGroupMemberTarget::Route(RouteTargetId::Proxy(
+ ProxyId::new(0).unwrap(),
+ )),
+ },
+ ProxyGroupMemberConfig {
+ name: "node-b".to_owned(),
+ target: ProxyGroupMemberTarget::Route(RouteTargetId::Proxy(
+ ProxyId::new(1).unwrap(),
+ )),
+ },
+ ],
+ initial_member: 0,
+ }],
+ vec![dispatcher.clone(), dispatcher.clone()],
+ dispatcher,
+ )
+ .unwrap()
+ }
+
+ async fn request(address: SocketAddr, request: &str) -> String {
+ let mut stream = TcpStream::connect(address).await.unwrap();
+ stream.write_all(request.as_bytes()).await.unwrap();
+ let mut response = Vec::new();
+ stream.read_to_end(&mut response).await.unwrap();
+ String::from_utf8(response).unwrap()
+ }
+
+ fn response_body(response: &str) -> &str {
+ response.split_once("\r\n\r\n").unwrap().1
+ }
+
+ #[test]
+ fn bearer_auth_is_strict_and_duplicate_safe() {
+ let valid = vec![("Authorization".to_owned(), "Bearer token".to_owned())];
+ assert!(authorized(&valid, Some("token")));
+ assert!(authorized(&[], None));
+ assert!(!authorized(&[], Some("token")));
+ assert!(!authorized(
+ &[("Authorization".to_owned(), "bearer token".to_owned())],
+ Some("token")
+ ));
+ assert!(!authorized(
+ &[
+ ("Authorization".to_owned(), "Bearer token".to_owned()),
+ ("authorization".to_owned(), "Bearer token".to_owned()),
+ ],
+ Some("token")
+ ));
+ assert!(!controller_token_eq(b"toke", b"token"));
+ assert!(!controller_token_eq(b"token-longer", b"token"));
+ let longest = vec![b'x'; MAX_CONTROLLER_SECRET_BYTES];
+ assert!(controller_token_eq(&longest, &longest));
+ }
+
+ #[test]
+ fn percent_decoding_is_single_pass_and_utf8_safe() {
+ assert_eq!(
+ decode_group_name("%E4%B8%BB%E7%BA%BF%E8%B7%AF").unwrap(),
+ "主线路"
+ );
+ assert_eq!(decode_group_name("a+b").unwrap(), "a+b");
+ assert!(decode_group_name("%252F").is_err());
+ assert!(decode_group_name("%2F").is_err());
+ assert!(decode_group_name("%GG").is_err());
+ assert!(decode_group_name("%A").is_err());
+ assert!(decode_group_name("%FF").is_err());
+ assert!(decode_group_name("..").is_err());
+ }
+
+ #[tokio::test]
+ async fn controller_lists_queries_and_switches_select_groups() {
+ let groups = test_groups();
+ let controller = RuntimeController::bind(
+ &ExternalControllerConfig {
+ listen: "127.0.0.1:0".parse().unwrap(),
+ secret: Some("secret".to_owned()),
+ },
+ None,
+ groups.clone(),
+ )
+ .await
+ .unwrap();
+ let address = controller.local_addr().unwrap();
+ let cancellation = CancellationToken::new();
+ let task = tokio::spawn(controller.serve(cancellation.clone()));
+
+ let unauthorized = request(address, "GET /group HTTP/1.1\r\n\r\n").await;
+ assert!(unauthorized.starts_with("HTTP/1.1 401 Unauthorized\r\n"));
+
+ let listed = request(
+ address,
+ "GET /group HTTP/1.1\r\nAuthorization: Bearer secret\r\n\r\n",
+ )
+ .await;
+ assert!(listed.starts_with("HTTP/1.1 200 OK\r\n"));
+ let listed: Value = serde_json::from_str(response_body(&listed)).unwrap();
+ assert_eq!(listed["proxies"][0]["name"], "主线路");
+ assert_eq!(listed["proxies"][0]["type"], "Selector");
+ assert_eq!(
+ listed["proxies"][0]["all"],
+ serde_json::json!(["node-a", "node-b"])
+ );
+ assert_eq!(listed["proxies"][0]["now"], "node-a");
+
+ let body = r#"{"name":"node-b"}"#;
+ let switched = request(
+ address,
+ &format!(
+ "PUT /proxies/%E4%B8%BB%E7%BA%BF%E8%B7%AF HTTP/1.1\r\nAuthorization: Bearer secret\r\nContent-Type: application/json\r\nContent-Length: {}\r\n\r\n{body}",
+ body.len()
+ ),
+ )
+ .await;
+ assert!(switched.starts_with("HTTP/1.1 204 No Content\r\n"));
+ assert_eq!(groups.state("主线路").unwrap().now, "node-b");
+
+ let queried = request(
+ address,
+ "GET /proxies/%E4%B8%BB%E7%BA%BF%E8%B7%AF HTTP/1.1\r\nAuthorization: Bearer secret\r\n\r\n",
+ )
+ .await;
+ let queried: Value = serde_json::from_str(response_body(&queried)).unwrap();
+ assert_eq!(queried["now"], "node-b");
+
+ cancellation.cancel();
+ task.await.unwrap().unwrap();
+ }
+
+ #[tokio::test]
+ async fn controller_rejects_invalid_selector_bodies_without_mutation() {
+ let groups = test_groups();
+ let controller = RuntimeController::bind(
+ &ExternalControllerConfig {
+ listen: "127.0.0.1:0".parse().unwrap(),
+ secret: Some("secret".to_owned()),
+ },
+ None,
+ groups.clone(),
+ )
+ .await
+ .unwrap();
+ let address = controller.local_addr().unwrap();
+ let cancellation = CancellationToken::new();
+ let task = tokio::spawn(controller.serve(cancellation.clone()));
+
+ let body = r#"{"name":"missing"}"#;
+ let unknown = request(
+ address,
+ &format!(
+ "PUT /proxies/%E4%B8%BB%E7%BA%BF%E8%B7%AF HTTP/1.1\r\nAuthorization: Bearer secret\r\nContent-Type: application/json\r\nContent-Length: {}\r\n\r\n{body}",
+ body.len()
+ ),
+ )
+ .await;
+ assert!(unknown.starts_with("HTTP/1.1 400 Bad Request\r\n"));
+ assert_eq!(groups.state("主线路").unwrap().now, "node-a");
+
+ let smuggled = request(
+ address,
+ "PUT /proxies/%E4%B8%BB%E7%BA%BF%E8%B7%AF HTTP/1.1\r\nAuthorization: Bearer secret\r\nContent-Type: application/json\r\nContent-Length: 17\r\nTransfer-Encoding: chunked\r\n\r\n{\"name\":\"node-b\"}",
+ )
+ .await;
+ assert!(smuggled.starts_with("HTTP/1.1 400 Bad Request\r\n"));
+ assert_eq!(groups.state("主线路").unwrap().now, "node-a");
+
+ let malformed = [
+ (
+ "PUT /proxies/%E4%B8%BB%E7%BA%BF%E8%B7%AF HTTP/1.1\r\nAuthorization: Bearer secret\r\nContent-Length: 17\r\n\r\n{\"name\":\"node-b\"}",
+ 415,
+ ),
+ (
+ "PUT /proxies/%E4%B8%BB%E7%BA%BF%E8%B7%AF HTTP/1.1\r\nAuthorization: Bearer secret\r\nContent-Type: application/json; charset=utf-8\r\nContent-Length: 17\r\n\r\n{\"name\":\"node-b\"}",
+ 415,
+ ),
+ (
+ "PUT /proxies/%E4%B8%BB%E7%BA%BF%E8%B7%AF HTTP/1.1\r\nAuthorization: Bearer secret\r\nContent-Type: application/json\r\n\r\n{\"name\":\"node-b\"}",
+ 411,
+ ),
+ (
+ "PUT /proxies/%E4%B8%BB%E7%BA%BF%E8%B7%AF HTTP/1.1\r\nAuthorization: Bearer secret\r\nContent-Type: application/json\r\nContent-Length: 17\r\nContent-Length: 17\r\n\r\n{\"name\":\"node-b\"}",
+ 400,
+ ),
+ (
+ "PUT /proxies/%E4%B8%BB%E7%BA%BF%E8%B7%AF HTTP/1.1\r\nAuthorization: Bearer secret\r\nContent-Type: application/json\r\nContent-Length: 27\r\n\r\n{\"name\":\"node-b\",\"extra\":1}",
+ 400,
+ ),
+ (
+ "PUT /proxies/%E4%B8%BB%E7%BA%BF%E8%B7%AF HTTP/1.1\r\nAuthorization: Bearer secret\r\nContent-Type: application/json\r\nContent-Length: 33\r\n\r\n{\"name\":\"node-a\",\"name\":\"node-b\"}",
+ 400,
+ ),
+ (
+ "GET /proxies/node-a HTTP/1.1\r\nAuthorization: Bearer secret\r\n\r\n",
+ 404,
+ ),
+ (
+ "GET /traffic HTTP/1.1\r\nAuthorization: Bearer secret\r\n\r\n",
+ 404,
+ ),
+ (
+ "GET /group?name=x HTTP/1.1\r\nAuthorization: Bearer secret\r\n\r\n",
+ 400,
+ ),
+ (
+ "GET /group/%2F HTTP/1.1\r\nAuthorization: Bearer secret\r\n\r\n",
+ 400,
+ ),
+ ("GET /group/missing HTTP/1.1\r\n\r\n", 401),
+ ];
+ for (raw, status) in malformed {
+ let response = request(address, raw).await;
+ assert!(
+ response.starts_with(&format!("HTTP/1.1 {status} ")),
+ "{response}"
+ );
+ assert!(response.contains("\r\nCache-Control: no-store\r\n"));
+ assert_eq!(groups.state("主线路").unwrap().now, "node-a");
+ }
+
+ let oversized = request(
+ address,
+ "PUT /proxies/%E4%B8%BB%E7%BA%BF%E8%B7%AF HTTP/1.1\r\nAuthorization: Bearer secret\r\nContent-Type: application/json\r\nContent-Length: 1025\r\n\r\n",
+ )
+ .await;
+ assert!(oversized.starts_with("HTTP/1.1 413 Payload Too Large\r\n"));
+
+ let mut half_body = TcpStream::connect(address).await.unwrap();
+ half_body
+ .write_all(
+ b"PUT /proxies/%E4%B8%BB%E7%BA%BF%E8%B7%AF HTTP/1.1\r\nAuthorization: Bearer secret\r\nContent-Type: application/json\r\nContent-Length: 17\r\n\r\n{",
+ )
+ .await
+ .unwrap();
+ cancellation.cancel();
+ tokio::time::timeout(Duration::from_secs(1), task)
+ .await
+ .expect("controller stop must cancel a partial body")
+ .unwrap()
+ .unwrap();
+ }
+}
diff --git a/src/dns/runtime.rs b/src/dns/runtime.rs
index 9651248..6d542b8 100644
--- a/src/dns/runtime.rs
+++ b/src/dns/runtime.rs
@@ -1,7 +1,7 @@
//! Bounded runtime DNS service with Mihomo-compatible nameserver egress.
//!
//! Upstream endpoints are literal IP addresses. Explicit nameserver fragments
-//! select DIRECT, one of the fixed proxy nodes, or the ordered rules using only that
+//! select DIRECT, a named route target, or the ordered rules using only that
//! endpoint as routing context; a DNS question name is never injected into
//! business routing.
@@ -35,7 +35,8 @@ use super::{
};
use crate::{
config::{
- DnsConfig, DnsNameserver, DnsNameserverPolicy, DnsRoute, DnsTransport, Network, RuleAction,
+ DnsConfig, DnsNameserver, DnsNameserverPolicy, DnsRoute, DnsTransport, Network,
+ RouteTargetId, RuleAction,
},
dispatch::{BoxStream, DispatchError, Dispatcher},
resources::{ResourceActivity, ResourceActivityGuard, RuntimeResourceStats},
@@ -103,7 +104,7 @@ pub struct RuntimeDns {
enum DnsEgressKey {
Single,
Direct,
- Proxy(crate::config::ProxyId),
+ Route(RouteTargetId),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
@@ -913,9 +914,9 @@ impl RuntimeDns {
match nameserver.route {
DnsRoute::Direct => Ok((DnsEgressKey::Direct, direct)),
- DnsRoute::Proxy(id) => proxies
- .get(id)
- .map(|dispatcher| (DnsEgressKey::Proxy(id), dispatcher))
+ DnsRoute::Route(id) => proxies
+ .get_route(id)
+ .map(|dispatcher| (DnsEgressKey::Route(id), dispatcher))
.map_err(AttemptError::Dispatch),
DnsRoute::Rules => {
let destination = Destination::Ip(nameserver.endpoint());
@@ -926,9 +927,9 @@ impl RuntimeDns {
})?;
match rules.evaluate_with_geo(&context, self.geo_matcher.as_ref()) {
RuleEvaluation::Matched(rule_match) => match rule_match.action {
- RuleAction::Proxy(id) => proxies
- .get(id)
- .map(|dispatcher| (DnsEgressKey::Proxy(id), dispatcher))
+ RuleAction::Route(id) => proxies
+ .get_route(id)
+ .map(|dispatcher| (DnsEgressKey::Route(id), dispatcher))
.map_err(AttemptError::Dispatch),
RuleAction::Direct => Ok((DnsEgressKey::Direct, direct)),
RuleAction::Reject => {
@@ -2269,7 +2270,9 @@ mod tests {
transport,
address: IpAddr::V4(Ipv4Addr::new(192, 0, 2, index)),
port: 53,
- route: crate::config::DnsRoute::Proxy(crate::config::ProxyId::new(0).unwrap()),
+ route: crate::config::DnsRoute::Route(crate::config::RouteTargetId::Proxy(
+ crate::config::ProxyId::new(0).unwrap(),
+ )),
}
}
@@ -2650,8 +2653,9 @@ mod tests {
let mut direct_nameserver = nameserver(1, DnsTransport::Tcp);
direct_nameserver.route = DnsRoute::Direct;
let mut proxy_nameserver = direct_nameserver;
- proxy_nameserver.route =
- DnsRoute::Proxy(crate::config::ProxyId::new(0).expect("proxy zero is valid"));
+ proxy_nameserver.route = DnsRoute::Route(crate::config::RouteTargetId::Proxy(
+ crate::config::ProxyId::new(0).expect("proxy zero is valid"),
+ ));
let resolver = RuntimeDns::new_routed(
&config(false, vec![direct_nameserver]),
proxy.clone(),
@@ -2677,6 +2681,80 @@ mod tests {
assert_eq!(resolver.tcp_pool.snapshot().current_idle, 2);
}
+ #[tokio::test]
+ async fn group_switch_keeps_dns_cache_and_tcp_pool_until_a_new_connection() {
+ use crate::config::{
+ ProxyGroupId, ProxyGroupMemberConfig, ProxyGroupMemberTarget, ProxyId, RouteTargetId,
+ SelectProxyGroupConfig,
+ };
+ use crate::routing::{ProxyGroups, RouteTargetDispatchers};
+
+ let address = IpAddr::V4(Ipv4Addr::new(203, 0, 113, 65));
+ let old = Arc::new(ScriptedTcpDispatcher::new(vec![vec![
+ TcpScriptReply::Response(ResponseSpec::answer(address)),
+ TcpScriptReply::Response(ResponseSpec::answer(address)),
+ ]]));
+ let new = Arc::new(ScriptedTcpDispatcher::new(vec![vec![
+ TcpScriptReply::Response(ResponseSpec::answer(address)),
+ ]]));
+ let direct: Arc = Arc::new(MockDispatcher::default());
+ let proxy_dispatchers: Vec> = vec![old.clone(), new.clone()];
+ let groups = ProxyGroups::new(
+ &[SelectProxyGroupConfig {
+ name: "group".to_owned(),
+ members: vec![
+ ProxyGroupMemberConfig {
+ name: "old".to_owned(),
+ target: ProxyGroupMemberTarget::Route(RouteTargetId::Proxy(
+ ProxyId::new(0).unwrap(),
+ )),
+ },
+ ProxyGroupMemberConfig {
+ name: "new".to_owned(),
+ target: ProxyGroupMemberTarget::Route(RouteTargetId::Proxy(
+ ProxyId::new(1).unwrap(),
+ )),
+ },
+ ],
+ initial_member: 0,
+ }],
+ proxy_dispatchers.clone(),
+ direct.clone(),
+ )
+ .unwrap();
+ let route_targets =
+ RouteTargetDispatchers::with_proxy_groups(proxy_dispatchers, &groups).unwrap();
+ let group = RouteTargetId::Group(ProxyGroupId::new(0).unwrap());
+ let mut upstream = nameserver(1, DnsTransport::Tcp);
+ upstream.route = DnsRoute::Route(group);
+ let resolver = RuntimeDns::new_routed_proxies(
+ &config(false, vec![upstream]),
+ route_targets,
+ direct,
+ RuleSet::compile(vec![rule(RuleKind::Match, RuleAction::Route(group))]).unwrap(),
+ Arc::new(EmptyGeoMatcher),
+ );
+
+ assert_eq!(resolver.resolve("cached.example").await.unwrap(), [address]);
+ groups.select("group", "new").unwrap();
+ assert_eq!(resolver.resolve("cached.example").await.unwrap(), [address]);
+ assert_eq!(new.tcp_calls.load(Ordering::Acquire), 0);
+
+ assert_eq!(resolver.resolve("pooled.example").await.unwrap(), [address]);
+ assert_eq!(old.tcp_calls.load(Ordering::Acquire), 1);
+ assert_eq!(old.tcp_queries.load(Ordering::Acquire), 2);
+ assert_eq!(new.tcp_calls.load(Ordering::Acquire), 0);
+
+ tokio::task::yield_now().await;
+ assert_eq!(
+ resolver.resolve("rebuilt.example").await.unwrap(),
+ [address]
+ );
+ assert_eq!(new.tcp_calls.load(Ordering::Acquire), 1);
+ assert_eq!(new.tcp_queries.load(Ordering::Acquire), 1);
+ assert_eq!(resolver.tcp_pool.snapshot().stale_retries, 1);
+ }
+
#[tokio::test]
async fn tcp_pool_allows_active_connections_above_old_ceiling_but_retains_only_two_idle() {
const ACTIVE: usize = 12;
@@ -2750,8 +2828,9 @@ mod tests {
for index in 1..=5 {
let mut upstream = nameserver(index, DnsTransport::Tcp);
- upstream.route =
- DnsRoute::Proxy(crate::config::ProxyId::new(0).expect("proxy zero is valid"));
+ upstream.route = DnsRoute::Route(crate::config::RouteTargetId::Proxy(
+ crate::config::ProxyId::new(0).expect("proxy zero is valid"),
+ ));
let query = build_query(
u16::from(index),
&format!("idle-{index}.example"),
@@ -2832,7 +2911,9 @@ mod tests {
direct.clone(),
RuleSet::compile(vec![rule(
RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
+ RuleAction::Route(crate::config::RouteTargetId::Proxy(
+ crate::config::ProxyId::new(0).unwrap(),
+ )),
)])
.unwrap(),
Arc::new(EmptyGeoMatcher),
@@ -2860,7 +2941,9 @@ mod tests {
),
rule(
RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
+ RuleAction::Route(crate::config::RouteTargetId::Proxy(
+ crate::config::ProxyId::new(0).unwrap(),
+ )),
),
])
.unwrap(),
@@ -2890,7 +2973,9 @@ mod tests {
),
rule(
RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
+ RuleAction::Route(crate::config::RouteTargetId::Proxy(
+ crate::config::ProxyId::new(0).unwrap(),
+ )),
),
])
.unwrap(),
@@ -2924,7 +3009,9 @@ mod tests {
transport: DnsTransport::Tcp,
address: "1.1.1.1".parse().unwrap(),
port: 53,
- route: DnsRoute::Proxy(crate::config::ProxyId::new(0).unwrap()),
+ route: DnsRoute::Route(crate::config::RouteTargetId::Proxy(
+ crate::config::ProxyId::new(0).unwrap(),
+ )),
};
let policy_nameserver = DnsNameserver {
transport: DnsTransport::Tcp,
@@ -2943,7 +3030,9 @@ mod tests {
direct.clone(),
RuleSet::compile(vec![rule(
RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
+ RuleAction::Route(crate::config::RouteTargetId::Proxy(
+ crate::config::ProxyId::new(0).unwrap(),
+ )),
)])
.unwrap(),
Arc::new(PolicyGeoMatcher),
@@ -3014,7 +3103,9 @@ mod tests {
direct.clone(),
RuleSet::compile(vec![rule(
RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
+ RuleAction::Route(crate::config::RouteTargetId::Proxy(
+ crate::config::ProxyId::new(0).unwrap(),
+ )),
)])
.unwrap(),
Arc::new(PolicyGeoMatcher),
@@ -3058,7 +3149,9 @@ mod tests {
direct.clone(),
RuleSet::compile(vec![rule(
RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
+ RuleAction::Route(crate::config::RouteTargetId::Proxy(
+ crate::config::ProxyId::new(0).unwrap(),
+ )),
)])
.unwrap(),
Arc::new(PolicyGeoMatcher),
@@ -3107,7 +3200,9 @@ mod tests {
direct.clone(),
RuleSet::compile(vec![rule(
RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
+ RuleAction::Route(crate::config::RouteTargetId::Proxy(
+ crate::config::ProxyId::new(0).unwrap(),
+ )),
)])
.unwrap(),
Arc::new(PolicyGeoMatcher),
@@ -3170,7 +3265,9 @@ mod tests {
),
rule(
RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
+ RuleAction::Route(crate::config::RouteTargetId::Proxy(
+ crate::config::ProxyId::new(0).unwrap(),
+ )),
),
])
.unwrap(),
@@ -3209,7 +3306,9 @@ mod tests {
direct.clone(),
RuleSet::compile(vec![rule(
RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
+ RuleAction::Route(crate::config::RouteTargetId::Proxy(
+ crate::config::ProxyId::new(0).unwrap(),
+ )),
)])
.unwrap(),
Arc::new(EmptyGeoMatcher),
@@ -3249,7 +3348,9 @@ mod tests {
direct,
RuleSet::compile(vec![rule(
RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
+ RuleAction::Route(crate::config::RouteTargetId::Proxy(
+ crate::config::ProxyId::new(0).unwrap(),
+ )),
)])
.unwrap(),
Arc::new(EmptyGeoMatcher),
@@ -3286,7 +3387,9 @@ mod tests {
rule(RuleKind::Network(Network::Udp), RuleAction::Reject),
rule(
RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
+ RuleAction::Route(crate::config::RouteTargetId::Proxy(
+ crate::config::ProxyId::new(0).unwrap(),
+ )),
),
])
.unwrap(),
diff --git a/src/geodata/manager.rs b/src/geodata/manager.rs
index 211d663..b243402 100644
--- a/src/geodata/manager.rs
+++ b/src/geodata/manager.rs
@@ -1378,7 +1378,9 @@ mod tests {
fn rule(kind: RuleKind) -> RuleSpec {
RuleSpec {
kind,
- action: RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
+ action: RuleAction::Route(crate::config::RouteTargetId::Proxy(
+ crate::config::ProxyId::new(0).unwrap(),
+ )),
no_resolve: false,
}
}
diff --git a/src/geodata/tests.rs b/src/geodata/tests.rs
index e764405..36e616b 100644
--- a/src/geodata/tests.rs
+++ b/src/geodata/tests.rs
@@ -88,7 +88,9 @@ fn geoip_list(entries: &[Vec]) -> Vec {
fn rule(kind: RuleKind) -> RuleSpec {
RuleSpec {
kind,
- action: RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
+ action: RuleAction::Route(crate::config::RouteTargetId::Proxy(
+ crate::config::ProxyId::new(0).unwrap(),
+ )),
no_resolve: false,
}
}
diff --git a/src/lib.rs b/src/lib.rs
index 6a4a8fc..d0d6133 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -5,6 +5,8 @@
//! dispatches to one public runtime lifecycle plus private batch-measurement workers.
pub mod config;
+#[cfg(feature = "inbound-http")]
+mod controller;
pub mod data_dir;
pub mod dialer;
pub mod dispatch;
@@ -39,7 +41,7 @@ pub mod session;
mod socks5;
#[cfg(any(feature = "tun", test))]
mod tcp_sniffer;
-#[cfg(any(feature = "tun", test))]
+#[cfg(any(feature = "inbound-http", feature = "tun", test))]
pub(crate) mod traffic;
#[cfg(feature = "outbound-vless")]
pub mod transport;
@@ -62,7 +64,7 @@ pub const INVOKE_API_VERSION: u32 = 5;
/// Internal configuration schema revision reported through Invoke.
///
/// The strict Mihomo YAML subset deliberately carries no version field.
-pub const CONFIG_VERSION: u8 = 12;
+pub const CONFIG_VERSION: u8 = 13;
/// Stable implementation identifier returned by the version Invoke method.
pub const ENGINE: &str = "rust";
@@ -74,5 +76,5 @@ pub const ENGINE: &str = "rust";
pub const BUILD_IDENTITY: &str = concat!(
"VCore;engine=rust;coreVersion=",
env!("CARGO_PKG_VERSION"),
- ";invokeApiVersion=5;configVersion=12"
+ ";invokeApiVersion=5;configVersion=13"
);
diff --git a/src/routing/dispatcher.rs b/src/routing/dispatcher.rs
index 8181d50..efd6326 100644
--- a/src/routing/dispatcher.rs
+++ b/src/routing/dispatcher.rs
@@ -16,7 +16,7 @@ use tokio::{
};
use crate::{
- config::{Network, ProxyId, RuleAction},
+ config::{Network, ProxyId, RouteTargetId, RuleAction},
dispatch::{BoxStream, DatagramTransport, DispatchError, Dispatcher},
dns::{
MAX_MESSAGE_SIZE,
@@ -25,7 +25,9 @@ use crate::{
session::{Datagram, DatagramSession, Destination, InboundKind, StreamSession},
};
-use super::{GeoMatcher, RoutingContext, RuleEvaluation, RuleSet};
+use super::{
+ GeoMatcher, ProxyGroups, ResolvedProxyGroupLeaf, RoutingContext, RuleEvaluation, RuleSet,
+};
const TCP_DNS_DUPLEX_CAPACITY: usize = 8 * 1024;
@@ -59,18 +61,22 @@ fn runtime_dns_error(error: impl std::fmt::Display) -> DispatchError {
DispatchError::Other(format!("runtime DNS: {error}"))
}
-/// Runtime proxy registry. Configuration validation converts every
-/// user-facing tag into a checked [`ProxyId`].
+/// Runtime registry for concrete proxy nodes.
+///
+/// Group-aware runtime paths use the crate-private [`RouteTargetDispatchers`]
+/// name and methods while this type preserves the public node-only API.
#[derive(Clone)]
pub struct ProxyDispatchers {
- slots: Vec>,
+ proxies: Vec>,
+ groups: Vec>,
+ proxy_groups: Option>,
}
impl std::fmt::Debug for ProxyDispatchers {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter
.debug_struct("ProxyDispatchers")
- .field("len", &self.slots.len())
+ .field("len", &self.proxies.len())
.finish_non_exhaustive()
}
}
@@ -82,27 +88,86 @@ impl ProxyDispatchers {
"proxy registry must contain at least one entry".to_owned(),
));
}
- Ok(Self { slots: proxies })
+ Ok(Self {
+ proxies,
+ groups: Vec::new(),
+ proxy_groups: None,
+ })
+ }
+
+ pub(crate) fn with_proxy_groups(
+ proxies: Vec>,
+ proxy_groups: &Arc,
+ ) -> Result {
+ let mut registry = Self::new(proxies)?;
+ registry.groups = (0..proxy_groups.len())
+ .map(|index| {
+ proxy_groups.dispatcher(
+ crate::config::ProxyGroupId::new(index)
+ .expect("ProxyGroupId has no count-based ceiling"),
+ )
+ })
+ .collect();
+ registry.proxy_groups = Some(proxy_groups.clone());
+ Ok(registry)
}
#[must_use]
pub fn len(&self) -> usize {
- self.slots.len()
+ self.proxies.len()
}
#[must_use]
pub fn is_empty(&self) -> bool {
- self.slots.is_empty()
+ self.proxies.is_empty()
}
pub fn get(&self, id: ProxyId) -> Result<&Arc, DispatchError> {
- self.slots
+ self.proxies
.get(id.index())
.ok_or_else(|| DispatchError::Other(format!("unknown proxy id {}", id.index())))
}
+
+ pub(crate) fn get_route(
+ &self,
+ id: RouteTargetId,
+ ) -> Result<&Arc, DispatchError> {
+ match id {
+ RouteTargetId::Proxy(id) => self.get(id),
+ RouteTargetId::Group(id) => self.groups.get(id.index()).ok_or_else(|| {
+ DispatchError::Other(format!("unknown proxy group id {}", id.index()))
+ }),
+ }
+ }
+
+ pub(crate) fn resolve(
+ &self,
+ id: RouteTargetId,
+ ) -> Result {
+ match id {
+ RouteTargetId::Proxy(id) => self
+ .proxies
+ .get(id.index())
+ .cloned()
+ .map(|dispatcher| ResolvedProxyGroupLeaf {
+ dispatcher,
+ direct: false,
+ })
+ .ok_or_else(|| DispatchError::Other(format!("unknown proxy id {}", id.index()))),
+ RouteTargetId::Group(id) => self
+ .proxy_groups
+ .as_ref()
+ .ok_or_else(|| {
+ DispatchError::Other(format!("unknown proxy group id {}", id.index()))
+ })?
+ .resolve_leaf(id),
+ }
+ }
}
-/// Ordered VCore router backed by named proxy nodes, built-in DIRECT, and
+pub(crate) type RouteTargetDispatchers = ProxyDispatchers;
+
+/// Ordered VCore router backed by named route targets, built-in DIRECT, and
/// fail-closed REJECT actions.
///
/// The outer session observer records returned transport lifetimes without
@@ -110,7 +175,7 @@ impl ProxyDispatchers {
/// proxy id and one direct transport for each association and chooses between
/// them independently for every datagram.
pub struct RoutingDispatcher {
- proxies: ProxyDispatchers,
+ route_targets: ProxyDispatchers,
direct: Arc,
dns: Option>,
ipv6: bool,
@@ -121,18 +186,18 @@ pub struct RoutingDispatcher {
impl RoutingDispatcher {
#[must_use]
pub fn new(
- proxies: ProxyDispatchers,
+ route_targets: ProxyDispatchers,
direct: Arc,
dns: Option>,
rules: RuleSet,
geo_matcher: Arc,
) -> Self {
- Self::new_with_ipv6(proxies, direct, dns, true, rules, geo_matcher)
+ Self::new_with_ipv6(route_targets, direct, dns, true, rules, geo_matcher)
}
#[must_use]
pub(crate) fn new_with_ipv6(
- proxies: ProxyDispatchers,
+ route_targets: ProxyDispatchers,
direct: Arc,
dns: Option>,
ipv6: bool,
@@ -140,7 +205,7 @@ impl RoutingDispatcher {
geo_matcher: Arc,
) -> Self {
Self {
- proxies,
+ route_targets,
direct,
dns: dns.map(|dns| dns as Arc),
ipv6,
@@ -159,7 +224,7 @@ impl RoutingDispatcher {
geo_matcher: Arc,
) -> Self {
Self {
- proxies: ProxyDispatchers::new(vec![proxy])
+ route_targets: ProxyDispatchers::new(vec![proxy])
.expect("test proxy registry contains one entry"),
direct,
dns,
@@ -234,7 +299,7 @@ impl RoutingDispatcher {
));
};
- let mut routed_destination = match destination {
+ let routed_destination = match destination {
Destination::Domain { port, .. } => Destination::Domain {
host: context
.domain()
@@ -244,32 +309,41 @@ impl RoutingDispatcher {
},
Destination::Ip(_) => destination.clone(),
};
- if let Some(address) = context.pinned_ip() {
- routed_destination =
- Destination::Ip(std::net::SocketAddr::new(address, destination.port()));
- } else if rule_match.action == RuleAction::Direct
- && let Destination::Domain { host, port } = destination
- {
- let addresses = if let Some(addresses) = resolved.as_deref() {
- addresses
- } else {
- resolved = Some(match &self.dns {
- Some(dns) => {
- self.resolve_addresses(dns, context.domain().unwrap_or(host))
- .await
- }
- None => Vec::new(),
- });
- resolved.as_deref().unwrap_or_default()
- };
- let address = preferred_address(addresses).ok_or(DispatchError::HostUnreachable)?;
- routed_destination = Destination::Ip(std::net::SocketAddr::new(address, *port));
+ let mut decision = RouteDecision {
+ action: rule_match.action,
+ destination: context.pinned_ip().map_or(routed_destination, |address| {
+ Destination::Ip(std::net::SocketAddr::new(address, destination.port()))
+ }),
+ resolved_addresses: resolved,
+ };
+ if decision.action == RuleAction::Direct {
+ self.resolve_direct_destination(&mut decision).await?;
}
+ Ok(decision)
+ }
- Ok(RouteDecision {
- action: rule_match.action,
- destination: routed_destination,
- })
+ async fn resolve_direct_destination(
+ &self,
+ decision: &mut RouteDecision,
+ ) -> Result<(), DispatchError> {
+ let (host, port) = match &decision.destination {
+ Destination::Domain { host, port } => (host.clone(), *port),
+ Destination::Ip(_) => return Ok(()),
+ };
+ let address = if let Some(addresses) = decision.resolved_addresses.as_deref() {
+ preferred_address(addresses)
+ } else {
+ let addresses = match &self.dns {
+ Some(dns) => self.resolve_addresses(dns, &host).await,
+ None => Vec::new(),
+ };
+ let address = preferred_address(&addresses);
+ decision.resolved_addresses = Some(addresses);
+ address
+ }
+ .ok_or(DispatchError::HostUnreachable)?;
+ decision.destination = Destination::Ip(std::net::SocketAddr::new(address, port));
+ Ok(())
}
fn dns_tcp_stream(&self, dns: Arc) -> BoxStream {
@@ -357,18 +431,26 @@ impl Drop for DnsTcpStream {
struct RouteDecision {
action: RuleAction,
destination: Destination,
+ resolved_addresses: Option>,
}
fn log_route_decision(network: Network, decision: &RouteDecision) {
let destination_port = decision.destination.port();
match decision.action {
- RuleAction::Proxy(id) => tracing::debug!(
+ RuleAction::Route(RouteTargetId::Proxy(id)) => tracing::debug!(
?network,
action = "proxy",
proxy_index = id.index(),
destination_port,
"routing decision"
),
+ RuleAction::Route(RouteTargetId::Group(id)) => tracing::debug!(
+ ?network,
+ action = "proxy_group",
+ proxy_group_index = id.index(),
+ destination_port,
+ "routing decision"
+ ),
RuleAction::Direct => tracing::debug!(
?network,
action = "direct",
@@ -403,7 +485,7 @@ impl Dispatcher for RoutingDispatcher {
return Ok(self.dns_tcp_stream(dns.clone()));
}
- let decision = self
+ let mut decision = self
.route(
Network::Tcp,
session.inbound,
@@ -411,11 +493,24 @@ impl Dispatcher for RoutingDispatcher {
session.sniffed_domain.as_deref(),
)
.await?;
+ let resolved_target = match decision.action {
+ RuleAction::Route(id) => Some(self.route_targets.resolve(id)?),
+ RuleAction::Direct | RuleAction::Reject => None,
+ };
+ if resolved_target.as_ref().is_some_and(|target| target.direct) {
+ self.resolve_direct_destination(&mut decision).await?;
+ }
log_route_decision(Network::Tcp, &decision);
session.destination = decision.destination;
session.sniffed_domain = None;
match decision.action {
- RuleAction::Proxy(id) => self.proxies.get(id)?.connect_tcp(session).await,
+ RuleAction::Route(_) => {
+ resolved_target
+ .expect("route target was resolved before dispatch")
+ .dispatcher
+ .connect_tcp(session)
+ .await
+ }
RuleAction::Direct => self.direct.connect_tcp(session).await,
RuleAction::Reject => Err(DispatchError::NotAllowed),
}
@@ -428,7 +523,7 @@ impl Dispatcher for RoutingDispatcher {
Ok(Box::new(RoutedDatagramTransport {
router: self.clone_parts(),
session,
- proxy_transports: HashMap::new(),
+ route_transports: HashMap::new(),
direct_transport: None,
logged_route_actions: HashSet::new(),
receive_wakeup: Arc::new(Notify::new()),
@@ -439,7 +534,7 @@ impl Dispatcher for RoutingDispatcher {
impl RoutingDispatcher {
fn clone_parts(&self) -> Self {
Self {
- proxies: self.proxies.clone(),
+ route_targets: self.route_targets.clone(),
direct: self.direct.clone(),
dns: self.dns.clone(),
ipv6: self.ipv6,
@@ -452,15 +547,20 @@ impl RoutingDispatcher {
struct RoutedDatagramTransport {
router: RoutingDispatcher,
session: DatagramSession,
- proxy_transports: HashMap>,
+ route_transports: HashMap,
direct_transport: Option>,
logged_route_actions: HashSet,
receive_wakeup: Arc,
}
+struct CachedRouteTransport {
+ transport: Box,
+ direct: bool,
+}
+
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
enum LoggedRouteAction {
- Proxy(ProxyId),
+ Route(RouteTargetId),
Direct,
Reject,
}
@@ -468,7 +568,7 @@ enum LoggedRouteAction {
impl From for LoggedRouteAction {
fn from(action: RuleAction) -> Self {
match action {
- RuleAction::Proxy(id) => Self::Proxy(id),
+ RuleAction::Route(id) => Self::Route(id),
RuleAction::Direct => Self::Direct,
RuleAction::Reject => Self::Reject,
}
@@ -480,20 +580,44 @@ impl RoutedDatagramTransport {
self.logged_route_actions.insert(action.into())
}
- async fn send_proxy(&mut self, id: ProxyId, datagram: Datagram) -> Result<(), DispatchError> {
- if !self.proxy_transports.contains_key(&id) {
- let transport = self
- .router
- .proxies
- .get(id)?
- .open_datagram(self.session.clone())
+ async fn send_route(
+ &mut self,
+ id: RouteTargetId,
+ mut decision: RouteDecision,
+ mut datagram: Datagram,
+ ) -> Result<(), DispatchError> {
+ let direct = self.route_transports.get(&id).map(|cached| cached.direct);
+ let direct = match direct {
+ Some(direct) => direct,
+ None => {
+ let target = self.router.route_targets.resolve(id)?;
+ let direct = target.direct;
+ if direct {
+ self.router
+ .resolve_direct_destination(&mut decision)
+ .await?;
+ }
+ let transport = target
+ .dispatcher
+ .open_datagram(self.session.clone())
+ .await?;
+ self.route_transports
+ .insert(id, CachedRouteTransport { transport, direct });
+ self.receive_wakeup.notify_one();
+ direct
+ }
+ };
+ if direct && !matches!(decision.destination, Destination::Ip(_)) {
+ self.router
+ .resolve_direct_destination(&mut decision)
.await?;
- self.proxy_transports.insert(id, transport);
- self.receive_wakeup.notify_one();
}
- self.proxy_transports
+ datagram.remote = decision.destination;
+ datagram.sniffed_domain = None;
+ self.route_transports
.get_mut(&id)
- .expect("proxy transport was inserted")
+ .expect("route transport was inserted")
+ .transport
.send(datagram)
.await
}
@@ -518,9 +642,9 @@ impl RoutedDatagramTransport {
async fn receive_inner(&mut self) -> Result {
loop {
let mut receives = self
- .proxy_transports
+ .route_transports
.values_mut()
- .map(|transport| transport.receive())
+ .map(|cached| cached.transport.receive())
.collect::>();
if let Some(direct) = self.direct_transport.as_mut() {
receives.push(direct.receive());
@@ -552,11 +676,13 @@ impl DatagramTransport for RoutedDatagramTransport {
if self.should_log_route_action(decision.action) {
log_route_decision(Network::Udp, &decision);
}
- datagram.remote = decision.destination;
- datagram.sniffed_domain = None;
match decision.action {
- RuleAction::Proxy(id) => self.send_proxy(id, datagram).await,
- RuleAction::Direct => self.send_direct(datagram).await,
+ RuleAction::Route(id) => self.send_route(id, decision, datagram).await,
+ RuleAction::Direct => {
+ datagram.remote = decision.destination;
+ datagram.sniffed_domain = None;
+ self.send_direct(datagram).await
+ }
// UDP REJECT applies only to this datagram. The association stays
// alive so a later destination can select another action.
RuleAction::Reject => Ok(()),
@@ -569,8 +695,8 @@ impl DatagramTransport for RoutedDatagramTransport {
async fn close(&mut self) -> Result<(), DispatchError> {
let mut first_error = None;
- for proxy in self.proxy_transports.values_mut() {
- if let Err(error) = proxy.close().await
+ for route in self.route_transports.values_mut() {
+ if let Err(error) = route.transport.close().await
&& first_error.is_none()
{
first_error = Some(error);
@@ -582,7 +708,7 @@ impl DatagramTransport for RoutedDatagramTransport {
{
first_error = Some(error);
}
- self.proxy_transports.clear();
+ self.route_transports.clear();
self.direct_transport = None;
if let Some(error) = first_error {
Err(error)
@@ -603,14 +729,15 @@ mod tests {
},
};
- use bytes::Bytes;
- use tokio::io::{AsyncReadExt as _, AsyncWriteExt as _};
-
use super::*;
use crate::{
- config::{IpCidr, PortRange, RuleKind, RuleSpec},
+ config::{
+ IpCidr, PortRange, ProxyGroupId, ProxyGroupMemberConfig, ProxyGroupMemberTarget,
+ ProxyId, RuleKind, RuleSpec, SelectProxyGroupConfig,
+ },
routing::EmptyGeoMatcher,
};
+ use bytes::Bytes;
#[derive(Default)]
struct RecordingDispatcher {
@@ -770,6 +897,31 @@ mod tests {
}
}
+ fn proxy_action(index: usize) -> RuleAction {
+ RuleAction::Route(RouteTargetId::Proxy(ProxyId::new(index).unwrap()))
+ }
+
+ fn group_action(index: usize) -> RuleAction {
+ RuleAction::Route(RouteTargetId::Group(ProxyGroupId::new(index).unwrap()))
+ }
+
+ fn select_group(
+ name: &str,
+ members: Vec<(&str, ProxyGroupMemberTarget)>,
+ ) -> SelectProxyGroupConfig {
+ SelectProxyGroupConfig {
+ name: name.to_owned(),
+ members: members
+ .into_iter()
+ .map(|(name, target)| ProxyGroupMemberConfig {
+ name: name.to_owned(),
+ target,
+ })
+ .collect(),
+ initial_member: 0,
+ }
+ }
+
fn dispatcher(
proxy: Arc,
direct: Arc,
@@ -829,6 +981,120 @@ mod tests {
assert!(registry.get(ProxyId::new(300).unwrap()).is_err());
}
+ #[tokio::test]
+ async fn group_route_snapshots_direct_dns_for_tcp() {
+ let proxy = Arc::new(RecordingDispatcher::default());
+ let direct = Arc::new(RecordingDispatcher::default());
+ let groups = ProxyGroups::new(
+ &[select_group(
+ "route",
+ vec![("DIRECT", ProxyGroupMemberTarget::Direct)],
+ )],
+ vec![proxy.clone()],
+ direct.clone(),
+ )
+ .unwrap();
+ let targets = RouteTargetDispatchers::with_proxy_groups(vec![proxy], &groups).unwrap();
+ let dns = Arc::new(MockDns::new(vec![IpAddr::V4(Ipv4Addr::new(
+ 203, 0, 113, 9,
+ ))]));
+ let router = RoutingDispatcher {
+ route_targets: targets,
+ direct: direct.clone(),
+ dns: Some(dns.clone()),
+ ipv6: true,
+ rules: Arc::new(
+ RuleSet::compile(vec![rule(RuleKind::Match, group_action(0))]).unwrap(),
+ ),
+ geo_matcher: Arc::new(EmptyGeoMatcher),
+ };
+
+ router
+ .connect_tcp(StreamSession {
+ inbound: InboundKind::Http,
+ source: "127.0.0.1:10000".parse().unwrap(),
+ destination: Destination::domain("example.com", 443).unwrap(),
+ sniffed_domain: None,
+ })
+ .await
+ .unwrap();
+
+ assert_eq!(dns.resolve_calls.load(Ordering::Relaxed), 1);
+ assert_eq!(
+ direct.tcp_sessions.lock().unwrap()[0].destination,
+ Destination::Ip("203.0.113.9:443".parse().unwrap())
+ );
+ }
+
+ #[tokio::test]
+ async fn group_route_keeps_existing_udp_transport_after_selection_changes() {
+ let first = Arc::new(RecordingDispatcher::default());
+ let second = Arc::new(RecordingDispatcher::default());
+ let direct = Arc::new(RecordingDispatcher::default());
+ let proxy_dispatchers = vec![
+ first.clone() as Arc,
+ second.clone() as Arc,
+ ];
+ let groups = ProxyGroups::new(
+ &[select_group(
+ "route",
+ vec![
+ (
+ "first",
+ ProxyGroupMemberTarget::Route(RouteTargetId::Proxy(
+ ProxyId::new(0).unwrap(),
+ )),
+ ),
+ (
+ "second",
+ ProxyGroupMemberTarget::Route(RouteTargetId::Proxy(
+ ProxyId::new(1).unwrap(),
+ )),
+ ),
+ ],
+ )],
+ proxy_dispatchers.clone(),
+ direct.clone(),
+ )
+ .unwrap();
+ let targets =
+ RouteTargetDispatchers::with_proxy_groups(proxy_dispatchers, &groups).unwrap();
+ let router = RoutingDispatcher::new(
+ targets,
+ direct,
+ None,
+ RuleSet::compile(vec![rule(RuleKind::Match, group_action(0))]).unwrap(),
+ Arc::new(EmptyGeoMatcher),
+ );
+ let mut old_association = router
+ .open_datagram(association(InboundKind::Http))
+ .await
+ .unwrap();
+
+ old_association
+ .send(datagram("192.0.2.1:443".parse().unwrap(), b"old"))
+ .await
+ .unwrap();
+ groups.select("route", "second").unwrap();
+ old_association
+ .send(datagram("192.0.2.1:443".parse().unwrap(), b"still-old"))
+ .await
+ .unwrap();
+ let mut new_association = router
+ .open_datagram(association(InboundKind::Http))
+ .await
+ .unwrap();
+ new_association
+ .send(datagram("192.0.2.1:443".parse().unwrap(), b"new"))
+ .await
+ .unwrap();
+
+ assert_eq!(first.udp_opens.load(Ordering::Relaxed), 1);
+ assert_eq!(first.datagrams.lock().unwrap().len(), 2);
+ assert_eq!(second.udp_opens.load(Ordering::Relaxed), 1);
+ assert_eq!(second.datagrams.lock().unwrap().len(), 1);
+ }
+
fn stream(destination: SocketAddr, inbound: InboundKind) -> StreamSession {
StreamSession {
inbound,
@@ -875,10 +1141,7 @@ mod tests {
RuleKind::DstPorts(vec![PortRange { start: 25, end: 25 }]),
RuleAction::Reject,
),
- rule(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
+ rule(RuleKind::Match, proxy_action(0)),
],
);
@@ -916,10 +1179,7 @@ mod tests {
RuleKind::DstPorts(vec![PortRange { start: 80, end: 80 }]),
RuleAction::Direct,
),
- rule(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
+ rule(RuleKind::Match, proxy_action(0)),
],
);
@@ -1009,10 +1269,7 @@ mod tests {
}),
RuleAction::Direct,
),
- rule(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
+ rule(RuleKind::Match, proxy_action(0)),
],
);
@@ -1051,10 +1308,7 @@ mod tests {
RuleKind::DomainSuffix("example.com".to_owned()),
RuleAction::Direct,
),
- rule(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
+ rule(RuleKind::Match, proxy_action(0)),
],
);
@@ -1096,10 +1350,7 @@ mod tests {
RuleKind::DomainSuffix("example.com".to_owned()),
RuleAction::Direct,
),
- rule(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
+ rule(RuleKind::Match, proxy_action(0)),
],
);
let mut transport = router
@@ -1144,10 +1395,7 @@ mod tests {
RuleKind::Domain("hint.example".to_owned()),
RuleAction::Direct,
),
- rule(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
+ rule(RuleKind::Match, proxy_action(0)),
],
);
@@ -1200,10 +1448,7 @@ mod tests {
proxy.clone(),
direct,
Some(dns.clone()),
- vec![rule(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- )],
+ vec![rule(RuleKind::Match, proxy_action(0))],
);
router
@@ -1233,17 +1478,17 @@ mod tests {
vec![
rule(
RuleKind::DstPorts(vec![PortRange { start: 80, end: 80 }]),
- RuleAction::Proxy(ProxyId::new(3).unwrap()),
+ proxy_action(3),
),
rule(
RuleKind::DstPorts(vec![PortRange { start: 81, end: 81 }]),
- RuleAction::Proxy(ProxyId::new(2).unwrap()),
+ proxy_action(2),
),
rule(
RuleKind::DstPorts(vec![PortRange { start: 82, end: 82 }]),
- RuleAction::Proxy(ProxyId::new(1).unwrap()),
+ proxy_action(1),
),
- rule(RuleKind::Match, RuleAction::Proxy(ProxyId::new(0).unwrap())),
+ rule(RuleKind::Match, proxy_action(0)),
],
);
@@ -1281,23 +1526,23 @@ mod tests {
vec![
rule(
RuleKind::DstPorts(vec![PortRange { start: 53, end: 53 }]),
- RuleAction::Proxy(ProxyId::new(3).unwrap()),
+ proxy_action(3),
),
rule(
RuleKind::DstPorts(vec![PortRange {
start: 123,
end: 123,
}]),
- RuleAction::Proxy(ProxyId::new(2).unwrap()),
+ proxy_action(2),
),
rule(
RuleKind::DstPorts(vec![PortRange {
start: 500,
end: 500,
}]),
- RuleAction::Proxy(ProxyId::new(1).unwrap()),
+ proxy_action(1),
),
- rule(RuleKind::Match, RuleAction::Proxy(ProxyId::new(0).unwrap())),
+ rule(RuleKind::Match, proxy_action(0)),
],
);
let mut transport = router
@@ -1391,10 +1636,7 @@ mod tests {
proxy.clone(),
Arc::new(RecordingDispatcher::default()),
None,
- vec![rule(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- )],
+ vec![rule(RuleKind::Match, proxy_action(0))],
);
router
.connect_tcp(StreamSession {
@@ -1427,10 +1669,7 @@ mod tests {
}),
RuleAction::Direct,
),
- rule(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
+ rule(RuleKind::Match, proxy_action(0)),
],
);
let mut transport = router
@@ -1463,10 +1702,7 @@ mod tests {
Arc::new(RecordingDispatcher::default()),
Arc::new(RecordingDispatcher::default()),
None,
- vec![rule(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- )],
+ vec![rule(RuleKind::Match, proxy_action(0))],
);
let association_router = router.clone_parts();
@@ -1486,10 +1722,7 @@ mod tests {
RuleKind::DstPorts(vec![PortRange { start: 9, end: 9 }]),
RuleAction::Reject,
),
- rule(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
+ rule(RuleKind::Match, proxy_action(0)),
],
);
let mut transport = router
@@ -1519,10 +1752,7 @@ mod tests {
proxy.clone(),
direct,
Some(dns.clone()),
- vec![rule(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- )],
+ vec![rule(RuleKind::Match, proxy_action(0))],
);
let mut tun_udp = router
@@ -1575,10 +1805,7 @@ mod tests {
Arc::new(RecordingDispatcher::default()),
Arc::new(RecordingDispatcher::default()),
Some(dns.clone()),
- vec![rule(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- )],
+ vec![rule(RuleKind::Match, proxy_action(0))],
);
let mut stream = router
.connect_tcp(stream("1.1.1.1:53".parse().unwrap(), InboundKind::Tun))
@@ -1625,10 +1852,7 @@ mod tests {
proxy,
direct,
Some(dns.clone()),
- vec![rule(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- )],
+ vec![rule(RuleKind::Match, proxy_action(0))],
);
let mut stream = router
@@ -1682,10 +1906,7 @@ mod tests {
}),
RuleAction::Reject,
),
- rule(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
+ rule(RuleKind::Match, proxy_action(0)),
],
);
@@ -1739,10 +1960,7 @@ mod tests {
RuleAction::Reject,
),
later_no_resolve,
- rule(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
+ rule(RuleKind::Match, proxy_action(0)),
],
);
@@ -1803,10 +2021,7 @@ mod tests {
RuleAction::Reject,
),
later_no_resolve,
- rule(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
+ rule(RuleKind::Match, proxy_action(0)),
],
);
diff --git a/src/routing/mod.rs b/src/routing/mod.rs
index 9dd4020..8c9841e 100644
--- a/src/routing/mod.rs
+++ b/src/routing/mod.rs
@@ -13,8 +13,13 @@ use crate::{
};
mod dispatcher;
+mod proxy_group;
+pub(crate) use dispatcher::RouteTargetDispatchers;
pub use dispatcher::{ProxyDispatchers, RoutingDispatcher};
+pub(crate) use proxy_group::{
+ ProxyGroupError, ProxyGroupState, ProxyGroups, ResolvedProxyGroupLeaf,
+};
/// Defensive runtime ceiling, independent from the configuration parser.
pub const MAX_ROUTING_RULES: usize = crate::config::MAX_RULES;
@@ -668,6 +673,12 @@ mod tests {
}
}
+ fn proxy_action(index: usize) -> RuleAction {
+ RuleAction::Route(crate::config::RouteTargetId::Proxy(
+ crate::config::ProxyId::new(index).unwrap(),
+ ))
+ }
+
fn domain_context(network: Network, host: &str, port: u16) -> RoutingContext {
let destination = Destination::domain(host, port).unwrap();
RoutingContext::new(network, &destination).unwrap()
@@ -691,10 +702,7 @@ mod tests {
RuleKind::DomainSuffix("example.com".to_owned()),
RuleAction::Reject,
),
- spec(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
+ spec(RuleKind::Match, proxy_action(0)),
])
.unwrap();
@@ -709,10 +717,7 @@ mod tests {
RuleKind::DomainSuffix("example.com".to_owned()),
RuleAction::Direct,
),
- spec(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
+ spec(RuleKind::Match, proxy_action(0)),
])
.unwrap();
@@ -726,7 +731,7 @@ mod tests {
);
assert_eq!(
action(rules.evaluate(&domain_context(Network::Tcp, "badexample.com", 443))),
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap())
+ proxy_action(0)
);
}
@@ -747,10 +752,7 @@ mod tests {
}),
RuleAction::Reject,
),
- spec(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
+ spec(RuleKind::Match, proxy_action(0)),
])
.unwrap();
@@ -767,7 +769,7 @@ mod tests {
);
assert_eq!(
action(rules.evaluate(&RoutingContext::new(Network::Tcp, &public).unwrap())),
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap())
+ proxy_action(0)
);
}
@@ -784,10 +786,7 @@ mod tests {
]),
RuleAction::Reject,
),
- spec(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
+ spec(RuleKind::Match, proxy_action(0)),
])
.unwrap();
@@ -801,7 +800,7 @@ mod tests {
);
assert_eq!(
action(rules.evaluate(&domain_context(Network::Tcp, "web.example", 80))),
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap())
+ proxy_action(0)
);
}
@@ -809,10 +808,7 @@ mod tests {
fn network_rule_distinguishes_tcp_and_udp() {
let rules = RuleSet::compile(vec![
spec(RuleKind::Network(Network::Udp), RuleAction::Reject),
- spec(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
+ spec(RuleKind::Match, proxy_action(0)),
])
.unwrap();
@@ -822,7 +818,7 @@ mod tests {
);
assert_eq!(
action(rules.evaluate(&domain_context(Network::Tcp, "example.com", 53))),
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap())
+ proxy_action(0)
);
}
@@ -892,10 +888,7 @@ mod tests {
);
let rules = RuleSet::compile(vec![
resolvable.clone(),
- spec(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
+ spec(RuleKind::Match, proxy_action(0)),
])
.unwrap();
let mut context = domain_context(Network::Tcp, "example.com", 443);
@@ -904,23 +897,14 @@ mod tests {
RuleEvaluation::NeedsIpResolution { rule_index: 0 }
);
context.mark_ip_resolution_unavailable();
- assert_eq!(
- action(rules.evaluate(&context)),
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap())
- );
+ assert_eq!(action(rules.evaluate(&context)), proxy_action(0));
resolvable.no_resolve = true;
- let rules = RuleSet::compile(vec![
- resolvable,
- spec(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
- ])
- .unwrap();
+ let rules =
+ RuleSet::compile(vec![resolvable, spec(RuleKind::Match, proxy_action(0))]).unwrap();
assert_eq!(
action(rules.evaluate(&domain_context(Network::Tcp, "example.com", 443))),
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap())
+ proxy_action(0)
);
}
@@ -943,10 +927,7 @@ mod tests {
RuleAction::Direct,
),
later_no_resolve,
- spec(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
+ spec(RuleKind::Match, proxy_action(0)),
])
.unwrap();
let mut context = domain_context(Network::Tcp, "example.com", 443);
@@ -989,10 +970,7 @@ mod tests {
}),
RuleAction::Direct,
),
- spec(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
+ spec(RuleKind::Match, proxy_action(0)),
])
.unwrap();
let mut context = domain_context(Network::Tcp, "example.com", 443);
@@ -1009,7 +987,7 @@ mod tests {
&[IpAddr::V4(Ipv4Addr::new(10, 0, 0, 7))],
),
RuleEvaluation::Matched(RuleMatch {
- action: RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
+ action: proxy_action(0),
rule_index: 2,
})
);
@@ -1020,15 +998,12 @@ mod tests {
fn absent_geodata_never_matches() {
let rules = RuleSet::compile(vec![
spec(RuleKind::GeoSite("CN".to_owned()), RuleAction::Direct),
- spec(
- RuleKind::Match,
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap()),
- ),
+ spec(RuleKind::Match, proxy_action(0)),
])
.unwrap();
assert_eq!(
action(rules.evaluate(&domain_context(Network::Tcp, "example.cn", 443))),
- RuleAction::Proxy(crate::config::ProxyId::new(0).unwrap())
+ proxy_action(0)
);
}
@@ -1037,14 +1012,17 @@ mod tests {
let proxy = crate::config::ProxyId::new(0).unwrap();
let rules = RuleSet::compile(vec![
spec(RuleKind::GeoIp("cn".to_owned()), RuleAction::Direct),
- spec(RuleKind::Match, RuleAction::Proxy(proxy)),
+ spec(
+ RuleKind::Match,
+ RuleAction::Route(crate::config::RouteTargetId::Proxy(proxy)),
+ ),
])
.unwrap();
let context = domain_context(Network::Tcp, "example.com", 443);
assert_eq!(
rules.evaluate_with_geo(&context, &EmptyGeoMatcher),
RuleEvaluation::Matched(RuleMatch {
- action: RuleAction::Proxy(proxy),
+ action: RuleAction::Route(crate::config::RouteTargetId::Proxy(proxy)),
rule_index: 1,
})
);
diff --git a/src/routing/proxy_group.rs b/src/routing/proxy_group.rs
new file mode 100644
index 0000000..e04db36
--- /dev/null
+++ b/src/routing/proxy_group.rs
@@ -0,0 +1,695 @@
+use std::{
+ collections::HashMap,
+ fmt,
+ sync::{
+ Arc,
+ atomic::{AtomicUsize, Ordering},
+ },
+};
+
+use async_trait::async_trait;
+
+use crate::{
+ config::{ProxyGroupId, ProxyGroupMemberTarget, RouteTargetId, SelectProxyGroupConfig},
+ dispatch::{BoxStream, DatagramTransport, DispatchError, Dispatcher},
+ session::{Datagram, DatagramSession, StreamSession},
+};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct ProxyGroupState {
+ pub(crate) name: String,
+ pub(crate) all: Vec,
+ pub(crate) now: String,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum ProxyGroupError {
+ UnknownGroup,
+ UnknownMember,
+}
+
+impl fmt::Display for ProxyGroupError {
+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+ formatter.write_str(match self {
+ Self::UnknownGroup => "unknown proxy group",
+ Self::UnknownMember => "unknown proxy group member",
+ })
+ }
+}
+
+impl std::error::Error for ProxyGroupError {}
+
+struct SelectProxyGroup {
+ name: String,
+ members: Box<[ProxyGroupMember]>,
+ selected: AtomicUsize,
+}
+
+struct ProxyGroupMember {
+ name: String,
+ target: ProxyGroupMemberTarget,
+}
+
+pub(crate) struct ResolvedProxyGroupLeaf {
+ pub(crate) dispatcher: Arc,
+ pub(crate) direct: bool,
+}
+
+/// Immutable select-group graph with one atomically replaceable member index
+/// per group. Concrete node dispatchers and DIRECT are shared with the rest of
+/// the runtime; groups own no protocol resources or background tasks.
+pub(crate) struct ProxyGroups {
+ proxies: Box<[Arc]>,
+ direct: Arc,
+ reject: Arc,
+ groups: Box<[SelectProxyGroup]>,
+ ids_by_name: HashMap,
+}
+
+impl fmt::Debug for ProxyGroups {
+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+ formatter
+ .debug_struct("ProxyGroups")
+ .field("proxies", &self.proxies.len())
+ .field("groups", &self.groups.len())
+ .finish_non_exhaustive()
+ }
+}
+
+impl ProxyGroups {
+ pub(crate) fn new(
+ configs: &[SelectProxyGroupConfig],
+ proxies: Vec>,
+ direct: Arc,
+ ) -> Result, DispatchError> {
+ let mut ids_by_name = HashMap::with_capacity(configs.len());
+ for (index, config) in configs.iter().enumerate() {
+ if config.members.is_empty() || config.initial_member >= config.members.len() {
+ return Err(DispatchError::Other(format!(
+ "proxy group {index} has invalid members or initial selection"
+ )));
+ }
+ if ids_by_name
+ .insert(
+ config.name.clone(),
+ ProxyGroupId::new(index).expect("ProxyGroupId has no count-based ceiling"),
+ )
+ .is_some()
+ {
+ return Err(DispatchError::Other(format!(
+ "duplicate proxy group at index {index}"
+ )));
+ }
+ for member in &config.members {
+ match member.target {
+ ProxyGroupMemberTarget::Route(RouteTargetId::Proxy(id))
+ if id.index() >= proxies.len() =>
+ {
+ return Err(DispatchError::Other(format!(
+ "proxy group {index} references unknown proxy id {}",
+ id.index()
+ )));
+ }
+ ProxyGroupMemberTarget::Route(RouteTargetId::Group(id))
+ if id.index() >= configs.len() =>
+ {
+ return Err(DispatchError::Other(format!(
+ "proxy group {index} references unknown group id {}",
+ id.index()
+ )));
+ }
+ _ => {}
+ }
+ }
+ }
+
+ Ok(Arc::new(Self {
+ proxies: proxies.into_boxed_slice(),
+ direct,
+ reject: Arc::new(RejectDispatcher),
+ groups: configs
+ .iter()
+ .map(|config| SelectProxyGroup {
+ name: config.name.clone(),
+ members: config
+ .members
+ .iter()
+ .map(|member| ProxyGroupMember {
+ name: member.name.clone(),
+ target: member.target,
+ })
+ .collect(),
+ selected: AtomicUsize::new(config.initial_member),
+ })
+ .collect(),
+ ids_by_name,
+ }))
+ }
+
+ #[must_use]
+ pub(crate) fn len(&self) -> usize {
+ self.groups.len()
+ }
+
+ pub(crate) fn list_states(&self) -> Vec {
+ self.groups.iter().map(SelectProxyGroup::state).collect()
+ }
+
+ pub(crate) fn state(&self, group: &str) -> Result {
+ let id = self
+ .ids_by_name
+ .get(group)
+ .copied()
+ .ok_or(ProxyGroupError::UnknownGroup)?;
+ Ok(self.groups[id.index()].state())
+ }
+
+ pub(crate) fn select(&self, group: &str, member: &str) -> Result<(), ProxyGroupError> {
+ let id = self
+ .ids_by_name
+ .get(group)
+ .copied()
+ .ok_or(ProxyGroupError::UnknownGroup)?;
+ let group = &self.groups[id.index()];
+ let selected = group
+ .members
+ .iter()
+ .position(|candidate| candidate.name == member)
+ .ok_or(ProxyGroupError::UnknownMember)?;
+ group.selected.store(selected, Ordering::Release);
+ Ok(())
+ }
+
+ pub(crate) fn resolve_leaf(
+ &self,
+ mut group_id: ProxyGroupId,
+ ) -> Result {
+ for _ in 0..=self.groups.len() {
+ let group = self.groups.get(group_id.index()).ok_or_else(|| {
+ DispatchError::Other(format!("unknown proxy group id {}", group_id.index()))
+ })?;
+ let selected = group.selected.load(Ordering::Acquire);
+ let member = group.members.get(selected).ok_or_else(|| {
+ DispatchError::Other(format!(
+ "proxy group {} has invalid selected index {selected}",
+ group_id.index()
+ ))
+ })?;
+ match member.target {
+ ProxyGroupMemberTarget::Route(RouteTargetId::Proxy(id)) => {
+ return self
+ .proxies
+ .get(id.index())
+ .cloned()
+ .map(|dispatcher| ResolvedProxyGroupLeaf {
+ dispatcher,
+ direct: false,
+ })
+ .ok_or_else(|| {
+ DispatchError::Other(format!("unknown proxy id {}", id.index()))
+ });
+ }
+ ProxyGroupMemberTarget::Route(RouteTargetId::Group(id)) => group_id = id,
+ ProxyGroupMemberTarget::Direct => {
+ return Ok(ResolvedProxyGroupLeaf {
+ dispatcher: self.direct.clone(),
+ direct: true,
+ });
+ }
+ ProxyGroupMemberTarget::Reject => {
+ return Ok(ResolvedProxyGroupLeaf {
+ dispatcher: self.reject.clone(),
+ direct: false,
+ });
+ }
+ }
+ }
+ Err(DispatchError::Other(
+ "proxy group nesting exceeded the runtime hop ceiling".to_owned(),
+ ))
+ }
+
+ pub(super) fn dispatcher(self: &Arc, id: ProxyGroupId) -> Arc {
+ Arc::new(SelectProxyGroupDispatcher {
+ groups: self.clone(),
+ id,
+ })
+ }
+}
+
+impl SelectProxyGroup {
+ fn state(&self) -> ProxyGroupState {
+ let selected = self.selected.load(Ordering::Acquire);
+ ProxyGroupState {
+ name: self.name.clone(),
+ all: self
+ .members
+ .iter()
+ .map(|member| member.name.clone())
+ .collect(),
+ now: self.members[selected].name.clone(),
+ }
+ }
+}
+
+struct SelectProxyGroupDispatcher {
+ groups: Arc,
+ id: ProxyGroupId,
+}
+
+#[async_trait]
+impl Dispatcher for SelectProxyGroupDispatcher {
+ async fn connect_tcp(&self, session: StreamSession) -> Result {
+ self.groups
+ .resolve_leaf(self.id)?
+ .dispatcher
+ .connect_tcp(session)
+ .await
+ }
+
+ async fn open_datagram(
+ &self,
+ session: DatagramSession,
+ ) -> Result, DispatchError> {
+ self.groups
+ .resolve_leaf(self.id)?
+ .dispatcher
+ .open_datagram(session)
+ .await
+ }
+}
+
+struct RejectDispatcher;
+
+#[async_trait]
+impl Dispatcher for RejectDispatcher {
+ async fn connect_tcp(&self, _session: StreamSession) -> Result {
+ Err(DispatchError::NotAllowed)
+ }
+
+ async fn open_datagram(
+ &self,
+ _session: DatagramSession,
+ ) -> Result, DispatchError> {
+ Ok(Box::new(RejectDatagramTransport))
+ }
+}
+
+struct RejectDatagramTransport;
+
+#[async_trait]
+impl DatagramTransport for RejectDatagramTransport {
+ async fn send(&mut self, _datagram: Datagram) -> Result<(), DispatchError> {
+ Ok(())
+ }
+
+ async fn receive(&mut self) -> Result {
+ std::future::pending().await
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use std::{
+ net::SocketAddr,
+ sync::atomic::{AtomicUsize, Ordering},
+ time::Duration,
+ };
+
+ use bytes::Bytes;
+ use tokio::sync::Semaphore;
+
+ use super::*;
+ use crate::{
+ config::{ProxyGroupMemberConfig, ProxyId},
+ session::{Destination, InboundKind},
+ };
+
+ #[derive(Default)]
+ struct RecordingDispatcher {
+ tcp_calls: AtomicUsize,
+ udp_opens: AtomicUsize,
+ udp_sends: Arc,
+ }
+
+ #[async_trait]
+ impl Dispatcher for RecordingDispatcher {
+ async fn connect_tcp(&self, _session: StreamSession) -> Result {
+ self.tcp_calls.fetch_add(1, Ordering::Relaxed);
+ let (client, _server) = tokio::io::duplex(1);
+ Ok(Box::new(client))
+ }
+
+ async fn open_datagram(
+ &self,
+ _session: DatagramSession,
+ ) -> Result, DispatchError> {
+ self.udp_opens.fetch_add(1, Ordering::Relaxed);
+ Ok(Box::new(RecordingDatagramTransport {
+ sends: self.udp_sends.clone(),
+ }))
+ }
+ }
+
+ struct RecordingDatagramTransport {
+ sends: Arc,
+ }
+
+ #[async_trait]
+ impl DatagramTransport for RecordingDatagramTransport {
+ async fn send(&mut self, _datagram: Datagram) -> Result<(), DispatchError> {
+ self.sends.fetch_add(1, Ordering::Relaxed);
+ Ok(())
+ }
+
+ async fn receive(&mut self) -> Result {
+ std::future::pending().await
+ }
+ }
+
+ struct GatedDispatcher {
+ calls: AtomicUsize,
+ started: Semaphore,
+ release: Semaphore,
+ }
+
+ struct FailingDispatcher;
+
+ #[async_trait]
+ impl Dispatcher for FailingDispatcher {
+ async fn connect_tcp(&self, _session: StreamSession) -> Result {
+ Err(DispatchError::HostUnreachable)
+ }
+
+ async fn open_datagram(
+ &self,
+ _session: DatagramSession,
+ ) -> Result, DispatchError> {
+ Err(DispatchError::NetworkUnreachable)
+ }
+ }
+
+ impl GatedDispatcher {
+ fn new() -> Self {
+ Self {
+ calls: AtomicUsize::new(0),
+ started: Semaphore::new(0),
+ release: Semaphore::new(0),
+ }
+ }
+ }
+
+ #[async_trait]
+ impl Dispatcher for GatedDispatcher {
+ async fn connect_tcp(&self, _session: StreamSession) -> Result {
+ self.calls.fetch_add(1, Ordering::Relaxed);
+ self.started.add_permits(1);
+ self.release.acquire().await.unwrap().forget();
+ let (client, _server) = tokio::io::duplex(1);
+ Ok(Box::new(client))
+ }
+
+ async fn open_datagram(
+ &self,
+ _session: DatagramSession,
+ ) -> Result, DispatchError> {
+ unreachable!()
+ }
+ }
+
+ fn member(name: &str, target: ProxyGroupMemberTarget) -> ProxyGroupMemberConfig {
+ ProxyGroupMemberConfig {
+ name: name.to_owned(),
+ target,
+ }
+ }
+
+ fn group(
+ name: &str,
+ members: Vec,
+ initial_member: usize,
+ ) -> SelectProxyGroupConfig {
+ SelectProxyGroupConfig {
+ name: name.to_owned(),
+ members,
+ initial_member,
+ }
+ }
+
+ fn stream_session() -> StreamSession {
+ StreamSession {
+ inbound: InboundKind::Http,
+ source: "127.0.0.1:10000".parse().unwrap(),
+ destination: Destination::Ip("192.0.2.1:443".parse().unwrap()),
+ sniffed_domain: None,
+ }
+ }
+
+ fn datagram_session() -> DatagramSession {
+ DatagramSession::new(InboundKind::Http, "127.0.0.1:10000".parse().unwrap())
+ }
+
+ fn datagram() -> Datagram {
+ Datagram {
+ remote: Destination::Ip("192.0.2.1:443".parse::().unwrap()),
+ payload: Bytes::from_static(b"payload"),
+ sniffed_domain: None,
+ }
+ }
+
+ #[tokio::test]
+ async fn nested_selection_preserves_duplicates_and_snapshots_new_transports() {
+ let first = Arc::new(RecordingDispatcher::default());
+ let second = Arc::new(RecordingDispatcher::default());
+ let direct = Arc::new(RecordingDispatcher::default());
+ let configs = [
+ group(
+ "child",
+ vec![
+ member(
+ "first",
+ ProxyGroupMemberTarget::Route(RouteTargetId::Proxy(
+ ProxyId::new(0).unwrap(),
+ )),
+ ),
+ member(
+ "first",
+ ProxyGroupMemberTarget::Route(RouteTargetId::Proxy(
+ ProxyId::new(0).unwrap(),
+ )),
+ ),
+ member(
+ "second",
+ ProxyGroupMemberTarget::Route(RouteTargetId::Proxy(
+ ProxyId::new(1).unwrap(),
+ )),
+ ),
+ ],
+ 2,
+ ),
+ group(
+ "parent",
+ vec![
+ member(
+ "child",
+ ProxyGroupMemberTarget::Route(RouteTargetId::Group(
+ ProxyGroupId::new(0).unwrap(),
+ )),
+ ),
+ member("DIRECT", ProxyGroupMemberTarget::Direct),
+ member("REJECT", ProxyGroupMemberTarget::Reject),
+ ],
+ 0,
+ ),
+ ];
+ let groups = ProxyGroups::new(
+ &configs,
+ vec![first.clone(), second.clone()],
+ direct.clone(),
+ )
+ .unwrap();
+ let parent = groups.dispatcher(ProxyGroupId::new(1).unwrap());
+
+ assert_eq!(
+ groups.list_states(),
+ vec![
+ ProxyGroupState {
+ name: "child".to_owned(),
+ all: vec!["first".to_owned(), "first".to_owned(), "second".to_owned()],
+ now: "second".to_owned(),
+ },
+ ProxyGroupState {
+ name: "parent".to_owned(),
+ all: vec!["child".to_owned(), "DIRECT".to_owned(), "REJECT".to_owned()],
+ now: "child".to_owned(),
+ },
+ ]
+ );
+ assert_eq!(
+ groups.select("missing", "first"),
+ Err(ProxyGroupError::UnknownGroup)
+ );
+ assert_eq!(
+ groups.select("child", "missing"),
+ Err(ProxyGroupError::UnknownMember)
+ );
+ assert_eq!(groups.state("child").unwrap().now, "second");
+
+ let mut old_udp = parent.open_datagram(datagram_session()).await.unwrap();
+ groups.select("child", "first").unwrap();
+ assert_eq!(
+ groups.groups[0].selected.load(Ordering::Acquire),
+ 0,
+ "duplicate selection must resolve to the first matching member"
+ );
+ old_udp.send(datagram()).await.unwrap();
+ let mut new_udp = parent.open_datagram(datagram_session()).await.unwrap();
+ new_udp.send(datagram()).await.unwrap();
+
+ assert_eq!(second.udp_opens.load(Ordering::Relaxed), 1);
+ assert_eq!(second.udp_sends.load(Ordering::Relaxed), 1);
+ assert_eq!(first.udp_opens.load(Ordering::Relaxed), 1);
+ assert_eq!(first.udp_sends.load(Ordering::Relaxed), 1);
+
+ groups.select("parent", "DIRECT").unwrap();
+ parent.connect_tcp(stream_session()).await.unwrap();
+ assert_eq!(direct.tcp_calls.load(Ordering::Relaxed), 1);
+
+ groups.select("parent", "REJECT").unwrap();
+ assert!(matches!(
+ parent.connect_tcp(stream_session()).await,
+ Err(DispatchError::NotAllowed)
+ ));
+ let mut rejected = parent.open_datagram(datagram_session()).await.unwrap();
+ rejected.send(datagram()).await.unwrap();
+ assert!(
+ tokio::time::timeout(Duration::from_millis(10), rejected.receive())
+ .await
+ .is_err()
+ );
+ }
+
+ #[tokio::test]
+ async fn in_flight_tcp_keeps_the_leaf_selected_before_await() {
+ let old = Arc::new(GatedDispatcher::new());
+ let new = Arc::new(RecordingDispatcher::default());
+ let direct = Arc::new(RecordingDispatcher::default());
+ let groups = ProxyGroups::new(
+ &[group(
+ "group",
+ vec![
+ member(
+ "old",
+ ProxyGroupMemberTarget::Route(RouteTargetId::Proxy(
+ ProxyId::new(0).unwrap(),
+ )),
+ ),
+ member(
+ "new",
+ ProxyGroupMemberTarget::Route(RouteTargetId::Proxy(
+ ProxyId::new(1).unwrap(),
+ )),
+ ),
+ ],
+ 0,
+ )],
+ vec![old.clone(), new.clone()],
+ direct,
+ )
+ .unwrap();
+ let dispatcher = groups.dispatcher(ProxyGroupId::new(0).unwrap());
+ let pending = tokio::spawn({
+ let dispatcher = dispatcher.clone();
+ async move { dispatcher.connect_tcp(stream_session()).await }
+ });
+ old.started.acquire().await.unwrap().forget();
+
+ groups.select("group", "new").unwrap();
+ old.release.add_permits(1);
+ pending.await.unwrap().unwrap();
+ dispatcher.connect_tcp(stream_session()).await.unwrap();
+
+ assert_eq!(old.calls.load(Ordering::Relaxed), 1);
+ assert_eq!(new.tcp_calls.load(Ordering::Relaxed), 1);
+ }
+
+ #[tokio::test]
+ async fn selected_member_failure_does_not_fallback_or_change_selection() {
+ let fallback = Arc::new(RecordingDispatcher::default());
+ let direct = Arc::new(RecordingDispatcher::default());
+ let groups = ProxyGroups::new(
+ &[group(
+ "group",
+ vec![
+ member(
+ "failing",
+ ProxyGroupMemberTarget::Route(RouteTargetId::Proxy(
+ ProxyId::new(0).unwrap(),
+ )),
+ ),
+ member(
+ "fallback",
+ ProxyGroupMemberTarget::Route(RouteTargetId::Proxy(
+ ProxyId::new(1).unwrap(),
+ )),
+ ),
+ ],
+ 0,
+ )],
+ vec![Arc::new(FailingDispatcher), fallback.clone()],
+ direct,
+ )
+ .unwrap();
+ let dispatcher = groups.dispatcher(ProxyGroupId::new(0).unwrap());
+
+ assert!(matches!(
+ dispatcher.connect_tcp(stream_session()).await,
+ Err(DispatchError::HostUnreachable)
+ ));
+ assert!(matches!(
+ dispatcher.open_datagram(datagram_session()).await,
+ Err(DispatchError::NetworkUnreachable)
+ ));
+ assert_eq!(fallback.tcp_calls.load(Ordering::Relaxed), 0);
+ assert_eq!(fallback.udp_opens.load(Ordering::Relaxed), 0);
+ assert_eq!(groups.state("group").unwrap().now, "failing");
+ }
+
+ #[test]
+ fn unexpected_group_cycle_hits_the_iterative_hop_ceiling() {
+ let direct = Arc::new(RecordingDispatcher::default());
+ let groups = ProxyGroups::new(
+ &[
+ group(
+ "a",
+ vec![member(
+ "b",
+ ProxyGroupMemberTarget::Route(RouteTargetId::Group(
+ ProxyGroupId::new(1).unwrap(),
+ )),
+ )],
+ 0,
+ ),
+ group(
+ "b",
+ vec![member(
+ "a",
+ ProxyGroupMemberTarget::Route(RouteTargetId::Group(
+ ProxyGroupId::new(0).unwrap(),
+ )),
+ )],
+ 0,
+ ),
+ ],
+ Vec::new(),
+ direct,
+ )
+ .unwrap();
+
+ let error = match groups.resolve_leaf(ProxyGroupId::new(0).unwrap()) {
+ Ok(_) => panic!("unexpected cycle resolved"),
+ Err(error) => error,
+ };
+ assert!(error.to_string().contains("hop ceiling"));
+ }
+}
diff --git a/src/runtime.rs b/src/runtime.rs
index d1c96c9..a1ff42c 100644
--- a/src/runtime.rs
+++ b/src/runtime.rs
@@ -7,11 +7,14 @@ use tokio::task::JoinHandle;
use tokio_util::sync::CancellationToken;
#[cfg(all(feature = "tun", any(unix, windows)))]
-use crate::{platform::TunIo, traffic::TrafficController, tun_runtime::TunRuntime};
+use crate::{platform::TunIo, tun_runtime::TunRuntime};
#[cfg(not(all(feature = "tun", any(unix, windows))))]
type TunRuntime = ();
-#[cfg(not(all(feature = "tun", any(unix, windows))))]
-type TrafficController = ();
+
+#[cfg(feature = "inbound-http")]
+use crate::controller::RuntimeController;
+#[cfg(not(feature = "inbound-http"))]
+type RuntimeController = ();
#[cfg(feature = "ffi")]
use crate::config::MeasureConfig;
@@ -30,7 +33,7 @@ use crate::{
},
outbound::{ConnectorDispatcher, DirectOutbound, OutboundConnector, UpstreamPath},
resources::RuntimeResourceStats,
- routing::{GeoMatcher, ProxyDispatchers, RoutingDispatcher, RuleSet},
+ routing::{GeoMatcher, ProxyGroups, RouteTargetDispatchers, RoutingDispatcher, RuleSet},
traffic::TunTrafficStats,
};
@@ -111,6 +114,7 @@ struct BuiltRuntimeParts {
dispatcher: Arc,
dns: Option>,
geodata_updater: Option,
+ proxy_groups: Arc,
proxy_graph: BuiltProxyGraph,
}
@@ -259,27 +263,26 @@ impl PreparedCore {
let dialer = dialer.with_ipv6(self.config.ipv6);
let handshake_stats = RuntimeResourceStats::new("runtime_handshake_observation");
let proxy_graph = self.build_proxy_graph(dialer.clone())?;
- let geodata_proxy = proxy_graph
- .get(self.config.default_proxy.index())
- .cloned()
- .ok_or_else(|| {
- io::Error::new(
- io::ErrorKind::InvalidInput,
- "default proxy is missing from the runtime graph",
- )
- })?;
- let geodata_dispatcher: Arc =
- Arc::new(ConnectorDispatcher::new(geodata_proxy));
- let proxies = self.wrap_proxy_dispatchers(proxy_graph.connectors(), &handshake_stats)?;
+ let proxy_dispatchers =
+ self.wrap_proxy_dispatchers(proxy_graph.connectors(), &handshake_stats)?;
let direct_raw: Arc = Arc::new(DirectOutbound::new(dialer));
let direct = observe_handshakes_with_stats(direct_raw, handshake_stats.clone());
+ let proxy_groups = ProxyGroups::new(
+ &self.config.proxy_groups,
+ proxy_dispatchers.clone(),
+ direct.clone(),
+ )
+ .map_err(|error| io::Error::new(io::ErrorKind::InvalidInput, error))?;
+ let route_targets =
+ RouteTargetDispatchers::with_proxy_groups(proxy_dispatchers, &proxy_groups)
+ .map_err(|error| io::Error::new(io::ErrorKind::InvalidInput, error))?;
let rules = self.rules.clone();
let redir_host_entries = self.dns_redir_host_entries();
let geo_matcher: Arc = self.geodata_registration.matcher();
let dns = self.config.dns.enable.then(|| {
Arc::new(RuntimeDns::new_routed_proxies_with_cache_limits(
&self.config.dns,
- proxies.clone(),
+ route_targets.clone(),
direct.clone(),
rules.clone(),
geo_matcher.clone(),
@@ -287,8 +290,22 @@ impl PreparedCore {
redir_host_entries,
))
});
+ let geodata_rules = RuleSet::compile(vec![crate::config::RuleSpec {
+ kind: crate::config::RuleKind::Match,
+ action: crate::config::RuleAction::Route(self.config.default_route_target),
+ no_resolve: false,
+ }])
+ .map_err(|error| io::Error::new(io::ErrorKind::InvalidInput, error))?;
+ let geodata_dispatcher: Arc = Arc::new(RoutingDispatcher::new_with_ipv6(
+ route_targets.clone(),
+ direct.clone(),
+ dns.clone(),
+ self.config.ipv6,
+ geodata_rules,
+ geo_matcher.clone(),
+ ));
let router: Arc = Arc::new(RoutingDispatcher::new_with_ipv6(
- proxies,
+ route_targets,
direct,
dns.clone(),
self.config.ipv6,
@@ -315,6 +332,7 @@ impl PreparedCore {
)
})
},
+ proxy_groups,
proxy_graph,
})
}
@@ -327,7 +345,7 @@ impl PreparedCore {
&self,
connectors: &[Arc],
handshake_stats: &RuntimeResourceStats,
- ) -> io::Result {
+ ) -> io::Result>> {
let mut dispatchers = Vec::with_capacity(connectors.len());
for (proxy, connector) in self.config.proxies.iter().zip(connectors) {
let mut dispatcher: Arc = Arc::new(
@@ -336,8 +354,31 @@ impl PreparedCore {
dispatcher = observe_handshakes_with_stats(dispatcher, handshake_stats.clone());
dispatchers.push(dispatcher);
}
- ProxyDispatchers::new(dispatchers)
- .map_err(|error| io::Error::new(io::ErrorKind::InvalidInput, error))
+ Ok(dispatchers)
+ }
+
+ async fn bind_controller(
+ &self,
+ traffic: Option>,
+ proxy_groups: Arc,
+ ) -> io::Result> {
+ let Some(config) = &self.config.external_controller else {
+ return Ok(None);
+ };
+ #[cfg(feature = "inbound-http")]
+ {
+ RuntimeController::bind(config, traffic, proxy_groups)
+ .await
+ .map(Some)
+ }
+ #[cfg(not(feature = "inbound-http"))]
+ {
+ let _ = (config, traffic, proxy_groups);
+ Err(io::Error::new(
+ io::ErrorKind::Unsupported,
+ "external controller support is disabled at build time",
+ ))
+ }
}
/// Starts configured local proxy listeners. TUN is started separately once
@@ -346,15 +387,17 @@ impl PreparedCore {
let BuiltRuntimeParts {
dispatcher,
geodata_updater,
+ proxy_groups,
proxy_graph,
..
} = self.build_dispatcher(dialer)?;
+ let controller = self.bind_controller(None, proxy_groups).await?;
RunningCore::start_components(
&self.config.inbounds,
dispatcher,
None,
None,
- None,
+ controller,
geodata_updater,
self.geodata_registration,
proxy_graph,
@@ -382,16 +425,16 @@ impl PreparedCore {
dispatcher,
dns,
geodata_updater,
+ proxy_groups,
proxy_graph,
} = self.build_dispatcher(dialer)?;
let sniffer = self.domain_sniffer_config();
let traffic_stats = self
.traffic_stats()
.unwrap_or_else(|| Arc::new(TunTrafficStats::default()));
- let traffic_controller = match &self.config.external_controller {
- Some(config) => Some(TrafficController::bind(config, traffic_stats.clone()).await?),
- None => None,
- };
+ let controller = self
+ .bind_controller(Some(traffic_stats.clone()), proxy_groups)
+ .await?;
let tun_runtime = TunRuntime::new_with_stats(
tun,
self.limits,
@@ -407,7 +450,7 @@ impl PreparedCore {
dispatcher,
Some(tun_runtime),
Some(traffic_stats),
- traffic_controller,
+ controller,
geodata_updater,
self.geodata_registration,
proxy_graph,
@@ -815,7 +858,7 @@ impl RunningCore {
dispatcher: Arc,
tun_runtime: Option,
traffic_stats: Option>,
- traffic_controller: Option,
+ controller: Option,
geodata_updater: Option,
geodata_registration: GeoDataRegistration,
proxy_graph: BuiltProxyGraph,
@@ -824,7 +867,7 @@ impl RunningCore {
let mut tasks = Vec::with_capacity(
inbounds.len()
+ usize::from(tun_runtime.is_some())
- + usize::from(traffic_controller.is_some())
+ + usize::from(controller.is_some())
+ usize::from(geodata_updater.is_some()),
);
#[cfg(not(feature = "inbound-http"))]
@@ -884,12 +927,15 @@ impl RunningCore {
tasks.push(tokio::spawn(tun_runtime.run(child)));
}
- #[cfg(all(feature = "tun", any(unix, windows)))]
- if let Some(traffic_controller) = traffic_controller {
+ #[cfg(feature = "inbound-http")]
+ if let Some(controller) = controller {
let child = cancellation.clone();
- tasks.push(tokio::spawn(traffic_controller.serve(child)));
+ tasks.push(tokio::spawn(controller.serve(child)));
}
+ #[cfg(not(feature = "inbound-http"))]
+ debug_assert!(controller.is_none());
+
if let Some(geodata_updater) = geodata_updater {
let child = cancellation.clone();
tasks.push(tokio::spawn(geodata_updater.run(child)));
@@ -1138,7 +1184,9 @@ rules:
assert_eq!(prepared.rules.len(), 1);
assert_eq!(
prepared.rules.rule(0).map(|rule| rule.action),
- Some(crate::config::RuleAction::Proxy(id)),
+ Some(crate::config::RuleAction::Route(
+ crate::config::RouteTargetId::Proxy(id)
+ )),
"moving the normalized rules must preserve the compiled default route"
);
}
diff --git a/src/traffic.rs b/src/traffic.rs
index 4830ec0..e9b901e 100644
--- a/src/traffic.rs
+++ b/src/traffic.rs
@@ -11,24 +11,8 @@ use serde::Serialize;
use tokio::time::{Instant, MissedTickBehavior, interval_at};
use tokio_util::sync::CancellationToken;
-#[cfg(feature = "inbound-http")]
-use crate::config::{ExternalControllerConfig, MAX_CONTROLLER_SECRET_BYTES};
-#[cfg(feature = "inbound-http")]
-use std::net::SocketAddr;
-#[cfg(feature = "inbound-http")]
-use tokio::{
- io::AsyncWriteExt,
- net::{TcpListener, TcpStream},
- task::JoinSet,
- time::timeout,
-};
-
const TRAFFIC_RATE_INTERVAL: Duration = Duration::from_secs(1);
const MAX_PUBLIC_TRAFFIC_BYTES: u64 = i64::MAX as u64;
-#[cfg(feature = "inbound-http")]
-const CONTROLLER_HEADER_TIMEOUT: Duration = Duration::from_secs(5);
-#[cfg(feature = "inbound-http")]
-const MAX_CONTROLLER_CONNECTIONS: usize = 8;
/// A mihomo-compatible traffic snapshot.
///
@@ -115,230 +99,8 @@ fn saturating_add(counter: &AtomicU64, value: u64) {
});
}
-#[cfg(feature = "inbound-http")]
-pub(crate) struct TrafficController {
- listener: TcpListener,
- secret: Option>,
- stats: Arc,
-}
-
-#[cfg(feature = "inbound-http")]
-impl std::fmt::Debug for TrafficController {
- fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
- formatter
- .debug_struct("TrafficController")
- .field("local_addr", &self.listener.local_addr().ok())
- .field("authenticated", &self.secret.is_some())
- .finish_non_exhaustive()
- }
-}
-
-#[cfg(feature = "inbound-http")]
-impl TrafficController {
- pub(crate) async fn bind(
- config: &ExternalControllerConfig,
- stats: Arc,
- ) -> io::Result {
- let listener = TcpListener::bind(config.listen).await?;
- Ok(Self {
- listener,
- secret: config.secret.as_deref().map(Arc::from),
- stats,
- })
- }
-
- #[cfg(test)]
- pub(crate) fn local_addr(&self) -> io::Result {
- self.listener.local_addr()
- }
-
- pub(crate) async fn serve(self, cancellation: CancellationToken) -> io::Result<()> {
- let mut tasks = JoinSet::new();
- loop {
- tokio::select! {
- biased;
- () = cancellation.cancelled() => break,
- joined = tasks.join_next(), if !tasks.is_empty() => {
- if let Some(Err(error)) = joined {
- tracing::warn!(
- cancelled = error.is_cancelled(),
- panicked = error.is_panic(),
- "traffic controller connection task failed"
- );
- }
- }
- accepted = self.listener.accept(), if tasks.len() < MAX_CONTROLLER_CONNECTIONS => {
- let (stream, peer) = accepted?;
- let secret = self.secret.clone();
- let stats = self.stats.clone();
- let child = cancellation.clone();
- tasks.spawn(async move {
- if let Err(error) =
- handle_controller_connection(stream, peer, secret, stats, child).await
- {
- tracing::debug!(
- error_kind = ?error.kind(),
- "traffic controller request failed"
- );
- }
- });
- }
- }
- }
- while tasks.join_next().await.is_some() {}
- Ok(())
- }
-}
-
-#[cfg(feature = "inbound-http")]
-async fn handle_controller_connection(
- mut stream: TcpStream,
- peer: SocketAddr,
- secret: Option>,
- stats: Arc,
- cancellation: CancellationToken,
-) -> io::Result<()> {
- if !peer.ip().is_loopback() {
- write_response(&mut stream, 403, &[], b"").await?;
- return Err(io::Error::new(
- io::ErrorKind::PermissionDenied,
- "traffic controller rejected a non-loopback peer",
- ));
- }
-
- let request = tokio::select! {
- biased;
- () = cancellation.cancelled() => return Ok(()),
- result = timeout(
- CONTROLLER_HEADER_TIMEOUT,
- crate::inbound::http::read_request_head(
- &mut stream,
- crate::inbound::DEFAULT_HEADER_LIMIT,
- ),
- ) => match result {
- Ok(Ok(request)) => request,
- Ok(Err(error)) => {
- write_response(&mut stream, 400, &[], b"").await?;
- return Err(error);
- }
- Err(_) => {
- write_response(&mut stream, 408, &[], b"").await?;
- return Err(io::Error::new(
- io::ErrorKind::TimedOut,
- "traffic controller request head timed out",
- ));
- }
- },
- };
-
- if !authorized(&request.headers, secret.as_deref()) {
- let body = br#"{"message":"Unauthorized"}"#;
- write_response(
- &mut stream,
- 401,
- &[
- ("WWW-Authenticate", "Bearer"),
- ("Content-Type", "application/json"),
- ],
- body,
- )
- .await?;
- return Err(io::Error::new(
- io::ErrorKind::PermissionDenied,
- "traffic controller authentication failed",
- ));
- }
- if request.target != "/traffic" {
- write_response(&mut stream, 404, &[], b"").await?;
- return Ok(());
- }
- if request.method != "GET" {
- write_response(&mut stream, 405, &[("Allow", "GET")], b"").await?;
- return Ok(());
- }
-
- let body = serde_json::to_vec(&stats.snapshot()).map_err(io::Error::other)?;
- write_response(
- &mut stream,
- 200,
- &[
- ("Content-Type", "application/json"),
- ("Cache-Control", "no-store"),
- ],
- &body,
- )
- .await
-}
-
-#[cfg(feature = "inbound-http")]
-fn authorized(headers: &[(String, String)], secret: Option<&str>) -> bool {
- let Some(secret) = secret else {
- return true;
- };
- let mut authorization = headers
- .iter()
- .filter(|(name, _)| name.eq_ignore_ascii_case("authorization"))
- .map(|(_, value)| value.as_str());
- let Some(value) = authorization.next() else {
- return false;
- };
- if authorization.next().is_some() {
- return false;
- }
- value
- .strip_prefix("Bearer ")
- .is_some_and(|token| controller_token_eq(token.as_bytes(), secret.as_bytes()))
-}
-
-#[cfg(feature = "inbound-http")]
-fn controller_token_eq(candidate: &[u8], secret: &[u8]) -> bool {
- let mut difference = candidate.len() ^ secret.len();
- for index in 0..MAX_CONTROLLER_SECRET_BYTES {
- let candidate = candidate.get(index).copied().unwrap_or_default();
- let secret = secret.get(index).copied().unwrap_or_default();
- difference |= usize::from(candidate ^ secret);
- }
- difference == 0
-}
-
-#[cfg(feature = "inbound-http")]
-async fn write_response(
- stream: &mut TcpStream,
- status: u16,
- headers: &[(&str, &str)],
- body: &[u8],
-) -> io::Result<()> {
- let reason = match status {
- 200 => "OK",
- 400 => "Bad Request",
- 401 => "Unauthorized",
- 403 => "Forbidden",
- 404 => "Not Found",
- 405 => "Method Not Allowed",
- 408 => "Request Timeout",
- _ => "Error",
- };
- let mut response = format!(
- "HTTP/1.1 {status} {reason}\r\nContent-Length: {}\r\nConnection: close\r\n",
- body.len()
- );
- for (name, value) in headers {
- response.push_str(name);
- response.push_str(": ");
- response.push_str(value);
- response.push_str("\r\n");
- }
- response.push_str("\r\n");
- stream.write_all(response.as_bytes()).await?;
- stream.write_all(body).await?;
- stream.shutdown().await
-}
-
#[cfg(test)]
mod tests {
- #[cfg(feature = "inbound-http")]
- use tokio::io::{AsyncReadExt, AsyncWriteExt};
-
use super::*;
#[test]
@@ -387,83 +149,4 @@ mod tests {
stats.record_up(8);
assert_eq!(stats.snapshot().up_total, MAX_PUBLIC_TRAFFIC_BYTES);
}
-
- #[cfg(feature = "inbound-http")]
- #[test]
- fn bearer_auth_is_strict_and_duplicate_safe() {
- let valid = vec![("Authorization".to_owned(), "Bearer token".to_owned())];
- assert!(authorized(&valid, Some("token")));
- assert!(authorized(&[], None));
- assert!(!authorized(&[], Some("token")));
- assert!(!authorized(
- &[("Authorization".to_owned(), "bearer token".to_owned())],
- Some("token")
- ));
- assert!(!authorized(
- &[
- ("Authorization".to_owned(), "Bearer token".to_owned()),
- ("authorization".to_owned(), "Bearer token".to_owned()),
- ],
- Some("token")
- ));
- assert!(!controller_token_eq(b"toke", b"token"));
- assert!(!controller_token_eq(b"token-longer", b"token"));
- let longest = vec![b'x'; MAX_CONTROLLER_SECRET_BYTES];
- assert!(controller_token_eq(&longest, &longest));
- }
-
- #[cfg(feature = "inbound-http")]
- #[tokio::test]
- async fn controller_returns_one_authenticated_snapshot() {
- let stats = Arc::new(TunTrafficStats::default());
- stats.record_up(123);
- stats.record_down(456);
- stats.rotate_rate_bucket();
- let config = ExternalControllerConfig {
- listen: "127.0.0.1:0".parse().unwrap(),
- secret: Some("random-token".to_owned()),
- };
- let controller = TrafficController::bind(&config, stats).await.unwrap();
- let address = controller.local_addr().unwrap();
- let cancellation = CancellationToken::new();
- let server = tokio::spawn(controller.serve(cancellation.clone()));
-
- let response = request(
- address,
- b"GET /traffic HTTP/1.1\r\nHost: localhost\r\nAuthorization: Bearer random-token\r\n\r\n",
- )
- .await;
- assert!(response.starts_with("HTTP/1.1 200 OK\r\n"));
- let body = response.split_once("\r\n\r\n").unwrap().1;
- assert_eq!(
- serde_json::from_str::(body).unwrap(),
- serde_json::json!({
- "up": 123,
- "down": 456,
- "upTotal": 123,
- "downTotal": 456,
- })
- );
-
- let unauthorized = request(
- address,
- b"GET /traffic HTTP/1.1\r\nHost: localhost\r\nAuthorization: Bearer wrong\r\n\r\n",
- )
- .await;
- assert!(unauthorized.starts_with("HTTP/1.1 401 Unauthorized\r\n"));
- assert!(unauthorized.contains("Content-Type: application/json\r\n"));
- assert!(unauthorized.ends_with(r#"{"message":"Unauthorized"}"#));
-
- cancellation.cancel();
- server.await.unwrap().unwrap();
- }
-
- #[cfg(feature = "inbound-http")]
- async fn request(address: SocketAddr, request: &[u8]) -> String {
- let mut stream = TcpStream::connect(address).await.unwrap();
- stream.write_all(request).await.unwrap();
- let mut response = Vec::new();
- stream.read_to_end(&mut response).await.unwrap();
- String::from_utf8(response).unwrap()
- }
}
diff --git a/src/windows/host.rs b/src/windows/host.rs
index 2299a4e..4b70fbd 100644
--- a/src/windows/host.rs
+++ b/src/windows/host.rs
@@ -17,23 +17,14 @@ use windows::{
},
Storage::ApplicationData,
Win32::{
- Foundation::{E_NOINTERFACE, HANDLE},
- System::{
- Com::{CLSCTX_LOCAL_SERVER, CoCreateInstance},
- Threading::{
- OpenProcess, PROCESS_SYNCHRONIZE, PROCESS_TERMINATE, TerminateProcess,
- WaitForSingleObject,
- },
- WinRT::{RO_INIT_MULTITHREADED, RoInitialize, RoUninitialize},
- },
- UI::Shell::{AO_NONE, ApplicationActivationManager, IApplicationActivationManager},
+ Foundation::E_NOINTERFACE,
+ System::WinRT::{RO_INIT_MULTITHREADED, RoInitialize, RoUninitialize},
},
- core::{HSTRING, IUnknown, Interface as _, Owned, Result as WindowsResult},
+ core::{Interface as _, Result as WindowsResult},
};
use super::{
managed_processes::SessionBackend,
- packet_channel::remove_rendezvous,
profile::{WindowsNetworkSettings, WindowsProfileConfiguration},
snapshot::SessionReference,
};
@@ -109,51 +100,6 @@ impl Drop for WinRtGuard {
}
}
-struct SessionHostProcess {
- handle: Owned,
- terminate_on_drop: bool,
-}
-
-impl SessionHostProcess {
- fn launch(family_name: &str, session_token: &str) -> Result {
- let manager: IApplicationActivationManager = unsafe {
- CoCreateInstance(
- &ApplicationActivationManager,
- None::<&IUnknown>,
- CLSCTX_LOCAL_SERVER,
- )
- }
- .map_err(display_error)?;
- let app_user_model_id: HSTRING = format!("{family_name}!SessionHost").into();
- let arguments: HSTRING = format!("--session-token {session_token}").into();
- let process_id =
- unsafe { manager.ActivateApplication(&app_user_model_id, &arguments, AO_NONE) }
- .map_err(display_error)?;
- let handle =
- unsafe { OpenProcess(PROCESS_TERMINATE | PROCESS_SYNCHRONIZE, false, process_id) }
- .map_err(display_error)?;
- Ok(Self {
- handle: unsafe { Owned::new(handle) },
- terminate_on_drop: true,
- })
- }
-
- fn release(mut self) {
- self.terminate_on_drop = false;
- }
-}
-
-impl Drop for SessionHostProcess {
- fn drop(&mut self) {
- if self.terminate_on_drop {
- unsafe {
- _ = TerminateProcess(*self.handle, 1);
- _ = WaitForSingleObject(*self.handle, 5_000);
- }
- }
- }
-}
-
/// Executes a packaged Windows host request. The returned string must be
/// released with `VCoreFree` from the same DLL.
///
@@ -286,8 +232,6 @@ fn start_vpn(payload: StartPayload) -> Result {
Ok(existing.profile.clone())
})
.map_err(display_error)?;
- remove_rendezvous(&environment.local_folder).map_err(display_error)?;
- let session_host = SessionHostProcess::launch(&environment.family_name, &token)?;
configure_profile(
&profile,
&environment.family_name,
@@ -316,7 +260,6 @@ fn start_vpn(payload: StartPayload) -> Result {
{
return Err(format!("connect Windows VPN returned status {}", status.0));
}
- session_host.release();
Ok(json!({"status": "connected", "snapshotToken": token}))
}
diff --git a/src/windows/packet_channel.rs b/src/windows/packet_channel.rs
index c0d8748..23960d3 100644
--- a/src/windows/packet_channel.rs
+++ b/src/windows/packet_channel.rs
@@ -196,16 +196,13 @@ impl Rendezvous {
Ok(rendezvous)
}
- pub(crate) fn from_json(bytes: &[u8], expected_token: &str) -> io::Result {
+ pub(crate) fn from_json(bytes: &[u8]) -> io::Result {
if bytes.is_empty() || bytes.len() > MAX_RENDEZVOUS_BYTES {
return Err(invalid_data("invalid Windows rendezvous size"));
}
let rendezvous: Self = serde_json::from_slice(bytes)
.map_err(|_| invalid_data("invalid Windows rendezvous JSON"))?;
rendezvous.validate()?;
- if rendezvous.snapshot_token != expected_token {
- return Err(invalid_data("Windows rendezvous snapshot mismatch"));
- }
Ok(rendezvous)
}
@@ -624,7 +621,7 @@ pub(crate) async fn read_packet_frame_async(
Ok(packet)
}
-pub(crate) fn read_rendezvous(local_folder: &Path, expected_token: &str) -> io::Result {
+pub(crate) fn read_rendezvous(local_folder: &Path) -> io::Result {
let path = local_folder.join(RENDEZVOUS_FILE);
let metadata = fs::symlink_metadata(&path)?;
if !metadata.is_file()
@@ -634,7 +631,7 @@ pub(crate) fn read_rendezvous(local_folder: &Path, expected_token: &str) -> io::
{
return Err(invalid_data("invalid Windows rendezvous file"));
}
- Rendezvous::from_json(&fs::read(path)?, expected_token)
+ Rendezvous::from_json(&fs::read(path)?)
}
pub(crate) fn remove_rendezvous(local_folder: &Path) -> io::Result<()> {
@@ -745,6 +742,26 @@ mod tests {
}
}
+ #[tokio::test]
+ async fn provider_rejects_a_candidate_not_bound_to_the_profile() {
+ let mut host = Vec::new();
+ write_control_async(
+ &mut host,
+ &ControlMessage::SessionHello {
+ version: PROTOCOL_VERSION,
+ snapshot_token: TOKEN.replace('0', "1"),
+ },
+ )
+ .await
+ .unwrap();
+
+ let error =
+ complete_provider_handshake(&mut host.as_slice(), &mut Vec::new(), TOKEN, binding())
+ .await
+ .unwrap_err();
+ assert_eq!(error.kind(), io::ErrorKind::InvalidData);
+ }
+
#[tokio::test]
async fn stop_interrupts_a_stalled_provider_handshake() {
let (provider, mut host) = tokio::io::duplex(4096);
@@ -840,17 +857,17 @@ mod tests {
let path = root.path().join(RENDEZVOUS_FILE);
let rendezvous = Rendezvous::new(TOKEN.to_owned(), OBJECT_PATH.to_owned()).unwrap();
publish_rendezvous(root.path(), &rendezvous).unwrap();
- assert_eq!(read_rendezvous(root.path(), TOKEN).unwrap(), rendezvous);
+ assert_eq!(read_rendezvous(root.path()).unwrap(), rendezvous);
remove_rendezvous(root.path()).unwrap();
remove_rendezvous(root.path()).unwrap();
assert!(!path.exists());
}
#[test]
- fn rendezvous_accepts_only_the_canonical_appcontainer_path_and_token() {
+ fn rendezvous_accepts_a_canonical_candidate_token_without_external_authority() {
let rendezvous = Rendezvous::new(TOKEN.to_owned(), OBJECT_PATH.to_owned()).unwrap();
let json = rendezvous.to_json().unwrap();
- assert_eq!(Rendezvous::from_json(&json, TOKEN).unwrap(), rendezvous);
+ assert_eq!(Rendezvous::from_json(&json).unwrap(), rendezvous);
assert_eq!(
rendezvous.qualified_names(1).unwrap(),
(
@@ -866,6 +883,60 @@ mod tests {
] {
assert!(Rendezvous::new(TOKEN.to_owned(), path.to_owned()).is_err());
}
- assert!(Rendezvous::from_json(&json, &TOKEN.replace('0', "1")).is_err());
+ let invalid_token = String::from_utf8(json)
+ .unwrap()
+ .replace(TOKEN, "vcore-session-v2:not-a-digest");
+ assert!(Rendezvous::from_json(invalid_token.as_bytes()).is_err());
+ }
+
+ #[test]
+ fn rendezvous_rejects_noncanonical_records() {
+ let rendezvous = Rendezvous::new(TOKEN.to_owned(), OBJECT_PATH.to_owned()).unwrap();
+ let json = String::from_utf8(rendezvous.to_json().unwrap()).unwrap();
+ let invalid = [
+ Vec::new(),
+ vec![b' '; MAX_RENDEZVOUS_BYTES + 1],
+ json.replace("\"protocolVersion\":1", "\"protocolVersion\":2")
+ .into_bytes(),
+ json.replace(CONTROL_LEAF, "VCore.Vpn.Control.v2")
+ .into_bytes(),
+ json.replace(DATA_LEAF, "VCore.Vpn.Data.v2").into_bytes(),
+ json.replace(TOKEN, "vcore-session-v2:not-a-digest")
+ .into_bytes(),
+ serde_json::to_vec(&Rendezvous {
+ object_path: "AppContainerNamedObjects\\invalid".to_owned(),
+ ..rendezvous
+ })
+ .unwrap(),
+ json.replace('}', ",\"unknown\":true}").into_bytes(),
+ ];
+ for (index, bytes) in invalid.into_iter().enumerate() {
+ assert!(
+ Rendezvous::from_json(&bytes).is_err(),
+ "invalid rendezvous case {index} was accepted"
+ );
+ }
+ }
+
+ #[test]
+ fn read_rendezvous_rejects_reparse_points() {
+ let root = tempfile::tempdir().unwrap();
+ let target = root.path().join("target.json");
+ fs::write(
+ &target,
+ Rendezvous::new(TOKEN.to_owned(), OBJECT_PATH.to_owned())
+ .unwrap()
+ .to_json()
+ .unwrap(),
+ )
+ .unwrap();
+ let link = root.path().join(RENDEZVOUS_FILE);
+ fs::create_dir_all(link.parent().unwrap()).unwrap();
+ std::os::windows::fs::symlink_file(target, link).unwrap();
+
+ assert_eq!(
+ read_rendezvous(root.path()).unwrap_err().kind(),
+ io::ErrorKind::InvalidData
+ );
}
}
diff --git a/src/windows/session.rs b/src/windows/session.rs
index b1c8a6d..b736674 100644
--- a/src/windows/session.rs
+++ b/src/windows/session.rs
@@ -7,7 +7,7 @@ use std::{
};
use tokio::{
- io::BufReader,
+ io::{AsyncRead, AsyncWrite, BufReader},
net::windows::named_pipe::{ClientOptions, NamedPipeClient},
sync::Notify,
task::JoinSet,
@@ -64,14 +64,13 @@ impl Drop for WinRtGuard {
#[doc(hidden)]
pub fn run() -> io::Result<()> {
let _winrt = WinRtGuard::enter()?;
- let token = parse_args(std::env::args().skip(1))?;
let (local_folder, installed_folder) = package_folders()?;
log::append(&local_folder, "session", "Session Host starting");
let runtime = tokio::runtime::Builder::new_current_thread()
.enable_io()
.enable_time()
.build()?;
- let result = runtime.block_on(run_async(&local_folder, &installed_folder, &token));
+ let result = runtime.block_on(run_async(&local_folder, &installed_folder));
log::append(
&local_folder,
"session",
@@ -91,26 +90,9 @@ pub fn log_startup_failure(_error: &io::Error) {
}
}
-fn parse_args(args: impl IntoIterator
- ) -> io::Result {
- let args: Vec = args.into_iter().collect();
- let [flag, token] = args.as_slice() else {
- return Err(io::Error::new(
- io::ErrorKind::InvalidInput,
- "invalid Session Host arguments",
- ));
- };
- if flag != "--session-token" {
- return Err(io::Error::new(
- io::ErrorKind::InvalidInput,
- "invalid Session Host arguments",
- ));
- }
- SessionReference::parse(token).map_err(io::Error::other)?;
- Ok(token.clone())
-}
-
-async fn run_async(local_folder: &Path, installed_folder: &Path, token: &str) -> io::Result<()> {
- let rendezvous = wait_for_rendezvous(local_folder, token).await?;
+async fn run_async(local_folder: &Path, installed_folder: &Path) -> io::Result<()> {
+ let rendezvous = wait_for_rendezvous(local_folder).await?;
+ let token = rendezvous.snapshot_token.clone();
let session_id = current_session_id()?;
let (control_name, data_name) = rendezvous.qualified_names(session_id)?;
let control = open_pipe(&control_name, STARTUP_TIMEOUT).await?;
@@ -118,24 +100,10 @@ async fn run_async(local_folder: &Path, installed_folder: &Path, token: &str) ->
// The Provider publishes and removes rendezvous; competing deletes can return ACCESS_DENIED.
let (mut control_read, mut control_write) = tokio::io::split(control);
- write_control_async(
- &mut control_write,
- &ControlMessage::SessionHello {
- version: PROTOCOL_VERSION,
- snapshot_token: token.to_owned(),
- },
- )
- .await?;
- let binding = match read_control_async(&mut control_read).await? {
- ControlMessage::ProviderHello {
- snapshot_token,
- physical_binding,
- ..
- } if snapshot_token == token => physical_binding,
- _ => return Err(invalid_data("invalid Provider handshake")),
- };
+ // Authenticate the candidate token before reading Snapshot or starting processes.
+ let binding = complete_session_handshake(&mut control_read, &mut control_write, &token).await?;
- let started = start_session(local_folder, installed_folder, token, binding, data).await;
+ let started = start_session(local_folder, installed_folder, &token, binding, data).await;
let (running, mut data_tasks, mut managed_processes) = match started {
Ok(started) => started,
Err(error) => {
@@ -226,6 +194,29 @@ async fn run_async(local_folder: &Path, installed_folder: &Path, token: &str) ->
}
}
+async fn complete_session_handshake(
+ control_read: &mut (impl AsyncRead + Unpin),
+ control_write: &mut (impl AsyncWrite + Unpin),
+ token: &str,
+) -> io::Result {
+ write_control_async(
+ control_write,
+ &ControlMessage::SessionHello {
+ version: PROTOCOL_VERSION,
+ snapshot_token: token.to_owned(),
+ },
+ )
+ .await?;
+ match read_control_async(control_read).await? {
+ ControlMessage::ProviderHello {
+ snapshot_token,
+ physical_binding,
+ ..
+ } if snapshot_token == token => Ok(physical_binding),
+ _ => Err(invalid_data("invalid Provider handshake")),
+ }
+}
+
async fn start_session(
local_folder: &Path,
installed_folder: &Path,
@@ -349,10 +340,10 @@ fn dialer_from_binding(binding: &PhysicalBinding) -> io::Result {
Ok(Dialer::default().with_windows_interface(ipv4, ipv6))
}
-async fn wait_for_rendezvous(local_folder: &Path, token: &str) -> io::Result {
+async fn wait_for_rendezvous(local_folder: &Path) -> io::Result {
let deadline = Instant::now() + STARTUP_TIMEOUT;
loop {
- match read_rendezvous(local_folder, token) {
+ match read_rendezvous(local_folder) {
Ok(rendezvous) => return Ok(rendezvous),
Err(error) if error.kind() == io::ErrorKind::NotFound && Instant::now() < deadline => {
sleep(Duration::from_millis(25)).await;
@@ -423,27 +414,36 @@ mod tests {
use super::*;
use crate::windows::packet_channel::AddressBindingV4;
- const TOKEN: &str =
- "vcore-session-v2:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+ #[tokio::test]
+ async fn provider_cannot_bind_a_candidate_to_another_snapshot() {
+ let candidate =
+ "vcore-session-v2:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+ let mut provider = Vec::new();
+ write_control_async(
+ &mut provider,
+ &ControlMessage::ProviderHello {
+ version: PROTOCOL_VERSION,
+ snapshot_token: candidate.replace('0', "1"),
+ physical_binding: PhysicalBinding {
+ adapter_id: "adapter".to_owned(),
+ profile_name: "Ethernet".to_owned(),
+ network_names: vec![],
+ ipv4: Some(AddressBindingV4 {
+ source: "192.0.2.10".parse().unwrap(),
+ interface_index: 10,
+ }),
+ ipv6: None,
+ },
+ },
+ )
+ .await
+ .unwrap();
- #[test]
- fn session_host_accepts_only_one_canonical_snapshot_argument() {
- assert_eq!(
- parse_args(["--session-token".to_owned(), TOKEN.to_owned()]).unwrap(),
- TOKEN
- );
- for args in [
- vec![],
- vec![TOKEN.to_owned()],
- vec!["--config".to_owned(), TOKEN.to_owned()],
- vec![
- "--session-token".to_owned(),
- TOKEN.to_owned(),
- "extra".to_owned(),
- ],
- ] {
- assert!(parse_args(args).is_err());
- }
+ let error =
+ complete_session_handshake(&mut provider.as_slice(), &mut Vec::new(), candidate)
+ .await
+ .unwrap_err();
+ assert_eq!(error.kind(), io::ErrorKind::InvalidData);
}
#[test]
diff --git a/src/windows/vpn.rs b/src/windows/vpn.rs
index 300d1b5..5b9d2b1 100644
--- a/src/windows/vpn.rs
+++ b/src/windows/vpn.rs
@@ -20,6 +20,7 @@ use windows::{
ApplicationModel::{
Background::{IBackgroundTask, IBackgroundTask_Impl, IBackgroundTaskInstance},
Core::CoreApplication,
+ FullTrustProcessLauncher,
},
Networking::{
Connectivity::{ConnectionProfile, NetworkInformation, NetworkStatusChangedEventHandler},
@@ -60,6 +61,7 @@ use super::{
log,
packet_channel::{
AddressBindingV4, AddressBindingV6, PacketCounters, PhysicalBinding, ProviderPacketSession,
+ remove_rendezvous,
},
profile::{WindowsNetworkSettings, WindowsProfileConfiguration},
};
@@ -620,6 +622,9 @@ impl VpnProvider {
));
}
+ remove_rendezvous(&local_folder).map_err(windows_error)?;
+ launch_session_host()?;
+
let unexpected_stop = fail_closed_handle.clone();
let session = ProviderPacketSession::start(
local_folder,
@@ -1025,6 +1030,10 @@ fn write_buffer(buffer: &Buffer, bytes: &[u8]) -> Result<()> {
buffer.SetLength(bytes.len() as u32)
}
+fn launch_session_host() -> Result<()> {
+ FullTrustProcessLauncher::LaunchFullTrustProcessForCurrentAppAsync()?.join()
+}
+
fn write_dummy(output: &IOutputStream) -> Result<()> {
let dummy = Buffer::Create(1)?;
write_buffer(&dummy, &[0])?;
diff --git a/tests/proxy_group_compat.rs b/tests/proxy_group_compat.rs
new file mode 100644
index 0000000..532c9e6
--- /dev/null
+++ b/tests/proxy_group_compat.rs
@@ -0,0 +1,119 @@
+use vcore::config::{
+ Config, DnsRoute, ProxyGroupId, ProxyGroupMemberTarget, RouteTargetId, RuleAction,
+};
+
+const COMMON_PREFIX: &str = r#"
+port: 1080
+authentication: [user:password]
+proxies:
+ - name: node-a
+ type: socks5
+ server: 192.0.2.1
+ port: 1080
+ udp: true
+ - name: node-b
+ type: socks5
+ server: 192.0.2.2
+ port: 1080
+ udp: true
+"#;
+
+#[test]
+fn accepts_the_mihomo_select_common_subset_without_flattening() {
+ let yaml = format!(
+ r#"{COMMON_PREFIX}
+proxy-groups:
+ - name: backup
+ type: select
+ proxies: [node-b, DIRECT]
+ - name: primary
+ type: select
+ proxies: [node-a, backup, REJECT, node-a]
+ default-selected: backup
+dns:
+ enable: true
+ nameserver: ["tcp://1.1.1.1:53#primary"]
+rules:
+ - DOMAIN-SUFFIX,example.com,backup
+ - MATCH,primary
+"#
+ );
+
+ let config = Config::parse_yaml(yaml.as_bytes()).unwrap();
+ let backup = ProxyGroupId::new(0).unwrap();
+ let primary = ProxyGroupId::new(1).unwrap();
+
+ assert_eq!(config.proxy_groups[1].initial_member, 1);
+ assert_eq!(
+ config.proxy_groups[1]
+ .members
+ .iter()
+ .map(|member| member.name.as_str())
+ .collect::>(),
+ ["node-a", "backup", "REJECT", "node-a"]
+ );
+ assert_eq!(
+ config.proxy_groups[1].members[1].target,
+ ProxyGroupMemberTarget::Route(RouteTargetId::Group(backup))
+ );
+ assert_eq!(config.default_route_target, RouteTargetId::Group(primary));
+ assert_eq!(
+ config.rules[0].action,
+ RuleAction::Route(RouteTargetId::Group(backup))
+ );
+ assert_eq!(
+ config.dns.nameservers[0].route,
+ DnsRoute::Route(RouteTargetId::Group(primary))
+ );
+}
+
+#[test]
+fn keeps_vcore_stricter_than_mihomo_at_the_documented_boundaries() {
+ for groups in [
+ r#"
+proxy-groups:
+ - name: primary
+ type: select
+ proxies: [node-a]
+ default-selected: missing
+"#,
+ r#"
+proxy-groups:
+ - name: primary
+ type: select
+ proxies: [node-a]
+ url: https://example.com/generate_204
+"#,
+ r#"
+proxy-groups:
+ - name: primary
+ type: url-test
+ proxies: [node-a]
+"#,
+ ] {
+ let yaml = format!("{COMMON_PREFIX}{groups}rules:\n - MATCH,primary\n");
+ assert!(Config::parse_yaml(yaml.as_bytes()).is_err(), "{yaml}");
+ }
+}
+
+#[test]
+fn keeps_dialer_proxy_concrete_node_only() {
+ let yaml = format!(
+ r#"{COMMON_PREFIX}
+proxy-groups:
+ - name: primary
+ type: select
+ proxies: [node-a, node-b]
+rules:
+ - MATCH,primary
+"#
+ )
+ .replacen(
+ " server: 192.0.2.1\n",
+ " server: 192.0.2.1\n dialer-proxy: primary\n",
+ 1,
+ );
+
+ let error = Config::parse_yaml(yaml.as_bytes()).unwrap_err();
+ assert!(error.to_string().contains("concrete proxy"));
+}