From 5cc01545a6355414a0eba23ab5d77a772334ecb3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 10:54:04 -0800 Subject: [PATCH 1/3] quest(m1): plan datagram tracks A track is datagrams or streams, fixed at creation. A datagram track has its own lite-07 request (priority only), a sequence and timestamp with no group, no ranges, no cache or FETCH, and maps to object ID 0 on moq-transport. Rewrites the datagram rules in subscribe-ranges, start-bookkeeping, time-addressing, and archive to match, and makes lite07-finalize require the epic. Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 4 + quest/m1/archive/README.md | 2 +- quest/m1/datagram-tracks/README.md | 92 +++++++++++++++++++ quest/m1/datagram-tracks/bindings.md | 20 ++++ quest/m1/datagram-tracks/ietf.md | 31 +++++++ quest/m1/datagram-tracks/js.md | 30 ++++++ quest/m1/datagram-tracks/rust.md | 60 ++++++++++++ quest/m1/lite07-finalize.md | 1 + quest/m1/subscribe-ranges/README.md | 16 +--- quest/m1/subscribe-ranges/js.md | 2 +- quest/m1/subscribe-ranges/lite.md | 7 +- .../m1/subscribe-ranges/start-bookkeeping.md | 15 ++- quest/m1/time-addressing/lite07.md | 6 +- quest/m1/time-addressing/model.md | 4 +- 14 files changed, 260 insertions(+), 30 deletions(-) create mode 100644 quest/m1/datagram-tracks/README.md create mode 100644 quest/m1/datagram-tracks/bindings.md create mode 100644 quest/m1/datagram-tracks/ietf.md create mode 100644 quest/m1/datagram-tracks/js.md create mode 100644 quest/m1/datagram-tracks/rust.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 5d548e00383..a856f079912 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -114,6 +114,9 @@ Added 2026-10-27 (maintainer, from an external security audit): relay and wire boundary fixes, importer streaming, moq-c handle wrap, browser input checks, and CI tool pins, under one epic; its credential leaks went to m0. +Added 2026-11-01 (maintainer): datagram tracks, so lite-07 freezes with +datagrams as their own track kind instead of single-frame groups. + Added 2026-10-27 (maintainer, from an external release-to-main audit): the bindings' silent `max_delay` default change and the upgrade notes that contradict the code. Its other findings already had owners or contradicted @@ -141,6 +144,7 @@ removed). - [Drop set](/quest/m1/drop-set.md) - each cursor judges missing groups against its own budget, so a narrow reader drops promptly and a widening re-offers groups already reported dropped on lite-07 - [Broadcast archives](/quest/m1/archive/README.md) - ANNOUNCE, TRACKS, and a SUBSCRIBE per track record every track under a prefix to any object_store, a host serves a stored broadcast back, and the catalog drops its archive pointer for a per-rendition `hls` field - [Subscriptions take a Delay { min, max }](/quest/m1/subscription-delay.md) - one Delay type across every subscription API, and omitted max means 0 in every binding +- [Datagram tracks](/quest/m1/datagram-tracks/README.md) - a track is datagrams or streams; datagram tracks have their own request and sequence, no ranges, no cache, and map to object ID 0 on moq-transport - [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it - [Smoke token subject](/quest/m1/smoke-token-subject.md) - condition: grant subject ships; then the release smoke test signs with `--subject` - [Moxygen pin bump](/quest/m1/moxygen-pin-bump.md) - waiting on moxygen#264, then the TRACK_STATUS patch is dropped diff --git a/quest/m1/archive/README.md b/quest/m1/archive/README.md index ff1f77deb66..7578f94f78f 100644 --- a/quest/m1/archive/README.md +++ b/quest/m1/archive/README.md @@ -47,7 +47,7 @@ archive (per-track `.timeline.z` records named by the catalog's root `//--` (`-` for an untimed track, `` percent-encoded as one segment), beside a small per-track `.info` holding its timescale and - priority. Each stored sequence keeps its form, group or datagram. A + priority. Datagram tracks are never stored ([Datagram tracks](/quest/m1/datagram-tracks/README.md), maintainer 2026-11-01). A track's `end` records how it ended, clean or with its error code, written with the broadcast's `.end` once the broadcast's listing ends; without them an archive reads as live. A served track advertises the archive's retention (no limit), not diff --git a/quest/m1/datagram-tracks/README.md b/quest/m1/datagram-tracks/README.md new file mode 100644 index 00000000000..280868f9845 --- /dev/null +++ b/quest/m1/datagram-tracks/README.md @@ -0,0 +1,92 @@ +# Datagram tracks + +## Goal + +A track is either a datagram track or a stream track, fixed when it is +created. A datagram track: + +- is subscribed through its own request, not SUBSCRIBE; +- carries frames that have only a sequence number and a timestamp, with no + group; +- takes no bounded ranges; +- is never cached, stored, or returned by FETCH. + +moq-transport maps its sequence to a group ID with object ID 0. Rust and JS +speak it on lite-07, and the epic ends with a Rust-JS interop test of a +datagram track on lite-07, direct and through a relay. Older lite versions +keep today's datagrams. + +## Plan + +Decided 2026-11-01 (maintainer, in `/quest-plan`): + +- **Datagrams are a track-level decision.** ✅ A track is datagrams or + streams, never a mix. This reverses the + [subscribe-ranges](/quest/m1/subscribe-ranges/README.md) decision of + 2026-10-20 that any single-frame group may go as a datagram, including a + copy of a streamed one. With no mixing, the stream/datagram dedup rule, the + ordering of a datagram among its group's streams, NOT_FETCHABLE, and every + datagram case in range accounting all go from lite-07. + - Reason: datagrams are never cached or stored, so they can't take part in + ranges, fills, or FETCH. Mixing them into a stream track makes every one + of those rules carry a datagram exception. +- **Own request.** ✅ A datagram track is subscribed through its own lite-07 + request, not SUBSCRIBE, and that request carries only a priority. ✅ It is + live from now: no start, end, order, or max delay. An update changes only + the priority. A datagram still waits behind higher-priority traffic. +- **No group terminology.** ✅ A datagram carries a sequence number and a + timestamp, with no group. The sequence is the datagram track's own, not + the group sequence space. On moq-transport it maps to a group ID with + object ID 0. + - This exempts datagrams from + [lite-07 by start](/quest/m1/time-addressing/lite07.md): they keep a + sequence, while stream tracks address groups by start. + - The timestamp stays, as it does for every frame. +- **Discovery.** ✅ The application knows which kind a track is, through its + catalog or by convention. The wire carries no kind signal. + - ✅ Datagram tracks and stream tracks have separate namespaces, so + "video" as streams and "video" as datagrams are independent tracks. + - A datagram request for a name with no datagram track is answered as for + any missing track. + - A relay forwards the kind it receives and needs no catalog. +- **Model API.** ✅ Separate types in Rust and JS. A broadcast creates a + stream track or a datagram producer/consumer pair with its own sequence + counter. The datagram types have no group, frame, range, fetch, or cache + API, so the group terminology disappears for datagrams. +- **moq-transport mixing.** ✅ Keep the requested kind. + - A datagram-track subscription maps to IETF SUBSCRIBE and keeps only + datagrams (object 0). Stream objects arriving on it are dropped and + logged. + - A stream-track subscription drops datagrams. + - Outbound, a datagram track sends only OBJECT_DATAGRAM with object ID 0. +- **Archive.** ✅ moq-archive skips datagram tracks. A datagram track is + live-only, and an archive's playback doesn't include it. +- **Version.** ✅ lite-07, before it is finalized. + [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) requires this epic. + lite-01..06 keep today's group datagrams. + +Not settled by the maintainer, so the first child decides it and records why: +the datagram request's answer carries the track's timescale and +compression, as TRACK_INFO does for a stream track. + +This README owns the work no child owns: + +- the Rust-JS interop test of a datagram track on lite-07, direct and + through a relay; +- rewriting the Datagrams section of `doc/concept/moq-lite.md`. + +The draft's own Datagrams section changes with the +[Rust child](/quest/m1/datagram-tracks/rust.md). + +## Required + +- [Rust datagram tracks](/quest/m1/datagram-tracks/rust.md) - Rust model types, the lite-07 datagram request and body, the draft, the relay, and moq-archive skipping datagram tracks +- [JS datagram tracks](/quest/m1/datagram-tracks/js.md) - `@moq/net` datagram types and the lite-07 datagram request +- [moq-transport datagram tracks](/quest/m1/datagram-tracks/ietf.md) - Rust and JS map a datagram track to SUBSCRIBE and OBJECT_DATAGRAM with object ID 0, keeping the requested kind +- [Bindings datagram tracks](/quest/m1/datagram-tracks/bindings.md) - moq-ffi, moq-c, and every wrapper expose the separate datagram types + +## Related + +- [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - ranges no longer cover datagrams +- [Address groups by timestamp](/quest/m1/time-addressing/README.md) - stream tracks address by start; datagram tracks keep a sequence +- [Broadcast archives](/quest/m1/archive/README.md) - skips datagram tracks diff --git a/quest/m1/datagram-tracks/bindings.md b/quest/m1/datagram-tracks/bindings.md new file mode 100644 index 00000000000..4373429a18c --- /dev/null +++ b/quest/m1/datagram-tracks/bindings.md @@ -0,0 +1,20 @@ +# [M] Bindings datagram tracks + +## Goal + +moq-ffi, moq-c, and every wrapper (Python, Swift, Kotlin, Go, Dart, C++) +expose the separate datagram producer and consumer types instead of +datagram methods on stream tracks, mirroring Rust's names. + +## Plan + +Follow the [epic](/quest/m1/datagram-tracks/README.md)'s decisions. Regenerate the +UniFFI outputs, update `go/wrapper` (`publish.go`, `subscribe.go`, +`records.go`) and `dart/moq`, and record the migration in each package's +`MIGRATE.md`. Update `doc/lib/*` where they show datagrams. + +Public API: breaking for every binding's datagrams. Wire: none. + +## Required + +- [Rust datagram tracks](/quest/m1/datagram-tracks/rust.md) - the Rust types the bindings mirror diff --git a/quest/m1/datagram-tracks/ietf.md b/quest/m1/datagram-tracks/ietf.md new file mode 100644 index 00000000000..498568af977 --- /dev/null +++ b/quest/m1/datagram-tracks/ietf.md @@ -0,0 +1,31 @@ +# [S] moq-transport datagram tracks + +## Goal + +Over moq-transport, Rust and JS map a datagram track to IETF SUBSCRIBE and +OBJECT_DATAGRAM, with its sequence as the group ID and object ID 0, and +keep the requested kind when a peer mixes datagrams and streams on one track. + +## Plan + +Decided 2026-11-01 (maintainer), in the +[epic](/quest/m1/datagram-tracks/README.md): + +- A datagram-track subscription keeps only datagrams with object ID 0. + Stream objects arriving on it are dropped and logged once per + subscription. +- A stream-track subscription drops datagrams. +- Outbound, a datagram track sends only OBJECT_DATAGRAM with object ID 0. + A stream track never sends OBJECT_DATAGRAM. +- A datagram with a nonzero object ID on a datagram-track subscription is + dropped and logged. + +Touches `rs/moq-net/src/ietf/datagram.rs` and the JS IETF adapter. Test +against moxygen in the interop lanes where it sends datagrams. + +Public API: none beyond the model. Wire: no format change. + +## Required + +- [Rust datagram tracks](/quest/m1/datagram-tracks/rust.md) - the datagram types this maps +- [JS datagram tracks](/quest/m1/datagram-tracks/js.md) - the JS datagram types this maps diff --git a/quest/m1/datagram-tracks/js.md b/quest/m1/datagram-tracks/js.md new file mode 100644 index 00000000000..7dfb26190e4 --- /dev/null +++ b/quest/m1/datagram-tracks/js.md @@ -0,0 +1,30 @@ +# [M] JS datagram tracks + +## Goal + +`@moq/net` has the same separate datagram types as Rust, and speaks the +lite-07 datagram request and datagram body against the Rust implementation. +Stream tracks lose `appendDatagram`, and datagram sequences no longer share +the group counter. Older lite versions keep today's group datagrams. + +## Plan + +Follow the [epic](/quest/m1/datagram-tracks/README.md)'s decisions and the +wire that [Rust datagram tracks](/quest/m1/datagram-tracks/rust.md) lands in +the draft. + +- Remove from `js/net/src/track.ts` and the lite subscriber and publisher: + - `appendDatagram` and the shared sequence counter (`track.test.ts` + "appendDatagram shares the group sequence counter"); + - the join and refresh rules for datagrams ("a join wants past a datagram + after the newest group"); + - the datagram cases in ranges. +- Map lite-01..06 group datagrams the same way Rust does. +- Update any first-party consumer of JS datagrams. + +Public API: breaking for `@moq/net` datagrams. Wire: lite-07-wip, matching +Rust. + +## Required + +- [Rust datagram tracks](/quest/m1/datagram-tracks/rust.md) - lands the lite-07 wire this matches diff --git a/quest/m1/datagram-tracks/rust.md b/quest/m1/datagram-tracks/rust.md new file mode 100644 index 00000000000..d080f6ae509 --- /dev/null +++ b/quest/m1/datagram-tracks/rust.md @@ -0,0 +1,60 @@ +# [L] Rust datagram tracks + +## Goal + +moq-net has separate datagram types: a broadcast creates a datagram +producer/consumer pair with its own sequence counter, and stream tracks +carry no datagram API. Lite-07 subscribes to a datagram track through its +own request and sends datagrams addressed by that sequence. The relay +forwards datagram tracks, and moq-archive skips them. lite-01..06 keep +today's group datagrams. + +## Plan + +The decisions are in the [epic](/quest/m1/datagram-tracks/README.md). + +**Model** +- Add the datagram producer and consumer types to `rs/moq-net/src/model/`. + Each has its own sequence counter and a tiny send/receive buffer, with no + cache and no ranges. +- Datagram tracks have their own namespace in a broadcast. +- Remove the datagram paths from stream tracks: + - `insert_datagram` and the stored datagrams in `model/datagram.rs`; + - `poll_recv_datagram` and its resume handling in `model/resume.rs`; + - datagram cases in fills, misses, and range accounting. + +**Wire (lite-07)** +- A datagram subscribe request carries only a priority, and an update + changes only the priority. +- A datagram carries its sequence, its timestamp, and the payload. +- Decide whether the request's answer carries the track's timescale and + compression as TRACK_INFO does, and record the reason in the epic. +- Remove the lite-07 rules that mixing needed: + - stream/datagram dedup; + - ordering a datagram among its group's streams; + - NOT_FETCHABLE; + - datagrams in SUBSCRIBE_DROP coverage; + - the datagram grace in the subscriber's end (`a_lost_datagram_delays_the_end`). +- On lite-01..06, map today's group datagrams onto the datagram types: + - Inbound, a group datagram on a subscription goes to the datagram track of + the same name. + - Outbound, a datagram track's subscriber on an old version gets group + datagrams keyed by its sequence. + +**Elsewhere** +- The relay forwards each kind as it received it. +- moq-archive's producer and consumer drop their datagram form. +- moq-ffi keeps its public datagram surface, mapped onto the new types + internally. Its public API changes in + [bindings](/quest/m1/datagram-tracks/bindings.md). +- Update `drafts/draft-lcurley-moq-lite.md`: the Datagrams section, the + request, the error table, and the lite-07 changelog. Then run + `just drafts check` and `just test interop --all`. +- The PR's Impact section says how to migrate. + +Public API: breaking. Stream tracks lose their datagram methods, and the +datagram types are new. Wire: lite-07-wip datagrams and a new request. + +## Related + +- [Lite-07 by start](/quest/m1/time-addressing/lite07.md) - stream groups address by start; datagrams keep a sequence diff --git a/quest/m1/lite07-finalize.md b/quest/m1/lite07-finalize.md index 73a951d9774..d0bdf1c30bd 100644 --- a/quest/m1/lite07-finalize.md +++ b/quest/m1/lite07-finalize.md @@ -115,6 +115,7 @@ timestamp bound in [#6168](https://github.com/moq-dev/moq/pull/6168). - [@moq/net by start](/quest/m1/time-addressing/js.md) - JS speaks the same lite-07 wire - [A job's exact route continues its claim's readers](/quest/m1/announce-takeover.md) - the job's route inherits the claim's identity, with no new wire message - [Subscriptions take a Delay { min, max }](/quest/m1/subscription-delay.md) - lite-07 SUBSCRIBE carries the delay's min as well as its max +- [Datagram tracks](/quest/m1/datagram-tracks/README.md) - lite-07 subscribes to datagram tracks through their own request, and datagrams carry their own sequence ## Related diff --git a/quest/m1/subscribe-ranges/README.md b/quest/m1/subscribe-ranges/README.md index 01a30a816fc..83ec1c41c43 100644 --- a/quest/m1/subscribe-ranges/README.md +++ b/quest/m1/subscribe-ranges/README.md @@ -30,7 +30,7 @@ relay bounds a sparse FETCH only if the model can request ranges: lite-07; published versions keep it, answered through the same model. - **Holes.** SUBSCRIBE_DROP (restored in lite-07) names every sequence in the requested ranges the publisher won't deliver: never existed, expired, or - refused upstream. Datagram groups are always dropped in a past range (#4982). The + refused upstream. On lite-01..06 datagram groups are always dropped in a past range (#4982); on lite-07 ranges never cover datagrams ([Datagram tracks](/quest/m1/datagram-tracks/README.md)). The publisher delivers what it has and fills the rest as upstream answers. - **Model.** `Subscription` gains `ranges` beside its `order`, mirroring the wire; `request_groups` as a separate API was rejected. A publisher's @@ -79,16 +79,10 @@ relay bounds a sparse FETCH only if the model can request ranges: [lite-07 finalizes](/quest/m1/lite07-finalize.md), which this line gates. This amends the 09-29 premise that ranges are group-only because a group's timestamp isn't always known: timed tracks know it, and untimed ones refuse. The cache half landed in its own PR after #5929. - A datagram is judged on its own (maintainer, 2026-10-20): its timestamp - against the range's times, its sequence against the absolute and resolved - relative groups, never through the settle walk. Refusing time anchors on - datagram tracks was considered and can't work: nothing signals that a track - carries datagrams, and the lite draft lets a publisher send any single-frame - group as a datagram, including a copy of one it also streams. Datagrams stay - ephemeral (maintainer, 2026-10-20): a buffered datagram never indexes where - its group starts, so a time end settles across a sequence that arrived only - as a datagram, and a stream copy of that group arriving later is read even - if it starts past the end. + A datagram was judged on its own (maintainer, 2026-10-20). Superseded + 2026-11-01 (maintainer): datagrams become their own track kind + ([Datagram tracks](/quest/m1/datagram-tracks/README.md)), so on lite-07 + a range never covers a datagram. - Ranges are whole groups: a range always starts at a group's first frame (maintainer, on [moq-dev/moq#6465](https://github.com/moq-dev/moq/pull/6465)). The IETF joining FETCH for the live group's uncached prefix stays, because today's bridge relies on it diff --git a/quest/m1/subscribe-ranges/js.md b/quest/m1/subscribe-ranges/js.md index 1d0b7c687c4..58774de905a 100644 --- a/quest/m1/subscribe-ranges/js.md +++ b/quest/m1/subscribe-ranges/js.md @@ -62,7 +62,7 @@ Ranges stay whole groups ([moq-dev/moq#6465](https://github.com/moq-dev/moq/pull so the group model keeps refusing a nonzero lite `frameStart` as a protocol violation, as `lite/subscriber.ts` `runGroup` does. Preserve the per-reader group-bound rule for reliable reads, live-edge selection, subscription -updates, and publisher datagrams. +and subscription updates. Datagrams move to their own track kind ([Datagram tracks](/quest/m1/datagram-tracks/README.md)). ## Related diff --git a/quest/m1/subscribe-ranges/lite.md b/quest/m1/subscribe-ranges/lite.md index 8ed65d2d990..3f0246b9598 100644 --- a/quest/m1/subscribe-ranges/lite.md +++ b/quest/m1/subscribe-ranges/lite.md @@ -45,10 +45,9 @@ resolved end and it resolves the end itself (`wire_ranges`), so only absolute bounded ranges complete upstream. A hole on a live track counts as dropped only once the feed gives up on it, past the arrivals grace; [Fetch as a range](/quest/m1/subscribe-ranges/fetch-range.md) owns judging -such a miss sooner. A range served only by datagrams never completes: they -resolve no SUBSCRIBE_START, so a FIN overtaking them leaves the receiver no -owed range to wait on. Datagram fills need the receiver told what is owed -first. +such a miss sooner. A range never covers a datagram on lite-07, since datagrams become their +own track kind ([Datagram tracks](/quest/m1/datagram-tracks/README.md), +maintainer 2026-11-01), so datagram fills need no handling here. Update `drafts/draft-lcurley-moq-lite.md` with each wire change here. Run `just drafts check` and `just test interop --all`. diff --git a/quest/m1/subscribe-ranges/start-bookkeeping.md b/quest/m1/subscribe-ranges/start-bookkeeping.md index 8567464585c..1f417378d0f 100644 --- a/quest/m1/subscribe-ranges/start-bookkeeping.md +++ b/quest/m1/subscribe-ranges/start-bookkeeping.md @@ -25,14 +25,13 @@ f235fcfcbd, df0bd5c36f, 342445f251, 06765f4c1a, 4927167904, f52848d634, plus `cursor_floor` and a pre-06 re-pin branch, encoding three wire generations of "start". -- On lite-07 a stream or a DROP accounts for every sequence except one sent - only as a datagram, which can be lost unseen - (`a_lost_datagram_delays_the_end` in `tests/integration/track_tail.rs`). - So the subscriber's end is "owed range covered and no stream active", - except that a hole a datagram may have left still settles within a bounded - grace; only reliable accounting of datagram sequences could remove that. - Keep `Settle`'s full grace for lite-05/06 and moq-transport behind one - version predicate. +- On lite-07 a stream or a DROP accounts for every sequence, since + [Datagram tracks](/quest/m1/datagram-tracks/README.md) takes datagrams out + of stream tracks (maintainer, 2026-11-01). The subscriber's end is "owed + range covered and no stream active", with no datagram grace; + `a_lost_datagram_delays_the_end` becomes a lite-05/06 case. Keep + `Settle`'s full grace for lite-05/06 and moq-transport behind one version + predicate. - Lite-07 is unpublished, so sending a fresh START per update can remove the `requested == start` gate (`lite/subscriber.rs`, about line 4898). diff --git a/quest/m1/time-addressing/lite07.md b/quest/m1/time-addressing/lite07.md index 4bf6f3ced2f..45467c92128 100644 --- a/quest/m1/time-addressing/lite07.md +++ b/quest/m1/time-addressing/lite07.md @@ -4,7 +4,7 @@ moq-lite-07 carries no group sequence numbers: a GROUP names its start and its predecessor's start, GROUP_END says where a whole group ends, and every -subscription bound, drop, and datagram is a time. Rust speaks it, the lite +subscription bound and drop is a time. Datagrams keep a sequence of their own ([Datagram tracks](/quest/m1/datagram-tracks/README.md)). Rust speaks it, the lite draft specifies it, and lite-01..06 are unchanged. ## Plan @@ -20,7 +20,7 @@ Decided 2026-10-25 (maintainer), from the spike: instead of resetting it, which changes the draft's reset rule for those groups (around line 760). - SUBSCRIBE and SUBSCRIBE_UPDATE bounds, SUBSCRIBE_OK and its largest, - SUBSCRIBE_END, SUBSCRIBE_DROP, and datagrams address by start. Drops name + SUBSCRIBE_END, and SUBSCRIBE_DROP address by start. Datagrams keep their own sequence (maintainer, 2026-11-01). Drops name time spans with no group to deliver, not sequence ranges. `Relative(n)` stays a group count. - Positions stay (start, frame index), preserving transport frame offsets. @@ -39,7 +39,7 @@ and `just test interop --all`. Public API: none beyond [the model](/quest/m1/time-addressing/model.md). Wire: lite-07-wip GROUP, GROUP_END, SUBSCRIBE, SUBSCRIBE_UPDATE, -SUBSCRIBE_OK, SUBSCRIBE_END, SUBSCRIBE_DROP, and datagrams change. +SUBSCRIBE_OK, SUBSCRIBE_END, and SUBSCRIBE_DROP change. ## Required diff --git a/quest/m1/time-addressing/model.md b/quest/m1/time-addressing/model.md index 04f3e4b9fdb..5cc1e99164e 100644 --- a/quest/m1/time-addressing/model.md +++ b/quest/m1/time-addressing/model.md @@ -76,7 +76,7 @@ it: - Resume across route flips (`resume.rs`), mid-group `Position` and `frame_start`, priority order within a subscription, `Demand::wanted`, and refresh. -- The datagram namespace, which shares the group space. +- Not datagrams: they become their own track kind with their own sequence ([Datagram tracks](/quest/m1/datagram-tracks/README.md)). - The legacy codecs: lite GROUP, SUBSCRIBE and SUBSCRIBE_UPDATE bounds, SUBSCRIBE_START and its largest, SUBSCRIBE_END, SUBSCRIBE_DROP, FETCH, and every IETF Location, Filter, FETCH, Largest, and NEW_GROUP_REQUEST. @@ -111,7 +111,7 @@ resume model (`rs/moq-net/src/model/resume_model.rs`, The PR's Impact section says how to migrate. Public API: breaking. `group::Info`, `create_group`, `append_group`, -`Position`, `Range` ends, `fetch_group`, `Subscriber::floor`, datagrams, and +`Position`, `Range` ends, `fetch_group`, `Subscriber::floor`, and group consumers address by start timestamp, and untimed tracks go away. Wire: no format change; legacy and lite-07-wip group IDs become start ticks. From d8e7d60c593e7a50848f04c6eb599e89f4af5f33 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 11:03:21 -0800 Subject: [PATCH 2/3] quest(m1): address review on the datagram tracks plan Co-Authored-By: Claude Opus 5.5 --- quest/m1/archive/README.md | 2 +- quest/m1/datagram-tracks/README.md | 3 ++- quest/m1/datagram-tracks/rust.md | 22 ++++++++++++------- .../m1/subscribe-ranges/start-bookkeeping.md | 3 ++- quest/m1/subscription-delay.md | 2 ++ 5 files changed, 21 insertions(+), 11 deletions(-) diff --git a/quest/m1/archive/README.md b/quest/m1/archive/README.md index 7578f94f78f..4e333722386 100644 --- a/quest/m1/archive/README.md +++ b/quest/m1/archive/README.md @@ -2,7 +2,7 @@ ## Goal -`moq-archive` stores every track of every broadcast under a path prefix into +`moq-archive` stores every stream track of every broadcast (datagram tracks are never stored) under a path prefix into any `object_store::ObjectStore` and serves a stored broadcast back as an ordinary broadcast, with no catalog dependency. A host finds broadcasts by ANNOUNCE and runs one `archive::Producer` per broadcast, which diff --git a/quest/m1/datagram-tracks/README.md b/quest/m1/datagram-tracks/README.md index 280868f9845..ade7f34cb86 100644 --- a/quest/m1/datagram-tracks/README.md +++ b/quest/m1/datagram-tracks/README.md @@ -32,7 +32,8 @@ Decided 2026-11-01 (maintainer, in `/quest-plan`): of those rules carry a datagram exception. - **Own request.** ✅ A datagram track is subscribed through its own lite-07 request, not SUBSCRIBE, and that request carries only a priority. ✅ It is - live from now: no start, end, order, or max delay. An update changes only + live from now: no start, end, order, or `Delay` + ([Subscription delay](/quest/m1/subscription-delay.md) exempts it). An update changes only the priority. A datagram still waits behind higher-priority traffic. - **No group terminology.** ✅ A datagram carries a sequence number and a timestamp, with no group. The sequence is the datagram track's own, not diff --git a/quest/m1/datagram-tracks/rust.md b/quest/m1/datagram-tracks/rust.md index d080f6ae509..b390a477645 100644 --- a/quest/m1/datagram-tracks/rust.md +++ b/quest/m1/datagram-tracks/rust.md @@ -35,18 +35,24 @@ The decisions are in the [epic](/quest/m1/datagram-tracks/README.md). - NOT_FETCHABLE; - datagrams in SUBSCRIBE_DROP coverage; - the datagram grace in the subscriber's end (`a_lost_datagram_delays_the_end`). -- On lite-01..06, map today's group datagrams onto the datagram types: - - Inbound, a group datagram on a subscription goes to the datagram track of - the same name. - - Outbound, a datagram track's subscriber on an old version gets group - datagrams keyed by its sequence. +- On lite-01..06, one subscription to a name carries both group streams and + group datagrams. Map it the way moq-transport does, keeping the requested + kind: + - Inbound, a datagram-track subscription keeps only group datagrams and + drops group streams. A stream-track subscription drops group datagrams. + - Outbound, an old-version SUBSCRIBE for a name is served from the stream + track of that name. It is served from the datagram track, as group + datagrams keyed by its sequence, only when no stream track has that name. + - This outbound rule is the plan's default. This quest may revisit it, and + records why if it does. **Elsewhere** - The relay forwards each kind as it received it. - moq-archive's producer and consumer drop their datagram form. -- moq-ffi keeps its public datagram surface, mapped onto the new types - internally. Its public API changes in - [bindings](/quest/m1/datagram-tracks/bindings.md). +- moq-ffi's public datagram API (`append_datagram`, `recv_datagram`) is + unchanged in this quest, and is backed internally by the new types. The + [bindings](/quest/m1/datagram-tracks/bindings.md) quest then replaces it + with the separate types. - Update `drafts/draft-lcurley-moq-lite.md`: the Datagrams section, the request, the error table, and the lite-07 changelog. Then run `just drafts check` and `just test interop --all`. diff --git a/quest/m1/subscribe-ranges/start-bookkeeping.md b/quest/m1/subscribe-ranges/start-bookkeeping.md index 1f417378d0f..1d7f173b5ce 100644 --- a/quest/m1/subscribe-ranges/start-bookkeeping.md +++ b/quest/m1/subscribe-ranges/start-bookkeeping.md @@ -25,7 +25,8 @@ f235fcfcbd, df0bd5c36f, 342445f251, 06765f4c1a, 4927167904, f52848d634, plus `cursor_floor` and a pre-06 re-pin branch, encoding three wire generations of "start". -- On lite-07 a stream or a DROP accounts for every sequence, since +- On lite-07 every owed range is covered by delivered stream groups or a + DROP, since [Datagram tracks](/quest/m1/datagram-tracks/README.md) takes datagrams out of stream tracks (maintainer, 2026-11-01). The subscriber's end is "owed range covered and no stream active", with no datagram grace; diff --git a/quest/m1/subscription-delay.md b/quest/m1/subscription-delay.md index f83f4370502..efa937fdd88 100644 --- a/quest/m1/subscription-delay.md +++ b/quest/m1/subscription-delay.md @@ -19,6 +19,8 @@ Decided 2026-10-30 (maintainer, follow-up planning): m1, because it breaks the p Each one's omitted or zeroed form becomes 0, and unlimited stays expressible. Dart defaults the parameter to `Duration.zero`, so an explicit `null` stays unlimited. Go's nil and C's unset `present` can't mean both, so each gains an explicit unlimited flag in the delay; the PR names it. The breaking binding changes get MIGRATE notes under `## Unreleased`. +- **Not datagram subscriptions:** a datagram track's request carries only a priority and takes no `Delay` ([Datagram tracks](/quest/m1/datagram-tracks/README.md), maintainer 2026-11-01). + Public API: breaking in every binding. Wire: lite-07 SUBSCRIBE and SUBSCRIBE_UPDATE gain `min`. ## Related From 0e681a57720c485b9e35d621e6e0eaf91177aff8 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 22:40:46 -0800 Subject: [PATCH 3/3] quest(m2): scope datagram plans to the datagram track split Pullfrog's review found net-wrap and lite-tail-drop-count still planning around track-level datagram methods and lite-07 datagram holes. Co-Authored-By: Claude Opus 5.5 --- quest/m1/datagram-tracks/README.md | 2 ++ quest/m2/lite-tail-drop-count.md | 2 +- quest/m2/net-wrap/README.md | 4 ++++ quest/m2/net-wrap/e2ee.md | 7 ++++--- quest/m2/net-wrap/traits.md | 3 ++- 5 files changed, 13 insertions(+), 5 deletions(-) diff --git a/quest/m1/datagram-tracks/README.md b/quest/m1/datagram-tracks/README.md index b352e7bab14..0b4771d3e6f 100644 --- a/quest/m1/datagram-tracks/README.md +++ b/quest/m1/datagram-tracks/README.md @@ -90,3 +90,5 @@ The draft's own Datagrams section changes with the - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - ranges no longer cover datagrams - [Address groups by timestamp](/quest/m1/time-addressing/README.md) - stream tracks address by start; datagram tracks keep a sequence +- [Wrapper traits over moq-net](/quest/m2/net-wrap/README.md) - the traits mirror the separate datagram types +- [moq-lite session tails count drops](/quest/m2/lite-tail-drop-count.md) - datagram holes matter only on lite-05/06 diff --git a/quest/m2/lite-tail-drop-count.md b/quest/m2/lite-tail-drop-count.md index d72ee0fed33..0ec7946a4d7 100644 --- a/quest/m2/lite-tail-drop-count.md +++ b/quest/m2/lite-tail-drop-count.md @@ -9,7 +9,7 @@ From lite-05 on, a moq-lite session's tail is complete once every group up to th Decided 2026-10-30 (maintainer, follow-up planning): m2. Found by the audit on [moq-dev/moq#7403](https://github.com/moq-dev/moq/pull/7403). The maintainer dislikes grace periods. - Count per version. lite-01..04 have no drop message, so they keep today's behaviour. -- Account for holes left by lost datagrams. +- On lite-05/06, account for holes left by lost datagrams. Lite-07 stream tracks carry no datagrams ([Datagram tracks](/quest/m1/datagram-tracks/README.md)). - Guard against a peer that never accounts for a group: decide with the maintainer whether that ends the tail with an error or keeps waiting. Don't add a new grace. - The IETF tail keeps its grace until the moq-transport gap-signal extension (planned in [moq-dev/moq#7425](https://github.com/moq-dev/moq/pull/7425)) lands, since moq-transport can't signal gaps. diff --git a/quest/m2/net-wrap/README.md b/quest/m2/net-wrap/README.md index def14e4acfb..ad910010b86 100644 --- a/quest/m2/net-wrap/README.md +++ b/quest/m2/net-wrap/README.md @@ -41,6 +41,10 @@ and its trait-versus-bridge comparison: their `poll_*` forms. A wrapper adapts to moq-net, not the other way around: moq-e2ee's error converts into `moq_net::Error`. +- **Datagrams follow the datagram types.** [Datagram tracks](/quest/m1/datagram-tracks/README.md) (m1) replaces + `append_datagram`, `insert_datagram`, and `recv_datagram` on stream tracks + with separate datagram producer and consumer types, so the traits mirror + those types instead. - **Terminal propagation crosses the wrapper.** Finish, typed aborts (such as e2ee's authentication error), and handle teardown reach the other side at every level, rather than collapsing into `Error::Dropped` or keeping a diff --git a/quest/m2/net-wrap/e2ee.md b/quest/m2/net-wrap/e2ee.md index cbc3814c939..6aa6af87b2c 100644 --- a/quest/m2/net-wrap/e2ee.md +++ b/quest/m2/net-wrap/e2ee.md @@ -20,9 +20,10 @@ the reverse (decided 2026-10-20, maintainer): - `moq_e2ee::Error` converts into `moq_net::Error`, keeping the draft's typed codes (such as an authentication failure) distinguishable rather than collapsing into `Error::Dropped`. -- Datagrams: `append_datagram`, `insert_datagram`, and `recv_datagram` - match moq-net's signatures, so the trait read yields only authenticated - datagrams. A datagram that fails authentication, or a duplicate, is +- Datagrams: the wrapper's datagram producer and consumer match the + separate datagram types of + [Datagram tracks](/quest/m1/datagram-tracks/README.md), so the trait read + yields only authenticated datagrams. A datagram that fails authentication, or a duplicate, is dropped there and the track continues. The draft's `authentication` event stays on moq-e2ee's own consumer, outside the trait, for callers that hold the concrete type. A trait read can't carry it without diff --git a/quest/m2/net-wrap/traits.md b/quest/m2/net-wrap/traits.md index 58f9a0c3688..d0a07879f6d 100644 --- a/quest/m2/net-wrap/traits.md +++ b/quest/m2/net-wrap/traits.md @@ -37,7 +37,8 @@ the methods exactly as moq-net has them today. wrapper's own subscriber, so E2EE decrypts behind it; `Resolving` and `Fetching` resolve to the wrapper's logical metadata and groups. - Adapters: a subscriber's `ordered` returns its own `track::Ordered` - with the same group, datagram, and control surface. moq-json's snapshot + with the same group and control surface; datagrams leave stream tracks + with [Datagram tracks](/quest/m1/datagram-tracks/README.md). moq-json's snapshot and window consumers, moq-mux, and moq-stats read through `ordered()`, so without it they stay concrete. - Listing (maintainer, 2026-10-24): a broadcast consumer's `tracks`