4.6 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。
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 串行,必须在后台线程执行。停止和释放会等待在途请求完成;当前不提供立即取消。TCP超时后可能已有部分字节发出,不应直接重发整个消息。后续生产版需异步资源接口和结构化错误码。
网络遥测
status 增加 traffic:rx_bytes / tx_bytes 为当前引擎运行期间采样到的累计隧道字节,rx_bytes_per_second / tx_bytes_per_second 是两次状态采样间的平均 B/s。首次采样速率为 null,重启引擎重新计数。包含组网控制、心跳和转发流量,不等于应用有效载荷。计数来自存活连接快照;若连接在两次采样之间消失,最后一次采样后的字节可能未计入。
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。