feat(moonnat): v0.1.0 首发收敛——README 全卷(血统明示 Tailscale netcheck·iroh autonat v2·RustDesk punch 思想线全自研 clean-room/包结构/特性/两层 API 快速上手)+ CHANGELOG 0.1.0(Keep a Changelog,moongard 形:Added 八项/Security 三条/Notes 三条——零默认名单纪律入卷)+ spec 演进承诺(0.x 同 minor)+ guides 两件(索引/入门:NatPump 回调方言与纯函数库两路)+ 版位 0.0.1→0.1.0 + 仓库指正 mbt.nat;剥离核查净(零默认 STUN 名单,宪法律 3.2 闭环);门 25/25 / check / fmt / info 绿

moonnat

NAT 画像与打洞编排纯核(MoonBit):RFC 8489 STUN 报文自实现、地址观测(autonat v2 纪律:nonce 防混淆 + dial-back 防谎报,自报不收)、打洞状态机(纯函数 reducer + 可配重试/端口预测)。核心零 IO 零时钟零随机,时间与熵全注入——moonkcp 同款纯核纪律,决策面 sim 可回放。

血统明示:Tailscale netcheck 思想、iroh autonat v2 验证纪律、 RustDesk punch 编排思想——思想与编排参考,实现与线全自研 (clean-room,Apache-2.0)。

包结构

包	内容
`thy1016/moonnat/core`	纯核:STUN 编解码 + 画像机 + 打洞 reducer + 探针口 port + Binding 事务 + NatPump 驱动器;依赖仅 `moonbitlang/async`
`thy1016/moonnat/adapter/udp`	探针口真 UDP 实现(UdpProbeSocket)

状态:0.1.0。0.x 实验期,API 仍可能随反馈调整;未经独立安全审计。结构事实与契约见 spec.md;纪律底卷见 const.md。

特性

纯核纪律:画像/打洞决策/重试全纯函数,now : Int64 与熵 (nonce 种子)全注入——核心零钟零随机,全决策确定性回放。
autonat v2 落数据面:探针 nonce 回声核对防混淆;dial-back 回连实测防谎报;自报形(nat_type 类)永不作决策输入。
RFC 8489 遵循层:报文头/属性 TLV/XOR-MAPPED-ADDRESS 自实现, RFC 5769 已知答案碎片逐字钉罐;未知属性保真保留(演进不破旧解码)。
单真变点:port 唯探针口一枚(pub(open) trait ProbeSocket); 其余 = 纯函数 + 注入参数 + 数据,变点之外不再立 trait。
两层 API:核心层(纯函数库 + reducer,宿主事件环接入)+ NatPump 驱动器(adapter 回调方言,on_picture / on_established / on_abandoned 沉没槽,独立用户五分钟上手)。

安装

moon add thy1016/moonnat

消费包 moon.pkg 按需添加 import:thy1016/moonnat/core(@core)、 thy1016/moonnat/adapter/udp(@udp)。

快速上手

画像一台机器的 NAT,再把洞打穿(真 UDP + 回声对端):

let socket = @udp.UdpProbeSocket::listen(addr_text="0.0.0.0:0")
let pump = @core.NatPump::new(
  socket,
  policy=@core.PunchPolicy::make(
    max_sends=6,
    use_port_prediction=true,
    retry_delay_ms=200L,
  ),
  callbacks=@core.NatPumpCallbacks::new(
    on_picture=fn(p : @core.NatPicture) -> Bool { true },   // no-go 可在此裁
    on_established=fn(addr : UInt32, port : Int32) -> Unit { ... },
    on_abandoned=fn(reason : String) -> Unit { ... },
  ),
  next_nonce=crypto_nonce,   // 熵注入口(生产 CSPRNG;测试计数器)
)
// 双服务器 STUN 探测入账(server 地址配置注入,本仓零默认名单)
let _ = pump.probe_once(server_id=0, server_addr=s1, server_port=3478, window_ms=500)
let _ = pump.probe_once(server_id=1, server_addr=s2, server_port=3478, window_ms=500)
// 画像出炉 → 打洞环跑到终态(回声/dial-back 全自动)
pump.launch(picture=pump.picture())
let final_state = pump.drive(attempt_window_ms=300)

宿主自有事件环?(vox1000 T5 形)——绕过 NatPump,直接吃纯核: stun_binding_probe 单轮事务 + nat_picture_of 画像 + punch_next reducer,在自己泵里驱动。

文档

spec.md —— 结构事实与契约(范围 / API 两层面 / 验收门)
const.md —— 宪法(纯核律 / 观测纪律 / 打洞编排律 / 单真变点律 / 守卫律)

License

Apache-2.0