#MoonKCP

#特性

• 纯状态机核心：Kcp::create 到 check 全量直译 C 参照——ACK 结算、 选择性与超时重传、快速重传（FASTACK_CONSERVE 变体）、窗口探针、拥塞 门限；update(current) 返回出帧，无任何隐藏时钟与系统调用。
• 会话壳 KcpSession：应用消息按 MSS 分片与碎片合并，waitsnd 水位 背压，FIFO 收件队列，链路判死透传。
• 多会话服务端 KcpServer：按报文头 conv 路由，未知会话自动建立， max_sessions 洪泛护栏，闲置回收（sweep，时钟由宿主注入）。
• async UDP 适配器：KcpUdpPeer（客户端直连 / 服务端单对端）与 KcpUdpHub（单 socket 多会话组合宿主，conv→地址自学习）。
• 观测面 Kcp::stats：RTT 平滑值、RTO、拥塞窗、在途与队列读数、超时 重传计数、接收守恒账（rcv_accepted == rcv_queue + rcv_buf 恒等可验）。
• 差分对拍保证：与 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)   // 低延迟档：interval 10ms / 快速重传 2
let _ = sender.send(Bytes::makei(64, fn(i) { i.to_byte() }))
// 每拍（间隔不大于 interval）：
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)  // conv 与背压水位
let n = session.send_message(payload)           // 窗口满返 -2（背压拒收）
let code = session.on_datagram(datagram)        // 宿主投递报文，就绪消息入队
let frames = session.tick(now_ms)               // 等价 update，返回待发帧

#UDP 适配器

// 服务端：一条 socket 服务多会话，按 conv 路由
let hub = @adapter.KcpUdpHub::listen(128, 1024)
// 客户端：connected UDP，指向服务端地址
let peer = @adapter.KcpUdpPeer::connect_client(7, 128, hub.local_addr())
// 驱动：peer.pump_out(t) 出帧、hub.recv_one() 收报、hub.pump_out(t) 回帧

#API 总览

#错误面

• Kcp::input 返回码：-1 长度不足或 conv 不符；-2 声明长度超出报文 余量；-3 非法命令字节。
• KcpSession::send_message 返回 -2 表示发送窗口满（背压拒收，应用 侧择时重试）；成功返回接受字节数。
• KcpServer::on_datagram 另有 -4：会话表满，报文弃置（洪泛护栏）。
• Kcp::recv 返回 None：队列空或碎片未齐（完整性门，不产半截消息）。

#设计边界

• 仅消息模式：KCP 的 stream 追加模式不提供；文档同步与控制面按消息 语义设计。
• 协作式单运行时内使用：非线程安全；跨线程事件须经运行时进入。
• 协议核心全后端可移植；adapter 因原生 socket 限 native 后端。
• 吞吐扩展（队列环形化等）按实测判据重估，当前未排期；基准读数见下节。

#测试与验证

moon test --target native
node workspace/async_watchdog.mjs   # async 门挂起看门狗
node workspace/diff_gate.mjs        # C 参照差分对拍
node workspace/bench.mjs            # 吞吐基准（留证不作门）

#许可证

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