Files
MeshPort/docs/ffi-contract.md
shenleiandClaude Opus 5.5 dc1bfc99d2 Move mesh networking logic into the SDK and fix lifecycle bugs
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>
2026-10-15 18:17:42 +09:00

10 KiB
Raw Permalink Blame History

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