SDK: - Add build_config/migrate_config, mesh_cidrs, route_generation, health and start_bridged; expose abi_info (capability revision 2). - Add wait_routes long-poll; stop wakes waiters, and context_free now stops the network immediately instead of waiting for waiters to time out. Hosts: - Dart: waitRoutes(), MeshProxySession route watcher, ABI capability check. - Android: fix a deadlock where every VPN request waited on its own single-thread worker; requests are now async, status is served from a snapshot, and combined mode reports Partial when the mesh stops. - macOS helper: mesh-only unified mode stops when the mesh is lost; installed_subnet_routes excludes the overlay. - Lab: restore Partial sessions, write migrated profiles back, remove the unreachable TOML import dialog; native test now connects via the form. Docs updated accordingly. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
72 lines
10 KiB
Markdown
72 lines
10 KiB
Markdown
# C ABI v1
|
||
|
||
声明位于 `crates/meshport-ffi/include/meshport.h`。
|
||
|
||
- `meshport_context_new()` 返回非零 context;失败为 0。
|
||
- `meshport_call(context, request_json)` 返回库分配的 NUL 结尾 UTF-8 字符串。
|
||
- `meshport_string_free()` 必须且只能释放该返回值一次。
|
||
- `meshport_context_free()` 停止该实例并释放资源;重复释放 context 为 no-op。
|
||
- 传入字符串必须在调用期间有效,不能传悬空指针。异常不会跨 C ABI 展开。
|
||
|
||
返回格式:`{"ok":true,"data":{...}}` 或 `{"ok":false,"error":"..."}`。
|
||
|
||
控制操作:validate/start(toml)、stop、status。
|
||
|
||
- `validate` 返回 `runtime_mode` 与 `overlay`(静态地址时为 `{address, prefix, network, routable}`,DHCP 为 null;`routable` 表示私有 IPv4 /16~/32)。可选 `check_local_overlap=true` 额外检查虚拟网段是否与本机现有接口重叠。
|
||
- `start` 同样接受 `check_local_overlap`。系统模式启动时 SDK 总是执行该检查,宿主不再自行预检。
|
||
- `build_config`(profile)由结构化表单草稿生成 SDK 接受的 TOML,返回 `toml`。`runtime_mode` 不是 `system_vpn`(包括宿主的 `unified_vpn`)时生成应用模式;`no_tun`/`use_smoltcp`、`enable_encryption=true`、`latency_first` 由 SDK 决定,宿主不再拼接 TOML。结果已通过 validate 同等校验。
|
||
- `migrate_config`(toml)移除旧版保存过、当前不接受的字段(顶层或 runtime 中的 `subnet_routes`),返回 `toml` 与 `changed`;无需迁移时原样返回。
|
||
- `abi_info` 返回 `{abi, revision, operations}`。`abi` 仍为 1;`revision` 是同一 ABI 内的能力修订号(当前 2:带 `build_config`/`migrate_config`/`start_bridged`/`wait_routes`/`health` 等),`operations` 列出支持的操作。宿主打开库后先调用它,修订号不足时给出明确错误,而不是在某个操作上才失败。旧库没有该操作,同样视为不满足。
|
||
- `start_bridged`(toml,可选 port、max_sessions、check_local_overlap、require_static_overlay)一步完成:校验应用模式、静态地址须可路由、可选要求静态地址与本机冲突检查,再启动网络与 SOCKS 桥接;任一步失败两者都不保留。返回 `engine_started`、`listen`、`overlay`、`mesh_cidrs`、`route_generation`。
|
||
|
||
`status` 的 `platform_network` 增加 `mesh_cidrs`(虚拟网段(可路由时)加已接受公告子网,规范化、排序,/32 也带后缀)、`route_generation`(`mesh_cidrs` 每次变化递增,宿主只需比较这个数)与 `overlay`。`subnet_routes` 保留,表示已接受公告子网本身。`health` 为 `{engine_running, bridge_running, mesh_routable}`,`mesh_routable` 表示宿主此刻可把 `mesh_cidrs` 流量交给桥接;停止时全部为 false。宿主不再自行计算前缀或判断组网是否可用。
|
||
|
||
`wait_routes`(可选 `after_generation`,`timeout_ms` 1–30000,默认 25000)长轮询路由变化:`route_generation` 与 `after_generation` 不同或网络停止时立即返回,否则超时返回 `changed:false`。返回 `running`、`changed`、`route_generation`、`mesh_cidrs`、`subnet_routes`。它不占用 context 的串行锁,等待期间 status、stop 等请求照常执行;需在独立线程/isolate 调用。网络停止时 SDK 会递增 generation、清空路由并标记停止,等待方被唤醒并得到 `running:false`。没有网络时立即返回 `running:false`(传了 `after_generation` 时 `changed:true`)。`meshport_context_free` 会立即停止网络并唤醒在途等待,不必等其超时。
|
||
|
||
`validate` 的 `include_profile=true` 投影将 `flags.foreign_relay_bps_limit` 编码为十进制字符串,以精确保留 u64 范围;宿主重新生成 TOML 时也应使用十进制字符串。默认无限制值为 `"18446744073709551615"`,不能经过浮点数转换。Flutter 会迁移旧配置中被舍入的默认无限制值,其他不精确或越界值要求重新输入。
|
||
|
||
应用内组网桥接:`socks_start`(可选 port,默认 0;max_sessions,默认 128)、`socks_status`、`socks_stop`。数据转发直接走原生并发任务,不经 JSON 字节 I/O。仅支持 IPv4 回环 SOCKS5 TCP/UDP;域名、IPv6、不支持的命令不做外部回退。stop/context free 先清理桥接再停止网络;socks_stop 不停止组网。需要新版原生库,详见 [SOCKS 桥接](socks-bridge.md)。
|
||
|
||
Android 系统模式需宿主 VpnService 创建 TUN 后调用 attach_tun(fd)。fd 由宿主持有,原生库不负责关闭;必须在原生实例停止后再关闭,替换网卡时须等新接口 ready 后关闭旧 fd。启动前注册 meshport_set_android_socket_protector,将原生 worker 的外层 socket 交给 VpnService.protect,回调与 JVM 桥接需保持有效。参考客户端 MeshVpnService 和 JNI NativeBridge。
|
||
|
||
TCP:tcp_connect(target)返回 resource;tcp_write(resource、bytes);tcp_read(resource、max_bytes、timeout_ms)返回 bytes/eof。
|
||
|
||
UDP:udp_bind(port,0 表示动态端口)返回 resource;udp_send(resource、target、bytes);udp_receive(resource、timeout_ms)返回 bytes/source。仅接收已建立远端 flow 的报文。
|
||
|
||
resource_close 关闭指定资源。资源不能跨 context 使用;停止后资源全部失效。
|
||
|
||
probe:target、protocol(TCP/UDP)、echo、timeout_ms。TCP echo=false 只测建连;TCP echo=true/UDP 验证回显字节。UDP 必须 echo=true。耗时包括相应操作全过程,并非基础线路纯 RTT。
|
||
|
||
单次 JSON 请求 ≤128 KiB,配置 ≤64 KiB;写数据建议按16 KiB分块。UDP bytes ≤65507;TCP read 最大65535。普通 I/O 超时 1–30000 ms,默认5000 ms。连接/绑定超时当前固定5000 ms。
|
||
|
||
该 ABI 同步且每 context 串行(`wait_routes` 除外),必须在后台线程执行。停止和释放会等待在途请求完成(`wait_routes` 会被唤醒而非等待);当前不提供立即取消。TCP超时后可能已有部分字节发出,不应直接重发整个消息。后续生产版需异步资源接口和结构化错误码。
|
||
|
||
## 网络遥测
|
||
|
||
`status` 增加 `traffic`:`rx_bytes` / `tx_bytes` 为当前引擎运行期间采样到的累计隧道字节,`rx_bytes_per_second` / `tx_bytes_per_second` 是两次状态采样间的平均 B/s。首次采样速率为 null,重启引擎重新计数。包含组网控制、心跳和转发流量,不等于应用有效载荷。计数来自存活连接快照;若连接在两次采样之间消失,最后一次采样后的字节可能未计入。
|
||
|
||
`nodes` 是 SDK 合并 routes 与 peers 后的节点视图(排除本机,routes 顺序在前):`path`(direct/relay)、`direct_available`、`hole_punched`、`latency_ms` 与 `latency_source`(link_rtt / route_estimate / null)、`metered` 及该节点链路的 rx/tx 字段。直连且有 RTT 时取链路 RTT,否则取路由估算;界面直接展示,不再自行判定。
|
||
|
||
`peers` 增加默认连接的 `latency_ms`(EasyTier ping RTT;未测出为 null),当前存活连接合计字节及采样速率。`routes` 增加所选路由的 `estimated_latency_ms` 与 `next_hop_peer_id`;估算为路由各链路延迟之和,不是端到端实测 RTT。多连接节点的 RTT 来自默认连接,流量为全部存活连接之和。中继目标未单独归集流量,其流量计入下一跳隧道。
|
||
|
||
`diagnostics_enable` 显式开启进程级穿透 tracing 采集,返回 enabled 与 scope。SDK 默认不安装全局 subscriber;已有宿主 subscriber 时 enabled=false,宿主应自行开启 EasyTier 穿透日志。启用后不可在本进程中卸载,采集仅匹配 easytier_core::connectivity::hole_punch,最多 200 条、每条 4 KiB;status 增加 diagnostic_traces,含递增 sequence,可跨采样去重。多实例共享采集范围;诊断中含节点地址,导出时当前网络密钥脱敏。
|
||
|
||
路由诊断增加 version、udp_nat_type、disable_p2p、need_p2p;cost 与 next_hop_peer_id 使用同一路由策略。peers.direct 表示存在物理直连,判断目标当前是否走直连还应核对对应 routes.next_hop_peer_id 是否等于目标 peer_id。
|
||
|
||
注意上游 directly_connected_conns 只统计非打洞连接,本 SDK 不再直接以其为空推断中继。peers.direct 包括 TCP/UDP 打洞后的物理连接,hole_punched 表示存在上游归类为打洞的存活连接。页面的直连/中继标签仍根据所选下一跳判断,而非仅根据 direct。
|
||
|
||
`quality_sample` 请求:`resource` 为已绑定 UDP 句柄,`target` 为 IPv4:port,`sequence` 为 u64,`timeout_ms` 为100–5000(默认1000)。返回 success、elapsed_ms、target_peer_id、next_hop_peer_id、next_hop_after、route_changed。超时/I/O错误返回 success=false、elapsed_ms=null;非法句柄或参数走 ABI 错误。复用 socket 并顺序调用,目标须支持原样 echo;状态前后采样不计入 RTT。
|
||
|
||
|
||
### 高级受管理代理配置(2026-10-11)
|
||
|
||
`direct_dns_server` 可选,`proxy_dns_server` 支持普通 IP DNS、HTTPS DoH、TLS DoT。`dns_server` 保留为独立 IP 启动解析器。直连模式不建立代理 DNS 依赖;代理 DNS 非直连模式需要手动选择代理节点。
|
||
|
||
`rule_sets` 是最多 32 个受管理条目的数组:`tag`(唯一)、`enabled`、`action`(proxy/direct/reject)。远程条目使用 `url`(HTTPS)、`format`(source/binary)、`download_detour`(direct/proxy)、`update_hours`(1–168,默认 24);内联条目使用 `rules`(sing-box headless 规则)。远程和内联不能混用,不接收特权文件路径。仅规则模式加载规则集,组网保护优先。配置入口仍拒绝未知字段及超过 64 KiB 的请求;不接受完整未管理 sing-box 配置。
|
||
|
||
订阅的 `auto_update` / `interval_minutes`、代理配置的 `proxy_enabled` 以及平台启动首选项由客户端持久化层管理,不是 EasyTier 组网 SDK 新参数。版本 1 配置可读取旧字段缺失的保存数据。自动连接仍按系统权限实际结果报告状态。
|
||
|
||
## 代理 DNS 保护
|
||
|
||
sing-box 引擎配置新增可选布尔字段 `dns_protection`。启用后,非直连互联网模式要求明确的 `proxy_dns_server` 和代理节点,普通解析和默认域名解析器均使用代理 DNS;不配置默认公共解析器,不回退启动 DNS。Flutter ProxyProfile 默认发送此字段,旧 JSON 调用未设置字段时兼容旧行为。代理节点与解析器主机名使用受管理 bootstrap 解析以避免循环;仅组网与直连模式保持独立。宿主应在关闭旧会话之前执行连接校验。
|