diff --git a/doc/concept/standard.md b/doc/concept/standard.md index 8699269a2bb..fd04a054dd3 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -28,7 +28,7 @@ subset drops. What a peer actually observes against this implementation: - **Pull.** Subscribers ask. Single-track `PUBLISH` offers are declined, unless they answer our `SUBSCRIBE_TRACKS` (below); announce a namespace and serve the resulting subscriptions. Announcements go out unsolicited, and we also ask for every prefix we may discover. The solicit `SETUP` option makes us wait to be asked. Without it, a draft 16+ peer also gets each match as a `NAMESPACE` on its `SUBSCRIBE_NAMESPACE` stream, so it hears the namespace twice. We send `PUBLISH` only to answer a `SUBSCRIBE_TRACKS` (below): on drafts 16 and 17 a `SUBSCRIBE_NAMESPACE` asking only for `PUBLISH` is refused, one asking for both gets only `NAMESPACE`, and any other Subscribe Options value closes the session. - **`SUBSCRIBE_TRACKS` lists, it never pushes.** On draft 18 and later, it lists every track of every broadcast under its prefix, later ones included. With `FORWARD=0`, each track gets a paused `PUBLISH` carrying its Track Properties, and an error `PUBLISH_DONE` once the track is no longer listed, never `TRACK_ENDED`, since the track may go on elsewhere. A `REQUEST_UPDATE` with `FORWARD=1` resumes one, served from the cache like a `SUBSCRIBE` with the update's filter and answered with `LARGEST_OBJECT`; `FORWARD=0` pauses it again. Each paused `PUBLISH` holds a subscription slot, and past the cap a track gets `PUBLISH_SKIPPED` (`PUBLISH_BLOCKED` on draft 18) instead. A listing that omits `FORWARD` or sets it to 1 asks for every track's objects: from draft 19 each track gets `PUBLISH_SKIPPED`, and the subscriber `SUBSCRIBE`s to what it wants; draft 18 has no such skip, so the request is refused with `NOT_SUPPORTED`. A prefix overlapping another listing gets `PREFIX_OVERLAP`, a `TRACK_PROPERTY_FILTER` gets `NOT_SUPPORTED`, and a `REQUEST_UPDATE` on the listing itself ends it. On draft 18, a `SUBSCRIBE` to a track we `PUBLISH`ed gets `DUPLICATE_SUBSCRIPTION`. Cancelling the listing stops new `PUBLISH`es, while those sent live on. A broadcast is listed only while our publish grant covers it, from scratch once it does. Rust sends it upstream for a listing (below); JavaScript does not. - **A Rust TRACKS listing sends `SUBSCRIBE_TRACKS` upstream, only on demand.** Listing a broadcast from a moq-transport peer on draft 18 and later sends `SUBSCRIBE_TRACKS` with `FORWARD=0` while someone lists it, never on connect, announce, or subscribe, so a peer that refuses, resets, or ignores it affects only that listing. Before draft 18 the listing is refused as unsupported. Each listed track's paused `PUBLISH` is its upstream copy, which a reader resumes rather than subscribing again. Only a `PUBLISH_DONE` with `TRACK_ENDED` removes a listed track; any other end, including the error our own answerer sends for an unlisted track, fails the listing, and readers list again. -- **History is one group.** In Rust, Object ID gaps must be marked by Prior Object ID Gap properties for a group to be fetchable. A `FETCH` returns one group from the cache, or on drafts 14 through 19 the saved prefix of the group a new subscription just joined. A range of groups is refused, as is a draft 20+ `LOCATION_FILTER` that ends at Largest Object rather than an absolute End Location. On draft 20 and later, `FETCH_OK`'s End Location is the requested end, capped at Largest Object: a range holding no objects gets an empty fetch stream, and only a start past Largest Object is refused, with `INVALID_RANGE`. A relay's copy with no upstream subscription can't know Largest Object short of the track's end, so it echoes the requested end instead. JavaScript publishing refuses every `FETCH`. Datagrams are never fetchable. A Rust reader that only fetches learns the track from `TRACK_STATUS` instead of subscribing, so a finished track stays fetchable; draft 17 still subscribes, since its `TRACK_STATUS` answer cannot say whether the track is timed, and so does a reader whose publisher refuses `TRACK_STATUS` as `NOT_SUPPORTED`. +- **History is one group.** In Rust, Object ID gaps must be marked by Prior Object ID Gap properties for a group to be fetchable. A `FETCH` returns one group from the cache, or on drafts 14 through 19 the saved prefix of the group a new subscription just joined. A range of groups is refused, as is a draft 20+ `LOCATION_FILTER` that ends at Largest Object rather than an absolute End Location. On drafts 14 through 19, `FETCH_OK` End Object 0 covers the entire End Group, matching the request; Rust also accepts the legacy answer naming the next group with Object 0. On draft 20 and later, `FETCH_OK`'s End Location is the requested end, capped at Largest Object: a range holding no objects gets an empty fetch stream, and only a start past Largest Object is refused, with `INVALID_RANGE`. A relay's copy with no upstream subscription can't know Largest Object short of the track's end, so it echoes the requested end instead. JavaScript publishing refuses every `FETCH`. Datagrams are never fetchable. A Rust reader that only fetches learns the track from `TRACK_STATUS` instead of subscribing, so a finished track stays fetchable; draft 17 still subscribes, since its `TRACK_STATUS` answer cannot say whether the track is timed, and so does a reader whose publisher refuses `TRACK_STATUS` as `NOT_SUPPORTED`. - **Compression.** Rust peers on draft 17 and later exchange compressed tracks when both offer the [Flate extension](/draft/moq-flate). Older peers receive one shared inflated copy. A publisher that seals the compression declaration makes that fallback unavailable: an incompatible peer is refused, preserving the sealed metadata. JavaScript does not offer the IETF extension. - **Timing.** A track whose `SUBSCRIBE_OK` declares no `TIMESCALE` is untimed, as is every track on drafts 14 through 16. A Rust reader that never subscribed takes the units from `TRACK_STATUS` on draft 18 and later. - **Strict SETUP and parameters.** Repeated unknown `SETUP` options, GREASE included, are accepted if well-formed; a repeated known option is rejected. On draft 17 and later, a `GROUP_ORDER` other than Ascending (1) or Descending (2) closes the session. Message parameters follow the negotiated draft's lists: drafts 14 and 15 ignore an unknown or misplaced parameter, draft 16 ignores one defined only for another message but closes the session on an unknown one, and draft 17 and later close it on both. Other malformed control input closes the session with the draft's code too, such as a server `SETUP` carrying `PATH` or `AUTHORITY`, a request cut short by FIN, or a second `GOAWAY` on one stream; a first `GOAWAY` on a request stream is legal. diff --git a/quest/m1/README.md b/quest/m1/README.md index 8097ac7fddb..bc891a2bf44 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -105,7 +105,6 @@ tracks, so per-group stats stop costing cluster announces. - [More tests under load](/quest/m1/test-flakes-2/README.md) - the second round of load-only failures, one quest per flake, fixed at the cause - [A public model](/quest/m1/public-model/README.md) - every model item a built-in session reaches is public, unnecessary, or marked deliberately private, so a custom publisher, subscriber, or relay builds from the public model alone - [A smaller, safer API than release](/quest/m1/api-audit/README.md) - every surface added since release has a consumer or is gone, overlapping operations are collapsed, names mirror across Rust, JS, and the bindings, and every break has its MIGRATE entry -- [FETCH_OK whole group](/quest/m1/ietf-fetch-end-location.md) - on drafts 14 to 19, FETCH_OK End Object 0 means the whole group in both directions, and a FETCH ending at the maximum group is refused as unsupported - [JavaScript FETCH](/quest/m1/js-fetch.md) - browser publishers answer IETF FETCH through the JS ranges request surface - [IETF fill timeout](/quest/m1/ietf-fill-timeout.md) - native FILL_TIMEOUT bounds upstream waiting on drafts 18-22, alongside local content-age enforcement - [Rust identity enforcement](/quest/m1/catalog-identity-rs.md) - `moq-mux` refuses a redefined rendition, and every Rust publisher mints a new rendition name for a decoder identity change and updates everything else in place diff --git a/quest/m1/ietf-fetch-end-location.md b/quest/m1/ietf-fetch-end-location.md deleted file mode 100644 index 48dcd05265a..00000000000 --- a/quest/m1/ietf-fetch-end-location.md +++ /dev/null @@ -1,45 +0,0 @@ -# [S] FETCH_OK End Object 0 is the whole group - -## Goal - -On moq-transport drafts 14 to 19, moq-net reads and writes a FETCH_OK End -Location `{g, 0}` as all of group g, the same way it already writes the FETCH -request. A peer answering our whole-group FETCH with `{g, 0}` is served, not -refused, and a peer reading our answer no longer concludes that group g+1 does -not exist. A FETCH ending at `{2^64-1, 0}` gets the NOT_SUPPORTED that other -multi-group ranges get, on draft 17 and later, the drafts whose encoding can -carry it (14 to 16 cap a varint at `2^62-1`). - -## Plan - -Decided 2026-10-21 (maintainer): fix all three sides in one PR, on behavior -rather than on draft text. The request side already spells the whole group -`{g, 0}`, while FETCH_OK is written and read as exclusive `{g+1, 0}`, so one -message has two readings depending on direction. IETF pairings between our own -released and current builds are out of scope, so no staged rollout. - -- Subscriber (`rs/moq-net/src/ietf/subscriber.rs`, FETCH_OK handling): before - draft 20, End Object 0 means the whole End Group, so `{g, 0}` covers g and - End Of Track sets the final sequence to g+1. Keep accepting `{g+1, 0}`, - which moxygen's relay cache and moqtest send, as covering g. -- Publisher (`rs/moq-net/src/ietf/publisher.rs`, standalone FETCH range): - keep the request's wire form instead of widening `{g, 0}` to `{g+1, 0}`. - That removes the `checked_add(1)` overflow (which also reaches draft 20+ - through the Absolute filter rewrite) and the `end.group - 1` step. -- Publisher FETCH_OK: echo `{g, 0}` for a covered whole group. - -Tests: replace the `{g+1, 0}` pins (`a_standalone_fetch_serves_one_whole_group`, -the `end_location()` helper, and the subscriber's group-fetch and abandon -fixtures) with the whole-group reading, and add a subscriber case for a -`{g+1, 0}` answer and a publisher case for `{u64::MAX, 0}`. Run -`just test interop --all`; moxygen must still interoperate. - -Document the pre-draft-20 FETCH_OK meaning next to the draft-20 line in -`doc/concept/standard.md`. - -Public API: none. Wire: drafts 14 to 19 FETCH_OK End Location changes from -`{g+1, 0}` to `{g, 0}` for a whole group. - -## Closes - -- [#6199](https://github.com/moq-dev/moq/issues/6199) - FETCH_OK End Location Object 0 means the whole group diff --git a/quest/m1/js-fetch.md b/quest/m1/js-fetch.md index e9550f1e416..cd5c5024d02 100644 --- a/quest/m1/js-fetch.md +++ b/quest/m1/js-fetch.md @@ -40,7 +40,6 @@ claims that change. ## Required - [JS ranges](/quest/m1/subscribe-ranges/js.md) - the on-demand request surface this dispatches onto -- [FETCH_OK whole group](/quest/m1/ietf-fetch-end-location.md) - the Rust FETCH_OK contract this copies reads End Object 0 as the whole group first ## Related diff --git a/rs/moq-net/MIGRATE.md b/rs/moq-net/MIGRATE.md index 11aa62bf313..2a77bfb9f78 100644 --- a/rs/moq-net/MIGRATE.md +++ b/rs/moq-net/MIGRATE.md @@ -4,6 +4,13 @@ How to update your code for each breaking change, newest first. ## Unreleased +### IETF whole-group FETCH answers name the requested group ([#6199](https://github.com/moq-dev/moq/issues/6199)) + +On moq-transport drafts 14 through 19, a whole-group `FETCH_OK` now names `{g, 0}` instead of `{g+1, 0}`. +Readers accept both forms and set End Of Track to the sequence after the fetched group. +An older moq-net reader can reject the new answer; upgrade it before pairing it with a new publisher, or use draft 20 and later, whose inclusive End Location is unchanged. +No Rust API changes. + ### Receive streams are read through leases (#5878) `transport::poll::RecvStream` now has `poll_lease(cx, want)`, `set_priority`, and `stop`, plus the provided `poll_read_chunk` and `read_chunk`. diff --git a/rs/moq-net/src/ietf/fetch.rs b/rs/moq-net/src/ietf/fetch.rs index 5174df19208..ddb23871a94 100644 --- a/rs/moq-net/src/ietf/fetch.rs +++ b/rs/moq-net/src/ietf/fetch.rs @@ -328,6 +328,8 @@ pub struct FetchOk { pub request_id: Option, pub group_order: GroupOrder, pub end_of_track: bool, + /// Drafts 14-19 use the last object plus one, or Object 0 for the whole End Group; + /// draft 20 and later use an inclusive End Location. pub end_location: Location, /// The track's properties, as SUBSCRIBE_OK carries them: MAX_CACHE_DURATION from the /// draft-14/15 parameters, the Track Properties block from draft-16 on. diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 61a96af3a0d..4e37dc9ecf7 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -2422,16 +2422,14 @@ where .await; } - // An End Object of 0 asks for the whole End Group. - let end = match end.object { - 0 => end.group.checked_add(1).map(|group| Location { group, object: 0 }), - _ => Some(end), - }; - let Some(end) = end.filter(|end| (start.group, start.object) < (end.group, end.object)) else { + // End Object 0 includes the entire End Group, even at the largest Group ID. + if start.group > end.group + || (start.group == end.group && end.object != 0 && start.object >= end.object) + { return self .reject_fetch(stream, msg.request_id, &Error::InvalidRange, "empty range") .await; - }; + } // The peer must have seen the announcement to name this namespace, so this // resolves like a SUBSCRIBE does. @@ -2518,11 +2516,7 @@ where // One group per FETCH: on a relay, a range costs a serial upstream fetch per missing // group, all buffered until FETCH_OK. Ranges wait for upstream fills by range. - let last = match end.object { - 0 => end.group - 1, - _ => end.group, - }; - if start.group != last { + if start.group != end.group { return self .reject_fetch( stream, @@ -2651,9 +2645,9 @@ where } (end, false) } else { - // A group that ends the track ends the response at its last object; otherwise - // the response ends where it was asked to. - match end_of_track { + // Cap a bounded response at the track's last object. A whole-group response + // keeps Object 0 rather than claiming that the next group is covered. + match end_of_track && end.object > 0 { true => ( Location { group: group.sequence, @@ -2661,7 +2655,7 @@ where }, true, ), - false => (end, false), + false => (end, end_of_track), } }; // Draft-20's End Location is inclusive: the requested end, capped at Largest Object @@ -9822,8 +9816,8 @@ mod serve_tests { Version::Draft22, ]; - /// FETCH_OK's End Location for a response whose last object is `last`: one past it - /// before draft 20, and the object itself from then on. + /// A bounded FETCH_OK's End Location: one past `last` before draft 20, + /// and the object itself from then on. Whole-group answers use Object 0 before draft 20. fn end_location(version: Version, group: u64, last: u64) -> Location { let object = match Filter::is_draft20(version) { true => last, @@ -10024,7 +10018,7 @@ mod serve_tests { let (ok, objects) = fetch_answer(buf, version); let end = match Filter::is_draft20(version) { true => Location { group: 2, object: 1 }, - false => Location { group: 3, object: 0 }, + false => Location { group: 2, object: 0 }, }; assert_eq!(ok.end_location, end, "{version}"); assert!(!ok.end_of_track, "{version}"); @@ -10566,7 +10560,11 @@ mod serve_tests { ) .await; let (ok, objects) = fetch_answer(buf, version); - assert_eq!(ok.end_location, end_location(version, 4, 1), "{version}"); + let end = match Filter::is_draft20(version) { + true => end_location(version, 4, 1), + false => Location { group: 4, object: 0 }, + }; + assert_eq!(ok.end_location, end, "{version}"); assert!(ok.end_of_track, "{version}"); assert_eq!(objects, pairs([4])[1..].to_vec(), "{version}"); } @@ -10649,6 +10647,38 @@ mod serve_tests { } } + /// A whole End Group at the wire's limit is valid: a multi-group range is unsupported, + /// and a missing single group is not found. Drafts 14-16 cannot encode u64::MAX. + #[moq_clock::test] + async fn a_standalone_fetch_through_the_maximum_group_is_unsupported() { + for version in FETCH_DRAFTS { + let maximum = match version { + Version::Draft14 | Version::Draft15 | Version::Draft16 => (1 << 62) - 1, + _ => u64::MAX, + }; + let mut h = serve(version); + publish_pairs(&mut h, 1, None); + h.track.finish().unwrap(); + settle().await; + for (start, code) in [(0, 0x3), (maximum, does_not_exist(version))] { + let buf = standalone_fetch( + &h, + Location { + group: start, + object: 0, + }, + Location { + group: maximum, + object: 0, + }, + GroupOrder::Ascending, + ) + .await; + assert_eq!(fetch_refusal(buf, version), code, "{version}: start {start}"); + } + } + } + /// Read a REQUEST_ERROR (or draft-14 FETCH_ERROR) off a refused FETCH, as its code. fn fetch_refusal(wire: bytes::Bytes, version: Version) -> u64 { let mut buf = Decoder::new(&wire, version.into()); diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 0c0ba532556..8eb9a27b13f 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -5306,7 +5306,7 @@ where } }; - // Draft-20's End Location is inclusive, so step one past it as older drafts spell it. + // Draft-20's End Location is inclusive; older drafts spell a bounded object one past it. let mut end = ok.end_location; if draft20 { let Some(object) = end.object.checked_add(1) else { @@ -5317,6 +5317,10 @@ where end.object = object; } + // Before draft-20, Object 0 covers the whole named group. Legacy answers one + // group past it still pass the exclusive comparison below. + let whole_group = !draft20 && end.group == sequence && end.object == 0; + // Draft-20's answer must cover its start within the requested group. Validate before // accepting the group or letting End of Track mark where the track ends. if draft20 && (end.group != sequence || end.object <= start) { @@ -5336,7 +5340,7 @@ where // The publisher knows where the track ends, which a range FETCH downstream needs. if ok.end_of_track { - let Some(final_sequence) = end.group.checked_add(u64::from(end.object > 0)) else { + let Some(final_sequence) = end.group.checked_add(u64::from(whole_group || end.object > 0)) else { request.reject(Error::ProtocolViolation); let _ = stream.writer.close().await; return; @@ -5345,14 +5349,14 @@ where } // Before draft-20, an empty answer opens no fetch stream at all. - if (end.group, end.object) <= (sequence, start) { + if !whole_group && (end.group, end.object) <= (sequence, start) { request.reject(Error::NotFound); let _ = stream.writer.close().await; return; } // An exclusive End Location inside the group bounds the stream; before draft-20 the - // stream also owes every object up to it. One past the group covers it whole. - let end = (end.group == sequence).then_some(end.object); + // stream also owes every object up to it. A whole-group answer has no object bound. + let end = (end.group == sequence && !whole_group).then_some(end.object); // Joined fetches still count until they pick the accepted group up from the cache. let joined = request.result.clone(); @@ -16021,7 +16025,7 @@ mod joining_fetch_tests { group_order: GroupOrder::Ascending, end_of_track: false, end_location: ietf::Location { - group: GROUP + 1, + group: GROUP, object: 0, }, properties: Default::default(), @@ -16197,7 +16201,7 @@ mod joining_fetch_tests { group_order: GroupOrder::Ascending, end_of_track: false, end_location: ietf::Location { - group: GROUP + 1, + group: GROUP, object: 0, }, properties: Default::default(), @@ -16254,7 +16258,7 @@ mod joining_fetch_tests { object: START - 1, }, ietf::Location { - group: GROUP + 1, + group: GROUP, object: 0, }, ] { @@ -16325,35 +16329,51 @@ mod joining_fetch_tests { /// numbers what arrives from there, so a publisher that evicted the prefix can answer. #[moq_clock::test] async fn a_group_fetch_asks_from_the_wanted_frame() { - for version in [Version::Draft19, Version::Draft20, Version::Draft22] { - group_fetch_from_frame(version).await; + for version in JOINING_DRAFTS + .into_iter() + .chain([Version::Draft20, Version::Draft21, Version::Draft22]) + { + for ended in [false, true] { + group_fetch_from_frame(version, false, ended).await; + } + } + } + + /// Legacy moxygen/cache answers one group past the requested group remain readable. + #[moq_clock::test] + async fn a_legacy_group_fetch_answer_still_covers_the_requested_group() { + for version in JOINING_DRAFTS { + for ended in [false, true] { + group_fetch_from_frame(version, true, ended).await; + } } } - async fn group_fetch_from_frame(version: Version) { + async fn group_fetch_from_frame(version: Version, legacy: bool, ended: bool) { const GROUP: u64 = 4; const START: u64 = 2; const LAST: u64 = START + 1; let draft20 = Filter::is_draft20(version); // The whole group, as each draft answers it: draft 20 names the last object, and - // older drafts one past the group. + // older drafts name the whole group with Object 0. let end_location = match draft20 { true => ietf::Location { group: GROUP, object: LAST, }, false => ietf::Location { - group: GROUP + 1, + group: GROUP + u64::from(legacy), object: 0, }, }; let ok = message_bytes( ietf::FetchOk::ID, &ietf::FetchOk { - request_id: None, + request_id: matches!(version, Version::Draft14 | Version::Draft15 | Version::Draft16) + .then_some(RequestId(1)), group_order: GroupOrder::Ascending, - end_of_track: false, + end_of_track: ended, end_location, properties: Default::default(), }, @@ -16372,15 +16392,24 @@ mod joining_fetch_tests { .unwrap(); for (index, payload) in [b"c", b"d"].iter().enumerate() { let first = index == 0; - ietf::FetchObject::Object { - subgroup: ietf::FetchSubgroup::Zero, - group: first.then_some(GROUP), - object: first.then_some(START), - priority: first.then_some(0), - properties: None, + if version == Version::Draft14 { + let w = &mut crate::coding::Encoder::new(&mut objects, version.into()); + w.varint(GROUP).unwrap(); + w.varint(0u64).unwrap(); // Subgroup + w.varint(START + index as u64).unwrap(); + w.u8(0); // Priority + w.varint(0u64).unwrap(); // Properties + } else { + ietf::FetchObject::Object { + subgroup: ietf::FetchSubgroup::Zero, + group: first.then_some(GROUP), + object: first.then_some(START), + priority: first.then_some(0), + properties: None, + } + .encode(&mut crate::coding::Encoder::new(&mut objects, version.into()), version) + .unwrap(); } - .encode(&mut crate::coding::Encoder::new(&mut objects, version.into()), version) - .unwrap(); crate::coding::Encoder::new(&mut objects, version.into()) .varint(1u64) .unwrap(); @@ -16425,9 +16454,14 @@ mod joining_fetch_tests { // The fetch stream, as the peer would open it. let (_, recv) = session.clone().open_bi(Default::default()).await.unwrap(); let mut stream = Reader::new(recv, version); - subscriber.clone().recv_fill(&mut stream).await.expect("group fetch"); + subscriber + .clone() + .recv_fill(&mut stream) + .await + .unwrap_or_else(|err| panic!("{version}: {err:?}")); serving.await.expect("run_group_fetch"); + assert_eq!(consumer.final_sequence(), ended.then_some(GROUP + 1)); let mut group = fetch.await.expect("fetched"); assert_eq!(group.index(), START, "the group starts where the reader wanted"); let mut payloads = Vec::new();