Skip to content

feat(transport): schedule moq send groups by QUIC stream priority - #96

Closed
Frando wants to merge 1 commit into
Frando/cleanup-authfrom
Frando/send-groups
Closed

Frando wants to merge 1 commit into
Frando/cleanup-authfrom
Frando/send-groups

Conversation

@Frando

@Frando Frando commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Stacked on #94 and mergeable after it. It no longer depends on noq: it builds against stock noq 1.4, and cargo tree -i noq-proto shows 1.4.0. Still a draft.

Problem

moq-transport-iroh returned no send groups, so moq-net ranked every group stream of a session in one queue, where the older of two equal-priority subscriptions goes first. On a capped link a pinned rendition switch never landed: the replacement's first group, its keyframe, waited behind the incumbent's backlog, which never drained. a_switch_lands_while_the_link_stays_capped was ignored for this reason.

Approach

Transport::send_group now returns a SendGroup. moq-net opens one per subscription, and expects a higher group to preempt lower ones, equal groups to share the bytes, streams inside a group to go in their own order, and ungrouped (control) streams to go first. moq-quic does this with deficit round robin. noq has one level, an i32 priority per stream, so the two levels are packed into it:

Stream Priority
ungrouped, priority p 2^29 + p
group priority g, tier t 16 * g + (15 - t)

The tier is the stream's dense rank by order within its group, capped at 15. The heads of equal-priority groups therefore share one priority, and noq sends streams of one priority round robin while send fairness is on, which is its default. So equal groups split the bytes, a group's older streams wait for its head, and a higher group outranks every tier of a lower one. Joining, leaving or reordering a stream reranks its group through a shared handle to each member's noq stream.

This differs from moq-quic in one way: fairness is per stream and only within a tier, so a group whose head is idle does not pass its share to its backlog. For live media that drops the backlog first, which the newest-first order wants anyway. Datagrams ignore their group, since noq queues them apart from streams.

The sharing relies on send fairness. An endpoint that sets send_fairness(false) in its QuicTransportConfig would get streams of one priority in write order, and the older group would go first again. RFC 9218's per-stream incremental flag removes that dependency. It is in n0-computer/noq#859, and #97 sets it on top of this PR.

Evidence

  • a_switch_lands_while_the_link_stays_capped, un-ignored, on stock noq 1.4: 7 of 7 runs pass (6 on their own plus one in the full suite, 6 to 11 s each). Before this change, with send_group returning None, 0 of 6 tries passed, and each timed out after 60 s still on high.
  • New tests in moq-transport-iroh cover the priority mapping and reranking (groups_rank_their_streams_in_tiers), plus a data test whose flow-control windows exceed the payload. In equal_priority_groups_progress_together, two equal-priority groups whose streams have orders 1000 and 0 interleave on stock noq: it passed 6 of 6 runs. The control test ungrouped_streams_drain_in_order sends the same streams ungrouped and confirms that they drain one after the other.
  • cargo make check-all (clippy -D warnings and the configured fmt check included), cargo fmt --check, cargo nextest run --workspace --all-features (656 passed), doctests, the full patchbay suite with --run-ignored all (8 of 8, under the measure lock) and scripts/check-links.py all pass.

Follow-ups

Rebased onto #94 at aa6de124 (the moq bump to e8075629a, which adds Offset to the send-stream trait, and the layout and endpoint moves). After the rebase: cargo make check-all and the 21 tests of moq-transport-iroh pass, and a_switch_lands_while_the_link_stays_capped passes 3 of 3 runs (7 to 10 s each).

🤖 Generated with Claude Code

@Frando
Frando force-pushed the Frando/send-groups branch from 007be94 to 59369d6 Compare November 14, 2026 08:19
@Frando Frando changed the title feat(transport): schedule moq send groups as incremental QUIC streams feat(transport): schedule moq send groups by QUIC stream priority Nov 14, 2026
moq-transport-iroh returned no send groups, so moq-net ranked every
group stream of a session in one queue, where the older of two
equal-priority subscriptions goes first. Under a held bandwidth cap a
rendition switch never landed: the replacement's first group waited
behind the incumbent's backlog, which never drained.

`Transport::send_group` now returns a `SendGroup`. iroh schedules a
stream by an i32 priority, so the group priority and each stream's
dense rank by order within its group are packed into it
(group * 16 + 15 - tier), with ungrouped streams at 2^29 and up, above
every group. The heads of equal-priority groups share one priority, and
noq sends streams of one priority round robin while send fairness is on,
its default, so they share the bytes. A group's older streams wait for
its head, and a higher group outranks every tier of a lower one. A
stream joining, leaving or moving reranks its group, which reaches the
other streams through a shared handle.

Unlike moq-quic's deficit round robin, fairness is per stream and only
within a tier: a group whose head is idle does not hand its share to its
backlog. With send fairness turned off the older group goes first
again; RFC 9218's incremental flag, which n0-computer/noq#859 adds,
would remove that dependency.

`a_switch_lands_while_the_link_stays_capped` is no longer ignored.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Frando
Frando force-pushed the Frando/send-groups branch from 59369d6 to cf14b6d Compare November 16, 2026 11:12
@Frando

Frando commented Nov 16, 2026

Copy link
Copy Markdown
Member Author

Folded into #94 as 4c505b9, with the review fixes: docs on how priority raises behave under noq 1.4, per-stream fairness stated plainly, a trace in the re-rank, and an early return in set_order. #97 now sits directly on #94.

@Frando Frando closed this Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant