From f0d185abb1f124be200d309678ae06130532a7f1 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 12 Oct 2026 18:11:38 -0700 Subject: [PATCH 1/2] quest(m1): plan subscription order and a live largest location Split `order` out of the model-ranges quest so it can land now on the contributor's #5370 commit, and plan `largest()` replacing `latest()` as a live stream seeded by the publisher's reported largest, instead of #5369's Info snapshot. Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 1 + quest/m1/largest.md | 35 ++++++++++++++++++++++++++++ quest/m1/subscribe-ranges/README.md | 6 +++-- quest/m1/subscribe-ranges/js.md | 3 ++- quest/m1/subscribe-ranges/model.md | 11 +++++---- quest/m1/subscribe-ranges/order.md | 36 +++++++++++++++++++++++++++++ 6 files changed, 84 insertions(+), 8 deletions(-) create mode 100644 quest/m1/largest.md create mode 100644 quest/m1/subscribe-ranges/order.md diff --git a/quest/m1/README.md b/quest/m1/README.md index ea0f0389b0a..5c96741ad12 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -66,6 +66,7 @@ folded into Dropped sources. - [Bump web-transport-iroh for the capsule close](/quest/m1/iroh-capsule-bump.md) - condition: moq-dev/web-transport#419 ships in a release, then moq's iroh HTTP/3 client reports a peer's close capsule - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - every stream group in a lite subscription arrives or is dropped by name, and lite-07 drops its stream count for it - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - a lite-07 SUBSCRIBE asks for past and live ranges with absolute or relative ends, in either order, and replaces FETCH; merged ranges never starve a subscriber; relays fill misses by range, including over moq-transport +- [Live largest location](/quest/m1/largest.md) - `largest()` replaces `latest()` in Rust and JS as a live stream of the track's largest location, known before the first group from the publisher's report - [Reproduce cross-node announce flapping](/quest/m1/cross-node-flapping.md) - a clean close reaches a client on another node as one retraction, checked by a 3+ relay drill on main - [Untimed lite-07](/quest/m1/lite-untimed.md) - lite-07 carries an untimed track in both languages; lite-05/06 write send time - [A watch and publish release ships assets()](/quest/m1/assets-release.md) - the release that lets the sites host the worklets diff --git a/quest/m1/largest.md b/quest/m1/largest.md new file mode 100644 index 00000000000..d9678e82f40 --- /dev/null +++ b/quest/m1/largest.md @@ -0,0 +1,35 @@ +# [M] Live largest location + +## Goal + +A track reader learns the track's largest location before the first group +arrives and follows it live. `largest()` replaces `latest()` on the track +producer, consumer and subscriber in Rust and `@moq/net`, returning a +`Location` (group and frame). It is seeded by the publisher's reported +largest (moq-transport SUBSCRIBE_OK, lite-07 SUBSCRIBE_START) and advances as +groups and frames arrive or a newer value is reported. It never lives on +`Info`, which is per-track and immutable. + +## Plan + +Decided with the maintainer (2026-10-13), after moq-dev/moq#5369 proposed +`Info.publisherLargest` as a snapshot of SUBSCRIBE_OK: + +- **Stream only, no snapshot.** Rust: `async fn largest(&mut self)` and + `poll_largest(waiter)`. JS: `async largest()`. The first call yields the + current location at once if known; each later call waits for a newer one, + skipping values in between; it ends (`None`/`undefined`) when the track + ends. +- **One name everywhere.** Rename on the producer, consumer and subscriber, + and update every caller (moq-json, moq-flate, moq-mux, moq-relay, moq-hls, + moq-c, and the rest) in the same PR. JS's buffered-only `largest()` takes + the new meaning. Callers that read `latest()` synchronously today, such as + producers picking their next sequence, are the risk of stream only; if one + truly needs a synchronous read, ask the maintainer rather than adding a + snapshot. +- Check that no cursor logic assumes the largest location was received + locally: a reported largest is a hint about the edge, not a cached group. +- Bindings follow the cross-package table if any expose `latest()`. +- Cover on mock time in both languages: known before the first group from + SUBSCRIBE_OK and SUBSCRIBE_START, advancing per frame, coalescing, and + ending with the track. diff --git a/quest/m1/subscribe-ranges/README.md b/quest/m1/subscribe-ranges/README.md index f93f0a76e85..99a584ccea9 100644 --- a/quest/m1/subscribe-ranges/README.md +++ b/quest/m1/subscribe-ranges/README.md @@ -30,7 +30,8 @@ relay bounds a sparse FETCH only if the model can request ranges: requested ranges the publisher won't deliver: never existed, expired, or refused upstream. Datagram groups are always dropped in a past range (#4982). The publisher delivers what it has and fills the rest as upstream answers. -- **Model.** `Subscription` gains `ranges` and `order`, mirroring the wire; +- **Model.** `Subscription` gains `ranges` and `order`, mirroring the wire + (`order` lands first, split out 2026-10-13); `request_groups` as a separate API was rejected. A publisher's `track::Dynamic` receives range requests for misses, replacing per-group `requested_group`, and `fetch_group` becomes a one-range subscription or is @@ -71,7 +72,8 @@ every sequence delivered or dropped. ## Required -- [Model ranges](/quest/m1/subscribe-ranges/model.md) - `Subscription` carries ranges and order, and `Dynamic` fills misses by range +- [Subscription order](/quest/m1/subscribe-ranges/order.md) - `Subscription` carries ascending or descending order in both languages, over moq-transport and lite-07 +- [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 ranges](/quest/m1/subscribe-ranges/ietf.md) - range FETCH upstream per missing run, and non-blocking FETCH served downstream diff --git a/quest/m1/subscribe-ranges/js.md b/quest/m1/subscribe-ranges/js.md index 52e6eb3ffb4..adb072fc32f 100644 --- a/quest/m1/subscribe-ranges/js.md +++ b/quest/m1/subscribe-ranges/js.md @@ -2,7 +2,8 @@ ## Goal -`@moq/net` matches Rust: `Subscription` carries ranges and order, the lite-07 +`@moq/net` matches Rust: `Subscription` carries ranges beside the order from +[Subscription order](/quest/m1/subscribe-ranges/order.md), the lite-07 SUBSCRIBE carries them on the wire, FETCH is gone from lite-07, and `fetchGroup` becomes a one-range subscription or is removed. A JavaScript publisher serves requested ranges that are no longer in its live cache. diff --git a/quest/m1/subscribe-ranges/model.md b/quest/m1/subscribe-ranges/model.md index 69161df13e1..2d2884d00c1 100644 --- a/quest/m1/subscribe-ranges/model.md +++ b/quest/m1/subscribe-ranges/model.md @@ -2,9 +2,9 @@ ## Goal -The Rust model's `Subscription` carries a list of group ranges and an order, -aggregated across subscribers. A track serves the union from one cursor -without duplicating a group, in the requested order, and reports every +The Rust model's `Subscription` carries a list of group ranges, aggregated +across subscribers. A track serves the union from one cursor without +duplicating a group, in the subscription's order, and reports every sequence it won't deliver. A publisher's `track::Dynamic` receives range requests for misses instead of one request per group. @@ -16,8 +16,8 @@ Guidance: - Ranges have `Absolute` or `Relative` ends (see the line). Aggregating subscribers onto one upstream request is the union of their ranges; a relative end resolves against the track's latest group when the publisher - serves it. Decide and document the order rule when orders conflict (for - example, desc wins). + serves it. [Subscription order](/quest/m1/subscribe-ranges/order.md) owns + `order` and its merge rule (descending wins). - This absorbs the deleted lite-07 Live flag quest, so the model mirrors the wire with no `live` field, and its tests move here, on mock time and both in-process and through a relay: a subscriber from `Absolute(4)` merged with @@ -48,4 +48,5 @@ Guidance: ## Related +- [Subscription order](/quest/m1/subscribe-ranges/order.md) - `Subscription` carries `order`, which ranges are served in - [FETCH max-delay](/quest/m1/fetch-max-delay.md) - historical request budgets and per-caller enforcement diff --git a/quest/m1/subscribe-ranges/order.md b/quest/m1/subscribe-ranges/order.md new file mode 100644 index 00000000000..a623b281a85 --- /dev/null +++ b/quest/m1/subscribe-ranges/order.md @@ -0,0 +1,36 @@ +# [L] Subscription order + +## Goal + +A subscriber chooses whether a track serves pending groups oldest or newest +first. `Subscription` carries `order: Order` (`Ascending` or `Descending`, +default `Descending`, today's rule) in Rust and `@moq/net`, and the track's +cursor serves its own subscriber in that order: ascending drains a backlog +oldest first instead of skipping to the newest group. moq-transport SUBSCRIBE +GROUP_ORDER and the lite-07 SUBSCRIBE carry it. Ranges stay in +[Model ranges](/quest/m1/subscribe-ranges/model.md). + +## Plan + +Split out of the model quest (maintainer, 2026-10-13) so it can land on +moq-dev/moq#5370, which added a JS GROUP_ORDER codec field nothing set or +honored. Build on that contributor's commit and credit them with a +`Co-authored-by:` trailer. + +- **Name.** `Order` under the track module (`Order::Ascending`, + `Order::Descending`; JS `"ascending" | "descending"`), not `GroupOrder`. + The private IETF `GroupOrder` maps to it; draft-14's 0 (any) decodes as + `Descending`, so no default variant is representable in the model. +- **Aggregation.** Subscribers sharing one upstream request may want + different orders; `Descending` wins upstream, so live subscribers stay + fresh. Each local cursor still serves its own subscriber in its own order + from the cache. +- **Wire.** lite-07 SUBSCRIBE and SUBSCRIBE_UPDATE carry `order`, documented + in `drafts/draft-lcurley-moq-lite.md`; lite-07 is unpublished. moq-transport + maps GROUP_ORDER both ways, and its publisher honors `Ascending`. +- **Older wires.** lite-06 and older cannot carry the field: an `Ascending` + subscription over them falls back to `Descending` (maintainer, 2026-10-13). +- Cover on mock time, in-process and through a relay, in both languages: a + backlog served ascending and descending, an ascending and a descending + subscriber merged on one upstream request, and an `Ascending` request over + lite-06 served newest first. From e91684af28bfa55ff86b216c74af695436186b0f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 12 Oct 2026 18:18:49 -0700 Subject: [PATCH 2/2] quest(m1): move next-sequence callers to the track allocator, not largest() Co-Authored-By: Claude Opus 5.5 --- quest/m1/largest.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/quest/m1/largest.md b/quest/m1/largest.md index d9678e82f40..3fda9f97ae3 100644 --- a/quest/m1/largest.md +++ b/quest/m1/largest.md @@ -23,8 +23,11 @@ Decided with the maintainer (2026-10-13), after moq-dev/moq#5369 proposed - **One name everywhere.** Rename on the producer, consumer and subscriber, and update every caller (moq-json, moq-flate, moq-mux, moq-relay, moq-hls, moq-c, and the rest) in the same PR. JS's buffered-only `largest()` takes - the new meaning. Callers that read `latest()` synchronously today, such as - producers picking their next sequence, are the risk of stream only; if one + the new meaning. Producers that pick their next sequence from + `latest() + 1` (moq-json, moq-mux) read the sequence high-water, which + datagrams and frameless groups also advance, so a frame `Location` can't + replace it: move each to the track's own allocator (`append_group`). If a + caller can't (moq-mux skips a sequence on a data-track discontinuity) or truly needs a synchronous read, ask the maintainer rather than adding a snapshot. - Check that no cursor logic assumes the largest location was received