#moonnet-lab

#它解决什么问题

#给谁用

• 学与教拥塞控制的人：把公式变成能动手的实验，不需要 Mininet，不需要 root，不需要 Linux。
• 设计与评估协议和算法的人：写一个算法就是实现一个 7 方法的接口；库自带 RFC 标准实现作为对照基线，丢包按包身份决定，两行遇到的是同一串丢包。
• 将来做 MoonBit 网络栈的人：把它当作回归测试台——MoonBit 目前没有网络协议栈，一旦有人开始写，最先需要的就是能在 moon test 里跑的确定性验证环境。

#当前状态

#快速开始

moon test                        # 运行全部测试
moon run cmd/moonnet -- list     # 列出 scenarios 目录里的实验
moon run cmd/moonnet -- run scenarios/long-fat.json --cc cubic
moon run cmd/moonnet -- run scenarios/bufferbloat-shallow.json --cc reno --trace --json > trace.json
moon run cmd/moonnet -- plot trace.json > trace.svg
moon run cmd/moonnet -- compare scenarios/long-fat.json --cc reno,cubic
moon run cmd/moonnet -- sweep scenarios/small-buffers.json --field loss --from 0 --to 0.02 --steps 5
moon run cmd/moonnet -- sweep scenarios/bufferbloat.json --field queue_packets --from 16 --to 600 --steps 5 --cc reno,cubic --seeds 3
moon run cmd/moonnet -- run scenarios/fairness.json   # 多条流抢一条链路
moon run cmd/moonnet -- run scenarios/bufferbloat.json --discipline codel

#作为库使用：命令行只是一个使用者

let sim = @sim.Sim::new(seed)                     // 虚拟时钟 + 冻结的随机源
let pair = @tcp.LinkPair::new_with_cc(            // 两个端点 + 两条链路
  sim,
  @tcp.TcpConfig::new(1000, 64000, 1000U),
  @tcp.TcpConfig::new(1000, 64000, 5000U),
  @net.LinkSpec::new("up", 10_000_000L, @sim.Time::from_ms(25L), @net.QueueSpec::packets(64)).with_loss(0.01),
  @net.LinkSpec::new("down", 10_000_000L, @sim.Time::from_ms(25L), @net.QueueSpec::packets(64)).with_loss(0.01),
  seed,
  @tcp.cubic(1000),
)
pair.connect(sim)
pair.client.send(sim, Bytes::make(1_000_000, b'x'))
sim.step_until(() => pair.server.delivered_bytes() == 1_000_000) |> ignore

• examples/embed_tcp——不读场景文件、不解析命令行，直接调用协议模型；测试断言同一 seed 两次运行结果一致。
• examples/rpc_retry——带自己的协议（超时 + 有限重试）复用时钟与链路模型，moon test 断言重试预算把未送达的调用从 13/20 降到 4/20。

moon run examples/embed_tcp/main    # 三个算法跑同一段传输
moon run examples/rpc_retry/main    # 不同丢包率下，一次调用要几次重试

#一个例子：同一个丢包，代价差二十倍

#拥塞控制：为什么必须慢下来

moon run cmd/moonnet -- compare scenarios/small-buffers.json --cc none,reno

scenario:   small buffers (seed 9, 200000 bytes, 1 run each)

algorithm  mean       fastest    slowest    throughput  retransmits  timeouts
none       3908.214s  3908.214s  3908.214s         0.4          105        70
reno       662.277ms  662.277ms  662.277ms      2415.9            2         0

scenario:   long fat path (seed 9, 20000000 bytes, 1 run each)

algorithm  mean      fastest   slowest   throughput  retransmits  timeouts
reno       214.129s  214.129s  214.129s       747.2          425        27
cubic      318.218s  318.218s  318.218s       502.7          199        12

algorithm  mean      fastest   slowest    throughput  retransmits  timeouts
reno       706.083s  214.129s  1312.194s       226.6         1177       112
cubic      218.618s  166.922s   318.218s       731.8          591        23

#实验是文件，不是代码

moon run cmd/moonnet -- list
moon run cmd/moonnet -- run scenarios/long-fat.json --cc reno
moon run cmd/moonnet -- run scenarios/long-fat.json --cc cubic
moon run cmd/moonnet -- run scenarios/long-fat.json --json > report.json

{
  "name": "long fat path",
  "seed": 9,
  "payload_bytes": 20000000,
  "algorithm": "reno",
  "uplink":   { "bandwidth_bps": 100000000, "delay_ms": 50, "loss": 0.01, "queue_packets": 2000 },
  "client":   { "mss": 1000, "receive_window": 2000000 }
}

#对比与扫描

moon run cmd/moonnet -- compare scenarios/long-fat.json --cc reno,cubic

scenario:   long fat path (seed 9, 20000000 bytes, 1 run each)

algorithm  mean        fastest     slowest     throughput  retransmits  timeouts
reno       214.129s    214.129s    214.129s         747.2          425        27
cubic      318.218s    318.218s    318.218s         502.7          199        12

note:       loss follows packet identity, so every row meets the same lost
            packets on a given seed. Acknowledgments carry no identity and
            fall back to transmission order, so their losses still differ.
            In a lossy scenario a few sixty-second timeouts dominate the
            total; more than one run is what makes the mean meaningful.

moon run cmd/moonnet -- compare scenarios/long-fat.json --cc reno,cubic --seeds 4

moon run cmd/moonnet -- sweep scenarios/small-buffers.json --field loss --from 0 --to 0.02 --steps 5 --cc reno,cubic

scenario:   small buffers, sweeping loss

loss    reno kbit/s  cubic kbit/s
0.0000        919.5         744.4
0.0100        597.2         601.7
0.0200        574.4         414.1

times:
loss    reno    cubic
0.0000  1.740s  2.149s
0.0100  2.678s  2.659s
0.0200  2.785s  3.863s

#多条流抢一条链路

"flows": [ { "algorithm": "reno", "count": 2 }, { "algorithm": "cubic", "count": 2 } ]

moon run cmd/moonnet -- run scenarios/fairness.json

scenario:   fairness: two reno against two cubic (seed 9, 4 flows sharing one path, 10.000s window)

flow    algorithm  delivered  share %  kbit/s  retransmits  timeouts
flow 0       reno    3789000     31.0  3031.2            0         0
flow 1       reno    1062987      8.7   850.3           62         0
flow 2      cubic    3777000     30.9  3021.6            0         0
flow 3      cubic    3564000     29.2  2851.2            4         0

total:      12192987 bytes
fairness:   0.8754 (Jain index over the shares above)
uplink:     65 dropped at the queue, 1 lost on the wire

• 测量在窗口处停止，不再排空事件队列。 退出窗口后如果继续跑，迟到的 ACK 会释放更多数据，总量会描述一个比报告窗口长得多的区间——第一版就是这么错的：20 MB 数据"在 5 秒内"通过了 10 Mbps 链路。
• Jain 指数只在所有流都还有数据要发时才说明问题。 报告里有一个饱和标记：若某条流把申报的量发完了，它退出竞争，份额数字反映的是申报量而不是路径。
• 同一算法的两条流不必然均分。 跨 9–12 四个种子，两条 CUBIC 流始终拿到两条 Reno 流约两倍的份额（合计 7.3–9.2 MB 对 3.9–4.8 MB），但同算法内部谁多谁少随种子改变，Jain 指数在 0.77–0.93 之间。也就是说"混合部署里 CUBIC 更占优"是稳定结论，"哪条流排第一"不是。

#缓冲区该多深：同一段传输，四种队列策略

"uplink": { "bandwidth_bps": 5000000, "delay_ms": 10, "queue_packets": 600, "discipline": "codel" }

moon run cmd/moonnet -- run scenarios/bufferbloat.json                        # drop-tail
moon run cmd/moonnet -- run scenarios/bufferbloat.json --discipline codel
moon run cmd/moonnet -- run scenarios/bufferbloat.json --discipline red
moon run cmd/moonnet -- run scenarios/bufferbloat-shallow.json                # 同一条路径，缓冲区 64 个包

1. 深缓冲区不等于更有余量，它更慢。 同一条路径、同一份数据，缓冲区从 64 个包加到 600 个包：传输从 7.4 秒涨到 16.6 秒，最坏排队延迟从 104 毫秒涨到 979 毫秒。全程 0 次超时、614 次快速重传——代价来自 CUBIC 对"一次溢出里成批丢失"的恢复，以及被自己的队列拉到近一秒的往返时间，不是定时器。
2. CoDel 修的正是这件事，而且吞吐更高。 它在缓冲区还空着一大半时就开始拒绝包（34 次拒绝全部是提前丢弃），发送端随之收缩窗口，队列不再站着：最坏排队延迟降到 226 毫秒，传输快了 3.3 倍，吞吐从 1445 涨到 4758 kbit/s（同一条 5 Mbps 链路的 95%）。
3. RED 在这条路径上把连接锁死了。 3 MB 数据用了 5.4 小时，326 次超时。RED 的判定量是"到达时更新的平均占用"：单条流把平均值推过上限之后，发送端停止发包，而这个平均值只能被到达的包推低，于是每 60 秒一次的定时器重传刚一到就被拒绝。换个拥塞控制也一样（--cc reno 是 17128.905s / 294 次超时），所以这是队列策略的性质，不是某个算法的性质。

#确定性是怎么保证的

1. 时间是整数。 虚拟时间以皮秒计数，存成 Int64。整个仿真里没有一处用浮点数做调度决策，因此不存在两个后端舍入到不同结果的可能。
2. 事件顺序有唯一解。 事件队列按 (时间, 到达序号) 排序，同一皮秒内先调度的事件先执行。没有哈希遍历、没有墙钟、没有并发。
3. 随机数是冻结的。 自带 SplitMix64 + xoshiro256**，参考向量在测试里钉死。每条链路、每条流用 fork(label) 从主种子派生独立随机流，所以新增一条无关的流不会扰动其他流的随机序列。
4. 事件处理里不分配内存。 队列用环形缓冲、容量按需增长，运行期间不分配，避免宿主内存管理影响时间行为。

#目录结构

src/sim/       虚拟时间、事件内核、随机源
src/net/       数据包、队列（含队列管理策略）、链路
src/tcp/       连接状态机、重传与恢复、拥塞控制
src/json/      零依赖 JSON 读写
src/lab/       场景、报告、对比与扫描、多流公平性
cmd/moonnet/   命令行入口
examples/      用库写的两个程序（下游的样子）
scenarios/     可编辑的实验文件
docs/          设计说明、路线图、生态定位、验证方式、接口契约、申报书

#与生态中已有工作的关系

1. 物理量可核对：时间是皮秒整数、队列按字节计量，所以"1500 字节的帧在 10 Mbps 链路上占 1.2 毫秒"是能手算验证并写成断言的，不是抽样出来的参数。
2. 协议与算法本身：TCP 状态机、RFC 6298 的 RTO 估计、Karn 算法、快速重传与多丢包恢复、Reno 与 CUBIC。通用框架里没有"拥塞窗口"这个概念。
3. 网络工程问题：这条路径上哪个算法更好、缓冲区该多大（深缓冲区比浅缓冲区慢一倍是这一版测出来的）、队列该用什么策略、多条流怎么分带宽。
4. 受控实验：丢包按包身份决定（两行遇到同一串丢包）、场景文件、固定字段顺序的报告、多种子平均——结论能被复算，也能被推翻。

#English summary

#License