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

72 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 解析以避免循环;仅组网与直连模式保持独立。宿主应在关闭旧会话之前执行连接校验。