#MoonKCP

#特性

• 协议核心：ACK 结算、选择性与超时重传、快速重传、窗口探针、拥塞门限， 全量直译 C 参照。
• 会话壳 KcpSession：消息分片与碎片合并、发送水位背压、FIFO 收件队列。
• 多会话服务端 KcpServer：按报文头 conv 路由、未知会话自动建立、 会话数上限护栏、闲置回收。
• UDP 适配器：KcpUdpPeer（双端直连）与 KcpUdpHub（单 socket 多会话 组合宿主）。
• 观测面 Kcp::stats：RTT、RTO、拥塞窗、队列读数、接收守恒账。
• FEC 前向纠错层 fec/（可选）：Reed-Solomon 系统码（GF(2^8)、Cauchy 阵 MDS），组内 ≤m 丢失当场恢复不等重传；MdsCodec 端口可换编码器， FecSession 组合壳一键接入。
• 差分对拍：与 C 参照在确定性丢包、乱序、停摆场景下帧转录逐字节一致。

#安装

moon add thy1016/moonkcp

#快速上手

#协议核心（零 IO 零时钟）

let sender = @moonkcp.Kcp::create(1)
let receiver = @moonkcp.Kcp::create(1)
sender.set_nodelay(1, 10, 2, 1)
let _ = sender.send(payload)
let frames = sender.update(now_ms)
for frame in frames {
  let _ = receiver.input(frame)
}
match receiver.recv() {
  Some(msg) => // 整消息（碎片已合并）
  None => () // 暂无就绪消息
}

#会话壳

let session = @moonkcp.KcpSession::new(1, 128)
let n = session.send_message(payload)   // 窗口满返回 -2（背压）
let code = session.on_datagram(datagram)
let frames = session.tick(now_ms)

#UDP 适配器

let hub = @adapter.KcpUdpHub::listen(128, 1024)   // 服务端：多会话
let peer = @adapter.KcpUdpPeer::connect_client(7, 128, hub.local_addr())

#FEC 前向纠错（可选层）

let session = @moonkcp.FecSession::new(1, 128, 3, 2) // conv, 背压水位, k, m
let n = session.send_message(payload)
let wire = session.tick(now_ms)        // 组满同突发附带冗余帧
let code = session.on_datagram(frame)  // 线帧进;恢复对应用透明
match session.poll_message() {
  Some(msg) => // 整消息
  None => ()
}

• 线格式：12B 自描述头（group_id / shard_index / k / m / payload_len）， 逐组参数由发侧单边拍板、收侧零协商（合同 = domain/fec_dialect.toml）。
• 语义：数据帧即刻透传（零排队延时）；组齐 k 片当场恢复补投；尾组不满 k 不闭组，>m 丢失回落 ARQ 兜底。
• 开销：带宽冗余 m/(k+m)——(3,2) 为 40%，(10,3) 为 23%；CPU 读数 moon run workspace/fec_bench --release（RS(10,3)/1200B 片：编码 ~100 MB/s、最坏恢复 ~45 MB/s、层直通 ~9 MB/s，百 KB/s 量级视频流 占 CPU 不足 1%）。
• 六边形：MdsCodec 端口注入，RS 仅为缺省适配器；编解码器工厂逐组 实例化（k/m 随帧头自描述），换码 = 换适配器，层机器零改动。

#API 总览

#错误面

• Kcp::input：-1 长度不足或 conv 不符；-2 声明长度超出报文余量； -3 非法命令字节。
• KcpSession::send_message：-2 发送窗口满（背压拒收）；成功返回 接受字节数。
• KcpServer::on_datagram：-4 会话表满，报文弃置。
• Kcp::recv：None 表示队列为空或碎片未齐。

#设计边界

• 仅消息模式；KCP 的 stream 追加模式不提供。
• 协作式单运行时内使用，非线程安全；跨线程事件须经运行时进入。
• 协议核心全后端可移植；适配器因原生 socket 限 native 后端。
• FEC 层为核外可选层：不接入即不存在；KCP 差分对拍门与 FEC 门互不触及。
• 吞吐扩展按实测判据重估，当前未排期。

#测试与验证

moon test --target native
node workspace/async_watchdog.mjs
node workspace/diff_gate.mjs
node workspace/bench.mjs

#许可证

• 本项目代码采用木兰宽松许可证第 2 版（MulanPSL-2.0，见 LICENSE）。
• .tests/kcp/ 内 C 参照文件按 MIT 许可分发，版权归其原作者。
• 无背书声明：文中对拍与基准计数为本项目自测结果，不构成任何第三方 的认证或背书。