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>
10 KiB
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 桥接。
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 解析以避免循环;仅组网与直连模式保持独立。宿主应在关闭旧会话之前执行连接校验。