diff --git a/quest/m1/subscribe-ranges/README.md b/quest/m1/subscribe-ranges/README.md index 9836d735bd6..6cb9c8ebe87 100644 --- a/quest/m1/subscribe-ranges/README.md +++ b/quest/m1/subscribe-ranges/README.md @@ -17,7 +17,9 @@ relay bounds a sparse FETCH only if the model can request ranges: - **Wire (lite-07, unpublished).** SUBSCRIBE carries a list of group ranges (an open end means live; ends may be relative, below) in place of Group Start/End, plus - `order: asc | desc` (desc, newest first, is today's rule and the default). + `order: asc | desc` (desc, newest first, is the default). Order landed in + #5385; over moq-transport the upstream order is fixed at SUBSCRIBE, since no + draft lets an update change it. Subscriber Max Age (the model's `max_delay`) stays as a cap alongside the ranges, since a group's timestamp isn't always known. Decided 2026-10-10: historical requests also obey that cap and publisher max-age. An omitted @@ -74,6 +76,8 @@ every sequence delivered or dropped. - [Model ranges](/quest/m1/subscribe-ranges/model.md) - `Subscription` carries ranges, and `Dynamic` fills misses by range - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - publishers name every group they won't deliver - [Lite-07 ranges](/quest/m1/subscribe-ranges/lite.md) - the lite-07 wire, Rust publisher and subscriber, and the draft +- [moq-transport FETCH and fill streams in the session queue](/quest/m1/subscribe-ranges/ietf-fetch-queue.md) - Rust FETCH and fill streams ranked against group streams; JS already ranks its fill and serves no FETCH +- [moq-transport upstream updates](/quest/m1/subscribe-ranges/ietf-update.md) - the upstream request follows the aggregate priority; its order stays fixed, as every draft requires - [moq-transport ranges](/quest/m1/subscribe-ranges/ietf.md) - range FETCH upstream per missing run, and non-blocking FETCH served downstream - [JS ranges](/quest/m1/subscribe-ranges/js.md) - `@moq/net` model and lite-07 parity diff --git a/quest/m1/subscribe-ranges/ietf-fetch-queue.md b/quest/m1/subscribe-ranges/ietf-fetch-queue.md new file mode 100644 index 00000000000..6c467747334 --- /dev/null +++ b/quest/m1/subscribe-ranges/ietf-fetch-queue.md @@ -0,0 +1,57 @@ +# [S] moq-transport FETCH and fill streams in the session queue + +## Goal + +Under congestion, a moq-transport FETCH or fill stream competes with the +session's group streams through the same priority queue: a fill as the group +it fills, a standalone FETCH by its subscriber priority. Today the Rust +moq-transport publisher gives these streams the raw subscriber priority as +their send order, mixing an absolute priority with the queue's relative ranks +(send order `255 - rank`), so how they compare with group streams is +arbitrary. + +## Plan + +Where it stands after #5385 (`rs/moq-net/src/ietf/publisher.rs`): + +- Group streams take a `Rank` from the session `PriorityQueue` through + `TrackServe::rank(sequence)`, keyed by the subscription's request id and + ordered by its `Order`. +- `run_fill` calls `stream.set_priority(priority)` with the raw subscriber + priority, and so does the FETCH stream in `run_fetch_stream`. + +The work: + +- A draft-20 fill joins its subscription's ranking as the group it fills, + the way JS already ranks it (`js/net/src/ietf/publisher.ts`, `#runFill`). + A joining FETCH, used before draft-20, ranks the same way within the + subscription it joins. +- A standalone FETCH gets its own queue entry, keyed by its own request id. + `Priority::cmp` compares that id before order or group, so the FETCH ranks + against group streams by subscriber priority alone, with the id breaking + ties. Its group and GROUP_ORDER do not affect the rank. It follows + priority changes the way a group stream's `Rank` does. +- JS parity (decided 2026-10-13 in #5400). JS already ranks its fill through + the subscription's `Priority`. It serves no standalone FETCH: `runFetch` + (`js/net/src/ietf/publisher.ts`) refuses every one. So JS has nothing to + change now, and any FETCH serving it gains later ranks through the same + `Priority`. +- Keep each stream ranked until it settles, not just until its FIN is + written (the #5385 review fix for JS group streams). +- Tests, on mock time, in Rust: a fill and a FETCH stream ranked against open + group streams of the same and a different priority, asserting + the recorded send orders the way `group_stream_preserves_model_priority` + does. + +This is unblocked and lands before [moq-transport ranges](/quest/m1/subscribe-ranges/ietf.md), +which makes a FETCH span several groups on one stream that keeps this one +entry. + +Out of scope: lite FETCH. lite-07 removes it, and published lite versions +answer FETCH through the range model that [Model ranges](/quest/m1/subscribe-ranges/model.md) +builds. + +## Related + +- [Scope and sign track priority](/quest/m1/track-priority-scope.md) - changes what the queue compares across subscriptions +- [FETCH max-delay](/quest/m1/fetch-max-delay.md) - the same FETCH serving path diff --git a/quest/m1/subscribe-ranges/ietf-update.md b/quest/m1/subscribe-ranges/ietf-update.md new file mode 100644 index 00000000000..53b8f39db94 --- /dev/null +++ b/quest/m1/subscribe-ranges/ietf-update.md @@ -0,0 +1,67 @@ +# [S] moq-transport upstream updates + +## Goal + +A relay's moq-transport upstream subscription follows its downstream +subscribers: when their aggregate subscriber priority changes, the relay sends +SUBSCRIBE_UPDATE (drafts 14 and 15) or REQUEST_UPDATE (draft-16 on) with the +new priority, as lite-07 already does. Today the IETF subscriber reads the +aggregate once, at SUBSCRIBE (`rs/moq-net/src/ietf/subscriber.rs`, +`js/net/src/ietf/subscriber.ts`), and never updates the request. + +Group order is not part of this. The upstream order stays whatever SUBSCRIBE +asked for (decided 2026-10-13 in #5400: updates carry priority only, with no +re-subscribe and no forced Descending upstream). + +## Plan + +Researched 2026-10-13 against the published drafts 14 to 22: no moq-transport +draft lets a subscriber change a subscription's group order. + +- Every draft says the group order of an existing subscription cannot be + changed (§7.1 in 14 to 20, §5.1.1 in 21 and 22). +- Draft-14's SUBSCRIBE_UPDATE has no Group Order field. From draft-15 on, + GROUP_ORDER's list of allowed messages leaves out the update message, and + draft-22 spells out per request type what a REQUEST_UPDATE may carry. +- Sending it anyway is ignored on 14 and 15, ambiguous on 16, and a + PROTOCOL_VIOLATION from draft-17 on. Draft-20 to 22 allow GROUP_ORDER inside + FILL_PARAMETERS, but that orders a new fill, not the subscription. +- The only way to change the order is to UNSUBSCRIBE and SUBSCRIBE again with + a fill or FETCH for the gap. That is not planned: it costs a round trip and + a gap to change a transmission preference on one leg, and the relay already + serves each downstream subscriber in its own order. + +What an update can carry, and this quest sends: + +- Subscriber priority, on every draft: a fixed field on draft-14, the + SUBSCRIBER_PRIORITY parameter after. +- Draft-14's SUBSCRIBE_UPDATE also requires Start Location and End Group, so a + priority update repeats the subscription's current bounds rather than + zeroes, which a conforming peer would read as narrowing to group 0. +- From draft-15 on, a priority update omits the subscription filter. Today + `SubscribeUpdate::encode_msg` (`rs/moq-net/src/ietf/subscribe.rs`) always + writes `Filter::NextObject`, which would reset the filter. +- Forward stays 1. Pausing is not part of this. +- The subscription filter is updatable from draft-15 on. Narrowing upstream + ranges belongs to [moq-transport ranges](/quest/m1/subscribe-ranges/ietf.md), + which can reuse this update path. + +Implementation: the IETF subscriber watches the aggregate the way +`lite/subscriber.rs` does (`buffer_update`), sending one update per change +and coalescing changes while one is in flight. The publisher side already +applies a priority update to open group streams +(`subscription_update_reprioritizes_open_group_streams`). The JS publisher on +drafts 14 to 16 still reads and discards updates, which +[the legacy updates quest](/quest/m1/ietf-legacy-updates.md) fixes first. +Test on mock time, +in Rust and JS, directly and through a relay: a second downstream subscriber +at a higher priority raises the upstream priority, and leaving lowers it again. + +## Required + +- [Apply draft 14-16 request updates](/quest/m1/ietf-legacy-updates.md) - the JS publisher applies the priority this sends + +## Related + +- [Scope and sign track priority](/quest/m1/track-priority-scope.md) - may stop forwarding downstream priority upstream on relay-to-relay links, which changes what this sends +- [moq-transport FETCH and fill streams in the session queue](/quest/m1/subscribe-ranges/ietf-fetch-queue.md) - the same publisher queue the updated priority lands in diff --git a/quest/m1/subscribe-ranges/model.md b/quest/m1/subscribe-ranges/model.md index 1f8684994ba..032bb1fa5ec 100644 --- a/quest/m1/subscribe-ranges/model.md +++ b/quest/m1/subscribe-ranges/model.md @@ -36,6 +36,19 @@ Guidance: (`fetch_group`, `requested_group`), moq-c (`poll_requested_group`), every binding wrapper and its `doc/lib` page, and `moq fetch` through `moq_relay::fetch_group` (added in the 2026-10-05 audit). +- Decided 2026-10-13 (#5400): the same reshape of `MoqSubscription` in moq-ffi + (`rs/moq-ffi/src/consumer.rs`) adds a `MoqOrder` enum (`Ascending`, + `Descending`) and `MoqSubscription.order`, defaulting to `Descending` and + mapped to `track::Subscription::order`, beside the ranges. It follows the + cross-package table like the rest: the `py/moq-rs`, `swift`, `kt`, + `dart/moq` and `go/wrapper/moq` wrappers, `cpp/moq`, C (inherited if the + [generated C bindings](/quest/m1/c/README.md) have landed, otherwise + `rs/moq-c/src/api.rs`, from which cbindgen generates `moq.h`), and their + `doc/lib` pages. `cpp/obs/src` and `doc/bin/obs.md` have no subscription + surface today, so they change only if OBS starts building a + `MoqSubscription`. Folded in here rather than a separate + quest, so the bindings break once. Test that an ascending subscription + receives a cached backlog oldest first in moq-ffi and each wrapper with tests. - Decided in the 2026-10-10 audit: `max_delay` caps every range, including historical FETCH replacements, and publisher `max_age` always clamps it. A FETCH with no reader delay uses publisher max-age alone, not the live diff --git a/quest/m1/track-priority-scope.md b/quest/m1/track-priority-scope.md index 1004111da75..d3acb72015f 100644 --- a/quest/m1/track-priority-scope.md +++ b/quest/m1/track-priority-scope.md @@ -18,17 +18,18 @@ that 127 is the middle of a `u8`. The wire stays a byte. Where the model stands today, all in `rs/moq-net`: -- One `PriorityQueue` per moq-lite session (`lite/publisher.rs`), a strict - global sort over every in-flight group on the connection: a subscription at +- One `PriorityQueue` per session, shared by the moq-lite and moq-transport + publishers, a strict global sort over every in-flight group on the + connection: a subscription at priority 200 pre-empts one at 100 indefinitely, and only the top 255 groups get a distinct rank. - `Priority` already ranks a group by its track priority, then its subscription - id, then newest group first within that subscription (`lite/priority.rs`). JS + id, then group within that subscription in its order (`priority.rs`). JS packs track priority and the group's position within its own subscription - into one send order (`js/net/src/lite/priority.ts`), so two tracks at equal + into one send order (`js/net/src/priority.ts`), so two tracks at equal priority interleave rather than one draining first. -- Group order within a track is fixed newest first today; a subscription-chosen - order arrives with [Subscribe ranges](/quest/m1/subscribe-ranges/README.md). +- Group order within a track follows each subscription's `order` (#5385), + newest first by default. - A relay forwards the max of its downstream subscriber priorities upstream (`model/subscription.rs`, `lite/subscriber.rs`), never the publisher's track priority, so one viewer asking for 255 raises that track above every other @@ -65,10 +66,10 @@ Direction to settle in the draft first, then the code: bypasses tenant isolation; settle their carrier beside the subscription one, or narrow the goal to subscription delivery. - Rank by track priority, then subscription, then the subscription's own group - order (newest first until subscribe ranges adds a direction). + order (`Subscription::order`, newest first by default). - Decide whether the publisher's `track::Info::priority` breaks a tie between equal subscriber priorities in `Priority::cmp` - (`rs/moq-net/src/lite/priority.rs`). The + (`rs/moq-net/src/priority.rs`). The [ladder controller](/quest/m3/ladder/controller.md), now in m3, wants that tiebreak; this quest owns the answer and the code change, so the controller only consumes it (2026-10-06 audit). Either way, make the docs agree: diff --git a/quest/m3/ladder/README.md b/quest/m3/ladder/README.md index e05a80ab841..74890fe81bd 100644 --- a/quest/m3/ladder/README.md +++ b/quest/m3/ladder/README.md @@ -35,7 +35,7 @@ estimate by `track::Info::priority`, filling a tier before the next sees a bit and splitting max-min fair within one. A controller that assigns descending priorities down the ladder gets correct allocation from that alone. Send order is a different number today: `Priority::cmp` -(`rs/moq-net/src/lite/priority.rs`) ranks first by `Priority.track`, which is +(`rs/moq-net/src/priority.rs`) ranks first by `Priority.track`, which is the subscriber's priority from SUBSCRIBE (`msg.priority` in `rs/moq-net/src/lite/publisher.rs`), not the publisher's `Info::priority`. [Scope track priority](/quest/m1/track-priority-scope.md) owns making the