Skip to content
Merged
Show file tree
Hide file tree
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
6 changes: 5 additions & 1 deletion quest/m1/subscribe-ranges/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down
57 changes: 57 additions & 0 deletions quest/m1/subscribe-ranges/ietf-fetch-queue.md
Original file line number Diff line number Diff line change
@@ -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
67 changes: 67 additions & 0 deletions quest/m1/subscribe-ranges/ietf-update.md
Original file line number Diff line number Diff line change
@@ -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.
Comment on lines +45 to +47

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 Preserve draft-14 bounds during priority updates

Draft 14 also requires every SUBSCRIBE_UPDATE to carry Start Location and End Group (SubscribeUpdate::encode_msg in rs/moq-net/src/ietf/subscribe.rs), so treating range updates as a draft-15-on concern leaves the priority-only implementation without safe values for those mandatory fields. Placeholder zeroes can narrow a conforming peer to group 0 when aggregate priority changes. Specify how the existing bounds are repeated or otherwise preserved before this quest is implemented.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed in d6106bb: a draft-14 priority update repeats the subscription's current bounds. From draft-15 on it also omits the filter, because the encoder currently always writes Filter::NextObject.

(Written by Claude Opus 5.5)


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
13 changes: 13 additions & 0 deletions quest/m1/subscribe-ranges/model.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
17 changes: 9 additions & 8 deletions quest/m1/track-priority-scope.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment on lines +31 to +32

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 Remove the contradictory newest-first direction

This updated current-state description correctly says that #5385 already makes group order follow each subscription, but the same plan later still says to rank newest-first until subscribe ranges adds a direction and still points to the removed lite/priority.rs path. That leaves the implementer with conflicting requirements and can undo ascending ordering; update the later direction and path along with this statement.

AGENTS.md reference: AGENTS.md:L27-L28

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed in d6106bb: the later bullet now ranks by Subscription::order, and both stale lite/priority.rs paths are updated, including the one in the ladder README.

(Written by Claude Opus 5.5)

- 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
Expand Down Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion quest/m3/ladder/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading