vox1000

六边形 p2p 连接框架(MoonBit):PeerId 身份、端点发现、路径选择、连接 状态机、协议路由、可靠/有损双泳道、三面安全(身份 / 授权 / 保密)—— 千里传音,一发即达。

名字致敬金庸笔下一灯大师的千里传音:内力所至,声音直达一人耳中, 旁人只闻微风。p2p 连接框架的本分正在于此——穿过 NAT 与中继的重重 山水,把字节送到该收的那一端。

血统明示

架构思想参考 iroh(MagicSocket / Endpoint / relay-bootstrap 保底在前 / netcheck 式自检皆借其形)、 netcheck 自检借 Tailscale 思想——思想与形态致敬,线全自研:wire 帧、握手消息、relay 协议、 发现记录、协议 id 词表全部自定义,不与 iroh / libp2p / 任何 QUIC 实现线级互通。算法层是唯一遵循层(Ed25519 / AES-GCM / SHA-256 / HKDF),经 mooncry 单一真源,标准测试向量对拍即门。

包结构

包	内容
thy1016/vox1000/core	六边形核心:纯 ADT 域 + 三 port(SeamNet / PeerDiscovery / ProtocolHandler)+ 连接状态机 + MagicSocket/Node 门面;依赖仅 moonbitlang/async
thy1016/vox1000/adapter/sim	确定性时钟 + 内存布线(SimFabric),编排回放测试基建
thy1016/vox1000/adapter/kcp	KCP 可靠泳道(KcpLane)+ 实 UDP 缝(UdpSeam),驱动 moonkcp 纯核
thy1016/vox1000/adapter/gate_moongard	授权面 adapter:moongard token 接入 CallGate 方言
thy1016/vox1000/examples/	绿门三对打 demo(真 UDP + 加密握手 + 协议路由 + 可靠流)

状态:0.1.0。0.x 实验期,API 仍可能随反馈调整;未经独立安全审计。 协议形态与演进锚见 spec.md;分步文档见 guides/。

特性

• 六边形分层:核心域(Domain + Ports + Orchestration)零传输、 零密码学、零时钟依赖;变点只立三扇门(网络缝 / 发现 / 协议处理器), 决策面纯函数、IO 面 async。
• 保底在前(relay-bootstrap):先经中继通、直连并行打洞、成则 静默换道、败则中继续流;路径选择是纯函数(path_select),策略 可配(direct_bias / rtt 门限)。
• 三面安全正交:身份面 = ed25519 签名环(对端以宣称公钥验 "vox1000-dial-v1" 绑定串);授权面 = moongard token(CallGate 方言,sub 与 PeerId 互核);保密面 = secchan PSK-CR 握手 + AES-GCM 记录层(方向密钥 + 滑窗防重放)。未认证可收发的连接态 不存在。
• 双泳道:lane 0 控制/流走 KCP 可靠有序;lane 1 有损媒体走裸缝
  • 截止即弃——队头阻塞按道绕行。
• 事件编排:连接全程出 P2pEvent 八拍事件流 (resolved / probed / selected / established / switched / failed / closed / announced),编排面吃事件不轮询。
• 确定性回放:adapter/sim 虚拟钟 + 内存布线,绿门用例零睡眠 零竞态,注入口丢包重传全程可断言。

安装

moon add thy1016/vox1000

消费包 moon.pkg 按需添加 import:thy1016/vox1000/core(@core), 及子包 adapter/sim(@sim)、adapter/kcp(@kcp)、 adapter/gate_moongard(@gate_moongard)。

依赖自家件:moonkcp (KCP 纯核 + secchan)、moongard (token 授权)、mooncry (算法单一真源)。

快速上手

最小对打(sim 布线,双节点加密建链、协议派发):

// 布线:内存缝 + 发现;身份:32 字节种子出 PeerId(ed25519)
let fabric = @sim.SimFabric::new()
let psk = Bytes::make(32, b'\x77')           // 保密面:PSK-CR + 记录层
let peer_a = @core.peer_id_from_seed(Bytes::from_array(Array::make(32, 1)))
let peer_b = @core.peer_id_from_seed(Bytes::from_array(Array::make(32, 2)))
// 构造错误(端点非法等)以 raise P2pError 报
let node_a = @core.Node::new(
  seam=@sim.SimNode::new(fabric~, addr=@core.Endpoint::LocalIpv4("10.0.0.1", 5001)),
  discovery=@core.MemoryDiscovery::new(now=fn() { 0L }, default_ttl_ms=60000L),
  local_peer=peer_a,
  psk~,
)
let node_b = @core.Node::new(
  seam=@sim.SimNode::new(fabric~, addr=@core.Endpoint::LocalIpv4("10.0.0.2", 5002)),
  discovery=..., local_peer=peer_b, psk~,
)
// 应门:注册协议处理器(协议 = 连接级,无每流协商)
node_b.handle_protocol(
  protocol=@core.ProtocolId::parse("echo/1"),
  handler=EchoHandler,
)
// 呼叫:认证通过才有连接返回,失败即 raise P2pError——
// 未认证可收发的连接态不存在
let conn = node_a.connect(peer_b, @core.ProtocolId::parse("echo/1"))

真传输一步到位(实 UDP 缝 + KCP 可靠泳道 + 加密握手 + 授权闸):

cd vox1000 && moon run examples/green_door3 --target native

绿门三四段:UdpSeam 冒烟 → Node 双端加密 dial + 闸 + 派发 → secchan 记录层密语往返 → KcpLane 真环回三消息。授权面(token)见 guides/02-security.md。

文档

• spec.md —— 协议形态与演进锚(三层定谳 / 三面安全 / wire 形 / 版本位承诺)
• guides/ —— 分步文档:入门、安全三面、双泳道媒体策略
• const.md —— 宪法(分层律 / 三真变点律 / 连接安全律 / 密码学与 wire 律 / 工程守卫律)

License

Apache-2.0