vox1000
Vox1000 —— 六边形 p2p 连接框架(KCP 独苗 + secchan 上座;core 零依赖,wire 全自研,层界即开源界)
p2p
networking
kcp
hexagonal
moonbit
Author
Version
0.5.1
License
Apache-2.0
Repository
Last updated
3 days ago
Downloads
82
#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)+ PunchEngine 打洞策略口(NatShape 判形 → PunchRecipe 配方映射 + 超集状态机阶段词)+ 连接状态机 + MagicSocket/Node 门面 |
| thy1016/vox1000/adapter/sim | 确定性时钟 + 内存布线(SimFabric),编排回放测试基建 |
| thy1016/vox1000/adapter/kcp | KCP 可靠泳道(KcpLane)+ 实 UDP 缝(UdpSeam),驱动 moonkcp 纯核 |
| thy1016/vox1000/adapter/nat | NAT 面:mini-STUN/Natcheck 发现(NatcheckDiscovery)+ 打洞驱动(PunchSession/PunchMount,moonnat NatPump 径) |
| thy1016/vox1000/adapter/relay | 中继承载(RelayCarrier)+ 打洞装配(PunchMount 布线),驱动 moonrelay |
| thy1016/vox1000/adapter/gate_moongard | 授权面 adapter:moongard token 接入 CallGate 方言 |
| thy1016/vox1000/examples/ | 绿门三对打 demo(真 UDP + 加密握手 + 协议路由 + 可靠流;t5 公网三门 relay/punch/full) |
#特性
- 六边形分层:核心域(Domain + Ports + Orchestration)零传输、 零密码学、零时钟依赖;变点只立三扇门(网络缝 / 发现 / 协议处理器), 决策面纯函数、IO 面 async。
- 保底在前(relay-bootstrap):先经中继通、直连并行打洞、成则 静默换道、败则中继续流;路径选择是纯函数(path_select),策略 可配(direct_bias / rtt 门限)。
- 打洞策略可插拔:判形→配方映射(NatShape × PunchRecipe)+ 统一 超集状态机(observe → bookkeeping → probe → pump → confirm → fallback, 形态只影响参数与阶段退化);PunchEngine port 单口多实现——实现可插拔 (公共桩/私有引擎),失败自动落中继兜底。裁定与演进见 spec §12。
- 三面安全正交:身份面 = 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)。
#快速上手
最小对打(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
Install
Download zipVox1000 —— 六边形 p2p 连接框架(KCP 独苗 + secchan 上座;core 零依赖,wire 全自研,层界即开源界)
p2pnetworkingkcphexagonalmoonbit
Apache-2.0
Updated 3 days ago
82 downloads