- Lab app: proxy panel, node editor, configuration and detail pages, responsive layout, and related tests - Add meshport-socks crate and sing-box bridge scripts/docs - Add singbox_flutter binding and meshport_client_core package - FFI, VPN helper (unified mac path), and Android/macOS runner updates - Docs for architecture, client runtime, UI design, and validation - UI design output artifacts under outputs/ui Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
59 lines
7.1 KiB
Markdown
59 lines
7.1 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` 的 `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 串行,必须在后台线程执行。停止和释放会等待在途请求完成;当前不提供立即取消。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。
|
||
|
||
|
||
### 高级受管理代理配置(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 解析以避免循环;仅组网与直连模式保持独立。宿主应在关闭旧会话之前执行连接校验。
|