Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 89 additions & 12 deletions quest/m1/quic/bbr-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,9 @@ qmux, stream scheduling, or other unrelated QUIC features.

## Plan

After the fork bootstrap, publish the corrected dependency chain and update
MoQ's manifest and lockfile pins. Record the parent commit, carried patches,
and upstream status. Follow the existing fork packaging rules; no mutable
branch or workspace-only patch may stand in for a release.

Fixes merged in the fork and awaiting release:
The fixes are merged in moq-dev/noq `main` and ship as 1.3.1 of
`moq-noq-proto`, `moq-noq-udp`, `moq-noq`, and `web-transport-moq`, which
share one version:

- [moq-dev/noq#3](https://github.com/moq-dev/noq/pull/3) - BBR packet identity across QUIC spaces
- [moq-dev/noq#4](https://github.com/moq-dev/noq/pull/4) - each BBR ACK sample completes before the model uses it
Expand All @@ -23,12 +20,92 @@ Fixes merged in the fork and awaiting release:
- [moq-dev/noq#8](https://github.com/moq-dev/noq/pull/8) - packets sent during ProbeRTT are application-limited, so its reduced rate cannot lower BBR's bandwidth model
- [moq-dev/noq#9](https://github.com/moq-dev/noq/pull/9) - a spurious loss episode restores the BBR model, window, and probe saved when the episode began

Verify the fork's regression suite and MoQ's default and supported runtime
builds against the released artifacts, including compatibility of controller
consumers if a callback API changed. Run a media-shaped transfer through the
real QUIC stack to confirm handshake sampling, pacing, and recovery work
together. This integration check is required; the broader media-flow study
and Google comparison do not gate these bug fixes.
[moq-dev/noq#10](https://github.com/moq-dev/noq/pull/10) prepares the
release. It bumps the version and internal pins, and adds `CHANGELOG-MOQ.md`,
which names the parent (n0-computer/noq `1a26a8b0`, unchanged since 1.3.0),
the carried set, and each change's upstream status. Upstream has only #7's
root, [n0-computer/noq#802](https://github.com/n0-computer/noq/pull/802) (open);
the rest go upstream with the [upstream quest](/quest/m1/quic/upstream.md).
The API change is additive (new `Controller` callbacks that default to the
deprecated ones they replace), and `cargo semver-checks` against 1.3.0 is
clean for all four crates. It ships as a patch so MoQ's `"1.3"` requirements
pick it up unchanged.

Release steps, in order:

1. Merge moq-dev/noq#10.
2. On crates.io, confirm all four crates list moq-dev/noq `moq-release.yml`
as a trusted publisher. `web-transport-moq` 1.3.0 was published apart from
the other three.
3. Tag the merge commit: `git tag v1.3.1 <merge-sha> && git push origin v1.3.1`.
`moq-release` checks the tag against the workspace version and runs
`cargo publish --workspace`.
4. Here, `Cargo.toml` keeps `"1.3"`. Run
`cargo update -p moq-noq-proto -p moq-noq-udp -p moq-noq -p web-transport-moq`.
The lock then holds the four at registry 1.3.1, and
`cargo tree -d --workspace --all-features` shows no second copy.
5. Run `just check`, `just rs tokio-features`,
`cargo clippy --locked -p moq-tokio -p moq-uring -p moq-relay --all-targets --all-features -- -D warnings`,
`cargo nextest run --locked -p moq-tokio -p moq-uring -p moq-relay --all-features`,
and the media check below with release builds of `moq-relay` and
`moq-bench`.
6. The PR that lands the lockfile deletes this quest. It changes no
manifest, so the published `moq-tokio` and `moq-uring` still accept
1.3.0. A new resolve picks 1.3.1, but a downstream lock that already has
1.3.0 keeps it until `cargo update`.

The media check sends one 4.8 Mbps track (30 fps, 20 kB frames, 1 s groups)
to two subscribers through `moq-relay` over QUIC with the default Delay
family (BBR). From the repository root, the loopback runs in a rootless
network namespace shaped by netem. The relay config is
`test/interop/interop.toml`: bind `127.0.0.1:4443`, `tls.generate`, public
auth, no iroh. The client disables the WebSocket fallback, since it wins the
race under loss, and the relay log must show three QUIC sessions and none
over WebSocket.

`moq-bench` exits 0 whenever any group arrives, which the broken 1.3.0
release still does. The shell keeps that exit status, so a successful `kill`
cannot hide a failed benchmark, and then refuses the 1.3.0 shape on this
path: under 60 MB received, p50 over 150 ms, or p99 over 400 ms. Those
cutoffs sit between the columns below.

```bash
unshare -rn bash -c '
ip link set lo up
tc qdisc add dev lo root netem delay 20ms loss 2% rate 40mbit
moq-relay test/interop/interop.toml &

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Run the checkout's release binaries explicitly

In a fresh checkout using the repository-required Nix development shell, neither moq-relay nor moq-bench is on PATH, and the preceding clippy and nextest commands do not create release executables. The documented release gate therefore stops here, or can accidentally test an unrelated globally installed version instead of the newly locked crates. Add an explicit release build and invoke target/release/moq-relay and target/release/moq-bench. (Written by GPT-5.6 Sol)

AGENTS.md reference: AGENTS.md:L82-L83

Useful? React with 👍 / 👎.

sleep 1
moq-bench --connect http://localhost:4443 --connect-websocket-enabled=false \
--fanout media --connections 3 --startup 1s --duration 60s --report 5s \
--fps 30 --frame-size 20000 --group-size 29 --output stats.jsonl
Comment on lines +78 to +80

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Gate the release on corrected media performance

When a BBR regression still delivers some media, as the documented 1.3.0 results do, this command exits successfully because Stats::ensure_delivery only requires groups_recv > 0; stats.jsonl is written but never checked against the 1.3.1 throughput or latency expectations. Consequently the required release gate can pass with the known-bad behavior even after the benchmark exit status is preserved. Add an explicit assertion on the recorded delivery and latency results.

AGENTS.md reference: AGENTS.md:L18-L18

Useful? React with 👍 / 👎.

status=$?
kill %1
exit "$status"' &&
python3 -c '
import json, sys
snap = json.loads(open("stats.jsonl", encoding="utf-8").read().splitlines()[-1])
recv, p50, p99 = snap["bytes_recv"], snap["latency_p50_ms"], snap["latency_p99_ms"]
if recv < 60_000_000 or p50 > 150 or p99 > 400:
sys.exit(f"media check looks like 1.3.0, not 1.3.1: bytes_recv={recv} p50={p50} p99={p99}")
'
```

Repeat only the `unshare` with `delay 20ms loss 1% rate 16mbit`, just above
the offered load, and compare that run to the table. Do not reuse the python
cutoffs there: 1.3.0 already delivers most of the bytes and the latency
ranges overlap, so that row is a capacity check, not a pass/fail gate.

Local runs against the fork through a `[patch.crates-io]` on
2026-09-25, two per cell, of about 71 MB offered:

| Path | 1.3.0 received | 1.3.0 latency p50 / p99 | 1.3.1 received | 1.3.1 latency p50 / p99 |
|---|---|---|---|---|
| 2% loss, 40 Mbps | 23-26 MB | 241-340 / 916-1076 ms | 69 MB | 54-55 / 131-141 ms |
| 1% loss, 16 Mbps | 53-55 MB | 115-120 / 334-414 ms | 57-61 MB | 130-132 / 293-376 ms |

The published crates are the same source, so a rerun against them should
match the 1.3.1 columns. The broader media-flow study and the Google comparison do not gate
these fixes.

## Related

Expand Down
Loading