Files
Vole/docs/tun-platform.md
T
yiguodev 608a8f255c feat: add client protocols, TLS capabilities, and platform validation (#1)
* chore: download latest official mihomo for interop tests

* test: capture N0 baseline and protocol feasibility probes

* docs: record N0 hybrid REALITY fork verification

* test: verify N0 controlled Hysteria2 auth and streams

Add an isolated Quinn adapter over existing DIRECT and SOCKS5 datagrams, bounded queues, protect rejection probes, and official latest peer fixtures. Record passing auth/TCP checks and the native Hysteria half-close failure separately. N0 remains incomplete; production sources and dependency locks are unchanged.

* test: validate N0 native QUIC hopping and XHTTP H3

Keep the probes isolated from production. Verify one-state Hysteria hopping, protected rebind rejection, Xray H3 entry and existing HY2 regressions. Set only the owned Linux peer MTU to avoid Initial-packet EMSGSIZE; retain native half-close failures as separate gates.

* fix: align XHTTP shutdown with Mihomo connection close

* test: verify N0 supplied-stream transport interfaces

Add isolated TLS, ordinary WebSocket and gRPC probes with owned I/O, bounded buffers and cancellation barriers.

Match Mihomo close behavior: preserve TLS/WS reads, distinguish clean WS underlay EOF from truncation, and close both gRPC directions. Use separate official SOCKS5 peers to avoid fixture loop detection.

Record 12 Debug/Release tests, 42 official Mihomo checks, dependency audits and Apple/Android compile checks. Keep production dependencies, third-party sources and remaining N0 gates unchanged.

* fix: upgrade h2 and retain completed responses after reset

* chore: use the current OneXray rustls fork origin

* chore: adopt published rustls 0.23.45 and official TLS binding

* chore: refresh N1 foundation and spike dependencies

* feat: validate next-protocol field and combination catalogs

* feat: share immutable TLS policies and bounded close semantics

* feat: add shared stream transports and decouple XUDP framing

* feat: add controlled datagram foundations and N1 acceptance harness

* chore: finalize N1 with verified x25519 dependency

* chore: publish N1 against the rustls release branch

* feat: add bounded Trojan request and datagram codecs

* feat: connect Trojan TLS TCP and UDP through the runtime

* feat: support Trojan WebSocket and duplex gRPC transports

* feat: enable Trojan and complete N2 consumer acceptance

* feat(vmess): add bounded AEAD header and body codecs

* fix(vmess): align close acceptance with Mihomo transports

* feat(vmess): add UDP codecs and isolated peer comparisons

* feat(vmess): complete public runtime and N3 acceptance

* docs: bind N3 acceptance and refresh validation guidance

* feat(vless): complete N4 transports, Vision and UDP support

Extract VLESS assembly, add plain/TLS stream transports, HTTPUpgrade, node-owned gRPC pooling, mTLS and classic REALITY, and implement Vision through public TLS record boundaries. Preserve XHTTP and the XUDP default while adding raw and packetaddr.

Complete 145 required groups and 39 field rows against isolated latest official peers, with 160 lifecycle/resource rounds, independent coverage and Apple/Android release builds. Preserve the three explicit WS/REALITY layered close comparisons and historical failures in the acceptance report. No third-party or dependency-lock changes.

* feat(vless): complete N5 XHTTP and sing-mux support

Add H1/H2/H3 request fields, independent download security and pools, bounded packet-up batching, and h2mux/smux/yamux over controlled transports.

Keep Mihomo-aligned close and path semantics, node-owned shutdown barriers, and isolated official-peer fixtures including the approved Caddy mTLS gateway.

Validate 416 required groups, 57 fields, 112 two-leg security checks, 240 lifecycle/resource cycles, independent coverage, and Apple/Android release builds. Record native-peer gaps and leave N6-N10, devices, CI, and release gates separate.

* feat: integrate boring TLS profiles and retire rustls fork

* test(tls): freeze selected fingerprint reference baseline

* docs(tls): record selected-profile library acceptance

* feat(tls): integrate selected client fingerprints and REALITY profiles

* feat(tls): complete selected fingerprint CF5 acceptance

* feat(hysteria2): complete N6 client support and acceptance

Implement Hysteria2 over official Quinn/h3/rustls and shared controlled IO, including TCP/UDP, bandwidth pacing, Salamander, port hopping, upstream snapshots and synchronous Stop.

Keep old-path receives active for the full bounded handover window, preserve independent reader wakeups, and require the exact nested TCP evidence assertions.

Validate one frozen N6 run: 36 required groups, 20 field rows, native Mihomo/Hysteria peers, H3 regression, 40 lifecycle rounds and Apple/Android production builds. Record independent coverage, artifact hashes and native-peer limitations.

* test(tls): record N7 hybrid REALITY prerequisite evidence

Preserve the locked classic-only API failure and distinguish the locally accepted boring hybrid extension from pending VCore S03/D16 integration. Record wrapper feasibility and publication boundaries without changing production configuration or dependencies.

* feat(vless): support explicitly required hybrid REALITY

* feat(crypto): wrap official BLAKE3 binary-context derivation

* feat(vless): implement authenticated Encryption wire transport

* feat(vless): enable authenticated Encryption across public transports

* build(tls): pin the authenticated ShadowTLS ClientHello hook

* feat(vless): add authenticated JLS transport security

Pin the separately approved boring JLS revision and expose strict main/download credentials under schema 24. Preserve native CertificateVerify and Finished, cancellation, and controlled IO ownership. Accept the JLS field slice with 122 isolated cases, 80 lifecycle/resource cycles, and Apple/Android release libraries; keep broader N7 gates separate.

* docs(n7): reconcile current JLS acceptance progress

* chore(vless): retire Restls while retaining JLS

* feat(vless): complete N7 static ECH and security combinations

Add static ECH for VLESS main and XHTTP download legs using existing TLS backends and official Rust HPKE. Keep Invoke v5 and advance the internal schema to revision 27.

Accept the narrowed N7 scope with 43 required groups, 11 fields, 301 isolated native cases, 240 lifecycle/resource rounds, and Apple/Android release builds. Record frozen inputs, 470 container cleanups, explicit upstream comparison gaps, and prior failed runs in docs/acceptance/next-protocols/N7.md.

* chore(protocols): retire WireGuard scope and foundations

* test: complete N9 protocol integration and resource gates

* build: add N10 production artifact evidence gates

* fix: restore Windows snapshot encoding and fail-closed delivery CI

* fix: use native ARM64 LLVM assembly and scoped delivery CI

* build: keep delivery lockfile bytes stable across platforms

* fix: preserve production guard lifecycle and isolate CI feature checks

* build: adopt released boring and registry shadowsocks

* ci: use release-oriented workflow names

* docs: consolidate contracts and streamline test tooling

Merge current protocol and platform contracts, remove milestone reports and obsolete spikes, and share core checks between local development and CI. Preserve all 884 executable case definitions and unique legacy assertions.

Validation: core Debug/Release, feature checks, Clippy, netstack, offline script tests, formatting and documentation links passed locally. Container interop smoke attempts failed during official peer downloads; business paths remain NOT RUN.

* test: replace milestone names with capability-based validation

Rename protocol and fingerprint suites, fixtures, and evidence identifiers by capability. Preserve acceptance cases and golden wire data while documenting reference, wire, and interoperability evidence separately.

* fix: address review findings and stabilize core CI

Flush accepted gRPC/H2 data through the supplied IO before reset, and wait for pending smux writes before FIN. Sanitize AnyTLS peer failures, reject XHTTP userinfo, and remove stale Android delivery artifacts.

Close container log capture even when inventory fails. Keep legacy host suites blocked before resource acquisition.

Separate Shadowsocks adapter codec checks from upstream strict server acceptance. Lock the random empty-request zero-padding failure with deterministic negative and positive fixtures, without changing the dependency or production behavior.

* test: isolate delivery fixture from Windows home lookup

* test: preserve UDP socket semantics during peer teardown

The memory peer treated its counterpart closing an mpsc channel as a local UDP BrokenPipe. That could terminate Quinn endpoint IO without waking a pending wait_idle, despite all four datagrams and CONNECTION_CLOSE having arrived.

Keep a closed peer link silent and late sends best-effort, add a deterministic fixture regression, and preserve the existing data and shutdown deadlines. Debug/Release, Clippy, and 300 consecutive regression iterations pass.

* fix: drain XHTTP uploads before releasing connection drivers

* fix: enforce lazy setup deadlines and safe delivery paths

Check the original deadline before accepting ready gRPC/H2 headers or sing-mux status, without limiting established reads. Reject symlinks and Windows reparse points in every delivery output path before filesystem mutations. Add deterministic memory and temporary-filesystem regressions.

* test: join XHTTP H3 peer tasks during cleanup

Quinn retains closed connections for three probe timeouts, so a delayed handshake can legitimately exceed the fixture's two-second wait_idle budget. Own, abort, and join the passive peer tasks after upload and client shutdown instead. Preserve upload integrity and client close bounds, and cover delayed handshakes in both streaming modes.
2026-09-28 12:50:01 +08:00

4.2 KiB
Raw Blame History

TUN 平台层

VCore 的 netstack、DNS、规则和出站只处理完整的原始 IPv4/IPv6 数据包。平台差异集中在编译期选择的 platform::TunIo。

Apple 与 Android

TunRuntime -> RustTunIo -> 宿主持有的 TUN fd 副本
  • iOS/macOS:宿主提供 utun 文件描述符,适配器处理四字节 packet-information 头。
  • Android:VpnService 提供 raw-IP 文件描述符。
  • Linux:产品入口不支持,即使依赖能够编译也会失败关闭。

宿主始终拥有原始文件描述符。VCore 启动时:

  1. 验证文件描述符有效且已设置 O_NONBLOCK;
  2. 通过 F_DUPFD_CLOEXEC 创建 VCore 持有的副本;
  3. 把副本交给同步 TUN device,并用 Tokio AsyncFd 驱动;
  4. 停止时只关闭副本。

VCore 不调用会修改共享 open-file-description 标志的异步构造器。tunFraming 是严格宿主协议:Apple 只接受 utun,Android 只接受 rawIp,不自动探测。

包 I/O 规则:

  • recv == 0 表示设备关闭;
  • 首个半字节必须表示 IPv4 或 IPv6;
  • 单次读取缓冲区固定为 1,500 字节;
  • 写入必须一次完成整个包,部分写入立即失败;
  • Apple PI 头不进入 netstack,也不计入流量。

Windows VPN

VpnChannel callback
  -> WindowsPacketAdapter
  -> 有界队列
  -> 同包 packet channel
  -> WindowsTunIo
  -> TunRuntime

Windows 使用 Windows.Networking.Vpn 回调,不使用文件描述符或适配器 ring:

  • Provider 在回调内复制 VpnPacketBuffer 字节,不保存系统缓冲区的借用;
  • 顶层 ipv6: false 时,Provider 向 StartWithMainTransport 传 null IPv6 client-address 参数,不分配 IPv6 TUN 地址,也不安装 IPv6 路由或 DNS;startVpn 的 IPv6 地址字段仍严格必填并经过验证;
  • Windows profile 固定覆盖所有应用;Provider 按 policy 设置本地子网旁路,并把最多 64 条规范目标 CIDR 加入 exclusion routes;
  • 系统和 Provider 创建的缓冲区都按 WinRT 所有权规则归还;
  • 回调不等待管道 I/O,入站和出站队列保持有界;
  • 空到非空的回环唤醒只通知 Decapsulate 排空响应队列;
  • Provider 与完全信任的 Session Host 通过安装包命名空间中的控制管道和数据管道交换原始 IP 包;
  • 数据帧为 u16 长度加 1..=1500 字节数据。写端最多合并 8 个已经就绪的帧,读端使用 64 KiB 缓冲区并逐帧校验;
  • EOF、截断、超限、任务异常和进程退出都会停止当前会话。

完整契约见 Windows VPN 平台边界 和 Windows 会话运行时。

MTU 与结构上限

用户 TUN 配置当前只接受 MTU 1500。Windows 因 StartWithMainTransport 平台上限对 L3 接口和 Session Host netstack 使用 1400;packet channel 仍保留 1500 字节解析上限:

原始 TUN 包                   1,500 字节
最终代理 UDP 负载             1,452 字节(Windows 1,352)
包队列                        256
普通事件 / UDP 响应           128
DNS 入站 / DNS 响应           128 / 128

TCP 会话、普通 UDP 关联、半开连接和出站握手不设固定业务数量上限。结构安全由有界队列、每流缓冲区、解析大小、超时、空闲清理和缓存提供。

物理出口

  • Android:每个出站 TCP/UDP socket 在 connect 前调用宿主 protect;失败则当前连接失败关闭。
  • Windows:Provider 为当前会话选择不可变的物理网络绑定;每个地址族只从非 link-local 地址中选择一个源 IP 和接口索引交给 Session Host,同时独立保留物理适配器全部去重的 on-link prefixes(包括 link-local)用于 VPN 路由。普通出站 socket 必须同时绑定源地址和 WinSock 接口索引。
  • Windows 只有配置中显式使用 127.0.0.0/8 范围内的 IPv4 字面量或 ::1 的本地出站可以跳过物理绑定;物理代理服务器的域名解析到任何回环地址都会失败关闭。
  • 物理适配器、选定源地址、全部 on-link prefixes 或网络身份变化后,Provider 等待 2 秒消抖并停止会话,不迁移 socket 或自动回退。

主机测试只能证明帧、所有权、队列和生命周期逻辑;平台实测范围见 验收矩阵。