From 05b43b87ab97599e015a1403da59e3ac9d14da59 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 28 Sep 2026 22:20:01 -0700 Subject: [PATCH 001/128] chore(quest): claim splice-edges Co-Authored-By: GPT-6 From 06bcadd06c96b0c54fae6247cc2485d503ec5dba Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 28 Sep 2026 23:53:31 -0700 Subject: [PATCH 002/128] fix(net): preserve splice boundary and warm-head state Co-Authored-By: GPT-6 Astra --- doc/concept/moq-lite.md | 6 ++ quest/m1/README.md | 1 - quest/m1/relay-late-joiner-history.md | 7 +-- quest/m1/resume-latest.md | 1 - quest/m1/splice-edges.md | 37 ----------- rs/moq-net/src/model/origin.rs | 89 ++++++++++++++++++++++++++- rs/moq-net/src/model/resume.rs | 49 ++++++++++++++- rs/moq-net/src/model/track.rs | 10 +-- 8 files changed, 146 insertions(+), 54 deletions(-) delete mode 100644 quest/m1/splice-edges.md diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index c2947245ed4..6dc19feef3a 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -224,6 +224,12 @@ anything on its own. Both ends apply it: the publisher skips a group rather than sending it, and the subscriber skips it again as it reads, since the publisher only ever sees the most tolerant budget across its subscribers. +Across a native route failover, the reader still judges buffered groups against +the logical track's live edge, including groups it is draining from a retired +route. A successor group with no timestamp leaves the preceding group's reach +unbounded until its first frame arrives. A cached open group's prefix remains +readable across repeated takeovers and idle resumes. + The publisher declares a retention window per track, which bounds how far back a fetch or late subscriber can reach. Media tracks default to 30 seconds so a segmented egress can still find its segments. diff --git a/quest/m1/README.md b/quest/m1/README.md index 19dad3cbf70..91d194bb146 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -34,7 +34,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [IETF hidden default](/quest/m1/ietf-hidden-default.md) - a moq-transport peer without the MoQ Hidden option is advertised hidden namespaces; one with it filters per subscription - [Watch refusal](/quest/m1/watch-refusal.md) - `` shows an origin refusal as an error instead of sitting offline - [moqsink recoverable errors](/quest/m1/moqsink-keyframe-latch.md) - a leading delta or a timestamp rewind drops frames until a keyframe instead of invalidating a moqsink pad -- [Splice edge cases](/quest/m1/splice-edges.md) - an unstamped successor, a pruned segment's boundary group, and a warm head during a takeover are each handled correctly - [Resumed groups](/quest/m1/resume-latest.md) - a half-delivered group ends once the new copy is past it, so a group-only reader never parks after a mid-group failover - [Track tail hardening](/quest/m1/track-tail-hardening.md) - Rust and JS wait out a track's tail by the same rules, with the known hang, count, truncation, grace, and memory holes closed - [JS close end](/quest/m1/js-track-close-end.md) - a JS track's clean close ends at its own last group, not a sibling producer's diff --git a/quest/m1/relay-late-joiner-history.md b/quest/m1/relay-late-joiner-history.md index bd041dc43ce..43d2c857ba7 100644 --- a/quest/m1/relay-late-joiner-history.md +++ b/quest/m1/relay-late-joiner-history.md @@ -36,9 +36,4 @@ What we saw: Start from how a newly spliced or parked segment derives its floor for a subscriber that asked for group 0, and whether a warm copy's cached groups -below the new segment's first group stay reachable. The -[splice edge cases](/quest/m1/splice-edges.md) touch the same code. - -## Related - -- [Splice edge cases](/quest/m1/splice-edges.md) - other spliced-track cases that lose or mis-judge groups +below the new segment's first group stay reachable. diff --git a/quest/m1/resume-latest.md b/quest/m1/resume-latest.md index f594bfc566c..fb878c5c1aa 100644 --- a/quest/m1/resume-latest.md +++ b/quest/m1/resume-latest.md @@ -71,4 +71,3 @@ Regression tests, on a paused clock (`#[tokio::test(start_paused = true)]`): ## Related - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - tells a resumed latest group when the new copy dropped it -- [Splice edge cases](/quest/m1/splice-edges.md) - the same splice code and test harness diff --git a/quest/m1/splice-edges.md b/quest/m1/splice-edges.md deleted file mode 100644 index aa0d904500f..00000000000 --- a/quest/m1/splice-edges.md +++ /dev/null @@ -1,37 +0,0 @@ -# [S] Splice edge cases - -## Goal - -Three spliced-track cases in `rs/moq-net` stop losing or mis-judging groups, -each with a regression test that fails before its fix: - -- A group whose successor segment's first servable group is still unstamped - keeps an unbounded reach, instead of borrowing a later segment's start and - being skipped or ended with `Error::Old`. -- A reader still draining a pruned segment has its boundary group judged - against the later segments, so a stale boundary group is skipped like any - other. -- A reader draining a warm head keeps it when the upstream fails over again - before the track parks. - -## Plan - -Codex raised all three on https://github.com/moq-dev/moq/pull/4103 and -https://github.com/moq-dev/moq/pull/4104 after the fixes there landed; none -was answered. - -- `served_start` in `rs/moq-net/src/model/resume.rs` says an unstamped group - stops the search, but `find_map` reads a segment's `None` (no group, or its - first group has no frame yet) as a miss and moves on. The two cases need - to be distinguishable, as the per-track `served_start` in - `rs/moq-net/src/model/track.rs` already treats them. -- `ResumeState::successor` finds the cursor's segment by id, so a segment - `prune` removed while a reader still drains it yields no successor at all. - Resolve it from the boundary and the remaining later segments instead. -- An ordinary takeover in `rs/moq-net/src/model/origin.rs` (`Action::Splice` - with no warm copy) overwrites `io.head` with `None`. Dropping the - `WarmGroup` aborts the cached head that a reader resumed from an earlier - park may still be reading, and the next park cannot rebuild the full group. - Keep the existing head when the splice has no new one to take. - -These are independent; one PR is fine since they share the splice tests. diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index d39e9c206f1..c386ece301e 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -2476,7 +2476,9 @@ async fn run_front(task: FrontTask) { tracks.remove(&name); continue; } - io.head = io.warm.take().and_then(|mut warm| warm.edge.take()); + if let Some(head) = io.warm.take().and_then(|mut warm| warm.edge.take()) { + io.head = Some(head); + } // The new segment has produced nothing yet: this is the // edge the copy is asked to advance. io.edge = io.resume.resume_position(); @@ -5693,6 +5695,91 @@ mod tests { } } + #[tokio::test] + async fn warm_head_survives_another_takeover_before_park() { + tokio::time::pause(); + let producer = origin(1).produce(); + let _server = producer + .dynamic("room/alice", Route::default().with_hops(hops(&[10])).with_cost(5)) + .unwrap(); + let pending = producer.consume().request_broadcast("room/alice"); + let upstream = broadcast::Info::new().produce(); + let mut dynamic = upstream.dynamic(); + queued(&_server).await.accept(&upstream); + let resolved = pending.await.unwrap(); + + let track = resolved.track("log").unwrap(); + let subscribing = tokio::spawn(async move { track.subscribe(None).await }); + let source = dynamic.requested_track().await.unwrap().accept(None); + let mut group = source.create_group(0u64.into()).unwrap(); + group.write_frame(crate::Timestamp::ZERO, b"a".as_ref()).unwrap(); + group.write_frame(crate::Timestamp::ZERO, b"b".as_ref()).unwrap(); + let mut subscription = subscribing.await.unwrap().unwrap(); + let mut reading = subscription.recv_group().await.unwrap().unwrap(); + assert_eq!(&reading.read_frame().await.unwrap().unwrap().payload[..], b"a"); + drop(reading); + drop(subscription); + source.unused().await.unwrap(); + drop(group); + drop(source); + + let track = resolved.track("log").unwrap(); + let subscribing = tokio::spawn(async move { track.subscribe(None).await }); + let mut resumed = dynamic.requested_track().await.unwrap().resolving_start().accept(None); + resumed.start_at(0).unwrap(); + let mut subscription = subscribing.await.unwrap().unwrap(); + let mut reading = subscription.recv_group().await.unwrap().unwrap(); + assert_eq!(&reading.read_frame().await.unwrap().unwrap().payload[..], b"a"); + + let replacement_server = producer + .dynamic("room/alice", Route::default().with_hops(hops(&[10]))) + .unwrap(); + let replacement = broadcast::Info::new().produce(); + let mut replacement_dynamic = replacement.dynamic(); + queued(&replacement_server).await.accept(&replacement); + let mut source = replacement_dynamic + .requested_track() + .await + .unwrap() + .resolving_start() + .accept(None); + source.start_at(0).unwrap(); + let mut group = source.create_group(0u64.into()).unwrap(); + group.start_at(2).unwrap(); + group.write_frame(crate::Timestamp::ZERO, b"c".as_ref()).unwrap(); + let mut continuation = reading.clone(); + continuation.start_at(2); + let frame = tokio::time::timeout(Duration::from_secs(1), continuation.read_frame()) + .await + .expect("replacement frame") + .unwrap() + .unwrap(); + assert_eq!(&frame.payload[..], b"c"); + drop(continuation); + assert_eq!(&reading.read_frame().await.unwrap().unwrap().payload[..], b"b"); + assert_eq!(&reading.read_frame().await.unwrap().unwrap().payload[..], b"c"); + drop(reading); + drop(subscription); + source.unused().await.unwrap(); + drop(group); + drop(source); + + let track = resolved.track("log").unwrap(); + let subscribing = tokio::spawn(async move { track.subscribe(None).await }); + let mut next = replacement_dynamic + .requested_track() + .await + .unwrap() + .resolving_start() + .accept(None); + next.start_at(0).unwrap(); + let mut subscription = subscribing.await.unwrap().unwrap(); + let mut reading = subscription.recv_group().await.unwrap().unwrap(); + for expected in [b"a", b"b", b"c"] { + assert_eq!(&reading.read_frame().await.unwrap().unwrap().payload[..], expected); + } + } + /// The same holds for a reader returning to a parked track: its warm cache /// does not stand in for the copy it is waiting on. #[tokio::test] diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 4669dd10234..eb8fca98509 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -250,10 +250,10 @@ impl ResumeState { /// Where the logical track continues past the exclusive group `boundary` of segment /// `id`, below the reader's `cap`: the start of the first group the later segments - /// serve there. `None` while none is cached, or it has no frame yet. + /// serve there. A draining reader's own segment may already have been pruned. fn successor(&self, id: u64, boundary: u64, cap: Option) -> Option { - let index = self.segments.iter().position(|segment| segment.id == id)?; - served_start(&self.segments[index + 1..], boundary, cap) + let index = self.segments.iter().position(|segment| segment.id > id)?; + served_start(&self.segments[index..], boundary, cap) } /// Append a segment serving the track from `start` onward, capping (or replacing) @@ -3303,6 +3303,49 @@ mod test { assert_eq!(replayed, vec![0, 1, 2, 3], "a backlog inside the budget crosses whole"); } + #[tokio::test] + async fn unstamped_successor_segment_keeps_the_previous_group_unbounded() { + let (mut a, a_read) = track_pair("a"); + let (b, b_read) = track_pair("b"); + let (mut c, c_read) = track_pair("c"); + write_group_at(&mut a, 0, "a0", Duration::ZERO); + let _unstamped = b.create_group(1u64.into()).unwrap(); + write_group_at(&mut c, 2, "c2", Duration::from_secs(10)); + write_group_at(&mut c, 3, "c3", Duration::from_secs(20)); + let mut producer = Producer::new(); + producer.switch(a_read, None).unwrap(); + producer.switch(b_read, Position::group(1)).unwrap(); + producer.switch(c_read, Position::group(2)).unwrap(); + let mut sub = producer.consume().subscribe(None); + assert_eq!( + recv(&mut sub), + 0, + "the unstamped successor must not borrow segment C's start" + ); + } + + #[tokio::test] + async fn pruned_segment_boundary_is_judged_against_later_segments() { + let (mut a, a_read) = track_pair("a"); + let mut producer = Producer::new(); + producer.switch(a_read, None).unwrap(); + let mut sub = producer.consume().subscribe(None); + // Keep A's cursor draining while its newest group advances beyond the late boundary group. + write_group_at(&mut a, 0, "a0", Duration::ZERO); + assert_eq!(recv(&mut sub), 0); + write_group_at(&mut a, 3, "past-boundary", Duration::from_secs(3)); + for sequence in 3..=(2 + MAX_SEGMENTS as u64) { + let (mut track, consumer) = track_pair("later"); + producer.switch(consumer, Position::group(sequence)).unwrap(); + write_group_at(&mut track, sequence, "later", Duration::from_secs(sequence * 10)); + assert_eq!(recv(&mut sub), sequence); + } + assert!(producer.state.read().pruned.is_some()); + // A's boundary group arrives after A was pruned; it is stale against group 3's start. + write_group_at(&mut a, 2, "a2", Duration::from_secs(2)); + recv_pending(&mut sub); + } + /// A segment's track never sees the groups of the segments after it: its own edge /// freezes once a takeover caps it, and its last group has no successor there. /// Both spliced cursors judge its backlog as one plain track holding the same groups diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 10aac201e1e..d7d4f055a60 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -575,8 +575,8 @@ impl TrackState { /// The first servable group's start in `from..cap`, with the slot identity a later /// judgment needs to tell that group from whatever replaces it. `None` when no such - /// group is cached or it has no frame yet: an unstamped successor leaves reach - /// unbounded, and this does not skip past it to a later group. + /// group is cached. An unstamped successor still returns its identity so a wrapping + /// splice does not skip past it to a later segment's stamped group. fn served_start(&self, from: u64, cap: Option) -> Option { let slot = self .lookup @@ -587,7 +587,7 @@ impl TrackState { Some(ServedStart { sequence: slot.group.sequence, stamp: slot.stamp, - timestamp: slot.group.timestamp()?, + timestamp: slot.group.timestamp(), }) } @@ -3349,7 +3349,7 @@ impl PartialEq for LiveEdge { struct ServedStart { sequence: u64, stamp: u32, - timestamp: Timestamp, + timestamp: Option, } /// A successor pushed onto another track's cursor. The timestamp alone is not enough: @@ -3358,7 +3358,7 @@ struct ServedStart { #[derive(Clone)] pub(crate) struct Successor { sequence: u64, - timestamp: Timestamp, + timestamp: Option, stamp: u32, track: kio::ConsumerWeak, } From ece7e572c3bf626f945da64bd76ed8c9c6e7c6b2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 06:15:14 -0700 Subject: [PATCH 003/128] chore(quest): one first-hop rule for anonymous and named fronts (#4498) Co-authored-by: Claude Opus 5.5 --- quest/m1/cluster-publisher-in-place.md | 27 +++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/quest/m1/cluster-publisher-in-place.md b/quest/m1/cluster-publisher-in-place.md index 1b46dacb42a..56031a7f1be 100644 --- a/quest/m1/cluster-publisher-in-place.md +++ b/quest/m1/cluster-publisher-in-place.md @@ -31,6 +31,16 @@ qualifying once its route's first hop changes (`qualifies` in it, which stops new requests while its live copies play out. Draining needs no abort plumbing and no draft narrowing. +Decided 2026-09-29 by the maintainer: one rule for both kinds of front. A +front never serves through a publisher other than the one it started with. +A named front may still resume through another route from its own +publisher, as lite allows; once none remains it ends. An anonymous front has +no publisher to match, so a first-hop change on its route ends it. Either +way in-flight tracks drain and new requests get a fresh front. Why: pinning +an anonymous front to its route id rather than a publisher is an +implementation detail, and it should not let a new publisher inherit the old +broadcast's track info. + Decided 2026-09-29: accept the compatibility break. Released moq-net (0.3.5 and later) refuses a first-hop REQUEST_UPDATE with a retry interval of 0, which leaves a moved publisher withdrawn on that session during a rolling @@ -51,11 +61,13 @@ withdraw fallback and no negotiation. refusing it: `run_publish_namespace_updates` in `rs/moq-net/src/ietf/subscriber.rs` and `runPublishNamespace` in `js/net/src/ietf/subscriber.ts` close the stream today. -- Rust model: an anonymous front (first hop 0) is pinned to its route - (`Pin::Route`), so it keeps taking new requests when that route's first hop - changes to a named publisher, pairing the old broadcast's cached track - metadata with the new publisher. End it on a first-hop change like a named - front, so its copies drain and new requests get a fresh front. +- Rust model: end an anonymous front on a first-hop change, removing an + accidental asymmetry. A named front is pinned by publisher + (`Pin::Publisher`), so a first-hop update disqualifies that route and the + front resumes through another route from its publisher, or ends. An anonymous + front (first hop 0) is pinned to a route id (`Pin::Route`), which an + in-place update keeps, so today it goes on serving new requests through the + new publisher with the old broadcast's cached track info. - JS lite `js/net/src/lite/subscriber.ts`: a different first hop calls `retract()` and announces again, so a forwarding relay withdraws the namespace. Emit an in-place update instead. In-flight subscriptions drain @@ -73,8 +85,9 @@ withdraw fallback and no negotiation. in-flight subscription keeps receiving the old publisher's groups until that copy ends and never receives a group from the new one; a request after the update resolves through the new publisher without the old - publisher's track info. Cover an anonymous (hop 0) to named change, and a - lite ANNOUNCE_UPDATE in JS. Run `just test interop --all`. + publisher's track info. Cover an anonymous (hop 0) to named change, a named + front that resumes through a remaining route from its own publisher and + never through the new one, and a lite ANNOUNCE_UPDATE in JS. Run `just test interop --all`. Public API: none. Wire: the cluster extension's update semantics change (no message or parameter changes), breaking first-hop updates toward released From 6a01640911bcf88f685f324c4c1902f778a3f8e0 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 06:34:47 -0700 Subject: [PATCH 004/128] fix(net): cancel an unwanted lite track still waiting on TRACK_INFO (#4494) Co-authored-by: Claude Opus 5.5 --- quest/m1/README.md | 1 + quest/m1/request-stream-serve.md | 43 ++++++++++++++++ rs/moq-net/src/lite/publisher.rs | 69 +++++++++++++++++++++++++ rs/moq-net/src/lite/subscriber.rs | 73 +++++++++++++++++++++++++++ rs/moq-net/tests/mesh_withdraw.rs | 14 +---- rs/moq-net/tests/support/harness.rs | 12 +++++ rs/moq-net/tests/track_info_cancel.rs | 66 ++++++++++++++++++++++++ 7 files changed, 265 insertions(+), 13 deletions(-) create mode 100644 quest/m1/request-stream-serve.md create mode 100644 rs/moq-net/tests/track_info_cancel.rs diff --git a/quest/m1/README.md b/quest/m1/README.md index 6641a45faea..bfd771be853 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -41,6 +41,7 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [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 - [FIN wait expiry](/quest/m1/fin-wait-expiry.md) - a group awaiting its FIN ack still expires and follows priority updates on lite and IETF - [Cross-relay bursts](/quest/m1/cross-relay-bursts.md) - bursty small-group tracks cross two relays without lost groups, unanswered FETCHes, or stalls +- [Request stream cancel](/quest/m1/request-stream-serve.md) - a lite publisher stops resolving a SUBSCRIBE or FETCH once the requester FINs or resets, through one wrapper that owns every request stream's reader - [JS closed-track leak](/quest/m1/js-closed-track-leak.md) - on dev, a subscriber that joins a closed JS track with unlimited retention is released instead of cached forever - [Session death parity](/quest/m1/session-death.md) - a local close ends tracks cleanly in both languages, and JS group readers see the session's error on session death - [Watch video guards](/quest/m1/watch-video-guards.md) - promoting a video track holds the last picture, and an older group never reaches the codec between live deltas diff --git a/quest/m1/request-stream-serve.md b/quest/m1/request-stream-serve.md new file mode 100644 index 00000000000..287deadb3db --- /dev/null +++ b/quest/m1/request-stream-serve.md @@ -0,0 +1,43 @@ +# [M] Lite request streams stop when the requester leaves + +## Goal + +A lite publisher stops resolving a SUBSCRIBE or FETCH as soon as the +requester closes its send direction, by FIN or reset, as TRACK already does +since #4494 (the draft ends a transaction when either side closes), so an +abandoned request releases its upstream lookup along the whole mesh. Serving +a request stream can't forget that watch: the handlers for TRACK, SUBSCRIBE, +and FETCH never hold the reader while they wait. + +## Plan + +`TrackInfoServe`, `SubscribeServe`, and `FetchServe` in +`rs/moq-net/src/lite/publisher.rs` each repeat the same decode, origin, and +broadcast steps, the same error classification and `abort`, and only +`TrackInfoServe` watches the reader for a FIN or reset. SUBSCRIBE waiting in +`Request` or `Confirm`, and FETCH waiting in `Request` or `Fetch`, pin the +upstream lookup for a requester that already left. + +Share one request-stream wrapper that owns the reader: it decodes the +message, then drives a per-kind handler that gets only the writer, watching +the reader for a FIN or reset for the whole wait. Pending data is not a close: +SUBSCRIBE forwards each SUBSCRIBE_UPDATE to its handler, and only a FIN or a +read error ends the handler. Fold the origin and broadcast steps into one shared +resolve step, so each state enum loses its `Hop` and `Request` variants. + +Rejected: a generic `kio::until(task, scope)`. The interest signal is owned +by the task itself (the reader, a `track::Request`), it covers one phase +rather than the whole task, and cancelling a track is a commit that can lose +to returning demand (`reject_unused`). Those are moq-net concerns, so the +guarantee comes from ownership in moq-net, not a kio combinator. The lite and +IETF subscribers keep their inline `poll_unused` checks. + +Tests: a SUBSCRIBE and a FETCH whose requester FINs or resets while the publisher +waits on the broadcast leave the upstream request unused, over real lite-05 +and lite-06 sessions like `tests/track_info_cancel.rs`. + +Public API: none. Wire: none. + +## Related + +- [Cross-relay bursts](/quest/m1/cross-relay-bursts.md) - unanswered FETCHes across relays, where an abandoned request pinning its lookup would show up diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 7a3d5ccb25e..88fca60ca6f 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -959,6 +959,20 @@ impl TrackInfoServe { fn poll_serve(&mut self, waiter: &kio::Waiter) -> Poll> { loop { + // While the lookup runs the requester sends nothing, so its send side closing, + // by FIN or reset, means it stopped waiting. Drop the lookup then, so the + // abandonment reaches our own upstream instead of pinning it for an answer + // nobody reads. (Once answered, its FIN is the normal end; `Finish` waits on it.) + if matches!( + self.state, + TrackInfoState::Hop { .. } | TrackInfoState::Request { .. } | TrackInfoState::Query { .. } + ) { + let stream = self.stream.as_mut().expect("stream present"); + let mut cx = Context::from_waker(waiter.waker()); + if let Poll::Ready(res) = stream.reader.poll_closed(&mut cx) { + return Poll::Ready(Err(res.err().unwrap_or(Error::Cancel))); + } + } match &mut self.state { TrackInfoState::Decode => { let stream = self.stream.as_mut().expect("stream present"); @@ -3702,4 +3716,59 @@ mod tests { assert_eq!(probes[0].bitrate, Some(1_000_000)); assert_eq!(probes[1].bitrate, None); } + + /// A requester that FINs its TRACK request before the answer has terminated the + /// transaction (moq-lite: closing the send direction ends the stream), so the + /// lookup ends rather than pinning an upstream request nobody will read. + #[tokio::test] + async fn track_info_ends_when_the_requester_finishes() { + use crate::coding::Encode; + use crate::lite::test_transport::ScriptedSession; + + let origin = crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(); + let broadcast = origin.create_broadcast("room").unwrap(); + // Held, never polled: the track request stays unanswered. + let _dynamic = broadcast.dynamic(); + broadcast.announce(Default::default()).unwrap(); + + let peer_setup = crate::lite::PeerSetup::default(); + peer_setup.set(crate::lite::Setup::default()); + let (_, goaway) = crate::goaway::Handle::new(true); + let publisher = Publisher::new(PublisherConfig { + runtime: crate::time::Clock::tokio(), + session: ScriptedSession::new(Vec::new()), + origin: origin.consume(), + version: Version::Lite06, + peer_setup, + goaway, + peer_hop: None, + }); + + let mut request = Vec::new(); + lite::Track { + broadcast: crate::Path::new("room"), + track: "video".into(), + } + .encode(&mut request, Version::Lite06) + .unwrap(); + + for (finished, session) in [ + (false, ScriptedSession::new(request.clone())), + (true, ScriptedSession::eof(request.clone())), + ] { + let mut session = session; + let (send, recv) = futures::future::poll_fn(|cx| { + ::poll_open_bi(&mut session, cx) + }) + .await + .unwrap(); + let stream = Stream:: { + writer: Writer::new(send, Version::Lite06), + reader: crate::coding::Reader::new(recv, Version::Lite06), + }; + let mut serve = TrackInfoServe::new(publisher.shared.clone(), stream).unwrap(); + let ended = serve.poll(&kio::Waiter::noop()).is_ready(); + assert_eq!(ended, finished, "finished={finished}"); + } + } } diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index c6944a8e492..a648b2f2c84 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -1571,6 +1571,65 @@ mod tests { ); } + /// A track still waiting on TRACK_INFO ends once nobody wants it, whether its TRACK + /// stream never opened (the peer's stream credit is spent), its request is stuck in + /// send, or its peer never answers. + /// Otherwise every request a relay's front abandons (a failover, a reader leaving) + /// holds a task, a stream, and the track until the peer answers, which may be never. + #[tokio::test] + async fn an_unused_track_stops_waiting_for_info() { + // A closed gate holds the TRACK request in its send; an open one sends it to a + // peer that never answers. + let (closed, open) = (kio::Producer::new(false), kio::Producer::new(true)); + for (stage, session) in [ + ("open", SinkSession::default()), + ("send", SinkSession::gated_bi(closed.consume())), + ("read", SinkSession::gated_bi(open.consume())), + ] { + let subscriber = Subscriber::new(SubscriberConfig { + runtime: crate::time::Clock::tokio(), + session, + origin: origin::Config::new(crate::Hop::new(1).unwrap()).produce(), + recv_bandwidth: None, + version: VERSION, + peer_setup: Default::default(), + peer_hop: None, + cost: None, + going_away: Default::default(), + }); + + let broadcast = crate::broadcast::Info::new().produce(); + let mut dynamic = broadcast.dynamic(); + let consumer = broadcast.consume(); + let mut waiting = Box::pin(consumer.track("video").unwrap().subscribe(None)); + assert!( + futures::poll!(waiting.as_mut()).is_pending(), + "{stage}: waiting on the publisher" + ); + let request = dynamic.requested_track().now_or_never().unwrap().expect("request"); + + let mut run = TrackServeRun::new( + TrackServe { + subscriber, + path: Path::new("room").to_owned(), + name: "video".to_string(), + }, + request, + ); + let waiter = kio::Waiter::noop(); + assert!( + kio::Task::poll(&mut run, &waiter).is_pending(), + "{stage}: waits while the track is wanted" + ); + + drop(waiting); + assert!( + kio::Task::poll(&mut run, &waiter).is_ready(), + "{stage}: an unused track kept waiting on TRACK_INFO" + ); + } + } + /// `establish` puts exactly one SUBSCRIBE on the wire, and the id is registered /// before any of it reaches the transport. /// @@ -3321,6 +3380,20 @@ impl kio::Task for TrackServeRun { loop { match &mut self.state { TrackRunState::Info { request, info } => { + // Nobody wants the track anymore (the origin failed over, the reader + // left): stop waiting on a peer that may never answer, which would + // otherwise hold this task, its TRACK stream, and the track for good. + // Dropping the fetch resets the stream. + let pending = request.as_ref().expect("request pending"); + if pending.poll_unused(waiter).is_ready() { + if pending.reject_unused(Error::Cancel) { + self.state = TrackRunState::Done; + return Poll::Ready(()); + } + // Demand returned in the gap and won inside `reject_unused`: poll + // again so the unused wait is armed for when it leaves. + continue; + } let res = ready!(info.poll_fetch(&self.serve, waiter)); let request = request.take().expect("request pending"); match res { diff --git a/rs/moq-net/tests/mesh_withdraw.rs b/rs/moq-net/tests/mesh_withdraw.rs index 1ce99301421..6d91c46a8f3 100644 --- a/rs/moq-net/tests/mesh_withdraw.rs +++ b/rs/moq-net/tests/mesh_withdraw.rs @@ -10,7 +10,7 @@ mod support; use std::{collections::HashMap, time::Duration}; use moq_net::{Hop, Version, announce, broadcast, origin}; -use support::harness::{MockConnectOptions, MockPair, connect_mock}; +use support::harness::{MockPair, peer}; fn produce_origin(hop: u64) -> origin::Producer { let (producer, driver) = origin::Producer::new(origin::Config::new(Hop::new(hop).unwrap())); @@ -18,18 +18,6 @@ fn produce_origin(hop: u64) -> origin::Producer { producer } -/// Peer two relays the way `moq-relay`'s cluster does: one session, both directions. -async fn peer(version: Version, a: &origin::Producer, b: &origin::Producer) -> MockPair { - let a = a.clone().peer(); - let b = b.clone().peer(); - let mut options = MockConnectOptions::new(version); - options.client_publish = Some(a.consume().with_hidden(true)); - options.client_subscribe = Some(a); - options.server_publish = Some(b.consume().with_hidden(true)); - options.server_subscribe = Some(b); - connect_mock(options).await -} - /// Every update per prefix until the cursor goes quiet. Time is paused, so the /// timeout fires only once every task is idle. async fn drain(announced: &mut announce::Consumer) -> HashMap> { diff --git a/rs/moq-net/tests/support/harness.rs b/rs/moq-net/tests/support/harness.rs index 4cd2cf254f0..2c4db0b07d3 100644 --- a/rs/moq-net/tests/support/harness.rs +++ b/rs/moq-net/tests/support/harness.rs @@ -114,3 +114,15 @@ pub async fn connect_mock(opts: MockConnectOptions) -> MockPair { server_transport: transports.1, } } + +/// Peer two relays the way `moq-relay`'s cluster does: one session, both directions. +pub async fn peer(version: Version, a: &origin::Producer, b: &origin::Producer) -> MockPair { + let a = a.clone().peer(); + let b = b.clone().peer(); + let mut options = MockConnectOptions::new(version); + options.client_publish = Some(a.consume().with_hidden(true)); + options.client_subscribe = Some(a); + options.server_publish = Some(b.consume().with_hidden(true)); + options.server_subscribe = Some(b); + connect_mock(options).await +} diff --git a/rs/moq-net/tests/track_info_cancel.rs b/rs/moq-net/tests/track_info_cancel.rs new file mode 100644 index 00000000000..1f8be9be935 --- /dev/null +++ b/rs/moq-net/tests/track_info_cancel.rs @@ -0,0 +1,66 @@ +//! A track request nobody wants anymore is cancelled all the way to the publisher. +//! +//! Until a publisher answers TRACK_INFO, each relay on the path holds a task, a TRACK +//! stream, and the track for the request. When the reader gives up, every hop must +//! let go; otherwise a peer that never answers (one still hunting for a route, or +//! with its stream credit spent) pins them for good, and a relay retrying across +//! routes accumulates them until it runs out of memory. + +mod support; + +use std::time::Duration; + +use moq_net::{Hop, Version, origin}; +use support::harness::peer; + +fn produce_origin(hop: u64) -> origin::Producer { + let (producer, driver) = origin::Producer::new(origin::Config::new(Hop::new(hop).unwrap())); + tokio::spawn(support::harness::run(driver)); + producer +} + +/// `relays` relays between the publisher and the reader. +async fn abandoned_request_reaches_the_publisher(version: &str, relays: u64) { + let version: Version = version.parse().unwrap(); + let nodes: Vec<_> = (1..=relays + 1).map(produce_origin).collect(); + let mut _pairs = Vec::new(); + for pair in nodes.windows(2) { + _pairs.push(peer(version, &pair[0], &pair[1]).await); + } + + let broadcast = nodes[0].create_broadcast("room").unwrap(); + let mut dynamic = broadcast.dynamic(); + broadcast.announce(Default::default()).unwrap(); + tokio::time::sleep(Duration::from_secs(1)).await; + + let consumer = nodes[relays as usize] + .consume() + .request_broadcast("room") + .await + .unwrap(); + let mut waiting = Box::pin(consumer.track("video").unwrap().subscribe(None)); + let request = tokio::select! { + request = dynamic.requested_track() => request.expect("the request reaches the publisher"), + _ = &mut waiting => panic!("nothing answered the track"), + }; + + // The publisher never answers; the reader gives up. + drop(waiting); + tokio::time::timeout(Duration::from_secs(5), kio::wait(|waiter| request.poll_unused(waiter))) + .await + .unwrap_or_else(|_| panic!("{version:?} over {relays} relays: the publisher's request is still wanted")); +} + +#[tokio::test(start_paused = true)] +async fn abandoned_request_reaches_the_publisher_lite05() { + for relays in [1, 2] { + abandoned_request_reaches_the_publisher("moq-lite-05", relays).await; + } +} + +#[tokio::test(start_paused = true)] +async fn abandoned_request_reaches_the_publisher_lite06() { + for relays in [1, 2] { + abandoned_request_reaches_the_publisher("moq-lite-06", relays).await; + } +} From 82fd85009ec604796354883e289e82b2b59f713d Mon Sep 17 00:00:00 2001 From: t0ms Date: Tue, 29 Sep 2026 17:20:00 +0100 Subject: [PATCH 005/128] quest: plan per-program SI and TS PSI reassembly (#4507) Co-authored-by: Cursor Co-authored-by: Luke Curley Co-authored-by: Claude Opus 5.5 --- quest/m1/README.md | 1 + quest/m1/ts-psi-reassembly.md | 59 +++++++++++++++++++++++++++++++++++ quest/m2/README.md | 1 + quest/m2/ts-program-si.md | 56 +++++++++++++++++++++++++++++++++ 4 files changed, 117 insertions(+) create mode 100644 quest/m1/ts-psi-reassembly.md create mode 100644 quest/m2/ts-program-si.md diff --git a/quest/m1/README.md b/quest/m1/README.md index bfd771be853..2521a20972b 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -61,6 +61,7 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [TS export jitter](/quest/m1/ts-export-jitter.md) - the video reorder bound follows later catalogs and the declared reorder depth, so a late B-frame never reorders TS output; an undeclared stream can reorder once per new maximum depth - [TS import shared shift](/quest/m1/ts-import-shared-shift.md) - unflagged loop wraps move audio and video by one shift, so A/V sync holds across wraps - [ffmpeg muxdelay](/quest/m1/ts-publish-muxdelay.md) - the documented MPEG-TS publish line adds `-muxdelay 0`, so quiet audio is not clumped +- [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) - `import ts` reads a PAT or PMT that spans packets or follows a nonzero pointer_field instead of aborting - [Same-hop importers](/quest/m1/hop-aligned-import.md) - importers sharing a `--hop` and fed one stream publish identical groups and timestamps, so failover survives - [PipeWire duplicate cameras](/quest/m1/pipewire-dup-cameras.md) - a webcam lists once with PipeWire enabled - [Catalog wall clock](/quest/m1/catalog-wall-clock.md) - `Clock::wall_clock` keeps the catalog's full precision instead of truncating to milliseconds diff --git a/quest/m1/ts-psi-reassembly.md b/quest/m1/ts-psi-reassembly.md new file mode 100644 index 00000000000..a6a7b6cf67e --- /dev/null +++ b/quest/m1/ts-psi-reassembly.md @@ -0,0 +1,59 @@ +# [L] TS PSI reassembly + +## Goal + +The MPEG-TS importer reads a PAT or PMT whose section spans several packets or +starts after a nonzero `pointer_field`, instead of aborting the import. Today +the `mpeg2ts` 0.6.1 reader parses PSI from a single packet and rejects a nonzero +`pointer_field`, and its error ends the whole import, so a valid long PMT (many +audio languages, long descriptors) or a PAT with more than about 40 programs +cannot be imported. `ts::programs()` finds such a PAT too. + +## Plan + +Settled decisions: + +- moq-mux owns the packet demux, and the import stops using + `mpeg2ts::ts::TsPacketReader`. It can't be fixed from outside: the reader's + PAT and PMT parsers are private to the crate, and it learns PES PIDs only + from PMTs it parsed itself. Feeding it a synthesized one-packet PMT to + register PIDs was rejected as fragile coupling, and fixing it upstream in + sile/mpeg2ts was rejected as slower and outside this repository. Switching to + `mpeg2ts-reader` was rejected too: it is a callback-driven demux framework + (last release January 2025), and moq-mux already owns the hard part in + `SectionReassembler`. Owning the demux also deletes the importer's + workarounds for the reader: the `Feed` mutex it reads through, and the + `pmt_pids`/`streams` gate that keeps unknown PIDs away from it. `mpeg2ts` + stays for export, tests, and plain types such as `StreamType`. +- PID 0 and every PMT PID go through the existing `SectionReassembler`, which + already handles `pointer_field`, split headers, and continuity gaps. The + PAT (`transport_stream_id`, version, program loop, possibly several sections) + and the PMT (program number, PCR PID, program descriptors, and the + elementary-stream loop with descriptors) are parsed in moq-mux. PES is + routed by the PIDs of the parsed PMT, and its header (PTS/DTS) is also parsed + in moq-mux. +- Each reassembled section's CRC-32/MPEG-2 is checked with the `crc` crate. + [Per-program SI](/quest/m2/ts-program-si.md) needs the same dependency, and + whichever change lands first adds it. A section with a bad CRC is dropped and + the last good table stays in force, so the import continues; it no longer + aborts as the `mpeg2ts` reader does. +- Each dropped section is counted per PID in `Import::stats`, so a corrupt feed + is visible rather than silently held on a stale table. `Stats` is + `#[non_exhaustive]`, so the new field is additive; its docs (today "frame + sync the demuxed audio streams lost") and `is_empty` widen to cover it, and + `moq-cli`'s `log_stats` reports it. Name it so the + [TR 101 290 plan](/quest/m2/1838-tr-101-290-monitoring-requirements-broadcast-contribution.md) + adopts it as `CRC_error`. +- `ts::programs()` reads through the same PAT path, so a PAT spanning packets + is found before any program publishes. +- One quest, because the demux refactor alone changes nothing observable. + +Keep every existing TS import test and fixture passing unchanged. Add tests for +a PMT spanning two packets, a PAT behind a nonzero `pointer_field`, a +multi-packet PAT with enough programs to need it (read by `ts::programs()` and +by `with_program`), and a PMT with a corrupt CRC that is dropped and counted +while the import keeps its previous PMT. + +## Required + +- [moq import ts: select programs](/quest/m1/ts-programs.md) - `ts::programs()` and `with_program`, which this quest's PAT path and tests build on diff --git a/quest/m2/README.md b/quest/m2/README.md index 92416e8d45b..44392617586 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -75,6 +75,7 @@ upstream release waits in [m4](/quest/m4/README.md). - [Send buffer pools](/quest/m2/quic-buffer-pool.md) - whether pooled send buffers beat Bytes in the stream send path - [AF_XDP UDP path](/quest/m2/af-xdp.md) - the kernel-bypass verdict on today's virtio hosts that gates DPDK - [GOP overhead](/quest/m2/gop-overhead.md) - price the I-frames a short GOP pays for, deciding whether a long GOP plus a keyframe request is worth designing +- [Per-program SI](/quest/m2/ts-program-si.md) - a selected TS program's broadcast carries only its own service's SDT and EIT - [#1838](/quest/m2/1838-tr-101-290-monitoring-requirements-broadcast-contribution.md) - plan TR 101 290 stream-health monitoring into implementation quests - [Teleoperation](/quest/m2/teleop/README.md) - MoQ carries robot video down and control up on one session as a library capability - [SIP media stack](/quest/m2/sip-stack.md) - terminate one inbound SIP audio call leg and expose it as Opus frames diff --git a/quest/m2/ts-program-si.md b/quest/m2/ts-program-si.md new file mode 100644 index 00000000000..7941d1a5837 --- /dev/null +++ b/quest/m2/ts-program-si.md @@ -0,0 +1,56 @@ +# [M] Per-program SI + +## Goal + +When an MPEG-TS import selects a program (`ts::Import::with_program`, so +`moq import ts --program ` and each broadcast of `--program all`), that +program's broadcast carries SI describing only its own service. Other services' +EIT sub-tables are dropped, and the SDT for this transport stream is rewritten +to list only the selected service. Network-wide tables (NIT, BAT, TDT/TOT, SDT +other, EIT other) pass through unchanged. An import without a selection does +no filtering by program and keeps today's capture behavior. + +## Plan + +Settled decisions: + +- Filter at import, in `si::Capture`, before a generation commits, so a + program's SI tracks never carry another service's bytes and exporters stay + unchanged. Filtering at export was rejected: every subscriber would still + receive the whole multiplex's schedule. +- Filter only under an explicit selection. A single-program input whose SDT + lists extra services is left alone, because default capture keeps the + sections it accepts verbatim. +- EIT actual (`table_id` 0x4E and 0x50..=0x5F): keep a sub-table only when its + `table_id_extension` (the service_id) is the selected program_number. Whole + sub-tables are dropped; nothing is rewritten. EIT other (0x4F and + 0x60..=0x6F) describes other transport streams and passes through. +- SDT actual (`table_id` 0x42 on PID 0x11): its one sub-table lists every + service, so once a generation is complete, rebuild it as a single section + (`section_number` and `last_section_number` 0) holding the selected service's + loop entry, wherever it sat in the source's sections. Keep the header fields + (transport_stream_id, version_number, original_network_id), recompute + `section_length`, and write a fresh CRC-32/MPEG-2 using the `crc` crate, which + is already in `Cargo.lock`, as a direct moq-mux dependency rather than a + hand-written table. [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) + needs it too, and whichever change lands first adds it. +- When the SDT has no entry for the selected service, carry no SDT actual rather + than fabricating a table the source never gave for this service. If a later + version drops the service, the next snapshot retires the SDT captured before + it, and its catalog entry goes too if nothing else is left on it. A later + version that lists the service again is captured normally. +- A `(PID, table_id)` whose every sub-table is filtered away gets no catalog + `mpegts.si` entry or track. +- The same change updates the program-selection paragraph in `doc/bin/cli.md` + and the `si.rs` module docs; no new page is needed. + +Test with a synthetic two-service multiplex whose SDT lists both services +across two sections, with EIT present/following for each. Each selected import +carries one SDT entry with a valid CRC and only its own EIT; an unselected +import keeps the sections verbatim; a selection missing from the SDT carries +none; an SDT version that drops the selected service retires the earlier one; +and the re-exported TS still parses. + +## Required + +- [moq import ts: select programs](/quest/m1/ts-programs.md) - `ts::Import::with_program`, which this filtering hangs off From 6b93b304334d2ee5ec835fc3bcd31f6972bc6082 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 09:30:47 -0700 Subject: [PATCH 006/128] chore(quest): abandon the live-marker app quest (#4512) Co-authored-by: Claude Opus 5.5 --- quest/m1/README.md | 1 - quest/m1/announce-live-apps.md | 36 ---------------------------------- 2 files changed, 37 deletions(-) delete mode 100644 quest/m1/announce-live-apps.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 2521a20972b..2d07dbaac0a 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -30,7 +30,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Close codes](/quest/m1/close-codes.md) - a client sees the peer's application close code over WebSocket and raw QUIC, like WebTransport - [Raw stream codes](/quest/m1/raw-stream-codes.md) - raw QUIC stream resets and stops carry the application's code, not an HTTP/3-mapped one - [WebTransport close upstream](/quest/m1/wt-close-upstream.md) - web-transport-moq delivers the close capsule itself, and moq-tokio's `CLOSE_LINGER` is deleted -- [Live in apps](/quest/m1/announce-live-apps.md) - the demo and `@moq/room` show "no broadcasts" from the `live` marker, which waits for the first session on page load - [IETF hidden default](/quest/m1/ietf-hidden-default.md) - a moq-transport peer without the MoQ Hidden option is advertised hidden namespaces; one with it filters per subscription - [Watch refusal](/quest/m1/watch-refusal.md) - `` shows an origin refusal as an error instead of sitting offline - [moqsink recoverable errors](/quest/m1/moqsink-keyframe-latch.md) - a leading delta or a timestamp rewind drops frames until a keyframe instead of invalidating a moqsink pad diff --git a/quest/m1/announce-live-apps.md b/quest/m1/announce-live-apps.md deleted file mode 100644 index c6f99695167..00000000000 --- a/quest/m1/announce-live-apps.md +++ /dev/null @@ -1,36 +0,0 @@ -# [M] Apps show "no broadcasts" from the live marker - -## Goal - -A browser page listing broadcasts shows an empty state once the relay has -said there are none, never a spinner that never resolves and never a false -empty state before the first session answered. The demo watch page and -`@moq/room` use `@moq/net`'s `live` marker, and `@moq/net` settles when an -origin stream opened before the first connection goes live. - -## Plan - -- #4261 (on `dev`) adds the `live` event, and #4266 the same marker in the - bindings. Open #4384 renames the announce events to Start/Update/End/Live; - follow its names if it lands first. The consumers it touches - (`demo/web/src/index.ts`, `js/room/src/room.ts`, `js/watch/src/broadcast.ts`, - `js/moq-boy`) skip it today. -- Page load: an origin stream opened before any session connects has no - session to wait on, so today it goes `live` at once and broadcasts arrive - after it. Settled: the reconnect loop (`js/net/src/connection/reload.ts`), - which already answers requests through `expect()`, holds the marker until - its first session lands `live` or its first dial gives up. An empty list - then means the relay said so or is unreachable, which a UI can tell apart. - Once a session is up, its own `live` ends the hold: every wire guarantees - one (ANNOUNCE_OK, ANNOUNCE_INIT, or the quiet-stream fallback). A peer that - accepts the announce stream and never answers is a peer bug, so no extra - timeout. - Check whether Rust's reconnecting client has the same gap. -- Apps: loading before `live`, an explicit empty state after it with nothing - announced, and an error state when the connection gives up. Libraries - expose the state as a signal; wording stays in the demo. -- Tests: an origin stream opened before connect is not `live` until the first - session is; a connection that cannot connect ends the wait. - -Public API: when `@moq/net` emits `live` changes; any state signal on -`@moq/room` or `@moq/watch` is additive. Lands on `dev` with #4261. Wire: none. From 395a92cbd4e5706c50b6c9bae79e5dd2effbe37a Mon Sep 17 00:00:00 2001 From: t0ms Date: Tue, 29 Sep 2026 17:40:08 +0100 Subject: [PATCH 007/128] feat(mux): report every TS elementary stream's access units and quiet time (#4502) Co-authored-by: Claude Opus 5.5 --- Cargo.lock | 1 + doc/bin/cli.md | 8 + quest/m1/3489-ts-import-stream-liveness.md | 51 --- quest/m1/README.md | 1 - quest/m1/srt-import-stats.md | 6 +- quest/m1/ts-import-shared-shift.md | 1 - ...ing-requirements-broadcast-contribution.md | 4 - rs/moq-cli/Cargo.toml | 1 + rs/moq-cli/src/publish.rs | 135 ++++++-- rs/moq-mux/src/container/ts/import.rs | 296 +++++++++++++----- rs/moq-mux/src/container/ts/import_test.rs | 229 ++++++++++++++ rs/moq-mux/src/container/ts/mux_rate.rs | 4 +- 12 files changed, 569 insertions(+), 168 deletions(-) delete mode 100644 quest/m1/3489-ts-import-stream-liveness.md diff --git a/Cargo.lock b/Cargo.lock index 27c0076dfc7..2e88d5942d8 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4315,6 +4315,7 @@ dependencies = [ "tokio", "tower-http 0.7.1", "tracing", + "tracing-test", "url", "usage-rs", "winit", diff --git a/doc/bin/cli.md b/doc/bin/cli.md index d641191e07f..e8345ac1320 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -71,6 +71,14 @@ turn. The same flag on an elementary PID other than the program PCR PID, a continuity-counter gap, and the 33-bit timestamp rollover move no clock and declare nothing. FLV covers H.264 + AAC. +`import ts` samples each elementary stream's access-unit count once a second and +logs a stream whose count stopped advancing, with how long it has been quiet on +the program clock, once per silence. The mux can keep flowing, PCR and +continuity intact, around a PID that delivers nothing, and no transport check +downstream sees it. A sparse stream such as SCTE-35 goes quiet between cues, so +the line reports rather than alarms; `Import::stats` carries the same counters +for a caller that sets its own limit. + MPEG-TS export restarts its clock and table cadence after a declared marker, discarding the old mux buffer. The first new clock packet signals the break and stdout pacing re-anchors. Every rendition joins the new program generation; diff --git a/quest/m1/3489-ts-import-stream-liveness.md b/quest/m1/3489-ts-import-stream-liveness.md deleted file mode 100644 index 8107a665b5e..00000000000 --- a/quest/m1/3489-ts-import-stream-liveness.md +++ /dev/null @@ -1,51 +0,0 @@ -# [M] moq import ts: every elementary stream reports its access units and how long it has been quiet - -## Goal - -An operator polling `moq import ts` can tell that a specific PID stopped -delivering access units while the mux kept flowing. `Import::stats` carries a -row for every elementary stream, video and verbatim included, with the -published access-unit count and the current gap since the last one, measured -on the transport's own clock. No threshold and no warning: a sparse stream -such as SCTE-35 is legitimately quiet, so liveness is derived by whoever -alarms. Nothing changes in what is published or how tracks are mapped. - -## Plan - -Measured in #3489: a 60 s video outage behind a running mux passes every TR -101 290 P1 check, produces identical logs, and delivers a 57 s hole; only the -audio half is visible, late, through #3372's resync line. - -- `rs/moq-mux/src/container/ts/import.rs`: `Stream::stats` returns `None` - for `H264`, `H265`, `Opus`, `Verbatim`, and `Clock`, and `Stats` documents - that an absent PID is healthy. Give every elementary stream a row and - retire the absence contract; the `lost.then_some(stats)` gate goes with it. - `StreamStats` is `#[non_exhaustive]`, so the new fields are additive. -- Clock: the packet loop reads the adaptation field for the discontinuity - indicator and skips the PCR bytes; parse the PCR there. `last_pts` advances - on video PES only and freezes with the very stream this must catch. Record - the clock at each access unit in `flush`; the gap is the current clock - minus that mark. Reuse the `discontinuity_indicator` helper the timebase-break - path already shares with duplicate detection. -- Surface: `rs/moq-cli/src/publish.rs` `log_stats` gains a line for a stream - whose count stopped advancing across a sample, distinct from the audio - resync message. The SRT gateway reports nothing today; that surface is - [SRT import stats](/quest/m1/srt-import-stats.md). -- Name and shape the counters so the TR 101 290 quest adopts them as its - `PID_error` check, and leave the catalog `stalled` bit alone: the importer - already sets it for a quiet video PID (`Stream::tick` after each decode - batch, #3630). These counters add no timeout; anything that must bound a - wait on a silent PID (the shared-shift quest) brings its own. -- Tests with the issue's stimulus shape: suppress one PID's PES while keeping - its PCR and continuity legal, assert the row's count stops and the gap - grows; audio and SCTE-35 arms. - -## Closes - -- [#3489](https://github.com/moq-dev/moq/issues/3489) - close this issue when the quest finishes - -## Related - -- [SRT import stats](/quest/m1/srt-import-stats.md) - the same rows read from the SRT gateway -- [#1838](/quest/m2/1838-tr-101-290-monitoring-requirements-broadcast-contribution.md) - the monitoring model that subsumes this as `PID_error` -- [Client stats](/quest/m1/qos/stats/schema.md) - where per-rendition liveness rides a publisher's stats broadcast diff --git a/quest/m1/README.md b/quest/m1/README.md index 2d07dbaac0a..c2c0560e64e 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -167,7 +167,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [#3021](/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md) - GStreamer maps every pad onto one continuous broadcast clock across source restarts - [Export linger](/quest/m1/export-linger.md) - every `moq export` waits `--linger` for a broadcast to return, and exits 0 on a clean end and 1 on a drop - [TS byte schedule](/quest/m1/ts-export-byte-schedule.md) - moq export ts places PCRs and padding on the byte grid `mpegts.muxRate` implies, so a receiver can clock off arrival -- [#3489](/quest/m1/3489-ts-import-stream-liveness.md) - moq import ts: every elementary stream reports its access units and how long it has been quiet - [SRT import stats](/quest/m1/srt-import-stats.md) - the SRT gateway reports the same per-stream counters instead of nothing - [Text availability](/quest/m1/text-schema.md) - a text track publishes its own coverage index instead of copying the media timeline - [ID3 catalog section](/quest/m1/id3.md) - timed ID3 as a first-class container-neutral catalog section diff --git a/quest/m1/srt-import-stats.md b/quest/m1/srt-import-stats.md index 3460586d8be..448f8b214b0 100644 --- a/quest/m1/srt-import-stats.md +++ b/quest/m1/srt-import-stats.md @@ -14,8 +14,4 @@ most, and today `rs/moq-srt/src/ts.rs` only calls `decode`. - Share the logging presentation with `rs/moq-cli/src/publish.rs` where needed so the two front doors report the same rows. - Test: the SRT harness feeds the suppressed-PID stimulus from the TS - liveness quest and asserts the gateway reports the stalled row. - -## Required - -- [#3489](/quest/m1/3489-ts-import-stream-liveness.md) - the rows this forwards + import tests and asserts the gateway reports the stalled row. diff --git a/quest/m1/ts-import-shared-shift.md b/quest/m1/ts-import-shared-shift.md index e5c9190bd3b..2ae0bf33974 100644 --- a/quest/m1/ts-import-shared-shift.md +++ b/quest/m1/ts-import-shared-shift.md @@ -47,5 +47,4 @@ Guidance: ## Related -- [#3489](/quest/m1/3489-ts-import-stream-liveness.md) - per-PID liveness in the same importer; touches `Stream` but not the shift - [Remove live()](/quest/m1/remove-live.md) - deletes the restart anchor; a wrap shift stays input-derived diff --git a/quest/m2/1838-tr-101-290-monitoring-requirements-broadcast-contribution.md b/quest/m2/1838-tr-101-290-monitoring-requirements-broadcast-contribution.md index f77cafbf261..aa3957a1fa8 100644 --- a/quest/m2/1838-tr-101-290-monitoring-requirements-broadcast-contribution.md +++ b/quest/m2/1838-tr-101-290-monitoring-requirements-broadcast-contribution.md @@ -38,7 +38,3 @@ Questions the planning session must answer: ## Closes - [#1838](https://github.com/moq-dev/moq/issues/1838) - close this issue when the quest finishes - -## Related - -- [TS import liveness](/quest/m1/3489-ts-import-stream-liveness.md) - the stream-stall case this model names `PID_error` diff --git a/rs/moq-cli/Cargo.toml b/rs/moq-cli/Cargo.toml index 4078f83f2e7..14f91b13366 100644 --- a/rs/moq-cli/Cargo.toml +++ b/rs/moq-cli/Cargo.toml @@ -134,6 +134,7 @@ tempfile = { workspace = true } # `test-util` enables `tokio::time::pause` so the TS round-trip test simulates the # exporter drain timeouts instantly instead of waiting on the wall clock. tokio = { workspace = true, features = ["test-util"] } +tracing-test = { workspace = true, features = ["no-env-filter"] } [[bench]] name = "play_buffer" diff --git a/rs/moq-cli/src/publish.rs b/rs/moq-cli/src/publish.rs index 9ce2ebc93b7..00f193517c5 100644 --- a/rs/moq-cli/src/publish.rs +++ b/rs/moq-cli/src/publish.rs @@ -132,26 +132,62 @@ pub struct CaptureArgs { pub no_audio: bool, } -/// Report the streams whose frame-sync counters moved since `previous`, one line each. +/// How often `import ts` compares the importer's per-stream counters. /// -/// The importer already warns on each individual resync; this is the running total, which is -/// what an operator turns into a rate. -fn log_stats(latest: Option<&ts::Stats>, previous: Option<&ts::Stats>) { - let Some(latest) = latest else { - return; - }; - for (pid, stream) in &latest.streams { - if previous.and_then(|previous| previous.streams.get(pid)) == Some(stream) { - continue; +/// Long enough that every continuous stream delivers many access units in between, so a +/// count that did not move is a stream that stopped rather than one between frames. +const STATS_INTERVAL: std::time::Duration = std::time::Duration::from_secs(1); + +/// Logs what moved in the importer's per-stream counters from one sample to the next. +#[derive(Default)] +struct StatsLog { + previous: Option, + /// Streams already reported quiet, so a silence is logged when it starts and not again + /// until the stream has delivered. + quiet: std::collections::BTreeSet, +} + +impl StatsLog { + /// Compare a sample taken [`STATS_INTERVAL`] after the last. + fn sample(&mut self, latest: ts::Stats) { + self.sync(&latest); + for (pid, stream) in &latest.streams { + let previous = self.previous.as_ref().and_then(|previous| previous.streams.get(pid)); + if previous.is_none_or(|previous| previous.units != stream.units) { + self.quiet.remove(pid); + } else if self.quiet.insert(*pid) { + tracing::info!( + pid = *pid, + track = stream.track, + units = stream.units, + quiet = ?stream.quiet, + "elementary stream stopped delivering access units" + ); + } + } + self.previous = Some(latest); + } + + /// Report the streams whose frame-sync counters moved, one line each. + /// + /// The importer already warns on each individual resync; this is the running total, which + /// is what an operator turns into a rate. + fn sync(&self, latest: &ts::Stats) { + let lost = |stream: &ts::StreamStats| (stream.resyncs, stream.discarded, stream.unconfirmed); + for (pid, stream) in &latest.streams { + let previous = self.previous.as_ref().and_then(|previous| previous.streams.get(pid)); + if previous.map_or((0, 0, 0), lost) == lost(stream) { + continue; + } + tracing::info!( + pid = *pid, + track = stream.track, + resyncs = stream.resyncs, + discarded = stream.discarded, + unconfirmed = stream.unconfirmed, + "audio frame sync lost" + ); } - tracing::info!( - pid = *pid, - track = stream.track, - resyncs = stream.resyncs, - discarded = stream.discarded, - unconfirmed = stream.unconfirmed, - "audio frame sync lost" - ); } } @@ -184,8 +220,8 @@ impl PublishDecoder { Ok(()) } - /// Audio frame sync the decoder has lost so far, for the formats that scan for it. - /// `None` where the container frames audio explicitly and so can't lose sync. + /// What each elementary stream has delivered and the audio frame sync lost so far, for + /// the formats that report it. fn stats(&self) -> Option { match self { Self::Ts(d) => Some(d.stats()), @@ -436,10 +472,11 @@ async fn decode( ) -> anyhow::Result<()> { let mut buffer = bytes::BytesMut::new(); - // Damage reported so far, so only the change is logged. A live feed is + // Counters reported so far, so only the change is logged. A live feed is // diagnosed by the rate at which these climb, and stdin may never end, so // they have to surface as they accumulate rather than at exit. - let mut reported = decoder.stats(); + let mut log = StatsLog::default(); + let mut sampled = tokio::time::Instant::now(); // Run the read/decode loop so an error surfaces here rather than // dropping the decoder (and its tracks) with a bare Error::Dropped. @@ -452,10 +489,11 @@ async fn decode( } decoder.decode_chunk(&buffer)?; - let latest = decoder.stats(); - if latest != reported { - log_stats(latest.as_ref(), reported.as_ref()); - reported = latest; + if sampled.elapsed() >= STATS_INTERVAL { + sampled = tokio::time::Instant::now(); + if let Some(stats) = decoder.stats() { + log.sample(stats); + } } } } @@ -466,8 +504,11 @@ async fn decode( // a bare Error::Dropped. let outcome = result.and_then(|()| decoder.finish()); // The drain at end of input can publish a frame nothing vouched for, so the - // final snapshot is only complete after `finish`. - log_stats(decoder.stats().as_ref(), reported.as_ref()); + // final snapshot is only complete after `finish`. It covers less than an interval, so + // only the frame sync is compared. + if let Some(stats) = decoder.stats() { + log.sync(&stats); + } match outcome { Ok(()) => catalog.finish(), Err(err) => { @@ -881,6 +922,44 @@ mod tests { assert_eq!(last.audio.renditions.len(), 1, "the audio rendition is still listed"); } + /// A stream whose count stops across a sample is logged once, with its silence, and again + /// only after it has delivered in between; a stream that keeps counting never is, and + /// neither reports frame sync it never lost. + #[test] + #[tracing_test::traced_test] + fn stats_log_reports_a_stream_that_stopped() { + const VIDEO: u16 = 0x100; + const AUDIO: u16 = 0x101; + let sample = |video: u64, audio: u64| { + let mut stats = ts::Stats::default(); + for (pid, track, units) in [(VIDEO, ".avc3", video), (AUDIO, ".mp2", audio)] { + let mut stream = ts::StreamStats::default(); + stream.track = track; + stream.units = units; + stream.quiet = Some(Duration::from_millis(40)); + stats.streams.insert(pid, stream); + } + stats + }; + + let mut log = StatsLog::default(); + for (video, audio) in [(10, 10), (10, 20), (10, 30), (11, 40), (11, 50)] { + log.sample(sample(video, audio)); + } + + logs_assert(|lines: &[&str]| { + let stopped: Vec<_> = lines + .iter() + .filter(|line| line.contains("stopped delivering access units")) + .collect(); + match stopped.as_slice() { + [first, second] if [first, second].iter().all(|line| line.contains("pid=256")) => Ok(()), + _ => Err(format!("expected two lines for the video PID, got {stopped:?}")), + } + }); + assert!(!logs_contain("audio frame sync lost"), "nothing lost frame sync"); + } + /// Read the first frame of a verbatim track back as raw bytes. async fn read_frame(consumer: &moq_net::broadcast::Consumer, name: &str) -> Vec { let track = consumer.track(name).unwrap().subscribe(None).await.unwrap(); diff --git a/rs/moq-mux/src/container/ts/import.rs b/rs/moq-mux/src/container/ts/import.rs index 0cfa35a5339..6b386339744 100644 --- a/rs/moq-mux/src/container/ts/import.rs +++ b/rs/moq-mux/src/container/ts/import.rs @@ -69,8 +69,10 @@ pub struct Import { pmt_pids: HashSet, /// Per elementary-stream-PID codec routing. streams: HashMap>, - /// Counters from audio routes a later PMT replaced, keyed by PID. + /// Counters from routes a later PMT replaced, keyed by PID. retired_stats: BTreeMap, + /// Access units per elementary stream, timed on the program clock. + liveness: Liveness, /// In-progress PES reassembly, keyed by elementary PID. pending: HashMap, /// Per elementary-stream-PID TS continuity state. @@ -161,6 +163,7 @@ impl Import { pmt_pids: HashSet::new(), streams: HashMap::new(), retired_stats: BTreeMap::new(), + liveness: Liveness::default(), pending: HashMap::new(), continuity: HashMap::new(), pcr_pid: None, @@ -289,15 +292,17 @@ impl Import { if self.pcr_pid.is_some_and(|p| p.as_u16() == pid) && pkt[1] & 0x80 == 0 { if discontinuity_indicator(&pkt) { self.timebase_break()?; - } else if self.supports_mpegts - && let Some(pcr) = pcr(&pkt) - && self.mux_rate.pcr(pcr) - { - self.record_mux_rate()?; + } else if let Some(pcr) = pcr(&pkt) { + self.liveness.pcr(pcr); + if self.supports_mpegts && self.mux_rate.pcr(pcr) { + self.record_mux_rate()?; + } } } if let Some(section) = self.sections.get_mut(&pid) { - self.published |= section.packet(&pkt, self.last_pts)?; + let units = section.packet(&pkt, self.last_pts)?; + self.published |= units > 0; + self.liveness.delivered(pid, units); continue; } // Intercept the standalone SI PIDs before the routing gate below drops them: @@ -385,6 +390,7 @@ impl Import { if self.pcr_pid != pmt.pcr_pid { self.pcr_pid = pmt.pcr_pid; // A new clock: the intervals straddling the switch measure nothing. + self.liveness.discontinuity(); if self.mux_rate.discontinuity() { self.record_mux_rate()?; } @@ -558,6 +564,9 @@ impl Import { if !matches!(stream, Stream::Ignored | Stream::Clock) { self.initialized = true; } + if !matches!(stream, Stream::Ignored) { + self.liveness.register(pid.as_u16()); + } self.streams.insert(pid, stream); self.continuity.entry(pid).or_default(); Ok(()) @@ -617,6 +626,7 @@ impl Import { descriptors, )?; self.sections.insert(pid.as_u16(), stream); + self.liveness.register(pid.as_u16()); self.initialized = true; tracing::debug!( pid = pid.as_u16(), @@ -693,6 +703,8 @@ impl Import { } if is_clock { + // Nothing is published, but each PES is a picture the source delivered. + self.liveness.delivered(pid.as_u16(), 1); return Ok(()); } @@ -737,7 +749,9 @@ impl Import { let Some(stream) = self.streams.get_mut(&pid) else { return Ok(()); }; - self.published |= stream.write(pending, batched, self.anchor.as_mut())?; + let units = stream.write(pending, batched, self.anchor.as_mut())?; + self.published |= units > 0; + self.liveness.delivered(pid.as_u16(), units); // Record the decoded media track's PID + PMT descriptors (language, ...) once // its lazily created track exists, so export can preserve them. @@ -788,6 +802,7 @@ impl Import { self.media_unwrap.discontinuity(); self.last_pts = None; self.published = false; + self.liveness.discontinuity(); if self.mux_rate.discontinuity() { self.record_mux_rate()?; } @@ -889,8 +904,9 @@ impl Import { for pid in pids { self.flush(pid)?; } - for stream in self.streams.values_mut() { - stream.finish()?; + for (pid, stream) in &mut self.streams { + let units = stream.finish()?; + self.liveness.delivered(pid.as_u16(), units); } for section in self.sections.values_mut() { section.finish()?; @@ -899,21 +915,27 @@ impl Import { Ok(()) } - /// Snapshot the audio frame sync this importer has lost or could not verify. + /// Snapshot what every elementary stream has delivered, and the audio frame sync lost on + /// the way. /// /// Cheap: it reads counters the demuxer already keeps, so a caller can poll it per /// chunk and report the delta. pub fn stats(&self) -> Stats { let mut streams = self.retired_stats.clone(); - for (pid, stream) in &self.streams { - let Some(current) = stream.stats() else { - continue; - }; + let routes = self + .streams + .iter() + .filter_map(|(pid, stream)| Some((pid.as_u16(), stream.stats()?))) + .chain(self.sections.keys().map(|&pid| (pid, StreamStats::new(".ts")))); + for (pid, current) in routes { streams - .entry(pid.as_u16()) + .entry(pid) .and_modify(|retired| retired.merge(¤t)) .or_insert(current); } + for (pid, stats) in &mut streams { + (stats.units, stats.quiet) = self.liveness.stream(*pid); + } Stats { streams } } @@ -935,33 +957,44 @@ impl Import { } } -/// Frame sync the demuxed audio streams lost or could not verify, keyed by elementary -/// stream PID. +/// What each demuxed elementary stream delivered, and the audio frame sync it lost or could +/// not verify, keyed by elementary stream PID. /// /// Snapshot it with [`Import::stats`]. Every count is cumulative for the life of the /// importer, so what an operator alarms on is the rate: a feed that resyncs once an hour is -/// healthy, one that resyncs every second is losing audio. +/// healthy, one that resyncs every second is losing audio, and one whose access units stop +/// advancing while the mux keeps flowing has lost that stream. #[derive(Clone, Debug, Default, PartialEq, Eq)] #[non_exhaustive] pub struct Stats { - /// Counters per elementary stream PID, ordered by PID. A PID that has never lost frame - /// sync is absent, so an empty map means nothing has been lost. + /// One row per elementary stream PID the importer carries, ordered by PID. A PID the + /// importer drops (an undecoded stream without the `mpegts` catalog section) has none. pub streams: BTreeMap, } impl Stats { - /// Whether no stream has lost frame sync. + /// Whether no elementary stream has been registered yet. pub fn is_empty(&self) -> bool { self.streams.is_empty() } } -/// What one elementary stream lost or could not verify. See [`Stats`]. +/// What one elementary stream delivered, lost, or could not verify. See [`Stats`]. #[derive(Clone, Debug, Default, PartialEq, Eq)] #[non_exhaustive] pub struct StreamStats { - /// The current or most recent MoQ track suffix for this PID (`.mp2`, `.ac3`, `.aac`, ...). + /// The current or most recent MoQ track suffix for this PID (`.avc3`, `.mp2`, `.ts`, ...), + /// or empty for MPEG-1/2 video, which is read for its clock and not published. pub track: &'static str, + /// Access units the stream delivered: frames published for decoded media, PES payloads or + /// sections carried verbatim, and PES read on MPEG-1/2 video. + pub units: u64, + /// Transport time since the stream last delivered an access unit, or since the PMT + /// declared it, measured on the program clock (PCR). `None` until the first PCR arrives. + /// + /// No threshold applies: a sparse stream such as SCTE-35 is legitimately quiet for + /// seconds, so how long is too long is for whoever alarms to decide. + pub quiet: Option, /// Completed resyncs: the stream lost frame sync and locked onto a confirmed frame /// again. Each one is a gap in the audio. pub resyncs: u64, @@ -976,7 +1009,15 @@ pub struct StreamStats { } impl StreamStats { - /// Add a newer route's counters while naming the route that is active now. + fn new(track: &'static str) -> Self { + Self { + track, + ..Default::default() + } + } + + /// Add a newer route's frame-sync counters while naming the route that is active now. + /// Delivery is kept per PID rather than per route, so it needs no merging. fn merge(&mut self, current: &Self) { self.track = current.track; self.resyncs += current.resyncs; @@ -1137,13 +1178,13 @@ impl SectionStream { }) } - /// Consume one 188-byte TS packet, publishing each completed section. `pts` is - /// the current media clock used to timestamp a section (its arrival on the + /// Consume one 188-byte TS packet, publishing each completed section and returning how + /// many. `pts` is the current media clock used to timestamp a section (its arrival on the /// timeline; the splice time itself is inside the section bytes), if one is running. - fn packet(&mut self, pkt: &[u8], pts: Option) -> anyhow::Result { + fn packet(&mut self, pkt: &[u8], pts: Option) -> anyhow::Result { let mut sections = Vec::new(); self.reassembler.push(pkt, &mut sections); - let published = !sections.is_empty(); + let published = sections.len() as u64; for section in sections { self.emit(section, pts)?; } @@ -1239,7 +1280,7 @@ impl VerbatimStream { /// Publish one reassembled PES payload verbatim, in its own group, stamped with /// its PTS (or the live edge when the PES carried none). - fn write(&mut self, pending: Pending, anchor: Option<&mut crate::clock::Anchor>) -> anyhow::Result { + fn write(&mut self, pending: Pending, anchor: Option<&mut crate::clock::Anchor>) -> anyhow::Result { // Record the original PES stream_id once, from the first PES, so export // re-emits the stream under its real id (e.g. 0xBD for teletext/DVB AC-3). if !self.stream_id_recorded { @@ -1266,7 +1307,7 @@ impl VerbatimStream { }; self.track.write(frame)?; self.track.cut(None)?; - Ok(true) + Ok(1) } fn discontinuity(&mut self, published: bool) -> anyhow::Result<()> { @@ -1419,6 +1460,73 @@ impl Continuity { } } +/// How long each elementary stream has gone without delivering an access unit. +/// +/// Measured on the program clock, the PCR summed interval by interval, so it runs straight +/// through the 33-bit wrap, a signalled time-base reset and a corrupt PCR instead of jumping +/// with them. Not the media clock: that follows the video PTS, and stops with the very stream +/// this catches. +#[derive(Default)] +struct Liveness { + /// The last PCR in 27 MHz ticks, forgotten at a reset so no interval spans one. + pcr: Option, + /// PCR ticks elapsed since the first PCR, if one has arrived. + elapsed: Option, + /// Per PID: access units delivered, and `elapsed` at the last one, or at registration. + /// Kept per PID rather than per route, so a PMT remap carries it like `retired_stats`. + streams: HashMap, +} + +impl Liveness { + /// A PCR arrived on the program's clock PID. + fn pcr(&mut self, pcr: u64) { + let elapsed = self.elapsed.get_or_insert(0); + if let Some(last) = self.pcr.replace(pcr) { + let step = (pcr + super::mux_rate::PCR_WRAP - last) % super::mux_rate::PCR_WRAP; + // Stepped one interval at a time, so a corrupt PCR, or the clock stepping back + // without a flag, costs one interval rather than inventing hours of silence on + // every PID. The bound is the mux-rate meter's. + if step <= super::mux_rate::MAX_INTERVAL { + *elapsed += step; + } + } + } + + /// The clock restarted or changed PID: the next interval measures nothing. + fn discontinuity(&mut self) { + self.pcr = None; + } + + /// The PMT declared `pid`. Its silence counts from here until it delivers. + fn register(&mut self, pid: u16) { + let now = self.elapsed.unwrap_or(0); + self.streams.entry(pid).or_insert((0, now)); + } + + /// `pid` delivered `units` access units just now. + fn delivered(&mut self, pid: u16, units: u64) { + if units == 0 { + return; + } + let now = self.elapsed.unwrap_or(0); + if let Some((count, last)) = self.streams.get_mut(&pid) { + *count += units; + *last = now; + } + } + + /// `pid`'s access units and how long it has been quiet. See [`StreamStats`]. + fn stream(&self, pid: u16) -> (u64, Option) { + let Some(&(units, last)) = self.streams.get(&pid) else { + return (0, None); + }; + let quiet = self + .elapsed + .map(|now| std::time::Duration::from_nanos((now - last) * 1_000 / 27)); + (units, quiet) + } +} + /// Byte-level reassembler for MPEG-TS private sections on one PID. /// /// Private sections (SCTE-35 table_id 0xFC and others) are not PES. This handles @@ -1567,12 +1675,13 @@ enum Stream { } impl Stream { + /// Route one reassembled PES, returning how many access units it published. fn write( &mut self, pending: Pending, batched: bool, anchor: Option<&mut crate::clock::Anchor>, - ) -> anyhow::Result { + ) -> anyhow::Result { match self { Stream::H264 { split, @@ -1585,10 +1694,10 @@ impl Stream { // Each PES is one access unit, so flush to emit it immediately. let mut frames = split.decode(&pending.data, pts)?; frames.extend(split.flush(pts)?); - let mut published = false; + let mut published = 0; for mut frame in frames { frame.timestamp = reanchor.apply(frame.timestamp, import.floor(frame.keyframe))?; - published |= skip_missing_keyframe(import.decode([frame]))?; + published += u64::from(skip_missing_keyframe(import.decode([frame]))?); } // After decode, so the track (and its catalog rendition) exists. if let Some(reorder) = reorder { @@ -1607,10 +1716,10 @@ impl Stream { // Each PES is one access unit, so flush to emit it immediately. let mut frames = split.decode(&pending.data, pts)?; frames.extend(split.flush(pts)?); - let mut published = false; + let mut published = 0; for mut frame in frames { frame.timestamp = reanchor.apply(frame.timestamp, import.floor(frame.keyframe))?; - published |= skip_missing_keyframe(import.decode([frame]))?; + published += u64::from(skip_missing_keyframe(import.decode([frame]))?); } if let Some(reorder) = reorder { import.observe_reorder(reorder)?; @@ -1621,7 +1730,7 @@ impl Stream { Stream::Opus(stream) => stream.write(pending, anchor), Stream::Legacy(stream) => stream.write(pending, anchor), Stream::Verbatim(stream) => stream.write(pending, anchor), - Stream::Clock | Stream::Ignored => Ok(false), + Stream::Clock | Stream::Ignored => Ok(0), } } @@ -1727,16 +1836,19 @@ impl Stream { } } - fn finish(&mut self) -> anyhow::Result<()> { + /// Finish the track, returning the access units a drained tail published. + fn finish(&mut self) -> anyhow::Result { match self { - Stream::H264 { import, .. } => Ok(import.finish()?), - Stream::H265 { import, .. } => Ok(import.finish()?), - Stream::Aac(stream) => stream.finish(), - Stream::Opus(stream) => stream.finish(), - Stream::Legacy(stream) => stream.finish(), - Stream::Verbatim(stream) => stream.finish(), - Stream::Clock | Stream::Ignored => Ok(()), + // Only the self-describing audio holds a frame back for a successor to confirm. + Stream::Aac(stream) => return stream.finish(), + Stream::Legacy(stream) => return stream.finish(), + Stream::H264 { import, .. } => import.finish()?, + Stream::H265 { import, .. } => import.finish()?, + Stream::Opus(stream) => stream.finish()?, + Stream::Verbatim(stream) => stream.finish()?, + Stream::Clock | Stream::Ignored => {} } + Ok(0) } fn abort(self, err: moq_net::Error) { @@ -1751,22 +1863,19 @@ impl Stream { } } - /// Frame sync this stream has lost, or `None` when it has lost none (or scans for none: - /// only the self-describing audio codecs do). + /// This route's track and the frame sync it has lost (only the self-describing audio + /// codecs scan for it), or `None` for a PID that is dropped rather than carried. fn stats(&self) -> Option { - let stats = match self { + Some(match self { Stream::Aac(stream) => stream.resync.stats(), Stream::Legacy(stream) => stream.resync.stats(), - Stream::H264 { .. } - | Stream::H265 { .. } - | Stream::Opus(_) - | Stream::Verbatim(_) - | Stream::Clock - | Stream::Ignored => return None, - }; - // A healthy stream reports nothing, so an empty snapshot means an intact feed. - let lost = stats.resyncs > 0 || stats.discarded > 0 || stats.unconfirmed > 0; - lost.then_some(stats) + Stream::H264 { .. } => StreamStats::new(".avc3"), + Stream::H265 { .. } => StreamStats::new(".hev1"), + Stream::Opus(_) => StreamStats::new(".opus"), + Stream::Verbatim(_) => StreamStats::new(".ts"), + Stream::Clock => StreamStats::new(""), + Stream::Ignored => return None, + }) } /// The MoQ track name of a decoded media stream, once its (lazily created) track @@ -1836,10 +1945,7 @@ impl Resync { // count from it for the life of the broadcast. unconfirmed: true, draining: false, - stats: StreamStats { - track, - ..Default::default() - }, + stats: StreamStats::new(track), } } @@ -2035,7 +2141,7 @@ impl AacStream { pending: Pending, batched: bool, anchor: Option<&mut crate::clock::Anchor>, - ) -> anyhow::Result { + ) -> anyhow::Result { let pes_base = unwrap_pts(&mut self.unwrap, pending.pts, anchor)?; // Prepend the partial frame left by the previous PES, if any. @@ -2061,6 +2167,7 @@ impl AacStream { // A single PES can carry several ADTS frames; split and feed each raw frame. let mut burst = std::time::Duration::ZERO; + let mut published = 0; let mut offset = 0; // Earliest candidate passed over for declaring a frame longer than the buffer holds, // carried only if nothing later in the buffer confirms. @@ -2192,6 +2299,7 @@ impl AacStream { // so the relay forwards it without waiting for the next. import.cut(None)?; self.resync.published(unvouched); + published += 1; // Offsets behind the published frame are spent; carrying one would republish it. fallback = None; @@ -2215,7 +2323,7 @@ impl AacStream { self.tail_pts = pts; } - Ok(!burst.is_zero()) + Ok(published) } /// The PES PTS on the published timeline. Resolved where each frame starts rather than @@ -2253,17 +2361,18 @@ impl AacStream { self.resync.desynced(); } - fn finish(&mut self) -> anyhow::Result<()> { + fn finish(&mut self) -> anyhow::Result { // Drain a frame held only for want of a successor to confirm it: at end of stream // that successor is never coming. Only once this stream has published a frame, // though. Before that nothing has vouched for any boundary, so accepting one here // would hand a capture that joined mid-frame and ended immediately the same false // frame that starting unconfirmed exists to reject, and build the track's config out // of it. + let mut drained = 0; if !self.tail.is_empty() && self.import.is_some() { self.resync.drain(); // No PTS to translate, so no mapping needed. - self.write(Pending::empty(), true, None)?; + drained = self.write(Pending::empty(), true, None)?; } // A partial frame at end of stream isn't emissible; drop it, but leave a trace for // diagnosing truncated captures. @@ -2279,7 +2388,7 @@ impl AacStream { if let Some(import) = &mut self.import { import.finish()?; } - Ok(()) + Ok(drained) } fn abort(mut self, err: moq_net::Error) { @@ -2299,13 +2408,14 @@ struct OpusStream { } impl OpusStream { - fn write(&mut self, pending: Pending, anchor: Option<&mut crate::clock::Anchor>) -> anyhow::Result { + fn write(&mut self, pending: Pending, anchor: Option<&mut crate::clock::Anchor>) -> anyhow::Result { let base = unwrap_pts(&mut self.unwrap, pending.pts, anchor)?; let edge = self.import.live_edge(); let base = base.map(|base| self.reanchor.apply(base, edge)).transpose()?; let data = &pending.data; let mut offset = 0; + let mut published = 0; // 48 kHz samples elapsed since this PES's PTS, advancing each packet after the first. let mut elapsed: u64 = 0; while offset < data.len() { @@ -2333,8 +2443,9 @@ impl OpusStream { // doesn't stall the timeline for the rest of the PES. elapsed += opus::packet_samples(packet).unwrap_or(960) as u64; offset = end; + published += 1; } - Ok(offset > 0) + Ok(published) } fn discontinuity(&mut self, published: bool) -> anyhow::Result<()> { @@ -2455,8 +2566,8 @@ struct LegacyStream { } impl LegacyStream { - fn write(&mut self, pending: Pending, anchor: Option<&mut crate::clock::Anchor>) -> anyhow::Result { - let mut published = false; + fn write(&mut self, pending: Pending, anchor: Option<&mut crate::clock::Anchor>) -> anyhow::Result { + let mut published = 0; let pes_base = unwrap_pts(&mut self.unwrap, pending.pts, anchor)?; // Prepend the partial frame left by the previous PES, if any. @@ -2621,7 +2732,7 @@ impl LegacyStream { // so the relay forwards it without waiting for the next. import.cut(None)?; self.resync.published(unvouched); - published = true; + published += 1; // Offsets behind the published frame are spent; carrying one would republish it. fallback = None; @@ -2676,17 +2787,18 @@ impl LegacyStream { self.resync.desynced(); } - fn finish(&mut self) -> anyhow::Result<()> { + fn finish(&mut self) -> anyhow::Result { // Drain a frame held only for want of a successor to confirm it: at end of stream // that successor is never coming. Only once this stream has published a frame, // though. Before that nothing has vouched for any boundary, so accepting one here // would hand a capture that joined mid-frame and ended immediately the same false // frame that starting unconfirmed exists to reject, and build the track's config out // of it. + let mut drained = 0; if !self.tail.is_empty() && self.import.is_some() { self.resync.drain(); // No PTS to translate, so no mapping needed. - self.write(Pending::empty(), None)?; + drained = self.write(Pending::empty(), None)?; } // A partial frame at end of stream isn't emissible verbatim; drop it, but // leave a trace for diagnosing truncated captures. @@ -2706,7 +2818,7 @@ impl LegacyStream { if let Some(import) = &mut self.import { import.finish()?; } - Ok(()) + Ok(drained) } fn abort(mut self, err: moq_net::Error) { @@ -2937,6 +3049,29 @@ mod test { assert_eq!(stats.resyncs, 0, "the stream has not regained sync yet"); } + #[test] + fn liveness_steps_over_a_corrupt_pcr_and_the_wrap() { + const MS: u64 = 27_000; + let mut liveness = super::Liveness::default(); + liveness.register(0x100); + let mut pcr = super::super::mux_rate::PCR_WRAP - 100 * MS; + for _ in 0..10 { + liveness.pcr(pcr); + pcr = (pcr + 40 * MS) % super::super::mux_rate::PCR_WRAP; + } + assert_eq!(liveness.stream(0x100), (0, Some(Duration::from_millis(360)))); + + // A PCR hours ahead, then the clock carrying on where it was: neither step counts. + liveness.pcr(pcr + 23_861_000 * MS); + liveness.pcr(pcr); + assert_eq!(liveness.stream(0x100).1, Some(Duration::from_millis(360))); + + liveness.pcr(pcr + 40 * MS); + liveness.delivered(0x100, 3); + liveness.pcr(pcr + 80 * MS); + assert_eq!(liveness.stream(0x100), (3, Some(Duration::from_millis(40)))); + } + #[test] fn resync_does_not_count_an_unvouched_eof_publication() { let mut resync = super::Resync::new(0x61, ".mp2"); @@ -3803,7 +3938,10 @@ mod test { // scanned past, and the next PES starts a frame the one after it confirms. The // counters exist for the shapes that don't get caught that early. assert!( - looped_stats.is_empty(), + looped_stats + .streams + .values() + .all(|s| s.resyncs == 0 && s.discarded == 0 && s.unconfirmed == 0), "a wrap the continuity check absorbs should cost no frame sync: {looped_stats:?}" ); } @@ -4027,6 +4165,8 @@ mod test { AAC_PID, super::StreamStats { track: ".aac", + units: 4, + quiet: None, resyncs: 1, discarded: 47, unconfirmed: 0, @@ -4218,6 +4358,8 @@ mod test { MP2_PID, super::StreamStats { track: ".mp2", + units: 4, + quiet: None, resyncs: 1, discarded: 72, unconfirmed: 0, @@ -4419,6 +4561,8 @@ mod test { MP2_PID, super::StreamStats { track: ".mp2", + units: 2, + quiet: None, resyncs: 0, discarded: 0, unconfirmed: 1, diff --git a/rs/moq-mux/src/container/ts/import_test.rs b/rs/moq-mux/src/container/ts/import_test.rs index 05ce77c6877..320a63ef62a 100644 --- a/rs/moq-mux/src/container/ts/import_test.rs +++ b/rs/moq-mux/src/container/ts/import_test.rs @@ -656,3 +656,232 @@ async fn live_import_restarts_forward_after_idle() { ); } } + +/// The PCR a packet's adaptation field carries, in 27 MHz ticks. +fn pcr(pkt: &[u8]) -> Option { + if pkt[3] & 0x20 == 0 || pkt[4] < 7 || pkt[5] & 0x10 == 0 { + return None; + } + let base = (u64::from(pkt[6]) << 25) + | (u64::from(pkt[7]) << 17) + | (u64::from(pkt[8]) << 9) + | (u64::from(pkt[9]) << 1) + | (u64::from(pkt[10]) >> 7); + Some(base * 300 + ((u64::from(pkt[10] & 0x01) << 8) | u64::from(pkt[11]))) +} + +fn packet_pid(pkt: &[u8]) -> u16 { + (u16::from(pkt[1] & 0x1f) << 8) | u16::from(pkt[2]) +} + +/// Each packet of `ts` with the program clock it arrives at, counted from the first PCR. +fn timed(ts: &[u8]) -> impl Iterator { + let mut first = None; + let mut now = std::time::Duration::ZERO; + ts.as_chunks::<188>().0.iter().map(move |pkt| { + if let Some(pcr) = pcr(pkt) { + let first = *first.get_or_insert(pcr); + now = std::time::Duration::from_nanos((pcr - first) * 1_000 / 27); + } + (now, pkt) + }) +} + +/// `ts` with the PES on `pid` suppressed from its first PES start at or after `from` to its +/// first at or after `to`, as an encoder whose one input died behind a running mux emits it. +/// +/// A suppressed packet that carried the PCR keeps it in an adaptation-only packet, every +/// other one becomes null stuffing so the mux rate holds, and the counters after the gap are +/// renumbered so continuity stays legal. +fn suppress(ts: &[u8], pid: u16, from: std::time::Duration, to: std::time::Duration) -> Vec { + let mut null = [0xff; 188]; + null[..4].copy_from_slice(&[0x47, 0x1f, 0xff, 0x10]); + + let mut out = Vec::with_capacity(ts.len()); + let (mut active, mut done) = (false, false); + let (mut last_cc, mut dropped) = (0, 0u8); + for (now, pkt) in timed(ts) { + let mut pkt = *pkt; + if packet_pid(&pkt) == pid { + if pkt[1] & 0x40 != 0 { + if !active && !done && now >= from { + active = true; + } else if active && now >= to { + (active, done) = (false, true); + } + } + let payload = pkt[3] & 0x10 != 0; + if active { + dropped = (dropped + u8::from(payload)) & 0x0f; + pkt = match pcr(&pkt) { + Some(_) => { + let mut clock = [0xff; 188]; + clock[..6].copy_from_slice(&[0x47, pkt[1] & 0x1f, pkt[2], 0x20 | last_cc, 183, 0x10]); + clock[6..12].copy_from_slice(&pkt[6..12]); + clock + } + None => null, + }; + } else { + pkt[3] = (pkt[3] & 0xf0) | (pkt[3].wrapping_sub(dropped) & 0x0f); + if payload { + last_cc = pkt[3] & 0x0f; + } + } + } + out.extend_from_slice(&pkt); + } + assert!(done, "the fixture must resume the PID before it ends"); + out +} + +/// What #3489 measured before MoQ saw the stimulus: the same packets and PCRs as `ts`, and +/// not one continuity error the fixture didn't already have. +fn assert_legal(ts: &[u8], stimulus: &[u8]) { + assert_eq!(ts.len(), stimulus.len(), "the mux rate moved"); + let clocks = |ts: &[u8]| { + ts.as_chunks::<188>() + .0 + .iter() + .filter_map(|pkt| pcr(pkt)) + .collect::>() + }; + assert_eq!(clocks(ts), clocks(stimulus), "a PCR went missing"); + let errors = |ts: &[u8]| { + let mut last = std::collections::HashMap::new(); + let mut errors = std::collections::BTreeMap::::new(); + for pkt in ts.as_chunks::<188>().0 { + let pid = packet_pid(pkt); + if pid == 0x1fff || pkt[3] & 0x10 == 0 { + continue; + } + let cc = pkt[3] & 0x0f; + if last.insert(pid, cc).is_some_and(|previous| cc != (previous + 1) & 0x0f) { + *errors.entry(pid).or_default() += 1; + } + } + errors + }; + assert_eq!(errors(ts), errors(stimulus), "the stimulus broke continuity"); +} + +/// Import `ts` with an `mpegts` catalog, snapshotting the stats once the program clock +/// reaches each of `at`, and once more at the end of the input. +fn sample(ts: &[u8], at: &[std::time::Duration]) -> Vec { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let _catalog = crate::catalog::Producer::new( + &mut broadcast, + crate::catalog::Config::default() + .with_catalog(crate::catalog::hang::Catalog::::default()), + ) + .unwrap(); + let mut import = crate::container::ts::Import::new(broadcast, _catalog.reserve()); + + let mut samples = Vec::new(); + let mut done = 0; + for &at in at { + let end = 188 + * timed(ts) + .position(|(now, _)| now >= at) + .expect("the fixture reaches it"); + import.decode(&ts[done..end]).unwrap(); + samples.push(import.stats()); + done = end; + } + import.decode(&ts[done..]).unwrap(); + samples.push(import.stats()); + samples +} + +/// #3489's stimulus: `pid` goes quiet between `from` and `to` while its PCR and continuity stay +/// legal. Its row stops counting and its silence grows with the program clock, where the +/// unmodified fixture keeps counting; `peer` keeps delivering throughout; and the row counts +/// again once the PID returns. +fn assert_stalls(fixture: &[u8], pid: u16, track: &str, peer: u16, from: f64, to: f64) { + use std::time::Duration; + + let stimulus = suppress(fixture, pid, Duration::from_secs_f64(from), Duration::from_secs_f64(to)); + assert_legal(fixture, &stimulus); + + let at = [Duration::from_secs_f64(from + 0.4), Duration::from_secs_f64(to - 0.2)]; + let control = sample(fixture, &at); + assert!( + control[1].streams[&pid].units > control[0].streams[&pid].units, + "the unmodified fixture delivers on {pid:#x} across the window" + ); + + let samples = sample(&stimulus, &at); + let [early, late, end] = [&samples[0], &samples[1], &samples[2]].map(|s| s.streams[&pid].clone()); + assert_eq!(early.track, track); + assert!(early.units > 0, "{pid:#x} delivered before it went quiet"); + assert_eq!(late.units, early.units, "{pid:#x} stopped counting"); + + let (early_quiet, late_quiet) = (early.quiet.unwrap(), late.quiet.unwrap()); + assert!( + early_quiet >= Duration::from_millis(350), + "{pid:#x} has been quiet since the window opened: {early_quiet:?}" + ); + let grew = late_quiet - early_quiet; + let elapsed = at[1] - at[0]; + assert!( + grew.abs_diff(elapsed) <= Duration::from_millis(50), + "the silence grows with the program clock: {grew:?} over {elapsed:?}" + ); + + let (peer_early, peer_late) = (&samples[0].streams[&peer], &samples[1].streams[&peer]); + assert!(peer_late.units > peer_early.units, "{peer:#x} kept delivering"); + assert!( + peer_late.quiet.unwrap() < Duration::from_millis(200), + "{peer:#x} is not quiet: {:?}", + peer_late.quiet + ); + + assert!(end.units > late.units, "{pid:#x} counts again once it returns"); + assert!(end.quiet.unwrap() < late_quiet, "{pid:#x} is no longer as quiet"); +} + +/// Video carrying the program's PCR, the layout #3489 measured: the suppressed PID still +/// drives the clock its own silence is measured on. +#[test] +fn import_reports_a_silent_video_pid() { + let data = include_bytes!("test_data/scte35/bbb5s.ts"); + assert_stalls(data, 0x100, ".hev1", 0x101, 1.5, 3.5); +} + +/// One of two MP2 programs goes quiet behind a dedicated PCR PID. +#[test] +fn import_reports_a_silent_audio_pid() { + let data = include_bytes!("test_data/scte35/kyrion_dirtystart.ts"); + assert_stalls(data, 0x101, ".mp2", 0x102, 1.5, 3.5); +} + +/// SCTE-35 is sparse, so its row reports the silence and leaves the verdict to the caller. +#[test] +fn import_reports_a_silent_scte35_pid() { + let data = include_bytes!("test_data/scte35/kyrion_dirtystart.ts"); + assert_stalls(data, 0x14d, ".ts", 0x100, 2.5, 3.5); +} + +/// Every elementary stream the importer carries reports a row, decoded, clock-only, and +/// verbatim alike, and every row has delivered. +#[test] +fn import_reports_every_elementary_stream() { + for (data, rows) in [ + ( + &include_bytes!("test_data/kyrion_mpeg2av_ac3.ts")[..], + &[(0x100, ""), (0x101, ".ac3"), (0x102, ".mp2"), (0x14d, ".ts")][..], + ), + ( + &include_bytes!("test_data/scte35/bbb5s.ts")[..], + &[(0x21, ".ts"), (0x100, ".hev1"), (0x101, ".opus")][..], + ), + ] { + let stats = sample(data, &[]).pop().unwrap(); + let tracks: Vec<(u16, &str)> = stats.streams.iter().map(|(&pid, s)| (pid, s.track)).collect(); + assert_eq!(tracks, rows); + for (pid, stream) in &stats.streams { + assert!(stream.units > 0, "{pid:#x} delivered nothing: {stream:?}"); + assert!(stream.quiet.is_some(), "{pid:#x} has no program clock: {stream:?}"); + } + } +} diff --git a/rs/moq-mux/src/container/ts/mux_rate.rs b/rs/moq-mux/src/container/ts/mux_rate.rs index 59071f0e348..ec4298b0ff6 100644 --- a/rs/moq-mux/src/container/ts/mux_rate.rs +++ b/rs/moq-mux/src/container/ts/mux_rate.rs @@ -13,7 +13,7 @@ const PCR_HZ: u64 = 27_000_000; /// Bits per transport packet. const PACKET_BITS: u64 = 188 * 8; /// The 33-bit base times 300 plus the 9-bit extension: the PCR wraps here. -const PCR_WRAP: u64 = (1 << 33) * 300; +pub(super) const PCR_WRAP: u64 = (1 << 33) * 300; /// How much PCR time one window spans before it is judged. const WINDOW: u64 = 2 * PCR_HZ; /// Intervals are pooled into samples this long before they are compared. One @@ -23,7 +23,7 @@ const WINDOW: u64 = 2 * PCR_HZ; const SAMPLE: u64 = WINDOW / 4; /// A PCR interval longer than this is a gap or a wrap gone wrong, not a sample: /// TR 101 290 already flags anything over 100 ms. -const MAX_INTERVAL: u64 = PCR_HZ; +pub(super) const MAX_INTERVAL: u64 = PCR_HZ; /// How far one sample may sit from a rate and still agree with it, in thousandths. /// A hardware multiplexer's rate wanders more than a percent between half-second /// samples while its whole-window average holds far tighter; a VBR source is off by From 382513ea92b397fb01eb1143d7ddfd93afd09103 Mon Sep 17 00:00:00 2001 From: t0ms Date: Tue, 29 Sep 2026 17:42:20 +0100 Subject: [PATCH 008/128] docs: flush quiet audio in the documented ffmpeg MPEG-TS line (#4514) Co-authored-by: Cursor --- demo/pub/justfile | 6 ++++-- doc/bin/cli.md | 2 +- doc/concept/standard.md | 2 +- quest/m1/README.md | 1 - quest/m1/ts-publish-muxdelay.md | 27 --------------------------- rs/moq-cli/README.md | 8 ++++---- 6 files changed, 10 insertions(+), 36 deletions(-) delete mode 100644 quest/m1/ts-publish-muxdelay.md diff --git a/demo/pub/justfile b/demo/pub/justfile index fb780f5e73e..2715bd75ccb 100644 --- a/demo/pub/justfile +++ b/demo/pub/justfile @@ -43,7 +43,7 @@ bbb url='http://localhost:4443' *args: ffmpeg -hide_banner -loglevel warning -copyts \ -stream_loop -1 -re -i media/bbb.mp4 \ -stream_loop -1 -re -i media/bbb-sd.mp4 \ - -map 0 -map 1:v -c copy -f mpegts -pes_payload_size 0 - \ + -map 0 -map 1:v -c copy -f mpegts -pes_payload_size 0 -muxdelay 0 - \ | cargo run --bin moq -- {{ args }} --connect "{{ url }}" --broadcast bbb.hang import ts # Encode the video-only SD rendition, preserving source timestamps and loop duration. @@ -259,10 +259,12 @@ ffmpeg-cmaf input output='-' *args: -f mp4 -movflags cmaf+separate_moof+delay_moov+skip_trailer -frag_duration 1000 {{ args }} {{ output }} # Convert an h264 input file to MPEG-TS format to stdout, with one PES per audio frame. +# -pes_payload_size 0 alone still queues audio frames under 170 bytes (silence) for up to +# 0.35 s; -muxdelay 0 writes each one as soon as the next arrives. [private] ffmpeg-ts input output='-' *args: ffmpeg -hide_banner -v quiet \ -stream_loop -1 -re \ -i "{{ input }}" \ -c copy \ - -f mpegts -pes_payload_size 0 {{ args }} {{ output }} + -f mpegts -pes_payload_size 0 -muxdelay 0 {{ args }} {{ output }} diff --git a/doc/bin/cli.md b/doc/bin/cli.md index e8345ac1320..0e0b5cee402 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -46,7 +46,7 @@ clients by `--auth-url` or `--auth-public`, as the relay does (see ```bash # Publish a file (remux to MPEG-TS without re-encoding) -ffmpeg -re -i video.mp4 -c copy -f mpegts -pes_payload_size 0 - | \ +ffmpeg -re -i video.mp4 -c copy -f mpegts -pes_payload_size 0 -muxdelay 0 - | \ moq --connect https://relay.example.com/anon --broadcast my-stream.hang import ts # Pull it back out diff --git a/doc/concept/standard.md b/doc/concept/standard.md index 282dcaf8801..b8a6ed81817 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -81,7 +81,7 @@ supports, and prints it in the logs. Publish a test pattern and play it back: ```bash ffmpeg -re -f lavfi -i testsrc=size=1280x720:rate=30 -f lavfi -i sine=frequency=440 \ -c:v libx264 -preset ultrafast -tune zerolatency -g 60 -c:a aac \ - -f mpegts -pes_payload_size 0 - \ + -f mpegts -pes_payload_size 0 -muxdelay 0 - \ | moq --connect https://relay.example.com --broadcast test.hang import ts moq --connect https://relay.example.com --broadcast test.hang export ts | ffplay - diff --git a/quest/m1/README.md b/quest/m1/README.md index c2c0560e64e..da2a9870d50 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -59,7 +59,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [TS program selection](/quest/m1/ts-programs.md) - `import ts` refuses a multi-program stream unless `--program ` picks one or publishes each - [TS export jitter](/quest/m1/ts-export-jitter.md) - the video reorder bound follows later catalogs and the declared reorder depth, so a late B-frame never reorders TS output; an undeclared stream can reorder once per new maximum depth - [TS import shared shift](/quest/m1/ts-import-shared-shift.md) - unflagged loop wraps move audio and video by one shift, so A/V sync holds across wraps -- [ffmpeg muxdelay](/quest/m1/ts-publish-muxdelay.md) - the documented MPEG-TS publish line adds `-muxdelay 0`, so quiet audio is not clumped - [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) - `import ts` reads a PAT or PMT that spans packets or follows a nonzero pointer_field instead of aborting - [Same-hop importers](/quest/m1/hop-aligned-import.md) - importers sharing a `--hop` and fed one stream publish identical groups and timestamps, so failover survives - [PipeWire duplicate cameras](/quest/m1/pipewire-dup-cameras.md) - a webcam lists once with PipeWire enabled diff --git a/quest/m1/ts-publish-muxdelay.md b/quest/m1/ts-publish-muxdelay.md deleted file mode 100644 index 688904da4d3..00000000000 --- a/quest/m1/ts-publish-muxdelay.md +++ /dev/null @@ -1,27 +0,0 @@ -# [XS] Documented ffmpeg line flushes audio - -## Goal - -The documented `ffmpeg ... -f mpegts -pes_payload_size 0 -` publish line stops -holding small audio frames in ffmpeg's muxer for up to 0.35 s. Those clumps -raise the importer's catalog `jitter` for the life of the track, and watch -adds about 230 ms of playout delay to match. - -## Plan - -Decided: add `-muxdelay 0` everywhere the line appears -(`demo/pub/justfile`, `doc/bin/cli.md`, `doc/concept/standard.md`, -`rs/moq-cli/README.md`). `import ts` needs no PCR lead. The reporter's patch -is ready. Verify by re-measuring the catalog jitter on a quiet-audio source; -there is no automated test for a docs line. - -The importer's jitter estimate keeping its maximum forever is a separate -problem; the player side is covered by the audio jitter target. - -## Closes - -- [#4347](https://github.com/moq-dev/moq/issues/4347) - close this issue when the quest finishes - -## Related - -- [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - a decaying playout estimate softens a transient burst diff --git a/rs/moq-cli/README.md b/rs/moq-cli/README.md index de0241a778b..8d68d1be713 100644 --- a/rs/moq-cli/README.md +++ b/rs/moq-cli/README.md @@ -32,7 +32,7 @@ moq --connect https://relay.example.com/anon \ ### Publish to a remote relay ```bash -ffmpeg -i input.mp4 -c copy -f mpegts -pes_payload_size 0 - | \ +ffmpeg -i input.mp4 -c copy -f mpegts -pes_payload_size 0 -muxdelay 0 - | \ moq --connect https://relay.example.com --broadcast my-stream.hang import ts ``` @@ -54,8 +54,8 @@ moq --connect https://relay.example.com --broadcast my-stream.hang play Hosts a MoQ server and publishes a single broadcast read from stdin into it. Useful for local testing without a separate relay process. ```bash -ffmpeg -i input.mp4 -c copy -f mpegts -pes_payload_size 0 - | \ - moq --listen '[::]:4443' --listen-tls-generate localhost --broadcast my-stream.hang import ts +ffmpeg -i input.mp4 -c copy -f mpegts -pes_payload_size 0 -muxdelay 0 - | \ + moq --listen '[::]:4443' --listen-tls-generate localhost --auth-public '**' --broadcast my-stream.hang import ts ``` ### Self-host: subscribe to an inbound broadcast @@ -63,7 +63,7 @@ ffmpeg -i input.mp4 -c copy -f mpegts -pes_payload_size 0 - | \ Hosts a MoQ server and writes an incoming broadcast's media to stdout. The inverse of the above. ```bash -moq --listen '[::]:4443' --listen-tls-generate localhost --broadcast my-stream.hang export ts | ffplay - +moq --listen '[::]:4443' --listen-tls-generate localhost --auth-public '**' --broadcast my-stream.hang export ts | ffplay - ``` ### Import formats From 5786456bd8b81df5c0dd663e1d60ff351536611b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 09:46:55 -0700 Subject: [PATCH 009/128] docs(relay): keep client grants off .internal for gossip (#4509) Co-authored-by: Claude Opus 5.5 --- doc/bin/relay/cluster.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/bin/relay/cluster.md b/doc/bin/relay/cluster.md index d313dd825a2..807becdeaeb 100644 --- a/doc/bin/relay/cluster.md +++ b/doc/bin/relay/cluster.md @@ -115,6 +115,16 @@ mesh = true A relay with `node` and `mesh` but no `connect` is a passive rendezvous. +Gossip trusts every node advertised under `.internal/origins/` and dials it +with `cluster.token`, unless the advertised URL carries its own `?jwt=`. Keep +client grants off `.internal/`: a client that can publish there can add a peer +that receives the token. + +Give `node` an authenticated TLS scheme (`https://`, `wss://`, `moqt://`, or +`moql://`). Peers dial that URL with the token, so `ws://` and `tcp://` send it +in cleartext, and `http://` pins a fingerprint fetched over plain HTTP and +may fall back to `ws://`. + On a LAN there may be no seed peer to gossip through. `[cluster.lan]` advertises this relay over mDNS and dials the peers that advertise back, so a rack or a home lab meshes with no seed list. A `moq --cluster-lan` process on the same From 24987847c7b968e9c0de5b8d8c6b275ff5fdfa74 Mon Sep 17 00:00:00 2001 From: shermerL <86936692+shermerL@users.noreply.github.com> Date: Wed, 30 Sep 2026 00:49:10 +0800 Subject: [PATCH 010/128] fix(video): guard portal sessions during negotiation (#4492) --- rs/moq-video/src/capture/pipewire.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/rs/moq-video/src/capture/pipewire.rs b/rs/moq-video/src/capture/pipewire.rs index 4ac1ea79209..1ceb8a0f28e 100644 --- a/rs/moq-video/src/capture/pipewire.rs +++ b/rs/moq-video/src/capture/pipewire.rs @@ -234,6 +234,8 @@ async fn portal_negotiate(cursor: bool) -> Result<(u32, OwnedFd, SessionGuard), .create_session(Default::default()) .await .map_err(|e| err("portal session", e))?; + let session = Arc::new(session); + let guard = SessionGuard::new(session.clone()); let restore = RESTORE_TOKEN.lock().unwrap().clone(); proxy @@ -273,7 +275,7 @@ async fn portal_negotiate(cursor: bool) -> Result<(u32, OwnedFd, SessionGuard), .open_pipe_wire_remote(&session, Default::default()) .await .map_err(|e| err("portal pipewire remote", e))?; - Ok((node_id, fd, SessionGuard::new(session))) + Ok((node_id, fd, guard)) } /// Closes the portal session when dropped, so the compositor's "screen is being @@ -285,7 +287,7 @@ struct SessionGuard { } impl SessionGuard { - fn new(session: ashpd::desktop::Session) -> Self { + fn new(session: Arc>) -> Self { let (tx, rx) = tokio::sync::oneshot::channel::<()>(); tokio::spawn(async move { // Resolves with `Err` once the guard (the sender) drops. From 15239d67764a3cd5f61e2d34e61efa87081e8e23 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 09:52:21 -0700 Subject: [PATCH 011/128] fix(hang): summarize skipped groups once per catch-up (#4490) Co-authored-by: GPT-6 --- js/hang/bench/slow-group.ts | 42 ++++++++++++++++ js/hang/src/container/consumer.skips.test.ts | 51 ++++++++++++++++++++ js/hang/src/container/consumer.ts | 11 +++-- quest/m1/README.md | 1 - quest/m1/slow-group-log.md | 24 --------- 5 files changed, 99 insertions(+), 30 deletions(-) create mode 100644 js/hang/bench/slow-group.ts create mode 100644 js/hang/src/container/consumer.skips.test.ts delete mode 100644 quest/m1/slow-group-log.md diff --git a/js/hang/bench/slow-group.ts b/js/hang/bench/slow-group.ts new file mode 100644 index 00000000000..68773f203eb --- /dev/null +++ b/js/hang/bench/slow-group.ts @@ -0,0 +1,42 @@ +// Run with `bun js/hang/bench/slow-group.ts` to measure warning traffic per catch-up. +import { Group, Time, Track, Varint } from "@moq/net"; +import { Signal } from "@moq/signals"; +import { Consumer } from "../src/container/consumer.ts"; +import { Format } from "../src/container/legacy.ts"; + +for (const count of [1, 16, 256, 1024]) { + const track = new Track.Producer("tone"); + const maxAge = new Signal(Time.Milli(30_000)); + const consumer = new Consumer(track.subscribe({ maxAge: Time.Milli(30_000) }), { + format: new Format("data"), + maxAge, + }); + const write = (sequence: number) => { + const group = new Group.Producer(sequence); + group.writeFrame({ payload: Varint.encode(sequence * 1000), timestamp: Time.Timestamp.now() }); + track.writeGroup(group); + }; + const buffered = async (timestamp: number) => { + while (consumer.buffered.peek().at(-1)?.end !== timestamp) await consumer.buffered.changed(); + }; + let warnings = 0; + let bytes = 0; + const warn = console.warn; + console.warn = (...args: unknown[]) => { + warnings++; + bytes += JSON.stringify(args).length; + }; + try { + for (let i = 0; i < count; i++) write(i); + await buffered(count - 1); + maxAge.set(Time.Milli.zero); + const started = performance.now(); + write(count); + await buffered(count); + console.log(JSON.stringify({ groups: count, warnings, bytes, catchupMs: performance.now() - started })); + } finally { + consumer.close(); + track.close(); + console.warn = warn; + } +} diff --git a/js/hang/src/container/consumer.skips.test.ts b/js/hang/src/container/consumer.skips.test.ts new file mode 100644 index 00000000000..dc845c47a4c --- /dev/null +++ b/js/hang/src/container/consumer.skips.test.ts @@ -0,0 +1,51 @@ +import { expect, spyOn, test } from "bun:test"; +import { Group, Time, Track, Varint } from "@moq/net"; +import { Signal } from "@moq/signals"; +import { Consumer } from "./consumer.ts"; +import { Format } from "./legacy.ts"; + +for (const count of [1, 16, 256]) { + test(`Consumer summarizes ${count} skipped groups once per catch-up`, async () => { + const warn = spyOn(console, "warn").mockImplementation(() => {}); + const track = new Track.Producer("tone"); + const maxAge = new Signal(Time.Milli(30_000)); + const consumer = new Consumer(track.subscribe({ maxAge: Time.Milli(30_000) }), { + format: new Format("data"), + maxAge, + }); + const write = (sequence: number, timestamp: number) => { + const group = new Group.Producer(sequence); + group.writeFrame({ payload: Varint.encode(timestamp), timestamp: Time.Timestamp.now() }); + track.writeGroup(group); + return group; + }; + const buffered = async (timestamp: number) => { + while (consumer.buffered.peek().at(-1)?.end !== timestamp) await consumer.buffered.changed(); + }; + try { + // Sparse sequence numbers make the count differ from the sequence range. + for (let i = 0; i < count; i++) write(i * 2, i * 1000); + await buffered(count - 1); + expect(warn).not.toHaveBeenCalled(); + maxAge.set(Time.Milli.zero); + const newest = write(count * 2, count * 1000); + await buffered(count); + expect(warn).toHaveBeenCalledTimes(1); + expect(warn).toHaveBeenLastCalledWith(`skipping slow groups: track=tone 0 -> ${count * 2} count=${count}`); + expect(consumer.buffered.peek()[0]?.start).toBe(Time.Milli(count)); + // The retained group is still delivered, and another catch-up reports separately. + expect((await consumer.next())?.group).toBe(count * 2); + newest.writeFrame({ payload: Varint.encode(count * 1000), timestamp: Time.Timestamp.now() }); + write(count * 2 + 2, (count + 1) * 1000); + await buffered(count + 1); + expect(warn).toHaveBeenCalledTimes(2); + expect(warn).toHaveBeenLastCalledWith( + `skipping slow groups: track=tone ${count * 2} -> ${count * 2 + 2} count=1`, + ); + } finally { + consumer.close(); + track.close(); + warn.mockRestore(); + } + }); +} diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index 912ada6fc76..0fc9766177d 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -304,7 +304,8 @@ export class Consumer { #checkMaxAge() { if (this.#active === undefined) return; - let skipped = false; + let skipped = 0; + const start = this.#groups[0]?.consumer.sequence; let hole = false; // Keep skipping the oldest group while the buffered span exceeds the max age. @@ -333,9 +334,6 @@ export class Consumer { this.#groups.shift(); this.#active = this.#groups[0]?.consumer.sequence; - console.warn( - `skipping slow group: track=${this.#track.name} ${first.consumer.sequence} -> ${this.#active}`, - ); const nextStart = this.#groups[0]?.frames.at(0)?.timestamp ?? this.#groups[0]?.end; const marker = !first.empty && !first.media; @@ -344,13 +342,16 @@ export class Consumer { } first.consumer.close(); first.frames.length = 0; - skipped = true; + skipped++; this.#gap = true; } if (hole) this.#markPlayhead(); if (skipped) { + console.warn( + `skipping slow groups: track=${this.#track.name} ${start} -> ${this.#active} count=${skipped}`, + ); this.#updateBuffered(); // Wake up any consumers waiting for a new frame. diff --git a/quest/m1/README.md b/quest/m1/README.md index da2a9870d50..8c4127c6880 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -50,7 +50,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Interop audio cold start](/quest/m1/interop-audio-cold-start.md) - the interop audio tone check stops failing on cold start, fixed at its cause - [Auth outage clock](/quest/m1/auth-outage-clock.md) - the relay and moq-auth outage tests run on a paused clock again and assert both bounds of `expires` - [Legacy end overshoot](/quest/m1/legacy-end-overshoot.md) - browser playback survives a group that starts inside the previous group's estimated end -- [Slow group log](/quest/m1/slow-group-log.md) - a starved viewer reports skipped groups once per catch-up, not once per group - [UnknownSession log flood](/quest/m1/unknown-session-logs.md) - streams reset before their WebTransport header stop being reported as UnknownSession at WARN - [Merge queue](/quest/m1/merge-queue.md) - the required checks run on `merge_group`, so a stale green check can no longer break main - [CI hygiene](/quest/m1/ci-hygiene.md) - a push to one PR never cancels another's run, and a failed run never saves the Rust cache diff --git a/quest/m1/slow-group-log.md b/quest/m1/slow-group-log.md deleted file mode 100644 index 91aa5d576fc..00000000000 --- a/quest/m1/slow-group-log.md +++ /dev/null @@ -1,24 +0,0 @@ -# [XS] A starved viewer reports skipped groups once - -## Goal - -When `@moq/watch` falls behind and skips groups past the max age, it logs one -summary per catch-up instead of one warning per skipped group, so a starved -page does not spend its remaining CPU on console traffic. - -## Plan - -`#checkMaxAge` in `js/hang/src/container/consumer.ts` calls `console.warn` -for every group it drops. A 2.5 ms Opus track is one group per frame, so a -page behind on it warns hundreds of times a second. In an interop `go -> js` -cell at load average 182, the subscriber logged 7151 `skipping slow group: -track=tone` lines in 149 s, and Playwright could not resolve the Pause button -for 30 s. Starvation was the cause; the warnings, each forwarded over CDP, -made it deeper. - -Report the skipped range and count once per `#checkMaxAge` call, the way -`watch/src/sync.ts` summarizes late frames. - -## Related - -- [More tests under load](/quest/m1/test-flakes-2.md) - other load-only failures, fixed at the cause From 18d7c2530c33ef16e19f229b38b7a0e42ce84c4c Mon Sep 17 00:00:00 2001 From: t0ms Date: Tue, 29 Sep 2026 17:58:32 +0100 Subject: [PATCH 012/128] test(ts): grade the byte schedule between PCRs (#4493) Co-authored-by: Claude Opus 5.5 Co-authored-by: Luke Curley --- quest/m1/ts-export-byte-schedule.md | 7 +- test/ts/README.md | 64 ++++++++++++-- test/ts/pcr-timing.py | 131 ++++++++++++++++++++++++++++ test/ts/run.sh | 24 ++++- 4 files changed, 216 insertions(+), 10 deletions(-) diff --git a/quest/m1/ts-export-byte-schedule.md b/quest/m1/ts-export-byte-schedule.md index 8427325a68e..1130acbd2d2 100644 --- a/quest/m1/ts-export-byte-schedule.md +++ b/quest/m1/ts-export-byte-schedule.md @@ -22,8 +22,9 @@ UDP sink is out of scope; delivery stays with an external tool. cap (fail loud, or drop to VBR with a warning) and record the choice here. - The CLI `Delivery` pacer releases one slice per PCR interval; confirm it still writes on the schedule the PCRs describe. -- Grade the distribution of bytes between consecutive PCRs, not only - adjacency: extend `test/ts/pcr-timing.py` (or add a check beside it) and run - it in the existing TS test recipe against a CBR fixture. +- `test/ts/pcr-timing.py`'s `pcr-schedule` grades the bytes between + consecutive PCRs, report-only in the TS recipe. Once the schedule lands, gate + it there with `--schedule-pct-min`, against a fixture whose keyframes outgrow + a PCR slot; the generated clip mostly pads and passes already. - `doc/bin/cli.md`: say that export pads to `mpegts.muxRate` on a constant-rate schedule and what latency that adds. diff --git a/test/ts/README.md b/test/ts/README.md index 2376bf8c0fc..e8507625136 100644 --- a/test/ts/README.md +++ b/test/ts/README.md @@ -35,7 +35,13 @@ subscriber's stdout goes straight into `pcr-timing.py` instead of a capture file That is the only arm that can see release timing at all, and it is what nightly runs (see [CI](#ci)). -The arm passes only when the grader's verdict *and* the publisher's exit status +The default arm runs `pcr-timing.py` over its capture too, after `compliance.py`, +for the one thing the IRD model does not grade: whether the bytes between +consecutive PCRs are the ones the mux rate implies +([`pcr-schedule`](#byte-schedule)). It is a shape check, so it reports without +gating unless `--strict`. + +The live arm passes only when the grader's verdict *and* the publisher's exit status are clean. The grader can only speak for what reached it, and the sample floor rejects a window that came up short, so a publisher dying late in the run leaves enough behind to pass every check: a broken round-trip reported as a good one. @@ -109,13 +115,17 @@ also means it cannot grade `release`: a change to *when* the exporter hands byte over is invisible to any harness that does not stamp arrivals. `pcr-timing.py` reads a pipe and grades all three in one pass. +A constant-rate stream makes a fourth claim, graded by `pcr-schedule`: that the +bytes between consecutive PCRs are the bytes the mux rate implies for that +interval. + ```bash -# live: all three domains, reading the exporter directly +# live: every domain, reading the exporter directly moq --connect http://localhost:4443 --broadcast live.hang export ts \ | ./pcr-timing.py --live --seconds 45 -# offline: value and position only (a file has no release timing left in it) -./pcr-timing.py capture.ts +# offline: value, position and schedule (a file has no release timing left in it) +./pcr-timing.py capture.ts --mux-rate 10000000 ``` It needs only `python3`, with no TSDuck, no source file and no declared mux rate, @@ -123,7 +133,10 @@ because every check is graded against the stream's **own** PCR values. If two consecutive PCRs are 25 ms apart in value then they must be ~25 ms apart in arrival, whatever clock rate the stream is running at. The price of that basis is the same one `compliance.py` pays: a PCR emitted at the wrong rate stays -internally consistent, so absolute rate is not what this grades. +internally consistent, so absolute rate is not what this grades. `pcr-schedule` +is the exception when it is given `--mux-rate`, which pins the rate the way +`duration-fidelity` does; without it, it estimates the rate from the capture and +grades only how evenly the bytes are laid over the PCRs. | Check | Severity | What it verifies | |---|---|---| @@ -133,6 +146,7 @@ internally consistent, so absolute rate is not what this grades. | `pcr-value-interval` | hard | no interval above `--repetition-ms` (default 40, TR 101 290), within one time base | | `pcr-release-timing` | hard | no more than `--release-pct-max` of intervals arrive further than `--release-ms` from the interval their own values assert, and accumulated drift stays within `--drift-ms`, being the standing lag the sender is allowed to hold; a sample below `--live-min-pcr` PCRs or `--live-cover-pct` of the window is a failure, not a pass (`--live` only) | | `pcr-position` | shape | share of PCR packets within `--adjacent-packets` of the previous one | +| `pcr-schedule` | shape | share of PCR intervals, on the busiest PCR PID, whose bytes are within `--schedule-tolerance-pct` (default 1) or one packet of what `--mux-rate` implies (estimated from the capture if not given); hard, at that share, when `--schedule-pct-min` is given | Accumulated drift has two shapes and only one is a defect, so the check bounds the total and reports the rate over the tail of the sample beside it. A sender @@ -183,8 +197,46 @@ Two invariants failing on the *same* PCRs is one cause rather than two, which tw aggregate percentages cannot show. It is report-only: it explains a failure, it does not define one. +### Byte schedule + +A census of the whole capture reports the average rate, and an exporter padding to +a declared rate gets that right. A receiver recovering its clock from packet +arrival needs something narrower: the rate over every PCR interval. +`pcr-schedule` takes consecutive PCRs on one PID and compares the bytes between +them with what the mux rate implies for the interval between their values, +reporting the relative error's p1, median, p99 and worst, and the share within +tolerance. PCRs from different PIDs are never pooled: two PIDs on offset grids +pool into a grid of half the interval that neither of them keeps. + +One packet is always allowed. PCR packets sit on packet boundaries, so a mux whose +PCR values are on a time grid is up to a packet off at every interval even when its +schedule is exact, and below ~19 kB per interval one packet is more than 1 %. A +correct 2 Mb/s stream on a 25 ms grid reads −0.74 % and +2.27 % on alternate +intervals, which a percentage alone would fail. + +Give the rate whenever it is known. The estimate is total bytes over total time, +so a transient biases every interval by the same amount: over a 20 s live window, +the exporter's unpadded first half-second pulled it ~3 % low and read every padded +interval after it as off schedule. `run.sh` passes the generated clip's rate +(`--bitrate`), and lets the grader estimate for `--source`. + +The generated clip is a weak fixture for this check. It compresses to almost +nothing, so padding dominates and no keyframe outgrows its slot: measured against +the exporter this check was written for, 92-97 % of intervals were on schedule +over three 20 s runs, the misses being near-empty intervals from the unpadded +start. A real constant-rate capture is the case that +discriminates. A 60 s cut of a 9.95 Mb/s broadcast clip round-tripped through the +same harness came back with a median of 1,316 B between PCRs against 31,081 B +nominal and 3.1 % of intervals within tolerance, while its aggregate rate was +within 16 b/s of nominal: + +```bash +just test ts --source cap.ts --duration 60 # reports the schedule, estimating the rate +./pcr-timing.py sub.ts --mux-rate 9945951 --schedule-pct-min 99 # gates on it +``` + `--report-json ` writes the full report, and `--strict` promotes the shape -check to hard. +checks to hard. ## Table anchoring (`table-anchor.py`) diff --git a/test/ts/pcr-timing.py b/test/ts/pcr-timing.py index 4137f176ab0..b318fe39043 100755 --- a/test/ts/pcr-timing.py +++ b/test/ts/pcr-timing.py @@ -11,11 +11,16 @@ release when the bytes carrying them were handed over (--live only) position where the PCR packets sit among the media bytes +and a constant-rate stream makes a fourth, which `schedule` grades: that the bytes +between consecutive PCRs are the bytes the mux rate implies for that interval. + Every check is an invariant on the stream, not an assertion about how the stream was produced. `release` grades arrival against the PCR's *own* values rather than against a wall clock, so it needs no reference clock, no source file and no declared mux rate; the price is that a clock running at the wrong rate stays internally consistent under it and has to be caught by `value` and `position`. +`schedule` takes the rate from --mux-rate when the caller knows it, and otherwise +estimates it from the capture and says so. Exit status is 0 when every hard check passes, 1 otherwise. `--strict` promotes the report-only (shape) checks to hard. @@ -24,6 +29,7 @@ import argparse import collections import json +import math import select import statistics import sys @@ -461,6 +467,104 @@ def check_position(scan, args): ) +def check_schedule(scan, args): + """The bytes between consecutive PCRs must be the bytes the mux rate implies. + + `position` asks whether PCR packets are spread among the media bytes; this asks + whether they are spread at the right rate. A constant-rate stream is one where the + byte distance between two PCRs, over the time between their values, is the mux rate + for every interval and not merely on average, and that is what a receiver recovering + its clock from packet arrival depends on. A census of the whole capture cannot see + it: a stream padded to the right total with its bytes heaped between a few PCRs reads + as constant-rate in aggregate and at almost no individual interval. + + The rate comes from --mux-rate when the caller knows it, which also pins the absolute + rate the way nothing else here does. Otherwise it is estimated from the graded + intervals themselves, so the aggregate is right by construction and what is left to + grade is only how evenly the bytes are laid over the PCRs. The report says which. + The estimate is total bytes over total time, so a transient in a short sample, such + as a start that is not yet padded, biases every interval's error by the same amount; + pass the rate whenever it is known. + + Report-only unless --schedule-pct-min is given: a VBR stream has no schedule to keep, + and `export ts` is VBR unless a mux rate is declared, so only the caller knows whether + this property was promised. + """ + hard = args.schedule_pct_min is not None + severity = HARD if hard else SHAPE + required = args.schedule_pct_min if hard else 99.0 + # One PID only. Two PIDs each on a correct grid, offset from one another, pool into a + # grid of half the interval with half the bytes in each slot, which is a schedule + # neither of them keeps. pcr-single-pid already fails a stream carrying two; grading + # the busier one keeps this check's answer about one clock rather than about both. + pids = collections.Counter(pid for _, _, _, pid in scan.pcr) + pid = pids.most_common(1)[0][0] if pids else None + on_pid = [(k, e) for k, e in enumerate(scan.pcr) if e[3] == pid] + graded = [] + skipped = 0 + for (_, a), (kb, b) in zip(on_pid, on_pid[1:]): + seconds = (b[1] - a[1]) / TICKS_PER_MS / 1000.0 + # An interval spanning a signalled new time base measures nothing, as in the value + # check. A non-positive one is a duplicate packet (legal) or a backwards clock (the + # value check's defect to report); neither has a rate to compare against. + if kb in scan.new_base or seconds <= 0: + skipped += 1 + continue + graded.append(((b[0] - a[0]) * PKT, seconds)) + if len(graded) < 3: + # Asked to gate, an ungradable stream is a failure rather than a clean one. + return ("pcr-schedule", severity, not hard, "not measured (too few PCR intervals on one PID)", {}) + + aggregate = 8.0 * sum(n for n, _ in graded) / sum(s for _, s in graded) + rate = args.mux_rate if args.mux_rate else aggregate + source = "declared" if args.mux_rate else "estimated from the capture" + want = [rate * s / 8.0 for _, s in graded] + # Adding 0.0 turns an exact -0.0 into 0.0, so an exact schedule does not print as -0%. + err = [100.0 * (n / w - 1.0) + 0.0 for (n, _), w in zip(graded, want)] + # PCR packets can only sit on packet boundaries, so a mux whose PCR values are on a + # time grid is up to a packet off at every interval even when its schedule is exact. + # Below ~19 kB per interval one packet is more than 1 %, and a percentage alone would + # fail a correct low-rate stream on quantisation. + slack = [max(args.schedule_tolerance_pct / 100.0 * w, PKT) for w in want] + within = sum(1 for (n, _), w, s in zip(graded, want, slack) if abs(n - w) <= s) + median_s = statistics.median(s for _, s in graded) + detail = { + "pid": pid, + "other_pcr_pids": sorted(p for p in pids if p != pid), + "count": len(graded), + "skipped": skipped, + "rate_bps": round(rate), + "rate_source": "declared" if args.mux_rate else "estimated", + "aggregate_bps": round(aggregate), + "median_bytes": statistics.median(n for n, _ in graded), + "nominal_bytes_at_median_interval": round(rate * median_s / 8.0), + "min_bytes": min(n for n, _ in graded), + "max_bytes": max(n for n, _ in graded), + "rel_err_p1_pct": round(percentile(err, 1), 2), + "rel_err_median_pct": round(statistics.median(err), 2), + "rel_err_p99_pct": round(percentile(err, 99), 2), + "rel_err_max_abs_pct": round(max(abs(e) for e in err), 2), + "tolerance_pct": args.schedule_tolerance_pct, + "within_tolerance": within, + "within_tolerance_pct": round(100.0 * within / len(graded), 2), + "required_pct": required, + } + aggregate_note = f", aggregate {aggregate:,.0f} b/s" if args.mux_rate else "" + return ( + "pcr-schedule", + severity, + # The exact counts, not the rounded share: 20,000 of 20,001 rounds to 100. + 100.0 * within >= required * len(graded), + f"{within}/{len(graded)} intervals ({detail['within_tolerance_pct']:g}%) within " + f"±{args.schedule_tolerance_pct:g}% (or one packet) of the bytes {rate:,.0f} b/s implies " + f"({source}{aggregate_note}); median gap {detail['median_bytes']:,.0f} B against " + f"{detail['nominal_bytes_at_median_interval']:,} B, error p1 {detail['rel_err_p1_pct']:+g}% " + f"median {detail['rel_err_median_pct']:+g}% p99 {detail['rel_err_p99_pct']:+g}%, " + f"worst {detail['rel_err_max_abs_pct']:g}%", + detail, + ) + + CHECKS = [ check_sync, check_continuity, @@ -468,6 +572,7 @@ def check_position(scan, args): check_value_interval, check_release, check_position, + check_schedule, ] @@ -542,9 +647,35 @@ def main(): ap.add_argument( "--adjacent-pct-max", type=float, default=1.0, help="share of clustered PCRs before pcr-position flags" ) + ap.add_argument( + "--mux-rate", + type=float, + metavar="BPS", + help="the constant rate pcr-schedule grades against, in bits per second (default: estimated from the capture)", + ) + ap.add_argument( + "--schedule-tolerance-pct", + type=float, + default=1.0, + help="how far an interval's bytes may be from what the mux rate implies, as a percentage; " + "one packet is always allowed (default 1)", + ) + ap.add_argument( + "--schedule-pct-min", + type=float, + metavar="PCT", + help="share of PCR intervals that must be within the schedule tolerance; giving it makes " + "pcr-schedule a hard check (default: report-only, flagging below 99)", + ) ap.add_argument("--strict", action="store_true", help="fail on shape checks too") ap.add_argument("--report-json", help="write the full report here") args = ap.parse_args() + for flag in ("mux_rate", "schedule_tolerance_pct", "schedule_pct_min"): + value = getattr(args, flag) + if value is not None and not math.isfinite(value): + ap.error(f"--{flag.replace('_', '-')} must be finite") + if args.mux_rate is not None and args.mux_rate <= 0: + ap.error("--mux-rate must be positive") if args.live: scan = scan_live(args.seconds) diff --git a/test/ts/run.sh b/test/ts/run.sh index 1b3ad5b0aa4..ea87b5eddec 100755 --- a/test/ts/run.sh +++ b/test/ts/run.sh @@ -282,6 +282,16 @@ harness_endpoint relay "$URL" # (a file has none left in it). It stops itself after its own window, so the # round-trip below still bounds the run. +# SCHEDULE carries the rate pcr-timing.py's schedule check grades against. The +# generated clip is muxed at $BITRATE, which is the rate the catalog records and the +# exporter pads to. Left to estimate, the grader divides total bytes by the PCR span, +# and any transient drags that off the true rate: an unpadded first half-second put it +# ~3 % low over a 20 s window, which then read every correctly padded interval as off +# schedule. A --source capture's rate is not known here, so for that the grader +# estimates it and says so. +SCHEDULE=() +[[ -z "$SOURCE" ]] && SCHEDULE=(--mux-rate "$BITRATE") + # Both halves matter and `wait` can only report one, so record each. The # exporter's own status is not incidental here: it decides whether the grader saw # the whole window or graded a stream that ended under it. @@ -293,7 +303,7 @@ grade_live() { timeout -k 3 $((DURATION + 20)) \ "$MOQ" --connect "$URL" --broadcast "$BROADCAST" export ts 2>"$HARNESS_RUN/sub.log" | python3 "$DIR/pcr-timing.py" --live --seconds "$DURATION" --release-pct-max 1 $STRICT \ - ${PASSTHRU[@]+"${PASSTHRU[@]}"} >"$HARNESS_RUN/timing.out" 2>&1 + ${SCHEDULE[@]+"${SCHEDULE[@]}"} ${PASSTHRU[@]+"${PASSTHRU[@]}"} >"$HARNESS_RUN/timing.out" 2>&1 printf '%s\n' "${PIPESTATUS[0]} ${PIPESTATUS[1]}" >"$HARNESS_RUN/timing.rc" } @@ -478,3 +488,15 @@ if ! analyze "$SUB_TS" "$SRC_TS"; then dump_logs exit 1 fi + +# compliance.py grades rate in aggregate and over fixed windows, neither of which says +# whether the bytes between consecutive PCRs are the ones the mux rate implies, so the +# capture goes through pcr-timing.py as well. Its hard checks gate here as they do under +# --live; pcr-schedule is a shape check, so it reports without gating unless --strict. +echo +if ! python3 "$DIR/pcr-timing.py" "$SUB_TS" ${SCHEDULE[@]+"${SCHEDULE[@]}"} $STRICT; then + echo >&2 + echo "error: PCR timing analysis failed (see round-trip logs below)" >&2 + dump_logs + exit 1 +fi From dd50276b200fe49152a2c0c3cddf137d70c458bc Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 10:01:16 -0700 Subject: [PATCH 013/128] fix(ci): only save Rust caches after successful jobs (#4487) Co-authored-by: GPT-6 --- .github/actions/rust-cache/action.yml | 2 ++ .github/workflows/interop.yml | 1 - .github/workflows/swift.yml | 1 - quest/m1/README.md | 1 - quest/m1/ci-hygiene.md | 25 ------------------------- 5 files changed, 2 insertions(+), 28 deletions(-) delete mode 100644 quest/m1/ci-hygiene.md diff --git a/.github/actions/rust-cache/action.yml b/.github/actions/rust-cache/action.yml index 572c730101a..43727027141 100644 --- a/.github/actions/rust-cache/action.yml +++ b/.github/actions/rust-cache/action.yml @@ -12,6 +12,8 @@ inputs: runs: using: composite steps: + # The pinned action saves in a post step guarded by success(), so failed + # builds cannot publish a cache even when dispatch saving is enabled. - uses: jdx/mr-boxington-action@7234d3dd1a6ca8f6c381eea8e4dfb03f18fcf777 # v1.3.0 with: version: 1.10.0 diff --git a/.github/workflows/interop.yml b/.github/workflows/interop.yml index 6246ef393a8..f2f95de0178 100644 --- a/.github/workflows/interop.yml +++ b/.github/workflows/interop.yml @@ -72,7 +72,6 @@ jobs: - name: Rust cache uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2 with: - cache-on-failure: true # A pull request's entry is scoped to its own branch, where no later # run reads it, while it spends the budget the shared store needs. save-if: ${{ github.event_name != 'pull_request' }} diff --git a/.github/workflows/swift.yml b/.github/workflows/swift.yml index 8c3cdcbfab8..bc7cdd98b7b 100644 --- a/.github/workflows/swift.yml +++ b/.github/workflows/swift.yml @@ -66,7 +66,6 @@ jobs: # none of which depend on the event, so a pull request restores what a # push saved. save-if: ${{ github.event_name == 'push' }} - cache-on-failure: true - name: Rust simulator check shell: bash diff --git a/quest/m1/README.md b/quest/m1/README.md index 8c4127c6880..53166c83383 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -52,7 +52,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Legacy end overshoot](/quest/m1/legacy-end-overshoot.md) - browser playback survives a group that starts inside the previous group's estimated end - [UnknownSession log flood](/quest/m1/unknown-session-logs.md) - streams reset before their WebTransport header stop being reported as UnknownSession at WARN - [Merge queue](/quest/m1/merge-queue.md) - the required checks run on `merge_group`, so a stale green check can no longer break main -- [CI hygiene](/quest/m1/ci-hygiene.md) - a push to one PR never cancels another's run, and a failed run never saves the Rust cache - [Wire compatibility](/quest/m1/wire-compat.md) - a nightly run tests this checkout against the last published release for tokens, session wire, and catalog/container - [Full codec string](/quest/m1/publish-codec-string.md) - browser-published video carries the encoder's full RFC 6381 codec string, so native players decode it - [TS program selection](/quest/m1/ts-programs.md) - `import ts` refuses a multi-program stream unless `--program ` picks one or publishes each diff --git a/quest/m1/ci-hygiene.md b/quest/m1/ci-hygiene.md deleted file mode 100644 index b535f60eb56..00000000000 --- a/quest/m1/ci-hygiene.md +++ /dev/null @@ -1,25 +0,0 @@ -# [XS] CI runs don't cancel each other or cache a broken build - -## Goal - -A push to one PR never cancels another PR's run, and a failed run never -saves the Rust cache later runs restore. - -## Plan - -- Concurrency: `check.yml`, `obs.yml`, `android.yml`, `wasm.yml`, and - `interop.yml` group by `${{ github.ref }}` only. Key them by event and PR - number the way `platform.yml` does (#4370). A `pull_request` run's - `github.ref` is already `refs/pull//merge`, so first find which runs - actually shared a group, and confirm the new key separates them. -- Cache: `interop.yml` and `swift.yml` set Swatinem's - `cache-on-failure: true`; #4384's interop cache got saved broken that way - (`failed to run custom build command for aws-lc-rs`). Drop it. Check - whether the shared `.github/actions/rust-cache` saves on failure, and make - it save only on success. - -Public API: none. Wire: none. - -## Related - -- [Merge queue](/quest/m1/merge-queue.md) - also touches the concurrency groups for queue refs From 1eca8773b24e8bc57e681733fff0ba86b5f58b04 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 10:04:36 -0700 Subject: [PATCH 014/128] fix(gst): recover from leading deltas and timestamp rewinds (#4480) Co-authored-by: GPT-6 --- doc/bin/gstreamer.md | 6 +++ quest/m1/README.md | 1 - quest/m1/moqsink-keyframe-latch.md | 34 --------------- rs/moq-gst/src/sink/pad.rs | 69 +++++++++++++++++++++++++++--- 4 files changed, 68 insertions(+), 42 deletions(-) delete mode 100644 quest/m1/moqsink-keyframe-latch.md diff --git a/doc/bin/gstreamer.md b/doc/bin/gstreamer.md index fa2cc877e5e..117064a59a6 100644 --- a/doc/bin/gstreamer.md +++ b/doc/bin/gstreamer.md @@ -88,6 +88,12 @@ timeline epoch and resets the handoff baseline. The pause does not inflate advertised jitter, and previously measured maxima remain. Resumed timestamps must continue forward on the broadcast media clock. +A video pad joining mid-GOP drops delta frames until its first keyframe. If a +source rewinds below the producer's live edge without signalling a break, the +pad drops that frame and waits for a keyframe at or beyond the live edge. It +keeps the rendition alive and preserves the media timeline; it does not shift +rewound timestamps forward. + ## moqsrc Pads are named by kind and appear as the catalog announces renditions: diff --git a/quest/m1/README.md b/quest/m1/README.md index 53166c83383..ca614f22370 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -32,7 +32,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [WebTransport close upstream](/quest/m1/wt-close-upstream.md) - web-transport-moq delivers the close capsule itself, and moq-tokio's `CLOSE_LINGER` is deleted - [IETF hidden default](/quest/m1/ietf-hidden-default.md) - a moq-transport peer without the MoQ Hidden option is advertised hidden namespaces; one with it filters per subscription - [Watch refusal](/quest/m1/watch-refusal.md) - `` shows an origin refusal as an error instead of sitting offline -- [moqsink recoverable errors](/quest/m1/moqsink-keyframe-latch.md) - a leading delta or a timestamp rewind drops frames until a keyframe instead of invalidating a moqsink pad - [Splice edge cases](/quest/m1/splice-edges.md) - an unstamped successor, a pruned segment's boundary group, and a warm head during a takeover are each handled correctly - [Resumed groups](/quest/m1/resume-latest.md) - a half-delivered group ends once the new copy is past it, so a group-only reader never parks after a mid-group failover - [Track tail hardening](/quest/m1/track-tail-hardening.md) - Rust and JS wait out a track's tail by the same rules, with the known hang, count, truncation, grace, and memory holes closed diff --git a/quest/m1/moqsink-keyframe-latch.md b/quest/m1/moqsink-keyframe-latch.md deleted file mode 100644 index 5cb8205681b..00000000000 --- a/quest/m1/moqsink-keyframe-latch.md +++ /dev/null @@ -1,34 +0,0 @@ -# [S] moqsink drops frames on recoverable importer errors - -## Goal - -A `moqsink` pad survives the importer errors moq-mux documents as -recoverable: it drops frames until the next keyframe instead of calling -`self.fail()` and losing the rendition for good. Two paths reach that -failure in `Media::write` (`rs/moq-gst/src/sink/pad.rs`) today: - -- A new pad starts unlatched (`keyframe: false`), so a first buffer that is a - delta frame fails it. -- A `TimestampRewind` with no signalled break (an rtspsrc jitterbuffer - re-anchoring) has no guard at all. - -## Plan - -The header-only buffer after a break was fixed in -https://github.com/moq-dev/moq/pull/4356: the latch stays armed after a -successful decode. Reuse that latch here. - -Decided: a video pad starts latched. On `TimestampRewind`, set the latch and -drop until a keyframe lands above the producer's live edge, losing up to one -GOP per re-anchor. Mapping a rewound timeline forward instead belongs to -[#3021](/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md). -The reporter offered the guard they run in production. - -Regression tests beside `video_pause_drops_deltas_until_the_next_keyframe`: - -- A new pad's first buffer is a delta: it drops. -- A rewind without a break: deltas drop until a keyframe above the edge. - -## Closes - -- [#4366](https://github.com/moq-dev/moq/issues/4366) - close this issue when the quest finishes diff --git a/rs/moq-gst/src/sink/pad.rs b/rs/moq-gst/src/sink/pad.rs index f9b68dd37bc..210bfce422e 100644 --- a/rs/moq-gst/src/sink/pad.rs +++ b/rs/moq-gst/src/sink/pad.rs @@ -51,16 +51,15 @@ struct Media { encoder: bool, /// Apply a timeline break before the next valid frame, using the normal write error path. discontinuity: bool, - /// A video break closed the group, and a pause resumes mid-GOP, so deltas drop until a keyframe - /// opens the next one. Stays set once armed: a successful decode may publish nothing (a - /// header-only buffer), and a delta only misses its keyframe while no group is open, which for - /// video means after a break. + /// Video can start or resume mid-GOP, so deltas drop until a keyframe opens a group. Stays set: + /// a successful decode may publish nothing (a header-only buffer), and a delta only misses its + /// keyframe while no group is open. keyframe: bool, } impl Media { /// Publish one frame at `micros` on the media clock, handed over at `now`. Returns false when a - /// delta frame is dropped while waiting for the keyframe after a break. + /// frame is dropped while waiting for a keyframe at or beyond the live edge. fn write(&mut self, data: &Bytes, micros: u64, now: Instant) -> Result { if std::mem::take(&mut self.discontinuity) { self.track.discontinuity()?; @@ -69,6 +68,12 @@ impl Media { let ts = hang::container::Timestamp::from_micros(micros).ok(); match self.track.decode(data, ts) { Err(moq_mux::Error::MissingKeyframe(_)) if self.keyframe => return Ok(false), + Err(moq_mux::Error::TimestampRewind(_)) => { + // A rejected delta leaves its group open; later deltas cannot decode across that gap. + self.track.cut(None)?; + self.keyframe = !self.audio; + return Ok(false); + } result => result?, } // One group (one QUIC stream) per audio packet, so the relay forwards it without waiting for @@ -484,7 +489,7 @@ impl Pad { audio, encoder, discontinuity: false, - keyframe: false, + keyframe: !audio, }))); self.caps = Some(caps.clone()); Ok(name) @@ -706,7 +711,10 @@ impl Pad { let result: Result<()> = match self.track.as_mut().expect("track present") { Sink::Media(media) => match media.write(&data, micros, now) { Ok(false) => { - gst::debug!(CAT, "dropping delta frame until the keyframe after a break"); + gst::debug!( + CAT, + "dropping frame until the next decodable frame at or beyond the live edge" + ); return Ok(PushOutcome::Dropped); } result => result.map(|_| ()), @@ -1735,6 +1743,53 @@ mod tests { } } + #[test] + fn video_start_drops_deltas_until_the_first_keyframe() { + gst::init().unwrap(); + let (broadcast, catalog) = producers(); + let mut pad = Pad::new(); + pad.observe_caps(&broadcast, &catalog, producer_options(&h264_caps(), Some("video"))); + pad.observe_segment(time_segment()); + let delta = Bytes::from_static(&[0, 0, 0, 1, 0x61, 0xe0, 0x12, 0x34]); + let now = Instant::now(); + let push = |pad: &mut Pad, data: Bytes, pts: u64| { + pad.push_buffer(data, Some(gst::ClockTime::from_mseconds(pts)), None, None, now) + .unwrap() + }; + assert_eq!(push(&mut pad, delta.clone(), 0), PushOutcome::Dropped); + assert!(!pad.is_failed()); + assert_eq!(push(&mut pad, delta.clone(), 33), PushOutcome::Dropped); + assert_eq!(push(&mut pad, h264_keyframe_au(), 66), PushOutcome::Published); + assert_eq!(push(&mut pad, delta, 100), PushOutcome::Published); + } + + #[test] + fn video_rewind_drops_deltas_until_a_keyframe_clears_the_live_edge() { + gst::init().unwrap(); + let delta = Bytes::from_static(&[0, 0, 0, 1, 0x61, 0xe0, 0x12, 0x34]); + for rewind in [delta.clone(), h264_keyframe_au()] { + let (broadcast, catalog) = producers(); + let mut pad = Pad::new(); + pad.observe_caps(&broadcast, &catalog, producer_options(&h264_caps(), Some("video"))); + pad.observe_segment(time_segment()); + let now = Instant::now(); + let push = |pad: &mut Pad, data: Bytes, pts: u64| { + pad.push_buffer(data, Some(gst::ClockTime::from_mseconds(pts)), None, None, now) + .unwrap() + }; + assert_eq!(push(&mut pad, h264_keyframe_au(), 0), PushOutcome::Published); + assert_eq!(push(&mut pad, delta.clone(), 33), PushOutcome::Published); + assert_eq!(push(&mut pad, h264_keyframe_au(), 100), PushOutcome::Published); + assert_eq!(push(&mut pad, delta.clone(), 133), PushOutcome::Published); + assert_eq!(push(&mut pad, rewind, 16), PushOutcome::Dropped); + assert!(!pad.is_failed()); + assert_eq!(push(&mut pad, delta.clone(), 166), PushOutcome::Dropped); + assert_eq!(push(&mut pad, h264_keyframe_au(), 66), PushOutcome::Dropped); + assert_eq!(push(&mut pad, h264_keyframe_au(), 200), PushOutcome::Published); + assert_eq!(push(&mut pad, delta.clone(), 233), PushOutcome::Published); + } + } + // A pause resumes mid-GOP: the break closed the group, so deltas drop until the next keyframe // instead of invalidating the pad. #[test] From 96362045a57ad911e394db6b644af84184823e67 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 09:59:08 -0700 Subject: [PATCH 015/128] fix(net): wake a parked read on its unstamped successor's first frame Co-Authored-By: Claude Opus 5.5 --- rs/moq-net/src/model/resume.rs | 35 ++++++++++++++++++++++++++++++++++ rs/moq-net/src/model/track.rs | 25 ++++++++++++++++-------- 2 files changed, 52 insertions(+), 8 deletions(-) diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index eb8fca98509..307843f1309 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -3324,6 +3324,41 @@ mod test { ); } + /// A handed-out group parked at its tail is re-judged once its unstamped successor in + /// the next segment presents a first frame. That frame touches only the successor's + /// group, not either track or the drift anchor, so the read has to watch it directly. + #[tokio::test] + async fn unstamped_successor_first_frame_wakes_a_parked_read() { + use std::task::Context; + + let (a, a_read) = track_pair("a"); + let (mut b, b_read) = track_pair("b"); + let mut head = a.create_group(0u64.into()).unwrap(); + head.write_frame(Timestamp::ZERO, b"a0".to_vec()).unwrap(); + let mut successor = b.create_group(1u64.into()).unwrap(); + write_group_at(&mut b, 2, "edge", Duration::from_secs(20)); + let mut producer = Producer::new(); + producer.switch(a_read, None).unwrap(); + producer.switch(b_read, Position::group(1)).unwrap(); + let mut sub = producer.consume().subscribe(None); + let mut reading = sub.recv_group().now_or_never().unwrap().unwrap().unwrap(); + assert_eq!(reading.sequence, 0, "an unbounded reach is not stale"); + assert_eq!(read(&mut reading), b"a0"); + + let (counter, waker) = CountWaker::new(); + let mut cx = Context::from_waker(&waker); + let mut next = std::pin::pin!(reading.read_frame()); + assert!(next.as_mut().poll(&mut cx).is_pending()); + + let before = counter.count(); + successor + .write_frame(Duration::from_secs(1).try_into().unwrap(), b"b1".to_vec()) + .unwrap(); + assert!(counter.count() > before, "the successor's first frame lost its wakeup"); + let result = next.as_mut().poll(&mut cx); + assert!(matches!(result, Poll::Ready(Ok(None))), "the head is stale: {result:?}"); + } + #[tokio::test] async fn pruned_segment_boundary_is_judged_against_later_segments() { let (mut a, a_read) = track_pair("a"); diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index d7d4f055a60..502dfbefe91 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -630,7 +630,7 @@ impl TrackState { .filter(|live| self.holds(live.sequence, live.stamp)) .map(|live| (live.sequence, live.timestamp)); // `outer` and `successor` were revalidated on their own tracks before this lock - // was taken ([`LiveEdge::is_live`], [`Successor::start`]). There is no slot for + // was taken ([`LiveEdge::is_live`], [`Successor::poll_start`]). There is no slot for // them here, and taking their locks here would nest. let Some((_, timestamp)) = local .into_iter() @@ -3208,7 +3208,10 @@ impl group::Expiry for GroupExpiry { .edge .filter(LiveEdge::is_live) .map(|live| (live.sequence, live.timestamp)); - let successor = anchor.successor.as_ref().and_then(Successor::start); + let successor = anchor + .successor + .as_ref() + .and_then(|successor| successor.poll_start(waiter)); let mut expired = false; let _ = self.state.poll(waiter, |state| { @@ -3297,8 +3300,9 @@ pub(crate) struct Anchor { /// Where the reader's next group past `cap` starts presenting, when another track /// serves it (a splice's next segment). The last group below the cap has no /// successor in its own track, so without this nothing bounds its reach and it is - /// never judged stale. `None` while unknown or unstamped. Revalidated like `edge`: - /// a cached start must not convict once that group is gone. + /// never judged stale. `None` while unknown; an unstamped group leaves reach unbounded + /// until its first frame. Revalidated like `edge`: a cached start must not convict + /// once that group is gone. pub successor: Option, } @@ -3365,14 +3369,16 @@ pub(crate) struct Successor { impl Successor { /// The start this still names, re-read from its own track, or `None` once that - /// group is gone or no longer stamped. Takes that track's lock, so never call it - /// under another's. - fn start(&self) -> Option { + /// group is gone or while it is unstamped. An unstamped start registers `waiter` for + /// the first frame, which bounds a reach without touching either track. Takes that + /// track's lock, so never call it under another's. + fn poll_start(&self, waiter: &kio::Waiter) -> Option { let state = self.track.read(); let slot = state.lookup.get(&self.sequence)?; if slot.stamp != self.stamp || slot.group.is_aborted() { return None; } + let _ = slot.group.poll_timestamp(waiter); slot.group.timestamp() } } @@ -3525,7 +3531,10 @@ impl PlainSubscriber { .as_ref() .filter(|live| live.is_live()) .map(|live| (live.sequence, live.timestamp)); - let successor = drift.successor.as_ref().and_then(Successor::start); + let successor = drift + .successor + .as_ref() + .and_then(|successor| successor.poll_start(waiter)); let presentation = drift.edge.presentation; let cap = drift.edge.cap; let budget = drift.budget; From 434ab81f5c1e251402c403772c83fc021931b6d7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 10:08:12 -0700 Subject: [PATCH 016/128] fix(net): align IETF object extension limits (#4475) Co-authored-by: GPT-6 --- doc/concept/standard.md | 5 ++ js/net/src/ietf/object.ts | 7 +++ js/net/src/ietf/subscriber.test.ts | 42 ++++++++++++++- rs/moq-net/src/ietf/subscriber.rs | 84 +++++++++++++++++++++++++++++- 4 files changed, 135 insertions(+), 3 deletions(-) diff --git a/doc/concept/standard.md b/doc/concept/standard.md index b8a6ed81817..54801adec8a 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -26,6 +26,11 @@ maps everything else to "not supported" or a harmless equivalent. The [moq-lite page](/concept/moq-lite#what-moq-lite-leaves-out) lists the differences. +Rust and JavaScript subscribers accept object extension blocks up to 64 KiB. +This is an implementation limit, not a limit in the IETF draft. A larger +declared block stops its subgroup stream with `MALFORMED_TRACK` before reading +the block; other groups and the session stay open. + An IETF publisher declares the track's default priority in `SUBSCRIBE_OK` or `PUBLISH` when that draft carries track properties. Groups without a priority flag inherit it. If the property is absent, the IETF wire default of 128 maps diff --git a/js/net/src/ietf/object.ts b/js/net/src/ietf/object.ts index ab37261e0ab..a5584da0334 100644 --- a/js/net/src/ietf/object.ts +++ b/js/net/src/ietf/object.ts @@ -1,7 +1,11 @@ +import { StreamCode, Stream as StreamError } from "../error.ts"; import { type Cursor, type Reader, Writer } from "../stream.ts"; import { Timescale, Timestamp } from "../time.ts"; import { type IetfVersion, Version } from "./version.ts"; +// Implementation limit for object extension blocks, independent of the IETF draft. +const MAX_OBJECT_EXTENSIONS = 64 * 1024; + const GROUP_END = 0x03; const END_OF_TRACK = 0x04; @@ -321,6 +325,9 @@ export class Frame { let timestamp: Timestamp | undefined; if (flags.hasExtensions) { const extensionsLength = c.u53(); + if (extensionsLength > MAX_OBJECT_EXTENSIONS) { + throw new StreamError(StreamCode.MalformedTrack, { message: "object extensions exceed 64 KiB" }); + } // A track that declared no timescale opted out of timestamps, so its objects // are stamped on arrival even if one carries a Timestamp we cannot interpret. if (timescale !== undefined) { diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index fe2bbe0a2a0..d558e148fc9 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -1,6 +1,6 @@ import { expect, spyOn, test } from "bun:test"; import type * as announce from "../announced.ts"; -import { ProtocolViolation } from "../error.ts"; +import { ProtocolViolation, StreamCode, Stream as StreamError } from "../error.ts"; import { type Hop, HopSchema } from "../hop.ts"; import { createMockTransportPair } from "../mock.ts"; import * as Path from "../path.ts"; @@ -1059,3 +1059,43 @@ test("returning demand survives a blocked unsubscribe", async () => { broadcast.close(); session.close(); }); + +test("object extension limit accepts 64 KiB and stops one byte over before reading", async () => { + for (const size of [65536, 65537]) { + for (const first of [true, false]) { + const { subscriber, track } = await subscribeTrack(); + const bytes = new Uint8Array((first ? 0 : 4) + 4 + (size === 65536 ? size + 2 : 0)); + let offset = 0; + if (!first) { + bytes.set([0, 0, 1, 42]); + offset = 4; + } + // Object delta zero followed by a three-byte leading-ones varint length. + bytes.set([0, 0xc1, 0, size - 65536], offset); + if (size === 65536) bytes.set([1, 42], bytes.length - 2); + const reader = new Reader(undefined, bytes, VERSION); + const stop = spyOn(reader, "stop"); + const header = new GroupMessage({ + trackAlias: ALIAS, + groupId: 3, + subGroupId: 0, + publisherPriority: 0, + flags: { ...groupFlags(true), hasExtensions: true }, + }); + await subscriber.handleGroup(header, reader); + if (size === 65536) { + expect(stop.mock.calls).toEqual([]); + const group = await track.ordered().nextGroup(); + expect(group?.frameCount).toBe(first ? 1 : 2); + expect(await group?.readString()).toBe("*"); + } else { + expect(stop).toHaveBeenCalledTimes(1); + const err = stop.mock.calls[0][0]; + expect(err).toBeInstanceOf(StreamError); + expect((err as StreamError).code).toBe(StreamCode.MalformedTrack); + } + stop.mockRestore(); + track.close(); + } + } +}); diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index b2cea32c262..000610327d2 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -2263,6 +2263,11 @@ where Err(err @ (Error::Cancel | Error::Stream(crate::StreamError::Cancel))) => { let _ = producer.abort(err); } + Err(err @ Error::Decode(DecodeError::MessageTooLarge { .. })) => { + let _ = producer.abort(err.clone()); + // Return the refusal to the dispatcher so it sends STOP_SENDING. + return Err(err); + } Err(err) => { tracing::debug!(%err, group = %producer.sequence, "group error"); let _ = producer.abort(err); @@ -2320,6 +2325,25 @@ enum Ended { /// Object status: no object at or past this location exists (every implemented draft). const END_OF_TRACK: u64 = 0x4; +// Implementation limit for object extension blocks, independent of the IETF draft. +const MAX_OBJECT_EXTENSIONS: usize = 64 * 1024; + +#[derive(Debug)] +struct ObjectExtensionsLength(usize); + +impl Decode for ObjectExtensionsLength { + fn decode(buf: &mut B, version: Version) -> Result { + let size = usize::decode(buf, version)?; + if size > MAX_OBJECT_EXTENSIONS { + return Err(DecodeError::MessageTooLarge { + size, + max: MAX_OBJECT_EXTENSIONS, + }); + } + Ok(Self(size)) + } +} + /// The start of a subgroup stream's first object, peeked before its group is created. #[derive(Debug, Clone, Copy)] struct FirstObject { @@ -2336,7 +2360,7 @@ impl Decode for PeekFirst { fn decode(buf: &mut B, version: Version) -> Result { let id = u64::decode(buf, version)?; if EXTENSIONS { - let size = usize::decode(buf, version)?; + let ObjectExtensionsLength(size) = ObjectExtensionsLength::decode(buf, version)?; if buf.remaining() < size { return Err(DecodeError::Short); } @@ -2930,7 +2954,7 @@ impl GroupIngest { }; } IngestPhase::ExtSize => { - let size: usize = ready!(reader.poll_decode(&mut cx))?; + let ObjectExtensionsLength(size) = ready!(reader.poll_decode(&mut cx))?; self.phase = IngestPhase::ExtBytes { size }; } IngestPhase::ExtBytes { size } => { @@ -5998,6 +6022,62 @@ mod stitch_tests { assert!(matches!(*h.fill.read(), Fill::Done), "the head was claimed"); } + #[tokio::test] + async fn object_extension_limit() { + for size in [65536usize, 65537] { + for first in [true, false] { + let mut script = Vec::new(); + ietf::GroupHeader { + track_alias: ALIAS, + group_id: SEQUENCE, + sub_group_id: 0, + publisher_priority: 0, + flags: ietf::GroupFlags { + has_extensions: true, + ..Default::default() + }, + } + .encode(&mut script, VERSION) + .unwrap(); + if !first { + // A complete first object exercises the ingestion path on the next one. + script.extend_from_slice(&[0, 0, 1, 42]); + } + 0u64.encode(&mut script, VERSION).unwrap(); + size.encode(&mut script, VERSION).unwrap(); + if size == 65536 { + // Unknown even properties with value zero, valid with delta type ids. + script.resize(script.len() + size, 0); + script.extend_from_slice(&[1, 42]); + } + // Over-limit lengths deliberately carry no extension bytes. + let h = Harness::new(Fill::Done, vec![script]); + let mut consumer = h.track.subscribe(None); + let mut stream = h.stream().await; + let result = h.subscriber.clone().recv_group(&mut stream).await; + if size == 65536 { + result.unwrap(); + let (_, frames) = read_group(&mut consumer).await; + assert_eq!(frames.len(), if first { 1 } else { 2 }); + } else { + assert!(matches!( + result, + Err(Error::Decode(DecodeError::MessageTooLarge { + size: 65537, + max: 65536 + })) + )); + // The stream dispatcher uses this mapping to stop only this stream. + assert_eq!( + crate::StreamError::from(&result.unwrap_err()), + crate::StreamError::MalformedTrack + ); + } + assert!(h.session.log.closes().is_empty()); + } + } + } + /// Append an END_OF_TRACK object: delta 0, an empty payload, then its status. fn end_of_track(mut stream: Vec) -> Vec { for value in [0u64, 0, END_OF_TRACK] { From 0c5489fc496bf2b5de0f79ac53feef3834647ee7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 10:09:03 -0700 Subject: [PATCH 017/128] fix(net): preserve cached history for late relay subscribers (#4472) Co-authored-by: Codex --- quest/m1/README.md | 1 - quest/m1/relay-late-joiner-history.md | 44 ------------- quest/m1/track-tail-interop.md | 1 - rs/moq-net/src/model/origin.rs | 10 +++ rs/moq-net/tests/history_groups.rs | 91 +++++++++++++++++++++++++++ 5 files changed, 101 insertions(+), 46 deletions(-) delete mode 100644 quest/m1/relay-late-joiner-history.md diff --git a/quest/m1/README.md b/quest/m1/README.md index ca614f22370..3c16e80f49a 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -17,7 +17,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. ## Required -- [Late joiner history](/quest/m1/relay-late-joiner-history.md) - a subscriber joining a relay's track from group 0 later still receives the cached finished group below the live one - [Cluster routing](/quest/m1/cluster-routing.md) - an announcement says where a broadcast originates, not how to reach it, and a relay hears only the prefixes its clients asked for - [Exact scope](/quest/m1/exact-scope.md) - a reader never sees an exact broadcast outside its scope, in Rust or JS; prefix routes above it still present as the empty path - [Track tail interop](/quest/m1/track-tail-interop.md) - a Rust publisher ending a track with a group in flight is read to its end by the JS subscriber, and the reverse, in `just test interop` diff --git a/quest/m1/relay-late-joiner-history.md b/quest/m1/relay-late-joiner-history.md deleted file mode 100644 index bd041dc43ce..00000000000 --- a/quest/m1/relay-late-joiner-history.md +++ /dev/null @@ -1,44 +0,0 @@ -# [M] Late joiner history - -## Goal - -A second subscriber that joins a relay's track from group 0 while a first -subscriber still holds it receives every group the relay has cached, -including a finished group older than the open live one. A regression test -that joins late through a relay fails before the fix. - -## Plan - -Found downstream on moq.pro: its billing rollup tracks replay a finished -history group followed by an open live group, and a second browser opening -the Cost page on the same edge intermittently loses the older group, so -prior-period usage rows are missing. Production dashboards are affected, -not just tests. #4387 fixed the first viewer's version of this; what it -leaves is the viewer that joins later. - -What we saw: - -- With #4387 applied, moq.pro's `e2e/tests/rollup-history.spec.ts - --repeat-each 12` still fails about a quarter of runs, always on the - second viewer. The edge logs `serving group` only for the newer group on - that viewer's subscription, while the first viewer got both. -- A late-joiner variant of `rs/moq-net/tests/history_groups.rs` showed the - relay's late cursor spliced across two segments with its floor at the - newer group, so the cached older group sat below it. The segment churn - comes through `Action::Query`, `Splice`, `Park`, and `Release` in - `rs/moq-net/src/model/origin.rs`, triggered by the TRACK_INFO request that - precedes each subscription and then goes idle. -- That variant is not a faithful reproduction yet: under paused time the - origin's linger timers fire during the test's idle waits, so it also failed - for lite-03 and the IETF drafts, which the real stack does not. A - reproduction needs to keep the relay's track warm without auto-advancing - past the linger, or drive the timers explicitly. - -Start from how a newly spliced or parked segment derives its floor for a -subscriber that asked for group 0, and whether a warm copy's cached groups -below the new segment's first group stay reachable. The -[splice edge cases](/quest/m1/splice-edges.md) touch the same code. - -## Related - -- [Splice edge cases](/quest/m1/splice-edges.md) - other spliced-track cases that lose or mis-judge groups diff --git a/quest/m1/track-tail-interop.md b/quest/m1/track-tail-interop.md index 01b0a683388..f33cff39350 100644 --- a/quest/m1/track-tail-interop.md +++ b/quest/m1/track-tail-interop.md @@ -41,7 +41,6 @@ delivered and clean. The ordering race itself stays in the unit tests. ## Required - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - publishers name every group they won't deliver, which the lite-07 case checks -- #4387 merges: a relayed subscription resolves its start from its source, so earlier in-flight groups are not lost (it adds quest/m1/relay-late-joiner-history.md) ## Related diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index d39e9c206f1..8fa6facb730 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -2095,6 +2095,7 @@ fn warm_copy(source: &track::Consumer, head: Option<&WarmGroup>) -> Option) -> Option= latest); if head.is_finished() { let _ = track.adopt_group(head.clone(), true); + first = Some(head.sequence); if is_latest { edge = Some(WarmGroup(head.clone())); } } else if is_latest { edge = warm_rebuild(&track, head, None); + first = edge.as_ref().map(|_| head.sequence); } } @@ -2131,10 +2134,17 @@ fn warm_copy(source: &track::Consumer, head: Option<&WarmGroup>) -> Option 3, + 6 => 2, + sequence => panic!("unexpected group {sequence}"), + }; + for _ in 0..frames { + assert!(group.read_frame().await.unwrap().is_some()); + } + sequences.push(group.sequence); + } + sequences.sort(); + assert_eq!(sequences, [5, 6]); +} + +#[tokio::test] +async fn a_late_subscriber_receives_the_relays_cached_history() { + tokio::time::pause(); + // Older drafts canonicalize group 0 to the live edge instead of replay. + let version: Version = "moq-lite-07-wip".parse().unwrap(); + let publisher = produce_origin(1); + let broadcast = publisher.create_broadcast("bcast").unwrap(); + let track = broadcast + .create_track("history", Info::default().with_max_age(FOREVER)) + .unwrap(); + broadcast.announce(Default::default()).unwrap(); + let relay = produce_origin(2); + let mut options = MockConnectOptions::new(version); + options.server_publish = Some(publisher.consume()); + options.client_subscribe = Some(relay.clone()); + let upstream = connect_mock(options).await; + let first = produce_origin(3); + let mut options = MockConnectOptions::new(version); + options.server_publish = Some(relay.consume()); + options.client_subscribe = Some(first.clone()); + let first_pair = connect_mock(options).await; + let consumer = first.consume(); + consumer.routed("bcast").await.unwrap(); + let remote = consumer.request_broadcast("bcast").await.unwrap(); + let subscription = Subscription::default() + .with_max_age(FOREVER) + .with_start(Position::group(0)); + let first_subscription = subscription.clone(); + let first_reader = tokio::spawn(async move { + let mut sub = remote + .track("history") + .unwrap() + .subscribe(first_subscription) + .await + .unwrap(); + read_history(&mut sub).await; + sub + }); + track.used().await.unwrap(); + upstream.server_transport.hold_unis(); + let mut old = track.create_group(moq_net::group::Info { sequence: 5 }).unwrap(); + for _ in 0..3 { + old.write_frame(Timestamp::now(), &b"old"[..]).unwrap(); + } + old.finish().unwrap(); + let mut live = track.create_group(moq_net::group::Info { sequence: 6 }).unwrap(); + for _ in 0..2 { + live.write_frame(Timestamp::now(), &b"live"[..]).unwrap(); + } + // Both streams open before paused time advances; 10ms stays below linger. + tokio::time::sleep(Duration::from_millis(10)).await; + upstream.server_transport.release_unis_reversed(); + let first_sub = tokio::time::timeout(TIMEOUT, first_reader) + .await + .expect("first subscriber history") + .unwrap(); + let late = produce_origin(4); + let mut options = MockConnectOptions::new(version); + options.server_publish = Some(relay.consume()); + options.client_subscribe = Some(late.clone()); + let late_pair = connect_mock(options).await; + let consumer = late.consume(); + consumer.routed("bcast").await.unwrap(); + let remote = consumer.request_broadcast("bcast").await.unwrap(); + let mut late_sub = remote.track("history").unwrap().subscribe(subscription).await.unwrap(); + tokio::time::timeout(TIMEOUT, read_history(&mut late_sub)) + .await + .unwrap_or_else(|_| panic!("{version}: late subscriber history")); + drop((first_sub, late_sub, first_pair, late_pair, upstream, live)); +} From ea66e93891d3dfcda3bf3a0ac8e338ce240056cb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 10:15:58 -0700 Subject: [PATCH 018/128] fix(auth): align key ID length validation (#4470) Co-authored-by: GPT-6 --- js/auth/src/key.test.ts | 14 +++++++++++++- js/auth/src/key.ts | 3 ++- 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/js/auth/src/key.test.ts b/js/auth/src/key.test.ts index 7802e6539e1..4a7d61e2f93 100644 --- a/js/auth/src/key.test.ts +++ b/js/auth/src/key.test.ts @@ -4,7 +4,7 @@ import { exportJWK, generateKeyPair, SignJWT } from "jose"; import type { Algorithm } from "./algorithm.ts"; import { authorize, type Claims } from "./claims.ts"; import { INSECURE_TEST_RS256_OTHER, INSECURE_TEST_RSA_KEYS } from "./insecure-test-keys.ts"; -import { Key } from "./key.ts"; +import { Key, KeyIdSchema } from "./key.ts"; // Helper function to encode JSON to base64url function encodeJwk(obj: unknown): string { @@ -792,3 +792,15 @@ test("verify - enforces not before", async () => { expect((await Key.verify(key, await signRaw({ publish: ["**"], nbf: now - 60 }))).nbf).toBe(now - 60); await expect(Key.verify(key, await signRaw({ publish: ["**"], nbf: now + 3600 }))).rejects.toThrow(); }); + +test("key IDs share Rust's grammar and 128-character limit", async () => { + for (const kid of ["a", "A0_-", "a".repeat(128)]) { + expect(KeyIdSchema.parse(kid)).toBe(kid); + expect(Key.parse(JSON.stringify({ ...testKey, kid })).kid).toBe(kid); + } + for (const kid of ["", "bad.key", "é", "a".repeat(129)]) { + expect(KeyIdSchema.safeParse(kid).success).toBe(false); + expect(() => Key.parse(JSON.stringify({ ...testKey, kid }))).toThrow(); + } + await expect(Key.generate("HS256", "a".repeat(129))).rejects.toThrow(); +}); diff --git a/js/auth/src/key.ts b/js/auth/src/key.ts index ac6dcb2001a..af5d9bf5b2d 100644 --- a/js/auth/src/key.ts +++ b/js/auth/src/key.ts @@ -6,9 +6,10 @@ import { type Claims, ClaimsSchema, ScopeSchema, scopeAllows } from "./claims.ts import { encodeGrants } from "./wire.ts"; /** - * A validated key identifier (kid). Only alphanumeric, hyphens, and underscores. + * A validated key identifier (kid). At most 128 alphanumeric, hyphen, or underscore characters. */ export const KeyIdSchema = z.string().check( + z.maxLength(128), z.refine((value) => /^[A-Za-z0-9_-]+$/.test(value), { message: "Key ID must contain only alphanumeric characters, hyphens, and underscores", }), From f50be98c3d962c69a39cef6399650496ab5a19de Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 10:19:06 -0700 Subject: [PATCH 019/128] fix(relay): pass packaged service config positionally (#4469) Co-authored-by: GPT-6 Astra --- doc/bin/relay/index.md | 3 +++ packaging/moq-relay/moq-relay.service | 2 +- quest/m0/README.md | 1 - quest/m0/relay-systemd-unit.md | 18 ------------------ rs/moq-relay/src/config.rs | 11 +++++++++++ 5 files changed, 15 insertions(+), 20 deletions(-) delete mode 100644 quest/m0/relay-systemd-unit.md diff --git a/doc/bin/relay/index.md b/doc/bin/relay/index.md index f0caabd0112..623168eb8dc 100644 --- a/doc/bin/relay/index.md +++ b/doc/bin/relay/index.md @@ -27,6 +27,9 @@ cargo install moq-relay # or brew, apt, dnf, winget, docker; see Instal moq-relay relay.toml ``` +The `.deb` and `.rpm` systemd service reads `/etc/moq-relay/relay.toml` +using the same positional config argument. + The relay takes one TOML file. A local development config: ```toml diff --git a/packaging/moq-relay/moq-relay.service b/packaging/moq-relay/moq-relay.service index 8cbe5ed7b63..8af96bdf591 100644 --- a/packaging/moq-relay/moq-relay.service +++ b/packaging/moq-relay/moq-relay.service @@ -6,7 +6,7 @@ Wants=network-online.target [Service] Type=notify -ExecStart=/usr/bin/moq-relay --file /etc/moq-relay/relay.toml +ExecStart=/usr/bin/moq-relay /etc/moq-relay/relay.toml # Escalating restart backoff: 5s after the first failure, stepping up to a minute. A relay that # dies on a bad config or an unbindable port would otherwise restart every 5s forever, which buries # the real error under a restart loop and hammers whatever it dials. RestartSteps and diff --git a/quest/m0/README.md b/quest/m0/README.md index 5327fdc0e54..09ca0b80190 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -30,7 +30,6 @@ Published API or wire breaks still land on dev; each quest's Plan says so. ## Required -- [Packaged relay starts](/quest/m0/relay-systemd-unit.md) - the `.deb` and `.rpm` relay service starts instead of crash-looping on `--file` - [quest check everywhere](/quest/m0/quest-check-everywhere.md) - `quest check` guards `main`, `dev`, and the line branches on push and PR, not only PRs into `main` - [Wildcard](/quest/m0/wildcard/README.md) - a relay resolves subscriptions against advertised prefixes, a service claims the prefix it could serve and refuses the rest instead of enumerating broadcasts, and the browser player treats a covering claim as availability - [Audio quality harness](/quest/m0/audio-quality-harness/README.md) - a browser playout latency regression fails a nightly run instead of arriving as a bug report, and its recorder supplies the jitter target's replay traces diff --git a/quest/m0/relay-systemd-unit.md b/quest/m0/relay-systemd-unit.md deleted file mode 100644 index 37a7e51a19c..00000000000 --- a/quest/m0/relay-systemd-unit.md +++ /dev/null @@ -1,18 +0,0 @@ -# [XS] Packaged relay starts - -## Goal - -The `.deb` and `.rpm` relay service starts. Today -`packaging/moq-relay/moq-relay.service` runs `moq-relay --file -/etc/moq-relay/relay.toml`, but the config path is positional and the relay -rejects unknown flags, so every packaged install crash-loops. - -## Plan - -`ExecStart=/usr/bin/moq-relay /etc/moq-relay/relay.toml`. Add the reporter's -unit test in the relay crate that parses the unit's `ExecStart` with the -relay's own `Cli`, so the unit and the parser can't drift again. - -## Closes - -- [#4343](https://github.com/moq-dev/moq/issues/4343) - close this issue when the quest finishes diff --git a/rs/moq-relay/src/config.rs b/rs/moq-relay/src/config.rs index 658a3e00357..98ad54e9373 100644 --- a/rs/moq-relay/src/config.rs +++ b/rs/moq-relay/src/config.rs @@ -346,6 +346,17 @@ mod tests { use super::*; use crate::test_env::EnvGuard; + #[test] + fn packaged_service_arguments() { + let unit = include_str!("../../../packaging/moq-relay/moq-relay.service"); + let command = unit.lines().find_map(|line| line.strip_prefix("ExecStart=")).unwrap(); + let mut args = command.split_whitespace(); + assert_eq!(args.next(), Some("/usr/bin/moq-relay")); + let args: Vec<_> = args.map(std::ffi::OsStr::new).collect(); + let cli = Cli::parse_from(&args).expect("packaged service arguments must parse"); + assert_eq!(cli.config.file.as_deref(), Some("/etc/moq-relay/relay.toml")); + } + /// The relay's own default still applies once the released spellings are gone. #[test] fn the_relay_default_applies() { From bbeb1339c4adb07d91461fe1261c99142dd14a30 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 10:26:46 -0700 Subject: [PATCH 020/128] test(json): prove the Rust snapshot gate measures the encoded delta (#4462) Co-authored-by: Claude Sonnet 5.5 --- quest/m1/README.md | 1 - quest/m1/json-compressed-gate-rs.md | 17 ---------- rs/moq-json/src/snapshot/encoder.rs | 48 ++++++++++++++++++++++++++++- 3 files changed, 47 insertions(+), 19 deletions(-) delete mode 100644 quest/m1/json-compressed-gate-rs.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 3c16e80f49a..6da635482b6 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -82,7 +82,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [In-band auth](/quest/m1/auth/README.md) - a session tells its peer what it may publish and subscribe to, unions tokens presented in band, and fails loud on an out-of-scope publish - [Dropped sources](/quest/m1/dropped-sources.md) - track consumers see the producer's real error on every end path, never `Dropped` - [Shaper virtual time](/quest/m1/shaper-virtual-time.md) - `moq-shaper` tests judge seeded decisions on paused time, not on wall-clock delivery under load -- [Rust compressed gate test](/quest/m1/json-compressed-gate-rs.md) - `rs/moq-json` proves a snapshot delta is gated on its encoded size - [Shrink the JS overflow test](/quest/m1/json-rolls-snapshot-test.md) - the `js/json` roll-on-overflow test uses a small `maxGroupBytes` budget instead of megabytes of JSON - [C++ through moq-ffi](/quest/m1/cpp/README.md) - generated C++ over moq-ffi with futures and expected-style errors, shipped as a tarball, vcpkg, and Conan, and adopted by the OBS plugin - [Generated C bindings](/quest/m1/c/README.md) - C generated from moq-ffi ships as `moq-c` 0.8.0 and replaces the hand-written libmoq diff --git a/quest/m1/json-compressed-gate-rs.md b/quest/m1/json-compressed-gate-rs.md deleted file mode 100644 index 0e84456b811..00000000000 --- a/quest/m1/json-compressed-gate-rs.md +++ /dev/null @@ -1,17 +0,0 @@ -# [XS] Rust test for the compressed snapshot gate - -## Goal - -`rs/moq-json`'s snapshot encoder has a test proving that a delta is admitted -by its encoded size, not its plaintext: a sync-flushed DEFLATE frame can come -out larger than its input, so a plaintext gate lets a patch overflow the -group and evict the snapshot a late joiner needs. The JS encoder gained this -test in the PR that retired `quest/m1/test-flakes.md`. - -## Plan - -- The gate compares against `moq_net::group::MAX_CACHE_BYTES`, which is too - large to reach cheaply. Mirror the JS approach: a crate-private budget the - test can shrink, so it measures real frames and sets a budget between the - patch's plaintext and encoded sizes. -- Confirm the test fails when the gate measures the plaintext. diff --git a/rs/moq-json/src/snapshot/encoder.rs b/rs/moq-json/src/snapshot/encoder.rs index 9ad51161713..ac23d567cae 100644 --- a/rs/moq-json/src/snapshot/encoder.rs +++ b/rs/moq-json/src/snapshot/encoder.rs @@ -215,6 +215,10 @@ pub struct Encoder { /// Frames emitted into the current group, snapshot included. group_frames: usize, + /// The most bytes a group may hold, the cap a delta is admitted under. A field rather than the + /// constant so a test can shrink it to a size it can reach. + max_group_bytes: u64, + /// Whether the next frame has to be a full snapshot, because a frame was lost or the caller cut /// the group. Kept separate from [`last`](Self::last) so a resync doesn't erase the value: that /// field is also what [`Producer::modify`](super::Producer::modify) seeds an edit from, and dropping @@ -235,6 +239,7 @@ impl Encoder { delta_bytes: 0, snapshot_len: 0, group_frames: 0, + max_group_bytes: moq_net::group::MAX_CACHE_BYTES, resync: false, _marker: PhantomData, } @@ -351,7 +356,7 @@ impl Encoder { // come out slightly larger than its input, so the plaintext is not an upper bound. Compressing // first advances the window, but [`Self::snapshot`] opens a fresh one, so an over-budget delta // costs only the wasted compression. - if self.snapshot_len + self.delta_bytes + payload.len() as u64 > moq_net::group::MAX_CACHE_BYTES { + if self.snapshot_len + self.delta_bytes + payload.len() as u64 > self.max_group_bytes { return self.snapshot(value).map(Some); } @@ -697,6 +702,47 @@ mod test { ); } + /// A sync-flushed DEFLATE frame can come out larger than its input, so the plaintext is not an + /// upper bound on what lands in the group. A patch that fits the budget by its plaintext but not + /// by its encoded size would otherwise slip through the gate, overflow the group, and evict the + /// snapshot a late joiner needs. Matches the JS `a compressed delta is gated on its encoded size`. + #[test] + fn a_compressed_delta_is_gated_on_its_encoded_size() { + let value = json!({ "v": "x".repeat(1000) }); + let patched = json!({ "v": "x".repeat(1000), "q": "a" }); + let plaintext = serde_json::to_vec(&json!({ "q": "a" })).unwrap().len(); + let config = Config { + delta_ratio: 100, + compression: Compression::Deflate, + }; + + // Measure the frames under the default budget, which admits the delta. + let mut probe = Encoder::::new(config.clone()); + let snapshot = commit(&mut probe, &value).expect("a snapshot"); + let delta = commit(&mut probe, &patched).expect("a delta"); + assert!(!delta.keyframe); + assert!( + delta.payload.len() > plaintext, + "the encoded delta ({}) must outgrow its plaintext ({plaintext}) for this to test anything", + delta.payload.len() + ); + + // A budget with room for the plaintext patch but not the encoded one. + let mut encoder = Encoder::::new(config); + encoder.max_group_bytes = (snapshot.payload.len() + plaintext) as u64; + assert!(commit(&mut encoder, &value).unwrap().keyframe); + + // The patch rolls a fresh snapshot instead of joining the first group. + let rolled = commit(&mut encoder, &patched).expect("a rolled snapshot"); + assert!(rolled.keyframe); + let mut decoder = moq_flate::Decoder::new(); + assert_eq!( + serde_json::from_slice::(&decoder.frame(&rolled.payload).unwrap()).unwrap(), + patched, + "the snapshot carries the whole value, not a patch" + ); + } + #[test] fn compressed_deltas_reuse_the_group_window() { let phrase = "Media over QUIC delivers real-time latency at massive scale"; From e77881a810001a1022726efcabb6831b4bcdc0b1 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 10:28:53 -0700 Subject: [PATCH 021/128] feat(rtmp): let an RTMP listener refuse plaintext (#4452) Co-authored-by: Claude Sonnet 5.5 --- doc/bin/rtmp.md | 8 +- quest/m1/README.md | 1 - quest/m1/rtmp-tls-only.md | 32 -------- rs/moq-rtmp/README.md | 6 +- rs/moq-rtmp/src/lib.rs | 10 ++- rs/moq-rtmp/src/listen.rs | 36 ++++++++- rs/moq-rtmp/src/server.rs | 159 +++++++++++++++++++++++++++++++------- 7 files changed, 181 insertions(+), 71 deletions(-) delete mode 100644 quest/m1/rtmp-tls-only.md diff --git a/doc/bin/rtmp.md b/doc/bin/rtmp.md index 6a144135d96..2c207747289 100644 --- a/doc/bin/rtmp.md +++ b/doc/bin/rtmp.md @@ -34,6 +34,10 @@ Any other player receives one video rendition: the largest picture (then highest bitrate) in a codec it advertised. A push carries the largest one. Implemented in pure Rust (no librtmp). The CLI speaks plaintext `rtmp://` -only; the library adds RTMPS on the same port when the embedder supplies a TLS -config. FLAC and MP3 enhanced-audio payloads are dropped because hang has no +only. The library adds RTMPS on the same port when the embedder supplies a TLS +config, and by default still accepts plaintext `rtmp://` there, so stream keys +can arrive unencrypted. The embedder can set `plaintext` to `false` to serve +`rtmps://` only: a plaintext client is refused at its first byte and the refusal +is logged with the peer address. Refusing plaintext without a TLS config fails +at startup. FLAC and MP3 enhanced-audio payloads are dropped because hang has no catalog codec for them. diff --git a/quest/m1/README.md b/quest/m1/README.md index 6da635482b6..aee27bb7f3b 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -63,7 +63,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Video surface](/quest/m1/video-surface.md) - on dev, moq-ffi's `native` becomes `surface`, refused on platforms with no surface - [HLS discontinuity sequence](/quest/m1/hls-discontinuity-sequence.md) - on dev, `Segment::discontinuity` is the absolute sequence, so every cursor agrees - [Auth client CA](/quest/m1/relay-auth-client-ca.md) - on dev, `auth::Config::validate` and `init` take the client-CA flag, so no caller can skip the check -- [RTMP TLS only](/quest/m1/rtmp-tls-only.md) - an RTMP listener configured for TLS can refuse plaintext instead of sniffing and serving it - [HLS linger](/quest/m1/hls-linger.md) - `moq_hls::Server` serves an ended broadcast for its playlist window plus grace, so the moq.pro edge drops its own pool - [Remove live()](/quest/m1/remove-live.md) - on dev, importers publish stream timestamps verbatim, the catalog clock maps them to wall time, and an encoder restart becomes a new epoch - [iroh versions](/quest/m1/iroh-lite-wip.md) - `iroh://` negotiates the configured versions, so `moq-lite-07-wip` can be opted into diff --git a/quest/m1/rtmp-tls-only.md b/quest/m1/rtmp-tls-only.md deleted file mode 100644 index e281f2021a1..00000000000 --- a/quest/m1/rtmp-tls-only.md +++ /dev/null @@ -1,32 +0,0 @@ -# [XS] RTMP listener can refuse plaintext - -## Goal - -An operator who configures TLS on the RTMP ingest listener can require it. -Today a TLS-configured listener sniffs the first byte and serves any -non-ClientHello connection as plaintext `rtmp://` on the same port -(`rs/moq-rtmp/src/listen.rs`), so setting `tls` silently keeps accepting -unencrypted stream keys. The sniffing behavior stays available; it is just no -longer the only choice. - -## Plan - -Decided by the maintainer during the merged-PR audit: add a mode rather than -drop the sniffing. #3964 shipped mixed mode after a bot review, not a human -one, and nobody chose it for operators who want TLS only. - -- Model it so a TLS-only listener without a TLS config cannot be expressed, - for example an enum carrying the `ServerConfig` (plaintext, TLS required, - TLS or plaintext) instead of a bool beside the `Option`. Keep today's - behavior as the default for an existing `tls` config unless that reads - wrong once written; say which in the PR. -- A plaintext connection to a TLS-only listener is refused at the first byte, - with a log line naming the peer, not left to time out. -- Thread the choice through the relay and gateway configs that build this - listener, and update `doc/bin/rtmp.md` and any relay config docs that - describe RTMPS. -- Test both modes: a plaintext client is refused by TLS-only and served by - mixed. - -Public API: additive on moq-rtmp's listen config if the default holds; a -published break (dev) if the field's type changes. Wire: none. diff --git a/rs/moq-rtmp/README.md b/rs/moq-rtmp/README.md index e45d1f14e9b..b2a3bce241a 100644 --- a/rs/moq-rtmp/README.md +++ b/rs/moq-rtmp/README.md @@ -89,7 +89,10 @@ Two ways to serve `rtmps://`: RTMPS alongside plaintext RTMP on the same port: a client that opens with a TLS ClientHello is TLS-terminated, any other is served as plaintext. Build the config from a `moq_tokio::tls::Listen` instance (RTMPS has no ALPN), or supply - any `rustls::ServerConfig`. + any `rustls::ServerConfig`. Set `Config::plaintext = false` (or + `Server::with_plaintext(false)`) to serve RTMPS only: a plaintext client is + refused at its first byte, so stream keys never cross the network + unencrypted. Refusing plaintext without a TLS config is an error at startup. ```rust let mut tls = moq_tokio::tls::Listen::default(); @@ -99,6 +102,7 @@ Two ways to serve `rtmps://`: let mut rtmp = moq_rtmp::Config::default(); rtmp.listen = Some("0.0.0.0:1935".parse()?); rtmp.tls = Some(server_config); // Arc: rtmp:// and rtmps:// + rtmp.plaintext = false; // optional: rtmps:// only ``` - **Bring your own transport.** Accept the connection and complete the TLS diff --git a/rs/moq-rtmp/src/lib.rs b/rs/moq-rtmp/src/lib.rs index 51124ff3a9c..7c29c938d17 100644 --- a/rs/moq-rtmp/src/lib.rs +++ b/rs/moq-rtmp/src/lib.rs @@ -48,10 +48,12 @@ //! //! RTMPS (RTMP over TLS) is supported two ways: //! -//! - **Let the gateway terminate TLS**: set [`Config::tls`] (or call -//! [`Server::with_tls`]) with a [`rustls::ServerConfig`], and the listener -//! serves `rtmps://` alongside `rtmp://` on the same port, telling them apart -//! by the client's first byte. +//! - **Let the gateway terminate TLS** (the default `tls` feature): set +//! `Config::tls` (or call `Server::with_tls`) with a `rustls::ServerConfig`, +//! and the listener serves `rtmps://` alongside `rtmp://` on the same port, +//! telling them apart by the client's first byte. Set [`Config::plaintext`] to `false` (or call +//! [`Server::with_plaintext`]) to refuse the plaintext clients and serve +//! `rtmps://` only. //! - **Bring your own transport**: accept the connection and complete the TLS //! handshake yourself (any [`Stream`]: a `tokio_rustls` stream, a custom //! socket, a test pipe), then hand the established stream to [`accept_stream`]. diff --git a/rs/moq-rtmp/src/listen.rs b/rs/moq-rtmp/src/listen.rs index 97d9e2176ba..30474e85bff 100644 --- a/rs/moq-rtmp/src/listen.rs +++ b/rs/moq-rtmp/src/listen.rs @@ -64,7 +64,8 @@ pub struct Config { /// TLS configuration for RTMPS (RTMP over TLS). When set, the /// [`listen`](Self::listen) address serves both: a client that opens with a /// TLS ClientHello (`rtmps://`) is TLS-terminated, any other is served as - /// plaintext (`rtmp://`). Build it with + /// plaintext (`rtmp://`), unless [`plaintext`](Self::plaintext) is `false`. + /// Build it with /// `moq_tokio::tls::Listen::server_config` (pass an empty ALPN list) or /// any [`rustls::ServerConfig`]. Leave `None` for plaintext only. /// @@ -74,6 +75,12 @@ pub struct Config { #[cfg(feature = "tls")] pub tls: Option>, + /// Accept plaintext `rtmp://` alongside `tls`. Set `false` to serve + /// `rtmps://` only: a plaintext client is refused at its first byte, so stream keys + /// never cross the network unencrypted. [`run`] fails at startup if this is `false` + /// with no `tls` to serve instead. + pub plaintext: bool, + active: ActivePaths, } @@ -86,6 +93,7 @@ impl Default for Config { import_max_age: None, #[cfg(feature = "tls")] tls: None, + plaintext: true, active: ActivePaths::default(), } } @@ -112,18 +120,24 @@ pub async fn run(origin: origin::Producer, config: Config) -> Result<()> { unreachable!("pending future never resolves"); }; - #[cfg_attr(not(feature = "tls"), allow(unused_mut))] let mut server = Server::bind(listen).await?; #[cfg(feature = "tls")] - let tls = config.tls.is_some(); + let tls = match (&config.tls, config.plaintext) { + (None, _) => "off", + (Some(_), true) => "optional", + (Some(_), false) => "required", + }; #[cfg(not(feature = "tls"))] - let tls = false; + let tls = "off"; #[cfg(feature = "tls")] if let Some(tls) = config.tls.clone() { server = server.with_tls(tls); } + server = server.with_plaintext(config.plaintext); + // Fail at startup, not by dropping every client. + server.check()?; tracing::info!(%listen, prefix = %config.prefix, tls, "RTMP ingest listening"); @@ -301,6 +315,20 @@ mod tests { drop(other); } + #[tokio::test] + async fn plaintext_off_without_tls_fails_at_startup() { + let config = Config { + listen: Some("127.0.0.1:0".parse().unwrap()), + plaintext: false, + ..Config::default() + }; + + let err = run(moq_tokio::origin::spawn(), config) + .await + .expect_err("nothing could connect"); + assert!(err.to_string().contains("no TLS config"), "{err}"); + } + #[test] fn cloned_configs_share_active_paths() { let config = Config::default(); diff --git a/rs/moq-rtmp/src/server.rs b/rs/moq-rtmp/src/server.rs index 19f661f3714..0ba3e2803f3 100644 --- a/rs/moq-rtmp/src/server.rs +++ b/rs/moq-rtmp/src/server.rs @@ -20,6 +20,7 @@ //! RTMPS (RTMP over TLS): [`Server::with_tls`] makes the listener terminate TLS //! before the RTMP handshake for any client that opens with a ClientHello, so //! `rtmps://` and `rtmp://` clients share one port with no other change. +//! [`Server::with_plaintext`] can refuse the plaintext ones. //! If you'd rather own the transport (custom TLS, a non-TCP socket, a test //! pipe), accept the connection and complete any handshake yourself, then hand //! the established stream to [`accept_stream`]; everything here is generic over @@ -227,18 +228,21 @@ const ACCEPT_RETRY_MAX: Duration = Duration::from_secs(5); /// An RTMP server that yields each connection's pending request as a [`Request`]. /// -/// Build it with [`bind`](Self::bind), optionally enable RTMPS with -/// [`with_tls`](Self::with_tls), then loop on [`accept`](Self::accept). The +/// Build it with [`bind`](Self::bind), optionally enable RTMPS with `with_tls` +/// (the `tls` feature), then loop on [`accept`](Self::accept). The /// handshake and the connect exchange happen inside `accept`, so a [`Request`] is /// only produced once a client actually wants to publish or play. pub struct Server { listener: TcpListener, - /// When set, each accepted connection is TLS-terminated (RTMPS) before the - /// RTMP handshake. + /// When set, each accepted connection that opens with a ClientHello is + /// TLS-terminated (RTMPS) before the RTMP handshake. #[cfg(feature = "tls")] tls: Option, + /// Whether a connection that is not TLS is served as plaintext RTMP. + plaintext: bool, + /// In-flight handshakes; each resolves to a ready [`Request`], or `None` if /// the connection closed or errored before issuing a publish or play. pending: FuturesUnordered>>>, @@ -263,6 +267,7 @@ impl Server { listener, #[cfg(feature = "tls")] tls: None, + plaintext: true, pending: FuturesUnordered::new(), accept_delay: ACCEPT_RETRY_MIN, accept_retry: None, @@ -271,7 +276,8 @@ impl Server { /// Serve RTMPS (`rtmps://`) alongside plaintext RTMP on this one port: a /// connection that opens with a TLS ClientHello is TLS-terminated, any other is - /// served as plaintext. Pass a `rustls::ServerConfig` (e.g. from + /// served as plaintext unless [`with_plaintext`](Self::with_plaintext) refuses it. + /// Pass a `rustls::ServerConfig` (e.g. from /// `moq_tokio::tls::Listen::server_config` with an empty ALPN list), or /// `None` to serve plaintext only. #[cfg(feature = "tls")] @@ -280,6 +286,31 @@ impl Server { self } + /// Whether to accept plaintext `rtmp://` (the default). Pass `false` to refuse it and + /// serve `rtmps://` only, so stream keys never cross the network unencrypted: a + /// client that does not open with a TLS ClientHello is dropped at its first byte. + /// That needs `with_tls`, or [`accept`](Self::accept) refuses to run. + pub fn with_plaintext(mut self, allow: bool) -> Self { + self.plaintext = allow; + self + } + + /// Refuse a server that would accept no connection at all: plaintext turned off with + /// no TLS to serve instead. + pub(crate) fn check(&self) -> Result<()> { + #[cfg(feature = "tls")] + let tls = self.tls.is_some(); + #[cfg(not(feature = "tls"))] + let tls = false; + + if !self.plaintext && !tls { + return Err(crate::Error::Session( + "plaintext RTMP is refused but no TLS config is set, so no client could connect".to_string(), + )); + } + Ok(()) + } + /// The local address the listener is bound to. pub fn local_addr(&self) -> Result { Ok(self.listener.local_addr()?) @@ -290,8 +321,14 @@ impl Server { /// New connections are accepted and handshaked concurrently; this returns the /// next one to reach its `publish` or `play` command. Connections that close or /// error before either are dropped without surfacing here. Returns `None` only - /// if the listener itself stops (it currently never does). + /// if the listener itself stops (it currently never does) or the server refuses + /// plaintext without TLS, which is logged as an error. pub async fn accept(&mut self) -> Option> { + if let Err(err) = self.check() { + tracing::error!(%err, "RTMP server misconfigured; not accepting connections"); + return None; + } + loop { // Copied out so the timer arm below doesn't borrow `self` alongside the other two. let retry = self.accept_retry; @@ -314,7 +351,7 @@ impl Server { self.accept_delay = ACCEPT_RETRY_MIN; configure_socket(&stream, peer); #[cfg(feature = "tls")] - let tls = self.tls.clone(); + let (tls, plaintext) = (self.tls.clone(), self.plaintext); self.pending.push(Box::pin(async move { // The TLS handshake (if any) and the RTMP handshake share one // budget, so a client that stalls either is dropped. @@ -327,6 +364,10 @@ impl Server { .await .map_err(|e| anyhow::anyhow!("rtmps tls handshake: {e}"))?, )), + _ if !plaintext => { + tracing::warn!(%peer, "refusing plaintext RTMP: this listener requires TLS (rtmps://)"); + return Ok(None); + } _ => Conn::Plain(stream), }; #[cfg(not(feature = "tls"))] @@ -2219,20 +2260,17 @@ mod tests { client.abort(); } - /// The same publish flow, but over TLS: prove [`Server::with_tls`] terminates - /// RTMPS and yields an identical [`Request`], and that the same port still serves - /// a plaintext client. Gated on `tls` (RTMPS support); the cert is generated by - /// the `moq-tokio` dev-dependency. + /// A throwaway self-signed server config for `localhost` plus a client connector that + /// trusts anything. The cert is generated by the `moq-tokio` dev-dependency. #[cfg(feature = "tls")] - #[tokio::test] - async fn rtmps_and_rtmp_share_one_port() { + fn tls_fixture() -> (std::sync::Arc, tokio_rustls::TlsConnector) { use std::sync::Arc; use rustls::client::danger::{HandshakeSignatureValid, ServerCertVerified, ServerCertVerifier}; use rustls::pki_types::{CertificateDer, ServerName, UnixTime}; use rustls::{DigitallySignedStruct, SignatureScheme}; - // Accept any server cert: the test uses a throwaway self-signed cert. + // Accept any server cert: the tests use a throwaway self-signed cert. #[derive(Debug)] struct NoVerify(Arc); @@ -2273,26 +2311,28 @@ mod tests { let provider = Arc::new(rustls::crypto::aws_lc_rs::default_provider()); - // Server: a self-signed cert for `localhost`, fronting the RTMP listener. let mut tls = moq_tokio::tls::Listen::default(); tls.generate = vec!["localhost".to_string()]; let server_config = tls.server_config(vec![]).expect("build RTMPS server config"); - let mut server = Server::bind("127.0.0.1:0".parse().unwrap()) - .await + let client_config = rustls::ClientConfig::builder_with_provider(provider.clone()) + .with_safe_default_protocol_versions() .unwrap() - .with_tls(server_config); - let addr = server.local_addr().unwrap(); + .dangerous() + .with_custom_certificate_verifier(Arc::new(NoVerify(provider))) + .with_no_client_auth(); + + (server_config, tokio_rustls::TlsConnector::from(Arc::new(client_config))) + } + + /// Publish over TLS: prove the server terminates RTMPS and yields an identical + /// [`Request`]. + #[cfg(feature = "tls")] + async fn rtmps_publish(server: &mut Server, connector: tokio_rustls::TlsConnector) { + use rustls::pki_types::ServerName; - // Client: TLS-connect (no verify), then run the ordinary RTMP client. + let addr = server.local_addr().unwrap(); let client = tokio::spawn(async move { - let client_config = rustls::ClientConfig::builder_with_provider(provider.clone()) - .with_safe_default_protocol_versions() - .unwrap() - .dangerous() - .with_custom_certificate_verifier(Arc::new(NoVerify(provider))) - .with_no_client_auth(); - let connector = tokio_rustls::TlsConnector::from(Arc::new(client_config)); let tcp = TcpStream::connect(addr).await.unwrap(); let server_name = ServerName::try_from("localhost").unwrap(); let stream = connector.connect(server_name, tcp).await.unwrap(); @@ -2312,6 +2352,22 @@ mod tests { }; publish.reject("test rejection").await.unwrap(); client.abort(); + } + + /// By default a server with TLS terminates RTMPS and still serves a plaintext client on the + /// same port. Gated on `tls` (RTMPS support). + #[cfg(feature = "tls")] + #[tokio::test] + async fn rtmps_and_rtmp_share_one_port() { + let (server_config, connector) = tls_fixture(); + + let mut server = Server::bind("127.0.0.1:0".parse().unwrap()) + .await + .unwrap() + .with_tls(server_config); + let addr = server.local_addr().unwrap(); + + rtmps_publish(&mut server, connector).await; let plain = tokio::spawn(async move { let stream = TcpStream::connect(addr).await.unwrap(); @@ -2327,4 +2383,53 @@ mod tests { play.reject("test rejection").await.unwrap(); plain.abort(); } + + /// With plaintext turned off, a server refuses a plaintext client at its first byte, + /// without waiting for the request timeout, and keeps serving RTMPS afterwards. + #[cfg(feature = "tls")] + #[tokio::test] + async fn rtmps_required_refuses_plaintext() { + let (server_config, connector) = tls_fixture(); + + let mut server = Server::bind("127.0.0.1:0".parse().unwrap()) + .await + .unwrap() + .with_tls(server_config) + .with_plaintext(false); + let addr = server.local_addr().unwrap(); + + // The connection is handled inside `accept`, so drive it while the plaintext client + // opens with an RTMP C0. + let plain = tokio::spawn(async move { + let mut stream = TcpStream::connect(addr).await.unwrap(); + stream.write_all(&[0x03]).await.unwrap(); + // A refusal closes the socket: EOF, or a reset when unread bytes were pending. + // A served client would instead be sent the handshake S0/S1. + let mut buf = [0u8; 1]; + matches!(stream.read(&mut buf).await, Ok(0) | Err(_)) + }); + + // The refusal comes well inside REQUEST_TIMEOUT, so a client that stayed open + // (a bug) fails the outer timeout rather than passing quietly. + let refused = tokio::select! { + refused = tokio::time::timeout(Duration::from_secs(5), plain) => refused, + request = server.accept() => panic!("plaintext client yielded a request: {}", request.is_some()), + }; + assert!(refused.expect("plaintext client was not refused").unwrap()); + + rtmps_publish(&mut server, connector).await; + } + + /// Refusing plaintext with no TLS to serve instead would listen for nothing, so the + /// server refuses to run rather than dropping every client. + #[tokio::test] + async fn plaintext_off_without_tls_is_refused() { + let mut server = Server::bind("127.0.0.1:0".parse().unwrap()) + .await + .unwrap() + .with_plaintext(false); + + assert!(server.check().is_err()); + assert!(server.accept().await.is_none()); + } } From 2e547afc008f9c75a57278ff6ef040c1cce94a79 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 10:31:04 -0700 Subject: [PATCH 022/128] fix(mux): LOC video groups end with the duration marker (#4450) Co-authored-by: Claude Sonnet 5.5 --- doc/concept/hang.md | 8 ++- doc/lib/rs/moq-mux.md | 2 +- quest/m1/README.md | 1 - quest/m1/loc-duration-marker.md | 15 ------ rs/moq-mux/src/container/consumer.rs | 2 +- rs/moq-mux/src/container/loc/mod.rs | 21 ++++++++ rs/moq-mux/src/container/producer.rs | 77 +++++++++++++++++++++++----- 7 files changed, 90 insertions(+), 36 deletions(-) delete mode 100644 quest/m1/loc-duration-marker.md diff --git a/doc/concept/hang.md b/doc/concept/hang.md index 39ec8b972f2..e358ad0ec6b 100644 --- a/doc/concept/hang.md +++ b/doc/concept/hang.md @@ -138,16 +138,14 @@ The `container.kind` on each rendition says how frames are framed: A consumer skips renditions with a kind it doesn't recognize and carries them through when republishing the catalog. -A Legacy video publisher can close the last frame's duration with an empty +A Legacy or LOC video publisher can close the last frame's duration with an empty codec payload whose timestamp is that frame's exclusive end. Consumers treat it as metadata and never pass it to a decoder. This lets a group close immediately without waiting for the next frame. Audio has codec-defined durations, and CMAF carries sample durations directly, so neither needs per-group duration markers. Audio retains its separate terminal marker before codec drain packets, allowing -consumers to discard encoder padding beyond the source endpoint. LOC readers -also skip empty payloads; LOC writers wait for the compatibility release before -emitting markers. Empty payloads on data tracks remain data, including empty -text cues. +consumers to discard encoder padding beyond the source endpoint. Empty payloads +on data tracks remain data, including empty text cues. ## Groups and keyframes diff --git a/doc/lib/rs/moq-mux.md b/doc/lib/rs/moq-mux.md index eb1fd59e7be..9f6f1408275 100644 --- a/doc/lib/rs/moq-mux.md +++ b/doc/lib/rs/moq-mux.md @@ -114,7 +114,7 @@ API: [docs.rs/moq-mux](https://docs.rs/moq-mux). Real-world usage: Container producers and consumers take a format configured from the track's audio or video catalog entry (`catalog::hang::Container::try_from(&config)`). For a raw track, supply `container::Kind` explicitly. `cut(Some(end))` flushes and closes the -group immediately. Legacy video writes an empty timestamped frame at that end; +group immediately. Legacy and LOC video write an empty timestamped frame at that end; audio and CMAF do not. With no explicit end, the producer uses a known sample duration or observed cadence, independently of batching and reorder jitter. Streaming consumers deliver frames immediately. The live fMP4 exporter receives diff --git a/quest/m1/README.md b/quest/m1/README.md index aee27bb7f3b..cc4e3a35c35 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -143,7 +143,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [#933](/quest/m1/933-video-rotation-metadata-not-propagated-from-mobile-camera.md) - the catalog rotation follows the live camera's orientation - [#2848](/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - the Opus producer follows its bandwidth grant through the settled `moq_mux::rate::Control` - [Ladder](/quest/m1/ladder/README.md) - a transcode ladder adapts to the uplink it publishes over, instead of encoding every live rung at its ceiling -- [LOC duration marker](/quest/m1/loc-duration-marker.md) - LOC producers write the marker once released consumers skip it - [#2278](/quest/m1/2278-watch-absolute-wall-clock-latency-target-for-synchronized.md) - hang: document reading the catalog-root clock and converting PTS to wall time, without synchronizing library playback to wall time - [Time stretch](/quest/m1/watch-audio-time-stretch.md) - js/watch: the audio ring converges by time-stretching instead of skipping or going silent - [Native audio quality](/quest/m1/audio-quality-native.md) - the browser lane's profiles, budgets, and metric schema run against `moq play` on a dummy device diff --git a/quest/m1/loc-duration-marker.md b/quest/m1/loc-duration-marker.md deleted file mode 100644 index 1151d244873..00000000000 --- a/quest/m1/loc-duration-marker.md +++ /dev/null @@ -1,15 +0,0 @@ -# [XS] LOC producers write the duration marker - -## Goal - -LOC video groups end with the empty frame that closes their last frame's -duration, the same contract the legacy container carries. - -## Plan - -The consumer-side skip has landed in `rs/moq-mux/src/container/loc` and -`js/loc`, and shipped in `moq-mux` 0.10.3 and `@moq/loc` 0.2.3. Endpoint -recognition is configured for media tracks, so empty data frames remain data. -Have the LOC producers write the marker at `cut` and `finish` exactly as the -legacy producer does (`Container::finish_group` on `loc::Wire(Kind::Video)`), -and extend the same tests. diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index ecaec6d60b8..ee8b7f28d65 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -1340,7 +1340,7 @@ mod tests { assert_eq!(micros, vec![0, 100_000], "markers skipped, next group reached"); } - /// LOC consumers skip an empty payload so later producers can write the duration marker. + /// LOC video consumers skip an empty payload: it is the duration marker, not media. #[tokio::test] async fn loc_empty_payload_is_skipped() { let track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.video)); diff --git a/rs/moq-mux/src/container/loc/mod.rs b/rs/moq-mux/src/container/loc/mod.rs index 413e042ea3c..f3ef259f12b 100644 --- a/rs/moq-mux/src/container/loc/mod.rs +++ b/rs/moq-mux/src/container/loc/mod.rs @@ -82,4 +82,25 @@ impl Container for Wire { fn end(&self, frame: &Frame) -> Option { (self.0 != Kind::Data && frame.payload.is_empty()).then_some(frame.timestamp) } + + fn finish_group( + &self, + group: &mut moq_net::group::Producer, + end: Option, + ) -> Result<(), Self::Error> { + if self.0 == Kind::Video + && let Some(timestamp) = end + { + self.write( + group, + &[Frame { + timestamp, + payload: bytes::Bytes::new(), + keyframe: false, + duration: None, + }], + )?; + } + Ok(()) + } } diff --git a/rs/moq-mux/src/container/producer.rs b/rs/moq-mux/src/container/producer.rs index abdd85fd726..906c35880a0 100644 --- a/rs/moq-mux/src/container/producer.rs +++ b/rs/moq-mux/src/container/producer.rs @@ -1160,29 +1160,80 @@ mod tests { assert_eq!(collect_payloads(consumer).await, vec![vec![(0, 2), (20_000, 2)]]); } - /// LOC producers do not write the marker until skipping consumers have shipped. + /// Drain all LOC groups, returning each group's (timestamp_micros, payload_len) pairs. + async fn collect_loc_payloads(mut consumer: moq_net::track::Subscriber) -> Vec> { + let mut groups = Vec::new(); + while let Some(mut group) = consumer.recv_group().await.unwrap() { + let mut frames = Vec::new(); + while let Some(frame) = group.read_frame().await.unwrap() { + let decoded = moq_loc::decode(frame.payload).unwrap(); + frames.push((decoded.timestamp, decoded.payload.len())); + } + groups.push(frames); + } + groups + } + + /// A LOC video group ends with an empty frame at the next keyframe's timestamp, like Legacy. #[tokio::test] - async fn loc_cut_writes_no_duration_marker() { + async fn loc_cut_writes_a_duration_marker_at_the_callers_bound() { let track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.video)); let consumer = track.subscribe(replay()); let mut producer = Producer::new(track, Container::Loc(crate::container::Kind::Video)); producer.write(frame(0, true)).unwrap(); + producer.write(frame(10_000, false)).unwrap(); producer - .cut(Some(moq_net::Timestamp::from_micros(33_000).unwrap())) + .cut(Some(moq_net::Timestamp::from_micros(15_000).unwrap())) .unwrap(); + producer.write(frame(20_000, true)).unwrap(); producer.finish().unwrap(); - let mut groups = Vec::new(); - let mut consumer = consumer; - while let Some(mut group) = consumer.recv_group().await.unwrap() { - let mut count = 0; - while group.next_frame().await.unwrap().is_some() { - count += 1; - } - groups.push(count); - } - assert_eq!(groups, vec![1], "LOC producers do not write the marker yet"); + let groups = collect_loc_payloads(consumer).await; + assert_eq!(groups[0], vec![(0, 2), (10_000, 2), (15_000, 0)]); + assert_eq!(groups[1][0], (20_000, 2)); + assert_eq!(groups[1].last().unwrap().1, 0, "finish closes the last group"); + } + + /// LOC audio never writes a duration marker, even at finish. + #[tokio::test] + async fn loc_audio_writes_no_duration_marker() { + let track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.audio)); + let consumer = track.subscribe(replay()); + let mut producer = Producer::new(track, Container::Loc(crate::container::Kind::Audio)); + + producer.write(frame(0, true)).unwrap(); + producer.write(frame(20_000, false)).unwrap(); + producer + .cut(Some(moq_net::Timestamp::from_micros(30_000).unwrap())) + .unwrap(); + producer.write(frame(40_000, true)).unwrap(); + producer.finish().unwrap(); + + assert_eq!( + collect_loc_payloads(consumer).await, + vec![vec![(0, 2), (20_000, 2)], vec![(40_000, 2)]] + ); + } + + /// LOC data tracks never write a duration marker, so an empty data frame stays data. + #[tokio::test] + async fn loc_data_writes_no_duration_marker() { + let track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.video)); + let consumer = track.subscribe(replay()); + let mut producer = Producer::new(track, Container::Loc(crate::container::Kind::Data)); + + producer.write(frame(0, true)).unwrap(); + producer + .cut(Some(moq_net::Timestamp::from_micros(15_000).unwrap())) + .unwrap(); + producer.write(frame(20_000, true)).unwrap(); + producer.finish().unwrap(); + + assert_eq!( + collect_loc_payloads(consumer).await, + vec![vec![(0, 2)], vec![(20_000, 2)]] + ); } /// `cut()` flushes the current group immediately; the next write must be a keyframe. From 9a22225e93649c6fc7be2758d025af4e1f2f0104 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 10:46:03 -0700 Subject: [PATCH 023/128] fix(mux): rebind single-track FLV export to a better rendition before the header (#4445) Co-authored-by: Claude Sonnet 5.5 --- quest/m1/README.md | 1 - quest/m1/flv-rebind.md | 14 --- rs/moq-mux/src/container/flv/export.rs | 17 +++- rs/moq-mux/src/container/flv/export_test.rs | 95 +++++++++++++++++++++ 4 files changed, 109 insertions(+), 18 deletions(-) delete mode 100644 quest/m1/flv-rebind.md diff --git a/quest/m1/README.md b/quest/m1/README.md index cc4e3a35c35..55b4f0a17f6 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -95,7 +95,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [GPU CI](/quest/m1/gpu-ci.md) - NVIDIA tests run nightly on a self-hosted GPU runner, and `just rs nvidia` runs them locally instead of skipping - [JS rendition ranking](/quest/m1/js-ranked.md) - `@moq/hang` ranks video renditions like Rust, and `@moq/watch`'s fallback uses it - [Audio rendition pick](/quest/m1/audio-ranked.md) - single-track FLV/RTMP and WHEP serve the best audio rendition, not the first by name -- [FLV rebind before header](/quest/m1/flv-rebind.md) - single-track FLV switches to a better rendition announced before the header - [FLV catalog stream](/quest/m1/flv-catalog-stream.md) - on dev, `flv::Export` takes a catalog stream like fmp4, replacing `with_select` - [Own the QUIC stack](/quest/m1/quic/README.md) - the moq-noq fork carries ACK progress, reliable reset, hierarchical scheduling, deadlines, peer limits, and qmux - [QoS](/quest/m1/qos/README.md) - broadcast health: relay starvation and timeliness histograms, and client stats broadcasts from publishers and viewers, on dev diff --git a/quest/m1/flv-rebind.md b/quest/m1/flv-rebind.md deleted file mode 100644 index 4aacafda746..00000000000 --- a/quest/m1/flv-rebind.md +++ /dev/null @@ -1,14 +0,0 @@ -# [XS] FLV rebind before header - -## Goal - -A single-track FLV export whose first catalog snapshot lacks the best -rendition switches to it if it appears before the stream header goes out, so -the pick doesn't depend on catalog timing. - -## Plan - -`flv::Export` binds from the first snapshot and ignores later ones in -single-track mode. Before the header, a better-ranked rendition could replace -the bound one; after it, FLV can't introduce a new config, so the current track -stays. Mock time in the test. diff --git a/rs/moq-mux/src/container/flv/export.rs b/rs/moq-mux/src/container/flv/export.rs index 73491f6ae62..7351124656e 100644 --- a/rs/moq-mux/src/container/flv/export.rs +++ b/rs/moq-mux/src/container/flv/export.rs @@ -11,7 +11,8 @@ //! //! By default FLV carries a single video and a single audio stream, so only the //! best video rendition (see [`Video::ranked`](hang::catalog::Video::ranked)) and -//! the first audio rendition are muxed and the rest are ignored. With +//! the first audio rendition are muxed and the rest are ignored. The video pick +//! follows the catalog until the stream header goes out, then stays. With //! [`with_multitrack`](Export::with_multitrack) every rendition is muxed instead, //! each as an enhanced-RTMP multitrack track addressed by its own track id (use //! this only for a player that advertised the `Multitrack` capability). @@ -327,8 +328,8 @@ impl Export { // Only bind before the header is emitted: the sequence-header (config) tags // go out with the header, and there's no in-band way to introduce a new // track's config mid-stream, so a rendition first seen afterward is left - // unmuxed rather than emitted as undecodable config-less frames. (This - // mirrors the single-track path ignoring extra renditions.) + // unmuxed rather than emitted as undecodable config-less frames. Until then a + // single-track stream rebinds to a better-ranked video rendition. if !self.header_emitted { self.bind_video(&catalog)?; self.bind_audio(&catalog)?; @@ -365,6 +366,16 @@ impl Export { ranked }; + // Before the header, a single-track stream follows the best rendition, so a + // snapshot that lacks it doesn't fix the pick. Dropping the bound track + // unsubscribes it; nothing was emitted from it yet. + if !self.multitrack + && let Some((best, _)) = renditions.first() + && self.video.first().is_some_and(|t| &t.name != *best) + { + self.video.clear(); + } + for (name, config) in renditions { if !self.multitrack && !self.video.is_empty() { break; diff --git a/rs/moq-mux/src/container/flv/export_test.rs b/rs/moq-mux/src/container/flv/export_test.rs index 147bdc165e2..46941f1c70d 100644 --- a/rs/moq-mux/src/container/flv/export_test.rs +++ b/rs/moq-mux/src/container/flv/export_test.rs @@ -748,6 +748,101 @@ async fn export_picks_the_best_selected_rendition() { assert_eq!(snap.audio.renditions.len(), 1, "audio is selected too"); } +/// A single-track export whose first snapshot lacks the best rendition switches to +/// it when it appears before the header goes out. +#[tokio::test(start_paused = true)] +async fn export_rebinds_to_a_better_rendition_before_the_header() { + use hang::catalog::{Container, H264, VideoConfig}; + use moq_net::Timestamp; + + use crate::container::Producer; + + let mut producer = moq_net::broadcast::Info::new().produce(); + let consumer = producer.consume(); + let mut catalog = crate::catalog::Producer::new(&mut producer, crate::catalog::Config::default()).unwrap(); + + // The small rendition is Annex-B (no description), so its header can't resolve + // until a keyframe arrives, which keeps the stream header pending. + let small = producer.create_track(producer.unique_name(".avc3"), None).unwrap(); + let mut config = VideoConfig::new(H264 { + profile: 0x42, + constraints: 0xc0, + level: 0x1f, + inline: true, + }); + config.container = Container::Legacy; + config.coded_width = Some(640); + config.coded_height = Some(360); + catalog + .modify() + .unwrap() + .video + .renditions + .insert(small.name().to_string(), config); + let _small = Producer::new( + small, + crate::catalog::hang::Container::Legacy(crate::container::Kind::Data), + ); + + let mut exporter = Export::new(crate::source::announced(&consumer)).await.unwrap(); + assert!( + tokio::time::timeout(Duration::from_millis(100), exporter.next()) + .await + .is_err(), + "the header waits on the small rendition's config" + ); + + // The best rendition shows up before any header went out. + let description = avcc_level(0x1e); + let large = producer.create_track(producer.unique_name(".avc1"), None).unwrap(); + let mut config = VideoConfig::new(H264 { + profile: 0x42, + constraints: 0xc0, + level: 0x1e, + inline: false, + }); + config.container = Container::Legacy; + config.description = Some(Bytes::from(description.clone())); + config.coded_width = Some(1920); + config.coded_height = Some(1080); + catalog + .modify() + .unwrap() + .video + .renditions + .insert(large.name().to_string(), config); + let mut large = Producer::new( + large, + crate::catalog::hang::Container::Legacy(crate::container::Kind::Data), + ); + large + .write(crate::container::Frame { + timestamp: Timestamp::from_millis(0).unwrap(), + duration: None, + payload: Bytes::from_static(&[0, 0, 0, 1, 0x65]), + keyframe: true, + }) + .unwrap(); + + let header = tokio::time::timeout(Duration::from_millis(100), exporter.next()) + .await + .expect("the header follows the better rendition") + .unwrap() + .unwrap(); + assert!( + header.windows(description.len()).any(|w| w == description.as_slice()), + "the sequence header carries the better rendition's avcC" + ); + + let frame = tokio::time::timeout(Duration::from_millis(100), exporter.next()) + .await + .expect("the better rendition's frame follows") + .unwrap() + .unwrap(); + assert_eq!(frame[0], super::TAG_VIDEO); + assert!(frame.windows(5).any(|w| w == [0, 0, 0, 1, 0x65])); +} + struct ParsedTag { tag_type: u8, timestamp: u32, From 7efe9b5eaca9dfdcff4a413772cdb73acf159c5c Mon Sep 17 00:00:00 2001 From: t0ms Date: Tue, 29 Sep 2026 19:03:16 +0100 Subject: [PATCH 024/128] fix(mux): follow the stream's reorder depth in TS export (#4500) Co-authored-by: Claude Opus 5.5 Co-authored-by: Cursor Co-authored-by: Luke Curley --- quest/m1/README.md | 1 - quest/m1/ts-export-jitter.md | 57 ---- rs/moq-mux/src/codec/h264/mod.rs | 207 +++++++++++++ rs/moq-mux/src/codec/h265/mod.rs | 47 +++ rs/moq-mux/src/codec/video.rs | 17 +- rs/moq-mux/src/container/ts/export.rs | 225 +++++++++++--- rs/moq-mux/src/container/ts/export_test.rs | 339 +++++++++++++++++++++ 7 files changed, 794 insertions(+), 99 deletions(-) delete mode 100644 quest/m1/ts-export-jitter.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 55b4f0a17f6..cada8fa4f73 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -53,7 +53,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Wire compatibility](/quest/m1/wire-compat.md) - a nightly run tests this checkout against the last published release for tokens, session wire, and catalog/container - [Full codec string](/quest/m1/publish-codec-string.md) - browser-published video carries the encoder's full RFC 6381 codec string, so native players decode it - [TS program selection](/quest/m1/ts-programs.md) - `import ts` refuses a multi-program stream unless `--program ` picks one or publishes each -- [TS export jitter](/quest/m1/ts-export-jitter.md) - the video reorder bound follows later catalogs and the declared reorder depth, so a late B-frame never reorders TS output; an undeclared stream can reorder once per new maximum depth - [TS import shared shift](/quest/m1/ts-import-shared-shift.md) - unflagged loop wraps move audio and video by one shift, so A/V sync holds across wraps - [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) - `import ts` reads a PAT or PMT that spans packets or follows a nonzero pointer_field instead of aborting - [Same-hop importers](/quest/m1/hop-aligned-import.md) - importers sharing a `--hop` and fed one stream publish identical groups and timestamps, so failover survives diff --git a/quest/m1/ts-export-jitter.md b/quest/m1/ts-export-jitter.md deleted file mode 100644 index 5e0b138748d..00000000000 --- a/quest/m1/ts-export-jitter.md +++ /dev/null @@ -1,57 +0,0 @@ -# [S] moq export ts: video reorder bound follows the stream - -## Goal - -Two `moq export ts` legs of one broadcast interleave video and audio -identically even when a B-frame arrives late. Today the media-time interleave -from [#4001](https://github.com/moq-dev/moq/pull/4001) treats a video track as -advanced past a candidate once its high-water mark, less its DTS reserve, -passes it. Without catalog `jitter` that reserve is the 16-tick -`DEFAULT_DTS_RESERVE`, so a B-frame presenting below the mark can still land -after audio it should precede, and the order depends on arrival again. A -`jitter` that shows up in a later catalog is ignored too: `update_catalog` -returns early once the PAT/PMT is built, before the per-track refresh. - -## Plan - -Decided: - -- Keep refreshing a video track's reserve from catalog `jitter` after the PMT - is emitted. The early return exists to lock the track layout, not the - per-track timing, and the importer often fills `jitter` only once it has - seen reordering. -- When `jitter` is absent, derive the reserve from the stream rather than - refuse it. The bitstream's reorder depth (H.264 VUI - `max_num_reorder_frames`, HEVC `sps_max_num_reorder_pics`) counts - pictures, not time, so it becomes a deterministic 90 kHz bound only with - fixed timing: the VUI `fixed_frame_rate_flag` with its tick, or the - catalog framerate. With both, the reserve is depth times frame duration, - known from the first keyframe before any frame is emitted. AV1 and VP9 - present in decode order and need no reserve. Otherwise (variable frame - rate, or nothing declared), grow the reserve from the reordering actually - observed (how far a frame's PTS falls below the track's high-water mark); - it only grows, so a stream that never reorders keeps today's tiny reserve. -- Refusing to export video without `jitter` was rejected as too extreme. -- Treating unknown jitter as unbounded was tried in #4001 and rejected: the - stall never clears when video leads, breaking - `quiet_track_is_emitted_around_then_rejoins`. - -Guidance: - -- The same reserve feeds `author_dts`, so growing it mid-stream shifts DTS - further behind PTS. The existing monotonic clamp keeps DTS from stepping - back; check the PCR, which backs off by the largest reserve, stays ahead of - every DTS written. -- Only the observed fallback is nondeterministic: a B-frame deeper than any - seen before can reorder output once per new maximum (Codex on #4307). - Refusing such streams was ruled out by the maintainer. Say - so in a comment and log each growth, so an undeclared stream is visible - rather than silently misordered. -- Tests in `export_test.rs`: two exporters with a late B-frame, no `jitter`, - and a declared reorder depth at a fixed frame rate produce byte-identical - output from the first frame; an undeclared stream converges after its deepest reorder; and a - `jitter` arriving in a catalog after the PMT raises the reserve. - -## Related - -- [TS export byte schedule](/quest/m1/ts-export-byte-schedule.md) - also reshapes PCR placement in `export.rs` diff --git a/rs/moq-mux/src/codec/h264/mod.rs b/rs/moq-mux/src/codec/h264/mod.rs index 9baf5367255..4340b7c02bc 100644 --- a/rs/moq-mux/src/codec/h264/mod.rs +++ b/rs/moq-mux/src/codec/h264/mod.rs @@ -144,6 +144,160 @@ impl Sps { } } +/// The reordering an SPS NAL unit declares in its VUI: `max_num_reorder_frames` from the +/// bitstream restriction, and the frame period when `fixed_frame_rate_flag` is set. +/// +/// `None` when the SPS carries no VUI or no bitstream restriction, or fails to parse. +pub(crate) fn sps_reorder(nal: &[u8]) -> Option { + if nal.len() < 4 { + return None; + } + let rbsp = h264_parser::nal::ebsp_to_rbsp(&nal[1..]); + let sps = h264_parser::Sps::parse(&rbsp).ok()?; + if !sps.vui_parameters_present_flag { + return None; + } + vui_reorder(&rbsp).ok().flatten() +} + +/// Walk an SPS RBSP to its VUI (ITU-T H.264 7.3.2.1.1, E.1.1). `h264_parser` stops at +/// `vui_parameters_present_flag` without exposing its position, so this re-reads the fields +/// before it. +fn vui_reorder(rbsp: &[u8]) -> h264_parser::Result> { + use h264_parser::bitreader::BitReader; + use h264_parser::eg::{read_se, read_ue}; + + let mut r = BitReader::new(rbsp); + let profile_idc = r.read_u8()?; + r.skip_bits(16)?; // constraint flags, reserved bits, level_idc + read_ue(&mut r)?; // seq_parameter_set_id + if matches!( + profile_idc, + 100 | 110 | 122 | 244 | 44 | 83 | 86 | 118 | 128 | 138 | 139 | 134 | 135 + ) { + let chroma_format_idc = read_ue(&mut r)?; + if chroma_format_idc == 3 { + r.skip_bits(1)?; // separate_colour_plane_flag + } + read_ue(&mut r)?; // bit_depth_luma_minus8 + read_ue(&mut r)?; // bit_depth_chroma_minus8 + r.skip_bits(1)?; // qpprime_y_zero_transform_bypass_flag + if r.read_flag()? { + let lists = if chroma_format_idc == 3 { 12 } else { 8 }; + for i in 0..lists { + if r.read_flag()? { + let size = if i < 6 { 16 } else { 64 }; + let (mut last, mut next) = (8i32, 8i32); + for _ in 0..size { + if next != 0 { + next = (last + read_se(&mut r)?).rem_euclid(256); + } + if next != 0 { + last = next; + } + } + } + } + } + } + read_ue(&mut r)?; // log2_max_frame_num_minus4 + match read_ue(&mut r)? { + 0 => { + read_ue(&mut r)?; // log2_max_pic_order_cnt_lsb_minus4 + } + 1 => { + r.skip_bits(1)?; // delta_pic_order_always_zero_flag + read_se(&mut r)?; // offset_for_non_ref_pic + read_se(&mut r)?; // offset_for_top_to_bottom_field + for _ in 0..read_ue(&mut r)? { + read_se(&mut r)?; // offset_for_ref_frame + } + } + _ => {} + } + read_ue(&mut r)?; // max_num_ref_frames + r.skip_bits(1)?; // gaps_in_frame_num_value_allowed_flag + read_ue(&mut r)?; // pic_width_in_mbs_minus1 + read_ue(&mut r)?; // pic_height_in_map_units_minus1 + if !r.read_flag()? { + r.skip_bits(1)?; // mb_adaptive_frame_field_flag + } + r.skip_bits(1)?; // direct_8x8_inference_flag + if r.read_flag()? { + for _ in 0..4 { + read_ue(&mut r)?; // frame_crop_*_offset + } + } + if !r.read_flag()? { + return Ok(None); + } + + // vui_parameters() + if r.read_flag()? && r.read_u8()? == 255 { + r.skip_bits(32)?; // sar_width, sar_height + } + if r.read_flag()? { + r.skip_bits(1)?; // overscan_appropriate_flag + } + if r.read_flag()? { + r.skip_bits(4)?; // video_format, video_full_range_flag + if r.read_flag()? { + r.skip_bits(24)?; // colour_primaries, transfer_characteristics, matrix_coefficients + } + } + if r.read_flag()? { + read_ue(&mut r)?; // chroma_sample_loc_type_top_field + read_ue(&mut r)?; // chroma_sample_loc_type_bottom_field + } + let mut period = None; + if r.read_flag()? { + let units = r.read_bits(32)?; + let scale = r.read_bits(32)?; + // With a fixed rate, a frame lasts two ticks (E.2.1). + if r.read_flag()? && units > 0 && scale > 0 { + period = Some((2 * u64::from(units), u64::from(scale))); + } + } + let nal_hrd = r.read_flag()?; + if nal_hrd { + skip_hrd(&mut r)?; + } + let vcl_hrd = r.read_flag()?; + if vcl_hrd { + skip_hrd(&mut r)?; + } + if nal_hrd || vcl_hrd { + r.skip_bits(1)?; // low_delay_hrd_flag + } + r.skip_bits(1)?; // pic_struct_present_flag + if !r.read_flag()? { + return Ok(None); + } + r.skip_bits(1)?; // motion_vectors_over_pic_boundaries_flag + for _ in 0..4 { + read_ue(&mut r)?; // max_bytes_per_pic_denom .. log2_max_mv_length_vertical + } + let depth = read_ue(&mut r)?; // max_num_reorder_frames + Ok(Some(crate::codec::video::Reorder { depth, period })) +} + +/// Skip `hrd_parameters()` (ITU-T H.264 E.1.2). +fn skip_hrd(r: &mut h264_parser::bitreader::BitReader) -> h264_parser::Result<()> { + use h264_parser::eg::read_ue; + + let cpb_cnt_minus1 = read_ue(r)?; + if cpb_cnt_minus1 > 31 { + return Err(h264_parser::Error::MalformedSps("cpb_cnt_minus1 out of range".into())); + } + r.skip_bits(8)?; // bit_rate_scale, cpb_size_scale + for _ in 0..=cpb_cnt_minus1 { + read_ue(r)?; // bit_rate_value_minus1 + read_ue(r)?; // cpb_size_value_minus1 + r.skip_bits(1)?; // cbr_flag + } + r.skip_bits(20) // four delay/offset lengths +} + /// Parsed AVCDecoderConfigurationRecord (ISO/IEC 14496-15 §5.3.3.1.2). /// /// Just the codec-config fields that the hang catalog records. The original @@ -469,12 +623,65 @@ fn process_nal( } } +/// Real SPS NAL units from 64x64, 25 fps x264 encodes (High profile, 50 Hz VUI tick), for +/// tests that need a VUI with a bitstream restriction. +#[cfg(test)] +pub(crate) mod fixtures { + /// `bframes=1:force-cfr=1`: one B-frame per reference (`max_num_reorder_frames` 1) with + /// `fixed_frame_rate_flag` set. + pub(crate) const SPS_IPB: &[u8] = &[ + 0x67, 0x64, 0x00, 0x0a, 0xac, 0xe4, 0x10, 0x9b, 0x01, 0x10, 0x00, 0x00, 0x03, 0x00, 0x10, 0x00, 0x00, 0x03, + 0x03, 0x28, 0xf1, 0x22, 0x51, 0x20, + ]; + /// `bframes=3:b-pyramid=2:force-cfr=1`: a B-pyramid (`max_num_reorder_frames` 2) with + /// `fixed_frame_rate_flag` set. + pub(crate) const SPS_PYRAMID: &[u8] = &[ + 0x67, 0x64, 0x00, 0x0a, 0xac, 0xd9, 0x44, 0x26, 0xc0, 0x44, 0x00, 0x00, 0x03, 0x00, 0x04, 0x00, 0x00, 0x03, + 0x00, 0xca, 0x3c, 0x48, 0x96, 0x58, + ]; + /// `bframes=1` at x264's default: `max_num_reorder_frames` 1 without `fixed_frame_rate_flag`. + pub(crate) const SPS_IPB_VARIABLE: &[u8] = &[ + 0x67, 0x64, 0x00, 0x0a, 0xac, 0xe4, 0x10, 0x9b, 0x01, 0x10, 0x00, 0x00, 0x03, 0x00, 0x10, 0x00, 0x00, 0x03, + 0x03, 0x20, 0xf1, 0x22, 0x51, 0x20, + ]; + pub(crate) const PPS: &[u8] = &[0x68, 0xeb, 0xe3, 0xcb, 0x22, 0xc0]; +} + #[cfg(test)] mod tests { use super::*; const SC4: &[u8] = &[0, 0, 0, 1]; + #[test] + fn sps_reorder_reads_the_vui() { + use crate::codec::video::Reorder; + + let fixed = Some((2, 50)); + assert_eq!( + sps_reorder(fixtures::SPS_IPB), + Some(Reorder { + depth: 1, + period: fixed + }) + ); + assert_eq!( + sps_reorder(fixtures::SPS_PYRAMID), + Some(Reorder { + depth: 2, + period: fixed + }) + ); + assert_eq!( + sps_reorder(fixtures::SPS_IPB_VARIABLE), + Some(Reorder { depth: 1, period: None }) + ); + // Baseline with no VUI declares nothing. + assert_eq!(sps_reorder(&[0x67, 0x42, 0xc0, 0x1f, 0xde]), None); + // A VUI cut short is no declaration rather than a wrong one. + assert_eq!(sps_reorder(&fixtures::SPS_IPB[..fixtures::SPS_IPB.len() - 3]), None); + } + fn annexb_frame(nals: &[&[u8]]) -> Bytes { let mut buf = BytesMut::new(); for nal in nals { diff --git a/rs/moq-mux/src/codec/h265/mod.rs b/rs/moq-mux/src/codec/h265/mod.rs index ab5eda651c1..ff5d51d49fe 100644 --- a/rs/moq-mux/src/codec/h265/mod.rs +++ b/rs/moq-mux/src/codec/h265/mod.rs @@ -215,6 +215,38 @@ pub(crate) fn config_from_hvcc(hvcc: &[u8]) -> Result Option { + let sps = SpsNALUnit::parse(&mut &nal[..]).ok()?; + let highest = sps.rbsp.sps_max_sub_layers_minus1 as usize; + let reorder = &sps.rbsp.sub_layer_ordering_info.sps_max_num_reorder_pics; + let depth = *reorder.get(highest).or(reorder.last())?; + let period = sps + .rbsp + .vui_parameters + .as_ref() + .and_then(|vui| vui.vui_timing_info.as_ref()) + .and_then(|timing| { + let sub_layers = &timing.hrd_parameters.as_ref()?.sub_layers; + let elemental = sub_layers + .get(highest) + .or(sub_layers.last())? + .elemental_duration_in_tc_minus1?; + let units = elemental + .checked_add(1)? + .checked_mul(u64::from(timing.num_units_in_tick.get()))?; + Some((units, u64::from(timing.time_scale.get()))) + }); + Some(crate::codec::video::Reorder { + depth: u32::try_from(depth).ok()?, + period, + }) +} + /// Annex-B → length-prefixed transmuxer; the H.265 analogue of /// [`crate::codec::h264::Avc1`]. /// @@ -477,6 +509,13 @@ pub(crate) mod fixtures { 0x02, 0x00, 0x00, 0x03, 0x00, 0x3c, 0x10, ]; pub(crate) const PPS: &[u8] = &[0x44, 0x01, 0xc1, 0x72, 0xb4, 0x62, 0x40]; + /// SPS from a 64x64, 25 fps x265 encode with `bframes=3:b-pyramid=1` and HRD signalling + /// (`sps_max_num_reorder_pics` 2). + pub(crate) const SPS_PYRAMID: &[u8] = &[ + 0x42, 0x01, 0x01, 0x01, 0x60, 0x00, 0x00, 0x03, 0x00, 0x90, 0x00, 0x00, 0x03, 0x00, 0x00, 0x03, 0x00, 0x3c, + 0xa0, 0x20, 0x81, 0x05, 0x96, 0x56, 0x59, 0x24, 0xca, 0xf0, 0x16, 0x80, 0x80, 0x00, 0x00, 0x03, 0x00, 0x80, + 0x00, 0x00, 0x0c, 0xb0, 0x0a, 0x48, 0x2f, 0x00, 0x07, 0xa1, 0x20, 0x00, 0xf4, 0x24, 0x40, + ]; /// An hvcC record built from the real parameter sets (4-byte NALU lengths). pub(crate) fn hvcc() -> Bytes { @@ -507,6 +546,14 @@ mod tests { moq_net::Timestamp::from_micros(0).unwrap() } + #[test] + fn sps_reorder_reads_the_highest_sub_layer() { + let reorder = sps_reorder(fixtures::SPS_PYRAMID).unwrap(); + assert_eq!(reorder.depth, 2); + assert_eq!(reorder.period, Some((1, 25))); + assert_eq!(sps_reorder(&fixtures::SPS[..8]), None); + } + /// hvc1: a length-prefixed access unit with an IDR slice wraps as one keyframe; /// the payload is passed through verbatim. The leading prefix-SEI NAL exercises /// the walk past non-slice NALs. diff --git a/rs/moq-mux/src/codec/video.rs b/rs/moq-mux/src/codec/video.rs index 9344d565ee0..219da9d09d5 100644 --- a/rs/moq-mux/src/codec/video.rs +++ b/rs/moq-mux/src/codec/video.rs @@ -1,10 +1,11 @@ -//! Shared catalog-publishing logic for the video codec importers. +//! Shared logic for the video codecs. //! //! Every video importer resolves its [`VideoConfig`](hang::catalog::VideoConfig) lazily from the //! bitstream and re-publishes it whenever the stream reveals a change. [`Catalog`] owns the part of //! that which is identical across codecs: overlay the caller's [`VideoHint`], skip a publish //! that matches the last one, and drive the shared [`hang::catalog::stalled::Detector`] detector so a -//! lagging rendition is marked in the catalog. +//! lagging rendition is marked in the catalog. [`Reorder`] is what a sequence header declares about +//! frame reordering, read by the exporters that author a decode clock. use std::time::{Duration, Instant}; @@ -14,6 +15,18 @@ use crate::catalog::VideoHint; type Track = crate::container::Producer; +/// The reordering a video sequence header declares. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(crate) struct Reorder { + /// The most pictures that can precede any picture in decode order and follow it in output + /// order: H.264 `max_num_reorder_frames`, HEVC `sps_max_num_reorder_pics`. A count of + /// pictures, not a time. + pub depth: u32, + /// One picture's duration as `(units, scale)`, i.e. `units / scale` seconds, when the header + /// declares a fixed picture rate. + pub period: Option<(u64, u64)>, +} + /// The catalog-publishing state a video importer overlays onto every config it resolves. /// /// Holds the caller's hint, the last config published (to dedupe re-publishes), and the diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index e1380502ae8..a75f27b1453 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -38,6 +38,7 @@ use moq_net::Timestamp; use crate::catalog::hang::Catalog; use crate::catalog::{CatalogFormat, Stream}; use crate::codec::annexb; +use crate::codec::video::Reorder; use crate::container::{ExportSource, Frame}; use super::adts; @@ -218,10 +219,9 @@ struct Track { /// High-water mark of the timestamps muxed within this rendition, independent of /// cross-track skew. Bounds where its next frame can land ([`Track::shown`]). timeline: Option, - /// Decode-clock reserve (90 kHz ticks): how far ahead of its PTS each frame decodes. Taken - /// from the catalog `jitter` (the reorder depth) so it is large enough for `DTS <= PTS`, - /// or [`DEFAULT_DTS_RESERVE`] when the catalog declares none. Only video uses it. - dts_reserve: u64, + /// Decode-clock reserve: how far ahead of its PTS each frame decodes. Only video sizes it; + /// every other kind holds [`DEFAULT_DTS_RESERVE`]. + reserve: Reserve, } impl Track { @@ -242,7 +242,7 @@ impl Track { return false; }; let reorder = match self.kind { - Kind::Video(_) => u128::from(self.dts_reserve) * 1_000_000_000 / 90_000, + Kind::Video(_) => u128::from(self.reserve.ticks) * 1_000_000_000 / 90_000, _ => 0, }; let floor = timeline.as_nanos().saturating_sub(reorder); @@ -250,6 +250,127 @@ impl Track { } } +/// A video rendition's decode-clock reserve in 90 kHz ticks: how far each frame's DTS runs +/// behind its PTS. It must exceed the rendition's reordering for `DTS <= PTS` to hold, and +/// [`Export::pcr_at`] backs the clock off by the largest one. +/// +/// The catalog `jitter` (the importer's max PTS - DTS) sizes it when published. Otherwise the +/// reorder depth the SPS declares sizes it, at the SPS's fixed picture rate or the catalog +/// `framerate`, so two exporters agree on it from their first keyframe. Otherwise it holds +/// [`DEFAULT_DTS_RESERVE`]. Reordering deeper than all of those raises it further +/// ([`Self::observe`]). +/// +/// It never shrinks: that would step the decode clock forward past frames already muxed and +/// the PCR ahead of DTS values already sent. +struct Reserve { + /// The catalog `jitter`, in ticks. + jitter: Option, + /// The catalog `framerate`: the picture period for an SPS that declares no fixed rate. + framerate: Option, + /// The avcC/hvcC [`Self::declared`] was read from. + description: Option, + declared: Option, + /// The reserve covering the deepest reordering muxed so far. + observed: u64, + /// Frames muxed since the one that set the rendition's high-water mark. + since_peak: u64, + /// The reserve in effect. + ticks: u64, +} + +impl Default for Reserve { + fn default() -> Self { + Self { + jitter: None, + framerate: None, + description: None, + declared: None, + observed: 0, + since_peak: 0, + ticks: DEFAULT_DTS_RESERVE, + } + } +} + +impl Reserve { + /// Take the rendition's timing from a catalog snapshot, before or after the program + /// tables are written. + fn configure(&mut self, config: &VideoConfig, name: &str) { + self.jitter = config + .jitter + .map(|t| (t.as_micros() * 90_000 / 1_000_000) as u64) + .filter(|&ticks| ticks > 0); + self.framerate = config.framerate.filter(|fps| fps.is_finite() && *fps > 0.0); + self.settle(name, "catalog"); + } + + /// Read the reorder depth from the codec config a keyframe is carried with. + fn describe(&mut self, stream_type: StreamType, description: Option<&Bytes>, name: &str) { + if self.description.as_ref() == description { + return; + } + self.description = description.cloned(); + self.declared = description.and_then(|d| declared_reorder(stream_type, d)); + self.settle(name, "sps"); + } + + /// Account for a frame muxed `gap` ticks below the rendition's high-water mark. + /// + /// This is the one path where the reserve depends on when an exporter joined rather than on + /// what the stream declares: a joiner adopts the depth only once it has muxed the deepest + /// reordering itself, and until then its DTS and PCR differ from an exporter that has. It + /// fires only when the catalog and the SPS both undercount the stream's reordering (or + /// declare none), and each growth is logged. + /// + /// The decode clock steps at least one tick per frame, so a frame decoded `k` frames after + /// the one that set the high-water mark needs `k` ticks beyond its gap. + fn observe(&mut self, gap: u64, name: &str) { + self.since_peak += 1; + let covering = gap.saturating_add(self.since_peak).min(MAX_DTS_RESERVE); + if covering > self.observed { + self.observed = covering; + self.settle(name, "observed"); + } + } + + /// Account for a frame at or above the rendition's high-water mark. + fn peak(&mut self) { + self.since_peak = 0; + } + + fn settle(&mut self, name: &str, source: &'static str) { + // As in [`Self::observe`], a reordered frame needs a tick for each frame decoded between + // it and the one above it; the declared depth stands in for that count. + let declared = self.declared.and_then(|reorder| { + let period = match reorder.period { + Some((units, scale)) => units.saturating_mul(90_000).div_ceil(scale), + None => (90_000.0 / self.framerate?).ceil() as u64, + }; + let depth = u64::from(reorder.depth); + let ticks = depth.saturating_mul(period).saturating_add(depth.max(1)); + Some(ticks.min(MAX_DTS_RESERVE)) + }); + let target = self + .jitter + .or(declared) + .unwrap_or(DEFAULT_DTS_RESERVE) + .max(self.observed); + if target > self.ticks { + if source == "observed" { + tracing::warn!( + track = %name, + from = self.ticks, + to = target, + "reordering deeper than the catalog or SPS declares; raising the video DTS reserve" + ); + } else { + tracing::info!(track = %name, from = self.ticks, to = target, source, "raising the video DTS reserve"); + } + self.ticks = target; + } + } +} + #[derive(Clone)] enum Kind { /// Video carries its TS stream type (H.264 = 0x1B, H.265 = 0x24). @@ -718,6 +839,19 @@ impl Export { } let frame = pending.frame; let track = self.tracks.get_mut(&name).unwrap(); + if let Kind::Video(stream_type) = track.kind { + if frame.keyframe { + track.reserve.describe(stream_type, track.source.description(), &name); + } + if let Some(timeline) = track.timeline + && frame.timestamp < timeline + { + let gap = to_ticks(timeline) - to_ticks(frame.timestamp); + track.reserve.observe(gap, &name); + } else { + track.reserve.peak(); + } + } track.timeline = Some(track.timeline.map_or(frame.timestamp, |last| last.max(frame.timestamp))); self.last_timestamp = Some(frame.timestamp); self.advance(frame.timestamp)?; @@ -939,6 +1073,13 @@ impl Export { } let es_pids: Vec = self.tracks.values().map(|t| t.pid).collect(); reject_colliding_si_pids(&mpegts, self.pmt_pid(), &es_pids)?; + // The layout is locked but the timing is not: a `jitter` or `framerate` published + // after the tables still sizes the decode clock. + for (name, config) in catalog.video.renditions.iter() { + if let Some(track) = self.tracks.get_mut(name) { + track.reserve.configure(config, name); + } + } return Ok(()); } @@ -977,21 +1118,20 @@ impl Export { let kind = video_kind(config, name)?; let descriptors = track_descriptors(&mpegts, name); let pid = pids[name]; - // The catalog `jitter` carries the reorder depth (max PTS - DTS), so use it as the - // decode-clock reserve; it may arrive in a later snapshot, so refresh it each time. - let reserve = dts_reserve(config); match old.remove(name) { Some(mut track) => { track.pid = pid; track.kind = kind; track.descriptors = descriptors; - track.dts_reserve = reserve; + track.reserve.configure(config, name); self.tracks.insert(name.clone(), track); } None => { let Some(source) = ExportSource::for_video(&self.source, name, config, self.max_age)? else { continue; }; + let mut reserve = Reserve::default(); + reserve.configure(config, name); self.insert_track(name, source, pid, kind, descriptors, reserve); } } @@ -1011,7 +1151,7 @@ impl Export { let Some(source) = ExportSource::for_audio(&self.source, name, config, self.max_age)? else { continue; }; - self.insert_track(name, source, pid, kind, descriptors, DEFAULT_DTS_RESERVE); + self.insert_track(name, source, pid, kind, descriptors, Reserve::default()); } } } @@ -1035,7 +1175,7 @@ impl Export { } None => { let source = ExportSource::for_stream(&self.source, name, self.max_age)?; - self.insert_track(name, source, pid, kind, descriptors, DEFAULT_DTS_RESERVE); + self.insert_track(name, source, pid, kind, descriptors, Reserve::default()); } } } @@ -1050,7 +1190,7 @@ impl Export { pid: u16, kind: Kind, descriptors: Vec, - dts_reserve: u64, + reserve: Reserve, ) { self.tracks.insert( name.to_string(), @@ -1065,7 +1205,7 @@ impl Export { descriptors, last_dts: None, timeline: None, - dts_reserve, + reserve, }, ); } @@ -1384,7 +1524,7 @@ impl Export { let dts = if is_video { let pts = to_ticks(frame.timestamp); let track = self.tracks.get_mut(name).context("missing track")?; - author_dts(pts, track.dts_reserve, &mut track.last_dts) + author_dts(pts, track.reserve.ticks, &mut track.last_dts) } else { None }; @@ -1691,7 +1831,9 @@ impl Export { /// /// The value backs off by the largest reserve of any track, not just the PCR /// track's: every rendition's PES must decode at or after the clock, and each - /// video track backs its DTS off by its own catalog jitter. Back off through the + /// video track backs its DTS off by its own [`Reserve`]. A reserve that grows steps + /// the clock back with it; the DTS already sent stay ahead of the clock values sent + /// with them, and [`author_dts`] keeps every later DTS above those. Back off through the /// 33-bit wrap rather than saturating: a timeline that starts inside the reserve /// would otherwise clamp its first slots to zero and break the uniform step. The /// wire field is a circular clock, so the masked wrapped value is the correct @@ -1701,7 +1843,7 @@ impl Export { let reserve = self .tracks .values() - .map(|t| t.dts_reserve) + .map(|t| t.reserve.ticks) .max() .unwrap_or(DEFAULT_DTS_RESERVE); let ticks = slot_ticks(index, PCR_INTERVAL).wrapping_sub(reserve); @@ -1936,14 +2078,17 @@ fn counter_before(bytes: &[u8], cut: usize, pid: u16, carried: Option) -> Op const PES_OPTIONAL_LEN: usize = 3 + 5; /// Extra bytes when the optional region also carries a DTS (5 DTS bytes). const PES_DTS_LEN: usize = 5; -/// Fallback decode-clock reserve in 90 kHz ticks when the catalog declares no `jitter`. At -/// 16 ticks (~0.18 ms) it is just a strict-monotonic nudge: it keeps DTS strictly increasing -/// across reordered (B-frame) decode order (the `ffplay -fflags +igndts` fix) but does not -/// keep `DTS <= PTS`. When the catalog carries `jitter` (the reorder depth, populated on -/// import), the track uses that instead, which is large enough to keep `DTS <= PTS`. See -/// [`author_dts`] and [`Track::dts_reserve`]. +/// Fallback decode-clock reserve in 90 kHz ticks when neither the catalog `jitter` nor the SPS +/// sizes one. At 16 ticks (~0.18 ms) it is just a strict-monotonic nudge: it keeps DTS strictly +/// increasing across reordered (B-frame) decode order (the `ffplay -fflags +igndts` fix) but +/// does not keep `DTS <= PTS` until reordering raises it. See [`author_dts`] and [`Reserve`]. const DEFAULT_DTS_RESERVE: u64 = 16; +/// Largest reserve an SPS or observed reordering can raise a track to (2 s): far past any real +/// reorder depth, so a corrupt SPS or a timestamp stepping back within a timeline cannot drag +/// the PCR back without bound. +const MAX_DTS_RESERVE: u64 = 2 * 90_000; + /// Whether `timestamp` has crossed into a later repetition slot than `last`. /// /// Slots are absolute on the media timeline (`floor(timestamp / interval)`) rather than @@ -2203,16 +2348,15 @@ fn ensure_raw(container: &Container, kind: &str, name: &str) -> anyhow::Result<( /// `ffplay -fflags +igndts` workaround). /// /// Since decode order is already the delivery order, the only job is to keep DTS strictly -/// increasing. The clock runs [`DTS_RESERVE`] ticks behind the PTS and never goes backwards: -/// a reordered frame whose PTS dips below the clock is nudged one tick past the last DTS. With -/// the small reserve this keeps DTS monotonic but lets it sit above a B-frame's own PTS; a -/// frame-scale reserve (or the faithful wire DTS) would be needed for `DTS <= PTS`. +/// increasing. The clock runs `reserve` ticks behind the PTS and never goes backwards: a +/// reordered frame whose PTS dips below the clock is nudged one tick past the last DTS. A +/// reserve larger than the reordering keeps `DTS <= PTS`; the [`DEFAULT_DTS_RESERVE`] fallback +/// keeps DTS monotonic but lets it sit above a B-frame's own PTS. /// -/// `reserve` is how far behind the PTS to run the clock (the catalog reorder depth, or the -/// fallback). `pts` and `last` are continuous (unwrapped) 90 kHz ticks, so the clock never -/// wraps mid-stream; the 33-bit wire wrap happens once at emission in [`write_pes`]. `last` is -/// the previous DTS, updated in place. Returns `None` when the DTS equals the PTS (PES stays -/// PTS-only). +/// `reserve` is the track's [`Reserve`]. `pts` and `last` are continuous (unwrapped) 90 kHz +/// ticks, so the clock never wraps mid-stream; the 33-bit wire wrap happens once at emission. +/// `last` is the previous DTS, updated in place. Returns `None` when the DTS equals the PTS +/// (PES stays PTS-only). fn author_dts(pts: u64, reserve: u64, last: &mut Option) -> Option { let mut dts = pts.saturating_sub(reserve); if let Some(prev) = *last @@ -2224,14 +2368,17 @@ fn author_dts(pts: u64, reserve: u64, last: &mut Option) -> Option { (dts != pts).then_some(dts) } -/// The decode-clock reserve for a video rendition: its catalog `jitter` (the reorder depth) -/// in 90 kHz ticks, or [`DEFAULT_DTS_RESERVE`] when none is declared. -fn dts_reserve(config: &VideoConfig) -> u64 { - config - .jitter - .map(|t| (t.as_micros() * 90_000 / 1_000_000) as u64) - .filter(|&ticks| ticks > 0) - .unwrap_or(DEFAULT_DTS_RESERVE) +/// The reordering declared by the first SPS in a video rendition's avcC/hvcC. +fn declared_reorder(stream_type: StreamType, description: &[u8]) -> Option { + match stream_type { + StreamType::H264 => { + crate::codec::h264::sps_reorder(crate::codec::h264::Avcc::parse(description).ok()?.sps.first()?) + } + StreamType::H265 => { + crate::codec::h265::sps_reorder(crate::codec::h265::Hvcc::parse(description).ok()?.sps.first()?) + } + _ => None, + } } #[cfg(test)] diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index 19dd6f9fae3..4c2dec24307 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -4952,3 +4952,342 @@ async fn export_stuffing_keeps_the_fractional_remainder() { ); assert!(clocked.nulls > 0, "no null stuffing was emitted"); } + +// The decode clock follows the stream's reordering: its reserve comes from the catalog `jitter`, +// else the depth the SPS declares, else the reordering muxed so far, and it keeps following all +// three after the program tables are written. + +/// Display offsets within a group, in decode order: a closed GOP with one B-frame per reference. +/// A B-frame lands one frame below the high-water mark. +const IPB: [u64; GOP as usize] = [0, 2, 1, 4, 3, 6, 5, 8, 7, 10, 9, 12, 11, 14, 13]; +/// A three-B pyramid: the outer B-frames sit under the middle one, so one lands three frames +/// below the high-water mark while the SPS can declare a depth of two. +const PYRAMID: [u64; GOP as usize] = [0, 4, 2, 1, 3, 8, 6, 5, 7, 12, 10, 9, 11, 14, 13]; +/// Where the [`Reordered`] timeline starts, in frames: whole groups, and far enough in that +/// the PCR's back-off never wraps below zero. +const REORDERED_BASE: u64 = 20 * GOP; +/// One 25 fps frame in 90 kHz ticks. +const FRAME_TICKS: u64 = 3_600; + +/// The start of video frame `frame` of a [`Reordered`] broadcast, in display order. +fn reordered_at(frame: u64) -> Timestamp { + Timestamp::from_micros((REORDERED_BASE + frame) * VIDEO_US).unwrap() +} + +/// A reordered H.264 rendition and an AAC one, on the late-join fixture's cadence. +struct Reordered { + _broadcast: moq_net::broadcast::Producer, + catalog: crate::catalog::Producer, + video: Producer, + audio: Producer, + source: crate::Source, + name: String, + /// Groups laid out as [`PYRAMID`]; every other group is [`IPB`]. + pyramid: &'static [u64], + audio_index: u64, +} + +impl Reordered { + fn new(sps: &'static [u8], pps: &'static [u8], pyramid: &'static [u64]) -> Self { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let consumer = broadcast.consume(); + let mut catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + + let track = broadcast + .create_track( + broadcast.unique_name(".avc1"), + hang::container::track_info(hang::catalog::PRIORITY.video), + ) + .unwrap(); + let name = track.name().to_string(); + let mut cfg = VideoConfig::new(H264 { + profile: sps[1], + constraints: sps[2], + level: sps[3], + inline: false, + }); + cfg.container = Container::Legacy; + cfg.description = + Some(crate::codec::h264::build_avcc(&[Bytes::from_static(sps)], &[Bytes::from_static(pps)]).unwrap()); + catalog.modify().unwrap().video.renditions.insert(name.clone(), cfg); + let video = Producer::new(track, HangContainer::Legacy(crate::container::Kind::Video)); + + let track = broadcast + .create_track( + broadcast.unique_name(".aac"), + hang::container::track_info(hang::catalog::PRIORITY.audio), + ) + .unwrap(); + let mut cfg = AudioConfig::new(AAC { profile: 2 }, 48_000, 2); + cfg.container = Container::Legacy; + catalog + .modify() + .unwrap() + .audio + .renditions + .insert(track.name().to_string(), cfg); + let audio = Producer::new(track, HangContainer::Legacy(crate::container::Kind::Audio)); + + Self { + source: crate::source::announced(&consumer), + _broadcast: broadcast, + catalog, + video, + audio, + name, + pyramid, + audio_index: 0, + } + } + + /// An exporter with its subscriptions resolved, so later polls need no runtime. + async fn export(&self, max_age: Duration) -> Export { + let mut export = Export::new(self.source.clone()).await.unwrap().with_max_age(max_age); + assert!(drain_frames(&mut export).await.is_empty()); + export + } + + /// Write the video frame `tick`-th in decode order. + fn video(&mut self, tick: u64) { + let (group, at) = (tick / GOP, (tick % GOP) as usize); + let layout = if self.pyramid.contains(&group) { &PYRAMID } else { &IPB }; + let keyframe = at == 0; + let slice = if keyframe { + vec![0x65u8; 3_000] + } else { + vec![0x41u8; 400] + }; + self.video + .write(Frame { + timestamp: reordered_at(group * GOP + layout[at]), + duration: None, + payload: length_prefixed(&[&slice]), + keyframe, + }) + .unwrap(); + } + + /// Write the next audio frame if it starts before video frame `frame`. + fn audio_before(&mut self, frame: u64) -> bool { + let index = self.audio_index; + let timestamp = Timestamp::from_micros(REORDERED_BASE * VIDEO_US + index * AUDIO_US).unwrap(); + if timestamp >= reordered_at(frame) { + return false; + } + self.audio + .write(Frame { + timestamp, + duration: None, + payload: Bytes::from_iter((0..180u16).map(|i| (i ^ index as u16) as u8)), + keyframe: index.is_multiple_of(AUDIO_GROUP), + }) + .unwrap(); + self.audio_index += 1; + true + } + + fn publish_jitter(&mut self, jitter: Duration) { + let mut catalog = self.catalog.modify().unwrap(); + catalog.video.renditions.get_mut(&self.name).unwrap().jitter = Some(jitter); + } + + fn finish(&mut self) { + self.video.finish().unwrap(); + self.audio.finish().unwrap(); + } +} + +/// Export a [`Reordered`] broadcast twice, like [`export_twice`]: the second exporter joins at +/// [`JOIN`], and both are drained after every tick. `jitter` is published at its tick when given. +async fn export_reordered( + sps: &'static [u8], + pps: &'static [u8], + pyramid: &'static [u64], + jitter: Option<(u64, Duration)>, +) -> (Vec, Vec) { + let mut rig = Reordered::new(sps, pps, pyramid); + let mut a = Export::new(rig.source.clone()).await.unwrap(); + let mut b = None; + let (mut out_a, mut out_b) = (Vec::new(), Vec::new()); + for tick in 0..TICKS { + if let Some((at, jitter)) = jitter + && at == tick + { + rig.publish_jitter(jitter); + } + rig.video(tick); + while rig.audio_before(tick + 1) {} + + out_a.extend(drain_frames(&mut a).await); + if let Some(b) = b.as_mut() { + out_b.extend(drain_frames(b).await); + } + if tick + 1 == JOIN { + b = Some(Export::new(rig.source.clone()).await.unwrap()); + } + } + rig.finish(); + let mut b = b.unwrap(); + out_a.extend(drain_frames(&mut a).await); + out_b.extend(drain_frames(&mut b).await); + (out_a, out_b) +} + +/// `(PTS, DTS)` of every video PES start in the frames stamped within `range`, in transport +/// order. The whole stream is read so the program tables resolve every PID. +fn video_timing(frames: &[Frame], range: impl std::ops::RangeBounds) -> Vec<(u64, Option)> { + let stamps: Vec = frames + .iter() + .flat_map(|f| std::iter::repeat_n(f.timestamp, f.payload.len() / 188)) + .collect(); + let bytes: Vec = frames.iter().flat_map(|f| f.payload.iter().copied()).collect(); + let mut reader = TsPacketReader::new(Cursor::new(bytes)); + let mut out = Vec::new(); + let mut index = 0; + while let Some(packet) = reader.read_ts_packet().unwrap() { + let stamp = stamps[index]; + index += 1; + if !range.contains(&stamp) { + continue; + } + if let Some(TsPayload::PesStart(pes)) = packet.payload + && (mpeg2ts::es::StreamId::VIDEO_MIN..=mpeg2ts::es::StreamId::VIDEO_MAX) + .contains(&pes.header.stream_id.as_u8()) + { + let pts = pes.header.pts.expect("video PES carried no PTS").as_u64(); + out.push((pts, pes.header.dts.map(|t| t.as_u64()))); + } + } + out +} + +/// Every video frame decodes at or before it is presented. +fn assert_decodes_before_presenting(timing: &[(u64, Option)]) { + assert!(timing.len() > 20, "too few video frames to judge: {}", timing.len()); + for (i, &(pts, dts)) in timing.iter().enumerate() { + let dts = dts.unwrap_or(pts); + assert!(dts <= pts, "frame {i} decodes at {dts}, after it is presented at {pts}"); + } +} + +/// In transport order, every PES unit decodes at or after the last PCR preceding it. +fn assert_decodes_after_the_clock(frames: &[Frame]) { + let bytes: Vec = frames.iter().flat_map(|f| f.payload.iter().copied()).collect(); + let mut reader = TsPacketReader::new(Cursor::new(bytes)); + let mut last_pcr = None; + while let Some(packet) = reader.read_ts_packet().unwrap() { + if let Some(pcr) = packet.adaptation_field.as_ref().and_then(|af| af.pcr) { + last_pcr = Some(pcr.as_u64() / 300); + } + if let Some(TsPayload::PesStart(pes)) = packet.payload + && let Some(pcr) = last_pcr + { + let pts = pes.header.pts.expect("PES carried no PTS").as_u64(); + let decode = pes.header.dts.map(|t| t.as_u64()).unwrap_or(pts); + assert!(decode >= pcr, "unit decodes at {decode}, before the clock at {pcr}"); + } + } +} + +/// With no `jitter`, an SPS that declares its reorder depth at a fixed frame rate sizes the +/// reserve from the first keyframe: every B-frame decodes at or before it is presented from the +/// start, and an exporter whose B-frames arrive behind the audio covering them renders the same +/// bytes as one that sees each tick whole. +#[tokio::test(start_paused = true)] +async fn declared_reorder_sizes_the_decode_clock_from_the_first_frame() { + let mut rig = Reordered::new( + crate::codec::h264::fixtures::SPS_IPB, + crate::codec::h264::fixtures::PPS, + &[], + ); + let max_age = Duration::from_millis(500); + let (mut late, mut whole) = (rig.export(max_age).await, rig.export(max_age).await); + let (mut out_late, mut out_whole) = (Vec::new(), Vec::new()); + for tick in 0..TICKS / 2 { + while rig.audio_before(tick + 2) { + out_late.extend(poll_frames(&mut late)); + } + rig.video(tick); + out_late.extend(poll_frames(&mut late)); + out_whole.extend(poll_frames(&mut whole)); + } + rig.finish(); + out_late.extend(drain_frames(&mut late).await); + out_whole.extend(drain_frames(&mut whole).await); + + let late: Vec = out_late.iter().flat_map(|f| f.payload.iter().copied()).collect(); + let whole: Vec = out_whole.iter().flat_map(|f| f.payload.iter().copied()).collect(); + assert!(late.len() > 100 * 188, "too little output to compare: {}", late.len()); + assert!(late == whole, "arrival order changed the rendering"); + + let timing = video_timing(&out_late, ..); + assert_decodes_before_presenting(&timing); + // Depth 1 at 25 fps, and one tick so the B-frame decodes after the P-frame above it. + let (pts, dts) = timing[1]; + assert_eq!( + pts, + (REORDERED_BASE + 2) * FRAME_TICKS, + "the first P-frame follows the keyframe" + ); + assert_eq!( + dts, + Some(pts - FRAME_TICKS - 1), + "the first P-frame already runs on the declared reserve" + ); + assert_decodes_after_the_clock(&out_late); +} + +/// With nothing declared, the reserve grows to the deepest reordering muxed so far. This is the +/// one path where it depends on when an exporter joined: a joiner that has muxed only shallow +/// groups runs a shallower clock than a runner that saw a deep one before the join, until the +/// deep structure recurs. From then on the two render the same bytes. +#[tokio::test(start_paused = true)] +async fn undeclared_reorder_converges_after_its_deepest_reorder() { + // The runner sees a pyramid in group 2; the joiner, arriving at group 5, first in group 7. + // Group 9 repeats it on the settled reserve. + let (runner, joiner) = export_reordered(SPS, PPS, &[2, 7, 9], None).await; + let keyframes: Vec = joiner.iter().filter(|f| f.keyframe).map(|f| f.timestamp).collect(); + let deepest = reordered_at(8 * GOP); + assert!( + keyframes[1] < deepest, + "the joiner must render shallow groups before the deep one" + ); + + assert_ne!( + video_timing(&runner, keyframes[1]..deepest), + video_timing(&joiner, keyframes[1]..deepest), + "a joiner that has not muxed the deepest reordering runs the runner's clock" + ); + assert_only_continuity_differs(&runner, &joiner, deepest); + + for frames in [&runner, &joiner] { + assert_decodes_before_presenting(&video_timing(frames, deepest..)); + // Growth steps the reserve up mid-stream; the clock must still never overtake a decode. + assert_decodes_after_the_clock(frames); + } +} + +/// A `jitter` first published after the program tables sizes the decode clock from then on, +/// so the running exporter renders what a joiner that found it in its first catalog renders. +#[tokio::test(start_paused = true)] +async fn jitter_published_after_the_tables_raises_the_reserve() { + let jitter = Duration::from_millis(80); + let (runner, joiner) = export_reordered(SPS, PPS, &[], Some((2 * GOP, jitter))).await; + let keyframes: Vec = joiner.iter().filter(|f| f.keyframe).map(|f| f.timestamp).collect(); + assert_only_continuity_differs(&runner, &joiner, keyframes[1]); + + // Every keyframe after the publish decodes a full `jitter` ahead of its presentation. + let ticks = 80 * 90; + let keyframe_timing: Vec<(u64, Option)> = video_timing(&runner, reordered_at(3 * GOP)..) + .into_iter() + .filter(|(pts, _)| (pts / FRAME_TICKS).is_multiple_of(GOP)) + .collect(); + assert!( + keyframe_timing.len() > 3, + "too few keyframes to judge: {keyframe_timing:?}" + ); + for (pts, dts) in keyframe_timing { + assert_eq!(dts, Some(pts - ticks), "keyframe at {pts} ignores the published jitter"); + } + assert_decodes_after_the_clock(&runner); +} From c2e7b58154450f179013e74219adfcf9b62753f6 Mon Sep 17 00:00:00 2001 From: t0ms Date: Tue, 29 Sep 2026 19:06:46 +0100 Subject: [PATCH 025/128] feat(srt): log the TS importer's per-stream counters on ingest (#4506) Co-authored-by: Claude Opus 5.5 Co-authored-by: Luke Curley --- Cargo.lock | 3 +- doc/bin/srt.md | 5 +- quest/m1/README.md | 1 - quest/m1/srt-import-stats.md | 17 --- rs/moq-cli/Cargo.toml | 1 - rs/moq-cli/src/publish.rs | 106 +----------------- rs/moq-mux/Cargo.toml | 1 + rs/moq-mux/src/container/ts/mod.rs | 2 + rs/moq-mux/src/container/ts/stats.rs | 159 +++++++++++++++++++++++++++ rs/moq-srt/Cargo.toml | 1 + rs/moq-srt/README.md | 4 +- rs/moq-srt/src/ts.rs | 144 +++++++++++++++++++++++- 12 files changed, 318 insertions(+), 126 deletions(-) delete mode 100644 quest/m1/srt-import-stats.md create mode 100644 rs/moq-mux/src/container/ts/stats.rs diff --git a/Cargo.lock b/Cargo.lock index 2e88d5942d8..32884ac4e37 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4315,7 +4315,6 @@ dependencies = [ "tokio", "tower-http 0.7.1", "tracing", - "tracing-test", "url", "usage-rs", "winit", @@ -4480,6 +4479,7 @@ dependencies = [ "thiserror 2.0.21", "tokio", "tracing", + "tracing-test", "url", "web-async", "webm-iterable", @@ -4746,6 +4746,7 @@ dependencies = [ "thiserror 2.0.21", "tokio", "tracing", + "tracing-test", ] [[package]] diff --git a/doc/bin/srt.md b/doc/bin/srt.md index bd8e852ab71..141ea5cbb46 100644 --- a/doc/bin/srt.md +++ b/doc/bin/srt.md @@ -8,7 +8,10 @@ description: SRT contribution and playback `moq import srt` accepts SRT pushes (`--listen`) or pulls from a remote SRT source (`--connect`); `moq export srt` serves SRT to players or pushes to a remote. The payload is MPEG-TS, so the same codecs as [`import ts`](/bin/cli) -apply: H.264/H.265 video and AAC, MP2, AC-3, or E-AC-3 audio. +apply: H.264/H.265 video and AAC, MP2, AC-3, or E-AC-3 audio. Ingest logs the +same per-stream lines as `import ts`, under an `srt{path=...}` span: an +elementary stream that stopped delivering access units, and audio frame sync +lost. ```bash # Accept a contribution feed and publish it diff --git a/quest/m1/README.md b/quest/m1/README.md index cada8fa4f73..1cbfb583a17 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -157,7 +157,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [#3021](/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md) - GStreamer maps every pad onto one continuous broadcast clock across source restarts - [Export linger](/quest/m1/export-linger.md) - every `moq export` waits `--linger` for a broadcast to return, and exits 0 on a clean end and 1 on a drop - [TS byte schedule](/quest/m1/ts-export-byte-schedule.md) - moq export ts places PCRs and padding on the byte grid `mpegts.muxRate` implies, so a receiver can clock off arrival -- [SRT import stats](/quest/m1/srt-import-stats.md) - the SRT gateway reports the same per-stream counters instead of nothing - [Text availability](/quest/m1/text-schema.md) - a text track publishes its own coverage index instead of copying the media timeline - [ID3 catalog section](/quest/m1/id3.md) - timed ID3 as a first-class container-neutral catalog section - [FLV script tags](/quest/m1/flv-script.md) - onMetaData and AMF data messages survive RTMP and FLV import diff --git a/quest/m1/srt-import-stats.md b/quest/m1/srt-import-stats.md deleted file mode 100644 index 448f8b214b0..00000000000 --- a/quest/m1/srt-import-stats.md +++ /dev/null @@ -1,17 +0,0 @@ -# [S] moq-srt reports the same import stats as moq import ts - -## Goal - -An operator running the SRT gateway sees the TS importer's per-stream -counters (access units, quiet gap, resyncs) the way `moq import ts` logs -them, instead of nothing. SRT contribution is where a silent PID matters -most, and today `rs/moq-srt/src/ts.rs` only calls `decode`. - -## Plan - -- Poll `self.importer.stats()` on the SRT publisher's existing - `ts::Import` at the same cadence as the CLI. -- Share the logging presentation with `rs/moq-cli/src/publish.rs` where - needed so the two front doors report the same rows. -- Test: the SRT harness feeds the suppressed-PID stimulus from the TS - import tests and asserts the gateway reports the stalled row. diff --git a/rs/moq-cli/Cargo.toml b/rs/moq-cli/Cargo.toml index 14f91b13366..4078f83f2e7 100644 --- a/rs/moq-cli/Cargo.toml +++ b/rs/moq-cli/Cargo.toml @@ -134,7 +134,6 @@ tempfile = { workspace = true } # `test-util` enables `tokio::time::pause` so the TS round-trip test simulates the # exporter drain timeouts instantly instead of waiting on the wall clock. tokio = { workspace = true, features = ["test-util"] } -tracing-test = { workspace = true, features = ["no-env-filter"] } [[bench]] name = "play_buffer" diff --git a/rs/moq-cli/src/publish.rs b/rs/moq-cli/src/publish.rs index 00f193517c5..b21f8978ed6 100644 --- a/rs/moq-cli/src/publish.rs +++ b/rs/moq-cli/src/publish.rs @@ -132,65 +132,6 @@ pub struct CaptureArgs { pub no_audio: bool, } -/// How often `import ts` compares the importer's per-stream counters. -/// -/// Long enough that every continuous stream delivers many access units in between, so a -/// count that did not move is a stream that stopped rather than one between frames. -const STATS_INTERVAL: std::time::Duration = std::time::Duration::from_secs(1); - -/// Logs what moved in the importer's per-stream counters from one sample to the next. -#[derive(Default)] -struct StatsLog { - previous: Option, - /// Streams already reported quiet, so a silence is logged when it starts and not again - /// until the stream has delivered. - quiet: std::collections::BTreeSet, -} - -impl StatsLog { - /// Compare a sample taken [`STATS_INTERVAL`] after the last. - fn sample(&mut self, latest: ts::Stats) { - self.sync(&latest); - for (pid, stream) in &latest.streams { - let previous = self.previous.as_ref().and_then(|previous| previous.streams.get(pid)); - if previous.is_none_or(|previous| previous.units != stream.units) { - self.quiet.remove(pid); - } else if self.quiet.insert(*pid) { - tracing::info!( - pid = *pid, - track = stream.track, - units = stream.units, - quiet = ?stream.quiet, - "elementary stream stopped delivering access units" - ); - } - } - self.previous = Some(latest); - } - - /// Report the streams whose frame-sync counters moved, one line each. - /// - /// The importer already warns on each individual resync; this is the running total, which - /// is what an operator turns into a rate. - fn sync(&self, latest: &ts::Stats) { - let lost = |stream: &ts::StreamStats| (stream.resyncs, stream.discarded, stream.unconfirmed); - for (pid, stream) in &latest.streams { - let previous = self.previous.as_ref().and_then(|previous| previous.streams.get(pid)); - if previous.map_or((0, 0, 0), lost) == lost(stream) { - continue; - } - tracing::info!( - pid = *pid, - track = stream.track, - resyncs = stream.resyncs, - discarded = stream.discarded, - unconfirmed = stream.unconfirmed, - "audio frame sync lost" - ); - } - } -} - enum PublishDecoder { Avc3 { split: Box, @@ -475,7 +416,7 @@ async fn decode( // Counters reported so far, so only the change is logged. A live feed is // diagnosed by the rate at which these climb, and stdin may never end, so // they have to surface as they accumulate rather than at exit. - let mut log = StatsLog::default(); + let mut log = ts::stats::Log::default(); let mut sampled = tokio::time::Instant::now(); // Run the read/decode loop so an error surfaces here rather than @@ -489,7 +430,7 @@ async fn decode( } decoder.decode_chunk(&buffer)?; - if sampled.elapsed() >= STATS_INTERVAL { + if sampled.elapsed() >= ts::stats::Log::INTERVAL { sampled = tokio::time::Instant::now(); if let Some(stats) = decoder.stats() { log.sample(stats); @@ -504,10 +445,9 @@ async fn decode( // a bare Error::Dropped. let outcome = result.and_then(|()| decoder.finish()); // The drain at end of input can publish a frame nothing vouched for, so the - // final snapshot is only complete after `finish`. It covers less than an interval, so - // only the frame sync is compared. + // final snapshot is only complete after `finish`. if let Some(stats) = decoder.stats() { - log.sync(&stats); + log.finish(&stats); } match outcome { Ok(()) => catalog.finish(), @@ -922,44 +862,6 @@ mod tests { assert_eq!(last.audio.renditions.len(), 1, "the audio rendition is still listed"); } - /// A stream whose count stops across a sample is logged once, with its silence, and again - /// only after it has delivered in between; a stream that keeps counting never is, and - /// neither reports frame sync it never lost. - #[test] - #[tracing_test::traced_test] - fn stats_log_reports_a_stream_that_stopped() { - const VIDEO: u16 = 0x100; - const AUDIO: u16 = 0x101; - let sample = |video: u64, audio: u64| { - let mut stats = ts::Stats::default(); - for (pid, track, units) in [(VIDEO, ".avc3", video), (AUDIO, ".mp2", audio)] { - let mut stream = ts::StreamStats::default(); - stream.track = track; - stream.units = units; - stream.quiet = Some(Duration::from_millis(40)); - stats.streams.insert(pid, stream); - } - stats - }; - - let mut log = StatsLog::default(); - for (video, audio) in [(10, 10), (10, 20), (10, 30), (11, 40), (11, 50)] { - log.sample(sample(video, audio)); - } - - logs_assert(|lines: &[&str]| { - let stopped: Vec<_> = lines - .iter() - .filter(|line| line.contains("stopped delivering access units")) - .collect(); - match stopped.as_slice() { - [first, second] if [first, second].iter().all(|line| line.contains("pid=256")) => Ok(()), - _ => Err(format!("expected two lines for the video PID, got {stopped:?}")), - } - }); - assert!(!logs_contain("audio frame sync lost"), "nothing lost frame sync"); - } - /// Read the first frame of a verbatim track back as raw bytes. async fn read_frame(consumer: &moq_net::broadcast::Consumer, name: &str) -> Vec { let track = consumer.track(name).unwrap().subscribe(None).await.unwrap(); diff --git a/rs/moq-mux/Cargo.toml b/rs/moq-mux/Cargo.toml index 315fad5b99d..5828a2b46af 100644 --- a/rs/moq-mux/Cargo.toml +++ b/rs/moq-mux/Cargo.toml @@ -43,3 +43,4 @@ webm-iterable = "0.7" [dev-dependencies] futures = { workspace = true } tokio = { workspace = true, features = ["test-util"] } +tracing-test = { workspace = true, features = ["no-env-filter"] } diff --git a/rs/moq-mux/src/container/ts/mod.rs b/rs/moq-mux/src/container/ts/mod.rs index 1a8b9e0a0e5..da0158c5b10 100644 --- a/rs/moq-mux/src/container/ts/mod.rs +++ b/rs/moq-mux/src/container/ts/mod.rs @@ -33,6 +33,8 @@ pub use catalog::{Catalog, Descriptor, Ext, Framing, Mpegts, Program, SiEntry, T pub use export::*; pub use import::*; +pub mod stats; + #[cfg(test)] mod export_test; #[cfg(test)] diff --git a/rs/moq-mux/src/container/ts/stats.rs b/rs/moq-mux/src/container/ts/stats.rs new file mode 100644 index 00000000000..9853721168e --- /dev/null +++ b/rs/moq-mux/src/container/ts/stats.rs @@ -0,0 +1,159 @@ +//! Reporting on the per-stream counters [`Import::stats`](super::Import::stats) returns. + +use std::collections::BTreeSet; + +use super::{Stats, StreamStats}; + +/// Logs what moved in an importer's [`Stats`] from one sample to the next, so every front +/// door that runs a TS importer reports the same lines. +/// +/// Feed it a snapshot every [`INTERVAL`](Self::INTERVAL) of wall time. The caller owns the +/// timer, since what counts as "now" differs between a CLI, a server, and a test. +#[derive(Default)] +pub struct Log { + previous: Option, + /// Streams already reported quiet, so a silence is logged when it starts and not again + /// until the stream has delivered. + quiet: BTreeSet, +} + +impl Log { + /// How often to [`sample`](Self::sample). + /// + /// Long enough that every continuous stream delivers many access units in between, so a + /// count that did not move is a stream that stopped rather than one between frames. + pub const INTERVAL: std::time::Duration = std::time::Duration::from_secs(1); + + /// Compare a snapshot taken [`INTERVAL`](Self::INTERVAL) after the last. + /// + /// Logs a stream whose access units did not advance since the last sample, once per + /// silence, and any stream whose frame-sync counters moved. + pub fn sample(&mut self, latest: Stats) { + self.sync(&latest); + for (pid, stream) in &latest.streams { + let previous = self.previous.as_ref().and_then(|previous| previous.streams.get(pid)); + if previous.is_none_or(|previous| previous.units != stream.units) { + self.quiet.remove(pid); + } else if self.quiet.insert(*pid) { + tracing::info!( + pid = *pid, + track = stream.track, + units = stream.units, + quiet = ?stream.quiet, + "elementary stream stopped delivering access units" + ); + } + } + self.previous = Some(latest); + } + + /// Compare the snapshot taken after [`Import::finish`](super::Import::finish). + /// + /// It covers less than an interval, so only the frame sync is compared: the drain at end + /// of input can publish a frame nothing vouched for. + pub fn finish(&self, latest: &Stats) { + self.sync(latest); + } + + /// Report the streams whose frame-sync counters moved, one line each. + /// + /// The importer already warns on each individual resync; this is the running total, which + /// is what an operator turns into a rate. + fn sync(&self, latest: &Stats) { + let lost = |stream: &StreamStats| (stream.resyncs, stream.discarded, stream.unconfirmed); + for (pid, stream) in &latest.streams { + let previous = self.previous.as_ref().and_then(|previous| previous.streams.get(pid)); + if previous.map_or((0, 0, 0), lost) == lost(stream) { + continue; + } + tracing::info!( + pid = *pid, + track = stream.track, + resyncs = stream.resyncs, + discarded = stream.discarded, + unconfirmed = stream.unconfirmed, + "audio frame sync lost" + ); + } + } +} + +#[cfg(test)] +mod test { + use super::*; + + /// A stream whose count stops across a sample is logged once, with its silence, and again + /// only after it has delivered in between; a stream that keeps counting never is, and + /// neither reports frame sync it never lost. + #[test] + #[tracing_test::traced_test] + fn reports_a_stream_that_stopped() { + const VIDEO: u16 = 0x100; + const AUDIO: u16 = 0x101; + let sample = |video: u64, audio: u64| { + let mut stats = Stats::default(); + for (pid, track, units) in [(VIDEO, ".avc3", video), (AUDIO, ".mp2", audio)] { + let stream = StreamStats { + track, + units, + quiet: Some(std::time::Duration::from_millis(40)), + ..Default::default() + }; + stats.streams.insert(pid, stream); + } + stats + }; + + let mut log = Log::default(); + for (video, audio) in [(10, 10), (10, 20), (10, 30), (11, 40), (11, 50)] { + log.sample(sample(video, audio)); + } + + logs_assert(|lines: &[&str]| { + let stopped: Vec<_> = lines + .iter() + .filter(|line| line.contains("stopped delivering access units")) + .collect(); + match stopped.as_slice() { + [first, second] if [first, second].iter().all(|line| line.contains("pid=256")) => Ok(()), + _ => Err(format!("expected two lines for the video PID, got {stopped:?}")), + } + }); + assert!(!logs_contain("audio frame sync lost"), "nothing lost frame sync"); + } + + /// A resync is reported on the sample that saw it, and the end of input still reports one + /// the last partial interval found. + #[test] + #[tracing_test::traced_test] + fn reports_frame_sync_lost_at_the_end() { + let sample = |resyncs: u64, units: u64| { + let stream = StreamStats { + track: ".mp2", + units, + resyncs, + ..Default::default() + }; + let mut stats = Stats::default(); + stats.streams.insert(0x101, stream); + stats + }; + + let mut log = Log::default(); + log.sample(sample(0, 10)); + log.sample(sample(0, 20)); + log.finish(&sample(1, 21)); + + logs_assert(|lines: &[&str]| { + match lines + .iter() + .filter(|line| line.contains("audio frame sync lost")) + .count() + { + 1 => Ok(()), + n => Err(format!("expected one frame-sync line, got {n}")), + } + }); + assert!(!logs_contain("stopped delivering"), "the stream kept counting"); + } +} diff --git a/rs/moq-srt/Cargo.toml b/rs/moq-srt/Cargo.toml index 44dd4bba92e..d6f5899d543 100644 --- a/rs/moq-srt/Cargo.toml +++ b/rs/moq-srt/Cargo.toml @@ -30,3 +30,4 @@ tracing = { workspace = true } # Builds the synthetic broadcasts the egress tests mux back to TS. hang = { path = "../hang" } srt-protocol = "0.4" +tracing-test = { workspace = true, features = ["no-env-filter"] } diff --git a/rs/moq-srt/README.md b/rs/moq-srt/README.md index b7eb3cf0f1d..36a25f5a68d 100644 --- a/rs/moq-srt/README.md +++ b/rs/moq-srt/README.md @@ -8,7 +8,9 @@ by its stream id `m=` mode: - `m=publish` (the default): ingest. Demux the connection's transport stream with [`moq-mux`](../moq-mux) and publish it into a MoQ origin as an ordinary broadcast. The contribution-ingest analogue of `moq-cli` HLS import and - `moq-rtc`'s WHIP. + `moq-rtc`'s WHIP. Once a second it logs the importer's per-stream counters + the way `moq import ts` does, so a PID that goes silent behind a running mux + is named. - `m=request`: egress. Re-mux a broadcast from the origin back to MPEG-TS and stream it to the caller, so `vlc srt://...` and `ffmpeg -i srt://...` can play any broadcast the origin carries (H.264/H.265 video, AAC/AC-3/MP2 audio). diff --git a/rs/moq-srt/src/ts.rs b/rs/moq-srt/src/ts.rs index 8e6ccf2abc4..f81681c5e18 100644 --- a/rs/moq-srt/src/ts.rs +++ b/rs/moq-srt/src/ts.rs @@ -30,6 +30,11 @@ pub struct Publisher { // A clone of the importer's producer, so an end can close the broadcast // (prompt unannounce) even though the importer owns it. broadcast: moq_net::broadcast::Producer, + // The importer's per-stream counters, logged as `moq import ts` logs them, under a + // span naming the path, since one server carries many ingests. + log: ts::stats::Log, + sampled: tokio::time::Instant, + span: tracing::Span, } impl Publisher { @@ -50,21 +55,34 @@ impl Publisher { Ok(Self { importer, broadcast: handle, + log: ts::stats::Log::default(), + sampled: tokio::time::Instant::now(), + span: tracing::info_span!("srt", %path), }) } /// Feed a chunk of MPEG-TS bytes (one SRT payload) into the importer. /// /// `decode` drains `data` fully, buffering any partial trailing packet in - /// its own internal scratch, so there's nothing to retain here. + /// its own internal scratch, so there's nothing to retain here. Once every + /// [`ts::stats::Log::INTERVAL`] it also logs what moved in the importer's + /// per-stream counters. pub fn feed(&mut self, data: Bytes) -> Result<()> { - Ok(self.importer.decode(&data).map_err(moq_mux::Error::from)?) + self.importer.decode(&data).map_err(moq_mux::Error::from)?; + if self.sampled.elapsed() >= ts::stats::Log::INTERVAL { + self.sampled = tokio::time::Instant::now(); + let _span = self.span.enter(); + self.log.sample(self.importer.stats()); + } + Ok(()) } /// Flush any buffered media, close out the broadcast's open groups, and end /// the broadcast so the origin unannounces it immediately. pub fn finish(&mut self) -> Result<()> { self.importer.finish().map_err(moq_mux::Error::from)?; + // The drain at end of input can publish a frame nothing vouched for. + self.span.in_scope(|| self.log.finish(&self.importer.stats())); self.broadcast.close(); Ok(()) } @@ -162,6 +180,94 @@ mod tests { /// moq-mux's export tests replay. const BBB5S: &[u8] = include_bytes!("../../moq-mux/src/container/ts/test_data/scte35/bbb5s.ts"); + /// The PCR a packet's adaptation field carries, in 27 MHz ticks. + fn pcr(pkt: &[u8]) -> Option { + if pkt[3] & 0x20 == 0 || pkt[4] < 7 || pkt[5] & 0x10 == 0 { + return None; + } + let base = (u64::from(pkt[6]) << 25) + | (u64::from(pkt[7]) << 17) + | (u64::from(pkt[8]) << 9) + | (u64::from(pkt[9]) << 1) + | (u64::from(pkt[10]) >> 7); + Some(base * 300 + ((u64::from(pkt[10] & 0x01) << 8) | u64::from(pkt[11]))) + } + + /// Each packet of `ts` with the program clock it arrives at, counted from the first PCR. + fn timed(ts: &[u8]) -> impl Iterator { + let mut first = None; + let mut now = Duration::ZERO; + ts.as_chunks::<188>().0.iter().map(move |pkt| { + if let Some(pcr) = pcr(pkt) { + let first = *first.get_or_insert(pcr); + now = Duration::from_nanos((pcr - first) * 1_000 / 27); + } + (now, pkt) + }) + } + + /// `ts` with the PES on `pid` suppressed from its first PES start at or after `from` to + /// its first at or after `to`, as an encoder whose one input died behind a running mux + /// emits it: the PCR kept in adaptation-only packets, everything else null stuffing, and + /// the counters after the gap renumbered so continuity stays legal. The stimulus the + /// moq-mux TS import tests check is legal. + fn suppress(ts: &[u8], pid: u16, from: Duration, to: Duration) -> Vec { + let mut null = [0xff; 188]; + null[..4].copy_from_slice(&[0x47, 0x1f, 0xff, 0x10]); + + let mut out = Vec::with_capacity(ts.len()); + let (mut active, mut done) = (false, false); + let (mut last_cc, mut dropped) = (0, 0u8); + for (now, pkt) in timed(ts) { + let mut pkt = *pkt; + if (u16::from(pkt[1] & 0x1f) << 8) | u16::from(pkt[2]) == pid { + if pkt[1] & 0x40 != 0 { + if !active && !done && now >= from { + active = true; + } else if active && now >= to { + (active, done) = (false, true); + } + } + let payload = pkt[3] & 0x10 != 0; + if active { + dropped = (dropped + u8::from(payload)) & 0x0f; + pkt = match pcr(&pkt) { + Some(_) => { + let mut clock = [0xff; 188]; + clock[..6].copy_from_slice(&[0x47, pkt[1] & 0x1f, pkt[2], 0x20 | last_cc, 183, 0x10]); + clock[6..12].copy_from_slice(&pkt[6..12]); + clock + } + None => null, + }; + } else { + pkt[3] = (pkt[3] & 0xf0) | (pkt[3].wrapping_sub(dropped) & 0x0f); + if payload { + last_cc = pkt[3] & 0x0f; + } + } + } + out.extend_from_slice(&pkt); + } + assert!(done, "the fixture must resume the PID before it ends"); + out + } + + /// Publish `ts` on `path` one SRT payload (7 packets) at a time, each delivered when the + /// program clock says it is due. + async fn ingest(origin: &moq_net::origin::Producer, path: &str, ts: &[u8]) { + let mut publisher = Publisher::new(origin, path, Default::default()).unwrap(); + let mut clock = Duration::ZERO; + for payload in timed(ts).collect::>().chunks(7) { + let (due, _) = payload[0]; + tokio::time::advance(due.saturating_sub(clock)).await; + clock = clock.max(due); + let bytes: Vec = payload.iter().flat_map(|(_, pkt)| pkt.iter().copied()).collect(); + publisher.feed(bytes.into()).unwrap(); + } + publisher.finish().unwrap(); + } + /// One payload-only TS packet carrying a complete PSI section (PUSI + pointer_field /// 0), padded to 188 with stuffing. fn psi_packet(pid: u16, section: &[u8]) -> Vec { @@ -229,6 +335,40 @@ mod tests { assert_eq!(info.max_age, Duration::from_secs(3)); } + /// A video PID that goes silent behind a running mux is logged against its ingest path, + /// and neither the same feed intact nor the audio that kept delivering is. + #[tokio::test(start_paused = true)] + #[tracing_test::traced_test] + async fn publisher_reports_a_silent_pid() { + const VIDEO: u16 = 0x100; + let origin = produce_origin(); + ingest(&origin, "intact", BBB5S).await; + let stimulus = suppress(BBB5S, VIDEO, Duration::from_millis(1500), Duration::from_millis(3500)); + ingest(&origin, "silent", &stimulus).await; + + logs_assert(|lines: &[&str]| { + let stopped: Vec<_> = lines + .iter() + .filter(|line| line.contains("stopped delivering access units")) + .collect(); + let reported = |path: &str, pid: u16| { + stopped + .iter() + .any(|line| line.contains(&format!("path={path}")) && line.contains(&format!("pid={pid} "))) + }; + if !reported("silent", VIDEO) { + return Err(format!("the silent video PID was not reported: {stopped:?}")); + } + if reported("intact", VIDEO) { + return Err(format!("the intact feed's video was reported: {stopped:?}")); + } + if reported("silent", 0x101) || reported("intact", 0x101) { + return Err(format!("the audio kept delivering: {stopped:?}")); + } + Ok(()) + }); + } + /// SRT is a contribution protocol, so SCTE-35 cues survive ingest and egress. #[tokio::test(start_paused = true)] async fn publisher_preserves_scte35_cues() { From 6543a7f4cd4b9979b1c11c199384170b65e04e87 Mon Sep 17 00:00:00 2001 From: t0ms Date: Tue, 29 Sep 2026 19:13:25 +0100 Subject: [PATCH 026/128] chore(quest): plan TR 101 290 monitoring (#4496) Co-authored-by: Claude Opus 5.5 Co-authored-by: Cursor Co-authored-by: Luke Curley --- quest/m1/README.md | 2 +- quest/m1/qos/stats/README.md | 2 + quest/m1/qos/stats/per-track.md | 42 +++++++ quest/m1/ts-psi-reassembly.md | 34 +++-- ...ing-requirements-broadcast-contribution.md | 40 ------ quest/m2/README.md | 4 +- quest/m2/ts-export-liveness.md | 50 ++++++++ quest/m2/ts-health-stats.md | 39 ++++++ quest/m2/ts-import-health.md | 116 ++++++++++++++++++ 9 files changed, 277 insertions(+), 52 deletions(-) create mode 100644 quest/m1/qos/stats/per-track.md delete mode 100644 quest/m2/1838-tr-101-290-monitoring-requirements-broadcast-contribution.md create mode 100644 quest/m2/ts-export-liveness.md create mode 100644 quest/m2/ts-health-stats.md create mode 100644 quest/m2/ts-import-health.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 1cbfb583a17..4c9068da8fe 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -54,7 +54,7 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Full codec string](/quest/m1/publish-codec-string.md) - browser-published video carries the encoder's full RFC 6381 codec string, so native players decode it - [TS program selection](/quest/m1/ts-programs.md) - `import ts` refuses a multi-program stream unless `--program ` picks one or publishes each - [TS import shared shift](/quest/m1/ts-import-shared-shift.md) - unflagged loop wraps move audio and video by one shift, so A/V sync holds across wraps -- [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) - `import ts` reads a PAT or PMT that spans packets or follows a nonzero pointer_field instead of aborting +- [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) - `import ts` reads a PAT or PMT that spans packets or follows a nonzero pointer_field instead of aborting, and one corrupted section costs a repetition and a counted `CRC_error`, not the import - [Same-hop importers](/quest/m1/hop-aligned-import.md) - importers sharing a `--hop` and fed one stream publish identical groups and timestamps, so failover survives - [PipeWire duplicate cameras](/quest/m1/pipewire-dup-cameras.md) - a webcam lists once with PipeWire enabled - [Catalog wall clock](/quest/m1/catalog-wall-clock.md) - `Clock::wall_clock` keeps the catalog's full precision instead of truncating to milliseconds diff --git a/quest/m1/qos/stats/README.md b/quest/m1/qos/stats/README.md index b74ec7f73f9..2c566bd11c1 100644 --- a/quest/m1/qos/stats/README.md +++ b/quest/m1/qos/stats/README.md @@ -51,6 +51,8 @@ Decisions settled while planning: ## Required +- [Per-track stats](/quest/m1/qos/stats/per-track.md) - decide whether media + stats ride one track per catalog track, before the schema settles - [Schema and library](/quest/m1/qos/stats/schema.md) - moq-stats takes an extension, serves per-broadcast tracks, and hang defines the media stats - [Rust reporters](/quest/m1/qos/stats/rust.md) - the CLI, players, and diff --git a/quest/m1/qos/stats/per-track.md b/quest/m1/qos/stats/per-track.md new file mode 100644 index 00000000000..e166d3ca755 --- /dev/null +++ b/quest/m1/qos/stats/per-track.md @@ -0,0 +1,42 @@ +# [S] Plan per-track stats tracks + +## Goal + +Decide whether a media publisher's stats ride one track per catalog track +instead of one entry per broadcast, and rewrite the stats quests to match. +This quest writes quests, not code. + +## Plan + +Run `/quest-plan` against this line and #4145. Raised while planning TR 101 +290 monitoring (#4496): `hang::Stats { audio, video, transport }` sums every +rendition of a kind, so a simulcast ladder is indistinguishable, and a +per-rendition map would repeat the catalog's structure in a parallel type. + +The proposal: a catalog track gains `stats: "video/hd.stats"`, a separate track +served on request, and a container section does the same (`mpegts.stats` from +the catalog's `mpegts` section). Stats stay off the catalog track itself, +which would churn every viewer's catalog on each interval. + +For it: no parallel structure, a dashboard subscribes only to the renditions +it watches and an unrequested track costs nothing, each section owns its +counters with no flattened extension or `Merge` wrapper, and moq-mux +importers already count per track. + +Against it, and what the session must answer: + +1. Subscriber reports: a viewer cannot be referenced from the publisher's + catalog, so its received, decoded and stalled counters still need its own + `.stats` broadcast. Does that broadcast mirror per-track tracks, or keep the + moq-stats entry? +2. The relay is media-agnostic and keeps moq-stats' per-broadcast `Traffic`; + is splitting media publishers onto a second mechanism acceptable against + this line's "one consumer reads both halves" goal? +3. Aggregation: N broadcasts × M tracks subscriptions against one per node. +4. If moq-stats entries stay, key media counters per track name rather than + per kind. + +## Related + +- [Schema and library](/quest/m1/qos/stats/schema.md) - the shape this may replace +- [TS health stats](/quest/m2/ts-health-stats.md) - waits on this for its section's shape diff --git a/quest/m1/ts-psi-reassembly.md b/quest/m1/ts-psi-reassembly.md index a6a7b6cf67e..e9f4638d319 100644 --- a/quest/m1/ts-psi-reassembly.md +++ b/quest/m1/ts-psi-reassembly.md @@ -36,14 +36,23 @@ Settled decisions: [Per-program SI](/quest/m2/ts-program-si.md) needs the same dependency, and whichever change lands first adds it. A section with a bad CRC is dropped and the last good table stays in force, so the import continues; it no longer - aborts as the `mpeg2ts` reader does. -- Each dropped section is counted per PID in `Import::stats`, so a corrupt feed - is visible rather than silently held on a stale table. `Stats` is - `#[non_exhaustive]`, so the new field is additive; its docs (today "frame - sync the demuxed audio streams lost") and `is_empty` widen to cover it, and - `moq-cli`'s `log_stats` reports it. Name it so the - [TR 101 290 plan](/quest/m2/1838-tr-101-290-monitoring-requirements-broadcast-contribution.md) - adopts it as `CRC_error`. + aborts as the `mpeg2ts` reader does. The section is refused whole, never + half-applied, so fail-loud holds at section granularity. A malformed + adaptation field on the PAT or a PMT PID, which ends the import today too, + costs that section the same way. A feed that never delivers a good PAT and + PMT still publishes nothing. Line noise on a live feed then costs one + repetition (0.5 s at most), not the broadcast; today one flipped CRC byte on + `bbb.ts` makes `decode` return `CRC32 mismatch` and `moq import ts` exit. +- Each section dropped for a CRC mismatch is counted in `Import::stats` as a + cumulative `crc_error`, so a corrupt feed is visible rather than silently + held on a stale table. It is stream-wide on `Stats`, since the PAT and PMT + PIDs have no elementary-stream row, and named for the TR 101 290 check that + [TS import health](/quest/m2/ts-import-health.md) adopts. A section dropped + for another reason (a malformed adaptation field, a parse failure) is not a + `crc_error`; that quest counts it under `PAT_error` or `PMT_error`. `Stats` + is `#[non_exhaustive]`, so the new field is additive; its docs (today per + elementary stream) and `is_empty` widen to cover it, and `moq-cli`'s + `log_stats` reports it. - `ts::programs()` reads through the same PAT path, so a PAT spanning packets is found before any program publishes. - One quest, because the demux refactor alone changes nothing observable. @@ -51,8 +60,13 @@ Settled decisions: Keep every existing TS import test and fixture passing unchanged. Add tests for a PMT spanning two packets, a PAT behind a nonzero `pointer_field`, a multi-packet PAT with enough programs to need it (read by `ts::programs()` and -by `with_program`), and a PMT with a corrupt CRC that is dropped and counted -while the import keeps its previous PMT. +by `with_program`), and a PAT and a PMT with a corrupt CRC, each between good +repetitions, that is dropped and counted once while the import keeps its +previous layout and a later good PMT revision still applies. A positive +control: a feed whose only PAT is corrupt publishes nothing and counts it. + +Folded in from `ts-import-psi-crc` while landing the TR 101 290 plan (#4496): +that quest duplicated this one's bad-CRC drop and `CRC_error` count. ## Required diff --git a/quest/m2/1838-tr-101-290-monitoring-requirements-broadcast-contribution.md b/quest/m2/1838-tr-101-290-monitoring-requirements-broadcast-contribution.md deleted file mode 100644 index aa3957a1fa8..00000000000 --- a/quest/m2/1838-tr-101-290-monitoring-requirements-broadcast-contribution.md +++ /dev/null @@ -1,40 +0,0 @@ -# [S] Plan TR 101 290 monitoring - -## Goal - -The TR 101 290 stream-health requirements in -[#1838](https://github.com/moq-dev/moq/issues/1838) become scoped -implementation quests with the open questions answered. This quest writes -quests, not code. - -## Plan - -Run `/quest-plan` against the issue and the current tree. The issue is a -requirements list (ETSI P1/P2/P3 checks, per-check counters, a per-stream -health roll-up) and asks for agreement before any skeleton; its parent -proposal #1799 is closed. - -Settled by the issue, carry over: - -- TS-level checks run at the TS edges (`moq import ts`, `moq export ts`, - `moq-srt`), never in the media-agnostic relay. -- In today's media-aware lane our muxer regenerates PAT, PMT, PCR, and CC, - so egress checks validate our own output and SI checks are not applicable. - Full P1 to P3 conformance only means something for an opaque whole-mux - lane, which nothing plans yet. -- Results surface through the existing stats plumbing (`moq-stats`), not a new - transport. No remediation (FEC, 2022-7) and no GUI. - -Questions the planning session must answer: - -1. Where the checks live: a new crate, or beside the TS container in - `rs/moq-mux/src/container/ts`. -2. The MVP subset: P1 plus the PCR, CC, and PTS parts of P2 is the issue's - suggestion. -3. The configuration surface (thresholds, PIDs, sampling) and how the - counters map onto `moq-stats` tracks. -4. Whether the opaque whole-mux lane is wanted at all; without it, P3 is out. - -## Closes - -- [#1838](https://github.com/moq-dev/moq/issues/1838) - close this issue when the quest finishes diff --git a/quest/m2/README.md b/quest/m2/README.md index 44392617586..d1a1a141c76 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -76,7 +76,9 @@ upstream release waits in [m4](/quest/m4/README.md). - [AF_XDP UDP path](/quest/m2/af-xdp.md) - the kernel-bypass verdict on today's virtio hosts that gates DPDK - [GOP overhead](/quest/m2/gop-overhead.md) - price the I-frames a short GOP pays for, deciding whether a long GOP plus a keyframe request is worth designing - [Per-program SI](/quest/m2/ts-program-si.md) - a selected TS program's broadcast carries only its own service's SDT and EIT -- [#1838](/quest/m2/1838-tr-101-290-monitoring-requirements-broadcast-contribution.md) - plan TR 101 290 stream-health monitoring into implementation quests +- [TS import health](/quest/m2/ts-import-health.md) - `moq import ts` counts the TR 101 290 errors of the feed it receives, PCR and PTS graded on its own values +- [TS export liveness](/quest/m2/ts-export-liveness.md) - `moq export ts` reports each elementary stream's access units and quiet time, catching a per-track stall +- [TS health stats](/quest/m2/ts-health-stats.md) - the TS counters ride the stats plumbing beside the media counters - [Teleoperation](/quest/m2/teleop/README.md) - MoQ carries robot video down and control up on one session as a library capability - [SIP media stack](/quest/m2/sip-stack.md) - terminate one inbound SIP audio call leg and expose it as Opus frames - [Carrier voice](/quest/m2/carrier-voice/README.md) - determine whether MoQ should be the call fabric for programmable carrier voice diff --git a/quest/m2/ts-export-liveness.md b/quest/m2/ts-export-liveness.md new file mode 100644 index 00000000000..f8c2a92b03f --- /dev/null +++ b/quest/m2/ts-export-liveness.md @@ -0,0 +1,50 @@ +# [S] moq export ts reports each elementary stream's access units and how long it has been quiet + +## Goal + +`Export::stats` returns `ts::Stats` with the import's per-PID row (#4502) for +every elementary stream the exporter writes: `units`, the access-unit count, +and `quiet`, the time since the last, on the output's own PCR. An operator can tell that one track stalled +at the exporter while PSI and the other PIDs kept flowing. The other fields of +`ts::Stats` stay zero at egress. `moq export ts` logs a line when a row stops +advancing. + +## Plan + +Decided while planning [#1838](https://github.com/moq-dev/moq/issues/1838): + +- **Liveness only, no ETSI counters at egress.** The media-aware lane + regenerates PAT, PMT, PCR and CC, so an egress check grades our muxer, never + the contribution feed. Sync, TEI, CRC, CC, PAT and PMT on bytes the muxer + constructs fail only on a code defect, which the `test/ts` hard checks catch + in CI, and `PAT_error` timed on the output's own PCR never fires on a whole + stall because that clock freezes too. `PCR_accuracy_error` would be + permanently in alarm: the exporter's PCR fails ±500 ns on every file sample + and the downstream groomer's output passes on every one + ([T33](https://github.com/tdrapier-wbd/moq-mpegts-paper/blob/d4c7573f9519a1c9c4882fab2021fbf82616fdcc/lab/test-33-gate2-preparation.md)). + PCR accuracy and wire timing belong to the groomer's monitoring of its own + output, outside this tree. +- **The runtime failure worth catching is a per-track stall.** #3533 stalled + video and primary audio at the exporter while PSI and the other PIDs + continued and the relay kept transmitting; only a per-PID liveness detector + on a subscriber found it + ([T27](https://github.com/tdrapier-wbd/moq-mpegts-paper/blob/d4c7573f9519a1c9c4882fab2021fbf82616fdcc/lab/test-27-liveness-detector.md)). +- **Same type as ingest.** `Export::stats` returns `ts::Stats`, so a + dashboard reads one schema at both edges. Additive on main. +- **No window in-tree.** The raw exporter delivers by group, with 102 + simultaneous media-time gaps over 0.3 s in 39 s on every PID, and thresholds + learned there differ from the groomed wire's for the same content (T27). A + window means something only with its monitoring point named, so the + consumer picks it. + +Implementation: + +- `rs/moq-mux/src/container/ts/export.rs`: count an access unit per PID when + its PES is written, and the quiet time on the output PCR. Fix the stale "TR 101 + 290 flags a gap over 40 ms" comment near `PCR_INTERVAL` (V1.4.1's limit is + 100 ms), and the matching 40 ms defaults and the "inserts no null packets, + and paces PCR once per media frame" sentence in `test/ts/README.md`. +- `rs/moq-cli/src/subscribe.rs` logs a stopped row the way `publish.rs` does. +- Tests in `export_test.rs`: a healthy export advances every row; a track that + stops mid-run grows its quiet time while PSI and the other PIDs continue, the + #3533 shape. diff --git a/quest/m2/ts-health-stats.md b/quest/m2/ts-health-stats.md new file mode 100644 index 00000000000..34d2939d7ba --- /dev/null +++ b/quest/m2/ts-health-stats.md @@ -0,0 +1,39 @@ +# [S] TS health counters ride the stats plumbing + +## Goal + +`moq import ts --stats` and `moq export ts --stats` publish the `ts::Stats` +counters so a dashboard reads the TR 101 290 counters and per-PID liveness +beside the media and delivery counters, with no new transport. No health +roll-up in-tree: green, amber or red per priority is the consumer's reading of +counter rates and PID quiet times. + +## Plan + +Decided while planning [#1838](https://github.com/moq-dev/moq/issues/1838): + +- **Surface through the stats plumbing**, as the issue settled. The shape is + whatever [per-track stats](/quest/m1/qos/stats/per-track.md) decides: a + section on the client `.stats` entry, or an `mpegts.stats` track referenced + from the catalog's `mpegts` section. Either way the name follows the + catalog's `mpegts` key, the counters stay owned by moq-mux beside + `ts::Ext`, and `hang` stays TS-free. +- **Counters sum, gauges do not.** Every check is a cumulative counter, which + keeps `.z` deltas small and lets an aggregate sum; the PID's `quiet` is a gauge and + merges newest-wins. +- `ts::Stats` gains serde, every field defaulted and unknown fields ignored; + `StreamStats.track` becomes owned so the type deserializes. +- Docs: `doc/concept/stats.md` documents each counter's TR 101 290 check, its + monitoring point (ingest grades the feed, egress grades our muxer, and + neither is the groomed wire), the value domain of the PCR checks, and that + the per-PID rows cover `PID_error`; `doc/bin/cli.md` the flags. +- Test: publish a TS clip with `--stats`, read it back, and assert every ETSI + counter reads zero on a clean clip while every elementary stream's + access-unit count advances. + +## Required + +- [Per-track stats](/quest/m1/qos/stats/per-track.md) - where and in what shape the counters are published +- [Rust reporters](/quest/m1/qos/stats/rust.md) - `moq import --stats` and `moq export --stats` +- [TS import health](/quest/m2/ts-import-health.md) - the ingest counters +- [TS export liveness](/quest/m2/ts-export-liveness.md) - the egress rows diff --git a/quest/m2/ts-import-health.md b/quest/m2/ts-import-health.md new file mode 100644 index 00000000000..0b9d8323977 --- /dev/null +++ b/quest/m2/ts-import-health.md @@ -0,0 +1,116 @@ +# [M] moq import ts counts the TR 101 290 errors of the feed it receives + +## Goal + +An operator polling `moq import ts`, or `moq-srt` through the same importer, +reads cumulative counters for the TR 101 290 checks that grade a contribution +feed at ingest: `TS_sync_loss`, `Sync_byte_error`, `PAT_error`, +`Continuity_count_error`, `PMT_error`, `Transport_error`, `CRC_error` (on +PAT and PMT), `PCR_repetition_error`, `PCR_discontinuity_indicator_error` and `PTS_error`. +Counters only: ETSI's fixed limits, no configuration, no verdict, and nothing +changes in what is published. + +## Plan + +Decided while planning [#1838](https://github.com/moq-dev/moq/issues/1838): + +- **The checks live beside the container**, in a private module under + `rs/moq-mux/src/container/ts` that takes 188-byte packets and keeps the + counters. No new crate: nothing outside the tree consumes one. The importer + already classifies sync, continuity and TEI for routing; routing reads the + module's classification rather than keeping a second. A packet with + `transport_error_indicator` set counts `Transport_error` and nothing else: + TR 101 290 derives no further error from it, so it feeds no continuity, + PCR, PTS or CRC check. +- **Counters are named for the ETSI check** in snake case + (`continuity_count_error`, ...), cumulative for the importer's life like + `resyncs`: stream-wide on `ts::Stats`, per PID on the PID's row. No + last-event timestamp and no green/amber/red roll-up; the rate is what an + operator alarms on, and the stats sample dates the event. +- **Limits are ETSI TR 101 290 V1.4.1's and fixed**: 0.5 s for PAT and PMT, + loss of sync after two or more consecutive corrupted sync bytes and + acquisition after five consecutive correct ones (ISO 13818-1 G.1), 100 ms + for PCR repetition (the 40 ms limit left TS 101 154 in 2005), 0 to 100 ms + for PCR discontinuity, 700 ms for PTS. The PMT names the PIDs, and every + packet is checked, so there is no sampling to configure. +- **No `PID_error` field.** ETSI defines it as a PMT-listed PID with no + packets for a user-specified period. The per-PID rows #3489 landed in + #4502 (`units`, access units delivered, and `quiet`, the time since the + last) cover it and are stricter: a dead video path behind a + live mux still sends adaptation-field-only PCR packets on its PID, which a + packet count reads as live + ([T27](https://github.com/tdrapier-wbd/moq-mpegts-paper/blob/d4c7573f9519a1c9c4882fab2021fbf82616fdcc/lab/test-27-liveness-detector.md)). + The rows keep #3489's names so no field claims the ETSI name for a different + measurement, and the consumer picks the window, as #3489 decided. The docs + map `PID_error` onto them. +- **`CRC_error` covers PAT and PMT only.** TR 101 290 names CAT, PAT, PMT, + NIT, EIT, BAT, SDT and TOT, and its table 5.1b cuts that to PAT and PMT for + systems with reduced SI, which a contribution feed is. The importer parses + only PAT and PMT, and [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) + already drops a bad-CRC section and counts it as `crc_error`; this quest + adopts that field. SI captured verbatim (NIT, SDT, EIT, BAT, TOT) is not + CRC-checked, and CAT is out with the scrambled services below. +- **Intervals run on the program clock** #4502 reads, accumulated step by + step with a jump bound: one corrupt PCR taken as an absolute distance + fabricated a 23,861 s outage on every PID in the campaign's detector (T27). + A clock that stops freezes every interval; the consumer sees that case as + every count standing still across two samples. +- **PCR and PTS are graded on values, and documented as such.** Repetition and + discontinuity compare consecutive PCR values on the PCR PID, not arrival + times: that grades the encoder's insertion, which is what ingest can speak + for, while the network in front of the importer (SRT, UDP, a pipe) re-times + arrival. The docs name the domain beside the counters, because a + value-domain pass is not a wire pass + ([evidence §3.2](https://github.com/tdrapier-wbd/moq-mpegts-paper/blob/d4c7573f9519a1c9c4882fab2021fbf82616fdcc/docs/evidence.md)). + - A signalled jump is legal: the interval across a packet carrying + `discontinuity_indicator` on the PCR PID is dropped from both checks (ISO + 13818-1 2.4.3.4); the importer already reads it in `timebase_break`. The + 33-bit wrap is modular, not a jump. + - `PCR_discontinuity_indicator_error` is a consecutive difference outside 0 + to 100 ms without the flag, backwards included. On values alone a run of + missing PCRs and an unsignalled jump are the same difference, so one + forward difference over 100 ms counts under both checks; the docs say so + rather than guess which it was. + - `PTS_error` is per elementary stream on the transport clock. Verbatim + streams with no cadence (SCTE-35, DVB subtitles) are left ungraded rather + than watched against an invented number. +- **`PCR_accuracy_error` is out.** ±500 ns is graded either against a + constant-rate model of byte position, which holds only on a CBR feed, or + against arrival on the wire, which is an analyser measurement + ([T33](https://github.com/tdrapier-wbd/moq-mpegts-paper/blob/d4c7573f9519a1c9c4882fab2021fbf82616fdcc/lab/test-33-gate2-preparation.md)). +- **No opaque whole-mux lane**: + [#1861](https://github.com/moq-dev/moq/issues/1861) is closed not planned + and verbatim TS is a non-goal in + [MSFTS convergence](/quest/m4/msfts-convergence.md). P3 is out of this set; + `CAT_error` too, since the lane carries no scrambled service. A scrambled + PAT or PMT still counts under its own check. + +Implementation: + +- `rs/moq-mux/src/container/ts/import.rs`: `Stats` and `StreamStats` are + `#[non_exhaustive]`, so the fields are additive. A continuity break + declared by `discontinuity_indicator`, the one duplicate ISO 13818-1 + 2.4.3.3 permits, and a payload-less packet repeating its counter are not + errors. +- `rs/moq-cli/src/publish.rs` `log_stats` logs a line when a counter moves, + as it does for resyncs. +- Measure `decode` throughput on `test_data/kyrion_mpeg2av_ac3.ts` before and + after; the checks read header bytes the loop already reads, so a measurable + cost is a finding. +- Tests, one stimulus per check with a control each way: a clean capture + reads zero, the faulted one reads exactly the count injected. Feed at least + a pair of packets, since a single packet never routes. Timing arms: a + 150 ms PCR gap counts one repetition and one discontinuity error, an 80 ms + gap counts nothing, a signalled 500 ms jump counts nothing, a placed wrap + counts nothing, and a 1 s PTS gap on one PID counts one there and nowhere + else. A TEI packet that also jumps its continuity counter counts one + `Transport_error` and no `Continuity_count_error`. + +## Required + +- [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) - the bad-CRC PAT or PMT the importer survives and counts as `crc_error` + +## Related + +- [SRT import stats](/quest/m1/srt-import-stats.md) - the gateway forwards the same `stats()` +- [TS health stats](/quest/m2/ts-health-stats.md) - where these counters are published From 24f622e49539bbf4517771868e7b31b7eef0ac3c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 11:25:30 -0700 Subject: [PATCH 027/128] fix(video): list V4L2 cameras once with PipeWire (#4488) Co-authored-by: GPT-6 Co-authored-by: Claude Opus 5.5 --- doc/lib/rs/moq-video.md | 6 ++- quest/m1/README.md | 1 - quest/m1/pipewire-dup-cameras.md | 24 --------- rs/moq-video/src/capture/mod.rs | 15 +++--- rs/moq-video/src/capture/pipewire/camera.rs | 58 ++++++++++++++++++-- rs/moq-video/src/capture/v4l2.rs | 60 ++++++++++++++++++++- 6 files changed, 126 insertions(+), 38 deletions(-) delete mode 100644 quest/m1/pipewire-dup-cameras.md diff --git a/doc/lib/rs/moq-video.md b/doc/lib/rs/moq-video.md index 11249d2e36f..05571de7446 100644 --- a/doc/lib/rs/moq-video.md +++ b/doc/lib/rs/moq-video.md @@ -40,7 +40,11 @@ are returned rather than treated as an empty list. Other platforms return `Error::Unsupported`. With `pipewire` enabled, `capture::cameras` also lists PipeWire camera nodes as -`pipewire:` after the V4L2 devices, and `pipewire` alone opens the +`pipewire:` after the V4L2 devices. V4L2 lists only devices offering +YUYV or MJPEG. A PipeWire V4L2 node is hidden only when its device path was +already listed by V4L2, so identical webcams stay distinct, and PipeWire-only +cameras and NV12- or RGB-only V4L2 devices remain visible through PipeWire. Explicit `pipewire:` +selectors still open hidden nodes, and `pipewire` alone opens the camera with the highest session priority, the session manager's default. That reaches cameras V4L2 cannot: a Raspberry Pi CSI camera behind libcamera, and any camera from inside a Flatpak or Snap sandbox, where the default camera comes diff --git a/quest/m1/README.md b/quest/m1/README.md index 4c9068da8fe..20ab5f5f516 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -56,7 +56,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [TS import shared shift](/quest/m1/ts-import-shared-shift.md) - unflagged loop wraps move audio and video by one shift, so A/V sync holds across wraps - [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) - `import ts` reads a PAT or PMT that spans packets or follows a nonzero pointer_field instead of aborting, and one corrupted section costs a repetition and a counted `CRC_error`, not the import - [Same-hop importers](/quest/m1/hop-aligned-import.md) - importers sharing a `--hop` and fed one stream publish identical groups and timestamps, so failover survives -- [PipeWire duplicate cameras](/quest/m1/pipewire-dup-cameras.md) - a webcam lists once with PipeWire enabled - [Catalog wall clock](/quest/m1/catalog-wall-clock.md) - `Clock::wall_clock` keeps the catalog's full precision instead of truncating to milliseconds - [Capture control](/quest/m1/capture-control.md) - on dev, `encode::Capture` replaces `CaptureOptions` without a `clock` field (it reads the catalog's), an unsupported `cut()` errors, and dropping the last `Control` cancels in-flight opens - [Video surface](/quest/m1/video-surface.md) - on dev, moq-ffi's `native` becomes `surface`, refused on platforms with no surface diff --git a/quest/m1/pipewire-dup-cameras.md b/quest/m1/pipewire-dup-cameras.md deleted file mode 100644 index c9ad2a46fc6..00000000000 --- a/quest/m1/pipewire-dup-cameras.md +++ /dev/null @@ -1,24 +0,0 @@ -# [XS] A webcam lists once with PipeWire enabled - -## Goal - -`moq_video::capture::cameras()` on Linux with the `pipewire` feature lists a -webcam once. Today a UVC webcam appears as its V4L2 device and again as the -PipeWire node that wraps it ([#4022](https://github.com/moq-dev/moq/pull/4022)). - -## Plan - -Decided: hide PipeWire camera nodes with `device.api = v4l2` whose device the -V4L2 backend already listed, keeping the shorter list over exposing the -backend choice. Nodes V4L2 cannot see stay: libcamera cameras (a Raspberry Pi -CSI camera) and everything inside a sandbox, where V4L2 lists nothing. - -Guidance: - -- Match on the node's V4L2 device path property (`api.v4l2.path`), not the - description, so two identical webcams stay distinct. -- Only the listing changes. `pipewire:` still opens a hidden node, and - the `pipewire` default keeps resolving by priority. -- Update the `cameras()` doc that currently says a webcam appears once per - backend, and cover the filter with a unit test over scanned node - properties. diff --git a/rs/moq-video/src/capture/mod.rs b/rs/moq-video/src/capture/mod.rs index f39ff453896..3f08347d53d 100644 --- a/rs/moq-video/src/capture/mod.rs +++ b/rs/moq-video/src/capture/mod.rs @@ -496,11 +496,11 @@ pub async fn open(config: &Config) -> Result { /// List the available cameras and the identifiers [`Source::Camera`] accepts. /// -/// On Linux with the `pipewire` feature, V4L2 devices come first and PipeWire -/// camera nodes follow, so a webcam that PipeWire also serves appears once per -/// backend. A session without PipeWire lists V4L2 alone. Inside a sandbox the -/// PipeWire nodes come through the camera portal, which may ask the user for -/// camera access. +/// On Linux, V4L2 lists only devices offering YUYV or MJPEG. With the `pipewire` +/// feature, PipeWire camera nodes follow, excluding V4L2 paths already listed. +/// PipeWire-only cameras remain visible. A session without PipeWire lists V4L2 +/// alone. Inside a sandbox the PipeWire nodes come through the camera portal, +/// which may ask the user for camera access. pub async fn cameras() -> Result, Error> { #[cfg(target_os = "macos")] { @@ -510,7 +510,10 @@ pub async fn cameras() -> Result, Error> { { let cameras = blocking(v4l2::cameras).await?; #[cfg(feature = "pipewire")] - let cameras = [cameras, pipewire::camera::cameras().await?].concat(); + let cameras = { + let pipewire = pipewire::camera::cameras(&cameras).await?; + [cameras, pipewire].concat() + }; Ok(cameras) } #[cfg(target_os = "windows")] diff --git a/rs/moq-video/src/capture/pipewire/camera.rs b/rs/moq-video/src/capture/pipewire/camera.rs index f19b0116e74..7af8db0ad0a 100644 --- a/rs/moq-video/src/capture/pipewire/camera.rs +++ b/rs/moq-video/src/capture/pipewire/camera.rs @@ -38,7 +38,7 @@ use crate::{Error, Rate, Size}; const QUERY_TIMEOUT: Duration = Duration::from_secs(5); /// List the PipeWire cameras as [`Camera`]s with `pipewire:` ids. -pub(in crate::capture) async fn cameras() -> Result, Error> { +pub(in crate::capture) async fn cameras(v4l2: &[Camera]) -> Result, Error> { let sandboxed = ashpd::is_sandboxed(); let remote = if sandboxed { match portal().await? { @@ -68,13 +68,22 @@ pub(in crate::capture) async fn cameras() -> Result, Error> { }) .await?; - Ok(nodes + Ok(camera_list(nodes, v4l2)) +} + +fn camera_list(nodes: Vec, v4l2: &[Camera]) -> Vec { + nodes .into_iter() + .filter(|node| { + !v4l2 + .iter() + .any(|camera| node.v4l2_path.as_deref() == Some(camera.id.as_str())) + }) .map(|node| Camera { id: format!("{PIPEWIRE}:{}", node.name), name: node.description, }) - .collect()) + .collect() } /// List the modes the camera named `node` (or the default camera) reports, for @@ -196,6 +205,8 @@ pub(super) struct Node { description: String, /// `priority.session`, which the session manager ranks default nodes by. priority: i32, + /// The underlying V4L2 path, only when the node uses the V4L2 backend. + v4l2_path: Option, } impl Node { @@ -219,6 +230,11 @@ impl Node { name: name.to_string(), description: description.to_string(), priority, + v4l2_path: (prop("device.api") == Some("v4l2")) + .then(|| prop("api.v4l2.path")) + .flatten() + .filter(|path| !path.is_empty()) + .map(str::to_string), }) } } @@ -733,6 +749,37 @@ mod tests { ("priority.session", "1000"), ]; + #[test] + fn listing_hides_only_v4l2_paths_already_enumerated() { + let mut props = WEBCAM.to_vec(); + props.extend([("device.api", "v4l2"), ("api.v4l2.path", "/dev/video0")]); + let webcam = node(&props).unwrap(); + let v4l2 = [Camera { + id: "/dev/video0".into(), + name: webcam.description.clone(), + }]; + assert!(camera_list(vec![webcam.clone()], &v4l2).is_empty()); + assert_eq!(camera_list(vec![webcam.clone()], &[]).len(), 1); + // An identical label on another device must not hide it. + props.pop(); + props.push(("api.v4l2.path", "/dev/video2")); + assert_eq!(camera_list(vec![node(&props).unwrap()], &v4l2).len(), 1); + // Missing paths and non-V4L2 backends are not proof of duplication. + props.pop(); + assert_eq!(camera_list(vec![node(&props).unwrap()], &v4l2).len(), 1); + props.pop(); + props.extend([("device.api", "libcamera"), ("api.v4l2.path", "/dev/video0")]); + assert_eq!(camera_list(vec![node(&props).unwrap()], &v4l2).len(), 1); + props.remove(props.len() - 2); + assert_eq!(camera_list(vec![node(&props).unwrap()], &v4l2).len(), 1); + // Listing never removes nodes from explicit or priority-based resolution. + assert_eq!( + resolve(std::slice::from_ref(&webcam), Some(&webcam.name)).unwrap(), + &webcam + ); + assert_eq!(resolve(std::slice::from_ref(&webcam), None).unwrap(), &webcam); + } + #[test] fn camera_nodes_are_video_sources_with_the_camera_role() { assert_eq!( @@ -742,6 +789,7 @@ mod tests { name: "v4l2_input.pci-0000_00_14.0-usb-0_4_1.0".to_string(), description: "Integrated Camera (V4L2)".to_string(), priority: 1000, + v4l2_path: None, }) ); @@ -1113,7 +1161,7 @@ mod tests { eprintln!("skipping: listing inside a sandbox would ask the camera portal"); return; } - let cameras = cameras().await.expect("listing PipeWire cameras"); + let cameras = cameras(&[]).await.expect("listing PipeWire cameras"); for camera in &cameras { assert!(camera.id.starts_with("pipewire:"), "{}", camera.id); assert!(!camera.name.is_empty()); @@ -1153,7 +1201,7 @@ mod tests { eprintln!("skipping: capturing inside a sandbox would ask the camera portal"); return; } - let cameras = cameras().await.expect("listing PipeWire cameras"); + let cameras = cameras(&[]).await.expect("listing PipeWire cameras"); if cameras.is_empty() { eprintln!("skipping: no PipeWire camera"); return; diff --git a/rs/moq-video/src/capture/v4l2.rs b/rs/moq-video/src/capture/v4l2.rs index c1e8099db52..7f54fa996c6 100644 --- a/rs/moq-video/src/capture/v4l2.rs +++ b/rs/moq-video/src/capture/v4l2.rs @@ -23,7 +23,7 @@ use super::{Config, Mode, Rate, Stream}; use crate::frame::{I420, Surface}; use crate::{Error, Size}; -/// List V4L2 capture nodes using paths that [`open_device`] accepts. +/// List V4L2 capture nodes that [`open`] can negotiate, by the paths [`open_device`] accepts. pub(super) fn cameras() -> Result, Error> { let mut nodes = moq_v4l::context::enum_devices(); nodes.sort_by_key(moq_v4l::context::Node::index); @@ -51,6 +51,19 @@ pub(super) fn cameras() -> Result, Error> { { return None; } + // A device with no YUYV or MJPEG would list an id `open` refuses, and + // hide the PipeWire entry for the same path that could still open it. + match convertible(&device) { + Ok(true) => {} + Ok(false) => { + tracing::debug!(device = %path, "V4L2 node offers no YUYV or MJPEG"); + return None; + } + Err(err) => { + tracing::debug!(device = %path, error = %err, "could not list V4L2 formats"); + return None; + } + } let name = node.name().filter(|name| !name.is_empty()).unwrap_or(capabilities.card); Some(super::Camera { id: path, name }) @@ -59,6 +72,38 @@ pub(super) fn cameras() -> Result, Error> { Ok(cameras) } +/// Whether the device offers a capture format [`Source`] converts. +fn convertible(device: &Device) -> Result { + convertible_with(|index| { + // All fields are integers or byte arrays; reserved fields must be zero. + let mut entry: moq_v4l::sys::v4l2_fmtdesc = unsafe { std::mem::zeroed() }; + entry.index = index; + entry.type_ = BufType::VideoCapture as u32; + // The request matches the initialized argument's type and size. + let result = unsafe { + moq_v4l::v4l2::ioctl( + device.handle().fd(), + moq_v4l::v4l2::vidioc::VIDIOC_ENUM_FMT, + &mut entry as *mut _ as *mut std::ffi::c_void, + ) + }; + Ok(enumeration(result)?.map(|()| FourCC::from(entry.pixelformat))) + }) +} + +// Read one entry at a time, like `frame_sizes`: moq-v4l's `enum_formats` treats +// every error as end-of-list. +fn convertible_with(mut format: impl FnMut(u32) -> Result, Error>) -> Result { + for index in 0..=u32::MAX { + match format(index)? { + Some(fourcc) if Source::from_fourcc(fourcc).is_some() => return Ok(true), + Some(_) => {} + None => return Ok(false), + } + } + Err(Error::Codec(anyhow::anyhow!("V4L2 format index overflow"))) +} + /// List the modes a V4L2 camera reports, for the formats this backend converts. /// /// `VIDIOC_ENUM_FRAMESIZES` and `VIDIOC_ENUM_FRAMEINTERVALS` describe a device @@ -721,6 +766,19 @@ mod tests { assert!(closest(replies, request(1280, 720)).is_none()); } + #[test] + fn only_devices_offering_a_converted_format_are_cameras() { + let formats = |list: &'static [&'static [u8; 4]]| { + move |index: u32| Ok(list.get(index as usize).map(|fourcc| FourCC::new(fourcc))) + }; + assert!(!convertible_with(formats(&[])).unwrap()); + assert!(!convertible_with(formats(&[b"NV12", b"RGB3"])).unwrap()); + assert!(convertible_with(formats(&[b"NV12", b"MJPG"])).unwrap()); + assert!(convertible_with(formats(&[b"YUYV"])).unwrap()); + let failed = convertible_with(|_| Err(Error::SourceUnavailable("ENUM_FMT".into()))); + assert!(failed.is_err()); + } + /// Every format we advertise round-trips through its fourcc, which is what /// lets `negotiate` recognize the driver's substitution. #[test] From 1e08ef57699e3290ff5d15fb55e61705aa26fe35 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 11:59:45 -0700 Subject: [PATCH 028/128] docs(hang): document the broadcast wall clock (#4461) Co-authored-by: Claude Sonnet 5.5 --- doc/lib/js/hang.md | 42 +++++++++++++++++++ ...l-clock-latency-target-for-synchronized.md | 32 -------------- quest/m1/README.md | 1 - quest/m2/teleop/correlation.md | 2 +- 4 files changed, 43 insertions(+), 34 deletions(-) delete mode 100644 quest/m1/2278-watch-absolute-wall-clock-latency-target-for-synchronized.md diff --git a/doc/lib/js/hang.md b/doc/lib/js/hang.md index 3487eeb136f..c8b03da1da6 100644 --- a/doc/lib/js/hang.md +++ b/doc/lib/js/hang.md @@ -30,3 +30,45 @@ handle's `path`. Run the same checks on a catalog from another source with Most apps never import it directly; the elements and `Broadcast` classes in the watch and publish packages do. Reach for it when hand-rolling a catalog or building a custom player. + +## Wall clock + +A catalog root may carry a `clock`: `{ wall, timescale }`, the wall-clock time +of PTS zero in `timescale` units (microseconds by default) since 2020-01-01. +`Catalog.wallClockTime(clock, pts, ptsTimescale)` maps a frame's PTS to a +`Date`. A `Container.Legacy` frame timestamp is microseconds, so pass `1_000_000`. + +```ts +for await (const root of Catalog.watch(broadcast)) { + if (!root.clock) continue; // the publisher exposes no clock + // `frame` comes from your own `Container.Legacy` consumer. + const captured = Catalog.wallClockTime(root.clock, frame.timestamp, 1_000_000); +} +``` + +- The mapping is fixed for the life of the broadcast. A discontinuity or a + system-clock adjustment on the publisher does not change it. +- It is independent of `archive`. A live-only broadcast carries a `clock` with + no segment index, so a DVR view can label its timeline from it either way. +- A `Date` holds whole milliseconds, so anything finer in the clock is + truncated. +- A result past the `Date` range comes back as an invalid `Date`, not an + exception, so check it before use. + +Two machines' wall times are only comparable when your application already +knows their clocks are synchronized. The catalog says where PTS zero was on the +publisher's clock, never whether the viewer's clock agrees with it. If you do +know, set `delay` to `target - (arrived - captured)`, where `arrived` is the +viewer's `Date.now()` for the frame that arrived earliest relative to its +timestamp, since `` anchors playback on that frame. That holds only +with the default zero `buffer`; a lookahead moves the anchor. `` adds +the largest active rendition's buffer on top, so a frame renders at about +`captured + target` plus that buffer: the rendition's catalog `delay` plus its +`jitter` (one video frame or one codec frame when unset), and for audio the +worklet quantum too. Viewers only line up when that buffer matches, and a +negative result means the target is already missed. + +The library never does this for you. Playback stays arrival-based: it does not +read the `clock`, estimate the viewer's clock from the session RTT, or +exchange time over a track, and a timestamp stays relative to the broadcast +rather than a reading of any wall clock. diff --git a/quest/m1/2278-watch-absolute-wall-clock-latency-target-for-synchronized.md b/quest/m1/2278-watch-absolute-wall-clock-latency-target-for-synchronized.md deleted file mode 100644 index b85a2da1693..00000000000 --- a/quest/m1/2278-watch-absolute-wall-clock-latency-target-for-synchronized.md +++ /dev/null @@ -1,32 +0,0 @@ -# [XS] hang: document the broadcast wall clock - -## Goal - -A browser application can find how to map presentation time to wall time -from `doc/lib/js/hang.md`, so an application that knows its viewers share a -clock can compute the delay that renders one frame at one instant everywhere, -and a DVR view can label its timeline. - -The library itself never synchronizes playback on wall time. That is the -decision behind [#2278](https://github.com/moq-dev/moq/issues/2278): frame -timestamps are relative by design, `Timestamp::now()` is a one-way bridge with -a per-process jitter to deter wall-clock readings, and two machines' clocks are -only comparable when the application already knows they are synced. No -absolute `delay` mode, no client clock estimation from the session RTT, and no -sync exchange over a track. - -## Plan - -The API already exists: the catalog root's optional `clock` (`ClockSchema`, -`Clock`) and `wallClockTime(clock, pts, ptsTimescale)` in -`js/hang/src/catalog/clock.ts`, exported from `@moq/hang/catalog`. Only the -docs are missing. Add a short section to `doc/lib/js/hang.md`: read `clock` -from a catalog root, convert a frame's PTS with `wallClockTime`, note that a -live-only broadcast carries it without an `archive` entry, that the mapping is -fixed for the broadcast's life, and that comparing wall times across machines -requires the application to know their clocks are synchronized. Keep -`js/watch` arrival-based Sync unchanged. - -## Closes - -- [#2278](https://github.com/moq-dev/moq/issues/2278) - close this issue when the quest finishes diff --git a/quest/m1/README.md b/quest/m1/README.md index 20ab5f5f516..21e6e2e4470 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -140,7 +140,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [#933](/quest/m1/933-video-rotation-metadata-not-propagated-from-mobile-camera.md) - the catalog rotation follows the live camera's orientation - [#2848](/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - the Opus producer follows its bandwidth grant through the settled `moq_mux::rate::Control` - [Ladder](/quest/m1/ladder/README.md) - a transcode ladder adapts to the uplink it publishes over, instead of encoding every live rung at its ceiling -- [#2278](/quest/m1/2278-watch-absolute-wall-clock-latency-target-for-synchronized.md) - hang: document reading the catalog-root clock and converting PTS to wall time, without synchronizing library playback to wall time - [Time stretch](/quest/m1/watch-audio-time-stretch.md) - js/watch: the audio ring converges by time-stretching instead of skipping or going silent - [Native audio quality](/quest/m1/audio-quality-native.md) - the browser lane's profiles, budgets, and metric schema run against `moq play` on a dummy device - [fMP4 emsg](/quest/m1/emsg.md) - event messages survive fMP4 import, and the timed-metadata contract ID3, SCTE-35, and FLV script tags share is settled with them diff --git a/quest/m2/teleop/correlation.md b/quest/m2/teleop/correlation.md index bb8e60ac914..1da8f218c59 100644 --- a/quest/m2/teleop/correlation.md +++ b/quest/m2/teleop/correlation.md @@ -20,7 +20,7 @@ anchors or mutable `set_wall` epochs. Report whether a mapping is present, but never infer that hosts are synchronized from its presence. State the clock assumption beside the API, since a join across unsynchronized hosts can look valid while being wrong. The library provides no clock-sync mechanism; see -[#2278](/quest/m1/2278-watch-absolute-wall-clock-latency-target-for-synchronized.md). +[#2278](https://github.com/moq-dev/moq/issues/2278). This is also the answer to Kyber's headline claim of continuous drift computation onto one unified timeline. Worth answering on the merits: From fbc94f1ead6596cb7ce5e8048dbdffbf47b278f2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 12:11:19 -0700 Subject: [PATCH 029/128] chore(quest): replan strict-CSP worklets as opt-in hosted assets (#4516) Co-authored-by: Claude Opus 5.5 --- quest/m1/README.md | 2 +- quest/m1/csp-assets.md | 81 ++++++++++++++++++++++++++++++++++ quest/m1/plan-watch-worker.md | 3 +- quest/m1/watch-worklet-file.md | 29 ------------ 4 files changed, 84 insertions(+), 31 deletions(-) create mode 100644 quest/m1/csp-assets.md delete mode 100644 quest/m1/watch-worklet-file.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 21e6e2e4470..d663cd37176 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -43,7 +43,7 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Session death parity](/quest/m1/session-death.md) - a local close ends tracks cleanly in both languages, and JS group readers see the session's error on session death - [Watch video guards](/quest/m1/watch-video-guards.md) - promoting a video track holds the last picture, and an older group never reaches the codec between live deltas - [Watch decoder recovery](/quest/m1/watch-decoder-recovery.md) - one malformed packet rebuilds the audio or video decoder instead of ending playback -- [Watch audio under CSP](/quest/m1/watch-worklet-file.md) - production builds ship the audio worklet as a file, so `script-src 'self'` pages play audio +- [Watch and publish under CSP](/quest/m1/csp-assets.md) - blob workers stay the default; strict-CSP apps host the files and set a base URL - [More tests under load](/quest/m1/test-flakes-2.md) - the second round of load-only failures, fixed at the cause - [Interop audio cold start](/quest/m1/interop-audio-cold-start.md) - the interop audio tone check stops failing on cold start, fixed at its cause - [Auth outage clock](/quest/m1/auth-outage-clock.md) - the relay and moq-auth outage tests run on a paused clock again and assert both bounds of `expires` diff --git a/quest/m1/csp-assets.md b/quest/m1/csp-assets.md new file mode 100644 index 00000000000..ad9a46bcbc3 --- /dev/null +++ b/quest/m1/csp-assets.md @@ -0,0 +1,81 @@ +# [M] Watch and publish under a strict CSP + +## Goal + +By default, watch and publish keep working on every bundler with no hosted +files: the worklets and the capture worker load from `blob:` URLs, as today. +An app whose CSP refuses `blob:` (`script-src 'self'`, `worker-src 'self'`) +opts in by copying the worker and worklet files out of `node_modules`, +hosting them, and giving each package their base URL. It then plays and +publishes audio with no CSP violations. + +Covers the watch render worklet, the publish capture worklet, and the +publish capture worker (`?worker&inline`). Today a strict CSP refuses all +three, and the only symptom is a console "spawn error". + +## Plan + +Why not `new URL(..., import.meta.url)`: [#4485](https://github.com/moq-dev/moq/pull/4485) +emitted the worklets as assets behind that pattern. Built consumers probed +in Chromium on 2026-09-29 gave these results. Vite build, Vite dev +(prebundled), webpack 5, Rspack, Parcel, and import maps copied the file. +esbuild ESM, Rollup, and Bun left it behind (a 404, so no audio). esbuild +IIFE threw `Invalid URL` at module load, which broke the whole player. A +library can't require every consumer to host its files. And a strict CSP +can't avoid a same-origin file, because `addModule` and `new Worker` need a +URL, and only `blob:`/`data:` URLs come without hosting. + +Decided in planning: + +- One set of entry points, with the hosted mode set at runtime. No second + entry tree and no export condition. +- The blob code sits behind a dynamic `import()` that only runs when no base + is set. So the default loads it lazily, and hosted mode on a code-splitting + bundler never downloads it. Single-file builds (esbuild without splitting, + Bun, IIFE) inline it, which is about 12 KB minified of dead weight in hosted + mode only. Accepted over doubling the exports. +- Hosted-mode files load from `new URL(, base)`, with the base + first resolved against `document.baseURI`, so a root-relative `/moq/` + works (`new URL(name, "/moq/")` alone throws). Never `import.meta.url`: + the default path must not reference an asset that some bundlers drop. +- API: one global base URL per package, set once before playback (e.g. + `Watch.assets("/moq/")` and `Publish.assets("/moq/")`; the exact name is for + review). Assets are app-wide, so nothing threads through `Player`, the + decoder, or the elements. room and moq-boy set nothing of their own; their + docs say to set both. +- Files: stable, unhashed names under each package's `dist/assets/` (e.g. + `@moq/watch/assets/render-worklet.js`), also listed in `package.json` + `exports` so copy plugins and `import.meta.resolve` can find them. The + worklet messages can change between versions, so the docs say to recopy on + every upgrade. +- `vite serve` in this repo keeps blob URLs. +- Docs: an inline section in `doc/lib/js/watch.md` and + `doc/lib/js/publish.md` (not a shared page). Each covers the base URL, the + files to copy, and the CSP directives. The capture worker needs + `worker-src`, the worklets `script-src`. +- Tests: + - A `js/common` unit test in `just js test`, with no browser. It asserts + the built default dist has no `new URL(..., import.meta.url)` asset + reference and that the blob code is only reached through `import()`. + - A manual bundler-matrix script, not wired into CI or nightly. This is the + maintainer's call, an exception to the repo's CI rule. It builds a + consumer with Vite, webpack, esbuild IIFE, and Bun, then loads each in + Chromium, in default mode (no CSP) and hosted mode (strict CSP). The page + loads all three assets directly (both worklets through `addModule`, and + the capture worker through a spawn and a message round trip). Chromium's + publish path uses the main-thread `MediaStreamTrackProcessor` and never + spawns the worker, and the worker path silently falls back when the + spawn fails. Report the results in the PR. + +Reuse from #4485 where it fits: the `resolveFileUrl`/`emitFile` plumbing in +`js/common/vite-plugin-worklet.ts` and its Playwright CSP page, minus the +interop CI step. + +## Closes + +- [#4323](https://github.com/moq-dev/moq/issues/4323) - close this issue when the quest finishes + +## Related + +- [JS bundle trims](/quest/m1/js-bundle-trims.md) - minifies worklets through the same plugin +- [Plan: watch worker](/quest/m1/plan-watch-worker.md) - a new watch worker joins the same assets base diff --git a/quest/m1/plan-watch-worker.md b/quest/m1/plan-watch-worker.md index f2bd4e21535..f632211053c 100644 --- a/quest/m1/plan-watch-worker.md +++ b/quest/m1/plan-watch-worker.md @@ -60,7 +60,8 @@ browser harness pieces instead of starting another. The rewritten implementation quest names the chosen model, the public handle shape of `Player` and ``, what happens to the composable classes, the worker bundling (the publish capture worker's `?worker&inline` is the -precedent; note the CSP `worker-src blob:` consequence), and the follow-up +precedent; like it, the worker ships a lazy blob plus a hostable file under +the package's assets base, per [strict CSP](/quest/m1/csp-assets.md)), and the follow-up quest for moving publish onto the same worker if the handle model wins. ## Related diff --git a/quest/m1/watch-worklet-file.md b/quest/m1/watch-worklet-file.md deleted file mode 100644 index b6a778364a6..00000000000 --- a/quest/m1/watch-worklet-file.md +++ /dev/null @@ -1,29 +0,0 @@ -# [S] Watch audio under a strict CSP - -## Goal - -A page with CSP `script-src 'self'` plays watch audio. Today -`js/common/vite-plugin-worklet.ts` always exports the render worklet as a -`blob:` URL, so `addModule` is refused and audio never starts, with only a -console "spawn error". - -## Plan - -Decided: in `vite build`, emit the worklet as its own file and export -`new URL(".js", import.meta.url)`; keep the blob URL only in -`vite serve`. Vite, webpack 5, and esbuild (with a plugin) resolve that -pattern inside a dependency. This applies to the publish capture worklet too -and deletes the runtime blob code. Document the consumer-bundler requirement. -The publish capture worker (`?worker&inline`) is out of scope. - -Verify in a browser under `script-src 'self'` (Chromium and Firefox) and -from a Vite consumer app. - -## Closes - -- [#4323](https://github.com/moq-dev/moq/issues/4323) - close this issue when the quest finishes - -## Related - -- [JS bundle trims](/quest/m1/js-bundle-trims.md) - minifies worklets through the same plugin -- [Plan: watch worker](/quest/m1/plan-watch-worker.md) - notes the capture worker's `worker-src blob:` need From 12f23811a08e9cab086480678e2904c2fcafd5c1 Mon Sep 17 00:00:00 2001 From: t0ms Date: Tue, 29 Sep 2026 20:13:50 +0100 Subject: [PATCH 030/128] test(ts): round-trip an open-GOP H.264 fixture (#4501) Co-authored-by: Claude Opus 5.5 Co-authored-by: Luke Curley --- .github/workflows/interop.yml | 8 + ...-264-tune-in-end-to-end-leading-picture.md | 43 --- quest/m1/README.md | 1 - quest/m1/open-gop-leading-pictures.md | 20 +- quest/m2/intra-refresh/README.md | 1 - test/justfile | 3 +- test/ts/README.md | 44 ++- test/ts/open-gop.py | 320 ++++++++++++++++++ test/ts/run.sh | 33 +- 9 files changed, 417 insertions(+), 56 deletions(-) delete mode 100644 quest/m1/2067-test-open-gop-h-264-tune-in-end-to-end-leading-picture.md create mode 100755 test/ts/open-gop.py diff --git a/.github/workflows/interop.yml b/.github/workflows/interop.yml index f2f95de0178..cbbe0a43f56 100644 --- a/.github/workflows/interop.yml +++ b/.github/workflows/interop.yml @@ -122,6 +122,14 @@ jobs: env: MOQ_TEST_RUNS: ${{ runner.temp }}/moq-test-runs + # The same round-trip over an open-GOP clip: every leading picture after a + # recovery point must come back, in decode order. + - name: TS open GOP + run: nix develop --command just test ts --open-gop + shell: bash -leo pipefail {0} + env: + MOQ_TEST_RUNS: ${{ runner.temp }}/moq-test-runs + # Builds the sparse-EPG and pending-version fixtures and round-trips # them, asserting the schedule survives and pending sections are dropped. - name: EIT fixtures diff --git a/quest/m1/2067-test-open-gop-h-264-tune-in-end-to-end-leading-picture.md b/quest/m1/2067-test-open-gop-h-264-tune-in-end-to-end-leading-picture.md deleted file mode 100644 index a10eafb6a04..00000000000 --- a/quest/m1/2067-test-open-gop-h-264-tune-in-end-to-end-leading-picture.md +++ /dev/null @@ -1,43 +0,0 @@ -# [M] Open-GOP H.264: fixture and cold tune-in characterization - -## Goal - -An open-GOP H.264 broadcast (non-IDR recovery-point keyframes with leading -pictures) round-trips in the `test/ts` harness as a regression fixture, and -the cold tune-in behaviour in a WebCodecs viewer is measured and written down: -glitch duration, dropped versus corrupt frames, and whether any decoder errors. - -## Plan - -#2066 taught the H.264 splitter to treat a recovery-point SEI as a keyframe, -so groups start at the recovery point and the rendition resolves. The -reference capture from #2050 is the hard case: every recovery point is -followed in decode order by about seven pictures presented *before* it, which -reference the previous GOP. At a cold tune-in those leading pictures decode -against missing references, and nothing in the Rust splitter or the JS -consumer identifies them. Continuous playback across a recovery point has all -the references and should be clean. - -- Fixture: `rs/moq-mux/src/container/ts/test_data/scte35/kyrion_dirtystart.ts` - is already open GOP with B-frames; confirm it carries leading pictures - (POC below the keyframe after a recovery point) and use it, else generate a - clip with x264 `open-gop=1` and a recovery-point SEI. The generated clip in - `test/ts/run.sh` is closed-GOP IDR today, so add the open-GOP source as a - second round-trip rather than replacing it. -- Characterization: drive `` through the media harness - (`just test media`, `test/interop/clients/js/media.ts`) with the - open-GOP fixture: continuous playback across recovery points and a cold - tune-in at one, counting dropped and corrupt frames and decoder errors; a - hardware decoder by hand if available. Record the numbers in the PR and in the - leading-picture quest. -- The consumer-side fix is - [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md), which - waits on these numbers. - -## Closes - -- [#2067](https://github.com/moq-dev/moq/issues/2067) - close this issue when the quest finishes - -## Related - -- [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - the tune-in drop this characterizes diff --git a/quest/m1/README.md b/quest/m1/README.md index d663cd37176..5ceca9ce577 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -148,7 +148,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [MSF caption roles](/quest/m1/captions-msf.md) - an MSF caption, subtitle, or sign-language track survives conversion to a hang catalog - [CEA-608/708](/quest/m1/captions-cea.md) - captions carried inside video SEI become a real text rendition at import - [Colour model](/quest/m1/color-model.md) - the catalog describes a rendition's colour and HDR properties instead of leaving a TODO -- [#2067](/quest/m1/2067-test-open-gop-h-264-tune-in-end-to-end-leading-picture.md) - Open-GOP H.264: a regression fixture and a measured cold tune-in - [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - a viewer joining at a recovery point drops the leading pictures it cannot decode; continuous viewers keep them - [Catalog warmup](/quest/m1/catalog-warmup.md) - `warmup` on video and audio renditions, in the catalog and the draft - [Audio warmup](/quest/m1/audio-warmup.md) - a viewer joining an Opus rendition mid-stream never hears the unconverged first 80 ms diff --git a/quest/m1/open-gop-leading-pictures.md b/quest/m1/open-gop-leading-pictures.md index c1f84922ea4..0dc7c0af266 100644 --- a/quest/m1/open-gop-leading-pictures.md +++ b/quest/m1/open-gop-leading-pictures.md @@ -21,6 +21,22 @@ drop belongs on the consumer: ingest cannot know whether a given viewer has the previous GOP, and dropping at ingest would degrade continuous playback for everyone. +Measured through `` in Chromium 153 on macOS, on the clip +`just test ts --open-gop` generates (three leading pictures per recovery +point) stretched to 120 s. Continuous playback decoded every leading picture +on both decoder paths, with no errors, and the two paths' frames were +identical. At a cold join the paths differ. VideoToolbox (the default there) +outputs nothing for the orphaned leading pictures and raises no error, and +every frame it does output matches the continuous decode, so a viewer merely +starts at the keyframe. The software decoder (`prefer-software`, the path a +browser without hardware H.264 takes; Linux was not measured) raises +`EncodingError` in every join, and the watch then closes its decoder, so video +stops. The same joins with the leading pictures removed from the stream decode +cleanly in software, so the error is the leading pictures, not the non-IDR +keyframe. A latency skip ("skipping slow group") orphans the next group's +leading pictures in the same way. The trim therefore has to happen before +decode, and the JS test should drive the software decoder. + - In the JS consumer (`js/hang/src/container/consumer.ts` forces the first sample of a group to `keyframe`, and `js/watch/src/video/decoder.ts` submits it as `"key"`): for the first group after any non-continuous transition, @@ -48,10 +64,6 @@ everyone. group's leading pictures trimmed too, so an implementation that only trims the initial group fails. Both cases in both languages. -## Required - -- [#2067](/quest/m1/2067-test-open-gop-h-264-tune-in-end-to-end-leading-picture.md) - decides whether the glitch is dropped frames, corrupt frames, or a decoder error, which sets what this has to prove - ## Related - [Consumer warmup](/quest/m2/intra-refresh/consumer-warmup.md) - the `recovery_frame_cnt > 0` case this rule does not cover diff --git a/quest/m2/intra-refresh/README.md b/quest/m2/intra-refresh/README.md index 3bfb94cd117..ca1405bcac5 100644 --- a/quest/m2/intra-refresh/README.md +++ b/quest/m2/intra-refresh/README.md @@ -50,6 +50,5 @@ Decisions the quests share: ## Related - [Audio warmup](/quest/m1/audio-warmup.md) - Opus convergence after a mid-stream join uses the same `warmup` field -- [#2067](/quest/m1/2067-test-open-gop-h-264-tune-in-end-to-end-leading-picture.md) - the open-GOP fixture and cold tune-in measurement - [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - frames stamped before the group's keyframe are the other tune-in trim - [Catalog warmup](/quest/m1/catalog-warmup.md) - the generic `warmup` field this line reads, kept in m1 for audio and open-GOP tune-in diff --git a/test/justfile b/test/justfile index ee082ed2316..2f3bc271f95 100644 --- a/test/justfile +++ b/test/justfile @@ -88,7 +88,8 @@ drill-sensitivity *args: # burstiness, instantaneous bitrate, T-STD). Flags: `--analyze-only file.ts` # (skip the round-trip), `--strict` (fail on shape warnings), `--source file.ts` # (use a real capture), `--live` (grade PCR release timing and byte position off -# the pipe instead, which a capture cannot carry; nightly runs this arm). See +# the pipe instead, which a capture cannot carry; nightly runs this arm), +# `--open-gop` (an open-GOP clip whose leading pictures must survive). See # ts/README.md. # Check the subscriber's MPEG-TS output for IRD compliance. diff --git a/test/ts/README.md b/test/ts/README.md index e8507625136..28bcf8e3482 100644 --- a/test/ts/README.md +++ b/test/ts/README.md @@ -11,12 +11,14 @@ is VBR, inserts no null packets, and paces PCR once per media frame, so several broadcast-shape checks are expected to flag. The report quantifies exactly where and by how much. -Three instruments live here. `compliance.py` (via `run.sh`) grades a captured file +Four instruments live here. `compliance.py` (via `run.sh`) grades a captured file against the IRD model. [`pcr-timing.py`](#pcr-timing-pcr-timingpy) grades a live pipe, which is the only way to see *when* the exporter released each PCR. [`table-anchor.py`](#table-anchoring-table-anchorpy) grades two exporters of one broadcast against each other, which is the only way to see whether a table's emission points come from the media or from the exporter's own clock. +[`open-gop.py`](#open-gop-open-goppy) grades an open-GOP capture against its +source, access unit by access unit. ## Running @@ -28,6 +30,7 @@ just test ts --strict # also fail on broadcast-shape warnings just test ts --with-eit # add a synthetic EPG first, report which SI survived just test ts --live # grade PCR release timing off the live pipe just test ts --pair # two exporters of one broadcast, grade table anchoring +just test ts --open-gop # open-GOP clip; its leading pictures must survive ``` `--live` swaps the analyzer, not the rig: the same round-trip runs, but the @@ -311,6 +314,38 @@ rather than leaving a percentage to interpret: -> a timer started with the exporter, not an anchor in the media ``` +## Open GOP (`open-gop.py`) + +Broadcast contribution encoders commonly send open GOP: after the first IDR, each +keyframe is a non-IDR I picture flagged by a recovery-point SEI, and the B pictures +that follow it in decode order but are presented before it (its leading pictures) +reference the previous GOP. Only a viewer that already holds that GOP can decode +them. Dropping them is right at a tune-in, which the transport cannot see, so the +round-trip has to hand every one of them on, in decode order. + +`--open-gop` swaps the generated clip for an x264 `open-gop=1` encode whose 24-frame +GOP and fixed B placement put three leading pictures behind every recovery point, +round-trips it, and runs `open-gop.py` on the source and capture before the +compliance report. With `--source`, it grades a real capture instead, and fails if +that capture has no leading pictures to grade. + +```bash +./open-gop.py source.ts capture.ts +``` + +Access units are matched by their slice data, so the comparison ignores the +parameter sets and delimiters the round-trip may re-insert and the timestamp +rebase. + +| Check | Severity | What it verifies | +|---|---|---| +| `fixture` | hard | the source has at least two non-IDR recovery points with leading pictures | +| `decode-order` | hard | the capture is one contiguous run of the source's access units from a random-access point, with DTS strictly increasing | +| `leading-pictures` | hard | every leading picture in that run is there and keeps the presentation offset the source gave it | +| `random-access-indicator` | shape | the exporter flags exactly the random-access access units | +| `recovery-point-sei` | shape | each recovery point keeps its SEI | +| `dts-before-pts` | shape | no access unit is stamped to decode after it presents | + ## EIT fixtures No capture in this repository carries EIT (PID 0x0012), so nothing exercises the @@ -408,9 +443,10 @@ exporter re-emits SI on its own repetition cadence rather than the source's. ## CI -`.github/workflows/interop.yml` runs `just test ts` and then `just test ts-eit` -after the interop matrix (nightly, on demand, and on PRs touching `test/ts/`). -The second recipe is `eit-roundtrip.sh`: it builds the sparse-schedule and +`.github/workflows/interop.yml` runs `just test ts`, `just test ts --open-gop`, +and `just test ts-eit` after the interop matrix (nightly, on demand, and on PRs +touching `test/ts/`). +`ts-eit` is `eit-roundtrip.sh`: it builds the sparse-schedule and pending-version fixtures from a generated clip, round-trips them through a relay, and censuses the capture, so a break in the generators or in the SI carriage they pin fails a PR instead of landing silently. TSDuck comes from the diff --git a/test/ts/open-gop.py b/test/ts/open-gop.py new file mode 100755 index 00000000000..65e921237a7 --- /dev/null +++ b/test/ts/open-gop.py @@ -0,0 +1,320 @@ +#!/usr/bin/env python3 +"""Grade whether an open-GOP H.264 stream keeps its leading pictures through a round-trip. + + ./open-gop.py source.ts capture.ts + +An open-GOP recovery point is a non-IDR I picture flagged by a recovery-point SEI. The +pictures that follow it in decode order but are presented before it, its leading +pictures, reference the previous GOP, so only a viewer that already holds that GOP can +decode them. A viewer playing continuously needs every one of them, in decode order. +Dropping them is right only at a tune-in, which the transport cannot see, so the +round-trip has to hand them all on. + +Access units are matched by their slice data. That makes the comparison indifferent to +the parameter sets and delimiters the round-trip may re-insert and to the timestamp +rebase, and exact about order: the capture must be one contiguous run of the source's +access units, starting at a random-access point. + +Hard checks: the source is open GOP with leading pictures (else nothing here is tested), +the capture is that contiguous run with DTS strictly increasing, and every captured +picture keeps the presentation offset the source gave it, which is what makes a leading +picture leading. Shape checks, reported and failing only under `--strict`: whether each +exported random-access point carries the random_access_indicator and keeps its +recovery-point SEI, and whether any access unit is stamped to decode after it presents. + +Exit status is 0 when every hard check passes, 1 otherwise. +""" + +import argparse +import hashlib +import sys +from dataclasses import dataclass + +PKT = 188 +SYNC = 0x47 +HARD, SHAPE = "hard", "shape" +AVC_STREAM_TYPE = 0x1B +NAL_SLICE, NAL_IDR, NAL_SEI = 1, 5, 6 +SEI_RECOVERY_POINT = 6 +TS_WRAP = 1 << 33 +# Two recovery points with leading pictures is the least that crosses a GOP boundary +# the fixture did not start at, which the first GOP after an IDR never does. +MIN_RECOVERY_POINTS = 2 +# The round-trip carries time in microseconds, so a 90 kHz tick can come back one off. +PTS_TOLERANCE = 1 + + +@dataclass +class AccessUnit: + key: bytes # digest of the slice NAL units, which the round-trip must not touch + pts: int + dts: int + rai: bool # random_access_indicator on the packet that starts the PES + idr: bool + recovery: bool # carries a recovery-point SEI + + +def fail(message): + print(f"error: {message}", file=sys.stderr) + sys.exit(1) + + +def packets(path): + with open(path, "rb") as f: + data = f.read() + if not data or len(data) % PKT or data[0] != SYNC: + fail(f"{path} is not a 188-byte-aligned transport stream") + return [data[i : i + PKT] for i in range(0, len(data), PKT)] + + +def pid_of(pkt): + return ((pkt[1] & 0x1F) << 8) | pkt[2] + + +def payload(pkt): + """The packet's payload, or None when it has none.""" + afc = (pkt[3] >> 4) & 0x3 + if not afc & 0x1: + return None + start = 4 + (1 + pkt[4] if afc & 0x2 else 0) + return pkt[start:] if start < PKT else None + + +def section(pkt): + """The PSI section starting in this packet (PAT and PMT fit in one here).""" + body = payload(pkt) + if body is None or not pkt[1] & 0x40: + return None + return body[1 + body[0] :] + + +def video_pid(path, pkts): + pmt = None + for pkt in pkts: + pid = pid_of(pkt) + if pmt is None and pid == 0 and (sec := section(pkt)): + # First program entry after the 8-byte header; program 0 is the NIT. + for i in range(8, 3 + (((sec[1] & 0x0F) << 8) | sec[2]) - 4, 4): + if (sec[i] << 8 | sec[i + 1]) != 0: + pmt = ((sec[i + 2] & 0x1F) << 8) | sec[i + 3] + break + elif pid == pmt and (sec := section(pkt)): + end = 3 + (((sec[1] & 0x0F) << 8) | sec[2]) - 4 + i = 12 + (((sec[10] & 0x0F) << 8) | sec[11]) + while i + 5 <= end: + if sec[i] == AVC_STREAM_TYPE: + return ((sec[i + 1] & 0x1F) << 8) | sec[i + 2] + i += 5 + (((sec[i + 3] & 0x0F) << 8) | sec[i + 4]) + fail(f"{path}: the PMT lists no H.264 stream") + fail(f"{path}: no PAT/PMT found") + + +def timestamp(b): + return ((b[0] >> 1) & 0x7) << 30 | b[1] << 22 | (b[2] >> 1) << 15 | b[3] << 7 | b[4] >> 1 + + +def nal_units(es): + """NAL units of an Annex-B elementary stream, without their start codes.""" + starts = [] + i = es.find(b"\x00\x00\x01") + while i >= 0: + starts.append(i + 3) + i = es.find(b"\x00\x00\x01", i + 3) + for n, start in enumerate(starts): + end = starts[n + 1] - 3 if n + 1 < len(starts) else len(es) + nal = es[start:end].rstrip(b"\x00") + if nal: + yield nal + + +def has_recovery_point(nal): + """True if an SEI NAL carries a recovery-point message (payload type 6).""" + rbsp = nal[1:].replace(b"\x00\x00\x03", b"\x00\x00") + i = 0 + try: + while i < len(rbsp) and rbsp[i] != 0x80: + kind = size = 0 + while rbsp[i] == 0xFF: + kind, i = kind + 255, i + 1 + kind, i = kind + rbsp[i], i + 1 + while rbsp[i] == 0xFF: + size, i = size + 255, i + 1 + size, i = size + rbsp[i], i + 1 + if kind == SEI_RECOVERY_POINT: + return True + i += size + except IndexError: + fail("an SEI NAL ends inside a message header") + return False + + +def access_units(path): + """One AccessUnit per video PES (the exporter and ffmpeg both write one AU per PES).""" + pkts = packets(path) + pid = video_pid(path, pkts) + pes = [] + for pkt in pkts: + if pid_of(pkt) != pid or (body := payload(pkt)) is None: + continue + if pkt[1] & 0x40: + rai = bool(pkt[3] & 0x20 and pkt[4] and pkt[5] & 0x40) + pes.append((rai, bytearray(body))) + elif pes: + pes[-1][1].extend(body) + units = [] + for rai, b in pes: + if b[:3] != b"\x00\x00\x01" or not b[7] & 0x80: + fail(f"{path}: a video PES carries no PTS") + pts = timestamp(b[9:14]) + dts = timestamp(b[14:19]) if b[7] & 0x40 else pts + digest, idr, recovery = hashlib.sha1(), False, False + for nal in nal_units(bytes(b[9 + b[8] :])): + kind = nal[0] & 0x1F + if kind in (NAL_SLICE, NAL_IDR): + digest.update(nal) + idr |= kind == NAL_IDR + recovery |= kind == NAL_SEI and has_recovery_point(nal) + units.append(AccessUnit(digest.digest(), pts, dts, rai, idr, recovery)) + return units + + +def delta(a, b): + """a - b on the 33-bit timestamp circle.""" + return (a - b + TS_WRAP // 2) % TS_WRAP - TS_WRAP // 2 + + +def is_rap(unit): + return unit.idr or unit.recovery + + +def leading(units): + """Per random-access point index, the indices of its leading pictures.""" + out, rap = {}, None + for i, unit in enumerate(units): + if is_rap(unit): + rap = i + out[rap] = [] + elif rap is not None and delta(unit.pts, units[rap].pts) < 0: + out[rap].append(i) + return out + + +def main(): + ap = argparse.ArgumentParser(description="Grade open-GOP leading pictures across a TS round-trip.") + ap.add_argument("source", help="TS that was published") + ap.add_argument("capture", help="TS the subscriber exported") + ap.add_argument("--strict", action="store_true", help="fail on shape checks too") + args = ap.parse_args() + + src = access_units(args.source) + cap = access_units(args.capture) + results = [] + + def check(name, severity, ok, detail): + results.append((name, severity, ok, detail)) + + src_leading = leading(src) + open_rps = [i for i, lead in src_leading.items() if lead and not src[i].idr] + check( + "fixture", + HARD, + len(open_rps) >= MIN_RECOVERY_POINTS, + f"source: {len(src)} AUs, {len(open_rps)} non-IDR recovery point(s) with " + f"{sum(len(src_leading[i]) for i in open_rps)} leading picture(s)", + ) + + # Where the capture starts in the source. Frames can repeat in principle, so take the + # first candidate the whole run agrees with rather than the first match on one key. + starts = [i for i, unit in enumerate(src) if cap and unit.key == cap[0].key] + start = next((i for i in starts if [u.key for u in src[i : i + len(cap)]] == [u.key for u in cap]), None) + if start is None: + detail = "the capture's first AU is not in the source" + if starts: + s, prefix = starts[0], 0 + while prefix < len(cap) and s + prefix < len(src) and src[s + prefix].key == cap[prefix].key: + prefix += 1 + want = s + prefix + kind = ( + "a leading picture" + if any(want in lead for lead in src_leading.values()) + else "a random-access point" + if want < len(src) and is_rap(src[want]) + else "a picture" + ) + detail = ( + f"capture AU {prefix} of {len(cap)} departs from the source; " + f"source AU {want} ({kind}) is missing or moved" + ) + check("decode-order", HARD, False, detail) + else: + backwards = [i for i in range(1, len(cap)) if delta(cap[i].dts, cap[i - 1].dts) <= 0] + ok = is_rap(src[start]) and not backwards + detail = f"{len(cap)} AUs, source AUs {start}..{start + len(cap) - 1} in order" + if not is_rap(src[start]): + detail += f"; but starts at source AU {start}, which is not a random-access point" + if backwards: + detail += f"; DTS does not advance at {len(backwards)} AU(s), first at {backwards[0]}" + check("decode-order", HARD, ok, detail) + + if start is not None: + # Leading pictures are defined by presentation offset, so check the offset of every + # captured picture rather than only counting the ones that still come out leading. + moved = [ + i + for i in range(len(cap)) + if abs(delta(cap[i].pts, cap[0].pts) - delta(src[start + i].pts, src[start].pts)) > PTS_TOLERANCE + ] + # Keyed on the source's random-access points, so an exporter that strips the SEI + # fails the SEI check below rather than hiding its leading pictures from this one. + kept = { + i - start: [j - start for j in lead if j < start + len(cap)] + for i, lead in src_leading.items() + if lead and start <= i < start + len(cap) + } + # A capture cut short can end inside a GOP; only a leading picture it reached is owed. + owed = sum(len(lead) for lead in kept.values()) + found = sum(1 for i, lead in kept.items() for j in lead if delta(cap[j].pts, cap[i].pts) < 0) + # Only a recovery point with a captured leading picture tests anything. + crossed = len([i for i, lead in kept.items() if lead and not src[start + i].idr]) + ok = not moved and found == owed and crossed >= MIN_RECOVERY_POINTS + detail = f"{found}/{owed} leading picture(s) across {crossed} recovery point(s)" + if moved: + detail += f"; {len(moved)} AU(s) presented away from the source's offset, first at {moved[0]}" + if crossed < MIN_RECOVERY_POINTS: + detail += f"; the capture reaches leading pictures at fewer than {MIN_RECOVERY_POINTS} recovery points" + check("leading-pictures", HARD, ok, detail) + + raps = [i for i in range(len(cap)) if is_rap(src[start + i])] + flagged = [i for i in raps if cap[i].rai] + stray = [i for i in range(len(cap)) if cap[i].rai and not is_rap(src[start + i])] + detail = f"{len(flagged)}/{len(raps)} random-access AU(s) flagged" + if stray: + detail += f"; {len(stray)} non-random-access AU(s) flagged too" + check("random-access-indicator", SHAPE, len(flagged) == len(raps) and not stray, detail) + + rps = [i for i in raps if src[start + i].recovery] + survived = [i for i in rps if cap[i].recovery] + check("recovery-point-sei", SHAPE, len(survived) == len(rps), f"{len(survived)}/{len(rps)} kept the SEI") + + late = [i for i in range(len(cap)) if delta(cap[i].dts, cap[i].pts) > 0] + worst = max((delta(cap[i].dts, cap[i].pts) for i in late), default=0) + check( + "dts-before-pts", + SHAPE, + not late, + f"{len(late)}/{len(cap)} AU(s) decode after they present, worst by {worst / 90:.1f} ms", + ) + + print("### open-GOP report") + failed = 0 + for name, severity, ok, detail in results: + gating = severity == HARD or args.strict + status = "PASS" if ok else ("FAIL" if gating else "WARN") + failed += not ok and gating + print(f" {status} {name:<24} [{severity}] {detail}") + print(f"{failed} check(s) failed" if failed else "open-gop: PASS") + return 1 if failed else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/test/ts/run.sh b/test/ts/run.sh index ea87b5eddec..0858b89dadc 100755 --- a/test/ts/run.sh +++ b/test/ts/run.sh @@ -17,6 +17,7 @@ # ./run.sh --with-eit # add a synthetic EPG first, report which SI survived # ./run.sh --live # grade PCR release timing off the live pipe # ./run.sh --pair # two exporters of one broadcast, grade table anchoring +# ./run.sh --open-gop # open-GOP clip; its leading pictures must survive # `--live` swaps the analyzer, not the rig. compliance.py grades a captured file # on the stream's own PCR clock, which is the right basis for the IRD model it @@ -59,6 +60,7 @@ STRICT="" WITH_EIT="" # add a synthetic EPG to the source and report which SI survived LIVE="" # grade the exporter's stdout as it arrives, rather than a capture PAIR="" # subscribe twice and grade the two captures against each other +OPEN_GOP="" # publish open GOP with leading pictures, and grade them through the round-trip # How far into the run the second subscriber joins. A late join is the point: two # exporters started together can share a cadence by starting together, which is # exactly the thing under test. @@ -116,6 +118,10 @@ while [[ $# -gt 0 ]]; do PAIR_JOIN="$2" shift 2 ;; + --open-gop) + OPEN_GOP=1 + shift + ;; *) PASSTHRU+=("$1") shift @@ -142,6 +148,12 @@ if [[ -n "$PAIR" ]]; then fi fi +# open-gop.py grades a capture against its source, which only the plain round-trip keeps. +if [[ -n "$OPEN_GOP" && -n "$ANALYZE_ONLY$LIVE$PAIR" ]]; then + echo "error: --open-gop cannot be combined with --analyze-only, --live, or --pair" >&2 + exit 1 +fi + URL="" # set once a port is reserved, below have() { command -v "$1" >/dev/null 2>&1; } @@ -226,17 +238,22 @@ if [[ -n "$SOURCE" ]]; then exit 1 } else - echo "### generating ~${DURATION}s broadcast-like clip with ffmpeg" + echo "### generating ~${DURATION}s broadcast-like ${OPEN_GOP:+open-GOP }clip with ffmpeg" # CBR with a 20 ms PCR, like a contribution feed. Not cosmetic: `regulate` # paces on the source PCR, so a clip whose clock is coarse and whose rate is # unconstrained is released unevenly and finishes early (measured: a 20 s clip # in 17 s, and release jitter of its own). The harness then grades ffmpeg. + X264="keyint=25:min-keyint=25:scenecut=0" + # Open GOP: after the first IDR, every keyframe is a non-IDR I picture with a + # recovery-point SEI. Fixed B placement in a 24-frame GOP puts three B pictures + # right after each one in decode order, presented before it: leading pictures. + [[ -n "$OPEN_GOP" ]] && X264="keyint=24:min-keyint=24:scenecut=0:open-gop=1:bframes=3:b-adapt=0" ffmpeg -y -hide_banner -loglevel error \ -f lavfi -i "testsrc=size=1280x720:rate=25" \ -f lavfi -i "sine=frequency=1000:sample_rate=48000" \ -t "$DURATION" \ -c:v libx264 -profile:v high -preset veryfast -pix_fmt yuv420p \ - -x264-params "keyint=25:min-keyint=25:scenecut=0" -b:v 8M \ + -x264-params "$X264" -b:v 8M \ -c:a aac -b:a 128k \ -f mpegts -muxrate "$BITRATE" -pcr_period 20 -pes_payload_size 0 "$SRC_TS" fi @@ -478,6 +495,18 @@ if [[ -n "$WITH_EIT" ]]; then "$(count_pid "$SRC_TS" "${spec##*:}")" "$(count_pid "$SUB_TS" "${spec##*:}")" done fi + +# Leading pictures are only decodable in continuous playback, which is the case this +# subscriber is in, so the round-trip owes every one of them, in decode order. +if [[ -n "$OPEN_GOP" ]]; then + echo + if ! python3 "$DIR/open-gop.py" "$SRC_TS" "$SUB_TS" $STRICT; then + echo >&2 + echo "error: open-GOP analysis failed (see round-trip logs below)" >&2 + dump_logs + exit 1 + fi +fi echo # Pass the source so duration-fidelity can pin the exported stream's rate. A tiny # capture still parses, so the round-trip can fail here with a non-empty file; From db8ca6c981b3dcb0b04c3c8d0fa72c46de792ee7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 12:14:32 -0700 Subject: [PATCH 031/128] fix(moq-tokio): iroh honors the configured versions (#4448) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Problem #4148 made `moq-lite-07-wip` opt-in, but `iroh://` built its listener ALPNs, dial offers, and H3 subprotocols from the `moq_net::ALPNS` constant instead of the configured `Versions`. A config opting into `moq-lite-07-wip` was accepted and then ignored on iroh, while `https://`, `moqt://`, TCP, and Unix sockets honored it. ## Approach - Dial: `iroh::connect` takes the client's resolved `Versions` (first ALPN is the primary, the rest are additional, H3 stays last). - Listen: `iroh::Config::bind` no longer registers ALPNs, since the endpoint is bound before any server's versions are known. `Server::build` calls `iroh::listen`, which registers the server's configured ALPNs (plus H3) with `Endpoint::set_alpns`. - Accept: `iroh::accept` matches the raw ALPN against the configured set, and the H3 branch picks the first offered subprotocol in that set (same as noq) instead of blindly the first. - An empty version list is refused (`iroh::Error::NoVersions`) at `Server::build` and at dial, never replaced by the default set. - The finalized lite-07 ALPN stays `moq-lite-07`, per the quest. Deletes the quest file and its milestone entry. Tests: `iroh_connect_lite_07_wip` (both ends opt in, asserts the negotiated ALPN) and `iroh_versions_disjoint` (default dialer vs wip-only listener never connects). Both fail on main. ## Impact - Public API: none changed. `iroh::Config::bind` keeps its signature; the endpoint it returns now accepts nothing until a `moq_tokio::server::Server` takes it. New variant `moq_tokio::iroh::Error::NoVersions` (the enum is `#[non_exhaustive]`). - `moq_tokio::server::Config::iroh` now documents that a server owns its endpoint's listener (ALPN set, accept, close), so one endpoint must not back two servers. - Wire: none for default configs. An iroh listener with a pinned `version` now advertises only those ALPNs (plus H3) instead of the full default set. ## Alternatives - Add a `versions` argument to `iroh::Config::bind`: breaks every caller (relay, cli, gst) and needs the listener's versions before the server exists. ## Follow-ups - `rs/moq-ffi/src/transport.rs` (the wasm browser dial) still offers `moq_net::ALPNS`. The wasm client has no version setting, so there is nothing configured to thread; left unchanged. Making it configurable is a public API change across every binding, so it needs a maintainer decision. (Written by Claude Sonnet 5.5, updated by Claude Opus 5.5) 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- quest/m1/README.md | 1 - quest/m1/iroh-lite-wip.md | 31 --------------- rs/moq-tokio/src/client.rs | 22 ++++++++--- rs/moq-tokio/src/iroh.rs | 53 +++++++++++++++++-------- rs/moq-tokio/src/server.rs | 24 +++++++++--- rs/moq-tokio/tests/backend.rs | 74 +++++++++++++++++++++++++++++++++++ 6 files changed, 147 insertions(+), 58 deletions(-) delete mode 100644 quest/m1/iroh-lite-wip.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 5ceca9ce577..081e7a7d6ba 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -63,7 +63,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Auth client CA](/quest/m1/relay-auth-client-ca.md) - on dev, `auth::Config::validate` and `init` take the client-CA flag, so no caller can skip the check - [HLS linger](/quest/m1/hls-linger.md) - `moq_hls::Server` serves an ended broadcast for its playlist window plus grace, so the moq.pro edge drops its own pool - [Remove live()](/quest/m1/remove-live.md) - on dev, importers publish stream timestamps verbatim, the catalog clock maps them to wall time, and an encoder restart becomes a new epoch -- [iroh versions](/quest/m1/iroh-lite-wip.md) - `iroh://` negotiates the configured versions, so `moq-lite-07-wip` can be opted into - [Go and Dart doc samples](/quest/m1/doc-samples-go-dart.md) - Go and Dart doc samples compile against their wrappers - [Data capture in bindings](/quest/m1/data-capture-bindings.md) - moq-ffi and every wrapper pass a data frame's capture time, and the JSON window producer takes one - [Moxygen compatibility](/quest/m1/moxygen/README.md) - one subgroup per group, whole-group FETCH, and one datagram per group, never a full moxygen pass diff --git a/quest/m1/iroh-lite-wip.md b/quest/m1/iroh-lite-wip.md deleted file mode 100644 index f6be7e23dc7..00000000000 --- a/quest/m1/iroh-lite-wip.md +++ /dev/null @@ -1,31 +0,0 @@ -# [XS] iroh honors the configured versions - -## Goal - -An `iroh://` client or listener configured with `moq-lite-07-wip` negotiates -it, as `https://`, `moqt://`, TCP, and Unix sockets already do. A version -list that iroh cannot offer is refused at startup, never silently replaced. - -## Plan - -https://github.com/moq-dev/moq/pull/4148 took `moq-lite-07-wip` out of -`moq_net::ALPNS` so it is opt-in only, but `rs/moq-tokio/src/iroh.rs` builds -its listener ALPNs, its dial offers, and its H3 subprotocols from that -constant rather than the configured `Versions` (`versions.alpns()`, which -`noq.rs`, `server.rs`, and `client.rs` use). So the opt-in is accepted by -config and then ignored on iroh. Thread the configured versions through -instead. - -`moq-ffi`'s transport (`rs/moq-ffi/src/transport.rs`) also offers -`moq_net::ALPNS` directly; fix it here too. The relay's WebSocket listener -already honors the configured versions. Scope is those two files. - -Decided by the maintainer: the finalized lite-07 ALPN stays `moq-lite-07`, -as `drafts/draft-lcurley-moq-lite.md` already says. Peers from the yanked -0.3.2 / 0.15.3 releases advertise `moq-lite-07` with an older framing, and -could land on it with a finalized peer; the maintainer accepts that risk -rather than burn the identifier. Nothing in this quest changes the ALPN. - -## Related - -- [iroh opt-in for moq-relay](/quest/m1/relay-iroh-opt-in.md) - a separate change: whether the relay builds iroh at all diff --git a/rs/moq-tokio/src/client.rs b/rs/moq-tokio/src/client.rs index dd1a0fdceb7..b2ed72358db 100644 --- a/rs/moq-tokio/src/client.rs +++ b/rs/moq-tokio/src/client.rs @@ -45,9 +45,14 @@ pub struct Client { /// The single resolved set of protocol versions, used to advertise moq ALPNs across /// every transport (passed into the QUIC backend's `connect` and used directly for /// raw TCP/UDS qmux and WebSocket). Resolved once in [`Client::new`] so the ALPN list - /// can't diverge between transports. iroh is the exception: it negotiates over the - /// full `moq_net::ALPNS` rather than the configured subset, so it reads nothing here. - #[cfg(any(feature = "noq", feature = "websocket", feature = "tcp", feature = "uds"))] + /// can't diverge between transports. + #[cfg(any( + feature = "noq", + feature = "iroh", + feature = "websocket", + feature = "tcp", + feature = "uds" + ))] versions: moq_net::Versions, /// The URL from [`connect.url`](crate::connect::Config::url), dialed by [`Client::publish`] / [`Client::consume`]. connect: Option, @@ -128,7 +133,13 @@ impl Client { Ok(Self { moq: moq_net::Client::new().with_versions(versions.clone()), - #[cfg(any(feature = "noq", feature = "websocket", feature = "tcp", feature = "uds"))] + #[cfg(any( + feature = "noq", + feature = "iroh", + feature = "websocket", + feature = "tcp", + feature = "uds" + ))] versions, connect: config.url, timeout, @@ -392,7 +403,8 @@ impl Client { if url.scheme() == "iroh" { let endpoint = self.iroh.as_ref().ok_or(Error::IrohDisabled)?; let target = request_target(&url); - let (session, binding) = crate::iroh::connect(endpoint, url, self.iroh_addrs.iter().copied()).await?; + let (session, binding) = + crate::iroh::connect(endpoint, url, self.iroh_addrs.iter().copied(), &self.versions).await?; let moq = match binding { crate::iroh::Binding::Raw => self.moq_with_path(target), diff --git a/rs/moq-tokio/src/iroh.rs b/rs/moq-tokio/src/iroh.rs index 00fb07e18e5..951260a137f 100644 --- a/rs/moq-tokio/src/iroh.rs +++ b/rs/moq-tokio/src/iroh.rs @@ -83,10 +83,14 @@ pub enum Error { #[error("failed to decode ALPN")] DecodeAlpn(#[from] std::string::FromUtf8Error), - /// The peer negotiated an ALPN this build does not speak. + /// The peer negotiated an ALPN outside the configured versions. #[error("unsupported ALPN: {0}")] UnsupportedAlpn(String), + /// The configured version list is empty, so there is no ALPN to offer. + #[error("no MoQ versions configured; iroh has no ALPN to offer")] + NoVersions, + /// The URL had no host, so there is no endpoint id to dial. #[error("Invalid URL: missing host")] MissingHost, @@ -190,6 +194,9 @@ pub struct Config { impl Config { /// Bind the iroh endpoint, applying the per-connection [`crate::quic::Config`] knobs. /// + /// The endpoint accepts nothing until a [`crate::server::Server`] takes it, which + /// registers the ALPNs of its configured versions. + /// /// iroh is a single P2P endpoint shared by both roles, so it takes the client /// section (the per-connection knobs are symmetric). It only honors the knobs /// its transport-config builder exposes (stream limits, idle timeout, MTU @@ -236,10 +243,6 @@ impl Config { SecretKey::generate() }; - // H3 is last because it requires WebTransport framing which not all H3 endpoints support. - let mut alpns: Vec> = moq_net::ALPNS.iter().map(|alpn| alpn.as_bytes().to_vec()).collect(); - alpns.push(web_transport_iroh::ALPN_H3.as_bytes().to_vec()); - // MoQ opens a stream per group, so raise the low default; also carry the // shared idle-timeout / MTU knobs onto iroh's own transport config. let max_streams = iroh::endpoint::VarInt::from_u64(quic.max_streams).unwrap_or(iroh::endpoint::VarInt::MAX); @@ -269,7 +272,6 @@ impl Config { Endpoint::builder(iroh::endpoint::presets::N0) } .secret_key(secret_key) - .alpns(alpns) .transport_config(transport.build()); if let Some(addr) = self.bind_v4 { builder = builder.bind_addr(addr)?; @@ -285,6 +287,22 @@ impl Config { } } +/// Register the ALPNs a listener accepts on `endpoint`, one per configured version. +/// +/// Refuses an empty list rather than binding a listener no peer can reach. +pub(crate) fn listen(endpoint: &Endpoint, versions: &moq_net::Versions) -> Result<()> { + let alpns = versions.alpns(); + if alpns.is_empty() { + return Err(Error::NoVersions); + } + + // H3 is last because it requires WebTransport framing which not all H3 endpoints support. + let mut accepted: Vec> = alpns.iter().map(|alpn| alpn.as_bytes().to_vec()).collect(); + accepted.push(web_transport_iroh::ALPN_H3.as_bytes().to_vec()); + endpoint.set_alpns(accepted); + Ok(()) +} + /// Accept an iroh connection, negotiate WebTransport or raw QUIC, and complete the /// handshake. Returns the established session plus the request URL (raw QUIC carries /// none). iroh exposes no client-certificate identity, so the identity is always `None`, @@ -292,6 +310,7 @@ impl Config { /// is always `None` too. pub(crate) async fn accept( conn: iroh::endpoint::Incoming, + alpns: Vec<&'static str>, ) -> Result> { let conn = conn.accept()?.await?; let alpn = String::from_utf8(conn.alpn().to_vec())?; @@ -306,7 +325,7 @@ pub(crate) async fn accept( let mut response = ConnectResponse::OK; let mut link = crate::server::Link::default(); - if let Some(protocol) = request.protocols.first() { + if let Some(protocol) = request.protocols.iter().find(|p| alpns.contains(&p.as_str())) { response = response.with_protocol(protocol); link.alpn = Some(protocol.clone()); } @@ -323,7 +342,7 @@ pub(crate) async fn accept( }) } // Raw QUIC carries no request URL; the path rides the SETUP. - alpn if moq_net::ALPNS.contains(&alpn) => { + alpn if alpns.contains(&alpn) => { let session = web_transport_iroh::QuicRequest::accept(conn).ok(); Ok(crate::server::Accepted { session, @@ -357,7 +376,11 @@ pub(crate) async fn connect( endpoint: &Endpoint, url: Url, addrs: impl IntoIterator, + versions: &moq_net::Versions, ) -> Result<(web_transport_iroh::Session, Binding)> { + let alpns = versions.alpns(); + let (primary, rest) = alpns.split_first().ok_or(Error::NoVersions)?; + let host = url.host().ok_or(Error::MissingHost)?.to_string(); let endpoint_id: iroh::EndpointId = host .parse() @@ -371,15 +394,13 @@ pub(crate) async fn connect( // We need to use this API to provide multiple ALPNs. // H3 is last because it requires WebTransport framing which not all H3 endpoints support. - let alpn = moq_net::ALPNS[0].as_bytes(); - let mut additional: Vec> = moq_net::ALPNS[1..] - .iter() - .map(|alpn| alpn.as_bytes().to_vec()) - .collect(); + let mut additional: Vec> = rest.iter().map(|alpn| alpn.as_bytes().to_vec()).collect(); additional.push(b"h3".to_vec()); let opts = iroh::endpoint::ConnectOptions::new().with_additional_alpns(additional); - let mut connecting = endpoint.connect_with_opts(endpoint_addr, alpn, opts).await?; + let mut connecting = endpoint + .connect_with_opts(endpoint_addr, primary.as_bytes(), opts) + .await?; let alpn = connecting.alpn().await?; let alpn = String::from_utf8(alpn)?; @@ -389,7 +410,7 @@ pub(crate) async fn connect( let url = url_set_scheme(url, "https")?; let mut request = ConnectRequest::new(url); - for alpn in moq_net::ALPNS { + for alpn in &alpns { request = request.with_protocol(alpn.to_string()); } @@ -398,7 +419,7 @@ pub(crate) async fn connect( Binding::H3, ) } - alpn if moq_net::ALPNS.contains(&alpn) => { + alpn if alpns.contains(&alpn) => { let conn = connecting.await?; (web_transport_iroh::Session::raw(conn), Binding::Raw) } diff --git a/rs/moq-tokio/src/server.rs b/rs/moq-tokio/src/server.rs index fa498347a52..451b8dd17bf 100644 --- a/rs/moq-tokio/src/server.rs +++ b/rs/moq-tokio/src/server.rs @@ -162,6 +162,10 @@ pub struct Config { pub websocket: Option, /// An Iroh endpoint to accept sessions from. + /// + /// The server owns the endpoint's listener: it replaces the endpoint's ALPN set with its + /// configured versions, accepts every incoming connection, and closes it on shutdown. + /// Don't give one endpoint to two servers; dialing through clones of it is fine. #[cfg(feature = "iroh")] pub iroh: Option, @@ -339,6 +343,13 @@ impl Server { unix_allow, ); + // The endpoint was bound before this server's versions were known, so it + // accepts nothing until they name its ALPNs. + #[cfg(feature = "iroh")] + if let Some(endpoint) = iroh.as_ref() { + iroh::listen(endpoint, &versions)?; + } + let mut moq = moq_net::Server::new().with_versions(versions.clone()).with_stats(stats); if let Some(publisher) = publisher { moq = moq.with_publisher(publisher); @@ -632,11 +643,14 @@ impl Server { } Some(_conn) = iroh_accept => { #[cfg(feature = "iroh")] - self.accept.push(async move { - let Accepted { session, url, identity, authority, link } = super::iroh::accept(_conn).await?; - let request = server.accept_request(tokio::time::Instant::now().into_std(), crate::transport::Session::new(session)).await?; - Ok(Request { transport: Transport::Iroh, url, identity, authority, link, kind: RequestKind::Iroh(Box::new(request)) }) - }.boxed()); + { + let alpns = versions.alpns(); + self.accept.push(async move { + let Accepted { session, url, identity, authority, link } = super::iroh::accept(_conn, alpns).await?; + let request = server.accept_request(tokio::time::Instant::now().into_std(), crate::transport::Session::new(session)).await?; + Ok(Request { transport: Transport::Iroh, url, identity, authority, link, kind: RequestKind::Iroh(Box::new(request)) }) + }.boxed()); + } } Some(_res) = ws_accept => { #[cfg(feature = "websocket")] diff --git a/rs/moq-tokio/tests/backend.rs b/rs/moq-tokio/tests/backend.rs index 01ef2a2bb23..2dd4ae1f051 100644 --- a/rs/moq-tokio/tests/backend.rs +++ b/rs/moq-tokio/tests/backend.rs @@ -528,8 +528,77 @@ async fn mtls_test(scheme: &str, reject: bool) { #[tracing_test::traced_test] #[tokio::test] async fn iroh_connect() { + iroh_connect_test(None).await; +} + +/// `moq-lite-07-wip` is opt-in, so it is on the wire only when both ends configure it. +/// iroh once built its ALPNs from the default constant and ignored that opt-in. +#[cfg(feature = "iroh")] +#[tracing_test::traced_test] +#[tokio::test] +async fn iroh_connect_lite_07_wip() { + iroh_connect_test(Some("moq-lite-07-wip")).await; +} + +/// A dialer and a listener that share no version never connect, instead of the +/// listener falling back to the default set. +#[cfg(feature = "iroh")] +#[tracing_test::traced_test] +#[tokio::test] +async fn iroh_versions_disjoint() { + use moq_tokio::iroh::Config as IrohConfig; + + let bind = || async { + let mut config = IrohConfig::default(); + config.enabled = Some(true); + config + .bind(&moq_tokio::quic::Config::default()) + .await + .expect("failed to bind iroh endpoint") + .expect("iroh endpoint not enabled") + }; + + let server_endpoint = bind().await; + let server_endpoint_id = server_endpoint.id(); + let server_addrs: Vec = server_endpoint.addr().ip_addrs().copied().collect(); + + let mut server_config = moq_tokio::listen::Config::default(); + server_config.bind = Some("[::]:0".parse().unwrap()); + server_config.tls.generate = vec!["localhost".into()]; + server_config.version = vec!["moq-lite-07-wip".parse().unwrap()]; + let mut config = moq_tokio::server::Config::default(); + config.listen = server_config; + config.iroh = Some(server_endpoint); + let mut server = config + .init() + .expect("failed to init server") + .listen() + .await + .expect("failed to listen"); + let server_handle = tokio::spawn(async move { server.accept().await.is_some() }); + + let mut client_config = moq_tokio::connect::Config::default(); + client_config.tls.insecure = Some(true); + let client = client_config + .init(Default::default()) + .expect("failed to init client") + .with_iroh(bind().await) + .with_iroh_addrs(server_addrs); + + let url: url::Url = format!("iroh://{server_endpoint_id}/room").parse().unwrap(); + let result = tokio::time::timeout(TIMEOUT, connect_once(client, url)) + .await + .expect("client connect timed out"); + assert!(result.is_err(), "the default set must not reach a wip-only listener"); + server_handle.abort(); +} + +#[cfg(feature = "iroh")] +async fn iroh_connect_test(version: Option<&str>) { use moq_tokio::iroh::Config as IrohConfig; + let version: Vec = version.map(|v| v.parse().unwrap()).into_iter().collect(); + // ── publisher (server) ────────────────────────────────────────── let pub_origin = moq_tokio::origin::spawn(); let broadcast = pub_origin.create_broadcast("test").expect("failed to create broadcast"); @@ -563,6 +632,7 @@ async fn iroh_connect() { let mut server_config = moq_tokio::listen::Config::default(); server_config.bind = Some("[::]:0".parse().unwrap()); server_config.tls.generate = vec!["localhost".into()]; + server_config.version = version.clone(); let mut config = moq_tokio::server::Config::default(); config.listen = server_config; @@ -586,6 +656,7 @@ async fn iroh_connect() { let mut client_config = moq_tokio::connect::Config::default(); client_config.tls.insecure = Some(true); + client_config.version = version.clone(); let client = client_config .init(Default::default()) @@ -608,6 +679,9 @@ async fn iroh_connect() { assert_eq!(request.url(), None); assert_eq!(request.path(), "/room"); assert_eq!(request.query(), Some("jwt=abc")); + if let Some(version) = version.first() { + assert_eq!(request.alpn(), Some(version.alpn())); + } let session = request.with_publisher(&pub_origin).ok().await?; let _broadcast = broadcast; From 4a5e421174203ecdb0eb0d046bef66f2aeb472a4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 12:29:30 -0700 Subject: [PATCH 032/128] fix(watch): hold video frames and reject older decode groups (#4483) Co-authored-by: GPT-6 Co-authored-by: Claude Opus 5.5 --- doc/lib/js/watch.md | 4 + js/hang/src/container/consumer.ts | 4 +- js/watch/src/video/decoder.test.ts | 146 ++++++++++++++++++++++++++++- js/watch/src/video/decoder.ts | 41 +++++--- quest/m1/README.md | 1 - quest/m1/watch-decoder-recovery.md | 1 - quest/m1/watch-video-guards.md | 37 -------- 7 files changed, 177 insertions(+), 57 deletions(-) delete mode 100644 quest/m1/watch-video-guards.md diff --git a/doc/lib/js/watch.md b/doc/lib/js/watch.md index 5ee0252dfa2..f151391dfdc 100644 --- a/doc/lib/js/watch.md +++ b/doc/lib/js/watch.md @@ -37,6 +37,10 @@ in sync at the latency you ask for. | `announced` | Wait for the broadcast to be announced before subscribing (default on), so a player can be mounted before the stream exists. | | `catalog-format` | `hang` (default, from the `.hang` suffix), `hangz` (compressed), `msf`, or `manual` to supply the catalog yourself. | +Video holds its last picture while paused, out of view, or waiting for a +resumed rendition's first frame. Its reported timestamp stays with that picture. +Going offline or closing the player clears it. + The overlay adds play/pause, volume, fullscreen, a quality selector, a buffering indicator, an unsupported-codec warning, and a stats panel. `` shows what the browser can play. diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index 0fc9766177d..6996e9c920d 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -140,8 +140,8 @@ export class Consumer { // Arriving below the delivery cursor is not a reason to drop a group. Groups are // sent newest-first, so the head of a subscription arrives after the live edge it - // was served alongside, and both consumers can still place one: audio writes into - // a timestamp-indexed ring, video drops a late frame at render. How far back one + // was served alongside. Audio can place older groups in its timestamp-indexed ring; + // video must reject older groups before decode to preserve codec references. How far back one // may be is the subscription's own max age, applied before it ever reaches here. const group: Group = { consumer, diff --git a/js/watch/src/video/decoder.test.ts b/js/watch/src/video/decoder.test.ts index fac3a7bbde7..b1565a597db 100644 --- a/js/watch/src/video/decoder.test.ts +++ b/js/watch/src/video/decoder.test.ts @@ -1,6 +1,7 @@ -import { describe, expect, it } from "bun:test"; +import { describe, expect, it, spyOn } from "bun:test"; import * as Catalog from "@moq/hang/catalog"; -import type * as Moq from "@moq/net"; +import * as Container from "@moq/hang/container"; +import * as Moq from "@moq/net"; import { Time } from "@moq/net"; import { Signal } from "@moq/signals"; import type { Broadcast } from "../broadcast"; @@ -147,3 +148,144 @@ describe("Decoder jitter across a source switch", () => { } }); }); + +// Drain reactive work without advancing playback time. +async function microtasks() { + for (let i = 0; i < 40; i++) await Promise.resolve(); +} + +class Picture { + closed = false; + displayWidth = 16; + displayHeight = 16; + readonly timestamp: number; + constructor(timestamp: number) { + this.timestamp = timestamp; + } + clone() { + return new Picture(this.timestamp); + } + close() { + this.closed = true; + } +} + +type Read = NonNullable>>; +function sample(group: number, timestamp: number, discontinuity = 0): Read { + return { + group, + discontinuity, + continuous: true, + frame: { timestamp: Time.Micro(timestamp), payload: new Uint8Array([1]), keyframe: true }, + }; +} + +async function guardedPlayback(kind: "legacy" | "cmaf", reads: Read[]) { + const originalDecoder = Object.getOwnPropertyDescriptor(globalThis, "VideoDecoder"); + const originalChunk = Object.getOwnPropertyDescriptor(globalThis, "EncodedVideoChunk"); + const submitted: number[] = []; + const next = spyOn(Container.Consumer.prototype, "next").mockImplementation(async () => reads.shift()); + class Codec { + state = "configured"; + readonly callbacks: VideoDecoderInit; + constructor(callbacks: VideoDecoderInit) { + this.callbacks = callbacks; + } + configure() {} + decode(chunk: EncodedVideoChunk) { + submitted.push(chunk.timestamp); + this.callbacks.output(new Picture(chunk.timestamp) as unknown as VideoFrame); + } + close() { + this.state = "closed"; + } + } + Object.defineProperty(globalThis, "VideoDecoder", { configurable: true, value: Codec }); + Object.defineProperty(globalThis, "EncodedVideoChunk", { + configurable: true, + value: class { + timestamp: number; + constructor(init: EncodedVideoChunkInit) { + this.timestamp = init.timestamp; + } + }, + }); + const video = config({ codedWidth: 16, codedHeight: 16, description: "01640028ffe100046764002801000268ee" }); + if (kind === "cmaf") + video.container = { kind, init: Buffer.from(Container.Cmaf.createVideoInitSegment(video)).toString("base64") }; + const producer = new Moq.Broadcast.Producer(); + const consumer = producer.consume(); + const catalog = new Signal({ video: { renditions: { video } } }); + const broadcast = new Signal({ + out: { catalog }, + relativeBroadcast: () => consumer, + } as unknown as Broadcast); + const source = new Source({ broadcast, supported: async () => true }); + const sync = new Sync({ delay: "instant" }); + const enabled = new Signal(true); + const decoder = new Decoder({ source, sync, enabled }); + await microtasks(); + return { + decoder, + enabled, + submitted, + close() { + decoder.close(); + source.close(); + sync.close(); + consumer.close(); + producer.close(); + next.mockRestore(); + for (const [name, original] of [ + ["VideoDecoder", originalDecoder], + ["EncodedVideoChunk", originalChunk], + ] as const) { + if (original) Object.defineProperty(globalThis, name, original); + else Reflect.deleteProperty(globalThis, name); + } + }, + }; +} + +it("promoting from no active track holds its picture and timestamp until a frame arrives", async () => { + const playback = await guardedPlayback("legacy", [sample(10, 1000)]); + try { + const held = playback.decoder.out.frame.peek(); + expect(held).toBeDefined(); + expect(playback.decoder.out.timestamp.peek()).toBe(Time.Milli(1)); + playback.enabled.set(false); + await microtasks(); + playback.enabled.set(true); + await microtasks(); + expect(playback.decoder.out.frame.peek()).toBe(held); + expect(playback.decoder.out.timestamp.peek()).toBe(Time.Milli(1)); + expect((held as unknown as Picture).closed).toBe(false); + } finally { + playback.close(); + } +}); + +// A late marker from older history raises a discontinuity without making older groups newer. +function marker(group: number, end: number, discontinuity: number): Read { + return { group, discontinuity, continuous: false, frame: undefined, end: Time.Micro(end) }; +} + +for (const kind of ["legacy", "cmaf"] as const) { + it(`${kind} skips older groups before decode, even across a stale marker's discontinuity`, async () => { + const playback = await guardedPlayback(kind, [ + sample(10, 1000), + sample(9, 900), + sample(10, 1100), + marker(8, 850, 1), + sample(7, 700, 1), + sample(11, 1200, 1), + ]); + try { + expect(playback.submitted).toEqual([1000, 1100, 1200]); + // Rejected payloads were still received, but never counted as frames. + expect(playback.decoder.out.stats.peek()).toEqual({ frameCount: 3, bytesReceived: 5 }); + } finally { + playback.close(); + } + }); +} diff --git a/js/watch/src/video/decoder.ts b/js/watch/src/video/decoder.ts index 592eb898d33..2d91fdb0d13 100644 --- a/js/watch/src/video/decoder.ts +++ b/js/watch/src/video/decoder.ts @@ -222,12 +222,13 @@ export class Decoder { // proxy() would share the same reference, allowing the source to close our frame. effect.run((inner) => { const frame = inner.get(active.frame); + if (!frame) return; // A promoted track holds the previous picture until its first frame. + this.#out.timestamp.set(Time.Milli.fromMicro(frame.timestamp as Time.Micro)); this.#out.frame.update((prev) => { prev?.close(); - return frame?.clone(); + return frame.clone(); }); }); - effect.proxy(this.#out.timestamp, active.timestamp); effect.proxy(this.#out.buffered, active.buffered); } @@ -428,6 +429,7 @@ class DecoderTrack { }); let previous: Time.Micro | undefined; + let latest: number | undefined; effect.spawn(async () => { for (;;) { @@ -440,6 +442,16 @@ class DecoderTrack { const { frame } = next; if (!frame) continue; // The group is done + // An older keyframe would replace the codec references needed by live deltas. Group + // sequences only grow within a subscription, so a discontinuity (which a stale marker + // can raise) never resets this guard. Rejected payloads still count as received bytes. + const stale = latest !== undefined && next.group < latest; + this.stats.update((current) => ({ + frameCount: (current?.frameCount ?? 0) + (stale ? 0 : 1), + bytesReceived: (current?.bytesReceived ?? 0) + frame.payload.byteLength, + })); + if (stale) continue; + // Mark that we received this frame right now. const timestamp = Time.Milli.fromMicro(frame.timestamp as Time.Micro); this.sync.received(timestamp, "video"); @@ -450,12 +462,6 @@ class DecoderTrack { timestamp: frame.timestamp, }); - // Track both frame count and bytes received for stats in the UI - this.stats.update((current) => ({ - frameCount: (current?.frameCount ?? 0) + 1, - bytesReceived: (current?.bytesReceived ?? 0) + frame.payload.byteLength, - })); - // Track decode buffer: frames sent to decoder but not yet rendered. Only bridge from // the previous frame when the consumer says nothing is missing in between. Group ids // can't answer that: they aren't required to be sequential (some encoders derive them @@ -467,6 +473,7 @@ class DecoderTrack { previous = frame.timestamp; + latest = next.group; decoder.decode(chunk); } }); @@ -505,6 +512,7 @@ class DecoderTrack { }); let previous: Time.Micro | undefined; + let latest: number | undefined; effect.spawn(async () => { for (;;) { @@ -517,15 +525,19 @@ class DecoderTrack { const { frame } = next; if (!frame) continue; - // Mark that we received this frame right now. - const timestamp = Time.Milli.fromMicro(frame.timestamp); - this.sync.received(timestamp, "video"); - - // Track stats + // An older keyframe would replace the codec references needed by live deltas. Group + // sequences only grow within a subscription, so a discontinuity (which a stale marker + // can raise) never resets this guard. Rejected payloads still count as received bytes. + const stale = latest !== undefined && next.group < latest; this.stats.update((current) => ({ - frameCount: (current?.frameCount ?? 0) + 1, + frameCount: (current?.frameCount ?? 0) + (stale ? 0 : 1), bytesReceived: (current?.bytesReceived ?? 0) + frame.payload.byteLength, })); + if (stale) continue; + + // Mark that we received this frame right now. + const timestamp = Time.Milli.fromMicro(frame.timestamp); + this.sync.received(timestamp, "video"); // Track decode buffer (see #runLegacy: bridge on the consumer's continuity signal, // never on group adjacency, which proves nothing about the timeline). @@ -536,6 +548,7 @@ class DecoderTrack { previous = frame.timestamp; if (decoder.state === "closed") break; + latest = next.group; decoder.decode( new EncodedVideoChunk({ type: frame.keyframe ? "key" : "delta", diff --git a/quest/m1/README.md b/quest/m1/README.md index 081e7a7d6ba..1f1664bb184 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -41,7 +41,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Request stream cancel](/quest/m1/request-stream-serve.md) - a lite publisher stops resolving a SUBSCRIBE or FETCH once the requester FINs or resets, through one wrapper that owns every request stream's reader - [JS closed-track leak](/quest/m1/js-closed-track-leak.md) - on dev, a subscriber that joins a closed JS track with unlimited retention is released instead of cached forever - [Session death parity](/quest/m1/session-death.md) - a local close ends tracks cleanly in both languages, and JS group readers see the session's error on session death -- [Watch video guards](/quest/m1/watch-video-guards.md) - promoting a video track holds the last picture, and an older group never reaches the codec between live deltas - [Watch decoder recovery](/quest/m1/watch-decoder-recovery.md) - one malformed packet rebuilds the audio or video decoder instead of ending playback - [Watch and publish under CSP](/quest/m1/csp-assets.md) - blob workers stay the default; strict-CSP apps host the files and set a base URL - [More tests under load](/quest/m1/test-flakes-2.md) - the second round of load-only failures, fixed at the cause diff --git a/quest/m1/watch-decoder-recovery.md b/quest/m1/watch-decoder-recovery.md index f4e208676d3..a88567066c8 100644 --- a/quest/m1/watch-decoder-recovery.md +++ b/quest/m1/watch-decoder-recovery.md @@ -25,4 +25,3 @@ instead of spinning. ## Related - [Audio warmup](/quest/m1/audio-warmup.md) - the same audio loops and priming -- [Watch video guards](/quest/m1/watch-video-guards.md) - keeps bad input from reaching the video codec diff --git a/quest/m1/watch-video-guards.md b/quest/m1/watch-video-guards.md deleted file mode 100644 index 765b652fc77..00000000000 --- a/quest/m1/watch-video-guards.md +++ /dev/null @@ -1,37 +0,0 @@ -# [S] Watch video holds its picture and its order - -## Goal - -Two `js/watch/src/video/decoder.ts` defects stop reaching the viewer: - -- Promoting a video track when none is active (after pause, scrolling back - into view, or a hidden rendition returning) holds the last picture instead - of painting black for a round trip plus a keyframe. -- An older finished group accepted behind the live group is never fed to the - codec between live deltas. - -## Plan - -Decided: - -- `#runActive` ignores the new track's initial `undefined` frame; clearing - stays with `#clearCurrentFrame` and `close()`. The held timestamp stays - with the held frame, so the outputs describe what is on screen. -- The guard lives in both video decode loops (legacy and CMAF): skip a frame - whose group is older than the newest group already fed, and reset on a - discontinuity. The consumer keeps serving older groups, since audio's - timestamp-indexed ring needs them. Fix the consumer comment claiming video - drops a late frame at render; that only holds after decode. - -Tests: a promote from nothing keeps the previous frame and timestamp; an older -group arriving after a newer one never reaches the decoder. - -## Closes - -- [#4338](https://github.com/moq-dev/moq/issues/4338) - close this issue when the quest finishes -- [#4339](https://github.com/moq-dev/moq/issues/4339) - close this issue when the quest finishes - -## Related - -- [#3056](/quest/m1/3056-watch-video-decoder-captures-the-rewind-generation-at.md) - another fix in the same decoder -- [Watch decoder recovery](/quest/m1/watch-decoder-recovery.md) - a bad feed today ends video for the subscription From f2515a0def0405225c0e93c22f5901a4e5bd9118 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 12:33:38 -0700 Subject: [PATCH 033/128] fix(mux): publish the 48 kHz decoder rate for Opus imports (#4443) Co-authored-by: Claude Sonnet 5.5 --- quest/m1/README.md | 1 - quest/m1/opus-catalog-rate.md | 15 ------------- rs/moq-mux/src/catalog/msf/consumer.rs | 5 +++-- rs/moq-mux/src/codec/opus/import.rs | 23 +++++++++++++++----- rs/moq-mux/src/container/flv/import.rs | 11 +--------- rs/moq-mux/src/container/flv/import_test.rs | 3 ++- rs/moq-mux/src/container/mkv/import.rs | 24 ++++++++++----------- rs/moq-mux/src/container/mkv/import_test.rs | 18 ++++++++++++++++ 8 files changed, 53 insertions(+), 47 deletions(-) delete mode 100644 quest/m1/opus-catalog-rate.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 1f1664bb184..e657b29d324 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -84,7 +84,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Opus concealment](/quest/m1/opus-conceal.md) - a lost Opus packet conceals the last packet's length, not 120 ms - [Audio codecs](/quest/m1/audio-codecs/README.md) - platform audio codecs, explicit unsupported cases, and channel layouts up to 7.1 - [Opus mapping family](/quest/m1/opus-mapping-family.md) - on dev, the Opus head config keeps its mapping family only in `mapping` -- [Opus catalog rate](/quest/m1/opus-catalog-rate.md) - MKV Opus import publishes the 48 kHz codec rate in the catalog, not the OpusHead input rate - [mp4-atom dOps mapping](/quest/m1/mp4-atom-dops-mapping.md) - a released mp4-atom reads and writes any `dOps` channel mapping family and table - [CMAF surround Opus](/quest/m1/cmaf-opus-surround.md) - fMP4 import and export carry an Opus channel mapping table - [js/hang dOps pre-skip](/quest/m1/js-dops-pre-skip.md) - CMAF encoding in js/hang stops hard-coding a 312-sample pre-skip diff --git a/quest/m1/opus-catalog-rate.md b/quest/m1/opus-catalog-rate.md deleted file mode 100644 index d6ba6bdd842..00000000000 --- a/quest/m1/opus-catalog-rate.md +++ /dev/null @@ -1,15 +0,0 @@ -# [XS] Opus catalog rate matches the decoder - -## Goal - -MKV Opus import publishes the codec rate (48 kHz) as the catalog sample rate, -not the OpusHead input rate, which is informational. The catalog describes -what the decoder outputs. - -## Plan - -fMP4 import already does this. Check the other importers that build the -catalog from an OpusHead (FLV and the raw Opus import look similar) and align -them in the same PR. The OpusHead description keeps the input rate. - -Regression: a 44.1 kHz-input OpusHead imports with a 48 kHz catalog rate. diff --git a/rs/moq-mux/src/catalog/msf/consumer.rs b/rs/moq-mux/src/catalog/msf/consumer.rs index c8e2a256a0a..58374e78ecf 100644 --- a/rs/moq-mux/src/catalog/msf/consumer.rs +++ b/rs/moq-mux/src/catalog/msf/consumer.rs @@ -332,8 +332,9 @@ fn derive_from_codec_config(track: &moq_msf::Track, codec: &AudioCodec, init: by if buf.has_remaining() { return Err(Error::OpusTrailingBytes(track.name.clone()).into()); } + // Opus decodes at 48 kHz; the OpusHead rate is informational. Ok(DerivedAudio { - sample_rate: cfg.sample_rate, + sample_rate: 48_000, channel_count: cfg.channel_count, }) } @@ -654,7 +655,7 @@ mod test { let catalog = from_msf::<()>(&msf).expect("Opus OpusHead should parse"); let audio = catalog.audio.renditions.get("audio0").expect("audio0 rendition"); - assert_eq!(audio.sample_rate, 24_000); + assert_eq!(audio.sample_rate, 48_000, "OpusHead rate is informational"); assert_eq!(audio.channel_count, 6); } diff --git a/rs/moq-mux/src/codec/opus/import.rs b/rs/moq-mux/src/codec/opus/import.rs index 69b4631c86f..1f769f94d9f 100644 --- a/rs/moq-mux/src/codec/opus/import.rs +++ b/rs/moq-mux/src/codec/opus/import.rs @@ -112,6 +112,8 @@ impl Import { } /// Build a catalog config from an OpusHead. Errors on a malformed or empty buffer. +/// +/// The catalog rate is the decoder's 48 kHz output, not the OpusHead's informational input rate. pub fn config(init: &[u8]) -> crate::Result { let mut buf = init; let mut config: hang::catalog::AudioConfig = Config::parse(&mut buf)?.into(); @@ -122,12 +124,11 @@ pub fn config(init: &[u8]) -> crate::Result { impl From for hang::catalog::AudioConfig { /// Build a catalog config from a config resolved out of band (e.g. gstreamer caps). + /// + /// The catalog describes the decoder's output: Opus always decodes at 48 kHz, whatever the + /// informational input rate in [`Config::sample_rate`] claims. fn from(config: Config) -> Self { - let mut audio = hang::catalog::AudioConfig::new( - hang::catalog::AudioCodec::Opus, - config.sample_rate, - config.channel_count, - ); + let mut audio = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Opus, 48_000, config.channel_count); audio.description = config.encode().ok(); audio.container = hang::catalog::Container::Legacy; audio @@ -140,6 +141,18 @@ mod tests { use moq_net::Timestamp; + #[test] + fn catalog_rate_is_decoder_rate() { + // A 44.1 kHz input rate is informational; the description keeps it, the catalog does not. + let head = super::Config::new(44_100, 2).encode().unwrap(); + let config = super::config(&head).unwrap(); + assert_eq!(config.sample_rate, 48_000); + assert_eq!(config.description.as_deref(), Some(head.as_ref())); + + let config: hang::catalog::AudioConfig = super::Config::new(44_100, 2).into(); + assert_eq!(config.sample_rate, 48_000); + } + #[tokio::test(start_paused = true)] async fn a_loc_reservation_reaches_the_wire_and_the_catalog() { let mut broadcast = moq_net::broadcast::Info::new().produce(); diff --git a/rs/moq-mux/src/container/flv/import.rs b/rs/moq-mux/src/container/flv/import.rs index d4d7fe267ba..ff7e44555dc 100644 --- a/rs/moq-mux/src/container/flv/import.rs +++ b/rs/moq-mux/src/container/flv/import.rs @@ -428,7 +428,7 @@ impl Import { match packet_type { AUDIO_PACKET_SEQUENCE_START => { let config = match fourcc { - b"Opus" => config_from_opus_head(payload)?, + b"Opus" => crate::codec::opus::config(payload)?, b"mp4a" => config_from_asc(payload)?, // MP3 / AC-3 / E-AC-3 are verbatim with no sequence header; they // configure from the first frame. Anything else is unsupported. @@ -818,15 +818,6 @@ fn config_from_asc(asc_bytes: &[u8]) -> anyhow::Result { Ok(config) } -/// Build an audio config for Opus from an `OpusHead` (RFC 7845) record. -fn config_from_opus_head(head: &[u8]) -> anyhow::Result { - let mut cursor = head; - let cfg = crate::codec::opus::Config::parse(&mut cursor)?; - let mut config = AudioConfig::new(AudioCodec::Opus, cfg.sample_rate, cfg.channel_count); - config.description = Some(Bytes::copy_from_slice(head)); - Ok(config) -} - /// Build an audio config for MP3 from a frame header (config is in band). fn config_from_mp3(frame: &[u8]) -> anyhow::Result { let cfg = crate::codec::mp3::Config::parse(frame)?; diff --git a/rs/moq-mux/src/container/flv/import_test.rs b/rs/moq-mux/src/container/flv/import_test.rs index ceb6a78897c..2073a6886ce 100644 --- a/rs/moq-mux/src/container/flv/import_test.rs +++ b/rs/moq-mux/src/container/flv/import_test.rs @@ -271,7 +271,8 @@ async fn import_enhanced_vp9() { /// header and carries the frames through. #[tokio::test(start_paused = true)] async fn import_enhanced_opus() { - let head = crate::codec::opus::Config::new(48_000, 2).encode().unwrap(); + // A 44.1 kHz input rate is informational; the catalog still reports the decoder's 48 kHz. + let head = crate::codec::opus::Config::new(44_100, 2).encode().unwrap(); let mut out = Vec::new(); out.extend_from_slice(b"FLV"); diff --git a/rs/moq-mux/src/container/mkv/import.rs b/rs/moq-mux/src/container/mkv/import.rs index 0fbf2bb4c30..4f49485c09a 100644 --- a/rs/moq-mux/src/container/mkv/import.rs +++ b/rs/moq-mux/src/container/mkv/import.rs @@ -571,20 +571,18 @@ fn build_audio_config( match codec_id { "A_OPUS" => { - // Codec private is OpusHead. If present, it's authoritative for rate/channels. - let (cfg_rate, cfg_channels) = if let Some(priv_data) = codec_private { - let mut cursor = priv_data.clone(); - let cfg = crate::codec::opus::Config::parse(&mut cursor)?; - (cfg.sample_rate, cfg.channel_count) - } else { - (sample_rate, channels) + // The catalog describes the decoder's output: Opus always decodes at 48 kHz, whatever the + // informational input rate in the OpusHead or SamplingFrequency claims. + let mut config = match codec_private { + Some(head) => { + let mut config = crate::codec::opus::config(head)?; + if config.channel_count == 0 { + config.channel_count = channels; + } + config + } + None => AudioConfig::new(AudioCodec::Opus, 48_000, channels), }; - - let mut config = AudioConfig::new( - AudioCodec::Opus, - if cfg_rate > 0 { cfg_rate } else { sample_rate }, - if cfg_channels > 0 { cfg_channels } else { channels }, - ); config.description = codec_private.cloned(); Ok(config) } diff --git a/rs/moq-mux/src/container/mkv/import_test.rs b/rs/moq-mux/src/container/mkv/import_test.rs index e244513c686..3eebf633ac7 100644 --- a/rs/moq-mux/src/container/mkv/import_test.rs +++ b/rs/moq-mux/src/container/mkv/import_test.rs @@ -305,6 +305,24 @@ fn test_vp9_opus_catalog() { assert_eq!(a.channel_count, 2); } +#[test] +fn test_opus_catalog_rate_is_decoder_rate() { + // A 44.1 kHz input rate is informational; the catalog still reports the decoder's 48 kHz. + let data = MkvBuilder::new() + .header("webm") + .segment_start() + .info(1_000_000) + .tracks(vec![track_entry_audio_opus(1, 44100.0, 2)]) + .cluster(0, || vec![simple_block(1, 0, true, b"opus")]) + .segment_end() + .build(); + + let catalog = run(&data); + let a = catalog.audio.renditions.values().next().unwrap(); + assert_eq!(a.sample_rate, 48000); + assert_eq!(a.channel_count, 2); +} + #[test] fn test_mp3_catalog() { let data = MkvBuilder::new() From a2cf47903464b101e480546a255c43586222b121 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 12:40:14 -0700 Subject: [PATCH 034/128] fix(net): validate complete control message bodies (#4473) Co-authored-by: Codex Co-authored-by: Claude Opus 5.5 --- drafts/draft-lcurley-moq-lite.md | 3 + js/net/src/lite/message.ts | 17 ++++- js/net/src/lite/setup.test.ts | 16 +++++ js/net/src/lite/setup.ts | 7 +- rs/moq-net/src/coding/decode.rs | 10 +++ rs/moq-net/src/coding/reader.rs | 107 +++++++++++++++++++++++++++++++ rs/moq-net/src/coding/varint.rs | 4 +- rs/moq-net/src/ietf/message.rs | 4 +- rs/moq-net/src/lite/message.rs | 17 ++++- rs/moq-net/src/lite/setup.rs | 25 ++++++++ rs/moq-net/src/setup.rs | 62 ++++++++++++++++-- 11 files changed, 258 insertions(+), 14 deletions(-) diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 36bef0581f4..ccec40d32c9 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -718,6 +718,8 @@ Setup Parameter { } ~~~ +The Message Length MUST NOT exceed 65,536 bytes; a receiver MUST treat a longer SETUP as a protocol violation and MAY reject it based on the length prefix alone. + **Parameter Count**: The number of Setup Parameters that follow. @@ -1340,6 +1342,7 @@ The `Message Length` describes the payload size on the wire. - Removed SUBSCRIBE_DROP and its type 0x2; a group without a Group Stream is not counted. - The Subscribe Stream FIN now follows once every counted Group Stream has finished or been reset. - Added announce compression: ANNOUNCE_START gains `Path Base` and `Path Keep` to copy the head of a live advertisement's suffix, and ANNOUNCE_START and ANNOUNCE_UPDATE gain `Hop Base` and `Hop Keep` to copy the tail of a live advertisement's Hop ID list. +- Capped the SETUP Message Length at 65,536 bytes. ## moq-lite-06 diff --git a/js/net/src/lite/message.ts b/js/net/src/lite/message.ts index eb289d6bf77..ba36ab80a7b 100644 --- a/js/net/src/lite/message.ts +++ b/js/net/src/lite/message.ts @@ -1,6 +1,10 @@ import { Reader, Writer } from "../stream.ts"; -export async function encode(writer: Writer, f: (w: Writer) => Promise) { +/** The largest message body either side accepts, matching the Rust implementation. */ +const MAX_SIZE = 64 * 1024 * 1024; + +// Encodes a message with a varint size prefix, refusing a body the peer would reject. +export async function encode(writer: Writer, f: (w: Writer) => Promise, max = MAX_SIZE) { let scratch = new Uint8Array(); const temp = new Writer( @@ -33,15 +37,22 @@ export async function encode(writer: Writer, f: (w: Writer) => Promise) { temp.close(); await temp.closed; + if (scratch.byteLength > max) { + throw new Error(`message too large: ${scratch.byteLength} bytes (max ${max})`); + } + await writer.u53(scratch.byteLength); if (scratch.byteLength > 0) { await writer.write(scratch); } } -// Reads a message with a varint size prefix. -export async function decode(reader: Reader, f: (r: Reader) => Promise): Promise { +// Reads a message with a varint size prefix, refusing an oversized body before reading it. +export async function decode(reader: Reader, f: (r: Reader) => Promise, max = MAX_SIZE): Promise { const size = await reader.u53(); + if (size > max) { + throw new Error(`message too large: ${size} bytes (max ${max})`); + } const data = await reader.read(size); const limit = new Reader(undefined, data); diff --git a/js/net/src/lite/setup.test.ts b/js/net/src/lite/setup.test.ts index 371ebbad780..77d2332ba1a 100644 --- a/js/net/src/lite/setup.test.ts +++ b/js/net/src/lite/setup.test.ts @@ -157,3 +157,19 @@ test("empty path decodes as the root", async () => { test("SETUP rejects a path with malformed UTF-8", async () => { await expect(decodeParam(PARAM_PATH, new Uint8Array([0xc3, 0x28]))).rejects.toThrow(); }); + +test("SETUP encode stops at the 64 KiB receive limit", async () => { + // Count, id, and a 4-byte length varint precede the path. + const atLimit = 64 * 1024 - 6; + const msg = new Setup({ path: "a".repeat(atLimit) }); + expect((await roundTrip(msg)).path).toBe(msg.path); + + const over = new Setup({ path: "a".repeat(atLimit + 1) }); + await expect(bytes((w) => over.encode(w, Version.DRAFT_05))).rejects.toThrow("too large"); +}); + +test("SETUP decode refuses an oversized length before reading the body", async () => { + // Only the prefix is present, so reading the body would fail with a different error. + const prefix = await bytes((w) => w.u53(64 * 1024 + 1)); + await expect(Setup.decode(new Reader(undefined, prefix), Version.DRAFT_05)).rejects.toThrow("too large"); +}); diff --git a/js/net/src/lite/setup.ts b/js/net/src/lite/setup.ts index b49c08d385f..37b724a4d0b 100644 --- a/js/net/src/lite/setup.ts +++ b/js/net/src/lite/setup.ts @@ -24,6 +24,9 @@ const PARAM_HOP = 0x5n; /** Cap on the number of parameters in a bag, matching the Rust decoder. */ const MAX_PARAMS = 64; +/** SETUP only carries negotiation parameters, so it gets a far smaller cap than other messages. */ +const MAX_SETUP_SIZE = 64 * 1024; + /** * The probe capability an endpoint advertises in SETUP. * @@ -265,12 +268,12 @@ export class Setup { /** Encode the SETUP message with its size prefix. Throws on pre-lite-05 versions. */ async encode(w: Writer, version: Version): Promise { Setup.#guard(version); - return Message.encode(w, this.#encode.bind(this)); + return Message.encode(w, this.#encode.bind(this), MAX_SETUP_SIZE); } /** Decode a SETUP message with its size prefix. Throws on pre-lite-05 versions. */ static async decode(r: Reader, version: Version): Promise { Setup.#guard(version); - return Message.decode(r, Setup.#decode); + return Message.decode(r, Setup.#decode, MAX_SETUP_SIZE); } } diff --git a/rs/moq-net/src/coding/decode.rs b/rs/moq-net/src/coding/decode.rs index 13579e73309..57888613548 100644 --- a/rs/moq-net/src/coding/decode.rs +++ b/rs/moq-net/src/coding/decode.rs @@ -83,6 +83,16 @@ pub enum DecodeError { Version, } +impl DecodeError { + /// A complete frame cannot be extended by reading more stream bytes. + pub(crate) fn complete(self) -> Self { + match self { + Self::Short => Self::InvalidValue, + other => other, + } + } +} + impl Decode for bool { fn decode(r: &mut R, version: V) -> Result { match u8::decode(r, version)? { diff --git a/rs/moq-net/src/coding/reader.rs b/rs/moq-net/src/coding/reader.rs index 434e9625511..4d08357d6f6 100644 --- a/rs/moq-net/src/coding/reader.rs +++ b/rs/moq-net/src/coding/reader.rs @@ -410,6 +410,113 @@ mod tests { } } + fn refuses_frame + Debug, V: StreamCodes + Clone>(prefix: &[u8], version: V, oversized: bool) { + let mut reader = Reader::new(Chunks([b"following bytes".as_slice()].into()), version); + reader.buffer.extend_from_slice(prefix); + let mut cx = Context::from_waker(std::task::Waker::noop()); + let result = reader.poll_decode::(&mut cx); + if oversized { + assert!( + matches!( + result, + Poll::Ready(Err(Error::Decode(DecodeError::MessageTooLarge { .. }))) + ), + "{result:?}" + ); + } else { + assert!( + matches!(result, Poll::Ready(Err(Error::Decode(DecodeError::InvalidValue)))), + "{result:?}" + ); + } + assert_eq!(reader.buffer.len(), prefix.len()); + assert_eq!(reader.stream.0.len(), 1, "read past the complete frame"); + } + + #[test] + fn malformed_complete_frames_are_refused() { + use crate::{Version, ietf, lite, setup}; + refuses_frame::(&[0], lite::Version::Lite05, false); + refuses_frame::(&[0], lite::Version::Lite05, false); + refuses_frame::(&[0, 0], ietf::Version::Draft20, false); + for version in [ + Version::Lite(lite::Version::Lite01), + Version::Lite(lite::Version::Lite02), + Version::Ietf(ietf::Version::Draft14), + ] { + let prefix = if version.is_lite() { + &[0x20, 0][..] + } else { + &[0x20, 0, 0][..] + }; + refuses_frame::(prefix, version, false); + let prefix = if version.is_lite() { + &[0x21, 0][..] + } else { + &[0x21, 0, 0][..] + }; + refuses_frame::(prefix, version, false); + } + } + + #[test] + fn oversized_setup_is_refused_at_the_prefix() { + use crate::{Version, lite, setup}; + for version in [lite::Version::Lite01, lite::Version::Lite02] { + for size in [65537u64, (1 << 40) + 1] { + let mut prefix = vec![0x20]; + size.encode(&mut prefix, version).unwrap(); + refuses_frame::(&prefix, Version::Lite(version), true); + prefix[0] = 0x21; + refuses_frame::(&prefix, Version::Lite(version), true); + } + } + for version in [lite::Version::Lite05, lite::Version::Lite06] { + let mut prefix = Vec::new(); + 65537u64.encode(&mut prefix, version).unwrap(); + refuses_frame::(&prefix, version, true); + } + } + + #[test] + fn setup_at_the_limit_waits_for_its_body() { + use crate::{Version, lite, setup}; + for version in [lite::Version::Lite01, lite::Version::Lite02] { + let mut prefix = vec![0x20]; + 65536u64.encode(&mut prefix, version).unwrap(); + assert!(matches!( + setup::Client::decode(&mut prefix.as_slice(), Version::Lite(version)), + Err(DecodeError::Short) + )); + prefix[0] = 0x21; + assert!(matches!( + setup::Server::decode(&mut prefix.as_slice(), Version::Lite(version)), + Err(DecodeError::Short) + )); + } + for version in [lite::Version::Lite05, lite::Version::Lite06] { + let mut prefix = Vec::new(); + 65536u64.encode(&mut prefix, version).unwrap(); + assert!(matches!( + lite::Setup::decode(&mut prefix.as_slice(), version), + Err(DecodeError::Short) + )); + } + } + + #[test] + fn fragmented_setup_waits_for_its_body() { + let mut reader = Reader::new(Chunks([b"\x01".as_slice()].into()), crate::lite::Version::Lite05); + let mut cx = Context::from_waker(std::task::Waker::noop()); + assert!(reader.poll_decode::(&mut cx).is_pending()); + reader.stream.0.push_back(b"\x00"); + assert!(matches!( + reader.poll_decode::(&mut cx), + Poll::Ready(Ok(_)) + )); + assert!(reader.buffer.is_empty()); + } + /// A consumer parked on the group cannot run until this task yields, so a burst of /// chunks owes exactly one wake: at the boundary, from whoever wrote them. Every /// other exit hands the wake to the caller's `finish` or `abort`. diff --git a/rs/moq-net/src/coding/varint.rs b/rs/moq-net/src/coding/varint.rs index a9339771747..e51180d531d 100644 --- a/rs/moq-net/src/coding/varint.rs +++ b/rs/moq-net/src/coding/varint.rs @@ -536,7 +536,9 @@ where VarInt: Decode, { fn decode(r: &mut R, version: V) -> Result { - VarInt::decode(r, version).map(|v| v.into_inner() as usize) + // Truncating on 32-bit targets (wasm32) would let an oversized length pass a size cap. + let v = VarInt::decode(r, version)?; + v.into_inner().try_into().map_err(|_| DecodeError::BoundsExceeded) } } diff --git a/rs/moq-net/src/ietf/message.rs b/rs/moq-net/src/ietf/message.rs index 4bf95248df7..3dad0df82f1 100644 --- a/rs/moq-net/src/ietf/message.rs +++ b/rs/moq-net/src/ietf/message.rs @@ -38,7 +38,7 @@ impl Decode for T { } let raw = buf.copy_to_bytes(size); let mut slice = &raw[..]; - match Self::decode_msg(&mut slice, version) { + match Self::decode_msg(&mut slice, version).map_err(DecodeError::complete) { Ok(result) => { if slice.remaining() > 0 { return Err(DecodeError::Long); @@ -56,7 +56,7 @@ impl Decode for T { return Err(DecodeError::Short); } let mut limited = buf.take(size); - match Self::decode_msg(&mut limited, version) { + match Self::decode_msg(&mut limited, version).map_err(DecodeError::complete) { Ok(result) => { if limited.remaining() > 0 { return Err(DecodeError::Long); diff --git a/rs/moq-net/src/lite/message.rs b/rs/moq-net/src/lite/message.rs index 0d28eb735f6..c3c0ceb61a9 100644 --- a/rs/moq-net/src/lite/message.rs +++ b/rs/moq-net/src/lite/message.rs @@ -23,6 +23,9 @@ pub(super) fn decode_size(buf: &mut B, version: Version) -> Result(&self, w: &mut W, version: Version) -> Result<(), EncodeError>; @@ -35,6 +38,10 @@ impl Encode for T { tracing::trace!(?self, "encoding"); let mut sizer = Sizer::default(); self.encode_msg(&mut sizer, version)?; + // Never emit a body our own receiver would refuse. + if sizer.size > Self::MAX_SIZE { + return Err(EncodeError::TooLarge); + } sizer.size.encode(w, version)?; self.encode_msg(w, version) } @@ -43,6 +50,12 @@ impl Encode for T { impl Decode for T { fn decode(buf: &mut B, version: Version) -> Result { let size = decode_size(buf, version)?; + if size > Self::MAX_SIZE { + return Err(DecodeError::MessageTooLarge { + size, + max: Self::MAX_SIZE, + }); + } if tracing::enabled!(tracing::Level::TRACE) { if buf.remaining() < size { @@ -50,7 +63,7 @@ impl Decode for T { } let raw = buf.copy_to_bytes(size); let mut slice = &raw[..]; - match Self::decode_msg(&mut slice, version) { + match Self::decode_msg(&mut slice, version).map_err(DecodeError::complete) { Ok(result) => { if slice.remaining() > 0 { return Err(DecodeError::Long); @@ -68,7 +81,7 @@ impl Decode for T { return Err(DecodeError::Short); } let mut limited = buf.take(size); - match Self::decode_msg(&mut limited, version) { + match Self::decode_msg(&mut limited, version).map_err(DecodeError::complete) { Ok(result) => { if limited.remaining() > 0 { return Err(DecodeError::Long); diff --git a/rs/moq-net/src/lite/setup.rs b/rs/moq-net/src/lite/setup.rs index 51225882cd2..c3868614e9e 100644 --- a/rs/moq-net/src/lite/setup.rs +++ b/rs/moq-net/src/lite/setup.rs @@ -185,6 +185,8 @@ pub struct Setup { } impl Message for Setup { + const MAX_SIZE: usize = crate::setup::MAX_SETUP_SIZE; + fn decode_msg(r: &mut R, version: Version) -> Result { if !version.has_setup_stream() { return Err(DecodeError::Version); @@ -363,6 +365,29 @@ mod tests { } } + /// Never emit a SETUP our own receiver would refuse. + #[test] + fn encode_enforces_the_setup_limit() { + // Count, id, and a 4-byte length varint precede the path. + let at_limit = crate::setup::MAX_SETUP_SIZE - 6; + let msg = Setup { + path: Some("a".repeat(at_limit)), + ..Default::default() + }; + assert_eq!(round_trip(&msg), msg); + + let msg = Setup { + path: Some("a".repeat(at_limit + 1)), + ..Default::default() + }; + let mut buf = bytes::BytesMut::new(); + assert!(matches!( + msg.encode(&mut buf, Version::Lite05), + Err(EncodeError::TooLarge) + )); + assert!(buf.is_empty()); + } + #[test] fn path_round_trip() { let msg = Setup { diff --git a/rs/moq-net/src/setup.rs b/rs/moq-net/src/setup.rs index 3a4a96cba09..24caaffebb7 100644 --- a/rs/moq-net/src/setup.rs +++ b/rs/moq-net/src/setup.rs @@ -10,6 +10,9 @@ use crate::{ ietf, lite, }; +// SETUP only carries negotiation parameters. Bound it independently of control messages. +pub(crate) const MAX_SETUP_SIZE: usize = 64 * 1024; + const CLIENT_SETUP: u8 = 0x20; const SERVER_SETUP: u8 = 0x21; @@ -72,6 +75,7 @@ impl Decode for Setup { if kind != SETUP_V17 { return Err(DecodeError::InvalidValue); } + // The fixed u16 length is already below MAX_SETUP_SIZE. let size = u16::decode(r, v)? as usize; if r.remaining() < size { return Err(DecodeError::Short); @@ -145,10 +149,17 @@ impl Decode for Client { let size = match SetupVersion::from_version(v) { SetupVersion::Draft14 | SetupVersion::Draft15Plus => u16::decode(r, v)? as usize, - SetupVersion::LiteLegacy => u64::decode(r, v)? as usize, + SetupVersion::LiteLegacy => usize::decode(r, v)?, SetupVersion::Modern | SetupVersion::Unsupported => return Err(DecodeError::Version), }; + if size > MAX_SETUP_SIZE { + return Err(DecodeError::MessageTooLarge { + size, + max: MAX_SETUP_SIZE, + }); + } + if r.remaining() < size { return Err(DecodeError::Short); } @@ -160,7 +171,9 @@ impl Decode for Client { // Draft15+: no versions list, parameters only. coding::Versions::from([v.into()]) } - SetupVersion::Draft14 | SetupVersion::LiteLegacy => coding::Versions::decode(&mut msg, v)?, + SetupVersion::Draft14 | SetupVersion::LiteLegacy => { + coding::Versions::decode(&mut msg, v).map_err(DecodeError::complete)? + } SetupVersion::Modern | SetupVersion::Unsupported => return Err(DecodeError::Version), }; @@ -179,6 +192,9 @@ impl Encode for Client { let mut sizer = Sizer::default(); self.encode_inner(&mut sizer, v)?; let size = sizer.size; + if size > MAX_SETUP_SIZE { + return Err(EncodeError::TooLarge); + } match SetupVersion::from_version(v) { SetupVersion::Draft14 | SetupVersion::Draft15Plus => { @@ -226,6 +242,9 @@ impl Encode for Server { let mut sizer = Sizer::default(); self.encode_inner(&mut sizer, v)?; let size = sizer.size; + if size > MAX_SETUP_SIZE { + return Err(EncodeError::TooLarge); + } match SetupVersion::from_version(v) { SetupVersion::Draft14 | SetupVersion::Draft15Plus => { @@ -249,10 +268,17 @@ impl Decode for Server { let size = match SetupVersion::from_version(v) { SetupVersion::Draft14 | SetupVersion::Draft15Plus => u16::decode(r, v)? as usize, - SetupVersion::LiteLegacy => u64::decode(r, v)? as usize, + SetupVersion::LiteLegacy => usize::decode(r, v)?, SetupVersion::Modern | SetupVersion::Unsupported => return Err(DecodeError::Version), }; + if size > MAX_SETUP_SIZE { + return Err(DecodeError::MessageTooLarge { + size, + max: MAX_SETUP_SIZE, + }); + } + if r.remaining() < size { return Err(DecodeError::Short); } @@ -260,7 +286,9 @@ impl Decode for Server { let mut msg = r.copy_to_bytes(size); let version = match SetupVersion::from_version(v) { SetupVersion::Draft15Plus => v.into(), - SetupVersion::Draft14 | SetupVersion::LiteLegacy => coding::Version::decode(&mut msg, v)?, + SetupVersion::Draft14 | SetupVersion::LiteLegacy => { + coding::Version::decode(&mut msg, v).map_err(DecodeError::complete)? + } SetupVersion::Modern | SetupVersion::Unsupported => return Err(DecodeError::Version), }; @@ -270,3 +298,29 @@ impl Decode for Server { }) } } + +#[cfg(test)] +mod tests { + use super::*; + + /// Never emit a legacy SETUP our own receiver would refuse. + #[test] + fn encode_enforces_the_setup_limit() { + let v = Version::Lite(lite::Version::Lite01); + let parameters = Bytes::from(vec![0; MAX_SETUP_SIZE]); + + let client = Client { + versions: coding::Versions::from([v.into()]), + parameters: parameters.clone(), + }; + let mut buf = Vec::new(); + assert!(matches!(client.encode(&mut buf, v), Err(EncodeError::TooLarge))); + + let server = Server { + version: v.into(), + parameters, + }; + let mut buf = Vec::new(); + assert!(matches!(server.encode(&mut buf, v), Err(EncodeError::TooLarge))); + } +} From 877cf55d7a82c8ec76f74361fe5549a0b02f1944 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 12:58:35 -0700 Subject: [PATCH 035/128] fix(rtc): redact WHIP and WHEP client URLs in logs (#4457) Co-authored-by: Claude Sonnet 5.5 --- Cargo.lock | 1 + rs/moq-rtc/Cargo.toml | 4 +++- rs/moq-rtc/src/client/mod.rs | 29 +++++++++++++++++++++++++++++ rs/moq-rtc/src/client/whep.rs | 3 ++- rs/moq-rtc/src/client/whip.rs | 3 ++- rs/moq-rtc/src/error.rs | 4 +++- rs/moq-rtc/src/lib.rs | 16 ++++++++++++++-- 7 files changed, 54 insertions(+), 6 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 32884ac4e37..4bc985f478c 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4680,6 +4680,7 @@ dependencies = [ "thiserror 2.0.21", "tokio", "tracing", + "tracing-test", "url", "uuid", ] diff --git a/rs/moq-rtc/Cargo.toml b/rs/moq-rtc/Cargo.toml index 6317324ae85..350c4cd9525 100644 --- a/rs/moq-rtc/Cargo.toml +++ b/rs/moq-rtc/Cargo.toml @@ -28,6 +28,8 @@ bytes = { workspace = true } hang = { workspace = true } moq-mux = { workspace = true } moq-net = { workspace = true } +# `RedactedUrl` keeps a dialed URL's query token and userinfo out of the logs. +moq-tokio = { workspace = true } reqwest = { workspace = true, features = ["rustls"] } str0m = "0.23" thiserror = { workspace = true } @@ -40,5 +42,5 @@ uuid = { version = "1", features = ["v4"] } # Signs the MESSAGE-INTEGRITY on a forged STUN binding request: str0m rejects a # request without one, and its own SHA1 provider is private. aws-lc-rs = { workspace = true } -moq-tokio = { path = "../moq-tokio", default-features = false } tokio = { workspace = true, features = ["test-util"] } +tracing-test = { workspace = true } diff --git a/rs/moq-rtc/src/client/mod.rs b/rs/moq-rtc/src/client/mod.rs index ceda32cbd35..80ea5899c45 100644 --- a/rs/moq-rtc/src/client/mod.rs +++ b/rs/moq-rtc/src/client/mod.rs @@ -87,3 +87,32 @@ impl Client { whip::dial(self, url, origin, path).await } } + +#[cfg(test)] +mod tests { + use super::*; + + #[tokio::test] + async fn http_error_redacts_url() { + // A freed port refuses the connection, so reqwest fails with the dialed URL attached. + let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("bind"); + let address = listener.local_addr().expect("local address"); + drop(listener); + + let origin = moq_tokio::origin::spawn(); + let broadcast = origin.create_broadcast("test").expect("create broadcast"); + let url = format!("http://user:pass@{address}/whep/test?jwt=secret") + .parse() + .expect("WHEP URL"); + let err = Client::new(Config::default()) + .subscribe(url, broadcast) + .await + .expect_err("dial a closed port"); + + assert!(matches!(err, crate::Error::Http(_)), "unexpected error: {err}"); + let printed = format!("{err} {err:?}"); + for secret in ["jwt", "secret", "user:pass"] { + assert!(!printed.contains(secret), "error leaked {secret}: {printed}"); + } + } +} diff --git a/rs/moq-rtc/src/client/whep.rs b/rs/moq-rtc/src/client/whep.rs index c1a3e764bcb..aeb97436227 100644 --- a/rs/moq-rtc/src/client/whep.rs +++ b/rs/moq-rtc/src/client/whep.rs @@ -56,7 +56,8 @@ pub(crate) async fn dial(client: &Client, url: Url, broadcast: moq_net::broadcas let answer = SdpAnswer::from_sdp_string(&body).map_err(|err| Error::InvalidSdp(err.to_string()))?; rtc.sdp_api().accept_answer(pending, answer).map_err(Error::rtc)?; - tracing::info!(%url, "whep client connected"); + // The URL routinely carries the auth token in its query, or userinfo. + tracing::info!(url = %moq_tokio::RedactedUrl::new(&url), "whep client connected"); // 1:1 socket (no demux on the client): pump its datagrams into the session. // The session tags each datagram with the advertised candidate matching its diff --git a/rs/moq-rtc/src/client/whip.rs b/rs/moq-rtc/src/client/whip.rs index 2e02db0a8de..a483ea024ea 100644 --- a/rs/moq-rtc/src/client/whip.rs +++ b/rs/moq-rtc/src/client/whip.rs @@ -71,7 +71,8 @@ pub(crate) async fn dial( let answer = SdpAnswer::from_sdp_string(&body).map_err(|err| Error::InvalidSdp(err.to_string()))?; rtc.sdp_api().accept_answer(pending, answer).map_err(Error::rtc)?; - tracing::info!(%url, "whip client connected"); + // The URL routinely carries the auth token in its query, or userinfo. + tracing::info!(url = %moq_tokio::RedactedUrl::new(&url), "whip client connected"); // 1:1 socket (no demux on the client): pump its datagrams into the session. // The session tags each datagram with the advertised candidate matching its diff --git a/rs/moq-rtc/src/error.rs b/rs/moq-rtc/src/error.rs index 76faaf58323..e36cf3a7131 100644 --- a/rs/moq-rtc/src/error.rs +++ b/rs/moq-rtc/src/error.rs @@ -73,7 +73,9 @@ pub enum Error { impl From for Error { fn from(err: reqwest::Error) -> Self { - Self::Http(std::sync::Arc::new(err)) + // reqwest prints the full URL in its error, and a dialed URL routinely + // carries the auth token in its query, or userinfo. + Self::Http(std::sync::Arc::new(err.without_url())) } } diff --git a/rs/moq-rtc/src/lib.rs b/rs/moq-rtc/src/lib.rs index 127fcf37496..1285c95e3ff 100644 --- a/rs/moq-rtc/src/lib.rs +++ b/rs/moq-rtc/src/lib.rs @@ -85,6 +85,7 @@ mod tests { const OPUS_PACKET: &[u8] = &[0xfc, 0xff, 0xfe]; #[tokio::test] + #[tracing_test::traced_test] async fn whip_and_whep_round_trip_opus() { let source_origin = moq_tokio::origin::spawn(); let source_consumer = source_origin.consume(); @@ -126,7 +127,10 @@ mod tests { let http = tokio::spawn(async move { axum::serve(listener, app).await.expect("serve HTTP") }); let client = Client::new(client::Config::default()); - let whip = format!("http://{address}/whip/ingested").parse().expect("WHIP URL"); + // Credentials in the dialed URLs must never reach the client's connect logs. + let whip = format!("http://user:pass@{address}/whip/ingested?jwt=secret") + .parse() + .expect("WHIP URL"); tokio::time::timeout(TIMEOUT, client.publish(whip, source_consumer, "source")) .await .expect("WHIP negotiation timed out") @@ -137,12 +141,20 @@ mod tests { .create_broadcast("output") .expect("create output broadcast"); let output_consumer = output.consume(); - let whep = format!("http://{address}/whep/ingested").parse().expect("WHEP URL"); + let whep = format!("http://user:pass@{address}/whep/ingested?jwt=secret") + .parse() + .expect("WHEP URL"); tokio::time::timeout(TIMEOUT, client.subscribe(whep, output)) .await .expect("WHEP negotiation timed out") .expect("WHEP negotiation failed"); + assert!(logs_contain("whip client connected")); + assert!(logs_contain("whep client connected")); + for secret in ["jwt", "secret", "user:pass"] { + assert!(!logs_contain(secret), "client logs leaked {secret}"); + } + let catalog_track = output_consumer .track(hang::Catalog::DEFAULT_NAME) .expect("output catalog track") From 16875d620b4ac8a682a272cba21707052ab936f7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 13:03:08 -0700 Subject: [PATCH 036/128] fix(rtmp): bound AMF0 nesting (#4471) Co-authored-by: GPT-6 Co-authored-by: Claude Opus 5.5 --- Cargo.lock | 11 - rs/moq-rtmp/Cargo.toml | 3 +- rs/moq-rtmp/src/lib.rs | 4 +- rs/moq-rtmp/src/rml/amf0/deserialization.rs | 336 ++++++++++++++++++ rs/moq-rtmp/src/rml/amf0/errors.rs | 49 +++ rs/moq-rtmp/src/rml/amf0/mod.rs | 67 ++++ rs/moq-rtmp/src/rml/amf0/serialization.rs | 235 ++++++++++++ .../rml/chunk_io/deserialization_errors.rs | 6 +- rs/moq-rtmp/src/rml/chunk_io/deserializer.rs | 14 +- .../rml/messages/deserialization_errors.rs | 2 +- .../src/rml/messages/message_payload.rs | 2 +- rs/moq-rtmp/src/rml/messages/mod.rs | 2 +- .../src/rml/messages/serialization_errors.rs | 2 +- .../src/rml/messages/types/amf0_command.rs | 18 +- .../src/rml/messages/types/amf0_data.rs | 16 +- rs/moq-rtmp/src/rml/mod.rs | 6 +- rs/moq-rtmp/src/rml/sessions/client/events.rs | 2 +- rs/moq-rtmp/src/rml/sessions/client/mod.rs | 2 +- rs/moq-rtmp/src/rml/sessions/client/tests.rs | 2 +- rs/moq-rtmp/src/rml/sessions/mod.rs | 2 +- rs/moq-rtmp/src/rml/sessions/server/events.rs | 2 +- rs/moq-rtmp/src/rml/sessions/server/mod.rs | 2 +- rs/moq-rtmp/src/rml/sessions/server/tests.rs | 83 ++++- rs/moq-rtmp/src/server.rs | 2 +- 24 files changed, 818 insertions(+), 52 deletions(-) create mode 100644 rs/moq-rtmp/src/rml/amf0/deserialization.rs create mode 100644 rs/moq-rtmp/src/rml/amf0/errors.rs create mode 100644 rs/moq-rtmp/src/rml/amf0/mod.rs create mode 100644 rs/moq-rtmp/src/rml/amf0/serialization.rs diff --git a/Cargo.lock b/Cargo.lock index 4bc985f478c..c783e53591f 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4699,7 +4699,6 @@ dependencies = [ "moq-net", "moq-tokio", "rand 0.10.3", - "rml_amf0", "rustls", "sha2", "socket2 0.6.5", @@ -7294,16 +7293,6 @@ dependencies = [ "portable-atomic-util", ] -[[package]] -name = "rml_amf0" -version = "0.3.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "63551cfcd4d1f42733c190e4b58dd268b1eacb73410d9afbf62784aa12cac240" -dependencies = [ - "byteorder", - "thiserror 1.0.69", -] - [[package]] name = "rsa" version = "0.9.10" diff --git a/rs/moq-rtmp/Cargo.toml b/rs/moq-rtmp/Cargo.toml index 1057d73d9db..581afd698cf 100644 --- a/rs/moq-rtmp/Cargo.toml +++ b/rs/moq-rtmp/Cargo.toml @@ -4,7 +4,7 @@ description = "RTMP / enhanced-RTMP contribution ingest gateway for Media over Q authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" # Our own code is MIT OR Apache-2.0. The vendored `src/rml/` module is a fork of -# rml_rtmp (MIT only, Copyright (c) 2017 Matthew Shapiro); its notice ships in +# rml_rtmp and rml_amf0 (MIT only, Copyright (c) 2017 Matthew Shapiro); its notice ships in # src/rml/LICENSE and applies to that module regardless of which option you pick. license = "MIT OR Apache-2.0" @@ -38,7 +38,6 @@ hmac = "0.13" moq-mux = { workspace = true } moq-net = { workspace = true } rand = { workspace = true } -rml_amf0 = "0.3" rustls = { version = "0.23", default-features = false, features = ["aws-lc-rs"], optional = true } sha2 = "0.11" # TCP keepalive on accepted sockets, so a half-open connection (a peer that diff --git a/rs/moq-rtmp/src/lib.rs b/rs/moq-rtmp/src/lib.rs index 7c29c938d17..1dac15e4cae 100644 --- a/rs/moq-rtmp/src/lib.rs +++ b/rs/moq-rtmp/src/lib.rs @@ -63,7 +63,7 @@ //! reaps a play session whose viewer vanished without closing. //! //! Pure Rust: the RTMP handshake, chunk codec, and session state machine live in -//! the vendored `rml` module (a fork of `rml_rtmp`), with no librtmp or ffmpeg +//! the vendored `rml` module (forks of `rml_rtmp` and `rml_amf0`), with no librtmp or ffmpeg //! dependency. #![warn(missing_docs)] @@ -74,7 +74,7 @@ mod dial; mod error; mod flv; mod listen; -// Vendored fork of rml_rtmp; see the module docs. +// Vendored forks of rml_rtmp and rml_amf0; see the module docs. mod rml; mod server; diff --git a/rs/moq-rtmp/src/rml/amf0/deserialization.rs b/rs/moq-rtmp/src/rml/amf0/deserialization.rs new file mode 100644 index 00000000000..8b7033323a6 --- /dev/null +++ b/rs/moq-rtmp/src/rml/amf0/deserialization.rs @@ -0,0 +1,336 @@ +//! This module contains functionality to deserialize values from bytes +//! that were encoded via the AMF0 specification +//! (http://wwwimages.adobe.com/content/dam/Adobe/en/devnet/amf/pdf/amf0-file-format-specification.pdf) + +use super::Amf0Value; +use super::errors::Amf0DeserializationError; +use super::markers; +use byteorder::{BigEndian, ReadBytesExt}; +use std::collections::HashMap; +use std::io::Read; + +struct ObjectProperty { + label: String, + value: Amf0Value, +} + +/// Turns any readable byte stream and converts it into an array of AMF0 values +pub fn deserialize(bytes: &mut R) -> Result, Amf0DeserializationError> { + let mut results = vec![]; + + loop { + match read_next_value(bytes, 0)? { + Some(x) => results.push(x), + None => break, + }; + } + + Ok(results) +} + +fn read_next_value(bytes: &mut R, depth: usize) -> Result, Amf0DeserializationError> { + let mut buffer: [u8; 1] = [0]; + let bytes_read = bytes.read(&mut buffer)?; + + if bytes_read == 0 { + return Ok(None); + } + + if buffer[0] == markers::OBJECT_END_MARKER { + return Ok(None); + } + + // Count containers, allowing scalar leaves inside the 64th container. + if matches!( + buffer[0], + markers::OBJECT_MARKER | markers::ECMA_ARRAY_MARKER | markers::STRICT_ARRAY_MARKER + ) && depth >= 64 + { + return Err(Amf0DeserializationError::MaxDepthExceeded); + } + + match buffer[0] { + markers::BOOLEAN_MARKER => parse_bool(bytes).map(Some), + markers::NULL_MARKER => parse_null().map(Some), + markers::UNDEFINED_MARKER => parse_undefined().map(Some), + markers::NUMBER_MARKER => parse_number(bytes).map(Some), + markers::OBJECT_MARKER => parse_object(bytes, depth + 1).map(Some), + markers::ECMA_ARRAY_MARKER => parse_ecma_array(bytes, depth + 1).map(Some), + markers::STRING_MARKER => parse_string(bytes).map(Some), + markers::STRICT_ARRAY_MARKER => parse_strict_array(bytes, depth + 1).map(Some), + _ => Err(Amf0DeserializationError::UnknownMarker { marker: buffer[0] }), + } +} + +fn parse_number(bytes: &mut R) -> Result { + let number = bytes.read_f64::()?; + let value = Amf0Value::Number(number); + + Ok(value) +} + +fn parse_null() -> Result { + Ok(Amf0Value::Null) +} + +fn parse_undefined() -> Result { + Ok(Amf0Value::Undefined) +} + +fn parse_bool(bytes: &mut R) -> Result { + let value = bytes.read_u8()?; + + if value == 1 { + Ok(Amf0Value::Boolean(true)) + } else { + Ok(Amf0Value::Boolean(false)) + } +} + +fn parse_string(bytes: &mut R) -> Result { + let length = bytes.read_u16::()?; + let mut buffer: Vec = vec![0_u8; length as usize]; + bytes.read(&mut buffer)?; + + let value = String::from_utf8(buffer)?; + Ok(Amf0Value::Utf8String(value)) +} + +fn parse_object(bytes: &mut R, depth: usize) -> Result { + let mut properties = HashMap::new(); + + loop { + match parse_object_property(bytes, depth)? { + Some(property) => properties.insert(property.label, property.value), + None => break, + }; + } + + let deserialized_value = Amf0Value::Object(properties); + Ok(deserialized_value) +} + +fn parse_ecma_array(bytes: &mut R, depth: usize) -> Result { + // An ECMA array is an array of values indexed via strings instead of numeric indexes (so + // essentially a hash map). It seems functionally equivalent to an object so for simplicity + // treat it as such. + + // While the spec says it gives you the count of items in the array, it is vague about if + // the object end marker is used. In real world usages I have found the associative array + // actually ends with a 0x000009 ending (same as objects do). If we don't consume this + // then the buffer will start at that ending and funky things will happen. So for now it seems + // like we can ignore the associative count and just read exactly as we would an object. + + let _associative_count = bytes.read_u32::()?; + parse_object(bytes, depth) +} + +fn parse_strict_array(bytes: &mut R, depth: usize) -> Result { + let _array_count = bytes.read_u32::()?; + let mut values: Vec = Vec::new(); + + for _ in 0.._array_count { + match read_next_value(bytes, depth)? { + Some(value) => { + values.push(value); + } + None => break, + }; + } + + Ok(Amf0Value::StrictArray(values)) +} + +fn parse_object_property( + bytes: &mut R, + depth: usize, +) -> Result, Amf0DeserializationError> { + let label_length = bytes.read_u16::()?; + if label_length == 0 { + // Next byte should be the end of object marker. We need to read this + // to make sure we progress the current position. + let byte = bytes.read_u8()?; + if byte != markers::OBJECT_END_MARKER { + return Err(Amf0DeserializationError::UnexpectedEmptyObjectPropertyName); + } + + return Ok(None); + } + + let mut label_buffer = vec![0; label_length as usize]; + bytes.read(&mut label_buffer)?; + + let label = String::from_utf8(label_buffer)?; + + match read_next_value(bytes, depth)? { + None => Err(Amf0DeserializationError::UnexpectedEof), + Some(property_value) => Ok(Some(ObjectProperty { + label, + value: property_value, + })), + } +} + +#[cfg(test)] +mod tests { + use super::super::Amf0Value; + use super::super::markers; + use super::deserialize; + use byteorder::{BigEndian, WriteBytesExt}; + use std::collections::HashMap; + use std::io::Cursor; + + #[test] + fn can_deserialize_strict_array() { + let mut vector = vec![]; + vector.push(markers::STRICT_ARRAY_MARKER); + vector.write_u32::(2).unwrap(); + vector.push(markers::NUMBER_MARKER); + vector.write_f64::(1.0).unwrap(); + vector.push(markers::NUMBER_MARKER); + vector.write_f64::(2.0).unwrap(); + + let mut input = Cursor::new(vector); + let result = deserialize(&mut input).unwrap(); + + let mut array = Vec::new(); + + array.push(Amf0Value::Number(1.0)); + array.push(Amf0Value::Number(2.0)); + + let expected = vec![Amf0Value::StrictArray(array)]; + assert_eq!(result, expected); + } + + #[test] + fn can_deserialize_number() { + let number: f64 = 332.0; + + let mut vector = vec![]; + vector.write_u8(markers::NUMBER_MARKER).unwrap(); + vector.write_f64::(number).unwrap(); + + let mut input = Cursor::new(vector); + let result = deserialize(&mut input).unwrap(); + + let expected = vec![Amf0Value::Number(number)]; + assert_eq!(result, expected); + } + + #[test] + fn can_deserialize_true_boolean() { + let mut vector = vec![]; + vector.write_u8(markers::BOOLEAN_MARKER).unwrap(); + vector.write_u8(1).unwrap(); + + let mut input = Cursor::new(vector); + let result = deserialize(&mut input).unwrap(); + + let expected = vec![Amf0Value::Boolean(true)]; + assert_eq!(result, expected); + } + + #[test] + fn can_deserialize_false_boolean() { + let mut vector = vec![]; + vector.write_u8(markers::BOOLEAN_MARKER).unwrap(); + vector.write_u8(0).unwrap(); + + let mut input = Cursor::new(vector); + let result = deserialize(&mut input).unwrap(); + + let expected = vec![Amf0Value::Boolean(false)]; + assert_eq!(result, expected); + } + + #[test] + fn can_deserialize_string() { + let value = "test"; + + let mut vector = vec![]; + vector.write_u8(markers::STRING_MARKER).unwrap(); + vector.write_u16::(value.len() as u16).unwrap(); + vector.extend(value.as_bytes()); + + let mut input = Cursor::new(vector); + let result = deserialize(&mut input).unwrap(); + + let expected = vec![Amf0Value::Utf8String(value.to_string())]; + assert_eq!(result, expected); + } + + #[test] + fn can_deserialize_null() { + let mut vector = vec![]; + vector.write_u8(markers::NULL_MARKER).unwrap(); + + let mut input = Cursor::new(vector); + let result = deserialize(&mut input).unwrap(); + + let expected = vec![Amf0Value::Null]; + assert_eq!(result, expected); + } + + #[test] + fn can_deserialize_object() { + const NUMBER: f64 = 332.0; + + let mut vector = vec![]; + vector.push(markers::OBJECT_MARKER); + vector.write_u16::(4).unwrap(); + vector.extend("test".as_bytes()); + vector.push(markers::NUMBER_MARKER); + vector.write_f64::(NUMBER).unwrap(); + vector.write_u16::(markers::UTF_8_EMPTY_MARKER).unwrap(); + vector.push(markers::OBJECT_END_MARKER); + + let mut input = Cursor::new(vector); + let result = deserialize(&mut input).unwrap(); + + let mut properties = HashMap::new(); + properties.insert("test".to_string(), Amf0Value::Number(NUMBER)); + + let expected = vec![Amf0Value::Object(properties)]; + assert_eq!(result, expected); + } + + #[test] + fn can_deserialize_emca_array() { + let mut vector = vec![]; + vector.push(markers::ECMA_ARRAY_MARKER); + vector.write_u32::(2).unwrap(); + vector.write_u16::(5).unwrap(); + vector.extend("test1".as_bytes()); + vector.push(markers::NUMBER_MARKER); + vector.write_f64::(1.0).unwrap(); + vector.write_u16::(5).unwrap(); + vector.extend("test2".as_bytes()); + vector.write_u8(markers::STRING_MARKER).unwrap(); + vector.write_u16::(6).unwrap(); + vector.extend("second".as_bytes()); + vector.write_u16::(markers::UTF_8_EMPTY_MARKER).unwrap(); + vector.push(markers::OBJECT_END_MARKER); + + let mut input = Cursor::new(vector); + let result = deserialize(&mut input).unwrap(); + + let mut properties = HashMap::new(); + properties.insert("test1".to_string(), Amf0Value::Number(1.0)); + properties.insert("test2".to_string(), Amf0Value::Utf8String("second".to_string())); + + let expected = vec![Amf0Value::Object(properties)]; + assert_eq!(result, expected); + } + + #[test] + fn can_deserialize_undefined() { + let mut vector = vec![]; + vector.write_u8(markers::UNDEFINED_MARKER).unwrap(); + + let mut input = Cursor::new(vector); + let result = deserialize(&mut input).unwrap(); + + let expected = vec![Amf0Value::Undefined]; + assert_eq!(result, expected); + } +} diff --git a/rs/moq-rtmp/src/rml/amf0/errors.rs b/rs/moq-rtmp/src/rml/amf0/errors.rs new file mode 100644 index 00000000000..29ebb9ce70f --- /dev/null +++ b/rs/moq-rtmp/src/rml/amf0/errors.rs @@ -0,0 +1,49 @@ +use std::{io, string}; +use thiserror::Error; + +/// Errors that can occur during the deserialization process +#[derive(Debug, Error)] +pub enum Amf0DeserializationError { + /// Container nesting exceeds the decoder limit. + #[error("AMF0 nesting exceeds 64 levels")] + MaxDepthExceeded, + + /// Every Amf0 value starts with a marker byte describing the type of value that was + /// encoded. For example a marker of `0x00` is a number, `0x01` is a string, etc.. + /// + /// This error is encountered when we see a maker value that we do not recognize. + #[error("Encountered unknown marker: {marker}")] + UnknownMarker { marker: u8 }, + + /// Object properties consist of a name and value pair. It is expected that every property + /// has a valid string name, and if the name is empty this error is raised. + #[error("Unexpected empty object property name")] + UnexpectedEmptyObjectPropertyName, + + /// This occurs when we are expecting more data but hit the end of the buffer + /// (e.g. we are reading an object property but there was no property value). + #[error("Hit end of the byte buffer but was expecting more data")] + UnexpectedEof, + + /// An I/O Error occurred while reading the data buffer + #[error("Failed to read byte buffer: {0}")] + BufferReadError(#[from] io::Error), + + /// Strings in AMF0 are UTF-8 encoded, so if the bytes read are not valid + /// UTF-8 this error will be raised. + #[error("Failed to read a utf8 string from the byte buffer: {0}")] + StringParseError(#[from] string::FromUtf8Error), +} + +/// Errors raised during to the serialization process +#[derive(Debug, Error)] +pub enum Amf0SerializationError { + /// Amf0 strings cannot be more than 65,535 characters, so if a string was provided + /// with a larger length than this than this error is raised. + #[error("String length greater than 65,535")] + NormalStringTooLong, + + /// An I/O error occurred while writing to the output buffer. + #[error("Failed to write to byte buffer")] + BufferWriteError(#[from] io::Error), +} diff --git a/rs/moq-rtmp/src/rml/amf0/mod.rs b/rs/moq-rtmp/src/rml/amf0/mod.rs new file mode 100644 index 00000000000..defba01a3d5 --- /dev/null +++ b/rs/moq-rtmp/src/rml/amf0/mod.rs @@ -0,0 +1,67 @@ +//! AMF0 codec vendored from rml_amf0 0.3.0 (MIT, Matthew Shapiro). +//! See ../LICENSE. Container nesting is limited to 64 levels when decoding. + +mod deserialization; +mod errors; +mod serialization; + +pub use deserialization::deserialize; +pub use errors::{Amf0DeserializationError, Amf0SerializationError}; +pub use serialization::serialize; + +use std::collections::HashMap; + +/// An Enum representing the different supported types of Amf0 values +#[derive(PartialEq, Debug, Clone)] +pub enum Amf0Value { + Number(f64), + Boolean(bool), + Utf8String(String), + Object(HashMap), + StrictArray(Vec), + Null, + Undefined, +} + +impl Amf0Value { + pub fn get_number(self) -> Option { + match self { + Amf0Value::Number(value) => Some(value), + _ => None, + } + } + + pub fn get_boolean(self) -> Option { + match self { + Amf0Value::Boolean(value) => Some(value), + _ => None, + } + } + + pub fn get_string(self) -> Option { + match self { + Amf0Value::Utf8String(value) => Some(value), + _ => None, + } + } + + pub fn get_object_properties(self) -> Option> { + match self { + Amf0Value::Object(properties) => Some(properties), + _ => None, + } + } +} + +mod markers { + pub const NUMBER_MARKER: u8 = 0; + pub const BOOLEAN_MARKER: u8 = 1; + pub const STRING_MARKER: u8 = 2; + pub const OBJECT_MARKER: u8 = 3; + pub const NULL_MARKER: u8 = 5; + pub const UNDEFINED_MARKER: u8 = 6; + pub const ECMA_ARRAY_MARKER: u8 = 8; + pub const OBJECT_END_MARKER: u8 = 9; + pub const STRICT_ARRAY_MARKER: u8 = 10; + pub const UTF_8_EMPTY_MARKER: u16 = 0; +} diff --git a/rs/moq-rtmp/src/rml/amf0/serialization.rs b/rs/moq-rtmp/src/rml/amf0/serialization.rs new file mode 100644 index 00000000000..3159dfae3bb --- /dev/null +++ b/rs/moq-rtmp/src/rml/amf0/serialization.rs @@ -0,0 +1,235 @@ +//! Module contains functionality for serializing values into an +//! bytes based on the AMF0 specification +//! (http://wwwimages.adobe.com/content/dam/Adobe/en/devnet/amf/pdf/amf0-file-format-specification.pdf) + +use super::Amf0Value; +use super::errors::Amf0SerializationError; +use super::markers; +use byteorder::{BigEndian, WriteBytesExt}; +use std::collections::HashMap; + +/// Serializes values into an amf0 encoded vector of bytes +pub fn serialize(values: &Vec) -> Result, Amf0SerializationError> { + let mut bytes = vec![]; + for value in values { + serialize_value(value, &mut bytes)?; + } + + Ok(bytes) +} + +fn serialize_value(value: &Amf0Value, bytes: &mut Vec) -> Result<(), Amf0SerializationError> { + match *value { + Amf0Value::Boolean(ref val) => Ok(serialize_bool(&val, bytes)), + Amf0Value::Null => Ok(serialize_null(bytes)), + Amf0Value::Undefined => Ok(serialize_undefined(bytes)), + Amf0Value::Number(ref val) => serialize_number(&val, bytes), + Amf0Value::Utf8String(ref val) => serialize_string(&val, bytes), + Amf0Value::Object(ref val) => serialize_object(&val, bytes), + Amf0Value::StrictArray(ref val) => serialize_strict_array(&val, bytes), + } +} + +fn serialize_number(value: &f64, bytes: &mut Vec) -> Result<(), Amf0SerializationError> { + bytes.push(markers::NUMBER_MARKER); + bytes.write_f64::(value.clone())?; + Ok(()) +} + +fn serialize_bool(value: &bool, bytes: &mut Vec) { + bytes.push(markers::BOOLEAN_MARKER); + bytes.push((value.clone()) as u8); +} + +fn serialize_string(value: &String, bytes: &mut Vec) -> Result<(), Amf0SerializationError> { + if value.len() > (u16::max_value() as usize) { + return Err(Amf0SerializationError::NormalStringTooLong); + } + + bytes.push(markers::STRING_MARKER); + bytes.write_u16::(value.len() as u16)?; + bytes.extend(value.as_bytes()); + Ok(()) +} + +fn serialize_null(bytes: &mut Vec) { + bytes.push(markers::NULL_MARKER); +} + +fn serialize_undefined(bytes: &mut Vec) { + bytes.push(markers::UNDEFINED_MARKER); +} + +fn serialize_object( + properties: &HashMap, + bytes: &mut Vec, +) -> Result<(), Amf0SerializationError> { + bytes.push(markers::OBJECT_MARKER); + + for (name, value) in properties { + // TODO: Add check that property name isn't greater than a u16 + bytes.write_u16::(name.len() as u16)?; + bytes.extend(name.as_bytes()); + serialize_value(&value, bytes)?; + } + + bytes.write_u16::(markers::UTF_8_EMPTY_MARKER)?; + bytes.push(markers::OBJECT_END_MARKER); + Ok(()) +} + +fn serialize_strict_array(array: &Vec, bytes: &mut Vec) -> Result<(), Amf0SerializationError> { + bytes.push(markers::STRICT_ARRAY_MARKER); + + bytes.write_u32::(array.len() as u32)?; + + for value in array { + serialize_value(&value, bytes)?; + } + + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::super::Amf0Value; + use super::super::errors::Amf0SerializationError; + use super::super::markers; + use super::serialize; + use byteorder::{BigEndian, WriteBytesExt}; + use std::collections::HashMap; + + #[test] + fn can_serialize_strict_array() { + let number: f64 = 332.0; + + let value = Amf0Value::Number(number); + + let input = vec![Amf0Value::StrictArray(vec![value])]; + + let result = serialize(&input).unwrap(); + + let mut expected = vec![]; + + expected.write_u8(markers::STRICT_ARRAY_MARKER).unwrap(); + expected.write_u32::(1).unwrap(); + expected.write_u8(markers::NUMBER_MARKER).unwrap(); + expected.write_f64::(number).unwrap(); + + assert_eq!(result, expected); + } + + #[test] + fn can_serialize_number() { + let number: f64 = 332.0; + + let input = vec![Amf0Value::Number(number)]; + let result = serialize(&input).unwrap(); + + let mut expected = vec![]; + expected.write_u8(markers::NUMBER_MARKER).unwrap(); + expected.write_f64::(number).unwrap(); + + assert_eq!(result, expected); + } + + #[test] + fn can_serialize_true_boolean() { + let input = vec![Amf0Value::Boolean(true)]; + let result = serialize(&input).unwrap(); + + let mut expected = vec![]; + expected.write_u8(markers::BOOLEAN_MARKER).unwrap(); + expected.write_u8(1).unwrap(); + + assert_eq!(result, expected); + } + + #[test] + fn can_serialize_false_boolean() { + let input = vec![Amf0Value::Boolean(false)]; + let result = serialize(&input).unwrap(); + + let mut expected = vec![]; + expected.write_u8(markers::BOOLEAN_MARKER).unwrap(); + expected.write_u8(0).unwrap(); + + assert_eq!(result, expected); + } + + #[test] + fn can_serialize_string() { + let value = "test"; + + let input = vec![Amf0Value::Utf8String(value.to_string())]; + let result = serialize(&input).unwrap(); + + let mut expected = vec![]; + expected.write_u8(markers::STRING_MARKER).unwrap(); + expected.write_u16::(value.len() as u16).unwrap(); + expected.extend(value.as_bytes()); + + assert_eq!(result, expected); + } + + #[test] + fn can_serialize_null() { + let input = vec![Amf0Value::Null]; + let result = serialize(&input).unwrap(); + + let mut expected = vec![]; + expected.write_u8(markers::NULL_MARKER).unwrap(); + + assert_eq!(result, expected); + } + + #[test] + fn can_serialize_object() { + const NUMBER: f64 = 332.0; + + let mut properties = HashMap::new(); + properties.insert("test".to_string(), Amf0Value::Number(NUMBER)); + + let input = vec![Amf0Value::Object(properties)]; + let result = serialize(&input).unwrap(); + + let mut expected = vec![]; + expected.push(markers::OBJECT_MARKER); + expected.write_u16::(4).unwrap(); + expected.extend("test".as_bytes()); + expected.push(markers::NUMBER_MARKER); + expected.write_f64::(NUMBER).unwrap(); + expected.write_u16::(markers::UTF_8_EMPTY_MARKER).unwrap(); + expected.push(markers::OBJECT_END_MARKER); + + assert_eq!(result, expected); + } + + #[test] + fn error_when_string_length_greater_than_u16() { + let mut value = String::new(); + let max = (u16::max_value() as u32) + 1; + for _ in 0..max { + value.push('a'); + } + + let input = vec![Amf0Value::Utf8String(value)]; + let result = serialize(&input); + + assert!(match result { + Err(Amf0SerializationError::NormalStringTooLong) => true, + _ => false, + }); + } + + #[test] + fn can_serialize_undefined() { + let input = vec![Amf0Value::Undefined]; + let result = serialize(&input).unwrap(); + + let mut expected = vec![]; + expected.write_u8(markers::UNDEFINED_MARKER).unwrap(); + + assert_eq!(result, expected); + } +} diff --git a/rs/moq-rtmp/src/rml/chunk_io/deserialization_errors.rs b/rs/moq-rtmp/src/rml/chunk_io/deserialization_errors.rs index 5704561281d..15fd98fc448 100644 --- a/rs/moq-rtmp/src/rml/chunk_io/deserialization_errors.rs +++ b/rs/moq-rtmp/src/rml/chunk_io/deserialization_errors.rs @@ -12,10 +12,8 @@ pub enum ChunkDeserializationError { #[error("Received chunk with non-zero chunk type on csid {csid} prior to receiving a type 0 chunk")] NoPreviousChunkOnStream { csid: u32 }, - /// The max chunk size does not allow chunk sizes more than 2,147,483,647 (since it's encoded in only - /// 31 bytes of the SetChunkSize message), so this error occurs when a chunk size of greater than - /// this value is attempted to be set - #[error("Requested an invalid max chunk size of {chunk_size}. The largest chunk size possible is 2147483647")] + /// Chunk sizes must fit in 31 bits and be at least one byte. + #[error("Requested an invalid max chunk size of {chunk_size}. Expected 1 through 2147483647")] InvalidMaxChunkSize { chunk_size: usize }, /// An I/O error occurred while reading the input buffer diff --git a/rs/moq-rtmp/src/rml/chunk_io/deserializer.rs b/rs/moq-rtmp/src/rml/chunk_io/deserializer.rs index 3102ddd3853..78946357572 100644 --- a/rs/moq-rtmp/src/rml/chunk_io/deserializer.rs +++ b/rs/moq-rtmp/src/rml/chunk_io/deserializer.rs @@ -178,7 +178,7 @@ impl ChunkDeserializer { /// This method should almost always be called only in reaction to receiving a `SetChunkSize` /// message from the other end. pub fn set_max_chunk_size(&mut self, new_size: usize) -> Result<(), ChunkDeserializationError> { - if new_size > 2147483647 { + if new_size == 0 || new_size > 2147483647 { return Err(ChunkDeserializationError::InvalidMaxChunkSize { chunk_size: new_size }); } @@ -462,6 +462,18 @@ mod tests { use byteorder::{BigEndian, LittleEndian, WriteBytesExt}; use std::io::{Cursor, Write}; + #[test] + fn chunk_size_floor() { + let mut decoder = ChunkDeserializer::new(); + assert!(matches!( + decoder.set_max_chunk_size(0), + Err(ChunkDeserializationError::InvalidMaxChunkSize { chunk_size: 0 }) + )); + assert_eq!(decoder.get_max_chunk_size(), 128); + decoder.set_max_chunk_size(1).unwrap(); + assert_eq!(decoder.get_max_chunk_size(), 1); + } + #[test] fn can_read_type_0_chunk_with_small_chunk_stream_id_and_small_timestamp() { let csid = 50; diff --git a/rs/moq-rtmp/src/rml/messages/deserialization_errors.rs b/rs/moq-rtmp/src/rml/messages/deserialization_errors.rs index 26e4e8dec81..ee6624bdfcc 100644 --- a/rs/moq-rtmp/src/rml/messages/deserialization_errors.rs +++ b/rs/moq-rtmp/src/rml/messages/deserialization_errors.rs @@ -1,4 +1,4 @@ -use rml_amf0::Amf0DeserializationError; +use crate::rml::amf0::Amf0DeserializationError; use thiserror::Error; use std::io; diff --git a/rs/moq-rtmp/src/rml/messages/message_payload.rs b/rs/moq-rtmp/src/rml/messages/message_payload.rs index dca302e702f..0ddd9fb2195 100644 --- a/rs/moq-rtmp/src/rml/messages/message_payload.rs +++ b/rs/moq-rtmp/src/rml/messages/message_payload.rs @@ -137,10 +137,10 @@ impl MessagePayload { #[cfg(test)] mod tests { use super::{MessagePayload, RtmpMessage}; + use crate::rml::amf0::Amf0Value; use crate::rml::messages::{PeerBandwidthLimitType, UserControlEventType}; use crate::rml::time::RtmpTimestamp; use bytes::{BufMut, Bytes, BytesMut}; - use rml_amf0::Amf0Value; #[test] fn can_get_payload_from_abort_message() { diff --git a/rs/moq-rtmp/src/rml/messages/mod.rs b/rs/moq-rtmp/src/rml/messages/mod.rs index c7608938182..3a165f65faf 100644 --- a/rs/moq-rtmp/src/rml/messages/mod.rs +++ b/rs/moq-rtmp/src/rml/messages/mod.rs @@ -14,9 +14,9 @@ mod types; pub use self::deserialization_errors::MessageDeserializationError; pub use self::message_payload::MessagePayload; pub use self::serialization_errors::MessageSerializationError; +use crate::rml::amf0::Amf0Value; use crate::rml::time::RtmpTimestamp; use bytes::Bytes; -use rml_amf0::Amf0Value; /// The type of bandwidth limiting that is being requested #[derive(Eq, PartialEq, Debug, Clone)] diff --git a/rs/moq-rtmp/src/rml/messages/serialization_errors.rs b/rs/moq-rtmp/src/rml/messages/serialization_errors.rs index 43d2b8ecd66..748651e5c0d 100644 --- a/rs/moq-rtmp/src/rml/messages/serialization_errors.rs +++ b/rs/moq-rtmp/src/rml/messages/serialization_errors.rs @@ -1,4 +1,4 @@ -use rml_amf0::Amf0SerializationError; +use crate::rml::amf0::Amf0SerializationError; use thiserror::Error; use std::io; diff --git a/rs/moq-rtmp/src/rml/messages/types/amf0_command.rs b/rs/moq-rtmp/src/rml/messages/types/amf0_command.rs index 6120e8b12d8..730f76e50c1 100644 --- a/rs/moq-rtmp/src/rml/messages/types/amf0_command.rs +++ b/rs/moq-rtmp/src/rml/messages/types/amf0_command.rs @@ -1,6 +1,6 @@ +use crate::rml::amf0; +use crate::rml::amf0::Amf0Value; use bytes::Bytes; -use rml_amf0; -use rml_amf0::Amf0Value; use std::io::Cursor; use crate::rml::messages::RtmpMessage; @@ -19,14 +19,14 @@ pub fn serialize( ]; values.append(&mut additional_arguments); - let bytes = rml_amf0::serialize(&values)?; + let bytes = amf0::serialize(&values)?; Ok(Bytes::from(bytes)) } pub fn deserialize(data: Bytes) -> Result { let mut cursor = Cursor::new(data); - let mut arguments = rml_amf0::deserialize(&mut cursor)?; + let mut arguments = amf0::deserialize(&mut cursor)?; let command_name: String; let transaction_id: f64; @@ -71,9 +71,9 @@ pub fn deserialize(data: Bytes) -> Result) -> Result { - let bytes = rml_amf0::serialize(&values)?; + let bytes = amf0::serialize(&values)?; Ok(Bytes::from(bytes)) } pub fn deserialize(data: Bytes) -> Result { let mut cursor = Cursor::new(data); - let values = rml_amf0::deserialize(&mut cursor)?; + let values = amf0::deserialize(&mut cursor)?; Ok(RtmpMessage::Amf0Data { values }) } @@ -22,9 +22,9 @@ pub fn deserialize(data: Bytes) -> Result panic!("Expected Amf0Command command, instead received: {:?}", x), } } + +#[test] +fn amf0_nesting_limit() { + // A bounded stack, so unbounded recursion overflows instead of passing on a large default. + std::thread::Builder::new() + .stack_size(2 * 1024 * 1024) + .spawn(|| { + // Object, ECMA array, and strict array markers. + for marker in [3, 8, 10] { + for depth in [64, 65, 100_000] { + // AMF0 data, AMF0 command, and their AMF3-labelled forms. + for type_id in [18, 20, 15, 17] { + let packet = nested_amf0_packet(marker, depth, type_id); + let (mut session, _) = ServerSession::new(ServerSessionConfig::new()).unwrap(); + let result = session.handle_input(&packet); + let case = format!("marker {marker}, depth {depth}, type {type_id}"); + if depth <= 64 { + assert!(result.is_ok(), "{case}: {result:?}"); + } else { + assert!( + matches!( + result, + Err(ServerSessionError::MessageDeserializationError( + MessageDeserializationError::Amf0DeserializationError( + amf0::Amf0DeserializationError::MaxDepthExceeded + ) + )) + ), + "{case}: expected nesting error, got {result:?}" + ); + } + } + } + } + }) + .unwrap() + .join() + .unwrap(); +} + +/// Builds wire bytes directly so preparing the input does not recurse. +fn nested_amf0_packet(marker: u8, depth: usize, type_id: u8) -> Vec { + let mut data = amf0::serialize(&vec![Amf0Value::Utf8String("test".into())]).unwrap(); + if type_id == 20 || type_id == 17 { + data.extend_from_slice(&[0; 9]); // transaction number + } + for _ in 0..depth { + data.push(marker); + if marker == 8 || marker == 10 { + data.extend_from_slice(&1u32.to_be_bytes()); + } + if marker == 3 || marker == 8 { + data.extend_from_slice(&[0, 1, b'x']); + } + } + data.push(5); // null leaf + if marker == 3 || marker == 8 { + for _ in 0..depth { + data.extend_from_slice(&[0, 0, 9]); + } + } + if type_id == 17 { + data.insert(0, 0); // AMF0 command labelled AMF3 + } + let payload = MessagePayload { + timestamp: RtmpTimestamp::new(0), + type_id, + message_stream_id: 0, + data: Bytes::from(data), + }; + ChunkSerializer::new() + .serialize(&payload, true, false) + .unwrap() + .bytes + .to_vec() +} diff --git a/rs/moq-rtmp/src/server.rs b/rs/moq-rtmp/src/server.rs index 0ba3e2803f3..c3fd78a8b42 100644 --- a/rs/moq-rtmp/src/server.rs +++ b/rs/moq-rtmp/src/server.rs @@ -33,8 +33,8 @@ use std::pin::Pin; use std::task::{Context, Poll}; use std::time::Duration; +use crate::rml::amf0::Amf0Value; use crate::rml::handshake::{Handshake, HandshakeProcessResult, PeerType}; -use crate::rml::rml_amf0::Amf0Value; use crate::rml::sessions::{ FourCcSupport, ServerSession, ServerSessionConfig, ServerSessionEvent, ServerSessionResult, }; From 2709f989a21298295bad6e5ac571afcbc1ef9555 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 13:20:13 -0700 Subject: [PATCH 037/128] chore(quest): drop the retired srt-import-stats link (#4530) Co-authored-by: Claude Opus 5.5 --- quest/m2/ts-import-health.md | 1 - 1 file changed, 1 deletion(-) diff --git a/quest/m2/ts-import-health.md b/quest/m2/ts-import-health.md index 0b9d8323977..695f2cd8e92 100644 --- a/quest/m2/ts-import-health.md +++ b/quest/m2/ts-import-health.md @@ -112,5 +112,4 @@ Implementation: ## Related -- [SRT import stats](/quest/m1/srt-import-stats.md) - the gateway forwards the same `stats()` - [TS health stats](/quest/m2/ts-health-stats.md) - where these counters are published From 30826ff7ce6609e108d4d99b3c15d9905f6e24c4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 13:21:03 -0700 Subject: [PATCH 038/128] fix(hang): write a zero dOps pre-skip when the track has no description (#4439) Co-authored-by: Claude Sonnet 5.5 --- js/hang/src/container/cmaf/encode.test.ts | 18 +++++++++++++++++- js/hang/src/container/cmaf/encode.ts | 4 ++-- quest/m1/README.md | 1 - quest/m1/js-dops-pre-skip.md | 12 ------------ 4 files changed, 19 insertions(+), 16 deletions(-) delete mode 100644 quest/m1/js-dops-pre-skip.md diff --git a/js/hang/src/container/cmaf/encode.test.ts b/js/hang/src/container/cmaf/encode.test.ts index 6f293404595..91efdd0ff0e 100644 --- a/js/hang/src/container/cmaf/encode.test.ts +++ b/js/hang/src/container/cmaf/encode.test.ts @@ -1,6 +1,7 @@ import { expect, test } from "bun:test"; import { readIsoBoxes, readTrun, type TrackRunBox } from "@svta/cml-iso-bmff"; -import { encodeDataSegment } from "./encode.ts"; +import { u53 } from "../../catalog/integers.ts"; +import { createAudioInitSegment, encodeDataSegment } from "./encode.ts"; for (const kind of ["audio", "video"] as const) { for (const keyframe of [false, true]) { @@ -23,3 +24,18 @@ for (const kind of ["audio", "video"] as const) { }); } } + +test("opus init segment without a description trims no pre-skip", () => { + const init = createAudioInitSegment({ + codec: "opus", + sampleRate: u53(48_000), + numberOfChannels: u53(2), + container: { kind: "legacy" }, + }); + const at = new TextDecoder().decode(init).indexOf("dOps"); + expect(at).toBeGreaterThan(0); + // dOps payload: version (1), channel count (1), pre-skip (2, big-endian). + const dops = new DataView(init.buffer, init.byteOffset + at + 4, 4); + expect(dops.getUint8(1)).toBe(2); + expect(dops.getUint16(2, false)).toBe(0); +}); diff --git a/js/hang/src/container/cmaf/encode.ts b/js/hang/src/container/cmaf/encode.ts index 9831b61083e..3c676d8cba9 100644 --- a/js/hang/src/container/cmaf/encode.ts +++ b/js/hang/src/container/cmaf/encode.ts @@ -873,8 +873,8 @@ function createDOpsBox(channelCount: number, sampleRate: number, description?: s dOps[offset++] = 0; // Version dOps[offset++] = channelCount; - view.setUint16(offset, 312, false); - offset += 2; // PreSkip (typical value) + view.setUint16(offset, 0, false); + offset += 2; // PreSkip: unknown without an OpusHead, so trim nothing, like the Rust exporter view.setUint32(offset, sampleRate, false); offset += 4; // InputSampleRate view.setInt16(offset, 0, false); diff --git a/quest/m1/README.md b/quest/m1/README.md index e657b29d324..0046059c970 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -86,7 +86,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Opus mapping family](/quest/m1/opus-mapping-family.md) - on dev, the Opus head config keeps its mapping family only in `mapping` - [mp4-atom dOps mapping](/quest/m1/mp4-atom-dops-mapping.md) - a released mp4-atom reads and writes any `dOps` channel mapping family and table - [CMAF surround Opus](/quest/m1/cmaf-opus-surround.md) - fMP4 import and export carry an Opus channel mapping table -- [js/hang dOps pre-skip](/quest/m1/js-dops-pre-skip.md) - CMAF encoding in js/hang stops hard-coding a 312-sample pre-skip - [GPU CI](/quest/m1/gpu-ci.md) - NVIDIA tests run nightly on a self-hosted GPU runner, and `just rs nvidia` runs them locally instead of skipping - [JS rendition ranking](/quest/m1/js-ranked.md) - `@moq/hang` ranks video renditions like Rust, and `@moq/watch`'s fallback uses it - [Audio rendition pick](/quest/m1/audio-ranked.md) - single-track FLV/RTMP and WHEP serve the best audio rendition, not the first by name diff --git a/quest/m1/js-dops-pre-skip.md b/quest/m1/js-dops-pre-skip.md deleted file mode 100644 index 273669a0f91..00000000000 --- a/quest/m1/js-dops-pre-skip.md +++ /dev/null @@ -1,12 +0,0 @@ -# [XS] js/hang dOps without an invented pre-skip - -## Goal - -`js/hang` CMAF encoding stops writing a hard-coded 312-sample pre-skip into -`dOps` when the track has no description, so a remuxed track never trims audio -its encoder did not ask to trim. - -## Plan - -Without an OpusHead there is no known pre-skip; write 0 or refuse, whichever -matches how the Rust exporter (`synthesize_audio_trak`) handles the same case. From 59c0dc2229d9dfae72abd15ba599c5532068d9d3 Mon Sep 17 00:00:00 2001 From: t0ms Date: Tue, 29 Sep 2026 21:21:07 +0100 Subject: [PATCH 039/128] feat(ts): import one program of a multiplex, or each as its own broadcast (#4505) Co-authored-by: Cursor Co-authored-by: Luke Curley Co-authored-by: Claude Opus 5.5 --- Cargo.lock | 1 + doc/bin/cli.md | 12 + quest/m1/README.md | 1 - quest/m1/ts-programs.md | 37 --- quest/m1/ts-psi-reassembly.md | 8 +- quest/m2/ts-import-health.md | 4 +- quest/m2/ts-program-si.md | 4 - rs/moq-cli/Cargo.toml | 2 + rs/moq-cli/src/args.rs | 70 ++++- rs/moq-cli/src/main.rs | 14 +- rs/moq-cli/src/publish.rs | 418 +++++++++++++++++++++++--- rs/moq-mux/src/container/ts/import.rs | 231 ++++++++++++-- 12 files changed, 687 insertions(+), 115 deletions(-) delete mode 100644 quest/m1/ts-programs.md diff --git a/Cargo.lock b/Cargo.lock index c783e53591f..b397cdaf8f4 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4305,6 +4305,7 @@ dependencies = [ "moq-tokio", "moq-transcode", "moq-video", + "mpeg2ts", "pollster", "reqwest", "rustls", diff --git a/doc/bin/cli.md b/doc/bin/cli.md index 0e0b5cee402..6b01b5d81b0 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -79,6 +79,18 @@ downstream sees it. A sparse stream such as SCTE-35 goes quiet between cues, so the line reports rather than alarms; `Import::stats` carries the same counters for a caller that sets its own limit. +MPEG-TS import takes one program. A multi-program stream is refused before +anything is published, naming its programs, rather than merged onto one clock; +a PAT that adds a program mid-stream ends the import the same way. +`--program 2` imports program 2 alone. `--program all` publishes each program +the first PAT lists as its own broadcast, with its own clock and catalog, keeping +the catalog suffix last: `--broadcast event.hang` publishes `event/1.hang`, +`event/2.hang`, and so on. `export ts` writes one program per broadcast. + +```bash +moq --connect https://relay.example.com/anon --broadcast event.hang import ts --program all < mux.ts +``` + MPEG-TS export restarts its clock and table cadence after a declared marker, discarding the old mux buffer. The first new clock packet signals the break and stdout pacing re-anchors. Every rendition joins the new program generation; diff --git a/quest/m1/README.md b/quest/m1/README.md index 0046059c970..c1dd03c88fe 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -51,7 +51,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Merge queue](/quest/m1/merge-queue.md) - the required checks run on `merge_group`, so a stale green check can no longer break main - [Wire compatibility](/quest/m1/wire-compat.md) - a nightly run tests this checkout against the last published release for tokens, session wire, and catalog/container - [Full codec string](/quest/m1/publish-codec-string.md) - browser-published video carries the encoder's full RFC 6381 codec string, so native players decode it -- [TS program selection](/quest/m1/ts-programs.md) - `import ts` refuses a multi-program stream unless `--program ` picks one or publishes each - [TS import shared shift](/quest/m1/ts-import-shared-shift.md) - unflagged loop wraps move audio and video by one shift, so A/V sync holds across wraps - [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) - `import ts` reads a PAT or PMT that spans packets or follows a nonzero pointer_field instead of aborting, and one corrupted section costs a repetition and a counted `CRC_error`, not the import - [Same-hop importers](/quest/m1/hop-aligned-import.md) - importers sharing a `--hop` and fed one stream publish identical groups and timestamps, so failover survives diff --git a/quest/m1/ts-programs.md b/quest/m1/ts-programs.md deleted file mode 100644 index 14e17a964c1..00000000000 --- a/quest/m1/ts-programs.md +++ /dev/null @@ -1,37 +0,0 @@ -# [L] moq import ts: select programs - -## Goal - -A multi-program transport stream is never silently merged. Today `import ts` -keeps the first program's identity, adds every PMT's streams to one broadcast -on one clock, and loses content; `export ts` rebuilds one program. After -this quest `import ts` refuses a multi-program input by default, naming the -programs, and `--program` chooses what to import. - -## Plan - -Decided: - -- Default: error before publishing when the initial PAT lists more than one - non-zero program, naming each program and pointing at `--program`. A later - PAT that adds a program ends the import with the same error; media already - published stays. -- `--program ` imports program `n` only. -- `--program all` publishes one broadcast per program, each with its own clock - and catalog. The catalog suffix stays last so discovery and format detection - still see it: `--broadcast event.hang` publishes `event/1.hang` and - `event/2.hang`. -- `export ts` stays one program per broadcast. - -Tests: a synthetic two-program input with far-apart clocks fails naming both -programs; `--program 2` publishes only program 2's streams on program 2's -clock; `--program all` publishes both broadcasts, each timed correctly. Update -`doc/bin/cli.md` and the `--help` text. - -## Closes - -- [#4353](https://github.com/moq-dev/moq/issues/4353) - close this issue when the quest finishes - -## Related - -- [TS import shared shift](/quest/m1/ts-import-shared-shift.md) - its per-program shift assumes the single program this settles diff --git a/quest/m1/ts-psi-reassembly.md b/quest/m1/ts-psi-reassembly.md index e9f4638d319..665a76a8da3 100644 --- a/quest/m1/ts-psi-reassembly.md +++ b/quest/m1/ts-psi-reassembly.md @@ -51,8 +51,8 @@ Settled decisions: for another reason (a malformed adaptation field, a parse failure) is not a `crc_error`; that quest counts it under `PAT_error` or `PMT_error`. `Stats` is `#[non_exhaustive]`, so the new field is additive; its docs (today per - elementary stream) and `is_empty` widen to cover it, and `moq-cli`'s - `log_stats` reports it. + elementary stream) and `is_empty` widen to cover it, and `ts::stats::Log` + reports it. - `ts::programs()` reads through the same PAT path, so a PAT spanning packets is found before any program publishes. - One quest, because the demux refactor alone changes nothing observable. @@ -67,7 +67,3 @@ control: a feed whose only PAT is corrupt publishes nothing and counts it. Folded in from `ts-import-psi-crc` while landing the TR 101 290 plan (#4496): that quest duplicated this one's bad-CRC drop and `CRC_error` count. - -## Required - -- [moq import ts: select programs](/quest/m1/ts-programs.md) - `ts::programs()` and `with_program`, which this quest's PAT path and tests build on diff --git a/quest/m2/ts-import-health.md b/quest/m2/ts-import-health.md index 695f2cd8e92..faf45a6a4df 100644 --- a/quest/m2/ts-import-health.md +++ b/quest/m2/ts-import-health.md @@ -92,8 +92,8 @@ Implementation: declared by `discontinuity_indicator`, the one duplicate ISO 13818-1 2.4.3.3 permits, and a payload-less packet repeating its counter are not errors. -- `rs/moq-cli/src/publish.rs` `log_stats` logs a line when a counter moves, - as it does for resyncs. +- `ts::stats::Log` logs a line when a counter moves, as it does for + resyncs. - Measure `decode` throughput on `test_data/kyrion_mpeg2av_ac3.ts` before and after; the checks read header bytes the loop already reads, so a measurable cost is a finding. diff --git a/quest/m2/ts-program-si.md b/quest/m2/ts-program-si.md index 7941d1a5837..168022f0a11 100644 --- a/quest/m2/ts-program-si.md +++ b/quest/m2/ts-program-si.md @@ -50,7 +50,3 @@ carries one SDT entry with a valid CRC and only its own EIT; an unselected import keeps the sections verbatim; a selection missing from the SDT carries none; an SDT version that drops the selected service retires the earlier one; and the re-exported TS still parses. - -## Required - -- [moq import ts: select programs](/quest/m1/ts-programs.md) - `ts::Import::with_program`, which this filtering hangs off diff --git a/rs/moq-cli/Cargo.toml b/rs/moq-cli/Cargo.toml index 4078f83f2e7..5a04e95d909 100644 --- a/rs/moq-cli/Cargo.toml +++ b/rs/moq-cli/Cargo.toml @@ -130,6 +130,8 @@ sd-notify = { workspace = true } moq-msf = { path = "../moq-msf" } # `test_relay` stands up a real relay for the `fetch` tests to read through. moq-relay = { path = "../moq-relay", default-features = false, features = ["test-support"] } +# Writes the PAT and PMTs, CRCs included, of the two-program input `import ts --program all` splits. +mpeg2ts = "0.6.0" tempfile = { workspace = true } # `test-util` enables `tokio::time::pause` so the TS round-trip test simulates the # exporter drain timeouts instantly instead of waiting on the wall clock. diff --git a/rs/moq-cli/src/args.rs b/rs/moq-cli/src/args.rs index dd3249bb247..61a81d78017 100644 --- a/rs/moq-cli/src/args.rs +++ b/rs/moq-cli/src/args.rs @@ -728,7 +728,7 @@ pub enum ImportSource { /// Fragmented MP4 / CMAF from stdin. Fmp4, /// MPEG-TS from stdin. - Ts, + Ts(TsImport), /// FLV / RTMP container from stdin. Flv, /// Pull a remote HLS / LL-HLS playlist (http/https URL or local file) into MoQ. @@ -751,13 +751,60 @@ impl ImportSource { Some(match self { Self::Avc3 => PublishFormat::Avc3, Self::Fmp4 => PublishFormat::Fmp4, - Self::Ts => PublishFormat::Ts, + Self::Ts(args) => PublishFormat::Ts { + program: args.program.and_then(TsProgram::number), + }, Self::Flv => PublishFormat::Flv, _ => return None, }) } } +/// The MPEG-TS stdin container: which programs of a multiplex to publish. +#[derive(usage::Args, Clone)] +#[usage(unknown_flags = "error", args_override_self = false)] +pub struct TsImport { + /// Import one program of a multi-program stream, by its PAT program number, or `all` to + /// publish each program as its own broadcast (`event.hang` becomes `event/1.hang`, + /// `event/2.hang`, ...). Without it, a stream carrying more than one program is refused. + #[usage(long)] + pub program: Option, +} + +/// An `import ts --program` value. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum TsProgram { + /// The program with this PAT program number. + One(u16), + /// Every program, each as its own broadcast. + All, +} + +impl TsProgram { + /// The single program selected, `None` for `all`. + fn number(self) -> Option { + match self { + Self::One(program) => Some(program), + Self::All => None, + } + } +} + +impl std::str::FromStr for TsProgram { + type Err = String; + + fn from_str(arg: &str) -> Result { + match arg { + "all" => Ok(Self::All), + _ => match arg.parse() { + Ok(0) => Err("program 0 is the network PID, not a program".to_string()), + Ok(program) => Ok(Self::One(program)), + Err(_) => Err(format!("expected a program number or `all`, got `{arg}`")), + }, + } + } +} + // ------------------------------------------------------------------ export /// export = MoQ -> one sink. @@ -956,6 +1003,25 @@ mod tests { assert!(cli.validate().is_ok()); } + #[test] + fn import_ts_takes_a_program_number_or_all() { + // `None` when the command line is refused. + let program = |value: &str| { + let cli = Invocation::try_parse_from(["moq", "import", "ts", "--program", value]).ok()?; + let Command::Import(import) = &cli.stages[0] else { + panic!("an import stage"); + }; + let ImportSource::Ts(args) = &import.source else { + panic!("an import ts stage"); + }; + Some(args.program) + }; + assert_eq!(program("2"), Some(Some(TsProgram::One(2)))); + assert_eq!(program("all"), Some(Some(TsProgram::All))); + assert_eq!(program("0"), None, "0 is the network PID"); + assert_eq!(program("two"), None); + } + /// A released spelling is refused, and the error names what to write instead. /// /// The alternative is what this replaced: the flag parsed onto a hidden field, diff --git a/rs/moq-cli/src/main.rs b/rs/moq-cli/src/main.rs index 15809849e44..ff8c09359d0 100644 --- a/rs/moq-cli/src/main.rs +++ b/rs/moq-cli/src/main.rs @@ -25,7 +25,7 @@ mod test_env; mod transcode; mod web; -use args::{Command, Export, ExportSink, Import, ImportSource, Invocation, MoqSide}; +use args::{Command, Export, ExportSink, Import, ImportSource, Invocation, MoqSide, TsImport, TsProgram}; use hang::moq_net; use publish::Publish; use subscribe::{Subscribe, SubscribeArgs}; @@ -631,11 +631,19 @@ fn spawn_import( if let Some(format) = import.source.stdin_format() { warn_if_missing_format(&name); - let broadcast = origin.create_broadcast(&name).context("failed to create broadcast")?; let config = moq_mux::catalog::Config::default() .with_max_age(max_age) .with_bandwidth(bandwidth.clone()); - let publish = Publish::new(broadcast, &format, config)?; + let publish = if let ImportSource::Ts(TsImport { + program: Some(TsProgram::All), + }) = &import.source + { + let name = require_broadcast(name, "import ts --program all")?; + Publish::ts_programs(origin.clone(), name, config) + } else { + let broadcast = origin.create_broadcast(&name).context("failed to create broadcast")?; + Publish::new(broadcast, &format, config)? + }; publish.announce()?; local = Some(publish); } else { diff --git a/rs/moq-cli/src/publish.rs b/rs/moq-cli/src/publish.rs index b21f8978ed6..5bf7c089160 100644 --- a/rs/moq-cli/src/publish.rs +++ b/rs/moq-cli/src/publish.rs @@ -9,8 +9,8 @@ pub enum PublishFormat { Avc3, /// Fragmented MP4 (CMAF). Fmp4, - /// MPEG-TS (transport stream). - Ts, + /// MPEG-TS (transport stream), limited to one `program` of a multiplex when given. + Ts { program: Option }, /// FLV (Flash Video / RTMP). Flv, } @@ -141,6 +141,8 @@ enum PublishDecoder { // TS carries undecoded elementary streams (SCTE-35, teletext, DVB AC-3, ...) // verbatim, so it uses the `mpegts` catalog extension rather than the media-only `()`. Ts(Box>), + /// `import ts --program all`: one importer, broadcast, and catalog per program. + TsPrograms(Box), Flv(Box), } @@ -155,7 +157,8 @@ impl PublishDecoder { import.decode(frames)?; } Self::Fmp4(d) => d.decode(chunk)?, - Self::Ts(d) => d.decode(chunk)?, + Self::Ts(d) => d.decode(chunk).map_err(suggest_program)?, + Self::TsPrograms(d) => d.decode(chunk)?, Self::Flv(d) => d.decode(chunk)?, } Ok(()) @@ -166,6 +169,7 @@ impl PublishDecoder { fn stats(&self) -> Option { match self { Self::Ts(d) => Some(d.stats()), + Self::TsPrograms(d) => Some(d.stats()), Self::Avc3 { .. } | Self::Fmp4(_) | Self::Flv(_) => None, } } @@ -182,6 +186,7 @@ impl PublishDecoder { } Self::Fmp4(d) => d.finish()?, Self::Ts(d) => d.finish()?, + Self::TsPrograms(d) => d.finish()?, Self::Flv(d) => d.finish()?, } Ok(()) @@ -194,15 +199,27 @@ impl PublishDecoder { Self::Avc3 { import, .. } => import.abort(err), Self::Fmp4(d) => d.abort(err), Self::Ts(d) => d.abort(err), + Self::TsPrograms(d) => d.abort(err), Self::Flv(d) => d.abort(err), } } } +/// Point a multi-program refusal at the flag that resolves it. +fn suggest_program(err: anyhow::Error) -> anyhow::Error { + if err.is::() { + err.context("choose one with `--program `, or publish each with `--program all`") + } else { + err + } +} + /// The catalog a stdin decoder publishes into. TS carries the `mpegts` extension. enum PublishCatalog { Media(moq_mux::catalog::Producer), Ts(moq_mux::catalog::Producer), + /// `import ts --program all`: each program's catalog, finished by [`TsPrograms::finish`]. + TsPrograms, } impl PublishCatalog { @@ -211,9 +228,140 @@ impl PublishCatalog { match self { Self::Media(catalog) => catalog.finish()?, Self::Ts(catalog) => catalog.finish()?, + Self::TsPrograms => {} + } + Ok(()) + } +} + +/// Build the importer and `mpegts` catalog for one TS broadcast. +/// +/// TS carries undecoded elementary streams (SCTE-35, teletext, DVB AC-3, ...) verbatim, so it +/// uses the `mpegts` catalog extension rather than the media-only `()`. The catalog producer +/// owns the broadcast's catalog tracks, so each broadcast gets exactly one. +fn ts_import( + broadcast: &mut moq_net::broadcast::Producer, + config: moq_mux::catalog::Config, + program: Option, +) -> anyhow::Result<(ts::Import, moq_mux::catalog::Producer)> { + let config = config.with_catalog(moq_mux::catalog::hang::Catalog::::default()); + let catalog = moq_mux::catalog::Producer::new(broadcast, config)?; + let mut import = ts::Import::new(broadcast.clone(), catalog.reserve()).live(); + if let Some(program) = program { + import = import.with_program(program); + } + Ok((import, catalog)) +} + +/// One program's broadcast under `import ts --program all`. +struct ProgramImport { + /// Keeps the origin-created broadcast alive; the importer's clone doesn't. + _broadcast: moq_net::broadcast::Producer, + import: ts::Import, + catalog: moq_mux::catalog::Producer, +} + +/// `import ts --program all`: every program the first PAT lists, each published as its own +/// broadcast on its own clock and catalog. +/// +/// Input ahead of that PAT is dropped, as a single importer drops media ahead of its PSI. A +/// program a later PAT adds is not published; one it removes ends the import. +struct TsPrograms { + origin: moq_net::origin::Producer, + name: String, + config: moq_mux::catalog::Config, + /// Input held until it contains a whole PAT. + pending: Vec, + /// Empty until the PAT arrives. + programs: Vec, +} + +impl TsPrograms { + fn new(origin: moq_net::origin::Producer, name: String, config: moq_mux::catalog::Config) -> Self { + Self { + origin, + name, + config, + pending: Vec::new(), + programs: Vec::new(), + } + } + + fn decode(&mut self, chunk: &[u8]) -> anyhow::Result<()> { + if !self.programs.is_empty() { + return self.feed(chunk); + } + self.pending.extend_from_slice(chunk); + let Some(programs) = ts::programs(&self.pending).filter(|programs| !programs.is_empty()) else { + // Only a packet's worth of tail can still hold the start of the PAT. + let keep = self.pending.len().saturating_sub(TS_PACKET_SIZE - 1); + self.pending.drain(..keep); + return Ok(()); + }; + for program in programs { + let name = program_broadcast(&self.name, program); + let mut broadcast = self + .origin + .create_broadcast(&name) + .with_context(|| format!("failed to create broadcast {name}"))?; + let (import, catalog) = ts_import(&mut broadcast, self.config.clone(), Some(program))?; + broadcast + .announce(Default::default()) + .with_context(|| format!("failed to announce broadcast {name}"))?; + self.programs.push(ProgramImport { + _broadcast: broadcast, + import, + catalog, + }); + } + let pending = std::mem::take(&mut self.pending); + self.feed(&pending) + } + + fn feed(&mut self, chunk: &[u8]) -> anyhow::Result<()> { + for program in &mut self.programs { + program.import.decode(chunk)?; } Ok(()) } + + /// Every program's counters in one map: PIDs are unique across a multiplex. + fn stats(&self) -> ts::Stats { + let mut stats = ts::Stats::default(); + for program in &self.programs { + stats.streams.extend(program.import.stats().streams); + } + stats + } + + /// Finish each program's tracks, then its catalog while it still lists them. + fn finish(&mut self) -> anyhow::Result<()> { + for program in &mut self.programs { + program.import.finish()?; + program.catalog.finish()?; + } + Ok(()) + } + + fn abort(self, err: moq_net::Error) { + for program in self.programs { + program.import.abort(err.clone()); + } + } +} + +const TS_PACKET_SIZE: usize = 188; + +/// The broadcast one program of `name` publishes on, keeping the catalog suffix last so format +/// detection still sees it: `event.hang` becomes `event/2.hang`. +fn program_broadcast(name: &str, program: u16) -> String { + match moq_mux::catalog::CatalogFormat::detect(name) { + Some(format) => { + let stem = &name[..name.len() - format.extension().len()]; + format!("{stem}/{program}{}", format.extension()) + } + None => format!("{name}/{program}"), + } } // Exactly one Source exists per process, so the size gap between the small @@ -231,20 +379,21 @@ enum Source { /// concurrently. #[cfg(feature = "capture")] Capture { + broadcast: moq_net::broadcast::Producer, catalog: moq_mux::catalog::Producer, video: Option<(moq_video::capture::Config, moq_video::encode::Options)>, audio: Option<(moq_audio::capture::Config, moq_audio::encode::Options)>, }, } -/// A single-broadcast publisher: decodes stdin (or captures local devices) into +/// A stdin or capture publisher: decodes stdin (or captures local devices) into /// a broadcast that the MoQ side announces. pub struct Publish { source: Source, // Keeps the origin-created broadcast alive for the publisher's lifetime; - // tracks and importers don't. Only the capture path also writes through it. - #[cfg_attr(not(feature = "capture"), allow(dead_code))] - broadcast: moq_net::broadcast::Producer, + // tracks and importers don't. `None` for `import ts --program all`, whose + // programs each keep and announce their own. + broadcast: Option, } impl Publish { @@ -260,20 +409,15 @@ impl Publish { format: &PublishFormat, config: moq_mux::catalog::Config, ) -> anyhow::Result { - // TS carries undecoded elementary streams (SCTE-35, teletext, DVB AC-3, ...) - // verbatim, so it uses the `mpegts` catalog extension rather than the media-only - // `()`. The catalog producer owns the broadcast's catalog tracks, so each broadcast - // gets exactly one; TS builds its `Ext` catalog here instead of the shared `()` below. - if let PublishFormat::Ts = format { - let config = config.with_catalog(moq_mux::catalog::hang::Catalog::::default()); - let catalog = moq_mux::catalog::Producer::new(&mut broadcast, config)?; - let ts = ts::Import::new(broadcast.clone(), catalog.reserve()).live(); + // TS builds its `Ext` catalog instead of the shared `()` below. + if let PublishFormat::Ts { program } = *format { + let (ts, catalog) = ts_import(&mut broadcast, config, program)?; return Ok(Self { source: Source::Stream { decoder: PublishDecoder::Ts(Box::new(ts)), catalog: PublishCatalog::Ts(catalog), }, - broadcast, + broadcast: Some(broadcast), }); } @@ -292,7 +436,7 @@ impl Publish { let fmp4 = fmp4::Import::new(broadcast.clone(), catalog.reserve()).live(); PublishDecoder::Fmp4(Box::new(fmp4)) } - PublishFormat::Ts => unreachable!("TS is handled above with the mpegts catalog extension"), + PublishFormat::Ts { .. } => unreachable!("TS is handled above with the mpegts catalog extension"), PublishFormat::Flv => { let flv = flv::Import::new(broadcast.clone(), catalog.reserve()).live(); PublishDecoder::Flv(Box::new(flv)) @@ -304,10 +448,25 @@ impl Publish { decoder, catalog: PublishCatalog::Media(catalog), }, - broadcast, + broadcast: Some(broadcast), }) } + /// Build a publisher decoding a multi-program TS from stdin into one broadcast per program, + /// named after `name` (`event.hang` becomes `event/1.hang`, `event/2.hang`, ...). + /// + /// The programs aren't known until the PAT arrives, so each broadcast is created and + /// announced then, and [`announce`](Self::announce) has nothing to do. + pub fn ts_programs(origin: moq_net::origin::Producer, name: String, config: moq_mux::catalog::Config) -> Self { + Self { + source: Source::Stream { + decoder: PublishDecoder::TsPrograms(Box::new(TsPrograms::new(origin, name, config))), + catalog: PublishCatalog::TsPrograms, + }, + broadcast: None, + } + } + /// Build a publisher capturing local devices (camera/screen and microphone). /// /// `bandwidth` is the uplink's send estimate, when there is one: the video @@ -336,14 +495,22 @@ impl Publish { anyhow::ensure!(video.is_some() || audio.is_some(), "nothing to capture"); Ok(Self { - source: Source::Capture { catalog, video, audio }, - broadcast, + source: Source::Capture { + broadcast: broadcast.clone(), + catalog, + video, + audio, + }, + broadcast: Some(broadcast), }) } /// Advertise the broadcast's path, now that the catalog tracks are in place. pub fn announce(&self) -> anyhow::Result<()> { - self.broadcast + let Some(broadcast) = &self.broadcast else { + return Ok(()); + }; + broadcast .announce(Default::default()) .context("failed to announce broadcast") } @@ -353,7 +520,12 @@ impl Publish { match self.source { Source::Stream { decoder, catalog } => decode(decoder, catalog, tokio::io::stdin()).await, #[cfg(feature = "capture")] - Source::Capture { catalog, video, audio } => { + Source::Capture { + broadcast, + catalog, + video, + audio, + } => { // Each enabled medium publishes its own track onto the shared // broadcast + catalog. Frames are stamped from the catalog's // advertised clock so HLS/DASH wall times match the mapping on @@ -363,7 +535,7 @@ impl Publish { // so it is `!Send`. let clock = catalog.clock(); let video_fut = { - let broadcast = self.broadcast.clone(); + let broadcast = broadcast.clone(); let catalog = catalog.clone(); async move { match video { @@ -376,21 +548,18 @@ impl Publish { } } }; - let audio_fut = { - let broadcast = self.broadcast.clone(); - async move { - match audio { - Some((config, encode)) => { - let mut options = moq_audio::encode::PublicationOptions::default(); - options.capture = config; - options.encode = encode; - options.clock = clock; - moq_audio::encode::publish_capture(broadcast, catalog, options) - .await - .map_err(anyhow::Error::from) - } - None => Ok(()), + let audio_fut = async move { + match audio { + Some((config, encode)) => { + let mut options = moq_audio::encode::PublicationOptions::default(); + options.capture = config; + options.encode = encode; + options.clock = clock; + moq_audio::encode::publish_capture(broadcast, catalog, options) + .await + .map_err(anyhow::Error::from) } + None => Ok(()), } }; @@ -711,7 +880,7 @@ mod tests { let broadcast = origin.create_broadcast("cli").unwrap(); broadcast.announce(Default::default()).unwrap(); settle().await; - let mut publish = Publish::new(broadcast, &PublishFormat::Ts, Default::default()).unwrap(); + let mut publish = Publish::new(broadcast, &PublishFormat::Ts { program: None }, Default::default()).unwrap(); #[allow(irrefutable_let_patterns)] let Source::Stream { decoder, .. } = &mut publish.source else { panic!("expected a stream source"); @@ -792,7 +961,7 @@ mod tests { let broadcast = moq_net::broadcast::Info::new().produce(); let consumer = broadcast.consume(); let config = moq_mux::catalog::Config::default().with_clock(clock); - let mut publish = Publish::new(broadcast, &PublishFormat::Ts, config).unwrap(); + let mut publish = Publish::new(broadcast, &PublishFormat::Ts { program: None }, config).unwrap(); #[allow(irrefutable_let_patterns)] let Source::Stream { decoder, .. } = &mut publish.source else { panic!("expected a stream source"); @@ -837,7 +1006,7 @@ mod tests { async fn eof_finishes_the_catalog_with_its_renditions() { let broadcast = moq_net::broadcast::Info::new().produce(); let consumer = broadcast.consume(); - let publish = Publish::new(broadcast, &PublishFormat::Ts, Default::default()).unwrap(); + let publish = Publish::new(broadcast, &PublishFormat::Ts { program: None }, Default::default()).unwrap(); let mut catalogs = hang::catalog::Catalog::<()>::subscribe(&consumer).await.unwrap(); #[allow(irrefutable_let_patterns)] @@ -862,6 +1031,175 @@ mod tests { assert_eq!(last.audio.renditions.len(), 1, "the audio rendition is still listed"); } + #[test] + fn program_broadcasts_keep_the_catalog_suffix_last() { + assert_eq!(program_broadcast("event.hang", 2), "event/2.hang"); + assert_eq!(program_broadcast("demo/event.msf", 7), "demo/event/7.msf"); + assert_eq!(program_broadcast("event", 1), "event/1"); + } + + /// A PAT listing two programs, then one MP2 PES of each: program 1 on PID `0x61` at 1 s + /// with fill bytes `0xAA`/`0xBB`, program 2 on PID `0x71` an hour later with `0xCC`/`0xDD`. + fn two_programs() -> Vec { + use mpeg2ts::es::StreamType; + use mpeg2ts::ts::payload::{Pat, Pmt}; + use mpeg2ts::ts::{ + ContinuityCounter, EsInfo, Pid, ProgramAssociation, TransportScramblingControl, TsHeader, TsPacket, + TsPacketWriter, TsPayload, VersionNumber, WriteTsPacket, + }; + + let write = |out: &mut Vec, pid: u16, payload: TsPayload| { + let packet = TsPacket { + header: TsHeader { + transport_error_indicator: false, + transport_priority: false, + pid: Pid::new(pid).unwrap(), + transport_scrambling_control: TransportScramblingControl::NotScrambled, + continuity_counter: ContinuityCounter::default(), + }, + adaptation_field: None, + payload: Some(payload), + }; + TsPacketWriter::new(out).write_ts_packet(&packet).unwrap(); + }; + let programs = [ + (1, 0x100, 0x61, 90_000, [0xAA, 0xBB]), + (2, 0x200, 0x71, 3_601 * 90_000, [0xCC, 0xDD]), + ]; + + let mut out = Vec::new(); + let pat = Pat { + transport_stream_id: 1, + version_number: VersionNumber::default(), + table: programs + .iter() + .map(|&(program_num, pmt_pid, ..)| ProgramAssociation { + program_num, + program_map_pid: Pid::new(pmt_pid).unwrap(), + }) + .collect(), + }; + write(&mut out, Pid::PAT, TsPayload::Pat(pat)); + for &(program_num, pmt_pid, es_pid, ..) in &programs { + let pmt = Pmt { + program_num, + pcr_pid: Some(Pid::new(es_pid).unwrap()), + version_number: VersionNumber::default(), + program_info: Vec::new(), + es_info: vec![EsInfo { + stream_type: StreamType::Mpeg1Audio, + elementary_pid: Pid::new(es_pid).unwrap(), + descriptors: Vec::new(), + }], + }; + write(&mut out, pmt_pid, TsPayload::Pmt(pmt)); + } + for &(_, _, es_pid, pts, fills) in &programs { + out.extend(mp2_pes_packet(es_pid, pts, fills)); + } + out + } + + /// One TS packet on `pid` holding a PES of two MP2 frames at `pts`, the second confirming + /// the first so the legacy path publishes it. + fn mp2_pes_packet(pid: u16, pts: u64, fills: [u8; 2]) -> Vec { + let mut payload = Vec::new(); + for fill in fills { + let mut frame = vec![0xFF, 0xF5, 0x18, 0xC0]; + frame.resize(72, fill); + payload.extend(frame); + } + let mut pes = vec![0x00, 0x00, 0x01, 0xc0]; + let len = 3 + 5 + payload.len(); + pes.extend([(len >> 8) as u8, len as u8, 0x80, 0x80, 0x05]); + pes.extend([ + 0x21 | (((pts >> 30) & 0x07) << 1) as u8, + (pts >> 22) as u8, + 0x01 | (((pts >> 15) & 0x7f) << 1) as u8, + (pts >> 7) as u8, + 0x01 | ((pts & 0x7f) << 1) as u8, + ]); + pes.extend(payload); + + let stuffing = 184 - 1 - pes.len(); + let mut packet = vec![0x47, 0x40 | (pid >> 8) as u8, pid as u8, 0x30, stuffing as u8]; + if stuffing > 0 { + packet.push(0x00); + packet.resize(5 + stuffing, 0xff); + } + packet.extend(pes); + assert_eq!(packet.len(), 188); + packet + } + + /// Plain `import ts` refuses a multiplex, naming its programs and the flag that picks one. + #[test] + fn a_multiplex_is_refused_with_the_programs_and_the_flag() { + let broadcast = moq_net::broadcast::Info::new().produce(); + let mut publish = Publish::new(broadcast, &PublishFormat::Ts { program: None }, Default::default()).unwrap(); + #[allow(irrefutable_let_patterns)] + let Source::Stream { decoder, .. } = &mut publish.source else { + panic!("expected a stream source"); + }; + let err = format!("{:#}", decoder.decode_chunk(&two_programs()).unwrap_err()); + assert!(err.contains("--program") && err.contains("programs (1, 2)"), "{err}"); + } + + /// `import ts --program all` holds the input until the PAT is whole, then publishes each + /// program as its own broadcast carrying only that program, live on its own first frame + /// rather than an hour apart on one shared clock. + #[tokio::test] + async fn every_program_publishes_its_own_broadcast() { + let origin = moq_tokio::origin::spawn(); + let ago = Duration::from_secs(60); + let clock = moq_mux::Clock::at(std::time::Instant::now() - ago, std::time::SystemTime::now() - ago).unwrap(); + let config = moq_mux::catalog::Config::default().with_clock(clock); + let publish = Publish::ts_programs(origin.clone(), "event.hang".to_string(), config); + let Source::Stream { + decoder: PublishDecoder::TsPrograms(mut programs), + .. + } = publish.source + else { + panic!("expected the per-program decoder"); + }; + + let input = two_programs(); + let before = clock.now(); + programs.decode(&input[..100]).unwrap(); + assert!( + programs.programs.is_empty(), + "no program is known before the PAT is whole" + ); + programs.decode(&input[100..]).unwrap(); + programs.finish().unwrap(); + let after = clock.now(); + + for (path, fills) in [("event/1.hang", [0xAA, 0xBB]), ("event/2.hang", [0xCC, 0xDD])] { + let consumer = moq_mux::Source::new(origin.consume(), path).broadcast().await.unwrap(); + let catalog = hang::catalog::Catalog::<()>::subscribe(&consumer) + .await + .unwrap() + .next() + .await + .unwrap() + .expect("a catalog"); + let renditions: Vec<_> = catalog.audio.renditions.iter().collect(); + assert_eq!(renditions.len(), 1, "{path} carries its own program's one stream"); + let (name, config) = renditions[0]; + let track = consumer.track(name).unwrap().subscribe(None).await.unwrap(); + let container = Container::try_from(config).unwrap(); + let frame = Consumer::new(track, container).read().await.unwrap().expect("a frame"); + assert!(fills.contains(&frame.payload[4]), "{path} carries only its own program"); + let skew = Duration::from_secs(2).as_micros(); + assert!( + before.as_micros() - skew <= frame.timestamp.as_micros() + && frame.timestamp.as_micros() <= after.as_micros() + skew, + "{path} is live on arrival: {:?} not in {before:?}..={after:?}", + frame.timestamp + ); + } + } + /// Read the first frame of a verbatim track back as raw bytes. async fn read_frame(consumer: &moq_net::broadcast::Consumer, name: &str) -> Vec { let track = consumer.track(name).unwrap().subscribe(None).await.unwrap(); diff --git a/rs/moq-mux/src/container/ts/import.rs b/rs/moq-mux/src/container/ts/import.rs index 6b386339744..d23e1160ef5 100644 --- a/rs/moq-mux/src/container/ts/import.rs +++ b/rs/moq-mux/src/container/ts/import.rs @@ -139,6 +139,9 @@ pub struct Import { /// The source's mapping onto the broadcast clock, set by [`live`](Self::live). `None` /// publishes the source's unwrapped PTS verbatim. anchor: Option, + /// The program number chosen by [`with_program`](Self::with_program). `None` imports the + /// multiplex's only program and refuses a PAT that lists more than one. + program: Option, } impl Import { @@ -183,9 +186,20 @@ impl Import { last_pts: None, media_unwrap: PtsUnwrap::default(), anchor: None, + program: None, } } + /// Import only the program numbered `program` in the PAT, ignoring the rest of the multiplex. + /// + /// Without this, a PAT that lists more than one program fails the import with + /// [`MultipleProgramsError`] rather than merging them onto one clock. A PAT that does not + /// list `program` fails it too. + pub fn with_program(mut self, program: u16) -> Self { + self.program = Some(program); + self + } + /// Publish on the broadcast clock rather than the source's own PTS. /// /// For a live feed with its own zero: the first frame is live on arrival, every elementary @@ -385,6 +399,10 @@ impl Import { let pid = packet.header.pid; match packet.payload { Some(TsPayload::Pmt(pmt)) => { + // PMTs of several programs may share one PID; only the chosen one maps streams. + if self.program.is_some_and(|program| program != pmt.program_num) { + return Ok(()); + } // Which PID speaks for the program clock, so a `discontinuity_indicator` there // can be read as a timebase reset rather than a counter jump. if self.pcr_pid != pmt.pcr_pid { @@ -440,12 +458,7 @@ impl Import { } Some(TsPayload::PesStart(pes)) => self.handle_pes_start(pid, pes)?, Some(TsPayload::PesContinuation(bytes)) => self.handle_pes_continuation(pid, &bytes)?, - // Learn the PMT PIDs so the routing gate in `decode` lets them through. - Some(TsPayload::Pat(pat)) => { - self.pmt_pids - .extend(pat.table.iter().map(|entry| entry.program_map_pid)); - self.record_program_identity(&pat)?; - } + Some(TsPayload::Pat(pat)) => self.handle_pat(&pat)?, _ => {} } Ok(()) @@ -849,19 +862,46 @@ impl Import { Ok(()) } + /// Pick the imported program from a PAT and learn its PMT PID, so the routing gate in + /// `decode` lets that PMT through and no other. + /// + /// Every PAT is checked, so a program added mid-stream ends an unselected import, and a + /// selected program that disappears ends a selected one; media already published stays. + fn handle_pat(&mut self, pat: &mpeg2ts::ts::payload::Pat) -> anyhow::Result<()> { + // program_number 0 is the network PID association, not a program. + let programs: Vec<_> = pat.table.iter().filter(|entry| entry.program_num != 0).collect(); + let numbers = || programs.iter().map(|entry| entry.program_num).collect::>(); + let entry = match self.program { + Some(program) => match programs.iter().find(|entry| entry.program_num == program) { + Some(entry) => entry, + None => anyhow::bail!( + "transport stream has no program {program}; its PAT lists {}", + list_programs(&numbers()) + ), + }, + None => match programs.as_slice() { + [] => return Ok(()), + [entry] => entry, + _ => return Err(MultipleProgramsError { programs: numbers() }.into()), + }, + }; + self.pmt_pids.insert(entry.program_map_pid); + self.record_program_identity(pat.transport_stream_id, entry) + } + /// Capture the transport/service identity (TSID, service number, PMT PID) from the /// PAT into the catalog service record, once. No-op without `mpegts` support. - fn record_program_identity(&mut self, pat: &mpeg2ts::ts::payload::Pat) -> anyhow::Result<()> { + fn record_program_identity( + &mut self, + transport_stream_id: u16, + entry: &mpeg2ts::ts::ProgramAssociation, + ) -> anyhow::Result<()> { if !self.supports_mpegts || self.identity_recorded { return Ok(()); } - // program_number 0 is the network PID association, not a service; skip it. - let Some(entry) = pat.table.iter().find(|entry| entry.program_num != 0) else { - return Ok(()); - }; if let Some(mpegts) = self.catalog.modify()?.ext.mpegts_mut() { let program = mpegts.program.get_or_insert_with(Default::default); - program.transport_stream_id = pat.transport_stream_id; + program.transport_stream_id = transport_stream_id; program.program_number = entry.program_num; program.pmt_pid = entry.program_map_pid.as_u16(); } @@ -957,6 +997,51 @@ impl Import { } } +/// A PAT listed more than one program, and the [`Import`] was not told which one to take. +/// +/// Importing them all onto one broadcast would put unrelated clocks on one timeline, so the +/// import stops instead. Pick one with [`Import::with_program`]. +#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)] +#[error("transport stream carries {} programs ({})", .programs.len(), list_programs(.programs))] +pub struct MultipleProgramsError { + /// The program numbers the PAT lists, in PAT order. + pub programs: Vec, +} + +fn list_programs(programs: &[u16]) -> String { + programs.iter().map(u16::to_string).collect::>().join(", ") +} + +/// The program numbers listed by the first whole PAT in `data`, in PAT order, or `None` if +/// there is none yet. +/// +/// For choosing importers before any exists: each [`Import`] reads the PAT itself. +pub fn programs(data: &[u8]) -> Option> { + let mut off = 0; + while let Some(rel) = memchr::memchr(0x47, &data[off..]) { + off += rel; + let packet = data.get(off..off + TsPacket::SIZE)?; + // PID 0 opening a section. The section CRC rejects a sync byte found in payload. + if packet[1] & 0x5f == 0x40 + && packet[2] == 0 + && let Ok(Some(TsPacket { + payload: Some(TsPayload::Pat(pat)), + .. + })) = TsPacketReader::new(packet).read_ts_packet() + { + return Some( + pat.table + .iter() + .map(|entry| entry.program_num) + .filter(|&program| program != 0) + .collect(), + ); + } + off += 1; + } + None +} + /// What each demuxed elementary stream delivered, and the audio frame sync it lost or could /// not verify, keyed by elementary stream PID. /// @@ -3288,23 +3373,34 @@ mod test { /// /// The clock rides the first elementary stream, as a real mux puts it on the video. fn synth_pmt(es: &[(StreamType, u16)], cuei: bool) -> Vec { + synth_programs(&[(1, 0x0100, es)], cuei) + } + + /// A program to synthesize: `(program_num, pmt_pid, [(stream_type, pid)])`. + type SynthProgram<'a> = (u16, u16, &'a [(StreamType, u16)]); + + /// Serialize one PAT listing every program, then each program's PMT, as [`synth_pmt`] + /// does for one. + fn synth_programs(programs: &[SynthProgram], cuei: bool) -> Vec { use mpeg2ts::ts::payload::{Pat, Pmt}; use mpeg2ts::ts::{ ContinuityCounter, Descriptor, EsInfo, Pid, ProgramAssociation, TransportScramblingControl, TsHeader, TsPacket, TsPacketWriter, TsPayload, VersionNumber, WriteTsPacket, }; - const PMT_PID: u16 = 0x0100; let pat = Pat { transport_stream_id: 1, version_number: VersionNumber::default(), - table: vec![ProgramAssociation { - program_num: 1, - program_map_pid: Pid::new(PMT_PID).unwrap(), - }], + table: programs + .iter() + .map(|&(program_num, pmt_pid, _)| ProgramAssociation { + program_num, + program_map_pid: Pid::new(pmt_pid).unwrap(), + }) + .collect(), }; - let pmt = Pmt { - program_num: 1, + let pmt = |program_num: u16, es: &[(StreamType, u16)]| Pmt { + program_num, pcr_pid: es.first().map(|&(_, pid)| Pid::new(pid).unwrap()), version_number: VersionNumber::default(), program_info: if cuei { @@ -3342,7 +3438,9 @@ mod test { let mut out = Vec::new(); write(&mut out, Pid::PAT, TsPayload::Pat(pat)); - write(&mut out, PMT_PID, TsPayload::Pmt(pmt)); + for &(program_num, pmt_pid, es) in programs { + write(&mut out, pmt_pid, TsPayload::Pmt(pmt(program_num, es))); + } out } @@ -5324,6 +5422,99 @@ mod test { out } + /// A two-program multiplex whose clocks sit an hour apart: program 1's MP2 on + /// `0x0061` starts at 1 s, program 2's on `0x0071` at 3601 s. + fn two_programs() -> Vec { + let mut data = synth_programs( + &[ + (1, 0x0100, &[(StreamType::Mpeg1Audio, 0x0061)]), + (2, 0x0200, &[(StreamType::Mpeg1Audio, 0x0071)]), + ], + false, + ); + data.extend(mp2_pes(0x0061, 0, 90_000, [0xAA, 0xBB])); + data.extend(mp2_pes(0x0071, 0, 3_601 * 90_000, [0xCC, 0xDD])); + data + } + + #[test] + fn a_multi_program_input_is_refused_before_publishing() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + let mut import = super::Import::new(broadcast, catalog.reserve()); + + let err = import.decode(&two_programs()).unwrap_err(); + assert_eq!( + err.downcast_ref::(), + Some(&super::MultipleProgramsError { programs: vec![1, 2] }), + "{err:#}" + ); + assert!(catalog.snapshot().audio.renditions.is_empty(), "nothing was published"); + } + + #[test] + fn a_program_added_mid_stream_ends_the_import() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + let mut import = super::Import::new(broadcast, catalog.reserve()); + import + .decode(&synth_pmt(&[(StreamType::Mpeg1Audio, 0x0061)], false)) + .unwrap(); + import.decode(&mp2_pes(0x0061, 0, 90_000, [0xAA, 0xBB])).unwrap(); + + let err = import.decode(&two_programs()).unwrap_err(); + assert!(err.downcast_ref::().is_some(), "{err:#}"); + assert_eq!( + catalog.snapshot().audio.renditions.len(), + 1, + "program 1 stays published" + ); + } + + #[tokio::test(start_paused = true)] + async fn a_selected_program_publishes_only_its_streams_on_its_clock() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let consumer = broadcast.consume(); + let catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + let mut import = super::Import::new(broadcast, catalog.reserve()).with_program(2); + import.decode(&two_programs()).unwrap(); + import.finish().unwrap(); + + let snapshot = catalog.snapshot(); + let names: Vec<_> = snapshot.audio.renditions.keys().collect(); + assert_eq!(names.len(), 1, "only program 2's stream: {names:?}"); + let (frames, _) = read_breaks(&consumer, names[0]).await; + assert!(!frames.is_empty(), "program 2 published"); + assert!( + frames + .iter() + .all(|frame| frame.payload[4] == 0xCC || frame.payload[4] == 0xDD), + "no program 1 frame leaks in" + ); + assert_eq!(frames[0].timestamp.as_micros(), 3_601_000_000, "program 2's own PTS"); + } + + #[test] + fn a_selected_program_the_pat_does_not_list_is_refused() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + let mut import = super::Import::new(broadcast, catalog.reserve()).with_program(3); + + let err = import.decode(&two_programs()).unwrap_err().to_string(); + assert!(err.contains("no program 3") && err.contains("1, 2"), "{err}"); + } + + #[test] + fn programs_reads_the_first_whole_pat() { + let data = two_programs(); + assert_eq!(super::programs(&data), Some(vec![1, 2])); + // A sync byte in leading junk is skipped; a truncated PAT is not a PAT yet. + let mut shifted = vec![0x47, 0x40, 0x00, 0x10]; + shifted.extend_from_slice(&data); + assert_eq!(super::programs(&shifted), Some(vec![1, 2])); + assert_eq!(super::programs(&data[..100]), None); + } + /// Two MP2 renditions, the first of which the PMT designates as the PCR PID. const PCR_PID: u16 = 0x0061; const PEER_PID: u16 = 0x0062; From 684d3c7b2db1254b97a4dd3d56cd0994a9f40cc7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 13:21:10 -0700 Subject: [PATCH 040/128] fix(tokio): drive raw stream handshakes per connection (#4474) Co-authored-by: Codex Co-authored-by: Claude Opus 5.5 --- rs/moq-tokio/src/server.rs | 223 ++++++++++++++++++++++++++++--------- rs/moq-tokio/src/tcp.rs | 24 ++-- rs/moq-tokio/src/unix.rs | 27 +++-- 3 files changed, 200 insertions(+), 74 deletions(-) diff --git a/rs/moq-tokio/src/server.rs b/rs/moq-tokio/src/server.rs index 451b8dd17bf..bb76de16430 100644 --- a/rs/moq-tokio/src/server.rs +++ b/rs/moq-tokio/src/server.rs @@ -881,8 +881,8 @@ impl StreamBind { /// Bound by [`Server::bind`] (they need a runtime). [`Server::listen`] then starts /// each accept loop; a bind-only listener starts them on the first /// [`Listener::accept`] instead. Each loop feeds completed [`Request`]s back over -/// a channel. The tasks own their listeners and are stopped when the [`Listener`] -/// closes or drops, so bound sockets don't linger. +/// a channel. The tasks own their listeners and in-flight handshakes, and are +/// stopped when the [`Listener`] closes or drops, so no socket lingers. #[cfg(any(feature = "tcp", all(feature = "uds", unix)))] struct StreamListeners { binds: Vec, @@ -1038,21 +1038,31 @@ fn spawn_tcp_loop( ) -> tokio::task::JoinHandle<()> { let local = listener.local_addr().ok(); tokio::spawn(async move { + // Owned by the loop so stopping it (listener close or drop) also aborts + // every in-flight handshake, releasing its socket. + let mut handshakes = tokio::task::JoinSet::new(); loop { - match listener.accept_with_addr().await { - Some(Ok((session, remote))) => { - let link = Link { - remote: Some(remote), - local, - ..Default::default() - }; - spawn_stream_request(session, Transport::Tcp, link, server.clone(), tx.clone()) + let pending = tokio::select! { + pending = listener.accept_pending() => pending, + Some(_) = handshakes.join_next() => continue, + }; + let server = server.clone(); + let tx = tx.clone(); + handshakes.spawn(async move { + match pending.await { + Ok((session, remote)) => { + let link = Link { + remote: Some(remote), + local, + ..Default::default() + }; + stream_request(session, Transport::Tcp, link, server, tx).await + } + // Per-connection: a failed `accept(2)` is the listener's own to + // classify and pace, and never surfaces here. + Err(err) => tracing::warn!(%err, "tcp qmux handshake failed"), } - // Per-connection: a failed `accept(2)` is the listener's own to - // classify and pace, and never surfaces here. - Some(Err(err)) => tracing::warn!(%err, "tcp qmux handshake failed"), - None => break, - } + }); } }) } @@ -1065,58 +1075,65 @@ fn spawn_unix_loop( tx: tokio::sync::mpsc::Sender, ) -> tokio::task::JoinHandle<()> { tokio::spawn(async move { + // Owned by the loop, as in `spawn_tcp_loop`. + let mut handshakes = tokio::task::JoinSet::new(); loop { - match listener.accept().await { - Some(Ok((session, cred))) => { - // Enforce the allowlist (if any) before reading SETUP bytes from the peer. - if let Some(allow) = &allow - && !allow.permits(&cred) - { - tracing::warn!(uid = cred.uid, gid = cred.gid, pid = ?cred.pid, "unix connection rejected by allow list"); - continue; + let pending = tokio::select! { + pending = listener.accept_pending() => pending, + Some(_) = handshakes.join_next() => continue, + }; + let server = server.clone(); + let tx = tx.clone(); + let allow = allow.clone(); + handshakes.spawn(async move { + match pending.await { + Ok((session, cred)) => { + // Enforce the allowlist (if any) before reading SETUP bytes from the peer. + if let Some(allow) = &allow + && !allow.permits(&cred) + { + tracing::warn!(uid = cred.uid, gid = cred.gid, pid = ?cred.pid, "unix connection rejected by allow list"); + return; + } + stream_request(session, Transport::Unix, Link::default(), server, tx).await; } - spawn_stream_request(session, Transport::Unix, Link::default(), server.clone(), tx.clone()); + // Per-connection, as in `spawn_tcp_loop`. + Err(err) => tracing::warn!(%err, "unix qmux handshake failed"), } - // Per-connection, as in `spawn_tcp_loop`. - Some(Err(err)) => tracing::warn!(%err, "unix qmux handshake failed"), - None => break, - } + }); } }) } -/// Read the SETUP from an accepted stream session (concurrently, so one slow or -/// malicious peer doesn't stall the listener) and forward the resulting request. +/// Read SETUP in the connection task and forward the resulting request. #[cfg(any(feature = "tcp", all(feature = "uds", unix)))] -fn spawn_stream_request( +async fn stream_request( session: qmux::Session, transport: Transport, link: Link, server: moq_net::Server, tx: tokio::sync::mpsc::Sender, ) { - tokio::spawn(async move { - match server - .accept_request( - tokio::time::Instant::now().into_std(), - crate::transport::Session::new(session), - ) - .await - { - Ok(request) => { - let request = Request { - transport, - url: None, - authority: None, - identity: None, - link, - kind: RequestKind::Qmux(Box::new(request)), - }; - let _ = tx.send(request).await; - } - Err(err) => tracing::debug!(%err, "stream SETUP handshake failed"), + match server + .accept_request( + tokio::time::Instant::now().into_std(), + crate::transport::Session::new(session), + ) + .await + { + Ok(request) => { + let request = Request { + transport, + url: None, + authority: None, + identity: None, + link, + kind: RequestKind::Qmux(Box::new(request)), + }; + let _ = tx.send(request).await; } - }); + Err(err) => tracing::debug!(%err, "stream SETUP handshake failed"), + } } /// An accepted connection whose MoQ SETUP has already been exchanged. @@ -1508,6 +1525,108 @@ impl Request { mod tests { use super::*; + /// The second handshake must finish while the first peer is still stalled. + /// Reading the first server bytes proves it reached the handshake before we + /// connect the second peer; EOF would mean its handshake already failed. + #[cfg(feature = "tcp")] + #[tokio::test] + async fn tcp_stalled_handshake_does_not_block_accept() { + use tokio::io::AsyncReadExt; + let listener = crate::tcp::Listener::bind("127.0.0.1:0".parse().unwrap()) + .await + .unwrap() + .with_protocols(["moq-lite-06"]); + let addr = listener.local_addr().unwrap(); + let (tx, _rx) = tokio::sync::mpsc::channel(1); + let task = spawn_tcp_loop(listener, moq_net::Server::new(), tx); + let mut stalled = tokio::net::TcpStream::connect(addr).await.unwrap(); + stalled.read_u8().await.expect("first handshake started"); + let mut remaining = Vec::new(); + tokio::select! { + biased; + _ = stalled.read_to_end(&mut remaining) => panic!("first handshake ended before second completed"), + result = qmux::tcp::Config::new(qmux::Version::QMux01) + .protocols(["moq-lite-06"]).connect(addr) => { + result.expect("second handshake completes"); + } + } + task.abort(); + let _ = task.await; + } + + #[cfg(all(feature = "uds", unix))] + #[tokio::test] + async fn unix_stalled_handshake_does_not_block_accept() { + use tokio::io::AsyncReadExt; + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("listener.sock"); + let listener = crate::unix::Listener::bind(&path) + .await + .unwrap() + .with_protocols(["moq-lite-06"]); + let (tx, _rx) = tokio::sync::mpsc::channel(1); + let task = spawn_unix_loop(listener, moq_net::Server::new(), None, tx); + let mut stalled = tokio::net::UnixStream::connect(&path).await.unwrap(); + stalled.read_u8().await.expect("first handshake started"); + let mut remaining = Vec::new(); + tokio::select! { + biased; + _ = stalled.read_to_end(&mut remaining) => panic!("first handshake ended before second completed"), + result = qmux::uds::Config::new(qmux::Version::QMux01) + .protocols(["moq-lite-06"]).connect(&path) => { + result.expect("second handshake completes"); + } + } + task.abort(); + let _ = task.await; + } + + /// Stopping the accept loop must drop a stalled handshake at once. Each + /// handshake task holds a `tx` clone, so the channel closes only when they are + /// all gone. Time pauses only once the socket I/O is done (a paused runtime + /// waiting on the kernel would skip ahead to qmux's own handshake timeout), so + /// a leaked task leaves the runtime idle and fires the 1s timeout first. + #[cfg(feature = "tcp")] + #[tokio::test] + async fn tcp_stop_aborts_stalled_handshake() { + use tokio::io::AsyncReadExt; + let listener = crate::tcp::Listener::bind("127.0.0.1:0".parse().unwrap()) + .await + .unwrap() + .with_protocols(["moq-lite-06"]); + let addr = listener.local_addr().unwrap(); + let (tx, mut rx) = tokio::sync::mpsc::channel(1); + let task = spawn_tcp_loop(listener, moq_net::Server::new(), tx); + let mut stalled = tokio::net::TcpStream::connect(addr).await.unwrap(); + stalled.read_u8().await.expect("handshake started"); + tokio::time::pause(); + task.abort(); + let _ = task.await; + let closed = tokio::time::timeout(std::time::Duration::from_secs(1), rx.recv()).await; + assert!(matches!(closed, Ok(None)), "stalled handshake outlived its accept loop"); + } + + #[cfg(all(feature = "uds", unix))] + #[tokio::test] + async fn unix_stop_aborts_stalled_handshake() { + use tokio::io::AsyncReadExt; + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("listener.sock"); + let listener = crate::unix::Listener::bind(&path) + .await + .unwrap() + .with_protocols(["moq-lite-06"]); + let (tx, mut rx) = tokio::sync::mpsc::channel(1); + let task = spawn_unix_loop(listener, moq_net::Server::new(), None, tx); + let mut stalled = tokio::net::UnixStream::connect(&path).await.unwrap(); + stalled.read_u8().await.expect("handshake started"); + tokio::time::pause(); + task.abort(); + let _ = task.await; + let closed = tokio::time::timeout(std::time::Duration::from_secs(1), rx.recv()).await; + assert!(matches!(closed, Ok(None)), "stalled handshake outlived its accept loop"); + } + #[test] fn version_help_lists_every_parseable_name() { #[derive(usage::Cli)] diff --git a/rs/moq-tokio/src/tcp.rs b/rs/moq-tokio/src/tcp.rs index b94d5266f77..b2753886331 100644 --- a/rs/moq-tokio/src/tcp.rs +++ b/rs/moq-tokio/src/tcp.rs @@ -233,21 +233,23 @@ impl Listener { /// loop, so this always yields. It stays because dropping it is a breaking change /// to a published signature. pub async fn accept(&self) -> Option> { - self.accept_with_addr() - .await - .map(|result| result.map(|(session, _)| session)) + Some(self.accept_pending().await.await.map(|(session, _)| session)) } - /// Accept the next connection and retain the peer's address. - pub(crate) async fn accept_with_addr(&self) -> Option> { + /// Accept a socket and return its independently driven qmux handshake. + pub(crate) async fn accept_pending( + &self, + ) -> impl Future> + use<> { let (stream, addr) = self.accept_socket().await; tracing::debug!(%addr, "accepted TCP connection"); - let session = qmux::tcp::Config::new(WIRE_VERSION) - .protocols(self.protocols.iter().map(String::as_str)) - .accept(stream) - .await - .map_err(|err| Error::Accept(crate::error::message(err))); - Some(session.map(|session| (session, addr))) + let config = qmux::tcp::Config::new(WIRE_VERSION).protocols(self.protocols.iter().map(String::as_str)); + async move { + let session = config + .accept(stream) + .await + .map_err(|err| Error::Accept(crate::error::message(err)))?; + Ok((session, addr)) + } } /// The `accept(2)` half: keep asking until a connection comes back. diff --git a/rs/moq-tokio/src/unix.rs b/rs/moq-tokio/src/unix.rs index 15fa1d954fe..6b857cb051c 100644 --- a/rs/moq-tokio/src/unix.rs +++ b/rs/moq-tokio/src/unix.rs @@ -348,21 +348,26 @@ impl Listener { /// /// As in [`crate::tcp`], the `Option` has no `None` case left to report. pub async fn accept(&self) -> Option> { + Some(self.accept_pending().await.await) + } + + /// Accept a socket and return its independently driven qmux handshake. + pub(crate) async fn accept_pending(&self) -> impl Future> + use<> { let stream = self.accept_socket().await; - let cred = match stream.peer_cred() { - Ok(cred) => PeerCred { + let config = qmux::uds::Config::new(WIRE_VERSION).protocols(self.protocols.iter().map(String::as_str)); + async move { + let cred = stream.peer_cred()?; + let cred = PeerCred { uid: cred.uid(), gid: cred.gid(), pid: cred.pid(), - }, - Err(err) => return Some(Err(err.into())), - }; - let session = qmux::uds::Config::new(WIRE_VERSION) - .protocols(self.protocols.iter().map(String::as_str)) - .accept(stream) - .await - .map_err(|err| Error::Accept(crate::error::message(err))); - Some(session.map(|session| (session, cred))) + }; + let session = config + .accept(stream) + .await + .map_err(|err| Error::Accept(crate::error::message(err)))?; + Ok((session, cred)) + } } /// The `accept(2)` half: keep asking until a connection comes back. From 0676be8305114241419e1e00139959fcd9508143 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 13:21:14 -0700 Subject: [PATCH 041/128] chore(quest): abandon sub-millisecond wall clock (#4449) Co-authored-by: Claude Opus 5.5 --- quest/m1/README.md | 1 - quest/m1/catalog-wall-clock.md | 28 ---------------------------- quest/m1/remove-live.md | 1 - 3 files changed, 30 deletions(-) delete mode 100644 quest/m1/catalog-wall-clock.md diff --git a/quest/m1/README.md b/quest/m1/README.md index c1dd03c88fe..80888ca183d 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -54,7 +54,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [TS import shared shift](/quest/m1/ts-import-shared-shift.md) - unflagged loop wraps move audio and video by one shift, so A/V sync holds across wraps - [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) - `import ts` reads a PAT or PMT that spans packets or follows a nonzero pointer_field instead of aborting, and one corrupted section costs a repetition and a counted `CRC_error`, not the import - [Same-hop importers](/quest/m1/hop-aligned-import.md) - importers sharing a `--hop` and fed one stream publish identical groups and timestamps, so failover survives -- [Catalog wall clock](/quest/m1/catalog-wall-clock.md) - `Clock::wall_clock` keeps the catalog's full precision instead of truncating to milliseconds - [Capture control](/quest/m1/capture-control.md) - on dev, `encode::Capture` replaces `CaptureOptions` without a `clock` field (it reads the catalog's), an unsupported `cut()` errors, and dropping the last `Control` cancels in-flight opens - [Video surface](/quest/m1/video-surface.md) - on dev, moq-ffi's `native` becomes `surface`, refused on platforms with no surface - [HLS discontinuity sequence](/quest/m1/hls-discontinuity-sequence.md) - on dev, `Segment::discontinuity` is the absolute sequence, so every cursor agrees diff --git a/quest/m1/catalog-wall-clock.md b/quest/m1/catalog-wall-clock.md deleted file mode 100644 index 1b25deeeef9..00000000000 --- a/quest/m1/catalog-wall-clock.md +++ /dev/null @@ -1,28 +0,0 @@ -# [XS] Catalog wall clock keeps sub-millisecond precision - -## Goal - -`hang::catalog::Clock::wall_clock` returns the wall time at the precision the -catalog carries, not truncated to milliseconds. The wire field is `{ wall, -timescale }` with a `u32` timescale defaulting to microseconds, and `pts` -arrives at its own timescale, but `wall_clock` divides down to Unix -milliseconds before building the `SystemTime`, which holds nanoseconds. The -capture clock fixtures from [#4125](https://github.com/moq-dev/moq/pull/4125) -assert at millisecond precision because of it. - -## Plan - -- Rust: compute the offset from the moq epoch in nanoseconds (or as a - `Duration` from whole seconds plus the remainder at the clock's timescale) - and add it to `UNIX_EPOCH + MOQ_EPOCH_UNIX_MILLIS`. Keep the existing - overflow and JSON-safe range checks. Tighten the fixtures that currently - assert milliseconds. -- JS: `wallClockTime` in `js/hang/src/catalog/clock.ts` returns a `Date`, - which only holds milliseconds. Leave its return type alone unless a caller - needs more; note the platform limit in its doc so the two sides are not - mistaken for a mismatch. -- Callers that format the value (HLS `EXT-X-PROGRAM-DATE-TIME`, DASH - `availabilityStartTime`) choose their own output precision; check none - relied on the truncation. - -Public API and wire: none. diff --git a/quest/m1/remove-live.md b/quest/m1/remove-live.md index 99c040ec2c7..80be20255df 100644 --- a/quest/m1/remove-live.md +++ b/quest/m1/remove-live.md @@ -46,5 +46,4 @@ replace `ts_import_publishes_on_the_broadcast_clock` in moq-cli. ## Related - [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - the new epoch an encoder restart becomes -- [Catalog wall clock](/quest/m1/catalog-wall-clock.md) - the PTS-to-wall conversion this relies on, at full precision - [TS import shared shift](/quest/m1/ts-import-shared-shift.md) - the TS re-anchor shift that must stay input-derived From ec494f3fae1041802f3c2ff52bc239f11333eb6f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 13:23:23 -0700 Subject: [PATCH 042/128] chore(quest): plan MessageChannel between worker and audio worklet (#4532) Co-authored-by: Claude Opus 5.5 --- quest/m1/plan-watch-worker.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/quest/m1/plan-watch-worker.md b/quest/m1/plan-watch-worker.md index f632211053c..94f8afb7a61 100644 --- a/quest/m1/plan-watch-worker.md +++ b/quest/m1/plan-watch-worker.md @@ -35,9 +35,14 @@ Prototype both models on the same pipeline and measure them against each other: Settled constraints either way: - `AudioContext` and the render worklet stay on main. The worklet's ring - endpoint (the `SharedArrayBuffer` ring, or a `MessagePort` straight to the - worklet on the postMessage path) is handed to the worker so decoded PCM - never transits main, and the playhead reaches `Sync` the same way. + endpoint is handed to the worker so decoded PCM never transits main, and + the playhead reaches `Sync` the same way. With `SharedArrayBuffer` that is + the shared ring. Without it, main creates a `MessageChannel` and transfers + one port to the worker and the other to the worklet (over `node.port`); PCM + and playhead state then flow worker to worklet and back on that channel. + This keeps the non-isolated path immune to main-thread jank without + COOP/COEP. A transferred `ReadableStream` is not an alternative: it is + postMessage underneath, and the worklet would still drain it into its ring. - `Sync` lives in the worker. Main-thread readers (captions, UI) observe it through the bridge. - `IntersectionObserver`, `visibilitychange`, and the element's size stay on @@ -62,7 +67,9 @@ shape of `Player` and ``, what happens to the composable classes, the worker bundling (the publish capture worker's `?worker&inline` is the precedent; like it, the worker ships a lazy blob plus a hostable file under the package's assets base, per [strict CSP](/quest/m1/csp-assets.md)), and the follow-up -quest for moving publish onto the same worker if the handle model wins. +quest for moving publish onto the same worker if the handle model wins. That +follow-up wires the capture worklet to the encoder worker with a +`MessageChannel` too, so captured PCM also skips main. ## Related From 1511f7571348125f61cd64f9247388e82c1c02cf Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 13:26:06 -0700 Subject: [PATCH 043/128] chore(quest): claim quest/m1/publish-codec-string From e24828a601611b08daacbf8c0564572582e9ef80 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 13:34:21 -0700 Subject: [PATCH 044/128] fix(publish): advertise the codec string the video encoder reports Drop the bare avc1/vp09/av01/hev1 probe hints, which every browser refuses, and follow EncodedVideoChunkMetadata.decoderConfig.codec in the catalog. Co-Authored-By: Claude Opus 5.5 --- js/publish/src/video/encoder.test.ts | 138 +++++++++++++++++++++++++++ js/publish/src/video/encoder.ts | 29 ++++-- quest/m1/README.md | 1 - quest/m1/publish-codec-string.md | 37 ------- 4 files changed, 157 insertions(+), 48 deletions(-) delete mode 100644 quest/m1/publish-codec-string.md diff --git a/js/publish/src/video/encoder.test.ts b/js/publish/src/video/encoder.test.ts index 14124fb7021..ffd6a2714c2 100644 --- a/js/publish/src/video/encoder.test.ts +++ b/js/publish/src/video/encoder.test.ts @@ -569,3 +569,141 @@ test.each(["encoder lag", "quiet startup"])("marks a rendition stalled for %s", else Reflect.deleteProperty(globalThis, "VideoEncoder"); } }); + +// Every browser refuses a bare hint, so probing one only delays the fallback, and a browser that +// accepted it would publish a codec no native player can decode. +test("the probe only offers full codec strings", async () => { + using _videoEncoder = installFakeVideoEncoder(); + const probe = spyOn(FakeVideoEncoder, "isConfigSupported").mockImplementation(async () => ({ supported: false })); + const error = spyOn(console, "error").mockImplementation(() => {}); + const capture = { + in: { source: new Signal({ getSettings: () => ({ frameRate: 30 }), getConstraints: () => ({}) }) }, + out: { display: new Signal({ width: 1280, height: 720 }) }, + }; + const encoder = new Encoder("video", { enabled: true, capture: capture as never }); + try { + await settle(); + const probed = probe.mock.calls.map(([config]) => config.codec); + expect(probed.length).toBeGreaterThan(0); + expect(probed.filter((codec) => codec !== "vp8" && !codec.includes("."))).toEqual([]); + expect(encoder.settled.peek()).toBe(true); + } finally { + encoder.close(); + probe.mockRestore(); + error.mockRestore(); + } +}); + +test("the catalog advertises the codec string the encoder reports", async () => { + // Refine the configured string like Safari does, reporting the profile the encoder chose. + const REPORTED: Record = { + "avc1.640028": "avc1.64001F", + "vp09.00.10.08": "vp09.00.31.08", + }; + + class ReportingVideoEncoder { + state: CodecState = "unconfigured"; + #output: VideoEncoderInit["output"]; + #codec?: string; + #fresh = false; + + constructor(init: VideoEncoderInit) { + this.#output = init.output; + } + + static async isConfigSupported(config: VideoEncoderConfig): Promise<{ supported: boolean }> { + return { supported: config.codec in REPORTED }; + } + + configure(config: VideoEncoderConfig): void { + this.state = "configured"; + this.#codec = config.codec; + this.#fresh = true; + } + + encode(frame: VideoFrame): void { + const chunk = { type: "key", timestamp: frame.timestamp, byteLength: 1, copyTo: () => {} }; + const metadata = this.#fresh && this.#codec ? { decoderConfig: { codec: REPORTED[this.#codec] } } : {}; + this.#fresh = false; + this.#output(chunk as never, metadata as never); + } + + close(): void { + this.state = "closed"; + } + } + + const original = Object.getOwnPropertyDescriptor(globalThis, "VideoEncoder"); + Object.defineProperty(globalThis, "VideoEncoder", { + configurable: true, + value: ReportingVideoEncoder, + writable: true, + }); + + const { Fanout } = await import("../fanout"); + let controller!: ReadableStreamDefaultController; + const stream = new ReadableStream({ + start: (c) => { + controller = c; + }, + }); + const fanout = new Fanout(stream, { clone: (frame) => ({ timestamp: frame.timestamp, close: () => {} }) as never }); + let timestamp = 0; + const push = async () => { + controller.enqueue({ timestamp, close: () => {} } as never); + timestamp += 33_333; + await new Promise((resolve) => setTimeout(resolve, 10)); + }; + + const track = new Moq.Track.Producer("video").accept({ priority: 60 }); + const sub = track.subscribe(); + const rendition = { + config: new Signal(undefined), + track: new Signal(track), + close: () => track.close(), + }; + const capture = { + in: { source: new Signal({ getSettings: () => ({ frameRate: 30 }), getConstraints: () => ({}) }) }, + out: { display: new Signal({ width: 1280, height: 720 }), frames: new Signal(fanout) }, + }; + const estimate = new Signal(10_000_000); + const bandwidth = new Moq.Bandwidth.Allocator(estimate); + const encoder = new Encoder("video", { + enabled: true, + broadcast: { video: () => rendition, baseline: new Baseline() } as never, + capture: capture as never, + bandwidth, + }); + + try { + // The probed string is advertised before any frame, so the rendition announces without demand. + await settle(); + expect(encoder.out.catalog.peek()?.codec).toBe("vp09.00.10.08"); + + await push(); + await settle(); + expect(encoder.out.catalog.peek()?.codec).toBe("vp09.00.31.08"); + + // A bitrate change rebuilds the catalog without reverting to the probed string. + estimate.set(500_000); + await settle(); + expect(encoder.out.resolved.peek()?.bitrate).toBe(500_000); + expect(encoder.out.catalog.peek()?.codec).toBe("vp09.00.31.08"); + + // A codec switch drops the stale report, then follows the new encoder's output. + encoder.config.set({ codec: "avc1" }); + await settle(); + expect(encoder.out.catalog.peek()?.codec).toBe("avc1.640028"); + + await push(); + await settle(); + expect(encoder.out.catalog.peek()?.codec).toBe("avc1.64001F"); + } finally { + encoder.close(); + bandwidth.close(); + sub.close(); + fanout.close(); + if (original) Object.defineProperty(globalThis, "VideoEncoder", original); + else Reflect.deleteProperty(globalThis, "VideoEncoder"); + } +}); diff --git a/js/publish/src/video/encoder.ts b/js/publish/src/video/encoder.ts index 1f0f2a82011..98533f513ba 100644 --- a/js/publish/src/video/encoder.ts +++ b/js/publish/src/video/encoder.ts @@ -137,6 +137,10 @@ export class Encoder { // The codec the browser will actually encode with, tagged with the inputs it was probed against. #codec = new Signal(undefined); + // The codec string the encoder's output reported, tagged with the codec it was configured with. + // It can be more specific than the probed string: Safari reports the encoder's active profile. + #reported = new Signal<{ configured: string; codec: string } | undefined>(undefined); + // Uncapped target bitrate (pixels, maxBitrate), the reservation's ceiling. #ceiling = new Signal(undefined); @@ -274,10 +278,15 @@ export class Encoder { let lastKeyframe: Time.Micro | undefined; let lastEncoded: Time.Micro | undefined; + let configured: string | undefined; effect.spawn(async () => { const encoder = new VideoEncoder({ - output: (frame: EncodedVideoChunk) => { + output: (frame: EncodedVideoChunk, metadata?: EncodedVideoChunkMetadata) => { + // Only present on the first output after a configure, or when the encoder's config changes. + const reported = metadata?.decoderConfig?.codec; + if (reported && configured) this.#reported.set({ configured, codec: reported }); + const key = frame.type === "key"; if (key) { lastKeyframe = frame.timestamp as Time.Micro; @@ -309,6 +318,7 @@ export class Encoder { if (!config) return; encoder.configure(config); + configured = config.codec; }); effect.run((effect) => { @@ -413,8 +423,13 @@ export class Encoder { return; } + // Advertise what the encoder reported, falling back to the probed string until its first output, + // so the rendition announces without waiting on demand. Keyed by the configured codec so a codec + // switch never keeps a stale string. + const reported = effect.get(this.#reported); + const catalog: Catalog.VideoConfig = { - codec: config.codec, + codec: reported?.configured === config.codec ? reported.codec : config.codec, bitrate: config.bitrate ? Catalog.u53(config.bitrate) : undefined, framerate: config.framerate, codedWidth: Catalog.u53(config.width), @@ -592,30 +607,27 @@ export class Encoder { } | undefined > { - // A list of codecs to try, in order of preference. + // A list of codecs to try, in order of preference. Only full RFC 6381 strings: Chrome, Firefox, + // and Safari all refuse a bare `avc1` or `vp09`, and native players can't decode without the profile. const HARDWARE_CODECS = [ // VP9 // More likely to have hardware decoding, but hardware encoding is less likely. "vp09.00.10.08", - "vp09", // Browser's choice // H.264 // Almost always has hardware encoding and decoding. "avc1.640028", "avc1.4D401F", "avc1.42E01E", - "avc1", // AV1 // One day will get moved higher up the list, but hardware decoding is rare. "av01.0.08M.08", - "av01", // HEVC (aka h.265) // More likely to have hardware encoding, but less likely to be supported (licensing issues). // Unfortunately, Firefox doesn't support decoding so it's down here at the bottom. "hev1.1.6.L93.B0", - "hev1", // Browser's choice // VP8 // A terrible codec but it's easy. @@ -628,7 +640,6 @@ export class Encoder { "avc1.640028", // High "avc1.4D401F", // Main "avc1.42E01E", // Baseline - "avc1", // VP8 "vp8", @@ -636,12 +647,10 @@ export class Encoder { // VP9 // It's a bit more expensive to encode so we shy away from it. "vp09.00.10.08", - "vp09", // HEVC (aka h.265) // This likely won't work because of licensing issues. "hev1.1.6.L93.B0", - "hev1", // Browser's choice ]; // Try hardware encoding first. diff --git a/quest/m1/README.md b/quest/m1/README.md index 80888ca183d..37c611d6b0f 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -50,7 +50,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [UnknownSession log flood](/quest/m1/unknown-session-logs.md) - streams reset before their WebTransport header stop being reported as UnknownSession at WARN - [Merge queue](/quest/m1/merge-queue.md) - the required checks run on `merge_group`, so a stale green check can no longer break main - [Wire compatibility](/quest/m1/wire-compat.md) - a nightly run tests this checkout against the last published release for tokens, session wire, and catalog/container -- [Full codec string](/quest/m1/publish-codec-string.md) - browser-published video carries the encoder's full RFC 6381 codec string, so native players decode it - [TS import shared shift](/quest/m1/ts-import-shared-shift.md) - unflagged loop wraps move audio and video by one shift, so A/V sync holds across wraps - [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) - `import ts` reads a PAT or PMT that spans packets or follows a nonzero pointer_field instead of aborting, and one corrupted section costs a repetition and a counted `CRC_error`, not the import - [Same-hop importers](/quest/m1/hop-aligned-import.md) - importers sharing a `--hop` and fed one stream publish identical groups and timestamps, so failover survives diff --git a/quest/m1/publish-codec-string.md b/quest/m1/publish-codec-string.md deleted file mode 100644 index 291cbe6ca15..00000000000 --- a/quest/m1/publish-codec-string.md +++ /dev/null @@ -1,37 +0,0 @@ -# [S] js/publish advertises the full codec string - -## Goal - -Every video rendition `@moq/publish` puts in the catalog carries a full -RFC 6381 codec string, so native players can decode what browsers publish. -Today the encoder probe in `js/publish/src/video/encoder.ts` falls back to the -bare hints `vp09`, `avc1`, `av01`, and `hev1` when no specific string is -supported, and the catalog publishes the hint as the codec. Rust `hang` parses -those as `VideoCodec::Unknown`, so moq-video and the other native consumers -refuse the track ([#4095](https://github.com/moq-dev/moq/pull/4095)). - -## Plan - -Decided: advertise the codec string from the encoder's own output, -`EncodedVideoChunkMetadata.decoderConfig.codec`, rather than the probe input. -Rust keeps refusing bare hints: the decoder gate needs the profile before it -subscribes. - -Guidance: - -- The catalog is built from the resolved config today, before any frame is - encoded. Either hold the rendition out of the catalog until the first - output reports its `decoderConfig`, or update it then; keep the stall and - jitter reporting working either way. `` holds its first - announce until every captured encoder settles, so holding the rendition out - keeps the whole broadcast unannounced; and since the encoder only runs - while the track is subscribed, holding it until the first output deadlocks - unless the encoder runs without demand until then. -- Check what each browser returns for a bare hint. If one echoes the hint - back, derive the string from the bitstream (SPS for H.264/H.265, the - sequence header for AV1, the uncompressed header for VP9), or fail loud - rather than publish a string no native player accepts. -- A reconfigure (resolution or codec change) can change the string; the - catalog follows it. -- Tests with the fake `VideoEncoder`: a bare-hint probe whose output reports - a full string publishes the full string. From 3bc194899ab5d7118d4b1fd8653cf7176dc1e86f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 13:44:26 -0700 Subject: [PATCH 045/128] quest(m1): plan catalog estimate rate limiting and CI runner stalls (#4535) Co-authored-by: Claude Opus 5.5 --- quest/m1/README.md | 2 ++ quest/m1/catalog-estimate-rate.md | 44 +++++++++++++++++++++++++++++++ quest/m1/ci-runner-stalls.md | 29 ++++++++++++++++++++ 3 files changed, 75 insertions(+) create mode 100644 quest/m1/catalog-estimate-rate.md create mode 100644 quest/m1/ci-runner-stalls.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 80888ca183d..f2a1622a0f7 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -45,6 +45,8 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Watch and publish under CSP](/quest/m1/csp-assets.md) - blob workers stay the default; strict-CSP apps host the files and set a base URL - [More tests under load](/quest/m1/test-flakes-2.md) - the second round of load-only failures, fixed at the cause - [Interop audio cold start](/quest/m1/interop-audio-cold-start.md) - the interop audio tone check stops failing on cold start, fixed at its cause +- [CI runner stalls](/quest/m1/ci-runner-stalls.md) - the 0.4 to 0.8 s freezes of both interop tracks on CI are attributed from a week of nightlies and fixed or told apart from playback bugs +- [Catalog estimate rate](/quest/m1/catalog-estimate-rate.md) - a rising `jitter`/`delay` estimate republishes the catalog at most once a second, in js/publish and moq-mux - [Auth outage clock](/quest/m1/auth-outage-clock.md) - the relay and moq-auth outage tests run on a paused clock again and assert both bounds of `expires` - [Legacy end overshoot](/quest/m1/legacy-end-overshoot.md) - browser playback survives a group that starts inside the previous group's estimated end - [UnknownSession log flood](/quest/m1/unknown-session-logs.md) - streams reset before their WebTransport header stop being reported as UnknownSession at WARN diff --git a/quest/m1/catalog-estimate-rate.md b/quest/m1/catalog-estimate-rate.md new file mode 100644 index 00000000000..3aa26cf7fcb --- /dev/null +++ b/quest/m1/catalog-estimate-rate.md @@ -0,0 +1,44 @@ +# [S] A rising catalog estimate republishes at most once a second + +## Goal + +A publisher whose `jitter` or `delay` estimate keeps rising under load stops +republishing the catalog on every 1 ms step. Estimate-driven republishes are +rate-limited to one per second in `js/publish` and `moq-mux`: the first rise +publishes at once, and later rises inside the window coalesce into one publish +at the window's end carrying the latest value. Track additions, removals, and +config changes still publish immediately. + +## Plan + +Found in [#4529](https://github.com/moq-dev/moq/pull/4529): under load, the +lifetime-maximum `Estimator` (`js/publish/src/jitter.ts`, mirroring +`moq_mux::catalog::Estimator`) rises 1 ms at a time and each rise republishes +the catalog, which makes every player send a subscribe update on every track. + +Decided with the maintainer: + +- Rate limit, not quantization, so the advertised value stays exact. +- Leading and trailing edge, 1 s window: a first estimate arrives without + delay and the catalog never trails the estimate by more than a window. +- Estimate-driven changes only; a structural catalog change never waits. +- Keep the draft's never-lower rule. #4529 also saw an estimate grow to about + 586 ms on an overloaded machine, so resuming refilled that whole delay. That + is the rule working as written ("a burst it emitted once it may emit + again"), not a bug for this quest. + +A pending trailing publish folds into any structural publish that happens +first. Unit tests drive the window on a mocked clock in both languages. + +The churn fans out (every rise reaches every subscriber on every track), so +add a benchmark swept over tracks x subscribers that drives a rising estimate +and counts catalog publishes and subscribe updates. It shows the saving now and +catches a regression later as a slope. `moq-mux` has no benches yet; add one +there or extend `rs/moq-net/benches/session.rs`. + +Public API: none expected. Wire: none; catalog contents are unchanged, only +how often they are sent. + +## Related + +- [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - the player-side target the advertised jitter floors diff --git a/quest/m1/ci-runner-stalls.md b/quest/m1/ci-runner-stalls.md new file mode 100644 index 00000000000..3d6f4df3bdf --- /dev/null +++ b/quest/m1/ci-runner-stalls.md @@ -0,0 +1,29 @@ +# [S] Interop freezes on CI runners are attributed + +## Goal + +The 0.4 to 0.8 s freezes where both interop tracks stop at once on CI are +attributed to the runner, the relay, or the player, with evidence from the +nightly traces. A cause in our code is fixed at its source; a runner stall is +documented, and the interop checks tell it apart from a playback bug instead +of failing on it as one. + +## Plan + +Found in [#4529](https://github.com/moq-dev/moq/pull/4529) while chasing the +cold-start tone check: some CI traces show both tracks freezing together, +which that fix shortens but cannot remove. #4529 added the player's `delay` to +the interop trace, so a week of nightlies after it lands shows the freezes +without the delay-flush noise that hid them. + +Collect the failing and passing nightly interop traces for that week, line up +each freeze against relay and player timestamps, and look for what the +runner was doing (CPU steal, GC, disk). Decided with the maintainer: diagnose +first from real nightlies rather than assume a runner stall. + +Public API: none. Wire: none. + +## Required + +- A week of nightly interop runs on `main` after #4529 merges +- [Interop audio cold start](/quest/m1/interop-audio-cold-start.md) - #4529, which adds the `delay` column these traces need From fe311b3d34c7685d5822a0b7290f89411bfcf14e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 13:47:18 -0700 Subject: [PATCH 046/128] fix(publish): probe the reported codec string with a one-frame encode Mirror moq-video's Config::probe: encode one mid-gray frame with a throwaway encoder and advertise its decoderConfig.codec from the first announce, instead of following the live encoder's output. Co-Authored-By: Claude Opus 5.5 --- js/publish/src/video/encoder.test.ts | 202 ++++++++++----------------- js/publish/src/video/encoder.ts | 121 ++++++++-------- 2 files changed, 139 insertions(+), 184 deletions(-) diff --git a/js/publish/src/video/encoder.test.ts b/js/publish/src/video/encoder.test.ts index ffd6a2714c2..8e28708c5f6 100644 --- a/js/publish/src/video/encoder.test.ts +++ b/js/publish/src/video/encoder.test.ts @@ -12,7 +12,17 @@ class FakeVideoEncoder { // Every accepted probe, so a test can assert a published config was actually validated. static accepted: string[] = []; + // The codec string the encoder reports in its output for a configured one. Echoes by default, + // like Chrome and Firefox. + static report: (codec: string) => string | undefined = (codec) => codec; + state: CodecState = "unconfigured"; + #output: VideoEncoderInit["output"]; + #codec?: string; + + constructor(init: VideoEncoderInit) { + this.#output = init.output; + } static async isConfigSupported(config: VideoEncoderConfig): Promise<{ supported: boolean }> { FakeVideoEncoder.probes++; @@ -24,32 +34,50 @@ class FakeVideoEncoder { return { supported }; } - configure(): void { + configure(config: VideoEncoderConfig): void { this.state = "configured"; + this.#codec = config.codec; } encode(): void {} + // Only the probe flushes, so only it sees an output; the live encoder holds every frame. + async flush(): Promise { + const codec = this.#codec && FakeVideoEncoder.report(this.#codec); + const chunk = { type: "key", timestamp: 0, byteLength: 1, copyTo: () => {} }; + this.#output(chunk as never, (codec ? { decoderConfig: { codec } } : {}) as never); + } + close(): void { this.state = "closed"; } } +class FakeVideoFrame { + timestamp = 0; + close(): void {} +} + function installFakeVideoEncoder() { const original = Object.getOwnPropertyDescriptor(globalThis, "VideoEncoder"); + const frame = Object.getOwnPropertyDescriptor(globalThis, "VideoFrame"); Object.defineProperty(globalThis, "VideoEncoder", { configurable: true, value: FakeVideoEncoder, writable: true, }); + Object.defineProperty(globalThis, "VideoFrame", { configurable: true, value: FakeVideoFrame, writable: true }); return { [Symbol.dispose]() { + FakeVideoEncoder.report = (codec) => codec; if (original) { Object.defineProperty(globalThis, "VideoEncoder", original); } else { Reflect.deleteProperty(globalThis, "VideoEncoder"); } + if (frame) Object.defineProperty(globalThis, "VideoFrame", frame); + else Reflect.deleteProperty(globalThis, "VideoFrame"); }, }; } @@ -458,40 +486,8 @@ test("frame sources retain their dimensions and nominal frame rate", async () => test.each(["encoder lag", "quiet startup"])("marks a rendition stalled for %s", async (reason) => { const clock = spyOn(performance, "now").mockReturnValue(0); - class DelayedVideoEncoder { - static probes = 0; - state: CodecState = "unconfigured"; - #output: VideoEncoderInit["output"]; - - constructor(init: VideoEncoderInit) { - this.#output = init.output; - } - - static async isConfigSupported(config: VideoEncoderConfig): Promise<{ supported: boolean }> { - DelayedVideoEncoder.probes++; - return { supported: config.codec.startsWith("avc1") }; - } - - configure(): void { - this.state = "configured"; - } - - encode(): void { - // Hold the output: a throttled encoder never hands frames to the session. - } - - close(): void { - this.state = "closed"; - void this.#output; - } - } - - const original = Object.getOwnPropertyDescriptor(globalThis, "VideoEncoder"); - Object.defineProperty(globalThis, "VideoEncoder", { - configurable: true, - value: DelayedVideoEncoder, - writable: true, - }); + // The fake holds every live output, like a throttled encoder that never hands frames to the session. + using _videoEncoder = installFakeVideoEncoder(); class Frame { codedWidth = 640; @@ -565,8 +561,6 @@ test.each(["encoder lag", "quiet startup"])("marks a rendition stalled for %s", encoder.close(); fanout.close(); clock.mockRestore(); - if (original) Object.defineProperty(globalThis, "VideoEncoder", original); - else Reflect.deleteProperty(globalThis, "VideoEncoder"); } }); @@ -594,116 +588,66 @@ test("the probe only offers full codec strings", async () => { } }); -test("the catalog advertises the codec string the encoder reports", async () => { - // Refine the configured string like Safari does, reporting the profile the encoder chose. +// The catalog is written before any subscriber starts the real encoder, so it has to carry what the +// bitstream will say from the first announce, not a probe input a native player may refuse. +test("the catalog advertises the codec string a probe encode reports", async () => { + using _videoEncoder = installFakeVideoEncoder(); + // Refine the configured string, as an encoder that picks its own level would. const REPORTED: Record = { - "avc1.640028": "avc1.64001F", "vp09.00.10.08": "vp09.00.31.08", + "avc1.640028": "avc1.64001F", }; + const probe = spyOn(FakeVideoEncoder, "isConfigSupported").mockImplementation(async (config) => ({ + supported: config.codec in REPORTED, + })); + FakeVideoEncoder.report = (codec) => REPORTED[codec]; - class ReportingVideoEncoder { - state: CodecState = "unconfigured"; - #output: VideoEncoderInit["output"]; - #codec?: string; - #fresh = false; - - constructor(init: VideoEncoderInit) { - this.#output = init.output; - } - - static async isConfigSupported(config: VideoEncoderConfig): Promise<{ supported: boolean }> { - return { supported: config.codec in REPORTED }; - } - - configure(config: VideoEncoderConfig): void { - this.state = "configured"; - this.#codec = config.codec; - this.#fresh = true; - } - - encode(frame: VideoFrame): void { - const chunk = { type: "key", timestamp: frame.timestamp, byteLength: 1, copyTo: () => {} }; - const metadata = this.#fresh && this.#codec ? { decoderConfig: { codec: REPORTED[this.#codec] } } : {}; - this.#fresh = false; - this.#output(chunk as never, metadata as never); - } - - close(): void { - this.state = "closed"; - } - } - - const original = Object.getOwnPropertyDescriptor(globalThis, "VideoEncoder"); - Object.defineProperty(globalThis, "VideoEncoder", { - configurable: true, - value: ReportingVideoEncoder, - writable: true, - }); - - const { Fanout } = await import("../fanout"); - let controller!: ReadableStreamDefaultController; - const stream = new ReadableStream({ - start: (c) => { - controller = c; - }, - }); - const fanout = new Fanout(stream, { clone: (frame) => ({ timestamp: frame.timestamp, close: () => {} }) as never }); - let timestamp = 0; - const push = async () => { - controller.enqueue({ timestamp, close: () => {} } as never); - timestamp += 33_333; - await new Promise((resolve) => setTimeout(resolve, 10)); - }; - - const track = new Moq.Track.Producer("video").accept({ priority: 60 }); - const sub = track.subscribe(); - const rendition = { - config: new Signal(undefined), - track: new Signal(track), - close: () => track.close(), - }; const capture = { in: { source: new Signal({ getSettings: () => ({ frameRate: 30 }), getConstraints: () => ({}) }) }, - out: { display: new Signal({ width: 1280, height: 720 }), frames: new Signal(fanout) }, + out: { display: new Signal({ width: 1280, height: 720 }) }, }; - const estimate = new Signal(10_000_000); - const bandwidth = new Moq.Bandwidth.Allocator(estimate); - const encoder = new Encoder("video", { - enabled: true, - broadcast: { video: () => rendition, baseline: new Baseline() } as never, - capture: capture as never, - bandwidth, + const encoder = new Encoder("video", { enabled: true, capture: capture as never }); + const advertised: string[] = []; + const unsubscribe = encoder.out.catalog.subscribe((catalog) => { + if (catalog) advertised.push(catalog.codec); }); try { - // The probed string is advertised before any frame, so the rendition announces without demand. - await settle(); - expect(encoder.out.catalog.peek()?.codec).toBe("vp09.00.10.08"); - - await push(); - await settle(); - expect(encoder.out.catalog.peek()?.codec).toBe("vp09.00.31.08"); - - // A bitrate change rebuilds the catalog without reverting to the probed string. - estimate.set(500_000); await settle(); - expect(encoder.out.resolved.peek()?.bitrate).toBe(500_000); + expect(encoder.out.resolved.peek()?.codec).toBe("vp09.00.10.08"); expect(encoder.out.catalog.peek()?.codec).toBe("vp09.00.31.08"); - // A codec switch drops the stale report, then follows the new encoder's output. + // A codec change re-probes and advertises the new encoder's string. encoder.config.set({ codec: "avc1" }); await settle(); - expect(encoder.out.catalog.peek()?.codec).toBe("avc1.640028"); + expect(encoder.out.resolved.peek()?.codec).toBe("avc1.640028"); + expect(encoder.out.catalog.peek()?.codec).toBe("avc1.64001F"); - await push(); + // The configured strings were never advertised, not even briefly. + expect([...new Set(advertised)]).toEqual(["vp09.00.31.08", "avc1.64001F"]); + } finally { + unsubscribe(); + encoder.close(); + probe.mockRestore(); + } +}); + +test("a probe encode that reports no codec string fails loud", async () => { + using _videoEncoder = installFakeVideoEncoder(); + FakeVideoEncoder.report = () => undefined; + const error = spyOn(console, "error").mockImplementation(() => {}); + const capture = { + in: { source: new Signal({ getSettings: () => ({ frameRate: 30 }), getConstraints: () => ({}) }) }, + out: { display: new Signal({ width: 1280, height: 720 }) }, + }; + const encoder = new Encoder("video", { enabled: true, capture: capture as never }); + try { await settle(); - expect(encoder.out.catalog.peek()?.codec).toBe("avc1.64001F"); + expect(encoder.out.catalog.peek()).toBeUndefined(); + expect(encoder.settled.peek()).toBe(true); + expect(error).toHaveBeenCalled(); } finally { encoder.close(); - bandwidth.close(); - sub.close(); - fanout.close(); - if (original) Object.defineProperty(globalThis, "VideoEncoder", original); - else Reflect.deleteProperty(globalThis, "VideoEncoder"); + error.mockRestore(); } }); diff --git a/js/publish/src/video/encoder.ts b/js/publish/src/video/encoder.ts index 98533f513ba..411dd0cf280 100644 --- a/js/publish/src/video/encoder.ts +++ b/js/publish/src/video/encoder.ts @@ -137,10 +137,6 @@ export class Encoder { // The codec the browser will actually encode with, tagged with the inputs it was probed against. #codec = new Signal(undefined); - // The codec string the encoder's output reported, tagged with the codec it was configured with. - // It can be more specific than the probed string: Safari reports the encoder's active profile. - #reported = new Signal<{ configured: string; codec: string } | undefined>(undefined); - // Uncapped target bitrate (pixels, maxBitrate), the reservation's ceiling. #ceiling = new Signal(undefined); @@ -278,15 +274,10 @@ export class Encoder { let lastKeyframe: Time.Micro | undefined; let lastEncoded: Time.Micro | undefined; - let configured: string | undefined; effect.spawn(async () => { const encoder = new VideoEncoder({ - output: (frame: EncodedVideoChunk, metadata?: EncodedVideoChunkMetadata) => { - // Only present on the first output after a configure, or when the encoder's config changes. - const reported = metadata?.decoderConfig?.codec; - if (reported && configured) this.#reported.set({ configured, codec: reported }); - + output: (frame: EncodedVideoChunk) => { const key = frame.type === "key"; if (key) { lastKeyframe = frame.timestamp as Time.Micro; @@ -318,7 +309,6 @@ export class Encoder { if (!config) return; encoder.configure(config); - configured = config.codec; }); effect.run((effect) => { @@ -418,18 +408,21 @@ export class Encoder { #runCatalog(effect: Effect): void { const enabled = effect.get(this.in.enabled); const config = effect.get(this.out.resolved); - if (!enabled || !config) { + // Advertise the codec string the probe's encoder reported rather than the one we configured, + // so it names the profile and level the bitstream actually carries. The resolved config is + // derived from the probe, but can briefly trail a new one within a batch. + const detected = effect.get(this.#codec); + const matches = + detected?.codec === config?.codec && + detected?.width === config?.width && + detected?.height === config?.height; + if (!enabled || !config || !detected || !matches) { effect.set(this.#out.catalog, undefined); return; } - // Advertise what the encoder reported, falling back to the probed string until its first output, - // so the rendition announces without waiting on demand. Keyed by the configured codec so a codec - // switch never keeps a stale string. - const reported = effect.get(this.#reported); - const catalog: Catalog.VideoConfig = { - codec: reported?.configured === config.codec ? reported.codec : config.codec, + codec: detected.reported, bitrate: config.bitrate ? Catalog.u53(config.bitrate) : undefined, framerate: config.framerate, codedWidth: Catalog.u53(config.width), @@ -457,8 +450,6 @@ export class Encoder { effect.spawn(async () => { try { const detected = await this.#bestCodec(required, dimensions); - if (!detected) return; - effect.set(this.#codec, { ...detected, required, ...dimensions }); } catch (err) { this.#fail(effect); @@ -600,13 +591,7 @@ export class Encoder { async #bestCodec( required: string, dimensions: { width: number; height: number }, - ): Promise< - | { - codec: string; - hardwareAcceleration: HardwareAcceleration; - } - | undefined - > { + ): Promise> { // A list of codecs to try, in order of preference. Only full RFC 6381 strings: Chrome, Firefox, // and Safari all refuse a bare `avc1` or `vp09`, and native players can't decode without the profile. const HARDWARE_CODECS = [ @@ -658,35 +643,17 @@ export class Encoder { // VideoToolbox only hardware-encodes H.264 and HEVC. Skip the hardware pass and let it fall // through to the software pass, which is H.264 first, since Safari routes that through // VideoToolbox anyway regardless of the hint. - if (hardwareReliable()) { - for (const codec of HARDWARE_CODECS) { - if (!codec.startsWith(required)) continue; - - const hardwareAcceleration: HardwareAcceleration = "prefer-hardware"; - - const hardware: VideoEncoderConfig = { - codec, - width: dimensions.width, - height: dimensions.height, - latencyMode: "realtime", - hardwareAcceleration, - avc: codec.startsWith("avc1") ? { format: "annexb" } : undefined, - // @ts-expect-error Typescript needs to be updated. - hevc: codec.startsWith("hev1") ? { format: "annexb" } : undefined, - }; - - const { supported } = await VideoEncoder.isConfigSupported(hardware); - if (supported) return { codec, hardwareAcceleration }; - } - } + const candidates: [string, HardwareAcceleration][] = [ + ...(hardwareReliable() + ? HARDWARE_CODECS.map((codec) => [codec, "prefer-hardware"] as [string, HardwareAcceleration]) + : []), + ...SOFTWARE_CODECS.map((codec) => [codec, "prefer-software"] as [string, HardwareAcceleration]), + ]; - // Try software encoding. - for (const codec of SOFTWARE_CODECS) { + for (const [codec, hardwareAcceleration] of candidates) { if (!codec.startsWith(required)) continue; - const hardwareAcceleration: HardwareAcceleration = "prefer-software"; - - const software: VideoEncoderConfig = { + const config: VideoEncoderConfig = { codec, width: dimensions.width, height: dimensions.height, @@ -697,8 +664,8 @@ export class Encoder { hevc: codec.startsWith("hev1") ? { format: "annexb" } : undefined, }; - const { supported } = await VideoEncoder.isConfigSupported(software); - if (supported) return { codec, hardwareAcceleration }; + const { supported } = await VideoEncoder.isConfigSupported(config); + if (supported) return { codec, hardwareAcceleration, reported: await reportedCodec(config) }; } throw new Error("no supported codec"); @@ -718,7 +685,10 @@ function sourceFrameRate(source: Source): number | undefined { // A hardware probe result, carrying the inputs it ran against so a consumer can tell whether it // still applies. type Detected = { + // The codec string we configure the encoder with. codec: string; + // The codec string the encoder reported for it, which the catalog advertises. + reported: string; hardwareAcceleration: HardwareAcceleration; // The codec prefix the user required at probe time. required: string; @@ -726,6 +696,47 @@ type Detected = { height: number; }; +// Encode one frame with a throwaway encoder and return the codec string it reports, like +// moq-video's `Config::probe`. The encoder picks the profile and level it actually writes, so reading +// them back lets the rendition be advertised before a subscriber starts the real encoder, without a +// claim the first keyframe would contradict. It closes before the config resolves, so it never +// overlaps the first real encoder; only a re-probe while serving briefly holds two sessions. +async function reportedCodec(config: VideoEncoderConfig): Promise { + let reported: string | undefined; + const encoder = new VideoEncoder({ + output: (_chunk, metadata) => { + reported ??= metadata?.decoderConfig?.codec; + }, + // flush() rejects with the same error. + error: () => {}, + }); + + try { + encoder.configure(config); + + // Mid-gray, since the picture only has to make the encoder emit its config. + const { width, height } = config; + const frame = new VideoFrame(new Uint8Array((width * height * 3) / 2).fill(0x80), { + format: "I420", + codedWidth: width, + codedHeight: height, + timestamp: 0, + }); + try { + encoder.encode(frame, { keyFrame: true }); + } finally { + frame.close(); + } + + await encoder.flush(); + } finally { + if (encoder.state !== "closed") encoder.close(); + } + + if (!reported) throw new Error(`${config.codec} encoder reported no codec string`); + return reported; +} + // Scale the bitrate for more efficient codecs, relative to H.264. // TODO This shouldn't be linear, as the efficiency is very similar at low bitrates. function codecBitrateScale(codec: string): number { From a5bbf8755ad4a3e3445191df79aa87d0d31d57da Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 13:59:29 -0700 Subject: [PATCH 047/128] fix(net): a JS track's clean close ends at its own last group (#4522) Co-authored-by: Claude Opus 5.5 --- js/net/src/broadcast.test.ts | 48 ++++++++++++++++++++++++++++++++++ js/net/src/track.ts | 6 ++--- quest/m1/README.md | 1 - quest/m1/js-track-close-end.md | 20 -------------- 4 files changed, 51 insertions(+), 24 deletions(-) delete mode 100644 quest/m1/js-track-close-end.md diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index 28d202c48c6..f1640b4af3a 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -135,6 +135,54 @@ test("a sibling producer's groups do not settle an aborted end", async () => { broadcast.close(); }); +test("a clean close ends at the track's own last group, not a sibling's", async () => { + const broadcast = new BroadcastProducer(); + const firstSubscriber = broadcast.track("media").subscribe(); + const secondSubscriber = broadcast.track("media").subscribe(); + const firstRequest = await wireOf(broadcast).requested(); + const secondRequest = await wireOf(broadcast).requested(); + if (!firstRequest || !secondRequest) throw new Error("expected requests"); + const firstProducer = firstRequest.accept(); + const secondProducer = secondRequest.accept(); + + const reader = firstProducer.subscribe(); + firstProducer.appendGroup().close(); + for (let i = 0; i < 3; i++) secondProducer.appendGroup().close(); + firstProducer.close(); + + // The sibling took 1..3, which the first producer will never send. + expect(reader.final()).toBe(1); + + firstSubscriber.close(); + secondSubscriber.close(); + secondProducer.close(); + broadcast.close(); +}); + +test("finishAt accepts an end below a sibling's groups", async () => { + const broadcast = new BroadcastProducer(); + const firstSubscriber = broadcast.track("media").subscribe(); + const secondSubscriber = broadcast.track("media").subscribe(); + const firstRequest = await wireOf(broadcast).requested(); + const secondRequest = await wireOf(broadcast).requested(); + if (!firstRequest || !secondRequest) throw new Error("expected requests"); + const firstProducer = firstRequest.accept(); + const secondProducer = secondRequest.accept(); + + const reader = firstProducer.subscribe(); + firstProducer.appendGroup().close(); + for (let i = 0; i < 3; i++) secondProducer.appendGroup().close(); + expect(() => firstProducer.finishAt(0)).toThrow("track end 0 is below the next sequence 1"); + firstProducer.finishAt(2); + expect(reader.final()).toBe(2); + + firstSubscriber.close(); + secondSubscriber.close(); + firstProducer.close(); + secondProducer.close(); + broadcast.close(); +}); + test("closing a broadcast rejects a dequeued request", async () => { const broadcast = new BroadcastProducer(); const subscriber = broadcast.track("media").subscribe(); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 9f406cd55d5..09af757c9e1 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -856,8 +856,8 @@ export class Producer { if (!Number.isSafeInteger(final) || final < 0) throw new RangeError(`invalid track end: ${final}`); const declared = this.#state.final.peek(); if (declared !== undefined) throw new Error(`track already ends at ${declared}`); - if (final < this.#sequence.next) { - throw new Error(`track end ${final} is below the next sequence ${this.#sequence.next}`); + if (final < this.#received) { + throw new Error(`track end ${final} is below the next sequence ${this.#received}`); } this.#declareFinal(final); } @@ -881,7 +881,7 @@ export class Producer { if (this.#state.closed.peek() !== undefined) return; if (abort && this.#settled()) abort = undefined; if (abort === undefined && this.#state.final.peek() === undefined) { - this.#declareFinal(this.#sequence.next); + this.#declareFinal(this.#received); } // Nobody will finish these, so a subscriber that has not taken one yet never sees it. // Not evicted: a reader already holding one keeps its frames and sees the abort. diff --git a/quest/m1/README.md b/quest/m1/README.md index f2a1622a0f7..a0f69da5033 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -34,7 +34,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Splice edge cases](/quest/m1/splice-edges.md) - an unstamped successor, a pruned segment's boundary group, and a warm head during a takeover are each handled correctly - [Resumed groups](/quest/m1/resume-latest.md) - a half-delivered group ends once the new copy is past it, so a group-only reader never parks after a mid-group failover - [Track tail hardening](/quest/m1/track-tail-hardening.md) - Rust and JS wait out a track's tail by the same rules, with the known hang, count, truncation, grace, and memory holes closed -- [JS close end](/quest/m1/js-track-close-end.md) - a JS track's clean close ends at its own last group, not a sibling producer's - [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 - [FIN wait expiry](/quest/m1/fin-wait-expiry.md) - a group awaiting its FIN ack still expires and follows priority updates on lite and IETF - [Cross-relay bursts](/quest/m1/cross-relay-bursts.md) - bursty small-group tracks cross two relays without lost groups, unanswered FETCHes, or stalls diff --git a/quest/m1/js-track-close-end.md b/quest/m1/js-track-close-end.md deleted file mode 100644 index c86f3e16610..00000000000 --- a/quest/m1/js-track-close-end.md +++ /dev/null @@ -1,20 +0,0 @@ -# [XS] A JS track's clean close ends at its own last group - -## Goal - -`close()` on a JS track producer declares the final sequence from the groups -that track actually produced, like Rust's `finish()` uses its own -`max_sequence`. A sibling producer on the same broadcast and name can no -longer push the end past groups this track will ever send. - -## Plan - -- `close()` in `js/net/src/track.ts` calls `#declareFinal(this.#sequence.next)`, - and `#sequence` is shared per broadcast and track name (`bindProducer`). - Use the track's own `#received` high-water mark instead, which #4385 added - and only `#settled` reads today. -- Re-check `finishAt` for the same shared-counter assumption. -- Regression test: two producers on one name, the sibling creates later - groups, and the closed track's final sequence is its own last group + 1. - -Public API: none. Wire: none. From a16f8d0bf03deaf5341a0e1c956f5e4e1f03ac93 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 14:14:20 -0700 Subject: [PATCH 048/128] fix(audio): conceal one Opus packet's length for a lost packet, not 120 ms (#4442) Co-authored-by: Claude Sonnet 5.5 --- quest/m1/README.md | 1 - quest/m1/opus-conceal.md | 33 ------------------- rs/moq-audio/src/decode/decoder.rs | 51 +++++++++++++++++++++++++++--- 3 files changed, 47 insertions(+), 38 deletions(-) delete mode 100644 quest/m1/opus-conceal.md diff --git a/quest/m1/README.md b/quest/m1/README.md index a0f69da5033..847b8359b7c 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -80,7 +80,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [C++ through moq-ffi](/quest/m1/cpp/README.md) - generated C++ over moq-ffi with futures and expected-style errors, shipped as a tarball, vcpkg, and Conan, and adopted by the OBS plugin - [Generated C bindings](/quest/m1/c/README.md) - C generated from moq-ffi ships as `moq-c` 0.8.0 and replaces the hand-written libmoq - [OBS native codecs](/quest/m1/obs-moq-video/README.md) - replace FFmpeg video and audio decoding with moq-video and moq-audio, deliver GPU frames, and use native audio/video encoders -- [Opus concealment](/quest/m1/opus-conceal.md) - a lost Opus packet conceals the last packet's length, not 120 ms - [Audio codecs](/quest/m1/audio-codecs/README.md) - platform audio codecs, explicit unsupported cases, and channel layouts up to 7.1 - [Opus mapping family](/quest/m1/opus-mapping-family.md) - on dev, the Opus head config keeps its mapping family only in `mapping` - [mp4-atom dOps mapping](/quest/m1/mp4-atom-dops-mapping.md) - a released mp4-atom reads and writes any `dOps` channel mapping family and table diff --git a/quest/m1/opus-conceal.md b/quest/m1/opus-conceal.md deleted file mode 100644 index cac6f8255ed..00000000000 --- a/quest/m1/opus-conceal.md +++ /dev/null @@ -1,33 +0,0 @@ -# [XS] Opus concealment length - -## Goal - -`moq_audio` `Decoder::decode(&[])` conceals one Opus packet, the length of the -last real one, instead of 120 ms. The API is unchanged and lands on main. - -## Plan - -- `rs/moq-audio/src/decode/decoder.rs` passes `max_frame_size` (120 ms) as - libopus's `frame_size` on every call, and libopus conceals exactly that many - samples. Record the last packet's sample count (`opus_packet_get_nb_samples`) - and pass it for an empty packet; it is always a multiple of 2.5 ms. -- The audio-codecs line branch moves this code to - `rs/moq-audio/src/decode/backend/libopus.rs` (same `max_frame_size`); - land the fix wherever the code lives when this starts, and port it on the - line's next merge from main otherwise. -- Refuse loss before any packet has decoded, rather than surfacing libopus's - `BUFFER_TOO_SMALL`. -- Document on `decode` how much an empty packet conceals. -- Regression from the issue's repro: one lost 20 ms packet yields 20 ms. -- A `conceal(duration)` method and `decode(Option<&[u8]>)` were rejected: no - consumer needs a caller-chosen length, and the latter breaks the common case. - How platform backends signal loss belongs to the decode-backend seam. - -## Closes - -- [#4248](https://github.com/moq-dev/moq/issues/4248) - `Decoder::decode(&[])` conceals 120 ms of Opus audio for one lost packet - -## Related - -- [Audio loss recovery](/quest/m2/audio-loss-recovery.md) - the FEC versus concealment policy study -- [Decode backend](/quest/m1/audio-codecs/decode-backend.md) - where platform decoders signal loss diff --git a/rs/moq-audio/src/decode/decoder.rs b/rs/moq-audio/src/decode/decoder.rs index 3d813c40c65..0267cd417f9 100644 --- a/rs/moq-audio/src/decode/decoder.rs +++ b/rs/moq-audio/src/decode/decoder.rs @@ -73,6 +73,9 @@ struct Opus { inner: *mut OpusDecoder, pre_skip_remaining: usize, max_frame_size: usize, + /// Frames per channel in the last packet that decoded, which is what a lost + /// packet most likely carried. `None` until one has. + last_frame_size: Option, in_dtx: bool, } @@ -135,6 +138,7 @@ impl Decoder { inner, pre_skip_remaining: head.pre_skip as usize, max_frame_size: (opus::DECODE_RATE as usize * MAX_FRAME_MS) / 1000, + last_frame_size: None, in_dtx: false, }; @@ -281,13 +285,26 @@ impl Decoder { /// Decode one packet into interleaved `f32` PCM and report its codec activity. /// - /// Empty Opus packets invoke packet-loss concealment. Loss during DTX remains - /// classified as DTX, while loss during active audio remains active. + /// An empty Opus packet marks one lost packet and conceals as much audio as the + /// last packet that decoded held, so a lost 20 ms packet yields 20 ms. It is + /// refused with [`Error::Decode`] before any packet has decoded, since there is + /// no length to conceal. Loss during DTX remains classified as DTX, while loss + /// during active audio remains active. pub fn decode(&mut self, packet: &[u8]) -> Result { match &mut self.backend { Backend::Opus(opus) => { let channels = self.layout.channels() as usize; - let mut out = vec![0.0f32; opus.max_frame_size * channels]; + // libopus conceals exactly `frame_size` samples for a lost packet, and + // the decoder can't know how long it was, so assume the last one's length. + // A real packet decodes into the most it can hold. + let frame_size = if packet.is_empty() { + opus.last_frame_size.ok_or_else(|| { + Error::Decode("opus packet lost before any packet decoded, so no length to conceal".into()) + })? + } else { + opus.max_frame_size + }; + let mut out = vec![0.0f32; frame_size * channels]; // SAFETY: `inner` owns a live OpusDecoder; packet/out slices are // bounded by the lengths we pass. let samples = unsafe { @@ -296,13 +313,16 @@ impl Decoder { packet.as_ptr(), packet.len() as i32, out.as_mut_ptr(), - opus.max_frame_size as i32, + frame_size as i32, 0, ) }; if samples < 0 { return Err(crate::opus::decode_error(samples)); } + if !packet.is_empty() { + opus.last_frame_size = Some(samples as usize); + } out.truncate(samples as usize * channels); let trim_frames = opus.pre_skip_remaining.min(samples as usize); if trim_frames > 0 { @@ -504,6 +524,29 @@ pub(crate) mod tests { } } + /// One lost packet conceals one packet's worth of audio, not the 120 ms + /// libopus would fill given the whole buffer. + #[test] + fn opus_conceals_the_length_of_the_last_packet() { + let packets = opus_packets(3); + let mut decoder = Decoder::new( + &opus_catalog(moq_mux::codec::opus::Config::new(48_000, 1)), + &Config::default(), + ) + .unwrap(); + + // Nothing decoded yet, so there is no length to conceal. + assert!(matches!(decoder.decode(&[]), Err(Error::Decode(_)))); + + for packet in &packets { + decoder.decode(packet).unwrap(); + } + assert_eq!(decoder.decode(&[]).unwrap().samples.len(), 960); + + // Concealment doesn't change the length: the next loss is the same size. + assert_eq!(decoder.decode(&[]).unwrap().samples.len(), 960); + } + #[test] fn opus_applies_the_declared_gain() { let packets = opus_packets(5); From d34030c65ad1b731dc95ed341341bfe6aa9ff8b3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 14:19:06 -0700 Subject: [PATCH 049/128] ci: cut redundant platform and release builds, fix starved cache warm (#4541) Co-authored-by: Claude Opus 5.5 --- .github/workflows/alert.yml | 7 +-- .github/workflows/cache.yml | 7 ++- .github/workflows/libmoq.yml | 5 ++ .github/workflows/moq-cli.yml | 5 ++ .github/workflows/moq-gst.yml | 5 ++ .github/workflows/moq-relay.yml | 5 ++ .github/workflows/nightly.yml | 15 ++++++ .github/workflows/obs.yml | 66 ++++++++++++++++++++++-- .github/workflows/platform.yml | 71 ++++++++------------------ .github/workflows/release-dart-ffi.yml | 7 ++- .github/workflows/release-js.yml | 5 ++ .github/workflows/release-py.yml | 5 ++ rs/justfile | 62 ++++++++++++++++------ 13 files changed, 187 insertions(+), 78 deletions(-) diff --git a/.github/workflows/alert.yml b/.github/workflows/alert.yml index e478ad32895..9e264da8d30 100644 --- a/.github/workflows/alert.yml +++ b/.github/workflows/alert.yml @@ -21,9 +21,9 @@ on: # Android) are omitted so they don't spawn a skipped Alert run on every # push to every PR. `just gh check` enforces both halves of that. # - # Swift and Platform are here despite also running on pull requests: Swift - # warms its own Rust cache on `main`, and Platform compiles every merge to - # `main` and `dev`. Those push runs are nobody's check, so a break in them + # Swift, OBS, and Platform are here despite also running on pull requests: + # Swift warms its own Rust cache on `main`, and OBS and Platform build every + # merge to `main` and `dev`. Those push runs are nobody's check, so a break in them # would otherwise go unseen. The cost is a skipped Alert run per pull # request. workflows: @@ -37,6 +37,7 @@ on: - moq-gst - moq-relay - Nightly + - OBS - Platform - release-brew - Release Dart diff --git a/.github/workflows/cache.yml b/.github/workflows/cache.yml index 6e1a1291225..4fb0bf42805 100644 --- a/.github/workflows/cache.yml +++ b/.github/workflows/cache.yml @@ -40,10 +40,13 @@ on: # Priming a cold cache by hand, e.g. after a toolchain bump rolls the key. workflow_dispatch: -# Newest `main` wins; an older warm is worth less than the runner it holds. +# Queue rather than cancel. A warm takes 30-50 minutes and `main` merges more +# often than that, so cancelling meant no warm ever finished and every pull +# request restored a store hours stale. Actions keeps only the newest pending +# run per group, so merges that land mid-warm still coalesce into one. concurrency: group: cache-${{ github.ref }} - cancel-in-progress: true + cancel-in-progress: false jobs: warm: diff --git a/.github/workflows/libmoq.yml b/.github/workflows/libmoq.yml index 7eb12759de1..7726371df53 100644 --- a/.github/workflows/libmoq.yml +++ b/.github/workflows/libmoq.yml @@ -45,6 +45,11 @@ jobs: uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: determinate: false + # Trust the flake's cachix substituter, as check.yml does, so the dev + # shell is substituted rather than built from source. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= - name: Install Rust (Windows) if: '!matrix.use_nix' diff --git a/.github/workflows/moq-cli.yml b/.github/workflows/moq-cli.yml index 141e47ecb8d..a7963178e4d 100644 --- a/.github/workflows/moq-cli.yml +++ b/.github/workflows/moq-cli.yml @@ -117,6 +117,11 @@ jobs: - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: determinate: false + # Trust the flake's cachix substituter, as check.yml does, so the dev + # shell is substituted rather than built from source. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= - name: Parse version id: parse diff --git a/.github/workflows/moq-gst.yml b/.github/workflows/moq-gst.yml index 2c93d1ac9a7..228c5ef1511 100644 --- a/.github/workflows/moq-gst.yml +++ b/.github/workflows/moq-gst.yml @@ -37,6 +37,11 @@ jobs: - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: determinate: false + # Trust the flake's cachix substituter, as check.yml does, so the dev + # shell is substituted rather than built from source. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= - name: Parse version id: parse diff --git a/.github/workflows/moq-relay.yml b/.github/workflows/moq-relay.yml index 761ee0aba35..19dfd61601c 100644 --- a/.github/workflows/moq-relay.yml +++ b/.github/workflows/moq-relay.yml @@ -118,6 +118,11 @@ jobs: - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: determinate: false + # Trust the flake's cachix substituter, as check.yml does, so the dev + # shell is substituted rather than built from source. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= - name: Parse version id: parse diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index 7d197dbdbdc..36731b7b5d3 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -53,6 +53,11 @@ jobs: - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: determinate: false + # Trust the flake's cachix substituter, as check.yml does, so the dev + # shell is substituted rather than built from source. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= # Restore only, like `tests` below. Saving its own store cost 3.6 GB of the # repository's 10 GB budget and evicted the one every pull request restores. @@ -174,6 +179,11 @@ jobs: - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: determinate: false + # Trust the flake's cachix substituter, as check.yml does, so the dev + # shell is substituted rather than built from source. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= - name: Rust cache uses: ./.github/actions/rust-cache - name: Test @@ -277,6 +287,11 @@ jobs: - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: determinate: false + # Trust the flake's cachix substituter, as check.yml does, so the dev + # shell is substituted rather than built from source. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= - name: Install nightly Rust uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable with: diff --git a/.github/workflows/obs.yml b/.github/workflows/obs.yml index 05e78169b9f..e4c696d0c06 100644 --- a/.github/workflows/obs.yml +++ b/.github/workflows/obs.yml @@ -7,7 +7,9 @@ name: OBS # Linux is the platform that needs no bundle at all -- nixpkgs has obs-studio, # Qt6 and ffmpeg, so the `.#obs` shell is the whole dependency set. The plugin is # platform-independent C++ over libmoq's C ABI, so a Linux compile catches the -# breakage a macOS developer would otherwise ship uncompiled. +# breakage a macOS developer would otherwise ship uncompiled. The macOS and +# Windows release builds cover the rest: each platform's link line and the +# obs-deps bundle. # # Narrow trigger, like swift.yml: the plugin's own sources, the libmoq header # they call through, and the flake that supplies the toolchain. @@ -36,13 +38,28 @@ name: OBS # A list of paths still can't be complete here -- a vendored C source or a # .cargo/config.toml could do it too -- and `rs/**` would run this on nearly # every PR, which is the cost that removed the Windows and macOS gates (#2600). -# So this filter covers the likely inputs at PR time and nightly.yml runs the -# same recipe diff-independently to cover the rest. +# So this filter covers the likely inputs at PR time, and pushes to `main` and +# `dev` rebuild on any Rust or plugin change to cover the rest. nightly.yml also +# runs the Linux recipe diff-independently. permissions: contents: read on: + push: + branches: [main, dev] + paths: + - "rs/**" + - "cpp/obs/**" + - "doc/lib/c/**" + - "doc/lib/samples.sh" + - ".cargo/**" + - "Cargo.toml" + - "Cargo.lock" + - "rust-toolchain.toml" + - "flake.nix" + - "flake.lock" + - ".github/workflows/obs.yml" pull_request: # `closed` is here only so merging/closing a PR cancels its in-flight run # via the concurrency group below; the job itself is skipped on close. @@ -61,9 +78,12 @@ on: - "flake.lock" - ".github/workflows/obs.yml" +# Keyed and cancelled like platform.yml: a merged PR's `closed` run must not +# cancel the push run it triggers, and `main` merges faster than a push run +# finishes, so pushes queue rather than cancel. concurrency: - group: obs-${{ github.ref }} - cancel-in-progress: true + group: obs-${{ github.event_name }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} jobs: build: @@ -108,3 +128,39 @@ jobs: # cargo step inside is a no-op and this is just a cc and a run. - name: libmoq C fixtures run: nix develop .#obs --command just rs c-tests + + # The release build of the OBS plugin, minus the published libmoq: build.sh + # without `--libmoq-release` links the in-tree rs/libmoq instead, so a PR is + # checked against its own C ABI. The obs-deps bundle (libobs, Qt6, ffmpeg) + # comes from buildspec.json at configure time, same as a tag build. + release: + name: OBS (${{ matrix.name }}) + if: github.event.action != 'closed' + runs-on: ${{ matrix.os }} + timeout-minutes: 60 + strategy: + fail-fast: false + matrix: + include: + - name: macOS + target: aarch64-apple-darwin + os: macos-latest + - name: Windows + target: x86_64-pc-windows-msvc + # The plugin preset uses the Visual Studio 17 2022 generator. + os: windows-2022 + + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Install Rust + uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable + + - name: Build + shell: bash + env: + TARGET: ${{ matrix.target }} + run: ./cpp/obs/build.sh --target "$TARGET" --output "$RUNNER_TEMP/obs" diff --git a/.github/workflows/platform.yml b/.github/workflows/platform.yml index d7e35342403..8abd8d483f5 100644 --- a/.github/workflows/platform.yml +++ b/.github/workflows/platform.yml @@ -3,18 +3,15 @@ name: Platform # Compiles the workspace on Windows and macOS, the `#[cfg(...)]` code no Linux # job compiles at all: moq-video's Media Foundation and VideoToolbox backends, # their capture paths, moq-audio's ScreenCaptureKit capture, and the smaller -# platform branches elsewhere. It also builds the OBS plugin against the -# obs-deps bundle, which obs.yml can't do on Linux. Without this, a change that -# breaks any of them (a moq-net type they consume, say) merges green and -# compiles for the first time in a tag-triggered release build. +# platform branches elsewhere. Without this, a change that breaks any of them +# (a moq-net type they consume, say) merges green and compiles for the first +# time in a tag-triggered release build. # -# Filtered to the Rust workspace and the OBS plugin, rather than to each job's -# exact dependency graph like android.yml: these are the slowest and most -# expensive runners in CI, and a quest or docs PR has nothing for them to build. -# -# Pushes to `main` and `dev` catch the break two individually green PRs make -# once both land, which is what the nightly run of these jobs used to cover. -# `dev` never ran the nightly at all. +# A pull request compiles only the crates it changed plus their dependents, +# the same selection the Linux `check` job makes, because these are the +# slowest and scarcest runners in CI. Pushes to `main` and `dev` compile +# everything, catching the break two individually green PRs make once both +# land. `dev` never ran the nightly at all. # # Outside Nix, like android.yml: neither runner has it, so each installs the # runner-native toolchain. rust-toolchain.toml still pins the compiler, and the @@ -32,7 +29,6 @@ on: branches: [main, dev] paths: - "rs/**" - - "cpp/**" - ".cargo/**" - "Cargo.toml" - "Cargo.lock" @@ -45,7 +41,6 @@ on: types: [opened, synchronize, reopened, closed] paths: - "rs/**" - - "cpp/**" - ".cargo/**" - "Cargo.toml" - "Cargo.lock" @@ -59,7 +54,10 @@ concurrency: # PR's `closed` run can report the base branch as its ref instead of the PR's # merge ref, and then wouldn't cancel the PR's in-flight run. group: platform-${{ github.event_name }}-${{ github.event.pull_request.number || github.ref }} - cancel-in-progress: true + # Pushes queue instead: `main` merges faster than these jobs finish, so + # cancelling meant almost no push run ever reported. Actions keeps only the + # newest pending run, so queued merges still coalesce. + cancel-in-progress: ${{ github.event_name == 'pull_request' }} env: JUST_VERSION: 1.52.0 @@ -76,6 +74,8 @@ jobs: uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false + # Full history so a pull request can diff against its base. + fetch-depth: 0 - name: Install Rust uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable @@ -96,7 +96,9 @@ jobs: - name: Check shell: bash - run: just rs windows + env: + SCOPE: ${{ github.event_name == 'push' && '--all' || '' }} + run: just rs windows "$SCOPE" macos: name: macOS @@ -109,6 +111,7 @@ jobs: uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false + fetch-depth: 0 - name: Install Rust uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable @@ -119,40 +122,6 @@ jobs: tool: just@${{ env.JUST_VERSION }} - name: Check - run: just rs macos - - # The release build of the OBS plugin, minus the published libmoq: build.sh - # without `--libmoq-release` links the in-tree rs/libmoq instead, so a PR is - # checked against its own C ABI. The obs-deps bundle (libobs, Qt6, ffmpeg) - # comes from buildspec.json at configure time, same as a tag build. - obs: - name: OBS (${{ matrix.name }}) - if: github.event.action != 'closed' - runs-on: ${{ matrix.os }} - timeout-minutes: 60 - strategy: - fail-fast: false - matrix: - include: - - name: macOS - target: aarch64-apple-darwin - os: macos-latest - - name: Windows - target: x86_64-pc-windows-msvc - # The plugin preset uses the Visual Studio 17 2022 generator. - os: windows-2022 - - steps: - - name: Checkout - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - - - name: Build - shell: bash env: - TARGET: ${{ matrix.target }} - run: ./cpp/obs/build.sh --target "$TARGET" --output "$RUNNER_TEMP/obs" + SCOPE: ${{ github.event_name == 'push' && '--all' || '' }} + run: just rs macos "$SCOPE" diff --git a/.github/workflows/release-dart-ffi.yml b/.github/workflows/release-dart-ffi.yml index 0396251ace9..73dd54b38af 100644 --- a/.github/workflows/release-dart-ffi.yml +++ b/.github/workflows/release-dart-ffi.yml @@ -12,13 +12,16 @@ on: # workflow this way so a broken build surfaces before the tag is cut. workflow_call: workflow_dispatch: + # Packaging changes only, like the other FFI release workflows. A change to + # the moq-ffi sources is covered on every platform by cheaper gates: check.yml + # compiles it and regenerates the Dart bindings, platform.yml and swift.yml + # compile it for macOS, Windows, and iOS, and nightly runs this full matrix. pull_request: paths: - ".github/workflows/release-dart-ffi.yml" - "dart/moq_ffi/**" - "dart/scripts/**" - - "rs/moq-ffi/**" - - "!rs/moq-ffi/Cargo.toml" + - "rs/moq-ffi/build.sh" permissions: contents: read diff --git a/.github/workflows/release-js.yml b/.github/workflows/release-js.yml index a8480c33106..422a685f123 100644 --- a/.github/workflows/release-js.yml +++ b/.github/workflows/release-js.yml @@ -38,6 +38,11 @@ jobs: - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: determinate: false + # Trust the flake's cachix substituter, as check.yml does. Without it + # `nix develop` built the dev shell from source, about 13 minutes. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= - name: Setup npm registry uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v6 diff --git a/.github/workflows/release-py.yml b/.github/workflows/release-py.yml index b2ba9f0cd2f..8e66b73f188 100644 --- a/.github/workflows/release-py.yml +++ b/.github/workflows/release-py.yml @@ -105,6 +105,11 @@ jobs: - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: determinate: false + # Trust the flake's cachix substituter, as check.yml does, so the dev + # shell is substituted rather than built from source. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= - name: Build run: nix develop --command just py package diff --git a/rs/justfile b/rs/justfile index 68677b5bef6..78834941d2a 100644 --- a/rs/justfile +++ b/rs/justfile @@ -587,16 +587,11 @@ fix-changed $FILES: # # Default features rather than `--all-features`: jemalloc doesn't build on # MSVC, and the Linux-only features (vaapi, pipewire, io-uring) have nothing to -# compile here. moq-gst is excluded because it links GStreamer via pkg-config, -# which the runner doesn't have. -# -# `moq-cli/play` and `moq-cli/capture` are named explicitly because they are -# off by default, and they are what turns on the device and render code in -# moq-video, moq-audio, and the cli itself. +# compile here. -# Compile the whole workspace on a Windows host. Must run ON Windows. -windows *args: - cargo check --locked --workspace --exclude moq-gst {{ no_fuzz }} --all-targets --features "moq-cli/play moq-cli/capture" {{ args }} +# Compile what the branch changed since BASE on a Windows host, or everything with `--all`. +windows $BASE="": + just rs _platform "$BASE" # Compile and test the io_uring relay path, which is off the default feature set. # Linux-only, and the tests below the 6.12 kernel floor skip themselves. @@ -619,14 +614,51 @@ uring-check *args: # encode/decode and its ScreenCaptureKit / AVFoundation capture, moq-audio's # ScreenCaptureKit system audio and TCC permission pre-check, and moq-sock's # BSD socket-buffer sysctl. platform.yml runs this alongside `windows`. + +# Compile what the branch changed since BASE on a macOS host, or everything with `--all`. +macos $BASE="": + just rs _platform "$BASE" + +# The shared body of `windows` and `macos`, scoped like `check-changed` so a +# one-crate PR compiles one crate on these slow runners too. moq-gst is dropped +# because it links GStreamer via pkg-config, which the runners don't have. # -# The same workspace and features as `windows`, for the same reasons: moq-gst -# needs GStreamer, and the cli's `play` and `capture` features are what turn on -# the device and render code. +# `moq-cli/play` and `moq-cli/capture` are named explicitly because they are +# off by default, and they are what turns on the device and render code in +# moq-video, moq-audio, and the cli itself. Only when moq-cli is selected, +# since cargo rejects a feature of a package outside the selection; any change +# to the crates those features reach selects moq-cli as a dependent anyway. + +# Compile what the branch changed since BASE plus its dependents, or everything with `--all`. +[private] +_platform $BASE: + #!/usr/bin/env bash + set -euo pipefail + packages=ALL + if [[ "$BASE" != --all ]]; then + files=$(just _changed "$BASE") + # `_select` reads an empty list as everything, so an empty diff stops here. + if [[ -z "$files" ]]; then + echo "rs: nothing changed; skipping." + exit 0 + fi + [[ "$files" == ALL ]] || packages=$(just rs _select "$files") + fi -# Compile the whole workspace on a macOS host. Must run ON macOS. -macos *args: - cargo check --locked --workspace --exclude moq-gst {{ no_fuzz }} --all-targets --features "moq-cli/play moq-cli/capture" {{ args }} + features="--features moq-cli/play,moq-cli/capture" + if [[ "$packages" == ALL ]]; then + cargo check --locked --workspace --exclude moq-gst {{ no_fuzz }} --all-targets $features + exit 0 + fi + + packages=$(sed -E 's|--package [^ ]*/moq-gst#[^ ]* ?||' <<< "$packages") + if [[ -z "${packages// }" ]]; then + echo "rs: no crates affected; skipping." + exit 0 + fi + just rs _wants-play "$packages" || features="" + echo "rs: checking $(just rs _names "$packages")" + cargo check --locked $packages --all-targets $features # The Linux device code: moq-video's V4L2 and X11 capture and moq-audio's cpal # capture, all behind the off-by-default `capture` feature. `check-changed` runs From e6679baa8783d6820eefe8005e7d728a77284611 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 14:30:05 -0700 Subject: [PATCH 050/128] chore(quest): plan media stats as hang tracks and viewer feedback as .echo broadcasts (#4510) Co-authored-by: Claude Opus 5.5 --- quest/m1/README.md | 4 +- quest/m1/catalog-track-alias.md | 52 ++++++++++ quest/m1/closure-counters.md | 5 - quest/m1/qos/README.md | 26 ++--- quest/m1/qos/lag-dashboard.md | 6 +- quest/m1/qos/publisher-timeliness.md | 4 +- quest/m1/qos/starvation.md | 2 +- quest/m1/qos/stats/README.md | 63 ------------ quest/m1/qos/stats/encoder-feedback.md | 52 ---------- quest/m1/qos/stats/js.md | 37 ------- quest/m1/qos/stats/per-track.md | 42 -------- quest/m1/qos/stats/rust.md | 38 ------- quest/m1/qos/stats/schema.md | 71 ------------- quest/m1/stats/README.md | 133 +++++++++++++++++++++++++ quest/m1/stats/encoder-feedback.md | 70 +++++++++++++ quest/m1/stats/js.md | 38 +++++++ quest/m1/stats/rust.md | 47 +++++++++ quest/m1/stats/schema.md | 67 +++++++++++++ quest/m2/latency-ledger.md | 8 +- quest/m2/stats-delta.md | 11 +- quest/m2/teleop/README.md | 6 +- quest/m2/teleop/robot.md | 4 +- quest/m2/ts-health-stats.md | 17 ++-- 23 files changed, 452 insertions(+), 351 deletions(-) create mode 100644 quest/m1/catalog-track-alias.md delete mode 100644 quest/m1/qos/stats/README.md delete mode 100644 quest/m1/qos/stats/encoder-feedback.md delete mode 100644 quest/m1/qos/stats/js.md delete mode 100644 quest/m1/qos/stats/per-track.md delete mode 100644 quest/m1/qos/stats/rust.md delete mode 100644 quest/m1/qos/stats/schema.md create mode 100644 quest/m1/stats/README.md create mode 100644 quest/m1/stats/encoder-feedback.md create mode 100644 quest/m1/stats/js.md create mode 100644 quest/m1/stats/rust.md create mode 100644 quest/m1/stats/schema.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 847b8359b7c..cbdb4795f29 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -89,7 +89,9 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Audio rendition pick](/quest/m1/audio-ranked.md) - single-track FLV/RTMP and WHEP serve the best audio rendition, not the first by name - [FLV catalog stream](/quest/m1/flv-catalog-stream.md) - on dev, `flv::Export` takes a catalog stream like fmp4, replacing `with_select` - [Own the QUIC stack](/quest/m1/quic/README.md) - the moq-noq fork carries ACK progress, reliable reset, hierarchical scheduling, deadlines, peer limits, and qmux -- [QoS](/quest/m1/qos/README.md) - broadcast health: relay starvation and timeliness histograms, and client stats broadcasts from publishers and viewers, on dev +- [QoS](/quest/m1/qos/README.md) - broadcast health: relay starvation and timeliness histograms, on dev +- [Catalog track alias](/quest/m1/catalog-track-alias.md) - catalog rendition keys become aliases with an optional `track` name, so one catalog lists renditions from several broadcasts +- [Media stats](/quest/m1/stats/README.md) - publishers announce a stats track in the catalog, viewers answer a soliciting catalog through a per-catalog `.echo` broadcast, and a Rust encoder adapts to them - [Drain](/quest/m1/drain/README.md) - relay restarts drain sessions over GOAWAY instead of hard-dropping them - [Strict Redirect::resolve](/quest/m1/redirect-resolve.md) - on dev, `Redirect::resolve` can no longer quietly turn a refused redirect into a redial - [Transport upgrade](/quest/m1/transport-upgrade/README.md) - a session that came up over WebSocket moves to QUIC once the QUIC dial lands, handing over at a group boundary diff --git a/quest/m1/catalog-track-alias.md b/quest/m1/catalog-track-alias.md new file mode 100644 index 00000000000..d2abff6177c --- /dev/null +++ b/quest/m1/catalog-track-alias.md @@ -0,0 +1,52 @@ +# [M] hang catalog rendition keys are aliases + +## Goal + +A hang catalog's video and audio rendition keys are aliases, unique within +the catalog, rather than wire track names. A rendition config gains an +optional `track`, the wire track name, beside its existing `broadcast`; +absent, the track name is the alias, so every catalog published today parses +and plays unchanged. One catalog can then list renditions from several +broadcasts that share a track name. + +## Plan + +Decided (2026-09-29) while planning [media stats](/quest/m1/stats/README.md), +which keys its snapshots by this alias: without it, a catalog referencing two +broadcasts that both publish `video` cannot list both, and a snapshot keyed by +track name would collapse them. + +- The field is `track`, beside `broadcast` on `VideoConfig` and `AudioConfig` + in `rs/hang` and their zod schemas in `js/hang`. Additive on main: an + optional field on `#[non_exhaustive]` types. +- Every reader that subscribes by the map key resolves the wire name through + one helper instead, in Rust and JS, so no path keeps assuming key equals + name. Publishers keep writing no `track` unless they need it. +- Open: a released reader ignores `track` and subscribes by the key, so it + cannot play a rendition whose `track` differs from its alias. Candidates: + accept that, since such a listing was not expressible before and a + publisher sets `track` only when it must; or move the reader change to + `dev` behind a catalog version. The maintainer settled it as additive on + main; confirm the forward-compatibility cost before starting. +- The MSF conversion in `rs/moq-mux` names MSF tracks by the key today. + It carries the wire name and keeps the alias through a round-trip test, or + refuses a catalog whose `track` differs from its alias. +- Scope: `rs/hang`, `js/hang`, their readers, `drafts/draft-lcurley-moq-hang.md` + (validate with `just drafts check`), and `doc/concept/hang.md`. +- Tests: an old catalog resolves each track name to its key; a catalog with + two renditions naming the same `track` in different broadcasts round-trips + in both languages and plays each. +- Open: text, JSON, and binary sections also carry `broadcast` and key by + track name. Candidates: keep this to video and audio, as decided, or give + every section with `broadcast` a `track` through the same helper so + resolution is uniform. +- Open: video and audio are separate maps, so one key can appear in both. + Within one broadcast that already means one track for two kinds, but with + `broadcast` references it parses today. Candidates: refuse a cross-kind + duplicate (a validation tightening on main), or accept it and kind-qualify + the stats and echo keys. + +## Related + +- [Media stats](/quest/m1/stats/README.md) - keys stats and feedback by this + alias diff --git a/quest/m1/closure-counters.md b/quest/m1/closure-counters.md index 7d209f9b90b..04fb95b8cf3 100644 --- a/quest/m1/closure-counters.md +++ b/quest/m1/closure-counters.md @@ -26,8 +26,3 @@ Settle which counters must be monotonic and over what lifetime, and whether the fresh-segment contract already permits a per-node closure reset or only a cumulative traffic regression. The answer is a consumer-facing contract, so document it in `moq-stats` rather than leaving it as an aggregate detail. - -## Related - -- [Client stats](/quest/m1/qos/stats/README.md) - publishes the same counters - to consumers diff --git a/quest/m1/qos/README.md b/quest/m1/qos/README.md index 3bf61cf0617..cc343a9c7cd 100644 --- a/quest/m1/qos/README.md +++ b/quest/m1/qos/README.md @@ -5,8 +5,8 @@ Publishers, relays, and viewers report the telemetry that broadcast health and congestion views need: how far behind viewers are according to what the network has acknowledged, how timely publishers are against their own media -clock, and what publishers and viewers report for themselves in their own -stats broadcasts. Together they can drive an +clock, and what publishers and viewers report for themselves through +[media stats](/quest/m1/stats/README.md). Together they can drive an unknown/healthy/degraded/unhealthy verdict per broadcast with congestion visible for viewers in aggregate, the way CMSD does for HLS. @@ -23,19 +23,17 @@ Everything the relay reports is distilled per broadcast on the existing `moq-stats` keys. No per-subscriber or per-session row reaches the wire from the relay: many subscriptions collapse into byte-weighted cumulative histograms, which stay monotonic and merge-patch friendly, and which any -consumer can diff into a distribution. Clients report for themselves, each in -its own `.stats` broadcast on the same layout, so viewer feedback costs -bandwidth only where a publisher or dashboard chose to read it. +consumer can diff into a distribution. Clients report for themselves through +hang stats and `.echo` feedback tracks, planned in their own line on `main`. The counters and channels land here. The moq.pro (downstream) dashboard work, including the health badge, connection-health drill-down, and stream preflight, consumes them downstream. -Decided (2026-09-28): the whole line, including the client stats line, targets -`dev`. The moq-stats schema change -([#4145](https://github.com/moq-dev/moq/pull/4145)) breaks the published -`moq-stats` crate, and a line cannot close with part of it on `main` and part -on `dev`. +Decided (2026-09-28): the whole line targets `dev`, because its moq-stats +changes break the published crate. Client stats left the line (2026-09-29) +when media stats moved out of moq-stats onto hang tracks, which are additive +on `main`. ## Required @@ -52,6 +50,8 @@ on `dev`. - [Publisher timeliness](/quest/m1/qos/publisher-timeliness.md) - per broadcast, how late media arrives at the relay against the track's own clock, and whether timestamps stay monotonic -- [Client stats](/quest/m1/qos/stats/README.md) - publishers and viewers - report their own media, transport, and playback health in `.stats` - broadcasts on the moq-stats layout, and a Rust encoder adapts to its viewers + +## Related + +- [Media stats](/quest/m1/stats/README.md) - publishers and viewers report + their own media, transport, and playback health, the media half of a verdict diff --git a/quest/m1/qos/lag-dashboard.md b/quest/m1/qos/lag-dashboard.md index c89e45f38f1..4a2d5f01ae7 100644 --- a/quest/m1/qos/lag-dashboard.md +++ b/quest/m1/qos/lag-dashboard.md @@ -21,10 +21,8 @@ and per node like the existing counters. bucket, and say which. - Skip `.`-prefixed system broadcasts, as the existing aggregate does. Lag is per broadcast, so a per-broadcast view is worth adding if it stays cheap. -- The [browser stats quest](/quest/m1/qos/stats/js.md) moves the dashboard - onto `@moq/stats` on the same line. If it has landed, read `lag` and - `dropped` through its schemas; otherwise extend the existing interfaces and - let whichever lands second reconcile. +- Extend the dashboard's existing relay-stats interfaces; no `@moq/stats` + package is planned. Public API: none. Wire: none. diff --git a/quest/m1/qos/publisher-timeliness.md b/quest/m1/qos/publisher-timeliness.md index 8fd16bf480d..682ae47d869 100644 --- a/quest/m1/qos/publisher-timeliness.md +++ b/quest/m1/qos/publisher-timeliness.md @@ -53,5 +53,5 @@ excluded. - [Starvation](/quest/m1/qos/starvation.md) - the egress half, same histogram shape -- [Client stats](/quest/m1/qos/stats/schema.md) - the publisher's own view - of the same uplink, in the transport section of its stats broadcast +- [Media stats](/quest/m1/stats/schema.md) - the publisher's own view + of the same uplink, in the transport section of its stats track diff --git a/quest/m1/qos/starvation.md b/quest/m1/qos/starvation.md index 829af00b10c..0a9131ad71e 100644 --- a/quest/m1/qos/starvation.md +++ b/quest/m1/qos/starvation.md @@ -85,5 +85,5 @@ sum into one row; the aggregate consumer sums two nodes bucket by bucket. moves the frontier at every frame end once `poll_acked` is released - [Publisher timeliness](/quest/m1/qos/publisher-timeliness.md) - the ingress mirror on the `Role::Subscriber` rows -- [Client stats](/quest/m1/qos/stats/README.md) - receiver-side evidence +- [Media stats](/quest/m1/stats/README.md) - receiver-side evidence for the same lag, reported by the viewers themselves diff --git a/quest/m1/qos/stats/README.md b/quest/m1/qos/stats/README.md deleted file mode 100644 index 2c566bd11c1..00000000000 --- a/quest/m1/qos/stats/README.md +++ /dev/null @@ -1,63 +0,0 @@ -# Client stats - -## Goal - -Any MoQ client can publish its own stats as a broadcast the way the relay -does: a publisher reports what it sends, a subscriber reports what it received -and played, and a consumer authorized to see them, a dashboard or the publisher -itself, reads them per broadcast. The same `moq-stats` layout carries the -relay's delivery counters and a media client's media counters, so one consumer -reads both, and a broadcast name ending in `.stats` is how a dashboard tells -telemetry from content. Encoders close the loop: a Rust publisher can adapt its -bitrate to what its viewers report. Not here: no wire change, no clock -synchronization, no requirement that any client report, and no relay -involvement beyond routing. - -## Plan - -Decisions settled while planning: - -- **Reuse moq-stats.** `moq_stats::Producer` and `Consumer` take an - extension flattened next to `Traffic` in every per-broadcast entry, the way - `hang::timeline::Record` does; `()` is the relay, `hang::Stats` is a - media client. Old consumers ignore the extra fields; a consumer that knows - the extension reads both halves. A client's `Traffic` comes from the same - registry the relay uses, attached through `Client::with_stats`. -- **One broadcast per client at a path its token allows, ending in - `.stats`**: `pilot/feedback.stats`, `room/alice.stats`. The relay's - `.stats/node/` prefix convention stays; moq-stats documents both. - Reporting is opt-in because reading is: a publisher subscribes to a prefix - it chose, never to every viewer. -- **`publisher.json` and `subscriber.json` stay the everything entry points**, - keyed by broadcast path as the client sees it, so a transcoder's report - attributes each rung to its broadcast. A consumer that wants one broadcast - requests `/subscriber.json` or `/publisher.json` (plus `.z`) - and the producer serves it on demand, the way tier tracks are served - today. On a tiered relay the name is `//...`, matched against - the producer's tier labels longest first; a default-tier broadcast whose - path starts with another tier's label is refused rather than guessed. -- **Counters are cumulative**, like `Traffic`, so `.z` merge-patch deltas stay - small and the aggregate can sum across clients. Gauges, a latency or a - target bitrate, are carried but never summed. -- **Publisher transport rides here.** The publisher role carries a - `transport` section sampled from `ConnectionStats` for the connection the - broadcast is published over, replacing the connection-scoped channel the - QoS line planned. Self-reports are diagnostics: never billing, - authorization, or route-selection input. -- **A published break goes through dev**, because `moq-stats` is a published crate and the generic - producer is a breaking change, and the moq-json rework there is what the - producers build on. The parent QoS line targets `dev` with it (#4145), so - every quest here does too. - -## Required - -- [Per-track stats](/quest/m1/qos/stats/per-track.md) - decide whether media - stats ride one track per catalog track, before the schema settles -- [Schema and library](/quest/m1/qos/stats/schema.md) - moq-stats takes an - extension, serves per-broadcast tracks, and hang defines the media stats -- [Rust reporters](/quest/m1/qos/stats/rust.md) - the CLI, players, and - encoders publish and read `.stats` broadcasts -- [Browser reporters](/quest/m1/qos/stats/js.md) - `@moq/stats` mirrors the - crate, and the browser publisher and player report through it -- [Encoder feedback](/quest/m1/qos/stats/encoder-feedback.md) - a Rust - encoder subscribes to its viewers' stats and adapts its bitrate diff --git a/quest/m1/qos/stats/encoder-feedback.md b/quest/m1/qos/stats/encoder-feedback.md deleted file mode 100644 index f6391b0b7ca..00000000000 --- a/quest/m1/qos/stats/encoder-feedback.md +++ /dev/null @@ -1,52 +0,0 @@ -# [M] A Rust encoder adapts its bitrate to what its viewers report - -## Goal - -A `moq-video` or `moq-audio` encode producer given a feedback prefix -subscribes to the `.stats` broadcasts announced under it, reads the -per-broadcast subscriber track for the broadcast it publishes, and lowers its -bitrate while viewers report stalls and late frames, beside the congestion -estimate it already follows. Which viewers count is the publisher's choice of -prefix. Keyframe requests stay out. - -## Plan - -- `encode::Options` in `rs/moq-video` and `rs/moq-audio` (the producer - options, beside `bandwidth`) gains `feedback: Option`, - a handle built from an - `origin::Consumer` and a prefix: it consumes announcements under the - prefix, keeps one `moq_stats::Consumer` per `.stats` broadcast - requesting `/subscriber.json`, and folds the reports into one - signal, the share of viewers stalled over the last interval and their late - frame rate, weighted equally per viewer. The counters are cumulative, so - the handle keeps the previous snapshot per viewer and diffs it; a counter - that goes backwards is a restarted viewer and resets that baseline. Viewers - that stop reporting age out on the stats interval, so one stall long ago - never lowers the target forever. -- `moq_mux::rate::Control` takes that signal beside the bandwidth estimate: - a stalled share - above a threshold steps the target down like a bandwidth drop, recovery - follows the existing attack curve, and the estimate stays the ceiling. - Audio does not follow its grant today (`Options::bandwidth` in - `rs/moq-audio/src/encode/producer.rs` reserves only), so it follows this - signal only once the grant quest lands; until then the loop drives video. -- `moq import --feedback ` and `moq transcode --feedback ` - wire it; each rung of the ladder reads its own broadcast's track. -- Test with the CLI publishing to a relay and two `moq play --stats` viewers - under the prefix, one throttled through the impairment profile: the target - bitrate drops within two intervals of the throttled viewer reporting stalls - and recovers after it stops. Document the flag in `doc/bin/cli.md` and the - loop in the moq-video README. - -## Required - -- [Schema and library](/quest/m1/qos/stats/schema.md) - the feedback it reads -- [Rust reporters](/quest/m1/qos/stats/rust.md) - the viewers that report and - the CLI it wires - -## Related - -- [Ladder](/quest/m1/ladder/README.md) - the transcode ladder that adapts to - its uplink today -- [Audio follows the grant](/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - - the audio rate follow this signal would feed diff --git a/quest/m1/qos/stats/js.md b/quest/m1/qos/stats/js.md deleted file mode 100644 index 280092e32c2..00000000000 --- a/quest/m1/qos/stats/js.md +++ /dev/null @@ -1,37 +0,0 @@ -# [M] The browser publisher and player report stats - -## Goal - -`@moq/stats` mirrors `moq-stats`: the frame schemas, `Producer`, -`Consumer`, the aggregate, and the `.stats` naming. `@moq/hang` defines the -media stats schema, `` publishes subscriber stats and -`` publisher stats when given a stats path, and the demo -dashboard reads relay stats through the package instead of its own copies. - -## Plan - -- `js/stats`: zod schemas for `Traffic`, `Presence`, and `Stats` with the - extension flattened; snapshot-mode producer pairs (`.json` and `.z`) with - the same delta and compression settings as Rust; the per-broadcast track - served on request through the broadcast's requested-track handle; a - consumer keyed by tier, role, and path; and the aggregate. Fixtures are the - Rust crate's, shared through `js/test`, so the two encoders stay wire - identical. -- `@moq/hang` adds `Stats` in `js/hang/src/stats.ts`, mirroring - `rs/hang/src/stats.rs` field for field. -- `js/watch`: the decoder `Stats` signals grow the counters the schema needs - (late, stalled duration, underruns from the worklet's count, decode errors, - newest timestamp) and a `stats` attribute names the broadcast to publish - at; `js/publish` does the same for the encoder counters, with the - connection's `WebTransport.getStats()` as the transport section. The - existing UI stats panels read the same signals. -- `demo/web/src/stats.ts` drops its hand-written interfaces and - `STATS_PREFIX` for the package, and the demo gains a stats path on both - elements so the media test reads a browser viewer's report through - `moq export stats`. -- `doc/lib/js` documents the package. - -## Required - -- [Schema and library](/quest/m1/qos/stats/schema.md) - the wire shape this - mirrors diff --git a/quest/m1/qos/stats/per-track.md b/quest/m1/qos/stats/per-track.md deleted file mode 100644 index e166d3ca755..00000000000 --- a/quest/m1/qos/stats/per-track.md +++ /dev/null @@ -1,42 +0,0 @@ -# [S] Plan per-track stats tracks - -## Goal - -Decide whether a media publisher's stats ride one track per catalog track -instead of one entry per broadcast, and rewrite the stats quests to match. -This quest writes quests, not code. - -## Plan - -Run `/quest-plan` against this line and #4145. Raised while planning TR 101 -290 monitoring (#4496): `hang::Stats { audio, video, transport }` sums every -rendition of a kind, so a simulcast ladder is indistinguishable, and a -per-rendition map would repeat the catalog's structure in a parallel type. - -The proposal: a catalog track gains `stats: "video/hd.stats"`, a separate track -served on request, and a container section does the same (`mpegts.stats` from -the catalog's `mpegts` section). Stats stay off the catalog track itself, -which would churn every viewer's catalog on each interval. - -For it: no parallel structure, a dashboard subscribes only to the renditions -it watches and an unrequested track costs nothing, each section owns its -counters with no flattened extension or `Merge` wrapper, and moq-mux -importers already count per track. - -Against it, and what the session must answer: - -1. Subscriber reports: a viewer cannot be referenced from the publisher's - catalog, so its received, decoded and stalled counters still need its own - `.stats` broadcast. Does that broadcast mirror per-track tracks, or keep the - moq-stats entry? -2. The relay is media-agnostic and keeps moq-stats' per-broadcast `Traffic`; - is splitting media publishers onto a second mechanism acceptable against - this line's "one consumer reads both halves" goal? -3. Aggregation: N broadcasts × M tracks subscriptions against one per node. -4. If moq-stats entries stay, key media counters per track name rather than - per kind. - -## Related - -- [Schema and library](/quest/m1/qos/stats/schema.md) - the shape this may replace -- [TS health stats](/quest/m2/ts-health-stats.md) - waits on this for its section's shape diff --git a/quest/m1/qos/stats/rust.md b/quest/m1/qos/stats/rust.md deleted file mode 100644 index 2a9f7ebb07c..00000000000 --- a/quest/m1/qos/stats/rust.md +++ /dev/null @@ -1,38 +0,0 @@ -# [M] The Rust CLI, players, and encoders report stats - -## Goal - -`moq import --stats ` publishes a `.stats` broadcast reporting what the -import sends, `moq export --stats ` and `moq play --stats ` report -what the player received and played, and `moq export stats ` prints any -stats broadcast, the relay's `.stats/node/` included, as JSON lines. A -publisher of a `.hang` broadcast can learn whether its viewers played it. - -## Plan - -- Counters at the source, in the crates that own the event: the `moq-video` - and `moq-audio` encode producers count frames, bytes, keyframes, and drops; - the decode and render paths count decoded, late, stalled, underruns, and - errors, where `underruns` in `rs/moq-audio/src/playback` is already counted - privately. Each exposes a `stats()` snapshot of cumulative counters; no - callback, no per-frame lock. -- `moq-cli` attaches a `moq_net::stats::Session` to its client through - `Client::with_stats`, folds the codec counters into `hang::Stats` per - broadcast on the stats interval, and publishes through - `moq_stats::Producer` in exact-path mode at the flag's path. - A path that does not end in `.stats` is refused at parse time. The transport section comes from - the connection's `ConnectionStats`. -- `moq export stats ` is a new sink: subscribe the stats broadcast and - print each `publisher.json`, `subscriber.json`, and `sessions.json` frame - as one JSON line tagged with its track, with `--track` selecting one and - `--compressed` reading the `.z` twins. It is the one sink that does not go - through `.hang` catalog discovery, so route it around `catalog_format`. -- `doc/bin/cli.md` documents the flag and the sink. The media test - publishes with `--stats`, plays with `--stats`, and reads both with - `moq export stats`, asserting the subscriber's liveness advances and the - publisher's frame count matches what was sent. - -## Required - -- [Schema and library](/quest/m1/qos/stats/schema.md) - the producer and the - media types diff --git a/quest/m1/qos/stats/schema.md b/quest/m1/qos/stats/schema.md deleted file mode 100644 index 2a60d265ece..00000000000 --- a/quest/m1/qos/stats/schema.md +++ /dev/null @@ -1,71 +0,0 @@ -# [L] moq-stats takes an extension and hang defines the media stats - -## Goal - -`moq_stats::Producer` publishes a stats broadcast whose per-broadcast -entries are `Traffic` plus an extension `E`, `Consumer` and the aggregate -read it back, any consumer can request one broadcast's entry as its own -track, and `hang::Stats` is the media extension: what a publisher sent and -what a subscriber received and played, per audio and video. The relay is -`Producer<()>` and its wire output does not change. - -## Plan - -- `moq_stats::Ext`: `Serialize + DeserializeOwned + Default + Clone + Merge`, - implemented for `()`. `Merge` is the aggregate's private `Mergeable` made - public with the `Copy` bound dropped; `Traffic` and `Presence` implement it - as they do today. A frame is `BTreeMap>`, where `Stats` - is `Traffic` with `E` flattened beside it; `TrafficFrame` becomes that - alias for `()`. `sessions.json` stays a core track outside the extension: - `[/]sessions.json[.z]`, a `BTreeMap` keyed by auth - root, read through `Consumer::sessions` whatever `E` is; a client publishes - it only when it holds sessions worth counting. -- An exact-path mode. `produce::Config` treats its path as a prefix and - advertises `/node[/]`, so a client asking for - `room/alice.stats` would publish `room/alice.stats/node`, which no longer - ends in `.stats`. `produce::Config::at(path)` publishes the broadcast at - exactly that path with no category segment, refusing a path that does not - end in `.stats`; the relay keeps the prefix layout. Test the advertised - path for both modes. -- Per-broadcast tracks: `requested_track_shape` in - `rs/moq-stats/src/produce.rs` accepts - `[/]/{publisher,subscriber}.json[.z]` by matching the - producer's tier labels longest first, and refuses a default-tier path that - starts with another tier's label. The track is a snapshot of that one - entry, emitted on the same interval, and lives while requested under the - existing quotas. `Consumer` gains `traffic_for(tier, role, path)`. -- `hang::Stats { audio, video, transport }` in `rs/hang/src/stats.rs`, one - struct per role folded into sections, every field defaulted and unknown - fields ignored: - - subscriber, per audio and video: bytes and frames received, frames - decoded, frames dropped as late, stalls and stalled duration, audio - underruns, decode errors, the newest media timestamp received and the - wall time it arrived (liveness: exact in media time, as good as the - clock in wall time), and the current playout latency as a gauge; - - publisher, per audio and video: frames, bytes, keyframes, frames dropped - before encode, and the target bitrate as a gauge; - - publisher `transport`: rtt, estimated send rate, bytes and packets lost, - and sample age from `ConnectionStats`, repeated across the broadcasts one - connection carries. - `Merge` sums counters, leaves gauges out of the sum, and keeps the newest - liveness pair. -- Naming: `.stats` as a broadcast suffix, documented in the `moq-stats` - crate docs and `doc/lib/rs/index.md` beside the relay's prefix convention, - with `moq_stats::is_stats(path)` so a dashboard filters telemetry from - content. -- The relay keeps `Producer<()>`; the `[stats]` section of - `doc/bin/relay/config.md` gains the per-broadcast track and its refusal - rule. Fixtures: a relay frame parses as `Stats<()>` and as - `Stats` with the extension defaulted; a media frame parses - under the old `Traffic` with the extension ignored; the aggregate sums two - clients' counters and leaves gauges alone; the per-broadcast track for a - tiered name and a refused ambiguous one. -- Drop the legacy `announced` / bare-plural / `*_closed` spellings from the - `Traffic` and `Presence` serializers once a moq-stats release carrying both - has shipped and the demo dashboard (and any moq.pro consumer) reads the - `*_started` / `*_ended` names. Deserialize keeps accepting them. Wire only. - -## Related - -- [Starvation](/quest/m1/qos/starvation.md) - the relay's delivery counters, - the other half of a health verdict diff --git a/quest/m1/stats/README.md b/quest/m1/stats/README.md new file mode 100644 index 00000000000..24828d41bce --- /dev/null +++ b/quest/m1/stats/README.md @@ -0,0 +1,133 @@ +# Media stats and viewer feedback + +## Goal + +A hang publisher can announce a stats track in its catalog, and a publisher +that wants to hear from its viewers can solicit feedback there too. The +publisher's `stats` track is one snapshot of what it sent, per rendition and +for its connection. A viewer publishes one `.echo` broadcast per soliciting +catalog it reads, carrying what it received and played, per rendition, and +its own connection. A dashboard reads both the same way a publisher does, and +a Rust encoder adapts its bitrate to what its viewers report. Stats and +feedback cost nothing on the network unless someone subscribes. Not here: the +relay's `moq-stats` layout, which stays as it is; clock synchronization; any +requirement that a client report; and feedback as an input to billing, +authorization, or route selection. + +## Plan + +Decided while planning. This supersedes the moq-stats extension design of +[#4145](https://github.com/moq-dev/moq/pull/4145), revives +[moq#2734](https://github.com/moq-dev/moq/issues/2734) in a reshaped form, and +answers the per-track stats question raised in +[#4496](https://github.com/moq-dev/moq/pull/4496): one snapshot track per +catalog keyed by rendition, not a stats track per rendition and not a sum per +kind. + +- **Media stats leave moq-stats.** The relay is media-agnostic and keeps + `Traffic`, `Presence`, and `.stats/node/` unchanged. Media stats are + hang tracks, discovered through the catalog, so no `Producer` + extension, `Merge` wrapper, or flattened generic is needed. One layout for + relay and clients is given up on purpose. +- **Publisher: `stats: { track }` in the catalog.** A root section naming one + snapshot track: `{ transport, renditions: { : stats::Track } }`, + plus container sections flattened in the way `Catalog` flattens + `ts::Ext`. The stats stay off the catalog track, which would otherwise churn + for every viewer on each interval. +- **Keyed by rendition alias** (2026-09-29). Both snapshots key by the + catalog's rendition keys, which [catalog track + alias](/quest/m1/catalog-track-alias.md) makes aliases unique within a + catalog. Nothing repeats the catalog's `video`/`audio` nesting; the kind + comes from the catalog entry. A viewer reports a rendition that references + another broadcast to the catalog that lists it, under its alias there. The + publisher's own snapshot covers only renditions it writes and omits + referenced ones, whose sender reports them in its own catalog. + Reason: a track name alone collides once a catalog lists renditions from + several broadcasts. +- **Viewer: feedback only when solicited.** Most publishers do not read + feedback, so a publisher solicits it with a root `echo: { path }` section; + absent means none. The section is an object so later fields stay additive. + Root key collisions with application extensions are accepted, not guarded. +- **Echo path in the catalog** (2026-09-29). `path` is relative to the + broadcast serving the catalog and resolves like a rendition's `broadcast` + (URL-style, so from `room/live`, `viewers` is `room/viewers` and + `live/viewers` is `room/live/viewers`). A viewer publishes its `.echo` + broadcast under the resolved prefix at a name the application gives it. The + application issues tokens to match. Reason: applications control the + layout and the token rights, and the publisher reads exactly that prefix. +- **One `.echo` broadcast per catalog** (2026-09-29). A viewer announces it + only after reading the soliciting catalog, and it carries one feedback + track at a fixed name hang defines. It is not a hang broadcast and has no + catalog, so no player lists it as content, and the suffix lets a reader + filter at announce time. The name is generic so keyframe requests and + bandwidth estimates can join later. Reason: a shared `.echo` serving a + track per publisher needed accept-any-name serving, claims, refusals, and + an unclaimed cap to survive name collisions and a publisher subscribing + before the viewer read the catalog; one broadcast per catalog removes the + collisions, the race, and the cap with less code, and needs no JS track + request API. +- **Trust is the token prefix** (2026-09-29). Whoever the application's + tokens let publish under the echo path may report, and no report is + authenticated beyond that. How far one viewer may move the encoder is + application-specific (a simulcast ladder suffers less from one viewer than + a single rendition), so the encoder's built-in step-down policy takes a + tunable config that the application can adjust or disable. +- **Feedback track: one snapshot**, `{ transport, renditions: { : + echo::Track } }`, so the publisher looks up its own renditions directly. +- **One type per role, shared across kinds.** + - `stats::Track`: sent frames and bytes, keyframes, skipped frames, target + bitrate. + - `echo::Track`: received, decoded, late, decode errors, stalls, + stalled duration, underruns, newest arrival, latency. + - A kind's unused fields are omitted. + - `transport` is one type at both roles: rtt, rate, loss, sample age. A + browser has only PROBE rtt until + [#2733](https://github.com/moq-dev/moq/issues/2733)-style counters land. +- **Encoding**: cumulative counters about once a second through + `moq_json::snapshot`, with the `.z` merge-patch sibling, produced whenever + stats are enabled. An unsubscribed stats track never leaves the process. + Gauges are carried but never summed. +- **On main.** Every change is additive: optional sections on + `#[non_exhaustive]` catalog types, and new types. The line left the + [QoS](/quest/m1/qos/README.md) line, which stays on `dev` for the relay's + moq-stats changes. +- **No `@moq/stats` package.** Media types live in `@moq/hang`, and the + demo dashboard's relay-stats reader stays where it is. +- Docs stay inline: `doc/concept/hang.md` documents both catalog sections, + `doc/concept/stats.md` gains a media section beside the relay's, and + `drafts/draft-lcurley-moq-hang.md` specs the wire. + +Open, to settle before [encoder feedback](/quest/m1/stats/encoder-feedback.md) +starts: + +- **Referenced-rendition feedback.** A derivative catalog (a `moq-transcode` + passthrough) collects feedback for a source rendition it lists, but owns + no encoder for it, and the source encoder reads only its own catalog's + prefix. Candidates: the derivative forwards those rows to the source's + echo path, or the source encoder also reads catalogs that reference it, + or referenced renditions stay report-only. +- **Shared echo prefixes.** Two catalogs can resolve their echo paths to one + prefix (`../viewers` from `room/a/live` and `room/b/live`). Then a viewer + using one name for both closes one `.echo` with the other, and each + publisher reads the other's reports under a shared alias. Candidates: + require each catalog's echo prefix to be its own, as application policy + like the token rights, or carry the catalog's broadcast in the snapshot + and ignore reports for another. + +## Required + +- [Catalog track alias](/quest/m1/catalog-track-alias.md) - rendition keys + become aliases, the key both snapshots use +- [Schema](/quest/m1/stats/schema.md) - hang defines the `stats` and + `echo` catalog sections, their snapshot types, and the draft text +- [Rust reporters](/quest/m1/stats/rust.md) - the CLI, players, encoders, and + moq-mux remuxes publish stats and feedback +- [Browser reporters](/quest/m1/stats/js.md) - `` publishes + stats and `` publishes feedback +- [Encoder feedback](/quest/m1/stats/encoder-feedback.md) - a Rust encoder + reads its viewers' feedback and adapts its bitrate + +## Related + +- [QoS](/quest/m1/qos/README.md) - the relay's delivery counters, the other + half of a health verdict diff --git a/quest/m1/stats/encoder-feedback.md b/quest/m1/stats/encoder-feedback.md new file mode 100644 index 00000000000..e30ad835cec --- /dev/null +++ b/quest/m1/stats/encoder-feedback.md @@ -0,0 +1,70 @@ +# [M] A Rust encoder adapts its bitrate to what its viewers report + +## Goal + +A `moq-video` or `moq-audio` encode producer given a feedback handle solicits +feedback in its catalog. It reads the feedback track from every `.echo` +broadcast announced under the catalog's echo path, and lowers its bitrate +while viewers report stalls and late frames, beside the congestion estimate +it already follows. Keyframe requests stay out. + +## Plan + +- `encode::Options` in `rs/moq-video` and `rs/moq-audio` (the producer + options, beside `bandwidth`) gains `echo: Option`. + - The handle is built from an `origin::Consumer` and the echo path, + resolved against the publisher's broadcast. + - It consumes `.echo` announcements under that path, subscribes to the + feedback track on each, and reads its own renditions by alias. + - It folds the reports into one signal: the share of viewers stalled over + the last interval and their late frame rate, weighted equally per viewer. + - The counters are cumulative, so the handle keeps the previous snapshot + per viewer and diffs it. A counter that goes backwards means a restarted + viewer and resets that baseline. + - A viewer counts toward a rendition while its latest snapshot has a row + for that alias, so viewers of other rungs, or ones that switched away, + never dilute the share. The announcement, not the age of its last + report, keeps that snapshot current: an unchanged snapshot sends no frame, so a quiet healthy + viewer must not age out. Diffing already makes one stall long + ago contribute nothing to later intervals. +- Trust (2026-09-29): the token prefix is the boundary. Any viewer the + application's tokens let publish under the echo path counts. How far + viewers may move the target is application-specific (a simulcast ladder + suffers less from one viewer than a single rendition), so the step-down + policy is built in but takes a tunable config struct: a minimum viewer + count or quorum, a bitrate floor, and the stalled-share threshold, with a + way to disable it. Reason: a safe default without hard-coding one + application's policy. +- `moq_mux::rate::Control` takes that signal beside the bandwidth estimate. + A stalled share above the threshold steps the target down like a bandwidth + drop, never below the floor; recovery follows the existing decay ramp, + and the estimate stays the ceiling. Audio does not follow its grant today + (`Options::bandwidth` in `rs/moq-audio/src/encode/producer.rs` reserves + only). It follows this signal only once the grant quest lands; until then + the loop drives video. +- `moq import --echo ` and `moq transcode --echo ` set the + catalog's `echo` section and wire the handle. Each rung of the ladder + reads its own renditions. +- Test: the CLI publishes to a relay, and two `moq play --echo` viewers + report under the echo path, one of them throttled through the impairment + profile. The target bitrate drops within two intervals of the throttled + viewer reporting stalls, and recovers after it stops. A unit test on mocked + time checks that the quorum and floor bound one viewer's influence. +- A benchmark sweeps viewers and renditions per snapshot, runs at least + nightly, and shows one interval's fold growing with the rows it reads, not + a full-table scan per rendition. +- Document the flag in `doc/bin/cli.md` and the loop and its config in the + moq-video README. + +## Required + +- [Schema](/quest/m1/stats/schema.md) - the `echo` section and feedback snapshot +- [Rust reporters](/quest/m1/stats/rust.md) - the viewers that report and + the CLI it wires + +## Related + +- [Ladder](/quest/m1/ladder/README.md) - the transcode ladder that adapts to + its uplink today +- [Audio follows the grant](/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - + the audio rate follow this signal would feed diff --git a/quest/m1/stats/js.md b/quest/m1/stats/js.md new file mode 100644 index 00000000000..01d5c23531b --- /dev/null +++ b/quest/m1/stats/js.md @@ -0,0 +1,38 @@ +# [M] The browser publisher and player report stats and feedback + +## Goal + +`` announces a stats track in its catalog and fills it. +``, given an echo name, publishes an `.echo` broadcast under the +echo path of a catalog soliciting feedback. Both use the `@moq/hang` schemas. + +## Plan + +- `js/publish`: + - The encoder `Stats` signals are already per rendition (`frames`, + `bytes`, `keyframes`). Add drops and the target bitrate. + - Fold them into the stats snapshot keyed by rendition alias, and write it + through the `moq-json` snapshot producer with its `.z` sibling. A `stats` + attribute enables it. + - `transport` carries PROBE rtt only, because `WebTransport.getStats()` + returns nothing useful in Chromium or Firefox today. +- `js/watch`: + - The decoder `Stats` signals grow late frames, stalls and stalled + duration, underruns from the worklet's count, decode errors, and the + newest arrival. + - An `echo` attribute names the viewer, refused unless it is one path + segment, as in Rust. Once a watched catalog carries an + `echo` section, the element resolves the echo path against the broadcast, + appends `.echo`, and publishes there with the fixed feedback track, keyed by rendition alias, the same rule as + Rust, and reconciles it on each catalog update like Rust. + - Watch elements on one connection watching the same catalog under one + name share its producer, because a second `createBroadcast` at a path + closes the first. +- The existing UI stats panels read the same signals. +- The demo sets both attributes, so the media test can read a browser + viewer's feedback through `moq export echo`. +- `doc/lib/js` documents the attributes. + +## Required + +- [Schema](/quest/m1/stats/schema.md) - the zod schemas this fills diff --git a/quest/m1/stats/rust.md b/quest/m1/stats/rust.md new file mode 100644 index 00000000000..6afa565ed05 --- /dev/null +++ b/quest/m1/stats/rust.md @@ -0,0 +1,47 @@ +# [M] The Rust CLI, players, encoders, and remuxes report stats and feedback + +## Goal + +- `moq import --stats` and `moq publish --stats` announce a stats track in + the catalog and fill it with what they send. +- `moq play` and `moq export`, given `--echo `, publish an `.echo` + broadcast under each watched catalog's echo path and fill its feedback + track. +- `moq export stats ` prints a broadcast's stats snapshots, and + `moq export echo ` prints the feedback of every `.echo` broadcast + under a prefix, as JSON lines. + +## Plan + +- Counters come from the source, per track, as cumulative `stats()` + snapshots: no callback, no per-frame lock. + - Publisher: the `moq-video` and `moq-audio` encode producers count frames, + bytes, keyframes, and drops. The `moq-mux` importers count the frames and + bytes they write per track. A remux never encodes, so without them the + CLI would have nothing to report for `moq import`. + - Viewer: the decode and render paths count received, decoded, late, + stalled, underruns, and errors. The `moq-mux` exporters count the frames + and bytes they receive per track, so `moq export --echo` reports a row + for each rendition it remuxes. `underruns` in + `rs/moq-audio/src/playback` is already counted privately. +- `moq-cli` folds the counters into `hang::stats::Snapshot` on the stats + interval and writes it through `moq_json::snapshot`, with the `.z` sibling. + A TS import flattens `ts::Stats` in as `mpegts`. `transport` comes from + the connection's `ConnectionStats`. +- Feedback: after reading a catalog with an `echo` section, the player + resolves the echo path against the broadcast, appends `.echo`, and + publishes there with the fixed feedback + track, keyed by the catalog's rendition aliases. Each catalog update + reconciles it: a removed `echo` section, a changed path, or no longer + watching unannounces the old broadcast. A name that is not a single path segment is refused at + parse time. +- `moq export stats` and `moq export echo` are sinks that skip `.hang` media + discovery, so they route around `catalog_format`. +- `doc/bin/cli.md` documents the flags and sinks. +- The media test publishes with `--stats` and plays with `--echo` against a + publisher that solicits feedback. It asserts that the publisher's frame + count matches what was sent and that the viewer's newest arrival advances. + +## Required + +- [Schema](/quest/m1/stats/schema.md) - the sections and snapshot types diff --git a/quest/m1/stats/schema.md b/quest/m1/stats/schema.md new file mode 100644 index 00000000000..31d56e4481e --- /dev/null +++ b/quest/m1/stats/schema.md @@ -0,0 +1,67 @@ +# [M] hang defines the stats and echo sections and their snapshots + +## Goal + +`hang::Catalog` carries two optional root sections, `stats: { track }` and +`echo: { path }`. hang defines the snapshot types those tracks carry: the +publisher's per-rendition and transport counters, and a viewer's +per-rendition and transport feedback. Rust and JS parse the same fixtures, +and the hang draft specs both. Nothing produces them yet. + +## Plan + +- `rs/hang/src/catalog`: `Stats { track }` and `Echo { path }`, both + `#[non_exhaustive]`, as `Option` fields on `Catalog` that are omitted from + the wire when absent. `path` is relative to the broadcast serving the + catalog and resolves through `try_resolve`, like a rendition's + `broadcast`; `.echo` is appended to the result. A path that escapes + the root refuses the catalog. Shared fixtures pin both in both languages. Additive on main. +- `rs/hang/src/stats.rs`: the publisher snapshot, + `Snapshot { transport, renditions: BTreeMap, #[serde(flatten)] ext: E }`. + The generic lets moq-mux flatten `{ mpegts: ts::Stats }` in beside it, the + way `Catalog` takes `ts::Ext`. `Track` holds sent frames, sent bytes, + keyframes, skipped frames, and the target bitrate as a gauge. +- `rs/hang/src/echo.rs`: + `Snapshot { transport, renditions: BTreeMap }`. `Track` + holds: + - received frames and bytes, decoded, late, and decode errors; + - stalls, stalled duration, and underruns; + - the newest media timestamp received, with the wall time it arrived; + - the playout latency, as a gauge. +- Both snapshots key by the catalog's rendition alias. Feedback covers a + rendition that references another broadcast under its alias in the catalog + that lists it; the publisher snapshot omits referenced renditions (decided + in the [README](/quest/m1/stats/README.md)). +- `Transport` is shared: rtt, estimated rate, bytes and packets lost, and + sample age. Every field is optional, because a browser has only PROBE rtt. +- Every field is defaulted, zero and `None` are omitted, unknown fields are + ignored, and each type is `#[non_exhaustive]`. Durations are milliseconds + and rates bits per second, as in `moq-stats`. +- hang names the `.echo` suffix and the feedback track (a helper such as + `hang::echo::is_echo(path)`), so a reader filters at announce time and a + publisher subscribes by a known name. +- `js/hang`: zod schemas mirroring both sections and all three snapshot + types, field for field. Fixtures are shared through `js/test`. +- `drafts/draft-lcurley-moq-hang.md` specs the two sections, the snapshot + schemas, and the `.echo` convention: one broadcast per soliciting catalog, + under the catalog's echo path, announced after the viewer reads the + catalog. Validate with `just drafts check`. +- Open: the MSF catalog conversion in `rs/moq-mux` copies only the media + sections and `ext`, so `stats` and `echo` drop silently under + `--catalog-format msf`. Candidates: carry them through MSF with a + round-trip test, or refuse `--stats` and `--echo` with MSF. +- Docs: `doc/concept/hang.md`, and a media section in `doc/concept/stats.md`. +- Tests: + - fixtures round-trip in both languages; + - an old catalog without the sections parses unchanged; + - a snapshot with an unknown field parses. + +## Required + +- [Catalog track alias](/quest/m1/catalog-track-alias.md) - the rendition + alias both snapshots key by + +## Related + +- [#4145](https://github.com/moq-dev/moq/pull/4145) - the closed moq-stats + extension design; salvage its field docs and serde helpers diff --git a/quest/m2/latency-ledger.md b/quest/m2/latency-ledger.md index ed059c529ba..ad3cee94e8e 100644 --- a/quest/m2/latency-ledger.md +++ b/quest/m2/latency-ledger.md @@ -14,9 +14,9 @@ trade to get it running. This quest promotes them. - Take the stage schema the harness already defines (capture, encode, publish flush, network, jitter buffer, decode, render) and expose it as fields of - `hang::Stats`, the media extension the client stats schema adds to - `moq-stats` (`rs/hang/src/stats.rs`, and its `@moq/stats` mirror), rather - than a second readout: an observable value a `.stats` broadcast already + the hang stats and feedback snapshots (`rs/hang/src/stats.rs`, + `rs/hang/src/echo.rs`, and their `@moq/hang` mirrors), rather than a + second readout: an observable value a stats or `.echo` track already carries, not a callback. Decided so viewers report latency the same way they report stalls. - Both languages, matching names, per the repo's cross-language rule. Scrutinise @@ -34,7 +34,7 @@ trade to get it running. This quest promotes them. ## Required - [Audio quality harness](/quest/m0/audio-quality-harness/README.md) - defines the stage schema and lands the probes this promotes -- [Schema and library](/quest/m1/qos/stats/schema.md) - adds `hang::Stats`, which this extends +- [Media stats schema](/quest/m1/stats/schema.md) - adds the stats and feedback snapshots this extends ## Related diff --git a/quest/m2/stats-delta.md b/quest/m2/stats-delta.md index 475e7c65322..d1243fd9746 100644 --- a/quest/m2/stats-delta.md +++ b/quest/m2/stats-delta.md @@ -76,10 +76,9 @@ Design points left open for the implementer: - Extensibility: if every field is a varint, a reader can skip mask bits it does not know, so fields append without breaking old readers. Decide that or refuse unknown bits loudly, and say which. -- Gauges: the [client stats](/quest/m1/qos/stats/README.md) extension adds - non-monotonic gauges (a latency, a target bitrate). Encode them absolute or - zigzag, or have a producer with a non-`()` extension refuse this flavor, and - document the contract. +- Gauges: none today. Media stats, with their latency and bitrate gauges, + ride hang tracks rather than a moq-stats extension, so this flavor encodes + relay frames only. - Measure `sessions` (`Presence`) too; the benchmark skipped it. - Sweep the aggregate over node publishers x entries per node, for both flavors; the benchmark above only varied one relay's stream, so it cannot @@ -95,8 +94,7 @@ which is a published API break and goes to `dev` unless additive. `TrafficFrame` / `SessionsFrame`. The JS decoder is about 120 lines and dependency-free apart from inflate (`@moq/flate`); read varints through `BigInt` or split 32-bit halves, since counters exceed 2^53. It belongs with -the JS stats reader, `@moq/stats` if [browser reporters](/quest/m1/qos/stats/js.md) -has landed by then. Share fixtures between Rust and JS so the two stay wire +the demo dashboard's relay-stats reader. Share fixtures between Rust and JS so the two stay wire identical, and keep the benchmark in-tree, wired into CI at least nightly. **Docs and spec.** No IETF draft covers stats today. Write the format into @@ -111,5 +109,4 @@ impact: new on-demand tracks; existing tracks unchanged. ## Related - [Stats format page](/doc/concept/stats.md) - where the new flavor is documented -- [Client stats](/quest/m1/qos/stats/README.md) - the extension and gauges the format must carry or refuse - [Compressed tracks](/quest/m2/flate/README.md) - group-scoped DEFLATE tracks, whose group-window discipline this flavor repeats diff --git a/quest/m2/teleop/README.md b/quest/m2/teleop/README.md index fa7e5f5a4f2..492354d7274 100644 --- a/quest/m2/teleop/README.md +++ b/quest/m2/teleop/README.md @@ -111,8 +111,8 @@ stating plainly because it is what a builder is comparing against. - [e2ee](/quest/m1/e2ee/README.md) - the answer for a protected control link - [Text schema](/quest/m1/text-schema.md) - non-media tracks in a catalog, arrived at from the media side -- [Client stats](/quest/m1/qos/stats/schema.md) - publisher-reported stats - as a `.stats` broadcast (moq#2734); teleop's latency instrumentation - extends that extension rather than adding a second stats surface +- [Media stats](/quest/m1/stats/schema.md) - publisher-reported stats + on a catalog-announced track (moq#2734); teleop's latency instrumentation + extends those types rather than adding a second stats surface - [Video hardware validation](/quest/m3/video-hardware.md) - the VAAPI run that covers Intel ground robots and NUC companions diff --git a/quest/m2/teleop/robot.md b/quest/m2/teleop/robot.md index 3ebd5b00793..f88dd40f8b3 100644 --- a/quest/m2/teleop/robot.md +++ b/quest/m2/teleop/robot.md @@ -75,8 +75,8 @@ The framing is where the guarantee lives, not the subscription flags: opaque-bytes ones for binary frames (`moq-binary`, folding into `moq-flate` per moq-binary's fold into moq-flate ([#4425](https://github.com/moq-dev/moq/pull/4425), on `dev`)). - Per-stage timestamp instrumentation, generalised from moq-boy's `status` - track. Check it against the publisher-reported stats broadcast - ([client stats](/quest/m1/qos/stats/schema.md), moq#2734) before adding a + track. Check it against the publisher-reported stats track + ([media stats](/quest/m1/stats/schema.md), moq#2734) before adding a second stats surface. Capability only: publishing a competitive benchmark is out of scope, because Transitive's breakdown puts camera plus USB at roughly 100 ms of a 130 ms glass-to-glass total, so we would mostly be diff --git a/quest/m2/ts-health-stats.md b/quest/m2/ts-health-stats.md index 34d2939d7ba..9e408b3ace6 100644 --- a/quest/m2/ts-health-stats.md +++ b/quest/m2/ts-health-stats.md @@ -12,12 +12,17 @@ counter rates and PID quiet times. Decided while planning [#1838](https://github.com/moq-dev/moq/issues/1838): -- **Surface through the stats plumbing**, as the issue settled. The shape is - whatever [per-track stats](/quest/m1/qos/stats/per-track.md) decides: a - section on the client `.stats` entry, or an `mpegts.stats` track referenced - from the catalog's `mpegts` section. Either way the name follows the +- **Surface through the stats plumbing**, as the issue settled. The + [media stats schema](/quest/m1/stats/schema.md) settles the shape: an + import flattens `ts::Stats` into the publisher's stats snapshot under the catalog's `mpegts` key, the counters stay owned by moq-mux beside `ts::Ext`, and `hang` stays TS-free. +- Open: an export is a viewer, which has no stats track and reports only + through a soliciting catalog's `.echo` feedback, so where `moq export ts + --stats` publishes its egress rows is unsettled. Candidates: extend the + solicited `.echo` snapshot with a flattened container section, give viewers + their own stats surface, or narrow this quest to import. Leaning toward + narrowing, since the other two widen the settled stats design. - **Counters sum, gauges do not.** Every check is a cumulative counter, which keeps `.z` deltas small and lets an aggregate sum; the PID's `quiet` is a gauge and merges newest-wins. @@ -33,7 +38,7 @@ Decided while planning [#1838](https://github.com/moq-dev/moq/issues/1838): ## Required -- [Per-track stats](/quest/m1/qos/stats/per-track.md) - where and in what shape the counters are published -- [Rust reporters](/quest/m1/qos/stats/rust.md) - `moq import --stats` and `moq export --stats` +- [Media stats schema](/quest/m1/stats/schema.md) - the snapshot the counters flatten into +- [Rust reporters](/quest/m1/stats/rust.md) - `moq import --stats` and the stats interval - [TS import health](/quest/m2/ts-import-health.md) - the ingest counters - [TS export liveness](/quest/m2/ts-export-liveness.md) - the egress rows From 4565110eea5c41c7a6548f137965ae2e1257dc1c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 14:47:03 -0700 Subject: [PATCH 051/128] test(json): shrink the snapshot overflow test with a small group budget (#4440) Co-authored-by: Claude Sonnet 5.5 --- js/json/src/snapshot/encoder.ts | 8 ++++++-- js/json/src/snapshot/snapshot.test.ts | 21 +++++++++++++-------- quest/m1/README.md | 1 - quest/m1/json-rolls-snapshot-test.md | 14 -------------- 4 files changed, 19 insertions(+), 25 deletions(-) delete mode 100644 quest/m1/json-rolls-snapshot-test.md diff --git a/js/json/src/snapshot/encoder.ts b/js/json/src/snapshot/encoder.ts index 82800aa9395..f42ec058142 100644 --- a/js/json/src/snapshot/encoder.ts +++ b/js/json/src/snapshot/encoder.ts @@ -13,6 +13,10 @@ const MAX_DELTA_FRAMES = 256; // entrypoint: the Producer needs it to know whether to hold a group open, nothing else does. export const DEFAULT_DELTA_RATIO = 8; +// Bytes a group may hold before it rolls when {@link Config.maxGroupBytes} is left unset: moq-net's +// per-group cache limit. Not re-exported from the package entrypoint; a test pins it to that limit. +export const DEFAULT_MAX_GROUP_BYTES = Group.MAX_GROUP_CACHE_BYTES; + /** Options shared by an {@link Encoder} and the {@link Producer} that wraps one. */ export interface Config { // Controls how aggressively the encoder emits deltas (merge patches) instead of full snapshots. @@ -45,7 +49,7 @@ export interface Config { /** * Bytes a group may hold before it rolls, defaulting to moq-net's per-group cache limit. Lets a - * test reach the limit without megabytes of JSON. + * test reach the limit without megabytes of JSON. Must fit the snapshot's own frame. * * @internal */ @@ -149,7 +153,7 @@ export class Encoder { constructor(config: Config = {}) { this.#config = config; this.#compress = isDeflate(config.compression); - this.#maxGroupBytes = config.maxGroupBytes ?? Group.MAX_GROUP_CACHE_BYTES; + this.#maxGroupBytes = config.maxGroupBytes ?? DEFAULT_MAX_GROUP_BYTES; } /** diff --git a/js/json/src/snapshot/snapshot.test.ts b/js/json/src/snapshot/snapshot.test.ts index 668ddf7fac6..8b2f3457c6a 100644 --- a/js/json/src/snapshot/snapshot.test.ts +++ b/js/json/src/snapshot/snapshot.test.ts @@ -1,7 +1,7 @@ import { expect, test } from "bun:test"; import { Group, Error as NetError, StreamCode, Time, Track } from "@moq/net"; import { Consumer } from "./consumer.ts"; -import { Encoder } from "./encoder.ts"; +import { DEFAULT_MAX_GROUP_BYTES, Encoder } from "./encoder.ts"; import { Producer } from "./producer.ts"; type Value = Record; @@ -331,19 +331,24 @@ test("a rejected update leaves the previous value readable", async () => { expect(await drain(track.subscribe())).toEqual([{ keep: true }]); }); +test("the default group budget is moq-net's group cache limit", () => { + // The tests below shrink the budget, so pin the default they stand in for. + expect(DEFAULT_MAX_GROUP_BYTES).toBe(Group.MAX_GROUP_CACHE_BYTES); +}); + test("a delta that would overflow the snapshot rolls a new one instead", async () => { // A delta is only readable while its group still holds the snapshot it applies to. A patch - // that pushes the group past the cache would abort it, leaving a late subscriber with no + // that pushes the group past the budget would abort it, leaving a late subscriber with no // value. Mirrors the cumulative check in the Rust encoder. // - // The value is replaced rather than grown, so each snapshot fits the cache on its own while the + // The value is replaced rather than grown, so each snapshot fits the budget on its own while the // snapshot plus the patch that rewrites it does not. - const half = Math.floor(Group.MAX_GROUP_CACHE_BYTES * 0.6); + const size = 40; const track = new Track.Producer("test"); - const producer = new Producer({ track }); + const producer = new Producer({ track, maxGroupBytes: 64 }); - producer.update({ v: "x".repeat(half) }); - producer.update({ v: "y".repeat(half) }); + producer.update({ v: "x".repeat(size) }); + producer.update({ v: "y".repeat(size) }); producer.finish(); // Two groups, a self-contained snapshot each, rather than one whose frame 0 was evicted. @@ -354,7 +359,7 @@ test("a delta that would overflow the snapshot rolls a new one instead", async ( // The newest value is readable with no earlier frame to apply it to. const values = await drain(track.subscribe({ maxAge: REPLAY_LATENCY })); - expect(values[values.length - 1]).toEqual({ v: "y".repeat(half) }); + expect(values[values.length - 1]).toEqual({ v: "y".repeat(size) }); }); test("a compressed delta is gated on its encoded size, not its plaintext", async () => { diff --git a/quest/m1/README.md b/quest/m1/README.md index cbdb4795f29..94f54d74333 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -76,7 +76,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [In-band auth](/quest/m1/auth/README.md) - a session tells its peer what it may publish and subscribe to, unions tokens presented in band, and fails loud on an out-of-scope publish - [Dropped sources](/quest/m1/dropped-sources.md) - track consumers see the producer's real error on every end path, never `Dropped` - [Shaper virtual time](/quest/m1/shaper-virtual-time.md) - `moq-shaper` tests judge seeded decisions on paused time, not on wall-clock delivery under load -- [Shrink the JS overflow test](/quest/m1/json-rolls-snapshot-test.md) - the `js/json` roll-on-overflow test uses a small `maxGroupBytes` budget instead of megabytes of JSON - [C++ through moq-ffi](/quest/m1/cpp/README.md) - generated C++ over moq-ffi with futures and expected-style errors, shipped as a tarball, vcpkg, and Conan, and adopted by the OBS plugin - [Generated C bindings](/quest/m1/c/README.md) - C generated from moq-ffi ships as `moq-c` 0.8.0 and replaces the hand-written libmoq - [OBS native codecs](/quest/m1/obs-moq-video/README.md) - replace FFmpeg video and audio decoding with moq-video and moq-audio, deliver GPU frames, and use native audio/video encoders diff --git a/quest/m1/json-rolls-snapshot-test.md b/quest/m1/json-rolls-snapshot-test.md deleted file mode 100644 index 653d9eba4c2..00000000000 --- a/quest/m1/json-rolls-snapshot-test.md +++ /dev/null @@ -1,14 +0,0 @@ -# [XS] Shrink the JS snapshot overflow test - -## Goal - -The `js/json` test "a delta that would overflow the snapshot rolls a new one -instead" stops building two ~19 MiB values (about 1 s idle, several under -load) and exercises the same roll with a few bytes, through the encoder's -internal `maxGroupBytes` budget. - -## Plan - -- Keep one assertion that the default budget is moq-net's group cache limit, - so the shrunk test doesn't hide a drift between the two. -- Confirm the test fails when the gate is removed. From 7d4ec645baf91df037d463c285a30d0d25ac9999 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 15:04:28 -0700 Subject: [PATCH 052/128] chore(quest): delete watch-decoder-recovery (#4521) Co-authored-by: Claude Opus 5.5 --- quest/m1/README.md | 1 - quest/m1/watch-decoder-recovery.md | 27 --------------------------- 2 files changed, 28 deletions(-) delete mode 100644 quest/m1/watch-decoder-recovery.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 94f54d74333..ac8f90f6cc6 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -40,7 +40,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Request stream cancel](/quest/m1/request-stream-serve.md) - a lite publisher stops resolving a SUBSCRIBE or FETCH once the requester FINs or resets, through one wrapper that owns every request stream's reader - [JS closed-track leak](/quest/m1/js-closed-track-leak.md) - on dev, a subscriber that joins a closed JS track with unlimited retention is released instead of cached forever - [Session death parity](/quest/m1/session-death.md) - a local close ends tracks cleanly in both languages, and JS group readers see the session's error on session death -- [Watch decoder recovery](/quest/m1/watch-decoder-recovery.md) - one malformed packet rebuilds the audio or video decoder instead of ending playback - [Watch and publish under CSP](/quest/m1/csp-assets.md) - blob workers stay the default; strict-CSP apps host the files and set a base URL - [More tests under load](/quest/m1/test-flakes-2.md) - the second round of load-only failures, fixed at the cause - [Interop audio cold start](/quest/m1/interop-audio-cold-start.md) - the interop audio tone check stops failing on cold start, fixed at its cause diff --git a/quest/m1/watch-decoder-recovery.md b/quest/m1/watch-decoder-recovery.md deleted file mode 100644 index a88567066c8..00000000000 --- a/quest/m1/watch-decoder-recovery.md +++ /dev/null @@ -1,27 +0,0 @@ -# [M] Watch decoders recover from an error - -## Goal - -One malformed packet no longer ends audio or video for the rest of a -subscription. Today a WebCodecs error closes the decoder, both audio loops -`break` (added in #2415 to stop an `InvalidStateError` loop), and video calls -`effect.close()`; nothing rebuilds the decoder, and playback silently stops. - -## Plan - -Decided: rebuild inside the loop, for audio and video alike. On a decoder -error, rebuild through one shared `build()` helper, skip to the next keyframe, -and give up after three rebuilds in a row with no output. A rebuilt legacy -audio decoder re-runs its warmup priming. Cover the legacy and CMAF loops. - -Tests: a corrupt packet mid-stream is followed by decoded output from the next -keyframe; a stream of only corrupt packets gives up after three rebuilds -instead of spinning. - -## Closes - -- [#4324](https://github.com/moq-dev/moq/issues/4324) - close this issue when the quest finishes - -## Related - -- [Audio warmup](/quest/m1/audio-warmup.md) - the same audio loops and priming From e925be88d4e5b82e7ad9900cfa103ec3b19ce7bd Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 15:04:31 -0700 Subject: [PATCH 053/128] test(tokio): isolate TLS root reload tests from shared /tmp (#4537) Co-authored-by: Claude Opus 5.5 --- rs/moq-tokio/src/tls.rs | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/rs/moq-tokio/src/tls.rs b/rs/moq-tokio/src/tls.rs index 13d3d9ba09e..e58b917c44b 100644 --- a/rs/moq-tokio/src/tls.rs +++ b/rs/moq-tokio/src/tls.rs @@ -2591,13 +2591,15 @@ mod tests { #[cfg(all(feature = "watch", feature = "noq"))] #[test] fn reloadable_client_roots_disable_server_resumption() { - use std::io::Write; - let (ca_a, server_cert, server_key, client_cert, client_key) = signed_certificates(); let (ca_b, _, _, _, _) = signed_certificates(); - let mut root_file = tempfile::NamedTempFile::new().unwrap(); - root_file.write_all(ca_a.as_bytes()).unwrap(); - let paths = vec![root_file.path().to_path_buf()]; + // A dedicated directory, not `/tmp`: the watcher registers the parent, so + // unrelated churn there fires a reload that can read `ca_a` and store it + // after this test's own `reload()` installed `ca_b`. + let dir = tempfile::TempDir::new().unwrap(); + let root_path = dir.path().join("root.pem"); + std::fs::write(&root_path, ca_a).unwrap(); + let paths = vec![root_path.clone()]; let provider = crypto::provider(); let build_client = |cert, key| { @@ -2657,7 +2659,7 @@ mod tests { rustls::HandshakeKind::Full ); - std::fs::write(root_file.path(), ca_b).unwrap(); + std::fs::write(&root_path, ca_b).unwrap(); reload.reload(); assert!(handshake_kinds(reloadable_client, reloadable).is_err()); } @@ -2665,13 +2667,13 @@ mod tests { #[cfg(all(feature = "watch", feature = "noq"))] #[test] fn custom_roots_reload_for_new_client_and_server_handshakes() { - use std::io::Write; - let (ca_a, server_a, _, client_a, _) = signed_certificates(); let (ca_b, server_b, _, client_b, _) = signed_certificates(); - let mut root_file = tempfile::NamedTempFile::new().unwrap(); - root_file.write_all(ca_a.as_bytes()).unwrap(); - let paths = vec![root_file.path().to_path_buf()]; + // A dedicated directory, not `/tmp`: see `reloadable_client_roots_disable_server_resumption`. + let dir = tempfile::TempDir::new().unwrap(); + let root_path = dir.path().join("root.pem"); + std::fs::write(&root_path, ca_a).unwrap(); + let paths = vec![root_path.clone()]; let provider = crypto::provider(); let custom = CustomRoots::new(paths.clone()).unwrap(); @@ -2707,7 +2709,7 @@ mod tests { assert!(client_verifier.verify_client_cert(&client_a, &[], now).is_ok()); assert!(client_verifier.verify_client_cert(&client_b, &[], now).is_err()); - std::fs::write(root_file.path(), ca_b).unwrap(); + std::fs::write(&root_path, ca_b).unwrap(); server_verifier.inner.state.reload(); client_verifier.inner.state.reload(); @@ -2719,7 +2721,7 @@ mod tests { assert!(client_verifier.verify_client_cert(&client_a, &[], now).is_err()); // A malformed replacement must not erase the last valid verifier. - std::fs::write(root_file.path(), "not a PEM certificate").unwrap(); + std::fs::write(&root_path, "not a PEM certificate").unwrap(); server_verifier.inner.state.reload(); client_verifier.inner.state.reload(); assert!( From 66a60f4644d5a4072d8543b63b3dd29dea12bd4f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 15:04:49 -0700 Subject: [PATCH 054/128] fix(net): negotiate hidden namespace discovery for IETF peers (#4482) Co-authored-by: GPT-6 --- doc/concept/moq-lite.md | 8 +- drafts/draft-lcurley-moq-hidden.md | 18 +++-- js/net/src/ietf/connection.ts | 1 + js/net/src/ietf/hidden.ts | 2 +- js/net/src/ietf/publisher.test.ts | 67 ++++++++++++++++ js/net/src/ietf/publisher.ts | 13 +++- js/net/src/ietf/subscriber.test.ts | 26 +++++++ js/net/src/integration.test.ts | 6 +- quest/m1/README.md | 1 - quest/m1/ietf-hidden-default.md | 53 ------------- rs/moq-net/src/ietf/hidden.rs | 3 +- rs/moq-net/src/ietf/publisher.rs | 120 ++++++++++++++++++++++++----- rs/moq-net/src/model/origin.rs | 29 ++++++- 13 files changed, 256 insertions(+), 91 deletions(-) delete mode 100644 quest/m1/ietf-hidden-default.md diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index c2947245ed4..91e7ef342bd 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -111,8 +111,12 @@ const announced = connection.announced(Path.Pattern.all(), { hidden: true }); On the wire, moq-lite 07 (`moq-lite-07-wip`, opt-in only) carries the opt-in on each announce request, and moq-transport carries it as a `SUBSCRIBE_NAMESPACE` parameter once the peer's -`SETUP` says it understands one ([hidden](/draft/moq-hidden)). An older peer -never opts in, so it never discovers hidden routes. Rust sessions always opt in +`SETUP` says it understands one ([hidden](/draft/moq-hidden)). An older MoQ Lite peer +never opts in, so it never discovers hidden routes. +IETF peers that omit the MoQ Hidden setup option receive all authorized +namespaces, including dot-prefixed namespaces. Peers that declare it opt in +per subscription; a prefix naming the dot segment itself also lists its +children. Rust sessions always opt in on the wire and filter per local reader, so a relay mirrors everything and each consumer decides. diff --git a/drafts/draft-lcurley-moq-hidden.md b/drafts/draft-lcurley-moq-hidden.md index ee1c14720ee..4f9089ccf43 100644 --- a/drafts/draft-lcurley-moq-hidden.md +++ b/drafts/draft-lcurley-moq-hidden.md @@ -24,7 +24,7 @@ informative: --- abstract This document defines an extension for MoQ Transport {{moqt}} that hides namespaces from discovery. -A namespace with a field starting with `.` below the prefix a subscriber asked for is left out of the advertisements it receives, unless its SUBSCRIBE_NAMESPACE opts in. +For peers that negotiate this extension, a namespace with a field starting with `.` below the prefix a subscriber asked for is left out of the advertisements it receives, unless its SUBSCRIBE_NAMESPACE opts in. A platform can then add internal namespaces, such as statistics, without them turning up in applications that list everything and use what they find. --- note_Note_to_Readers @@ -52,7 +52,7 @@ This extension reserves a leading `.` for such namespaces, as file systems do fo A hidden namespace is still published, routed, and subscribed to like any other; it is only left out of discovery by default. A subscriber that wants hidden namespaces too says so on the SUBSCRIBE_NAMESPACE that would list them. -The name alone decides: there is no publisher-side flag, so a namespace cannot be hidden from one subscriber and listed to another under the same prefix. +For peers that declare this extension, the namespace name and the requested prefix determine whether an opt-in is needed. # Setup Negotiation @@ -70,7 +70,7 @@ A receiver MUST ignore the value. An endpoint MUST NOT send the HIDDEN parameter to a peer that did not declare this option, because an unknown parameter fails decoding. A subscriber that wants hidden namespaces therefore waits for the peer's SETUP before sending SUBSCRIBE_NAMESPACE. -The rest of this extension applies whether or not the peer declared the option: a peer that never heard of it never opts in, so it is never told about hidden namespaces. +The filtering rules below apply only to peers that declared this option. A publisher MUST NOT hide namespaces from discovery solely because of a leading `.` when the peer did not declare it. Such peers receive all authorized namespaces, as in unextended MoQ Transport. # Opting In {#parameter} @@ -90,11 +90,12 @@ A receiver MUST close the session with a PROTOCOL_VIOLATION on any other value. # Advertising {#advertising} -A publisher SHOULD NOT advertise a hidden namespace in response to a SUBSCRIBE_NAMESPACE that did not opt in. +For a peer that declared the HIDDEN Setup Option, a publisher SHOULD NOT advertise a hidden namespace in response to a SUBSCRIBE_NAMESPACE that did not opt in. Hiding is a convenience for discovery, not access control, so a publisher MAY treat a subscriber it trusts, such as another relay in its own cluster, as opted in. -An unsolicited PUBLISH_NAMESPACE answers no prefix, so it is measured against the empty one: a publisher SHOULD NOT send one for a hidden namespace. +An unsolicited PUBLISH_NAMESPACE answers no prefix, so it is measured against the empty one: a publisher SHOULD NOT send one for a hidden namespace to a peer that declared the HIDDEN Setup Option. When unsolicited advertisements are live, a SUBSCRIBE_NAMESPACE is answered with only the namespaces they left out, which is to say those hidden from the empty prefix, that the subscription may see. +A peer that did not declare the option already receives all namespaces unsolicited, so its subscription adds no duplicate advertisements. That covers both an opt-in and a prefix that names a hidden field itself, and no namespace is advertised twice. Hiding narrows discovery and nothing else. @@ -133,6 +134,13 @@ Both values are even, so each is a bare varint. --- back +# Changelog + +## Since draft-lcurley-moq-hidden-00 (in progress) + +- Apply hidden filtering only to peers that declared the HIDDEN Setup Option. +- Measure visibility from the requested namespace prefix, independently of authorization scope. + # Acknowledgments {:numbered="false"} diff --git a/js/net/src/ietf/connection.ts b/js/net/src/ietf/connection.ts index bcbcf01abc2..c2a11987c7e 100644 --- a/js/net/src/ietf/connection.ts +++ b/js/net/src/ietf/connection.ts @@ -137,6 +137,7 @@ export class Connection implements Established { session: this.#session, publish, requiresSolicitation: solicit ?? false, + hidden, cluster, }); this.#solicit = solicit; diff --git a/js/net/src/ietf/hidden.ts b/js/net/src/ietf/hidden.ts index cd22aff02ff..ea732799303 100644 --- a/js/net/src/ietf/hidden.ts +++ b/js/net/src/ietf/hidden.ts @@ -6,7 +6,7 @@ import { SetupOption, type SetupOptions } from "./parameters.ts"; * A namespace with a field starting with `.` below the prefix a subscription asked for is * left out of discovery unless the SUBSCRIBE_NAMESPACE opts in with the HIDDEN parameter. * An unknown parameter fails decoding, so the parameter is only sent to a peer whose SETUP - * carried the HIDDEN option. + * carried the HIDDEN option. Peers that did not declare the option receive every namespace. * * @module * @internal diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index 55dea4e9a58..e4e76de3ce7 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -1808,3 +1808,70 @@ test("draft-20: PUBLISH_DONE waits for a queued group and counts every stream", client.close(); } }); + +for (const version of [Version.DRAFT_15, Version.DRAFT_19] as const) { + for (const declared of [false, true]) { + for (const solicited of [false, true]) { + for (const optIn of [false, true]) { + test(`hidden negotiation: ${version}, declared=${declared}, solicited=${solicited}, optIn=${optIn}`, async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const origin = new OriginProducer(); + // Authorization heads must not replace the request's empty visibility prefix. + const scope = new Path.Patterns([ + Path.Pattern.subtree(Path.from(".stats")), + Path.Pattern.subtree(Path.from("visible")), + ]); + const pub = new Publisher({ + quic: pair.server, + session: new NativeSession(pair.server, version, true), + publish: origin.scope(Path.empty(), scope).consume(), + requiresSolicitation: solicited, + hidden: declared, + }); + publish(origin, Path.from(".stats/node")); + publish(origin, Path.from("visible")); + let subscription: Stream | undefined; + let run: Promise; + if (solicited) { + subscription = await Stream.open(pair.client, { version: version }); + const accepted = await Stream.accept(pair.server, version); + if (!accepted) throw new Error("missing subscription"); + run = pub.runSubscribeNamespace( + new SubscribeNamespace({ requestId: 0n, namespace: Path.empty(), hidden: optIn }), + accepted, + ); + expect(await subscription.reader.u53()).toBe(RequestOk.id); + await RequestOk.decode(subscription.reader, version); + } else { + run = pub.runPublishNamespaces(); + } + const expected = !declared || (solicited && optIn) ? [".stats/node", "visible"] : ["visible"]; + const advertisements: Stream[] = []; + for (const path of expected) { + if (subscription && version !== Version.DRAFT_15) { + expect(await subscription.reader.u53()).toBe(SubscribeNamespaceEntry.id); + expect((await SubscribeNamespaceEntry.decode(subscription.reader, version)).suffix).toBe( + Path.from(path), + ); + } else { + const stream = await Stream.accept(pair.client, version); + if (!stream) throw new Error("missing advertisement"); + advertisements.push(stream); + expect(await stream.reader.u53()).toBe(PublishNamespace.id); + const msg = await PublishNamespace.decode(stream.reader, version); + expect(msg.trackNamespace).toBe(Path.from(path)); + await stream.writer.u53(RequestOk.id); + await new RequestOk({ + requestId: version === Version.DRAFT_15 ? msg.requestId : undefined, + }).encode(stream.writer, version); + } + } + subscription?.close(); + origin.close(); + await run; + for (const stream of advertisements) stream.close(); + }); + } + } + } +} diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index a4f1988ead5..9666621b20a 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -165,6 +165,7 @@ export class Publisher { #quic: WebTransport; #session: Session; #requiresSolicitation: boolean; + #hidden: boolean; // The origin this session serves, borrowed: it outlives the session, and closing the // session leaves its broadcasts alone. The namespaces are advertised with an unsolicited @@ -188,6 +189,7 @@ export class Publisher { session, publish, requiresSolicitation, + hidden = false, cluster, }: { /** The WebTransport session, for uni streams. */ @@ -198,6 +200,8 @@ export class Publisher { publish?: OriginConsumer; /** Whether the peer's SETUP asked to be told on request (MoQ Solicit). */ requiresSolicitation: boolean; + /** Whether the peer declared MoQ Hidden. */ + hidden?: boolean; /** The Hop IDs the SETUP exchange settled (MoQ Cluster). */ cluster?: Cluster.Hops; }) { @@ -207,6 +211,7 @@ export class Publisher { this.#advertised = origin?.advertised ?? new Signal(new Map()); this.#publish = publish; this.#requiresSolicitation = requiresSolicitation; + this.#hidden = hidden; this.#advert = Cluster.advertise(cluster); } @@ -749,8 +754,8 @@ export class Publisher { // peer asked to be told only on request, it has already heard everything visible // from the empty prefix unasked, so this stream carries only what that hid. const carries = (covered: Path.Valid) => - (msg.hidden || !hiddenBelow(prefix, covered)) && - (this.#requiresSolicitation || hiddenBelow(Path.empty(), covered)); + (!this.#hidden || msg.hidden || !hiddenBelow(prefix, covered)) && + (this.#requiresSolicitation || (this.#hidden && hiddenBelow(Path.empty(), covered))); // Reports whether the peer now holds the namespace: an inline entry always // lands, but a PUBLISH_NAMESPACE request can be declined. @@ -926,8 +931,8 @@ export class Publisher { const updated = new Map(); for (const [covered, candidates] of advertised) { - // Unasked, a hidden namespace stays off the wire (MoQ Hidden). - if (hiddenBelow(Path.empty(), covered) || candidates.length === 0) continue; + // Only peers that declared MoQ Hidden filter unsolicited discovery. + if ((this.#hidden && hiddenBelow(Path.empty(), covered)) || candidates.length === 0) continue; updated.set(covered, candidates[0]); } diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index d558e148fc9..001d1aca3a7 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -1060,6 +1060,32 @@ test("returning demand survives a blocked unsubscribe", async () => { session.close(); }); +test("local readers filter hidden unsolicited namespaces from a legacy peer", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const subscriber = new Subscriber({ session: new NativeSession(pair.server, VERSION, true) }); + const plain = subscriber.announced(); + const opted = subscriber.announced(undefined, { hidden: true }); + const handlers: Promise[] = []; + const streams: Stream[] = []; + for (const path of [".stats/node", "visible"]) { + const stream = await Stream.open(pair.server, { version: VERSION }); + streams.push(stream); + handlers.push( + subscriber.runPublishNamespace( + new PublishNamespace({ requestId: 0n, trackNamespace: Path.from(path) }), + stream, + ), + ); + } + expect((await plain.next())?.prefix).toBe(Path.from("visible")); + expect((await opted.next())?.prefix).toBe(Path.from(".stats/node")); + expect((await opted.next())?.prefix).toBe(Path.from("visible")); + for (const stream of streams) stream.close(); + plain.close(); + opted.close(); + await Promise.all(handlers); +}); + test("object extension limit accepts 64 KiB and stops one byte over before reading", async () => { for (const size of [65536, 65537]) { for (const first of [true, false]) { diff --git a/js/net/src/integration.test.ts b/js/net/src/integration.test.ts index c59f511f1ef..83326ed30ba 100644 --- a/js/net/src/integration.test.ts +++ b/js/net/src/integration.test.ts @@ -421,18 +421,20 @@ async function announcedUntil(announced: { next(): Promise<{ prefix: Path.Valid // A `.`-named broadcast is left out of discovery unless the request opts in or names the // dot segment. lite-06 cannot carry the opt-in, so its peer never lists the hidden path. -for (const [protocol, carriesOptIn] of [ +for (const [protocol, carriesOptIn, version] of [ [Lite.ALPN_07_WIP, true], [Lite.ALPN_06, false], [Ietf.ALPN.DRAFT_19, true], [Ietf.ALPN.DRAFT_16, true], + ["", true, Ietf.Version.DRAFT_14], + [Ietf.ALPN.DRAFT_15, true], ] as const) { test(`integration: ${protocol} hides dot paths from discovery`, async () => { const pair = createMockTransportPair(protocol); const origin = new OriginProducer(); const [client, server] = await Promise.all([ connect(url, { transport: pair.client }), - accept(pair.server, url, { publish: origin.consume() }), + accept(pair.server, url, { publish: origin.consume(), version }), ]); // Published first, so a reader that may see it lists it before `visible`. diff --git a/quest/m1/README.md b/quest/m1/README.md index ac8f90f6cc6..03a1dec8beb 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -29,7 +29,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Close codes](/quest/m1/close-codes.md) - a client sees the peer's application close code over WebSocket and raw QUIC, like WebTransport - [Raw stream codes](/quest/m1/raw-stream-codes.md) - raw QUIC stream resets and stops carry the application's code, not an HTTP/3-mapped one - [WebTransport close upstream](/quest/m1/wt-close-upstream.md) - web-transport-moq delivers the close capsule itself, and moq-tokio's `CLOSE_LINGER` is deleted -- [IETF hidden default](/quest/m1/ietf-hidden-default.md) - a moq-transport peer without the MoQ Hidden option is advertised hidden namespaces; one with it filters per subscription - [Watch refusal](/quest/m1/watch-refusal.md) - `` shows an origin refusal as an error instead of sitting offline - [Splice edge cases](/quest/m1/splice-edges.md) - an unstamped successor, a pruned segment's boundary group, and a warm head during a takeover are each handled correctly - [Resumed groups](/quest/m1/resume-latest.md) - a half-delivered group ends once the new copy is past it, so a group-only reader never parks after a mid-group failover diff --git a/quest/m1/ietf-hidden-default.md b/quest/m1/ietf-hidden-default.md deleted file mode 100644 index 0004b8c584c..00000000000 --- a/quest/m1/ietf-hidden-default.md +++ /dev/null @@ -1,53 +0,0 @@ -# [S] IETF peers without MoQ Hidden see hidden namespaces - -## Goal - -A moq-transport peer that did not declare the MoQ Hidden setup option is -advertised every namespace, hidden ones included. A peer that declared it -keeps today's behavior: hidden namespaces are left out unless its -SUBSCRIBE_NAMESPACE opts in. Rust and JS publishers agree, and -`drafts/draft-lcurley-moq-hidden.md` says so. - -Today the rule applies whether or not the peer declared the option, so a -third-party IETF client can never see a hidden namespace except by naming its -dot segment in the prefix. - -## Plan - -Maintainer decisions: - -- Hiding exists to keep existing moq-lite customers (lite-06 and older) from - seeing new `.pro/` broadcasts. None of them use an IETF client, and the - extension will not be adopted by the IETF draft, so an IETF peer that - never heard of it gets everything. A peer that declares it chooses per - subscription whether to filter on the wire. -- Our own IETF clients already declare the option and filter locally when a - reader does not ask for hidden, so their behavior does not change. -- moq-lite is unchanged: lite-06 and older never see hidden paths, and lite-07 - opts in. - -Guidance: - -- Both publishers, both the SUBSCRIBE_NAMESPACE path and the unsolicited - PUBLISH_NAMESPACE path, and draft-14/15 (PUBLISH_NAMESPACE requests) as well - as 16+ (inline NAMESPACE entries). -- Rewrite the draft's "applies whether or not the peer declared the option" - rule and keep `just drafts check` green. `doc/concept/moq-lite.md` also - says a peer without the extension never discovers hidden routes, as do the - module docs in `rs/moq-net/src/ietf/hidden.rs` and `js/net/src/ietf/hidden.ts`; - update them in the same change. -- It is a wire behavior change in both languages, so run - `just test interop --all` before landing. -- Tests: an undeclared peer sees hidden namespaces, a declared peer without - the parameter does not, on at least one pre-16 and one 16+ draft. Also fill - the gaps where nothing is tested today: draft-14/15 with hidden, JS IETF - without solicitation, and local filtering when a peer sends hidden paths the - reader did not ask for. -- Hiddenness is measured from the requested prefix, as the draft already - defines it and JS already does. Rust measures from the publish origin's - scope heads instead, so a publish scope like `.stats/**` exposes - `.stats/node` to a request for the empty prefix; bring Rust in line and test - that case in both languages. - -Public API: none. Wire: behavior change for IETF peers that did not declare -MoQ Hidden. diff --git a/rs/moq-net/src/ietf/hidden.rs b/rs/moq-net/src/ietf/hidden.rs index 6fedea39166..388334a516d 100644 --- a/rs/moq-net/src/ietf/hidden.rs +++ b/rs/moq-net/src/ietf/hidden.rs @@ -4,7 +4,8 @@ //! for is hidden: it is left out of discovery unless the subscription opts in. The //! opt-in is the HIDDEN parameter on SUBSCRIBE_NAMESPACE, and since an unknown //! parameter fails decoding, it is only sent to a peer whose SETUP carried the HIDDEN -//! option. The rule itself is the one moq-lite applies (see +//! option. Peers that did not declare the option receive every namespace. +//! The rule itself is the one moq-lite applies (see //! [`crate::origin::Consumer::with_hidden`]). use super::Version; diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 2243679f4ef..bb0d36d49ab 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -1731,7 +1731,9 @@ where // Split horizon, as the solicited loop applies it: never advertise a route back // to the peer it came from. - let origin = self.excluding(&peer); + let origin = self + .excluding(&peer) + .discovery(!self.peer_setup.get().await.hidden || self.origin.includes_hidden()); let ns = Namespaces::new(peer, Target::Requests(None)); self.run_namespaces(origin, crate::Path::empty().to_owned(), ns).await @@ -1809,12 +1811,10 @@ where _ => Target::Inline(stream), }; - // Hidden namespaces are left out unless the peer opted in (MoQ Hidden). A publish + // Peers that declared MoQ Hidden filter namespaces unless they opted in. A publish // origin that already opted in (the caller's choice for this peer) keeps them. - let origin = match msg.hidden { - true => origin.with_hidden(true), - false => origin, - }; + let declared = self.peer_setup.get().await.hidden; + let origin = origin.discovery(!declared || msg.hidden || self.origin.includes_hidden()); // Unless the peer asked to be told only on request, it has already heard what an // unsolicited PUBLISH_NAMESPACE can say. Repeating it here would leave it holding @@ -1823,8 +1823,8 @@ where // until the peer is done with it. let origin = match self.requires_solicitation().await { true => origin, - false if self.origin.includes_hidden() => origin.empty(), - false => origin.beyond(&self.origin), + false if !declared || self.origin.includes_hidden() => origin.empty(), + false => origin.beyond(&self.origin.clone().discovery(false)), }; let ns = Namespaces::new(peer, target); @@ -4142,19 +4142,47 @@ mod tests { /// were opened. One stream means the entry rode the subscription inline; two means /// it went out as its own PUBLISH_NAMESPACE request. async fn advertise_both_ways(solicit: Option) -> (usize, usize) { - let log = advertise_with_hidden(solicit, "", false).await; + let log = advertise_with_hidden(Discovery { + solicit, + ..Discovery::default() + }) + .await; (occurrences(&log, b"cam"), log.bi_opens()) } /// [`advertise_both_ways`] with a hidden `.stats/node` beside `cam`, and the peer's /// SUBSCRIBE_NAMESPACE for `prefix` opting in to hidden namespaces or not. - async fn advertise_with_hidden( + struct Discovery<'a> { + version: Version, + declared: bool, solicit: Option, - prefix: &str, + prefix: &'a str, hidden: bool, - ) -> crate::lite::test_transport::Log { - const VERSION: Version = Version::Draft17; + scoped: bool, + } + + impl Default for Discovery<'_> { + fn default() -> Self { + Self { + version: Version::Draft17, + declared: true, + solicit: Some(true), + prefix: "", + hidden: false, + scoped: false, + } + } + } + async fn advertise_with_hidden(case: Discovery<'_>) -> crate::lite::test_transport::Log { + let Discovery { + version, + declared: hidden_declared, + solicit, + prefix, + hidden, + scoped, + } = case; let origin = crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(); let _cam = origin.announce("cam", crate::origin::Route::default()).unwrap(); let _stats = origin.announce(".stats/node", crate::origin::Route::default()).unwrap(); @@ -4164,21 +4192,34 @@ mod tests { // PUBLISH_NAMESPACE request. let session = crate::lite::test_transport::ScriptedSession::per_stream(vec![ Vec::new(), - publish_namespace_ok(VERSION).await, + publish_namespace_ok(version).await, ]); let log = session.log.clone(); + let setup = peer::PeerSetup::default(); + setup.set(peer::Peer { + solicit, + hidden: hidden_declared, + ..Default::default() + }); + let consume = match scoped { + true => origin + .consume() + .scope("", &crate::Pattern::subtree(".stats").unwrap().into()) + .unwrap(), + false => origin.consume(), + }; let publisher = Publisher::new( crate::time::Clock::tokio(), session.clone(), - origin.consume(), + consume, Control::new(None, false), None, - declared(solicit), - VERSION, + setup, + version, ); - let stream = Stream::open(&mut session.clone(), VERSION).await.unwrap(); + let stream = Stream::open(&mut session.clone(), version).await.unwrap(); let msg = ietf::SubscribeNamespace { request_id: RequestId(1), namespace: crate::Path::new(prefix), @@ -4216,7 +4257,13 @@ mod tests { (Some(true), "", true, 1, 1), (Some(true), ".stats", false, 0, 1), ] { - let log = advertise_with_hidden(solicit, prefix, hidden).await; + let log = advertise_with_hidden(Discovery { + solicit, + prefix, + hidden, + ..Discovery::default() + }) + .await; let case = format!("solicit {solicit:?}, prefix {prefix:?}, hidden {hidden}"); assert_eq!(occurrences(&log, b"cam"), cam, "{case}"); // An inline entry names its suffix, so count the leaf. @@ -4224,6 +4271,41 @@ mod tests { } } + #[tokio::test(start_paused = true)] + async fn hidden_discovery_obeys_peer_setup_and_requested_prefix() { + for version in [ + Version::Draft14, + Version::Draft15, + Version::Draft16, + Version::Draft19, + Version::Draft22, + ] { + for declared in [false, true] { + for solicit in [Some(false), Some(true)] { + for scoped in [false, true] { + for (prefix, hidden) in [("", false), ("", true), (".stats", false)] { + let log = advertise_with_hidden(Discovery { + version, + declared, + solicit, + prefix, + hidden, + scoped, + }) + .await; + let expected = usize::from(!declared || hidden || prefix == ".stats"); + assert_eq!( + occurrences(&log, b"node"), + expected, + "{version:?}: declared={declared}, solicit={solicit:?}, scoped={scoped}, prefix={prefix}, hidden={hidden}" + ); + } + } + } + } + } + } + /// The regression that made announces solicited in the first place: a namespace sent /// as both PUBLISH_NAMESPACE and NAMESPACE leaves the peer holding two sources for /// one broadcast, and whichever arrives second replaces the one the first attached. diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 8fa6facb730..14d07b814f3 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -1139,6 +1139,8 @@ pub(crate) fn interest_prefixes(allowed: &Patterns) -> Vec { pub(crate) struct Hidden { /// Report hidden routes too. include: bool, + /// Measure visibility from the request prefix instead of authorization heads. + from: Option, /// Report only what a feed scoped to these heads hides, for a stream that tops /// up a feed already carrying everything visible from them. beyond: Option>, @@ -1147,7 +1149,8 @@ pub(crate) struct Hidden { impl Hidden { /// Whether a cursor hanging at `heads` reports a route at `prefix`. fn discovers(&self, heads: &[PathOwned], prefix: &Path) -> bool { - (self.include || !hides(heads, prefix)) && self.beyond.as_ref().is_none_or(|outer| hides(outer, prefix)) + (self.include || !hides(self.from.as_ref().map(std::slice::from_ref).unwrap_or(heads), prefix)) + && self.beyond.as_ref().is_none_or(|outer| hides(outer, prefix)) } /// This rule for a cursor reading through `mount`, whose heads sit on the @@ -1159,6 +1162,7 @@ impl Hidden { }); Self { include: self.include, + from: self.from.as_ref().and_then(|head| mount.translate_head(head)), beyond, } } @@ -3774,7 +3778,21 @@ impl Consumer { /// A clone whose [`announced`](Self::announced) reports only the routes a feed /// from `outer` hides, for a stream topping up that feed. pub(crate) fn beyond(mut self, outer: &Consumer) -> Self { - self.hidden.beyond = Some(interest_prefixes(&outer.scope.allowed)); + self.hidden.beyond = Some( + outer + .hidden + .from + .clone() + .map(|head| vec![head]) + .unwrap_or_else(|| interest_prefixes(&outer.scope.allowed)), + ); + self + } + + /// Set wire discovery visibility relative to this consumer's requested root. + pub(crate) fn discovery(mut self, hidden: bool) -> Self { + self.hidden.include = hidden; + self.hidden.from = Some(self.root.clone()); self } @@ -3871,7 +3889,12 @@ impl Consumer { let allowed = mount.translate(&self.scope.allowed); // Hidden at the mount point means hidden throughout: the dot segment is above // everything the mount holds. A top-up feed's rule moves onto the target. - if allowed.is_empty() || !(self.hidden.include || !hides(&heads, &mount.at)) { + if allowed.is_empty() + || !(self.hidden.include + || !hides( + self.hidden.from.as_ref().map(std::slice::from_ref).unwrap_or(&heads), + &mount.at, + )) { continue; } cursors.push(cursor( From 56a5da44058ed892e88ffb857180becf4cb7f7fa Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 15:05:49 -0700 Subject: [PATCH 055/128] quest(m1/js-fetch-cancel): claim From 1e0a46f08a8141ce356cd5521448b8a628c43a3f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 15:05:50 -0700 Subject: [PATCH 056/128] quest(m1/js-ietf-reprice): claim Co-Authored-By: Claude Opus 5.5 From 4a0c45072fe832b126798f35186492f25f276ee5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 15:09:45 -0700 Subject: [PATCH 057/128] fix(moq-net): a group awaiting its FIN ack still expires and follows priority (#4534) Co-authored-by: Claude Opus 5.5 --- quest/m1/README.md | 1 - quest/m1/cross-relay-bursts.md | 10 +- quest/m1/fin-wait-expiry.md | 31 ------ rs/moq-net/src/ietf/publisher.rs | 61 ++++++++++- rs/moq-net/src/lite/publisher.rs | 146 ++++++++++++++++++++++---- rs/moq-net/src/lite/test_transport.rs | 63 +++++------ rs/moq-tokio/src/transport.rs | 46 +++++++- 7 files changed, 252 insertions(+), 106 deletions(-) delete mode 100644 quest/m1/fin-wait-expiry.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 03a1dec8beb..4b9ac7a8f1e 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -34,7 +34,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Resumed groups](/quest/m1/resume-latest.md) - a half-delivered group ends once the new copy is past it, so a group-only reader never parks after a mid-group failover - [Track tail hardening](/quest/m1/track-tail-hardening.md) - Rust and JS wait out a track's tail by the same rules, with the known hang, count, truncation, grace, and memory holes closed - [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 -- [FIN wait expiry](/quest/m1/fin-wait-expiry.md) - a group awaiting its FIN ack still expires and follows priority updates on lite and IETF - [Cross-relay bursts](/quest/m1/cross-relay-bursts.md) - bursty small-group tracks cross two relays without lost groups, unanswered FETCHes, or stalls - [Request stream cancel](/quest/m1/request-stream-serve.md) - a lite publisher stops resolving a SUBSCRIBE or FETCH once the requester FINs or resets, through one wrapper that owns every request stream's reader - [JS closed-track leak](/quest/m1/js-closed-track-leak.md) - on dev, a subscriber that joins a closed JS track with unlimited retention is released instead of cached forever diff --git a/quest/m1/cross-relay-bursts.md b/quest/m1/cross-relay-bursts.md index 25607b1be82..a9415011e8d 100644 --- a/quest/m1/cross-relay-bursts.md +++ b/quest/m1/cross-relay-bursts.md @@ -14,17 +14,13 @@ node, or one self-hosted relay, loses nothing. Reproduce first, on a local two-relay cluster with the reporter's harness (offered in the issue) and the relay build cdn.moq.pro ran. Then fix what the repro shows. Suspects: `Old` expiry or newest-first dropping on the relay hop, -and FETCH not forwarded or answered upstream. Re-measure the stalls after -[FIN wait expiry](/quest/m1/fin-wait-expiry.md), a candidate cause. Keep the -repro as a regression test in the cluster tests. +and FETCH not forwarded or answered upstream. A group awaiting its FIN ack +now expires and follows priority updates, which removed one candidate cause. +Keep the repro as a regression test in the cluster tests. The issue's stale and flapping announcements after a clean close are cluster-routing evidence, not this quest's scope. -## Required - -- [FIN wait expiry](/quest/m1/fin-wait-expiry.md) - removes one candidate cause of the stalls before measuring - ## Closes - [#4349](https://github.com/moq-dev/moq/issues/4349) - close this issue when the quest finishes diff --git a/quest/m1/fin-wait-expiry.md b/quest/m1/fin-wait-expiry.md deleted file mode 100644 index eb163fa6fe6..00000000000 --- a/quest/m1/fin-wait-expiry.md +++ /dev/null @@ -1,31 +0,0 @@ -# [S] A group awaiting its FIN ack still expires - -## Goal - -A group whose FIN is written but not yet acknowledged still expires with -`Old` and still follows priority updates, on lite and IETF. Today the -`Closed` arm only awaits `writer.poll_close`, so a stale group keeps its -queued bytes and its old send order, which can stall newer groups behind it. - -## Plan - -The issue ships four failing tests, a `with_fin_gate` test hook, and a fix: - -- lite: poll priority above the state match, not only in `Serve`. -- lite and IETF: in `Closed`, poll `poll_expired_while_pending` and abort with - `Old`. -- moq-tokio: `set_priority` in `Closing` fires the existing interrupt so the - new order applies, instead of only storing it. - -Each priority update rebuilds the `closed()` watch; check the publisher -benchmarks for a regression. The flaky -`subscription_end_integrity::a_subscription_cut_by_the_publisher_disconnecting_does_not_end_clean` -the reporter hit is tracked in [More tests under load](/quest/m1/test-flakes-2.md). - -## Closes - -- [#4332](https://github.com/moq-dev/moq/issues/4332) - close this issue when the quest finishes - -## Related - -- [Starvation](/quest/m1/qos/starvation.md) - its frontier relies on FIN acks, which can now end in `Old` diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index bb0d36d49ab..775283b2cba 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -2143,7 +2143,7 @@ enum GroupState { batch_pos: usize, }, /// Every frame is written and the FIN sent: wait for the acknowledgement so a - /// late cancel can still reset the stream. + /// late cancel or expiry can still reset the stream. Closed { writer: Writer, }, @@ -2351,7 +2351,17 @@ impl GroupServe { // Wait until everything is acknowledged by the peer so we can still // cancel the stream. poll_close releases the stream on completion so // the Drop fallback cannot reset the acknowledged stream. - let res = ready!(writer.poll_close(&mut cx)); + let res = match writer.poll_close(&mut cx) { + Poll::Ready(res) => res, + // Those bytes still hold the connection until acknowledged, so a + // group gone stale meanwhile releases them like one still serving: + // dropping the writer resets the stream. + Poll::Pending if self.group.poll_expired_while_pending(waiter, true) => { + self.state = GroupState::Done; + return Poll::Ready(Err(Error::Old)); + } + Poll::Pending => return Poll::Pending, + }; let sequence = self.msg.group_id; self.state = GroupState::Done; return Poll::Ready(res.map(|()| { @@ -2569,6 +2579,53 @@ mod group_priority_test { assert!(matches!(serving.await, Err(Error::Old))); } + /// A FIN holds the subgroup's bytes until the peer acknowledges it, so a subgroup + /// that goes stale while waiting still expires instead of pinning them. + #[tokio::test] + async fn unacknowledged_fin_expires_with_the_group() { + tokio::time::pause(); + + let session = SinkSession::new(Default::default()).with_unacked_fin(); + let log = session.log.clone(); + let track = track::Producer::new(std::sync::Arc::new(crate::broadcast::Info::default()), "test", None); + let mut subscriber = track.subscribe(None); + let mut old = track.append_group().unwrap(); + old.write_frame(crate::Timestamp::ZERO, b"old".as_slice()).unwrap(); + old.finish().unwrap(); + let group = subscriber.recv_group().await.unwrap().expect("old group"); + + let mut serve = GroupServe::new( + session, + ietf::GroupHeader { + track_alias: 0, + group_id: 0, + sub_group_id: 0, + publisher_priority: 0, + flags: Default::default(), + }, + 0, + group, + Some(Timescale::default()), + Version::Draft19, + GroupSlice::default(), + ); + let mut serving = std::pin::pin!(kio::wait(|waiter| serve.poll_serve(waiter))); + assert!( + futures::poll!(serving.as_mut()).is_pending(), + "the FIN is unacknowledged" + ); + assert!(log.resets().is_empty()); + + tokio::time::advance(Duration::from_secs(1)).await; + let mut edge = track.append_group().unwrap(); + edge.write_frame(crate::Timestamp::from_millis(1000).unwrap(), b"edge".as_slice()) + .unwrap(); + edge.finish().unwrap(); + + assert!(matches!(futures::poll!(serving.as_mut()), Poll::Ready(Err(Error::Old)))); + assert_eq!(log.resets(), vec![crate::StreamError::Cancel.to_code()]); + } + /// The final payload remains guarded after its frame has advanced the group cursor. #[tokio::test] async fn blocked_final_transport_chunk_expires_with_the_group() { diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 88fca60ca6f..4ca5adafbd2 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -2566,7 +2566,7 @@ enum GroupState { batch_pos: usize, }, /// Every frame is written and the FIN sent: wait for the acknowledgement so a - /// late cancel can still reset the stream. + /// late cancel or expiry can still reset the stream. Closed { writer: Writer, }, @@ -2607,6 +2607,29 @@ impl GroupServe { /// every failure as Cancel. fn poll_serve(&mut self, waiter: &kio::Waiter) -> Poll> { loop { + // Queue and SUBSCRIBE_UPDATE priority changes apply on every pass, whatever + // the stream is blocked on, including a FIN awaiting its acknowledgement + // (the transport still schedules its retransmissions). The rank is re-read + // as a send order when handled, since the two conventions are inverted. + if let GroupState::Serve { writer, .. } | GroupState::Closed { writer } = &mut self.state { + while let Poll::Ready(rank) = self.priority.poll_next(waiter) { + writer.set_priority(PriorityHandle::send_order_of(rank)); + } + let seen = self.ctx.track_priority_seen; + // A dropped producer just disables this arm, like the queue arm above. + if let Poll::Ready(Ok(value)) = self.ctx.track_priority.poll(waiter, |value| { + if **value != seen { + Poll::Ready(**value) + } else { + Poll::Pending + } + }) { + self.ctx.track_priority_seen = value; + let rank = self.priority.set_track(value); + writer.set_priority(PriorityHandle::send_order_of(rank)); + } + } + match &mut self.state { GroupState::Open => { if self.group.poll_expired(waiter) { @@ -2654,26 +2677,6 @@ impl GroupServe { } => { let mut cx = Context::from_waker(waiter.waker()); - // Queue and SUBSCRIBE_UPDATE priority changes apply on every pass, - // whatever the write pipeline is blocked on. The rank is re-read as - // a send order when handled, since the two conventions are inverted. - while let Poll::Ready(rank) = self.priority.poll_next(waiter) { - writer.set_priority(PriorityHandle::send_order_of(rank)); - } - let seen = self.ctx.track_priority_seen; - // A dropped producer just disables this arm, like the queue arm above. - if let Poll::Ready(Ok(value)) = self.ctx.track_priority.poll(waiter, |value| { - if **value != seen { - Poll::Ready(**value) - } else { - Poll::Pending - } - }) { - self.ctx.track_priority_seen = value; - let rank = self.priority.set_track(value); - writer.set_priority(PriorityHandle::send_order_of(rank)); - } - let outcome = 'serve: { // The peer closing first cancels the group. if writer.poll_closed(&mut cx).is_ready() { @@ -2797,7 +2800,20 @@ impl GroupServe { // poll_close releases the stream on completion: the peer acknowledged // everything, so the Drop fallback must not reset the stream and // discard bytes still retransmitting. - let res = ready!(writer.poll_close(&mut cx)); + let res = match writer.poll_close(&mut cx) { + Poll::Ready(res) => res, + // Those bytes still hold the connection until acknowledged, so a + // group gone stale meanwhile releases them like one still serving. + Poll::Pending if self.group.poll_expired_while_pending(waiter, true) => { + let GroupState::Closed { writer } = std::mem::replace(&mut self.state, GroupState::Done) + else { + unreachable!() + }; + writer.abort(&Error::Old); + return Poll::Ready(Err(Error::Old)); + } + Poll::Pending => return Poll::Pending, + }; self.state = GroupState::Done; return Poll::Ready(res.map(|()| { tracing::debug!(sequence = self.sequence, "finished group"); @@ -3196,6 +3212,92 @@ mod serve_group_test { ); } + /// A FIN holds the group's bytes until the peer acknowledges it, so a group that + /// goes stale while waiting still expires instead of pinning them. + #[tokio::test] + async fn unacknowledged_fin_expires_with_the_group() { + tokio::time::pause(); + + let session = SinkSession::new(Log::default()).with_unacked_fin(); + let log = session.log.clone(); + let track_priority = kio::Producer::new(0u8); + let subscription = Subscription { + session, + id: 0, + track_name: "test".into(), + priority: PriorityQueue::default(), + track_priority: track_priority.consume(), + track_priority_seen: 0, + version: Version::Lite06, + timescale: Some(crate::Timescale::default()), + opens: Default::default(), + }; + + let track = track::Producer::new(Arc::new(broadcast::Info::default()), "test", None); + let mut subscriber = track.subscribe(None); + let mut old = track.append_group().unwrap(); + old.write_frame(Timestamp::ZERO, b"old".as_slice()).unwrap(); + old.finish().unwrap(); + let group = subscriber.recv_group().await.unwrap().expect("old group"); + + let handle = subscription.priority.insert(Priority::new(0, 0, 0)); + let mut serve = std::pin::pin!(subscription.serve_group(0, 0, handle, group)); + assert!(futures::poll!(serve.as_mut()).is_pending(), "the FIN is unacknowledged"); + assert!(log.resets().is_empty()); + + tokio::time::advance(Duration::from_secs(1)).await; + let mut edge = track.append_group().unwrap(); + edge.write_frame(Timestamp::from_millis(1000).unwrap(), b"edge".as_slice()) + .unwrap(); + edge.finish().unwrap(); + + assert!(matches!(futures::poll!(serve.as_mut()), Poll::Ready(Err(Error::Old)))); + assert_eq!(log.resets(), vec![crate::StreamError::Old.to_code()]); + } + + /// The transport keeps scheduling a finished stream's retransmissions until the + /// FIN is acknowledged, so queue and SUBSCRIBE_UPDATE reorders still reach it. + #[tokio::test] + async fn unacknowledged_fin_follows_priority_changes() { + let session = SinkSession::new(Log::default()).with_unacked_fin(); + let log = session.log.clone(); + let track_priority = kio::Producer::new(0u8); + let subscription = Subscription { + session, + id: 0, + track_name: "test".into(), + priority: PriorityQueue::default(), + track_priority: track_priority.consume(), + track_priority_seen: 0, + version: Version::Lite06, + timescale: Some(crate::Timescale::default()), + opens: Default::default(), + }; + + let track = track::Producer::new(Arc::new(broadcast::Info::default()), "test", None); + let mut group = track.create_group(group::Info { sequence: 0 }).unwrap(); + group.write_frame(Timestamp::ZERO, b"hello".as_slice()).unwrap(); + let consumer = group.consume(); + group.finish().unwrap(); + + let handle = subscription.priority.insert(Priority::new(0, 0, 0)); + let queue = subscription.priority.clone(); + let mut serve = std::pin::pin!(subscription.serve_group(0, 0, handle, consumer)); + assert!(futures::poll!(serve.as_mut()).is_pending(), "the FIN is unacknowledged"); + assert_eq!(log.priorities().last(), Some(&255)); + + // A newer group of the same subscription goes first. + let _newer = queue.insert(Priority::new(0, 0, 1)); + assert!(futures::poll!(serve.as_mut()).is_pending()); + assert_eq!(log.priorities().last(), Some(&254)); + + // A SUBSCRIBE_UPDATE raising this track reranks it above the newer group. + *track_priority.write().ok().expect("the group watches the priority") = 1; + assert!(futures::poll!(serve.as_mut()).is_pending()); + assert_eq!(log.priorities().last(), Some(&255)); + assert!(log.resets().is_empty()); + } + /// A lite-07 subscription's run loop, from group 0, and the log of its subscribe stream. fn lite07_run( session: SinkSession, diff --git a/rs/moq-net/src/lite/test_transport.rs b/rs/moq-net/src/lite/test_transport.rs index a49d263aef9..ff69af76af1 100644 --- a/rs/moq-net/src/lite/test_transport.rs +++ b/rs/moq-net/src/lite/test_transport.rs @@ -93,6 +93,8 @@ pub struct SinkSend { /// [`poll_closed`](poll::SendStream::poll_closed) waits on, mirroring a peer that /// acknowledges the FIN; an unfinished one parks like a peer that never answers. finished: bool, + /// A finished stream still parks, like a peer that has not acknowledged the FIN. + unacked_fin: bool, } impl SinkSend { @@ -102,6 +104,7 @@ impl SinkSend { gate: None, park: kio::Park::default(), finished: false, + unacked_fin: false, } } @@ -112,6 +115,7 @@ impl SinkSend { gate: Some(gate), park: kio::Park::default(), finished: false, + unacked_fin: false, } } } @@ -149,7 +153,7 @@ impl poll::SendStream for SinkSend { } fn poll_closed(&mut self, _cx: &mut Context<'_>) -> Poll> { - match self.finished { + match self.finished && !self.unacked_fin { true => Poll::Ready(Ok(())), // Nothing to acknowledge yet, so park like a peer that never answers. false => Poll::Pending, @@ -331,6 +335,8 @@ pub struct SinkSession { /// Set by [`Self::gated_open_uni`] to withhold unidirectional stream credit. uni_open_gate: Option>, uni_open_park: kio::Park, + /// Set by [`Self::with_unacked_fin`]. + unacked_fin: bool, /// The ALPN to report, for a test that needs a specific negotiated version rather /// than the SETUP-negotiated fallback an absent one selects. protocol: Option<&'static str>, @@ -344,16 +350,17 @@ impl SinkSession { pub fn new(log: Log) -> Self { Self { log, - bi_gate: None, - accept_gate: None, - uni_gate: None, - uni_open_gate: None, - uni_open_park: kio::Park::default(), - protocol: None, - stats: Arc::new(Mutex::new(SinkStats::default())), + ..Default::default() } } + /// Never acknowledge a unidirectional stream's FIN, like a congested peer, so a + /// finished group stays waiting on it. + pub fn with_unacked_fin(mut self) -> Self { + self.unacked_fin = true; + self + } + /// Report these connection statistics, as a real transport would. pub fn with_stats(self, stats: SinkStats) -> Self { self.set_stats(stats); @@ -378,14 +385,8 @@ impl SinkSession { /// into the test. pub fn gated_bi(gate: kio::Consumer) -> Self { Self { - log: Log::default(), bi_gate: Some(gate), - accept_gate: None, - uni_gate: None, - uni_open_gate: None, - uni_open_park: kio::Park::default(), - protocol: None, - stats: Arc::new(Mutex::new(SinkStats::default())), + ..Default::default() } } @@ -396,42 +397,24 @@ impl SinkSession { /// a reply reaches the wire needs a session that hands out accepted streams. pub fn accepted_bi(gate: kio::Consumer) -> Self { Self { - log: Log::default(), - bi_gate: None, accept_gate: Some(gate), - uni_gate: None, - uni_open_gate: None, - uni_open_park: kio::Park::default(), - protocol: None, - stats: Arc::new(Mutex::new(SinkStats::default())), + ..Default::default() } } /// Open unidirectional streams immediately, holding their writes until `gate` opens. pub fn gated_uni(gate: kio::Consumer) -> Self { Self { - log: Log::default(), - bi_gate: None, - accept_gate: None, uni_gate: Some(gate), - uni_open_gate: None, - uni_open_park: kio::Park::default(), - protocol: None, - stats: Arc::new(Mutex::new(SinkStats::default())), + ..Default::default() } } /// Hold unidirectional stream opens until `gate` grants stream credit. pub fn gated_open_uni(gate: kio::Consumer) -> Self { Self { - log: Log::default(), - bi_gate: None, - accept_gate: None, - uni_gate: None, uni_open_gate: Some(gate), - uni_open_park: kio::Park::default(), - protocol: None, - stats: Arc::new(Mutex::new(SinkStats::default())), + ..Default::default() } } } @@ -455,6 +438,7 @@ impl poll::Session for SinkSession { gate: Some(gate), park: kio::Park::default(), finished: false, + unacked_fin: false, }; Poll::Ready(Ok((send, PendingRecv))) } @@ -470,6 +454,7 @@ impl poll::Session for SinkSession { gate: Some(gate), park: kio::Park::default(), finished: false, + unacked_fin: false, }; Poll::Ready(Ok((send, PendingRecv))) } @@ -482,10 +467,12 @@ impl poll::Session for SinkSession { Poll::Ready(Err(_)) | Poll::Pending => return Poll::Pending, } } - Poll::Ready(Ok(match &self.uni_gate { + let mut send = match &self.uni_gate { Some(gate) => SinkSend::gated(self.log.clone(), gate.clone()), None => SinkSend::new(self.log.clone()), - })) + }; + send.unacked_fin = self.unacked_fin; + Poll::Ready(Ok(send)) } fn poll_send_datagram(&mut self, _cx: &mut Context<'_>, _payload: &[u8]) -> Poll> { diff --git a/rs/moq-tokio/src/transport.rs b/rs/moq-tokio/src/transport.rs index 6567bcaf7a9..3912a2402b0 100644 --- a/rs/moq-tokio/src/transport.rs +++ b/rs/moq-tokio/src/transport.rs @@ -243,7 +243,9 @@ pub struct SendStream { completed: Bytes, /// Cancels the in-flight write so a reset applies immediately instead of /// waiting behind blocked I/O (whose partial progress a reset discards - /// anyway). Fired by [`reset`](wt_poll::SendStream::reset) and by [`Drop`]. + /// anyway). Fired by [`reset`](wt_poll::SendStream::reset) and by [`Drop`], + /// and by [`set_priority`](wt_poll::SendStream::set_priority) during the + /// closed() watch, which holds the stream but is safe to restart. interrupt: Option>, } @@ -259,7 +261,7 @@ enum SendState { chunk: Bytes, }, /// The closed() acknowledgement watch; a `None` result means it was - /// interrupted by a late reset (see [`SendStream::interrupt`]). + /// interrupted by a late reset or priority change (see [`SendStream::interrupt`]). Closing(#[allow(clippy::type_complexity)] OpBox<(S, Option>)>), } @@ -390,6 +392,14 @@ impl wt_poll::SendStream for SendS fn set_priority(&mut self, order: u8) { match self.state.get_mut().unwrap().as_mut() { Some(SendState::Idle(stream)) => stream.set_priority(order), + // A finished stream still retransmits under its priority until the FIN is + // acknowledged, so reclaim it from the watch rather than wait that out. + Some(SendState::Closing(_)) => { + self.priority = Some(order); + if let Some(tx) = self.interrupt.take() { + let _ = tx.send(()); + } + } _ => self.priority = Some(order), } } @@ -488,9 +498,9 @@ impl wt_poll::SendStream for SendS self.interrupt = None; self.settle(&mut stream); *self.state.get_mut().unwrap() = Some(SendState::Idle(stream)); - // An interrupted watch was abandoned for a late reset, - // which settle just applied; the next iteration watches - // the now-reset stream, which resolves promptly. + // An interrupted watch was abandoned for a late reset or + // priority change, which settle just applied; the next + // iteration watches again. if let Some(res) = res { return Poll::Ready(res); } @@ -1012,6 +1022,32 @@ mod tests { let _ = closed; } + // A finished stream still retransmits under its priority, so a reorder must + // reach it during the ack watch, and the watch must still resolve afterwards. + #[test] + fn a_priority_change_reaches_the_ack_watch() { + let fake = FakeSend::default(); + fake.never_ack.store(true, Ordering::SeqCst); + let mut send = SendStream::new(fake.clone()); + let mut cx = cx(); + + assert_eq!(send.poll_write(&mut cx, b"queued"), Poll::Ready(Ok(6))); + send.finish().unwrap(); + assert!(send.poll_closed(&mut cx).is_pending()); + + send.set_priority(7); + assert!(send.poll_closed(&mut cx).is_pending()); + assert_eq!(fake.priorities.lock().unwrap().as_slice(), &[7]); + + // The ack arrives for the restarted watch. + fake.never_ack.store(false, Ordering::SeqCst); + send.set_priority(8); + assert_eq!(send.poll_closed(&mut cx), Poll::Ready(Ok(()))); + assert_eq!(fake.priorities.lock().unwrap().as_slice(), &[7, 8]); + assert!(fake.resets.lock().unwrap().is_empty()); + assert_eq!(fake.writes.lock().unwrap().as_slice(), b"queued"); + } + // The poll contract allows retrying a pending write with a SHORTER buffer; // transmitted-but-unreported bytes reconcile against the buffer presented, // never reporting more than its length and never re-transmitting. From 02f41726dd2f1e5f36d9470ceb45ad20f4f4061e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 15:19:12 -0700 Subject: [PATCH 058/128] feat(net): cancel a pending fetchGroup with an AbortSignal FetchGroupOptions gains `signal`. An abort rejects that caller with the signal's reason and closes only its share; the coalesced FETCH stream is cancelled once the last sharer leaves, including during setup. An already-aborted signal rejects before anything is sent. Co-Authored-By: Claude Opus 5.5 --- doc/lib/js/net.md | 2 +- js/net/src/broadcast.test.ts | 16 ++++++ js/net/src/broadcast.ts | 4 +- js/net/src/lite/subscriber.test.ts | 84 +++++++++++++++++++++++++++++- js/net/src/lite/subscriber.ts | 50 +++++++++++++----- js/net/src/track.ts | 8 +++ js/net/src/util/abort.ts | 18 +++++++ quest/m1/README.md | 1 - quest/m1/js-fetch-cancel.md | 25 --------- 9 files changed, 165 insertions(+), 43 deletions(-) create mode 100644 js/net/src/util/abort.ts delete mode 100644 quest/m1/js-fetch-cancel.md diff --git a/doc/lib/js/net.md b/doc/lib/js/net.md index b0d4fda217e..9a7b4dd01e1 100644 --- a/doc/lib/js/net.md +++ b/doc/lib/js/net.md @@ -53,7 +53,7 @@ for (;;) { - **Discovery** by any pattern scope (`origin.announced(scope)`, such as `room/*/chat`; default everything). Each event's `prefix` is the covered prefix relative to the origin, `captures` reports what the scope's wildcards matched when the prefix pins them, and `kind` says whether it was announced, updated, or retracted. The consumer is an async iterable. `origin.broadcasts(scope)` is a live `Getter>` of the same covered prefixes for UIs that need the current set. A borrowed `Connection.origin` also exposes `dynamic(prefix, route)` for serving paths on demand. - **Subscriptions** carry a priority, a `Time.Milli` max age, and optional `groups` bounds. Groups arrive out of order and are read frame by frame, with `Error.TooFarBehind` when a reader asks for a frame the group never held and `Error.GroupTooLarge` when a write exceeds the cache budget and aborts the group. - **Track ends**: `close()` ends a track at its live edge, while `finishAt(n)` declares the exclusive end ahead of it and still accepts the groups below. A subscriber reads the end with `final()` or awaits `finished()`. A remote track ends only once every group below its end has arrived or was dropped; one reset before its header arrived is skipped after the subscription's max age on moq-lite (one second without one), or after one second on IETF. -- **Datagrams** on moq-lite 05+ and fetch-by-sequence for history. `track.fetchGroup(sequence)` on moq-lite resolves when the publisher sends the first response byte or finishes an empty group. A missing group rejects the fetch with `StreamCode.NotFound`, including every concurrent caller sharing that fetch. +- **Datagrams** on moq-lite 05+ and fetch-by-sequence for history. `track.fetchGroup(sequence)` on moq-lite resolves when the publisher sends the first response byte or finishes an empty group. A missing group rejects the fetch with `StreamCode.NotFound`, including every concurrent caller sharing that fetch. `fetchGroup(sequence, { signal })` abandons a pending fetch with the signal's reason; the shared stream is cancelled only once every caller has left. Once resolved, close the group instead. - **Errors** live under one namespace: a stream reset throws `Error.Stream` with a `StreamCode`, while a session close gives `Error.Session` with a `SessionCode`. The registries are disjoint, so the same number means different things in each, and 64+ is yours. Named conditions such as `Error.TooFarBehind`, `Error.FrameTooLarge`, and `Error.GroupTooLarge` subclass `Error.Stream`, so one `code` check handles a condition raised here or reported by the peer. IETF streams use their own mapping: cancellation sends CANCELLED, other local failures send INTERNAL\_ERROR, and received codes remain opaque. - **Paths** with `Path.relative` for the cross-broadcast catalog references hang uses. A `Broadcast.Consumer` names its broadcast by `path`: the path it was requested at relative to the origin handle's root, or empty for a standalone broadcast. Those references resolve against it. Path patterns (`Path.Pattern`, `Path.Patterns`) are re-exported from [`@moq/pattern`](https://www.npmjs.com/package/@moq/pattern). Literal `Path` stays a coordinate. diff --git a/js/net/src/broadcast.test.ts b/js/net/src/broadcast.test.ts index f1640b4af3a..9c77d51b06c 100644 --- a/js/net/src/broadcast.test.ts +++ b/js/net/src/broadcast.test.ts @@ -487,3 +487,19 @@ test("a fetch waits for a group still to come", async () => { broadcast.close(); }); + +test("aborting a fetch rejects with the signal's reason", async () => { + const broadcast = new BroadcastProducer(); + broadcast.createTrack("video"); + + const early = new Error("early"); + await expect(wireOf(broadcast).fetchGroup("video", 0, { signal: AbortSignal.abort(early) })).rejects.toBe(early); + + const controller = new AbortController(); + const pending = wireOf(broadcast).fetchGroup("video", 0, { signal: controller.signal }); + const late = new Error("late"); + controller.abort(late); + await expect(pending).rejects.toBe(late); + + broadcast.close(); +}); diff --git a/js/net/src/broadcast.ts b/js/net/src/broadcast.ts index cf1a0995106..fa94ed42dd8 100644 --- a/js/net/src/broadcast.ts +++ b/js/net/src/broadcast.ts @@ -10,6 +10,7 @@ import { Route } from "./hop.ts"; import { hooks, type TrackSequence } from "./internal.ts"; import * as Path from "./path.ts"; import * as track from "./track.ts"; +import { untilAborted } from "./util/abort.ts"; import { registerWire, trackOf, type Broadcast as Wire } from "./wire.ts"; /** The origin callback a created broadcast uses to advertise its exact path. @internal */ @@ -129,11 +130,12 @@ async function fetchGroup( sequence: number, options: track.FetchGroupOptions = {}, ): Promise { + options.signal?.throwIfAborted(); const subscriber = subscribe(state, name, { priority: options.priority }); hooks.exemptFetch(subscriber); try { for (;;) { - const group = await subscriber.recvGroup(); + const group = await untilAborted(subscriber.recvGroup(), options.signal); if (!group) throw new NotFound(`group ${sequence}`); if (group.sequence === sequence) { // Close the subscription when the returned group finishes, not now: an diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index f9dec8b9016..48a931839eb 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -1,7 +1,7 @@ import { expect, spyOn, test } from "bun:test"; import { Signal } from "@moq/signals"; import type { Probe as ProbeStats } from "../connection/stats.ts"; -import { error, reason, StreamCode, StreamError } from "../error.ts"; +import { error, fromTransport, reason, StreamCode, StreamError } from "../error.ts"; import { HopSchema, isAnonymous, MAX_HOPS, Route, UNKNOWN_HOP } from "../hop.ts"; import * as Path from "../path.ts"; import { Writer } from "../stream.ts"; @@ -803,3 +803,85 @@ test("a fetch started after the subscriber closes rejects without opening a stre expectCut(err, undefined); expect(streams.length).toBe(0); }); + +test("an already-aborted fetch rejects without opening a stream", async () => { + const { quic, streams } = fakeSession(); + const subscriber = new Subscriber(quic, Version.DRAFT_05, HopSchema.parse(1n)); + const cause = new Error("gone"); + + const err = await subscriber + .fetchGroup(Path.from("room"), "video", 0, { signal: AbortSignal.abort(cause) }) + .catch((err: unknown) => err); + expect(err).toBe(cause); + expect(streams.length).toBe(0); +}); + +// Coalesced fetches share one FETCH stream. An abort releases only that caller's share; the +// stream is cancelled once the last sharer leaves, before its FETCH is sent if it can be. +test("one of two fetch sharers aborting leaves the other's fetch", async () => { + const { quic, streams } = fakeSession(); + const subscriber = new Subscriber(quic, Version.DRAFT_05, HopSchema.parse(1n)); + + const controller = new AbortController(); + const a = subscriber.fetchGroup(Path.from("room"), "video", 0, { signal: controller.signal }); + const b = subscriber.fetchGroup(Path.from("room"), "video", 0); + + await drainUntil(() => streams.length === 1); + await answerTrackInfo(streams[0]); + await drainUntil(() => streams.length === 2); + await streams[1].reading; + + const cause = new Error("gone"); + controller.abort(cause); + expect(await a.catch((err: unknown) => err)).toBe(cause); + + let aborted = false; + void streams[1].aborted.then(() => { + aborted = true; + }); + // An empty-group FIN accepts the fetch. + streams[1].inbound.close(); + const group = await b; + expect(await group.readFrame()).toBeUndefined(); + expect(aborted).toBe(false); + + subscriber.close(); +}); + +test.each([ + ["the TRACK_INFO", "track"], + ["the FETCH", "fetch"], +] as const)("the last fetch sharer aborting during %s cancels it", async (_, stage) => { + const { quic, streams } = fakeSession(); + const subscriber = new Subscriber(quic, Version.DRAFT_05, HopSchema.parse(1n)); + + const first = new AbortController(); + const second = new AbortController(); + const a = subscriber.fetchGroup(Path.from("room"), "video", 0, { signal: first.signal }); + const b = subscriber.fetchGroup(Path.from("room"), "video", 0, { signal: second.signal }); + + await drainUntil(() => streams.length === 1); + await streams[0].reading; + if (stage === "fetch") { + await answerTrackInfo(streams[0]); + await drainUntil(() => streams.length === 2); + await streams[1].reading; + } + + first.abort(new Error("first")); + second.abort(new Error("second")); + expect(((await a.catch((err: unknown) => err)) as Error).message).toBe("first"); + expect(((await b.catch((err: unknown) => err)) as Error).message).toBe("second"); + + if (stage === "track") { + // The TRACK_INFO still completes, but no FETCH is sent for the abandoned group. + await answerTrackInfo(streams[0]); + for (let i = 0; i < 100; i++) await Promise.resolve(); + expect(streams.length).toBe(1); + } else { + const err = fromTransport(await streams[1].aborted) as StreamError; + expect(err.code).toBe(StreamCode.Cancel); + } + + subscriber.close(); +}); diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 61c3e7aaf25..b7d9a8b7b0e 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -12,6 +12,7 @@ import { type OpenOptions, type Reader, Stream } from "../stream.ts"; import { TAIL_GRACE_MS, Tail } from "../tail.ts"; import * as Time from "../time.ts"; import type * as track from "../track.ts"; +import { untilAborted } from "../util/abort.ts"; import { TimeoutError, withTimeout } from "../util/timeout.ts"; import { overrideBroadcastWire, wireOf } from "../wire.ts"; import { @@ -731,24 +732,32 @@ export class Subscriber { sequence: number, options: track.FetchGroupOptions = {}, ): Promise { + options.signal?.throwIfAborted(); + // Coalesce onto a still-open fetch of the same group so we don't open a second FETCH // stream (and re-download it); each caller reads an independent mirror. + // + // Reserve each caller's mirror before the fetch starts or is awaited: the fetch watches + // demand from the start, and a fast FIN cannot discard frames before these callers + // receive their handles. An abort closes only this caller's mirror, so the stream is + // cancelled once the last one leaves. const key = JSON.stringify([broadcast, track, sequence]); let entry = this.#fetches.get(key); - if (!entry || entry.group.isClosed) { + let consumer: netGroup.Consumer; + if (entry && !entry.group.isClosed) { + consumer = entry.group.mirror(); + } else { const group = new netGroup.Producer(sequence); - entry = { group, accepted: this.#runFetch(broadcast, track, sequence, options, group) }; + consumer = group.mirror(); + entry = { group, accepted: this.#runFetch(broadcast, track, sequence, options.priority ?? 0, group) }; this.#fetches.set(key, entry); void group.closed.then(() => { if (this.#fetches.get(key)?.group === group) this.#fetches.delete(key); }); } - // Reserve each caller's mirror before awaiting acceptance so the pump sees demand, - // and a fast FIN cannot discard frames before these callers receive their handles. - const consumer = entry.group.mirror(); try { - await entry.accepted; + await untilAborted(entry.accepted, options.signal); return consumer; } catch (err) { consumer.close(); @@ -757,12 +766,13 @@ export class Subscriber { } // Open the FETCH stream and pump the response into the shared group. Setup errors close the - // group, evict the entry, and reject every caller waiting for acceptance. + // group, evict the entry, and reject every caller waiting for acceptance. A setup every caller + // has abandoned is cancelled the same way. async #runFetch( broadcast: Path.Valid, track: string, sequence: number, - options: track.FetchGroupOptions, + priority: number, group: netGroup.Producer, ): Promise { try { @@ -773,10 +783,10 @@ export class Subscriber { // Lite has no FETCH_OK, so a publisher that never answers would hold the setup forever. // Subscriber.close() closing the group releases every caller at any stage, and resets // the streams the setup opened. - const setup = this.#fetchSetup(broadcast, track, sequence, options); + const setup = this.#fetchSetup(broadcast, track, sequence, priority, group); let accepted: { stream: Stream; info: TrackInfo }; try { - accepted = await untilClosed(group, setup); + accepted = await untilAbandoned(group, setup); } catch (err: unknown) { // A setup that finishes just after the close hands back a stream nobody will read. void setup.then( @@ -794,20 +804,21 @@ export class Subscriber { } // Resolve the track's timescale, then open the FETCH stream and wait for it to be accepted. + // Closing the group during that wait resets the stream. async #fetchSetup( broadcast: Path.Valid, track: string, sequence: number, - options: track.FetchGroupOptions, + priority: number, + group: netGroup.Producer, ): Promise<{ stream: Stream; info: TrackInfo }> { - const info = await this.#trackInfo(broadcast, track); - const priority = options.priority ?? 0; + const info = await untilClosed(group, this.#trackInfo(broadcast, track)); return this.#exchange({ sendOrder: sendOrder({ priority }) }, async (stream) => { await stream.writer.u53(StreamId.Fetch); await new FetchMessage({ broadcast, track, priority, group: sequence }).encode(stream.writer, this.version); // A byte or an empty-group FIN accepts the fetch; a reset rejects it. // done() buffers that byte so the response pump can decode it normally. - await stream.reader.done(); + await untilClosed(group, stream.reader.done()); return { stream, info }; }); } @@ -1195,6 +1206,17 @@ async function untilClosed(group: netGroup.Producer, step: Promise): Promi return value as T; } +// Like untilClosed, but also cancels once every reader has left. Demand is level-triggered, so a +// caller that coalesces onto the group before the check re-arms it. +async function untilAbandoned(group: netGroup.Producer, step: Promise): Promise { + const idle: unique symbol = Symbol("idle"); + for (;;) { + const value = await untilClosed(group, race([step, group.unused().then((): typeof idle => idle)])); + if (value !== idle) return value as T; + if (!group.used.peek()) throw new StreamError(StreamCode.Cancel, { message: "cancel" }); + } +} + /** * A broadcast consumed from a lite session. It resolves `track.Consumer.query()` and * `.fetchGroup()` over the wire (lite-05+ TRACK / FETCH streams) by reaching into the diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 09af757c9e1..52dc4034e01 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -243,6 +243,14 @@ export class Request { export interface FetchGroupOptions { /** Delivery priority for the fetch stream. Defaults to `0`. */ priority?: number; + + /** + * Abandons this fetch, rejecting with the signal's reason. Concurrent fetches of the same + * group share one stream, cancelled only once every caller has left. An already-aborted + * signal rejects before anything is sent, and aborting after the group resolves has no + * effect; close the group instead. + */ + signal?: AbortSignal; } /** diff --git a/js/net/src/util/abort.ts b/js/net/src/util/abort.ts new file mode 100644 index 00000000000..ed1f32ba8b2 --- /dev/null +++ b/js/net/src/util/abort.ts @@ -0,0 +1,18 @@ +import { race } from "@moq/signals"; + +// Settle with `promise`, or reject with the signal's reason once it aborts. An already-aborted +// signal rejects at once. There's no cancellation of `promise` itself; the caller releases +// whatever it holds when this rejects. +export async function untilAborted(promise: Promise, signal?: AbortSignal): Promise { + if (!signal) return promise; + signal.throwIfAborted(); + + const { promise: aborted, reject } = Promise.withResolvers(); + const onAbort = () => reject(signal.reason); + signal.addEventListener("abort", onAbort, { once: true }); + try { + return await race([promise, aborted]); + } finally { + signal.removeEventListener("abort", onAbort); + } +} diff --git a/quest/m1/README.md b/quest/m1/README.md index 03a1dec8beb..3c57823667a 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -67,7 +67,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [JS IETF datagrams](/quest/m1/js-ietf-datagram.md) - `@moq/net` sends and receives datagram groups over moq-transport, like Rust - [#2991](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - one dynamic producer per track name in both languages, with the sequence namespace surviving a replacement - [JavaScript FETCH](/quest/m1/js-fetch.md) - generic on-demand group serving and IETF FETCH for browser publishers -- [JS fetch cancel](/quest/m1/js-fetch-cancel.md) - `FetchGroupOptions.signal` abandons one pending fetch without closing the track - [Archive](/quest/m1/archive/README.md) - record selected tracks to any object_store and replay them over FETCH or derived HLS; the catalog entry and format may break in place, since no archives exist - [Tooling](/quest/m1/tooling/README.md) - justfiles become a one-line menu over `sh/`, one impact map scopes CI, and every workflow step runs a recipe - [Path patterns](/quest/m1/path-patterns.md) - one matcher for every predicate over broadcast paths: tokens, origins, interest diff --git a/quest/m1/js-fetch-cancel.md b/quest/m1/js-fetch-cancel.md deleted file mode 100644 index e7371fb4fd5..00000000000 --- a/quest/m1/js-fetch-cancel.md +++ /dev/null @@ -1,25 +0,0 @@ -# [S] A JS fetch can be cancelled - -## Goal - -A `@moq/net` caller can abandon one pending group fetch without closing the -track or session, the follow-up #4357 left. - -## Plan - -Decided 2026-09-28: `FetchGroupOptions` (`js/net/src/track.ts`) gains -`signal?: AbortSignal`, the standard JS idiom, and additive. - -- Thread it through `js/net/src/broadcast.ts` and `lite/subscriber.ts`. - `ietf/subscriber.ts` rejects `fetchGroup` today (moq-transport has no - one-shot group fetch), so it stays unchanged. -- Fetches for the same group share one stream (`lite/subscriber.ts`), so an - abort releases this caller's share and rejects its promise with the - signal's reason. The stream is cancelled only when the last sharer leaves. -- An already-aborted signal rejects before anything is sent. -- Tests: one of two sharers aborts and the other still receives the group; - the last sharer aborting cancels the stream. -- Document the option where fetch is documented under `doc/`. - -Public API: additive `FetchGroupOptions.signal`. Wire: none new; the -existing cancel path. From 570042f0ebee6b916f378a4866472e403c048483 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 15:23:02 -0700 Subject: [PATCH 059/128] feat(net): IETF publisher reprices a held namespace in place A route whose price or hop chain moves behind the same original publisher is now a REQUEST_UPDATE on the PUBLISH_NAMESPACE request, or a re-sent NAMESPACE inline, instead of a withdrawal and a fresh advertisement. A republish or a first-hop change still withdraws. A refused update withdraws and honors its retry interval; an unanswered one drops the request and re-offers fresh. Co-Authored-By: Claude Opus 5.5 --- js/net/src/ietf/cluster.ts | 6 +- js/net/src/ietf/publish_namespace.ts | 4 +- js/net/src/ietf/publisher.test.ts | 389 ++++++++++++++++++++-- js/net/src/ietf/publisher.ts | 428 +++++++++++++++---------- quest/m1/README.md | 1 - quest/m1/cluster-publisher-in-place.md | 11 +- quest/m1/js-ietf-reprice.md | 19 -- 7 files changed, 633 insertions(+), 225 deletions(-) delete mode 100644 quest/m1/js-ietf-reprice.md diff --git a/js/net/src/ietf/cluster.ts b/js/net/src/ietf/cluster.ts index 3215ec5e732..9a77b3cea0b 100644 --- a/js/net/src/ietf/cluster.ts +++ b/js/net/src/ietf/cluster.ts @@ -14,9 +14,9 @@ * `lite/announce.ts`); this module is the moq-transport binding, negotiated on draft-17+ * only, where SETUP is a Key-Value-Pair block. * - * We are a leaf, never a relay: the only path we can advertise is our own, so we stamp a - * single-entry HOP_PATH and seed the cost at 0. What we get out of declaring is the other - * direction. A relay that knows our Hop ID withholds the advertisements that already flowed + * A broadcast we produce carries a single-entry HOP_PATH and a cost of 0, and a route we + * forward carries its own hop chain and warm cost with our id appended. What we get out of + * declaring is also the other direction. A relay that knows our Hop ID withholds the advertisements that already flowed * through us, so publishing a broadcast no longer announces it back to us, which is what * moq-lite has always done with its own hop chain. * diff --git a/js/net/src/ietf/publish_namespace.ts b/js/net/src/ietf/publish_namespace.ts index f094b7c57a0..1be3e59c458 100644 --- a/js/net/src/ietf/publish_namespace.ts +++ b/js/net/src/ietf/publish_namespace.ts @@ -75,8 +75,8 @@ export class PublishNamespace { * REQUEST_UPDATE (0x02) on a PUBLISH_NAMESPACE stream: the cluster parameters that * changed (draft-lcurley-moq-cluster, Updating an Advertisement). * - * Draft-17+ only: the extension negotiates on nothing earlier. We are a leaf and never - * reprice, so only a relay sends one to us. + * Draft-17+ only: the extension negotiates on nothing earlier. The publisher sends one when + * a forwarded route's price or hop chain moves behind the same original publisher. */ export class PublishNamespaceUpdate { static id = 0x02; diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index e4e76de3ce7..ef76bce3db9 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -1,4 +1,4 @@ -import { expect, mock, spyOn, test } from "bun:test"; +import { expect, jest, mock, spyOn, test } from "bun:test"; import { Signal } from "@moq/signals"; import type { Producer as BroadcastProducer } from "../broadcast.ts"; import { error } from "../error.ts"; @@ -16,11 +16,11 @@ import type * as Cluster from "./cluster.ts"; import { FetchHeader } from "./fetch.ts"; import { Frame, Group as GroupMessage } from "./object.ts"; import { PublishDone } from "./publish.ts"; -import { PublishNamespace } from "./publish_namespace.ts"; +import { PublishNamespace, PublishNamespaceUpdate } from "./publish_namespace.ts"; import { Publisher } from "./publisher.ts"; import { RequestError, RequestOk } from "./request.ts"; import { Subscribe, SubscribeOk } from "./subscribe.ts"; -import { SubscribeNamespace, SubscribeNamespaceEntry } from "./subscribe_namespace.ts"; +import { SubscribeNamespace, SubscribeNamespaceEntry, SubscribeNamespaceEntryDone } from "./subscribe_namespace.ts"; import { TrackStatusRequest } from "./track.ts"; import { ALPN, type IetfVersion, Version } from "./version.ts"; @@ -940,34 +940,373 @@ test("an advertisement carries our hop id once the peer declared one", async () } }); -test("an advertisement carries the announced route and re-prices in place", async () => { - const self: Hop = HopSchema.parse(7n); - const peer: Hop = HopSchema.parse(9n); - const via: Hop = HopSchema.parse(3n); - const pair = createMockTransportPair(ALPN.DRAFT_19); - const { pub, origin } = publisher(pair.server, { cluster: { self, peer } }); - const broadcast = origin.createBroadcast(Path.from("mine")); - broadcast.announce({ hops: [via], cost: 4n }); - void pub.runPublishNamespaces(); +/** Let every pending promise chain run without letting a faked timer fire. */ +async function flush() { + for (let i = 0; i < 20; i++) await new Promise((resolve) => setImmediate(resolve)); +} - const stream = await nextStream(pair.client); - if (!stream) throw new Error("no PUBLISH_NAMESPACE for the broadcast"); +/** Advance faked time in steps, letting the loop react between them as it would in real time. */ +async function advance(ms: number, step = 50) { + for (let elapsed = 0; elapsed < ms; elapsed += step) { + jest.advanceTimersByTime(step); + await flush(); + } +} + +/** Advance faked time until `done` holds, failing once `limit` has passed without it. */ +async function advanceUntil(done: () => boolean, limit: number, step = 50) { + for (let elapsed = 0; !done(); elapsed += step) { + if (elapsed >= limit) throw new Error(`still waiting after ${limit}ms`); + jest.advanceTimersByTime(step); + await flush(); + } +} + +/** How a promise has settled so far, read without awaiting it. */ +function watch(promise: Promise): { state: "pending" | "resolved" | "rejected"; value?: T } { + const status: { state: "pending" | "resolved" | "rejected"; value?: T } = { state: "pending" }; + promise.then( + (value) => { + status.state = "resolved"; + status.value = value; + }, + () => { + status.state = "rejected"; + }, + ); + return status; +} + +/** + * Every stream the publisher opens, in order, collected as they arrive so a test can ask + * whether one came without a timer. + */ +function accepted(transport: WebTransport): Stream[] { + const queue: Stream[] = []; + void (async () => { + const reader = transport.incomingBidirectionalStreams.getReader(); + for (;;) { + const next = await reader.read().catch(() => undefined); + if (!next || next.done) return; + queue.push(new Stream({ readable: next.value.readable, writable: next.value.writable, version: VERSION })); + } + })(); + return queue; +} + +/** Take the next stream the publisher opened, failing if it has not opened one. */ +async function take(queue: Stream[]): Promise { + await flush(); + const stream = queue.shift(); + if (!stream) throw new Error("expected the publisher to open a stream"); + return stream; +} + +/** Read one PUBLISH_NAMESPACE and its cluster parameters, then accept it. */ +async function acceptClustered(stream: Stream): Promise { expect(await stream.reader.u53()).toBe(PublishNamespace.id); const msg = await PublishNamespace.decode(stream.reader, VERSION, true); - expect(msg.trackNamespace).toBe(Path.from("mine")); - expect(msg.cluster).toEqual({ hops: [via, self], cost: 4n }); await acceptPublishNamespace(stream); + return msg.cluster; +} - broadcast.announce({ hops: [via], cost: 8n }); - const next = await nextStream(pair.client); - if (!next) throw new Error("no PUBLISH_NAMESPACE for the re-price"); - expect(await next.reader.u53()).toBe(PublishNamespace.id); - const updated = await PublishNamespace.decode(next.reader, VERSION, true); - expect(updated.trackNamespace).toBe(Path.from("mine")); - expect(updated.cluster).toEqual({ hops: [via, self], cost: 8n }); - await acceptPublishNamespace(next); +/** Read one REQUEST_UPDATE off a PUBLISH_NAMESPACE stream. */ +async function readUpdate(stream: Stream): Promise { + expect(await stream.reader.u53()).toBe(PublishNamespaceUpdate.id); + return (await PublishNamespaceUpdate.decode(stream.reader, VERSION)).update; +} - origin.close(); +/** A clustered publisher on fake time, with every stream it opens collected. */ +function clustered(requiresSolicitation = false) { + jest.useFakeTimers(); + const self: Hop = HopSchema.parse(7n); + const peer: Hop = HopSchema.parse(9n); + const pair = createMockTransportPair(ALPN.DRAFT_19); + const { pub, origin } = publisher(pair.server, { cluster: { self, peer }, requiresSolicitation }); + const streams = accepted(pair.client); + const close = () => { + origin.close(); + jest.useRealTimers(); + }; + return { self, pair, pub, origin, streams, close }; +} + +const VIA: Hop = HopSchema.parse(3n); +const MID: Hop = HopSchema.parse(4n); +const OTHER: Hop = HopSchema.parse(5n); + +/** + * A reprice is a REQUEST_UPDATE on the request that already carries the namespace, with + * only what changed. A cost that drops to 0 has to say so: REQUEST_UPDATE keeps an omitted + * parameter, so leaving it out would leave the peer holding the old price. + */ +test("a price change on a held namespace is one REQUEST_UPDATE, not a withdrawal", async () => { + const { self, pub, origin, streams, close } = clustered(); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + broadcast.announce({ hops: [VIA], cost: 4n }); + void pub.runPublishNamespaces(); + + const stream = await take(streams); + expect(await acceptClustered(stream)).toEqual({ hops: [VIA, self], cost: 4n }); + + broadcast.announce({ hops: [VIA], cost: 8n }); + expect(await readUpdate(stream)).toEqual({ hops: undefined, cost: 8n }); + await acceptPublishNamespace(stream); + + broadcast.announce({ hops: [VIA], cost: 0n }); + expect(await readUpdate(stream)).toEqual({ hops: undefined, cost: 0n }); + await acceptPublishNamespace(stream); + + // Still the one request, still open: nothing was withdrawn or advertised again. + const more = watch(stream.reader.done()); + await flush(); + expect(more.state).toBe("pending"); + expect(streams).toHaveLength(0); + } finally { + close(); + } +}); + +test("a hop path change behind the same publisher is one REQUEST_UPDATE carrying HOP_PATH", async () => { + const { self, pub, origin, streams, close } = clustered(); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + broadcast.announce({ hops: [VIA], cost: 4n }); + void pub.runPublishNamespaces(); + + const stream = await take(streams); + await acceptClustered(stream); + + broadcast.announce({ hops: [VIA, MID], cost: 4n }); + expect(await readUpdate(stream)).toEqual({ hops: [VIA, MID, self], cost: undefined }); + await acceptPublishNamespace(stream); + + const more = watch(stream.reader.done()); + await flush(); + expect(more.state).toBe("pending"); + expect(streams).toHaveLength(0); + } finally { + close(); + } +}); + +/** NAMESPACE has no REQUEST_UPDATE; the receiver reads a repeat as a replacement. */ +test("a solicited namespace is repriced with one NAMESPACE and no NAMESPACE_DONE", async () => { + const { self, pair, pub, origin, close } = clustered(true); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + broadcast.announce({ hops: [VIA], cost: 4n }); + + const subscription = await Stream.open(pair.client, { version: VERSION }); + const stream = await Stream.accept(pair.server, VERSION); + if (!stream) throw new Error("the subscription stream was never accepted"); + void pub.runSubscribeNamespace(new SubscribeNamespace({ requestId: 0n, namespace: Path.empty() }), stream); + + const entry = async () => { + expect(await subscription.reader.u53()).toBe(SubscribeNamespaceEntry.id); + return await SubscribeNamespaceEntry.decode(subscription.reader, VERSION, true); + }; + + expect(await subscription.reader.u53()).toBe(RequestOk.id); + await RequestOk.decode(subscription.reader, VERSION); + expect(await entry()).toMatchObject({ suffix: Path.from("mine"), cluster: { hops: [VIA, self], cost: 4n } }); + + broadcast.announce({ hops: [VIA, MID], cost: 8n }); + expect(await entry()).toMatchObject({ + suffix: Path.from("mine"), + cluster: { hops: [VIA, MID, self], cost: 8n }, + }); + + const more = watch(subscription.reader.u53()); + await flush(); + expect(more.state).toBe("pending"); + subscription.close(); + } finally { + close(); + } +}); + +/** + * A different broadcast is not a reprice, and neither is a different original publisher: + * the cluster draft has that withdrawn and advertised again, so a receiver never reads two + * publishers' content as one stream. + */ +const RESTARTS = [ + [ + "a republish", + (origin: OriginProducer, old: BroadcastProducer) => { + const next = origin.createBroadcast(Path.from("mine")); + next.announce({ hops: [VIA], cost: 4n }); + old.close(); + }, + ], + ["a first-hop change", (_: OriginProducer, old: BroadcastProducer) => old.announce({ hops: [OTHER], cost: 4n })], +] as const; + +test.each(RESTARTS)("%s withdraws the PUBLISH_NAMESPACE and advertises again", async (_, restart) => { + const { pub, origin, streams, close } = clustered(); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + broadcast.announce({ hops: [VIA], cost: 4n }); + void pub.runPublishNamespaces(); + + const old = await take(streams); + await acceptClustered(old); + + restart(origin, broadcast); + + // Draft-17+ withdraws with the FIN alone, and the replacement waits for it. + expect(await old.reader.done()).toBe(true); + const next = await take(streams); + expect(await acceptClustered(next)).toMatchObject({ cost: 4n }); + } finally { + close(); + } +}); + +test.each(RESTARTS)("%s withdraws the solicited NAMESPACE and sends it again", async (_, restart) => { + const { pair, pub, origin, close } = clustered(true); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + broadcast.announce({ hops: [VIA], cost: 4n }); + + const subscription = await Stream.open(pair.client, { version: VERSION }); + const stream = await Stream.accept(pair.server, VERSION); + if (!stream) throw new Error("the subscription stream was never accepted"); + void pub.runSubscribeNamespace(new SubscribeNamespace({ requestId: 0n, namespace: Path.empty() }), stream); + + expect(await subscription.reader.u53()).toBe(RequestOk.id); + await RequestOk.decode(subscription.reader, VERSION); + expect(await subscription.reader.u53()).toBe(SubscribeNamespaceEntry.id); + await SubscribeNamespaceEntry.decode(subscription.reader, VERSION, true); + + restart(origin, broadcast); + + expect(await subscription.reader.u53()).toBe(SubscribeNamespaceEntryDone.id); + expect((await SubscribeNamespaceEntryDone.decode(subscription.reader, VERSION)).suffix).toBe(Path.from("mine")); + expect(await subscription.reader.u53()).toBe(SubscribeNamespaceEntry.id); + expect((await SubscribeNamespaceEntry.decode(subscription.reader, VERSION, true)).suffix).toBe( + Path.from("mine"), + ); + subscription.close(); + } finally { + close(); + } +}); + +/** + * A REQUEST_ERROR on an update withdraws the advertisement, and the fresh offer that + * brings it back waits out the interval the peer named, or never comes for an interval + * of 0. + */ +test.each([ + ["waits out its retry interval", 10_000n], + ["that forbids retrying is never re-offered", 0n], +])("a refused update %s", async (_, retryInterval) => { + const { pub, origin, streams, close } = clustered(); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + broadcast.announce({ hops: [VIA], cost: 4n }); + void pub.runPublishNamespaces(); + + const stream = await take(streams); + await acceptClustered(stream); + + broadcast.announce({ hops: [VIA], cost: 8n }); + await readUpdate(stream); + await declinePublishNamespace(stream, retryInterval); + + // Our side finishes too, which completes the withdrawal. + expect(await stream.reader.done()).toBe(true); + + // Well past our own backoff, but inside the interval the peer asked for. + await advance(9_000); + expect(streams).toHaveLength(0); + + if (retryInterval === 0n) { + await advance(20_000); + expect(streams).toHaveLength(0); + return; + } + + // Past the interval, the next backoff (at most its ceiling) brings it back. + await advanceUntil(() => streams.length > 0, 6_500); + const fresh = await take(streams); + expect(await acceptClustered(fresh)).toMatchObject({ cost: 8n }); + } finally { + close(); + } +}); + +/** + * One update is outstanding per stream, which is what satisfies MAX_REQUEST_UPDATES + * without reading it: a change landing while one waits for its answer goes out after. + */ +test("a change while an update is unanswered waits for its answer", async () => { + const { pub, origin, streams, close } = clustered(); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + broadcast.announce({ hops: [VIA], cost: 4n }); + void pub.runPublishNamespaces(); + + const stream = await take(streams); + await acceptClustered(stream); + + broadcast.announce({ hops: [VIA], cost: 8n }); + expect(await readUpdate(stream)).toEqual({ hops: undefined, cost: 8n }); + + broadcast.announce({ hops: [VIA], cost: 12n }); + const second = watch(stream.reader.u53()); + await advance(1_000); + expect(second.state).toBe("pending"); + expect(streams).toHaveLength(0); + + await acceptPublishNamespace(stream); + await flush(); + expect(second.state).toBe("resolved"); + expect(second.value).toBe(PublishNamespaceUpdate.id); + expect((await PublishNamespaceUpdate.decode(stream.reader, VERSION)).update).toEqual({ + hops: undefined, + cost: 12n, + }); + await acceptPublishNamespace(stream); + } finally { + close(); + } +}); + +/** + * A peer that never answers an update cannot be assumed to hold either price, so the + * request is dropped and the namespace comes back on a fresh one. + */ +test("an unanswered update drops the request and re-offers the namespace fresh", async () => { + const { pub, origin, streams, close } = clustered(); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + broadcast.announce({ hops: [VIA], cost: 4n }); + void pub.runPublishNamespaces(); + + const stream = await take(streams); + await acceptClustered(stream); + + broadcast.announce({ hops: [VIA], cost: 8n }); + await readUpdate(stream); + const reset = watch(stream.reader.u53()); + + await advance(4_900); + expect(reset.state).toBe("pending"); + expect(streams).toHaveLength(0); + + // The timeout resets the request, then the retry offers it on a new one. + await advance(100); + expect(reset.state).toBe("rejected"); + await advanceUntil(() => streams.length > 0, 200); + const fresh = await take(streams); + expect(await acceptClustered(fresh)).toMatchObject({ cost: 8n }); + } finally { + close(); + } }); /** diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 9666621b20a..68bc40d6354 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -2,7 +2,7 @@ import { type Dispose, type Getter, race, Signal } from "@moq/signals"; import type * as broadcast from "../broadcast.ts"; import { controlTimeout, error, reason, StreamCode, StreamError } from "../error.ts"; import type * as group from "../group.ts"; -import type { Route } from "../hop.ts"; +import type { Hop, Route } from "../hop.ts"; import { hiddenBelow, hooks, presented } from "../internal.ts"; import type { Consumer as OriginConsumer } from "../origin.ts"; import * as Path from "../path.ts"; @@ -21,7 +21,12 @@ import { FetchFrame, Frame, Group as GroupMessage } from "./object.ts"; import { fromWire, toWire } from "./priority.ts"; import * as Properties from "./properties.ts"; import { PublishDone, PublishDoneStatus } from "./publish.ts"; -import { PublishNamespace, PublishNamespaceDone, PublishNamespaceOk } from "./publish_namespace.ts"; +import { + PublishNamespace, + PublishNamespaceDone, + PublishNamespaceOk, + PublishNamespaceUpdate, +} from "./publish_namespace.ts"; import { RequestError, RequestOk } from "./request.ts"; import { type Subscribe, SubscribeError, SubscribeOk } from "./subscribe.ts"; import { @@ -49,16 +54,35 @@ function clusterFor(base: Cluster.Advert | undefined, route: Route): Cluster.Adv } /** - * Whether the peer would decode the same advertisement: the same broadcast and, with MoQ - * Cluster, the same hop chain and warm cost. The cold cost, and the whole route without - * Cluster, never reach the wire, so a change there must not restart the namespace. + * What it takes to move the peer from `held` to `next`. + * + * - `"same"`: the peer would decode the same advertisement. The cold cost, and the whole + * route without Cluster, never reach the wire, so a change there sends nothing. + * - `"restart"`: nothing is held, nothing is wanted, a different broadcast, or a different + * original publisher, which draft-lcurley-moq-cluster has withdrawn and advertised again + * so a receiver never reads two publishers' content as one stream. + * - Otherwise the same broadcast from the same original publisher at a new hop chain or + * warm cost, repriced in place with only the parameters that changed. */ -function sameAdvert(base: Cluster.Advert | undefined, a: Advertised | undefined, b: Advertised | undefined): boolean { - if (a === undefined || b === undefined || a.identity !== b.identity) return false; - const x = clusterFor(base, a.route); - const y = clusterFor(base, b.route); - if (x === undefined || y === undefined) return x === y; - return x.cost === y.cost && x.hops.length === y.hops.length && x.hops.every((hop, i) => hop === y.hops[i]); +function change( + base: Cluster.Advert | undefined, + held: Advertised | undefined, + next: Advertised | undefined, +): "same" | "restart" | Cluster.Update { + if (held === undefined || next === undefined || held.identity !== next.identity) return "restart"; + const x = clusterFor(base, held.route); + const y = clusterFor(base, next.route); + if (x === undefined || y === undefined) return x === y ? "same" : "restart"; + + const hops = sameHops(x.hops, y.hops); + if (hops && x.cost === y.cost) return "same"; + if (x.hops[0] !== y.hops[0]) return "restart"; + return { hops: hops ? undefined : y.hops, cost: x.cost === y.cost ? undefined : y.cost }; +} + +/** Whether two hop paths list the same hops in the same order. */ +function sameHops(a: Hop[], b: Hop[]): boolean { + return a.length === b.length && a.every((hop, i) => hop === b[i]); } /** @@ -83,6 +107,39 @@ function retryAfter(delay: number): Promise { */ type Refused = "never" | number; +/** + * How the peer answered an advertisement or an update: it holds the namespace, it does + * not and said nothing about coming back (`"dropped"`), or it refused. + */ +type Answer = "held" | "dropped" | Refused; + +/** The open PUBLISH_NAMESPACE request per advertised path. */ +type Requests = Map; + +/** What one announce loop knows about the peer, keyed the way that loop names namespaces. */ +interface Namespaces { + /** What the peer holds, by identity plus route. */ + active: Map; + + /** What the peer refused, and whether coming back is worth anything. */ + refused: Map; + + /** The identity each refusal was about, so a republish at the same path clears it. */ + offered: Map; +} + +/** Where one announce loop sends its advertisements. */ +interface Target { + /** Advertise a namespace the peer does not hold. */ + advertise(key: Path.Valid, next: Advertised): Promise; + + /** Reprice a namespace the peer holds, from the same original publisher. */ + update(key: Path.Valid, next: Advertised, update: Cluster.Update): Promise; + + /** Withdraw a namespace the peer holds. */ + withdraw(key: Path.Valid): Promise; +} + /** What {@link Publisher.runGroup} needs to serve one group. */ interface RunGroup { /** The subscription's request ID, doubling as the track alias. */ @@ -723,8 +780,9 @@ export class Publisher { * This carries the advertisements when the peer asked to be told on request (MoQ * Solicit); otherwise {@link runPublishNamespaces} has already announced everything * visible and repeating it here would leave the peer holding two sources for one - * broadcast, so only the hidden namespaces it may see ride here (MoQ Hidden). Draft-16+ streams Namespace entries inline; draft-14/15 predate those - * messages, so each advertisement is a PUBLISH_NAMESPACE request of its own. + * broadcast, so only the hidden namespaces it may see ride here (MoQ Hidden). + * Draft-16+ streams Namespace entries inline; draft-14/15 predate those messages, so + * each advertisement is a PUBLISH_NAMESPACE request of its own. * * @internal */ @@ -734,7 +792,7 @@ export class Publisher { const legacy = version === Version.DRAFT_14 || version === Version.DRAFT_15; // Draft-14/15: the open PUBLISH_NAMESPACE request per advertised suffix. - const requests = new Map(); + const requests: Requests = new Map(); try { // Send OK response @@ -757,35 +815,34 @@ export class Publisher { (!this.#hidden || msg.hidden || !hiddenBelow(prefix, covered)) && (this.#requiresSolicitation || (this.#hidden && hiddenBelow(Path.empty(), covered))); - // Reports whether the peer now holds the namespace: an inline entry always - // lands, but a PUBLISH_NAMESPACE request can be declined. - const advertise = async (suffix: Path.Valid, snap: Advertised): Promise => { - const cluster = clusterFor(this.#advert, snap.route); - if (legacy) { - return await this.#advertise(Path.join(prefix, suffix), requests, refused, cluster); - } - + // Inline entries always land, and the receiver treats a repeated NAMESPACE as a + // replacement, so repricing one is just sending it again. Only a legacy + // PUBLISH_NAMESPACE request can be declined. + const namespace = async (suffix: Path.Valid, snap: Advertised): Promise => { await stream.writer.u53(SubscribeNamespaceEntry.id); + const cluster = clusterFor(this.#advert, snap.route); await new SubscribeNamespaceEntry({ suffix, cluster }).encode(stream.writer, version); - return true; - }; - const withdraw = async (suffix: Path.Valid) => { - if (legacy) { - await this.#withdraw(Path.join(prefix, suffix), requests); - } else { - await stream.writer.u53(SubscribeNamespaceEntryDone.id); - await new SubscribeNamespaceEntryDone({ suffix }).encode(stream.writer, version); - } + return "held"; }; - - // What the peer holds: keyed by suffix, valued by the routing front, so a republish - // diffs as withdraw-then-advertise rather than nothing. - let active = new Map(); + const target: Target = legacy + ? { + advertise: (suffix, snap) => + this.#advertise(Path.join(prefix, suffix), requests, clusterFor(this.#advert, snap.route)), + update: (suffix, _snap, update) => this.#update(Path.join(prefix, suffix), requests, update), + withdraw: (suffix) => this.#withdraw(Path.join(prefix, suffix), requests), + } + : { + advertise: namespace, + update: namespace, + withdraw: async (suffix) => { + await stream.writer.u53(SubscribeNamespaceEntryDone.id); + await new SubscribeNamespaceEntryDone({ suffix }).encode(stream.writer, version); + }, + }; + + // Keyed by suffix, as the entries name them. + const ns: Namespaces = { active: new Map(), refused: new Map(), offered: new Map() }; let retry = 0; - // What the peer refused, and whether coming back is worth anything. - const refused = new Map(); - // The identity each refusal was about, so a republish at the same path clears it. - const offered = new Map(); for (;;) { // Subscribe BEFORE reconciling, for the same reason as @@ -803,50 +860,7 @@ export class Publisher { break; } - const updated = presented(prefix, advertised, carries); - - // A namespace that is gone, or that a republish replaced, takes its refusal with - // it: the peer refused a broadcast, not a path forever, so a different one at - // the same path is offered again. The origin swaps the front in one mutation, - // so the path never leaves `updated` and only the front says they differ. - for (const path of [...refused.keys()]) { - const suffix = Path.stripPrefix(prefix, path); - const snap = suffix === null ? undefined : updated.get(suffix); - if (snap === undefined || offered.get(path) !== snap.identity) { - refused.delete(path); - offered.delete(path); - } - } - - // Track what the peer holds rather than what we attempted: a declined - // advertisement stays out of `held`, so the next turn retries it instead of - // believing the namespace is already up. - const held = new Map(active); - // Withdraw first so a republish or re-price reads as withdraw-then-advertise - // (a restart). Identity change is a new broadcast; a route change is the - // same one at a new cost or hop chain. - for (const [removed, snap] of active) { - if (sameAdvert(this.#advert, updated.get(removed), snap)) continue; - await withdraw(removed); - held.delete(removed); - } - for (const [added, snap] of updated) { - if (sameAdvert(this.#advert, held.get(added), snap)) continue; - if (!this.#offerable(Path.join(prefix, added), refused)) continue; - offered.set(Path.join(prefix, added), snap.identity); - if (await advertise(added, snap)) held.set(added, snap); - } - - active = held; - - // Whatever we wanted up and could not get up, as {@link runPublishNamespaces} - // does: only a legacy request can be declined, and nothing about the peer - // starting to answer raises a signal this loop is watching. - const outstanding = [...updated].some( - ([suffix, snap]) => - !sameAdvert(this.#advert, active.get(suffix), snap) && - this.#pending(Path.join(prefix, suffix), refused), - ); + const outstanding = await this.#reconcile(ns, presented(prefix, advertised, carries), target); retry = outstanding ? Math.min(retry ? retry * 2 : RETRY_BASE, RETRY_MAX) : 0; // Wait for the next change, or for the peer to unsubscribe. @@ -889,7 +903,12 @@ export class Publisher { } // The open PUBLISH_NAMESPACE request per advertised path. - const requests = new Map(); + const requests: Requests = new Map(); + const target: Target = { + advertise: (path, snap) => this.#advertise(path, requests, clusterFor(this.#advert, snap.route)), + update: (path, _snap, update) => this.#update(path, requests, update), + withdraw: (path) => this.#withdraw(path, requests), + }; // The origin outlives the session and its signal never ends, so this loop needs the // session's own ending to stop: without it a closed connection leaves the loop parked @@ -903,14 +922,9 @@ export class Publisher { let dispose: Dispose | undefined; try { - // What the peer holds: keyed by path, valued by identity plus route, so a - // republish diffs as withdraw-then-advertise rather than nothing. - let active = new Map(); + // Keyed by path. + const ns: Namespaces = { active: new Map(), refused: new Map(), offered: new Map() }; let retry = 0; - // What the peer refused, and whether coming back is worth anything. - const refused = new Map(); - // The identity each refusal was about, so a republish at the same path clears it. - const offered = new Map(); for (;;) { // Subscribe BEFORE reconciling. Each advertisement below waits a round trip @@ -936,45 +950,7 @@ export class Publisher { updated.set(covered, candidates[0]); } - // A namespace that is gone, or that a republish replaced, takes its refusal with - // it: the peer refused a broadcast, not a path forever, so a different one at - // the same path is offered again. Rust gets this by rebuilding the watched entry. - for (const path of [...refused.keys()]) { - const snap = updated.get(path); - if (snap === undefined || offered.get(path) !== snap.identity) { - refused.delete(path); - offered.delete(path); - } - } - - // Withdraw first so a republish or re-price reads as withdraw-then-advertise - // (a restart) rather than nothing. - for (const [removed, snap] of active) { - if (sameAdvert(this.#advert, updated.get(removed), snap)) continue; - await this.#withdraw(removed, requests); - } - for (const [added, snap] of updated) { - if (sameAdvert(this.#advert, active.get(added), snap)) continue; - if (!this.#offerable(added, refused)) continue; - offered.set(added, snap.identity); - await this.#advertise(added, requests, refused, clusterFor(this.#advert, snap.route)); - } - - // What the peer holds, not what we attempted: a declined PUBLISH_NAMESPACE - // leaves no request behind, so it stays outstanding below. - active = new Map( - [...requests.keys()].flatMap((path) => { - const snap = updated.get(path); - return snap ? [[path, snap] as const] : []; - }), - ); - - // Whatever we wanted up and could not get up. Stream credit freeing, a - // transient failure clearing, or the peer starting to answer raises no - // signal of its own, so the only way back is to ask again on a timer. - const outstanding = [...updated].some( - ([path, snap]) => !sameAdvert(this.#advert, active.get(path), snap) && this.#pending(path, refused), - ); + const outstanding = await this.#reconcile(ns, updated, target); retry = outstanding ? Math.min(retry ? retry * 2 : RETRY_BASE, RETRY_MAX) : 0; // Wait for the next change, which has already fired if one landed above. @@ -997,14 +973,78 @@ export class Publisher { } } + /** + * Bring the peer's view in line with `updated`, one namespace at a time, and report + * whether anything it should hold is still missing and worth coming back for. + * + * Nothing the peer cannot see is sent, a reprice updates the namespace in place, and + * anything else is withdrawn first so a republish reads as withdraw-then-advertise. + * `ns` records what the peer holds rather than what we attempted: a declined + * advertisement or update stays out of it, so the next turn offers it fresh instead + * of believing it is already up. + */ + async #reconcile(ns: Namespaces, updated: Map, target: Target): Promise { + // A namespace that is gone, or that a republish replaced, takes its refusal with + // it: the peer refused a broadcast, not a path forever, so a different one at the + // same path is offered again. The origin swaps the front in one mutation, so the + // path never leaves `updated` and only the front says they differ. Rust gets this + // by rebuilding the watched entry. + for (const key of [...ns.refused.keys()]) { + const snap = updated.get(key); + if (snap === undefined || ns.offered.get(key) !== snap.identity) { + ns.refused.delete(key); + ns.offered.delete(key); + } + } + + const held = new Map(ns.active); + for (const [key, snap] of ns.active) { + if (change(this.#advert, snap, updated.get(key)) !== "restart") continue; + await target.withdraw(key); + held.delete(key); + } + + for (const [key, snap] of updated) { + const prev = held.get(key); + const diff = change(this.#advert, prev, snap); + if (diff === "same") continue; + + let answer: Answer; + if (prev !== undefined && diff !== "restart") { + answer = await target.update(key, snap, diff); + } else { + // A fresh offer waits for what a refusal asked for, whatever brought us back. + if (!this.#offerable(key, ns.refused)) continue; + answer = await target.advertise(key, snap); + } + ns.offered.set(key, snap.identity); + + if (answer === "held") { + held.set(key, snap); + } else { + held.delete(key); + if (answer !== "dropped") ns.refused.set(key, answer); + } + } + + ns.active = held; + + // Whatever we wanted up and could not get up. Stream credit freeing, a transient + // failure clearing, or the peer starting to answer raises no signal of its own, so + // the only way back is to ask again on a timer. + return [...updated].some( + ([key, snap]) => change(this.#advert, held.get(key), snap) !== "same" && this.#pending(key, ns.refused), + ); + } + /** * Whether a namespace may be offered to the peer right now. * * A peer that asked never to be offered it again means it, whatever brought us back; * one that named a minimum wait gets it, even when our own backoff comes round sooner. */ - #offerable(path: Path.Valid, refused: Map): boolean { - const entry = refused.get(path); + #offerable(key: Path.Valid, refused: Map): boolean { + const entry = refused.get(key); if (entry === undefined) return true; return entry !== "never" && Date.now() >= entry; } @@ -1017,26 +1057,35 @@ export class Publisher { * gating the timer on offerable instead would disarm it for exactly the wait it is * supposed to be counting. Only a refusal that forbids retrying ends it. */ - #pending(path: Path.Valid, refused: Map): boolean { - return refused.get(path) !== "never"; + #pending(key: Path.Valid, refused: Map): boolean { + return refused.get(key) !== "never"; + } + + /** + * What a REQUEST_ERROR's retry interval, in milliseconds, says about re-offering the + * namespace. + * + * Draft-14/15 carry no such field, so a 0 there says nothing and our own backoff + * stands; everywhere else 0 means the peer does not want this again. + */ + #refusal(err: RequestError): Answer { + const version = this.#session.version; + if (version === Version.DRAFT_14 || version === Version.DRAFT_15) return "dropped"; + return err.retryInterval === 0n ? "never" : Date.now() + Number(err.retryInterval); } /** * Advertise one namespace on its own PUBLISH_NAMESPACE request. A declined request * is logged and skipped: a peer that wants none of this rejects each one and stays * connected. - * - * `refused` records what a refusal said about coming back, so a peer that asked not to - * be offered a namespace again is not re-offered it by the retry above. */ async #advertise( path: Path.Valid, - requests: Map, - refused: Map, + requests: Requests, cluster: Cluster.Advert | undefined = this.#advert, - ): Promise { + ): Promise { const requestId = await this.#session.nextRequestId(); - if (requestId === undefined) return false; + if (requestId === undefined) return "dropped"; // Opening is inside the try because it fails like any other advertisement does: // a peer out of stream credit rejects here, and letting that escape would unwind @@ -1051,8 +1100,8 @@ export class Publisher { // advertisements, so a peer that takes the stream and answers nothing strands // every publish and withdrawal behind it. Timing out costs this namespace a // turn and leaves it outstanding, which the retry above re-offers. - await withTimeout( - (async () => { + const answer = await withTimeout( + (async (): Promise => { await stream.writer.u53(PublishNamespace.id); const msg = new PublishNamespace({ requestId, trackNamespace: path, cluster }); await msg.encode(stream.writer, this.#session.version); @@ -1060,26 +1109,16 @@ export class Publisher { // Read response (RequestOk and PublishNamespaceOk share 0x07) const respTypeId = await stream.reader.u53(); if (respTypeId === RequestError.id) { - // The peer named how long to stay away, in milliseconds. Draft-14/15 - // carry no such field, so a 0 there says nothing and our own backoff - // stands; everywhere else 0 means it does not want this again. const err = await RequestError.decode(stream.reader, this.#session.version); - const legacy = - this.#session.version === Version.DRAFT_14 || this.#session.version === Version.DRAFT_15; - if (!legacy) { - refused.set( - path, - err.retryInterval === 0n ? "never" : Date.now() + Number(err.retryInterval), - ); - } - throw new Error( - `PublishNamespace rejected: ${requestReason( - err.errorCode, - err.reasonPhrase, - "publish_namespace", - this.#session.version, - )}`, + const why = requestReason( + err.errorCode, + err.reasonPhrase, + "publish_namespace", + this.#session.version, ); + console.warn(`announce refused: broadcast=${path} error=${why}`); + stream.abort(new Error(`PublishNamespace rejected: ${why}`)); + return this.#refusal(err); } if (respTypeId !== RequestOk.id) { throw new Error(`PublishNamespace rejected: typeId=0x${respTypeId.toString(16)}`); @@ -1090,29 +1129,82 @@ export class Publisher { } else { await RequestOk.decode(stream.reader, this.#session.version); } + return "held"; })(), ADVERTISE_TIMEOUT_MS, `advertisement timed out after ${ADVERTISE_TIMEOUT_MS}ms waiting for the peer's answer`, ); - requests.set(path, { path, requestId, stream: request }); - return true; + if (answer === "held") requests.set(path, { path, requestId, stream }); + return answer; } catch (err: unknown) { // The peer never answered the advertisement: a control timeout, not late content. const e = err instanceof TimeoutError ? controlTimeout(err) : error(err); console.warn(`announce failed: broadcast=${path} error=${reason(e)}`); request?.abort(e); - return false; + return "dropped"; } } + /** + * Reprice a namespace the peer holds: REQUEST_UPDATE on the request that carries it, + * with only the parameters that changed, then its answer. + * + * Waiting for the answer keeps one update outstanding per stream, which satisfies any + * MAX_REQUEST_UPDATES the peer set without reading it; a change landing meanwhile waits + * for the next turn. The answer decides whether the peer still holds the namespace: a + * REQUEST_ERROR closes the peer's side and withdraws the advertisement, so ours is + * finished too, and an unanswered update is dropped abruptly, since a peer that ignored + * it cannot be assumed to hold either price. Either way the retry re-offers it fresh. + */ + async #update(path: Path.Valid, requests: Requests, update: Cluster.Update): Promise { + const request = requests.get(path); + if (!request) return "dropped"; + + const version = this.#session.version; + let answer: Answer; + try { + const requestId = await this.#session.nextRequestId(); + if (requestId === undefined) throw new Error("no request ID for the update"); + + answer = await withTimeout( + (async (): Promise => { + const { writer, reader } = request.stream; + await writer.u53(PublishNamespaceUpdate.id); + await new PublishNamespaceUpdate({ requestId, update }).encode(writer, version); + + const typeId = await reader.u53(); + if (typeId === RequestError.id) { + const err = await RequestError.decode(reader, version); + const why = requestReason(err.errorCode, err.reasonPhrase, "publish_namespace", version); + console.warn(`publish_namespace update refused: broadcast=${path} error=${why}`); + return this.#refusal(err); + } + if (typeId !== RequestOk.id) { + throw new Error(`unexpected answer to the update: typeId=0x${typeId.toString(16)}`); + } + await RequestOk.decode(reader, version); + return "held"; + })(), + ADVERTISE_TIMEOUT_MS, + `update timed out after ${ADVERTISE_TIMEOUT_MS}ms waiting for the peer's answer`, + ); + } catch (err: unknown) { + const e = err instanceof TimeoutError ? controlTimeout(err) : error(err); + console.warn(`publish_namespace update failed: broadcast=${path} error=${reason(e)}`); + requests.delete(path); + request.stream.abort(e); + return "dropped"; + } + + if (answer !== "held") await this.#withdraw(path, requests); + return answer; + } + /** * Close out a namespace's PUBLISH_NAMESPACE request with PUBLISH_NAMESPACE_DONE. */ - async #withdraw( - path: Path.Valid, - requests: Map, - ) { + async #withdraw(path: Path.Valid, requests: Requests) { const request = requests.get(path); if (!request) return; requests.delete(path); diff --git a/quest/m1/README.md b/quest/m1/README.md index 03a1dec8beb..d256bd8a9fc 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -62,7 +62,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Go and Dart doc samples](/quest/m1/doc-samples-go-dart.md) - Go and Dart doc samples compile against their wrappers - [Data capture in bindings](/quest/m1/data-capture-bindings.md) - moq-ffi and every wrapper pass a data frame's capture time, and the JSON window producer takes one - [Moxygen compatibility](/quest/m1/moxygen/README.md) - one subgroup per group, whole-group FETCH, and one datagram per group, never a full moxygen pass -- [JS IETF reprice](/quest/m1/js-ietf-reprice.md) - `@moq/net`'s IETF publisher reprices a held namespace in place, like Rust, instead of withdraw-then-advertise - [Cluster publisher in place](/quest/m1/cluster-publisher-in-place.md) - under the IETF cluster extension a publisher change updates an advertisement in place, like lite, and never splices across publishers - [JS IETF datagrams](/quest/m1/js-ietf-datagram.md) - `@moq/net` sends and receives datagram groups over moq-transport, like Rust - [#2991](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - one dynamic producer per track name in both languages, with the sequence namespace surviving a replacement diff --git a/quest/m1/cluster-publisher-in-place.md b/quest/m1/cluster-publisher-in-place.md index 56031a7f1be..fcdb9a15527 100644 --- a/quest/m1/cluster-publisher-in-place.md +++ b/quest/m1/cluster-publisher-in-place.md @@ -73,9 +73,10 @@ withdraw fallback and no negotiation. namespace. Emit an in-place update instead. In-flight subscriptions drain the old copy, and new requests neither reuse the old publisher's cached track info nor splice onto a live subscription, matching Rust. -- JS sender `js/net/src/ietf/publisher.ts` (`runPublishNamespaces`): once - JS IETF reprice gives it in-place updates, a first-hop change uses them too - instead of withdrawing. +- JS sender `js/net/src/ietf/publisher.ts` (`change`): a first-hop change + returns an update instead of `"restart"`, so both the PUBLISH_NAMESPACE + path (REQUEST_UPDATE) and the inline path (a re-sent NAMESPACE) update in + place instead of withdrawing. - Docs: `doc/bin/relay/cluster.md`, and any `doc/concept` page that describes the cluster extension, say a publisher change updates in place, in-flight subscriptions drain the old publisher, and new requests take the @@ -93,10 +94,6 @@ Public API: none. Wire: the cluster extension's update semantics change (no message or parameter changes), breaking first-hop updates toward released relays as decided above. -## Required - -- [JS IETF reprice](/quest/m1/js-ietf-reprice.md) - the JS IETF publisher updates a held namespace in place, which a first-hop change then reuses - ## Related - [Cluster routing](/quest/m1/cluster-routing.md) - the routing plan these advertisements feed diff --git a/quest/m1/js-ietf-reprice.md b/quest/m1/js-ietf-reprice.md deleted file mode 100644 index 9378a100add..00000000000 --- a/quest/m1/js-ietf-reprice.md +++ /dev/null @@ -1,19 +0,0 @@ -# [S] JS IETF reprices a namespace in place - -## Goal - -When a route's price changes but its original publisher does not, `@moq/net`'s IETF publisher reprices the namespace the peer already holds in place, as Rust does, instead of withdrawing it and advertising it again. A subscriber never sees a namespace briefly vanish because its cost or hop chain moved, unless the peer refuses or ignores the update. - -## Plan - -Rust already does this in `rs/moq-net/src/ietf/publisher.rs` (`sync_namespace`, `update_namespace`). `js/net/src/ietf/publisher.ts` withdraws first on both paths, so that "a republish or re-price reads as withdraw-then-advertise". Match Rust: - -- PUBLISH_NAMESPACE: send REQUEST_UPDATE on the request that carries the namespace, with only the changed parameters, and wait for its answer so one update is outstanding per stream (which satisfies MAX_REQUEST_UPDATES). A REQUEST_ERROR withdraws it and an unanswered update drops the request; the retry re-offers it fresh, honoring a REQUEST_ERROR's retry interval as Rust's `refusal` does (from draft-16, 0 means never). -- Inline (a solicited SUBSCRIBE_NAMESPACE, draft-16+): re-send NAMESPACE on the response stream, which the receiver treats as a replacement, without NAMESPACE_DONE first. -- A different broadcast still withdraws and advertises again. A different original publisher (first hop) still withdraws too, as the draft requires today; [cluster publisher in place](/quest/m1/cluster-publisher-in-place.md) builds on this quest to update it in place (decided 2026-09-28). - -The wire-visible comparison from the announce-dedupe work decides whether anything is sent at all. - -Found while landing the announce update dedupe (#4423). No wire change: REQUEST_UPDATE is already in the IETF drafts the tree negotiates. - -Tests: a price change on a held namespace sends one REQUEST_UPDATE and no PUBLISH_NAMESPACE_DONE; a nonzero cost repriced to 0 carries an explicit cost 0, since REQUEST_UPDATE keeps an omitted parameter; a hop path change behind the same first hop sends one REQUEST_UPDATE carrying HOP_PATH and no withdrawal; a solicited namespace is repriced with one NAMESPACE and no NAMESPACE_DONE; a republish still withdraws on both paths (inline: NAMESPACE_DONE, then NAMESPACE), as does a first-hop change until the cluster quest; a REQUEST_ERROR withdraws, and its retry interval holds the re-offer back (never, for 0 from draft-16); with mocked time, a second change while an update is unanswered sends nothing until it resolves, and an update that times out drops the request and re-offers the namespace on a fresh one. From e3caf5c26a5d6081f326dcfd0bf080259ff51955 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 15:41:14 -0700 Subject: [PATCH 060/128] quest: datagrams are live-only; drop hls-linger; demo serve-hls renditions Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 2 +- quest/m1/datagram-unfetchable.md | 44 ++++++++++++++++++++++++++++++++ quest/m1/hls-linger.md | 41 ----------------------------- quest/m2/README.md | 2 ++ quest/m2/serve-hls-renditions.md | 16 ++++++++++++ 5 files changed, 63 insertions(+), 42 deletions(-) create mode 100644 quest/m1/datagram-unfetchable.md delete mode 100644 quest/m1/hls-linger.md create mode 100644 quest/m2/serve-hls-renditions.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 4b9ac7a8f1e..5a68f4c02d9 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -56,7 +56,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Video surface](/quest/m1/video-surface.md) - on dev, moq-ffi's `native` becomes `surface`, refused on platforms with no surface - [HLS discontinuity sequence](/quest/m1/hls-discontinuity-sequence.md) - on dev, `Segment::discontinuity` is the absolute sequence, so every cursor agrees - [Auth client CA](/quest/m1/relay-auth-client-ca.md) - on dev, `auth::Config::validate` and `init` take the client-CA flag, so no caller can skip the check -- [HLS linger](/quest/m1/hls-linger.md) - `moq_hls::Server` serves an ended broadcast for its playlist window plus grace, so the moq.pro edge drops its own pool - [Remove live()](/quest/m1/remove-live.md) - on dev, importers publish stream timestamps verbatim, the catalog clock maps them to wall time, and an encoder restart becomes a new epoch - [Go and Dart doc samples](/quest/m1/doc-samples-go-dart.md) - Go and Dart doc samples compile against their wrappers - [Data capture in bindings](/quest/m1/data-capture-bindings.md) - moq-ffi and every wrapper pass a data frame's capture time, and the JSON window producer takes one @@ -64,6 +63,7 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [JS IETF reprice](/quest/m1/js-ietf-reprice.md) - `@moq/net`'s IETF publisher reprices a held namespace in place, like Rust, instead of withdraw-then-advertise - [Cluster publisher in place](/quest/m1/cluster-publisher-in-place.md) - under the IETF cluster extension a publisher change updates an advertisement in place, like lite, and never splices across publishers - [JS IETF datagrams](/quest/m1/js-ietf-datagram.md) - `@moq/net` sends and receives datagram groups over moq-transport, like Rust +- [Datagrams are live-only](/quest/m1/datagram-unfetchable.md) - no FETCH, replay to a new subscriber, or cache fill ever returns a datagram group - [#2991](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - one dynamic producer per track name in both languages, with the sequence namespace surviving a replacement - [JavaScript FETCH](/quest/m1/js-fetch.md) - generic on-demand group serving and IETF FETCH for browser publishers - [JS fetch cancel](/quest/m1/js-fetch-cancel.md) - `FetchGroupOptions.signal` abandons one pending fetch without closing the track diff --git a/quest/m1/datagram-unfetchable.md b/quest/m1/datagram-unfetchable.md new file mode 100644 index 00000000000..febf484b023 --- /dev/null +++ b/quest/m1/datagram-unfetchable.md @@ -0,0 +1,44 @@ +# [S] Datagrams are live-only + +## Goal + +A datagram group is delivered only to subscribers present when it is sent. +FETCH never returns one, a new subscription never replays buffered datagrams, +and a relay fills no cache miss with one. Anything that needs reliable or +late-joiner delivery should use a stream group instead. + +## Plan + +Decided in planning (09-29), after the moxygen fetch-fill agent found that the +relay's group-fetch decoder refuses a draft-16+ fetch object that carries the +datagram flag, and reports it as "unsupported": + +- Keep the existing 64-datagram send buffer per track + (`rs/moq-net/src/model/track.rs`, `MAX_DATAGRAMS`). An age bound was + considered and dropped. +- A new subscription starts at the next datagram sent, not at the buffered + backlog. This covers Rust and `@moq/net`, lite and IETF. +- FETCH never serves a datagram group. A publisher answers a FETCH for one the + way it answers any group it won't deliver (dropped or does not exist), + never with its payload. +- A received fetch object with the datagram flag is refused as not fetchable, + a protocol error rather than `Unsupported`. That covers the relay's group + fill (`recv_group_fetch_objects`, on the moxygen line) and the joining-fetch + fill (`run_fill_objects`). +- Update `drafts/draft-lcurley-moq-lite.md` to say datagrams are neither + cached nor fetchable, and `doc/concept/`. Run `just drafts check` and + `just test interop --all`. + +Not planned: reliable or cached datagrams. If they are ever wanted, the way to +get them is back-pressure in the QUIC library and treating each datagram like +a one-shot stream, not a cache. + +Tests: a subscriber joining after datagrams were sent receives only later +ones. A FETCH covering a datagram group gets no payload. A fetch stream +carrying a datagram-flagged object is refused. + +## Related + +- [Moxygen compatibility](/quest/m1/moxygen/README.md) - says it carries one datagram per group live; this keeps them out of FETCH +- [JS IETF datagrams](/quest/m1/js-ietf-datagram.md) - JS datagram send and receive over moq-transport +- [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - datagram groups stay best effort there too diff --git a/quest/m1/hls-linger.md b/quest/m1/hls-linger.md deleted file mode 100644 index 9da2c54d1c4..00000000000 --- a/quest/m1/hls-linger.md +++ /dev/null @@ -1,41 +0,0 @@ -# [S] moq-hls keeps an ended broadcast for its playlist window - -## Goal - -A player polling `moq_hls::Server` can finish the last segments of a broadcast -that just ended, and a republish of the same name takes over cleanly. Today -`Server` evicts a broadcaster as soon as its broadcast closes, so the playlist -404s mid-window. The moq.pro edge works around it with its own pool on top of -`Broadcaster` that holds an ended broadcast for the playlist window plus a -grace period and checks for a republish -([#3964](https://github.com/moq-dev/moq/pull/3964)). Once moq-hls owns this, -the edge deletes its pool. - -## Plan - -Decided: moq-hls owns the retention through an `export::Config` field (the -playlist window plus a grace period), so every embedder gets it and the edge -has nothing to duplicate. `Config` is `#[non_exhaustive]`, so the field is -additive on `main`. - -Guidance: - -- The eviction lives in `server/mod.rs` (`evict_closed` and the - `is_closed` checks in `Server::broadcaster`). An ended broadcaster keeps - serving its final playlist, marked ended if the renditions know it, until - the linger expires. -- A republish during the linger replaces the ended broadcaster. Decide - whether a request for the name resolves the new broadcast first and falls - back to the ended one only when nothing is announced; match what the edge - pool does today. -- Segments are fetched from the relay cache on request, so the linger is only - useful within the cache's retention; say so on the field, as `window` does. -- A zero linger keeps today's behavior. Pick the default with the edge's - current value in mind. -- Tests: a request inside the linger after close still gets the playlist and - a cached segment; after it expires the name 404s; a republish inside the - linger is served. - -## Related - -- [Export linger](/quest/m1/export-linger.md) - the CLI exporter's wait for a broadcast to return; same idea, separate code diff --git a/quest/m2/README.md b/quest/m2/README.md index d1a1a141c76..32dd0af66ac 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -93,3 +93,5 @@ upstream release waits in [m4](/quest/m4/README.md). - [Audio capture time](/quest/m2/audio-capture-time.md) - native audio stamps a buffer's capture instant, not when the driver reads it - [X11 capture transport](/quest/m2/x11-capture-shm.md) - move X11 capture to shared memory and RandR events instead of a per-frame socket copy - [Capture frame buffers](/quest/m2/capture-frame-buffers.md) - stop rebuilding a full-frame buffer every tick in the X11 and Windows backends + +- [Demo serve-hls renditions](/quest/m2/serve-hls-renditions.md) - `just pub serve-hls` serves 720p and 144p instead of two 256-wide copies \ No newline at end of file diff --git a/quest/m2/serve-hls-renditions.md b/quest/m2/serve-hls-renditions.md new file mode 100644 index 00000000000..9953f140a9e --- /dev/null +++ b/quest/m2/serve-hls-renditions.md @@ -0,0 +1,16 @@ +# [XS] Demo serve-hls publishes distinct renditions + +## Goal + +`just pub serve-hls` serves two renditions at different resolutions, as +`just pub hls` does. Today both come out 256 wide: the `-vf:0` and `-vf:1` +options aren't per-stream in ffmpeg, so the last filter wins. + +## Plan + +Use per-stream filters (`-filter:v:0`, `-filter:v:1`), scaled to 720p and +144p to match `hls`. Scaling the 720p source up to 1080p couldn't encode in +real time on a dev machine. The recipe body moves to `sh/demo/serve-hls.sh` +when the [tooling line](/quest/m1/tooling/README.md) lands; fix it wherever it +lives. Check it by fetching both playlists and comparing each rendition's +`RESOLUTION`. From 7db2ab9fdf040f411654d433aeef5a1e4f45360b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 15:42:40 -0700 Subject: [PATCH 061/128] quest: capture is a default feature Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 1 + quest/m1/capture-default.md | 38 +++++++++++++++++++++++++++++++++++++ 2 files changed, 39 insertions(+) create mode 100644 quest/m1/capture-default.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 5a68f4c02d9..ee5b48eb001 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -53,6 +53,7 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) - `import ts` reads a PAT or PMT that spans packets or follows a nonzero pointer_field instead of aborting, and one corrupted section costs a repetition and a counted `CRC_error`, not the import - [Same-hop importers](/quest/m1/hop-aligned-import.md) - importers sharing a `--hop` and fed one stream publish identical groups and timestamps, so failover survives - [Capture control](/quest/m1/capture-control.md) - on dev, `encode::Capture` replaces `CaptureOptions` without a `clock` field (it reads the catalog's), an unsupported `cut()` errors, and dropping the last `Control` cancels in-flight opens +- [Capture by default](/quest/m1/capture-default.md) - moq-video and moq-audio build `capture` by default, so pre-merge checks test it and the capture gate goes away - [Video surface](/quest/m1/video-surface.md) - on dev, moq-ffi's `native` becomes `surface`, refused on platforms with no surface - [HLS discontinuity sequence](/quest/m1/hls-discontinuity-sequence.md) - on dev, `Segment::discontinuity` is the absolute sequence, so every cursor agrees - [Auth client CA](/quest/m1/relay-auth-client-ca.md) - on dev, `auth::Config::validate` and `init` take the client-CA flag, so no caller can skip the check diff --git a/quest/m1/capture-default.md b/quest/m1/capture-default.md new file mode 100644 index 00000000000..8e2264afc87 --- /dev/null +++ b/quest/m1/capture-default.md @@ -0,0 +1,38 @@ +# [S] Capture is a default feature + +## Goal + +`capture` is on by default in moq-video and moq-audio, so the pre-merge +`just check` compiles and tests device capture like any other default code, +and the separate capture CI gate goes away. The flag stays so a minimal build +can opt out. Workspace consumers that set `default-features = false` (the +relay, the language bindings) keep building without it. + +## Plan + +Decided in planning (09-29), after capture-control (#4545) found that +pre-merge `just check` never runs moq-video's `capture` tests: + +- **Default-on, keep the flag.** Removing the flag was rejected: consumers + that don't want device stacks would pay for them. +- moq-video's `capture` already costs nothing to build on any platform. Its + Cargo comment says it stays off only "until every distribution ships it", a + packaging concern this reverses. +- moq-audio's `capture` links libasound when it builds on Linux, which is why + it depends on [ALSA link](/quest/m1/capture-alsa-link.md). Once libasound + loads at runtime, the default costs no system library. +- Delete the special capture gate (`rs capture`, `capture-test`, and the + capture branch in `sh/rs/select.sh` on the tooling line) once default + `just check` covers it. Keep the platform jobs (`just rs macos`, + `just rs windows`). +- Update the Cargo feature comments, moq-cli's `capture` feature (it may + become redundant), and `doc/` wherever capture is described as opt-in. + +Verify: `just check` on a moq-video or moq-audio change runs the capture +tests, and a `default-features = false` consumer (for example +`cargo tree -p moq-ffi -e features`) pulls no capture dependency. + +## Required + +- [Tooling](/quest/m1/tooling/README.md) - rewrites the capture gate this deletes +- [ALSA link](/quest/m1/capture-alsa-link.md) - moq-audio capture can't be on by default while it links libasound at build time From 47674390692111507cb183956587d0bb294c4076 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 15:43:07 -0700 Subject: [PATCH 062/128] feat(ffi): Python, Go, and Dart print MoqError's Rust message (#4433) Co-authored-by: Claude Opus 5.5 --- .github/workflows/release-go-ffi.yml | 4 +- dart/README.md | 9 +- dart/moq_ffi/lib/src/moq.dart | 160 +++--------------- dart/moq_ffi/test/smoke_test.dart | 5 + doc/lib/dart/index.md | 3 +- doc/lib/go/index.md | 2 +- doc/lib/kt/index.md | 4 +- doc/lib/py/index.md | 2 +- doc/lib/swift/index.md | 3 +- flake.nix | 19 ++- go/ffi/README.md | 4 +- go/scripts/check-errors.sh | 2 +- go/scripts/check.sh | 2 +- go/scripts/stage.sh | 2 +- go/wrapper/errors_test.go | 21 +++ .../kotlin/dev/moq/ffi/BindingsSmokeTest.kt | 7 + py/moq-rs/moq/errors.py | 20 +++ py/moq-rs/pyproject.toml | 10 +- py/moq-rs/tests/test_local.py | 7 + quest/m1/README.md | 1 - quest/m1/error-display.md | 34 ---- quest/m3/upstream-forks.md | 9 +- rs/moq-ffi/build.sh | 2 +- rs/moq-ffi/src/error.rs | 3 + swift/Tests/MoqTests/SmokeTests.swift | 6 + 25 files changed, 131 insertions(+), 210 deletions(-) delete mode 100644 quest/m1/error-display.md diff --git a/.github/workflows/release-go-ffi.yml b/.github/workflows/release-go-ffi.yml index f7db014cd46..30c3ea56edd 100644 --- a/.github/workflows/release-go-ffi.yml +++ b/.github/workflows/release-go-ffi.yml @@ -35,9 +35,9 @@ concurrency: env: # A fork until NordSecurity ships a uniffi 0.32 generator; see flake.nix. - # The revision is v0.9.0+v0.32.0. + # The revision is v0.10.0-kixelated.1+v0.32.0. UNIFFI_BINDGEN_GO_REPO: https://github.com/kixelated/uniffi-bindgen-go - UNIFFI_BINDGEN_GO_REV: v0.9.0+v0.32.0 + UNIFFI_BINDGEN_GO_REV: v0.10.0-kixelated.1+v0.32.0 jobs: parse-version: diff --git a/dart/README.md b/dart/README.md index 466876666c1..8feee4745f7 100644 --- a/dart/README.md +++ b/dart/README.md @@ -20,13 +20,14 @@ WebAssembly. Browser applications should use the TypeScript packages. ## Generator Bindings use [`kixelated/uniffi-dart`](https://github.com/kixelated/uniffi-dart) -tag `v0.3.0+v0.32.0`, which carries the UniFFI 0.32 and library-mode CLI -changes. The Nix development shell supplies that exact revision. Without Nix, -install it with: +tag `v0.3.1-kixelated.5+v0.32.0`, which carries the UniFFI 0.32 and +library-mode CLI changes. The Nix development shell supplies that exact +revision plus `nix/uniffi-dart-record-error.patch`. Without Nix, install it +with: ```bash cargo install --git https://github.com/kixelated/uniffi-dart \ - --tag 'v0.3.0+v0.32.0' --features binary uniffi-dart + --tag 'v0.3.1-kixelated.5+v0.32.0' --features binary uniffi-dart ``` ## Releases diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index a79ae74b9a4..e4d5f7532b5 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -8,7 +8,9 @@ import "dart:ffi"; import "dart:io" show Platform, File, Directory; import "dart:isolate"; import "dart:typed_data"; + import "package:ffi/ffi.dart"; + import "uniffi_runtime.dart"; export "uniffi_runtime.dart"; @@ -2107,6 +2109,16 @@ abstract class MoqException implements Exception { RustBuffer lower(); int allocationSize(); int write(Uint8List buf); + @override + String toString() { + return rustCallWithLifter( + (status) => uniffi_moq_ffi_fn_method_moqerror_uniffi_trait_display( + FfiConverterMoqException.lower(this), + status, + ), + FfiConverterString.lift, + ); + } } class FfiConverterMoqException { @@ -2343,11 +2355,6 @@ class ProtocolMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "ProtocolMoqException($details)"; - } } class TransportMoqException extends MoqException { @@ -2386,11 +2393,6 @@ class TransportMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "TransportMoqException($v0)"; - } } class InternalMoqException extends MoqException { @@ -2429,11 +2431,6 @@ class InternalMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "InternalMoqException($v0)"; - } } class MediaMoqException extends MoqException { @@ -2472,11 +2469,6 @@ class MediaMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "MediaMoqException($v0)"; - } } class MuxMoqException extends MoqException { @@ -2515,11 +2507,6 @@ class MuxMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "MuxMoqException($v0)"; - } } class JsonTrackMoqException extends MoqException { @@ -2558,11 +2545,6 @@ class JsonTrackMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "JsonTrackMoqException($v0)"; - } } class UrlMoqException extends MoqException { @@ -2601,11 +2583,6 @@ class UrlMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "UrlMoqException($v0)"; - } } class TimeOverflowMoqException extends MoqException { @@ -2634,11 +2611,6 @@ class TimeOverflowMoqException extends MoqException { int new_offset = buf.offsetInBytes + 4; return new_offset; } - - @override - String toString() { - return "TimeOverflowMoqException"; - } } class LogLevelMoqException extends MoqException { @@ -2677,11 +2649,6 @@ class LogLevelMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "LogLevelMoqException($v0)"; - } } class TaskMoqException extends MoqException { @@ -2720,11 +2687,6 @@ class TaskMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "TaskMoqException($v0)"; - } } class JsonMoqException extends MoqException { @@ -2763,11 +2725,6 @@ class JsonMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "JsonMoqException($v0)"; - } } class CancelledMoqException extends MoqException { @@ -2796,11 +2753,6 @@ class CancelledMoqException extends MoqException { int new_offset = buf.offsetInBytes + 4; return new_offset; } - - @override - String toString() { - return "CancelledMoqException"; - } } class ClosedMoqException extends MoqException { @@ -2829,11 +2781,6 @@ class ClosedMoqException extends MoqException { int new_offset = buf.offsetInBytes + 4; return new_offset; } - - @override - String toString() { - return "ClosedMoqException"; - } } class BusyMoqException extends MoqException { @@ -2862,11 +2809,6 @@ class BusyMoqException extends MoqException { int new_offset = buf.offsetInBytes + 4; return new_offset; } - - @override - String toString() { - return "BusyMoqException"; - } } class ConnectMoqException extends MoqException { @@ -2905,11 +2847,6 @@ class ConnectMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "ConnectMoqException($v0)"; - } } class BindMoqException extends MoqException { @@ -2948,11 +2885,6 @@ class BindMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "BindMoqException($v0)"; - } } class RejectMoqException extends MoqException { @@ -2991,11 +2923,6 @@ class RejectMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "RejectMoqException($v0)"; - } } class AlreadyRespondedMoqException extends MoqException { @@ -3024,11 +2951,6 @@ class AlreadyRespondedMoqException extends MoqException { int new_offset = buf.offsetInBytes + 4; return new_offset; } - - @override - String toString() { - return "AlreadyRespondedMoqException"; - } } class CodecMoqException extends MoqException { @@ -3067,11 +2989,6 @@ class CodecMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "CodecMoqException($v0)"; - } } class UnauthorizedMoqException extends MoqException { @@ -3100,11 +3017,6 @@ class UnauthorizedMoqException extends MoqException { int new_offset = buf.offsetInBytes + 4; return new_offset; } - - @override - String toString() { - return "UnauthorizedMoqException"; - } } class ForbiddenMoqException extends MoqException { @@ -3133,11 +3045,6 @@ class ForbiddenMoqException extends MoqException { int new_offset = buf.offsetInBytes + 4; return new_offset; } - - @override - String toString() { - return "ForbiddenMoqException"; - } } class NotFoundMoqException extends MoqException { @@ -3166,11 +3073,6 @@ class NotFoundMoqException extends MoqException { int new_offset = buf.offsetInBytes + 4; return new_offset; } - - @override - String toString() { - return "NotFoundMoqException"; - } } class UnsupportedMoqException extends MoqException { @@ -3199,11 +3101,6 @@ class UnsupportedMoqException extends MoqException { int new_offset = buf.offsetInBytes + 4; return new_offset; } - - @override - String toString() { - return "UnsupportedMoqException"; - } } class AlreadyCommittedMoqException extends MoqException { @@ -3232,11 +3129,6 @@ class AlreadyCommittedMoqException extends MoqException { int new_offset = buf.offsetInBytes + 4; return new_offset; } - - @override - String toString() { - return "AlreadyCommittedMoqException"; - } } class InvalidRouteMoqException extends MoqException { @@ -3275,11 +3167,6 @@ class InvalidRouteMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "InvalidRouteMoqException($v0)"; - } } class InvalidPatternMoqException extends MoqException { @@ -3318,11 +3205,6 @@ class InvalidPatternMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "InvalidPatternMoqException($v0)"; - } } class UnresolvableBroadcastMoqException extends MoqException { @@ -3361,11 +3243,6 @@ class UnresolvableBroadcastMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "UnresolvableBroadcastMoqException($v0)"; - } } class LogMoqException extends MoqException { @@ -3404,11 +3281,6 @@ class LogMoqException extends MoqException { ); return new_offset; } - - @override - String toString() { - return "LogMoqException($v0)"; - } } class MoqExceptionErrorHandler extends UniffiRustCallStatusErrorHandler { @@ -11667,6 +11539,14 @@ external Pointer uniffi_moq_ffi_fn_method_moqsession_status( Pointer ptr, ); +@Native)>( + assetId: _uniffiAssetId, +) +external RustBuffer uniffi_moq_ffi_fn_method_moqerror_uniffi_trait_display( + RustBuffer ptr, + Pointer uniffiStatus, +); + @Native)>( assetId: _uniffiAssetId, ) diff --git a/dart/moq_ffi/test/smoke_test.dart b/dart/moq_ffi/test/smoke_test.dart index 0782864a596..6265d206fd6 100644 --- a/dart/moq_ffi/test/smoke_test.dart +++ b/dart/moq_ffi/test/smoke_test.dart @@ -28,6 +28,11 @@ void main() { ); }); + test('an exception prints the Rust error message', () { + expect(ClosedMoqException().toString(), 'closed'); + expect(TransportMoqException('reset').toString(), 'transport: reset'); + }); + test('raw track round trips a frame', () async { final broadcast = MoqBroadcastProducer(); final track = broadcast.publishTrack(name: 'events', info: null); diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index 36c7d263194..feb90f7b5d3 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -97,7 +97,8 @@ Cancelling a stream releases the native cursor. The package re-exports Generated configuration setters throw if a connect, listen, or accept is in flight, or after `cancel()`. Incoming requests report a `MoqTransport` enum. `ProtocolMoqException` carries a `MoqProtocolException` as `details` (scope, verbatim -code, kind) when the peer sent a session or stream code. +code, kind) when the peer sent a session or stream code. An exception's +`toString()` is the Rust error message. `moq.bandwidth()` divides the connection's send estimate; `reserve` a share for an app-owned encoder so several publishers on one session split the diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index 2743da61f56..040558a94d5 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -122,7 +122,7 @@ of the [shared feature list](/lib/#what-every-binding-can-do) maps one to one: `FetchGroup`/`FetchMediaGroup`, `Dynamic()` with `Requests(ctx)`, `Session.Bandwidth()` to divide the send estimate, `AppendDatagram`/`Datagrams(ctx)`, `SetCatalogSection`, `Demand()` for `Used`/`Unused`, -`Session().Stats()`. `moq.IsAuthError` and `moq.IsShutdown` classify errors. `moq.ProtocolError(err)` is the structured protocol failure (scope, verbatim code, kind) when the peer sent one. +`Session().Stats()`. `moq.IsAuthError` and `moq.IsShutdown` classify errors. `moq.ProtocolError(err)` is the structured protocol failure (scope, verbatim code, kind) when the peer sent one. `err.Error()` is the Rust error message. `DecodeVideo` picks the decoded CPU pixel layout: `VideoDecoderOutput.Format` is I420 when nil, or `VideoPixelFormatRgba` for four bytes a pixel, and every diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index d4b76efbc21..b0581661009 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -91,8 +91,8 @@ connection's send estimate; pass it to `encodeVideo` / `encodeAudio` or `reserve` a share for an app-owned track. `MoqException.isAuth` and `isShutdown` classify errors. Microsecond fields read back as a `kotlin.time.Duration`: `stats.rtt`, `backoff.initial`, `frame.timestamp`. `protocolError` is the structured protocol failure -(scope, verbatim code, kind) when the peer sent one. Cancelling the collecting coroutine cancels the -native side. +(scope, verbatim code, kind) when the peer sent one. An exception's `toString()` is the Rust error message. +Cancelling the collecting coroutine cancels the native side. `encodeAudio` encodes raw PCM inside the binding. Its codec is an object, `AudioCodec.opus()`, and `AudioEncoderOutput.frameDurationUs` sets the Opus diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index 609f957aee3..a7d3e1d0f65 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -106,7 +106,7 @@ and a producer's `demand()`, a `TrackDemand` whose `used()`/`unused()` let capture idle when nobody is subscribed. `request.set_publish`/`set_consume` raise if the request is already answered, cancelled, or currently accepting. `session.bandwidth()` divides the connection's send estimate; pass it to `encode_video` / `encode_audio` or `reserve` a share for an -app-owned track. `moq.is_auth(err)` and `moq.is_shutdown(err)` classify errors. `moq.protocol_error(err)` is the structured protocol failure (scope, verbatim code, kind) when the peer sent one. Catch `moq.Error.Busy` when a setter races an in-flight connect, listen, or accept. +app-owned track. `moq.is_auth(err)` and `moq.is_shutdown(err)` classify errors. `moq.protocol_error(err)` is the structured protocol failure (scope, verbatim code, kind) when the peer sent one. `str(err)` is the Rust error message. Catch `moq.Error.Busy` when a setter races an in-flight connect, listen, or accept. Each server request reports a `moq.Transport` enum, including QUIC, Iroh, WebSocket, TCP, and Unix sockets. diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index 8cc2695afe1..fb941054928 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -96,7 +96,8 @@ to one: `fetchGroup`/`fetchMediaGroup`, `dynamic()` for tracks and `dynamic(pref divides the connection's send estimate; pass it to `encodeVideo` / `encodeAudio` or `reserve` a share for an app-owned track. `MoqError.isAuth` and `isShutdown` classify errors. `protocolError` is the structured protocol failure -(scope, verbatim code, kind) when the peer sent one. +(scope, verbatim code, kind) when the peer sent one. An error's `description` is +the Rust error message. `encodeAudio` encodes raw PCM inside the binding. Its codec is an object, `AudioCodec.opus()`, and `AudioEncoderOutput.frameDurationUs` sets the Opus diff --git a/flake.nix b/flake.nix index bf676502d6b..3529312a1e4 100644 --- a/flake.nix +++ b/flake.nix @@ -272,8 +272,8 @@ # check` skips itself, which reads as a pass in CI. # # The tag pairs the generator's own version with the uniffi release it - # targets (v0.9.0+v0.32.0 -> uniffi 0.32), and it only understands - # metadata emitted by that uniffi, so it moves with the `uniffi` + # targets (v0.10.0-kixelated.1+v0.32.0 -> uniffi 0.32), and it only + # understands metadata emitted by that uniffi, so it moves with the `uniffi` # dependency in rs/moq-ffi/Cargo.toml. Five other places name the same # generator version and must be bumped together: the repo and revision # in release-go-ffi.yml, and the `cargo install` line in @@ -284,20 +284,21 @@ # uniffi 0.32 generator: the metadata encoding changed in 0.32 even # though the contract version did not, so v0.7.1+v0.31.0 fails to read a # 0.32-built cdylib at all. The fork carries the port, tracked upstream - # as NordSecurity/uniffi-bindgen-go#96. Move back to NordSecurity once - # they tag a 0.32 release. + # as NordSecurity/uniffi-bindgen-go#96, and renders an enum error's + # exported Display as its Error(). Move back to NordSecurity once they + # tag a 0.32 release carrying both. uniffi-bindgen-go = pkgs.rustPlatform.buildRustPackage rec { pname = "uniffi-bindgen-go"; - version = "0.9.0+v0.32.0"; + version = "0.10.0-kixelated.1+v0.32.0"; src = pkgs.fetchFromGitHub { owner = "kixelated"; repo = "uniffi-bindgen-go"; rev = "v${version}"; - hash = "sha256-7Hli9SmLknZe5p7iGYsRNxmUL6ovKL2jhX62Z/79K4o="; + hash = "sha256-0DCIgHt4R5ndtLkeXw/KF500HidB13L2HeuS4eLvLHU="; }; - cargoHash = "sha256-ecpo/Z9hc3oPt/pF9Y+EB6SZANR8TDOJR6f/xSzJ9Uw="; + cargoHash = "sha256-wD+5Ghd4WFFQWAY2PXedXVPG+oPGozG9HbOhXB0fWco="; # The tag is a virtual workspace whose other members are uniffi test # fixtures. Building from the root would compile all of them, and CI @@ -323,13 +324,13 @@ # `-kixelated.N` pre-release so they never collide with upstream's. uniffi-bindgen-dart = pkgs.rustPlatform.buildRustPackage rec { pname = "uniffi-bindgen-dart"; - version = "0.3.1-kixelated.4+v0.32.0"; + version = "0.3.1-kixelated.5+v0.32.0"; src = pkgs.fetchFromGitHub { owner = "kixelated"; repo = "uniffi-dart"; rev = "v${version}"; - hash = "sha256-BCIooajAp0Wqt7LeanFSdmS/GT0uYo+d8Qv2jGWCJD8="; + hash = "sha256-MobLv4aov+ySk3X8bd6Sr5MLiXxCprkoFqEFt5xOerw="; }; # The upstream repository ignores Cargo.lock so cargo installs test diff --git a/go/ffi/README.md b/go/ffi/README.md index 23aae8b0253..64a12a712ef 100644 --- a/go/ffi/README.md +++ b/go/ffi/README.md @@ -29,13 +29,13 @@ The dev shell provides both `go` and `uniffi-bindgen-go`, so `nix develop --comm ```bash cargo install uniffi-bindgen-go \ --git https://github.com/kixelated/uniffi-bindgen-go \ - --rev v0.9.0+v0.32.0 \ + --rev v0.10.0-kixelated.1+v0.32.0 \ --locked ``` `--locked` matters: `uniffi_bindgen` depends on `toml` across a `>=0.9, <2` range, so a fresh resolve can pick a different `toml` than the generator was built against. -The revision is `v0.9.0+v0.32.0`, matching the `uniffi` version `rs/moq-ffi` depends on; `flake.nix` pins the same source. It points at a fork because upstream has no uniffi 0.32 release yet; `flake.nix` carries the details. Generated async calls take `context.Context` as the first argument. +The revision is `v0.10.0-kixelated.1+v0.32.0`, matching the `uniffi` version `rs/moq-ffi` depends on; `flake.nix` pins the same source. It points at a fork because upstream has no uniffi 0.32 release yet; `flake.nix` carries the details. Generated async calls take `context.Context` as the first argument. ## Layout diff --git a/go/scripts/check-errors.sh b/go/scripts/check-errors.sh index 4717ea8dcfb..f5e6595ef21 100755 --- a/go/scripts/check-errors.sh +++ b/go/scripts/check-errors.sh @@ -7,7 +7,7 @@ TEST=$3 generated=$(sed -n 's/^var \(ErrMoqError[[:alnum:]]*\) =.*/\1/p' "$GENERATED" | sort) wrapped=$(sed -n 's/^[[:space:]]*Err[[:alnum:]]* = ffi\.\(ErrMoqError[[:alnum:]]*\)$/\1/p' "$WRAPPER" | sort) -tested=$(sed -n 's/.*ffi\.New\(MoqError[[:alnum:]]*\)(.*/Err\1/p' "$TEST" | sort) +tested=$(sed -n 's/.*ffi\.New\(MoqError[[:alnum:]]*\)(.*/Err\1/p' "$TEST" | sort -u) if [[ -z "$generated" || -z "$wrapped" || -z "$tested" ]]; then echo "go check: failed to discover MoqError sentinels" >&2 diff --git a/go/scripts/check.sh b/go/scripts/check.sh index 5f5901c0a78..46f39f23afc 100755 --- a/go/scripts/check.sh +++ b/go/scripts/check.sh @@ -30,7 +30,7 @@ if ! command -v cargo >/dev/null 2>&1; then fi if ! command -v uniffi-bindgen-go >/dev/null 2>&1; then echo "go check: uniffi-bindgen-go not on PATH, skipping" >&2 - echo " install: cargo install uniffi-bindgen-go --git https://github.com/kixelated/uniffi-bindgen-go --rev v0.9.0+v0.32.0 --locked" >&2 + echo " install: cargo install uniffi-bindgen-go --git https://github.com/kixelated/uniffi-bindgen-go --rev v0.10.0-kixelated.1+v0.32.0 --locked" >&2 exit 0 fi diff --git a/go/scripts/stage.sh b/go/scripts/stage.sh index 3fcde904108..dcb09e22897 100755 --- a/go/scripts/stage.sh +++ b/go/scripts/stage.sh @@ -57,7 +57,7 @@ command -v cargo >/dev/null 2>&1 || { } command -v uniffi-bindgen-go >/dev/null 2>&1 || { echo "go stage: uniffi-bindgen-go not on PATH" >&2 - echo " install: cargo install uniffi-bindgen-go --git https://github.com/kixelated/uniffi-bindgen-go --rev v0.9.0+v0.32.0 --locked" >&2 + echo " install: cargo install uniffi-bindgen-go --git https://github.com/kixelated/uniffi-bindgen-go --rev v0.10.0-kixelated.1+v0.32.0 --locked" >&2 exit 1 } diff --git a/go/wrapper/errors_test.go b/go/wrapper/errors_test.go index aa5fe25d66d..360e8e98f60 100644 --- a/go/wrapper/errors_test.go +++ b/go/wrapper/errors_test.go @@ -30,6 +30,27 @@ func TestStreamAbortProtocolDetails(t *testing.T) { } } +func TestErrorMessage(t *testing.T) { + tests := []struct { + err error + want string + }{ + {ffi.NewMoqErrorClosed(), "closed"}, + {ffi.NewMoqErrorTransport("reset"), "transport: reset"}, + {ffi.NewMoqErrorProtocol(ffi.MoqProtocolError{ + Scope: ffi.MoqErrorScopeStream, + Code: 468, + Kind: ffi.MoqProtocolKindApp, + Message: "gone", + }), "gone"}, + } + for _, test := range tests { + if got := test.err.Error(); got != test.want { + t.Errorf("Error() = %q, want %q", got, test.want) + } + } +} + func TestErrorSentinels(t *testing.T) { tests := []struct { name string diff --git a/kt/moq-ffi/src/jvmAndAndroidTest/kotlin/dev/moq/ffi/BindingsSmokeTest.kt b/kt/moq-ffi/src/jvmAndAndroidTest/kotlin/dev/moq/ffi/BindingsSmokeTest.kt index 08603e68bc2..ebc481b3dd1 100644 --- a/kt/moq-ffi/src/jvmAndAndroidTest/kotlin/dev/moq/ffi/BindingsSmokeTest.kt +++ b/kt/moq-ffi/src/jvmAndAndroidTest/kotlin/dev/moq/ffi/BindingsSmokeTest.kt @@ -6,6 +6,7 @@ import uniffi.moq.MoqException import uniffi.moq.MoqOriginConfig import uniffi.moq.MoqOriginProducer import kotlin.test.Test +import kotlin.test.assertEquals import kotlin.test.assertFailsWith /** @@ -24,6 +25,12 @@ class BindingsSmokeTest { } } + @Test + fun `an exception prints the Rust error message`() { + assertEquals("closed", MoqException.Closed().toString()) + assertEquals("transport: reset", MoqException.Transport("reset").toString()) + } + @Test fun `origin producer constructs and consumes`() = runTest { MoqOriginProducer(MoqOriginConfig()).use { origin -> diff --git a/py/moq-rs/moq/errors.py b/py/moq-rs/moq/errors.py index 73cc48f7367..ecc76a8b928 100644 --- a/py/moq-rs/moq/errors.py +++ b/py/moq-rs/moq/errors.py @@ -3,10 +3,30 @@ from __future__ import annotations from moq_ffi import MoqError, MoqProtocolKind +from moq_ffi._uniffi.moq import ( + _uniffi_rust_call, + _UniffiFfiConverterString, + _UniffiFfiConverterTypeMoqError, + _UniffiLib, +) from .types import ProtocolError +def _display(self: MoqError) -> str: + # moq-ffi exports MoqError's Display, but upstream uniffi's Python template + # renders no traits on errors, so call the exported method directly. + return _UniffiFfiConverterString.lift( + _uniffi_rust_call( + _UniffiLib.uniffi_moq_ffi_fn_method_moqerror_uniffi_trait_display, + _UniffiFfiConverterTypeMoqError.lower(self), + ) + ) + + +MoqError.__str__ = _display + + def is_shutdown(err: BaseException) -> bool: """True for `Cancelled` and `Closed`, which arise from graceful shutdown rather than actual failures. diff --git a/py/moq-rs/pyproject.toml b/py/moq-rs/pyproject.toml index 71c3999f462..d638ca09cca 100644 --- a/py/moq-rs/pyproject.toml +++ b/py/moq-rs/pyproject.toml @@ -28,11 +28,11 @@ classifiers = [ "Topic :: Multimedia :: Sound/Audio", "Topic :: Multimedia :: Video", ] -# Compatible-release pin: floats to the latest 0.3.x moq-ffi patch without a -# wrapper re-release. A moq-ffi minor bump (0.4) is the only thing that forces -# bumping this constraint. Floor is 0.4.3, the first release with the WebSocket -# fallback setters. -dependencies = ["moq-ffi ~= 0.4.3"] +# Compatible-release pin: floats to the latest 0.4.x moq-ffi patch without a +# wrapper re-release. A moq-ffi minor bump (0.5) is the only thing that forces +# bumping this constraint. Floor is 0.4.9, the first release that exports +# MoqError's Display, which `moq.errors` calls for `str(err)`. +dependencies = ["moq-ffi ~= 0.4.9"] [project.urls] Homepage = "https://github.com/moq-dev/moq" diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index 9f09dd57bfb..bd6810046a1 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -122,6 +122,13 @@ def test_protocol_error_helper_covers_known_app_and_unknown(): assert moq.protocol_error(RuntimeError("nope")) is None +def test_error_str_is_rust_display(): + assert str(moq.Error.Closed()) == "closed" # type: ignore[attr-defined] + assert str(moq.Error.Transport("reset")) == "transport: reset" # type: ignore[attr-defined] + details = moq.ProtocolError(scope=moq.ErrorScope.STREAM, code=468, kind=moq.ProtocolKind.APP, message="gone") + assert str(moq.Error.Protocol(details)) == "gone" # type: ignore[attr-defined] + + def test_publish_media_lifecycle(): broadcast = moq.BroadcastProducer() media = broadcast.publish_audio(moq.AudioFormat.OPUS, opus_head()) diff --git a/quest/m1/README.md b/quest/m1/README.md index 4b9ac7a8f1e..f16bd7f1d75 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -23,7 +23,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Binding audio delay](/quest/m1/binding-surface.md) - moq-ffi and every wrapper configure and observe audio playout delay - [FFI shape](/quest/m1/ffi-shape/README.md) - the bindings mirror Rust's layers: net at the root, then media, json, flate, audio, and video namespaces built from the handle below - [Track demand](/quest/m1/track-demand.md) - Rust and JS watch a track's subscribers through `demand()` alone -- [Error messages](/quest/m1/error-display.md) - Python, Go, and Dart print `MoqError` with Rust's message, as Kotlin and Swift do - [Session close](/quest/m1/session-close.md) - a graceful session end withdraws announces and waits one second for the ack - [Graceful close in bindings](/quest/m1/bindings-graceful-close.md) - on dev, `shutdown` drains a session in moq-ffi and every wrapper like Rust, so the wrappers keep the tail of a publish - [Close codes](/quest/m1/close-codes.md) - a client sees the peer's application close code over WebSocket and raw QUIC, like WebTransport diff --git a/quest/m1/error-display.md b/quest/m1/error-display.md deleted file mode 100644 index 894f3581d0d..00000000000 --- a/quest/m1/error-display.md +++ /dev/null @@ -1,34 +0,0 @@ -# [M] Every binding prints MoqError's message - -## Goal - -Python's `str(err)`, Go's `err.Error()`, and Dart's `toString()` on a -`MoqError` return the message from moq-ffi's exported `Display`, as Kotlin's -`toString()` and Swift's `description` already do. No hand-written -per-variant strings and no extra message function. - -## Plan - -- #4292 adds `#[uniffi::export(Display)]` on `MoqError` in - `rs/moq-ffi/src/error.rs`, on the C++ line. If it has not reached `main` - when this starts, add the same attribute here; it is additive. -- Go and Dart are fixed in their generators; Python in its wrapper: - - Go: the `kixelated/uniffi-bindgen-go` fork. The generated `Error()` prints - `MoqError: `. Render the exported `Display` for errors, tag, and - bump every pin site the `flake.nix` comment lists. - - Dart: the `kixelated/uniffi-dart` fork. The regenerated bindings already - carry the unused extern; wire it to `toString()`, tag, bump `flake.nix`, - and regenerate `dart/moq_ffi`. - - Python: upstream `mozilla/uniffi-rs` (0.32.2 here) renders no uniffi - traits on errors (`ErrorTemplate.py`). Settled: no upstream PR. The - hand-written `py/moq-rs` package defines `__str__` on `MoqError` by - calling the exported `Display`, so the message still comes from Rust. -- A test per binding that a known error prints Rust's text (`Closed` prints - `closed`), and `doc/lib/{py,go,dart}` updated where they show error output. - -Public API: the string form of `MoqError` changes in Python, Go, and Dart. -Wire: none. - -## Related - -- [C++ through moq-ffi](/quest/m1/cpp/README.md) - where #4292 adds the export and C++ `to_string()` diff --git a/quest/m3/upstream-forks.md b/quest/m3/upstream-forks.md index 45856ec20ed..61debd6e692 100644 --- a/quest/m3/upstream-forks.md +++ b/quest/m3/upstream-forks.md @@ -25,7 +25,11 @@ One outcome per candidate: allocate a `ForeignBytes` nothing frees; the free belongs after the call, not inside the lowering), and audit callback interfaces for the same RustBuffer leak, so the upstream offer is complete. `moq_ffi` uses neither - today. + today. Also the enum `toString()` from an exported `Display` + (kixelated/uniffi-dart#6). +- **uniffi-bindgen-go** (`kixelated/uniffi-bindgen-go`): an enum error's + `Error()` from its exported `Display`, with the `DisplayError` fixture. + The uniffi 0.32 port is NordSecurity/uniffi-bindgen-go#96. - **uniffi-rs Python typing** of data-carrying enum variants ([#4049](https://github.com/moq-dev/moq/pull/4049)): the generated type makes `moq.VideoEncoderKind.AUTO()` fail pyright, so @@ -39,8 +43,7 @@ One outcome per candidate: `v0.11.0-kixelated.1+v0.32.2`, matching the Dart fork. It never collides with an upstream tag. Under SemVer a pre-release sorts before its base, so this only works because every pin names the exact tag; never let tooling - pick "the newest" fork tag (Codex on #4307). The Go fork (`v0.9.0+v0.32.0`) moves to it - at its next bump. + pick "the newest" fork tag (Codex on #4307). - Offer each fix with the regression test it landed with. When upstream merges one, move the pin in `flake.nix` (and the places its comment lists) and delete the carried patch. diff --git a/rs/moq-ffi/build.sh b/rs/moq-ffi/build.sh index 75342c3f08a..ef8ef928f89 100755 --- a/rs/moq-ffi/build.sh +++ b/rs/moq-ffi/build.sh @@ -172,7 +172,7 @@ generate_bindings() { # Go uses a separate, third-party bindgen. Upstream has no uniffi 0.32 # release yet, so install the compatible generator fork with: - # cargo install --locked uniffi-bindgen-go --git https://github.com/kixelated/uniffi-bindgen-go --rev v0.9.0+v0.32.0 + # cargo install --locked uniffi-bindgen-go --git https://github.com/kixelated/uniffi-bindgen-go --rev v0.10.0-kixelated.1+v0.32.0 if command -v uniffi-bindgen-go >/dev/null 2>&1; then echo " Generating go bindings..." uniffi-bindgen-go --library "$lib_path" --out-dir "$OUTPUT_DIR/bindings/go" diff --git a/rs/moq-ffi/src/error.rs b/rs/moq-ffi/src/error.rs index cce70fb82f7..30e370dbbf5 100644 --- a/rs/moq-ffi/src/error.rs +++ b/rs/moq-ffi/src/error.rs @@ -150,7 +150,10 @@ fn stream_kind(err: &moq_net::StreamError) -> MoqProtocolKind { } /// Error returned by all UniFFI-exported functions. +/// +/// Exports `Display`, which the bindings surface as the error's string form. #[derive(Debug, thiserror::Error, uniffi::Error)] +#[uniffi::export(Display)] #[non_exhaustive] pub enum MoqError { /// A protocol failure carrying the peer's session or stream code. diff --git a/swift/Tests/MoqTests/SmokeTests.swift b/swift/Tests/MoqTests/SmokeTests.swift index 38485871e1d..f1ff4b8ea4f 100644 --- a/swift/Tests/MoqTests/SmokeTests.swift +++ b/swift/Tests/MoqTests/SmokeTests.swift @@ -21,6 +21,12 @@ final class SmokeTests: XCTestCase { } } + /// An error's description is the Rust error message. + func testErrorDescriptionIsRustMessage() { + XCTAssertEqual(MoqError.Closed.description, "closed") + XCTAssertEqual(MoqError.Transport("reset").description, "transport: reset") + } + /// Verifies the native lib loads and the wrapper compiles against the /// generated API. No network needed: we just instantiate a few types and /// exercise the cancel path. From 7fac11b2ff87f932c973303d1fb05efadca4aab5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 15:50:34 -0700 Subject: [PATCH 063/128] docs(agents): a broadcast, track, or group name always means the same content Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 3618479e56e..15b5547d3fa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,6 +60,7 @@ A bad shape costs a breaking change in every language, and the surface is huge. - Keep things private until a consumer needs them. Scrutinize every new exported item. - Never add `foo_with_x`, `foo_checked`, or a compatibility shim. Make the breaking change to `foo` on `dev` instead. Additive changes stay on `main`. - Let the type system make misuse unrepresentable +- A broadcast, track, or group name always means the same content. MoQ has no ETag-style invalidation, so a publisher that reuses a name for different content (such as restarting group numbers) is a bug; publish a new broadcast instead of working around it. - Avoid callback parameters. Return a handle, an event, or a Producer/Consumer split. - Avoid 4+ args; use a struct or object. - Name by role, not today's implementation. From 87c27c7564215efc51744203b32281674f66b78f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 15:54:40 -0700 Subject: [PATCH 064/128] quest: check serve-hls resolutions in the master playlist Co-Authored-By: Claude Opus 5.5 --- quest/m2/README.md | 3 +-- quest/m2/serve-hls-renditions.md | 4 ++-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/quest/m2/README.md b/quest/m2/README.md index 32dd0af66ac..95f08456402 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -93,5 +93,4 @@ upstream release waits in [m4](/quest/m4/README.md). - [Audio capture time](/quest/m2/audio-capture-time.md) - native audio stamps a buffer's capture instant, not when the driver reads it - [X11 capture transport](/quest/m2/x11-capture-shm.md) - move X11 capture to shared memory and RandR events instead of a per-frame socket copy - [Capture frame buffers](/quest/m2/capture-frame-buffers.md) - stop rebuilding a full-frame buffer every tick in the X11 and Windows backends - -- [Demo serve-hls renditions](/quest/m2/serve-hls-renditions.md) - `just pub serve-hls` serves 720p and 144p instead of two 256-wide copies \ No newline at end of file +- [Demo serve-hls renditions](/quest/m2/serve-hls-renditions.md) - `just pub serve-hls` serves 720p and 144p instead of two 256-wide copies diff --git a/quest/m2/serve-hls-renditions.md b/quest/m2/serve-hls-renditions.md index 9953f140a9e..3e86c953bc0 100644 --- a/quest/m2/serve-hls-renditions.md +++ b/quest/m2/serve-hls-renditions.md @@ -12,5 +12,5 @@ Use per-stream filters (`-filter:v:0`, `-filter:v:1`), scaled to 720p and 144p to match `hls`. Scaling the 720p source up to 1080p couldn't encode in real time on a dev machine. The recipe body moves to `sh/demo/serve-hls.sh` when the [tooling line](/quest/m1/tooling/README.md) lands; fix it wherever it -lives. Check it by fetching both playlists and comparing each rendition's -`RESOLUTION`. +lives. Check it by fetching `master.m3u8` and comparing the two renditions' +`RESOLUTION` attributes. From 8b6abc0a13486325c30304bdec7c50de5240c7e5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 15:55:30 -0700 Subject: [PATCH 065/128] fix(watch): park audio for a delay rise instead of flushing the ring (#4529) Co-authored-by: Claude Opus 5.5 --- js/watch/src/audio/buffer.test.ts | 28 ++++++ js/watch/src/audio/buffer.ts | 7 +- js/watch/src/audio/decoder.ts | 42 +------- js/watch/src/audio/latency.test.ts | 13 +-- js/watch/src/audio/latency.ts | 18 ---- js/watch/src/audio/ring-buffer.test.ts | 62 ++++++++---- js/watch/src/audio/ring-buffer.ts | 18 +++- js/watch/src/audio/shared-ring-buffer.test.ts | 98 +++++++++++++++++++ js/watch/src/audio/shared-ring-buffer.ts | 45 ++++++--- quest/m1/README.md | 1 - quest/m1/ci-runner-stalls.md | 3 +- quest/m1/interop-audio-cold-start.md | 29 ------ test/interop/clients/js/media.ts | 2 +- test/interop/clients/js/src/contract.ts | 2 + test/interop/clients/js/src/probe.ts | 1 + 15 files changed, 230 insertions(+), 139 deletions(-) create mode 100644 js/watch/src/audio/buffer.test.ts delete mode 100644 quest/m1/interop-audio-cold-start.md diff --git a/js/watch/src/audio/buffer.test.ts b/js/watch/src/audio/buffer.test.ts new file mode 100644 index 00000000000..07499287778 --- /dev/null +++ b/js/watch/src/audio/buffer.test.ts @@ -0,0 +1,28 @@ +import { describe, expect, it } from "bun:test"; +import type { Time } from "@moq/net"; +import { createAudioBuffer } from "./buffer"; +import type { InitShared } from "./render"; +import { SharedRingBuffer } from "./shared-ring-buffer"; + +describe("SharedAudioBuffer", () => { + // The worklet keeps reading the old ring until `init-shared` lands, so a rise that grows the ring + // has to park that one too, or audio drains ahead of video in between. + it("parks the ring the worklet still reads when a rise grows it", () => { + const sent: InitShared[] = []; + const worklet = { port: { postMessage: (msg: InitShared) => sent.push(msg) } } as unknown as AudioWorkletNode; + const buffer = createAudioBuffer(worklet, 1, 1000, 100); + try { + const old = new SharedRingBuffer(sent[0]); + buffer.insert(0 as Time.Micro, [new Float32Array(100).fill(1.0)]); + expect(old.read([new Float32Array(50)])).toBe(50); + + buffer.setLatency(1000); + expect(sent.length).toBe(2); + expect(old.stalled).toBe(true); + expect(old.read([new Float32Array(50)])).toBe(0); + expect(new SharedRingBuffer(sent[1]).stalled).toBe(true); + } finally { + buffer.close(); + } + }); +}); diff --git a/js/watch/src/audio/buffer.ts b/js/watch/src/audio/buffer.ts index 4c3a0263e5d..528ed936081 100644 --- a/js/watch/src/audio/buffer.ts +++ b/js/watch/src/audio/buffer.ts @@ -188,16 +188,17 @@ class SharedAudioBuffer implements AudioBuffer { setLatency(samples: number): void { this.#backpressure.setHeadroom(samplesToMicro(samples, this.rate)); + // Park the current ring before any resize: the worklet keeps reading it until `init-shared` + // lands, and `resize` carries the floor and the park over to the copy. + this.#ring.setLatency(samples); + // Grow the ring (preserving the unread window) if it's too small for the new latency. if (this.#ring.capacity < samples * 1.5) { const newCapacity = Math.max(this.rate, samples * 2); this.#ring = this.#ring.resize(newCapacity); - this.#ring.setLatency(samples); const msg: InitShared = { type: "init-shared", ...this.#ring.init }; this.#worklet.port.postMessage(msg); - } else { - this.#ring.setLatency(samples); } } diff --git a/js/watch/src/audio/decoder.ts b/js/watch/src/audio/decoder.ts index 8745d04af45..1af6875c66f 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -20,17 +20,13 @@ import type { Sync } from "../sync"; import { type AudioBuffer, createAudioBuffer } from "./buffer"; import { type DecoderConfig, decoderConfig, type PlaybackIdentity, playbackIdentity } from "./config"; import { Handover } from "./handover"; -import { reanchorFloor, ringSamples } from "./latency"; +import { ringSamples } from "./latency"; // Compiled and inlined as a blob URL via vite-plugin-worklet. import RenderWorklet from "./render-worklet.ts?worklet"; import type { Source } from "./source"; import { type DecodedSpan, Terminal } from "./terminal"; import { Warmup } from "./warmup"; -// How long the latency target must hold steady before a floor increase re-anchors. Coalesces a -// slider drag (many small steps) into a single re-anchor once the user settles on a value. -const LATENCY_REANCHOR_DEBOUNCE_MS = 150; - const LEGACY_WARMUP_CALLBACKS = 3; export type DecoderInput = { @@ -108,10 +104,6 @@ export class Decoder { // Ordered discontinuity and endpoint state from the container consumer. #terminal = new Terminal(); - // The latency floor as of the last settled change, to detect a floor *increase* (needs a deeper - // cushion) versus a decrease or a real-time RTT wiggle. See #runLatencyReanchor. - #prevFloor?: Time.Milli; - // Which subscription the ring's buffered samples came from. See #runDecoder. #handover = new Handover(); @@ -144,7 +136,6 @@ export class Decoder { this.#signals.run(this.#runWorklet.bind(this)); this.#signals.run(this.#runEnabled.bind(this)); this.#signals.run(this.#runLatency.bind(this)); - this.#signals.run(this.#runLatencyReanchor.bind(this)); this.#signals.run(this.#runDecoder.bind(this)); } @@ -247,39 +238,12 @@ export class Decoder { const ring = this.#ring; if (!ring) return; + // A rise parks playback until the ring refills to the new floor, which is what keeps audio in + // step with video. A catalog's jitter estimate can rise a millisecond at a time. const delay = effect.get(this.sync.out.delay); ring.setLatency(ringSamples(ring.rate, delay)); } - // Re-anchor when the delay floor *increases*. A larger floor needs a deeper cushion: video - // rebuilds it implicitly (its per-frame sync.wait() reads the live buffer, so it just holds - // longer), but the audio ring keeps draining at its old depth -- resize() (via setLatency) only - // re-stalls an *empty* ring, so a mid-playback ring never refills to the new floor and audio runs - // ahead of video (the "raise latency, only video re-buffers" desync). reset() re-stalls the ring - // so it refills to the new floor. Watch the latency target and media delay, excluding adaptive - // RTT jitter, and debounce so a slider drag coalesces into one re-anchor. Decreases are left to - // natural catch-up. - #runLatencyReanchor(effect: Effect): void { - const delay = effect.get(this.sync.out.delay); - const jitter = effect.get(this.sync.out.jitter); - const floor = reanchorFloor({ - delay: effect.get(this.sync.in.delay), - media: Time.Milli.sub(delay, jitter), - }); - if (this.#prevFloor === undefined) { - // Startup: the initial fill already builds the cushion; just record the baseline. - this.#prevFloor = floor; - return; - } - // When the timer fires, the floor read above is still current: any change would have rerun - // this effect (tearing down the timer), so compare it against the pre-change baseline directly. - const baseline = this.#prevFloor; - effect.timer(() => { - if (floor > baseline) this.reset(); - this.#prevFloor = floor; - }, LATENCY_REANCHOR_DEBOUNCE_MS); - } - #runDecoder(effect: Effect): void { const enabled = effect.get(this.in.enabled); if (!enabled) return; diff --git a/js/watch/src/audio/latency.test.ts b/js/watch/src/audio/latency.test.ts index ecc7c1f4d23..e6918210456 100644 --- a/js/watch/src/audio/latency.test.ts +++ b/js/watch/src/audio/latency.test.ts @@ -1,20 +1,9 @@ import { describe, expect, it } from "bun:test"; import type { Time } from "@moq/net"; -import { reanchorFloor, ringSamples } from "./latency"; +import { ringSamples } from "./latency"; const ms = (value: number) => value as Time.Milli; -describe("reanchorFloor", () => { - it("includes the fixed delay and the largest media delay", () => { - expect(reanchorFloor({ delay: ms(100), media: ms(80) })).toBe(ms(180)); - }); - - it("tracks rendition delay without adaptive RTT jitter", () => { - expect(reanchorFloor({ delay: "auto", media: ms(80) })).toBe(ms(80)); - expect(reanchorFloor({ delay: "auto", media: ms(200) })).toBe(ms(200)); - }); -}); - describe("ringSamples", () => { // `delay="instant"` reports a zero buffer. Passed through, the ring rejects it and the // worklet is left with no backend that any later resize can revive. diff --git a/js/watch/src/audio/latency.ts b/js/watch/src/audio/latency.ts index 1766d2b8d58..1885d28fd9f 100644 --- a/js/watch/src/audio/latency.ts +++ b/js/watch/src/audio/latency.ts @@ -1,22 +1,4 @@ import { Time } from "@moq/net"; -import type { Delay } from "../sync"; - -/** The inputs that determine whether audio needs a deeper playback cushion. */ -export interface ReanchorFloor { - /** How far playback trails the live edge. */ - delay: Delay; - - /** Largest additional delay required by the registered media decoders. */ - media?: Time.Milli; -} - -/** The stable delay floor whose increase requires the audio ring to refill. */ -export function reanchorFloor(props: ReanchorFloor): Time.Milli { - // "auto" and "instant" contribute nothing: the adaptive RTT component is deliberately excluded - // so an RTT wiggle doesn't re-anchor, and "instant" holds nothing at all. - const target = typeof props.delay === "number" ? props.delay : Time.Milli.zero; - return Time.Milli.add(target, props.media ?? Time.Milli.zero); -} // An AudioWorkletProcessor renders in fixed 128-sample quanta, so a ring shallower than one can // never be read from. diff --git a/js/watch/src/audio/ring-buffer.test.ts b/js/watch/src/audio/ring-buffer.test.ts index 5d1fb2ceba0..a53d2111e1f 100644 --- a/js/watch/src/audio/ring-buffer.test.ts +++ b/js/watch/src/audio/ring-buffer.test.ts @@ -419,7 +419,7 @@ describe("resize", () => { expect(buffer.capacity).toBe(50); expect(buffer.length).toBe(50); // Truncated to new capacity - expect(buffer.stalled).toBe(true); // Should trigger stall + expect(buffer.stalled).toBe(false); // Already covers the new floor }); it("should be a no-op when capacity is unchanged", () => { @@ -458,7 +458,7 @@ describe("resize", () => { buffer.resize(50 as Time.Milli); expect(buffer.capacity).toBe(50); expect(buffer.length).toBe(50); - expect(buffer.stalled).toBe(true); + expect(buffer.stalled).toBe(false); }); it("should handle resize when buffer is empty", () => { @@ -495,17 +495,16 @@ describe("resize", () => { expect(buffer.stalled).toBe(false); }); - it("should exit stall and read new data after resize", () => { + it("should resume and then read new data after a shrinking resize", () => { const buffer = new AudioRingBuffer({ rate: 1000, channels: 1, latency: 100 as Time.Milli }); // Write some initial data write(buffer, 0 as Time.Milli, 50, { channels: 1, value: 1.0 }); - // Resize to smaller buffer + // Resize to a floor the buffered data already covers buffer.resize(50 as Time.Milli); - expect(buffer.stalled).toBe(true); + expect(buffer.stalled).toBe(false); - // Write new data to fill the buffer and exit stall // The overflow will discard preserved samples and advance readIndex write(buffer, 50 as Time.Milli, 50, { channels: 1, value: 2.0 }); expect(buffer.stalled).toBe(false); @@ -771,31 +770,52 @@ describe("buffered mode", () => { }); }); -describe("latency increase re-anchor", () => { - it("resize() does not re-stall a mid-playback ring, but reset() does", () => { +describe("latency increase", () => { + // Video holds a deeper floor on its own, so audio has to park for the difference or it runs + // ahead. Flushing instead cost the whole floor in silence for every rise, however small. + it("parks a playing ring until the deeper floor refills, keeping what it buffered", () => { const buffer = new AudioRingBuffer({ rate: 1000, channels: 1, latency: 100 as Time.Milli }); - // Fill to the floor so playback starts (un-stalls), then play some samples. + // Fill to the floor so playback starts, then play half of it. write(buffer, 0 as Time.Milli, 100, { channels: 1, value: 1.0 }); expect(buffer.stalled).toBe(false); read(buffer, 50, 1); - // Raising the latency floor grows the target but must NOT re-stall a ring mid-playback: - // resize() only re-stalls an empty ring, so it keeps draining at the old depth. This is - // exactly why setLatency() alone doesn't re-buffer -- the desync the Decoder re-anchor fixes. - buffer.resize(200 as Time.Milli); - expect(buffer.stalled).toBe(false); + buffer.resize(110 as Time.Milli); + expect(buffer.stalled).toBe(true); + expect(buffer.length).toBe(50); - // reset() re-stalls, so the ring refills to the (new) floor before playing again. The Decoder - // calls reset() on a latency-floor increase (#runLatencyReanchor) to re-anchor to the cushion. - buffer.reset(); + // Refilling to the 110-sample floor takes 60 more samples, not the whole floor. + write(buffer, 100 as Time.Milli, 59, { channels: 1, value: 2.0 }); expect(buffer.stalled).toBe(true); + write(buffer, 159 as Time.Milli, 1, { channels: 1, value: 2.0 }); + expect(buffer.stalled).toBe(false); + + // Playback resumes where it parked rather than at the refill. + expect(Time.Milli.fromMicro(buffer.timestamp)).toBe(50 as Time.Milli); + expect(read(buffer, 1, 1)[0][0]).toBe(1.0); + }); - // ...and it refills to the *new* 200-sample floor, not the old 100: still stalled at 199, - // un-stalls only once the 200th sample lands. This proves resize(200) moved the target. - write(buffer, 0 as Time.Milli, 199, { channels: 1, value: 1.0 }); + it("keeps playing through a shallower floor", () => { + const buffer = new AudioRingBuffer({ rate: 1000, channels: 1, latency: 100 as Time.Milli }); + write(buffer, 0 as Time.Milli, 100, { channels: 1, value: 1.0 }); + read(buffer, 50, 1); + + buffer.resize(90 as Time.Milli); + expect(buffer.stalled).toBe(false); + }); + + it("resumes a refill once a shallower floor is already covered", () => { + const buffer = new AudioRingBuffer({ rate: 1000, channels: 1, latency: 100 as Time.Milli }); + write(buffer, 0 as Time.Milli, 100, { channels: 1, value: 1.0 }); + read(buffer, 50, 1); + + buffer.resize(110 as Time.Milli); expect(buffer.stalled).toBe(true); - write(buffer, 199 as Time.Milli, 1, { channels: 1, value: 1.0 }); + + // No further frame arrives, as when the source stops, so only the lower floor can resume it. + buffer.resize(50 as Time.Milli); expect(buffer.stalled).toBe(false); + expect(read(buffer, 1, 1)[0][0]).toBe(1.0); }); }); diff --git a/js/watch/src/audio/ring-buffer.ts b/js/watch/src/audio/ring-buffer.ts index fb94f036928..38387a13a3b 100644 --- a/js/watch/src/audio/ring-buffer.ts +++ b/js/watch/src/audio/ring-buffer.ts @@ -65,10 +65,24 @@ export class AudioRingBuffer { } resize(latency: Time.Milli): void { - this.#latencySamples = Math.ceil(this.rate * Time.Second.fromMilli(latency)); + const latencySamples = Math.ceil(this.rate * Time.Second.fromMilli(latency)); + + // A deeper floor parks playback until it refills. Video holds the extra delay on its own, so + // audio that kept draining at the old depth would run ahead by the difference. Parking keeps + // what is buffered, so a rise costs only its own size in silence, and none if the buffer + // already covers the new floor. + if (latencySamples > this.#latencySamples) this.#stalled = true; + this.#latencySamples = latencySamples; const newCapacity = this.#capacityFor(this.#latencySamples); - if (newCapacity === this.capacity) return; + if (newCapacity !== this.capacity) this.#reallocate(newCapacity); + + // Resume a refill that the buffer already covers, which `write` would only notice on the + // next frame, never for a source that has stopped. + if (latencySamples > 0 && this.length >= latencySamples) this.#stalled = false; + } + + #reallocate(newCapacity: number): void { if (newCapacity === 0) throw new Error("empty buffer"); const newBuffer: Float32Array[] = []; diff --git a/js/watch/src/audio/shared-ring-buffer.test.ts b/js/watch/src/audio/shared-ring-buffer.test.ts index 2647ea3cc7e..72e3a621a48 100644 --- a/js/watch/src/audio/shared-ring-buffer.test.ts +++ b/js/watch/src/audio/shared-ring-buffer.test.ts @@ -476,6 +476,104 @@ describe("setLatency", () => { const output2 = read(buffer, 128, 1); expect(output2[0].length).toBe(20); }); + + // Video holds a deeper floor on its own, so audio has to park for the difference or it runs + // ahead. Flushing instead cost the whole floor in silence for every rise, however small. + it("parks a playing ring until the deeper floor refills, keeping what it buffered", () => { + const buffer = create({ rate: 1000, channels: 1, capacity: 256, latency: 100 }); + insert(buffer, 0, 100, { channels: 1, value: 1.0 }); + expect(buffer.stalled).toBe(false); + read(buffer, 50, 1); + + buffer.setLatency(110); + expect(buffer.stalled).toBe(true); + expect(read(buffer, 128, 1)[0].length).toBe(0); + + // Refilling to the 110-sample floor takes 60 more samples, not the whole floor. + insert(buffer, 100, 59, { channels: 1, value: 2.0 }); + expect(buffer.stalled).toBe(true); + insert(buffer, 159, 1, { channels: 1, value: 2.0 }); + expect(buffer.stalled).toBe(false); + + // Playback resumes where it parked rather than at the refill. + expect(Time.Milli.fromMicro(buffer.timestamp)).toBe(50 as Time.Milli); + expect(read(buffer, 1, 1)[0][0]).toBe(1.0); + }); + + it("silences a quantum already in flight when the floor rises", () => { + const init = allocSharedRingBuffer(1, 256, 1000); + const main = new SharedRingBuffer(init); + main.setLatency(100); + insert(main, 0, 100, { channels: 1, value: 1.0 }); + const worklet = new SharedRingBuffer(init); + const out = [new Float32Array(50).fill(-1)]; + + // Raise the floor from inside the read's LATENCY load: past the STALLED check, before the + // copy and publish, which is where the worklet sits whenever the two threads overlap. + const LATENCY = 1; + let fired = false; + const realLoad = Atomics.load; + const atomics = Atomics as { load: unknown }; + atomics.load = (arr: Int32Array | BigInt64Array, idx: number) => { + const value = realLoad(arr as Int32Array, idx); + if (!fired && arr instanceof Int32Array && idx === LATENCY) { + fired = true; + main.setLatency(110); + } + return value; + }; + + let result = -1; + try { + result = worklet.read(out); + } finally { + atomics.load = realLoad; + } + expect(fired).toBe(true); + + // The quantum raced the park, so none of it renders and the playhead stays put. + expect(result).toBe(0); + expect(out[0]).toEqual(new Float32Array(50)); + expect(Time.Milli.fromMicro(main.timestamp)).toBe(0 as Time.Milli); + + insert(main, 100, 10, { channels: 1, value: 2.0 }); + expect(main.stalled).toBe(false); + expect(read(worklet, 1, 1)[0][0]).toBe(1.0); + }); + + it("keeps playing through a shallower floor", () => { + const buffer = create({ rate: 1000, channels: 1, capacity: 256, latency: 100 }); + insert(buffer, 0, 100, { channels: 1, value: 1.0 }); + read(buffer, 50, 1); + + buffer.setLatency(90); + expect(buffer.stalled).toBe(false); + }); + + it("keeps playing through a deeper floor the buffer already covers", () => { + const buffer = create({ rate: 1000, channels: 1, capacity: 256, latency: 100 }); + insert(buffer, 0, 40, { channels: 1, value: 1.0 }); + insert(buffer, 40, 110, { channels: 1, value: 2.0 }); + + buffer.setLatency(110); + expect(buffer.stalled).toBe(false); + // The skip lands on the new floor: the last 110 samples. + expect(read(buffer, 1, 1)[0][0]).toBe(2.0); + }); + + it("resumes a refill once a shallower floor is already covered", () => { + const buffer = create({ rate: 1000, channels: 1, capacity: 256, latency: 100 }); + insert(buffer, 0, 100, { channels: 1, value: 1.0 }); + read(buffer, 50, 1); + + buffer.setLatency(110); + expect(buffer.stalled).toBe(true); + + // No further frame arrives, as when the source stops, so only the lower floor can resume it. + buffer.setLatency(50); + expect(buffer.stalled).toBe(false); + expect(read(buffer, 1, 1)[0][0]).toBe(1.0); + }); }); describe("stalled getter", () => { diff --git a/js/watch/src/audio/shared-ring-buffer.ts b/js/watch/src/audio/shared-ring-buffer.ts index ce790948547..f4c0ba2a4f2 100644 --- a/js/watch/src/audio/shared-ring-buffer.ts +++ b/js/watch/src/audio/shared-ring-buffer.ts @@ -206,14 +206,14 @@ export class SharedRingBuffer { } /** - * Step the epoch by one, leaving the playhead wherever the reader has taken it. + * Step the epoch by `by`, leaving the playhead wherever the reader has taken it. * * Retries while the word changes under it: only the epoch half is the writer's to move. */ - #step(): void { + #step(by: number): void { for (;;) { const state = Atomics.load(this.#state, 0); - const next = pack((epochOf(state) + 1) | 0, readOf(state)); + const next = pack((epochOf(state) + by) | 0, readOf(state)); if (Atomics.compareExchange(this.#state, 0, state, next) === state) return; } } @@ -300,11 +300,15 @@ export class SharedRingBuffer { // Advance WRITE (only forward) Atomics.store(this.#control, WRITE, i32Max(Atomics.load(this.#control, WRITE), end)); - // Un-stall: if buffered data >= LATENCY - const currentRead = readOf(Atomics.load(this.#state, 0)); - const currentWrite = Atomics.load(this.#control, WRITE); + this.#resume(); + } + + // Un-stall once the buffered data covers LATENCY. + #resume(): void { + const read = readOf(Atomics.load(this.#state, 0)); + const write = Atomics.load(this.#control, WRITE); const latency = Atomics.load(this.#control, LATENCY); - if (((currentWrite - currentRead) | 0) >= latency && latency > 0) { + if (((write - read) | 0) >= latency && latency > 0) { Atomics.store(this.#control, STALLED, 0); } } @@ -371,9 +375,28 @@ export class SharedRingBuffer { return count; } - /** Update the target latency in samples. */ + /** + * Update the target latency in samples. Main thread only. + * + * A deeper floor parks playback until it refills. Video holds the extra delay on its own, so + * audio that kept draining at the old depth would run ahead by the difference. Parking keeps + * what is buffered, so a rise costs only its own size in silence, and none if the buffer + * already covers the new floor. + */ setLatency(samples: number): void { - Atomics.store(this.#control, LATENCY, samples); + const previous = Atomics.exchange(this.#control, LATENCY, samples); + if (previous > 0 && samples > previous) { + Atomics.store(this.#control, STALLED, 1); + // A reader already past the STALLED check would still publish its quantum. Moving the + // word fails its exchange, and one that snapshots after this sees STALLED. Two keeps the + // epoch even, since odd belongs to `truncate`. + this.#step(2); + } + + // Parked, the playhead holds still, so this measures exactly what is buffered. It also + // resumes a refill that a shallower floor has already covered, which `insert` would only + // notice on the next frame, never for a source that has stopped. + this.#resume(); } /** @@ -389,7 +412,7 @@ export class SharedRingBuffer { // Bracket the retreat with epoch steps, so a reader is never left holding a WRITE this // dropped the tail of. See `epochOf`. - this.#step(); + this.#step(1); for (;;) { const write = Atomics.load(this.#control, WRITE); // Never retreat past the playhead: those samples are already due. The worklet can still @@ -401,7 +424,7 @@ export class SharedRingBuffer { if (((write - clamped) | 0) <= 0) break; if (Atomics.compareExchange(this.#control, WRITE, write, clamped) === write) break; } - this.#step(); + this.#step(1); } /** diff --git a/quest/m1/README.md b/quest/m1/README.md index f16bd7f1d75..5b99fdc6e0f 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -39,7 +39,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Session death parity](/quest/m1/session-death.md) - a local close ends tracks cleanly in both languages, and JS group readers see the session's error on session death - [Watch and publish under CSP](/quest/m1/csp-assets.md) - blob workers stay the default; strict-CSP apps host the files and set a base URL - [More tests under load](/quest/m1/test-flakes-2.md) - the second round of load-only failures, fixed at the cause -- [Interop audio cold start](/quest/m1/interop-audio-cold-start.md) - the interop audio tone check stops failing on cold start, fixed at its cause - [CI runner stalls](/quest/m1/ci-runner-stalls.md) - the 0.4 to 0.8 s freezes of both interop tracks on CI are attributed from a week of nightlies and fixed or told apart from playback bugs - [Catalog estimate rate](/quest/m1/catalog-estimate-rate.md) - a rising `jitter`/`delay` estimate republishes the catalog at most once a second, in js/publish and moq-mux - [Auth outage clock](/quest/m1/auth-outage-clock.md) - the relay and moq-auth outage tests run on a paused clock again and assert both bounds of `expires` diff --git a/quest/m1/ci-runner-stalls.md b/quest/m1/ci-runner-stalls.md index 3d6f4df3bdf..ae944c35bfe 100644 --- a/quest/m1/ci-runner-stalls.md +++ b/quest/m1/ci-runner-stalls.md @@ -25,5 +25,4 @@ Public API: none. Wire: none. ## Required -- A week of nightly interop runs on `main` after #4529 merges -- [Interop audio cold start](/quest/m1/interop-audio-cold-start.md) - #4529, which adds the `delay` column these traces need +- A week of nightly interop runs on `main` after #4529, which adds the `delay` column these traces need diff --git a/quest/m1/interop-audio-cold-start.md b/quest/m1/interop-audio-cold-start.md deleted file mode 100644 index 78c2522dd06..00000000000 --- a/quest/m1/interop-audio-cold-start.md +++ /dev/null @@ -1,29 +0,0 @@ -# [S] Interop audio tone survives a cold start - -## Goal - -The interop "Media output and lifecycle" step stops failing the audio tone -check on cold start. The 2026-09-28 nightly on `main` failed with -`FAIL audio tone: cold start: 55/64 samples carried the fixture tone above the -noise floor`, against a 90% agreement floor. - -## Plan - -- Reproduce it: run the interop media step in a loop on a loaded machine - until the cold-start row fails, and capture which samples miss (the first - ones, or scattered). -- Find the cause before touching the check: the likely suspects are decoder - or playout warm-up after the context resumes. [Publish channel count](/quest/m1/publish-audio-channel-count.md) - saw the same symptom, but `test/interop/clients/js/src/fixture.ts` already - dropped the `channelCount` override, so that's not it. -- Fix it at the source. The cold-start window deliberately starts once the - context runs, without waiting for a tone, so a slow start has to fail - there. Keep that window: if the misses are the first samples, find what - delays the first audible output instead of moving the window. Don't lower - `AGREEMENT` (`test/interop/clients/js/media.ts`) without a measured reason. - -Public API: none. Wire: none. - -## Related - -- [More tests under load](/quest/m1/test-flakes-2.md) - the other load-only failures diff --git a/test/interop/clients/js/media.ts b/test/interop/clients/js/media.ts index 787b00665e3..f4e9577d3a0 100644 --- a/test/interop/clients/js/media.ts +++ b/test/interop/clients/js/media.ts @@ -178,7 +178,7 @@ function traceLine(sample: PlayerState, start: number): string { return ( ` +${((sample.at - start) / 1000).toFixed(2)}s frame=${sample.frameId ?? "-"} ` + `step=${sample.toneStep ?? "-"}/${step} tone=${margin.toFixed(0)}dB ${sample.toneHz?.toFixed(0) ?? "-"}Hz ` + - `paused=${sample.paused} audio=${sample.audioBytes}B${sample.audioStalled ? " stalled" : ""}` + `paused=${sample.paused} delay=${sample.delay}ms audio=${sample.audioBytes}B${sample.audioStalled ? " stalled" : ""}` ); } diff --git a/test/interop/clients/js/src/contract.ts b/test/interop/clients/js/src/contract.ts index d7fc63342cd..00c8803e94f 100644 --- a/test/interop/clients/js/src/contract.ts +++ b/test/interop/clients/js/src/contract.ts @@ -130,6 +130,8 @@ export type Sample = { audioTimestamp?: number; /** Whether the audio buffer is waiting to refill. */ audioStalled: boolean; + /** How far playback trails the live edge, in milliseconds: the player's resolved sync delay. */ + delay: number; /** Peak frequency in the tone band, absent until the graph exists. */ toneHz?: number; /** The tone step that peak names, absent when no tone stands above the floor. */ diff --git a/test/interop/clients/js/src/probe.ts b/test/interop/clients/js/src/probe.ts index 23c7441a0df..b6e3c5cca60 100644 --- a/test/interop/clients/js/src/probe.ts +++ b/test/interop/clients/js/src/probe.ts @@ -138,6 +138,7 @@ export function attach(el: MoqWatch): () => void { audioContext: el.audio.out.context.peek()?.state, audioTimestamp: el.audio.out.timestamp.peek() ?? undefined, audioStalled: el.audio.out.stalled.peek(), + delay: el.sync.out.delay.peek(), ...(analyser ? analyze(analyser, spectrum, wave) : {}), paused: el.paused, pausedAttribute: el.hasAttribute("paused"), From 87f41ef5d95c806ec72483c1d70667f4913954f9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 15:56:45 -0700 Subject: [PATCH 066/128] chore(quest): fold exact scope into moq-lite announcement shapes (#4517) Co-authored-by: Claude Opus 5.5 --- quest/m0/wildcard/README.md | 4 +- quest/m1/README.md | 1 - quest/m1/exact-scope.md | 24 ------ quest/m1/path-patterns.md | 7 +- quest/m1/processor/advertise-auth.md | 5 +- quest/m3/README.md | 2 +- quest/m3/announce-shapes.md | 109 +++++++++++++++++++++++++++ quest/m3/suffix-announce.md | 42 ----------- 8 files changed, 120 insertions(+), 74 deletions(-) delete mode 100644 quest/m1/exact-scope.md create mode 100644 quest/m3/announce-shapes.md delete mode 100644 quest/m3/suffix-announce.md diff --git a/quest/m0/wildcard/README.md b/quest/m0/wildcard/README.md index 8e9173b6d0a..97be3a60c42 100644 --- a/quest/m0/wildcard/README.md +++ b/quest/m0/wildcard/README.md @@ -227,5 +227,5 @@ distinguish recording generations reads the catalog's archive entry with an HRW tie-break, built on this line's longest-prefix rule - [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - derived output mirrors the source path, `@` segment included -- [Suffix announce](/quest/m3/suffix-announce.md) - moq-lite-only suffix - claims, deferred until a service prefix cannot express one +- [Announcement shapes](/quest/m3/announce-shapes.md) - moq-lite-only exact, + suffix, and prefix+suffix claims that survive relay hops diff --git a/quest/m1/README.md b/quest/m1/README.md index 5b99fdc6e0f..82e217cb564 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -18,7 +18,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. ## Required - [Cluster routing](/quest/m1/cluster-routing.md) - an announcement says where a broadcast originates, not how to reach it, and a relay hears only the prefixes its clients asked for -- [Exact scope](/quest/m1/exact-scope.md) - a reader never sees an exact broadcast outside its scope, in Rust or JS; prefix routes above it still present as the empty path - [Track tail interop](/quest/m1/track-tail-interop.md) - a Rust publisher ending a track with a group in flight is read to its end by the JS subscriber, and the reverse, in `just test interop` - [Binding audio delay](/quest/m1/binding-surface.md) - moq-ffi and every wrapper configure and observe audio playout delay - [FFI shape](/quest/m1/ffi-shape/README.md) - the bindings mirror Rust's layers: net at the root, then media, json, flate, audio, and video namespaces built from the handle below diff --git a/quest/m1/exact-scope.md b/quest/m1/exact-scope.md deleted file mode 100644 index 3e20a7b7067..00000000000 --- a/quest/m1/exact-scope.md +++ /dev/null @@ -1,24 +0,0 @@ -# [S] An exact broadcast outside a reader's scope stays hidden - -## Goal - -A reader scoped to `/a/b` never sees an exact broadcast at `/a`, in Rust or -JS. A prefix advertisement at or above the scope still presents as the empty -path, because it may serve paths under the scope; an exact broadcast cannot. - -## Plan - -Decided 2026-09-28: exact match everywhere, aligning on the JS local view. - -- Rust: `sync_cursor` in `rs/moq-net/src/model/origin.rs` admits an exact - entry by prefix overlap. Match exact entries against the reader's patterns - instead. `cursor_keeps_an_overlapping_prefix_above_its_scope` covers a - prefix route and stays. -- JS wire view: `Scope.projectRoutes` in `js/net/src/origin.ts` treats every - entry above the root as covering. Skip exact entries there, as `#listed` - already does with `candidate.exact ? pattern.matches(path)`. -- Add the same case to both languages' tests: an exact broadcast at `/a` and - a prefix route at `/a`, read through a `/a/b` scope, yield only the prefix. - -Public API: none. Wire: a narrower reader receives fewer announcements; no -message changes. diff --git a/quest/m1/path-patterns.md b/quest/m1/path-patterns.md index 691bcf1dc30..ce5536ce77c 100644 --- a/quest/m1/path-patterns.md +++ b/quest/m1/path-patterns.md @@ -5,7 +5,8 @@ Every predicate over a MoQ broadcast path uses one matcher. Tokens, origin scopes, announce interests, and public access rules can express `pid/*/chat` and `**/*.hang` without maintaining competing glob dialects. -Routing is not a predicate here: advertisements stay prefixes. +Routing is not a predicate here: advertisements stay prefixes, and +[announcement shapes](/quest/m3/announce-shapes.md) owns non-prefix routing. Literal paths remain coordinates, not sets. Roots, joins, exact broadcast names, URL paths, filesystem paths, and object-store keys keep their own @@ -80,7 +81,9 @@ AUTH grants on moq-lite-06 carry the shared pattern semantics, without changing older protocol versions. Interest stays a prefix: [#3770](https://github.com/moq-dev/moq/pull/3770) keeps patterns off the announce wire, so ANNOUNCE_REQUEST and SUBSCRIBE_NAMESPACE carry the prefix the caller asked for and a wildcard is -an optional filter on the consume side. +an optional filter on the consume side. [Announcement shapes](/quest/m3/announce-shapes.md) +later adds only exact, suffix, and prefix+suffix to moq-lite's ANNOUNCE_REQUEST; +any other pattern stays a consume-side filter. Replace lite-06 AUTH grant prefixes with patterns in Rust and JavaScript in the same change. Update the lite draft and version-gated fixtures together. diff --git a/quest/m1/processor/advertise-auth.md b/quest/m1/processor/advertise-auth.md index d3dc514541f..08e2985071c 100644 --- a/quest/m1/processor/advertise-auth.md +++ b/quest/m1/processor/advertise-auth.md @@ -17,8 +17,9 @@ announcement or publish request still requires publish permission, so an advertise-only worker cannot bypass the demand exchange. Decided: the advertise scope is prefix-only. Advertising is prefix-only on -every wire (Wildcard's decision) and suffix routing is dropped, so leading-star -and suffix advertise patterns have nothing to authorize. Token claim patterns +every wire (Wildcard's decision) until [announcement shapes](/quest/m3/announce-shapes.md) +adds exact and suffix shapes to moq-lite, so leading-star and suffix advertise +patterns have nothing to authorize yet; that quest extends this scope. Token claim patterns keep their suffix support for publish and subscribe. Decided: an advertised prefix must overlap the advertise scope, not sit diff --git a/quest/m3/README.md b/quest/m3/README.md index ac3b0631f5a..5f1ec16b652 100644 --- a/quest/m3/README.md +++ b/quest/m3/README.md @@ -20,5 +20,5 @@ condition clears, move the quest to the milestone its work belongs in. - [#2893](/quest/m3/2893-video-validate-pipewire-dma-buf-capture-on-kde-hardware.md) - video: validate PipeWire DMA-BUF capture on KDE hardware - [Embedded video](/quest/m3/video-embedded.md) - EGL import in the renderer, so moq-video presents on a Pi - [Vision worker](/quest/m3/processor-vision.md) - a documented customer-run vision worker proves the processor contract -- [Suffix announce](/quest/m3/suffix-announce.md) - moq-lite-only suffix announce and interest, benchmarked over the announce table, once a deployment needs a claim a service prefix cannot express +- [Announcement shapes](/quest/m3/announce-shapes.md) - moq-lite announcements and interests carry prefix, exact, suffix, or prefix+suffix shapes that survive relay hops, benchmarked over the announce table - [Upstream forks](/quest/m3/upstream-forks.md) - offer the uniffi generator fixes our cpp, dart, and Python forks carry upstream, lowest priority diff --git a/quest/m3/announce-shapes.md b/quest/m3/announce-shapes.md new file mode 100644 index 00000000000..19083a6c45f --- /dev/null +++ b/quest/m3/announce-shapes.md @@ -0,0 +1,109 @@ +# [XL] Announcement shapes in moq-lite + +## Goal + +A moq-lite announcement carries its shape, prefix, exact, suffix, or +prefix+suffix, and relays preserve it across hops. A subscriber can request +announcements by any shape (`**/transcode.pro`), and a publisher can +advertise one, so a fleet-wide service claims every matching path once +instead of per prefix. An exact broadcast at `/a` stays hidden from a reader +scoped to `/a/b` on every hop, not only on the origin holding it. + +moq-lite only: IETF sessions stay prefix-only. Routing only: token claim +patterns keep their suffix support unchanged. + +## Plan + +Decided 2026-09-29 (quest-plan interview): + +- [#4479](https://github.com/moq-dev/moq/pull/4479) does not land. It hid an + exact broadcast from a narrower reader only on the origin holding it: no + wire carries exactness, so relays install forwarded announcements through + `Producer::dynamic` as prefix routes and the broadcast's existence leaks to + narrower readers downstream. Exactness and suffixes are one problem, a + route's shape on the wire, so they are one quest. +- IETF stays prefix-only: moq-transport will not support exact or suffix + announcements (PUBLISH_NAMESPACE and NAMESPACE are prefix routes), so a + session negotiated as IETF never carries a shape and there is no draft to + converge with. +- The quest stays in m3, grown from the suffix-announce quest rather than a + new m1 quest, because that quest already holds the benchmark-first plan and + the version-gated wire approach both shapes need. +- The old gate ("a deployment needs a suffix claim a service prefix cannot + express") is removed: the exact-scope leak is reason enough. +- [Path patterns](/quest/m1/path-patterns.md) keeps advertisements as prefixes + and names this quest as the owner of non-prefix routing. + +### Wire + +The shape rides on both ANNOUNCE_REQUEST (interest) and ANNOUNCE_START +(advertisement), version- or setup-gated like `hidden`. A new announce Type is +not an option: an old receiver skips an unknown type without assigning it an +id (`rs/moq-net/src/lite/announce.rs`), so the id streams diverge. An older +peer gets prefix-only behavior; decide per shape whether downgrading it to a +prefix is safe (an exact route widened to a prefix still leaks) or whether the +route is withheld. Update `js/net` and `drafts/draft-lcurley-moq-lite.md` in +the same PR. + +Today ANNOUNCE_START carries a path relative to the requested prefix, which +the receiver joins back on (`rs/moq-net/src/lite/subscriber.rs`). A suffix +interest (`**/transcode.pro`) has no literal prefix to join, and a matching +route is not its suffix, so the draft must define how each advertisement is +anchored and rebased for each interest shape, with the cross-shape overlap +cases as vectors both languages test. + +Only these four shapes go on the wire. A richer interest pattern +(`pid/*/chat`) stays a consume-side filter over the widest shape that covers +it, as [path patterns](/quest/m1/path-patterns.md) decided for every pattern +before this quest. + +### Model + +The origin model needs an `exact` route kind distinct from `source`: today +only a local broadcast (`source` set) is exact, and a forwarded route is +always a prefix. Carrying the kind also tightens `serves()` for a remote exact +route. An exact and a prefix route can share a path, but `sync_cursor` +presents one best entry per path and the lite announce state +(`AnnounceRun.live`, pending updates) is keyed by path alone, so today one +shape hides the other on the wire. Shape likely joins that identity. The +known exact-scope spots: + +- Rust: `sync_cursor` in `rs/moq-net/src/model/origin.rs` admits an exact + entry by prefix overlap; match it against the reader's patterns instead. + `cursor_keeps_an_overlapping_prefix_above_its_scope` covers a prefix route + and stays. +- JS: `Scope.projectRoutes` in `js/net/src/origin.ts` treats every entry + above the root as covering, and `Candidate.exact` is local-only today. +- Test in both languages, locally and across a relay hop: an exact broadcast + at `/a` and a prefix route at `/a` both survive a root-scoped hop, and read + through a `/a/b` scope yield only the prefix. #4479's regressions and + benchmark are a starting point. + +### Benchmark first + +The route table is a trie keyed by path segment (`rs/moq-net/benches/origin.rs`). +A suffix cannot walk it, so a naive match costs the whole announce table on +every announcement and every new cursor. Requests hit the same wall: +`request_broadcast` resolves through `best_route`, which walks the prefix trie +for the longest covering claim, so a suffix advertisement must also be found +by SUBSCRIBE and FETCH resolution. Longest prefix cannot rank `a/**` against +`**/z` for `a/x/z`, so define one total cross-shape precedence and tie rule +that Rust, JS, and relays share; path patterns' structural specificity is the +natural starting point. + +Extend `rs/moq-net/benches/origin.rs` with suffix and exact cursors and route +lookups, each swept over publishers and subscribers, and extend +`js/net/bench/forward.ts` the same way, since `Scope.projectRoutes` scans +routes independently of Rust. The slopes decide between a reversed-segment +index and dropping suffix shapes from the quest. + +A non-prefix advertisement needs authorizing: +[advertise auth](/quest/m1/processor/advertise-auth.md) scopes are prefix-only +today, and this quest extends them to the new shapes. Token patterns +(`moq-pattern`, `moq_auth::Claims`) already match suffixes and do not change. + +## Related + +- [Wildcard](/quest/m0/wildcard/README.md) - prefix-only advertisements and the service-prefix layout this extends +- [Path patterns](/quest/m1/path-patterns.md) - owns the pattern dialect a shaped interest would reuse +- [Cluster routing](/quest/m1/cluster-routing.md) - forwards announcements between relays, which must keep their shape diff --git a/quest/m3/suffix-announce.md b/quest/m3/suffix-announce.md deleted file mode 100644 index 5e061f3b39d..00000000000 --- a/quest/m3/suffix-announce.md +++ /dev/null @@ -1,42 +0,0 @@ -# [L] Suffix announce and interest in moq-lite - -## Goal - -A moq-lite subscriber can request announcements by suffix (`**/transcode.pro`) -and a publisher can advertise one, so a fleet-wide service claims every -matching path once instead of per prefix. moq-lite only: IETF sessions stay -prefix-only. Routing only: token claim patterns keep their suffix support -unchanged. - -## Plan - -Decided in the 2026-09-28 quest audit: suffix routing is dropped from every -other quest, which are prefix-only, and lives here as a moq-lite-only -extension. IETF MoQT refuses suffix matching, so a session negotiated as IETF -never carries it and there is no draft to converge with. - -Today `AnnounceRequest` (`rs/moq-net/src/lite/announce.rs`) carries only a -`prefix`, and the origin's route table is a trie keyed by path segment -(`rs/moq-net/benches/origin.rs`). A suffix cannot walk that trie, so a naive -match costs the whole announce table on every announcement and every new -cursor. Requests hit the same wall: `request_broadcast` resolves through -`best_route`, which walks the prefix trie for the longest covering claim, so -a suffix advertisement must also be inserted where SUBSCRIBE and FETCH -resolution find it, with the same specificity rules as prefix claims. -Benchmark first: extend `rs/moq-net/benches/origin.rs` with suffix cursors -and suffix route lookups, each swept over publishers and subscribers. The -slopes decide between a reversed-segment index and abandoning the quest. - -The wire field is version-gated like `hidden`. Update `js/net` and -`drafts/draft-lcurley-moq-lite.md` in the same PR. Token patterns -(`moq-pattern`, `moq_auth::Claims`) already match suffixes and do not change. - -## Required - -- A deployment needs a suffix claim that a service prefix (`./...`) - cannot express - -## Related - -- [Wildcard](/quest/m0/wildcard/README.md) - prefix-only advertisements and the service-prefix layout this would extend -- [Path patterns](/quest/m1/path-patterns.md) - owns the pattern dialect a suffix interest would reuse From e18b27b565927eb50b4539d36c7bf01f54b0ba16 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 15:59:12 -0700 Subject: [PATCH 067/128] feat(net): re-send NAMESPACE inline on a first-hop change, as Rust does The PUBLISH_NAMESPACE path still withdraws for a new original publisher, now inside #update like Rust's update_namespace. Co-Authored-By: Claude Opus 5.5 --- js/net/src/ietf/publisher.test.ts | 28 +++++++------ js/net/src/ietf/publisher.ts | 58 ++++++++++++++++---------- quest/m1/cluster-publisher-in-place.md | 8 ++-- 3 files changed, 57 insertions(+), 37 deletions(-) diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index ef76bce3db9..e21788c8a6c 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -1091,8 +1091,14 @@ test("a hop path change behind the same publisher is one REQUEST_UPDATE carrying } }); -/** NAMESPACE has no REQUEST_UPDATE; the receiver reads a repeat as a replacement. */ -test("a solicited namespace is repriced with one NAMESPACE and no NAMESPACE_DONE", async () => { +/** + * NAMESPACE has no REQUEST_UPDATE; the receiver reads a repeat as a replacement. That holds + * for a new original publisher too, as in Rust: only a PUBLISH_NAMESPACE is withdrawn for one. + */ +test.each([ + ["a hop path and cost change", [VIA, MID], 8n], + ["a first-hop change", [OTHER], 4n], +] as const)("a solicited namespace takes %s as one NAMESPACE and no NAMESPACE_DONE", async (_, hops, cost) => { const { self, pair, pub, origin, close } = clustered(true); try { const broadcast = origin.createBroadcast(Path.from("mine")); @@ -1112,11 +1118,8 @@ test("a solicited namespace is repriced with one NAMESPACE and no NAMESPACE_DONE await RequestOk.decode(subscription.reader, VERSION); expect(await entry()).toMatchObject({ suffix: Path.from("mine"), cluster: { hops: [VIA, self], cost: 4n } }); - broadcast.announce({ hops: [VIA, MID], cost: 8n }); - expect(await entry()).toMatchObject({ - suffix: Path.from("mine"), - cluster: { hops: [VIA, MID, self], cost: 8n }, - }); + broadcast.announce({ hops: [...hops], cost }); + expect(await entry()).toMatchObject({ suffix: Path.from("mine"), cluster: { hops: [...hops, self], cost } }); const more = watch(subscription.reader.u53()); await flush(); @@ -1128,9 +1131,9 @@ test("a solicited namespace is repriced with one NAMESPACE and no NAMESPACE_DONE }); /** - * A different broadcast is not a reprice, and neither is a different original publisher: - * the cluster draft has that withdrawn and advertised again, so a receiver never reads two - * publishers' content as one stream. + * A different broadcast is not a reprice, and on a PUBLISH_NAMESPACE neither is a different + * original publisher: the cluster draft has that withdrawn and advertised again, so a + * receiver never reads two publishers' content as one stream. */ const RESTARTS = [ [ @@ -1165,7 +1168,7 @@ test.each(RESTARTS)("%s withdraws the PUBLISH_NAMESPACE and advertises again", a } }); -test.each(RESTARTS)("%s withdraws the solicited NAMESPACE and sends it again", async (_, restart) => { +test("a republish withdraws the solicited NAMESPACE and sends it again", async () => { const { pair, pub, origin, close } = clustered(true); try { const broadcast = origin.createBroadcast(Path.from("mine")); @@ -1181,7 +1184,8 @@ test.each(RESTARTS)("%s withdraws the solicited NAMESPACE and sends it again", a expect(await subscription.reader.u53()).toBe(SubscribeNamespaceEntry.id); await SubscribeNamespaceEntry.decode(subscription.reader, VERSION, true); - restart(origin, broadcast); + const [, republish] = RESTARTS[0]; + republish(origin, broadcast); expect(await subscription.reader.u53()).toBe(SubscribeNamespaceEntryDone.id); expect((await SubscribeNamespaceEntryDone.decode(subscription.reader, VERSION)).suffix).toBe(Path.from("mine")); diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 68bc40d6354..75124c97550 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -58,26 +58,28 @@ function clusterFor(base: Cluster.Advert | undefined, route: Route): Cluster.Adv * * - `"same"`: the peer would decode the same advertisement. The cold cost, and the whole * route without Cluster, never reach the wire, so a change there sends nothing. - * - `"restart"`: nothing is held, nothing is wanted, a different broadcast, or a different - * original publisher, which draft-lcurley-moq-cluster has withdrawn and advertised again - * so a receiver never reads two publishers' content as one stream. - * - Otherwise the same broadcast from the same original publisher at a new hop chain or - * warm cost, repriced in place with only the parameters that changed. + * - `"restart"`: nothing is held, nothing is wanted, or a different broadcast, which is + * withdrawn and advertised again. + * - Otherwise the same broadcast at a new hop chain or warm cost: the cluster parameters + * the peer holds and the ones it should, for the target to update. */ function change( base: Cluster.Advert | undefined, held: Advertised | undefined, next: Advertised | undefined, -): "same" | "restart" | Cluster.Update { +): "same" | "restart" | Reprice { if (held === undefined || next === undefined || held.identity !== next.identity) return "restart"; - const x = clusterFor(base, held.route); - const y = clusterFor(base, next.route); - if (x === undefined || y === undefined) return x === y ? "same" : "restart"; - - const hops = sameHops(x.hops, y.hops); - if (hops && x.cost === y.cost) return "same"; - if (x.hops[0] !== y.hops[0]) return "restart"; - return { hops: hops ? undefined : y.hops, cost: x.cost === y.cost ? undefined : y.cost }; + const from = clusterFor(base, held.route); + const to = clusterFor(base, next.route); + if (from === undefined || to === undefined) return from === to ? "same" : "restart"; + if (from.cost === to.cost && sameHops(from.hops, to.hops)) return "same"; + return { from, to }; +} + +/** A held advertisement's cluster parameters, and the ones the peer should hold instead. */ +interface Reprice { + from: Cluster.Advert; + to: Cluster.Advert; } /** Whether two hop paths list the same hops in the same order. */ @@ -133,8 +135,8 @@ interface Target { /** Advertise a namespace the peer does not hold. */ advertise(key: Path.Valid, next: Advertised): Promise; - /** Reprice a namespace the peer holds, from the same original publisher. */ - update(key: Path.Valid, next: Advertised, update: Cluster.Update): Promise; + /** Reprice a namespace the peer holds: the same broadcast at a new hop chain or cost. */ + update(key: Path.Valid, next: Advertised, reprice: Reprice): Promise; /** Withdraw a namespace the peer holds. */ withdraw(key: Path.Valid): Promise; @@ -816,8 +818,9 @@ export class Publisher { (this.#requiresSolicitation || (this.#hidden && hiddenBelow(Path.empty(), covered))); // Inline entries always land, and the receiver treats a repeated NAMESPACE as a - // replacement, so repricing one is just sending it again. Only a legacy - // PUBLISH_NAMESPACE request can be declined. + // replacement, so repricing one is just sending it again, a new original + // publisher included, as Rust does. Only a legacy PUBLISH_NAMESPACE request can + // be declined. const namespace = async (suffix: Path.Valid, snap: Advertised): Promise => { await stream.writer.u53(SubscribeNamespaceEntry.id); const cluster = clusterFor(this.#advert, snap.route); @@ -828,7 +831,7 @@ export class Publisher { ? { advertise: (suffix, snap) => this.#advertise(Path.join(prefix, suffix), requests, clusterFor(this.#advert, snap.route)), - update: (suffix, _snap, update) => this.#update(Path.join(prefix, suffix), requests, update), + update: (suffix, _snap, reprice) => this.#update(Path.join(prefix, suffix), requests, reprice), withdraw: (suffix) => this.#withdraw(Path.join(prefix, suffix), requests), } : { @@ -906,7 +909,7 @@ export class Publisher { const requests: Requests = new Map(); const target: Target = { advertise: (path, snap) => this.#advertise(path, requests, clusterFor(this.#advert, snap.route)), - update: (path, _snap, update) => this.#update(path, requests, update), + update: (path, _snap, reprice) => this.#update(path, requests, reprice), withdraw: (path) => this.#withdraw(path, requests), }; @@ -1156,11 +1159,24 @@ export class Publisher { * REQUEST_ERROR closes the peer's side and withdraws the advertisement, so ours is * finished too, and an unanswered update is dropped abruptly, since a peer that ignored * it cannot be assumed to hold either price. Either way the retry re-offers it fresh. + * + * A different original publisher is not an update. draft-lcurley-moq-cluster has it + * withdrawn and advertised again, so the receiver never reads two publishers' content + * as one continuous stream. A NAMESPACE has no such rule and is simply sent again. */ - async #update(path: Path.Valid, requests: Requests, update: Cluster.Update): Promise { + async #update(path: Path.Valid, requests: Requests, { from, to }: Reprice): Promise { + if (from.hops[0] !== to.hops[0]) { + await this.#withdraw(path, requests); + return await this.#advertise(path, requests, to); + } + const request = requests.get(path); if (!request) return "dropped"; + const update: Cluster.Update = { + hops: sameHops(from.hops, to.hops) ? undefined : to.hops, + cost: from.cost === to.cost ? undefined : to.cost, + }; const version = this.#session.version; let answer: Answer; try { diff --git a/quest/m1/cluster-publisher-in-place.md b/quest/m1/cluster-publisher-in-place.md index fcdb9a15527..d58c7231e65 100644 --- a/quest/m1/cluster-publisher-in-place.md +++ b/quest/m1/cluster-publisher-in-place.md @@ -73,10 +73,10 @@ withdraw fallback and no negotiation. namespace. Emit an in-place update instead. In-flight subscriptions drain the old copy, and new requests neither reuse the old publisher's cached track info nor splice onto a live subscription, matching Rust. -- JS sender `js/net/src/ietf/publisher.ts` (`change`): a first-hop change - returns an update instead of `"restart"`, so both the PUBLISH_NAMESPACE - path (REQUEST_UPDATE) and the inline path (a re-sent NAMESPACE) update in - place instead of withdrawing. +- JS sender `js/net/src/ietf/publisher.ts` (`#update`): the + PUBLISH_NAMESPACE path stops withdrawing on a first-hop change and sends a + REQUEST_UPDATE, as Rust will; the inline path already re-sends NAMESPACE in + place, like Rust's. - Docs: `doc/bin/relay/cluster.md`, and any `doc/concept` page that describes the cluster extension, say a publisher change updates in place, in-flight subscriptions drain the old publisher, and new requests take the From a9888e4113304c03f60c972a6e76d4e5aa0138b4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 16:12:44 -0700 Subject: [PATCH 068/128] claim quest/m1/cluster-publisher-in-place Co-Authored-By: Claude Opus 5.5 From 42a1fb5f32176c0b43286f04178d3b6d3a1fbd9c Mon Sep 17 00:00:00 2001 From: t0ms Date: Wed, 30 Sep 2026 00:19:56 +0100 Subject: [PATCH 069/128] feat(cli): linger export ts across a broadcast that leaves and returns (#4504) Co-authored-by: Claude Opus 5.5 Co-authored-by: Cursor Co-authored-by: Luke Curley --- doc/bin/cli.md | 8 + quest/m1/README.md | 1 - quest/m1/export-linger.md | 39 ---- quest/m1/hls-linger.md | 4 - quest/m1/track-tail-interop.md | 3 +- rs/moq-cli/src/args.rs | 36 ++++ rs/moq-cli/src/main.rs | 1 + rs/moq-cli/src/subscribe.rs | 105 ++++++++-- rs/moq-cli/tests/export.rs | 212 ++++++++++++++++++++ rs/moq-mux/src/container/flv/export.rs | 18 +- rs/moq-mux/src/container/flv/export_test.rs | 87 ++++++++ rs/moq-mux/src/container/ts/export.rs | 82 +++++++- rs/moq-mux/src/container/ts/export_test.rs | 167 +++++++++++++++ rs/moq-mux/src/source.rs | 39 ++++ 14 files changed, 720 insertions(+), 82 deletions(-) delete mode 100644 quest/m1/export-linger.md create mode 100644 rs/moq-cli/tests/export.rs diff --git a/doc/bin/cli.md b/doc/bin/cli.md index 6b01b5d81b0..9c5d484e052 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -322,6 +322,14 @@ not arrival order, so two exporters of one broadcast emit them in one order. A track quiet for longer is muxed around until it catches up; a sparse track (SCTE-35) costs that wait once per cue. `--max-age 0` keeps arrival order. +A stdout export ends with the broadcast. `export ts --linger 10s` waits that +long for the broadcast to come back instead: a publisher that restarts within +it is picked up under the same PIDs, with the break flagged (PCR discontinuity, +PAT/PMT re-sent). Nothing is written while it is gone. When the linger runs out, +the exit code is that of the last end: 0 if the broadcast finished cleanly, 1 if +it dropped or failed. The default is `0s`, which exits on the first end the same +way. Only `ts` can mark the restart, so the other formats refuse `--linger`. + ## Debugging `RUST_LOG=debug` prints the negotiated version and every subscription. diff --git a/quest/m1/README.md b/quest/m1/README.md index 82e217cb564..e64ee5a520b 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -141,7 +141,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Catalog warmup](/quest/m1/catalog-warmup.md) - `warmup` on video and audio renditions, in the catalog and the draft - [Audio warmup](/quest/m1/audio-warmup.md) - a viewer joining an Opus rendition mid-stream never hears the unconverged first 80 ms - [#3021](/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md) - GStreamer maps every pad onto one continuous broadcast clock across source restarts -- [Export linger](/quest/m1/export-linger.md) - every `moq export` waits `--linger` for a broadcast to return, and exits 0 on a clean end and 1 on a drop - [TS byte schedule](/quest/m1/ts-export-byte-schedule.md) - moq export ts places PCRs and padding on the byte grid `mpegts.muxRate` implies, so a receiver can clock off arrival - [Text availability](/quest/m1/text-schema.md) - a text track publishes its own coverage index instead of copying the media timeline - [ID3 catalog section](/quest/m1/id3.md) - timed ID3 as a first-class container-neutral catalog section diff --git a/quest/m1/export-linger.md b/quest/m1/export-linger.md deleted file mode 100644 index 7c590f12a89..00000000000 --- a/quest/m1/export-linger.md +++ /dev/null @@ -1,39 +0,0 @@ -# [M] moq export: a linger rides out a broadcast that leaves and returns - -## Goal - -Every `moq export ` can outlive a session bounce or a publisher -restart. `--linger ` (default 0) is how long the exporter waits for -the broadcast to be announced again after it goes away; when it returns, the -output resumes after a discontinuity, and while it is gone the output simply -stops (no stuffing, so carrier and content liveness stay one event). The exit -code says how the broadcast ended: 0 when the catalog track finished cleanly, -1 when it was dropped or anything else failed. Today every export subscribes -once and exits 1 with `json: dropped`, even while `moq_tokio` is mid-reconnect -(#3926). - -## Plan - -- A catalog FIN and a drop both wait out the linger, so a planned publisher - restart is covered; when the wait expires, the exit code reflects the last - end. With the default of 0, a FIN exits 0 and a drop exits 1 immediately. -- One implementation in the shared export path: `run_stdout` in - `rs/moq-cli/src/main.rs` and `moq_mux::Source`, not per format. Re-resolve - with `origin::Consumer::routed_broadcast` after the old broadcast ends; the - origin already outlives each session. -- A return is a new catalog on the same exporter: each format writes it the - way it already writes a catalog change or discontinuity (TS sets the - discontinuity indicator and re-emits PSI). A format that cannot express a - restart refuses a non-zero `--linger` at startup. -- `drive()` currently maps every clean task end and every error the same way; - thread the FIN versus drop distinction through to the exit code. -- The fixed-layout exporters report a track that finished before the catalog - as removed: TS as `TS track layout changed ... removed` (reproducible with - `test/ts/run.sh --pair`), FLV as `FLV track ... removed mid-stream`. A clean - end can exit 1 before linger applies. A finished track is not a removed - one; tell them apart in both, with a regression test each (#3926). -- `doc/bin/cli.md`: document `--linger` and the exit codes next to - `export --max-age`. -- Tests: a relay-backed CLI test that restarts the publisher within the linger - and sees output resume, one that lets it expire and checks exit 1, and a - clean FIN that exits 0. diff --git a/quest/m1/hls-linger.md b/quest/m1/hls-linger.md index 9da2c54d1c4..d240cdf86ce 100644 --- a/quest/m1/hls-linger.md +++ b/quest/m1/hls-linger.md @@ -35,7 +35,3 @@ Guidance: - Tests: a request inside the linger after close still gets the playlist and a cached segment; after it expires the name 404s; a republish inside the linger is served. - -## Related - -- [Export linger](/quest/m1/export-linger.md) - the CLI exporter's wait for a broadcast to return; same idea, separate code diff --git a/quest/m1/track-tail-interop.md b/quest/m1/track-tail-interop.md index f33cff39350..7e664668ffa 100644 --- a/quest/m1/track-tail-interop.md +++ b/quest/m1/track-tail-interop.md @@ -19,8 +19,7 @@ What stood in the way when the Rust half landed: - `moq import` exits the moment stdin ends, closing its session with the tail still in flight, so a finite CLI publisher cannot end a track cleanly. The fix is a publisher that waits for its subscriptions to drain before it - closes; `moq export`'s linger ([Export linger](/quest/m1/export-linger.md)) is - the reader-side cousin. + closes; `moq export ts --linger` is the reader-side cousin. - The native JS subscriber (`test/interop/clients/js-native`) returns on the first frame. It needs a mode that reads a track to its end and reports how it ended and which groups it saw. diff --git a/rs/moq-cli/src/args.rs b/rs/moq-cli/src/args.rs index 61a81d78017..b2c659e1eb5 100644 --- a/rs/moq-cli/src/args.rs +++ b/rs/moq-cli/src/args.rs @@ -282,6 +282,17 @@ impl Invocation { /// Called before anything binds a port or dials out, so a refused invocation has /// no side effects to unwind. pub fn validate(&self) -> anyhow::Result<()> { + for command in &self.stages { + if let Command::Export(export) = command + && let Some(stdout) = export.sink.stdout() + { + anyhow::ensure!( + stdout.linger.is_zero() || matches!(stdout.format, SubscribeFormat::Ts), + "--linger needs an output that can mark a restart, and only `export ts` can" + ); + } + } + // One stage is what the CLI has always run, so nothing below can bite. if self.stages.len() == 1 { return Ok(()); @@ -893,6 +904,7 @@ impl ExportSink { let container = |format, container: &Container| Stdout { format, max_age: container.max_age.into_std(), + linger: container.linger.into_std(), fragment_duration: None, mux_rate: None, }; @@ -921,6 +933,7 @@ impl ExportSink { pub struct Stdout { pub format: SubscribeFormat, pub max_age: Duration, + pub linger: Duration, pub fragment_duration: Option, pub mux_rate: Option, } @@ -933,6 +946,11 @@ pub struct Container { #[usage(long, default = "500ms")] pub max_age: crate::duration::Duration, + /// How long to wait for the broadcast to come back once it ends (e.g. `10s`). + /// `ts` only; the output stops while it is gone and resumes flagged as a break. + #[usage(long, default = "0s")] + pub linger: crate::duration::Duration, + /// The released spelling of [`Self::max_age`]. #[usage(long = "latency-max", hide = true)] latency_max: Option, @@ -1003,6 +1021,24 @@ mod tests { assert!(cli.validate().is_ok()); } + /// Only TS can mark where a returned broadcast restarts, so only `export ts` may linger. + #[test] + fn linger_is_ts_only() { + let parse = |format: &str, linger: &str| { + Invocation::try_parse_from(["moq", "--connect", "http://relay", "export", format, "--linger", linger]) + .unwrap() + }; + assert!(parse("ts", "10s").validate().is_ok()); + for format in ["fmp4", "mkv", "flv", "h264", "h265"] { + let err = parse(format, "10s").validate().unwrap_err().to_string(); + assert!(err.contains("--linger"), "{format}: {err}"); + assert!( + parse(format, "0s").validate().is_ok(), + "{format}: no linger is always fine" + ); + } + } + #[test] fn import_ts_takes_a_program_number_or_all() { // `None` when the command line is refused. diff --git a/rs/moq-cli/src/main.rs b/rs/moq-cli/src/main.rs index ff8c09359d0..d339abe70c6 100644 --- a/rs/moq-cli/src/main.rs +++ b/rs/moq-cli/src/main.rs @@ -716,6 +716,7 @@ fn spawn_export( let args = SubscribeArgs { format: stdout.format, max_age: stdout.max_age, + linger: stdout.linger, fragment_duration: stdout.fragment_duration, mux_rate: stdout.mux_rate, catalog: export.catalog_format, diff --git a/rs/moq-cli/src/subscribe.rs b/rs/moq-cli/src/subscribe.rs index 0680d83f8b8..2d1d8f67c58 100644 --- a/rs/moq-cli/src/subscribe.rs +++ b/rs/moq-cli/src/subscribe.rs @@ -139,6 +139,9 @@ pub struct SubscribeArgs { /// How far playback may drift from the live edge before skipping groups. pub max_age: Duration, + /// How long to wait for the broadcast to come back after it ends (TS only). + pub linger: Duration, + /// Cap the output duration: publisher groups by default for fMP4, video GOPs for MKV. pub fragment_duration: Option, @@ -300,6 +303,8 @@ impl Subscribe { // is re-framed as ADTS. `fragment_duration` does not apply to TS. `with_ts` // selects the `mpegts` catalog extension so undecoded elementary streams // (SCTE-35, teletext, DVB AC-3, ...) are re-emitted verbatim on their PIDs. + let source = self.source.clone(); + let mut broadcast = source.broadcast().await?; let mut ts = moq_mux::container::ts::Export::with_ts(self.source, self.catalog) .await? .with_max_age(self.args.max_age); @@ -316,23 +321,44 @@ impl Subscribe { // bounded; it needs to know whether each frame was waited for, hence the // hand-rolled poll instead of `ts.next()`. let mut delivery = Delivery::new(self.args.max_age); + let linger = self.args.linger; loop { - let mut waited = false; - let frame = hang::moq_net::kio::wait(|waiter| match ts.poll_next(waiter) { - std::task::Poll::Pending => { - waited = true; - std::task::Poll::Pending - } - ready => ready, - }) - .await?; - - let Some(frame) = frame else { break }; - delivery.update(&frame, ts.discontinuity()); - delivery.deliver(&frame, waited, &mut stdout).await?; + let end = loop { + let mut waited = false; + let frame = hang::moq_net::kio::wait(|waiter| match ts.poll_next(waiter) { + std::task::Poll::Pending => { + waited = true; + std::task::Poll::Pending + } + ready => ready, + }) + .await; + + let frame = match frame { + Ok(Some(frame)) => frame, + Ok(None) => break Ok(()), + Err(err) => break Err(err), + }; + delivery.update(&frame, ts.discontinuity()); + delivery.deliver(&frame, waited, &mut stdout).await?; + }; + + // Any end waits out the linger, and on expiry the last one is the result: a + // clean catalog finish exits 0, a drop or any other failure exits 1. + if linger.is_zero() { + return Ok(end?); + } + match &end { + Ok(()) => tracing::info!(?linger, "broadcast finished, waiting for it to return"), + Err(err) => tracing::warn!(%err, ?linger, "broadcast ended, waiting for it to return"), + } + let Some(returned) = resume_within(&source, &broadcast, &mut ts, linger).await? else { + tracing::info!(?linger, "broadcast did not return"); + return Ok(end?); + }; + broadcast = returned; + tracing::info!("broadcast returned, resuming"); } - - Ok(()) } async fn run_flv(self) -> anyhow::Result<()> { @@ -355,6 +381,28 @@ impl Subscribe { } } +/// Wait up to `linger` for the `ended` broadcast to return and `ts` to resume on it. +/// +/// The linger bounds the whole return, catalog subscription included: a returned +/// broadcast whose catalog never resolves must not hold the export past it. `None` +/// when it did not return in time. +async fn resume_within( + source: &moq_mux::Source, + ended: &hang::moq_net::broadcast::Consumer, + ts: &mut moq_mux::container::ts::Export, + linger: Duration, +) -> anyhow::Result> { + let resume = async { + let returned = source.returned(ended).await?; + ts.resume().await?; + anyhow::Ok(returned) + }; + match tokio::time::timeout(linger, resume).await { + Ok(returned) => Ok(Some(returned?)), + Err(_) => Ok(None), + } +} + /// Paced stdout delivery for the TS export: sleeps until each frame's send /// instant, with total delivery lag bounded by the latency budget. /// @@ -675,4 +723,31 @@ mod tests { delivery.deliver(&next, false, &mut out).await.unwrap(); assert_eq!(now.elapsed(), Duration::from_millis(40)); } + + /// A broadcast that returns but never serves its catalog gives up at the linger, + /// rather than waiting on the catalog past it. + #[tokio::test(start_paused = true)] + async fn a_return_without_a_catalog_expires_with_the_linger() { + let (origin, driver) = hang::moq_net::origin::Producer::new(Default::default()); + tokio::spawn(hang::moq_net::time::run(driver)); + let source = moq_mux::Source::new(origin.consume(), "live"); + + let mut first = origin.publish("live", Default::default()).unwrap(); + let catalog = moq_mux::catalog::Producer::new(&mut first, Default::default()).unwrap(); + let ended = source.broadcast().await.unwrap(); + let mut ts = moq_mux::container::ts::Export::with_ts(source.clone(), CatalogFormat::Hang) + .await + .unwrap(); + drop((first, catalog)); + + // Back, but its catalog request is never answered. + let second = origin.publish("live", Default::default()).unwrap(); + let _unanswered = second.dynamic(); + + let linger = Duration::from_secs(10); + let start = tokio::time::Instant::now(); + let resumed = resume_within(&source, &ended, &mut ts, linger).await.unwrap(); + assert!(resumed.is_none(), "a return that never resumes is no return"); + assert_eq!(start.elapsed(), linger); + } } diff --git a/rs/moq-cli/tests/export.rs b/rs/moq-cli/tests/export.rs new file mode 100644 index 00000000000..3815187993a --- /dev/null +++ b/rs/moq-cli/tests/export.rs @@ -0,0 +1,212 @@ +//! `moq export ts --linger` over a real relay: the export rides out a publisher that +//! leaves and comes back, and exits with the verdict of the broadcast's last end. +#![cfg(unix)] + +use std::process::Stdio; +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +use tokio::io::{AsyncReadExt, AsyncWriteExt}; +use tokio::process::{Child, ChildStdin}; +use tokio::task::JoinHandle; + +const TIMEOUT: Duration = Duration::from_secs(30); +/// About three seconds of HEVC and Opus. +const CLIP: &[u8] = include_bytes!("../../moq-mux/src/container/ts/test_data/bbb_cbr.ts"); + +type Output = Arc>>; + +struct Relay { + url: String, + fingerprint: String, +} + +async fn relay() -> Relay { + let _ = moq_tokio::crypto::install_default(); + let fixture = moq_relay::test_relay().await.expect("test relay"); + let ready = fixture.relay.ready(); + tokio::spawn(fixture.relay.run()); + ready.wait().await.expect("relay ready"); + Relay { + url: fixture.url.to_string(), + fingerprint: fixture.fingerprint, + } +} + +fn moq(relay: &Relay, args: &[&str]) -> tokio::process::Command { + let mut command = tokio::process::Command::new(env!("CARGO_BIN_EXE_moq")); + // A `MOQ_*` variable in the developer's shell must not reconfigure the child. + for (name, _) in std::env::vars_os() { + if name.to_string_lossy().starts_with("MOQ_") { + command.env_remove(name); + } + } + command + .args([ + "--connect", + &relay.url, + "--connect-tls-fingerprint", + &relay.fingerprint, + "--broadcast", + "demo", + ]) + .args(args) + .kill_on_drop(true); + command +} + +/// Start `moq export ts --linger `, collecting its stdout. +fn export(relay: &Relay, linger: &str) -> (Child, Output) { + let mut child = moq(relay, &["export", "ts", "--linger", linger]) + .stdout(Stdio::piped()) + .spawn() + .expect("spawn export"); + let mut stdout = child.stdout.take().expect("stdout"); + let output = Output::default(); + let sink = output.clone(); + tokio::spawn(async move { + let mut buf = vec![0; 64 * 1024]; + while let Ok(n) = stdout.read(&mut buf).await + && n > 0 + { + sink.lock().unwrap().extend_from_slice(&buf[..n]); + } + }); + (child, output) +} + +/// Start `moq import ts` and feed it the clip at about real time, handing stdin back +/// once it is all written. Closing stdin then finishes the broadcast. +fn import(relay: &Relay) -> (Child, JoinHandle) { + let mut child = moq(relay, &["import", "ts"]) + .stdin(Stdio::piped()) + .spawn() + .expect("spawn import"); + let mut stdin = child.stdin.take().expect("stdin"); + let feeding = tokio::spawn(async move { + for chunk in CLIP.chunks(188 * 40) { + stdin.write_all(chunk).await.expect("write stdin"); + tokio::time::sleep(Duration::from_millis(150)).await; + } + stdin + }); + (child, feeding) +} + +/// Wait until the export has written more than `len` bytes. +async fn output_past(output: &Output, len: usize) { + tokio::time::timeout(TIMEOUT, async { + while output.lock().unwrap().len() <= len { + tokio::time::sleep(Duration::from_millis(50)).await; + } + }) + .await + .expect("the export wrote nothing"); +} + +/// End the publisher the way an operator does, which drops the broadcast unfinished. +async fn interrupt(mut child: Child, stdin: ChildStdin) { + let pid = child.id().expect("running").to_string(); + let status = std::process::Command::new("kill") + .args(["-INT", &pid]) + .status() + .expect("kill"); + assert!(status.success()); + // The interrupted process exits once its stdin read returns; closing stdin any + // sooner could land first and finish the broadcast instead. + tokio::time::sleep(Duration::from_millis(500)).await; + drop(stdin); + wait(&mut child).await; +} + +async fn wait(child: &mut Child) -> std::process::ExitStatus { + tokio::time::timeout(TIMEOUT, child.wait()) + .await + .expect("moq never exited") + .expect("wait for moq") +} + +/// The 188-byte packets of `ts`, checking they are aligned. +fn packets(ts: &[u8]) -> impl Iterator { + ts.as_chunks::<188>() + .0 + .iter() + .inspect(|packet| assert_eq!(packet[0], 0x47, "the output is packet aligned")) +} + +fn pid(packet: &[u8]) -> u16 { + u16::from(packet[1] & 0x1f) << 8 | u16::from(packet[2]) +} + +/// The adaptation field flags byte, when the packet carries a non-empty adaptation field. +fn adaptation_flags(packet: &[u8]) -> Option { + (packet[3] & 0x20 != 0 && packet[4] > 0).then_some(packet[5]) +} + +#[tokio::test] +async fn a_clean_finish_exits_zero_once_the_linger_expires() { + let relay = relay().await; + let (mut export, output) = export(&relay, "1s"); + + let (mut publisher, feeding) = import(&relay); + let stdin = feeding.await.unwrap(); + output_past(&output, 0).await; + drop(stdin); + assert!(wait(&mut publisher).await.success()); + let finished = Instant::now(); + + let status = wait(&mut export).await; + assert!(status.success(), "a clean finish exits 0, got {status}"); + assert!( + finished.elapsed() >= Duration::from_millis(900), + "the export waited out its linger" + ); +} + +#[tokio::test] +async fn a_drop_exits_one_once_the_linger_expires() { + let relay = relay().await; + let (mut export, output) = export(&relay, "1s"); + + let (publisher, feeding) = import(&relay); + let stdin = feeding.await.unwrap(); + output_past(&output, 0).await; + interrupt(publisher, stdin).await; + + let status = wait(&mut export).await; + assert_eq!(status.code(), Some(1), "a drop exits 1, got {status}"); +} + +#[tokio::test] +async fn a_publisher_restarted_within_the_linger_resumes_the_output() { + let relay = relay().await; + let (mut export, output) = export(&relay, "10s"); + + let (publisher, feeding) = import(&relay); + let stdin = feeding.await.unwrap(); + output_past(&output, 0).await; + interrupt(publisher, stdin).await; + // Let the paced tail of the first broadcast drain before marking where it ended. + tokio::time::sleep(Duration::from_secs(1)).await; + let mark = output.lock().unwrap().len().next_multiple_of(188); + + let (mut publisher, feeding) = import(&relay); + let stdin = feeding.await.unwrap(); + output_past(&output, mark).await; + drop(stdin); + assert!(wait(&mut publisher).await.success()); + + let status = wait(&mut export).await; + assert!(status.success(), "the last end was a clean finish, got {status}"); + + let output = output.lock().unwrap(); + let after = &output[mark..]; + let total = packets(after).count(); + assert!(total > 100, "the returned broadcast went out: {total} packets"); + assert!(packets(after).any(|p| pid(p) == 0), "PAT re-emitted after the restart"); + // The PCR the returned broadcast opens with flags the break. + let first_pcr = packets(after) + .find_map(|p| adaptation_flags(p).filter(|flags| flags & 0x10 != 0)) + .expect("a PCR after the restart"); + assert_ne!(first_pcr & 0x80, 0, "the restart is flagged as a break"); +} diff --git a/rs/moq-mux/src/container/flv/export.rs b/rs/moq-mux/src/container/flv/export.rs index 7351124656e..04f362726cd 100644 --- a/rs/moq-mux/src/container/flv/export.rs +++ b/rs/moq-mux/src/container/flv/export.rs @@ -339,16 +339,10 @@ impl Export { tracing::warn!("ignoring FLV rendition that appeared after the stream header"); } - // A bound track vanishing from the catalog is a layout change FLV can't express. - for track in self.tracks() { - let present = if is_video_flavor(track.flavor) { - catalog.video.renditions.contains_key(&track.name) - } else { - catalog.audio.renditions.contains_key(&track.name) - }; - anyhow::ensure!(present, "FLV track '{}' removed mid-stream", track.name); - } - + // A bound track leaving the catalog is read to its own end rather than refused. A + // publisher retires a rendition as its track finishes or drops, and the catalog + // update races that end on another stream, so only the track's end can say which it + // was: a finish ends it cleanly, and a drop is the error the export reports. Ok(()) } @@ -696,10 +690,6 @@ fn ensure_legacy(container: &Container, kind: &str, name: &str) -> anyhow::Resul } } -fn is_video_flavor(flavor: Flavor) -> bool { - matches!(flavor, Flavor::Avc | Flavor::Hevc | Flavor::Av1 | Flavor::Vp9) -} - fn video_flavor(config: &hang::catalog::VideoConfig) -> anyhow::Result { match &config.codec { VideoCodec::H264(_) => Ok(Flavor::Avc), diff --git a/rs/moq-mux/src/container/flv/export_test.rs b/rs/moq-mux/src/container/flv/export_test.rs index 46941f1c70d..1c1679db135 100644 --- a/rs/moq-mux/src/container/flv/export_test.rs +++ b/rs/moq-mux/src/container/flv/export_test.rs @@ -995,6 +995,93 @@ async fn export_authors_dts_and_composition_time_for_reordered_avc() { ); } +/// Poll `exporter` into `out` until it ends or goes idle; `None` if it went idle. +async fn drain_until_idle(exporter: &mut Export, out: &mut Vec) -> Option> { + loop { + match tokio::time::timeout(Duration::from_millis(100), exporter.next()).await { + Ok(Ok(Some(chunk))) => out.extend_from_slice(&chunk), + Ok(Ok(None)) => return Some(Ok(())), + Ok(Err(e)) => return Some(Err(e)), + Err(_) => return None, + } + } +} + +/// A bound track that leaves the catalog is read to its own end, not refused as removed: +/// a publisher retires a rendition as its track ends, and the catalog update can land first. +#[tokio::test(start_paused = true)] +async fn a_track_leaving_the_catalog_is_read_to_its_end() { + use hang::catalog::{AAC, AudioConfig, Container, H264, VideoConfig}; + use moq_net::Timestamp; + + let mut producer = moq_net::broadcast::Info::new().produce(); + let consumer = producer.consume(); + + let mut catalog = crate::catalog::Producer::new(&mut producer, crate::catalog::Config::default()).unwrap(); + let video_track = producer.create_track(producer.unique_name(".avc1"), None).unwrap(); + let audio_track = producer.create_track(producer.unique_name(".aac"), None).unwrap(); + let audio_name = audio_track.name().to_string(); + + let mut video_config = VideoConfig::new(H264 { + profile: 0x42, + constraints: 0xc0, + level: 0x1f, + inline: false, + }); + video_config.container = Container::Legacy; + video_config.description = Some(Bytes::from(avcc())); + let mut audio_config = AudioConfig::new(AAC { profile: 2 }, 44100, 2); + audio_config.container = Container::Legacy; + audio_config.description = Some(Bytes::from_static(&ASC)); + { + let mut catalog = catalog.modify().unwrap(); + catalog + .video + .renditions + .insert(video_track.name().to_string(), video_config); + catalog.audio.renditions.insert(audio_name.clone(), audio_config); + } + + let legacy = || crate::catalog::hang::Container::Legacy(crate::container::Kind::Data); + let mut video = crate::container::Producer::new(video_track, legacy()); + let mut audio = crate::container::Producer::new(audio_track, legacy()); + let frame = |timestamp_ms: u64, payload: &'static [u8], keyframe| crate::container::Frame { + timestamp: Timestamp::from_millis(timestamp_ms).unwrap(), + duration: None, + payload: Bytes::from_static(payload), + keyframe, + }; + video.write(frame(0, &[0, 0, 0, 1, 0x65], true)).unwrap(); + audio.write(frame(0, &[0xde, 0xad], true)).unwrap(); + + let mut exporter = Export::new(crate::source::announced(&consumer)) + .await + .unwrap() + .with_max_age(RECORDING_MAX_AGE); + let mut exported = Vec::new(); + assert!(drain_until_idle(&mut exporter, &mut exported).await.is_none()); + + // The audio rendition retires before its tail lands; the video carries on. + catalog.modify().unwrap().audio.renditions.remove(&audio_name); + audio.write(frame(23, &[0xbe, 0xef], true)).unwrap(); + audio.finish().unwrap(); + video.write(frame(33, &[0, 0, 0, 1, 0x41], false)).unwrap(); + video.finish().unwrap(); + catalog.finish().unwrap(); + + let end = drain_until_idle(&mut exporter, &mut exported).await; + assert!( + matches!(end, Some(Ok(()))), + "a track leaving the catalog is not a layout change: {end:?}" + ); + let tags = parse_tags(&exported); + let audio_frames = tags + .iter() + .filter(|t| t.tag_type == super::TAG_AUDIO && t.body[1] == super::AAC_RAW) + .count(); + assert_eq!(audio_frames, 2, "the leaving track's tail went out"); +} + async fn drain_exporter_chunks(mut exporter: Export, chunks: usize) -> Vec { let mut exported = Vec::new(); for _ in 0..chunks { diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index a75f27b1453..20308810eae 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -16,7 +16,7 @@ //! length-prefixed -> Annex-B conversion, re-injecting the parameter sets as //! inline NALs on every keyframe. CMAF tracks are rejected with a clear error. -use std::collections::{BTreeMap, HashMap, VecDeque}; +use std::collections::{BTreeMap, HashMap, HashSet, VecDeque}; use std::pin::Pin; use std::task::Poll; use std::time::Duration; @@ -113,6 +113,10 @@ fn sanitize_mux_rate(rate: u64) -> Option { pub struct Export { source: crate::Source, catalog: Option>, + catalog_format: CatalogFormat, + /// Tracks [`Self::resume`] left on the ended broadcast, resubscribed as the + /// returned catalog lists them. + stale: HashSet, max_age: Duration, tracks: HashMap, @@ -661,6 +665,8 @@ impl Export { Ok(Self { source, catalog: Some(catalog), + catalog_format, + stale: HashSet::new(), max_age: Duration::ZERO, tracks: HashMap::new(), counters: HashMap::new(), @@ -1057,7 +1063,13 @@ impl Export { } } - // The program tables are written once; reject layout changes afterwards. + // The program tables are written once; reject a track added afterwards. + // + // A track that leaves the catalog is not a layout change: it keeps its PID and is + // read to its own end. A publisher retires a rendition as its track finishes or + // drops, and the catalog update races that end on another stream, so the leaving + // cannot say which it was. The track's end does: a finish ends it cleanly, and a + // drop is the error the export reports. if self.psi.is_some() { for name in active.keys() { anyhow::ensure!( @@ -1065,11 +1077,8 @@ impl Export { "TS track layout changed after PAT/PMT was emitted: '{name}' added" ); } - for name in self.tracks.keys() { - anyhow::ensure!( - active.contains_key(name), - "TS track layout changed after PAT/PMT was emitted: '{name}' removed" - ); + if !self.stale.is_empty() { + self.resubscribe(&catalog, &mpegts)?; } let es_pids: Vec = self.tracks.values().map(|t| t.pid).collect(); reject_colliding_si_pids(&mpegts, self.pmt_pid(), &es_pids)?; @@ -1182,6 +1191,34 @@ impl Export { Ok(()) } + /// Point each stale track this snapshot lists at the returned broadcast. + /// + /// The PIDs and PMT stay as announced. A track the returned catalog does not list stays + /// finished, silent on its PID. + fn resubscribe(&mut self, catalog: &Catalog, mpegts: &catalog::Mpegts) -> anyhow::Result<()> { + for (name, track) in self.tracks.iter_mut() { + if !self.stale.contains(name) { + continue; + } + let source = if let Some(config) = catalog.video.renditions.get(name) { + ExportSource::for_video(&self.source, name, config, self.max_age)? + } else if let Some(config) = catalog.audio.renditions.get(name) { + ExportSource::for_audio(&self.source, name, config, self.max_age)? + } else if mpegts.tracks.get(name).is_some_and(|t| t.verbatim.is_some()) { + Some(ExportSource::for_stream(&self.source, name, self.max_age)?) + } else { + None + }; + let Some(source) = source else { + continue; + }; + self.stale.remove(name); + track.source = source; + track.finished = false; + } + Ok(()) + } + /// Insert a freshly created export track. fn insert_track( &mut self, @@ -1217,6 +1254,37 @@ impl Export { self.emitted_epoch } + /// Carry on with the broadcast that replaced the one this export was reading. + /// + /// Call it once [`Source::returned`](crate::Source::returned) has resolved, after + /// [`next`](Self::next) returned `None` or an error. Whatever the ended broadcast left + /// unwritten is dropped and the program clock restarts, so the next output flags the + /// break and re-emits the PAT/PMT. The returned catalog resubscribes each track as it + /// lists it, under the program already announced; one that adds a track fails as a + /// layout change. + pub async fn resume(&mut self) -> Result<(), crate::Error> { + self.catalog = Some(self.source.catalog::(self.catalog_format).await?); + self.si_flushed = false; + // A name no entry carries, so the returned catalog repoints every SI entry. + for si in self.si.values_mut() { + si.track.clear(); + } + if self.psi.is_none() { + // Nothing announced yet: the returned catalog builds the program afresh. + self.tracks.clear(); + } + // Whatever the ended broadcast left is done, including a track whose error ended + // the export: polled again, it would end this one too. + for (name, track) in self.tracks.iter_mut() { + track.finished = true; + track.pending = None; + track.discontinuity = 0; + self.stale.insert(name.clone()); + } + self.rewind(); + Ok(()) + } + /// Discard uncommitted bytes and restart the program clock. Every rendition /// joins the new generation: no track is fenced across a declared marker. fn rewind(&mut self) { diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index 4c2dec24307..0cdcb50524c 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -5291,3 +5291,170 @@ async fn jitter_published_after_the_tables_raises_the_reserve() { } assert_decodes_after_the_clock(&runner); } + +/// Publish a Legacy AAC rendition named `name`. +fn aac_rendition( + broadcast: &mut moq_net::broadcast::Producer, + catalog: &mut crate::catalog::Producer, + name: &str, +) -> Producer { + let track = broadcast + .create_track(name, hang::container::track_info(hang::catalog::PRIORITY.audio)) + .unwrap(); + let mut cfg = AudioConfig::new(AAC { profile: 2 }, 48_000, 2); + cfg.container = Container::Legacy; + catalog.modify().unwrap().audio.renditions.insert(name.to_string(), cfg); + Producer::new(track, HangContainer::Legacy(crate::container::Kind::Data)) +} + +/// Write one AAC frame at `ms`, in a group of its own. +fn write_aac(producer: &mut Producer, ms: u64) { + producer + .write(Frame { + timestamp: Timestamp::from_millis(ms).unwrap(), + duration: None, + payload: Bytes::from_static(&[0x21, 0x10, 0x04, 0x60]), + keyframe: true, + }) + .unwrap(); + producer.cut(None).unwrap(); +} + +/// Count the PES packets across `frames`. +fn pes_count(frames: &[Frame]) -> usize { + let bytes: Vec = frames.iter().flat_map(|f| f.payload.iter().copied()).collect(); + let mut reader = TsPacketReader::new(Cursor::new(bytes)); + let mut count = 0; + while let Some(packet) = reader.read_ts_packet().unwrap() { + if matches!(packet.payload, Some(TsPayload::PesStart(_))) { + count += 1; + } + } + count +} + +/// Pull frames until the export ends, returning them and how it ended. +async fn drain_to_end(export: &mut Export) -> (Vec, crate::Result<()>) { + let mut out = Vec::new(); + loop { + match tokio::time::timeout(Duration::from_secs(5), export.next()) + .await + .expect("the export ends") + { + Ok(Some(frame)) => out.push(frame), + Ok(None) => return (out, Ok(())), + Err(err) => return (out, Err(err)), + } + } +} + +/// A track that leaves the catalog after the PMT is read to its own end rather than +/// refused as a layout change. A publisher retires a rendition as its track ends, and +/// that catalog update can land before the track's last frames and its finish do, so +/// this retires the rendition first: the order in which the old check misread a clean +/// end as a removed track. +#[tokio::test(start_paused = true)] +async fn a_track_leaving_the_catalog_is_read_to_its_end() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let consumer = broadcast.consume(); + let mut catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + let mut kept = aac_rendition(&mut broadcast, &mut catalog, "a.aac"); + let mut leaving = aac_rendition(&mut broadcast, &mut catalog, "b.aac"); + + let mut export = Export::new(crate::source::announced(&consumer)) + .await + .unwrap() + .with_max_age(RECORDING_MAX_AGE); + for ms in (0..200).step_by(20) { + write_aac(&mut kept, ms); + write_aac(&mut leaving, ms); + } + let mut frames = drain_frames(&mut export).await; + assert!(!frames.is_empty(), "the program started"); + + catalog.modify().unwrap().audio.renditions.remove("b.aac"); + for ms in (200..300).step_by(20) { + write_aac(&mut kept, ms); + write_aac(&mut leaving, ms); + } + leaving.finish().unwrap(); + for ms in (300..400).step_by(20) { + write_aac(&mut kept, ms); + } + kept.finish().unwrap(); + catalog.finish().unwrap(); + + let (rest, end) = drain_to_end(&mut export).await; + end.expect("a track leaving the catalog is not a layout change"); + frames.extend(rest); + assert_eq!(pes_count(&frames), 20 + 15, "every frame of both tracks went out"); +} + +/// A broadcast that ends and is published again carries on in the same export: the +/// returned catalog resubscribes the program's tracks, the clock break is flagged once, +/// and the PAT/PMT go out again for a receiver re-acquiring after the gap. Both ways a +/// broadcast ends, a clean finish and a drop, resume the same way. +async fn resume_after(finish: bool) { + let origin = crate::source::produce_origin(); + let source = crate::Source::new(origin.consume(), "live"); + let publish = || { + let mut broadcast = origin.publish("live", Default::default()).unwrap(); + let catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + (broadcast, catalog) + }; + + let (mut broadcast, mut catalog) = publish(); + let mut track = aac_rendition(&mut broadcast, &mut catalog, "a.aac"); + let ended = source.broadcast().await.unwrap(); + let mut export = Export::new(source.clone()) + .await + .unwrap() + .with_max_age(RECORDING_MAX_AGE); + for ms in (0..200).step_by(20) { + write_aac(&mut track, ms); + } + let mut before = drain_frames(&mut export).await; + if finish { + track.finish().unwrap(); + catalog.finish().unwrap(); + } + drop((broadcast, catalog, track)); + let (rest, end) = drain_to_end(&mut export).await; + before.extend(rest); + assert_eq!(end.is_ok(), finish, "a finish ends cleanly and a drop fails: {end:?}"); + + // The returned catalog lists the track only in its second snapshot, and the restarted + // publisher's clock starts over. + let (mut broadcast, mut catalog) = publish(); + std::ops::DerefMut::deref_mut(&mut catalog.modify().unwrap()); + source.returned(&ended).await.unwrap(); + export.resume().await.unwrap(); + let mut after = drain_frames(&mut export).await; + assert!(after.is_empty(), "nothing to carry before the track is listed"); + let mut track = aac_rendition(&mut broadcast, &mut catalog, "a.aac"); + for ms in (0..200).step_by(20) { + write_aac(&mut track, ms); + } + after.extend(drain_frames(&mut export).await); + track.finish().unwrap(); + catalog.finish().unwrap(); + let (rest, end) = drain_to_end(&mut export).await; + after.extend(rest); + end.unwrap(); + + assert_eq!(export.discontinuity(), 1, "the return is one break"); + assert_eq!(count_discontinuity(&before), 0); + assert_eq!(count_discontinuity(&after), 1, "the break is flagged once"); + assert!(count_pid(&after, 0x0000) >= 1, "PAT re-emitted after the return"); + assert_eq!(pes_count(&after), 10, "the returned broadcast's frames all went out"); +} + +#[tokio::test(start_paused = true)] +async fn resume_after_a_finish() { + resume_after(true).await; +} + +#[tokio::test(start_paused = true)] +async fn resume_after_a_drop() { + resume_after(false).await; +} diff --git a/rs/moq-mux/src/source.rs b/rs/moq-mux/src/source.rs index 7c88e0156fa..9c884ac552d 100644 --- a/rs/moq-mux/src/source.rs +++ b/rs/moq-mux/src/source.rs @@ -59,6 +59,15 @@ impl Source { crate::catalog::Consumer::new(&broadcast, format).await } + /// Wait for the broadcast to come back after `ended`, the one an export was reading, closes. + /// + /// A broadcast that stays up never returns, so a clean catalog end that leaves it announced + /// waits here until the caller's own deadline. Bound the wait with a timeout. + pub async fn returned(&self, ended: &moq_net::broadcast::Consumer) -> crate::Result { + ended.closed().await; + Ok(self.origin.routed_broadcast(&self.path).await?) + } + /// Begin resolving the catalog broadcast (the one at this source's path). pub(crate) fn request_catalog(&self) -> kio::Pending { self.origin.request_broadcast(&self.path) @@ -373,6 +382,36 @@ mod tests { assert!(binding.broadcast().await.is_err()); } + #[tokio::test] + async fn returned_waits_for_a_new_broadcast_after_the_old_one_ends() { + let origin = produce_origin(); + let first = origin.publish("live", Default::default()).unwrap(); + settle().await; + let source = Source::new(origin.consume(), "live"); + let ended = source.broadcast().await.unwrap(); + + let returned = source.returned(&ended); + tokio::pin!(returned); + tokio::select! { + biased; + _ = &mut returned => panic!("the broadcast is still up"), + _ = settle() => {} + } + + // Gone, and nothing serves the path yet. + drop(first); + tokio::select! { + biased; + _ = &mut returned => panic!("nothing has published the path again"), + _ = settle() => {} + } + + let _second = origin.publish("live", Default::default()).unwrap(); + let back = returned.await.unwrap(); + assert!(!back.is_closed()); + assert!(!back.is_clone(&ended)); + } + #[tokio::test] async fn no_override_targets_catalog_broadcast() { let origin = produce_origin(); From e86f00a3f19c5d9a41e3863eb8b53564c8d7467b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 16:25:10 -0700 Subject: [PATCH 070/128] quest: data tracks stamp on the catalog's current clock Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 1 + quest/m1/data-track-clock.md | 19 +++++++++++++++++++ 2 files changed, 20 insertions(+) create mode 100644 quest/m1/data-track-clock.md diff --git a/quest/m1/README.md b/quest/m1/README.md index ee5b48eb001..9c7b0a0b3a5 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -58,6 +58,7 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [HLS discontinuity sequence](/quest/m1/hls-discontinuity-sequence.md) - on dev, `Segment::discontinuity` is the absolute sequence, so every cursor agrees - [Auth client CA](/quest/m1/relay-auth-client-ca.md) - on dev, `auth::Config::validate` and `init` take the client-CA flag, so no caller can skip the check - [Remove live()](/quest/m1/remove-live.md) - on dev, importers publish stream timestamps verbatim, the catalog clock maps them to wall time, and an encoder restart becomes a new epoch +- [Data track clock](/quest/m1/data-track-clock.md) - JSON and binary data tracks stamp on the catalog's clock at write time, matching the media's anchored clock - [Go and Dart doc samples](/quest/m1/doc-samples-go-dart.md) - Go and Dart doc samples compile against their wrappers - [Data capture in bindings](/quest/m1/data-capture-bindings.md) - moq-ffi and every wrapper pass a data frame's capture time, and the JSON window producer takes one - [Moxygen compatibility](/quest/m1/moxygen/README.md) - one subgroup per group, whole-group FETCH, and one datagram per group, never a full moxygen pass diff --git a/quest/m1/data-track-clock.md b/quest/m1/data-track-clock.md new file mode 100644 index 00000000000..170d34a09a9 --- /dev/null +++ b/quest/m1/data-track-clock.md @@ -0,0 +1,19 @@ +# [XS] Data tracks stamp on the catalog's current clock + +## Goal + +A JSON or binary data track publishes timestamps on the same clock mapping as +the media next to it, however early it was created. Today a data track copies +the catalog clock when it's created. An importer sets that clock from its +first frame (remove-live, #4543), so a data track created before that frame +maps its timestamps to a different clock than the media. + +## Plan + +Have data tracks read the catalog's clock when they stamp, not a copy made +when they were created. Keep it crate-private if possible. Test: a data track +created before an importer's first frame stamps on the anchored clock. + +## Required + +- [Remove live()](/quest/m1/remove-live.md) - introduces the first-frame clock anchor From 4e808226c976c754095a2ed768fd9e7c8e672207 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 16:25:27 -0700 Subject: [PATCH 071/128] fix(net): keep a refusal's identity only while the refusal stands Co-Authored-By: Claude Opus 5.5 --- js/net/src/ietf/publisher.ts | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 75124c97550..7d01e4963a3 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -1020,13 +1020,17 @@ export class Publisher { if (!this.#offerable(key, ns.refused)) continue; answer = await target.advertise(key, snap); } - ns.offered.set(key, snap.identity); - + // `offered` pairs with `refused`, so a held or withdrawn path leaves nothing behind. if (answer === "held") { held.set(key, snap); + ns.refused.delete(key); + ns.offered.delete(key); } else { held.delete(key); - if (answer !== "dropped") ns.refused.set(key, answer); + if (answer !== "dropped") { + ns.refused.set(key, answer); + ns.offered.set(key, snap.identity); + } } } From 10f3f1c8d47f0bcc2df3d4671d2e8d7076276f65 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 16:31:04 -0700 Subject: [PATCH 072/128] fix(publish): probe with the frame rate and bitrate ceiling Match moq-video's Config::probe, which opens its encoder with the full config: an encoder may pick its level from either. The ceiling is the per-codec target before the bandwidth grant, so a grant never re-probes; frameRate, bitrateScale, maxBitrate and maxPixels do. Co-Authored-By: Claude Opus 5.5 --- js/publish/src/video/encoder.test.ts | 58 +++++++++ js/publish/src/video/encoder.ts | 183 +++++++++++++-------------- 2 files changed, 144 insertions(+), 97 deletions(-) diff --git a/js/publish/src/video/encoder.test.ts b/js/publish/src/video/encoder.test.ts index 8e28708c5f6..154f7013acf 100644 --- a/js/publish/src/video/encoder.test.ts +++ b/js/publish/src/video/encoder.test.ts @@ -651,3 +651,61 @@ test("a probe encode that reports no codec string fails loud", async () => { error.mockRestore(); } }); + +// An encoder may pick its level from the frame rate or bitrate, so the probe encodes with both. The +// bitrate is the ceiling, so a bandwidth grant caps the live encoder without re-probing. +test("the probe encodes with the frame rate and bitrate ceiling", async () => { + using _videoEncoder = installFakeVideoEncoder(); + const probe = spyOn(FakeVideoEncoder, "isConfigSupported"); + + const track = new Moq.Track.Producer("video").accept({ priority: 60 }); + const sub = track.subscribe(); + const rendition = { + config: new Signal(undefined), + track: new Signal(track), + close: () => track.close(), + }; + const capture = { + in: { source: new Signal({ getSettings: () => ({ frameRate: 30 }), getConstraints: () => ({}) }) }, + out: { display: new Signal({ width: 1280, height: 720 }), frames: new Signal(undefined) }, + }; + const estimate = new Signal(100_000_000); + const bandwidth = new Moq.Bandwidth.Allocator(estimate); + const encoder = new Encoder("video", { + enabled: true, + broadcast: { video: () => rendition, baseline: new Baseline() } as never, + capture: capture as never, + bandwidth, + }); + const accepted = () => + probe.mock.calls.map(([config]) => config).filter((config) => config.codec.startsWith("avc1")); + + try { + await settle(); + const first = accepted().at(-1); + expect(first).toMatchObject({ framerate: 30 }); + expect(first?.bitrate).toBeGreaterThan(0); + expect(encoder.out.resolved.peek()?.bitrate).toBe(first?.bitrate); + + // A grant below the ceiling caps the live config but leaves the probe alone. + const probes = probe.mock.calls.length; + estimate.set(500_000); + await settle(); + expect(encoder.out.resolved.peek()?.bitrate).toBe(500_000); + expect(probe.mock.calls.length).toBe(probes); + + // A frame rate change re-probes with the new rate and its larger ceiling. + encoder.config.set({ frameRate: 60 }); + await settle(); + expect(probe.mock.calls.length).toBeGreaterThan(probes); + const second = accepted().at(-1); + expect(second).toMatchObject({ framerate: 60 }); + expect(second?.bitrate).toBeGreaterThan(first?.bitrate ?? 0); + expect(encoder.out.catalog.peek()?.framerate).toBe(60); + } finally { + encoder.close(); + bandwidth.close(); + sub.close(); + probe.mockRestore(); + } +}); diff --git a/js/publish/src/video/encoder.ts b/js/publish/src/video/encoder.ts index 411dd0cf280..86534f1ed50 100644 --- a/js/publish/src/video/encoder.ts +++ b/js/publish/src/video/encoder.ts @@ -134,7 +134,7 @@ export class Encoder { // The output dimensions of the video in pixels. #dimensions = new Signal<{ width: number; height: number } | undefined>(undefined); - // The codec the browser will actually encode with, tagged with the inputs it was probed against. + // The config the browser accepted and encoded a probe frame with, and the codec string it reported. #codec = new Signal(undefined); // Uncapped target bitrate (pixels, maxBitrate), the reservation's ceiling. @@ -143,9 +143,9 @@ export class Encoder { // This rendition's claim on the connection, held while a track is live. #reservation = new Signal(undefined); - // Only the codec prefix the user asked for, narrowed out of `config` so tuning any other knob - // doesn't re-probe the hardware. - #codecFilter: Computed; + // Only the knobs the probe encodes with, narrowed out of `config` and the source so tuning any + // other knob, or a bandwidth grant, doesn't re-probe the hardware. + #target: Computed; // How many resolution runs threw for their current inputs (no supported codec, an invalid knob), // so no config is coming until one reruns. @@ -174,7 +174,23 @@ export class Encoder { bandwidth: getter(props?.bandwidth), }; this.config = Signal.from(props?.config); - this.#codecFilter = this.#signals.computed((effect) => effect.get(this.config)?.codec ?? ""); + this.#target = this.#signals.computed((effect): Target | undefined => { + const capture = effect.get(this.in.capture); + if (!capture) return; + + const source = effect.get(capture.in.source); + if (!source) return; + + const user = effect.get(this.config) ?? {}; + return { + required: user.codec ?? "", + // Prefer the explicitly requested rate; the encode loop drops frames to enforce it. + framerate: user.frameRate ?? sourceFrameRate(source) ?? 30, + maxPixels: user.maxPixels, + bitrateScale: user.bitrateScale ?? 0.07, + maxBitrate: user.maxBitrate, + }; + }); this.settled = this.#signals.computed( (effect) => effect.get(this.#out.catalog) !== undefined || effect.get(this.#failures) > 0, ); @@ -413,9 +429,10 @@ export class Encoder { // derived from the probe, but can briefly trail a new one within a batch. const detected = effect.get(this.#codec); const matches = - detected?.codec === config?.codec && - detected?.width === config?.width && - detected?.height === config?.height; + detected?.config.codec === config?.codec && + detected?.config.width === config?.width && + detected?.config.height === config?.height && + detected?.config.framerate === config?.framerate; if (!enabled || !config || !detected || !matches) { effect.set(this.#out.catalog, undefined); return; @@ -445,12 +462,12 @@ export class Encoder { const dimensions = effect.get(this.#dimensions); if (!dimensions) return; - const required = effect.get(this.#codecFilter) ?? ""; + const target = effect.get(this.#target); + if (!target) return; effect.spawn(async () => { try { - const detected = await this.#bestCodec(required, dimensions); - effect.set(this.#codec, { ...detected, required, ...dimensions }); + effect.set(this.#codec, await this.#bestCodec(dimensions, target)); } catch (err) { this.#fail(effect); throw err; @@ -458,71 +475,20 @@ export class Encoder { }); } - // Size the bitrate for the detected codec. Synchronous, so a new bandwidth estimate updates the - // config within the same microtask instead of leaving it blank while something re-derives it. + // Cap the probed config's bitrate by the bandwidth grant. Synchronous, so a new bandwidth estimate + // updates the config within the same microtask instead of leaving it blank while something + // re-derives it. Everything else comes from the probe as-is, so the resolved config is always one + // the hardware accepted. #runResolved(effect: Effect): void { - // NOTE: dimensions already factors in user provided maxPixels. - // It's a separate effect in order to deduplicate. if (!effect.get(this.in.enabled)) return; - const capture = effect.get(this.in.capture); - if (!capture) return; - - const source = effect.get(capture.in.source); - if (!source) return; - - const dimensions = effect.get(this.#dimensions); - if (!dimensions) return; - const detected = effect.get(this.#codec); if (!detected) return; - // A probe only speaks for the inputs it ran against. Changing them reruns the probe, which - // clears the stale result, but a bandwidth sample landing in the same batch schedules this - // effect independently: it then runs against dimensions that are already written while the - // probe hasn't been torn down yet. Wait for a probe that matches rather than publishing a - // pairing the hardware never accepted. - const required = effect.get(this.#codecFilter) ?? ""; - if (detected.required !== required) return; - if (detected.width !== dimensions.width || detected.height !== dimensions.height) return; - - const { codec, hardwareAcceleration } = detected; - // Get the user provided config. - const user = effect.get(this.config) ?? {}; - - // Prefer the explicitly requested rate; the encode loop drops frames to enforce it. - const framerate = user.frameRate ?? sourceFrameRate(source) ?? 30; - - const maxPixels = user.maxPixels ?? dimensions.width * dimensions.height; - const bitrateScale = user.bitrateScale ?? 0.07; - - // TARGET BITRATE CALCULATION (h264) - // 480p@30 = 1.0mbps - // 480p@60 = 1.5mbps - // 720p@30 = 2.5mbps - // 720p@60 = 3.5mpbs - // 1080p@30 = 4.5mbps - // 1080p@60 = 6.0mbps - - // 30fps is the baseline, applying a multiplier for higher framerates. - // Framerate does not cause a multiplicative increase in bitrate because of delta encoding. - // TODO Make this better. - const framerateFactor = 30.0 + (framerate - 30) / 2; - - // ACTUAL BITRATE CALCULATION - // 480p@30 = 409920 * 30 * 0.07 = 0.9 Mb/s - // 480p@60 = 409920 * 45 * 0.07 = 1.3 Mb/s - // 720p@30 = 921600 * 30 * 0.07 = 1.9 Mb/s - // 720p@60 = 921600 * 45 * 0.07 = 2.9 Mb/s - // 1080p@30 = 2073600 * 30 * 0.07 = 4.4 Mb/s - // 1080p@60 = 2073600 * 45 * 0.07 = 6.5 Mb/s - let bitrate = Math.round(maxPixels * bitrateScale * framerateFactor * codecBitrateScale(codec)); - - bitrate = Math.round(Math.min(bitrate, user.maxBitrate || bitrate)); - // The reservation's ceiling is what we can ever send, not the grant: a // grant that followed our own output would hand the room away on a still // picture and not have it back when the picture moved. + let bitrate = detected.config.bitrate; effect.set(this.#ceiling, bitrate); const reservation = effect.get(this.#reservation); @@ -532,20 +498,7 @@ export class Encoder { if (grant != null) bitrate = Math.min(bitrate, grant); } - const config: VideoEncoderConfig = { - codec, - width: dimensions.width, - height: dimensions.height, - framerate, - bitrate, - avc: codec.startsWith("avc1") ? { format: "annexb" } : undefined, - // @ts-expect-error Typescript needs to be updated. - hevc: codec.startsWith("hev1") ? { format: "annexb" } : undefined, - latencyMode: "realtime", - hardwareAcceleration, - }; - - effect.set(this.#out.resolved, config); + effect.set(this.#out.resolved, { ...detected.config, bitrate }); } #runDimensions(effect: Effect): void { @@ -588,10 +541,7 @@ export class Encoder { } // Try to determine the best config for the given settings. - async #bestCodec( - required: string, - dimensions: { width: number; height: number }, - ): Promise> { + async #bestCodec(dimensions: { width: number; height: number }, target: Target): Promise { // A list of codecs to try, in order of preference. Only full RFC 6381 strings: Chrome, Firefox, // and Safari all refuse a bare `avc1` or `vp09`, and native players can't decode without the profile. const HARDWARE_CODECS = [ @@ -651,12 +601,17 @@ export class Encoder { ]; for (const [codec, hardwareAcceleration] of candidates) { - if (!codec.startsWith(required)) continue; + if (!codec.startsWith(target.required)) continue; - const config: VideoEncoderConfig = { + // The full config, like moq-video's probe: an encoder may pick its level from the frame rate + // or bitrate. The bitrate is the ceiling rather than the grant, so a bandwidth estimate never + // re-probes. + const config: Detected["config"] = { codec, width: dimensions.width, height: dimensions.height, + framerate: target.framerate, + bitrate: ceiling(codec, dimensions, target), latencyMode: "realtime", hardwareAcceleration, avc: codec.startsWith("avc1") ? { format: "annexb" } : undefined, @@ -665,7 +620,7 @@ export class Encoder { }; const { supported } = await VideoEncoder.isConfigSupported(config); - if (supported) return { codec, hardwareAcceleration, reported: await reportedCodec(config) }; + if (supported) return { config, reported: await reportedCodec(config) }; } throw new Error("no supported codec"); @@ -682,20 +637,54 @@ function sourceFrameRate(source: Source): number | undefined { return "frames" in source ? source.frameRate : normalizeSource(source).track.getSettings().frameRate; } -// A hardware probe result, carrying the inputs it ran against so a consumer can tell whether it -// still applies. +// The knobs a probe encodes with, besides the dimensions. +type Target = { + // The codec prefix the user required. + required: string; + framerate: number; + maxPixels?: number; + bitrateScale: number; + maxBitrate?: number; +}; + +// A hardware probe result. type Detected = { - // The codec string we configure the encoder with. - codec: string; + // The config the browser accepted and encoded a probe frame with. Its bitrate is the ceiling, + // before any bandwidth grant. + config: VideoEncoderConfig & { framerate: number; bitrate: number }; // The codec string the encoder reported for it, which the catalog advertises. reported: string; - hardwareAcceleration: HardwareAcceleration; - // The codec prefix the user required at probe time. - required: string; - width: number; - height: number; }; +// The most this rendition ever sends with `codec`, before a bandwidth grant caps it. +function ceiling(codec: string, dimensions: { width: number; height: number }, target: Target): number { + // NOTE: dimensions already factors in user provided maxPixels. + const maxPixels = target.maxPixels ?? dimensions.width * dimensions.height; + + // TARGET BITRATE CALCULATION (h264) + // 480p@30 = 1.0mbps + // 480p@60 = 1.5mbps + // 720p@30 = 2.5mbps + // 720p@60 = 3.5mpbs + // 1080p@30 = 4.5mbps + // 1080p@60 = 6.0mbps + + // 30fps is the baseline, applying a multiplier for higher framerates. + // Framerate does not cause a multiplicative increase in bitrate because of delta encoding. + // TODO Make this better. + const framerateFactor = 30.0 + (target.framerate - 30) / 2; + + // ACTUAL BITRATE CALCULATION + // 480p@30 = 409920 * 30 * 0.07 = 0.9 Mb/s + // 480p@60 = 409920 * 45 * 0.07 = 1.3 Mb/s + // 720p@30 = 921600 * 30 * 0.07 = 1.9 Mb/s + // 720p@60 = 921600 * 45 * 0.07 = 2.9 Mb/s + // 1080p@30 = 2073600 * 30 * 0.07 = 4.4 Mb/s + // 1080p@60 = 2073600 * 45 * 0.07 = 6.5 Mb/s + const bitrate = Math.round(maxPixels * target.bitrateScale * framerateFactor * codecBitrateScale(codec)); + return Math.round(Math.min(bitrate, target.maxBitrate || bitrate)); +} + // Encode one frame with a throwaway encoder and return the codec string it reports, like // moq-video's `Config::probe`. The encoder picks the profile and level it actually writes, so reading // them back lets the rendition be advertised before a subscriber starts the real encoder, without a From bc7542d52f247a8d48667f06554897aebde3bb63 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 16:47:29 -0700 Subject: [PATCH 073/128] fix(publish): keep the rendition advertised while it re-probes The previous probe result stays in place until the new one resolves, so a re-probe replaces the catalog entry in one update, or leaves it untouched when nothing changed. A failed probe still drops it and fails loud. ceiling() now rejects a non-positive bitrate before the browser sees it. Co-Authored-By: Claude Opus 5.5 --- js/publish/src/video/encoder.test.ts | 44 +++++++++++++++++++++ js/publish/src/video/encoder.ts | 58 +++++++++++++++++----------- 2 files changed, 79 insertions(+), 23 deletions(-) diff --git a/js/publish/src/video/encoder.test.ts b/js/publish/src/video/encoder.test.ts index 154f7013acf..b20b873457b 100644 --- a/js/publish/src/video/encoder.test.ts +++ b/js/publish/src/video/encoder.test.ts @@ -378,12 +378,15 @@ test("an invalid knob settles the encoder without a config", async () => { out: { display: new Signal({ width: 1920, height: 1080 }) }, }; const config = new Signal<{ bitrateScale?: number } | undefined>({ bitrateScale: -1 }); + const probe = spyOn(FakeVideoEncoder, "isConfigSupported"); const encoder = new Encoder("video", { enabled: true, capture: capture as never, config }); try { await settle(); expect(encoder.out.catalog.peek()).toBeUndefined(); expect(encoder.settled.peek()).toBe(true); expect(error).toHaveBeenCalled(); + // Refused before the browser could coerce it into an unsigned bitrate. + expect(probe).not.toHaveBeenCalled(); // Fixing the knob clears the failure and resolves a config. config.set(undefined); @@ -393,6 +396,7 @@ test("an invalid knob settles the encoder without a config", async () => { } finally { encoder.close(); error.mockRestore(); + probe.mockRestore(); } }); @@ -709,3 +713,43 @@ test("the probe encodes with the frame rate and bitrate ceiling", async () => { probe.mockRestore(); } }); + +// A re-probe keeps the rendition advertised while it runs: dropping it, even for a moment, would +// tell every subscriber the track went away. +test("a re-probe swaps the catalog entry in one update", async () => { + using _videoEncoder = installFakeVideoEncoder(); + const probe = spyOn(FakeVideoEncoder, "isConfigSupported"); + const capture = { + in: { source: new Signal({ getSettings: () => ({ frameRate: 30 }), getConstraints: () => ({}) }) }, + out: { display: new Signal({ width: 1280, height: 720 }) }, + }; + const encoder = new Encoder("video", { enabled: true, capture: capture as never }); + + try { + await settle(); + expect(encoder.out.catalog.peek()?.framerate).toBe(30); + + const published: (number | undefined)[] = []; + const unsubscribe = encoder.out.catalog.subscribe((catalog) => published.push(catalog?.framerate)); + try { + // A frame rate change re-probes, and the catalog goes straight from the old entry to the new. + let probes = probe.mock.calls.length; + encoder.config.set({ frameRate: 60 }); + await settle(); + expect(probe.mock.calls.length).toBeGreaterThan(probes); + expect(published).toEqual([60]); + + // A re-probe that lands on the same config leaves the catalog untouched. + probes = probe.mock.calls.length; + encoder.config.set({ frameRate: 60, maxPixels: 1280 * 720 }); + await settle(); + expect(probe.mock.calls.length).toBeGreaterThan(probes); + expect(published).toEqual([60]); + } finally { + unsubscribe(); + } + } finally { + encoder.close(); + probe.mockRestore(); + } +}); diff --git a/js/publish/src/video/encoder.ts b/js/publish/src/video/encoder.ts index 86534f1ed50..be6d04d9c6b 100644 --- a/js/publish/src/video/encoder.ts +++ b/js/publish/src/video/encoder.ts @@ -135,8 +135,13 @@ export class Encoder { #dimensions = new Signal<{ width: number; height: number } | undefined>(undefined); // The config the browser accepted and encoded a probe frame with, and the codec string it reported. + // Kept through a re-probe, so the rendition stays in the catalog until the new probe replaces it. #codec = new Signal(undefined); + // The probed config capped by the bandwidth grant, and the codec string to advertise for it. One + // signal, so the catalog never pairs a new probe's string with the previous config. + #live = new Signal<{ config: VideoEncoderConfig; reported: string } | undefined>(undefined); + // Uncapped target bitrate (pixels, maxBitrate), the reservation's ceiling. #ceiling = new Signal(undefined); @@ -423,23 +428,17 @@ export class Encoder { // Returns the catalog for the configured settings, or undefined while disabled / unresolved. #runCatalog(effect: Effect): void { const enabled = effect.get(this.in.enabled); - const config = effect.get(this.out.resolved); - // Advertise the codec string the probe's encoder reported rather than the one we configured, - // so it names the profile and level the bitstream actually carries. The resolved config is - // derived from the probe, but can briefly trail a new one within a batch. - const detected = effect.get(this.#codec); - const matches = - detected?.config.codec === config?.codec && - detected?.config.width === config?.width && - detected?.config.height === config?.height && - detected?.config.framerate === config?.framerate; - if (!enabled || !config || !detected || !matches) { + const live = effect.get(this.#live); + if (!enabled || !live) { effect.set(this.#out.catalog, undefined); return; } + // Advertise the codec string the probe's encoder reported rather than the one we configured, + // so it names the profile and level the bitstream actually carries. + const { config, reported } = live; const catalog: Catalog.VideoConfig = { - codec: detected.reported, + codec: reported, bitrate: config.bitrate ? Catalog.u53(config.bitrate) : undefined, framerate: config.framerate, codedWidth: Catalog.u53(config.width), @@ -453,22 +452,29 @@ export class Encoder { effect.set(this.#out.catalog, catalog); } - // Probe the hardware for the best codec. Deliberately depends on as little as possible: every - // rerun blanks the codec (and with it the resolved config and the catalog entry) for however long - // the probe takes, which on a busy GPU process is a long time. + // Probe the hardware for the best codec. Deliberately depends on as little as possible, since a + // probe on a busy GPU process takes a long time. The previous result stays in place meanwhile, so + // a re-probe swaps the catalog entry in one update, or not at all when nothing changed. #runCodec(effect: Effect): void { - if (!effect.get(this.in.enabled)) return; - + const enabled = effect.get(this.in.enabled); const dimensions = effect.get(this.#dimensions); - if (!dimensions) return; - const target = effect.get(this.#target); - if (!target) return; + if (!enabled || !dimensions || !target) { + this.#codec.set(undefined); + return; + } + // Captured now: the run's signal is replaced once a rerun starts. + const superseded = effect.abort; effect.spawn(async () => { try { - effect.set(this.#codec, await this.#bestCodec(dimensions, target)); + const detected = await this.#bestCodec(dimensions, target); + if (!superseded.aborted) this.#codec.set(detected); } catch (err) { + // A newer probe reports its own outcome. + if (superseded.aborted) return; + + this.#codec.set(undefined); this.#fail(effect); throw err; } @@ -498,7 +504,9 @@ export class Encoder { if (grant != null) bitrate = Math.min(bitrate, grant); } - effect.set(this.#out.resolved, { ...detected.config, bitrate }); + const config = { ...detected.config, bitrate }; + effect.set(this.#out.resolved, config); + effect.set(this.#live, { config, reported: detected.reported }); } #runDimensions(effect: Effect): void { @@ -682,7 +690,11 @@ function ceiling(codec: string, dimensions: { width: number; height: number }, t // 1080p@30 = 2073600 * 30 * 0.07 = 4.4 Mb/s // 1080p@60 = 2073600 * 45 * 0.07 = 6.5 Mb/s const bitrate = Math.round(maxPixels * target.bitrateScale * framerateFactor * codecBitrateScale(codec)); - return Math.round(Math.min(bitrate, target.maxBitrate || bitrate)); + const capped = Math.round(Math.min(bitrate, target.maxBitrate || bitrate)); + + // Refuse a bad knob here, before the browser coerces it into an unsigned bitrate. + if (!(capped > 0)) throw new Error(`bitrate must be positive: ${capped}`); + return capped; } // Encode one frame with a throwaway encoder and return the codec string it reports, like From 6d0a88df14cc5804e3fbeb1062debaea153ec2b4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 16:51:43 -0700 Subject: [PATCH 074/128] test(auth): run the outage tests on a paused clock without sockets (#4527) Co-authored-by: Claude Opus 5.5 --- quest/m1/README.md | 1 - quest/m1/auth-outage-clock.md | 63 ------- quest/m1/test-flakes-2.md | 6 + rs/moq-auth/src/client.rs | 261 ++++++++++++++-------------- rs/moq-relay/tests/auth_lifetime.rs | 153 ++++++++++------ 5 files changed, 233 insertions(+), 251 deletions(-) delete mode 100644 quest/m1/auth-outage-clock.md diff --git a/quest/m1/README.md b/quest/m1/README.md index e64ee5a520b..d1f265a2994 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -40,7 +40,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [More tests under load](/quest/m1/test-flakes-2.md) - the second round of load-only failures, fixed at the cause - [CI runner stalls](/quest/m1/ci-runner-stalls.md) - the 0.4 to 0.8 s freezes of both interop tracks on CI are attributed from a week of nightlies and fixed or told apart from playback bugs - [Catalog estimate rate](/quest/m1/catalog-estimate-rate.md) - a rising `jitter`/`delay` estimate republishes the catalog at most once a second, in js/publish and moq-mux -- [Auth outage clock](/quest/m1/auth-outage-clock.md) - the relay and moq-auth outage tests run on a paused clock again and assert both bounds of `expires` - [Legacy end overshoot](/quest/m1/legacy-end-overshoot.md) - browser playback survives a group that starts inside the previous group's estimated end - [UnknownSession log flood](/quest/m1/unknown-session-logs.md) - streams reset before their WebTransport header stop being reported as UnknownSession at WARN - [Merge queue](/quest/m1/merge-queue.md) - the required checks run on `merge_group`, so a stale green check can no longer break main diff --git a/quest/m1/auth-outage-clock.md b/quest/m1/auth-outage-clock.md deleted file mode 100644 index 43c923a8b3e..00000000000 --- a/quest/m1/auth-outage-clock.md +++ /dev/null @@ -1,63 +0,0 @@ -# [M] Auth outage tests on a paused clock - -## Goal - -The moq-relay and moq-auth outage tests run on tokio's paused clock again and -assert both bounds: a session (or grant) survives an auth outage until its -`expires`, and closes at `expires`, not later. No wall-clock sleeps, no -widened timeouts, and no dependence on how fast the OS delivers loopback. - -## Plan - -- The tests: `an_outage_keeps_the_session_until_expires` in - `rs/moq-relay/tests/auth_lifetime.rs` - ([#4244](https://github.com/moq-dev/moq/pull/4244)) and - `an_outage_keeps_the_grant_until_expires` in `rs/moq-auth/src/client.rs` - ([#4291](https://github.com/moq-dev/moq/pull/4291)). Both moved to the real - clock because a paused clock auto-advances while the runtime waits on a - real socket, so a virtual timer fired before macOS delivered loopback. That - swapped one violation of "unit tests mock time" for another, and #4244 - dropped the upper bound. Read both PR descriptions: they list what was - tried and why it failed (restoring a listener probe, pausing after setup, - waiting on the log). -- The race is real sockets under virtual time, so fix it by taking the - sockets out of these tests. Look at what the codebase already offers - before building anything: `rs/moq-net/tests/support/mock.rs` (an in-memory - session pair), `moq_relay::auth::Auth::embedded` with its `Admissions` - (decides leases in-process), and the lease driver in moq-auth, which could - be exercised against an in-process answer source instead of HTTP. If the - relay's `Connection` or moq-auth's `Client` cannot take such a transport, - prefer the small seam that lets them over a test-only shim. -- Decide where each assertion belongs. The outage semantics (a 503 keeps the - grant until `expires`) are moq-auth's; the relay test may only need to show - that a lease reaching `expires` closes the session as `Expired` and reports - `end`. Don't keep two tests proving the same thing. -- Measure against tokio's clock, not `SystemTime`: the grant still carries a - wall-clock `expires`, so pin how it maps onto the paused clock. -- Other paused-clock tests touch real sockets and would share the hazard - once a timeout lands on their path. #4291's audit named - `a_grant_within_clock_skew_stays_live` (moq-auth) and - `fixed_addresses_keep_tls_name_and_request_host` (moq-tokio websocket); - moq-auth's `clock_server` helper exists only to keep axum on the paused - clock. Move those onto the same seam if it is cheap. -- Prove it: loop the tests with every core loaded, on macOS if available, - and mutate the deadline both ways (close early, close late) to see each - bound fail. - -Public API: none unless a transport seam is needed; report it if so. Wire: -none. - -## Related - -- [More tests under load](/quest/m1/test-flakes-2.md) - the same rule - applied to other load-only failures -- [moq-shaper virtual time](/quest/m1/shaper-virtual-time.md) - the same - paused-clock-versus-real-socket fight in moq-shaper -- [#4280](https://github.com/moq-dev/moq/pull/4280) - moq-archive and - moq-hls tests poll with real-clock sleeps, on the archive track-timeline - line -- [#4281](https://github.com/moq-dev/moq/pull/4281) - OBS `WaitFor` polling, - on the C++ line -- [Nightly 2026-09-26](https://github.com/moq-dev/moq/actions/runs/36240326747/job/108399481809) - - the macOS relay tarball job failed this test with "publisher connect - timeout", before #4244 landed diff --git a/quest/m1/test-flakes-2.md b/quest/m1/test-flakes-2.md index 44fbc2ad56c..a5941853f93 100644 --- a/quest/m1/test-flakes-2.md +++ b/quest/m1/test-flakes-2.md @@ -43,6 +43,12 @@ retry. `start_paused = true` but sleeps 1.2 s of real time, because the debounce reads `crate::Clock`, which uses `std::time::Instant`, so the paused tokio clock never reaches it. +- moq-tokio websocket `fixed_addresses_keep_tls_name_and_request_host` and + `ipv6_literal_fixed_addresses` pause the clock over a real TLS dial on + loopback. They pass today, but once a timeout lands on that path, the paused + clock can fire it before loopback delivers, the race + [#4527](https://github.com/moq-dev/moq/pull/4527) removed from the auth + outage tests. ## Plan diff --git a/rs/moq-auth/src/client.rs b/rs/moq-auth/src/client.rs index 935e22c784e..cd07c3f06a2 100644 --- a/rs/moq-auth/src/client.rs +++ b/rs/moq-auth/src/client.rs @@ -70,26 +70,24 @@ impl Client { /// Admit a session: POST `connect`, validate the reply, and return the lease the /// session holds. The session reports totals through [`lease::Consumer::close`]. pub async fn connect(&self, request: Request) -> crate::Result { - let mut request = request; - request.event = Event::Connect; - - let grant = self.post(&request).await?; - let (producer, consumer) = lease::Producer::new(grant.clone()); - - let driver = Driver { - client: self.clone(), - request, - producer: Some(producer), - expires: grant.deadline(), - started: Instant::now(), - }; - tokio::spawn(driver.run(grant)); - - Ok(consumer) + connect(self.clone(), request).await } +} + +/// Where a lease's requests go: the auth server over HTTP, or an in-process +/// answer in tests, so the lease's timers run on Tokio's paused clock with no +/// socket for them to outrun. +trait Post: Clone + Send + Sync + 'static { + /// Send a `connect` or `revalidate`: the grant as answered, not yet validated, + /// a refusal, or an outage. + fn post(&self, request: &Request) -> impl Future> + Send; + + /// Send the `end`. + fn post_end(&self, request: &Request) -> impl Future> + Send; +} - /// One POST: a 2xx with a valid grant admits, a 401 or 403 refuses, a 2xx - /// whose grant fails validation is that error, and everything else is an +impl Post for Client { + /// A 2xx carries the grant, a 401 or 403 refuses, and everything else is an /// outage the caller decides about. async fn post(&self, request: &Request) -> crate::Result { let response = self.http.post(self.url.clone()).json(request).send().await?; @@ -100,26 +98,61 @@ impl Client { if !status.is_success() { return Err(Error::Unavailable(format!("auth server answered {status}"))); } - let grant: Grant = response.json().await?; - grant.validate().map_err(|err| match err { - // An empty grant is a refusal, not a malformed answer. - Error::UselessGrant => Error::Refused, - other => other, - })?; - Ok(grant) + Ok(response.json().await?) } + + async fn post_end(&self, request: &Request) -> crate::Result<()> { + self.http + .post(self.url.clone()) + .json(request) + .send() + .await? + .error_for_status()?; + Ok(()) + } +} + +/// Admit a session through `server` and spawn the driver behind its lease. +async fn connect(server: S, mut request: Request) -> crate::Result { + request.event = Event::Connect; + + let grant = ask(&server, &request).await?; + let (producer, consumer) = lease::Producer::new(grant.clone()); + + let driver = Driver { + server, + request, + producer: Some(producer), + expires: grant.deadline(), + started: Instant::now(), + }; + tokio::spawn(driver.run(grant)); + + Ok(consumer) +} + +/// One `connect` or `revalidate`: a valid grant admits, and one that fails +/// validation is that error. +async fn ask(server: &S, request: &Request) -> crate::Result { + let grant = server.post(request).await?; + grant.validate().map_err(|err| match err { + // An empty grant is a refusal, not a malformed answer. + Error::UselessGrant => Error::Refused, + other => other, + })?; + Ok(grant) } /// The task behind a lease: re-checks on cadence and reports the end. -struct Driver { - client: Client, +struct Driver { + server: S, request: Request, producer: Option, started: Instant, expires: Option, } -impl Driver { +impl Driver { async fn run(mut self, grant: Grant) { let (reason, bytes) = self.drive(grant).await; @@ -130,7 +163,7 @@ impl Driver { bytes, }; // The session is already gone; nothing to do with a failure but say so. - if let Err(err) = self.client.post_end(&request).await { + if let Err(err) = self.server.post_end(&request).await { tracing::warn!(id = %request.id, %err, "failed to report the session end"); } } @@ -219,22 +252,10 @@ impl Driver { } fn post_revalidate(&self) -> Pin> + Send>> { - let client = self.client.clone(); + let server = self.server.clone(); let mut request = self.request.clone(); request.event = Event::Revalidate; - Box::pin(async move { client.post(&request).await }) - } -} - -impl Client { - async fn post_end(&self, request: &Request) -> crate::Result<()> { - self.http - .post(self.url.clone()) - .json(request) - .send() - .await? - .error_for_status()?; - Ok(()) + Box::pin(async move { ask(&server, &request).await }) } } @@ -316,34 +337,42 @@ mod tests { server } - /// Keep HTTP handling on the paused test clock instead of wiremock's separate runtime. - async fn clock_server(log: Log, grant: Grant, stall: bool) -> Client { - use axum::{Json, Router, extract::State, http::StatusCode, response::IntoResponse, routing::post}; - let router = Router::new() - .route( - "/", - post( - |State((log, grant, stall)): State<(Log, Grant, bool)>, Json(request): Json| async move { - let event = request.event.clone(); - log.0.lock().push(request); - match event { - Event::Connect => Json(grant).into_response(), - Event::Revalidate if stall => std::future::pending().await, - Event::Revalidate => StatusCode::SERVICE_UNAVAILABLE.into_response(), - Event::End { .. } => StatusCode::OK.into_response(), - } - }, - ), - ) - .with_state((log, grant, stall)); - let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); - let url = format!("http://{}/", listener.local_addr().unwrap()); - tokio::spawn(async move { axum::serve(listener, router).await.unwrap() }); - // Only the lease clock is under test; an HTTP timeout can auto-advance - // Tokio's paused clock before loopback I/O gets its first reactor turn. - Client { - http: reqwest::Client::builder().no_proxy().build().unwrap(), - url: url.parse().unwrap(), + /// An in-process auth server for tests on Tokio's paused clock: it logs each + /// request and answers with `respond`, never when that returns `None`. With no + /// socket, the clock only advances once every answer has landed. + #[derive(Clone)] + struct Script { + log: Log, + #[allow(clippy::type_complexity)] + respond: std::sync::Arc Option> + Send + Sync>, + } + + impl Script { + fn new(log: Log, respond: impl Fn(&Request) -> Option> + Send + Sync + 'static) -> Self { + Self { + log, + respond: std::sync::Arc::new(respond), + } + } + + async fn connect(&self) -> crate::Result { + connect(self.clone(), request()).await + } + } + + impl Post for Script { + async fn post(&self, request: &Request) -> crate::Result { + self.log.0.lock().push(request.clone()); + let answer = (self.respond)(request); + match answer { + Some(answer) => answer, + None => std::future::pending().await, + } + } + + async fn post_end(&self, request: &Request) -> crate::Result<()> { + self.log.0.lock().push(request.clone()); + Ok(()) } } @@ -497,25 +526,32 @@ mod tests { tokio::time::pause(); let mut grant = Grant::new(patterns(&["**"]), Patterns::new()); grant.expires = Some(SystemTime::now() - Duration::from_secs(1)); - let client = clock_server(Log::default(), grant, false).await; - assert!(matches!(client.connect(request()).await, Err(Error::GrantExpired))); + let script = Script::new(Log::default(), move |_| Some(Ok(grant.clone()))); + assert!(matches!(script.connect().await, Err(Error::GrantExpired))); } + /// An outage is evidence of nothing: the grant stands through failed re-checks + /// until `expires`, and closes then, not later. #[tokio::test] - async fn a_grant_closes_at_its_expiry() { + async fn an_outage_keeps_the_grant_until_expires() { tokio::time::pause(); - // Whole seconds, as the grant crosses the wire, so the client sees this exact instant. - // An hour out, so a slow runner cannot expire it before `connect` answers. - let now = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).unwrap(); - let expires = SystemTime::UNIX_EPOCH + Duration::from_secs(now.as_secs() + 3600); - let mut grant = Grant::new(patterns(&["**"]), Patterns::new()); - grant.expires = Some(expires); - let client = clock_server(Log::default(), grant, false).await; + let expires = SystemTime::now() + Duration::from_secs(3); + let log = Log::default(); + let script = Script::new(log.clone(), move |request| { + Some(match request.event { + Event::Connect => { + let mut grant = grant(None, Some(Duration::from_secs(1))); + grant.expires = Some(expires); + Ok(grant) + } + _ => Err(Error::Unavailable("auth server answered 503".into())), + }) + }); - // The client reads both clocks somewhere inside `connect`, so bracket it: the - // bounds hold however long it takes. + // `expires` is wall-clock time, which the client maps onto Tokio's clock + // somewhere inside `connect`, so bracket it: the bounds hold however long it takes. let (wall, tick) = (SystemTime::now(), tokio::time::Instant::now()); - let consumer = client.connect(request()).await.unwrap(); + let consumer = script.connect().await.unwrap(); let earliest = tick + expires.duration_since(SystemTime::now()).unwrap(); let latest = tokio::time::Instant::now() + expires.duration_since(wall).unwrap(); @@ -525,51 +561,18 @@ mod tests { tokio::time::timeout_at(earliest - tolerance, consumer.closed()) .await .is_err(), - "live until its expiry" - ); - let reason = tokio::time::timeout_at(latest + tolerance, consumer.closed()) - .await - .expect("closed at its expiry, not later"); - assert_eq!(reason, Reason::Expired); - } - - /// On the real clock: a paused one jumps to the expiry timer whenever the runtime - /// waits on a socket, and macOS delivers loopback asynchronously, so the lease can - /// expire and drop the re-check before the server sees it. Load only delays the - /// close, so asserting it never lands before `expires` holds on a busy machine. - #[tokio::test] - async fn an_outage_keeps_the_grant_until_expires() { - // Whole seconds, as the grant crosses the wire, so the client sees this exact instant. - let now = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).unwrap(); - let expires = SystemTime::UNIX_EPOCH + Duration::from_secs(now.as_secs() + 3); - - let log = Log::default(); - let server = server(log.clone(), move |request| match request.event { - Event::Connect => { - let mut grant = grant(None, Some(Duration::from_secs(1))); - grant.expires = Some(expires); - ResponseTemplate::new(200).set_body_json(grant) - } - Event::Revalidate => ResponseTemplate::new(503), - Event::End { .. } => ResponseTemplate::new(200), - }) - .await; - let consumer = client(&server).connect(request()).await.unwrap(); - - let reason = tokio::time::timeout(Duration::from_secs(10), consumer.closed()) - .await - .expect("expired"); - assert_eq!(reason, Reason::Expired); - assert!(SystemTime::now() >= expires, "an outage must not close before expires"); - assert!( - log.revalidates() >= 1, - "no re-check reached the server during the outage" + "an outage must not close before expires" ); + assert!(log.revalidates() >= 1, "the outage was answered before expires"); assert_eq!( consumer.grant().publish, patterns(&["**"]), "the grant stands through the outage" ); + let reason = tokio::time::timeout_at(latest + tolerance, consumer.closed()) + .await + .expect("closed at expires, not later"); + assert_eq!(reason, Reason::Expired); assert!(matches!( log.end().await.event, Event::End { @@ -582,13 +585,11 @@ mod tests { #[tokio::test] async fn expiry_fires_while_a_recheck_is_stalled() { tokio::time::pause(); - let client = clock_server( - Log::default(), - grant(Some(Duration::from_secs(3)), Some(Duration::from_secs(1))), - true, - ) - .await; - let consumer = client.connect(request()).await.unwrap(); + let script = Script::new(Log::default(), |request| match request.event { + Event::Connect => Some(Ok(grant(Some(Duration::from_secs(3)), Some(Duration::from_secs(1))))), + _ => None, + }); + let consumer = script.connect().await.unwrap(); let reason = tokio::time::timeout(Duration::from_secs(5), consumer.closed()) .await diff --git a/rs/moq-relay/tests/auth_lifetime.rs b/rs/moq-relay/tests/auth_lifetime.rs index a61e794a671..12d305d6c37 100644 --- a/rs/moq-relay/tests/auth_lifetime.rs +++ b/rs/moq-relay/tests/auth_lifetime.rs @@ -4,10 +4,11 @@ //! or QUIC) or its axum WebSocket path (`serve_ws` over `ws://`), points it at a //! scripted auth server, connects a publisher and a subscriber, confirms media //! flows, then asserts the relay follows the server's word: a re-check that moves -//! the tier retags the live session's stats, a narrower grant or a refusal closes it, an outage -//! keeps it until `expires`, and every close reports `end` with what it moved. +//! the tier retags the live session's stats, a narrower grant or a refusal closes it, +//! and every close reports `end` with what it moved. //! The last tests swap the server for an in-process decider answering -//! `Admissions`, and prove the lease it drives reaches the session the same way. +//! `Admissions`, and prove the lease it drives reaches the session the same way, +//! including an outage that keeps it until `expires`, on Tokio's paused clock. use std::sync::{Arc, Mutex}; use std::time::{Duration, SystemTime}; @@ -746,60 +747,6 @@ async fn http_routes_hold_a_lease() { relay.abort(); } -/// An outage keeps the session until `expires`, then closes it as expired. -/// -/// On the real clock: a paused one jumps to the next timer whenever the runtime -/// waits on a socket, and macOS delivers loopback asynchronously, so a virtual -/// timeout can fire before the relay answers. Load only delays the close, so -/// asserting it never lands before `expires` holds on a busy machine. -#[tokio::test] -async fn an_outage_keeps_the_session_until_expires() { - // Whole seconds, as the grant crosses the wire, so the relay sees this exact instant. - let now = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).unwrap(); - let expires = SystemTime::UNIX_EPOCH + Duration::from_secs(now.as_secs() + 3); - - let mut grant = grant(Duration::ZERO); - grant.expires = Some(expires); - let script = Script::new(grant); - script.on_revalidate(Answer::Status(503)); - let (port, relay) = spawn_relay(build_auth(script.spawn().await)).await; - let (pub_session, sub_session) = connect_and_round_trip(&room_url("tcp", port)).await; - - assert_closed(pub_session, TIMEOUT, "publisher").await; - assert!( - SystemTime::now() >= expires, - "an outage must not close the publisher before expires" - ); - let outages = script - .seen - .lock() - .unwrap() - .iter() - .filter(|r| r.event == Event::Revalidate) - .count(); - assert!(outages > 0, "no re-check reached the server during the outage"); - assert_closed(sub_session, TIMEOUT, "subscriber").await; - - let ends = tokio::time::timeout(TIMEOUT, async { - loop { - let ends = script.ends(); - if ends.len() == 2 { - return ends; - } - tokio::time::sleep(Duration::from_millis(10)).await; - } - }) - .await - .expect("both sessions report their end"); - for end in ends { - let Event::End { reason, .. } = &end.event else { - unreachable!() - }; - assert_eq!(*reason, moq_auth::lease::Reason::Expired); - } - relay.abort(); -} - /// A session the client closes reports `end` with its duration and byte counters. /// Over QUIC, the one transport whose connection reports its totals. #[tokio::test] @@ -1041,6 +988,98 @@ async fn a_fixed_lease_still_expires() { } } +/// A connected `(client, server)` session pair over an in-memory byte stream, so a +/// test on Tokio's paused clock never waits on a socket: the clock only advances +/// once every byte in flight has landed. +async fn memory_sessions() -> (moq_net::Session, moq_net::Session) { + let config = || { + let mut config = qmux::Config::new(qmux::Version::QMux01); + config.protocol = qmux::Protocol::Negotiate(moq_net::ALPNS.iter().map(|alpn| alpn.to_string()).collect()); + config + }; + let stream = |io| qmux::transport::Stream::new(io, qmux::Version::QMux01, config().max_record_size); + let (client, server) = tokio::io::duplex(64 * 1024); + let (client, server) = tokio::try_join!( + qmux::Session::connect(stream(client), config()), + qmux::Session::accept(stream(server), config()), + ) + .expect("qmux handshake"); + + let now = tokio::time::Instant::now().into_std(); + let client = async { + let (session, driver) = moq_net::Client::new() + .connect(now, moq_tokio::transport::Session::new(client)) + .await + .expect("client handshake"); + tokio::spawn(moq_net::time::run(driver)); + session + }; + let server = async { + let (session, driver) = moq_net::Server::new() + .accept(now, moq_tokio::transport::Session::new(server)) + .await + .expect("server handshake"); + tokio::spawn(moq_net::time::run(driver)); + session + }; + tokio::join!(client, server) +} + +/// An outage keeps the session until `expires`, then closes it as expired and +/// reports that as its end. A decider that never answers again is an outage as +/// far as the relay can tell, so the relay enforces `expires` itself; how an auth +/// server's outage keeps the grant is `moq_auth::Client`'s to test. +#[tokio::test(start_paused = true)] +async fn an_outage_keeps_the_session_until_expires() { + let expires = SystemTime::now() + Duration::from_secs(3); + let (auth, mut admissions) = moq_relay::auth::Auth::embedded("test-relay"); + let decider = tokio::spawn(async move { + let admission = admissions.next().await.expect("an admission"); + let mut grant = Grant::new(all(), all()); + grant.expires = Some(expires); + let (producer, consumer) = moq_auth::lease::Producer::new(grant); + admission.grant(consumer); + producer + }); + + // `expires` is wall-clock time, which the relay maps onto Tokio's clock + // somewhere inside `admit`, so bracket it: the bounds hold however long it takes. + let (wall, tick) = (SystemTime::now(), tokio::time::Instant::now()); + let lease = auth + .admit(auth.request(moq_auth::Transport::Tcp, "/room")) + .await + .expect("admitted"); + let earliest = tick + expires.duration_since(SystemTime::now()).unwrap(); + let latest = tokio::time::Instant::now() + expires.duration_since(wall).unwrap(); + let producer = decider.await.expect("decider"); + + let (client, server) = memory_sessions().await; + let supervised = tokio::spawn(moq_relay::supervise( + server, + lease, + moq_relay::shutdown::Observer::disabled(), + None, + )); + + // A millisecond either side for Tokio's timer resolution. + let tolerance = Duration::from_millis(1); + assert!( + tokio::time::timeout_at(earliest - tolerance, client.closed()) + .await + .is_err(), + "an outage must not close the session before expires" + ); + tokio::time::timeout_at(latest + tolerance, client.closed()) + .await + .expect("closed at expires, not later"); + let (reason, _) = producer.closed().await; + assert_eq!(reason, moq_auth::lease::Reason::Expired); + supervised + .await + .expect("supervisor") + .expect("a lease end is not a session error"); +} + /// A relay whose config names no auth source is the embedder's to decide: `run` /// refuses to start until the admissions are taken, and once they are, the /// decider's grant admits sessions through the assembled relay. From 39b16cbeda42ab54f1ecb128ec07a155660f0ae1 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 16:53:23 -0700 Subject: [PATCH 075/128] fix(net): a refused update's closed request doesn't end the announce loop Co-Authored-By: Claude Opus 5.5 --- js/net/src/ietf/publisher.test.ts | 32 +++++++++++++++++++++++++++++++ js/net/src/ietf/publisher.ts | 4 +++- 2 files changed, 35 insertions(+), 1 deletion(-) diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index e21788c8a6c..f2db02eb9c3 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -1243,6 +1243,38 @@ test.each([ } }); +/** + * A peer that refuses an update and then closes its side can make our withdrawal's wait + * on the FIN reject. The request is gone either way, so the loop keeps the refusal and + * re-offers the namespace instead of ending. + */ +test("a refused update whose peer closes the request keeps the loop running", async () => { + const { pub, origin, streams, close } = clustered(); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + broadcast.announce({ hops: [VIA], cost: 4n }); + let failed: unknown; + void pub.runPublishNamespaces().catch((err: unknown) => { + failed = err; + }); + + const stream = await take(streams); + await acceptClustered(stream); + + broadcast.announce({ hops: [VIA], cost: 8n }); + await readUpdate(stream); + await declinePublishNamespace(stream, 1n); + stream.close(); + + await advanceUntil(() => streams.length > 0 || failed !== undefined, 10_000); + expect(failed).toBeUndefined(); + const fresh = await take(streams); + expect(await acceptClustered(fresh)).toMatchObject({ cost: 8n }); + } finally { + close(); + } +}); + /** * One update is outstanding per stream, which is what satisfies MAX_REQUEST_UPDATES * without reading it: a change landing while one waits for its answer goes out after. diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 7d01e4963a3..fdc56c0d257 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -1217,7 +1217,9 @@ export class Publisher { return "dropped"; } - if (answer !== "held") await this.#withdraw(path, requests); + // The peer already closed out a refused request, and its STOP_SENDING can reject the + // wait on our FIN. That is the withdrawal finishing, not a reason to end the loop. + if (answer !== "held") await this.#withdraw(path, requests).catch(() => undefined); return answer; } From bfe29e27354215a9ee84a3c0f1a42d637c188e26 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 16:58:41 -0700 Subject: [PATCH 076/128] feat(net): a cluster publisher change updates the advertisement in place Under the IETF cluster extension a first-hop change is an ordinary update: in-flight subscriptions drain the old publisher, new requests take the updated route as a fresh broadcast, and nothing splices across publishers. An anonymous Rust front now ends on a first-hop change like a named one. Co-Authored-By: Claude Opus 5.5 --- doc/bin/relay/cluster.md | 6 ++ doc/concept/moq-lite.md | 5 +- drafts/draft-lcurley-moq-cluster.md | 6 +- js/net/src/announced.test.ts | 2 +- js/net/src/ietf/publisher.test.ts | 52 +++++++++----- js/net/src/ietf/publisher.ts | 12 +--- js/net/src/ietf/subscriber.test.ts | 25 +++++-- js/net/src/ietf/subscriber.ts | 19 ++--- js/net/src/lite/subscriber.test.ts | 95 +++++++++++++++--------- js/net/src/lite/subscriber.ts | 44 ++++-------- quest/m1/README.md | 1 - quest/m1/cluster-publisher-in-place.md | 99 -------------------------- rs/moq-net/src/ietf/publisher.rs | 51 ++++++------- rs/moq-net/src/ietf/subscriber.rs | 57 +++++---------- rs/moq-net/src/model/front.rs | 6 +- rs/moq-net/src/model/origin.rs | 96 ++++++++++++++++++++++++- 16 files changed, 286 insertions(+), 290 deletions(-) delete mode 100644 quest/m1/cluster-publisher-in-place.md diff --git a/doc/bin/relay/cluster.md b/doc/bin/relay/cluster.md index 807becdeaeb..8326e6c364d 100644 --- a/doc/bin/relay/cluster.md +++ b/doc/bin/relay/cluster.md @@ -29,6 +29,12 @@ are spliced in. If no compatible source remains, the track fails with `Unsupported`. New immutable properties require a new track name or broadcast identity. +A route whose original publisher (its first hop) changes is updated in place on +both wire protocols, so the broadcast never briefly vanishes downstream. +Subscriptions already in flight keep draining the old publisher until it ends +and are never spliced onto the new one. New requests resolve through the updated +route as a fresh broadcast, without the old publisher's track properties. + ## Topology List the peers each relay dials. That's the whole topology. diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 91e7ef342bd..853a2bd41f9 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -84,7 +84,10 @@ in flight alone: each track runs to its own end or failure. On moq-lite 05 and newer, a clean end requires `SUBSCRIBE_END` before the publisher's FIN. A FIN without that declaration fails the subscription with `ProtocolViolation`; older moq-lite versions use FIN alone. moq-transport requires `PUBLISH_DONE` before FIN. -moq-transport sessions behave the same when a namespace is withdrawn. +moq-transport sessions behave the same when a namespace is withdrawn. A route +update that changes its first hop, the original publisher, is not a retraction: +subscriptions in flight drain the old publisher, and new requests resolve +through the new one. ### Hidden broadcasts diff --git a/drafts/draft-lcurley-moq-cluster.md b/drafts/draft-lcurley-moq-cluster.md index 912be90e329..5d40640cd41 100644 --- a/drafts/draft-lcurley-moq-cluster.md +++ b/drafts/draft-lcurley-moq-cluster.md @@ -229,7 +229,8 @@ An endpoint MUST NOT open a second stream for an advertisement it already mainta An update replaces the old parameters atomically, so a receiver MUST NOT tear down subscriptions or drop cached state because one arrived. If the first HOP_PATH entry is unchanged the content is continuous and subscriptions MAY resume on the new route at a group boundary, even when that entry is 0: there is one advertisement, and its stream is the continuity. -If the publisher did change, the endpoint MUST withdraw the advertisement (PUBLISH_NAMESPACE_DONE or NAMESPACE_DONE) and advertise again rather than update in place. +If the first entry changed, the publisher changed, and the endpoint still sends an ordinary update. +The receiver keeps each subscription it is already serving on the old source until that source ends, MUST NOT resume or splice it onto the updated route, and serves new requests from the updated route without state cached from the old publisher. The expected update is a ROUTE_COST change, which is how a relay signals that it started or stopped carrying the namespace. @@ -267,7 +268,7 @@ Under this extension an advertisement is a path, so a session advertises a names A receiver MAY still hold paths to several publishers of one namespace and choose between them as it sees fit: serve from the cheapest and move to the next when it fails. A refusal moves to another publisher only as {{selection}} allows: once, and only for NO_CAPACITY. -The advertised path and the served source stay the same publisher: a relay that moves to another MUST withdraw its advertisement and advertise the new path ({{updating}}), so the first Hop ID downstream always names the publisher whose Objects flow. +A relay that moves to another publisher MUST update its advertisement to the new path ({{updating}}), so the first Hop ID downstream names the publisher that new subscriptions reach. Moving between distinct publishers is a discontinuity: their groups are not one sequence, so a subscriber sees an unrelated Location, and a FETCH that succeeds against one may fail against the other. Redundant publishers of the same content avoid this by sharing a Hop ID ({{hop-ids}}), which makes their paths interchangeable and lets a subscription fail over at a group boundary. @@ -330,6 +331,7 @@ This document requests one registration in the "REQUEST_ERROR Codes" registry. ## moq-cluster-02 - Defined request resolution against the longest covering prefix and the NO_CAPACITY refusal with its single re-resolution; any other refusal is terminal, including between several publishers of one namespace. - A relay does not advertise a namespace because it resolved it; the publisher advertises the concrete namespace once producing. +- A change of original publisher is an ordinary update instead of a withdrawal and a new advertisement. Subscriptions already served drain the old source; new requests take the updated route. ## moq-cluster-01 - Assigned identities are local selection state and MUST NOT be forwarded. diff --git a/js/net/src/announced.test.ts b/js/net/src/announced.test.ts index 68adf0d212b..6b11c091fc2 100644 --- a/js/net/src/announced.test.ts +++ b/js/net/src/announced.test.ts @@ -48,7 +48,7 @@ test("a same-name re-announce is a distinct update", async () => { // The stream is a log, not a set: it carries a redundant announce as its own update rather // than collapsing it. Deciding what a repeat means belongs to the session layer, which resolves - // a restart into either nothing (a route change) or an end + start (a new publisher). + // a restart into either nothing (an identical route) or an in-place update. const route = Route.default; producer.append({ prefix: p("a"), captures: undefined, kind: "announced", route }); producer.append({ prefix: p("a"), captures: undefined, kind: "announced", route }); diff --git a/js/net/src/ietf/publisher.test.ts b/js/net/src/ietf/publisher.test.ts index e21788c8a6c..fa9eb24abfd 100644 --- a/js/net/src/ietf/publisher.test.ts +++ b/js/net/src/ietf/publisher.test.ts @@ -1093,7 +1093,7 @@ test("a hop path change behind the same publisher is one REQUEST_UPDATE carrying /** * NAMESPACE has no REQUEST_UPDATE; the receiver reads a repeat as a replacement. That holds - * for a new original publisher too, as in Rust: only a PUBLISH_NAMESPACE is withdrawn for one. + * for a new original publisher too. */ test.each([ ["a hop path and cost change", [VIA, MID], 8n], @@ -1131,23 +1131,40 @@ test.each([ }); /** - * A different broadcast is not a reprice, and on a PUBLISH_NAMESPACE neither is a different - * original publisher: the cluster draft has that withdrawn and advertised again, so a - * receiver never reads two publishers' content as one stream. + * A different original publisher updates the PUBLISH_NAMESPACE in place, as any other + * change does: withdrawing it would make the namespace briefly vanish downstream. */ -const RESTARTS = [ - [ - "a republish", - (origin: OriginProducer, old: BroadcastProducer) => { - const next = origin.createBroadcast(Path.from("mine")); - next.announce({ hops: [VIA], cost: 4n }); - old.close(); - }, - ], - ["a first-hop change", (_: OriginProducer, old: BroadcastProducer) => old.announce({ hops: [OTHER], cost: 4n })], -] as const; +test("a first-hop change is one REQUEST_UPDATE carrying HOP_PATH, not a withdrawal", async () => { + const { self, pub, origin, streams, close } = clustered(); + try { + const broadcast = origin.createBroadcast(Path.from("mine")); + broadcast.announce({ hops: [VIA], cost: 4n }); + void pub.runPublishNamespaces(); -test.each(RESTARTS)("%s withdraws the PUBLISH_NAMESPACE and advertises again", async (_, restart) => { + const stream = await take(streams); + await acceptClustered(stream); + + broadcast.announce({ hops: [OTHER], cost: 4n }); + expect(await readUpdate(stream)).toEqual({ hops: [OTHER, self], cost: undefined }); + await acceptPublishNamespace(stream); + + const more = watch(stream.reader.done()); + await flush(); + expect(more.state).toBe("pending"); + expect(streams).toHaveLength(0); + } finally { + close(); + } +}); + +/** A different broadcast is not an update: it withdraws the old one and advertises again. */ +function republish(origin: OriginProducer, old: BroadcastProducer) { + const next = origin.createBroadcast(Path.from("mine")); + next.announce({ hops: [VIA], cost: 4n }); + old.close(); +} + +test("a republish withdraws the PUBLISH_NAMESPACE and advertises again", async () => { const { pub, origin, streams, close } = clustered(); try { const broadcast = origin.createBroadcast(Path.from("mine")); @@ -1157,7 +1174,7 @@ test.each(RESTARTS)("%s withdraws the PUBLISH_NAMESPACE and advertises again", a const old = await take(streams); await acceptClustered(old); - restart(origin, broadcast); + republish(origin, broadcast); // Draft-17+ withdraws with the FIN alone, and the replacement waits for it. expect(await old.reader.done()).toBe(true); @@ -1184,7 +1201,6 @@ test("a republish withdraws the solicited NAMESPACE and sends it again", async ( expect(await subscription.reader.u53()).toBe(SubscribeNamespaceEntry.id); await SubscribeNamespaceEntry.decode(subscription.reader, VERSION, true); - const [, republish] = RESTARTS[0]; republish(origin, broadcast); expect(await subscription.reader.u53()).toBe(SubscribeNamespaceEntryDone.id); diff --git a/js/net/src/ietf/publisher.ts b/js/net/src/ietf/publisher.ts index 75124c97550..170e70b32ad 100644 --- a/js/net/src/ietf/publisher.ts +++ b/js/net/src/ietf/publisher.ts @@ -1150,7 +1150,7 @@ export class Publisher { } /** - * Reprice a namespace the peer holds: REQUEST_UPDATE on the request that carries it, + * Update a namespace the peer holds: REQUEST_UPDATE on the request that carries it, * with only the parameters that changed, then its answer. * * Waiting for the answer keeps one update outstanding per stream, which satisfies any @@ -1160,16 +1160,10 @@ export class Publisher { * finished too, and an unanswered update is dropped abruptly, since a peer that ignored * it cannot be assumed to hold either price. Either way the retry re-offers it fresh. * - * A different original publisher is not an update. draft-lcurley-moq-cluster has it - * withdrawn and advertised again, so the receiver never reads two publishers' content - * as one continuous stream. A NAMESPACE has no such rule and is simply sent again. + * A different original publisher is an update like any other: the receiver drains what + * it already serves from the old one and never splices the two. */ async #update(path: Path.Valid, requests: Requests, { from, to }: Reprice): Promise { - if (from.hops[0] !== to.hops[0]) { - await this.#withdraw(path, requests); - return await this.#advertise(path, requests, to); - } - const request = requests.get(path); if (!request) return "dropped"; diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index 001d1aca3a7..18968dbe625 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -615,11 +615,11 @@ test("a PUBLISH_NAMESPACE repricing is acknowledged in place", async () => { }); /** - * An update whose first Hop ID differs names a different publisher, whose content is not - * continuous with what is held. The draft has the sender withdraw and advertise again - * instead, so the update is refused and the stream closed, which is that withdrawal. + * An update whose first Hop ID differs names a different publisher. It still updates the + * advertisement in place and the stream stays open. A broadcast already held keeps + * draining, while the next consume starts fresh. */ -test("a PUBLISH_NAMESPACE update that changes the publisher is refused", async () => { +test("a PUBLISH_NAMESPACE update that changes the publisher applies in place", async () => { const pair = createMockTransportPair(ALPN.DRAFT_19); const session = new NativeSession(pair.server, VERSION, true); const subscriber = new Subscriber({ session, cluster: { self: SELF, peer: PEER } }); @@ -642,16 +642,27 @@ test("a PUBLISH_NAMESPACE update that changes the publisher is refused", async ( if (!peer) throw new Error("no PUBLISH_NAMESPACE stream"); expect(await peer.reader.u53()).toBe(RequestOk.id); await RequestOk.decode(peer.reader, VERSION); + const held = subscriber.consume(Path.from("theirs")); await peer.writer.u53(PublishNamespaceUpdate.id); await new PublishNamespaceUpdate({ requestId: 3n, update: { hops: [HopSchema.parse(8n), PEER] } }).encode( peer.writer, VERSION, ); - expect(await peer.reader.u53()).toBe(RequestError.id); - await RequestError.decode(peer.reader, VERSION); + expect(await peer.reader.u53()).toBe(RequestOk.id); + await RequestOk.decode(peer.reader, VERSION); + expect(await announced.next()).toMatchObject({ + prefix: Path.from("theirs"), + kind: "updated", + route: { hops: [HopSchema.parse(8n), PEER] }, + }); + + const fresh = subscriber.consume(Path.from("theirs")); + expect(fresh.closed).not.toBe(held.closed); + expect(held.closed.peek()).toBeUndefined(); - // The refusal closed the stream, which withdrew the advertisement. + // Still announced: the stream ending is what retracts it. + peer.close(); await handler; expect(await announced.next()).toMatchObject({ prefix: Path.from("theirs"), kind: "retracted" }); }); diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 9b9833d15ee..3e727bf8335 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -242,10 +242,14 @@ export class Subscriber { * Replace the stored route for a path that is already announced. A no-op when the * hops and cost did not change; otherwise consumers hear `updated` so a forwarder * can reprice without retracting. + * + * A new first hop is a new publisher: holders keep their broadcast to drain, but the + * next consume starts fresh rather than reusing the old publisher's cached track info. */ #updateAnnounce(path: Path.Valid, route: Route) { const existing = this.#announced.get(path); if (existing === undefined || routesEqual(existing.route, route)) return; + if (existing.route.hops[0] !== route.hops[0]) this.#consumes.evict(path); existing.route = route; console.debug(`announced: broadcast=${path} rerouted`); for (const [consumer, filter] of this.#announcedConsumers) { @@ -895,20 +899,7 @@ export class Subscriber { throw new ProtocolViolation("cluster parameters on a session that negotiated none"); } } else { - // A different original publisher is a different advertisement, which the - // draft has withdrawn and made again: its content is not continuous with - // what is held. Refusing the update closes the stream, which is that - // withdrawal. - if (update.update.hops !== undefined && update.update.hops[0] !== held.hops[0]) { - console.warn(`publish_namespace update changes the publisher: broadcast=${path}`); - await stream.writer.u53(RequestError.id); - await new RequestError({ - errorCode: toRequestCode("not_supported", "publish_namespace", version), - reasonPhrase: "a new publisher is a new advertisement", - }).encode(stream.writer, version); - stream.close(); - return; - } + // A different original publisher applies in place too, as it does inline. held = Cluster.apply(held, update.update); } diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index f9dec8b9016..e401d509330 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -225,41 +225,61 @@ test("a received chain with hop 0 is marked anonymous", async () => { subscriber.close(); }); -test("a restart from the same publisher is a route change, not a republish", async () => { +test("a restart updates the route in place, even from another publisher", async () => { const { subscriber, send, settle } = announceHarness(Version.DRAFT_06); const announced = subscriber.announced(); await settle(); + const room = Path.from("room"); await send((w) => new AnnounceOk(PEER, 0).encode(w, Version.DRAFT_06)); + await send((w) => + encodeAnnounceBroadcast(w, { status: "active", suffix: room, hops: [PUBLISHER_A] }, Version.DRAFT_06), + ); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "announced" }); + const held = subscriber.consume(room); + + // Same publisher over an identical route: no metadata to forward, so nothing surfaces. + await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [PUBLISHER_A] }, Version.DRAFT_06)); + + // A reprice from the same publisher surfaces, which proves the identical restart above + // emitted nothing. The same publisher keeps sharing one broadcast. await send((w) => encodeAnnounceBroadcast( w, - { status: "active", suffix: Path.from("room"), hops: [PUBLISHER_A] }, + { status: "restart", id: 0n, hops: [PUBLISHER_A], cost: { warm: 4n, cold: 4n } }, Version.DRAFT_06, ), ); - expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "announced" }); - - // Same publisher over an identical route. In-flight subscriptions resume across it, - // and there is no metadata to forward, so the subscriber must not surface a restart. - await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [PUBLISHER_A] }, Version.DRAFT_06)); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "updated" }); + const same = subscriber.consume(room); + expect(same.closed).toBe(held.closed); - // A different publisher took the path: nothing carries over, so this one does surface, - // as an end before the start. Reaching it proves the identical reroute above emitted nothing. + // A different publisher took the path: an in-place update, never a retraction. await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [PUBLISHER_B] }, Version.DRAFT_06)); - expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "retracted" }); - expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "announced" }); + expect(await announced.next()).toMatchObject({ + prefix: room, + kind: "updated", + route: { hops: [PUBLISHER_B, PEER] }, + }); - // A third publisher takes over. The replacement above has to leave its own publisher on - // record, or this one reads as a first announcement and skips the end. - await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [PUBLISHER_C] }, Version.DRAFT_06)); - expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "retracted" }); - expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "announced" }); + // The holder keeps its broadcast to drain, but the next consume starts fresh rather + // than reusing the old publisher's cached track info. + const fresh = subscriber.consume(room); + expect(fresh.closed).not.toBe(held.closed); + expect(held.closed.peek()).toBeUndefined(); - // And the new owner's own reroute is still transparent. + // A third publisher is another update. The one above has to leave its own publisher on + // record, or this one would not read as a change. await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [PUBLISHER_C] }, Version.DRAFT_06)); + expect(await announced.next()).toMatchObject({ + prefix: room, + kind: "updated", + route: { hops: [PUBLISHER_C, PEER] }, + }); + expect(subscriber.consume(room).closed).not.toBe(fresh.closed); + await send((w) => encodeAnnounceBroadcast(w, { status: "endedId", id: 0n }, Version.DRAFT_06)); - expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "retracted" }); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "retracted" }); announced.close(); subscriber.close(); @@ -316,33 +336,41 @@ test("a lite-05 duplicate announce follows the same restart rule", async () => { // On lite-05 a restart travels as a duplicate ANNOUNCE rather than its own message. await send(active([PUBLISHER_A])); await send(active([PUBLISHER_B])); - expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "retracted" }); - expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "announced" }); + expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "updated" }); announced.close(); subscriber.close(); }); // A responder that withholds its Hop ID sends the reserved 0, and an empty chain means it -// originated the path itself, so the advertisement names nobody. Two such advertisements can -// be unrelated publishers, so a restart must replace the broadcast rather than reroute it: -// cached track info and in-flight subscriptions must not splice across them. Mirrors the Rust -// `unknown_publisher_restart_replaces` regression. -test("a restart from an unidentified publisher replaces rather than reroutes", async () => { +// originated the path itself, so the advertisement names nobody. A restart of it is still the +// one advertisement, whose stream is the continuity, so it updates in place like Rust's and +// keeps the shared broadcast. Only a first hop that changes names a new publisher. +test("a restart from an unidentified publisher updates in place", async () => { const { subscriber, send, settle } = announceHarness(Version.DRAFT_06); const announced = subscriber.announced(); await settle(); + const room = Path.from("room"); await send((w) => new AnnounceOk(UNKNOWN_HOP, 0).encode(w, Version.DRAFT_06)); + await send((w) => encodeAnnounceBroadcast(w, { status: "active", suffix: room, hops: [] }, Version.DRAFT_06)); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "announced" }); + const held = subscriber.consume(room); + await send((w) => - encodeAnnounceBroadcast(w, { status: "active", suffix: Path.from("room"), hops: [] }, Version.DRAFT_06), + encodeAnnounceBroadcast( + w, + { status: "restart", id: 0n, hops: [], cost: { warm: 4n, cold: 4n } }, + Version.DRAFT_06, + ), ); - expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "announced" }); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "updated" }); + expect(subscriber.consume(room).closed).toBe(held.closed); - // Nobody is named on either side, so this is not provably the same content. - await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [] }, Version.DRAFT_06)); - expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "retracted" }); - expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "announced" }); + // Naming a publisher is a change of publisher: the next consume starts fresh. + await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [PUBLISHER_A] }, Version.DRAFT_06)); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "updated" }); + expect(subscriber.consume(room).closed).not.toBe(held.closed); announced.close(); subscriber.close(); @@ -683,11 +711,10 @@ test("a draft-05 duplicate start is still a restart", async () => { // Same publisher over a new route: transparent, and emphatically not an error. await send((w) => encodeAnnounceBroadcast(w, active, Version.DRAFT_05)); - // A different publisher does surface, which is what proves the reroute above passed. + // A different publisher surfaces as an update, which is what proves the reroute above passed. const replaced: AnnounceBroadcast = { status: "active", suffix: Path.from("room"), hops: [PUBLISHER_B] }; await send((w) => encodeAnnounceBroadcast(w, replaced, Version.DRAFT_05)); - expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "retracted" }); - expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "announced" }); + expect(await announced.next()).toMatchObject({ prefix: Path.from("room"), kind: "updated" }); announced.close(); subscriber.close(); diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 61c3e7aaf25..567d06475f1 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -241,9 +241,9 @@ export class Subscriber { // the map instead would let a later announce take the path, and the skipped one's // `endedId` would then retract that one's state. // - // `publisher` is what lets a restart tell a route change (same publisher, - // subscriptions resume) from a replacement (a new generation took the path, - // nothing carries over). + // `publisher` is what lets a restart tell a route change (same publisher) from a + // new publisher on the route, whose content the next consume must not share + // with the old one's. type Advertisement = { publisher: Hop | undefined; live: boolean; @@ -398,14 +398,8 @@ export class Subscriber { } // The first hop identifies the original publisher; an empty chain means the - // peer itself originated it. See `restart_announce` in the Rust subscriber. + // peer itself originated it. const publisher = hops?.[0] ?? responderOrigin; - - // A publisher with no identity (an empty chain from a peer that withheld its - // own id, or a lite-03 UNKNOWN placeholder) never proves continuity: two such - // advertisements can be unrelated publishers. Mirrors the - // `publisher == Hop::UNKNOWN` arm of the Rust `restart_announce`. - const identified = publisher !== undefined && publisher !== UNKNOWN_HOP; const fullHops = hops !== undefined && responderOrigin !== undefined ? [...hops, responderOrigin] @@ -432,30 +426,22 @@ export class Subscriber { } // A second advertisement for a path we already carry is a restart: either an - // explicit ANNOUNCE_UPDATE, or (lite-05) a duplicate ANNOUNCE. + // explicit ANNOUNCE_UPDATE, or (lite-05) a duplicate ANNOUNCE. It updates the + // route in place, so a forwarder re-prices without retracting. const previous = advertised.get(path); if (previous?.live) { - if (identified && previous.publisher === publisher) { - // Same publisher, new route. In-flight subscriptions resume across it. - // Emit the route so a forwarder can re-price without retracting. - if (!routesEqual(previous.route, route)) { - advertised.set(path, { publisher, live: true, route, captures }); - console.debug(`announced: broadcast=${path} rerouted`); - announced.append({ prefix: path, captures, kind: "updated", route }); - } else { - console.debug(`announced: broadcast=${path} rerouted`); - } - continue; + // A different publisher took the path. Subscriptions already open drain + // the old copy, but the next consume starts fresh rather than reusing the + // old publisher's cached track info. + if (previous.publisher !== publisher) this.#consumes.evict(path); + advertised.set(path, { publisher, live: true, route, captures }); + console.debug(`announced: broadcast=${path} rerouted`); + if (!routesEqual(previous.route, route)) { + announced.append({ prefix: path, captures, kind: "updated", route }); } - - // A different publisher took the path, so cached track info and existing - // subscriptions must not carry over. Surface a real end before the start. - retract(); + continue; } - // After `retract()`, which clears the entry: the path is advertised again, by - // whoever just took it over. Recording it before would leave nothing behind, so - // the *next* takeover would read as a first announcement and skip its own end. advertised.set(path, { publisher, live: true, route, captures }); console.debug(`announced: broadcast=${path} active=true`); diff --git a/quest/m1/README.md b/quest/m1/README.md index 99b24c227eb..efb5b364a03 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -58,7 +58,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Go and Dart doc samples](/quest/m1/doc-samples-go-dart.md) - Go and Dart doc samples compile against their wrappers - [Data capture in bindings](/quest/m1/data-capture-bindings.md) - moq-ffi and every wrapper pass a data frame's capture time, and the JSON window producer takes one - [Moxygen compatibility](/quest/m1/moxygen/README.md) - one subgroup per group, whole-group FETCH, and one datagram per group, never a full moxygen pass -- [Cluster publisher in place](/quest/m1/cluster-publisher-in-place.md) - under the IETF cluster extension a publisher change updates an advertisement in place, like lite, and never splices across publishers - [JS IETF datagrams](/quest/m1/js-ietf-datagram.md) - `@moq/net` sends and receives datagram groups over moq-transport, like Rust - [#2991](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - one dynamic producer per track name in both languages, with the sequence namespace surviving a replacement - [JavaScript FETCH](/quest/m1/js-fetch.md) - generic on-demand group serving and IETF FETCH for browser publishers diff --git a/quest/m1/cluster-publisher-in-place.md b/quest/m1/cluster-publisher-in-place.md deleted file mode 100644 index d58c7231e65..00000000000 --- a/quest/m1/cluster-publisher-in-place.md +++ /dev/null @@ -1,99 +0,0 @@ -# [M] A publisher change updates a cluster advertisement in place - -## Goal - -Under the IETF cluster extension, an advertisement whose original publisher -(first HOP_PATH entry) changes is updated in place, like any other change, -instead of withdrawn and advertised again. A subscriber never sees a -namespace briefly vanish because its publisher moved. Subscriptions already -served from the old publisher drain it until it ends; new requests take the -updated route; nothing is resumed or spliced across two publishers. - -## Plan - -Decided 2026-09-28: match moq-lite. A route's first hop is its identity: -routes update in place, and across differing first hops a relay must not -splice a live subscription. The cluster draft instead requires -PUBLISH_NAMESPACE_DONE or NAMESPACE_DONE and a fresh advertisement, using the -withdraw to force that discontinuity. The maintainer prefers updating over -quickly toggling a namespace. - -Decided 2026-09-29 by the maintainer: a first-hop update does not end -subscriptions already served from the old publisher. In-flight tracks keep -draining the old copy until it ends on its own, and new requests take the -updated route. This replaces the earlier same-day decision to end them and -fail over to another route from the old publisher. Why: the lite draft -already leaves in-flight subscriptions "undisturbed" by ANNOUNCE_UPDATE, the -cluster draft already forbids tearing down subscriptions because an update -arrived, and Rust already drains: a front pinned to `Pin::Publisher` stops -qualifying once its route's first hop changes (`qualifies` in -`rs/moq-net/src/model/origin.rs`), and `selected(None)` in `front.rs` ends -it, which stops new requests while its live copies play out. Draining needs -no abort plumbing and no draft narrowing. - -Decided 2026-09-29 by the maintainer: one rule for both kinds of front. A -front never serves through a publisher other than the one it started with. -A named front may still resume through another route from its own -publisher, as lite allows; once none remains it ends. An anonymous front has -no publisher to match, so a first-hop change on its route ends it. Either -way in-flight tracks drain and new requests get a fresh front. Why: pinning -an anonymous front to its route id rather than a publisher is an -implementation detail, and it should not let a new publisher inherit the old -broadcast's track info. - -Decided 2026-09-29: accept the compatibility break. Released moq-net (0.3.5 -and later) refuses a first-hop REQUEST_UPDATE with a retry interval of 0, -which leaves a moved publisher withdrawn on that session during a rolling -upgrade. Only this tree's relays speak the cluster extension, so there is no -withdraw fallback and no negotiation. - -- `drafts/draft-lcurley-moq-cluster.md` (Updating an Advertisement, and the - "moves to another MUST withdraw" line under Several Publishers): a - publisher change is sent as an ordinary update (REQUEST_UPDATE, or a - re-sent NAMESPACE). A receiver that sees the first entry change keeps - in-flight subscriptions on the old source until it ends, serves new - requests from the updated route, and MUST NOT resume or splice a - subscription onto it. Add a changelog entry, and run `just drafts check`. -- Rust `rs/moq-net/src/ietf/publisher.rs` (`sync_namespace`): the - PUBLISH_NAMESPACE path stops withdrawing on a first-hop change; the inline - path already updates in place. -- Receivers in both languages accept a first-hop change in place instead of - refusing it: `run_publish_namespace_updates` in - `rs/moq-net/src/ietf/subscriber.rs` and `runPublishNamespace` in - `js/net/src/ietf/subscriber.ts` close the stream today. -- Rust model: end an anonymous front on a first-hop change, removing an - accidental asymmetry. A named front is pinned by publisher - (`Pin::Publisher`), so a first-hop update disqualifies that route and the - front resumes through another route from its publisher, or ends. An anonymous - front (first hop 0) is pinned to a route id (`Pin::Route`), which an - in-place update keeps, so today it goes on serving new requests through the - new publisher with the old broadcast's cached track info. -- JS lite `js/net/src/lite/subscriber.ts`: a different first hop calls - `retract()` and announces again, so a forwarding relay withdraws the - namespace. Emit an in-place update instead. In-flight subscriptions drain - the old copy, and new requests neither reuse the old publisher's cached - track info nor splice onto a live subscription, matching Rust. -- JS sender `js/net/src/ietf/publisher.ts` (`#update`): the - PUBLISH_NAMESPACE path stops withdrawing on a first-hop change and sends a - REQUEST_UPDATE, as Rust will; the inline path already re-sends NAMESPACE in - place, like Rust's. -- Docs: `doc/bin/relay/cluster.md`, and any `doc/concept` page that - describes the cluster extension, say a publisher change updates in place, - in-flight subscriptions drain the old publisher, and new requests take the - new one. -- Tests in both languages: a first-hop change sends one update and no - withdrawal; the receiver applies it without closing the stream; an - in-flight subscription keeps receiving the old publisher's groups until - that copy ends and never receives a group from the new one; a request - after the update resolves through the new publisher without the old - publisher's track info. Cover an anonymous (hop 0) to named change, a named - front that resumes through a remaining route from its own publisher and - never through the new one, and a lite ANNOUNCE_UPDATE in JS. Run `just test interop --all`. - -Public API: none. Wire: the cluster extension's update semantics change (no -message or parameter changes), breaking first-hop updates toward released -relays as decided above. - -## Related - -- [Cluster routing](/quest/m1/cluster-routing.md) - the routing plan these advertisements feed diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 775283b2cba..f776cea7465 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -1383,7 +1383,7 @@ where (true, Some(_)) => { tracing::debug!(broadcast = %absolute, "publish_namespace update"); refused = self - .update_namespace(target, requests, path, suffix, &watch.sent, &advert) + .update_namespace(target, requests, suffix, &watch.sent, &advert) .await?; } (true, None) => { @@ -1515,7 +1515,7 @@ where Ok(Refused::No) } - /// Reprice a namespace the peer holds: REQUEST_UPDATE on the request that carries + /// Update a namespace the peer holds: REQUEST_UPDATE on the request that carries /// it, with only the parameters that changed, then its answer. /// /// Waiting for the answer keeps one update outstanding per stream, which satisfies @@ -1526,16 +1526,14 @@ where /// is dropped the same way, since a peer that ignored it cannot be assumed to hold /// either price. /// - /// A different original publisher is not an update. The cluster draft has it - /// withdrawn and advertised again, so the receiver never reads two publishers' - /// content as one continuous stream. + /// A different original publisher is an update like any other: the receiver + /// drains what it already serves from the old one and never splices the two. /// /// Returns what the refusal, if any, said about coming back. async fn update_namespace( &self, target: &mut Target, requests: &mut HashMap>, - path: &crate::PathOwned, suffix: &crate::PathOwned, held: &Advert, advert: &Advert, @@ -1545,13 +1543,6 @@ where let (Some(next), Some(held)) = (advert.params(), held.params()) else { return Ok(Refused::No); }; - if held.hops.hops().iter().next() != next.hops.hops().iter().next() { - tracing::debug!(broadcast = %self.origin.absolute(path), "publisher changed; advertising again"); - self.withdraw_namespace(target, requests, suffix.clone()).await?; - return self - .advertise_namespace(requests, path, suffix.clone(), Some(next)) - .await; - } let Some(request) = requests.get_mut(suffix) else { return Ok(Refused::No); }; @@ -4653,11 +4644,11 @@ mod tests { assert_eq!(log.bi_opens(), 1, "the update rode the request's own stream"); } - /// A route from a different original publisher is not an update: its content is not - /// continuous with what the peer holds, so the draft has the advertisement withdrawn - /// and made again rather than repriced in place. + /// A route from a different original publisher updates the advertisement in place, + /// like any other change: withdrawing it would make the namespace briefly vanish + /// downstream just because its publisher moved. #[tokio::test] - async fn a_publisher_change_is_withdrawn_and_advertised_again() { + async fn a_publisher_change_is_a_request_update() { const VERSION: Version = Version::Draft19; let origin = crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(); @@ -4671,9 +4662,9 @@ mod tests { .unwrap(); settle().await; - // Stream 1 accepts the advertisement from A; stream 2 accepts the one from B. + // One stream: the advertisement from A and its update to B, each answered OK. let ok = publish_namespace_ok(VERSION).await; - let session = crate::lite::test_transport::ScriptedSession::per_stream(vec![ok.clone(), ok]); + let session = crate::lite::test_transport::ScriptedSession::per_stream(vec![[ok.clone(), ok].concat()]); let log = session.log.clone(); let publisher = Publisher::new( @@ -4703,16 +4694,6 @@ mod tests { crate::origin::Route::default().with_hops(publisher_b).with_cost(0), ) .unwrap(); - for _ in 0..100 { - assert!(futures::poll!(run.as_mut()).is_pending()); - if occurrences(&log, b"cam") >= 2 { - break; - } - settle().await; - } - - assert_eq!(occurrences(&log, b"cam"), 2, "advertised again for the new publisher"); - assert_eq!(log.bi_opens(), 2, "on a fresh request stream"); let update = request_update( VERSION, &ietf::PublishNamespaceUpdate { @@ -4724,7 +4705,17 @@ mod tests { }, ) .await; - assert_eq!(occurrences(&log, &update), 0, "a publisher change is never an update"); + for _ in 0..100 { + assert!(futures::poll!(run.as_mut()).is_pending()); + if occurrences(&log, &update) >= 1 { + break; + } + settle().await; + } + + assert_eq!(occurrences(&log, &update), 1, "REQUEST_UPDATE carrying B's path"); + assert_eq!(occurrences(&log, b"cam"), 1, "PUBLISH_NAMESPACE was not repeated"); + assert_eq!(log.bi_opens(), 1, "no withdrawal and no second stream"); } /// A peer that refuses an update closes the stream, which withdraws the diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 000610327d2..53834b661e2 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -1082,30 +1082,10 @@ where // An omitted parameter keeps its value, so the update lands on what the peer // already advertised. The parameters exist only on a session that negotiated // the extension; anywhere else they are the peer's violation. + // A different original publisher applies in place too: the origin drains what + // the old one already serves and never splices the two. held = match &held { - Some(current) => { - // A different original publisher is a different advertisement, which - // the draft has withdrawn and made again: applying it in place would - // carry subscriptions across content that is not continuous. Refusing - // the update closes the stream, which is the withdrawal the peer owed. - if let Some(hops) = &msg.hops - && hops.hops().iter().next() != current.hops.hops().iter().next() - { - tracing::warn!(%path, "publish_namespace update changes the publisher"); - self.write_error( - stream, - msg.request_id, - &Error::Unsupported, - "a new publisher is a new advertisement", - ) - .await?; - if stream.writer.finish().is_ok() { - let _ = stream.writer.closed().await; - } - return Ok(()); - } - Some(msg.apply(current)) - } + Some(current) => Some(msg.apply(current)), None if msg.hops.is_some() || msg.cost.is_some() => { tracing::warn!(%path, "cluster parameters on a session that negotiated none"); return Err(Error::ProtocolViolation); @@ -4716,8 +4696,7 @@ mod tests { } /// An update replaces the advertisement in place: the route moves, the refcount does - /// not, and the source is not torn down. Only a changed original publisher replaces - /// it, since that content is not interchangeable. + /// not, and the source is not torn down. #[tokio::test] async fn cluster_update_replaces_in_place() { let (mut subscriber, origin) = cluster_subscriber(crate::Hop::new(1).unwrap()); @@ -5234,12 +5213,11 @@ mod tests { assert_eq!(replies(&log, ietf::RequestOk::ID), 0); } - /// An update whose first Hop ID differs names a different publisher, whose content - /// is not continuous with what is held. The draft has the sender withdraw and - /// advertise again instead, so the update is refused and the stream closed, which - /// is that withdrawal. + /// An update whose first Hop ID differs names a different publisher. It still + /// replaces the advertisement in place and the stream stays open: the origin, not the + /// session, keeps the two publishers' content apart. #[tokio::test] - async fn an_update_that_changes_the_publisher_is_refused() { + async fn an_update_that_changes_the_publisher_applies_in_place() { let self_origin = crate::Hop::new(5).unwrap(); let peer = peer_9(); let (clean, _) = clean_and_looped(); @@ -5255,7 +5233,6 @@ mod tests { let path = crate::Path::new("room/host").to_owned(); let mut attached = true; - let mut result = None; { let mut run = std::pin::pin!(subscriber.run_publish_namespace_updates( &mut stream, @@ -5265,20 +5242,20 @@ mod tests { &mut attached, )); for _ in 0..20 { - if let std::task::Poll::Ready(res) = futures::poll!(run.as_mut()) { - result = Some(res); - break; - } + assert!( + futures::poll!(run.as_mut()).is_pending(), + "a publisher change must not close the stream" + ); settle().await; } } - assert!(matches!(result, Some(Ok(()))), "refused cleanly, got {result:?}"); - assert_eq!(replies(&log, ietf::RequestError::ID), 1, "REQUEST_ERROR went out"); - assert_eq!(replies(&log, ietf::RequestOk::ID), 0); - let route = routed_now(&consumer, "room/host").expect("the caller releases the route"); + assert!(attached, "the advertisement stays attached"); + assert_eq!(replies(&log, ietf::RequestOk::ID), 1, "REQUEST_OK went out"); + assert_eq!(replies(&log, ietf::RequestError::ID), 0); + let route = routed_now(&consumer, "room/host").expect("still routed"); let hops: Vec<_> = route.hops.iter().map(|h| h.id()).collect(); - assert_eq!(hops, vec![7, 9], "the held path was not replaced"); + assert_eq!(hops, vec![8, 9], "the held path was replaced"); } /// A second PUBLISH_NAMESPACE on the stream that already carries one is not an diff --git a/rs/moq-net/src/model/front.rs b/rs/moq-net/src/model/front.rs index 4f0ed264427..93eae6197f9 100644 --- a/rs/moq-net/src/model/front.rs +++ b/rs/moq-net/src/model/front.rs @@ -138,7 +138,8 @@ pub(super) enum Identity { Local, /// The serving route's first hop was absent or [`Hop::UNKNOWN`], which /// identifies nobody: the front cannot resume through any other route, so - /// its source ending, or `route` leaving the table, ends it. + /// its source ending, `route` leaving the table, or `route` gaining a first + /// hop ends it. Anonymous { route: u64 }, /// The first hop of the serving route. Routes sharing it are the same /// origin reached another way and safe to resume through. @@ -154,7 +155,8 @@ pub(super) enum Pin { Local, /// Only routes originated by this first hop. Publisher(Hop), - /// Only this route: the front never fails over. + /// Only this route, while its publisher stays unknown: the front never fails + /// over, and an update naming a publisher ends it. Route(u64), } diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 14d07b814f3..3850310dc0d 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -780,7 +780,8 @@ impl RouteEntry { Pin::Any => true, Pin::Local => self.local, Pin::Publisher(first) => self.hops.iter().next() == Some(&first), - Pin::Route(id) => self.id == id, + // An update that names a publisher is a different one, even in place. + Pin::Route(id) => self.id == id && self.hops.iter().next().is_none_or(|first| *first == Hop::UNKNOWN), } } @@ -1821,6 +1822,13 @@ impl AnnounceProducer { let Some(entry) = shared.routes.entry_mut(prefix, *id) else { return Err(Error::Closed); }; + // A new first hop is a new publisher: a later request goes back to the + // handler rather than joining what the old one served. + if entry.hops.iter().next() != route.hops.iter().next() + && let Some(server) = &entry.server + { + drop(std::mem::take(&mut server.lock().served)); + } entry.hops = route.hops.clone(); entry.stale = stale; entry.cost = route.cost; @@ -3371,8 +3379,10 @@ impl Dynamic { /// Re-price the route in place: replace its hops and cost. /// /// Consumers observe another active update for the same prefix; sessions - /// forward it as a restart, so route churn never looks like new content. The - /// prefix is fixed at announce time: to move a route, drop this and call + /// forward it as a restart, so route churn never looks like new content. A + /// new first hop is a new publisher: broadcasts already served from the old + /// one drain, and later requests reach the handler again. The prefix is fixed + /// at announce time: to move a route, drop this and call /// [`Producer::dynamic`] again. Fails with [`Error::Closed`] once the origin's /// [`Driver`] has been dropped. pub fn update(&self, route: Route) -> Result<(), Error> { @@ -6828,6 +6838,86 @@ mod tests { pending.await.expect("re-request resolves through the rival"); } + /// A route updated in place to a new first hop names a new publisher, whether the + /// front started anonymous or named. The in-flight subscription drains the old copy + /// until it ends and never splices the new one; a new request gets a fresh front + /// through the new publisher, free of the old broadcast's track info. + #[tokio::test] + async fn a_first_hop_update_drains_the_old_publisher() { + for first in [&[][..], &[0][..], &[10][..]] { + let (mut rig, server, _source) = ResumeRig::new(first).await; + server.update(Route::default().with_hops(hops(&[11]))).unwrap(); + + // The old copy keeps flowing to the subscription already reading it. + let mut group = rig.incumbent_track.append_group().unwrap(); + group.write_frame(crate::Timestamp::ZERO, b"draining".as_ref()).unwrap(); + group.finish().unwrap(); + let mut group = next_group(&mut rig.subscription) + .await + .expect("the in-flight subscription survives the update") + .expect("track ended early"); + let frame = group.read_frame().await.expect("read frame").expect("frame"); + assert_eq!(&frame.payload[..], b"draining", "first hop {first:?}"); + + // A new request is a new broadcast from the new publisher, whose track info + // differs from what the old front cached. + let consumer = rig.producer.consume(); + let pending = consumer.request_broadcast("room/alice"); + let request = queued(&server).await; + let replacement = broadcast::Info::new().produce(); + let track = replacement + .create_track("video", track::Info::default().with_priority(7)) + .unwrap(); + let mut group = track.append_group().unwrap(); + group.write_frame(crate::Timestamp::ZERO, b"new".as_ref()).unwrap(); + group.finish().unwrap(); + request.accept(&replacement); + + let resolved = pending.await.expect("resolves through the new publisher"); + assert!( + !resolved.is_clone(&rig.resolved), + "first hop {first:?} joined the old front" + ); + let mut fresh = resolved + .track("video") + .unwrap() + .subscribe(None) + .await + .expect("the old publisher's track info does not apply"); + let mut group = next_group(&mut fresh) + .await + .expect("recv group") + .expect("track ended early"); + let frame = group.read_frame().await.expect("read frame").expect("frame"); + assert_eq!(&frame.payload[..], b"new"); + + // The old copy ending ends the drained subscription, without a group from + // the new publisher. + rig.incumbent_track.finish().unwrap(); + let end = next_group(&mut rig.subscription).await; + assert!( + !matches!(end, Ok(Some(_))), + "first hop {first:?} spliced the new publisher into a live subscription" + ); + } + } + + /// A named front whose route moves to a new publisher resumes through another route + /// from its own publisher, never through the updated one. + #[tokio::test] + async fn a_first_hop_update_resumes_through_the_same_publisher() { + let (mut rig, incumbent, _source) = ResumeRig::new(&[10]).await; + let standby_server = rig.standby(&[10, 20]); + + incumbent.update(Route::default().with_hops(hops(&[11]))).unwrap(); + + assert_resumes(&mut rig, &standby_server).await; + assert!( + incumbent.poll_requested_broadcast(&kio::Waiter::noop()).is_pending(), + "the front never asks the new publisher" + ); + } + #[tokio::test] async fn anonymous_routes_never_resume() { // An empty hop chain identifies nobody, so two of them must not pass for From f3577c941abf5d6f32434f295e5b12336811b53d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 16:59:07 -0700 Subject: [PATCH 077/128] fix(net): track tail hardening (#4533) Co-authored-by: Claude Opus 5.5 --- doc/concept/moq-lite.md | 15 +- js/net/src/ietf/subscriber.ts | 13 +- js/net/src/ietf/tail.test.ts | 14 ++ js/net/src/lite/subscriber.ts | 62 +++++- js/net/src/lite/tail.test.ts | 86 +++++++- js/net/src/tail.test.ts | 76 ++++++- js/net/src/tail.ts | 104 ++++++++-- quest/m1/README.md | 2 +- quest/m1/reader-end-parity.md | 32 +++ quest/m1/session-death.md | 1 - quest/m1/subscribe-drop.md | 4 +- quest/m1/track-tail-hardening.md | 79 -------- rs/moq-net/src/ietf/publisher.rs | 34 +++- rs/moq-net/src/ietf/subscriber.rs | 168 +++++++++++---- rs/moq-net/src/lite/subscriber.rs | 279 ++++++++++++++++++++++--- rs/moq-net/src/tail.rs | 325 ++++++++++++++++++++++++++---- rs/moq-net/tests/support/mock.rs | 34 +++- rs/moq-net/tests/track_tail.rs | 163 ++++++++++++++- 18 files changed, 1241 insertions(+), 250 deletions(-) create mode 100644 quest/m1/reader-end-parity.md delete mode 100644 quest/m1/track-tail-hardening.md diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 91e7ef342bd..d5c89265cbb 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -38,14 +38,21 @@ sides explicitly enable it. On moq-lite 07, `SUBSCRIBE_END` counts the group streams opened for the subscription. Rust and TypeScript stop waiting for missing streams once that -many headers have arrived; skipped group sequences add no wait. Groups already -being received continue until their own stream ends or resets. +many headers have arrived; skipped group sequences add no wait. A stream whose +header arrived is always read to its end before the subscription completes. A stream reset before its header arrived cannot be counted, so the subscriber still allows a grace period for late streams. The grace uses the subscription's nonzero effective maximum age, or one second when no maximum age is set. -moq-lite 05 and 06 instead account for group sequences using received headers -and `SUBSCRIBE_DROP`. +moq-lite 05 and 06 instead account for group sequences using received headers, +datagrams, and `SUBSCRIBE_DROP`, from the start group the subscription last +asked for. A lost datagram is not owed, but its hole waits out the grace like a +lost stream. + +From moq-lite 06, an end that contradicts the groups received aborts the track: +a group at or past `SUBSCRIBE_END`, or a `SUBSCRIBE_END` below a group already +received. moq-lite 05 specified an inclusive end, so there it only drops that +group or the early boundary. ## Discovery diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 9b9833d15ee..69dcdb0dce3 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -8,7 +8,7 @@ import { Cost, type Route, routesEqual, UNKNOWN_HOP } from "../hop.ts"; import { hiddenBelow, hooks, scopeCaptures, scopeHead, scopeOverlaps } from "../internal.ts"; import * as Path from "../path.ts"; import type { Cursor, Reader, Stream } from "../stream.ts"; -import { TAIL_GRACE_MS, Tail } from "../tail.ts"; +import { Tail } from "../tail.ts"; import { type Timescale, Timestamp } from "../time.ts"; import type * as track from "../track.ts"; import { TimeoutError, withTimeout } from "../util/timeout.ts"; @@ -52,6 +52,8 @@ type Subscription = { // The group streams received, so the subscription can wait for the ones PUBLISH_DONE // says are still owed. tail: Tail; + // The track's exclusive end, once an END_OF_TRACK declares it. + end?: number; }; // Out-parameter for #openSubscribe: lets the caller observe partial progress @@ -674,7 +676,7 @@ export class Subscriber { const { tail, track } = subscription; const complete = () => count > 0n && BigInt(tail.streams) >= count; - await tail.settle(complete, TAIL_GRACE_MS, track.closed); + await tail.settle(complete, track.closed); } /** @@ -1018,6 +1020,12 @@ export class Subscriber { let producer: netGroup.Producer | undefined; const open = () => { if (!producer) { + // The publisher contradicted its own end, which no later group can repair. + if (subscription.end !== undefined && group.groupId >= subscription.end) { + throw new ProtocolViolation( + `group ${group.groupId} is at or past the declared end ${subscription.end}`, + ); + } producer = new netGroup.Producer(group.groupId); track.writeGroup(producer); } @@ -1068,6 +1076,7 @@ export class Subscriber { } catch (err: unknown) { throw new ProtocolViolation(`invalid END_OF_TRACK: ${reason(error(err))}`); } + subscription.end ??= end; return; } if (frame.payload === undefined) break; diff --git a/js/net/src/ietf/tail.test.ts b/js/net/src/ietf/tail.test.ts index da233686e77..3f43b53dc92 100644 --- a/js/net/src/ietf/tail.test.ts +++ b/js/net/src/ietf/tail.test.ts @@ -178,6 +178,20 @@ test("END_OF_TRACK at object 0 ends the track before its group, which never exis expect(reader.final()).toBe(2); }); +test("a group at or past the END_OF_TRACK aborts the track", async () => { + const { subscriber, reader } = await subscribed(); + const end = groupStream(subscriber, 2); + end.write(END_OF_TRACK); + end.finish(); + expect(await reader.finished()).toBe(2); + + const late = groupStream(subscriber, 2); + late.write(object("2.0")); + late.finish(); + await late.handled; + expect(await reader.closed).toBeInstanceOf(ProtocolViolation); +}); + test("a bare FIN without PUBLISH_DONE aborts the track", async () => { const { reader, fin } = await subscribed(); await fin(); diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 61c3e7aaf25..ee919a230dc 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -82,6 +82,8 @@ interface SubscribeEntry { // The group streams received, so the subscription can wait for the ones still owed // after the publisher ends it. tail: Tail; + // The first group the SUBSCRIBE asked for, if any. + requested?: number; // The first group the publisher serves (SUBSCRIBE_START) and the track's exclusive end // (SUBSCRIBE_END), once it declares them. start?: number; @@ -587,7 +589,7 @@ export class Subscriber { const subscriptionUpdates = this.version === Version.DRAFT_01 || this.version === Version.DRAFT_02 ? undefined - : this.#runSubscriptionUpdates(id, broadcast, producer, msg, stream); + : this.#runSubscriptionUpdates(id, broadcast, entry, msg, stream); // Terminal conditions (stream end, track close, a failed subscription update) settle at most // once; race them into one stable promise so the demand loop doesn't re-subscribe each pass. @@ -652,7 +654,20 @@ export class Subscriber { } // Register before opening SUBSCRIBE so a racing GROUP stream finds the entry. - const entry: SubscribeEntry = { track: producer, timescale, tail: new Tail() }; + const entry: SubscribeEntry = { + track: producer, + timescale, + // The effective max age is the stopgap grace: the wrong clock (it bounds + // presentation-time drift), but it is how long the subscriber was willing to wait + // for a late group anyway. Already the smaller of the subscriber's and the track's. + tail: new Tail({ + grace: () => { + const maxAge = producer.subscription.peek()?.maxAge ?? Time.Milli.zero; + return maxAge > 0 ? maxAge : TAIL_GRACE_MS; + }, + }), + requested: msg.startGroup, + }; this.#subscribes.set(id, entry); state.stream = await Stream.open(this.#quic); @@ -872,6 +887,9 @@ export class Subscriber { if ("start" in resp) { entry.start = resp.start.group; + // The groups the SUBSCRIBE asked for below it are unavailable, whatever the + // demand asks later. + if (entry.requested !== undefined) entry.tail.account(entry.requested, entry.start); } else if ("end" in resp) { if (entry.end !== undefined) throw new ProtocolViolation("duplicate SUBSCRIBE_END"); entry.end = resp.end.group; @@ -881,7 +899,13 @@ export class Subscriber { try { entry.track.finishAt(entry.end); } catch (err) { - throw new ProtocolViolation(`invalid SUBSCRIBE_END: ${reason(error(err))}`); + // lite-05 specified an inclusive end, and @moq/net 0.1.3 to 0.1.9 sent one, so + // there an end below a received group only costs the early boundary: the FIN + // still finishes the track. Later drafts made it exclusive. + if (this.version !== Version.DRAFT_05) { + throw new ProtocolViolation(`invalid SUBSCRIBE_END: ${reason(error(err))}`); + } + console.warn(`invalid SUBSCRIBE_END: ${reason(error(err))}`); } } else if ("drop" in resp) { entry.tail.account(resp.drop.start, resp.drop.end + 1); @@ -897,9 +921,6 @@ export class Subscriber { // headers arrived keep reading until their own FIN or reset. #settleTail(entry: SubscribeEntry): Promise { const { tail, track } = entry; - // Already the smaller of the subscriber's and the track's max age. - const maxAge = track.subscription.peek()?.maxAge ?? Time.Milli.zero; - const grace = maxAge > 0 ? maxAge : TAIL_GRACE_MS; const complete = () => { if (entry.streams !== undefined) return tail.streams >= entry.streams; @@ -907,13 +928,17 @@ export class Subscriber { if (entry.end === undefined) return false; // Without SUBSCRIBE_START the publisher served no group at all. if (entry.start === undefined) return true; - const bounds = groupBounds(track.subscription.peek()?.groups ?? {}); - const start = Math.max(entry.start, bounds.start); + // Owed from the floor the demand last asked for, which an update can move either + // way, or where SUBSCRIBE_START resolved a live-edge one. The groups the SUBSCRIBE + // asked for below its SUBSCRIBE_START were accounted for when it arrived. + const groups = track.subscription.peek()?.groups; + const bounds = groupBounds(groups ?? {}); + const start = groups?.start === undefined ? entry.start : bounds.start; const end = bounds.end === undefined ? entry.end : Math.min(entry.end, bounds.end); return tail.covers(start, end); }; - return tail.settle(complete, grace, track.closed); + return tail.settle(complete, track.closed); } /** @@ -930,10 +955,11 @@ export class Subscriber { async #runSubscriptionUpdates( id: bigint, broadcast: Path.Valid, - track: track.Producer, + entry: SubscribeEntry, msg: Subscribe, stream: Stream, ): Promise { + const track = entry.track; const stopped: Promise = race([track.closed, stream.reader.closed]).then(() => null); let lastSent: track.Subscription = { priority: msg.priority, @@ -958,6 +984,12 @@ export class Subscriber { const bounds = groupBounds(current.groups); if (emptyRange({ startGroup: bounds.start, endGroup: bounds.end })) throw new Error(EMPTY_RANGE); + // A lowered floor owes groups nobody asked for until now. + if (current.groups?.start !== undefined) { + const floor = lastSent.groups?.start === undefined ? entry.start : groupBounds(lastSent.groups).start; + entry.tail.demand(bounds.start, floor ?? Number.POSITIVE_INFINITY); + } + // Round-trip the other Subscribe parameters so the publisher doesn't // interpret SUBSCRIBE_UPDATE as a reset of ordered/maxAge/etc. const update = new SubscribeUpdate({ @@ -1005,6 +1037,16 @@ export class Subscriber { const read = tail.open(group.sequence); try { + // The publisher contradicted its own end, which no later group can repair. lite-05 + // specified an inclusive end, so its last group lands on it: the write below drops + // only that group there. + if (entry.end !== undefined && group.sequence >= entry.end && this.version !== Version.DRAFT_05) { + const violation = new ProtocolViolation( + `group ${group.sequence} is at or past the declared end ${entry.end}`, + ); + track.close(violation); + throw violation; + } track.writeGroup(producer); // Block until the timescale is known; the group's stream can arrive before diff --git a/js/net/src/lite/tail.test.ts b/js/net/src/lite/tail.test.ts index 245791287da..87e0a9a474a 100644 --- a/js/net/src/lite/tail.test.ts +++ b/js/net/src/lite/tail.test.ts @@ -6,6 +6,7 @@ import { createMockTransportPair } from "../mock.ts"; import * as Path from "../path.ts"; import { Reader, Stream } from "../stream.ts"; import { Milli } from "../time.ts"; +import type { Groups } from "../track.ts"; import { Group as GroupMessage } from "./group.ts"; import { StreamId } from "./stream.ts"; import { @@ -51,10 +52,10 @@ function groupStream(subscriber: Subscriber, sequence: number) { * it answers TRACK_INFO, then writes whatever responses the test asks for on the subscribe * stream and FINs it when told. */ -async function subscribed(version: Version, maxAge = GRACE) { +async function subscribed(version: Version, maxAge = GRACE, groups?: Groups) { const pair = createMockTransportPair(ALPN_05); const subscriber = new Subscriber(pair.client, version, randomHop()); - const reader = subscriber.consume(Path.from("room")).track("video").subscribe({ maxAge }); + const reader = subscriber.consume(Path.from("room")).track("video").subscribe({ maxAge, groups }); const info = await Stream.accept(pair.server); if (!info) throw new Error("the subscriber never asked for TRACK_INFO"); @@ -210,16 +211,91 @@ describe.each([Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07])("%s", (ver expect(reader.final()).toBe(0); }); - test("a SUBSCRIBE_END below a group already received aborts the track", async () => { + // lite-05 specified an inclusive end, so there the group costs only its own stream. + test(`a group at or past SUBSCRIBE_END ${version === Version.DRAFT_05 ? "is dropped" : "aborts the track"}`, async () => { const { subscriber, reader, respond } = await subscribed(version); await respond({ start: new SubscribeStart(0) }); + await respond({ end: new SubscribeEnd(2, 2) }); + expect(await reader.finished()).toBe(2); + + await groupStream(subscriber, 2).handled; + if (version === Version.DRAFT_05) { + expect(await settlesWithin(Promise.resolve(reader.closed), 50)).toBe(false); + } else { + expect(await reader.closed).toBeInstanceOf(ProtocolViolation); + } + }); + + test("a floor below SUBSCRIBE_START owes nothing below it", async () => { + const { subscriber, reader, respond, fin } = await subscribed(version, Milli(60_000), { + start: { included: 1 }, + }); + await respond({ start: new SubscribeStart(3) }); + const group = groupStream(subscriber, 3); + group.finish(); + await group.handled; + await respond({ end: new SubscribeEnd(4, 1) }); + await fin(); + + expect((await reader.recvGroup())?.sequence).toBe(3); + expect(await settlesWithin(reader.recvGroup(), 1000)).toBe(true); + expect(await reader.closed).toBeNull(); + }); + + test.skipIf(version === Version.DRAFT_07)("a lowered floor owes the groups it newly asked for", async () => { + const maxAge = Milli(60_000); + const { subscriber, respond, fin } = await subscribed(version, maxAge, { start: { included: 3 } }); + await respond({ start: new SubscribeStart(3) }); + const group = groupStream(subscriber, 3); + group.write("3.0"); + group.finish(); + await group.handled; + + // A second reader lowers the floor, which the subscription forwards as an update. + const lower = subscriber + .consume(Path.from("room")) + .track("video") + .subscribe({ maxAge, groups: { start: { included: 1 } } }); + await respond({ end: new SubscribeEnd(4, 1) }); + await fin(); + // Long enough for a subscription that owed nothing more to have ended. + await new Promise((resolve) => setTimeout(resolve, 50)); + + // QUIC does not order streams, so the lowered groups land after the FIN. + for (const sequence of [1, 2]) { + const late = groupStream(subscriber, sequence); + late.write(`${sequence}.0`); + late.finish(); + await late.handled; + } + + const received: number[] = []; + for (;;) { + const next = await lower.recvGroup(); + if (!next) break; + received.push(next.sequence); + } + expect(received).toContain(1); + expect(received).toContain(2); + expect(await lower.closed).toBeNull(); + }); + + // lite-05 specified an inclusive end, and @moq/net 0.1.3 to 0.1.9 sent one, so there an end + // below a received group only costs the early boundary. + test(`a SUBSCRIBE_END below a group already received ${version === Version.DRAFT_05 ? "finishes clean" : "aborts the track"}`, async () => { + const { subscriber, reader, respond, fin } = await subscribed(version); + await respond({ start: new SubscribeStart(0) }); const group = groupStream(subscriber, 3); group.finish(); await group.handled; await respond({ end: new SubscribeEnd(2, 2) }); - const closed = await reader.closed; - expect(closed).toBeInstanceOf(Error); + if (version === Version.DRAFT_05) { + await fin(); + expect(await reader.closed).toBeNull(); + } else { + expect(await reader.closed).toBeInstanceOf(ProtocolViolation); + } }); }); diff --git a/js/net/src/tail.test.ts b/js/net/src/tail.test.ts index 9daa4eaa56e..62c4ebfe941 100644 --- a/js/net/src/tail.test.ts +++ b/js/net/src/tail.test.ts @@ -1,11 +1,12 @@ -import { expect, test } from "bun:test"; +import { describe, expect, test } from "bun:test"; +import { Once } from "@moq/signals"; import { accept, connect } from "./connection/index.ts"; import * as Ietf from "./ietf/index.ts"; import * as Lite from "./lite/index.ts"; import { createMockTransportPair } from "./mock.ts"; import { Producer as OriginProducer } from "./origin.ts"; import * as Path from "./path.ts"; -import { TAIL_GRACE_MS } from "./tail.ts"; +import { TAIL_GRACE_MS, Tail } from "./tail.ts"; import { Milli } from "./time.ts"; import type { Ordered } from "./track.ts"; import { wireOf } from "./wire.ts"; @@ -103,3 +104,74 @@ test.each([Ietf.ALPN.DRAFT_16, Ietf.ALPN.DRAFT_17, Ietf.ALPN.DRAFT_20])( } }, ); + +describe("Tail", () => { + const GRACE = Milli(1000); + + function tail() { + const clock = { now: 0 }; + return { clock, tail: new Tail({ grace: () => GRACE, now: () => clock.now }) }; + } + + test("a gap older than the grace folds away", () => { + const { clock, tail: t } = tail(); + t.account(0, 1); + t.account(2, 3); + clock.now = GRACE / 2; + t.account(4, 5); + expect(t.covers(0, 3)).toBe(false); + + // Splitting the younger gap keeps it as late as it was. + t.account(6, 7); + clock.now = GRACE; + t.account(8, 9); + expect(t.covers(0, 3)).toBe(true); + expect(t.covers(0, 5)).toBe(false); + }); + + test("splitting a gap leaves both halves with its age", () => { + const { clock, tail: t } = tail(); + t.account(0, 1); + t.account(9, 10); + clock.now = GRACE / 2; + t.account(5, 6); + expect(t.covers(0, 10)).toBe(false); + + clock.now = GRACE; + t.account(9, 10); + expect(t.covers(0, 10)).toBe(true); + }); + + test("a lowered floor restarts the gap age", () => { + const { clock, tail: t } = tail(); + t.account(3, 4); + t.account(9, 10); + + clock.now = GRACE * 2; + t.demand(1, 3); + t.account(1, 2); + expect(t.covers(1, 4)).toBe(false); + // Only the gap the floor reached restarts. + expect(t.covers(3, 10)).toBe(true); + + clock.now = GRACE * 3; + t.account(9, 10); + expect(t.covers(1, 10)).toBe(true); + }); + + test("the grace waits for a stream being read", async () => { + const t = new Tail({ grace: () => Milli(10) }); + const read = t.open(0); + let settled = false; + const settling = t + .settle(() => false, new Once()) + .then(() => { + settled = true; + }); + + await new Promise((resolve) => setTimeout(resolve, 50)); + expect(settled).toBe(false); + read(); + await settling; + }); +}); diff --git a/js/net/src/tail.ts b/js/net/src/tail.ts index e516f1ea089..b732ae11338 100644 --- a/js/net/src/tail.ts +++ b/js/net/src/tail.ts @@ -14,6 +14,18 @@ export const TAIL_GRACE_MS = Milli(1000); // setTimeout truncates a longer delay to a signed 32-bit int and fires at once. const MAX_TIMEOUT_MS = 2 ** 31 - 1; +// A run of accounted sequences `[start, end)`, and when the gap below it opened (in +// `performance.now()` milliseconds), which is when its missing groups became late. +type Run = { start: number; end: number; since: number }; + +/** How a {@link Tail} measures its grace. */ +export interface TailOptions { + /** How long to wait for a group that cannot be accounted for. Read each time it is needed. */ + grace?: () => Milli; + /** The clock, in `performance.now()` milliseconds. */ + now?: () => number; +} + /** * The group streams a subscription has received, so its end can wait for the ones still owed. * @@ -22,16 +34,28 @@ const MAX_TIMEOUT_MS = 2 ** 31 - 1; * the publisher dropped them) and how many streams are still being read, and {@link settle} * waits on them. * + * A lost datagram is not owed: it leaves a hole that waits out the grace like a stream reset + * before its header. + * * @internal */ export class Tail { - // Disjoint, sorted, exclusive-end ranges of accounted sequences. A gap splits a range, so - // this stays as small as the number of gaps rather than the number of groups. - #accounted: [number, number][] = []; + // Disjoint, sorted, non-adjacent runs of accounted sequences. A gap older than the grace + // can no longer be waited for, so it folds into the runs around it, which bounds this by + // the gaps opened within the grace rather than every gap in the subscription. A fold is + // final: a later, longer grace or a lowered floor cannot reopen it. + #runs: Run[] = []; // Group streams whose header arrived, and those still being read. #streams = 0; #active = 0; #changed = new Signal(0); + #grace: () => Milli; + #now: () => number; + + constructor(options: TailOptions = {}) { + this.#grace = options.grace ?? (() => TAIL_GRACE_MS); + this.#now = options.now ?? (() => performance.now()); + } /** Group streams whose header arrived, whether they finished or were reset. */ get streams(): number { @@ -61,29 +85,44 @@ export class Tail { this.#account(start, end); } + /** Restart the age of every gap reaching into `[start, end)`, which the demand newly asks for. */ + demand(start: number, end: number): void { + if (start >= end) return; + const now = this.#now(); + let below = 0; + this.#runs = this.#runs.map((run) => { + const reached = below < end && start < run.start; + below = run.end; + return reached ? { ...run, since: now } : run; + }); + } + /** Whether every sequence in `[start, end)` is accounted for. */ covers(start: number, end: number): boolean { if (start >= end) return true; - // Ranges are merged on insert, so one range covers the span or none does. - return this.#accounted.some(([lo, hi]) => lo <= start && end <= hi); + // Runs are merged on insert, so one run covers the span or none does. + return this.#runs.some((run) => run.start <= start && end <= run.end); } /** - * Wait until every stream is read to its end and `complete()` holds, or `grace` - * milliseconds pass with nothing left being read, or `closed` settles. + * Wait until every stream is read to its end and `complete()` holds, or the grace passes + * with nothing left being read, or `closed` settles. * * A stream still being read is always waited for: a group ends on its own stream's FIN * or reset, never because its track ended. The grace only gives up on streams that never * arrived. */ - async settle(complete: () => boolean, grace: Milli, closed: GetPromise): Promise { + async settle(complete: () => boolean, closed: GetPromise): Promise { + // A gap that aged past the grace since the last insert is no longer waited for either. + this.#expire(this.#now()); + let expired = false; const timer = setTimeout( () => { expired = true; this.#bump(); }, - Math.min(grace, MAX_TIMEOUT_MS), + Math.min(this.#grace(), MAX_TIMEOUT_MS), ); try { while (closed.peek() === undefined) { @@ -98,27 +137,48 @@ export class Tail { #account(start: number, end: number): void { if (start >= end) return; - const merged: [number, number][] = []; - let lo = start; - let hi = end; + const now = this.#now(); + const runs: Run[] = []; + let merged: Run | undefined; let placed = false; - for (const range of this.#accounted) { - if (range[1] < lo) { - merged.push(range); - } else if (hi < range[0]) { - if (!placed) merged.push([lo, hi]); + for (const run of this.#runs) { + if (run.end < start) { + runs.push(run); + } else if (end < run.start) { + // Splitting a gap leaves both halves as late as it was. + if (!placed) runs.push(merged ?? { start, end, since: run.since }); placed = true; - merged.push(range); + runs.push(run); } else { - lo = Math.min(lo, range[0]); - hi = Math.max(hi, range[1]); + merged = { + start: Math.min(merged?.start ?? start, run.start), + end: Math.max(merged?.end ?? end, run.end), + since: merged?.since ?? run.since, + }; } } - if (!placed) merged.push([lo, hi]); - this.#accounted = merged; + // A run past every other one opens a new gap. + if (!placed) runs.push(merged ?? { start, end, since: now }); + this.#runs = runs; + this.#expire(now); this.#bump(); } + // Fold every gap older than the grace into the runs around it. + #expire(now: number): void { + const grace = this.#grace(); + const runs: Run[] = []; + for (const run of this.#runs) { + const below = runs.at(-1); + if (below && now - run.since >= grace) { + runs[runs.length - 1] = { ...below, end: run.end }; + } else { + runs.push(run); + } + } + this.#runs = runs; + } + #bump(): void { this.#changed.update((revision) => revision + 1); } diff --git a/quest/m1/README.md b/quest/m1/README.md index d1f265a2994..36c5acd76ef 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -30,8 +30,8 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Watch refusal](/quest/m1/watch-refusal.md) - `` shows an origin refusal as an error instead of sitting offline - [Splice edge cases](/quest/m1/splice-edges.md) - an unstamped successor, a pruned segment's boundary group, and a warm head during a takeover are each handled correctly - [Resumed groups](/quest/m1/resume-latest.md) - a half-delivered group ends once the new copy is past it, so a group-only reader never parks after a mid-group failover -- [Track tail hardening](/quest/m1/track-tail-hardening.md) - Rust and JS wait out a track's tail by the same rules, with the known hang, count, truncation, grace, and memory holes closed - [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 +- [Reader end parity](/quest/m1/reader-end-parity.md) - JS readers see a track's end once the newest group reaches the declared end, as Rust readers do - [Cross-relay bursts](/quest/m1/cross-relay-bursts.md) - bursty small-group tracks cross two relays without lost groups, unanswered FETCHes, or stalls - [Request stream cancel](/quest/m1/request-stream-serve.md) - a lite publisher stops resolving a SUBSCRIBE or FETCH once the requester FINs or resets, through one wrapper that owns every request stream's reader - [JS closed-track leak](/quest/m1/js-closed-track-leak.md) - on dev, a subscriber that joins a closed JS track with unlimited retention is released instead of cached forever diff --git a/quest/m1/reader-end-parity.md b/quest/m1/reader-end-parity.md new file mode 100644 index 00000000000..dbceda77167 --- /dev/null +++ b/quest/m1/reader-end-parity.md @@ -0,0 +1,32 @@ +# [S] Readers see a track's end at the same moment in Rust and JS + +## Goal + +A track reader in `@moq/net` sees the end as soon as the newest group reaches +the declared end, as Rust readers already do, instead of waiting for the track +to close after the tail settles. The same subscription ends for a reader at +the same point in both languages. + +## Plan + +Found in [#4533](https://github.com/moq-dev/moq/pull/4533): the tails agree +on when a subscription settles, but the reader-facing end differs. The Rust +track model ends for readers once the newest group reaches the declared end, +so a hole waiting out the grace never delays a reader. JS readers wait for the +track to close, grace included. + +Decided with the maintainer: adopt Rust's behavior in JS. A reader isn't held +for the grace over groups it would skip anyway; the tail still settles +separately for accounting. Keep a clean end that has not settled distinct from +an abort, as #4120 and #4116 require. + +Tests: the same scenario in both languages (a declared end with a missing +group in the grace window) reports the end to readers without waiting out the +grace. Consider asserting it across languages in [Track tail +interop](/quest/m1/track-tail-interop.md). + +Public API: none expected; a JS behavior change. Wire: none. + +## Related + +- [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - names every missing group, so fewer holes reach the grace at all diff --git a/quest/m1/session-death.md b/quest/m1/session-death.md index 0eec5aa84ae..af67ddd7151 100644 --- a/quest/m1/session-death.md +++ b/quest/m1/session-death.md @@ -43,5 +43,4 @@ clean end needs a public method. ## Related -- [Track tail hardening](/quest/m1/track-tail-hardening.md) - the tail rules this must not mask - [Graceful session close](/quest/m1/session-close.md) - what a local close sends the peer diff --git a/quest/m1/subscribe-drop.md b/quest/m1/subscribe-drop.md index 3f93210d63d..ecd671811c5 100644 --- a/quest/m1/subscribe-drop.md +++ b/quest/m1/subscribe-drop.md @@ -34,6 +34,9 @@ Decided: grace, as today. - A resumed group ([Resumed groups](/quest/m1/resume-latest.md)) that is the new copy's latest ends with the DROP's error when the copy drops it. +- A dropped or aborted group is visible to readers, not silently skipped. + #4533 found the Rust model releases an aborted group's sequence and skips it, + so a truncated first object is indistinguishable from a group never sent. Update `drafts/draft-lcurley-moq-lite.md` (SUBSCRIBE_DROP, SUBSCRIBE_END, the lite-07 changelog), `doc/concept/moq-lite.md`, and the Rust and JS lite @@ -46,5 +49,4 @@ without waiting out the grace. ## Related -- [Track tail hardening](/quest/m1/track-tail-hardening.md) - the same tail accounting, in both languages - [Track tail interop](/quest/m1/track-tail-interop.md) - the Rust-JS proof of the lite-07 drop case diff --git a/quest/m1/track-tail-hardening.md b/quest/m1/track-tail-hardening.md deleted file mode 100644 index 74d412bd042..00000000000 --- a/quest/m1/track-tail-hardening.md +++ /dev/null @@ -1,79 +0,0 @@ -# [M] Track tail hardening - -## Goal - -moq-net and `@moq/net` wait out a subscription's tail by the same rules, and -the known holes in those rules are closed. A finished IETF subscription never -hangs its request task or under-reports its stream count, a group whose -header arrived is never silently dropped from a clean end, the grace never -cuts off a stream still being read, and tail bookkeeping stays bounded on a -lossy track. - -## Plan - -Track tail landed in https://github.com/moq-dev/moq/pull/4086 (JS) and -https://github.com/moq-dev/moq/pull/4116 (Rust), and Codex's findings on both -were left for this pass. Fix each in the language named and check whether -the other has the same hole. - -Bugs: - -- **Rust IETF publisher, END_OF_TRACK not cancellable.** After the group - streams drain, `write_end_of_track` in `rs/moq-net/src/ietf/publisher.rs` - runs outside the race against `stream.reader.poll_closed` and the session, - so with uni-stream credit exhausted an unsubscribe leaves the request task - parked forever, never sending PUBLISH_DONE. -- **Rust IETF publisher, stream count.** END_OF_TRACK is counted only if the - whole write succeeds, while every other stream counts once opened. A reset - END_OF_TRACK whose header still arrives can then land after the subscriber - met the count and retired the alias. -- **Rust IETF subscriber, truncated first object.** `open_group` peeks the - first object with `?` before creating the group, so a stream reset or - truncated after its header drops that group, and since the stream still - counts, the track can end clean without it. Keep the END_OF_TRACK peek, but - create and abort the named group on any other peek failure. -- **Rust grace cuts off an arrived stream.** `Settle::poll` in - `rs/moq-net/src/tail.rs` returns when the grace fires even if an - END_OF_TRACK stream is mid-read, so the track finishes at the live edge and - the later marker is ignored. JS's `Tail.settle` already waits for active - streams; do the same. -- **JS lite floor.** `Math.max(entry.start, bounds.start)` in - `js/net/src/lite/subscriber.ts` ignores a SUBSCRIBE_UPDATE that lowered the - floor after SUBSCRIBE_START, so a newly requested lower group reordered - behind the FIN is dropped. `bounds.start` alone is wrong too: a subscriber - that asked below the announced start would wait for groups never promised. - The owed start has to remember the floor each request was answered at. - Check whether Rust's `SubStream::owed` has the same shape. - -Open questions. The maintainer chose to plan these without settling them; -decide in the PR, applying the choice to both languages: - -- **Are lost datagrams owed before a track ends?** Both `Tail`s account a - datagram only when it arrives, so a lost one leaves a hole in the owed span - and the end waits out the whole grace (JS was reported to wait and Rust - not, but Rust's `covers(owed)` reads the same way despite the comment in - `route_datagram`; confirm with a test first). Recommendation: no, datagrams - are best effort. [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) decided - the same: datagram groups are not owed, so an uncovered hole waits out the - grace on every version. -- **Does a group at or past the declared end abort the track, or only that - group?** Rust aborts the track with `ProtocolViolation`; JS aborts the group - and ends clean. Recommendation: abort the track in both. The peer - contradicted its own end, and the repo fails loud on malformed input. -- **How is tail memory bounded?** Rust `Tail.accounted` gains a range per - permanent gap for the life of the subscription, and so does JS's. A gap - older than the grace can no longer be waited for, so folding it in as - accounted loses nothing. Recommendation: that, which bounds the ranges by - the gaps inside the grace window. Once publishers send SUBSCRIBE_DROP for - every gap, only datagram holes remain. - -Regression tests go in `rs/moq-net/tests/track_tail.rs` (its `hold_unis` -mock makes the reorder deterministic) and the JS tail tests. Wire output only -changes if the stream-count fix does, and that is a correction to what the -drafts already require. - -## Related - -- [Track tail interop](/quest/m1/track-tail-interop.md) - the Rust-JS check that both sides now agree -- [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - every group is a stream or a drop, replacing lite-07's stream count -- [Session death](/quest/m1/session-death.md) - how a tail ends when the session dies under it diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 775283b2cba..780e9966cd7 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -620,26 +620,40 @@ where .await }; - // Every data stream this subscription opened is closed by now, which PUBLISH_DONE - // requires, so the count it reports is final. let completed = served.is_some(); let (res, filled) = served.unwrap_or((Ok(()), false)); - let mut streams = track_serve.opened() + u64::from(filled); // Draft-14 on carries no end location in PUBLISH_DONE: an END_OF_TRACK object is // what tells the subscriber where the track ended. A cancelled subscription is - // owed nothing more. + // owed nothing more, and one cancelled while the marker waits for stream credit + // abandons it. if completed && res.is_ok() && let Some(end) = track_serve.end() { - match track_serve.write_end_of_track(end, priority).await { - Ok(()) => streams += 1, - // A failure only costs the subscriber the early boundary. - Err(err) => tracing::debug!(%err, id = %request_id, "end of track failed"), + let mut marker = std::pin::pin!(track_serve.write_end_of_track(end, priority)); + let mut closed_session = self.session.clone(); + let written = kio::wait(|waiter| { + if let Poll::Ready(res) = waiter.poll_future(marker.as_mut()) { + return Poll::Ready(res); + } + let mut cx = std::task::Context::from_waker(waiter.waker()); + if stream.reader.poll_closed(&mut cx).is_ready() || closed_session.poll_closed(&mut cx).is_ready() { + return Poll::Ready(Err(Error::Cancel)); + } + Poll::Pending + }) + .await; + // A failure only costs the subscriber the early boundary. + if let Err(err) = written { + tracing::debug!(%err, id = %request_id, "end of track failed"); } } + // Every data stream this subscription opened is closed by now, which PUBLISH_DONE + // requires, so the count it reports is final. + let streams = track_serve.opened() + u64::from(filled); + // Send PublishDone let (status, reason) = match &res { Ok(()) => (ietf::PublishDoneStatus::TrackEnded, "track ended"), @@ -2015,11 +2029,13 @@ impl TrackServe { /// the group that will never exist. /// /// The last group's stream has usually finished before the track ends, so the marker - /// cannot ride on it. The stream counts toward PUBLISH_DONE once it is open. + /// cannot ride on it. Like a group stream, it counts toward PUBLISH_DONE once open, + /// since a reset can still deliver its header. async fn write_end_of_track(&mut self, end: u64, priority: u8) -> Result<(), Error> { let mut stream = std::future::poll_fn(|cx| self.session.poll_open_uni(cx)) .await .map_err(Error::from_transport)?; + self.opened.fetch_add(1, Ordering::Relaxed); stream.set_priority(priority); let mut writer = Writer::new(stream, self.version); diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 000610327d2..5871f5bec56 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -15,7 +15,7 @@ use crate::{ }; use super::{Message, Version, cluster, error::request, peer}; -use crate::tail::{self, Settle, Tail}; +use crate::tail::{Reading, Settle, Tail}; use kio::Lock; @@ -374,20 +374,6 @@ impl TrackState { } } -/// Counts a data stream toward its subscription's [`Tail`] once its handler is done with it. -/// -/// Counting at the end rather than at the header means a Stream Count that is reached never -/// races the stream's own work, such as the END_OF_TRACK that declares where the track ends. -struct Counted(kio::Producer); - -impl Drop for Counted { - fn drop(&mut self) { - if let Ok(mut tail) = self.0.write() { - tail.stream(); - } - } -} - struct BroadcastState { // The route announced into our origin for this namespace, post-charge. route: crate::origin::Route, @@ -1840,18 +1826,18 @@ where tracing::info!(broadcast = %self.origin.absolute(&broadcast_path), track = %track_name, "subscribe complete"); // The publisher sends PUBLISH_DONE once every data stream it opened // is closed, but QUIC does not order them, so some can still be on - // their way. Wait until Stream Count of them are read, or a bounded - // grace for any reset before its header (the draft says to use a - // timeout). The count is a hint: a published peer sends 0, which - // waits out the grace. - let tail = self + // their way. Wait until Stream Count of their headers arrived and + // each is read to its end, or a bounded grace for any reset before + // its header (the draft says to use a timeout). The count is a hint: + // a published peer sends 0, which waits out the grace. + let held = self .state .lock() .subscribes .get(&request_id) - .map(|held| held.tail.consume()); - if let Some(tail) = tail { - let mut settle = Settle::new(&self.runtime, tail, tail::GRACE); + .map(|held| (held.tail.consume(), held.fill.clone())); + if let Some((tail, fill)) = held { + let mut settle = Settle::new(&self.runtime, tail); kio::wait(|waiter| { if !fetch_done && let Some(fut) = fetching.as_mut() @@ -1859,7 +1845,7 @@ where { fetch_done = true; } - settle.poll(waiter, |tail| count > 0 && tail.streams() >= count) + poll_settled(&mut settle, waiter, &fill, count) }) .await; } @@ -2179,7 +2165,7 @@ where } }; - let (mut track, timescale, fill, _counted) = { + let (mut track, timescale, fill, mut reading) = { let state = self.state.lock(); let track = state.subscribes.get(&request_id).ok_or(Error::NotFound)?; ( @@ -2187,8 +2173,8 @@ where track.timescale, track.fill.clone(), // Every data stream counts toward PUBLISH_DONE's Stream Count, even one - // dropped below. - Counted(track.tail.clone()), + // dropped below, and the subscription's end waits until it is read. + Reading::open(&track.tail, Some(group.group_id), self.runtime.now()), ) }; @@ -2225,14 +2211,25 @@ where // Otherwise dropping the local subscriber cannot end this handler. let opened = { let mut opening = track.clone(); - let mut open = std::pin::pin!(self.open_group(stream, &mut opening, &fill, &group)); + let mut open = std::pin::pin!(self.open_group(stream, &mut opening, &fill, &group, &mut reading)); kio::wait(|waiter| { if let Poll::Ready(err) = track.poll_closed(waiter) { return Poll::Ready(Err(err)); } waiter.poll_future(open.as_mut()) }) - .await? + .await + }; + let opened = match opened { + // The group is at or past the end the publisher declared, which no later stream + // can repair. + Err(Error::Closed) => { + tracing::warn!(group = group.group_id, "group past the declared end of track"); + let _ = track.abort(Error::ProtocolViolation); + return Err(Error::ProtocolViolation); + } + Err(err) => return Err(err), + Ok(opened) => opened, }; let (producer, start) = match opened { Opened::Group(producer, start) => (producer, start), @@ -2388,15 +2385,34 @@ where track: &mut track::Producer, fill: &kio::Producer, header: &ietf::GroupHeader, + reading: &mut Reading, ) -> Result { let sequence = header.group_id; // Stats (groups/frames/bytes) are counted in the model as the group is written, // through the tagged `track::Producer`. let create = |track: &mut track::Producer| track.create_group(group::Info { sequence }); - let first = match header.flags.has_extensions { - true => stream.decode_peek_maybe::>().await?.map(|peek| peek.0), - false => stream.decode_peek_maybe::>().await?.map(|peek| peek.0), + let peeked = match header.flags.has_extensions { + true => stream + .decode_peek_maybe::>() + .await + .map(|peek| peek.map(|peek| peek.0)), + false => stream + .decode_peek_maybe::>() + .await + .map(|peek| peek.map(|peek| peek.0)), + }; + let first = match peeked { + Ok(first) => first, + // The header arrived, so the stream counts toward the track's end. Abort the + // group it named rather than let the track end clean without it. A fill that + // already holds the group reports it through its own producer. + Err(err) => { + if let Ok(group) = create(track) { + let _ = group.abort(err.clone()); + } + return Err(err); + } }; if first.is_some_and(|first| first.id == 0 && first.end_of_track) { return Ok(Opened::EndOfTrack); @@ -2427,7 +2443,7 @@ where // A group starting partway through is the tail of one the fill began, and // without that head it has a hole at the front. - Some(start) => match self.claim_fill(fill, track, sequence, Some(start)).await? { + Some(start) => match self.claim_fill(fill, track, sequence, Some(start), reading).await? { Some(producer) => Ok(Opened::Group(producer, start)), None => { tracing::warn!(sequence, start, "no fill to stitch a mid-group stream onto"); @@ -2437,7 +2453,7 @@ where // A stream that ends without an object: the group is over and had nothing // outside the fill's range, so the head it delivered is the whole group. - None => match self.claim_fill(fill, track, sequence, None).await? { + None => match self.claim_fill(fill, track, sequence, None, reading).await? { Some(producer) => Ok(Opened::Group(producer, 0)), None => Ok(Opened::Group(create(track)?, 0)), }, @@ -2454,15 +2470,19 @@ where /// /// Waiting is what keeps the two streams from interleaving into one producer. It ends /// with the subscription, so a publisher that promises a fill and never delivers one - /// costs this stream and nothing else. + /// costs this stream and nothing else. Meanwhile this stream stops holding the + /// subscription's end open: the fill's own stream holds it if its header arrived, and + /// the grace gives up on it if not. async fn claim_fill( &self, fill: &kio::Producer, track: &track::Producer, sequence: u64, start: Option, + reading: &mut Reading, ) -> Result, Error> { - kio::wait(|waiter| { + reading.park(); + let settled = kio::wait(|waiter| { if let Poll::Ready(err) = track.poll_closed(waiter) { return Poll::Ready(Err(err)); } @@ -2473,13 +2493,18 @@ where }); match settled { - Poll::Ready(Ok(mut fill)) => Poll::Ready(fill.claim(sequence, start)), + Poll::Ready(Ok(_)) => Poll::Ready(Ok(())), // The subscription went away underneath us. Poll::Ready(Err(_)) => Poll::Ready(Err(Error::Dropped)), Poll::Pending => Poll::Pending, } }) - .await + .await; + // Hold the end open again before taking the head: once the fill is claimed, this + // stream is the only thing saying the group is still being read. + reading.resume(); + settled?; + fill.write().map_err(|_| Error::Dropped)?.claim(sequence, start) } } @@ -2561,7 +2586,9 @@ where let track = state.subscribes.get(&subscribe_id).ok_or(Error::NotFound)?; // A fill is one of the subscription's own data streams, so PUBLISH_DONE counts // it. A joining FETCH is a request of its own. - let counted = joined.is_none().then(|| Counted(track.tail.clone())); + let counted = joined + .is_none() + .then(|| Reading::open(&track.tail, None, self.runtime.now())); (subscribe_id, track.fill.clone(), track.joining, track.largest, counted) }; @@ -2919,6 +2946,15 @@ fn advance_fill_group( open_fill_group(track, head, sequence) } +/// Ready once a finished subscription's data streams are accounted for: Stream Count of +/// their headers, and no fill outstanding. A tail parked on its head holds nothing open +/// itself, so the fill does until the head is claimed. +fn poll_settled(settle: &mut Settle, waiter: &kio::Waiter, fill: &kio::Producer, count: u64) -> Poll<()> { + // Read before the tail: Done is terminal, so the answer cannot go stale. + let filled = !fill.read().outstanding(); + settle.poll(waiter, |tail| filled && count > 0 && tail.streams() >= count) +} + /// A refused or missing joining FETCH continues the subscription live: drop the outstanding /// fill so a mid-group tail is not left waiting on a head that is never coming. fn settle_join_live(fill: &kio::Producer) { @@ -6022,6 +6058,42 @@ mod stitch_tests { assert!(matches!(*h.fill.read(), Fill::Done), "the head was claimed"); } + /// A tail parked on its head stops holding the end open, so the finished fill does until + /// the head is claimed: otherwise the subscription looks settled between the fill + /// finishing and the tail waking, and ends before the tail is read. + #[tokio::test] + async fn an_unclaimed_fill_holds_the_end_open() { + let h = Harness::new( + Fill::Serving(Some(Timescale::MICRO)), + vec![ + fill_stream(SEQUENCE, &[b"head-0", b"head-1"]), + tail_stream(SEQUENCE, 2, &[b"tail-2"]), + ], + ); + let mut fill = h.stream().await; + let mut tail = h.stream().await; + + let mut serve_tail = h.subscriber.clone(); + let mut tailing = std::pin::pin!(serve_tail.recv_group(&mut tail)); + assert!( + futures::poll!(tailing.as_mut()).is_pending(), + "the tail waits for its head" + ); + h.subscriber.clone().recv_fill(&mut fill).await.expect("fill"); + + let state = h.subscriber.state.lock().subscribes[&REQUEST].tail.consume(); + let count = state.read().streams(); + let mut settle = Settle::new(&crate::time::Clock::tokio(), state); + let mut settled = std::pin::pin!(kio::wait(|waiter| poll_settled(&mut settle, waiter, &h.fill, count))); + assert!( + futures::poll!(settled.as_mut()).is_pending(), + "the head is still owed to the tail" + ); + + tailing.await.expect("tail"); + settled.await; + } + #[tokio::test] async fn object_extension_limit() { for size in [65536usize, 65537] { @@ -6102,6 +6174,24 @@ mod stitch_tests { assert!(consumer.recv_group().await.unwrap().is_none(), "then the track ends"); } + /// A group at or past the end an END_OF_TRACK declared contradicts that end, which no + /// later stream can repair, so the whole track fails rather than ending clean without it. + #[tokio::test] + async fn a_group_past_the_declared_end_aborts_the_track() { + use futures::FutureExt; + + let mut h = Harness::new(Fill::Done, vec![tail_stream(SEQUENCE, 0, &[b"late"])]); + h.track.finish_at(SEQUENCE).unwrap(); + let mut stream = h.stream().await; + + let res = h.subscriber.clone().recv_group(&mut stream).await; + assert!(matches!(res, Err(Error::ProtocolViolation)), "{res:?}"); + assert!(matches!( + h.track.closed().now_or_never(), + Some(Error::ProtocolViolation) + )); + } + /// END_OF_TRACK at object 0 says the group does not exist, so the track ends before it /// and no group is created for it. #[tokio::test] diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index a648b2f2c84..0fbc2097fc8 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -15,7 +15,7 @@ use crate::{ }; use super::Version; -use crate::tail::{self, Settle, Tail}; +use crate::tail::{self, Reading, Settle, Tail}; use kio::Lock; @@ -456,7 +456,7 @@ impl Subscriber { // A datagram is never owed a stream, so it never holds the subscription's end open. if let Ok(mut tail) = entry.tail.write() { - tail.account(dg.sequence..dg.sequence.saturating_add(1)); + tail.account(dg.sequence..dg.sequence.saturating_add(1), self.runtime.now()); } entry.producer.insert_datagram(dg.sequence, timestamp, dg.payload)?; Ok(()) @@ -740,6 +740,7 @@ enum GroupRecvState { group: crate::recv::Group, track: track::Producer, ingest: FrameIngest, + _reading: Reading, }, Done, } @@ -760,22 +761,40 @@ impl GroupRecv { let mut cx = std::task::Context::from_waker(waiter.waker()); let hdr = ready!(self.reader.poll_decode::(&mut cx))?; - let (group, track, timescale) = { + let (group, track, timescale, reading) = { let mut subs = self.subscriber.subscribes.lock(); let entry = subs.get_mut(&hdr.subscribe).ok_or(Error::Cancel)?; - if let Ok(mut tail) = entry.tail.write() { - tail.open(hdr.sequence); - } + // The subscription's end waits until this stream is read. + let reading = Reading::open(&entry.tail, Some(hdr.sequence), self.subscriber.runtime.now()); let group_info = group::Info { sequence: hdr.sequence }; // Stats (groups/frames/bytes) are counted in the model as the group // is written, through the tagged `track::Producer`. - let mut group = entry.producer.create_group(group_info)?; + let mut group = match entry.producer.create_group(group_info) { + Ok(group) => group, + // The group is at or past the end the publisher declared, which no + // later stream can repair. Before lite-05 only a local finish sets + // an end, and lite-05 specified an inclusive one, so its last + // group lands on it: drop only that stream there. + Err(Error::Closed) + if !matches!( + self.subscriber.version, + Version::Lite01 + | Version::Lite02 | Version::Lite03 + | Version::Lite04 | Version::Lite05 + ) => + { + tracing::warn!(group = hdr.sequence, "group past the declared end of track"); + let _ = entry.producer.clone().abort(Error::ProtocolViolation); + return Poll::Ready(Err(Error::ProtocolViolation)); + } + Err(err) => return Poll::Ready(Err(err)), + }; // The stream may carry only the tail of the group; number the frames // from where the publisher said they start so a reader splicing // across routes lines them up. group.start_at(hdr.frame_start)?; - (group, entry.producer.clone(), entry.timescale) + (group, entry.producer.clone(), entry.timescale, reading) }; // The timescale came from TRACK_INFO (read before this subscription was @@ -785,9 +804,12 @@ impl GroupRecv { group: crate::recv::Group::new(group), track, ingest: FrameIngest::new(self.subscriber.runtime.clone(), timescale), + _reading: reading, }; } - GroupRecvState::Serve { group, track, ingest } => { + GroupRecvState::Serve { + group, track, ingest, .. + } => { // The track or group dying cancels the stream; the peer's own close // arrives through the ingest's reads. let res = 'serve: { @@ -806,7 +828,10 @@ impl GroupRecv { // Held until the group settles below, so a frame the track or group cut // short drops into an already-aborted group instead of reporting a loss. let GroupRecvState::Serve { - group, ingest: _ingest, .. + group, + ingest: _ingest, + _reading, + .. } = std::mem::replace(&mut self.state, GroupRecvState::Done) else { unreachable!() @@ -1379,6 +1404,172 @@ mod tests { const VERSION: Version = Version::Lite05; + /// The owed groups start at the floor the demand last asked for, which an update can move + /// either way after SUBSCRIBE_START answered the SUBSCRIBE. + #[tokio::test] + async fn the_owed_floor_follows_the_demand() { + let mut session = crate::lite::test_transport::ScriptedSession::new(Vec::new()); + let stream = Stream::open(&mut session, VERSION).await.unwrap(); + let mut sub = SubStream { + stream, + id: 0, + max_age: Duration::ZERO, + start: Some(Position::group(2)), + priority: 0, + requested: Some(Position::group(2)), + tail: Default::default(), + served: None, + end: Some(lite::SubscribeEnd { group: 10, streams: 0 }), + }; + assert_eq!( + sub.owed(None), + Some(10..10), + "without SUBSCRIBE_START nothing was served" + ); + + sub.served = Some(4); + assert_eq!( + sub.owed(None), + Some(2..10), + "the groups below START are accounted for on arrival" + ); + sub.start = Some(Position::group(6)); + assert_eq!(sub.owed(None), Some(6..10), "a raised floor owes nothing below it"); + sub.start = Some(Position::group(1)); + assert_eq!( + sub.owed(None), + Some(1..10), + "a lowered floor owes what it newly asked for" + ); + sub.start = None; + assert_eq!( + sub.owed(Some(8)), + Some(4..8), + "a live-edge floor starts where START resolved it" + ); + } + + /// A group at or past the end the publisher declared contradicts that end, which no later + /// stream can repair, so the whole track fails rather than ending clean without it. lite-05 + /// specified an inclusive end, so there it costs only that group's stream. + #[tokio::test] + async fn a_group_past_the_declared_end_aborts_the_track() { + use crate::transport::poll::Session as _; + + for version in [Version::Lite05, Version::Lite06, Version::Lite07] { + let mut script = Vec::new(); + lite::Group { + subscribe: 7, + sequence: 3, + frame_start: 0, + } + .encode(&mut script, version) + .unwrap(); + let mut session = crate::lite::test_transport::ScriptedSession::eof(script); + let subscriber = Subscriber::new(SubscriberConfig { + runtime: crate::time::Clock::tokio(), + session: session.clone(), + origin: origin::Config::new(crate::Hop::new(1).unwrap()).produce(), + recv_bandwidth: None, + version, + peer_setup: Default::default(), + peer_hop: None, + cost: None, + going_away: Default::default(), + }); + + let mut track = track::Producer::new(std::sync::Arc::new(crate::broadcast::Info::default()), "video", None); + track.finish_at(3).unwrap(); + subscriber.subscribes.lock().insert( + 7, + TrackEntry { + producer: track.clone(), + timescale: Some(Timescale::default()), + tail: Default::default(), + }, + ); + + let (_, recv) = session.open_bi().await.unwrap(); + let mut group = GroupRecv::new(subscriber, Reader::new(recv, version)); + let res = kio::wait(|waiter| group.poll_serve(waiter)).await; + match version { + Version::Lite05 => { + assert!(matches!(res, Err(Error::Closed)), "{version:?}: {res:?}"); + assert!( + track.closed().now_or_never().is_none(), + "{version:?}: the track lives on" + ); + } + _ => { + assert!(matches!(res, Err(Error::ProtocolViolation)), "{version:?}: {res:?}"); + assert!(matches!(track.closed().now_or_never(), Some(Error::ProtocolViolation))); + } + } + } + } + + /// A SUBSCRIBE_END below a group already received contradicts that group. lite-05 + /// specified an inclusive end, and `@moq/net` 0.1.3 to 0.1.9 sent one, so there it only + /// costs the early boundary; later drafts abort the track. + #[tokio::test(start_paused = true)] + async fn a_subscribe_end_below_a_received_group() { + for version in [Version::Lite05, Version::Lite06, Version::Lite07] { + let mut responses = Vec::new(); + lite::SubscribeResponse::Start(lite::SubscribeStart { group: 0 }) + .encode(&mut responses, version) + .unwrap(); + lite::SubscribeResponse::End(lite::SubscribeEnd { group: 2, streams: 1 }) + .encode(&mut responses, version) + .unwrap(); + let session = crate::lite::test_transport::ScriptedSession::eof(responses); + let subscriber = Subscriber::new(SubscriberConfig { + runtime: crate::time::Clock::tokio(), + session, + origin: origin::Config::new(crate::Hop::new(1).unwrap()).produce(), + recv_bandwidth: None, + version, + peer_setup: Default::default(), + peer_hop: None, + cost: None, + going_away: Default::default(), + }); + let serve = TrackServe { + subscriber, + path: Path::new("room").to_owned(), + name: "video".to_string(), + }; + let broadcast = crate::broadcast::Info::new().produce(); + let request = broadcast.reserve_track("video").unwrap(); + let serving = ServeLoop::new(&serve, request, Default::default(), Some(Timescale::default())); + let mut group = serving.serving.create_group(group::Info { sequence: 2 }).unwrap(); + group.write_frame(crate::Timestamp::ZERO, b"2".as_slice()).unwrap(); + group.finish().unwrap(); + let mut reader = broadcast + .consume() + .track("video") + .unwrap() + .subscribe(None) + .await + .unwrap(); + let mut running = TrackServeRun { + serve, + state: TrackRunState::Serve(serving), + }; + kio::wait(|waiter| kio::Task::poll(&mut running, waiter)).await; + + let end = loop { + match reader.recv_group().await { + Ok(Some(_)) => continue, + end => break end.map(|group| group.map(|group| group.sequence)), + } + }; + match version { + Version::Lite05 => assert!(matches!(end, Ok(None)), "{version:?}: {end:?}"), + _ => assert!(matches!(end, Err(Error::ProtocolViolation)), "{version:?}: {end:?}"), + } + } + } + /// Drive the subscriber with a peer's response bytes followed by FIN. async fn check_subscription_fin(version: Version, responses: Vec, clean: bool) { let session = crate::lite::test_transport::ScriptedSession::eof(responses); @@ -2778,11 +2969,18 @@ impl SubStream { /// The groups the publisher still owes once it has ended the subscription. /// /// `None` when nothing says which: drafts before SUBSCRIBE_END only have the FIN. - /// Without a SUBSCRIBE_START the publisher served no group at all. + /// Without a SUBSCRIBE_START the publisher served no group at all. Otherwise they start + /// at the floor the demand last asked for, which an update can move either way, or + /// where SUBSCRIBE_START resolved a live-edge one. The groups the SUBSCRIBE asked for + /// below its SUBSCRIBE_START are accounted for as unavailable when it arrives. fn owed(&self, requested_end: Option) -> Option> { let end = self.end.as_ref()?.group; let end = requested_end.map_or(end, |requested| requested.min(end)); - Some(self.served.unwrap_or(end)..end) + let start = match self.served { + Some(served) => self.start.map_or(served, |start| start.group), + None => end, + }; + Some(start..end) } } @@ -3055,6 +3253,14 @@ impl TrackServe { let start_moved = active.start != subscription.start; active.priority = subscription.priority; active.max_age = subscription.max_age; + if let Ok(mut tail) = active.tail.write() { + tail.set_grace(tail::grace(subscription.max_age)); + // A lowered floor owes groups nobody asked for until now. + if let Some(start) = subscription.start { + let floor = active.start.map(|start| start.group).or(active.served); + tail.demand(start.group..floor.unwrap_or(u64::MAX), self.subscriber.runtime.now()); + } + } active.start = subscription.start; if supports_update { // The floor follows the requested start, in both directions: @@ -3127,7 +3333,7 @@ impl TrackServe { tracing::info!(id, broadcast = %self.subscriber.log_path(&self.path), track = %self.name, "subscribe started"); - let tail = kio::Producer::new(Tail::default()); + let tail = kio::Producer::new(Tail::new(tail::grace(subscription.max_age))); self.subscriber.subscribes.lock().insert( id, TrackEntry { @@ -3735,15 +3941,22 @@ impl ServeLoop { // consumers learn the boundary early; the later stream FIN // then finds the track already finished. lite::SubscribeResponse::End(end) => { - // finish_at rejects a boundary at or below the live - // edge, which is what a peer sending an inclusive bound - // looks like once the final group has already arrived. - // Don't abort: the stream FIN still finishes the track, - // so this only costs the early boundary. Warn anyway, - // since it's our only signal that a peer disagrees - // about the encoding. + // finish_at rejects a boundary at or below a group + // already received. lite-05 specified an inclusive end, + // and `@moq/net` 0.1.3 to 0.1.9 sent one, so there it + // only costs the early boundary: warn, and let the FIN + // finish the track. Later drafts made it exclusive, so + // the publisher contradicted its own end. if let Err(err) = self.serving.finish_at(end.group) { - tracing::warn!(track = %serve.name, group = end.group, %err, "invalid subscribe end"); + match serve.subscriber.version { + Version::Lite05 => { + tracing::warn!(track = %serve.name, group = end.group, %err, "invalid subscribe end") + } + _ => { + tracing::warn!(track = %serve.name, group = end.group, %err, "subscribe end below a received group"); + return Poll::Ready(ServeEnd::GiveBack(Error::ProtocolViolation)); + } + } } active.end = Some(end.clone()); } @@ -3763,12 +3976,22 @@ impl ServeLoop { let _ = self.serving.start_at(start.group); } active.served = Some(start.group); + // The groups the SUBSCRIBE asked for below it are + // unavailable, whatever the demand asks later. + if let Some(requested) = active.requested + && let Ok(mut tail) = active.tail.write() + { + tail.account(requested.group..start.group, serve.subscriber.runtime.now()); + } } // The publisher will never send these groups, so they // are accounted for without a stream. lite::SubscribeResponse::Drop(dropped) => { if let Ok(mut tail) = active.tail.write() { - tail.account(dropped.start..dropped.end.saturating_add(1)); + tail.account( + dropped.start..dropped.end.saturating_add(1), + serve.subscriber.runtime.now(), + ); } } // OK just resolves the range (the producer already orders @@ -3800,12 +4023,14 @@ impl ServeLoop { // The effective max age is the stopgap grace: the wrong clock // (it bounds presentation-time drift), but it is how long the // subscriber was willing to wait for a late group anyway. - let grace = subscription - .map(|sub| sub.max_age) - .filter(|max_age| !max_age.is_zero()) - .unwrap_or(tail::GRACE); + if let Ok(mut tail) = active.tail.write() { + tail.set_grace(tail::grace( + subscription.map(|sub| sub.max_age).unwrap_or_default(), + )); + tail.expire(serve.subscriber.runtime.now()); + } self.mode = ServeMode::Tail { - settle: Settle::new(&serve.subscriber.runtime, active.tail.consume(), grace), + settle: Settle::new(&serve.subscriber.runtime, active.tail.consume()), owed: active.owed(requested_end), streams: active .end diff --git a/rs/moq-net/src/tail.rs b/rs/moq-net/src/tail.rs index 34e2ff6a292..b32a2f66487 100644 --- a/rs/moq-net/src/tail.rs +++ b/rs/moq-net/src/tail.rs @@ -5,10 +5,14 @@ //! it. The subscriber keeps the subscription routable until each owed group is accounted //! for, or a grace expires for a group whose stream was reset before its header arrived. //! A reset that keeps the header (reliable reset) would make the grace unnecessary. +//! +//! A stream whose header arrived is read to its end whatever the grace says: a group ends +//! on its own stream's FIN or reset, never because its track ended. A lost datagram is not +//! owed: it leaves a hole that waits out the grace like a stream reset before its header. use std::{ops::Range, task::Poll, time::Duration}; -use crate::runtime::Deadline; +use crate::runtime::{Deadline, Instant}; /// How long a subscriber waits for a group stream it cannot account for once the /// publisher has ended the subscription. @@ -17,52 +21,125 @@ use crate::runtime::Deadline; /// it with. Matches `@moq/net`, so a reader cannot tell which side it is talking to. pub(crate) const GRACE: Duration = Duration::from_secs(1); +/// The grace for a subscription with `max_age`: how long the subscriber was willing to +/// wait for a late group anyway, or [`GRACE`] without one. +pub(crate) fn grace(max_age: Duration) -> Duration { + match max_age.is_zero() { + true => GRACE, + false => max_age, + } +} + +/// A run of accounted sequences. +#[derive(Debug, Clone, PartialEq, Eq)] +struct Run { + groups: Range, + /// When the gap below this run opened, which is when its missing groups became late. + since: Instant, +} + /// The data streams a subscription has received, and the groups they account for. -#[derive(Default, Debug)] +#[derive(Debug)] pub(crate) struct Tail { - // Disjoint, sorted, non-adjacent ranges of accounted sequences, so this grows with the - // number of gaps rather than the number of groups. - accounted: Vec>, + // Disjoint, sorted, non-adjacent runs of accounted sequences. A gap older than the grace + // can no longer be waited for, so it folds into the runs around it, which bounds this by + // the gaps opened within the grace rather than every gap in the subscription. A fold is + // final: a later, longer grace or a lowered floor cannot reopen it. + runs: Vec, + grace: Duration, streams: u64, + // Streams whose header arrived and that are still being read. + active: u64, +} + +impl Default for Tail { + fn default() -> Self { + Self { + runs: Vec::new(), + grace: GRACE, + streams: 0, + active: 0, + } + } } impl Tail { - /// Record a group stream whose header arrived. - pub fn open(&mut self, sequence: u64) { - self.stream(); - self.account(sequence..sequence.saturating_add(1)); + /// A tail that gives up on a missing group after `grace`. + pub fn new(grace: Duration) -> Self { + Self { + grace, + ..Self::default() + } } - /// Record a data stream that names no single group, such as a fill. - pub fn stream(&mut self) { - self.streams += 1; + /// Change the grace, for a subscription whose max age changed. + pub fn set_grace(&mut self, grace: Duration) { + self.grace = grace; } /// Record groups as accounted for without a stream: dropped, or sent as a datagram. - pub fn account(&mut self, groups: Range) { + pub fn account(&mut self, groups: Range, now: Instant) { if groups.is_empty() { return; } - // Every range the insert overlaps or touches merges with it into one. - let first = self.accounted.partition_point(|range| range.end < groups.start); - let last = self.accounted.partition_point(|range| range.start <= groups.end); - let merged = match &self.accounted[first..last] { - [] => groups, - [head, .., tail] => head.start.min(groups.start)..tail.end.max(groups.end), - [only] => only.start.min(groups.start)..only.end.max(groups.end), + // Every run the insert overlaps or touches merges with it into one. + let first = self.runs.partition_point(|run| run.groups.end < groups.start); + let last = self.runs.partition_point(|run| run.groups.start <= groups.end); + let merged = match &self.runs[first..last] { + [] => Run { + groups, + // Splitting a gap leaves both halves as late as it was. A run past every + // other one opens a new gap. + since: self.runs.get(first).map_or(now, |above| above.since), + }, + [head, .., tail] => Run { + groups: head.groups.start.min(groups.start)..tail.groups.end.max(groups.end), + since: head.since, + }, + [only] => Run { + groups: only.groups.start.min(groups.start)..only.groups.end.max(groups.end), + since: only.since, + }, }; - self.accounted.splice(first..last, [merged]); + self.runs.splice(first..last, [merged]); + self.expire(now); + } + + /// Restart the age of every gap reaching into `groups`, which the demand newly asks for. + pub fn demand(&mut self, groups: Range, now: Instant) { + if groups.is_empty() { + return; + } + let mut below = 0; + for run in &mut self.runs { + if below < groups.end && groups.start < run.groups.start { + run.since = now; + } + below = run.groups.end; + } + } + + /// Fold every gap older than the grace into the runs around it. + pub fn expire(&mut self, now: Instant) { + let grace = self.grace; + self.runs.dedup_by(|run, below| { + let expired = now.duration_since(run.since) >= grace; + if expired { + below.groups.end = run.groups.end; + } + expired + }); } /// Whether every group in `groups` is accounted for. pub fn covers(&self, groups: Range) -> bool { - // Ranges merge on insert, so one range covers the span or none does. + // Runs merge on insert, so one run covers the span or none does. groups.is_empty() || self - .accounted + .runs .iter() - .any(|range| range.start <= groups.start && groups.end <= range.end) + .any(|run| run.groups.start <= groups.start && groups.end <= run.groups.end) } /// Data streams received, whether they finished or were reset. @@ -71,6 +148,65 @@ impl Tail { } } +/// A data stream whose header arrived, holding its subscription's end open until dropped. +pub(crate) struct Reading { + tail: Option>, + active: bool, +} + +impl Reading { + /// Count a data stream, accounting for `group` when it names one (a fill does not). + pub fn open(tail: &kio::Producer, group: Option, now: Instant) -> Self { + let Ok(mut state) = tail.write() else { + return Self { + tail: None, + active: false, + }; + }; + state.streams += 1; + state.active += 1; + if let Some(group) = group { + state.account(group..group.saturating_add(1), now); + } + Self { + tail: Some(tail.clone()), + active: true, + } + } + + /// Stop holding the end open while the stream waits on another one, which holds it + /// open itself if its header arrived. + pub fn park(&mut self) { + self.set_active(false); + } + + /// Hold the end open again once the stream resumes reading. + pub fn resume(&mut self) { + self.set_active(true); + } + + fn set_active(&mut self, active: bool) { + if self.active == active { + return; + } + self.active = active; + if let Some(tail) = &self.tail + && let Ok(mut state) = tail.write() + { + match active { + true => state.active += 1, + false => state.active -= 1, + } + } + } +} + +impl Drop for Reading { + fn drop(&mut self) { + self.set_active(false); + } +} + /// Waits out a subscription's tail: until the owed streams are accounted for, or the grace. pub(crate) struct Settle { tail: kio::Consumer, @@ -78,21 +214,21 @@ pub(crate) struct Settle { } impl Settle { - /// Start waiting on `tail`, giving up on missing streams after `grace`. - pub fn new(runtime: &crate::time::Clock, tail: kio::Consumer, grace: Duration) -> Self { + /// Start waiting on `tail`, giving up on missing streams after its grace. + pub fn new(runtime: &crate::time::Clock, tail: kio::Consumer) -> Self { + let grace = tail.read().grace; Self { tail, grace: Deadline::after(runtime, grace), } } - /// Ready once `complete` holds, the grace expires, or the subscription is gone. + /// Ready once no stream is being read and either `complete` holds or the grace + /// expired, or once the subscription is gone. pub fn poll(&mut self, waiter: &kio::Waiter, mut complete: impl FnMut(&Tail) -> bool) -> Poll<()> { - if self.grace.poll(waiter).is_ready() { - return Poll::Ready(()); - } + let expired = self.grace.poll(waiter).is_ready(); self.tail - .poll(waiter, |tail| match complete(tail) { + .poll(waiter, |tail| match tail.active == 0 && (expired || complete(tail)) { true => Poll::Ready(()), false => Poll::Pending, }) @@ -104,24 +240,129 @@ impl Settle { mod tests { use super::*; + fn groups(tail: &Tail) -> Vec> { + tail.runs.iter().map(|run| run.groups.clone()).collect() + } + #[test] - fn ranges_merge_across_gaps() { + fn runs_merge_across_gaps() { + let now = Instant::now(); let mut tail = Tail::default(); - tail.open(0); - tail.open(2); + tail.account(0..1, now); + tail.account(2..3, now); assert!(!tail.covers(0..3), "group 1 is missing"); - assert_eq!(tail.accounted, vec![0..1, 2..3]); + assert_eq!(groups(&tail), vec![0..1, 2..3]); - tail.account(1..2); - assert!(tail.covers(0..3) && tail.accounted.len() == 1, "adjacent ranges merge"); + tail.account(1..2, now); + assert!(tail.covers(0..3) && tail.runs.len() == 1, "adjacent runs merge"); - tail.account(5..7); - tail.account(9..10); - tail.account(4..9); - assert_eq!(tail.accounted, vec![0..3, 4..10], "one insert swallows several ranges"); + tail.account(5..7, now); + tail.account(9..10, now); + tail.account(4..9, now); + assert_eq!(groups(&tail), vec![0..3, 4..10], "one insert swallows several runs"); assert!(tail.covers(4..10)); assert!(!tail.covers(2..5)); assert!(tail.covers(7..7), "an empty range is always covered"); - assert_eq!(tail.streams(), 2, "only streams count, not drops"); + } + + /// A gap older than the grace folds away, so a lossy track keeps only the gaps it can + /// still wait for. + #[test] + fn a_gap_past_the_grace_folds_away() { + let start = Instant::now(); + let mut tail = Tail::new(GRACE); + tail.account(0..1, start); + tail.account(2..3, start); + tail.account(4..5, start + GRACE / 2); + assert_eq!(groups(&tail), vec![0..1, 2..3, 4..5]); + + // Splitting the younger gap keeps it as late as it was. + tail.account(6..7, start + GRACE / 2); + tail.account(8..9, start + GRACE); + assert_eq!( + groups(&tail), + vec![0..3, 4..5, 6..7, 8..9], + "only the oldest gap expired" + ); + + tail.expire(start + GRACE * 2); + assert_eq!(groups(&tail), vec![0..9]); + assert!(tail.covers(0..9)); + } + + /// Splitting a gap leaves both halves with its age. + #[test] + fn a_split_gap_keeps_its_age() { + let start = Instant::now(); + let mut tail = Tail::new(GRACE); + tail.account(0..1, start); + tail.account(9..10, start); + tail.account(5..6, start + GRACE / 2); + assert_eq!(groups(&tail), vec![0..1, 5..6, 9..10]); + + tail.expire(start + GRACE); + assert_eq!(groups(&tail), vec![0..10], "both halves opened at the start"); + } + + /// A gap the demand newly asks for is late only from then, however old the run above it. + #[test] + fn a_lowered_floor_restarts_the_gap_age() { + let start = Instant::now(); + let mut tail = Tail::new(GRACE); + tail.account(3..4, start); + tail.account(9..10, start); + + let lowered = start + GRACE * 2; + tail.demand(1..3, lowered); + tail.account(1..2, lowered); + assert_eq!( + groups(&tail), + vec![1..2, 3..10], + "only the gap the floor reached restarts" + ); + assert!(!tail.covers(1..4)); + + tail.expire(lowered + GRACE); + assert!(tail.covers(1..10)); + } + + /// The grace gives up on streams that never arrived, never on one still being read: + /// its group, or the END_OF_TRACK it carries, still belongs to the track. + #[tokio::test(start_paused = true)] + async fn the_grace_waits_for_a_stream_being_read() { + use crate::runtime::Timers as _; + + let runtime = crate::time::Clock::tokio(); + let tail = kio::Producer::new(Tail::default()); + let reading = Reading::open(&tail, Some(0), runtime.now()); + let mut settle = Settle::new(&runtime, tail.consume()); + let mut settled = std::pin::pin!(kio::wait(|waiter| settle.poll(waiter, |_| false))); + + tokio::time::sleep(GRACE * 2).await; + assert!( + futures::poll!(settled.as_mut()).is_pending(), + "a stream is still being read" + ); + + drop(reading); + settled.await; + } + + /// A stream parked on another one does not hold the end open. + #[tokio::test(start_paused = true)] + async fn a_parked_stream_does_not_hold_the_end() { + use crate::runtime::Timers as _; + + let runtime = crate::time::Clock::tokio(); + let tail = kio::Producer::new(Tail::default()); + let mut reading = Reading::open(&tail, None, runtime.now()); + reading.park(); + let mut settle = Settle::new(&runtime, tail.consume()); + kio::wait(|waiter| settle.poll(waiter, |tail| tail.streams() == 1)).await; + + reading.resume(); + assert_eq!(tail.read().active, 1); + drop(reading); + assert_eq!(tail.read().active, 0); } } diff --git a/rs/moq-net/tests/support/mock.rs b/rs/moq-net/tests/support/mock.rs index c23cfbb5bff..36e5f74ea05 100644 --- a/rs/moq-net/tests/support/mock.rs +++ b/rs/moq-net/tests/support/mock.rs @@ -366,6 +366,10 @@ struct SessionSide { conn: Arc, /// Uni streams this side opened that the peer has not accepted yet, while held. held: Mutex>>, + /// Whether the peer has withheld uni stream credit, parking every open. + withheld: Mutex, + /// Whether the datagrams this side sends are lost. + lossy: Mutex, } /// An in-memory mock WebTransport session. @@ -382,6 +386,7 @@ pub struct MockSession { accept_bi: kio::Park, datagram: kio::Park, closed: kio::Park, + open_uni: kio::Park, } impl poll::Session for MockSession { @@ -439,7 +444,15 @@ impl poll::Session for MockSession { } } - fn poll_open_uni(&mut self, _cx: &mut Context<'_>) -> Poll> { + fn poll_open_uni(&mut self, cx: &mut Context<'_>) -> Poll> { + if *self.side.withheld.lock().unwrap() { + self.side.conn.waiters.register(self.open_uni.hold(cx)); + return match self.side.conn.error() { + Some(err) => Poll::Ready(Err(err)), + None => Poll::Pending, + }; + } + let (mut our_send, peer_recv) = new_stream_pair(&self.side.conn); if let Some(held) = self.side.held.lock().unwrap().as_mut() { @@ -456,6 +469,9 @@ impl poll::Session for MockSession { } fn poll_send_datagram(&mut self, _cx: &mut Context<'_>, payload: &[u8]) -> Poll> { + if *self.side.lossy.lock().unwrap() { + return Poll::Ready(Ok(())); + } match self.side.peer_datagrams.try_push(Bytes::copy_from_slice(payload)) { Ok(()) => Poll::Ready(Ok(())), Err(_) => Poll::Ready(Err(self.close_error())), @@ -553,6 +569,17 @@ impl MockSession { pub fn drop_unis(&self) { self.side.held.lock().unwrap().take(); } + + /// Park every uni stream this side opens from now on, like a peer that has granted + /// no more stream credit. + pub fn withhold_unis(&self) { + *self.side.withheld.lock().unwrap() = true; + } + + /// Lose every datagram this side sends from now on. + pub fn lose_datagrams(&self) { + *self.side.lossy.lock().unwrap() = true; + } } impl MockSession { @@ -590,6 +617,8 @@ pub fn create_mock_session_pair(protocol: Option<&'static str>) -> (MockSession, protocol, conn: conn.clone(), held: Mutex::default(), + withheld: Mutex::default(), + lossy: Mutex::default(), }); let server_side = Arc::new(SessionSide { @@ -602,6 +631,8 @@ pub fn create_mock_session_pair(protocol: Option<&'static str>) -> (MockSession, protocol, conn, held: Mutex::default(), + withheld: Mutex::default(), + lossy: Mutex::default(), }); let new = |side| MockSession { @@ -610,6 +641,7 @@ pub fn create_mock_session_pair(protocol: Option<&'static str>) -> (MockSession, accept_bi: kio::Park::default(), datagram: kio::Park::default(), closed: kio::Park::default(), + open_uni: kio::Park::default(), }; (new(client_side), new(server_side)) diff --git a/rs/moq-net/tests/track_tail.rs b/rs/moq-net/tests/track_tail.rs index a2e21403bf9..71857fc61b7 100644 --- a/rs/moq-net/tests/track_tail.rs +++ b/rs/moq-net/tests/track_tail.rs @@ -56,12 +56,22 @@ struct Outcome { elapsed: Duration, } -/// Publish a group below the declared end (or none for an empty track), hold its stream -/// back until the subscription ends, then deliver or lose it. -async fn round(version: &str, late: Late, final_sequence: u64) -> Outcome { +/// A publisher and subscriber over the mock, with the subscriber holding `bcast`. +struct Pair { + pair: support::harness::MockPair, + track: moq_net::track::Producer, + remote: moq_net::broadcast::Consumer, + _keep: ( + moq_net::broadcast::Producer, + moq_net::origin::Producer, + moq_net::origin::Producer, + ), +} + +async fn connect(version: &str) -> Pair { let publisher = produce_origin(1); let broadcast = publisher.create_broadcast("bcast").unwrap(); - let mut track = broadcast.create_track("video", None).unwrap(); + let track = broadcast.create_track("video", None).unwrap(); broadcast.announce(Default::default()).unwrap(); let subscriber = produce_origin(2); @@ -80,6 +90,24 @@ async fn round(version: &str, late: Late, final_sequence: u64) -> Outcome { .expect("resolve timeout") .expect("broadcast resolves"); + Pair { + pair, + track, + remote, + _keep: (broadcast, publisher, subscriber), + } +} + +/// Publish a group below the declared end (or none for an empty track), hold its stream +/// back until the subscription ends, then deliver or lose it. +async fn round(version: &str, late: Late, final_sequence: u64) -> Outcome { + let Pair { + pair, + mut track, + remote, + _keep, + } = connect(version).await; + let reader = tokio::spawn(async move { let subscription = moq_net::track::Subscription::default().with_start(moq_net::track::Position::group(0)); let mut sub = remote @@ -140,7 +168,7 @@ async fn round(version: &str, late: Late, final_sequence: u64) -> Outcome { .await .expect("the subscription never ended") .expect("reader panicked"); - drop((pair, broadcast, publisher, subscriber)); + drop((pair, _keep)); Outcome { frames, err, @@ -214,3 +242,128 @@ async fn lite07_zero_streams_end_without_the_grace() { assert!(outcome.frames.is_empty()); assert!(outcome.elapsed < GRACE / 10, "ended after {:?}", outcome.elapsed); } + +/// IETF drafts over the control stream adapter (14), on their own streams (17), and with +/// subscription fills (20+). +const IETF: &[&str] = &[ + "moq-transport-14", + "moq-transport-17", + "moq-transport-20", + "moq-transport-22", +]; + +/// A subscriber that leaves while END_OF_TRACK waits for stream credit ends the publisher's +/// request, instead of parking it until credit that may never come. +#[tokio::test] +async fn ietf_leaving_cancels_a_blocked_end_of_track() { + tokio::time::pause(); + for version in IETF { + let Pair { + pair, + track, + remote, + _keep, + } = connect(version).await; + + let subscription = moq_net::track::Subscription::default().with_start(moq_net::track::Position::group(0)); + let mut sub = remote + .track("video") + .unwrap() + .subscribe(subscription) + .await + .expect("subscribe"); + tokio::time::timeout(TIMEOUT, track.used()) + .await + .expect("no subscriber appeared") + .unwrap(); + + let mut group = track.append_group().unwrap(); + group.write_frame(Timestamp::ZERO, PAYLOAD).unwrap(); + group.finish().unwrap(); + let mut group = tokio::time::timeout(TIMEOUT, sub.recv_group()) + .await + .expect("group timeout") + .unwrap() + .expect("a group"); + while group.read_frame().await.unwrap().is_some() {} + + // Out of stream credit, so the marker cannot open. + pair.server_transport.withhold_unis(); + track.finish().unwrap(); + tokio::time::sleep(GRACE / 10).await; + assert!( + track.subscription().is_some(), + "{version}: the publisher is still ending the request" + ); + + // The request task holds the publisher's subscription until it ends. + drop((group, sub)); + tokio::time::timeout(TIMEOUT, async { + while track.subscription().is_some() { + tokio::time::sleep(GRACE / 100).await; + } + }) + .await + .unwrap_or_else(|_| panic!("{version}: the publisher's request never ended")); + drop((pair, _keep)); + } +} + +/// A lost datagram is not owed. Nothing tells the subscriber its sequence was a datagram, so +/// on the drafts that account for the owed range its hole keeps the subscription routable for +/// the grace, like a stream reset before its header. A reader never waits on it: the track +/// ends for readers once the live edge reaches the declared end. +#[tokio::test] +async fn a_lost_datagram_never_delays_the_end() { + tokio::time::pause(); + for version in ["moq-lite-05", "moq-lite-07-wip"] { + let Pair { + pair, + mut track, + remote, + _keep, + } = connect(version).await; + + let reader = tokio::spawn(async move { + let subscription = moq_net::track::Subscription::default().with_start(moq_net::track::Position::group(0)); + let mut sub = remote + .track("video") + .unwrap() + .subscribe(subscription) + .await + .expect("subscribe"); + let mut groups = Vec::new(); + while let Some(group) = sub.recv_group().await.expect("track aborted") { + groups.push(group.sequence); + } + (groups, tokio::time::Instant::now()) + }); + tokio::time::timeout(TIMEOUT, track.used()) + .await + .expect("no subscriber appeared") + .unwrap(); + + for datagram in [false, true, false] { + if datagram { + pair.server_transport.lose_datagrams(); + track.append_datagram(Timestamp::ZERO, PAYLOAD).unwrap(); + } else { + let mut group = track.append_group().unwrap(); + group.write_frame(Timestamp::ZERO, PAYLOAD).unwrap(); + group.finish().unwrap(); + } + tokio::time::sleep(GRACE / 100).await; + } + let finished = tokio::time::Instant::now(); + track.finish().unwrap(); + + let (groups, ended) = tokio::time::timeout(TIMEOUT, reader) + .await + .expect("the subscription never ended") + .expect("reader panicked"); + assert_eq!(groups, [0, 2], "{version}"); + let elapsed = ended - finished; + assert!(elapsed < GRACE / 10, "{version}: ended after {elapsed:?}"); + drop((pair, _keep)); + } +} From f8cf9e5310bf10d519ab6a1e20c6ea6a0aacb0d6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 17:25:38 -0700 Subject: [PATCH 078/128] feat(net): an update from an unknown publisher is a new source A hop-0 route can't prove it is the same publisher, so every update to one ends the anonymous front and clears the served broadcast in Rust, and JS restarts it. The cluster draft drops the hop-0 continuity rule. Co-Authored-By: Claude Opus 5.5 --- doc/bin/relay/cluster.md | 10 +++-- doc/concept/moq-lite.md | 6 +-- drafts/draft-lcurley-moq-cluster.md | 10 +++-- js/net/src/ietf/subscriber.test.ts | 48 +++++++++++++++++++- js/net/src/ietf/subscriber.ts | 17 ++++++-- js/net/src/lite/subscriber.test.ts | 21 +++++---- js/net/src/lite/subscriber.ts | 22 +++++++--- rs/moq-net/src/ietf/subscriber.rs | 7 +-- rs/moq-net/src/model/front.rs | 29 +++++++----- rs/moq-net/src/model/origin.rs | 68 ++++++++++++++++++++--------- 10 files changed, 174 insertions(+), 64 deletions(-) diff --git a/doc/bin/relay/cluster.md b/doc/bin/relay/cluster.md index 8326e6c364d..e7ed252b390 100644 --- a/doc/bin/relay/cluster.md +++ b/doc/bin/relay/cluster.md @@ -30,10 +30,12 @@ are spliced in. If no compatible source remains, the track fails with identity. A route whose original publisher (its first hop) changes is updated in place on -both wire protocols, so the broadcast never briefly vanishes downstream. -Subscriptions already in flight keep draining the old publisher until it ends -and are never spliced onto the new one. New requests resolve through the updated -route as a fresh broadcast, without the old publisher's track properties. +both wire protocols, so the broadcast never briefly vanishes downstream. An +update to a route whose first hop is 0 counts as a new source too, since nothing +shows it is the same publisher. Either way, subscriptions already in flight keep +draining the old source until it ends and are never spliced onto the new one. +New requests resolve through the updated route as a fresh broadcast, without the +old source's track properties. ## Topology diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 853a2bd41f9..03af643837c 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -85,9 +85,9 @@ newer, a clean end requires `SUBSCRIBE_END` before the publisher's FIN. A FIN without that declaration fails the subscription with `ProtocolViolation`; older moq-lite versions use FIN alone. moq-transport requires `PUBLISH_DONE` before FIN. moq-transport sessions behave the same when a namespace is withdrawn. A route -update that changes its first hop, the original publisher, is not a retraction: -subscriptions in flight drain the old publisher, and new requests resolve -through the new one. +update that changes its first hop, the original publisher, or whose first hop is +0 is a new source but not a retraction: subscriptions in flight drain the old +source, and new requests resolve through the updated route. ### Hidden broadcasts diff --git a/drafts/draft-lcurley-moq-cluster.md b/drafts/draft-lcurley-moq-cluster.md index 5d40640cd41..47c1163ee16 100644 --- a/drafts/draft-lcurley-moq-cluster.md +++ b/drafts/draft-lcurley-moq-cluster.md @@ -227,10 +227,11 @@ A receiver MUST NOT treat the repeat as a duplicate or a protocol violation. An advertisement lives as long as its stream, so an update on a new stream would leave two streams claiming one namespace. An endpoint MUST NOT open a second stream for an advertisement it already maintains on the session. -An update replaces the old parameters atomically, so a receiver MUST NOT tear down subscriptions or drop cached state because one arrived. -If the first HOP_PATH entry is unchanged the content is continuous and subscriptions MAY resume on the new route at a group boundary, even when that entry is 0: there is one advertisement, and its stream is the continuity. -If the first entry changed, the publisher changed, and the endpoint still sends an ordinary update. -The receiver keeps each subscription it is already serving on the old source until that source ends, MUST NOT resume or splice it onto the updated route, and serves new requests from the updated route without state cached from the old publisher. +An update replaces the old parameters atomically, so a receiver MUST NOT tear down subscriptions because one arrived. +If the first HOP_PATH entry is unchanged and non-zero the content is continuous and subscriptions MAY resume on the new route at a group boundary. +Otherwise the update is a new source: the first entry changed, or it is 0 and cannot show that the publisher did not change ({{zero}}). +The endpoint still sends it as an ordinary update. +The receiver keeps each subscription it is already serving on the old source until that source ends, MUST NOT resume or splice it onto the updated route, and serves new requests from the updated route without state cached from the old source. The expected update is a ROUTE_COST change, which is how a relay signals that it started or stopped carrying the namespace. @@ -332,6 +333,7 @@ This document requests one registration in the "REQUEST_ERROR Codes" registry. - Defined request resolution against the longest covering prefix and the NO_CAPACITY refusal with its single re-resolution; any other refusal is terminal, including between several publishers of one namespace. - A relay does not advertise a namespace because it resolved it; the publisher advertises the concrete namespace once producing. - A change of original publisher is an ordinary update instead of a withdrawal and a new advertisement. Subscriptions already served drain the old source; new requests take the updated route. +- An update whose first HOP_PATH entry is 0 is a new source like a change of publisher, not a continuation. ## moq-cluster-01 - Assigned identities are local selection state and MUST NOT be forwarded. diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index 18968dbe625..be05801f467 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -1,7 +1,7 @@ import { expect, spyOn, test } from "bun:test"; import type * as announce from "../announced.ts"; import { ProtocolViolation, StreamCode, Stream as StreamError } from "../error.ts"; -import { type Hop, HopSchema } from "../hop.ts"; +import { type Hop, HopSchema, UNKNOWN_HOP } from "../hop.ts"; import { createMockTransportPair } from "../mock.ts"; import * as Path from "../path.ts"; import { Reader, Stream } from "../stream.ts"; @@ -667,6 +667,52 @@ test("a PUBLISH_NAMESPACE update that changes the publisher applies in place", a expect(await announced.next()).toMatchObject({ prefix: Path.from("theirs"), kind: "retracted" }); }); +/** + * An update whose first Hop ID is 0 before and after cannot be proven the same publisher, + * so it is a restart: consumers hear an end before the start, and the next consume starts + * fresh while a held broadcast drains. The stream stays open. + */ +test("a PUBLISH_NAMESPACE update from an unknown publisher restarts it", async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const session = new NativeSession(pair.server, VERSION, true); + const subscriber = new Subscriber({ session, cluster: { self: SELF, peer: PEER } }); + const theirs = Path.from("theirs"); + + const announced = subscriber.announced(); + await acceptSubscribeNamespace(pair.client); + + const request = await Stream.open(pair.server, { version: VERSION }); + const handler = subscriber.runPublishNamespace( + new PublishNamespace({ + requestId: 0n, + trackNamespace: theirs, + cluster: { hops: [UNKNOWN_HOP, PEER], cost: 4n }, + }), + request, + ); + expect(await announced.next()).toMatchObject({ prefix: theirs, kind: "announced" }); + + const peer = await nextStream(pair.client); + if (!peer) throw new Error("no PUBLISH_NAMESPACE stream"); + expect(await peer.reader.u53()).toBe(RequestOk.id); + await RequestOk.decode(peer.reader, VERSION); + const held = subscriber.consume(theirs); + + await peer.writer.u53(PublishNamespaceUpdate.id); + await new PublishNamespaceUpdate({ requestId: 3n, update: { cost: 0n } }).encode(peer.writer, VERSION); + expect(await peer.reader.u53()).toBe(RequestOk.id); + await RequestOk.decode(peer.reader, VERSION); + expect(await announced.next()).toMatchObject({ prefix: theirs, kind: "retracted" }); + expect(await announced.next()).toMatchObject({ prefix: theirs, kind: "announced" }); + + expect(subscriber.consume(theirs).closed).not.toBe(held.closed); + expect(held.closed.peek()).toBeUndefined(); + + peer.close(); + await handler; + expect(await announced.next()).toMatchObject({ prefix: theirs, kind: "retracted" }); +}); + /** * A second PUBLISH_NAMESPACE on the stream that already carries one is no longer an * update: it is the base draft's duplicate request, a protocol violation. diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 3e727bf8335..5eae7550e16 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -245,17 +245,26 @@ export class Subscriber { * * A new first hop is a new publisher: holders keep their broadcast to drain, but the * next consume starts fresh rather than reusing the old publisher's cached track info. + * An update whose first hop is 0 on both sides cannot be proven the same publisher, so + * it is a restart: consumers hear an end before the start, as on moq-lite. */ #updateAnnounce(path: Path.Valid, route: Route) { const existing = this.#announced.get(path); if (existing === undefined || routesEqual(existing.route, route)) return; - if (existing.route.hops[0] !== route.hops[0]) this.#consumes.evict(path); + const previous = existing.route; + const restart = previous.hops[0] === UNKNOWN_HOP && route.hops[0] === UNKNOWN_HOP; + if (restart || previous.hops[0] !== route.hops[0]) this.#consumes.evict(path); existing.route = route; - console.debug(`announced: broadcast=${path} rerouted`); + console.debug(`announced: broadcast=${path} ${restart ? "restarted" : "rerouted"}`); for (const [consumer, filter] of this.#announcedConsumers) { if (!sees(filter, path)) continue; - const scope = filter.scope; - consumer.append({ prefix: path, captures: scopeCaptures(scope, path), kind: "updated", route }); + const captures = scopeCaptures(filter.scope, path); + if (restart) { + consumer.append({ prefix: path, captures, kind: "retracted", route: previous }); + consumer.append({ prefix: path, captures, kind: "announced", route }); + } else { + consumer.append({ prefix: path, captures, kind: "updated", route }); + } } } diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index e401d509330..da9bd28c2e9 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -343,10 +343,11 @@ test("a lite-05 duplicate announce follows the same restart rule", async () => { }); // A responder that withholds its Hop ID sends the reserved 0, and an empty chain means it -// originated the path itself, so the advertisement names nobody. A restart of it is still the -// one advertisement, whose stream is the continuity, so it updates in place like Rust's and -// keeps the shared broadcast. Only a first hop that changes names a new publisher. -test("a restart from an unidentified publisher updates in place", async () => { +// originated the path itself, so the advertisement names nobody. Two such advertisements can +// be unrelated publishers, so a restart is a new source: an end before the start, and the next +// consume starts fresh. Mirrors the Rust origin, where any update to an anonymous route ends +// the front serving it. +test("a restart from an unidentified publisher is a new source", async () => { const { subscriber, send, settle } = announceHarness(Version.DRAFT_06); const announced = subscriber.announced(); await settle(); @@ -364,13 +365,17 @@ test("a restart from an unidentified publisher updates in place", async () => { Version.DRAFT_06, ), ); - expect(await announced.next()).toMatchObject({ prefix: room, kind: "updated" }); - expect(subscriber.consume(room).closed).toBe(held.closed); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "retracted" }); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "announced" }); + const restarted = subscriber.consume(room); + expect(restarted.closed).not.toBe(held.closed); + expect(held.closed.peek()).toBeUndefined(); - // Naming a publisher is a change of publisher: the next consume starts fresh. + // Naming a publisher is a change of publisher, which updates in place and still + // starts the next consume fresh. await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [PUBLISHER_A] }, Version.DRAFT_06)); expect(await announced.next()).toMatchObject({ prefix: room, kind: "updated" }); - expect(subscriber.consume(room).closed).not.toBe(held.closed); + expect(subscriber.consume(room).closed).not.toBe(restarted.closed); announced.close(); subscriber.close(); diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 567d06475f1..ec378d44dff 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -109,6 +109,11 @@ const MAX_CLOSE_REASON = 1024; // The longest prefix of `text` that fits a close reason. `encodeInto` stops on a whole // code point, so `read` never lands mid-character the way slicing bytes would. +/** Whether a publisher names nobody: absent, or the reserved hop 0. */ +function unidentified(publisher: Hop | undefined): boolean { + return publisher === undefined || publisher === UNKNOWN_HOP; +} + function closeReason(text: string): string { const encoder = new TextEncoder(); const buf = new Uint8Array(MAX_CLOSE_REASON); @@ -241,9 +246,9 @@ export class Subscriber { // the map instead would let a later announce take the path, and the skipped one's // `endedId` would then retract that one's state. // - // `publisher` is what lets a restart tell a route change (same publisher) from a - // new publisher on the route, whose content the next consume must not share - // with the old one's. + // `publisher` is what lets a restart tell a route change (the same named + // publisher) from a new source (another publisher, or one naming nobody), whose + // content the next consume must not share with the old one's. type Advertisement = { publisher: Hop | undefined; live: boolean; @@ -426,10 +431,15 @@ export class Subscriber { } // A second advertisement for a path we already carry is a restart: either an - // explicit ANNOUNCE_UPDATE, or (lite-05) a duplicate ANNOUNCE. It updates the - // route in place, so a forwarder re-prices without retracting. + // explicit ANNOUNCE_UPDATE, or (lite-05) a duplicate ANNOUNCE. A named + // publisher's restart updates the route in place, so a forwarder re-prices + // without retracting. Mirrors the Rust origin's route generation. const previous = advertised.get(path); - if (previous?.live) { + if (previous?.live && unidentified(previous.publisher) && unidentified(publisher)) { + // Nobody is named on either side, so this cannot be proven the same + // content: a new source. Surface a real end before the start. + retract(); + } else if (previous?.live) { // A different publisher took the path. Subscriptions already open drain // the old copy, but the next consume starts fresh rather than reusing the // old publisher's cached track info. diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 53834b661e2..596167f1548 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -4733,9 +4733,10 @@ mod tests { /// Regression: a publisher that declares no identity of its own contributes /// `Hop::UNKNOWN` as the first hop, which identifies nothing. A repeat NAMESPACE /// is still the same advertisement being repriced (the expected update, and how a - /// relay signals that it started carrying the namespace), so the source and every - /// live subscription on it must survive. Reading the repeat as a new publisher - /// detached the source milliseconds after SUBSCRIBE went out. + /// relay signals that it started carrying the namespace), so the route stays + /// attached and every live subscription on it drains rather than ending; only new + /// requests treat it as a new source. Detaching the route instead ended the source + /// milliseconds after SUBSCRIBE went out. #[tokio::test(start_paused = true)] async fn anonymous_publisher_survives_a_repricing_update() { let (mut subscriber, origin) = cluster_subscriber(crate::Hop::new(1).unwrap()); diff --git a/rs/moq-net/src/model/front.rs b/rs/moq-net/src/model/front.rs index 93eae6197f9..831f11e9196 100644 --- a/rs/moq-net/src/model/front.rs +++ b/rs/moq-net/src/model/front.rs @@ -21,12 +21,14 @@ use std::{ use crate::{Error, Hop, runtime::Instant, track}; /// A route the table selected for the front: the entry id, the endpoint that -/// originated it, and whether it is a broadcast published on this origin. +/// originated it, whether it is a broadcast published on this origin, and how +/// many times an update made it a new source. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(super) struct Candidate { pub route: u64, pub first: Option, pub local: bool, + pub generation: u64, } /// Why an upstream request through a route did not produce a source. @@ -138,9 +140,9 @@ pub(super) enum Identity { Local, /// The serving route's first hop was absent or [`Hop::UNKNOWN`], which /// identifies nobody: the front cannot resume through any other route, so - /// its source ending, `route` leaving the table, or `route` gaining a first - /// hop ends it. - Anonymous { route: u64 }, + /// its source ending, `route` leaving the table, or any update to `route` + /// (a new `generation`) ends it. + Anonymous { route: u64, generation: u64 }, /// The first hop of the serving route. Routes sharing it are the same /// origin reached another way and safe to resume through. Publisher(Hop), @@ -155,9 +157,9 @@ pub(super) enum Pin { Local, /// Only routes originated by this first hop. Publisher(Hop), - /// Only this route, while its publisher stays unknown: the front never fails - /// over, and an update naming a publisher ends it. - Route(u64), + /// Only this generation of this route, while its publisher stays unknown: + /// the front never fails over, and any update to the route ends it. + Route { id: u64, generation: u64 }, } impl Identity { @@ -165,7 +167,7 @@ impl Identity { match self { Self::Undetermined => Pin::Any, Self::Local => Pin::Local, - Self::Anonymous { route } => Pin::Route(route), + Self::Anonymous { route, generation } => Pin::Route { id: route, generation }, Self::Publisher(hop) => Pin::Publisher(hop), } } @@ -440,7 +442,10 @@ impl Front { self.identity = match (candidate.local, candidate.first) { (true, _) => Identity::Local, (false, Some(hop)) if hop != Hop::UNKNOWN => Identity::Publisher(hop), - (false, _) => Identity::Anonymous { route: candidate.route }, + (false, _) => Identity::Anonymous { + route: candidate.route, + generation: candidate.generation, + }, }; } @@ -678,6 +683,7 @@ mod tests { route, first: Some(hop(first)), local: false, + generation: 0, } } @@ -686,6 +692,7 @@ mod tests { route, first: None, local: true, + generation: 0, } } @@ -886,6 +893,7 @@ mod tests { route: 1, first: Some(Hop::UNKNOWN), local: false, + generation: 0, }; let mut front = serving(candidate, 100); assert_actions( @@ -923,9 +931,10 @@ mod tests { route: 1, first: Some(Hop::UNKNOWN), local: false, + generation: 0, }; let mut front = serving(candidate, 100); - assert_eq!(front.pin(), Pin::Route(1)); + assert_eq!(front.pin(), Pin::Route { id: 1, generation: 0 }); assert_actions( front.step(Event::SourceClosed { source: 100 }), &[Action::Detach { source: 100 }, Action::End { err: Error::Dropped }], diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 3850310dc0d..0c52db6b754 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -737,6 +737,10 @@ struct RouteEntry { /// through it. A broadcast is in the table from creation but serves nobody, /// locally or remotely, until it announces. advertised: bool, + /// Bumped by each update that makes the entry a new source: a first hop + /// that changed, or one that names nobody. An anonymous front serves only + /// the generation it started on. + generation: u64, /// Whether a peer the chain passes through has since withdrawn this prefix. /// The route was derived from that peer's advertisement, so it serves nobody /// until the peer announces again. See [`Dynamic::withdrawn`]. @@ -755,6 +759,11 @@ impl RouteEntry { self.advertised && !self.stale } + /// Whether the first hop names nobody, so no update can prove continuity. + fn first_unknown(&self) -> bool { + self.hops.iter().next().is_none_or(|first| *first == Hop::UNKNOWN) + } + fn is_anonymous(&self) -> bool { self.hops.iter().any(|hop| *hop == Hop::UNKNOWN) } @@ -780,8 +789,7 @@ impl RouteEntry { Pin::Any => true, Pin::Local => self.local, Pin::Publisher(first) => self.hops.iter().next() == Some(&first), - // An update that names a publisher is a different one, even in place. - Pin::Route(id) => self.id == id && self.hops.iter().next().is_none_or(|first| *first == Hop::UNKNOWN), + Pin::Route { id, generation } => self.id == id && self.generation == generation && self.first_unknown(), } } @@ -1725,6 +1733,7 @@ impl Announcing { server: serving.server.clone(), source: serving.source.clone(), advertised: serving.advertised, + generation: 0, stale, claim: claim.clone(), }); @@ -1822,12 +1831,16 @@ impl AnnounceProducer { let Some(entry) = shared.routes.entry_mut(prefix, *id) else { return Err(Error::Closed); }; - // A new first hop is a new publisher: a later request goes back to the - // handler rather than joining what the old one served. - if entry.hops.iter().next() != route.hops.iter().next() - && let Some(server) = &entry.server - { - drop(std::mem::take(&mut server.lock().served)); + // A new first hop is a new publisher, and an unknown one cannot prove it + // is the same: either way a later request goes back to the handler + // rather than joining what was served before. + let first = route.hops.iter().next(); + let unknown = first.is_none_or(|first| *first == Hop::UNKNOWN); + if unknown || entry.hops.iter().next() != first { + entry.generation += 1; + if let Some(server) = &entry.server { + drop(std::mem::take(&mut server.lock().served)); + } } entry.hops = route.hops.clone(); entry.stale = stale; @@ -2329,6 +2342,7 @@ async fn run_front(task: FrontTask) { route: entry.id, first: entry.hops.iter().next().copied(), local: entry.local, + generation: entry.generation, }); let serving_closing = front .serving() @@ -2358,6 +2372,7 @@ async fn run_front(task: FrontTask) { route, first: entry.hops.iter().next().copied(), local: entry.local, + generation: entry.generation, }, entry.source.clone(), entry.server.clone(), @@ -3379,9 +3394,9 @@ impl Dynamic { /// Re-price the route in place: replace its hops and cost. /// /// Consumers observe another active update for the same prefix; sessions - /// forward it as a restart, so route churn never looks like new content. A - /// new first hop is a new publisher: broadcasts already served from the old - /// one drain, and later requests reach the handler again. The prefix is fixed + /// forward it as a restart. A new first hop, or an unknown one, is a new + /// source: broadcasts already served drain, and later requests reach the + /// handler again. The prefix is fixed /// at announce time: to move a route, drop this and call /// [`Producer::dynamic`] again. Fails with [`Error::Closed`] once the origin's /// [`Driver`] has been dropped. @@ -4077,7 +4092,7 @@ impl Consumer { /// announced the route. When its serving source dies or a better qualifying /// route appears, the front re-splices through the best route sharing its /// first hop at a group boundary, invisibly to subscribers. A change that - /// does not preserve the first hop ends the broadcast instead, as does its + /// does not preserve a known first hop ends the broadcast instead, as does its /// route retracting with no replacement, and the next request re-serves the /// path. Tracks already in flight carry on to their own end. /// @@ -6839,14 +6854,25 @@ mod tests { } /// A route updated in place to a new first hop names a new publisher, whether the - /// front started anonymous or named. The in-flight subscription drains the old copy - /// until it ends and never splices the new one; a new request gets a fresh front - /// through the new publisher, free of the old broadcast's track info. + /// front started anonymous or named, and an update that leaves the first hop unknown + /// cannot prove it is the same one. Either way the in-flight subscription drains the + /// old copy until it ends and never splices the new one; a new request gets a fresh + /// front through the updated route, free of the old broadcast's track info. #[tokio::test] - async fn a_first_hop_update_drains_the_old_publisher() { - for first in [&[][..], &[0][..], &[10][..]] { + async fn a_new_source_drains_the_old_one() { + let cases: [(&[u64], &[u64]); 6] = [ + (&[], &[11]), + (&[0], &[11]), + (&[10], &[11]), + (&[10], &[0]), + (&[0], &[0]), + (&[], &[]), + ]; + for (first, next) in cases { let (mut rig, server, _source) = ResumeRig::new(first).await; - server.update(Route::default().with_hops(hops(&[11]))).unwrap(); + server + .update(Route::default().with_hops(hops(next)).with_cost(3)) + .unwrap(); // The old copy keeps flowing to the subscription already reading it. let mut group = rig.incumbent_track.append_group().unwrap(); @@ -6857,7 +6883,7 @@ mod tests { .expect("the in-flight subscription survives the update") .expect("track ended early"); let frame = group.read_frame().await.expect("read frame").expect("frame"); - assert_eq!(&frame.payload[..], b"draining", "first hop {first:?}"); + assert_eq!(&frame.payload[..], b"draining", "{first:?} to {next:?}"); // A new request is a new broadcast from the new publisher, whose track info // differs from what the old front cached. @@ -6876,7 +6902,7 @@ mod tests { let resolved = pending.await.expect("resolves through the new publisher"); assert!( !resolved.is_clone(&rig.resolved), - "first hop {first:?} joined the old front" + "{first:?} to {next:?} joined the old front" ); let mut fresh = resolved .track("video") @@ -6897,7 +6923,7 @@ mod tests { let end = next_group(&mut rig.subscription).await; assert!( !matches!(end, Ok(Some(_))), - "first hop {first:?} spliced the new publisher into a live subscription" + "{first:?} to {next:?} spliced the new publisher into a live subscription" ); } } From 4885cbc4a98e5c421c8d6917c650ded6167dcd0e Mon Sep 17 00:00:00 2001 From: rc4 <8405591+rc4@users.noreply.github.com> Date: Tue, 29 Sep 2026 20:34:51 -0400 Subject: [PATCH 079/128] docs: correct dnf add repo syntax (#4503) Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- doc/setup/install.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/setup/install.md b/doc/setup/install.md index 175687d6ef0..ff5b9877ebe 100644 --- a/doc/setup/install.md +++ b/doc/setup/install.md @@ -64,7 +64,10 @@ sudo apt install moq-relay moq gstreamer1.0-moq Fedora 39+, RHEL 9, Rocky 9, AlmaLinux 9. On openSUSE use `zypper addrepo`. ```bash +# DNF4, including RHEL 9 sudo dnf config-manager --add-repo https://rpm.moq.dev/moq.repo +# DNF5 +sudo dnf config-manager addrepo --from-repofile https://rpm.moq.dev/moq.repo sudo dnf install moq-relay moq gstreamer1-moq ``` From 3edeb7e8c4dfe175e573a66606bf2b643e3dd943 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 18:07:23 -0700 Subject: [PATCH 080/128] revert: drop the hop-0 new-source rule in favor of stamping Relays now stamp an unknown first hop with a per-connection ID instead. Co-Authored-By: Claude Opus 5.5 --- doc/bin/relay/cluster.md | 10 ++--- doc/concept/moq-lite.md | 6 +-- drafts/draft-lcurley-moq-cluster.md | 10 ++--- js/net/src/ietf/subscriber.test.ts | 48 +------------------- js/net/src/ietf/subscriber.ts | 17 ++------ js/net/src/lite/subscriber.test.ts | 21 ++++----- js/net/src/lite/subscriber.ts | 22 +++------- rs/moq-net/src/ietf/subscriber.rs | 7 ++- rs/moq-net/src/model/front.rs | 29 +++++------- rs/moq-net/src/model/origin.rs | 68 +++++++++-------------------- 10 files changed, 64 insertions(+), 174 deletions(-) diff --git a/doc/bin/relay/cluster.md b/doc/bin/relay/cluster.md index e7ed252b390..8326e6c364d 100644 --- a/doc/bin/relay/cluster.md +++ b/doc/bin/relay/cluster.md @@ -30,12 +30,10 @@ are spliced in. If no compatible source remains, the track fails with identity. A route whose original publisher (its first hop) changes is updated in place on -both wire protocols, so the broadcast never briefly vanishes downstream. An -update to a route whose first hop is 0 counts as a new source too, since nothing -shows it is the same publisher. Either way, subscriptions already in flight keep -draining the old source until it ends and are never spliced onto the new one. -New requests resolve through the updated route as a fresh broadcast, without the -old source's track properties. +both wire protocols, so the broadcast never briefly vanishes downstream. +Subscriptions already in flight keep draining the old publisher until it ends +and are never spliced onto the new one. New requests resolve through the updated +route as a fresh broadcast, without the old publisher's track properties. ## Topology diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 03af643837c..853a2bd41f9 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -85,9 +85,9 @@ newer, a clean end requires `SUBSCRIBE_END` before the publisher's FIN. A FIN without that declaration fails the subscription with `ProtocolViolation`; older moq-lite versions use FIN alone. moq-transport requires `PUBLISH_DONE` before FIN. moq-transport sessions behave the same when a namespace is withdrawn. A route -update that changes its first hop, the original publisher, or whose first hop is -0 is a new source but not a retraction: subscriptions in flight drain the old -source, and new requests resolve through the updated route. +update that changes its first hop, the original publisher, is not a retraction: +subscriptions in flight drain the old publisher, and new requests resolve +through the new one. ### Hidden broadcasts diff --git a/drafts/draft-lcurley-moq-cluster.md b/drafts/draft-lcurley-moq-cluster.md index 47c1163ee16..5d40640cd41 100644 --- a/drafts/draft-lcurley-moq-cluster.md +++ b/drafts/draft-lcurley-moq-cluster.md @@ -227,11 +227,10 @@ A receiver MUST NOT treat the repeat as a duplicate or a protocol violation. An advertisement lives as long as its stream, so an update on a new stream would leave two streams claiming one namespace. An endpoint MUST NOT open a second stream for an advertisement it already maintains on the session. -An update replaces the old parameters atomically, so a receiver MUST NOT tear down subscriptions because one arrived. -If the first HOP_PATH entry is unchanged and non-zero the content is continuous and subscriptions MAY resume on the new route at a group boundary. -Otherwise the update is a new source: the first entry changed, or it is 0 and cannot show that the publisher did not change ({{zero}}). -The endpoint still sends it as an ordinary update. -The receiver keeps each subscription it is already serving on the old source until that source ends, MUST NOT resume or splice it onto the updated route, and serves new requests from the updated route without state cached from the old source. +An update replaces the old parameters atomically, so a receiver MUST NOT tear down subscriptions or drop cached state because one arrived. +If the first HOP_PATH entry is unchanged the content is continuous and subscriptions MAY resume on the new route at a group boundary, even when that entry is 0: there is one advertisement, and its stream is the continuity. +If the first entry changed, the publisher changed, and the endpoint still sends an ordinary update. +The receiver keeps each subscription it is already serving on the old source until that source ends, MUST NOT resume or splice it onto the updated route, and serves new requests from the updated route without state cached from the old publisher. The expected update is a ROUTE_COST change, which is how a relay signals that it started or stopped carrying the namespace. @@ -333,7 +332,6 @@ This document requests one registration in the "REQUEST_ERROR Codes" registry. - Defined request resolution against the longest covering prefix and the NO_CAPACITY refusal with its single re-resolution; any other refusal is terminal, including between several publishers of one namespace. - A relay does not advertise a namespace because it resolved it; the publisher advertises the concrete namespace once producing. - A change of original publisher is an ordinary update instead of a withdrawal and a new advertisement. Subscriptions already served drain the old source; new requests take the updated route. -- An update whose first HOP_PATH entry is 0 is a new source like a change of publisher, not a continuation. ## moq-cluster-01 - Assigned identities are local selection state and MUST NOT be forwarded. diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index be05801f467..18968dbe625 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -1,7 +1,7 @@ import { expect, spyOn, test } from "bun:test"; import type * as announce from "../announced.ts"; import { ProtocolViolation, StreamCode, Stream as StreamError } from "../error.ts"; -import { type Hop, HopSchema, UNKNOWN_HOP } from "../hop.ts"; +import { type Hop, HopSchema } from "../hop.ts"; import { createMockTransportPair } from "../mock.ts"; import * as Path from "../path.ts"; import { Reader, Stream } from "../stream.ts"; @@ -667,52 +667,6 @@ test("a PUBLISH_NAMESPACE update that changes the publisher applies in place", a expect(await announced.next()).toMatchObject({ prefix: Path.from("theirs"), kind: "retracted" }); }); -/** - * An update whose first Hop ID is 0 before and after cannot be proven the same publisher, - * so it is a restart: consumers hear an end before the start, and the next consume starts - * fresh while a held broadcast drains. The stream stays open. - */ -test("a PUBLISH_NAMESPACE update from an unknown publisher restarts it", async () => { - const pair = createMockTransportPair(ALPN.DRAFT_19); - const session = new NativeSession(pair.server, VERSION, true); - const subscriber = new Subscriber({ session, cluster: { self: SELF, peer: PEER } }); - const theirs = Path.from("theirs"); - - const announced = subscriber.announced(); - await acceptSubscribeNamespace(pair.client); - - const request = await Stream.open(pair.server, { version: VERSION }); - const handler = subscriber.runPublishNamespace( - new PublishNamespace({ - requestId: 0n, - trackNamespace: theirs, - cluster: { hops: [UNKNOWN_HOP, PEER], cost: 4n }, - }), - request, - ); - expect(await announced.next()).toMatchObject({ prefix: theirs, kind: "announced" }); - - const peer = await nextStream(pair.client); - if (!peer) throw new Error("no PUBLISH_NAMESPACE stream"); - expect(await peer.reader.u53()).toBe(RequestOk.id); - await RequestOk.decode(peer.reader, VERSION); - const held = subscriber.consume(theirs); - - await peer.writer.u53(PublishNamespaceUpdate.id); - await new PublishNamespaceUpdate({ requestId: 3n, update: { cost: 0n } }).encode(peer.writer, VERSION); - expect(await peer.reader.u53()).toBe(RequestOk.id); - await RequestOk.decode(peer.reader, VERSION); - expect(await announced.next()).toMatchObject({ prefix: theirs, kind: "retracted" }); - expect(await announced.next()).toMatchObject({ prefix: theirs, kind: "announced" }); - - expect(subscriber.consume(theirs).closed).not.toBe(held.closed); - expect(held.closed.peek()).toBeUndefined(); - - peer.close(); - await handler; - expect(await announced.next()).toMatchObject({ prefix: theirs, kind: "retracted" }); -}); - /** * A second PUBLISH_NAMESPACE on the stream that already carries one is no longer an * update: it is the base draft's duplicate request, a protocol violation. diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 5eae7550e16..3e727bf8335 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -245,26 +245,17 @@ export class Subscriber { * * A new first hop is a new publisher: holders keep their broadcast to drain, but the * next consume starts fresh rather than reusing the old publisher's cached track info. - * An update whose first hop is 0 on both sides cannot be proven the same publisher, so - * it is a restart: consumers hear an end before the start, as on moq-lite. */ #updateAnnounce(path: Path.Valid, route: Route) { const existing = this.#announced.get(path); if (existing === undefined || routesEqual(existing.route, route)) return; - const previous = existing.route; - const restart = previous.hops[0] === UNKNOWN_HOP && route.hops[0] === UNKNOWN_HOP; - if (restart || previous.hops[0] !== route.hops[0]) this.#consumes.evict(path); + if (existing.route.hops[0] !== route.hops[0]) this.#consumes.evict(path); existing.route = route; - console.debug(`announced: broadcast=${path} ${restart ? "restarted" : "rerouted"}`); + console.debug(`announced: broadcast=${path} rerouted`); for (const [consumer, filter] of this.#announcedConsumers) { if (!sees(filter, path)) continue; - const captures = scopeCaptures(filter.scope, path); - if (restart) { - consumer.append({ prefix: path, captures, kind: "retracted", route: previous }); - consumer.append({ prefix: path, captures, kind: "announced", route }); - } else { - consumer.append({ prefix: path, captures, kind: "updated", route }); - } + const scope = filter.scope; + consumer.append({ prefix: path, captures: scopeCaptures(scope, path), kind: "updated", route }); } } diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index da9bd28c2e9..e401d509330 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -343,11 +343,10 @@ test("a lite-05 duplicate announce follows the same restart rule", async () => { }); // A responder that withholds its Hop ID sends the reserved 0, and an empty chain means it -// originated the path itself, so the advertisement names nobody. Two such advertisements can -// be unrelated publishers, so a restart is a new source: an end before the start, and the next -// consume starts fresh. Mirrors the Rust origin, where any update to an anonymous route ends -// the front serving it. -test("a restart from an unidentified publisher is a new source", async () => { +// originated the path itself, so the advertisement names nobody. A restart of it is still the +// one advertisement, whose stream is the continuity, so it updates in place like Rust's and +// keeps the shared broadcast. Only a first hop that changes names a new publisher. +test("a restart from an unidentified publisher updates in place", async () => { const { subscriber, send, settle } = announceHarness(Version.DRAFT_06); const announced = subscriber.announced(); await settle(); @@ -365,17 +364,13 @@ test("a restart from an unidentified publisher is a new source", async () => { Version.DRAFT_06, ), ); - expect(await announced.next()).toMatchObject({ prefix: room, kind: "retracted" }); - expect(await announced.next()).toMatchObject({ prefix: room, kind: "announced" }); - const restarted = subscriber.consume(room); - expect(restarted.closed).not.toBe(held.closed); - expect(held.closed.peek()).toBeUndefined(); + expect(await announced.next()).toMatchObject({ prefix: room, kind: "updated" }); + expect(subscriber.consume(room).closed).toBe(held.closed); - // Naming a publisher is a change of publisher, which updates in place and still - // starts the next consume fresh. + // Naming a publisher is a change of publisher: the next consume starts fresh. await send((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 0n, hops: [PUBLISHER_A] }, Version.DRAFT_06)); expect(await announced.next()).toMatchObject({ prefix: room, kind: "updated" }); - expect(subscriber.consume(room).closed).not.toBe(restarted.closed); + expect(subscriber.consume(room).closed).not.toBe(held.closed); announced.close(); subscriber.close(); diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index ec378d44dff..567d06475f1 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -109,11 +109,6 @@ const MAX_CLOSE_REASON = 1024; // The longest prefix of `text` that fits a close reason. `encodeInto` stops on a whole // code point, so `read` never lands mid-character the way slicing bytes would. -/** Whether a publisher names nobody: absent, or the reserved hop 0. */ -function unidentified(publisher: Hop | undefined): boolean { - return publisher === undefined || publisher === UNKNOWN_HOP; -} - function closeReason(text: string): string { const encoder = new TextEncoder(); const buf = new Uint8Array(MAX_CLOSE_REASON); @@ -246,9 +241,9 @@ export class Subscriber { // the map instead would let a later announce take the path, and the skipped one's // `endedId` would then retract that one's state. // - // `publisher` is what lets a restart tell a route change (the same named - // publisher) from a new source (another publisher, or one naming nobody), whose - // content the next consume must not share with the old one's. + // `publisher` is what lets a restart tell a route change (same publisher) from a + // new publisher on the route, whose content the next consume must not share + // with the old one's. type Advertisement = { publisher: Hop | undefined; live: boolean; @@ -431,15 +426,10 @@ export class Subscriber { } // A second advertisement for a path we already carry is a restart: either an - // explicit ANNOUNCE_UPDATE, or (lite-05) a duplicate ANNOUNCE. A named - // publisher's restart updates the route in place, so a forwarder re-prices - // without retracting. Mirrors the Rust origin's route generation. + // explicit ANNOUNCE_UPDATE, or (lite-05) a duplicate ANNOUNCE. It updates the + // route in place, so a forwarder re-prices without retracting. const previous = advertised.get(path); - if (previous?.live && unidentified(previous.publisher) && unidentified(publisher)) { - // Nobody is named on either side, so this cannot be proven the same - // content: a new source. Surface a real end before the start. - retract(); - } else if (previous?.live) { + if (previous?.live) { // A different publisher took the path. Subscriptions already open drain // the old copy, but the next consume starts fresh rather than reusing the // old publisher's cached track info. diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 596167f1548..53834b661e2 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -4733,10 +4733,9 @@ mod tests { /// Regression: a publisher that declares no identity of its own contributes /// `Hop::UNKNOWN` as the first hop, which identifies nothing. A repeat NAMESPACE /// is still the same advertisement being repriced (the expected update, and how a - /// relay signals that it started carrying the namespace), so the route stays - /// attached and every live subscription on it drains rather than ending; only new - /// requests treat it as a new source. Detaching the route instead ended the source - /// milliseconds after SUBSCRIBE went out. + /// relay signals that it started carrying the namespace), so the source and every + /// live subscription on it must survive. Reading the repeat as a new publisher + /// detached the source milliseconds after SUBSCRIBE went out. #[tokio::test(start_paused = true)] async fn anonymous_publisher_survives_a_repricing_update() { let (mut subscriber, origin) = cluster_subscriber(crate::Hop::new(1).unwrap()); diff --git a/rs/moq-net/src/model/front.rs b/rs/moq-net/src/model/front.rs index 831f11e9196..93eae6197f9 100644 --- a/rs/moq-net/src/model/front.rs +++ b/rs/moq-net/src/model/front.rs @@ -21,14 +21,12 @@ use std::{ use crate::{Error, Hop, runtime::Instant, track}; /// A route the table selected for the front: the entry id, the endpoint that -/// originated it, whether it is a broadcast published on this origin, and how -/// many times an update made it a new source. +/// originated it, and whether it is a broadcast published on this origin. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(super) struct Candidate { pub route: u64, pub first: Option, pub local: bool, - pub generation: u64, } /// Why an upstream request through a route did not produce a source. @@ -140,9 +138,9 @@ pub(super) enum Identity { Local, /// The serving route's first hop was absent or [`Hop::UNKNOWN`], which /// identifies nobody: the front cannot resume through any other route, so - /// its source ending, `route` leaving the table, or any update to `route` - /// (a new `generation`) ends it. - Anonymous { route: u64, generation: u64 }, + /// its source ending, `route` leaving the table, or `route` gaining a first + /// hop ends it. + Anonymous { route: u64 }, /// The first hop of the serving route. Routes sharing it are the same /// origin reached another way and safe to resume through. Publisher(Hop), @@ -157,9 +155,9 @@ pub(super) enum Pin { Local, /// Only routes originated by this first hop. Publisher(Hop), - /// Only this generation of this route, while its publisher stays unknown: - /// the front never fails over, and any update to the route ends it. - Route { id: u64, generation: u64 }, + /// Only this route, while its publisher stays unknown: the front never fails + /// over, and an update naming a publisher ends it. + Route(u64), } impl Identity { @@ -167,7 +165,7 @@ impl Identity { match self { Self::Undetermined => Pin::Any, Self::Local => Pin::Local, - Self::Anonymous { route, generation } => Pin::Route { id: route, generation }, + Self::Anonymous { route } => Pin::Route(route), Self::Publisher(hop) => Pin::Publisher(hop), } } @@ -442,10 +440,7 @@ impl Front { self.identity = match (candidate.local, candidate.first) { (true, _) => Identity::Local, (false, Some(hop)) if hop != Hop::UNKNOWN => Identity::Publisher(hop), - (false, _) => Identity::Anonymous { - route: candidate.route, - generation: candidate.generation, - }, + (false, _) => Identity::Anonymous { route: candidate.route }, }; } @@ -683,7 +678,6 @@ mod tests { route, first: Some(hop(first)), local: false, - generation: 0, } } @@ -692,7 +686,6 @@ mod tests { route, first: None, local: true, - generation: 0, } } @@ -893,7 +886,6 @@ mod tests { route: 1, first: Some(Hop::UNKNOWN), local: false, - generation: 0, }; let mut front = serving(candidate, 100); assert_actions( @@ -931,10 +923,9 @@ mod tests { route: 1, first: Some(Hop::UNKNOWN), local: false, - generation: 0, }; let mut front = serving(candidate, 100); - assert_eq!(front.pin(), Pin::Route { id: 1, generation: 0 }); + assert_eq!(front.pin(), Pin::Route(1)); assert_actions( front.step(Event::SourceClosed { source: 100 }), &[Action::Detach { source: 100 }, Action::End { err: Error::Dropped }], diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 0c52db6b754..3850310dc0d 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -737,10 +737,6 @@ struct RouteEntry { /// through it. A broadcast is in the table from creation but serves nobody, /// locally or remotely, until it announces. advertised: bool, - /// Bumped by each update that makes the entry a new source: a first hop - /// that changed, or one that names nobody. An anonymous front serves only - /// the generation it started on. - generation: u64, /// Whether a peer the chain passes through has since withdrawn this prefix. /// The route was derived from that peer's advertisement, so it serves nobody /// until the peer announces again. See [`Dynamic::withdrawn`]. @@ -759,11 +755,6 @@ impl RouteEntry { self.advertised && !self.stale } - /// Whether the first hop names nobody, so no update can prove continuity. - fn first_unknown(&self) -> bool { - self.hops.iter().next().is_none_or(|first| *first == Hop::UNKNOWN) - } - fn is_anonymous(&self) -> bool { self.hops.iter().any(|hop| *hop == Hop::UNKNOWN) } @@ -789,7 +780,8 @@ impl RouteEntry { Pin::Any => true, Pin::Local => self.local, Pin::Publisher(first) => self.hops.iter().next() == Some(&first), - Pin::Route { id, generation } => self.id == id && self.generation == generation && self.first_unknown(), + // An update that names a publisher is a different one, even in place. + Pin::Route(id) => self.id == id && self.hops.iter().next().is_none_or(|first| *first == Hop::UNKNOWN), } } @@ -1733,7 +1725,6 @@ impl Announcing { server: serving.server.clone(), source: serving.source.clone(), advertised: serving.advertised, - generation: 0, stale, claim: claim.clone(), }); @@ -1831,16 +1822,12 @@ impl AnnounceProducer { let Some(entry) = shared.routes.entry_mut(prefix, *id) else { return Err(Error::Closed); }; - // A new first hop is a new publisher, and an unknown one cannot prove it - // is the same: either way a later request goes back to the handler - // rather than joining what was served before. - let first = route.hops.iter().next(); - let unknown = first.is_none_or(|first| *first == Hop::UNKNOWN); - if unknown || entry.hops.iter().next() != first { - entry.generation += 1; - if let Some(server) = &entry.server { - drop(std::mem::take(&mut server.lock().served)); - } + // A new first hop is a new publisher: a later request goes back to the + // handler rather than joining what the old one served. + if entry.hops.iter().next() != route.hops.iter().next() + && let Some(server) = &entry.server + { + drop(std::mem::take(&mut server.lock().served)); } entry.hops = route.hops.clone(); entry.stale = stale; @@ -2342,7 +2329,6 @@ async fn run_front(task: FrontTask) { route: entry.id, first: entry.hops.iter().next().copied(), local: entry.local, - generation: entry.generation, }); let serving_closing = front .serving() @@ -2372,7 +2358,6 @@ async fn run_front(task: FrontTask) { route, first: entry.hops.iter().next().copied(), local: entry.local, - generation: entry.generation, }, entry.source.clone(), entry.server.clone(), @@ -3394,9 +3379,9 @@ impl Dynamic { /// Re-price the route in place: replace its hops and cost. /// /// Consumers observe another active update for the same prefix; sessions - /// forward it as a restart. A new first hop, or an unknown one, is a new - /// source: broadcasts already served drain, and later requests reach the - /// handler again. The prefix is fixed + /// forward it as a restart, so route churn never looks like new content. A + /// new first hop is a new publisher: broadcasts already served from the old + /// one drain, and later requests reach the handler again. The prefix is fixed /// at announce time: to move a route, drop this and call /// [`Producer::dynamic`] again. Fails with [`Error::Closed`] once the origin's /// [`Driver`] has been dropped. @@ -4092,7 +4077,7 @@ impl Consumer { /// announced the route. When its serving source dies or a better qualifying /// route appears, the front re-splices through the best route sharing its /// first hop at a group boundary, invisibly to subscribers. A change that - /// does not preserve a known first hop ends the broadcast instead, as does its + /// does not preserve the first hop ends the broadcast instead, as does its /// route retracting with no replacement, and the next request re-serves the /// path. Tracks already in flight carry on to their own end. /// @@ -6854,25 +6839,14 @@ mod tests { } /// A route updated in place to a new first hop names a new publisher, whether the - /// front started anonymous or named, and an update that leaves the first hop unknown - /// cannot prove it is the same one. Either way the in-flight subscription drains the - /// old copy until it ends and never splices the new one; a new request gets a fresh - /// front through the updated route, free of the old broadcast's track info. + /// front started anonymous or named. The in-flight subscription drains the old copy + /// until it ends and never splices the new one; a new request gets a fresh front + /// through the new publisher, free of the old broadcast's track info. #[tokio::test] - async fn a_new_source_drains_the_old_one() { - let cases: [(&[u64], &[u64]); 6] = [ - (&[], &[11]), - (&[0], &[11]), - (&[10], &[11]), - (&[10], &[0]), - (&[0], &[0]), - (&[], &[]), - ]; - for (first, next) in cases { + async fn a_first_hop_update_drains_the_old_publisher() { + for first in [&[][..], &[0][..], &[10][..]] { let (mut rig, server, _source) = ResumeRig::new(first).await; - server - .update(Route::default().with_hops(hops(next)).with_cost(3)) - .unwrap(); + server.update(Route::default().with_hops(hops(&[11]))).unwrap(); // The old copy keeps flowing to the subscription already reading it. let mut group = rig.incumbent_track.append_group().unwrap(); @@ -6883,7 +6857,7 @@ mod tests { .expect("the in-flight subscription survives the update") .expect("track ended early"); let frame = group.read_frame().await.expect("read frame").expect("frame"); - assert_eq!(&frame.payload[..], b"draining", "{first:?} to {next:?}"); + assert_eq!(&frame.payload[..], b"draining", "first hop {first:?}"); // A new request is a new broadcast from the new publisher, whose track info // differs from what the old front cached. @@ -6902,7 +6876,7 @@ mod tests { let resolved = pending.await.expect("resolves through the new publisher"); assert!( !resolved.is_clone(&rig.resolved), - "{first:?} to {next:?} joined the old front" + "first hop {first:?} joined the old front" ); let mut fresh = resolved .track("video") @@ -6923,7 +6897,7 @@ mod tests { let end = next_group(&mut rig.subscription).await; assert!( !matches!(end, Ok(Some(_))), - "{first:?} to {next:?} spliced the new publisher into a live subscription" + "first hop {first:?} spliced the new publisher into a live subscription" ); } } From 6afea661334139a7771ec42552a6c13cde049b07 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 18:36:50 -0700 Subject: [PATCH 081/128] fix(rs): pass _select seeds to awk via ENVIRON for BSD awk BSD awk (macOS) rejects a newline in a -v value, so the macOS platform job failed on any PR touching two or more crates. Co-Authored-By: Claude Opus 5.5 --- rs/justfile | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/rs/justfile b/rs/justfile index 78834941d2a..8074f2f9d4c 100644 --- a/rs/justfile +++ b/rs/justfile @@ -220,9 +220,10 @@ _select $FILES: ' <<< "$metadata") # A crate has to be rebuilt when anything it depends on changed, so walk the - # edges backwards until the selection stops growing. - selected=$(awk -v seeds="$seeds" ' - BEGIN { split(seeds, s, "\n"); for (i in s) want[s[i]] = 1 } + # edges backwards until the selection stops growing. The seeds go through the + # environment because BSD awk (macOS) rejects a newline in a `-v` value. + selected=$(SEEDS="$seeds" awk ' + BEGIN { split(ENVIRON["SEEDS"], s, "\n"); for (i in s) want[s[i]] = 1 } { pkg[NR] = $1; dep[NR] = $2 } END { do { @@ -409,6 +410,11 @@ _select-test: fail "a moq-relay diff must not drive the media contract: $(just rs _names "$relay")" fi + # Several seeds select all of them, not just the first. + pair=$(just rs _names "$(just rs _select $'rs/moq-auth/src/lib.rs\nrs/moq-hls/src/lib.rs')") + grep -qw moq-auth <<< "$pair" && grep -qw moq-hls <<< "$pair" \ + || fail "a two-crate diff must select both: $pair" + # A crate nested inside another crate's directory is covered by its parent's # seed. Selecting it directly would compile libFuzzer on every moq-net diff, # and its directory name is not its crate name, so it would also mis-report. From e7b7c60b8c9b31c0e617824a80559b5f32a749a4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 18:40:47 -0700 Subject: [PATCH 082/128] feat(net): relays stamp an unknown publisher with a per-connection hop A route whose first hop is 0 or absent (moq-transport without the cluster extension, lite-01..03, or a peer sending 0) gets a random non-zero hop picked once per connection. A legacy publisher's reconnect then reads downstream as a changed first hop, so the only rule left is: a changed first hop is a new source, anything else updates in place. Co-Authored-By: Claude Opus 5.5 --- doc/bin/relay/cluster.md | 6 ++ doc/concept/moq-lite.md | 3 +- drafts/draft-lcurley-moq-cluster.md | 22 +++++--- drafts/draft-lcurley-moq-lite.md | 7 ++- js/net/src/hop.ts | 13 +++++ js/net/src/ietf/subscriber.test.ts | 27 ++++++++- js/net/src/ietf/subscriber.ts | 17 ++++-- js/net/src/lite/subscriber.test.ts | 53 ++++++++++-------- js/net/src/lite/subscriber.ts | 28 ++++++---- rs/moq-net/src/ietf/subscriber.rs | 70 ++++++++++++----------- rs/moq-net/src/lite/subscriber.rs | 80 ++++++++++++++++++--------- rs/moq-net/src/model/origin.rs | 23 +++++++- rs/moq-net/tests/legacy_reconnect.rs | 78 ++++++++++++++++++++++++++ rs/moq-relay/tests/cluster_unknown.rs | 10 ++-- 14 files changed, 323 insertions(+), 114 deletions(-) create mode 100644 rs/moq-net/tests/legacy_reconnect.rs diff --git a/doc/bin/relay/cluster.md b/doc/bin/relay/cluster.md index 8326e6c364d..cc6277febf4 100644 --- a/doc/bin/relay/cluster.md +++ b/doc/bin/relay/cluster.md @@ -35,6 +35,12 @@ Subscriptions already in flight keep draining the old publisher until it ends and are never spliced onto the new one. New requests resolve through the updated route as a fresh broadcast, without the old publisher's track properties. +A publisher whose protocol names no hop (moq-transport without the cluster +extension, moq-lite 01 through 03, or a peer that sends 0) gets a random first +hop from the relay it connects to, fresh for each connection. Its reconnect is +therefore a new publisher downstream, while a reprice on the same connection +stays in place. + ## Topology List the peers each relay dials. That's the whole topology. diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 853a2bd41f9..f6564a079d8 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -65,7 +65,8 @@ that serves only some of the paths beneath its prefix refuses the rest as they are requested. Each route carries the chain of relay identities it passed through, which is how forwarding loops are caught, and a cost, which is how a subscriber picks among several routes to the same broadcast. A hop of 0 is the -anonymous mark and travels the chain unchanged. A route that passed through an +anonymous mark and travels the chain unchanged, except as the first hop: a relay +names an unknown publisher with a random ID fresh per connection. A route that passed through an anonymous hop at any depth ranks below every fully identified route, whatever the costs say; among anonymous routes, cost keeps ordering. diff --git a/drafts/draft-lcurley-moq-cluster.md b/drafts/draft-lcurley-moq-cluster.md index 5d40640cd41..fb7dca90269 100644 --- a/drafts/draft-lcurley-moq-cluster.md +++ b/drafts/draft-lcurley-moq-cluster.md @@ -109,7 +109,7 @@ It stands for an endpoint that did not negotiate this extension, and an endpoint Since any number of endpoints can be 0, it identifies nothing: - **Loop detection**: 0 in a HOP_PATH is never a loop. A receiver whose own Hop ID is 0 cannot detect loops through itself and MUST NOT discard an advertisement merely because the path contains 0. -- **Origin identity**: an advertisement whose first entry is 0 has an unknown publisher. A receiver MUST NOT treat two such advertisements as interchangeable ({{selection}}). +- **Origin identity**: an advertisement whose first entry is 0 has an unknown publisher, which a relay names with a stamp of its own before recording it ({{stamping}}). A receiver MUST NOT treat two unstamped ones as interchangeable ({{selection}}). - **Filtering**: a peer that declared 0 gave the receiver nothing to filter that session on. The receiver MAY assign an ID of its own ({{assigned}}) as local selection state and MUST NOT write it into HOP_PATH. Duplicate *non-zero* Hop IDs in one HOP_PATH are a loop; duplicate zeros are not. @@ -121,14 +121,21 @@ It uses that ID as local selection state: as what it filters that session on, in The ID is the receiver's own, not the peer's, and MUST NOT be forwarded. An advertisement that arrives with its own HOP_PATH already names the sender there, as 0 if withheld. -A receiver writes 0 for an upstream that sent no HOP_PATH ({{bridging}}). +An unnamed publisher is stamped instead ({{stamping}}), which is not an assigned identity. An assigned ID MUST NOT be shared between peers not known to be the same endpoint. -Sharing one makes their content interchangeable ({{selection}}) and suppresses each one's advertisements to the other, so two unrelated publishers would be merged into one and starve each other of routes. +Sharing one suppresses each one's advertisements to the other, so two unrelated peers would starve each other of routes. -A peer the receiver authenticated, or dialed and therefore chose, SHOULD get one stable ID, so its reconnects and redundant sessions are recognized as the same content; a fresh ID per connection would make one peer look like several. +A peer the receiver authenticated, or dialed and therefore chose, SHOULD get one stable ID, so its reconnects and redundant sessions are filtered as one peer; a fresh ID per connection would make one peer look like several. An anonymous accepted session cannot be correlated with anything, so it SHOULD get a distinct ID per session: not an identity, but enough to keep routes learned from it from being advertised back to it, which is the loop 0 cannot prevent. +## Stamping an Unknown Publisher {#stamping} +A relay that records an advertisement whose first HOP_PATH entry is 0, or that arrived with no HOP_PATH ({{bridging}}), MUST replace that entry with a random non-zero Hop ID, picked once for the session the advertisement arrived on. +A 0 anywhere else in HOP_PATH stays. + +Nothing on the wire says whether an unnamed publisher that reconnects is the same one, so a fresh stamp per session makes its reconnect a change of publisher downstream ({{updating}}), while an update on the same session keeps the stamp and applies in place. +A stamp names a session, not a peer: it MUST NOT be reused across sessions or taken as the peer's identity. + # Namespace Advertisements {#namespace} HOP_PATH and ROUTE_COST are Key-Value-Pair parameters ({{moqt}} Section 2.5). @@ -191,7 +198,7 @@ Unknown, out-of-budget, and saturated routes are outside the guarantee: a receiv # Relay Behavior A relay forwarding an advertisement MUST append its own Hop ID to the HOP_PATH it received, so its ID is always the last entry. -A received 0 is forwarded unchanged. +A received 0 is forwarded unchanged, except as the first entry ({{stamping}}). A relay MUST discard an advertisement whose HOP_PATH already contains its own non-zero Hop ID: forwarding it would extend a loop, and subscribing through it would route the relay back to itself. This check catches loops of any length and is the only loop defense required. @@ -199,7 +206,7 @@ A conforming sender never sends one ({{selection}}), so a receiver MAY close the ## Bridging {#bridging} An upstream that did not negotiate the extension sends no HOP_PATH. -The relay creates one with a single 0 entry for that upstream ({{zero}}), then appends its own Hop ID. +The relay creates one holding only its stamp for that session ({{stamping}}), then appends its own Hop ID. The identity a receiver assigned that upstream ({{assigned}}) is local selection state and MUST NOT appear in HOP_PATH. ## Accumulating Cost {#accumulating} @@ -228,7 +235,7 @@ An advertisement lives as long as its stream, so an update on a new stream would An endpoint MUST NOT open a second stream for an advertisement it already maintains on the session. An update replaces the old parameters atomically, so a receiver MUST NOT tear down subscriptions or drop cached state because one arrived. -If the first HOP_PATH entry is unchanged the content is continuous and subscriptions MAY resume on the new route at a group boundary, even when that entry is 0: there is one advertisement, and its stream is the continuity. +If the first HOP_PATH entry is unchanged the content is continuous and subscriptions MAY resume on the new route at a group boundary. If the first entry changed, the publisher changed, and the endpoint still sends an ordinary update. The receiver keeps each subscription it is already serving on the old source until that source ends, MUST NOT resume or splice it onto the updated route, and serves new requests from the updated route without state cached from the old publisher. @@ -332,6 +339,7 @@ This document requests one registration in the "REQUEST_ERROR Codes" registry. - Defined request resolution against the longest covering prefix and the NO_CAPACITY refusal with its single re-resolution; any other refusal is terminal, including between several publishers of one namespace. - A relay does not advertise a namespace because it resolved it; the publisher advertises the concrete namespace once producing. - A change of original publisher is an ordinary update instead of a withdrawal and a new advertisement. Subscriptions already served drain the old source; new requests take the updated route. +- A relay stamps an advertisement whose first HOP_PATH entry is 0, or that has no HOP_PATH, with a random Hop ID picked per session, instead of recording 0. ## moq-cluster-01 - Assigned identities are local selection state and MUST NOT be forwarded. diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index ccec40d32c9..95eaa7ecd28 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -408,6 +408,8 @@ This is the only loop defense moq-lite requires, and it catches loops of any len A conforming sender never sends one (see below), so a receiver MAY instead close the session with a protocol violation; discarding is what keeps a mesh working when one member does not conform. A Hop ID of 0 means unknown and never matches anything; withholding an ID trades loop detection for privacy. A receiver MAY assign an identity of its own to a peer that declared 0, as local selection state for filtering that session; it MUST NOT forward that identity as a Hop ID. +A relay that records an announcement whose reconstructed path is empty or starts with 0 MUST replace that first entry with a random non-zero Hop ID, picked once for the session it arrived on. +Nothing on the wire says whether an unnamed publisher that reconnects is the same one, so its reconnect reads downstream as a new first hop, while an ANNOUNCE_UPDATE on the same session keeps the stamp. A publisher MUST NOT advertise a path whose entries contain the Hop ID the subscriber declared in its SETUP (see [Hop Parameter](#hop-parameter)). The receiver can only discard it, and acting on it would form a loop, so sending one is never useful. @@ -912,8 +914,8 @@ The responding publisher's own Hop ID is NOT included in the resolved list; it i When forwarding an announcement received from an upstream peer, a relay MUST append the upstream peer's ANNOUNCE_OK `Hop ID` to the resolved list, since that ID is no longer implicit downstream. The first entry of the reconstructed path identifies the endpoint that originated the route. A Hop ID value of 0 means the hop is unknown: either it was never assigned or a relay deliberately withholds it (see [Routing](#routing)). -A received 0 is forwarded unchanged. -When bridging an announcement from an upstream that sent no hop list, a relay writes 0 for that hop. +A received 0 is forwarded unchanged, except as the first entry, which a relay stamps (see [Routing](#routing)). +When bridging an announcement from an upstream that sent no hop list, a relay writes its stamp for that hop. An identity a receiver assigned that upstream is local selection state and MUST NOT be forwarded as a Hop ID. A receiver MUST close the session with a PROTOCOL_VIOLATION if a non-zero Hop ID appears twice in the resolved list. @@ -1343,6 +1345,7 @@ The `Message Length` describes the payload size on the wire. - The Subscribe Stream FIN now follows once every counted Group Stream has finished or been reset. - Added announce compression: ANNOUNCE_START gains `Path Base` and `Path Keep` to copy the head of a live advertisement's suffix, and ANNOUNCE_START and ANNOUNCE_UPDATE gain `Hop Base` and `Hop Keep` to copy the tail of a live advertisement's Hop ID list. - Capped the SETUP Message Length at 65,536 bytes. +- A relay stamps an announcement whose reconstructed path is empty or starts with 0 with a random Hop ID picked per session, instead of recording 0. ## moq-lite-06 diff --git a/js/net/src/hop.ts b/js/net/src/hop.ts index cbb2c0d1cfc..85ce8cab478 100644 --- a/js/net/src/hop.ts +++ b/js/net/src/hop.ts @@ -66,6 +66,19 @@ export function randomHop(): Hop { return HopSchema.parse(raw === 0n ? 1n : raw); } +/** + * Name an unknown original publisher: fill an empty chain, or replace a first entry of 0, + * with `stamp`, the receiving connection's own random id. A publisher that reconnects then + * reads downstream as a new first hop. `undefined` if `stamp` already appears later in the + * chain. Mirrors `Hops::stamp` in rs/moq-net. + */ +export function stampHops(hops: readonly Hop[], stamp: Hop): Hop[] | undefined { + if (hops.length === 0) return [stamp]; + if (hops[0] !== UNKNOWN_HOP) return [...hops]; + if (hops.includes(stamp)) return undefined; + return [stamp, ...hops.slice(1)]; +} + /** * What pulling content via a route costs, in two magnitudes accumulated together * and compared in that order: lower {@link Cost.warm} wins, and {@link Cost.cold} diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index 18968dbe625..698272d83f9 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -1,7 +1,7 @@ import { expect, spyOn, test } from "bun:test"; import type * as announce from "../announced.ts"; import { ProtocolViolation, StreamCode, Stream as StreamError } from "../error.ts"; -import { type Hop, HopSchema } from "../hop.ts"; +import { type Hop, HopSchema, UNKNOWN_HOP } from "../hop.ts"; import { createMockTransportPair } from "../mock.ts"; import * as Path from "../path.ts"; import { Reader, Stream } from "../stream.ts"; @@ -101,6 +101,31 @@ test("an unsolicited announcement lands", async () => { }); }); +/** + * A session without the Cluster extension names no publisher, so each connection stamps its + * own random Hop ID as the first hop: a publisher that reconnects reads as a new one. + */ +test("an advertisement with no path is stamped per connection", async () => { + const stamp = async () => { + const pair = createMockTransportPair(ALPN.DRAFT_19); + const subscriber = new Subscriber({ session: new NativeSession(pair.server, VERSION, true) }); + const announced = subscriber.announced(); + expect(await nextStream(pair.client)).toBeDefined(); + + const stream = await Stream.open(pair.server, { version: VERSION }); + void subscriber.runPublishNamespace( + new PublishNamespace({ requestId: 0n, trackNamespace: Path.from("legacy") }), + stream, + ); + const hops = (await announced.next())?.route.hops ?? []; + expect(hops).toHaveLength(1); + expect(hops[0]).not.toBe(UNKNOWN_HOP); + return hops[0]; + }; + + expect(await stamp()).not.toBe(await stamp()); +}); + /** * Answer the SUBSCRIBE_NAMESPACE the subscriber just opened, then hand back its stream so * the test can feed inline NAMESPACE entries down it. diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index 3e727bf8335..aaf0ea5aadf 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -4,7 +4,7 @@ import * as broadcast from "../broadcast.ts"; import { BroadcastCache } from "../consume.ts"; import { closeError, controlTimeout, error, ProtocolViolation, reason, sessionCause } from "../error.ts"; import * as netGroup from "../group.ts"; -import { Cost, type Route, routesEqual, UNKNOWN_HOP } from "../hop.ts"; +import { Cost, type Route, randomHop, routesEqual, stampHops } from "../hop.ts"; import { hiddenBelow, hooks, scopeCaptures, scopeHead, scopeOverlaps } from "../internal.ts"; import * as Path from "../path.ts"; import type { Cursor, Reader, Stream } from "../stream.ts"; @@ -117,6 +117,10 @@ export class Subscriber { // Dedup consumed broadcasts per path: repeat consume() calls share one subscription. #consumes = new BroadcastCache(); + // A random Hop ID of this connection's own, written as the first hop of any path that + // names no publisher, so a publisher that reconnects reads as a new one. + #stamp = randomHop(); + // Paths with a legacy PUBLISH_NAMESPACE request in flight, reserved synchronously. // The count below is only taken once the OK is written, and two requests that both // got past the duplicate check before either attached would both take one. @@ -175,10 +179,15 @@ export class Subscriber { return advert !== undefined && this.#cluster !== undefined && Cluster.loops(advert, this.#cluster.self); } - /** The route an advertisement carries; one without a path is anonymous and free. */ + /** + * The route an advertisement carries; one without a path is free. A path that names no + * publisher, or none at all, is named by this connection's stamp. + */ #route(advert: Cluster.Advert | undefined): Route { - if (advert === undefined) return { hops: [UNKNOWN_HOP], cost: Cost.zero }; - return { hops: advert.hops, cost: { warm: advert.cost, cold: advert.cost } }; + if (advert === undefined) return { hops: [this.#stamp], cost: Cost.zero }; + // A stamp colliding with a later entry is a 1-in-2^53 draw: keep the path as sent. + const hops = stampHops(advert.hops, this.#stamp) ?? [...advert.hops]; + return { hops, cost: { warm: advert.cost, cold: advert.cost } }; } /** diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index e401d509330..3843556e9ce 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -184,26 +184,32 @@ test("an unidentified responder keeps hop 0 on a nonempty chain", async () => { subscriber.close(); }); -test("a received empty hop list is filled with hop 0 and marked anonymous", async () => { - const { subscriber, send, settle } = announceHarness(Version.DRAFT_06); - const announced = subscriber.announced(); - await settle(); +test("a received hop list naming no publisher is stamped per connection", async () => { + const first = async () => { + const { subscriber, send, settle } = announceHarness(Version.DRAFT_06); + const announced = subscriber.announced(); + await settle(); + + await send((w) => new AnnounceOk(UNKNOWN_HOP, 0).encode(w, Version.DRAFT_06)); + await send((w) => + encodeAnnounceBroadcast(w, { status: "active", suffix: Path.from("room"), hops: [] }, Version.DRAFT_06), + ); + const update = await announced.next(); + expect(update).toMatchObject({ prefix: Path.from("room"), kind: "announced" }); + const hops = update?.route.hops ?? []; + expect(hops).toHaveLength(1); + expect(hops[0]).not.toBe(UNKNOWN_HOP); - await send((w) => new AnnounceOk(UNKNOWN_HOP, 0).encode(w, Version.DRAFT_06)); - await send((w) => - encodeAnnounceBroadcast(w, { status: "active", suffix: Path.from("room"), hops: [] }, Version.DRAFT_06), - ); - expect(await announced.next()).toMatchObject({ - prefix: Path.from("room"), - kind: "announced", - route: { hops: [UNKNOWN_HOP] }, - }); + announced.close(); + subscriber.close(); + return hops[0]; + }; - announced.close(); - subscriber.close(); + // A reconnect is a new connection, so the same unnamed publisher reads as a new one. + expect(await first()).not.toBe(await first()); }); -test("a received chain with hop 0 is marked anonymous", async () => { +test("a received chain starting with hop 0 has only its first entry stamped", async () => { const { subscriber, send, settle } = announceHarness(Version.DRAFT_06); const announced = subscriber.announced(); await settle(); @@ -216,10 +222,11 @@ test("a received chain with hop 0 is marked anonymous", async () => { Version.DRAFT_06, ), ); - expect(await announced.next()).toMatchObject({ - prefix: Path.from("room"), - kind: "announced", - }); + const update = await announced.next(); + expect(update).toMatchObject({ prefix: Path.from("room"), kind: "announced" }); + const [stamp, ...rest] = update?.route.hops ?? []; + expect(stamp).not.toBe(UNKNOWN_HOP); + expect(rest).toEqual([PUBLISHER_A, PEER]); announced.close(); subscriber.close(); @@ -343,9 +350,9 @@ test("a lite-05 duplicate announce follows the same restart rule", async () => { }); // A responder that withholds its Hop ID sends the reserved 0, and an empty chain means it -// originated the path itself, so the advertisement names nobody. A restart of it is still the -// one advertisement, whose stream is the continuity, so it updates in place like Rust's and -// keeps the shared broadcast. Only a first hop that changes names a new publisher. +// originated the path itself, so the advertisement names nobody and the connection stamps it. +// A restart on the same connection keeps that stamp, so it is a reprice that updates in place +// and keeps the shared broadcast. Only a first hop that changes names a new publisher. test("a restart from an unidentified publisher updates in place", async () => { const { subscriber, send, settle } = announceHarness(Version.DRAFT_06); const announced = subscriber.announced(); diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 567d06475f1..9fe819432f1 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -5,7 +5,7 @@ import type { Probe as ProbeStats } from "../connection/stats.ts"; import { BroadcastCache } from "../consume.ts"; import { controlTimeout, error, ProtocolViolation, reason, StreamCode, StreamError, sessionCause } from "../error.ts"; import * as netGroup from "../group.ts"; -import { Cost, type Hop, MAX_HOPS, type Route, routesEqual, UNKNOWN_HOP } from "../hop.ts"; +import { Cost, type Hop, MAX_HOPS, type Route, randomHop, routesEqual, stampHops } from "../hop.ts"; import { groupBounds, hiddenBelow, scopeCaptures, scopeHead, scopeOverlaps } from "../internal.ts"; import * as Path from "../path.ts"; import { type OpenOptions, type Reader, Stream } from "../stream.ts"; @@ -134,6 +134,10 @@ export class Subscriber { // Dedup consumed broadcasts per path: repeat consume() calls share one subscription. #consumes = new BroadcastCache(); + // A random Hop ID of this connection's own, written as the first hop of any chain that + // names no publisher, so a publisher that reconnects reads as a new one. + #stamp: Hop; + // Dedup in-flight one-shot fetches, keyed by [broadcast, track, sequence]. Concurrent (or // repeat, while still open) fetchGroup() calls for the same group share one FETCH stream and // each get an independent mirror; the entry is evicted once the group closes. @@ -168,6 +172,7 @@ export class Subscriber { this.#quic = quic; this.version = version; this.hop = hop; + this.#stamp = randomHop(); this.#probe = probe; this.#peerSetup = peerSetup; } @@ -262,16 +267,16 @@ export class Subscriber { // they go on record and obey the same one-per-path rule: the initial set // naming a path twice is the same violation as two ANNOUNCE_STARTs for it, // and the record is what catches either. Draft01/02 carry no hop ids and no - // ANNOUNCE_OK, so nothing names the publisher. + // ANNOUNCE_OK, so this connection's stamp names the publisher. for (const suffix of init.suffixes) { const path = Path.join(prefix, suffix); if (advertised.has(path)) { throw new ProtocolViolation(`duplicate announce for ${path}`); } - const route = { hops: [UNKNOWN_HOP], cost: Cost.zero }; + const route = { hops: [this.#stamp], cost: Cost.zero }; const live = visible(path); const captures = scopeCaptures(scope, path); - advertised.set(path, { publisher: undefined, live, route, captures }); + advertised.set(path, { publisher: this.#stamp, live, route, captures }); if (!live) continue; console.debug(`announced: broadcast=${path} active=true`); announced.append({ prefix: path, captures, kind: "announced", route }); @@ -398,17 +403,17 @@ export class Subscriber { } // The first hop identifies the original publisher; an empty chain means the - // peer itself originated it. - const publisher = hops?.[0] ?? responderOrigin; - const fullHops = + // peer itself originated it. One that names nobody (lite-01..03, or a peer + // reporting 0) is named by this connection's stamp. + const fullHops = stampHops( hops !== undefined && responderOrigin !== undefined ? [...hops, responderOrigin] - : [...(hops ?? [])]; - // A received empty list is the anonymous mark, not a local announcement. - if (fullHops.length === 0) fullHops.push(UNKNOWN_HOP); + : [...(hops ?? [])], + this.#stamp, + ); // Appending a withheld AnnounceOk(0) onto a 32-entry list is the same // drop Rust's Hops::push makes: do not expose an overlong chain. - if (fullHops.length > MAX_HOPS) { + if (fullHops === undefined || fullHops.length > MAX_HOPS) { console.debug(`announced: broadcast=${path} dropped (hop chain at MAX_HOPS)`); advertised.set(path, { publisher: undefined, @@ -418,6 +423,7 @@ export class Subscriber { }); continue; } + const publisher = fullHops[0]; const route: Route = { hops: fullHops, cost: cost ?? Cost.zero }; const captures = scopeCaptures(scope, path); if (!visible(path)) { diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 53834b661e2..033239cb999 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -429,6 +429,10 @@ pub(super) struct Subscriber { // that withheld an identity is not named on the wire. A server answers it per // accepted session; a client only when it knows the peer. session_origin: crate::Hop, + // A random Hop ID of this connection's own, written as the first hop of any path + // that arrives naming no publisher, so a publisher that reconnects reads downstream + // as a new one. Fresh per connection, unlike `session_origin`. + stamp: crate::Hop, // Our own Hop ID, which an advertisement must not already contain: one that does // looped back through us. self_origin: crate::Hop, @@ -501,6 +505,7 @@ where origin, control, session_origin: peer_hop.unwrap_or(crate::Hop::UNKNOWN), + stamp: crate::Hop::random(), self_origin, peer_setup, cost, @@ -553,10 +558,10 @@ where /// The route for an advertisement that carries no path of its own. /// - /// Base moq-transport has no hops on the wire, so the chain is a single 0: the - /// anonymous mark, forwarded unchanged. The session's assigned identity stays - /// on `via` for split-horizon; putting it in the chain would publish a name for - /// a peer that declined to give one. + /// Base moq-transport has no hops on the wire, so the chain is this connection's + /// stamp alone, naming the unknown publisher for as long as the connection lasts. + /// The session's assigned identity stays on `via` for split-horizon; putting it in + /// the chain would publish a name for a peer that declined to give one. /// /// The link is charged all the same. Such an advertisement carries no ROUTE_COST, /// which reads as 0, but the draft charges every advertisement for the direction it @@ -565,12 +570,10 @@ where /// /// It is charged only one hop, though the chain it stands for may be arbitrarily /// long: a peer that carries no hop ids hides its depth, so this route understates - /// its true length. An anonymous route already ranks below every identified one, - /// so that understatement cannot beat a real path. Price such a link with - /// [`crate::Client::with_cost`] among other anonymous routes. + /// its true length. Price such a link with [`crate::Client::with_cost`]. fn session_route(&self, peer: &cluster::Peer) -> crate::origin::Route { let mut hops = crate::Hops::new(); - hops.push(crate::Hop::UNKNOWN) + hops.push(self.stamp) .expect("an empty hop chain has room for one entry"); crate::origin::Route::default() .with_hops(hops) @@ -584,8 +587,9 @@ where /// /// A negotiated peer supplies the path and cost, so the route is what the mesh /// actually knows: the full chain, and the accumulated cost plus this link's price. - /// A received 0 stays 0. An advertisement whose path already contains our own Hop - /// ID looped back, and neither forwarding it nor subscribing through it is safe. + /// A first entry of 0 is replaced by this connection's stamp; a 0 anywhere else + /// stays. An advertisement whose path already contains our own Hop ID looped back, + /// and neither forwarding it nor subscribing through it is safe. fn route(&self, advert: Option<&cluster::Advert>, peer: &cluster::Peer) -> Option { let Some(advert) = advert else { return Some(Advertised { @@ -597,11 +601,11 @@ where return None; } - Some(Advertised { - route: advert - .route(cluster::link_cost(self.cost, peer)) - .with_via(self.via(peer)), - }) + let mut route = advert + .route(cluster::link_cost(self.cost, peer)) + .with_via(self.via(peer)); + route.hops.stamp(self.stamp).ok()?; + Some(Advertised { route }) } /// Bind the alias the publisher chose for this subscription. @@ -4104,9 +4108,9 @@ mod tests { assert!(!table.map.contains_key(&0), "the oldest tombstone is forgotten first"); } - /// moq-transport carries no hop ids, so a peer's broadcasts are marked - /// anonymous (hop 0). An identity assigned via `Client::with_peer_hop` is - /// stored as `via` for split-horizon and never written into the chain. + /// moq-transport carries no hop ids, so a peer's broadcasts are named by the + /// connection's own random stamp. An identity assigned via `Client::with_peer_hop` + /// is stored as `via` for split-horizon and never written into the chain. #[tokio::test] async fn assigned_peer_hop_attributes_announces() { let session = crate::lite::test_transport::SinkSession::new(Default::default()); @@ -4137,8 +4141,9 @@ mod tests { let mut announced = consumer.announced(); let route = announced.assert_next_active("room/host"); let hops: Vec<_> = route.hops.iter().copied().collect(); - assert_eq!(hops, vec![crate::Hop::UNKNOWN]); - assert!(route.is_anonymous()); + assert_eq!(hops, vec![subscriber.stamp]); + assert_ne!(subscriber.stamp, crate::Hop::UNKNOWN); + assert_ne!(subscriber.stamp, assigned, "the assigned identity stays off the chain"); let mut hidden = consumer.excluding(assigned).announced(); hidden.assert_next_wait(); @@ -4201,11 +4206,11 @@ mod tests { assert_eq!(route.hops, upstream); } - /// Two sessions assigned the same identity announce the same anonymous chain. - /// The cursor treats that as an identical re-announce, so a reconnect is - /// invisible and retracting the stale session leaves the fresh route standing. + /// Two sessions assigned the same identity still stamp their own first hop, since + /// a wire with no hop ids cannot say the content continued: the reconnect reads as a + /// new source, while split-horizon keeps filtering on the shared identity. #[tokio::test] - async fn reconnecting_peer_joins_the_front_it_replaces() { + async fn reconnecting_peer_is_a_new_first_hop() { let peer = crate::Hop::new(777).unwrap(); let self_origin = crate::Hop::new(1).unwrap(); @@ -4237,17 +4242,18 @@ mod tests { }; let first = connect(); - announced.assert_next_active("room/host"); + let first_stamp = first.stamp; + let route = announced.assert_next_active("room/host"); + assert_eq!(route.hops.iter().next(), Some(&first_stamp)); - // The peer reconnects before the old session is retired: an identical route - // from the fresh session joins without any consumer-visible churn. - let _second = connect(); - announced.assert_next_wait(); + // The peer reconnects before the old session is retired, under its own stamp. + let second = connect(); + assert_ne!(second.stamp, first_stamp); + assert!(routed_now(&consumer, "room/host").is_some()); - // The stale session finally retracting leaves the fresh route standing. + // Neither route is offered back to the peer they both came from. + consumer.excluding(peer).announced().assert_next_wait(); drop(first); - announced.assert_next_wait(); - assert!(routed_now(&consumer, "room/host").is_some()); } fn cluster_subscriber( diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index a648b2f2c84..a2b07445ff1 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -69,6 +69,11 @@ pub(super) struct Subscriber { // another session's, while a client only assigns one it knows out of band. The // assigned id stays local and is never written into a hop chain. session_origin: crate::Hop, + // A random Hop ID of this connection's own, written as the first hop of any chain + // that names no publisher (Lite01/02, a Lite03 placeholder, or a peer reporting 0), + // so a publisher that reconnects reads downstream as a new one. Fresh per + // connection, unlike `session_origin`. + stamp: crate::Hop, subscribes: Lock>, /// Why this session ended, once it has. A track still waiting on TRACK_INFO is /// not in [`Self::subscribes`], so dropping its request reads this instead of @@ -110,6 +115,7 @@ impl Subscriber { recv_bandwidth: config.recv_bandwidth, self_origin, session_origin: config.peer_hop.unwrap_or(crate::Hop::UNKNOWN), + stamp: crate::Hop::random(), subscribes: Default::default(), ended: Default::default(), next_id: Default::default(), @@ -306,13 +312,12 @@ impl Subscriber { return Ok(false); } - // Lite03 carries its hop count as UNKNOWN placeholders rather than real - // ids; they stay 0 and count as anonymous. Lite01/02 send no list at all. - // Either way the chain must have at least the anonymous mark so a - // downstream hop can see that this path passed through an unidentified hop. - if hops.is_empty() { - hops.push(crate::Hop::UNKNOWN) - .expect("an empty hop chain always has room for one entry, and repeats nothing"); + // Lite01/02 send no list at all, and Lite03 carries only UNKNOWN placeholders, + // so the publisher may be unnamed: this connection's stamp names it. Later + // placeholders stay 0 and count as anonymous. + if hops.stamp(self.stamp).is_err() { + tracing::debug!(route = %self.log_path(&path), "dropping announce; stamp already in the chain"); + return Ok(false); } tracing::debug!(route = %self.log_path(&path), hops = hops.len(), "announce"); @@ -405,9 +410,11 @@ impl Subscriber { return Ok(false); } - if hops.is_empty() { - hops.push(crate::Hop::UNKNOWN) - .expect("an empty hop chain always has room for one entry, and repeats nothing"); + // Named by this connection's stamp when the chain names no publisher, exactly as + // the announce was, so a restart of the same unnamed publisher stays in place. + if hops.stamp(self.stamp).is_err() { + announced.declined(path); + return Ok(false); } tracing::debug!(route = %self.log_path(&path), hops = hops.len(), "restart"); @@ -2477,8 +2484,9 @@ mod tests { ); } - /// A peer that declares no identity is marked anonymous (hop 0). The assigned - /// identity stays on `via` for split-horizon and is never written into the chain. + /// A peer that declares no identity has its publisher named by the connection's + /// stamp. The assigned identity stays on `via` for split-horizon and is never + /// written into the chain. #[tokio::test] async fn assigned_peer_hop_attributes_announces() { let session = SinkSession::new(Default::default()); @@ -2513,19 +2521,20 @@ mod tests { .unwrap(); assert!(accepted); - // The route is announced synchronously: hop 0 on the wire, assigned id local. + // The route is announced synchronously: the stamp in the chain, assigned id local. let mut cursor = consumer.announced(); let route = cursor.assert_next_active("room/host"); let hops: Vec<_> = route.hops.iter().copied().collect(); - assert_eq!(hops, vec![crate::Hop::UNKNOWN]); - assert!(route.is_anonymous()); + assert_eq!(hops, vec![subscriber.stamp]); + assert_ne!(subscriber.stamp, assigned); let mut hidden = consumer.excluding(assigned).announced(); hidden.assert_next_wait(); } - /// Lite03 hop-count placeholders stay 0 and count as anonymous; they are not - /// rewritten with the assigned identity. + /// Lite03 hop-count placeholders name nobody, so the first is replaced by the + /// connection's stamp; the rest stay 0 and count as anonymous. None is rewritten with + /// the assigned identity. #[tokio::test] async fn lite03_placeholders_stay_anonymous() { let assigned = crate::Hop::new(777).unwrap(); @@ -2561,26 +2570,28 @@ mod tests { let mut cursor = consumer.announced(); let route = cursor.assert_next_active("room/host"); let hops: Vec<_> = route.hops.iter().copied().collect(); - assert_eq!(hops, vec![crate::Hop::UNKNOWN, crate::Hop::UNKNOWN]); + assert_eq!(hops, vec![subscriber.stamp, crate::Hop::UNKNOWN]); assert!(route.is_anonymous()); } - /// A peer with no assigned identity is attributed the reserved origin 0 - /// (UNKNOWN). This layer never mints one of its own: whether an anonymous peer - /// gets an identity, and whether two of its sessions share it, is the caller's - /// policy, and a minted id here would be indistinguishable from a declared one. + /// A publisher that names nobody is stamped with a random id fresh per connection, + /// never 0: a restart on the same connection keeps the stamp and updates in place, + /// while the same publisher reconnecting reads as a new first hop. #[tokio::test] - async fn absent_peer_hop_stamps_unknown() { - let (mut subscriber, consumer) = restart_subscriber(SinkSession::new(Default::default())); + async fn an_unnamed_publisher_is_stamped_per_connection() { + let (mut first, consumer) = restart_subscriber(SinkSession::new(Default::default())); + let (second, _) = restart_subscriber(SinkSession::new(Default::default())); + assert_ne!(first.stamp, crate::Hop::UNKNOWN); + assert_ne!(first.stamp, second.stamp, "each connection stamps its own id"); let mut announced = Announced::default(); - subscriber + first .start_announce( Path::new("room/host").to_owned(), crate::Hops::new(), crate::origin::Cost::UNKNOWN, 0, - None, + Some(crate::Hop::UNKNOWN), &mut announced, ) .unwrap(); @@ -2588,7 +2599,22 @@ mod tests { let mut cursor = consumer.announced(); let route = cursor.assert_next_active("room/host"); let hops: Vec<_> = route.hops.iter().copied().collect(); - assert_eq!(hops, vec![crate::Hop::UNKNOWN]); + assert_eq!(hops, vec![first.stamp]); + + // A reprice from the same unnamed publisher keeps the stamp, so it stays in place. + first + .restart_announce( + Path::new("room/host").to_owned(), + crate::Hops::new(), + crate::origin::Cost::UNKNOWN, + 4, + Some(crate::Hop::UNKNOWN), + &mut announced, + ) + .unwrap(); + let route = cursor.assert_next_active("room/host"); + let hops: Vec<_> = route.hops.iter().copied().collect(); + assert_eq!(hops, vec![first.stamp]); } fn restart_subscriber(session: SinkSession) -> (Subscriber, crate::origin::Consumer) { diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 3850310dc0d..bbe7c2434f4 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -265,6 +265,26 @@ impl Hops { Ok(()) } + /// Name an unknown original publisher: fill an empty chain, or replace a first + /// entry of 0, with `stamp`, the receiving session's own per-connection id. + /// + /// A publisher that reconnects then reads downstream as a new first hop, which is + /// all anyone can say about it. Fails with [`InvalidHop::Duplicate`] if `stamp` + /// already appears later in the chain. + pub(crate) fn stamp(&mut self, stamp: Hop) -> Result<(), InvalidHop> { + match self.0.first() { + None => self.push(stamp), + Some(first) if *first == Hop::UNKNOWN => { + if self.0[1..].contains(&stamp) { + return Err(InvalidHop::Duplicate); + } + self.0[0] = stamp; + Ok(()) + } + Some(_) => Ok(()), + } + } + /// Returns true if any entry matches `hop`. pub fn contains(&self, hop: &Hop) -> bool { self.0.contains(hop) @@ -456,7 +476,8 @@ pub struct Route { /// The chain of origins the route has traversed, oldest first. Each relay /// appends its own [`crate::Hop`] when forwarding; used for loop detection /// and as the selection tie-break. A 0 entry is the anonymous mark and - /// travels unchanged; see [`Self::is_anonymous`]. + /// travels unchanged, except as the first entry, which a session receiving + /// it replaces with its own per-connection stamp; see [`Self::is_anonymous`]. pub hops: Hops, /// What pulling content via this route costs, accumulated per link: lower wins diff --git a/rs/moq-net/tests/legacy_reconnect.rs b/rs/moq-net/tests/legacy_reconnect.rs new file mode 100644 index 00000000000..8376f24dee8 --- /dev/null +++ b/rs/moq-net/tests/legacy_reconnect.rs @@ -0,0 +1,78 @@ +//! A publisher on a wire with no hop ids, reconnecting through a relay, is a new source +//! downstream. +//! +//! moq-transport without the Cluster extension names no publisher, so the relay it +//! connects to stamps each connection with a random Hop ID of its own. A reconnect is a +//! new connection and so a new first hop, which a downstream relay reads as a new +//! source rather than splicing it onto the old one. + +mod support; + +use std::time::Duration; + +use moq_net::{Hop, Version, announce, origin}; +use support::harness::{MockConnectOptions, MockPair, connect_mock, peer}; + +const TEST_TIMEOUT: Duration = Duration::from_secs(10); +const PATH: &str = "room/cam"; + +fn produce_origin(hop: u64) -> origin::Producer { + let (producer, driver) = origin::Producer::new(origin::Config::new(Hop::new(hop).unwrap())); + tokio::spawn(support::harness::run(driver)); + producer +} + +/// Connect `publisher` to `relay` over draft-14, which carries no hop ids. +async fn connect_legacy(publisher: &origin::Producer, relay: &origin::Producer) -> MockPair { + let mut options = MockConnectOptions::new("moq-transport-14".parse::().unwrap()); + options.client_publish = Some(publisher.consume()); + options.server_subscribe = Some(relay.clone()); + connect_mock(options).await +} + +/// The first hop of the next active update for [`PATH`]. A withdrawal in between is +/// skipped: whether the relay saw the new connection before the old one dropped is a +/// race, and either way the path comes back. +async fn next_first_hop(announced: &mut announce::Consumer) -> Hop { + loop { + let update = announced.next().await.expect("announce cursor ended"); + if update.prefix.as_str() != PATH || !update.kind.is_active() { + continue; + } + return *update.route.hops.iter().next().expect("a route names its first hop"); + } +} + +#[tokio::test] +async fn a_legacy_reconnect_is_a_new_first_hop_downstream() { + for mesh in ["moq-lite-06", "moq-transport-17"] { + tokio::time::timeout(TEST_TIMEOUT, async { + let publisher = produce_origin(9); + let relay = produce_origin(1); + let downstream = produce_origin(2); + let _mesh = peer(mesh.parse::().unwrap(), &relay, &downstream).await; + let mut announced = downstream.consume().announced(); + + let broadcast = publisher.create_broadcast(PATH).unwrap(); + broadcast.announce(Default::default()).unwrap(); + + let first = connect_legacy(&publisher, &relay).await; + let before = next_first_hop(&mut announced).await; + assert_ne!(before, Hop::UNKNOWN, "{mesh}: the relay stamps an unnamed publisher"); + assert_ne!(before, Hop::new(9).unwrap(), "{mesh}: draft-14 never carried the id"); + + // The publisher reconnects: the same content, but nothing on the wire says so. + let second = connect_legacy(&publisher, &relay).await; + drop(first); + let mut after = next_first_hop(&mut announced).await; + while after == before { + after = next_first_hop(&mut announced).await; + } + assert_ne!(after, Hop::UNKNOWN, "{mesh}: the relay stamps the new connection too"); + + drop(second); + }) + .await + .expect("test timed out"); + } +} diff --git a/rs/moq-relay/tests/cluster_unknown.rs b/rs/moq-relay/tests/cluster_unknown.rs index 5409b85818a..8bad8f13a8a 100644 --- a/rs/moq-relay/tests/cluster_unknown.rs +++ b/rs/moq-relay/tests/cluster_unknown.rs @@ -1,6 +1,6 @@ //! Regression for an external publisher whose protocol does not declare a Hop ID. -//! The relay records that publisher as `Hop::UNKNOWN`; reflected cluster paths -//! must not replace it while gossiping around a redundant mesh. +//! The relay stamps that publisher with a random Hop ID of the connection's own; +//! reflected cluster paths must not replace it while gossiping around a redundant mesh. use std::time::Duration; @@ -105,8 +105,8 @@ async fn publish_version(port: u16, version: &str) -> Publisher { } async fn publish_unknown(port: u16) -> Publisher { - // Draft-14 has no Cluster extension, so the accepting relay must represent - // this external publisher with the wire-defined UNKNOWN Hop ID. + // Draft-14 has no Cluster extension, so the accepting relay must name this + // external publisher with a stamp of its own. publish_version(port, "moq-transport-14").await } @@ -226,7 +226,7 @@ async fn assert_unknown_publisher_stays_announced(cluster_version: Option Date: Tue, 29 Sep 2026 19:00:06 -0700 Subject: [PATCH 083/128] fix(net): re-resolve a splice successor on every judgment An unstamped successor aborted or evicted before its first frame left the cached anchor naming a dead group, so a read parked at the previous group's tail stayed unbounded. The anchor now holds the successor query and re-resolves it across the later segments each time, registering on the splice state, the consulted tracks, and an unstamped group's first frame. Co-Authored-By: Claude Opus 5.5 --- doc/concept/moq-lite.md | 3 +- rs/moq-net/src/model/resume.rs | 179 +++++++++++++++++++++++++++------ rs/moq-net/src/model/track.rs | 166 +++++++----------------------- 3 files changed, 187 insertions(+), 161 deletions(-) diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 6dc19feef3a..b17b0c30a6f 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -227,7 +227,8 @@ publisher only ever sees the most tolerant budget across its subscribers. Across a native route failover, the reader still judges buffered groups against the logical track's live edge, including groups it is draining from a retired route. A successor group with no timestamp leaves the preceding group's reach -unbounded until its first frame arrives. A cached open group's prefix remains +unbounded until its first frame arrives; if it is dropped first, the next group +takes its place. A cached open group's prefix remains readable across repeated takeovers and idle resumes. The publisher declares a retention window per track, which bounds how far back diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 307843f1309..089c361fafc 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -26,10 +26,8 @@ use std::collections::{BTreeMap, HashSet}; use std::ops::Bound; use std::task::{Poll, ready}; -#[cfg(test)] -use crate::Timestamp; -use crate::{Datagram, Error, Result, frame, group, track}; -use track::{Anchor, LiveEdge, Successor}; +use crate::{Datagram, Error, Result, Timestamp, frame, group, track}; +use track::{Anchor, LiveEdge}; use super::subscription::{Cap, Position, Subscription, max_some, min_some}; @@ -144,18 +142,60 @@ fn slice(prefs: &Subscription, start: Option, end: Option) - } } -/// The first servable group in `from..cap` across `segments`, with the slot identity a -/// later judgment needs. An unstamped group stops the search: skipping it for a later -/// start would shrink a reach that is not yet proven. -fn served_start(segments: &[Segment], from: u64, cap: Option) -> Option { - segments.iter().find_map(|segment| { +/// Where the first servable group in `from..cap` across `segments` starts presenting; +/// see [`track::Consumer::poll_first_start`]. An unstamped group stops the search: +/// skipping it for a later start would shrink a reach that is not yet proven. +fn poll_first_start<'a>( + segments: impl IntoIterator, + waiter: &kio::Waiter, + from: u64, + cap: Option, +) -> Option> { + segments.into_iter().find_map(|segment| { let start = segment.start.map_or(0, |start| start.group).max(from); segment .track - .served_start(start, min_some(cap, last_group(segment.end))) + .poll_first_start(waiter, start, min_some(cap, last_group(segment.end))) }) } +/// Where a splice continues past the exclusive group `boundary` of segment `after`, +/// below the reader's `cap`: the first group the later segments serve there. Holds the +/// question rather than a cached answer, so a group aborted or evicted before its first +/// frame hands the bound to whichever group serves there next. +#[derive(Clone)] +pub(crate) struct Successor { + state: kio::ConsumerWeak, + after: u64, + boundary: u64, + cap: Option, +} + +impl Successor { + /// Where the successor starts presenting: `None` while no later group is cached or + /// the first one is unstamped. Registers `waiter` for anything that could move it. + /// Takes the splice's and its segments' locks, so never call it under a track's. + pub(crate) fn poll_start(&self, waiter: &kio::Waiter) -> Option { + let mut start = None; + let _ = self.state.poll(waiter, |state| { + // A draining reader's own segment may already have been pruned. + let later = state.segments.iter().filter(|segment| segment.id > self.after); + start = poll_first_start(later, waiter, self.boundary, self.cap).flatten(); + Poll::<()>::Pending + }); + start + } +} + +impl PartialEq for Successor { + fn eq(&self, other: &Self) -> bool { + self.after == other.after + && self.boundary == other.boundary + && self.cap == other.cap + && self.state.same_channel(&other.state) + } +} + /// How many segments a logical track keeps before pruning terminal ones from the /// front: the live segment plus a couple of predecessors still draining to slow /// readers. Without a bound, every failover leaves one dead segment (pinning a @@ -248,14 +288,6 @@ impl ResumeState { .max_by_key(|edge| edge.sequence) } - /// Where the logical track continues past the exclusive group `boundary` of segment - /// `id`, below the reader's `cap`: the start of the first group the later segments - /// serve there. A draining reader's own segment may already have been pruned. - fn successor(&self, id: u64, boundary: u64, cap: Option) -> Option { - let index = self.segments.iter().position(|segment| segment.id > id)?; - served_start(&self.segments[index..], boundary, cap) - } - /// Append a segment serving the track from `start` onward, capping (or replacing) /// the previous segments so the ranges stay disjoint and ascending. fn switch(&mut self, track: track::Consumer, start: Option) -> Result<()> { @@ -706,10 +738,20 @@ impl Consumer { self.state.read().live_edge(cap) } - /// Where the first servable group in `from..cap` starts, with the identity to - /// revalidate it; see [`track::Consumer::served_start`]. - pub(crate) fn served_start(&self, from: u64, cap: Option) -> Option { - served_start(&self.state.read().segments, from, cap) + /// Where the first servable group in `from..cap` starts presenting; see + /// [`track::Consumer::poll_first_start`]. + pub(crate) fn poll_first_start( + &self, + waiter: &kio::Waiter, + from: u64, + cap: Option, + ) -> Option> { + let mut start = None; + let _ = self.state.poll(waiter, |state| { + start = poll_first_start(&state.segments, waiter, from, cap); + Poll::<()>::Pending + }); + start } /// The newest cached group across every spliced segment; see @@ -1721,16 +1763,21 @@ impl Subscriber { /// content the logical track holds, which a segment's own track never sees. /// /// When the boundary lowers the cap, the reader's next group past it lives in a - /// later segment, so `state` supplies where it starts ([`Anchor::successor`]). - /// Otherwise the logical anchor's own successor (a wrapping splice's) still holds. - fn segment_anchor(seg: &SegmentSub, anchor: Anchor, state: &ResumeState) -> Anchor { + /// later segment of `state` ([`Anchor::successor`]). Otherwise the logical anchor's + /// own successor (a wrapping splice's) still holds. + fn segment_anchor(seg: &SegmentSub, anchor: Anchor, state: &kio::Consumer) -> Anchor { let Some(boundary) = seg.last_group() else { return anchor; }; let cap = anchor.cap; let mut capped = anchor.capped(Some(boundary)); if capped.cap != cap { - capped.successor = state.successor(seg.id, boundary, cap); + capped.successor = Some(Successor { + state: state.weak(), + after: seg.id, + boundary, + cap, + }); } capped } @@ -1749,8 +1796,9 @@ impl Subscriber { /// logical edge moves whenever any of them grows. fn refresh_anchor(&mut self) { let outer = self.outer.clone().capped(self.end_sequence); - let state = self.state.read(); - let edge = state + let edge = self + .state + .read() .live_edge(outer.cap) .into_iter() .chain(outer.edge.clone()) @@ -1763,7 +1811,7 @@ impl Subscriber { *current = anchor.clone(); } for seg in &mut self.segments { - let anchor = Self::segment_anchor(seg, anchor.clone(), &state); + let anchor = Self::segment_anchor(seg, anchor.clone(), &self.state); seg.anchor = anchor.clone(); if let Some(sub) = seg.stale_sub_mut() { sub.set_anchor(anchor); @@ -3359,6 +3407,79 @@ mod test { assert!(matches!(result, Poll::Ready(Ok(None))), "the head is stale: {result:?}"); } + /// An unstamped successor aborted before its first frame no longer names where the + /// track continues, so a read parked at the previous group's tail re-resolves it: + /// first to a later group already cached, then to one that arrives after the abort. + #[tokio::test] + async fn aborted_unstamped_successor_re_resolves_a_parked_read() { + use std::task::Context; + + let (a, a_read) = track_pair("a"); + let (mut b, b_read) = track_pair("b"); + let mut head = a.create_group(0u64.into()).unwrap(); + head.write_frame(Timestamp::ZERO, b"a0".to_vec()).unwrap(); + let successor = b.create_group(1u64.into()).unwrap(); + write_group_at(&mut b, 3, "edge", Duration::from_secs(20)); + let mut producer = Producer::new(); + producer.switch(a_read, None).unwrap(); + producer.switch(b_read, Position::group(1)).unwrap(); + let budget = Subscription::default().with_max_age(Duration::from_secs(10)); + let mut sub = producer.consume().subscribe(budget); + let mut reading = sub.recv_group().now_or_never().unwrap().unwrap().unwrap(); + assert_eq!(reading.sequence, 0, "an unbounded reach is not stale"); + assert_eq!(read(&mut reading), b"a0"); + + let (counter, waker) = CountWaker::new(); + let mut cx = Context::from_waker(&waker); + let mut next = std::pin::pin!(reading.read_frame()); + assert!(next.as_mut().poll(&mut cx).is_pending()); + + successor.abort(Error::Cancel).unwrap(); + // Group 3 is now the successor, and the edge itself: within the budget. + assert!(next.as_mut().poll(&mut cx).is_pending()); + + let before = counter.count(); + write_group_at(&mut b, 2, "b2", Duration::from_secs(1)); + assert!(counter.count() > before, "the replacement successor lost its wakeup"); + let result = next.as_mut().poll(&mut cx); + assert!(matches!(result, Poll::Ready(Ok(None))), "the head is stale: {result:?}"); + } + + /// The same across segments: once the next segment's only group is aborted, the + /// segment after it says where the track continues. + #[tokio::test] + async fn aborted_unstamped_successor_re_resolves_across_segments() { + use std::task::Context; + + let (a, a_read) = track_pair("a"); + let (b, b_read) = track_pair("b"); + let (mut c, c_read) = track_pair("c"); + let mut head = a.create_group(0u64.into()).unwrap(); + head.write_frame(Timestamp::ZERO, b"a0".to_vec()).unwrap(); + let successor = b.create_group(1u64.into()).unwrap(); + write_group_at(&mut c, 2, "c2", Duration::from_secs(1)); + write_group_at(&mut c, 3, "c3", Duration::from_secs(20)); + let mut producer = Producer::new(); + producer.switch(a_read, None).unwrap(); + producer.switch(b_read, Position::group(1)).unwrap(); + producer.switch(c_read, Position::group(2)).unwrap(); + let mut sub = producer.consume().subscribe(None); + let mut reading = sub.recv_group().now_or_never().unwrap().unwrap().unwrap(); + assert_eq!(reading.sequence, 0, "an unbounded reach is not stale"); + assert_eq!(read(&mut reading), b"a0"); + + let (counter, waker) = CountWaker::new(); + let mut cx = Context::from_waker(&waker); + let mut next = std::pin::pin!(reading.read_frame()); + assert!(next.as_mut().poll(&mut cx).is_pending()); + + let before = counter.count(); + successor.abort(Error::Cancel).unwrap(); + assert!(counter.count() > before, "the successor's abort lost its wakeup"); + let result = next.as_mut().poll(&mut cx); + assert!(matches!(result, Poll::Ready(Ok(None))), "the head is stale: {result:?}"); + } + #[tokio::test] async fn pruned_segment_boundary_is_judged_against_later_segments() { let (mut a, a_read) = track_pair("a"); diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 502dfbefe91..49aa3ba2ecb 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -19,6 +19,7 @@ use crate::{broadcast, cache, group, stats}; use super::{Datagram, Requests}; use super::Cap; +use super::resume::Successor; pub use super::subscription::{Position, Subscription}; use std::{ @@ -555,40 +556,20 @@ impl TrackState { /// and `beyond` is where it starts when another track serves it (a splice's next /// segment; see [`Anchor::successor`]). fn reach(&self, sequence: u64, cap: Option, beyond: Option) -> Option { - match self.first_start(sequence.saturating_add(1), cap) { - Some(start) => start, + match self.first_servable(sequence.saturating_add(1), cap) { + Some(group) => group.timestamp(), None => beyond, } } - /// Where the first servable group in `from..cap` starts presenting: `None` when no - /// such group is cached, `Some(None)` while it has no frame yet. - fn first_start(&self, from: u64, cap: Option) -> Option> { - let slot = self - .lookup - .range(from..) - .map(|(_, slot)| slot) - .take_while(|slot| super::subscription::before_end(slot.group.sequence, cap)) - .find(|slot| slot.visible && !slot.group.is_aborted())?; - Some(slot.group.timestamp()) - } - - /// The first servable group's start in `from..cap`, with the slot identity a later - /// judgment needs to tell that group from whatever replaces it. `None` when no such - /// group is cached. An unstamped successor still returns its identity so a wrapping - /// splice does not skip past it to a later segment's stamped group. - fn served_start(&self, from: u64, cap: Option) -> Option { - let slot = self - .lookup + /// The first servable group in `from..cap`, stamped or not. + fn first_servable(&self, from: u64, cap: Option) -> Option<&group::Producer> { + self.lookup .range(from..) .map(|(_, slot)| slot) .take_while(|slot| super::subscription::before_end(slot.group.sequence, cap)) - .find(|slot| slot.visible && !slot.group.is_aborted())?; - Some(ServedStart { - sequence: slot.group.sequence, - stamp: slot.stamp, - timestamp: slot.group.timestamp(), - }) + .find(|slot| slot.visible && !slot.group.is_aborted()) + .map(|slot| &slot.group) } /// Whether the group at `sequence` has drifted further behind `edge` than `budget` @@ -629,9 +610,9 @@ impl TrackState { .presentation .filter(|live| self.holds(live.sequence, live.stamp)) .map(|live| (live.sequence, live.timestamp)); - // `outer` and `successor` were revalidated on their own tracks before this lock - // was taken ([`LiveEdge::is_live`], [`Successor::poll_start`]). There is no slot for - // them here, and taking their locks here would nest. + // `outer` was revalidated and `successor` resolved on their own tracks before this + // lock was taken ([`LiveEdge::is_live`], [`Successor::poll_start`]). There is no + // slot for them here, and taking their locks here would nest. let Some((_, timestamp)) = local .into_iter() .chain(edge.outer) @@ -2537,20 +2518,29 @@ impl Consumer { } } - /// Where the first servable group in `from..cap` starts, with enough identity to - /// revalidate it later. A splice answers from the first segment holding one. - pub(crate) fn served_start(&self, from: u64, cap: Option) -> Option { + /// Where the first servable group in `from..cap` starts presenting: `None` while no + /// such group is cached, `Some(None)` while it has no frame yet. Registers `waiter` + /// for whatever could move that answer: a group arriving or leaving, or the unstamped + /// one's first frame. A splice answers from the first segment holding one. + pub(crate) fn poll_first_start( + &self, + waiter: &kio::Waiter, + from: u64, + cap: Option, + ) -> Option> { match &self.inner { ConsumerKind::Plain(state) => { - let served = state.read().served_start(from, cap)?; - Some(Successor { - sequence: served.sequence, - timestamp: served.timestamp, - stamp: served.stamp, - track: state.weak(), - }) + let mut start = None; + let _ = state.poll(waiter, |state| { + start = state.first_servable(from, cap).map(|group| { + let _ = group.poll_timestamp(waiter); + group.timestamp() + }); + Poll::<()>::Pending + }); + start } - ConsumerKind::Spliced(resume) => resume.served_start(from, cap), + ConsumerKind::Spliced(resume) => resume.poll_first_start(waiter, from, cap), } } @@ -3164,8 +3154,8 @@ enum SubscriberKind { /// One poll's view of how far this subscription may drift: the clamped budget and the /// live edge to measure a candidate group against. Resolved once, then applied to every -/// group that poll considers. `outer` and `successor` are revalidated per candidate, -/// outside this track's lock. +/// group that poll considers. `outer` is revalidated and `successor` resolved per +/// candidate, outside this track's lock. #[derive(Clone)] struct Drift { budget: Duration, @@ -3300,9 +3290,8 @@ pub(crate) struct Anchor { /// Where the reader's next group past `cap` starts presenting, when another track /// serves it (a splice's next segment). The last group below the cap has no /// successor in its own track, so without this nothing bounds its reach and it is - /// never judged stale. `None` while unknown; an unstamped group leaves reach unbounded - /// until its first frame. Revalidated like `edge`: a cached start must not convict - /// once that group is gone. + /// never judged stale. Resolved afresh on every judgment rather than cached, so a + /// group that goes away hands the bound to whichever group serves there next. pub successor: Option, } @@ -3348,50 +3337,6 @@ impl PartialEq for LiveEdge { } } -/// The first servable group past a segment boundary: where it starts, and which slot -/// that start was read from. -struct ServedStart { - sequence: u64, - stamp: u32, - timestamp: Option, -} - -/// A successor pushed onto another track's cursor. The timestamp alone is not enough: -/// once the group is evicted, a later group can keep the outer edge valid while this -/// start is no longer where the track continues. -#[derive(Clone)] -pub(crate) struct Successor { - sequence: u64, - timestamp: Option, - stamp: u32, - track: kio::ConsumerWeak, -} - -impl Successor { - /// The start this still names, re-read from its own track, or `None` once that - /// group is gone or while it is unstamped. An unstamped start registers `waiter` for - /// the first frame, which bounds a reach without touching either track. Takes that - /// track's lock, so never call it under another's. - fn poll_start(&self, waiter: &kio::Waiter) -> Option { - let state = self.track.read(); - let slot = state.lookup.get(&self.sequence)?; - if slot.stamp != self.stamp || slot.group.is_aborted() { - return None; - } - let _ = slot.group.poll_timestamp(waiter); - slot.group.timestamp() - } -} - -impl PartialEq for Successor { - fn eq(&self, other: &Self) -> bool { - self.sequence == other.sequence - && self.timestamp == other.timestamp - && self.stamp == other.stamp - && self.track.same_channel(&other.track) - } -} - /// The newest servable group that has presented at least one frame. #[derive(Clone, Copy)] struct PresentationEdge { @@ -6452,47 +6397,6 @@ mod test { open.finish().unwrap(); } - /// A pushed successor is the same kind of cached fact. Evicting it must not keep - /// bounding the previous segment's last group while a later group still anchors the - /// outer edge. - #[tokio::test] - async fn an_evicted_successor_convicts_nothing() { - let producer = track_producer("a", None); - let mut subscriber = producer.subscribe(Subscription::default().with_max_age(Duration::from_secs(1))); - let mut open = producer.append_group().unwrap(); - open.write_frame(Timestamp::ZERO, bytes::Bytes::from_static(b"a")) - .unwrap(); - let mut group = subscriber.recv_group().await.unwrap().expect("group"); - assert!(group.read_frame().await.unwrap().is_some()); - - let mut next = track_producer("b", None); - // Early enough that group 0 is already past the budget, and not itself the edge. - let successor = append_at(&mut next, 10); - append_at(&mut next, 30_000); - let consumer = next.consume(); - subscriber.set_anchor(Anchor { - cap: None, - edge: consumer.live_edge(None), - successor: consumer.served_start(successor, None), - }); - - let mut control = group.clone(); - assert!( - matches!(control.read_frame().now_or_never(), Some(Ok(None))), - "the open group ends against the successor" - ); - - let slot = next.modify().unwrap().lookup.remove(&successor).unwrap(); - let _ = slot.group.abort(Error::Evicted); - - assert!( - group.read_frame().now_or_never().is_none(), - "a vanished successor is no reason to drop what is left" - ); - assert!(!group.latency_expired()); - open.finish().unwrap(); - } - #[tokio::test] async fn a_lower_sequence_is_never_the_live_edge() { let producer = track_producer("test", None); From 5b433390556378ee45f167aa97150249e65bb090 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 19:24:27 -0700 Subject: [PATCH 084/128] quest: a datagram-flagged fetch object fails only its fetch Co-Authored-By: Claude Opus 5.5 --- quest/m1/datagram-unfetchable.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/quest/m1/datagram-unfetchable.md b/quest/m1/datagram-unfetchable.md index febf484b023..264d256331b 100644 --- a/quest/m1/datagram-unfetchable.md +++ b/quest/m1/datagram-unfetchable.md @@ -21,8 +21,9 @@ datagram flag, and reports it as "unsupported": - FETCH never serves a datagram group. A publisher answers a FETCH for one the way it answers any group it won't deliver (dropped or does not exist), never with its payload. -- A received fetch object with the datagram flag is refused as not fetchable, - a protocol error rather than `Unsupported`. That covers the relay's group +- A received fetch object with the datagram flag is refused as not fetchable. + It fails only that fetch or fill, not the session, because draft-16+ allows + the flag (maintainer, 09-29, on Codex's review). That covers the relay's group fill (`recv_group_fetch_objects`, on the moxygen line) and the joining-fetch fill (`run_fill_objects`). - Update `drafts/draft-lcurley-moq-lite.md` to say datagrams are neither @@ -35,7 +36,7 @@ a one-shot stream, not a cache. Tests: a subscriber joining after datagrams were sent receives only later ones. A FETCH covering a datagram group gets no payload. A fetch stream -carrying a datagram-flagged object is refused. +carrying a datagram-flagged object fails that fetch and leaves the session up. ## Related From f5281183c3dbadd248bfbce82fedb07420f6d6aa Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 19:34:13 -0700 Subject: [PATCH 085/128] feat(net): stamp an unknown publisher ahead of its 0 A route with a leading 0 becomes [stamp, 0, ...] and an empty one [stamp, 0], so the first hop is still unique per connection while the 0 keeps the route ranked below fully identified ones. Co-Authored-By: Claude Opus 5.5 --- doc/bin/relay/cluster.md | 6 +-- doc/concept/moq-lite.md | 4 +- drafts/draft-lcurley-moq-cluster.md | 13 +++--- drafts/draft-lcurley-moq-lite.md | 9 ++-- js/net/src/hop.ts | 15 ++++--- js/net/src/ietf/subscriber.test.ts | 6 ++- js/net/src/ietf/subscriber.ts | 9 ++-- js/net/src/lite/subscriber.test.ts | 9 ++-- js/net/src/lite/subscriber.ts | 6 +-- js/net/src/origin.test.ts | 19 ++++++++- rs/moq-net/src/ietf/subscriber.rs | 13 +++--- rs/moq-net/src/lite/subscriber.rs | 23 +++++----- rs/moq-net/src/model/origin.rs | 66 +++++++++++++++++++++++++---- 13 files changed, 137 insertions(+), 61 deletions(-) diff --git a/doc/bin/relay/cluster.md b/doc/bin/relay/cluster.md index cc6277febf4..88bc2f3e288 100644 --- a/doc/bin/relay/cluster.md +++ b/doc/bin/relay/cluster.md @@ -37,9 +37,9 @@ route as a fresh broadcast, without the old publisher's track properties. A publisher whose protocol names no hop (moq-transport without the cluster extension, moq-lite 01 through 03, or a peer that sends 0) gets a random first -hop from the relay it connects to, fresh for each connection. Its reconnect is -therefore a new publisher downstream, while a reprice on the same connection -stays in place. +hop from the relay it connects to, fresh for each connection, followed by a 0. +Its reconnect is therefore a new publisher downstream, a reprice on the same +connection stays in place, and the 0 keeps it ranked as anonymous. ## Topology diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index f6564a079d8..ccf2ec07873 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -65,8 +65,8 @@ that serves only some of the paths beneath its prefix refuses the rest as they are requested. Each route carries the chain of relay identities it passed through, which is how forwarding loops are caught, and a cost, which is how a subscriber picks among several routes to the same broadcast. A hop of 0 is the -anonymous mark and travels the chain unchanged, except as the first hop: a relay -names an unknown publisher with a random ID fresh per connection. A route that passed through an +anonymous mark and travels the chain unchanged; when it is the first hop, a relay +puts a random ID, fresh per connection, in front of it to name the publisher. A route that passed through an anonymous hop at any depth ranks below every fully identified route, whatever the costs say; among anonymous routes, cost keeps ordering. diff --git a/drafts/draft-lcurley-moq-cluster.md b/drafts/draft-lcurley-moq-cluster.md index fb7dca90269..97d0760c1e4 100644 --- a/drafts/draft-lcurley-moq-cluster.md +++ b/drafts/draft-lcurley-moq-cluster.md @@ -109,7 +109,7 @@ It stands for an endpoint that did not negotiate this extension, and an endpoint Since any number of endpoints can be 0, it identifies nothing: - **Loop detection**: 0 in a HOP_PATH is never a loop. A receiver whose own Hop ID is 0 cannot detect loops through itself and MUST NOT discard an advertisement merely because the path contains 0. -- **Origin identity**: an advertisement whose first entry is 0 has an unknown publisher, which a relay names with a stamp of its own before recording it ({{stamping}}). A receiver MUST NOT treat two unstamped ones as interchangeable ({{selection}}). +- **Origin identity**: an advertisement whose first entry is 0 has an unknown publisher, which a relay names by putting a stamp of its own in front ({{stamping}}). A receiver MUST NOT treat two unstamped ones as interchangeable ({{selection}}). - **Filtering**: a peer that declared 0 gave the receiver nothing to filter that session on. The receiver MAY assign an ID of its own ({{assigned}}) as local selection state and MUST NOT write it into HOP_PATH. Duplicate *non-zero* Hop IDs in one HOP_PATH are a loop; duplicate zeros are not. @@ -130,10 +130,11 @@ A peer the receiver authenticated, or dialed and therefore chose, SHOULD get one An anonymous accepted session cannot be correlated with anything, so it SHOULD get a distinct ID per session: not an identity, but enough to keep routes learned from it from being advertised back to it, which is the loop 0 cannot prevent. ## Stamping an Unknown Publisher {#stamping} -A relay that records an advertisement whose first HOP_PATH entry is 0, or that arrived with no HOP_PATH ({{bridging}}), MUST replace that entry with a random non-zero Hop ID, picked once for the session the advertisement arrived on. -A 0 anywhere else in HOP_PATH stays. +A relay that records an advertisement whose first HOP_PATH entry is 0 MUST insert a random non-zero Hop ID in front of it, picked once for the session the advertisement arrived on. +One that arrived with no HOP_PATH ({{bridging}}) becomes that stamp followed by 0. Nothing on the wire says whether an unnamed publisher that reconnects is the same one, so a fresh stamp per session makes its reconnect a change of publisher downstream ({{updating}}), while an update on the same session keeps the stamp and applies in place. +The 0 behind the stamp keeps the path ranked below fully identified ones ({{selection}}), since the unnamed hop may hide any depth. A stamp names a session, not a peer: it MUST NOT be reused across sessions or taken as the peer's identity. @@ -198,7 +199,7 @@ Unknown, out-of-budget, and saturated routes are outside the guarantee: a receiv # Relay Behavior A relay forwarding an advertisement MUST append its own Hop ID to the HOP_PATH it received, so its ID is always the last entry. -A received 0 is forwarded unchanged, except as the first entry ({{stamping}}). +A received 0 is forwarded unchanged, behind a stamp when it is the first entry ({{stamping}}). A relay MUST discard an advertisement whose HOP_PATH already contains its own non-zero Hop ID: forwarding it would extend a loop, and subscribing through it would route the relay back to itself. This check catches loops of any length and is the only loop defense required. @@ -206,7 +207,7 @@ A conforming sender never sends one ({{selection}}), so a receiver MAY close the ## Bridging {#bridging} An upstream that did not negotiate the extension sends no HOP_PATH. -The relay creates one holding only its stamp for that session ({{stamping}}), then appends its own Hop ID. +The relay creates one holding its stamp for that session followed by 0 ({{stamping}}), then appends its own Hop ID. The identity a receiver assigned that upstream ({{assigned}}) is local selection state and MUST NOT appear in HOP_PATH. ## Accumulating Cost {#accumulating} @@ -339,7 +340,7 @@ This document requests one registration in the "REQUEST_ERROR Codes" registry. - Defined request resolution against the longest covering prefix and the NO_CAPACITY refusal with its single re-resolution; any other refusal is terminal, including between several publishers of one namespace. - A relay does not advertise a namespace because it resolved it; the publisher advertises the concrete namespace once producing. - A change of original publisher is an ordinary update instead of a withdrawal and a new advertisement. Subscriptions already served drain the old source; new requests take the updated route. -- A relay stamps an advertisement whose first HOP_PATH entry is 0, or that has no HOP_PATH, with a random Hop ID picked per session, instead of recording 0. +- A relay puts a random Hop ID, picked per session, in front of an advertisement whose first HOP_PATH entry is 0, and writes that stamp followed by 0 for one with no HOP_PATH. ## moq-cluster-01 - Assigned identities are local selection state and MUST NOT be forwarded. diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index 95eaa7ecd28..b1537812392 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -408,8 +408,9 @@ This is the only loop defense moq-lite requires, and it catches loops of any len A conforming sender never sends one (see below), so a receiver MAY instead close the session with a protocol violation; discarding is what keeps a mesh working when one member does not conform. A Hop ID of 0 means unknown and never matches anything; withholding an ID trades loop detection for privacy. A receiver MAY assign an identity of its own to a peer that declared 0, as local selection state for filtering that session; it MUST NOT forward that identity as a Hop ID. -A relay that records an announcement whose reconstructed path is empty or starts with 0 MUST replace that first entry with a random non-zero Hop ID, picked once for the session it arrived on. +A relay that records an announcement whose reconstructed path starts with 0 MUST insert a random non-zero Hop ID in front of it, picked once for the session it arrived on; an empty path becomes that stamp followed by 0. Nothing on the wire says whether an unnamed publisher that reconnects is the same one, so its reconnect reads downstream as a new first hop, while an ANNOUNCE_UPDATE on the same session keeps the stamp. +The 0 behind the stamp keeps the path ranked below fully identified ones. A publisher MUST NOT advertise a path whose entries contain the Hop ID the subscriber declared in its SETUP (see [Hop Parameter](#hop-parameter)). The receiver can only discard it, and acting on it would form a loop, so sending one is never useful. @@ -914,8 +915,8 @@ The responding publisher's own Hop ID is NOT included in the resolved list; it i When forwarding an announcement received from an upstream peer, a relay MUST append the upstream peer's ANNOUNCE_OK `Hop ID` to the resolved list, since that ID is no longer implicit downstream. The first entry of the reconstructed path identifies the endpoint that originated the route. A Hop ID value of 0 means the hop is unknown: either it was never assigned or a relay deliberately withholds it (see [Routing](#routing)). -A received 0 is forwarded unchanged, except as the first entry, which a relay stamps (see [Routing](#routing)). -When bridging an announcement from an upstream that sent no hop list, a relay writes its stamp for that hop. +A received 0 is forwarded unchanged, behind a stamp when it is the first entry (see [Routing](#routing)). +When bridging an announcement from an upstream that sent no hop list, a relay writes its stamp followed by 0 for that hop. An identity a receiver assigned that upstream is local selection state and MUST NOT be forwarded as a Hop ID. A receiver MUST close the session with a PROTOCOL_VIOLATION if a non-zero Hop ID appears twice in the resolved list. @@ -1345,7 +1346,7 @@ The `Message Length` describes the payload size on the wire. - The Subscribe Stream FIN now follows once every counted Group Stream has finished or been reset. - Added announce compression: ANNOUNCE_START gains `Path Base` and `Path Keep` to copy the head of a live advertisement's suffix, and ANNOUNCE_START and ANNOUNCE_UPDATE gain `Hop Base` and `Hop Keep` to copy the tail of a live advertisement's Hop ID list. - Capped the SETUP Message Length at 65,536 bytes. -- A relay stamps an announcement whose reconstructed path is empty or starts with 0 with a random Hop ID picked per session, instead of recording 0. +- A relay puts a random Hop ID, picked per session, in front of an announcement whose reconstructed path starts with 0, and writes that stamp followed by 0 for an empty path. ## moq-lite-06 diff --git a/js/net/src/hop.ts b/js/net/src/hop.ts index 85ce8cab478..b5e69ebc766 100644 --- a/js/net/src/hop.ts +++ b/js/net/src/hop.ts @@ -67,16 +67,17 @@ export function randomHop(): Hop { } /** - * Name an unknown original publisher: fill an empty chain, or replace a first entry of 0, - * with `stamp`, the receiving connection's own random id. A publisher that reconnects then - * reads downstream as a new first hop. `undefined` if `stamp` already appears later in the - * chain. Mirrors `Hops::stamp` in rs/moq-net. + * Name an unknown original publisher: put `stamp`, the receiving connection's own random id, + * in front of a chain that starts with 0, and turn an empty chain into `[stamp, 0]`. A + * publisher that reconnects then reads downstream as a new first hop, while the 0 after the + * stamp keeps the route ranked as anonymous. `undefined` if the chain is full or already holds + * `stamp`. Mirrors `Hops::stamp` in rs/moq-net. */ export function stampHops(hops: readonly Hop[], stamp: Hop): Hop[] | undefined { - if (hops.length === 0) return [stamp]; + if (hops.length === 0) return [stamp, UNKNOWN_HOP]; if (hops[0] !== UNKNOWN_HOP) return [...hops]; - if (hops.includes(stamp)) return undefined; - return [stamp, ...hops.slice(1)]; + if (hops.length >= MAX_HOPS || hops.includes(stamp)) return undefined; + return [stamp, ...hops]; } /** diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index 698272d83f9..5b89d781709 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -103,7 +103,8 @@ test("an unsolicited announcement lands", async () => { /** * A session without the Cluster extension names no publisher, so each connection stamps its - * own random Hop ID as the first hop: a publisher that reconnects reads as a new one. + * own random Hop ID in front of a 0: a publisher that reconnects reads as a new one, and the 0 + * keeps it ranked below identified routes. */ test("an advertisement with no path is stamped per connection", async () => { const stamp = async () => { @@ -118,8 +119,9 @@ test("an advertisement with no path is stamped per connection", async () => { stream, ); const hops = (await announced.next())?.route.hops ?? []; - expect(hops).toHaveLength(1); + expect(hops).toHaveLength(2); expect(hops[0]).not.toBe(UNKNOWN_HOP); + expect(hops[1]).toBe(UNKNOWN_HOP); return hops[0]; }; diff --git a/js/net/src/ietf/subscriber.ts b/js/net/src/ietf/subscriber.ts index aaf0ea5aadf..8671b6e6d51 100644 --- a/js/net/src/ietf/subscriber.ts +++ b/js/net/src/ietf/subscriber.ts @@ -4,7 +4,7 @@ import * as broadcast from "../broadcast.ts"; import { BroadcastCache } from "../consume.ts"; import { closeError, controlTimeout, error, ProtocolViolation, reason, sessionCause } from "../error.ts"; import * as netGroup from "../group.ts"; -import { Cost, type Route, randomHop, routesEqual, stampHops } from "../hop.ts"; +import { Cost, type Route, randomHop, routesEqual, stampHops, UNKNOWN_HOP } from "../hop.ts"; import { hiddenBelow, hooks, scopeCaptures, scopeHead, scopeOverlaps } from "../internal.ts"; import * as Path from "../path.ts"; import type { Cursor, Reader, Stream } from "../stream.ts"; @@ -181,11 +181,12 @@ export class Subscriber { /** * The route an advertisement carries; one without a path is free. A path that names no - * publisher, or none at all, is named by this connection's stamp. + * publisher, or none at all, gets this connection's stamp in front of a 0. */ #route(advert: Cluster.Advert | undefined): Route { - if (advert === undefined) return { hops: [this.#stamp], cost: Cost.zero }; - // A stamp colliding with a later entry is a 1-in-2^53 draw: keep the path as sent. + if (advert === undefined) return { hops: [this.#stamp, UNKNOWN_HOP], cost: Cost.zero }; + // A full chain, or a stamp colliding with an entry (a 1-in-2^53 draw), keeps the + // path as sent. const hops = stampHops(advert.hops, this.#stamp) ?? [...advert.hops]; return { hops, cost: { warm: advert.cost, cold: advert.cost } }; } diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index 3843556e9ce..e3b8e104d1a 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -197,8 +197,11 @@ test("a received hop list naming no publisher is stamped per connection", async const update = await announced.next(); expect(update).toMatchObject({ prefix: Path.from("room"), kind: "announced" }); const hops = update?.route.hops ?? []; - expect(hops).toHaveLength(1); + expect(hops).toHaveLength(2); expect(hops[0]).not.toBe(UNKNOWN_HOP); + // The 0 after the stamp keeps the unnamed publisher ranked as anonymous. + expect(hops[1]).toBe(UNKNOWN_HOP); + expect(update && isAnonymous(update.route)).toBe(true); announced.close(); subscriber.close(); @@ -209,7 +212,7 @@ test("a received hop list naming no publisher is stamped per connection", async expect(await first()).not.toBe(await first()); }); -test("a received chain starting with hop 0 has only its first entry stamped", async () => { +test("a received chain starting with hop 0 keeps it behind the stamp", async () => { const { subscriber, send, settle } = announceHarness(Version.DRAFT_06); const announced = subscriber.announced(); await settle(); @@ -226,7 +229,7 @@ test("a received chain starting with hop 0 has only its first entry stamped", as expect(update).toMatchObject({ prefix: Path.from("room"), kind: "announced" }); const [stamp, ...rest] = update?.route.hops ?? []; expect(stamp).not.toBe(UNKNOWN_HOP); - expect(rest).toEqual([PUBLISHER_A, PEER]); + expect(rest).toEqual([UNKNOWN_HOP, PUBLISHER_A, PEER]); announced.close(); subscriber.close(); diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index 9fe819432f1..c024bba9dac 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -5,7 +5,7 @@ import type { Probe as ProbeStats } from "../connection/stats.ts"; import { BroadcastCache } from "../consume.ts"; import { controlTimeout, error, ProtocolViolation, reason, StreamCode, StreamError, sessionCause } from "../error.ts"; import * as netGroup from "../group.ts"; -import { Cost, type Hop, MAX_HOPS, type Route, randomHop, routesEqual, stampHops } from "../hop.ts"; +import { Cost, type Hop, MAX_HOPS, type Route, randomHop, routesEqual, stampHops, UNKNOWN_HOP } from "../hop.ts"; import { groupBounds, hiddenBelow, scopeCaptures, scopeHead, scopeOverlaps } from "../internal.ts"; import * as Path from "../path.ts"; import { type OpenOptions, type Reader, Stream } from "../stream.ts"; @@ -273,7 +273,7 @@ export class Subscriber { if (advertised.has(path)) { throw new ProtocolViolation(`duplicate announce for ${path}`); } - const route = { hops: [this.#stamp], cost: Cost.zero }; + const route = { hops: [this.#stamp, UNKNOWN_HOP], cost: Cost.zero }; const live = visible(path); const captures = scopeCaptures(scope, path); advertised.set(path, { publisher: this.#stamp, live, route, captures }); @@ -404,7 +404,7 @@ export class Subscriber { // The first hop identifies the original publisher; an empty chain means the // peer itself originated it. One that names nobody (lite-01..03, or a peer - // reporting 0) is named by this connection's stamp. + // reporting 0) gets this connection's stamp in front of its 0. const fullHops = stampHops( hops !== undefined && responderOrigin !== undefined ? [...hops, responderOrigin] diff --git a/js/net/src/origin.test.ts b/js/net/src/origin.test.ts index 635b4fb2fba..e26a9f80c2a 100644 --- a/js/net/src/origin.test.ts +++ b/js/net/src/origin.test.ts @@ -2,7 +2,7 @@ import { expect, test } from "bun:test"; import { getter } from "@moq/signals"; import { type Consumer as BroadcastConsumer, Producer as BroadcastProducer } from "./broadcast.ts"; import { StreamCode, StreamError } from "./error.ts"; -import { HopSchema, Route } from "./hop.ts"; +import { HopSchema, Route, stampHops } from "./hop.ts"; import type { Consumer, Table } from "./origin.ts"; import { Producer } from "./origin.ts"; import * as Path from "./path.ts"; @@ -117,6 +117,23 @@ test("unscoped broadcast getters share one fresh snapshot per mutation", () => { origin.close(); }); +test("a stamped route ranks below an identified one of the same length", () => { + const origin = new Producer(); + const path = Path.from("room/alice"); + const stamped = stampHops([], HopSchema.parse(5n)); + if (!stamped) throw new Error("an empty chain always has room"); + const identified = [HopSchema.parse(11n), PEER]; + expect(stamped).toHaveLength(identified.length); + + const legacy = wireOf(origin).receive(path, { hops: stamped, cost: 0n }); + const named = wireOf(origin).receive(path, { hops: identified, cost: 9n }); + expect(origin.consume().broadcasts().peek().get(path)).toEqual(Route.normalize({ hops: identified, cost: 9n })); + + legacy.close(); + named.close(); + origin.close(); +}); + test("an announced local path competes with a received route on cost", async () => { const origin = new Producer(); const consumer = origin.consume(); diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 033239cb999..8165bd92477 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -559,7 +559,8 @@ where /// The route for an advertisement that carries no path of its own. /// /// Base moq-transport has no hops on the wire, so the chain is this connection's - /// stamp alone, naming the unknown publisher for as long as the connection lasts. + /// stamp, naming the unknown publisher for as long as the connection lasts, then + /// the anonymous 0 that keeps it ranked below identified routes. /// The session's assigned identity stays on `via` for split-horizon; putting it in /// the chain would publish a name for a peer that declined to give one. /// @@ -573,8 +574,8 @@ where /// its true length. Price such a link with [`crate::Client::with_cost`]. fn session_route(&self, peer: &cluster::Peer) -> crate::origin::Route { let mut hops = crate::Hops::new(); - hops.push(self.stamp) - .expect("an empty hop chain has room for one entry"); + hops.stamp(self.stamp) + .expect("an empty hop chain has room for the stamp and its 0"); crate::origin::Route::default() .with_hops(hops) .with_via(self.via(peer)) @@ -587,8 +588,7 @@ where /// /// A negotiated peer supplies the path and cost, so the route is what the mesh /// actually knows: the full chain, and the accumulated cost plus this link's price. - /// A first entry of 0 is replaced by this connection's stamp; a 0 anywhere else - /// stays. An advertisement whose path already contains our own Hop ID looped back, + /// A path starting with 0 gets this connection's stamp in front of it; the 0s stay. An advertisement whose path already contains our own Hop ID looped back, /// and neither forwarding it nor subscribing through it is safe. fn route(&self, advert: Option<&cluster::Advert>, peer: &cluster::Peer) -> Option { let Some(advert) = advert else { @@ -4141,8 +4141,9 @@ mod tests { let mut announced = consumer.announced(); let route = announced.assert_next_active("room/host"); let hops: Vec<_> = route.hops.iter().copied().collect(); - assert_eq!(hops, vec![subscriber.stamp]); + assert_eq!(hops, vec![subscriber.stamp, crate::Hop::UNKNOWN]); assert_ne!(subscriber.stamp, crate::Hop::UNKNOWN); + assert!(route.is_anonymous(), "the 0 after the stamp still ranks it as unknown"); assert_ne!(subscriber.stamp, assigned, "the assigned identity stays off the chain"); let mut hidden = consumer.excluding(assigned).announced(); diff --git a/rs/moq-net/src/lite/subscriber.rs b/rs/moq-net/src/lite/subscriber.rs index a2b07445ff1..28d1b641422 100644 --- a/rs/moq-net/src/lite/subscriber.rs +++ b/rs/moq-net/src/lite/subscriber.rs @@ -313,10 +313,10 @@ impl Subscriber { } // Lite01/02 send no list at all, and Lite03 carries only UNKNOWN placeholders, - // so the publisher may be unnamed: this connection's stamp names it. Later - // placeholders stay 0 and count as anonymous. + // so the publisher may be unnamed: this connection's stamp goes in front to name + // it, and the 0s stay so the route still ranks as anonymous. if hops.stamp(self.stamp).is_err() { - tracing::debug!(route = %self.log_path(&path), "dropping announce; stamp already in the chain"); + tracing::debug!(route = %self.log_path(&path), "dropping announce; no room to stamp the chain"); return Ok(false); } @@ -2525,16 +2525,17 @@ mod tests { let mut cursor = consumer.announced(); let route = cursor.assert_next_active("room/host"); let hops: Vec<_> = route.hops.iter().copied().collect(); - assert_eq!(hops, vec![subscriber.stamp]); + assert_eq!(hops, vec![subscriber.stamp, crate::Hop::UNKNOWN]); assert_ne!(subscriber.stamp, assigned); + assert!(route.is_anonymous()); let mut hidden = consumer.excluding(assigned).announced(); hidden.assert_next_wait(); } - /// Lite03 hop-count placeholders name nobody, so the first is replaced by the - /// connection's stamp; the rest stay 0 and count as anonymous. None is rewritten with - /// the assigned identity. + /// Lite03 hop-count placeholders name nobody, so the connection's stamp goes in front; + /// the placeholders stay 0 and count as anonymous. None is rewritten with the + /// assigned identity. #[tokio::test] async fn lite03_placeholders_stay_anonymous() { let assigned = crate::Hop::new(777).unwrap(); @@ -2570,12 +2571,12 @@ mod tests { let mut cursor = consumer.announced(); let route = cursor.assert_next_active("room/host"); let hops: Vec<_> = route.hops.iter().copied().collect(); - assert_eq!(hops, vec![subscriber.stamp, crate::Hop::UNKNOWN]); + assert_eq!(hops, vec![subscriber.stamp, crate::Hop::UNKNOWN, crate::Hop::UNKNOWN]); assert!(route.is_anonymous()); } /// A publisher that names nobody is stamped with a random id fresh per connection, - /// never 0: a restart on the same connection keeps the stamp and updates in place, + /// never 0, ahead of the 0 that keeps it ranked as unknown: a restart on the same connection keeps the stamp and updates in place, /// while the same publisher reconnecting reads as a new first hop. #[tokio::test] async fn an_unnamed_publisher_is_stamped_per_connection() { @@ -2599,7 +2600,7 @@ mod tests { let mut cursor = consumer.announced(); let route = cursor.assert_next_active("room/host"); let hops: Vec<_> = route.hops.iter().copied().collect(); - assert_eq!(hops, vec![first.stamp]); + assert_eq!(hops, vec![first.stamp, crate::Hop::UNKNOWN]); // A reprice from the same unnamed publisher keeps the stamp, so it stays in place. first @@ -2614,7 +2615,7 @@ mod tests { .unwrap(); let route = cursor.assert_next_active("room/host"); let hops: Vec<_> = route.hops.iter().copied().collect(); - assert_eq!(hops, vec![first.stamp]); + assert_eq!(hops, vec![first.stamp, crate::Hop::UNKNOWN]); } fn restart_subscriber(session: SinkSession) -> (Subscriber, crate::origin::Consumer) { diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index bbe7c2434f4..0f5ff462752 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -265,20 +265,28 @@ impl Hops { Ok(()) } - /// Name an unknown original publisher: fill an empty chain, or replace a first - /// entry of 0, with `stamp`, the receiving session's own per-connection id. + /// Name an unknown original publisher: prefix `stamp`, the receiving session's own + /// per-connection id, to a chain that starts with 0, and turn an empty chain into + /// `[stamp, 0]`. /// /// A publisher that reconnects then reads downstream as a new first hop, which is - /// all anyone can say about it. Fails with [`InvalidHop::Duplicate`] if `stamp` - /// already appears later in the chain. + /// all anyone can say about it, while the 0 after the stamp keeps the route ranked + /// as anonymous. Fails with [`InvalidHop::TooMany`] if the chain is full, and with + /// [`InvalidHop::Duplicate`] if `stamp` already appears in it. pub(crate) fn stamp(&mut self, stamp: Hop) -> Result<(), InvalidHop> { match self.0.first() { - None => self.push(stamp), + None => { + self.push(stamp)?; + self.push(Hop::UNKNOWN) + } Some(first) if *first == Hop::UNKNOWN => { - if self.0[1..].contains(&stamp) { + if self.0.len() >= MAX_HOPS { + return Err(InvalidHop::TooMany); + } + if self.0.contains(&stamp) { return Err(InvalidHop::Duplicate); } - self.0[0] = stamp; + self.0.insert(0, stamp); Ok(()) } Some(_) => Ok(()), @@ -476,8 +484,8 @@ pub struct Route { /// The chain of origins the route has traversed, oldest first. Each relay /// appends its own [`crate::Hop`] when forwarding; used for loop detection /// and as the selection tie-break. A 0 entry is the anonymous mark and - /// travels unchanged, except as the first entry, which a session receiving - /// it replaces with its own per-connection stamp; see [`Self::is_anonymous`]. + /// travels unchanged; a session receiving one as the first entry puts its own + /// per-connection stamp in front of it; see [`Self::is_anonymous`]. pub hops: Hops, /// What pulling content via this route costs, accumulated per link: lower wins @@ -5139,6 +5147,46 @@ mod tests { assert_eq!(route.cost, Cost::new(5)); } + /// A stamped route names its session but keeps the 0 behind the stamp, so it still + /// loses to a fully identified route of the same length, however cheap it is. + #[tokio::test] + async fn a_stamped_route_ranks_below_an_identified_one() { + let producer = origin(1).produce(); + let mut announced = producer.consume().announced(); + + let mut stamped = Hops::new(); + stamped.stamp(origin(5)).unwrap(); + assert_eq!(stamped.as_slice(), &[origin(5), Hop::UNKNOWN]); + + let _legacy = producer + .announce("room", Route::default().with_hops(stamped).with_cost(0)) + .unwrap(); + let route = announced.assert_next_active("room"); + assert!(route.is_anonymous()); + + let _identified = producer + .announce("room", Route::default().with_hops(hops(&[10, 11])).with_cost(5)) + .unwrap(); + let route = announced.assert_next_active("room"); + assert_eq!(route.hops.as_slice(), hops(&[10, 11]).as_slice()); + } + + #[test] + fn stamping_keeps_the_leading_zero_and_names_nothing_else() { + let mut chain = hops(&[0, 7]); + chain.stamp(origin(5)).unwrap(); + assert_eq!(chain.as_slice(), hops(&[5, 0, 7]).as_slice()); + + // Already named: untouched. + let mut named = hops(&[7, 0]); + named.stamp(origin(5)).unwrap(); + assert_eq!(named.as_slice(), hops(&[7, 0]).as_slice()); + + // A full chain has no room for the stamp. + let mut full = Hops::try_from(vec![Hop::UNKNOWN; MAX_HOPS]).unwrap(); + assert_eq!(full.stamp(origin(5)), Err(InvalidHop::TooMany)); + } + #[tokio::test] async fn anonymous_routes_order_by_cost() { let producer = origin(1).produce(); From d3c73df1eff9b7f0a1b95eba84e1fe73de6c675e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 20:03:35 -0700 Subject: [PATCH 086/128] quest: plan relay hardening and IETF decode fixes (#4570) Co-authored-by: Claude Opus 5.5 --- quest/m0/README.md | 19 ++++++++++++- quest/m0/frame-alloc-budget.md | 32 ++++++++++++++++++++++ quest/m0/handshake-deadline.md | 24 +++++++++++++++++ quest/m0/ietf-fin-not-cancel.md | 32 ++++++++++++++++++++++ quest/m0/ietf-legal-input.md | 48 +++++++++++++++++++++++++++++++++ quest/m0/noq-reassembly-cap.md | 35 ++++++++++++++++++++++++ quest/m0/qmux-reset-race.md | 27 +++++++++++++++++++ quest/m0/remove-gossip.md | 37 +++++++++++++++++++++++++ quest/m0/request-caps.md | 36 +++++++++++++++++++++++++ quest/m0/revalidate-overflow.md | 18 +++++++++++++ quest/m0/shared-fronts.md | 33 +++++++++++++++++++++++ quest/m0/subscriber-prune.md | 19 +++++++++++++ quest/m1/README.md | 1 - quest/m1/auth/request-token.md | 11 +++++--- quest/m1/cluster-routing.md | 5 ++-- quest/m1/coding-reader-cap.md | 21 --------------- quest/m1/moxygen/fetch.md | 7 ++++- quest/m2/hidden-exemption.md | 2 +- 18 files changed, 376 insertions(+), 31 deletions(-) create mode 100644 quest/m0/frame-alloc-budget.md create mode 100644 quest/m0/handshake-deadline.md create mode 100644 quest/m0/ietf-fin-not-cancel.md create mode 100644 quest/m0/ietf-legal-input.md create mode 100644 quest/m0/noq-reassembly-cap.md create mode 100644 quest/m0/qmux-reset-race.md create mode 100644 quest/m0/remove-gossip.md create mode 100644 quest/m0/request-caps.md create mode 100644 quest/m0/revalidate-overflow.md create mode 100644 quest/m0/shared-fronts.md create mode 100644 quest/m0/subscriber-prune.md delete mode 100644 quest/m1/coding-reader-cap.md diff --git a/quest/m0/README.md b/quest/m0/README.md index 09ca0b80190..d0507ec5504 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -2,7 +2,10 @@ ## Goal -The work in flight now, in two independent tracks. Routing: a publisher stops +The work in flight now, in three independent tracks. Relay hardening: every +resource a peer can make the relay hold is bounded by what it sent or by a +budget, no peer input panics the process, and legal moq-transport input never +fails a session, ahead of Seattle interop on 2026-10-12. Routing: a publisher stops sending announce updates the wire cannot tell apart, a service claims the prefix it could serve instead of enumerating broadcasts. Audio playout: the target is a measured estimate of arrival timing in both languages, a browser regression fails a @@ -26,11 +29,25 @@ browser lane grades it nightly and records the traces it replays; the native lane is a standalone m1 quest, since nothing here waits on it. The A/V clock builds on the jitter target's per-track spread. +Relay hardening comes from an external review on 2026-09-29, verified against +`main`. Its quests describe fixes, not exploits. + Published API or wire breaks still land on dev; each quest's Plan says so. ## Required - [quest check everywhere](/quest/m0/quest-check-everywhere.md) - `quest check` guards `main`, `dev`, and the line branches on push and PR, not only PRs into `main` +- [noq reassembly cap](/quest/m0/noq-reassembly-cap.md) - noq carries quinn's stream reassembly cap and the connection receive window is finite by default +- [qmux reset race](/quest/m0/qmux-reset-race.md) - qmux handles RESET_STREAM under one lock instead of panicking +- [Remove gossip](/quest/m0/remove-gossip.md) - a relay dials only configured peers; `cluster.mesh` is refused at startup +- [Shared fronts](/quest/m0/shared-fronts.md) - viewer sessions share a front, so fronts scale with peers, not viewers +- [Frame alloc budget](/quest/m0/frame-alloc-budget.md) - frame buffers pre-allocate within a per-session budget and otherwise grow with bytes received +- [Handshake deadline](/quest/m0/handshake-deadline.md) - an unfinished handshake or slow HTTP header times out +- [Request caps](/quest/m0/request-caps.md) - lite message sizes, IETF request IDs, and per-session announces and subscriptions are bounded +- [Subscriber prune](/quest/m0/subscriber-prune.md) - a track's subscription list holds only live subscribers +- [Revalidate overflow](/quest/m0/revalidate-overflow.md) - no auth duration can overflow a deadline and abort the relay +- [Legal IETF input](/quest/m0/ietf-legal-input.md) - draft-20+ FETCH, allowed parameters, INCLUDE_PROPERTIES and FORWARD=0 decode and are refused per request, not session-fatal +- [IETF FIN semantics](/quest/m0/ietf-fin-not-cancel.md) - a request stream FIN stops updates without cancelling, and REQUEST_UPDATE on a subscribe is parsed - [Wildcard](/quest/m0/wildcard/README.md) - a relay resolves subscriptions against advertised prefixes, a service claims the prefix it could serve and refuses the rest instead of enumerating broadcasts, and the browser player treats a covering claim as availability - [Audio quality harness](/quest/m0/audio-quality-harness/README.md) - a browser playout latency regression fails a nightly run instead of arriving as a bug report, and its recorder supplies the jitter target's replay traces - [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - the audio playout target is a measured estimate of arrival timing in both languages, not a round-trip guess diff --git a/quest/m0/frame-alloc-budget.md b/quest/m0/frame-alloc-budget.md new file mode 100644 index 00000000000..bd55c8a8e47 --- /dev/null +++ b/quest/m0/frame-alloc-budget.md @@ -0,0 +1,32 @@ +# [M] Frame buffers are backed by bytes received + +## Goal + +The memory a relay commits to an incoming frame tracks what the peer has +sent, not only the size it declared. Today the first payload byte allocates +the whole declared size (up to `MAX_CACHE_BYTES`, 32 MiB) with +`vec![0u8; size]` and charges it to the cache, with no aggregate bound. + +## Plan + +- Pre-allocating the declared size is a deliberate optimization, so keep it + within a per-session budget: a frame whose declared size fits the + session's remaining budget is allocated up front; past the budget the + buffer grows as bytes arrive. Bytes are returned to the budget when the + frame completes or aborts. Decided 2026-09-29. +- Charge the cache by bytes written rather than declared size + (`model/group.rs` `state.cache += frame.size`). +- Benchmark first (`rs/moq-net/benches`): frame receive throughput swept over + frame size and concurrent streams, for today, full growth, and the budget, + so the budget's default comes from the measurement. +- Paths: `model/frame.rs` `MutableFrameBuf::new`, `coding/reader.rs` + `poll_read_frame`, called from both `lite/subscriber.rs` and + `ietf/subscriber.rs`. + +Public API: none expected; if the budget needs a knob, it goes on the relay +config, not moq-net. Wire: none. + +## Related + +- [Frame slot charge](/quest/m1/frame-slot-charge.md) - also changes what a group charges the cache +- [Peer limits](/quest/m1/quic/peer-limits.md) - stream counts and windows per peer diff --git a/quest/m0/handshake-deadline.md b/quest/m0/handshake-deadline.md new file mode 100644 index 00000000000..e8f998804b3 --- /dev/null +++ b/quest/m0/handshake-deadline.md @@ -0,0 +1,24 @@ +# [S] Handshakes and HTTP headers have deadlines + +## Goal + +A connection that never completes its QUIC, WebTransport, WebSocket or MoQ +SETUP handshake is closed after a deadline, and the relay's HTTP listener +times out slow request headers. Today `moq-tokio/src/server.rs` pushes +`accept_request` futures with no deadline, and the 5 s keep-alive keeps an +idle pre-SETUP connection alive indefinitely. axum-server 0.8 builds hyper +without a timer, so hyper's `header_read_timeout` never fires +(`moq-relay/src/web.rs`). + +## Plan + +- Wrap the accept future in a timeout covering everything up to a completed + SETUP, then close with the transport's timeout code. The timeout is a + config value with a default of around 10 s. +- Configure `http1().timer(TokioTimer).header_read_timeout(..)` on the + relay's HTTP builder. +- Tests on a paused clock: a stalled SETUP is closed at the deadline, and a + completed one is not. +- Document both in `doc/bin/relay/config.md`. + +Public API: a config field on the server. Wire: none. diff --git a/quest/m0/ietf-fin-not-cancel.md b/quest/m0/ietf-fin-not-cancel.md new file mode 100644 index 00000000000..329cac16ee3 --- /dev/null +++ b/quest/m0/ietf-fin-not-cancel.md @@ -0,0 +1,32 @@ +# [M] A request stream FIN is not a cancellation + +## Goal + +On moq-transport's bidi request streams (draft 19+), a peer's FIN means no +more updates, not cancel. Only RESET_STREAM, STOP_SENDING or our own end +cancels. Today a FIN withdraws a PUBLISH_NAMESPACE +(`ietf/subscriber.rs`), ends a SUBSCRIBE_NAMESPACE, and cancels a SUBSCRIBE +(`ietf/publisher.rs`). Draft-21 section 6.4.2.2 says a requester MAY FIN +right after its message. A REQUEST_UPDATE on a subscribe stream is never +parsed either: its first byte makes `poll_closed` return an error and +silently ends the subscription. + +## Plan + +- Gate on version: drafts 17 and 18 say a FIN cancels SUBSCRIBE_NAMESPACE, + so keep that there, and test both sides of the gate. +- Separate the read side's clean FIN (`Reader::poll_closed` returning Ok) + from a reset. On FIN, keep serving and stop reading. Watch the writer for + STOP_SENDING. +- Parse REQUEST_UPDATE on subscribe streams, where the draft allows it. + Apply what we support and refuse the rest `NOT_SUPPORTED`. +- Check the same FIN handling in `js/net`. +- Tests for each request type: FIN right after the request keeps it alive, + a reset cancels it, and a REQUEST_UPDATE is applied. + +Public API: none. Wire: conformance fix; no draft change. + +## Related + +- [Legal IETF input](/quest/m0/ietf-legal-input.md) - the other interop blocker +- [Lite request streams](/quest/m1/request-stream-serve.md) - lite deliberately treats a FIN as ending the request; don't unify the two diff --git a/quest/m0/ietf-legal-input.md b/quest/m0/ietf-legal-input.md new file mode 100644 index 00000000000..1faf8828d1f --- /dev/null +++ b/quest/m0/ietf-legal-input.md @@ -0,0 +1,48 @@ +# [L] Legal IETF input never fails the session + +## Goal + +Every message a conformant draft-14 to draft-22 peer may send decodes, and +anything we don't support is refused per request, not by closing the session. +moxygen and libquicr send several of these today, and Seattle interop is +2026-10-12. + +## Plan + +Each of these closes the session today with `PROTOCOL_VIOLATION`: + +- FETCH on drafts 20+ still decodes the removed Fetch Type field + (`ietf/fetch.rs`). Decode the draft-20 layout: namespace, name and params, + with the range in LOCATION_FILTER. Refuse it `NOT_SUPPORTED` until + [moxygen FETCH](/quest/m1/moxygen/fetch.md) serves it. Fix the encoder and + the pinned test in `version.rs`. +- Request parameters the draft allows on a message fail `decode_params!`: + AUTHORIZATION TOKEN (0x03) anywhere, NEW_GROUP_REQUEST (0x32) and the + object and track filters (0x25 to 0x29) on SUBSCRIBE and REQUEST_UPDATE, + FILL_TIMEOUT (0x0A) and 0x21 and 0x35 on FETCH, and any parameter on TRACK_STATUS. Accept each + one where the draft allows it. The token is decoded and ignored, since the + session grant still applies; [Request token](/quest/m1/auth/request-token.md) + gives it meaning (decided 2026-09-29). An unknown key stays fatal, per the + draft. +- INCLUDE_PROPERTIES (0x35) is read as length-prefixed; the draft defines a + uint8 (`ietf/subscribe.rs`). Encode and decode it as `u8`, and delete the + doc comment arguing for key-parity framing: that rule covers Setup and + Properties KVPs, not message parameters. +- FORWARD=0 returns `DecodeError::Unsupported`. Decode it, then refuse the + request `NOT_SUPPORTED`. + +Not in scope: pre-draft-20 subscribe filters other than Largest Object stay +ignored. `older_drafts_are_ignored` in `ietf/publisher.rs` records that +choice, since honoring them would change what existing peers receive. + +- Tests: one decode test per message and draft, built from the draft's + message figures and bytes captured from moxygen and libquicr, plus a + session test showing each refusal leaves the session open. +- Mirror the decode in `js/net`. + +Public API: none. Wire: fixes conformance; no draft change. + +## Related + +- [IETF FIN semantics](/quest/m0/ietf-fin-not-cancel.md) - the other interop blocker +- [IETF stream types](/quest/m1/ietf-uni-stream-types.md) - same stream-scoped-before-fatal rule for uni streams diff --git a/quest/m0/noq-reassembly-cap.md b/quest/m0/noq-reassembly-cap.md new file mode 100644 index 00000000000..db3e5456fc6 --- /dev/null +++ b/quest/m0/noq-reassembly-cap.md @@ -0,0 +1,35 @@ +# [M] noq carries quinn's stream reassembly cap + +## Goal + +The QUIC stacks the relay builds on bound how many out-of-order chunks a +stream or CRYPTO buffer holds, as quinn-proto 0.11.15 does, and a connection's +receive window is finite by default. Today `moq-noq-proto` 1.3.2 (`main`) and +2.0.0 (`dev`), and upstream `noq-proto` 1.3.0 (pulled in by the relay's default `iroh` +feature), predate quinn's fix, and `cargo audit` cannot match them because +the crates are renamed. + +## Plan + +- Port quinn [fed0321a](https://github.com/quinn-rs/quinn/commit/fed0321a) + ([quinn#2694](https://github.com/quinn-rs/quinn/pull/2694), + RUSTSEC-2026-0185) to moq-dev/noq: `Assembler::insert` returns an error past + 1024 buffered chunks after defragmenting, the stream path closes with + `INTERNAL_ERROR`, and the CRYPTO path does the same. Keep quinn's test. + Release 1.3.3 and 2.0.1, then bump the pins here. +- Open the same port as a PR on n0-computer/noq (approved 2026-09-29; the + advisory is public). iroh builds stay on the unfixed upstream crate until + n0 releases it; bump when they do. +- Give `moq-tokio` a finite default connection `receive_window` instead of + the backend's `VarInt::MAX` (`rs/moq-tokio/src/noq.rs` `apply_windows`, + `quic.rs`). Pick the value with a throughput measurement, not a + guess, and update `doc/bin/relay/config.md`. +- `rs/moq-uring` depends on `moq-noq-proto` too, so the same pin bump + covers the io_uring workers. + +Public API: none. Wire: a peer that exceeds the chunk cap is closed. + +## Related + +- [QUIC release](/quest/m1/quic/release.md) - owns the fork's security-update procedure this gap shows is missing +- [Peer limits](/quest/m1/quic/peer-limits.md) - per-peer windows and stream limits diff --git a/quest/m0/qmux-reset-race.md b/quest/m0/qmux-reset-race.md new file mode 100644 index 00000000000..6b6143f59a8 --- /dev/null +++ b/quest/m0/qmux-reset-race.md @@ -0,0 +1,27 @@ +# [XS] qmux handles RESET_STREAM under one lock + +## Goal + +qmux's RESET_STREAM handling never panics when the writer task removes the +receive stream concurrently. Today `session.rs` checks +`streams.recv.contains_key`, drops the lock, and later re-locks with +`.expect("live recv stream")`; a `StopSending` queued by a dropped +`RecvStream` can remove the entry in between. A missing entry must be a +no-op, not a panic. + +## Plan + +- In moq-dev/web-transport `rs/qmux/src/session.rs`, look the entry up once + under a single lock (`if let Some(recv) = get_mut`); a missing entry means + the stream already closed and the reset is a no-op. +- Regression test that removes the entry between the two points. +- Audit the other `expect`s on the stream maps (`sched.rs`) for the same + pattern. +- Release a patch on the pinned 0.5 line and on 0.6, then bump the 0.5 pin + here. Moving to 0.6 is not part of this quest. + +Public API: none. Wire: none. + +## Related + +- [qmux on noq-proto](/quest/m1/quic/qmux.md) - replaces these stream maps entirely, later diff --git a/quest/m0/remove-gossip.md b/quest/m0/remove-gossip.md new file mode 100644 index 00000000000..58901b13952 --- /dev/null +++ b/quest/m0/remove-gossip.md @@ -0,0 +1,37 @@ +# [S] Remove cluster gossip discovery + +## Goal + +A relay dials only peers an operator configured: `cluster.connect`, the +connect API, or LAN mDNS. Gossip discovery (`cluster.mesh`), which advertises +under `.internal/origins/` and dials whatever URL appears there with +`cluster.token`, is removed. It is the only path that dials a URL learned +from an announcement. The design favors a configured full mesh, and moq.pro drives peers +through `--cluster-connect-api` and never enables gossip. + +## Plan + +- Delete gossip advertising and discovery (`rs/moq-relay/src/cluster.rs`, + `nodes.rs` `MESH_PREFIX`) and whatever becomes dead behind them. Keep + `cluster.node` only if something else still reads it. +- `nodes.rs` also backs the internal `/nodes` endpoint (`internal.rs` + `serve_nodes`), which merges gossiped advertisements with direct sessions. + It keeps direct sessions only; document the changed response. +- Retarget `rs/moq-relay/tests/hidden_cluster.rs` to another `.`-prefixed + hidden broadcast, and fix the `.internal/origins` comment in + `connection.rs`. +- Lands on `main` as a security fix, not `dev`. `--cluster-mesh`, + `MOQ_CLUSTER_MESH` and `mesh = true` fail at startup with a message + pointing at `cluster.connect`, so nobody silently loses their mesh. + Decided 2026-09-29. +- Docs: rewrite the Discovery section of `doc/bin/relay/cluster.md`, drop the + `.internal/` warning, and add an upgrade note in `doc/setup/upgrade.md`. + Search the repo for `cluster-mesh` and `mesh = true` in examples and demo + recipes. + +Public API: removes a relay config field and flag. Wire: relays stop +announcing `.internal/origins`. + +## Related + +- [Cluster routing](/quest/m1/cluster-routing.md) - takes its topology from configured links only diff --git a/quest/m0/request-caps.md b/quest/m0/request-caps.md new file mode 100644 index 00000000000..b469c58adc8 --- /dev/null +++ b/quest/m0/request-caps.md @@ -0,0 +1,36 @@ +# [L] Peer-declared lengths and request counts are bounded + +## Goal + +Every length and count a peer declares is bounded before the relay buffers +or tracks it. That covers three things: + +- lite control messages, which may declare 64 MiB each + (`lite/message.rs`, buffered by `coding/reader.rs` `poll_read_more`); +- IETF FETCH object properties, decoded as a bare `Vec` with no cap; +- IETF incoming request IDs, which are never checked against the + `MAX_REQUEST_ID` we advertise on drafts 14 to 16 (`u32::MAX`, + `rs/moq-net/src/server.rs` and `client.rs`). + +Announces and subscriptions per session are capped as well. + +## Plan + +- Lite: per-message `MAX_SIZE` sized to the largest legitimate message + (SETUP already caps at 64 KiB). Anything larger is a decode error. +- Audit `rs/moq-net/src/coding/` for any other decode that allocates from a + peer length, and cap the fetch properties. This absorbs the deleted + `coding-reader-cap` quest. +- IETF drafts 14 to 16: advertise a finite `MAX_REQUEST_ID` window, grant more with + MAX_REQUEST_ID as requests close, and close with the draft's error on an ID + past it (`ietf/control.rs`, `ietf/adapter.rs`). Draft-17 removed + MAX_REQUEST_ID; there QUIC's bidi stream limit and the per-session cap + bound requests. +- A per-session cap on live announces and subscriptions on both protocols, + refused per request rather than session-fatal where the protocol allows. +- Benchmark per-session request churn swept over sessions and requests per + session, so the window refill shows no slope. +- Mirror the lite message cap in `js/net`. + +Public API: possibly caps on the session config; propose the shape in the PR. +Wire: behaviour within the drafts' existing limits. No format change. diff --git a/quest/m0/revalidate-overflow.md b/quest/m0/revalidate-overflow.md new file mode 100644 index 00000000000..f42c8ba0ad1 --- /dev/null +++ b/quest/m0/revalidate-overflow.md @@ -0,0 +1,18 @@ +# [XS] Auth durations cannot overflow a deadline + +## Goal + +No auth-server or token duration can panic the relay. Today +`moq-auth/src/client.rs` computes `Instant::now() + cadence` for the +`revalidate` value, and `Grant::deadline` adds a token's `exp` the same way. +A value near `u64::MAX` seconds overflows and panics. + +## Plan + +- Use `checked_add`. `Grant::validate` refuses a `revalidate` longer than the + grant's expiry, and treats an `exp` beyond `Instant`'s range as no expiry. +- Unit tests with `u64::MAX` revalidate and exp. +- Grep the workspace for other `Instant + Duration` on peer- or + server-supplied values. + +Public API: none. Wire: none. diff --git a/quest/m0/shared-fronts.md b/quest/m0/shared-fronts.md new file mode 100644 index 00000000000..f2594ad9fff --- /dev/null +++ b/quest/m0/shared-fronts.md @@ -0,0 +1,33 @@ +# [M] Viewer sessions share a front + +## Goal + +The number of origin fronts for a path is bounded by the peers that appear in +its route chains, not by viewer sessions. Today every session gets +`Hop::random()`, the lite publisher serves through `origin.excluding(hop)`, +and fronts are keyed by `(path, Horizon)` (`model/origin.rs`). Each viewer +therefore mints its own front plus a driver task, and `run_front` only ends +on route retraction or source close, so fronts accumulate for the life of a +long-running broadcast. + +## Plan + +- Key a front by its effective exclusion: a hop that appears in no route + chain for the path excludes nothing, so its sessions share the plain front. + When such a hop later shows up in a chain, the sessions it covers move to + the filtered front. Decided 2026-09-29, over ending idle fronts after a + linger, because it also removes the per-viewer cost while viewers are + active. +- Check whether prefix routes mint fronts for arbitrary covered paths + (`origin.rs` optimistic resolve) and bound that the same way. +- Measure with a benchmark swept over viewers and broadcasts + (`rs/moq-net/benches/origin.rs`): fronts and bytes per viewer before and + after, plus reconnect churn. + +Public API: none. Wire: none. + +## Related + +- [Front deadlines](/quest/m1/front-deadline-index.md) - per-front cost per track +- [Front parking](/quest/m1/origin-front-parks.md) - also changes what mints a front +- [Relay memory](/quest/m1/relay-memory.md) - per-announcement measurements diff --git a/quest/m0/subscriber-prune.md b/quest/m0/subscriber-prune.md new file mode 100644 index 00000000000..eecffd3dce6 --- /dev/null +++ b/quest/m0/subscriber-prune.md @@ -0,0 +1,19 @@ +# [XS] A track drops departed subscribers + +## Goal + +A track's subscription list holds only live subscribers. Today +`register_subscription` (`model/track.rs`) pushes without pruning, and closed +entries are only removed when the aggregate changes. While at least one +viewer stays, churning viewers with identical preferences accumulate, and +`combined_subscription` walks all of them on every wake. + +## Plan + +- Remove an entry when its subscriber drops, or `retain` live entries on push + and on each poll, whichever keeps the wake path cheapest. +- A unit test that churns identical subscribers under one steady viewer and + asserts the list length stays bounded. +- A benchmark swept over steady viewers and churn rate. + +Public API: none. Wire: none. diff --git a/quest/m1/README.md b/quest/m1/README.md index 9b5c96a74ea..0cb39d32db7 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -117,7 +117,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Publish channel count](/quest/m1/publish-audio-channel-count.md) - forcing a channel count on an Audio.Capture stops costing the subscriber gaps of silence - [JS abandonment](/quest/m1/js-subscribe-abandonment.md) - a viewer returning during IETF subscribe setup keeps its track across microtasks - [IETF stream types](/quest/m1/ietf-uni-stream-types.md) - padding streams are discarded stream-only and an unknown uni type closes the session, per draft-21 -- [Rust decode caps](/quest/m1/coding-reader-cap.md) - every Rust decode that allocates from a peer-supplied length is bounded - [Epoch primitive](/quest/m1/epoch.md) - one `Epoch` type in moq-net and @moq/net, carried as a trailing `@` path segment, shared by e2ee and broadcast epochs - [E2EE](/quest/m1/e2ee/README.md) - TypeScript and Rust peers interoperate over encrypted broadcasts no relay can decrypt - [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - each publish of a name gets a fresh `@` epoch, viewers follow the newest live one at once, and bare names still resolve on every version diff --git a/quest/m1/auth/request-token.md b/quest/m1/auth/request-token.md index fa93750186c..ddf64060128 100644 --- a/quest/m1/auth/request-token.md +++ b/quest/m1/auth/request-token.md @@ -11,8 +11,9 @@ does not cover it, by the token on the request; with neither it is refused `UNAUTHORIZED`. The token's grant covers only the request it rode on and lives exactly as long as that request, and a REQUEST_UPDATE carrying a new token replaces it, which is how a peer refreshes. It scopes by path, never -by method. Today the strict decoder on newer drafts fails the whole message -on the unknown key, and the legacy drafts silently ignore it. +by method. [Legal IETF input](/quest/m0/ietf-legal-input.md) decodes and +ignores the key first, so a token no longer fails the session; this quest +gives it meaning. ## Plan @@ -20,8 +21,9 @@ on the unknown key, and the legacy drafts silently ignore it. (`rs/moq-net/src/ietf/token.rs`, `js/net/src/ietf/token.ts`): `USE_VALUE` yields the token, `REGISTER` is a value since we advertise no `MAX_AUTH_TOKEN_CACHE_SIZE`, and `DELETE` or `USE_ALIAS` closes with `PROTOCOL_VIOLATION`. Both decoder families change: the strict - `decode_params!` path, which rejects the key today, and the generic KVP - path the legacy drafts use, which ignores it. + `decode_params!` path, which ignores the key after + [Legal IETF input](/quest/m0/ietf-legal-input.md), and the generic KVP + path the legacy drafts use, which also ignores it. - Fallback only: a request the session grant already covers is served without verifying its token. Otherwise its token becomes an `auth::Request` on the session's `auth::Handle`, the seam an AUTH stream's @@ -71,5 +73,6 @@ to) and on `moq_auth::Client` (the per-request lease). Wire: none new; the param ## Required +- [Legal IETF input](/quest/m0/ietf-legal-input.md) - decodes the parameter everywhere the draft allows it - [Relay tokens](/quest/m1/auth/relay-refresh.md) - supplies the lease revalidation the per-request lease reuses diff --git a/quest/m1/cluster-routing.md b/quest/m1/cluster-routing.md index 35dd9c22f19..9cb6fb698ef 100644 --- a/quest/m1/cluster-routing.md +++ b/quest/m1/cluster-routing.md @@ -58,8 +58,9 @@ but does not end it; see the findings below. relay graph and link costs. Relays flood per-link liveness among themselves with a per-link seqno. The seqno is scoped to the relay's incarnation, so a restarted relay's links supersede its stale ones instead of looking older. - Gossip discovery (`cluster.mesh`) stays for zero-config self-hosting and - derives the topology from what it discovers; it need not scale. + Configured links are the only source: gossip discovery is removed by + [Remove gossip](/quest/m0/remove-gossip.md), and LAN mDNS dials peers + that then count as configured links. - A relay batches the liveness reports it sends, its own and those it forwards, for a short hold-down (50 ms in the simulator), and recomputes its trees after a matching delay, as OSPF's SPF delay does. Unbatched, one diff --git a/quest/m1/coding-reader-cap.md b/quest/m1/coding-reader-cap.md deleted file mode 100644 index 68b22a6a797..00000000000 --- a/quest/m1/coding-reader-cap.md +++ /dev/null @@ -1,21 +0,0 @@ -# [XS] Rust decoders cap a bare byte or string read - -## Goal - -Every Rust decode path that allocates from a peer-supplied length has an -upper bound. #4373 fixed a JS size-cap bypass; the lite and IETF message -decoders in Rust already check every length prefix, but `coding/reader.rs` -has no overall cap for a bare `Vec` or `String` decode. - -## Plan - -- Audit `rs/moq-net/src/coding/` for decodes that allocate from a length - prefix without a bound, and list which call sites reach them from the - wire. -- Where one is reachable, bound it by the message's size limit and refuse - anything larger with a decode error. If none is reachable, add the bound - anyway only if it's one line; otherwise delete this quest with the audit - in the PR. - -Public API: none. Wire: oversized fields are refused, which they already -should be. diff --git a/quest/m1/moxygen/fetch.md b/quest/m1/moxygen/fetch.md index f236d1751f0..e38d1e533b3 100644 --- a/quest/m1/moxygen/fetch.md +++ b/quest/m1/moxygen/fetch.md @@ -11,7 +11,8 @@ subscriber sees. ## Plan Standalone FETCH and a non-zero joining FETCH are refused today with -"not supported". Walk `track::Consumer::fetch_group`, one group, then the +"not supported". Those forms exist only before draft-20; on draft-20+ the +range comes from LOCATION_FILTER. Walk `track::Consumer::fetch_group`, one group, then the next. Do not add an archive. A joining FETCH is the same walk for the groups it names. A form the walk @@ -20,6 +21,10 @@ cannot express is still an explicit refusal, not a hang. The moxygen FETCH cases that ask for whole groups are the check. The rest of that suite is not. +## Required + +- [Legal IETF input](/quest/m0/ietf-legal-input.md) - decodes the draft-20+ FETCH layout this serves + ## Related - [Moxygen compatibility](/quest/m1/moxygen/README.md) - the line this belongs to diff --git a/quest/m2/hidden-exemption.md b/quest/m2/hidden-exemption.md index 96ecf2afea6..18a993aca67 100644 --- a/quest/m2/hidden-exemption.md +++ b/quest/m2/hidden-exemption.md @@ -13,7 +13,7 @@ for peers that predate it. callers in `rs/moq-relay/src/{connection,uring,websocket}.rs`, and the forced `with_hidden(true)` on the outbound dial in `rs/moq-relay/src/cluster.rs`. - Replace `rs/moq-relay/tests/hidden_cluster.rs` with a lite-07 mesh test that - still sees `.internal/origins`. + still sees a `.`-prefixed hidden broadcast. ## Required From 94d9f0d4211b003d248aaac14b6a18ce2c8acef1 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 20:06:51 -0700 Subject: [PATCH 087/128] quest: plan the TS stats module move on dev (#4572) Co-authored-by: Claude Opus 5.5 --- quest/m1/README.md | 1 + quest/m1/ts-stats-module.md | 45 +++++++++++++++++++++++++++++++++++++ quest/m2/ts-health-stats.md | 6 +++-- 3 files changed, 50 insertions(+), 2 deletions(-) create mode 100644 quest/m1/ts-stats-module.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 0cb39d32db7..0d582724d64 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -45,6 +45,7 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Wire compatibility](/quest/m1/wire-compat.md) - a nightly run tests this checkout against the last published release for tokens, session wire, and catalog/container - [TS import shared shift](/quest/m1/ts-import-shared-shift.md) - unflagged loop wraps move audio and video by one shift, so A/V sync holds across wraps - [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) - `import ts` reads a PAT or PMT that spans packets or follows a nonzero pointer_field instead of aborting, and one corrupted section costs a repetition and a counted `CRC_error`, not the import +- [TS stats module](/quest/m1/ts-stats-module.md) - on dev, the TS stats types move under `ts::stats` as `Snapshot` and `Stream`, with an owned `track` - [Same-hop importers](/quest/m1/hop-aligned-import.md) - importers sharing a `--hop` and fed one stream publish identical groups and timestamps, so failover survives - [Capture control](/quest/m1/capture-control.md) - on dev, `encode::Capture` replaces `CaptureOptions` without a `clock` field (it reads the catalog's), an unsupported `cut()` errors, and dropping the last `Control` cancels in-flight opens - [Capture by default](/quest/m1/capture-default.md) - moq-video and moq-audio build `capture` by default, so pre-merge checks test it and the capture gate goes away diff --git a/quest/m1/ts-stats-module.md b/quest/m1/ts-stats-module.md new file mode 100644 index 00000000000..a68a4203fbd --- /dev/null +++ b/quest/m1/ts-stats-module.md @@ -0,0 +1,45 @@ +# [S] TS stats module + +## Goal + +On `dev`, every moq-mux TS stats type lives in the `container::ts::stats` +module beside `stats::Log`: `ts::Stats` becomes `ts::stats::Snapshot` and +`ts::StreamStats` becomes `ts::stats::Stream`. `StreamStats.track` becomes an +owned `String`, and `ts::MultipleProgramsError` becomes `#[non_exhaustive]`. +No new fields and no behavior change. + +## Plan + +Decided while planning the follow-ups of +[#4505](https://github.com/moq-dev/moq/pull/4505) and +[#4506](https://github.com/moq-dev/moq/pull/4506): + +- **Breaking, so `dev`.** `Stats` and `StreamStats` have been published since + moq-mux 0.9.14. #4506 kept them at `ts::` on `main` for that reason. +- **Names: `stats::Snapshot` and `stats::Stream`.** `Snapshot` matches + `moq_net::stats::Snapshot`. `stats::Import` was rejected because it reads + like `ts::Import`, and `stats::Pid` because the row is a stream's liveness, + not the PID itself. +- **`StreamStats.track` becomes `String`.** This is batched here so there is + one break, not two. [TS health stats](/quest/m2/ts-health-stats.md) needs + it so the type deserializes. +- **`MultipleProgramsError` gets `#[non_exhaustive]`.** Callers keep + recovering it by downcast (`moq-cli` hints `--program` from it) and keep + reading `programs`. It can gain fields without another break. A `ts::Error` + enum was rejected: the importer returns `anyhow`, so callers would still + downcast. +- Update moq-cli's `publish.rs`, the only consumer that names these types. + moq-srt only uses `stats::Log`. +- Main quests still add fields under the old names: + [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md), + [TS import health](/quest/m2/ts-import-health.md) and + [TS export liveness](/quest/m2/ts-export-liveness.md). The rename carries + those fields at merge time. Update the type names in the quests still open + when this lands, including [media stats schema](/quest/m1/stats/schema.md) + and [Rust reporters](/quest/m1/stats/rust.md). + +Public API: breaking renames in moq-mux. Wire: none. + +## Required + +- `main` merged into `dev`, carrying #4506's `ts::stats` module (dev has none yet) diff --git a/quest/m2/ts-health-stats.md b/quest/m2/ts-health-stats.md index 9e408b3ace6..28e8fc6b9d3 100644 --- a/quest/m2/ts-health-stats.md +++ b/quest/m2/ts-health-stats.md @@ -26,8 +26,9 @@ Decided while planning [#1838](https://github.com/moq-dev/moq/issues/1838): - **Counters sum, gauges do not.** Every check is a cumulative counter, which keeps `.z` deltas small and lets an aggregate sum; the PID's `quiet` is a gauge and merges newest-wins. -- `ts::Stats` gains serde, every field defaulted and unknown fields ignored; - `StreamStats.track` becomes owned so the type deserializes. +- `ts::Stats` gains serde, every field defaulted and unknown fields ignored. + [TS stats module](/quest/m1/ts-stats-module.md) makes `track` owned so the + type deserializes. - Docs: `doc/concept/stats.md` documents each counter's TR 101 290 check, its monitoring point (ingest grades the feed, egress grades our muxer, and neither is the groomed wire), the value domain of the PCR checks, and that @@ -38,6 +39,7 @@ Decided while planning [#1838](https://github.com/moq-dev/moq/issues/1838): ## Required +- [TS stats module](/quest/m1/ts-stats-module.md) - the owned `track` that lets the rows deserialize - [Media stats schema](/quest/m1/stats/schema.md) - the snapshot the counters flatten into - [Rust reporters](/quest/m1/stats/rust.md) - `moq import --stats` and the stats interval - [TS import health](/quest/m2/ts-import-health.md) - the ingest counters From fd3bb81337f4a7c4a8abc2a3723924d62474844e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 21:31:18 -0700 Subject: [PATCH 088/128] docs: add hand-drawn language icons to library table (#4563) --- doc/.vitepress/theme/Banner.vue | 7 +++ doc/.vitepress/theme/custom.css | 29 ++++++++++++ doc/lib/index.md | 16 +++---- doc/public/icons/languages/c.svg | 20 +++++++++ doc/public/icons/languages/dart.svg | 27 ++++++++++++ doc/public/icons/languages/go.svg | 26 +++++++++++ doc/public/icons/languages/kotlin.svg | 19 ++++++++ doc/public/icons/languages/python.svg | 30 +++++++++++++ doc/public/icons/languages/rust.svg | 54 +++++++++++++++++++++++ doc/public/icons/languages/swift.svg | 36 +++++++++++++++ doc/public/icons/languages/typescript.svg | 29 ++++++++++++ 11 files changed, 285 insertions(+), 8 deletions(-) create mode 100644 doc/public/icons/languages/c.svg create mode 100644 doc/public/icons/languages/dart.svg create mode 100644 doc/public/icons/languages/go.svg create mode 100644 doc/public/icons/languages/kotlin.svg create mode 100644 doc/public/icons/languages/python.svg create mode 100644 doc/public/icons/languages/rust.svg create mode 100644 doc/public/icons/languages/swift.svg create mode 100644 doc/public/icons/languages/typescript.svg diff --git a/doc/.vitepress/theme/Banner.vue b/doc/.vitepress/theme/Banner.vue index 8d85b53c0c4..73c5e6280d6 100644 --- a/doc/.vitepress/theme/Banner.vue +++ b/doc/.vitepress/theme/Banner.vue @@ -25,6 +25,13 @@ line-height: 1.4; } +@media (min-width: 960px) { + .moq-banner { + height: var(--moq-banner-height); + margin-top: var(--vp-nav-height); + } +} + .moq-banner p { margin: 0.15rem 0; color: var(--vp-c-text-2); diff --git a/doc/.vitepress/theme/custom.css b/doc/.vitepress/theme/custom.css index 80986a4c5ce..67020908878 100644 --- a/doc/.vitepress/theme/custom.css +++ b/doc/.vitepress/theme/custom.css @@ -1,4 +1,6 @@ :root { + --moq-banner-height: 2.55rem; + /* Brand colors - green accent matching moq.dev */ --vp-c-brand-1: #16a34a; --vp-c-brand-2: #15803d; @@ -130,6 +132,11 @@ border-bottom-color: #334155; } +/* The layout-top notice already clears the fixed navbar. */ +.Layout .VPContent { + padding-top: 0; +} + /* Community.vue is the GitHub/Discord pair in the desktop navbar. Keep the stock entries so the mobile overlay still has those links, and hide the duplicates here (VPNavBarExtra is also inside VPNavBar). */ @@ -143,11 +150,33 @@ background-color: #0f172a; } +@media (min-width: 960px) { + .Layout .VPSidebar { + top: calc(var(--vp-nav-height) + var(--moq-banner-height)); + height: calc(100vh - var(--vp-nav-height) - var(--moq-banner-height)); + padding-top: 0; + } +} + /* Home hero styling */ .VPHero .name { color: #22c55e; } +.vp-doc .language-icon { + width: 2rem; + height: 2rem; + object-fit: contain; + display: inline-block; + vertical-align: middle; + margin-right: 1rem; +} + +.vp-doc td:has(.language-icon) { + white-space: nowrap; + min-width: 10rem; +} + /* Feature layout - emoji in top right corner */ .VPFeature { position: relative; diff --git a/doc/lib/index.md b/doc/lib/index.md index 27eaf5edd18..31cfa3e47de 100644 --- a/doc/lib/index.md +++ b/doc/lib/index.md @@ -10,14 +10,14 @@ protocol. A publisher in Python is consumable by a subscriber in Swift. | Language | Package | Best for | | --- | --- | --- | -| [Rust](/lib/rs/) | `moq-net`, `hang`, and friends on crates.io | Servers, CLIs, native apps, anything that needs the full stack including hardware codecs. | -| [TypeScript](/lib/js/) | `@moq/*` on npm | Browsers (WebTransport + WebCodecs) and Node/Bun/Deno. | -| [Swift](/lib/swift/) | `Moq` via SwiftPM | iOS, iPadOS, macOS. | -| [Kotlin](/lib/kt/) | `dev.moq:moq` on Maven Central | Android and the JVM. | -| [Python](/lib/py/) | `moq-rs` on PyPI | Scripts, ML pipelines, voice agents. | -| [Go](/lib/go/) | `moq.dev/moq` | Go services and tooling. | -| [Dart](/lib/dart/) | `moq` on pub.dev | Flutter apps. | -| [C](/lib/c/) | `libmoq` | C/C++ and any language with a C FFI. | +| [Rust](/lib/rs/) | `moq-net`, `hang`, and friends on crates.io | Servers, CLIs, native apps, anything that needs the full stack including hardware codecs. | +| [TypeScript](/lib/js/) | `@moq/*` on npm | Browsers (WebTransport + WebCodecs) and Node/Bun/Deno. | +| [Swift](/lib/swift/) | `Moq` via SwiftPM | iOS, iPadOS, macOS. | +| [Kotlin](/lib/kt/) | `dev.moq:moq` on Maven Central | Android and the JVM. | +| [Python](/lib/py/) | `moq-rs` on PyPI | Scripts, ML pipelines, voice agents. | +| [Go](/lib/go/) | `moq.dev/moq` | Go services and tooling. | +| [Dart](/lib/dart/) | `moq` on pub.dev | Flutter apps. | +| [C](/lib/c/) | `libmoq` | C/C++ and any language with a C FFI. | ## How they relate diff --git a/doc/public/icons/languages/c.svg b/doc/public/icons/languages/c.svg new file mode 100644 index 00000000000..908f7bd169f --- /dev/null +++ b/doc/public/icons/languages/c.svg @@ -0,0 +1,20 @@ + + C + + + + diff --git a/doc/public/icons/languages/dart.svg b/doc/public/icons/languages/dart.svg new file mode 100644 index 00000000000..5282756c0b9 --- /dev/null +++ b/doc/public/icons/languages/dart.svg @@ -0,0 +1,27 @@ + + Dart + + + + diff --git a/doc/public/icons/languages/go.svg b/doc/public/icons/languages/go.svg new file mode 100644 index 00000000000..b463e050841 --- /dev/null +++ b/doc/public/icons/languages/go.svg @@ -0,0 +1,26 @@ + + Go + + + + + + + diff --git a/doc/public/icons/languages/kotlin.svg b/doc/public/icons/languages/kotlin.svg new file mode 100644 index 00000000000..4412d147f70 --- /dev/null +++ b/doc/public/icons/languages/kotlin.svg @@ -0,0 +1,19 @@ + + Kotlin + + + + diff --git a/doc/public/icons/languages/python.svg b/doc/public/icons/languages/python.svg new file mode 100644 index 00000000000..5f6f9871c17 --- /dev/null +++ b/doc/public/icons/languages/python.svg @@ -0,0 +1,30 @@ + + Python + + + + + diff --git a/doc/public/icons/languages/rust.svg b/doc/public/icons/languages/rust.svg new file mode 100644 index 00000000000..f2888db2d8a --- /dev/null +++ b/doc/public/icons/languages/rust.svg @@ -0,0 +1,54 @@ + + Rust (Ferris) + + + + + + + + diff --git a/doc/public/icons/languages/swift.svg b/doc/public/icons/languages/swift.svg new file mode 100644 index 00000000000..fb2c202112f --- /dev/null +++ b/doc/public/icons/languages/swift.svg @@ -0,0 +1,36 @@ + + Swift + + + + diff --git a/doc/public/icons/languages/typescript.svg b/doc/public/icons/languages/typescript.svg new file mode 100644 index 00000000000..d9a37061a9a --- /dev/null +++ b/doc/public/icons/languages/typescript.svg @@ -0,0 +1,29 @@ + + TypeScript + + + + From 98ff05e35cec12ea40d598b7ee5ffcf27b4ffc3a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 21:34:37 -0700 Subject: [PATCH 089/128] fix(rpm): sign every package so gpgcheck=1 installs work (#4571) Co-authored-by: Claude Opus 5.5 --- infra/rpm/publish.sh | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/infra/rpm/publish.sh b/infra/rpm/publish.sh index d8a61ba1427..f8d2be9e37c 100755 --- a/infra/rpm/publish.sh +++ b/infra/rpm/publish.sh @@ -2,7 +2,8 @@ # # Regenerate yum/dnf repo metadata and push to the rpm-moq-dev R2 bucket. # Pull the current pool, merge in new .rpm files from $ARTIFACTS_DIR, -# rebuild repodata with createrepo_c, sign repomd.xml with GPG, and upload. +# sign every package, rebuild repodata with createrepo_c, sign repomd.xml +# with GPG, and upload. # # Required env: # ARTIFACTS_DIR directory containing new .rpm files to add @@ -12,7 +13,7 @@ # SIGNING_KEY ascii-armored GPG private key (shared with apt repo and maven publishing) # SIGNING_PASSWORD optional passphrase for SIGNING_KEY # -# Required tools: rclone, createrepo_c, gpg. +# Required tools: rclone, rpmsign, createrepo_c, gpg. set -euo pipefail @@ -86,11 +87,24 @@ if [[ ${#KEY_IDS[@]} -ne 1 ]]; then exit 1 fi KEY_ID="${KEY_IDS[0]}" +# Read the passphrase from a file so it never appears in a process list. GPG_PASS_ARGS=() if [[ -n "${SIGNING_PASSWORD:-}" ]]; then - GPG_PASS_ARGS=(--pinentry-mode loopback --passphrase "$SIGNING_PASSWORD") + printf '%s' "$SIGNING_PASSWORD" >"$GNUPGHOME/passphrase" + GPG_PASS_ARGS=(--pinentry-mode loopback --passphrase-file "$GNUPGHOME/passphrase") fi +# moq.repo sets gpgcheck=1, so dnf rejects any unsigned package. Sign the whole +# merged pool, not just the new artifacts: packages published before signing +# existed need it too. rpmsign skips any package already signed by this key, +# so only new or unsigned packages change and get re-uploaded. +echo ">> Sign packages..." +mapfile -t POOL < <(find "$WORK/${DIST}" -name '*.rpm') +rpmsign --addsign \ + --define "_gpg_name ${KEY_ID}" \ + --define "_gpg_sign_cmd_extra_args --batch ${GPG_PASS_ARGS[*]}" \ + "${POOL[@]}" + echo ">> Generate repodata per arch..." for arch in "${ARCHES[@]}"; do dir="$WORK/${DIST}/${arch}" From 5f41798a4ed88deddc4939996c439729a547da8e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 21:46:32 -0700 Subject: [PATCH 090/128] fix(moq-mux): signal a new time base when the DTS reserve steps the PCR back (#4574) Co-authored-by: Claude Opus 5.5 --- rs/moq-mux/src/container/ts/export.rs | 20 ++++++++++++------ rs/moq-mux/src/container/ts/export_test.rs | 24 ++++++++++++++++++---- test/ts/README.md | 2 +- test/ts/compliance.py | 24 ++++++++++++++++++---- 4 files changed, 55 insertions(+), 15 deletions(-) diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index 20308810eae..5457c6eaa17 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -150,6 +150,9 @@ pub struct Export { /// Generation of the last returned frame, updated only at the output boundary. emitted_epoch: u64, pcr_discontinuity: bool, + /// Back-off of the last PCR emitted ([`Self::pcr_at`]), so a reserve that grows past it + /// flags the next one as a new time base. + pcr_reserve: Option, /// TS packets muxed into the span that is still open. pending: Vec, /// Offsets into [`pending`](Self::pending) where a keyframe's packets begin, so @@ -682,6 +685,7 @@ impl Export { epoch: 0, emitted_epoch: 0, pcr_discontinuity: false, + pcr_reserve: None, pending: Vec::new(), keyframes: Vec::new(), queue: VecDeque::new(), @@ -1900,12 +1904,13 @@ impl Export { /// The value backs off by the largest reserve of any track, not just the PCR /// track's: every rendition's PES must decode at or after the clock, and each /// video track backs its DTS off by its own [`Reserve`]. A reserve that grows steps - /// the clock back with it; the DTS already sent stay ahead of the clock values sent - /// with them, and [`author_dts`] keeps every later DTS above those. Back off through the - /// 33-bit wrap rather than saturating: a timeline that starts inside the reserve - /// would otherwise clamp its first slots to zero and break the uniform step. The - /// wire field is a circular clock, so the masked wrapped value is the correct - /// mod-2^33 back-off. + /// the clock back with it, which only a new time base allows (ISO 13818-1 2.4.3.4), + /// so that PCR sets `discontinuity_indicator`. The DTS already sent stay ahead of + /// the clock values sent with them, and [`author_dts`] keeps every later DTS above + /// those. Back off through the 33-bit wrap rather than saturating: a timeline that + /// starts inside the reserve would otherwise clamp its first slots to zero and break + /// the uniform step. The wire field is a circular clock, so the masked wrapped value + /// is the correct mod-2^33 back-off. fn pcr_at(&mut self, index: u128, before: Option) -> anyhow::Result> { let pcr_pid = self.psi.as_ref().context("PSI not built")?.pcr_pid; let reserve = self @@ -1915,6 +1920,9 @@ impl Export { .max() .unwrap_or(DEFAULT_DTS_RESERVE); let ticks = slot_ticks(index, PCR_INTERVAL).wrapping_sub(reserve); + if self.pcr_reserve.replace(reserve).is_some_and(|last| reserve > last) { + self.pcr_discontinuity = true; + } // Nothing has gone out on this PID yet, so there is no counter to repeat and // any value starts a valid run; take the one before the next to be used. let cc = match before { diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index 0cdcb50524c..b6b4eef9857 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -2560,7 +2560,13 @@ async fn reordered_video_keeps_the_table_cadence() { assert_eq!(export.discontinuity(), 0, "a reorder is not a rewind"); assert_eq!(count_pid(&out, 0x0000), 10, "PAT once per 500ms slot, not per reorder"); assert_eq!(count_pid(&out, 0x0011), 3, "SDT once per 2s slot, not per reorder"); - assert_eq!(count_discontinuity(&out), 0, "a reorder is not a discontinuity"); + // The SPS declares no reorder depth, so the first B-frame grows the reserve once, after + // the first PCR: that one step back is a new time base, the reorders after it are not. + assert_eq!( + count_discontinuity(&out), + 1, + "only the reserve's growth restarts the clock" + ); } /// A program with more than one track marks the break once, not once per track. A @@ -5170,14 +5176,24 @@ fn assert_decodes_before_presenting(timing: &[(u64, Option)]) { } } -/// In transport order, every PES unit decodes at or after the last PCR preceding it. +/// In transport order, every PES unit decodes at or after the last PCR preceding it, and the +/// clock only steps back where a PCR signals a new time base. fn assert_decodes_after_the_clock(frames: &[Frame]) { let bytes: Vec = frames.iter().flat_map(|f| f.payload.iter().copied()).collect(); let mut reader = TsPacketReader::new(Cursor::new(bytes)); let mut last_pcr = None; while let Some(packet) = reader.read_ts_packet().unwrap() { - if let Some(pcr) = packet.adaptation_field.as_ref().and_then(|af| af.pcr) { - last_pcr = Some(pcr.as_u64() / 300); + if let Some(af) = packet.adaptation_field.as_ref() + && let Some(pcr) = af.pcr + { + let pcr = pcr.as_u64() / 300; + if let Some(last) = last_pcr { + assert!( + pcr > last || af.discontinuity_indicator, + "the clock steps back from {last} to {pcr} without a discontinuity" + ); + } + last_pcr = Some(pcr); } if let Some(TsPayload::PesStart(pes)) = packet.payload && let Some(pcr) = last_pcr diff --git a/test/ts/README.md b/test/ts/README.md index 28bcf8e3482..4fb5950b9d8 100644 --- a/test/ts/README.md +++ b/test/ts/README.md @@ -78,7 +78,7 @@ Severities: **hard** checks fail the run by default; **shape** checks report as | `psi-crc` | hard | no section dropped for a bad CRC | | `continuity` | hard | no continuity-counter discontinuities | | `pcr-presence` | hard | a PCR PID is declared and carries PCR | -| `pcr-monotonic` | hard | PCR strictly increases (one 33-bit wrap tolerated) | +| `pcr-monotonic` | hard | PCR strictly increases (one 33-bit wrap tolerated), except into a PCR that signals `discontinuity_indicator` | | `duration-fidelity` | hard | exported PCR span tracks the source's duration (round-trip only) | | `pcr-repetition` | shape | consecutive PCRs within the limit (default 40 ms) | | `pcr-jitter` | shape | per-interval PCR jitter vs the nominal bitrate (pcrverify model) | diff --git a/test/ts/compliance.py b/test/ts/compliance.py index b02f5990c06..66aae98fe7d 100755 --- a/test/ts/compliance.py +++ b/test/ts/compliance.py @@ -112,6 +112,8 @@ class Scan: pid_packets: dict[int, list[tuple[int, int]]] # (ts_index, pcr_27mhz) samples for every PID that carries PCR. pcr_by_pid: dict[int, list[tuple[int, int]]] + # ts_index of every PCR that starts a new time base (discontinuity_indicator). + pcr_new_base: set[int] def scan_packets(ts_path: str, packet_size: int) -> Scan: @@ -125,6 +127,10 @@ def scan_packets(ts_path: str, packet_size: int) -> Scan: pid_packets: dict[int, list[tuple[int, int]]] = {} pcr_by_pid: dict[int, list[tuple[int, int]]] = {} + pcr_new_base: set[int] = set() + # PIDs whose discontinuity_indicator rode a packet without a PCR, so the new time + # base starts at their next PCR (ISO 13818-1 2.4.3.5). + pending_base: set[int] = set() index = 0 offset = 0 n = len(data) @@ -147,6 +153,8 @@ def scan_packets(ts_path: str, packet_size: int) -> Scan: af_len = data[offset + 4] if af_len > 0: flags = data[offset + 5] + if flags & 0x80: + pending_base.add(pid) if (flags & 0x10) and af_len >= 7: # PCR present base = ( (data[offset + 6] << 25) @@ -157,6 +165,9 @@ def scan_packets(ts_path: str, packet_size: int) -> Scan: ) ext = ((data[offset + 10] & 0x01) << 8) | data[offset + 11] pcr_by_pid.setdefault(pid, []).append((index, base * 300 + ext)) + if pid in pending_base: + pending_base.discard(pid) + pcr_new_base.add(index) if afc in (1, 3): # Payload = 184 minus the adaptation field (its length byte + body). consumed = (1 + af_len) if afc == 3 else 0 @@ -173,6 +184,7 @@ def scan_packets(ts_path: str, packet_size: int) -> Scan: total_packets=index, pid_packets=pid_packets, pcr_by_pid=pcr_by_pid, + pcr_new_base=pcr_new_base, ) @@ -331,18 +343,22 @@ def check_pcr_presence(analysis: dict, clock_by_pid: dict[int, PcrClock]) -> Che def check_pcr_monotonic(scan: Scan) -> Check: - """PCR must strictly increase per PID (a single 33-bit wrap is tolerated).""" + """PCR must strictly increase per PID (a single 33-bit wrap is tolerated). + + Except into a PCR that signals a new time base (ISO 13818-1 2.4.3.4), which may + take any value; those are counted so a stream that leans on them still shows it. + """ breaks = 0 for _pid, samples in scan.pcr_by_pid.items(): prev = None - for _i, pcr in samples: - if prev is not None: + for i, pcr in samples: + if prev is not None and i not in scan.pcr_new_base: delta = pcr - prev # A legitimate wrap shows as a large negative jump; anything else is a fault. if delta <= 0 and not delta < -PCR_WRAP / 2: breaks += 1 prev = pcr - metrics = {"pcr_backwards": breaks} + metrics = {"pcr_backwards": breaks, "signalled_discontinuities": len(scan.pcr_new_base)} if breaks == 0: return Check("pcr-monotonic", Severity.HARD, Status.PASS, "PCR strictly increasing", metrics) return Check("pcr-monotonic", Severity.HARD, Status.FAIL, f"{breaks} backwards PCR step(s)", metrics) From 87a9177c6a91f8357538020b0726cabfbe920668 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 21:47:25 -0700 Subject: [PATCH 091/128] feat(moq-mux): estimate the catalog framerate (#4576) Co-authored-by: Claude Opus 5.5 Co-authored-by: Space Bunny Free --- rs/moq-mux/src/catalog/estimate.rs | 226 +++++++++++++++++++++++++++- rs/moq-mux/src/catalog/tracks.rs | 12 ++ rs/moq-mux/src/codec/h264/import.rs | 20 +++ rs/moq-mux/src/codec/h264/mod.rs | 77 +++++++++- rs/moq-mux/src/codec/h265/import.rs | 23 +-- rs/moq-mux/src/codec/h265/mod.rs | 35 ++--- 6 files changed, 357 insertions(+), 36 deletions(-) diff --git a/rs/moq-mux/src/catalog/estimate.rs b/rs/moq-mux/src/catalog/estimate.rs index 9455626547f..52830505b88 100644 --- a/rs/moq-mux/src/catalog/estimate.rs +++ b/rs/moq-mux/src/catalog/estimate.rs @@ -4,8 +4,29 @@ use std::time::{Duration, Instant}; use moq_net::Timestamp; -/// The window over which bitrate is averaged before it is reported. -const BITRATE_WINDOW: Duration = Duration::from_secs(1); +/// The window over which bitrate and framerate are averaged before they are reported. +const RATE_WINDOW: Duration = Duration::from_secs(1); + +/// The frame rates a measurement snaps to. Anything else (a variable-rate source's average) +/// publishes nothing, since consumers size clocks from the value (an fMP4 timescale of +/// `framerate * 1000`). +const FRAMERATES: [f64; 11] = [ + 24_000.0 / 1001.0, + 24.0, + 25.0, + 30_000.0 / 1001.0, + 30.0, + 48.0, + 50.0, + 60_000.0 / 1001.0, + 60.0, + 100.0, + 120.0, +]; + +/// How far a measurement may sit from the rate it snaps to: half the 0.1% gap between an NTSC +/// rate and its integer neighbour, so no measurement is ambiguous between them. +const FRAMERATE_TOLERANCE: f64 = 0.0005; const JITTER_WINDOW: Duration = Duration::from_secs(10); /// The catalog fields an [`Estimator`] can measure from the frames fed to it. @@ -22,6 +43,8 @@ pub struct Estimate { pub bitrate: Option, /// The most this track's minimum flush lateness has trailed the broadcast's earliest track. pub delay: Option, + /// The maximum frame rate in frames per second, when it is a standard one. + pub framerate: Option, } impl Estimate { @@ -42,9 +65,15 @@ impl Estimate { self.delay = delay.into(); self } + + /// Set the frame rate in frames per second (or clear it with `None`). + pub fn with_framerate(mut self, framerate: impl Into>) -> Self { + self.framerate = framerate.into(); + self + } } -/// Measures the catalog jitter and bitrate of one track from the frames written to it. +/// Measures the catalog jitter, bitrate, and framerate of one track from the frames written to it. /// /// A [`container::Producer`](crate::container::Producer) created through the catalog owns one, /// feeds it as you write, and publishes the result automatically. Local encoders also call @@ -85,6 +114,7 @@ impl Estimate { pub struct Estimator { jitter: Jitter, bitrate: Bitrate, + framerate: Framerate, /// This track's recent minimum flush lateness. baseline: Window, /// The recent minimum across every track sharing it. A standalone estimator's is its own, so @@ -113,6 +143,7 @@ impl Estimator { pub fn write(&mut self, timestamp: Timestamp, bytes: usize) { let timestamp = nanos(timestamp); self.bitrate.write(timestamp, bytes); + self.framerate.write(timestamp); } /// Measure when an encoder handed a frame to the transport. Only locally encoded frames should @@ -134,6 +165,7 @@ impl Estimator { /// frame) leaves the span open to fold into the next one, so nothing is lost by cutting often. pub fn cut(&mut self, end: Option) { self.bitrate.cut(end.map(nanos)); + self.framerate.cut(); } /// Discard the open bitrate span and the flush baselines, so nothing is measured across a break @@ -143,6 +175,7 @@ impl Estimator { /// pre-pause minimum would otherwise read as a delay until it left the window. pub fn discontinuity(&mut self) { self.bitrate.discontinuity(); + self.framerate.discontinuity(); self.baseline = Window::default(); self.broadcast.discontinuity(); } @@ -168,6 +201,7 @@ impl Estimator { jitter: self.jitter.current(), bitrate: self.bitrate.current(), delay: (!self.delay.is_zero()).then_some(self.delay), + framerate: self.framerate.max, } } } @@ -195,7 +229,7 @@ fn elapsed(start: u128, end: u128) -> Option { /// Tracks the maximum bitrate in bits per second, averaged over whole spans. /// /// A span's bytes are only counted once it is closed, and the average is taken over at least -/// [`BITRATE_WINDOW`] of media so a lone keyframe doesn't spike the reported value. +/// [`RATE_WINDOW`] of media so a lone keyframe doesn't spike the reported value. #[derive(Default)] struct Bitrate { span: Option, @@ -237,7 +271,7 @@ impl Bitrate { self.window_bytes = self.window_bytes.saturating_add(span.bytes); self.window_duration += duration; - if self.window_duration < BITRATE_WINDOW { + if self.window_duration < RATE_WINDOW { return; } @@ -259,6 +293,69 @@ impl Bitrate { } } +/// Tracks the maximum framerate: frames written per second of advance in the highest timestamp, +/// snapped to one of [`FRAMERATES`]. +/// +/// Not per span like [`Bitrate`]: a reordered group spans more than its own frames (an open GOP's +/// leading pictures present before its keyframe), while the highest timestamp advances one period +/// per frame whatever the order. Sampled at cuts, so every window starts and ends at the same point +/// of the group structure. +#[derive(Default)] +struct Framerate { + /// The highest timestamp written, in scale-free nanoseconds. + high: Option, + /// The highest timestamp when the window opened. + open: Option, + /// Frames written since the window opened. + frames: u64, + max: Option, +} + +impl Framerate { + fn write(&mut self, ts: u128) { + self.high = Some(self.high.map_or(ts, |high| high.max(ts))); + self.frames += 1; + } + + fn cut(&mut self) { + let Some(high) = self.high else { + return; + }; + // The first window opens at a cut too, not at the first frame, which may be a join that + // starts partway into the group structure. + let Some(open) = self.open else { + self.open = Some(high); + self.frames = 0; + return; + }; + let Some(duration) = elapsed(open, high).filter(|duration| *duration >= RATE_WINDOW) else { + return; + }; + let measured = self.frames as f64 / duration.as_secs_f64(); + let snapped = FRAMERATES + .into_iter() + .map(|rate| (rate, (measured - rate).abs() / rate)) + .filter(|(_, error)| *error <= FRAMERATE_TOLERANCE) + .min_by(|a, b| a.1.total_cmp(&b.1)) + .map(|(rate, _)| rate); + if let Some(framerate) = snapped + && self.max.is_none_or(|max| framerate > max) + { + self.max = Some(framerate); + } + self.open = Some(high); + self.frames = 0; + } + + /// Time nothing across a break in the timeline. + fn discontinuity(&mut self) { + *self = Self { + max: self.max, + ..Self::default() + }; + } +} + /// An open run of frames: everything written since the last boundary that could be timed. struct Span { /// Scale-free nanoseconds, per [`nanos`]. @@ -562,6 +659,107 @@ mod tests { assert_eq!(estimate.jitter, None); } + /// Write groups `groups` of `order.len()` frames at 25 fps, in decode order with `order` giving + /// each frame's display offset from its keyframe, cutting at every keyframe like + /// `container::Producer::write`. Group 0 starts a second in, so leading pictures stay positive. + fn feed_groups(estimator: &mut Estimator, groups: std::ops::Range, order: &[i64]) { + for group in groups { + let keyframe = 25 + (group * order.len() as u64) as i64; + for (i, &offset) in order.iter().enumerate() { + let ts = micros(((keyframe + offset) as u64) * 40_000); + if i == 0 { + estimator.cut(Some(ts)); + } + estimator.write(ts, 1_000); + } + } + } + + #[test] + fn framerate_waits_for_the_window() { + let mut estimator = Estimator::new(); + // Half a second of 25 fps. + let order: Vec = (0..12).collect(); + feed_groups(&mut estimator, 0..1, &order); + estimator.cut(None); + assert_eq!(estimator.estimate().framerate, None); + + feed_groups(&mut estimator, 1..5, &order); + assert_eq!(estimator.estimate().framerate, Some(25.0)); + } + + /// B-frames in decode order: every group presents a frame below the one written before it. + #[test] + fn framerate_counts_reordered_groups() { + let mut estimator = Estimator::new(); + // IPBB in a 24-frame closed GOP. + let mut order = vec![0]; + for quad in 0..(23 / 3) { + let base = quad * 3; + order.extend([base + 3, base + 1, base + 2]); + } + order.extend(22..24); + assert_eq!(order.len(), 24); + feed_groups(&mut estimator, 0..5, &order); + assert_eq!(estimator.estimate().framerate, Some(25.0)); + } + + /// An open GOP's leading pictures present before their keyframe, so a group spans more than + /// its own frames: timing groups by their span would read 24 frames over 27 periods. + #[test] + fn framerate_counts_leading_pictures() { + let mut estimator = Estimator::new(); + // Keyframe, then three leading B-frames presented before it, then the rest. + let mut order = vec![0, -3, -2, -1]; + order.extend(1..21); + assert_eq!(order.len(), 24); + feed_groups(&mut estimator, 0..5, &order); + assert_eq!(estimator.estimate().framerate, Some(25.0)); + } + + /// 30000/1001 fps on a 90 kHz clock: no period is a whole number of nanoseconds, and the + /// measurement is 0.1% from 30 fps. + #[test] + fn framerate_snaps_to_ntsc() { + let mut estimator = Estimator::new(); + for i in 0..300u64 { + let ts = Timestamp::from_scale(i * 3003, 90_000).unwrap(); + estimator.cut(Some(ts)); + estimator.write(ts, 1_000); + estimator.cut(None); + } + assert_eq!(estimator.estimate().framerate, Some(30_000.0 / 1001.0)); + } + + /// A variable-rate source whose windows average no standard rate publishes nothing. + #[test] + fn framerate_skips_nonstandard_rates() { + let mut estimator = Estimator::new(); + // 27 fps: 37 ms apart, give or take. + for i in 0..100u64 { + let ts = micros(i * 37_037); + estimator.cut(Some(ts)); + estimator.write(ts, 1_000); + } + assert_eq!(estimator.estimate().framerate, None); + } + + /// The highest rate over any window is reported, and a slower one doesn't lower it. + #[test] + fn framerate_reports_the_maximum() { + let mut estimator = Estimator::new(); + let order: Vec = (0..25).collect(); + feed_groups(&mut estimator, 0..3, &order); + assert_eq!(estimator.estimate().framerate, Some(25.0)); + + for i in 0..40u64 { + let ts = micros(4_000_000 + i * 41_667); + estimator.cut(Some(ts)); + estimator.write(ts, 1_000); + } + assert_eq!(estimator.estimate().framerate, Some(25.0), "24 fps doesn't lower it"); + } + /// A break in the timeline discards the open span rather than timing it across the gap, and /// resets the frame spacing so the gap is never mistaken for a frame duration. #[test] @@ -582,4 +780,22 @@ mod tests { ); assert_eq!(estimator.estimate().jitter, None, "the gap is not a frame duration"); } + + /// Frames on either side of a break are never timed across it. + #[test] + fn discontinuity_resets_the_framerate_window() { + let mut estimator = Estimator::new(); + for i in 0..10u64 { + estimator.write(micros(i * 40_000), 1_000); + } + estimator.discontinuity(); + + // Resumed 40 minutes later at 25 fps. Timed across the gap it would read ~0 fps. + for i in 0..60u64 { + let ts = micros(2_400_000_000 + i * 40_000); + estimator.cut(Some(ts)); + estimator.write(ts, 1_000); + } + assert_eq!(estimator.estimate().framerate, Some(25.0)); + } } diff --git a/rs/moq-mux/src/catalog/tracks.rs b/rs/moq-mux/src/catalog/tracks.rs index 2e040a17ba4..80e29e2fb92 100644 --- a/rs/moq-mux/src/catalog/tracks.rs +++ b/rs/moq-mux/src/catalog/tracks.rs @@ -296,11 +296,13 @@ impl RenditionConfig for hang::catalog::VideoConfig { .with_jitter(self.jitter) .with_bitrate(self.bitrate) .with_delay(self.delay) + .with_framerate(self.framerate) } fn set_estimate(&mut self, estimate: Estimate) { self.jitter = estimate.jitter; self.bitrate = estimate.bitrate; self.delay = estimate.delay; + self.framerate = estimate.framerate; } } @@ -598,6 +600,9 @@ impl> Rendition { if estimate.delay.is_none() { estimate.delay = detected.delay; } + if estimate.framerate.is_none() { + estimate.framerate = detected.framerate; + } estimate } @@ -920,6 +925,7 @@ mod tests { let config = snapshot.video.renditions.get("v").unwrap(); assert!(config.jitter.is_some(), "absent jitter should be auto-detected"); assert!(config.bitrate.is_some(), "absent bitrate should be auto-detected"); + assert_eq!(config.framerate, Some(25.0), "absent framerate should be auto-detected"); } #[test] @@ -989,6 +995,7 @@ mod tests { let hint = VideoHint { bitrate: Some(456), + framerate: Some(30.0), ..Default::default() }; let mut config = config(None, None); @@ -1000,6 +1007,11 @@ mod tests { let snapshot = catalog.snapshot(); let config = snapshot.video.renditions.get("v").unwrap(); assert_eq!(config.bitrate, Some(456), "a hinted bitrate must not be overwritten"); + assert_eq!( + config.framerate, + Some(30.0), + "a hinted framerate must not be overwritten" + ); assert!(config.jitter.is_some(), "the unhinted jitter should still be detected"); } diff --git a/rs/moq-mux/src/codec/h264/import.rs b/rs/moq-mux/src/codec/h264/import.rs index dc1ed46da5a..45787d5521f 100644 --- a/rs/moq-mux/src/codec/h264/import.rs +++ b/rs/moq-mux/src/codec/h264/import.rs @@ -273,6 +273,7 @@ fn config_from_avcc(avcc_bytes: &[u8]) -> Result { }); config.coded_width = avcc.coded_width; config.coded_height = avcc.coded_height; + config.framerate = avcc.sps.first().and_then(|sps| super::sps_framerate(sps)); config.description = Some(Bytes::copy_from_slice(avcc_bytes)); Ok(config) } @@ -290,6 +291,7 @@ fn config_from_sps(sps_nal: &[u8]) -> Result { }); config.coded_width = Some(sps.coded_width); config.coded_height = Some(sps.coded_height); + config.framerate = super::sps_framerate(sps_nal); Ok(config) } @@ -325,6 +327,24 @@ mod tests { (track, catalog) } + /// Only a fixed-rate SPS states the frame rate; without `fixed_frame_rate_flag` its tick is a + /// ceiling, left for the catalog estimator to measure. + #[test] + fn config_takes_only_a_fixed_framerate() { + use crate::codec::h264::fixtures; + + let fixed = super::super::build_avcc( + &[Bytes::from_static(fixtures::SPS_IPB)], + &[Bytes::from_static(fixtures::PPS)], + ) + .unwrap(); + assert_eq!(config(&fixed).unwrap().framerate, Some(25.0)); + + let mut inline = vec![0, 0, 0, 1]; + inline.extend_from_slice(fixtures::SPS_IPB_VARIABLE); + assert_eq!(config(&inline).unwrap().framerate, None); + } + /// An avcC initializer resolves a config with the avcC stored as `description`. #[tokio::test(start_paused = true)] async fn initialize_avc1_lands_in_catalog() { diff --git a/rs/moq-mux/src/codec/h264/mod.rs b/rs/moq-mux/src/codec/h264/mod.rs index 4340b7c02bc..bddbe199633 100644 --- a/rs/moq-mux/src/codec/h264/mod.rs +++ b/rs/moq-mux/src/codec/h264/mod.rs @@ -149,6 +149,39 @@ impl Sps { /// /// `None` when the SPS carries no VUI or no bitstream restriction, or fails to parse. pub(crate) fn sps_reorder(nal: &[u8]) -> Option { + let vui = sps_vui(nal)?; + Some(crate::codec::video::Reorder { + depth: vui.depth?, + period: vui.period, + }) +} + +/// The frame rate an SPS NAL unit fixes with `fixed_frame_rate_flag`. +/// +/// Without the flag the VUI tick only bounds the rate from above, so it is left to measurement. +/// A field-capable SPS is left out too: `pic_struct` in the slice header then decides whether a +/// tick counts a field or a frame (ITU-T H.264 E.2.1, Table E-6), and only measurement settles it. +pub(crate) fn sps_framerate(nal: &[u8]) -> Option { + let vui = sps_vui(nal)?; + if !vui.frame_only { + return None; + } + let (units, scale) = vui.period?; + Some(scale as f64 / units as f64) +} + +/// What an SPS VUI declares about picture timing. +struct Vui { + /// `frame_mbs_only_flag`: every picture is a frame, so two ticks are one frame. + frame_only: bool, + /// One frame's duration as `(units, scale)` when `fixed_frame_rate_flag` is set. + period: Option<(u64, u64)>, + /// `max_num_reorder_frames`, when the bitstream restriction is present. + depth: Option, +} + +/// `None` when the SPS carries no VUI or fails to parse. +fn sps_vui(nal: &[u8]) -> Option { if nal.len() < 4 { return None; } @@ -157,13 +190,13 @@ pub(crate) fn sps_reorder(nal: &[u8]) -> Option { if !sps.vui_parameters_present_flag { return None; } - vui_reorder(&rbsp).ok().flatten() + vui(&rbsp).ok().flatten() } /// Walk an SPS RBSP to its VUI (ITU-T H.264 7.3.2.1.1, E.1.1). `h264_parser` stops at /// `vui_parameters_present_flag` without exposing its position, so this re-reads the fields /// before it. -fn vui_reorder(rbsp: &[u8]) -> h264_parser::Result> { +fn vui(rbsp: &[u8]) -> h264_parser::Result> { use h264_parser::bitreader::BitReader; use h264_parser::eg::{read_se, read_ue}; @@ -219,7 +252,8 @@ fn vui_reorder(rbsp: &[u8]) -> h264_parser::Result h264_parser::Result Bytes { let mut buf = BytesMut::new(); for nal in nals { diff --git a/rs/moq-mux/src/codec/h265/import.rs b/rs/moq-mux/src/codec/h265/import.rs index a5607b31557..13ff53a1506 100644 --- a/rs/moq-mux/src/codec/h265/import.rs +++ b/rs/moq-mux/src/codec/h265/import.rs @@ -278,7 +278,7 @@ fn config_from_sps(sps_nal: &[u8]) -> Result { }); config.coded_width = Some(sps.rbsp.cropped_width() as u32); config.coded_height = Some(sps.rbsp.cropped_height() as u32); - config.framerate = vui_data.framerate; + config.framerate = super::sps_period(&sps.rbsp).map(|(units, scale)| scale as f64 / units as f64); config.display_aspect_width = vui_data.display_ratio_width; config.display_aspect_height = vui_data.display_ratio_height; Ok(config) @@ -303,19 +303,12 @@ fn find_sps(payload: &[u8]) -> Option { #[derive(Default)] struct VuiData { - framerate: Option, display_ratio_width: Option, display_ratio_height: Option, } impl VuiData { fn new(vui: &scuffle_h265::VuiParameters) -> Self { - // FPS = time_scale / num_units_in_tick - let framerate = vui - .vui_timing_info - .as_ref() - .map(|t| t.time_scale.get() as f64 / t.num_units_in_tick.get() as f64); - let (display_ratio_width, display_ratio_height) = match &vui.aspect_ratio_info { // Extended SAR has explicit arbitrary values for width and height. scuffle_h265::AspectRatioInfo::ExtendedSar { sar_width, sar_height } => { @@ -328,7 +321,6 @@ impl VuiData { }; VuiData { - framerate, display_ratio_width, display_ratio_height, } @@ -375,6 +367,19 @@ mod tests { (track, catalog) } + /// Only an SPS whose HRD fixes the picture rate states it; the VUI tick alone is a ceiling, + /// left for the catalog estimator to measure. + #[test] + fn config_takes_only_a_fixed_framerate() { + let mut fixed = vec![0, 0, 0, 1]; + fixed.extend_from_slice(fixtures::SPS_PYRAMID); + assert_eq!(config(&fixed).unwrap().framerate, Some(25.0)); + + let mut ceiling = vec![0, 0, 0, 1]; + ceiling.extend_from_slice(fixtures::SPS); + assert_eq!(config(&ceiling).unwrap().framerate, None); + } + /// An hvcC initializer resolves a config with the hvcC stored as `description`. /// The hvc1 analogue of the avcC test in [`crate::codec::h264`]'s importer. #[tokio::test(start_paused = true)] diff --git a/rs/moq-mux/src/codec/h265/mod.rs b/rs/moq-mux/src/codec/h265/mod.rs index ff5d51d49fe..d0f420e2745 100644 --- a/rs/moq-mux/src/codec/h265/mod.rs +++ b/rs/moq-mux/src/codec/h265/mod.rs @@ -225,28 +225,29 @@ pub(crate) fn sps_reorder(nal: &[u8]) -> Option { let highest = sps.rbsp.sps_max_sub_layers_minus1 as usize; let reorder = &sps.rbsp.sub_layer_ordering_info.sps_max_num_reorder_pics; let depth = *reorder.get(highest).or(reorder.last())?; - let period = sps - .rbsp - .vui_parameters - .as_ref() - .and_then(|vui| vui.vui_timing_info.as_ref()) - .and_then(|timing| { - let sub_layers = &timing.hrd_parameters.as_ref()?.sub_layers; - let elemental = sub_layers - .get(highest) - .or(sub_layers.last())? - .elemental_duration_in_tc_minus1?; - let units = elemental - .checked_add(1)? - .checked_mul(u64::from(timing.num_units_in_tick.get()))?; - Some((units, u64::from(timing.time_scale.get()))) - }); Some(crate::codec::video::Reorder { depth: u32::try_from(depth).ok()?, - period, + period: sps_period(&sps.rbsp), }) } +/// One picture's duration at the highest sub-layer as `(units, scale)`, when the VUI's HRD +/// parameters fix the picture rate within the CVS (ITU-T H.265 E.3.2). Without that the VUI tick +/// only bounds the rate from above. +pub(crate) fn sps_period(sps: &scuffle_h265::SpsRbsp) -> Option<(u64, u64)> { + let highest = sps.sps_max_sub_layers_minus1 as usize; + let timing = sps.vui_parameters.as_ref()?.vui_timing_info.as_ref()?; + let sub_layers = &timing.hrd_parameters.as_ref()?.sub_layers; + let elemental = sub_layers + .get(highest) + .or(sub_layers.last())? + .elemental_duration_in_tc_minus1?; + let units = elemental + .checked_add(1)? + .checked_mul(u64::from(timing.num_units_in_tick.get()))?; + Some((units, u64::from(timing.time_scale.get()))) +} + /// Annex-B → length-prefixed transmuxer; the H.265 analogue of /// [`crate::codec::h264::Avc1`]. /// From 583aac6c28be30301b23fdaa44c4d42a3b9781a3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 21:59:41 -0700 Subject: [PATCH 092/128] test(moq-net): watch mesh_withdraw's cursor from its own task (#4564) Co-authored-by: Claude Opus 5.5 --- rs/moq-net/tests/mesh_withdraw.rs | 39 +++++++++++++++++++++++-------- 1 file changed, 29 insertions(+), 10 deletions(-) diff --git a/rs/moq-net/tests/mesh_withdraw.rs b/rs/moq-net/tests/mesh_withdraw.rs index 6d91c46a8f3..37a9c349535 100644 --- a/rs/moq-net/tests/mesh_withdraw.rs +++ b/rs/moq-net/tests/mesh_withdraw.rs @@ -9,6 +9,8 @@ mod support; use std::{collections::HashMap, time::Duration}; +use tokio::sync::mpsc; + use moq_net::{Hop, Version, announce, broadcast, origin}; use support::harness::{MockPair, peer}; @@ -18,21 +20,38 @@ fn produce_origin(hop: u64) -> origin::Producer { producer } -/// Every update per prefix until the cursor goes quiet. Time is paused, so the +/// Every update per prefix until the watcher goes quiet. Time is paused, so the /// timeout fires only once every task is idle. -async fn drain(announced: &mut announce::Consumer) -> HashMap> { +async fn drain( + watched: &mut mpsc::UnboundedReceiver<(String, announce::Kind)>, +) -> HashMap> { let mut updates = HashMap::>::new(); - while let Ok(Some(update)) = tokio::time::timeout(Duration::from_secs(1), announced.next()).await { - updates.entry(update.prefix.to_string()).or_default().push(update.kind); + while let Ok(Some((prefix, kind))) = tokio::time::timeout(Duration::from_secs(1), watched.recv()).await { + updates.entry(prefix).or_default().push(kind); } updates } +/// Watch `announced` from its own task, the way a session's announce writer does: +/// it runs when woken, between the relays' own tasks, rather than only once the +/// test task is polled again, which would coalesce every intermediate update. +fn watch(mut announced: announce::Consumer) -> mpsc::UnboundedReceiver<(String, announce::Kind)> { + let (tx, rx) = mpsc::unbounded_channel(); + tokio::spawn(async move { + while let Some(update) = announced.next().await { + if tx.send((update.prefix.to_string(), update.kind)).is_err() { + break; + } + } + }); + rx +} + /// `n` relays meshed over `edges`, watched from the last one. struct Mesh { nodes: Vec, _pairs: Vec, - announced: announce::Consumer, + watched: mpsc::UnboundedReceiver<(String, announce::Kind)>, } impl Mesh { @@ -43,11 +62,11 @@ impl Mesh { for &(a, b) in edges { pairs.push(peer(version, &nodes[a], &nodes[b]).await); } - let announced = nodes.last().unwrap().consume().announced(); + let watched = watch(nodes.last().unwrap().consume().announced()); Self { nodes, _pairs: pairs, - announced, + watched, } } @@ -64,7 +83,7 @@ impl Mesh { broadcast }) .collect(); - let updates = drain(&mut self.announced).await; + let updates = drain(&mut self.watched).await; assert_eq!(updates.len(), count); for (prefix, kinds) in updates { assert_eq!(kinds[0], announce::Kind::Announced, "{prefix}: {kinds:?}"); @@ -100,7 +119,7 @@ async fn full_mesh_withdraw_retracts_once(version: &str) { let mut mesh = Mesh::new(version, 8, &full_mesh(8)).await; let broadcasts = mesh.publish(100, 0).await; drop(broadcasts); - let updates = drain(&mut mesh.announced).await; + let updates = drain(&mut mesh.watched).await; assert_eq!(updates.len(), 100); for (prefix, kinds) in updates { assert_eq!(kinds, [announce::Kind::Retracted], "{prefix}"); @@ -118,7 +137,7 @@ async fn partial_mesh_withdraw_then_republish() { let mut mesh = Mesh::new("moq-lite-06", 12, &ring_with_chords(12)).await; let broadcasts = mesh.publish(100, 0).await; drop(broadcasts); - let updates = drain(&mut mesh.announced).await; + let updates = drain(&mut mesh.watched).await; assert_eq!(updates.len(), 100); for (prefix, kinds) in updates { assert!(!kinds.last().unwrap().is_active(), "{prefix}: {kinds:?}"); From a0ccc8832fc69914cd8be072473b121b3af0824e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 22:00:57 -0700 Subject: [PATCH 093/128] docs(quest): cluster routing no longer waits on moq.pro workers (moq.pro#2080) (#4566) Co-authored-by: Claude Opus 5.5 --- quest/m1/cluster-routing.md | 1 - 1 file changed, 1 deletion(-) diff --git a/quest/m1/cluster-routing.md b/quest/m1/cluster-routing.md index 9cb6fb698ef..d15a3d77256 100644 --- a/quest/m1/cluster-routing.md +++ b/quest/m1/cluster-routing.md @@ -200,7 +200,6 @@ registry. What decides the wire: ## Required -- moq.pro workers stop electing on hop chains, reading the relay's local origin instead ([moq.pro voice-local-origin](https://github.com/moq-dev/moq.pro/blob/main/quest/m0/voice-local-origin.md)) - [Wildcard](/quest/m0/wildcard/README.md) - the longest-prefix rule, pool spread, and reply identity this selection builds on ## Related From 7f5ae43d0d76a8aa29a9b3de9f1a676612f55edb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 22:01:04 -0700 Subject: [PATCH 094/128] quest(m1): plan parked reads waking on evicted or aborted groups (#4575) Co-authored-by: Claude Opus 5.5 --- quest/m1/README.md | 1 + quest/m1/parked-read-wakes.md | 25 +++++++++++++++++++++++++ 2 files changed, 26 insertions(+) create mode 100644 quest/m1/parked-read-wakes.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 19187cea9c5..9501773df57 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -30,6 +30,7 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Watch refusal](/quest/m1/watch-refusal.md) - `` shows an origin refusal as an error instead of sitting offline - [Resumed groups](/quest/m1/resume-latest.md) - a half-delivered group ends once the new copy is past it, so a group-only reader never parks after a mid-group failover - [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 +- [Parked reads wake](/quest/m1/parked-read-wakes.md) - a read parked on an evicted or aborted group wakes and re-judges, for resume successors and plain tracks alike - [Reader end parity](/quest/m1/reader-end-parity.md) - JS readers see a track's end once the newest group reaches the declared end, as Rust readers do - [Cross-relay bursts](/quest/m1/cross-relay-bursts.md) - bursty small-group tracks cross two relays without lost groups, unanswered FETCHes, or stalls - [Request stream cancel](/quest/m1/request-stream-serve.md) - a lite publisher stops resolving a SUBSCRIBE or FETCH once the requester FINs or resets, through one wrapper that owns every request stream's reader diff --git a/quest/m1/parked-read-wakes.md b/quest/m1/parked-read-wakes.md new file mode 100644 index 00000000000..2e372aff464 --- /dev/null +++ b/quest/m1/parked-read-wakes.md @@ -0,0 +1,25 @@ +# [S] Parked reads wake + +## Goal + +A read parked on a group that is evicted or aborted always wakes and +re-judges, for resume successors and plain tracks alike, pinned by mock-time +regression tests. + +## Plan + +Follow-ups from [#4484](https://github.com/moq-dev/moq/pull/4484), which made +`resume::Successor` recompute its answer on every judgment: + +- Its regression tests cover an aborted unstamped successor only. Eviction + wakes through a different path, so add a resume-level test where the + successor is evicted before its first frame. If it already passes, this + item lands as a test. +- A stamped group that is aborted without being evicted wakes no parked + reader, on a plain track as well as a successor. It only matters under a + timestamp rewind. Reproduce it first, then wake the waiters at the source. + +Settled: one quest, since both are the same wakeup invariant in +`rs/moq-net/src/model/track.rs` and `resume.rs`. + +Public API: none. Wire: none. From c15753e2e2ce5eba4588bfaa01fedfb3e3a82146 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 22:35:37 -0700 Subject: [PATCH 095/128] fix(hls,auth): redact credentials from URLs in errors (#4536) Co-authored-by: Claude Opus 5.5 --- rs/moq-auth/src/client.rs | 46 ++++++++++++++++++++++++++++++++++++--- rs/moq-auth/src/error.rs | 8 +++++-- rs/moq-hls/src/error.rs | 22 ++++++++++++++++++- 3 files changed, 70 insertions(+), 6 deletions(-) diff --git a/rs/moq-auth/src/client.rs b/rs/moq-auth/src/client.rs index cd07c3f06a2..2ba037af41c 100644 --- a/rs/moq-auth/src/client.rs +++ b/rs/moq-auth/src/client.rs @@ -43,7 +43,7 @@ impl Client { None => false, }; if !loopback { - return Err(Error::InsecureUrl(url.to_string())); + return Err(Error::InsecureUrl(redact(&url))); } (builder, url) } @@ -53,12 +53,12 @@ impl Client { }, #[cfg(unix)] "unix" => { - let path = url.to_file_path().map_err(|()| Error::InvalidUrl(url.to_string()))?; + let path = url.to_file_path().map_err(|()| Error::InvalidUrl(redact(&url)))?; // The socket is the transport; the request target is the server's root. let target = Url::parse("http://localhost/").expect("a constant URL parses"); (builder.unix_socket(path), target) } - _ => return Err(Error::InvalidUrl(url.to_string())), + _ => return Err(Error::InvalidUrl(redact(&url))), }; Ok(Self { @@ -143,6 +143,16 @@ async fn ask(server: &S, request: &Request) -> crate::Result { Ok(grant) } +/// `url` without its userinfo, query, or fragment, any of which may carry a credential. +fn redact(url: &Url) -> String { + let mut url = url.clone(); + let _ = url.set_username(""); + let _ = url.set_password(None); + url.set_query(None); + url.set_fragment(None); + url.to_string() +} + /// The task behind a lease: re-checks on cadence and reports the end. struct Driver { server: S, @@ -458,6 +468,23 @@ mod tests { assert!(matches!(err, Error::Refused), "{err}"); } + #[tokio::test] + async fn http_error_redacts_url() { + // A freed port refuses the connection, so reqwest fails with the dialed URL attached. + let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("bind"); + let address = listener.local_addr().expect("local address"); + drop(listener); + + let url = format!("http://user:pass@{address}/?jwt=secret").parse().unwrap(); + let err = Client::new(url, None).unwrap().connect(request()).await.unwrap_err(); + + assert!(matches!(err, Error::Unavailable(_)), "unexpected error: {err}"); + let printed = format!("{err} {err:?}"); + for secret in ["jwt", "secret", "user:pass"] { + assert!(!printed.contains(secret), "error leaked {secret}: {printed}"); + } + } + #[tokio::test] async fn revalidate_runs_on_cadence_and_applies_the_reply() { let log = Log::default(); @@ -639,6 +666,19 @@ mod tests { )); #[cfg(unix)] assert!(Client::new("unix:///run/moq-auth.sock".parse().unwrap(), None).is_ok()); + + // The refused URL is reported, minus anything that may carry a credential. + for url in [ + "http://user:pass@auth.example/?jwt=secret#frag", + "ftp://user:pass@auth.example/?jwt=secret#frag", + ] { + let err = Client::new(url.parse().unwrap(), None).err().expect("refused"); + let printed = format!("{err} {err:?}"); + assert!(printed.contains("auth.example/"), "{printed}"); + for secret in ["jwt", "secret", "user", "pass", "frag"] { + assert!(!printed.contains(secret), "error leaked {secret}: {printed}"); + } + } } /// Backoff leaves the driver in this same state (nothing in flight, a timer armed), diff --git a/rs/moq-auth/src/error.rs b/rs/moq-auth/src/error.rs index fcd36d3496d..c32d0d06b16 100644 --- a/rs/moq-auth/src/error.rs +++ b/rs/moq-auth/src/error.rs @@ -178,8 +178,12 @@ from_message! { } #[cfg(feature = "client")] -from_message! { - reqwest::Error => Unavailable, +impl From for Error { + fn from(err: reqwest::Error) -> Self { + // reqwest prints the full URL in its error, and a dialed URL can carry + // credentials in its query or userinfo. + Self::Unavailable(message(err.without_url())) + } } pub type Result = std::result::Result; diff --git a/rs/moq-hls/src/error.rs b/rs/moq-hls/src/error.rs index a87420bcd32..2d909b79601 100644 --- a/rs/moq-hls/src/error.rs +++ b/rs/moq-hls/src/error.rs @@ -141,7 +141,9 @@ impl Error { impl From for Error { fn from(err: reqwest::Error) -> Self { - Error::Reqwest(std::sync::Arc::new(err)) + // reqwest prints the full URL in its error, and a playlist or segment URL + // routinely carries a signed token in its query. + Error::Reqwest(std::sync::Arc::new(err.without_url())) } } @@ -166,4 +168,22 @@ mod tests { assert_eq!(Error::ParsePlaylist("not a playlist".to_string()).status(), None); assert_eq!(Error::Moq(moq_net::Error::Transport("lost".to_string())).status(), None); } + + #[tokio::test] + async fn http_error_redacts_url() { + // A freed port refuses the connection, so reqwest fails with the dialed URL attached. + let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("bind"); + let address = listener.local_addr().expect("local address"); + drop(listener); + + let err: Error = reqwest::get(format!("http://user:pass@{address}/media.m3u8?jwt=secret")) + .await + .expect_err("dial a closed port") + .into(); + + let printed = format!("{err} {err:?}"); + for secret in ["jwt", "secret", "user:pass"] { + assert!(!printed.contains(secret), "error leaked {secret}: {printed}"); + } + } } From e5239631b7ecdef60aff02132a62fd3155329fc7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 22:42:56 -0700 Subject: [PATCH 096/128] docs: one rpm repo command that works on DNF4 and DNF5 (#4567) Co-authored-by: Claude Opus 5.5 --- doc/setup/install.md | 5 +---- rs/moq-gst/README.md | 2 +- rs/moq-relay/README.md | 2 +- 3 files changed, 3 insertions(+), 6 deletions(-) diff --git a/doc/setup/install.md b/doc/setup/install.md index ff5b9877ebe..83a5e9ce0f8 100644 --- a/doc/setup/install.md +++ b/doc/setup/install.md @@ -64,10 +64,7 @@ sudo apt install moq-relay moq gstreamer1.0-moq Fedora 39+, RHEL 9, Rocky 9, AlmaLinux 9. On openSUSE use `zypper addrepo`. ```bash -# DNF4, including RHEL 9 -sudo dnf config-manager --add-repo https://rpm.moq.dev/moq.repo -# DNF5 -sudo dnf config-manager addrepo --from-repofile https://rpm.moq.dev/moq.repo +sudo curl -fsSL https://rpm.moq.dev/moq.repo -o /etc/yum.repos.d/moq.repo sudo dnf install moq-relay moq gstreamer1-moq ``` diff --git a/rs/moq-gst/README.md b/rs/moq-gst/README.md index d7dde7b85f0..ffd42f952c7 100644 --- a/rs/moq-gst/README.md +++ b/rs/moq-gst/README.md @@ -27,7 +27,7 @@ sudo apt update && sudo apt install gstreamer1.0-moq ### Fedora / RHEL / Rocky / AlmaLinux ```bash -sudo dnf config-manager --add-repo https://rpm.moq.dev/moq.repo +sudo curl -fsSL https://rpm.moq.dev/moq.repo -o /etc/yum.repos.d/moq.repo sudo dnf install gstreamer1-moq ``` diff --git a/rs/moq-relay/README.md b/rs/moq-relay/README.md index 888b10a8d71..f1cac529ad2 100644 --- a/rs/moq-relay/README.md +++ b/rs/moq-relay/README.md @@ -26,7 +26,7 @@ walkthrough. ### Fedora / RHEL / Rocky / AlmaLinux ```bash -sudo dnf config-manager --add-repo https://rpm.moq.dev/moq.repo +sudo curl -fsSL https://rpm.moq.dev/moq.repo -o /etc/yum.repos.d/moq.repo sudo dnf install moq-relay ``` From 6f1a9e33ede8f85bb8f262fe646d9437deec65e2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 29 Sep 2026 22:55:44 -0700 Subject: [PATCH 097/128] feat(srt): select a program of a multi-program feed (#4569) Co-authored-by: Claude Opus 5.5 --- doc/bin/cli.md | 1 + doc/bin/srt.md | 9 + quest/m1/ts-psi-reassembly.md | 6 +- rs/moq-cli/src/args.rs | 23 ++- rs/moq-cli/src/main.rs | 6 +- rs/moq-cli/src/publish.rs | 179 +----------------- rs/moq-cli/src/srt.rs | 72 ++++++- rs/moq-mux/src/container/ts/import.rs | 48 +---- rs/moq-mux/src/container/ts/mod.rs | 2 + rs/moq-mux/src/container/ts/programs.rs | 242 ++++++++++++++++++++++++ rs/moq-srt/README.md | 15 +- rs/moq-srt/src/dial.rs | 15 +- rs/moq-srt/src/lib.rs | 1 + rs/moq-srt/src/listen.rs | 16 +- rs/moq-srt/src/server.rs | 17 +- rs/moq-srt/src/ts.rs | 219 +++++++++++++++++---- 16 files changed, 587 insertions(+), 284 deletions(-) create mode 100644 rs/moq-mux/src/container/ts/programs.rs diff --git a/doc/bin/cli.md b/doc/bin/cli.md index 9c5d484e052..65c66fa6a8b 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -86,6 +86,7 @@ a PAT that adds a program mid-stream ends the import the same way. the first PAT lists as its own broadcast, with its own clock and catalog, keeping the catalog suffix last: `--broadcast event.hang` publishes `event/1.hang`, `event/2.hang`, and so on. `export ts` writes one program per broadcast. +`import srt` takes the same `--program`. ```bash moq --connect https://relay.example.com/anon --broadcast event.hang import ts --program all < mux.ts diff --git a/doc/bin/srt.md b/doc/bin/srt.md index 141ea5cbb46..a2abd327ab5 100644 --- a/doc/bin/srt.md +++ b/doc/bin/srt.md @@ -25,6 +25,15 @@ ffplay srt://localhost:9000 moq --connect https://relay.example.com/anon --broadcast event.hang import srt --connect 'srt://encoder.example.com:9000?streamid=live/cam' ``` +A multi-program feed is refused, as with `import ts`, unless `--program` +picks one: `--program 2` imports program 2 alone, and `--program all` +publishes each program as its own broadcast (`event.hang` becomes +`event/1.hang`, `event/2.hang`, and so on). + +```bash +moq --connect https://relay.example.com/anon --broadcast event.hang import srt --listen '[::]:9000' --program all +``` + `--latency` sets the SRT receive buffer and doubles as the skip threshold on export. Export paces each SRT payload on the media clock, and re-anchors that pacing on a declared marker, so a restarted timeline plays out from the diff --git a/quest/m1/ts-psi-reassembly.md b/quest/m1/ts-psi-reassembly.md index 665a76a8da3..d5fa4556ed3 100644 --- a/quest/m1/ts-psi-reassembly.md +++ b/quest/m1/ts-psi-reassembly.md @@ -7,7 +7,7 @@ starts after a nonzero `pointer_field`, instead of aborting the import. Today the `mpeg2ts` 0.6.1 reader parses PSI from a single packet and rejects a nonzero `pointer_field`, and its error ends the whole import, so a valid long PMT (many audio languages, long descriptors) or a PAT with more than about 40 programs -cannot be imported. `ts::programs()` finds such a PAT too. +cannot be imported. `ts::Programs` finds such a PAT too. ## Plan @@ -53,13 +53,13 @@ Settled decisions: is `#[non_exhaustive]`, so the new field is additive; its docs (today per elementary stream) and `is_empty` widen to cover it, and `ts::stats::Log` reports it. -- `ts::programs()` reads through the same PAT path, so a PAT spanning packets +- `ts::Programs` reads through the same PAT path, so a PAT spanning packets is found before any program publishes. - One quest, because the demux refactor alone changes nothing observable. Keep every existing TS import test and fixture passing unchanged. Add tests for a PMT spanning two packets, a PAT behind a nonzero `pointer_field`, a -multi-packet PAT with enough programs to need it (read by `ts::programs()` and +multi-packet PAT with enough programs to need it (read by `ts::Programs` and by `with_program`), and a PAT and a PMT with a corrupt CRC, each between good repetitions, that is dropped and counted once while the import keeps its previous layout and a later good PMT revision still applies. A positive diff --git a/rs/moq-cli/src/args.rs b/rs/moq-cli/src/args.rs index b2c659e1eb5..733a4eaff1b 100644 --- a/rs/moq-cli/src/args.rs +++ b/rs/moq-cli/src/args.rs @@ -747,7 +747,7 @@ pub enum ImportSource { /// RTMP: pull a remote play (`--connect`) or accept incoming publishes (`--listen`). Rtmp(crate::rtmp::Args), /// SRT: pull a remote stream (`--connect`) or accept incoming publishes (`--listen`). - Srt(crate::srt::Args), + Srt(crate::srt::ImportArgs), /// WebRTC: WHEP client pulling a remote (`--connect`) or WHIP server accepting publishes (`--listen`). Rtc(crate::rtc::Args), /// Capture a local source (camera, display, window, app, microphone) and @@ -782,7 +782,7 @@ pub struct TsImport { pub program: Option, } -/// An `import ts --program` value. +/// An `import ts --program` or `import srt --program` value. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum TsProgram { /// The program with this PAT program number. @@ -1058,6 +1058,25 @@ mod tests { assert_eq!(program("two"), None); } + /// `import srt` takes the same `--program` as `import ts`; `export srt` has no program to pick. + #[test] + fn import_srt_takes_a_program() { + let cli = + Invocation::try_parse_from(["moq", "import", "srt", "--listen", "[::]:9000", "--program", "all"]).unwrap(); + let Command::Import(import) = &cli.stages[0] else { + panic!("an import stage"); + }; + let ImportSource::Srt(args) = &import.source else { + panic!("an import srt stage"); + }; + assert_eq!(args.program(), Some(moq_srt::Program::All)); + assert!(args.endpoint.listen.is_some()); + + assert!( + Invocation::try_parse_from(["moq", "export", "srt", "--listen", "[::]:9000", "--program", "2"]).is_err() + ); + } + /// A released spelling is refused, and the error names what to write instead. /// /// The alternative is what this replaced: the flag parsed onto a hidden field, diff --git a/rs/moq-cli/src/main.rs b/rs/moq-cli/src/main.rs index d339abe70c6..fd1bb72bf27 100644 --- a/rs/moq-cli/src/main.rs +++ b/rs/moq-cli/src/main.rs @@ -661,11 +661,13 @@ fn spawn_import( } } ImportSource::Srt(srt) => { + let program = srt.program(); + let srt = srt.endpoint; if let Some(addr) = srt.listen { let name = require_broadcast(name, "import srt --listen")?; - tasks.spawn(srt::listen_import(target(name), addr, srt.latency.into_std())); + tasks.spawn(srt::listen_import(target(name), addr, srt.latency.into_std(), program)); } else if let Some(url) = srt.connect { - tasks.spawn(srt::connect_import(target(name), url, srt.latency.into_std())); + tasks.spawn(srt::connect_import(target(name), url, srt.latency.into_std(), program)); } } ImportSource::Rtc(rtc) => { diff --git a/rs/moq-cli/src/publish.rs b/rs/moq-cli/src/publish.rs index 5bf7c089160..3dc1adf9632 100644 --- a/rs/moq-cli/src/publish.rs +++ b/rs/moq-cli/src/publish.rs @@ -142,7 +142,7 @@ enum PublishDecoder { // verbatim, so it uses the `mpegts` catalog extension rather than the media-only `()`. Ts(Box>), /// `import ts --program all`: one importer, broadcast, and catalog per program. - TsPrograms(Box), + TsPrograms(Box), Flv(Box), } @@ -218,7 +218,7 @@ fn suggest_program(err: anyhow::Error) -> anyhow::Error { enum PublishCatalog { Media(moq_mux::catalog::Producer), Ts(moq_mux::catalog::Producer), - /// `import ts --program all`: each program's catalog, finished by [`TsPrograms::finish`]. + /// `import ts --program all`: each program's catalog, finished by [`ts::Programs::finish`]. TsPrograms, } @@ -253,117 +253,6 @@ fn ts_import( Ok((import, catalog)) } -/// One program's broadcast under `import ts --program all`. -struct ProgramImport { - /// Keeps the origin-created broadcast alive; the importer's clone doesn't. - _broadcast: moq_net::broadcast::Producer, - import: ts::Import, - catalog: moq_mux::catalog::Producer, -} - -/// `import ts --program all`: every program the first PAT lists, each published as its own -/// broadcast on its own clock and catalog. -/// -/// Input ahead of that PAT is dropped, as a single importer drops media ahead of its PSI. A -/// program a later PAT adds is not published; one it removes ends the import. -struct TsPrograms { - origin: moq_net::origin::Producer, - name: String, - config: moq_mux::catalog::Config, - /// Input held until it contains a whole PAT. - pending: Vec, - /// Empty until the PAT arrives. - programs: Vec, -} - -impl TsPrograms { - fn new(origin: moq_net::origin::Producer, name: String, config: moq_mux::catalog::Config) -> Self { - Self { - origin, - name, - config, - pending: Vec::new(), - programs: Vec::new(), - } - } - - fn decode(&mut self, chunk: &[u8]) -> anyhow::Result<()> { - if !self.programs.is_empty() { - return self.feed(chunk); - } - self.pending.extend_from_slice(chunk); - let Some(programs) = ts::programs(&self.pending).filter(|programs| !programs.is_empty()) else { - // Only a packet's worth of tail can still hold the start of the PAT. - let keep = self.pending.len().saturating_sub(TS_PACKET_SIZE - 1); - self.pending.drain(..keep); - return Ok(()); - }; - for program in programs { - let name = program_broadcast(&self.name, program); - let mut broadcast = self - .origin - .create_broadcast(&name) - .with_context(|| format!("failed to create broadcast {name}"))?; - let (import, catalog) = ts_import(&mut broadcast, self.config.clone(), Some(program))?; - broadcast - .announce(Default::default()) - .with_context(|| format!("failed to announce broadcast {name}"))?; - self.programs.push(ProgramImport { - _broadcast: broadcast, - import, - catalog, - }); - } - let pending = std::mem::take(&mut self.pending); - self.feed(&pending) - } - - fn feed(&mut self, chunk: &[u8]) -> anyhow::Result<()> { - for program in &mut self.programs { - program.import.decode(chunk)?; - } - Ok(()) - } - - /// Every program's counters in one map: PIDs are unique across a multiplex. - fn stats(&self) -> ts::Stats { - let mut stats = ts::Stats::default(); - for program in &self.programs { - stats.streams.extend(program.import.stats().streams); - } - stats - } - - /// Finish each program's tracks, then its catalog while it still lists them. - fn finish(&mut self) -> anyhow::Result<()> { - for program in &mut self.programs { - program.import.finish()?; - program.catalog.finish()?; - } - Ok(()) - } - - fn abort(self, err: moq_net::Error) { - for program in self.programs { - program.import.abort(err.clone()); - } - } -} - -const TS_PACKET_SIZE: usize = 188; - -/// The broadcast one program of `name` publishes on, keeping the catalog suffix last so format -/// detection still sees it: `event.hang` becomes `event/2.hang`. -fn program_broadcast(name: &str, program: u16) -> String { - match moq_mux::catalog::CatalogFormat::detect(name) { - Some(format) => { - let stem = &name[..name.len() - format.extension().len()]; - format!("{stem}/{program}{}", format.extension()) - } - None => format!("{name}/{program}"), - } -} - // Exactly one Source exists per process, so the size gap between the small // Stream variant and the larger Capture config is irrelevant. #[allow(clippy::large_enum_variant)] @@ -460,7 +349,7 @@ impl Publish { pub fn ts_programs(origin: moq_net::origin::Producer, name: String, config: moq_mux::catalog::Config) -> Self { Self { source: Source::Stream { - decoder: PublishDecoder::TsPrograms(Box::new(TsPrograms::new(origin, name, config))), + decoder: PublishDecoder::TsPrograms(Box::new(ts::Programs::new(origin, name, config).live())), catalog: PublishCatalog::TsPrograms, }, broadcast: None, @@ -1031,13 +920,6 @@ mod tests { assert_eq!(last.audio.renditions.len(), 1, "the audio rendition is still listed"); } - #[test] - fn program_broadcasts_keep_the_catalog_suffix_last() { - assert_eq!(program_broadcast("event.hang", 2), "event/2.hang"); - assert_eq!(program_broadcast("demo/event.msf", 7), "demo/event/7.msf"); - assert_eq!(program_broadcast("event", 1), "event/1"); - } - /// A PAT listing two programs, then one MP2 PES of each: program 1 on PID `0x61` at 1 s /// with fill bytes `0xAA`/`0xBB`, program 2 on PID `0x71` an hour later with `0xCC`/`0xDD`. fn two_programs() -> Vec { @@ -1145,61 +1027,6 @@ mod tests { assert!(err.contains("--program") && err.contains("programs (1, 2)"), "{err}"); } - /// `import ts --program all` holds the input until the PAT is whole, then publishes each - /// program as its own broadcast carrying only that program, live on its own first frame - /// rather than an hour apart on one shared clock. - #[tokio::test] - async fn every_program_publishes_its_own_broadcast() { - let origin = moq_tokio::origin::spawn(); - let ago = Duration::from_secs(60); - let clock = moq_mux::Clock::at(std::time::Instant::now() - ago, std::time::SystemTime::now() - ago).unwrap(); - let config = moq_mux::catalog::Config::default().with_clock(clock); - let publish = Publish::ts_programs(origin.clone(), "event.hang".to_string(), config); - let Source::Stream { - decoder: PublishDecoder::TsPrograms(mut programs), - .. - } = publish.source - else { - panic!("expected the per-program decoder"); - }; - - let input = two_programs(); - let before = clock.now(); - programs.decode(&input[..100]).unwrap(); - assert!( - programs.programs.is_empty(), - "no program is known before the PAT is whole" - ); - programs.decode(&input[100..]).unwrap(); - programs.finish().unwrap(); - let after = clock.now(); - - for (path, fills) in [("event/1.hang", [0xAA, 0xBB]), ("event/2.hang", [0xCC, 0xDD])] { - let consumer = moq_mux::Source::new(origin.consume(), path).broadcast().await.unwrap(); - let catalog = hang::catalog::Catalog::<()>::subscribe(&consumer) - .await - .unwrap() - .next() - .await - .unwrap() - .expect("a catalog"); - let renditions: Vec<_> = catalog.audio.renditions.iter().collect(); - assert_eq!(renditions.len(), 1, "{path} carries its own program's one stream"); - let (name, config) = renditions[0]; - let track = consumer.track(name).unwrap().subscribe(None).await.unwrap(); - let container = Container::try_from(config).unwrap(); - let frame = Consumer::new(track, container).read().await.unwrap().expect("a frame"); - assert!(fills.contains(&frame.payload[4]), "{path} carries only its own program"); - let skew = Duration::from_secs(2).as_micros(); - assert!( - before.as_micros() - skew <= frame.timestamp.as_micros() - && frame.timestamp.as_micros() <= after.as_micros() + skew, - "{path} is live on arrival: {:?} not in {before:?}..={after:?}", - frame.timestamp - ); - } - } - /// Read the first frame of a verbatim track back as raw bytes. async fn read_frame(consumer: &moq_net::broadcast::Consumer, name: &str) -> Vec { let track = consumer.track(name).unwrap().subscribe(None).await.unwrap(); diff --git a/rs/moq-cli/src/srt.rs b/rs/moq-cli/src/srt.rs index 7afbe3ff7fc..35993e691dd 100644 --- a/rs/moq-cli/src/srt.rs +++ b/rs/moq-cli/src/srt.rs @@ -10,6 +10,7 @@ use moq_srt::{Reject, Request, Server}; use moq_tokio::RedactedUrl; use url::Url; +use crate::args::TsProgram; use crate::moq::{ImportTarget, notify_ready}; /// SRT endpoint args: exactly one of `--connect` (dial) / `--listen` (bind). @@ -31,8 +32,49 @@ pub struct Args { pub latency: crate::duration::Duration, } +/// SRT import args: the endpoint, plus which programs of a multiplex to publish. +#[derive(usage::Args, Clone)] +#[usage(unknown_flags = "error", args_override_self = false)] +pub struct ImportArgs { + #[usage(flatten)] + pub endpoint: Args, + + /// Import one program of a multi-program feed, by its PAT program number, or `all` to + /// publish each program as its own broadcast (`event.hang` becomes `event/1.hang`, + /// `event/2.hang`, ...). Without it, a feed carrying more than one program is refused. + #[usage(long)] + pub program: Option, +} + +impl ImportArgs { + /// The library's selection for `--program`. + pub fn program(&self) -> Option { + self.program.map(|program| match program { + TsProgram::One(program) => moq_srt::Program::One(program), + TsProgram::All => moq_srt::Program::All, + }) + } +} + +/// Point a multi-program refusal at the flag that resolves it. +fn suggest_program(err: moq_srt::Error) -> anyhow::Error { + let multiplex = matches!(&err, moq_srt::Error::Mux(moq_mux::Error::Other(inner)) + if inner.is::()); + let err = anyhow::Error::from(err); + if multiplex { + err.context("choose one with `--program `, or publish each with `--program all`") + } else { + err + } +} + /// Accept incoming SRT publishes into the Origin as `target.name`; reject requests (import). -pub async fn listen_import(target: ImportTarget, addr: SocketAddr, latency: Duration) -> anyhow::Result<()> { +pub async fn listen_import( + target: ImportTarget, + addr: SocketAddr, + latency: Duration, + program: Option, +) -> anyhow::Result<()> { let ImportTarget { origin, name, @@ -53,10 +95,12 @@ pub async fn listen_import(target: ImportTarget, addr: SocketAddr, latency: Dura if let Err(err) = publish .with_max_age(max_age) .with_bandwidth(bandwidth) + .with_program(program) .accept(&origin, &name) .await { - tracing::warn!(%name, %err, "SRT ingest ended with error"); + let err = suggest_program(err); + tracing::warn!(%name, err = format!("{err:#}"), "SRT ingest ended with error"); } }); } @@ -107,7 +151,12 @@ pub async fn listen_export( } /// Dial a remote SRT server and pull its stream into the Origin under `target.name` (import). -pub async fn connect_import(target: ImportTarget, url: Url, latency: Duration) -> anyhow::Result<()> { +pub async fn connect_import( + target: ImportTarget, + url: Url, + latency: Duration, + program: Option, +) -> anyhow::Result<()> { let (addr, resource) = parse_url(&url).await?; let name = &target.name; tracing::info!(url = %RedactedUrl::new(&url), %name, "SRT client pulling"); @@ -116,8 +165,9 @@ pub async fn connect_import(target: ImportTarget, url: Url, latency: Duration) - let client = moq_srt::Client::new(addr, resource) .with_latency(latency) .with_max_age(target.max_age) - .with_bandwidth(target.bandwidth); - Ok(client.pull(&target.origin, name).await?) + .with_bandwidth(target.bandwidth) + .with_program(program); + client.pull(&target.origin, name).await.map_err(suggest_program) } /// Push a broadcast from the Origin to a remote SRT server (export). @@ -184,6 +234,18 @@ mod tests { assert!(parse("udp://127.0.0.1:9000").await.is_err()); } + /// A multiplex refusal names the flag that resolves it; other errors pass through unchanged. + #[test] + fn a_multiplex_suggests_the_program_flag() { + let refused = moq_mux::container::ts::MultipleProgramsError { programs: vec![1, 2] }; + let err = suggest_program(moq_srt::Error::Mux(anyhow::Error::from(refused).into())); + let err = format!("{err:#}"); + assert!(err.contains("--program") && err.contains("programs (1, 2)"), "{err}"); + + let err = format!("{:#}", suggest_program(moq_srt::Error::ListenerClosed)); + assert!(!err.contains("--program"), "{err}"); + } + #[tokio::test] async fn requires_port_and_resource() { assert!(parse("srt://127.0.0.1").await.is_err()); diff --git a/rs/moq-mux/src/container/ts/import.rs b/rs/moq-mux/src/container/ts/import.rs index d23e1160ef5..5f4c10ef233 100644 --- a/rs/moq-mux/src/container/ts/import.rs +++ b/rs/moq-mux/src/container/ts/import.rs @@ -1000,7 +1000,8 @@ impl Import { /// A PAT listed more than one program, and the [`Import`] was not told which one to take. /// /// Importing them all onto one broadcast would put unrelated clocks on one timeline, so the -/// import stops instead. Pick one with [`Import::with_program`]. +/// import stops instead. Pick one with [`Import::with_program`], or import each as its own +/// broadcast with [`Programs`](super::Programs). #[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)] #[error("transport stream carries {} programs ({})", .programs.len(), list_programs(.programs))] pub struct MultipleProgramsError { @@ -1012,36 +1013,6 @@ fn list_programs(programs: &[u16]) -> String { programs.iter().map(u16::to_string).collect::>().join(", ") } -/// The program numbers listed by the first whole PAT in `data`, in PAT order, or `None` if -/// there is none yet. -/// -/// For choosing importers before any exists: each [`Import`] reads the PAT itself. -pub fn programs(data: &[u8]) -> Option> { - let mut off = 0; - while let Some(rel) = memchr::memchr(0x47, &data[off..]) { - off += rel; - let packet = data.get(off..off + TsPacket::SIZE)?; - // PID 0 opening a section. The section CRC rejects a sync byte found in payload. - if packet[1] & 0x5f == 0x40 - && packet[2] == 0 - && let Ok(Some(TsPacket { - payload: Some(TsPayload::Pat(pat)), - .. - })) = TsPacketReader::new(packet).read_ts_packet() - { - return Some( - pat.table - .iter() - .map(|entry| entry.program_num) - .filter(|&program| program != 0) - .collect(), - ); - } - off += 1; - } - None -} - /// What each demuxed elementary stream delivered, and the audio frame sync it lost or could /// not verify, keyed by elementary stream PID. /// @@ -3097,7 +3068,7 @@ impl Read for Feed { } #[cfg(test)] -mod test { +pub(super) mod test { use std::collections::BTreeMap; use std::time::Duration; @@ -5424,7 +5395,7 @@ mod test { /// A two-program multiplex whose clocks sit an hour apart: program 1's MP2 on /// `0x0061` starts at 1 s, program 2's on `0x0071` at 3601 s. - fn two_programs() -> Vec { + pub(in crate::container::ts) fn two_programs() -> Vec { let mut data = synth_programs( &[ (1, 0x0100, &[(StreamType::Mpeg1Audio, 0x0061)]), @@ -5504,17 +5475,6 @@ mod test { assert!(err.contains("no program 3") && err.contains("1, 2"), "{err}"); } - #[test] - fn programs_reads_the_first_whole_pat() { - let data = two_programs(); - assert_eq!(super::programs(&data), Some(vec![1, 2])); - // A sync byte in leading junk is skipped; a truncated PAT is not a PAT yet. - let mut shifted = vec![0x47, 0x40, 0x00, 0x10]; - shifted.extend_from_slice(&data); - assert_eq!(super::programs(&shifted), Some(vec![1, 2])); - assert_eq!(super::programs(&data[..100]), None); - } - /// Two MP2 renditions, the first of which the PMT designates as the PCR PID. const PCR_PID: u16 = 0x0061; const PEER_PID: u16 = 0x0062; diff --git a/rs/moq-mux/src/container/ts/mod.rs b/rs/moq-mux/src/container/ts/mod.rs index da0158c5b10..05858df90f1 100644 --- a/rs/moq-mux/src/container/ts/mod.rs +++ b/rs/moq-mux/src/container/ts/mod.rs @@ -22,6 +22,7 @@ mod adts; mod export; mod import; mod mux_rate; +mod programs; mod si; // The `mpegts` catalog section (per-track PID + descriptors plus verbatim carriage @@ -32,6 +33,7 @@ mod catalog; pub use catalog::{Catalog, Descriptor, Ext, Framing, Mpegts, Program, SiEntry, Track, Verbatim}; pub use export::*; pub use import::*; +pub use programs::Programs; pub mod stats; diff --git a/rs/moq-mux/src/container/ts/programs.rs b/rs/moq-mux/src/container/ts/programs.rs new file mode 100644 index 00000000000..8f2a139b74f --- /dev/null +++ b/rs/moq-mux/src/container/ts/programs.rs @@ -0,0 +1,242 @@ +//! Every program of a multiplex, each imported as its own broadcast. + +use anyhow::Context; +use mpeg2ts::ts::{ReadTsPacket, TsPacket, TsPacketReader, TsPayload}; + +use super::{Ext, Import, Stats}; +use crate::catalog; + +/// Imports every program the first PAT lists, each as its own broadcast on `origin`, with its +/// own clock and catalog. +/// +/// Program `n` of `event.hang` publishes on `event/n.hang`, keeping the catalog suffix last so +/// format detection still sees it; a name without one gains a plain `/n`. Input ahead of that +/// PAT is dropped, as a single [`Import`] drops media ahead of its PSI. A program a later PAT +/// adds is not published; one it removes ends the import. +pub struct Programs { + origin: moq_net::origin::Producer, + name: moq_net::PathOwned, + config: catalog::Config, + live: bool, + /// Input held until it contains a whole PAT. + pending: Vec, + /// Empty until the PAT arrives. + programs: Vec, +} + +/// One program's broadcast. +struct Program { + /// Keeps the origin-created broadcast alive; the importer's clone doesn't. + _broadcast: moq_net::broadcast::Producer, + import: Import, + catalog: catalog::Producer, +} + +impl Programs { + /// Split the multiplex into broadcasts named after `name`, each catalog built from `config`. + pub fn new(origin: moq_net::origin::Producer, name: impl moq_net::AsPath, config: catalog::Config) -> Self { + Self { + origin, + name: name.as_path().to_owned(), + config, + live: false, + pending: Vec::new(), + programs: Vec::new(), + } + } + + /// Publish each program on its broadcast's clock, as [`Import::live`] does. + pub fn live(mut self) -> Self { + self.live = true; + self + } + + /// Demux a chunk of the multiplex. A trailing partial packet is retained for the next call. + pub fn decode(&mut self, data: &[u8]) -> anyhow::Result<()> { + if !self.programs.is_empty() { + return self.feed(data); + } + self.pending.extend_from_slice(data); + let Some(programs) = pat_programs(&self.pending).filter(|programs| !programs.is_empty()) else { + // Only a packet's worth of tail can still hold the start of the PAT. + let keep = self.pending.len().saturating_sub(TsPacket::SIZE - 1); + self.pending.drain(..keep); + return Ok(()); + }; + for program in programs { + let name = program_broadcast(self.name.as_str(), program); + let mut broadcast = self + .origin + .create_broadcast(&name) + .with_context(|| format!("failed to create broadcast {name}"))?; + // TS carries undecoded elementary streams verbatim, so each catalog carries the + // `mpegts` extension, and owns its broadcast's catalog tracks. + let config = self + .config + .clone() + .with_catalog(catalog::hang::Catalog::::default()); + let catalog = catalog::Producer::new(&mut broadcast, config)?; + let mut import = Import::new(broadcast.clone(), catalog.reserve()).with_program(program); + if self.live { + import = import.live(); + } + broadcast + .announce(Default::default()) + .with_context(|| format!("failed to announce broadcast {name}"))?; + self.programs.push(Program { + _broadcast: broadcast, + import, + catalog, + }); + } + let pending = std::mem::take(&mut self.pending); + self.feed(&pending) + } + + fn feed(&mut self, data: &[u8]) -> anyhow::Result<()> { + for program in &mut self.programs { + program.import.decode(data)?; + } + Ok(()) + } + + /// Every program's counters in one map: PIDs are unique across a multiplex. + pub fn stats(&self) -> Stats { + let mut stats = Stats::default(); + for program in &self.programs { + stats.streams.extend(program.import.stats().streams); + } + stats + } + + /// Finish each program's tracks, then its catalog while it still lists them. + pub fn finish(&mut self) -> anyhow::Result<()> { + for program in &mut self.programs { + program.import.finish()?; + program.catalog.finish()?; + } + Ok(()) + } + + /// Abort every program's tracks with `err`, as [`Import::abort`] does. Consumes the importer. + pub fn abort(self, err: moq_net::Error) { + for program in self.programs { + program.import.abort(err.clone()); + } + } +} + +/// The broadcast one program of `name` publishes on: `event.hang` becomes `event/2.hang`. +fn program_broadcast(name: &str, program: u16) -> String { + match catalog::CatalogFormat::detect(name) { + Some(format) => { + let stem = &name[..name.len() - format.extension().len()]; + format!("{stem}/{program}{}", format.extension()) + } + None => format!("{name}/{program}"), + } +} + +/// The program numbers listed by the first whole PAT in `data`, in PAT order, or `None` if +/// there is none yet. +fn pat_programs(data: &[u8]) -> Option> { + let mut off = 0; + while let Some(rel) = memchr::memchr(0x47, &data[off..]) { + off += rel; + let packet = data.get(off..off + TsPacket::SIZE)?; + // PID 0 opening a section. The section CRC rejects a sync byte found in payload. + if packet[1] & 0x5f == 0x40 + && packet[2] == 0 + && let Ok(Some(TsPacket { + payload: Some(TsPayload::Pat(pat)), + .. + })) = TsPacketReader::new(packet).read_ts_packet() + { + return Some( + pat.table + .iter() + .map(|entry| entry.program_num) + .filter(|&program| program != 0) + .collect(), + ); + } + off += 1; + } + None +} + +#[cfg(test)] +mod test { + use std::time::Duration; + + use super::*; + use crate::catalog::hang::Container; + use crate::container::Consumer; + use crate::container::ts::import::test::two_programs; + + #[test] + fn program_broadcasts_keep_the_catalog_suffix_last() { + assert_eq!(program_broadcast("event.hang", 2), "event/2.hang"); + assert_eq!(program_broadcast("demo/event.msf", 7), "demo/event/7.msf"); + assert_eq!(program_broadcast("event", 1), "event/1"); + } + + #[test] + fn pat_programs_reads_the_first_whole_pat() { + let data = two_programs(); + assert_eq!(pat_programs(&data), Some(vec![1, 2])); + // A sync byte in leading junk is skipped; a truncated PAT is not a PAT yet. + let mut shifted = vec![0x47, 0x40, 0x00, 0x10]; + shifted.extend_from_slice(&data); + assert_eq!(pat_programs(&shifted), Some(vec![1, 2])); + assert_eq!(pat_programs(&data[..100]), None); + } + + /// The input is held until the PAT is whole, then each program publishes as its own + /// broadcast carrying only that program, live on its own first frame rather than an hour + /// apart on one shared clock. + #[tokio::test] + async fn every_program_publishes_its_own_broadcast() { + let origin = crate::source::produce_origin(); + let ago = Duration::from_secs(60); + let clock = crate::Clock::at(std::time::Instant::now() - ago, std::time::SystemTime::now() - ago).unwrap(); + let config = catalog::Config::default().with_clock(clock); + let mut programs = Programs::new(origin.clone(), "event.hang", config).live(); + + let input = two_programs(); + let before = clock.now(); + programs.decode(&input[..100]).unwrap(); + assert!( + programs.programs.is_empty(), + "no program is known before the PAT is whole" + ); + programs.decode(&input[100..]).unwrap(); + programs.finish().unwrap(); + let after = clock.now(); + + for (path, fills) in [("event/1.hang", [0xAA, 0xBB]), ("event/2.hang", [0xCC, 0xDD])] { + let consumer = crate::Source::new(origin.consume(), path).broadcast().await.unwrap(); + let catalog = hang::catalog::Catalog::<()>::subscribe(&consumer) + .await + .unwrap() + .next() + .await + .unwrap() + .expect("a catalog"); + let renditions: Vec<_> = catalog.audio.renditions.iter().collect(); + assert_eq!(renditions.len(), 1, "{path} carries its own program's one stream"); + let (name, config) = renditions[0]; + let track = consumer.track(name).unwrap().subscribe(None).await.unwrap(); + let container = Container::try_from(config).unwrap(); + let frame = Consumer::new(track, container).read().await.unwrap().expect("a frame"); + assert!(fills.contains(&frame.payload[4]), "{path} carries only its own program"); + let skew = Duration::from_secs(2).as_micros(); + assert!( + before.as_micros() - skew <= frame.timestamp.as_micros() + && frame.timestamp.as_micros() <= after.as_micros() + skew, + "{path} is live on arrival: {:?} not in {before:?}..={after:?}", + frame.timestamp + ); + } + } +} diff --git a/rs/moq-srt/README.md b/rs/moq-srt/README.md index 36a25f5a68d..c589fa8ceb2 100644 --- a/rs/moq-srt/README.md +++ b/rs/moq-srt/README.md @@ -39,9 +39,10 @@ tokio::select! { ## CLI A command-line interface is provided by the [`moq-cli`](../moq-cli) binary, on -top of this library. +top of this library. Its listener bridges the single `--broadcast` and ignores +the stream id; see [`doc/bin/srt.md`](../../doc/bin/srt.md). -Feed any SRT source: +Feed any SRT source into a `run` listener with prefix `live`: ```bash # Publish: lands at broadcast `live/cam0`. @@ -58,16 +59,22 @@ the publisher does. ## Routing -Each connection's broadcast path and direction come from its SRT stream id: +Under `run`, each connection's broadcast path and direction come from its SRT +stream id: - Standard form `#!::r=,m=` -> ``, with `m=request` selecting egress and anything else (including absent) selecting ingest. - Otherwise the raw stream id (e.g. OBS-style `app/key`), always ingest. -`--srt-prefix` is prepended to namespace a listener's streams. First publisher on +`Config::prefix` is prepended to namespace a listener's streams. First publisher on a path wins; a second publish of the same path is rejected. Requests don't claim a path, so any number of players can pull the same broadcast. +A multi-program feed is refused unless `Config::program` picks one program +(`Program::One(n)`) or every program (`Program::All`), which publishes each on +its own broadcast under the path: `live/cam0/1`, `live/cam0/2`, and so on. To +choose per connection, drive `Server` and call `Publish::with_program`. + ## Auth `run` is unauthenticated: anyone who can reach the UDP port can publish or diff --git a/rs/moq-srt/src/dial.rs b/rs/moq-srt/src/dial.rs index 6c516664051..2367a857843 100644 --- a/rs/moq-srt/src/dial.rs +++ b/rs/moq-srt/src/dial.rs @@ -23,8 +23,8 @@ use std::time::Duration; use moq_net::origin; use srt_tokio::SrtSocket; -use crate::Result; use crate::server::{DEFAULT_LATENCY, configure_buffers, serve_publish, serve_subscribe}; +use crate::{Program, Result}; /// An SRT caller that can publish a MoQ broadcast or pull a remote stream. /// @@ -57,6 +57,9 @@ pub struct Client { /// Connection allocator each ingested track claims its peak-hold bitrate on. /// [`pull`] only; [`publish`] reads a broadcast someone else declared. bandwidth: moq_net::bandwidth::Allocator, + + /// The programs of a multi-program remote [`pull`] publishes, or `None` to refuse one. + program: Option, } impl Client { @@ -69,6 +72,7 @@ impl Client { latency: DEFAULT_LATENCY, max_age: None, bandwidth: moq_net::bandwidth::Allocator::unlimited(), + program: None, } } @@ -90,6 +94,13 @@ impl Client { self } + /// Publish one program of a multi-program stream [`pull`](Self::pull) receives, or each as + /// its own broadcast under the pulled path. `None` (the default) refuses a multiplex. + pub fn with_program(mut self, program: impl Into>) -> Self { + self.program = program.into(); + self + } + /// Push a MoQ broadcast out to the remote as MPEG-TS until the broadcast ends. pub async fn publish(&self, origin: &origin::Consumer, path: impl moq_net::AsPath) -> Result<()> { let path = path.as_path(); @@ -104,7 +115,7 @@ impl Client { let catalog = moq_mux::catalog::Config::default() .with_max_age(self.max_age) .with_bandwidth(self.bandwidth.clone()); - serve_publish(origin, path.as_str(), socket, catalog).await + serve_publish(origin, path.as_str(), socket, catalog, self.program).await } async fn call(&self, mode: Mode) -> Result { diff --git a/rs/moq-srt/src/lib.rs b/rs/moq-srt/src/lib.rs index ffa13510865..da8d3543bc9 100644 --- a/rs/moq-srt/src/lib.rs +++ b/rs/moq-srt/src/lib.rs @@ -48,3 +48,4 @@ pub use dial::Client; pub use error::{Error, Result}; pub use listen::{Config, run}; pub use server::{Publish, Reject, Request, Server, Subscribe}; +pub use ts::Program; diff --git a/rs/moq-srt/src/listen.rs b/rs/moq-srt/src/listen.rs index 6b5f3d84dfd..5cc7f5476e9 100644 --- a/rs/moq-srt/src/listen.rs +++ b/rs/moq-srt/src/listen.rs @@ -31,8 +31,8 @@ use std::time::Duration; use moq_net::{Path, PathOwned, origin}; -use crate::Result; use crate::server::{Request, Server}; +use crate::{Program, Result}; /// SRT gateway configuration. /// @@ -64,6 +64,11 @@ pub struct Config { /// advertise segments that are still fetchable. Lower it when nothing reads history /// and the memory matters. Only affects ingest (`m=publish`); egress ignores it. pub max_age: Option, + + /// The programs of a multi-program feed every ingest publishes, or `None` to refuse a + /// multiplex. To choose per path, drive [`Server`] and call + /// [`Publish::with_program`](crate::Publish::with_program) on each request. + pub program: Option, } impl Default for Config { @@ -73,6 +78,7 @@ impl Default for Config { prefix: Path::empty().to_owned(), latency: crate::server::DEFAULT_LATENCY, max_age: None, + program: None, } } } @@ -110,6 +116,7 @@ pub async fn run(origin: origin::Producer, config: Config) -> Result<()> { let active = ActivePaths::default(); let prefix = config.prefix; let max_age = config.max_age; + let program = config.program; while let Some(request) = server.accept().await { let prefix = prefix.clone(); @@ -130,7 +137,12 @@ pub async fn run(origin: origin::Producer, config: Config) -> Result<()> { let _ = publish.reject(crate::Reject::Unavailable).await; return; }; - if let Err(err) = publish.with_max_age(max_age).accept(&origin, &path).await { + if let Err(err) = publish + .with_max_age(max_age) + .with_program(program) + .accept(&origin, &path) + .await + { tracing::warn!(%peer, %path, %err, "SRT ingest ended with error"); } else { tracing::info!(%peer, %path, "SRT ingest ended"); diff --git a/rs/moq-srt/src/server.rs b/rs/moq-srt/src/server.rs index ddbab0d5552..e51667dc19e 100644 --- a/rs/moq-srt/src/server.rs +++ b/rs/moq-srt/src/server.rs @@ -29,7 +29,7 @@ use srt_tokio::access::{AccessControlList, ConnectionMode, RejectReason, Standar use srt_tokio::options::{PacketCount, SocketOptions, StreamId}; use srt_tokio::{ConnectionRequest, SrtIncoming, SrtListener, SrtSocket}; -use crate::Result; +use crate::{Program, Result}; /// Why an SRT publish or subscribe was refused. #[derive(Clone, Copy, Debug, PartialEq, Eq)] @@ -248,6 +248,7 @@ impl Server { latency: self.latency, max_age: None, bandwidth: moq_net::bandwidth::Allocator::unlimited(), + program: None, }; // `m=request` reads a broadcast out; everything else publishes one in. @@ -280,6 +281,8 @@ struct Pending { /// Connection allocator each ingested track claims its peak-hold bitrate on. /// Override with [`Publish::with_bandwidth`]. bandwidth: moq_net::bandwidth::Allocator, + /// The programs of a multiplex an ingest publishes. Override with [`Publish::with_program`]. + program: Option, } /// What an accepted SRT connection wants: to contribute media ([`Publish`]) or to @@ -378,6 +381,13 @@ impl Publish { self } + /// Publish one program of a multi-program feed, or each as its own broadcast under the + /// accepted path. `None` (the default) fails an ingest whose PAT lists more than one. + pub fn with_program(mut self, program: impl Into>) -> Self { + self.0.program = program.into(); + self + } + /// Accept the publish: announce a broadcast at `path` in `origin` and pump the /// connection's MPEG-TS into it until the client disconnects. /// @@ -392,7 +402,7 @@ impl Publish { let config = moq_mux::catalog::Config::default() .with_max_age(self.0.max_age) .with_bandwidth(self.0.bandwidth); - serve_publish(origin, path.as_str(), socket, config).await + serve_publish(origin, path.as_str(), socket, config, self.0.program).await } /// Reject the publish with a verdict the client can distinguish on the wire. @@ -469,10 +479,11 @@ pub(crate) async fn serve_publish( path: &str, mut socket: SrtSocket, config: moq_mux::catalog::Config, + program: Option, ) -> Result<()> { use futures::TryStreamExt; - let mut publisher = crate::ts::Publisher::new(origin, path, config)?; + let mut publisher = crate::ts::Publisher::new(origin, path, config, program)?; // Run the read/feed loop so an error surfaces here instead of unwinding past // the publisher, which would drop it (and its tracks) with a bare Error::Dropped. diff --git a/rs/moq-srt/src/ts.rs b/rs/moq-srt/src/ts.rs index f81681c5e18..b470181c23b 100644 --- a/rs/moq-srt/src/ts.rs +++ b/rs/moq-srt/src/ts.rs @@ -15,21 +15,29 @@ use moq_net::origin; use crate::Result; -/// Publishes an MPEG-TS source into the origin as a single broadcast. +/// Which programs of a multi-program MPEG-TS an ingest publishes. +/// +/// Without one, an ingest whose PAT lists more than one program fails with +/// [`ts::MultipleProgramsError`] rather than merging unrelated clocks onto one broadcast. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Program { + /// Only the program with this PAT program number, on the ingest's path. + One(u16), + /// Every program the first PAT lists, each as its own broadcast under the ingest's path: + /// `live/cam0` publishes `live/cam0/1`, `live/cam0/2`, ... (`event.hang` publishes + /// `event/1.hang`, keeping the catalog suffix last). + All, +} + +/// Publishes an MPEG-TS source into the origin: one broadcast, or one per program. /// /// Each chunk is handed straight to the TS importer, which consumes whole /// transport packets and retains any partial trailing packet internally for the /// next call (the same pattern `moq-cli import ... stdin ts` uses against stdin). -/// Either [`Self::finish`] or dropping the publisher ends the broadcast and -/// unannounces the path. +/// Either [`Self::finish`] or dropping the publisher ends the broadcasts and +/// unannounces their paths. pub struct Publisher { - // TS carries undecoded elementary streams (SCTE-35, teletext, DVB AC-3, ...) - // verbatim, so the importer uses the `mpegts` catalog extension rather than the - // media-only `()`, which would route those PIDs to `Stream::Ignored` and drop them. - importer: ts::Import, - // A clone of the importer's producer, so an end can close the broadcast - // (prompt unannounce) even though the importer owns it. - broadcast: moq_net::broadcast::Producer, + importer: Importer, // The importer's per-stream counters, logged as `moq import ts` logs them, under a // span naming the path, since one server carries many ingests. log: ts::stats::Log, @@ -37,24 +45,53 @@ pub struct Publisher { span: tracing::Span, } +enum Importer { + One { + // TS carries undecoded elementary streams (SCTE-35, teletext, DVB AC-3, ...) + // verbatim, so the importer uses the `mpegts` catalog extension rather than the + // media-only `()`, which would route those PIDs to `Stream::Ignored` and drop them. + import: Box>, + // A clone of the importer's producer, so an end can close the broadcast + // (prompt unannounce) even though the importer owns it. + broadcast: moq_net::broadcast::Producer, + }, + /// Each program's broadcast is created and announced once the first PAT names it. + All(Box), +} + impl Publisher { - /// Create the broadcast on `origin` at `path` and wire up the TS importer + - /// catalog. + /// Wire up the TS importer and catalog for `path` on `origin`, announcing the broadcast + /// now, or each program's once the PAT lists it for [`Program::All`]. /// /// `config` is the catalog the importer publishes into: retention /// (`with_max_age`) and the connection allocator passthrough tracks claim on /// (`with_bandwidth`). - pub fn new(origin: &origin::Producer, path: &str, config: moq_mux::catalog::Config) -> Result { - let mut broadcast = origin.publish(path, moq_net::origin::Route::default())?; - let config = config.with_catalog(moq_mux::catalog::hang::Catalog::::default()); - let catalog = moq_mux::catalog::Producer::new(&mut broadcast, config)?; - let handle = broadcast.clone(); - let importer = ts::Import::new(broadcast, catalog.reserve()); - tracing::info!(%path, "publishing ingest broadcast"); + pub fn new( + origin: &origin::Producer, + path: &str, + config: moq_mux::catalog::Config, + program: Option, + ) -> Result { + let importer = match program { + Some(Program::All) => Importer::All(Box::new(ts::Programs::new(origin.clone(), path, config))), + Some(Program::One(_)) | None => { + let mut broadcast = origin.publish(path, moq_net::origin::Route::default())?; + let config = config.with_catalog(moq_mux::catalog::hang::Catalog::::default()); + let catalog = moq_mux::catalog::Producer::new(&mut broadcast, config)?; + let mut import = ts::Import::new(broadcast.clone(), catalog.reserve()); + if let Some(Program::One(program)) = program { + import = import.with_program(program); + } + Importer::One { + import: Box::new(import), + broadcast, + } + } + }; + tracing::info!(%path, ?program, "publishing ingest broadcast"); Ok(Self { importer, - broadcast: handle, log: ts::stats::Log::default(), sampled: tokio::time::Instant::now(), span: tracing::info_span!("srt", %path), @@ -68,32 +105,53 @@ impl Publisher { /// [`ts::stats::Log::INTERVAL`] it also logs what moved in the importer's /// per-stream counters. pub fn feed(&mut self, data: Bytes) -> Result<()> { - self.importer.decode(&data).map_err(moq_mux::Error::from)?; + match &mut self.importer { + Importer::One { import, .. } => import.decode(&data), + Importer::All(programs) => programs.decode(&data), + } + .map_err(moq_mux::Error::from)?; if self.sampled.elapsed() >= ts::stats::Log::INTERVAL { self.sampled = tokio::time::Instant::now(); let _span = self.span.enter(); - self.log.sample(self.importer.stats()); + self.log.sample(self.stats()); } Ok(()) } + fn stats(&self) -> ts::Stats { + match &self.importer { + Importer::One { import, .. } => import.stats(), + Importer::All(programs) => programs.stats(), + } + } + /// Flush any buffered media, close out the broadcast's open groups, and end /// the broadcast so the origin unannounces it immediately. pub fn finish(&mut self) -> Result<()> { - self.importer.finish().map_err(moq_mux::Error::from)?; + match &mut self.importer { + Importer::One { import, broadcast } => { + import.finish().map_err(moq_mux::Error::from)?; + broadcast.close(); + } + Importer::All(programs) => programs.finish().map_err(moq_mux::Error::from)?, + } // The drain at end of input can publish a frame nothing vouched for. - self.span.in_scope(|| self.log.finish(&self.importer.stats())); - self.broadcast.close(); + self.span.in_scope(|| self.log.finish(&self.stats())); Ok(()) } /// Abort the published tracks with `err` so subscribers see the real cause /// (the SRT caller dropped, a demux error) rather than a generic `Error::Dropped`. /// - /// Consumes the publisher and closes the broadcast. + /// Consumes the publisher and closes the broadcasts. pub fn abort(self, err: moq_net::Error) { - self.importer.abort(err); - self.broadcast.close(); + match self.importer { + Importer::One { import, broadcast } => { + import.abort(err); + broadcast.close(); + } + Importer::All(programs) => programs.abort(err), + } } } @@ -256,7 +314,7 @@ mod tests { /// Publish `ts` on `path` one SRT payload (7 packets) at a time, each delivered when the /// program clock says it is due. async fn ingest(origin: &moq_net::origin::Producer, path: &str, ts: &[u8]) { - let mut publisher = Publisher::new(origin, path, Default::default()).unwrap(); + let mut publisher = Publisher::new(origin, path, Default::default(), None).unwrap(); let mut clock = Duration::ZERO; for payload in timed(ts).collect::>().chunks(7) { let (due, _) = payload[0]; @@ -295,23 +353,101 @@ mod tests { section } - /// A PAT with one program (number 1) whose PMT lives on `pmt_pid`. - fn pat(pmt_pid: u16) -> Vec { - let mut s = vec![0x00, 0xb0, 0x0d, 0x00, 0x01, 0xc1, 0x00, 0x00]; - s.extend_from_slice(&[0x00, 0x01]); - s.extend_from_slice(&[0xe0 | (pmt_pid >> 8) as u8, pmt_pid as u8]); + /// A PAT listing each `(program_number, pmt_pid)`. + fn pat(programs: &[(u16, u16)]) -> Vec { + let len = 9 + 4 * programs.len(); + let mut s = vec![0x00, 0xb0, len as u8, 0x00, 0x01, 0xc1, 0x00, 0x00]; + for &(program, pmt_pid) in programs { + s.extend_from_slice(&program.to_be_bytes()); + s.extend_from_slice(&[0xe0 | (pmt_pid >> 8) as u8, pmt_pid as u8]); + } seal(s) } - /// A PMT for program 1 declaring a single H.264 elementary stream on `es_pid`. - fn pmt(es_pid: u16) -> Vec { - let mut s = vec![0x02, 0xb0, 0x12, 0x00, 0x01, 0xc1, 0x00, 0x00]; + /// A PMT for `program` declaring a single elementary stream of `stream_type` on `es_pid`. + fn pmt(program: u16, stream_type: u8, es_pid: u16) -> Vec { + let mut s = vec![0x02, 0xb0, 0x12]; + s.extend_from_slice(&program.to_be_bytes()); + s.extend_from_slice(&[0xc1, 0x00, 0x00]); s.extend_from_slice(&[0xe0 | (es_pid >> 8) as u8, es_pid as u8]); s.extend_from_slice(&[0xf0, 0x00]); - s.extend_from_slice(&[0x1b, 0xe0 | (es_pid >> 8) as u8, es_pid as u8, 0xf0, 0x00]); + s.extend_from_slice(&[stream_type, 0xe0 | (es_pid >> 8) as u8, es_pid as u8, 0xf0, 0x00]); seal(s) } + /// The PSI of a two-program multiplex, each program carrying one private PES stream + /// (carried verbatim, so the catalog lists it without waiting on media): program 1's on + /// PID 0x101, program 2's on 0x201. + fn two_programs() -> Bytes { + let mut ts = psi_packet(0x0000, &pat(&[(1, 0x0100), (2, 0x0200)])); + ts.extend_from_slice(&psi_packet(0x0100, &pmt(1, 0x06, 0x0101))); + ts.extend_from_slice(&psi_packet(0x0200, &pmt(2, 0x06, 0x0201))); + ts.into() + } + + /// The PAT program number and the stream PIDs the catalog at `path` records, once it is + /// announced. + async fn program(origin: &moq_net::origin::Producer, path: &str) -> (u16, Vec) { + let consumer = origin.consume(); + timeout(Duration::from_secs(5), consumer.routed(path)) + .await + .expect("announce timed out") + .expect("the broadcast is announced"); + let broadcast = consumer.request_broadcast(path).await.unwrap(); + let mut catalog = moq_mux::catalog::Consumer::::new(&broadcast, CatalogFormat::Hang) + .await + .unwrap(); + let snapshot = timeout(Duration::from_secs(5), catalog.next()) + .await + .expect("catalog timed out") + .unwrap() + .expect("a catalog"); + let program = snapshot.ext.mpegts.program.as_ref().expect("the PAT identity"); + let pids = snapshot.ext.mpegts.tracks.values().map(|track| track.pid).collect(); + (program.program_number, pids) + } + + /// Without a selection, a multiplex is refused rather than merged onto one broadcast. + #[tokio::test(start_paused = true)] + async fn publisher_refuses_a_multiplex() { + let origin = produce_origin(); + let mut publisher = Publisher::new(&origin, "ingest", Default::default(), None).unwrap(); + let err = publisher.feed(two_programs()).unwrap_err(); + let crate::Error::Mux(moq_mux::Error::Other(inner)) = &err else { + panic!("a demux error: {err}"); + }; + assert_eq!( + inner.downcast_ref::(), + Some(&ts::MultipleProgramsError { programs: vec![1, 2] }) + ); + } + + /// `Program::One` publishes the chosen program alone on the ingest's path. + #[tokio::test(start_paused = true)] + async fn publisher_imports_one_program() { + let origin = produce_origin(); + let mut publisher = Publisher::new(&origin, "ingest", Default::default(), Some(Program::One(2))).unwrap(); + publisher.feed(two_programs()).unwrap(); + assert_eq!(program(&origin, "ingest").await, (2, vec![0x0201])); + } + + /// `Program::All` publishes each program as its own broadcast under the ingest's path. + #[tokio::test(start_paused = true)] + async fn publisher_imports_every_program() { + let origin = produce_origin(); + let mut publisher = Publisher::new(&origin, "ingest", Default::default(), Some(Program::All)).unwrap(); + publisher.feed(two_programs()).unwrap(); + assert_eq!(program(&origin, "ingest/1").await, (1, vec![0x0101])); + assert_eq!(program(&origin, "ingest/2").await, (2, vec![0x0201])); + assert!( + timeout(Duration::from_secs(1), origin.consume().routed("ingest")) + .await + .is_err(), + "nothing is published on the bare path" + ); + publisher.finish().unwrap(); + } + /// The retention the caller configured has to reach the media tracks the TS importer /// mints off the PMT, not stop at the catalog producer it was set on. #[tokio::test] @@ -321,11 +457,12 @@ mod tests { &origin, "live/cam0", moq_mux::catalog::Config::default().with_max_age(Duration::from_secs(3)), + None, ) .unwrap(); - let mut ts = psi_packet(0x0000, &pat(0x0100)); - ts.extend_from_slice(&psi_packet(0x0100, &pmt(0x0101))); + let mut ts = psi_packet(0x0000, &pat(&[(1, 0x0100)])); + ts.extend_from_slice(&psi_packet(0x0100, &pmt(1, 0x1b, 0x0101))); publisher.feed(Bytes::from(ts)).unwrap(); let consumer = origin.consume(); @@ -373,7 +510,7 @@ mod tests { #[tokio::test(start_paused = true)] async fn publisher_preserves_scte35_cues() { let origin = produce_origin(); - let mut publisher = Publisher::new(&origin, "ingest", Default::default()).unwrap(); + let mut publisher = Publisher::new(&origin, "ingest", Default::default(), None).unwrap(); let consumer = origin.consume(); timeout(Duration::from_secs(5), consumer.routed("ingest")) From 59706a4b1ec0f2e86a0f4f20fb8ff7fae4abc4c4 Mon Sep 17 00:00:00 2001 From: Thom Shutt <294441994+thomshutt-fastly@users.noreply.github.com> Date: Wed, 30 Sep 2026 14:57:23 +0100 Subject: [PATCH 098/128] fix(net): send the AUTHORITY setup option from moqt:// clients (#4578) --- rs/moq-net/src/client.rs | 48 ++++++++++++++++++++++++ rs/moq-net/src/ietf/session.rs | 61 ++++++++++++++++++++++++++++++- rs/moq-net/src/server.rs | 2 + rs/moq-tokio/src/client.rs | 67 +++++++++++++++++++++++++++++++++- 4 files changed, 176 insertions(+), 2 deletions(-) diff --git a/rs/moq-net/src/client.rs b/rs/moq-net/src/client.rs index 75abdb5e3b2..8531ea788cf 100644 --- a/rs/moq-net/src/client.rs +++ b/rs/moq-net/src/client.rs @@ -17,6 +17,7 @@ pub struct Client { stats: stats::Session, versions: Versions, setup_path: Option, + setup_authority: Option, cost: Option, peer_hop: Option, } @@ -82,6 +83,12 @@ impl Client { self } + /// Set the URI authority to advertise in SETUP (moq-transport only) + pub fn with_authority(mut self, authority: impl Into) -> Self { + self.setup_authority = Some(authority.into()); + self + } + /// Price this link, in the units the rest of the mesh uses (moq-lite-06+, and /// `moqt-17`+ via the MoQ Cluster extension). /// @@ -266,6 +273,7 @@ impl Client { cost: self.cost, version: draft, path: self.setup_path.clone(), + authority: self.setup_authority.clone(), peer_setup_stream: None, peer_declared: None, })?; @@ -341,6 +349,9 @@ impl Client { if let Some(path) = &self.setup_path { parameters.set_bytes(ietf::ParameterBytes::Path, path.clone().into_bytes()); } + if let Some(authority) = &self.setup_authority { + parameters.set_bytes(ietf::ParameterBytes::Authority, authority.clone().into_bytes()); + } ietf::solicit::into_setup(&mut parameters, ietf_encoding); ietf::hidden::into_setup(&mut parameters, ietf_encoding); let parameters = parameters.encode_bytes(ietf_encoding)?; @@ -410,6 +421,7 @@ impl Client { cost: self.cost, version: v, path: None, + authority: None, peer_setup_stream: None, peer_declared: Some(peer_declared), })?; @@ -739,6 +751,42 @@ mod tests { .expect("connect failed"); } + /// The client SETUP on the bidi control stream (the pre-draft-17 framing) carries the + /// AUTHORITY next to the PATH. + #[tokio::test(start_paused = true)] + async fn draft14_setup_carries_the_authority() { + let fake = FakeSession::new(Some(ALPN_LITE), mock_server_setup(Version::Lite(lite::Version::Lite01))); + let client = Client::new() + .with_versions( + [ + Version::Lite(lite::Version::Lite01), + Version::Ietf(ietf::Version::Draft14), + ] + .into(), + ) + .with_path("/anon") + .with_authority("relay.example.com:4443"); + + let (_session, driver) = client + .connect(tokio::time::Instant::now().into_std(), fake.clone()) + .await + .unwrap(); + tokio::spawn(crate::time::run(driver)); + + let mut setup_bytes = Bytes::from(fake.control_writes()); + let setup = setup::Client::decode(&mut setup_bytes, Version::Ietf(ietf::Version::Draft14)).unwrap(); + let mut parameters = setup.parameters; + let parameters = ietf::Parameters::decode(&mut parameters, ietf::Version::Draft14).unwrap(); + assert_eq!( + parameters.get_bytes(ietf::ParameterBytes::Authority), + Some(b"relay.example.com:4443".as_ref()) + ); + assert_eq!( + parameters.get_bytes(ietf::ParameterBytes::Path), + Some(b"/anon".as_ref()) + ); + } + #[tokio::test(start_paused = true)] async fn alpn_lite_falls_back_to_draft14_and_switches_version_post_setup() { run_alpn_lite_fallback_case(Some(ALPN_LITE)).await; diff --git a/rs/moq-net/src/ietf/session.rs b/rs/moq-net/src/ietf/session.rs index 121f3f10e4e..fcb9f300079 100644 --- a/rs/moq-net/src/ietf/session.rs +++ b/rs/moq-net/src/ietf/session.rs @@ -54,6 +54,9 @@ pub struct Config { /// transports). A server passes `None`. pub path: Option, + /// The URI authority we advertise in our SETUP, under the same rules as `path`. + pub authority: Option, + /// The peer's SETUP stream, when it was already read before [`start`] (a draft-17+ /// server that gated on the client's path via [`accept_setup`]). It becomes the /// GOAWAY channel; `None` lets the uni loop read the SETUP itself. @@ -80,6 +83,7 @@ where cost, version, path, + authority, peer_setup_stream, peer_declared, } = config; @@ -275,7 +279,9 @@ where let session = session.clone(); let goaway = goaway.clone(); async move { - if let Err(err) = run_setup(runtime, session, version, path, self_origin, cost, goaway).await { + if let Err(err) = + run_setup(runtime, session, version, path, authority, self_origin, cost, goaway).await + { tracing::warn!(%err, "setup send error"); } std::future::pending::<()>().await; @@ -524,11 +530,13 @@ fn peer_from_params(params: &ietf::Parameters, version: Version) -> Result( runtime: crate::time::Clock, mut session: S, version: Version, path: Option, + authority: Option, self_origin: Hop, cost: Option, goaway: crate::goaway::Protocol, @@ -543,6 +551,9 @@ async fn run_setup( if let Some(path) = path { parameters.set_bytes(ietf::ParameterBytes::Path, path.into_bytes()); } + if let Some(authority) = authority { + parameters.set_bytes(ietf::ParameterBytes::Authority, authority.into_bytes()); + } cluster::peer_into_setup(&mut parameters, self_origin, cost, version); solicit::into_setup(&mut parameters, version); hidden::into_setup(&mut parameters, version); @@ -946,6 +957,7 @@ mod tests { cost: None, version: VERSION, path: None, + authority: None, peer_setup_stream: None, // A peer that declared its Hop ID negotiated the extension, which is what // makes the cluster parameters mandatory in both directions. @@ -1004,6 +1016,7 @@ mod tests { cost: None, version: Version::Draft18, path: None, + authority: None, peer_setup_stream: None, // The requests wait on the peer's SETUP (MoQ Hidden). peer_declared: Some(peer::Peer::default()), @@ -1055,6 +1068,7 @@ mod tests { cost: None, version: Version::Draft18, path: None, + authority: None, peer_setup_stream: None, peer_declared, }) @@ -1162,6 +1176,7 @@ mod tests { cost: None, version: VERSION, path: None, + authority: None, peer_setup_stream: None, // Pre-settled, so nothing waits on a SETUP the dead stream will never // carry and the dispatch loop actually runs. @@ -1176,6 +1191,49 @@ mod tests { assert_eq!(log.closes(), vec![], "nothing may close the transport"); } + /// A draft-17+ client advertises its AUTHORITY in the SETUP it writes on its uni stream. + #[tokio::test] + async fn setup_carries_the_authority() { + const AUTHORITY: &[u8] = b"relay.example.com:4443"; + + // The driver parks forever once SETUP is out, so bound it: paused time makes the + // deadline fire the moment nothing else can run. + tokio::time::pause(); + + for version in [Version::Draft18, Version::Draft19] { + let session = crate::lite::test_transport::ScriptedSession::new(Vec::new()); + let log = session.log.clone(); + + let (driver, _goaway) = start(Config { + runtime: crate::time::Clock::tokio(), + session, + setup: None, + request_id_max: None, + client: true, + publish: None, + subscribe: None, + peer_hop: None, + cost: None, + version, + path: None, + authority: Some(String::from_utf8(AUTHORITY.to_vec()).unwrap()), + peer_setup_stream: None, + peer_declared: Some(peer::Peer::default()), + }) + .expect("start the session"); + + tokio::time::timeout(std::time::Duration::from_secs(10), driver) + .await + .expect_err("the session ended instead of parking after SETUP"); + + assert_eq!( + occurrences(&log, AUTHORITY), + 1, + "{version:?}: SETUP must carry the authority once" + ); + } + } + #[tokio::test] async fn a_uni_stream_dead_before_its_type_does_not_end_the_session() { a_dead_incoming_stream_is_not_fatal(crate::lite::test_transport::DeadStreamSession::unis(1)).await; @@ -1354,6 +1412,7 @@ mod tests { cost: None, version: VERSION, path: None, + authority: None, peer_setup_stream: None, peer_declared: None, }) diff --git a/rs/moq-net/src/server.rs b/rs/moq-net/src/server.rs index a6e9fd0fc90..346b8a200d8 100644 --- a/rs/moq-net/src/server.rs +++ b/rs/moq-net/src/server.rs @@ -531,6 +531,7 @@ where cost: None, version, path: None, + authority: None, peer_setup_stream: Some(peer_setup.stream), peer_declared: Some(peer_setup.declared), })?; @@ -637,6 +638,7 @@ where cost: None, version: v, path: None, + authority: None, peer_setup_stream: None, peer_declared: Some(peer_declared), })?; diff --git a/rs/moq-tokio/src/client.rs b/rs/moq-tokio/src/client.rs index b2ed72358db..686fd6c6df7 100644 --- a/rs/moq-tokio/src/client.rs +++ b/rs/moq-tokio/src/client.rs @@ -368,8 +368,12 @@ impl Client { // SETUP instead; `setup_path` returns `None` for the ones that carry a URI, where // sending it again is a protocol violation. An iroh-only build reads none of this: // that dial waits for the negotiated binding and builds its own. - #[allow(unused_variables)] let moq = self.moq_with_path(setup_path(&url)); + #[allow(unused_variables)] + let moq = match setup_authority(&url) { + Some(authority) => moq.with_authority(authority), + None => moq, + }; // Plain TCP (qmux, no TLS). Explicit opt-in scheme; never raced against // QUIC, which can't speak it. Use only on a trusted network. @@ -548,6 +552,30 @@ fn setup_path(url: &Url) -> Option { } } +/// The URI authority to advertise in the SETUP, chosen by the dial URL's scheme. +/// +/// A raw-QUIC `moqt://` client MUST send it (draft-ietf-moq-transport-21, 9.1.1). Built +/// from the host and port so URL userinfo never goes on the wire. `None` for every other +/// scheme, and when the URL has no host, since an empty authority is meaningless. +#[cfg(any( + feature = "noq", + feature = "iroh", + feature = "websocket", + feature = "tcp", + feature = "uds" +))] +fn setup_authority(url: &Url) -> Option { + if url.scheme() != "moqt" { + return None; + } + + let host = url.host_str().filter(|host| !host.is_empty())?; + Some(match url.port() { + Some(port) => format!("{host}:{port}"), + None => host.to_owned(), + }) +} + #[cfg(all(feature = "websocket", feature = "noq"))] #[derive(Debug, PartialEq, Eq)] enum TransportRace { @@ -785,6 +813,43 @@ mod tests { } } + #[cfg(any( + feature = "noq", + feature = "iroh", + feature = "websocket", + feature = "tcp", + feature = "uds" + ))] + #[test] + fn setup_authority_is_only_for_raw_quic_moqt() { + let cases = [ + ("moqt://relay.example.com", Some("relay.example.com")), + ("moqt://relay.example.com/anon?jwt=abc", Some("relay.example.com")), + ("moqt://relay.example.com:4443/anon", Some("relay.example.com:4443")), + ("moqt://[::1]:4443", Some("[::1]:4443")), + // Userinfo is a credential, and never goes on the wire. + ( + "moqt://user:pass@relay.example.com:4443", + Some("relay.example.com:4443"), + ), + // A hostless URL has no authority to send. + ("moqt:///anon", None), + // Only the draft's `moqt://` scheme is required to send it. + ("moql://relay.example.com", None), + ("tcp://relay.example.com:4443", None), + ("https://relay.example.com", None), + ("wss://relay.example.com", None), + ("unix:///run/moq.sock", None), + ("iroh://k5lnrlndqpqcgh4d5nhbnbnhcyrgvw6ttxwrsvsu4nlt6foorxaa", None), + ]; + + for (url, want) in cases { + let url = Url::parse(url).unwrap(); + let got = setup_authority(&url); + assert_eq!(got.as_deref(), want, "{url}"); + } + } + /// The iroh dial derives its target here rather than through [`setup_path`], since /// only the negotiated binding says whether to send one. #[cfg(any( From 94cc9b05cc5b340945eb7278c68f5ec37deaff53 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 07:14:40 -0700 Subject: [PATCH 099/128] quest: wt-close-upstream waits on the web-transport-moq release (#4520) Co-authored-by: Claude Opus 5.5 Co-authored-by: OpenCode (space-bunny-free) --- quest/m1/README.md | 1 + quest/m1/browser-close-code.md | 35 ++++++++++++++++++++++++++++++++++ quest/m1/wt-close-upstream.md | 34 +++++++++++++++++++++------------ 3 files changed, 58 insertions(+), 12 deletions(-) create mode 100644 quest/m1/browser-close-code.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 9501773df57..246d1b26c8a 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -27,6 +27,7 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Close codes](/quest/m1/close-codes.md) - a client sees the peer's application close code over WebSocket and raw QUIC, like WebTransport - [Raw stream codes](/quest/m1/raw-stream-codes.md) - raw QUIC stream resets and stops carry the application's code, not an HTTP/3-mapped one - [WebTransport close upstream](/quest/m1/wt-close-upstream.md) - web-transport-moq delivers the close capsule itself, and moq-tokio's `CLOSE_LINGER` is deleted +- [Browser close code](/quest/m1/browser-close-code.md) - a playwright case proves the page reads a relay's close code and reason, on every web-transport backend - [Watch refusal](/quest/m1/watch-refusal.md) - `` shows an origin refusal as an error instead of sitting offline - [Resumed groups](/quest/m1/resume-latest.md) - a half-delivered group ends once the new copy is past it, so a group-only reader never parks after a mid-group failover - [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 diff --git a/quest/m1/browser-close-code.md b/quest/m1/browser-close-code.md new file mode 100644 index 00000000000..95df47c7672 --- /dev/null +++ b/quest/m1/browser-close-code.md @@ -0,0 +1,35 @@ +# [M] A browser sees the close code on every WebTransport backend + +## Goal + +A browser interop case proves a relay's rejection reaches the page: the relay +closes the session with an application code and reason, and the page reads +both from `WebTransport.closed`. Every `moq-dev/web-transport` backend that +speaks WebTransport (noq, quinn, iroh) delivers the close capsule, verified by +that case or an equivalent test, and any that doesn't is fixed upstream. + +## Plan + +[WebTransport close upstream](/quest/m1/wt-close-upstream.md) fixed +`web-transport-moq`'s close path with a Rust regression test, but only +Chromium treats the H3 control stream ending early as fatal, so no Rust peer +proves the browser path. The playwright interop harness in `test/interop/` +has no close-code scenario yet. + +- Add the browser case: a relay (or `Request::reject`) closes with a code, and + the page asserts the code and reason. It should fail with the capsule fix + reverted. +- Audit `web-transport-noq`, `-quinn`, and `-iroh` for the same bug: a close + capsule sent from a task that doesn't keep the H3 control streams alive. + `web-transport-iroh` 0.7 sends no capsule at all, only a QUIC close; decide + there whether iroh's WebTransport path should send one. +- Fix upstream, release, and bump the pins, once wt-close finishes. + +Decided with the maintainer: the browser case and the backend audit ship +together, since the case is what proves each backend. + +Public API: none. Wire: none, unless iroh starts sending the capsule. + +## Required + +- [WebTransport close upstream](/quest/m1/wt-close-upstream.md) - the noq fix and pin bump the browser case needs diff --git a/quest/m1/wt-close-upstream.md b/quest/m1/wt-close-upstream.md index a277c17cb06..84f801729d8 100644 --- a/quest/m1/wt-close-upstream.md +++ b/quest/m1/wt-close-upstream.md @@ -1,4 +1,4 @@ -# [S] WebTransport close delivers its capsule upstream +# [XS] WebTransport close delivers its capsule upstream ## Goal @@ -20,22 +20,32 @@ detached task until `closed()` resolves, capped at a 10s `CLOSE_LINGER`. Decided 2026-09-29: fix it at the source and remove the timeout workaround. -- In moq-dev/noq, the close path keeps whatever the capsule needs alive until - it is delivered, without the caller's help. Its regression test drops the - session right after `close()` and asserts the peer reads the capsule - before the H3 control stream ends; it must fail on 1.3.2. A Rust peer - alone proves nothing: `session_close_surfaces_a_rejection_code` in - `rs/moq-tokio/tests/broadcast.rs` passed on 1.3.2 without the linger, - because only Chromium treats the control stream's end as fatal. Add a - browser check too if the playwright harness makes it cheap. -- Release `web-transport-moq` 1.3.x and bump the pin on `main` (2.x on `dev` - if it has moved). +The upstream fix makes the close task own a clone of the whole session: +[moq-dev/noq#23](https://github.com/moq-dev/noq/pull/23) for 2.x (`dev`) and +its backport [moq-dev/noq#24](https://github.com/moq-dev/noq/pull/24) for +1.3.x (`main`). Their `web-transport-moq/tests/close_capsule.rs` drops the +session right after `close()` against a hand-rolled HTTP/3 peer and fails on +1.3.2 and 2.0.0. + +Remaining, once the releases carrying them are published: + +- Bump the `web-transport-moq` pin on `main` (and on `dev` if 2.0.x lands + first). - Delete `CLOSE_LINGER`, its task, and its mock-session tests from - moq-tokio. + moq-tokio. They are exactly what #4429 added, so reverting it is enough. + +A browser check is left to +[Browser close code](/quest/m1/browser-close-code.md): the playwright harness +has no close-code scenario, so it is not cheap to add here. Public API: none. Wire: none. +## Required + +- A `web-transport-moq` 1.3.x release that carries moq-dev/noq#24 + ## Related +- [Browser close code](/quest/m1/browser-close-code.md) - the playwright case that proves Chromium reads the code this quest unblocks - [Close codes on every transport](/quest/m1/close-codes.md) - the same symptom over qmux and raw QUIC - [UnknownSession log flood](/quest/m1/unknown-session-logs.md) - another `web-transport-moq` release and pin bump From 3e7313aeb198513af277ffebb03b8bc00d18b3af Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 07:15:13 -0700 Subject: [PATCH 100/128] quest(m2): plan a Windows.Graphics.Capture backend (#4586) Co-authored-by: Claude Opus 5.5 --- quest/m2/README.md | 5 +- quest/m2/capture-frame-buffers.md | 22 +++---- quest/m2/capture-wgc.md | 97 +++++++++++++++++++++++++++++++ quest/m2/capture-windows.md | 29 +++------ 4 files changed, 116 insertions(+), 37 deletions(-) create mode 100644 quest/m2/capture-wgc.md diff --git a/quest/m2/README.md b/quest/m2/README.md index 95f08456402..1526d8d7649 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -87,10 +87,11 @@ upstream release waits in [m4](/quest/m4/README.md). - [Runtime QA hosts](/quest/m2/runtime-qa-hosts.md) - run exact source snapshots on accessible Linux and device hosts with retrievable debug evidence - [Media QA on other engines](/quest/m2/browser-media-qa-engines.md) - the media harness measures a Firefox or WebKit player over the fallback and names what each engine lacks - [Firefox 155 WebTransport](/quest/m2/firefox-155-webtransport.md) - Firefox negotiates the version by subprotocol, and the other new WebTransport features stay unused on purpose -- [Windows capture parity](/quest/m2/capture-windows.md) - system audio and screen cursor capture with a settled app-capture policy +- [Windows.Graphics.Capture](/quest/m2/capture-wgc.md) - one WGC backend for display and window capture with the cursor, replacing Desktop Duplication and GDI +- [Windows capture parity](/quest/m2/capture-windows.md) - system audio and a settled app-capture policy - [Linux capture parity](/quest/m2/capture-linux.md) - Wayland window/system-audio capture with explicit display-selection and app-capture limits - [Plan capture ergonomics](/quest/m2/capture-ergonomics.md) - scope independent crop and audio mixing quests - [Audio capture time](/quest/m2/audio-capture-time.md) - native audio stamps a buffer's capture instant, not when the driver reads it - [X11 capture transport](/quest/m2/x11-capture-shm.md) - move X11 capture to shared memory and RandR events instead of a per-frame socket copy -- [Capture frame buffers](/quest/m2/capture-frame-buffers.md) - stop rebuilding a full-frame buffer every tick in the X11 and Windows backends +- [Capture frame buffers](/quest/m2/capture-frame-buffers.md) - stop rebuilding a full-frame buffer every tick in the X11 backend - [Demo serve-hls renditions](/quest/m2/serve-hls-renditions.md) - `just pub serve-hls` serves 720p and 144p instead of two 256-wide copies diff --git a/quest/m2/capture-frame-buffers.md b/quest/m2/capture-frame-buffers.md index 156a3e5fe8d..466191c9b41 100644 --- a/quest/m2/capture-frame-buffers.md +++ b/quest/m2/capture-frame-buffers.md @@ -1,29 +1,23 @@ -# [S] moq-video: X11 and Windows capture rebuild their frame buffers every tick +# [S] moq-video: X11 capture rebuilds its frame buffers every tick ## Goal -Neither native screen-capture backend allocates a full-frame buffer per frame. -Steady-state capture reuses the same scratch memory and GDI objects. +X11 screen capture does not allocate a full-frame buffer per frame. +Steady-state capture reuses the same scratch memory. ## Plan -Both backends added in the native screen-capture work allocate the whole frame, -every frame, on the pump thread. - -`capture/window.rs`'s `snapshot` creates a memory DC, a compatible bitmap, and a -`vec![0u8; w * h * 4]` per call, then destroys them. At 1080p60 that is roughly -500 MB/s of allocation plus GDI object churn for pixels whose size never changes -while the stream is open. All three belong in `Capture`, built once at open: the -pump thread owns the struct, so the `!Send` handles are fine where they are. +The X11 backend added in the native screen-capture work allocates the whole +frame, every frame, on the pump thread. The Windows GDI path had the same cost +and is deleted by [Windows.Graphics.Capture](/quest/m2/capture-wgc.md) instead. `capture/x11.rs`'s `PixelFormat::rgb` allocates a `w * h * 3` `Vec` and fills it with three `push` calls per pixel, and `I420::from_rgb` then walks it again into a third buffer. Take an `&mut Vec` the `Capture` owns and `clear()` it, so the allocation happens once. -Neither is a correctness bug, so this is a steady-state cost question: measure -before and after rather than assuming. The X11 half compiles on Linux CI; the -Windows half needs a Windows host (`just rs windows`). +This is not a correctness bug, so it is a steady-state cost question: measure +before and after rather than assuming. ## Related diff --git a/quest/m2/capture-wgc.md b/quest/m2/capture-wgc.md new file mode 100644 index 00000000000..eb17dc59b1a --- /dev/null +++ b/quest/m2/capture-wgc.md @@ -0,0 +1,97 @@ +# [L] Windows.Graphics.Capture backend for display and window capture + +## Goal + +One Windows.Graphics.Capture (WGC) backend serves `Source::Display` and +`Source::Window` on Windows and honors `config.cursor` through +`IsCursorCaptureEnabled`. It replaces both current backends: DXGI Desktop +Duplication (`capture/desktopduplication.rs`, which ignores `config.cursor`) +and GDI window capture (`capture/window.rs`, whose `PrintWindow` runs on the +target's UI thread). Frames stay on the GPU as NV12 `Surface::Texture`. + +Out of scope: application capture and system audio, which stay in +[Windows capture parity](/quest/m2/capture-windows.md). WGC captures one +monitor or one window per item and has no per-process source, so it does not +answer app capture. + +## Plan + +Decided in planning (09-30): + +- **Replace, no fallback.** Delete `desktopduplication.rs` and the GDI capture + path. Keeping DD as a fallback means two backends for Windows builds that + are out of support anyway. +- **Mirror `capture/screencapture.rs`.** `CreateForMonitor` or + `CreateForWindow` (through `IGraphicsCaptureItemInterop`) builds the + `GraphicsCaptureItem`. Everything after that is shared: one session, a + free-threaded frame pool, a first frame to learn the size, and a guard that + closes the session on drop. `GraphicsCaptureItem.Closed` ends the stream. +- **GPU NV12 output.** Each BGRA pool frame goes through an + `ID3D11VideoProcessor` blit into an owned NV12 `d3d11::Texture` on the + capture device, so it can reach the Media Foundation hardware encoder + zero-copy, just as camera frames do. Pool frames are recycled, so copying out + is required. Generalize the existing NV12 `Scaler` in `frame.rs` to take BGRA + input instead of writing a second processor. openh264 already downloads a + `Texture` through `to_i420`. The existing scaler copies its input color + space to its output, which is right for resizing but wrong for converting. + Set the RGB range and the output YCbCr matrix explicitly so they match what + the encoder signals. Otherwise HD frames get converted with BT.601 while the + stream advertises BT.709. NV12 also needs even dimensions, and a window's + size is often odd. Keep the BGRA pool at its native size, and crop the NV12 + texture and the stream geometry down to even, as both current backends do. +- **The `windows` crate directly** (0.62, already a public re-export), not + `windows-capture` or another wrapper. We need our own D3D11 device, so it can + be shared with the encoder, and one `windows` version. This adds WinRT + features (`Graphics_Capture`, `Graphics_DirectX_Direct3D11`, + `Win32_System_WinRT_Graphics_Capture`, `Win32_System_WinRT_Direct3D11`, + `Win32_Graphics_Dwm`, and whatever else they pull in). Adding features is + additive. +- **Minimum Windows 10 2004 (build 19041).** That is where + `IsCursorCaptureEnabled` appears. Refuse loud below it with + `Error::Unsupported`, never silently drop the cursor. Set + `IsBorderRequired = false` where the property exists (build 20348+), but + request `GraphicsCaptureAccessKind::Borderless` first: without that access, + setting the property can fail with `E_ACCESSDENIED`. If access is denied, + keep the border rather than failing the capture. Older builds keep the + yellow capture border. Document the minimum in + `doc/lib/rs/moq-video.md`. +- **Resize ends the stream.** When `ContentSize` changes, debounce with + `Settle` and then return `Read::Done` so the caller reopens, the way + `window.rs` does today. The encoder's geometry is fixed. This also removes + DD's stale-size bug, where it keeps converting at the old width and height + after a mode change. +- **Displays enumerate across every adapter.** Use `EnumDisplayMonitors` + rather than adapter 0's DXGI outputs, which miss monitors attached to the + other GPU on hybrid laptops. Keep the user-visible `display:N` ids and names. +- **Windows skip DWM-cloaked entries.** Filter on `DWMWA_CLOAKED` (hidden UWP + windows and other virtual desktops), and size windows from + `DWMWA_EXTENDED_FRAME_BOUNDS` rather than `GetWindowRect`, which includes the + invisible borders. Enumeration never opens a capture: `ContentSize` belongs + to a frame, so it is only used for resize detection on the selected + capture. Keep the `window:{hwnd}` ids. + +Public API: no Rust signature changes. `config.cursor` starts working for +displays. Windows builds older than 19041 go from working to refused. + +Verification: Windows CI only runs `cargo check`, and hosted runners have no +real desktop. Add `#[ignore]` display and window tests, run them by hand on +real Windows hardware, and record this checklist in the PR: + +- cursor on and off +- an odd-sized window +- color on an SD and an HD source, from BGRA through NV12 to the encoder, on + both the Media Foundation path and the openh264 readback path +- window resize, close, and minimize +- multi-monitor +- one Windows 10 2004+ machine, showing that the yellow border appears there + +Fix the docs this makes stale in the same PR: `rs/moq-video/README.md`, +`doc/lib/rs/moq-video.md`, `doc/bin/cli.md`, the `capture/mod.rs` module doc, +the Cargo feature comment, and the `frame.rs` docs on which producers make a +`Texture`. + +## Related + +- [Windows capture parity](/quest/m2/capture-windows.md) - app capture and system audio, which WGC does not answer +- [Capture frame buffers](/quest/m2/capture-frame-buffers.md) - its GDI half disappears with `window.rs` +- [Direct3D11 render import](/quest/m2/render-d3d11.md) - the other end of keeping Windows frames on the GPU diff --git a/quest/m2/capture-windows.md b/quest/m2/capture-windows.md index c52a3ae046b..5e3f4a14043 100644 --- a/quest/m2/capture-windows.md +++ b/quest/m2/capture-windows.md @@ -1,18 +1,13 @@ -# [L] Windows capture parity +# [M] Windows capture parity ## Goal -App capture, system audio, and whole-screen cursor capture work on Windows. -Window capture landed with the native screen capture work; these are what it -left behind. +App capture and system audio work on Windows. Display and window capture, +including the cursor, move to +[Windows.Graphics.Capture](/quest/m2/capture-wgc.md). ## Plan -Window capture and its cursor now exist: `capture/window.rs` enumerates -top-level windows, captures the selected one through GDI, composites the cursor -when `config.cursor` asks for it, and surfaces the ids through `moq devices`. -What remains: - - **Applications** (every window of a process, including ones that open later) are still `Unsupported` outside macOS, where `SCShareableContent` gives it almost free. Windows has no direct equivalent, so this needs per-window @@ -22,21 +17,13 @@ What remains: exists but is macOS-only and returns `Unsupported` elsewhere. Unlike macOS this does not go through the screen-capture API, so it is an independent path and does not inherit the Screen Recording permission coupling. -- **The cursor on whole-screen capture** is still missing: the Desktop - Duplication backend handles neither `PointerShape` nor `PointerPosition`, so - `config.cursor` controls nothing there. Window capture and both other - platforms honor it, which makes this the odd one out. -Note that the window capture that landed is GDI. It now reaches -DirectComposition content through `PrintWindow(PW_RENDERFULLCONTENT)`, but that -call runs on the target window's UI thread, so the backend probes the window for -responsiveness every frame and skips one that is hung, and it still round-trips -BGRA through the CPU on its way to I420. Windows.Graphics.Capture has neither -coupling and delivers `IDirect3DSurface` frames the existing D3D11 path could -take zero-copy. WGC would also answer app capture and the cursor, so weigh -these three against doing that once. +WGC does not answer app capture. It captures one monitor or one window per +item and has no per-process source, so the per-window-composition or +window-only decision still stands after that backend lands. ## Related +- [Windows.Graphics.Capture](/quest/m2/capture-wgc.md) - display and window capture with the cursor, which this quest no longer owns - [Linux capture parity](/quest/m2/capture-linux.md) - the same gaps, through the portal and PipeWire From 146769e5909a68b5475914fe72413a349623958d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 07:21:52 -0700 Subject: [PATCH 101/128] quest: apply the 2026-09-30 audit (#4589) Co-authored-by: Claude Opus 5.5 --- quest/README.md | 22 ++-- quest/m0/README.md | 50 +++++---- quest/m0/audio-jitter-target/README.md | 21 ++-- quest/m0/audio-jitter-target/watch.md | 6 +- quest/m0/frame-alloc-budget.md | 2 +- quest/m0/ietf-fin-not-cancel.md | 5 +- quest/m0/ietf-legal-input.md | 3 +- quest/m0/ietf-subgroup-refusal.md | 26 +++++ quest/{m1 => m0}/ietf-uni-stream-types.md | 4 + quest/m0/noq-reassembly-cap.md | 12 +- quest/m0/qmux-reset-race.md | 2 +- quest/m0/quest-check-everywhere.md | 24 ++-- quest/m0/remove-gossip.md | 14 ++- quest/m0/request-caps.md | 4 + quest/m0/shared-fronts.md | 2 +- quest/m0/wildcard/README.md | 28 +++-- ...r-a-synchronous-decode-so-the-publisher.md | 53 +++------ ...s-dropping-one-split-server-resizes-the.md | 35 ------ ...ic-tracks-and-preserve-sequences-across.md | 5 + ...generated-media-timelines-to-wall-clock.md | 53 +++++---- quest/m1/README.md | 65 ++++------- quest/m1/archive/README.md | 2 - quest/m1/archive/enrollment-flake.md | 2 +- quest/m1/archive/writer.md | 8 ++ quest/m1/audio-codecs/README.md | 1 - quest/m1/auth/README.md | 11 +- quest/m1/auth/bindings.md | 29 ++--- quest/m1/auth/lite.md | 5 - quest/m1/auth/peer-grant.md | 4 +- quest/m1/auth/relay-refresh.md | 1 - quest/m1/auth/request-token.md | 5 +- quest/m1/auth/token-in-band.md | 7 +- quest/{m0/plan-av-clock.md => m1/av-clock.md} | 3 + quest/m1/bbr-ack-cleanup.md | 10 +- quest/m1/bench-ci.md | 2 +- quest/m1/bench-coverage.md | 28 ----- quest/m1/bindings-graceful-close.md | 15 --- quest/m1/broadcast-epoch/README.md | 6 +- quest/m1/broadcast-epoch/bindings.md | 10 +- quest/m1/broadcast-epoch/gst-obs.md | 8 +- quest/m1/broadcast-epoch/origin.md | 5 + quest/m1/cache-expiry-growth.md | 4 - quest/m1/cache-wall-eviction.md | 2 +- quest/m1/capture-control.md | 50 --------- quest/m1/cli-packaging.md | 14 +++ quest/m1/cli-serve.md | 9 +- quest/m1/close-codes.md | 42 ------- .../README.md} | 48 +++++++- quest/m1/color-model.md | 54 ++------- quest/m1/cpp/README.md | 19 ++-- quest/m1/cpp/generator.md | 2 +- quest/m1/cross-relay-bursts.md | 2 +- quest/m1/dart-codecs.md | 7 ++ quest/m1/dart-publish.md | 6 +- quest/m1/data-track-clock.md | 7 +- quest/m1/datagram-unfetchable.md | 11 ++ quest/m1/drain/README.md | 2 +- quest/m1/effect-cancel.md | 12 -- quest/m1/ffi-shape/README.md | 4 - quest/m1/ffi-shape/codec.md | 2 +- quest/m1/ffi-shape/net.md | 10 +- quest/m1/frame-slot-charge.md | 4 +- quest/m1/gpu-ci.md | 1 - quest/m1/hls-discontinuity-sequence.md | 37 ------ quest/m1/hop-aligned-import.md | 7 +- quest/{m2 => m1}/ietf-drain-before-close.md | 4 - quest/m1/js-closed-track-leak.md | 18 --- quest/m1/js-fetch.md | 2 +- quest/m1/legacy-end-overshoot.md | 22 +++- quest/m1/merge-queue.md | 13 ++- quest/m1/mobile-ownership.md | 22 ++++ quest/m1/moq-installer.md | 84 -------------- quest/m1/obs-moq-video/README.md | 20 ++-- quest/m1/obs-moq-video/linux-bundle.md | 4 +- quest/m1/obs-moq-video/preset-parity.md | 4 +- quest/m1/obs-moq-video/source.md | 3 +- quest/m1/obs-moq-video/vpx.md | 2 +- quest/m1/origin-front-parks.md | 8 ++ quest/m1/p2p/transit.md | 37 ------ quest/m1/parked-read-wakes.md | 8 ++ quest/m1/path-patterns.md | 105 ------------------ ...relay-cpu-is-vdso-clock-reads-the-drive.md | 2 +- ...-moq-uring-add-opt-in-napi-busy-polling.md | 30 ----- ...-reusable-io-uring-enter-wait-arguments.md | 35 ------ quest/m1/perf/README.md | 42 +++---- quest/m1/perf/coding-decode.md | 31 ------ quest/m1/perf/egress-keepalive.md | 35 ------ quest/m1/perf/egress-requeue.md | 31 ------ quest/m1/perf/group-cost.md | 15 ++- quest/m1/perf/lock-wait.md | 7 +- quest/m1/perf/priority-set-track-wakes.md | 42 ------- quest/m1/perf/uring-one-enter.md | 4 +- quest/m1/perf/uring-quiescence.md | 21 ++-- quest/m1/performance-comparisons.md | 15 ++- quest/m1/performance-profiles.md | 1 - quest/m1/plan-watch-worker.md | 2 +- quest/{m2 => m1}/play-drain-tail.md | 0 quest/m1/qos/README.md | 3 - quest/m1/qos/starvation.md | 4 +- quest/m1/quic/README.md | 52 ++++----- quest/m1/quic/release.md | 32 ------ quest/m1/quic/reliable-reset.md | 4 +- quest/m1/quic/scheduler.md | 6 +- quest/m1/quic/upstream.md | 31 +++--- quest/m1/quic/uring-close.md | 6 + quest/m1/raw-stream-codes.md | 12 +- quest/m1/relay-auth-client-ca.md | 8 +- quest/m1/relay-iroh-opt-in.md | 4 +- quest/m1/relay-memory.md | 41 ------- quest/m1/remove-live.md | 49 -------- quest/m1/resume-latest.md | 2 + quest/m1/rs2ts/README.md | 22 ++-- quest/m1/rs2ts/sans-io/README.md | 9 +- quest/m1/rs2ts/sans-io/async-feature.md | 2 +- quest/{m2 => m1}/serve-hls-renditions.md | 0 quest/m1/session-close.md | 34 ------ quest/m1/session-death.md | 4 - quest/m1/stats-producer-bench.md | 33 ------ quest/m1/stats/README.md | 31 ++---- quest/m1/subscribe-drop.md | 13 ++- quest/m1/test-flakes-2.md | 90 --------------- quest/m1/test-flakes-2/README.md | 46 ++++++++ quest/m1/test-flakes-2/broadcast-race.md | 22 ++++ quest/m1/test-flakes-2/cli-paused-clock.md | 30 +++++ quest/m1/test-flakes-2/media-late-join.md | 15 +++ quest/m1/test-flakes-2/mux-debounce-clock.md | 15 +++ quest/m1/test-flakes-2/publish-audio-clock.md | 11 ++ .../shaper-virtual-time.md | 0 quest/m1/test-flakes-2/subscription-cut.md | 14 +++ quest/m1/test-flakes-2/warn-capture.md | 14 +++ .../m1/test-flakes-2/websocket-paused-tls.md | 14 +++ quest/m1/track-demand.md | 22 ---- quest/m1/track-priority-scope.md | 7 ++ quest/m1/track-tail-interop.md | 18 +-- quest/m1/transport-upgrade/README.md | 2 +- quest/m1/ts-import-shared-shift.md | 4 - quest/m1/unknown-session-logs.md | 46 -------- quest/m1/uring-ietf.md | 4 +- quest/m1/video-surface.md | 36 ------ quest/m1/watch-audio-time-stretch.md | 3 +- quest/m1/watch-refusal.md | 38 ------- quest/m1/watch-worker.md | 2 +- quest/m1/wt-close-upstream.md | 9 +- ...evc-and-av1-support-in-the-nvidia-codec.md | 22 ++-- ...te-35-ad-cue-signaling-carried-opaquely.md | 10 +- ...ipewire-dma-bufs-safely-into-the-vulkan.md | 11 +- ...-the-webtransport-stream-header-at-open.md | 6 +- ...tch-completion-wakeups-with-min-timeout.md | 3 + ...fixed-file-slots-for-worker-udp-sockets.md | 3 + quest/m2/README.md | 101 ++++++++++------- quest/{m3 => m2}/announce-shapes.md | 21 ++-- quest/m2/archive-backward-timestamps.md | 16 --- .../browser.md => m2/archive-browser.md} | 6 +- .../archive-paced-replay.md} | 6 + quest/m2/audio-decode-mediacodec.md | 1 + quest/m2/audio-decode-mediafoundation.md | 3 +- quest/m2/audio-encode-mediacodec.md | 1 + quest/m2/audio-encode-mediafoundation.md | 4 - quest/m2/audio-loss-recovery.md | 28 ----- quest/m2/audio-opus-backend.md | 25 ++++- quest/m2/av1-metadata.md | 8 +- quest/m2/bench-coverage.md | 50 +++++++++ quest/m2/browser-media-qa-engines.md | 8 +- quest/{m1/perf => m2}/cache-shard.md | 5 + quest/{m1 => m2}/captions-cea.md | 4 +- quest/m2/capture-ergonomics.md | 27 ----- quest/m2/capture-frame-buffers.md | 24 ---- quest/m2/capture-wgc.md | 2 +- quest/m2/carrier-voice/README.md | 56 ---------- quest/m2/carrier-voice/proof.md | 35 ------ quest/m2/carrier-voice/protocol.md | 44 -------- quest/m2/carrier-voice/sip-originate.md | 32 ------ quest/m2/carrier-voice/verdict.md | 44 -------- quest/m2/catalog-tracks.md | 56 ++++------ quest/{m1 => m2}/closure-counters.md | 2 + quest/m2/color-catalog.md | 56 ++++++++++ quest/m2/cpp-vcpkg.md | 2 +- quest/{m1 => m2}/emsg.md | 8 +- quest/m2/flate.md | 40 +++++++ quest/m2/flate/README.md | 22 ---- quest/m2/flate/bindings.md | 32 ------ quest/{m1 => m2}/flv-script.md | 10 +- quest/m2/gop-overhead.md | 4 + quest/{m1 => m2}/id3.md | 10 +- quest/m2/intra-refresh/README.md | 23 ++-- quest/m2/js-discontinuity.md | 22 ---- quest/{m1 => m2}/ladder/README.md | 7 +- quest/{m1 => m2}/ladder/controller.md | 2 +- quest/{m1 => m2}/ladder/fetch.md | 2 +- quest/m2/livekit-webrtc-bridge.md | 27 ----- quest/m2/mobile-capture-android.md | 2 +- quest/m2/mobile-capture-ios.md | 2 +- quest/m2/mobile-completion.md | 2 +- quest/m2/mobile-ownership.md | 26 ----- quest/{m1 => m2}/moq-install-url.md | 8 +- quest/m2/moq-installer.md | 52 +++++++++ quest/{m1 => m2}/moq-relay-subcommand.md | 3 + quest/m2/msfts-convergence.md | 26 +++++ quest/m2/nvenc-pool.md | 8 +- .../obs-decode-linux.md} | 2 +- .../obs-decode-windows.md} | 0 .../macos.md => m2/obs-macos.md} | 0 .../windows.md => m2/obs-windows.md} | 0 quest/{m1 => m2}/one-port/README.md | 13 ++- quest/{m1 => m2}/one-port/srt-demux.md | 4 +- quest/{m1 => m2}/one-port/tcp-demux.md | 2 +- quest/{m1 => m2}/one-port/udp-demux.md | 34 +++--- quest/{m1 => m2}/p2p/README.md | 38 +++---- quest/{m1 => m2}/p2p/cli.md | 6 +- quest/{m1 => m2}/p2p/cost-scopes.md | 8 +- quest/{m1 => m2}/p2p/harness.md | 6 +- quest/{m1 => m2}/p2p/signal.md | 14 +-- quest/m2/p2p/transit.md | 35 ++++++ quest/{m1 => m2}/p2p/transport.md | 6 +- quest/{m1 => m2}/p2p/unordered.md | 9 +- quest/{m1 => m2}/p2p/watch.md | 12 +- quest/{m1 => m2}/p2p/webrtc.md | 8 +- quest/m2/pipewire-camera-planes.md | 1 - quest/{m1 => m2}/processor/README.md | 14 +-- quest/{m1 => m2}/processor/advertise-auth.md | 2 +- quest/{m1 => m2}/processor/grant-lease.md | 4 +- quest/{m1 => m2}/processor/media-contract.md | 4 + .../quic/ack-hook.md => m2/quic-ack-hook.md} | 29 +++-- .../quic-ack-progress.md} | 9 +- quest/m2/quic-bbr-google.md | 40 ------- .../quic-bbr-loss-parity.md} | 4 + quest/m2/quic-bbr-natural-drain.md | 45 +++++++- quest/m2/quic-buffer-pool.md | 27 ----- .../quic/deadline.md => m2/quic-deadline.md} | 8 +- .../ecn-measure.md => m2/quic-ecn-measure.md} | 3 + quest/m2/quic-ecn.md | 4 +- quest/m2/quic-egress-profile.md | 56 ++++++++++ quest/m2/quic-fec.md | 30 ----- quest/m2/quic-keep-alive.md | 10 +- quest/m2/quic-kernel-pacing.md | 40 ------- quest/m2/quic-probe.md | 3 +- quest/{m1/quic/qmux.md => m2/quic-qmux.md} | 15 ++- quest/m2/quic-send-batching.md | 28 ----- quest/m2/redundant-ingest.md | 30 ----- quest/m2/relay-io-uring-package.md | 4 +- quest/{m1/rs2ts/ietf.md => m2/rs2ts-ietf.md} | 5 +- .../ietf.md => m2/rs2ts-sans-io-ietf.md} | 3 + quest/m2/runtime-qa-hosts.md | 43 ------- quest/m2/sei.md | 39 +++++++ quest/m2/sei/README.md | 33 ------ quest/m2/sei/evidence.md | 32 ------ quest/m2/sei/sei-rust.md | 37 ------ quest/m2/sei/sei-web.md | 29 ----- quest/m2/sei/sei.md | 54 --------- quest/{m1 => m2}/signed-priority.md | 5 + quest/m2/sip-stack.md | 34 ------ quest/{m1/qos => m2}/starvation-frames.md | 6 +- quest/m2/stats-delta.md | 6 +- .../stats-encoder-feedback.md} | 24 +++- quest/m2/teleop/README.md | 53 ++++----- quest/m2/teleop/correlation.md | 32 ------ quest/m2/teleop/robot.md | 22 ++++ quest/m2/teleop/ros2.md | 38 ------- quest/m2/teleop/v4l2-encode.md | 43 ------- quest/{m1 => m2}/text-schema.md | 2 + quest/m2/ts-import-health.md | 2 +- quest/{m1/perf => m2}/uring-open-contract.md | 6 +- quest/{m1 => m2}/uring-tcp/README.md | 15 ++- quest/{m1 => m2}/uring-tcp/ablation.md | 0 quest/{m1 => m2}/uring-tcp/relay.md | 4 +- quest/{m1 => m2}/uring-tcp/stream.md | 2 +- quest/m2/video-codec-coverage.md | 2 +- quest/{m4 => m2}/video-vaapi.md | 30 ++--- quest/m2/x11-capture-shm.md | 13 ++- ...ipewire-dma-buf-capture-on-kde-hardware.md | 66 ----------- ...use-sendmsg-zc-for-large-udp-gso-trains.md | 8 ++ ...ter-tx-pool-buffers-for-zero-copy-sends.md | 6 +- quest/m3/README.md | 50 +++++++-- quest/{m2 => m3}/af-xdp.md | 14 ++- quest/{m2 => m3}/cat/README.md | 9 +- quest/{m2 => m3}/cat/present.md | 8 +- quest/{m2 => m3}/cat/verify.md | 0 quest/{m2 => m3}/cpp-conan.md | 3 + quest/{m2 => m3}/cs/README.md | 9 +- quest/{m2 => m3}/cs/generator.md | 0 quest/{m2 => m3}/cs/package.md | 2 +- quest/m3/dpdk.md | 28 ----- quest/{m2 => m3}/hidden-exemption.md | 5 +- .../intra-refresh-bindings.md} | 2 +- .../intra-refresh-encode-config.md} | 6 + .../intra-refresh-nvenc.md} | 10 +- .../intra-refresh-v4l2.md} | 2 +- quest/{m2 => m3}/livekit-shim.md | 18 +-- quest/m3/nvenc-av1.md | 31 ++++++ quest/{m2 => m3}/obs-linux-gpu.md | 5 +- quest/m3/pipewire-camera-hardware.md | 23 ---- quest/m3/processor-vision.md | 43 ------- quest/{m2 => m3}/quic-gcc.md | 7 +- quest/{m2 => m3}/quic-receive-ts.md | 14 ++- quest/{m2 => m3}/routing-cost-domains.md | 8 +- .../teleop-browser-package.md} | 2 + .../mavlink.md => m3/teleop-mavlink.md} | 2 + .../teleop/proof.md => m3/teleop-proof.md} | 6 +- quest/{m2 => m3}/unity.md | 4 +- quest/{m2 => m3}/unreal.md | 4 +- quest/m3/upstream-forks.md | 62 ----------- quest/m3/video-hardware.md | 66 +++++++++-- quest/{m2 => m3}/watch-data-sync.md | 9 +- quest/{m2 => m3}/whep-abr.md | 7 ++ quest/m4/README.md | 8 +- quest/m4/msfts-convergence.md | 22 ---- quest/m4/safari-webtransport.md | 2 +- quest/m4/vaapi-resize-pool.md | 19 ---- 308 files changed, 2017 insertions(+), 3341 deletions(-) create mode 100644 quest/m0/ietf-subgroup-refusal.md rename quest/{m1 => m0}/ietf-uni-stream-types.md (92%) delete mode 100644 quest/m1/2964-quic-workers-dropping-one-split-server-resizes-the.md rename quest/{m0/plan-av-clock.md => m1/av-clock.md} (95%) delete mode 100644 quest/m1/bench-coverage.md delete mode 100644 quest/m1/bindings-graceful-close.md delete mode 100644 quest/m1/capture-control.md delete mode 100644 quest/m1/close-codes.md rename quest/m1/{cluster-routing.md => cluster-routing/README.md} (83%) delete mode 100644 quest/m1/effect-cancel.md delete mode 100644 quest/m1/hls-discontinuity-sequence.md rename quest/{m2 => m1}/ietf-drain-before-close.md (84%) delete mode 100644 quest/m1/js-closed-track-leak.md create mode 100644 quest/m1/mobile-ownership.md delete mode 100644 quest/m1/moq-installer.md delete mode 100644 quest/m1/p2p/transit.md delete mode 100644 quest/m1/path-patterns.md delete mode 100644 quest/m1/perf/3203-moq-uring-add-opt-in-napi-busy-polling.md delete mode 100644 quest/m1/perf/3205-moq-uring-register-reusable-io-uring-enter-wait-arguments.md delete mode 100644 quest/m1/perf/coding-decode.md delete mode 100644 quest/m1/perf/egress-keepalive.md delete mode 100644 quest/m1/perf/egress-requeue.md delete mode 100644 quest/m1/perf/priority-set-track-wakes.md rename quest/{m2 => m1}/play-drain-tail.md (100%) delete mode 100644 quest/m1/quic/release.md delete mode 100644 quest/m1/relay-memory.md delete mode 100644 quest/m1/remove-live.md rename quest/{m2 => m1}/serve-hls-renditions.md (100%) delete mode 100644 quest/m1/session-close.md delete mode 100644 quest/m1/stats-producer-bench.md delete mode 100644 quest/m1/test-flakes-2.md create mode 100644 quest/m1/test-flakes-2/README.md create mode 100644 quest/m1/test-flakes-2/broadcast-race.md create mode 100644 quest/m1/test-flakes-2/cli-paused-clock.md create mode 100644 quest/m1/test-flakes-2/media-late-join.md create mode 100644 quest/m1/test-flakes-2/mux-debounce-clock.md create mode 100644 quest/m1/test-flakes-2/publish-audio-clock.md rename quest/m1/{ => test-flakes-2}/shaper-virtual-time.md (100%) create mode 100644 quest/m1/test-flakes-2/subscription-cut.md create mode 100644 quest/m1/test-flakes-2/warn-capture.md create mode 100644 quest/m1/test-flakes-2/websocket-paused-tls.md delete mode 100644 quest/m1/track-demand.md delete mode 100644 quest/m1/unknown-session-logs.md delete mode 100644 quest/m1/video-surface.md delete mode 100644 quest/m1/watch-refusal.md rename quest/{m1 => m2}/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md (90%) rename quest/{m1/perf => m2}/3129-moq-uring-write-the-webtransport-stream-header-at-open.md (90%) rename quest/{m1/perf => m2}/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md (93%) rename quest/{m1/perf => m2}/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md (93%) rename quest/{m3 => m2}/announce-shapes.md (87%) delete mode 100644 quest/m2/archive-backward-timestamps.md rename quest/{m1/archive/browser.md => m2/archive-browser.md} (91%) rename quest/{m1/archive/paced-replay.md => m2/archive-paced-replay.md} (86%) delete mode 100644 quest/m2/audio-loss-recovery.md create mode 100644 quest/m2/bench-coverage.md rename quest/{m1/perf => m2}/cache-shard.md (90%) rename quest/{m1 => m2}/captions-cea.md (92%) delete mode 100644 quest/m2/capture-ergonomics.md delete mode 100644 quest/m2/capture-frame-buffers.md delete mode 100644 quest/m2/carrier-voice/README.md delete mode 100644 quest/m2/carrier-voice/proof.md delete mode 100644 quest/m2/carrier-voice/protocol.md delete mode 100644 quest/m2/carrier-voice/sip-originate.md delete mode 100644 quest/m2/carrier-voice/verdict.md rename quest/{m1 => m2}/closure-counters.md (95%) create mode 100644 quest/m2/color-catalog.md rename quest/{m1 => m2}/emsg.md (93%) create mode 100644 quest/m2/flate.md delete mode 100644 quest/m2/flate/README.md delete mode 100644 quest/m2/flate/bindings.md rename quest/{m1 => m2}/flv-script.md (82%) rename quest/{m1 => m2}/id3.md (87%) delete mode 100644 quest/m2/js-discontinuity.md rename quest/{m1 => m2}/ladder/README.md (94%) rename quest/{m1 => m2}/ladder/controller.md (98%) rename quest/{m1 => m2}/ladder/fetch.md (95%) delete mode 100644 quest/m2/livekit-webrtc-bridge.md delete mode 100644 quest/m2/mobile-ownership.md rename quest/{m1 => m2}/moq-install-url.md (91%) create mode 100644 quest/m2/moq-installer.md rename quest/{m1 => m2}/moq-relay-subcommand.md (93%) create mode 100644 quest/m2/msfts-convergence.md rename quest/{m1/obs-moq-video/decode-linux.md => m2/obs-decode-linux.md} (96%) rename quest/{m1/obs-moq-video/decode-windows.md => m2/obs-decode-windows.md} (100%) rename quest/{m1/obs-moq-video/macos.md => m2/obs-macos.md} (100%) rename quest/{m1/obs-moq-video/windows.md => m2/obs-windows.md} (100%) rename quest/{m1 => m2}/one-port/README.md (88%) rename quest/{m1 => m2}/one-port/srt-demux.md (94%) rename quest/{m1 => m2}/one-port/tcp-demux.md (96%) rename quest/{m1 => m2}/one-port/udp-demux.md (59%) rename quest/{m1 => m2}/p2p/README.md (82%) rename quest/{m1 => m2}/p2p/cli.md (89%) rename quest/{m1 => m2}/p2p/cost-scopes.md (89%) rename quest/{m1 => m2}/p2p/harness.md (90%) rename quest/{m1 => m2}/p2p/signal.md (91%) create mode 100644 quest/m2/p2p/transit.md rename quest/{m1 => m2}/p2p/transport.md (91%) rename quest/{m1 => m2}/p2p/unordered.md (87%) rename quest/{m1 => m2}/p2p/watch.md (74%) rename quest/{m1 => m2}/p2p/webrtc.md (89%) rename quest/{m1 => m2}/processor/README.md (80%) rename quest/{m1 => m2}/processor/advertise-auth.md (98%) rename quest/{m1 => m2}/processor/grant-lease.md (92%) rename quest/{m1 => m2}/processor/media-contract.md (89%) rename quest/{m1/quic/ack-hook.md => m2/quic-ack-hook.md} (62%) rename quest/{m1/quic/ack-progress.md => m2/quic-ack-progress.md} (84%) delete mode 100644 quest/m2/quic-bbr-google.md rename quest/{m1/quic/bbr-loss-parity.md => m2/quic-bbr-loss-parity.md} (91%) delete mode 100644 quest/m2/quic-buffer-pool.md rename quest/{m1/quic/deadline.md => m2/quic-deadline.md} (89%) rename quest/{m1/quic/ecn-measure.md => m2/quic-ecn-measure.md} (94%) create mode 100644 quest/m2/quic-egress-profile.md delete mode 100644 quest/m2/quic-fec.md delete mode 100644 quest/m2/quic-kernel-pacing.md rename quest/{m1/quic/qmux.md => m2/quic-qmux.md} (78%) delete mode 100644 quest/m2/quic-send-batching.md delete mode 100644 quest/m2/redundant-ingest.md rename quest/{m1/rs2ts/ietf.md => m2/rs2ts-ietf.md} (71%) rename quest/{m1/rs2ts/sans-io/ietf.md => m2/rs2ts-sans-io-ietf.md} (85%) delete mode 100644 quest/m2/runtime-qa-hosts.md create mode 100644 quest/m2/sei.md delete mode 100644 quest/m2/sei/README.md delete mode 100644 quest/m2/sei/evidence.md delete mode 100644 quest/m2/sei/sei-rust.md delete mode 100644 quest/m2/sei/sei-web.md delete mode 100644 quest/m2/sei/sei.md rename quest/{m1 => m2}/signed-priority.md (89%) delete mode 100644 quest/m2/sip-stack.md rename quest/{m1/qos => m2}/starvation-frames.md (92%) rename quest/{m1/stats/encoder-feedback.md => m2/stats-encoder-feedback.md} (76%) delete mode 100644 quest/m2/teleop/correlation.md delete mode 100644 quest/m2/teleop/ros2.md delete mode 100644 quest/m2/teleop/v4l2-encode.md rename quest/{m1 => m2}/text-schema.md (95%) rename quest/{m1/perf => m2}/uring-open-contract.md (75%) rename quest/{m1 => m2}/uring-tcp/README.md (76%) rename quest/{m1 => m2}/uring-tcp/ablation.md (100%) rename quest/{m1 => m2}/uring-tcp/relay.md (92%) rename quest/{m1 => m2}/uring-tcp/stream.md (96%) rename quest/{m4 => m2}/video-vaapi.md (66%) delete mode 100644 quest/m3/2893-video-validate-pipewire-dma-buf-capture-on-kde-hardware.md rename quest/{m1/perf => m3}/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md (90%) rename quest/{m1/perf => m3}/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md (88%) rename quest/{m2 => m3}/af-xdp.md (65%) rename quest/{m2 => m3}/cat/README.md (90%) rename quest/{m2 => m3}/cat/present.md (88%) rename quest/{m2 => m3}/cat/verify.md (100%) rename quest/{m2 => m3}/cpp-conan.md (91%) rename quest/{m2 => m3}/cs/README.md (78%) rename quest/{m2 => m3}/cs/generator.md (100%) rename quest/{m2 => m3}/cs/package.md (94%) delete mode 100644 quest/m3/dpdk.md rename quest/{m2 => m3}/hidden-exemption.md (84%) rename quest/{m2/intra-refresh/bindings.md => m3/intra-refresh-bindings.md} (94%) rename quest/{m2/intra-refresh/encode-config.md => m3/intra-refresh-encode-config.md} (86%) rename quest/{m2/intra-refresh/nvenc-refresh.md => m3/intra-refresh-nvenc.md} (78%) rename quest/{m2/intra-refresh/v4l2-refresh.md => m3/intra-refresh-v4l2.md} (96%) rename quest/{m2 => m3}/livekit-shim.md (74%) create mode 100644 quest/m3/nvenc-av1.md rename quest/{m2 => m3}/obs-linux-gpu.md (93%) delete mode 100644 quest/m3/pipewire-camera-hardware.md delete mode 100644 quest/m3/processor-vision.md rename quest/{m2 => m3}/quic-gcc.md (82%) rename quest/{m2 => m3}/quic-receive-ts.md (73%) rename quest/{m2 => m3}/routing-cost-domains.md (93%) rename quest/{m2/teleop/browser-package.md => m3/teleop-browser-package.md} (93%) rename quest/{m2/teleop/mavlink.md => m3/teleop-mavlink.md} (97%) rename quest/{m2/teleop/proof.md => m3/teleop-proof.md} (82%) rename quest/{m2 => m3}/unity.md (89%) rename quest/{m2 => m3}/unreal.md (85%) delete mode 100644 quest/m3/upstream-forks.md rename quest/{m2 => m3}/watch-data-sync.md (71%) rename quest/{m2 => m3}/whep-abr.md (77%) delete mode 100644 quest/m4/msfts-convergence.md delete mode 100644 quest/m4/vaapi-resize-pool.md diff --git a/quest/README.md b/quest/README.md index dcc3e3b52d5..38d4b4b9bc4 100644 --- a/quest/README.md +++ b/quest/README.md @@ -7,18 +7,24 @@ grouped into milestones ordered by priority. ## Plan -m0 is everything in flight now: announce and wildcard routing, and audio -playout (jitter target, quality harness, A/V clock). m1 is the next wave across reliability, features, -performance, and planning. m2 holds later features, design studies, and -experiments. m3 is deferred: work whose first step is outside this repository. -m4 waits on an upstream release or external dependency to ship. Priority is +m0 is everything in flight now: relay hardening and IETF interop ahead of +Seattle, wildcard routing, and audio playout (jitter target and quality +harness). m1 is the next wave across reliability, features, performance, and +planning. m2 holds later features, design studies, and experiments. m3 is +gated on the outside world: hardware, a partner, a consumer, or a provider's +offer. m4 waits on an upstream release. Priority is separate from branch targeting: published API and wire breaks still land on dev under the repository rules. +A quest waiting on the outside world, in any milestone, states that condition +as a plain-text `Required` bullet, so `quest ready` reports it blocked. +`/quest-audit` re-checks those gates; when one clears, remove the bullet and +move the quest to the milestone its priority belongs in. + ## Required -- [m0: immediate priorities](/quest/m0/README.md) - everything in flight now: announce and wildcard routing, and audio playout +- [m0: immediate priorities](/quest/m0/README.md) - everything in flight now: relay hardening and IETF interop for Seattle, wildcard routing, and audio playout - [m1: next wave](/quest/m1/README.md) - reliability, capabilities, performance, and the planning that settles their contracts - [m2: later work](/quest/m2/README.md) - deferred features, design studies, and experiments -- [m3: deferred](/quest/m3/README.md) - gated on the outside world: hardware nobody has, a partner, or a provider's offer -- [m4: upstream](/quest/m4/README.md) - waiting on an upstream release or external dependency, re-checked periodically +- [m3: deferred](/quest/m3/README.md) - gated on the outside world: hardware, a partner, a consumer, or a provider's offer +- [m4: upstream](/quest/m4/README.md) - waiting on an upstream release, re-checked periodically diff --git a/quest/m0/README.md b/quest/m0/README.md index d0507ec5504..fae3a99c494 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -2,14 +2,13 @@ ## Goal -The work in flight now, in three independent tracks. Relay hardening: every -resource a peer can make the relay hold is bounded by what it sent or by a -budget, no peer input panics the process, and legal moq-transport input never -fails a session, ahead of Seattle interop on 2026-10-12. Routing: a publisher stops -sending announce updates the wire cannot tell apart, a service claims the -prefix it could serve instead of enumerating broadcasts. Audio playout: the target is a measured -estimate of arrival timing in both languages, a browser regression fails a -nightly run, and the audio playhead becomes the clock video follows. +The work in flight now, in three independent tracks. Relay hardening: legal +moq-transport input never fails a session ahead of Seattle interop on +2026-10-12, every resource a peer can make the relay hold is bounded by what +it sent or by a budget, and no peer input panics the process. Routing: a +service claims the prefix it could serve instead of enumerating broadcasts. +Audio playout: the target is a measured estimate of arrival timing in both +languages, and a browser regression fails a nightly run. ## Plan @@ -18,24 +17,35 @@ done. moq.pro tracks this repository as a submodule rather than a release, so no release quest gates this milestone. The Pronto GPU integration lives in moq.pro. -Routing: announce-update dedupe is a wire-compatible fix on every version. The -wildcard line is prefix-only on the wire; its resolve and demand work is done -on the line branch and waits to land. Serving the relay's ingested-only -view (`origin::Consumer::local()`) to localhost workers belongs to moq.pro's -edge, which embeds moq-relay; it moved there on 2026-09-28. +Relay hardening: IETF interop leads the ranking, since only those quests +block Seattle. Subgroup refusal came from the moxygen line and IETF stream +types from m1; both moved here in the 2026-09-30 audit because a session +ended by legal input is exactly what Seattle would hit. The DoS hardening +from an external review on 2026-09-29, verified against `main`, stays in m0 +as security work. Its quests describe fixes, not exploits. + +Routing: the wildcard line is prefix-only on the wire; its resolve and demand +work is done on the line branch and waits to land. Serving the relay's +ingested-only view (`origin::Consumer::local()`) to localhost workers belongs +to moq.pro's edge, which embeds moq-relay; it moved there on 2026-09-28. Audio playout: the jitter target replaces the round-trip guess. The harness's browser lane grades it nightly and records the traces it replays; the native -lane is a standalone m1 quest, since nothing here waits on it. The A/V clock -builds on the jitter target's per-track spread. - -Relay hardening comes from an external review on 2026-09-29, verified against -`main`. Its quests describe fixes, not exploits. +lane is a standalone m1 quest, since nothing here waits on it. The harness +line lands before the jitter line, since both add +`js/watch/src/audio/replay.test.ts`. The [A/V clock](/quest/m1/av-clock.md) +moved to m1 in the 2026-09-30 audit: it waits on the whole jitter line and is +a published `@moq/watch` break on dev. Published API or wire breaks still land on dev; each quest's Plan says so. ## Required +- [Legal IETF input](/quest/m0/ietf-legal-input.md) - draft-20+ FETCH, allowed parameters, INCLUDE_PROPERTIES and FORWARD=0 decode and are refused per request, not session-fatal +- [IETF FIN semantics](/quest/m0/ietf-fin-not-cancel.md) - a request stream FIN stops updates without cancelling, and REQUEST_UPDATE on a subscribe is parsed +- [Subgroup refusal](/quest/m0/ietf-subgroup-refusal.md) - a non-zero moq-transport subgroup costs that one stream, never the session +- [IETF stream types](/quest/m0/ietf-uni-stream-types.md) - padding streams are discarded stream-only and an unknown uni type closes the session, per draft-21 +- [Request caps](/quest/m0/request-caps.md) - lite message sizes, IETF request IDs, and per-session announces and subscriptions are bounded - [quest check everywhere](/quest/m0/quest-check-everywhere.md) - `quest check` guards `main`, `dev`, and the line branches on push and PR, not only PRs into `main` - [noq reassembly cap](/quest/m0/noq-reassembly-cap.md) - noq carries quinn's stream reassembly cap and the connection receive window is finite by default - [qmux reset race](/quest/m0/qmux-reset-race.md) - qmux handles RESET_STREAM under one lock instead of panicking @@ -43,15 +53,11 @@ Published API or wire breaks still land on dev; each quest's Plan says so. - [Shared fronts](/quest/m0/shared-fronts.md) - viewer sessions share a front, so fronts scale with peers, not viewers - [Frame alloc budget](/quest/m0/frame-alloc-budget.md) - frame buffers pre-allocate within a per-session budget and otherwise grow with bytes received - [Handshake deadline](/quest/m0/handshake-deadline.md) - an unfinished handshake or slow HTTP header times out -- [Request caps](/quest/m0/request-caps.md) - lite message sizes, IETF request IDs, and per-session announces and subscriptions are bounded - [Subscriber prune](/quest/m0/subscriber-prune.md) - a track's subscription list holds only live subscribers - [Revalidate overflow](/quest/m0/revalidate-overflow.md) - no auth duration can overflow a deadline and abort the relay -- [Legal IETF input](/quest/m0/ietf-legal-input.md) - draft-20+ FETCH, allowed parameters, INCLUDE_PROPERTIES and FORWARD=0 decode and are refused per request, not session-fatal -- [IETF FIN semantics](/quest/m0/ietf-fin-not-cancel.md) - a request stream FIN stops updates without cancelling, and REQUEST_UPDATE on a subscribe is parsed - [Wildcard](/quest/m0/wildcard/README.md) - a relay resolves subscriptions against advertised prefixes, a service claims the prefix it could serve and refuses the rest instead of enumerating broadcasts, and the browser player treats a covering claim as availability - [Audio quality harness](/quest/m0/audio-quality-harness/README.md) - a browser playout latency regression fails a nightly run instead of arriving as a bug report, and its recorder supplies the jitter target's replay traces - [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - the audio playout target is a measured estimate of arrival timing in both languages, not a round-trip guess -- [A/V clock](/quest/m0/plan-av-clock.md) - the audio playhead drives Sync.reference while audio plays, through per-track sync handles ## Related diff --git a/quest/m0/audio-jitter-target/README.md b/quest/m0/audio-jitter-target/README.md index 9ccd989e690..9b5c88ad7de 100644 --- a/quest/m0/audio-jitter-target/README.md +++ b/quest/m0/audio-jitter-target/README.md @@ -14,8 +14,8 @@ the same arrival trace. Boundaries: convergence still uses skip-ahead and silence, so playing slightly faster or slower to converge stays [Time stretch](/quest/m1/watch-audio-time-stretch.md). No packet loss concealment. -Video keeps its own target; making the audio playhead the clock is [Plan: A/V -clock](/quest/m0/plan-av-clock.md). +Video keeps its own target; making the audio playhead the clock is [A/V +clock](/quest/m1/av-clock.md). ## Plan @@ -42,15 +42,15 @@ reporter; they replace the #3477 traces wherever the quests name them. The algorithm is written down at `doc/concept/audio-jitter.md`, with a conformance corpus beside it that both implementations will read. -Neither `main` nor `dev` has a measured estimator. `js/watch/src/sync.ts:159` +Neither `main` nor `dev` has a measured estimator yet. `js/watch/src/sync.ts:159` still computes `max(MIN_JITTER, minRtt * 1.25)` from the connection's PROBE, and `js/watch/src/audio/latency.ts` still exists. `sync.ts` also adds the advertised jitter to that term, where the document settles on a maximum. -The prior art is the branch of PR #3517, -`origin/quest/m0/3477-watch-auto-latency`, two commits ahead of `dev`. The PR -is closed and never merged; the watch quest starts from the branch rather than -from `dev`. It already deletes the RTT term +The prior art from PR #3517 (closed 2026-09-10, branch deleted 2026-09-30) +landed on this line's branch through +[#3954](https://github.com/moq-dev/moq/pull/3954), so the watch quest works +there. It deletes the RTT term (`MIN_JITTER`, `FALLBACK_JITTER`, `#minRtt`, and the `probe` input are gone from `sync.ts`; `latency.ts` survives, minus `reanchorFloor`) and plumbs a per-track arrival `spread` through `Container.Consumer`, measured at container @@ -66,7 +66,7 @@ is immediate and unclamped, so a tune-in across a stale group sets the target to seconds. Note that `sync.ts` has since been refactored on `main` to a `register(jitter)` -list, so the branch does not rebase cleanly. +list, which is one of the conflicts merging `main` in resolves. Native has no jitter buffer at all. `rs/moq-audio`'s `decode::Options` (`rs/moq-audio/src/decode/consumer.rs`) carries `max_age`, how far @@ -76,7 +76,8 @@ buffer against uneven arrivals. ## Required -- [Watch](/quest/m0/audio-jitter-target/watch.md) - js/watch and js/hang bring the #3517 branch's estimator into conformance +- [Audio quality harness](/quest/m0/audio-quality-harness/README.md) - lands first, since both lines add `js/watch/src/audio/replay.test.ts`; it also records the traces the watch quest replays +- [Watch](/quest/m0/audio-jitter-target/watch.md) - js/watch and js/hang bring the #3954 estimator into conformance - [Native](/quest/m0/audio-jitter-target/native.md) - rs/moq-audio grows a measured jitter buffer from the same algorithm ## Closes @@ -85,6 +86,4 @@ buffer against uneven arrivals. ## Related -- [Audio quality harness](/quest/m0/audio-quality-harness/README.md) - the automated proof, and the recorder of the traces the watch quest replays - [Time stretch](/quest/m1/watch-audio-time-stretch.md) - inaudible convergence, on top of this -- [Plan: A/V clock](/quest/m0/plan-av-clock.md) - the clock this target eventually feeds diff --git a/quest/m0/audio-jitter-target/watch.md b/quest/m0/audio-jitter-target/watch.md index a1a258f61ed..0151ecdd387 100644 --- a/quest/m0/audio-jitter-target/watch.md +++ b/quest/m0/audio-jitter-target/watch.md @@ -92,13 +92,9 @@ The branch also replaces `probe` in `SyncInput` with per-track `audioSpread` and `videoSpread` inputs, which breaks the published `@moq/watch` type. This quest lands on `main`, so it adds the spread inputs beside `probe` and stops reading `probe`; removing it is part of the `SyncInput` reshape in -[Plan: A/V clock](/quest/m0/plan-av-clock.md). Land the estimator so +[Plan: A/V clock](/quest/m1/av-clock.md). Land the estimator so that quest can adopt it without a second estimator change. ## Required - [Browser harness](/quest/m0/audio-quality-harness/browser.md) - records the arrival traces this quest replays - -## Related - -- [Plan: A/V clock](/quest/m0/plan-av-clock.md) - reshapes `SyncInput` around the per-track spread this quest produces diff --git a/quest/m0/frame-alloc-budget.md b/quest/m0/frame-alloc-budget.md index bd55c8a8e47..25c28fba887 100644 --- a/quest/m0/frame-alloc-budget.md +++ b/quest/m0/frame-alloc-budget.md @@ -28,5 +28,5 @@ config, not moq-net. Wire: none. ## Related -- [Frame slot charge](/quest/m1/frame-slot-charge.md) - also changes what a group charges the cache +- [Frame slot charge](/quest/m1/frame-slot-charge.md) - lands first; both change the cache charge in `model/group.rs` - [Peer limits](/quest/m1/quic/peer-limits.md) - stream counts and windows per peer diff --git a/quest/m0/ietf-fin-not-cancel.md b/quest/m0/ietf-fin-not-cancel.md index 329cac16ee3..ccae4e3d282 100644 --- a/quest/m0/ietf-fin-not-cancel.md +++ b/quest/m0/ietf-fin-not-cancel.md @@ -26,7 +26,10 @@ silently ends the subscription. Public API: none. Wire: conformance fix; no draft change. +## Required + +- [Legal IETF input](/quest/m0/ietf-legal-input.md) - lands first; both change `ietf/fetch.rs` and the request close path + ## Related -- [Legal IETF input](/quest/m0/ietf-legal-input.md) - the other interop blocker - [Lite request streams](/quest/m1/request-stream-serve.md) - lite deliberately treats a FIN as ending the request; don't unify the two diff --git a/quest/m0/ietf-legal-input.md b/quest/m0/ietf-legal-input.md index 1faf8828d1f..c90b5f547bf 100644 --- a/quest/m0/ietf-legal-input.md +++ b/quest/m0/ietf-legal-input.md @@ -44,5 +44,6 @@ Public API: none. Wire: fixes conformance; no draft change. ## Related +- [Request token](/quest/m1/auth/request-token.md) - also edits `decode_params!`, turning the ignored token into a per-request grant - [IETF FIN semantics](/quest/m0/ietf-fin-not-cancel.md) - the other interop blocker -- [IETF stream types](/quest/m1/ietf-uni-stream-types.md) - same stream-scoped-before-fatal rule for uni streams +- [IETF stream types](/quest/m0/ietf-uni-stream-types.md) - same stream-scoped-before-fatal rule for uni streams diff --git a/quest/m0/ietf-subgroup-refusal.md b/quest/m0/ietf-subgroup-refusal.md new file mode 100644 index 00000000000..969ea143388 --- /dev/null +++ b/quest/m0/ietf-subgroup-refusal.md @@ -0,0 +1,26 @@ +# [S] Subgroup refusal stays on the stream + +## Goal + +A peer that sends a non-zero subgroup on moq-transport loses that one stream, +never the session. Every other track on the session keeps flowing. + +## Plan + +Against moxygen's `moqtest_server`, a track with two subgroups per group ended +the relay's upstream session, and the server reconnected. Our side refuses the +stream today. Whether the session ends because of how we refuse it (the reset +code, STOP_SENDING, or the alias state it leaves behind) or because the peer +reacts badly to a correct refusal is not known yet. Reproduce it first. If the +peer is at fault, say so on its tracker and keep a regression test for our side. + +A test with an IETF peer that sends a subgroup 1 stream next to a healthy track +is the check. + +Moved from the moxygen line to m0 in the 2026-09-30 audit: a non-zero +subgroup ending the upstream session is exactly m0's "legal input never fails +a session", and moxygen will send it at Seattle interop on 2026-10-12. + +## Related + +- [Moxygen compatibility](/quest/m1/moxygen/README.md) - subgroups stay out of scope; only the blast radius is in diff --git a/quest/m1/ietf-uni-stream-types.md b/quest/m0/ietf-uni-stream-types.md similarity index 92% rename from quest/m1/ietf-uni-stream-types.md rename to quest/m0/ietf-uni-stream-types.md index 6b0ca089c90..1dfd4e01040 100644 --- a/quest/m1/ietf-uni-stream-types.md +++ b/quest/m0/ietf-uni-stream-types.md @@ -8,6 +8,10 @@ so it ships on main. ## Plan +Moved from m1 to m0 in the 2026-09-30 audit: a padding stream answered with +INTERNAL_ERROR is legal input mishandled, which m0 fixes before Seattle +interop on 2026-10-12. + `run_unis` in `rs/moq-net/src/ietf/session.rs` routes every non-SETUP uni stream to `run_uni_group`, which rejects padding and unknown types alike while leaving the session alive. That stream-only rejection reaches the wire as diff --git a/quest/m0/noq-reassembly-cap.md b/quest/m0/noq-reassembly-cap.md index db3e5456fc6..160d9c08f72 100644 --- a/quest/m0/noq-reassembly-cap.md +++ b/quest/m0/noq-reassembly-cap.md @@ -16,14 +16,19 @@ the crates are renamed. RUSTSEC-2026-0185) to moq-dev/noq: `Assembler::insert` returns an error past 1024 buffered chunks after defragmenting, the stream path closes with `INTERNAL_ERROR`, and the CRYPTO path does the same. Keep quinn's test. - Release 1.3.3 and 2.0.1, then bump the pins here. + 1.3.3 and 2.0.1 are already taken by the open release PRs moq-dev/noq#21 + and #22: fold the port into those releases or take the next patch numbers, + then bump the pins here. - Open the same port as a PR on n0-computer/noq (approved 2026-09-29; the advisory is public). iroh builds stay on the unfixed upstream crate until n0 releases it; bump when they do. - Give `moq-tokio` a finite default connection `receive_window` instead of the backend's `VarInt::MAX` (`rs/moq-tokio/src/noq.rs` `apply_windows`, `quic.rs`). Pick the value with a throughput measurement, not a - guess, and update `doc/bin/relay/config.md`. + guess, and update `doc/bin/relay/config.md`. Size it so relay-to-relay + cluster sessions, which carry every viewer's traffic on one connection, + are not throttled; per-peer windows wait for + [Peer limits](/quest/m1/quic/peer-limits.md). - `rs/moq-uring` depends on `moq-noq-proto` too, so the same pin bump covers the io_uring workers. @@ -31,5 +36,4 @@ Public API: none. Wire: a peer that exceeds the chunk cap is closed. ## Related -- [QUIC release](/quest/m1/quic/release.md) - owns the fork's security-update procedure this gap shows is missing -- [Peer limits](/quest/m1/quic/peer-limits.md) - per-peer windows and stream limits +- [Peer limits](/quest/m1/quic/peer-limits.md) - per-peer windows and stream limits, which later let cluster sessions take a larger window than clients diff --git a/quest/m0/qmux-reset-race.md b/quest/m0/qmux-reset-race.md index 6b6143f59a8..0aa6adcdd39 100644 --- a/quest/m0/qmux-reset-race.md +++ b/quest/m0/qmux-reset-race.md @@ -24,4 +24,4 @@ Public API: none. Wire: none. ## Related -- [qmux on noq-proto](/quest/m1/quic/qmux.md) - replaces these stream maps entirely, later +- [qmux on noq-proto](/quest/m2/quic-qmux.md) - replaces these stream maps entirely, later diff --git a/quest/m0/quest-check-everywhere.md b/quest/m0/quest-check-everywhere.md index c62ab16a6f6..447eadfca61 100644 --- a/quest/m0/quest-check-everywhere.md +++ b/quest/m0/quest-check-everywhere.md @@ -7,21 +7,13 @@ ## Plan -- `dev` has no `quest` flake input and no `quest check` in its justfile; - #4428's main-into-dev sync brings both. After it lands, convert the - old-format quests on `dev` until `quest check` passes there. -- Line branches pin their own `quest` revision (the wildcard line pinned - 46d7fe8 against main's 8590d2a), so an old pin passes an old format. - Merging `main` into each active line bumps the pin; do that for the lines - that fail today and fix what the new check reports. -- `just ci check` runs `quest check` on pull requests only. Also run it on - push to `main`, `dev`, and `quest/**`, so a direct merge commit (such as - `main` merged into a line) can't land a broken tree. Use a dedicated job - that runs `quest check` unconditionally: `check.yml`'s scope steps diff - against `origin/$GITHUB_BASE_REF`, which is empty on a push. +- `check.yml` runs `quest check` on pull requests only. Also run it on push to + `main`, `dev`, and `quest/**`, so a direct merge commit (such as `main` + merged into a line) can't land a broken tree. Use a dedicated job that runs + `quest check` unconditionally: `check.yml`'s scope steps diff against + `origin/$GITHUB_BASE_REF`, which is empty on a push. +- `dev` already pins main's `quest` (8590d2a) and passes since #4428. Only the + wildcard line still pins 46d7fe8: merge `main` into it to bump the pin, and + fix what the new check reports. Public API: none. Wire: none. - -## Required - -- #4428 merged to `dev` diff --git a/quest/m0/remove-gossip.md b/quest/m0/remove-gossip.md index 58901b13952..ecf38db9b70 100644 --- a/quest/m0/remove-gossip.md +++ b/quest/m0/remove-gossip.md @@ -23,15 +23,21 @@ through `--cluster-connect-api` and never enables gossip. - Lands on `main` as a security fix, not `dev`. `--cluster-mesh`, `MOQ_CLUSTER_MESH` and `mesh = true` fail at startup with a message pointing at `cluster.connect`, so nobody silently loses their mesh. - Decided 2026-09-29. + Decided 2026-09-29. moq-cli reuses moq-relay's cluster config, so the same + refusal covers `moq`'s `--cluster-mesh` (`doc/bin/cli.md`). +- `rs/moq-net/tests/mesh_withdraw.rs` stays: it already wires origins to + each other directly (`MockPair`), which is what a configured full mesh + does, and its withdraw semantics still apply. Rewrite it only if gossip + removal changes what it exercises. Decided in the 2026-09-30 audit. - Docs: rewrite the Discovery section of `doc/bin/relay/cluster.md`, drop the `.internal/` warning, and add an upgrade note in `doc/setup/upgrade.md`. - Search the repo for `cluster-mesh` and `mesh = true` in examples and demo - recipes. + Fix the mesh examples in `doc/bin/cli.md`, `doc/bin/relay/config.md`, and + `rs/moq-relay/README.md`, then search the repo for `cluster-mesh` and + `mesh = true` in any other examples and demo recipes. Public API: removes a relay config field and flag. Wire: relays stop announcing `.internal/origins`. ## Related -- [Cluster routing](/quest/m1/cluster-routing.md) - takes its topology from configured links only +- [Cluster routing](/quest/m1/cluster-routing/README.md) - takes its topology from configured links only diff --git a/quest/m0/request-caps.md b/quest/m0/request-caps.md index b469c58adc8..d0ee8679a20 100644 --- a/quest/m0/request-caps.md +++ b/quest/m0/request-caps.md @@ -34,3 +34,7 @@ Announces and subscriptions per session are capped as well. Public API: possibly caps on the session config; propose the shape in the PR. Wire: behaviour within the drafts' existing limits. No format change. + +## Required + +- [IETF FIN semantics](/quest/m0/ietf-fin-not-cancel.md) - MAX_REQUEST_ID refills as requests close, and that change decides when a request closes diff --git a/quest/m0/shared-fronts.md b/quest/m0/shared-fronts.md index f2594ad9fff..272681e48c3 100644 --- a/quest/m0/shared-fronts.md +++ b/quest/m0/shared-fronts.md @@ -30,4 +30,4 @@ Public API: none. Wire: none. - [Front deadlines](/quest/m1/front-deadline-index.md) - per-front cost per track - [Front parking](/quest/m1/origin-front-parks.md) - also changes what mints a front -- [Relay memory](/quest/m1/relay-memory.md) - per-announcement measurements +- [Wildcard](/quest/m0/wildcard/README.md) - its line rewrites `model/origin.rs` heavily (+401 lines, fronts end on a standing refusal); land after it or rebase onto it diff --git a/quest/m0/wildcard/README.md b/quest/m0/wildcard/README.md index 97be3a60c42..0b106cd870b 100644 --- a/quest/m0/wildcard/README.md +++ b/quest/m0/wildcard/README.md @@ -22,9 +22,9 @@ over FETCH wants to say "if nobody is publishing this live, I have it", which is the catch-all `**`, a claim about every path at once. The cost of enumerating is real even though its last measurement is stale. -[relay-memory](/quest/m1/relay-memory.md) measured one announcement at 8.8 KB -per relay plus 4.3 KB per additional route before prefix routes made a -standby route a table entry, and owns remeasuring it. Whatever the current +One announcement measured 8.8 KB per relay plus 4.3 KB per additional route +before prefix routes made a standby route a table entry; +[Cluster routing](/quest/m1/cluster-routing/README.md) owns remeasuring it. Whatever the current number, every relay that hears an announcement pays it whether or not anything there subscribes, so "workers times broadcasts" is that number multiplied across the fleet in resident memory. @@ -51,8 +51,8 @@ Route cost already names this case: "The original publisher seeds it with its production cost: zero for a live publish, something large for a standby that would have to start working (a cold transcoder)" (`drafts/draft-lcurley-moq-lite.md`). `moq_auth::Claims.publish` and -`origin::Producer` gain versioned patterns through -[Path patterns](/quest/m1/path-patterns.md), so tokens and filters reuse the +`origin::Producer` gained versioned patterns on the +[Auth](/quest/m1/auth/README.md) line, so tokens and filters reuse the same matcher; advertisements stay prefixes. `Cost { warm, cold }` (`rs/moq-net/src/model/origin.rs:426`) is the route cost since [#2925](https://github.com/moq-dev/moq/pull/2925). @@ -88,8 +88,8 @@ field. ### Decisions - **One prefix on the wire, one pattern in the token and the filter.** An - advertisement is a path prefix; the [path-patterns](/quest/m1/path-patterns.md) - dialect is what tokens and the consume-side filter use, matched by the + advertisement is a path prefix; the pattern dialect from the + [Auth](/quest/m1/auth/README.md) line is what tokens and the consume-side filter use, matched by the shared matcher, so nothing resembles a second grammar and nothing on the wire spells a wildcard. - **Longest prefix wins, and its refusal is final.** This is the rule @@ -140,7 +140,7 @@ field. refused. A prefix wider than the grant is accepted, but it only routes requests for paths the grant covers. Fleet-wide services use the cluster identity; a customer service serves only what its own v1 grant contains. - Until [Advertise-only authorization](/quest/m1/processor/advertise-auth.md) + Until [Advertise-only authorization](/quest/m2/processor/advertise-auth.md) lands, the publish scope stands in for advertising; a credential with its own advertise scope is checked against that instead. - **Claims are visible to subscribers.** A subscriber sees every advertised @@ -189,7 +189,7 @@ field. - **Patterns are independent of clustering.** The `moq-pattern` crate owns the matching semantics tokens and filters share, with no draft of its own; no announce message carries a pattern on either protocol (AUTH grants on - lite-06 do, per [Path patterns](/quest/m1/path-patterns.md)). moq-cluster adds hop + lite-06 do, per the [Auth](/quest/m1/auth/README.md) line). moq-cluster adds hop lists, costs, pool selection, and request resolution to prefix advertisements. @@ -206,7 +206,9 @@ never see `.pro/` broadcasts, which could confuse their business logic. Those versions cannot opt into hidden routes, so the relay never announces them there. Hidden routes are a moq-lite-07 feature, so the player's covering check (Demand, done on the line branch) opts into them and sees a claim only when -lite-07 is negotiated. A customer who wants transcodes upgrades, or +lite-07 is negotiated. Finalizing lite-07 is a rollout condition, not a +blocker for this line (decided in the 2026-09-30 audit), since the check works +whenever lite-07 is negotiated. A customer who wants transcodes upgrades, or subscribes to the explicit `.pro//...` path, which works on any version. Grants and metering are the deployment's; moq.pro's are in its [wildcard questline](https://github.com/moq-dev/moq.pro/blob/main/quest/m2/wildcard/README.md). @@ -219,13 +221,9 @@ distinguish recording generations reads the catalog's archive entry ## Related -- [path-patterns](/quest/m1/path-patterns.md) - owns the pattern dialect - and the shared matcher tokens and filters reuse - [archive](/quest/m1/archive/README.md) - an archive claims the root, and its catalog names the generations a claim cannot -- [Cluster routing](/quest/m1/cluster-routing.md) - origin selection by cost - with an HRW tie-break, built on this line's longest-prefix rule - [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - derived output mirrors the source path, `@` segment included -- [Announcement shapes](/quest/m3/announce-shapes.md) - moq-lite-only exact, +- [Announcement shapes](/quest/m2/announce-shapes.md) - moq-lite-only exact, suffix, and prefix+suffix claims that survive relay hops diff --git a/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md b/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md index 9f04697e6ce..0c36f01a0bd 100644 --- a/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md +++ b/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md @@ -1,44 +1,27 @@ -# [M] js/net: decode messages synchronously from buffered bytes +# [XS] js/net: cap the publisher's subscription controls ## Goal -The lite publisher applies every buffered control before it pops a group, -with no read-ahead queue: bounded memory and exact control-first ordering at -once. +A peer flooding `SUBSCRIBE_UPDATE` while the lite publisher is blocked in a +control-stream write cannot grow its memory without bound: past a fixed cap +the session fails with a protocol error. ## Plan -The serving loop must apply every buffered `SUBSCRIBE_UPDATE` before it pops a -group, or a group goes out under a range the peer already superseded. Rust gets -that from `poll_decode_maybe` in `rs/moq-net/src/lite/publisher.rs`, which -decodes straight out of the reader's buffer and so drains controls to -exhaustion in one poll. `js/net/src/lite/publisher.ts` works around -the async `Reader` by decoding ahead into `SubscriptionControls`, which the -loop drains synchronously. That queue is unbounded: it grows while the loop is -blocked in a control-stream write, so a peer flooding updates during a stalled -write converts flow-controlled bytes into heap objects. A single-message slot -was tried in #2820 and broke ordering, because `take()` cannot yield to the -decoder without letting a group pop slip in between. - -`Reader` in `js/net/src/stream.ts` already decodes synchronously: a decode is -a function over a `Cursor`, whose reads throw an internal short signal when the -buffered bytes run out. `tryDecode` returns undefined and consumes nothing in -that case, and `decode`/`decodeMaybe` are the one async driver that fills and -retries. The primitives (`u62`, `u53`, `read`, `string`, ...) are that driver -applied to the `Cursor` reads, and the group and FETCH frame loops drain every -buffered frame with `tryDecode` (`js/net/bench/frames.ts`). The 22 -`static async decode` message decoders under `js/net/src/lite/`, plus four -`decodeMaybe` variants, still await a primitive per field. - -- Convert all 26 decoders to a single synchronous body over a `Cursor`, with - the async form as `reader.decode(...)` rather than a second copy. `Message` - in `lite/message.ts` becomes a sync size-prefixed wrapper. -- The publisher drains controls synchronously in its loop and - `SubscriptionControls` goes away. -- Tests: the publisher applies N buffered updates before the next group - pop; a partial update with a group already ready waits for the second fill - and pops the group under the new range, so incomplete is never read as "no - control pending"; the flood case stays bounded. +`SubscriptionControls` in `js/net/src/lite/publisher.ts` (:169) decodes +ahead of the serving loop so every buffered update applies before the next +group pop. It keeps only the newest range for the loop, but the decoder runs +on its own and calls `apply` for each update, so a peer can turn +flow-controlled bytes into unbounded work and heap while the loop is stalled. +First confirm what still grows on the current code, then cap the updates +decoded between two drains by the loop and fail the session on overflow, +matching Rust's refusal of malformed input. Test: a flood during a stalled +write fails the session instead of growing. + +Decided in the 2026-09-30 audit: the rewrite to synchronous decoders is +dropped. Generated lite from the [rs2ts line](/quest/m1/rs2ts/README.md) +replaces hand-written js/net, and it gets control-first ordering from moq-net's +`poll_decode_maybe`. This quest only closes the memory hole until then. ## Closes diff --git a/quest/m1/2964-quic-workers-dropping-one-split-server-resizes-the.md b/quest/m1/2964-quic-workers-dropping-one-split-server-resizes-the.md deleted file mode 100644 index 891110d96d6..00000000000 --- a/quest/m1/2964-quic-workers-dropping-one-split-server-resizes-the.md +++ /dev/null @@ -1,35 +0,0 @@ -# [M] Integrate the hardened reuseport group with QUIC workers - -## Goal - -The owning tokio worker group uses `moq_sock::shard::Group`'s enforced -formation and socket-retention contract. Complete and retained socket groups -preserve connection-ID steering through partial startup and member teardown. - -## Plan - -The published `Workers::split` ownership change and functional group shutdown -have landed. Do not repeat -that API redesign here. This follow-up replaces the worker's private lifetime -bookkeeping with the hardened socket-group primitive. - -Adopt moq-sock's claims and complete-group ownership. No member serves before -the final bind and filter attachment, and every socket stays owned until -serving has stopped for the group. Preserve the dev owner, shutdown, failure -propagation, and worker-local builder contract without another published -signature change. - -Use Linux runtime regressions to exercise incomplete startup, a failed final -bind, dropping an unused server handle, and a serving member completing or -failing. Check the socket group and connection-ID steering on a surviving -session while unused handles are dropped, and prove all serving stops when -the group terminates. Wire the tests into normal or nightly CI. - -Public API: no further `moq-tokio` ownership change. The hardened group -already exists (`Group::bind` and `Group::complete` over `Claim` in -`rs/moq-sock/src/shard.rs`). Wire: no format change. Close #2964 only when -both the dev ownership proof and this integration are complete. - -## Closes - -- [#2964](https://github.com/moq-dev/moq/issues/2964) - close this issue when the quest finishes diff --git a/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md b/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md index 53691398992..886144d2d0e 100644 --- a/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md +++ b/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md @@ -86,3 +86,8 @@ the closed producer's cache or terminal state. ## Closes - [#2991](https://github.com/moq-dev/moq/issues/2991) - close this issue when the quest finishes + +## Related + +- [Resume latest](/quest/m1/resume-latest.md) - edits `resume.rs` and its takeover tests (#4491) +- [Parked reads wake](/quest/m1/parked-read-wakes.md) - edits the same `resume.rs` wakeups diff --git a/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md b/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md index 0df856a18a3..b12adcc5407 100644 --- a/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md +++ b/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md @@ -1,37 +1,36 @@ -# [M] GStreamer preserves the broadcast PTS-to-wall clock +# [S] GStreamer picks the broadcast wall epoch ## Goal -`moqsink` maps every media pad onto one continuous broadcast clock, exposing -its fixed wall epoch through the shared Hang contract. Source restarts never -change the interpretation of media already published. +`moqsink` exposes one fixed wall epoch for the broadcast through the shared +Hang clock contract, so every pad's timestamps relate to UTC the same way. ## Plan -Use the current broadcast-wide segment timeline and clock contract, not the -old per-rendition timeline or removed `set_wall` method. Map the buffer PTS -through its TIME segment into the broadcast's running-time domain before -publication, preserving valid within-group B-frame reordering. - -Choose the wall epoch once. Prefer GstReferenceTimestampMeta only when it -names a recognized absolute clock domain; otherwise relate the pipeline clock, -base time, running time, and local SystemTime. Account for the mapped PTS when -computing PTS zero. An unidentified reference clock is not UTC. Every pad uses -the same mapping rather than independently sampling a new epoch. - -Keep that mapping through flushes, encoder restarts, and source PTS resets. -Translate a restarted source forward on the existing clock, including idle -gaps; refuse a source that cannot be mapped consistently. Discontinuity -markers never change wall or retime retained records. Do not add per-record -anchors or define a GStreamer-specific catalog shape. - -Test recognized reference metadata, deterministic local-clock fallback, -delayed first buffers, multiple pads, timescale conversion, numeric limits, -source restarts, idle gaps, and a system-clock adjustment. Existing timeline -records remain unchanged. Consume the prerequisite's catalog format; no new -transport TIMESTAMP/TIMESCALE semantics, synchronization protocol, or drift -correction is introduced here. Run the GStreamer CI and `interop --all` lanes. +The PTS mapping already exists: `rs/moq-gst/src/sink/pad.rs` maps each +buffer PTS through its TIME segment into the shared running-time domain +(`rs/moq-gst/src/sink/timeline.rs`), and #4480 made rewinds drop frames. Only +the wall-epoch choice remains. + +Choose the wall epoch once per broadcast. Prefer GstReferenceTimestampMeta +only when it names a recognized absolute clock domain; otherwise relate the +pipeline clock, base time, running time, and local SystemTime. An unidentified +reference clock is not UTC. Every pad uses the same epoch rather than sampling +its own. Do not define a GStreamer-specific catalog shape. + +Decided in the 2026-09-30 audit: a restart is a new broadcast epoch, not a +forward re-anchor on the old clock (per remove-live and +[GStreamer and OBS](/quest/m1/broadcast-epoch/gst-obs.md)), and +[#3115](/quest/m2/3115-moqsink-the-publication-has-no-generation-so-a-flush.md) +handles the sink side. + +Test recognized reference metadata, the deterministic local-clock fallback, +delayed first buffers, and multiple pads sharing one epoch. ## Closes - [#3021](https://github.com/moq-dev/moq/issues/3021) - close this issue when the quest finishes + +## Related + +- [GStreamer and OBS](/quest/m1/broadcast-epoch/gst-obs.md) - a restarted pipeline publishes a new epoch diff --git a/quest/m1/README.md b/quest/m1/README.md index 246d1b26c8a..5be428fc5a8 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -15,46 +15,46 @@ Give one agent ownership of each shared code area at a time (origin/auth, the JS Reader, audio playback, media containers and archive, bindings, worker transport, benchmark tooling); worktrees isolate commits, not semantics. +A line with no named consumer waits in m2 until one appears. The 2026-09-30 +audit moved P2P, one-port, ladder, processor, timed metadata, the installer, +the OBS GPU paths, the IETF half of rs2ts, and the unmeasured io_uring and +QUIC studies there on that rule. + ## Required -- [Cluster routing](/quest/m1/cluster-routing.md) - an announcement says where a broadcast originates, not how to reach it, and a relay hears only the prefixes its clients asked for +- [Cluster routing](/quest/m1/cluster-routing/README.md) - an announcement says where a broadcast originates, not how to reach it, and a relay hears only the prefixes its clients asked for - [Track tail interop](/quest/m1/track-tail-interop.md) - a Rust publisher ending a track with a group in flight is read to its end by the JS subscriber, and the reverse, in `just test interop` +- [Merge queue](/quest/m1/merge-queue.md) - the required checks run on `merge_group`, so a stale green check can no longer break main - [Binding audio delay](/quest/m1/binding-surface.md) - moq-ffi and every wrapper configure and observe audio playout delay - [FFI shape](/quest/m1/ffi-shape/README.md) - the bindings mirror Rust's layers: net at the root, then media, json, flate, audio, and video namespaces built from the handle below -- [Track demand](/quest/m1/track-demand.md) - Rust and JS watch a track's subscribers through `demand()` alone -- [Session close](/quest/m1/session-close.md) - a graceful session end withdraws announces and waits one second for the ack -- [Graceful close in bindings](/quest/m1/bindings-graceful-close.md) - on dev, `shutdown` drains a session in moq-ffi and every wrapper like Rust, so the wrappers keep the tail of a publish -- [Close codes](/quest/m1/close-codes.md) - a client sees the peer's application close code over WebSocket and raw QUIC, like WebTransport - [Raw stream codes](/quest/m1/raw-stream-codes.md) - raw QUIC stream resets and stops carry the application's code, not an HTTP/3-mapped one +- [IETF drain before close](/quest/m1/ietf-drain-before-close.md) - moq-transport sessions deliver finished tracks before a graceful close, as moq-lite does +- [Demo serve-hls renditions](/quest/m1/serve-hls-renditions.md) - `just pub serve-hls` serves 720p and 144p instead of two 256-wide copies +- [moq play drain tail](/quest/m1/play-drain-tail.md) - retired renditions and finite tracks play their last 10 ms of audio - [WebTransport close upstream](/quest/m1/wt-close-upstream.md) - web-transport-moq delivers the close capsule itself, and moq-tokio's `CLOSE_LINGER` is deleted - [Browser close code](/quest/m1/browser-close-code.md) - a playwright case proves the page reads a relay's close code and reason, on every web-transport backend -- [Watch refusal](/quest/m1/watch-refusal.md) - `` shows an origin refusal as an error instead of sitting offline - [Resumed groups](/quest/m1/resume-latest.md) - a half-delivered group ends once the new copy is past it, so a group-only reader never parks after a mid-group failover - [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 - [Parked reads wake](/quest/m1/parked-read-wakes.md) - a read parked on an evicted or aborted group wakes and re-judges, for resume successors and plain tracks alike - [Reader end parity](/quest/m1/reader-end-parity.md) - JS readers see a track's end once the newest group reaches the declared end, as Rust readers do - [Cross-relay bursts](/quest/m1/cross-relay-bursts.md) - bursty small-group tracks cross two relays without lost groups, unanswered FETCHes, or stalls - [Request stream cancel](/quest/m1/request-stream-serve.md) - a lite publisher stops resolving a SUBSCRIBE or FETCH once the requester FINs or resets, through one wrapper that owns every request stream's reader -- [JS closed-track leak](/quest/m1/js-closed-track-leak.md) - on dev, a subscriber that joins a closed JS track with unlimited retention is released instead of cached forever - [Session death parity](/quest/m1/session-death.md) - a local close ends tracks cleanly in both languages, and JS group readers see the session's error on session death - [Watch and publish under CSP](/quest/m1/csp-assets.md) - blob workers stay the default; strict-CSP apps host the files and set a base URL -- [More tests under load](/quest/m1/test-flakes-2.md) - the second round of load-only failures, fixed at the cause +- [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 - [CI runner stalls](/quest/m1/ci-runner-stalls.md) - the 0.4 to 0.8 s freezes of both interop tracks on CI are attributed from a week of nightlies and fixed or told apart from playback bugs - [Catalog estimate rate](/quest/m1/catalog-estimate-rate.md) - a rising `jitter`/`delay` estimate republishes the catalog at most once a second, in js/publish and moq-mux - [Legacy end overshoot](/quest/m1/legacy-end-overshoot.md) - browser playback survives a group that starts inside the previous group's estimated end -- [UnknownSession log flood](/quest/m1/unknown-session-logs.md) - streams reset before their WebTransport header stop being reported as UnknownSession at WARN -- [Merge queue](/quest/m1/merge-queue.md) - the required checks run on `merge_group`, so a stale green check can no longer break main - [Wire compatibility](/quest/m1/wire-compat.md) - a nightly run tests this checkout against the last published release for tokens, session wire, and catalog/container - [TS import shared shift](/quest/m1/ts-import-shared-shift.md) - unflagged loop wraps move audio and video by one shift, so A/V sync holds across wraps - [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) - `import ts` reads a PAT or PMT that spans packets or follows a nonzero pointer_field instead of aborting, and one corrupted section costs a repetition and a counted `CRC_error`, not the import +- [RTMP interleaving](/quest/m1/rtmp-interleaving.md) - isolate partial messages before optimizing assembly copies - [TS stats module](/quest/m1/ts-stats-module.md) - on dev, the TS stats types move under `ts::stats` as `Snapshot` and `Stream`, with an owned `track` - [Same-hop importers](/quest/m1/hop-aligned-import.md) - importers sharing a `--hop` and fed one stream publish identical groups and timestamps, so failover survives -- [Capture control](/quest/m1/capture-control.md) - on dev, `encode::Capture` replaces `CaptureOptions` without a `clock` field (it reads the catalog's), an unsupported `cut()` errors, and dropping the last `Control` cancels in-flight opens +- [Audio capture without ALSA link](/quest/m1/capture-alsa-link.md) - moq-audio capture and playback build on Linux without linking libasound - [Capture by default](/quest/m1/capture-default.md) - moq-video and moq-audio build `capture` by default, so pre-merge checks test it and the capture gate goes away -- [Video surface](/quest/m1/video-surface.md) - on dev, moq-ffi's `native` becomes `surface`, refused on platforms with no surface -- [HLS discontinuity sequence](/quest/m1/hls-discontinuity-sequence.md) - on dev, `Segment::discontinuity` is the absolute sequence, so every cursor agrees +- [Ship capture and playback](/quest/m1/cli-packaging.md) - a released moq binary can capture and play, which no distribution currently enables - [Auth client CA](/quest/m1/relay-auth-client-ca.md) - on dev, `auth::Config::validate` and `init` take the client-CA flag, so no caller can skip the check -- [Remove live()](/quest/m1/remove-live.md) - on dev, importers publish stream timestamps verbatim, the catalog clock maps them to wall time, and an encoder restart becomes a new epoch - [Data track clock](/quest/m1/data-track-clock.md) - JSON and binary data tracks stamp on the catalog's clock at write time, matching the media's anchored clock - [Go and Dart doc samples](/quest/m1/doc-samples-go-dart.md) - Go and Dart doc samples compile against their wrappers - [Data capture in bindings](/quest/m1/data-capture-bindings.md) - moq-ffi and every wrapper pass a data frame's capture time, and the JSON window producer takes one @@ -65,10 +65,8 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [JavaScript FETCH](/quest/m1/js-fetch.md) - generic on-demand group serving and IETF FETCH for browser publishers - [Archive](/quest/m1/archive/README.md) - record selected tracks to any object_store and replay them over FETCH or derived HLS; the catalog entry and format may break in place, since no archives exist - [Tooling](/quest/m1/tooling/README.md) - justfiles become a one-line menu over `sh/`, one impact map scopes CI, and every workflow step runs a recipe -- [Path patterns](/quest/m1/path-patterns.md) - one matcher for every predicate over broadcast paths: tokens, origins, interest - [In-band auth](/quest/m1/auth/README.md) - a session tells its peer what it may publish and subscribe to, unions tokens presented in band, and fails loud on an out-of-scope publish - [Dropped sources](/quest/m1/dropped-sources.md) - track consumers see the producer's real error on every end path, never `Dropped` -- [Shaper virtual time](/quest/m1/shaper-virtual-time.md) - `moq-shaper` tests judge seeded decisions on paused time, not on wall-clock delivery under load - [C++ through moq-ffi](/quest/m1/cpp/README.md) - generated C++ over moq-ffi with futures and expected-style errors, shipped as a tarball, vcpkg, and Conan, and adopted by the OBS plugin - [Generated C bindings](/quest/m1/c/README.md) - C generated from moq-ffi ships as `moq-c` 0.8.0 and replaces the hand-written libmoq - [OBS native codecs](/quest/m1/obs-moq-video/README.md) - replace FFmpeg video and audio decoding with moq-video and moq-audio, deliver GPU frames, and use native audio/video encoders @@ -80,6 +78,7 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [JS rendition ranking](/quest/m1/js-ranked.md) - `@moq/hang` ranks video renditions like Rust, and `@moq/watch`'s fallback uses it - [Audio rendition pick](/quest/m1/audio-ranked.md) - single-track FLV/RTMP and WHEP serve the best audio rendition, not the first by name - [FLV catalog stream](/quest/m1/flv-catalog-stream.md) - on dev, `flv::Export` takes a catalog stream like fmp4, replacing `with_select` +- [io_uring flow control](/quest/m1/uring-flow-control-windows.md) - the relay's io_uring workers honor the QUIC flow-control windows instead of refusing them - [Own the QUIC stack](/quest/m1/quic/README.md) - the moq-noq fork carries ACK progress, reliable reset, hierarchical scheduling, deadlines, peer limits, and qmux - [QoS](/quest/m1/qos/README.md) - broadcast health: relay starvation and timeliness histograms, on dev - [Catalog track alias](/quest/m1/catalog-track-alias.md) - catalog rendition keys become aliases with an optional `track` name, so one catalog lists renditions from several broadcasts @@ -87,62 +86,44 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Drain](/quest/m1/drain/README.md) - relay restarts drain sessions over GOAWAY instead of hard-dropping them - [Strict Redirect::resolve](/quest/m1/redirect-resolve.md) - on dev, `Redirect::resolve` can no longer quietly turn a refused redirect into a redial - [Transport upgrade](/quest/m1/transport-upgrade/README.md) - a session that came up over WebSocket moves to QUIC once the QUIC dial lands, handing over at a group boundary -- [P2P](/quest/m1/p2p/README.md) - opted-in clients serve each other over data channels and iroh while the relay stays the rendezvous and the fallback, under application policy -- [One port](/quest/m1/one-port/README.md) - a relay speaks QUIC, STUN, WebRTC media, and SRT on one UDP port and HTTP, RTMP, and RTMPS on one TCP port -- [Signed priority](/quest/m1/signed-priority.md) - on dev, every API priority is an `i8` with 0 as the unset midpoint, and hang's built-ins sit above it - [Scope track priority](/quest/m1/track-priority-scope.md) - priority orders one owner's streams, and a shared cluster session is fair across tenants -- [Stream sessions](/quest/m1/uring-tcp/README.md) - serve WebSocket and HTTP from the io_uring workers, where io_uring pays off most - [IETF on the ring](/quest/m1/uring-ietf.md) - the io_uring workers serve moq-transport sessions too, so a uring relay drops no client protocol - [BBR ACK cleanup](/quest/m1/bbr-ack-cleanup.md) - packet bookkeeping scales with completed entries instead of scanning the flight on every ACK - [Perf](/quest/m1/perf/README.md) - eliminate measured hot-path costs across moq-uring, kio, and the moq-net model - [#2924](/quest/m1/2924-moq-relay-tls-rotation-is-not-atomic-across-thread-per.md) - every listener on both runtimes shares one reloadable served identity, so rotation is atomic and generate works with workers -- [#2964](/quest/m1/2964-quic-workers-dropping-one-split-server-resizes-the.md) - integrate the dev worker owner with hardened socket-group formation - [Benchmark regressions in CI](/quest/m1/bench-ci.md) - PRs get a non-blocking comparison of the Criterion benches they affect, and a nightly trend on main alerts on regressions - [Benchmark comparisons](/quest/m1/performance-comparisons.md) - retained evidence, repeated paired runs, and uncertainty for performance claims - [#3126](/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md) - moq-bench reports per-interval latency percentiles so the ramp leaves the steady state - [Relay session bench](/quest/m1/bench-relay.md) - the same scenario through moq-relay's own connection handling -- [Bench coverage](/quest/m1/bench-coverage.md) - Criterion targets for moq-mux containers, the hang catalog, moq-auth verification, and moq-pattern matching -- [Stats producer bench](/quest/m1/stats-producer-bench.md) - the stats drain and encode cost per tick, swept over held paths and tiers and run nightly - [Relay profiling](/quest/m1/performance-profiles.md) - reproducible CPU and allocation captures under the existing workloads - [Browser benchmarks](/quest/m1/browser-benchmarks.md) - measure JS transport, container, decode, and render costs in an identified browser - [Generated @moq/net](/quest/m1/rs2ts/README.md) - the browser runs moq-net as TypeScript generated from the Rust source, retiring js/net's hand-written protocol and model code - [Plan: watch worker](/quest/m1/plan-watch-worker.md) - prototype an invisible page worker against app-spawned workers, and land the jank harness that decides - [Watch worker](/quest/m1/watch-worker.md) - watch playback runs in a worker onto an OffscreenCanvas, so main-thread jank never stalls video or audio -- [Closure counters](/quest/m1/closure-counters.md) - a departed node's return never regresses the closure counters a consumer already saw -- [RTMP interleaving](/quest/m1/rtmp-interleaving.md) - isolate partial messages before optimizing assembly copies - [Cache expiry growth](/quest/m1/cache-expiry-growth.md) - with the default pool, relay memory plateaus at the expiry window on every version - [Plan: cache age-out](/quest/m1/cache-wall-eviction.md) - a swept benchmark decides whether the track cache ages groups out on wall time without a write - [Frame slot charge](/quest/m1/frame-slot-charge.md) - a group's frame slots past the first four count against the cache pool, including capacity a released group keeps -- [Relay memory](/quest/m1/relay-memory.md) - remeasure what an announcement costs after prefix routes - [Front deadlines](/quest/m1/front-deadline-index.md) - a front's per-event cost stops growing with its track count: an expiry index and per-track wakes, proven by a churn benchmark - [Front parking](/quest/m1/origin-front-parks.md) - an unroutable request waits on a front instead of re-asking on every route-table move - [Publish channel count](/quest/m1/publish-audio-channel-count.md) - forcing a channel count on an Audio.Capture stops costing the subscriber gaps of silence - [JS abandonment](/quest/m1/js-subscribe-abandonment.md) - a viewer returning during IETF subscribe setup keeps its track across microtasks -- [IETF stream types](/quest/m1/ietf-uni-stream-types.md) - padding streams are discarded stream-only and an unknown uni type closes the session, per draft-21 - [Epoch primitive](/quest/m1/epoch.md) - one `Epoch` type in moq-net and @moq/net, carried as a trailing `@` path segment, shared by e2ee and broadcast epochs - [E2EE](/quest/m1/e2ee/README.md) - TypeScript and Rust peers interoperate over encrypted broadcasts no relay can decrypt - [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - each publish of a name gets a fresh `@` epoch, viewers follow the newest live one at once, and bare names still resolve on every version -- [Processor](/quest/m1/processor/README.md) - a customer-run worker publishes an on-demand contribution under its own service prefix with scoped access - [#3056](/quest/m1/3056-watch-video-decoder-captures-the-rewind-generation-at.md) - watch: the video decoder resets on a declared discontinuity - [#933](/quest/m1/933-video-rotation-metadata-not-propagated-from-mobile-camera.md) - the catalog rotation follows the live camera's orientation - [#2848](/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - the Opus producer follows its bandwidth grant through the settled `moq_mux::rate::Control` -- [Ladder](/quest/m1/ladder/README.md) - a transcode ladder adapts to the uplink it publishes over, instead of encoding every live rung at its ceiling - [Time stretch](/quest/m1/watch-audio-time-stretch.md) - js/watch: the audio ring converges by time-stretching instead of skipping or going silent +- [A/V clock](/quest/m1/av-clock.md) - the audio playhead drives Sync.reference while audio plays, through per-track sync handles - [Native audio quality](/quest/m1/audio-quality-native.md) - the browser lane's profiles, budgets, and metric schema run against `moq play` on a dummy device -- [fMP4 emsg](/quest/m1/emsg.md) - event messages survive fMP4 import, and the timed-metadata contract ID3, SCTE-35, and FLV script tags share is settled with them -- [#2279](/quest/m1/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md) - hang: SCTE-35 cues arrive immediately on an independent metadata track, optionally associated with a rendition - [Caption import](/quest/m1/captions-import.md) - fMP4 and MKV subtitle tracks import as text renditions instead of erroring or being dropped - [MSF caption roles](/quest/m1/captions-msf.md) - an MSF caption, subtitle, or sign-language track survives conversion to a hang catalog -- [CEA-608/708](/quest/m1/captions-cea.md) - captions carried inside video SEI become a real text rendition at import -- [Colour model](/quest/m1/color-model.md) - the catalog describes a rendition's colour and HDR properties instead of leaving a TODO +- [Encoder colour](/quest/m1/color-model.md) - every moq-video encode path signals the colour its output actually has, or refuses instead of mislabelling - [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - a viewer joining at a recovery point drops the leading pictures it cannot decode; continuous viewers keep them - [Catalog warmup](/quest/m1/catalog-warmup.md) - `warmup` on video and audio renditions, in the catalog and the draft - [Audio warmup](/quest/m1/audio-warmup.md) - a viewer joining an Opus rendition mid-stream never hears the unconverged first 80 ms -- [#3021](/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md) - GStreamer maps every pad onto one continuous broadcast clock across source restarts +- [#3021](/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md) - moq-gst picks the broadcast wall epoch; a restarted source is a new epoch, not a forward re-anchor - [TS byte schedule](/quest/m1/ts-export-byte-schedule.md) - moq export ts places PCRs and padding on the byte grid `mpegts.muxRate` implies, so a receiver can clock off arrival -- [Text availability](/quest/m1/text-schema.md) - a text track publishes its own coverage index instead of copying the media timeline -- [ID3 catalog section](/quest/m1/id3.md) - timed ID3 as a first-class container-neutral catalog section -- [FLV script tags](/quest/m1/flv-script.md) - onMetaData and AMF data messages survive RTMP and FLV import - [Release profile](/quest/m1/release-profile.md) - every release build gets fat LTO, one codegen unit, and stripping from the workspace profile instead of three script exports - [Size report](/quest/m1/size-report.md) - a nightly job reports every shipped artifact's size, native and JS, and alerts when one grows - [Publish lazy file source](/quest/m1/publish-lazy-file.md) - a camera or screen `` stops downloading mediabunny's ~99 KB gzip @@ -151,17 +132,11 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [Bindings size profile](/quest/m1/ffi-size-profile.md) - a benchmark decides whether the moq-ffi builds ship at opt-level "s", which halves the dylib - [Go mirror delivery](/quest/m1/go-mirror-delivery.md) - the Go binding's staticlibs stop growing git history by ~210 MiB per release - [Relay iroh opt-in](/quest/m1/relay-iroh-opt-in.md) - moq-relay drops iroh from its defaults and shipped builds, while moq-cli keeps it for P2P +- [Rust owns mobile codecs](/quest/m1/mobile-ownership.md) - the settled verdict (Rust codecs, CVPixelBuffer bridge) is written where binding work reads it - [Dart on iOS](/quest/m1/dart-ios.md) - prove the shipped iOS native asset actually loads on a device, which no CI can - [Kotlin JVM exit](/quest/m1/kt-jvm-exit.md) - a Kotlin/JVM program exits cleanly whatever the moq-ffi runtime thread is doing, like Python does since #3766 - [Dart publish](/quest/m1/dart-publish.md) - the packages are built and dry-run clean but exist nowhere consumers can install from - [Dart codec parity](/quest/m1/dart-codecs.md) - Dart is the one binding that cannot originate media -- [#2850](/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md) - js/net: decode messages synchronously from buffered bytes and delete the publisher read-ahead queue -- [Install moq](/quest/m1/moq-installer.md) - one command installs or upgrades the released CLI on macOS and Linux -- [Install URL](/quest/m1/moq-install-url.md) - moq.dev serves the canonical installer at /install.sh -- [`moq relay`](/quest/m1/moq-relay-subcommand.md) - the relay runs under a `moq` verb with its own flags and TOML, while `moq-relay` stays a minimal binary +- [#2850](/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md) - js/net caps the publisher's subscription controls so a flood cannot grow memory without bound - [`moq --listen` admission](/quest/m1/cli-serve.md) - a listening CLI session is authenticated, scoped, counted, and drained like a relay's instead of accepting everything - [#709](/quest/m1/709-automatic-letsencrypt-support.md) - the relay provisions and renews its own ACME certificate through rustls-acme over TLS-ALPN-01, persisted on disk -- [Audio capture without ALSA link](/quest/m1/capture-alsa-link.md) - moq-audio capture and playback build on Linux without linking libasound -- [Ship capture and playback](/quest/m1/cli-packaging.md) - a released moq binary can capture and play, which no distribution currently enables -- [io_uring flow control](/quest/m1/uring-flow-control-windows.md) - the relay's io_uring workers honor the QUIC flow-control windows instead of refusing them -- [Remove effect.cancel](/quest/m1/effect-cancel.md) - `@moq/signals` drops the deprecated `Effect.cancel` on dev diff --git a/quest/m1/archive/README.md b/quest/m1/archive/README.md index dd334aa40b5..28cf3ecec7e 100644 --- a/quest/m1/archive/README.md +++ b/quest/m1/archive/README.md @@ -114,9 +114,7 @@ owned by that prerequisite, not duplicated in archive storage. - [Recording writer](/quest/m1/archive/writer.md) - feed the segmenter from a `broadcast::Consumer`, store each segment, then commit its record - [Recording reader](/quest/m1/archive/reader.md) - serve archived FETCH through a supplied `broadcast::Producer` -- [Paced replay](/quest/m1/archive/paced-replay.md) - a replay pushes its groups to live subscribers on one shared clock, so any live player plays it - [Replay provenance](/quest/m1/archive/provenance.md) - a replay's catalog names its timeline, replay path, store URL, and format version -- [Browser archive](/quest/m1/archive/browser.md) - the same contract for browser-published broadcasts - [Offline archive HLS](/quest/m1/archive/hls.md) - render playlists from the archive timeline and fetch segment media lazily - [DVR rewind](/quest/m1/archive/dvr.md) - seek through a bounded archive and return to live playback - [Enrollment flake](/quest/m1/archive/enrollment-flake.md) - the opening-snapshot test waits for real enrollment, not the `.info` file diff --git a/quest/m1/archive/enrollment-flake.md b/quest/m1/archive/enrollment-flake.md index 43950247033..f8a02346e09 100644 --- a/quest/m1/archive/enrollment-flake.md +++ b/quest/m1/archive/enrollment-flake.md @@ -22,5 +22,5 @@ Public API: none. Wire: none. ## Related -- [More tests hold up under load](/quest/m1/test-flakes-2.md) - the same +- [More tests hold up under load](/quest/m1/test-flakes-2/README.md) - the same round of load-only failures on `main` diff --git a/quest/m1/archive/writer.md b/quest/m1/archive/writer.md index 16eb74108d2..3a1329e1f74 100644 --- a/quest/m1/archive/writer.md +++ b/quest/m1/archive/writer.md @@ -70,6 +70,14 @@ Wait the deletion grace period from successful recovery, then delete unreference left by interrupted expiration or uploads. Failed or incomplete recovery must prevent deletion. Preserve `.info` and timeline checkpoint objects. +On resume, fail loud on a track that goes backward. The resume step already +refuses a group ID at or below the recovered track's last one; also refuse a +first group whose timestamp is before the recovered track's last recorded +timestamp, instead of writing overlapping media time. The caller starts a new +prefix. Test a backward and a forward restart. Decided in the 2026-09-30 +audit: folded in from a separate quest, and the archive format may break in +place since it is unreleased. + Keep archive policy out of protocol libraries. As the native application that owns its storage and track choices, `moq-cli` attaches the writer to every import path and enrolls the resulting `broadcast::Consumer` tracks. Downstream diff --git a/quest/m1/audio-codecs/README.md b/quest/m1/audio-codecs/README.md index e6051c995d2..e9c3cf198bc 100644 --- a/quest/m1/audio-codecs/README.md +++ b/quest/m1/audio-codecs/README.md @@ -62,7 +62,6 @@ ready now. ## Related - [OBS native codecs](/quest/m1/obs-moq-video/README.md) - the OBS source and encoder adapters consume this through moq-ffi; #3498 narrowed OBS to what moq-audio decodes today -- [Runtime QA hosts](/quest/m2/runtime-qa-hosts.md) - Windows and Android verification needs a host; the Windows and macOS CI gates only compile - [Dart codec parity](/quest/m1/dart-codecs.md) - Dart gains these once it builds with the `audio` feature - [Media Foundation decode](/quest/m2/audio-decode-mediafoundation.md) - Windows decodes HE-AAC, multichannel AAC, and what else the MFTs offer - [Media Foundation encode](/quest/m2/audio-encode-mediafoundation.md) - Windows encodes AAC-LC diff --git a/quest/m1/auth/README.md b/quest/m1/auth/README.md index ab481d45580..df7c411cabb 100644 --- a/quest/m1/auth/README.md +++ b/quest/m1/auth/README.md @@ -47,8 +47,8 @@ Decisions settled while planning, recorded so review does not relitigate them: root, and every token in a union shares the connection's root. Unscoped permission is `**`; an empty union grants nothing. Legacy AUTH wire codecs explicitly convert representable prefix unions, where `[""]` means all, - and refuse patterns they cannot represent. [Pattern interest](/quest/m1/path-patterns.md) - upgrades AUTH and ANNOUNCE_REQUEST wire fields together without changing + and refuse patterns they cannot represent. Pattern interest (#4277, on this + line) upgrades AUTH and ANNOUNCE_REQUEST wire fields together without changing the public pattern-valued grant type. - **Fail loud by aborting the session.** A publisher whose origin announces a broadcast outside the union aborts the session with `Unauthorized`, naming @@ -111,7 +111,7 @@ existing lite-06 ALPN. - [Expired token error](/quest/m1/auth/expired-error.md) - an expired token reports `Error::Expired`, not `Unauthorized`, in Rust, JS, and the bindings - [Bindings](/quest/m1/auth/bindings.md) - grants and tokens reach every - binding through moq-ffi and libmoq + binding through moq-ffi - [Token in band](/quest/m1/auth/token-in-band.md) - the credential can leave the URL: a session starts on what the URL carried and its AUTH streams add the rest, with the URL kept for peers below lite-06 @@ -120,7 +120,6 @@ existing lite-06 ALPN. ## Related -- [Pattern interest](/quest/m1/path-patterns.md) - moves AUTH's legacy grant prefixes to patterns; ANNOUNCE_REQUEST stays a prefix -- [Expiring media grants](/quest/m1/processor/grant-lease.md) - a worker's +- [Expiring media grants](/quest/m2/processor/grant-lease.md) - a worker's lease renewal is a new in-band token -- [P2P](/quest/m1/p2p/README.md) - the first consumer of hop-bound peer grants +- [P2P](/quest/m2/p2p/README.md) - the first consumer of hop-bound peer grants diff --git a/quest/m1/auth/bindings.md b/quest/m1/auth/bindings.md index 6bd1a36ab27..c46c2540c8b 100644 --- a/quest/m1/auth/bindings.md +++ b/quest/m1/auth/bindings.md @@ -2,43 +2,44 @@ ## Goal -Every binding can read a session's grant and present more tokens: moq-ffi and -libmoq expose it, and the hand-written Python, Swift, Kotlin, Go, and Dart -wrappers and their docs carry it. An OBS user whose token is about to expire -mid-stream can be handed a new one without the plugin reconnecting. +Every binding can read a session's grant and present more tokens: moq-ffi +exposes it, the generated C and C++ bindings pick it up from moq-ffi, and the +hand-written Python, Swift, Kotlin, Go, and Dart wrappers and their docs carry +it. An OBS user whose token is about to expire mid-stream can be handed a new +one without the plugin reconnecting. ## Plan - `MoqSession` in `rs/moq-ffi/src/session.rs` gains `auth()` returning an `Arc` object, the shape `publisher()` uses, with `grant() -> - Option` (a record: publish prefixes, subscribe prefixes, expiry as - a duration) for the union, `async grant_changed() -> MoqGrant` so a caller + Option` (a record: publish patterns, subscribe patterns, expiry + as a duration, matching `auth::Grant`) for the union, `async grant_changed() -> MoqGrant` so a caller can await the next change without polling, and `async add(token: String) -> Arc` whose object carries that token's own `grant()` and `closed()` and whose release withdraws it, raising the structured error moq-ffi already maps on refusal. `MoqClient` sessions reached through the reconnecting connection use the accessor [Relay tokens](/quest/m1/auth/relay-refresh.md) adds. -- libmoq: `moq_session_auth_grant`, `moq_session_auth_add`, and - `moq_auth_token_close` with the terminal-status callback contract the other - async calls use, in `rs/libmoq/src/api.rs` and the session table; - regenerate `moq.h`, and update `cpp/obs/src` only if the plugin surfaces a - token field, otherwise leave it. -- Interop: the Python, Go, and C interop clients print their grant and join +- No new libmoq API: the hand-written C ABI gets no more feature work. The + generated C and C++ bindings get this from moq-ffi, and OBS reaches it + through [C++ through moq-ffi](/quest/m1/cpp/README.md); update `cpp/obs/src` + only if the plugin surfaces a token field. +- Interop: the Python, Go, and C++ interop clients print their grant and join the assertion [Interop grants](/quest/m1/auth/interop.md) adds for Rust and JS. - Wrappers: `py/moq-rs/moq/session.py`, `swift/Sources/Moq`, `kt/.../Flows.kt` (a `Flow` over `grant_changed`), `go/wrapper/moq/session.go` (context-cancellable like the rest), and `dart/moq/lib/moq.dart`. Kotlin typealiases pick up the raw methods for free; the flow is the idiomatic add. -- Docs: `doc/lib/{py,swift,kt,go,dart,c}` each gain a short auth section, and +- Docs: `doc/lib/{py,swift,kt,go,dart}` each gain a short auth section, and `doc/lib/rs` documents `Session::auth()`. - Tests: each wrapper's existing session test reads a grant from a local relay, adds a second token minted by `moq auth`, sees the union grow, and releases it; the refusal path surfaces the structured error in each language. -Additive. +Additive. Decided in the 2026-09-30 audit: libmoq is frozen, so the C +surface comes from moq-ffi rather than new `moq_session_auth_*` calls. ## Required diff --git a/quest/m1/auth/lite.md b/quest/m1/auth/lite.md index 6d54e56217e..2c5eb5add95 100644 --- a/quest/m1/auth/lite.md +++ b/quest/m1/auth/lite.md @@ -144,8 +144,3 @@ app-added token does not suspend the check; a reset AUTH stream reports cross-language harness. On main, additive. - -## Related - -- [Pattern interest](/quest/m1/path-patterns.md) - moves AUTH's grant - prefixes to patterns; ANNOUNCE_REQUEST stays a prefix diff --git a/quest/m1/auth/peer-grant.md b/quest/m1/auth/peer-grant.md index 7a839443d82..bdf539b257d 100644 --- a/quest/m1/auth/peer-grant.md +++ b/quest/m1/auth/peer-grant.md @@ -46,7 +46,7 @@ serves only the granted paths. A missing, expired, HMAC-signed, or unproven grant is not a grant. P2P is the first consumer: -[Signaling and policy](/quest/m1/p2p/signal.md) presents the grant in band +[Signaling and policy](/quest/m2/p2p/signal.md) presents the grant in band on each direct session. This quest does not depend on that line. Docs: `doc/bin/relay/auth.md` states that peer grants need an asymmetric @@ -66,4 +66,4 @@ Additive. ## Related -- [Signaling and policy](/quest/m1/p2p/signal.md) - the first consumer +- [Signaling and policy](/quest/m2/p2p/signal.md) - the first consumer diff --git a/quest/m1/auth/relay-refresh.md b/quest/m1/auth/relay-refresh.md index cff68ecc51a..65fa8ddc8b1 100644 --- a/quest/m1/auth/relay-refresh.md +++ b/quest/m1/auth/relay-refresh.md @@ -81,7 +81,6 @@ Additive. ## Required - [Origin narrowing](/quest/m1/auth/narrowing.md) - the live re-scope a shrinking token union needs, so no temporary close-on-shrink policy ships -- [Pattern interest](/quest/m1/path-patterns.md) - AUTH can represent the complete grants relay revalidation returns - [Lite stream](/quest/m1/auth/lite.md) - supplies the AUTH stream and `auth::Request` this consumes - [Unauthorized reset](/quest/m1/auth/unauthorized.md) - the code this diff --git a/quest/m1/auth/request-token.md b/quest/m1/auth/request-token.md index ddf64060128..f7336308975 100644 --- a/quest/m1/auth/request-token.md +++ b/quest/m1/auth/request-token.md @@ -73,6 +73,9 @@ to) and on `moq_auth::Client` (the per-request lease). Wire: none new; the param ## Required -- [Legal IETF input](/quest/m0/ietf-legal-input.md) - decodes the parameter everywhere the draft allows it - [Relay tokens](/quest/m1/auth/relay-refresh.md) - supplies the lease revalidation the per-request lease reuses + +## Related + +- [Legal IETF input](/quest/m0/ietf-legal-input.md) - also edits `decode_params!`; refresh this Plan when it lands, since the strict decoder then decodes and ignores the token diff --git a/quest/m1/auth/token-in-band.md b/quest/m1/auth/token-in-band.md index 59bf43eb58f..574bf9c96c5 100644 --- a/quest/m1/auth/token-in-band.md +++ b/quest/m1/auth/token-in-band.md @@ -24,8 +24,11 @@ AUTH can carry the full grant once the pattern-interest prerequisite lands. the client makes. A `?jwt=` in the URL stays a member of the union, which is how cluster dial targets keep their per-peer credential, and per-dial extras use the session's `auth().add()` once connected. moq-ffi - `MoqClient::set_tokens`, libmoq `moq_client_set_tokens` (mirrored in the - wrappers and `cpp/obs/src`), and `js/net`'s `connect` options field follow. + `MoqClient::set_tokens` (mirrored in the wrappers, and reaching the + generated C and C++ bindings and OBS through + [C++ through moq-ffi](/quest/m1/cpp/README.md)) and `js/net`'s `connect` + options field follow. Decided in the 2026-09-30 audit: no new libmoq API, + since it gets no more feature work. - Credential refresh belongs with token presentation. Resolve the configured credential source before each dial. After an authorization refusal, resolve it once more and retry only when the credential changed; do not loop on a diff --git a/quest/m0/plan-av-clock.md b/quest/m1/av-clock.md similarity index 95% rename from quest/m0/plan-av-clock.md rename to quest/m1/av-clock.md index c82e3ff855c..fe19a250911 100644 --- a/quest/m0/plan-av-clock.md +++ b/quest/m1/av-clock.md @@ -11,6 +11,9 @@ the next re-anchor. ## Plan +Moved from m0 to m1 in the 2026-09-30 audit: it waits on the whole jitter +line and is a published `@moq/watch` break on dev, so it is not in flight. + Settled: per-track handles, and this quest lands them. `sync.track("audio")` and `sync.track("video")` each report their advertised delay and measured spread, and one is nominated as the clock source. `SyncInput` diff --git a/quest/m1/bbr-ack-cleanup.md b/quest/m1/bbr-ack-cleanup.md index 3439bf801ef..bb0db79437a 100644 --- a/quest/m1/bbr-ack-cleanup.md +++ b/quest/m1/bbr-ack-cleanup.md @@ -10,10 +10,10 @@ behavior. ## Plan -The fix lives in moq-dev/noq. In released 1.3.1 (`ff9d2ab5`), -[`on_end_acks`](https://github.com/moq-dev/noq/blob/ff9d2ab518cfb155f9ebb9925f1c784665eac92a/noq-proto/src/congestion/bbr3/mod.rs#L1783) -runs `retain` over all tracked packets, then scans them again to mark stale -entries. Draining a flight with fixed-size ACK batches has quadratic total +The fix lives in moq-dev/noq. The baseline is the current releases: the +workspace pins moq-noq 1.3.2 and 2.0.0 is out. In both, `on_end_acks` +(`noq-proto/src/congestion/bbr3/mod.rs:1845`) runs `retain` over all tracked +packets, then scans them again to mark stale entries. Draining a flight with fixed-size ACK batches has quadratic total cleanup work. [Google QUICHE](https://github.com/google/quiche/blob/c961965aa3ee8f2b6f05ebcac794f7854101adcd/quiche/quic/core/congestion_control/bandwidth_sampler.cc#L377) uses packet-number lookup and obsolete-prefix reclamation; use that as a reference without copying a TCP or single-space assumption into QUIC. @@ -55,6 +55,6 @@ is needed. ## Related -- [Loss sampling](/quest/m1/quic/bbr-loss-parity.md) - preserve packet metadata needed by the separate loss-sample repair; both edit `bbr3/mod.rs`, so sequence them - [BBR starvation edges](/quest/m1/quic/bbr-app-limited-edges.md) - also edits `bbr3/mod.rs`; one owner there at a time - [Benchmark comparisons](/quest/m1/performance-comparisons.md) - reusable measurement guidance, not a prerequisite for this fix +- [Loss sampling](/quest/m2/quic-bbr-loss-parity.md) - preserve packet metadata needed by the separate loss-sample repair; both edit `bbr3/mod.rs`, so sequence them diff --git a/quest/m1/bench-ci.md b/quest/m1/bench-ci.md index 4df11aa246b..7376f8e4a5c 100644 --- a/quest/m1/bench-ci.md +++ b/quest/m1/bench-ci.md @@ -50,4 +50,4 @@ a GitHub App: ## Related - [Benchmark comparisons](/quest/m1/performance-comparisons.md) - extends the same `bench/run.sh` with repeated paired rounds -- [Bench coverage](/quest/m1/bench-coverage.md) - more targets for this job to track +- [Bench coverage](/quest/m2/bench-coverage.md) - more targets for this job to track diff --git a/quest/m1/bench-coverage.md b/quest/m1/bench-coverage.md deleted file mode 100644 index 05d5b3077a3..00000000000 --- a/quest/m1/bench-coverage.md +++ /dev/null @@ -1,28 +0,0 @@ -# [M] Benchmarks for containers, catalog, auth, and path matching - -## Goal - -Hot paths that have no benchmark get Criterion targets, so CI tracks them: -`moq-mux` container import and export per frame, `hang` catalog encode, decode, -and update, `moq-auth` token verification, and `moq-pattern` path matching. - -## Plan - -- `moq-mux`: fMP4/CMAF and Annex-B import and export over checked-in or - generated fixtures, with throughput in frames and bytes. Keep fixture - generation out of the timed region. -- `hang`: catalog encode and decode swept over rendition count, plus the - per-update cost a publisher pays. -- `moq-auth`: JWT verification per connection, swept over algorithm and claim - size. The in-band token path gets its bench with - [In-band token](/quest/m1/auth/token-in-band.md), not here. -- `moq-pattern`: matching swept over pattern count and path depth. Coordinate - with [Path patterns](/quest/m1/path-patterns.md) so the matcher gets one - bench, not two. - -Anything that fans out gets a sweep over both axes. Name each target after -what it measures, so the CI comment reads without opening the file. - -## Related - -- [Benchmark regressions in CI](/quest/m1/bench-ci.md) - tracks these targets on PRs and nightly diff --git a/quest/m1/bindings-graceful-close.md b/quest/m1/bindings-graceful-close.md deleted file mode 100644 index adfa57fac50..00000000000 --- a/quest/m1/bindings-graceful-close.md +++ /dev/null @@ -1,15 +0,0 @@ -# [M] Bindings close sessions gracefully - -## Goal - -On dev, `shutdown` in moq-ffi and every wrapper (py, swift, kt, go, dart, and the generated C/C++) drains the session the way `moq_net::Session::close` and `moq_tokio::Connection::close` do. Finished tracks deliver their last groups and FIN before the session ends, bounded by the same deadline. The language bindings stop losing the tail of a publish when they stop. OBS gets this only once it moves off hand-written libmoq onto the generated C++, which [C++ through moq-ffi](/quest/m1/cpp/README.md) owns; libmoq takes no more shutdown work. - -## Plan - -`Session::close` and `Connection::close` landed with drain-before-close (#4430). Today the FFI session (`rs/moq-ffi/src/session.rs`) only has `cancel(code)` and `shutdown()`, and `shutdown` is just `cancel(0)`, which ends it immediately. - -Decision (maintainer, 2026-09-28): `shutdown` becomes the async draining close in every binding. The name can't be `close`, because UniFFI's Kotlin generator already emits `AutoCloseable.close()` to release the handle, and `shutdown` already promises a graceful shutdown. Turning it async is breaking, so this targets `dev`; no second method, per the no-shim rule in AGENTS.md. `cancel` stays the immediate path. Like `Session::close`, `shutdown` is fallible: a drain the peer does not acknowledge in time surfaces as a timeout error through each binding's error mechanism rather than a silent success. Test both paths end to end through moq-ffi: a final group and clean track end reach the peer after `shutdown` returns, and an unacknowledged drain returns the timeout. - -Mirror `shutdown` in each wrapper and follow the Cross-Package Sync table in AGENTS.md, including `doc/lib/*`, except `rs/libmoq`, whose shutdown work is abandoned per [Generated C bindings](/quest/m1/c/README.md). IETF sessions still close at once until [IETF drain before close](/quest/m2/ietf-drain-before-close.md) lands. - -Public API: breaking on dev, `shutdown` becomes async, drains, and returns the close error in moq-ffi and every wrapper. Wire: no format change; a binding's shutdown now sends queued data and FIN before closing instead of discarding them. diff --git a/quest/m1/broadcast-epoch/README.md b/quest/m1/broadcast-epoch/README.md index 337297edc33..96a0172d3e7 100644 --- a/quest/m1/broadcast-epoch/README.md +++ b/quest/m1/broadcast-epoch/README.md @@ -15,8 +15,8 @@ wire message changes. At an epoch-aware relay, a request for a bare name resolves to its newest live epoch on every protocol version. Non-goals: redundant publishers sharing one epoch, and failing over between -them faster than the keep-alive (the [redundant ingest](/quest/m2/redundant-ingest.md) -study). Also out of scope: trusting the publisher's clock (a far-future epoch +them faster than the keep-alive (a question +[Cluster routing](/quest/m1/cluster-routing/README.md) owns). Also out of scope: trusting the publisher's clock (a far-future epoch wins until its route goes away). ## Plan @@ -61,5 +61,5 @@ This README owns: - [Origin](/quest/m1/broadcast-epoch/origin.md) - moq-net publish mints an epoch, consumers follow the newest live one, and bare requests resolve to it on every version - [Apps](/quest/m1/broadcast-epoch/apps.md) - moq-cli, the browser publish and watch components, and demo/web publish under epochs and play bare names - [Gateways](/quest/m1/broadcast-epoch/gateways.md) - RTMP, SRT, and WHIP ingest mint an epoch per incoming connection, so an encoder reconnect is a clean takeover -- [Bindings](/quest/m1/broadcast-epoch/bindings.md) - moq-ffi, libmoq, and every wrapper expose the epoch and inherit the default +- [Bindings](/quest/m1/broadcast-epoch/bindings.md) - moq-ffi and every wrapper expose the epoch and inherit the default - [GStreamer and OBS](/quest/m1/broadcast-epoch/gst-obs.md) - moqsink and the OBS plugin publish each run under a fresh epoch diff --git a/quest/m1/broadcast-epoch/bindings.md b/quest/m1/broadcast-epoch/bindings.md index ed5567ef691..e7bb2876fd4 100644 --- a/quest/m1/broadcast-epoch/bindings.md +++ b/quest/m1/broadcast-epoch/bindings.md @@ -2,8 +2,9 @@ ## Goal -`moq-ffi`, `libmoq`, and the py, swift, kt, go, and dart wrappers publish under -the default epoch and follow bare names like Rust. The epoch of a published or +`moq-ffi` and the py, swift, kt, go, and dart wrappers publish under the +default epoch and follow bare names like Rust. The generated C and C++ +bindings pick it up from moq-ffi; libmoq gets no new API. The epoch of a published or consumed broadcast is readable, and a caller can pass an explicit one. The reconnect counter `session.epoch()` is renamed so "epoch" has one meaning. @@ -13,9 +14,12 @@ reconnect counter `session.epoch()` is renamed so "epoch" has one meaning. argument. Keep the surface to what a binding consumer needs. - Rename `session.epoch()` in every binding (for example to `connects()`). That is a break, so it lands on `dev`. -- Update `doc/lib/{py,swift,kt,go,dart,c}` per the cross-package sync table, +- Update `doc/lib/{py,swift,kt,go,dart}` per the cross-package sync table, and run `just test smoke --all`. +Decided in the 2026-09-30 audit: libmoq is frozen (renamed `rs/moq-c` on +`dev`), so C and C++ consumers get epochs from moq-ffi. + ## Required - [Origin](/quest/m1/broadcast-epoch/origin.md) - the behavior the bindings surface diff --git a/quest/m1/broadcast-epoch/gst-obs.md b/quest/m1/broadcast-epoch/gst-obs.md index 5ae7824177d..35604ee5e4d 100644 --- a/quest/m1/broadcast-epoch/gst-obs.md +++ b/quest/m1/broadcast-epoch/gst-obs.md @@ -10,9 +10,11 @@ restarted pipeline or a stop and start in OBS is a clean takeover for viewers. `moqsink` takes the origin default per session. When [#3115](/quest/m2/3115-moqsink-the-publication-has-no-generation-so-a-flush.md) lands, each of its publication generations is a new epoch. OBS gets it -through libmoq. Update `doc/bin/gstreamer.md` and `doc/bin/obs.md` if they -show paths. +through the generated C++ bindings from moq-ffi (decided in the 2026-09-30 +audit: libmoq gets no new API). Update `doc/bin/gstreamer.md` and +`doc/bin/obs.md` if they show paths. ## Required -- [Bindings](/quest/m1/broadcast-epoch/bindings.md) - OBS publishes through libmoq +- [Bindings](/quest/m1/broadcast-epoch/bindings.md) - moq-ffi exposes epochs +- [C++ through moq-ffi](/quest/m1/cpp/README.md) - OBS publishes through the generated C++ diff --git a/quest/m1/broadcast-epoch/origin.md b/quest/m1/broadcast-epoch/origin.md index 1e065f18acd..0c02eab0ba0 100644 --- a/quest/m1/broadcast-epoch/origin.md +++ b/quest/m1/broadcast-epoch/origin.md @@ -32,6 +32,9 @@ any wire change. exclusion and the per-path fronts from #3312 stay intact. - Benchmark resolution swept over epochs per name and names per origin, so following does not scan the table. +- Open: does a catalog `broadcast` reference by bare name pin the epoch its + catalog came from, or follow the newest? Settle it with + [Catalog track alias](/quest/m1/catalog-track-alias.md). - Update `doc/concept` and `drafts/draft-lcurley-moq-lite.md` wherever they describe resolution or takeover. The rule is a relay behavior, so state it in the draft even though no field changes. @@ -43,4 +46,6 @@ Wire: none. ## Related +- [Catalog track alias](/quest/m1/catalog-track-alias.md) - cross-broadcast catalog references, which must pick an epoch + - [#2991](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - a new epoch starts each track at sequence 0 diff --git a/quest/m1/cache-expiry-growth.md b/quest/m1/cache-expiry-growth.md index 0aafd2b2c1f..7bbe215a52c 100644 --- a/quest/m1/cache-expiry-growth.md +++ b/quest/m1/cache-expiry-growth.md @@ -27,7 +27,3 @@ Otherwise reproduce with a focused test. Unexpired groups at higher throughput, expiry not running on some path, or groups held outside the pool's accounting would each explain it. Fix what is actually wrong. Consider whether an unbounded default is the right default for an origin at all. - -## Related - -- [Relay memory](/quest/m1/relay-memory.md) - what an announcement costs in memory diff --git a/quest/m1/cache-wall-eviction.md b/quest/m1/cache-wall-eviction.md index 083a2857e52..7643c0075e4 100644 --- a/quest/m1/cache-wall-eviction.md +++ b/quest/m1/cache-wall-eviction.md @@ -42,4 +42,4 @@ Public API: none from the plan. Wire: none. ## Related - [Cache expiry growth](/quest/m1/cache-expiry-growth.md) - relay memory past the expiry window, in the same cache -- [Cache shard](/quest/m1/perf/cache-shard.md) - the pool's shared counters under many workers +- [Cache shard](/quest/m2/cache-shard.md) - the pool's shared counters under many workers diff --git a/quest/m1/capture-control.md b/quest/m1/capture-control.md deleted file mode 100644 index 958853788f1..00000000000 --- a/quest/m1/capture-control.md +++ /dev/null @@ -1,50 +0,0 @@ -# [M] Capture Control: settled name, loud cut, prompt cancel, catalog clock - -## Goal - -The capture handles from [#4184](https://github.com/moq-dev/moq/pull/4184), -on `dev` only, get their final shape before release: - -- `encode::CaptureOptions` is `encode::Capture` in both moq-audio and - moq-video. -- `Control::cut()` on video tells the caller when the backend cannot force a - keyframe. Today the driver logs one warning on `CutUnsupported` and keeps - the GOP cadence, so a recording or resume boundary silently never appears. -- Dropping the last `Control` ends the driver promptly, including while the - startup probe, `capture::open`, `Sink::open`, or an encode is in flight. - Today those awaits never see the handle close, so a camera or permission - prompt can outlive its owner. -- Capture publishers stamp on the clock their catalog advertises, with no - separate clock to pass. Today both `CaptureOptions` carry their own - `clock: moq_mux::Clock`, and `Default` builds a fresh one, so a caller - relying on the default publishes against a mapping the catalog never - advertised. `moq import capture` passes `catalog.clock()`, the only correct - value. - -## Plan - -Decided: - -- Rename to `encode::Capture`, which reads as the capture half next to - `encode::Options`. Update moq-cli and the docs; moq-ffi and libmoq do not - call the capture paths, so no binding mirror exists today. -- `cut()` fails loud with an error rather than logging. The encoder is opened - lazily, so the handle may not know yet; the probe already opens one, which - is one place to learn it early. Choose between `cut()` returning - `Result` (refusing once the backend is known) and the driver ending with - `CutUnsupported`, and record the choice here. -- Race every await in the driver against the controls closing, rather than - only the idle wait, so the probe and the demand-driven opens both cancel. -- Drop the `clock` field from both options; `Control::new` already takes the - catalog producer, so it reads `catalog.clock()`. Update moq-cli and any - binding that forwards a clock. The clock fixtures in both crates already - pass the catalog's clock, so they keep grading the same path. This absorbs - the former m2 capture-clock-source quest: it breaks the same `dev` options, - so one break lands instead of two. - -This is a `dev` break layered on #4184; land it on `dev` before the release -that first publishes these handles. - -Tests: a backend without forced keyframes surfaces `CutUnsupported` to the -caller; dropping the last `Control` during a slow fake open or probe returns -from `Driver::run` without finishing the open. diff --git a/quest/m1/cli-packaging.md b/quest/m1/cli-packaging.md index 730b83b3bcc..33a48b9b306 100644 --- a/quest/m1/cli-packaging.md +++ b/quest/m1/cli-packaging.md @@ -30,6 +30,20 @@ than at run. Then verify the shipped artifact runs `moq devices` and `moq play` on each platform, since a feature that compiles into the binary and then fails to open a device is the same gap one layer down. +Also enable `v4l2` in the Linux ARM release build, so a released binary on a +Raspberry Pi 4 publishes from `moq import capture` through the V4L2 M2M +hardware encoder (`rs/moq-video/src/v4l2.rs`, already run on a Pi 4's +`bcm2835-codec`) with no GStreamer detour. Verify that once on a Pi 4. + +Add a board hardware note to `doc/bin/cli.md` next to the capture build +instructions: Raspberry Pi 5 has no video encoder and Jetson Orin Nano ships +without NVENC; Pi 4, CM4, Zero 2 W, and Orin NX and above encode. RK3588 +encodes through rkmpp in a vendor kernel, not V4L2, so it stays on the +`moq-gst` route. + +Decided in the 2026-09-30 audit: the v4l2 encode quest folded in here, since +its remaining work was one release feature flag and a doc note. + ## Required - [Audio capture without runtime system libraries](/quest/m1/capture-alsa-link.md) - the microphone path must start without system audio libraries before every distribution can ship it diff --git a/quest/m1/cli-serve.md b/quest/m1/cli-serve.md index 9456879ca9f..298cd2a3f67 100644 --- a/quest/m1/cli-serve.md +++ b/quest/m1/cli-serve.md @@ -30,6 +30,11 @@ relay. configured; the unauthenticated import-to-export smoke keeps passing with `--auth-public`. -## Required +Decided in the 2026-09-30 audit: no longer waits on +[`moq relay`](/quest/m2/moq-relay-subcommand.md). `moq-cli` already depends +on `moq-relay`, and the open-relay listener is a security gap that should not +wait on an m2 subcommand. -- [`moq relay`](/quest/m1/moq-relay-subcommand.md) - the CLI hosts the relay library, which `serve` comes from +## Related + +- [`moq relay`](/quest/m2/moq-relay-subcommand.md) - the CLI later hosts the whole relay diff --git a/quest/m1/close-codes.md b/quest/m1/close-codes.md deleted file mode 100644 index 8478905c3bc..00000000000 --- a/quest/m1/close-codes.md +++ /dev/null @@ -1,42 +0,0 @@ -# [M] Close codes on every transport - -## Goal - -A client sees the application close code its peer sent, for example -`SessionError::App(4011)` from `Session::abort` or `Request::reject`, over -WebSocket (qmux) and raw QUIC (`moqt://`), as it already does over -WebTransport. Never `Transport("connection closed")` or its own `Internal`. - -## Plan - -Both bugs are upstream; fix them at the source, release, and bump the pins. - -Targets `dev`: #4262 (open) does this, and the qmux release pulls in -`web-transport-trait` 0.5 (`SendStream::set_priority` takes `i32`), a Rust -API break. It reports `@moq/qmux` already keeps the first close. - -- qmux 0.5.1 (`moq-dev/web-transport`) lets later writes overwrite the - recorded close in `session.rs`: the WS Close frame read after - APPLICATION_CLOSE (reader loop, backend `send_replace`), a local `close()` - after the peer closed, and a second peer APPLICATION_CLOSE. `accept_uni` and - `accept_bi` also return a bare `Closed`. Make the first close win, make - `close()` a no-op once closed, and have `accept_*` return the recorded - reason. Add a qmux test where APPLICATION_CLOSE and EOF arrive together. -- `web-transport-moq` 1.3.2 (`moq-dev/noq#11`) maps a raw `moqt://` peer's - `ApplicationClosed` code directly. Done; only the regression below remains. -- moq-net's `close(Internal)` after a transport error is correct: closing a - closed connection does nothing. Do not work around it here. -- One moq-tokio regression runs the issue's three cases (abort after accept, - abort then drop, reject during handshake) over `https://`, `ws://`, and - `moqt://`, and fails on the current pins. -- Check whether `@moq/net`'s qmux peer keeps the first close too; fix it in - the same PR if not. - -## Closes - -- [#4249](https://github.com/moq-dev/moq/issues/4249) - application close code is lost over the WebSocket (qmux) transport - -## Related - -- [qmux on noq](/quest/m1/quic/qmux.md) - the rewrite must keep first-close-wins -- [io_uring close](/quest/m1/quic/uring-close.md) - the same symptom class on the io_uring backend diff --git a/quest/m1/cluster-routing.md b/quest/m1/cluster-routing/README.md similarity index 83% rename from quest/m1/cluster-routing.md rename to quest/m1/cluster-routing/README.md index d15a3d77256..821bd5f0805 100644 --- a/quest/m1/cluster-routing.md +++ b/quest/m1/cluster-routing/README.md @@ -5,15 +5,20 @@ A broadcast event reaches each relay at most once, and a relay learns only the prefixes its own clients asked for. An announcement says a path exists at an origin relay, at a cost; how to reach that origin comes from a shared relay -topology, so no announcement inside a cluster carries a hop list. This quest -records the design; its wire and implementation quests are planned from the -simulator's report. +topology, so no announcement inside a cluster carries a hop list. A relay's +memory scales with what it serves, not with what the mesh knows. This +questline records the design; its wire and implementation quests are planned +from the simulator's report. Non-goals: warm re-origination (a warm relay would be one more origin with a cost, so leave room for it), and a permanently mixed-version cluster. ## Plan +This is a questline with no children yet. Its children (wire and +implementation) are planned next in a separate `/quest-plan` session, from +the decisions and open questions below. + ### Why not path vector or Babel Today every relay advertises its best route to every peer not already in the @@ -167,6 +172,29 @@ registry. What decides the wire: the same scenario costs 18.6M messages instead of 189k. Per-origin seqnos, above, end both. +### Memory before and after + +On-demand announcements bound the route table by demand; measure that saving +before and after the implementation lands. Keep two costs apart: the route +table and per-announcement state (`RouteEntry` plus `ServeState`) scale with +announcements and routes, while the served-content cache a `ServeState` +materializes scales with demand. + +Every published figure is stale. The old baseline was 8.8 KB per announced +broadcast plus 4.3 KB per extra route on `adad52b`, measured with two +throwaway `moq-net` examples driving an origin under a counting allocator and +reading `/proc/self/statm`. Since then +[moq#2989](https://github.com/moq-dev/moq/pull/2989) cut `kio`'s inline waiter +slots from 32 to 4 (a `kio::State<()>` went from 896 B to about 200 B, and +`kio`'s `tests/waiter_allocs.rs` pins that lever as spent), and +[moq#3225](https://github.com/moq-dev/moq/pull/3225) made a standby route a +table entry rather than an object graph. Neither example is committed, since +they need `#[doc(hidden)]` size probes on private types. Rebuild them and +restate the per-broadcast and per-route cost, the per-peer session +bookkeeping (`announce_ids`, `held`, `watched`), and the shed threshold on a +degree-5, 1 GB node. Chat-shaped traffic (one broadcast per channel or per +chatter) depends on the answer. + ### Open questions - Sharding registries by HRW over a prefix key once one registry cannot hold @@ -194,6 +222,14 @@ registry. What decides the wire: `doc/concept/use-case/contribution.md`). Inside a cluster no announcement carries a hop list, so two encoders on different ingest relays become two origins. Keep the documented behavior or change the docs in the same PR. + Say whether same-hop semantics survive, or + [Same-hop importers](/quest/m1/hop-aligned-import.md)' work is thrown + away. The redundant ingest study folded in here: whether the pair claims one + `@` epoch, what enforces the aligned groups and matching catalog the + docs only ask for, and who declares the incumbent dead early (a failover + service that retracts it, or active-active delivery to the relay). Weigh it + against the moq-transport rule that each publisher of a namespace must be + asked (#3697). The answer may be a no-go. - Whether equal-cost next hops should spread by a hash of the path. A fixed tie-break sends every path through the same neighbour and its failure takes them all. @@ -204,6 +240,8 @@ registry. What decides the wire: ## Related -- [Redundant ingest](/quest/m2/redundant-ingest.md) - builds on the `--hop` failover this must keep or replace -- [Routing cost domains](/quest/m2/routing-cost-domains.md) - cost across the cluster boundaries this keeps path vector +- [Same-hop importers](/quest/m1/hop-aligned-import.md) - builds on `--hop` failover, which this line must keep or replace +- [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - a redundant pair would share one epoch + - [Cross-relay delivery under bursts](/quest/m1/cross-relay-bursts.md) - its #4349 report also shows closed broadcasts announced for up to 229 s and flapping between Retracted and Announced across nodes, evidence for per-incarnation seqnos +- [Routing cost domains](/quest/m3/routing-cost-domains.md) - cost across the cluster boundaries this keeps path vector diff --git a/quest/m1/color-model.md b/quest/m1/color-model.md index cf39b1ed8be..45fed149ab4 100644 --- a/quest/m1/color-model.md +++ b/quest/m1/color-model.md @@ -1,11 +1,11 @@ -# [M] Catalog colour model +# [M] Encoders signal the colour they produce ## Goal -The Hang catalog describes a video rendition's colour: primaries, transfer -characteristics, matrix coefficients, range, and the HDR10 mastering display and -content light levels. A renderer can set up its pipeline from the catalog -instead of guessing or reparsing the bitstream. +Every moq-video encode path signals the colour its output pixels actually +have. The CUDA, D3D, and Android paths preserve primaries, transfer, matrix, +and range through conversion, and a path that cannot honour the requested +colour converts correctly or refuses instead of mislabelling. ## Plan @@ -15,45 +15,13 @@ warn about a known color mismatch and then label unchanged pixels as the requested color: convert correctly or refuse. Preserve color information through CUDA, D3D, and Android paths and test the signaled VUI against pixels. -`rs/hang/src/catalog/video/mod.rs` has carried a bare `// TODO color space` since -the config was written. Two codecs already expose colour per their own syntax: -`VP9` carries primaries, transfer characteristics, matrix coefficients, and -range inside its codec string, and `AV1` has the same fields, which -`rs/moq-mux/src/codec/av1/import.rs` fills from the sequence header. They only -round-trip through muxers (the fMP4 exporter writes VP9's into `vpcC`); no -renderer consumes either, H.264 and H.265 have no equivalent, and there is no HDR10, -mastering display, or content light handling in `rs/` or `js/` at all. So an -HDR broadcast is delivered today and rendered as if it were SDR, whatever the -source signalled. - -Model the codec-neutral properties rather than one codec's syntax, so H.264 and -H.265 VUI, AV1 colour config, and a container's `colr` box all populate the same -fields. Generalize the existing VP9 and AV1 fields into that model rather than -adding a second colour source beside them: the codec-specific fields keep their -wire meaning (the VP9 codec string is defined by its spec) and feed the neutral -fields at import, so a renderer reads one place. Fill them at import from -whichever source the rendition provides, and emit them on export. - -Settle the precedence before adding the fields, because these sources disagree -in real files and a renderer must not see a different answer per import path. -Prefer the bitstream over the container: VUI and the AV1 colour config are what -the encoder actually signalled and travel with the elementary stream, while a -`colr` box is added by a muxer that may be wrong or stale. Record which source -won so a conflict is diagnosable rather than invisible, and treat an -unspecified value as absent rather than as a signalled default, so a partial -container box does not override a complete bitstream. - -Static display properties belong here rather than in a timed track, which is -also where the HDR10 metadata that lives in H.26x SEI should land once it can be -read. That is the one seam with the SEI line, and it runs in one direction: -this quest gives display metadata a home, and does not depend on SEI work. - -Test each source of truth in isolation, a source that signals nothing, a -conflict between VUI and container resolving to the bitstream, a container box -that fills a gap the bitstream left unspecified, and an SDR round trip that -stays byte-identical. +Decided in the 2026-09-30 audit: split from the catalog colour model, which +moved to [Catalog colour](/quest/m2/color-catalog.md) because no renderer +consumes colour from the catalog today. Encoder correctness stays in m1 +because a mislabelled stream is wrong for every consumer. ## Related -- [SEI sidecars](/quest/m2/sei/README.md) - moves SEI out of the video track; +- [Catalog colour](/quest/m2/color-catalog.md) - the catalog describes a rendition's colour and HDR properties +- [SEI sidecars](/quest/m2/sei.md) - moves SEI out of the video track; the display metadata inside it needs the home this quest builds diff --git a/quest/m1/cpp/README.md b/quest/m1/cpp/README.md index b20d4c9f7ea..7fedd405dd9 100644 --- a/quest/m1/cpp/README.md +++ b/quest/m1/cpp/README.md @@ -2,7 +2,7 @@ ## Goal -A C++ developer adds one registry line or one tarball, includes ``, +A C++ developer adds one release tarball, includes ``, and holds the whole moq-ffi surface (session, origin, broadcast, track, group, media, audio and video) as RAII objects whose async operations return cancellable futures, with no `user_data` plumbing, no handle integers, and no @@ -41,11 +41,12 @@ One library, C++17 floor (OBS's baseline), feature-gated extras: `co_await` on a future under `__cpp_impl_coroutine`, `std::expected` under `__cpp_lib_expected`. Never a second library per standard. -Distribution is all of: a release tarball with a CMake package config and -pkg-config file (mirroring `libmoq.yml`), a vcpkg registry we own, and a Conan -remote we own, the latter two fetching the prebuilt tarball so consumers never -need a Rust toolchain or the bindgen fork. vcpkg lands first; the Conan recipe -reads the same release manifest so a release bumps both. +Distribution is a release tarball with a CMake package config and pkg-config +file (mirroring `libmoq.yml`), so consumers never need a Rust toolchain or the +bindgen fork. Decided in the 2026-09-30 audit: this line promises the tarball +only. A [vcpkg registry](/quest/m2/cpp-vcpkg.md) (m2) and a +[Conan remote](/quest/m3/cpp-conan.md) (m3) fetch the same tarball later and +stay deferred. Confirmed in [#4100](https://github.com/moq-dev/moq/pull/4100): @@ -74,7 +75,7 @@ Confirmed in [#4100](https://github.com/moq-dev/moq/pull/4100): ## Related -- [C# through moq-ffi](/quest/m2/cs/README.md) - the same recipe with NordSecurity's C# generator -- [Unreal prototype](/quest/m2/unreal.md) - a UE5 module consumes the package with exceptions disabled - [vcpkg registry](/quest/m2/cpp-vcpkg.md) - a registry we own serves the prebuilt package to `vcpkg` manifests -- [Conan remote](/quest/m2/cpp-conan.md) - a remote we own serves the same tarball to `conan install` +- [Conan remote](/quest/m3/cpp-conan.md) - a remote we own serves the prebuilt package to Conan +- [C# through moq-ffi](/quest/m3/cs/README.md) - the same recipe with NordSecurity's C# generator +- [Unreal prototype](/quest/m3/unreal.md) - a UE5 module consumes the package with exceptions disabled diff --git a/quest/m1/cpp/generator.md b/quest/m1/cpp/generator.md index 1a3c917d0dc..66dc7d8be83 100644 --- a/quest/m1/cpp/generator.md +++ b/quest/m1/cpp/generator.md @@ -44,4 +44,4 @@ stop here and write down why. ## Related -- [C# generator](/quest/m2/cs/generator.md) - the same 0.32 port against NordSecurity's C# generator +- [C# generator](/quest/m3/cs/generator.md) - the same 0.32 port against NordSecurity's C# generator diff --git a/quest/m1/cross-relay-bursts.md b/quest/m1/cross-relay-bursts.md index a9415011e8d..a7a31241d4a 100644 --- a/quest/m1/cross-relay-bursts.md +++ b/quest/m1/cross-relay-bursts.md @@ -27,4 +27,4 @@ cluster-routing evidence, not this quest's scope. ## Related -- [Cluster routing](/quest/m1/cluster-routing.md) - owns the stale and flapping announcements from the same report +- [Cluster routing](/quest/m1/cluster-routing/README.md) - owns the stale and flapping announcements from the same report diff --git a/quest/m1/dart-codecs.md b/quest/m1/dart-codecs.md index a0563a2791b..b302fdee481 100644 --- a/quest/m1/dart-codecs.md +++ b/quest/m1/dart-codecs.md @@ -32,3 +32,10 @@ This quest owns Dart integration of the already-landed `MoqVideoConsumer`: expose it through the Dart wrapper, ship codec-enabled artifacts, and test subscribed video decoding from Dart in CI. Update the capability docs in the same change. Do not finish with codecs enabled but the consumer unexposed. + +Decided in the 2026-09-30 audit: wait for the codec namespaces, so the Dart +wrapper exposes encoders and decoders in their final shape once. + +## Required + +- [Codec](/quest/m1/ffi-shape/codec.md) - audio and video codecs get their own namespaces in moq-ffi diff --git a/quest/m1/dart-publish.md b/quest/m1/dart-publish.md index f51a9d4f83f..f634f082147 100644 --- a/quest/m1/dart-publish.md +++ b/quest/m1/dart-publish.md @@ -39,11 +39,15 @@ hand-edited before tagging. Verify the published `moq_ffi` resolves its native asset from a clean machine with no monorepo checkout, since that download path is the one CI never exercises. -The blocker below is about not publishing a claim we cannot support: the +The iOS blocker is about not publishing a claim we cannot support: the first release is the one that reaches strangers, and pub.dev packages generally cannot be unpublished or deleted. A version may be retracted within seven days, but retraction does not erase it. +Decided in the 2026-09-30 audit: publishing also waits on FFI shape, which +relies on Dart being unpublished so its breaking renames are free. + ## Required - [Dart on iOS](/quest/m1/dart-ios.md) - the package advertises iOS, which nobody has run +- [FFI shape](/quest/m1/ffi-shape/README.md) - its breaking renames are free only while Dart is unpublished diff --git a/quest/m1/data-track-clock.md b/quest/m1/data-track-clock.md index 170d34a09a9..fcb277566b4 100644 --- a/quest/m1/data-track-clock.md +++ b/quest/m1/data-track-clock.md @@ -10,10 +10,9 @@ maps its timestamps to a different clock than the media. ## Plan +Remove live() (#4543) is done on `dev`, and the first-frame clock anchor +exists only there, so this targets `dev`. + Have data tracks read the catalog's clock when they stamp, not a copy made when they were created. Keep it crate-private if possible. Test: a data track created before an importer's first frame stamps on the anchored clock. - -## Required - -- [Remove live()](/quest/m1/remove-live.md) - introduces the first-frame clock anchor diff --git a/quest/m1/datagram-unfetchable.md b/quest/m1/datagram-unfetchable.md index 264d256331b..2de867c657f 100644 --- a/quest/m1/datagram-unfetchable.md +++ b/quest/m1/datagram-unfetchable.md @@ -34,9 +34,20 @@ Not planned: reliable or cached datagrams. If they are ever wanted, the way to get them is back-pressure in the QUIC library and treating each datagram like a one-shot stream, not a cache. +The subscription's range bounds datagrams the way it bounds groups, fixed in +the model rather than filtered per session. Decided in the 2026-09-30 audit: +the moxygen line's datagram-range quest merged here, since it duplicated this +late-join rule. Its edge cases: + +- a datagram at the start group when a frame offset skips object 0; +- SUBSCRIBE_UPDATE moving the range while datagrams are in flight; +- a datagram that lands before the subscription's alias or id is known. + Tests: a subscriber joining after datagrams were sent receives only later ones. A FETCH covering a datagram group gets no payload. A fetch stream carrying a datagram-flagged object fails that fetch and leaves the session up. +Each edge case above gets one, and a test tells a datagram filtered by the +range apart from one dropped for any other reason. ## Related diff --git a/quest/m1/drain/README.md b/quest/m1/drain/README.md index 786b65f1065..f1195be9dfa 100644 --- a/quest/m1/drain/README.md +++ b/quest/m1/drain/README.md @@ -58,4 +58,4 @@ by the stop deadline and encoder reconnect. ## Related -- [Cluster routing](/quest/m1/cluster-routing.md) - the configured topology and link costs a second relay per PoP joins +- [Cluster routing](/quest/m1/cluster-routing/README.md) - the configured topology and link costs a second relay per PoP joins diff --git a/quest/m1/effect-cancel.md b/quest/m1/effect-cancel.md deleted file mode 100644 index 540fa9db1a8..00000000000 --- a/quest/m1/effect-cancel.md +++ /dev/null @@ -1,12 +0,0 @@ -# [XS] Remove effect.cancel - -## Goal - -`@moq/signals` no longer exports `Effect.cancel`. Its only use was racing a -per-run pending promise, which leaks a reaction per call. It is already -marked `@internal`, and every internal caller uses `effect.race` instead. - -## Plan - -A published break to `@moq/signals`, so it targets dev. Delete the getter and -the promise backing it, and fix any caller or doc the deprecation left behind. diff --git a/quest/m1/ffi-shape/README.md b/quest/m1/ffi-shape/README.md index 878b5921725..f1edaccb158 100644 --- a/quest/m1/ffi-shape/README.md +++ b/quest/m1/ffi-shape/README.md @@ -56,7 +56,3 @@ work no child does: - [Net](/quest/m1/ffi-shape/net.md) - client and server take config records, snapshots are records, and the verbs match moq-net - [Media](/quest/m1/ffi-shape/media.md) - catalog, import, and container consume move under `media` - [Codecs](/quest/m1/ffi-shape/codec.md) - audio and video encoders and decoders move under their own namespaces with one constructor shape - -## Related - -- [Track demand](/quest/m1/track-demand.md) - the same `demand()` cleanup in Rust and JS diff --git a/quest/m1/ffi-shape/codec.md b/quest/m1/ffi-shape/codec.md index a5668cfc195..629f7b96264 100644 --- a/quest/m1/ffi-shape/codec.md +++ b/quest/m1/ffi-shape/codec.md @@ -22,7 +22,7 @@ The video encoder's output mirrors moq-video's `encode::Gop`: `Keyframe { interval }` variant, defaulting to keyframes at two seconds, and documented as non-exhaustive like the core. The wrappers expose it as an enum their callers construct, not one they are asked to match, so -[intra-refresh bindings](/quest/m2/intra-refresh/bindings.md) adds the refresh +[intra-refresh bindings](/quest/m3/intra-refresh-bindings.md) adds the refresh variant additively instead of breaking `gop` a second time. Go gets no uniffi default, so its zero value must read as keyframe mode. diff --git a/quest/m1/ffi-shape/net.md b/quest/m1/ffi-shape/net.md index 10212aa3013..3deba0302b8 100644 --- a/quest/m1/ffi-shape/net.md +++ b/quest/m1/ffi-shape/net.md @@ -15,8 +15,14 @@ are renamed. in Rust, since Go gets none; Option fields keep additions additive. This also retires Kotlin `Moq.connect`'s twelve named parameters. - The client config carries the protocol versions to offer, as libmoq's - `moq_client_config.versions` already does (`rs/libmoq/src/api.rs`), so every - binding can pin or restrict versions. moq-ffi has no version setter today. + `moq_client_config.versions` already does (`rs/libmoq/src/client.rs:37`), so + every binding can pin or restrict versions. moq-ffi has no version setter + today. +- The cpp line's client-config quest (`quest/m1/cpp/client-config.md` on + branch `quest/m1/cpp/README`) ships this same `MoqClientConfig` record + additively on `main`. Decided in the 2026-09-30 audit: this quest then only + removes the fallible setters on `dev`, rather than designing the record + twice. - Objects that are only getters become records (`AnnounceUpdate` today). Handles with verbs (`Request`, `TrackRequest`, `GroupRequest`) stay objects. - `TrackProducer` drops `name`/`is_used`/`used`/`unused` for `demand()`. diff --git a/quest/m1/frame-slot-charge.md b/quest/m1/frame-slot-charge.md index d7c199e5aab..4b61d31b08a 100644 --- a/quest/m1/frame-slot-charge.md +++ b/quest/m1/frame-slot-charge.md @@ -48,6 +48,6 @@ that was OOM-killing relays serving chat, and deliberately left out of it. Public API: none, unless `MAX_CACHE_BYTES` is restated. Wire: none. -## Related +## Required -- [Relay memory](/quest/m1/relay-memory.md) - the per-announcement half of the same question, whose figures also predate the current accounting +- [Frame alloc budget](/quest/m0/frame-alloc-budget.md) - edits the same group cache charge; land it first diff --git a/quest/m1/gpu-ci.md b/quest/m1/gpu-ci.md index 64bacaeeec2..e294915c561 100644 --- a/quest/m1/gpu-ci.md +++ b/quest/m1/gpu-ci.md @@ -58,4 +58,3 @@ Public API: none. Wire: none. ## Related - [Video hardware validation](/quest/m3/video-hardware.md) - hardware paths nothing runs yet -- [Runtime QA hosts](/quest/m2/runtime-qa-hosts.md) - on-demand jobs on hardware hosts, a broader contract than a nightly diff --git a/quest/m1/hls-discontinuity-sequence.md b/quest/m1/hls-discontinuity-sequence.md deleted file mode 100644 index a191a9e2aa6..00000000000 --- a/quest/m1/hls-discontinuity-sequence.md +++ /dev/null @@ -1,37 +0,0 @@ -# [S] moq-hls segments carry the absolute discontinuity sequence - -## Goal - -Every `moq_hls::export::Segment` reports the discontinuity sequence it belongs -to, the value a recorder writes as `EXT-X-DISCONTINUITY-SEQUENCE`, so two -cursors on sibling renditions agree no matter when each was created. On `dev`, -`Segment::discontinuity` is a `u64` count of breaks since the cursor's -previous segment ([#4068](https://github.com/moq-dev/moq/pull/4068)). A cursor -created after its rendition rebinds starts its count from its own first row, -so it disagrees with a sibling on the baseline. - -## Plan - -Decided: - -- Report the absolute sequence the timeline fanout already stamps on each - row, instead of the difference between rows. A recorder writes - `EXT-X-DISCONTINUITY-SEQUENCE` from the first segment and an - `EXT-X-DISCONTINUITY` wherever the value changes. -- Land it on `dev` before the next moq-hls release, so it ships in the same - breaking release as the existing `bool` to `u64` change rather than - breaking the field twice. - -Guidance: - -- `Position` in `export/segments.rs` then only tracks `after`; the - skip/emit baseline logic goes away. Check the serve path's playlist - rendering (`rendition.rs`, `playlist.rs`) already derives its tags from the - same stamp. -- The sequence is absolute within one `Broadcaster`. Document what a recorder - should do when its broadcaster is rebuilt and the sequence restarts. -- Update the field doc and the tests that assert per-cursor counts; add one - where a cursor created after a rebind reports the same sequence as a cursor - that has run since the start. -- moq.pro's recorder and index store the count today; note the change for its - pin bump. diff --git a/quest/m1/hop-aligned-import.md b/quest/m1/hop-aligned-import.md index 6f6f68b6c62..9b34dd42b0c 100644 --- a/quest/m1/hop-aligned-import.md +++ b/quest/m1/hop-aligned-import.md @@ -21,8 +21,8 @@ encoded stream. Capture is out: two encoders never align. not a per-process counter. Decide how both processes agree across a timestamp wrap (TS PTS wraps every 26.5 h) when they started on opposite sides of it. -- Frame timestamps derive from the input alone too: any re-anchor shift must - come from the stream, not process start or wall clock. +- Frame timestamps derive from the input alone too. Importers publish the + stream's own timestamps and refuse a rewind, so nothing shifts them. - An importer announces only once it knows its tracks, so it never refuses a track the incumbent serves. - Docs (`doc/bin/cli.md` "Redundant publishers", the `--hop` doc comment) @@ -40,6 +40,5 @@ survives the standby joining and the incumbent stopping. ## Related -- [Redundant ingest](/quest/m2/redundant-ingest.md) - splicing across first hops and two encoders, which this does not attempt -- [TS import shared shift](/quest/m1/ts-import-shared-shift.md) - the TS re-anchor shift that must stay input-derived +- [Cluster routing](/quest/m1/cluster-routing/README.md) - drops hop lists inside a cluster and must say whether same-hop failover survives; it also owns splicing across first hops and two encoders, which this does not attempt - [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - a redundant pair shares one epoch diff --git a/quest/m2/ietf-drain-before-close.md b/quest/m1/ietf-drain-before-close.md similarity index 84% rename from quest/m2/ietf-drain-before-close.md rename to quest/m1/ietf-drain-before-close.md index e5c034130dc..732dd31a91a 100644 --- a/quest/m2/ietf-drain-before-close.md +++ b/quest/m1/ietf-drain-before-close.md @@ -12,7 +12,3 @@ the shared one second `CLOSE_TIMEOUT`. its sessions close at once. Count the IETF publisher's in-flight subscribe and fetch serves the way `lite::Publisher::drained` does, and report them there. Extend `rs/moq-net/tests/session_close.rs` to cover an IETF version. - -## Related - -- [Session close](/quest/m1/session-close.md) - the graceful end that withdraws announces diff --git a/quest/m1/js-closed-track-leak.md b/quest/m1/js-closed-track-leak.md deleted file mode 100644 index bc1755302c5..00000000000 --- a/quest/m1/js-closed-track-leak.md +++ /dev/null @@ -1,18 +0,0 @@ -# [XS] A late subscriber to a closed JS track is released - -## Goal - -On `dev`, where `@moq/net`'s track retention can be unlimited, a subscriber -that joins a track after its producer closed is removed from the track cache -once it's done, instead of being held forever. - -## Plan - -Found while landing the main-into-dev sync (#4428). That PR stopped caching -a subscriber the producer closes when retention is unlimited, since nothing -ages it out, but a subscriber that arrives after the close takes a different -path in `js/net/src/track.ts` and is never cleaned up. Release it on the same -terms, and add a test that a late subscriber to a closed track leaves no -cache entry once it drops. - -Public API: none. Wire: none. Targets `dev`, where unlimited retention lives. diff --git a/quest/m1/js-fetch.md b/quest/m1/js-fetch.md index a02da35c4ce..50ac6349eb8 100644 --- a/quest/m1/js-fetch.md +++ b/quest/m1/js-fetch.md @@ -43,4 +43,4 @@ A published API break, if the chosen shape requires one, goes through dev. ## Related -- [Browser archive](/quest/m1/archive/browser.md) - supplies memory or OPFS archive data through this generic request surface +- [Browser archive](/quest/m2/archive-browser.md) - supplies memory or OPFS archive data through this generic request surface diff --git a/quest/m1/legacy-end-overshoot.md b/quest/m1/legacy-end-overshoot.md index 77cff3dc582..6fdd917ab48 100644 --- a/quest/m1/legacy-end-overshoot.md +++ b/quest/m1/legacy-end-overshoot.md @@ -4,7 +4,8 @@ A `@moq/watch` subscriber never aborts a browser-published track with "group timestamp is below the live edge" when the publisher's next group starts -inside the previous group's estimated end. +inside the previous group's estimated end: the JS consumer enforces +monotonic group starts, like Rust. ## Plan @@ -22,13 +23,22 @@ takes the live edge from the end marker, so that keyframe's group reads as below it and the track aborts. The consumer's covered-group skip tolerates the same overlap the live-edge check rejects. +Decided (maintainer, #4543): group starts are monotonic, and that is the only +hard rule. A group's keyframe may not start below the previous group's start, +and no frame may sit below the start of the group before its own. Frames, +keyframes included, may dip below the previous group's content (B-frames, or +a keyframe overlapping its last frame), so an estimated end is never a hard +edge. A group may start at the same timestamp as the previous one; strictly +increasing starts are not enforced. Group IDs never move backwards. A group +starting before the previous group's start is a restart, a new broadcast. +The Rust `moq-mux` producer and consumer enforce this on `dev` since #4543. + - Reproduce with a mocked clock: cut a group, then resume with a keyframe between the last frame and the estimated end. -- Decide which side is wrong: the producer's estimate reaching past what it - will refuse, or the consumer treating an estimated end as a hard edge. - Fix it there and keep the other side's rule consistent with it. -- Check the Rust `moq-mux` producer for the same estimate. +- Align `js/hang/src/container/consumer.ts` (and the JS producer, if it + differs) to "group starts monotonic", matching `rs/moq-mux/src/container`. +- Target `dev`, where the #4543 rule lives. ## Related -- [More tests under load](/quest/m1/test-flakes-2.md) - other load-only failures, fixed at the cause +- [More tests under load](/quest/m1/test-flakes-2/README.md) - other load-only failures, fixed at the cause diff --git a/quest/m1/merge-queue.md b/quest/m1/merge-queue.md index d84f2cee103..a90b27b0d40 100644 --- a/quest/m1/merge-queue.md +++ b/quest/m1/merge-queue.md @@ -17,9 +17,9 @@ and there is no merge queue, so nothing re-runs them on the combined tree. queue tests the combination once, at merge time. - Make the workflows ready: every workflow providing a required check (today `Check` and `Test` in `.github/workflows/check.yml`) also runs on - `merge_group`. `just ci check|test` runs `sh/dispatch.sh`, which scopes - by diffing against its `BASE` argument, else `origin/$GITHUB_BASE_REF`. A - merge group sets no `GITHUB_BASE_REF`, so pass the group's base + `merge_group`. `just ci $JOB $BASE` (`justfile`) scopes by diffing + against its `BASE` argument, else `origin/$GITHUB_BASE_REF`. A merge group + sets no `GITHUB_BASE_REF`, so pass the group's base (`github.event.merge_group.base_sha`) as `BASE`. Check the concurrency group and the `closed`-only skip still behave for queue refs. - Document it in `CONTRIBUTING.md`: PRs merge through the queue, a @@ -29,8 +29,11 @@ and there is no merge queue, so nothing re-runs them on the combined tree. act, after the workflow change lands on `main`. Hand it over with the settings to use rather than changing it. +Decided in the 2026-09-30 audit: no longer waits on the tooling line; the +queue needs only `just ci $JOB $BASE`, which `main` already has. + Public API: none. Wire: none. -## Required +## Related -- [Tooling](/quest/m1/tooling/README.md) - `just ci` and `sh/dispatch.sh`, the entry point the queue runs +- [Tooling](/quest/m1/tooling/README.md) - later changes to the `just ci` entry point the queue runs diff --git a/quest/m1/mobile-ownership.md b/quest/m1/mobile-ownership.md new file mode 100644 index 00000000000..abfee2ab29d --- /dev/null +++ b/quest/m1/mobile-ownership.md @@ -0,0 +1,22 @@ +# [XS] Rust owns codecs on mobile + +## Goal + +The mobile media boundary is written down: Rust owns capture, codecs, and +rendering, and `moq-ffi` bridges native surfaces (`CVPixelBuffer` on iOS, +Android `HardwareBuffer`/`Surface`) as opaque handles. Swift and Kotlin do not +grow a parallel platform codec stack. + +## Plan + +Decided in the 2026-09-30 audit: option 2 from #700, Rust owns codecs. The +tree already shipped it. `moq-ffi` defaults to the `audio` and `video` +features (`rs/moq-ffi/Cargo.toml:27`), so the Kotlin and Swift packages already +carry the Rust codecs, and #4094 added the `CVPixelBuffer` bridge +(`MoqVideoSurface::PixelBuffer` on `dev`). Option 1 would add a second media +stack beside one that exists. + +What remains is recording the verdict in `rs/moq-ffi/AGENTS.md` (a maintainer +edit) and in [Android capture](/quest/m2/mobile-capture-android.md) and +[iOS capture](/quest/m2/mobile-capture-ios.md), which target `moq-video` as +written and no longer wait on this. diff --git a/quest/m1/moq-installer.md b/quest/m1/moq-installer.md deleted file mode 100644 index 78b023d5145..00000000000 --- a/quest/m1/moq-installer.md +++ /dev/null @@ -1,84 +0,0 @@ -# [M] One-command moq installation and upgrades - -## Goal - -A canonical Bash installer installs the released `moq` binary on supported -macOS and Linux machines without Rust or sudo. Running it again upgrades -the same installation; selecting a version supports -reproducible installs and deliberate downgrades. - -Install only `moq` from the `moq-cli` release. Token and relay functionality -belong to its subcommands, not separate installer choices. This work does -not implement those subcommands, automatic updates, a self-update command, -service setup, Windows support, or new release targets. - -## Plan - -- Default to the latest stable `moq-cli` release, with an explicit version - option. Resolve that product's tags, not the repository-wide latest - release: this repository publishes multiple independently versioned crates. - Refuse missing versions, malformed input, and incomplete releases clearly. -- Reuse the release archives and `SHA256SUMS`. Verify the selected archive - before extracting and installing its expected executable. Stage and check - the replacement before modifying the destination. Commit the executable and - ownership record as one recoverable transaction on the destination - filesystem: stage the new pair, retain the validated prior pair, and write a - durable journal before either rename. Record distinct phases after the - executable rename and after the ownership-record rename. On a handled - failure, roll back both files. After interruption, the next run must use the - journal to complete the new pair when both staged objects validate together. - If both renames completed, validate the installed pair and finish cleanup; - otherwise restore the prior pair, or remove every transaction file for an - initial install. Recovery must not misclassify a partial transaction as an - unmanaged installation. - Flush staged files, journal updates, renames, and their directory entries at - the required commit boundaries. Remove the journal and backups only after the - matching pair is durable. This is the atomic installation contract: recovery - exposes either the complete old pair or the complete new pair, never a mixed - pair. A failed initial install leaves no destination, while a failed upgrade - leaves the prior executable and ownership record usable. Clean up temporary - files after commit or rollback. -- Support the existing targets: macOS ARM64 and Linux x86_64/ARM64 with - glibc 2.34 or newer. Refuse unsupported operating systems, architectures, - and libc variants with actionable diagnostics. Intel macOS and musl/Alpine - require separate release work. -- Default to `~/.local/bin` with an explicit directory override. Do not invoke - sudo or edit shell profiles. Print the installed version and path, and - shell-appropriate PATH instructions when needed. Detect when another - `moq` on PATH would take precedence so success does not imply the wrong - binary will run. Do not follow an existing destination symlink into a - package manager's installation or overwrite a conflicting unmanaged file. - Keep a durable ownership record bound to the destination and installed - binary digest. Refuse replacement when the record is missing, malformed, - or mismatched, including a record copied from another destination. A valid - prior installation can be replaced; failed upgrades must preserve both its - binary and usable ownership record. -- Keep the canonical script and its tests in this repository. Publish a - usable HTTPS source for the dependent website quest; that quest exposes - `https://moq.dev/install.sh` without duplicating installer logic. -- Document first install, latest-version upgrade, explicit version selection, - directory override, PATH setup, and removal in `doc/setup/install.md`. - Use the working canonical URL until the website quest switches the example. - Package-manager installations continue to use their package manager for - upgrades. Describe only the subcommands the selected release actually ships. -- Wire installer tests into `just check` and CI. Cover initial - install, repeat install, upgrade, explicit downgrade, product-specific latest - selection, unsupported hosts, corrupt/missing assets, destination conflicts, - and failure preserving an existing executable. Use controlled fixtures for - failure cases, including interruption before and after every journal, rename, - durability, and cleanup boundary. Explicitly cover the post-second-rename, - pre-cleanup state. Assert that each case completes the new pair or restores - the old pair, and that an initial-install failure leaves neither file. Add - native macOS/Linux smoke coverage for executable startup. - Exercise the canonical script with real release assets in a temporary - install directory and run the installed `moq --version`. The dependent - website quest owns verification of the final public URL. - -## Related - -- [Binary release workflow](/quest/m1/tooling/release-binary.md) - reuse its - artifacts without requiring workflow consolidation -- [`moq relay`](/quest/m1/moq-relay-subcommand.md) - relay functionality joins - the same executable independently of its installation method -- [Install URL](/quest/m1/moq-install-url.md) - exposes this installer through - the moq.dev website after it is published diff --git a/quest/m1/obs-moq-video/README.md b/quest/m1/obs-moq-video/README.md index 1e41ad84c8f..16027a90966 100644 --- a/quest/m1/obs-moq-video/README.md +++ b/quest/m1/obs-moq-video/README.md @@ -8,34 +8,36 @@ Remove the MoQ OBS plugin's dependency on OBS/system FFmpeg ABI versions by deco Portability and FFmpeg removal lead. The current MoQ source decodes video with libavcodec, libavutil, and libswscale, and audio with libavcodec (`moq_source_decode_audio_frame` in `cpp/obs/src/moq-source.cpp`). Its swresample linkage is unused. FFmpeg linkage goes away only once both the video source replacement and the audio decode replacement land. The stranded audio branch (#3498, merged only into `codex/obs-audio-receive-base`) is abandoned; the audio playback quest replans it on the generated C++. The plugin reaches codecs through the generated C++ package over moq-ffi (the migration quest linked below lands first); build `libmoq_ffi` statically with only the codec features needed here; OS frameworks and runtime GPU drivers remain valid dependencies. Verify plugin imports instead of promising a completely static OBS plugin. -Attempt GPU delivery immediately, starting on macOS. Windows and Linux can ship independently. Prefer direct surface reuse, allow GPU conversion/blits, and automatically fall back to CPU delivery when import is unavailable or fails. Stats must show the actual decoder/encoder, delivery path, and fallback reason. Retaining a texture handle is insufficient unless pool ownership and synchronization also prevent reuse while work is in flight. +Attempt GPU delivery immediately on macOS decode; other platforms keep the CPU path here. Prefer direct surface reuse, allow GPU conversion/blits, and automatically fall back to CPU delivery when import is unavailable or fails. Stats must show the actual decoder/encoder, delivery path, and fallback reason. Retaining a texture handle is insufficient unless pool ownership and synchronization also prevent reuse while work is in flight. Initial video decoding covers H.264, HEVC, and AV1 where moq-video has an available backend. Unsupported codecs produce an actionable error; do not retain an FFmpeg fallback. VP8/VP9 return through their own follow-up quest. Audio playback covers Opus, AAC-LC, and PCM. Publishing remains opt-in, with one **Use MoQ encoders** choice for video and audio. Keep the existing OBS encoder mode. Internal OBS encoder adapters call moq-video/moq-audio, preserving OBS's A/V handling and the existing encoded MoQ output. The combined choice is enabled only when both adapters are present. Start with H.264, supported HEVC, and Opus; defer AV1/AAC encoding and PCM publishing UI. Keep bitrate separate from **Low latency**, **Balanced** (default), and **Quality** presets. Presets describe supported buffering/compression controls, not an end-to-end delay promise. -The quests separate portable decoding, platform GPU delivery, audio, and publishing so each can land and be validated independently. moq-ffi's decoded frames own their surface and convert to CPU pixels only on request (#4094, on `dev`); a native decode exposes the platform surface as a borrowed view, which each platform quest extends to its own surface type. +The quests separate portable decoding, audio, and publishing so each can land and be validated independently. moq-ffi's decoded frames own their surface and convert to CPU pixels only on request (#4094, on `dev`); a surface decode exposes the platform surface as a borrowed view, which each platform GPU quest extends to its own surface type. + +Decided in the 2026-09-30 audit: the Windows and Linux GPU decode paths and the macOS and Windows GPU encoder inputs moved to m2 (listed under Related), because each needs physical-hardware proof, and Linux GPU input is already m2/m3. ## Required - [Video source replacement](/quest/m1/obs-moq-video/source.md) - remove the FFmpeg video decode and attempt macOS GPU delivery immediately, with a working CPU fallback on other platforms - [Audio playback](/quest/m1/obs-moq-video/audio-playback.md) - replace the FFmpeg audio decode with moq-audio -- [Windows decoded frames](/quest/m1/obs-moq-video/decode-windows.md) - present decoded D3D11 surfaces in OBS without CPU readback -- [Linux decoded frames](/quest/m1/obs-moq-video/decode-linux.md) - present supported native decoded surfaces with visible CPU fallback - [Linux bundle](/quest/m1/obs-moq-video/linux-bundle.md) - attach a portable Linux x86_64 tarball to every obs-moq release once FFmpeg is gone - [Encoder presets](/quest/m1/obs-moq-video/presets.md) - define and measure shared low-latency, balanced, and quality policies - [Preset parity](/quest/m1/obs-moq-video/preset-parity.md) - audio stores and reports its preset like video, defaults to Balanced, and the preset claims hold - [Audio publishing](/quest/m1/obs-moq-video/audio-publish.md) - back an internal OBS Opus encoder with moq-audio - [Video publishing](/quest/m1/obs-moq-video/adapter.md) - back an internal OBS video encoder with moq-video and expose the combined opt-in mode - [Rate control](/quest/m1/obs-moq-video/rate-control.md) - the plugin reserves its bitrate and retunes the OBS encoder to the grant -- [macOS GPU input](/quest/m1/obs-moq-video/macos.md) - feed the encoder from the OBS compositor without CPU readback -- [Windows GPU input](/quest/m1/obs-moq-video/windows.md) - import or blit OBS D3D11 textures with explicit synchronization - [VP8/VP9 decoding](/quest/m1/obs-moq-video/vpx.md) - restore those playback codecs without an FFmpeg ABI dependency ## Related -- [OBS migration](/quest/m1/cpp/obs.md) - every quest here starts from the plugin on the generated C++, so codec surface is designed in moq-ffi and reaches libmoq and the other wrappers through the Cross-Package Sync table, not as OBS-only C symbols -- [Linux GPU input](/quest/m2/obs-linux-gpu.md) - allocation-export feasibility and its dependent implementation are deferred -- [VAAPI encode and decode](/quest/m4/video-vaapi.md) - owns Linux backend decode/import capabilities; reconcile its older dependency assumptions against current code +- [OBS migration](/quest/m1/cpp/obs.md) - every quest here starts from the plugin on the generated C++, so codec surface is designed in moq-ffi and reaches the other bindings through the Cross-Package Sync table, not as OBS-only C symbols +- [Linux GPU decode](/quest/m2/obs-decode-linux.md) - present hardware-decoded frames without CPU readback; needs physical-hardware proof +- [Windows GPU decode](/quest/m2/obs-decode-windows.md) - present D3D11 decoded textures without CPU readback; needs physical-hardware proof +- [macOS GPU input](/quest/m2/obs-macos.md) - feed compositor frames to VideoToolbox without a CPU round trip; needs physical-hardware proof +- [Windows GPU input](/quest/m2/obs-windows.md) - feed D3D11 compositor frames to the encoder without CPU staging; needs physical-hardware proof - [Video hardware validation](/quest/m3/video-hardware.md) - physical hardware evidence is required for each claimed GPU path - [Audio codecs](/quest/m1/audio-codecs/README.md) - HE-AAC, multichannel, and native AAC encode reach the OBS source and encoder adapters through moq-ffi +- [Linux GPU input](/quest/m3/obs-linux-gpu.md) - allocation-export feasibility and its dependent implementation are deferred +- [VAAPI encode and decode](/quest/m2/video-vaapi.md) - owns Linux backend decode/import capabilities; reconcile its older dependency assumptions against current code diff --git a/quest/m1/obs-moq-video/linux-bundle.md b/quest/m1/obs-moq-video/linux-bundle.md index 8a10983f3a8..7342b24611f 100644 --- a/quest/m1/obs-moq-video/linux-bundle.md +++ b/quest/m1/obs-moq-video/linux-bundle.md @@ -9,7 +9,7 @@ Every `obs-moq-v*` release attaches a Linux x86_64 tarball that loads into a sto - The only reason `obs-build` in `.github/workflows/libmoq.yml` skips Linux is FFmpeg: the source links nix/distro libavcodec for both video and audio, which is not portable. The FFmpeg removal (video source replacement plus audio playback) is the blocker; once the plugin is C++ over moq-ffi plus libobs and Qt6, a Linux build has no extra runtime dependency that OBS itself does not already carry. - Build on `ubuntu-24.04` (glibc 2.39, the floor OBS's own Linux packages target) against the libobs and Qt6 headers OBS's plugin template uses; the template's `.deb` recipe is the reference. Ship the plain archive layout the other platforms use (`obs-moq-*-x86_64-unknown-linux-gnu.tar.gz` with `bin/64bit/obs-moq.so` and `data/`), extractable into `~/.config/obs-studio/plugins/obs-moq/`. A `.deb` is optional and separate. - Flatpak OBS cannot load a plugin from the host filesystem. Verify a real Flatpak install and support it only if the sandbox's runtime ABI matches, documenting the `~/.var/app/com.obsproject.Studio/config/obs-studio/plugins/` path. Otherwise, state plainly that Flatpak is unsupported. -- `cpp/obs/build.sh --target x86_64-unknown-linux-gnu` produces the tarball, and the matrix in `obs-build` gains the row; nothing else in the release pipeline changes. Keep the nightly `just obs ci` compile as the PR gate; #4370 (open) compiles the OBS plugin on every PR, which covers the Linux compile if it lands first. +- `cpp/obs/build.sh --target x86_64-unknown-linux-gnu` produces the tarball, and the matrix in `obs-build` gains the row; nothing else in the release pipeline changes. The Linux compile gate already exists: #4370 (merged) compiles the OBS plugin on every PR. - Verify by loading the tarball into the oldest supported OBS 32 release and current stable on Ubuntu 24.04 and one non-Debian distro (Fedora), publishing and subscribing against a relay, and inspecting the `.so` with `ldd` for nothing beyond libobs, Qt6, glibc, and OS libraries. ## Required @@ -19,4 +19,4 @@ Every `obs-moq-v*` release attaches a Linux x86_64 tarball that loads into a sto ## Related -- [Linux decoded frames](/quest/m1/obs-moq-video/decode-linux.md) - native surface delivery lands on top of the portable CPU path this bundle ships +- [Linux decoded frames](/quest/m2/obs-decode-linux.md) - native surface delivery lands on top of the portable CPU path this bundle ships diff --git a/quest/m1/obs-moq-video/preset-parity.md b/quest/m1/obs-moq-video/preset-parity.md index d2c2cd86239..42a87504b3e 100644 --- a/quest/m1/obs-moq-video/preset-parity.md +++ b/quest/m1/obs-moq-video/preset-parity.md @@ -40,8 +40,8 @@ The shape is settled; this finishes it: - Known gap: VAAPI reports `LowLatency` whatever was asked, and V4L2 and MediaCodec report unconfirmed; no quest owns measuring and mapping presets for them. Media Foundation and VideoToolbox are owned by - [Windows GPU input](/quest/m1/obs-moq-video/windows.md) and - [macOS GPU input](/quest/m1/obs-moq-video/macos.md). + [Windows GPU input](/quest/m2/obs-windows.md) and + [macOS GPU input](/quest/m2/obs-macos.md). Public API: additive on moq-audio (the stored preset and its `Applied` report); the unpublished audio `Preset` default changes. Wire: none. diff --git a/quest/m1/obs-moq-video/source.md b/quest/m1/obs-moq-video/source.md index e0178523f94..e7bf0fd977e 100644 --- a/quest/m1/obs-moq-video/source.md +++ b/quest/m1/obs-moq-video/source.md @@ -7,7 +7,7 @@ The MoQ source loads and plays supported video without FFmpeg's video libraries ## Plan - Replace `cpp/obs/src/moq-source.cpp` video decode and conversion with moq-video through the generated C++ package: the moq-ffi video consumer for the CPU path, including frame ownership and cancellation semantics. Support H.264, HEVC, and available AV1 decoding; report unsupported VP8/VP9 explicitly until their follow-up lands. -- Decode with `MoqVideoDecoderOutput.native` set: each `MoqVideoDecodedFrame` retains the decoder's surface, `native()` borrows it (`PixelBuffer` on macOS) for as long as the frame lives, and `pixels(format)` is the CPU fallback. Hold the frame until OBS's GPU work reading it completes; held frames hold decoder pool slots. This surface landed on `dev` (#4094). +- Decode with `MoqVideoDecoderOutput.surface` set: each `MoqVideoDecodedFrame` retains the decoder's surface, `surface()` borrows it (`MoqVideoSurface::PixelBuffer` on macOS) for as long as the frame lives, and `pixels(format)` is the CPU fallback. A platform with no `MoqVideoSurface` variant refuses the opt-in. Hold the frame until OBS's GPU work reading it completes; held frames hold decoder pool slots. This surface is on `dev` only (#4094, renamed in 97575f002). - Implement the macOS presentation probe immediately: retain VideoToolbox PixelBuffer/IOSurface storage, inspect OBS graphics import and rendering support, and convert to OBS's expected color format on the GPU if necessary. Adapt the source render path to import textures on the graphics thread; preserve source timing instead of simply drawing the newest frame. An asynchronous CPU source API alone does not prove native GPU delivery. - Bound decoded frames retained by the render thread. On import failure, switch to the existing I420 delivery path and show the reason in Stats. Keep fallback stable for the stream/device configuration rather than retrying every frame; re-probe on a relevant configuration change or restart. Device loss and resize must retire old surfaces only after rendering completes. - Preserve timestamps, range/primaries, stride and plane layout, catalog/rendition changes, reconnect, visibility/deactivation behavior, and existing source settings. Carry frame-generation identity so late callbacks cannot display frames from a replaced source. @@ -17,6 +17,7 @@ The MoQ source loads and plays supported video without FFmpeg's video libraries ## Required - [OBS migration](/quest/m1/cpp/obs.md) - the plugin is on the generated C++ before decode changes +- dev's decoded-frame surface (#4094, 97575f002) reaches main ## Related diff --git a/quest/m1/obs-moq-video/vpx.md b/quest/m1/obs-moq-video/vpx.md index 528d73b1243..6dbc9ed8a9b 100644 --- a/quest/m1/obs-moq-video/vpx.md +++ b/quest/m1/obs-moq-video/vpx.md @@ -14,4 +14,4 @@ MoQ consumers, including the OBS source, decode VP8 and VP9 without depending on ## Related - [Video source replacement](/quest/m1/obs-moq-video/source.md) - consumer integration, not a blocker for codec implementation -- [Color model](/quest/m1/color-model.md) - share codec-neutral color metadata rather than introducing VP9-only conversions +- [Catalog colour model](/quest/m2/color-catalog.md) - share codec-neutral color metadata rather than introducing VP9-only conversions diff --git a/quest/m1/origin-front-parks.md b/quest/m1/origin-front-parks.md index e31c28fa4e5..729c9c1d825 100644 --- a/quest/m1/origin-front-parks.md +++ b/quest/m1/origin-front-parks.md @@ -28,3 +28,11 @@ show the replacement is cheaper. Public API: no signature change expected. `routed_broadcast` and `request_broadcast` keep their contracts; only where the waiting happens changes. + +Decided in the 2026-09-30 audit: this lands after shared fronts, which +reworks the same `model/origin.rs` fronts, and may move to m2 if shared +fronts' benchmark shows the retry loop's re-mint is noise. + +## Required + +- [Shared fronts](/quest/m0/shared-fronts.md) - reworks the same fronts, and its benchmark decides whether this stays in m1 diff --git a/quest/m1/p2p/transit.md b/quest/m1/p2p/transit.md deleted file mode 100644 index 20a8f23d9d4..00000000000 --- a/quest/m1/p2p/transit.md +++ /dev/null @@ -1,37 +0,0 @@ -# [M] Transit in the JS origin - -## Goal - -A tab forwards the routes it receives on one session to the sessions it -serves, so a watcher can re-serve a broadcast to a peer and a room of -watchers can cost the relay one egress stream. Split horizon holds: a route -is never announced back to the session it arrived on, and every forwarded -chain carries the tab's hop id. - -## Plan - -The JS origin keeps two tables so a received entry can never be announced -back to a peer; that separation stays. Transit adds the forwarding step: a -route received on session A is announced on every other attached session -with the tab's hop id appended to `hops`, the receiving link's cost added -per [cost across scopes](/quest/m1/p2p/cost-scopes.md) once it exists and -`Cost::UNKNOWN` semantics until then, and dropped when the chain reaches -`MAX_HOPS` or already contains the tab's id. A retraction forwards the same -way. - -Serving a forwarded route means the tab subscribes upstream once and fans out -from its own origin, which is what the Rust origin already does with -`with_publisher` and `with_subscriber`; the JS origin gains the same -splice-and-share behavior for remote routes it serves onward. - -The hop id must be one per origin, not per session, so the roster id from -[signaling](/quest/m1/p2p/signal.md) and the id in forwarded chains agree. - -Tests with the mock transport pair: a route received on A appears on B with -the id appended and never on A; a chain already containing the id is dropped; -a retraction on A retracts on B; two watchers of one tab share one upstream -subscription. - -## Related - -- [Watch opts in](/quest/m1/p2p/watch.md) - the first topology that needs a forwarding tab diff --git a/quest/m1/parked-read-wakes.md b/quest/m1/parked-read-wakes.md index 2e372aff464..3e403f8b261 100644 --- a/quest/m1/parked-read-wakes.md +++ b/quest/m1/parked-read-wakes.md @@ -22,4 +22,12 @@ Follow-ups from [#4484](https://github.com/moq-dev/moq/pull/4484), which made Settled: one quest, since both are the same wakeup invariant in `rs/moq-net/src/model/track.rs` and `resume.rs`. +Land after [resume latest](/quest/m1/resume-latest.md) (#4491), which edits +the same `resume.rs` wakeups, and rebase onto it. + Public API: none. Wire: none. + +## Related + +- [Resume latest](/quest/m1/resume-latest.md) - edits the same `resume.rs` wakeups; lands first (#4491) +- [#2991](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - extends the `resume.rs` takeover tests diff --git a/quest/m1/path-patterns.md b/quest/m1/path-patterns.md deleted file mode 100644 index ce5536ce77c..00000000000 --- a/quest/m1/path-patterns.md +++ /dev/null @@ -1,105 +0,0 @@ -# [M] Path patterns - -## Goal - -Every predicate over a MoQ broadcast path uses one matcher. Tokens, -origin scopes, announce interests, and public access rules can express -`pid/*/chat` and `**/*.hang` without maintaining competing glob dialects. -Routing is not a predicate here: advertisements stay prefixes, and -[announcement shapes](/quest/m3/announce-shapes.md) owns non-prefix routing. - -Literal paths remain coordinates, not sets. Roots, joins, exact broadcast -names, URL paths, filesystem paths, and object-store keys keep their own -types. The relay's `/announced/*prefix` debug endpoint remains a prefix-only -exception. - -## Plan - -### Dialect - -A v1 pattern is canonical `/`-separated segments: - -- a literal; -- `*`, matching one complete segment; -- `lit*lit`, with one `*` matching bytes inside one segment (`*.hang`, `foo*`, - `foo.*.hang`); -- `**`, matching zero or more complete segments, at most once per pattern. - -Patterns are exact by default. `foo` matches only `foo`, `foo/**` matches its -subtree including `foo`, `**` matches every path, and the empty pattern matches -only the current root. Reject leading, trailing, or repeated `/`, more than one -`*` in a segment, `**` mixed with literal bytes, and more than one `**`. A -second star in a segment stays reserved: matching it is still linear, but -containment stops being two string compares. Literal `*` needs no escape: new -path construction and publication reject it, while decoders tolerate it on -legacy protocol versions during rollout. - -Construction moves `**` before adjacent `*` segments: `*/**` becomes -`**/*`. Equivalent wildcard placements therefore share one text and identity. - -A pattern list is an unordered union reduced by containment. The shared -algebra supplies matching, overlap, containment, a literal head, and exact -set-valued rebasing. The set-valued result is load-bearing: rebasing `**/a` at -`a` must preserve both the root match and deeper paths ending in `a`. Union -containment is per member: a candidate covered only jointly by several members -(`a/**` against `a`, `a/*`, `a/*/**`) is refused, so the check stays linear and -a grant that means a subtree writes `a/**`. Pattern precedence uses one total -structural specificity everywhere rules overlap, ordered by literal segments, -then no `**`, then `lit*lit` segments, then `*` segments, then literal bytes -pinned inside `lit*lit` segments, then literal head length. That order agrees -with containment (a strict superset always ranks lower); equal patterns form -the same tier. - -### Ownership and compatibility - -`moq-pattern` and `@moq/pattern` own the grammar and algebra; `moq-net`, -`moq-auth`, `@moq/net`, and `@moq/auth` re-export them. Literal `Path` types -stay in `moq-net` / `@moq/net`. Golden cross-language vectors -(`rs/moq-pattern/tests/pattern.json`), exhaustive small cases, randomized round -trips, and the moq-net fuzz harness's `pattern` target prevent semantic drift at -the authorization boundary. Matching is linear and inherits `Path::MAX_PARTS` -(32), which also bounds residual expansion. - -Grants and claims carry no version. `moq-auth` grants are patterns: `foo` -means exactly `foo` and a subtree is `foo/**`. The published `put`/`get` -prefix encoding stays readable as subtrees, and subtree-only grants are still -written in it so older verifiers keep working. A wire message that carried -prefixes keeps them on the protocol versions that defined them; only new -versions carry patterns. - -The syntax follows Ant-style path patterns without `?`, classes, or braces. -NATS subjects motivate segment wildcards and reserved wildcard bytes; Vault -ACLs motivate structural specificity. Common Access -Token and `draft-ietf-moq-c4m-01` provide exact, prefix, and suffix matches per -namespace field, including exact depth with a trailing `nil`. Document the -exact common subset and keep the richer MoQ forms explicit rather than claiming -CAT cannot represent `pid/*/chat`. - -### Grants on the wire - -AUTH grants on moq-lite-06 carry the shared pattern semantics, without -changing older protocol versions. Interest stays a prefix: [#3770](https://github.com/moq-dev/moq/pull/3770) -keeps patterns off the announce wire, so ANNOUNCE_REQUEST and -SUBSCRIBE_NAMESPACE carry the prefix the caller asked for and a wildcard is -an optional filter on the consume side. [Announcement shapes](/quest/m3/announce-shapes.md) -later adds only exact, suffix, and prefix+suffix to moq-lite's ANNOUNCE_REQUEST; -any other pattern stays a consume-side filter. - -Replace lite-06 AUTH grant prefixes with patterns in Rust and JavaScript in -the same change. Update the lite draft and version-gated fixtures together. -Authorize by exact containment in the subscriber's v1 grant. Older moq-lite -versions keep their existing prefix wire and behavior; a grant they cannot -represent is refused, not narrowed. Cluster peers adopt nothing as a side -effect of this wire work. - -Test Rust and JavaScript interop, leading wildcards, `**` zero-segment -matches, containment refusal, and old-version behavior. - -## Required - -- [Lite auth](/quest/m1/auth/lite.md) - establish the AUTH exchange before upgrading its grants to patterns - -## Related - -- [Wildcard advertisements](/quest/m0/wildcard/README.md) - routes on prefix - claims; the matcher only filters them against consume-side interest diff --git a/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md b/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md index a5fccaa027a..4d9317643df 100644 --- a/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md +++ b/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md @@ -35,7 +35,7 @@ Where the reads are: `close` (rs/moq-uring/src/quic/noq/connection.rs:239), `handle_timeout` (:671), and `poll_transmit` (:786). The last one runs once per GSO train, since `flush` stages one train per turn (see - [Egress requeue](/quest/m1/perf/egress-requeue.md)). + [Run to quiescence](/quest/m1/perf/uring-quiescence.md)). The same profile shows the timer heap at ~1.6%: `::set` 0.92% plus diff --git a/quest/m1/perf/3203-moq-uring-add-opt-in-napi-busy-polling.md b/quest/m1/perf/3203-moq-uring-add-opt-in-napi-busy-polling.md deleted file mode 100644 index 5cce493345b..00000000000 --- a/quest/m1/perf/3203-moq-uring-add-opt-in-napi-busy-polling.md +++ /dev/null @@ -1,30 +0,0 @@ -# [M] moq-uring: add opt-in NAPI busy polling - -## Goal - -A worker can opt into io_uring NAPI busy polling from relay configuration, -off by default, reported honestly when unsupported, with bare-metal latency -and idle-cost numbers recorded before it is recommended anywhere. - -## Plan - -Follow-up to #2875. - -The relay already pins one worker and one ring per core. io_uring NAPI busy polling can keep a worker close to the NIC receive path and reduce wakeup latency, at the cost of continuously consuming CPU and power while it polls. - -#### Proposal - -- Add an explicit worker-level NAPI configuration with disabled as the default. -- Start with dynamic NAPI-ID tracking through `register_napi`. Add static IDs only if deployment can discover and maintain the correct queue IDs reliably. -- Make busy-poll duration and preferred-busy-poll behavior observable in relay configuration and stats. -- Report unsupported registration clearly. Do not silently claim the mode is active. -- Ensure unregister and worker teardown are safe. -- Document that this mode is for dedicated, latency-sensitive cores, not general self-hosting. - -#### Acceptance - -Measure on bare metal with the deployment NIC and queue affinity configured, not loopback. Compare disabled and several busy-poll durations under low, medium, and saturated load. Record p50, p99, and p999 packet latency, relay CPU, CPU idle residency, interrupts, drops, goodput, and power if available. Ship only as opt-in unless fleet-level data shows an acceptable idle-cost tradeoff. - -## Closes - -- [#3203](https://github.com/moq-dev/moq/issues/3203) - close this issue when the quest finishes diff --git a/quest/m1/perf/3205-moq-uring-register-reusable-io-uring-enter-wait-arguments.md b/quest/m1/perf/3205-moq-uring-register-reusable-io-uring-enter-wait-arguments.md deleted file mode 100644 index 904e0547ed2..00000000000 --- a/quest/m1/perf/3205-moq-uring-register-reusable-io-uring-enter-wait-arguments.md +++ /dev/null @@ -1,35 +0,0 @@ -# [M] moq-uring: register reusable io_uring_enter wait arguments - -## Goal - -Timed parking reuses one registered `io_uring_reg_wait` entry per worker via -`IORING_ENTER_EXT_ARG_REG` on Linux 6.13+, keeping today's `SubmitArgs` -path (rs/moq-uring/src/worker.rs:305, :410) as the 6.12 fallback, retained -only if cycles per enter measurably drop. - -## Plan - -Follow-up to #2875 and the CQ batching experiment in #3200. - -Timed parking currently builds a `Timespec` and `SubmitArgs` for each wait, then asks the kernel to copy the extended enter arguments. Linux 6.13 added registered wait regions and `IORING_ENTER_EXT_ARG_REG`, allowing a ring to reuse kernel-known wait storage. - -#### Proposal - -- After #3200 fixes the wait shape, register one stable `io_uring_reg_wait` entry per worker. -- Update its absolute deadline, batch target, and minimum wait before each enter, then use `IORING_ENTER_EXT_ARG_REG`. -- Keep the current extended-argument path as the Linux 6.12 fallback. Do not raise the kernel floor for this micro-optimization without benchmark evidence. -- Prefer safe upstream support in the `io-uring` crate. If the current release lacks the registration API, contribute or upgrade that support instead of spreading raw ABI calls through the worker. -- Keep registration ownership and unregistration in one worker-owned type. -- Test repeated deadline changes, no-deadline waits, interrupted enters, and teardown. - -#### Acceptance - -Measure this after the winning #3200 configuration, where enter frequency and argument shape are known. Record cycles and instructions per enter, enters per second, relay CPU, and latency. Retain the 6.13 fast path only if the end-to-end CPU change is measurable. - -## Required - -- [#3200: moq-uring: batch completion wakeups with MIN_TIMEOUT](/quest/m1/perf/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md) - complete the prerequisite issue first - -## Closes - -- [#3205](https://github.com/moq-dev/moq/issues/3205) - close this issue when the quest finishes diff --git a/quest/m1/perf/README.md b/quest/m1/perf/README.md index 95ae136cdd0..4eb4d4ad0fc 100644 --- a/quest/m1/perf/README.md +++ b/quest/m1/perf/README.md @@ -23,7 +23,7 @@ hot-path survey, so quests don't re-litigate them: - `moq-uring`'s only backend is noq. Every profile names its backend. The historical quiche-flavor numbers cited in - [Egress requeue](/quest/m1/perf/egress-requeue.md) and + [Run to quiescence](/quest/m1/perf/uring-quiescence.md) and [#3122](/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md) are re-measured on noq. - Cross-thread wakeups are already cheap: one futex word per worker, at most @@ -43,32 +43,26 @@ The relay's `/metrics` endpoint already carries the ring-level counters (enters, park/wake, batch effectiveness) several quests want as evidence, one row per io_uring worker. -## Required +Decided in the 2026-09-30 audit: io_uring is off by default and ships in no +package, and none of the uring micro-opts is measured on noq. The unmeasured +ones moved out (3129, 3200, 3202, the open contract, and cache shard to m2; +3201 and 3204 to m3), and NAPI busy polling (3203), registered wait +arguments (3205), and the priority `set_track` wakes were dropped. Egress +requeue folded into Run to quiescence; egress keep-alive and owned decode +copies folded into Group cost. The benchmark noise estimate and the noq +re-profile come first, since every quest here accepts "within noise". Lock +wait and One enter per turn rank next: they produce the numbers that decide +the rest. -- [Open contract](/quest/m1/perf/uring-open-contract.md) - plan concurrent WebTransport opening and cancellation +## Required -- [Announce replay](/quest/m1/perf/announce-replay.md) - the initial announce set replays in linear time, so joins don't slow with the route count -- [Group cost](/quest/m1/perf/group-cost.md) - count and cut the allocations and time spent relaying one small group to one viewer -- [One enter per turn](/quest/m1/perf/uring-one-enter.md) - a parking turn pays one io_uring_enter, submits flush deferred completions, and SQEs per enter is a counter -- [Run to quiescence](/quest/m1/perf/uring-quiescence.md) - a received packet's reply is staged in the same turn, under a pass budget that keeps the fairness rule +- [Performance comparisons](/quest/m1/performance-comparisons.md) - the noise estimate every "within noise" verdict here depends on +- [Performance profiles](/quest/m1/performance-profiles.md) - the reproducible noq profile the quests below re-measure on - [Lock wait](/quest/m1/perf/lock-wait.md) - each worker reports time blocked on cross-worker locks, deciding whether the shared model needs work +- [One enter per turn](/quest/m1/perf/uring-one-enter.md) - a parking turn pays one io_uring_enter, submits flush deferred completions, and SQEs per enter is a counter +- [Group cost](/quest/m1/perf/group-cost.md) - count and cut the allocations and time spent relaying one small group to one viewer +- [Run to quiescence](/quest/m1/perf/uring-quiescence.md) - a received packet's reply is staged in the same turn, under a pass and train budget that keeps the fairness rule +- [Announce replay](/quest/m1/perf/announce-replay.md) - the initial announce set replays in linear time, so joins don't slow with the route count - [Ingest batch](/quest/m1/perf/ingest-batch.md) - relay ingest pays one lock, wake, and clock read per chunk burst instead of per chunk -- [Egress cache refresh](/quest/m1/perf/egress-keepalive.md) - measure refresh costs while preserving slow-reader retention -- [Owned decoding copies](/quest/m1/perf/coding-decode.md) - measure and reduce owned decode allocations and copies - [#3122](/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md) - moq-uring: ~2.5% of relay CPU is vdso clock reads; the drive loop and its callers each re-read Instant::now() -- [Cache shard](/quest/m1/perf/cache-shard.md) - stop hammering one process-global cache line from every worker - [#3199](/quest/m1/perf/3199-moq-uring-remove-sq-indirection-and-per-enter-ring-fd.md) - moq-uring: remove SQ indirection and per-enter ring fd lookup -- [#3200](/quest/m1/perf/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md) - moq-uring: batch completion wakeups with MIN_TIMEOUT -- [#3129](/quest/m1/perf/3129-moq-uring-write-the-webtransport-stream-header-at-open.md) - moq-uring: write the WebTransport stream header at open time, so finish() never owes one -- [Egress requeue](/quest/m1/perf/egress-requeue.md) - trains per turn on the egress driver becomes a measured budget instead of a hardcoded one -- [#3201](/quest/m1/perf/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md) - moq-uring: use SENDMSG_ZC for large UDP GSO trains -- [#3202](/quest/m1/perf/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md) - moq-uring: use fixed-file slots for worker UDP sockets -- [#3204](/quest/m1/perf/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md) - moq-uring: register TX-pool buffers for zero-copy sends -- [Priority set_track wakes](/quest/m1/perf/priority-set-track-wakes.md) - a track priority change stops waking groups that end up where they started -- [#3203](/quest/m1/perf/3203-moq-uring-add-opt-in-napi-busy-polling.md) - moq-uring: add opt-in NAPI busy polling -- [#3205](/quest/m1/perf/3205-moq-uring-register-reusable-io-uring-enter-wait-arguments.md) - moq-uring: register reusable io_uring_enter wait arguments - -## Related - -- [Send buffer pools](/quest/m2/quic-buffer-pool.md) - the stream-send - allocation question, measured on the same shapes diff --git a/quest/m1/perf/coding-decode.md b/quest/m1/perf/coding-decode.md deleted file mode 100644 index 1e9e7af9301..00000000000 --- a/quest/m1/perf/coding-decode.md +++ /dev/null @@ -1,31 +0,0 @@ -# [S] Reduce owned path and byte-string decode copies - -## Goal - -Reduce measured allocation and payload-copy costs for owned byte strings, -strings, and paths without changing decoded values, errors, or wire bytes. - -## Plan - -`rs/moq-net/src/coding/decode.rs` decodes `Vec` through -`Buf::copy_to_bytes` followed by `to_vec`; `String` consumes that vector. -The first operation can return a shared view for a contiguous `Bytes` input, -but may allocate and copy for another `Buf`. Do not count every call as a -payload copy or assume a twofold improvement on production readers. - -Benchmark the actual reader input types, contiguous and chained buffers, -lengths 8 B through 1 KiB, and representative announcement messages. Compare -safe copying into an initialized vector with the current implementation. -Preserve bounds checks before allocation and UTF-8 validation. Keep owned -return types; borrowed decoding and new public APIs are outside this quest. - -Register a Criterion target in `moq-net` for discovery by `just bench`. -Report allocations, copied bytes, and throughput with paired base/current -runs. Retain the current implementation if no useful win is measured. -Add normal-CI regressions for fragmented input, truncated lengths/payloads, -invalid UTF-8, empty values, and path normalization; run the existing net -fuzz targets with `just rs fuzz path` and commit any regression inputs. - -## Related - -- [Benchmark comparisons](/quest/m1/performance-comparisons.md) - measurement conventions diff --git a/quest/m1/perf/egress-keepalive.md b/quest/m1/perf/egress-keepalive.md deleted file mode 100644 index 208b9efa9c4..00000000000 --- a/quest/m1/perf/egress-keepalive.md +++ /dev/null @@ -1,35 +0,0 @@ -# [S] Measure and reduce egress cache-refresh overhead - -## Goal - -Reduce measured cache-refresh overhead during batched delivery without -expiring a group while a slow subscriber or FETCH reader is draining it. -Retain the current behavior if the improvement is within measurement noise. - -## Plan - -`group::Consumer::keep_alive` takes a state read guard and calls -`Charge::refresh`. Both lite and IETF publishers call it between completed -frame writes. This protects a drain that spans longer than `latency_max`; -a stamp only at batch fill is insufficient. `Charge::touch` already skips -population accounting when the coarse timestamp has not advanced. - -Measure read-guard, clock, and atomic costs separately for fast fanout and -flow-controlled readers, including SUBSCRIBE and FETCH. Preserve per-frame -liveness refresh unless an alternative proves the same retention behavior. -Do not introduce another clock or pool-accounting mechanism: those belong to -[Cache shard](/quest/m1/perf/cache-shard.md). Recheck its implementation -before optimizing the remaining publisher overhead. - -Extend the existing group and track Criterion targets and add a bounded -session regression to normal CI. Keep -`slow_prefetch_reader_survives_expiry` (`rs/moq-net/src/model/track.rs`), and cover expiry scans -while a batch drains, cancellation, and eventual expiry after reads stop. -Report delivered bytes, refresh cost, CPU, and throughput for paired runs; -fewer refresh calls alone are not evidence of a win. - -## Related - -- [Cache shard](/quest/m1/perf/cache-shard.md) - owns shared accounting and clock costs -- [Ingest batch](/quest/m1/perf/ingest-batch.md) - ingest batching -- [#3122](/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md) - runtime clock costs diff --git a/quest/m1/perf/egress-requeue.md b/quest/m1/perf/egress-requeue.md deleted file mode 100644 index 90ba3987178..00000000000 --- a/quest/m1/perf/egress-requeue.md +++ /dev/null @@ -1,31 +0,0 @@ -# [XS] Trains per turn on the egress driver becomes a measured budget - -## Goal - -The io_uring QUIC driver stages one GSO train per turn and then wakes -itself (`Driver::flush`, rs/moq-uring/src/quic/noq/connection.rs:744), so a -deep backlog on one connection pays a whole driver turn per train of -`TRAIN_SEGMENTS = 63` segments (noq/connection.rs:23; `MAX_GSO_SEGMENTS = -64` at udp.rs:56 is the kernel cap). That cadence is a hardcoded fairness choice. -Make it a measured budget. - -## Plan - -The re-walk half of #3120 landed in #3134 (e6962b20e) on the since-deleted -quiche driver; the noq driver drains an event queue instead of walking -iterators (noq/connection.rs:697) and never had that shape. What is left is -the budget. - -- Add a trains-per-turn budget to `flush`. One train then - requeue is deliberate fairness across connections sharing a socket; keep - fairness by bounding the budget, and sweep 1, 2, and 4 trains per turn - under the fanout and single-heavy-connection shapes to see whether the - extra turn latency is real. -- Re-profile on noq; the numbers in #3120 are the quiche driver's. - -Acceptance: CPU per Gbps and throughput ceiling via `just bench BASE` on -Linux. Latency must not regress at the chosen budget. A no-win keeps 1. - -The [quiescence quest](/quest/m1/perf/uring-quiescence.md) sweeps this -budget together with its pass budget; land whichever runs first and fold the -other's sweep in. diff --git a/quest/m1/perf/group-cost.md b/quest/m1/perf/group-cost.md index a716f8889ef..9dea750f034 100644 --- a/quest/m1/perf/group-cost.md +++ b/quest/m1/perf/group-cost.md @@ -25,6 +25,17 @@ keeps that waiter and skips re-registering on lists that still hold it the next largest source from there. A measured no-win abandons the quest, per this line's rules. -## Related +Decided in the 2026-09-30 audit: two suspected per-group costs merged here +as candidates to measure with `SESSION_ALLOCS`, not separate quests. -- [Owned decoding copies](/quest/m1/perf/coding-decode.md) - decode-side copies are part of the same per-group cost +- Egress cache refresh: `group::Consumer::keep_alive` takes a state read + guard and calls `Charge::refresh` between completed frame writes on both + the lite and IETF publishers. It protects a drain longer than + `latency_max`, so keep per-frame liveness and + `slow_prefetch_reader_survives_expiry` (rs/moq-net/src/model/track.rs); + fewer refresh calls alone are not a win. +- Owned decode copies: `rs/moq-net/src/coding/decode.rs` decodes `Vec` + through `Buf::copy_to_bytes` then `to_vec`, and `String` consumes that + vector. Measure on the real reader input types (contiguous and chained) + before assuming a copy; keep the owned return types, bounds checks, and + UTF-8 validation. diff --git a/quest/m1/perf/lock-wait.md b/quest/m1/perf/lock-wait.md index 2fb63d7918b..e4e922bf7c7 100644 --- a/quest/m1/perf/lock-wait.md +++ b/quest/m1/perf/lock-wait.md @@ -27,7 +27,6 @@ Below one percent, record it and close the quest. Above, open a quest with the measured hot locks named, and only then decide between submitting staged SQEs before a blocking acquire and shrinking the lock in the model. -## Related - -- [Cache shard](/quest/m1/perf/cache-shard.md) - one of the shared cells the - wait would point at +Decided in the 2026-09-30 audit: [Cache shard](/quest/m2/cache-shard.md) +stays in m2 and is taken up only if this shows more than 1% contention on +the pool line. diff --git a/quest/m1/perf/priority-set-track-wakes.md b/quest/m1/perf/priority-set-track-wakes.md deleted file mode 100644 index b830630139c..00000000000 --- a/quest/m1/perf/priority-set-track-wakes.md +++ /dev/null @@ -1,42 +0,0 @@ -# [S] Stop set_track waking groups that end up where they started - -## Goal - -`lite::priority`'s `set_track` (rs/moq-net/src/lite/priority.rs:342) re-ranks -an item as `extract` (:322) then `place` (:261). The extract shifts every following vec entry up one and the place shifts them back -down, so an entry whose rank does not net-change is still woken: the shift up -takes its parked waker, and the shift back finds nothing left to restore. - -A track priority change should wake only the groups whose rank actually moved. - -## Plan - -The insert and remove paths are already exact, because each performs a single -monotone shift where every touched entry genuinely moves by one. Only the -double mutation in `set_track` can cancel itself out. - -Two shapes, cheapest first: - -- Defer the reconcile. Have `update_location` (:236) record the touched id and - leave `PriorityEntry::rank` (:185) holding the last *published* rank, then compare once at - the end of the mutation and wake only the net movers. Simple and total, but it - adds a second slab lookup per shifted entry to the insert hot path, so measure - it against `priority_queue_insert_front` (rs/moq-net/benches/priority.rs:25) - before taking it. -- Rotate instead of remove-and-reinsert. Moving an item within the sorted vec - only shifts the entries strictly between its old and new index, so computing - that range directly is both exact and less work than the two full shifts. It - has to keep the vec/overflow boundary in `place` intact, including the case - where the re-ranked item crosses it. - -The queue rework in #3298 left the wake count on this path as it was. It is a -cold path (a SUBSCRIBE_UPDATE -priority change), never group open or close. - -Acceptance: a test that parks each handle on its own waiter, calls `set_track` -on the front entry within a range where it stays first, and asserts no other -handle woke. No regression on the `priority_queue_insert_front` benches. - -## Related - -- [Hierarchical scheduling](/quest/m1/quic/scheduler.md) - removes this queue where the new scheduler replaces it diff --git a/quest/m1/perf/uring-one-enter.md b/quest/m1/perf/uring-one-enter.md index 5ff2baf3de9..c6238cdf53c 100644 --- a/quest/m1/perf/uring-one-enter.md +++ b/quest/m1/perf/uring-one-enter.md @@ -42,7 +42,7 @@ fails without the flag. Latency must not regress. ## Related -- [#3200](/quest/m1/perf/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md) - - the wait side of the same enter - [Run to quiescence](/quest/m1/perf/uring-quiescence.md) - fewer turns per packet, which multiplies this saving +- [#3200](/quest/m2/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md) - + the wait side of the same enter diff --git a/quest/m1/perf/uring-quiescence.md b/quest/m1/perf/uring-quiescence.md index 88b48797225..ba226bd7291 100644 --- a/quest/m1/perf/uring-quiescence.md +++ b/quest/m1/perf/uring-quiescence.md @@ -29,11 +29,17 @@ must not starve the socket. dispatch, then tasks to quiescence, then submit or park. That removes the stale first pass a park-returning turn runs today (worker.rs:180 polls on readiness the previous turn already consumed). -- The egress driver's one-train-then-self-wake shape - (rs/moq-uring/src/quic/noq/connection.rs:743-751) interacts with the - budget: a deep backlog would consume every pass. Fold the - [egress requeue](/quest/m1/perf/egress-requeue.md) train budget into the - same sweep so trains per turn and passes per turn are measured together. +- The egress driver stages one GSO train of `TRAIN_SEGMENTS = 63` segments + per turn and then wakes itself (`Driver::flush`, + rs/moq-uring/src/quic/noq/connection.rs:743-751), so a deep backlog pays a + whole turn per train and would consume every pass. That cadence is a + hardcoded fairness choice across connections sharing a socket. Make it a + trains-per-turn budget on `flush` and sweep 1, 2, and 4 together with the + pass budget, under the fanout and single-heavy-connection shapes, so trains + per turn and passes per turn are measured together. A no-win keeps 1 train. + The #3120 numbers are the deleted quiche driver's; re-profile on noq. + Decided in the 2026-09-30 audit: the egress requeue quest merged here, since + both budgets need the same sweep. - Add `passes` per turn to the metrics beside `turns`. Acceptance: turns and enters per received datagram on the chat shape @@ -45,8 +51,3 @@ meaning with a budget of 1 and gains a sibling proving the budget bound. - [One enter per turn](/quest/m1/perf/uring-one-enter.md) - the metrics and the submit placement this sweep is measured with - -## Related - -- [Egress requeue](/quest/m1/perf/egress-requeue.md) - the train budget - measured in the same sweep diff --git a/quest/m1/performance-comparisons.md b/quest/m1/performance-comparisons.md index ab8a640e72a..9512e1b2cbb 100644 --- a/quest/m1/performance-comparisons.md +++ b/quest/m1/performance-comparisons.md @@ -7,14 +7,17 @@ estimate and preserved evidence, so a small reported speedup can be evaluated. ## Plan -`bench/run.sh` runs each relay workload once as base then current, -without repeated rounds or alternating execution order. `cleanup` deletes the run +`bench/run.sh --runtime` already repeats rounds (`MOQ_BENCH_RUNTIME_ROUNDS`, +default 3) and reports the median (`bench/run.sh:15`, `:322`), but the +`just bench BASE` comparison still runs each relay workload once as base then +current, without alternating execution order. `cleanup` deletes the run directory, including Criterion estimates, load/host JSONL, relay logs, and -summaries. Preserve the existing default command -while extending this harness rather than creating another benchmark runner. +summaries. Preserve the existing default command while extending this harness +rather than creating another benchmark runner. -- Add configurable repeated paired rounds, alternate base/current order, and - perform warmup outside the measured window. Keep the current load generator, +- Reuse the runtime mode's rounds and median for the BASE comparison, as + paired rounds that alternate base/current order, and perform warmup outside + the measured window. Keep the current load generator, workload, backend, and resolved settings identical for both revisions. - Save individual paired results and report median paired deltas plus a documented dispersion/confidence estimate. Flag insufficient or noisy samples instead of diff --git a/quest/m1/performance-profiles.md b/quest/m1/performance-profiles.md index e0c5da304c0..b9817b837bb 100644 --- a/quest/m1/performance-profiles.md +++ b/quest/m1/performance-profiles.md @@ -45,5 +45,4 @@ verify current supported versions and pin any newly installed tools. ## Related - [Benchmark comparisons](/quest/m1/performance-comparisons.md) - repeatable results and artifact metadata -- [Relay memory](/quest/m1/relay-memory.md) - retained route and announcement memory - [Release profile](/quest/m1/release-profile.md) - also changes `[profile.profiling]`; land one, then rebase the other diff --git a/quest/m1/plan-watch-worker.md b/quest/m1/plan-watch-worker.md index 94f8afb7a61..baf471e1771 100644 --- a/quest/m1/plan-watch-worker.md +++ b/quest/m1/plan-watch-worker.md @@ -75,4 +75,4 @@ follow-up wires the capture worklet to the encoder worker with a - [Watch worker](/quest/m1/watch-worker.md) - the implementation this rewrites - [Browser benchmarks](/quest/m1/browser-benchmarks.md) - artifact conventions; may absorb the harness later -- [A/V clock](/quest/m0/plan-av-clock.md) - the `Sync` shape the implementation moves; the prototype can pace against today's +- [A/V clock](/quest/m1/av-clock.md) - the `Sync` shape the implementation moves; the prototype can pace against today's diff --git a/quest/m2/play-drain-tail.md b/quest/m1/play-drain-tail.md similarity index 100% rename from quest/m2/play-drain-tail.md rename to quest/m1/play-drain-tail.md diff --git a/quest/m1/qos/README.md b/quest/m1/qos/README.md index cc343a9c7cd..96e59d38cd3 100644 --- a/quest/m1/qos/README.md +++ b/quest/m1/qos/README.md @@ -44,9 +44,6 @@ on `main`. subscription records its last partial interval instead of losing it - [Lag dashboard](/quest/m1/qos/lag-dashboard.md) - the demo stats dashboard shows viewer lag percentiles and dropped media -- [Starvation at frame granularity](/quest/m1/qos/starvation-frames.md) - the - acknowledged frontier moves at every frame boundary through `poll_acked`, - with a delivery-delay histogram for jitter - [Publisher timeliness](/quest/m1/qos/publisher-timeliness.md) - per broadcast, how late media arrives at the relay against the track's own clock, and whether timestamps stay monotonic diff --git a/quest/m1/qos/starvation.md b/quest/m1/qos/starvation.md index 0a9131ad71e..9e6c21d5520 100644 --- a/quest/m1/qos/starvation.md +++ b/quest/m1/qos/starvation.md @@ -37,7 +37,7 @@ sample keeps it climbing the buckets while its frontier stands still. While the source is paused nothing is produced, so a tick carries no weight and the histogram does not move; a viewer's lag stays whatever it was until its frontier catches up, and reappears in the buckets once production resumes. This slice moves the frontier once per group; -the [frame-granularity quest](/quest/m1/qos/starvation-frames.md) moves it +the [frame-granularity quest](/quest/m2/starvation-frames.md) moves it per frame without changing the wire shape or the sampler, so fix both here. Aggregate as a byte-weighted cumulative histogram on `Traffic`, on the @@ -81,8 +81,6 @@ sum into one row; the aggregate consumer sums two nodes bucket by bucket. ## Related -- [Starvation at frame granularity](/quest/m1/qos/starvation-frames.md) - - moves the frontier at every frame end once `poll_acked` is released - [Publisher timeliness](/quest/m1/qos/publisher-timeliness.md) - the ingress mirror on the `Role::Subscriber` rows - [Media stats](/quest/m1/stats/README.md) - receiver-side evidence diff --git a/quest/m1/quic/README.md b/quest/m1/quic/README.md index 36c4c19aa23..d09e79e75b5 100644 --- a/quest/m1/quic/README.md +++ b/quest/m1/quic/README.md @@ -6,12 +6,12 @@ MoQ owns the QUIC features it needs. noq, the Quinn-derived stack n0 maintains for Iroh, is the parent; the moq-dev fork carries what MoQ needs on MoQ's schedule and offers it upstream when it is general. One core serves the tokio backend, the thread-per-core `moq-uring` backend, iroh, and qmux. The -features are per-stream acknowledgment progress, reliable stream resets, -hierarchical stream scheduling with per-broadcast fairness, the shared stream -state machine used by qmux, per-stream deadlines, and wider limits for relay -peers. The experiments that may join them (GCC, FEC, receive timestamps, -kernel pacing, buffer pools, media probing, L4S, careful resume, deadline -keep-alive) live in [m2](/quest/m2/README.md) and do not gate this line. +features are BBR correctness, reliable stream resets, hierarchical stream +scheduling with per-broadcast fairness, and wider limits for relay peers. +Per-stream acknowledgment progress, per-stream deadlines, qmux on the shared +stream state machine, and the experiments (GCC, receive timestamps, the egress +profile, media probing, L4S, careful resume, deadline keep-alive) live in +[m2](/quest/m2/README.md) and do not gate this line. ## Plan @@ -28,8 +28,9 @@ with only what each needs, rather than adding another simulation loop; a fix at the transport boundary still needs a transport test through the real callbacks. The existing loops stay, since the fork merges upstream weekly and a port would conflict. Each BBR fix ships in a fork patch release without -waiting for the remaining transport features. The -[Google comparison](/quest/m2/quic-bbr-google.md) is a separate study. +waiting for the remaining transport features. The comparison against +Google's BBR is part of the separate +[natural drain study](/quest/m2/quic-bbr-natural-drain.md). Rules the line keeps: @@ -38,6 +39,8 @@ Rules the line keeps: never a crate that impersonates the parent; - published MoQ crates depend on crates.io releases of the fork, never a workspace-only Cargo patch or a mutable branch; +- each feature quest releases the fork crate it changes and records the + parent noq commit it is based on; there is no separate release quest; - MoQ's config names congestion families (`Loss`, `Delay`, and `RealTime` once GCC ships), never algorithms; noq's public `Controller` trait is the seam experiments plug into, and MoQ owns which algorithm each family means. @@ -49,20 +52,18 @@ session with fairness enabled, the send group is the broadcast. The default MoQ order is newest group first; an ordered subscription keeps oldest first. This is a transport API change, not a MoQ wire change. +Decided in the 2026-09-30 audit: deadlines, qmux, BBR loss parity, ECN +measurement, ACK progress, and the ACK hook moved to m2, since no m1 quest +consumes them. The release quest was deleted: the fork already publishes to +crates.io (moq-noq 1.3.2, web-transport-moq 2.0.0) with no workspace patch, +and the qmux crate release folds into [qmux](/quest/m2/quic-qmux.md). + ## Required - [BBR idle burst](/quest/m1/quic/bbr-app-limited.md) - a fork regression proves a burst after a long idle is paced at the learned bandwidth, closing #4219 -- [Align BBR loss handling with draft-06](/quest/m1/quic/bbr-loss-parity.md) - losses use their own sample and undo re-enters ProbeUp through Refill - [Mark BBR starvation wherever the source runs dry](/quest/m1/quic/bbr-app-limited-edges.md) - partial polls count, local send caps do not, receiver credit is pinned - [Deliver the application close before io_uring teardown](/quest/m1/quic/uring-close.md) - the peer receives the final close when the client immediately stops its worker -- [Measure ECN on the backbone](/quest/m1/quic/ecn-measure.md) - a written - verdict on marking versus dropping, and whether Linode and OVH keep marks -- [Per-stream ACK progress](/quest/m1/quic/ack-progress.md) - the fork reports - how far a send stream has been acknowledged and when -- [poll_acked in web-transport](/quest/m1/quic/ack-hook.md) - the - backend-neutral hook that awaits an acknowledged stream offset, implemented - for noq and released - [Reliable stream reset](/quest/m1/quic/reliable-reset.md) - `RESET_STREAM_AT`, so a reset WebTransport stream still delivers its header - [Hierarchical stream scheduling](/quest/m1/quic/scheduler.md) - strict @@ -70,12 +71,6 @@ This is a transport API change, not a MoQ wire change. the lossy scalar; retransmits follow the same order - [Relay peers get wider limits](/quest/m1/quic/peer-limits.md) - MAX_STREAMS and MAX_DATA are raised after SETUP identifies a cluster peer -- [Per-stream deadlines](/quest/m1/quic/deadline.md) - hopeless retransmits - become resets, and a tail loss probe fires early while there is still time -- [qmux on the QUIC stream state machine](/quest/m1/quic/qmux.md) - qmux is a - first-class crate in the fork over the shared stream state machine -- [Release the stack](/quest/m1/quic/release.md) - publish immutable, - consumable versions of the fork and its adapters - [Upstream the fork](/quest/m1/quic/upstream.md) - every general carried change is offered to n0-computer/noq once its shape has settled @@ -85,18 +80,13 @@ This is a transport API change, not a MoQ wire change. per-broadcast fairness policy on cluster sessions - [Starvation](/quest/m1/qos/starvation.md) - the first consumer of ACK progress: how far behind viewers are, from the relay's point of view -- [Receive timestamps](/quest/m2/quic-receive-ts.md) - per-packet arrival - times for GCC and deadlines -- [GCC egress experiment](/quest/m2/quic-gcc.md) - a measured verdict on - WebRTC-style delay control -- [FEC experiment](/quest/m2/quic-fec.md) - a measured verdict on transport - redundancy -- [Kernel pacing](/quest/m2/quic-kernel-pacing.md), [Send batching](/quest/m2/quic-send-batching.md), - [Send buffer pools](/quest/m2/quic-buffer-pool.md), [Natural media drains](/quest/m2/quic-bbr-natural-drain.md) - - the syscall, allocation, and controller spikes - [Multipath spike](/quest/m2/multipath-spike.md) - a noq capability that MoQ does not use yet - [Discover media headroom](/quest/m2/quic-probe.md) - test useful-media pacing before adding redundant probe traffic - [L4S on the backbone](/quest/m2/quic-ecn.md) - an ECT(1) option in the fork, an `ecn` config knob, and a dualpi2 measurement - [Careful resume on reconnect](/quest/m2/quic-careful-resume.md) - a redial starts at the previous connection's rate - [Keep-alive by deadline](/quest/m2/quic-keep-alive.md) - a PING only when the idle deadline nears, no fixed timer +- [Receive timestamps](/quest/m3/quic-receive-ts.md) - per-packet arrival + times for GCC and deadlines +- [GCC egress experiment](/quest/m3/quic-gcc.md) - a measured verdict on + WebRTC-style delay control diff --git a/quest/m1/quic/release.md b/quest/m1/quic/release.md deleted file mode 100644 index fee1d41bdfc..00000000000 --- a/quest/m1/quic/release.md +++ /dev/null @@ -1,32 +0,0 @@ -# [M] Release the QUIC stack - -## Goal - -Immutable releases of `moq-noq-proto`, `moq-noq`, `moq-noq-udp`, -`web-transport-moq`, and the qmux crate are available to every published MoQ -crate. The workspace lockfile identifies exact released sources, with no -root-only Cargo patch or mutable git branch, and a consumer can tell from any -release which parent commit it carries. - -## Plan - -Release the dependency chain from the bottom up: the fork's crates, which one -tag releases together, then `web-transport-trait` if its surface moved, then -qmux. Pin each released version in this repository's workspace dependencies -and regenerate `Cargo.lock`. Verify minimal, default, and all-feature builds so -enabling iroh, qmux, or the uring runtime cannot unify two incompatible copies -of the protocol state. - -Each fork release documents the parent commit, the carried patches with their -upstream PR or the reason there is none, and the security-update procedure. A -release is incomplete if a consumer cannot tell whether an advisory against -the parent applies. - -## Required - -- [Reliable stream reset](/quest/m1/quic/reliable-reset.md) - the - WebTransport-required transport extension -- [Hierarchical stream scheduling](/quest/m1/quic/scheduler.md) - the new - transport API -- [qmux on the QUIC stream state machine](/quest/m1/quic/qmux.md) - the - shared qmux implementation diff --git a/quest/m1/quic/reliable-reset.md b/quest/m1/quic/reliable-reset.md index 10746d214fa..64becb43ca2 100644 --- a/quest/m1/quic/reliable-reset.md +++ b/quest/m1/quic/reliable-reset.md @@ -68,7 +68,7 @@ provisional codepoints if the document changes before release. - moq-net (`rs/moq-net/src/tail.rs`) and `@moq/net` (`js/net/src/tail.ts`) wait a grace for a group whose reset lost its header until this lands -- [qmux on the QUIC stream state machine](/quest/m1/quic/qmux.md) - consumes - the same reset state without a parallel implementation - The removed quiche backend was the one stack that had this, so it is the known browser-compliance gap. +- [qmux on the QUIC stream state machine](/quest/m2/quic-qmux.md) - consumes + the same reset state without a parallel implementation diff --git a/quest/m1/quic/scheduler.md b/quest/m1/quic/scheduler.md index 58bcb30b191..c28b33fb3ae 100644 --- a/quest/m1/quic/scheduler.md +++ b/quest/m1/quic/scheduler.md @@ -96,7 +96,7 @@ prove byte fairness over a bounded window, strict preemption by a higher priority, newest-first backlog shedding, dynamic priority updates, blocked-stream handling, sequence wrap and sparse sequence values, and cleanup on reset. This quest owns native QUIC proof and -reusable scheduling fixtures. [qmux](/quest/m1/quic/qmux.md) owns running those +reusable scheduling fixtures. [qmux](/quest/m2/quic-qmux.md) owns running those fixtures through its record writer after adopting the scheduler; native scheduler completion must not wait for that dependent integration. Preserve working behavior on backends not yet migrated, and remove queue code only @@ -112,8 +112,10 @@ where the new implementation makes it redundant. - [moq#3320](https://github.com/moq-dev/moq/pull/3320) - removes the current dense-rank queue from the wide scalar path and records why a scalar cannot provide this fairness level -- [Ladder controller](/quest/m1/ladder/controller.md) - rendition priority is +- [Ladder controller](/quest/m2/ladder/controller.md) - rendition priority is a policy consumer of the same hierarchy - [Scope track priority](/quest/m1/track-priority-scope.md) - owns the priority semantics this mechanism realizes, including the scheduling-domain scope +- [Signed priority](/quest/m2/signed-priority.md) - changes the priority type + this orders on; keep the ordering, not just the type diff --git a/quest/m1/quic/upstream.md b/quest/m1/quic/upstream.md index 294e9c0e44b..796f087fd93 100644 --- a/quest/m1/quic/upstream.md +++ b/quest/m1/quic/upstream.md @@ -16,7 +16,7 @@ release and its shape has stopped moving, split it into an upstream PR with the tests it landed with. Offer the seven BBR correctness fixes (moq-noq 1.3.1, #4206) and -their [loss](/quest/m1/quic/bbr-loss-parity.md) and +their [loss](/quest/m2/quic-bbr-loss-parity.md) and [starvation](/quest/m1/quic/bbr-app-limited-edges.md) follow-ups with their regressions before promoting BBR as the default. Reuse existing upstream work, particularly [PR #802](https://github.com/n0-computer/noq/pull/802), @@ -34,42 +34,39 @@ Then the feature proposal order, each linked to its producing quest: since it adopted noq): a one-line change whose point is that every noq and iroh user, the maintainers included, runs the controller MoQ depends on, so its regressions are found upstream and not only here; -1. per-stream acknowledgment progress ([ACK progress](/quest/m1/quic/ack-progress.md)); +1. per-stream acknowledgment progress ([ACK progress](/quest/m2/quic-ack-progress.md)); 2. `RESET_STREAM_AT` ([reliable reset](/quest/m1/quic/reliable-reset.md)); 3. hierarchical send groups ([scheduler](/quest/m1/quic/scheduler.md)); -4. per-stream deadlines ([deadlines](/quest/m1/quic/deadline.md)); -5. the qmux crate over the shared stream state machine ([qmux](/quest/m1/quic/qmux.md)). +4. per-stream deadlines ([deadlines](/quest/m2/quic-deadline.md)); +5. the qmux crate over the shared stream state machine ([qmux](/quest/m2/quic-qmux.md)). -The m2 features (keep-alive by deadline, careful resume as a `Controller` +Items 1, 4, and 5 moved to m2 in the 2026-09-30 audit; like the other m2 +features they are offered when they land and do not gate this quest. The +other m2 features (keep-alive by deadline, careful resume as a `Controller` wrapper, ECT(1) marking, the media-headroom mechanism) are offered when they land, but do not gate this quest: an m1 quest must not wait on m2 work. The -next experiments (receive timestamps, GCC, FEC, kernel pacing, send -batching, buffer pools, the natural-drain check) join the list only with a +next experiments (receive timestamps, GCC, the egress profile, the +natural-drain check) join the list only with a positive verdict. Record in this quest what upstream accepted, what it asked to see as an extension crate, and what it declined; a declined change stays in the fork -with the link beside it. The quest completes when the list above has been -offered and answered. +with the link beside it. The quest completes when the m1 items above have +been offered and answered. ## Required -- [Align BBR loss handling with draft-06](/quest/m1/quic/bbr-loss-parity.md) - [Mark BBR starvation wherever the source runs dry](/quest/m1/quic/bbr-app-limited-edges.md) - -- [Per-stream ACK progress](/quest/m1/quic/ack-progress.md) - [Reliable stream reset](/quest/m1/quic/reliable-reset.md) - [Hierarchical stream scheduling](/quest/m1/quic/scheduler.md) -- [Per-stream deadlines](/quest/m1/quic/deadline.md) -- [qmux on the QUIC stream state machine](/quest/m1/quic/qmux.md) ## Related -- [Receive timestamps](/quest/m2/quic-receive-ts.md), [GCC](/quest/m2/quic-gcc.md), - [FEC](/quest/m2/quic-fec.md), [Natural media drains](/quest/m2/quic-bbr-natural-drain.md) - - experiments that join the list with a positive verdict - [Keep-alive by deadline](/quest/m2/quic-keep-alive.md), [Careful resume on reconnect](/quest/m2/quic-careful-resume.md), [L4S on the backbone](/quest/m2/quic-ecn.md), [Discover media headroom](/quest/m2/quic-probe.md) - m2 features offered upstream when they land +- [BBR media study](/quest/m2/quic-bbr-natural-drain.md), + [Receive timestamps](/quest/m3/quic-receive-ts.md), [GCC](/quest/m3/quic-gcc.md) - + experiments that join the list with a positive verdict diff --git a/quest/m1/quic/uring-close.md b/quest/m1/quic/uring-close.md index f3ac2ab58f1..68971a73f69 100644 --- a/quest/m1/quic/uring-close.md +++ b/quest/m1/quic/uring-close.md @@ -16,3 +16,9 @@ Reproduce on a Linux kernel supporting the io_uring worker, both in isolation and alongside the full test suite. Determine where the final close is lost between QUIC output, UDP submission, and worker teardown. Preserve the existing close contract; do not mask the failure with a retry or a longer timeout. + +## Plan + +#4431 (2f4b78581) fixed the same root cause, a paced CONNECTION_CLOSE lost +at teardown. Re-run this test under the #4431 stress setup (8 stress-ng hogs +on one CPU); if it passes, delete this quest. diff --git a/quest/m1/raw-stream-codes.md b/quest/m1/raw-stream-codes.md index f4e50e3373d..7ddf9891e32 100644 --- a/quest/m1/raw-stream-codes.md +++ b/quest/m1/raw-stream-codes.md @@ -15,9 +15,9 @@ on stream errors. WebTransport sessions keep the mapping they need. `web-transport-iroh` and `web-transport-quinn` (moq-dev/web-transport) do the same. A raw peer's code 5 reads as `None` or another value, and ours reaches it as a large HTTP/3 code. -- [Close codes](/quest/m1/close-codes.md) fixes the same mix-up for - `ApplicationClosed` (noq#11 is released; #4262 is still open on `dev`, so - this follows it there unless trait 0.5 reaches main first). Let each stream know whether its +- Close codes (#4262, merged on `dev` 09-28) fixed the same mix-up for + `ApplicationClosed` and brought `web-transport-trait` 0.5, which exists + only on `dev`, so this targets `dev`. Let each stream know whether its session is raw and skip the mapping there, in all three adapters, with a round-trip test per adapter against a plain QUIC peer. - Release the fixed crates and bump the pins here in the same quest; published @@ -33,11 +33,7 @@ on stream errors. WebTransport sessions keep the mapping they need. a legacy-sender test per adapter. The other direction has no fix at the receiver: an older peer misreads a fixed peer's raw codes. Check which codes moq-net acts on (group stream resets, subscribe STOP_SENDING): if any drives - behaviour beyond reporting, this is a wire break and retargets to `dev`. + behaviour beyond reporting, this is a wire break as well. Public API: none expected. Wire: raw QUIC stream error codes become the application's own values; compatible only if older peers merely report them. - -## Required - -- [Close codes](/quest/m1/close-codes.md) - the adapter releases and trait 0.5 this builds on diff --git a/quest/m1/relay-auth-client-ca.md b/quest/m1/relay-auth-client-ca.md index 34623934296..3dec1299618 100644 --- a/quest/m1/relay-auth-client-ca.md +++ b/quest/m1/relay-auth-client-ca.md @@ -10,7 +10,8 @@ config instead of quietly refusing every session. ## Plan -- [#4364](https://github.com/moq-dev/moq/pull/4364) adds an additive +- [#4364](https://github.com/moq-dev/moq/pull/4364) (merged 09-28, and + `dev` has merged `main` since) added an additive `Config::validate_client_ca(&self, client_ca: bool)` that `Relay::load` and the CLI must each remember to call; the CLI missing the original check is the bug it fixes. Fold it into `validate(&self, client_ca: bool)` so every @@ -34,8 +35,3 @@ config instead of quietly refusing every session. Public API: breaks `moq_relay::auth::Config::validate` and `init`, removes `validate_client_ca`, so this targets `dev`. Wire: none. - -## Required - -- #4364 merged to `main` -- `dev` has merged `main` after #4364 lands diff --git a/quest/m1/relay-iroh-opt-in.md b/quest/m1/relay-iroh-opt-in.md index 51e2fa9b54e..522796d96f4 100644 --- a/quest/m1/relay-iroh-opt-in.md +++ b/quest/m1/relay-iroh-opt-in.md @@ -26,5 +26,5 @@ Guidance: ## Related -- [`moq relay`](/quest/m1/moq-relay-subcommand.md) - forwards the relay's features from moq-cli's -- [P2P](/quest/m1/p2p/README.md) - why moq-cli keeps iroh +- [`moq relay`](/quest/m2/moq-relay-subcommand.md) - forwards the relay's features from moq-cli's +- [P2P](/quest/m2/p2p/README.md) - why moq-cli keeps iroh diff --git a/quest/m1/relay-memory.md b/quest/m1/relay-memory.md deleted file mode 100644 index b4d90377025..00000000000 --- a/quest/m1/relay-memory.md +++ /dev/null @@ -1,41 +0,0 @@ -# [S] Relay memory per announcement - -## Goal - -A relay's memory scales with what it serves, not with what the mesh knows, -and the numbers behind that claim are current. Two costs to keep apart when -measuring: the route table and per-announcement state (`RouteEntry` plus -`ServeState`) scale with announcements and routes, while the served-content -cache a `ServeState` materializes scales with demand. - -## Plan - -Every published figure predates two changes and is untrustworthy: - -- [moq#2989](https://github.com/moq-dev/moq/pull/2989) cut `kio`'s inline - waiter slots from 32 to 4, so a `kio::State<()>` went from 896 B to about - 200 B. Going lower trades memory for an allocation per wake, which - `kio`'s `tests/waiter_allocs.rs` pins; that lever is spent. -- [moq#3225](https://github.com/moq-dev/moq/pull/3225) made a received - announcement a `RouteEntry` plus one `ServeState` whose cache materializes - a broadcast only when something requests a path. A standby route is a - table entry, not an object graph, so degree stopped being a multiplier. - -The old baseline was 8.8 KB per announced broadcast plus 4.3 KB per extra -route on `adad52b`, measured with two throwaway `moq-net` examples driving an -origin under a counting allocator and reading `/proc/self/statm`. Neither is -committed, since they need `#[doc(hidden)]` size probes on private types. -Rebuild them from this description and restate the per-broadcast and -per-route cost, the per-peer session bookkeeping (`announce_ids`, `held`, -`watched`), and the shed threshold on a degree-5, 1 GB node, before anyone -quotes a number again. Chat-shaped traffic (one broadcast per channel or -per chatter) depends on the answer. - -On-demand announcements are now [Cluster routing](/quest/m1/cluster-routing.md)'s -plan: a relay learns only the prefixes its own clients request, which bounds -the table by demand. These numbers size that saving. - -## Related - -- [Cluster routing](/quest/m1/cluster-routing.md) - on-demand announcements shrink the table this measures -- [Perf](/quest/m1/perf/README.md) - the hot-path work that owns the remaining per-cell cost diff --git a/quest/m1/remove-live.md b/quest/m1/remove-live.md deleted file mode 100644 index 80be20255df..00000000000 --- a/quest/m1/remove-live.md +++ /dev/null @@ -1,49 +0,0 @@ -# [M] Importers publish stream timestamps; the catalog clock maps them to wall - -## Goal - -The fMP4, MPEG-TS, and FLV importers in `rs/moq-mux` have no `live()`: every -importer publishes the stream's own timestamps verbatim (after PTS unwrap), -and the catalog's root `clock` is what maps them to wall time. `moq import` -(`rs/moq-cli/src/publish.rs`) stops calling it. An encoder that restarts its -timestamps ends the broadcast with an error instead of being re-anchored -forward onto the old one; turning the republish into a new epoch is the -broadcast epoch line's outcome, not this quest's. The SRT, RTMP, and HLS gateways, which reuse these -importers, get the same behavior. - -## Plan - -Decided (2026-09-28, replacing the gateway live-clock quest, which planned -the opposite: every gateway opting into `live()`): - -- Timestamps stay verbatim from the stream. Rewriting them onto an - arrival-time anchor breaks same-hop importers, which must derive every - timestamp from the input alone (the hop-aligned import quest in - [#4388](https://github.com/moq-dev/moq/pull/4388)), and hides the source's - own timeline from anything downstream. -- The catalog clock carries the mapping. An importer establishes the root - `clock` so the stream's PTS converts to wall time (the first frame is live - on arrival), rather than translating each timestamp. Open: whether the - importer sets the catalog clock from its first frame (the mapping is fixed - at construction today, `moq_mux::Clock` and `catalog::Config::with_clock`) - or the caller builds the catalog once the first PTS is known. Every track of - one input, and every rendition of one HLS import, shares that one mapping. -- An encoder restart (a PTS rewind or a signalled time-base discontinuity) is - a new epoch, not a forward re-anchor: the importer ends the broadcast with - an error, and the caller republishes, which the broadcast epoch line turns - into a fresh `@`. Until that line lands, a restart fails loud. -- Delete `live()` from `ts::Import`, `fmp4::Import`, and `flv::Import`, the - crate-private `clock::Anchor`, and `SourceMap` if nothing else uses it. - fMP4 passthrough stops rewriting `tfdt`. A published `moq-mux` API break, - so this targets `dev`. - -Tests: per importer, a source starting at a large PTS publishes that PTS and -a catalog clock that maps it to near the arrival time; a rewind ends the -broadcast with an error. Update `doc/lib/rs/moq-mux.md` (the `live()` -paragraph), `doc/bin/cli.md`, and the gateway pages under `doc/bin/`, and -replace `ts_import_publishes_on_the_broadcast_clock` in moq-cli. - -## Related - -- [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - the new epoch an encoder restart becomes -- [TS import shared shift](/quest/m1/ts-import-shared-shift.md) - the TS re-anchor shift that must stay input-derived diff --git a/quest/m1/resume-latest.md b/quest/m1/resume-latest.md index fb878c5c1aa..3949bfec69e 100644 --- a/quest/m1/resume-latest.md +++ b/quest/m1/resume-latest.md @@ -71,3 +71,5 @@ Regression tests, on a paused clock (`#[tokio::test(start_paused = true)]`): ## Related - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - tells a resumed latest group when the new copy dropped it +- [Parked reads wake](/quest/m1/parked-read-wakes.md) - edits the same `resume.rs` wakeups; lands after this quest's #4491 +- [#2991](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - extends the same `resume.rs` takeover tests diff --git a/quest/m1/rs2ts/README.md b/quest/m1/rs2ts/README.md index e37edf9eb0b..b89bcd59c4e 100644 --- a/quest/m1/rs2ts/README.md +++ b/quest/m1/rs2ts/README.md @@ -5,7 +5,7 @@ moq-net is the single implementation of the MoQ protocol and model layer. The browser runs it as TypeScript generated from the Rust source, retiring js/net's hand-written equivalent with no regression in bundle size, CPU, or -usability. Lite comes first, IETF after. Transport glue (the WebTransport and +usability. Lite is this line; IETF follows in m2. Transport glue (the WebTransport and WebSocket pumps, timers) stays hand-written TypeScript. ## Plan @@ -48,18 +48,29 @@ Decided in planning (2026-09-27), with the spike data in - Hand-written js/net fixes keep landing until the generated path replaces them; it is months out. +Decided in the 2026-09-30 audit: the lite half stays in m1 with an explicit +go/no-go after the no-downgrade report below; a no-go stops the line before +anything else is generated. The IETF half (the sans-IO IETF session, +generated IETF, and the IETF parameters quest on this line's branch) moved to +m2 and waits on that go. + +PR #4455 (branch `quest/m1/rs2ts/lite-leading-ones`) changes the lite-07 +varint wire and no quest tracks it; it coordinates with +[subscribe drop](/quest/m1/subscribe-drop.md)'s lite-07 edits. + This README's own work is the no-downgrade report once generated lite ships: bundle size, per-frame CPU, and first-frame latency against the hand-written js/net it replaces, measured with the [browser benchmarks](/quest/m1/browser-benchmarks.md). ## Required +- [Browser benchmarks](/quest/m1/browser-benchmarks.md) - the harness the no-downgrade report uses + - [VarInt codec](/quest/m1/rs2ts/varint-codec.md) - moq-net encodes through a `VarInt` newtype and a concrete slice-based codec, not generic traits on primitives - [rs2ts](/quest/m1/rs2ts/translator.md) - a Charon-based translator emits readable TypeScript for moq-net's lite codec, committed and checked for drift in CI - [Sans-IO moq-net](/quest/m1/rs2ts/sans-io/README.md) - moq-net builds and runs without a runtime; async helpers sit behind an `async` feature - [Mock-clock tests](/quest/m1/rs2ts/mock-clock.md) - moq-net's tests run on the sans-IO clock instead of tokio, so they translate with the code - [Generated lite](/quest/m1/rs2ts/lite.md) - @moq/net's lite session and model layer are generated from moq-net -- [Generated IETF](/quest/m1/rs2ts/ietf.md) - @moq/net's moq-transport session is generated too - [Remove moq-wasm](/quest/m1/rs2ts/remove-wasm.md) - the WASM experiment is deleted once generated lite ships ## Closes @@ -68,10 +79,7 @@ js/net it replaces, measured with the [browser benchmarks](/quest/m1/browser-ben - [#2822](https://github.com/moq-dev/moq/issues/2822) - close this issue when the quest finishes - [#2835](https://github.com/moq-dev/moq/issues/2835) - close this issue when the quest finishes -## Required - -- [Browser benchmarks](/quest/m1/browser-benchmarks.md) - the harness the no-downgrade report uses - ## Related -- [#2850](/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md) - the same synchronous decode shape, in hand-written js/net today +- [#2850](/quest/m1/2850-js-net-give-reader-a-synchronous-decode-so-the-publisher.md) - caps hand-written js/net's subscription controls; generated lite replaces the rest +- [Generated IETF](/quest/m2/rs2ts-ietf.md) - the IETF half, deferred to m2 until the lite go/no-go diff --git a/quest/m1/rs2ts/sans-io/README.md b/quest/m1/rs2ts/sans-io/README.md index 03a4cfb82be..a74c9af8bb6 100644 --- a/quest/m1/rs2ts/sans-io/README.md +++ b/quest/m1/rs2ts/sans-io/README.md @@ -13,11 +13,16 @@ reimplements the async helpers natively with Promises, so the translator reads the crate without the `async` feature. Split by layer so each lands on `dev` independently. -The line has no work of its own beyond its children. +The line has no work of its own beyond its children. Decided in the +2026-09-30 audit: the IETF session moved to m2 with the rest of the IETF +half; this line is lite and the model only. ## Required - [Sans-IO lite session](/quest/m1/rs2ts/sans-io/lite.md) - the lite session is driven by bytes, stream events, and `tick(now)` - [Sans-IO model](/quest/m1/rs2ts/sans-io/model.md) - origin, broadcast, track, and group handles run without a runtime, with time supplied by the caller - [The async feature](/quest/m1/rs2ts/sans-io/async-feature.md) - the async helpers sit behind an `async` feature and a CI lane builds and tests moq-net without it -- [Sans-IO IETF session](/quest/m1/rs2ts/sans-io/ietf.md) - the moq-transport session is driven the same way as lite + +## Related + +- [Sans-IO IETF session](/quest/m2/rs2ts-sans-io-ietf.md) - the moq-transport session, deferred to m2 diff --git a/quest/m1/rs2ts/sans-io/async-feature.md b/quest/m1/rs2ts/sans-io/async-feature.md index f7b7e350465..586cc5309e3 100644 --- a/quest/m1/rs2ts/sans-io/async-feature.md +++ b/quest/m1/rs2ts/sans-io/async-feature.md @@ -11,7 +11,7 @@ crate that [Generated lite](/quest/m1/rs2ts/lite.md) translates. - The feature is on by default, so Rust callers see no change. JS reimplements the helpers with Promises over the poll API. - Generated lite needs the lite session and the model without the feature, - not IETF. Until the [Sans-IO IETF session](/quest/m1/rs2ts/sans-io/ietf.md) + not IETF. Until the [Sans-IO IETF session](/quest/m2/rs2ts-sans-io-ietf.md) lands, the IETF session can sit behind the feature too; that quest then moves it out. - The lane runs at least the tests that do not exercise the helpers; tests diff --git a/quest/m2/serve-hls-renditions.md b/quest/m1/serve-hls-renditions.md similarity index 100% rename from quest/m2/serve-hls-renditions.md rename to quest/m1/serve-hls-renditions.md diff --git a/quest/m1/session-close.md b/quest/m1/session-close.md deleted file mode 100644 index 1ac4d9d92ee..00000000000 --- a/quest/m1/session-close.md +++ /dev/null @@ -1,34 +0,0 @@ -# [M] Graceful session close withdraws announces - -## Goal - -Ending a session on purpose withdraws the namespaces it published and waits -for the peer to acknowledge that, up to one second. `abort`, and dropping the -last handle, still end the session immediately and do not wait. - -## Plan - -Rust has `abort` and drop, and both end the session now. Drop sends a bare -`Cancel`, so `PUBLISH_NAMESPACE_DONE` never goes out. -`moq_net::Session::close()` and `moq_tokio::Connection::close()` already -exist: they wait up to `CLOSE_TIMEOUT` (one second, in `moq-net`'s -`session.rs`) for finished tracks to deliver, then end the session, returning -`Error::Timeout` if the peer was too slow. Extend that drain phase to -unannounce what this session published and wait for the acknowledgements, -under the same deadline. Only moq-lite drains today; IETF sessions close at -once. - -JS `Established.close()` is synchronous today. It becomes the same graceful -end and returns a promise, which is a published break, so that change targets -`dev`. `abort` stays immediate in both languages. - -`doc/concept/moq-lite.md` says a graceful close withdraws announces and an -abort does not. No new page. - -The interop runner is the consumer that found this -([#4209](https://github.com/moq-dev/moq/pull/4209)): after a successful -publish it calls `abort`, so the relay never sees `PUBLISH_NAMESPACE_DONE` and -the next run is told the namespace is already published. Switch it to the -graceful `close()` once that exists. If the calling code lives outside this -repository (moq-interop-runner), that change is a PR there and needs the -maintainer's approval before posting. diff --git a/quest/m1/session-death.md b/quest/m1/session-death.md index af67ddd7151..2d848eebcf1 100644 --- a/quest/m1/session-death.md +++ b/quest/m1/session-death.md @@ -40,7 +40,3 @@ Extend the existing session-death tests (Rust integration cases) with a local close and with a group reader, on lite and IETF. Behavior change, no signature change on either side unless the Rust clean end needs a public method. - -## Related - -- [Graceful session close](/quest/m1/session-close.md) - what a local close sends the peer diff --git a/quest/m1/stats-producer-bench.md b/quest/m1/stats-producer-bench.md deleted file mode 100644 index 869404f06b3..00000000000 --- a/quest/m1/stats-producer-bench.md +++ /dev/null @@ -1,33 +0,0 @@ -# [S] Stats producer fan-out benchmark - -## Goal - -A `moq-stats` benchmark measures what one relay pays per stats tick to drain -its registry and encode the traffic tracks, swept over held paths and tiers, -so a cost that grows with the whole table instead of the paths that changed -shows up as a slope. It runs at least nightly. - -## Plan - -- [#4299](https://github.com/moq-dev/moq/pull/4299) keeps an idle path in - every frame while the registry holds its counters, adding about 430 B per - idle path to each plain frame (maintainer's note on the PR). Nothing - measures what that, or the per-tick drain, costs as held paths grow. - `rs/moq-stats/benches/decode.rs` covers only the reader. -- Sweep held paths (for example 100 to 50k) against tiers, and the share of - paths that are idle versus changed this tick. Report time and allocations - per tick, and plain and compressed bytes per frame, the way `decode.rs` - reports its table. Include the point where a plain frame nears its size - cap, since a frame that is too large leaves stale counters behind. -- Drive the real producer path (`process_slot`, the snapshot encoders) over - a synthetic `Registry`, not a re-implementation of it. Exposing a bench - hook is fine if it stays out of the public API. -- `decode.rs` is not in CI either. Run both targets once in the nightly - benchmark smoke, as `moq-net`'s are. - -Public API: none. Wire: none. - -## Related - -- [Binary delta stats flavor](/quest/m2/stats-delta.md) - its gate needs the encode baseline this measures -- [Benchmark regressions in CI](/quest/m1/bench-ci.md) - compares these targets across PRs once it lands diff --git a/quest/m1/stats/README.md b/quest/m1/stats/README.md index 24828d41bce..3bd008a5b29 100644 --- a/quest/m1/stats/README.md +++ b/quest/m1/stats/README.md @@ -7,8 +7,7 @@ that wants to hear from its viewers can solicit feedback there too. The publisher's `stats` track is one snapshot of what it sent, per rendition and for its connection. A viewer publishes one `.echo` broadcast per soliciting catalog it reads, carrying what it received and played, per rendition, and -its own connection. A dashboard reads both the same way a publisher does, and -a Rust encoder adapts its bitrate to what its viewers report. Stats and +its own connection. A dashboard reads both the same way a publisher does. Stats and feedback cost nothing on the network unless someone subscribes. Not here: the relay's `moq-stats` layout, which stays as it is; clock synchronization; any requirement that a client report; and feedback as an input to billing, @@ -68,10 +67,7 @@ kind. request API. - **Trust is the token prefix** (2026-09-29). Whoever the application's tokens let publish under the echo path may report, and no report is - authenticated beyond that. How far one viewer may move the encoder is - application-specific (a simulcast ladder suffers less from one viewer than - a single rendition), so the encoder's built-in step-down policy takes a - tunable config that the application can adjust or disable. + authenticated beyond that. - **Feedback track: one snapshot**, `{ transport, renditions: { : echo::Track } }`, so the publisher looks up its own renditions directly. - **One type per role, shared across kinds.** @@ -97,22 +93,9 @@ kind. `doc/concept/stats.md` gains a media section beside the relay's, and `drafts/draft-lcurley-moq-hang.md` specs the wire. -Open, to settle before [encoder feedback](/quest/m1/stats/encoder-feedback.md) -starts: - -- **Referenced-rendition feedback.** A derivative catalog (a `moq-transcode` - passthrough) collects feedback for a source rendition it lists, but owns - no encoder for it, and the source encoder reads only its own catalog's - prefix. Candidates: the derivative forwards those rows to the source's - echo path, or the source encoder also reads catalogs that reference it, - or referenced renditions stay report-only. -- **Shared echo prefixes.** Two catalogs can resolve their echo paths to one - prefix (`../viewers` from `room/a/live` and `room/b/live`). Then a viewer - using one name for both closes one `.echo` with the other, and each - publisher reads the other's reports under a shared alias. Candidates: - require each catalog's echo prefix to be its own, as application policy - like the token rights, or carry the catalog's broadcast in the snapshot - and ignore reports for another. +Decided in the 2026-09-30 audit: a Rust encoder adapting its bitrate to viewer +feedback moved to [encoder feedback](/quest/m2/stats-encoder-feedback.md) (m2), +along with its open questions. This line only publishes and reads the reports. ## Required @@ -124,10 +107,10 @@ starts: moq-mux remuxes publish stats and feedback - [Browser reporters](/quest/m1/stats/js.md) - `` publishes stats and `` publishes feedback -- [Encoder feedback](/quest/m1/stats/encoder-feedback.md) - a Rust encoder - reads its viewers' feedback and adapts its bitrate ## Related - [QoS](/quest/m1/qos/README.md) - the relay's delivery counters, the other half of a health verdict +- [Encoder feedback](/quest/m2/stats-encoder-feedback.md) - a Rust encoder + adapts its bitrate to what its viewers report diff --git a/quest/m1/subscribe-drop.md b/quest/m1/subscribe-drop.md index ecd671811c5..a74d3596df7 100644 --- a/quest/m1/subscribe-drop.md +++ b/quest/m1/subscribe-drop.md @@ -47,6 +47,17 @@ Regression tests: a publisher that expires a group, skips a sequence, and resets a stream before its header; on each version the subscriber settles without waiting out the grace. +Add the lite-07 drop case to the tail interop harness from +[track tail interop](/quest/m1/track-tail-interop.md): Rust and JS +subscribers both settle on SUBSCRIBE_DROP through the relay, so a group the +publisher skipped or never opened ends the track without waiting out the +grace. Decided in the 2026-09-30 audit: the case moved here so the basic +tail interop could land first. + +PR #4455 (`quest/m1/rs2ts/lite-leading-ones`) also edits the lite-07 wire +(varints) and no quest tracks it; coordinate the draft's lite-07 changelog +with it. + ## Related -- [Track tail interop](/quest/m1/track-tail-interop.md) - the Rust-JS proof of the lite-07 drop case +- [Track tail interop](/quest/m1/track-tail-interop.md) - the Rust-JS tail harness the lite-07 drop case extends diff --git a/quest/m1/test-flakes-2.md b/quest/m1/test-flakes-2.md deleted file mode 100644 index a5941853f93..00000000000 --- a/quest/m1/test-flakes-2.md +++ /dev/null @@ -1,90 +0,0 @@ -# [S] More tests hold up under load - -## Goal - -A second round after [#4286](https://github.com/moq-dev/moq/pull/4286): -tests that pass alone but have failed under a loaded `just check` pass -reliably, each fixed at its cause, never by raising a timeout or adding a -retry. - -- moq-cli `fetch::tests::a_frame_read_times_out` asserts on a 500 ms wall - deadline ([#4084](https://github.com/moq-dev/moq/pull/4084)). The cause - (#4431): `rs/moq-cli/src/fetch.rs` wraps the whole run in one - `timeout_at(deadline, ...)`, so connect, TLS, announce, and subscribe share - the budget with the read, and under load setup alone can spend it. -- moq-cli `complete::tests::a_stage_broadcast_picks_the_catalog_to_read` - ([#4084](https://github.com/moq-dev/moq/pull/4084)), - `the_catalog_format_on_the_line_is_honored` - ([#4089](https://github.com/moq-dev/moq/pull/4089)), and - `a_relay_on_the_line_answers_broadcast`: both of the latter pair came back - empty after the fixed 1.5 s `CEILING` on a loaded runner - ([#4404](https://github.com/moq-dev/moq/pull/4404)). -- moq-net `model::group::test::drop_unfinished_warns` counts WARNs through a - global tracing capture, so another test's WARN, or a missed one, changes - the count ([#4104](https://github.com/moq-dev/moq/pull/4104)). The - `model::track` test of the same name uses the same helper. -- moq-tokio `broadcast_race_quic_wins` binds TCP `:0` and then UDP on the - same number, which nothing reserves: the collision - [#4084](https://github.com/moq-dev/moq/pull/4084) removed from its sibling - after [#4055](https://github.com/moq-dev/moq/pull/4055) papered over it with - a retry. -- moq-tokio - `subscription_end_integrity::a_subscription_cut_by_the_publisher_disconnecting_does_not_end_clean` - ends `Ok(None)` with 10 of 20 frames in 3 of 8 full-suite runs on a clean - tree, and passes alone (#4332). -- `just test media` late join failed once after - [#4181](https://github.com/moq-dev/moq/pull/4181): "joined at frame 111, 16 - frames behind 127", against a budget of one GOP (15). -- js/publish audio encoder test "a rendition trailing the broadcast's - earliest advertises delay" reads the real clock, so it fails when its file - runs alone (timestamps go negative early in the process) (#4414). Mock time. -- moq-mux `container::ts::export_test::debounce_opens_without_a_media_clock` - died with SIGTERM once in a combined run. It is marked - `start_paused = true` but sleeps 1.2 s of real time, because the debounce - reads `crate::Clock`, which uses `std::time::Instant`, so the paused tokio - clock never reaches it. -- moq-tokio websocket `fixed_addresses_keep_tls_name_and_request_host` and - `ipv6_literal_fixed_addresses` pause the clock over a real TLS dial on - loopback. They pass today, but once a timeout lands on that path, the paused - clock can fire it before loopback delivers, the race - [#4527](https://github.com/moq-dev/moq/pull/4527) removed from the auth - outage tests. - -## Plan - -- Timing tests: prefer a paused clock over wall time (`moq-cli`'s - subscribe tests already use `#[tokio::test(start_paused = true)]`), or - assert on an event instead of a deadline. If a test is slow under load - because the code under test is slow, fix that. -- Fetch timeout: test on a paused clock (maintainer decision, 2026-09-28). - The fixture runs real sockets against an in-process relay, where a paused - clock fires QUIC timers while packets are in flight, so first make the - timers mockable: run the fixture over an in-memory transport, or drive - noq's timers from the test clock, whichever is smaller. Keep the one - absolute 30 s deadline, matching the relay's `/fetch`; on a paused clock - setup costs no time, so it can't spend the read's budget. -- moq-mux debounce: let the test drive `crate::Clock`'s time (a tokio - `Instant` under test, or an injected source) so the window passes on the - paused clock, and drop the real sleep. -- WARN counting: capture per test (a scoped subscriber or a filter on the - test's own span) instead of a process-global count. -- The race test shares one port only so both transports sit behind one URL. - Separate `:0` ports fix the bind collision but not the race itself: with - `websocket.delay = 0` either arm can legitimately win under load. Make the - order deterministic the way #4084 did, holding the WebSocket arm until QUIC - has connected, rather than asserting on a real race; no retry. #4084's follow-ups - (`tests/reconnect.rs` `spawn_server`, `tests/worker.rs` `free_udp_port`) - are the same probe-and-rebind pattern; fix them here if cheap. -- Media late join: first decide whether 16 frames is a real regression (the - player joining at the previous GOP's keyframe) or an off-by-one in how the - fixture samples the live edge. Fix whichever it is; don't widen the - budget without a reason. -- Prove it by running `just check --all` several times on a loaded machine, - as the first round did. - -Public API: none. Wire: none. - -## Related - -- [Archive enrollment](/quest/m1/archive/enrollment-flake.md) - the same - kind of flake on the archive line, where its test lives diff --git a/quest/m1/test-flakes-2/README.md b/quest/m1/test-flakes-2/README.md new file mode 100644 index 00000000000..c48c60452bf --- /dev/null +++ b/quest/m1/test-flakes-2/README.md @@ -0,0 +1,46 @@ +# More tests hold up under load + +## Goal + +A second round after [#4286](https://github.com/moq-dev/moq/pull/4286): +tests that pass alone but have failed under a loaded `just check` pass +reliably, each fixed at its cause, never by raising a timeout or adding a +retry. + +## Plan + +Decided in the 2026-09-30 audit: the round held independent flakes in one +quest, so it split into one child per flake, grouping only those that share +a fixture. Each child lands on its own. + +Rules every child keeps: + +- Prefer a paused clock over wall time (`moq-cli`'s subscribe tests already + use `#[tokio::test(start_paused = true)]`), or assert on an event instead + of a deadline. If a test is slow under load because the code under test is + slow, fix that. +- A paused clock auto-advances while the runtime idles, so it can fire a + timer before a real socket delivers. Where real sockets fight the paused + clock, make the timers mockable or move the test off real sockets. + +This README's own work, after the children: run `just check --all` several +times on a loaded machine, as the first round did. + +Public API: none. Wire: none. + +## Required + +- [moq-cli tests on a paused clock](/quest/m1/test-flakes-2/cli-paused-clock.md) - the fetch timeout and completion tests stop racing wall-clock budgets +- [Subscription cut by disconnect](/quest/m1/test-flakes-2/subscription-cut.md) - a publisher disconnect never ends a subscription clean +- [Broadcast race](/quest/m1/test-flakes-2/broadcast-race.md) - the QUIC-wins race test binds no shared port and has a deterministic winner +- [Media late join](/quest/m1/test-flakes-2/media-late-join.md) - `just test media` late join stays within one GOP, or the regression is fixed +- [Shaper virtual time](/quest/m1/test-flakes-2/shaper-virtual-time.md) - `moq-shaper` tests judge seeded decisions on paused time, not on wall-clock delivery under load +- [Scoped WARN capture](/quest/m1/test-flakes-2/warn-capture.md) - the drop-unfinished tests count only their own WARNs +- [moq-mux debounce clock](/quest/m1/test-flakes-2/mux-debounce-clock.md) - the TS export debounce test advances on the paused clock +- [js/publish audio clock](/quest/m1/test-flakes-2/publish-audio-clock.md) - the audio encoder delay test runs on mock time +- [WebSocket paused TLS dial](/quest/m1/test-flakes-2/websocket-paused-tls.md) - the fixed-address WebSocket tests stop pausing the clock over a real dial + +## Related + +- [Archive enrollment](/quest/m1/archive/enrollment-flake.md) - the same + kind of flake on the archive line, where its test lives diff --git a/quest/m1/test-flakes-2/broadcast-race.md b/quest/m1/test-flakes-2/broadcast-race.md new file mode 100644 index 00000000000..36b0ddf1850 --- /dev/null +++ b/quest/m1/test-flakes-2/broadcast-race.md @@ -0,0 +1,22 @@ +# [S] Broadcast race without a shared port + +## Goal + +moq-tokio `broadcast_race_quic_wins` binds no port it didn't reserve and +has a deterministic winner. + +## Plan + +It binds TCP `:0` and then UDP on the same number, which nothing reserves: +the collision [#4084](https://github.com/moq-dev/moq/pull/4084) removed from +its sibling after [#4055](https://github.com/moq-dev/moq/pull/4055) papered +over it with a retry. + +The test shares one port only so both transports sit behind one URL. +Separate `:0` ports fix the bind collision but not the race itself: with +`websocket.delay = 0` either arm can legitimately win under load. Make the +order deterministic the way #4084 did, holding the WebSocket arm until QUIC +has connected, rather than asserting on a real race; no retry. #4084's +follow-ups (`tests/reconnect.rs` `spawn_server`, `tests/worker.rs` +`free_udp_port`) are the same probe-and-rebind pattern; fix them here if +cheap. diff --git a/quest/m1/test-flakes-2/cli-paused-clock.md b/quest/m1/test-flakes-2/cli-paused-clock.md new file mode 100644 index 00000000000..f29e8ab11c5 --- /dev/null +++ b/quest/m1/test-flakes-2/cli-paused-clock.md @@ -0,0 +1,30 @@ +# [M] moq-cli tests on a paused clock + +## Goal + +The moq-cli fetch and completion tests pass under any host load: none of +them races a wall-clock budget against connect, TLS, announce, and +subscribe. + +## Plan + +- `fetch::tests::a_frame_read_times_out` asserts on a 500 ms wall deadline + ([#4084](https://github.com/moq-dev/moq/pull/4084)). + `rs/moq-cli/src/fetch.rs` wraps the whole run in one + `timeout_at(deadline, ...)`, so setup shares the budget with the read, and + under load setup alone can spend it. +- `complete::tests::a_stage_broadcast_picks_the_catalog_to_read` + ([#4084](https://github.com/moq-dev/moq/pull/4084)), + `the_catalog_format_on_the_line_is_honored` + ([#4089](https://github.com/moq-dev/moq/pull/4089)), and + `a_relay_on_the_line_answers_broadcast`: the latter pair came back empty + after the fixed 1.5 s `CEILING` on a loaded runner + ([#4404](https://github.com/moq-dev/moq/pull/4404)). + +Test on a paused clock (maintainer decision, 2026-09-28). The fixture runs +real sockets against an in-process relay, where a paused clock fires QUIC +timers while packets are in flight, so first make the timers mockable: run +the fixture over an in-memory transport, or drive noq's timers from the test +clock, whichever is smaller. Keep fetch's one absolute 30 s deadline, +matching the relay's `/fetch`; on a paused clock setup costs no time, so it +can't spend the read's budget. The completion tests reuse the same fixture. diff --git a/quest/m1/test-flakes-2/media-late-join.md b/quest/m1/test-flakes-2/media-late-join.md new file mode 100644 index 00000000000..c795da647c8 --- /dev/null +++ b/quest/m1/test-flakes-2/media-late-join.md @@ -0,0 +1,15 @@ +# [S] Media late join within one GOP + +## Goal + +`just test media` late join holds its one-GOP budget under load, or the +regression behind it is fixed. + +## Plan + +It failed once after [#4181](https://github.com/moq-dev/moq/pull/4181): +"joined at frame 111, 16 frames behind 127", against a budget of one GOP +(15). First decide whether 16 frames is a real regression (the player +joining at the previous GOP's keyframe) or an off-by-one in how the fixture +samples the live edge. Fix whichever it is; don't widen the budget without a +reason. diff --git a/quest/m1/test-flakes-2/mux-debounce-clock.md b/quest/m1/test-flakes-2/mux-debounce-clock.md new file mode 100644 index 00000000000..e29f84934b2 --- /dev/null +++ b/quest/m1/test-flakes-2/mux-debounce-clock.md @@ -0,0 +1,15 @@ +# [XS] moq-mux debounce test on the paused clock + +## Goal + +moq-mux `container::ts::export_test::debounce_opens_without_a_media_clock` +advances on the paused clock and sleeps no real time. + +## Plan + +It died with SIGTERM once in a combined run. It is marked +`start_paused = true` but sleeps 1.2 s of real time, because the debounce +reads `crate::Clock`, which uses `std::time::Instant`, so the paused tokio +clock never reaches it. Let the test drive `crate::Clock`'s time (a tokio +`Instant` under test, or an injected source) so the window passes on the +paused clock, and drop the real sleep. diff --git a/quest/m1/test-flakes-2/publish-audio-clock.md b/quest/m1/test-flakes-2/publish-audio-clock.md new file mode 100644 index 00000000000..ccc4becaadf --- /dev/null +++ b/quest/m1/test-flakes-2/publish-audio-clock.md @@ -0,0 +1,11 @@ +# [XS] js/publish audio delay test on mock time + +## Goal + +The js/publish audio encoder test "a rendition trailing the broadcast's +earliest advertises delay" passes when its file runs alone. + +## Plan + +It reads the real clock, so timestamps go negative early in the process and +it fails when run alone (#4414). Run it on mock time. diff --git a/quest/m1/shaper-virtual-time.md b/quest/m1/test-flakes-2/shaper-virtual-time.md similarity index 100% rename from quest/m1/shaper-virtual-time.md rename to quest/m1/test-flakes-2/shaper-virtual-time.md diff --git a/quest/m1/test-flakes-2/subscription-cut.md b/quest/m1/test-flakes-2/subscription-cut.md new file mode 100644 index 00000000000..8819c67ed95 --- /dev/null +++ b/quest/m1/test-flakes-2/subscription-cut.md @@ -0,0 +1,14 @@ +# [S] Subscription cut by publisher disconnect + +## Goal + +moq-tokio +`subscription_end_integrity::a_subscription_cut_by_the_publisher_disconnecting_does_not_end_clean` +passes in every full-suite run. + +## Plan + +It ends `Ok(None)` with 10 of 20 frames in 3 of 8 full-suite runs on a clean +tree, and passes alone (#4332). A clean end after a publisher disconnect is a +real bug if the code can produce it, not only a test race: reproduce under +load first, find which path reports the cut as a clean end, and fix it there. diff --git a/quest/m1/test-flakes-2/warn-capture.md b/quest/m1/test-flakes-2/warn-capture.md new file mode 100644 index 00000000000..d6f928e0c43 --- /dev/null +++ b/quest/m1/test-flakes-2/warn-capture.md @@ -0,0 +1,14 @@ +# [XS] Scoped WARN capture + +## Goal + +moq-net `model::group::test::drop_unfinished_warns` and the `model::track` +test of the same name count only the WARNs their own code emits. + +## Plan + +Both count WARNs through a global tracing capture, so another test's WARN, +or a missed one, changes the count +([#4104](https://github.com/moq-dev/moq/pull/4104)). Capture per test, with a +scoped subscriber or a filter on the test's own span, instead of a +process-global count. diff --git a/quest/m1/test-flakes-2/websocket-paused-tls.md b/quest/m1/test-flakes-2/websocket-paused-tls.md new file mode 100644 index 00000000000..d92b724882a --- /dev/null +++ b/quest/m1/test-flakes-2/websocket-paused-tls.md @@ -0,0 +1,14 @@ +# [XS] WebSocket fixed-address tests off the paused clock + +## Goal + +moq-tokio websocket `fixed_addresses_keep_tls_name_and_request_host` and +`ipv6_literal_fixed_addresses` no longer pause the clock over a real TLS +dial. + +## Plan + +They pass today, but they pause the clock over a real TLS dial on loopback. +Once a timeout lands on that path, the paused clock can fire it before +loopback delivers, the race [#4527](https://github.com/moq-dev/moq/pull/4527) +removed from the auth outage tests. Remove it the same way. diff --git a/quest/m1/track-demand.md b/quest/m1/track-demand.md deleted file mode 100644 index 6dc5cea5bcc..00000000000 --- a/quest/m1/track-demand.md +++ /dev/null @@ -1,22 +0,0 @@ -# [M] Track demand is watched through demand() alone - -## Goal - -In Rust and JS, a track's subscribers are watched only through its `Demand`: -`track::Producer` drops `is_used`/`used`/`unused` and every layer producer -built on a track (moq-json, moq-mux import, moq-audio, moq-binary) exposes -`demand()` instead of its own copies. Group and broadcast `used`/`unused` stay; -`Demand` is a track concept, and group demand drives fetch coalescing. - -## Plan - -About 150 call sites move, across moq-net, moq-mux, moq-json, moq-audio, -moq-binary, moq-relay, moq-transcode, moq-stats, and libmoq. Both waits -already surface the track's abort reason, so callers keep their errors. Keep -`abort_unused` if its race still needs an owner. JS mirrors the Rust shape in `js/net`. - -Lands on `dev` alongside the [FFI shape](/quest/m1/ffi-shape/README.md) -line, so moq-net breaks once. - -Public API: breaking in moq-net and the layer crates, and in `@moq/net`. Wire: -none. diff --git a/quest/m1/track-priority-scope.md b/quest/m1/track-priority-scope.md index 4e4552e4323..5e81a1a5219 100644 --- a/quest/m1/track-priority-scope.md +++ b/quest/m1/track-priority-scope.md @@ -57,6 +57,11 @@ Direction to settle in the draft first, then the code: or narrow the goal to subscription delivery. - Keep the current ranking: track priority, then subscription, then newest group; do not reintroduce a group-order direction knob. +- 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:48`). The + [ladder controller](/quest/m2/ladder/controller.md), now in m2, wants that + tiebreak; this quest owns the answer so the controller only consumes it. - A per-session cap on distinct ranks is a scheduling detail; whatever replaces the 255-entry sort must stay O(log n) per group under chat-shaped churn. @@ -77,3 +82,5 @@ change. - [Starvation](/quest/m1/qos/starvation.md) - the relay-side signal that shows a starved subscription +- [Signed priority](/quest/m2/signed-priority.md) - changes the priority type, + not which streams it competes with diff --git a/quest/m1/track-tail-interop.md b/quest/m1/track-tail-interop.md index 7e664668ffa..e31403931b7 100644 --- a/quest/m1/track-tail-interop.md +++ b/quest/m1/track-tail-interop.md @@ -24,23 +24,17 @@ What stood in the way when the Rust half landed: first frame. It needs a mode that reads a track to its end and reports how it ended and which groups it saw. -Also cover the drop case: +The harness exposed a relay start-floor defect: when a newer group arrives +first, earlier in-flight groups can be lost. #4387 fixed it (merged 09-28). -- On moq-lite-07 add a drop case: both subscribers settle on SUBSCRIBE_DROP, - so a group the publisher skipped or never opened ends the track without - waiting out the grace. lite-07 replaces the SUBSCRIBE_END stream count - (#4224) with it. -- The harness exposed a relay start-floor defect: when a newer group arrives - first, earlier in-flight groups can be lost. #4387 fixes it, so the drop - proof waits on it. +Decided in the 2026-09-30 audit: the lite-07 drop case moved into +[SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md)'s tests, so the basic Rust and +JS tail interop lands now instead of waiting on that [L] quest. QUIC on localhost rarely reorders, so this is a smoke check that the end is delivered and clean. The ordering race itself stays in the unit tests. -## Required - -- [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - publishers name every group they won't deliver, which the lite-07 case checks - ## Related +- [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - owns the lite-07 drop case on top of this harness - [Reliable stream reset](/quest/m1/quic/reliable-reset.md) - keeps a reset stream's header, so the reset acts as a one-group drop diff --git a/quest/m1/transport-upgrade/README.md b/quest/m1/transport-upgrade/README.md index 094817c6e0e..25a197bed54 100644 --- a/quest/m1/transport-upgrade/README.md +++ b/quest/m1/transport-upgrade/README.md @@ -45,7 +45,7 @@ Shared decisions: `moq-tokio`, `websocketWon` in `js/net`) forgets the URL: QUIC works on this network, so the head start comes back. Otherwise a network where WebSocket narrowly beats QUIC would open two connections on every reconnect. -- The old session gets `Goaway::same()` with the configured handover cap before +- The old session gets `Goaway::new()` with the configured handover cap before it enters draining. The relay refuses new requests on it from then on; the splice ends its subscriptions at the boundary. - One-shot `connect()` returns one session and never upgrades; every diff --git a/quest/m1/ts-import-shared-shift.md b/quest/m1/ts-import-shared-shift.md index 2ae0bf33974..acdf5972497 100644 --- a/quest/m1/ts-import-shared-shift.md +++ b/quest/m1/ts-import-shared-shift.md @@ -44,7 +44,3 @@ Guidance: - Tests beside the existing loop-wrap tests: a muxed H.264 + AAC loop whose period is not a multiple of either frame duration keeps the first audio and video timestamps of each pass at the source offset across three wraps. - -## Related - -- [Remove live()](/quest/m1/remove-live.md) - deletes the restart anchor; a wrap shift stays input-derived diff --git a/quest/m1/unknown-session-logs.md b/quest/m1/unknown-session-logs.md deleted file mode 100644 index b1db43f89ad..00000000000 --- a/quest/m1/unknown-session-logs.md +++ /dev/null @@ -1,46 +0,0 @@ -# [S] UnknownSession log flood - -## Goal - -moq.pro relays stop logging -`web_transport_moq::session: failed to decode unidirectional stream err=WebTransportError(UnknownSession)` -for streams that were simply reset or cut off before their WebTransport -header arrived. A stream that really names another session is still reported -as `UnknownSession`, and the error a caller sees says what happened. - -## Plan - -Seen in production at a rate like the old-group warnings -https://github.com/moq-dev/moq/pull/4208 fixed, on the same hosts. - -Root cause, confirmed by a test: `decode_uni` and `decode_bi` in -`web-transport-moq`'s `session.rs` map every failure to read the stream type -or session ID to `UnknownSession`, and a peer reset before those bytes -arrive is one. moq resets a group's stream when the group is superseded or -expires, and without reliable reset the header is discarded with it. - -The fix keeps the read's cause as `WebTransportError::ReadError`, keeps -`UnknownSession` for a session-ID mismatch, and logs a reset or lost -connection at debug: - -- [moq-dev/noq#19](https://github.com/moq-dev/noq/pull/19) for 2.x (`dev`) - and its backport [moq-dev/noq#20](https://github.com/moq-dev/noq/pull/20) - for 1.3.x (`main`). -- [moq-dev/web-transport#405](https://github.com/moq-dev/web-transport/pull/405) - for `web-transport-quinn`, `web-transport-noq`, and `web-transport-iroh`, - which carry the same code. `main` pins `web-transport-iroh` 0.7, so it - gets the iroh fix when `dev` merges. - -Remaining: bump `web-transport-moq` to the 1.3.3 release on `main` (and -2.0.1 on `dev` if it lands first). Then confirm on a moq.pro relay that the -rate drops, and that any remaining `UnknownSession` lines are real -mismatches. - -## Required - -- `web-transport-moq` 1.3.3 released from moq-dev/noq#20 - -## Related - -- [Close codes on every transport](/quest/m1/close-codes.md) - another error mapping fix in the same crate -- [Reliable stream reset](/quest/m1/quic/reliable-reset.md) - keeps a reset stream's header, which removes most of these diff --git a/quest/m1/uring-ietf.md b/quest/m1/uring-ietf.md index c9f9cbcb31a..c860ec359de 100644 --- a/quest/m1/uring-ietf.md +++ b/quest/m1/uring-ietf.md @@ -31,5 +31,5 @@ ring requires the release carrying it. ## Related -- [Stream sessions](/quest/m1/uring-tcp/README.md) - the other protocol gap - on the ring, WebSocket and HTTP +- [Stream sessions](/quest/m2/uring-tcp/README.md) - the other protocol gap + on the ring, WebSocket and HTTP, deferred to m2 diff --git a/quest/m1/video-surface.md b/quest/m1/video-surface.md deleted file mode 100644 index d5e7cdc9f56..00000000000 --- a/quest/m1/video-surface.md +++ /dev/null @@ -1,36 +0,0 @@ -# [XS] FFI decoded frames expose a surface, only where one exists - -## Goal - -moq-ffi names the decoder's retained picture the way moq-video does, and a -caller cannot opt into it on a platform that has none. On `dev` -([#4094](https://github.com/moq-dev/moq/pull/4094)) the frame's view is -`MoqVideoNative` from `native()`, enabled by `MoqVideoDecoderOutput.native`. -Only macOS has a variant (`PixelBuffer`). Elsewhere the opt-in still decodes -to native surfaces, `native()` always returns `None`, and a tiled VAAPI -DMA-BUF also fails `pixels()`, so the caller gets frames it cannot read. - -## Plan - -Decided: - -- Rename to surface naming, mirroring `moq_video::Surface`: - `MoqVideoSurface`, `surface()`, and the matching `MoqVideoDecoderOutput` - flag. "Native" named today's implementation, not the role. -- Refuse the opt-in at subscribe time on platforms with no surface variant - (Windows and Linux today) with a clear unsupported error. Each platform - lifts the refusal when its variant lands with hardware proof, in - [decode-windows](/quest/m1/obs-moq-video/decode-windows.md) and - [decode-linux](/quest/m1/obs-moq-video/decode-linux.md). - -Guidance: - -- Whether `moq_video::Output::Native` should follow the rename is a - separate call; ask before touching it. -- Update the wrappers and docs per the root `AGENTS.md` sync table: the Go, - Python, Swift, and Kotlin option docs mention the native surface flag, and - `quest/m1/obs-moq-video/source.md` and the release plan on `dev` name - `native`. -- A `dev` break on top of #4094, so it rides the same release. -- Test: the opt-in is refused where there is no variant, and on macOS - `surface()` returns the pixel buffer. diff --git a/quest/m1/watch-audio-time-stretch.md b/quest/m1/watch-audio-time-stretch.md index 0ceb0850b6f..34134a7e210 100644 --- a/quest/m1/watch-audio-time-stretch.md +++ b/quest/m1/watch-audio-time-stretch.md @@ -12,7 +12,7 @@ Boundaries: no packet loss concealment; an underrun still renders a ramped gap. The target estimator and the ring's slack and re-stall are the [audio jitter target](/quest/m0/audio-jitter-target/README.md) line (#3517 was closed in favor of it); the clock the stretch converges toward is -[Plan: A/V clock](/quest/m0/plan-av-clock.md). +[Plan: A/V clock](/quest/m1/av-clock.md). ## Plan @@ -28,5 +28,4 @@ was closed in favor of it); the clock the stretch converges toward is ## Required -- [Plan: A/V clock](/quest/m0/plan-av-clock.md) - stretching against a free-running ring only moves the drift - [Watch](/quest/m0/audio-jitter-target/watch.md) - the recorded traces this replays, and the JS target it converges toward diff --git a/quest/m1/watch-refusal.md b/quest/m1/watch-refusal.md deleted file mode 100644 index 4412cf6113d..00000000000 --- a/quest/m1/watch-refusal.md +++ /dev/null @@ -1,38 +0,0 @@ -# [S] Watch shows a refusal - -## Goal - -When the origin refuses the broadcast `` asks for, the player shows -that refusal as an error instead of sitting offline as if nothing was -published yet. Refusal stays terminal, as -[#4230](https://github.com/moq-dev/moq/pull/4230) made it in `@moq/net` to -match Rust moq-net: the player never re-asks a handler that already said no. - -## Plan - -- The gap is Codex's P1 on #4230 - ([r4109909244](https://github.com/moq-dev/moq/pull/4230#discussion_r4109909244)): - `js/watch/src/broadcast.ts` only watches `request.active`, so after a - `dynamic()` handler refuses, the request closes with an error that nobody - reads and `active` stays `undefined` forever. -- Observe `Requesting.closed` and carry the error into the broadcast's - state. Whether that is a new `"error"` status, a separate error signal, or - both is open; mirror how the element already surfaces other terminal - states, such as the unsupported indicator. Keep the error's message so the - UI can say why. `unroutable` is also true for a path nothing serves yet, so - it cannot tell a refusal from offline. -- What clears the error is part of the design: a fresh request (a new - `name` or origin, or re-enabling) should be the only way back. No retry - loop. -- Cover both the announced and unannounced paths in `#runBroadcast`. -- Show it in the UI, and update `demo/web` if it consumes the status. Add a - test in `js/watch` where a `dynamic()` handler refuses and the broadcast - reports the error. -- Update `doc/` wherever the watch status values are documented. - -Public API: likely additive (a new status value or error signal on the watch -broadcast and element). Wire: none. - -## Related - -- [#4230](https://github.com/moq-dev/moq/pull/4230) - made JS refusals terminal diff --git a/quest/m1/watch-worker.md b/quest/m1/watch-worker.md index ccbbc14bc72..527a11c7471 100644 --- a/quest/m1/watch-worker.md +++ b/quest/m1/watch-worker.md @@ -31,7 +31,7 @@ Gate on the plan's jank harness and N-player sweep, both nightly. ## Required - [Plan: watch worker](/quest/m1/plan-watch-worker.md) - picks the worker model and rewrites this quest -- [A/V clock](/quest/m0/plan-av-clock.md) - reshapes `Sync` and the worklet playhead, so the move to the worker happens once +- [A/V clock](/quest/m1/av-clock.md) - reshapes `Sync` and the worklet playhead, so the move to the worker happens once ## Related diff --git a/quest/m1/wt-close-upstream.md b/quest/m1/wt-close-upstream.md index 84f801729d8..ac4b763988a 100644 --- a/quest/m1/wt-close-upstream.md +++ b/quest/m1/wt-close-upstream.md @@ -40,6 +40,13 @@ has no close-code scenario, so it is not cheap to add here. Public API: none. Wire: none. +Decided in the 2026-09-30 audit: the UnknownSession log flood quest merged +here, since the same `web-transport-moq` release carries its fix. +`decode_uni` and `decode_bi` mapped a stream reset before its WebTransport +header to `UnknownSession`, flooding relay logs with WARNs; the fork now +keeps the read's cause and logs a reset at debug. After the bump, confirm on +a moq.pro relay that the flood stops. + ## Required - A `web-transport-moq` 1.3.x release that carries moq-dev/noq#24 @@ -47,5 +54,3 @@ Public API: none. Wire: none. ## Related - [Browser close code](/quest/m1/browser-close-code.md) - the playwright case that proves Chromium reads the code this quest unblocks -- [Close codes on every transport](/quest/m1/close-codes.md) - the same symptom over qmux and raw QUIC -- [UnknownSession log flood](/quest/m1/unknown-session-logs.md) - another `web-transport-moq` release and pin bump diff --git a/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md b/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md index 384a5f33b78..532a8543e66 100644 --- a/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md +++ b/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md @@ -1,29 +1,29 @@ -# [L] Complete NVIDIA Main10 and AV1 encoding support +# [M] Complete NVIDIA Main10 encoding support ## Goal -Implement and verify the remaining 10-bit HEVC and AV1 encoding work tracked -in [#2147](https://github.com/moq-dev/moq/issues/2147). NVDEC AV1 decoding and +Implement and verify the remaining 10-bit HEVC encoding work tracked in +[#2147](https://github.com/moq-dev/moq/issues/2147). NVDEC AV1 decoding and catalog AV1 types already exist; do not reimplement them. ## Plan +Decided in the 2026-09-30 audit: AV1 encoding split out to +[NVENC AV1](/quest/m3/nvenc-av1.md), because it needs an Ada GPU and the only +GPU CI host is an RTX 3070 Ti. Main10 stays here since that host can verify it. + Extend the settled frame and NVENC contracts with Main10 surfaces, profile selection, and accurate codec metadata. Audit byte pitch, plane layout, CPU download, and P016 input/output together; a codec enum alone does not establish 10-bit support. Preserve color metadata and refuse unsupported conversions. Do not imply that OpenH264 can decode HEVC or tonemap HDR. -Add AV1 encoding only where the queried NVIDIA device/driver supports it. -Preserve OBU framing and accurate catalog configuration through transcode. Use existing extensible codec enums; no replacement of the 0.1 core API is planned. Keep the NVIDIA backend optional and loaded at runtime. -Split Main10 and AV1 implementation into independent PRs if hardware or review -scope warrants it. Validate decoded pixels, bit depth, profile, framing, -resource lifetime, drain, and refusal on unsupported devices. Wire fixtures -and contract tests into CI, and record actual hardware execution separately. -Lack of suitable hardware leaves that implementation unverified, not complete. +Validate decoded pixels, bit depth, profile, resource lifetime, drain, and +refusal on unsupported devices. Wire fixtures and contract tests into CI, and +run the hardware tests on the [GPU CI](/quest/m1/gpu-ci.md) host. Public API: additive capabilities on the extension points settled on main. Wire: existing codec signaling, with cross-language fixtures for any metadata change. @@ -34,4 +34,6 @@ codec signaling, with cross-language fixtures for any metadata change. ## Related +- [GPU CI](/quest/m1/gpu-ci.md) - the RTX 3070 Ti host that verifies Main10 +- [NVENC AV1](/quest/m3/nvenc-av1.md) - the AV1 half of #2147, hardware-gated - [Codec coverage study](/quest/m2/video-codec-coverage.md) - measure optional software and other native backends separately diff --git a/quest/m1/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md b/quest/m2/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md similarity index 90% rename from quest/m1/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md rename to quest/m2/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md index 65fd5ba4cbd..0ddef060e66 100644 --- a/quest/m1/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md +++ b/quest/m2/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md @@ -9,7 +9,9 @@ exporter understands. Server-side ad insertion is a separate future quest. ## Plan -Use the shared event contract [emsg](/quest/m1/emsg.md) settles. Deliver cues immediately, including when splice_time is in the +Deferred to m2 in the 2026-09-30 audit: no named consumer for timed metadata. + +Use the shared event contract [emsg](/quest/m2/emsg.md) settles. Deliver cues immediately, including when splice_time is in the future; consumers need advance notification. Metadata group sequences are independent of media GOPs. @@ -40,14 +42,10 @@ schema: the draft is the normative spec, and a section Rust and JS emit must be in it the day it ships. Cross-package sync: `rs/hang`, `js/hang`, `rs/moq-mux`, `doc/concept`. -## Required - -- [fMP4 emsg](/quest/m1/emsg.md) - settles the shared framing and missing-data semantics before this section adopts them - ## Closes - [#2279](https://github.com/moq-dev/moq/issues/2279) - close this issue when the quest finishes ## Related -- [ID3 catalog section](/quest/m1/id3.md) - the other typed timed-metadata section, same rule +- [ID3 catalog section](/quest/m2/id3.md) - the other typed timed-metadata section, same rule diff --git a/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md b/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md index d72e102a55f..d479c5efcac 100644 --- a/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md +++ b/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md @@ -4,7 +4,7 @@ The Linux zero-copy spine from [#2819](https://github.com/moq-dev/moq/issues/2819), `PipeWire DMA-BUF -> Surface::DmaBuf -> Vulkan import -> render shader`, is -proven on real hardware, and a V4L2 camera feeds `Surface::DmaBuf` too. +proven on real hardware. ## Plan @@ -26,9 +26,11 @@ What remains: driver will not import, and re-tiles nothing. A VA-API VPP re-tile is only worth adding if a measured capture source lands on such a modifier; record the modifiers seen and decide. -- V4L2 capture still converts to I420 on the CPU. Export its buffers with - `VIDIOC_EXPBUF` (the ioctl is in `moq-v4l`, unused) as a `Surface::DmaBuf` - so a camera reaches VA-API or NVENC without a copy. + +Decided in the 2026-09-30 audit: V4L2 `VIDIOC_EXPBUF` export is dropped. +V4L2 capture only takes YUYV and MJPEG (`rs/moq-video/src/capture/v4l2.rs`), +both of which need a CPU conversion or decode anyway, so exporting the buffer +saves no copy. Revisit only if NV12 camera capture lands. Refs #2481, #1837. @@ -39,4 +41,3 @@ Refs #2481, #1837. ## Related - [Capture multi-plane PipeWire cameras](/quest/m2/pipewire-camera-planes.md) - separate memory blocks from a camera, the capture offer rather than this import -- [#2893: video: validate PipeWire DMA-BUF capture on KDE hardware](/quest/m3/2893-video-validate-pipewire-dma-buf-capture-on-kde-hardware.md) - the KDE portal capture that timed out diff --git a/quest/m1/perf/3129-moq-uring-write-the-webtransport-stream-header-at-open.md b/quest/m2/3129-moq-uring-write-the-webtransport-stream-header-at-open.md similarity index 90% rename from quest/m1/perf/3129-moq-uring-write-the-webtransport-stream-header-at-open.md rename to quest/m2/3129-moq-uring-write-the-webtransport-stream-header-at-open.md index 67e260a184d..c6f9e783364 100644 --- a/quest/m1/perf/3129-moq-uring-write-the-webtransport-stream-header-at-open.md +++ b/quest/m2/3129-moq-uring-write-the-webtransport-stream-header-at-open.md @@ -31,9 +31,13 @@ The reason it is not a small change: `poll_open_uni` would have to hold a half-o Worth confirming the trade too: making `open` block on credit moves the backpressure earlier, which is more correct but changes when a caller learns about it. +Decided in the 2026-09-30 audit: moved to m2. No in-tree caller hits the +wart (moq-net always pairs `finish()` with `poll_closed`), and io_uring +ships in no package. + ## Required -- [Open contract](/quest/m1/perf/uring-open-contract.md) - settle concurrent ownership and backpressure before implementation +- [Open contract](/quest/m2/uring-open-contract.md) - settle concurrent ownership and backpressure before implementation ## Closes diff --git a/quest/m1/perf/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md b/quest/m2/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md similarity index 93% rename from quest/m1/perf/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md rename to quest/m2/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md index 9dd02084d06..3bf50216a67 100644 --- a/quest/m1/perf/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md +++ b/quest/m2/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md @@ -35,6 +35,9 @@ The kernel returns when `N` CQEs arrive, when `t` expires after partial progress Benchmark chat, 1:1 video, and fanout workloads with `N = 1/4/8/16` and `t = 0/5/10/20 us`. Record CQEs per wake, enters per second, CPU per message, p50, p99, and p999 latency. Pick no production default until the latency budget and CPU win are both demonstrated. +Decided in the 2026-09-30 audit: moved to m2. It trades latency for CPU, +the win is unmeasured on noq, and io_uring ships in no package. + ## Closes - [#3200](https://github.com/moq-dev/moq/issues/3200) - close this issue when the quest finishes diff --git a/quest/m1/perf/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md b/quest/m2/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md similarity index 93% rename from quest/m1/perf/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md rename to quest/m2/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md index bb9a3d65b71..67f44fde701 100644 --- a/quest/m1/perf/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md +++ b/quest/m2/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md @@ -30,6 +30,9 @@ Registered files let SQEs address a stable table slot with `types::Fixed`. This Benchmark steady-state send/receive traffic and high socket-churn workloads. Record CPU, cycles, instructions, throughput, and socket lifetime cost. Keep the implementation only if the hot-path win justifies the slot-lifecycle complexity. +Decided in the 2026-09-30 audit: moved to m2. The hot-path win is +unmeasured on noq, and io_uring ships in no package. + ## Closes - [#3202](https://github.com/moq-dev/moq/issues/3202) - close this issue when the quest finishes diff --git a/quest/m2/README.md b/quest/m2/README.md index 1526d8d7649..f79539a25fd 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -10,88 +10,107 @@ Nothing here blocks a release. Promote a quest into [m1](/quest/m1/README.md) when it joins the next wave, including planning work whose decisions are worth settling now; deferral does not abandon a feature. A study may end with a measured no-go. Work gated on hardware, a -partner, or a provider waits in [m3](/quest/m3/README.md); work waiting on an -upstream release waits in [m4](/quest/m4/README.md). +partner, a consumer, or a provider waits in [m3](/quest/m3/README.md); work +waiting on an upstream release waits in [m4](/quest/m4/README.md). ## Required +- [P2P](/quest/m2/p2p/README.md) - opted-in clients serve each other over data channels and iroh while the relay stays the rendezvous and the fallback, under application policy +- [One port](/quest/m2/one-port/README.md) - a relay speaks QUIC and STUN on one UDP port and HTTP, RTMP, and RTMPS on one TCP port; WebRTC media is an embedder hook +- [Ladder](/quest/m2/ladder/README.md) - a transcode ladder adapts to the uplink it publishes over, instead of encoding every live rung at its ceiling +- [Processor](/quest/m2/processor/README.md) - a customer-run worker publishes an on-demand contribution under its own service prefix with scoped access +- [Stream sessions](/quest/m2/uring-tcp/README.md) - serve WebSocket and HTTP from the io_uring workers, where io_uring pays off most +- [fMP4 emsg](/quest/m2/emsg.md) - settles the shared framing and missing-data semantics before this section adopts them +- [ID3 catalog section](/quest/m2/id3.md) - timed ID3 as a first-class container-neutral catalog section +- [FLV script tags](/quest/m2/flv-script.md) - onMetaData and AMF data messages survive RTMP and FLV import +- [#2279](/quest/m2/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md) - hang: SCTE-35 cues arrive immediately on an independent metadata track, optionally associated with a rendition +- [CEA-608/708](/quest/m2/captions-cea.md) - captions carried inside video SEI become a real text rendition at import +- [Browser archive](/quest/m2/archive-browser.md) - the same contract for browser-published broadcasts +- [Paced replay](/quest/m2/archive-paced-replay.md) - a replay pushes its groups to live subscribers on one shared clock, so any live player plays it +- [Install moq](/quest/m2/moq-installer.md) - one command installs or upgrades the released CLI on macOS and Linux +- [Install URL](/quest/m2/moq-install-url.md) - moq.dev serves the canonical installer at /install.sh +- [`moq relay`](/quest/m2/moq-relay-subcommand.md) - the relay runs under a `moq` verb with its own flags and TOML, while `moq-relay` stays a minimal binary +- [Linux decoded frames](/quest/m2/obs-decode-linux.md) - present supported native decoded surfaces with visible CPU fallback +- [Windows decoded frames](/quest/m2/obs-decode-windows.md) - present decoded D3D11 surfaces in OBS without CPU readback +- [macOS GPU input](/quest/m2/obs-macos.md) - feed the encoder from the OBS compositor without CPU readback +- [Windows GPU input](/quest/m2/obs-windows.md) - import or blit OBS D3D11 textures with explicit synchronization +- [Sans-IO IETF session](/quest/m2/rs2ts-sans-io-ietf.md) - the session shape it translates +- [Generated IETF](/quest/m2/rs2ts-ietf.md) - @moq/net's moq-transport session is generated too +- [Per-stream deadlines](/quest/m2/quic-deadline.md) - hopeless retransmits + become resets, and a tail loss probe fires early while there is still time +- [qmux on the QUIC stream state machine](/quest/m2/quic-qmux.md) - qmux is a + first-class crate in the fork over the shared stream state machine +- [Align BBR loss handling with draft-06](/quest/m2/quic-bbr-loss-parity.md) - losses use their own sample and undo re-enters ProbeUp through Refill +- [Measure ECN on the backbone](/quest/m2/quic-ecn-measure.md) - a written + verdict on marking versus dropping, and whether Linode and OVH keep marks +- [Starvation at frame granularity](/quest/m2/starvation-frames.md) - the + acknowledged frontier moves at every frame boundary through `poll_acked`, + with a delivery-delay histogram for jitter +- [Per-stream ACK progress](/quest/m2/quic-ack-progress.md) - the fork reports + how far a send stream has been acknowledged and when +- [poll_acked in web-transport](/quest/m2/quic-ack-hook.md) - the + backend-neutral hook that awaits an acknowledged stream offset, implemented + for noq and released +- [#3200](/quest/m2/3200-moq-uring-batch-completion-wakeups-with-min-timeout.md) - moq-uring: batch completion wakeups with MIN_TIMEOUT +- [#3202](/quest/m2/3202-moq-uring-use-fixed-file-slots-for-worker-udp-sockets.md) - moq-uring: use fixed-file slots for worker UDP sockets +- [Open contract](/quest/m2/uring-open-contract.md) - settle concurrent ownership and backpressure before implementation +- [#3129](/quest/m2/3129-moq-uring-write-the-webtransport-stream-header-at-open.md) - moq-uring: write the WebTransport stream header at open time, so finish() never owes one +- [Cache shard](/quest/m2/cache-shard.md) - stop hammering one process-global cache line from every worker +- [Encoder feedback](/quest/m2/stats-encoder-feedback.md) - a Rust encoder + reads its viewers' feedback and adapts its bitrate +- [Text availability](/quest/m2/text-schema.md) - a text track publishes its own coverage index instead of copying the media timeline +- [Closure counters](/quest/m2/closure-counters.md) - a departed node's return never regresses the closure counters a consumer already saw +- [Bench coverage](/quest/m2/bench-coverage.md) - Criterion targets for moq-pattern matching first, then the stats producer, moq-mux containers, the hang catalog, and moq-auth +- [Signed priority](/quest/m2/signed-priority.md) - on dev, every API priority is an `i8` with 0 as the unset midpoint, and hang's built-ins sit above it - [AV1 metadata separation](/quest/m2/av1-metadata.md) - retain metadata OBUs inline while evaluating separate delivery -- [SEI separation](/quest/m2/sei/README.md) - retain inline SEI until measured savings or a metadata-only consumer justify a split -- [Catalog track identity](/quest/m2/catalog-tracks.md) - compare immutable track definitions with explicit catalog-to-group binding +- [Catalog track identity](/quest/m2/catalog-tracks.md) - a changed track configuration becomes a new track name or epoch, never a mutated definition +- [Catalog colour model](/quest/m2/color-catalog.md) - the catalog describes a rendition's colour and HDR properties once a renderer consumes them - [Archive recovery listing](/quest/m2/archive-recovery-listing.md) - a resumed DVR lists what changed since its checkpoint, not every stored group -- [Archive backward timestamps](/quest/m2/archive-backward-timestamps.md) - a resumed recording refuses a track whose timestamps go backward -- [IETF drain before close](/quest/m2/ietf-drain-before-close.md) - moq-transport sessions deliver finished tracks before a graceful close, as moq-lite does -- [moq play drain tail](/quest/m2/play-drain-tail.md) - retired renditions and finite tracks play their last 10 ms of audio - [Relay io_uring packages](/quest/m2/relay-io-uring-package.md) - Linux relay packages ship io_uring once the ring is on par with tokio -- [Mobile ownership](/quest/m2/mobile-ownership.md) - decide whether Rust or platform code owns mobile capture, codecs, and rendering - [iOS capture](/quest/m2/mobile-capture-ios.md) - camera and screen capture if the mobile ownership decision selects Rust - [Android capture](/quest/m2/mobile-capture-android.md) - NDK/JNI capture using the existing codecs if mobile ownership selects Rust - [Mobile completion](/quest/m2/mobile-completion.md) - verify the selected native/mobile path before closing #700 -- [Linux OBS GPU input](/quest/m2/obs-linux-gpu.md) - publish OBS compositor frames without CPU readback on a validated Linux graphics/encoder combination -- [LiveKit client shim](/quest/m2/livekit-shim.md) - a media compatibility facade over the room SDK -- [Audio loss recovery](/quest/m2/audio-loss-recovery.md) - prove a useful Opus recovery policy before exposing another option -- [Opus implementation](/quest/m2/audio-opus-backend.md) - compare current codec quality, CPU, and optional build costs +- [Opus implementation](/quest/m2/audio-opus-backend.md) - compare Opus codec quality, CPU, build cost, and the loss recovery each backend offers - [Latency ledger](/quest/m2/latency-ledger.md) - a session reports where its end-to-end audio delay went, stage by stage - [JS LOC duration marker](/quest/m2/js-loc-duration-marker.md) - `@moq/loc`'s producer ends each video group with the empty duration frame, as moq-mux does -- [JS discontinuity](/quest/m2/js-discontinuity.md) - on dev, JS `discontinuity()` without an end writes no cadence-estimated end, like Rust -- [Synced data playback](/quest/m2/watch-data-sync.md) - js/watch releases JSON and binary payloads on the media playhead, and a slow data track holds media back - [Media Foundation decode](/quest/m2/audio-decode-mediafoundation.md) - Windows decodes HE-AAC, multichannel AAC, and what else the MFTs offer - [Media Foundation encode](/quest/m2/audio-encode-mediafoundation.md) - Windows encodes AAC-LC - [MediaCodec decode](/quest/m2/audio-decode-mediacodec.md) - Android decodes HE-AAC, multichannel AAC, and what else the device offers - [MediaCodec encode](/quest/m2/audio-encode-mediacodec.md) - Android encodes AAC-LC - [Video codec coverage](/quest/m2/video-codec-coverage.md) - prioritize remaining native AV1 and portable decoder gaps -- [#2147](/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md) - moq-video: 10-bit HEVC and AV1 support in the NVIDIA codec path +- [#2147](/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md) - moq-video: 10-bit HEVC in the NVIDIA codec path; AV1 is m3 - [NVENC buffer pool](/quest/m2/nvenc-pool.md) - NVENC reuses input and output buffers instead of allocating per frame, if a benchmark shows it wins - [NVENC held frames](/quest/m2/nvenc-held-frames.md) - moq-nvenc refuses or drives configurations whose frames the driver holds back - [Direct3D11 render import](/quest/m2/render-d3d11.md) - Windows presents without downloading every frame to system memory - [Intra-refresh GOPs](/quest/m2/intra-refresh/README.md) - video with periodic intra refresh publishes, imports, and tunes in cleanly with one group per sweep and a catalog `warmup` - [Capture multi-plane PipeWire cameras](/quest/m2/pipewire-camera-planes.md) - I420 and NV12 cameras that deliver one memory block per plane - [#2819](/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md) - moq-video: validate PipeWire DMA-BUFs into the Vulkan renderer on hardware, and export V4L2 buffers as DMA-BUFs -- [Unreal prototype](/quest/m2/unreal.md) - a UE5 module on the C++ package with exceptions disabled, rendering a subscribed broadcast to a texture -- [Unity prototype](/quest/m2/unity.md) - the C# package under IL2CPP, playing subscribed audio -- [C# through moq-ffi](/quest/m2/cs/README.md) - generated C# over moq-ffi as a NuGet package with native runtimes - [vcpkg registry](/quest/m2/cpp-vcpkg.md) - a registry we own serves the prebuilt package to `vcpkg` manifests -- [Conan remote](/quest/m2/cpp-conan.md) - a remote we own serves the same tarball to `conan install` -- [Compressed tracks](/quest/m2/flate/README.md) - the hand-written binding wrappers expose flate tracks - [Binary delta stats](/quest/m2/stats-delta.md) - an on-demand varint delta flavor of every stats track, if relay encode CPU still matters after the JSON fixes - [#3115](/quest/m2/3115-moqsink-the-publication-has-no-generation-so-a-flush.md) - moqsink: a flushing restart after EOS opens a new publication generation -- [Redundant ingest](/quest/m2/redundant-ingest.md) - decide whether two publishers sharing one epoch may splice, and who declares the incumbent dead before the keep-alive does - [Multipath spike](/quest/m2/multipath-spike.md) - whether bonded contribution over multipath QUIC is worth building, given it needs noq on both ends -- [Receive timestamps](/quest/m2/quic-receive-ts.md) - per-packet arrival times in ACKs, the feedback GCC and deadlines need -- [QUIC GCC](/quest/m2/quic-gcc.md) - a measured verdict on delay-based congestion control for media egress, shipping as `RealTime` -- [QUIC FEC](/quest/m2/quic-fec.md) - a measured verdict on transport-level FEC vs retransmission -- [Google BBR comparison](/quest/m2/quic-bbr-google.md) - measure growth detection and precautionary probing after the correctness fixes -- [WHEP ABR](/quest/m2/whep-abr.md) - a WHEP viewer switches renditions from its own congestion feedback -- [Natural media drains](/quest/m2/quic-bbr-natural-drain.md) - whether bounded drain credit avoids ProbeRTT deadline interference +- [BBR media study](/quest/m2/quic-bbr-natural-drain.md) - whether bounded drain credit avoids ProbeRTT deadline interference, and where our BBR differs from Google's - [Discover media headroom](/quest/m2/quic-probe.md) - test useful-media pacing before adding redundant probe traffic - [L4S on the backbone](/quest/m2/quic-ecn.md) - an ECT(1) option in the fork, an `ecn` config knob, and a dualpi2 measurement - [Careful resume on reconnect](/quest/m2/quic-careful-resume.md) - a redial starts at the previous connection's rate - [Keep-alive by deadline](/quest/m2/quic-keep-alive.md) - a PING only when the idle deadline nears, no fixed timer - [noq socket close](/quest/m2/noq-socket-close.md) - noq releases an endpoint's socket on close, so moq-tokio drops its wrapper -- [Drop the hidden cluster exemption](/quest/m2/hidden-exemption.md) - relays stop forcing hidden broadcasts on cluster peers once every peer opts in on the wire -- [Routing cost domains](/quest/m2/routing-cost-domains.md) - design operator boundaries and policy without adding incomparable costs -- [Kernel pacing](/quest/m2/quic-kernel-pacing.md) - whether SO_TXTIME pacing beats a userspace pacer the io_uring driver ignores today -- [Send batching](/quest/m2/quic-send-batching.md) - whether sendmmsg across connections pays on the tokio path -- [Send buffer pools](/quest/m2/quic-buffer-pool.md) - whether pooled send buffers beat Bytes in the stream send path -- [AF_XDP UDP path](/quest/m2/af-xdp.md) - the kernel-bypass verdict on today's virtio hosts that gates DPDK - [GOP overhead](/quest/m2/gop-overhead.md) - price the I-frames a short GOP pays for, deciding whether a long GOP plus a keyframe request is worth designing - [Per-program SI](/quest/m2/ts-program-si.md) - a selected TS program's broadcast carries only its own service's SDT and EIT - [TS import health](/quest/m2/ts-import-health.md) - `moq import ts` counts the TR 101 290 errors of the feed it receives, PCR and PTS graded on its own values - [TS export liveness](/quest/m2/ts-export-liveness.md) - `moq export ts` reports each elementary stream's access units and quiet time, catching a per-track stall - [TS health stats](/quest/m2/ts-health-stats.md) - the TS counters ride the stats plumbing beside the media counters - [Teleoperation](/quest/m2/teleop/README.md) - MoQ carries robot video down and control up on one session as a library capability -- [SIP media stack](/quest/m2/sip-stack.md) - terminate one inbound SIP audio call leg and expose it as Opus frames -- [Carrier voice](/quest/m2/carrier-voice/README.md) - determine whether MoQ should be the call fabric for programmable carrier voice -- [LiveKit WebRTC bridge](/quest/m2/livekit-webrtc-bridge.md) - a go/no-go verdict, backed by a spike, on per-track LiveKit-to-MoQ bridging -- [Common Access Tokens](/quest/m2/cat/README.md) - a moq-transport client presents a CAT in SETUP and `moq auth serve` admits it with the scope its `moqt` claim names -- [Runtime QA hosts](/quest/m2/runtime-qa-hosts.md) - run exact source snapshots on accessible Linux and device hosts with retrievable debug evidence - [Media QA on other engines](/quest/m2/browser-media-qa-engines.md) - the media harness measures a Firefox or WebKit player over the fallback and names what each engine lacks - [Firefox 155 WebTransport](/quest/m2/firefox-155-webtransport.md) - Firefox negotiates the version by subprotocol, and the other new WebTransport features stay unused on purpose - [Windows.Graphics.Capture](/quest/m2/capture-wgc.md) - one WGC backend for display and window capture with the cursor, replacing Desktop Duplication and GDI - [Windows capture parity](/quest/m2/capture-windows.md) - system audio and a settled app-capture policy - [Linux capture parity](/quest/m2/capture-linux.md) - Wayland window/system-audio capture with explicit display-selection and app-capture limits -- [Plan capture ergonomics](/quest/m2/capture-ergonomics.md) - scope independent crop and audio mixing quests - [Audio capture time](/quest/m2/audio-capture-time.md) - native audio stamps a buffer's capture instant, not when the driver reads it - [X11 capture transport](/quest/m2/x11-capture-shm.md) - move X11 capture to shared memory and RandR events instead of a per-frame socket copy -- [Capture frame buffers](/quest/m2/capture-frame-buffers.md) - stop rebuilding a full-frame buffer every tick in the X11 backend -- [Demo serve-hls renditions](/quest/m2/serve-hls-renditions.md) - `just pub serve-hls` serves 720p and 144p instead of two 256-wide copies +- [Egress profile](/quest/m2/quic-egress-profile.md) - measure relay send-path syscalls, pacing bursts, and allocations before optimizing any of them +- [SEI separation study](/quest/m2/sei.md) - measure whether separating SEI saves enough, or has a metadata-only consumer, to justify a split +- [Compressed tracks](/quest/m2/flate.md) - moq-ffi and every wrapper expose flate tracks through a `flate` namespace like `json` +- [Announcement shapes](/quest/m2/announce-shapes.md) - moq-lite announcements and interests carry prefix, exact, suffix, or prefix+suffix shapes that survive relay hops, benchmarked over the announce table +- [MSFTS convergence](/quest/m2/msfts-convergence.md) - the demultiplexed TS lane converges on MSFTS where the two still differ: program tables and the ES payload unit +- [VAAPI encode and decode](/quest/m2/video-vaapi.md) - H.265 encode and decode, pre-generated bindings, and pooled resize surfaces, including the moq-dev/vaapi release that carries them diff --git a/quest/m3/announce-shapes.md b/quest/m2/announce-shapes.md similarity index 87% rename from quest/m3/announce-shapes.md rename to quest/m2/announce-shapes.md index 19083a6c45f..db1263cce2f 100644 --- a/quest/m3/announce-shapes.md +++ b/quest/m2/announce-shapes.md @@ -26,13 +26,13 @@ Decided 2026-09-29 (quest-plan interview): announcements (PUBLISH_NAMESPACE and NAMESPACE are prefix routes), so a session negotiated as IETF never carries a shape and there is no draft to converge with. -- The quest stays in m3, grown from the suffix-announce quest rather than a - new m1 quest, because that quest already holds the benchmark-first plan and - the version-gated wire approach both shapes need. +- The quest grew from the suffix-announce quest rather than a new m1 quest, + because that quest already holds the benchmark-first plan and the + version-gated wire approach both shapes need. +- Moved from m3 to m2 in the 2026-09-30 audit: it has no external gate, and + the exact-scope leak is a real bug. - The old gate ("a deployment needs a suffix claim a service prefix cannot express") is removed: the exact-scope leak is reason enough. -- [Path patterns](/quest/m1/path-patterns.md) keeps advertisements as prefixes - and names this quest as the owner of non-prefix routing. ### Wire @@ -54,8 +54,10 @@ cases as vectors both languages test. Only these four shapes go on the wire. A richer interest pattern (`pid/*/chat`) stays a consume-side filter over the widest shape that covers -it, as [path patterns](/quest/m1/path-patterns.md) decided for every pattern -before this quest. +it. Path patterns already shipped for that filtering and for token claims +(`moq-pattern`, `@moq/pattern`, +[#3746](https://github.com/moq-dev/moq/pull/3746), and the +[auth line](/quest/m1/auth/README.md)). ### Model @@ -98,12 +100,11 @@ routes independently of Rust. The slopes decide between a reversed-segment index and dropping suffix shapes from the quest. A non-prefix advertisement needs authorizing: -[advertise auth](/quest/m1/processor/advertise-auth.md) scopes are prefix-only +[advertise auth](/quest/m2/processor/advertise-auth.md) scopes are prefix-only today, and this quest extends them to the new shapes. Token patterns (`moq-pattern`, `moq_auth::Claims`) already match suffixes and do not change. ## Related - [Wildcard](/quest/m0/wildcard/README.md) - prefix-only advertisements and the service-prefix layout this extends -- [Path patterns](/quest/m1/path-patterns.md) - owns the pattern dialect a shaped interest would reuse -- [Cluster routing](/quest/m1/cluster-routing.md) - forwards announcements between relays, which must keep their shape +- [Cluster routing](/quest/m1/cluster-routing/README.md) - forwards announcements between relays, which must keep their shape diff --git a/quest/m2/archive-backward-timestamps.md b/quest/m2/archive-backward-timestamps.md deleted file mode 100644 index c5175e4c41a..00000000000 --- a/quest/m2/archive-backward-timestamps.md +++ /dev/null @@ -1,16 +0,0 @@ -# [XS] Archive refuses backward timestamps - -## Goal - -A resumed recording refuses a track whose timestamps go backward past the -recovered timeline, failing loud like the group-ID check, instead of writing -overlapping media time. The caller starts a new prefix. - -## Plan - -Check the first group's timestamp against the recovered track's last recorded -timestamp at enrollment, and test both a backward and a forward restart. - -## Required - -- [Archive](/quest/m1/archive/README.md) - the recovery this hardens ships with the line diff --git a/quest/m1/archive/browser.md b/quest/m2/archive-browser.md similarity index 91% rename from quest/m1/archive/browser.md rename to quest/m2/archive-browser.md index 520a5cb09e0..1a6d5bc935f 100644 --- a/quest/m1/archive/browser.md +++ b/quest/m2/archive-browser.md @@ -31,8 +31,10 @@ the supported drafts without duplicating transport dispatch or codecs here. Ship the contract in the `@moq/*` packages. A dashboard browser-to-HLS proof remains downstream (moq.pro) work. +Deferred to m2 in the 2026-09-30 audit: no named consumer; the native archive +lands first. + ## Required - [JavaScript FETCH](/quest/m1/js-fetch.md) - generic on-demand group serving and IETF FETCH support - -- [Recording writer](/quest/m1/archive/writer.md) +- [Archive](/quest/m1/archive/README.md) - the native writer, reader, and DVR contract this ports diff --git a/quest/m1/archive/paced-replay.md b/quest/m2/archive-paced-replay.md similarity index 86% rename from quest/m1/archive/paced-replay.md rename to quest/m2/archive-paced-replay.md index c17cd658e67..9286a610169 100644 --- a/quest/m1/archive/paced-replay.md +++ b/quest/m2/archive-paced-replay.md @@ -25,3 +25,9 @@ who joins late joins mid-replay. - Test with paused time: record, replay paced, and assert a plain subscriber gets every group in order at media pace, that a late subscriber starts at the current group, and that two tracks stay aligned. +- Deferred to m2 in the 2026-09-30 audit: no named consumer; FETCH replay + already serves DVR and HLS. + +## Required + +- [Recording reader](/quest/m1/archive/reader.md) - the FETCH reader this adds live publishing to diff --git a/quest/m2/audio-decode-mediacodec.md b/quest/m2/audio-decode-mediacodec.md index 936bc13a325..35498472260 100644 --- a/quest/m2/audio-decode-mediacodec.md +++ b/quest/m2/audio-decode-mediacodec.md @@ -25,6 +25,7 @@ behind a new optional audio `mediacodec` feature and the decode seam, on `target ## Required +- [Mobile ownership](/quest/m1/mobile-ownership.md) - if Kotlin owns platform codecs, this backend is moot - [Decode seam](/quest/m1/audio-codecs/decode-backend.md) - the candidate order this backend joins - [Layout](/quest/m1/audio-codecs/layout.md) - what a multichannel frame is delivered as diff --git a/quest/m2/audio-decode-mediafoundation.md b/quest/m2/audio-decode-mediafoundation.md index 6fae6be4fae..2fb647fff1a 100644 --- a/quest/m2/audio-decode-mediafoundation.md +++ b/quest/m2/audio-decode-mediafoundation.md @@ -29,5 +29,4 @@ ones. Behind the decode seam as the first candidate on `target_os = ## Related -- [Runtime QA hosts](/quest/m2/runtime-qa-hosts.md) - where the Windows run happens -- [Windows decoded frames](/quest/m1/obs-moq-video/decode-windows.md) - the OBS Windows line this feeds +- [Windows decoded frames](/quest/m2/obs-decode-windows.md) - the OBS Windows line this feeds diff --git a/quest/m2/audio-encode-mediacodec.md b/quest/m2/audio-encode-mediacodec.md index 7bb26674eaf..5adc169241f 100644 --- a/quest/m2/audio-encode-mediacodec.md +++ b/quest/m2/audio-encode-mediacodec.md @@ -20,6 +20,7 @@ behind the `mediacodec` feature and the encode seam. ## Required +- [Mobile ownership](/quest/m1/mobile-ownership.md) - if Kotlin owns platform codecs, this backend is moot - [Encode seam](/quest/m1/audio-codecs/encode-backend.md) - the candidate order this backend joins - [Layout](/quest/m1/audio-codecs/layout.md) - the input layout the encoder accepts - [MediaCodec decode](/quest/m2/audio-decode-mediacodec.md) - the round-trip regression decodes through it diff --git a/quest/m2/audio-encode-mediafoundation.md b/quest/m2/audio-encode-mediafoundation.md index b1c3440f6bc..6600698e7c4 100644 --- a/quest/m2/audio-encode-mediafoundation.md +++ b/quest/m2/audio-encode-mediafoundation.md @@ -23,7 +23,3 @@ behind the encode seam on Windows. - [Encode seam](/quest/m1/audio-codecs/encode-backend.md) - the candidate order this backend joins - [Layout](/quest/m1/audio-codecs/layout.md) - the input layout the encoder accepts - [Media Foundation decode](/quest/m2/audio-decode-mediafoundation.md) - the round-trip regression decodes through it - -## Related - -- [Runtime QA hosts](/quest/m2/runtime-qa-hosts.md) - where the Windows run happens diff --git a/quest/m2/audio-loss-recovery.md b/quest/m2/audio-loss-recovery.md deleted file mode 100644 index 9be8b40dc08..00000000000 --- a/quest/m2/audio-loss-recovery.md +++ /dev/null @@ -1,28 +0,0 @@ -# [M] Decide a tested Opus loss-recovery policy - -## Goal - -Decide whether a concrete MoQ audio consumer benefits from in-band Opus FEC, -with a tested loss/latency policy before exposing any additive option on -`encode::Settings`. -This does not block 0.1. - -## Plan - -The old boolean supplied no expected-loss percentage and our decoder never -requested FEC recovery. Treat source loss, late-group abandonment, and DTX as -different cases. Define sequencing, expected loss, playout lookahead, recovery -versus concealment, and behavior when the next packet is unavailable. - -Use deterministic dropped-packet fixtures to prove redundancy is emitted and -used, compare audible quality and delay against concealment, and name the -transport scenario where it helps. End with a measured go/no-go and a small -additive policy if justified; do not reintroduce an enable flag tested only by -reading the codec's control value. Implementation fixtures belong in CI. - -Public API: no change during the study; any later policy must fit the extensible -audio settings. Existing wire compatibility must be demonstrated. - -## Related - -- [Audio quality](/quest/m0/audio-quality-harness/README.md) - quality and latency measurements diff --git a/quest/m2/audio-opus-backend.md b/quest/m2/audio-opus-backend.md index a981f0e0070..0a5ccf0e6fc 100644 --- a/quest/m2/audio-opus-backend.md +++ b/quest/m2/audio-opus-backend.md @@ -1,9 +1,10 @@ -# [M] Compare current Opus implementations +# [M] Compare Opus implementations and loss recovery ## Goal -Determine whether an optional newer Opus backend improves quality or CPU enough -to justify its build and maintenance cost while retaining the simple Rust path. +Determine whether an optional newer Opus backend improves quality, CPU, or +loss recovery enough to justify its build and maintenance cost while retaining +the simple Rust path, and settle a tested loss-recovery policy. ## Plan @@ -18,6 +19,24 @@ CPU, and package/toolchain cost. Keep native compilation optional and use the existing private backend seam; do not add another public configuration surface just to expose one implementation's controls. A no-go is a valid outcome. +### Loss recovery + +Decided in the 2026-09-30 audit: the loss-recovery policy study folds in here, +because the options depend on the backend. DRED and deep PLC need libopus 1.5+, +while the current 1.3.1 port only offers in-band LBRR FEC and classic +concealment. + +Decide whether a concrete MoQ audio consumer benefits from FEC, DRED, or deep +PLC over concealment. The old FEC boolean supplied no expected-loss percentage +and our decoder never requested FEC recovery. Treat source loss, late-group +abandonment, and DTX as different cases. Define sequencing, expected loss, +playout lookahead, recovery versus concealment, and behavior when the next +packet is unavailable. Use deterministic dropped-packet fixtures to prove +redundancy is emitted and used, compare audible quality and delay, and name +the transport scenario where it helps. Any resulting policy is small and +additive on the extensible audio settings; do not reintroduce an enable flag +tested only by reading the codec's control value. + Retain fixtures and repeatable measurements in the existing CI/nightly audio harness. Public API and wire: no change for the study; validate compatibility before a separately scoped backend implementation. diff --git a/quest/m2/av1-metadata.md b/quest/m2/av1-metadata.md index 475794e8dee..afc4bec8343 100644 --- a/quest/m2/av1-metadata.md +++ b/quest/m2/av1-metadata.md @@ -29,12 +29,8 @@ Preserve `metadata_type`, the payload bytes, and ordering within the temporal unit. Test HDR10+ T.35 metadata, timecode, an unknown metadata type, several OBUs in one temporal unit, and a byte-identical round trip. -## Required - -- [Metadata association contract](/quest/m2/sei/sei.md) - settles the shared framing and missing-data semantics before this section adopts them - ## Related -- [SEI sidecars](/quest/m2/sei/README.md) - the H.26x contract this should +- [SEI sidecars](/quest/m2/sei.md) - the H.26x contract this should follow rather than duplicate -- [fMP4 emsg carriage](/quest/m1/emsg.md) - independent carriage of container metadata, not a prerequisite for codec extraction +- [fMP4 emsg carriage](/quest/m2/emsg.md) - independent carriage of container metadata, not a prerequisite for codec extraction diff --git a/quest/m2/bench-coverage.md b/quest/m2/bench-coverage.md new file mode 100644 index 00000000000..9e78d0cd71a --- /dev/null +++ b/quest/m2/bench-coverage.md @@ -0,0 +1,50 @@ +# [M] Benchmarks for patterns, stats, containers, catalog, and auth + +## Goal + +Hot paths that have no benchmark get Criterion targets, so CI tracks them: +`moq-pattern` path matching, the `moq-stats` producer per tick, `moq-mux` +container import and export per frame, `hang` catalog encode, decode, and +update, and `moq-auth` token verification. + +## Plan + +Deferred to m2 in the 2026-09-30 audit. The `moq-pattern` benchmark is the +one worth doing first, and could return to m1 as its own quest. + +- `moq-pattern`: matching swept over pattern count and path depth. Patterns + shipped as `rs/moq-pattern` and `js/pattern`, so the matcher gets one bench + here, not a second one elsewhere. +- `moq-stats` producer (folded in from the stats producer benchmark): measure + what one relay pays per stats tick to drain its registry and encode the + traffic tracks. #4299 keeps an idle path in every frame while the registry + holds its counters (about 430 B per idle path per plain frame), and nothing + measures that or the per-tick drain as held paths grow. Sweep held paths + (for example 100 to 50k) against tiers and the share of idle versus changed + paths. Report time and allocations per tick, and plain and compressed bytes + per frame the way `rs/moq-stats/benches/decode.rs` reports its table, + including the point where a plain frame nears its size cap. Drive the real + producer path (`process_slot`, the snapshot encoders) over a synthetic + `Registry`; a bench hook is fine if it stays out of the public API. This is + the moq-json snapshot encoder profile + [Binary delta stats](/quest/m2/stats-delta.md) gates on. `decode.rs` is not + in CI either; run both targets in the nightly benchmark smoke, as + `moq-net`'s are. +- `moq-mux`: fMP4/CMAF and Annex-B import and export over checked-in or + generated fixtures, with throughput in frames and bytes. Keep fixture + generation out of the timed region. +- `hang`: catalog encode and decode swept over rendition count, plus the + per-update cost a publisher pays. +- `moq-auth`: JWT verification per connection, swept over algorithm and claim + size. The in-band token path gets its bench with + [In-band token](/quest/m1/auth/token-in-band.md), not here. + +Anything that fans out gets a sweep over both axes. Name each target after +what it measures, so the CI comment reads without opening the file. + +Public API: none. Wire: none. + +## Related + +- [Benchmark regressions in CI](/quest/m1/bench-ci.md) - tracks these targets on PRs and nightly +- [Binary delta stats](/quest/m2/stats-delta.md) - its gate needs the stats encode baseline this measures diff --git a/quest/m2/browser-media-qa-engines.md b/quest/m2/browser-media-qa-engines.md index 343d8cb478e..2cf1adce000 100644 --- a/quest/m2/browser-media-qa-engines.md +++ b/quest/m2/browser-media-qa-engines.md @@ -18,8 +18,10 @@ WebCodecs encode and decode, AudioWorklet, `MediaStreamTrackProcessor`, Neither Playwright Firefox nor Playwright WebKit ships WebTransport, and WebKit also lacks the WebCodecs encoder, so neither can publish and neither -can play over QUIC. What they can do is play over the WebSocket fallback, -which is the path a real Firefox viewer takes today. +can play over QUIC. What they can do is play over the WebSocket fallback. +Real Firefox does use WebTransport; only Playwright's build lacks it, so a +fallback run covers the player, not Firefox's transport path (see open PR +[#4460](https://github.com/moq-dev/moq/pull/4460)). - Split the harness's publisher and subscriber roles so an engine can take one side: a Chromium fixture with a Firefox or WebKit player over the @@ -34,4 +36,4 @@ which is the path a real Firefox viewer takes today. ## Related -- [Runtime QA hosts](/quest/m2/runtime-qa-hosts.md) - where an engine that will not run on the CI image runs +- [Firefox 155 WebTransport](/quest/m2/firefox-155-webtransport.md) - the real Firefox transport path, verified by hand diff --git a/quest/m1/perf/cache-shard.md b/quest/m2/cache-shard.md similarity index 90% rename from quest/m1/perf/cache-shard.md rename to quest/m2/cache-shard.md index 3be996a5ae1..65d7a28d554 100644 --- a/quest/m1/perf/cache-shard.md +++ b/quest/m2/cache-shard.md @@ -58,6 +58,11 @@ where available), relay CPU and RSS at the fanout shape via behavior covered by the existing cache tests plus new ones for the staleness bound. +Decided in the 2026-09-30 audit: moved to m2 because the contention is +unmeasured on noq. [Lock wait](/quest/m1/perf/lock-wait.md) decides it; take +this up only if that shows more than 1% contention on the pool line. + ## Related +- [Lock wait](/quest/m1/perf/lock-wait.md) - measures whether the pool line is contended enough to justify this - [#3122](/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md) - the remaining clock reads one layer down; a pool epoch driven by its per-turn timestamp is the way to drop the last per-frame read, and the model should drink from that cup rather than grow a second clock diff --git a/quest/m1/captions-cea.md b/quest/m2/captions-cea.md similarity index 92% rename from quest/m1/captions-cea.md rename to quest/m2/captions-cea.md index 909fa7e97b6..e7f3be5cde3 100644 --- a/quest/m1/captions-cea.md +++ b/quest/m2/captions-cea.md @@ -8,6 +8,8 @@ without extraction those broadcasts have no captions in MoQ at all. ## Plan +Deferred to m2 in the 2026-09-30 audit: no named consumer for timed metadata. + Parse the `user_data_registered_itu_t_t35` SEI payloads that carry CEA-708 (with 608 compatibility bytes inside) out of H.264 and H.265 access units at import, and publish the decoded cues as a `text` rendition beside the video. @@ -34,6 +36,6 @@ exists to prevent, so cover the ordering with a test rather than a comment. ## Related -- [SEI](/quest/m2/sei/README.md) - carries SEI byte-faithfully as a sidecar; if +- [SEI](/quest/m2/sei.md) - carries SEI byte-faithfully as a sidecar; if that line lands, this parser is a candidate to move onto it rather than walking the access unit itself diff --git a/quest/m2/capture-ergonomics.md b/quest/m2/capture-ergonomics.md deleted file mode 100644 index 0584416ba73..00000000000 --- a/quest/m2/capture-ergonomics.md +++ /dev/null @@ -1,27 +0,0 @@ -# [S] Plan capture ergonomics - -## Goal - -Two papercuts in the capture surface, none blocking but each visible the -first time someone hits it. - -This is a planning dispatch. Verify each current limitation against source, -then replace this quest with independently completable crop and audio mixing -quests. Each needs a chosen public API, ownership -boundary, supported/refused cases, and CI acceptance tests. Ask the maintainer -about unsettled crop coordinates and audio clock/mixing policy before coding. -Keep additions compatible with the settled main capture contracts. Identify any -published API break for a separate maintainer decision; independent format -validation already has its own quest. - -## Plan - -- **Region and crop capture.** No knob exists anywhere; `capture::Config` - carries source, device, width, height, and framerate. Cropping a region of a - display is the common screen-share case that currently requires capturing - the whole thing. -- **Mixing multiple audio devices.** One device, one track. A screen share - wanting microphone plus system audio has no way to say so, which is exactly - the combination the `System` source makes newly reachable. - Preserve exclusive AEC microphone ownership and define clock alignment - before sharing processed microphone input. diff --git a/quest/m2/capture-frame-buffers.md b/quest/m2/capture-frame-buffers.md deleted file mode 100644 index 466191c9b41..00000000000 --- a/quest/m2/capture-frame-buffers.md +++ /dev/null @@ -1,24 +0,0 @@ -# [S] moq-video: X11 capture rebuilds its frame buffers every tick - -## Goal - -X11 screen capture does not allocate a full-frame buffer per frame. -Steady-state capture reuses the same scratch memory. - -## Plan - -The X11 backend added in the native screen-capture work allocates the whole -frame, every frame, on the pump thread. The Windows GDI path had the same cost -and is deleted by [Windows.Graphics.Capture](/quest/m2/capture-wgc.md) instead. - -`capture/x11.rs`'s `PixelFormat::rgb` allocates a `w * h * 3` `Vec` and fills it -with three `push` calls per pixel, and `I420::from_rgb` then walks it again into -a third buffer. Take an `&mut Vec` the `Capture` owns and `clear()` it, so -the allocation happens once. - -This is not a correctness bug, so it is a steady-state cost question: measure -before and after rather than assuming. - -## Related - -- [X11 capture transport](/quest/m2/x11-capture-shm.md) - the larger X11 cost, in the same read path diff --git a/quest/m2/capture-wgc.md b/quest/m2/capture-wgc.md index eb17dc59b1a..80302d8254a 100644 --- a/quest/m2/capture-wgc.md +++ b/quest/m2/capture-wgc.md @@ -93,5 +93,5 @@ the Cargo feature comment, and the `frame.rs` docs on which producers make a ## Related - [Windows capture parity](/quest/m2/capture-windows.md) - app capture and system audio, which WGC does not answer -- [Capture frame buffers](/quest/m2/capture-frame-buffers.md) - its GDI half disappears with `window.rs` +- [X11 capture transport](/quest/m2/x11-capture-shm.md) - owns the X11 frame-buffer reuse; the GDI half disappears with `window.rs` - [Direct3D11 render import](/quest/m2/render-d3d11.md) - the other end of keeping Windows frames on the GPU diff --git a/quest/m2/carrier-voice/README.md b/quest/m2/carrier-voice/README.md deleted file mode 100644 index 4be5cad6d13..00000000000 --- a/quest/m2/carrier-voice/README.md +++ /dev/null @@ -1,56 +0,0 @@ -# Programmable carrier voice - -## Goal - -Determine whether MoQ should be the programmable call fabric between developer -clients, carrier gateways, and auxiliary call services. The design covers -developer-to-gateway and gateway-to-gateway calls; the first lab proves only a -developer client calling a SIP endpoint. - -Stock phones remain on IMS/SIP/RTP. MoQ begins at a carrier-controlled gateway -or developer client, where publish/subscribe can make a live call available to -recorders, agents, transcription, translation, and conferencing without a -bespoke media fork for each service. - -## Plan - -- Use one role-based call model for both topologies. A developer client and a - SIP/IMS gateway are authenticated call legs; internal gateway-to-gateway - transport is the same protocol with two gateway legs, not a second design. -- Calling is an application protocol carried by ordinary - [MOQT](https://datatracker.ietf.org/doc/draft-ietf-moq-transport/). A leg - publishes a short-lived offer and call-state objects plus its Opus audio; the - other leg subscribes and publishes its own state and audio. - `PUBLISH_NAMESPACE` and `SUBSCRIBE_NAMESPACE` provide discovery only. Do not - add call semantics to MOQT or treat namespace publication itself as ringing. -- Scope offers below an opaque line and random call id, never a raw phone - number or caller-asserted identity. The E.164 destination is authenticated - offer metadata, the usable source line comes from the credential, and the - gateway is authoritative for routing and telephone state. -- Offers are live session state, not an offline inbox. Withdrawing the offer or - losing its publisher cancels an unanswered call. Durable notifications, - voicemail, retries after disconnect, and webhook delivery remain separate - product surfaces. -- Keep IMS registration, native handset integration, roaming, emergency - calling, lawful intercept, number provisioning, SMS/MMS/RCS, and carrier - compliance outside the experiment. The SIP adapter is the boundary to that - world. - -## Required - -- [Call fabric protocol](/quest/m2/carrier-voice/protocol.md) - versioned - namespaces, roles, state transitions, authorization, and both topologies -- [SIP call origination](/quest/m2/carrier-voice/sip-originate.md) - the shared - SIP stack originates one outbound audio call for the lab -- [Developer-to-SIP proof](/quest/m2/carrier-voice/proof.md) - a developer - publishes a call that reaches a SIP endpoint, with a passive second consumer -- [Carrier-voice verdict](/quest/m2/carrier-voice/verdict.md) - compare MoQ, - RTP, and RoQ, then record the smallest justified product surface - -## Related - -- [SIP media stack](/quest/m2/sip-stack.md) - the telephone-network adapter - this lab extends; the inbound-call product built on it is moq.pro - (downstream) work -- `@moq/room` - conferencing may eventually reuse its participant model, but is - not required by this experiment diff --git a/quest/m2/carrier-voice/proof.md b/quest/m2/carrier-voice/proof.md deleted file mode 100644 index df3b8b7f90d..00000000000 --- a/quest/m2/carrier-voice/proof.md +++ /dev/null @@ -1,35 +0,0 @@ -# [L] Developer-to-SIP proof - -## Goal - -A reproducible lab call starts when a developer client publishes a MoQ offer, -rings and answers at a real SIP endpoint, and carries bidirectional Opus audio. -A recorder or mock agent subscribes to the live call without either endpoint -creating a separate media connection. - -## Plan - -- Build the smallest standalone gateway beside the protocol and `moq-sip`: - subscribe to the configured line prefix, authorize the offer, originate the - SIP dialog, publish authoritative call state and received audio, then - subscribe to the developer leg and send that audio as RTP. Do not wire the - experiment into the moq.pro (downstream) edge or dashboard. -- Drive it with a Rust or TypeScript developer client and a scripted SIP - endpoint or interoperable softphone. One command starts the relay, gateway, - endpoint, client, and auxiliary subscriber; retained artifacts include state - transitions, synchronized audio timestamps, and packet captures. -- Prove happy-path ringing/answer/audio and the failure paths that define the - contract: rejection, caller cancellation, remote hangup, publisher loss, - unauthorized line use, spoofed source identity, and an auxiliary subscriber - without recording permission. -- Keep the second consumer passive so the proof measures MoQ's programmable - fanout rather than designing conferencing. The gateway-to-gateway topology - receives an architecture-level walkthrough using the same roles and wire, - but no second gateway implementation. - -## Required - -- [Call fabric protocol](/quest/m2/carrier-voice/protocol.md) - fixes the wire, - authority, and lifecycle the lab implements -- [SIP call origination](/quest/m2/carrier-voice/sip-originate.md) - supplies - the outbound telephone leg diff --git a/quest/m2/carrier-voice/protocol.md b/quest/m2/carrier-voice/protocol.md deleted file mode 100644 index 1ea89aaa437..00000000000 --- a/quest/m2/carrier-voice/protocol.md +++ /dev/null @@ -1,44 +0,0 @@ -# [M] Call fabric protocol - -## Goal - -A versioned experimental protocol defines how authenticated call legs offer, -accept, carry, and end an audio call over ordinary MoQ. It describes both -developer-to-gateway and gateway-to-gateway calls without exposing phone -numbers in namespaces or trusting caller-supplied identity. - -## Plan - -- Define a project-scoped line inbox and opaque call/leg hierarchy. The shape - starts at `voice/lines//calls//legs/`; each leg - publishes only its own broadcast, containing an Opus audio track and a - versioned state track. The exact wire lives beside the Rust and TypeScript - implementations, not only in this quest. -- The first caller-leg state is an offer. For outbound telephone calls it - carries the E.164 destination and requested capabilities. Gateway-authored - states report routing, ringing, answer, rejection, and termination. Define - ordering, duplicate/replay handling, terminal-state behavior, cancellation - on withdrawal, and simultaneous teardown so reconnects cannot resurrect a - call. -- Authorization assigns roles rather than trusting path text: a caller may - publish its leg and request use of a configured line, the carrier gateway - validates that line and publishes authoritative telephone state, the remote - leg publishes its media, and an auxiliary consumer receives a least-privilege - subscription to the call. A source number is derived from the credential and - line configuration, never accepted from offer metadata. -- Use standard namespace discovery to notice new calls under an authorized - line prefix. Do not extend MOQT. Bound offer lifetime, state-object size, - call count, and per-line concurrency, and specify what is observable to a - relay even when media objects are encrypted. -- Include sequence diagrams for developer-to-SIP and gateway-to-gateway calls, - plus a threat model covering number enumeration, caller-ID spoofing, path - injection, unauthorized recording, replay, abandoned offers, and confused - deputy use of a carrier trunk. -- Land shared schema/types and state-machine tests in this repository. Keep - HTTP/webhooks out of the wire; the verdict may recommend them later as a - durable product-control surface without changing the live media model. - -## Related - -- [SIP call origination](/quest/m2/carrier-voice/sip-originate.md) - adapts the - telephone leg to the protocol diff --git a/quest/m2/carrier-voice/sip-originate.md b/quest/m2/carrier-voice/sip-originate.md deleted file mode 100644 index c973fbbac2a..00000000000 --- a/quest/m2/carrier-voice/sip-originate.md +++ /dev/null @@ -1,32 +0,0 @@ -# [M] SIP call origination - -## Goal - -The `moq-sip` stack can originate one audio-only SIP call and expose the -resulting dialog as Opus frames in and out. The first consumer is the -programmable carrier-voice lab, not a production outbound-calling product. - -## Plan - -- Extend the selected SIP stack rather than building a second SIP adapter. The - embedder supplies the request URI, asserted line identity, credentials, and - Opus source/sink; the crate owns INVITE transactions, SDP offer/answer, - provisional and final responses, RTP/SRTP, cancellation, and BYE. -- Reuse the inbound stack's Opus/G.711 negotiation, transcoding, RTP clock - normalization, and teardown. Exercise ringing, answer, rejection, caller - cancellation, remote hangup, and timeout against a real softphone or test - PBX. -- Keep PSTN routing, number ownership, caller-ID policy, emergency calling, - registrar support, DTMF, billing, and production trunk credentials outside - this quest. The lab gateway decides whether an authenticated caller may use - a line before it asks `moq-sip` to originate. - -## Required - -- [SIP media stack](/quest/m2/sip-stack.md) - origination extends the same - dialog, codec, and RTP implementation - -## Related - -- [Developer-to-SIP proof](/quest/m2/carrier-voice/proof.md) - the first - end-to-end consumer diff --git a/quest/m2/carrier-voice/verdict.md b/quest/m2/carrier-voice/verdict.md deleted file mode 100644 index f80046a1876..00000000000 --- a/quest/m2/carrier-voice/verdict.md +++ /dev/null @@ -1,44 +0,0 @@ -# [M] Carrier-voice verdict - -## Goal - -A measured go/no-go verdict decides whether MoQ earns a maintained role in -programmable carrier voice, and if so whether that role is developer-facing, -an internal gateway fabric, or both. An inconclusive result creates no product -commitment. - -## Plan - -- Replay the same Opus source through direct RTP, the MoQ lab path, and - [RTP over QUIC](https://datatracker.ietf.org/doc/draft-ietf-avtcore-rtp-over-quic/) - (RoQ). Its current Internet-Draft is expired prior art, not an assumed - adoption target: use a credible implementation if one remains runnable; - otherwise record why that arm cannot support a product decision instead of - building a second production stack just for the comparison. -- Use fixed clean, constrained-cellular, random-loss, burst-loss, and simulated - Wi-Fi/cellular path-change profiles. Record call setup time, one-way audio - latency and jitter, late/lost frames, recovery gaps, wire overhead, gateway - CPU, and connection continuity. Keep codec, packetization, source audio, - network trace, and hardware fixed across arms. -- Measure the proposed advantage directly: attach the auxiliary subscriber and - report its incremental setup work, latency, bandwidth, and gateway CPU. Also - document the equivalent RTP media-fork implementation so "programmable" is - compared against a real alternative rather than asserted. -- A go requires the full call lifecycle and mobility profiles to complete - without a protocol workaround, and MoQ's p99 one-way latency to stay within - 50 ms of direct RTP while the auxiliary subscriber remains an ordinary - authorized subscription. Treat the threshold as a rejection bound, not a - claim that a 50 ms regression is desirable. -- The verdict separately answers: whether in-band MoQ call control is simpler - than HTTP plus media streams, whether QUIC path migration helps in the - implementations we can actually ship, whether object overhead is acceptable - for 20 ms audio, and whether gateway-to-gateway transport adds value beyond - the developer-facing API. Recommend only the smallest surface supported by - the evidence and create implementation quests only for that surface. -- The conventional inbound SIP gateway product is moq.pro (downstream) work - and remains the standing telephone path regardless of this verdict. - -## Required - -- [Developer-to-SIP proof](/quest/m2/carrier-voice/proof.md) - provides the - working MoQ path and reproducible harness diff --git a/quest/m2/catalog-tracks.md b/quest/m2/catalog-tracks.md index 4726ec7c408..d301e2dd904 100644 --- a/quest/m2/catalog-tracks.md +++ b/quest/m2/catalog-tracks.md @@ -2,42 +2,32 @@ ## Goal -Choose how a catalog describes a track over its lifetime so live playback and -recorded playback do not guess which configuration applies to a media group. -Explore immutable track definitions as an alternative to correlating catalog -updates with groups. This is independent of DVR and does not gate archives. +A track's catalog definition never changes for its name, so live and recorded +playback never guess which configuration applies to a group. A publisher whose +track configuration changes either refuses the change or publishes it under a +new track name or a new broadcast epoch. This is independent of DVR and does +not gate archives. ## Plan -There is no explicit catalog-update-to-group binding. Timestamps alone do not -establish one. Audit publishers, consumers, and catalog composition in Rust and -JS to identify which track properties change today and why: codec/config bytes, -resolution, audio layout, rendition metadata, and broadcast references. - -Compare two approaches with concrete publish and playback examples: - -- Make each track definition immutable for its identity. A configuration change - creates a new track identity instead of changing the meaning of existing - groups. This is the preferred direction to investigate, not a settled API. -- Keep mutable definitions with an explicit configuration identity or update - boundary that groups can reference. Measure the protocol and lifecycle cost - against immutable definitions rather than assuming version binding is needed. - -Distinguish immutable track definitions from a completely immutable catalog. -Decide whether catalogs may add/remove tracks or change presentation metadata, -what happens to removed track identities, and whether a name can be reused. -Cover codec changes, rendition switches, reconnects, late joiners, reordered -catalog/media delivery, and readers seeking older groups. Evaluate what catalog -state must remain discoverable when media outlives the publishing session; -retaining snapshots alone cannot establish which configuration a group uses. - -Present the recommendation and migration costs for maintainer agreement before -changing public APIs or wire semantics. Produce focused implementation quests -for the chosen design, including Rust/JS and binding synchronization, HLS/watch -behavior, draft changes, and CI regression coverage. Target any published API -break at dev. Do not add an archive-only version index or change DVR retention -as a substitute for deciding track identity. +Decided in the 2026-09-30 audit: track identity is immutable. Mutable +definitions with a configuration identity that groups reference (the old +option 2) are out, because they contradict the rule that a track name always +means the same content, and MoQ has no ETag-style invalidation. + +Audit publishers in Rust and JS for the properties that change mid-track +today (codec/config bytes, resolution, audio layout, rendition metadata) and +make each one either refuse the change or mint a new identity: a new track +name through a [catalog alias](/quest/m1/catalog-track-alias.md) when the +catalog can keep both, or a new [broadcast epoch](/quest/m1/broadcast-epoch/README.md) +when the whole broadcast restarts. The catalog may still add and remove +tracks; a removed name is never reused for different content. + +Cover codec changes, rendition switches, reconnects, and late joiners in Rust, +JS, and HLS/watch tests. Target any published API break at `dev`. ## Related -- [Archive](/quest/m1/archive/README.md) - storage and replay consume the eventual identity contract +- [Catalog track alias](/quest/m1/catalog-track-alias.md) - lets a catalog list a new track name for a changed rendition +- [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - a restart is a new epoch rather than a changed track +- [Archive](/quest/m1/archive/README.md) - storage and replay consume the identity contract diff --git a/quest/m1/closure-counters.md b/quest/m2/closure-counters.md similarity index 95% rename from quest/m1/closure-counters.md rename to quest/m2/closure-counters.md index 04fb95b8cf3..347c37f708d 100644 --- a/quest/m1/closure-counters.md +++ b/quest/m2/closure-counters.md @@ -9,6 +9,8 @@ explicit fresh segment. The rule is documented as a consumer-facing contract. ## Plan +Deferred to m2 in the 2026-09-30 audit: no named consumer. + The stickiness fix ([moq#3625](https://github.com/moq-dev/moq/pull/3625)) keeps a departed node's last `Traffic` contribution and drops `Presence` immediately. Its review raised an open P2: retiring the gauges advances the diff --git a/quest/m2/color-catalog.md b/quest/m2/color-catalog.md new file mode 100644 index 00000000000..15318849d29 --- /dev/null +++ b/quest/m2/color-catalog.md @@ -0,0 +1,56 @@ +# [M] Catalog colour model + +## Goal + +The Hang catalog describes a video rendition's colour: primaries, transfer +characteristics, matrix coefficients, range, and the HDR10 mastering display and +content light levels. A renderer can set up its pipeline from the catalog +instead of guessing or reparsing the bitstream. + +## Plan + +Deferred to m2 in the 2026-09-30 audit: no renderer consumes colour today, so +the model waits for one. Encoder colour correctness stays in m1 as +[Encoder colour](/quest/m1/color-model.md). + +`rs/hang/src/catalog/video/mod.rs` has carried a bare `// TODO color space` since +the config was written. Two codecs already expose colour per their own syntax: +`VP9` carries primaries, transfer characteristics, matrix coefficients, and +range inside its codec string, and `AV1` has the same fields, which +`rs/moq-mux/src/codec/av1/import.rs` fills from the sequence header. They only +round-trip through muxers (the fMP4 exporter writes VP9's into `vpcC`); no +renderer consumes either, H.264 and H.265 have no equivalent, and there is no HDR10, +mastering display, or content light handling in `rs/` or `js/` at all. So an +HDR broadcast is delivered today and rendered as if it were SDR, whatever the +source signalled. + +Model the codec-neutral properties rather than one codec's syntax, so H.264 and +H.265 VUI, AV1 colour config, and a container's `colr` box all populate the same +fields. Generalize the existing VP9 and AV1 fields into that model rather than +adding a second colour source beside them: the codec-specific fields keep their +wire meaning (the VP9 codec string is defined by its spec) and feed the neutral +fields at import, so a renderer reads one place. Fill them at import from +whichever source the rendition provides, and emit them on export. + +Settle the precedence before adding the fields, because these sources disagree +in real files and a renderer must not see a different answer per import path. +Prefer the bitstream over the container: VUI and the AV1 colour config are what +the encoder actually signalled and travel with the elementary stream, while a +`colr` box is added by a muxer that may be wrong or stale. Record which source +won so a conflict is diagnosable rather than invisible, and treat an +unspecified value as absent rather than as a signalled default, so a partial +container box does not override a complete bitstream. + +Static display properties belong here rather than in a timed track, which is +also where the HDR10 metadata that lives in H.26x SEI should land once it can be +read. That is the one seam with the SEI line, and it runs in one direction: +this quest gives display metadata a home, and does not depend on SEI work. + +Test each source of truth in isolation, a source that signals nothing, a +conflict between VUI and container resolving to the bitstream, a container box +that fills a gap the bitstream left unspecified, and an SDR round trip that +stays byte-identical. + +## Related + +- [Encoder colour](/quest/m1/color-model.md) - encoders signal the colour they actually produce diff --git a/quest/m2/cpp-vcpkg.md b/quest/m2/cpp-vcpkg.md index 36ffc7427f0..646839fbbe3 100644 --- a/quest/m2/cpp-vcpkg.md +++ b/quest/m2/cpp-vcpkg.md @@ -30,4 +30,4 @@ CI on Windows, macOS, and Linux. ## Related -- [Conan remote](/quest/m2/cpp-conan.md) - the same tarball through Conan +- [Conan remote](/quest/m3/cpp-conan.md) - the same tarball through Conan diff --git a/quest/m1/emsg.md b/quest/m2/emsg.md similarity index 93% rename from quest/m1/emsg.md rename to quest/m2/emsg.md index 505d9c3f7b4..77af76c5813 100644 --- a/quest/m1/emsg.md +++ b/quest/m2/emsg.md @@ -13,6 +13,8 @@ it rather than restating it. Deferred SEI extraction is not a prerequisite. ## Plan +Deferred to m2 in the 2026-09-30 audit: no named consumer for timed metadata. + The shared contract, recorded here and mirrored in the Hang draft: - Publish an event as soon as it is received, on its own group sequence; never @@ -55,8 +57,8 @@ byte-identical. ## Related -- [ID3 catalog section](/quest/m1/id3.md) - gives one payload type carried here a - typed contract - [AV1 metadata OBUs](/quest/m2/av1-metadata.md) - the same silent drop in a different layer -- [FLV script tags](/quest/m1/flv-script.md) - likewise +- [ID3 catalog section](/quest/m2/id3.md) - gives one payload type carried here a + typed contract +- [FLV script tags](/quest/m2/flv-script.md) - likewise diff --git a/quest/m2/flate.md b/quest/m2/flate.md new file mode 100644 index 00000000000..04d30073a51 --- /dev/null +++ b/quest/m2/flate.md @@ -0,0 +1,40 @@ +# [M] Flate tracks in every binding + +## Goal + +Opaque tracks, compressed per group or not, are published and consumed the +same way from every language, not only Rust and JS, and the bytes on the wire +are identical across all of them. A track published from a wrapper decodes in +the browser with `@moq/flate` and vice versa. + +## Plan + +Decided in the 2026-09-30 audit: collapse the line into this quest and follow +the `json` namespace pattern that [#4526](https://github.com/moq-dev/moq/pull/4526) +sets, rather than the per-wrapper siblings of the old bindings quest. + +`moq-flate` and `@moq/flate` absorb `moq-binary`'s snapshot and stream modes +in moq-binary's fold into moq-flate ([#4425](https://github.com/moq-dev/moq/pull/4425), on `dev`), so the crate +already owns the per-group window a caller could otherwise desynchronize. +Bind those track modes, not the bare codec: a `frame()` call across the FFI +boundary invites the window desync the track modes exist to prevent. + +#4526 removes moq-ffi's `publish_binary_*` and adds `MoqFlate*Producer::new` +constructed from a track producer, as `json` does. What remains: + +- moq-ffi has no consume side for flate tracks. Add consumers mirroring the + `json` ones so each wrapper can read what it writes. +- Each wrapper (Python, Swift, Kotlin, Go, Dart) gains a `flate` namespace in + the same place and shape as its `json` one. +- Document in `doc/lib/{py,swift,kt,go,dart}` beside the JSON entry. +- Tests: a round trip in each wrapper that has tests, and one cross-language + check that a wrapper-published group decodes with `@moq/flate`. Run + `just test interop --all`. + +Public API: additive on top of #4526. Wire, catalog, and relay: none. +Compression stays invisible to `moq-net`; a compressed track is announced, +routed, and cached like any other. + +## Required + +- [JSON](/quest/m1/ffi-shape/json.md) - sets the `json` and `flate` namespace pattern this follows diff --git a/quest/m2/flate/README.md b/quest/m2/flate/README.md deleted file mode 100644 index abb54d689d7..00000000000 --- a/quest/m2/flate/README.md +++ /dev/null @@ -1,22 +0,0 @@ -# Compressed tracks - -## Goal - -Opaque tracks, compressed per group or not, are published and consumed the -same way from every language, not only Rust and JS, and the bytes on the wire -are identical across all of them. - -## Plan - -`moq-flate` and `@moq/flate` absorb `moq-binary`'s snapshot and stream modes -in moq-binary's fold into moq-flate ([#4425](https://github.com/moq-dev/moq/pull/4425), on `dev`), so the crate -already owns the per-group window a caller could otherwise desynchronize. The -track wrapper this line once planned was dropped for that reason. What -remains is reaching those tracks from the hand-written binding wrappers. - -No wire, catalog, or relay impact. Compression stays invisible to `moq-net`; -a compressed track is announced, routed, and cached like any other. - -## Required - -- [Bindings](/quest/m2/flate/bindings.md) - the hand-written wrappers expose flate tracks diff --git a/quest/m2/flate/bindings.md b/quest/m2/flate/bindings.md deleted file mode 100644 index bf6f8042b9e..00000000000 --- a/quest/m2/flate/bindings.md +++ /dev/null @@ -1,32 +0,0 @@ -# [M] Flate bindings - -## Goal - -The hand-written wrappers (Python, Swift, Kotlin, Go, Dart) expose flate -tracks, the snapshot and stream opaque tracks moq-ffi already generates, in -their own idiom beside the JSON entry. A track published from a wrapper -decodes in the browser with `@moq/flate` and vice versa. - -## Plan - -moq-ffi publishes opaque tracks today (`publish_binary_snapshot` and -`publish_binary_stream`, #4137), renamed after `flate` by -moq-binary's fold into moq-flate ([#4425](https://github.com/moq-dev/moq/pull/4425), on `dev`). Only the -generated bindings reach them; no wrapper does. This quest binds the existing -track modes, not the bare codec: a `frame()` call across the FFI boundary -invites the window desync the track modes exist to prevent. - -- moq-ffi has no consume side for these tracks. Add it next to the JSON - consumers so each wrapper can read what it writes. -- Wrappers per the Cross-Package Sync table: `go/wrapper/json.go`, - `py/moq-rs/moq/{publish,subscribe}.py`, `swift/Sources/Moq/Json.swift`, - `kt/moq`'s `Json.kt` with its `Aliases.kt` re-exports, and - `dart/moq/lib/src/aliases.dart` each gain a flate sibling. If - [FFI shape](/quest/m1/ffi-shape/README.md) has landed, follow its `flate` - namespace instead. -- Document in `doc/lib/{py,swift,kt,go,dart}` beside the JSON entry. -- Tests: a round trip in each wrapper that has tests, and one cross-language - check that a wrapper-published group decodes with `@moq/flate`. Run - `just test interop --all`. - -Public API: additive on moq-ffi and every wrapper. Wire: none. diff --git a/quest/m1/flv-script.md b/quest/m2/flv-script.md similarity index 82% rename from quest/m1/flv-script.md rename to quest/m2/flv-script.md index 27dc2919cd2..0d90021f9c3 100644 --- a/quest/m1/flv-script.md +++ b/quest/m2/flv-script.md @@ -7,6 +7,8 @@ FLV script tags survive RTMP and FLV import instead of being discarded, so ## Plan +Deferred to m2 in the 2026-09-30 audit: no named consumer for timed metadata. + `rs/moq-mux/src/container/flv/import.rs` matches `TAG_SCRIPT => {}` and moves on, which drops every AMF data message an encoder sends. `onMetaData` is the one every RTMP publisher emits, and applications routinely push their own cues @@ -15,7 +17,7 @@ through the same channel. Carry raw tag payloads without decoding AMF into a fixed vocabulary. Publish when received on independently sequenced metadata groups, with event time on the broadcast clock and source placement per the contract -[emsg](/quest/m1/emsg.md) settles. Tags before media +[emsg](/quest/m2/emsg.md) settles. Tags before media are delivered immediately and retain explicit pre-media placement; audio-only and script-only input do not require a dummy video rendition. Where `onMetaData` duplicates something the catalog already models (dimensions, @@ -26,12 +28,6 @@ Export reproduces the tags on the FLV path. Test `onMetaData`, an application message with a custom name, AMF0 and AMF3 payloads, a tag before the first media tag, and a byte-identical round trip. -## Required - -- [fMP4 emsg](/quest/m1/emsg.md) - settles the shared framing and missing-data semantics before this section adopts them - ## Related -- [fMP4 emsg carriage](/quest/m1/emsg.md) - the same silent drop in a different - layer - [AV1 metadata OBUs](/quest/m2/av1-metadata.md) - likewise diff --git a/quest/m2/gop-overhead.md b/quest/m2/gop-overhead.md index 9c9a8649b37..e19576e6d0e 100644 --- a/quest/m2/gop-overhead.md +++ b/quest/m2/gop-overhead.md @@ -36,3 +36,7 @@ this quest. ## Closes - [#2284](https://github.com/moq-dev/moq/issues/2284) - close this issue when the quest finishes + +## Related + +- [Intra-refresh GOPs](/quest/m2/intra-refresh/README.md) - refresh encoding is the flat-bitrate alternative this verdict prices diff --git a/quest/m1/id3.md b/quest/m2/id3.md similarity index 87% rename from quest/m1/id3.md rename to quest/m2/id3.md index 4d5f1d019f2..dcec002c744 100644 --- a/quest/m1/id3.md +++ b/quest/m2/id3.md @@ -10,8 +10,10 @@ stream. ## Plan +Deferred to m2 in the 2026-09-30 audit: no named consumer for timed metadata. + Define the catalog section and frame contract for complete ID3 tags on the -shared event contract [emsg](/quest/m1/emsg.md) settles. Publish tags when +shared event contract [emsg](/quest/m2/emsg.md) settles. Publish tags when received on independently sequenced groups, with their presentation time on the broadcast clock and an optional association to the program's rendition. ID3-only programs need no artificial media owner. Carry original tag bytes, @@ -35,11 +37,7 @@ large tags spanning PES packets, timestamp wrap, discontinuity, and an ID3-only program. Include non-ID3 and malformed stream type `0x15` fixtures that remain generic. -## Required - -- [fMP4 emsg](/quest/m1/emsg.md) - settles the shared framing and missing-data semantics before this section adopts them - ## Related -- [SEI sidecars](/quest/m2/sei/README.md) - the separate codec metadata +- [SEI sidecars](/quest/m2/sei.md) - the separate codec metadata contract diff --git a/quest/m2/intra-refresh/README.md b/quest/m2/intra-refresh/README.md index ca1405bcac5..c606b28fe0e 100644 --- a/quest/m2/intra-refresh/README.md +++ b/quest/m2/intra-refresh/README.md @@ -5,9 +5,14 @@ Video encoded with periodic intra refresh has no keyframes. Each frame refreshes a stripe of the picture, so a decoder that starts at the beginning of a sweep is clean once the sweep completes, and the bitrate never spikes. This questline -makes such video a first-class hang broadcast at both ends: our encoders can -emit it, streams contributed that way import cleanly, and every viewer tunes in -without a visible glitch. +makes such video a first-class hang broadcast on import and playback: streams +contributed that way import cleanly, and every viewer tunes in without a +visible glitch. + +Decided in the 2026-09-30 audit: the encode side (shared config, NVENC, V4L2, +bindings) moved to m3 pending the [GOP overhead](/quest/m2/gop-overhead.md) +verdict. Import and playback stay here because contributed feeds already use +intra refresh regardless of what our encoders do. The motivations, in the order they settle tradeoffs: a flat bitrate at low latency, so a bandwidth grant holds; faster tune-in, since a short refresh cycle @@ -29,22 +34,14 @@ Decisions the quests share: mid-stream skip both decode everything and present nothing until recovery, freezing on the last good frame. A group that opens on a true IDR shows at once. -- The shared encode config extends the `Gop` contract settled in main, - and a cut in refresh mode starts a new sweep, never an IDR. - H.264 and H.265 only. AV1 and VP9 have no standard gradual refresh signal. - WebCodecs has no intra-refresh option, so js/publish is consumer-only here. - Backends without the knob refuse refresh mode; NVENC and V4L2 get it now, - Media Foundation and MediaCodec are follow-ups. + WebCodecs has no intra-refresh option, so js/publish is consumer-only. ## Required - [Consumer warmup](/quest/m2/intra-refresh/consumer-warmup.md) - JS and Rust viewers join `warmup` earlier and withhold display until recovery, except at a true IDR - [H.264 import](/quest/m2/intra-refresh/h264-import.md) - the splitter keeps `recovery_frame_cnt` and import publishes `warmup` from it - [H.265 import](/quest/m2/intra-refresh/h265-import.md) - the splitter reads the recovery-point SEI so an HEVC intra-refresh stream forms groups and publishes `warmup` -- [Encode config](/quest/m2/intra-refresh/encode-config.md) - refresh mode extends the settled GOP contract; the producer cuts groups per sweep and publishes `warmup` -- [NVENC refresh](/quest/m2/intra-refresh/nvenc-refresh.md) - the NVENC backend encodes refresh mode for H.264 and HEVC -- [V4L2 refresh](/quest/m2/intra-refresh/v4l2-refresh.md) - the V4L2 backend encodes refresh mode -- [Bindings](/quest/m2/intra-refresh/bindings.md) - moq-ffi and every wrapper expose refresh mode, additive on the ffi-shape `Gop` enum - [Export sync flags](/quest/m2/intra-refresh/export-sync-flags.md) - fmp4, MKV, and HLS stop advertising a refresh group start as a sync sample ## Related @@ -52,3 +49,5 @@ Decisions the quests share: - [Audio warmup](/quest/m1/audio-warmup.md) - Opus convergence after a mid-stream join uses the same `warmup` field - [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - frames stamped before the group's keyframe are the other tune-in trim - [Catalog warmup](/quest/m1/catalog-warmup.md) - the generic `warmup` field this line reads, kept in m1 for audio and open-GOP tune-in +- [GOP overhead](/quest/m2/gop-overhead.md) - the verdict that decides whether our encoders emit refresh mode +- [Encode config](/quest/m3/intra-refresh-encode-config.md) - refresh-mode groups on the `Gop` contract, parked with NVENC, V4L2, and bindings behind it diff --git a/quest/m2/js-discontinuity.md b/quest/m2/js-discontinuity.md deleted file mode 100644 index 0270c141b2f..00000000000 --- a/quest/m2/js-discontinuity.md +++ /dev/null @@ -1,22 +0,0 @@ -# [XS] JS discontinuity() writes no estimated end - -## Goal - -`@moq/hang`'s `discontinuity()` without an explicit end closes the group with -no cadence-estimated end, as Rust `moq_mux::container::Producer::discontinuity` -does. Whatever resumes can land sooner than one estimated frame later (a -capture swap), and an end past it reads as a rewind to every consumer. - -## Plan - -The rename landed on `dev` in #4141 and kept the old behavior: in -`js/hang/src/container/legacy.ts`, `discontinuity(end?)` calls `#close(end)`, -which fills a missing `end` with `#end + #interval`. Rust's `discontinuity()` -calls `close(None, None)` and clears the cadence first. - -Give the break its own close path that passes no estimate when the caller -gave no end, leaving the routine close's estimate alone. Test that a -discontinuity after a steady cadence writes no end past the last frame. - -Public API: behavior change in `@moq/hang`'s `discontinuity()`, which exists -only on `dev`, so it targets `dev`. Wire: none. diff --git a/quest/m1/ladder/README.md b/quest/m2/ladder/README.md similarity index 94% rename from quest/m1/ladder/README.md rename to quest/m2/ladder/README.md index 0c242cc396d..ebb9027691c 100644 --- a/quest/m1/ladder/README.md +++ b/quest/m2/ladder/README.md @@ -15,6 +15,9 @@ state. ## Plan +Deferred to m2 in the 2026-09-30 audit: no named consumer for the +publisher-side ladder. + The catalog and player half already shipped in [moq#2865](https://github.com/moq-dev/moq/pull/2865): the optional `stalled` state exists in `rs/hang`, `js/hang`, `rs/moq-msf`, `js/msf`, the HANG draft @@ -73,9 +76,9 @@ encoders on every target change. ## Required -- [Controller](/quest/m1/ladder/controller.md) - one controller owns every +- [Controller](/quest/m2/ladder/controller.md) - one controller owns every rung's share, target, stalled state, and send order -- [Fetch and catalog](/quest/m1/ladder/fetch.md) - uncached FETCH encodes at +- [Fetch and catalog](/quest/m2/ladder/fetch.md) - uncached FETCH encodes at the shared applied target, and rung state survives a source catalog refresh ## Closes diff --git a/quest/m1/ladder/controller.md b/quest/m2/ladder/controller.md similarity index 98% rename from quest/m1/ladder/controller.md rename to quest/m2/ladder/controller.md index 32ba4c18604..53015fe2171 100644 --- a/quest/m1/ladder/controller.md +++ b/quest/m2/ladder/controller.md @@ -18,7 +18,7 @@ today's fixed-rate behavior exactly and never publishes congestion-induced `stalled` state, which is what keeps this additive. The controller subdivides that estimate across the ladder and applies the -band boundary from the [questline](/quest/m1/ladder/README.md), including the +band boundary from the [questline](/quest/m2/ladder/README.md), including the lowest rung's `max / 3` case. `moq_transcode::Ladder` is ascending: `new` sorts by configured maximum (`rs/moq-transcode/src/ladder.rs:101`) and `rungs()` is lowest first (`:125-128`), so the next lower rendition the diff --git a/quest/m1/ladder/fetch.md b/quest/m2/ladder/fetch.md similarity index 95% rename from quest/m1/ladder/fetch.md rename to quest/m2/ladder/fetch.md index 54630fedcec..4e529ecc2a0 100644 --- a/quest/m1/ladder/fetch.md +++ b/quest/m2/ladder/fetch.md @@ -31,5 +31,5 @@ intact. ## Required -- [Controller](/quest/m1/ladder/controller.md) - there is no shared applied +- [Controller](/quest/m2/ladder/controller.md) - there is no shared applied target to read until the controller owns one diff --git a/quest/m2/livekit-webrtc-bridge.md b/quest/m2/livekit-webrtc-bridge.md deleted file mode 100644 index 3cc4f54ed7c..00000000000 --- a/quest/m2/livekit-webrtc-bridge.md +++ /dev/null @@ -1,27 +0,0 @@ -# [M] LiveKit WebRTC bridge evaluation - -## Goal - -A go/no-go verdict, backed by a working spike, on bridging LiveKit rooms to -MoQ per-track over WebRTC using LiveKit's Rust SDK: a native participant -joins the room and republishes its tracks into MoQ, optionally the reverse. -The verdict decides whether this becomes a maintained gateway. - -## Plan - -- The zero-code paths already exist and bound the value: LiveKit Egress - pushes RTMP/SRT into the existing gateways today (composited and - transcoded), and `moq export rtc --connect` publishes WHIP into LiveKit - Ingress. LiveKit has no WHIP/WHEP egress, so per-track LiveKit to MoQ - requires joining the room as a participant via livekit rust-sdks - (Apache 2.0, no Chrome/GStreamer). -- Spike it in-tree: a rust-sdks participant subscribes to all tracks and - republishes via moq-net + moq-mux, with codec passthrough where possible - (Opus/VP8/VP9; H.264 through the Annex-B importer). -- Assess dependency weight of the webrtc stack, per-track fidelity versus the - Egress paths, simulcast handling, and where a real gateway would live (edge - versus standalone). - -## Related - -- [LiveKit client shim](/quest/m2/livekit-shim.md) diff --git a/quest/m2/mobile-capture-android.md b/quest/m2/mobile-capture-android.md index 0c69542352f..7482917a804 100644 --- a/quest/m2/mobile-capture-android.md +++ b/quest/m2/mobile-capture-android.md @@ -23,7 +23,7 @@ so the mechanism exists. ## Required -- [Ownership boundary](/quest/m2/mobile-ownership.md) - decides whether an NDK/JNI backend family is worth building +- [Ownership boundary](/quest/m1/mobile-ownership.md) - decides whether an NDK/JNI backend family is worth building ## Related diff --git a/quest/m2/mobile-capture-ios.md b/quest/m2/mobile-capture-ios.md index 968dfc596d8..b24bcb8e0bb 100644 --- a/quest/m2/mobile-capture-ios.md +++ b/quest/m2/mobile-capture-ios.md @@ -24,7 +24,7 @@ same everywhere. ## Required -- [Ownership boundary](/quest/m2/mobile-ownership.md) - decides whether Rust owns capture on mobile at all +- [Ownership boundary](/quest/m1/mobile-ownership.md) - decides whether Rust owns capture on mobile at all ## Related diff --git a/quest/m2/mobile-completion.md b/quest/m2/mobile-completion.md index 7770a0280f2..8490656ed71 100644 --- a/quest/m2/mobile-completion.md +++ b/quest/m2/mobile-completion.md @@ -24,9 +24,9 @@ Do not close #700 merely because its next subset or a design decision finished. - [Dart on iOS](/quest/m1/dart-ios.md) - the Dart iOS asset proof - [Dart codec parity](/quest/m1/dart-codecs.md) - codec-enabled artifacts and Dart video consumer integration -- [Mobile ownership](/quest/m2/mobile-ownership.md) - select and scope the mobile media architecture - [iOS capture](/quest/m2/mobile-capture-ios.md) - deliver the selected iOS capture path - [Android capture](/quest/m2/mobile-capture-android.md) - deliver the selected Android capture and codec path +- [Mobile ownership](/quest/m1/mobile-ownership.md) - select and scope the mobile media architecture ## Closes diff --git a/quest/m2/mobile-ownership.md b/quest/m2/mobile-ownership.md deleted file mode 100644 index 14e17f4c940..00000000000 --- a/quest/m2/mobile-ownership.md +++ /dev/null @@ -1,26 +0,0 @@ -# [S] Plan: who owns capture, codecs, and rendering on mobile - -## Goal - -A written decision, recorded in this tree, on the mobile media boundary: -either Swift and Kotlin own camera, platform codecs, and rendering while Rust -carries encoded access units through the existing media APIs, or Rust owns -capture, codecs, and rendering and `moq-ffi` grows opaque native surface -bridges for `CVPixelBuffer` and Android `HardwareBuffer`/`Surface`. The -capture quests in this questline start only once this is settled. - -## Plan - -- Option 1 is smaller and idiomatic for an app SDK; option 2 avoids two - parallel media stacks and matches the in-tree direction of moq-video, at - the cost of native-handle ownership across the FFI. #700 lays both out. -- Weigh with evidence rather than preference: what `moq-kit` already does in - Kotlin over `moq-ffi`, what the iroh-live reimplementation says about the - Rust-native audience, and the copy cost of byte-array frames measured on a - device. -- Record the verdict here and in `rs/moq-ffi/AGENTS.md`, and re-estimate - [Android capture](/quest/m2/mobile-capture-android.md) and - [iOS capture](/quest/m2/mobile-capture-ios.md) against it; both target - `moq-video`, so replace them with the required platform-owned implementation - quests if the answer is option 1. Update [mobile completion](/quest/m2/mobile-completion.md) - to require those replacements before abandoning the Rust capture quests. diff --git a/quest/m1/moq-install-url.md b/quest/m2/moq-install-url.md similarity index 91% rename from quest/m1/moq-install-url.md rename to quest/m2/moq-install-url.md index 86a1378ba94..bcda57218ef 100644 --- a/quest/m1/moq-install-url.md +++ b/quest/m2/moq-install-url.md @@ -8,6 +8,9 @@ maintaining another copy of the install logic. ## Plan +Deferred to m2 in the 2026-09-30 audit: it follows [the +installer](/quest/m2/moq-installer.md), which is m2. + - Implement the hosting change in **moq-dev/moq.dev**, which owns the root website, not moq.pro. Track this cross-repository work here beside its installer dependency; complete this quest only after the website change @@ -27,8 +30,3 @@ maintaining another copy of the install logic. working. Keep upgrade and version-selection examples aligned with the canonical installer's interface. Add route coverage to the site's normal checks for the shell response/redirect and error behavior. - -## Required - -- [Install moq](/quest/m1/moq-installer.md) - canonical installer, release - selection, upgrade behavior, and tests are published first diff --git a/quest/m2/moq-installer.md b/quest/m2/moq-installer.md new file mode 100644 index 00000000000..c5c88937c05 --- /dev/null +++ b/quest/m2/moq-installer.md @@ -0,0 +1,52 @@ +# [S] One-command moq installation and upgrades + +## Goal + +A canonical Bash installer installs the released `moq` binary on supported +macOS and Linux machines without Rust or sudo. Running it again upgrades +the same installation; selecting a version supports +reproducible installs and deliberate downgrades. + +Install only `moq` from the `moq-cli` release. Token and relay functionality +belong to its subcommands, not separate installer choices. This work does +not implement those subcommands, automatic updates, a self-update command, +service setup, Windows support, or new release targets. + +## Plan + +Deferred to m2 in the 2026-09-30 audit: no named consumer; `cargo install`, +Nix, Docker, and winget already install `moq`. + +- Default to the latest stable `moq-cli` release, with an explicit version + option. Resolve that product's tags, not the repository-wide latest + release: this repository publishes multiple independently versioned crates. + Refuse missing versions, malformed input, and incomplete releases clearly. +- Verify the selected archive against the release's `SHA256SUMS`, extract it + into a temporary file in the destination directory, then atomically rename + it over the destination. A failed install leaves the prior binary untouched. + Decided in the 2026-09-30 audit: no journaled transaction or ownership + record; that was out of proportion for one binary. +- Support the existing targets: macOS ARM64 and Linux x86_64/ARM64 with + glibc 2.34 or newer. Refuse unsupported operating systems, architectures, + and libc variants with actionable diagnostics. +- Default to `~/.local/bin` with an explicit directory override. Do not invoke + sudo or edit shell profiles. Print the installed version and path, and PATH + instructions when needed. Warn when another `moq` on PATH takes precedence. + Refuse a destination that is a symlink, so a package manager's install is + never overwritten. +- Keep the canonical script and its tests in this repository, and publish a + usable HTTPS source for [the install URL](/quest/m2/moq-install-url.md). +- Document install, upgrade, version selection, directory override, and + removal in `doc/setup/install.md`. +- Wire installer tests into `just check` and CI: initial install, upgrade, + explicit downgrade, product-specific latest selection, unsupported hosts, + corrupt or missing assets, and a failure preserving the existing binary. + Run the script against real release assets in a temporary directory and + run the installed `moq --version`. + +## Related + +- [Binary release workflow](/quest/m1/tooling/release-binary.md) - reuse its + artifacts without requiring workflow consolidation +- [`moq relay`](/quest/m2/moq-relay-subcommand.md) - relay functionality joins + the same executable independently of its installation method diff --git a/quest/m1/moq-relay-subcommand.md b/quest/m2/moq-relay-subcommand.md similarity index 93% rename from quest/m1/moq-relay-subcommand.md rename to quest/m2/moq-relay-subcommand.md index 0c0453d7048..88833abf60b 100644 --- a/quest/m1/moq-relay-subcommand.md +++ b/quest/m2/moq-relay-subcommand.md @@ -9,6 +9,9 @@ decode, and render stack. ## Plan +Deferred to m2 in the 2026-09-30 audit: no named consumer, and [`moq --listen` +admission](/quest/m1/cli-serve.md) no longer waits on it. + `moq-relay` is lib+bin (`rs/moq-relay/Cargo.toml`), with a 15-line `main.rs` that installs the aws-lc-rs provider, optionally jemalloc, and calls `Relay::load(Config::load()?).await?.run()`. diff --git a/quest/m2/msfts-convergence.md b/quest/m2/msfts-convergence.md new file mode 100644 index 00000000000..ac9a67dc4a3 --- /dev/null +++ b/quest/m2/msfts-convergence.md @@ -0,0 +1,26 @@ +# [M] MPEG-TS lane converges with MSFTS ES-level carriage + +## Goal + +A subscriber author can map this repository's demultiplexed TS lane +(access units, Hang catalog `mpegts` section) onto MSFTS ES-level carriage +without guessing. Transporting TS verbatim is a non-goal. + +## Plan + +Decided in the 2026-09-30 audit: moved from m4 and the msfts#33 gate removed. +msfts#33 closed on 2026-09-28, answered by msfts#36 (merged 2026-09-24), and +egress moved to msfts#37 (closed). Two differences remain: + +- **Program tables.** MSFTS carries them in tracks; here they live in the + Hang catalog's `mpegts` section. Decide whether to publish a mapping from + the catalog section to MSFTS's table tracks, or change either side. +- **ES units.** MSFTS es-units carry the whole PES packet; here they carry the + payload plus `stream_id`. Decide whether the PES header fields we drop + matter to a subscriber, and converge or document the mapping. + +Update `drafts/draft-lcurley-moq-mpegts.md` and `doc/concept` with whatever +lands. Open TS PRs [#4577](https://github.com/moq-dev/moq/pull/4577) (per-ES +access units at export), [#4579](https://github.com/moq-dev/moq/pull/4579) +(export on the mux rate), and [#4580](https://github.com/moq-dev/moq/pull/4580) +(per-program SI) touch the same area; land or rebase on them first. diff --git a/quest/m2/nvenc-pool.md b/quest/m2/nvenc-pool.md index c1723df7283..bd6c851e7f8 100644 --- a/quest/m2/nvenc-pool.md +++ b/quest/m2/nvenc-pool.md @@ -15,4 +15,10 @@ quest and report the numbers. frames) on every `encode`, and frees them all at the end of the call. Keep a small pool sized by the frames in flight, which is one today since B-frames are off. Re-register a CUDA resource only when its pointer changes. Measure -with the `encode-presets` example from #4099. +with the `encode-presets` example from #4099, which so far exists only on the +[OBS moq-video](/quest/m1/obs-moq-video/README.md) line; if that line has not +merged, run it from that branch or add an encode benchmark on main instead. + +## Related + +- [OBS moq-video](/quest/m1/obs-moq-video/README.md) - carries the `encode-presets` example this measures with diff --git a/quest/m1/obs-moq-video/decode-linux.md b/quest/m2/obs-decode-linux.md similarity index 96% rename from quest/m1/obs-moq-video/decode-linux.md rename to quest/m2/obs-decode-linux.md index 8ee602d6867..cd5c24376d6 100644 --- a/quest/m1/obs-moq-video/decode-linux.md +++ b/quest/m2/obs-decode-linux.md @@ -17,4 +17,4 @@ At least one supported Linux hardware decoder delivers frames to OBS without CPU ## Related -- [VAAPI encode and decode](/quest/m4/video-vaapi.md) - owns remaining VAAPI decode and native surface gaps; avoid a duplicate backend implementation +- [VAAPI encode and decode](/quest/m2/video-vaapi.md) - owns remaining VAAPI decode and native surface gaps; avoid a duplicate backend implementation diff --git a/quest/m1/obs-moq-video/decode-windows.md b/quest/m2/obs-decode-windows.md similarity index 100% rename from quest/m1/obs-moq-video/decode-windows.md rename to quest/m2/obs-decode-windows.md diff --git a/quest/m1/obs-moq-video/macos.md b/quest/m2/obs-macos.md similarity index 100% rename from quest/m1/obs-moq-video/macos.md rename to quest/m2/obs-macos.md diff --git a/quest/m1/obs-moq-video/windows.md b/quest/m2/obs-windows.md similarity index 100% rename from quest/m1/obs-moq-video/windows.md rename to quest/m2/obs-windows.md diff --git a/quest/m1/one-port/README.md b/quest/m2/one-port/README.md similarity index 88% rename from quest/m1/one-port/README.md rename to quest/m2/one-port/README.md index 8e9fbe8e00c..d7c055b883a 100644 --- a/quest/m1/one-port/README.md +++ b/quest/m2/one-port/README.md @@ -20,6 +20,9 @@ reuseport shard groups are a later consumer, not a blocker. ## Plan +Deferred to m2 in the 2026-09-30 audit: the consumer is moq.pro's edge, SRT is +blocked upstream on srt-tokio, and STUN's only consumer is P2P, also m2. + ### Classifying a datagram RFC 7983 already partitions the first byte: STUN is 0 to 3, DTLS 20 to 63, @@ -73,11 +76,11 @@ pre-accepted streams can stand behind. ## Required -- [UDP demux](/quest/m1/one-port/udp-demux.md) - one socket carries QUIC, STUN answers, and the WebRTC media path, with greasing off -- [TCP acceptor](/quest/m1/one-port/tcp-demux.md) - one listener carries TLS-terminated HTTP, RTMP, and RTMPS -- [SRT on the shared socket](/quest/m1/one-port/srt-demux.md) - srt-tokio accepts a virtual socket and the flow table pins its 4-tuples +- [UDP demux](/quest/m2/one-port/udp-demux.md) - one socket carries QUIC and STUN answers, with greasing off and a WebRTC hook for embedders +- [TCP acceptor](/quest/m2/one-port/tcp-demux.md) - one listener carries TLS-terminated HTTP, RTMP, and RTMPS +- [SRT on the shared socket](/quest/m2/one-port/srt-demux.md) - srt-tokio accepts a virtual socket and the flow table pins its 4-tuples ## Related -- [P2P](/quest/m1/p2p/README.md) - the client that names the relay as its STUN server -- [Stream sessions](/quest/m1/uring-tcp/README.md) - the io_uring workers that would host the same demux later +- [P2P](/quest/m2/p2p/README.md) - the client that names the relay as its STUN server +- [Stream sessions](/quest/m2/uring-tcp/README.md) - the io_uring workers that would host the same demux later diff --git a/quest/m1/one-port/srt-demux.md b/quest/m2/one-port/srt-demux.md similarity index 94% rename from quest/m1/one-port/srt-demux.md rename to quest/m2/one-port/srt-demux.md index 92b3da2d155..d12a4920833 100644 --- a/quest/m1/one-port/srt-demux.md +++ b/quest/m2/one-port/srt-demux.md @@ -16,7 +16,7 @@ socket. Fallback if refused: `srt-protocol` is sans-io, so `moq-srt` drives its `Listen` and `Connection` state machines directly on fed packets, which is more code but removes the dependency on `srt-tokio`'s socket handling. -The demux side is the flow table from [UDP demux](/quest/m1/one-port/udp-demux.md): +The demux side is the flow table from [UDP demux](/quest/m2/one-port/udp-demux.md): a 4-tuple already pinned to WebRTC (ICE succeeded) is never tested for SRT. An unknown 4-tuple whose full SRT handshake header matches (control bit, type 0, and the SRT magic, not merely `80 00`) pins to SRT provisionally: @@ -35,5 +35,5 @@ with a QUIC client active on the same port; a QUIC short header from a new ## Required -- [UDP demux](/quest/m1/one-port/udp-demux.md) +- [UDP demux](/quest/m2/one-port/udp-demux.md) - srt-tokio accepts a caller-supplied socket abstraction upstream, or the sans-io fallback is chosen diff --git a/quest/m1/one-port/tcp-demux.md b/quest/m2/one-port/tcp-demux.md similarity index 96% rename from quest/m1/one-port/tcp-demux.md rename to quest/m2/one-port/tcp-demux.md index cdc71480197..4b973b9584a 100644 --- a/quest/m1/one-port/tcp-demux.md +++ b/quest/m2/one-port/tcp-demux.md @@ -34,4 +34,4 @@ against one listener each land in the right arm. ## Related -- [UDP demux](/quest/m1/one-port/udp-demux.md) - the UDP half +- [UDP demux](/quest/m2/one-port/udp-demux.md) - the UDP half diff --git a/quest/m1/one-port/udp-demux.md b/quest/m2/one-port/udp-demux.md similarity index 59% rename from quest/m1/one-port/udp-demux.md rename to quest/m2/one-port/udp-demux.md index 017ea18ac88..9b44ff448ca 100644 --- a/quest/m1/one-port/udp-demux.md +++ b/quest/m2/one-port/udp-demux.md @@ -2,17 +2,18 @@ ## Goal -`moq-relay` reads one UDP socket and serves QUIC, STUN Binding answers, and -the WebRTC media path from it. A WHIP or WHEP client sees ICE candidates on -the QUIC port, a P2P client can list `stun::`, and every -backend config has QUIC-bit greasing off so a short header is always -recognizable. +`moq-relay` reads one UDP socket and serves QUIC and STUN Binding answers from +it. A P2P client can list `stun::`, and every backend config has +QUIC-bit greasing off so a short header is always recognizable. The WebRTC +media path is an embedder hook: the demux hands its class to a virtual socket +an embedder such as moq.pro's edge can feed to `moq-rtc`, since `moq-relay` +serves no WHIP or WHEP. ## Plan `moq-sock` gains the demux: a task owning the OS socket (or shard) that classifies each datagram by the rules in the -[questline README](/quest/m1/one-port/README.md) and hands it to the matching +[questline README](/quest/m2/one-port/README.md) and hands it to the matching virtual socket, plus the flow table keyed by 4-tuple that SRT will need, built now so its shape is settled. Each virtual socket implements `AsyncUdpSocket`: `poll_recv` drains its queue, `poll_send` writes through @@ -38,16 +39,19 @@ one is a public query and goes to the responder. Public STUN clients never send USERNAME and ICE agents always do. Off by default in `moq-relay`, on with `--stun`. -WebRTC: `moq_rtc::server::mux::Mux` gains `Mux::feed(src, bytes)` and a -constructor over a virtual socket, so it stops binding its own port; its -advertised candidates become the shared address. `Config.udp_bind` goes. -When ICE succeeds on a 4-tuple the mux reports it and the outer flow table -pins that tuple to WebRTC, so later RTP cannot be classified as SRT. +WebRTC: DTLS, RTP, and USERNAME-carrying STUN go to a `webrtc` virtual +socket that `moq-relay` leaves unconsumed and an embedder takes. Adapting +`moq_rtc::server::mux::Mux` to it (`Mux::feed`, a shared advertised address, +and pinning ICE 4-tuples in the flow table) is the embedder's work, not this +quest's. -Tests: a unit test per first-byte class routes to the right virtual socket; -an integration test runs a QUIC client, a STUN Binding round trip, and a WHIP -session against one bound port. `moq-relay` docs list the port once. +Decided in the 2026-09-30 audit: narrowed to QUIC plus STUN in the relay, +because `moq-relay` has no `moq-rtc` dependency and serves no WHIP or WHEP. + +Tests: a unit test per first-byte class routes to the right virtual socket, +including the WebRTC hook; an integration test runs a QUIC client and a STUN +Binding round trip against one bound port. `moq-relay` docs list the port once. ## Related -- [P2P](/quest/m1/p2p/README.md) - the client side of the STUN answer +- [P2P](/quest/m2/p2p/README.md) - the client side of the STUN answer diff --git a/quest/m1/p2p/README.md b/quest/m2/p2p/README.md similarity index 82% rename from quest/m1/p2p/README.md rename to quest/m2/p2p/README.md index b0817e23798..f6e40ddb044 100644 --- a/quest/m1/p2p/README.md +++ b/quest/m2/p2p/README.md @@ -28,13 +28,14 @@ under "One channel, qmux, ordered". ## Plan +Deferred to m2 in the 2026-09-30 audit: no named consumer. + ### The relay is the rendezvous and the fallback Every opted-in peer already holds a session to the same relay, so discovery and signaling ride that session as ordinary moq broadcasts under a reserved -prefix (`.p2p/` by default, configurable), the same shape -[carrier voice](/quest/m2/carrier-voice/README.md) uses for call setup. The -relay learns nothing new; trust is its token scope. A peer that may publish +prefix (`.p2p/` by default, configurable). The relay learns nothing new; +trust is its token scope. A peer that may publish under the prefix is as trusted as any publisher the token admits, so this line needs no E2EE. @@ -44,7 +45,7 @@ the best remaining one and the subscription moves back. That is the whole fallback story; nothing TURN-shaped is built. A relay that also answers STUN on its QUIC port -([one port](/quest/m1/one-port/README.md)) is the lowest-RTT STUN server a +([one port](/quest/m2/one-port/README.md)) is the lowest-RTT STUN server a client can name, but this line takes ICE servers from the application and works with any. @@ -77,12 +78,12 @@ negotiated `maxMessageSize` (256 KiB in Chrome). The cost is head-of-line blocking: one lost chunk stalls every stream until SCTP retransmits it. qmux frames already carry stream offsets, so the follow-up is a qmux transport parameter that permits reordering plus receiver -reassembly, which [qmux on the QUIC core](/quest/m1/quic/qmux.md) provides +reassembly, which [qmux on the QUIC core](/quest/m2/quic-qmux.md) provides for free. Both sides advertise that capability in the roster before the channel is created so it can run `ordered: false`; a loss then stalls only the stream it hit. `RTCDataChannel.ordered` cannot change after the channel exists, so the first qmux record is too late to choose. The -[harness](/quest/m1/p2p/harness.md) supplies the numbers that decide when +[harness](/quest/m2/p2p/harness.md) supplies the numbers that decide when that follow-up is worth it. Channel-per-stream is not planned. moq opens a stream per group, so it churns @@ -101,13 +102,13 @@ already declares a random hop id, so browser hops are identified; the roster id is that hop id, held once per origin rather than once per session. Watcher-to-watcher offload needs a tab to forward what it receives, which the -JS origin does not do today: [transit](/quest/m1/p2p/transit.md). +JS origin does not do today: [transit](/quest/m2/p2p/transit.md). How a P2P route outranks the relay's is deliberately open. Costs today live in one scope, a relay mesh pricing its own links; a P2P link is neither free nor the CDN's egress, and `warm` only accumulates, so a tab forwarding the relay's route ties the relay and loses on chain length. -[Cost across scopes](/quest/m1/p2p/cost-scopes.md) writes the rule before +[Cost across scopes](/quest/m2/p2p/cost-scopes.md) writes the rule before the watcher depends on it. No Rust + WASM in-tab hop: [rs2ts](/quest/m1/rs2ts/remove-wasm.md) removes the @@ -127,20 +128,17 @@ WASM build, so the browser side stays TypeScript. ## Required -- [Data channel transport](/quest/m1/p2p/transport.md) - `@moq/p2p` speaks qmux over one ordered RTCDataChannel behind the WebTransport shape `@moq/net` consumes -- [Signaling and policy](/quest/m1/p2p/signal.md) - opted-in peers find each other under the prefix, the application picks who to dial, and the roster-size gate decides whether STUN is used -- [Native data channel transport](/quest/m1/p2p/webrtc.md) - `moq-tokio` holds a moq-net session with a browser over str0m with a full ICE agent -- [moq-cli joins](/quest/m1/p2p/cli.md) - `--p2p` publishes a roster entry with its iroh endpoint, dials iroh between native peers, and serves browsers as a transit hop -- [Transit in the JS origin](/quest/m1/p2p/transit.md) - a tab forwards the routes it receives to its peers with split horizon and its hop id appended -- [Cost across scopes](/quest/m1/p2p/cost-scopes.md) - the written rule for how relay egress, mesh links, and P2P links compare, so a peer that already carries a broadcast wins -- [Watch opts in](/quest/m1/p2p/watch.md) - one attribute turns it on in the demo and the watcher migrates to the cheapest route -- [Harness](/quest/m1/p2p/harness.md) - the Playwright harness and the numbers behind every mapping decision -- [Unordered qmux](/quest/m1/p2p/unordered.md) - qmux tolerates reordering so the data channel runs unordered and a loss stalls one stream +- [Data channel transport](/quest/m2/p2p/transport.md) - `@moq/p2p` speaks qmux over one ordered RTCDataChannel behind the WebTransport shape `@moq/net` consumes +- [Signaling and policy](/quest/m2/p2p/signal.md) - opted-in peers find each other under the prefix, the application picks who to dial, and the roster-size gate decides whether STUN is used +- [Native data channel transport](/quest/m2/p2p/webrtc.md) - `moq-tokio` holds a moq-net session with a browser over str0m with a full ICE agent +- [moq-cli joins](/quest/m2/p2p/cli.md) - `--p2p` publishes a roster entry with its iroh endpoint, dials iroh between native peers, and serves browsers as a transit hop +- [Transit in the JS origin](/quest/m2/p2p/transit.md) - a tab forwards the routes it receives to its peers with split horizon and its hop id appended +- [Cost across scopes](/quest/m2/p2p/cost-scopes.md) - the written rule for how relay egress, mesh links, and P2P links compare, so a peer that already carries a broadcast wins +- [Watch opts in](/quest/m2/p2p/watch.md) - one attribute turns it on in the demo and the watcher migrates to the cheapest route +- [Harness](/quest/m2/p2p/harness.md) - the Playwright harness and the numbers behind every mapping decision +- [Unordered qmux](/quest/m2/p2p/unordered.md) - qmux tolerates reordering so the data channel runs unordered and a loss stalls one stream ## Related - [Peer grants](/quest/m1/auth/peer-grant.md) - the hop-bound credential a direct session presents; HMAC keys issue none -- [One port](/quest/m1/one-port/README.md) - the relay answers STUN on its QUIC port - [E2EE](/quest/m1/e2ee/README.md) - what a peer would need if the token scope stopped being the trust boundary -- [qmux on the QUIC core](/quest/m1/quic/qmux.md) - the stream core the unordered follow-up rides -- [Carrier voice](/quest/m2/carrier-voice/README.md) - signaling as an application protocol over moq, the pattern reused here diff --git a/quest/m1/p2p/cli.md b/quest/m2/p2p/cli.md similarity index 89% rename from quest/m1/p2p/cli.md rename to quest/m2/p2p/cli.md index f0b28f71270..a5e3b161450 100644 --- a/quest/m1/p2p/cli.md +++ b/quest/m2/p2p/cli.md @@ -16,7 +16,7 @@ than adding startup checks. `--p2p-ice-server`, `Peers` takes; `select` is the CLI's built-in default of dialing everyone. The roster entry mirrors the `info.json` schema from -[signaling](/quest/m1/p2p/signal.md): the listener's LAN addresses as +[signaling](/quest/m2/p2p/signal.md): the listener's LAN addresses as WebTransport URLs, ordered the way `mdns::Peer::urls` orders them, with the listener's certificate fingerprint; the iroh endpoint id when `--iroh` is on, which is the first place an endpoint id appears in any roster; `webrtc: true`; @@ -35,5 +35,5 @@ Docs: a "P2P" section in `doc/bin/cli.md` beside the LAN cluster one. ## Required -- [Native data channel transport](/quest/m1/p2p/webrtc.md) -- [Signaling and policy](/quest/m1/p2p/signal.md) - the roster and offer schema this mirrors +- [Native data channel transport](/quest/m2/p2p/webrtc.md) +- [Signaling and policy](/quest/m2/p2p/signal.md) - the roster and offer schema this mirrors diff --git a/quest/m1/p2p/cost-scopes.md b/quest/m2/p2p/cost-scopes.md similarity index 89% rename from quest/m1/p2p/cost-scopes.md rename to quest/m2/p2p/cost-scopes.md index 1aecaa1c194..fd0a2e5b2ce 100644 --- a/quest/m1/p2p/cost-scopes.md +++ b/quest/m2/p2p/cost-scopes.md @@ -26,7 +26,7 @@ link is neither free (peer uplink, reliability) nor the CDN's egress, and nothing flattens `warm` when an origin already carries the content, so a tab forwarding the relay's route at the relay's price plus its own ties the relay and loses on chain length. Candidate rules to weigh, with the numbers from -the [harness](/quest/m1/p2p/harness.md) where they exist: +the [harness](/quest/m2/p2p/harness.md) where they exist: - a warm discount: an origin actively receiving a broadcast re-announces it at `warm` 0 and `cold` unchanged, over every session, in both languages, @@ -43,10 +43,10 @@ holds when the first hop is a publisher tab, and whether the warm discount belongs in the mesh too. Write the rule beside route selection in `doc/concept/transport.md`, mirror it in `draft-lcurley-moq-lite.md` and `draft-lcurley-moq-cluster.md` where the wire carries it, and pass -`just drafts check`. Then update [watch](/quest/m1/p2p/watch.md) and -[transit](/quest/m1/p2p/transit.md) with the chosen rule and open the +`just drafts check`. Then update [watch](/quest/m2/p2p/watch.md) and +[transit](/quest/m2/p2p/transit.md) with the chosen rule and open the implementation quest it needs. ## Related -- [Cluster routing](/quest/m1/cluster-routing.md) - the mesh-side use of cost +- [Cluster routing](/quest/m1/cluster-routing/README.md) - the mesh-side use of cost diff --git a/quest/m1/p2p/harness.md b/quest/m2/p2p/harness.md similarity index 90% rename from quest/m1/p2p/harness.md rename to quest/m2/p2p/harness.md index 9ecd76588ae..0863d93dd2d 100644 --- a/quest/m1/p2p/harness.md +++ b/quest/m2/p2p/harness.md @@ -36,6 +36,6 @@ points. ## Required -- [moq-cli joins](/quest/m1/p2p/cli.md) -- [Signaling and policy](/quest/m1/p2p/signal.md) -- [Transit in the JS origin](/quest/m1/p2p/transit.md) - the watcher-to-watcher row +- [moq-cli joins](/quest/m2/p2p/cli.md) +- [Signaling and policy](/quest/m2/p2p/signal.md) +- [Transit in the JS origin](/quest/m2/p2p/transit.md) - the watcher-to-watcher row diff --git a/quest/m1/p2p/signal.md b/quest/m2/p2p/signal.md similarity index 91% rename from quest/m1/p2p/signal.md rename to quest/m2/p2p/signal.md index a447ebc850f..c0884266119 100644 --- a/quest/m1/p2p/signal.md +++ b/quest/m2/p2p/signal.md @@ -11,7 +11,7 @@ size above which new negotiations stop using them. No new relay behavior. ## Plan `Peers` in `@moq/p2p` takes the shared origin and the policy knobs from the -[questline README](/quest/m1/p2p/README.md): `enabled`, `prefix`, +[questline README](/quest/m2/p2p/README.md): `enabled`, `prefix`, `iceServers`, `max`, `meta`, `select`. Publishing into the origin reaches the relay and the origin's announce stream is the roster. Tests inject a peer connection factory so `bun test` covers pairing, the roster gate, and @@ -28,9 +28,9 @@ the presenter public key that [peer grants](/quest/m1/auth/peer-grant.md) bind, the application's `meta`, and for native peers an optional `webtransport: { url, fingerprint }` and `iroh` endpoint id. The schema is shared with -[moq-cli](/quest/m1/p2p/cli.md). Unordered is advertised here so the dialer +[moq-cli](/quest/m2/p2p/cli.md). Unordered is advertised here so the dialer can set `RTCDataChannel.ordered` at create time; see -[unordered qmux](/quest/m1/p2p/unordered.md). +[unordered qmux](/quest/m2/p2p/unordered.md). Pairing is sparse: broadcasts exist only for pairs some `select` chose, so the cost is the dialed pairs, not the square of the roster. Whoever selects a @@ -59,7 +59,7 @@ failure is terminal for the pair until either side re-announces; no retry loop. Each established connection goes through `connect` with the supplied transport on the dialing side and `accept` on the answering side, both with `publish: origin.consume()` and `consume: origin`, so the tab serves what it -publishes and, once [transit](/quest/m1/p2p/transit.md) lands, what it +publishes and, once [transit](/quest/m2/p2p/transit.md) lands, what it receives. Trust: publishing under the prefix proves only that the relay admitted the @@ -81,9 +81,5 @@ there is no equal-scope shortcut. ## Required -- [Data channel transport](/quest/m1/p2p/transport.md) +- [Data channel transport](/quest/m2/p2p/transport.md) - [Peer grants](/quest/m1/auth/peer-grant.md) - the hop-bound, asymmetrically signed credential a direct session presents; HS256 keys issue none - -## Related - -- [Carrier voice protocol](/quest/m2/carrier-voice/README.md) - the same signaling-as-broadcasts shape diff --git a/quest/m2/p2p/transit.md b/quest/m2/p2p/transit.md new file mode 100644 index 00000000000..cde7482763c --- /dev/null +++ b/quest/m2/p2p/transit.md @@ -0,0 +1,35 @@ +# [S] Transit in the JS origin + +## Goal + +A test proves a tab forwards the routes it receives on one session to the +sessions it serves, so a watcher can re-serve a broadcast to a peer and a room +of watchers can cost the relay one egress stream. Split horizon holds: a route +is never announced back to the session it arrived on, and every forwarded +chain carries the tab's hop id. + +## Plan + +Decided in the 2026-09-30 audit: shrink to a test. The Rust origin already +does transit (`with_publisher` and `with_subscriber` splice and share remote +routes), and [Generated lite](/quest/m1/rs2ts/lite.md) replaces the +hand-written JS origin with one generated from it, so there is no JS +forwarding step to write by hand. + +The hop id must be one per origin, not per session, so the roster id from +[signaling](/quest/m2/p2p/signal.md) and the id in forwarded chains agree. + +Tests with the mock transport pair against the generated origin: a route +received on A appears on B with the id appended and never on A; a chain +already containing the id or at `MAX_HOPS` is dropped; a retraction on A +retracts on B; two watchers of one tab share one upstream subscription. If a +case fails, the fix goes in the Rust origin. + +## Required + +- [Generated lite](/quest/m1/rs2ts/lite.md) - the JS origin generated from moq-net, which already does transit + +## Related + +- [Watch opts in](/quest/m2/p2p/watch.md) - the first topology that needs a forwarding tab +- [Cost across scopes](/quest/m2/p2p/cost-scopes.md) - adds the receiving link's cost to forwarded routes diff --git a/quest/m1/p2p/transport.md b/quest/m2/p2p/transport.md similarity index 91% rename from quest/m1/p2p/transport.md rename to quest/m2/p2p/transport.md index 93ab5ab8371..4ba0a5931ea 100644 --- a/quest/m1/p2p/transport.md +++ b/quest/m2/p2p/transport.md @@ -26,7 +26,7 @@ clamped to the negotiated `maxMessageSize`; a record that would exceed it is split at a frame boundary, never chunked mid-frame. The channel is created with `ordered: true` and no retransmit limit unless signaling already agreed unordered; `ordered` is a constructor option so -[unordered qmux](/quest/m1/p2p/unordered.md) flips it without a second +[unordered qmux](/quest/m2/p2p/unordered.md) flips it without a second transport. The flip is decided from the roster before `createDataChannel`, never from the first qmux record. @@ -41,5 +41,5 @@ the sentence declaring P2P out of scope goes. `just drafts check` passes. ## Related -- [Signaling and policy](/quest/m1/p2p/signal.md) - supplies the peer connection and the agreed ALPN -- [Native data channel transport](/quest/m1/p2p/webrtc.md) - the same binding in Rust +- [Signaling and policy](/quest/m2/p2p/signal.md) - supplies the peer connection and the agreed ALPN +- [Native data channel transport](/quest/m2/p2p/webrtc.md) - the same binding in Rust diff --git a/quest/m1/p2p/unordered.md b/quest/m2/p2p/unordered.md similarity index 87% rename from quest/m1/p2p/unordered.md rename to quest/m2/p2p/unordered.md index 3a8433010c2..a4dc1ffbf76 100644 --- a/quest/m1/p2p/unordered.md +++ b/quest/m2/p2p/unordered.md @@ -13,7 +13,7 @@ qmux frames already carry stream offsets; the draft's in-order STREAM requirement exists so a receiver can deliver without reassembly. Add a transport parameter, `unordered`, that both sides must send for the relaxed rule to apply, and receiver-side reassembly by offset for STREAM frames when -it does. Once [qmux on the QUIC core](/quest/m1/quic/qmux.md) lands, that +it does. Once [qmux on the QUIC core](/quest/m2/quic-qmux.md) lands, that reassembly is QUIC's own receive buffer and this quest is the parameter plus the binding flip; before it, do not build a second reassembly buffer. One record is one SCTP message, so the unordered writer emits frames for only @@ -42,12 +42,11 @@ Draft: `draft-lcurley-qmux.md` gains the parameter and the relaxed rule; the data channel row in `draft-lcurley-moq-lite.md` says which mode it runs. `just drafts check` passes. -Measure with the [harness](/quest/m1/p2p/harness.md) before and after: stall +Measure with the [harness](/quest/m2/p2p/harness.md) before and after: stall duration after an induced loss is the number this quest exists to move, and throughput must not regress. ## Required -- [Harness](/quest/m1/p2p/harness.md) - the loss row this quest is measured against -- [qmux on the QUIC core](/quest/m1/quic/qmux.md) - the receive buffer that makes reassembly free -- [Signaling and policy](/quest/m1/p2p/signal.md) - the roster advertisement that decides ordered before the channel exists +- [Harness](/quest/m2/p2p/harness.md) - the loss row this quest is measured against +- [Signaling and policy](/quest/m2/p2p/signal.md) - the roster advertisement that decides ordered before the channel exists diff --git a/quest/m1/p2p/watch.md b/quest/m2/p2p/watch.md similarity index 74% rename from quest/m1/p2p/watch.md rename to quest/m2/p2p/watch.md index 476879b88da..8307f6c0649 100644 --- a/quest/m1/p2p/watch.md +++ b/quest/m2/p2p/watch.md @@ -13,17 +13,17 @@ goes away, with no visible interruption. `Peers` on the shared connection's origin with the demo's ICE servers and a `max` from the page; `demo/web` exposes the toggle. The route pick is the origin's, from its cost ranking (`compareRoutes` in `js/net/src/origin.ts`) under the rule from -[cost across scopes](/quest/m1/p2p/cost-scopes.md): a peer already carrying +[cost across scopes](/quest/m2/p2p/cost-scopes.md): a peer already carrying the broadcast wins, and its retraction falls back to the relay. Three topologies and the demo shows all of them: a publishing tab serving watcher tabs directly, watcher tabs pulling from a `moq-cli --p2p` hop, and a watcher tab re-serving to another watcher through -[transit](/quest/m1/p2p/transit.md). +[transit](/quest/m2/p2p/transit.md). ## Required -- [Signaling and policy](/quest/m1/p2p/signal.md) -- [moq-cli joins](/quest/m1/p2p/cli.md) - the native hop the second topology shows -- [Transit in the JS origin](/quest/m1/p2p/transit.md) -- [Cost across scopes](/quest/m1/p2p/cost-scopes.md) +- [Signaling and policy](/quest/m2/p2p/signal.md) +- [moq-cli joins](/quest/m2/p2p/cli.md) - the native hop the second topology shows +- [Transit in the JS origin](/quest/m2/p2p/transit.md) +- [Cost across scopes](/quest/m2/p2p/cost-scopes.md) diff --git a/quest/m1/p2p/webrtc.md b/quest/m2/p2p/webrtc.md similarity index 89% rename from quest/m1/p2p/webrtc.md rename to quest/m2/p2p/webrtc.md index 3b6ee88cb50..6dfe54fc1f4 100644 --- a/quest/m1/p2p/webrtc.md +++ b/quest/m2/p2p/webrtc.md @@ -32,7 +32,7 @@ reliable ordered str0m channel, the way `ws::Upgraded` does, and feed `qmux::Session` through `transport::Session` like `websocket.rs`. One record per message, `max_record_size` 16 KiB by default, clamped to the negotiated message size. `ordered` is a config knob for -[unordered qmux](/quest/m1/p2p/unordered.md), set from the roster before +[unordered qmux](/quest/m2/p2p/unordered.md), set from the roster before the channel is created, never from the first qmux record. Tests: an in-process str0m pair over loopback runs moq-net's session tests; @@ -41,6 +41,6 @@ candidate is offered and selected. Browser interop is the harness's job. ## Related -- [Data channel transport](/quest/m1/p2p/transport.md) - the browser side of the same binding -- [moq-cli joins](/quest/m1/p2p/cli.md) - the first consumer -- [One port](/quest/m1/one-port/README.md) - the relay-side STUN answer this client can be pointed at +- [Data channel transport](/quest/m2/p2p/transport.md) - the browser side of the same binding +- [moq-cli joins](/quest/m2/p2p/cli.md) - the first consumer +- [One port](/quest/m2/one-port/README.md) - the relay-side STUN answer this client can be pointed at diff --git a/quest/m2/pipewire-camera-planes.md b/quest/m2/pipewire-camera-planes.md index 5cc58a94f85..c8cda797532 100644 --- a/quest/m2/pipewire-camera-planes.md +++ b/quest/m2/pipewire-camera-planes.md @@ -12,5 +12,4 @@ Unit-test the offer, a multi-block NV12 buffer, and a multi-block I420 buffer, w ## Related -- [Validate PipeWire cameras on a portal and a Pi](/quest/m3/pipewire-camera-hardware.md) - the pass that shows whether a real Pi or portal camera delivers separate planes - [PipeWire DMA-BUFs into Vulkan](/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md) - the hardware validation of the DMA-BUF path diff --git a/quest/m1/processor/README.md b/quest/m2/processor/README.md similarity index 80% rename from quest/m1/processor/README.md rename to quest/m2/processor/README.md index 2adda569162..401ddba58f4 100644 --- a/quest/m1/processor/README.md +++ b/quest/m2/processor/README.md @@ -24,24 +24,24 @@ service-prefix layout, not `/.pro`. Suffix routing is dropped everywhere, and a prefix claim needs the variable part of the path trailing, so the processor claims its prefix and mirrors the source path beneath it. The source's catalog reaches the output through a -cross-broadcast reference ([media contract](/quest/m1/processor/media-contract.md)). +cross-broadcast reference ([media contract](/quest/m2/processor/media-contract.md)). + +Deferred to m2 in the 2026-09-30 audit: no processor customer is committed, +and its end-to-end proof (processor-vision) was deleted. ## Required -- [Processor media contract](/quest/m1/processor/media-contract.md) - define +- [Processor media contract](/quest/m2/processor/media-contract.md) - define contribution references, source relations, and correlation in the Hang catalog -- [Advertise-only authorization](/quest/m1/processor/advertise-auth.md) - a +- [Advertise-only authorization](/quest/m2/processor/advertise-auth.md) - a worker may advertise its service prefix without receiving permission to publish arbitrary paths under it -- [Expiring media grants](/quest/m1/processor/grant-lease.md) - enforce +- [Expiring media grants](/quest/m2/processor/grant-lease.md) - enforce short-lived exact grants on already-open consumer and producer handles ## Related -- [Reference vision worker](/quest/m3/processor-vision.md) - a runnable worker - publishes frame-correlated detections and proves demand, reconnect, - failover, and teardown end to end - [Wildcard advertisements](/quest/m0/wildcard/README.md) - lets a dormant processor advertise what it could serve without enumerating live sources, and sets the service-prefix layout diff --git a/quest/m1/processor/advertise-auth.md b/quest/m2/processor/advertise-auth.md similarity index 98% rename from quest/m1/processor/advertise-auth.md rename to quest/m2/processor/advertise-auth.md index 08e2985071c..3b9d5198700 100644 --- a/quest/m1/processor/advertise-auth.md +++ b/quest/m2/processor/advertise-auth.md @@ -17,7 +17,7 @@ announcement or publish request still requires publish permission, so an advertise-only worker cannot bypass the demand exchange. Decided: the advertise scope is prefix-only. Advertising is prefix-only on -every wire (Wildcard's decision) until [announcement shapes](/quest/m3/announce-shapes.md) +every wire (Wildcard's decision) until [announcement shapes](/quest/m2/announce-shapes.md) adds exact and suffix shapes to moq-lite, so leading-star and suffix advertise patterns have nothing to authorize yet; that quest extends this scope. Token claim patterns keep their suffix support for publish and subscribe. diff --git a/quest/m1/processor/grant-lease.md b/quest/m2/processor/grant-lease.md similarity index 92% rename from quest/m1/processor/grant-lease.md rename to quest/m2/processor/grant-lease.md index 66ee0bf16ac..b28462b6c43 100644 --- a/quest/m1/processor/grant-lease.md +++ b/quest/m2/processor/grant-lease.md @@ -22,8 +22,8 @@ cooperative worker timer. Build on what exists: `Grant::deadline` (`rs/moq-auth/src/grant.rs`, #4237) already pins an accepted grant to a fixed deadline, and dev's `moq_auth::lease` (#3943) re-checks a session on cadence and reports why it ended. Extend those to the handles a grant opened rather -than adding a second timer. No clock-skew grace: open #4368 makes expiry -exact and drops `CLOCK_SKEW`, so a deadline in the past is expired. +than adding a second timer. No clock-skew grace: #4368 (merged) made expiry +exact and dropped `CLOCK_SKEW`, so a deadline in the past is expired. Cover an idle open handle, active source reads, active publication, refresh before expiry, refresh after demand ends, disconnect races, HTTP and HLS rejection of diff --git a/quest/m1/processor/media-contract.md b/quest/m2/processor/media-contract.md similarity index 89% rename from quest/m1/processor/media-contract.md rename to quest/m2/processor/media-contract.md index 1bcf95eb5f7..27c4f3d8cd8 100644 --- a/quest/m1/processor/media-contract.md +++ b/quest/m2/processor/media-contract.md @@ -31,3 +31,7 @@ Land Rust and JavaScript catalog bindings, resolver behavior, and fixtures for video, audio, text, missing output, malformed relations, lazy resolution, and relative-path escape. The release and the moq.pro (downstream) pin rollout stay out of this quest. + +## Required + +- [Catalog track alias](/quest/m1/catalog-track-alias.md) - renditions from a source and an output broadcast that share a track name would otherwise collide in one catalog diff --git a/quest/m1/quic/ack-hook.md b/quest/m2/quic-ack-hook.md similarity index 62% rename from quest/m1/quic/ack-hook.md rename to quest/m2/quic-ack-hook.md index 9939c630cc3..2879ba8da37 100644 --- a/quest/m1/quic/ack-hook.md +++ b/quest/m2/quic-ack-hook.md @@ -9,10 +9,13 @@ guess. ## Plan -The work lives in `moq-dev/web-transport`. This quest exists so the release -it produces is one condition dependents wait on; it supersedes the design in -moq-dev/web-transport#368, whose snapshot-counter shape loses the wakeups a -latency sample needs. +The trait method lives in `moq-dev/web-transport`. The `web-transport-moq` +adapter lives in the moq-dev/noq fork and is released from it +(Cargo.toml:236-237), so its implementation folds into +[ACK progress](/quest/m2/quic-ack-progress.md)'s release rather than a +separate one. This quest exists so the release it produces is one condition +dependents wait on; it supersedes the design in moq-dev/web-transport#368, +whose snapshot-counter shape loses the wakeups a latency sample needs. Add one method to `SendStream`, in the trait's poll style: @@ -30,7 +33,7 @@ use. A default body cannot construct a backend's own `Self::Error`, so unsupported has to live in the return type rather than the error, and a consumer must treat `None` as unknown, never as delivered. -Implement it in `web-transport-moq` over the fork's accessor. Leave +Implement it in `web-transport-moq`, in the fork, over the fork's accessor. Leave `web-transport-wasm` on the default; the browser's `WebTransportSendStream.getStats()` is unimplemented in shipping Chrome and its `bytesAcknowledged` is at risk in the W3C draft. qmux over a reliable transport may treat serialization as @@ -42,17 +45,21 @@ the middle of an in-flight frame, several waiters on one stream in offset order, a waiter whose offset lies beyond the final size, reset by sender, STOP_SENDING by the receiver, and session close. -Cut releases of `web-transport-trait` and `web-transport-moq`. The quest -completes when both are on crates.io. +Cut a `web-transport-trait` release, and ship the adapter in the fork +release that carries ACK progress. The quest completes when both are on +crates.io. + +Decided in the 2026-09-30 audit: moved to m2 with its only consumer, +[frame-granularity starvation](/quest/m2/starvation-frames.md). ## Required -- [Per-stream ACK progress in noq](/quest/m1/quic/ack-progress.md) - the - noq-proto accessor the adapter reads +- [Per-stream ACK progress in noq](/quest/m2/quic-ack-progress.md) - the + noq-proto accessor the adapter reads, released together ## Related -- [Starvation at frame granularity](/quest/m1/qos/starvation-frames.md) - the +- [Starvation at frame granularity](/quest/m2/starvation-frames.md) - the moq-net consumer -- [qmux on the QUIC stream state machine](/quest/m1/quic/qmux.md) - decides +- [qmux on the QUIC stream state machine](/quest/m2/quic-qmux.md) - decides what acknowledgment means over a reliable transport diff --git a/quest/m1/quic/ack-progress.md b/quest/m2/quic-ack-progress.md similarity index 84% rename from quest/m1/quic/ack-progress.md rename to quest/m2/quic-ack-progress.md index 747f63d6497..839ad1b145c 100644 --- a/quest/m1/quic/ack-progress.md +++ b/quest/m2/quic-ack-progress.md @@ -33,11 +33,16 @@ stream teardown: the accessor must not return a prefix that includes bytes the peer will never acknowledge, and a waiter for an offset beyond the final size must resolve with the reset instead of hanging. -Land it in the fork and offer it upstream once it is stable. The quest +Land it in the fork and offer it upstream once it is stable. The +`web-transport-moq` half of [the ACK hook](/quest/m2/quic-ack-hook.md) lives +in the same fork repository and ships in the same release. The quest completes when a `moq-noq-proto` release carries the accessor and `Cargo.lock` here can name it. +Decided in the 2026-09-30 audit: moved to m2 with its consumers, the ACK +hook and [frame-granularity starvation](/quest/m2/starvation-frames.md). + ## Related -- [poll_acked in web-transport](/quest/m1/quic/ack-hook.md) - the first +- [poll_acked in web-transport](/quest/m2/quic-ack-hook.md) - the first consumer of the accessor diff --git a/quest/m2/quic-bbr-google.md b/quest/m2/quic-bbr-google.md deleted file mode 100644 index 63c90992fe8..00000000000 --- a/quest/m2/quic-bbr-google.md +++ /dev/null @@ -1,40 +0,0 @@ -# [M] Measure the remaining Google BBR differences - -## Goal - -A measured decision on two remaining differences from Google's public BBR: -recognizing bandwidth growth within a round and precautionary bandwidth -probing. Each gets an adopt, retain, or investigate-further verdict; Google -parity is not assumed to be an improvement and does not gate correctness fixes. - -## Plan - -Use the corrected fork as the baseline. The 2026-09-21 audit compared -noq-proto 1.3.0 / upstream `1a26a8b` with Google Linux BBRv3 `90210de4` -and Google QUICHE `535a2730`. Recheck current upstream sources before testing. -Use QUICHE's actual `bbr3_sender.cc` with its shared `bbr2_*` model; -the older BBR2 sender is not a substitute for its BBR3 state machine. - -- [Google Linux](https://github.com/google/bbr/blob/90210de4b779d40496dee0b89081780eeddf2a60/net/ipv4/tcp_bbr.c#L1924) recognizes growth on any ACK and increments - the plateau counter only at a round boundary. Noq follows - [draft-06](https://www.ietf.org/archive/id/draft-ietf-ccwg-bbr-06.html#section-5.3.1.2)'s earlier round-start gate. QUICHE - instead checks its bandwidth maximum at round boundaries. Test bursty and - aggregated ACKs and changing bottleneck capacity for premature plateau exits. -- [Google Linux](https://github.com/google/bbr/blob/90210de4b779d40496dee0b89081780eeddf2a60/net/ipv4/tcp_bbr.c#L1803) and - [Google QUICHE](https://github.com/google/quiche/blob/535a2730e77d47e0dc03746555cc9c34b17bc9e9/quiche/quic/core/congestion_control/bbr3_sender.cc#L1079) stop precautionarily when - probing reaches a previously lossy inflight bound, then accelerate a later - probe if feedback is clean. Noq lacks this state and transition. Compare - shallow queues, capacity increases, random loss, and competing flows. - -Report throughput, queue delay, loss, convergence time, and fairness with -pinned code and configurations. Keep transport differences and QUICHE flags -explicit; compare each algorithm change separately. A simulation result is -not an end-to-end network measurement. Persist a reproducible harness in CI -(at least nightly) and the verdict with the quest's completion. Create a -separate implementation quest for any adopted change rather than silently -expanding this study into a controller rewrite. - -## Related - -- [Natural media drains](/quest/m2/quic-bbr-natural-drain.md) - reuse media profiles and measurements -- [Upstream the fork](/quest/m1/quic/upstream.md) - share useful findings with upstream diff --git a/quest/m1/quic/bbr-loss-parity.md b/quest/m2/quic-bbr-loss-parity.md similarity index 91% rename from quest/m1/quic/bbr-loss-parity.md rename to quest/m2/quic-bbr-loss-parity.md index 7b36bf4f537..5a2cb439a6c 100644 --- a/quest/m1/quic/bbr-loss-parity.md +++ b/quest/m2/quic-bbr-loss-parity.md @@ -31,6 +31,10 @@ first ACK sample, and a loss between ACKs that must not alter the next ACK's sample. Retain the spurious-loss undo coverage through Refill. Internal only; no `Controller` or wire change. +Decided in the 2026-09-30 audit: moved to m2. The seven correctness fixes +already shipped, and this remaining gap has no observed impact on MoQ +traffic yet. + ## Related - [Upstream the fork](/quest/m1/quic/upstream.md) - offers this fix alongside the seven diff --git a/quest/m2/quic-bbr-natural-drain.md b/quest/m2/quic-bbr-natural-drain.md index 561b4bea8bf..5ca6de5d3b3 100644 --- a/quest/m2/quic-bbr-natural-drain.md +++ b/quest/m2/quic-bbr-natural-drain.md @@ -1,14 +1,22 @@ -# [M] Measure natural draining before BBR ProbeRTT +# [L] BBR media study ## Goal -A measured adopt-or-retain decision on allowing natural media drains to -satisfy ProbeRTT. Reduce demonstrated frame deadline interference without +Measured adopt, retain, or investigate-further decisions on three BBR +behaviors under media traffic: allowing natural media drains to satisfy +ProbeRTT, recognizing bandwidth growth within a round, and precautionary +bandwidth probing. Reduce demonstrated frame deadline interference without stale minimum RTT, persistent queues, or unfairness. Application limitation -alone is not evidence that the path drained. +alone is not evidence that the path drained, and Google parity is not +assumed to be an improvement. ## Plan +Decided in the 2026-09-30 audit: the Google BBR comparison merged here as +one study, since both reuse the same media profiles, harness, and baseline. + +### Natural drains + Use the corrected released fork as baseline. ProbeRTT targets half the estimated BDP, floored at the minimum pipe window; entering the mode need not withhold useful bytes. First locate actual cwnd stalls and deadline @@ -40,7 +48,34 @@ harness in CI, with broader network cases at least nightly, and a verdict with pinned sources/configurations. Any adopted production policy gets a separate implementation quest; this study does not silently change defaults. +### Google differences + +The 2026-09-21 audit compared noq-proto 1.3.0 / upstream `1a26a8b` with +Google Linux BBRv3 `90210de4` and Google QUICHE `535a2730`. Recheck current +upstream sources before testing. Use QUICHE's actual `bbr3_sender.cc` with +its shared `bbr2_*` model; the older BBR2 sender is not a substitute for its +BBR3 state machine. + +- [Google Linux](https://github.com/google/bbr/blob/90210de4b779d40496dee0b89081780eeddf2a60/net/ipv4/tcp_bbr.c#L1924) + recognizes growth on any ACK and increments the plateau counter only at a + round boundary. Noq follows + [draft-06](https://www.ietf.org/archive/id/draft-ietf-ccwg-bbr-06.html#section-5.3.1.2)'s + earlier round-start gate. QUICHE instead checks its bandwidth maximum at + round boundaries. Test bursty and aggregated ACKs and changing bottleneck + capacity for premature plateau exits. +- [Google Linux](https://github.com/google/bbr/blob/90210de4b779d40496dee0b89081780eeddf2a60/net/ipv4/tcp_bbr.c#L1803) + and [Google QUICHE](https://github.com/google/quiche/blob/535a2730e77d47e0dc03746555cc9c34b17bc9e9/quiche/quic/core/congestion_control/bbr3_sender.cc#L1079) + stop precautionarily when probing reaches a previously lossy inflight + bound, then accelerate a later probe if feedback is clean. Noq lacks this + state and transition. Compare shallow queues, capacity increases, random + loss, and competing flows. + +Report throughput, queue delay, loss, convergence time, and fairness with +pinned code and configurations. Keep transport differences and QUICHE flags +explicit and compare each algorithm change separately. A simulation result +is not an end-to-end network measurement. + ## Related +- [Upstream the fork](/quest/m1/quic/upstream.md) - share useful findings with upstream - [Discover media headroom](/quest/m2/quic-probe.md) - preserving an estimate and discovering spare capacity are separate problems -- [Google BBR comparison](/quest/m2/quic-bbr-google.md) - separate growth and precautionary-probing decisions diff --git a/quest/m2/quic-buffer-pool.md b/quest/m2/quic-buffer-pool.md deleted file mode 100644 index b5e34f03ef7..00000000000 --- a/quest/m2/quic-buffer-pool.md +++ /dev/null @@ -1,27 +0,0 @@ -# [S] Send buffer pools - -## Goal - -A measured verdict on pooled send buffers versus `Bytes` in the stream send -path. noq's `SendBuffer` keeps a write above 1452 bytes as the caller's -`Bytes` without copying and coalesces smaller writes into a `BytesMut`; -moq-net hands it frames as `Bytes` from its own allocation. Either a pool of -fixed-size buffers recycled after acknowledgment measurably cuts allocation -and cache misses on the relay's egress, or `Bytes` is shown to be within -noise and the idea is closed. - -## Plan - -- Count allocations and bytes copied per frame on the fanout and video - shapes with the existing profiling captures, split by frame size, so the - share of sub-threshold copies is known before anything is built. -- Prototype in the fork: a `BufFactory`-style seam on `SendBuffer` that takes - buffers from a pool and returns them on ACK, with the pool sized per - connection from the send window. -- `just bench BASE` on Linux: CPU per Gbps, RSS, and p99 latency. Ship only a - measured win. - -## Related - -- [#3204](/quest/m1/perf/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md) - - the UDP-side pool the same buffers could feed diff --git a/quest/m1/quic/deadline.md b/quest/m2/quic-deadline.md similarity index 89% rename from quest/m1/quic/deadline.md rename to quest/m2/quic-deadline.md index 8450cadfa4c..008fcbf9c20 100644 --- a/quest/m1/quic/deadline.md +++ b/quest/m2/quic-deadline.md @@ -21,7 +21,7 @@ Implement in the fork. - On loss detection, before queueing a retransmission for a stream with a deadline, estimate the arrival instant as now plus the forward one-way delay. Start with `min_rtt / 2`, corrected by the peer's reported ACK delay; - the [receive-timestamps spike](/quest/m2/quic-receive-ts.md) replaces that + the [receive-timestamps spike](/quest/m3/quic-receive-ts.md) replaces that guess with a measured forward delay. If the estimate is past the deadline, reset the stream with a dedicated error code and drop its retransmit ranges, including bytes already lost, so flow control is returned in one step. @@ -42,6 +42,10 @@ retransmitted past their deadline (must be zero), spurious resets under reordering, and probe overhead versus the default PTO. A proactive probe that raises loss or latency under any profile stays off by default. +Decided in the 2026-09-30 audit: moved to m2. No m1 quest consumes it, and +[Upstream the fork](/quest/m1/quic/upstream.md) offers it when it lands +rather than waiting on it. + ## Required - [Hierarchical stream scheduling](/quest/m1/quic/scheduler.md) - the @@ -49,7 +53,7 @@ raises loss or latency under any profile stays off by default. ## Related -- [Receive timestamps](/quest/m2/quic-receive-ts.md) - a measured forward +- [Receive timestamps](/quest/m3/quic-receive-ts.md) - a measured forward delay replaces the half-RTT estimate - [Discover media headroom](/quest/m2/quic-probe.md) - can reuse retransmission machinery if redundant capacity probes prove worthwhile diff --git a/quest/m1/quic/ecn-measure.md b/quest/m2/quic-ecn-measure.md similarity index 94% rename from quest/m1/quic/ecn-measure.md rename to quest/m2/quic-ecn-measure.md index 2745829780d..b04caf44818 100644 --- a/quest/m1/quic/ecn-measure.md +++ b/quest/m2/quic-ecn-measure.md @@ -36,3 +36,6 @@ from 1.3.1 is a defective baseline, not evidence that classic ECN cannot help. and the tcpdump summaries beside the numbers in the L4S quest's Plan. If neither provider preserves the marks, say so there: L4S stays off and the marking response is only a lab result. + +Decided in the 2026-09-30 audit: moved to m2 with its only consumer, +[L4S on the backbone](/quest/m2/quic-ecn.md). diff --git a/quest/m2/quic-ecn.md b/quest/m2/quic-ecn.md index 3d8e415b83d..a2779e7c031 100644 --- a/quest/m2/quic-ecn.md +++ b/quest/m2/quic-ecn.md @@ -24,7 +24,7 @@ need the fork. default (today's behavior on tokio), and `doc/bin/relay/config.md` documents it in the same PR. - Measure on the netem bottleneck from the - [ECN study](/quest/m1/quic/ecn-measure.md) with `dualpi2` marking against + [ECN study](/quest/m2/quic-ecn-measure.md) with `dualpi2` marking against the same bottleneck dropping: queueing delay, goodput, loss. The study's provider verdict decides whether the result matters outside the lab; if neither Linode nor OVH preserves the marks, L4S stays off and the @@ -35,5 +35,5 @@ need the fork. ## Required -- [Measure ECN on the backbone](/quest/m1/quic/ecn-measure.md) - the +- [Measure ECN on the backbone](/quest/m2/quic-ecn-measure.md) - the provider verdict this quest acts on diff --git a/quest/m2/quic-egress-profile.md b/quest/m2/quic-egress-profile.md new file mode 100644 index 00000000000..6a30e7127f7 --- /dev/null +++ b/quest/m2/quic-egress-profile.md @@ -0,0 +1,56 @@ +# [M] Relay egress syscall and allocation profile + +## Goal + +A measured verdict on the relay's egress costs below moq-net: syscalls per +train, allocations and copies per frame, and whether a released GSO train +bursts at the bottleneck. Each lever below is built only if the profile +shows its cost; a lever measured within noise is recorded and closed. + +## Plan + +Decided in the 2026-09-30 audit: send batching, kernel pacing, and send +buffer pools merged into this one measure-first quest, since all three are +questions about the same egress path and share one profile. + +Measure first, on the chat and fanout shapes with many connections, tokio +workers versus io_uring workers, with the existing profiling captures: + +- Syscalls: the tokio path sends one `sendmsg` per GSO train per connection; + the io_uring path queues one SQE per train and submits them together. Count + syscalls per second and CPU per Gbps, and confirm from the io_uring + worker's `enters` counter that the ring already amortizes. +- Allocations: noq's `SendBuffer` keeps a write above 1452 bytes as the + caller's `Bytes` and coalesces smaller writes into a `BytesMut`. Count + allocations and bytes copied per frame, split by frame size, so the share + of sub-threshold copies is known. +- Bursts: noq paces inside `poll_transmit` on both runtimes (#4400, + rs/moq-uring/src/quic/noq/connection.rs:814-817), so the only open question + is whether a released GSO train leaves the NIC as a burst the bottleneck + cannot absorb. On a netem bottleneck, compare inter-packet gaps and queue + occupancy for a 64-segment train against the same bytes paced at the + controller's rate. + +Then, only where the profile shows a cost: + +- `sendmmsg` in `moq-noq-udp` behind the existing GSO path, submitting every + train ready across connections in one call, falling back to per-train + `sendmsg` on partial failure the way the GSO fallback does. +- A `BufFactory`-style seam on `SendBuffer` in the fork that takes buffers + from a pool sized from the send window and returns them on ACK. +- `SCM_TXTIME` stamps, one per train, at the time noq's pacer would have + released it, tested under both `etf` and `fq`. The socket is shared across + connections per worker, so `SO_MAX_PACING_RATE` cannot express + per-connection pacing. Measure on a real NIC as well as loopback, since + `etf` needs hardware offload to be exact. + +Report CPU per Gbps, RSS, loss, and p99 latency via `just bench BASE` on +Linux. The verdict names which levers ship and which qdisc, if any, relay +hosts need. + +## Related + +- [#3201](/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md) - + zero-copy on the same trains +- [#3204](/quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md) - + the UDP-side pool the same buffers could feed diff --git a/quest/m2/quic-fec.md b/quest/m2/quic-fec.md deleted file mode 100644 index 5b2f32f0983..00000000000 --- a/quest/m2/quic-fec.md +++ /dev/null @@ -1,30 +0,0 @@ -# [L] QUIC FEC experiment - -## Goal - -Record a measured verdict on transport-level forward error correction: whether -spending redundancy before loss beats retransmission on delivery latency, and -at what loss regime it pays. Scope is fork-controlled native peers because -browsers and vanilla WebTransport peers cannot consume custom frames. Ship -nothing by default; abandonment is a valid result. - -## Plan - -Measure the production loss distribution before building. If losses are too -rare or bursty for the candidate codes to recover inside a group's lifetime, -record that result and stop. - -Try the cheapest bounded shapes first: parity across a group's tail packets, -datagram-level parity, then stream-data FEC frames. Keep all framing in the -selected QUIC fork; the MoQ wire does not change. - -Compare against [early retransmission](/quest/m2/quic-probe.md), not only plain -ARQ. Both spend the same spare-bandwidth budget on redundancy. Use the same -netem and real-NIC limits as the -[GCC experiment](/quest/m2/quic-gcc.md), and report delivery latency, goodput, -redundancy cost, and unrecovered group loss. - -## Required - -- [Probe capacity by early retransmission](/quest/m2/quic-probe.md) - supplies - the baseline this experiment must beat diff --git a/quest/m2/quic-keep-alive.md b/quest/m2/quic-keep-alive.md index f4ebdf65303..7c7fc08512d 100644 --- a/quest/m2/quic-keep-alive.md +++ b/quest/m2/quic-keep-alive.md @@ -5,7 +5,9 @@ A connection sends a PING only when its idle deadline is near, never on a fixed clock. An idle connection with a 30 s idle timeout costs one packet per roughly 30 s minus a few PTOs; a busy connection costs none. The -`keep_alive` interval knob on `quic::Client` and `quic::Server` goes away. +`keep_alive` setting on `quic::Client` and `quic::Server` becomes an optional +maximum, default none. Redefining it is a config and CLI break, so this +targets `dev`. ## Plan @@ -24,9 +26,9 @@ timeout by hand. Replace it in the fork: shorter life than the idle timeout. That is the only knob. - The multipath per-path keep-alive follows the same rule per path. -moq-tokio drops `keep_alive` from the `[quic]` sections, CLI flags, and env -vars; NAT-sensitive deployments keep it as the new maximum, documented in -`doc/bin/relay/config.md`. The qmux WebSocket keep-alive (`qmux::ws::KeepAlive`, +moq-tokio's `quic.keep_alive` (`rs/moq-tokio/src/quic.rs`) in the `[quic]` +sections, CLI flags, and env vars becomes that optional maximum, default none, +documented in `doc/bin/relay/config.md` for NAT-sensitive deployments. The qmux WebSocket keep-alive (`qmux::ws::KeepAlive`, 5 s ping and 30 s deadline) already has this shape; make its wording match. Tests: an idle connection survives an idle timeout with exactly one PING per diff --git a/quest/m2/quic-kernel-pacing.md b/quest/m2/quic-kernel-pacing.md deleted file mode 100644 index f8d3b329153..00000000000 --- a/quest/m2/quic-kernel-pacing.md +++ /dev/null @@ -1,40 +0,0 @@ -# [M] Kernel pacing - -## Goal - -A measured verdict on handing packet pacing to the kernel. Today noq's pacer -is a userspace token bucket on both runtimes: `poll_transmit` holds a train -until the pacing timer fires, which the io_uring driver arms through -`poll_timeout` like the tokio driver does, but a released GSO train still -leaves the NIC as one burst. The `flush_one` comment in -`rs/moq-uring/src/quic/noq/connection.rs` saying the driver ignores the hint -is stale from quiche. Either the kernel paces each train (`SO_TXTIME` with the `etf` or -`fq` qdisc, per-packet transmit times in the cmsg the driver already builds) -and burstiness at the bottleneck drops without costing CPU, or the burst is -shown not to matter on the fleet's paths. - -## Plan - -- Measure first: on a netem bottleneck, compare inter-packet gaps and queue - occupancy for a 64-segment GSO train against the same bytes paced at the - controller's rate. If the bottleneck absorbs the burst without loss or - delay at the fleet's typical rates, record it and stop. -- Then the io_uring path: stamp each GSO train with `SCM_TXTIME` at the time - noq's pacer would have released it, one timestamp per train (the kernel - spreads segments only with `fq`'s pacing, so test both qdiscs). The socket - is shared across connections per worker, so per-socket rate limits - (`SO_MAX_PACING_RATE`) cannot express per-connection pacing; only - per-packet times can. -- Report CPU per Gbps, loss, and p99 latency against the userspace pacer on - the tokio path and the unpaced io_uring path, on a real NIC as well as - loopback, since `etf` needs hardware offload to be exact. - -The verdict names which qdisc the relay hosts need, or that none is worth -configuring. - -## Related - -- [Send batching](/quest/m2/quic-send-batching.md) - the other syscall-side - lever on the same path -- [#3201](/quest/m1/perf/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md) - - zero-copy on the same trains diff --git a/quest/m2/quic-probe.md b/quest/m2/quic-probe.md index f1e8ef3e065..9f9f4827d13 100644 --- a/quest/m2/quic-probe.md +++ b/quest/m2/quic-probe.md @@ -47,5 +47,4 @@ retain the baseline and record why before exposing an ineffective option. ## Related - [Natural media drains](/quest/m2/quic-bbr-natural-drain.md) - separate ProbeRTT policy experiment -- [FEC experiment](/quest/m2/quic-fec.md) - repetition competes for the redundancy budget -- [GCC egress experiment](/quest/m2/quic-gcc.md) - delay control changes what headroom means +- [GCC egress experiment](/quest/m3/quic-gcc.md) - delay control changes what headroom means diff --git a/quest/m1/quic/qmux.md b/quest/m2/quic-qmux.md similarity index 78% rename from quest/m1/quic/qmux.md rename to quest/m2/quic-qmux.md index c67682ead82..30bde059131 100644 --- a/quest/m1/quic/qmux.md +++ b/quest/m2/quic-qmux.md @@ -38,9 +38,8 @@ Add the missing wire evidence before release: golden draft-02 vectors, bidirectional interoperability against the published `qmux` 0.5.x crate, and the TypeScript qmux/WebSocket peer used by `js/net`. Preserve rejection of prohibited QUIC frames, params-first setup, record-size validation, close and -reset semantics (the first recorded close wins, per -[close codes](/quest/m1/close-codes.md)), keep-alive behavior, and bounded -flow-control tests. +reset semantics (the first recorded close wins, as close codes #4262 +settled on dev), keep-alive behavior, and bounded flow-control tests. The crate lives in the fork's workspace as `moq-noq-qmux`, so the stream state machine internals it drives stay crate-private there; `moq-dev/web-transport`'s @@ -48,6 +47,16 @@ state machine internals it drives stay crate-private there; `moq-dev/web-transpo state machine in the dependency graph, and the accessors qmux needs are `pub(crate)` to that workspace, never part of `moq-noq-proto`'s public API. +Release it from the fork like the other fork crates: tag `moq-noq-qmux` with +the parent noq commit and the carried patches (each with its upstream PR or +the reason there is none), pin the crates.io version in this workspace, and +verify minimal, default, and all-feature builds so enabling iroh, qmux, or +the uring runtime never unifies two copies of the stream state. The quest +completes when that release is on crates.io and `Cargo.lock` names it. + +Decided in the 2026-09-30 audit: moved to m2, since no m1 quest consumes it. +The separate QUIC release quest was deleted and its qmux step folded here. + ## Required - [Reliable stream reset](/quest/m1/quic/reliable-reset.md) - qmux reuses the diff --git a/quest/m2/quic-send-batching.md b/quest/m2/quic-send-batching.md deleted file mode 100644 index e33dea0d726..00000000000 --- a/quest/m2/quic-send-batching.md +++ /dev/null @@ -1,28 +0,0 @@ -# [S] Send batching across connections - -## Goal - -A measured verdict on batching sends across connections. The tokio path sends -one `sendmsg` per GSO train per connection; a worker flushing many small -connections pays a syscall each. `sendmmsg` submits every ready train in one -call. The io_uring path already queues one SQE per train and submits them -together, so the question there is whether it already gets the benefit. - -## Plan - -- Add `sendmmsg` to `moq-noq-udp` behind the existing GSO path: the runtime - collects the trains ready across connections in one poll and submits them - together, falling back to per-train `sendmsg` on partial failure the way - the GSO fallback does. -- Measure syscalls per second and CPU per Gbps on the chat and fanout shapes - with many connections, tokio workers versus io_uring workers, before and - after. Confirm from the io_uring worker's `enters` counter that the ring - already amortizes the same way. - -A measured no-win abandons the tokio change; the io_uring result is recorded -either way. - -## Related - -- [Kernel pacing](/quest/m2/quic-kernel-pacing.md) - pacing per train - changes what a batch can contain diff --git a/quest/m2/redundant-ingest.md b/quest/m2/redundant-ingest.md deleted file mode 100644 index 241fe5bb33b..00000000000 --- a/quest/m2/redundant-ingest.md +++ /dev/null @@ -1,30 +0,0 @@ -# [M] Redundant ingest under one epoch - -## Goal - -Decide whether and how two live publishers of identical content share one -broadcast, so viewers survive losing one faster than the QUIC keep-alive. -The study may end in a no-go. - -## Plan - -Start from what is documented today (`doc/bin/cli.md` "Redundant -publishers"): two encoders sharing a Hop ID (`--hop 42`) are one first hop, -so relays hold both routes and fail over at a group boundary under the #3312 -same-first-hop rule, provided the tracks are identical with aligned groups. - -Open questions: how that maps onto epochs (the pair claiming one -`@`), what enforces the alignment the docs only ask for (group -sequences, a matching catalog), and who declares the incumbent dead early: a -failover service that retracts it, or active-active delivery to the relay. -[Cluster routing](/quest/m1/cluster-routing.md) drops hop lists inside a -cluster and must decide what replaces this failover; follow its answer. -Weigh them against the moq-transport rule that multiple publishers of a -namespace must each be asked (#3697) and the cluster draft. Output: a -decision, with a quest for the chosen mechanism. - -## Related - -- [Same-hop importers](/quest/m1/hop-aligned-import.md) - identical tracks from one encoded stream under one first hop, the case this generalizes -- [Cluster routing](/quest/m1/cluster-routing.md) - decides what replaces first-hop failover inside a cluster -- [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - explicit epochs are what a redundant pair would share diff --git a/quest/m2/relay-io-uring-package.md b/quest/m2/relay-io-uring-package.md index 23dc0e46d91..7e82c06e82a 100644 --- a/quest/m2/relay-io-uring-package.md +++ b/quest/m2/relay-io-uring-package.md @@ -38,4 +38,6 @@ Public API: none. Wire: none. - [Flow-control windows](/quest/m1/uring-flow-control-windows.md) - the `[quic]` section must not be refused at startup on the ring - [Close before teardown](/quest/m1/quic/uring-close.md) - sessions on the - ring must end with their application close + ring must end with their application close; probably fixed by + [#4431](https://github.com/moq-dev/moq/pull/4431), so re-run its repro + before starting and drop this blocker if it passes diff --git a/quest/m1/rs2ts/ietf.md b/quest/m2/rs2ts-ietf.md similarity index 71% rename from quest/m1/rs2ts/ietf.md rename to quest/m2/rs2ts-ietf.md index b72b735753e..75390d156e1 100644 --- a/quest/m1/rs2ts/ietf.md +++ b/quest/m2/rs2ts-ietf.md @@ -14,7 +14,10 @@ they stay exact as `U64` and only fail where code converts them to Public API: breaks `@moq/net`; retargets to `dev`. Wire: none. +Decided in the 2026-09-30 audit: deferred to m2 until generated lite passes +its no-downgrade go/no-go in the [rs2ts line](/quest/m1/rs2ts/README.md). + ## Required - [Generated lite](/quest/m1/rs2ts/lite.md) - the pipeline this reuses -- [Sans-IO IETF session](/quest/m1/rs2ts/sans-io/ietf.md) - the session shape it translates +- [Sans-IO IETF session](/quest/m2/rs2ts-sans-io-ietf.md) - the session shape it translates diff --git a/quest/m1/rs2ts/sans-io/ietf.md b/quest/m2/rs2ts-sans-io-ietf.md similarity index 85% rename from quest/m1/rs2ts/sans-io/ietf.md rename to quest/m2/rs2ts-sans-io-ietf.md index 542c1965a11..a6d764f4e3d 100644 --- a/quest/m1/rs2ts/sans-io/ietf.md +++ b/quest/m2/rs2ts-sans-io-ietf.md @@ -16,6 +16,9 @@ first with the IETF session behind it, move the session out. Public API: breaks moq-net's IETF session API; retargets to `dev`. Wire: none. +Decided in the 2026-09-30 audit: deferred to m2 with generated IETF, its only +consumer, until generated lite passes its go/no-go. + ## Required - [Sans-IO lite session](/quest/m1/rs2ts/sans-io/lite.md) - sets the driver shape diff --git a/quest/m2/runtime-qa-hosts.md b/quest/m2/runtime-qa-hosts.md deleted file mode 100644 index 983c22443c1..00000000000 --- a/quest/m2/runtime-qa-hosts.md +++ /dev/null @@ -1,43 +0,0 @@ -# [L] On-demand runtime QA hosts - -## Goal - -An agent can submit an exact checkout to an available Linux or hardware test -host and retrieve results, logs, and symbols through a repeatable command. -Unsupported or inaccessible environments remain explicit verification gaps. - -## Plan - -Hosted Windows/macOS recipes compile platform code, while -`quest/m3/video-hardware.md` and `quest/m1/dart-ios.md` already own physical -validation work. This quest supplies the reusable access and execution contract, -not another list of codec or device bugs. - -- Inventory existing authorized hosts and devices first: OS/architecture, - kernel/io_uring capability, GPU/driver, media devices, display/session access, - and debugger/packet-capture permissions. Installed SSH or LLDB is not proof - that a suitable target is reachable. Do not provision paid infrastructure. -- Implement a host-side job runner plus a local submit/status/cancel/artifacts - recipe. Address an immutable source snapshot and record its digest; do not - test whichever branch the remote directory happens to contain. -- Start with one disposable Linux CPU runner for transport/runtime tests. Give - jobs isolated directories, resource limits, leases, and bounded cleanup. - Run untrusted PR code without production credentials or persistent access to - other jobs. Use existing CI or SSH access rather than adding a public service. -- Add one available device profile as proof of extensibility. Keep camera, - microphone, portal, signing, and interactive-session authorization explicit; - report unavailable devices rather than silently using a software fallback. -- Support test-owned stack capture and read-only log/metrics/artifact retrieval. - A separate debug session may retain a failed process with an expiring lease. - Document the human handoff when a permission prompt or device action is needed. - -Acceptance: submit a known SHA, recover its complete evidence, cancel a hung -job, and verify no child process or device lease remains. A mismatched source -digest or absent required backend must fail capability validation. Demonstrate -one real Linux runtime scenario and one available device scenario; if no device -is available, split that rollout into an explicit externally blocked follow-up. - -## Related - -- [Video hardware validation](/quest/m3/video-hardware.md) - owns real encoder/capture/zero-copy verdicts -- [Dart on iOS](/quest/m1/dart-ios.md) - owns simulator/device packaging validation diff --git a/quest/m2/sei.md b/quest/m2/sei.md new file mode 100644 index 00000000000..369c8d583b8 --- /dev/null +++ b/quest/m2/sei.md @@ -0,0 +1,39 @@ +# [S] Measure whether SEI separation is worthwhile + +## Goal + +Record enough evidence to decide whether a separate SEI track is worth its +framing and reassembly cost. Keep H.264 and HEVC SEI inline while this is +unresolved; a no-go verdict is a valid outcome. + +## Plan + +Decided in the 2026-09-30 audit: collapse the line into this study. The +schema, Rust, and web reinsertion quests were deleted; they only make sense +after a positive verdict, and would be re-scoped from it. + +Measure SEI payload types, bytes, and cadence on representative H.264 and HEVC +inputs. Separate small timing/display metadata, captions, encoder information, +and arbitrary vendor data. Identify a concrete metadata-only consumer if one +motivates the feature. Do not infer typical savings from a synthetic large +payload or from the codec permitting one. + +Compare current inline delivery with the bytes a video-only subscriber could +avoid, including any marker/sidecar overhead. Report total storage separately: +putting the same bytes in two tracks does not itself reduce a complete archive. + +Account for recovery points, display metadata, captions, and unknown payloads; +identify what must remain inline or be restored for each supported receiver. +A deadline bounds waiting but cannot prove absent metadata never existed. +Include loss, late arrival, and consumer compatibility in the tradeoff. + +Return a recommendation for maintainer agreement. A positive verdict scopes +which payloads move, whether extraction is opt-in, and the association and +latency contract, then files the follow-on quests. A negative verdict ends the +line without affecting captions or unrelated timed-metadata carriage. + +## Related + +- [Catalog colour model](/quest/m2/color-catalog.md) - preserves display metadata semantics +- [fMP4 emsg](/quest/m2/emsg.md) - independently settles carriage for metadata already outside video +- [CEA-608/708](/quest/m2/captions-cea.md) - can read inline caption SEI without waiting for this experiment diff --git a/quest/m2/sei/README.md b/quest/m2/sei/README.md deleted file mode 100644 index da44b7e4f84..00000000000 --- a/quest/m2/sei/README.md +++ /dev/null @@ -1,33 +0,0 @@ -# SEI separation evaluation - -## Goal - -Keep H.264 and HEVC SEI inline unless measured savings or a concrete -metadata-only consumer justify separate delivery. Evaluate that tradeoff before -committing a catalog, marker, or reassembly format. - -## Plan - -SEI separation is deferred. Existing metadata consumers may inspect the inline -bitstream; this line does not block captions or unrelated timed-metadata -carriage. The schema and implementation quests are conditional follow-ons, -not permission to strip by default. A no-go verdict abandons them. - -Preserve decoder, display, recovery-point, and caption behavior. Raw vendor -payloads may be large, but that does not establish typical bandwidth savings. -Total storage and bytes delivered to a video-only subscriber are different -measurements. Any future split must state which payloads move and how missing -metadata is handled; do not promise byte-faithful export after a deadline miss. - -## Required - -- [SEI evidence](/quest/m2/sei/evidence.md) - measure savings and identify a consumer before deciding whether to split -- [SEI section](/quest/m2/sei/sei.md) - define a format only after a positive verdict and settled association policy -- [Rust split and reinsert](/quest/m2/sei/sei-rust.md) - implement the approved split and bounded export behavior -- [Web access](/quest/m2/sei/sei-web.md) - expose approved sidecar samples independently of video - -## Related - -- [fMP4 emsg](/quest/m1/emsg.md) - independently settles carriage for metadata already outside video -- [Colour model](/quest/m1/color-model.md) - preserves display metadata semantics -- [CEA-608/708](/quest/m1/captions-cea.md) - can read inline caption SEI without waiting for this experiment diff --git a/quest/m2/sei/evidence.md b/quest/m2/sei/evidence.md deleted file mode 100644 index 259915fdac5..00000000000 --- a/quest/m2/sei/evidence.md +++ /dev/null @@ -1,32 +0,0 @@ -# [S] Measure whether SEI separation is worthwhile - -## Goal - -Record enough evidence to decide whether a separate SEI track is worth its -framing and reassembly cost. Keep SEI inline while this is unresolved; a no-go -verdict is a valid outcome. - -## Plan - -Measure SEI payload types, bytes, and cadence on representative H.264 and HEVC -inputs. Separate small timing/display metadata, captions, encoder information, -and arbitrary vendor data. Identify a concrete metadata-only consumer if one -motivates the feature. Do not infer typical savings from a synthetic large -payload or from the codec permitting one. - -Compare current inline delivery with the bytes a video-only subscriber could -avoid, including any marker/sidecar overhead. Report total storage separately: -putting the same bytes in two tracks does not itself reduce a complete archive. - -Account for recovery points, display metadata, captions, and unknown payloads; -identify what must remain inline or be restored for each supported receiver. -Compare inline markers, sidecar coverage, and bounded best-effort joining only -if the use case justifies pursuing a split. A deadline bounds waiting but -cannot prove absent metadata never existed. Include loss, late arrival, and -consumer compatibility in the tradeoff. - -Return a recommendation for maintainer agreement. A positive verdict scopes -which payloads to move, whether extraction is opt-in, and the association and -latency contract before the schema or implementation quests start. A negative -verdict abandons the remaining separation quests without affecting unrelated -timed-metadata carriage. diff --git a/quest/m2/sei/sei-rust.md b/quest/m2/sei/sei-rust.md deleted file mode 100644 index b8df34ff0e0..00000000000 --- a/quest/m2/sei/sei-rust.md +++ /dev/null @@ -1,37 +0,0 @@ -# [M] Rust SEI split and reinsert - -## Goal - -Rust importers strip H.264/H.265 SEI out of the access unit into the Hang `sei` -sidecar, and Rust exporters put it back byte-faithfully. A round trip through -any supported container reproduces the original bitstream. - -## Plan - -Implement one codec-aware split and reinsert primitive in `moq-mux` and reuse it -from every container gateway rather than creating gateway-local copies. -Apply the split policy selected by the section quest. Preserve inline -payloads that it excludes from splitting, and do not assume arbitrary SEI -can be removed without affecting receiver behavior. - -The exporter joins by group sequence and frame ordinal and restores prefix and -suffix placement and ordering. Placement is exact or it is a loss; there is no -useful approximate reinsertion. - -Export is a live consumer of two independently scheduled tracks, so state its -join budget rather than assuming the sidecar is already there. Reinsert within -the mux buffer the exporter already holds for its audio and video interleave, -and past that budget report the gap using the section's presence signal and -continue. No delivery guarantee is needed, only a stated deadline and an -honest account of what missed it: a silent drop would let export claim a -byte-faithful bitstream it did not produce. - -Round-trip exact NAL bytes through Annex B, length-prefixed samples, MPEG-TS, -and fMP4. Exercise a video-only subscription, a sidecar-only subscription, -a sidecar arriving after its video frame, reconnect at a group boundary, and -bounded cleanup of sidecar samples whose video frame never arrives. - -## Required - -- [SEI section](/quest/m2/sei/sei.md) - defines the catalog and correlation - contract diff --git a/quest/m2/sei/sei-web.md b/quest/m2/sei/sei-web.md deleted file mode 100644 index 0c21839431a..00000000000 --- a/quest/m2/sei/sei-web.md +++ /dev/null @@ -1,29 +0,0 @@ -# [S] Web SEI access - -## Goal - -The web Hang stack discovers `sei` sidecars and exposes their samples to -applications, so a browser can read timecode, ad markers, or telemetry without -subscribing to the video track at all. - -## Plan - -Add typed catalog bindings for the section and a subscriber that yields raw SEI -samples keyed by the video group sequence and frame ordinal they came from, the -exact identity the section defines, with the frame timestamp carried as data -for presentation-time sync. Keep it independent -of the decode path: this quest exposes raw sidecar samples. The section -contract must separately establish which payloads can be moved without -requiring restoration before decoding or display. - -Applications parse the NAL payloads themselves with whatever vocabulary they -need, so a new payload type requires no change here. - -Test a sidecar-only subscriber with the video track never requested, a -subscriber that takes both, late join, and reconnect. Prove that a backgrounded -tab consuming only the sidecar draws no video bandwidth. - -## Required - -- [SEI section](/quest/m2/sei/sei.md) - defines the catalog and correlation - contract diff --git a/quest/m2/sei/sei.md b/quest/m2/sei/sei.md deleted file mode 100644 index 5dd18fd98d5..00000000000 --- a/quest/m2/sei/sei.md +++ /dev/null @@ -1,54 +0,0 @@ -# [S] SEI catalog section - -## Goal - -Hang defines a top-level `sei` section that relates raw H.264 and H.265 SEI NAL -units to the video access unit they were stripped from. The contract is -sufficient for byte-faithful reinsertion on export and for an application that -subscribes to the sidecar alone. - -## Plan - -The framing below is provisional pending the split-policy and association -decision. Do not treat per-access-unit coverage as settled. - -This is a candidate codec-sidecar contract, not the prerequisite for unrelated -ID3, SCTE-35, emsg, or FLV metadata carriage: a metadata track belongs to exactly one -rendition, uses that rendition's group sequence, stamps each frame with the -wire timestamp of the media it accompanies, and carries raw bytes. A 1080p and -a 360p rendition carry different SEI, so there is one sidecar per video -rendition, and group 7 of the sidecar holds the SEI for group 7 of its video. - -Within a group the frame's wire timestamp is the key, so an application -syncing to presentation time reads it directly instead of joining against the -video track it deliberately did not subscribe to. Several access units can -share a timestamp on the raw Annex B path (`h264::Split::decode` resolves one -clock value per call and gives it to every access unit in that chunk), so the -frame's ordinal within the group disambiguates those; it is a tie-break, not -the identity. - -Preserve prefix or suffix placement, original NAL bytes, and order when -several SEI units accompany one access unit. The codec is the mapped video -rendition's, not serialized again in the sidecar. Placement has to be exact, not -approximate: `recovery_point` on the wrong access unit misdirects a receiver's -tune-in, `pic_timing` breaks field cadence and pulldown, and reordered -CEA-608/708 byte pairs garble a stateful caption decoder. - -Represent whether an access unit had SEI, so a consumer can tell "there was -none" from "lost, pruned, or not yet arrived". Missing SEI is common and valid, -but an exporter cannot claim a byte-faithful reinsertion it did not make, and -without this signal that loss is unreportable. - -Nothing in the video framing changes: the presence signal lives in the sidecar -track's own coverage, not as a flag on video frames, because no consumer blocks -on a sidecar to release a video frame. - -Version the schema so a later semantic view can be added without rewriting the -raw contract. Include fixtures for H.264 and H.265 prefix and suffix SEI, -multiple NAL units on one access unit, frames with no SEI, several access units -sharing one timestamp, and group boundaries. - -## Required - -- [SEI evidence](/quest/m2/sei/evidence.md) - positive evidence is needed before committing the format -- Maintainer approval of a positive split verdict, eligible payloads, and the association and latency policy. diff --git a/quest/m1/signed-priority.md b/quest/m2/signed-priority.md similarity index 89% rename from quest/m1/signed-priority.md rename to quest/m2/signed-priority.md index 9fcfa54d105..5f2136fb720 100644 --- a/quest/m1/signed-priority.md +++ b/quest/m2/signed-priority.md @@ -44,6 +44,10 @@ moq-archive's `Info::priority` follows. Its version-1 `.info` stores the Report the wire impact in the PR: none in format, but the default byte moves again, from 127 to 128 on moq-lite and from 128 to 127 on IETF. +Decided in the 2026-09-30 audit: moved to m2. It stays deferred unless it +ships in the same `dev` release as the moxygen default change, so the default +byte moves once instead of twice. + ## Required - [Moxygen compatibility](/quest/m1/moxygen/README.md) - ships the 127 default and the one-urgency invariant this re-maps @@ -51,3 +55,4 @@ again, from 127 to 128 on moq-lite and from 128 to 127 on IETF. ## Related - [Scope track priority](/quest/m1/track-priority-scope.md) - which streams a priority competes with, not its type +- [Hierarchical stream scheduling](/quest/m1/quic/scheduler.md) - reworks the same priority arithmetic in the transport diff --git a/quest/m2/sip-stack.md b/quest/m2/sip-stack.md deleted file mode 100644 index da2df3dabbb..00000000000 --- a/quest/m2/sip-stack.md +++ /dev/null @@ -1,34 +0,0 @@ -# [L] SIP media stack - -## Goal - -A `moq-sip` crate that terminates one inbound audio call leg: INVITE-only SIP -over UDP/TCP/TLS, SDP offer/answer for Opus and G.711 (SRTP when offered), and -a plain RTP media leg exposed to the embedder as Opus frames in and out. -Registrar, outbound, video, and DTMF are out of scope; REGISTER gets 405 and -RFC 4733 telephone-events are ignored. This quest completes when the crate is -consumable by an embedder. - -## Plan - -- Open with an evaluation, spike-backed like the - [WebRTC bridge verdict](/quest/m2/livekit-webrtc-bridge.md): drive a real - inbound call through the candidate full Rust SIP stacks (ezk-sip, rvoip, - and whatever else is current) and adopt the one that holds up. Fallback if - none do: an existing parser crate (e.g. rsip) for message/SDP syntax plus a - minimal own INVITE-only transaction and dialog engine - the surface is - small once registrar, proxy, and outbound are out. -- The media leg is plain negotiated RTP: `moq-rtc`/str0m is ICE/DTLS-first - and its reusable session internals are crate-private, so it is precedent, - not a base. Consider publicizing moq-rtc's codec bridges rather than - duplicating the RTP-to-hang mapping, and reuse `moq-audio`'s Opus codec - for the G.711<->Opus transcode, with rate conversion through - `decode::Output` and `encode::Input` since the resampler is private (mono - 8 kHz; G.711 companding is new code, nothing in the repository has it). -- RTP wall-clock normalization off RTCP sender reports, as moq-rtc does. -- The embedder decides paths and auth; the crate's API is - "answer this INVITE, give me the caller as Opus, take Opus to play" plus - call teardown. Silence generation until playback audio exists lives here, - so every embedder gets answer-with-silence for free. -- The SIP edge gateway and line provisioning that consume this crate as an - inbound-call product are moq.pro (downstream) work. diff --git a/quest/m1/qos/starvation-frames.md b/quest/m2/starvation-frames.md similarity index 92% rename from quest/m1/qos/starvation-frames.md rename to quest/m2/starvation-frames.md index 34ab0a1adf3..bb71aa27221 100644 --- a/quest/m1/qos/starvation-frames.md +++ b/quest/m2/starvation-frames.md @@ -41,6 +41,10 @@ Backends that return unsupported from `poll_acked` keep the group-granularity sampling from the parent quest, so the histogram never disappears over qmux or a browser transport; document which resolution a node offers. +Decided in the 2026-09-30 audit: moved to m2. The group-granularity sampler +from the parent quest answers the m1 question, and this waits on the m2 ACK +hook. + Tests: the frontier tracking frame ends under a peer that acknowledges in bursts, with interval samples landing one bucket lower than group-granularity tracking of the same run; a reset mid-group attributing only the @@ -52,5 +56,5 @@ unsupported. - [Starvation](/quest/m1/qos/starvation.md) - fixes the wire shape and the group-granularity fallback -- [poll_acked in web-transport](/quest/m1/quic/ack-hook.md) - the released +- [poll_acked in web-transport](/quest/m2/quic-ack-hook.md) - the released hook this samples through diff --git a/quest/m2/stats-delta.md b/quest/m2/stats-delta.md index d1243fd9746..04e757a8af7 100644 --- a/quest/m2/stats-delta.md +++ b/quest/m2/stats-delta.md @@ -106,7 +106,11 @@ maintainer's call; ask before writing one. Public API impact: additive on moq-stats unless the helpers change. Wire impact: new on-demand tracks; existing tracks unchanged. +## Required + +- [Bench coverage](/quest/m2/bench-coverage.md) - its stats producer benchmark is the moq-json snapshot encoder profile the gate needs + ## Related - [Stats format page](/doc/concept/stats.md) - where the new flavor is documented -- [Compressed tracks](/quest/m2/flate/README.md) - group-scoped DEFLATE tracks, whose group-window discipline this flavor repeats +- [Compressed tracks](/quest/m2/flate.md) - group-scoped DEFLATE tracks, whose group-window discipline this flavor repeats diff --git a/quest/m1/stats/encoder-feedback.md b/quest/m2/stats-encoder-feedback.md similarity index 76% rename from quest/m1/stats/encoder-feedback.md rename to quest/m2/stats-encoder-feedback.md index e30ad835cec..7a160a3e948 100644 --- a/quest/m1/stats/encoder-feedback.md +++ b/quest/m2/stats-encoder-feedback.md @@ -10,6 +10,9 @@ it already follows. Keyframe requests stay out. ## Plan +Deferred to m2 in the 2026-09-30 audit: no named consumer; the media stats it +reads land first in m1. + - `encode::Options` in `rs/moq-video` and `rs/moq-audio` (the producer options, beside `bandwidth`) gains `echo: Option`. - The handle is built from an `origin::Consumer` and the echo path, @@ -56,6 +59,23 @@ it already follows. Keyframe requests stay out. - Document the flag in `doc/bin/cli.md` and the loop and its config in the moq-video README. +Open, to settle before starting (moved from the +[media stats](/quest/m1/stats/README.md) line): + +- **Referenced-rendition feedback.** A derivative catalog (a `moq-transcode` + passthrough) collects feedback for a source rendition it lists, but owns + no encoder for it, and the source encoder reads only its own catalog's + prefix. Candidates: the derivative forwards those rows to the source's + echo path, or the source encoder also reads catalogs that reference it, + or referenced renditions stay report-only. +- **Shared echo prefixes.** Two catalogs can resolve their echo paths to one + prefix (`../viewers` from `room/a/live` and `room/b/live`). Then a viewer + using one name for both closes one `.echo` with the other, and each + publisher reads the other's reports under a shared alias. Candidates: + require each catalog's echo prefix to be its own, as application policy + like the token rights, or carry the catalog's broadcast in the snapshot + and ignore reports for another. + ## Required - [Schema](/quest/m1/stats/schema.md) - the `echo` section and feedback snapshot @@ -64,7 +84,7 @@ it already follows. Keyframe requests stay out. ## Related -- [Ladder](/quest/m1/ladder/README.md) - the transcode ladder that adapts to - its uplink today - [Audio follows the grant](/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md) - the audio rate follow this signal would feed +- [Ladder](/quest/m2/ladder/README.md) - the transcode ladder that adapts to + its uplink today diff --git a/quest/m2/teleop/README.md b/quest/m2/teleop/README.md index 492354d7274..c9deab559e0 100644 --- a/quest/m2/teleop/README.md +++ b/quest/m2/teleop/README.md @@ -5,12 +5,16 @@ MoQ carries a robot's video down and its control up on one session, as a library capability rather than a demo convention. -Generic in the library, integration-shaped in the proofs: Kyber is the first -transport replacement, while ArduPilot remains the first open protocol and -flight integration. The primitive is what any teleoperated machine needs. The -Kyber integration itself (replacing Kymux with moq-net and hang for Kyber's -media, input, feedback, and control) lives in Kyber's own repository, so it -has no quests here. +Generic in the library: the primitive is what any teleoperated machine needs, +and integrations are adapters on top of it. ArduPilot is the first open +protocol and flight integration, parked in m3 until a real ArduPilot user or +partner shows up. + +Decided in the 2026-09-30 audit: the ROS 2 bridge was deleted, cross-track +correlation folded into [robot](/quest/m2/teleop/robot.md), V4L2-M2M encoding +folded into [CLI packaging](/quest/m1/cli-packaging.md), and the MAVLink +bridge, SITL proof, and browser package moved to m3. Kyber is a competitor +with proprietary framing, not a transport we replace. ## Plan @@ -25,9 +29,9 @@ demo and private to it. Every integrator rebuilds the announce fan-in, the operator arbitration, and the latency instrumentation from scratch. The hang catalog is no longer a gap: it advertises data tracks in its `json` -and `binary` sections beside video and audio. What is genuinely missing is -`moq-video`'s V4L2-M2M encoder backend in a released `moq-cli`, so the boards -that fly have no native hardware-encode path anyone can install. +and `binary` sections beside video and audio. The other missing piece, +`moq-video`'s V4L2-M2M encoder in a released `moq-cli`, is tracked by +[CLI packaging](/quest/m1/cli-packaging.md). ### Two delivery classes, one session @@ -49,7 +53,7 @@ The split is a framing decision, not a subscription flag, and `moq-json` and modes. What that means for the primitive is in [robot](/quest/m2/teleop/robot.md), and what it means for a protocol multiplexing many message rates onto one link is in -[mavlink](/quest/m2/teleop/mavlink.md). +[mavlink](/quest/m3/teleop-mavlink.md). ### Who is already here @@ -86,33 +90,24 @@ stating plainly because it is what a builder is comparing against. - [Operator arbitration](/quest/m2/teleop/arbitration.md) - exactly one controller commands a vehicle at a time, with explicit handoff and a stated authorization boundary -- [MAVLink bridge](/quest/m2/teleop/mavlink.md) - a `moq-mavlink` gateway - replacing the VPN plus two unmanaged UDP flows, with QGroundControl and - friends unchanged -- [Browser teleoperation package](/quest/m2/teleop/browser-package.md) - `@moq/robot` - mirrors the Rust crate, so browser clients consume the catalog and delivery - classes -- [SITL proof and browser ground station](/quest/m2/teleop/proof.md) - ArduPilot - SITL and a synthetic camera flown from a browser ground station, reproducible - in five minutes -- [V4L2-M2M encoding](/quest/m2/teleop/v4l2-encode.md) - a released `moq-cli` - reaches `moq-video`'s hardware encoder on the boards that fly, and the boards - worth buying are written down - [Teleoperation use-case docs](/quest/m2/teleop/docs.md) - `doc/concept/use-case/` gains a teleoperation page, with a runnable non-media example beside it -- [ROS 2 bridge](/quest/m2/teleop/ros2.md) - a ROS 2 bridge sibling to the - MAVLink one, carrying topics over the same two delivery classes -- [Cross-track correlation](/quest/m2/teleop/correlation.md) - a command, the - telemetry it produced, and the video frame showing the result share one - timebase ## Related - [e2ee](/quest/m1/e2ee/README.md) - the answer for a protected control link -- [Text schema](/quest/m1/text-schema.md) - non-media tracks in a catalog, - arrived at from the media side - [Media stats](/quest/m1/stats/schema.md) - publisher-reported stats on a catalog-announced track (moq#2734); teleop's latency instrumentation extends those types rather than adding a second stats surface - [Video hardware validation](/quest/m3/video-hardware.md) - the VAAPI run that covers Intel ground robots and NUC companions +- [CLI packaging](/quest/m1/cli-packaging.md) - ships the V4L2-M2M encoder the + boards that fly need +- [MAVLink bridge](/quest/m3/teleop-mavlink.md) - a `moq-mavlink` gateway, + parked until a real ArduPilot user or partner +- [SITL proof and browser ground station](/quest/m3/teleop-proof.md) - ArduPilot + SITL flown from a browser, parked with the bridge +- [Browser teleoperation package](/quest/m3/teleop-browser-package.md) - + `@moq/robot` mirroring the Rust crate, parked with the bridge +- [Text schema](/quest/m2/text-schema.md) - non-media tracks in a catalog, + arrived at from the media side diff --git a/quest/m2/teleop/correlation.md b/quest/m2/teleop/correlation.md deleted file mode 100644 index 1da8f218c59..00000000000 --- a/quest/m2/teleop/correlation.md +++ /dev/null @@ -1,32 +0,0 @@ -# [M] Cross-track correlation - -## Goal - -A command, the telemetry sample it produced, and the video frame showing the -result share one timebase, so a teleoperation recording is usable as training -data and an operator can be shown what the machine actually saw. - -## Plan - -The two hosts' clocks are related by deployment assumption, not by the library: -a robot deployment already synchronizes both ends. Each broadcast's fixed -catalog-root `clock: { wall, timescale }` is the bridge. Media and command -tracks keep their own timescales; convert PTS explicitly into the broadcast -clock before joining samples. The robot's video and telemetry share a clock; -the operator's command broadcast supplies its own synchronized mapping. - -Source restarts preserve each broadcast's mapping. There are no per-record -anchors or mutable `set_wall` epochs. Report whether a mapping is present, -but never infer that hosts are synchronized from its presence. State the clock -assumption beside the API, since a join across unsynchronized hosts can look -valid while being wrong. The library provides no clock-sync mechanism; see -[#2278](https://github.com/moq-dev/moq/issues/2278). - -This is also the answer to Kyber's headline claim of continuous drift -computation onto one unified timeline. Worth answering on the merits: -correlating sensor, command and video is the actual product need, and it is -the same property that makes an MCAP recording valuable. - -## Required - -- [Robot teleoperation primitive](/quest/m2/teleop/robot.md) diff --git a/quest/m2/teleop/robot.md b/quest/m2/teleop/robot.md index f88dd40f8b3..dd7d317ff01 100644 --- a/quest/m2/teleop/robot.md +++ b/quest/m2/teleop/robot.md @@ -82,6 +82,28 @@ The framing is where the guarantee lives, not the subscription flags: roughly 100 ms of a 130 ms glass-to-glass total, so we would mostly be measuring somebody's webcam. +### Cross-track correlation + +Decided in the 2026-09-30 audit: correlation folds in here rather than being +its own quest. A command, the telemetry sample it produced, and the video frame +showing the result share one timebase, so a recording is usable as training +data and an operator sees what the machine actually saw. + +The bridge is each broadcast's fixed catalog-root `clock: { wall, timescale }`, +documented in `doc/concept/hang.md` (#4461). Media and command tracks keep +their own timescales; convert PTS explicitly into the broadcast clock before +joining samples. The robot's video and telemetry share a clock; the operator's +command broadcast supplies its own mapping. + +The clock assumption: the two hosts' wall clocks are synchronized by the +deployment, not by the library. State this beside the API, since a join across +unsynchronized hosts looks valid while being wrong. Report whether a mapping is +present, but never infer synchronization from its presence. No per-record +anchors or clock-sync mechanism; see +[#2278](https://github.com/moq-dev/moq/issues/2278). + +### Port + Port `moq-boy` onto the crate in the same change, as the no-arbitration case. It is the only existing consumer, and if the abstraction cannot express crowd control then it is the wrong abstraction. diff --git a/quest/m2/teleop/ros2.md b/quest/m2/teleop/ros2.md deleted file mode 100644 index a7d6dfc919b..00000000000 --- a/quest/m2/teleop/ros2.md +++ /dev/null @@ -1,38 +0,0 @@ -# [L] ROS 2 bridge - -## Goal - -A ROS 2 bridge sibling to the MAVLink one, carrying topics over the same two -delivery classes. - -## Plan - -### It must land in MCAP - -Recordability is the axis this loses on if ignored. `rtsp_image_transport` -publishes a URL string, so rosbag2 records the URL and not the video; Foxglove's -`CompressedVideo` beat it despite banning B-frames and re-stapling parameter -sets to every keyframe, purely because it stays a recordable message. -Teleoperation video is training data, so a bridge that breaks the recording -loses regardless of latency. - -### Why not DDS - -Nobody runs RTPS over a WAN: discovery data grows quadratically, there is no -NAT traversal short of a port-forward rule per pair of communicating clients, -and reliable QoS on a lossy link produces latency spikes rather than delivery. -Every serious deployment already terminates DDS at the edge and -re-encapsulates. The competitors are the ones named in the questline README, -not the middleware. - -### Sizing - -Larger than the MAVLink bridge: type handling, QoS mapping, and the MCAP -requirement are each real work. Take it after the primitive has one integration -proving it, which is why it requires the MAVLink bridge rather than only the -crate. - -## Required - -- [Robot teleoperation primitive](/quest/m2/teleop/robot.md) -- [MAVLink bridge](/quest/m2/teleop/mavlink.md) diff --git a/quest/m2/teleop/v4l2-encode.md b/quest/m2/teleop/v4l2-encode.md deleted file mode 100644 index 222844d62b3..00000000000 --- a/quest/m2/teleop/v4l2-encode.md +++ /dev/null @@ -1,43 +0,0 @@ -# [S] V4L2-M2M encoding - -## Goal - -A released `moq-cli` encodes in hardware on the boards that fly, so a Raspberry -Pi needs no GStreamer detour, and the hardware worth buying is written down. - -## Plan - -The backend exists: `moq-video`'s opt-in `v4l2` feature drives the stateful -V4L2 M2M encoder and decoder through `rs/moq-video/src/v4l2.rs`, and both have -run on a Pi 4 (`bcm2835-codec`). What is left is getting it into people's -hands. - -Released `moq-cli` binaries are built with default features, so neither -`capture` nor `v4l2` is compiled in and the backend reaches nobody who installs -a release. A hardware encoder nobody can install is not a fix. [CLI -packaging](/quest/m1/cli-packaging.md) makes capture available; this quest must -also enable `v4l2` in the Linux ARM release build. It finishes once a released -binary on a Pi 4 publishes from `moq import capture` through the hardware -encoder. - -Write the hardware note down, in `doc/bin/cli.md` next to the capture build -instructions. Two landmines make it part of the deliverable: Raspberry Pi 5 has -no video encoder at all, and Jetson Orin Nano ships without NVENC. The boards -that still encode are Pi 4/CM4/Zero 2 W, Orin NX and above, and RK3588. -Rockchip stays excluded from the backend: RK3588 encoding goes through rkmpp in -a vendor kernel rather than V4L2, and the existing `moq-gst` route already ships -aarch64 packages for it. Adding an rkmpp backend is a separate decision. - -Validate what the Pi 4 run did not reach: `set_bitrate` on a running encoder -(congestion control retunes through it), resolutions past 640x360 where 1080p -codes as 1088 rows and the compose rectangle crops it back, and the other -`bcm2835-codec` boards (Zero 2 W, CM4). - -## Required - -- [CLI packaging](/quest/m1/cli-packaging.md) - the released binary has to - compile `capture` before a hardware encoder in it reaches anyone - -## Related - -- [Video hardware validation](/quest/m3/video-hardware.md) - the other unproven encoder backend, VAAPI diff --git a/quest/m1/text-schema.md b/quest/m2/text-schema.md similarity index 95% rename from quest/m1/text-schema.md rename to quest/m2/text-schema.md index d4fed133608..b7fd16f6c03 100644 --- a/quest/m1/text-schema.md +++ b/quest/m2/text-schema.md @@ -8,6 +8,8 @@ the audio or video timeline it transcribes. ## Plan +Deferred to m2 in the 2026-09-30 audit: no named consumer. + The `text` catalog section already carries the rest of the contract: relative `broadcast` references so a transcription can live in its own broadcast, cue timing on the shared media clock, and `jitter` for the publisher's flush diff --git a/quest/m2/ts-import-health.md b/quest/m2/ts-import-health.md index faf45a6a4df..77188dc12b8 100644 --- a/quest/m2/ts-import-health.md +++ b/quest/m2/ts-import-health.md @@ -81,7 +81,7 @@ Decided while planning [#1838](https://github.com/moq-dev/moq/issues/1838): - **No opaque whole-mux lane**: [#1861](https://github.com/moq-dev/moq/issues/1861) is closed not planned and verbatim TS is a non-goal in - [MSFTS convergence](/quest/m4/msfts-convergence.md). P3 is out of this set; + [MSFTS convergence](/quest/m2/msfts-convergence.md). P3 is out of this set; `CAT_error` too, since the lane carries no scrambled service. A scrambled PAT or PMT still counts under its own check. diff --git a/quest/m1/perf/uring-open-contract.md b/quest/m2/uring-open-contract.md similarity index 75% rename from quest/m1/perf/uring-open-contract.md rename to quest/m2/uring-open-contract.md index f49a4e3196a..39e37fa4c5e 100644 --- a/quest/m1/perf/uring-open-contract.md +++ b/quest/m2/uring-open-contract.md @@ -19,6 +19,10 @@ bounds, cancellation behavior, and regression cases for concurrent openers, credit starvation, dropped futures, and finish/drop. This quest ships the plan; it does not close #3129 or implement an unsettled public contract. +Decided in the 2026-09-30 audit: moved to m2 with #3129, which it plans. +io_uring ships in no package, and #3129 fixes an API wart no in-tree caller +hits. + ## Related -- [Write headers at open](/quest/m1/perf/3129-moq-uring-write-the-webtransport-stream-header-at-open.md) - implementation after the contract is settled +- [Write headers at open](/quest/m2/3129-moq-uring-write-the-webtransport-stream-header-at-open.md) - implementation after the contract is settled diff --git a/quest/m1/uring-tcp/README.md b/quest/m2/uring-tcp/README.md similarity index 76% rename from quest/m1/uring-tcp/README.md rename to quest/m2/uring-tcp/README.md index f18fc505373..831e86655f7 100644 --- a/quest/m1/uring-tcp/README.md +++ b/quest/m2/uring-tcp/README.md @@ -19,10 +19,10 @@ The three quests below ship together as one capability, in order. The prerequisite that shapes the middle quest: **qmux sessions arrive through the axum router**. `web.rs` routes `/` and `/{*path}` to -`websocket::serve_ws` (rs/moq-relay/src/web.rs:256-259). The gate is +`websocket::serve_ws` (rs/moq-relay/src/web.rs:343-344). The gate is moq-relay's own `websocket` feature (rs/moq-relay/Cargo.toml:43, which is what turns on `axum/ws`) plus the runtime `resolved_ws()` check -(web.rs:257), so a WebSocket session is an HTTP upgrade before it is a media +(web.rs:342), so a WebSocket session is an HTTP upgrade before it is a media session. There is no moving qmux onto the ring without also running the HTTP server that upgrades it there. That is not a reason to rewrite axum: hyper is runtime-agnostic, so implementing `hyper::rt::{Read, Write, Executor}` over @@ -33,11 +33,16 @@ Measure before porting, the same way the echo bench (rs/moq-uring/benches/session_lite.rs) gated the UDP path. The ablation's number is what justifies the rest of the line. +Decided in the 2026-09-30 audit: moved to m2. The +[transport upgrade](/quest/m1/transport-upgrade/README.md) shrinks the +WebSocket hot path by moving clients to QUIC, and no fleet demand asks for +ring TCP. + ## Required -- [Ablation](/quest/m1/uring-tcp/ablation.md) - measure ring TCP against tokio +- [Ablation](/quest/m2/uring-tcp/ablation.md) - measure ring TCP against tokio TCP under the qmux workload before committing to the port -- [Stream](/quest/m1/uring-tcp/stream.md) - a `tcp` module in `moq-uring`, and +- [Stream](/quest/m2/uring-tcp/stream.md) - a `tcp` module in `moq-uring`, and the `hyper::rt` adapters that let axum run on it -- [Relay](/quest/m1/uring-tcp/relay.md) - serve the relay's WebSocket and +- [Relay](/quest/m2/uring-tcp/relay.md) - serve the relay's WebSocket and stream listeners from the io_uring workers diff --git a/quest/m1/uring-tcp/ablation.md b/quest/m2/uring-tcp/ablation.md similarity index 100% rename from quest/m1/uring-tcp/ablation.md rename to quest/m2/uring-tcp/ablation.md diff --git a/quest/m1/uring-tcp/relay.md b/quest/m2/uring-tcp/relay.md similarity index 92% rename from quest/m1/uring-tcp/relay.md rename to quest/m2/uring-tcp/relay.md index c9427116628..cfce78c5203 100644 --- a/quest/m1/uring-tcp/relay.md +++ b/quest/m2/uring-tcp/relay.md @@ -13,7 +13,7 @@ the operator at a separate `init_streams` tokio server (rs/moq-relay/src/uring.rs:116-120); the only thing it refuses is `tls.generate` (:126-128). Replace the silent skip with real support: each worker binds its own listener in the reuseport group and runs the router from -[stream](/quest/m1/uring-tcp/stream.md) on it. +[stream](/quest/m2/uring-tcp/stream.md) on it. The split of work stays what `uring.rs` already documents (:10-15): the worker owns everything transport-shaped, while authentication and session @@ -29,5 +29,5 @@ worker. ## Required -- [Stream](/quest/m1/uring-tcp/stream.md) - the module and adapters this +- [Stream](/quest/m2/uring-tcp/stream.md) - the module and adapters this serves from diff --git a/quest/m1/uring-tcp/stream.md b/quest/m2/uring-tcp/stream.md similarity index 96% rename from quest/m1/uring-tcp/stream.md rename to quest/m2/uring-tcp/stream.md index 780f6d9c325..c0ce1630d23 100644 --- a/quest/m1/uring-tcp/stream.md +++ b/quest/m2/uring-tcp/stream.md @@ -32,4 +32,4 @@ existing suite does. ## Required -- [Ring TCP ablation](/quest/m1/uring-tcp/ablation.md) - a positive verdict selects the mechanisms before the worker implementation starts +- [Ring TCP ablation](/quest/m2/uring-tcp/ablation.md) - a positive verdict selects the mechanisms before the worker implementation starts diff --git a/quest/m2/video-codec-coverage.md b/quest/m2/video-codec-coverage.md index 36b369303b5..423619c9ca3 100644 --- a/quest/m2/video-codec-coverage.md +++ b/quest/m2/video-codec-coverage.md @@ -30,5 +30,5 @@ Public API and wire: no changes during this study. ## Related - [NVIDIA formats](/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md) - existing AV1 encode and 10-bit scope -- [VAAPI](/quest/m4/video-vaapi.md) - existing Linux codec expansion - [VP8/VP9](/quest/m1/obs-moq-video/vpx.md) - existing portable decoder scope +- [VAAPI](/quest/m2/video-vaapi.md) - existing Linux codec expansion diff --git a/quest/m4/video-vaapi.md b/quest/m2/video-vaapi.md similarity index 66% rename from quest/m4/video-vaapi.md rename to quest/m2/video-vaapi.md index 1f3ee5658a7..eb95c2e0a8a 100644 --- a/quest/m4/video-vaapi.md +++ b/quest/m2/video-vaapi.md @@ -4,12 +4,17 @@ VAAPI encodes H.264 and H.265 from a DMA-BUF without a download, decodes H.265 as well as H.264, and the `vaapi` feature costs a consumer nothing at -build time so it can return to default-on. Every piece needs a `moq-dev/vaapi` -release first. +build time so it can return to default-on. A resize reuses its output +surfaces. ## Plan -Three gaps, one external dependency. +Decided in the 2026-09-30 audit: moved from m4, and the "gated on a +`moq-dev/vaapi` release" blocker is gone. That crate is our own repo (last +release 0.1.0 on 2026-09-24), so this quest includes the crate work (HEVC +encode, H.265 decode, pre-generated bindings, the resize pool) and cutting the +release, then bumping the workspace requirement here. The resize-pool quest +folds in for the same reason. **Decode.** The H.264 decoder landed (moq-vaapi 0.0.4, `decode/backend/vaapi.rs`), with the default `decode::Config::output` of `Output::Native` handing out @@ -39,16 +44,15 @@ fixed-width types, `c_char` left symbolic), so one checked-in file serves every Linux target, as `moq-v4l` already does for `videodev2.h`. Then the feature can return to default-on here. +**Resize pool.** moq-vaapi's `Processor` allocates the blit output with +`ExportedFrame::from_surface` on every resize. Keep one surface per output +size; when the exported frame drops, the surface returns for the next blit of +that size. A frame the consumer still holds is not overwritten; the processor +allocates another. Keep at most one free surface per size and destroy any +returned past that, the decoder pool's rule. `Surface::resize` stays the same +call. The reuse test belongs in moq-vaapi; here, confirm a resize still returns +an NV12 DMA-BUF. + Note what is already fine: a host with libva present but no usable VA driver already falls back cleanly, since `Encoder::new` returns `Err` and `backend::open` drops to openh264. - -## Required - -- A `moq-dev/vaapi` release exposing an HEVC encoder (H.264 decode is in - 0.0.4; DMA-BUF encode and VPP shipped in 0.1.0) and pre-generated bindings - instead of a bindgen build script - -## Related - -- [Pool VAAPI resize surfaces](/quest/m4/vaapi-resize-pool.md) - reuse one VPP output surface per size, a separate moq-vaapi release diff --git a/quest/m2/x11-capture-shm.md b/quest/m2/x11-capture-shm.md index 15e21051fe9..dbf4f8b9840 100644 --- a/quest/m2/x11-capture-shm.md +++ b/quest/m2/x11-capture-shm.md @@ -24,9 +24,12 @@ capture does the same thing with a per-frame `get_geometry`; it already selects `StructureNotify` and drains that queue between frames, so `ConfigureNotify` is there to be consumed and the round trip dropped. -Both changes are contained to the one backend and are verifiable on a Linux +Decided in the 2026-09-30 audit: the X11 half of the frame-buffer quest folds +in here, since it is the same read path. `PixelFormat::rgb` allocates a +`w * h * 3` `Vec` per frame and fills it with three `push` calls per pixel, +then `I420::from_rgb` walks it again into a third buffer. Reuse an +`&mut Vec` the `Capture` owns and `clear()` it, so the allocation happens +once. Measure before and after rather than assuming. + +All of these changes are contained to the one backend and are verifiable on a Linux host with a real X session; CI compiles the file but cannot run it. - -## Related - -- [Capture frame buffers](/quest/m2/capture-frame-buffers.md) - the per-frame allocations in the same read path diff --git a/quest/m3/2893-video-validate-pipewire-dma-buf-capture-on-kde-hardware.md b/quest/m3/2893-video-validate-pipewire-dma-buf-capture-on-kde-hardware.md deleted file mode 100644 index a911c2f6558..00000000000 --- a/quest/m3/2893-video-validate-pipewire-dma-buf-capture-on-kde-hardware.md +++ /dev/null @@ -1,66 +0,0 @@ -# [M] video: validate PipeWire DMA-BUF capture on KDE hardware - -## Goal - -Implement and verify the behavior tracked in [#2893](https://github.com/moq-dev/moq/issues/2893) -within the issue's stated scope and boundaries. - -## Plan - -Use the public issue's scope, implementation notes, and acceptance criteria -below as the starting plan. Reconcile paths and assumptions with the current -tree before implementation. - -### Issue context - -#### Problem - -Hardware validation for #2839 did not complete on a KDE/Wayland desktop. The screen source was selected in the portal, but the ignored PipeWire capture test never received a frame and timed out after 120 seconds. - -This is a focused follow-up to the broader Linux zero-copy tracker in #2819. - -#### Environment - -- KDE desktop on Wayland -- `XDG_CURRENT_DESKTOP=KDE` -- `WAYLAND_DISPLAY=wayland-0` -- `DISPLAY=:0` -- `XDG_RUNTIME_DIR=/run/user/1000` -- Active desktop D-Bus session - -#### Reproduction - -Run from the Nix development shell after #2839: - -```sh -cargo nextest run --profile ci -p moq-video --all-features --run-ignored ignored-only portal_captures_frames --no-capture -``` - -During review, a temporary assertion also required captured frames to be `Surface::DmaBuf`. The run reached the test, the portal source was selected, then nextest reported the test as slow after 60 seconds and terminated it at 120 seconds without receiving a frame. - -#### Expected - -- Portal selection completes. -- PipeWire format and buffer negotiation completes. -- The first frame arrives within the existing capture timeout. -- A DMA-BUF-capable compositor produces `Surface::DmaBuf`; shared memory remains a working fallback. - -#### Validation - -- \[ ] Reproduce the post-selection timeout on KDE/Wayland. -- \[ ] Add tracing around portal completion, PipeWire connection, format fixation, buffer allocation, and first-frame delivery to locate the stall. -- \[ ] Validate packed RGB DMA-BUF capture and Vulkan import on Intel or AMD hardware. -- \[ ] Validate the linear DMA-BUF CPU fallback. -- \[ ] Confirm shared-memory PipeWire capture still works when DMA-BUF is unavailable. -- \[ ] Hold multiple frames long enough to exercise buffer leasing without pool exhaustion or reused content. -- \[ ] Add or refine an ignored hardware test so the observed failure is distinguishable from a portal-selection timeout. - -Refs #2839 and #2819. - -## Closes - -- [#2893](https://github.com/moq-dev/moq/issues/2893) - close this issue when the quest finishes - -## Related - -- [#2819: moq-video: carry PipeWire DMA-BUFs safely into the Vulkan renderer](/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md) - related open work diff --git a/quest/m1/perf/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md b/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md similarity index 90% rename from quest/m1/perf/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md rename to quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md index 5315677c57f..9930a37408f 100644 --- a/quest/m1/perf/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md +++ b/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md @@ -35,6 +35,14 @@ The UDP path already assembles up to 64 KiB GSO trains in stable pool buffers, t Sweep the threshold across realistic chat and media packet trains. Record relay CPU, goodput, CQEs per send, copy-fallback rate, TX-pool pressure, p99 latency, and memory residency at fixed offered load. Enable it by default only where the end-to-end result beats regular `SendMsg`. +Decided in the 2026-09-30 audit: moved to m3. The #3224 prototype was 6 to +9% slower, the win needs a physical-NIC sweep nobody has run, and io_uring +ships in no package. + +## Required + +- A physical-NIC remote peer to measure zero-copy sends against + ## Closes - [#3201](https://github.com/moq-dev/moq/issues/3201) - close this issue when the quest finishes diff --git a/quest/m1/perf/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md b/quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md similarity index 88% rename from quest/m1/perf/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md rename to quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md index 86f4ebb14ae..05aa724c3d3 100644 --- a/quest/m1/perf/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md +++ b/quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md @@ -34,9 +34,13 @@ The TX pool already owns stable `Box<[u8]>` allocations and grows lazily. If zer Compare #3201 with and without registered buffers using the same threshold and workload matrix. Record CPU, cycles, registration cost, locked memory, pool starvation, throughput, and latency. Do not add the complexity unless it improves the winning zero-copy range beyond ordinary `SendMsgZc`. +Decided in the 2026-09-30 audit: moved to m3. Fixed buffers on +`SENDMSG_ZC` need Linux 6.15, above the 6.12 floor, and the #3201 +experiment it builds on moved to m3 too. + ## Required -- [#3201: moq-uring: use SENDMSG_ZC for large UDP GSO trains](/quest/m1/perf/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md) - complete the prerequisite issue first +- [#3201](/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md) - the zero-copy send experiment this extends ## Closes diff --git a/quest/m3/README.md b/quest/m3/README.md index 5f1ec16b652..57d33620742 100644 --- a/quest/m3/README.md +++ b/quest/m3/README.md @@ -3,22 +3,48 @@ ## Goal Work whose first step is outside this repository: hardware nobody on the team -has, a partner or customer, or a hosting provider's offer. Nothing here can -start by opening an editor. +has, a partner or customer who asks for it, or a hosting provider's offer. +Nothing here should start by opening an editor. ## Plan -A quest lands here when its gate is the outside world, not its priority. Each -states the condition in prose or as a plain-text `Required` bullet. When the -condition clears, move the quest to the milestone its work belongs in. +A quest lands here when its gate is the outside world, not its priority. Its gate +is a plain-text `Required` bullet, re-checked as the root +[questline](/quest/README.md) describes. A +speculative feature with no consumer parks here rather than in m2, and is +deleted when it goes stale; git history keeps it. ## Required -- [DPDK](/quest/m3/dpdk.md) - a kernel-bypass UDP path for the relay, once a provider offers SR-IOV or bare metal -- [Video hardware validation](/quest/m3/video-hardware.md) - run the encode, capture, and zero-copy paths that were written but never run on real machines -- [Validate PipeWire cameras on a portal and a Pi](/quest/m3/pipewire-camera-hardware.md) - run the shipped PipeWire camera through the camera portal and a Pi CSI node -- [#2893](/quest/m3/2893-video-validate-pipewire-dma-buf-capture-on-kde-hardware.md) - video: validate PipeWire DMA-BUF capture on KDE hardware +- [Video hardware validation](/quest/m3/video-hardware.md) - run the encode, capture, and zero-copy paths that were never run on real machines, including PipeWire on KDE, the camera portal, and a Pi +- [NVENC AV1](/quest/m3/nvenc-av1.md) - AV1 encode through NVENC, once an Ada-generation GPU is available - [Embedded video](/quest/m3/video-embedded.md) - EGL import in the renderer, so moq-video presents on a Pi -- [Vision worker](/quest/m3/processor-vision.md) - a documented customer-run vision worker proves the processor contract -- [Announcement shapes](/quest/m3/announce-shapes.md) - moq-lite announcements and interests carry prefix, exact, suffix, or prefix+suffix shapes that survive relay hops, benchmarked over the announce table -- [Upstream forks](/quest/m3/upstream-forks.md) - offer the uniffi generator fixes our cpp, dart, and Python forks carry upstream, lowest priority +- [#3201: moq-uring: use SENDMSG_ZC for large UDP GSO trains](/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md) - complete the prerequisite issue first +- [#3204](/quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md) - moq-uring: register TX-pool buffers for zero-copy sends +- [Receive timestamps](/quest/m3/quic-receive-ts.md) - per-packet arrival times in ACKs, the feedback GCC and deadlines need +- [QUIC GCC](/quest/m3/quic-gcc.md) - a measured verdict on delay-based congestion control for media egress, shipping as `RealTime` +- [AF_XDP UDP path](/quest/m3/af-xdp.md) - the kernel-bypass verdict on today's virtio hosts that gates DPDK +- [C# through moq-ffi](/quest/m3/cs/README.md) - generated C# over moq-ffi as a NuGet package with native runtimes +- [Unity prototype](/quest/m3/unity.md) - the C# package under IL2CPP, playing subscribed audio +- [Unreal prototype](/quest/m3/unreal.md) - a UE5 module on the C++ package with exceptions disabled, rendering a subscribed broadcast to a texture +- [LiveKit client shim](/quest/m3/livekit-shim.md) - a media compatibility facade over the room SDK +- [Conan remote](/quest/m3/cpp-conan.md) - a remote we own serves the same tarball to `conan install` +- [WHEP ABR](/quest/m3/whep-abr.md) - a WHEP viewer switches renditions from its own congestion feedback +- [Synced data playback](/quest/m3/watch-data-sync.md) - js/watch releases JSON and binary payloads on the media playhead, and a slow data track holds media back +- [Linux OBS GPU input](/quest/m3/obs-linux-gpu.md) - publish OBS compositor frames without CPU readback on a validated Linux graphics/encoder combination +- [Routing cost domains](/quest/m3/routing-cost-domains.md) - design operator boundaries and policy without adding incomparable costs +- [Common Access Tokens](/quest/m3/cat/README.md) - a moq-transport client presents a CAT in SETUP and `moq auth serve` admits it with the scope its `moqt` claim names +- [Drop the hidden cluster exemption](/quest/m3/hidden-exemption.md) - relays stop forcing hidden broadcasts on cluster peers once every peer opts in on the wire +- [MAVLink bridge](/quest/m3/teleop-mavlink.md) - a `moq-mavlink` gateway + replacing the VPN plus two unmanaged UDP flows, with QGroundControl and + friends unchanged +- [SITL proof and browser ground station](/quest/m3/teleop-proof.md) - ArduPilot + SITL and a synthetic camera flown from a browser ground station, reproducible + in five minutes +- [Browser teleoperation package](/quest/m3/teleop-browser-package.md) - `@moq/robot` + mirrors the Rust crate, so browser clients consume the catalog and delivery + classes +- [Encode config](/quest/m3/intra-refresh-encode-config.md) - refresh mode extends the settled GOP contract; the producer cuts groups per sweep and publishes `warmup` +- [NVENC refresh](/quest/m3/intra-refresh-nvenc.md) - the NVENC backend encodes refresh mode for H.264 and HEVC +- [V4L2 refresh](/quest/m3/intra-refresh-v4l2.md) - the V4L2 backend encodes refresh mode +- [Bindings](/quest/m3/intra-refresh-bindings.md) - moq-ffi and every wrapper expose refresh mode, additive on the ffi-shape `Gop` enum diff --git a/quest/m2/af-xdp.md b/quest/m3/af-xdp.md similarity index 65% rename from quest/m2/af-xdp.md rename to quest/m3/af-xdp.md index 775b7b34c63..9ae34da3b0a 100644 --- a/quest/m2/af-xdp.md +++ b/quest/m3/af-xdp.md @@ -6,7 +6,7 @@ A measured verdict on an AF_XDP socket as the io_uring worker's UDP path on the hosts the fleet runs today. virtio-net supports AF_XDP in copy mode on any Linode or OVH instance and zero-copy where the driver allows; if it lifts the per-worker packet ceiling or cuts CPU per Gbps materially against the -io_uring path, the DPDK question becomes concrete; if not, kernel bypass is +io_uring path, full kernel bypass becomes a concrete question; if not, it is closed until hardware changes. ## Plan @@ -17,10 +17,12 @@ closed until hardware changes. behind a feature; nothing ships. - Measure packets per second, CPU per Gbps, and p99 latency on one virtio host in copy mode, on the chat and fanout shapes, against the io_uring path - with the zero-copy and busy-poll quests' best settings. + with the zero-copy quests' best settings. -## Related +Decided in the 2026-09-30 audit: moved to m3. The relay packages don't ship +io_uring yet, so a bypass that competes with it has no deployment to +improve. -- [DPDK](/quest/m3/dpdk.md) - the full bypass this verdict gates -- [#3203](/quest/m1/perf/3203-moq-uring-add-opt-in-napi-busy-polling.md) - - the in-kernel ceiling this competes with +## Required + +- [Relay io_uring packages](/quest/m2/relay-io-uring-package.md) - the io_uring path this is compared against ships first diff --git a/quest/m2/cat/README.md b/quest/m3/cat/README.md similarity index 90% rename from quest/m2/cat/README.md rename to quest/m3/cat/README.md index d68c4ec7d54..40871479531 100644 --- a/quest/m2/cat/README.md +++ b/quest/m3/cat/README.md @@ -41,6 +41,10 @@ Boundaries decided while planning: ## Plan +In m3 because nobody is asking for CAT yet and the claim keys are +unregistered; a consumer presenting CATs, or the draft registering the keys, +brings it back. + Order: the SETUP option already reaches the auth server as `moq_auth::Request.token`; verification comes first, then our clients present one. Everything rides `moq_auth::Request` and @@ -49,10 +53,11 @@ one. Everything rides `moq_auth::Request` and ## Required -- [Verify](/quest/m2/cat/verify.md) - `moq_auth::cat` turns a CAT into a +- draft-ietf-moq-c4m registers the moqt claim keys +- [Verify](/quest/m3/cat/verify.md) - `moq_auth::cat` turns a CAT into a grant and `moq auth serve` admits one; `moq auth sign|verify` mint and check the format -- [Present](/quest/m2/cat/present.md) - a CAT is one kind of configured +- [Present](/quest/m3/cat/present.md) - a CAT is one kind of configured token, riding the SETUP option the in-band token quest already writes ## Related diff --git a/quest/m2/cat/present.md b/quest/m3/cat/present.md similarity index 88% rename from quest/m2/cat/present.md rename to quest/m3/cat/present.md index 8fcd5185864..53b2a8f877e 100644 --- a/quest/m2/cat/present.md +++ b/quest/m3/cat/present.md @@ -13,9 +13,9 @@ the option fails loud instead of dropping the credential. - [Token in band](/quest/m1/auth/token-in-band.md) defines the client token configuration and writes the first configured token into the setup option - as type 0. This quest makes the kind explicit: each configured token is a - `moq_net::setup::Token { kind, value }`, a JWT keeps kind `0x0` and its - URL and AUTH stream behavior, and a CAT is kind `0x01`. `--connect-token` + as type 0. `moq_net::setup::Token { kind, value }` already carries the + kind, with CAT = `0x1` (#4278); a JWT keeps kind `0x0` and its URL and + AUTH stream behavior. `--connect-token` keeps taking a JWT; `--connect-cat ` (and `MOQ_CONNECT_CAT`) adds a CAT. One CAT per connection: it is the connection credential, so a configured CAT takes the setup option and the JWT that would have gone @@ -40,7 +40,7 @@ Public API: additive on `moq-tokio` and `js/net`. Wire: none. ## Required -- [Verify](/quest/m2/cat/verify.md) - the server that admits the token the +- [Verify](/quest/m3/cat/verify.md) - the server that admits the token the end-to-end test presents - [Token in band](/quest/m1/auth/token-in-band.md) - the token configuration and setup-option writer this adds a kind to diff --git a/quest/m2/cat/verify.md b/quest/m3/cat/verify.md similarity index 100% rename from quest/m2/cat/verify.md rename to quest/m3/cat/verify.md diff --git a/quest/m2/cpp-conan.md b/quest/m3/cpp-conan.md similarity index 91% rename from quest/m2/cpp-conan.md rename to quest/m3/cpp-conan.md index 19e36c2ac2c..9d7048dc7b3 100644 --- a/quest/m2/cpp-conan.md +++ b/quest/m3/cpp-conan.md @@ -9,6 +9,9 @@ Windows, macOS, and Linux. ## Plan +In m3 until a Conan consumer asks; vcpkg and the release tarball cover +C++ consumers first. + - A `moq-cpp` recipe, named after the package, on a moq-dev remote (Artifactory or a GitHub-hosted `conan` index) that packages the prebuilt release tarball per setting and exports the `moq::cpp` CMake target from diff --git a/quest/m2/cs/README.md b/quest/m3/cs/README.md similarity index 78% rename from quest/m2/cs/README.md rename to quest/m3/cs/README.md index 69c17b0a8dd..dca620bd43a 100644 --- a/quest/m2/cs/README.md +++ b/quest/m3/cs/README.md @@ -10,6 +10,9 @@ a mirror. Unity is a separate prototype. ## Plan +In m3 until a .NET or Unity consumer asks; the C++ line covers native +embedders first. + NordSecurity's `uniffi-bindgen-cs` (latest `v0.11.0+v0.31.0`) already emits async methods as `Task` and async callback interfaces; it needs the same uniffi 0.32 port the Go, Dart, and C++ generators got. Plain .NET first; the @@ -19,10 +22,10 @@ up front. ## Required -- [Generator](/quest/m2/cs/generator.md) - uniffi-bindgen-cs on uniffi 0.32, pinned and generating `cs/ffi` in CI -- [Package](/quest/m2/cs/package.md) - the `cs/moq` wrapper, NuGet package with native runtimes, interop client, and docs +- [Generator](/quest/m3/cs/generator.md) - uniffi-bindgen-cs on uniffi 0.32, pinned and generating `cs/ffi` in CI +- [Package](/quest/m3/cs/package.md) - the `cs/moq` wrapper, NuGet package with native runtimes, interop client, and docs ## Related - [C++ through moq-ffi](/quest/m1/cpp/README.md) - the sibling line this copies -- [Unity prototype](/quest/m2/unity.md) - the package under IL2CPP +- [Unity prototype](/quest/m3/unity.md) - the package under IL2CPP diff --git a/quest/m2/cs/generator.md b/quest/m3/cs/generator.md similarity index 100% rename from quest/m2/cs/generator.md rename to quest/m3/cs/generator.md diff --git a/quest/m2/cs/package.md b/quest/m3/cs/package.md similarity index 94% rename from quest/m2/cs/package.md rename to quest/m3/cs/package.md index 5b5eadd73c4..7937460b0f2 100644 --- a/quest/m2/cs/package.md +++ b/quest/m3/cs/package.md @@ -24,4 +24,4 @@ interop --all` and `doc/lib/cs` documents the package. ## Required -- [Generator](/quest/m2/cs/generator.md) - the pinned generator that emits `cs/ffi` +- [Generator](/quest/m3/cs/generator.md) - the pinned generator that emits `cs/ffi` diff --git a/quest/m3/dpdk.md b/quest/m3/dpdk.md deleted file mode 100644 index efaf48e21ca..00000000000 --- a/quest/m3/dpdk.md +++ /dev/null @@ -1,28 +0,0 @@ -# [XL] DPDK - -## Goal - -A relay build whose io_uring workers are replaced by DPDK poll-mode workers -owning a NIC queue each, measured against the kernel path on the same host. -Worth building only on hardware with SR-IOV virtual functions or a dedicated -NIC; neither Linode nor OVH VPS, where the fleet runs, offers either. - -## Plan - -Do not start until the [AF_XDP spike](/quest/m2/af-xdp.md) has a verdict: it -runs on today's hosts and bounds what bypass can buy. If it shows the kernel -path is within reach of line rate, this quest is abandoned. - -When a provider offers the hardware: a `moq-dpdk` worker crate mirroring -`moq-uring`'s worker contract (one QUIC endpoint per worker, connection-ID -steering by the NIC's RSS or a flow rule), userspace UDP/IP, and the noq -endpoint driven from the poll loop. Measure packets per second, CPU per -Gbps, and p99 latency against io_uring on the same box, then decide whether -a bare-metal tier is worth operating. - -## Required - -- [AF_XDP UDP path](/quest/m2/af-xdp.md) - the no-hardware verdict this waits - on; a kernel path within reach of line rate abandons this quest -- A moq.pro relay provider offers SR-IOV or bare-metal hosts the fleet can - run on diff --git a/quest/m2/hidden-exemption.md b/quest/m3/hidden-exemption.md similarity index 84% rename from quest/m2/hidden-exemption.md rename to quest/m3/hidden-exemption.md index 18a993aca67..97dc8acac6e 100644 --- a/quest/m2/hidden-exemption.md +++ b/quest/m3/hidden-exemption.md @@ -9,6 +9,9 @@ for peers that predate it. ## Plan +In m3 because it waits on a deployment, not on code; it comes back once +the mesh runs lite-07. + - Remove the `cluster_peer` argument from `connection::authorize` and its callers in `rs/moq-relay/src/{connection,uring,websocket}.rs`, and the forced `with_hidden(true)` on the outbound dial in `rs/moq-relay/src/cluster.rs`. @@ -17,4 +20,4 @@ for peers that predate it. ## Required -- Every deployed relay in the moq.pro mesh speaks a finalized moq-lite-07 or MoQ Hidden; `moq-lite-07-wip` is opt-in only. +- The moq.pro mesh deploys lite-07 diff --git a/quest/m2/intra-refresh/bindings.md b/quest/m3/intra-refresh-bindings.md similarity index 94% rename from quest/m2/intra-refresh/bindings.md rename to quest/m3/intra-refresh-bindings.md index 78bbc95863d..ea45a3093db 100644 --- a/quest/m2/intra-refresh/bindings.md +++ b/quest/m3/intra-refresh-bindings.md @@ -21,5 +21,5 @@ both modes. ## Required -- [Encode config](/quest/m2/intra-refresh/encode-config.md) - the core refresh variant this mirrors +- [Encode config](/quest/m3/intra-refresh-encode-config.md) - the core refresh variant this mirrors - [Codecs](/quest/m1/ffi-shape/codec.md) - the `MoqVideoGop` enum this extends diff --git a/quest/m2/intra-refresh/encode-config.md b/quest/m3/intra-refresh-encode-config.md similarity index 86% rename from quest/m2/intra-refresh/encode-config.md rename to quest/m3/intra-refresh-encode-config.md index ab4f51ead77..14de81adb48 100644 --- a/quest/m2/intra-refresh/encode-config.md +++ b/quest/m3/intra-refresh-encode-config.md @@ -14,6 +14,11 @@ without replacing an API after 0.1. ## Plan +Decided in the 2026-09-30 audit: the encode side moved to m3 pending the +[GOP overhead](/quest/m2/gop-overhead.md) verdict. If a short keyframe GOP +is cheap, a flat bitrate is not worth encoder work; imported refresh streams +are still handled by [the m2 line](/quest/m2/intra-refresh/README.md). + - Extend the non-exhaustive `Gop` contract from main with refresh mode. Keep the settled frame-count units and `cut()` operation; do not replace the public config or rename the operation again. A cut in refresh mode asks @@ -43,4 +48,5 @@ without replacing an API after 0.1. ## Required +- [GOP overhead](/quest/m2/gop-overhead.md) - the verdict on whether keyframe cost justifies refresh encoding - [Catalog warmup](/quest/m1/catalog-warmup.md) - the field the producer publishes diff --git a/quest/m2/intra-refresh/nvenc-refresh.md b/quest/m3/intra-refresh-nvenc.md similarity index 78% rename from quest/m2/intra-refresh/nvenc-refresh.md rename to quest/m3/intra-refresh-nvenc.md index 5040bc67a0d..e540a8c3e25 100644 --- a/quest/m2/intra-refresh/nvenc-refresh.md +++ b/quest/m3/intra-refresh-nvenc.md @@ -21,12 +21,16 @@ refuses the mode. producer's `warmup` matches the refreshed macroblocks, and translate a cut into a forced sweep restart instead of `FORCEIDR`. Check the capability at construction and refuse without it. -- Verification needs hardware: no CI runner has an NVIDIA GPU, so run the - probe by hand, feed the output through the H.264 and H.265 import quests' +- Verification needs hardware: run it on the [GPU CI](/quest/m1/gpu-ci.md) + host once it exists, else run the probe by hand, feed the output through the H.264 and H.265 import quests' splitters to confirm one group per sweep and the SEI count, and record the numbers in the PR. Any test that needs the GPU skips loudly rather than reporting success. ## Required -- [Encode config](/quest/m2/intra-refresh/encode-config.md) - the `Gop` enum and cut semantics this implements +- [Encode config](/quest/m3/intra-refresh-encode-config.md) - the `Gop` enum and cut semantics this implements + +## Related + +- [GPU CI](/quest/m1/gpu-ci.md) - the RTX 3070 Ti runner that can verify this without a hand run diff --git a/quest/m2/intra-refresh/v4l2-refresh.md b/quest/m3/intra-refresh-v4l2.md similarity index 96% rename from quest/m2/intra-refresh/v4l2-refresh.md rename to quest/m3/intra-refresh-v4l2.md index 20b3c1fb1d2..40e969ae202 100644 --- a/quest/m2/intra-refresh/v4l2-refresh.md +++ b/quest/m3/intra-refresh-v4l2.md @@ -34,4 +34,4 @@ claiming a boundary that was not encoded. ## Required -- [Encode config](/quest/m2/intra-refresh/encode-config.md) - the `Gop` enum and cut semantics this implements +- [Encode config](/quest/m3/intra-refresh-encode-config.md) - the `Gop` enum and cut semantics this implements diff --git a/quest/m2/livekit-shim.md b/quest/m3/livekit-shim.md similarity index 74% rename from quest/m2/livekit-shim.md rename to quest/m3/livekit-shim.md index 6e5697e38c7..74e35d14d41 100644 --- a/quest/m2/livekit-shim.md +++ b/quest/m3/livekit-shim.md @@ -13,10 +13,14 @@ and the connect URL/token changed. ## Plan +In m3 until a LiveKit user asks to migrate; `@moq/room` already serves +new rooms directly. + - The shim is a LiveKit-API facade over `@moq/room`, which carries hang.live's convention: the room is a path prefix in the connection URL and token root, participants are discovered from the bare announce stream, identity is the - next path segment, and each participant publishes `/camera` - (camera + mic, hd/sd renditions) and `/screen` (screenshare, + path before the broadcast name, and each participant publishes + `/camera.hang` (camera + mic, hd/sd renditions) and + `/screen.hang` (screenshare, whose announce/unannounce is the screenshare lifecycle). The shim groups the two paths per identity into one RemoteParticipant and maps catalog entries to TrackPublications. @@ -27,10 +31,10 @@ and the connect URL/token changed. state derives from catalog track presence. Names and coarse state are a follow-up wired to the room SDK's `hang/*.json` metadata, not a rival scheme. -- Recommend tokens scoped to `put: /` so participants cannot - publish at each other's paths (hang.live grants `put` on the whole room - subtree today). +- Mint tokens with `@moq/room`'s `claims(room, identity)`, which scopes the + `publish` claim to the identity's subtree so participants cannot publish at + each other's paths. -## Related +## Required -- [WebRTC bridge evaluation](/quest/m2/livekit-webrtc-bridge.md) +- A LiveKit user asks for a drop-in client diff --git a/quest/m3/nvenc-av1.md b/quest/m3/nvenc-av1.md new file mode 100644 index 00000000000..1715d6ed32e --- /dev/null +++ b/quest/m3/nvenc-av1.md @@ -0,0 +1,31 @@ +# [M] NVENC AV1 encoding + +## Goal + +The NVENC backend encodes AV1 where the queried NVIDIA device and driver +support it, with OBU framing and an accurate catalog configuration through +transcode, and refuses it elsewhere. + +## Plan + +Split from the Main10 quest in the 2026-09-30 audit. It sits in m3 because it +is hardware-gated: AV1 NVENC needs an Ada GPU, and the only GPU CI host is an +RTX 3070 Ti. An Ada GPU on a CI host, or a consumer asking for AV1 encode, +brings it back. + +Query the capability at construction and refuse without it. Use existing +extensible codec enums; keep the NVIDIA backend optional and loaded at +runtime. Validate decoded pixels, profile, framing, drain, and refusal on +unsupported devices. Lack of suitable hardware leaves this unverified, not +complete. + +Public API: additive. Wire: existing AV1 codec signaling. + +## Required + +- Ada or newer NVIDIA GPU available for verification + +## Related + +- [Main10](/quest/m2/2147-moq-video-10-bit-hevc-and-av1-support-in-the-nvidia-codec.md) - the other half of #2147 +- [GPU CI](/quest/m1/gpu-ci.md) - the current runner lacks AV1 NVENC diff --git a/quest/m2/obs-linux-gpu.md b/quest/m3/obs-linux-gpu.md similarity index 93% rename from quest/m2/obs-linux-gpu.md rename to quest/m3/obs-linux-gpu.md index 7d29c34ec7f..2af3bc1b293 100644 --- a/quest/m2/obs-linux-gpu.md +++ b/quest/m3/obs-linux-gpu.md @@ -6,6 +6,9 @@ A supported Linux OBS graphics/encoder combination publishes composited video wi ## Plan +In m3 until the OBS encoder ships and a Linux user reports CPU readback as +the bottleneck. + - Start with an API feasibility probe. OBS exposes DMA-BUF import in `graphics.h`; that is not proof its compositor textures can be exported. Determine whether EGL/GL allocation export is available, or whether an upstream OBS hook or an encoder-owned exportable render target is required. - moq-video encodes a `Surface::DmaBuf` on VAAPI without a download, and scales one through VPP (moq-vaapi 0.1.0). This quest still has to turn an OBS compositor texture into a DMA-BUF that import accepts. - Negotiate DRM device, fourcc, plane offsets/strides, modifiers, and synchronization. Reuse `Surface::DmaBuf` and the hardware encoder's real import path, retaining allocation ownership until completion. A borrowed fd or an importable packed RGB texture does not prove the encoder accepts NV12 on the same device. @@ -19,5 +22,5 @@ A supported Linux OBS graphics/encoder combination publishes composited video wi ## Related -- [VAAPI encode and decode](/quest/m4/video-vaapi.md) - H.265 and checked-in bindings. The DMA-BUF encoder import this quest needs is already on main (moq-vaapi 0.1.0). - [Video hardware validation](/quest/m3/video-hardware.md) - native input and encoder acceptance need hardware evidence +- [VAAPI encode and decode](/quest/m2/video-vaapi.md) - H.265 and checked-in bindings. The DMA-BUF encoder import this quest needs is already on main (moq-vaapi 0.1.0). diff --git a/quest/m3/pipewire-camera-hardware.md b/quest/m3/pipewire-camera-hardware.md deleted file mode 100644 index 29ac05026d6..00000000000 --- a/quest/m3/pipewire-camera-hardware.md +++ /dev/null @@ -1,23 +0,0 @@ -# [S] Validate PipeWire cameras on a portal and a Pi - -## Goal - -The xdg-desktop-portal Camera path and a Raspberry Pi CSI camera each capture frames through the PipeWire camera that already shipped, or this quest records what stopped the pass. There is no new capture API. - -## Plan - -Open `pipewire` and one `pipewire:` in a sandbox, where the portal raises its permission dialog, and on a Pi whose CSI camera is a PipeWire node (spa-libcamera). Record the mode that opened, whether frames arrived, and whether the producer used one memory block or one per plane. - -Fix only a defect the pass hits. A separate-plane producer belongs to the multi-plane quest. If that is why a Pi produces nothing, write that down and stop. `doc/lib/rs/moq-video.md` says both paths are reachable. If a path cannot capture, correct that sentence in the same change. - -A libcamera source stays out. Embedded video already leaves `rpicam-vid` to the application. This pass uses the PipeWire camera only. - -## Required - -- A sandbox that can show the camera portal dialog, and a Raspberry Pi whose CSI camera appears as a PipeWire node - -## Related - -- [Capture multi-plane PipeWire cameras](/quest/m2/pipewire-camera-planes.md) - separate-plane I420 and NV12, when the pass finds them -- [Video hardware validation](/quest/m3/video-hardware.md) - the other encode and capture runs that still need a machine -- [Embedded video path](/quest/m3/video-embedded.md) - presenting on a Pi, which is a different gap diff --git a/quest/m3/processor-vision.md b/quest/m3/processor-vision.md deleted file mode 100644 index 672181a336c..00000000000 --- a/quest/m3/processor-vision.md +++ /dev/null @@ -1,43 +0,0 @@ -# [L] Reference vision worker - -## Goal - -A documented customer-run worker connects to a relay with an external processor -credential, subscribes to a low-resolution video rendition only when demanded, -runs object detection, and publishes frame-correlated bounding boxes as a Hang -contribution. The selected rendition is carried by the source broadcast rather -than referenced from another broadcast. A browser renders the boxes over -uninterrupted source video. - -## Plan - -Build the reference in an integration repository or in-tree example, not as a -hosted moq.pro (downstream) runtime. Keep the model replaceable and the output -contract plain: class, confidence, normalized bounds, source video rendition, -group sequence, and frame ordinal. The proof is about transport and lifecycle, -not model accuracy. - -Provide a five minute local path with a synthetic or recorded source and a -second path against a deployed relay with a real publisher. Demonstrate no -source subscription before output demand, requested rendition selection, -bounded latest-frame processing, clean demand teardown, reconnect, two -interchangeable workers on one logical contribution, token rotation, -revocation, and source withdrawal. Use the processor media contract's source -relation and the current net first-hop identity rules for failover and -reconnect; do not introduce a separate epoch field. Republish at the same -source path with a new source identity and prove stale inference output cannot -attach to the new source. Slow inference must drop stale work rather than -build latency. A fixture with a cross-broadcast rendition reference fails as -unsupported without subscribing to its target. Define refusal of an -unverifiable source relation in the shared contract before implementing it -here, and keep ordinary source playback independent of that refusal. - -Publish deployment examples for a local process and one generic container -platform, without tying anything in-tree to either. Record CPU/GPU and traffic -measurements so a customer can size its own worker. - -## Required - -- [Processor media contract](/quest/m1/processor/media-contract.md) - supplies - the contribution and source-relation schema the example worker must publish -- moq.pro processor registration exists (downstream, external condition) diff --git a/quest/m2/quic-gcc.md b/quest/m3/quic-gcc.md similarity index 82% rename from quest/m2/quic-gcc.md rename to quest/m3/quic-gcc.md index be4ba72d15f..268726aa01a 100644 --- a/quest/m2/quic-gcc.md +++ b/quest/m3/quic-gcc.md @@ -26,7 +26,12 @@ than loopback. State the experiment's boundary beside the result: netem cannot establish behavior against production cross traffic or real wifi and cellular loss. +Receive timestamps are native-only: browsers never negotiate the extension, +so GCC can only target native peers or relay-to-relay sessions, not browser +egress. Decided in the 2026-09-30 audit: parked in m3 until such a consumer +exists. + ## Required -- [Receive timestamps](/quest/m2/quic-receive-ts.md) - the per-packet +- [Receive timestamps](/quest/m3/quic-receive-ts.md) - the per-packet arrival times the delay filter runs on diff --git a/quest/m2/quic-receive-ts.md b/quest/m3/quic-receive-ts.md similarity index 73% rename from quest/m2/quic-receive-ts.md rename to quest/m3/quic-receive-ts.md index d36d4c299dd..ad94b72070e 100644 --- a/quest/m2/quic-receive-ts.md +++ b/quest/m3/quic-receive-ts.md @@ -17,7 +17,7 @@ written reason it does not pay. `Controller` that hands each acknowledged packet its receive instant. Both ends are ours; browsers never see it. - Compare the forward delay it measures against the half-RTT estimate the - [deadline quest](/quest/m1/quic/deadline.md) starts with, on the impaired + [deadline quest](/quest/m2/quic-deadline.md) starts with, on the impaired path profile with asymmetric delay. Report how often the half-RTT estimate would have kept a hopeless retransmission or reset a deliverable one. - Measure the ACK overhead the timestamps add on a fanout-shaped relay egress, @@ -26,7 +26,15 @@ written reason it does not pay. The GCC experiment requires this; a delay-based controller without per-packet arrival times is a different, weaker experiment. +Both ends must be ours, so this is native-only and serves native peers or +relay-to-relay sessions. Decided in the 2026-09-30 audit: parked in m3 with +GCC until such a consumer exists. + +## Required + +- A native-to-native consumer of receive timestamps (browsers never see them) + ## Related -- [QUIC GCC](/quest/m2/quic-gcc.md) - the controller that consumes it -- [Per-stream deadlines](/quest/m1/quic/deadline.md) - the other consumer +- [QUIC GCC](/quest/m3/quic-gcc.md) - the controller that consumes it +- [Per-stream deadlines](/quest/m2/quic-deadline.md) - the other consumer diff --git a/quest/m2/routing-cost-domains.md b/quest/m3/routing-cost-domains.md similarity index 93% rename from quest/m2/routing-cost-domains.md rename to quest/m3/routing-cost-domains.md index 58e0ab5f1f8..a21210a6871 100644 --- a/quest/m2/routing-cost-domains.md +++ b/quest/m3/routing-cost-domains.md @@ -4,7 +4,7 @@ Settle how independently operated MoQ networks exchange reachability without adding incomparable costs, at the cluster boundaries where -[Cluster routing](/quest/m1/cluster-routing.md) keeps path vector with cluster +[Cluster routing](/quest/m1/cluster-routing/README.md) keeps path vector with cluster ids as hops. Cost inside one cluster is cluster-routing's. Produce a reviewed design and scoped implementation quests, not a protocol implementation. Cloudflare, moq.pro, and self-hosted relays can retain their @@ -54,9 +54,11 @@ a second peer-policy mechanism. Completion is a documented decision, worked counterexamples or model checks, and independently completable follow-up quests. Open wire/API choices belong to this design exercise. +## Required + +- [Cluster routing](/quest/m1/cluster-routing/README.md) - this designs on its inter-cluster path vector + ## Related -- [Cluster routing](/quest/m1/cluster-routing.md) - in-cluster topology and - cost; this designs only what crosses its boundaries - [#3769](https://github.com/moq-dev/moq/pull/3769) - measurement-based pricing prompted the separation of measurement, operator policy, and protocol diff --git a/quest/m2/teleop/browser-package.md b/quest/m3/teleop-browser-package.md similarity index 93% rename from quest/m2/teleop/browser-package.md rename to quest/m3/teleop-browser-package.md index 56e4c29449d..ec5319449bf 100644 --- a/quest/m2/teleop/browser-package.md +++ b/quest/m3/teleop-browser-package.md @@ -7,6 +7,8 @@ and delivery classes rather than reimplementing them. ## Plan +Parked in m3 until a real ArduPilot user or partner asks (2026-09-30 audit). + Follow the existing split: `net`, `hang`, `json` and `auth` each have a Rust crate and a TypeScript package, with zod schemas mirroring the Rust types. There is no `@moq/mux`, so the catalog extension goes through the same seam diff --git a/quest/m2/teleop/mavlink.md b/quest/m3/teleop-mavlink.md similarity index 97% rename from quest/m2/teleop/mavlink.md rename to quest/m3/teleop-mavlink.md index aa50bb5853b..ce96f5034a4 100644 --- a/quest/m2/teleop/mavlink.md +++ b/quest/m3/teleop-mavlink.md @@ -8,6 +8,8 @@ and MAVProxy connect unchanged. ## Plan +Parked in m3 until a real ArduPilot user or partner asks (2026-09-30 audit). + ### Shape A library crate reached through `moq-cli`, the way `moq-srt` and `moq-rtmp` diff --git a/quest/m2/teleop/proof.md b/quest/m3/teleop-proof.md similarity index 82% rename from quest/m2/teleop/proof.md rename to quest/m3/teleop-proof.md index cf45e914415..82a903937da 100644 --- a/quest/m2/teleop/proof.md +++ b/quest/m3/teleop-proof.md @@ -8,6 +8,8 @@ five minutes. ## Plan +Parked in m3 until a real ArduPilot user or partner asks (2026-09-30 audit). + The browser client subscribes video and telemetry and publishes control, the shape Blue Robotics' Cockpit proves is viable. It is the demo and the end-to-end proof of the primitive, not a bid to out-feature QGroundControl: @@ -23,5 +25,5 @@ the maintenance. ## Required -- [MAVLink bridge](/quest/m2/teleop/mavlink.md) -- [Browser teleoperation package](/quest/m2/teleop/browser-package.md) +- [MAVLink bridge](/quest/m3/teleop-mavlink.md) +- [Browser teleoperation package](/quest/m3/teleop-browser-package.md) diff --git a/quest/m2/unity.md b/quest/m3/unity.md similarity index 89% rename from quest/m2/unity.md rename to quest/m3/unity.md index d2acb94f081..3c3e42cd7c4 100644 --- a/quest/m2/unity.md +++ b/quest/m3/unity.md @@ -10,6 +10,8 @@ target, subscribes to a broadcast, and plays decoded audio through an ## Plan +In m3 with the C# line; a Unity consumer asking brings both back. + - IL2CPP forbids dynamic callback marshaling: every reverse P/Invoke needs a static method with `[MonoPInvokeCallback]`. Audit what the generated `cs/ffi` emits for callback interfaces and futures, and whether the generator needs @@ -24,4 +26,4 @@ target, subscribes to a broadcast, and plays decoded audio through an ## Required -- [Package](/quest/m2/cs/package.md) - the NuGet whose contents Unity imports +- [Package](/quest/m3/cs/package.md) - the NuGet whose contents Unity imports diff --git a/quest/m2/unreal.md b/quest/m3/unreal.md similarity index 85% rename from quest/m2/unreal.md rename to quest/m3/unreal.md index 64b59128097..04df6f976a5 100644 --- a/quest/m2/unreal.md +++ b/quest/m3/unreal.md @@ -10,6 +10,8 @@ editor stability across a play-stop-play cycle. ## Plan +In m3 until an Unreal consumer asks; the C++ package it links already exists. + - Consume the release tarball through the module's `Build.cs` (`PublicAdditionalLibraries`, include paths); Unreal's build does not use vcpkg or CMake, which is why the tarball exists alongside the registries. @@ -25,4 +27,4 @@ editor stability across a play-stop-play cycle. ## Required -- [Package](/quest/m1/cpp/package.md) - the tarball the module links +- [C++ through moq-ffi](/quest/m1/cpp/README.md) - the package the module links landed on this line (#4187) and reaches main with it diff --git a/quest/m3/upstream-forks.md b/quest/m3/upstream-forks.md deleted file mode 100644 index 61debd6e692..00000000000 --- a/quest/m3/upstream-forks.md +++ /dev/null @@ -1,62 +0,0 @@ -# [S] Offer the uniffi generator fixes upstream - -## Goal - -Every general fix our uniffi generator forks carry has been offered to its -upstream, or recorded as declined or MoQ-specific, so each fork shrinks -toward a pin on an upstream tag. Very low priority: the forks work, and the -first step is someone else's review. Every external post, issue, or PR needs -the maintainer's approval at the time it is made. - -One outcome per candidate: - -- **uniffi-bindgen-cpp** (`kixelated/uniffi-bindgen-cpp`, forked from - LiveKit's `uniffi-0.31-async`, PR #1; - [#4100](https://github.com/moq-dev/moq/pull/4100)): the two leak fixes (a - ready Rust future freed without `rust_future_complete`, and a dropped - foreign future that never completed its oneshot), the missing - `#include ` MSVC needs, the uniffi 0.32 port, and - `error_style = "expected"`. The bug fixes are the easy offer; the 0.32 port - and the expected style depend on LiveKit taking async at all. -- **uniffi-dart** (`kixelated/uniffi-dart`; - [#4072](https://github.com/moq-dev/moq/pull/4072)): the - `nix/uniffi-dart-record-error.patch` and the RustBuffer release fixes. Fix - the latent `lowerForeignBytes` leak first (borrowed `&[u8]` arguments - allocate a `ForeignBytes` nothing frees; the free belongs after the call, - not inside the lowering), and audit callback interfaces for the same - RustBuffer leak, so the upstream offer is complete. `moq_ffi` uses neither - today. Also the enum `toString()` from an exported `Display` - (kixelated/uniffi-dart#6). -- **uniffi-bindgen-go** (`kixelated/uniffi-bindgen-go`): an enum error's - `Error()` from its exported `Display`, with the `DisplayError` fixture. - The uniffi 0.32 port is NordSecurity/uniffi-bindgen-go#96. -- **uniffi-rs Python typing** of data-carrying enum variants - ([#4049](https://github.com/moq-dev/moq/pull/4049)): the generated type - makes `moq.VideoEncoderKind.AUTO()` fail pyright, so - `doc/lib/py/index.md` carries a `pyright: ignore`. Fix it at the source - and drop the ignore once a release carries it. - -## Plan - -- Decided in #4100: fork tags keep upstream's `v+v` - scheme with a `-kixelated.N` pre-release, e.g. - `v0.11.0-kixelated.1+v0.32.2`, matching the Dart fork. It never collides - with an upstream tag. Under SemVer a pre-release sorts before its base, so - this only works because every pin names the exact tag; never let tooling - pick "the newest" fork tag (Codex on #4307). -- Offer each fix with the regression test it landed with. When upstream - merges one, move the pin in `flake.nix` (and the places its comment lists) - and delete the carried patch. -- Record each outcome (merged, declined with the reason, or not offered - because it is MoQ-specific) in the PR that finishes this quest. - -Public API: none. Wire: none. - -## Required - -- The maintainer approves offering the fixes upstream, per post, issue, or PR - -## Related - -- [Upstream the fork](/quest/m1/quic/upstream.md) - the same practice for the noq fork -- [C++ through moq-ffi](/quest/m1/cpp/README.md) - the line that forked the C++ generator diff --git a/quest/m3/video-hardware.md b/quest/m3/video-hardware.md index c8bf739fabd..d2f420a456d 100644 --- a/quest/m3/video-hardware.md +++ b/quest/m3/video-hardware.md @@ -1,4 +1,4 @@ -# [M] Video hardware validation +# [L] Video hardware validation ## Goal @@ -8,32 +8,76 @@ real hardware get run on it, and what breaks gets fixed. ## Plan Every item here is blocked on a physical machine rather than on code, which is -why they sit together and why they sit in m3. +why they sit together and why they sit in m3. Decided in the 2026-09-30 audit: +the KDE DMA-BUF capture and PipeWire camera validations fold in here, and the +V4L2 `VIDIOC_EXPBUF` source is dropped with the export itself (see +[#2819](/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md)). - **VAAPI low-power entrypoint and a second GPU.** H.264 encode, DMA-BUF input, and VPP resize ran on Intel Meteor Lake with iHD (moq-vaapi 0.1.0). Still unrun: the low-power encode entrypoint, which that device does not expose, and `MOQ_VAAPI_DEVICE` naming a node other than the first render node. -- **VAAPI input from V4L2 `VIDIOC_EXPBUF`.** DMA-BUF encode ran from a VA-API - decode and from PipeWire. A V4L2 export has not been the source. - **Windows Media Foundation capture**: on-demand open and close, so the camera LED is off when nobody is watching, and NV12 delivery from MJPEG and YUY2 cameras. - **A live camera run per platform**: capture needs device permission that a headless or agent process cannot grant itself. -Precedent for what this catches: NVENC validation on an RTX 3070 Ti found that -NVENC rejects stream-ordered pool memory, so buffers registered with it must -come from plain `cuMemAlloc`. That is not a bug any amount of review finds. +### PipeWire DMA-BUF capture on KDE + +Tracked in [#2893](https://github.com/moq-dev/moq/issues/2893). On a +KDE/Wayland desktop the portal source was selected, but the ignored +`portal_captures_frames` test never received a frame and timed out at 120 +seconds: + +```sh +cargo nextest run --profile ci -p moq-video --all-features --run-ignored ignored-only portal_captures_frames --no-capture +``` + +- Reproduce the post-selection timeout, then add tracing around portal + completion, PipeWire connection, format fixation, buffer allocation, and + first-frame delivery to locate the stall. +- A DMA-BUF-capable compositor produces `Surface::DmaBuf`; confirm the linear + DMA-BUF CPU fallback and shared-memory capture still work when DMA-BUF is + unavailable. +- Refine the ignored test so this failure is distinguishable from a + portal-selection timeout. + +### PipeWire cameras on a portal and a Pi + +Open `pipewire` and one `pipewire:` in a sandbox, where the portal +raises its permission dialog, and on a Raspberry Pi whose CSI camera is a +PipeWire node (spa-libcamera). Record the mode that opened, whether frames +arrived, and whether the producer used one memory block or one per plane. +No new capture API, and no libcamera source. + +A separate-plane producer belongs to +[multi-plane cameras](/quest/m2/pipewire-camera-planes.md); if that is why a +Pi produces nothing, write it down and stop. `doc/lib/rs/moq-video.md` says +both paths are reachable; correct that sentence if one cannot capture. + +### Fixes + +Fix only a defect a run hits. Precedent for what this catches: NVENC +validation on an RTX 3070 Ti found that NVENC rejects stream-ordered pool +memory, so buffers registered with it must come from plain `cuMemAlloc`. That +is not a bug any amount of review finds. ## Required - Someone with the hardware runs it: an Intel GPU exposing the VAAPI low-power - entrypoint, a second render node, a V4L2 capture device with DMA-BUF export, - a Windows machine with MJPEG and YUY2 cameras, and a live camera per platform + entrypoint, a second render node, a Windows machine with MJPEG and YUY2 + cameras, a live camera per platform, a KDE/Wayland desktop with an Intel or + AMD GPU, a sandbox that can show the camera portal dialog, and a Raspberry + Pi whose CSI camera appears as a PipeWire node + +## Closes + +- [#2893](https://github.com/moq-dev/moq/issues/2893) - close this issue when the quest finishes ## Related -- [Validate PipeWire cameras on a portal and a Pi](/quest/m3/pipewire-camera-hardware.md) - the camera portal and a Pi CSI node, which are a different machine from this list -- [PipeWire DMA-BUF on KDE](/quest/m3/2893-video-validate-pipewire-dma-buf-capture-on-kde-hardware.md) - the same kind of gate, for screen capture +- [#2819](/quest/m2/2819-moq-video-carry-pipewire-dma-bufs-safely-into-the-vulkan.md) - the DMA-BUF import validation this capture feeds +- [Capture multi-plane PipeWire cameras](/quest/m2/pipewire-camera-planes.md) - separate-plane I420 and NV12, when the Pi pass finds them +- [Embedded video path](/quest/m3/video-embedded.md) - presenting on a Pi, which is a different gap diff --git a/quest/m2/watch-data-sync.md b/quest/m3/watch-data-sync.md similarity index 71% rename from quest/m2/watch-data-sync.md rename to quest/m3/watch-data-sync.md index a8afced6e0d..16a287344c3 100644 --- a/quest/m2/watch-data-sync.md +++ b/quest/m3/watch-data-sync.md @@ -16,9 +16,10 @@ releases it. `delay` and `jitter` with `Sync` like a media rendition. - Snapshot tracks release the newest value at or before the playhead; stream tracks release every record in order. -- Take this up when an application needs synchronized data playback; until - then, a raw consumer reads payloads as they arrive. +- In m3 until an application needs synchronized data playback, such as + teleop telemetry beside video; until then, a raw consumer reads payloads as + they arrive. -## Related +## Required -- [Cross-track correlation](/quest/m2/teleop/correlation.md) - joins recordings on the broadcast clock rather than live playout +- [Data track clock](/quest/m1/data-track-clock.md) - data timestamps share the media clock mapping, so the playhead can release them diff --git a/quest/m2/whep-abr.md b/quest/m3/whep-abr.md similarity index 77% rename from quest/m2/whep-abr.md rename to quest/m3/whep-abr.md index af2367d95aa..b91c396e618 100644 --- a/quest/m2/whep-abr.md +++ b/quest/m3/whep-abr.md @@ -8,9 +8,16 @@ over MoQ, so a weak link gets SD instead of stalling on HD. ## Plan +In m3 until a WHEP viewer needs adaptive quality; MoQ viewers already switch +renditions, and a WHEP viewer gets the best rendition today. + Open questions: whether to drive switching from str0m's bandwidth estimate (TWCC) or from loss and REMB, how to switch without a keyframe gap (subscribe the new rendition and splice at its next group, as the JS decoder does), and whether offering the renditions as WebRTC simulcast layers (RIDs) buys anything for a receive-only browser. Keep the best rendition (`hang::catalog::Video::ranked`) as the starting rendition. + +## Required + +- A WHEP viewer that needs rendition switching diff --git a/quest/m4/README.md b/quest/m4/README.md index 2dbf68dde3d..5ef8cbfb662 100644 --- a/quest/m4/README.md +++ b/quest/m4/README.md @@ -7,13 +7,9 @@ so it is not forgotten. ## Plan -Each quest states its gate as a plain-text `Required` bullet. Re-check the -gates periodically; when one clears, remove the bullet and promote the quest to -the milestone its priority belongs in. +Each quest states its gate as a plain-text `Required` bullet, re-checked as the +root [questline](/quest/README.md) describes. ## Required -- [VAAPI encode and decode](/quest/m4/video-vaapi.md) - H.265 encode and decode, and pre-generated bindings that remove the libclang build dependency, gated on a moq-dev/vaapi release -- [Pool VAAPI resize surfaces](/quest/m4/vaapi-resize-pool.md) - a resize reuses one output surface per size once moq-vaapi ships that pool - [Safari WebTransport](/quest/m4/safari-webtransport.md) - WebKit browsers return to WebTransport once WebKit 319818 ships fixed -- [MSFTS convergence](/quest/m4/msfts-convergence.md) - the demultiplexed TS lane maps onto MSFTS ES-level carriage once msfts#33 settles the payload unit diff --git a/quest/m4/msfts-convergence.md b/quest/m4/msfts-convergence.md deleted file mode 100644 index fb344dd510d..00000000000 --- a/quest/m4/msfts-convergence.md +++ /dev/null @@ -1,22 +0,0 @@ -# [M] MPEG-TS lane converges with MSFTS ES-level carriage - -## Goal - -A subscriber author can map this repository's demultiplexed TS lane -(access units, Hang catalog `mpegts` section) onto MSFTS ES-level carriage -without guessing. #3731 settled four of six divergences (scope, group -alignment as a SHOULD, mux rate, egress timing); the payload unit (access units -versus filtered 188-octet packets) is MSFTS's call at msfts#33, and SI -repetition is now per `table_id` here versus a subscriber obligation there. -Transporting TS verbatim is a non-goal. - -## Plan - -Once msfts#33 settles, re-read the draft and decide what converges: a -published mapping from the `mpegts` catalog section to the `m2ts` fields, or a -change on either side. Update `drafts/draft-lcurley-moq-mpegts.md` and -`doc/concept` with whatever lands. - -## Required - -- msfts#33 (https://github.com/mondain/msfts/issues/33) settles the ES-level payload unit diff --git a/quest/m4/safari-webtransport.md b/quest/m4/safari-webtransport.md index df16c0f41eb..85b3a454a0f 100644 --- a/quest/m4/safari-webtransport.md +++ b/quest/m4/safari-webtransport.md @@ -13,7 +13,7 @@ this. - Name the exact Safari and iOS or iPadOS releases that ship the fix in the quest and in the `browser.ts` comment, then gate on them for Safari and for the iOS WebKit browsers, keeping older versions on the fallback. As of - 2026-09-08 the bug is still NEW with no fix released. + 2026-09-30 the bug is still NEW with no fix released. - Before flipping, rerun the raw WebTransport reproduction from #2388 (about 7,600 eleven-byte unidirectional streams, and about 16 MiB of data) on the fixed Safari, then a watch longer than two minutes in the QA harness on diff --git a/quest/m4/vaapi-resize-pool.md b/quest/m4/vaapi-resize-pool.md deleted file mode 100644 index 6041e66901f..00000000000 --- a/quest/m4/vaapi-resize-pool.md +++ /dev/null @@ -1,19 +0,0 @@ -# [S] Pool VAAPI resize surfaces - -## Goal - -A VAAPI resize reuses one output surface per destination size instead of allocating one per frame. `Surface::resize` stays the same call. The decoder pool is unchanged. - -## Plan - -`Processor` in moq-vaapi allocates the blit output with `ExportedFrame::from_surface` on every resize. Keep one surface per output size. When the exported frame drops, that surface returns and the next blit of the same size uses it. A frame the consumer still holds is not overwritten; the processor allocates another. The pool keeps one free surface per size and destroys any surface returned past that, so a burst of released frames cannot park them all. That is the decoder pool's rule, applied to resize outputs. - -moq-video already blits through `Processor` and exports the result. The reuse test belongs in moq-vaapi. Here, bump the workspace requirement and confirm a resize still returns an NV12 DMA-BUF. - -## Required - -- A `moq-vaapi` release whose `Processor` reuses one output surface per destination size and destroys free surfaces past one per size - -## Related - -- [VAAPI encode and decode](/quest/m4/video-vaapi.md) - H.265 and checked-in bindings, the other moq-vaapi gate From cead1bd306e901b885c905d127d4a0b944b1ea8e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 07:26:57 -0700 Subject: [PATCH 102/128] quest(m1): drop the retired TS import shared shift (#4583) Co-authored-by: Space Bunny Free --- quest/m1/README.md | 1 - quest/m1/ts-import-shared-shift.md | 46 ------------------------------ 2 files changed, 47 deletions(-) delete mode 100644 quest/m1/ts-import-shared-shift.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 5be428fc5a8..b560c4d5831 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -46,7 +46,6 @@ QUIC studies there on that rule. - [Catalog estimate rate](/quest/m1/catalog-estimate-rate.md) - a rising `jitter`/`delay` estimate republishes the catalog at most once a second, in js/publish and moq-mux - [Legacy end overshoot](/quest/m1/legacy-end-overshoot.md) - browser playback survives a group that starts inside the previous group's estimated end - [Wire compatibility](/quest/m1/wire-compat.md) - a nightly run tests this checkout against the last published release for tokens, session wire, and catalog/container -- [TS import shared shift](/quest/m1/ts-import-shared-shift.md) - unflagged loop wraps move audio and video by one shift, so A/V sync holds across wraps - [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) - `import ts` reads a PAT or PMT that spans packets or follows a nonzero pointer_field instead of aborting, and one corrupted section costs a repetition and a counted `CRC_error`, not the import - [RTMP interleaving](/quest/m1/rtmp-interleaving.md) - isolate partial messages before optimizing assembly copies - [TS stats module](/quest/m1/ts-stats-module.md) - on dev, the TS stats types move under `ts::stats` as `Snapshot` and `Stream`, with an owned `track` diff --git a/quest/m1/ts-import-shared-shift.md b/quest/m1/ts-import-shared-shift.md deleted file mode 100644 index acdf5972497..00000000000 --- a/quest/m1/ts-import-shared-shift.md +++ /dev/null @@ -1,46 +0,0 @@ -# [S] moq import ts: one re-anchor shift per program - -## Goal - -An unflagged loop wrap in `moq import ts` moves audio and video forward by the -same amount, so A/V sync holds across any number of wraps. Today each -elementary stream owns a `Reanchor` and grows its shift to reach its own live -edge ([#3997](https://github.com/moq-dev/moq/pull/3997)). Audio and video -edges sit on their own last frame starts, so each wrap drifts A/V by the -difference in frame durations: about 12 ms at 30 fps with 48 kHz AAC, or -1.7 s a day on a 10-minute loop. - -## Plan - -Decided: a program-level shared shift in `rs/moq-mux/src/container/ts/import.rs`. -Every stream of a program applies the same shift, grown once per wrap by the -largest amount any stream needs to clear its edge, which preserves the source's -inter-stream offsets. A timebase break (PCR discontinuity) clears it for the -whole program, as it already does per stream. - -Guidance: - -- The shift must be known before any stream emits a frame of the new - generation (Codex on #4307): a first stream that grows only enough for - itself leaves a later-arriving stream below its edge, and growing again - then drifts the two. Decided: hold each stream's post-wrap frames until - every live stream of the program has shown its new PTS, then take the - maximum growth once. -- The hold needs its own bound: #3489 adds per-PID counters, not a timeout, - and the catalog `stalled` bit (`Stream::tick`, #3630) covers video only and - runs on the catalog's timer. Decided: bound the hold on the program clock - (PCR advance since the first stream's new generation, not wall time), and - commit the shift over the streams seen so far when it expires. A stream - that returns later applies the committed shift, clamped to its edge as - below. The `Anchor`/`Lane` split behind `live()` in `moq_mux::clock` solves - a similar problem for restarts, but the remove-live quest deletes it, so - copy what helps rather than depending on it. -- A stream whose own edge is still above the shifted timestamp after the - shared growth (its tail ran longer) is the case that forces growing by the - maximum. Landing on its edge is accepted today; keep that trade-off. -- Sections already take the video shift, so cues keep following pictures. - MPEG-2 video (`Stream::Clock`) has no track and so no edge, but it should - read the shared shift too. -- Tests beside the existing loop-wrap tests: a muxed H.264 + AAC loop whose - period is not a multiple of either frame duration keeps the first audio and - video timestamps of each pass at the source offset across three wraps. From a42a56dd8b93e5248c1e8750654f6d4a5a782382 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 08:17:09 -0700 Subject: [PATCH 103/128] feat(lite): moq-lite-07 switches to 64-bit leading-ones varints (#4455) Co-authored-by: Claude Opus 5.5 --- .github/workflows/nightly.yml | 6 + doc/concept/moq-lite.md | 5 +- drafts/draft-lcurley-moq-lite.md | 8 ++ js/net/bench/frames.ts | 5 +- js/net/bench/lite-varint.ts | 146 +++++++++++++++++++++++ js/net/bench/reader.ts | 3 +- js/net/bench/varint.ts | 2 +- js/net/src/connection/accept.ts | 4 +- js/net/src/connection/connect.ts | 2 +- js/net/src/ietf/adapter.ts | 8 +- js/net/src/ietf/ietf.test.ts | 6 +- js/net/src/ietf/object.ts | 19 ++- js/net/src/lite/announce.test.ts | 123 ++++++++++++++------ js/net/src/lite/announce.ts | 12 +- js/net/src/lite/connection.ts | 11 +- js/net/src/lite/datagram.test.ts | 26 +++-- js/net/src/lite/datagram.ts | 16 +-- js/net/src/lite/fetch.test.ts | 3 +- js/net/src/lite/goaway.test.ts | 3 +- js/net/src/lite/group.test.ts | 8 +- js/net/src/lite/message.ts | 3 +- js/net/src/lite/priority.test.ts | 3 +- js/net/src/lite/probe.test.ts | 9 +- js/net/src/lite/publisher.test.ts | 62 +++++----- js/net/src/lite/publisher.ts | 3 +- js/net/src/lite/setup.test.ts | 38 +++--- js/net/src/lite/setup.ts | 40 +++---- js/net/src/lite/subscribe.test.ts | 22 ++-- js/net/src/lite/subscriber.test.ts | 3 + js/net/src/lite/subscriber.ts | 14 +-- js/net/src/lite/tail.test.ts | 6 +- js/net/src/lite/track.test.ts | 26 ++++- js/net/src/stream.test.ts | 178 +++++++++++++++++++---------- js/net/src/stream.ts | 130 ++++++++++++++------- quest/m1/rs2ts/varint-codec.md | 7 +- rs/moq-net/Cargo.toml | 8 +- rs/moq-net/benches/varint.rs | 43 +++++++ rs/moq-net/src/coding/varint.rs | 126 ++++++++++++++++---- rs/moq-net/src/fuzz.rs | 131 ++++++++++++++++++++- rs/moq-net/src/lite/announce.rs | 25 ++-- rs/moq-net/src/lite/compress.rs | 4 +- rs/moq-net/src/lite/parameters.rs | 17 ++- rs/moq-net/src/lite/setup.rs | 43 +++++-- rs/moq-net/src/model/origin.rs | 5 +- rs/moq-net/src/test_interop.rs | 107 ++++++++++++++++- test/interop/README.md | 7 ++ test/interop/bare-fin.ts | 19 +-- test/interop/lite-varint.ts | 98 ++++++++++++++++ test/interop/varint.ts | 6 +- test/justfile | 3 +- 50 files changed, 1237 insertions(+), 365 deletions(-) create mode 100644 js/net/bench/lite-varint.ts create mode 100644 rs/moq-net/benches/varint.rs create mode 100644 test/interop/lite-varint.ts diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index 36731b7b5d3..4d8ee86658d 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -103,6 +103,12 @@ jobs: if: ${{ !cancelled() }} run: nix develop --command bun js/net/bench/varint.ts + # Bytes and time for lite-06 against lite-07 frames, groups, and requests. No + # threshold: it only has to keep running. + - name: JS lite varint benchmark + if: ${{ !cancelled() }} + run: nix develop --command bun js/net/bench/lite-varint.ts + # Fails if publishing a group costs more as the track retains more groups, # which means the latency guard or the cache went back to scanning them all. - name: JS track retention benchmark diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 393ee606482..e627c18f211 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -32,7 +32,10 @@ and newer, each side also sends a `SETUP` message with its capabilities. Rust and TypeScript speak moq-lite 01 through 06 and moq-transport drafts 14 through 22. Clients offer `moq-lite-06` first by default. moq-lite 07 is still in progress: it negotiates as `moq-lite-07-wip`, and only when both -sides explicitly enable it. +sides explicitly enable it. moq-lite 07 also switches every varint from QUIC's +two-bit length prefix to moq-transport's leading-ones form, so values up to 127 +take one byte instead of up to 63, and the range widens from 62 to 64 bits. Rust +still refuses lite-07 values above 2^62-1 until its `VarInt` widens. ## Subscription completion diff --git a/drafts/draft-lcurley-moq-lite.md b/drafts/draft-lcurley-moq-lite.md index b1537812392..38621fa966f 100644 --- a/drafts/draft-lcurley-moq-lite.md +++ b/drafts/draft-lcurley-moq-lite.md @@ -29,6 +29,7 @@ normative: date: false RFC3986: RFC6455: + RFC9000: RFC9002: informative: @@ -682,6 +683,12 @@ A group whose frame does not fit is simply not eligible for datagram delivery. # Encoding This section covers the encoding of each message. +## Variable-Length Integers {#varint} +A field marked `(i)` is a variable-length integer. +moq-lite-07 uses the leading-ones encoding of [moqt]: the number of leading 1 bits in the first byte gives the length, from 1 byte carrying 7 bits to 9 bytes carrying 64, and every length is valid. +Earlier versions use the two-bit length prefix of [RFC9000], Section 16, which carries at most 2^62-1. +A relay that cannot encode a value for a peer on an earlier version MUST NOT truncate it. + ## Message Length Most messages are prefixed with a variable-length integer indicating the number of bytes in the message payload that follows. This length field does not include the length of the varint length itself. @@ -1340,6 +1347,7 @@ The `Message Length` describes the payload size on the wire. ## moq-lite-07 - Assigned `moq-lite-07-wip` as this draft's protocol identifier until it is finalized as `moq-lite-07`. +- Switched every variable-length integer, including SETUP parameter values, from QUIC's two-bit length prefix to moq-transport's leading-ones encoding, widening the range to 64 bits. - Hid routes with a `.`-prefixed segment below the requested prefix from announce discovery, and added the ANNOUNCE_REQUEST `Hidden` field to opt in. - Added `Stream Count` to SUBSCRIBE_END: the number of Group Streams opened for the subscription. SUBSCRIBE_END is now sent once every counted Group Stream has opened, rather than as soon as the final group is known. - Removed SUBSCRIBE_DROP and its type 0x2; a group without a Group Stream is not counted. diff --git a/js/net/bench/frames.ts b/js/net/bench/frames.ts index 34752d52625..bff942ce72c 100644 --- a/js/net/bench/frames.ts +++ b/js/net/bench/frames.ts @@ -7,6 +7,7 @@ import { Subscribe, SubscribeOk } from "../src/ietf/subscribe.ts"; import { Subscriber as IetfSubscriber } from "../src/ietf/subscriber.ts"; import { ALPN, Version as IetfVersion } from "../src/ietf/version.ts"; import { readFrames } from "../src/lite/group.ts"; +import { Version as LiteVersion } from "../src/lite/version.ts"; import { createMockTransportPair } from "../src/mock.ts"; import * as Path from "../src/path.ts"; import { Reader, Stream } from "../src/stream.ts"; @@ -48,7 +49,9 @@ const lite: Protocol = { async subscribe() { const open: Open = (stream) => { const producer = new Producer(0); - const done = readFrames(new Reader(stream), producer, 1_000_000).then(() => producer.close()); + const done = readFrames(new Reader(stream, undefined, LiteVersion.DRAFT_06), producer, 1_000_000).then(() => + producer.close(), + ); return { group: Promise.resolve(producer.consume()), done }; }; return { open, close: () => {} }; diff --git a/js/net/bench/lite-varint.ts b/js/net/bench/lite-varint.ts new file mode 100644 index 00000000000..4338a448e55 --- /dev/null +++ b/js/net/bench/lite-varint.ts @@ -0,0 +1,146 @@ +/** Lite-07 leading-ones varints against lite-06 QUIC varints, for what a publisher writes per frame, group, and request. */ +import { randomHop } from "../src/hop.ts"; +import { Datagram } from "../src/lite/datagram.ts"; +import { Group } from "../src/lite/group.ts"; +import { ProbeLevel, Setup } from "../src/lite/setup.ts"; +import { Subscribe } from "../src/lite/subscribe.ts"; +import { Version } from "../src/lite/version.ts"; +import * as Path from "../src/path.ts"; +import { type Cursor, Reader, Writer } from "../src/stream.ts"; + +const versions = [Version.DRAFT_06, Version.DRAFT_07]; +const minMs = 200; // Run each case at least this long. +let checksum = 0; + +/** A lite object: how the publisher writes it and how the subscriber reads it back. */ +interface Sample { + name: string; + encode(w: Writer, version: Version): Promise; + decode(r: Reader, version: Version): Promise; +} + +// A FRAME header: the zigzag timestamp delta, then the size. +const header = (c: Cursor) => { + c.u62(); + return c.u53(); +}; + +// FRAME headers with the payloads left out, as (timestamp delta in µs, size) pairs. +function frames(name: string, headers: [bigint, number][]): Sample { + const zigzag = (d: bigint) => (d << 1n) ^ (d >> 63n); + return { + name, + async encode(w) { + for (const [delta, size] of headers) { + await w.u62(zigzag(delta)); + await w.u53(size); + } + }, + async decode(r) { + // The subscriber's read loop, one synchronous decode per buffered frame, minus the payload. + let n = 0; + while (r.tryDecode(header) !== undefined) n++; + return n; + }, + }; +} + +const video = frames( + "Video", + Array.from({ length: 60 }, (_, n): [bigint, number] => { + if (n === 0) return [0n, 60_000]; + return [33_333n, n % 10 === 0 ? 17_000 : 8_000]; + }), +); +const audio = frames( + "Audio", + Array.from({ length: 50 }, (_, n): [bigint, number] => [n === 0 ? 0n : 20_000n, 160]), +); + +const group: Sample = { + name: "Group", + encode: (w, version) => new Group({ subscribe: 3n, sequence: 1_234 }).encode(w, version), + decode: (r, version) => Group.decode(r, version), +}; + +const subscribe: Sample = { + name: "Subscribe", + encode: (w, version) => + new Subscribe({ + id: 3n, + broadcast: Path.from("room/alice"), + track: "video", + priority: 2, + maxAge: 10_000, + }).encode(w, version), + decode: (r, version) => Subscribe.decode(r, version), +}; + +const datagram: Sample = { + name: "Datagram", + encode: (w, version) => w.write(new Datagram(3n, 1_234, 1_234_567_890, new Uint8Array()).encode(version)), + decode: (r, version) => r.readAll().then((data) => Datagram.decode(data, version)), +}; + +const hop = randomHop(); +const setup: Sample = { + name: "Setup", + encode: (w, version) => new Setup({ probe: ProbeLevel.Report, hop }).encode(w, version), + decode: (r, version) => Setup.decode(r, version), +}; + +/** Collect what one encode writes. */ +async function wire(sample: Sample, version: Version): Promise { + const chunks: Uint8Array[] = []; + const w = new Writer(new WritableStream({ write: (c) => void chunks.push(c.slice()) }), version); + await sample.encode(w, version); + w.close(); + await w.closed; + const out = new Uint8Array(chunks.reduce((n, c) => n + c.byteLength, 0)); + let offset = 0; + for (const c of chunks) { + out.set(c, offset); + offset += c.byteLength; + } + return out; +} + +/** Time `f` until `minMs` has passed, returning ns per call. */ +async function time(f: () => Promise): Promise { + for (let i = 0; i < 1_000; i++) await f(); // warm up + let calls = 0; + const start = performance.now(); + let elapsed = 0; + while (elapsed < minMs) { + for (let i = 0; i < 1_000; i++) await f(); + calls += 1_000; + elapsed = performance.now() - start; + } + return (elapsed * 1e6) / calls; +} + +// A Writer whose sink discards, so encode is timed without collecting bytes. +const sink = () => + new WritableStream({ + write: (c) => { + checksum += c.byteLength; + }, + }); + +console.log("sample,version,bytes,encode_ns,decode_ns"); +for (const sample of [video, audio, group, subscribe, datagram, setup]) { + for (const version of versions) { + const bytes = await wire(sample, version); + const encode = await time(async () => { + const w = new Writer(sink(), version); + await sample.encode(w, version); + }); + const decode = await time(async () => { + checksum += Number((await sample.decode(new Reader(undefined, bytes, version), version)) !== undefined); + }); + console.log( + `${sample.name},${version.toString(16)},${bytes.byteLength},${encode.toFixed(0)},${decode.toFixed(0)}`, + ); + } +} +if (checksum === 0) throw new Error("benchmark did no work"); diff --git a/js/net/bench/reader.ts b/js/net/bench/reader.ts index 76eac2e4c99..acdede13c64 100644 --- a/js/net/bench/reader.ts +++ b/js/net/bench/reader.ts @@ -1,4 +1,5 @@ /** Sweep frame size and chunk size for one Reader.read of a fragmented frame. */ +import { Version } from "../src/lite/version.ts"; import { Reader } from "../src/stream.ts"; const frameSizes = [16 * 1024, 256 * 1024, 1024 * 1024]; @@ -31,7 +32,7 @@ for (const frameSize of frameSizes) { controller.close(); }, }); - const reader = new Reader(stream); + const reader = new Reader(stream, undefined, Version.DRAFT_06); const start = performance.now(); const read = await reader.read(frameSize); diff --git a/js/net/bench/varint.ts b/js/net/bench/varint.ts index d8322a1c1e7..1cc8812e852 100644 --- a/js/net/bench/varint.ts +++ b/js/net/bench/varint.ts @@ -15,7 +15,7 @@ let checksum = 0; const formats = [ { name: "quic", - version: undefined, + version: Version.DRAFT_16, encode: Varint.encodeTo, values: [2 ** 6 - 1, 2 ** 14 - 1, 2 ** 30 - 1, Number.MAX_SAFE_INTEGER], }, diff --git a/js/net/src/connection/accept.ts b/js/net/src/connection/accept.ts index d0f4f2c2977..86a9ac33ad3 100644 --- a/js/net/src/connection/accept.ts +++ b/js/net/src/connection/accept.ts @@ -142,7 +142,7 @@ async function acceptSetup( wiring: SessionProps, ): Promise { // Accept bidi, read ClientSetup, write ServerSetup - const stream = await Stream.accept(transport); + const stream = await Stream.accept(transport, version); if (!stream) throw new Error("no incoming bidi stream for SETUP"); const clientCompat = await stream.reader.u53(); @@ -187,7 +187,7 @@ async function acceptNegotiated( ): Promise { const setupVersion = Ietf.Version.DRAFT_14; - const stream = await Stream.accept(transport); + const stream = await Stream.accept(transport, setupVersion); if (!stream) throw new Error("no incoming bidi stream for SETUP"); const clientCompat = await stream.reader.u53(); diff --git a/js/net/src/connection/connect.ts b/js/net/src/connection/connect.ts index 759c3cceb0e..493b1016100 100644 --- a/js/net/src/connection/connect.ts +++ b/js/net/src/connection/connect.ts @@ -297,7 +297,7 @@ async function negotiate(url: URL, session: WebTransport, wiring: SessionProps): throw new Error(`unsupported WebTransport protocol: ${protocol}`); } - const stream = await Stream.open(session); + const stream = await Stream.open(session, { version: setupVersion }); await stream.writer.u53(Lite.StreamId.ClientCompat); const encoder = new TextEncoder(); diff --git a/js/net/src/ietf/adapter.ts b/js/net/src/ietf/adapter.ts index b51e48d8dac..780b6a1b39c 100644 --- a/js/net/src/ietf/adapter.ts +++ b/js/net/src/ietf/adapter.ts @@ -212,9 +212,7 @@ export class ControlStreamAdapter implements Session { }, }); - const stream = new Stream({ readable, writable: sendWritable }); - stream.reader.version = this.version; - stream.writer.version = this.version; + const stream = new Stream({ readable, writable: sendWritable, version: this.version }); return stream; } @@ -339,9 +337,7 @@ export class ControlStreamAdapter implements Session { const sendWritable = this.#createSendWritable(); - const stream = new Stream({ readable, writable: sendWritable }); - stream.reader.version = this.version; - stream.writer.version = this.version; + const stream = new Stream({ readable, writable: sendWritable, version: this.version }); this.#streams.set(requestId, { controller }); diff --git a/js/net/src/ietf/ietf.test.ts b/js/net/src/ietf/ietf.test.ts index ec6d906c20a..cfd7d29525d 100644 --- a/js/net/src/ietf/ietf.test.ts +++ b/js/net/src/ietf/ietf.test.ts @@ -1068,7 +1068,7 @@ test("TrackStatusRequest v17: round trip with requiredRequestIdDelta", async () // Helper to encode a namespace to raw bytes async function encodeNamespace(namespace: Path.Valid): Promise { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, Version.DRAFT_14); await Namespace.encode(writer, namespace); writer.close(); await writer.closed; @@ -1077,14 +1077,14 @@ async function encodeNamespace(namespace: Path.Valid): Promise { // Helper to decode a namespace from raw bytes async function decodeNamespace(bytes: Uint8Array): Promise { - const reader = new Reader(undefined, bytes); + const reader = new Reader(undefined, bytes, Version.DRAFT_14); return await Namespace.decode(reader); } // Helper to encode raw IETF namespace tuple fields async function encodeNamespaceTuple(parts: string[]): Promise { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, Version.DRAFT_14); await writer.u53(parts.length); for (const part of parts) await writer.string(part); writer.close(); diff --git a/js/net/src/ietf/object.ts b/js/net/src/ietf/object.ts index a5584da0334..9d6a63b883d 100644 --- a/js/net/src/ietf/object.ts +++ b/js/net/src/ietf/object.ts @@ -1,5 +1,5 @@ import { StreamCode, Stream as StreamError } from "../error.ts"; -import { type Cursor, type Reader, Writer } from "../stream.ts"; +import { asIetf, type Cursor, type Reader, Writer } from "../stream.ts"; import { Timescale, Timestamp } from "../time.ts"; import { type IetfVersion, Version } from "./version.ts"; @@ -47,12 +47,7 @@ function hasDeltaObjectPropertyTypes(version: IetfVersion | undefined): boolean } } -async function encodeObjectPropertyType( - w: Writer, - id: bigint, - prev: bigint, - version: IetfVersion | undefined, -): Promise { +async function encodeObjectPropertyType(w: Writer, id: bigint, prev: bigint, version: IetfVersion): Promise { const encoded = hasDeltaObjectPropertyTypes(version) ? id - prev : id; await w.u62(encoded); } @@ -65,7 +60,7 @@ async function encodeObjectTime( w: Writer, timestamp: Timestamp, timescale: Timescale, - version: IetfVersion | undefined, + version: IetfVersion, ): Promise { const value = Math.round((timestamp.value * timescale) / timestamp.scale); await encodeObjectPropertyType(w, PROP_TIMESTAMP, 0n, version); @@ -75,7 +70,7 @@ async function encodeObjectTime( async function encodeObjectExtensions( timestamp: Timestamp | undefined, timescale: Timescale, - version: IetfVersion | undefined, + version: IetfVersion, ): Promise { if (timestamp === undefined) { return new Uint8Array(); @@ -112,7 +107,7 @@ function decodeObjectTime(c: Cursor, timescale: Timescale): Timestamp | undefine while (c.remaining > 0) { const step = c.u62(); - const id = !hasDeltaObjectPropertyTypes(c.version) || first ? step : prevType + step; + const id = !hasDeltaObjectPropertyTypes(asIetf(c.version)) || first ? step : prevType + step; first = false; prevType = id; @@ -285,7 +280,7 @@ export class Frame { * `idDelta` is the first object's absolute Object ID and zero for every later one, so a * group whose head was trimmed by a filter still puts the true numbering on the wire. */ - async encode(w: Writer, flags: GroupFlags, timescale: Timescale, version = w.version, idDelta = 0): Promise { + async encode(w: Writer, flags: GroupFlags, timescale: Timescale, version: IetfVersion, idDelta = 0): Promise { await w.u53(idDelta); if (flags.hasExtensions) { @@ -398,7 +393,7 @@ export class FetchFrame { } /** Encode this object at `position`, stamping it in the track's timescale. */ - async encode(w: Writer, position: FetchPosition, timescale: Timescale, version = w.version): Promise { + async encode(w: Writer, position: FetchPosition, timescale: Timescale, version: IetfVersion): Promise { if (position.first) { // Include the priority too: "same as the prior object" has no prior to refer to. const properties = this.timestamp !== undefined ? FETCH_PROPERTIES : 0; diff --git a/js/net/src/lite/announce.test.ts b/js/net/src/lite/announce.test.ts index 69b34cb9e5a..86b212d308a 100644 --- a/js/net/src/lite/announce.test.ts +++ b/js/net/src/lite/announce.test.ts @@ -25,10 +25,11 @@ function concat(chunks: Uint8Array[]): Uint8Array { return out; } -async function bytes(f: (w: Writer) => Promise): Promise { +async function bytes(f: (w: Writer) => Promise, version: Version): Promise { const written: Uint8Array[] = []; const writer = new Writer( new WritableStream({ write: (chunk) => void written.push(new Uint8Array(chunk)) }), + version, ); await f(writer); writer.close(); @@ -37,7 +38,11 @@ async function bytes(f: (w: Writer) => Promise): Promise { } async function roundTrip(msg: AnnounceBroadcast, version: Version): Promise { - const reader = new Reader(undefined, await bytes((w) => encodeAnnounceBroadcast(w, msg, version))); + const reader = new Reader( + undefined, + await bytes((w) => encodeAnnounceBroadcast(w, msg, version), version), + version, + ); return decodeAnnounceBroadcast(reader, version); } @@ -74,8 +79,8 @@ test("AnnounceBroadcast skips an unknown type on draft-06", async () => { await w.u53(4); await w.u53(1); await w.u8(0); - }); - const reader = new Reader(undefined, encoded); + }, Version.DRAFT_06); + const reader = new Reader(undefined, encoded, Version.DRAFT_06); expect(await decodeAnnounceBroadcast(reader, Version.DRAFT_06)).toEqual({ status: "skipped" }); }); @@ -91,37 +96,49 @@ test("AnnounceBroadcast drops the route cost before draft-06", async () => { test("AnnounceBroadcast rejects cross-version forms", async () => { await expect( - bytes((w) => encodeAnnounceBroadcast(w, { status: "endedId", id: 1n }, Version.DRAFT_05)), + bytes((w) => encodeAnnounceBroadcast(w, { status: "endedId", id: 1n }, Version.DRAFT_05), Version.DRAFT_05), ).rejects.toThrow(); await expect( - bytes((w) => encodeAnnounceBroadcast(w, { status: "restart", id: 1n, hops: [] }, Version.DRAFT_05)), + bytes( + (w) => encodeAnnounceBroadcast(w, { status: "restart", id: 1n, hops: [] }, Version.DRAFT_05), + Version.DRAFT_05, + ), ).rejects.toThrow(); await expect( - bytes((w) => encodeAnnounceBroadcast(w, { status: "ended", suffix: Path.from("room/cam") }, Version.DRAFT_06)), + bytes( + (w) => encodeAnnounceBroadcast(w, { status: "ended", suffix: Path.from("room/cam") }, Version.DRAFT_06), + Version.DRAFT_06, + ), ).rejects.toThrow(); }); test("AnnounceBroadcast accepts explicit restart status on draft-05", async () => { - const wire = await bytes((w) => - encodeAnnounceBroadcast(w, { status: "active", suffix: Path.from("room/cam"), hops: [] }, Version.DRAFT_05), + const wire = await bytes( + (w) => + encodeAnnounceBroadcast(w, { status: "active", suffix: Path.from("room/cam"), hops: [] }, Version.DRAFT_05), + Version.DRAFT_05, ); wire[1] = 2; - const got = await decodeAnnounceBroadcast(new Reader(undefined, wire), Version.DRAFT_05); + const got = await decodeAnnounceBroadcast(new Reader(undefined, wire, Version.DRAFT_05), Version.DRAFT_05); expect(got).toEqual({ status: "active", suffix: Path.from("room/cam"), hops: [] }); }); test("AnnounceBroadcast rejects explicit restart status before draft-05", async () => { - const wire = await bytes((w) => - encodeAnnounceBroadcast(w, { status: "active", suffix: Path.from("room/cam"), hops: [] }, Version.DRAFT_04), + const wire = await bytes( + (w) => + encodeAnnounceBroadcast(w, { status: "active", suffix: Path.from("room/cam"), hops: [] }, Version.DRAFT_04), + Version.DRAFT_04, ); wire[1] = 2; - await expect(decodeAnnounceBroadcast(new Reader(undefined, wire), Version.DRAFT_04)).rejects.toThrow(); + await expect( + decodeAnnounceBroadcast(new Reader(undefined, wire, Version.DRAFT_04), Version.DRAFT_04), + ).rejects.toThrow(); }); async function requestRoundTrip(msg: AnnounceRequest, version: Version): Promise { - const reader = new Reader(undefined, await bytes((w) => msg.encode(w, version))); + const reader = new Reader(undefined, await bytes((w) => msg.encode(w, version), version), version); return AnnounceRequest.decode(reader, version); } @@ -139,8 +156,8 @@ test("AnnounceRequest drops excludeHop on draft-06", async () => { const got = await requestRoundTrip(msg, Version.DRAFT_06); expect(got.excludeHop).toBe(0n); - const with05 = await bytes((w) => msg.encode(w, Version.DRAFT_05)); - const with06 = await bytes((w) => msg.encode(w, Version.DRAFT_06)); + const with05 = await bytes((w) => msg.encode(w, Version.DRAFT_05), Version.DRAFT_05); + const with06 = await bytes((w) => msg.encode(w, Version.DRAFT_06), Version.DRAFT_06); expect(with06.byteLength).toBeLessThan(with05.byteLength); }); @@ -158,7 +175,11 @@ test("AnnounceRequest carries hidden from draft-07", async () => { // conforming publisher. test("AnnounceOk accepts the reserved unknown origin", async () => { const msg = new AnnounceOk(UNKNOWN_HOP, 3); - const reader = new Reader(undefined, await bytes((w) => msg.encode(w, Version.DRAFT_05))); + const reader = new Reader( + undefined, + await bytes((w) => msg.encode(w, Version.DRAFT_05), Version.DRAFT_05), + Version.DRAFT_05, + ); const got = await AnnounceOk.decode(reader, Version.DRAFT_05); expect(got.hop).toBe(UNKNOWN_HOP); expect(got.active).toBe(3); @@ -166,7 +187,11 @@ test("AnnounceOk accepts the reserved unknown origin", async () => { test("AnnounceOk round-trips a declared origin", async () => { const msg = new AnnounceOk(HopSchema.parse(42n), 1); - const reader = new Reader(undefined, await bytes((w) => msg.encode(w, Version.DRAFT_05))); + const reader = new Reader( + undefined, + await bytes((w) => msg.encode(w, Version.DRAFT_05), Version.DRAFT_05), + Version.DRAFT_05, + ); const got = await AnnounceOk.decode(reader, Version.DRAFT_05); expect(got.hop).toBe(HopSchema.parse(42n)); expect(got.active).toBe(1); @@ -179,7 +204,9 @@ test("a hop chain that revisits a hop is refused in both directions", async () = // Outbound: refused before it reaches the wire. A receiver must close the session over // a repeated Hop ID, so sending one costs someone else their session. - await expect(bytes((w) => encodeAnnounceBroadcast(w, looped, Version.DRAFT_06))).rejects.toThrow("appears twice"); + await expect(bytes((w) => encodeAnnounceBroadcast(w, looped, Version.DRAFT_06), Version.DRAFT_06)).rejects.toThrow( + "appears twice", + ); // Inbound: encode a chain that is legal, then rewrite its last hop to repeat the // first. Only a non-conforming sender produces these bytes, which is why they have to @@ -189,7 +216,7 @@ test("a hop chain that revisits a hop is refused in both directions", async () = suffix: Path.from("room"), hops: [four, eight, HopSchema.parse(9n)], }; - const forged = await bytes((w) => encodeAnnounceBroadcast(w, legal, Version.DRAFT_06)); + const forged = await bytes((w) => encodeAnnounceBroadcast(w, legal, Version.DRAFT_06), Version.DRAFT_06); const nine = forged.lastIndexOf(9); expect(nine).toBeGreaterThan(0); forged[nine] = 4; @@ -197,12 +224,12 @@ test("a hop chain that revisits a hop is refused in both directions", async () = // The type carries the consequence, not just the text: the subscriber's dispatch closes // the session on `instanceof ProtocolViolation`, so a plain Error here would reset the // stream and leave a nonconforming peer free to repeat itself. - await expect(decodeAnnounceBroadcast(new Reader(undefined, forged), Version.DRAFT_06)).rejects.toThrow( - ProtocolViolation, - ); - await expect(decodeAnnounceBroadcast(new Reader(undefined, forged), Version.DRAFT_06)).rejects.toThrow( - "appears twice", - ); + await expect( + decodeAnnounceBroadcast(new Reader(undefined, forged, Version.DRAFT_06), Version.DRAFT_06), + ).rejects.toThrow(ProtocolViolation); + await expect( + decodeAnnounceBroadcast(new Reader(undefined, forged, Version.DRAFT_06), Version.DRAFT_06), + ).rejects.toThrow("appears twice"); // Repeated unknowns are not a loop: 0 identifies nothing, so any number of hops may // be unknown. A lite-03 announcement is nothing but these. @@ -225,7 +252,7 @@ function unhex(text: string): Uint8Array { // Resolve every announcement on a lite-07 stream, as the subscriber does. async function resolveStream(data: Uint8Array) { - const reader = new Reader(undefined, data); + const reader = new Reader(undefined, data, Version.DRAFT_07); const history = new AnnounceHistory(); const out: unknown[] = []; for (;;) { @@ -260,7 +287,7 @@ const GOLDEN_RESOLVED = [ // Pinned from the Rust encoder (`lite::compress::tests::golden_stream_is_pinned`), so the // JS decoder is checked against real compressed output. const GOLDEN = - "001600000a726f6f6d2f612f63616d000251116222000000000d0102036d696301017333010000020a00010180004444010000010101000d02010162020180005555010000"; + "001600000a726f6f6d2f612f63616d00029111a222000000000d0102036d69630101b3330100000209000101c04444010000010101000c020101620201c05555010000"; test("AnnounceHistory resolves the Rust encoder's compressed stream", async () => { expect(await resolveStream(unhex(GOLDEN))).toEqual(GOLDEN_RESOLVED); @@ -268,7 +295,7 @@ test("AnnounceHistory resolves the Rust encoder's compressed stream", async () = // JS always encodes literally; Rust decodes these bytes too (`js_literal_stream_decodes`). const JS_LITERAL = - "001600000a726f6f6d2f612f63616d000251116222000000001600000a726f6f6d2f612f6d6963000273336222000000020c0000028000444462220000000101010014000006726f6f6d2f620002800055556222000000"; + "001600000a726f6f6d2f612f63616d00029111a222000000001600000a726f6f6d2f612f6d69630002b333a222000000020b000002c04444a2220000000101010013000006726f6f6d2f620002c05555a222000000"; test("the literal draft-07 stream matches what Rust decodes", async () => { const wire = await bytes(async (w) => { @@ -291,7 +318,7 @@ test("the literal draft-07 stream matches what Rust decodes", async () => { { status: "active", suffix: Path.from("room/b"), hops: [hop(0x5555n), relay], cost }, v, ); - }); + }, Version.DRAFT_07); expect(hex(wire)).toBe(JS_LITERAL); expect(await resolveStream(wire)).toEqual(GOLDEN_RESOLVED); }); @@ -335,10 +362,10 @@ test("a keep without a base is a violation on draft-07", async () => { await w.u53(0); await w.u53(8); for (const b of [0, 1, 0, 0, 0, 0, 0, 0]) await w.u8(b); - }); - await expect(decodeAnnounceBroadcast(new Reader(undefined, wire), Version.DRAFT_07)).rejects.toThrow( - ProtocolViolation, - ); + }, Version.DRAFT_07); + await expect( + decodeAnnounceBroadcast(new Reader(undefined, wire, Version.DRAFT_07), Version.DRAFT_07), + ).rejects.toThrow(ProtocolViolation); }); test("draft-06 has no room for a base", async () => { @@ -348,5 +375,31 @@ test("draft-06 has no room for a base", async () => { hops: [], pathBase: { distance: 1n, keep: 1 }, }; - await expect(bytes((w) => encodeAnnounceBroadcast(w, msg, Version.DRAFT_06))).rejects.toThrow(); + await expect(bytes((w) => encodeAnnounceBroadcast(w, msg, Version.DRAFT_06), Version.DRAFT_06)).rejects.toThrow(); +}); + +// Costs saturate at 2^62-1 on every version: a larger one from a lite-07 peer reads as the +// ceiling, and one set locally goes out as the ceiling, so a cost always forwards to lite-06. +test("route costs saturate at 2^62-1 on every version", async () => { + const ceiling = 2n ** 62n - 1n; + const huge = 2n ** 64n - 1n; + for (const version of [Version.DRAFT_06, Version.DRAFT_07]) { + const got = await roundTrip( + { status: "active", suffix: Path.from("x"), hops: [], cost: { warm: huge, cold: huge } }, + version, + ); + expect(got).toMatchObject({ cost: { warm: ceiling, cold: ceiling } }); + } + + // ANNOUNCE_START: path base, path keep, empty suffix, hop base, no hops, hop keep, then + // warm and cold at 2^64-1, which only lite-07's varints can carry. + const wire = await bytes(async (w) => { + await w.u53(0); + await w.u53(24); + for (const b of [0, 0, 0, 0, 0, 0]) await w.u8(b); + await w.u62(huge); + await w.u62(huge); + }, Version.DRAFT_07); + const got = await decodeAnnounceBroadcast(new Reader(undefined, wire, Version.DRAFT_07), Version.DRAFT_07); + expect(got).toMatchObject({ cost: { warm: ceiling, cold: ceiling } }); }); diff --git a/js/net/src/lite/announce.ts b/js/net/src/lite/announce.ts index da874389fa6..69ee0c09445 100644 --- a/js/net/src/lite/announce.ts +++ b/js/net/src/lite/announce.ts @@ -176,16 +176,20 @@ async function decodeHopsBlock(r: Reader, version: Version): Promise<{ hops: Hop } // The route cost rides lite-06+ announcements as two varints, warm then cold; older -// versions carry neither. +// versions carry neither. Costs saturate at 2^62-1 on every version, even where lite-07's +// varints could carry more, so a cost always forwards to a peer on an older version. +const MAX_COST = 2n ** 62n - 1n; +const saturate = (v: bigint) => (v > MAX_COST ? MAX_COST : v); + async function encodeRouteCost(w: Writer, version: Version, cost: Cost | undefined) { if (!hasRouteCost(version)) return; - await w.u62(cost?.warm ?? 0n); - await w.u62(cost?.cold ?? 0n); + await w.u62(saturate(cost?.warm ?? 0n)); + await w.u62(saturate(cost?.cold ?? 0n)); } async function decodeRouteCost(r: Reader, version: Version): Promise { if (!hasRouteCost(version)) return undefined; - return { warm: await r.u62(), cold: await r.u62() }; + return { warm: saturate(await r.u62()), cold: saturate(await r.u62()) }; } // lite-06 message body (no discriminator; the type is carried outside the length prefix). diff --git a/js/net/src/lite/connection.ts b/js/net/src/lite/connection.ts index 4aec63c3a3b..855ce50af8c 100644 --- a/js/net/src/lite/connection.ts +++ b/js/net/src/lite/connection.ts @@ -116,6 +116,11 @@ export class Connection implements Established { this.url = url; this.#quic = quic; this.#session = session; + // The session stream was opened at the SETUP exchange's version; the rest of it speaks this one. + if (session) { + session.reader.version = version; + session.writer.version = version; + } this.version = versionName(version); this.#version = version; this.transport = transportOf(quic); @@ -204,7 +209,7 @@ export class Connection implements Established { // our session identity so the peer can filter // reflected announcements (lite-06 removed ANNOUNCE_REQUEST's exclude_hop for it). async #sendSetup(): Promise { - const writer = await Writer.open(this.#quic); + const writer = await Writer.open(this.#quic, { version: this.#version }); try { await writer.u53(DataType.Setup); const probe = await probeLevel(this.#quic, this.#version); @@ -218,7 +223,7 @@ export class Connection implements Established { async #runBidis() { for (;;) { - const stream = await Stream.accept(this.#quic); + const stream = await Stream.accept(this.#quic, this.#version); if (!stream) break; this.#runBidi(stream) @@ -259,7 +264,7 @@ export class Connection implements Established { } async #runUnis() { - const readers = new Readers(this.#quic); + const readers = new Readers(this.#quic, this.#version); for (;;) { const stream = await readers.next(); diff --git a/js/net/src/lite/datagram.test.ts b/js/net/src/lite/datagram.test.ts index ff2b8d04f77..80abce58db8 100644 --- a/js/net/src/lite/datagram.test.ts +++ b/js/net/src/lite/datagram.test.ts @@ -1,28 +1,38 @@ import { expect, test } from "bun:test"; import { Datagram } from "./datagram.ts"; +import { Version } from "./version.ts"; const enc = new TextEncoder(); const dec = new TextDecoder(); test("datagram body round-trips", async () => { - const dg = new Datagram(7n, 42, 1000, enc.encode("hello")); - const decoded = await Datagram.decode(dg.encode()); - expect(decoded.subscribe).toBe(7n); - expect(decoded.sequence).toBe(42); - expect(decoded.timestamp).toBe(1000); - expect(dec.decode(decoded.payload)).toBe("hello"); + for (const version of [Version.DRAFT_06, Version.DRAFT_07]) { + const dg = new Datagram(7n, 42, 1000, enc.encode("hello")); + const decoded = await Datagram.decode(dg.encode(version), version); + expect(decoded.subscribe).toBe(7n); + expect(decoded.sequence).toBe(42); + expect(decoded.timestamp).toBe(1000); + expect(dec.decode(decoded.payload)).toBe("hello"); + } }); test("datagram body has no inner length prefix", () => { const dg = new Datagram(1n, 2, 3, enc.encode("world")); - const body = dg.encode(); + const body = dg.encode(Version.DRAFT_06); // Three single-byte varints (values < 64) followed by the raw 5-byte payload. expect(body.byteLength).toBe(8); expect(dec.decode(body.slice(3))).toBe("world"); }); +test("datagram body varints follow the version's encoding", () => { + // 100 takes the two-byte QUIC form on lite-06 and one leading-ones byte on lite-07. + const dg = new Datagram(100n, 100, 100, new Uint8Array()); + expect([...dg.encode(Version.DRAFT_06)]).toEqual([0x40, 0x64, 0x40, 0x64, 0x40, 0x64]); + expect([...dg.encode(Version.DRAFT_07)]).toEqual([0x64, 0x64, 0x64]); +}); + test("datagram body round-trips an empty payload", async () => { const dg = new Datagram(0n, 0, 0, new Uint8Array()); - const decoded = await Datagram.decode(dg.encode()); + const decoded = await Datagram.decode(dg.encode(Version.DRAFT_07), Version.DRAFT_07); expect(decoded.payload.byteLength).toBe(0); }); diff --git a/js/net/src/lite/datagram.ts b/js/net/src/lite/datagram.ts index 1f76707e17a..6fbb0df9d02 100644 --- a/js/net/src/lite/datagram.ts +++ b/js/net/src/lite/datagram.ts @@ -3,8 +3,8 @@ * * @module */ -import { Reader } from "../stream.ts"; -import * as Varint from "../varint.ts"; +import { encodeVarint, Reader } from "../stream.ts"; +import type { Version } from "./version.ts"; /** * A QUIC datagram body: `subscribe (i) | sequence (i) | timestamp (i) | payload (b)`. @@ -31,10 +31,10 @@ export class Datagram { } /** Encode the body to a single `Uint8Array` (no length prefix; the datagram boundary delimits it). */ - encode(): Uint8Array { - const subscribe = Varint.encodeTo(new ArrayBuffer(8), this.subscribe); - const sequence = Varint.encodeTo(new ArrayBuffer(8), this.sequence); - const timestamp = Varint.encodeTo(new ArrayBuffer(8), this.timestamp); + encode(version: Version): Uint8Array { + const subscribe = encodeVarint(this.subscribe, version); + const sequence = encodeVarint(this.sequence, version); + const timestamp = encodeVarint(this.timestamp, version); const out = new Uint8Array( subscribe.byteLength + sequence.byteLength + timestamp.byteLength + this.payload.byteLength, @@ -51,8 +51,8 @@ export class Datagram { } /** Decode a datagram body from the raw bytes of one QUIC datagram. */ - static async decode(data: Uint8Array): Promise { - const r = new Reader(undefined, data); + static async decode(data: Uint8Array, version: Version): Promise { + const r = new Reader(undefined, data, version); const subscribe = await r.u62(); const sequence = await r.u53(); const timestamp = await r.u53(); diff --git a/js/net/src/lite/fetch.test.ts b/js/net/src/lite/fetch.test.ts index 0eb06dca94e..c073a51cd90 100644 --- a/js/net/src/lite/fetch.test.ts +++ b/js/net/src/lite/fetch.test.ts @@ -19,6 +19,7 @@ async function encode(version: Version, fetch: Fetch): Promise { const written: Uint8Array[] = []; const writer = new Writer( new WritableStream({ write: (chunk) => void written.push(new Uint8Array(chunk)) }), + version, ); await fetch.encode(writer, version); writer.close(); @@ -27,7 +28,7 @@ async function encode(version: Version, fetch: Fetch): Promise { } async function roundtrip(version: Version, fetch: Fetch): Promise { - const reader = new Reader(undefined, await encode(version, fetch)); + const reader = new Reader(undefined, await encode(version, fetch), version); return Fetch.decode(reader, version); } diff --git a/js/net/src/lite/goaway.test.ts b/js/net/src/lite/goaway.test.ts index 17d7a43800e..a051b010ce6 100644 --- a/js/net/src/lite/goaway.test.ts +++ b/js/net/src/lite/goaway.test.ts @@ -18,6 +18,7 @@ async function encode(msg: Goaway, version: Version): Promise { const written: Uint8Array[] = []; const writer = new Writer( new WritableStream({ write: (chunk) => void written.push(new Uint8Array(chunk)) }), + version, ); await msg.encode(writer, version); writer.close(); @@ -26,7 +27,7 @@ async function encode(msg: Goaway, version: Version): Promise { } async function decode(bytes: Uint8Array, version: Version): Promise { - const reader = new Reader(undefined, bytes); + const reader = new Reader(undefined, bytes, version); return await Goaway.decode(reader, version); } diff --git a/js/net/src/lite/group.test.ts b/js/net/src/lite/group.test.ts index e0df4212ed0..44e2c9b64e7 100644 --- a/js/net/src/lite/group.test.ts +++ b/js/net/src/lite/group.test.ts @@ -3,9 +3,13 @@ import { Producer } from "../group.ts"; import { Reader } from "../stream.ts"; import * as Varint from "../varint.ts"; import { readFrames } from "./group.ts"; +import { Version } from "./version.ts"; const SCALE = 1000; +// The frames below are QUIC varints, so the streams read them as lite-06. +const VERSION = Version.DRAFT_06; + /** Frames as a group stream carries them: a zigzag timestamp delta when timestamped, then the sized payload. */ function encode(frames: { delta?: number; payload: number[] }[]): Uint8Array { const bytes: number[] = []; @@ -24,6 +28,8 @@ function streamOf(chunks: Uint8Array[]): Reader { controller.close(); }, }), + undefined, + VERSION, ); } @@ -86,7 +92,7 @@ test("a stream that ends inside a frame rejects", async () => { test("stops once the group closes", async () => { const producer = new Producer(0); // Never ends: only the close can stop the read. - const stream = new Reader(new ReadableStream()); + const stream = new Reader(new ReadableStream(), undefined, VERSION); const done = readFrames(stream, producer, SCALE); producer.close(); await done; diff --git a/js/net/src/lite/message.ts b/js/net/src/lite/message.ts index ba36ab80a7b..b48552e5542 100644 --- a/js/net/src/lite/message.ts +++ b/js/net/src/lite/message.ts @@ -31,6 +31,7 @@ export async function encode(writer: Writer, f: (w: Writer) => Promise, ma } }, }), + writer.version, ); await f(temp); @@ -55,7 +56,7 @@ export async function decode(reader: Reader, f: (r: Reader) => Promise, ma } const data = await reader.read(size); - const limit = new Reader(undefined, data); + const limit = new Reader(undefined, data, reader.version); const msg = await f(limit); // Check that we consumed exactly the right number of bytes diff --git a/js/net/src/lite/priority.test.ts b/js/net/src/lite/priority.test.ts index 5adf91897ef..25733b381de 100644 --- a/js/net/src/lite/priority.test.ts +++ b/js/net/src/lite/priority.test.ts @@ -3,6 +3,7 @@ import { Producer as BroadcastProducer } from "../broadcast.ts"; import { type SendStream, Writer } from "../stream.ts"; import { Priority, sendOrder } from "./priority.ts"; +import { Version } from "./version.ts"; // The last position that still fits below the track priority. const MAX_POSITION = 2 ** 44 - 1; @@ -64,7 +65,7 @@ function ranking(options: { priority?: number; ordered?: boolean } = {}) { const open = () => { const stream = new WritableStream() as SendStream; streams.push(stream); - return new Writer(stream); + return new Writer(stream, Version.DRAFT_06); }; return { priority: new Priority(subscriber), open, streams, broadcast }; diff --git a/js/net/src/lite/probe.test.ts b/js/net/src/lite/probe.test.ts index 150f96c8c7d..ff44a4f7484 100644 --- a/js/net/src/lite/probe.test.ts +++ b/js/net/src/lite/probe.test.ts @@ -14,10 +14,11 @@ function concat(chunks: Uint8Array[]): Uint8Array { return out; } -async function bytes(f: (w: Writer) => Promise): Promise { +async function bytes(f: (w: Writer) => Promise, version: Version): Promise { const written: Uint8Array[] = []; const writer = new Writer( new WritableStream({ write: (chunk) => void written.push(new Uint8Array(chunk)) }), + version, ); await f(writer); writer.close(); @@ -26,7 +27,7 @@ async function bytes(f: (w: Writer) => Promise): Promise { } async function roundTrip(msg: Probe, version: Version = Version.DRAFT_05): Promise { - const reader = new Reader(undefined, await bytes((w) => msg.encode(w, version))); + const reader = new Reader(undefined, await bytes((w) => msg.encode(w, version), version), version); const got = await Probe.decode(reader, version); expect(await reader.done()).toBe(true); return got; @@ -66,7 +67,9 @@ test("lite-03 carries the bitrate alone", async () => { // varint encoder converts with `BigInt`, which throws on one, and the publisher's // catch would then close the probe stream for the rest of the session. test("a fractional RTT must not reach the encoder", async () => { - await expect(bytes((w) => new Probe({ bitrate: 1_000, rtt: 12.34 }).encode(w, Version.DRAFT_05))).rejects.toThrow(); + await expect( + bytes((w) => new Probe({ bitrate: 1_000, rtt: 12.34 }).encode(w, Version.DRAFT_05), Version.DRAFT_05), + ).rejects.toThrow(); // Rounding first is what the publisher does, and it encodes cleanly. const got = await roundTrip(new Probe({ bitrate: 1_000, rtt: Math.round(12.34) })); diff --git a/js/net/src/lite/publisher.test.ts b/js/net/src/lite/publisher.test.ts index 2466166cd29..64d50dd9806 100644 --- a/js/net/src/lite/publisher.test.ts +++ b/js/net/src/lite/publisher.test.ts @@ -45,6 +45,7 @@ test.each([Version.DRAFT_01, Version.DRAFT_03, Version.DRAFT_06])( await Promise.resolve(); const failure = new Error("peer stopped receiving announcements"); const stream = new Stream({ + version: version, readable: new ReadableStream(), writable: new WritableStream({ write() { @@ -96,6 +97,7 @@ test.each([ const written: Uint8Array[] = []; const stream = new Stream({ + version: version, readable: new ReadableStream(), writable: new WritableStream({ write(chunk) { @@ -132,8 +134,8 @@ async function subscribeEnd(sequences: number[], version: Version = Version.DRAF const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version }); + const server = await Stream.accept(pair.server, version); if (!server) throw new Error("publisher never accepted the subscribe stream"); const msg = new Subscribe({ id: 0n, broadcast: Path.from("test"), track: "video", priority: 0 }); @@ -195,8 +197,8 @@ async function groupSendOrders(options: { priority: number; sequences: number[]; const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); + const server = await Stream.accept(pair.server, Version.DRAFT_05); if (!server) throw new Error("publisher never accepted the subscribe stream"); const msg = replaySubscribe({ @@ -279,8 +281,8 @@ test("lite draft-05: a subscribe update re-ranks a group already on the wire", a const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); + const server = await Stream.accept(pair.server, Version.DRAFT_05); if (!server) throw new Error("publisher never accepted the subscribe stream"); const msg = replaySubscribe({ @@ -343,8 +345,8 @@ test("lite draft-05: a subscribe update during the stream open still ranks the g return open(options); }; - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); + const server = await Stream.accept(pair.server, Version.DRAFT_05); if (!server) throw new Error("publisher never accepted the subscribe stream"); const msg = replaySubscribe({ @@ -392,8 +394,8 @@ test("lite draft-05: many concurrent groups share one subscription listener", as const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); + const server = await Stream.accept(pair.server, Version.DRAFT_05); if (!server) throw new Error("publisher never accepted the subscribe stream"); const msg = replaySubscribe({ @@ -451,7 +453,7 @@ test("lite draft-05: the fetch response ranks the publisher's own writes", async group.close(); track.writeGroup(group); - const client = await Stream.open(pair.client); + const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); // Accept by hand rather than via Stream.accept, so the test keeps the writable the // publisher ranks (a real WebTransportSendStream takes the same assignment). @@ -459,7 +461,7 @@ test("lite draft-05: the fetch response ranks the publisher's own writes", async const accepted = await incoming.read(); incoming.releaseLock(); if (accepted.done) throw new Error("publisher never saw the fetch stream"); - const server = new Stream(accepted.value); + const server = new Stream({ ...accepted.value, version: Version.DRAFT_05 }); const msg = new Fetch({ broadcast: Path.from("test"), track: "video", priority: 3, group: 7 }); try { @@ -545,7 +547,7 @@ async function servedSubscription( const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video", { maxAge: options.maxAge }); - const client = await Stream.open(pair.client); + const client = await Stream.open(pair.client, { version: version }); // Accept by hand rather than via Stream.accept, so the gate sits between the publisher // and the wire. @@ -555,7 +557,7 @@ async function servedSubscription( if (accepted.done) throw new Error("publisher never accepted the subscribe stream"); const gate = gateWrites(accepted.value.writable, options.gated ?? false); - const server = new Stream({ readable: accepted.value.readable, writable: gate.writable }); + const server = new Stream({ readable: accepted.value.readable, writable: gate.writable, version: version }); const msg = replaySubscribe({ id: 0n, @@ -597,7 +599,7 @@ async function servedSubscription( clearTimeout(timer); if (!next || next.done) return undefined; - const reader = new Reader(next.value); + const reader = new Reader(next.value, undefined, version); await reader.u53(); // stream type const header = await GroupMessage.decode(reader, version); @@ -1046,8 +1048,8 @@ test("lite draft-07: subscribe end waits for groups below a declared finish", as const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_07 }); + const server = await Stream.accept(pair.server, Version.DRAFT_07); if (!server) throw new Error("publisher never accepted the subscribe stream"); void publisher.runSubscribe( new Subscribe({ id: 0n, broadcast: Path.from("test"), track: "video", priority: 0 }), @@ -1101,8 +1103,8 @@ async function heldOpenEnd() { return createUni(options); }); - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_07 }); + const server = await Stream.accept(pair.server, Version.DRAFT_07); if (!server) throw new Error("publisher never accepted the subscribe stream"); void publisher.runSubscribe( new Subscribe({ id: 0n, broadcast: Path.from("test"), track: "video", priority: 0 }), @@ -1178,8 +1180,8 @@ async function serve( const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_06 }); + const server = await Stream.accept(pair.server, Version.DRAFT_06); if (!server) throw new Error("publisher never accepted the subscribe stream"); const msg = new Subscribe({ @@ -1221,7 +1223,7 @@ async function serve( clearTimeout(timer); if (!next || next.done) break; - const stream = new Reader(next.value); + const stream = new Reader(next.value, undefined, Version.DRAFT_06); await stream.u53(); // stream type const header = await GroupMessage.decode(stream, Version.DRAFT_06); @@ -1367,8 +1369,8 @@ async function saturatedGroup() { const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); + const server = await Stream.accept(pair.server, Version.DRAFT_05); if (!server) throw new Error("publisher never accepted the subscribe stream"); const msg = new Subscribe({ id: 0n, broadcast: Path.from("test"), track: "video", priority: 0 }); @@ -1446,8 +1448,8 @@ test("lite draft-05: a blocked group header is reset when the group expires", as const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop(), origin.consume()); const broadcast = publish(origin, Path.from("test")); const track = broadcast.createTrack("video"); - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); + const server = await Stream.accept(pair.server, Version.DRAFT_05); if (!server) throw new Error("publisher never accepted the subscribe stream"); try { @@ -1533,8 +1535,8 @@ test("runProbe rounds a fractional smoothedRtt instead of killing the stream", a const publisher = new Publisher(pair.server, Version.DRAFT_05, randomHop()); // The subscriber opens the probe stream; the publisher only replies on it. - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); + const server = await Stream.accept(pair.server, Version.DRAFT_05); if (!server) throw new Error("publisher never accepted the probe stream"); // `runProbe` loops until the stream closes, so close it rather than leaving the @@ -1603,8 +1605,8 @@ test("lite draft-05: a group that goes stale while its stream opens writes nothi return stale; }); - const client = await Stream.open(pair.client); - const server = await Stream.accept(pair.server); + const client = await Stream.open(pair.client, { version: Version.DRAFT_05 }); + const server = await Stream.accept(pair.server, Version.DRAFT_05); if (!server) throw new Error("publisher never accepted the subscribe stream"); try { diff --git a/js/net/src/lite/publisher.ts b/js/net/src/lite/publisher.ts index 7ed96222225..d8d5c57004b 100644 --- a/js/net/src/lite/publisher.ts +++ b/js/net/src/lite/publisher.ts @@ -974,7 +974,7 @@ export class Publisher { // Convert the timestamp to the track's advertised timescale, matching #serveGroup. const ts = Math.round(datagram.timestamp.as(timescale)); - const body = new DatagramMessage(sub, datagram.sequence, ts, datagram.payload).encode(); + const body = new DatagramMessage(sub, datagram.sequence, ts, datagram.payload).encode(this.version); // No group fallback: drop anything that doesn't fit a single datagram. if (body.byteLength > maxSize) { @@ -1038,6 +1038,7 @@ export class Publisher { // in the order we asked, which is oldest-first, exactly backwards for live media. // Failing here drops the group and lets the next one compete for the next slot. const stream = await Writer.tryOpen(this.#quic, { + version: this.version, sendOrder: priority.rank(group.sequence), cancel: unsubscribed, waitUntilAvailable: false, diff --git a/js/net/src/lite/setup.test.ts b/js/net/src/lite/setup.test.ts index 77d2332ba1a..7a7b805142c 100644 --- a/js/net/src/lite/setup.test.ts +++ b/js/net/src/lite/setup.test.ts @@ -23,10 +23,11 @@ function concat(chunks: Uint8Array[]): Uint8Array { return out; } -async function bytes(f: (w: Writer) => Promise): Promise { +async function bytes(f: (w: Writer) => Promise, version: Version): Promise { const written: Uint8Array[] = []; const writer = new Writer( new WritableStream({ write: (chunk) => void written.push(new Uint8Array(chunk)) }), + version, ); await f(writer); writer.close(); @@ -35,7 +36,11 @@ async function bytes(f: (w: Writer) => Promise): Promise { } async function roundTrip(msg: Setup): Promise { - const reader = new Reader(undefined, await bytes((w) => msg.encode(w, Version.DRAFT_05))); + const reader = new Reader( + undefined, + await bytes((w) => msg.encode(w, Version.DRAFT_05), Version.DRAFT_05), + Version.DRAFT_05, + ); const got = await Setup.decode(reader, Version.DRAFT_05); expect(await reader.done()).toBe(true); return got; @@ -49,14 +54,14 @@ async function decodeParam(id: bigint, value: Uint8Array): Promise { await w.u62(id); await w.u53(value.byteLength); if (value.byteLength > 0) await w.write(value); - }); + }, Version.DRAFT_05); const framed = await bytes(async (w) => { await w.u53(body.byteLength); // Message size prefix await w.write(body); - }); + }, Version.DRAFT_05); - return await Setup.decode(new Reader(undefined, framed), Version.DRAFT_05); + return await Setup.decode(new Reader(undefined, framed, Version.DRAFT_05), Version.DRAFT_05); } test("empty SETUP round-trips on draft-05", async () => { @@ -98,15 +103,18 @@ test("Both is the wire default, so it is omitted rather than encoded", async () // Both must be the absence of the parameter, so a server that predates it decodes a // Both client back to Both. Assert the empty bag directly: comparing against another // default-constructed Setup would agree with itself even if we encoded Both. - const both = await bytes((w) => new Setup({ role: Role.Both }).encode(w, Version.DRAFT_05)); + const both = await bytes((w) => new Setup({ role: Role.Both }).encode(w, Version.DRAFT_05), Version.DRAFT_05); const emptyBag = await bytes(async (w) => { await w.u53(1); // Message size prefix: one byte of body follows await w.u53(0); // parameter count - }); + }, Version.DRAFT_05); expect(both).toEqual(emptyBag); // A directional role is still encoded, so the check above can actually fail. - const publisher = await bytes((w) => new Setup({ role: Role.Publisher }).encode(w, Version.DRAFT_05)); + const publisher = await bytes( + (w) => new Setup({ role: Role.Publisher }).encode(w, Version.DRAFT_05), + Version.DRAFT_05, + ); expect(publisher.byteLength).toBeGreaterThan(both.byteLength); }); @@ -140,12 +148,12 @@ test("hop 0 decodes as absent", async () => { }); test("SETUP is rejected before draft-05", async () => { - await expect(bytes((w) => new Setup().encode(w, Version.DRAFT_04))).rejects.toThrow(); + await expect(bytes((w) => new Setup().encode(w, Version.DRAFT_04), Version.DRAFT_04)).rejects.toThrow(); }); test("SETUP decode is rejected before draft-05", async () => { - const framed = await bytes((w) => new Setup().encode(w, Version.DRAFT_05)); - await expect(Setup.decode(new Reader(undefined, framed), Version.DRAFT_04)).rejects.toThrow(); + const framed = await bytes((w) => new Setup().encode(w, Version.DRAFT_05), Version.DRAFT_05); + await expect(Setup.decode(new Reader(undefined, framed, Version.DRAFT_04), Version.DRAFT_04)).rejects.toThrow(); }); test("empty path decodes as the root", async () => { @@ -165,11 +173,13 @@ test("SETUP encode stops at the 64 KiB receive limit", async () => { expect((await roundTrip(msg)).path).toBe(msg.path); const over = new Setup({ path: "a".repeat(atLimit + 1) }); - await expect(bytes((w) => over.encode(w, Version.DRAFT_05))).rejects.toThrow("too large"); + await expect(bytes((w) => over.encode(w, Version.DRAFT_05), Version.DRAFT_05)).rejects.toThrow("too large"); }); test("SETUP decode refuses an oversized length before reading the body", async () => { // Only the prefix is present, so reading the body would fail with a different error. - const prefix = await bytes((w) => w.u53(64 * 1024 + 1)); - await expect(Setup.decode(new Reader(undefined, prefix), Version.DRAFT_05)).rejects.toThrow("too large"); + const prefix = await bytes((w) => w.u53(64 * 1024 + 1), Version.DRAFT_05); + await expect(Setup.decode(new Reader(undefined, prefix, Version.DRAFT_05), Version.DRAFT_05)).rejects.toThrow( + "too large", + ); }); diff --git a/js/net/src/lite/setup.ts b/js/net/src/lite/setup.ts index 37b724a4d0b..22b61b42680 100644 --- a/js/net/src/lite/setup.ts +++ b/js/net/src/lite/setup.ts @@ -6,9 +6,8 @@ */ import { type Hop, HopSchema } from "../hop.ts"; -import type { Reader, Writer } from "../stream.ts"; +import { encodeVarint, Reader, type Writer } from "../stream.ts"; import { decodeUtf8 } from "../util/utf8.ts"; -import * as Varint from "../varint.ts"; import * as Message from "./message.ts"; import { hasSetupStream, type Version } from "./version.ts"; @@ -114,20 +113,21 @@ class Parameters { return this.#entries.get(id); } - /** Set a parameter to a varint value, replacing any existing entry. */ - setVarint(id: bigint, value: number | bigint) { - this.#entries.set(id, Varint.encode(Number(value))); + /** Set a parameter to a varint value in `version`'s encoding, replacing any existing entry. */ + setVarint(id: bigint, value: number | bigint, version: Version) { + this.#entries.set(id, encodeVarint(value, version)); } - /** Decode a parameter as a single varint, if present. Throws if trailing bytes remain. */ - getVarint(id: bigint): bigint | undefined { + /** Decode a parameter as a single varint in `version`'s encoding, if present. Throws if trailing bytes remain. */ + async getVarint(id: bigint, version: Version): Promise { const bytes = this.#entries.get(id); if (bytes === undefined) return undefined; - const [value, remain] = Varint.decode(bytes); - if (remain.byteLength !== 0) { + const r = new Reader(undefined, bytes, version); + const value = await r.u62(); + if (!(await r.done())) { throw new Error("trailing bytes after varint parameter"); } - return BigInt(value); + return value; } async encode(w: Writer) { @@ -225,29 +225,29 @@ export class Setup { } } - async #encode(w: Writer) { + async #encode(w: Writer, version: Version) { const params = new Parameters(); // None is the wire default, so omit it to keep the message empty when nothing is set. if (this.probe !== ProbeLevel.None) { - params.setVarint(PARAM_PROBE, this.probe); + params.setVarint(PARAM_PROBE, this.probe, version); } if (this.path !== undefined) { params.setBytes(PARAM_PATH, new TextEncoder().encode(this.path)); } // Both is the wire default, sent as the absence of the parameter. if (this.role !== Role.Both) { - params.setVarint(PARAM_ROLE, this.role); + params.setVarint(PARAM_ROLE, this.role, version); } if (this.hop !== undefined && this.hop !== 0n) { - params.setVarint(PARAM_HOP, this.hop); + params.setVarint(PARAM_HOP, this.hop, version); } await params.encode(w); } - static async #decode(r: Reader): Promise { + static async #decode(r: Reader, version: Version): Promise { const params = await Parameters.decode(r); - const probeCode = params.getVarint(PARAM_PROBE); + const probeCode = await params.getVarint(PARAM_PROBE, version); const probe = probeCode === undefined ? ProbeLevel.None : probeFromCode(probeCode); // An empty path is valid and means the same as omitting the parameter, so a @@ -255,11 +255,11 @@ export class Setup { const pathBytes = params.getBytes(PARAM_PATH); const path = pathBytes === undefined ? undefined : decodeUtf8(pathBytes); - const roleCode = params.getVarint(PARAM_ROLE); + const roleCode = await params.getVarint(PARAM_ROLE, version); const role = roleCode === undefined ? Role.Both : roleFromCode(roleCode); // 0 carries no identity (it cannot be excluded), so it decodes as absent. - const hopRaw = params.getVarint(PARAM_HOP); + const hopRaw = await params.getVarint(PARAM_HOP, version); const hop = hopRaw === undefined || hopRaw === 0n ? undefined : HopSchema.parse(hopRaw); return new Setup({ probe, path, role, hop }); @@ -268,12 +268,12 @@ export class Setup { /** Encode the SETUP message with its size prefix. Throws on pre-lite-05 versions. */ async encode(w: Writer, version: Version): Promise { Setup.#guard(version); - return Message.encode(w, this.#encode.bind(this), MAX_SETUP_SIZE); + return Message.encode(w, (w) => this.#encode(w, version), MAX_SETUP_SIZE); } /** Decode a SETUP message with its size prefix. Throws on pre-lite-05 versions. */ static async decode(r: Reader, version: Version): Promise { Setup.#guard(version); - return Message.decode(r, Setup.#decode, MAX_SETUP_SIZE); + return Message.decode(r, (r) => Setup.#decode(r, version), MAX_SETUP_SIZE); } } diff --git a/js/net/src/lite/subscribe.test.ts b/js/net/src/lite/subscribe.test.ts index afd4c7c0a66..4da1af09185 100644 --- a/js/net/src/lite/subscribe.test.ts +++ b/js/net/src/lite/subscribe.test.ts @@ -32,6 +32,7 @@ async function encode(version: Version, resp: SubscribeResponse): Promise({ write: (chunk) => void written.push(new Uint8Array(chunk)) }), + version, ); await encodeSubscribeResponse(writer, resp, version); writer.close(); @@ -40,12 +41,12 @@ async function encode(version: Version, resp: SubscribeResponse): Promise { - const reader = new Reader(undefined, await encode(version, resp)); + const reader = new Reader(undefined, await encode(version, resp), version); return decodeSubscribeResponse(reader, version); } async function encodeSubscribe(msg: Subscribe): Promise { - const writer = new Writer(new WritableStream()); + const writer = new Writer(new WritableStream(), Version.DRAFT_06); try { await msg.encode(writer, Version.DRAFT_06); } finally { @@ -60,6 +61,7 @@ async function encodeMessage( const written: Uint8Array[] = []; const writer = new Writer( new WritableStream({ write: (chunk) => void written.push(new Uint8Array(chunk)) }), + version, ); await message.encode(writer, version); writer.close(); @@ -90,7 +92,7 @@ test("Subscribe round-trips every option including startGroup 0", async () => { // Lite-06 carries the raw floor, and a floor of 0 with no frame offset is the same // absence of a constraint as no floor at all, so it canonicalizes to undefined. const got = await Subscribe.decode( - new Reader(undefined, await encodeMessage(Version.DRAFT_06, message)), + new Reader(undefined, await encodeMessage(Version.DRAFT_06, message), Version.DRAFT_06), Version.DRAFT_06, ); expect(got.priority).toBe(7); @@ -102,7 +104,7 @@ test("Subscribe round-trips every option including startGroup 0", async () => { // partway through group 0 (a catalog never leaves it). message.startFrame = 4; const resumed = await Subscribe.decode( - new Reader(undefined, await encodeMessage(Version.DRAFT_06, message)), + new Reader(undefined, await encodeMessage(Version.DRAFT_06, message), Version.DRAFT_06), Version.DRAFT_06, ); expect(resumed.startGroup).toBe(0); @@ -112,7 +114,7 @@ test("Subscribe round-trips every option including startGroup 0", async () => { // A pre-06 wire folds the vacuous floor back to absent: an explicit group 0 there // would mean "replay from the beginning", which is not what a floor of 0 asks for. const folded = await Subscribe.decode( - new Reader(undefined, await encodeMessage(Version.DRAFT_05, message)), + new Reader(undefined, await encodeMessage(Version.DRAFT_05, message), Version.DRAFT_05), Version.DRAFT_05, ); expect(folded.startGroup).toBeUndefined(); @@ -127,7 +129,7 @@ test("SubscribeUpdate round-trips every option including startGroup 0", async () endGroup: 12, }); const got = await SubscribeUpdate.decode( - new Reader(undefined, await encodeMessage(Version.DRAFT_06, message)), + new Reader(undefined, await encodeMessage(Version.DRAFT_06, message), Version.DRAFT_06), Version.DRAFT_06, ); expect(got.priority).toBe(8); @@ -137,7 +139,7 @@ test("SubscribeUpdate round-trips every option including startGroup 0", async () // The same fold as SUBSCRIBE on a pre-06 wire. const folded = await SubscribeUpdate.decode( - new Reader(undefined, await encodeMessage(Version.DRAFT_05, message)), + new Reader(undefined, await encodeMessage(Version.DRAFT_05, message), Version.DRAFT_05), Version.DRAFT_05, ); expect(folded.startGroup).toBeUndefined(); @@ -173,9 +175,9 @@ test("SubscribeDrop is gone on draft-07", async () => { // A draft-06 DROP is an unknown response type on draft-07. const wire06 = await encode(Version.DRAFT_06, drop); - await expect(decodeSubscribeResponse(new Reader(undefined, wire06), Version.DRAFT_07)).rejects.toThrow( - "unknown subscribe response type: 2", - ); + await expect( + decodeSubscribeResponse(new Reader(undefined, wire06, Version.DRAFT_07), Version.DRAFT_07), + ).rejects.toThrow("unknown subscribe response type: 2"); }); test("SubscribeDrop is type 0x2 on draft-05 and 0x1 on draft-04", async () => { diff --git a/js/net/src/lite/subscriber.test.ts b/js/net/src/lite/subscriber.test.ts index 03ba18cad58..de0190a75f3 100644 --- a/js/net/src/lite/subscriber.test.ts +++ b/js/net/src/lite/subscriber.test.ts @@ -72,6 +72,7 @@ function announceHarness(version: Version, origin = 1n) { const written: Uint8Array[] = []; const writer = new Writer( new WritableStream({ write: (chunk) => void written.push(new Uint8Array(chunk)) }), + version, ); await f(writer); writer.close(); @@ -392,6 +393,7 @@ async function probeBytes(probes: Probe[], version: Version): Promise({ write: (chunk) => void chunks.push(new Uint8Array(chunk)) }), + version, ); for (const probe of probes) await probe.encode(writer, version); writer.close(); @@ -775,6 +777,7 @@ async function answerTrackInfo(stream: FakeStream): Promise { const chunks: Uint8Array[] = []; const writer = new Writer( new WritableStream({ write: (chunk) => void chunks.push(new Uint8Array(chunk)) }), + Version.DRAFT_05, ); await new TrackInfo({}).encode(writer, Version.DRAFT_05); for (const chunk of chunks) stream.inbound.enqueue(chunk); diff --git a/js/net/src/lite/subscriber.ts b/js/net/src/lite/subscriber.ts index b81d761ee18..30a6e03cdbf 100644 --- a/js/net/src/lite/subscriber.ts +++ b/js/net/src/lite/subscriber.ts @@ -217,7 +217,7 @@ export class Subscriber { // to reset the stream, not just close our side of it. let stream: Stream; try { - stream = await Stream.open(this.#quic); + stream = await Stream.open(this.#quic, { version: this.version }); } catch (err: unknown) { announced.close(error(err)); return; @@ -663,7 +663,7 @@ export class Subscriber { }; this.#subscribes.set(id, entry); - state.stream = await Stream.open(this.#quic); + state.stream = await Stream.open(this.#quic, { version: this.version }); await state.stream.writer.u53(StreamId.Subscribe); await msg.encode(state.stream.writer, this.version); @@ -680,7 +680,7 @@ export class Subscriber { // Opens a TRACK stream, reads the single TRACK_INFO, and FINs. Lite-05+ only. async #trackInfo(broadcast: Path.Valid, track: string): Promise { - return this.#exchange(undefined, async (stream) => { + return this.#exchange({ version: this.version }, async (stream) => { await stream.writer.u53(StreamId.Track); await new TrackMessage(broadcast, track).encode(stream.writer, this.version); const info = await TrackInfo.decode(stream.reader, this.version); @@ -693,7 +693,7 @@ export class Subscriber { // Opens a stream and runs a request/response exchange on it, resetting the stream if `run` // fails. Subscriber.close() also resets it while `run` is pending, so a peer that never // answers cannot hold it open, and a stream that opens after the close is reset at once. - async #exchange(options: OpenOptions | undefined, run: (stream: Stream) => Promise): Promise { + async #exchange(options: OpenOptions, run: (stream: Stream) => Promise): Promise { const closed = this.#closed.signal; closed.throwIfAborted(); const stream = await Stream.open(this.#quic, options); @@ -820,7 +820,7 @@ export class Subscriber { group: netGroup.Producer, ): Promise<{ stream: Stream; info: TrackInfo }> { const info = await untilClosed(group, this.#trackInfo(broadcast, track)); - return this.#exchange({ sendOrder: sendOrder({ priority }) }, async (stream) => { + return this.#exchange({ sendOrder: sendOrder({ priority }), version: this.version }, async (stream) => { await stream.writer.u53(StreamId.Fetch); await new FetchMessage({ broadcast, track, priority, group: sequence }).encode(stream.writer, this.version); // A byte or an empty-group FIN accepts the fetch; a reset rejects it. @@ -1127,7 +1127,7 @@ export class Subscriber { // Decode one datagram body and hand it to the matching subscription's producer. Drops the // datagram (best-effort) if the subscription is unknown/closed or its timescale isn't resolved. async #routeDatagram(payload: Uint8Array): Promise { - const dg = await DatagramMessage.decode(payload); + const dg = await DatagramMessage.decode(payload, this.version); const entry = this.#subscribes.get(dg.subscribe); if (!entry) return; // Unknown or already-closed subscription. @@ -1180,7 +1180,7 @@ export class Subscriber { // transport hiccup) MUST NOT tear down the connection. On error, drop the // estimates so consumers know they're stale. try { - const stream = await Stream.open(this.#quic); + const stream = await Stream.open(this.#quic, { version: this.version }); await stream.writer.u53(StreamId.Probe); for (;;) { diff --git a/js/net/src/lite/tail.test.ts b/js/net/src/lite/tail.test.ts index 87e0a9a474a..b6717c2860e 100644 --- a/js/net/src/lite/tail.test.ts +++ b/js/net/src/lite/tail.test.ts @@ -37,7 +37,7 @@ function groupStream(subscriber: Subscriber, sequence: number) { const readable = new ReadableStream({ start: (c) => (controller = c) }); const handled = subscriber.runGroup( new GroupMessage({ subscribe: 0n, sequence }), - new Reader(readable, undefined, undefined), + new Reader(readable, undefined, subscriber.version), ); return { write: (payload: string) => controller.enqueue(frame(payload)), @@ -57,14 +57,14 @@ async function subscribed(version: Version, maxAge = GRACE, groups?: Groups) { const subscriber = new Subscriber(pair.client, version, randomHop()); const reader = subscriber.consume(Path.from("room")).track("video").subscribe({ maxAge, groups }); - const info = await Stream.accept(pair.server); + const info = await Stream.accept(pair.server, version); if (!info) throw new Error("the subscriber never asked for TRACK_INFO"); expect(await info.reader.u53()).toBe(StreamId.Track); await TrackMessage.decode(info.reader, version); await new TrackInfo({ maxAge: 60_000 }).encode(info.writer, version); info.close(); - const sub = await Stream.accept(pair.server); + const sub = await Stream.accept(pair.server, version); if (!sub) throw new Error("the subscriber never subscribed"); expect(await sub.reader.u53()).toBe(StreamId.Subscribe); await Subscribe.decode(sub.reader, version); diff --git a/js/net/src/lite/track.test.ts b/js/net/src/lite/track.test.ts index 6e120243355..ca4d25d44f9 100644 --- a/js/net/src/lite/track.test.ts +++ b/js/net/src/lite/track.test.ts @@ -16,10 +16,11 @@ function concat(chunks: Uint8Array[]): Uint8Array { return out; } -async function bytes(f: (w: Writer) => Promise): Promise { +async function bytes(f: (w: Writer) => Promise, version: Version): Promise { const written: Uint8Array[] = []; const writer = new Writer( new WritableStream({ write: (chunk) => void written.push(new Uint8Array(chunk)) }), + version, ); await f(writer); writer.close(); @@ -33,7 +34,11 @@ test("TrackInfo round-trips on draft-05", async () => { maxAge: 2000, timescale: 90000, }); - const reader = new Reader(undefined, await bytes((w) => info.encode(w, Version.DRAFT_05))); + const reader = new Reader( + undefined, + await bytes((w) => info.encode(w, Version.DRAFT_05), Version.DRAFT_05), + Version.DRAFT_05, + ); const got = await TrackInfo.decode(reader, Version.DRAFT_05); expect(got.priority).toBe(7); expect(got.maxAge).toBe(2000); @@ -42,14 +47,18 @@ test("TrackInfo round-trips on draft-05", async () => { test("TrackInfo defaults match cross-language wire bytes", async () => { const info = new TrackInfo(infoDefaults()); - expect(await bytes((w) => info.encode(w, Version.DRAFT_05))).toEqual( + expect(await bytes((w) => info.encode(w, Version.DRAFT_05), Version.DRAFT_05)).toEqual( new Uint8Array([0x06, 0x00, 0x00, 0x53, 0x88, 0x43, 0xe8]), ); }); test("Track request round-trips on draft-05", async () => { const msg = new Track(Path.from("room"), "video"); - const reader = new Reader(undefined, await bytes((w) => msg.encode(w, Version.DRAFT_05))); + const reader = new Reader( + undefined, + await bytes((w) => msg.encode(w, Version.DRAFT_05), Version.DRAFT_05), + Version.DRAFT_05, + ); const got = await Track.decode(reader, Version.DRAFT_05); expect(got.broadcast).toBe(Path.from("room")); expect(got.track).toBe("video"); @@ -57,7 +66,7 @@ test("Track request round-trips on draft-05", async () => { test("TRACK_INFO is rejected before draft-05", async () => { const info = new TrackInfo({ timescale: 90000 }); - await expect(bytes((w) => info.encode(w, Version.DRAFT_04))).rejects.toThrow(); + await expect(bytes((w) => info.encode(w, Version.DRAFT_04), Version.DRAFT_04)).rejects.toThrow(); }); test("TrackInfo round-trips valid boundary metadata", async () => { @@ -66,7 +75,11 @@ test("TrackInfo round-trips valid boundary metadata", async () => { maxAge: Number.MAX_SAFE_INTEGER, timescale: Number.MAX_SAFE_INTEGER, }); - const reader = new Reader(undefined, await bytes((w) => info.encode(w, Version.DRAFT_05))); + const reader = new Reader( + undefined, + await bytes((w) => info.encode(w, Version.DRAFT_05), Version.DRAFT_05), + Version.DRAFT_05, + ); const got = await TrackInfo.decode(reader, Version.DRAFT_05); expect(got.priority).toBe(255); expect(got.maxAge).toBe(Number.MAX_SAFE_INTEGER); @@ -115,6 +128,7 @@ test("mutated TrackInfo fields emit no bytes on encode", async () => { const written: Uint8Array[] = []; const writer = new Writer( new WritableStream({ write: (chunk) => void written.push(new Uint8Array(chunk)) }), + Version.DRAFT_05, ); await expect(info.encode(writer, Version.DRAFT_05)).rejects.toThrow(RangeError); writer.close(); diff --git a/js/net/src/stream.test.ts b/js/net/src/stream.test.ts index 1c54ff92c81..c2b770f2f3a 100644 --- a/js/net/src/stream.test.ts +++ b/js/net/src/stream.test.ts @@ -11,10 +11,14 @@ import { StreamError, } from "./error.ts"; import { Version } from "./ietf/version.ts"; -import { type Cursor, Reader, Stream, Writer } from "./stream.ts"; +import { Version as Lite } from "./lite/version.ts"; +import { type Cursor, Reader, Stream, type StreamVersion, Writer } from "./stream.ts"; import { TimeoutError } from "./util/timeout.ts"; import { U64 } from "./util/u64.ts"; +// The generic tests below read and write QUIC varints on the moq-lite stream code registry. +const QUIC = Lite.DRAFT_06; + // Helper to create a writable stream that captures written data function createTestWritableStream(): { stream: WritableStream; written: Uint8Array[] } { const written: Uint8Array[] = []; @@ -40,7 +44,7 @@ function concatChunks(chunks: Uint8Array[]): Uint8Array { test("Writer u8", async () => { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, QUIC); await writer.u8(42); await writer.u8(255); @@ -56,7 +60,7 @@ test("Writer u8", async () => { test("Writer u8 refuses out of range values before emitting bytes", async () => { for (const value of [-1, 1.5, 256, Number.NaN, Number.POSITIVE_INFINITY]) { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, QUIC); await expect(writer.u8(value)).rejects.toThrow(RangeError); writer.close(); await writer.closed; @@ -66,7 +70,7 @@ test("Writer u8 refuses out of range values before emitting bytes", async () => test("Writer i32", async () => { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, QUIC); await writer.i32(0); await writer.i32(-1); @@ -87,7 +91,7 @@ test("Writer i32", async () => { test("Writer u53", async () => { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, QUIC); await writer.u53(0); await writer.u53(63); // MAX_U6 @@ -119,7 +123,7 @@ test("Writer u53 refuses unsafe values before emitting bytes", async () => { 2 ** 62 + 1, ]) { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, QUIC); await expect(writer.u53(value)).rejects.toThrow(RangeError); writer.close(); await writer.closed; @@ -129,7 +133,7 @@ test("Writer u53 refuses unsafe values before emitting bytes", async () => { test("Writer string", async () => { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, QUIC); await writer.string("hello"); await writer.string("🎉"); @@ -140,7 +144,7 @@ test("Writer string", async () => { const result = concatChunks(written); // Create a reader to parse the result - const reader = new Reader(undefined, result); + const reader = new Reader(undefined, result, QUIC); const str1 = await reader.string(); const str2 = await reader.string(); @@ -150,14 +154,14 @@ test("Writer string", async () => { }); test("Reader string rejects malformed UTF-8", async () => { - const reader = new Reader(undefined, new Uint8Array([2, 0xc3, 0x28])); + const reader = new Reader(undefined, new Uint8Array([2, 0xc3, 0x28]), QUIC); await expect(reader.string()).rejects.toThrow(); }); test("Reader u8", async () => { const data = new Uint8Array([42, 255, 0, 128]); - const reader = new Reader(undefined, data); + const reader = new Reader(undefined, data, QUIC); expect(await reader.u8()).toBe(42); expect(await reader.u8()).toBe(255); @@ -169,7 +173,7 @@ test("Reader u8", async () => { test("Reader read with exact sizes", async () => { const data = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); - const reader = new Reader(undefined, data); + const reader = new Reader(undefined, data, QUIC); const chunk1 = await reader.read(3); expect(chunk1).toEqual(new Uint8Array([1, 2, 3])); @@ -185,7 +189,7 @@ test("Reader read with exact sizes", async () => { test("Reader read with zero size", async () => { const data = new Uint8Array([1, 2, 3]); - const reader = new Reader(undefined, data); + const reader = new Reader(undefined, data, QUIC); const chunk = await reader.read(0); expect(chunk).toEqual(new Uint8Array([])); @@ -197,7 +201,7 @@ test("Reader read with zero size", async () => { test("Reader readAll", async () => { const data = new Uint8Array([1, 2, 3, 4, 5]); - const reader = new Reader(undefined, data); + const reader = new Reader(undefined, data, QUIC); // Read some data first await reader.read(2); @@ -214,7 +218,7 @@ test("Reader u53 varint decoding", async () => { const testValues = [0, 63, 64, 16383, 16384, 1073741823, 1073741824, Number.MAX_SAFE_INTEGER]; const { stream, written } = createTestWritableStream(); - const testWriter = new Writer(stream); + const testWriter = new Writer(stream, QUIC); for (const value of testValues) { await testWriter.u53(value); @@ -224,7 +228,7 @@ test("Reader u53 varint decoding", async () => { await testWriter.closed; const data = concatChunks(written); - const reader = new Reader(undefined, data); + const reader = new Reader(undefined, data, QUIC); for (const expectedValue of testValues) { const actualValue = await reader.u53(); @@ -241,13 +245,13 @@ test("Reader u53 rejects integers that cannot be represented exactly", async () for (const value of wireValues) { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, QUIC); await writer.u62(value); writer.close(); await writer.closed; // A failed decode consumes nothing; the stream is unusable after it anyway. - const reader = new Reader(undefined, concatChunks(written)); + const reader = new Reader(undefined, concatChunks(written), QUIC); await expect(reader.u53()).rejects.toThrow(`value larger than 53-bits: ${value}`); expect(await reader.done()).toBe(false); } @@ -257,7 +261,7 @@ test("Reader u62 varint decoding", async () => { const testValues = [0n, 63n, 64n, 16383n, 16384n, 1073741823n, 1073741824n, 9007199254740991n]; // MAX_U53 const { stream, written } = createTestWritableStream(); - const testWriter = new Writer(stream); + const testWriter = new Writer(stream, QUIC); for (const value of testValues) { await testWriter.u62(value); @@ -267,7 +271,7 @@ test("Reader u62 varint decoding", async () => { await testWriter.closed; const data = concatChunks(written); - const reader = new Reader(undefined, data); + const reader = new Reader(undefined, data, QUIC); for (const expectedValue of testValues) { const actualValue = await reader.u62(); @@ -281,7 +285,7 @@ test("Reader string decoding", async () => { const testStrings = ["hello", "🎉", "", "world with spaces", "multi\nline\nstring"]; const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, QUIC); for (const str of testStrings) { await writer.string(str); @@ -291,7 +295,7 @@ test("Reader string decoding", async () => { await writer.closed; const data = concatChunks(written); - const reader = new Reader(undefined, data); + const reader = new Reader(undefined, data, QUIC); for (const expectedString of testStrings) { const actualString = await reader.string(); @@ -313,7 +317,7 @@ test("Reader from stream", async () => { }, }); - const reader = new Reader(stream); + const reader = new Reader(stream, undefined, QUIC); // Read all data const result = await reader.readAll(); @@ -332,7 +336,7 @@ test("Reader stream with partial reads", async () => { }, }); - const reader = new Reader(stream); + const reader = new Reader(stream, undefined, QUIC); // Read specific amounts that cross chunk boundaries const first = await reader.read(3); // Should span first two chunks @@ -357,7 +361,7 @@ test("Reader preserves returned views across fills", async () => { controller.close(); }, }); - const reader = new Reader(stream); + const reader = new Reader(stream, undefined, QUIC); const head = await reader.read(1); expect(head).toEqual(new Uint8Array([1])); const joined = await reader.read(3); @@ -376,7 +380,7 @@ test("Reader returns a view of a chunk that already holds the read", async () => controller.close(); }, }); - const reader = new Reader(stream); + const reader = new Reader(stream, undefined, QUIC); const read = await reader.read(3); expect(read.buffer).toBe(chunk.buffer); expect(read).toEqual(new Uint8Array([1, 2, 3])); @@ -390,7 +394,7 @@ test("Reader joins every chunk a read spans", async () => { controller.close(); }, }); - const reader = new Reader(stream); + const reader = new Reader(stream, undefined, QUIC); expect(await reader.u8()).toBe(0); expect(await reader.read(98)).toEqual(Uint8Array.from({ length: 98 }, (_, index) => index + 1)); expect(await reader.done()).toBe(false); @@ -400,13 +404,13 @@ test("Reader joins every chunk a read spans", async () => { test("Reader u53 decodes two-byte stream type prefixes", async () => { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, QUIC); await writer.u53(0x40); writer.close(); await writer.closed; - const reader = new Reader(undefined, concatChunks(written)); + const reader = new Reader(undefined, concatChunks(written), QUIC); expect(await reader.u53()).toBe(0x40); expect(await reader.done()).toBe(true); }); @@ -416,7 +420,7 @@ const sized = (c: Cursor) => c.read(c.u53()); test("Reader tryDecode drains every buffered message, then consumes nothing from a partial one", async () => { let controller!: ReadableStreamDefaultController; - const reader = new Reader(new ReadableStream({ start: (c) => (controller = c) })); + const reader = new Reader(new ReadableStream({ start: (c) => (controller = c) }), undefined, QUIC); controller.enqueue(new Uint8Array([1, 0xa, 2, 0xb, 0xc, 3, 0xd])); expect(await reader.done()).toBe(false); @@ -434,13 +438,13 @@ test("Reader tryDecode drains every buffered message, then consumes nothing from }); test("Reader tryDecode holds only the decode that ran short to the bytes it needs", () => { - const reader = new Reader(undefined, new Uint8Array([2, 0xa])); + const reader = new Reader(undefined, new Uint8Array([2, 0xa]), QUIC); expect(reader.tryDecode(sized)).toBeUndefined(); expect(reader.tryDecode((c) => c.u8())).toBe(2); }); test("Reader decode rejects a stream that ends inside a message", async () => { - const reader = new Reader(undefined, new Uint8Array([3, 0xa])); + const reader = new Reader(undefined, new Uint8Array([3, 0xa]), QUIC); expect(reader.tryDecode(sized)).toBeUndefined(); await expect(reader.decode(sized)).rejects.toThrow("unexpected end of stream"); }); @@ -449,13 +453,13 @@ test("Reader refuses an oversized value even when it is already buffered", async const size = 64 * 1024 * 1024 + 1; const buffer = new Uint8Array(4 + size); buffer.set([0x84, 0x00, 0x00, 0x01]); // the 4-byte varint for size - await expect(new Reader(undefined, buffer).string()).rejects.toThrow("exceeds max size"); - await expect(new Reader(undefined, buffer.subarray(4)).read(size)).rejects.toThrow("exceeds max size"); + await expect(new Reader(undefined, buffer, QUIC).string()).rejects.toThrow("exceeds max size"); + await expect(new Reader(undefined, buffer.subarray(4), QUIC).read(size)).rejects.toThrow("exceeds max size"); }); test("Reader refuses a buffered decode whose fields together exceed the max size", async () => { const half = 32 * 1024 * 1024; - const reader = new Reader(undefined, new Uint8Array(2 * half + 1)); + const reader = new Reader(undefined, new Uint8Array(2 * half + 1), QUIC); await expect(reader.decode((c) => [c.read(half), c.read(half + 1)])).rejects.toThrow("exceeds max size"); }); @@ -477,6 +481,8 @@ test("Reader closed rejects with the decoded reset code", async () => { new ReadableStream({ start: (controller) => controller.error(new Reset(2)), }), + undefined, + QUIC, ); const err = await reader.closed.then( @@ -492,6 +498,7 @@ test("Writer closed rejects with the decoded reset code", async () => { new WritableStream({ start: (controller) => controller.error(new Reset(31)), }), + QUIC, ); const err = await writer.closed.then( @@ -504,7 +511,7 @@ test("Writer closed rejects with the decoded reset code", async () => { test("Writer reset forwards only a stream error code", async () => { const session = new SessionError(SessionCode.Unauthorized); - const sessionWriter = new Writer(new WritableStream()); + const sessionWriter = new Writer(new WritableStream(), QUIC); sessionWriter.reset(session); const sessionResult = await sessionWriter.closed.then( () => undefined, @@ -513,7 +520,7 @@ test("Writer reset forwards only a stream error code", async () => { expect(sessionResult).toBe(session); const stream = new StreamError(StreamCode.DeliveryTimeout); - const streamWriter = new Writer(new WritableStream()); + const streamWriter = new Writer(new WritableStream(), QUIC); streamWriter.reset(stream); const streamResult = await streamWriter.closed.then( () => undefined, @@ -524,7 +531,7 @@ test("Writer reset forwards only a stream error code", async () => { }); test("closed is stable, so racing it per frame does not allocate", async () => { - const reader = new Reader(new ReadableStream()); + const reader = new Reader(new ReadableStream(), undefined, QUIC); expect(reader.closed).toBe(reader.closed); }); @@ -592,7 +599,7 @@ function stalledBidiTransport() { test("open gives up on a peer that never frees a bidi slot", async () => { const { quic, freeSlot, discarded } = stalledBidiTransport(); - await expect(Stream.open(quic, { timeout: EXPIRES_MS })).rejects.toThrow(/timed out/); + await expect(Stream.open(quic, { timeout: EXPIRES_MS, version: QUIC })).rejects.toThrow(/timed out/); freeSlot(); await discarded; @@ -601,7 +608,7 @@ test("open gives up on a peer that never frees a bidi slot", async () => { test("open waits for a bidi slot rather than failing on a busy session", async () => { const { quic, freeSlot } = stalledBidiTransport(); - const opening = Stream.open(quic, { timeout: OUTLASTS_TEST_MS }); + const opening = Stream.open(quic, { timeout: OUTLASTS_TEST_MS, version: QUIC }); expect(await Promise.race([opening.then(() => "opened"), Promise.resolve("waiting")])).toBe("waiting"); freeSlot(); @@ -614,7 +621,7 @@ test("tryOpen gives up on a cancel that settled before the open", async () => { const { quic, freeSlot, aborted } = stalledTransport(); freeSlot(); - expect(await Writer.tryOpen(quic, { cancel: Promise.resolve() })).toBeUndefined(); + expect(await Writer.tryOpen(quic, { cancel: Promise.resolve(), version: QUIC })).toBeUndefined(); await aborted; }); @@ -626,7 +633,7 @@ test("tryOpen gives up when cancelled, resetting a stream that opens afterwards" cancel = resolve; }); - const opening = Writer.tryOpen(quic, { cancel: cancelled }); + const opening = Writer.tryOpen(quic, { cancel: cancelled, version: QUIC }); cancel(); expect(await opening).toBeUndefined(); @@ -642,7 +649,7 @@ test("tryOpen rethrows a rejected cancel, resetting a stream that opens afterwar fail = reject; }); - const opening = Writer.tryOpen(quic, { cancel: cancelled }); + const opening = Writer.tryOpen(quic, { cancel: cancelled, version: QUIC }); fail(new Error("stop sending")); await expect(opening).rejects.toThrow("stop sending"); @@ -655,7 +662,9 @@ test("tryOpen rethrows a rejected cancel, resetting a stream that opens afterwar test("tryOpen gives up when the peer never frees a slot", async () => { const { quic, freeSlot, aborted } = stalledTransport(); - expect(await Writer.tryOpen(quic, { cancel: new Promise(() => {}), timeout: EXPIRES_MS })).toBeUndefined(); + expect( + await Writer.tryOpen(quic, { cancel: new Promise(() => {}), timeout: EXPIRES_MS, version: QUIC }), + ).toBeUndefined(); freeSlot(); await aborted; @@ -664,7 +673,7 @@ test("tryOpen gives up when the peer never frees a slot", async () => { test("tryOpen returns the stream when a slot is available", async () => { const { quic, freeSlot } = stalledTransport(); - const opening = Writer.tryOpen(quic, { cancel: new Promise(() => {}), timeout: OUTLASTS_TEST_MS }); + const opening = Writer.tryOpen(quic, { cancel: new Promise(() => {}), timeout: OUTLASTS_TEST_MS, version: QUIC }); freeSlot(); expect(await opening).toBeInstanceOf(Writer); @@ -680,7 +689,7 @@ test("tryOpen shares one reaction on a cancel reused across opens", async () => const cancel = new Promise(() => {}); const reactions = spyOn(cancel, "then"); for (let i = 0; i < 100; i++) { - expect(await Writer.tryOpen(quic, { cancel })).toBeInstanceOf(Writer); + expect(await Writer.tryOpen(quic, { cancel, version: QUIC })).toBeInstanceOf(Writer); } expect(reactions).toHaveBeenCalledTimes(1); }); @@ -698,10 +707,10 @@ test("open waits for a stream slot instead of rejecting once the peer's limit is }, } as unknown as WebTransport; - await Stream.open(quic, { sendOrder: 7 }); - await Writer.open(quic); + await Stream.open(quic, { sendOrder: 7, version: QUIC }); + await Writer.open(quic, { version: QUIC }); // The one path that opens faster than a peer can retire streams opts out. - await Writer.open(quic, { waitUntilAvailable: false }); + await Writer.open(quic, { waitUntilAvailable: false, version: QUIC }); expect(options).toEqual([ { sendOrder: 7, waitUntilAvailable: true }, @@ -714,7 +723,7 @@ test("open waits for a stream slot instead of rejecting once the peer's limit is // each row says what it costs on a draft that predates the registration. TOO_FAR_BEHIND // arrived in draft-17, and moq-lite's own 48-63 codes are in no draft at all. for (const [version, tooFarBehind] of [ - [undefined, StreamCode.TooFarBehind], + [QUIC, StreamCode.TooFarBehind], [Version.DRAFT_14, StreamCode.Internal], [Version.DRAFT_19, StreamCode.TooFarBehind], [Version.DRAFT_20, StreamCode.TooFarBehind], @@ -723,9 +732,9 @@ for (const [version, tooFarBehind] of [ for (const [reason, expected] of [ [new Lagged(), tooFarBehind], [new Reset(5), tooFarBehind], - [new FrameTooLarge(), version === undefined ? StreamCode.FrameTooLarge : StreamCode.Internal], - [new GroupTooLarge(), version === undefined ? StreamCode.GroupTooLarge : StreamCode.Internal], - [new NotFound("broadcast"), version === undefined ? StreamCode.NotFound : StreamCode.Internal], + [new FrameTooLarge(), version === QUIC ? StreamCode.FrameTooLarge : StreamCode.Internal], + [new GroupTooLarge(), version === QUIC ? StreamCode.GroupTooLarge : StreamCode.Internal], + [new NotFound("broadcast"), version === QUIC ? StreamCode.NotFound : StreamCode.Internal], // Assigned by every draft, so these survive the translation intact. [new TimeoutError("open"), StreamCode.DeliveryTimeout], [new ProtocolViolation("bad message"), StreamCode.SessionClosed], @@ -793,20 +802,69 @@ for (const [version, tooFarBehind] of [ ); const err = await reader.closed.catch((err: unknown) => err); expect(err).toBeInstanceOf(StreamError); - expect((err as StreamError).code).toBe(version === undefined ? StreamCode(70) : StreamCode.Internal); - if (version !== undefined) expect((err as StreamError).message).toContain("70"); + expect((err as StreamError).code).toBe(version === QUIC ? StreamCode(70) : StreamCode.Internal); + if (version !== QUIC) expect((err as StreamError).message).toContain("70"); }); } +async function written(version: Lite, f: (w: Writer) => Promise): Promise { + const { stream, written } = createTestWritableStream(); + const writer = new Writer(stream, version); + await f(writer); + writer.close(); + await writer.closed; + return [...concatChunks(written)]; +} + +test("lite-07 varints count leading ones; lite-06 keeps the QUIC form", async () => { + expect(await written(Lite.DRAFT_06, (w) => w.u53(100))).toEqual([0x40, 0x64]); + expect(await written(Lite.DRAFT_07, (w) => w.u53(100))).toEqual([0x64]); + expect(await written(Lite.DRAFT_07, (w) => w.u62(2n ** 62n - 1n))).toEqual([ + 0xff, 0x3f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, + ]); + + expect(await new Reader(undefined, new Uint8Array([0x40, 0x64]), Lite.DRAFT_06).u53()).toBe(100); + expect(await new Reader(undefined, new Uint8Array([0x80, 0x64]), Lite.DRAFT_07).u53()).toBe(100); + // The 7-byte form, reserved only on draft-17. + const seven = new Uint8Array([0xfd, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd]); + expect(await new Reader(undefined, seven, Lite.DRAFT_07).u62()).toBe(0x1_2345_6789_abcdn); +}); + +test("the varint range follows the version: 64 bits on lite-07, 62 on lite-06", async () => { + const max = 2n ** 64n - 1n; + const wire = await written(Lite.DRAFT_07, (w) => w.u62(max)); + expect(wire).toEqual(Array(9).fill(0xff)); + expect(await new Reader(undefined, Uint8Array.from(wire), Lite.DRAFT_07).u62()).toBe(max); + await expect(written(Lite.DRAFT_06, (w) => w.u62(2n ** 62n))).rejects.toThrow("62-bits"); +}); + +test("a lite-07 stream decodes reset codes with the moq-lite registry", async () => { + // 0x4 is GOING_AWAY on moq-lite but a foreign code on draft-17. + const reset = async (version: StreamVersion) => { + const reader = new Reader( + new ReadableStream({ + start: (controller) => controller.error(new Reset(4)), + }), + undefined, + version, + ); + const err = await reader.closed.then( + () => undefined, + (e: unknown) => e, + ); + return (err as StreamError).code; + }; + expect(await reset(Lite.DRAFT_07)).toBe(StreamCode.GoingAway); + expect(await reset(Version.DRAFT_17)).toBe(StreamCode.Internal); +}); + test("Writer and Reader varint round-trip every size in both formats", async () => { const values = [0n, 63n, 64n, 127n, 128n, 2n ** 14n, 2n ** 21n, 2n ** 28n, 2n ** 30n, 2n ** 32n, 2n ** 35n]; values.push(2n ** 42n, 2n ** 49n, 2n ** 53n, 2n ** 56n, 2n ** 62n - 1n); - for (const version of [undefined, Version.DRAFT_16, Version.DRAFT_17, Version.DRAFT_19]) { + for (const version of [Lite.DRAFT_06, Lite.DRAFT_07, Version.DRAFT_16, Version.DRAFT_17, Version.DRAFT_19]) { // Only leading-ones varints reach past 62 bits. const all = - version === Version.DRAFT_17 || version === Version.DRAFT_19 - ? [...values, 2n ** 62n, 2n ** 64n - 1n] - : values; + version === Lite.DRAFT_06 || version === Version.DRAFT_16 ? values : [...values, 2n ** 62n, 2n ** 64n - 1n]; const { stream, written } = createTestWritableStream(); const writer = new Writer(stream, version); for (const value of all) await writer.varint(U64.fromBigInt(value)); @@ -821,7 +879,7 @@ test("Writer and Reader varint round-trip every size in both formats", async () test("Writer varint refuses a QUIC varint past 62 bits before emitting bytes", async () => { const { stream, written } = createTestWritableStream(); - const writer = new Writer(stream); + const writer = new Writer(stream, Version.DRAFT_16); await expect(writer.varint(U64.fromBigInt(2n ** 62n))).rejects.toThrow(/larger than 62-bits/); await expect(writer.varint(U64.MAX)).rejects.toThrow(/larger than 62-bits/); expect(written).toEqual([]); @@ -830,7 +888,7 @@ test("Writer varint refuses a QUIC varint past 62 bits before emitting bytes", a test("Reader u53 decodes every size in both formats, one byte per chunk", async () => { const values = [0, 63, 64, 127, 128, 16383, 16384, 2 ** 21, 2 ** 28 - 1, 2 ** 28, 2 ** 30 - 1, 2 ** 30]; values.push(2 ** 35, 2 ** 42, 2 ** 49, Number.MAX_SAFE_INTEGER); - for (const version of [undefined, Version.DRAFT_17]) { + for (const version of [Lite.DRAFT_06, Lite.DRAFT_07, Version.DRAFT_17]) { const { stream, written } = createTestWritableStream(); const writer = new Writer(stream, version); for (const value of values) await writer.u53(value); diff --git a/js/net/src/stream.ts b/js/net/src/stream.ts index 47e3d374d55..c2847f395a1 100644 --- a/js/net/src/stream.ts +++ b/js/net/src/stream.ts @@ -2,6 +2,7 @@ import { race } from "@moq/signals"; import { fromTransport, StreamCode, StreamError, toStreamCode, toTransport } from "./error.ts"; import type { IetfVersion } from "./ietf/version.ts"; import { Version } from "./ietf/version.ts"; +import { Version as Lite, type Version as LiteVersion } from "./lite/version.ts"; import { TimeoutError, withTimeout } from "./util/timeout.ts"; import { POW32, toBigInt, toNumber, U64 } from "./util/u64.ts"; import { decodeUtf8 } from "./util/utf8.ts"; @@ -20,7 +21,8 @@ import { // Decode raw transport errors before mapping so they cannot bypass the negotiated // registry. Ordinary errors already send 0 and retain their local identity. -function withCode(reason: unknown, version?: IetfVersion): unknown { +function withCode(reason: unknown, stream: StreamVersion): unknown { + const version = asIetf(stream); const decoded = fromTransport(reason, { version }); const code = toStreamCode(decoded, { version }); return code === StreamCode.Internal && decoded === reason ? reason : toTransport(code, decoded.message); @@ -60,13 +62,59 @@ async function openWithin(opening: Promise, timeout: number, discard: (str } } -function isLeadingOnes(version?: IetfVersion): boolean { - return ( - version !== undefined && - version !== Version.DRAFT_14 && - version !== Version.DRAFT_15 && - version !== Version.DRAFT_16 - ); +/** + * The version a stream's bytes follow: a moq-transport draft or a moq-lite draft. Required on + * every stream so the varint form never defaults silently; a stream opened before negotiation + * names the version its handshake is encoded with. + */ +export type StreamVersion = IetfVersion | LiteVersion; + +const LITE: ReadonlySet = new Set(Object.values(Lite)); + +function isLite(version: StreamVersion): version is LiteVersion { + return LITE.has(version); +} + +/** The moq-transport draft a stream follows, or undefined on moq-lite, whose stream codes are the same on every draft. */ +export function asIetf(version: StreamVersion): IetfVersion | undefined { + return isLite(version) ? undefined : version; +} + +// Every draft newer than these counts leading ones, so a new version falls forward. +function isLeadingOnes(version: StreamVersion): boolean { + switch (version) { + case Version.DRAFT_14: + case Version.DRAFT_15: + case Version.DRAFT_16: + case Lite.DRAFT_01: + case Lite.DRAFT_02: + case Lite.DRAFT_03: + case Lite.DRAFT_04: + case Lite.DRAFT_05: + case Lite.DRAFT_06: + return false; + default: + return true; + } +} + +// Encode `hi`/`lo` into `dst` in the varint form `version` uses: QUIC up to 2^62-1, leading-ones up to 2^64-1. +function encodeTo(dst: ArrayBuffer, hi: number, lo: number, version: StreamVersion): Uint8Array { + let buf: Uint8Array; + if (isLeadingOnes(version)) { + buf = new Uint8Array(dst, 0, lengthLeadingOnes(hi, lo)); + writeLeadingOnes(buf, hi, lo, buf.length); + } else { + buf = new Uint8Array(dst, 0, lengthQuic(hi, lo)); + writeQuic(buf, hi, lo, buf.length); + } + return buf; +} + +/** Encode one varint in the form `version` uses, for a body written outside a {@link Writer}. */ +export function encodeVarint(v: number | bigint, version: StreamVersion): Uint8Array { + const lo = split(v); + return encodeTo(new ArrayBuffer(9), parts.hi, lo, version); } /** @@ -83,8 +131,8 @@ export type SendStream = WritableStream & { sendOrder?: number }; /** Options for opening an outgoing stream. */ export interface OpenOptions { - /** The negotiated IETF version, which selects the varint encoding. */ - version?: IetfVersion; + /** The negotiated version, which selects the varint encoding. */ + version: StreamVersion; /** * The transport send order, where HIGHER values are transmitted first. @@ -125,7 +173,7 @@ export class Stream { constructor(props: { writable: WritableStream; readable: ReadableStream; - version?: IetfVersion; + version: StreamVersion; }); /** Pair halves that were opened separately, as the SETUP exchange does. */ constructor(props: { writer: Writer; reader: Reader }); @@ -134,17 +182,19 @@ export class Stream { readable?: ReadableStream; writer?: Writer; reader?: Reader; - version?: IetfVersion; + version?: StreamVersion; }) { - const writer = props.writer ?? (props.writable && new Writer(props.writable, props.version)); - const reader = props.reader ?? (props.readable && new Reader(props.readable, undefined, props.version)); + const version = props.version; + const writer = props.writer ?? (props.writable && version !== undefined && new Writer(props.writable, version)); + const reader = + props.reader ?? (props.readable && version !== undefined && new Reader(props.readable, undefined, version)); if (!writer || !reader) throw new Error("stream needs both halves"); this.writer = writer; this.reader = reader; } - static async accept(quic: WebTransport, version?: IetfVersion): Promise { + static async accept(quic: WebTransport, version: StreamVersion): Promise { for (;;) { const reader = quic.incomingBidirectionalStreams.getReader() as ReadableStreamDefaultReader; @@ -163,7 +213,7 @@ export class Stream { * @param options - The version its varints encode with, and the send order ranking it * against the session's other streams */ - static async open(quic: WebTransport, options?: OpenOptions): Promise { + static async open(quic: WebTransport, options: OpenOptions): Promise { const { readable, writable } = await openWithin( quic.createBidirectionalStream(sendOptions(options)), options?.timeout ?? OPEN_TIMEOUT_MS, @@ -172,7 +222,7 @@ export class Stream { void stream.readable.cancel().catch(() => void 0); }, ); - return new Stream({ readable, writable, version: options?.version }); + return new Stream({ readable, writable, version: options.version }); } close() { @@ -202,12 +252,16 @@ export class Reader { #closed?: Promise; // The decode that last ran short and how far, so a retry can wait for those bytes. #short?: { decode: (c: Cursor) => unknown; err: Short }; - version?: IetfVersion; + version: StreamVersion; // Either stream or buffer MUST be provided. - constructor(stream: ReadableStream, buffer?: Uint8Array, version?: IetfVersion); - constructor(stream: undefined, buffer: Uint8Array, version?: IetfVersion); - constructor(stream?: ReadableStream, buffer?: Uint8Array, version?: IetfVersion) { + constructor(stream: ReadableStream, buffer: Uint8Array | undefined, version: StreamVersion); + constructor(stream: undefined, buffer: Uint8Array, version: StreamVersion); + constructor( + stream: ReadableStream | undefined, + buffer: Uint8Array | undefined, + version: StreamVersion, + ) { this.#buffer = buffer ?? new Uint8Array(); this.#stream = stream; this.#reader = this.#stream?.getReader(); @@ -223,7 +277,7 @@ export class Reader { // Every read of this stream funnels through here, so decoding the peer's reset code // once is enough to keep the raw transport error out of every caller (and every app). const result = await this.#reader.read().catch((err: unknown) => { - throw fromTransport(err, { version: this.version }); + throw fromTransport(err, { version: asIetf(this.version) }); }); if (result.done) { @@ -397,7 +451,7 @@ export class Reader { // shape depending on which one won. Derived once, so racing it per frame doesn't allocate. get closed(): Promise { this.#closed ??= (this.#reader?.closed ?? Promise.resolve()).catch((err: unknown) => { - throw fromTransport(err, { version: this.version }); + throw fromTransport(err, { version: asIetf(this.version) }); }); return this.#closed; } @@ -424,7 +478,7 @@ const EMPTY = new Short(1); * anything before its last read, must not swallow what it throws, and must read at least a byte. */ export class Cursor { - readonly version?: IetfVersion; + readonly version: StreamVersion; #buffer: Uint8Array; #offset = 0; // Resolved once, since every varint read branches on it. @@ -435,7 +489,7 @@ export class Cursor { // First bytes below this are a varint of at most 4 bytes: 0xc0 for QUIC, 0xf0 for leading-ones. #word: number; - constructor(buffer: Uint8Array, version?: IetfVersion) { + constructor(buffer: Uint8Array, version: StreamVersion) { this.#buffer = buffer; this.version = version; this.#leadingOnes = isLeadingOnes(version); @@ -591,9 +645,9 @@ export class Writer { // Scratch buffer for each primitive write, sized for the longest (a 9-byte leading-ones varint). #scratch: ArrayBuffer; - version?: IetfVersion; + version: StreamVersion; - constructor(stream: WritableStream, version?: IetfVersion) { + constructor(stream: WritableStream, version: StreamVersion) { this.#stream = stream; this.#scratch = new ArrayBuffer(9); this.#writer = this.#stream.getWriter(); @@ -656,22 +710,14 @@ export class Writer { } #varint(hi: number, lo: number): Promise { - let buf: Uint8Array; - if (isLeadingOnes(this.version)) { - buf = new Uint8Array(this.#scratch, 0, lengthLeadingOnes(hi, lo)); - writeLeadingOnes(buf, hi, lo, buf.length); - } else { - buf = new Uint8Array(this.#scratch, 0, lengthQuic(hi, lo)); - writeQuic(buf, hi, lo, buf.length); - } - return this.write(buf); + return this.write(encodeTo(this.#scratch, hi, lo, this.version)); } async write(v: Uint8Array) { // Mirrors Reader.#fill: every write funnels through here, so a STOP_SENDING from the // peer surfaces as a typed code rather than the transport's own error shape. await this.#writer.write(v).catch((err: unknown) => { - throw fromTransport(err, { version: this.version }); + throw fromTransport(err, { version: asIetf(this.version) }); }); } @@ -689,7 +735,7 @@ export class Writer { // typed code it would get from a write. get closed(): Promise { this.#closed ??= this.#writer.closed.catch((err: unknown) => { - throw fromTransport(err, { version: this.version }); + throw fromTransport(err, { version: asIetf(this.version) }); }); return this.#closed; } @@ -704,14 +750,14 @@ export class Writer { * @param options - The version its varints encode with, and the send order ranking it * against the session's other streams */ - static async open(quic: WebTransport, options?: OpenOptions): Promise { + static async open(quic: WebTransport, options: OpenOptions): Promise { const writable = await openWithin( quic.createUnidirectionalStream(sendOptions(options)) as Promise>, options?.timeout ?? OPEN_TIMEOUT_MS, (stream) => void stream.abort().catch(() => void 0), ); - return new Writer(writable, options?.version); + return new Writer(writable, options.version); } /** @@ -771,9 +817,9 @@ function setInt32(dst: ArrayBuffer, v: number): Uint8Array { // Returns the next stream from the connection export class Readers { #reader: ReadableStreamDefaultReader>; - #version?: IetfVersion; + #version: StreamVersion; - constructor(quic: WebTransport, version?: IetfVersion) { + constructor(quic: WebTransport, version: StreamVersion) { this.#reader = quic.incomingUnidirectionalStreams.getReader() as ReadableStreamDefaultReader< ReadableStream >; diff --git a/quest/m1/rs2ts/varint-codec.md b/quest/m1/rs2ts/varint-codec.md index 39557cb31b4..cda246b8ba8 100644 --- a/quest/m1/rs2ts/varint-codec.md +++ b/quest/m1/rs2ts/varint-codec.md @@ -17,7 +17,12 @@ WASM against 6 KB for a hand-carved one. Guidance: -- Keep the 62-bit range; the wire is not bounded to 2^53. +- Widen `VarInt` to the full 64 bits that leading-ones carries on moq-lite-07 + and moq-transport draft-17+, and never bound it to 2^53. QUIC varints still + refuse to encode past 2^62-1. On lite-07 this lets Rust delete the + `BoundsExceeded` arm in the lite dispatch and flips `lite_varint_interop` from + refusal to a round trip. Also revisit `MAX_COST`: costs saturate at 2^62-1 on + every version, but the draft caps them at the largest value a varint carries. - Message types keep a local trait; the primitives become inherent methods on concrete reader and writer types (`varint`, `string`, `bytes`, ...). Make the version a concrete type rather than a generic `V` where possible. diff --git a/rs/moq-net/Cargo.toml b/rs/moq-net/Cargo.toml index 967afb259d1..e4c2c85c5fc 100644 --- a/rs/moq-net/Cargo.toml +++ b/rs/moq-net/Cargo.toml @@ -16,7 +16,7 @@ categories = ["multimedia", "network-programming", "web-programming"] ignored = ["getrandom"] [features] -# Exposes the wire codecs to the `fuzz/` harness and the announce bench through the +# Exposes the wire codecs to the `fuzz/` harness and the announce and varint benches through the # hidden `fuzz` module. Off by default and hidden from the docs. fuzz = [] @@ -75,6 +75,12 @@ name = "announce" harness = false required-features = ["fuzz"] +# Reaches the private lite codec through the hidden `fuzz` module. +[[bench]] +name = "varint" +harness = false +required-features = ["fuzz"] + [[bench]] name = "group" harness = false diff --git a/rs/moq-net/benches/varint.rs b/rs/moq-net/benches/varint.rs new file mode 100644 index 00000000000..01ce78a3978 --- /dev/null +++ b/rs/moq-net/benches/varint.rs @@ -0,0 +1,43 @@ +//! Lite-07 leading-ones varints against lite-06 QUIC varints: the bytes and the CPU to +//! encode and decode what a publisher writes per frame, per group, and per request. +//! +//! The two versions share these layouts, so the only difference is the varint codec. +//! The byte counts print once before the timings. +//! +//! Run with `cargo bench -p moq-net --features fuzz --bench varint`. + +use std::hint::black_box; + +use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main}; +use moq_net::{Version, fuzz::LiteSample}; + +fn versions() -> [(&'static str, Version); 2] { + ["moq-lite-06", "moq-lite-07-wip"].map(|name| (name, name.parse().unwrap())) +} + +fn bench(c: &mut Criterion) { + println!("{:<10} {:>8} {:>8}", "sample", "lite-06", "lite-07"); + for sample in LiteSample::ALL { + let [lite06, lite07] = versions().map(|(_, version)| sample.encode(version).len()); + println!("{:<10} {lite06:>8} {lite07:>8}", format!("{sample:?}")); + } + + let mut group = c.benchmark_group("lite_varint"); + for sample in LiteSample::ALL { + for (name, version) in versions() { + let id = format!("{sample:?}/{name}"); + group.bench_function(BenchmarkId::new("encode", &id), |b| { + b.iter(|| black_box(sample.encode(black_box(version)))) + }); + + let wire = sample.encode(version); + group.bench_function(BenchmarkId::new("decode", &id), |b| { + b.iter(|| black_box(sample.decode(black_box(version), black_box(&wire)))) + }); + } + } + group.finish(); +} + +criterion_group!(benches, bench); +criterion_main!(benches); diff --git a/rs/moq-net/src/coding/varint.rs b/rs/moq-net/src/coding/varint.rs index e51180d531d..08e35cab0fa 100644 --- a/rs/moq-net/src/coding/varint.rs +++ b/rs/moq-net/src/coding/varint.rs @@ -270,7 +270,7 @@ impl VarInt { /// - `1111110x` → 7 bytes, 49 usable bits (draft-18+, INVALID in draft-17 per #1595) /// - `11111110` → 8 bytes, 56 usable bits /// - `11111111` → 9 bytes, 64 usable bits - fn decode_leading_ones(r: &mut R, version: ietf::Version) -> Result { + fn decode_leading_ones(r: &mut R) -> Result { if !r.has_remaining() { return Err(DecodeError::Short); } @@ -341,9 +341,6 @@ impl VarInt { } 6 => { // 1111110x + 6 bytes, 49 bits (draft-18+, INVALID in draft-17 per #1595) - if matches!(version, ietf::Version::Draft17) { - return Err(DecodeError::InvalidValue); - } if r.remaining() < 6 { return Err(DecodeError::Short); } @@ -380,7 +377,7 @@ impl VarInt { /// Always emits the minimal canonical form. Draft-18 also accepts 7-byte form /// (`1111110x`) on decode but we never emit it because the 8-byte form is one byte /// larger but simpler and is universally valid. - fn encode_leading_ones(&self, w: &mut W, _version: ietf::Version) -> Result<(), EncodeError> { + fn encode_leading_ones(&self, w: &mut W) -> Result<(), EncodeError> { let x = self.0; let remaining = w.remaining_mut(); @@ -452,16 +449,39 @@ impl VarInt { use crate::{Version, ietf, lite}; -// All lite versions use QUIC-style varint encoding. +// Lite01-06 use QUIC-style varints; lite-07+ uses leading-ones. Lite-07 is only reached +// through its ALPN, so the codec is known before the first byte of any stream. impl Encode for VarInt { - fn encode(&self, w: &mut W, _: lite::Version) -> Result<(), EncodeError> { - self.encode_quic(w) + fn encode(&self, w: &mut W, version: lite::Version) -> Result<(), EncodeError> { + match version { + lite::Version::Lite01 + | lite::Version::Lite02 + | lite::Version::Lite03 + | lite::Version::Lite04 + | lite::Version::Lite05 + | lite::Version::Lite06 => self.encode_quic(w), + _ => self.encode_leading_ones(w), + } } } impl Decode for VarInt { - fn decode(r: &mut R, _: lite::Version) -> Result { - Self::decode_quic(r) + fn decode(r: &mut R, version: lite::Version) -> Result { + match version { + lite::Version::Lite01 + | lite::Version::Lite02 + | lite::Version::Lite03 + | lite::Version::Lite04 + | lite::Version::Lite05 + | lite::Version::Lite06 => Self::decode_quic(r), + // Lite-07 values span the full 64 bits, but `VarInt` is still 62-bit here, so a + // larger value is a loud decode error, never a truncation. Known limitation, lifted + // when the VarInt codec quest (quest/m1/rs2ts/varint-codec.md) widens `VarInt`. + _ => match Self::decode_leading_ones(r)? { + x if x > Self::MAX => Err(DecodeError::BoundsExceeded), + x => Ok(x), + }, + } } } @@ -470,7 +490,7 @@ impl Encode for VarInt { fn encode(&self, w: &mut W, version: ietf::Version) -> Result<(), EncodeError> { match version { ietf::Version::Draft14 | ietf::Version::Draft15 | ietf::Version::Draft16 => self.encode_quic(w), - _ => self.encode_leading_ones(w, version), + _ => self.encode_leading_ones(w), } } } @@ -479,7 +499,11 @@ impl Decode for VarInt { fn decode(r: &mut R, version: ietf::Version) -> Result { match version { ietf::Version::Draft14 | ietf::Version::Draft15 | ietf::Version::Draft16 => Self::decode_quic(r), - _ => Self::decode_leading_ones(r, version), + // Draft-18 made 1111110x the 7-byte form; draft-17 reserves it (#1595). + ietf::Version::Draft17 if r.chunk().first().is_some_and(|b| b.leading_ones() == 6) => { + Err(DecodeError::InvalidValue) + } + _ => Self::decode_leading_ones(r), } } } @@ -592,7 +616,7 @@ mod tests { for (bytes, expected) in cases { // Test decoding let mut buf = Bytes::from(bytes.to_vec()); - let decoded = VarInt::decode_leading_ones(&mut buf, ietf::Version::Draft17).expect("decode should succeed"); + let decoded = VarInt::decode_leading_ones(&mut buf).expect("decode should succeed"); assert_eq!( decoded.into_inner(), *expected, @@ -607,9 +631,7 @@ mod tests { && (bytes.len() == 1 || *expected != 37) { let mut encoded = Vec::new(); - varint - .encode_leading_ones(&mut encoded, ietf::Version::Draft17) - .expect("encode should succeed"); + varint.encode_leading_ones(&mut encoded).expect("encode should succeed"); assert_eq!(&encoded, bytes, "encode mismatch for value {expected}"); } } @@ -621,7 +643,7 @@ mod tests { let mut buf = Bytes::from_static(&[0xFC]); assert!( matches!( - VarInt::decode_leading_ones(&mut buf, ietf::Version::Draft17), + VarInt::decode(&mut buf, ietf::Version::Draft17), Err(DecodeError::InvalidValue) ), "0xFC should be rejected as invalid on draft-17" @@ -643,7 +665,7 @@ mod tests { let varint = VarInt::from_u64(value).expect("value should be representable as VarInt"); let mut encoded = Vec::new(); varint - .encode_leading_ones(&mut encoded, ietf::Version::Draft17) + .encode_leading_ones(&mut encoded) .expect("leading-ones encode should succeed"); assert_eq!( encoded.len(), @@ -652,8 +674,7 @@ mod tests { ); let mut bytes = Bytes::from(encoded); - let decoded = VarInt::decode_leading_ones(&mut bytes, ietf::Version::Draft17) - .expect("leading-ones decode should succeed"); + let decoded = VarInt::decode_leading_ones(&mut bytes).expect("leading-ones decode should succeed"); assert_eq!(decoded.into_inner(), value, "round-trip mismatch for value {value}"); } } @@ -663,7 +684,7 @@ mod tests { // 1111110x prefix: invalid on draft-17. let bytes = Bytes::from(vec![0xFC, 0, 0, 0, 0, 0, 0]); let mut buf = bytes.clone(); - let err = VarInt::decode_leading_ones(&mut buf, ietf::Version::Draft17).unwrap_err(); + let err = VarInt::decode(&mut buf, ietf::Version::Draft17).unwrap_err(); assert!(matches!(err, DecodeError::InvalidValue)); } @@ -721,6 +742,67 @@ mod tests { } } + fn lite(value: u64, version: lite::Version) -> Vec { + let mut buf = Vec::new(); + VarInt::try_from(value).unwrap().encode(&mut buf, version).unwrap(); + buf + } + + /// Lite-01 through lite-06 keep the QUIC form byte for byte. + #[test] + fn lite06_keeps_quic_varints() { + for version in [lite::Version::Lite01, lite::Version::Lite05, lite::Version::Lite06] { + assert_eq!(lite(63, version), [0x3F]); + assert_eq!(lite(64, version), [0x40, 0x40]); + assert_eq!(lite(16_384, version), [0x80, 0x00, 0x40, 0x00]); + } + } + + /// Lite-07 switches to leading-ones, including at every length boundary. + #[test] + fn lite07_uses_leading_ones() { + let version = lite::Version::Lite07; + let cases: &[(u64, &[u8])] = &[ + (0, &[0x00]), + (127, &[0x7F]), + (128, &[0x80, 0x80]), + ((1 << 14) - 1, &[0xBF, 0xFF]), + (1 << 14, &[0xC0, 0x40, 0x00]), + ((1 << 21) - 1, &[0xDF, 0xFF, 0xFF]), + (1 << 21, &[0xE0, 0x20, 0x00, 0x00]), + ((1 << 56) - 1, &[0xFE, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF]), + (1 << 56, &[0xFF, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]), + ( + VarInt::MAX.into_inner(), + &[0xFF, 0x3F, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF], + ), + ]; + for (value, wire) in cases { + assert_eq!(lite(*value, version), *wire, "encode {value}"); + let mut buf = *wire; + assert_eq!(VarInt::decode(&mut buf, version).unwrap().into_inner(), *value); + assert!(buf.is_empty()); + } + } + + /// The 7-byte `1111110x` form is valid on lite-07, as on draft-18+. + #[test] + fn lite07_accepts_7_byte_varint() { + let mut buf: &[u8] = &[0xFD, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD]; + let decoded = VarInt::decode(&mut buf, lite::Version::Lite07).unwrap(); + assert_eq!(decoded.into_inner(), 0x1_2345_6789_ABCD); + } + + /// Lite-07 values above 2^62-1 are legal on the wire, but the 62-bit `VarInt` cannot + /// hold them yet, so they must fail loud rather than wrap or truncate. + #[test] + fn lite07_values_above_62_bits_fail_loud() { + for wire in [[0xFF, 0x40, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00], [0xFF; 9]] { + let err = VarInt::decode(&mut &wire[..], lite::Version::Lite07).unwrap_err(); + assert!(matches!(err, DecodeError::BoundsExceeded), "{wire:02x?}: {err:?}"); + } + } + #[test] fn draft18_accepts_7_byte_varint() { // Value 0x1234_5678_9ABC encoded as 7-byte leading-ones (1111110x | hi, +6 bytes). @@ -734,7 +816,7 @@ mod tests { bytes.push(((value >> shift) & 0xFF) as u8); } let mut buf = Bytes::from(bytes); - let decoded = VarInt::decode_leading_ones(&mut buf, ietf::Version::Draft18).unwrap(); + let decoded = VarInt::decode(&mut buf, ietf::Version::Draft18).unwrap(); assert_eq!(decoded.into_inner(), value); } } diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index 5fc9f793b63..a7dd0261951 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -252,6 +252,124 @@ pub fn decode_announces(mut data: &[u8], compress: bool) -> Vec { resolved } +/// A varint-heavy lite wire object, as the varint bench times it: what a publisher +/// pays per frame, per group, and per request. +#[derive(Clone, Copy, Debug)] +pub enum LiteSample { + /// A 30 fps video group's FRAME headers: a zigzag timestamp delta in microseconds and + /// a size, 60 of them, led by a 60 KB keyframe. Payloads are left out. + Video, + /// A 50 Hz Opus group's FRAME headers: 50 of 20 ms and 160 bytes. + Audio, + /// A GROUP header, well into a long-running track. + Group, + /// A SUBSCRIBE for a track, the way a player opens one. + Subscribe, + /// A datagram's header, with an empty payload. + Datagram, + /// A SETUP declaring a probe level, a cost, and a random Hop ID. + Setup, +} + +impl LiteSample { + /// Every sample, in the order the bench reports them. + pub const ALL: [Self; 6] = [ + Self::Video, + Self::Audio, + Self::Group, + Self::Subscribe, + Self::Datagram, + Self::Setup, + ]; + + /// The FRAME headers for [`Self::Video`] and [`Self::Audio`], as (delta, size) pairs. + fn frames(self) -> Vec<(i64, u64)> { + match self { + Self::Video => (0..60) + .map(|n| match n { + 0 => (0, 60_000), + n if n % 10 == 0 => (33_333, 17_000), + _ => (33_333, 8_000), + }) + .collect(), + Self::Audio => (0..50).map(|n| (if n == 0 { 0 } else { 20_000 }, 160)).collect(), + _ => Vec::new(), + } + } + + /// Encode this sample at `version`, which must be a moq-lite version. + pub fn encode(self, version: crate::Version) -> Vec { + let version = lite::Version::try_from(version).expect("a moq-lite version"); + let mut buf = Vec::new(); + match self { + Self::Video | Self::Audio => { + for (delta, size) in self.frames() { + VarInt::from_zigzag(delta).unwrap().encode(&mut buf, version).unwrap(); + size.encode(&mut buf, version).unwrap(); + } + } + Self::Group => lite::Group { + subscribe: 3, + sequence: 1_234, + frame_start: 0, + } + .encode(&mut buf, version) + .unwrap(), + Self::Subscribe => lite::Subscribe { + id: 3, + broadcast: Path::new("room/alice"), + track: "video".into(), + priority: 2, + max_age: std::time::Duration::from_secs(10), + start_group: None, + end_group: None, + start_frame: 0, + end_frame: None, + } + .encode(&mut buf, version) + .unwrap(), + Self::Datagram => lite::Datagram { + subscribe: 3, + sequence: 1_234, + timestamp: 1_234_567_890, + payload: bytes::Bytes::new(), + } + .encode(&mut buf, version) + .unwrap(), + Self::Setup => lite::Setup { + probe: lite::ProbeLevel::Report, + cost: Some(1), + hop: Some(crate::Hop::new(0x1d_2c3b_4a59_6877).unwrap()), + ..Default::default() + } + .encode(&mut buf, version) + .unwrap(), + } + buf + } + + /// Decode what [`Self::encode`] wrote at `version`, returning how many objects it read. + pub fn decode(self, version: crate::Version, mut data: &[u8]) -> usize { + let version = lite::Version::try_from(version).expect("a moq-lite version"); + let data = &mut data; + match self { + Self::Video | Self::Audio => { + let mut frames = 0; + while !data.is_empty() { + VarInt::decode(data, version).unwrap(); + u64::decode(data, version).unwrap(); + frames += 1; + } + frames + } + Self::Group => lite::Group::decode(data, version).map(|_| 1).unwrap(), + Self::Subscribe => lite::Subscribe::decode(data, version).map(|_| 1).unwrap(), + Self::Datagram => lite::Datagram::decode(data, version).map(|_| 1).unwrap(), + Self::Setup => lite::Setup::decode(data, version).map(|_| 1).unwrap(), + } + } +} + /// Feed a lite-07 announce stream through the stateful decoder, then check that our /// encoder's compression of what it resolved reads back as the same announcements. /// @@ -324,13 +442,14 @@ pub fn ietf_wire(data: &[u8]) -> bool { /// Decode a varint with whichever codec the selected version uses. /// -/// Byte 0 picks the version, which is the whole point: moq-lite and drafts 14-16 use -/// the QUIC two-bit length tag, while draft-17+ counts leading ones, and the two -/// disagree about which byte sequences are even legal. +/// Byte 0 picks the version, which is the whole point: lite-01 to lite-06 and drafts +/// 14-16 use the QUIC two-bit length tag, while lite-07 and draft-17+ count leading +/// ones, and the two disagree about which byte sequences are even legal. /// -/// The decoded value is deliberately not asserted to be within [`VarInt::MAX`]: the -/// leading-ones form spans the full `u64` by design, so a 9-byte encoding decodes -/// above the 62-bit ceiling and only fails when re-encoded for a QUIC-form version. +/// The decoded value is deliberately not asserted to be within [`VarInt::MAX`]: on the +/// IETF wire the leading-ones form spans the full `u64` by design, so a 9-byte encoding +/// decodes above the 62-bit ceiling. Lite-07 allows the same range, but refuses it at +/// decode until `VarInt` widens to 64 bits. pub fn varint(data: &[u8]) -> bool { let Some((&selector, rest)) = data.split_first() else { return false; diff --git a/rs/moq-net/src/lite/announce.rs b/rs/moq-net/src/lite/announce.rs index 9e460d15302..415fe598d3c 100644 --- a/rs/moq-net/src/lite/announce.rs +++ b/rs/moq-net/src/lite/announce.rs @@ -201,10 +201,13 @@ impl Decode for Cost { if !version.has_route_cost() { return Ok(Cost::UNKNOWN); } - Ok(Cost { + // Costs saturate at 2^62-1 on every version, so a larger one (lite-07's varints + // reach 2^64-1) reads as the ceiling and still forwards to an older peer. + let cost = Cost { warm: u64::decode(buf, version)?, cold: u64::decode(buf, version)?, - }) + }; + Ok(cost.clamped()) } } @@ -783,15 +786,19 @@ mod tests { ); } - // A peer may legally advertise the largest varint there is, and adding this - // link's price to it must not push the result out of range. + // Costs saturate at 2^62-1 on every version, lite-07's 64-bit varints included, so + // charging a link on top of the ceiling still re-encodes for a peer on any version. #[test] fn charged_cost_stays_encodable() { - let mut buf = Vec::new(); - crate::origin::Cost::MAX - .charged(1) - .encode(&mut buf, Version::Lite06) - .expect("a charged cost must stay encodable"); + let cost = Cost::new(u64::MAX).charged(1); + assert_eq!(cost, Cost::new((1 << 62) - 1)); + assert_eq!(Cost::MAX.charged(1), cost); + for version in [Version::Lite06, Version::Lite07] { + let mut buf = Vec::new(); + cost.encode(&mut buf, version) + .expect("a charged cost must stay encodable"); + assert_eq!(Cost::decode(&mut &buf[..], version).unwrap(), cost, "{version}"); + } } #[test] diff --git a/rs/moq-net/src/lite/compress.rs b/rs/moq-net/src/lite/compress.rs index e908e8cbecd..eda17b39163 100644 --- a/rs/moq-net/src/lite/compress.rs +++ b/rs/moq-net/src/lite/compress.rs @@ -581,7 +581,7 @@ mod tests { /// A compressed stream pinned byte for byte: `js/net/src/lite/announce.test.ts` /// decodes the same hex, so a codec change on either side breaks both. - const GOLDEN: &str = "001600000a726f6f6d2f612f63616d000251116222000000000d0102036d696301017333010000020a00010180004444010000010101000d02010162020180005555010000"; + const GOLDEN: &str = "001600000a726f6f6d2f612f63616d00029111a222000000000d0102036d69630101b3330100000209000101c04444010000010101000c020101620201c05555010000"; fn golden() -> Vec { use crate::fuzz::Announced; @@ -604,7 +604,7 @@ mod tests { /// The literal lite-07 stream `js/net` writes for the same announcements, which /// never picks a base. - const JS_LITERAL: &str = "001600000a726f6f6d2f612f63616d000251116222000000001600000a726f6f6d2f612f6d6963000273336222000000020c0000028000444462220000000101010014000006726f6f6d2f620002800055556222000000"; + const JS_LITERAL: &str = "001600000a726f6f6d2f612f63616d00029111a222000000001600000a726f6f6d2f612f6d69630002b333a222000000020b000002c04444a2220000000101010013000006726f6f6d2f620002c05555a222000000"; #[test] fn js_literal_stream_decodes() { diff --git a/rs/moq-net/src/lite/parameters.rs b/rs/moq-net/src/lite/parameters.rs index b0148a6aae3..b7930a6c747 100644 --- a/rs/moq-net/src/lite/parameters.rs +++ b/rs/moq-net/src/lite/parameters.rs @@ -23,20 +23,19 @@ impl Parameters { self.0.get(&id).map(Vec::as_slice) } - /// Set a parameter to a varint value, replacing any existing entry. - pub fn set_varint(&mut self, id: u64, value: u64) { - let mut buf = Vec::new(); - // Infallible: writing into a Vec never runs short. - value.encode(&mut buf, Version::Lite05).expect("varint encode into Vec"); - self.0.insert(id, buf); + /// Set a parameter to a varint value in `version`'s encoding, replacing any existing entry. + pub fn set_varint(&mut self, id: u64, value: u64, version: Version) -> Result<(), EncodeError> { + self.0.insert(id, value.encode_bytes(version)?.to_vec()); + Ok(()) } - /// Decode a parameter as a single varint, if present. Errors if trailing bytes remain. - pub fn get_varint(&self, id: u64) -> Result, DecodeError> { + /// Decode a parameter as a single varint in `version`'s encoding, if present. Errors if + /// trailing bytes remain. + pub fn get_varint(&self, id: u64, version: Version) -> Result, DecodeError> { let Some(mut bytes) = self.0.get(&id).map(Vec::as_slice) else { return Ok(None); }; - let value = u64::decode(&mut bytes, Version::Lite05)?; + let value = u64::decode(&mut bytes, version)?; if !bytes.is_empty() { return Err(DecodeError::Long); } diff --git a/rs/moq-net/src/lite/setup.rs b/rs/moq-net/src/lite/setup.rs index c3868614e9e..53810df0476 100644 --- a/rs/moq-net/src/lite/setup.rs +++ b/rs/moq-net/src/lite/setup.rs @@ -194,7 +194,7 @@ impl Message for Setup { let params = Parameters::decode(r, version)?; let probe = params - .get_varint(PARAM_PROBE)? + .get_varint(PARAM_PROBE, version)? .map(ProbeLevel::from_code) .unwrap_or_default(); let path = match params.get_bytes(PARAM_PATH) { @@ -205,11 +205,13 @@ impl Message for Setup { ), None => None, }; - let role = params.get_varint(PARAM_ROLE)?.and_then(Role::from_code); - let cost = params.get_varint(PARAM_COST)?; + let role = params.get_varint(PARAM_ROLE, version)?.and_then(Role::from_code); + let cost = params.get_varint(PARAM_COST, version)?; // 0 is legal on the wire but carries no identity (it can't be excluded), // so it decodes as "not declared" rather than an error. - let hop = params.get_varint(PARAM_HOP)?.and_then(|id| crate::Hop::new(id).ok()); + let hop = params + .get_varint(PARAM_HOP, version)? + .and_then(|id| crate::Hop::new(id).ok()); Ok(Self { probe, @@ -228,7 +230,7 @@ impl Message for Setup { let mut params = Parameters::default(); // None is the wire default, so omit it to keep the message empty when nothing is set. if self.probe != ProbeLevel::None { - params.set_varint(PARAM_PROBE, self.probe.to_code()); + params.set_varint(PARAM_PROBE, self.probe.to_code(), version)?; } if let Some(path) = &self.path { params.set_bytes(PARAM_PATH, path.as_bytes().to_vec()); @@ -236,13 +238,13 @@ impl Message for Setup { // Bidirectional is the wire default (absence of the parameter), so only a // directional role is encoded. if let Some(role) = self.role { - params.set_varint(PARAM_ROLE, role.to_code()); + params.set_varint(PARAM_ROLE, role.to_code(), version)?; } if let Some(cost) = self.cost { - params.set_varint(PARAM_COST, cost); + params.set_varint(PARAM_COST, cost, version)?; } if let Some(hop) = self.hop { - params.set_varint(PARAM_HOP, hop.id()); + params.set_varint(PARAM_HOP, hop.id(), version)?; } params.encode(w, version) @@ -365,6 +367,25 @@ mod tests { } } + /// Parameter values follow the session's varint codec, not a fixed one: a value that + /// takes the two-byte QUIC form on lite-06 fits one leading-ones byte on lite-07. + #[test] + fn parameter_values_use_the_version_codec() { + let msg = Setup { + cost: Some(100), + ..Default::default() + }; + for (version, wire) in [ + (Version::Lite06, &[0x05, 0x01, 0x04, 0x02, 0x40, 0x64][..]), + (Version::Lite07, &[0x04, 0x01, 0x04, 0x01, 0x64][..]), + ] { + let mut buf = Vec::new(); + msg.encode(&mut buf, version).unwrap(); + assert_eq!(buf, wire, "{version}"); + assert_eq!(Setup::decode(&mut &buf[..], version).unwrap(), msg, "{version}"); + } + } + /// Never emit a SETUP our own receiver would refuse. #[test] fn encode_enforces_the_setup_limit() { @@ -415,7 +436,7 @@ mod tests { let version = Version::Lite05; let mut params = Parameters::default(); - params.set_varint(super::PARAM_HOP, 0); + params.set_varint(super::PARAM_HOP, 0, version).unwrap(); let mut body = bytes::BytesMut::new(); params.encode(&mut body, version).unwrap(); // Frame the body with the Message Length prefix `Setup::decode` expects. @@ -455,7 +476,7 @@ mod tests { // Frame a SETUP message carrying an unknown probe level (99) by hand: the // parameters body, prefixed with its length (the lite Message size prefix). let mut params = Parameters::default(); - params.set_varint(PARAM_PROBE, 99); + params.set_varint(PARAM_PROBE, 99, Version::Lite05).unwrap(); let mut body = Vec::new(); params.encode(&mut body, Version::Lite05).unwrap(); @@ -485,7 +506,7 @@ mod tests { // server. The draft mandates this fallback. for code in [0u64, 9, 250] { let mut params = Parameters::default(); - params.set_varint(PARAM_ROLE, code); + params.set_varint(PARAM_ROLE, code, Version::Lite05).unwrap(); let mut body = Vec::new(); params.encode(&mut body, Version::Lite05).unwrap(); diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 1aef8cf8ba2..2758b39347f 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -36,7 +36,7 @@ use crate::{ /// on the wire, names nobody, and marks the chain anonymous for route selection. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct Hop { - /// 62-bit identifier. Encoded as a QUIC varint on the wire. + /// 62-bit identifier, so it fits a varint on every wire version. id: u64, } @@ -384,7 +384,8 @@ where /// /// The ceiling is the wire's, not the model's: lite-06 carries each cost as a QUIC /// varint, which tops out at 2^62-1, so a larger value could be selected on but -/// never forwarded. +/// never forwarded. It applies on every version, lite-07's 64-bit varints included, +/// so a cost stays forwardable to a QUIC-varint version. const MAX_COST: u64 = (1 << 62) - 1; /// What pulling content via a route costs, in two magnitudes that accumulate diff --git a/rs/moq-net/src/test_interop.rs b/rs/moq-net/src/test_interop.rs index 24d3d03abee..5b12c04544e 100644 --- a/rs/moq-net/src/test_interop.rs +++ b/rs/moq-net/src/test_interop.rs @@ -1,8 +1,8 @@ //! Bytes cross the language boundary to a Bun script under `test/interop`: subscription -//! responses for subscribers on a mock transport, and varint encodings. +//! responses for subscribers on a mock transport, varint encodings, and moq-lite messages. use crate::coding::{Decode, Encode, VarInt}; -use crate::ietf; +use crate::{ietf, lite}; // Runs a script with a JSON argument, returning its stdout. fn bun(script: &str, input: serde_json::Value) -> Vec { @@ -68,3 +68,106 @@ fn varint_interop() { assert!(buf.is_empty()); } } + +/// Every leading-ones length boundary, plus the JS safe-integer edge and the 62-bit ceiling. +fn lite_values() -> Vec { + let mut values = vec![0]; + for bits in [6, 7, 14, 21, 28, 30, 35, 42, 49, 53, 56] { + values.extend([(1u64 << bits) - 1, 1 << bits]); + } + values.push(VarInt::MAX.into_inner()); + values +} + +/// One GROUP header and its frames, as a publisher writes them: a zigzag timestamp delta, +/// the payload size, then the payload. +fn lite_group(version: lite::Version) -> Vec { + let mut buf = Vec::new(); + let header = lite::Group { + subscribe: 5, + sequence: 1 << 20, + frame_start: 200, + }; + header.encode(&mut buf, version).unwrap(); + for (delta, size) in [(0i64, 10usize), (33_333, 300), (-1_000, 20_000), (1 << 40, 1)] { + VarInt::from_zigzag(delta).unwrap().encode(&mut buf, version).unwrap(); + size.encode(&mut buf, version).unwrap(); + buf.extend(std::iter::repeat_n(0xAB, size)); + } + buf +} + +#[derive(serde::Deserialize)] +struct Echo { + values: Vec, + varints: Vec, + setup: Vec, + datagram: Vec, + group: Vec, + beyond: Vec, +} + +/// JS decodes what Rust encodes back to the same values, and its own encoding of those +/// values is byte for byte Rust's, on lite-06 (QUIC) and lite-07 (leading-ones). +/// +/// Past 2^62-1 the range is per version. JS writes lite-07's 64-bit values, which Rust +/// must refuse with a decode error until its `VarInt` widens; on lite-06 JS refuses them. +#[test] +#[ignore = "requires Bun; run by just test interop"] +fn lite_varint_interop() { + let values = lite_values(); + for version in [lite::Version::Lite06, lite::Version::Lite07] { + let mut varints = Vec::new(); + for value in &values { + value.encode(&mut varints, version).unwrap(); + } + + let setup = lite::Setup { + hop: Some(crate::Hop::new(VarInt::MAX.into_inner()).unwrap()), + ..Default::default() + } + .encode_bytes(version) + .unwrap(); + + let datagram = lite::Datagram { + subscribe: (1 << 40) + 1, + sequence: 300, + timestamp: (1 << 50) + 5, + payload: bytes::Bytes::from_static(b"x"), + } + .encode_bytes(version) + .unwrap(); + + let group = lite_group(version); + + let input = serde_json::json!({ + "version": crate::Version::from(version).alpn(), + "values": values.len(), + "varints": varints, + "setup": setup.to_vec(), + "datagram": datagram.to_vec(), + "group": group, + }); + let echo: Echo = serde_json::from_slice(&bun("lite-varint.ts", input)).expect("JS returned its encodings"); + + let decoded: Vec = echo.values.iter().map(|v| v.parse().unwrap()).collect(); + assert_eq!(decoded, values, "{version}: JS decoded different values"); + assert_eq!(echo.varints, varints, "{version}: JS encoded the values differently"); + assert_eq!(echo.setup, setup, "{version}: SETUP"); + assert_eq!(echo.datagram, datagram, "{version}: datagram"); + assert_eq!(echo.group, group, "{version}: group"); + + match version { + lite::Version::Lite07 => { + let mut expected = vec![0xFF, 0x40, 0, 0, 0, 0, 0, 0, 0]; + expected.extend([0xFF; 9]); + assert_eq!(echo.beyond, expected, "{version}: JS's 64-bit encodings"); + for wire in echo.beyond.chunks(9) { + let err = VarInt::decode(&mut &wire[..], version).unwrap_err(); + assert!(matches!(err, crate::coding::DecodeError::BoundsExceeded), "{err:?}"); + } + } + _ => assert!(echo.beyond.is_empty(), "{version}: JS wrote a value past 2^62-1"), + } + } +} diff --git a/test/interop/README.md b/test/interop/README.md index 0a0a5c1d866..3d961b65ad7 100644 --- a/test/interop/README.md +++ b/test/interop/README.md @@ -206,3 +206,10 @@ hands moq-net's QUIC and leading-ones encodings of each varint size boundary `varint.ts`. That script decodes them into js/net's `U64`, checks its `number` conversion, and returns js/net's own encodings, which Rust requires to match byte for byte and decode back to the same value. + +`lite_varint_interop` runs next to it and does the same through moq-lite's +version dispatch: `lite-varint.ts` decodes Rust's lite-06 (QUIC) and lite-07 +(leading-ones) varints, a SETUP carrying a 62-bit Hop ID, a datagram, and a +GROUP stream with frames, and re-encodes them byte for byte. Past 2^62-1 the +range is per version: JS writes lite-07's 64-bit values, which Rust must refuse +with a decode error until its `VarInt` widens, and JS refuses them on lite-06. diff --git a/test/interop/bare-fin.ts b/test/interop/bare-fin.ts index fc899157e19..96db7ddce2a 100644 --- a/test/interop/bare-fin.ts +++ b/test/interop/bare-fin.ts @@ -21,6 +21,13 @@ import type { Subscriber as TrackSubscriber } from "../../js/net/src/track.ts"; console.debug = console.error; const input: { version: string; started: boolean; clean: boolean; responses: number[] } = JSON.parse(process.argv[2]); const pair = createMockTransportPair(input.version); +const path = Path.from("room"); +const lite: Record = { + "moq-lite-05": LiteVersion.DRAFT_05, + "moq-lite-06": LiteVersion.DRAFT_06, + "moq-lite-07-wip": LiteVersion.DRAFT_07, +}; +const version = lite[input.version]; const bytes: number[] = []; const output = new Writer( new WritableStream({ @@ -28,26 +35,20 @@ const output = new Writer( bytes.push(...chunk); }, }), + version ?? IetfVersion.DRAFT_19, ); -const path = Path.from("room"); -const lite: Record = { - "moq-lite-05": LiteVersion.DRAFT_05, - "moq-lite-06": LiteVersion.DRAFT_06, - "moq-lite-07-wip": LiteVersion.DRAFT_07, -}; -const version = lite[input.version]; let reader: TrackSubscriber; let peer: Stream | undefined; if (version !== undefined) { const subscriber = new LiteSubscriber(pair.client, version, randomHop()); reader = subscriber.consume(path).track("video").subscribe(); - const info = await Stream.accept(pair.server); + const info = await Stream.accept(pair.server, version); assert(info); assert.equal(await info.reader.u53(), StreamId.Track); await Track.decode(info.reader, version); await new TrackInfo({}).encode(info.writer, version); info.close(); - peer = await Stream.accept(pair.server); + peer = await Stream.accept(pair.server, version); assert(peer); assert.equal(await peer.reader.u53(), StreamId.Subscribe); await Subscribe.decode(peer.reader, version); diff --git a/test/interop/lite-varint.ts b/test/interop/lite-varint.ts new file mode 100644 index 00000000000..fcf72b92117 --- /dev/null +++ b/test/interop/lite-varint.ts @@ -0,0 +1,98 @@ +/** Decode Rust's lite varints and messages, then echo JS's own encoding of them back. */ +import assert from "node:assert/strict"; +import { Datagram } from "../../js/net/src/lite/datagram.ts"; +import { frameDecoder, Group } from "../../js/net/src/lite/group.ts"; +import { Setup } from "../../js/net/src/lite/setup.ts"; +import { Version } from "../../js/net/src/lite/version.ts"; +import { Reader, Writer } from "../../js/net/src/stream.ts"; + +const input: { + version: string; + values: number; + varints: number[]; + setup: number[]; + datagram: number[]; + group: number[]; +} = JSON.parse(process.argv[2]); + +const versions: Record = { + "moq-lite-06": Version.DRAFT_06, + "moq-lite-07-wip": Version.DRAFT_07, +}; +const version = versions[input.version]; +assert(version !== undefined, `unknown version ${input.version}`); + +const reader = (bytes: number[]) => new Reader(undefined, Uint8Array.from(bytes), version); + +// Collects whatever `f` writes with a Writer on this version. +async function write(f: (w: Writer) => Promise): Promise { + const out: number[] = []; + const w = new Writer(new WritableStream({ write: (chunk) => void out.push(...chunk) }), version); + await f(w); + w.close(); + await w.closed; + return out; +} + +// Varints: decode every value Rust wrote, then write them back. +const r = reader(input.varints); +const values: bigint[] = []; +for (let i = 0; i < input.values; i++) values.push(await r.u62()); +assert(await r.done(), "trailing varint bytes"); +const varints = await write(async (w) => { + for (const v of values) await w.u62(v); +}); + +// Past 2^62-1 the range is per version: lite-07 carries the full 64 bits, which JS writes and +// reads back and Rust (62-bit until its VarInt widens) must refuse loudly; lite-06's QUIC form +// cannot express it, so JS refuses to write it, as Rust does. +const huge = [1n << 62n, (1n << 64n) - 1n]; +let beyond: number[] = []; +if (version === Version.DRAFT_07) { + beyond = await write(async (w) => { + for (const v of huge) await w.u62(v); + }); + const back = reader(beyond); + for (const v of huge) assert.equal(await back.u62(), v); +} else { + for (const v of huge) await assert.rejects(write((w) => w.u62(v))); +} + +const setup = await Setup.decode(reader(input.setup), version); +const setupBytes = await write((w) => setup.encode(w, version)); + +const datagram = await Datagram.decode(Uint8Array.from(input.datagram), version); +const datagramBytes = [...datagram.encode(version)]; + +// A GROUP header, then frames until the stream ends. +const g = reader(input.group); +const group = await Group.decode(g, version); +const decode = frameDecoder(1_000_000); +const frames: { timestamp: bigint; payload: Uint8Array }[] = []; +for (;;) { + const frame = await g.decodeMaybe(decode); + if (!frame) break; + frames.push({ timestamp: BigInt(frame.timestamp.value), payload: frame.payload }); +} +const zigzag = (d: bigint) => (d << 1n) ^ (d >> 63n); +const groupBytes = await write(async (w) => { + await group.encode(w, version); + let prev = 0n; + for (const { timestamp, payload } of frames) { + await w.u62(zigzag(timestamp - prev)); + prev = timestamp; + await w.u53(payload.byteLength); + await w.write(payload); + } +}); + +console.log( + JSON.stringify({ + values: values.map((v) => v.toString()), + varints, + setup: setupBytes, + datagram: datagramBytes, + group: groupBytes, + beyond, + }), +); diff --git a/test/interop/varint.ts b/test/interop/varint.ts index 464a34b5f00..5a4689de12a 100644 --- a/test/interop/varint.ts +++ b/test/interop/varint.ts @@ -7,7 +7,7 @@ import { U64 } from "../../js/net/src/util/u64.ts"; // Each value is a decimal string, since JSON numbers round past 2^53. const input: { values: string[]; quic: number[][]; leadingOnes: number[][] } = JSON.parse(process.argv[2]); -async function encode(v: U64, version?: Version): Promise { +async function encode(v: U64, version: Version): Promise { const bytes: number[] = []; const writer = new Writer(new WritableStream({ write: (chunk) => void bytes.push(...chunk) }), version); await writer.varint(v); @@ -16,7 +16,7 @@ async function encode(v: U64, version?: Version): Promise { return bytes; } -async function decode(bytes: number[], version?: Version): Promise { +async function decode(bytes: number[], version: Version): Promise { const reader = new Reader(undefined, new Uint8Array(bytes), version); const v = await reader.varint(); assert(await reader.done(), `trailing bytes after ${v}`); @@ -27,7 +27,7 @@ const output: { quic: number[][]; leadingOnes: number[][] } = { quic: [], leadin for (const [i, value] of input.values.entries()) { const expected = U64.fromBigInt(BigInt(value)); for (const [format, version] of [ - ["quic", undefined], + ["quic", Version.DRAFT_16], ["leadingOnes", Version.DRAFT_17], ] as const) { const decoded = await decode(input[format][i], version); diff --git a/test/justfile b/test/justfile index 2f3bc271f95..d98acad97df 100644 --- a/test/justfile +++ b/test/justfile @@ -38,7 +38,8 @@ harness: # client, and the GStreamer moqsrc plugin). --timeout 30 gives headless Chromium # cold-start headroom. Other flags pass through, e.g. # `just test interop --publishers rust,python --subscribers rust,c`. -# Both runs first check js/net's varints against moq-net's encoder at every size boundary. +# Both runs first check js/net's varints against moq-net's encoder at every size boundary, +# and on lite-06/07 messages (the filter also matches `lite_varint_interop`). interop *args: #!/usr/bin/env bash set -euo pipefail From 6dc9ec749340248bf9c9079cddec810b586e7342 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 08:32:51 -0700 Subject: [PATCH 104/128] quest(m1): plan #4456, #4508, #4581, #4582 (#4587) Co-authored-by: Claude Opus 5.5 --- quest/m1/README.md | 3 ++ quest/m1/android-logcat.md | 41 +++++++++++++++ quest/m1/broadcast-epoch/README.md | 1 + quest/m1/broadcast-epoch/gateways.md | 4 ++ quest/m1/broadcast-epoch/ts-restart.md | 52 +++++++++++++++++++ quest/m1/close-tail.md | 69 ++++++++++++++++++++++++++ quest/m1/track-tail-interop.md | 1 + quest/m1/ts-damaged-units.md | 60 ++++++++++++++++++++++ 8 files changed, 231 insertions(+) create mode 100644 quest/m1/android-logcat.md create mode 100644 quest/m1/broadcast-epoch/ts-restart.md create mode 100644 quest/m1/close-tail.md create mode 100644 quest/m1/ts-damaged-units.md diff --git a/quest/m1/README.md b/quest/m1/README.md index b560c4d5831..79e58213c6b 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -27,8 +27,10 @@ QUIC studies there on that rule. - [Merge queue](/quest/m1/merge-queue.md) - the required checks run on `merge_group`, so a stale green check can no longer break main - [Binding audio delay](/quest/m1/binding-surface.md) - moq-ffi and every wrapper configure and observe audio playout delay - [FFI shape](/quest/m1/ffi-shape/README.md) - the bindings mirror Rust's layers: net at the root, then media, json, flate, audio, and video namespaces built from the handle below +- [Android logcat](/quest/m1/android-logcat.md) - on dev, Android builds always log to logcat and the `android-logcat` feature is gone - [Raw stream codes](/quest/m1/raw-stream-codes.md) - raw QUIC stream resets and stops carry the application's code, not an HTTP/3-mapped one - [IETF drain before close](/quest/m1/ietf-drain-before-close.md) - moq-transport sessions deliver finished tracks before a graceful close, as moq-lite does +- [Close waits for the tail](/quest/m1/close-tail.md) - on lite-07, `close()` returns `Ok` only after each subscriber FINs its Subscribe Stream, having read the track to its end - [Demo serve-hls renditions](/quest/m1/serve-hls-renditions.md) - `just pub serve-hls` serves 720p and 144p instead of two 256-wide copies - [moq play drain tail](/quest/m1/play-drain-tail.md) - retired renditions and finite tracks play their last 10 ms of audio - [WebTransport close upstream](/quest/m1/wt-close-upstream.md) - web-transport-moq delivers the close capsule itself, and moq-tokio's `CLOSE_LINGER` is deleted @@ -47,6 +49,7 @@ QUIC studies there on that rule. - [Legacy end overshoot](/quest/m1/legacy-end-overshoot.md) - browser playback survives a group that starts inside the previous group's estimated end - [Wire compatibility](/quest/m1/wire-compat.md) - a nightly run tests this checkout against the last published release for tokens, session wire, and catalog/container - [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) - `import ts` reads a PAT or PMT that spans packets or follows a nonzero pointer_field instead of aborting, and one corrupted section costs a repetition and a counted `CRC_error`, not the import +- [TS damaged units](/quest/m1/ts-damaged-units.md) - one malformed PES or access unit is dropped, counted as `damaged`, and resynced at the next keyframe instead of ending the import - [RTMP interleaving](/quest/m1/rtmp-interleaving.md) - isolate partial messages before optimizing assembly copies - [TS stats module](/quest/m1/ts-stats-module.md) - on dev, the TS stats types move under `ts::stats` as `Snapshot` and `Stream`, with an owned `track` - [Same-hop importers](/quest/m1/hop-aligned-import.md) - importers sharing a `--hop` and fed one stream publish identical groups and timestamps, so failover survives diff --git a/quest/m1/android-logcat.md b/quest/m1/android-logcat.md new file mode 100644 index 00000000000..233f09e880f --- /dev/null +++ b/quest/m1/android-logcat.md @@ -0,0 +1,41 @@ +# [XS] Android logs always go to logcat + +## Goal + +On dev, `moq_tokio::Log::init` sends logs to logcat on every Android build, so +the published Kotlin and Dart bindings (and libmoq) stop losing every Rust log +to stderr, which Android app processes discard. The `android-logcat` Cargo +feature is gone from `moq-tokio` and `moq-ffi`. + +## Plan + +Today the logcat layer in `rs/moq-tokio/src/log.rs` is gated on +`all(target_os = "android", feature = "android-logcat")`, and no shipped build +enables the feature: libmoq has no `[features]`, and `rs/moq-ffi/build.sh`, the +Dart build hook, and the release workflows build Android without it. The +published `dev.moq:moq-ffi-android` 0.4.8 does not link `liblog`. + +Decided (maintainer, 2026-09-30): gate the layer on `target_os = "android"` +alone and delete the feature, rather than wire it through every build, so no +Android consumer has to know to turn it on. Logging stays opt-in at runtime, +since `Log::init` runs only when the app calls it. Removing a feature from +published crates is a break, so this targets dev; no no-op feature is kept. + +- `tracing-android` becomes a plain dependency under the existing + `cfg(target_os = "android")` target table in `rs/moq-tokio/Cargo.toml`; it + must stay target-gated because `android_log-sys` links `liblog` + unconditionally. +- Fix the `Log::init` doc comment, which already claims logcat. +- Leave the `rs/moq-native` tombstone alone. +- Regression check: the Android CI workflow builds moq-ffi for one Android + target and asserts the `.so` imports `__android_log_*`. + +The reporter ([#4456](https://github.com/moq-dev/moq/issues/4456)) has this +working locally and offered the PR. + +Public API: breaking on dev, the `android-logcat` feature is removed from +`moq-tokio` and `moq-ffi`. Wire: none. + +## Closes + +- [#4456](https://github.com/moq-dev/moq/issues/4456) - Rust logs never reach logcat on Android diff --git a/quest/m1/broadcast-epoch/README.md b/quest/m1/broadcast-epoch/README.md index 96a0172d3e7..f32738ce2b1 100644 --- a/quest/m1/broadcast-epoch/README.md +++ b/quest/m1/broadcast-epoch/README.md @@ -61,5 +61,6 @@ This README owns: - [Origin](/quest/m1/broadcast-epoch/origin.md) - moq-net publish mints an epoch, consumers follow the newest live one, and bare requests resolve to it on every version - [Apps](/quest/m1/broadcast-epoch/apps.md) - moq-cli, the browser publish and watch components, and demo/web publish under epochs and play bare names - [Gateways](/quest/m1/broadcast-epoch/gateways.md) - RTMP, SRT, and WHIP ingest mint an epoch per incoming connection, so an encoder reconnect is a clean takeover +- [TS restart](/quest/m1/broadcast-epoch/ts-restart.md) - on dev, a signalled backward TS discontinuity finishes the broadcast and continues the same input under a fresh epoch - [Bindings](/quest/m1/broadcast-epoch/bindings.md) - moq-ffi and every wrapper expose the epoch and inherit the default - [GStreamer and OBS](/quest/m1/broadcast-epoch/gst-obs.md) - moqsink and the OBS plugin publish each run under a fresh epoch diff --git a/quest/m1/broadcast-epoch/gateways.md b/quest/m1/broadcast-epoch/gateways.md index 89a3df5c853..0b0f059aa5b 100644 --- a/quest/m1/broadcast-epoch/gateways.md +++ b/quest/m1/broadcast-epoch/gateways.md @@ -17,3 +17,7 @@ describes ingest paths. ## Required - [Origin](/quest/m1/broadcast-epoch/origin.md) - the publish default + +## Related + +- [TS restart](/quest/m1/broadcast-epoch/ts-restart.md) - a signalled restart inside one connection, which this quest's per-connection epoch does not cover diff --git a/quest/m1/broadcast-epoch/ts-restart.md b/quest/m1/broadcast-epoch/ts-restart.md new file mode 100644 index 00000000000..2e438ff31b6 --- /dev/null +++ b/quest/m1/broadcast-epoch/ts-restart.md @@ -0,0 +1,52 @@ +# [M] A signalled TS restart continues as a new epoch + +## Goal + +On dev, when a TS feed rewinds its time base and signals it +(`discontinuity_indicator` on the PCR PID, ISO/IEC 13818-1 2.4.3.5), +`moq import ts` and `moq-srt` finish the current broadcast cleanly and publish +the rest of the same input as a new broadcast under a fresh epoch, in the same +process and connection. This covers an encoder restart or source switch behind +a gateway that keeps its connection up, and a looping playout server, none of +which makes a new connection for [Gateways](/quest/m1/broadcast-epoch/gateways.md) +to turn into an epoch. An unsignalled rewind stays fatal, as #4543 decided. + +## Plan + +Since #4543 (on dev), every rewind ends the import with `TimestampRewind` from +`Producer::write`; the importer already reads the flag in `timebase_break`, +and a flagged forward jump publishes break markers and carries on. + +Decided (maintainer, 2026-09-30): + +- A rewind is new content, so it is always a new broadcast at a new epoch + path, never a continuation of the old name. Viewers of the bare name follow + it through [Origin](/quest/m1/broadcast-epoch/origin.md). +- `decode` stops at the flagged rewind and reports it. The caller finishes the + old broadcast (a clean end, not an abort, so its viewers read to its end), + publishes a new broadcast at a fresh epoch path, and calls + `import.restart(broadcast)`. The importer carries over only the PAT/PMT + layout and the bytes it has not consumed, so there is no wait for the next + PSI repetition; tracks, groups, and timestamps start fresh. `ts::Programs` + does this per program. Returning unconsumed bytes to a fresh `Import` was + rejected for the PSI wait, and letting the importer publish its own + broadcast was rejected for coupling moq-mux to origin publishing. +- A flag with the next PCR behind the last one is a restart; a flag with a + forward jump stays a break marker. The 33-bit wrap is modular, not a rewind. +- Callers: `moq import ts` (`rs/moq-cli`) and `moq-srt`'s `Publisher`, single + program and `Program::All`. + +Tests: a fixture with a flagged rewind publishes two broadcasts, the second +starting at the rewound PTS; the same rewind unflagged still errors; one SRT +connection carries both epochs. Update `doc/bin/cli.md` and `doc/bin/srt.md`. + +Public API: breaking in moq-mux on dev, `ts::Import::decode` reports a restart +and `restart` is new. Wire: none. + +## Required + +- [Origin](/quest/m1/broadcast-epoch/origin.md) - the fresh epoch path the rest of the feed publishes under + +## Closes + +- [#4582](https://github.com/moq-dev/moq/issues/4582) - a signalled backward TS discontinuity ends the import diff --git a/quest/m1/close-tail.md b/quest/m1/close-tail.md new file mode 100644 index 00000000000..1c1e75dfb9d --- /dev/null +++ b/quest/m1/close-tail.md @@ -0,0 +1,69 @@ +# [M] A graceful close waits for the subscriber to read the tail + +## Goal + +When `Session::close()` returns `Ok` on moq-lite-07, every subscriber has read +each finished track to its end: every frame of the final group, then a clean +end. Today close counts a group delivered once the peer's QUIC stack acks it, +then sends `CONNECTION_CLOSE`, and a real QUIC stack discards stream data the +subscriber's moq-net has not read yet. The subscriber loses the final group and +sees `Session(Cancel)`, while the publisher is told the close succeeded. + +## Plan + +Root cause: a lite serve decrements the publisher's `owed` count once its +group streams and Subscribe Stream FIN are acked (`poll_close` in +`rs/moq-net/src/lite/publisher.rs`), and `Publisher::drained()` reads only that +count. `poll_drain` in `rs/moq-net/src/session.rs` then closes the session with +`Cancel`. The lost final group is unread data the subscriber's QUIC stack +discards on `CONNECTION_CLOSE`; the subscriber's abort then ends the track with +that group still open. `tests/session_close.rs` passes only because the mock +transport keeps unread data after close. + +Decided (maintainer, 2026-09-30): + +- The fix is a FIN handshake, per subscription. On lite-07 the subscriber FINs + its side of the Subscribe Stream once its tail accounting settles the track's + end, never earlier: every group below the end has been read to its FIN, + reset, or dropped. Today that accounting is SUBSCRIBE_END's `Stream Count`; + once [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) lands it is a received + group or a SUBSCRIBE_DROP per sequence. The FIN rule rides on whichever is in + place, so neither quest waits on the other. The publisher's + drain waits until each served Subscribe Stream is closed both ways (the + subscriber's FIN or a reset), under the same `CLOSE_TIMEOUT`, before + `CONNECTION_CLOSE`. A session-level GOAWAY handshake was rejected: the peer + would need the same per-subscription knowledge to know when to close. +- lite-07 only, since it is still wip and the draft can require the + subscriber FIN there. On lite-05 and lite-06 an old subscriber never FINs, + so close keeps today's ack-based drain rather than time out every close. + #4508's repro is on lite-05, and that path stays as it is: this quest closes + the issue by fixing the close on the version that can carry the FIN rule. + IETF sessions stay with [IETF drain before close](/quest/m1/ietf-drain-before-close.md). +- Both subscribers change: moq-net and `@moq/net`. + +Update `drafts/draft-lcurley-moq-lite.md` (the Subscribe section gains the +subscriber FIN rule, with a changelog entry) and `doc/concept/moq-lite.md` +(a subscription ends with both sides' FIN, and a graceful close waits for it). Check that a lite-07 publisher +already treats a subscriber FIN after SUBSCRIBE_END as the end of a finished +subscription, not a cancel of one still in flight +([Request stream cancel](/quest/m1/request-stream-serve.md)). + +Tests: the reporter's `close_tail` case (one session, paused clock, a mock +switch that acks a FIN as soon as it is sent, as a real transport does) fails +today and passes with the fix; a subscriber that never FINs makes close return +`Error::Timeout`; a final range with a skipped and a reset group still settles +and FINs. Run `just test interop --all`, since both the Rust and JS subscribers change; +[Track tail interop](/quest/m1/track-tail-interop.md) is the cross-language +proof over a real relay. + +Public API: none. Wire: on lite-07 a subscriber FINs its Subscribe Stream +after reading the track's end, and a publisher closing gracefully waits for it. + +## Closes + +- [#4508](https://github.com/moq-dev/moq/issues/4508) - `close()` returns `Ok` while the subscriber gets a cut track + +## Related + +- [IETF drain before close](/quest/m1/ietf-drain-before-close.md) - the same drain for moq-transport sessions +- [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - replaces the lite-07 tail accounting the FIN rule waits on diff --git a/quest/m1/track-tail-interop.md b/quest/m1/track-tail-interop.md index e31403931b7..9450e353d04 100644 --- a/quest/m1/track-tail-interop.md +++ b/quest/m1/track-tail-interop.md @@ -38,3 +38,4 @@ delivered and clean. The ordering race itself stays in the unit tests. - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - owns the lite-07 drop case on top of this harness - [Reliable stream reset](/quest/m1/quic/reliable-reset.md) - keeps a reset stream's header, so the reset acts as a one-group drop +- [Close waits for the tail](/quest/m1/close-tail.md) - the publisher-side fix this test proves across a real relay diff --git a/quest/m1/ts-damaged-units.md b/quest/m1/ts-damaged-units.md new file mode 100644 index 00000000000..8de2efbd990 --- /dev/null +++ b/quest/m1/ts-damaged-units.md @@ -0,0 +1,60 @@ +# [M] TS import drops a damaged unit instead of ending the ingest + +## Goal + +`moq import ts`, and `moq-srt` through the same importer, survive a packet, +PES, or access unit they cannot parse: a malformed PES header or media-PID +adaptation field with `transport_error_indicator` clear, or a codec error such +as an H.264 NAL with `forbidden_zero_bit` set. The damaged unit is dropped and +counted, its track waits for its next keyframe, and the ingest carries on. +Today the first such error ends the import, and the gateway hangs up. + +## Plan + +Today `decode` in `rs/moq-mux/src/container/ts/import.rs` runs +`while let Some(packet) = self.reader.read_ts_packet()? { self.handle_packet(packet)?; }`, +so any PES-header error from the reader and any codec error from `flush` ends +the import. The `transport_error_indicator` branch already drops a flagged +packet (clears `pending[pid]` and calls `stream.desync()`), and it is the model. + +Decided (maintainer, 2026-09-30): + +- Fail-loud holds at unit granularity, as [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) + holds it at section granularity: a damaged unit is refused whole, never half + published, and counted, and nothing else about the feed changes. PSI damage + stays that quest's. +- Drop the unit the way the TEI branch does: clear the PID's pending PES and + desync its stream, so a codec that needs one waits for the next keyframe. + Make sure the scratch buffer still advances past the packet on this path + (today an error skips `self.scratch.drain(..off)`). +- Count each drop in a new cumulative per-PID `damaged` counter on the stream's + stats row, beside `resyncs` and `discarded`, reported by `ts::stats::Log`. + It names what happened; no TR 101 290 check matches a codec error, and + [TS import health](/quest/m2/ts-import-health.md) keeps the ETSI names. + The rows are `#[non_exhaustive]`, so the field is additive; follow + [TS stats module](/quest/m1/ts-stats-module.md)'s names if it has landed. +- Errors that are not confined to one unit (the producer refusing a rewind, + origin or catalog failures) stay fatal. +- Built on the demux TS PSI reassembly owns, since that quest moves PES header + parsing into moq-mux. + +Tests, from [#4581](https://github.com/moq-dev/moq/issues/4581)'s stimuli on a +fixture: a video PES header with its flag and timestamp bytes zeroed (TEI +clear), and one H.264 NAL with `forbidden_zero_bit` set. Each import carries +on, counts exactly one `damaged` on that PID and none elsewhere, and publishes +again from the next keyframe; a clean fixture counts zero. Document the counter +wherever the TS stats fields are described. + +Public API: additive, one stats field. Wire: none. + +## Required + +- [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) - moq-mux owns the demux and PES header parsing this drops through + +## Closes + +- [#4581](https://github.com/moq-dev/moq/issues/4581) - one malformed packet ends the TS import + +## Related + +- [TS import health](/quest/m2/ts-import-health.md) - the TR 101 290 counters for the same feed From a0309f6effd57b003cf978643a4c7d655bf5c0b2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 09:11:10 -0700 Subject: [PATCH 105/128] chore(tooling): thin justfiles and CI that calls them (#4038) Co-authored-by: Claude Opus 5.5 Co-authored-by: Grok 4.7 --- .github/actions/just/action.yml | 11 + .github/justfile | 49 +- .github/scripts/package-binary.test.sh | 72 -- .github/workflows/alert.yml | 4 +- .github/workflows/android.yml | 10 +- .github/workflows/apt-repo.yml | 5 +- .github/workflows/check.yml | 39 +- .github/workflows/docker.yml | 4 +- .github/workflows/interop.yml | 2 +- .github/workflows/libmoq.yml | 26 +- .github/workflows/moq-cli.yml | 217 +--- .github/workflows/moq-gst.yml | 26 +- .github/workflows/moq-relay.yml | 216 +--- .github/workflows/nightly.yml | 19 +- .github/workflows/obs.yml | 5 +- .github/workflows/platform.yml | 17 +- .github/workflows/release-binary.yml | 258 ++++ .github/workflows/release-brew.yml | 6 +- .github/workflows/release-dart-ffi.yml | 172 +-- .github/workflows/release-dart.yml | 8 +- .github/workflows/release-ffi.yml | 169 +++ .github/workflows/release-go-ffi.yml | 163 +-- .github/workflows/release-go.yml | 10 +- .github/workflows/release-kt-ffi.yml | 146 +-- .github/workflows/release-kt-lib.yml | 18 +- .github/workflows/release-py-ffi.yml | 4 +- .github/workflows/release-py.yml | 12 +- .github/workflows/release-swift-ffi.yml | 130 +- .github/workflows/release-swift-lib.yml | 40 +- .github/workflows/rpm-repo.yml | 5 +- .github/workflows/swift.yml | 6 +- .github/workflows/wasm.yml | 1 + .gitignore | 5 +- CONTRIBUTING.md | 4 + Cargo.toml | 2 +- bench/justfile | 19 - cpp/obs/justfile | 389 +----- dart/justfile | 22 +- dart/moq_ffi/hook/build.dart | 2 +- dart/moq_ffi/pubspec.yaml | 2 +- demo/boy/justfile | 18 +- demo/justfile | 57 +- demo/pub/justfile | 171 +-- demo/relay/justfile | 53 +- demo/sub/justfile | 4 +- doc/setup/dev.md | 8 +- drafts/justfile | 84 +- flake.nix | 17 +- go/.gitignore | 2 +- go/ffi/README.md | 8 +- go/ffi/moq/cgo.go | 6 +- go/justfile | 59 +- go/wrapper/README.md | 2 +- go/wrapper/go.mod | 2 +- js/common/workers.test.ts | 45 - js/justfile | 103 +- js/wasm/.gitignore | 2 +- js/wasm/README.md | 2 +- justfile | 908 +------------ kt/.gitignore | 2 +- kt/README.md | 1 - kt/justfile | 39 +- kt/moq-ffi/build.gradle.kts | 2 +- .../kotlin/dev/moq/docs/Prelude.kt | 2 +- py/justfile | 76 +- quest/m1/README.md | 1 - quest/m1/bench-ci.md | 8 +- quest/m1/capture-default.md | 3 +- quest/m1/doc-samples-go-dart.md | 6 +- quest/m1/gpu-ci.md | 4 +- quest/m1/merge-queue.md | 7 - quest/m1/performance-comparisons.md | 4 - quest/m1/serve-hls-renditions.md | 5 +- quest/m1/size-report.md | 4 +- quest/m1/tooling/README.md | 25 - quest/m1/tooling/justfiles.md | 102 -- quest/m1/tooling/release-binary.md | 31 - quest/m1/tooling/release-ffi.md | 35 - quest/m1/tooling/workflows-call-just.md | 45 - quest/m2/moq-installer.md | 4 +- rs/justfile | 1132 +++-------------- rs/moq-gst/package.sh | 2 +- rs/moq-gst/scrub.sh | 2 +- rs/moq-wasm/README.md | 4 +- rs/scripts/doc-names.jq | 31 - rs/scripts/package-nfpm.test.sh | 68 - sh/changed.sh | 35 + sh/clean.sh | 72 ++ {dart/scripts => sh/dart}/check.sh | 11 +- {dart/scripts => sh/dart}/generate.sh | 2 +- {dart/scripts => sh/dart}/package.sh | 2 +- {dart/scripts => sh/dart}/publish.sh | 4 +- sh/demo/ca.sh | 15 + sh/demo/cert.sh | 20 + sh/demo/download.sh | 15 + sh/demo/hls.sh | 69 + sh/demo/key.sh | 11 + sh/demo/port.sh | 18 + sh/demo/run.sh | 24 + sh/demo/serve-hls.sh | 43 + sh/demo/sync.sh | 16 + sh/demo/token.sh | 19 + sh/demo/wait.sh | 14 + sh/dispatch.sh | 205 +++ sh/drafts/build.sh | 20 + sh/drafts/check.sh | 36 + sh/drafts/publish.sh | 44 + {.github/scripts => sh/gh}/alert.sh | 13 +- sh/gh/check-runs.ts | 26 + {.github/scripts => sh/gh}/install-formula.py | 0 .../scripts => sh/gh}/install-formula.test.py | 0 {.github/scripts => sh/gh}/release.sh | 0 {.github/scripts => sh/gh}/release.test.sh | 0 {.github/scripts => sh/gh}/render-formula.sh | 0 .../scripts => sh/gh}/trigger-repo-publish.sh | 0 {go/scripts => sh/go}/check-errors.sh | 0 {go/scripts => sh/go}/check.sh | 8 +- {go/scripts => sh/go}/package-ffi.sh | 4 +- {go/scripts => sh/go}/package-wrapper.sh | 4 +- {go/scripts => sh/go}/publish-ffi.sh | 0 {go/scripts => sh/go}/publish-wrapper.sh | 0 {go/scripts => sh/go}/publish-wrapper.test.sh | 6 +- {go/scripts => sh/go}/stage.sh | 4 +- sh/js/workers.sh | 16 + {kt/scripts => sh/kt}/check.sh | 4 +- {kt/scripts => sh/kt}/generate.sh | 4 +- {kt/scripts => sh/kt}/package.sh | 4 +- sh/markdown.sh | 69 + sh/obs/check.sh | 68 + sh/obs/compile.sh | 67 + sh/obs/fix.sh | 12 + sh/obs/includes.sh | 72 ++ sh/obs/preset.sh | 22 + sh/obs/test.sh | 42 + sh/obs/unit.sh | 54 + sh/py/samples.sh | 17 + sh/rs/c-tests.sh | 74 ++ sh/rs/fuzz.sh | 40 + {rs/scripts => sh/rs}/media-features.sh | 0 {rs/scripts => sh/rs}/package-binary.sh | 2 +- {rs/scripts => sh/rs}/package-nfpm.sh | 0 {rs/scripts => sh/rs}/package-rename.test.py | 2 +- {rs/scripts => sh/rs}/package-windows.sh | 2 +- sh/rs/package.sh | 51 + sh/rs/platform.sh | 17 + {rs/scripts => sh/rs}/scrub-macho.sh | 0 sh/rs/select.sh | 178 +++ {rs/scripts => sh/rs}/stats-docs.py | 0 sh/rs/tokio-features.sh | 28 + sh/rs/vulkan-cuda.sh | 17 + sh/shell.sh | 27 + {swift/scripts => sh/swift}/check.sh | 2 +- {swift/scripts => sh/swift}/package-ffi.sh | 4 +- {swift/scripts => sh/swift}/package.sh | 4 +- {swift/scripts => sh/swift}/publish-ffi.sh | 0 {swift/scripts => sh/swift}/publish.sh | 0 {swift/scripts => sh/swift}/verify-ffi.sh | 4 +- {swift/scripts => sh/swift}/verify.sh | 4 +- swift/.gitignore | 2 +- swift/.spi.yml | 2 +- swift/Package.swift | 4 +- swift/Package.swift.template | 2 +- swift/README.md | 7 +- swift/Tests/MoqTests/Docs/Prelude.swift | 2 +- swift/ffi/Package.swift.template | 2 +- swift/justfile | 60 +- test/README.md | 22 - test/interop/README.md | 4 +- test/interop/clients/go/go.mod | 2 +- test/interop/interop.sh | 14 +- test/justfile | 39 +- test/wasm/README.md | 2 +- test/wasm/run.sh | 2 +- 173 files changed, 2865 insertions(+), 4479 deletions(-) create mode 100644 .github/actions/just/action.yml delete mode 100755 .github/scripts/package-binary.test.sh create mode 100644 .github/workflows/release-binary.yml create mode 100644 .github/workflows/release-ffi.yml delete mode 100755 bench/justfile delete mode 100644 js/common/workers.test.ts delete mode 100644 quest/m1/tooling/README.md delete mode 100644 quest/m1/tooling/justfiles.md delete mode 100644 quest/m1/tooling/release-binary.md delete mode 100644 quest/m1/tooling/release-ffi.md delete mode 100644 quest/m1/tooling/workflows-call-just.md delete mode 100644 rs/scripts/doc-names.jq delete mode 100755 rs/scripts/package-nfpm.test.sh create mode 100755 sh/changed.sh create mode 100755 sh/clean.sh rename {dart/scripts => sh/dart}/check.sh (88%) rename {dart/scripts => sh/dart}/generate.sh (96%) rename {dart/scripts => sh/dart}/package.sh (97%) rename {dart/scripts => sh/dart}/publish.sh (84%) create mode 100755 sh/demo/ca.sh create mode 100755 sh/demo/cert.sh create mode 100755 sh/demo/download.sh create mode 100755 sh/demo/hls.sh create mode 100755 sh/demo/key.sh create mode 100755 sh/demo/port.sh create mode 100755 sh/demo/run.sh create mode 100755 sh/demo/serve-hls.sh create mode 100755 sh/demo/sync.sh create mode 100755 sh/demo/token.sh create mode 100755 sh/demo/wait.sh create mode 100755 sh/dispatch.sh create mode 100755 sh/drafts/build.sh create mode 100755 sh/drafts/check.sh create mode 100755 sh/drafts/publish.sh rename {.github/scripts => sh/gh}/alert.sh (93%) create mode 100644 sh/gh/check-runs.ts rename {.github/scripts => sh/gh}/install-formula.py (100%) rename {.github/scripts => sh/gh}/install-formula.test.py (100%) rename {.github/scripts => sh/gh}/release.sh (100%) rename {.github/scripts => sh/gh}/release.test.sh (100%) rename {.github/scripts => sh/gh}/render-formula.sh (100%) rename {.github/scripts => sh/gh}/trigger-repo-publish.sh (100%) rename {go/scripts => sh/go}/check-errors.sh (100%) rename {go/scripts => sh/go}/check.sh (84%) rename {go/scripts => sh/go}/package-ffi.sh (98%) rename {go/scripts => sh/go}/package-wrapper.sh (97%) rename {go/scripts => sh/go}/publish-ffi.sh (100%) rename {go/scripts => sh/go}/publish-wrapper.sh (100%) rename {go/scripts => sh/go}/publish-wrapper.test.sh (97%) rename {go/scripts => sh/go}/stage.sh (98%) create mode 100755 sh/js/workers.sh rename {kt/scripts => sh/kt}/check.sh (92%) rename {kt/scripts => sh/kt}/generate.sh (96%) rename {kt/scripts => sh/kt}/package.sh (97%) create mode 100755 sh/markdown.sh create mode 100755 sh/obs/check.sh create mode 100755 sh/obs/compile.sh create mode 100755 sh/obs/fix.sh create mode 100755 sh/obs/includes.sh create mode 100755 sh/obs/preset.sh create mode 100755 sh/obs/test.sh create mode 100755 sh/obs/unit.sh create mode 100755 sh/py/samples.sh create mode 100755 sh/rs/c-tests.sh create mode 100755 sh/rs/fuzz.sh rename {rs/scripts => sh/rs}/media-features.sh (100%) rename {rs/scripts => sh/rs}/package-binary.sh (99%) rename {rs/scripts => sh/rs}/package-nfpm.sh (100%) rename {rs/scripts => sh/rs}/package-rename.test.py (98%) rename {rs/scripts => sh/rs}/package-windows.sh (98%) create mode 100755 sh/rs/package.sh create mode 100755 sh/rs/platform.sh rename {rs/scripts => sh/rs}/scrub-macho.sh (100%) create mode 100755 sh/rs/select.sh rename {rs/scripts => sh/rs}/stats-docs.py (100%) create mode 100755 sh/rs/tokio-features.sh create mode 100755 sh/rs/vulkan-cuda.sh create mode 100755 sh/shell.sh rename {swift/scripts => sh/swift}/check.sh (98%) rename {swift/scripts => sh/swift}/package-ffi.sh (98%) rename {swift/scripts => sh/swift}/package.sh (98%) rename {swift/scripts => sh/swift}/publish-ffi.sh (100%) rename {swift/scripts => sh/swift}/publish.sh (100%) rename {swift/scripts => sh/swift}/verify-ffi.sh (96%) rename {swift/scripts => sh/swift}/verify.sh (96%) diff --git a/.github/actions/just/action.yml b/.github/actions/just/action.yml new file mode 100644 index 00000000000..a41f055151a --- /dev/null +++ b/.github/actions/just/action.yml @@ -0,0 +1,11 @@ +name: Install just +description: Install the pinned just for jobs outside the nix dev shell, which already provides it. + +runs: + using: composite + steps: + # A checksum-verified prebuilt, so it costs seconds rather than a + # `cargo install`. Keep the version in step with nixpkgs' just in flake.lock. + - uses: taiki-e/install-action@4cef1412cce204788f482e778a0b9187f9626a29 # v2.87.21 + with: + tool: just@1.58.0 diff --git a/.github/justfile b/.github/justfile index f341da77296..1bccfc53380 100644 --- a/.github/justfile +++ b/.github/justfile @@ -1,13 +1,40 @@ -set fallback +set working-directory := '..' -# actionlint is skipped when absent locally; the root `_tools` preflight makes -# it a hard requirement under MOQ_STRICT, so CI can't skip it. - -# Lint GitHub Actions workflows. +# Lint GitHub Actions workflows, their alert coverage, and that every step runs a recipe. check: - python3 {{ source_directory() }}/scripts/install-formula.test.py - {{ source_directory() }}/scripts/release.test.sh - @if command -v nfpm >/dev/null 2>&1 && command -v envsubst >/dev/null 2>&1 && command -v dpkg-deb >/dev/null 2>&1 && command -v rpm >/dev/null 2>&1; then python3 {{ source_directory() }}/../rs/scripts/package-rename.test.py; fi - @if command -v actionlint >/dev/null 2>&1; then actionlint; fi - {{ source_directory() }}/scripts/alert.sh check-coverage - @if command -v rustc >/dev/null 2>&1; then {{ source_directory() }}/scripts/package-binary.test.sh; fi + actionlint + sh/gh/alert.sh check-coverage + bun sh/gh/check-runs.ts + +# Tests of the release tooling itself; nightly, not on every pull request. +test: + python3 sh/gh/install-formula.test.py + sh/gh/release.test.sh + python3 sh/rs/package-rename.test.py + sh/go/publish-wrapper.test.sh + bash .claude/hooks/direnv.test.sh + +# Release workflow helpers, e.g. `just gh release parse-version moq-cli`. +[positional-arguments] +release *args: + sh/gh/release.sh "$@" + +# Post a failed run to Discord, or check that alert.yml covers every workflow. +[positional-arguments] +alert *args: + sh/gh/alert.sh "$@" + +# Render a Homebrew formula template for a release. +[positional-arguments] +formula *args: + sh/gh/render-formula.sh "$@" + +# Copy a rendered formula into a Homebrew tap checkout, migrating renamed formulae. +[positional-arguments] +install-formula *args: + python3 sh/gh/install-formula.py "$@" + +# Trigger the apt-repo and rpm-repo workflows for a release tag. +[positional-arguments] +trigger-repo-publish *args: + sh/gh/trigger-repo-publish.sh "$@" diff --git a/.github/scripts/package-binary.test.sh b/.github/scripts/package-binary.test.sh deleted file mode 100755 index b1390552f15..00000000000 --- a/.github/scripts/package-binary.test.sh +++ /dev/null @@ -1,72 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -WORKSPACE_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" - -tmp="$(mktemp -d)" -trap 'rm -rf "$tmp"' EXIT - -binary="$tmp/moq-relay" -printf '#!/usr/bin/env sh\necho test\n' >"$binary" -chmod 0755 "$binary" -target="$(rustc -vV | awk '/^host:/ {print $2}')" - -# This test covers archive staging, not the macOS Mach-O rewrite. -mkdir "$tmp/bin" -printf '#!/usr/bin/env sh\nprintf "Linux\\n"\n' >"$tmp/bin/uname" -chmod 0755 "$tmp/bin/uname" - -PATH="$tmp/bin:$PATH" "$WORKSPACE_DIR/rs/scripts/package-binary.sh" \ - --crate moq-relay \ - --bin moq-relay \ - --binary "$binary" \ - --bare \ - --version 0.14.13 \ - --target "$target" \ - --output "$tmp/dist" - -name="moq-relay-v0.14.13-$target" -bare="$tmp/dist/$name" -archive="$tmp/dist/$name.tar.gz" - -[[ -x "$bare" ]] -[[ -f "$archive" ]] - -mkdir "$tmp/extracted" -tar -xzf "$archive" -C "$tmp/extracted" -[[ -x "$tmp/extracted/$name/bin/moq-relay" ]] -[[ -f "$tmp/extracted/$name/LICENSE-MIT" ]] -[[ -f "$tmp/extracted/$name/LICENSE-APACHE" ]] -cmp "$binary" "$bare" -cmp "$binary" "$tmp/extracted/$name/bin/moq-relay" - -echo "release assets package together without path collisions" - -# Without --binary the script builds the flake package named after the binary: -# `.#moq` for the moq-cli crate, since `.#moq-cli` is a stub refusing the old name. -cat >"$tmp/bin/nix" <<'NIX' -#!/usr/bin/env bash -set -euo pipefail -[[ "$1 $3" == "build --out-link" && "$2" == *"#moq" ]] || { - echo "unexpected: nix $*" >&2 - exit 1 -} -mkdir -p "$4/bin" -printf '#!/usr/bin/env sh\necho moq\n' >"$4/bin/moq" -chmod 0755 "$4/bin/moq" -NIX -chmod 0755 "$tmp/bin/nix" - -PATH="$tmp/bin:$PATH" "$WORKSPACE_DIR/rs/scripts/package-binary.sh" \ - --crate moq-cli \ - --bin moq \ - --version 0.12.2 \ - --target "$target" \ - --output "$tmp/dist" - -name="moq-cli-v0.12.2-$target" -tar -xzf "$tmp/dist/$name.tar.gz" -C "$tmp/extracted" -[[ "$("$tmp/extracted/$name/bin/moq")" == moq ]] - -echo "a nix build packages the flake output named after the binary" diff --git a/.github/workflows/alert.yml b/.github/workflows/alert.yml index 9e264da8d30..d0d3f51a29a 100644 --- a/.github/workflows/alert.yml +++ b/.github/workflows/alert.yml @@ -81,6 +81,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Post to Discord env: DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }} @@ -91,4 +93,4 @@ jobs: RUN_REF: ${{ github.event.workflow_run.head_branch }} RUN_TITLE: ${{ github.event.workflow_run.display_title }} RUN_ACTOR: ${{ github.event.workflow_run.triggering_actor.login }} - run: .github/scripts/alert.sh discord + run: just gh alert discord diff --git a/.github/workflows/android.yml b/.github/workflows/android.yml index 881d1276862..44c6e807a4d 100644 --- a/.github/workflows/android.yml +++ b/.github/workflows/android.yml @@ -50,7 +50,6 @@ concurrency: env: CARGO_NDK_VERSION: 4.1.2 - JUST_VERSION: 1.52.0 jobs: android: @@ -74,15 +73,10 @@ jobs: # No Rust cache: this workflow only runs on pull requests, which may not # save one, so it would have nothing to restore. + - uses: ./.github/actions/just + - name: Install cargo-ndk run: cargo install --locked "cargo-ndk@$CARGO_NDK_VERSION" - # A checksummed release binary, where `cargo install` would spend ~2 minutes - # building just from source. - - name: Install just - uses: taiki-e/install-action@4cef1412cce204788f482e778a0b9187f9626a29 # v2.87.21 - with: - tool: just@${{ env.JUST_VERSION }} - - name: Check run: just rs android diff --git a/.github/workflows/apt-repo.yml b/.github/workflows/apt-repo.yml index ff790e1583b..5e8905ed21c 100644 --- a/.github/workflows/apt-repo.yml +++ b/.github/workflows/apt-repo.yml @@ -34,6 +34,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Set up packaging tools uses: ./.github/actions/setup-packaging @@ -53,10 +55,9 @@ jobs: - name: Publish to R2 shell: bash env: - ARTIFACTS_DIR: artifacts R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }} R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }} R2_ACCOUNT_ID: ${{ secrets.R2_ACCOUNT_ID }} SIGNING_KEY: ${{ secrets.SIGNING_KEY }} SIGNING_PASSWORD: ${{ secrets.SIGNING_PASSWORD }} - run: ./infra/apt/publish.sh + run: just infra apt publish "$GITHUB_WORKSPACE/artifacts" diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index 8fa0ed62ea5..834ac0fac63 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -39,19 +39,7 @@ jobs: # Full history so `just ci check` can diff against origin/$GITHUB_BASE_REF. fetch-depth: 0 - # Quests, agent config, and root Markdown compile nothing, so a diff of only - # those skips the disk cleanup and Rust cache that exist for the build. - - name: Scope - id: scope - run: | - base=$(git merge-base "origin/$GITHUB_BASE_REF" HEAD) - files=$(git diff --name-only "$base") - if grep -qvE '^(quest/|\.claude/|[^/]+\.md$)' <<< "$files"; then - echo build=true >> "$GITHUB_OUTPUT" - fi - - name: Free disk space - if: steps.scope.outputs.build uses: jlumbroso/free-disk-space@ceedf095f4ec1a097402bc6bd80831f2e1a6fde6 # main with: tool-cache: false @@ -75,20 +63,19 @@ jobs: # scope such an entry to the PR's own branch anyway, where no later PR # could read it while it ate the repository's 10 GB budget. - name: Rust cache - if: steps.scope.outputs.build uses: ./.github/actions/rust-cache # The same recipe a developer runs locally. It diffs against # origin/$GITHUB_BASE_REF and touches only the packages this PR changed - # plus their dependents, so a one-crate PR compiles one crate. + # plus their dependents, so a one-crate PR compiles one crate and a + # quest-only PR runs only the lints. sh/dispatch.sh's impact map is the one + # place that decides; the setup above always runs rather than keep a second + # path map here. # # MOQ_STRICT turns every "tool missing, skipping" guard into an error. # Locally an absent formatter means less gets checked; here it would mean # a green run that checked nothing, which is the failure mode worth # spending a preflight on. - - name: Test direnv hook - run: bash .claude/hooks/direnv.test.sh - - name: Check run: nix develop --command just ci check env: @@ -108,26 +95,12 @@ jobs: # Full history so `just ci test` can diff against origin/$GITHUB_BASE_REF. fetch-depth: 0 - # Same scope as the `check` job. No test covers those files either, so the - # job skips everything and reports green instead of spending a minute of - # setup to run nothing. - - name: Scope - id: scope - run: | - base=$(git merge-base "origin/$GITHUB_BASE_REF" HEAD) - files=$(git diff --name-only "$base") - if grep -qvE '^(quest/|\.claude/|[^/]+\.md$)' <<< "$files"; then - echo build=true >> "$GITHUB_OUTPUT" - fi - - name: Free disk space - if: steps.scope.outputs.build uses: jlumbroso/free-disk-space@ceedf095f4ec1a097402bc6bd80831f2e1a6fde6 # main with: tool-cache: false - - if: steps.scope.outputs.build - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main + - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: determinate: false # Trust the flake's cachix substituter. `nixConfig` in flake.nix is @@ -142,13 +115,11 @@ jobs: # Restore only, same as the `check` job above. - name: Rust cache - if: steps.scope.outputs.build uses: ./.github/actions/rust-cache # NEXTEST_PROFILE picks up the longer hang timeout in .config/nextest.toml; # without it a runner under load could trip the local one. - name: Test - if: steps.scope.outputs.build run: nix develop --command just ci test env: MOQ_STRICT: 1 diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index fc6748864b7..5fcbc152e44 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -39,6 +39,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - id: parse env: CRATE: ${{ inputs.package }} @@ -58,7 +60,7 @@ jobs: *) package="$crate" ;; esac echo "package=${package}" >> "$GITHUB_OUTPUT" - .github/scripts/release.sh parse-version "$crate" + just gh release parse-version "$crate" build: name: Build ${{ matrix.platform }} diff --git a/.github/workflows/interop.yml b/.github/workflows/interop.yml index cbbe0a43f56..74a22e98bd1 100644 --- a/.github/workflows/interop.yml +++ b/.github/workflows/interop.yml @@ -24,7 +24,7 @@ on: - "test/justfile" - "package.json" # The Go client builds against the modules this script stages. - - "go/scripts/**" + - "sh/go/**" - ".github/workflows/interop.yml" concurrency: diff --git a/.github/workflows/libmoq.yml b/.github/workflows/libmoq.yml index 7726371df53..990cd2e65c8 100644 --- a/.github/workflows/libmoq.yml +++ b/.github/workflows/libmoq.yml @@ -40,6 +40,8 @@ jobs: fetch-depth: 0 persist-credentials: false + - uses: ./.github/actions/just + - name: Install Nix if: matrix.use_nix uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main @@ -60,12 +62,12 @@ jobs: - name: Parse version id: parse shell: bash - run: .github/scripts/release.sh parse-version libmoq + run: just gh release parse-version libmoq - name: Build and package shell: bash run: | - ./rs/libmoq/build.sh \ + just rs package-libmoq \ --target ${{ matrix.target }} \ --version ${{ steps.parse.outputs.version }} \ --output dist @@ -90,13 +92,15 @@ jobs: fetch-depth: 0 persist-credentials: false + - uses: ./.github/actions/just + - name: Parse version id: parse - run: .github/scripts/release.sh parse-version libmoq + run: just gh release parse-version libmoq - name: Find previous tag id: prev_tag - run: .github/scripts/release.sh prev-tag libmoq + run: just gh release prev-tag libmoq - name: Download artifacts uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 @@ -110,7 +114,7 @@ jobs: RELEASE_TAG: ${{ github.ref_name }} RELEASE_TITLE: "libmoq v${{ steps.parse.outputs.version }}" RELEASE_PREV_TAG: ${{ steps.prev_tag.outputs.tag }} - run: .github/scripts/release.sh create artifacts + run: just gh release create artifacts # The OBS plugin (cpp/obs) statically links libmoq, so it ships with every # libmoq release: rebuild it against the release we just published (no @@ -142,10 +146,12 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Parse version id: parse shell: bash - run: .github/scripts/release.sh parse-version libmoq + run: just gh release parse-version libmoq # Native Xcode / Visual Studio; libobs/Qt6/ffmpeg come from the obs-deps # bundle and libmoq from the release we just published (--libmoq-release). @@ -155,7 +161,7 @@ jobs: TARGET: ${{ matrix.target }} VERSION: ${{ steps.parse.outputs.version }} run: | - ./cpp/obs/build.sh --target "$TARGET" --libmoq-release "$VERSION" --output dist + just obs package --target "$TARGET" --libmoq-release "$VERSION" --output dist - name: Upload artifact uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 @@ -176,9 +182,11 @@ jobs: fetch-depth: 0 persist-credentials: false + - uses: ./.github/actions/just + - name: Parse version id: parse - run: .github/scripts/release.sh parse-version libmoq + run: just gh release parse-version libmoq # Only the obs-moq archives: the libmoq-* artifacts from the build job # belong to the libmoq release, not this one. @@ -213,4 +221,4 @@ jobs: RELEASE_TAG: "obs-moq-v${{ steps.parse.outputs.version }}" RELEASE_TITLE: "obs-moq v${{ steps.parse.outputs.version }}" RELEASE_PREV_TAG: ${{ steps.prev_tag.outputs.tag }} - run: .github/scripts/release.sh create artifacts + run: just gh release create artifacts diff --git a/.github/workflows/moq-cli.yml b/.github/workflows/moq-cli.yml index a7963178e4d..0258e0ca072 100644 --- a/.github/workflows/moq-cli.yml +++ b/.github/workflows/moq-cli.yml @@ -17,220 +17,11 @@ permissions: contents: read jobs: - build: - name: Build (${{ matrix.target }}) - runs-on: ${{ matrix.runs-on }} - - strategy: - fail-fast: false - matrix: - include: - - target: x86_64-unknown-linux-gnu - runs-on: ubuntu-22.04 - deb-arch: amd64 - rpm-arch: x86_64 - - target: aarch64-unknown-linux-gnu - runs-on: ubuntu-22.04-arm - deb-arch: arm64 - rpm-arch: aarch64 - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - with: - targets: ${{ matrix.target }} - - - name: Parse version - id: parse - shell: bash - run: .github/scripts/release.sh parse-version moq-cli - - - name: Set up packaging tools - uses: ./.github/actions/setup-packaging - - - name: Build (release, glibc 2.34) - shell: bash - # Pin to glibc 2.34 so one binary covers Ubuntu 22.04+ (.deb) - # and AlmaLinux/RHEL/Rocky 9+ (.rpm). - run: cargo zigbuild --locked --release --target ${{ matrix.target }}.2.34 -p moq-cli - - - name: Package release assets - shell: bash - env: - VERSION: ${{ steps.parse.outputs.version }} - TARGET: ${{ matrix.target }} - run: | - ./rs/scripts/package-binary.sh \ - --crate moq-cli \ - --bin moq \ - --binary "target/${TARGET}/release/moq" \ - --bare \ - --version "$VERSION" \ - --target "$TARGET" \ - --output dist - - - name: Package .deb (Ubuntu 22.04 toolchain) - shell: bash - env: - VERSION: ${{ steps.parse.outputs.version }} - ARCH: ${{ matrix.deb-arch }} - BINARY_PATH: target/${{ matrix.target }}/release/moq - run: | - rs/scripts/package-nfpm.sh packaging/moq-cli/nfpm.yaml deb dist/ - rs/scripts/package-nfpm.sh packaging/moq-cli/transition.yaml deb dist/ - - - name: Package .rpm - shell: bash - env: - VERSION: ${{ steps.parse.outputs.version }} - ARCH: ${{ matrix.rpm-arch }} - BINARY_PATH: target/${{ matrix.target }}/release/moq - run: rs/scripts/package-nfpm.sh packaging/moq-cli/nfpm.yaml rpm dist/ - - - name: Upload artifacts - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: moq-cli-${{ matrix.target }} - path: dist/* - - build-tarball-macos: - name: Build macOS tarball (${{ matrix.target }}) - runs-on: ${{ matrix.os }} - - strategy: - fail-fast: false - matrix: - include: - - target: aarch64-apple-darwin - os: macos-latest - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - fetch-depth: 0 - persist-credentials: false - - - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main - with: - determinate: false - # Trust the flake's cachix substituter, as check.yml does, so the dev - # shell is substituted rather than built from source. - extra-conf: | - extra-substituters = https://kixelated.cachix.org - extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= - - - name: Parse version - id: parse - shell: bash - run: .github/scripts/release.sh parse-version moq-cli - - - name: Build and package tarball - shell: bash - run: | - ./rs/scripts/package-binary.sh \ - --crate moq-cli \ - --bin moq \ - --target ${{ matrix.target }} \ - --version ${{ steps.parse.outputs.version }} \ - --output dist - - - name: Upload artifact - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: moq-cli-${{ matrix.target }} - path: dist/* - - build-windows: - name: Build Windows zip (${{ matrix.target }}) - runs-on: windows-latest - - strategy: - fail-fast: false - matrix: - include: - - target: x86_64-pc-windows-msvc - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - with: - targets: ${{ matrix.target }} - - # aws-lc-rs assembles its x86_64 crypto with NASM on Windows. - - name: Install NASM - shell: pwsh - run: | - choco install nasm -y --no-progress - "C:\Program Files\NASM" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append - - - name: Parse version - id: parse - shell: bash - run: .github/scripts/release.sh parse-version moq-cli - - - name: Build and package zip - shell: bash - run: | - ./rs/scripts/package-windows.sh \ - --crate moq-cli \ - --bin moq \ - --target ${{ matrix.target }} \ - --version ${{ steps.parse.outputs.version }} \ - --output dist - - - name: Upload artifact - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: moq-cli-${{ matrix.target }} - path: dist/* - release: - name: Release - needs: [build, build-tarball-macos, build-windows] - if: github.ref_type == 'tag' - runs-on: ubuntu-latest + uses: ./.github/workflows/release-binary.yml + with: + crate: moq-cli + bin: moq permissions: contents: write actions: write - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - fetch-depth: 0 - persist-credentials: false - - - name: Parse version - id: parse - run: .github/scripts/release.sh parse-version moq-cli - - - name: Find previous tag - id: prev_tag - run: .github/scripts/release.sh prev-tag moq-cli - - - name: Download artifacts - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 - with: - path: artifacts - merge-multiple: true - - - name: Create or update release - env: - GH_TOKEN: ${{ github.token }} - RELEASE_TAG: ${{ github.ref_name }} - RELEASE_TITLE: "moq-cli v${{ steps.parse.outputs.version }}" - RELEASE_PREV_TAG: ${{ steps.prev_tag.outputs.tag }} - run: .github/scripts/release.sh create artifacts - - - name: Trigger apt/rpm repo publish - env: - GH_TOKEN: ${{ github.token }} - TAG: ${{ github.ref_name }} - run: .github/scripts/trigger-repo-publish.sh diff --git a/.github/workflows/moq-gst.yml b/.github/workflows/moq-gst.yml index 228c5ef1511..7ce0e927052 100644 --- a/.github/workflows/moq-gst.yml +++ b/.github/workflows/moq-gst.yml @@ -34,6 +34,8 @@ jobs: fetch-depth: 0 persist-credentials: false + - uses: ./.github/actions/just + - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: determinate: false @@ -46,7 +48,7 @@ jobs: - name: Parse version id: parse shell: bash - run: .github/scripts/release.sh parse-version moq-gst + run: just gh release parse-version moq-gst - name: Build and package (tarball) shell: bash @@ -54,7 +56,7 @@ jobs: TARGET: ${{ matrix.target }} VERSION: ${{ steps.parse.outputs.version }} run: | - ./rs/moq-gst/build.sh \ + just rs package-gst \ --target "$TARGET" \ --version "$VERSION" \ --output dist @@ -85,7 +87,7 @@ jobs: run: | set -euo pipefail tar -xzf "dist/moq-gst-v${VERSION}-${TARGET}.tar.gz" -C dist/ - ./rs/moq-gst/smoke.sh "dist/moq-gst-v${VERSION}-${TARGET}/lib/gstreamer-1.0" + just rs gst-smoke "dist/moq-gst-v${VERSION}-${TARGET}/lib/gstreamer-1.0" - name: Upload artifact uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 @@ -117,6 +119,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Install Rust uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable with: @@ -128,7 +132,7 @@ jobs: - name: Parse version id: parse shell: bash - run: .github/scripts/release.sh parse-version moq-gst + run: just gh release parse-version moq-gst - name: Install GStreamer dev libraries shell: bash @@ -165,7 +169,7 @@ jobs: PLUGIN_DIR: /usr/lib/${{ matrix.deb-multiarch }}/gstreamer-1.0 run: | mkdir -p dist - rs/scripts/package-nfpm.sh packaging/moq-gst/nfpm.yaml deb dist/ + just rs package-nfpm packaging/moq-gst/nfpm.yaml deb dist/ - name: Package .rpm shell: bash @@ -177,7 +181,7 @@ jobs: PLUGIN_DIR: /usr/lib64/gstreamer-1.0 run: | mkdir -p dist - rs/scripts/package-nfpm.sh packaging/moq-gst/nfpm.yaml rpm dist/ + just rs package-nfpm packaging/moq-gst/nfpm.yaml rpm dist/ - name: Upload artifacts uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 @@ -200,13 +204,15 @@ jobs: fetch-depth: 0 persist-credentials: false + - uses: ./.github/actions/just + - name: Parse version id: parse - run: .github/scripts/release.sh parse-version moq-gst + run: just gh release parse-version moq-gst - name: Find previous tag id: prev_tag - run: .github/scripts/release.sh prev-tag moq-gst + run: just gh release prev-tag moq-gst - name: Download artifacts uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 @@ -220,10 +226,10 @@ jobs: RELEASE_TAG: ${{ github.ref_name }} RELEASE_TITLE: "moq-gst v${{ steps.parse.outputs.version }}" RELEASE_PREV_TAG: ${{ steps.prev_tag.outputs.tag }} - run: .github/scripts/release.sh create artifacts + run: just gh release create artifacts - name: Trigger apt/rpm repo publish env: GH_TOKEN: ${{ github.token }} TAG: ${{ github.ref_name }} - run: .github/scripts/trigger-repo-publish.sh + run: just gh trigger-repo-publish diff --git a/.github/workflows/moq-relay.yml b/.github/workflows/moq-relay.yml index 19dfd61601c..cfb4767b530 100644 --- a/.github/workflows/moq-relay.yml +++ b/.github/workflows/moq-relay.yml @@ -17,219 +17,11 @@ permissions: contents: read jobs: - build: - name: Build (${{ matrix.target }}) - runs-on: ${{ matrix.runs-on }} - - strategy: - fail-fast: false - matrix: - include: - # Native runners. Each binary is built on the same arch it ships - # for, so the .deb/.rpm linkage matches the distro's glibc on the - # oldest LTS we support (Ubuntu 22.04 / AlmaLinux 9). - - target: x86_64-unknown-linux-gnu - runs-on: ubuntu-22.04 - deb-arch: amd64 - rpm-arch: x86_64 - - target: aarch64-unknown-linux-gnu - runs-on: ubuntu-22.04-arm - deb-arch: arm64 - rpm-arch: aarch64 - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - with: - targets: ${{ matrix.target }} - - - name: Parse version - id: parse - shell: bash - run: .github/scripts/release.sh parse-version moq-relay - - - name: Set up packaging tools - uses: ./.github/actions/setup-packaging - - - name: Build (release, glibc 2.34) - shell: bash - # Pin to glibc 2.34 so one binary covers Ubuntu 22.04+ (.deb) - # and AlmaLinux/RHEL/Rocky 9+ (.rpm). - run: cargo zigbuild --locked --release --target ${{ matrix.target }}.2.34 -p moq-relay - - - name: Package release assets - shell: bash - env: - VERSION: ${{ steps.parse.outputs.version }} - TARGET: ${{ matrix.target }} - run: | - ./rs/scripts/package-binary.sh \ - --crate moq-relay \ - --bin moq-relay \ - --binary "target/${TARGET}/release/moq-relay" \ - --bare \ - --version "$VERSION" \ - --target "$TARGET" \ - --output dist - - - name: Package .deb (Ubuntu 22.04 toolchain, glibc 2.35) - shell: bash - env: - VERSION: ${{ steps.parse.outputs.version }} - ARCH: ${{ matrix.deb-arch }} - BINARY_PATH: target/${{ matrix.target }}/release/moq-relay - run: rs/scripts/package-nfpm.sh packaging/moq-relay/nfpm.yaml deb dist/ - - - name: Package .rpm - shell: bash - env: - VERSION: ${{ steps.parse.outputs.version }} - ARCH: ${{ matrix.rpm-arch }} - BINARY_PATH: target/${{ matrix.target }}/release/moq-relay - run: rs/scripts/package-nfpm.sh packaging/moq-relay/nfpm.yaml rpm dist/ - - - name: Upload artifacts - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: moq-relay-${{ matrix.target }} - path: dist/* - - build-tarball-macos: - name: Build macOS tarball (${{ matrix.target }}) - runs-on: ${{ matrix.os }} - - strategy: - fail-fast: false - matrix: - include: - - target: aarch64-apple-darwin - os: macos-latest - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - fetch-depth: 0 - persist-credentials: false - - - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main - with: - determinate: false - # Trust the flake's cachix substituter, as check.yml does, so the dev - # shell is substituted rather than built from source. - extra-conf: | - extra-substituters = https://kixelated.cachix.org - extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= - - - name: Parse version - id: parse - shell: bash - run: .github/scripts/release.sh parse-version moq-relay - - - name: Build and package tarball - shell: bash - run: | - ./rs/scripts/package-binary.sh \ - --crate moq-relay \ - --target ${{ matrix.target }} \ - --version ${{ steps.parse.outputs.version }} \ - --output dist - - - name: Upload artifact - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: moq-relay-${{ matrix.target }} - path: dist/* - - build-windows: - name: Build Windows zip (${{ matrix.target }}) - runs-on: windows-latest - - strategy: - fail-fast: false - matrix: - include: - - target: x86_64-pc-windows-msvc - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - with: - targets: ${{ matrix.target }} - - # aws-lc-rs assembles its x86_64 crypto with NASM on Windows. - - name: Install NASM - shell: pwsh - run: | - choco install nasm -y --no-progress - "C:\Program Files\NASM" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append - - - name: Parse version - id: parse - shell: bash - run: .github/scripts/release.sh parse-version moq-relay - - - name: Build and package zip - shell: bash - run: | - ./rs/scripts/package-windows.sh \ - --crate moq-relay \ - --target ${{ matrix.target }} \ - --version ${{ steps.parse.outputs.version }} \ - --output dist - - - name: Upload artifact - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: moq-relay-${{ matrix.target }} - path: dist/* - release: - name: Release - needs: [build, build-tarball-macos, build-windows] - if: github.ref_type == 'tag' - runs-on: ubuntu-latest + uses: ./.github/workflows/release-binary.yml + with: + crate: moq-relay + bin: moq-relay permissions: contents: write actions: write - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - fetch-depth: 0 - persist-credentials: false - - - name: Parse version - id: parse - run: .github/scripts/release.sh parse-version moq-relay - - - name: Find previous tag - id: prev_tag - run: .github/scripts/release.sh prev-tag moq-relay - - - name: Download artifacts - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 - with: - path: artifacts - merge-multiple: true - - - name: Create or update release - env: - GH_TOKEN: ${{ github.token }} - RELEASE_TAG: ${{ github.ref_name }} - RELEASE_TITLE: "moq-relay v${{ steps.parse.outputs.version }}" - RELEASE_PREV_TAG: ${{ steps.prev_tag.outputs.tag }} - run: .github/scripts/release.sh create artifacts - - - name: Trigger apt/rpm repo publish - env: - GH_TOKEN: ${{ github.token }} - TAG: ${{ github.ref_name }} - run: .github/scripts/trigger-repo-publish.sh diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index 4d8ee86658d..f020a65d191 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -75,45 +75,43 @@ jobs: # over independent observers of the new live broadcast map. - name: JS origin broadcast map benchmark if: ${{ !cancelled() }} - run: | - nix develop --command bun install --frozen-lockfile - nix develop --command bun js/net/bench/broadcasts.ts + run: nix develop --command just js bench broadcasts # A route above several interest heads lands once per head, so its re-price # should expose any slope over heads times received routes. - name: JS origin announce forwarding benchmark if: ${{ !cancelled() }} - run: nix develop --command bun js/net/bench/forward.ts + run: nix develop --command just js bench forward # Fails if reading a fragmented frame costs more per byte as the frame grows. - name: JS stream reader benchmark if: ${{ !cancelled() }} - run: nix develop --command bun js/net/bench/reader.ts + run: nix develop --command just js bench reader # Fails if a chunk carrying many small frames costs as much per frame as one # carrying a single frame, on either the lite or moq-transport group stream, # which means decoding went back to a wakeup per frame. - name: JS group frame benchmark if: ${{ !cancelled() }} - run: nix develop --command bun js/net/bench/frames.ts + run: nix develop --command just js bench frames # Times one varint encode and decode per wire format. No threshold: it only # has to keep running, and its numbers are the baseline for the generated codec. - name: JS varint benchmark if: ${{ !cancelled() }} - run: nix develop --command bun js/net/bench/varint.ts + run: nix develop --command just js bench varint # Bytes and time for lite-06 against lite-07 frames, groups, and requests. No # threshold: it only has to keep running. - name: JS lite varint benchmark if: ${{ !cancelled() }} - run: nix develop --command bun js/net/bench/lite-varint.ts + run: nix develop --command just js bench lite-varint # Fails if publishing a group costs more as the track retains more groups, # which means the latency guard or the cache went back to scanning them all. - name: JS track retention benchmark if: ${{ !cancelled() }} - run: nix develop --command bun js/net/bench/track.ts + run: nix develop --command just js bench track # Runs each moq-net Criterion routine once, so a bench that panics (an # unparsable version, a shape that deadlocks) fails here instead of on the @@ -172,7 +170,8 @@ jobs: matrix: # `rs uring` is a separate feature compile (off the default set) and # kernel-gated below 6.12. The embedding tests for io_uring live there. - recipe: ["rs doctest --workspace", "rs loom", "test drill-sensitivity", "rs uring"] + # `gh test` exercises the release tooling, which no pull request runs. + recipe: ["rs doctest --workspace", "rs loom", "test drill-sensitivity", "rs uring", "gh test"] steps: - name: Free disk space uses: jlumbroso/free-disk-space@ceedf095f4ec1a097402bc6bd80831f2e1a6fde6 # main diff --git a/.github/workflows/obs.yml b/.github/workflows/obs.yml index e4c696d0c06..53e3de4a7db 100644 --- a/.github/workflows/obs.yml +++ b/.github/workflows/obs.yml @@ -66,6 +66,7 @@ on: types: [opened, synchronize, reopened, closed] paths: - "cpp/obs/**" + - "sh/obs/**" - "rs/libmoq/**" - "doc/lib/c/**" - "doc/lib/samples.sh" @@ -159,8 +160,10 @@ jobs: - name: Install Rust uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable + - uses: ./.github/actions/just + - name: Build shell: bash env: TARGET: ${{ matrix.target }} - run: ./cpp/obs/build.sh --target "$TARGET" --output "$RUNNER_TEMP/obs" + run: just obs package --target "$TARGET" --output "$RUNNER_TEMP/obs" diff --git a/.github/workflows/platform.yml b/.github/workflows/platform.yml index 8abd8d483f5..819d731bb63 100644 --- a/.github/workflows/platform.yml +++ b/.github/workflows/platform.yml @@ -34,6 +34,7 @@ on: - "Cargo.lock" - "rust-toolchain.toml" - "justfile" + - "sh/**" - ".github/workflows/platform.yml" pull_request: # `closed` is here only so merging/closing a PR cancels its in-flight run @@ -46,6 +47,7 @@ on: - "Cargo.lock" - "rust-toolchain.toml" - "justfile" + - "sh/**" - ".github/workflows/platform.yml" concurrency: @@ -59,9 +61,6 @@ concurrency: # newest pending run, so queued merges still coalesce. cancel-in-progress: ${{ github.event_name == 'pull_request' }} -env: - JUST_VERSION: 1.52.0 - jobs: windows: name: Windows @@ -87,12 +86,7 @@ jobs: choco install nasm -y --no-progress "C:\Program Files\NASM" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append - # A checksummed release binary, where `cargo install` would spend ~2 minutes - # building just from source. - - name: Install just - uses: taiki-e/install-action@4cef1412cce204788f482e778a0b9187f9626a29 # v2.87.21 - with: - tool: just@${{ env.JUST_VERSION }} + - uses: ./.github/actions/just - name: Check shell: bash @@ -116,10 +110,7 @@ jobs: - name: Install Rust uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - - name: Install just - uses: taiki-e/install-action@4cef1412cce204788f482e778a0b9187f9626a29 # v2.87.21 - with: - tool: just@${{ env.JUST_VERSION }} + - uses: ./.github/actions/just - name: Check env: diff --git a/.github/workflows/release-binary.yml b/.github/workflows/release-binary.yml new file mode 100644 index 00000000000..88350386f05 --- /dev/null +++ b/.github/workflows/release-binary.yml @@ -0,0 +1,258 @@ +name: release-binary + +# Builds, packages, and (on a tag) releases one workspace binary. moq-cli.yml +# and moq-relay.yml call it; they keep the tag trigger and the workflow name +# that alert.yml, release-brew.yml, and release-winget.yml match on. + +on: + workflow_call: + inputs: + crate: + description: "Cargo package to build, e.g. moq-cli" + required: true + type: string + bin: + description: "Executable the package ships, e.g. moq" + required: true + type: string + +permissions: + contents: read + +env: + CRATE: ${{ inputs.crate }} + BIN: ${{ inputs.bin }} + +jobs: + build: + name: Build (${{ matrix.target }}) + runs-on: ${{ matrix.runs-on }} + + strategy: + fail-fast: false + matrix: + include: + # Native runners. Each binary is built on the same arch it ships + # for, so the .deb/.rpm linkage matches the distro's glibc on the + # oldest LTS we support (Ubuntu 22.04 / AlmaLinux 9). + - target: x86_64-unknown-linux-gnu + runs-on: ubuntu-22.04 + deb-arch: amd64 + rpm-arch: x86_64 + - target: aarch64-unknown-linux-gnu + runs-on: ubuntu-22.04-arm + deb-arch: arm64 + rpm-arch: aarch64 + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - uses: ./.github/actions/just + + - name: Install Rust + uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable + with: + targets: ${{ matrix.target }} + + - name: Parse version + id: parse + shell: bash + run: just gh release parse-version "$CRATE" + + - name: Set up packaging tools + uses: ./.github/actions/setup-packaging + + - name: Build (release, glibc 2.34) + shell: bash + # Pin to glibc 2.34 so one binary covers Ubuntu 22.04+ (.deb) + # and AlmaLinux/RHEL/Rocky 9+ (.rpm). + run: cargo zigbuild --locked --release --target ${{ matrix.target }}.2.34 -p "$CRATE" + + - name: Package release assets + shell: bash + env: + VERSION: ${{ steps.parse.outputs.version }} + TARGET: ${{ matrix.target }} + run: | + just rs package-binary \ + --crate "$CRATE" \ + --bin "$BIN" \ + --binary "target/${TARGET}/release/${BIN}" \ + --bare \ + --version "$VERSION" \ + --target "$TARGET" \ + --output dist + + # A transition.yaml beside nfpm.yaml is a deb-only package that keeps + # apt upgrades following a renamed package. + - name: Package .deb (Ubuntu 22.04 toolchain) + shell: bash + env: + VERSION: ${{ steps.parse.outputs.version }} + ARCH: ${{ matrix.deb-arch }} + BINARY_PATH: target/${{ matrix.target }}/release/${{ inputs.bin }} + run: | + just rs package-nfpm "packaging/$CRATE/nfpm.yaml" deb dist/ + if [[ -f "packaging/$CRATE/transition.yaml" ]]; then + just rs package-nfpm "packaging/$CRATE/transition.yaml" deb dist/ + fi + + - name: Package .rpm + shell: bash + env: + VERSION: ${{ steps.parse.outputs.version }} + ARCH: ${{ matrix.rpm-arch }} + BINARY_PATH: target/${{ matrix.target }}/release/${{ inputs.bin }} + run: just rs package-nfpm "packaging/$CRATE/nfpm.yaml" rpm dist/ + + - name: Upload artifacts + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 + with: + name: ${{ inputs.crate }}-${{ matrix.target }} + path: dist/* + + build-tarball-macos: + name: Build macOS tarball (${{ matrix.target }}) + runs-on: ${{ matrix.os }} + + strategy: + fail-fast: false + matrix: + include: + - target: aarch64-apple-darwin + os: macos-latest + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + persist-credentials: false + + - uses: ./.github/actions/just + + - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main + with: + determinate: false + # Trust the flake's cachix substituter, as check.yml does, so the dev + # shell is substituted rather than built from source. + extra-conf: | + extra-substituters = https://kixelated.cachix.org + extra-trusted-public-keys = kixelated.cachix.org-1:CmFcV0lyM6KuVM2m9mih0q4SrAa0XyCsiM7GHrz3KKk= + + - name: Parse version + id: parse + shell: bash + run: just gh release parse-version "$CRATE" + + - name: Build and package tarball + shell: bash + run: | + just rs package-binary \ + --crate "$CRATE" \ + --bin "$BIN" \ + --target ${{ matrix.target }} \ + --version ${{ steps.parse.outputs.version }} \ + --output dist + + - name: Upload artifact + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 + with: + name: ${{ inputs.crate }}-${{ matrix.target }} + path: dist/* + + build-windows: + name: Build Windows zip (${{ matrix.target }}) + runs-on: windows-latest + + strategy: + fail-fast: false + matrix: + include: + - target: x86_64-pc-windows-msvc + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - uses: ./.github/actions/just + + - name: Install Rust + uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable + with: + targets: ${{ matrix.target }} + + # aws-lc-rs assembles its x86_64 crypto with NASM on Windows. + - name: Install NASM + shell: pwsh + run: | + choco install nasm -y --no-progress + "C:\Program Files\NASM" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append + + - name: Parse version + id: parse + shell: bash + run: just gh release parse-version "$CRATE" + + - name: Build and package zip + shell: bash + run: | + just rs package-windows \ + --crate "$CRATE" \ + --bin "$BIN" \ + --target ${{ matrix.target }} \ + --version ${{ steps.parse.outputs.version }} \ + --output dist + + - name: Upload artifact + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 + with: + name: ${{ inputs.crate }}-${{ matrix.target }} + path: dist/* + + release: + name: Release + needs: [build, build-tarball-macos, build-windows] + if: github.ref_type == 'tag' + runs-on: ubuntu-latest + permissions: + contents: write + actions: write + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + persist-credentials: false + + - uses: ./.github/actions/just + + - name: Parse version + id: parse + run: just gh release parse-version "$CRATE" + + - name: Find previous tag + id: prev_tag + run: just gh release prev-tag "$CRATE" + + - name: Download artifacts + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 + with: + path: artifacts + merge-multiple: true + + - name: Create or update release + env: + GH_TOKEN: ${{ github.token }} + RELEASE_TAG: ${{ github.ref_name }} + RELEASE_TITLE: "${{ inputs.crate }} v${{ steps.parse.outputs.version }}" + RELEASE_PREV_TAG: ${{ steps.prev_tag.outputs.tag }} + run: just gh release create artifacts + + - name: Trigger apt/rpm repo publish + env: + GH_TOKEN: ${{ github.token }} + TAG: ${{ github.ref_name }} + run: just gh trigger-repo-publish diff --git a/.github/workflows/release-brew.yml b/.github/workflows/release-brew.yml index 20fe7211562..5e8594de054 100644 --- a/.github/workflows/release-brew.yml +++ b/.github/workflows/release-brew.yml @@ -41,6 +41,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Parse crate and version id: parse env: @@ -98,7 +100,7 @@ jobs: VERSION: ${{ steps.parse.outputs.version }} run: | mkdir -p rendered - ./.github/scripts/render-formula.sh \ + just gh formula \ --template ".github/homebrew/Formula/${CRATE}.rb.tmpl" \ --version "$VERSION" \ --release-dir release-assets \ @@ -156,7 +158,7 @@ jobs: EOF fi - python3 ../.github/scripts/install-formula.py "$CRATE" "../rendered/${CRATE}.rb" . + just gh install-formula "$CRATE" "rendered/${CRATE}.rb" homebrew-tap if git diff --quiet && [[ -z "$(git status --porcelain)" ]]; then echo "No changes to commit (formula already up to date)." diff --git a/.github/workflows/release-dart-ffi.yml b/.github/workflows/release-dart-ffi.yml index 73dd54b38af..4e75507115c 100644 --- a/.github/workflows/release-dart-ffi.yml +++ b/.github/workflows/release-dart-ffi.yml @@ -19,8 +19,9 @@ on: pull_request: paths: - ".github/workflows/release-dart-ffi.yml" + - ".github/workflows/release-ffi.yml" - "dart/moq_ffi/**" - - "dart/scripts/**" + - "sh/dart/**" - "rs/moq-ffi/build.sh" permissions: @@ -34,117 +35,71 @@ concurrency: group: release-dart-ffi-${{ github.ref_type == 'tag' && 'publish' || github.ref }} cancel-in-progress: ${{ github.ref_type != 'tag' }} -env: - CARGO_NDK_VERSION: 4.1.2 - jobs: - parse-version: - name: Parse version + ffi: + name: moq-ffi + uses: ./.github/workflows/release-ffi.yml + with: + language: dart + # The raw bindings are checked in under dart/moq_ffi, so none here. + bindings: false + default-features: false + targets: >- + [ + "aarch64-linux-android", + "armv7-linux-androideabi", + "x86_64-linux-android", + "x86_64-unknown-linux-gnu", + "aarch64-unknown-linux-gnu", + "aarch64-apple-darwin", + "x86_64-apple-darwin", + "aarch64-apple-ios", + "aarch64-apple-ios-sim", + "x86_64-apple-ios", + "x86_64-pc-windows-msvc" + ] + + # hook/build.dart downloads moq-ffi--- and its + # .sha256 from the release, so each target's shared library is renamed flat. + assets: + name: Stage Native Assets + needs: [ffi] runs-on: ubuntu-latest - outputs: - version: ${{ steps.parse.outputs.version }} steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Parse version - id: parse - run: .github/scripts/release.sh parse-version moq-ffi - - build: - name: Build Native Asset (${{ matrix.target }}) - needs: [parse-version] - runs-on: ${{ matrix.os }} - - strategy: - fail-fast: false - matrix: - include: - - target: aarch64-linux-android - os: ubuntu-latest - - target: armv7-linux-androideabi - os: ubuntu-latest - - target: x86_64-linux-android - os: ubuntu-latest - - target: x86_64-unknown-linux-gnu - os: ubuntu-latest - - target: aarch64-unknown-linux-gnu - os: ubuntu-latest - - target: aarch64-apple-darwin - os: macos-latest - - target: x86_64-apple-darwin - os: macos-latest - - target: aarch64-apple-ios - os: macos-latest - - target: aarch64-apple-ios-sim - os: macos-latest - - target: x86_64-apple-ios - os: macos-latest - - target: x86_64-pc-windows-msvc - os: windows-latest - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable + - name: Download per-target libs + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 with: - targets: ${{ matrix.target }} - - # No Rust cache: its entry would evict the store every pull request - # restores from the 10 GB budget. See cache.yml. - - - name: Install cross-compilation tools (Linux ARM64) - if: matrix.target == 'aarch64-unknown-linux-gnu' - run: | - sudo apt-get update - sudo apt-get install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu - - - name: Install cargo-ndk (Android) - if: contains(matrix.target, 'android') - run: cargo install --locked "cargo-ndk@$CARGO_NDK_VERSION" + path: libs-raw + pattern: dart-lib-* - - name: Build and stage asset - shell: bash + - name: Stage env: - BUILD_TARGET: ${{ matrix.target }} - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} - IPHONEOS_DEPLOYMENT_TARGET: ${{ contains(matrix.target, 'apple-ios') && '16.0' || '' }} + BUILD_VERSION: ${{ needs.ffi.outputs.version }} run: | - ./rs/moq-ffi/build.sh \ - --target "$BUILD_TARGET" \ - --version "$BUILD_VERSION" \ - --output dist \ - --no-default-features - - case "$BUILD_TARGET" in - *-apple-ios* | *-apple-darwin*) LIBRARY=libmoq_ffi.dylib ;; - *-windows-*) LIBRARY=moq_ffi.dll ;; - *) LIBRARY=libmoq_ffi.so ;; - esac - - NAME="moq-ffi-$BUILD_VERSION-$BUILD_TARGET-$LIBRARY" mkdir -p assets - cp "dist/moq-ffi-$BUILD_VERSION-$BUILD_TARGET/lib/$LIBRARY" "assets/$NAME" - if command -v sha256sum >/dev/null 2>&1; then - sha256sum "assets/$NAME" > "assets/$NAME.sha256" - else - shasum -a 256 "assets/$NAME" > "assets/$NAME.sha256" - fi - - - name: Upload Native Asset + for dir in libs-raw/dart-lib-*; do + target="${dir#libs-raw/dart-lib-}" + case "$target" in + *-apple-ios* | *-apple-darwin*) library=libmoq_ffi.dylib ;; + *-windows-*) library=moq_ffi.dll ;; + *) library=libmoq_ffi.so ;; + esac + name="moq-ffi-$BUILD_VERSION-$target-$library" + cp "$dir/$library" "assets/$name" + (cd assets && sha256sum "$name" > "$name.sha256") + done + ls -la assets + + - name: Upload Native Assets uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 with: - name: dart-asset-${{ matrix.target }} + name: dart-assets path: assets/* package: name: Check pub package - needs: [parse-version] + needs: [ffi] runs-on: ubuntu-latest steps: @@ -152,13 +107,15 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - uses: dart-lang/setup-dart@6afc89df92d6eb3834022f73cd65adc8cdfcb92d # v1.8.1 - name: Stage and check package env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} + BUILD_VERSION: ${{ needs.ffi.outputs.version }} run: | - ./dart/scripts/package.sh \ + just dart package \ --package moq_ffi \ --version "$BUILD_VERSION" \ --output release-out @@ -175,7 +132,7 @@ jobs: release: name: Attach Native Assets - needs: [parse-version, build] + needs: [ffi, assets] if: github.ref_type == 'tag' runs-on: ubuntu-latest permissions: @@ -187,29 +144,30 @@ jobs: fetch-depth: 0 persist-credentials: false + - uses: ./.github/actions/just + - name: Find previous tag id: prev_tag - run: .github/scripts/release.sh prev-tag moq-ffi + run: just gh release prev-tag moq-ffi - name: Download Native Assets uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 with: + name: dart-assets path: artifacts - pattern: dart-asset-* - merge-multiple: true - name: Create or update release env: GH_TOKEN: ${{ github.token }} RELEASE_TAG: ${{ github.ref_name }} - RELEASE_TITLE: "moq-ffi v${{ needs.parse-version.outputs.version }}" + RELEASE_TITLE: "moq-ffi v${{ needs.ffi.outputs.version }}" RELEASE_PREV_TAG: ${{ steps.prev_tag.outputs.tag }} RELEASE_CHECKSUMS: SHA256SUMS-dart - run: .github/scripts/release.sh create artifacts + run: just gh release create artifacts publish: name: Publish moq_ffi to pub.dev - needs: [parse-version, package, release] + needs: [ffi, package, release] if: github.ref_type == 'tag' runs-on: ubuntu-latest environment: @@ -228,5 +186,5 @@ jobs: - name: Publish env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} + BUILD_VERSION: ${{ needs.ffi.outputs.version }} run: cd "package/moq_ffi-$BUILD_VERSION" && dart pub publish --force diff --git a/.github/workflows/release-dart.yml b/.github/workflows/release-dart.yml index 2c099bc3188..3578ae386c2 100644 --- a/.github/workflows/release-dart.yml +++ b/.github/workflows/release-dart.yml @@ -12,7 +12,7 @@ on: paths: - ".github/workflows/release-dart.yml" - "dart/moq/**" - - "dart/scripts/**" + - "sh/dart/**" permissions: contents: read @@ -37,6 +37,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - uses: dart-lang/setup-dart@6afc89df92d6eb3834022f73cd65adc8cdfcb92d # v1.8.1 - name: Resolve version @@ -47,7 +49,7 @@ jobs: if [[ "$EVENT_NAME" == "pull_request" ]]; then VERSION=$(sed -n 's/^version: //p' dart/moq/pubspec.yaml | head -1) else - .github/scripts/release.sh parse-version moq-dart + just gh release parse-version moq-dart exit 0 fi echo "version=$VERSION" >> "$GITHUB_OUTPUT" @@ -69,7 +71,7 @@ jobs: env: BUILD_VERSION: ${{ steps.version.outputs.version }} run: | - ./dart/scripts/package.sh \ + just dart package \ --package moq \ --version "$BUILD_VERSION" \ --output release-out diff --git a/.github/workflows/release-ffi.yml b/.github/workflows/release-ffi.yml new file mode 100644 index 00000000000..ff7cfc85aee --- /dev/null +++ b/.github/workflows/release-ffi.yml @@ -0,0 +1,169 @@ +name: release-ffi + +# Builds rs/moq-ffi for each requested target and generates its UniFFI +# bindings. The release-{dart,go,kt,swift}-ffi.yml callers package and publish; +# they keep the moq-ffi-v* tag trigger and the workflow name that alert.yml and +# the workflow_run chains match on. +# +# Uploads, all prefixed by `language` so callers sharing one nightly run never +# collide: +# -lib- the target's native libraries (the lib/ directory) +# -bindings dist/bindings//, when `bindings` is set + +on: + workflow_call: + inputs: + language: + description: "Binding language and artifact prefix, e.g. kotlin" + required: true + type: string + targets: + description: "JSON array of Rust targets to build" + required: true + type: string + bindings: + description: "Generate and upload the bindings for `language`" + type: boolean + default: true + default-features: + description: "Build moq-ffi with its default features (audio and video)" + type: boolean + default: true + outputs: + version: + description: "moq-ffi version, from the tag or (off a tag) rs/moq-ffi/Cargo.toml" + value: ${{ jobs.parse-version.outputs.version }} + +permissions: + contents: read + +# Pinned rather than "latest": `--locked` only fixes the tool's own +# dependencies, not which version of the tool cargo selects. +env: + CARGO_NDK_VERSION: 4.1.2 + +jobs: + parse-version: + name: Parse version + runs-on: ubuntu-latest + outputs: + version: ${{ steps.parse.outputs.version }} + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - uses: ./.github/actions/just + + - name: Parse version + id: parse + run: just gh release parse-version moq-ffi + + build: + name: Build moq-ffi (${{ matrix.target }}) + needs: [parse-version] + runs-on: ${{ contains(matrix.target, '-apple-') && 'macos-latest' || contains(matrix.target, '-windows-') && 'windows-latest' || 'ubuntu-latest' }} + + strategy: + fail-fast: false + matrix: + target: ${{ fromJSON(inputs.targets) }} + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - uses: ./.github/actions/just + + - name: Install Rust + uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable + with: + targets: ${{ matrix.target }} + + # No Rust cache: its entry would evict the store every pull request + # restores from the 10 GB budget. See cache.yml. + + - name: Install cross-compilation tools (Linux ARM64) + if: matrix.target == 'aarch64-unknown-linux-gnu' + run: | + sudo apt-get update + # g++ as well as gcc: moq-video's openh264 fallback is C++, and + # cc-rs looks for aarch64-linux-gnu-g++ by name. + sudo apt-get install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu + + - name: Install cargo-ndk (Android) + if: contains(matrix.target, 'android') + run: cargo install --locked "cargo-ndk@$CARGO_NDK_VERSION" + + - name: Build + shell: bash + env: + BUILD_TARGET: ${{ matrix.target }} + BUILD_VERSION: ${{ needs.parse-version.outputs.version }} + DEFAULT_FEATURES: ${{ inputs.default-features }} + # Set iOS deployment target to avoid ___chkstk_darwin linker errors. + IPHONEOS_DEPLOYMENT_TARGET: ${{ contains(matrix.target, 'apple-ios') && '16.0' || '' }} + run: | + args=(--target "$BUILD_TARGET" --version "$BUILD_VERSION" --output dist) + if [[ "$DEFAULT_FEATURES" == false ]]; then + args+=(--no-default-features) + fi + just rs package-ffi "${args[@]}" + + - name: Upload lib + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 + with: + name: ${{ inputs.language }}-lib-${{ matrix.target }} + # Only the lib/ contents, so a caller's download is /. + path: dist/moq-ffi-${{ needs.parse-version.outputs.version }}-${{ matrix.target }}/lib/ + + bindings: + name: Generate bindings + needs: [parse-version] + if: inputs.bindings + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - uses: ./.github/actions/just + + - name: Install Rust + uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable + + # No Rust cache: its entry would evict the store every pull request + # restores from the 10 GB budget. See cache.yml. + + # Go uses a third-party generator; build.sh skips Go when it is absent. + - name: Install uniffi-bindgen-go + if: inputs.language == 'go' + env: + # A fork until NordSecurity ships a uniffi 0.32 generator; see flake.nix. + # The revision is v0.10.0-kixelated.1+v0.32.0. + UNIFFI_BINDGEN_GO_REPO: https://github.com/kixelated/uniffi-bindgen-go + UNIFFI_BINDGEN_GO_REV: v0.10.0-kixelated.1+v0.32.0 + run: | + cargo install --locked uniffi-bindgen-go \ + --git "$UNIFFI_BINDGEN_GO_REPO" \ + --rev "$UNIFFI_BINDGEN_GO_REV" + + - name: Generate bindings + env: + BUILD_VERSION: ${{ needs.parse-version.outputs.version }} + run: | + just rs package-ffi \ + --bindings-only \ + --version "$BUILD_VERSION" \ + --output dist + + - name: Upload bindings + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 + with: + name: ${{ inputs.language }}-bindings + path: dist/bindings/${{ inputs.language }}/ + # A language build.sh does not generate would otherwise upload nothing. + if-no-files-found: error diff --git a/.github/workflows/release-go-ffi.yml b/.github/workflows/release-go-ffi.yml index 30c3ea56edd..e35e940046b 100644 --- a/.github/workflows/release-go-ffi.yml +++ b/.github/workflows/release-go-ffi.yml @@ -16,10 +16,11 @@ on: pull_request: paths: - ".github/workflows/release-go-ffi.yml" - - ".github/scripts/release.sh" + - ".github/workflows/release-ffi.yml" + - "sh/gh/release.sh" - "go/ffi/**" - - "go/scripts/package-ffi.sh" - - "go/scripts/publish-ffi.sh" + - "sh/go/package-ffi.sh" + - "sh/go/publish-ffi.sh" - "rs/moq-ffi/build.sh" permissions: @@ -33,132 +34,32 @@ concurrency: group: release-go-ffi-${{ github.ref_type == 'tag' && 'publish' || github.ref }} cancel-in-progress: ${{ github.ref_type != 'tag' }} -env: - # A fork until NordSecurity ships a uniffi 0.32 generator; see flake.nix. - # The revision is v0.10.0-kixelated.1+v0.32.0. - UNIFFI_BINDGEN_GO_REPO: https://github.com/kixelated/uniffi-bindgen-go - UNIFFI_BINDGEN_GO_REV: v0.10.0-kixelated.1+v0.32.0 - jobs: - parse-version: - name: Parse version - runs-on: ubuntu-latest - outputs: - version: ${{ steps.parse.outputs.version }} - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 - with: - persist-credentials: false - - - name: Parse version - id: parse - run: .github/scripts/release.sh parse-version moq-ffi - - build: - name: Build moq-ffi (${{ matrix.target }}) - needs: [parse-version] - runs-on: ${{ matrix.os }} - - strategy: - fail-fast: false - matrix: - include: - - target: x86_64-unknown-linux-gnu - os: ubuntu-latest - - target: aarch64-unknown-linux-gnu - os: ubuntu-latest - - target: aarch64-apple-darwin - os: macos-latest - - target: x86_64-pc-windows-msvc - os: windows-latest - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - with: - targets: ${{ matrix.target }} - - # No Rust cache: its entry would evict the store every pull request - # restores from the 10 GB budget. See cache.yml. - - - name: Install cross-compilation tools (Linux ARM64) - if: matrix.target == 'aarch64-unknown-linux-gnu' - run: | - sudo apt-get update - # g++ as well as gcc: moq-video's openh264 fallback is C++, and - # cc-rs looks for aarch64-linux-gnu-g++ by name. - sudo apt-get install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu - - - name: Build - shell: bash - env: - BUILD_TARGET: ${{ matrix.target }} - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} - run: | - ./rs/moq-ffi/build.sh \ - --target "$BUILD_TARGET" \ - --version "$BUILD_VERSION" \ - --output dist - - - name: Upload lib - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: go-lib-${{ matrix.target }} - # package.sh expects /; upload just lib/ contents. - path: dist/moq-ffi-${{ needs.parse-version.outputs.version }}-${{ matrix.target }}/lib/ - - bindings: - name: Generate bindings - needs: [parse-version] - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - - # No Rust cache: its entry would evict the store every pull request - # restores from the 10 GB budget. See cache.yml. - - - name: Install uniffi-bindgen-go - run: | - cargo install --locked uniffi-bindgen-go \ - --git "$UNIFFI_BINDGEN_GO_REPO" \ - --rev "$UNIFFI_BINDGEN_GO_REV" - - - name: Generate bindings - env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} - run: | - ./rs/moq-ffi/build.sh \ - --bindings-only \ - --version "$BUILD_VERSION" \ - --output dist - - - name: Upload bindings - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: go-bindings - path: dist/bindings/go/ + ffi: + name: moq-ffi + uses: ./.github/workflows/release-ffi.yml + with: + language: go + targets: >- + [ + "x86_64-unknown-linux-gnu", + "aarch64-unknown-linux-gnu", + "aarch64-apple-darwin", + "x86_64-pc-windows-msvc" + ] package: name: Package - needs: [parse-version, build, bindings] + needs: [ffi] runs-on: ubuntu-latest steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false + - uses: ./.github/actions/just + - name: Download per-target libs uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 with: @@ -200,9 +101,9 @@ jobs: - name: Package env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} + BUILD_VERSION: ${{ needs.ffi.outputs.version }} run: | - ./go/scripts/package-ffi.sh \ + just go package-ffi \ --version "$BUILD_VERSION" \ --source-dir go/ffi \ --lib-dir libs \ @@ -217,15 +118,17 @@ jobs: publish: name: Publish to Go module mirror - needs: [package, parse-version] + needs: [ffi, package] runs-on: ubuntu-latest if: github.ref_type == 'tag' steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false + - uses: ./.github/actions/just + - name: Generate moq-bot token uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3 id: token @@ -245,24 +148,26 @@ jobs: - name: Publish to moq-dev/moq-go-ffi mirror env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} + BUILD_VERSION: ${{ needs.ffi.outputs.version }} # Token is minted fresh per run, expires in 1 hour, never at rest. GO_FFI_MIRROR_TOKEN: ${{ steps.token.outputs.token }} GIT_AUTHOR_NAME: moq-bot GIT_AUTHOR_EMAIL: moq-bot[bot]@users.noreply.github.com - run: ./go/scripts/publish-ffi.sh + run: just go publish-ffi publish-dry-run: name: Publish dry-run - needs: [package, parse-version] + needs: [ffi, package] runs-on: ubuntu-latest if: github.ref_type != 'tag' steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false + - uses: ./.github/actions/just + - name: Download package uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 with: @@ -271,5 +176,5 @@ jobs: - name: Dry-run publish to mirror env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} - run: ./go/scripts/publish-ffi.sh --dry-run + BUILD_VERSION: ${{ needs.ffi.outputs.version }} + run: just go publish-ffi --dry-run diff --git a/.github/workflows/release-go.yml b/.github/workflows/release-go.yml index 0f87ed9b743..bb817841acd 100644 --- a/.github/workflows/release-go.yml +++ b/.github/workflows/release-go.yml @@ -66,6 +66,8 @@ jobs: fetch-depth: 0 persist-credentials: false + - uses: ./.github/actions/just + - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 with: go-version: "1.23" @@ -105,7 +107,7 @@ jobs: if: github.event_name == 'push' env: FFI_VERSION: ${{ steps.ffi.outputs.version }} - run: .github/scripts/release.sh ffi-unreleased "$FFI_VERSION" + run: just gh release ffi-unreleased "$FFI_VERSION" # Skip on unreleased ffi changes, and when the pinned ffi's mirror tag is # missing (release-plz merged but Release Go FFI hasn't published yet): @@ -160,7 +162,7 @@ jobs: LINE: ${{ steps.line.outputs.line }} FFI_VERSION: ${{ steps.ffi.outputs.version }} run: | - ./go/scripts/package-wrapper.sh --line "$LINE" --ffi-version "$FFI_VERSION" --output release-out + just go package-wrapper --line "$LINE" --ffi-version "$FFI_VERSION" --output release-out - name: Upload wrapper module if: steps.gate.outputs.skip != 'true' @@ -180,6 +182,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Generate moq-bot token uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3 id: token @@ -203,4 +207,4 @@ jobs: GO_MIRROR_TOKEN: ${{ steps.token.outputs.token }} GIT_AUTHOR_NAME: moq-bot GIT_AUTHOR_EMAIL: moq-bot[bot]@users.noreply.github.com - run: ./go/scripts/publish-wrapper.sh + run: just go publish-wrapper diff --git a/.github/workflows/release-kt-ffi.yml b/.github/workflows/release-kt-ffi.yml index 7694fb4b839..0b48e10b929 100644 --- a/.github/workflows/release-kt-ffi.yml +++ b/.github/workflows/release-kt-ffi.yml @@ -20,131 +20,27 @@ concurrency: group: release-kt-ffi cancel-in-progress: false -# Pinned rather than "latest": `--locked` only fixes the tool's own -# dependencies, not which version of the tool cargo selects. -env: - CARGO_NDK_VERSION: 4.1.2 - jobs: - parse-version: - name: Parse version - runs-on: ubuntu-latest - outputs: - version: ${{ steps.parse.outputs.version }} - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Parse version - id: parse - run: .github/scripts/release.sh parse-version moq-ffi - - build: - name: Build moq-ffi (${{ matrix.target }}) - needs: [parse-version] - runs-on: ${{ matrix.os }} - - strategy: - fail-fast: false - matrix: - include: - # Android - - target: aarch64-linux-android - os: ubuntu-latest - - target: armv7-linux-androideabi - os: ubuntu-latest - - target: x86_64-linux-android - os: ubuntu-latest - # Desktop JVM - - target: x86_64-unknown-linux-gnu - os: ubuntu-latest - - target: aarch64-unknown-linux-gnu - os: ubuntu-latest - - target: aarch64-apple-darwin - os: macos-latest - - target: x86_64-pc-windows-msvc - os: windows-latest - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - with: - targets: ${{ matrix.target }} - - # No Rust cache: its entry would evict the store every pull request - # restores from the 10 GB budget. See cache.yml. - - - name: Install cross-compilation tools (Linux ARM64) - if: matrix.target == 'aarch64-unknown-linux-gnu' - run: | - sudo apt-get update - # g++ as well as gcc: moq-video's openh264 fallback is C++, and - # cc-rs looks for aarch64-linux-gnu-g++ by name. - sudo apt-get install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu - - - name: Install cargo-ndk (Android) - if: contains(matrix.target, 'android') - run: cargo install --locked "cargo-ndk@$CARGO_NDK_VERSION" - - - name: Build - shell: bash - env: - BUILD_TARGET: ${{ matrix.target }} - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} - run: | - ./rs/moq-ffi/build.sh \ - --target "$BUILD_TARGET" \ - --version "$BUILD_VERSION" \ - --output dist - - - name: Upload lib - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: kotlin-lib-${{ matrix.target }} - # Upload only the lib/ contents; package.sh expects /. - path: dist/moq-ffi-${{ needs.parse-version.outputs.version }}-${{ matrix.target }}/lib/ - - bindings: - name: Generate bindings - needs: [parse-version] - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - - # No Rust cache: its entry would evict the store every pull request - # restores from the 10 GB budget. See cache.yml. - - - name: Generate bindings - env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} - run: | - ./rs/moq-ffi/build.sh \ - --bindings-only \ - --version "$BUILD_VERSION" \ - --output dist - - - name: Upload bindings - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: kotlin-bindings - # Upload only the kotlin subdir. - path: dist/bindings/kotlin/ + ffi: + name: moq-ffi + uses: ./.github/workflows/release-ffi.yml + with: + language: kotlin + # Android, then the desktop JVM. + targets: >- + [ + "aarch64-linux-android", + "armv7-linux-androideabi", + "x86_64-linux-android", + "x86_64-unknown-linux-gnu", + "aarch64-unknown-linux-gnu", + "aarch64-apple-darwin", + "x86_64-pc-windows-msvc" + ] package: name: Package and publish - needs: [parse-version, build, bindings] + needs: [ffi] runs-on: ubuntu-latest env: # Picked up by com.vanniktech.maven.publish via Gradle project properties. @@ -160,6 +56,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6.0.1 with: distribution: temurin @@ -197,9 +95,9 @@ jobs: - name: Stage native libs + bindings into the gradle module env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} + BUILD_VERSION: ${{ needs.ffi.outputs.version }} run: | - ./kt/scripts/package.sh \ + just kt package \ --version "$BUILD_VERSION" \ --lib-dir libs \ --bindings-dir bindings \ @@ -208,7 +106,7 @@ jobs: - name: Publish to Maven Central if: github.ref_type == 'tag' env: - MOQFFI_VERSION: ${{ needs.parse-version.outputs.version }} + MOQFFI_VERSION: ${{ needs.ffi.outputs.version }} ORG_GRADLE_PROJECT_signingInMemoryKey: ${{ secrets.SIGNING_KEY }} ORG_GRADLE_PROJECT_signingInMemoryKeyPassword: ${{ secrets.SIGNING_PASSWORD }} run: | diff --git a/.github/workflows/release-kt-lib.yml b/.github/workflows/release-kt-lib.yml index 92fcbf64220..f3947ef2ac5 100644 --- a/.github/workflows/release-kt-lib.yml +++ b/.github/workflows/release-kt-lib.yml @@ -30,7 +30,7 @@ on: - "kt/build.gradle.kts" - "kt/settings.gradle.kts" - ".github/workflows/release-kt-lib.yml" - - ".github/scripts/release.sh" + - "sh/gh/release.sh" pull_request: paths: - "kt/moq/**" @@ -38,7 +38,7 @@ on: - "kt/build.gradle.kts" - "kt/settings.gradle.kts" - ".github/workflows/release-kt-lib.yml" - - ".github/scripts/release.sh" + - "sh/gh/release.sh" - "rs/moq-ffi/build.sh" # Manual trigger so a wrapper bump can be published once the bindings it # depends on land on Maven Central (the guard below skips otherwise). @@ -75,6 +75,8 @@ jobs: fetch-depth: 0 persist-credentials: false + - uses: ./.github/actions/just + - name: Read moq.version id: version run: | @@ -103,18 +105,18 @@ jobs: - name: Check for unreleased FFI changes id: ffi-diff if: github.event_name != 'workflow_run' - run: .github/scripts/release.sh ffi-unreleased "${{ steps.ffi.outputs.version }}" + run: just gh release ffi-unreleased "${{ steps.ffi.outputs.version }}" - name: Check wrapper publication id: wrapper - run: .github/scripts/release.sh maven-exists dev.moq moq "${{ steps.version.outputs.version }}" + run: just gh release maven-exists dev.moq moq "${{ steps.version.outputs.version }}" # The bindings this checkout generates must be on Maven Central, or the # wrapper's POM range resolves to an older moq-ffi without them. - name: Check bindings publication id: bindings if: github.event_name != 'workflow_run' && steps.wrapper.outputs.exists != 'true' && steps.ffi-diff.outputs.unreleased != 'true' - run: .github/scripts/release.sh maven-exists dev.moq moq-ffi "${{ steps.ffi.outputs.version }}" + run: just gh release maven-exists dev.moq moq-ffi "${{ steps.ffi.outputs.version }}" - name: Decide publish id: decide @@ -167,6 +169,8 @@ jobs: ref: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_sha || github.sha }} persist-credentials: false + - uses: ./.github/actions/just + - name: Install Rust uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable @@ -178,7 +182,7 @@ jobs: env: BUILD_VERSION: ${{ needs.check-version.outputs.version }} run: | - ./rs/moq-ffi/build.sh --bindings-only --version "$BUILD_VERSION" --output dist + just rs package-ffi --bindings-only --version "$BUILD_VERSION" --output dist mkdir -p kt/moq-ffi/src/jvmAndAndroidMain/kotlin/uniffi/moq cp dist/bindings/kotlin/uniffi/moq/moq.kt \ kt/moq-ffi/src/jvmAndAndroidMain/kotlin/uniffi/moq/moq.kt @@ -202,7 +206,7 @@ jobs: - name: Recheck wrapper publication id: recheck if: github.event_name != 'pull_request' - run: .github/scripts/release.sh maven-exists dev.moq moq "${{ needs.check-version.outputs.version }}" + run: just gh release maven-exists dev.moq moq "${{ needs.check-version.outputs.version }}" - name: Publish to Maven Central if: github.event_name != 'pull_request' && steps.recheck.outputs.exists != 'true' diff --git a/.github/workflows/release-py-ffi.yml b/.github/workflows/release-py-ffi.yml index 2a79e7096ee..678abd24388 100644 --- a/.github/workflows/release-py-ffi.yml +++ b/.github/workflows/release-py-ffi.yml @@ -34,9 +34,11 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Parse version id: parse - run: .github/scripts/release.sh parse-version moq-ffi + run: just gh release parse-version moq-ffi # Maturin reads the wheel version from rs/moq-ffi/Cargo.toml (via # `dynamic = ["version"]` in pyproject.toml). If a tag is pushed by diff --git a/.github/workflows/release-py.yml b/.github/workflows/release-py.yml index 8e66b73f188..beb00e7dadf 100644 --- a/.github/workflows/release-py.yml +++ b/.github/workflows/release-py.yml @@ -19,7 +19,7 @@ on: paths: - "py/moq-rs/**" - ".github/workflows/release-py.yml" - - ".github/scripts/release.sh" + - "sh/gh/release.sh" workflow_run: workflows: ["Release Py FFI"] types: @@ -56,9 +56,11 @@ jobs: fetch-depth: 0 persist-credentials: false + - uses: ./.github/actions/just + - name: Read version id: version - run: .github/scripts/release.sh read-version py/moq-rs/pyproject.toml + run: just gh release read-version py/moq-rs/pyproject.toml - name: Resolve FFI version id: ffi @@ -78,14 +80,14 @@ jobs: if: github.event_name == 'push' env: FFI_VERSION: ${{ steps.ffi.outputs.version }} - run: .github/scripts/release.sh ffi-unreleased "$FFI_VERSION" + run: just gh release ffi-unreleased "$FFI_VERSION" - name: Check FFI on PyPI id: ffi-pypi if: github.event_name == 'push' && steps.ffi-gate.outputs.unreleased != 'true' env: FFI_VERSION: ${{ steps.ffi.outputs.version }} - run: .github/scripts/release.sh pypi-exists moq-ffi "$FFI_VERSION" + run: just gh release pypi-exists moq-ffi "$FFI_VERSION" - name: Unpublished FFI notice if: github.event_name == 'push' && steps.ffi-gate.outputs.unreleased != 'true' && steps.ffi-pypi.outputs.exists != 'true' @@ -100,7 +102,7 @@ jobs: id: pypi env: VERSION: ${{ steps.version.outputs.version }} - run: .github/scripts/release.sh pypi-exists moq-rs "$VERSION" + run: just gh release pypi-exists moq-rs "$VERSION" - uses: DeterminateSystems/nix-installer-action@1d87d45818068401a10cf16bdc5f00b24994a83f # main with: diff --git a/.github/workflows/release-swift-ffi.yml b/.github/workflows/release-swift-ffi.yml index bb4c757256c..afa2fbf175e 100644 --- a/.github/workflows/release-swift-ffi.yml +++ b/.github/workflows/release-swift-ffi.yml @@ -23,100 +23,16 @@ concurrency: cancel-in-progress: false jobs: - parse-version: - name: Parse version - runs-on: ubuntu-latest - outputs: - version: ${{ steps.parse.outputs.version }} - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Parse version - id: parse - run: .github/scripts/release.sh parse-version moq-ffi - - build: - name: Build moq-ffi (${{ matrix.target }}) - needs: [parse-version] - runs-on: macos-latest - - strategy: - fail-fast: false - matrix: - target: - - aarch64-apple-ios - - aarch64-apple-ios-sim - - aarch64-apple-darwin - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - with: - targets: ${{ matrix.target }} - - # No Rust cache: its entry would evict the store every pull request - # restores from the 10 GB budget. See cache.yml. - - - name: Build - shell: bash - env: - BUILD_TARGET: ${{ matrix.target }} - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} - # Set iOS deployment target to avoid ___chkstk_darwin linker errors. - IPHONEOS_DEPLOYMENT_TARGET: ${{ contains(matrix.target, 'apple-ios') && '16.0' || '' }} - run: | - ./rs/moq-ffi/build.sh \ - --target "$BUILD_TARGET" \ - --version "$BUILD_VERSION" \ - --output dist - - - name: Upload lib - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: swift-lib-${{ matrix.target }} - path: dist/moq-ffi-${{ needs.parse-version.outputs.version }}-${{ matrix.target }}/lib/ - - bindings: - name: Generate bindings - needs: [parse-version] - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Install Rust - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable - - # No Rust cache: its entry would evict the store every pull request - # restores from the 10 GB budget. See cache.yml. - - - name: Generate bindings - env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} - run: | - ./rs/moq-ffi/build.sh \ - --bindings-only \ - --version "$BUILD_VERSION" \ - --output dist - - - name: Upload bindings - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 - with: - name: swift-bindings - path: dist/bindings/swift/ + ffi: + name: moq-ffi + uses: ./.github/workflows/release-ffi.yml + with: + language: swift + targets: '["aarch64-apple-ios", "aarch64-apple-ios-sim", "aarch64-apple-darwin"]' package: name: Package - needs: [parse-version, build, bindings] + needs: [ffi] runs-on: macos-latest steps: @@ -124,6 +40,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Download per-target libs uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 with: @@ -147,9 +65,9 @@ jobs: - name: Package env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} + BUILD_VERSION: ${{ needs.ffi.outputs.version }} run: | - ./swift/scripts/package-ffi.sh \ + just swift package-ffi \ --version "$BUILD_VERSION" \ --lib-dir libs \ --bindings-dir bindings \ @@ -167,7 +85,7 @@ jobs: # points at this asset, so it must exist before any consumer resolves the # SPM tag. name: Attach assets to GitHub release - needs: [package, parse-version] + needs: [ffi, package] if: github.ref_type == 'tag' runs-on: ubuntu-latest permissions: @@ -181,9 +99,11 @@ jobs: # up GH_TOKEN directly, so don't persist a contents-write token. persist-credentials: false + - uses: ./.github/actions/just + - name: Find previous tag id: prev_tag - run: .github/scripts/release.sh prev-tag moq-ffi + run: just gh release prev-tag moq-ffi - name: Download package uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 @@ -195,9 +115,9 @@ jobs: env: GH_TOKEN: ${{ github.token }} RELEASE_TAG: ${{ github.ref_name }} - RELEASE_TITLE: "moq-ffi v${{ needs.parse-version.outputs.version }}" + RELEASE_TITLE: "moq-ffi v${{ needs.ffi.outputs.version }}" RELEASE_PREV_TAG: ${{ steps.prev_tag.outputs.tag }} - run: .github/scripts/release.sh create artifacts + run: just gh release create artifacts verify: # Gate the mirror push on actually being able to resolve the staged package @@ -205,7 +125,7 @@ jobs: # fine but SPM cannot resolve (e.g. a path-based binaryTarget slipping in # where a URL+checksum is expected). name: Verify staged package resolves - needs: [release, parse-version] + needs: [ffi, release] runs-on: macos-latest steps: @@ -213,6 +133,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Download staged package uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 with: @@ -221,13 +143,13 @@ jobs: - name: Resolve and build smoke consumer env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} + BUILD_VERSION: ${{ needs.ffi.outputs.version }} run: | - ./swift/scripts/verify-ffi.sh --tarball "artifacts/moq-ffi-${BUILD_VERSION}-swift-ffi.tar.gz" + just swift verify-ffi --tarball "artifacts/moq-ffi-${BUILD_VERSION}-swift-ffi.tar.gz" publish: name: Publish to Swift Package mirror - needs: [verify, parse-version] + needs: [ffi, verify] runs-on: ubuntu-latest steps: @@ -235,6 +157,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Generate moq-bot token uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3 id: token @@ -254,9 +178,9 @@ jobs: - name: Publish to moq-dev/moq-swift-ffi mirror env: - BUILD_VERSION: ${{ needs.parse-version.outputs.version }} + BUILD_VERSION: ${{ needs.ffi.outputs.version }} # Token is minted fresh per run, expires in 1 hour, never at rest. SWIFT_MIRROR_TOKEN: ${{ steps.token.outputs.token }} GIT_AUTHOR_NAME: moq-bot GIT_AUTHOR_EMAIL: moq-bot[bot]@users.noreply.github.com - run: ./swift/scripts/publish-ffi.sh + run: just swift publish-ffi diff --git a/.github/workflows/release-swift-lib.yml b/.github/workflows/release-swift-lib.yml index 6c5b07fc5a5..2684aa4f595 100644 --- a/.github/workflows/release-swift-lib.yml +++ b/.github/workflows/release-swift-lib.yml @@ -22,22 +22,22 @@ on: - "swift/Package.swift.template" - "swift/Sources/Moq/**" - "swift/Tests/**" - - "swift/scripts/package.sh" - - "swift/scripts/publish.sh" - - "swift/scripts/verify.sh" + - "sh/swift/package.sh" + - "sh/swift/publish.sh" + - "sh/swift/verify.sh" - ".github/workflows/release-swift-lib.yml" - - ".github/scripts/release.sh" + - "sh/gh/release.sh" pull_request: paths: - "swift/VERSION" - "swift/Package.swift.template" - "swift/Sources/Moq/**" - "swift/Tests/**" - - "swift/scripts/package.sh" - - "swift/scripts/publish.sh" - - "swift/scripts/verify.sh" + - "sh/swift/package.sh" + - "sh/swift/publish.sh" + - "sh/swift/verify.sh" - ".github/workflows/release-swift-lib.yml" - - ".github/scripts/release.sh" + - "sh/gh/release.sh" workflow_run: workflows: ["Release Swift FFI"] types: @@ -79,6 +79,8 @@ jobs: fetch-depth: 0 persist-credentials: false + - uses: ./.github/actions/just + - name: Read versions id: version env: @@ -101,13 +103,13 @@ jobs: if: github.event_name != 'workflow_run' env: FFI_VERSION: ${{ steps.version.outputs.ffi_version }} - run: .github/scripts/release.sh ffi-unreleased "$FFI_VERSION" + run: just gh release ffi-unreleased "$FFI_VERSION" - name: Check FFI mirror tag id: ffi-gate env: FFI_VERSION: ${{ steps.version.outputs.ffi_version }} - run: .github/scripts/release.sh git-tag-exists moq-dev/moq-swift-ffi "$FFI_VERSION" + run: just gh release git-tag-exists moq-dev/moq-swift-ffi "$FFI_VERSION" - name: Unpublished FFI notice if: steps.ffi-diff.outputs.unreleased != 'true' && steps.ffi-gate.outputs.exists != 'true' && github.event_name != 'pull_request' @@ -121,12 +123,12 @@ jobs: id: gate env: VERSION: ${{ steps.version.outputs.version }} - run: .github/scripts/release.sh git-tag-exists moq-dev/moq-swift "$VERSION" + run: just gh release git-tag-exists moq-dev/moq-swift "$VERSION" - name: Package env: BUILD_VERSION: ${{ steps.version.outputs.version }} - run: ./swift/scripts/package.sh --version "$BUILD_VERSION" --output release-out + run: just swift package --version "$BUILD_VERSION" --output release-out - name: Upload Swift package uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 @@ -149,6 +151,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Check FFI mirror tag id: ffi if: needs.build.outputs.publish == 'true' || (github.event_name == 'pull_request' && needs.build.outputs.ffi_unreleased != 'true') @@ -158,7 +162,7 @@ jobs: # rather than a hard failure, so the first bootstrap (before # moq-swift-ffi exists) skips the cross-package resolve instead of # failing the job. publish.sh stays idempotent regardless. - run: .github/scripts/release.sh git-tag-exists moq-dev/moq-swift-ffi "$FFI_VERSION" || echo "exists=false" >> "$GITHUB_OUTPUT" + run: just gh release git-tag-exists moq-dev/moq-swift-ffi "$FFI_VERSION" || echo "exists=false" >> "$GITHUB_OUTPUT" - name: Download staged package if: steps.ffi.outputs.exists == 'true' @@ -171,7 +175,7 @@ jobs: if: steps.ffi.outputs.exists == 'true' env: BUILD_VERSION: ${{ needs.build.outputs.version }} - run: ./swift/scripts/verify.sh --tarball "artifacts/moq-${BUILD_VERSION}-swift.tar.gz" + run: just swift verify --tarball "artifacts/moq-${BUILD_VERSION}-swift.tar.gz" - name: Skip notice if: needs.build.outputs.ffi_unreleased == 'true' @@ -194,6 +198,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Generate moq-bot token uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3 id: token @@ -218,7 +224,7 @@ jobs: SWIFT_MIRROR_TOKEN: ${{ steps.token.outputs.token }} GIT_AUTHOR_NAME: moq-bot GIT_AUTHOR_EMAIL: moq-bot[bot]@users.noreply.github.com - run: ./swift/scripts/publish.sh + run: just swift publish publish-dry-run: name: Publish dry-run @@ -231,6 +237,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Download package uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 with: @@ -240,4 +248,4 @@ jobs: - name: Dry-run publish to mirror env: BUILD_VERSION: ${{ needs.build.outputs.version }} - run: ./swift/scripts/publish.sh --dry-run + run: just swift publish --dry-run diff --git a/.github/workflows/rpm-repo.yml b/.github/workflows/rpm-repo.yml index 4c7df9dd844..93dc8c4a943 100644 --- a/.github/workflows/rpm-repo.yml +++ b/.github/workflows/rpm-repo.yml @@ -32,6 +32,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Set up packaging tools uses: ./.github/actions/setup-packaging @@ -51,10 +53,9 @@ jobs: - name: Publish to R2 shell: bash env: - ARTIFACTS_DIR: artifacts R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }} R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }} R2_ACCOUNT_ID: ${{ secrets.R2_ACCOUNT_ID }} SIGNING_KEY: ${{ secrets.SIGNING_KEY }} SIGNING_PASSWORD: ${{ secrets.SIGNING_PASSWORD }} - run: ./infra/rpm/publish.sh + run: just infra rpm publish "$GITHUB_WORKSPACE/artifacts" diff --git a/.github/workflows/swift.yml b/.github/workflows/swift.yml index bc7cdd98b7b..6a806b3ce44 100644 --- a/.github/workflows/swift.yml +++ b/.github/workflows/swift.yml @@ -14,6 +14,7 @@ on: branches: [main] paths: - "swift/**" + - "sh/swift/**" - "doc/lib/swift/**" - "doc/lib/samples.sh" - "rs/moq-ffi/**" @@ -26,6 +27,7 @@ on: types: [opened, synchronize, reopened, closed] paths: - "swift/**" + - "sh/swift/**" - "doc/lib/swift/**" - "doc/lib/samples.sh" - "rs/moq-ffi/**" @@ -53,6 +55,8 @@ jobs: with: persist-credentials: false + - uses: ./.github/actions/just + - name: Install Rust uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable with: @@ -80,4 +84,4 @@ jobs: done - name: Swift check - run: ./swift/scripts/check.sh + run: just swift check diff --git a/.github/workflows/wasm.yml b/.github/workflows/wasm.yml index d0c8392de3d..5f93aab325c 100644 --- a/.github/workflows/wasm.yml +++ b/.github/workflows/wasm.yml @@ -43,6 +43,7 @@ on: - "test/wasm/**" - "test/lib/**" - "justfile" + - "js/justfile" - "test/justfile" - ".cargo/config.toml" - "package.json" diff --git a/.gitignore b/.gitignore index af3a5c21aca..53171c83752 100644 --- a/.gitignore +++ b/.gitignore @@ -7,9 +7,8 @@ *.local.json # Claude Code scratch space. These are untracked working directories, and -# `just _changed` counts untracked files, so leaving them visible pushes the -# changed-file list past its cap and silently turns every scoped `just check` -# into `check --all`. The worktrees also carry their own biome.jsonc, which the +# `just check` counts untracked files, so leaving them visible would put their +# whole tree in scope. The worktrees also carry their own biome.jsonc, which the # unscoped run then rejects as a nested root config. /.claude/cache/ /.claude/tmp/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9bf948cca47..03b50aea224 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -50,6 +50,10 @@ Wait for Codex to review the final head before merging. Merge only on its thumbs up, or once every Codex finding on the PR is fixed or replied to. Codex skips fork PRs; ask the maintainer to request one. +# CI + +Workflow steps run `just` recipes, never a script path; `just gh check` enforces it. + # Follow-ups If you encounter issues, or findings that are out of scope, create follow-up quests. diff --git a/Cargo.toml b/Cargo.toml index 789ecbbfd04..c27908b5072 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -317,7 +317,7 @@ debug = true # Size-optimized build for the browser/WASM bindings (rs/moq-wasm). Shipping over # the wire, so optimize for size, not speed (~579KB -> ~471KB gzipped vs the -# default release profile). `just wasm` builds with `--profile wasm-release`. +# default release profile). `just js wasm` builds with `--profile wasm-release`. [profile.wasm-release] inherits = "release" opt-level = "z" diff --git a/bench/justfile b/bench/justfile deleted file mode 100755 index b3fa64c3929..00000000000 --- a/bench/justfile +++ /dev/null @@ -1,19 +0,0 @@ -#!/usr/bin/env just --justfile - -set working-directory := '..' - -# Benchmark the current tree, or compare it with a commit. -compare $BASE="": - #!/usr/bin/env bash - exec bench/run.sh "$BASE" - -# Compare the shared Tokio runtime with independent Tokio and io_uring workers. -runtime $ROUNDS="3" $WORKERS="": - #!/usr/bin/env bash - MOQ_BENCH_RUNTIME_ROUNDS="$ROUNDS" MOQ_BENCH_RUNTIME_WORKERS="$WORKERS" \ - exec bench/run.sh --runtime - -# Compile every binary and feature used by the repository-level harness. -check: - cargo check --locked --package moq-relay --package moq-bench \ - --features moq-relay/io-uring diff --git a/cpp/obs/justfile b/cpp/obs/justfile index 8a2778d6cf7..e252eccccba 100644 --- a/cpp/obs/justfile +++ b/cpp/obs/justfile @@ -21,389 +21,48 @@ default: # Configure via CMake presets. MOQ_LOCAL defaults to the repo root inside # CMakeLists.txt (so libmoq builds from rs/libmoq); pass `path=/some/moq` to -# override. We deliberately don't compute the path here: `justfile_directory()` -# resolves to the root justfile when this runs as `just obs setup`, so the - -# relative math would point outside the repo. +# override it. setup preset="" path="": - #!/usr/bin/env bash - set -euo pipefail - PRESET=$(just preset "{{ preset }}") - if [ -n "{{ path }}" ]; then - echo "Configuring with preset: $PRESET and MOQ_LOCAL={{ path }}" - cmake --preset "$PRESET" -DMOQ_LOCAL="{{ path }}" - else - echo "Configuring with preset: $PRESET (MOQ_LOCAL defaults to the repo root)" - cmake --preset "$PRESET" - fi + cmake --preset "$(../../sh/obs/preset.sh '{{ preset }}')" {{ if path == "" { "" } else { "-DMOQ_LOCAL=" + quote(path) } }} # Build via CMake presets. Run `just obs setup` first (it configures + downloads - # deps); not chained here because on macOS setup reconfigures OBS, which is slow. build preset="": - #!/usr/bin/env bash - set -euo pipefail - PRESET=$(just preset "{{ preset }}") - cmake --build --preset "$PRESET" - -# Copy the freshly built plugin into the OBS user plugin dir and launch OBS. - -# Uses the installed OBS (no local OBS build required). macOS only for now. -run: - #!/usr/bin/env bash - set -euo pipefail - if [[ "$OSTYPE" != "darwin"* ]]; then - echo "just run is macOS-only for now; copy build_*/obs-moq.* into your OBS plugin dir manually" >&2 - exit 1 - fi - dest="$HOME/Library/Application Support/obs-studio/plugins" - mkdir -p "$dest" - cp -a build_macos/RelWithDebInfo/obs-moq.plugin "$dest/" - RUST_LOG=debug RUST_BACKTRACE=1 OBS_LOG_LEVEL=debug /Applications/OBS.app/Contents/MacOS/OBS + cmake --build --preset "$(../../sh/obs/preset.sh '{{ preset }}')" # Type-check every plugin source and unit test, without linking or an obs-deps -# download. -# -# This is the gate to run in a worktree. `just obs build` needs the -# multi-hundred-MB obs-deps bundle (macOS/Windows) and a full cargo build, per -# worktree; this needs neither, because the dev shell carries all three header -# sets: libobs pinned to the same OBS release buildspec.json downloads (see -# `obs-headers` in flake.nix), Qt6, and ffmpeg. CI links the real thing on Linux -# (.github/workflows/obs.yml). -# -# It compiles the Qt sources too, which the CMake build only does when -# ENABLE_QT and ENABLE_FRONTEND_API are on, so the definitions they gate on are -# set here to match. -# -# test/ is in scope because each test file defines the libmoq entry points the -# plugin calls, so a signature that drifts from the generated moq.h is a -# conflicting C declaration. Catching that needs only headers, which is why it -# belongs here: `just obs ci` finds the same drift, but only where obs.yml's -# path filter reaches, and `just obs test` is manual. +# download. The gate to run in a worktree. compile: - #!/usr/bin/env bash - set -euo pipefail - # Never skips, for the reason `test` doesn't: a compile gate that reports - # success without compiling is worse than no gate. Everything it needs is in - # the dev shell, so the fix is always to enter it. - cxx="${CXX:-c++}" - if ! command -v "$cxx" >/dev/null; then - echo "no C++ compiler at '$cxx'" >&2 - exit 1 - fi - for pkgs in "Qt6Widgets Qt6Gui Qt6Core" "libavcodec libavutil libswscale libswresample"; do - # shellcheck disable=SC2086 - if ! pkg-config --exists $pkgs; then - echo "missing headers for: $pkgs" >&2 - echo "run inside 'nix develop', which supplies Qt6 and ffmpeg on every platform" >&2 - exit 1 - fi - done - - # Assign first so a failure in `_includes` still aborts under `set -e`, - # then split on newlines only: an include path may contain spaces. - includes_raw=$(just _includes) - includes=() - while IFS= read -r flag; do includes+=("$flag"); done <<< "$includes_raw" - - qt=$(pkg-config --cflags Qt6Widgets Qt6Gui Qt6Core) - ffmpeg=$(pkg-config --cflags libavcodec libavutil libswscale libswresample) - - # MOQ_VERSION_STRING only reaches a label in the dock, so any value - # type-checks the same; CMake stamps the real libmoq version. - status=0 - for source in src/*.cpp test/*.cpp; do - # shellcheck disable=SC2086 - # -Wno-unused-command-line-argument: the nix compiler wrapper injects - # link flags, which a syntax-only run reports as unused, once per file. - # $qt and $ffmpeg stay unquoted on purpose: pkg-config hands back one - # space-separated string, and splitting it is the intended reading. - if ! "$cxx" -std=c++17 -fsyntax-only -Wno-unused-command-line-argument \ - "${includes[@]}" $qt $ffmpeg \ - -DMOQ_FRONTEND_ENABLED -DMOQ_VERSION_STRING='"0.0.0"' "$source"; then - status=1 - fi - done - exit $status + ../../sh/obs/compile.sh # Compile and link the plugin the way CI does, against the `.#obs` shell's own # libobs/Qt6/ffmpeg, then run the unit tests. Linux-only in practice: it's the -# one platform where nixpkgs has obs-studio, so nothing has to be downloaded. -# Manual elsewhere. -# -# The tests run here without ThreadSanitizer because this is the only recipe CI -# invokes (.github/workflows/obs.yml). `just obs test` is manual, so on its own -# it can't make a build red; the sanitizer finds more, but only what runs in CI -# gates a merge. -# -# CMAKE_BUILD_TYPE overrides the preset's RelWithDebInfo because the Rust cache -# CI restores holds dev-profile artifacts. A release build of libmoq would -# rebuild its whole dependency tree on every run, and the gate is about whether -# the plugin compiles, which the profile doesn't change. +# one platform where nixpkgs has obs-studio. The Debug build type reuses the +# dev-profile Rust artifacts CI restores, where a release libmoq would rebuild +# its whole dependency tree. ci preset="": - #!/usr/bin/env bash - set -euo pipefail - PRESET=$(just preset "{{ preset }}" ci) - cmake --preset "$PRESET" -DCMAKE_BUILD_TYPE=Debug - cmake --build --preset "$PRESET" - just _unit - -# Print the -I flags for libobs and libmoq, shared by `compile` and `_unit`. -# -# moq.h is generated by cbindgen from rs/libmoq/src, so regenerate rather than -# just locating it: a stale header is how a plugin call to a since-changed -# libmoq function type-checks anyway. -[private] -_includes: - #!/usr/bin/env bash - set -euo pipefail - # The dev shell's pinned headers first, so every platform checks against the - # same libobs. Then the obs-deps framework (macOS/Windows), the OBS sources - # CMake unpacks beside it, and a system install (Linux without nix). - obs_include="" - for candidate in \ - "${OBS_INCLUDE_DIR:-}" \ - .deps/Frameworks/libobs.framework/Versions/A/Headers \ - .deps/obs-studio-*/libobs; do - if [ -n "$candidate" ] && [ -f "$candidate/obs.h" ]; then - obs_include="$candidate" - break - fi - done - if [ -z "$obs_include" ] && command -v pkg-config >/dev/null && pkg-config --exists libobs; then - obs_include=$(pkg-config --variable=includedir libobs)/obs - fi - if [ -z "$obs_include" ]; then - echo "libobs headers not found; run inside 'nix develop' (or set OBS_INCLUDE_DIR)" >&2 - exit 1 - fi - - # obs.h reaches as of OBS 32, which used to be vendored - # under libobs/util/ and so came along with the headers above. The dev shell - # carries it (see flake.nix); the obs-deps bundle ships its own copy beside - # libobs, which is how the macOS and Windows builds get it. - simde_include="" - if command -v pkg-config >/dev/null && pkg-config --exists simde; then - simde_include=$(pkg-config --variable=includedir simde) - else - for candidate in .deps/obs-deps-*/include; do - if [ -f "$candidate/simde/x86/sse2.h" ]; then - simde_include="$candidate" - break - fi - done - fi - if [ -z "$simde_include" ]; then - echo "simde headers not found; run inside 'nix develop', which supplies them" >&2 - exit 1 - fi - - (cd ../.. && cargo check --locked --quiet -p libmoq) - - # rs/libmoq/build.rs writes the header into its OUT_DIR, so ask cargo where - # that is. Replays the check above from cache, so it costs a process rather - # than a compile. - out_dir=$(cd ../.. && cargo check --locked -p libmoq --message-format=json | - jq -r 'select(.reason == "build-script-executed") | select(.package_id | tostring | test("libmoq")) | .out_dir' | - tail -1) - if [ -z "$out_dir" ]; then - echo "cargo reported no build script output for libmoq" >&2 - exit 1 - fi - moq_include="$out_dir/include" - if [ ! -f "$moq_include/moq.h" ]; then - echo "$moq_include/moq.h missing after 'cargo check --locked -p libmoq'" >&2 - exit 1 - fi - - # One flag per line, path glued to the -I, so a caller can rebuild the - # arguments without splitting on the spaces in a path. - printf -- '-I%s\n' src "$obs_include" "$simde_include" "$moq_include" + cmake --preset "$(../../sh/obs/preset.sh '{{ preset }}' ci)" -DCMAKE_BUILD_TYPE=Debug + cmake --build --preset "$(../../sh/obs/preset.sh '{{ preset }}' ci)" + ../../sh/obs/unit.sh # Unit-test the plugin sources against stubbed libobs/libmoq/ffmpeg, under -# ThreadSanitizer. -# -# Manual because ThreadSanitizer needs its own build. `just obs ci` runs the -# same tests without it, so a regression these assertions catch still turns PR -# CI red; the sanitizer is what -# adds the races on top. Run this whenever you touch src/, especially the session -# callback plumbing, whose orderings the build can't check. +# ThreadSanitizer. Manual; `just obs ci` runs them without the sanitizer. test: - #!/usr/bin/env bash - set -euo pipefail - # Unlike the lint recipes, this one never skips: a test gate that reports - # success without running anything is worse than no gate. - cxx="${CXX:-c++}" - unsupported="'$cxx' cannot build and run -fsanitize=thread binaries. These tests need a - Clang or GCC whose ThreadSanitizer runtime works on this host: set CXX, or on Windows run - them from WSL, since neither MSVC nor Clang on Windows implements ThreadSanitizer. - They also run without the sanitizer as part of 'just obs ci'." - if ! command -v "$cxx" >/dev/null; then - echo "no C++ compiler at '$cxx'." >&2 - echo "$unsupported" >&2 - exit 1 - fi - - probe=$(mktemp -d) - trap 'rm -rf "$probe"' EXIT - - # Run the probe, don't just link it: a mismatch between the compiler's TSan - # runtime and the host kernel (macOS is where this shows up) links fine and - # then segfaults before main, which is an unreadable way for the real test - # to fail. - # The subshell keeps bash's own "Segmentation fault" job message out of the - # output, so the explanation below is all the reader gets. - if ! printf 'int main(){}\n' | "$cxx" -x c++ -fsanitize=thread -o "$probe/probe" - >/dev/null 2>&1 \ - || ! ("$probe/probe" >/dev/null 2>&1) 2>/dev/null; then - echo "$unsupported" >&2 - exit 1 - fi - - just _unit tsan + ../../sh/obs/test.sh -# Compile and run the unit tests, plain or under ThreadSanitizer. Shared by -# `test` and `ci` so both run the same assertions. -[private] -_unit mode="plain": - #!/usr/bin/env bash - set -euo pipefail - cxx="${CXX:-c++}" - if ! command -v "$cxx" >/dev/null; then - echo "no C++ compiler at '$cxx'" >&2 - exit 1 - fi - # moq-source.cpp decodes with ffmpeg, so its test needs the headers even - # though it stubs every function out of them. - if ! pkg-config --exists libavcodec libavutil libswscale; then - echo "missing ffmpeg headers" >&2 - echo "run inside 'nix develop', which supplies ffmpeg on every platform" >&2 - exit 1 - fi - - includes_raw=$(just _includes) - includes=() - while IFS= read -r flag; do includes+=("$flag"); done <<< "$includes_raw" - - ffmpeg=$(pkg-config --cflags libavcodec libavutil libswscale) - - flags=(-std=c++17 -g -O0 -pthread) - if [ "{{ mode }}" = "tsan" ]; then - flags+=(-fsanitize=thread) - fi - - out=$(mktemp -d) - trap 'rm -rf "$out"' EXIT - - # One binary per source under test: each test file defines its own libobs and - # libmoq stubs, so two of them can't share a link. Header-only helpers - # (quality defaults) build as a third binary with no plugin source. - for name in moq-output moq-source; do - # shellcheck disable=SC2086 - # $ffmpeg stays unquoted on purpose: pkg-config hands back one - # space-separated string, and splitting it is the intended reading. - "$cxx" "${flags[@]}" "${includes[@]}" $ffmpeg \ - -o "$out/$name-test" "test/$name-test.cpp" "src/$name.cpp" - TSAN_OPTIONS="halt_on_error=1" "$out/$name-test" - done - for name in moq-quality-defaults moq-dock-stop moq-error moq-encoder-latency moq-dial moq-spark; do - "$cxx" "${flags[@]}" "${includes[@]}" \ - -o "$out/$name-test" "test/$name-test.cpp" - TSAN_OPTIONS="halt_on_error=1" "$out/$name-test" - done - -# Lint formatting. Skips a tool silently if it isn't on $PATH (matches repo convention). +# Lint formatting and the OBS version pins. check: - #!/usr/bin/env bash - set -euo pipefail - if grep -Fq '"MOQ_VERSION"' CMakePresets.json; then - echo "CMakePresets.json must not pin MOQ_VERSION" >&2 - exit 1 - fi - # The headers `just obs compile` type-checks against are a second copy of - # the OBS version this spec downloads, so a bump here has to reach flake.nix - # or the two gates check different libobs. - spec_obs=$(jq -r '.dependencies["obs-studio"].version // ""' buildspec.json) - flake_obs=$(sed -n '/pname = "libobs-headers"/,/}/p' ../../flake.nix | sed -n 's/.*version = "\([^"]*\)".*/\1/p') - # Both are pattern matches against files this recipe doesn't own the shape - # of. An empty parse compares equal to an empty parse, so the guard would - # pass by reporting nothing rather than by finding the versions in sync. - if [ -z "$spec_obs" ] || [ -z "$flake_obs" ]; then - echo "couldn't read the obs-studio version: '$spec_obs' from buildspec.json, '$flake_obs' from flake.nix" >&2 - exit 1 - fi - if [ "$spec_obs" != "$flake_obs" ]; then - echo "obs-studio is $spec_obs in buildspec.json but $flake_obs in flake.nix (libobs-headers)" >&2 - exit 1 - fi - # And a third: `just obs ci` links against nixpkgs' obs-studio, the one OBS - # this repo doesn't pick. Without this the released macOS/Windows binaries - # could be a whole libobs API apart from what CI ever compiles. Patch - # releases carry no API change, so only the major.minor has to agree; that - # also keeps the guard quiet until flake.lock actually moves OBS, which is - # the change that opens the gap and so the one that should fail. - # OBS_LINKED_VERSION comes from the dev shell (see flake.nix), so this leg - # is skipped outside it, where there is no nixpkgs obs-studio to compare. - # MOQ_STRICT turns that skip into an error for the same reason it turns a - # missing tool into one: in CI a leg that checks nothing still reports green. - if [ -z "${OBS_LINKED_VERSION:-}" ]; then - if [ -n "${MOQ_STRICT:-}" ]; then - echo "MOQ_STRICT is set but OBS_LINKED_VERSION is unset; run inside 'nix develop', which exports it" >&2 - exit 1 - fi - else - spec_api=$(echo "$spec_obs" | cut -d. -f1,2) - linked_api=$(echo "$OBS_LINKED_VERSION" | cut -d. -f1,2) - if [ "$spec_api" != "$linked_api" ]; then - echo "obs-studio is $spec_obs in buildspec.json but $OBS_LINKED_VERSION in nixpkgs, which is what 'just obs ci' links" >&2 - echo "bump buildspec.json and flake.nix's libobs-headers to $OBS_LINKED_VERSION, or pin nixpkgs back" >&2 - exit 1 - fi - fi - if command -v cmake >/dev/null; then - build_dir=$(mktemp -d) - trap 'rm -rf "$build_dir"' EXIT - if cmake -S . -B "$build_dir" -DMOQ_LOCAL= >"$build_dir/configure.log" 2>&1; then - echo "CMake accepted a release build without MOQ_VERSION" >&2 - exit 1 - fi - if ! grep -Fq "MOQ_VERSION is required when MOQ_LOCAL does not contain rs/libmoq" "$build_dir/configure.log"; then - cat "$build_dir/configure.log" >&2 - exit 1 - fi - fi - if command -v clang-format >/dev/null; then - git ls-files 'src/*.cpp' 'src/*.h' 'test/*.cpp' | xargs clang-format --dry-run --Werror - fi - if command -v gersemi >/dev/null; then - gersemi --check CMakeLists.txt cmake - fi + ../../sh/obs/check.sh # Auto-fix formatting. fix: - #!/usr/bin/env bash - set -euo pipefail - if command -v clang-format >/dev/null; then - git ls-files 'src/*.cpp' 'src/*.h' 'test/*.cpp' | xargs clang-format -i - fi - if command -v gersemi >/dev/null; then - gersemi --in-place CMakeLists.txt cmake - fi + ../../sh/obs/fix.sh + +# Runs in the caller's directory, so a relative `--output` means what it would +# to the script itself. -# Detect the CMake preset for the current platform (or use the override). -# Pass `ci` as the second argument for the warnings-as-errors variant, whose -# name upstream spells differently on each platform. -preset override="" variant="": - #!/usr/bin/env bash - set -euo pipefail - if [[ -n "{{ override }}" ]]; then - echo "{{ override }}" - elif [[ "$OSTYPE" == "darwin"* ]]; then - [[ "{{ variant }}" == "ci" ]] && echo "macos-ci" || echo "macos" - elif [[ "$OSTYPE" == "linux-gnu"* ]]; then - [[ "{{ variant }}" == "ci" ]] && echo "ubuntu-ci-x86_64" || echo "ubuntu-x86_64" - elif [[ "$OSTYPE" == "msys" || "$OSTYPE" == "cygwin" ]]; then - [[ "{{ variant }}" == "ci" ]] && echo "windows-ci-x64" || echo "windows-x64" - else - echo "Unknown platform: $OSTYPE" >&2 - exit 1 - fi +# Build and package the obs-moq plugin for release. +[no-cd] +[positional-arguments] +package *args: + {{ quote(justfile_directory() / "cpp/obs/build.sh") }} "$@" diff --git a/dart/justfile b/dart/justfile index 9823e8cf324..5c2fc803ffc 100644 --- a/dart/justfile +++ b/dart/justfile @@ -1,18 +1,22 @@ #!/usr/bin/env just --justfile # Check the generated bindings and both Dart packages. -check $FILES="": - ./scripts/check.sh "{{ FILES }}" +check: + ../sh/dart/check.sh # Format Dart sources. -fix $FILES="": - ./scripts/check.sh --fix "{{ FILES }}" +fix: + ../sh/dart/check.sh --fix # Regenerate the raw UniFFI Dart bindings. generate: - ./scripts/generate.sh + ../sh/dart/generate.sh -# Remove Dart tool state and build output. -clean: - rm -rf moq/.dart_tool moq_ffi/.dart_tool - rm -rf moq/build moq_ffi/build +# `package` runs in the caller's directory, so a relative `--output` means +# what it would to the script itself. + +# Package a Dart library for pub.dev. +[no-cd] +[positional-arguments] +package *args: + {{ quote(justfile_directory() / "sh/dart/package.sh") }} "$@" diff --git a/dart/moq_ffi/hook/build.dart b/dart/moq_ffi/hook/build.dart index 6916ea46a70..bfb465d6036 100644 --- a/dart/moq_ffi/hook/build.dart +++ b/dart/moq_ffi/hook/build.dart @@ -7,7 +7,7 @@ import 'package:http/http.dart' as http; /// The moq-ffi release whose native assets this package downloads. /// -/// dart/scripts/package.sh rewrites this when staging a release. The sentinel +/// sh/dart/package.sh rewrites this when staging a release. The sentinel /// is never used to download: a checkout builds from source instead, and a /// package built without the injection fails loudly rather than fetching a /// library that does not match these bindings. diff --git a/dart/moq_ffi/pubspec.yaml b/dart/moq_ffi/pubspec.yaml index cf7a8ecadc2..0f53a4f24cb 100644 --- a/dart/moq_ffi/pubspec.yaml +++ b/dart/moq_ffi/pubspec.yaml @@ -1,6 +1,6 @@ name: moq_ffi description: Raw Dart and Flutter bindings for Media over QUIC. -# Overridden by dart/scripts/package.sh from the moq-ffi-v* tag. Committing a +# Overridden by sh/dart/package.sh from the moq-ffi-v* tag. Committing a # real version would go stale the moment release-plz bumps the crate. version: 0.0.0-dev repository: https://github.com/moq-dev/moq/tree/main/dart/moq_ffi diff --git a/demo/boy/justfile b/demo/boy/justfile index 9312d15bd55..5837865a5e9 100644 --- a/demo/boy/justfile +++ b/demo/boy/justfile @@ -11,13 +11,9 @@ default: "just wait && just web" # Download the given ROM from our R2 bucket. +[positional-arguments] download rom: - #!/usr/bin/env bash - if [ ! -f "rom/{{ rom }}" ]; then - mkdir -p rom - curl -fSL -o "rom/{{ rom }}.tmp" "https://rom.moq.dev/{{ rom }}" - mv "rom/{{ rom }}.tmp" "rom/{{ rom }}" - fi + @../../sh/demo/download.sh "https://rom.moq.dev/$1" "rom/$1" # Big2Small (puzzle): https://mdsteele.itch.io/big2small b2s: @@ -70,15 +66,9 @@ upload file: bun wrangler r2 object put "rom-moq-dev/{{ file }}" --file "rom/{{ file }}" --remote # Sync all ROMs to R2 +[positional-arguments] sync dir="rom": - #!/usr/bin/env bash - set -euo pipefail - for file in "{{ dir }}"/*; do - [ -e "$file" ] || continue - key=$(basename "$file") - echo "Uploading $key..." - bun wrangler r2 object put "rom-moq-dev/$key" --file "$file" --remote - done + ../../sh/demo/sync.sh rom-moq-dev "$@" # List files in the R2 bucket list: diff --git a/demo/justfile b/demo/justfile index bfd725f82d1..08b359d9ffa 100644 --- a/demo/justfile +++ b/demo/justfile @@ -1,65 +1,18 @@ set fallback -mod boy -mod pub -mod relay -mod sub -mod web - # Run the web demo (default). # -# Picks the first free port at/after 4443 (both UDP for QUIC and TCP for HTTP) -# so multiple worktrees can run `just dev` without colliding. The relay reads - -# the port from MOQ_LISTEN/MOQ_WEB_HTTP_LISTEN, overriding localhost.toml. +# Picks the first free port at/after 4443 so multiple worktrees can run +# `just dev` without colliding; see sh/demo/run.sh. default: - #!/usr/bin/env bash - set -euo pipefail bun install - - port=$(just port) - if [ "$port" != "4443" ]; then - echo ">>> Port 4443 is busy, using $port instead" >&2 - fi - - base="http://localhost:$port" - - # Scope the bind env vars to the relay only. The unified `moq` binary also - # reads MOQ_LISTEN, so exporting it globally would make the `pub` client - # try to start a server (and fail without a TLS cert). - bun run concurrently --kill-others --names rly,bbb,web --prefix-colors auto \ - "MOQ_LISTEN='[::]:$port' MOQ_WEB_HTTP_LISTEN='[::]:$port' just relay" \ - "just wait $base/certificate.sha256 && just pub bbb $base" \ - "just wait $base/certificate.sha256 && just web serve $base" - -# Find the first free port at/after `start` (checked on both TCP and UDP). -# `lsof` isn't available everywhere (e.g. Git Bash on Windows); without it we -# can't probe, so fall back to `start` and let the relay surface a bind error if - -# it's actually taken. -[private] -port start="4443": - #!/usr/bin/env bash - set -euo pipefail - port={{ start }} - if command -v lsof >/dev/null 2>&1; then - while lsof -nP -iTCP:"$port" -sTCP:LISTEN -t >/dev/null 2>&1 \ - || lsof -nP -iUDP:"$port" -t >/dev/null 2>&1; do - port=$((port + 1)) - done - fi - echo "$port" + ../sh/demo/run.sh # Wait for the localhost relay to be ready by repeatedly requesting the cert +[positional-arguments] [private] wait url="http://localhost:4443/certificate.sha256": - #!/usr/bin/env bash - set -euo pipefail - for i in $(seq 1 600); do - curl -sf "{{ url }}" > /dev/null 2>&1 && exit 0 - sleep 1 - done - exit 1 + ../sh/demo/wait.sh "$@" # Throttle UDP traffic for testing (macOS only, requires sudo). throttle: diff --git a/demo/pub/justfile b/demo/pub/justfile index 2715bd75ccb..f50d1d5447f 100644 --- a/demo/pub/justfile +++ b/demo/pub/justfile @@ -1,4 +1,5 @@ set fallback +set shell := ["bash", "-euo", "pipefail", "-c"] # --- R2 bucket management (vid.moq.dev) --- @@ -18,15 +19,9 @@ upload file: bun wrangler r2 object put "video-moq-dev/{{ file }}" --file "media/{{ file }}" --remote # Sync all files in a local directory to R2 +[positional-arguments] sync dir="media": - #!/usr/bin/env bash - set -euo pipefail - for file in "{{ dir }}"/*; do - [ -e "$file" ] || continue - key=$(basename "$file") - echo "Uploading $key..." - bun wrangler r2 object put "video-moq-dev/$key" --file "$file" --remote - done + ../../sh/demo/sync.sh video-moq-dev "$@" # List files in the bucket list: @@ -36,6 +31,7 @@ list: # --- Publishing --- # Publish Big Buck Bunny to a relay server. +[positional-arguments] bbb url='http://localhost:4443' *args: just download bbb just download bbb-sd @@ -44,7 +40,7 @@ bbb url='http://localhost:4443' *args: -stream_loop -1 -re -i media/bbb.mp4 \ -stream_loop -1 -re -i media/bbb-sd.mp4 \ -map 0 -map 1:v -c copy -f mpegts -pes_payload_size 0 -muxdelay 0 - \ - | cargo run --bin moq -- {{ args }} --connect "{{ url }}" --broadcast bbb.hang import ts + | cargo run --bin moq -- "${@:2}" --connect "{{ url }}" --broadcast bbb.hang import ts # Encode the video-only SD rendition, preserving source timestamps and loop duration. encode-bbb-sd: @@ -58,19 +54,22 @@ check-bbb: python3 bbb.py check # Publish Tears of Steel to a relay server. +[positional-arguments] tos url='http://localhost:4443' *args: just download tos - just ts tos "{{ url }}" {{ args }} + just ts tos "$@" # Publish a video using ffmpeg (CMAF / fMP4) to a relay server. +[positional-arguments] cmaf name url='http://localhost:4443' *args: cargo build --bin moq - just ffmpeg-cmaf "media/{{ name }}.mp4" | cargo run --bin moq -- {{ args }} --connect "{{ url }}" --broadcast "{{ name }}.hang" import fmp4 + just ffmpeg-cmaf "media/{{ name }}.mp4" | cargo run --bin moq -- "${@:3}" --connect "{{ url }}" --broadcast "{{ name }}.hang" import fmp4 # Publish a video using ffmpeg (MPEG-TS) to a relay server. +[positional-arguments] ts name url='http://localhost:4443' *args: cargo build --bin moq - just ffmpeg-ts "media/{{ name }}.mp4" | cargo run --bin moq -- {{ args }} --connect "{{ url }}" --broadcast "{{ name }}.hang" import ts + just ffmpeg-ts "media/{{ name }}.mp4" | cargo run --bin moq -- "${@:3}" --connect "{{ url }}" --broadcast "{{ name }}.hang" import ts # Publish a video via iroh. iroh name url prefix="": @@ -79,82 +78,13 @@ iroh name url prefix="": just ffmpeg-ts "media/{{ name }}.mp4" | cargo run --bin moq -- --iroh-enabled --connect "{{ url }}" --broadcast "{{ prefix }}{{ name }}.hang" import ts # Generate and ingest an HLS stream from a video file. +[positional-arguments] hls name relay="http://localhost:4443": - #!/usr/bin/env bash - set -euo pipefail - - just download "{{ name }}" - - INPUT="media/{{ name }}.mp4" - OUT_DIR="media/{{ name }}" - - rm -rf "$OUT_DIR" - mkdir -p "$OUT_DIR" - - echo ">>> Generating HLS stream to disk (1280x720 + 256x144)..." - - ffmpeg -hide_banner -loglevel warning -re -stream_loop -1 -i "$INPUT" \ - -filter_complex "\ - [0:v]split=2[v0][v1]; \ - [v0]scale=-2:720[v720]; \ - [v1]scale=-2:144[v144]" \ - -map "[v720]" -map "[v144]" -map 0:a:0 \ - -r 25 -preset veryfast -g 50 -keyint_min 50 -sc_threshold 0 \ - -c:v:0 libx264 -profile:v:0 high -level:v:0 4.1 -pix_fmt:v:0 yuv420p -tag:v:0 avc1 \ - -b:v:0 4M -maxrate:v:0 4.4M -bufsize:v:0 8M \ - -c:v:1 libx264 -profile:v:1 high -level:v:1 4.1 -pix_fmt:v:1 yuv420p -tag:v:1 avc1 \ - -b:v:1 300k -maxrate:v:1 330k -bufsize:v:1 600k \ - -c:a aac -b:a 128k \ - -f hls -hls_time 2 -hls_list_size 6 \ - -hls_flags independent_segments+delete_segments \ - -hls_segment_type fmp4 \ - -master_pl_name master.m3u8 \ - -var_stream_map "v:0,agroup:audio,name:720 v:1,agroup:audio,name:144 a:0,agroup:audio,name:audio" \ - -hls_segment_filename "$OUT_DIR/v%v/segment_%09d.m4s" \ - "$OUT_DIR/v%v/stream.m3u8" & - - FFMPEG_PID=$! - - echo ">>> Waiting for HLS playlist generation..." - for i in {1..30}; do - if [ -f "$OUT_DIR/master.m3u8" ]; then break; fi - sleep 0.5 - done - - if [ ! -f "$OUT_DIR/master.m3u8" ]; then - kill $FFMPEG_PID 2>/dev/null || true - echo "Error: master.m3u8 not generated in time" - exit 1 - fi - - echo ">>> Waiting for variant playlists..." - sleep 2 - for i in {1..20}; do - if [ -f "$OUT_DIR/v0/stream.m3u8" ] || [ -f "$OUT_DIR/v720/stream.m3u8" ] || [ -f "$OUT_DIR/v144/stream.m3u8" ] || [ -f "$OUT_DIR/vaudio/stream.m3u8" ]; then - break - fi - sleep 0.5 - done - - CLEANUP_CALLED=false - cleanup() { - if [ "$CLEANUP_CALLED" = "true" ]; then return; fi - CLEANUP_CALLED=true - echo "Shutting down..." - kill $FFMPEG_PID 2>/dev/null || true - sleep 0.5 - kill -9 $FFMPEG_PID 2>/dev/null || true - } - trap cleanup SIGINT SIGTERM EXIT - - echo ">>> Importing HLS via moq-cli" - cargo run --bin moq -- --connect "{{ relay }}" --broadcast "{{ name }}.hang" import hls "$OUT_DIR/master.m3u8" - EXIT_CODE=$? - - cleanup - exit $EXIT_CODE + just download "$1" + ../../sh/demo/hls.sh "$@" # Publish a video using H.264 Annex B format. +[positional-arguments] h264 name url="http://localhost:4443" *args: just download "{{ name }}" cargo build --bin moq @@ -165,68 +95,31 @@ h264 name url="http://localhost:4443" *args: -c:v copy -an \ -bsf:v h264_mp4toannexb \ -f h264 \ - - | cargo run --bin moq -- {{ args }} --connect "{{ url }}" --broadcast "{{ name }}.hang" import avc3 + - | cargo run --bin moq -- "${@:3}" --connect "{{ url }}" --broadcast "{{ name }}.hang" import avc3 # Publish a video using ffmpeg directly from moq to the localhost. +[positional-arguments] serve name *args: just download "{{ name }}" cargo build --bin moq - just ffmpeg-ts "media/{{ name }}.mp4" | cargo run --bin moq -- {{ args }} --listen "[::]:4443" --listen-tls-generate "localhost" --auth-public "**" --broadcast "{{ name }}.hang" import ts + just ffmpeg-ts "media/{{ name }}.mp4" | cargo run --bin moq -- "${@:2}" --listen "[::]:4443" --listen-tls-generate "localhost" --auth-public "**" --broadcast "{{ name }}.hang" import ts # Generate and serve an HLS stream from a video for testing. +[positional-arguments] serve-hls name port="8000": - #!/usr/bin/env bash - set -euo pipefail - - just download "{{ name }}" - - INPUT="media/{{ name }}.mp4" - OUT_DIR="media/{{ name }}" - - rm -rf "$OUT_DIR" - mkdir -p "$OUT_DIR" - - echo ">>> Starting HLS stream generation..." - echo ">>> Master playlist: http://localhost:{{ port }}/master.m3u8" - - cleanup() { - echo "Shutting down..." - kill $(jobs -p) 2>/dev/null || true - exit 0 - } - trap cleanup SIGINT SIGTERM - - ffmpeg -loglevel warning -re -stream_loop -1 -i "$INPUT" \ - -map 0:v:0 -map 0:v:0 -map 0:a:0 \ - -r 25 -preset veryfast -g 50 -keyint_min 50 -sc_threshold 0 \ - -c:v:0 libx264 -profile:v:0 high -level:v:0 4.1 -pix_fmt:v:0 yuv420p -tag:v:0 avc1 -bsf:v:0 dump_extra -b:v:0 4M -vf:0 "scale=1920:-2" \ - -c:v:1 libx264 -profile:v:1 high -level:v:1 4.1 -pix_fmt:v:1 yuv420p -tag:v:1 avc1 -bsf:v:1 dump_extra -b:v:1 300k -vf:1 "scale=256:-2" \ - -c:a aac -b:a 128k \ - -f hls \ - -hls_time 2 -hls_list_size 12 \ - -hls_flags independent_segments+delete_segments \ - -hls_segment_type fmp4 \ - -master_pl_name master.m3u8 \ - -var_stream_map "v:0,agroup:audio v:1,agroup:audio a:0,agroup:audio" \ - -hls_segment_filename "$OUT_DIR/v%v/segment_%09d.m4s" \ - "$OUT_DIR/v%v/stream.m3u8" & - - sleep 2 - echo ">>> HTTP server: http://localhost:{{ port }}/" - cd "$OUT_DIR" && python3 -m http.server {{ port }} + just download "$1" + ../../sh/demo/serve-hls.sh "$@" # Publish the clock broadcast. +[arg("action", pattern="publish|subscribe")] +[positional-arguments] clock action url="http://localhost:4443" *args: - @if [ "{{ action }}" != "publish" ] && [ "{{ action }}" != "subscribe" ]; then \ - echo "Error: action must be 'publish' or 'subscribe', got '{{ action }}'" >&2; \ - exit 1; \ - fi - - cargo run -p moq-tokio --example clock -- --connect "{{ url }}" --broadcast "clock" {{ args }} {{ action }} + cargo run -p moq-tokio --example clock -- --connect "{{ url }}" --broadcast "clock" "${@:3}" "{{ action }}" # --- GStreamer --- # Publish a video using GStreamer to a relay server. +[positional-arguments] gst name url='http://localhost:4443' *args: just download "{{ name }}" cargo build -p moq-gst @@ -235,36 +128,36 @@ gst name url='http://localhost:4443' *args: gst-launch-1.0 -v -e multifilesrc location="media/{{ name }}.mp4" loop=true ! parsebin name=parse \ parse. ! queue ! identity sync=true ! mux.sink_0 \ parse. ! queue ! identity sync=true ! mux.sink_1 \ - moqsink name=mux url="{{ url }}" broadcast="{{ name }}.hang" {{ args }} + moqsink name=mux url="{{ url }}" broadcast="{{ name }}.hang" "${@:3}" # --- Private helpers --- # Download a test video (already fragmented on vid.moq.dev). +[positional-arguments] [private] download name: - @if [ ! -f "media/{{ name }}.mp4" ]; then \ - mkdir -p media; \ - curl -fsSL "https://vid.moq.dev/{{ name }}.mp4" -o "media/{{ name }}.mp4"; \ - fi + @../../sh/demo/download.sh "https://vid.moq.dev/$1.mp4" "media/$1.mp4" # Convert an h264 input file to CMAF (fmp4) format to stdout, with one fragment per sample. # -frag_duration rather than frag_every_frame: the latter repeats a fragment's tfdt when it # interleaves audio and video, landing two samples on one timestamp. +[positional-arguments] [private] ffmpeg-cmaf input output='-' *args: ffmpeg -hide_banner -v quiet \ -stream_loop -1 -re \ -i "{{ input }}" \ -c copy \ - -f mp4 -movflags cmaf+separate_moof+delay_moov+skip_trailer -frag_duration 1000 {{ args }} {{ output }} + -f mp4 -movflags cmaf+separate_moof+delay_moov+skip_trailer -frag_duration 1000 "${@:3}" "{{ output }}" # Convert an h264 input file to MPEG-TS format to stdout, with one PES per audio frame. # -pes_payload_size 0 alone still queues audio frames under 170 bytes (silence) for up to # 0.35 s; -muxdelay 0 writes each one as soon as the next arrives. +[positional-arguments] [private] ffmpeg-ts input output='-' *args: ffmpeg -hide_banner -v quiet \ -stream_loop -1 -re \ -i "{{ input }}" \ -c copy \ - -f mpegts -pes_payload_size 0 -muxdelay 0 {{ args }} {{ output }} + -f mpegts -pes_payload_size 0 -muxdelay 0 "${@:3}" "{{ output }}" diff --git a/demo/relay/justfile b/demo/relay/justfile index c0e33a31971..db04682e600 100644 --- a/demo/relay/justfile +++ b/demo/relay/justfile @@ -34,60 +34,17 @@ leaf1: (cert "leaf1") # Generate a self-signed CA ca: - #!/usr/bin/env bash - set -euo pipefail - umask 077 - - [ -f ca.pem ] && [ -f ca.key ] && exit 0 - rm -f ca.pem ca.key - printf '[req]\ndistinguished_name = req_dn\n[req_dn]\n' > ca.cnf - export OPENSSL_CONF="ca.cnf" - openssl req -x509 -sha256 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes \ - -days 365 -subj "/CN=moq cluster CA" \ - -keyout ca.key -out ca.pem + ../../sh/demo/ca.sh # Generate a self-signed certificate using the root CA. - -# Chrome requires a <=14 day validity for self-signed certs. +[positional-arguments] cert name: ca - #!/usr/bin/env bash - set -euo pipefail - umask 077 - - export OPENSSL_CONF="ca.cnf" - openssl req -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes \ - -subj "/CN={{ name }}" \ - -keyout "{{ name }}.key" -out "{{ name }}.csr" - openssl x509 -req -sha256 -in "{{ name }}.csr" \ - -CA ca.pem -CAkey ca.key -CAcreateserial \ - -days 14 -extfile <(printf "subjectAltName=DNS:localhost\n") \ - -out "{{ name }}.crt" - rm "{{ name }}.csr" + ../../sh/demo/cert.sh "$@" # Generate a random secret key for authentication. key: - #!/usr/bin/env bash - set -euo pipefail - umask 077 - - [ -f root.jwk ] && exit 0 - rm -f *.jwt - cargo run --bin moq -- auth generate --out root.jwk + ../../sh/demo/key.sh # Generate authentication tokens for local development. token: key - #!/usr/bin/env bash - set -euo pipefail - umask 077 - - if [ ! -f demo-web.jwt ]; then - cargo run --quiet --bin moq -- auth sign --key root.jwk \ - --root demo --subscribe '**' --publish 'me/**' \ - > demo-web.jwt - fi - - if [ ! -f demo-cli.jwt ]; then - cargo run --quiet --bin moq -- auth sign --key root.jwk \ - --root demo --publish '**' \ - > demo-cli.jwt - fi + ../../sh/demo/token.sh diff --git a/demo/sub/justfile b/demo/sub/justfile index e7ec69ed855..824fd6674a2 100644 --- a/demo/sub/justfile +++ b/demo/sub/justfile @@ -1,6 +1,8 @@ set fallback +set shell := ["bash", "-euo", "pipefail", "-c"] # Subscribe to a broadcast using GStreamer and render to the screen. +[positional-arguments] gst name url='http://localhost:4443' *args: cargo build -p moq-gst @@ -8,6 +10,6 @@ gst name url='http://localhost:4443' *args: # by name so a bare `! decodebin3` can't latch onto the audio pad and leave the # video sink empty; route audio to its own sink so it doesn't stall the session. GST_PLUGIN_PATH_1_0="${PWD}/../../target/debug${GST_PLUGIN_PATH_1_0:+:$GST_PLUGIN_PATH_1_0}" \ - gst-launch-1.0 -v -e moqsrc name=s url="{{ url }}" broadcast="{{ name }}" {{ args }} \ + gst-launch-1.0 -v -e moqsrc name=s url="{{ url }}" broadcast="{{ name }}" "${@:3}" \ s.video_0 ! queue ! decodebin3 ! videoconvert ! autovideosink \ s.audio_0 ! queue ! decodebin3 ! audioconvert ! autoaudiosink diff --git a/doc/setup/dev.md b/doc/setup/dev.md index d8d35f9ff87..b17faa24049 100644 --- a/doc/setup/dev.md +++ b/doc/setup/dev.md @@ -7,7 +7,8 @@ description: Build, test, and debug the MoQ repository The repository uses [Just](https://github.com/casey/just) as its command runner. Run commands inside the Nix dev shell (`nix develop`) so your tools -match CI. +match CI. `just check` and `just fix` refuse to run outside it; set +`MOQ_ALLOW_HOST=1` to use the host toolchain anyway. | Command | Purpose | | --- | --- | @@ -72,6 +73,11 @@ just fix just check ``` +These diff the branch against its upstream (or `origin/main`) and run only the +modules the diff reaches. The map from paths to modules lives in +`sh/dispatch.sh`. Recipes stay thin: any logic (conditionals, loops, traps) +lives in a script under `sh/`. + See [CONTRIBUTING.md](https://github.com/moq-dev/moq/blob/main/CONTRIBUTING.md) for branch targeting, commit messages, and reviews, and [Agent setup](/setup/agent) if an AI coding agent is doing the work. diff --git a/drafts/justfile b/drafts/justfile index 547465396e7..bdb39c6e4df 100644 --- a/drafts/justfile +++ b/drafts/justfile @@ -5,92 +5,28 @@ # # The toolchain (kramdown-rfc, xml2rfc, mmark) comes from the nix dev shell # (see `draftsDeps` in flake.nix), so `nix develop --command just drafts build` -# renders with the same tool versions everywhere. There is no submodule or -# venv to bootstrap: `kramdown-rfc` turns the markdown into RFC XML, `xml2rfc` -# renders the txt/html. +# renders with the same tool versions everywhere. `kramdown-rfc` turns the +# markdown into RFC XML, `xml2rfc` renders the txt/html. set working-directory := '.' -# Common xml2rfc flags. --allow-local-file-access lets it read the CSS/refs. -xml2rfc := "xml2rfc -q --allow-local-file-access" - # List the draft names (the argument to `build` / `publish`). default: - @for f in draft-*.md; do echo "${f%.md}"; done + @ls draft-*.md | sed 's/\.md$//' -# Render one draft to .txt and .html (local editor's copy, -# gitignored). Renders the -latest docname as-is; use `publish` for a version. +# Render one draft to .txt and .html (local editor's copy, gitignored). build name: - kramdown-rfc --v3 < {{ name }}.md > {{ name }}.xml - {{ xml2rfc }} --text {{ name }}.xml -o {{ name }}.txt - {{ xml2rfc }} --html {{ name }}.xml -o {{ name }}.html - @echo "built {{ name }}.txt and {{ name }}.html" + ../sh/drafts/build.sh {{ name }} # Render every draft. all: - @for f in draft-*.md; do just build "${f%.md}"; done + ../sh/drafts/build.sh # Validate that every draft parses and that its generated XML passes validation. -# -# Both halves are needed. kramdown-rfc catches markdown and frontmatter errors, -# but happily emits XML for a cross-reference that points at no such section; -# xml2rfc is what rejects the dangling IDREF. Checking only the first half lets -# a broken `[text](#anchor)` pass here and then fail at `publish` time, which is -# the worst place to find it. -# -# --preptool stops after validation instead of rendering txt/html, and -N keeps -# it off the network (kramdown-rfc already inlined the references), which is -# what makes this a couple of seconds per draft rather than a minute. check: - bun install --frozen-lockfile --cwd .. - @grep -n "$(printf '\t')" draft-*.md; case $? in \ - 0) echo "tabs render unpredictably in xml2rfc; indent with spaces" >&2; exit 1;; \ - 1) ;; \ - *) exit 1;; \ - esac - @for f in draft-*.md; do \ - echo "checking $f"; \ - kramdown-rfc --v3 < "$f" > "${f%.md}.xml" || exit 1; \ - {{ xml2rfc }} --preptool -N "${f%.md}.xml" -o "${f%.md}.prepped.xml" \ - || { rm -f "${f%.md}.prepped.xml"; exit 1; }; \ - rm -f "${f%.md}.prepped.xml"; \ - done - @for f in moq-e2ee-*.ts; do \ - bun tsc --noEmit --skipLibCheck --target esnext --module esnext --moduleResolution bundler --types bun "$f" || exit 1; \ - bun "$f" || exit 1; \ - done - -# Remove generated files and the reference cache. -clean: - rm -f draft-*.xml draft-*.txt draft-*.html - rm -rf .refcache + ../sh/drafts/check.sh -# Submit a new draft version to the IETF datatracker. The datatracker emails -# the submitter a confirmation link; the submission is not final until that -# link is clicked. For a brand-new draft (-00) set "Replaces" on the -# confirmation page. -# Example: just drafts publish draft-lcurley-moq-lite 05 you@example.com +# Submit a new draft version to the IETF datatracker, e.g. +# `just drafts publish draft-lcurley-moq-lite 05 you@example.com`. publish name version email: - #!/usr/bin/env bash - set -euo pipefail - case "{{ version }}" in - [0-9][0-9]) ;; - *) echo "version must be two digits, e.g. 05" >&2; exit 1 ;; - esac - doc="{{ name }}-{{ version }}" - if [ ! -f "{{ name }}.md" ]; then - echo "no such draft: {{ name }}.md" >&2; exit 1 - fi - echo "Building $doc.xml" - sed "s/{{ name }}-latest/$doc/g" "{{ name }}.md" | kramdown-rfc --v3 > "$doc.xml" - echo "Submitting $doc.xml to the datatracker as {{ email }}" - resp="$(mktemp)" - code="$(curl -sS -o "$resp" -w '%{http_code}' \ - -F "user={{ email }}" -F "xml=@$doc.xml" \ - https://datatracker.ietf.org/api/submission)" - echo "HTTP $code" - cat "$resp"; echo; rm -f "$resp" - case "$code" in - 200|201) echo "Submitted. Check {{ email }} for the confirmation link." ;; - *) echo "Submission failed." >&2; exit 1 ;; - esac + ../sh/drafts/publish.sh {{ name }} {{ version }} {{ email }} diff --git a/flake.nix b/flake.nix index 3529312a1e4..419fce61336 100644 --- a/flake.nix +++ b/flake.nix @@ -135,7 +135,7 @@ # unification would otherwise hide a broken single-crate build. cargo-hack cargo-nextest - # Browser/WASM bindings (rs/moq-wasm -> @moq/wasm via `just wasm`). + # Browser/WASM bindings (rs/moq-wasm -> @moq/wasm via `just js wasm`). # wasm-bindgen-cli must match the `wasm-bindgen` crate version (the # crate is pinned to nixpkgs' CLI version); bump both together. wasm-bindgen-cli @@ -245,10 +245,9 @@ ]; # Linters / formatters used by `just check` and `just fix`, which - # guard each tool with `command -v` so they skip silently when the - # binary isn't on $PATH. CI sets MOQ_STRICT=1, which turns that skip - # into an error (see `_tools` in the root justfile), so this list and - # that one have to stay in step. + # skip a module whose tools aren't on $PATH. CI sets MOQ_STRICT=1, + # which turns that skip into an error (see the tools map in + # sh/dispatch.sh), so this list and that one have to stay in step. lintDeps = with pkgs; [ shellcheck shfmt @@ -277,8 +276,8 @@ # dependency in rs/moq-ffi/Cargo.toml. Five other places name the same # generator version and must be bumped together: the repo and revision # in release-go-ffi.yml, and the `cargo install` line in - # rs/moq-ffi/build.sh, go/ffi/README.md, go/scripts/check.sh, and - # go/scripts/stage.sh. + # rs/moq-ffi/build.sh, go/ffi/README.md, sh/go/check.sh, and + # sh/go/stage.sh. # # This points at a fork rather than NordSecurity because upstream has no # uniffi 0.32 generator: the metadata encoding changed in 0.32 even @@ -531,6 +530,10 @@ ''; env = { + # What sh/dispatch.sh checks before a scoped `just check` or `just + # fix`. IN_NIX_SHELL would also pass inside another project's shell. + MOQ_DEV_SHELL = "1"; + # Where `just obs compile` and `just obs test` look for libobs. Set # on every platform so the plugin type-checks against the pinned OBS # release everywhere, rather than whatever the host happens to have. diff --git a/go/.gitignore b/go/.gitignore index 9d1c2961a27..4e2b41f06ea 100644 --- a/go/.gitignore +++ b/go/.gitignore @@ -1,4 +1,4 @@ -# Generated by scripts/{check,package-ffi}.sh; the main repo stays binary-free. +# Generated by sh/go/{check,package-ffi}.sh; the main repo stays binary-free. ffi/moq/moq.go ffi/moq/moq.h ffi/moq/lib/ diff --git a/go/ffi/README.md b/go/ffi/README.md index 64a12a712ef..6edaf6937e2 100644 --- a/go/ffi/README.md +++ b/go/ffi/README.md @@ -20,9 +20,9 @@ The published module ships prebuilt `libmoq_ffi.a` for `linux/amd64`, `linux/arm ## Local development -`go/scripts/stage.sh` builds `moq-ffi` for the host, runs `uniffi-bindgen-go` to regenerate `moq.go`, and stages this module plus the wrapper into `dist/` with the wrapper wired to the local ffi by a `replace`. It prints the two staged module directories, so anything that needs to build Go against this checkout (`go/scripts/check.sh`, `test/interop`) shares one staging path. +`sh/go/stage.sh` builds `moq-ffi` for the host, runs `uniffi-bindgen-go` to regenerate `moq.go`, and stages this module plus the wrapper into `dist/` with the wrapper wired to the local ffi by a `replace`. It prints the two staged module directories, so anything that needs to build Go against this checkout (`sh/go/check.sh`, `test/interop`) shares one staging path. -`go/scripts/check.sh` stages that way and then runs `go build`/`go vet`/`go test`. It also runs `publish-wrapper.test.sh`, which drives the wrapper publisher against a scratch bare repo (no cargo, no network). Run via `just go check`. Skips cleanly without `cargo`, `go`, or `uniffi-bindgen-go`. +`sh/go/check.sh` stages that way and then runs `go build`/`go vet`/`go test`. Run via `just go check`. Skips cleanly without `cargo`, `go`, or `uniffi-bindgen-go`. The dev shell provides both `go` and `uniffi-bindgen-go`, so `nix develop --command just go check` needs no setup. Without Nix, install `uniffi-bindgen-go` once: @@ -49,8 +49,8 @@ go/ffi/ lib/_/libmoq_ffi.a (gitignored, staged at release time) ``` -Compiled binaries never live in the source tree. `scripts/check.sh` stages into the gitignored `dist/` working dir under the repo root; CI does the equivalent assembly into the [moq-dev/moq-go-ffi](https://github.com/moq-dev/moq-go-ffi) mirror. +Compiled binaries never live in the source tree. `sh/go/check.sh` stages into the gitignored `dist/` working dir under the repo root; CI does the equivalent assembly into the [moq-dev/moq-go-ffi](https://github.com/moq-dev/moq-go-ffi) mirror. ## Release -The `release-go-ffi.yml` workflow fires on every `moq-ffi-v*` tag, builds per-target static libraries, runs `uniffi-bindgen-go`, calls `go/scripts/package-ffi.sh` to assemble the module, and `go/scripts/publish-ffi.sh` to push the result to `moq-dev/moq-go-ffi` with a bare-semver tag (e.g. `v0.2.18`) lockstep with the crate. Go's module proxy picks up the new tag automatically. +The `release-go-ffi.yml` workflow fires on every `moq-ffi-v*` tag, builds per-target static libraries, runs `uniffi-bindgen-go`, calls `just go package-ffi` to assemble the module, and `just go publish-ffi` to push the result to `moq-dev/moq-go-ffi` with a bare-semver tag (e.g. `v0.2.18`) lockstep with the crate. Go's module proxy picks up the new tag automatically. diff --git a/go/ffi/moq/cgo.go b/go/ffi/moq/cgo.go index 8be6f790a68..50dc423b50e 100644 --- a/go/ffi/moq/cgo.go +++ b/go/ffi/moq/cgo.go @@ -3,12 +3,12 @@ // moq.dev/moq wrapper, which builds on this package. // // The exported API is generated from rs/moq-ffi via uniffi-bindgen-go and -// dropped in alongside this file (moq.go) by scripts/package-ffi.sh; the in-tree -// source therefore does not build on its own. Run scripts/check.sh to stage a +// dropped in alongside this file (moq.go) by sh/go/package-ffi.sh; the in-tree +// source therefore does not build on its own. Run sh/go/check.sh to stage a // complete copy into dist/ and exercise it. // // The per-platform static archive is loaded from moq/lib/_/ -// inside the staged module, populated by scripts/package-ffi.sh from the release +// inside the staged module, populated by sh/go/package-ffi.sh from the release // build matrix. package moq diff --git a/go/justfile b/go/justfile index d842e27d103..b4fa2d0d07c 100644 --- a/go/justfile +++ b/go/justfile @@ -10,36 +10,41 @@ default: # Stages both the ffi and wrapper modules into dist/ (wiring the wrapper to the # local ffi via replace). Skips cleanly if cargo, go, or uniffi-bindgen-go is -# missing. -# -# This runs the tests too, so there is no separate `just go test`. Takes an -# optional newline-separated list of changed files and skips when none are -# Go-scoped; `just go check` (no FILES) always runs. +# missing. This runs the tests too, so there is no separate `just go test`. # Build moq-ffi, run uniffi-bindgen-go, then `go build`/`go vet`/`go test`. -check $FILES="": - #!/usr/bin/env bash - set -euo pipefail - if [[ -n "$FILES" ]] && ! grep -qE '^(go/|rs/moq-ffi/)' <<< "$FILES"; then - echo "go: no Go changes; skipping." - exit 0 - fi - bash scripts/check.sh - -# Stage the in-tree go/ffi source + per-target moq-ffi libs + generated -# bindings into the moq.dev/moq-ffi module ready for publish. +check: + bash ../sh/go/check.sh + +# Release recipes run in the caller's directory, so a relative `--output` or +# `--tarball` means what it would to the script itself. + +# Stage the in-tree go/ffi source, per-target moq-ffi libs, and generated +# bindings into the moq.dev/moq-ffi module. + +# Stage the moq.dev/moq-ffi module for publish. +[no-cd] +[positional-arguments] package-ffi *args: - bash scripts/package-ffi.sh {{ args }} + {{ quote(justfile_directory() / "sh/go/package-ffi.sh") }} "$@" # Stage the in-tree go/wrapper source into the moq.dev/moq module, rewriting its -# moq.dev/moq-ffi require to the target ffi version, ready for publish. -package-wrapper *args: - bash scripts/package-wrapper.sh {{ args }} - -# The paths are the gitignored ones in go/.gitignore. `just go check` stages -# into the workspace dist/ instead, which `just js clean` sweeps, so these only -# show up when uniffi-bindgen-go or `go mod` is pointed at the tree directly. +# moq.dev/moq-ffi require to the target ffi version. -# Remove the generated bindings, native libs, and vendoring from go/. -clean: - rm -rf ffi/moq/moq.go ffi/moq/moq.h ffi/moq/lib ffi/go.sum ffi/vendor wrapper/go.sum wrapper/vendor +# Stage the moq.dev/moq wrapper module for publish. +[no-cd] +[positional-arguments] +package-wrapper *args: + {{ quote(justfile_directory() / "sh/go/package-wrapper.sh") }} "$@" + +# Push the staged moq-go-ffi module to the moq-dev/moq-go-ffi mirror. +[no-cd] +[positional-arguments] +publish-ffi *args: + {{ quote(justfile_directory() / "sh/go/publish-ffi.sh") }} "$@" + +# Push the staged moq-go wrapper module to the moq-dev/moq-go mirror. +[no-cd] +[positional-arguments] +publish-wrapper *args: + {{ quote(justfile_directory() / "sh/go/publish-wrapper.sh") }} "$@" diff --git a/go/wrapper/README.md b/go/wrapper/README.md index dbc9bd15b07..781c8d055e9 100644 --- a/go/wrapper/README.md +++ b/go/wrapper/README.md @@ -121,4 +121,4 @@ The committed `go.mod` carries a `require moq.dev/moq-ffi v0.0.0` **placeholder* ## Local development -Run `just go check`: it builds `moq-ffi` for the host, regenerates the bindings, stages both modules into `dist/` with a `replace` wiring the wrapper to the local ffi, and runs `go build`/`go vet`/`go test`. It also runs `scripts/publish-wrapper.test.sh`, which exercises the publisher's release/no-op/recovery paths against a scratch bare repo standing in for the mirror. See [../ffi/README.md](../ffi/README.md) for the `uniffi-bindgen-go` install. +Run `just go check`: it builds `moq-ffi` for the host, regenerates the bindings, stages both modules into `dist/` with a `replace` wiring the wrapper to the local ffi, and runs `go build`/`go vet`/`go test`. See [../ffi/README.md](../ffi/README.md) for the `uniffi-bindgen-go` install. diff --git a/go/wrapper/go.mod b/go/wrapper/go.mod index e306de284d7..eba975c62c7 100644 --- a/go/wrapper/go.mod +++ b/go/wrapper/go.mod @@ -3,7 +3,7 @@ module moq.dev/moq go 1.23 // The require below is a placeholder. The real version is rewritten at release -// time by go/scripts/package-wrapper.sh to the latest published moq-ffi, and +// time by sh/go/package-wrapper.sh to the latest published moq-ffi, and // `just go check` injects a local `replace` to the freshly-generated bindings. // Do not "fix" this by hand or add a replace directive to the committed file. require moq.dev/moq-ffi v0.0.0 diff --git a/js/common/workers.test.ts b/js/common/workers.test.ts deleted file mode 100644 index 5b11c5e1fba..00000000000 --- a/js/common/workers.test.ts +++ /dev/null @@ -1,45 +0,0 @@ -import { expect, test } from "bun:test"; -import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; -import { tmpdir } from "node:os"; -import { join, resolve } from "node:path"; - -test("worker checks select changed projects and propagate build failures", () => { - const temp = mkdtempSync(join(tmpdir(), "moq-workers-")); - const log = join(temp, "calls"); - writeFileSync( - join(temp, "bun"), - '#!/bin/sh\nprintf "%s %s\\n" "$PWD" "$*" >> "$WORKER_TEST_LOG"\nif [ "$*" = "run deploy --dry-run" ]; then exit "$WORKER_TEST_EXIT"; fi\n', - { mode: 0o755 }, - ); - try { - for (const project of ["infra/apt", "infra/rpm", "demo/pub"]) { - writeFileSync(log, ""); - const result = Bun.spawnSync(["just", "js", "check", `${project}/bun.lock`], { - cwd: resolve(import.meta.dir, "../.."), - env: { - ...process.env, - PATH: `${temp}:${process.env.PATH}`, - WORKER_TEST_LOG: log, - WORKER_TEST_EXIT: "0", - }, - }); - expect(result.exitCode).toBe(0); - expect(readFileSync(log, "utf8").trim().split("\n")).toEqual([ - `${resolve(import.meta.dir, "../..", project)} install --frozen-lockfile`, - `${resolve(import.meta.dir, "../..", project)} run deploy --dry-run`, - ]); - } - const failed = Bun.spawnSync(["just", "js", "check", "infra/apt/bun.lock"], { - cwd: resolve(import.meta.dir, "../.."), - env: { - ...process.env, - PATH: `${temp}:${process.env.PATH}`, - WORKER_TEST_LOG: log, - WORKER_TEST_EXIT: "1", - }, - }); - expect(failed.exitCode).not.toBe(0); - } finally { - rmSync(temp, { recursive: true, force: true }); - } -}); diff --git a/js/justfile b/js/justfile index 4be426446e8..7118f097734 100644 --- a/js/justfile +++ b/js/justfile @@ -6,108 +6,53 @@ set working-directory := '.' -# Paths a JS check depends on: every bun workspace (they are not all under js/, -# see the root package.json) plus the config shared by all of them. `check`, -# `fix`, and `ci` all skip themselves when a diff misses this. -scope := '^(js/|doc/|drafts/|demo/(boy|web)/|test/interop/clients/js|test/wasm/|package\.json$|bun\.lock(b)?$|biome\.jsonc$)' - # Run all checks by default. default: just check -install: - bun install - -# Takes an optional newline-separated list of changed files and skips if none -# match the JS scope; `just js check` (no FILES) always runs. -# -# FILES is an exported parameter, not `{{ FILES }}`: just interpolates the -# latter into the recipe source, where a filename like `$(...)` would run as a -# command. Git-derived paths are untrusted input, so they stay data. - # `build` runs here rather than as its own gate: the per-package `check` script # is `tsc --noEmit`, which never runs declaration emit, so the errors that only # surface when emitting a `.d.ts` (TS4023 and friends) pass `check` and then # break a JSR/npm publish. It costs about 20s for every package. - +# # `common/deps.ts` runs first and cheaply: bundlers resolve an undeclared # workspace import through hoisting, so nothing else in `check` notices one. +# doc/ is in scope, so the binding pages' stats fields are checked here too. # Lint, type-check, biome-format, and build all packages. -check $FILES="": - #!/usr/bin/env bash - set -euo pipefail - # These Workers have independent lockfiles outside the Bun workspace. - # Validate the deploy bundle without publishing or requiring credentials. - for project in infra/apt infra/rpm demo/pub; do - if [[ -z "$FILES" ]] || grep -qE "^($project/|js/justfile$)" <<< "$FILES"; then - ( - cd "../$project" - bun install --frozen-lockfile - bun run deploy --dry-run - ) - fi - done - if [[ -n "$FILES" ]] && ! grep -qE '{{ scope }}' <<< "$FILES"; then - echo "js: no JS changes; skipping." - exit 0 - fi - # doc/ is in this scope, so the binding pages are checked here. - python3 ../rs/scripts/stats-docs.py +check: + python3 ../sh/rs/stats-docs.py bun install --frozen-lockfile bun common/deps.ts - if tty -s; then - bun run --filter='*' --elide-lines=0 check - else - bun run --filter='*' check - fi + bun run --filter='*' --elide-lines=0 check bun biome check just build -# Auto-fix lint and formatting issues. Skips on the same terms as `check`. -fix $FILES="": - #!/usr/bin/env bash - set -euo pipefail - if [[ -n "$FILES" ]] && ! grep -qE '{{ scope }}' <<< "$FILES"; then - echo "js: no JS changes; skipping." - exit 0 - fi +# Validate the Worker deploy bundles outside the Bun workspace. +workers: + ../sh/js/workers.sh + +# Auto-fix lint and formatting issues. +fix: bun install bun biome check --write -# Run all unit tests. Skips on the same terms as `check`. -test $FILES="": - #!/usr/bin/env bash - set -euo pipefail - if [[ -n "$FILES" ]] && ! grep -qE '{{ scope }}' <<< "$FILES"; then - echo "js: no JS changes; skipping tests." - exit 0 - fi +# Run all unit tests. +test: + bun install --frozen-lockfile + bun test common/declarations.test.ts common/deps.test.ts + bun run --filter='*' --elide-lines=0 test + +# Run one net benchmark: broadcasts, forward, reader, frames, track, varint, or lite-varint. +bench name: bun install --frozen-lockfile - bun test common/declarations.test.ts common/deps.test.ts common/workers.test.ts - if tty -s; then - bun run --filter='*' --elide-lines=0 test - else - bun run --filter='*' test - fi + bun net/bench/{{ name }}.ts # Build all packages. build: bun run --filter='*' build -# Remove node_modules and build output. The bun workspace spans the repo - -# (deps hoist to the root, not into js/), so sweep from the workspace root. -clean: - #!/usr/bin/env bash - set -euo pipefail - cd .. - find . -name .claude -prune -o \ - -type d \( -name node_modules -o -name dist -o -name out -o -name pkg \) \ - -prune -exec rm -rf {} + - find . -name .claude -prune -o -type f -name '*.tsbuildinfo' -exec rm -f {} + - -# Pull in new versions and report what's outdated. -update: - bun update - bun outdated +# Build browser/WASM bindings into @moq/wasm using the pinned wasm-bindgen toolchain. +wasm: + cargo build --locked -p moq-wasm --target wasm32-unknown-unknown --profile wasm-release + wasm-bindgen --target web --out-name moq --out-dir wasm/dist "${CARGO_TARGET_DIR:-../target}/wasm32-unknown-unknown/wasm-release/moq_wasm.wasm" diff --git a/js/wasm/.gitignore b/js/wasm/.gitignore index d3d540b01fb..b7322370aeb 100644 --- a/js/wasm/.gitignore +++ b/js/wasm/.gitignore @@ -1,3 +1,3 @@ -# Generated by `just wasm` (wasm-bindgen). The .wasm binary and JS glue are +# Generated by `just js wasm` (wasm-bindgen). The .wasm binary and JS glue are # build artifacts, not source: build them, never commit them. /dist/ diff --git a/js/wasm/README.md b/js/wasm/README.md index a3f2c2f2949..0cb4a6c4686 100644 --- a/js/wasm/README.md +++ b/js/wasm/README.md @@ -32,7 +32,7 @@ calls. Freeing a `Session` also closes it. `dist/` is generated, not committed. Build it from the repo root: ```bash -just wasm +just js wasm ``` That compiles `rs/moq-wasm` for `wasm32-unknown-unknown`, runs `wasm-bindgen` diff --git a/justfile b/justfile index bbba70cb92a..c20feb7f2d6 100644 --- a/justfile +++ b/justfile @@ -1,5 +1,8 @@ #!/usr/bin/env just --justfile # Using Just: https://github.com/casey/just?tab=readme-ov-file#installation +# +# Every recipe is a menu entry: one line that runs a tool, or a script under +# sh/. Logic belongs in the script. set unstable @@ -29,10 +32,6 @@ mod relay 'demo/relay' mod sub 'demo/sub' mod web 'demo/web' -# Byte budget for a changed-file list, sized so it survives being passed as a -# single argv/env string on every hop of the dispatch. See `_changed`. -changed_max := '65536' - # Run the demo by default. default: just demo @@ -43,912 +42,47 @@ dev: # Benchmark the current tree, or compare it with a commit: `just bench origin/main`. bench $BASE="": - #!/usr/bin/env bash - exec just --justfile bench/justfile compare "$BASE" + bench/run.sh "$BASE" # Compare one multi-threaded Tokio runtime with the same number of independent -# Tokio/epoll and io_uring workers. Defaults to every logical CPU. -bench-runtime $ROUNDS="3" $WORKERS="": - #!/usr/bin/env bash - exec just --justfile bench/justfile runtime "$ROUNDS" "$WORKERS" - -# A linked worktree's Git metadata does not live under its own root: the -# per-worktree directory is `--git-dir` and everything shared (objects, remote -# refs, the branch namespace) is under `--git-common-dir`, which for an agent -# checkout is inside the main repository. Write access to the source tree -# therefore says nothing about whether this checkout can fetch, branch, or -# rebase; the answer is a property of those two directories, and finding out by -# running `git fetch` and reading the error is the slow way. -# -# `check` reports; `setup` fetches, points the branch at its base, and records -# the SHA it fetched under the per-worktree Git directory, where `check` reads it -# back to say how stale the recorded base has become. Neither ever resets, -# rebases, cleans, or checks anything out: a dirty tree is someone's work in -# progress, and adopting a checkout must not be able to destroy it. -# -# BASE follows the same rule as the rest of the repo (see `_base`): `main` -# unless the branch's upstream says otherwise. - -# Report a worktree's base, Git metadata access, and state; `setup` also fetches. -worktree ACTION="check" $BASE="": - #!/usr/bin/env bash - set -euo pipefail - - case "{{ ACTION }}" in - check | setup) ;; - *) - echo "usage: just worktree [check|setup] [BASE]" >&2 - exit 2 - ;; - esac - - root=$(git rev-parse --show-toplevel) - git_dir=$(cd "$(git rev-parse --git-dir)" && pwd) - common_dir=$(cd "$(git rev-parse --git-common-dir)" && pwd) - branch=$(git branch --show-current || true) - - # A written probe rather than `[[ -w ]]`: the directory can be readable and - # nominally writable while the sandbox, a read-only mount, or an ACL refuses - # the create, and it is the create that fetch and branch creation need. - access() { - local dir="$1" probe - [[ -d "$dir" ]] || { echo missing; return; } - [[ -r "$dir" ]] || { echo denied; return; } - probe="$dir/.moq-access-probe.$$" - if (umask 077 && : > "$probe") 2>/dev/null; then - rm -f "$probe" - echo write - else - echo read-only - fi - } - - # A directory git will create on demand is only as writable as its nearest - # existing parent, so probe upward instead of reporting it missing. - access_or_parent() { - local dir="$1" parent - while [[ ! -d "$dir" ]]; do - parent=$(dirname "$dir") - [[ "$parent" != "$dir" ]] || { echo missing; return; } - dir="$parent" - done - access "$dir" - } - - base=$(just _base "$BASE") - stamp="$git_dir/moq-base" - # Whichever remote provides the base, not always origin. A base whose first - # segment names no remote (a local branch, a tag) leaves origin. - remote="${base%%/*}" - git remote | grep -qx "$remote" || remote=origin - - objects=$(access "$common_dir/objects") - heads=$(access "$common_dir/refs/heads") - worktree_meta=$(access "$git_dir") - worktree=$(access "$root") - # Tracking is `branch..remote`/`.merge` in the repository config, which - # lives in the common directory alongside the `config.lock` the write needs, - # not in the branch's ref. Probing refs/heads for it would refuse on a - # writable config and, worse, proceed on a read-only one. - config=$(access "$common_dir") - # A fetch writes three places, not one: objects, the remote-tracking refs it - # updates, and FETCH_HEAD in the per-worktree directory. The refs are the - # narrow one: `refs/remotes/` is where `.lock` is created, so - # probing `refs/remotes` stops a directory short and passes a split that git - # then fails on. - tracking=$(access_or_parent "$common_dir/refs/remotes/$remote") - - echo "worktree: $root" - echo "branch: ${branch:-(detached)} $(git rev-parse --short HEAD)" - echo "git-dir: $git_dir ($worktree_meta)" - echo "common-dir: $common_dir ($config)" - echo " fetch needs $common_dir/objects: $objects" - echo " $common_dir/refs/remotes/$remote: $tracking" - echo " $git_dir (FETCH_HEAD): $worktree_meta" - echo " branch needs $common_dir/refs/heads: $heads" - echo " upstream needs $common_dir/config: $config" - echo " rebase needs $git_dir: $worktree_meta" - echo " $root: $worktree" - echo " $common_dir/refs/heads: $heads" - - dirty=$(git status --porcelain | wc -l | tr -d ' ') - echo "dirty: $dirty tracked/untracked path(s)" +# Tokio/epoll and io_uring workers; WORKERS defaults to every logical CPU. - if [[ "{{ ACTION }}" == setup ]]; then - blocked="" - [[ "$objects" == write ]] || blocked="$blocked $common_dir/objects ($objects)" - [[ "$tracking" == write ]] || blocked="$blocked $common_dir/refs/remotes/$remote ($tracking)" - [[ "$worktree_meta" == write ]] || blocked="$blocked $git_dir ($worktree_meta)" - if [[ -n "$blocked" ]]; then - echo "error: cannot fetch;$blocked" >&2 - echo " grant write access to the main repository's Git directory, not just this worktree" >&2 - exit 1 - fi - # The remote resolved above, not always origin: recording a stamp against a - # ref nobody refreshed is worse than recording none, and `just check` would - # scope the branch against a base that has since moved. - git fetch --quiet "$remote" - # Repointing an upstream someone chose would silently change what `just - # check` scopes against, so only three cases write it: no upstream, an - # upstream `_base` discards anyway (the branch's own remote copy, which - # `git push -u` leaves behind and which says nothing about what the branch - # merges into), and a base the caller named on the command line. - upstream=$(git rev-parse --abbrev-ref '@{upstream}' 2> /dev/null || true) - # Two things stop the write, and they fail identically: a detached HEAD has - # no branch to hang an upstream on, and the config it lands in may be - # read-only. Skipping either silently would report a setup that recorded - # the caller's base while `just check` still scoped against origin/main. - blocker="" - if [[ -z "$branch" ]]; then - blocker="HEAD is detached" - elif [[ "$config" != write ]]; then - blocker="$common_dir/config is $config" - fi - if [[ -z "$upstream" ]] || [[ "$upstream" == */"$branch" ]] || [[ -n "$BASE" ]]; then - if [[ -z "$blocker" ]]; then - git branch --set-upstream-to "$base" "$branch" - elif [[ "$base" == origin/main ]]; then - # Nothing is lost: with no upstream `_base` falls back to - # origin/main, which is what this would have written. - echo "warning: cannot record the upstream; $blocker" >&2 - else - # The upstream is the only place this choice survives, so a setup - # that could not write it did not do what it was asked. - echo "error: cannot set the upstream to $base; $blocker" >&2 - echo " the branch would keep scoping against origin/main" >&2 - exit 1 - fi - fi - # Resolved, written, then renamed into place. A redirect straight into the - # stamp truncates it before git runs, so a failure there would leave an - # empty file that reads back as a recorded base that never existed. Each - # setup needs its own temporary file so concurrent runs cannot rename or - # overwrite each other's in-progress stamp. - if [[ "$worktree_meta" == write ]]; then - stamp_tmp=$(mktemp "$git_dir/.moq-base.XXXXXXXX") - if ! git rev-parse "$base" > "$stamp_tmp"; then - rm -f "$stamp_tmp" - exit 1 - fi - mv "$stamp_tmp" "$stamp" - fi - fi - - if ! git rev-parse --verify --quiet "$base^{commit}" > /dev/null; then - echo "base: $base (NOT FETCHED; run 'just worktree setup')" - exit 0 - fi - - head=$(git rev-parse "$base") - echo "base: $base $(git rev-parse --short "$base")" - echo "upstream: $(git rev-parse --abbrev-ref '@{upstream}' 2> /dev/null || echo '(unset)')" - echo "behind: $(git rev-list --count "HEAD..$base") commit(s)" - - recorded="" - [[ -f "$stamp" ]] && recorded=$(cat "$stamp") - - # A stamp that no longer names a commit is worse than none: reporting it would - # abort here on the `rev-parse --short` rather than say what to do about it. - # An interrupted setup, or a base garbage-collected out of the repository. - if [[ -z "$recorded" ]]; then - echo "recorded: (none; run 'just worktree setup')" - elif ! git rev-parse --verify --quiet "$recorded^{commit}" > /dev/null; then - echo "recorded: $recorded (UNKNOWN COMMIT; run 'just worktree setup')" - elif [[ "$recorded" == "$head" ]]; then - echo "recorded: $(git rev-parse --short "$recorded") (current)" - else - echo "recorded: $(git rev-parse --short "$recorded") (STALE; $base has moved since setup)" - fi +# Compare a shared Tokio runtime with independent workers: `just bench-runtime 5 16`. +bench-runtime $ROUNDS="3" $WORKERS="": + MOQ_BENCH_RUNTIME_ROUNDS="$ROUNDS" MOQ_BENCH_RUNTIME_WORKERS="$WORKERS" bench/run.sh --runtime # Install repo-wide tooling. Per-language deps install on first check. install: bun install - cargo install --locked cargo-shear cargo-sort cargo-upgrades cargo-edit cargo-semver-checks release-plz - -# Resolve BASE: arg > $GITHUB_BASE_REF > upstream > origin/main. A branch's -# upstream is the branch it merges into, which is the base a `dev`-targeted -# branch needs. `git push -u` repoints upstream at the branch's own remote copy, -# which would diff HEAD against itself, so ignore that case (see AGENTS.md). -# GITHUB_BASE_REF outranks the upstream because a PR checkout has no upstream -# configured, and the branch being merged into is exactly the base GitHub is -# asking about. -# -# Shared by `_changed` and `worktree`, so a checkout's scope and its reported -# base can never disagree. - -# Print the ref this branch is based on. -[private] -_base $BASE="": - #!/usr/bin/env bash - set -euo pipefail - - base="$BASE" - if [[ -z "$base" && -n "${GITHUB_BASE_REF:-}" ]]; then - base="origin/${GITHUB_BASE_REF}" - fi - if [[ -z "$base" ]]; then - base=$(git rev-parse --abbrev-ref '@{upstream}' 2>/dev/null || true) - if [[ -z "$base" || "$base" == */"$(git branch --show-current)" ]]; then - base="origin/main" - fi - fi - printf '%s\n' "$base" - -# Reports the base it picked on stderr, so a surprising scope is traceable. -# -# LIMIT is the byte budget for the printed list, and exists as a parameter so -# `_changed-test` can force the oversized path without a synthetic 30k-file diff. - -# Print the files this branch changed relative to BASE, one per line, or `ALL`. -[private] -_changed $BASE $LIMIT=changed_max: - #!/usr/bin/env bash - set -euo pipefail - - base=$(just _base "$BASE") - - merge_base=$(git merge-base "$base" HEAD) || { - echo "error: cannot resolve merge-base against $base (is full history fetched?)" >&2 - exit 1 - } - echo "base: $base" >&2 - - # Untracked files count too: a brand new crate or module is the whole change. - files=$({ - git diff --name-only "$merge_base" - git ls-files --others --exclude-standard - } | sort -u) - - # Assigned rather than tested inline, so a failing `_changed-cap` aborts here - # under `set -e`. Inside `[[ ]]` its exit status is discarded, and the caller - # would then scope to a list that never got budgeted -- straight back into the - # E2BIG this exists to prevent. - cap=$(printf '%s' "$files" | just _changed-cap "$LIMIT") - if [[ "$cap" == ALL ]]; then - echo ALL - exit 0 - fi - - # Guarded because a bare printf of an empty list prints a newline, and the - # callers test the result for emptiness to decide whether anything changed. - if [[ -n "$files" ]]; then - printf '%s\n' "$files" - fi - -# Every hop of the dispatch takes the changed-file list as one argument, and -# just exports recipe parameters into the child's environment, so the whole list -# has to fit in a single execve string. Linux caps one string at MAX_ARG_STRLEN -# (32 pages, 131072 bytes) however large ARG_MAX is, so past that each hop dies -# with E2BIG, which just reports as exit code 126 and no mention of the diff. A -# diff that large selects most of the workspace anyway, so the callers widen to -# the unscoped suite, which passes no list at all. -# -# Split out from `_changed` so `_changed-test` can drive the decision with a -# synthetic list, rather than needing the working tree to hold a diff of a -# particular size. -# -# The list arrives on stdin, which is both the only channel that can carry an -# oversized one and the only way to measure it honestly: `${#var}` counts -# CHARACTERS under a UTF-8 locale while execve counts BYTES, so a path set of -# 3-byte characters would read as a third of its real size and sail past a -# budget it actually blows. - -# Print `ALL` when the changed-file list on stdin is too long for one argument. -[private] -_changed-cap $LIMIT=changed_max: - #!/usr/bin/env bash - set -euo pipefail - - [[ "$LIMIT" =~ ^[0-9]+$ ]] || { - echo "changed: not a byte count: $LIMIT" >&2 - exit 2 - } - - bytes=$(wc -c | tr -d '[:space:]') - if ((bytes > LIMIT)); then - echo "changed: $bytes bytes of paths exceeds the $LIMIT budget; selecting everything." >&2 - echo ALL - fi - -# Guards the thing that fails LOUDLY but unhelpfully: past the budget every -# `just` hop dies with "Argument list too long" and exit 126, naming neither the -# diff nor the recipe that could not receive it. Both halves matter -- a budget -# that never trips scopes nothing, and one above what execve accepts still dies. - -# Check that an oversized diff widens to `ALL`, and that the budget fits in argv. -[private] -_changed-test $LIMIT=changed_max: - #!/usr/bin/env bash - set -euo pipefail - - fail() { echo "changed: _changed-test: $1" >&2; exit 1; } - - # Synthetic sizes rather than whatever the working tree happens to hold: a - # clean checkout has no diff at all, and `check --all` runs there (cache.yml - # warms the cache from `main`), so a test keyed on the real list would take - # down the one job allowed to write the shared Rust cache. - [[ "$(printf 'aaaa' | just _changed-cap 3)" == ALL ]] || fail "over budget must print ALL" - [[ -z "$(printf 'aaa' | just _changed-cap 3)" ]] || fail "at budget must print nothing" - [[ -z "$(printf '' | just _changed-cap 3)" ]] || fail "an empty diff must print nothing" - - # The smallest nonempty list there is, against the only budget below it. - [[ "$(printf 'x' | just _changed-cap 0)" == ALL ]] || fail "a 1-byte list must exceed a 0 budget" - - # execve counts bytes, so the budget has to as well. Spelled as raw bytes - # rather than as characters: this is one CJK character, 3 bytes wide, which - # `${#var}` would count as 1 under a UTF-8 locale and let past a 2-byte - # budget it actually blows. - [[ "$(printf '\xe6\x97\xa5' | just _changed-cap 2)" == ALL ]] \ - || fail "the budget must count bytes, not characters" - - # A byte count is the whole input, so anything else is a caller bug, not a - # reason to silently scope to nothing. - ! printf '' | just _changed-cap not-a-number 2> /dev/null || fail "a bad budget must be rejected" - - # ...and that rejection has to reach the caller. A swallowed one would hand - # back an unbudgeted list, which is the failure this whole recipe prevents. - ! just _changed "" not-a-number 2> /dev/null || fail "a rejected budget must fail _changed" - - # Linux caps a single argv/env string at MAX_ARG_STRLEN (32 pages), whatever - # ARG_MAX says, and the list travels as one string. Asserted rather than - # probed because this repo's CI is the Linux host and a dev box may be laxer. - ((LIMIT <= 131072)) || fail "budget $LIMIT exceeds Linux MAX_ARG_STRLEN" - - # The budget still has to survive the hop it was sized for, which the checks - # above cannot show: they never pass a list that big to anything. - payload=$(head -c "$LIMIT" /dev/zero | tr '\0' x) - [[ "$(just _echo "$payload" | wc -c)" -eq $((LIMIT + 1)) ]] \ - || fail "a $LIMIT-byte list does not survive an argv hop" - - # End to end, but only when there is a diff to be oversized: see above. The - # budget is zero rather than one because the real list is whatever the - # checkout holds, and a single one-character root path is a one-byte list - # that a one-byte budget does not exceed. Zero is below every nonempty list. - if [[ -n "$(just _changed "" 100000000)" ]]; then - [[ "$(just _changed "" 0)" == ALL ]] || fail "a diff over budget must print ALL" - fi - - echo "changed: budget ok" - -# Print an argument back, to measure what survives a `just` invocation. -[private] -_echo $VALUE: - @printf '%s\n' "$VALUE" - -# Tools every scope guards with `command -v`, so an incomplete local toolchain -# checks less instead of failing. That trade is wrong in CI, where a skip is -# indistinguishable from a pass, so CI exports MOQ_STRICT=1 and this turns the -# required set into a precondition. Checked up front, and as one list, so a -# missing tool is reported before a long compile rather than after it. -# -# Required per scope, mirroring what `check` actually dispatches for a given -# diff: demanding gradle on a docs-only PR would fail a run that was never going -# to invoke it. Takes the same file list as the dispatch, or `ALL` to require -# everything (`check --all`). -# -# One deliberate absence: swift exists only on macOS, and `swift check` skips -# off-macOS by design; swift.yml is its real gate. - -# Fail when a tool the diff's scopes need is missing. No-op unless MOQ_STRICT. -[private] -_tools $FILES="": - #!/usr/bin/env bash - set -euo pipefail - [[ -n "${MOQ_STRICT:-}" ]] || exit 0 - - scoped() { [[ "$FILES" == ALL ]] || grep -qE "$1" <<< "$FILES"; } - - # `_check-common` runs on every invocation, so its tools are unconditional. - tools=(actionlint bun jq nix nixfmt shellcheck shfmt taplo python3 nfpm dpkg-deb envsubst rpm) - scoped '^(drafts/|doc/\.vitepress/drafts\.ts$)' && tools+=(kramdown-rfc xml2rfc) - scoped '^(bench/|rs/|Cargo\.(toml|lock)$|rust-toolchain\.toml$)' && tools+=(cargo envsubst) - scoped '^(quest/|flake\.lock$)' && tools+=(quest) - scoped '^(py/|pyproject\.toml$|uv\.lock$|rs/moq-ffi/|doc/lib/py/|doc/lib/samples\.sh$)' && tools+=(uv) - scoped '^(kt/|rs/moq-ffi/|doc/lib/kt/|doc/lib/samples\.sh$)' && tools+=(gradle java) - # cargo because `go check` builds moq-ffi for the host, and skips on a - # missing cargo the same way it skips on a missing go. rsync because the - # publish scripts stage the mirror tree with it, so the publisher test skips - # without it, and a skip that keeps `just check` green is what MOQ_STRICT is - # here to prevent. - scoped '^(go/|rs/moq-ffi/)' && tools+=(go uniffi-bindgen-go cargo rsync) - scoped '^(dart/|rs/moq-ffi/)' && tools+=(cargo dart uniffi_bindgen_dart) - # Two obs recipes with two dispatch scopes, so two lines: over-requiring - # would fail a diff that never runs the recipe. `just obs compile` needs - # cargo to regenerate moq.h and pkg-config to locate Qt6 and ffmpeg. Every - # platform: the plugin type-checks against headers, and the dev shell ships - # those even on Darwin, where obs-studio can't build. - scoped '^(cpp/obs/|rs/libmoq/|flake\.nix$)' && tools+=(pkg-config cargo) - # `just obs check` lints with clang-format and gersemi, validates the CMake - # release configuration, and compares the three OBS pins, one of which moves - # on a flake.lock bump alone. - scoped '^(cpp/obs/|flake\.(nix|lock)$)' && tools+=(clang-format gersemi cmake) - - # Scopes overlap (rs/moq-ffi/ is in five of them), so the same tool can land - # in the list twice and be reported missing twice. Splitting on whitespace is - # safe: every entry is a bare command name. - tools=($(printf '%s\n' "${tools[@]}" | sort -u)) - - missing=() - for tool in "${tools[@]}"; do - command -v "$tool" >/dev/null 2>&1 || missing+=("$tool") - done - if ((${#missing[@]})); then - echo "error: MOQ_STRICT is set but these tools are missing: ${missing[*]}" >&2 - echo " run inside 'nix develop', or unset MOQ_STRICT to skip what isn't installed" >&2 - exit 1 - fi + cargo install --locked cargo-shear cargo-sort cargo-semver-checks release-plz # Lints, compiles, and tests only the packages the branch changed plus -# everything depending on them, so several worktrees can build at once. Rust -# compiles once: the test build doubles as the clippy gate (see `rs check-test`). -# `check --all` is the unscoped suite. +# everything depending on them; `check --all` is the unscoped suite. BASE +# defaults to the branch's upstream. Rust compiles once: its test build doubles +# as the clippy gate (see `rs check-test`). # Lint, compile, and test what the branch changed since BASE, plus its dependents. check $BASE="": - just _check "$BASE" true + sh/dispatch.sh check "$BASE" -# CI splits `check` into two parallel jobs, since one runner doing both takes -# about the sum of their times. Both share `check`'s scoping (and CI adds -# MOQ_STRICT=1), so there is no second, drifting definition of "checked". +# CI runs `check` as two parallel jobs, since one runner doing both takes about +# the sum of their times. Same dispatch, with MOQ_STRICT=1. -# Run half of `check` for CI: `check` lints and compiles, `test` runs the tests. +# Run half of `check` for CI: JOB `check` lints and compiles, `test` runs the tests. ci $JOB $BASE="": - #!/usr/bin/env bash - set -euo pipefail - case "$JOB" in - check) just _check "$BASE" false ;; - test) just _test "$BASE" ;; - *) - echo "ci: unknown job '$JOB', want check or test" >&2 - exit 2 - ;; - esac - -# TEST=false is `ci check`: Rust lints through `cargo clippy`, which only -# emits metadata and so finishes sooner than the test build it stands in for. - -# Lint and compile what the branch changed since BASE, and test it when TEST=true. -[private] -_check $BASE $TEST: - #!/usr/bin/env bash - set -euo pipefail - - if [[ "$BASE" == --all ]]; then - files=ALL - else - files=$(just _changed "$BASE") - fi - - # `_changed` says ALL when the list outgrew what argv can carry. The unscoped - # suite is the path that passes no list at all, so it is the one that works. - # The dispatch below lives in this file, which matches no - # language scope, so a PR that rewrites how CI dispatches would otherwise - # validate none of it. Widen to the unscoped suite instead. - if [[ "$files" != ALL ]] && grep -qE '^justfile$' <<< "$files"; then - echo "check: root orchestration changed; checking everything." >&2 - files=ALL - fi - - just _tools "$files" - - if [[ "$files" == ALL ]]; then - just js check - just drafts check - if [[ "$TEST" == true ]]; then - just rs check-test --workspace --exclude moq-net-fuzz - just rs play - else - just rs check --workspace --exclude moq-net-fuzz - fi - just rs tokio-features - just rs media-features - just --justfile bench/justfile check - quest check - just test drill-sensitivity --apply-only - # Not covered by the line above: moq-wasm only exists on the wasm32 target. - just rs wasm - just py check - just kt check - just swift check - just go check - just dart check - just obs check - just obs compile - just _flake - elif [[ -n "$files" ]]; then - just js check "$files" - just rs check-changed "$files" "$TEST" - if echo "$files" | grep -q '^bench/'; then - just --justfile bench/justfile check - fi - # Draft sources render into the doc site and carry their own kramdown-rfc - # plus vector checks; a drafts-only diff would otherwise skip both. - if echo "$files" | grep -qE '^(drafts/|doc/\.vitepress/drafts\.ts$)'; then - just drafts check - fi - # Quest documents form one graph, so validate the whole living tree when - # either a quest or the flake-pinned validator changes. - if echo "$files" | grep -qE '^(quest/|flake\.lock$)'; then - quest check - fi - # The drill mutations patch Rust source, so a Rust change can move the - # code they target. Only nightly runs the drills against them; this - # catches a stale patch in the PR that moved its code. - if echo "$files" | grep -qE '^(rs/|test/drill/)'; then - just test drill-sensitivity --apply-only - fi - just py check "$files" - just kt check "$files" - just swift check "$files" - just go check "$files" - just dart check "$files" - # Type-checking the plugin and its unit tests needs only headers, so it - # runs here rather than waiting for obs.yml to link them on Linux. libmoq - # is in scope because the plugin calls through its generated C header, and - # the tests restate those entry points as stubs, so an ABI change breaks - # both. flake.nix because it owns the libobs headers this compiles - # against -- obs.yml links against nixpkgs' obs-studio instead, so nothing - # else would notice that package going bad. - if echo "$files" | grep -qE '^(cpp/obs/|rs/libmoq/|flake\.nix$)'; then - just obs compile - fi - # flake.nix is in scope because `just obs check` is what compares the OBS - # version pinned there against buildspec.json, and either side can move. - # flake.lock too, because the third OBS the guard compares is nixpkgs' - # obs-studio, the one `just obs ci` links: it moves on a lock bump alone, - # and that bump is the change that opens the gap. - if echo "$files" | grep -qE '^(cpp/obs/|flake\.(nix|lock)$)'; then - just obs check - fi - # Validates flake eval + dev shell build; it no longer compiles the - # workspace, so it's cheap. Gated anyway: a pure doc/JS PR can't - # affect flake eval. - if echo "$files" | grep -qE '(^rs/|^Cargo\.(toml|lock)$|^flake\.lock$|\.nix$)'; then - just _flake - fi - else - echo "check: nothing changed." - fi - - # Rust already ran its tests above, from the build that linted it. The kt, - # swift, go, and dart checks always run theirs, so only js and py remain. - # An empty list means "everything" to the per-language recipes. - if [[ "$TEST" == true && -n "$files" ]]; then - scope=$files - [[ "$scope" == ALL ]] && scope= - just js test "$scope" - just py test "$scope" - fi - - just _check-common - -# `ci test`'s half of `_check`: the same scoping, but only the languages whose -# tests are separate from their check (js, rs, py). - -# Run unit tests for what the branch changed since BASE, plus its dependents. -[private] -_test $BASE: - #!/usr/bin/env bash - set -euo pipefail - - if [[ "$BASE" == --all ]]; then - files=ALL - else - files=$(just _changed "$BASE") - fi - - # Mirrors `_check`: widen to everything when the list outgrew argv or the - # dispatch itself changed. - if [[ "$files" != ALL ]] && grep -qE '^justfile$' <<< "$files"; then - echo "test: root orchestration changed; testing everything." >&2 - files=ALL - fi - - just _tools "$files" - - if [[ "$files" == ALL ]]; then - just js test - just rs test --workspace --exclude moq-net-fuzz - just rs play - just py test - elif [[ -n "$files" ]]; then - just js test "$files" - just rs test-changed "$files" - just py test "$files" - else - echo "test: nothing changed." - fi - -# Skips when nix is absent: the flake is not a precondition for working on the -# repo, and `_tools` already makes it required under MOQ_STRICT. - -# Validate flake evaluation and the dev shell build. -[private] -_flake: - @if command -v nix >/dev/null 2>&1; then nix flake check; fi - -# Repository-wide non-compiling checks shared by scoped and unscoped `check`. -# Optional shell, workflow, TOML, Nix, and justfile lints skip if missing. -# -# `bun install` because remark-cli lives in node_modules and `just js check` is -# where it would otherwise be installed, which a Rust-only diff skips. - -# Run shell checks or formatting over tracked files that exist in the worktree. -[private] -_shell $ACTION: - #!/usr/bin/env bash - set -euo pipefail - - if ! command -v shfmt >/dev/null 2>&1; then - exit 0 - fi - if [[ "$ACTION" == "check" ]] && ! command -v shellcheck >/dev/null 2>&1; then - exit 0 - fi - - scripts_file=$(mktemp) - trap 'rm -f "$scripts_file"' EXIT - shfmt -f=0 . > "$scripts_file" - - scripts=() - while IFS= read -r -d '' file; do - if git --literal-pathspecs ls-files --error-unmatch -- "$file" >/dev/null 2>&1; then - scripts+=("$file") - fi - done < "$scripts_file" - ((${#scripts[@]})) || exit 0 - - case "$ACTION" in - check) - shfmt --diff "${scripts[@]}" - shellcheck "${scripts[@]}" - ;; - fix) - shfmt --write "${scripts[@]}" - ;; - *) - echo "invalid shell action: $ACTION" >&2 - exit 2 - ;; - esac - -# remark-cli has no `--check`. `--frail` raises the exit code on lint messages, -# and only `--output` formats, so a file that is merely misformatted passes both -# ways. Format a scratch mirror and diff that, so the check stays read-only -# while `fix` still writes in place. - -# Run Markdown lints over the worktree, either checking formatting or applying it. -[private] -_markdown $ACTION: - #!/usr/bin/env bash - set -euo pipefail - - case "$ACTION" in - check) ;; - fix) - bun remark . --quiet --output - exit 0 - ;; - *) - echo "invalid markdown action: $ACTION" >&2 - exit 2 - ;; - esac - - mirror=$(mktemp -d) - trap 'rm -rf "$mirror"' EXIT - - extension_list=$(bun -e \ - 'import extensions from "markdown-extensions"; console.log(extensions.join("\n"))') - patterns=() - while IFS= read -r extension; do - [[ -n "$extension" ]] && patterns+=("*.$extension") - done <<< "$extension_list" - ((${#patterns[@]})) || { - echo "error: remark reported no Markdown extensions" >&2 - exit 1 - } - - # Untracked files are in scope so a new doc is linted before it is staged; - # --exclude-standard keeps build output out. - files=() - while IFS= read -r -d '' file; do - [[ -f "$file" ]] || continue - files+=("$file") - mkdir -p "$mirror/$(dirname "$file")" - cp "$file" "$mirror/$file" - done < <(git ls-files -z --cached --others --exclude-standard -- "${patterns[@]}") - ((${#files[@]})) || exit 0 - - # The config rides along so every .remarkignore pattern resolves against the - # mirror root exactly as it does here, and node_modules is where the plugins - # named by .remarkrc.mjs come from. - cp .remarkrc.mjs .remarkignore "$mirror/" - ln -s "$PWD/node_modules" "$mirror/node_modules" - - status=0 - (cd "$mirror" && bun remark . --quiet --frail --output) || status=$? - - stale=() - for file in "${files[@]}"; do - cmp -s "$file" "$mirror/$file" || stale+=("$file") - done - - if ((${#stale[@]})); then - echo "error: these files are not formatted, run 'just fix':" >&2 - printf ' %s\n' "${stale[@]}" >&2 - status=1 - fi - - exit "$status" - -# Check Markdown formatting detection without touching the caller's worktree. -[private] -_markdown-test: - #!/usr/bin/env bash - set -euo pipefail - - fail() { echo "markdown: _markdown-test: $1" >&2; exit 1; } - - repo=$PWD - fixture=$(mktemp -d) - trap 'rm -rf "$fixture"' EXIT - - git -C "$fixture" init --quiet - cp .remarkrc.mjs .remarkignore "$fixture/" - ln -s "$repo/node_modules" "$fixture/node_modules" - for file in dirty.md dirty.markdown; do - printf '# dirty_heading\n' > "$fixture/$file" - git -C "$fixture" add "$file" - done - - original='# dirty_heading' - if just --justfile "$repo/justfile" --working-directory "$fixture" \ - _markdown check > "$fixture/check.log" 2>&1; then - fail "formatter-only drift must fail the check" - fi - for file in dirty.md dirty.markdown; do - [[ "$(<"$fixture/$file")" == "$original" ]] \ - || fail "the check modified $file" - grep -q "$file" "$fixture/check.log" \ - || fail "the check did not name $file" - done - - just --justfile "$repo/justfile" --working-directory "$fixture" _markdown fix - for file in dirty.md dirty.markdown; do - [[ "$(<"$fixture/$file")" == '# dirty\_heading' ]] \ - || fail "the fix did not format $file" - done - just --justfile "$repo/justfile" --working-directory "$fixture" _markdown check - - echo "markdown: check/fix regression ok" - -# Repository-wide lints, shared by scoped and unscoped `check`. -[private] -_check-common: - just _changed-test - bun install --frozen-lockfile - just _markdown-test - just _markdown check - just _shell check - @if command -v taplo >/dev/null 2>&1; then RUST_LOG=error taplo format --check; fi - @if command -v nixfmt >/dev/null 2>&1; then nixfmt --check $(find . -name '*.nix' -not -path './node_modules/*' -not -path './target/*' -not -path './.venv/*' -not -path './.direnv/*'); fi - @for f in $(find . -name justfile -not -path './node_modules/*' -not -path './target/*' -not -path './.venv/*' -not -path './.direnv/*'); do just --fmt --check --justfile "$f"; done - just gh check - -# Scoped exactly like `check`, because `clippy --fix` compiles what it fixes. -# Pass `--all` for the unscoped version. + sh/dispatch.sh "ci-$JOB" "$BASE" # Auto-fix lint and formatting for what the branch changed since BASE. fix $BASE="": - #!/usr/bin/env bash - set -euo pipefail - - if [[ "$BASE" == --all ]]; then - files=ALL - else - files=$(just _changed "$BASE") - fi - - # Mirrors `check`: too long for argv means fix everything instead. - if [[ "$files" == ALL ]]; then - just js fix - just rs fix --workspace --exclude moq-net-fuzz - just py fix - just dart fix - just obs fix - elif [[ -n "$files" ]]; then - just js fix "$files" - just rs fix-changed "$files" - just py fix "$files" - just dart fix "$files" - if echo "$files" | grep -q '^cpp/obs/'; then - just obs fix - fi - else - echo "fix: nothing changed." - fi - - just _fix-common - -# Optional tools skip if missing locally. `bun install` for the same reason as -# `_check-common`. - -# Repository-wide fixes, shared by scoped and unscoped `fix`. -[private] -_fix-common: - bun install - just _markdown fix - just _shell fix - @if command -v taplo >/dev/null 2>&1; then RUST_LOG=error taplo format; fi - @if command -v nixfmt >/dev/null 2>&1; then nixfmt $(find . -name '*.nix' -not -path './node_modules/*' -not -path './target/*' -not -path './.venv/*' -not -path './.direnv/*'); fi - @for f in $(find . -name justfile -not -path './node_modules/*' -not -path './target/*' -not -path './.venv/*' -not -path './.direnv/*'); do just --fmt --justfile "$f"; done + sh/dispatch.sh fix "$BASE" # Build the packages. build: just js build just rs build - if command -v uv &> /dev/null; then just py build; fi - if command -v wasm-bindgen &> /dev/null; then just wasm; fi - -# Build browser/WASM bindings into @moq/wasm using the pinned wasm-bindgen toolchain. -wasm: - cargo build --locked -p moq-wasm --target wasm32-unknown-unknown --profile wasm-release - wasm-bindgen --target web --out-name moq \ - --out-dir js/wasm/dist "${CARGO_TARGET_DIR:-target}/wasm32-unknown-unknown/wasm-release/moq_wasm.wasm" - -# Only this checkout by default. Agent worktrees each carry their own artifacts -# now that the shared target dir is gone, and another agent is usually building -# in one right now: `cargo clean` under a running build fails it, and there is no -# way to tell a finished worktree from a busy one from out here. `just clean all` -# is the explicit opt-in for a machine the caller knows is idle. -# -# Source is never touched either way, dirty or untracked: this deletes build -# output, not work. Nothing here reaches a machine-wide store -- no Nix garbage -# collection, no cargo/bun/uv home cache -- because those are shared with every -# other checkout and rebuilding them costs far more than the space they hold. + just py build + just js wasm # Delete this checkout's build artifacts and caches; `all` includes agent worktrees. clean SCOPE="here": - #!/usr/bin/env bash - set -euo pipefail - - case "{{ SCOPE }}" in - here | all) ;; - *) - echo "usage: just clean [here|all]" >&2 - exit 2 - ;; - esac - - just rs clean - just js clean - just py clean - just kt clean - just swift clean - just go clean - just dart clean - - # Caches not owned by any one language: nix build result, direnv, wrangler. - rm -rf result .direnv - find . -name .claude -prune -o -type d -name .wrangler -prune -exec rm -rf {} + - - # Worktrees don't nest, so this recurses exactly one level. Tolerate stale - # worktrees on branches that predate this recipe. - if [[ "{{ SCOPE }}" == all ]]; then - for wt in .claude/worktrees/*/; do - [ -f "${wt}justfile" ] || continue - echo "==> cleaning ${wt}" - (cd "$wt" && just clean) || echo " (skipped: just clean failed in ${wt})" - done - fi - -# Upgrade any tooling -update: - just js update - just rs update - nix flake update - -# Serve the documentation locally. -doc: - cd doc && bun run dev + sh/clean.sh {{ SCOPE }} diff --git a/kt/.gitignore b/kt/.gitignore index 25c4ac20b35..ae71352dba6 100644 --- a/kt/.gitignore +++ b/kt/.gitignore @@ -4,7 +4,7 @@ build/ local.properties .kotlin/ -# Generated by kt/scripts/{check,package}.sh. Never check these in. +# Generated by sh/kt/{check,package}.sh. Never check these in. moq-ffi/src/jvmAndAndroidMain/kotlin/uniffi/ moq-ffi/src/jvmMain/resources/ moq-ffi/src/androidMain/jniLibs/ diff --git a/kt/README.md b/kt/README.md index 62c509e960f..2afe6524f6d 100644 --- a/kt/README.md +++ b/kt/README.md @@ -89,7 +89,6 @@ kt/ src/ jvmAndAndroidMain/kotlin/dev/moq/ Wrapper sources (Moq, Server, Aliases, Flows, Durations, Errors) jvmAndAndroidTest/ Facade smoke test - scripts/ check.sh, package.sh ``` The native/UniFFI layer stays in a single `dev.moq:moq-ffi` artifact because uniffi-linked libraries can't be split across separately packaged artifacts (the Python `moq-rs` wheel is one umbrella for the same reason). That constraint is about the *native* layer; the pure-Kotlin `dev.moq:moq` wrapper sits cleanly on top of it as its own artifact because it ships no native code. diff --git a/kt/justfile b/kt/justfile index 8acb7ebe9b6..2a3994710a6 100644 --- a/kt/justfile +++ b/kt/justfile @@ -9,42 +9,23 @@ set working-directory := '.' default: just check -# Missing tools are errors so wrapper drift cannot slip past a green check. -# # This runs the tests too, so there is no separate `just kt test`: the script -# builds, generates, and tests as one gradle invocation. Takes an optional -# newline-separated list of changed files and skips when none are Kotlin-scoped; -# `just kt check` (no FILES) always runs. +# builds, generates, and tests as one gradle invocation. # Build moq-ffi, regenerate the bindings, and run :moq-ffi:jvmTest + :moq:jvmTest. -check $FILES="": - #!/usr/bin/env bash - set -euo pipefail - if [[ -n "$FILES" ]] && ! grep -qE '^(kt/|rs/moq-ffi/|doc/lib/kt/|doc/lib/samples\.sh$)' <<< "$FILES"; then - echo "kt: no Kotlin changes; skipping." - exit 0 - fi - bash scripts/check.sh +check: + bash ../sh/kt/check.sh # Regenerate the checked-in uniffi bindings and host native library without # compiling or testing. For environments that intentionally lack Gradle. generate: - bash scripts/generate.sh + bash ../sh/kt/generate.sh -# Assemble the KMP module from per-target moq-ffi binaries + bindings. -# Used by .github/workflows/release-kt-ffi.yml; see kt/README.md for the +# Runs in the caller's directory, so a relative `--lib-dir` or `--output` means +# what it would to the script itself. See kt/README.md for the --lib-dir layout. -# expected --lib-dir layout. +# Assemble the KMP module from per-target moq-ffi binaries and bindings. +[no-cd] +[positional-arguments] package *args: - bash scripts/package.sh {{ args }} - -# Remove gradle output plus the moq-ffi bindings and native libs that -# scripts/check.sh generates into the source tree (see kt/.gitignore). -clean: - #!/usr/bin/env bash - set -euo pipefail - find . -name .claude -prune -o -type d \( -name build -o -name .gradle -o -name .kotlin \) -prune -exec rm -rf {} + - rm -rf local.properties \ - moq/src/jvmAndAndroidMain/kotlin/uniffi \ - moq/src/jvmMain/resources \ - moq/src/androidMain/jniLibs + {{ quote(justfile_directory() / "sh/kt/package.sh") }} "$@" diff --git a/kt/moq-ffi/build.gradle.kts b/kt/moq-ffi/build.gradle.kts index c5e76a9f0bd..4aa387e97fe 100644 --- a/kt/moq-ffi/build.gradle.kts +++ b/kt/moq-ffi/build.gradle.kts @@ -11,7 +11,7 @@ // ├─ jvmMain JVM-specific: native libs as JAR resources // └─ androidMain Android-specific: native libs in jniLibs // -// Native libraries + bindings are populated by `kt/scripts/package.sh`: +// Native libraries + bindings are populated by `sh/kt/package.sh`: // src/jvmMain/resources/-/ (JNA classpath layout) // src/androidMain/jniLibs//libmoq_ffi.so (Android packaging layout) // src/jvmAndAndroidMain/kotlin/uniffi/moq/moq.kt (uniffi-bindgen output) diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/docs/Prelude.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/docs/Prelude.kt index 07e047ee815..9f15448a620 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/docs/Prelude.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/docs/Prelude.kt @@ -1,4 +1,4 @@ -// The inputs the documentation samples leave to the reader. kt/scripts/check.sh +// The inputs the documentation samples leave to the reader. sh/kt/check.sh // compiles every Kotlin sample from the docs beside this file, so a sample that // names a missing symbol or the wrong arity fails the check. Never executed. package dev.moq.docs diff --git a/py/justfile b/py/justfile index b95d0de995c..da3fc8cfbf7 100644 --- a/py/justfile +++ b/py/justfile @@ -10,16 +10,6 @@ set working-directory := '.' -# Paths a Python check depends on. `rs/moq-ffi` is in scope because maturin -# bundles it into the moq-ffi wheel. `check`, `fix`, and `test` all skip -# themselves when a diff misses this; no FILES at all means force-run. The docs -# are in scope because `check` type-checks their samples against the wrapper. -# -# They also skip when uv is absent, matching the kt/swift/go check scripts: an -# incomplete local toolchain should check less rather than fail. The root -# `_tools` preflight makes uv a hard requirement under MOQ_STRICT. -scope := '^(py/|pyproject\.toml$|uv\.lock$|rs/moq-ffi/|doc/lib/py/|doc/lib/samples\.sh$)' - default: just check @@ -40,17 +30,7 @@ _develop: # the Docs after the fact. It mocks the native module, so it costs no Rust build. # Lint, type-check, editable-build, check the doc samples, and render the docs. -check $FILES="": - #!/usr/bin/env bash - set -euo pipefail - if [[ -n "$FILES" ]] && ! grep -qE '{{ scope }}' <<< "$FILES"; then - echo "py: no Python changes; skipping." - exit 0 - fi - if ! command -v uv >/dev/null 2>&1; then - echo "py: uv not on PATH, skipping" >&2 - exit 0 - fi +check: uv sync --locked --no-install-workspace uv run --no-sync ruff check . uv run --no-sync ruff format --check . @@ -59,50 +39,18 @@ check $FILES="": just samples just docs -# Samples leave their inputs (`payload`, `pts`) to the reader, so they follow -# the declarations in moq-rs/tests/doc_prelude.py. - # Type-check every Python sample in the docs against the installed wrapper. samples: - #!/usr/bin/env bash - set -euo pipefail - out=$(mktemp -d) - trap 'rm -rf "$out"' EXIT - { - cat moq-rs/tests/doc_prelude.py - bash ../doc/lib/samples.sh python ../doc/lib/py/index.md moq-rs/README.md moq-rs/docs/index.md - } > "$out/samples.py" - echo '{"pythonVersion": "3.10"}' > "$out/pyrightconfig.json" - uv run --no-sync pyright --project "$out" "$out/samples.py" + ../sh/py/samples.sh -# Auto-fix lint and formatting issues. Skips on the same terms as `check`. -fix $FILES="": - #!/usr/bin/env bash - set -euo pipefail - if [[ -n "$FILES" ]] && ! grep -qE '{{ scope }}' <<< "$FILES"; then - echo "py: no Python changes; skipping." - exit 0 - fi - if ! command -v uv >/dev/null 2>&1; then - echo "py: uv not on PATH, skipping" >&2 - exit 0 - fi +# Auto-fix lint and formatting issues. +fix: uv sync --no-install-workspace uv run --no-sync ruff check --fix . uv run --no-sync ruff format . -# Run the unit tests. Skips on the same terms as `check`. -test $FILES="": - #!/usr/bin/env bash - set -euo pipefail - if [[ -n "$FILES" ]] && ! grep -qE '{{ scope }}' <<< "$FILES"; then - echo "py: no Python changes; skipping tests." - exit 0 - fi - if ! command -v uv >/dev/null 2>&1; then - echo "py: uv not on PATH, skipping" >&2 - exit 0 - fi +# Run the unit tests. +test: uv sync --locked --no-install-workspace just _develop uv run --no-sync pytest moq-rs/tests/ moq-ffi/tests/ @@ -114,18 +62,6 @@ build: uv sync --locked --no-install-workspace just _develop -# Remove the virtualenv, release dist, bytecode caches, and the uniffi -# bindings maturin drops in during editable installs. The uv workspace venv - -# lives at the repo root, so reach up for it. -clean: - #!/usr/bin/env bash - set -euo pipefail - rm -rf dist moq-ffi/moq_ffi/_uniffi - rm -rf ../.venv .venv - find . -name .claude -prune -o -type d -name __pycache__ -prune -exec rm -rf {} + - find . -name .claude -prune -o -type f -name '*.pyc' -exec rm -f {} + - # Build the pure-python moq-rs wrapper sdist + wheel into py/dist (for release). # moq-ffi is built separately by maturin (see release-py.yml); the wrapper is diff --git a/quest/m1/README.md b/quest/m1/README.md index 79e58213c6b..2d5a98509e4 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -66,7 +66,6 @@ QUIC studies there on that rule. - [#2991](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - one dynamic producer per track name in both languages, with the sequence namespace surviving a replacement - [JavaScript FETCH](/quest/m1/js-fetch.md) - generic on-demand group serving and IETF FETCH for browser publishers - [Archive](/quest/m1/archive/README.md) - record selected tracks to any object_store and replay them over FETCH or derived HLS; the catalog entry and format may break in place, since no archives exist -- [Tooling](/quest/m1/tooling/README.md) - justfiles become a one-line menu over `sh/`, one impact map scopes CI, and every workflow step runs a recipe - [In-band auth](/quest/m1/auth/README.md) - a session tells its peer what it may publish and subscribe to, unions tokens presented in band, and fails loud on an out-of-scope publish - [Dropped sources](/quest/m1/dropped-sources.md) - track consumers see the producer's real error on every end path, never `Dropped` - [C++ through moq-ffi](/quest/m1/cpp/README.md) - generated C++ over moq-ffi with futures and expected-style errors, shipped as a tarball, vcpkg, and Conan, and adopted by the OBS plugin diff --git a/quest/m1/bench-ci.md b/quest/m1/bench-ci.md index 7376f8e4a5c..79f0081e916 100644 --- a/quest/m1/bench-ci.md +++ b/quest/m1/bench-ci.md @@ -23,8 +23,8 @@ a GitHub App: - PR: one job builds base and head on the same runner and runs only the selected targets, saving and comparing Criterion baselines. Selection is the - changed crates plus their dependents, from the impact map that the - [tooling line](/quest/m1/tooling/README.md) lands. No selected bench + changed crates plus their dependents, from the impact map in + `sh/dispatch.sh`. No selected bench means no job. Extend `bench/run.sh` with a Criterion-only, crate-scoped mode behind a recipe instead of writing a second runner. Hosted runners vary by about 3%, so the comment highlights only changes Criterion calls @@ -43,10 +43,6 @@ a GitHub App: - Document the comment, the trend, and local reproduction in `bench/README.md`. -## Required - -- [Tooling](/quest/m1/tooling/README.md) - owns the diff-to-crate impact map the PR job reuses - ## Related - [Benchmark comparisons](/quest/m1/performance-comparisons.md) - extends the same `bench/run.sh` with repeated paired rounds diff --git a/quest/m1/capture-default.md b/quest/m1/capture-default.md index 8e2264afc87..d27fde791eb 100644 --- a/quest/m1/capture-default.md +++ b/quest/m1/capture-default.md @@ -22,7 +22,7 @@ pre-merge `just check` never runs moq-video's `capture` tests: it depends on [ALSA link](/quest/m1/capture-alsa-link.md). Once libasound loads at runtime, the default costs no system library. - Delete the special capture gate (`rs capture`, `capture-test`, and the - capture branch in `sh/rs/select.sh` on the tooling line) once default + capture branch in `sh/rs/select.sh`) once default `just check` covers it. Keep the platform jobs (`just rs macos`, `just rs windows`). - Update the Cargo feature comments, moq-cli's `capture` feature (it may @@ -34,5 +34,4 @@ tests, and a `default-features = false` consumer (for example ## Required -- [Tooling](/quest/m1/tooling/README.md) - rewrites the capture gate this deletes - [ALSA link](/quest/m1/capture-alsa-link.md) - moq-audio capture can't be on by default while it links libasound at build time diff --git a/quest/m1/doc-samples-go-dart.md b/quest/m1/doc-samples-go-dart.md index 6680e0a0345..50a05e0ec98 100644 --- a/quest/m1/doc-samples-go-dart.md +++ b/quest/m1/doc-samples-go-dart.md @@ -21,7 +21,7 @@ knows neither language. adjusting a sample so it reads naturally and still compiles over growing the extractor. - Wire each into its language's check script, `sh/go/check.sh` and - `sh/dart/check.sh` on the tooling line, the way `sh/kt/check.sh` and + `sh/dart/check.sh`, the way `sh/kt/check.sh` and `sh/py/samples.sh` call `samples.sh`. Add `doc/lib/go/`, `doc/lib/dart/`, and `doc/lib/samples.sh` to the `go` and `dart` patterns of the impact map in `sh/dispatch.sh`, as the `py`, `kt`, and `swift` ones already have. @@ -29,7 +29,3 @@ knows neither language. fail on the doc sample. Public API: none. Wire: none. - -## Required - -- [Tooling](/quest/m1/tooling/README.md) - the `sh//` check scripts and the impact map this extends diff --git a/quest/m1/gpu-ci.md b/quest/m1/gpu-ci.md index e294915c561..b3b0d6175df 100644 --- a/quest/m1/gpu-ci.md +++ b/quest/m1/gpu-ci.md @@ -26,8 +26,7 @@ skipping inside the Nix shell. tests (Android, D3D11, PipeWire). Inside that selection a missing GPU fails the test instead of returning early. Keep the no-driver tests (`missing_driver_errors_instead_of_panicking`) outside it. -- `just rs nvidia`, a one-line recipe over `sh/rs/nvidia.sh` in the tooling - line's `sh//` layout: symlink only those three libraries (by +- `just rs nvidia`, a one-line recipe over `sh/rs/nvidia.sh`: symlink only those three libraries (by soname) from `/usr/lib/x86_64-linux-gnu` into a private directory, put that on `LD_LIBRARY_PATH`, and run that selection. Fail when a library is missing instead of skipping. `just rs vulkan-cuda` (`sh/rs/vulkan-cuda.sh`) puts the @@ -52,7 +51,6 @@ Public API: none. Wire: none. ## Required -- [Tooling](/quest/m1/tooling/README.md) - the `sh/` script layout and recipe-only workflows this follows - A self-hosted runner is registered for moq-dev/moq on the maintainer's host, with the NVIDIA driver ## Related diff --git a/quest/m1/merge-queue.md b/quest/m1/merge-queue.md index a90b27b0d40..308d0f59bf3 100644 --- a/quest/m1/merge-queue.md +++ b/quest/m1/merge-queue.md @@ -29,11 +29,4 @@ and there is no merge queue, so nothing re-runs them on the combined tree. act, after the workflow change lands on `main`. Hand it over with the settings to use rather than changing it. -Decided in the 2026-09-30 audit: no longer waits on the tooling line; the -queue needs only `just ci $JOB $BASE`, which `main` already has. - Public API: none. Wire: none. - -## Related - -- [Tooling](/quest/m1/tooling/README.md) - later changes to the `just ci` entry point the queue runs diff --git a/quest/m1/performance-comparisons.md b/quest/m1/performance-comparisons.md index 9512e1b2cbb..e6e5a01f8a6 100644 --- a/quest/m1/performance-comparisons.md +++ b/quest/m1/performance-comparisons.md @@ -39,10 +39,6 @@ rather than creating another benchmark runner. samples. Validate an unchanged-revision A/A run and a deliberately degraded fixture; keep normal machine timing informational rather than a flaky CI gate. -## Required - -- [Tooling](/quest/m1/tooling/README.md) - the recipe and script layout `just bench` runs under - ## Related - [Windowed latency](/quest/m1/3126-moq-bench-every-readme-example-fails-to-parse-and.md) - owns histogram/window semantics diff --git a/quest/m1/serve-hls-renditions.md b/quest/m1/serve-hls-renditions.md index 3e86c953bc0..36c0094f433 100644 --- a/quest/m1/serve-hls-renditions.md +++ b/quest/m1/serve-hls-renditions.md @@ -10,7 +10,6 @@ options aren't per-stream in ffmpeg, so the last filter wins. Use per-stream filters (`-filter:v:0`, `-filter:v:1`), scaled to 720p and 144p to match `hls`. Scaling the 720p source up to 1080p couldn't encode in -real time on a dev machine. The recipe body moves to `sh/demo/serve-hls.sh` -when the [tooling line](/quest/m1/tooling/README.md) lands; fix it wherever it -lives. Check it by fetching `master.m3u8` and comparing the two renditions' +real time on a dev machine. The recipe body lives in `sh/demo/serve-hls.sh`. +Check it by fetching `master.m3u8` and comparing the two renditions' `RESOLUTION` attributes. diff --git a/quest/m1/size-report.md b/quest/m1/size-report.md index d034a049f46..526a5cf4f14 100644 --- a/quest/m1/size-report.md +++ b/quest/m1/size-report.md @@ -39,8 +39,8 @@ Decided in planning: visible without a local rebuild. `cargo bloat` needs symbols, so build that pass with `CARGO_PROFILE_RELEASE_STRIP=none` and report stripped sizes separately. -- Following the tooling questline, the work lives in a `sh/` script behind a - `just` recipe, and `nightly.yml` calls the recipe. +- The work lives in a `sh/` script behind a `just` recipe, and `nightly.yml` + calls the recipe. Considered and declined (do not re-ask): diff --git a/quest/m1/tooling/README.md b/quest/m1/tooling/README.md deleted file mode 100644 index 5f3055bfc07..00000000000 --- a/quest/m1/tooling/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# Tooling: thin justfiles and CI that calls them - -## Goal - -A month of merges left the command surface bloated: 873 lines of root -`justfile`, seven self-tests of the tooling itself on every pull request, -three metadata guards, recipes nothing calls, and release workflows that are -the same file with a binary name swapped. The result is a `just` tree that is -a menu, not a language: every recipe is one line, every script lives under -`sh/`, the diff is resolved once by one impact map, and every workflow step -runs a recipe rather than a script path. - -## Plan - -`just` stays as the entry point because the vocabulary (`just check`, `just -fix`) is in every doc, skill, and workflow. Its cost was -self-inflicted: logic inside recipes. The quests below are ordered and each -requires the one before it, so they land as one line of pull requests. - -## Required - -- [Thin justfiles](/quest/m1/tooling/justfiles.md) - recipe bodies move to `sh/`, one impact map scopes check/fix/test, self-tests and guards are deleted -- [Workflows call just](/quest/m1/tooling/workflows-call-just.md) - no workflow `run:` step names a `.sh`; every script a workflow needs has a recipe -- [Binary release workflow](/quest/m1/tooling/release-binary.md) - moq-cli and moq-relay share one reusable workflow behind two thin callers -- [FFI release workflow](/quest/m1/tooling/release-ffi.md) - the five `release-*-ffi.yml` share the moq-ffi target matrix and artifact staging diff --git a/quest/m1/tooling/justfiles.md b/quest/m1/tooling/justfiles.md deleted file mode 100644 index 429dedb4325..00000000000 --- a/quest/m1/tooling/justfiles.md +++ /dev/null @@ -1,102 +0,0 @@ -# [L] Thin justfiles with one impact map - -## Goal - -Every justfile is a menu: each recipe is a single line that runs a tool or a -script under `sh/`, `just --list` shows each recipe once, and no recipe body -is bash. The scoped `check`, `fix`, and `test` resolve the branch diff once, -in one impact map, instead of a scope regex per language justfile plus a -mirror of them in the strict-tools preflight. Nothing that tests the tooling -itself runs on a pull request. A recipe that no workflow, doc, skill, or other -recipe invokes is gone, except the hand-run demo and infra ops recipes, which -stay as they are. - -## Plan - -Layout: - -- New root `sh/`. Root helpers sit at the top (`sh/dispatch.sh`, - `sh/markdown.sh`, `sh/shell.sh`, `sh/clean.sh`); per-area tooling moves - under `sh//`: `rs/scripts` to `sh/rs`, `.github/scripts` to `sh/gh`, - `go/scripts` to `sh/go`, `kt/scripts` to `sh/kt`, `swift/scripts` to - `sh/swift`, `dart/scripts` to `sh/dart`, and the OBS recipe bodies to - `sh/obs`. Workflow references to moved paths are updated mechanically here; - the next quest replaces them with recipes. -- Package build scripts that nix, CMake, gradle, and the dart build hook - point at stay put: `rs/*/build.sh`, `rs/moq-gst/{package,scrub,smoke}.sh`, - `cpp/obs/build.sh`, `infra/*/publish.sh`. The harness under `test/` is - harness code, not tooling; it stays too. -- `shfmt -f .` already enumerates `sh/`, so the shell lint covers everything - the justfiles stop containing. - -Dispatch: - -- `just check [BASE]`, `just fix [BASE]`, and `just ci check|test [BASE]` are - one line each: `sh/dispatch.sh check|fix|ci-check|ci-test "$BASE"`. The script resolves BASE - (arg, `GITHUB_BASE_REF`, upstream, `origin/main`), lists changed files into - a temp file, and applies one impact map: which language modules run, which - tools `MOQ_STRICT` demands, and whether the root orchestration changed and - everything runs. The map lives in one place; the `scope` variables in the - js, py, kt, swift, go, and dart justfiles and the regex table in `_tools` - are deleted with it. -- Per-language `check`, `fix`, and `test` lose their `$FILES` parameter and - skip logic. Only rs still receives the list: `just rs check-changed - ` (and `fix-changed`, `test-changed`) hand the path to - `sh/rs/select.sh`, which does the crate selection today spread over - `_select`, `_names`, and `_wants-wasm`. -- Passing a path instead of the list kills the argv budget: - `changed_max`, `_changed-cap`, `_changed-test`, `_echo`, and the E2BIG - commentary go. -- `check --all`, `fix --all`, and `ci check|test --all` keep their names; cache.yml, - nightly.yml, and the docs call them. - -Delete: - -- Self-tests: `_changed-test`, `_markdown-test`, `_select-test`, - `_doc-names-test`, `_publish-test`, `sh/rs/package-nfpm.test.sh`, - `sh/gh/package-binary.test.sh`. -- Guards: `_doc-names` and `doc-names.jq`, and the publish lower-bound - check. This is a deliberate trade: the guards were incidents' worth of - bash plus their self-tests on every pull request. Where each surfaces - instead: a doc-directory collision shows up as an intermittent `failed to - remove directory` in the `cargo doc` step of whichever pull request selects - both crates, not deterministically (resolve with `doc = false` as before); - a stale internal lower bound fails release-plz's publish. `_fuzz-lock` is - already gone: #3543 folded the fuzz harness into the workspace so the root - lockfile and `--locked` cover it. `alert.sh check-coverage` stays: it is a - lint of alert.yml, not of a recipe. -- The `worktree` recipe and its 170 lines, plus the Worktrees section of - `test/README.md`; keep `_base` folded into `sh/dispatch.sh`. -- `rs bump` and `rs semver`. `rs release` stays for release-rs.yml. -- The `mod` lines in `demo/justfile`: `just pub`, `just relay`, `just boy`, - `just sub`, `just web` are the only spelling, and `--list` stops showing - each twice. `just demo` remains the default recipe and `just dev` its - documented alias. - -Rename: - -- Root `wasm` becomes `js wasm`: it emits `js/wasm/dist`, so it is a JS - package build. `rs wasm` stays the compile gate and `test wasm` the browser - run. Update wasm.yml, root `build`, `test/wasm/run.sh` (which runs `just - wasm` to build the package under test), and the four doc references. - -Keep, moved into scripts unchanged in behavior: the remark mirror-and-diff in -`sh/markdown.sh` (remark-cli has no check mode and the lint presets are -wanted), `_shell`, `_flake` as its one-liner, `clean`, the rs `package` and -`fuzz` bodies, and the OBS `compile`, `_includes`, `_unit`, `test`, `check`, -and `preset` bodies. - -Arguments reach tools intact: `just rs test`, `check-test`, and -`capture-test` interpolate `{{ args }}` today, so a quoted nextest filterset -becomes a shell syntax error (#4342). Recipes that forward arguments use -`[positional-arguments]` and `"$@"`. No self-test for it, per the rule above. - -Docs: `doc/setup/dev.md`, `CONTRIBUTING.md`, `test/README.md`, and the -`AGENTS.md` mentions of `just wasm` follow the survivors. Verify with `just -check`, `just ci test`, and `just check --all`, and confirm every recipe name -check.yml, cache.yml, nightly.yml, interop.yml, wasm.yml, obs.yml, swift.yml, -and release-*.yml invoke still resolves. - -## Closes - -- [#4342](https://github.com/moq-dev/moq/issues/4342) - close this issue when the quest finishes diff --git a/quest/m1/tooling/release-binary.md b/quest/m1/tooling/release-binary.md deleted file mode 100644 index 95eecf91f16..00000000000 --- a/quest/m1/tooling/release-binary.md +++ /dev/null @@ -1,31 +0,0 @@ -# [M] One reusable workflow for the binary releases - -## Goal - -`moq-cli.yml` and `moq-relay.yml` are two copies of the same workflow (226 -and 225 lines) with the binary name swapped. They become one reusable -`release-binary.yml` taking `crate` and `bin` inputs, and two callers of a -dozen lines each that keep their tag trigger -and workflow name, so `alert.yml`, `release-brew.yml`, and -`release-winget.yml` keep matching on the names they match today. - -## Plan - -- `release-binary.yml` on `workflow_call` with inputs `crate` (the cargo - package) and `bin` (the executable name; `moq-cli` ships `moq`). It holds the Linux native-runner matrix, - the macOS tarball job, the Windows job, the `.deb` and `.rpm` packaging, the - release creation, and the repo-publish trigger, all as `just` recipes per - the preceding quest. -- Each caller keeps `name:` and `on.push.tags` exactly as they are and does - nothing but `uses: ./.github/workflows/release-binary.yml` with the two - inputs and the secrets it forwards. `workflow_run` consumers trigger off - the caller's name, so nothing downstream changes. -- The one text difference between the three today (a comment and a step name - about the glibc floor) belongs in the reusable file. -- Verify with `just gh check` and by diffing the rendered job list of each - caller against its predecessor with `gh workflow view`. The next tagged - release is the end-to-end check; say so in the PR. - -## Required - -- [Workflows call just](/quest/m1/tooling/workflows-call-just.md) - the reusable workflow is written in the recipe style from the start diff --git a/quest/m1/tooling/release-ffi.md b/quest/m1/tooling/release-ffi.md deleted file mode 100644 index 1627f981c8a..00000000000 --- a/quest/m1/tooling/release-ffi.md +++ /dev/null @@ -1,35 +0,0 @@ -# [M] One reusable workflow for the moq-ffi releases - -## Goal - -`release-dart-ffi.yml`, `release-go-ffi.yml`, `release-kt-ffi.yml`, -`release-swift-ffi.yml`, and `release-py-ffi.yml` share half to two thirds of -their lines: the moq-ffi cross-target build matrix and the artifact staging. -That shared half becomes one reusable `release-ffi.yml`; each language keeps -only its packaging and publish steps. - -## Plan - -- Measure the shared lines first (`comm` over the sorted files shows 74 to - 176 common lines per pair) and confirm the matrix targets agree. Where a - language needs a different target set (iOS simulator for swift, Android - ABIs for kt and dart), make the target list an input rather than forcing - one matrix. -- `release-ffi.yml` on `workflow_call`: builds `rs/moq-ffi` for the requested - targets, uploads one artifact per target, and outputs the version parsed - from the tag. Callers download the artifacts and run their `just - package` and publish recipes. -- `release-dart-ffi.yml` and `release-go-ffi.yml` also run on `pull_request`, - where `GITHUB_REF` is not a `moq-ffi-v*` tag and `parse-version` fails; they - read the version from `rs/moq-ffi/Cargo.toml` instead. The reusable - workflow keeps that fallback (an input or a ref check), or those PR runs die - before building. -- Callers keep their `name:` and triggers, as the binary quest did, so - `alert.yml` and the `workflow_run` chains (`release-go.yml`, - `release-py.yml`, `release-swift-lib.yml`) are untouched. -- Verify with `just gh check`; the next tagged `moq-ffi-v*` release is the - end-to-end check. - -## Required - -- [Binary release workflow](/quest/m1/tooling/release-binary.md) - proves the reusable-plus-callers pattern before it is applied to five files diff --git a/quest/m1/tooling/workflows-call-just.md b/quest/m1/tooling/workflows-call-just.md deleted file mode 100644 index 4d6c79c4e8e..00000000000 --- a/quest/m1/tooling/workflows-call-just.md +++ /dev/null @@ -1,45 +0,0 @@ -# [M] Every workflow step runs a recipe - -## Goal - -No `run:` line in `.github/workflows` names a `.sh` file. Every script a -workflow needs has a `just` recipe, so the menu is the whole command surface -and a script can move or change its arguments without touching twenty -workflows. The same recipes work locally for a dry run. - -## Plan - -Today the workflows call scripts directly at roughly ninety sites: -`sh/gh/release.sh` (54 calls as a helper library: `parse-version`, -`prev-tag`, `create`, registry existence checks), `sh/rs/package-nfpm.sh`, -`sh/rs/package-binary.sh`, `sh/rs/package-windows.sh`, -`sh/gh/trigger-repo-publish.sh`, `sh/gh/render-formula.sh`, `sh/gh/alert.sh`, -the swift `package`, `package-ffi`, `publish`, `publish-ffi`, `verify`, -`verify-ffi`, and `check` scripts, the go `package-ffi`, `package-wrapper`, -`publish-ffi`, `publish-wrapper` scripts, `sh/dart/package.sh`, -`sh/kt/package.sh`, and `infra/*/publish.sh`. - -- Add pass-through recipes where none exist, named by role under the area - module: `just gh release ...`, `just gh alert ...`, - `just gh formula ...`, `just gh trigger-repo-publish ...`, - `just rs package-binary ...`, `just rs package-nfpm ...`, - `just rs package-windows ...`, `just swift publish|verify|package-ffi|...`, - `just go publish-ffi|publish-wrapper`, `just dart package`, - `just infra apt publish` and `just infra rpm publish` (the recipes exist). - Existing wrappers (`kt package`, `swift package`, `go package-ffi`, - `go package-wrapper`, `py package`) are used as they are. -- Rewrite every `run:` step to the recipe. Where a workflow runs outside the - nix dev shell (Windows and macOS runners, AlmaLinux containers), `just` is - already installed or installable the way nightly.yml does it; keep that - pattern rather than falling back to a path. -- Record the rule in the CI section of `CONTRIBUTING.md` in one line, and - have `just gh check` enforce it: fail on any workflow `run:` line matching - `\.sh\b`. -- Verify with `actionlint` via `just gh check`, and with a manual - `workflow_dispatch` of apt-repo.yml, rpm-repo.yml, and release-winget.yml - where the inputs allow a dry run. The tag-triggered release workflows are - verified by the next release; say so in the PR. - -## Required - -- [Thin justfiles](/quest/m1/tooling/justfiles.md) - establishes `sh/` and the module recipes the workflows will call diff --git a/quest/m2/moq-installer.md b/quest/m2/moq-installer.md index c5c88937c05..5a95a000dcb 100644 --- a/quest/m2/moq-installer.md +++ b/quest/m2/moq-installer.md @@ -17,6 +17,8 @@ service setup, Windows support, or new release targets. Deferred to m2 in the 2026-09-30 audit: no named consumer; `cargo install`, Nix, Docker, and winget already install `moq`. +- Download the archives `.github/workflows/release-binary.yml` already + publishes; the installer needs no workflow change. - Default to the latest stable `moq-cli` release, with an explicit version option. Resolve that product's tags, not the repository-wide latest release: this repository publishes multiple independently versioned crates. @@ -46,7 +48,5 @@ Nix, Docker, and winget already install `moq`. ## Related -- [Binary release workflow](/quest/m1/tooling/release-binary.md) - reuse its - artifacts without requiring workflow consolidation - [`moq relay`](/quest/m2/moq-relay-subcommand.md) - relay functionality joins the same executable independently of its installation method diff --git a/rs/justfile b/rs/justfile index 8074f2f9d4c..e5e0eea1582 100644 --- a/rs/justfile +++ b/rs/justfile @@ -11,738 +11,145 @@ set working-directory := '..' # `moq-net-fuzz` is a workspace member only so it shares the root lockfile; libFuzzer # needs a nightly toolchain and sanitizer flags, so `just rs fuzz` is the one recipe -# that may compile it. Every `--workspace` below therefore carries this, and a new -# one that forgets it pays a vendored C++ libFuzzer build for nothing. The root -# justfile's `check --all` and `fix --all` spell it out, since a module cannot read this. +# that may compile it. Every `--workspace` below therefore carries this, as does +# sh/rs/select.sh, since it cannot read this. no_fuzz := "--exclude moq-net-fuzz" default: just check -# Default features for the selected workspace packages, here and in CI. The full -# workspace permutations (`--all-features`, `--no-default-features`) each cost a -# separate compile that shares almost nothing with this one, so `features` below -# covers them nightly. `check-changed` makes one scoped exception for moq-tokio, -# whose feature-gated transport surface must compile in isolation to avoid -# workspace feature unification hiding a broken configuration. -# -# No `cargo check` pass: clippy is a superset of it, and the two use different -# rustc wrappers, so running both means compiling the workspace twice. +# Default features for the selected packages. The full workspace permutations +# each cost a separate compile, so `features` covers them nightly. No `cargo +# check` pass: clippy is a superset of it, and the two use different rustc +# wrappers, so running both compiles the workspace twice. # # A bare `just rs check` is default-members, which skips libmoq, moq-ffi, -# moq-gst, and moq-wasm (they need cbindgen, a uniffi build, GStreamer, and a -# wasm32 target respectively, so they stay out of a casual local check). Every -# recipe that means "all of it" therefore passes `--workspace` explicitly, since -# `check` is the only gate now and nothing else would compile them. +# moq-gst, and moq-wasm; pass `--workspace` for all of it. # Compile, lint, format-check, doc-check, and verify dependency hygiene. +[positional-arguments] check *args: - cargo clippy --locked --all-targets {{ args }} -- -D warnings - just rs _lint {{ args }} + cargo clippy --locked --all-targets "$@" -- -D warnings + just rs _lint "$@" -# `check` with the clippy pass replaced by `test`, whose clippy-driver build -# reports the same findings. `build.warnings` turns them into errors without -# entering cargo's fingerprint, so a later plain `test` reuses the artifacts. -# `--no-tests=pass` because a selection can hold nothing testable (see -# `test-changed`). +# `check` with clippy replaced by the `test` build, whose clippy-driver reports +# the same findings. `build.warnings` turns them into errors without entering +# cargo's fingerprint, so a later plain `test` reuses the artifacts. A +# selection can hold nothing testable (moq-wasm has no host tests). # Compile, lint, and test in one build, plus everything else `check` verifies. +[positional-arguments] check-test *args: - #!/usr/bin/env bash - set -euo pipefail - if ! command -v clippy-driver >/dev/null 2>&1; then - echo "rs: check-test needs clippy-driver to lint" >&2 - exit 1 - fi - CARGO_BUILD_WARNINGS=deny just rs test --no-tests=pass {{ args }} - just rs _lint {{ args }} + CARGO_BUILD_WARNINGS=deny RUSTC_WORKSPACE_WRAPPER={{ require("clippy-driver") }} cargo nextest run --locked --all-targets --no-tests=pass "$@" + just rs _lint "$@" # Everything `check` verifies besides clippy. +[positional-arguments] _lint *args: - just rs _select-test - just rs _publish-test - just rs _doc-names-test - # A new MoqConnectionStats field has to reach every binding's doc page. - python3 rs/scripts/stats-docs.py - rs/scripts/package-nfpm.test.sh + python3 sh/rs/stats-docs.py cargo fmt --all --check - just rs _doc-names - RUSTDOCFLAGS="-D warnings" cargo doc --locked --no-deps {{ args }} + RUSTDOCFLAGS="-D warnings" cargo doc --locked --no-deps "$@" cargo shear cargo sort --workspace --check --no-format -# Two targets whose names differ only by `-` vs `_` render to the same -# `target/doc/`, and a `cargo doc` that selects both races to clean it: the -# collision warning escalates to `error: failed to remove directory` depending on -# which rustdoc process gets there first. That reads as a flake, and because the doc -# pass above is diff-scoped it surfaces on whichever unrelated PR happens to select -# both crates. Resolve a pair by setting `doc = false` on whichever target has no -# published API to render (usually the binary). -# -# Metadata only, so this costs no compilation and can sit in the PR gate. Takes an -# optional metadata file so `_doc-names-test` can feed it synthetic workspaces. -_doc-names metadata="": - #!/usr/bin/env bash - set -euo pipefail - - if [[ -n "{{ metadata }}" ]]; then - collisions=$(jq -r -f rs/scripts/doc-names.jq < "{{ metadata }}") - else - collisions=$(cargo metadata --locked --no-deps --format-version 1 | jq -r -f rs/scripts/doc-names.jq) - fi - - if [[ -n "$collisions" ]]; then - echo "rs: these targets render to the same doc directory:" >&2 - echo "$collisions" >&2 - echo "set doc = false on whichever has no published API." >&2 - exit 1 - fi - -# Both directions of `_doc-names`, since the interesting half is what it must NOT -# report: cargo documents only the library when a binary shares its own package's -# name, so flagging that would reject the conventional src/lib.rs + src/main.rs layout. -_doc-names-test: - #!/usr/bin/env bash - set -euo pipefail - - scratch=$(mktemp -d) - trap 'rm -rf "$scratch"' EXIT - - # Same package, same name: cargo suppresses the bin, so this must pass. - cat > "$scratch/ok.json" <<'JSON' - {"packages":[{"name":"solo","targets":[ - {"name":"solo","kind":["lib"],"doc":true}, - {"name":"solo","kind":["bin"],"doc":true}]}]} - JSON - just rs _doc-names "$scratch/ok.json" - - # Same package, differing only by `-` vs `_`: cargo folds before suppressing, so - # this must pass too. Comparing the names as spelled would report it. - cat > "$scratch/folded.json" <<'JSON' - {"packages":[{"name":"folded","targets":[ - {"name":"foo_bar","kind":["lib"],"doc":true}, - {"name":"foo-bar","kind":["bin"],"doc":true}]}]} - JSON - just rs _doc-names "$scratch/folded.json" - - # Different packages: a real collision, must be reported. - cat > "$scratch/bad.json" <<'JSON' - {"packages":[ - {"name":"a-lib","targets":[{"name":"shared_name","kind":["lib"],"doc":true}]}, - {"name":"b-cli","targets":[{"name":"shared-name","kind":["bin"],"doc":true}]}]} - JSON - if just rs _doc-names "$scratch/bad.json" 2>/dev/null; then - echo "rs: _doc-names missed a cross-package collision" >&2 - exit 1 - fi - - # `doc = false` is how a pair gets resolved, so it must stop being reported. - cat > "$scratch/fixed.json" <<'JSON' - {"packages":[ - {"name":"a-lib","targets":[{"name":"shared_name","kind":["lib"],"doc":true}]}, - {"name":"b-cli","targets":[{"name":"shared-name","kind":["bin"],"doc":false}]}]} - JSON - just rs _doc-names "$scratch/fixed.json" - - echo "rs: _doc-names ok" - # Auto-fix clippy/format/shear/sort. +[positional-arguments] fix *args: - cargo clippy --locked --fix --allow-staged --allow-dirty --all-targets {{ args }} + cargo clippy --locked --fix --allow-staged --allow-dirty --all-targets "$@" cargo fmt --all cargo shear --fix cargo sort --workspace --no-format -# Prints `ALL` when the diff hits something every crate depends on, and nothing -# when no crate is affected. -# -# FILES is an exported parameter, not `{{ FILES }}`: just interpolates the -# latter into the recipe source, where a filename like `$(...)` would run as a -# command. Git-derived paths are untrusted input, so they stay data. - -# Print `--package` flags for the crates a diff touches, plus their dependents. -[private] -_select $FILES: - #!/usr/bin/env bash - set -euo pipefail - - # Workspace-wide inputs affect every crate, so there is nothing to scope to. - # - # `rs/justfile` and the nextest config are in here because they define how - # every crate is checked and tested. They also match `^rs/` below while - # seeding no crate (the seed pattern needs `rs//...`), so without this - # a PR editing only the recipes would compile and test nothing at all, and a - # broken cargo flag would pass CI on a format check alone. - if [[ -z "$FILES" ]] || grep -qE '^(Cargo\.(toml|lock)|rust-toolchain\.toml|rs/justfile|\.config/nextest\.toml)$' <<< "$FILES"; then - echo ALL - exit 0 - fi - - grep -q '^rs/' <<< "$FILES" || exit 0 - - # `--no-deps` keeps this to workspace members and off the network. - metadata=$(cargo metadata --format-version 1 --no-deps) - - # A seed is the first path segment under `rs/`, so only a crate whose manifest - # sits directly at `rs//Cargo.toml` can ever be one. Drop the rest here: - # `moq-net-fuzz` lives at `rs/moq-net/fuzz`, so its seed is already `moq-net`, - # and leaving it in the graph would select it as a dependent of the crate it - # fuzzes and compile libFuzzer on every moq-net diff. - # - # `manifest_path` is a native path, so normalize the separator before splitting - # on it. Windows would otherwise match no segment, drop every package, and - # select nothing at all, where the assertion below fails safe to ALL. - metadata=$(jq '.packages |= map((.manifest_path |= gsub("\\\\"; "/")) | select(.manifest_path | split("/")[-3] == "rs"))' <<< "$metadata") - - # Every remaining crate directory is named after the crate it holds, which is - # what makes a changed path a seed below. Verify it rather than trust it: under- - # selecting silently checks nothing, so fall back to checking everything. - if jq -e '.packages[] | select((.manifest_path | split("/")[-2]) != .name)' <<< "$metadata" > /dev/null; then - echo "rs: a crate directory no longer matches its crate name; selecting everything." >&2 - echo ALL - exit 0 - fi - - seeds=$(sed -n 's|^rs/\([^/]*\)/.*|\1|p' <<< "$FILES" | sort -u) - - # Every workspace member, not just the default ones. `--no-deps` already - # limits this to the workspace. The non-default members (libmoq, moq-ffi, - # moq-gst, moq-wasm) have to participate as both seeds and dependents: they - # used to drop out here because `check` matched a bare `cargo check`, but - # `check` is the only gate now, and the `cargo clippy --workspace` in the - # deleted `just rs ci` is what used to cover them. Without them, a PR - # touching only rs/libmoq selects nothing and compiles nothing. - edges=$(jq -r ' - .packages[] - | .name as $name - | .dependencies[] - | "\($name) \(.name)" - ' <<< "$metadata") - - # A crate has to be rebuilt when anything it depends on changed, so walk the - # edges backwards until the selection stops growing. The seeds go through the - # environment because BSD awk (macOS) rejects a newline in a `-v` value. - selected=$(SEEDS="$seeds" awk ' - BEGIN { split(ENVIRON["SEEDS"], s, "\n"); for (i in s) want[s[i]] = 1 } - { pkg[NR] = $1; dep[NR] = $2 } - END { - do { - grew = 0 - for (i = 1; i <= NR; i++) - if (want[dep[i]] && !want[pkg[i]]) { want[pkg[i]] = 1; grew = 1 } - } while (grew) - # Every wanted crate, not just those that appear as an edge source: a - # crate with no dependencies of its own emits no edge, so keying the - # output on `pkg[i]` would drop it and select nothing for a direct - # change to it. Test the VALUE, not the key -- awk creates a key on - # every `want[dep[i]]` read above, so iterating keys alone would emit - # every crate the workspace mentions. The lookup below drops names that - # are not workspace crates, which is what keeps a seed like the - # non-crate `rs/scripts` from reaching cargo. - for (name in want) if (want[name]) print name - } - ' <<< "$edges" | sort -u) - - [[ -n "$selected" ]] || exit 0 - - # Emit cargo's own package ids, not bare names. A workspace crate we also - # publish collides with its crates.io copy as soon as any dependency pulls - # that copy in (the web-transport-* crates depend on a published `kio`), and - # `--package kio` is then ambiguous: cargo refuses during package selection, - # before compiling anything, so the whole gate fails. Ids from `cargo - # metadata` carry the source, so they are unambiguous by construction. - jq -r --arg selected "$selected" ' - ($selected | split("\n")) as $want - | .packages[] - | select(.name as $name | $want | index($name) != null) - | "--package \(.id)" - ' <<< "$metadata" | sort -u | tr '\n' ' ' - -# Bare crate names for the `--package ` flags `_select` emits, for log lines -# and for the wasm gate's alternation below. Matching names rather than the flag -# spelling keeps those call sites working whatever spec form `_select` uses; the -# previous alternation matched `--package ` literally and silently stopped -# firing the moment the spec form changed. Ids are `path+file://#` -# and `_select` only emits crates whose directory it has verified matches -# their crate name, so the last path segment is the name. - -# True when a selection includes a crate the wasm32 pass covers. One predicate -# rather than the same alternation in each gate, so the test below exercises what -# the gates actually run instead of a copy of it. -[private] -_wants-wasm $PACKAGES: - #!/usr/bin/env bash - set -euo pipefail - grep -qwE '(moq-wasm|moq-mux|moq-ffi)' <<< "$(just rs _names "$PACKAGES")" - -# True when the selection includes moq-tokio, whose zero-feature build is hidden -# by workspace feature unification whenever any dependent enables a transport. -[private] -_wants-tokio-features $PACKAGES: - #!/usr/bin/env bash - set -euo pipefail - grep -qw 'moq-tokio' <<< "$(just rs _names "$PACKAGES")" - -# True when the selection includes a crate with a `capture` feature. Selection -# pulls in dependents, so a diff to moq-mux or moq-net lands here too, which is -# how a rename in either reaches the device code that calls it. -[private] -_wants-capture $PACKAGES: - #!/usr/bin/env bash - set -euo pipefail - grep -qwE '(moq-video|moq-audio)' <<< "$(just rs _names "$PACKAGES")" - -# True when the selection includes moq-cli, whose `play` media tasks are off the -# default feature set. Selection pulls in dependents, so a diff to anything the -# player is built from (moq-audio, moq-video, moq-mux) lands here too. -[private] -_wants-play $PACKAGES: - #!/usr/bin/env bash - set -euo pipefail - grep -qw 'moq-cli' <<< "$(just rs _names "$PACKAGES")" - -# True when the selection includes moq-relay, whose io_uring listener is off the -# default feature set. Selection pulls in dependents, so a diff to any crate the -# relay is built from (moq-uring, moq-sock, moq-tokio) lands here too. -[private] -_wants-uring $PACKAGES: - #!/usr/bin/env bash - set -euo pipefail - grep -qw 'moq-relay' <<< "$(just rs _names "$PACKAGES")" - -# True when the media feature contracts have to run. The contract script is not -# a crate, so `_select` drops it; a diff that only edits the script must still -# reach the gate, or a broken command merges on shell lint alone. -[private] -_wants-media-features $PACKAGES $FILES: - #!/usr/bin/env bash - set -euo pipefail - grep -qwE '(moq-video|moq-audio|moq-transcode)' <<< "$(just rs _names "$PACKAGES")" \ - || grep -qx 'rs/scripts/media-features.sh' <<< "$FILES" +# Like `check`, but only the crates in a changed-file list plus their dependents. +check-changed $LIST: + sh/rs/select.sh check "$LIST" -# Print the crate names behind a list of `--package` flags. -[private] -_names $PACKAGES: - #!/usr/bin/env bash - set -euo pipefail - tr ' ' '\n' <<< "$PACKAGES" | sed -n 's|.*/\([^/#]*\)#.*|\1|p' | sort -u | tr '\n' ' ' +# Like `check-test`, but only the crates in a changed-file list plus their dependents. +check-test-changed $LIST: + sh/rs/select.sh check-test "$LIST" -# Guards the two things about selection that fail SILENTLY rather than loudly: -# a `--package` spec cargo cannot resolve takes the gate down before it compiles -# anything, and a wasm gate that stops matching skips the only pass that ever -# looks at moq-wasm's code (its crate root is `#![cfg(target_arch = "wasm32")]`, -# so the host pass sees an empty crate and reports success). Both have happened. +# Like `fix`, but only the crates in a changed-file list plus their dependents. +fix-changed $LIST: + sh/rs/select.sh fix "$LIST" -# Check that selection emits resolvable specs and still drives the wasm gate. -[private] -_select-test: - #!/usr/bin/env bash - set -euo pipefail - - fail() { echo "rs: _select-test: $1" >&2; exit 1; } - - # `kio` is published and pulled from crates.io by the web-transport-* crates, - # so the workspace copy and the registry copy share a name: a bare name is - # ambiguous and cargo refuses. Every emitted spec must name its source, and - # cargo must accept it. - packages=$(just rs _select "rs/kio/src/waiter.rs") - for spec in $(sed 's/--package //g' <<< "$packages"); do - [[ "$spec" == *"file://"* ]] || fail "expected a source-qualified id, got: $spec" - cargo pkgid --offline "$spec" > /dev/null 2>&1 || fail "cargo cannot resolve: $spec" - done - - # The wasm gate keys on names, so it survives whatever spec form the ids use. - just rs _wants-wasm "$packages" \ - || fail "a kio diff must still drive the wasm gate: $(just rs _names "$packages")" - - # ...and it must still be able to say no, or it is not a gate. - relay=$(just rs _select "rs/moq-relay/src/web.rs") - if just rs _wants-wasm "$relay"; then - fail "a moq-relay diff must not drive it: $(just rs _names "$relay")" - fi - - # The break the capture gate was added for: a moq-mux API change that missed - # its callers behind `capture`. A moq-mux diff has to reach it. - mux=$(just rs _select "rs/moq-mux/src/clock.rs") - just rs _wants-capture "$mux" \ - || fail "a moq-mux diff must drive the capture gate: $(just rs _names "$mux")" - if just rs _wants-capture "$relay"; then - fail "a moq-relay diff must not drive the capture gate: $(just rs _names "$relay")" - fi - - # The break the uring gate was added for: a change that breaks moq-relay's - # io_uring listener, which the default pass above never compiles. A moq-relay - # diff has to reach it, and a diff that cannot affect the relay must not. - just rs _wants-uring "$relay" \ - || fail "a moq-relay diff must drive the uring gate: $(just rs _names "$relay")" - hls=$(just rs _select "rs/moq-hls/src/lib.rs") - if just rs _wants-uring "$hls"; then - fail "a moq-hls diff must not drive the uring gate: $(just rs _names "$hls")" - fi - - tokio=$(just rs _select "rs/moq-tokio/src/lib.rs") - just rs _wants-tokio-features "$tokio" \ - || fail "a moq-tokio diff must drive its feature matrix: $(just rs _names "$tokio")" - if just rs _wants-tokio-features "$relay"; then - fail "a moq-relay-only selection must not drive the moq-tokio feature matrix" - fi - - # A non-crate directory under rs/ seeds a name that is not a package. It must - # select nothing rather than reach cargo as a bogus spec. - [[ -z "$(just rs _select "rs/scripts/package-binary.sh")" ]] \ - || fail "a non-crate seed must select nothing" - - # The contract script is that same kind of seed, so selection stays empty. - # The gate still has to run it: this is the diff that can break the commands. - [[ -z "$(just rs _select "rs/scripts/media-features.sh")" ]] \ - || fail "the media contract script must not select a crate" - just rs _wants-media-features "" "rs/scripts/media-features.sh" \ - || fail "a media-features.sh diff must drive the contract" - if just rs _wants-media-features "" "rs/scripts/package-binary.sh"; then - fail "an unrelated script must not drive the media contract" - fi - video=$(just rs _select "rs/moq-video/src/lib.rs") - just rs _wants-media-features "$video" "" \ - || fail "a moq-video diff must drive the media contract: $(just rs _names "$video")" - just rs _wants-media-features "--package file:///tmp/rs/moq-transcode#0" "" \ - || fail "moq-transcode alone must drive the media contract" - if just rs _wants-media-features "$relay" ""; then - fail "a moq-relay diff must not drive the media contract: $(just rs _names "$relay")" - fi - - # Several seeds select all of them, not just the first. - pair=$(just rs _names "$(just rs _select $'rs/moq-auth/src/lib.rs\nrs/moq-hls/src/lib.rs')") - grep -qw moq-auth <<< "$pair" && grep -qw moq-hls <<< "$pair" \ - || fail "a two-crate diff must select both: $pair" - - # A crate nested inside another crate's directory is covered by its parent's - # seed. Selecting it directly would compile libFuzzer on every moq-net diff, - # and its directory name is not its crate name, so it would also mis-report. - fuzz=$(just rs _names "$(just rs _select "rs/moq-net/fuzz/fuzz_targets/lite.rs")") - grep -qw moq-net <<< "$fuzz" || fail "a fuzz diff must select moq-net: $fuzz" - ! grep -qw fuzz <<< "$fuzz" || fail "a fuzz diff must not select the harness: $fuzz" - - echo "rs: selection ok" - -# Published crates need the current workspace version as the lower bound for -# internal dependencies. The workspace only tests that version set, and a looser -# bound lets package verification combine incompatible older releases. -# -# Internal dev-dependencies must be path-only. `cargo publish` keeps a versioned -# dev-dependency and requires it on crates.io, but release-plz orders publishes -# by normal dependencies only, so a bumped dev-dependency is often not there yet. -[private] -_publish-test: - #!/usr/bin/env bash - set -euo pipefail - - metadata=$(cargo metadata --locked --format-version 1 --no-deps) - stale=$(jq -r ' - .packages as $packages - | $packages[] as $package - | select($package.publish != []) - | $package.dependencies[] - | select(.source == null and .path != null and .kind != "dev") - | . as $dependency - | ($packages[] | select(.name == $dependency.name)) as $current - | select($dependency.req != ("^" + $current.version)) - | "\($package.name): \($dependency.name) requires \($dependency.req), current is ^\($current.version)" - ' <<< "$metadata") - - if [[ -n "$stale" ]]; then - echo "rs: published workspace dependency lower bounds are stale:" >&2 - echo "$stale" >&2 - exit 1 - fi - - versioned=$(jq -r ' - .packages[] - | select(.publish != []) - | .name as $package - | .dependencies[] - | select(.source == null and .path != null and .kind == "dev" and .req != "*") - | "\($package): \(.name) \(.req)" - ' <<< "$metadata") - - if [[ -n "$versioned" ]]; then - echo "rs: published crates have versioned workspace dev-dependencies:" >&2 - echo "$versioned" >&2 - echo "use { path = \"../\" } instead of { workspace = true }." >&2 - exit 1 - fi - - echo "rs: published workspace dependencies current" - -# Takes a newline-separated list of changed files; skips when no crate is -# affected. The `just rs ...` calls below go through the root justfile's -# `mod rs` because these recipes run from the repo root, where a bare `check` -# would resolve to the root recipe of that name. - -# Like `check`, but only the crates a diff touches plus their dependents. -# TEST=true runs `check-test` in place of `check`. -check-changed $FILES $TEST="false": - #!/usr/bin/env bash - set -euo pipefail - recipe=check - [[ "$TEST" == true ]] && recipe=check-test - packages=$(just rs _select "$FILES") - case "$packages" in - "") echo "rs: no crates affected; skipping." ;; - ALL) just rs "$recipe" --workspace {{ no_fuzz }} ;; - *) echo "rs: checking $(just rs _names "$packages")"; just rs "$recipe" $packages ;; - esac - - if [[ "$packages" == "ALL" ]] || just rs _wants-tokio-features "$packages"; then - just rs tokio-features - fi - - # moq-wasm's crate root is entirely `#![cfg(target_arch = "wasm32")]`, so - # however it got selected the host-target pass above compiled it to nothing - # and saw no errors in it. This wasm32 pass is what actually checks it. - # - # The alternation must list every package `wasm` compiles, not just moq-wasm: - # nothing in the workspace depends on moq-ffi, so an moq-ffi-only diff selects - # only itself and would never reach the gate that exists to cover it. moq-mux - # is selected by its dependents, none of which are moq-wasm. - if [[ "$packages" == "ALL" ]] || just rs _wants-wasm "$packages"; then - just rs wasm - fi - - # moq-video's and moq-audio's device code is behind `capture`, which is off - # by default, so the pass above never compiles it. Only nightly's - # `--all-features` did, and a break there lands on main. With TEST=true the - # lint rides the test build, as in `check-test`. - if [[ "$packages" == "ALL" ]] || just rs _wants-capture "$packages"; then - if [[ "$TEST" == true ]]; then - CARGO_BUILD_WARNINGS=deny just rs capture-test - else - just rs capture - fi - fi - - # moq-cli's media tasks are behind `play`, off by default, so the test pass - # above never runs them. Only `check` tests, so the lint-only CI job skips it. - if [[ "$TEST" == true ]] && { [[ "$packages" == "ALL" ]] || just rs _wants-play "$packages"; }; then - just rs play - fi - - # moq-relay's io_uring listener is behind `io-uring`, off by default, so the - # pass above never compiles it. `check --all` reaches it through `bench - # check`, but only for a diff under `bench/`; a relay change would otherwise - # land on the nightly. - if [[ "$packages" == "ALL" ]] || just rs _wants-uring "$packages"; then - just rs uring-check - fi - - # Each media feature shape compiles on its own (see rs/scripts/media-features.sh), - # about two minutes, so only a diff that reaches the media crates, or the - # contract script itself, pays for it. - if [[ "$packages" == "ALL" ]] || just rs _wants-media-features "$packages" "$FILES"; then - just rs media-features - fi +# Like `test`, but only the crates in a changed-file list plus their dependents. +test-changed $LIST: + sh/rs/select.sh test "$LIST" # Compile moq-tokio by itself at the feature extremes and with each crypto provider. -# Its default-feature build is already part of the ordinary clippy pass above. tokio-features: - #!/usr/bin/env bash - set -euo pipefail - - cargo clippy --locked -p moq-tokio --no-default-features -- -D warnings - cargo clippy --locked -p moq-tokio --all-features -- -D warnings - cargo clippy --locked -p moq-tokio --no-default-features --features noq,aws-lc-rs -- -D warnings - cargo clippy --locked -p moq-tokio --no-default-features --features noq,ring -- -D warnings - - for feature in aws-lc-rs ring tcp uds websocket; do - cargo clippy --locked -p moq-tokio --no-default-features --features "$feature" -- -D warnings - done - - want='a rustls QUIC backend requires a crypto provider: enable either the `aws-lc-rs` or `ring` feature' - if output=$(cargo check --locked -p moq-tokio --no-default-features --features noq 2>&1); then - echo "rs: moq-tokio with only noq should reject its missing crypto provider" >&2 - exit 1 - fi - if ! grep -qF "$want" <<< "$output"; then - echo "rs: moq-tokio with only noq should fail on: $want" >&2 - echo "$output" | grep -E '^error' >&2 || true - exit 1 - fi - -# Same as `fix`, but scoped the same way as `check-changed`. -fix-changed $FILES: - #!/usr/bin/env bash - set -euo pipefail - packages=$(just rs _select "$FILES") - case "$packages" in - "") echo "rs: no crates affected; skipping." ;; - ALL) just rs fix --workspace {{ no_fuzz }} ;; - *) echo "rs: fixing $(just rs _names "$packages")"; just rs fix $packages ;; - esac + sh/rs/tokio-features.sh - # Mirrors `check-changed`'s gate, alternation included: without this a wasm32 - # lint is never auto-fixed, and `check`'s wasm32 clippy pass fails on it later. - if [[ "$packages" == "ALL" ]] || just rs _wants-wasm "$packages"; then - just rs wasm-fix - fi - -# Runs the `#[cfg(windows)]` code past the compiler, which the Linux gate skips -# entirely: moq-video's Media Foundation capture/encode/decode and its D3D11 -# frames, moq-nvenc's Windows loader, and the Winsock paths in moq-tokio. A -# native host rather than a cross-compile, because openh264-sys2's vendored C++ -# needs an MSVC toolchain. platform.yml runs this on every pull request and -# every push to main and dev. -# -# Default features rather than `--all-features`: jemalloc doesn't build on -# MSVC, and the Linux-only features (vaapi, pipewire, io-uring) have nothing to -# compile here. +# Runs the `#[cfg(windows)]` code past the compiler, which the Linux gate +# skips; platform.yml runs it on a Windows runner, scoped like `check-changed` +# so a one-crate PR compiles one crate on these slow runners too. Default +# features, since jemalloc doesn't build on MSVC. # Compile what the branch changed since BASE on a Windows host, or everything with `--all`. windows $BASE="": - just rs _platform "$BASE" + sh/rs/platform.sh "$BASE" # Compile and test the io_uring relay path, which is off the default feature set. # Linux-only, and the tests below the 6.12 kernel floor skip themselves. -# -# `qlog` is a second axis, and the traces are what a debugging run depends on, -# so it gets a separate pass. +[positional-arguments] uring *args: - just rs uring-check {{ args }} - cargo nextest run --locked -p moq-uring -p moq-relay --features moq-relay/io-uring --all-targets {{ args }} - cargo clippy --locked -p moq-uring -p moq-relay --features moq-relay/io-uring,moq-relay/qlog --all-targets {{ args }} -- -D warnings - cargo nextest run --locked -p moq-uring --features qlog --all-targets {{ args }} + just rs uring-check "$@" + cargo nextest run --locked -p moq-uring -p moq-relay --features moq-relay/io-uring --all-targets "$@" + cargo clippy --locked -p moq-uring -p moq-relay --features moq-relay/io-uring,moq-relay/qlog --all-targets "$@" -- -D warnings + cargo nextest run --locked -p moq-uring --features qlog --all-targets "$@" -# Compile the io_uring relay path, off the default feature set. `check-changed` -# runs this whenever moq-relay is selected, so a change that breaks the ring -# listener fails its own PR rather than landing on the nightly. +# Compile the io_uring relay path, off the default feature set. +[positional-arguments] uring-check *args: - cargo clippy --locked -p moq-uring -p moq-relay --features moq-relay/io-uring --all-targets {{ args }} -- -D warnings + cargo clippy --locked -p moq-uring -p moq-relay --features moq-relay/io-uring --all-targets "$@" -- -D warnings -# Runs the Apple-gated code past the compiler: moq-video's VideoToolbox -# encode/decode and its ScreenCaptureKit / AVFoundation capture, moq-audio's -# ScreenCaptureKit system audio and TCC permission pre-check, and moq-sock's -# BSD socket-buffer sysctl. platform.yml runs this alongside `windows`. +# The Apple-gated code in moq-video, moq-audio, and moq-sock, which +# platform.yml compiles on a Mac runner alongside `windows`. # Compile what the branch changed since BASE on a macOS host, or everything with `--all`. macos $BASE="": - just rs _platform "$BASE" - -# The shared body of `windows` and `macos`, scoped like `check-changed` so a -# one-crate PR compiles one crate on these slow runners too. moq-gst is dropped -# because it links GStreamer via pkg-config, which the runners don't have. -# -# `moq-cli/play` and `moq-cli/capture` are named explicitly because they are -# off by default, and they are what turns on the device and render code in -# moq-video, moq-audio, and the cli itself. Only when moq-cli is selected, -# since cargo rejects a feature of a package outside the selection; any change -# to the crates those features reach selects moq-cli as a dependent anyway. - -# Compile what the branch changed since BASE plus its dependents, or everything with `--all`. -[private] -_platform $BASE: - #!/usr/bin/env bash - set -euo pipefail - packages=ALL - if [[ "$BASE" != --all ]]; then - files=$(just _changed "$BASE") - # `_select` reads an empty list as everything, so an empty diff stops here. - if [[ -z "$files" ]]; then - echo "rs: nothing changed; skipping." - exit 0 - fi - [[ "$files" == ALL ]] || packages=$(just rs _select "$files") - fi - - features="--features moq-cli/play,moq-cli/capture" - if [[ "$packages" == ALL ]]; then - cargo check --locked --workspace --exclude moq-gst {{ no_fuzz }} --all-targets $features - exit 0 - fi - - packages=$(sed -E 's|--package [^ ]*/moq-gst#[^ ]* ?||' <<< "$packages") - if [[ -z "${packages// }" ]]; then - echo "rs: no crates affected; skipping." - exit 0 - fi - just rs _wants-play "$packages" || features="" - echo "rs: checking $(just rs _names "$packages")" - cargo check --locked $packages --all-targets $features - -# The Linux device code: moq-video's V4L2 and X11 capture and moq-audio's cpal -# capture, all behind the off-by-default `capture` feature. `check-changed` runs -# this whenever either crate is selected. The per-crate `--features` spelling -# keeps it to those two instead of widening what their dependencies compile. -# `--all-features` would also build the bindgen codecs, which nightly covers. + sh/rs/platform.sh "$BASE" # Compile and lint the capture feature, which the default check skips. +[positional-arguments] capture *args: - cargo clippy --locked -p moq-video -p moq-audio --all-targets --features moq-video/capture,moq-audio/capture {{ args }} -- -D warnings + cargo clippy --locked -p moq-video -p moq-audio --all-targets --features moq-video/capture,moq-audio/capture "$@" -- -D warnings -# The capture publishers' tests (the clock fixtures among them) drive synthetic -# devices, so they need no hardware and run with every PR that reaches either crate. +# The capture tests drive synthetic devices, so they need no hardware. # Test the capture feature, which the default test pass skips. +[positional-arguments] capture-test *args: - just rs test -p moq-video -p moq-audio --features moq-video/capture,moq-audio/capture {{ args }} + just rs test -p moq-video -p moq-audio --features moq-video/capture,moq-audio/capture "$@" -# Same idea as `windows`/`macos`, for Android: moq-video's MediaCodec encoder and -# decoder, its `Surface::HardwareBuffer` variant, and the `frame::android` module -# are all `#[cfg(target_os = "android")]`, so a host-target check compiles none of -# them and every error in them stays invisible. -# -# Unlike `windows` and `macos` this needs no special host: the Android targets -# cross-compile from Linux in about half a minute. It needs an NDK, which -# `cargo-ndk` finds through `ANDROID_NDK_HOME` or the standard SDK layout. The -# dev shell provides neither, so android.yml runs this outside Nix on a GitHub -# runner, whose image ships an NDK, for every PR that touches moq-video or -# anything it is built from. -# -# arm64-v8a alone: it is the only ABI anything here ships, and the code is not -# ABI-specific, so the other two would compile the same source twice more. -# -# `check` rather than a `-D warnings` clippy, matching `windows` and `macos`: -# the capture module's plumbing is dead on a target with no capture backend, so -# a denying lint would fail on code this recipe is not here to police. +# moq-video's MediaCodec code is `#[cfg(target_os = "android")]`. Needs an NDK, +# which the dev shell lacks, so android.yml runs it outside Nix. `check` rather +# than a denying clippy: the capture plumbing is dead on a target without a +# capture backend. # Compile the Android backends, which the host-target check skips. +[positional-arguments] android *args: - cargo ndk -t arm64-v8a --platform 26 check --locked -p moq-video --all-targets {{ args }} + cargo ndk -t arm64-v8a --platform 26 check --locked -p moq-video --all-targets "$@" -# Same idea as `windows`/`macos`, for the browser: moq-wasm's whole crate root is -# `#![cfg(target_arch = "wasm32")]`, so a host-target `cargo check --workspace` -# compiles an empty crate and every error in it stays invisible. Only a wasm32 -# build sees the code. -# -# Unlike those two this needs no special host, so `ci` runs it on every Rust PR. -# The wasm32 target and the `getrandom`/`web-sys` cfg flags come from the Nix dev -# shell and `.cargo/config.toml`. Not to be confused with the root `just wasm`, -# which builds the shippable `@moq/wasm` package (wasm-bindgen, release profile); -# this is the compile gate. - -# `moq-mux` and `moq-ffi` ride along in the same invocation on purpose: `moq-mux` -# needs `getrandom`'s `wasm_js` backend that only its siblings declare, and feature -# unification only happens within one cargo invocation. Splitting them fails on -# getrandom. `--lib` rather than `--all-targets` because moq-mux's tests use tokio's -# native timers and moq-ffi's drive a native relay; moq-wasm has no test targets, so -# it loses no coverage. +# moq-wasm's crate root is `#![cfg(target_arch = "wasm32")]`, so only a wasm32 +# build sees the code. Not to be confused with `just js wasm`, which builds the +# shippable `@moq/wasm` package. `moq-mux` and `moq-ffi` share the invocation +# because moq-mux needs the getrandom backend only its siblings declare, and +# features unify only within one cargo invocation. # Compile and lint the browser/WASM bindings, which the host-target check skips. +[positional-arguments] wasm *args: - cargo clippy --locked -p moq-wasm -p moq-mux -p moq-ffi --target wasm32-unknown-unknown --lib {{ args }} -- -D warnings - -# The `fix` counterpart to `wasm`. `cargo fmt` is scoped rather than `--all` -# because this runs alongside `fix`, which already formats everything else. + cargo clippy --locked -p moq-wasm -p moq-mux -p moq-ffi --target wasm32-unknown-unknown --lib "$@" -- -D warnings # Auto-fix the browser/WASM bindings. +[positional-arguments] wasm-fix *args: - cargo clippy --locked --fix --allow-staged --allow-dirty -p moq-wasm -p moq-mux -p moq-ffi --target wasm32-unknown-unknown --lib {{ args }} + cargo clippy --locked --fix --allow-staged --allow-dirty -p moq-wasm -p moq-mux -p moq-ffi --target wasm32-unknown-unknown --lib "$@" cargo fmt -p moq-wasm -p moq-mux -p moq-ffi -# Dependency advisories plus the license/ban policy. Time-based rather than -# diff-based: an advisory lands without this repo changing, so a per-PR run both -# fires on PRs that cannot affect it and stays silent on the days nobody pushes. -# Runs nightly instead (.github/workflows/nightly.yml), which also keeps a fresh -# advisory from blocking an unrelated PR mid-review. - -# Audit dependencies against deny.toml. +# Audit dependencies against deny.toml. Nightly: advisories land without a diff. audit: cargo deny check --show-stats @@ -750,109 +157,16 @@ audit: relay-minimal: cargo nextest run --locked -p moq-relay --no-default-features --lib -E 'test(workers_require_a_quic_backend)' -# libmoq's C fixtures (`rs/libmoq/c-tests/*.c`) link `libmoq.a` the way an -# embedder does: an external `cc` against the generated `moq.h`, plus the native -# libraries from `rs/libmoq/native-libs` that cargo can't inject into a link it -# doesn't drive. Each fixture pins part of the C ABI at compile time and -# exercises it at runtime, so it has to run, not just compile. -# -# Outside nextest on purpose. The staticlib link alone takes ~2 minutes, past the -# hang budget in `.config/nextest.toml` once the rest of the workspace builds -# beside it, and `rs/AGENTS.md` says to make a slow test fast, not to raise the -# ceiling. obs.yml runs this on every PR that touches rs/libmoq, right after it -# has built the same debug libmoq.a for the plugin, and nightly.yml covers the -# paths that filter misses. -# -# Unix only: linking a Rust staticlib from MSVC spells the flags and the -# archive (`moq.lib`) differently, and this recipe doesn't model that. +# Outside nextest because the staticlib link alone outlasts its hang budget. # Compile and run libmoq's C fixtures, and the C doc samples, against libmoq.a. Must run on Unix. c-tests: - #!/usr/bin/env bash - set -euo pipefail - cc="${CC:-cc}" - if ! command -v "$cc" >/dev/null; then - echo "no C compiler at '$cc'" >&2 - exit 1 - fi - - cargo build --locked -p libmoq - - # Ask cargo where it put the staticlib and the header rather than assuming - # target/debug: CARGO_TARGET_DIR and a configured build target - # (`target//debug`) both move them, and guessing wrong would link a - # stale copy or nothing. Replays the build above from cache, so it costs a - # process, not a compile. - log=$(cargo build --locked -p libmoq --message-format=json) - lib=$(jq -r 'select(.reason == "compiler-artifact") | .filenames[] | select(endswith("/libmoq.a"))' <<<"$log" | tail -1) - if [ -z "$lib" ]; then - echo "cargo reported no libmoq.a for libmoq" >&2 - exit 1 - fi - profile=$(dirname "$lib") - # rs/libmoq/build.rs writes the header into its OUT_DIR. - out_dir=$(jq -r 'select(.reason == "build-script-executed") | select(.package_id | test("libmoq")) | .out_dir' <<<"$log" | tail -1) - include="$out_dir/include" - if [ -z "$out_dir" ] || [ ! -f "$include/moq.h" ]; then - echo "$include/moq.h missing after 'cargo build --locked -p libmoq'" >&2 - exit 1 - fi + sh/rs/c-tests.sh - # Same list nix/overlay.nix (moq.pc), CMakeLists.txt, and test/interop/interop.sh read: - # `framework:Foo` is a linker framework flag, anything else a plain library. - case "$(uname -s)" in - Darwin) native_libs=rs/libmoq/native-libs/apple.txt ;; - *) native_libs=rs/libmoq/native-libs/linux.txt ;; - esac - libs=() - while read -r entry; do - case "$entry" in - '' | '#'*) continue ;; - framework:*) libs+=(-framework "${entry#framework:}") ;; - *) libs+=("-l$entry") ;; - esac - done <"$native_libs" - - out=$(mktemp -d) - trap 'rm -rf "$out"' EXIT - - # The C docs compile against this header too: each sample beside the inputs - # doc-samples.h declares, and every name the prose cites. A `moq_decode_*` - # wildcard ends in `_` and is skipped. - bash doc/lib/samples.sh c doc/lib/c/index.md >"$out/doc-samples.c" - "$cc" -fsyntax-only -Werror=implicit-function-declaration -include rs/libmoq/c-tests/doc-samples.h -I"$include" "$out/doc-samples.c" - for name in $(grep -oE '\b(moq|MOQ)_[A-Za-z0-9_]*' doc/lib/c/index.md | grep -v '_$' | sort -u); do - if ! grep -qw "$name" "$include/moq.h"; then - echo "doc/lib/c/index.md cites $name, which moq.h does not declare" >&2 - exit 1 - fi - done - - for source in rs/libmoq/c-tests/*.c; do - bin="$out/$(basename "$source" .c)" - "$cc" "$source" -I"$include" -L"$profile" -lmoq "${libs[@]}" -o "$bin" - echo "running $source" - "$bin" - done - -# The feature permutations `check` leaves out. Each is a full workspace compile -# at a feature set that shares almost no artifacts with the default one (~6min -# for the all-features clippy alone), which is why this is nightly rather than -# part of the per-PR gate. -# -# `--all-features` is the only thing that compiles moq-cli's play/capture, the -# moq-video and moq-audio device features, the Linux bindgen codecs (vaapi, -# v4l2), PipeWire, and jemalloc. `--no-default-features` is -# the only thing that compiles the `#[cfg(not(feature = ...))]` arms. -# -# Cargo unifies features across a workspace selection. Check each package alone -# to catch missing dependencies in minimal builds. The nightly sweep adds each -# feature to aws-lc-rs; tokio-features checks provider-free transports, standalone -# providers, and the intentional refusal of rustls QUIC without a provider. -# -# Both carry `--all-targets`. A `#[cfg(test)]` module leans on whatever the -# default features happened to import, so a test that only compiles by accident -# is invisible to a lib-only check. +# The feature permutations `check` leaves out, nightly. `--all-features` is the +# only thing that compiles moq-cli's play/capture, the device features, the +# Linux bindgen codecs, PipeWire, and jemalloc; `--no-default-features` the only +# thing that compiles the `#[cfg(not(feature = ...))]` arms. # Compile the workspace at the feature extremes. features: @@ -871,258 +185,120 @@ features: # Compile the media crates at supported feature boundaries and prove expensive # native/render dependencies are absent when their features are excluded. media-features: - rs/scripts/media-features.sh + sh/rs/media-features.sh -# nextest, not `cargo test`, so a wedged test is killed instead of pinning a core -# until someone notices (`.config/nextest.toml` sets the timeout). The trade is -# doctests, which nextest does not execute; `just rs doctest` covers those. -# -# Takes cargo arguments, so `just rs test -p moq-net` works. `test-changed` is -# the diff-scoped variant that `just ci test` dispatches to. -# -# clippy-driver as the compiler wrapper is rustc plus the lint passes, so this -# one compilation both builds the test binaries and reports clippy findings. -# `cargo clippy` can't be reused here: it asks cargo for metadata only, and a -# metadata build and a codegen build have different fingerprints, so running -# both compiles the dependency tree twice. Linting here is free, which is what -# lets `check-test` (and so the root `just check`) compile Rust once. -# -# RUSTC_WORKSPACE_WRAPPER, not RUSTC_WRAPPER, for two reasons. Cargo folds it -# into the fingerprint, so a crate already built by a plain `cargo test` is -# rebuilt through clippy rather than silently reported as fresh with no -# findings. And it applies to workspace crates only, so dependencies keep the -# artifacts they share with plain cargo instead of duplicating the whole tree. -# It is also what `cargo clippy` sets internally. -# -# Findings stay warnings rather than errors. `check-test` is the gate (it sets -# `build.warnings=deny`), and a hard failure here would block running the tests -# over an unused import while you are mid-edit. -# -# No RUSTFLAGS: it is part of cargo's fingerprint too, so setting it here would -# split the artifact cache against every other cargo invocation, including CI's -# warm cache. Skips the wrapper entirely when clippy-driver is absent. +# nextest kills a wedged test (`.config/nextest.toml` sets the timeout), but +# skips doctests; `just rs doctest` covers those. clippy-driver as the workspace +# wrapper reports lint findings from the same compile, as warnings: `check-test` +# is the gate. It is part of cargo's fingerprint, and RUSTFLAGS would split the +# artifact cache, which is why neither is set any other way. # Run the test suite, reporting clippy findings from the same compile. +[positional-arguments] test *args: - RUSTC_WORKSPACE_WRAPPER="$(command -v clippy-driver || true)" cargo nextest run --locked --all-targets {{ args }} + RUSTC_WORKSPACE_WRAPPER="$(command -v clippy-driver || true)" cargo nextest run --locked --all-targets "$@" -# Exercise the Vulkan producer -> CUDA image contract, the GPU color conversion -# and resize, and NVENC encoding of the result on Linux/NVIDIA hardware. The -# driver directory is added explicitly because the Nix shell's dynamic loader -# path does not include Ubuntu's host driver directory. +# Exercise Vulkan -> CUDA -> NVENC on Linux/NVIDIA hardware. vulkan-cuda: - #!/usr/bin/env bash - set -euo pipefail - driver=$(/usr/sbin/ldconfig -p | awk '/libcuda\.so\.1/{print $NF; exit}') - if [[ -z "$driver" ]]; then - echo "libcuda.so.1 is not installed" >&2 - exit 1 - fi - driver_dir=$(dirname "$driver") - export LD_LIBRARY_PATH="$driver_dir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" - cargo nextest run --locked -p moq-video --run-ignored only -E 'test(/^frame::(vulkan|cuda)::tests::vulkan_cuda_/)' - -# Same selection as `check-changed`: compiling a crate's test binaries is the -# expensive half of a test run, so scoping matters more here than anywhere else. -# -# `--no-tests=pass` only on the scoped branch. A selection can legitimately hold -# nothing testable (moq-wasm has no host-target tests, since its crate root is -# `#![cfg(target_arch = "wasm32")]`), and nextest exits 4 on that by default. -# The unscoped branch keeps the default, where finding no tests really is wrong. - -# Like `test`, but only the crates a diff touches plus their dependents. -test-changed $FILES: - #!/usr/bin/env bash - set -euo pipefail - packages=$(just rs _select "$FILES") - case "$packages" in - "") echo "rs: no crates affected; skipping tests." ;; - ALL) just rs test --workspace {{ no_fuzz }} ;; - *) echo "rs: testing $(just rs _names "$packages")"; just rs test --no-tests=pass $packages ;; - esac - - # Mirrors `check-changed`: the capture tests are off the default feature set. - if [[ "$packages" == "ALL" ]] || just rs _wants-capture "$packages"; then - just rs capture-test - fi - - if [[ "$packages" == "ALL" ]] || just rs _wants-play "$packages"; then - just rs play - fi + sh/rs/vulkan-cuda.sh # The media tasks run against a recorder rather than a device (see -# `rs/moq-cli/src/play/fake.rs`), so this needs no speaker or display, only the -# device crates' build dependencies, which the dev shell carries. +# `rs/moq-cli/src/play/fake.rs`), so this needs no speaker or display. # Test moq-cli's `play` feature, which default features leave out. +[positional-arguments] play *args: - just rs test -p moq-cli --features play {{ args }} + just rs test -p moq-cli --features play "$@" # Compile and run the `/// ```` examples, which nextest skips. +[positional-arguments] doctest *args: - cargo test --locked --doc {{ args }} + cargo test --locked --doc "$@" + +# `--cfg loom` swaps kio's primitives for loom's, so it rebuilds the world and +# stays out of `check`. `--release` because a model check runs the body once +# per interleaving (411s -> 51s); the assertions are plain `assert!`. kio's +# models search every interleaving; moq-net's cap preemptions (see +# `tests/loom.rs`, `LOOM_MAX_PREEMPTIONS`). kio's own unit tests are +# `cfg(not(loom))`. # Permutation-test the concurrent handoffs with loom. -# -# `--cfg loom` swaps kio's Mutex/atomics for loom's instrumented ones, so it -# rebuilds the world and can't share artifacts with a normal `cargo test`, so -# it stays separate from `check`/`ci`. -# -# `--release` because a model check runs the body once per interleaving, so the -# optimizer pays for itself many times over: 411s -> 51s across the two suites. -# Our assertions are plain `assert!`, not `debug_assert!`, so nothing is -# compiled out (verified by re-running the mutation check in release). -# -# kio's models search every interleaving. moq-net's compose far more operations -# per path, so they cap preemptions (see `tests/loom.rs`) to stop the search -# growing exponentially with each lock the model layer adds. Set -# `LOOM_MAX_PREEMPTIONS` to search deeper. -# -# kio's own unit tests are `cfg(not(loom))`: they'd construct loom primitives -# outside `loom::model`, which panics. +[positional-arguments] loom *args: - RUSTFLAGS="--cfg loom" cargo test --locked --release -p kio --lib loom:: {{ args }} - RUSTFLAGS="--cfg loom" cargo test --locked --release -p moq-net --test loom {{ args }} - -# Coverage-guided fuzzing of the moq-net wire codecs (libFuzzer, via cargo-fuzz). -# -# The one recipe that steps off the pinned toolchain: libFuzzer needs `-Zsanitizer`, -# which is nightly-only, so this stays out of `check` and `test` the same way `loom` -# does. What CI gets instead is the replay: the target bodies live in moq-net's hidden -# `fuzz` module, and its own tests run the generated corpus plus everything committed -# under `fuzz/regressions/` on stable. A crash found here becomes a regression test -# nobody has to install cargo-fuzz to run. -# -# Seeds are regenerated first so the corpus follows the dispatch rather than a stale -# run, and libFuzzer writes what it discovers to the FIRST corpus directory, which is -# why the generated seeds are passed second and stay read-only. -# -# TARGET is lite, announce, ietf, varint, path, or pattern. Arguments pass through, so -# `just rs fuzz lite -- -max_total_time=300` bounds a run. See rs/moq-net/fuzz/README.md. -fuzz target *args: - #!/usr/bin/env bash - set -euo pipefail - - if ! command -v cargo-fuzz > /dev/null 2>&1; then - echo "rs: cargo-fuzz is missing: cargo install --locked cargo-fuzz" >&2 - exit 1 - fi - - if ! rustup run nightly rustc --version > /dev/null 2>&1; then - echo "rs: the nightly toolchain is missing: rustup toolchain install nightly" >&2 - exit 1 - fi - - cargo run --locked -q -p moq-net --features fuzz --example fuzz-seeds -- rs/moq-net/fuzz/seeds - mkdir -p rs/moq-net/fuzz/corpus/{{ target }} + RUSTFLAGS="--cfg loom" cargo test --locked --release -p kio --lib loom:: "$@" + RUSTFLAGS="--cfg loom" cargo test --locked --release -p moq-net --test loom "$@" - # Nightly by PATH rather than by `cargo +nightly`: the dev shell puts a - # Nix-provided cargo ahead of the rustup shim, so the `+` form is not - # understood, and cargo-fuzz shells out to a bare `cargo` and `rustc` anyway. - # Both have to be the nightly ones or the sanitizer flags are rejected. - export PATH="$(rustup run nightly rustc --print sysroot)/bin:$PATH" +# Needs nightly and cargo-fuzz; CI replays the corpus on stable through +# moq-net's own tests instead. See rs/moq-net/fuzz/README.md. - cargo fuzz run --fuzz-dir rs/moq-net/fuzz {{ target }} \ - rs/moq-net/fuzz/corpus/{{ target }} rs/moq-net/fuzz/seeds/{{ target }} {{ args }} +# Fuzz the moq-net wire codecs: `just rs fuzz lite -- -max_total_time=300`. +[positional-arguments] +fuzz target *args: + sh/rs/fuzz.sh "$@" +# Build the default workspace members. build: cargo build --locked -# Run a moq-bench preset against a relay, e.g. `just rs bench chat https://relay.example.com`. -# Extra args pass through, so `--connections 500 --output stats.jsonl` work as-is. -bench preset url *args: - cargo run --release -p moq-bench -- --file 'rs/moq-bench/config/{{ preset }}.toml' --connect '{{ url }}' {{ args }} - -# Measure the Linux Tokio/epoll UDP syscall path. Extra args pass to Criterion, -# e.g. `just rs bench-udp-tokio --quick`. -bench-udp-tokio *args: - cargo bench -p moq-uring --bench udp_tokio -- {{ args }} - -# Measure the Linux io_uring UDP completion path with multishot recvmsg. -bench-udp-uring *args: - cargo bench -p moq-uring --bench udp_uring -- {{ args }} - # Run the comparable epoll and io_uring UDP matrices. +[positional-arguments] bench-udp *args: - cargo bench -p moq-uring --bench udp_tokio -- {{ args }} - cargo bench -p moq-uring --bench udp_uring -- {{ args }} + cargo bench -p moq-uring --bench udp_tokio -- "$@" + cargo bench -p moq-uring --bench udp_uring -- "$@" # Measure a noq echo through the io_uring worker, ablating receive # batching, GRO, and GSO one at a time. Linux 6.12+ (skips loudly otherwise). +[positional-arguments] bench-echo *args: - cargo bench -p moq-uring --bench echo_noq -- {{ args }} + cargo bench -p moq-uring --bench echo_noq -- "$@" # Measure a full moq-lite session (publisher to subscriber) through the # io_uring worker, same ablations and per-iteration unit as bench-echo. # Linux 6.12+ (skips loudly otherwise). +[positional-arguments] bench-session *args: - cargo bench -p moq-uring --bench session_lite -- {{ args }} - -# Sample a process's CPU/memory/context switches on this host (run it where the -# relay runs; it only reads /proc). E.g. `just rs bench-host --name moq-relay`. -bench-host *args: - cargo run --release -p moq-bench --bin moq-bench-host -- {{ args }} - -# Remove the Rust target directory. -clean: - cargo clean - -# Check semver compatibility against crates.io (default-members only). -semver: - cargo semver-checks check-release - -# Update versions and changelogs via release-plz. -bump: - release-plz update + cargo bench -p moq-uring --bench session_lite -- "$@" # Create release PRs and publish crates via release-plz. release: release-plz release-pr --git-token "$GITHUB_TOKEN" release-plz release --git-token "$GITHUB_TOKEN" -update: - cargo update - cargo upgrade --incompatible - -# Build a .deb or .rpm for one of the Rust binaries locally. nfpm comes -# from the flake's dev shell (`nix develop`). For .rpm produced this way, -# the linkage matches the host's glibc; CI uses an AlmaLinux 9 container -# to produce broadly compatible artifacts instead. -# -# Examples: -# just rs package moq-relay deb - -# just rs package moq-cli rpm +# Build a .deb or .rpm locally: `just rs package moq-relay deb`. package crate packager: - #!/usr/bin/env bash - set -euo pipefail - case "{{ crate }}" in - moq-relay) bin=moq-relay ;; - moq-cli) bin=moq ;; - *) echo "Unknown crate: {{ crate }} (use moq-relay or moq-cli)" >&2; exit 1 ;; - esac - case "{{ packager }}" in - deb) - if command -v dpkg >/dev/null 2>&1; then - arch=$(dpkg --print-architecture) - else - case "$(uname -m)" in - x86_64) arch=amd64 ;; - aarch64|arm64) arch=arm64 ;; - *) echo "Cannot infer deb arch from host $(uname -m)" >&2; exit 1 ;; - esac - fi - ;; - rpm) arch=$(uname -m) ;; - *) echo "Unknown packager: {{ packager }} (use deb or rpm)" >&2; exit 1 ;; - esac - version=$(grep -m1 '^version' rs/{{ crate }}/Cargo.toml | sed 's/.*"\(.*\)".*/\1/') - cargo build --locked --release -p {{ crate }} - mkdir -p dist - VERSION="$version" ARCH="$arch" BINARY_PATH="target/release/$bin" \ - rs/scripts/package-nfpm.sh packaging/{{ crate }}/nfpm.yaml {{ packager }} dist/ - if [[ "{{ packager }}" == deb && -f "packaging/{{ crate }}/transition.yaml" ]]; then - VERSION="$version" ARCH="$arch" \ - rs/scripts/package-nfpm.sh packaging/{{ crate }}/transition.yaml deb dist/ - fi - ls -1 dist/ + sh/rs/package.sh {{ crate }} {{ packager }} + +# Build and package a workspace binary as a release tarball. +[positional-arguments] +package-binary *args: + sh/rs/package-binary.sh "$@" + +# Build and package a workspace binary as a Windows .zip. +[positional-arguments] +package-windows *args: + sh/rs/package-windows.sh "$@" + +# Render an nfpm config from the environment and build a .deb or .rpm: CONFIG PACKAGER OUTPUT. +[positional-arguments] +package-nfpm *args: + sh/rs/package-nfpm.sh "$@" + +# Build and package the moq-ffi native libraries, or only its bindings. +[positional-arguments] +package-ffi *args: + rs/moq-ffi/build.sh "$@" + +# Build and package libmoq. +[positional-arguments] +package-libmoq *args: + rs/libmoq/build.sh "$@" + +# Build and package the moq-gst GStreamer plugin. +[positional-arguments] +package-gst *args: + rs/moq-gst/build.sh "$@" + +# Load a packaged moq-gst plugin into the host's GStreamer and find its elements. +[positional-arguments] +gst-smoke *args: + rs/moq-gst/smoke.sh "$@" diff --git a/rs/moq-gst/package.sh b/rs/moq-gst/package.sh index b48f392eb20..85ff0731b67 100755 --- a/rs/moq-gst/package.sh +++ b/rs/moq-gst/package.sh @@ -145,7 +145,7 @@ mkdir -p "$OUTPUT_DIR" echo ">> Running nfpm ($PACKAGER)..." export VERSION ARCH="$PKG_ARCH" PKG_NAME PLUGIN_PATH="$BUILT_SO" PLUGIN_DIR -"$WORKSPACE_DIR/rs/scripts/package-nfpm.sh" \ +"$WORKSPACE_DIR/sh/rs/package-nfpm.sh" \ "$WORKSPACE_DIR/packaging/moq-gst/nfpm.yaml" "$PACKAGER" "$OUTPUT_DIR/" echo ">> Done. Artifacts in: $OUTPUT_DIR" diff --git a/rs/moq-gst/scrub.sh b/rs/moq-gst/scrub.sh index 5d4699deee1..09ec56ad34a 100755 --- a/rs/moq-gst/scrub.sh +++ b/rs/moq-gst/scrub.sh @@ -40,7 +40,7 @@ scrub_macos() { # Framework path covers the official .pkg installer, and /usr/lib lets # dyld resolve system libs (libiconv, libc++) via the dyld_shared_cache at # @rpath substitution time. - "$SCRIPT_DIR/../scripts/scrub-macho.sh" "$dylib" \ + "$SCRIPT_DIR/../../sh/rs/scrub-macho.sh" "$dylib" \ /opt/homebrew/lib \ /Library/Frameworks/GStreamer.framework/Libraries \ /usr/lib diff --git a/rs/moq-wasm/README.md b/rs/moq-wasm/README.md index 7a0609c710b..34a90b2ccc5 100644 --- a/rs/moq-wasm/README.md +++ b/rs/moq-wasm/README.md @@ -7,7 +7,7 @@ wire implementation in `@moq/net` (~10k LOC) with the canonical Rust one, so the protocol lives in exactly one place. This crate is the Rust half; the generated JS package is -[`@moq/wasm`](../../js/wasm) (`just wasm` builds it). It is **not** the same as +[`@moq/wasm`](../../js/wasm) (`just js wasm` builds it). It is **not** the same as `moq-ffi`: that crate uses UniFFI, which targets the C ABI (Kotlin/Swift/Python/ Go). Browsers need `wasm-bindgen`, so this is a separate sibling crate. (For *React Native* JS, `uniffi-bindgen-react-native` can reuse `moq-ffi` directly; @@ -66,7 +66,7 @@ dependency is commented out in `Cargo.toml` until then. ## Building -`just wasm` (from the repo root) does everything: builds for wasm and runs +`just js wasm` (from the repo root) does everything: builds for wasm and runs `wasm-bindgen` (web target) into `js/wasm/dist`. The wasm target, the cfg flags (`getrandom` wasm backend + web-sys unstable WebTransport APIs), and the `wasm-bindgen-cli` tool come from `.cargo/config.toml` and the Nix dev shell. diff --git a/rs/scripts/doc-names.jq b/rs/scripts/doc-names.jq deleted file mode 100644 index 5dfad17c57c..00000000000 --- a/rs/scripts/doc-names.jq +++ /dev/null @@ -1,31 +0,0 @@ -# Find workspace targets that would render to the same `target/doc/`. -# -# `cargo doc` writes each documented target to a directory named after the target with -# dashes folded to underscores, so two targets that differ only there collide: both -# rustdoc processes race to clean it, and the warning escalates to a hard error -# depending on which wins. -# -# Reads `cargo metadata --no-deps` and prints one line per colliding group. -[ .packages[] - | . as $pkg - # Cargo skips a binary that would land on the same directory as a library in its own - # package, documenting only the library, so such a pair never actually collides. - # Compared after folding, matching cargo: a `foo_bar` lib beside a `foo-bar` bin is - # suppressed too (verified against cargo 1.95). Only cross-package pairs collide. - | [ $pkg.targets[] - | select([.kind[]] | any(. == "lib" or . == "rlib" or . == "dylib" - or . == "cdylib" or . == "staticlib" or . == "proc-macro")) - | (.name | gsub("-"; "_")) - ] as $libs - | $pkg.targets[] - # `doc = false` in the manifest, which is how a reported pair gets resolved. - | select(.doc) - | select([.kind[]] | any(. == "lib" or . == "rlib" or . == "dylib" - or . == "cdylib" or . == "staticlib" or . == "proc-macro" or . == "bin")) - | select((([.kind[]] | any(. == "bin")) and ((.name | gsub("-"; "_")) | IN($libs[]))) | not) - | { dir: (.name | gsub("-"; "_")), package: $pkg.name, target: .name, kind: .kind[0] } -] -| group_by(.dir) -| map(select(length > 1)) -| .[] -| " target/doc/\(.[0].dir) <- " + (map("\(.package) [\(.kind)] \(.target)") | join(" and ")) diff --git a/rs/scripts/package-nfpm.test.sh b/rs/scripts/package-nfpm.test.sh deleted file mode 100755 index 5582669426e..00000000000 --- a/rs/scripts/package-nfpm.test.sh +++ /dev/null @@ -1,68 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -if ! command -v envsubst >/dev/null 2>&1; then - exit 0 -fi - -scratch=$(mktemp -d) -trap 'rm -rf "$scratch"' EXIT -mkdir -p "$scratch/bin" "$scratch/capture" - -cat >"$scratch/bin/nfpm" <<'SH' -#!/usr/bin/env bash -set -euo pipefail - -while (($#)); do - case "$1" in - --config) - config=$2 - shift 2 - ;; - --packager) - printf '%s\n' "$2" >"$NFPM_CAPTURE/packager" - shift 2 - ;; - --target) - printf '%s\n' "$2" >"$NFPM_CAPTURE/target" - shift 2 - ;; - *) shift ;; - esac -done - -cp "$config" "$NFPM_CAPTURE/config.yaml" -SH -chmod +x "$scratch/bin/nfpm" - -cat >"$scratch/nfpm.yaml" <<'YAML' -name: test -version: ${VERSION} -arch: ${ARCH} -contents: - - src: ${BINARY_PATH} - dst: /usr/bin/test -YAML - -PATH="$scratch/bin:$PATH" \ - NFPM_CAPTURE="$scratch/capture" \ - VERSION=1.2.3 \ - ARCH=amd64 \ - BINARY_PATH=target/release/test \ - rs/scripts/package-nfpm.sh "$scratch/nfpm.yaml" deb "$scratch/dist" - -grep -qx 'version: 1.2.3' "$scratch/capture/config.yaml" -grep -qx 'arch: amd64' "$scratch/capture/config.yaml" -grep -qx ' - src: target/release/test' "$scratch/capture/config.yaml" -grep -qx 'deb' "$scratch/capture/packager" -grep -qx "$scratch/dist" "$scratch/capture/target" - -if PATH="$scratch/bin:$PATH" \ - NFPM_CAPTURE="$scratch/capture" \ - VERSION=1.2.3 \ - ARCH=amd64 \ - rs/scripts/package-nfpm.sh "$scratch/nfpm.yaml" deb "$scratch/dist" 2>"$scratch/missing.log"; then - echo "package-nfpm accepted a missing BINARY_PATH" >&2 - exit 1 -fi -grep -qx "Missing environment variable in $scratch/nfpm.yaml: BINARY_PATH" "$scratch/missing.log" diff --git a/sh/changed.sh b/sh/changed.sh new file mode 100755 index 00000000000..287b950ac30 --- /dev/null +++ b/sh/changed.sh @@ -0,0 +1,35 @@ +#!/usr/bin/env bash +# Print the paths the branch changed since BASE, one per line. +# +# Usage: sh/changed.sh [BASE] +# +# BASE: the argument, then $GITHUB_BASE_REF (a PR checkout has no upstream), +# then the upstream, then origin/main. `git push -u` points the upstream at the +# branch's own remote copy, which would diff HEAD against itself, so that case +# falls through to origin/main. +set -euo pipefail + +base=${1:-} + +cd "$(git rev-parse --show-toplevel)" + +if [[ -z "$base" && -n "${GITHUB_BASE_REF:-}" ]]; then + base="origin/$GITHUB_BASE_REF" +fi +if [[ -z "$base" ]]; then + base=$(git rev-parse --abbrev-ref '@{upstream}' 2>/dev/null || true) + if [[ -z "$base" || "$base" == */"$(git branch --show-current)" ]]; then + base=origin/main + fi +fi +merge_base=$(git merge-base "$base" HEAD) || { + echo "error: cannot resolve merge-base against $base (is full history fetched?)" >&2 + exit 1 +} +echo "changed: base $base" >&2 + +# Untracked files count too: a brand new crate or module is the whole change. +{ + git diff --name-only "$merge_base" + git ls-files --others --exclude-standard +} | sort -u diff --git a/sh/clean.sh b/sh/clean.sh new file mode 100755 index 00000000000..24f495cafe7 --- /dev/null +++ b/sh/clean.sh @@ -0,0 +1,72 @@ +#!/usr/bin/env bash +# Delete build artifacts and caches: sh/clean.sh [here|all] +# +# Only this checkout by default. Agent worktrees each carry their own +# artifacts, and another agent is usually building in one: `cargo clean` under +# a running build fails it, and there is no telling a finished worktree from a +# busy one from out here. `all` is the explicit opt-in for an idle machine. +# +# Source is never touched, dirty or untracked: this deletes build output, not +# work. Nothing here reaches a machine-wide store (Nix, cargo/bun/uv home +# caches), because those are shared with every other checkout. +set -euo pipefail + +scope=${1:-here} +case "$scope" in + here | all) ;; + *) + echo "usage: sh/clean.sh [here|all]" >&2 + exit 2 + ;; +esac + +cd "$(git rev-parse --show-toplevel)" + +# Rust. +cargo clean + +# JS: the bun workspace spans the repo, so sweep from the root. +find . -name .claude -prune -o \ + -type d \( -name node_modules -o -name dist -o -name out -o -name pkg \) \ + -prune -exec rm -rf {} + +find . -name .claude -prune -o -type f -name '*.tsbuildinfo' -exec rm -f {} + + +# Python: the venv, release dist, bytecode, and the bindings maturin drops in. +rm -rf .venv py/.venv py/dist py/moq-ffi/moq_ffi/_uniffi +find py -name .claude -prune -o -type d -name __pycache__ -prune -exec rm -rf {} + +find py -name .claude -prune -o -type f -name '*.pyc' -exec rm -f {} + + +# Kotlin: gradle output plus the bindings and native libs sh/kt generates. +find kt -type d \( -name build -o -name .gradle -o -name .kotlin \) -prune -exec rm -rf {} + +rm -rf kt/local.properties \ + kt/moq-ffi/src/jvmAndAndroidMain/kotlin/uniffi \ + kt/moq-ffi/src/jvmMain/resources \ + kt/moq-ffi/src/androidMain/jniLibs + +# Swift: SwiftPM output plus the XCFramework and bindings sh/swift lays down. +rm -rf swift/.build swift/.swiftpm swift/Package.resolved \ + swift/Sources/MoqFFI/Generated.swift swift/MoqFFI.xcframework + +# Go: the gitignored bindings, native libs, and vendoring in go/. +rm -rf go/ffi/moq/moq.go go/ffi/moq/moq.h go/ffi/moq/lib go/ffi/go.sum \ + go/ffi/vendor go/wrapper/go.sum go/wrapper/vendor + +# Dart: tool state and build output. +rm -rf dart/moq/.dart_tool dart/moq_ffi/.dart_tool dart/moq/build dart/moq_ffi/build + +# Rendered drafts and their reference cache. +rm -rf drafts/draft-*.xml drafts/draft-*.txt drafts/draft-*.html drafts/.refcache + +# Caches no one language owns: nix build result, direnv, wrangler. +rm -rf result .direnv +find . -name .claude -prune -o -type d -name .wrangler -prune -exec rm -rf {} + + +# Worktrees don't nest, so this recurses exactly one level. Tolerate stale +# worktrees on branches that predate this script. +if [[ "$scope" == all ]]; then + for wt in .claude/worktrees/*/; do + [[ -f "${wt}justfile" ]] || continue + echo "==> cleaning ${wt}" + (cd "$wt" && just clean) || echo " (skipped: just clean failed in ${wt})" + done +fi diff --git a/dart/scripts/check.sh b/sh/dart/check.sh similarity index 88% rename from dart/scripts/check.sh rename to sh/dart/check.sh index 5e658e9b187..eaa4f579bef 100755 --- a/dart/scripts/check.sh +++ b/sh/dart/check.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash set -euo pipefail -DART_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) +DART_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/../../dart" && pwd) ACTION=check if [[ "${1:-}" == --fix ]]; then @@ -9,13 +9,6 @@ if [[ "${1:-}" == --fix ]]; then shift fi -# `just check` passes the whole changed-file list, so match the scope anywhere in -# it rather than only at the start. -files="${1:-}" -if [[ -n "$files" ]] && ! grep -qE '(^|[[:space:]])(dart/|rs/moq-ffi/)' <<<"$files"; then - exit 0 -fi - for tool in cargo dart uniffi_bindgen_dart; do if ! command -v "$tool" >/dev/null 2>&1; then echo "dart check: skipping, $tool is not installed" >&2 @@ -58,7 +51,7 @@ done generated=$(mktemp -d) trap 'rm -rf "$generated"' EXIT -"$DART_DIR/scripts/generate.sh" "$generated" +"$DART_DIR/../sh/dart/generate.sh" "$generated" for file in moq.dart uniffi_runtime.dart; do if ! diff -u -B "$DART_DIR/moq_ffi/lib/src/$file" "$generated/$file"; then diff --git a/dart/scripts/generate.sh b/sh/dart/generate.sh similarity index 96% rename from dart/scripts/generate.sh rename to sh/dart/generate.sh index bbbe65ad976..7a2c9c24fc3 100755 --- a/dart/scripts/generate.sh +++ b/sh/dart/generate.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash set -euo pipefail -DART_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) +DART_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/../../dart" && pwd) WORKSPACE_DIR=$(cd "$DART_DIR/.." && pwd) OUTPUT_DIR="${1:-$DART_DIR/moq_ffi/lib/src}" diff --git a/dart/scripts/package.sh b/sh/dart/package.sh similarity index 97% rename from dart/scripts/package.sh rename to sh/dart/package.sh index 21c4d7b135c..cb984776957 100755 --- a/dart/scripts/package.sh +++ b/sh/dart/package.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash set -euo pipefail -DART_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) +DART_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/../../dart" && pwd) PACKAGE="" VERSION="" OUTPUT_DIR="dist" diff --git a/dart/scripts/publish.sh b/sh/dart/publish.sh similarity index 84% rename from dart/scripts/publish.sh rename to sh/dart/publish.sh index 6a6caaa50e8..1348e0ec64b 100755 --- a/dart/scripts/publish.sh +++ b/sh/dart/publish.sh @@ -1,14 +1,14 @@ #!/usr/bin/env bash set -euo pipefail -DART_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) +DART_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/../../dart" && pwd) PACKAGE="${1:?usage: publish.sh }" VERSION="${2:?usage: publish.sh }" OUTPUT=$(mktemp -d) trap 'rm -rf "$OUTPUT"' EXIT package_dir=$( - "$DART_DIR/scripts/package.sh" \ + "$DART_DIR/../sh/dart/package.sh" \ --package "$PACKAGE" \ --version "$VERSION" \ --output "$OUTPUT" diff --git a/sh/demo/ca.sh b/sh/demo/ca.sh new file mode 100755 index 00000000000..01cfbd0c057 --- /dev/null +++ b/sh/demo/ca.sh @@ -0,0 +1,15 @@ +#!/usr/bin/env bash +# Generate the relay cluster's self-signed CA (ca.pem, ca.key, ca.cnf) in the +# current directory, unless it already exists. +# +# Usage: sh/demo/ca.sh, from demo/relay. +set -euo pipefail +umask 077 + +[ -f ca.pem ] && [ -f ca.key ] && exit 0 +rm -f ca.pem ca.key +printf '[req]\ndistinguished_name = req_dn\n[req_dn]\n' >ca.cnf +export OPENSSL_CONF="ca.cnf" +openssl req -x509 -sha256 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes \ + -days 365 -subj "/CN=moq cluster CA" \ + -keyout ca.key -out ca.pem diff --git a/sh/demo/cert.sh b/sh/demo/cert.sh new file mode 100755 index 00000000000..916ece90f61 --- /dev/null +++ b/sh/demo/cert.sh @@ -0,0 +1,20 @@ +#!/usr/bin/env bash +# Issue NAME.crt and NAME.key for localhost from the CA that sh/demo/ca.sh +# generates in the current directory. Chrome requires a <=14 day validity for +# self-signed certs. +# +# Usage: sh/demo/cert.sh NAME, from demo/relay. +set -euo pipefail +umask 077 + +name=${1:?usage: sh/demo/cert.sh NAME} + +export OPENSSL_CONF="ca.cnf" +openssl req -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes \ + -subj "/CN=$name" \ + -keyout "$name.key" -out "$name.csr" +openssl x509 -req -sha256 -in "$name.csr" \ + -CA ca.pem -CAkey ca.key -CAcreateserial \ + -days 14 -extfile <(printf "subjectAltName=DNS:localhost\n") \ + -out "$name.crt" +rm "$name.csr" diff --git a/sh/demo/download.sh b/sh/demo/download.sh new file mode 100755 index 00000000000..3b1a4f57a51 --- /dev/null +++ b/sh/demo/download.sh @@ -0,0 +1,15 @@ +#!/usr/bin/env bash +# Download URL to FILE unless FILE already exists. The download lands in a +# temporary file first, so an interrupted one is retried instead of cached. +# +# Usage: sh/demo/download.sh URL FILE +set -euo pipefail + +usage="usage: sh/demo/download.sh URL FILE" +url=${1:?$usage} +file=${2:?$usage} + +[ -f "$file" ] && exit 0 +mkdir -p "$(dirname "$file")" +curl -fsSL -o "$file.tmp" "$url" +mv "$file.tmp" "$file" diff --git a/sh/demo/hls.sh b/sh/demo/hls.sh new file mode 100755 index 00000000000..f2c15aa1f6d --- /dev/null +++ b/sh/demo/hls.sh @@ -0,0 +1,69 @@ +#!/usr/bin/env bash +# Encode media/NAME.mp4 into a looping HLS stream (1280x720 + 256x144 + audio) +# under media/NAME/, and import it into RELAY as NAME.hang. +# +# Usage: sh/demo/hls.sh NAME RELAY, from demo/pub. +set -euo pipefail + +usage="usage: sh/demo/hls.sh NAME RELAY" +name=${1:?$usage} +relay=${2:?$usage} + +input="media/$name.mp4" +out="media/$name" + +rm -rf "$out" +mkdir -p "$out" + +echo ">>> Generating HLS stream to disk (1280x720 + 256x144)..." + +ffmpeg -hide_banner -loglevel warning -re -stream_loop -1 -i "$input" \ + -filter_complex "[0:v]split=2[v0][v1]; [v0]scale=-2:720[v720]; [v1]scale=-2:144[v144]" \ + -map "[v720]" -map "[v144]" -map 0:a:0 \ + -r 25 -preset veryfast -g 50 -keyint_min 50 -sc_threshold 0 \ + -c:v:0 libx264 -profile:v:0 high -level:v:0 4.1 -pix_fmt:v:0 yuv420p -tag:v:0 avc1 \ + -b:v:0 4M -maxrate:v:0 4.4M -bufsize:v:0 8M \ + -c:v:1 libx264 -profile:v:1 high -level:v:1 4.1 -pix_fmt:v:1 yuv420p -tag:v:1 avc1 \ + -b:v:1 300k -maxrate:v:1 330k -bufsize:v:1 600k \ + -c:a aac -b:a 128k \ + -f hls -hls_time 2 -hls_list_size 6 \ + -hls_flags independent_segments+delete_segments \ + -hls_segment_type fmp4 \ + -master_pl_name master.m3u8 \ + -var_stream_map "v:0,agroup:audio,name:720 v:1,agroup:audio,name:144 a:0,agroup:audio,name:audio" \ + -hls_segment_filename "$out/v%v/segment_%09d.m4s" \ + "$out/v%v/stream.m3u8" & +ffmpeg=$! + +cleanup() { + echo "Shutting down..." + kill "$ffmpeg" 2>/dev/null || true + sleep 0.5 + kill -9 "$ffmpeg" 2>/dev/null || true +} +trap cleanup EXIT +# A signal exits, so the EXIT trap cleans up instead of the script resuming its waits. +trap 'exit 130' INT TERM + +echo ">>> Waiting for HLS playlist generation..." +for _ in {1..30}; do + if [ -f "$out/master.m3u8" ]; then break; fi + sleep 0.5 +done + +if [ ! -f "$out/master.m3u8" ]; then + echo "Error: master.m3u8 not generated in time" >&2 + exit 1 +fi + +echo ">>> Waiting for variant playlists..." +sleep 2 +for _ in {1..20}; do + if [ -f "$out/v720/stream.m3u8" ] || [ -f "$out/v144/stream.m3u8" ] || [ -f "$out/vaudio/stream.m3u8" ]; then + break + fi + sleep 0.5 +done + +echo ">>> Importing HLS via moq-cli" +cargo run --bin moq -- --connect "$relay" --broadcast "$name.hang" import hls "$out/master.m3u8" diff --git a/sh/demo/key.sh b/sh/demo/key.sh new file mode 100755 index 00000000000..1c199dafcbd --- /dev/null +++ b/sh/demo/key.sh @@ -0,0 +1,11 @@ +#!/usr/bin/env bash +# Generate the relay's signing key (root.jwk) in the current directory, unless +# it already exists. A new key invalidates every token, so they are removed. +# +# Usage: sh/demo/key.sh, from demo/relay. +set -euo pipefail +umask 077 + +[ -f root.jwk ] && exit 0 +rm -f ./*.jwt +cargo run --bin moq -- auth generate --out root.jwk diff --git a/sh/demo/port.sh b/sh/demo/port.sh new file mode 100755 index 00000000000..814314a7038 --- /dev/null +++ b/sh/demo/port.sh @@ -0,0 +1,18 @@ +#!/usr/bin/env bash +# Print the first port at/after START that is free on both TCP and UDP. +# +# `lsof` isn't available everywhere (e.g. Git Bash on Windows); without it we +# can't probe, so print START and let the relay surface a bind error if it's +# actually taken. +# +# Usage: sh/demo/port.sh START +set -euo pipefail + +port=${1:?usage: sh/demo/port.sh START} +if command -v lsof >/dev/null 2>&1; then + while lsof -nP -iTCP:"$port" -sTCP:LISTEN -t >/dev/null 2>&1 || + lsof -nP -iUDP:"$port" -t >/dev/null 2>&1; do + port=$((port + 1)) + done +fi +echo "$port" diff --git a/sh/demo/run.sh b/sh/demo/run.sh new file mode 100755 index 00000000000..af9d85555ba --- /dev/null +++ b/sh/demo/run.sh @@ -0,0 +1,24 @@ +#!/usr/bin/env bash +# Run the web demo: a localhost relay, Big Buck Bunny, and the web player. +# +# Picks the first free port at/after 4443 (both UDP for QUIC and TCP for HTTP) +# so multiple worktrees can run `just dev` without colliding. The relay reads +# the port from MOQ_LISTEN/MOQ_WEB_HTTP_LISTEN, overriding localhost.toml. +# +# Usage: sh/demo/run.sh, from demo/ so `just` resolves the demo recipes. +set -euo pipefail + +port=$("$(dirname "$0")/port.sh" 4443) +if [ "$port" != "4443" ]; then + echo ">>> Port 4443 is busy, using $port instead" >&2 +fi + +base="http://localhost:$port" + +# Scope the bind env vars to the relay only. The unified `moq` binary also +# reads MOQ_LISTEN, so exporting it globally would make the `pub` client +# try to start a server (and fail without a TLS cert). +bun run concurrently --kill-others --names rly,bbb,web --prefix-colors auto \ + "MOQ_LISTEN='[::]:$port' MOQ_WEB_HTTP_LISTEN='[::]:$port' just relay" \ + "just wait $base/certificate.sha256 && just pub bbb $base" \ + "just wait $base/certificate.sha256 && just web serve $base" diff --git a/sh/demo/serve-hls.sh b/sh/demo/serve-hls.sh new file mode 100755 index 00000000000..bf5257bc11a --- /dev/null +++ b/sh/demo/serve-hls.sh @@ -0,0 +1,43 @@ +#!/usr/bin/env bash +# Encode media/NAME.mp4 into a looping HLS stream under media/NAME/ and serve +# it over HTTP on PORT, for testing HLS import. +# +# Usage: sh/demo/serve-hls.sh NAME PORT, from demo/pub. +set -euo pipefail + +usage="usage: sh/demo/serve-hls.sh NAME PORT" +name=${1:?$usage} +port=${2:?$usage} + +input="media/$name.mp4" +out="media/$name" + +rm -rf "$out" +mkdir -p "$out" + +echo ">>> Starting HLS stream generation..." +echo ">>> Master playlist: http://localhost:$port/master.m3u8" + +ffmpeg -loglevel warning -re -stream_loop -1 -i "$input" \ + -map 0:v:0 -map 0:v:0 -map 0:a:0 \ + -r 25 -preset veryfast -g 50 -keyint_min 50 -sc_threshold 0 \ + -c:v:0 libx264 -profile:v:0 high -level:v:0 4.1 -pix_fmt:v:0 yuv420p -tag:v:0 avc1 -bsf:v:0 dump_extra -b:v:0 4M -vf:0 "scale=1920:-2" \ + -c:v:1 libx264 -profile:v:1 high -level:v:1 4.1 -pix_fmt:v:1 yuv420p -tag:v:1 avc1 -bsf:v:1 dump_extra -b:v:1 300k -vf:1 "scale=256:-2" \ + -c:a aac -b:a 128k \ + -f hls \ + -hls_time 2 -hls_list_size 12 \ + -hls_flags independent_segments+delete_segments \ + -hls_segment_type fmp4 \ + -master_pl_name master.m3u8 \ + -var_stream_map "v:0,agroup:audio v:1,agroup:audio a:0,agroup:audio" \ + -hls_segment_filename "$out/v%v/segment_%09d.m4s" \ + "$out/v%v/stream.m3u8" & +ffmpeg=$! + +trap 'echo "Shutting down..."; exit 0' INT TERM +trap 'kill "$ffmpeg" 2>/dev/null || true' EXIT + +sleep 2 +echo ">>> HTTP server: http://localhost:$port/" +cd "$out" +python3 -m http.server "$port" diff --git a/sh/demo/sync.sh b/sh/demo/sync.sh new file mode 100755 index 00000000000..af5f2fb8860 --- /dev/null +++ b/sh/demo/sync.sh @@ -0,0 +1,16 @@ +#!/usr/bin/env bash +# Upload every file in DIR to the R2 bucket BUCKET, keyed by its file name. +# +# Usage: sh/demo/sync.sh BUCKET DIR +set -euo pipefail + +usage="usage: sh/demo/sync.sh BUCKET DIR" +bucket=${1:?$usage} +dir=${2:?$usage} + +for file in "$dir"/*; do + [ -e "$file" ] || continue + key=$(basename "$file") + echo "Uploading $key..." + bun wrangler r2 object put "$bucket/$key" --file "$file" --remote +done diff --git a/sh/demo/token.sh b/sh/demo/token.sh new file mode 100755 index 00000000000..e85ebc7bace --- /dev/null +++ b/sh/demo/token.sh @@ -0,0 +1,19 @@ +#!/usr/bin/env bash +# Sign the local development tokens (demo-web.jwt, demo-cli.jwt) with root.jwk +# in the current directory, skipping any that already exist. +# +# Usage: sh/demo/token.sh, from demo/relay. +set -euo pipefail +umask 077 + +if [ ! -f demo-web.jwt ]; then + cargo run --quiet --bin moq -- auth sign --key root.jwk \ + --root demo --subscribe '**' --publish 'me/**' \ + >demo-web.jwt +fi + +if [ ! -f demo-cli.jwt ]; then + cargo run --quiet --bin moq -- auth sign --key root.jwk \ + --root demo --publish '**' \ + >demo-cli.jwt +fi diff --git a/sh/demo/wait.sh b/sh/demo/wait.sh new file mode 100755 index 00000000000..e556127c3a3 --- /dev/null +++ b/sh/demo/wait.sh @@ -0,0 +1,14 @@ +#!/usr/bin/env bash +# Wait up to ten minutes for URL to respond, e.g. a relay's certificate +# fingerprint once it is listening. +# +# Usage: sh/demo/wait.sh URL +set -euo pipefail + +url=${1:?usage: sh/demo/wait.sh URL} +for _ in $(seq 1 600); do + curl -sf "$url" >/dev/null 2>&1 && exit 0 + sleep 1 +done +echo "timed out waiting for $url" >&2 +exit 1 diff --git a/sh/dispatch.sh b/sh/dispatch.sh new file mode 100755 index 00000000000..09ec5c13fd9 --- /dev/null +++ b/sh/dispatch.sh @@ -0,0 +1,205 @@ +#!/usr/bin/env bash +# Run `just check`, `just fix`, or `just ci check|test` over what the branch +# changed. +# +# Usage: sh/dispatch.sh check|fix|ci-check|ci-test [BASE|--all] +# +# The branch diff is resolved once and matched against the impact map below, +# the one place that says which paths put which module in scope. `check` is +# `ci-check` plus `ci-test`, which CI runs as parallel jobs with MOQ_STRICT=1, +# so there is no second definition of "checked". +set -euo pipefail + +usage="usage: sh/dispatch.sh check|fix|ci-check|ci-test [BASE|--all]" +action=${1:?$usage} +base=${2:-} +case "$action" in + check | fix | ci-check | ci-test) ;; + *) + echo "$usage" >&2 + exit 2 + ;; +esac + +# A host toolchain fails deep in a build instead: its gcc keeps the +# _FORTIFY_SOURCE the dev shell disables, which breaks jemalloc's -Werror +# configure probes. This flake's dev shell sets MOQ_DEV_SHELL. Windows has no +# Nix, so it always runs on the host. +if [[ -z "${MOQ_DEV_SHELL:-}" && -z "${MOQ_ALLOW_HOST:-}" && "$OSTYPE" != msys && "$OSTYPE" != cygwin ]]; then + echo "error: run inside the Nix dev shell ('nix develop' or direnv) so tools match CI" >&2 + echo " or set MOQ_ALLOW_HOST=1 to use the host toolchain anyway" >&2 + exit 1 +fi + +cd "$(git rev-parse --show-toplevel)" + +changed=$(mktemp) +trap 'rm -f "$changed"' EXIT + +all= +if [[ "$base" == --all ]]; then + all=1 +else + sh/changed.sh "$base" >"$changed" + + # These files hold the map and the recipes that call it, and match no + # module, so a change to them would otherwise validate none of it. + if grep -qE '^(justfile|sh/(dispatch|changed)\.sh)$' "$changed"; then + echo "$action: root orchestration changed; running everything." >&2 + all=1 + fi +fi + +# The impact map: a module is in scope when a changed path matches its +# pattern. An empty pattern is a repository-wide lint that runs on every diff. +declare -A scope=( + [js]='^(js/|doc/|drafts/|demo/(boy|web)/|test/interop/clients/js|test/wasm/|sh/js/|sh/rs/stats-docs\.py$|package\.json$|bun\.lock(b)?$|biome\.jsonc$)' + # Workers with lockfiles outside the Bun workspace. + [workers]='^(infra/apt/|infra/rpm/|demo/pub/|sh/js/workers\.sh$)' + # sh/rs/select.sh widens to the whole workspace for inputs every crate shares. + [rs]='^(rs/|sh/rs/|Cargo\.(toml|lock)$|rust-toolchain\.toml$|\.config/nextest\.toml$)' + [bench]='^bench/' + [drafts]='^(drafts/|sh/drafts/|doc/\.vitepress/drafts\.ts$)' + # Quest documents form one graph, so any change validates the whole tree, + # as does a bump of the flake-pinned validator. + [quest]='^(quest/|flake\.lock$)' + # The drill mutations patch Rust source, so a Rust change can move the code + # they target. Only nightly runs the drills; this catches a stale patch. + [drill]='^(rs/|test/drill/)' + # maturin bundles rs/moq-ffi into the moq-ffi wheel, and the other + # bindings generate from it. Each check also compiles its doc samples. + [py]='^(py/|sh/py/|pyproject\.toml$|uv\.lock$|rs/moq-ffi/|doc/lib/py/|doc/lib/samples\.sh$)' + [kt]='^(kt/|sh/kt/|rs/moq-ffi/|doc/lib/kt/|doc/lib/samples\.sh$)' + [swift]='^(swift/|sh/swift/|rs/moq-ffi/|doc/lib/swift/|doc/lib/samples\.sh$)' + [go]='^(go/|sh/go/|rs/moq-ffi/)' + [dart]='^(dart/|sh/dart/|rs/moq-ffi/)' + # The plugin calls libmoq through its generated header, and flake.nix owns + # the libobs headers it compiles against. + [obs_compile]='^(cpp/obs/|sh/obs/|rs/libmoq/|flake\.nix$)' + # `obs check` compares the OBS pinned in buildspec.json, flake.nix, and + # nixpkgs, and the last moves on a flake.lock bump alone. + [obs]='^(cpp/obs/|sh/obs/|flake\.(nix|lock)$)' + [flake]='(^rs/|^Cargo\.(toml|lock)$|^flake\.lock$|\.nix$)' + [markdown]='' + [shell]='' + [toml]='' + [nix]='' + [justfile]='' + [gh]='' +) + +# The tools each module needs. A module missing one is skipped locally, so an +# incomplete toolchain checks less; under MOQ_STRICT (CI) it is an error, up +# front, because there a skip is indistinguishable from a pass. swift needs +# none: it skips off macOS by design, and swift.yml is its real gate. +declare -A tools=( + [js]='bun python3' + [workers]='bun' + [rs]='cargo jq' + [bench]='cargo' + [drafts]='bun kramdown-rfc xml2rfc' + [quest]='quest' + [drill]='' + [py]='uv' + [kt]='cargo gradle java' + [swift]='' + [go]='cargo go uniffi-bindgen-go' + [dart]='cargo dart uniffi_bindgen_dart' + [obs_compile]='cargo jq pkg-config' + [obs]='clang-format cmake gersemi jq' + [flake]='nix' + [markdown]='bun' + [shell]='shellcheck shfmt' + [toml]='taplo' + [nix]='nixfmt' + [justfile]='' + [gh]='actionlint bun' +) + +case "$action" in + check | ci-check) modules=(js workers drafts rs bench quest drill py kt swift go dart obs_compile obs flake markdown shell toml nix justfile gh) ;; + fix) modules=(js rs py dart obs markdown shell toml nix justfile) ;; + ci-test) modules=(js rs py) ;; +esac + +selected=() +missing=() +for module in "${modules[@]}"; do + pattern=${scope[$module]} + if [[ -z "$all" && -n "$pattern" ]] && ! grep -qE "$pattern" "$changed"; then + continue + fi + absent=() + for tool in ${tools[$module]}; do + command -v "$tool" >/dev/null 2>&1 || absent+=("$tool") + done + if ((${#absent[@]} == 0)); then + selected+=("$module") + elif [[ -n "${MOQ_STRICT:-}" ]]; then + missing+=("${absent[@]}") + else + echo "$action: skipping $module; missing ${absent[*]}" >&2 + fi +done + +if ((${#missing[@]})); then + echo "error: MOQ_STRICT is set but these tools are missing: $(printf '%s\n' "${missing[@]}" | sort -u | tr '\n' ' ')" >&2 + echo " run inside 'nix develop', or unset MOQ_STRICT to skip what isn't installed" >&2 + exit 1 +fi + +# rs selects crates from the same list, or the whole workspace. +rs_list=$changed +[[ -z "$all" ]] || rs_list=--all + +# Tracked and new files, skipping whatever .gitignore does (node_modules, target). +files() { + git ls-files -z --cached --others --exclude-standard -- "$@" +} + +# `check` and `ci-check` share every lint; they differ in how rs compiles and +# whether the tests run. +verb=${action#ci-} + +for module in "${selected[@]}"; do + case "$verb:$module" in + check:js) just js check ;; + check:workers) just js workers ;; + # `check` lints Rust through its test build, so the crates compile once; + # `ci-check` uses clippy, which is quicker when the tests run elsewhere. + check:rs) if [[ "$action" == check ]]; then just rs check-test-changed "$rs_list"; else just rs check-changed "$rs_list"; fi ;; + check:bench) cargo check --locked --package moq-relay --package moq-bench --features moq-relay/io-uring ;; + check:quest) quest check ;; + check:drill) just test drill-sensitivity --apply-only ;; + check:obs_compile) just obs compile ;; + check:flake) nix flake check ;; + check:markdown) + bun install --frozen-lockfile + sh/markdown.sh check + ;; + check:toml) RUST_LOG=error taplo format --check ;; + check:nix) files '*.nix' | xargs -0 nixfmt --check ;; + check:justfile) files justfile '*/justfile' | xargs -0 -n1 just --fmt --check --justfile ;; + fix:rs) just rs fix-changed "$rs_list" ;; + fix:markdown) + bun install + sh/markdown.sh fix + ;; + fix:toml) RUST_LOG=error taplo format ;; + fix:nix) files '*.nix' | xargs -0 nixfmt ;; + fix:justfile) files justfile '*/justfile' | xargs -0 -n1 just --fmt --justfile ;; + test:rs) just rs test-changed "$rs_list" ;; + *:shell) sh/shell.sh "$verb" ;; + *) just "$module" "$verb" ;; + esac +done + +# The rest of `check`'s tests. rs ran its own above, and the kt, swift, go, and +# dart checks always run theirs. +if [[ "$action" == check ]]; then + for module in "${selected[@]}"; do + case "$module" in + js | py) just "$module" test ;; + esac + done +fi diff --git a/sh/drafts/build.sh b/sh/drafts/build.sh new file mode 100755 index 00000000000..e050b63a3c1 --- /dev/null +++ b/sh/drafts/build.sh @@ -0,0 +1,20 @@ +#!/usr/bin/env bash +# Render drafts to .txt and .html: sh/drafts/build.sh [NAME...] +# +# The local editor's copy (gitignored), with the -latest docname as-is; use +# `just drafts publish` for a version. No NAME renders every draft. +set -euo pipefail + +cd "$(git rev-parse --show-toplevel)/drafts" + +names=("$@") +if ((${#names[@]} == 0)); then + for f in draft-*.md; do names+=("${f%.md}"); done +fi + +for name in "${names[@]}"; do + kramdown-rfc --v3 <"$name.md" >"$name.xml" + xml2rfc -q --allow-local-file-access --text "$name.xml" -o "$name.txt" + xml2rfc -q --allow-local-file-access --html "$name.xml" -o "$name.html" + echo "built $name.txt and $name.html" +done diff --git a/sh/drafts/check.sh b/sh/drafts/check.sh new file mode 100755 index 00000000000..3b8f884cab5 --- /dev/null +++ b/sh/drafts/check.sh @@ -0,0 +1,36 @@ +#!/usr/bin/env bash +# Validate that every draft parses and that its generated XML passes validation. +# +# Both halves are needed. kramdown-rfc catches markdown and frontmatter errors, +# but happily emits XML for a cross-reference that points at no such section; +# xml2rfc is what rejects the dangling IDREF. Checking only the first half lets +# a broken `[text](#anchor)` pass here and then fail at `publish` time. +# +# --preptool stops after validation instead of rendering txt/html, and -N keeps +# it off the network (kramdown-rfc already inlined the references), which is +# what makes this a couple of seconds per draft rather than a minute. +set -euo pipefail + +cd "$(git rev-parse --show-toplevel)" +bun install --frozen-lockfile +cd drafts + +if grep -n "$(printf '\t')" draft-*.md; then + echo "tabs render unpredictably in xml2rfc; indent with spaces" >&2 + exit 1 +fi + +for f in draft-*.md; do + echo "checking $f" + kramdown-rfc --v3 <"$f" >"${f%.md}.xml" + xml2rfc -q --allow-local-file-access --preptool -N "${f%.md}.xml" -o "${f%.md}.prepped.xml" || { + rm -f "${f%.md}.prepped.xml" + exit 1 + } + rm -f "${f%.md}.prepped.xml" +done + +for f in moq-e2ee-*.ts; do + bun tsc --noEmit --skipLibCheck --target esnext --module esnext --moduleResolution bundler --types bun "$f" + bun "$f" +done diff --git a/sh/drafts/publish.sh b/sh/drafts/publish.sh new file mode 100755 index 00000000000..9ef5e8ad5c0 --- /dev/null +++ b/sh/drafts/publish.sh @@ -0,0 +1,44 @@ +#!/usr/bin/env bash +# Submit a new draft version to the IETF datatracker: sh/drafts/publish.sh NAME VERSION EMAIL +# +# The datatracker emails the submitter a confirmation link; the submission is +# not final until that link is clicked. For a brand-new draft (-00) set +# "Replaces" on the confirmation page. +set -euo pipefail + +usage="usage: sh/drafts/publish.sh NAME VERSION EMAIL" +name=${1:?$usage} +version=${2:?$usage} +email=${3:?$usage} + +cd "$(git rev-parse --show-toplevel)/drafts" +case "$version" in + [0-9][0-9]) ;; + *) + echo "version must be two digits, e.g. 05" >&2 + exit 1 + ;; +esac +doc="$name-$version" +if [ ! -f "$name.md" ]; then + echo "no such draft: $name.md" >&2 + exit 1 +fi +echo "Building $doc.xml" +sed "s/$name-latest/$doc/g" "$name.md" | kramdown-rfc --v3 >"$doc.xml" +echo "Submitting $doc.xml to the datatracker as $email" +resp="$(mktemp)" +code="$(curl -sS -o "$resp" -w '%{http_code}' \ + -F "user=$email" -F "xml=@$doc.xml" \ + https://datatracker.ietf.org/api/submission)" +echo "HTTP $code" +cat "$resp" +echo +rm -f "$resp" +case "$code" in + 200 | 201) echo "Submitted. Check $email for the confirmation link." ;; + *) + echo "Submission failed." >&2 + exit 1 + ;; +esac diff --git a/.github/scripts/alert.sh b/sh/gh/alert.sh similarity index 93% rename from .github/scripts/alert.sh rename to sh/gh/alert.sh index 6a795dc47ad..ee95b2d7e39 100755 --- a/.github/scripts/alert.sh +++ b/sh/gh/alert.sh @@ -18,7 +18,7 @@ set -euo pipefail SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -WORKFLOWS_DIR="$(cd "$SCRIPT_DIR/../workflows" && pwd)" +WORKFLOWS_DIR="$(cd "$SCRIPT_DIR/../../.github/workflows" && pwd)" # Post a red embed naming the workflow, what it was reacting to, and a link. # jq builds the body so a commit subject with quotes or newlines can't produce @@ -88,7 +88,7 @@ check_coverage() { return 1 } -# Names of workflows carrying at least one non-pull_request trigger. +# Names of workflows with a trigger that starts a run outside a pull request. # # The YAML is parsed rather than pattern-matched. GitHub accepts `on:` as a # block map, block sequence, flow sequence or bare scalar, any of which may wrap @@ -113,9 +113,10 @@ non_pr_workflow_names() { printf "%s\n" "${files[@]}" | bun -e ' const files = (await Bun.stdin.text()).split("\n").filter(Boolean); -// Both report their failure as a check on the PR itself, so alert.yml skips -// them at runtime and a workflow triggered only by these needs no entry. -const PR_EVENTS = new Set(["pull_request", "pull_request_target"]); +// The PR events report their failure as a check on the PR itself, and +// workflow_call runs inside the run that called it, so a workflow triggered +// only by these needs no entry. +const UNWATCHED = new Set(["pull_request", "pull_request_target", "workflow_call"]); const names = []; for (const file of files) { const doc = Bun.YAML.parse(await Bun.file(file).text()); @@ -132,7 +133,7 @@ for (const file of files) { console.error("alert.sh: cannot read the on: value of " + file); process.exit(2); } - if (!triggers.some((t) => !PR_EVENTS.has(t))) continue; + if (!triggers.some((t) => !UNWATCHED.has(t))) continue; const name = doc.name; if (typeof name !== "string" || name.trim() === "") { diff --git a/sh/gh/check-runs.ts b/sh/gh/check-runs.ts new file mode 100644 index 00000000000..c979f47b73b --- /dev/null +++ b/sh/gh/check-runs.ts @@ -0,0 +1,26 @@ +// Fail when a workflow `run:` step names a script file. Workflows call `just` +// recipes, so a script can move or change its arguments without touching them, +// and the same command works locally. +import { Glob } from "bun"; + +type Step = { run?: string }; +type Job = { steps?: Step[] }; +type Workflow = { jobs?: Record }; + +const violations: string[] = []; +for await (const path of new Glob(".github/workflows/*.{yml,yaml}").scan({ dot: true })) { + const workflow = Bun.YAML.parse(await Bun.file(path).text()) as Workflow; + for (const [name, job] of Object.entries(workflow.jobs ?? {})) { + for (const step of job.steps ?? []) { + for (const line of step.run?.split("\n") ?? []) { + if (/\.(sh|py|ts|js|mjs)\b/.test(line)) violations.push(`${path} (${name}): ${line.trim()}`); + } + } + } +} + +if (violations.length > 0) { + console.error("workflow steps must run a `just` recipe, not a script:"); + for (const violation of violations.sort()) console.error(` ${violation}`); + process.exit(1); +} diff --git a/.github/scripts/install-formula.py b/sh/gh/install-formula.py similarity index 100% rename from .github/scripts/install-formula.py rename to sh/gh/install-formula.py diff --git a/.github/scripts/install-formula.test.py b/sh/gh/install-formula.test.py similarity index 100% rename from .github/scripts/install-formula.test.py rename to sh/gh/install-formula.test.py diff --git a/.github/scripts/release.sh b/sh/gh/release.sh similarity index 100% rename from .github/scripts/release.sh rename to sh/gh/release.sh diff --git a/.github/scripts/release.test.sh b/sh/gh/release.test.sh similarity index 100% rename from .github/scripts/release.test.sh rename to sh/gh/release.test.sh diff --git a/.github/scripts/render-formula.sh b/sh/gh/render-formula.sh similarity index 100% rename from .github/scripts/render-formula.sh rename to sh/gh/render-formula.sh diff --git a/.github/scripts/trigger-repo-publish.sh b/sh/gh/trigger-repo-publish.sh similarity index 100% rename from .github/scripts/trigger-repo-publish.sh rename to sh/gh/trigger-repo-publish.sh diff --git a/go/scripts/check-errors.sh b/sh/go/check-errors.sh similarity index 100% rename from go/scripts/check-errors.sh rename to sh/go/check-errors.sh diff --git a/go/scripts/check.sh b/sh/go/check.sh similarity index 84% rename from go/scripts/check.sh rename to sh/go/check.sh index 46f39f23afc..4f0d7de59bd 100755 --- a/go/scripts/check.sh +++ b/sh/go/check.sh @@ -3,7 +3,7 @@ set -euo pipefail # Local smoke check for the Go module. # -# Stages the ffi + wrapper modules from this checkout (scripts/stage.sh) and +# Stages the ffi + wrapper modules from this checkout (sh/go/stage.sh) and # runs `go build`/`go vet`/`go test` against them. Intended for `just go check`. # # The main repo stays binary-free: no `.a` or generated `.go` files land @@ -13,17 +13,13 @@ set -euo pipefail # Skipped cleanly on hosts without `go`, `cargo`, or `uniffi-bindgen-go`. SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -GO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +GO_DIR="$(cd "$SCRIPT_DIR/../../go" && pwd)" WORKSPACE_DIR="$(cd "$GO_DIR/.." && pwd)" if ! command -v go >/dev/null 2>&1; then echo "go check: no go on PATH, skipping" >&2 exit 0 fi -# The publish state machine needs neither cargo nor generated bindings, so it -# runs ahead of the gates that skip a partial toolchain. -bash "$SCRIPT_DIR/publish-wrapper.test.sh" - if ! command -v cargo >/dev/null 2>&1; then echo "go check: no cargo on PATH, skipping" >&2 exit 0 diff --git a/go/scripts/package-ffi.sh b/sh/go/package-ffi.sh similarity index 98% rename from go/scripts/package-ffi.sh rename to sh/go/package-ffi.sh index 04450fd28f1..b2d89cd51d2 100755 --- a/go/scripts/package-ffi.sh +++ b/sh/go/package-ffi.sh @@ -10,7 +10,7 @@ set -euo pipefail # output at $BINDINGS_DIR/moq/moq.go. # # Usage: -# go/scripts/package-ffi.sh --version 0.0.0-dev --lib-dir libs --bindings-dir bindings --output dist +# sh/go/package-ffi.sh --version 0.0.0-dev --lib-dir libs --bindings-dir bindings --output dist # # Optional: # --source-dir DIR in-tree ffi module skeleton (default: go/ffi) @@ -24,7 +24,7 @@ set -euo pipefail # $LIB_DIR/x86_64-pc-windows-msvc/moq_ffi.lib SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -GO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +GO_ROOT="$(cd "$SCRIPT_DIR/../../go" && pwd)" WORKSPACE_DIR="$(cd "$GO_ROOT/.." && pwd)" VERSION="" diff --git a/go/scripts/package-wrapper.sh b/sh/go/package-wrapper.sh similarity index 97% rename from go/scripts/package-wrapper.sh rename to sh/go/package-wrapper.sh index 210d0db854c..52159e7932e 100755 --- a/go/scripts/package-wrapper.sh +++ b/sh/go/package-wrapper.sh @@ -13,7 +13,7 @@ set -euo pipefail # produces an identical tree and no release. # # Usage: -# go/scripts/package-wrapper.sh --line 0.3 --ffi-version 0.2.18 --output dist +# sh/go/package-wrapper.sh --line 0.3 --ffi-version 0.2.18 --output dist # # Optional: # --source-dir DIR in-tree wrapper skeleton (default: go/wrapper) @@ -22,7 +22,7 @@ set -euo pipefail # --no-archive SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -GO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +GO_ROOT="$(cd "$SCRIPT_DIR/../../go" && pwd)" WORKSPACE_DIR="$(cd "$GO_ROOT/.." && pwd)" LINE="" diff --git a/go/scripts/publish-ffi.sh b/sh/go/publish-ffi.sh similarity index 100% rename from go/scripts/publish-ffi.sh rename to sh/go/publish-ffi.sh diff --git a/go/scripts/publish-wrapper.sh b/sh/go/publish-wrapper.sh similarity index 100% rename from go/scripts/publish-wrapper.sh rename to sh/go/publish-wrapper.sh diff --git a/go/scripts/publish-wrapper.test.sh b/sh/go/publish-wrapper.test.sh similarity index 97% rename from go/scripts/publish-wrapper.test.sh rename to sh/go/publish-wrapper.test.sh index 423778218be..39e57fe7943 100755 --- a/go/scripts/publish-wrapper.test.sh +++ b/sh/go/publish-wrapper.test.sh @@ -12,7 +12,7 @@ set -euo pipefail # missing. SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -GO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +GO_DIR="$(cd "$SCRIPT_DIR/../../go" && pwd)" if ! command -v go >/dev/null 2>&1; then echo "publish-wrapper test: no go on PATH, skipping" >&2 @@ -75,7 +75,7 @@ LINE=$(tr -d '[:space:]' <"$GO_DIR/wrapper/VERSION") # Stage a real wrapper tarball. --skip-tidy keeps it offline (no go.sum), which # is fine: publish-wrapper.sh only reads VERSION out of the staged tree. -bash "$GO_DIR/scripts/package-wrapper.sh" \ +bash "$SCRIPT_DIR/package-wrapper.sh" \ --line "$LINE" \ --ffi-version "0.0.0-test" \ --source-dir "$GO_DIR/wrapper" \ @@ -93,7 +93,7 @@ publish() { ( cd "$WORK/run" GO_MIRROR_URL="$MIRROR" GO_MIRROR_TOKEN=unused \ - bash "$GO_DIR/scripts/publish-wrapper.sh" + bash "$SCRIPT_DIR/publish-wrapper.sh" ) } diff --git a/go/scripts/stage.sh b/sh/go/stage.sh similarity index 98% rename from go/scripts/stage.sh rename to sh/go/stage.sh index dcb09e22897..86db6e827ca 100755 --- a/go/scripts/stage.sh +++ b/sh/go/stage.sh @@ -10,7 +10,7 @@ set -euo pipefail # its own module against them and build Go code against these bindings. # # Usage: -# go/scripts/stage.sh [--output DIR] +# sh/go/stage.sh [--output DIR] # # Optional: # --output DIR stage parent (default: /dist, gitignored) @@ -19,7 +19,7 @@ set -euo pipefail # for an optimized cdylib. SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -GO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +GO_DIR="$(cd "$SCRIPT_DIR/../../go" && pwd)" WORKSPACE_DIR="$(cd "$GO_DIR/.." && pwd)" STAGE_PARENT="$WORKSPACE_DIR/dist" diff --git a/sh/js/workers.sh b/sh/js/workers.sh new file mode 100755 index 00000000000..4fb2178c2ac --- /dev/null +++ b/sh/js/workers.sh @@ -0,0 +1,16 @@ +#!/usr/bin/env bash +# Validate each Worker's deploy bundle without publishing or credentials. +# +# These Workers have lockfiles outside the Bun workspace, so `just js check` +# never installs or builds them. +set -euo pipefail + +cd "$(git rev-parse --show-toplevel)" + +for project in infra/apt infra/rpm demo/pub; do + ( + cd "$project" + bun install --frozen-lockfile + bun run deploy --dry-run + ) +done diff --git a/kt/scripts/check.sh b/sh/kt/check.sh similarity index 92% rename from kt/scripts/check.sh rename to sh/kt/check.sh index 4a00e10eb73..57c3be14a05 100644 --- a/kt/scripts/check.sh +++ b/sh/kt/check.sh @@ -2,7 +2,7 @@ set -euo pipefail # Full check for the Kotlin packages: regenerate the bindings + native lib -# (scripts/generate.sh), then run the raw-bindings and wrapper JVM tests. +# (sh/kt/generate.sh), then run the raw-bindings and wrapper JVM tests. # # Unlike generation, this needs a JDK and Gradle. Both ship in the `nix # develop` dev shell (see flake.nix ktDeps), so a missing one is an error @@ -11,7 +11,7 @@ set -euo pipefail # should run `just kt generate` instead. SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -KT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +KT_DIR="$(cd "$SCRIPT_DIR/../../kt" && pwd)" bash "$SCRIPT_DIR/generate.sh" diff --git a/kt/scripts/generate.sh b/sh/kt/generate.sh similarity index 96% rename from kt/scripts/generate.sh rename to sh/kt/generate.sh index b1716373fa6..4ddc0d5947e 100755 --- a/kt/scripts/generate.sh +++ b/sh/kt/generate.sh @@ -6,11 +6,11 @@ set -euo pipefail # and regenerate the uniffi bindings. No Gradle, no JDK required. # # Intended for environments that intentionally lack Gradle (e.g. regenerating -# checked-in bindings after a moq-ffi change). `scripts/check.sh` calls this +# checked-in bindings after a moq-ffi change). `sh/kt/check.sh` calls this # first and then compiles + tests the result. Requires cargo. SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -KT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +KT_DIR="$(cd "$SCRIPT_DIR/../../kt" && pwd)" WORKSPACE_DIR="$(cd "$KT_DIR/.." && pwd)" if ! command -v cargo >/dev/null 2>&1; then diff --git a/kt/scripts/package.sh b/sh/kt/package.sh similarity index 97% rename from kt/scripts/package.sh rename to sh/kt/package.sh index 73e9011d708..03c9cc13382 100755 --- a/kt/scripts/package.sh +++ b/sh/kt/package.sh @@ -10,7 +10,7 @@ set -euo pipefail # uniffi-bindgen kotlin output at $BINDINGS_DIR/uniffi/moq/moq.kt. # # Usage: -# kt/scripts/package.sh --version 0.0.0-dev --lib-dir libs --bindings-dir bindings --output dist +# sh/kt/package.sh --version 0.0.0-dev --lib-dir libs --bindings-dir bindings --output dist # # Expected $LIB_DIR layout (per target, populated by the build matrix): # $LIB_DIR/aarch64-linux-android/libmoq_ffi.so @@ -20,7 +20,7 @@ set -euo pipefail # ... etc. SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -KT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +KT_DIR="$(cd "$SCRIPT_DIR/../../kt" && pwd)" VERSION="" LIB_DIR="" diff --git a/sh/markdown.sh b/sh/markdown.sh new file mode 100755 index 00000000000..cd811fa9119 --- /dev/null +++ b/sh/markdown.sh @@ -0,0 +1,69 @@ +#!/usr/bin/env bash +# Lint or format every Markdown file: sh/markdown.sh check|fix +# +# remark-cli has no check mode: `--frail` raises the exit code on lint +# messages, and only `--output` formats, so a file that is merely misformatted +# passes both ways. `check` formats a scratch mirror and diffs it, so it stays +# read-only while `fix` writes in place. +set -euo pipefail + +cd "$(git rev-parse --show-toplevel)" + +case "${1:-}" in + check) ;; + fix) + bun remark . --quiet --output + exit 0 + ;; + *) + echo "usage: sh/markdown.sh check|fix" >&2 + exit 2 + ;; +esac + +mirror=$(mktemp -d) +trap 'rm -rf "$mirror"' EXIT + +extension_list=$(bun -e \ + 'import extensions from "markdown-extensions"; console.log(extensions.join("\n"))') +patterns=() +while IFS= read -r extension; do + [[ -n "$extension" ]] && patterns+=("*.$extension") +done <<<"$extension_list" +((${#patterns[@]})) || { + echo "error: remark reported no Markdown extensions" >&2 + exit 1 +} + +# Untracked files are in scope so a new doc is linted before it is staged; +# --exclude-standard keeps build output out. +files=() +while IFS= read -r -d '' file; do + [[ -f "$file" ]] || continue + files+=("$file") + mkdir -p "$mirror/$(dirname "$file")" + cp "$file" "$mirror/$file" +done < <(git ls-files -z --cached --others --exclude-standard -- "${patterns[@]}") +((${#files[@]})) || exit 0 + +# The config rides along so every .remarkignore pattern resolves against the +# mirror root exactly as it does here, and node_modules is where the plugins +# named by .remarkrc.mjs come from. +cp .remarkrc.mjs .remarkignore "$mirror/" +ln -s "$PWD/node_modules" "$mirror/node_modules" + +status=0 +(cd "$mirror" && bun remark . --quiet --frail --output) || status=$? + +stale=() +for file in "${files[@]}"; do + cmp -s "$file" "$mirror/$file" || stale+=("$file") +done + +if ((${#stale[@]})); then + echo "error: these files are not formatted, run 'just fix':" >&2 + printf ' %s\n' "${stale[@]}" >&2 + status=1 +fi + +exit "$status" diff --git a/sh/obs/check.sh b/sh/obs/check.sh new file mode 100755 index 00000000000..b8b651b41b5 --- /dev/null +++ b/sh/obs/check.sh @@ -0,0 +1,68 @@ +#!/usr/bin/env bash +# Lint formatting. Skips a tool silently if it isn't on $PATH (matches repo convention). +set -euo pipefail + +cd "$(dirname "${BASH_SOURCE[0]}")/../../cpp/obs" + +if grep -Fq '"MOQ_VERSION"' CMakePresets.json; then + echo "CMakePresets.json must not pin MOQ_VERSION" >&2 + exit 1 +fi +# The headers `just obs compile` type-checks against are a second copy of +# the OBS version this spec downloads, so a bump here has to reach flake.nix +# or the two gates check different libobs. +spec_obs=$(jq -r '.dependencies["obs-studio"].version // ""' buildspec.json) +flake_obs=$(sed -n '/pname = "libobs-headers"/,/}/p' ../../flake.nix | sed -n 's/.*version = "\([^"]*\)".*/\1/p') +# Both are pattern matches against files this recipe doesn't own the shape +# of. An empty parse compares equal to an empty parse, so the guard would +# pass by reporting nothing rather than by finding the versions in sync. +if [ -z "$spec_obs" ] || [ -z "$flake_obs" ]; then + echo "couldn't read the obs-studio version: '$spec_obs' from buildspec.json, '$flake_obs' from flake.nix" >&2 + exit 1 +fi +if [ "$spec_obs" != "$flake_obs" ]; then + echo "obs-studio is $spec_obs in buildspec.json but $flake_obs in flake.nix (libobs-headers)" >&2 + exit 1 +fi +# And a third: `just obs ci` links against nixpkgs' obs-studio, the one OBS +# this repo doesn't pick. Without this the released macOS/Windows binaries +# could be a whole libobs API apart from what CI ever compiles. Patch +# releases carry no API change, so only the major.minor has to agree; that +# also keeps the guard quiet until flake.lock actually moves OBS, which is +# the change that opens the gap and so the one that should fail. +# OBS_LINKED_VERSION comes from the dev shell (see flake.nix), so this leg +# is skipped outside it, where there is no nixpkgs obs-studio to compare. +# MOQ_STRICT turns that skip into an error for the same reason it turns a +# missing tool into one: in CI a leg that checks nothing still reports green. +if [ -z "${OBS_LINKED_VERSION:-}" ]; then + if [ -n "${MOQ_STRICT:-}" ]; then + echo "MOQ_STRICT is set but OBS_LINKED_VERSION is unset; run inside 'nix develop', which exports it" >&2 + exit 1 + fi +else + spec_api=$(echo "$spec_obs" | cut -d. -f1,2) + linked_api=$(echo "$OBS_LINKED_VERSION" | cut -d. -f1,2) + if [ "$spec_api" != "$linked_api" ]; then + echo "obs-studio is $spec_obs in buildspec.json but $OBS_LINKED_VERSION in nixpkgs, which is what 'just obs ci' links" >&2 + echo "bump buildspec.json and flake.nix's libobs-headers to $OBS_LINKED_VERSION, or pin nixpkgs back" >&2 + exit 1 + fi +fi +if command -v cmake >/dev/null; then + build_dir=$(mktemp -d) + trap 'rm -rf "$build_dir"' EXIT + if cmake -S . -B "$build_dir" -DMOQ_LOCAL= >"$build_dir/configure.log" 2>&1; then + echo "CMake accepted a release build without MOQ_VERSION" >&2 + exit 1 + fi + if ! grep -Fq "MOQ_VERSION is required when MOQ_LOCAL does not contain rs/libmoq" "$build_dir/configure.log"; then + cat "$build_dir/configure.log" >&2 + exit 1 + fi +fi +if command -v clang-format >/dev/null; then + git ls-files 'src/*.cpp' 'src/*.h' 'test/*.cpp' | xargs clang-format --dry-run --Werror +fi +if command -v gersemi >/dev/null; then + gersemi --check CMakeLists.txt cmake +fi diff --git a/sh/obs/compile.sh b/sh/obs/compile.sh new file mode 100755 index 00000000000..6253cc15860 --- /dev/null +++ b/sh/obs/compile.sh @@ -0,0 +1,67 @@ +#!/usr/bin/env bash +# Type-check every plugin source and unit test, without linking or an obs-deps +# download. +# +# This is the gate to run in a worktree. `just obs build` needs the +# multi-hundred-MB obs-deps bundle (macOS/Windows) and a full cargo build, per +# worktree; this needs neither, because the dev shell carries all three header +# sets: libobs pinned to the same OBS release buildspec.json downloads (see +# `obs-headers` in flake.nix), Qt6, and ffmpeg. CI links the real thing on Linux +# (.github/workflows/obs.yml). +# +# It compiles the Qt sources too, which the CMake build only does when +# ENABLE_QT and ENABLE_FRONTEND_API are on, so the definitions they gate on are +# set here to match. +# +# test/ is in scope because each test file defines the libmoq entry points the +# plugin calls, so a signature that drifts from the generated moq.h is a +# conflicting C declaration. Catching that needs only headers, which is why it +# belongs here: `just obs ci` finds the same drift, but only where obs.yml's +# path filter reaches, and `just obs test` is manual. +set -euo pipefail + +here=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd) +cd "$here/../../cpp/obs" + +# Never skips, for the reason `test` doesn't: a compile gate that reports +# success without compiling is worse than no gate. Everything it needs is in +# the dev shell, so the fix is always to enter it. +cxx="${CXX:-c++}" +if ! command -v "$cxx" >/dev/null; then + echo "no C++ compiler at '$cxx'" >&2 + exit 1 +fi +for pkgs in "Qt6Widgets Qt6Gui Qt6Core" "libavcodec libavutil libswscale libswresample"; do + # shellcheck disable=SC2086 + if ! pkg-config --exists $pkgs; then + echo "missing headers for: $pkgs" >&2 + echo "run inside 'nix develop', which supplies Qt6 and ffmpeg on every platform" >&2 + exit 1 + fi +done + +# Assign first so a failure in `_includes` still aborts under `set -e`, +# then split on newlines only: an include path may contain spaces. +includes_raw=$("$here/includes.sh") +includes=() +while IFS= read -r flag; do includes+=("$flag"); done <<<"$includes_raw" + +qt=$(pkg-config --cflags Qt6Widgets Qt6Gui Qt6Core) +ffmpeg=$(pkg-config --cflags libavcodec libavutil libswscale libswresample) + +# MOQ_VERSION_STRING only reaches a label in the dock, so any value +# type-checks the same; CMake stamps the real libmoq version. +status=0 +for source in src/*.cpp test/*.cpp; do + # shellcheck disable=SC2086 + # -Wno-unused-command-line-argument: the nix compiler wrapper injects + # link flags, which a syntax-only run reports as unused, once per file. + # $qt and $ffmpeg stay unquoted on purpose: pkg-config hands back one + # space-separated string, and splitting it is the intended reading. + if ! "$cxx" -std=c++17 -fsyntax-only -Wno-unused-command-line-argument \ + "${includes[@]}" $qt $ffmpeg \ + -DMOQ_FRONTEND_ENABLED -DMOQ_VERSION_STRING='"0.0.0"' "$source"; then + status=1 + fi +done +exit $status diff --git a/sh/obs/fix.sh b/sh/obs/fix.sh new file mode 100755 index 00000000000..46cf8d27f86 --- /dev/null +++ b/sh/obs/fix.sh @@ -0,0 +1,12 @@ +#!/usr/bin/env bash +# Auto-fix formatting. +set -euo pipefail + +cd "$(dirname "${BASH_SOURCE[0]}")/../../cpp/obs" + +if command -v clang-format >/dev/null; then + git ls-files 'src/*.cpp' 'src/*.h' 'test/*.cpp' | xargs clang-format -i +fi +if command -v gersemi >/dev/null; then + gersemi --in-place CMakeLists.txt cmake +fi diff --git a/sh/obs/includes.sh b/sh/obs/includes.sh new file mode 100755 index 00000000000..45a8f83f316 --- /dev/null +++ b/sh/obs/includes.sh @@ -0,0 +1,72 @@ +#!/usr/bin/env bash +# Print the -I flags for libobs and libmoq, shared by compile.sh and unit.sh. +# +# moq.h is generated by cbindgen from rs/libmoq/src, so regenerate rather than +# just locating it: a stale header is how a plugin call to a since-changed +# libmoq function type-checks anyway. +set -euo pipefail + +cd "$(dirname "${BASH_SOURCE[0]}")/../../cpp/obs" + +# The dev shell's pinned headers first, so every platform checks against the +# same libobs. Then the obs-deps framework (macOS/Windows), the OBS sources +# CMake unpacks beside it, and a system install (Linux without nix). +obs_include="" +for candidate in \ + "${OBS_INCLUDE_DIR:-}" \ + .deps/Frameworks/libobs.framework/Versions/A/Headers \ + .deps/obs-studio-*/libobs; do + if [ -n "$candidate" ] && [ -f "$candidate/obs.h" ]; then + obs_include="$candidate" + break + fi +done +if [ -z "$obs_include" ] && command -v pkg-config >/dev/null && pkg-config --exists libobs; then + obs_include=$(pkg-config --variable=includedir libobs)/obs +fi +if [ -z "$obs_include" ]; then + echo "libobs headers not found; run inside 'nix develop' (or set OBS_INCLUDE_DIR)" >&2 + exit 1 +fi + +# obs.h reaches as of OBS 32, which used to be vendored +# under libobs/util/ and so came along with the headers above. The dev shell +# carries it (see flake.nix); the obs-deps bundle ships its own copy beside +# libobs, which is how the macOS and Windows builds get it. +simde_include="" +if command -v pkg-config >/dev/null && pkg-config --exists simde; then + simde_include=$(pkg-config --variable=includedir simde) +else + for candidate in .deps/obs-deps-*/include; do + if [ -f "$candidate/simde/x86/sse2.h" ]; then + simde_include="$candidate" + break + fi + done +fi +if [ -z "$simde_include" ]; then + echo "simde headers not found; run inside 'nix develop', which supplies them" >&2 + exit 1 +fi + +(cd ../.. && cargo check --locked --quiet -p libmoq) + +# rs/libmoq/build.rs writes the header into its OUT_DIR, so ask cargo where +# that is. Replays the check above from cache, so it costs a process rather +# than a compile. +out_dir=$(cd ../.. && cargo check --locked -p libmoq --message-format=json | + jq -r 'select(.reason == "build-script-executed") | select(.package_id | tostring | test("libmoq")) | .out_dir' | + tail -1) +if [ -z "$out_dir" ]; then + echo "cargo reported no build script output for libmoq" >&2 + exit 1 +fi +moq_include="$out_dir/include" +if [ ! -f "$moq_include/moq.h" ]; then + echo "$moq_include/moq.h missing after 'cargo check --locked -p libmoq'" >&2 + exit 1 +fi + +# One flag per line, path glued to the -I, so a caller can rebuild the +# arguments without splitting on the spaces in a path. +printf -- '-I%s\n' src "$obs_include" "$simde_include" "$moq_include" diff --git a/sh/obs/preset.sh b/sh/obs/preset.sh new file mode 100755 index 00000000000..c6bd950dc62 --- /dev/null +++ b/sh/obs/preset.sh @@ -0,0 +1,22 @@ +#!/usr/bin/env bash +# Detect the CMake preset for the current platform (or use the override). +# Pass `ci` as the second argument for the warnings-as-errors variant, whose +# name upstream spells differently on each platform. +set -euo pipefail + +cd "$(dirname "${BASH_SOURCE[0]}")/../../cpp/obs" +override=${1:-} +variant=${2:-} + +if [[ -n "$override" ]]; then + echo "$override" +elif [[ "$OSTYPE" == "darwin"* ]]; then + [[ "$variant" == "ci" ]] && echo "macos-ci" || echo "macos" +elif [[ "$OSTYPE" == "linux-gnu"* ]]; then + [[ "$variant" == "ci" ]] && echo "ubuntu-ci-x86_64" || echo "ubuntu-x86_64" +elif [[ "$OSTYPE" == "msys" || "$OSTYPE" == "cygwin" ]]; then + [[ "$variant" == "ci" ]] && echo "windows-ci-x64" || echo "windows-x64" +else + echo "Unknown platform: $OSTYPE" >&2 + exit 1 +fi diff --git a/sh/obs/test.sh b/sh/obs/test.sh new file mode 100755 index 00000000000..d8e596050c3 --- /dev/null +++ b/sh/obs/test.sh @@ -0,0 +1,42 @@ +#!/usr/bin/env bash +# Unit-test the plugin sources against stubbed libobs/libmoq/ffmpeg, under +# ThreadSanitizer. +# +# Manual because ThreadSanitizer needs its own build. `just obs ci` runs the +# same tests without it, so a regression these assertions catch still turns PR +# CI red; the sanitizer is what adds the races on top. Run this whenever you touch src/, especially the session +# callback plumbing, whose orderings the build can't check. +set -euo pipefail + +here=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd) +cd "$here/../../cpp/obs" + +# Unlike the lint recipes, this one never skips: a test gate that reports +# success without running anything is worse than no gate. +cxx="${CXX:-c++}" +unsupported="'$cxx' cannot build and run -fsanitize=thread binaries. These tests need a +Clang or GCC whose ThreadSanitizer runtime works on this host: set CXX, or on Windows run +them from WSL, since neither MSVC nor Clang on Windows implements ThreadSanitizer. +They also run without the sanitizer as part of 'just obs ci'." +if ! command -v "$cxx" >/dev/null; then + echo "no C++ compiler at '$cxx'." >&2 + echo "$unsupported" >&2 + exit 1 +fi + +probe=$(mktemp -d) +trap 'rm -rf "$probe"' EXIT + +# Run the probe, don't just link it: a mismatch between the compiler's TSan +# runtime and the host kernel (macOS is where this shows up) links fine and +# then segfaults before main, which is an unreadable way for the real test +# to fail. +# The subshell keeps bash's own "Segmentation fault" job message out of the +# output, so the explanation below is all the reader gets. +if ! printf 'int main(){}\n' | "$cxx" -x c++ -fsanitize=thread -o "$probe/probe" - >/dev/null 2>&1 || + ! ("$probe/probe" >/dev/null 2>&1) 2>/dev/null; then + echo "$unsupported" >&2 + exit 1 +fi + +"$here/unit.sh" tsan diff --git a/sh/obs/unit.sh b/sh/obs/unit.sh new file mode 100755 index 00000000000..54b775baace --- /dev/null +++ b/sh/obs/unit.sh @@ -0,0 +1,54 @@ +#!/usr/bin/env bash +# Compile and run the unit tests: sh/obs/unit.sh [plain|tsan] +# +# Shared by `just obs test` (ThreadSanitizer) and `just obs ci` (plain), so +# both run the same assertions. +set -euo pipefail + +here=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd) +cd "$here/../../cpp/obs" +mode=${1:-plain} + +cxx="${CXX:-c++}" +if ! command -v "$cxx" >/dev/null; then + echo "no C++ compiler at '$cxx'" >&2 + exit 1 +fi +# moq-source.cpp decodes with ffmpeg, so its test needs the headers even +# though it stubs every function out of them. +if ! pkg-config --exists libavcodec libavutil libswscale; then + echo "missing ffmpeg headers" >&2 + echo "run inside 'nix develop', which supplies ffmpeg on every platform" >&2 + exit 1 +fi + +includes_raw=$("$here/includes.sh") +includes=() +while IFS= read -r flag; do includes+=("$flag"); done <<<"$includes_raw" + +ffmpeg=$(pkg-config --cflags libavcodec libavutil libswscale) + +flags=(-std=c++17 -g -O0 -pthread) +if [ "$mode" = "tsan" ]; then + flags+=(-fsanitize=thread) +fi + +out=$(mktemp -d) +trap 'rm -rf "$out"' EXIT + +# One binary per source under test: each test file defines its own libobs and +# libmoq stubs, so two of them can't share a link. Header-only helpers +# (quality defaults) build as a third binary with no plugin source. +for name in moq-output moq-source; do + # shellcheck disable=SC2086 + # $ffmpeg stays unquoted on purpose: pkg-config hands back one + # space-separated string, and splitting it is the intended reading. + "$cxx" "${flags[@]}" "${includes[@]}" $ffmpeg \ + -o "$out/$name-test" "test/$name-test.cpp" "src/$name.cpp" + TSAN_OPTIONS="halt_on_error=1" "$out/$name-test" +done +for name in moq-quality-defaults moq-dock-stop moq-error moq-encoder-latency moq-dial moq-spark; do + "$cxx" "${flags[@]}" "${includes[@]}" \ + -o "$out/$name-test" "test/$name-test.cpp" + TSAN_OPTIONS="halt_on_error=1" "$out/$name-test" +done diff --git a/sh/py/samples.sh b/sh/py/samples.sh new file mode 100755 index 00000000000..dadc35e5d62 --- /dev/null +++ b/sh/py/samples.sh @@ -0,0 +1,17 @@ +#!/usr/bin/env bash +# Type-check every Python sample in the docs against the installed wrapper. +# +# Samples leave their inputs (`payload`, `pts`) to the reader, so they follow +# the declarations in moq-rs/tests/doc_prelude.py. +set -euo pipefail + +cd "$(git rev-parse --show-toplevel)/py" + +out=$(mktemp -d) +trap 'rm -rf "$out"' EXIT +{ + cat moq-rs/tests/doc_prelude.py + bash ../doc/lib/samples.sh python ../doc/lib/py/index.md moq-rs/README.md moq-rs/docs/index.md +} >"$out/samples.py" +echo '{"pythonVersion": "3.10"}' >"$out/pyrightconfig.json" +uv run --no-sync pyright --project "$out" "$out/samples.py" diff --git a/sh/rs/c-tests.sh b/sh/rs/c-tests.sh new file mode 100755 index 00000000000..225780bdcd3 --- /dev/null +++ b/sh/rs/c-tests.sh @@ -0,0 +1,74 @@ +#!/usr/bin/env bash +# Compile and run libmoq's C fixtures (`rs/libmoq/c-tests/*.c`), and the C doc +# samples, against libmoq.a, linked the way an embedder does: an external `cc` +# against the generated `moq.h`, plus the native libraries from +# `rs/libmoq/native-libs` that cargo can't inject into a link it doesn't drive. +# Unix only. +set -euo pipefail + +cd "$(git rev-parse --show-toplevel)" + +cc="${CC:-cc}" +if ! command -v "$cc" >/dev/null; then + echo "no C compiler at '$cc'" >&2 + exit 1 +fi + +cargo build --locked -p libmoq + +# Ask cargo where it put the staticlib and the header rather than assuming +# target/debug: CARGO_TARGET_DIR and a configured build target +# (`target//debug`) both move them, and guessing wrong would link a +# stale copy or nothing. Replays the build above from cache, so it costs a +# process, not a compile. +log=$(cargo build --locked -p libmoq --message-format=json) +lib=$(jq -r 'select(.reason == "compiler-artifact") | .filenames[] | select(endswith("/libmoq.a"))' <<<"$log" | tail -1) +if [ -z "$lib" ]; then + echo "cargo reported no libmoq.a for libmoq" >&2 + exit 1 +fi +profile=$(dirname "$lib") +# rs/libmoq/build.rs writes the header into its OUT_DIR. +out_dir=$(jq -r 'select(.reason == "build-script-executed") | select(.package_id | test("libmoq")) | .out_dir' <<<"$log" | tail -1) +include="$out_dir/include" +if [ -z "$out_dir" ] || [ ! -f "$include/moq.h" ]; then + echo "$include/moq.h missing after 'cargo build --locked -p libmoq'" >&2 + exit 1 +fi + +# Same list nix/overlay.nix (moq.pc), CMakeLists.txt, and test/interop/interop.sh read: +# `framework:Foo` is a linker framework flag, anything else a plain library. +case "$(uname -s)" in + Darwin) native_libs=rs/libmoq/native-libs/apple.txt ;; + *) native_libs=rs/libmoq/native-libs/linux.txt ;; +esac +libs=() +while read -r entry; do + case "$entry" in + '' | '#'*) continue ;; + framework:*) libs+=(-framework "${entry#framework:}") ;; + *) libs+=("-l$entry") ;; + esac +done <"$native_libs" + +out=$(mktemp -d) +trap 'rm -rf "$out"' EXIT + +# The C docs compile against this header too: each sample beside the inputs +# doc-samples.h declares, and every name the prose cites. A `moq_decode_*` +# wildcard ends in `_` and is skipped. +bash doc/lib/samples.sh c doc/lib/c/index.md >"$out/doc-samples.c" +"$cc" -fsyntax-only -Werror=implicit-function-declaration -include rs/libmoq/c-tests/doc-samples.h -I"$include" "$out/doc-samples.c" +grep -oE '\b(moq|MOQ)_[A-Za-z0-9_]*' doc/lib/c/index.md | grep -v '_$' | sort -u | while read -r name; do + if ! grep -qw "$name" "$include/moq.h"; then + echo "doc/lib/c/index.md cites $name, which moq.h does not declare" >&2 + exit 1 + fi +done + +for source in rs/libmoq/c-tests/*.c; do + bin="$out/$(basename "$source" .c)" + "$cc" "$source" -I"$include" -L"$profile" -lmoq "${libs[@]}" -o "$bin" + echo "running $source" + "$bin" +done diff --git a/sh/rs/fuzz.sh b/sh/rs/fuzz.sh new file mode 100755 index 00000000000..c23912f1e93 --- /dev/null +++ b/sh/rs/fuzz.sh @@ -0,0 +1,40 @@ +#!/usr/bin/env bash +# Coverage-guided fuzzing of the moq-net wire codecs: sh/rs/fuzz.sh TARGET [ARGS...] +# +# TARGET is lite, announce, ietf, varint, path, or pattern; ARGS pass to +# `cargo fuzz run`, so `just rs fuzz lite -- -max_total_time=300` bounds a run. +# See rs/moq-net/fuzz/README.md. +# +# Seeds are regenerated first so the corpus follows the dispatch rather than a +# stale run, and libFuzzer writes what it discovers to the FIRST corpus +# directory, which is why the generated seeds are passed second and stay +# read-only. +set -euo pipefail + +cd "$(git rev-parse --show-toplevel)" + +target=${1:?usage: sh/rs/fuzz.sh TARGET [ARGS...]} +shift + +if ! command -v cargo-fuzz >/dev/null 2>&1; then + echo "rs: cargo-fuzz is missing: cargo install --locked cargo-fuzz" >&2 + exit 1 +fi + +if ! rustup run nightly rustc --version >/dev/null 2>&1; then + echo "rs: the nightly toolchain is missing: rustup toolchain install nightly" >&2 + exit 1 +fi + +cargo run --locked -q -p moq-net --features fuzz --example fuzz-seeds -- rs/moq-net/fuzz/seeds +mkdir -p rs/moq-net/fuzz/corpus/"$target" + +# Nightly by PATH rather than by `cargo +nightly`: the dev shell puts a +# Nix-provided cargo ahead of the rustup shim, so the `+` form is not +# understood, and cargo-fuzz shells out to a bare `cargo` and `rustc` anyway. +# Both have to be the nightly ones or the sanitizer flags are rejected. +sysroot=$(rustup run nightly rustc --print sysroot) +export PATH="$sysroot/bin:$PATH" + +cargo fuzz run --fuzz-dir rs/moq-net/fuzz "$target" \ + rs/moq-net/fuzz/corpus/"$target" rs/moq-net/fuzz/seeds/"$target" "$@" diff --git a/rs/scripts/media-features.sh b/sh/rs/media-features.sh similarity index 100% rename from rs/scripts/media-features.sh rename to sh/rs/media-features.sh diff --git a/rs/scripts/package-binary.sh b/sh/rs/package-binary.sh similarity index 99% rename from rs/scripts/package-binary.sh rename to sh/rs/package-binary.sh index 0984857a204..cfda98d1ad7 100755 --- a/rs/scripts/package-binary.sh +++ b/sh/rs/package-binary.sh @@ -16,7 +16,7 @@ set -euo pipefail # produces an extensionless executable beside the archive. SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -RS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +RS_DIR="$(cd "$SCRIPT_DIR/../../rs" && pwd)" WORKSPACE_DIR="$(cd "$RS_DIR/.." && pwd)" CRATE="" diff --git a/rs/scripts/package-nfpm.sh b/sh/rs/package-nfpm.sh similarity index 100% rename from rs/scripts/package-nfpm.sh rename to sh/rs/package-nfpm.sh diff --git a/rs/scripts/package-rename.test.py b/sh/rs/package-rename.test.py similarity index 98% rename from rs/scripts/package-rename.test.py rename to sh/rs/package-rename.test.py index d4222ce00fd..484dda146aa 100644 --- a/rs/scripts/package-rename.test.py +++ b/sh/rs/package-rename.test.py @@ -27,7 +27,7 @@ def test_packages(self): for config, packager in (("nfpm", "deb"), ("transition", "deb"), ("nfpm", "rpm")): output = scratch / f"{name}-{config}.{packager}" subprocess.run([ - "bash", "rs/scripts/package-nfpm.sh", + "bash", "sh/rs/package-nfpm.sh", f"packaging/{old}/{config}.yaml", packager, str(output), ], env=env, cwd=ROOT, check=True) outputs[config, packager] = output diff --git a/rs/scripts/package-windows.sh b/sh/rs/package-windows.sh similarity index 98% rename from rs/scripts/package-windows.sh rename to sh/rs/package-windows.sh index 33658a71d51..19aee9b6a9b 100755 --- a/rs/scripts/package-windows.sh +++ b/sh/rs/package-windows.sh @@ -15,7 +15,7 @@ set -euo pipefail # releases, so wingetcreate can carry it forward unchanged. SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -RS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +RS_DIR="$(cd "$SCRIPT_DIR/../../rs" && pwd)" WORKSPACE_DIR="$(cd "$RS_DIR/.." && pwd)" CRATE="" diff --git a/sh/rs/package.sh b/sh/rs/package.sh new file mode 100755 index 00000000000..970d7c8ef7f --- /dev/null +++ b/sh/rs/package.sh @@ -0,0 +1,51 @@ +#!/usr/bin/env bash +# Build a .deb or .rpm for moq-relay or moq-cli locally: sh/rs/package.sh CRATE deb|rpm +# +# nfpm comes from the dev shell. An .rpm built this way links against the +# host's glibc; CI builds in an AlmaLinux 9 container for broad compatibility. +set -euo pipefail + +cd "$(git rev-parse --show-toplevel)" + +crate=${1:?usage: sh/rs/package.sh CRATE deb|rpm} +packager=${2:?usage: sh/rs/package.sh CRATE deb|rpm} + +case "$crate" in + moq-relay) bin=moq-relay ;; + moq-cli) bin=moq ;; + *) + echo "Unknown crate: $crate (use moq-relay or moq-cli)" >&2 + exit 1 + ;; +esac +case "$packager" in + deb) + if command -v dpkg >/dev/null 2>&1; then + arch=$(dpkg --print-architecture) + else + case "$(uname -m)" in + x86_64) arch=amd64 ;; + aarch64 | arm64) arch=arm64 ;; + *) + echo "Cannot infer deb arch from host $(uname -m)" >&2 + exit 1 + ;; + esac + fi + ;; + rpm) arch=$(uname -m) ;; + *) + echo "Unknown packager: $packager (use deb or rpm)" >&2 + exit 1 + ;; +esac +version=$(grep -m1 '^version' "rs/$crate/Cargo.toml" | sed 's/.*"\(.*\)".*/\1/') +cargo build --locked --release -p "$crate" +mkdir -p dist +VERSION="$version" ARCH="$arch" BINARY_PATH="target/release/$bin" \ + sh/rs/package-nfpm.sh "packaging/$crate/nfpm.yaml" "$packager" dist/ +if [[ "$packager" == deb && -f "packaging/$crate/transition.yaml" ]]; then + VERSION="$version" ARCH="$arch" \ + sh/rs/package-nfpm.sh "packaging/$crate/transition.yaml" deb dist/ +fi +ls -1 dist/ diff --git a/sh/rs/platform.sh b/sh/rs/platform.sh new file mode 100755 index 00000000000..ae807fca7f9 --- /dev/null +++ b/sh/rs/platform.sh @@ -0,0 +1,17 @@ +#!/usr/bin/env bash +# Compile what the branch changed since BASE, plus its dependents, on a Windows +# or macOS host. `--all` compiles the whole workspace. +# +# Usage: sh/rs/platform.sh [BASE|--all] +set -euo pipefail + +cd "$(git rev-parse --show-toplevel)" + +if [[ "${1:-}" == --all ]]; then + exec sh/rs/select.sh platform --all +fi + +list=$(mktemp) +trap 'rm -f "$list"' EXIT +sh/changed.sh "${1:-}" >"$list" +sh/rs/select.sh platform "$list" diff --git a/rs/scripts/scrub-macho.sh b/sh/rs/scrub-macho.sh similarity index 100% rename from rs/scripts/scrub-macho.sh rename to sh/rs/scrub-macho.sh diff --git a/sh/rs/select.sh b/sh/rs/select.sh new file mode 100755 index 00000000000..28bf44afa05 --- /dev/null +++ b/sh/rs/select.sh @@ -0,0 +1,178 @@ +#!/usr/bin/env bash +# Run `just rs check|check-test|fix|test` on the crates a diff touches, plus +# their dependents. `platform` is the Windows and macOS compile. +# +# Usage: sh/rs/select.sh check|check-test|fix|test|platform LISTFILE|--all +# +# LISTFILE holds the changed paths, one per line. `--all` is the whole +# workspace, as is a change to anything every crate is built or tested by. +set -euo pipefail + +usage="usage: sh/rs/select.sh check|check-test|fix|test|platform LISTFILE|--all" +action=${1:?$usage} +list=${2:?$usage} + +cd "$(git rev-parse --show-toplevel)" + +# Print `ALL`, nothing (no crate affected), or cargo package ids. +select_packages() { + if [[ "$list" == --all ]] || grep -qE '^(Cargo\.(toml|lock)|rust-toolchain\.toml|rs/justfile|sh/rs/(select|platform)\.sh|\.config/nextest\.toml)$' "$list"; then + echo ALL + return + fi + + grep -q '^rs/' "$list" || return 0 + + # `--no-deps` keeps this to workspace members and off the network. + local metadata + metadata=$(cargo metadata --format-version 1 --no-deps) + + # A seed is the first path segment under `rs/`, so only a crate whose + # manifest sits directly at `rs//Cargo.toml` can be one. That drops + # `moq-net-fuzz` (at `rs/moq-net/fuzz`), which a moq-net diff would + # otherwise select as a dependent and compile libFuzzer for. The separator + # is normalized first so Windows paths split too. + metadata=$(jq '.packages |= map((.manifest_path |= gsub("\\\\"; "/")) | select(.manifest_path | split("/")[-3] == "rs"))' <<<"$metadata") + + # A changed path is a seed only because every crate directory is named + # after its crate. Under-selecting checks nothing, so fall back to all. + if jq -e '.packages[] | select((.manifest_path | split("/")[-2]) != .name)' <<<"$metadata" >/dev/null; then + echo "rs: a crate directory no longer matches its crate name; selecting everything." >&2 + echo ALL + return + fi + + local seeds edges selected + seeds=$(sed -n 's|^rs/\([^/]*\)/.*|\1|p' "$list" | sort -u) + edges=$(jq -r '.packages[] | .name as $name | .dependencies[] | "\($name) \(.name)"' <<<"$metadata") + + # A crate is rebuilt when anything it depends on changed, so walk the edges + # backwards until the selection stops growing. Test the value, not the key: + # awk creates a key on every `want[dep[i]]` read. The id lookup below drops + # names that are not workspace crates, such as a seed from `rs/AGENTS.md`. + # The seeds go through the environment because BSD awk (macOS) rejects a + # newline in a `-v` value. + selected=$(SEEDS="$seeds" awk ' + BEGIN { split(ENVIRON["SEEDS"], s, "\n"); for (i in s) want[s[i]] = 1 } + { pkg[NR] = $1; dep[NR] = $2 } + END { + do { + grew = 0 + for (i = 1; i <= NR; i++) + if (want[dep[i]] && !want[pkg[i]]) { want[pkg[i]] = 1; grew = 1 } + } while (grew) + for (name in want) if (want[name]) print name + } + ' <<<"$edges" | sort -u) + + [[ -n "$selected" ]] || return 0 + + # Cargo's own package ids, not bare names: a workspace crate that is also + # pulled from crates.io (kio) makes `--package kio` ambiguous, and cargo + # refuses before compiling anything. + jq -r --arg selected "$selected" ' + ($selected | split("\n")) as $want + | .packages[] + | select(.name as $name | $want | index($name) != null) + | "--package \(.id)" + ' <<<"$metadata" | sort -u | tr '\n' ' ' +} + +packages=$(select_packages) + +# Ids are `path+file://#` for a directory named after its crate. +names=$(tr ' ' '\n' <<<"$packages" | sed -n 's|.*/\([^/#]*\)#.*|\1|p' | sort -u | tr '\n' ' ') + +# True when the selection includes a crate matching the pattern. +wants() { + [[ "$packages" == ALL ]] || grep -qwE "$1" <<<"$names" +} + +# The media feature contract script is no crate, so its own diff selects +# nothing and still has to reach the gate below. +media_script= +if [[ -f "$list" ]] && grep -qx 'sh/rs/media-features.sh' "$list"; then media_script=1; fi + +case "$packages" in + "") + if [[ "$action" == check* && -n "$media_script" ]]; then + just rs media-features + else + echo "rs: no crates affected; skipping." + fi + exit 0 + ;; + ALL) echo "rs: selecting the workspace" ;; + *) echo "rs: selecting $names" ;; +esac + +# `moq-net-fuzz` needs a nightly toolchain; only `just rs fuzz` compiles it. +if [[ "$packages" == ALL ]]; then + flags=(--workspace --exclude moq-net-fuzz) +else + # Space-separated `--package ` pairs; ids contain no spaces. + # shellcheck disable=SC2206 + flags=($packages) +fi + +case "$action" in + check | check-test) + just rs "$action" "${flags[@]}" + # Workspace feature unification hides a broken moq-tokio feature set + # whenever any dependent enables a transport. + if wants moq-tokio; then just rs tokio-features; fi + # moq-wasm's crate root is `#![cfg(target_arch = "wasm32")]`, so only a + # wasm32 pass checks it. moq-mux and moq-ffi ride along in that pass, and + # nothing depends on moq-ffi, so each has to reach it on its own. + if wants '(moq-wasm|moq-mux|moq-ffi)'; then just rs wasm; fi + # Device code behind the off-by-default `capture` feature. check-test + # lints it through the test build, as for the default features. + if wants '(moq-video|moq-audio)'; then + if [[ "$action" == check-test ]]; then CARGO_BUILD_WARNINGS=deny just rs capture-test; else just rs capture; fi + fi + # moq-cli's media tasks are behind `play`; only check-test runs tests. + if [[ "$action" == check-test ]] && wants moq-cli; then just rs play; fi + # The relay's io_uring listener, off the default feature set. + if wants moq-relay; then just rs uring-check; fi + # Each media feature shape compiles on its own, about two minutes. + if [[ -n "$media_script" ]] || wants '(moq-video|moq-audio|moq-transcode)'; then just rs media-features; fi + ;; + fix) + just rs fix "${flags[@]}" + if wants '(moq-wasm|moq-mux|moq-ffi)'; then just rs wasm-fix; fi + ;; + test) + # A selection can hold nothing testable (moq-wasm has no host tests), and + # nextest exits 4 on that; the whole workspace finding none really is wrong. + [[ "$packages" == ALL ]] || flags+=(--no-tests=pass) + just rs test "${flags[@]}" + # Tests behind the off-by-default `capture` and `play` features. + if wants '(moq-video|moq-audio)'; then just rs capture-test; fi + if wants moq-cli; then just rs play; fi + ;; + platform) + # moq-gst links GStreamer via pkg-config, which the runners don't have. + if [[ "$packages" == ALL ]]; then + flags+=(--exclude moq-gst) + else + flags=() + for id in $packages; do + [[ "$id" == --package || "$id" == */moq-gst#* ]] || flags+=(--package "$id") + done + if ((${#flags[@]} == 0)); then + echo "rs: no crates affected; skipping." + exit 0 + fi + fi + # `play` and `capture` are off by default and turn on the device and + # render code in moq-video, moq-audio, and the cli. Only when moq-cli is + # selected, since cargo rejects a feature of a package outside the + # selection; a change to anything they reach selects moq-cli anyway. + if wants moq-cli; then flags+=(--features "moq-cli/play moq-cli/capture"); fi + cargo check --locked "${flags[@]}" --all-targets + ;; + *) + echo "$usage" >&2 + exit 2 + ;; +esac diff --git a/rs/scripts/stats-docs.py b/sh/rs/stats-docs.py similarity index 100% rename from rs/scripts/stats-docs.py rename to sh/rs/stats-docs.py diff --git a/sh/rs/tokio-features.sh b/sh/rs/tokio-features.sh new file mode 100755 index 00000000000..b80de4f8e83 --- /dev/null +++ b/sh/rs/tokio-features.sh @@ -0,0 +1,28 @@ +#!/usr/bin/env bash +# Compile moq-tokio by itself at the feature extremes and with each crypto +# provider. Its default-feature build is already part of the ordinary clippy +# pass; this catches what workspace feature unification hides. +set -euo pipefail + +cd "$(git rev-parse --show-toplevel)" + +cargo clippy --locked -p moq-tokio --no-default-features -- -D warnings +cargo clippy --locked -p moq-tokio --all-features -- -D warnings +cargo clippy --locked -p moq-tokio --no-default-features --features noq,aws-lc-rs -- -D warnings +cargo clippy --locked -p moq-tokio --no-default-features --features noq,ring -- -D warnings + +for feature in aws-lc-rs ring tcp uds websocket; do + cargo clippy --locked -p moq-tokio --no-default-features --features "$feature" -- -D warnings +done + +# shellcheck disable=SC2016 # the backticks are literal, as rustc prints them +want='a rustls QUIC backend requires a crypto provider: enable either the `aws-lc-rs` or `ring` feature' +if output=$(cargo check --locked -p moq-tokio --no-default-features --features noq 2>&1); then + echo "rs: moq-tokio with only noq should reject its missing crypto provider" >&2 + exit 1 +fi +if ! grep -qF "$want" <<<"$output"; then + echo "rs: moq-tokio with only noq should fail on: $want" >&2 + echo "$output" | grep -E '^error' >&2 || true + exit 1 +fi diff --git a/sh/rs/vulkan-cuda.sh b/sh/rs/vulkan-cuda.sh new file mode 100755 index 00000000000..bcdc12944c0 --- /dev/null +++ b/sh/rs/vulkan-cuda.sh @@ -0,0 +1,17 @@ +#!/usr/bin/env bash +# Exercise the Vulkan producer -> CUDA image contract, the GPU color conversion +# and resize, and NVENC encoding of the result on Linux/NVIDIA hardware. The +# driver directory is added explicitly because the Nix shell's dynamic loader +# path does not include Ubuntu's host driver directory. +set -euo pipefail + +cd "$(git rev-parse --show-toplevel)" + +driver=$(/usr/sbin/ldconfig -p | awk '/libcuda\.so\.1/{print $NF; exit}') +if [[ -z "$driver" ]]; then + echo "libcuda.so.1 is not installed" >&2 + exit 1 +fi +driver_dir=$(dirname "$driver") +export LD_LIBRARY_PATH="$driver_dir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" +cargo nextest run --locked -p moq-video --run-ignored only -E 'test(/^frame::(vulkan|cuda)::tests::vulkan_cuda_/)' diff --git a/sh/shell.sh b/sh/shell.sh new file mode 100755 index 00000000000..fb6ae022c8b --- /dev/null +++ b/sh/shell.sh @@ -0,0 +1,27 @@ +#!/usr/bin/env bash +# Lint or format every tracked shell script: sh/shell.sh check|fix +set -euo pipefail + +cd "$(git rev-parse --show-toplevel)" + +scripts=() +while IFS= read -r -d '' file; do + if git --literal-pathspecs ls-files --error-unmatch -- "$file" >/dev/null 2>&1; then + scripts+=("$file") + fi +done < <(shfmt -f=0 .) +((${#scripts[@]})) || exit 0 + +case "${1:-}" in + check) + shfmt --diff "${scripts[@]}" + shellcheck "${scripts[@]}" + ;; + fix) + shfmt --write "${scripts[@]}" + ;; + *) + echo "usage: sh/shell.sh check|fix" >&2 + exit 2 + ;; +esac diff --git a/swift/scripts/check.sh b/sh/swift/check.sh similarity index 98% rename from swift/scripts/check.sh rename to sh/swift/check.sh index a05b47cb250..a1330ad4bff 100755 --- a/swift/scripts/check.sh +++ b/sh/swift/check.sh @@ -8,7 +8,7 @@ set -euo pipefail # `cargo`. Intended for `just swift check`. SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -SWIFT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +SWIFT_DIR="$(cd "$SCRIPT_DIR/../../swift" && pwd)" WORKSPACE_DIR="$(cd "$SWIFT_DIR/.." && pwd)" if ! command -v swift >/dev/null 2>&1; then diff --git a/swift/scripts/package-ffi.sh b/sh/swift/package-ffi.sh similarity index 98% rename from swift/scripts/package-ffi.sh rename to sh/swift/package-ffi.sh index 5958c213ae1..8166429c734 100755 --- a/swift/scripts/package-ffi.sh +++ b/sh/swift/package-ffi.sh @@ -12,7 +12,7 @@ set -euo pipefail # Only macOS hosts can run this (xcodebuild is required). # # Usage: -# swift/scripts/package-ffi.sh --version 0.0.0-dev --lib-dir dist --output dist +# sh/swift/package-ffi.sh --version 0.0.0-dev --lib-dir dist --output dist # # --version Version baked into Package.swift (the moq-ffi crate version). # --lib-dir Directory containing per-target moq-ffi outputs. @@ -24,7 +24,7 @@ set -euo pipefail # override when publishing from a fork. SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -SWIFT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +SWIFT_DIR="$(cd "$SCRIPT_DIR/../../swift" && pwd)" WORKSPACE_DIR="$(cd "$SWIFT_DIR/.." && pwd)" VERSION="" diff --git a/swift/scripts/package.sh b/sh/swift/package.sh similarity index 98% rename from swift/scripts/package.sh rename to sh/swift/package.sh index e1d40527192..4d281925ee1 100755 --- a/swift/scripts/package.sh +++ b/sh/swift/package.sh @@ -12,7 +12,7 @@ set -euo pipefail # package depends on at .upToNextMinor(from: ). # # Usage: -# swift/scripts/package.sh --version 0.3.0 --output dist +# sh/swift/package.sh --version 0.3.0 --output dist # # --version Wrapper version (from swift/VERSION). Names the tarball only; # the SPM version comes from the mirror's git tag. @@ -21,7 +21,7 @@ set -euo pipefail # --output Destination directory for the .tar.gz. SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -SWIFT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +SWIFT_DIR="$(cd "$SCRIPT_DIR/../../swift" && pwd)" WORKSPACE_DIR="$(cd "$SWIFT_DIR/.." && pwd)" VERSION="" diff --git a/swift/scripts/publish-ffi.sh b/sh/swift/publish-ffi.sh similarity index 100% rename from swift/scripts/publish-ffi.sh rename to sh/swift/publish-ffi.sh diff --git a/swift/scripts/publish.sh b/sh/swift/publish.sh similarity index 100% rename from swift/scripts/publish.sh rename to sh/swift/publish.sh diff --git a/swift/scripts/verify-ffi.sh b/sh/swift/verify-ffi.sh similarity index 96% rename from swift/scripts/verify-ffi.sh rename to sh/swift/verify-ffi.sh index 65c8f60d851..886fb75c6d9 100755 --- a/swift/scripts/verify-ffi.sh +++ b/sh/swift/verify-ffi.sh @@ -13,8 +13,8 @@ set -euo pipefail # never reaches consumers. # # Usage: -# swift/scripts/verify-ffi.sh --staged-dir -# swift/scripts/verify-ffi.sh --tarball +# sh/swift/verify-ffi.sh --staged-dir +# sh/swift/verify-ffi.sh --tarball # # Exactly one of --staged-dir / --tarball must be passed. diff --git a/swift/scripts/verify.sh b/sh/swift/verify.sh similarity index 96% rename from swift/scripts/verify.sh rename to sh/swift/verify.sh index 865495798d9..6df5a561b59 100755 --- a/swift/scripts/verify.sh +++ b/sh/swift/verify.sh @@ -13,8 +13,8 @@ set -euo pipefail # already published (true on a normal release; a correct failure otherwise). # # Usage: -# swift/scripts/verify.sh --staged-dir -# swift/scripts/verify.sh --tarball +# sh/swift/verify.sh --staged-dir +# sh/swift/verify.sh --tarball # # Exactly one of --staged-dir / --tarball must be passed. diff --git a/swift/.gitignore b/swift/.gitignore index b72f40122ba..40a03d7ac31 100644 --- a/swift/.gitignore +++ b/swift/.gitignore @@ -3,7 +3,7 @@ .swiftpm/ Package.resolved -# Generated by swift/scripts/{check,package}.sh — never check these in. +# Generated by sh/swift/{check,package}.sh — never check these in. Sources/MoqFFI/Generated.swift Tests/MoqTests/Docs/Samples.swift MoqFFI.xcframework/ diff --git a/swift/.spi.yml b/swift/.spi.yml index 0259deae9cc..9fb2ec6db2c 100644 --- a/swift/.spi.yml +++ b/swift/.spi.yml @@ -3,7 +3,7 @@ # served at https://swiftpackageindex.com/moq-dev/moq-swift/documentation. # # This file is copied into the published moq-dev/moq-swift mirror by -# swift/scripts/package.sh, since SPI reads it from the package root. +# sh/swift/package.sh, since SPI reads it from the package root. version: 1 builder: configs: diff --git a/swift/Package.swift b/swift/Package.swift index 97256a74c93..e06be8154a6 100644 --- a/swift/Package.swift +++ b/swift/Package.swift @@ -1,9 +1,9 @@ // swift-tools-version:5.9 -// Local-development manifest. swift/scripts/check.sh builds a single-slice +// Local-development manifest. sh/swift/check.sh builds a single-slice // MoqFFI.xcframework next to this file so the path-based binaryTarget below // resolves locally without a network fetch. // -// The released form (URL + checksum) is generated by swift/scripts/package.sh +// The released form (URL + checksum) is generated by sh/swift/package.sh // from Package.swift.template at release time. Edit the template, not this // file, when changing the released manifest. diff --git a/swift/Package.swift.template b/swift/Package.swift.template index 0cdfbf06060..f6339a07a8d 100644 --- a/swift/Package.swift.template +++ b/swift/Package.swift.template @@ -1,7 +1,7 @@ // swift-tools-version:5.9 // Released manifest for the ergonomic wrapper at moq-dev/moq-swift. The // source-of-truth template lives at swift/Package.swift.template in -// moq-dev/moq; swift/scripts/package.sh substitutes the moq-ffi version pin +// moq-dev/moq; sh/swift/package.sh substitutes the moq-ffi version pin // (REPLACE_FFI_VERSION) at release time. // // The wrapper versions independently of the bindings (see swift/VERSION). The diff --git a/swift/README.md b/swift/README.md index 766f1ff96ec..613831a5810 100644 --- a/swift/README.md +++ b/swift/README.md @@ -83,7 +83,7 @@ is an `AsyncSequence` of the decoded type. Pass matching `compression` on both s ## Local development -`swift/scripts/check.sh` builds `moq-ffi` for the host, regenerates the UniFFI Swift bindings, builds a single-slice `MoqFFI.xcframework`, and runs `swift test`, which also compiles every Swift sample in this README and `doc/lib/swift`, extracted by `doc/lib/samples.sh`. Requires macOS with `xcodebuild` and `swift` on `$PATH`. Run via `just swift check`; skips cleanly on non-macOS hosts. +`sh/swift/check.sh` builds `moq-ffi` for the host, regenerates the UniFFI Swift bindings, builds a single-slice `MoqFFI.xcframework`, and runs `swift test`, which also compiles every Swift sample in this README and `doc/lib/swift`, extracted by `doc/lib/samples.sh`. Requires macOS with `xcodebuild` and `swift` on `$PATH`. Run via `just swift check`; skips cleanly on non-macOS hosts. Local development uses one **monolithic** `Package.swift` containing both the `Moq` and `MoqFFI` targets plus the path-based XCFramework, so `swift test` and Xcode work against a single package. The split into two packages exists only in the released artifacts, assembled from the two templates below at release time. Because the FFI module is named `MoqFFI` in both layouts, the wrapper sources (`import MoqFFI`) compile identically either way. @@ -99,7 +99,6 @@ swift/ Moq/ Ergonomic wrapper (Client, Server, Origin, Broadcast, Track, Media, Audio, …) MoqFFI/ UniFFI-generated swift (populated by check.sh/package-ffi.sh, gitignored) Tests/MoqTests/ Smoke tests - scripts/ check.sh, package{,-ffi}.sh, verify{,-ffi}.sh, publish{,-ffi}.sh ``` Edit the templates when changing a released manifest; never copy the monolithic dev-mode form into the release path. @@ -118,8 +117,8 @@ To release a new wrapper version: bump `swift/VERSION` in a PR. On merge, `relea To dry-run a publish locally against a staged tarball: ```bash -BUILD_VERSION= ./swift/scripts/publish.sh --dry-run # wrapper -> moq-swift -BUILD_VERSION= ./swift/scripts/publish-ffi.sh --dry-run # bindings -> moq-swift-ffi +BUILD_VERSION= ./sh/swift/publish.sh --dry-run # wrapper -> moq-swift +BUILD_VERSION= ./sh/swift/publish-ffi.sh --dry-run # bindings -> moq-swift-ffi ``` No Apple Developer account or App Store Connect setup needed. diff --git a/swift/Tests/MoqTests/Docs/Prelude.swift b/swift/Tests/MoqTests/Docs/Prelude.swift index 7be98118e6e..f900542855a 100644 --- a/swift/Tests/MoqTests/Docs/Prelude.swift +++ b/swift/Tests/MoqTests/Docs/Prelude.swift @@ -1,4 +1,4 @@ -// The inputs the documentation samples leave to the reader. swift/scripts/check.sh +// The inputs the documentation samples leave to the reader. sh/swift/check.sh // compiles every Swift sample in the docs beside this file, so a sample that // names a missing symbol or the wrong labels fails the check. Never executed. import Foundation diff --git a/swift/ffi/Package.swift.template b/swift/ffi/Package.swift.template index d66fb3d01b6..55588ffc092 100644 --- a/swift/ffi/Package.swift.template +++ b/swift/ffi/Package.swift.template @@ -1,7 +1,7 @@ // swift-tools-version:5.9 // Released manifest for the raw UniFFI bindings package at moq-dev/moq-swift-ffi. // The source-of-truth template lives at swift/ffi/Package.swift.template in -// moq-dev/moq; swift/scripts/package-ffi.sh substitutes the xcframework URL and +// moq-dev/moq; sh/swift/package-ffi.sh substitutes the xcframework URL and // SHA-256 (REPLACE_URL / REPLACE_CHECKSUM) at release time. // // Lockstep with the moq-ffi Rust crate: each moq-ffi-v* tag publishes a matching diff --git a/swift/justfile b/swift/justfile index 8ab3c71bf91..075ae923142 100644 --- a/swift/justfile +++ b/swift/justfile @@ -9,29 +9,47 @@ default: just check # Skips cleanly on non-macOS hosts, which is why swift.yml runs it on a Mac. -# -# This runs the tests too, so there is no separate `just swift test`. Takes an -# optional newline-separated list of changed files and skips when none are -# Swift-scoped; `just swift check` (no FILES) always runs. +# This runs the tests too, so there is no separate `just swift test`. # Build moq-ffi for the host, regenerate uniffi bindings, run swift test. -check $FILES="": - #!/usr/bin/env bash - set -euo pipefail - if [[ -n "$FILES" ]] && ! grep -qE '^(swift/|rs/moq-ffi/|doc/lib/swift/|doc/lib/samples\.sh$)' <<< "$FILES"; then - echo "swift: no Swift changes; skipping." - exit 0 - fi - bash scripts/check.sh +check: + bash ../sh/swift/check.sh -# Assemble the released wrapper package from Package.swift.template. +# Release recipes run in the caller's directory, so a relative `--output` or +# `--tarball` means what it would to the script itself. -# Used by .github/workflows/release-swift-lib.yml. +# Assemble the released wrapper package from Package.swift.template. +[no-cd] +[positional-arguments] package *args: - bash scripts/package.sh {{ args }} - -# Remove SwiftPM build output plus the XCFramework and generated bindings - -# that scripts/check.sh lays down (see swift/.gitignore). -clean: - rm -rf .build .swiftpm Package.resolved Sources/MoqFFI/Generated.swift MoqFFI.xcframework + {{ quote(justfile_directory() / "sh/swift/package.sh") }} "$@" + +# Assemble the MoqFFI package from per-target static libs and the generated bindings. +[no-cd] +[positional-arguments] +package-ffi *args: + {{ quote(justfile_directory() / "sh/swift/package-ffi.sh") }} "$@" + +# Build a throwaway consumer of a staged wrapper package. +[no-cd] +[positional-arguments] +verify *args: + {{ quote(justfile_directory() / "sh/swift/verify.sh") }} "$@" + +# Build a throwaway consumer of a staged MoqFFI package. +[no-cd] +[positional-arguments] +verify-ffi *args: + {{ quote(justfile_directory() / "sh/swift/verify-ffi.sh") }} "$@" + +# Push the staged wrapper package to the moq-dev/moq-swift mirror. +[no-cd] +[positional-arguments] +publish *args: + {{ quote(justfile_directory() / "sh/swift/publish.sh") }} "$@" + +# Push the staged MoqFFI package to the moq-dev/moq-swift-ffi mirror. +[no-cd] +[positional-arguments] +publish-ffi *args: + {{ quote(justfile_directory() / "sh/swift/publish-ffi.sh") }} "$@" diff --git a/test/README.md b/test/README.md index ae54517fa27..968b286777b 100644 --- a/test/README.md +++ b/test/README.md @@ -88,25 +88,3 @@ with the `rm -rf` the run prints; nothing expires it for you. In CI the harness writes under `MOQ_TEST_RUNS`, and `interop.yml` and `wasm.yml` upload that directory as a short-lived artifact when the job fails. - -## Worktrees - -`just worktree` reports what a checkout can actually do before anything is built: -its base and how stale that base is, and whether the Git metadata is reachable for -fetch, branch creation, and rebase. A linked worktree keeps its shared metadata -under `--git-common-dir`, inside the main repository, so write access to the -source tree does not imply any of the three. - -```bash -just worktree # report, change nothing -just worktree setup # fetch, set the branch upstream, record the base SHA -``` - -`setup` never resets, rebases, or cleans, so it is safe to run against a checkout -with work in progress. - -The upstream is the only place the base survives, so `setup BASE` fails when it -cannot be written -- a detached HEAD has no branch to hang it on, and the shared -config may be read-only. Left as a warning, `just check` would go on scoping -against `origin/main` while setup reported success. Without a `BASE`, that -fallback is what would have been written anyway, so it warns instead. diff --git a/test/interop/README.md b/test/interop/README.md index 3d961b65ad7..8d862ba42e5 100644 --- a/test/interop/README.md +++ b/test/interop/README.md @@ -29,7 +29,7 @@ player survive the publication lifecycle. See [Media QA](#media-qa). |---|---|---|---| | Rust | `rs/moq-relay` + `rs/moq-cli` | `cargo build` | publish (video) + subscribe | | Python | `py/moq-rs` (+ `rs/moq-ffi`, import `moq`) | `uv build` wheels (maturin + hatchling), installed into a venv in the run directory | publish (video + audio) + subscribe | -| Go | `go/wrapper` (+ `rs/moq-ffi`, import `moq-go/moq`) | `go/scripts/stage.sh` (uniffi-bindgen-go) + `go build` | publish (video + audio) + subscribe | +| Go | `go/wrapper` (+ `rs/moq-ffi`, import `moq-go/moq`) | `sh/go/stage.sh` (uniffi-bindgen-go) + `go build` | publish (video + audio) + subscribe | | Browser | `js/watch` + `js/publish` | `vite build` + headless Chromium (Playwright) | publish (video + audio) + rendered playback | | Native JS | `js/net` + `js/hang` + the npm `@moq/web-transport` polyfill | `node` (tsx) and `bun` | subscribe | | C | `rs/libmoq` | `cargo build -p libmoq` + `cc` | subscribe | @@ -40,7 +40,7 @@ The browser, native JS, C, and GStreamer clients subscribe only by choice intentionally minimal, and `moqsink` publishing needs request-pad muxing this client doesn't drive). Rust, Python, Go, and the browser publish. -The Go client builds against the modules `go/scripts/stage.sh` assembles from +The Go client builds against the modules `sh/go/stage.sh` assembles from this checkout: `moq-ffi` compiled for the host, bindings regenerated with `uniffi-bindgen-go`, and the `go/wrapper` module wired to them by a `replace`. That is the same staging `just go check` uses, so this cell covers the Go diff --git a/test/interop/clients/go/go.mod b/test/interop/clients/go/go.mod index a57ce62b534..bd1ae2e2045 100644 --- a/test/interop/clients/go/go.mod +++ b/test/interop/clients/go/go.mod @@ -1,6 +1,6 @@ // Not a published module. test/interop/interop.sh builds this out of a scratch copy // and rewrites the require below into a `replace` pointing at the wrapper that -// go/scripts/stage.sh assembles from this checkout, so nothing resolves from the +// sh/go/stage.sh assembles from this checkout, so nothing resolves from the // module proxy. The placeholder version keeps the committed file honest: there // is no such tag, and there is no go.sum because every dependency is local. module moq.dev/interop diff --git a/test/interop/interop.sh b/test/interop/interop.sh index 0b7a45a1e6a..166257d7ae8 100755 --- a/test/interop/interop.sh +++ b/test/interop/interop.sh @@ -80,6 +80,14 @@ while [[ $# -gt 0 ]]; do MEDIA=1 shift ;; + # The full matrix. --timeout 30 gives headless Chromium cold-start + # headroom; flags after it still override. + --all) + PUBLISHERS="rust,python,go,js" + SUBSCRIBERS="rust,python,go,js,js-native-node,js-native-bun,c,gst" + TIMEOUT=30 + shift + ;; *) echo "unknown arg: $1" >&2 exit 2 @@ -250,7 +258,7 @@ prepare_js() { fi } -# Stage the Go modules from this checkout (go/scripts/stage.sh builds moq-ffi for +# Stage the Go modules from this checkout (sh/go/stage.sh builds moq-ffi for # the host, regenerates the bindings, and wires the wrapper to them by replace), # then build the interop client against that exact tree. The client is copied to a # scratch dir first so the committed go.mod keeps its placeholder require; every @@ -266,8 +274,8 @@ prepare_go() { } echo "building go client (workspace moq-go via uniffi-bindgen-go)..." local staged ffi_pkg wrapper_pkg src="$HARNESS_RUN/go-client" - if ! staged=$(bash "$WORKSPACE/go/scripts/stage.sh" --output "$HARNESS_RUN/go-stage" 2>"$HARNESS_RUN/go-stage.log"); then - mark_broken go "go/scripts/stage.sh failed" + if ! staged=$(bash "$WORKSPACE/sh/go/stage.sh" --output "$HARNESS_RUN/go-stage" 2>"$HARNESS_RUN/go-stage.log"); then + mark_broken go "sh/go/stage.sh failed" sed 's/^/ /' "$HARNESS_RUN/go-stage.log" >&2 || true return fi diff --git a/test/justfile b/test/justfile index d98acad97df..4b466640516 100644 --- a/test/justfile +++ b/test/justfile @@ -3,9 +3,6 @@ # Tests that span more than one language or need a live relay. Unit tests run # in the root `just check`. # -# Shebang recipes read their arguments as $1..$n. -set positional-arguments - # Two cross-language interop tests exist: # - https://github.com/moq-dev/smoke installs each client from its PUBLIC # package registry to catch packaging breakage in a release. @@ -15,8 +12,6 @@ set positional-arguments set fallback set working-directory := '.' -# `interop` reads its args as `$1`/`$@`; the `positional-arguments` setting above -# is what lets a shebang recipe see them. # List the cross-language suites. default: @@ -35,27 +30,21 @@ harness: # relay and runs the publisher x subscriber matrix. Default: rust only (fast # sanity check). `interop --all` runs the full matrix: rust + python + go + # browser publish; everyone subscribes (incl. native node/bun JS, the C libmoq -# client, and the GStreamer moqsrc plugin). --timeout 30 gives headless Chromium -# cold-start headroom. Other flags pass through, e.g. +# client, and the GStreamer moqsrc plugin). Other flags pass through, e.g. # `just test interop --publishers rust,python --subscribers rust,c`. # Both runs first check js/net's varints against moq-net's encoder at every size boundary, # and on lite-06/07 messages (the filter also matches `lite_varint_interop`). +[positional-arguments] interop *args: - #!/usr/bin/env bash - set -euo pipefail just rs test -p moq-net --lib varint_interop --run-ignored all - if [[ "${1:-}" == --all ]]; then - shift - ./interop/interop.sh --publishers rust,python,go,js --subscribers rust,python,go,js,js-native-node,js-native-bun,c,gst --timeout 30 "$@" - else - ./interop/interop.sh "$@" - fi + ./interop/interop.sh "$@" # Negative control: no publisher, every subscriber must time out (proves the # harness can actually report failure). +[positional-arguments] interop-negative *args: - ./interop/interop.sh --negative {{ args }} + ./interop/interop.sh --negative "$@" # Browser-to-browser media QA against a deterministic fixture: presented frame progress, audible # tone, audio/video skew, and the publication lifecycle (cold start, pause, rejoin, detach, @@ -63,8 +52,9 @@ interop-negative *args: # shifted tone, and a leaked session; each must fail the assertion it names. --timeout 30 gives # headless Chromium cold-start headroom. +[positional-arguments] media *args: - ./interop/interop.sh --media --timeout 30 {{ args }} + ./interop/interop.sh --media --timeout 30 "$@" # Disrupts a real relay over real QUIC three ways: cancel a stalled reader, kill # the relay mid-group, and republish an interrupted publisher's name. Ordinary @@ -73,16 +63,18 @@ media *args: # no-publisher negative control. See drill/README.md. # Transport and lifecycle failure drills. +[positional-arguments] drill *args: - just rs test -p moq-relay --test drills {{ args }} + just rs test -p moq-relay --test drills "$@" # Removes one recovery behavior at a time in a disposable copy of the tree and # requires the drill covering it to fail, for the reason the mutation names. The # checkout is never modified. `--list` shows the mutations. # Prove the drills fail without the fixes they cover. +[positional-arguments] drill-sensitivity *args: - ./drill/sensitivity.sh {{ args }} + ./drill/sensitivity.sh "$@" # Round-trips a PCR-paced TS through a relay and checks the subscriber's `export # ts` output with TSDuck plus a custom analyzer (PCR jitter/repetition, @@ -94,21 +86,24 @@ drill-sensitivity *args: # ts/README.md. # Check the subscriber's MPEG-TS output for IRD compliance. +[positional-arguments] ts *args: - ./ts/run.sh {{ args }} + ./ts/run.sh "$@" # Round-trip the EIT fixtures: the sparse schedule must survive and # pending-version sections must be dropped at import. +[positional-arguments] ts-eit *args: - ./ts/eit-roundtrip.sh {{ args }} + ./ts/eit-roundtrip.sh "$@" # Runs the @moq/wasm bindings in headless Chromium against a real relay, one per # protocol flavour. The crate is `#![cfg(target_arch = "wasm32")]`, so nothing in # `just check` or `just rs wasm` gets past compiling it. See wasm/README.md. # Browser coverage for the @moq/wasm bindings. +[positional-arguments] wasm *args: - ./wasm/run.sh {{ args }} + ./wasm/run.sh "$@" # Cross-language subscription termination over in-memory transports. bare-fin: diff --git a/test/wasm/README.md b/test/wasm/README.md index a65cb85dd8a..7e20248ccf6 100644 --- a/test/wasm/README.md +++ b/test/wasm/README.md @@ -21,7 +21,7 @@ just test wasm just test wasm --timeout 60 ``` -Everything is built from this checkout: `just wasm` for the bindings, `cargo +Everything is built from this checkout: `just js wasm` for the bindings, `cargo build -p moq-relay` for the relay. Each relay reserves its own port (see [the harness contract](../README.md)); `WASM_PORT` pins the first one instead. `WASM_PROFILE` picks the relay's cargo profile, and `RELAY_BIN` points at a diff --git a/test/wasm/run.sh b/test/wasm/run.sh index e2e649743e5..71ed51ba538 100755 --- a/test/wasm/run.sh +++ b/test/wasm/run.sh @@ -92,7 +92,7 @@ command -v wasm-bindgen >/dev/null 2>&1 || { # ── build ─────────────────────────────────────────────────────────────────── echo "building @moq/wasm..." -(cd "$WORKSPACE" && just wasm) +(cd "$WORKSPACE" && just js wasm) echo "building moq-relay ($PROFILE)..." flag=() From 603b973b41a53be3884dad66ca05e2a89f95fa55 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 09:11:44 -0700 Subject: [PATCH 106/128] quest(m1): split cluster routing into child quests (#4592) Co-authored-by: Claude Opus 5.5 --- quest/m0/remove-gossip.md | 2 +- quest/m0/wildcard/README.md | 2 +- quest/m1/README.md | 5 +- quest/m1/broadcast-epoch/README.md | 7 +- quest/m1/cluster-idle-timeout.md | 29 +++ quest/m1/cluster-routing/README.md | 251 +++++++++------------- quest/m1/cluster-routing/hop-removal.md | 45 ++++ quest/m1/cluster-routing/inter-cluster.md | 40 ++++ quest/m1/cluster-routing/memory.md | 46 ++++ quest/m1/cluster-routing/propagation.md | 73 +++++++ quest/m1/cluster-routing/selection.md | 72 +++++++ quest/m1/cluster-routing/topology.md | 61 ++++++ quest/m1/hop-aligned-import.md | 8 +- quest/m3/routing-cost-domains.md | 2 +- 14 files changed, 482 insertions(+), 161 deletions(-) create mode 100644 quest/m1/cluster-idle-timeout.md create mode 100644 quest/m1/cluster-routing/hop-removal.md create mode 100644 quest/m1/cluster-routing/inter-cluster.md create mode 100644 quest/m1/cluster-routing/memory.md create mode 100644 quest/m1/cluster-routing/propagation.md create mode 100644 quest/m1/cluster-routing/selection.md create mode 100644 quest/m1/cluster-routing/topology.md diff --git a/quest/m0/remove-gossip.md b/quest/m0/remove-gossip.md index ecf38db9b70..80b0635a49f 100644 --- a/quest/m0/remove-gossip.md +++ b/quest/m0/remove-gossip.md @@ -40,4 +40,4 @@ announcing `.internal/origins`. ## Related -- [Cluster routing](/quest/m1/cluster-routing/README.md) - takes its topology from configured links only +- [Cluster topology](/quest/m1/cluster-routing/topology.md) - takes its topology from configured links only, so it waits on this diff --git a/quest/m0/wildcard/README.md b/quest/m0/wildcard/README.md index 0b106cd870b..a41beec582e 100644 --- a/quest/m0/wildcard/README.md +++ b/quest/m0/wildcard/README.md @@ -24,7 +24,7 @@ is the catch-all `**`, a claim about every path at once. The cost of enumerating is real even though its last measurement is stale. One announcement measured 8.8 KB per relay plus 4.3 KB per additional route before prefix routes made a standby route a table entry; -[Cluster routing](/quest/m1/cluster-routing/README.md) owns remeasuring it. Whatever the current +[Cluster routing's memory benchmark](/quest/m1/cluster-routing/memory.md) remeasures it. Whatever the current number, every relay that hears an announcement pays it whether or not anything there subscribes, so "workers times broadcasts" is that number multiplied across the fleet in resident memory. diff --git a/quest/m1/README.md b/quest/m1/README.md index 2d5a98509e4..027063f5eea 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -22,7 +22,8 @@ QUIC studies there on that rule. ## Required -- [Cluster routing](/quest/m1/cluster-routing/README.md) - an announcement says where a broadcast originates, not how to reach it, and a relay hears only the prefixes its clients asked for +- [Cluster idle timeout](/quest/m1/cluster-idle-timeout.md) - a relay notices a silent peer relay within seconds, not after the shared 30 s QUIC idle timeout +- [Cluster routing](/quest/m1/cluster-routing/README.md) - a relay learns the relay graph once and each announcement once, not once per neighbour, and redundant publishers share an epoch instead of `--hop` - [Track tail interop](/quest/m1/track-tail-interop.md) - a Rust publisher ending a track with a group in flight is read to its end by the JS subscriber, and the reverse, in `just test interop` - [Merge queue](/quest/m1/merge-queue.md) - the required checks run on `merge_group`, so a stale green check can no longer break main - [Binding audio delay](/quest/m1/binding-surface.md) - moq-ffi and every wrapper configure and observe audio playout delay @@ -52,7 +53,7 @@ QUIC studies there on that rule. - [TS damaged units](/quest/m1/ts-damaged-units.md) - one malformed PES or access unit is dropped, counted as `damaged`, and resynced at the next keyframe instead of ending the import - [RTMP interleaving](/quest/m1/rtmp-interleaving.md) - isolate partial messages before optimizing assembly copies - [TS stats module](/quest/m1/ts-stats-module.md) - on dev, the TS stats types move under `ts::stats` as `Snapshot` and `Stream`, with an owned `track` -- [Same-hop importers](/quest/m1/hop-aligned-import.md) - importers sharing a `--hop` and fed one stream publish identical groups and timestamps, so failover survives +- [Same-hop importers](/quest/m1/hop-aligned-import.md) - importers fed one stream publish identical groups and timestamps, so failover between a redundant pair survives - [Audio capture without ALSA link](/quest/m1/capture-alsa-link.md) - moq-audio capture and playback build on Linux without linking libasound - [Capture by default](/quest/m1/capture-default.md) - moq-video and moq-audio build `capture` by default, so pre-merge checks test it and the capture gate goes away - [Ship capture and playback](/quest/m1/cli-packaging.md) - a released moq binary can capture and play, which no distribution currently enables diff --git a/quest/m1/broadcast-epoch/README.md b/quest/m1/broadcast-epoch/README.md index f32738ce2b1..3f8b69c8572 100644 --- a/quest/m1/broadcast-epoch/README.md +++ b/quest/m1/broadcast-epoch/README.md @@ -14,9 +14,10 @@ The epoch rides in the path, so it survives any moq-transport relay, and no wire message changes. At an epoch-aware relay, a request for a bare name resolves to its newest live epoch on every protocol version. -Non-goals: redundant publishers sharing one epoch, and failing over between -them faster than the keep-alive (a question -[Cluster routing](/quest/m1/cluster-routing/README.md) owns). Also out of scope: trusting the publisher's clock (a far-future epoch +Non-goals: pooling redundant publishers that share one epoch, which +[Cluster routing](/quest/m1/cluster-routing/README.md)'s selection and +`--hop` removal own; this line only keeps an epoch a caller supplies. Also out +of scope: trusting the publisher's clock (a far-future epoch wins until its route goes away). ## Plan diff --git a/quest/m1/cluster-idle-timeout.md b/quest/m1/cluster-idle-timeout.md new file mode 100644 index 00000000000..5bbf7d739b8 --- /dev/null +++ b/quest/m1/cluster-idle-timeout.md @@ -0,0 +1,29 @@ +# [S] Cluster idle timeout + +## Goal + +A relay notices a silent peer relay within seconds, not after the 30 s QUIC +idle timeout it shares with every viewer. moq.pro's routing simulator found +that failure detection, not routing, sets every outage window: a silent link +or relay loss goes unnoticed for the idle timeout in every routing design, +and subscribes through it go nowhere meanwhile. + +## Plan + +- Cluster sessions get their own idle timeout and keep-alive, shorter than + the `--quic-*` defaults (`rs/moq-tokio/src/quic.rs`, 30 s idle and 5 s + keep-alive). A keep-alive alone only keeps a quiet session open; the + timeout is what detects loss. +- QUIC's effective idle timeout is the smaller of the two endpoints' + (RFC 9000 section 10.1), so the dialing relay's setting bounds both sides of + a cluster link. Say so where the setting is documented. +- Pick the default in the PR with its reasoning: loss detection against + spurious drops on a lossy intercontinental link. +- Docs: `doc/bin/relay/cluster.md` and `doc/bin/relay/config.md`. + +Public API: adds a relay config field; lands on `main`. + +## Related + +- [Cluster routing](/quest/m1/cluster-routing/README.md) - its liveness and failover depend on this detection +- [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - viewers wait out the same timeout for an old route diff --git a/quest/m1/cluster-routing/README.md b/quest/m1/cluster-routing/README.md index 821bd5f0805..ee1ec30ac98 100644 --- a/quest/m1/cluster-routing/README.md +++ b/quest/m1/cluster-routing/README.md @@ -1,29 +1,63 @@ -# [XL] Cluster routing +# Cluster routing ## Goal -A broadcast event reaches each relay at most once, and a relay learns only the -prefixes its own clients asked for. An announcement says a path exists at an -origin relay, at a cost; how to reach that origin comes from a shared relay -topology, so no announcement inside a cluster carries a hop list. A relay's -memory scales with what it serves, not with what the mesh knows. This -questline records the design; its wire and implementation quests are planned -from the simulator's report. +Cut cluster gossip. A relay learns how to reach each other relay once, from +a topology shared across the cluster rather than repeated in every route, +and learns each announcement once rather than once per neighbour. Every relay +still holds the ledger of live announcements that ANNOUNCE_REQUEST and a cold +SUBSCRIBE need, and a broadcast under overlapping prefixes routes to one +origin deterministically. Redundancy an operator configures may deliver more +than one copy. Non-goals: warm re-origination (a warm relay would be one more origin with a cost, so leave room for it), and a permanently mixed-version cluster. ## Plan -This is a questline with no children yet. Its children (wire and -implementation) are planned next in a separate `/quest-plan` session, from -the decisions and open questions below. +### Decisions + +Settled in the 2026-09-30 `/quest-plan`: + +- The goal stays wide. The design below is the current candidate, not a + decision; [Propagation](/quest/m1/cluster-routing/propagation.md) settles + how announcements move and writes the implementation children that follow. +- Topology is a cluster message kept apart from routes, built from configured + links only (`--cluster-connect`, the connect API, LAN mDNS). Gossip + discovery goes first, but only the topology child waits on it. +- Every relay holds a record for every live announcement, since + ANNOUNCE_REQUEST and a SUBSCRIBE with no prior announce both need one. + Scoping that knowledge by demand needs registries, which Propagation may + defer to m2. +- `--hop` goes. An epoch-qualified concrete path (`foo/@`) is the + identity of a source: origins that announce the same one are + interchangeable, which is how a redundant pair is expressed. It is strictly + better than a Hop ID, which is per session, so a connection could not + publish several broadcasts with different identities. A path a claim + produces keeps Wildcard's per-origin identity, even once announced + concretely, since each worker's output is its own. +- The line lands on `dev`: deleting `--hop` and the publisher's Hop setup + parameter breaks a published CLI and wire. Wire changes go in the current + wip version (`moq-lite-07-wip` today, dropping `Hop Base` and `Hop Keep` + before they publish). If lite-07 is finalized first for the Wildcard + rollout, the remaining children move to the next wip version; finalizing + never waits on this line. +- The before/after memory figure is a committed benchmark, measured first. +- A short idle timeout for cluster sessions is its own m1 quest, + [Cluster idle timeout](/quest/m1/cluster-idle-timeout.md), since it helps + today's path vector too. +- Reduced flooding ([RFC 9667](https://www.rfc-editor.org/rfc/rfc9667)) and + registries are m2 unless Propagation pulls registries in; Propagation writes + whichever it defers. +- Between clusters, announcements stay path vector with cluster ids as hops, + in the last child. ### Why not path vector or Babel Today every relay advertises its best route to every peer not already in the -hop chain. One publish costs about R·(d-1) announces for R relays of mesh -degree d, every relay learns every broadcast (`.stats` and `.internal` +hop chain, and pulls every peer's full table with an empty-prefix +ANNOUNCE_REQUEST. One publish costs about R·(d-1) announces for R relays of +mesh degree d, every relay learns every broadcast (`.stats` and `.internal` included), and a link change rewrites every route crossing it. On moq.pro's live fleet (26 PoPs, average degree about 5) each relay receives every event about five times. Babel ([RFC 8966](https://www.rfc-editor.org/rfc/rfc8966)) @@ -42,7 +76,12 @@ the loops. Hiding the routes through a peer that withdrew the path ([#4399](https://github.com/moq-dev/moq/pull/4399)) reduces that path hunting but does not end it; see the findings below. -### Decisions +### Candidate design + +The children own their parts: topology in +[Topology](/quest/m1/cluster-routing/topology.md), existence and registries +in [Propagation](/quest/m1/cluster-routing/propagation.md), origin choice in +[Selection](/quest/m1/cluster-routing/selection.md). - Existence is split from reachability. An announcement carries the path, its origin relay, and the origin's cost, and nothing about the path to it. @@ -59,76 +98,28 @@ but does not end it; see the findings below. dropped. Purging on a liveness report instead drops a restarted origin's broadcasts until their re-announce lands, which the simulator showed as live broadcasts reported offline. -- The topology is configured: `--cluster-connect` or the connect API gives the - relay graph and link costs. Relays flood per-link liveness among themselves - with a per-link seqno. The seqno is scoped to the relay's incarnation, so a - restarted relay's links supersede its stale ones instead of looking older. - Configured links are the only source: gossip discovery is removed by - [Remove gossip](/quest/m0/remove-gossip.md), and LAN mDNS dials peers - that then count as configured links. - - A relay batches the liveness reports it sends, its own and those it - forwards, for a short hold-down (50 ms in the simulator), and recomputes - its trees after a matching delay, as OSPF's SPF delay does. Unbatched, one - relay restart at 340 relays sent half a million messages; batched, 27k. - - On session up, relays exchange a digest (each reporter's incarnation and - its seqno per link) and send only what the other lacks. A reporter's - reports flood separately, so its newest seqno alone would hide a missing - older one. The digest already counts the fresh report of the link that - just came up; sending the database first replays the relay's own report - from when the link went down, and the peer drops the link it is using. +- Relays flood per-link liveness among themselves with a per-link seqno scoped + to the relay's incarnation, batched for a short hold-down, with a digest + exchange on session up. - A relay picks the origin with the lowest shortest-path distance plus origin cost, ties broken by rendezvous hashing (HRW) of the requested path and the - origin id, and forwards along its shortest path. Distance compares cost, - then hop count, so every hop strictly shortens it even across `?cost=0` - links. That is a shortest path to a virtual node linked to every origin, so - it is loop-free whenever relays agree on the topology. The longest covering + origin id, and forwards along its shortest path. The longest covering prefix still ranks first, per [Wildcard](/quest/m0/wildcard/README.md). The - simulator saw no loop while views agreed, and HRW split an equal-cost pool - 63/49 where today's hash of the announced prefix sends all of it to one - sibling. -- The first relay's choice rides the SUBSCRIBE, and transit relays forward - toward that origin by topology alone, never re-selecting. Re-selection - against another existence view loops: a relay that lost a specific claim - falls back to a broader one through a relay still routing to the specific - one ([RFC 8966 section 3.5.4](https://www.rfc-editor.org/rfc/rfc8966#section-3.5.4)). - If the origin no longer serves the path, it refuses, and the first relay - selects again. -- SUBSCRIBE and FETCH carry a visited-relay list end to end. It catches loops - while liveness views disagree and names the path for stats. Narrowing it to - cluster hops is later work. The serving origin's identity rides the reply, - per Wildcard's Spread quest. On live's graph no disagreement looped across - 20 seeds of link, cost, and relay churn; the list is a safety net. -- Announcements are on demand. A relay forwards only the union of its clients' - ANNOUNCE_REQUEST prefixes, never the empty prefix. A wide prefix that many - edges' viewers request is that customer's cost. `.stats` becomes ordinary - demand. + first relay's choice rides the SUBSCRIBE, and transit relays forward toward + that origin by topology alone. SUBSCRIBE and FETCH carry a visited-relay + list as a loop safety net. +- Announcements to clients are on demand: a relay forwards only the union of + its clients' ANNOUNCE_REQUEST prefixes. `.stats` becomes ordinary demand. - Registries are an optional, configured tier: moq-relay in a registry mode, - one or more per region. - - An ingest relay registers its broadcasts with its nearest registry, and an - edge sends its ANNOUNCE_REQUEST there. - - Registries form a small full mesh and flood existence among themselves, so - an event crosses an ocean once per remote registry, not once per relay. - Announce latency is about one round trip to the nearest registry, - whatever the path length. - - A relay fails over to the next-nearest registry and reconciles its view - instead of treating the lost session as ends, so a registry failure never - reports a live broadcast offline. - - The reconcile is the relay's full live set at its current seqno, which - ends whatever it leaves out. The registry's snapshot carries each - relevant origin's last reconcile seqno, and the relay names the origins it - already holds, so a view kept through a freeze ends what ended meanwhile. - - With no registry reachable, a relay freezes: it keeps its view, learns - nothing new, and alerts. Falling back to flooding would cascade the - failure. -- Without registries (self-hosting), existence floods along the shortest-path - tree, one copy per relay. A relay forwards an event only when it changes its - view, so a duplicate copy, from trees built on disagreeing liveness, stops - there. A relay that gains a child in its tree (a view change or a new - session) pushes that origin's reset and records to it; without the push a - relay misses events while views disagree. -- Between clusters, announcements stay path vector with cluster ids as the - hops, like BGP between autonomous systems. A customer's on-prem cluster is - one hop, and an announcement naming the receiving cluster is dropped. + one or more per region. Registries form a small full mesh and flood + existence among themselves, so an event crosses an ocean once per remote + registry. A relay fails over to the next-nearest registry and reconciles; + with none reachable it freezes its view and alerts rather than falling back + to flooding. +- Without registries, existence floods along the shortest-path tree, one copy + per relay. A relay forwards an event only when it changes its view, and a + relay that gains a child in its tree pushes that origin's reset and records + to it. - The cluster switches versions as a whole; older lite and IETF sessions stay at its edges. @@ -138,7 +129,7 @@ The report is moq.pro's `just rs sim` (every scenario on live's graph) and `just rs sim sweep` (synthetic regional graphs of 34, 340, and 1020 relays). It carries messages and bytes by kind, per relay and cross-region, convergence, loop, stall, and failover windows, and state per relay and per -registry. What decides the wire: +registry. - Existence costs about one message per relay per event flooded, and one per interested relay plus one per remote registry with registries. On live, a @@ -150,13 +141,16 @@ registry. What decides the wire: loss and restore plus a relay loss and restart cost about 290 MiB of liveness flooding and 54 MiB of session-up digests against under 1 MiB of existence for twenty publishes, while a publish costs exactly one message - per relay. A reduced flooding topology - ([RFC 9667](https://www.rfc-editor.org/rfc/rfc9667)) is the known fix for - the flooding. + per relay. +- Unbatched, one relay restart at 340 relays sent half a million liveness + messages; batched for 50 ms, 27k. - Failure detection, not routing, sets every outage window: a silent link or relay loss is noticed after the 30 s QUIC idle timeout in every candidate, - and subscribes through it go nowhere until then. Cluster sessions need a - short idle timeout; a keepalive only keeps a quiet session open. + and subscribes through it go nowhere until then. +- The simulator saw no loop while views agreed, and HRW split an equal-cost + pool 63/49 where today's hash of the announced prefix sends all of it to one + sibling. On live's graph no disagreement looped across 20 seeds of link, + cost, and relay churn. - One registry per region and two cost about the same; two halves the busiest registry's load. A registration sent on a dead registry session that nobody has noticed yet waits for the failover. @@ -172,76 +166,31 @@ registry. What decides the wire: the same scenario costs 18.6M messages instead of 189k. Per-origin seqnos, above, end both. -### Memory before and after - -On-demand announcements bound the route table by demand; measure that saving -before and after the implementation lands. Keep two costs apart: the route -table and per-announcement state (`RouteEntry` plus `ServeState`) scale with -announcements and routes, while the served-content cache a `ServeState` -materializes scales with demand. - -Every published figure is stale. The old baseline was 8.8 KB per announced -broadcast plus 4.3 KB per extra route on `adad52b`, measured with two -throwaway `moq-net` examples driving an origin under a counting allocator and -reading `/proc/self/statm`. Since then -[moq#2989](https://github.com/moq-dev/moq/pull/2989) cut `kio`'s inline waiter -slots from 32 to 4 (a `kio::State<()>` went from 896 B to about 200 B, and -`kio`'s `tests/waiter_allocs.rs` pins that lever as spent), and -[moq#3225](https://github.com/moq-dev/moq/pull/3225) made a standby route a -table entry rather than an object graph. Neither example is committed, since -they need `#[doc(hidden)]` size probes on private types. Rebuild them and -restate the per-broadcast and per-route cost, the per-peer session -bookkeeping (`announce_ids`, `held`, `watched`), and the shed threshold on a -degree-5, 1 GB node. Chat-shaped traffic (one broadcast per channel or per -chatter) depends on the answer. - -### Open questions - -- Sharding registries by HRW over a prefix key once one registry cannot hold - everything, and what that key is. -- A mixed-version bridge, if a fleet cannot switch at once. -- How long a relay keeps an ended path's seqno. A new origin incarnation - clears it; within one, it must outlive every delayed copy of the start. -- How a push to a new tree child ends what the child missed within the same - incarnation. Its reset only marks a new incarnation, so the push may need a - watermark like the registry reconcile's: it ends only what the child holds - at or below it, and a delayed push cannot erase newer records. -- How long a relay keeps the records of an origin that never comes back. They - stop being reported once it is unreachable, but nothing removes them. -- How an edge routes a SUBSCRIBE for a path none of its clients asked to - announce. It holds no route for it, and asking a registry first adds a round - trip before the first byte. -- What a cold ANNOUNCE_REQUEST reports as live. Answering from the local view - keeps a relay from waiting on peers but reports an empty set until the - registry's replay lands, on every new prefix rather than in a rare race. -- What remains of announce compression's hop-tail half (`Hop Base` and - `Hop Keep` in the lite draft) once only cluster boundaries carry hops. -- What replaces `--hop` first-hop failover. Today two publishers sharing a Hop - ID are one source that relays fail over between at a group boundary - (`doc/bin/cli.md` "Redundant publishers", - `doc/concept/use-case/contribution.md`). Inside a cluster no announcement - carries a hop list, so two encoders on different ingest relays become two - origins. Keep the documented behavior or change the docs in the same PR. - Say whether same-hop semantics survive, or - [Same-hop importers](/quest/m1/hop-aligned-import.md)' work is thrown - away. The redundant ingest study folded in here: whether the pair claims one - `@` epoch, what enforces the aligned groups and matching catalog the - docs only ask for, and who declares the incumbent dead early (a failover - service that retracts it, or active-active delivery to the relay). Weigh it - against the moq-transport rule that each publisher of a namespace must be - asked (#3697). The answer may be a no-go. -- Whether equal-cost next hops should spread by a hash of the path. A fixed - tie-break sends every path through the same neighbour and its failure takes - them all. +### Remaining work + +Once every child has landed: + +- An end-to-end test: a multi-relay cluster in `rs/moq-relay/tests` where a + publish, an end, a relay restart, and a redundant-pair failover each reach + a subscriber on a far relay, with time mocked. +- Rewrite `doc/bin/relay/cluster.md` into the operator's view (topology, + link costs, idle timeout, redundant pairs), and add a routing page under + `doc/concept`. ## Required -- [Wildcard](/quest/m0/wildcard/README.md) - the longest-prefix rule, pool spread, and reply identity this selection builds on +- [Memory benchmark](/quest/m1/cluster-routing/memory.md) - a committed benchmark states per-announcement, per-route, and per-peer relay memory, before anything changes +- [Topology](/quest/m1/cluster-routing/topology.md) - relays learn the relay graph once from a cluster message, apart from routes +- [Propagation](/quest/m1/cluster-routing/propagation.md) - decides how each announcement reaches every relay once, and writes the implementation children +- [Selection](/quest/m1/cluster-routing/selection.md) - a broadcast under overlapping prefixes routes to one origin deterministically, and same-epoch origins are one source +- [Remove `--hop`](/quest/m1/cluster-routing/hop-removal.md) - redundant publishers share an explicit `@`, and `--hop` and the publisher's Hop ID are gone +- [Between clusters](/quest/m1/cluster-routing/inter-cluster.md) - announcements crossing a cluster boundary stay path vector with cluster ids as hops ## Related -- [Same-hop importers](/quest/m1/hop-aligned-import.md) - builds on `--hop` failover, which this line must keep or replace -- [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - a redundant pair would share one epoch - +- [Wildcard](/quest/m0/wildcard/README.md) - the longest-prefix rule, pool spread, and reply identity Selection builds on +- [Cluster idle timeout](/quest/m1/cluster-idle-timeout.md) - failure detection sets every outage window, today and after this line +- [Same-hop importers](/quest/m1/hop-aligned-import.md) - the importer half of a redundant pair; `--hop` removal re-keys it to a shared epoch +- [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - a redundant pair shares one epoch - [Cross-relay delivery under bursts](/quest/m1/cross-relay-bursts.md) - its #4349 report also shows closed broadcasts announced for up to 229 s and flapping between Retracted and Announced across nodes, evidence for per-incarnation seqnos - [Routing cost domains](/quest/m3/routing-cost-domains.md) - cost across the cluster boundaries this keeps path vector diff --git a/quest/m1/cluster-routing/hop-removal.md b/quest/m1/cluster-routing/hop-removal.md new file mode 100644 index 00000000000..2dcdf8221f1 --- /dev/null +++ b/quest/m1/cluster-routing/hop-removal.md @@ -0,0 +1,45 @@ +# [M] Redundant publishers share an epoch, not a hop + +## Goal + +Redundant publishers share an explicit `@` instead of a `--hop`, and +the publisher-facing Hop ID is gone: `moq`'s `--hop` / `MOQ_HOP` and the +deprecated `--origin` spelling, and the Hop setup parameter a publisher +sends. An epoch is strictly better, since a Hop ID is per session: one +connection cannot publish several broadcasts with different identities. + +## Plan + +- The pool semantics already live in + [Selection](/quest/m1/cluster-routing/selection.md): origins announcing the + same epoch-qualified concrete path are one source. This quest deletes what + that makes dead, including `Pin::Publisher(Hop)` in + `rs/moq-net/src/model/front.rs` and `RouteEntry::qualifies`. +- A redundant pair passes one explicit epoch; the broadcast-publish path keeps + an epoch a caller supplies ([Broadcast epochs](/quest/m1/broadcast-epoch/README.md)). + Give `moq` a flag for it if Broadcast epochs has not. +- Relays keep `cluster.id` as their identity; `--hop` fills it today + (`rs/moq-cli/src/args.rs`), so split that coupling. Decide whether relays + still need the Hop setup parameter or learn identity from topology. +- Re-key [Same-hop importers](/quest/m1/hop-aligned-import.md)'s docs and 1+1 + tests to a shared epoch. +- Docs: rewrite "Redundant publishers" in `doc/bin/cli.md` and + `doc/concept/use-case/contribution.md`, then search the repo for `--hop`, + `MOQ_HOP`, and `--cluster-id` examples, including demo recipes. + +Open: whether anything declares an incumbent dead faster than the cluster +idle timeout (a failover service that retracts it, or active-active delivery +to the relay). Neither is required to land this. + +Public API and wire: removes a CLI flag and the publisher's Hop setup +parameter; lands with the line on `dev`. + +## Required + +- [Selection](/quest/m1/cluster-routing/selection.md) - owns the same-epoch pool this relies on +- [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - a restart is a new path, not a splice +- [Same-hop importers](/quest/m1/hop-aligned-import.md) - the importer fixes this re-keys + +## Related + +- [Cluster idle timeout](/quest/m1/cluster-idle-timeout.md) - bounds how long a dead incumbent holds its pair diff --git a/quest/m1/cluster-routing/inter-cluster.md b/quest/m1/cluster-routing/inter-cluster.md new file mode 100644 index 00000000000..43386d65eff --- /dev/null +++ b/quest/m1/cluster-routing/inter-cluster.md @@ -0,0 +1,40 @@ +# [M] Routing between clusters + +## Goal + +Announcements crossing a cluster boundary stay path vector with cluster ids +as the hops, like BGP between autonomous systems. A customer's on-prem +cluster is one hop, and an announcement naming the receiving cluster is +dropped. Inside a cluster nothing carries a list of relay hops. + +## Plan + +- A boundary is a configured link to a relay of another cluster; decide how + a relay knows its own cluster id and its peer's. +- What crosses a boundary is what the chosen + [Propagation](/quest/m1/cluster-routing/propagation.md) design holds, plus + its cluster-id list. An imported record keeps that list as provenance, so + whichever boundary relay exports it appends its own cluster id to the full + list; stripping it on import would let A → B → C → A re-enter A. +- The remote origin is outside the receiving cluster's topology, so the + importing boundary relay announces the record inside its cluster as the + origin, with the boundary link's cost added. The serving origin's identity + still rides the reply, so re-originating does not merge two sources. +- Cluster-id lists are short, so they need no `Hop Base`/`Hop Keep` + compression. +- Cost across the boundary is plain configured link cost; business policy + and incomparable costs are + [Routing cost domains](/quest/m3/routing-cost-domains.md)'s. + +Wire: the boundary announcement in the current wip lite version, with the +draft updated in the same PR. Tests: two clusters with two boundary links +and an origin that is not a boundary relay, and three clusters in a cycle with different ingress and egress relays, where +an announcement neither loops nor re-enters its origin cluster. + +## Required + +- [Propagation](/quest/m1/cluster-routing/propagation.md) - the record shape a boundary exports + +## Related + +- [Routing cost domains](/quest/m3/routing-cost-domains.md) - designs policy on this path vector diff --git a/quest/m1/cluster-routing/memory.md b/quest/m1/cluster-routing/memory.md new file mode 100644 index 00000000000..a97d2e7b38d --- /dev/null +++ b/quest/m1/cluster-routing/memory.md @@ -0,0 +1,46 @@ +# [S] Relay memory benchmark + +## Goal + +A committed benchmark states what a relay's memory costs per announced +broadcast, per extra route, and per peer session, so the rest of +[Cluster routing](/quest/m1/cluster-routing/README.md) has a before figure and +reports its after figure against the same code. Chat-shaped traffic (one +broadcast per channel or per chatter) and Wildcard's "workers times +broadcasts" argument both depend on the answer. + +## Plan + +Every published figure is stale. The old baseline was 8.8 KB per announced +broadcast plus 4.3 KB per extra route on `adad52b`, measured with two +throwaway `moq-net` examples driving an origin under a counting allocator and +reading `/proc/self/statm`. Since then +[moq#2989](https://github.com/moq-dev/moq/pull/2989) cut `kio`'s inline waiter +slots from 32 to 4, and [moq#3225](https://github.com/moq-dev/moq/pull/3225) +made a standby route a table entry rather than an object graph. Neither +example was committed, since they needed `#[doc(hidden)]` size probes on +private types. + +- Measure through the public API with a counting allocator (as + `rs/moq-net/benches/session.rs` already does for groups), not private size + probes, so the benchmark survives the redesign. +- Sweep both axes: broadcasts announced, and peers each one is routed through, + so a cost that grows with the table rather than the touched path shows as a + slope. +- Keep two costs apart: the route table and per-announcement state + (`RouteEntry`, `ServeState` in `rs/moq-net/src/model/origin.rs`) scale with + announcements and routes, while the served-content cache a `ServeState` + materializes scales with demand. Per-peer bookkeeping is the lite + publisher's `live` map and `AnnounceEncoder` entries, the lite subscriber's + `Announced.routes`, and the IETF `watched` and `held`. +- Run it in the nightly benchmark job + ([Benchmark regressions in CI](/quest/m1/bench-ci.md)) or its own nightly + step if that has not landed. +- Record the before figures in the PR and in the questline README, and derive + the shed threshold on a degree-5, 1 GB node from them. The implementation + child that replaces per-peer routes reports the after figures. + +## Related + +- [Wildcard](/quest/m0/wildcard/README.md) - cites the stale figure +- [Benchmark regressions in CI](/quest/m1/bench-ci.md) - where the benchmark runs nightly diff --git a/quest/m1/cluster-routing/propagation.md b/quest/m1/cluster-routing/propagation.md new file mode 100644 index 00000000000..1614b590ab9 --- /dev/null +++ b/quest/m1/cluster-routing/propagation.md @@ -0,0 +1,73 @@ +# [M] Plan announcement propagation + +## Goal + +Decide how an announcement reaches every relay in a cluster once, rather than +once per neighbour, and how every relay keeps the ledger of live announcements +that ANNOUNCE_REQUEST and a cold SUBSCRIBE need. The output is a decision +recorded in the [questline README](/quest/m1/cluster-routing/README.md), +worked counterexamples, and rewritten implementation quests, not production +code. + +## Plan + +Decided: every relay holds a record for every live announcement, and an +announcement names its origin relay and cost, not a path to it +([Topology](/quest/m1/cluster-routing/topology.md) supplies reachability). + +Candidates to choose between or combine: + +- **Tree flooding with per-origin seqnos.** The README's candidate design: + existence floods along the origin's shortest-path tree, a relay forwards an + event only when it changes its view, and per-origin seqnos with + incarnation resets stop stale revivals. This is the same as "skip a + neighbour already closer to the origin": a relay forwards only to its + children in that origin's tree. +- **A central node owns gossip.** Registries: an optional tier, one or more + per region, full-meshed among themselves. An ingest relay registers with + its nearest, an edge sends its ANNOUNCE_REQUEST there, and a relay fails + over to the next-nearest and reconciles (its full live set at its current + seqno, ending whatever it leaves out; the registry's snapshot carries each + origin's last reconcile seqno). With none reachable a relay freezes its + view and alerts. The simulator found registries buy cross-ocean bytes and + one-round-trip announce latency, not message count, at live's 34 relays. +- **A compressed ledger.** The records are a replicated ledger of every live + announcement; sync it with digests (anti-entropy) and compress it, such as + prefix-shared paths, instead of per-event messages. + +Measure the choice with the simulator's scenarios (messages and bytes per +event, convergence, stale revival, restart, failover) and the +[Memory benchmark](/quest/m1/cluster-routing/memory.md)'s figures. + +Open questions the chosen design must answer: + +- How long a relay keeps an ended path's seqno. A new origin incarnation + clears it; within one, it must outlive every delayed copy of the start. +- How a relay that just became another's tree child catches up on what it + missed within the same incarnation. Its reset only marks a new incarnation, + so the push may need a watermark like the registry reconcile's: it ends only + what the child holds at or below it, and a delayed push cannot erase newer + records. +- How long a relay keeps the records of an origin that never comes back. They + stop being reported once it is unreachable, but nothing removes them. +- Whether registries belong in this line. If deferred, write an m2 quest for + them with sharding (HRW over a prefix key) and a mixed-version bridge as its + open questions, and one for reduced flooding + ([RFC 9667](https://www.rfc-editor.org/rfc/rfc9667)). + +The implementation quests it writes replace the empty-prefix ANNOUNCE_REQUEST +between peers and per-hop path-vector announcements, drop `Hop Base` and +`Hop Keep` from the current wip lite version, and report the memory +benchmark's after figures. Add each one to the Required of +[Selection](/quest/m1/cluster-routing/selection.md) and +[Routing between clusters](/quest/m1/cluster-routing/inter-cluster.md), so +neither starts on a record shape that is not implemented yet. + +## Required + +- [Memory benchmark](/quest/m1/cluster-routing/memory.md) - the before figures the choice is weighed against + +## Related + +- [Cross-relay delivery under bursts](/quest/m1/cross-relay-bursts.md) - its report of closed broadcasts announced for minutes is evidence for per-origin seqnos +- [Announcement shapes](/quest/m2/announce-shapes.md) - announcements between relays must keep their shape diff --git a/quest/m1/cluster-routing/selection.md b/quest/m1/cluster-routing/selection.md new file mode 100644 index 00000000000..c75f2b5b81a --- /dev/null +++ b/quest/m1/cluster-routing/selection.md @@ -0,0 +1,72 @@ +# [L] Deterministic origin selection + +## Goal + +A broadcast under overlapping announcements routes to one origin chosen +deterministically, and every relay forwards toward that origin by topology. +Origins that announce the same epoch-qualified concrete path are one source, +so a subscriber moves between them at a group boundary when the incumbent +ends or becomes unreachable. + +## Plan + +Decided: + +- The longest covering prefix ranks first, per + [Wildcard](/quest/m0/wildcard/README.md), and origin choice is + per broadcast, not per announced prefix. +- An epoch-qualified concrete path (`foo/@`) is a source's identity: + every origin announcing it is interchangeable, which is how a redundant + pair works without `--hop`. The first relay fails over between them at a + group boundary. A path with no epoch, or one a claim produces, keeps + Wildcard's per-origin identity (the origin SUBSCRIBE_OK names), since two + workers' groups differ. That includes a claim worker's derived output once + it is announced concretely: it mirrors the input's epoch + (`.pro/transcode//foo.hang/@e`), so after a double claim two workers + announce the same epoch-qualified path and must not pool. This extends + Wildcard's resume rule to concrete same-epoch origins. + +Candidate mechanics: + +- A relay picks the origin with the lowest shortest-path distance plus origin + cost, ties broken by rendezvous hashing (HRW) of the requested path and the + origin id, and forwards along its shortest path. That is a shortest path to + a virtual node linked to every origin, so it is loop-free whenever relays + agree on the topology. +- The first relay's choice rides the SUBSCRIBE and FETCH, and transit relays + forward toward that origin by topology alone, never re-selecting. + Re-selection against another existence view loops: a relay that lost a + specific claim falls back to a broader one through a relay still routing to + the specific one + ([RFC 8966 section 3.5.4](https://www.rfc-editor.org/rfc/rfc8966#section-3.5.4)). + A refusal follows Wildcard's refusal rule: only a capacity refusal lets the + first relay select once more within the same longest-prefix tier, excluding + the refusing origin, and any other refusal is terminal. +- SUBSCRIBE and FETCH carry a visited-relay list end to end. It catches loops + while liveness views disagree and names the path for stats. The serving + origin's identity rides the reply, per Wildcard's first-hop resume rule. + +Open: + +- Whether equal-cost next hops should spread by a hash of the path. A fixed + tie-break sends every path through the same neighbour, and its failure + takes them all. +- How a relay tells claim output from a redundant pair. One candidate: a + concrete path an origin announces under its own claim keeps per-origin + identity, since a redundant publisher claims nothing. + +Wire: SUBSCRIBE and FETCH fields in the current wip lite version, with the +draft updated in the same PR. Tests cover an HRW split across an equal-cost +pool, refusal and reselection, a same-epoch pair failing over mid-track +with no timestamp rewind, and a concrete double claim whose loser's +subscribers end and resubscribe rather than splice. + +## Required + +- [Topology](/quest/m1/cluster-routing/topology.md) - distance to each origin +- [Propagation](/quest/m1/cluster-routing/propagation.md) - the record shape that names each origin +- [Wildcard](/quest/m0/wildcard/README.md) - the longest-prefix rule, pool spread, and reply identity this builds on + +## Related + +- [Epoch primitive](/quest/m1/epoch.md) - parses the `@` segment that makes a path a source identity diff --git a/quest/m1/cluster-routing/topology.md b/quest/m1/cluster-routing/topology.md new file mode 100644 index 00000000000..35adf5f6a40 --- /dev/null +++ b/quest/m1/cluster-routing/topology.md @@ -0,0 +1,61 @@ +# [L] Cluster topology + +## Goal + +Relays learn the relay graph once, from a cluster message kept apart from +routes, instead of every route repeating how to reach its origin. Each relay +knows every configured link, whether it is up, and its cost, and computes its +shortest path to every other relay. No announcement is needed to learn that +relay K exists or how to reach it. + +## Plan + +Decided: the topology is configured. `--cluster-connect` or the connect API +gives the relay graph and link costs, and LAN mDNS dials peers that then count +as configured links. Gossip discovery is gone first, by +[Remove gossip](/quest/m0/remove-gossip.md). + +Candidate mechanics, from the simulator (see the questline README's +findings): + +- Relays flood per-link liveness among themselves with a per-link seqno. The + seqno is scoped to the relay's incarnation, so a restarted relay's links + supersede its stale ones instead of looking older. +- A relay batches the liveness reports it sends, its own and those it + forwards, for a short hold-down (50 ms in the simulator), and recomputes its + shortest paths after a matching delay, as OSPF's SPF delay does. Unbatched, + one relay restart at 340 relays sent half a million messages; batched, 27k. +- On session up, relays exchange a digest (each reporter's incarnation and + its seqno per link) and send only what the other lacks. A reporter's + reports flood separately, so its newest seqno alone would hide a missing + older one. The digest already counts the fresh report of the link that just + came up; sending the database first replays the relay's own report from + when the link went down, and the peer drops the link it is using. +- Distance compares cost, then hop count, so every hop strictly shortens it + even across `?cost=0` links. + +Reduced flooding ([RFC 9667](https://www.rfc-editor.org/rfc/rfc9667)) is +out of scope; [Propagation](/quest/m1/cluster-routing/propagation.md) writes +it as an m2 quest if it stays deferred. + +Open: moq-transport cluster peers. Cluster links accept moq-transport 17+ +today via the cluster extension (`drafts/draft-lcurley-moq-cluster.md`), +which these messages do not reach. +Either extend that draft, or refuse a cluster session that does not negotiate +the wip lite version, per the README's "the cluster switches versions as a +whole". Never accept a peer that cannot carry the topology. + +Wire: new cluster-session messages in the current wip lite version, with the +draft updated in the same PR. Tests drive topologies in process with mocked +time, including restart, a link flapping, and a digest racing a link that +just came up. Expose the computed graph where operators already look +(`/nodes` in `rs/moq-relay/src/internal.rs`). + +## Required + +- [Remove gossip](/quest/m0/remove-gossip.md) - configured links are the only topology source + +## Related + +- [Cluster idle timeout](/quest/m1/cluster-idle-timeout.md) - liveness only reports what the session layer detects +- [Drain](/quest/m1/drain/README.md) - a second relay per PoP joins this topology diff --git a/quest/m1/hop-aligned-import.md b/quest/m1/hop-aligned-import.md index 9b34dd42b0c..250076067bd 100644 --- a/quest/m1/hop-aligned-import.md +++ b/quest/m1/hop-aligned-import.md @@ -13,7 +13,11 @@ exits (#4354). ## Plan Decided: same-hop publishers MUST publish the same broadcasts and tracks. -Keep `--hop`, and make every container importer (ts, fmp4, flv, mkv, and the +Keep `--hop` for now: the users' bugs are on one relay today. Cluster +routing replaces it with a shared explicit epoch on `dev` (decided +2026-09-30), and its [`--hop` removal](/quest/m1/cluster-routing/hop-removal.md) +re-keys this quest's docs and tests. The importer work holds under either +key. Make every container importer (ts, fmp4, flv, mkv, and the SRT, RTMP, and HLS gateways that reuse them) meet the contract when fed one encoded stream. Capture is out: two encoders never align. @@ -40,5 +44,5 @@ survives the standby joining and the incumbent stopping. ## Related -- [Cluster routing](/quest/m1/cluster-routing/README.md) - drops hop lists inside a cluster and must say whether same-hop failover survives; it also owns splicing across first hops and two encoders, which this does not attempt +- [Remove `--hop`](/quest/m1/cluster-routing/hop-removal.md) - on dev, a redundant pair shares an explicit epoch instead, and this quest's docs and tests are re-keyed to it - [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - a redundant pair shares one epoch diff --git a/quest/m3/routing-cost-domains.md b/quest/m3/routing-cost-domains.md index a21210a6871..f32615b6aed 100644 --- a/quest/m3/routing-cost-domains.md +++ b/quest/m3/routing-cost-domains.md @@ -56,7 +56,7 @@ quests. Open wire/API choices belong to this design exercise. ## Required -- [Cluster routing](/quest/m1/cluster-routing/README.md) - this designs on its inter-cluster path vector +- [Routing between clusters](/quest/m1/cluster-routing/inter-cluster.md) - this designs on its inter-cluster path vector ## Related From 19cfa9b2cdf060ef60e429780df6b633250f62f3 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 30 Sep 2026 16:12:41 +0000 Subject: [PATCH 107/128] chore(deps): bump urllib3 from 2.7.0 to 2.8.0 (#4593) Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- uv.lock | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/uv.lock b/uv.lock index e9766ea3bf1..5cd21997f81 100644 --- a/uv.lock +++ b/uv.lock @@ -906,9 +906,9 @@ wheels = [ [[package]] name = "urllib3" -version = "2.7.0" +version = "2.8.0" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/53/0c/06f8b233b8fd13b9e5ee11424ef85419ba0d8ba0b3138bf360be2ff56953/urllib3-2.7.0.tar.gz", hash = "sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c", size = 433602, upload-time = "2026-05-07T16:13:18.596Z" } +sdist = { url = "https://files.pythonhosted.org/packages/e3/05/b17359e1cefb4f909b5e40b1b90a496d987258916dbbf88e842c729f510e/urllib3-2.8.0.tar.gz", hash = "sha256:63bf2ead4c879426ebf22ef2a781eeb4aa3b4ae798a0435506f8687fd5bb9b63", size = 458972, upload-time = "2026-09-15T19:29:36.253Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/7f/3e/5db95bcf282c52709639744ca2a8b149baccf648e39c8cc87553df9eae0c/urllib3-2.7.0-py3-none-any.whl", hash = "sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897", size = 131087, upload-time = "2026-05-07T16:13:17.151Z" }, + { url = "https://files.pythonhosted.org/packages/92/9d/c4e665119135114480843e7ab388fa94d8480650450e6f8e26b70d323a4c/urllib3-2.8.0-py3-none-any.whl", hash = "sha256:0cf3cae568d36aa9576b28dfb35f11328f1cb974ca7647d9475ebb86c75ac6e3", size = 135717, upload-time = "2026-09-15T19:29:34.577Z" }, ] From 4033bfa498c7eccb4dec1055fc8f870fd0c5f141 Mon Sep 17 00:00:00 2001 From: "moq-bot[bot]" <186640430+moq-bot[bot]@users.noreply.github.com> Date: Wed, 30 Sep 2026 16:21:24 +0000 Subject: [PATCH 108/128] chore: release (#4320) Co-authored-by: moq-bot[bot] <186640430+moq-bot[bot]@users.noreply.github.com> --- Cargo.lock | 143 +++++++++++++++++----------------- Cargo.toml | 42 +++++----- rs/hang/CHANGELOG.md | 6 ++ rs/hang/Cargo.toml | 2 +- rs/kio/CHANGELOG.md | 7 ++ rs/kio/Cargo.toml | 2 +- rs/libmoq/CHANGELOG.md | 8 ++ rs/libmoq/Cargo.toml | 2 +- rs/moq-archive/CHANGELOG.md | 6 ++ rs/moq-archive/Cargo.toml | 2 +- rs/moq-audio/CHANGELOG.md | 10 +++ rs/moq-audio/Cargo.toml | 2 +- rs/moq-auth/CHANGELOG.md | 17 ++++ rs/moq-auth/Cargo.toml | 2 +- rs/moq-binary/CHANGELOG.md | 6 ++ rs/moq-binary/Cargo.toml | 2 +- rs/moq-boy/CHANGELOG.md | 6 ++ rs/moq-boy/Cargo.toml | 2 +- rs/moq-cli/CHANGELOG.md | 22 ++++++ rs/moq-cli/Cargo.toml | 2 +- rs/moq-e2ee/CHANGELOG.md | 6 ++ rs/moq-e2ee/Cargo.toml | 2 +- rs/moq-ffi/CHANGELOG.md | 10 +++ rs/moq-ffi/Cargo.toml | 2 +- rs/moq-gst/CHANGELOG.md | 12 +++ rs/moq-gst/Cargo.toml | 2 +- rs/moq-hls/CHANGELOG.md | 6 ++ rs/moq-hls/Cargo.toml | 2 +- rs/moq-json/CHANGELOG.md | 10 +++ rs/moq-json/Cargo.toml | 2 +- rs/moq-loc/CHANGELOG.md | 6 ++ rs/moq-loc/Cargo.toml | 2 +- rs/moq-mux/CHANGELOG.md | 19 +++++ rs/moq-mux/Cargo.toml | 2 +- rs/moq-net/CHANGELOG.md | 34 ++++++++ rs/moq-net/Cargo.toml | 2 +- rs/moq-pattern/CHANGELOG.md | 10 +++ rs/moq-pattern/Cargo.toml | 2 +- rs/moq-relay/CHANGELOG.md | 22 ++++++ rs/moq-relay/Cargo.toml | 2 +- rs/moq-room/CHANGELOG.md | 6 ++ rs/moq-room/Cargo.toml | 2 +- rs/moq-rtc/CHANGELOG.md | 6 ++ rs/moq-rtc/Cargo.toml | 2 +- rs/moq-rtmp/CHANGELOG.md | 10 +++ rs/moq-rtmp/Cargo.toml | 2 +- rs/moq-sock/CHANGELOG.md | 6 ++ rs/moq-sock/Cargo.toml | 2 +- rs/moq-srt/CHANGELOG.md | 7 ++ rs/moq-srt/Cargo.toml | 2 +- rs/moq-stats/CHANGELOG.md | 6 ++ rs/moq-stats/Cargo.toml | 2 +- rs/moq-tokio/CHANGELOG.md | 24 ++++++ rs/moq-tokio/Cargo.toml | 2 +- rs/moq-transcode/CHANGELOG.md | 6 ++ rs/moq-transcode/Cargo.toml | 2 +- rs/moq-uring/CHANGELOG.md | 10 +++ rs/moq-uring/Cargo.toml | 2 +- rs/moq-video/CHANGELOG.md | 12 +++ rs/moq-video/Cargo.toml | 2 +- 60 files changed, 438 insertions(+), 121 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index b397cdaf8f4..3e3d8032a1f 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -415,9 +415,9 @@ dependencies = [ [[package]] name = "async-compression" -version = "0.4.48" +version = "0.4.50" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "fb61aea1a7def73ee7c350a184f0e70b32c182344e2e75bf70c9b621b83417fd" +checksum = "ee19bd99b43e3691acbad4e840420a4881cea6c0b66a208125a824f8fd53f5a1" dependencies = [ "compression-codecs", "compression-core", @@ -1240,9 +1240,9 @@ dependencies = [ [[package]] name = "compression-codecs" -version = "0.4.43" +version = "0.4.45" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "bef16c47ba2797aa6a909cc37d39911f3a6743811fe7408ac0b0cc0276b656e9" +checksum = "98fc98460ba0ad5317075d3632b8dfc45d0be8c4a49347c2a38272019717614a" dependencies = [ "compression-core", "flate2", @@ -2835,13 +2835,13 @@ dependencies = [ [[package]] name = "hang" -version = "0.21.8" +version = "0.21.9" dependencies = [ "anyhow", "bytes", "derive_more 2.1.1", "hex", - "kio 0.6.1", + "kio 0.6.2", "lazy_static", "moq-json", "moq-mux", @@ -3362,9 +3362,9 @@ checksum = "791930b43c0d5973160d90a8f3894509f2b273430f5c5c73b668636d0287c5c0" [[package]] name = "iroh" -version = "1.2.0" +version = "1.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b2f8d1cfffc83efe39a1031aab423ce09cb8048071baba550508931e9a81ce46" +checksum = "885787b892b5e2507c701f132ecbd45d2bad4bbb75157a19427087c16dadb833" dependencies = [ "backon", "blake3", @@ -3412,9 +3412,9 @@ dependencies = [ [[package]] name = "iroh-base" -version = "1.2.0" +version = "1.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ffd1efd1aaecd68d4d1b0727a30c5811f43fb822843e48f65f6e5db3b7256cc9" +checksum = "6ae9092be76c9f5429776ab3394f5a5a78dc19dc2524267e884a5b9781546c3f" dependencies = [ "curve25519-dalek", "data-encoding", @@ -3481,9 +3481,9 @@ dependencies = [ [[package]] name = "iroh-relay" -version = "1.2.0" +version = "1.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "beb2294a9749d6a25fd7cd8bcf0fccd932f20716d4f967d85d3f23c7135ae6a2" +checksum = "ee116a8233f84980574bb8d11e4517503080cd2c3605bafca04ee9c35d708bd9" dependencies = [ "blake3", "bytes", @@ -3802,7 +3802,7 @@ dependencies = [ [[package]] name = "kio" -version = "0.6.1" +version = "0.6.2" dependencies = [ "criterion", "futures", @@ -3884,13 +3884,13 @@ checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981" [[package]] name = "libmoq" -version = "0.6.8" +version = "0.6.9" dependencies = [ "anyhow", "bytes", "cbindgen", "hang", - "kio 0.6.1", + "kio 0.6.2", "moq-audio", "moq-json", "moq-loc", @@ -4155,7 +4155,7 @@ dependencies = [ [[package]] name = "moq-archive" -version = "0.0.8" +version = "0.0.9" dependencies = [ "async-trait", "bytes", @@ -4172,7 +4172,7 @@ dependencies = [ [[package]] name = "moq-audio" -version = "0.1.7" +version = "0.1.8" dependencies = [ "block2 0.6.2", "bytes", @@ -4180,7 +4180,7 @@ dependencies = [ "dispatch2", "fixed-resample", "hang", - "kio 0.6.1", + "kio 0.6.2", "moq-mux", "moq-net", "objc2 0.6.4", @@ -4203,14 +4203,14 @@ dependencies = [ [[package]] name = "moq-auth" -version = "0.1.5" +version = "0.2.0" dependencies = [ "anyhow", "aws-lc-rs", "axum", "base64 0.23.1", "jsonwebtoken", - "kio 0.6.1", + "kio 0.6.2", "moq-auth", "moq-pattern", "moq-token", @@ -4252,10 +4252,10 @@ dependencies = [ [[package]] name = "moq-binary" -version = "0.1.7" +version = "0.1.8" dependencies = [ "bytes", - "kio 0.6.1", + "kio 0.6.2", "moq-flate", "moq-net", "thiserror 2.0.21", @@ -4264,7 +4264,7 @@ dependencies = [ [[package]] name = "moq-boy" -version = "0.5.8" +version = "0.5.9" dependencies = [ "anyhow", "boytacean", @@ -4284,7 +4284,7 @@ dependencies = [ [[package]] name = "moq-cli" -version = "0.12.8" +version = "0.13.0" dependencies = [ "anyhow", "axum", @@ -4323,14 +4323,14 @@ dependencies = [ [[package]] name = "moq-e2ee" -version = "0.0.8" +version = "0.0.9" dependencies = [ "aws-lc-rs", "base64 0.23.1", "bytes", "criterion", "hex", - "kio 0.6.1", + "kio 0.6.2", "moq-net", "serde_json", "thiserror 2.0.21", @@ -4342,12 +4342,12 @@ dependencies = [ [[package]] name = "moq-ffi" -version = "0.4.8" +version = "0.4.9" dependencies = [ "bytes", "getrandom 0.4.3", "hang", - "kio 0.6.1", + "kio 0.6.2", "moq-audio", "moq-json", "moq-mux", @@ -4376,7 +4376,7 @@ dependencies = [ [[package]] name = "moq-gst" -version = "0.4.8" +version = "0.4.9" dependencies = [ "anyhow", "bytes", @@ -4395,13 +4395,13 @@ dependencies = [ [[package]] name = "moq-hls" -version = "0.5.8" +version = "0.5.9" dependencies = [ "axum", "bytes", "hang", "humantime", - "kio 0.6.1", + "kio 0.6.2", "m3u8-rs", "moq-mux", "moq-net", @@ -4419,12 +4419,12 @@ dependencies = [ [[package]] name = "moq-json" -version = "0.5.5" +version = "0.5.6" dependencies = [ "bytes", "criterion", "json-patch", - "kio 0.6.1", + "kio 0.6.2", "moq-flate", "moq-net", "serde", @@ -4436,7 +4436,7 @@ dependencies = [ [[package]] name = "moq-loc" -version = "0.2.16" +version = "0.2.17" dependencies = [ "bytes", "moq-net", @@ -4454,7 +4454,7 @@ dependencies = [ [[package]] name = "moq-mux" -version = "0.10.8" +version = "0.10.9" dependencies = [ "anyhow", "base64 0.23.1", @@ -4462,7 +4462,7 @@ dependencies = [ "futures", "h264-parser", "hang", - "kio 0.6.1", + "kio 0.6.2", "memchr", "moq-binary", "moq-json", @@ -4492,14 +4492,14 @@ version = "0.20.0" [[package]] name = "moq-net" -version = "0.3.7" +version = "0.3.8" dependencies = [ "arrayvec", "bytes", "criterion", "futures", "getrandom 0.4.3", - "kio 0.6.1", + "kio 0.6.2", "loom", "moq-pattern", "num_enum", @@ -4600,7 +4600,7 @@ dependencies = [ [[package]] name = "moq-pattern" -version = "0.1.1" +version = "0.1.2" dependencies = [ "moq-pattern", "serde", @@ -4609,7 +4609,7 @@ dependencies = [ [[package]] name = "moq-relay" -version = "0.15.8" +version = "0.16.0" dependencies = [ "anyhow", "axum", @@ -4653,9 +4653,9 @@ dependencies = [ [[package]] name = "moq-room" -version = "0.2.8" +version = "0.2.9" dependencies = [ - "kio 0.6.1", + "kio 0.6.2", "moq-auth", "moq-json", "moq-net", @@ -4667,7 +4667,7 @@ dependencies = [ [[package]] name = "moq-rtc" -version = "0.3.8" +version = "0.3.9" dependencies = [ "aws-lc-rs", "axum", @@ -4688,7 +4688,7 @@ dependencies = [ [[package]] name = "moq-rtmp" -version = "0.3.8" +version = "0.3.9" dependencies = [ "anyhow", "byteorder", @@ -4722,7 +4722,7 @@ dependencies = [ [[package]] name = "moq-sock" -version = "0.1.0" +version = "0.2.0" dependencies = [ "core_affinity", "libc", @@ -4735,7 +4735,7 @@ dependencies = [ [[package]] name = "moq-srt" -version = "0.3.8" +version = "0.3.9" dependencies = [ "bytes", "futures", @@ -4752,7 +4752,7 @@ dependencies = [ [[package]] name = "moq-stats" -version = "0.2.8" +version = "0.2.9" dependencies = [ "futures", "moq-json", @@ -4785,7 +4785,7 @@ dependencies = [ [[package]] name = "moq-tokio" -version = "0.19.19" +version = "0.19.20" dependencies = [ "anyhow", "bytes", @@ -4839,12 +4839,12 @@ dependencies = [ [[package]] name = "moq-transcode" -version = "0.1.7" +version = "0.1.8" dependencies = [ "anyhow", "bytes", "hang", - "kio 0.6.1", + "kio 0.6.2", "moq-mux", "moq-net", "moq-tokio", @@ -4858,14 +4858,14 @@ dependencies = [ [[package]] name = "moq-uring" -version = "0.0.9" +version = "0.0.10" dependencies = [ "anyhow", "bytes", "criterion", "http", "io-uring", - "kio 0.6.1", + "kio 0.6.2", "libc", "moq-net", "moq-noq-proto", @@ -4915,7 +4915,7 @@ dependencies = [ [[package]] name = "moq-video" -version = "0.1.7" +version = "0.1.8" dependencies = [ "anyhow", "ash", @@ -6907,9 +6907,9 @@ dependencies = [ [[package]] name = "quinn-proto" -version = "0.11.18" +version = "0.11.19" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a9746dbde176634f4f2f1faf2404e30a31b2bc1e9cafb5329c95d8177a18c9fc" +checksum = "0e750cca55fe4f0439a15d0bb529da9651e79993e8e72c61a899a36d462befbe" dependencies = [ "aws-lc-rs", "bytes", @@ -6930,9 +6930,9 @@ dependencies = [ [[package]] name = "quinn-udp" -version = "0.5.15" +version = "0.5.16" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "35a133f956daabe89a61a685c2649f13d82d5aa4bd5d12d1277e1072a21c0694" +checksum = "af66907df18639dcf4db56ca65490cabc4b27a97dbadd96f2926cca73298f016" dependencies = [ "cfg_aliases", "libc", @@ -8800,9 +8800,9 @@ dependencies = [ [[package]] name = "tokio-rustls" -version = "0.26.5" +version = "0.26.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b0c85f2c3ef0b1cd58b36682f4b17aaa995f0e5db534d85692b4903abce21f67" +checksum = "c9cc2678c2cdd569ef8215e2afd7954ada2ae20b4fdd2c5fe6139a3b02d105db" dependencies = [ "rustls", "tokio", @@ -9420,32 +9420,33 @@ dependencies = [ [[package]] name = "usage-argv" -version = "6.11.1" +version = "6.12.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "669a2fcdc2d909c0858fcf190d6135dd9fb303da3497f1b9fea8592bb414d74c" +checksum = "d81d0292a01b769c28c094fc9da0596f49a4c78a6da88ffda53de9eafefc5b20" [[package]] name = "usage-config" -version = "6.11.1" +version = "6.12.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7bf47002e31d27e4cad2326006ff50b88e726b6e8601f3a47cb2c2a3f4eb1357" +checksum = "6d9f207fbe8bc0c04c454f0f0f64f06238e1ca7c1b87af6f7353166944d1c1dc" [[package]] name = "usage-derive" -version = "6.11.1" +version = "6.12.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "fba1fef6ebefcad2733a1120567baf665b67b85382539de4b6187dd85b5eab12" +checksum = "6731f7bc17e630509b9c254ac13049dfc02451011d9dc9eb52865157304c03dc" dependencies = [ "proc-macro2", "quote", "syn 3.0.6", + "toml 1.1.6+spec-1.1.0", ] [[package]] name = "usage-rs" -version = "6.11.1" +version = "6.12.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3ba4af226b5e8186231f5fc83dc913522fab3b5accc7fc3811e940794d522407" +checksum = "b770a1ed5bf2c95707490f612e0c5597d7c664c6e37b60772ead3a8359526115" dependencies = [ "usage-argv", "usage-config", @@ -9455,9 +9456,9 @@ dependencies = [ [[package]] name = "usage-test" -version = "6.11.1" +version = "6.12.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "af670ae025049d131b1d16600e80fd6794cd83e69a3c84cb6605cdb8176f4957" +checksum = "1011b07f3e21381eaaada43daeb5dce92469bc25c87921e6c957b2c3ba5ae716" dependencies = [ "usage-argv", ] @@ -10799,9 +10800,9 @@ dependencies = [ [[package]] name = "yoke-derive" -version = "0.8.3" +version = "0.8.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "33811428bee40dbceb6d545e95754741d17a6aef9a4849f0fd62e2ba4f412a78" +checksum = "ec8ebde2db3681e8c9980cc27822030e68752690ddfa9473e739aeb4dbde6d71" dependencies = [ "proc-macro2", "quote", diff --git a/Cargo.toml b/Cargo.toml index c27908b5072..68dc8174394 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -119,14 +119,14 @@ dispatch2 = "0.3.1" flate2 = { version = "1.1", default-features = false } futures = "0.3" getrandom = { version = "0.4", features = ["wasm_js"] } -hang = { version = "0.21.8", path = "rs/hang" } +hang = { version = "0.21.9", path = "rs/hang" } hex = "0.4" # HMAC-SHA256 for the mDNS membership proofs (moq-tokio's `mdns` feature). hmac = "0.13" humantime = "2.3" io-uring = "0.7.14" jsonwebtoken = "11" -kio = { version = "0.6.1", path = "rs/kio" } +kio = { version = "0.6.2", path = "rs/kio" } lazy_static = "1.5" libc = "0.2" libloading = "0.9" @@ -137,16 +137,16 @@ loom = { version = "0.7.2", features = ["futures"] } # DNS-SD advertisement and browsing for LAN peer discovery (moq-tokio's `mdns` feature). # `async` awaits the event channel instead of blocking a thread on it. mdns-sd = { version = "0.21", features = ["async"] } -moq-audio = { version = "0.1.7", path = "rs/moq-audio", default-features = false } -moq-auth = { version = "0.1.5", path = "rs/moq-auth" } -moq-binary = { version = "0.1.7", path = "rs/moq-binary" } +moq-audio = { version = "0.1.8", path = "rs/moq-audio", default-features = false } +moq-auth = { version = "0.2.0", path = "rs/moq-auth" } +moq-binary = { version = "0.1.8", path = "rs/moq-binary" } moq-flate = { version = "0.2.0", path = "rs/moq-flate" } -moq-hls = { version = "0.5.8", path = "rs/moq-hls", default-features = false } -moq-json = { version = "0.5.5", path = "rs/moq-json" } -moq-loc = { version = "0.2.16", path = "rs/moq-loc" } +moq-hls = { version = "0.5.9", path = "rs/moq-hls", default-features = false } +moq-json = { version = "0.5.6", path = "rs/moq-json" } +moq-loc = { version = "0.2.17", path = "rs/moq-loc" } moq-msf = { version = "0.5.1", path = "rs/moq-msf" } -moq-mux = { version = "0.10.8", path = "rs/moq-mux" } -moq-net = { version = "0.3.7", path = "rs/moq-net" } +moq-mux = { version = "0.10.9", path = "rs/moq-mux" } +moq-net = { version = "0.3.8", path = "rs/moq-net" } # The MoQ fork of noq (moq-dev/noq). iroh keeps upstream noq, so a build with the # iroh feature carries both stacks. moq-noq-proto = { version = "1.3.2", default-features = false } @@ -155,24 +155,24 @@ moq-noq-udp = "1.3.2" # driver at runtime. Compiles on any platform (macOS included) but only actually # used by moq-video on Linux. moq-nvenc = { version = "0.1.2", path = "rs/moq-nvenc" } -moq-pattern = { version = "0.1.1", path = "rs/moq-pattern" } -moq-relay = { version = "0.15.8", path = "rs/moq-relay", default-features = false } -moq-rtc = { version = "0.3.8", path = "rs/moq-rtc" } -moq-rtmp = { version = "0.3.8", path = "rs/moq-rtmp" } -moq-sock = { version = "0.1.0", path = "rs/moq-sock" } -moq-srt = { version = "0.3.8", path = "rs/moq-srt" } -moq-stats = { version = "0.2.8", path = "rs/moq-stats" } -moq-tokio = { version = "0.19.19", path = "rs/moq-tokio", default-features = false } +moq-pattern = { version = "0.1.2", path = "rs/moq-pattern" } +moq-relay = { version = "0.16.0", path = "rs/moq-relay", default-features = false } +moq-rtc = { version = "0.3.9", path = "rs/moq-rtc" } +moq-rtmp = { version = "0.3.9", path = "rs/moq-rtmp" } +moq-sock = { version = "0.2.0", path = "rs/moq-sock" } +moq-srt = { version = "0.3.9", path = "rs/moq-srt" } +moq-stats = { version = "0.2.9", path = "rs/moq-stats" } +moq-tokio = { version = "0.19.20", path = "rs/moq-tokio", default-features = false } # Default features off on moq-transcode and moq-video so each workspace consumer # chooses native codecs, OpenH264, and rendering explicitly. Both crates still # provide working native plus software defaults when depended on directly. # VAAPI is opt-in everywhere; its decoder is hardware-validated, while its # encoder is not yet. -moq-transcode = { version = "0.1.7", path = "rs/moq-transcode", default-features = false } +moq-transcode = { version = "0.1.8", path = "rs/moq-transcode", default-features = false } # default-features off (the noq backend) so the consumer picks which QUIC # stack the io_uring path compiles; cargo features are additive, so a default-on # backend could not be opted out of. -moq-uring = { version = "0.0.9", path = "rs/moq-uring", default-features = false } +moq-uring = { version = "0.0.10", path = "rs/moq-uring", default-features = false } # In-tree fork of `v4l` with the videodev2.h bindings checked in, so moq-video's # `capture` and `v4l2` need no libclang or kernel headers. Linux only; an empty # stub elsewhere. @@ -185,7 +185,7 @@ moq-vaapi = "0.1.0" # `features = ["capture"]` to a consumer that ships in those bindings pulls the # whole device graph into every one of them. Codec features are independent of # that argument, so moq-ffi and libmoq opt NVIDIA, OpenH264, and VAAPI back in. -moq-video = { version = "0.1.7", path = "rs/moq-video", default-features = false } +moq-video = { version = "0.1.8", path = "rs/moq-video", default-features = false } nix = { version = "0.31.3", features = ["net", "socket", "uio"] } # Upstream noq-proto, only for iroh's controller factory types. noq-proto = { version = "1.2", default-features = false } diff --git a/rs/hang/CHANGELOG.md b/rs/hang/CHANGELOG.md index 9083efe9a85..29fd8b30c5b 100644 --- a/rs/hang/CHANGELOG.md +++ b/rs/hang/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.21.9](https://github.com/moq-dev/moq/compare/hang-v0.21.8...hang-v0.21.9) - 2026-09-30 + +### Other + +- updated the following local packages: kio, moq-net, moq-json + ## [0.21.8](https://github.com/moq-dev/moq/compare/hang-v0.21.7...hang-v0.21.8) - 2026-09-27 ### Added diff --git a/rs/hang/Cargo.toml b/rs/hang/Cargo.toml index 6f9733a8353..940ce9dea4c 100644 --- a/rs/hang/Cargo.toml +++ b/rs/hang/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.21.8" +version = "0.21.9" edition = "2024" rust-version.workspace = true diff --git a/rs/kio/CHANGELOG.md b/rs/kio/CHANGELOG.md index 7ddc2611bba..bb0877821c0 100644 --- a/rs/kio/CHANGELOG.md +++ b/rs/kio/CHANGELOG.md @@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.6.2](https://github.com/moq-dev/moq/compare/kio-v0.6.1...kio-v0.6.2) - 2026-09-30 + +### Fixed + +- *(kio)* keep a lost waiter's recorded lists idempotent ([#4422](https://github.com/moq-dev/moq/pull/4422)) +- *(net)* keep an aborted track's finished groups, expire ended tracks ([#4378](https://github.com/moq-dev/moq/pull/4378)) + ## [0.6.1](https://github.com/moq-dev/moq/compare/kio-v0.6.0...kio-v0.6.1) - 2026-09-26 ### Fixed diff --git a/rs/kio/Cargo.toml b/rs/kio/Cargo.toml index 9ad60223b50..0bee6842597 100644 --- a/rs/kio/Cargo.toml +++ b/rs/kio/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley"] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.6.1" +version = "0.6.2" edition = "2024" rust-version.workspace = true diff --git a/rs/libmoq/CHANGELOG.md b/rs/libmoq/CHANGELOG.md index e633377dfcb..6324f5616d1 100644 --- a/rs/libmoq/CHANGELOG.md +++ b/rs/libmoq/CHANGELOG.md @@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.6.9](https://github.com/moq-dev/moq/compare/libmoq-v0.6.8...libmoq-v0.6.9) - 2026-09-30 + +### Fixed + +- *(net)* an origin::Dynamic keeps its origin alive ([#4417](https://github.com/moq-dev/moq/pull/4417)) +- *(libmoq)* render moq.pc only when packaging ([#4372](https://github.com/moq-dev/moq/pull/4372)) +- *(libmoq)* open extern "C" in the generated moq.h ([#4350](https://github.com/moq-dev/moq/pull/4350)) + ## [0.6.8](https://github.com/moq-dev/moq/compare/libmoq-v0.6.7...libmoq-v0.6.8) - 2026-09-27 ### Other diff --git a/rs/libmoq/Cargo.toml b/rs/libmoq/Cargo.toml index 72ddaffaa8c..81459f2c269 100644 --- a/rs/libmoq/Cargo.toml +++ b/rs/libmoq/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley ", "Brian Medley " repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.6.8" +version = "0.6.9" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-archive/CHANGELOG.md b/rs/moq-archive/CHANGELOG.md index 45bbe508b01..882e455a773 100644 --- a/rs/moq-archive/CHANGELOG.md +++ b/rs/moq-archive/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.0.9](https://github.com/moq-dev/moq/compare/moq-archive-v0.0.8...moq-archive-v0.0.9) - 2026-09-30 + +### Other + +- updated the following local packages: moq-net + ## [0.0.8](https://github.com/moq-dev/moq/compare/moq-archive-v0.0.7...moq-archive-v0.0.8) - 2026-09-27 ### Other diff --git a/rs/moq-archive/Cargo.toml b/rs/moq-archive/Cargo.toml index 6aaee0878b5..67c7a6431fe 100644 --- a/rs/moq-archive/Cargo.toml +++ b/rs/moq-archive/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.0.8" +version = "0.0.9" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-audio/CHANGELOG.md b/rs/moq-audio/CHANGELOG.md index 6d63a2edf1f..6171b073ea2 100644 --- a/rs/moq-audio/CHANGELOG.md +++ b/rs/moq-audio/CHANGELOG.md @@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.1.8](https://github.com/moq-dev/moq/compare/moq-audio-v0.1.7...moq-audio-v0.1.8) - 2026-09-30 + +### Fixed + +- *(audio)* conceal one Opus packet's length for a lost packet, not 120 ms ([#4442](https://github.com/moq-dev/moq/pull/4442)) + +### Other + +- compile the Windows, macOS, and OBS plugin code on every PR ([#4370](https://github.com/moq-dev/moq/pull/4370)) + ## [0.1.7](https://github.com/moq-dev/moq/compare/moq-audio-v0.1.6...moq-audio-v0.1.7) - 2026-09-27 ### Other diff --git a/rs/moq-audio/Cargo.toml b/rs/moq-audio/Cargo.toml index b0bdca9aaf8..930600d357d 100644 --- a/rs/moq-audio/Cargo.toml +++ b/rs/moq-audio/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.1.7" +version = "0.1.8" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-auth/CHANGELOG.md b/rs/moq-auth/CHANGELOG.md index 20fd5c973d5..088e9e919d1 100644 --- a/rs/moq-auth/CHANGELOG.md +++ b/rs/moq-auth/CHANGELOG.md @@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.2.0](https://github.com/moq-dev/moq/compare/moq-auth-v0.1.5...moq-auth-v0.2.0) - 2026-09-30 + +### Added + +- *(net)* read a subtree through an origin mount ([#4271](https://github.com/moq-dev/moq/pull/4271)) + +### Fixed + +- *(hls,auth)* redact credentials from URLs in errors ([#4536](https://github.com/moq-dev/moq/pull/4536)) +- *(auth)* make grant expiry exact, dropping the clock-skew grace ([#4368](https://github.com/moq-dev/moq/pull/4368)) +- *(auth)* admit a SETUP token equal to the jwt query ([#4359](https://github.com/moq-dev/moq/pull/4359)) +- *(auth)* [**breaking**] restore 0.14 auth parity ([#4319](https://github.com/moq-dev/moq/pull/4319)) + +### Other + +- *(auth)* run the outage tests on a paused clock without sockets ([#4527](https://github.com/moq-dev/moq/pull/4527)) + ## [0.1.5](https://github.com/moq-dev/moq/compare/moq-auth-v0.1.4...moq-auth-v0.1.5) - 2026-09-27 ### Added diff --git a/rs/moq-auth/Cargo.toml b/rs/moq-auth/Cargo.toml index d0c3196e106..7e0f3c7d88e 100644 --- a/rs/moq-auth/Cargo.toml +++ b/rs/moq-auth/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley"] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.1.5" +version = "0.2.0" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-binary/CHANGELOG.md b/rs/moq-binary/CHANGELOG.md index 23d61fa49e9..96ccc5f7921 100644 --- a/rs/moq-binary/CHANGELOG.md +++ b/rs/moq-binary/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.1.8](https://github.com/moq-dev/moq/compare/moq-binary-v0.1.7...moq-binary-v0.1.8) - 2026-09-30 + +### Other + +- updated the following local packages: kio, moq-net + ## [0.1.7](https://github.com/moq-dev/moq/compare/moq-binary-v0.1.6...moq-binary-v0.1.7) - 2026-09-27 ### Added diff --git a/rs/moq-binary/Cargo.toml b/rs/moq-binary/Cargo.toml index 439d2ea6eba..118a8ad600a 100644 --- a/rs/moq-binary/Cargo.toml +++ b/rs/moq-binary/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.1.7" +version = "0.1.8" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-boy/CHANGELOG.md b/rs/moq-boy/CHANGELOG.md index 5aed50492d3..289a77154ac 100644 --- a/rs/moq-boy/CHANGELOG.md +++ b/rs/moq-boy/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.5.9](https://github.com/moq-dev/moq/compare/moq-boy-v0.5.8...moq-boy-v0.5.9) - 2026-09-30 + +### Other + +- update Cargo.lock dependencies + ## [0.5.8](https://github.com/moq-dev/moq/compare/moq-boy-v0.5.7...moq-boy-v0.5.8) - 2026-09-27 ### Other diff --git a/rs/moq-boy/Cargo.toml b/rs/moq-boy/Cargo.toml index 71be7defbfe..53102aa218f 100644 --- a/rs/moq-boy/Cargo.toml +++ b/rs/moq-boy/Cargo.toml @@ -7,7 +7,7 @@ license = "MIT OR Apache-2.0" keywords = ["moq", "gameboy", "streaming", "emulator", "live"] categories = ["multimedia::video", "emulators", "network-programming"] -version = "0.5.8" +version = "0.5.9" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-cli/CHANGELOG.md b/rs/moq-cli/CHANGELOG.md index 30b677f4948..26e7e140565 100644 --- a/rs/moq-cli/CHANGELOG.md +++ b/rs/moq-cli/CHANGELOG.md @@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.13.0](https://github.com/moq-dev/moq/compare/moq-cli-v0.12.8...moq-cli-v0.13.0) - 2026-09-30 + +### Added + +- *(srt)* select a program of a multi-program feed ([#4569](https://github.com/moq-dev/moq/pull/4569)) +- *(cli)* linger export ts across a broadcast that leaves and returns ([#4504](https://github.com/moq-dev/moq/pull/4504)) +- *(ts)* import one program of a multiplex, or each as its own broadcast ([#4505](https://github.com/moq-dev/moq/pull/4505)) +- *(srt)* log the TS importer's per-stream counters on ingest ([#4506](https://github.com/moq-dev/moq/pull/4506)) +- *(mux)* report every TS elementary stream's access units and quiet time ([#4502](https://github.com/moq-dev/moq/pull/4502)) +- *(net)* drain queued stream data before a graceful close ([#4430](https://github.com/moq-dev/moq/pull/4430)) + +### Fixed + +- *(cli)* refuse every MoQ-side flag a verb never reads ([#4419](https://github.com/moq-dev/moq/pull/4419)) +- *(cli)* refuse a client CA under --auth-public on a listener ([#4364](https://github.com/moq-dev/moq/pull/4364)) +- *(cli)* schedule play decode by the earliest owed picture ([#4374](https://github.com/moq-dev/moq/pull/4374)) +- *(auth)* [**breaking**] restore 0.14 auth parity ([#4319](https://github.com/moq-dev/moq/pull/4319)) + +### Other + +- flush quiet audio in the documented ffmpeg MPEG-TS line ([#4514](https://github.com/moq-dev/moq/pull/4514)) + ## [0.12.8](https://github.com/moq-dev/moq/compare/moq-cli-v0.12.7...moq-cli-v0.12.8) - 2026-09-27 ### Fixed diff --git a/rs/moq-cli/Cargo.toml b/rs/moq-cli/Cargo.toml index 5a04e95d909..a5e612bf45b 100644 --- a/rs/moq-cli/Cargo.toml +++ b/rs/moq-cli/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.12.8" +version = "0.13.0" edition = "2024" # Depends on moq-relay, whose sysinfo 0.39 needs 1.95, above the 1.91 workspace # floor. This binary is an application, so the bump stays here rather than diff --git a/rs/moq-e2ee/CHANGELOG.md b/rs/moq-e2ee/CHANGELOG.md index e51500a8edb..7f837ccb64e 100644 --- a/rs/moq-e2ee/CHANGELOG.md +++ b/rs/moq-e2ee/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.0.9](https://github.com/moq-dev/moq/compare/moq-e2ee-v0.0.8...moq-e2ee-v0.0.9) - 2026-09-30 + +### Other + +- updated the following local packages: kio, moq-net + ## [0.0.8](https://github.com/moq-dev/moq/compare/moq-e2ee-v0.0.7...moq-e2ee-v0.0.8) - 2026-09-27 ### Other diff --git a/rs/moq-e2ee/Cargo.toml b/rs/moq-e2ee/Cargo.toml index 7ae4e28b5ef..1719fc078b1 100644 --- a/rs/moq-e2ee/Cargo.toml +++ b/rs/moq-e2ee/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.0.8" +version = "0.0.9" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-ffi/CHANGELOG.md b/rs/moq-ffi/CHANGELOG.md index 982b8aa4713..9094c0b3521 100644 --- a/rs/moq-ffi/CHANGELOG.md +++ b/rs/moq-ffi/CHANGELOG.md @@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.4.9](https://github.com/moq-dev/moq/compare/moq-ffi-v0.4.8...moq-ffi-v0.4.9) - 2026-09-30 + +### Added + +- *(ffi)* Python, Go, and Dart print MoqError's Rust message ([#4433](https://github.com/moq-dev/moq/pull/4433)) + +### Fixed + +- *(net)* an origin::Dynamic keeps its origin alive ([#4417](https://github.com/moq-dev/moq/pull/4417)) + ## [0.4.8](https://github.com/moq-dev/moq/compare/moq-ffi-v0.4.7...moq-ffi-v0.4.8) - 2026-09-27 ### Added diff --git a/rs/moq-ffi/Cargo.toml b/rs/moq-ffi/Cargo.toml index 7238d5dad46..2942e247eb6 100644 --- a/rs/moq-ffi/Cargo.toml +++ b/rs/moq-ffi/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley ", "Brian Medley " repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.4.8" +version = "0.4.9" edition = "2024" keywords = ["quic", "http3", "webtransport", "media", "live"] diff --git a/rs/moq-gst/CHANGELOG.md b/rs/moq-gst/CHANGELOG.md index f8d3f075ee0..d81fa4a9e94 100644 --- a/rs/moq-gst/CHANGELOG.md +++ b/rs/moq-gst/CHANGELOG.md @@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.4.9](https://github.com/moq-dev/moq/compare/moq-gst-v0.4.8...moq-gst-v0.4.9) - 2026-09-30 + +### Fixed + +- *(gst)* recover from leading deltas and timestamp rewinds ([#4480](https://github.com/moq-dev/moq/pull/4480)) +- *(moq-gst)* moqsrc waits for its session to end on stop ([#4416](https://github.com/moq-dev/moq/pull/4416)) +- *(gst)* keep waiting for a keyframe after a header-only buffer ([#4356](https://github.com/moq-dev/moq/pull/4356)) + +### Other + +- one rpm repo command that works on DNF4 and DNF5 ([#4567](https://github.com/moq-dev/moq/pull/4567)) + ## [0.4.8](https://github.com/moq-dev/moq/compare/moq-gst-v0.4.7...moq-gst-v0.4.8) - 2026-09-27 ### Other diff --git a/rs/moq-gst/Cargo.toml b/rs/moq-gst/Cargo.toml index 7adbdccd526..d3d5b33448e 100644 --- a/rs/moq-gst/Cargo.toml +++ b/rs/moq-gst/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley"] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.4.8" +version = "0.4.9" edition = "2024" rust-version.workspace = true publish = true diff --git a/rs/moq-hls/CHANGELOG.md b/rs/moq-hls/CHANGELOG.md index e8c40609215..21315716c38 100644 --- a/rs/moq-hls/CHANGELOG.md +++ b/rs/moq-hls/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.5.9](https://github.com/moq-dev/moq/compare/moq-hls-v0.5.8...moq-hls-v0.5.9) - 2026-09-30 + +### Fixed + +- *(hls,auth)* redact credentials from URLs in errors ([#4536](https://github.com/moq-dev/moq/pull/4536)) + ## [0.5.8](https://github.com/moq-dev/moq/compare/moq-hls-v0.5.7...moq-hls-v0.5.8) - 2026-09-27 ### Other diff --git a/rs/moq-hls/Cargo.toml b/rs/moq-hls/Cargo.toml index 47b2a92d4de..122ad928b4f 100644 --- a/rs/moq-hls/Cargo.toml +++ b/rs/moq-hls/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.5.8" +version = "0.5.9" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-json/CHANGELOG.md b/rs/moq-json/CHANGELOG.md index 3fe1b6d5a7e..66b8c0045aa 100644 --- a/rs/moq-json/CHANGELOG.md +++ b/rs/moq-json/CHANGELOG.md @@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.5.6](https://github.com/moq-dev/moq/compare/moq-json-v0.5.5...moq-json-v0.5.6) - 2026-09-30 + +### Fixed + +- *(net)* keep an aborted track's finished groups, expire ended tracks ([#4378](https://github.com/moq-dev/moq/pull/4378)) + +### Other + +- *(json)* prove the Rust snapshot gate measures the encoded delta ([#4462](https://github.com/moq-dev/moq/pull/4462)) + ## [0.5.5](https://github.com/moq-dev/moq/compare/moq-json-v0.5.4...moq-json-v0.5.5) - 2026-09-27 ### Added diff --git a/rs/moq-json/Cargo.toml b/rs/moq-json/Cargo.toml index 62dc702b489..1a4b0dbf455 100644 --- a/rs/moq-json/Cargo.toml +++ b/rs/moq-json/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.5.5" +version = "0.5.6" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-loc/CHANGELOG.md b/rs/moq-loc/CHANGELOG.md index 851eb1a60dd..f9919b8a870 100644 --- a/rs/moq-loc/CHANGELOG.md +++ b/rs/moq-loc/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.2.17](https://github.com/moq-dev/moq/compare/moq-loc-v0.2.16...moq-loc-v0.2.17) - 2026-09-30 + +### Other + +- updated the following local packages: moq-net + ## [0.2.16](https://github.com/moq-dev/moq/compare/moq-loc-v0.2.15...moq-loc-v0.2.16) - 2026-09-27 ### Other diff --git a/rs/moq-loc/Cargo.toml b/rs/moq-loc/Cargo.toml index ca491c7795b..9b254acd5d9 100644 --- a/rs/moq-loc/Cargo.toml +++ b/rs/moq-loc/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.2.16" +version = "0.2.17" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-mux/CHANGELOG.md b/rs/moq-mux/CHANGELOG.md index f4ef743a18e..3b1f6bac4a3 100644 --- a/rs/moq-mux/CHANGELOG.md +++ b/rs/moq-mux/CHANGELOG.md @@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.10.9](https://github.com/moq-dev/moq/compare/moq-mux-v0.10.8...moq-mux-v0.10.9) - 2026-09-30 + +### Added + +- *(srt)* select a program of a multi-program feed ([#4569](https://github.com/moq-dev/moq/pull/4569)) +- *(moq-mux)* estimate the catalog framerate ([#4576](https://github.com/moq-dev/moq/pull/4576)) +- *(cli)* linger export ts across a broadcast that leaves and returns ([#4504](https://github.com/moq-dev/moq/pull/4504)) +- *(ts)* import one program of a multiplex, or each as its own broadcast ([#4505](https://github.com/moq-dev/moq/pull/4505)) +- *(srt)* log the TS importer's per-stream counters on ingest ([#4506](https://github.com/moq-dev/moq/pull/4506)) +- *(mux)* report every TS elementary stream's access units and quiet time ([#4502](https://github.com/moq-dev/moq/pull/4502)) + +### Fixed + +- *(moq-mux)* signal a new time base when the DTS reserve steps the PCR back ([#4574](https://github.com/moq-dev/moq/pull/4574)) +- *(mux)* publish the 48 kHz decoder rate for Opus imports ([#4443](https://github.com/moq-dev/moq/pull/4443)) +- *(mux)* follow the stream's reorder depth in TS export ([#4500](https://github.com/moq-dev/moq/pull/4500)) +- *(mux)* rebind single-track FLV export to a better rendition before the header ([#4445](https://github.com/moq-dev/moq/pull/4445)) +- *(mux)* LOC video groups end with the duration marker ([#4450](https://github.com/moq-dev/moq/pull/4450)) + ## [0.10.8](https://github.com/moq-dev/moq/compare/moq-mux-v0.10.7...moq-mux-v0.10.8) - 2026-09-27 ### Added diff --git a/rs/moq-mux/Cargo.toml b/rs/moq-mux/Cargo.toml index 5828a2b46af..846a02b873e 100644 --- a/rs/moq-mux/Cargo.toml +++ b/rs/moq-mux/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.10.8" +version = "0.10.9" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-net/CHANGELOG.md b/rs/moq-net/CHANGELOG.md index e60aef120ec..08e8bc428d2 100644 --- a/rs/moq-net/CHANGELOG.md +++ b/rs/moq-net/CHANGELOG.md @@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.3.8](https://github.com/moq-dev/moq/compare/moq-net-v0.3.7...moq-net-v0.3.8) - 2026-09-30 + +### Added + +- *(lite)* moq-lite-07 switches to 64-bit leading-ones varints ([#4455](https://github.com/moq-dev/moq/pull/4455)) +- *(net)* BigInt-free varint codec, internal U64, and checked Varint.decode ([#4454](https://github.com/moq-dev/moq/pull/4454)) +- *(net)* drain queued stream data before a graceful close ([#4430](https://github.com/moq-dev/moq/pull/4430)) +- *(net)* read a subtree through an origin mount ([#4271](https://github.com/moq-dev/moq/pull/4271)) + +### Fixed + +- *(net)* send the AUTHORITY setup option from moqt:// clients ([#4578](https://github.com/moq-dev/moq/pull/4578)) +- *(net)* re-resolve a splice successor on every judgment +- *(net)* preserve cached history for late relay subscribers ([#4472](https://github.com/moq-dev/moq/pull/4472)) +- *(net)* align IETF object extension limits ([#4475](https://github.com/moq-dev/moq/pull/4475)) +- *(net)* cancel an unwanted lite track still waiting on TRACK_INFO ([#4494](https://github.com/moq-dev/moq/pull/4494)) +- *(net)* skip announce updates the peer cannot tell apart ([#4423](https://github.com/moq-dev/moq/pull/4423)) +- *(net)* an origin::Dynamic keeps its origin alive ([#4417](https://github.com/moq-dev/moq/pull/4417)) +- *(net)* resolve a relayed subscription's start from its source ([#4387](https://github.com/moq-dev/moq/pull/4387)) +- *(moq-net)* hide routes through a peer that withdrew the prefix ([#4399](https://github.com/moq-dev/moq/pull/4399)) +- *(net)* forget spliced tracks unread for the linger, finished ones included ([#4361](https://github.com/moq-dev/moq/pull/4361)) +- *(net)* select scoped routes after filtering, not before ([#4363](https://github.com/moq-dev/moq/pull/4363)) +- *(net)* refuse chained and wildcard origin mounts in any order ([#4362](https://github.com/moq-dev/moq/pull/4362)) +- *(net)* keep an aborted track's finished groups, expire ended tracks ([#4378](https://github.com/moq-dev/moq/pull/4378)) +- *(net)* keep a settled track's groups when it is aborted ([#4351](https://github.com/moq-dev/moq/pull/4351)) + +### Other + +- *(moq-net)* watch mesh_withdraw's cursor from its own task ([#4564](https://github.com/moq-dev/moq/pull/4564)) +- Merge pull request #4561 from moq-dev/quest/m1/cluster-publisher-in-place +- Merge pull request #4484 from moq-dev/quest/m1/splice-edges +- Merge remote-tracking branch 'origin/main' into quest/m1/splice-edges +- *(quest)* drop suffix-based routing from the plans ([#4382](https://github.com/moq-dev/moq/pull/4382)) + ## [0.3.7](https://github.com/moq-dev/moq/compare/moq-net-v0.3.6...moq-net-v0.3.7) - 2026-09-27 ### Added diff --git a/rs/moq-net/Cargo.toml b/rs/moq-net/Cargo.toml index e4c2c85c5fc..f5b82dcb394 100644 --- a/rs/moq-net/Cargo.toml +++ b/rs/moq-net/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley"] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.3.7" +version = "0.3.8" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-pattern/CHANGELOG.md b/rs/moq-pattern/CHANGELOG.md index 56c0b699cd8..d1dc2a02d59 100644 --- a/rs/moq-pattern/CHANGELOG.md +++ b/rs/moq-pattern/CHANGELOG.md @@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.1.2](https://github.com/moq-dev/moq/compare/moq-pattern-v0.1.1...moq-pattern-v0.1.2) - 2026-09-30 + +### Fixed + +- *(pattern)* JS subtree of a max-depth path is the path itself ([#4360](https://github.com/moq-dev/moq/pull/4360)) + +### Other + +- *(quest)* drop suffix-based routing from the plans ([#4382](https://github.com/moq-dev/moq/pull/4382)) + ## [0.1.1](https://github.com/moq-dev/moq/compare/moq-pattern-v0.1.0...moq-pattern-v0.1.1) - 2026-09-27 ### Fixed diff --git a/rs/moq-pattern/Cargo.toml b/rs/moq-pattern/Cargo.toml index 6a3d8af3ba2..bd2f54d7d02 100644 --- a/rs/moq-pattern/Cargo.toml +++ b/rs/moq-pattern/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley"] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.1.1" +version = "0.1.2" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-relay/CHANGELOG.md b/rs/moq-relay/CHANGELOG.md index 01140559d4d..fc16d19fd0c 100644 --- a/rs/moq-relay/CHANGELOG.md +++ b/rs/moq-relay/CHANGELOG.md @@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.16.0](https://github.com/moq-dev/moq/compare/moq-relay-v0.15.8...moq-relay-v0.16.0) - 2026-09-30 + +### Added + +- *(net)* relays stamp an unknown publisher with a per-connection hop +- *(net)* read a subtree through an origin mount ([#4271](https://github.com/moq-dev/moq/pull/4271)) + +### Fixed + +- *(relay)* pass packaged service config positionally ([#4469](https://github.com/moq-dev/moq/pull/4469)) +- *(sock)* resolve an ephemeral reuseport group's port with a plain bind ([#4409](https://github.com/moq-dev/moq/pull/4409)) +- *(auth)* make grant expiry exact, dropping the clock-skew grace ([#4368](https://github.com/moq-dev/moq/pull/4368)) +- *(cli)* refuse a client CA under --auth-public on a listener ([#4364](https://github.com/moq-dev/moq/pull/4364)) +- *(net)* refuse chained and wildcard origin mounts in any order ([#4362](https://github.com/moq-dev/moq/pull/4362)) +- *(auth)* [**breaking**] restore 0.14 auth parity ([#4319](https://github.com/moq-dev/moq/pull/4319)) + +### Other + +- one rpm repo command that works on DNF4 and DNF5 ([#4567](https://github.com/moq-dev/moq/pull/4567)) +- Merge remote-tracking branch 'origin/main' into quest/m1/cluster-publisher-in-place +- prove stopped relays and worker groups closed their sockets instead of racing a rebind ([#4408](https://github.com/moq-dev/moq/pull/4408)) + ## [0.15.8](https://github.com/moq-dev/moq/compare/moq-relay-v0.15.7...moq-relay-v0.15.8) - 2026-09-27 ### Added diff --git a/rs/moq-relay/Cargo.toml b/rs/moq-relay/Cargo.toml index 14b5c5c5675..2f77c34c965 100644 --- a/rs/moq-relay/Cargo.toml +++ b/rs/moq-relay/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley"] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.15.8" +version = "0.16.0" edition = "2024" # sysinfo 0.39 (cache governor cgroup limits) needs 1.95, above the 1.91 # workspace floor. moq-relay is lib+bin, so this applies to its library target diff --git a/rs/moq-room/CHANGELOG.md b/rs/moq-room/CHANGELOG.md index 8f4460b0811..87e6ec7dbe0 100644 --- a/rs/moq-room/CHANGELOG.md +++ b/rs/moq-room/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.2.9](https://github.com/moq-dev/moq/compare/moq-room-v0.2.8...moq-room-v0.2.9) - 2026-09-30 + +### Other + +- updated the following local packages: kio, moq-net, moq-json, moq-auth + ## [0.2.8](https://github.com/moq-dev/moq/compare/moq-room-v0.2.7...moq-room-v0.2.8) - 2026-09-27 ### Other diff --git a/rs/moq-room/Cargo.toml b/rs/moq-room/Cargo.toml index e7e0fc2be66..3236d412453 100644 --- a/rs/moq-room/Cargo.toml +++ b/rs/moq-room/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.2.8" +version = "0.2.9" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-rtc/CHANGELOG.md b/rs/moq-rtc/CHANGELOG.md index c5a89cf0702..093948f385e 100644 --- a/rs/moq-rtc/CHANGELOG.md +++ b/rs/moq-rtc/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.3.9](https://github.com/moq-dev/moq/compare/moq-rtc-v0.3.8...moq-rtc-v0.3.9) - 2026-09-30 + +### Fixed + +- *(rtc)* redact WHIP and WHEP client URLs in logs ([#4457](https://github.com/moq-dev/moq/pull/4457)) + ## [0.3.8](https://github.com/moq-dev/moq/compare/moq-rtc-v0.3.7...moq-rtc-v0.3.8) - 2026-09-27 ### Fixed diff --git a/rs/moq-rtc/Cargo.toml b/rs/moq-rtc/Cargo.toml index 350c4cd9525..26c8fe067a1 100644 --- a/rs/moq-rtc/Cargo.toml +++ b/rs/moq-rtc/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.3.8" +version = "0.3.9" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-rtmp/CHANGELOG.md b/rs/moq-rtmp/CHANGELOG.md index f81ac82a2c3..27f11dff101 100644 --- a/rs/moq-rtmp/CHANGELOG.md +++ b/rs/moq-rtmp/CHANGELOG.md @@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.3.9](https://github.com/moq-dev/moq/compare/moq-rtmp-v0.3.8...moq-rtmp-v0.3.9) - 2026-09-30 + +### Added + +- *(rtmp)* let an RTMP listener refuse plaintext ([#4452](https://github.com/moq-dev/moq/pull/4452)) + +### Fixed + +- *(rtmp)* bound AMF0 nesting ([#4471](https://github.com/moq-dev/moq/pull/4471)) + ## [0.3.8](https://github.com/moq-dev/moq/compare/moq-rtmp-v0.3.7...moq-rtmp-v0.3.8) - 2026-09-27 ### Fixed diff --git a/rs/moq-rtmp/Cargo.toml b/rs/moq-rtmp/Cargo.toml index 581afd698cf..a94613dbe36 100644 --- a/rs/moq-rtmp/Cargo.toml +++ b/rs/moq-rtmp/Cargo.toml @@ -8,7 +8,7 @@ repository = "https://github.com/moq-dev/moq" # src/rml/LICENSE and applies to that module regardless of which option you pick. license = "MIT OR Apache-2.0" -version = "0.3.8" +version = "0.3.9" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-sock/CHANGELOG.md b/rs/moq-sock/CHANGELOG.md index 83cfd9f669c..fc7166fedf8 100644 --- a/rs/moq-sock/CHANGELOG.md +++ b/rs/moq-sock/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.2.0](https://github.com/moq-dev/moq/compare/moq-sock-v0.1.0...moq-sock-v0.2.0) - 2026-09-30 + +### Fixed + +- *(sock)* resolve an ephemeral reuseport group's port with a plain bind ([#4409](https://github.com/moq-dev/moq/pull/4409)) + ## [0.0.1](https://github.com/moq-dev/moq/releases/tag/moq-sock-v0.0.1) - 2026-09-23 ### Added diff --git a/rs/moq-sock/Cargo.toml b/rs/moq-sock/Cargo.toml index c86336f496d..91ebb7c37c0 100644 --- a/rs/moq-sock/Cargo.toml +++ b/rs/moq-sock/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.1.0" +version = "0.2.0" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-srt/CHANGELOG.md b/rs/moq-srt/CHANGELOG.md index 9d9defe076d..0f662f86fa7 100644 --- a/rs/moq-srt/CHANGELOG.md +++ b/rs/moq-srt/CHANGELOG.md @@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.3.9](https://github.com/moq-dev/moq/compare/moq-srt-v0.3.8...moq-srt-v0.3.9) - 2026-09-30 + +### Added + +- *(srt)* select a program of a multi-program feed ([#4569](https://github.com/moq-dev/moq/pull/4569)) +- *(srt)* log the TS importer's per-stream counters on ingest ([#4506](https://github.com/moq-dev/moq/pull/4506)) + ## [0.3.8](https://github.com/moq-dev/moq/compare/moq-srt-v0.3.7...moq-srt-v0.3.8) - 2026-09-27 ### Other diff --git a/rs/moq-srt/Cargo.toml b/rs/moq-srt/Cargo.toml index d6f5899d543..5d2de7b09a3 100644 --- a/rs/moq-srt/Cargo.toml +++ b/rs/moq-srt/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.3.8" +version = "0.3.9" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-stats/CHANGELOG.md b/rs/moq-stats/CHANGELOG.md index 4143caec728..bc61f5af033 100644 --- a/rs/moq-stats/CHANGELOG.md +++ b/rs/moq-stats/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.2.9](https://github.com/moq-dev/moq/compare/moq-stats-v0.2.8...moq-stats-v0.2.9) - 2026-09-30 + +### Other + +- updated the following local packages: moq-net, moq-json + ## [0.2.8](https://github.com/moq-dev/moq/compare/moq-stats-v0.2.7...moq-stats-v0.2.8) - 2026-09-27 ### Fixed diff --git a/rs/moq-stats/Cargo.toml b/rs/moq-stats/Cargo.toml index d2ba4ac4286..cb73eec320f 100644 --- a/rs/moq-stats/Cargo.toml +++ b/rs/moq-stats/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.2.8" +version = "0.2.9" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-tokio/CHANGELOG.md b/rs/moq-tokio/CHANGELOG.md index d89727bf475..0221b4f6dfb 100644 --- a/rs/moq-tokio/CHANGELOG.md +++ b/rs/moq-tokio/CHANGELOG.md @@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.19.20](https://github.com/moq-dev/moq/compare/moq-tokio-v0.19.19...moq-tokio-v0.19.20) - 2026-09-30 + +### Added + +- *(net)* drain queued stream data before a graceful close ([#4430](https://github.com/moq-dev/moq/pull/4430)) + +### Fixed + +- *(net)* send the AUTHORITY setup option from moqt:// clients ([#4578](https://github.com/moq-dev/moq/pull/4578)) +- *(moq-net)* a group awaiting its FIN ack still expires and follows priority ([#4534](https://github.com/moq-dev/moq/pull/4534)) +- *(tokio)* drive raw stream handshakes per connection ([#4474](https://github.com/moq-dev/moq/pull/4474)) +- *(moq-tokio)* iroh honors the configured versions ([#4448](https://github.com/moq-dev/moq/pull/4448)) +- *(tokio)* keep a WebTransport session's H3 streams open while it closes ([#4429](https://github.com/moq-dev/moq/pull/4429)) +- *(tokio)* drain a GOAWAY predecessor on Connection::close ([#4436](https://github.com/moq-dev/moq/pull/4436)) +- *(sock)* resolve an ephemeral reuseport group's port with a plain bind ([#4409](https://github.com/moq-dev/moq/pull/4409)) +- *(tokio)* handle IPv6 literals in TLS server names ([#4322](https://github.com/moq-dev/moq/pull/4322)) +- *(tokio)* accept a bare IPv6 TLS host name override on WebSocket ([#4405](https://github.com/moq-dev/moq/pull/4405)) + +### Other + +- *(tokio)* isolate TLS root reload tests from shared /tmp ([#4537](https://github.com/moq-dev/moq/pull/4537)) +- *(tokio)* match a worker group's full address when counting its sockets ([#4404](https://github.com/moq-dev/moq/pull/4404)) +- prove stopped relays and worker groups closed their sockets instead of racing a rebind ([#4408](https://github.com/moq-dev/moq/pull/4408)) + ## [0.19.19](https://github.com/moq-dev/moq/compare/moq-tokio-v0.19.18...moq-tokio-v0.19.19) - 2026-09-27 ### Added diff --git a/rs/moq-tokio/Cargo.toml b/rs/moq-tokio/Cargo.toml index 7e15142f966..4e1042c5183 100644 --- a/rs/moq-tokio/Cargo.toml +++ b/rs/moq-tokio/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley"] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.19.19" +version = "0.19.20" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-transcode/CHANGELOG.md b/rs/moq-transcode/CHANGELOG.md index a8fe965b83d..9e7b6b3dec6 100644 --- a/rs/moq-transcode/CHANGELOG.md +++ b/rs/moq-transcode/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.1.8](https://github.com/moq-dev/moq/compare/moq-transcode-v0.1.7...moq-transcode-v0.1.8) - 2026-09-30 + +### Other + +- updated the following local packages: kio, moq-net, moq-mux, moq-video, hang + ## [0.1.7](https://github.com/moq-dev/moq/compare/moq-transcode-v0.1.6...moq-transcode-v0.1.7) - 2026-09-27 ### Fixed diff --git a/rs/moq-transcode/Cargo.toml b/rs/moq-transcode/Cargo.toml index 2c34597c758..8fcb88f393e 100644 --- a/rs/moq-transcode/Cargo.toml +++ b/rs/moq-transcode/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.1.7" +version = "0.1.8" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-uring/CHANGELOG.md b/rs/moq-uring/CHANGELOG.md index 7e87c776dfa..f795ee763d5 100644 --- a/rs/moq-uring/CHANGELOG.md +++ b/rs/moq-uring/CHANGELOG.md @@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.0.10](https://github.com/moq-dev/moq/compare/moq-uring-v0.0.9...moq-uring-v0.0.10) - 2026-09-30 + +### Fixed + +- *(uring)* publish a local close only once its CONNECTION_CLOSE is staged ([#4431](https://github.com/moq-dev/moq/pull/4431)) + +### Other + +- *(uring)* noq paces inside poll_transmit, not ignored ([#4400](https://github.com/moq-dev/moq/pull/4400)) + ## [0.0.9](https://github.com/moq-dev/moq/compare/moq-uring-v0.0.8...moq-uring-v0.0.9) - 2026-09-27 ### Other diff --git a/rs/moq-uring/Cargo.toml b/rs/moq-uring/Cargo.toml index af9e9fd8e07..8c0eeaeb6c2 100644 --- a/rs/moq-uring/Cargo.toml +++ b/rs/moq-uring/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.0.9" +version = "0.0.10" edition = "2024" rust-version.workspace = true diff --git a/rs/moq-video/CHANGELOG.md b/rs/moq-video/CHANGELOG.md index 70f717d661a..a9a69ce909b 100644 --- a/rs/moq-video/CHANGELOG.md +++ b/rs/moq-video/CHANGELOG.md @@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.1.8](https://github.com/moq-dev/moq/compare/moq-video-v0.1.7...moq-video-v0.1.8) - 2026-09-30 + +### Fixed + +- *(video)* list V4L2 cameras once with PipeWire ([#4488](https://github.com/moq-dev/moq/pull/4488)) +- *(video)* guard portal sessions during negotiation ([#4492](https://github.com/moq-dev/moq/pull/4492)) +- *(video)* re-anchor native capture above its last timestamp ([#4418](https://github.com/moq-dev/moq/pull/4418)) + +### Other + +- compile the Windows, macOS, and OBS plugin code on every PR ([#4370](https://github.com/moq-dev/moq/pull/4370)) + ## [0.1.7](https://github.com/moq-dev/moq/compare/moq-video-v0.1.6...moq-video-v0.1.7) - 2026-09-27 ### Fixed diff --git a/rs/moq-video/Cargo.toml b/rs/moq-video/Cargo.toml index aa8b4f8b9d4..867d71e8a2e 100644 --- a/rs/moq-video/Cargo.toml +++ b/rs/moq-video/Cargo.toml @@ -5,7 +5,7 @@ authors = ["Luke Curley "] repository = "https://github.com/moq-dev/moq" license = "MIT OR Apache-2.0" -version = "0.1.7" +version = "0.1.8" edition = "2024" rust-version.workspace = true From 2b58fcb9050a6d7fd30d6352ed54e85d23ba6928 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 09:22:56 -0700 Subject: [PATCH 109/128] feat(audio): backend seams, surround layouts, and AAC encode (audio-codecs line) (#4081) Co-authored-by: Claude Opus 5.5 Co-authored-by: Grok 4.7 --- doc/bin/cli.md | 13 +- doc/lib/c/index.md | 3 +- doc/lib/go/index.md | 12 + doc/lib/kt/index.md | 13 +- doc/lib/py/index.md | 13 +- doc/lib/rs/moq-audio.md | 54 +- doc/lib/rs/moq-mux.md | 2 +- doc/lib/swift/index.md | 13 +- go/wrapper/publish.go | 2 +- go/wrapper/types.go | 10 +- js/hang/src/util/aac.test.ts | 8 +- js/hang/src/util/aac.ts | 10 +- .../kotlin/dev/moq/Aliases.kt | 2 +- py/moq-rs/README.md | 2 +- py/moq-rs/moq/publish.py | 4 +- ...bandwidth-grant-in-moq-audio-instead-of.md | 14 +- quest/m1/README.md | 11 +- quest/m1/aac-encode-refusals.md | 27 + quest/m1/aac-parse-truncated-sbr.md | 21 + quest/m1/audio-codecs/README.md | 69 -- quest/m1/audio-codecs/aac-pce.md | 34 - quest/m1/audio-codecs/decode-backend.md | 43 -- quest/m1/audio-codecs/encode-audiotoolbox.md | 31 - quest/m1/audio-codecs/encode-backend.md | 50 -- quest/m1/audio-codecs/he-aac-refusal.md | 34 - quest/m1/audio-codecs/layout.md | 51 -- quest/m1/audio-codecs/named-codecs.md | 27 - quest/m1/audio-codecs/opus-surround.md | 26 - ...oolbox.md => audio-decode-audiotoolbox.md} | 19 +- quest/m1/audio-encode-audiotoolbox.md | 37 + quest/m1/cmaf-opus-surround.md | 1 - quest/m1/ffi-frame-duration-default.md | 22 + quest/m1/gst-opus-surround.md | 21 + quest/m1/he-aac-catalog-output.md | 29 + quest/m1/obs-moq-video/README.md | 3 +- quest/m1/obs-moq-video/audio-playback.md | 2 +- quest/m1/obs-moq-video/audio-publish.md | 6 +- quest/m1/opus-mapping-family.md | 8 +- quest/m1/ts-aac-pce-join.md | 31 + quest/m1/ts-opus-channel-codes.md | 27 + quest/m1/ts-opus-export-refusals.md | 23 + quest/m2/audio-decode-mediacodec.md | 2 - quest/m2/audio-decode-mediafoundation.md | 5 - quest/m2/audio-encode-mediacodec.md | 5 +- quest/m2/audio-encode-mediafoundation.md | 2 - rs/libmoq/src/audio.rs | 14 +- rs/moq-audio/Cargo.toml | 2 +- rs/moq-audio/src/aac.rs | 4 +- rs/moq-audio/src/aec.rs | 28 +- rs/moq-audio/src/decode/backend/libopus.rs | 440 +++++++++++ rs/moq-audio/src/decode/backend/mod.rs | 289 +++++++ rs/moq-audio/src/decode/backend/pcm.rs | 78 ++ rs/moq-audio/src/decode/backend/symphonia.rs | 106 +++ rs/moq-audio/src/decode/consumer.rs | 21 +- rs/moq-audio/src/decode/decoder.rs | 386 ++-------- rs/moq-audio/src/decode/mod.rs | 5 +- rs/moq-audio/src/encode/backend/libopus.rs | 207 +++++ rs/moq-audio/src/encode/backend/mod.rs | 336 ++++++++ rs/moq-audio/src/encode/backend/pcm.rs | 55 ++ rs/moq-audio/src/encode/backend/stub.rs | 86 +++ rs/moq-audio/src/encode/capture.rs | 35 +- rs/moq-audio/src/encode/encoder.rs | 715 ++++++++++-------- rs/moq-audio/src/encode/mod.rs | 7 +- rs/moq-audio/src/encode/producer.rs | 91 ++- rs/moq-audio/src/layout.rs | 132 +++- rs/moq-audio/src/lib.rs | 7 +- rs/moq-audio/src/opus.rs | 216 +++++- rs/moq-audio/src/playback.rs | 7 +- rs/moq-audio/src/playback/device.rs | 120 ++- rs/moq-audio/src/playback/driver.rs | 30 +- rs/moq-audio/src/playback/mixer.rs | 205 +++-- rs/moq-audio/src/playback/sink.rs | 170 +++-- rs/moq-audio/src/resample.rs | 271 ++++++- rs/moq-audio/tests/import.rs | 64 ++ rs/moq-audio/tests/roundtrip.rs | 68 ++ rs/moq-cli/src/play/media.rs | 2 +- rs/moq-ffi/src/audio.rs | 32 +- rs/moq-ffi/src/binary.rs | 13 +- rs/moq-ffi/src/test.rs | 54 ++ rs/moq-mux/src/codec/aac/mod.rs | 549 +++++++++++++- rs/moq-mux/src/codec/opus/import.rs | 2 +- rs/moq-mux/src/codec/opus/mapping.rs | 179 +++++ rs/moq-mux/src/codec/opus/mod.rs | 203 +++-- rs/moq-mux/src/container/ts/adts.rs | 64 +- rs/moq-mux/src/container/ts/export.rs | 51 +- rs/moq-mux/src/container/ts/export_test.rs | 144 ++++ rs/moq-mux/src/container/ts/import.rs | 49 +- rs/moq-mux/src/container/ts/import_test.rs | 49 ++ .../src/container/ts/test_data/aac_quad.ts | Bin 0 -> 2632 bytes .../src/container/ts/test_data/he_aac.flv | Bin 0 -> 3110 bytes .../src/container/ts/test_data/he_aac_v2.flv | Bin 0 -> 3297 bytes .../src/container/ts/test_data/opus_5_1.ts | Bin 0 -> 5452 bytes swift/Sources/Moq/Aliases.swift | 2 +- swift/Sources/Moq/Broadcast.swift | 2 +- 94 files changed, 4876 insertions(+), 1556 deletions(-) create mode 100644 quest/m1/aac-encode-refusals.md create mode 100644 quest/m1/aac-parse-truncated-sbr.md delete mode 100644 quest/m1/audio-codecs/README.md delete mode 100644 quest/m1/audio-codecs/aac-pce.md delete mode 100644 quest/m1/audio-codecs/decode-backend.md delete mode 100644 quest/m1/audio-codecs/encode-audiotoolbox.md delete mode 100644 quest/m1/audio-codecs/encode-backend.md delete mode 100644 quest/m1/audio-codecs/he-aac-refusal.md delete mode 100644 quest/m1/audio-codecs/layout.md delete mode 100644 quest/m1/audio-codecs/named-codecs.md delete mode 100644 quest/m1/audio-codecs/opus-surround.md rename quest/m1/{audio-codecs/decode-audiotoolbox.md => audio-decode-audiotoolbox.md} (70%) create mode 100644 quest/m1/audio-encode-audiotoolbox.md create mode 100644 quest/m1/ffi-frame-duration-default.md create mode 100644 quest/m1/gst-opus-surround.md create mode 100644 quest/m1/he-aac-catalog-output.md create mode 100644 quest/m1/ts-aac-pce-join.md create mode 100644 quest/m1/ts-opus-channel-codes.md create mode 100644 quest/m1/ts-opus-export-refusals.md create mode 100644 rs/moq-audio/src/decode/backend/libopus.rs create mode 100644 rs/moq-audio/src/decode/backend/mod.rs create mode 100644 rs/moq-audio/src/decode/backend/pcm.rs create mode 100644 rs/moq-audio/src/decode/backend/symphonia.rs create mode 100644 rs/moq-audio/src/encode/backend/libopus.rs create mode 100644 rs/moq-audio/src/encode/backend/mod.rs create mode 100644 rs/moq-audio/src/encode/backend/pcm.rs create mode 100644 rs/moq-audio/src/encode/backend/stub.rs create mode 100644 rs/moq-audio/tests/import.rs create mode 100644 rs/moq-mux/src/codec/opus/mapping.rs create mode 100644 rs/moq-mux/src/container/ts/test_data/aac_quad.ts create mode 100644 rs/moq-mux/src/container/ts/test_data/he_aac.flv create mode 100644 rs/moq-mux/src/container/ts/test_data/he_aac_v2.flv create mode 100644 rs/moq-mux/src/container/ts/test_data/opus_5_1.ts diff --git a/doc/bin/cli.md b/doc/bin/cli.md index 65c66fa6a8b..d236b883323 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -97,6 +97,11 @@ discarding the old mux buffer. The first new clock packet signals the break and stdout pacing re-anchors. Every rendition joins the new program generation; no track is fenced across the marker. +MPEG-TS export frames AAC as ADTS, which labels only the AAC Main, LC, SSR, +and LTP profiles. HE-AAC and HE-AACv2 go out as their AAC-LC core, and decoders +find the SBR and PS in band, as ffmpeg's ADTS output does. A track whose +profile or channel layout ADTS cannot label is refused rather than mislabeled. + A constant-rate MPEG-TS source records its multiplex rate in the catalog (`mpegts.muxRate`, measured off the PCR clock, null stuffing included), and `export ts` pads its output with null packets back to that rate so an IRD or @@ -118,9 +123,11 @@ moq --connect https://relay.example.com/anon --broadcast my-stream.hang play moq ... play --delay 500ms # trade latency for a jittery link ``` -Decodes H.264, H.265, and AV1 video and Opus, PCM, and AAC-LC audio using -the platform hardware decoder where available. `--video-name` and -`--audio-name` pick a rendition. +Decodes H.264, H.265, and AV1 video using the platform hardware decoder where +available, and Opus, PCM, and AAC-LC (mono or stereo) audio in software. The +log names the decoder each track opened. `--video-name` and `--audio-name` +pick a rendition. HE-AAC signaled only in band (implicit SBR, as over MPEG-TS) +plays as its half-rate AAC-LC core. Playback runs on a clock it owns. `--delay` (default 100 ms) is how far it trails the live edge, which is both the jitter a late frame may absorb and the diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index 7093bd5a4f1..34389a21520 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -39,7 +39,8 @@ pkg-config file included. - **Threading.** Any function from any thread. Raw publish calls block until the codec takes the frame, which paces a publisher. - **Connection health.** `moq_session_stats()` reports available metrics with per-field validity flags. `moq_session_snapshot()` samples those metrics and the negotiated draft name together from the same connection. Its protocol string is backed by static storage. Both return an offline error between reconnects and leave the destination untouched. `moq_session_bandwidth()` mints an allocator over the send estimate; `moq_bandwidth_reserve` claims a share for an app-owned track, and `moq_encode_video` / `moq_encode_audio` take the same handle so the built-in video encoder follows the grant. - **Raw playback.** Raw audio and video consumers start at the newest cached group when opened, so rebuilding a live decoder skips the retained backlog. -- **Raw audio encode.** `moq_audio_encoder_output.codec` names the codec (only `"opus"` today), and `frame_duration_us` sets the Opus frame length: 2500, 5000, 10000, 20000, 40000, or 60000, with 0 meaning the 20 ms default. +- **Raw audio encode.** `moq_audio_encoder_output.codec` names the codec: `"opus"`, `"pcm"`, or `"aac"`. `frame_duration_us` sets the Opus frame length: 2500, 5000, 10000, 20000, 40000, or 60000, with 0 meaning the codec's default (20 ms for Opus, 1024 samples for AAC). AAC-LC encodes through the platform's encoder, so a host without one refuses it. +- **Audio channel layouts.** A `channels` count also names the speaker layout, by the WAVE convention: 1 is mono, 2 stereo, 3 2.1, 4 quad, 5 5.0, 6 5.1, 7 6.1, and 8 7.1, interleaved front left, front right, center, LFE, back, then side. `moq_decode_audio` remixes to the count you ask for; past 8 channels the samples pass through but can't be remixed. - **Raw decode output.** `moq_video_decoder_output` selects the decoded CPU pixel format (`MOQ_VIDEO_PIXEL_FORMAT_I420` or `_RGBA`) and target size (`width`/`height`, both zero for native; otherwise even and non-zero). Unknown formats and invalid sizes fail `moq_decode_video` before subscribing; accepted requests deliver exactly that layout or fail on the terminal callback. - **Encoded video metadata.** `moq_video_init.hint` is a zero-initialized `moq_video_hint` with `has_*` flags for coded dimensions, bitrate (bits per second), frame rate, and latency preference. Hints seed a video codec track's catalog; detected dimensions take precedence. - **Client config.** A zeroed `moq_client_config` means the defaults for every knob, which is what lets a new one be appended without disturbing callers. Fields cover protocol (`versions`), TLS (`tls_fingerprints`, `tls_roots`, `tls_cert`/`_key`, `tls_host_name`), transport (`bind`, `connect_timeout_us`, `failover_delay_us`/`resolution_delay_us` for Happy Eyeballs, `websocket_enabled`/`_delay_us`), and tuning (reconnect backoff, `quic_*`). Every duration is in microseconds. A knob whose default isn't zero carries a `has_*` flag, so setting `backoff_timeout_us = 0` needs `has_backoff_timeout = true` to mean "retry forever" rather than "use the default". `moq_client_defaults()` reports what a NULL config dials with. diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index 040558a94d5..acaf8ac0674 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -124,6 +124,18 @@ one: `FetchGroup`/`FetchMediaGroup`, `Dynamic()` with `Requests(ctx)`, `AppendDatagram`/`Datagrams(ctx)`, `SetCatalogSection`, `Demand()` for `Used`/`Unused`, `Session().Stats()`. `moq.IsAuthError` and `moq.IsShutdown` classify errors. `moq.ProtocolError(err)` is the structured protocol failure (scope, verbatim code, kind) when the peer sent one. `err.Error()` is the Rust error message. +`EncodeAudio` encodes raw PCM inside the binding. Its codec is `OpusAudioCodec()` +or `AacAudioCodec()`, and `AudioEncoderOutput.FrameDurationUs` sets the Opus +frame length: 2500, 5000, 10000, 20000 (the default), 40000, or 60000. 0 takes +the codec's own frame, which AAC needs. AAC-LC encodes through the platform's +encoder, so a host without one refuses it. + +Audio `Channels` also names the speaker layout, by the WAVE convention: 1 is +mono, 2 stereo, 3 2.1, 4 quad, 5 5.0, 6 5.1, 7 6.1, and 8 7.1, interleaved +front left, front right, center, LFE, back, then side. Decoding remixes to the +count you ask for; past 8 channels the samples pass through but can't be +remixed. + `DecodeVideo` picks the decoded CPU pixel layout: `VideoDecoderOutput.Format` is I420 when nil, or `VideoPixelFormatRgba` for four bytes a pixel, and every `VideoDecodedFrame` repeats the layout it was decoded to. `Resize` is best diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index b0581661009..df948961c9b 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -95,8 +95,17 @@ connection's send estimate; pass it to `encodeVideo` / `encodeAudio` or Cancelling the collecting coroutine cancels the native side. `encodeAudio` encodes raw PCM inside the binding. Its codec is an object, -`AudioCodec.opus()`, and `AudioEncoderOutput.frameDurationUs` sets the Opus -frame length: 2500, 5000, 10000, 20000 (the default), 40000, or 60000. +`AudioCodec.opus()` or `AudioCodec.aac()`, and +`AudioEncoderOutput.frameDurationUs` sets the Opus frame length: 2500, 5000, +10000, 20000 (the default), 40000, or 60000. 0 takes the codec's own frame, +which AAC needs. AAC-LC encodes through the platform's encoder, so a host +without one refuses it. + +Audio `channels` also names the speaker layout, by the WAVE convention: 1 is +mono, 2 stereo, 3 2.1, 4 quad, 5 5.0, 6 5.1, 7 6.1, and 8 7.1, interleaved +front left, front right, center, LFE, back, then side. Decoding remixes to the +count you ask for; past 8 channels the samples pass through but can't be +remixed. `decodeVideo` picks the decoded CPU pixel layout: `VideoDecoderOutput.format` is `VideoPixelFormat.I420` when null, or `VideoPixelFormat.RGBA` for four bytes diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index a7d3e1d0f65..5a597e7e336 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -111,8 +111,17 @@ Each server request reports a `moq.Transport` enum, including QUIC, Iroh, WebSocket, TCP, and Unix sockets. `encode_audio` encodes raw PCM inside the binding. Its codec is an object, -`moq.AudioCodec.opus()`, and `AudioEncoderOutput.frame_duration_us` sets the -Opus frame length: 2500, 5000, 10000, 20000 (the default), 40000, or 60000. +`moq.AudioCodec.opus()` or `moq.AudioCodec.aac()`, and +`AudioEncoderOutput.frame_duration_us` sets the Opus frame length: 2500, 5000, +10000, 20000 (the default), 40000, or 60000. 0 takes the codec's own frame, +which AAC needs. AAC-LC encodes through the platform's encoder, so a host +without one refuses it. + +Audio `channels` also names the speaker layout, by the WAVE convention: 1 is +mono, 2 stereo, 3 2.1, 4 quad, 5 5.0, 6 5.1, 7 6.1, and 8 7.1, interleaved +front left, front right, center, LFE, back, then side. Decoding remixes to the +count you ask for; past 8 channels the samples pass through but can't be +remixed. `decode_video` picks the decoded CPU pixel layout: `VideoDecoderOutput.format` is `VideoPixelFormat.I420` when unset, or `VideoPixelFormat.RGBA` for four diff --git a/doc/lib/rs/moq-audio.md b/doc/lib/rs/moq-audio.md index e2185530753..ba5a7256a3b 100644 --- a/doc/lib/rs/moq-audio.md +++ b/doc/lib/rs/moq-audio.md @@ -13,8 +13,14 @@ the far end. Everything is Rust, so there is no C toolchain, CMake step, or codec to install. `Layout` names speaker meaning separately from a channel count. `Mono` is center, -`Stereo` is left then right, and `Discrete(n)` preserves unnamed channels without -inventing speaker positions. Encoding keeps source PCM in `encode::Input` and +`Stereo` is left then right, and the surround layouts up to `SevenPointOne` +interleave in the SMPTE/WAVE order (front left, front right, center, LFE, back, +side). A catalog carries only a count, which reads as that count's WAVE default +(`Layout::from_channels`: 6 is 5.1, 8 is 7.1). `Discrete(n)` preserves unnamed +channels without inventing speaker positions, so it passes through but never +remixes. Decoding and playback downmix with the ITU-R BS.775 coefficients and +upmix by leaving the extra speakers silent; the playback mix runs in whatever +layout the output device opened. Encoding keeps source PCM in `encode::Input` and codec requirements in `encode::Settings`; `encode::Options` adds publication policy. Decoding likewise separates low-level `decode::Config`, PCM `decode::Output`, and subscription `decode::Options`. @@ -22,18 +28,56 @@ policy. Decoding likewise separates low-level `decode::Config`, PCM | Module | Does | | --- | --- | | `capture` | Microphones via CoreAudio, WASAPI, ALSA (and PipeWire/PulseAudio hosts), plus macOS system audio | -| `encode` | PCM to Opus (with DTX and voice-activity signaling) or raw PCM for the lowest latency | +| `encode` | PCM to Opus (with DTX and voice-activity signaling), raw PCM for the lowest latency, or AAC-LC through a platform encoder | | `decode` | Opus, PCM, and AAC-LC back to PCM, resampled to the rate you want | | `playback` | One output device mixing every track in a call, with click-free volume ramps | | `aec` | Acoustic echo cancellation (a port of WebRTC's), so a laptop with no headset doesn't feed itself back | +`decode` picks a backend per track the way `moq-video` does: a platform decoder +first, then software. `decode::Config::kind` narrows it: `Kind::Software` skips +the platform tier, and `Kind::Named` requires the track to be a codec, by its +name (`"opus"`, `"pcm"`, or `"aac"`), and refuses any other. Backends are never +named; `Decoder::name()` reports which one opened. + +| Backend | Decodes | Hosts | +| --- | --- | --- | +| `libopus` | Opus, mono or stereo, and surround up to 7.1 (channel mapping family 1) | all | +| `pcm` | PCM | all | +| `symphonia` | AAC-LC, mono or stereo (the default-on `aac` feature) | all | + +No platform decoder is wired in yet, so multichannel AAC and HE-AAC declared in +its config are refused at construction on every host. HE-AAC signaled only in +band plays as its half-rate LC core. Linux has no OS audio decoder, so it will +stay that way there. Surround Opus is pure Rust, so it is the one multichannel +path every host has. Opus mapping families other than 0 and 1 (ambisonics, and +255's unpositioned channels) are refused, since they declare no speakers. + Opus always decodes at 48 kHz, its own clock, whatever input rate the OpusHead records (44.1 kHz and unknown included), and applies the head's pre-skip and output gain. A track without a description decodes mono or stereo from the catalog with neither. A description that is present but malformed (truncated, wrong signature, a new major version, or a channel count its mapping family -forbids) is refused, as is any channel mapping family other than 0, rather -than falling back to the catalog's fields. +forbids) is refused rather than falling back to the catalog's fields. + +`encode` selects the same way, through `encode::Settings::kind`, where +`Kind::Named` requires `Settings::codec` to match the codec name, and +`Encoder::name()` reports what opened. + +| Backend | Encodes | Hosts | +| --- | --- | --- | +| `libopus` | Opus, mono or stereo | all | +| `pcm` | PCM | all | + +`encode::Codec::Aac` is AAC-LC (`mp4a.40.2`) at the input's rate and layout: +mono, stereo, 3.0, 4.0, 5.0, 5.1, or 7.1, the layouts with an AAC +channelConfiguration. Frames are 1024 samples, so `Settings::from_input` sets +`frame_duration` to match. The catalog's AudioSpecificConfig is built from the +settings when the track is registered, and since it has no field for the +encoder's delay, packets are stamped that much earlier so the first input +sample still lands at the first timestamp. There is no software AAC encoder, +and no platform encoder is wired in yet, so `Codec::Aac` is refused at +construction on every host for now. Linux has no OS encoder, so it will stay +that way there. Highlights: diff --git a/doc/lib/rs/moq-mux.md b/doc/lib/rs/moq-mux.md index 9f6f1408275..85dba3b09cc 100644 --- a/doc/lib/rs/moq-mux.md +++ b/doc/lib/rs/moq-mux.md @@ -14,7 +14,7 @@ Turns existing container formats into hang broadcasts and back. This is what | Format | Import | Export | Notes | | --- | --- | --- | --- | | fMP4 / CMAF | yes | yes | Passthrough as `cmaf` or repackaged as `legacy`. | -| MPEG-TS | yes | yes | H.264/H.265; AAC, MP2, AC-3, E-AC-3; SCTE-35 and subtitle PIDs carried as tracks; service tables round-trip; signalled timebase discontinuities preserved; paced export. | +| MPEG-TS | yes | yes | H.264/H.265; AAC, MP2, AC-3, E-AC-3, Opus up to 7.1; SCTE-35 and subtitle PIDs carried as tracks; service tables round-trip; signalled timebase discontinuities preserved; paced export. | | FLV / RTMP | yes | yes | Legacy H.264 + AAC + MP3, plus enhanced-RTMP HEVC, AV1, VP9, Opus, AC-3, E-AC-3, and multitrack. | | Matroska / WebM | yes | yes | | | Annex-B (H.264, H.265) | yes | yes | Parameter sets extracted to the catalog or re-injected per keyframe. | diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index fb941054928..7fc2f410199 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -100,8 +100,17 @@ divides the connection's send estimate; pass it to `encodeVideo` / the Rust error message. `encodeAudio` encodes raw PCM inside the binding. Its codec is an object, -`AudioCodec.opus()`, and `AudioEncoderOutput.frameDurationUs` sets the Opus -frame length: 2500, 5000, 10000, 20000 (the default), 40000, or 60000. +`AudioCodec.opus()` or `AudioCodec.aac()`, and +`AudioEncoderOutput.frameDurationUs` sets the Opus frame length: 2500, 5000, +10000, 20000 (the default), 40000, or 60000. 0 takes the codec's own frame, +which AAC needs. AAC-LC encodes through the platform's encoder, so a host +without one refuses it. + +Audio `channels` also names the speaker layout, by the WAVE convention: 1 is +mono, 2 stereo, 3 2.1, 4 quad, 5 5.0, 6 5.1, 7 6.1, and 8 7.1, interleaved +front left, front right, center, LFE, back, then side. Decoding remixes to the +count you ask for; past 8 channels the samples pass through but can't be +remixed. `decodeVideo` picks the decoded CPU pixel layout: `VideoDecoderOutput.format` is `.i420` when unset, or `.rgba` for four bytes a pixel, and every frame diff --git a/go/wrapper/publish.go b/go/wrapper/publish.go index 5b668b3e433..f8dbc59e533 100644 --- a/go/wrapper/publish.go +++ b/go/wrapper/publish.go @@ -193,7 +193,7 @@ func (b *BroadcastProducer) PublishContainerStream(format ContainerFormat) (*Con // EncodeAudio publishes a raw-audio track with an in-process encoder. // -// Select the codec with OpusAudioCodec (currently the only constructor). +// Select the codec with OpusAudioCodec or AacAudioCodec. // Pass bandwidth to reserve this track's bitrate against the session's // allocator so a co-resident video encoder sizes itself against what is left. func (b *BroadcastProducer) EncodeAudio(name string, input AudioEncoderInput, output AudioEncoderOutput, bandwidth *Bandwidth) (*AudioProducer, error) { diff --git a/go/wrapper/types.go b/go/wrapper/types.go index 40bf4f53eaa..3c588ba2dfa 100644 --- a/go/wrapper/types.go +++ b/go/wrapper/types.go @@ -8,14 +8,14 @@ import ffi "moq.dev/moq-ffi/moq" type ( // Audio describes one audio rendition in a broadcast catalog: codec, sample rate, channel count, and container. Audio = ffi.MoqAudio - // AudioCodec selects the audio encoder codec. Build one with OpusAudioCodec; + // AudioCodec selects the audio encoder codec. Build one with OpusAudioCodec or AacAudioCodec; // adding a codec later adds a constructor, not a breaking enum change. AudioCodec = ffi.MoqAudioCodec // AudioDecoderOutput configures the PCM format, sample rate, and channels DecodeAudio delivers. AudioDecoderOutput = ffi.MoqAudioDecoderOutput // AudioEncoderInput declares the PCM sample format, sample rate, and channel count of frames written to an audio producer. AudioEncoderInput = ffi.MoqAudioEncoderInput - // AudioEncoderOutput configures the Opus encoder: codec, optional sample rate, channels, bitrate, and frame duration. + // AudioEncoderOutput configures the encoder: codec, optional sample rate, channels, bitrate, and frame duration. AudioEncoderOutput = ffi.MoqAudioEncoderOutput // AudioSampleFormat is a raw PCM sample layout, mirroring WebCodecs AudioData.format. AudioSampleFormat = ffi.MoqAudioSampleFormat @@ -184,6 +184,12 @@ func OpusAudioCodec() *AudioCodec { return ffi.MoqAudioCodecOpus() } +// AacAudioCodec selects AAC-LC through the platform's encoder for EncodeAudio. +// A host without one refuses it. Leave FrameDurationUs at 0 for AAC's own frame. +func AacAudioCodec() *AudioCodec { + return ffi.MoqAudioCodecAac() +} + // VideoPixelFormat values: the raw pixel layout fed to the in-process encoder, // and the one the in-process decoder delivers. const ( diff --git a/js/hang/src/util/aac.test.ts b/js/hang/src/util/aac.test.ts index c31059ec80f..50dfe903ad9 100644 --- a/js/hang/src/util/aac.test.ts +++ b/js/hang/src/util/aac.test.ts @@ -48,9 +48,11 @@ describe("audioSpecificConfig", () => { expect(audioSpecificConfig(48000, 8)).toEqual(new Uint8Array([0x11, 0xb8])); }); - // Unsupported channel counts fall back to stereo (config 2). - it("unsupported channel count falls back to stereo", () => { - expect(audioSpecificConfig(48000, 7)).toEqual(audioSpecificConfig(48000, 2)); + // A count with no channel configuration is refused rather than described as stereo. + it("refuses a channel count with no configuration", () => { + for (const count of [0, 7, 9]) { + expect(() => audioSpecificConfig(48000, count)).toThrow(); + } }); // Non-table sample rates use the 5-byte explicit-frequency form (freqIndex 0xF). diff --git a/js/hang/src/util/aac.ts b/js/hang/src/util/aac.ts index f417e4c0bdb..ca0cc2fd45b 100644 --- a/js/hang/src/util/aac.ts +++ b/js/hang/src/util/aac.ts @@ -45,19 +45,19 @@ export function pickRate(rate: number): number { const AAC_LC = 2; // audioObjectType for AAC-LC // Map a channel count to its AAC channelConfiguration (ISO 14496-3 Table 1.19). Configs 1..=6 are -// identity (5.1 is config 6 / 6 channels); 8 channels is config 7 (7.1). Anything else has no valid -// config, so fall back to stereo (matching the Rust muxer in rs/moq-mux/src/codec/aac). +// identity (5.1 is config 6 / 6 channels); 8 channels is config 7 (7.1). Anything else has no +// config, and describing it as stereo would mislabel every channel past the first two. function channelConfig(channelCount: number): number { - if (channelCount >= 1 && channelCount <= 6) return channelCount; + if (Number.isInteger(channelCount) && channelCount >= 1 && channelCount <= 6) return channelCount; if (channelCount === 8) return 7; - return 2; + throw new Error(`no AAC channel configuration for ${channelCount} channels`); } /** * Build the AAC-LC AudioSpecificConfig that decoders need when frames are raw (no ADTS header). * * Standard sample rates produce the 2-byte form; non-table rates fall back to the 5-byte form - * with an explicit 24-bit frequency. Mirrors the Rust muxer so JS and Rust agree on the bytes. + * with an explicit 24-bit frequency. Throws for a channel count no configuration names. */ export function audioSpecificConfig(sampleRate: number, channelCount: number): Uint8Array { const config = channelConfig(channelCount); diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt index 9c8639bce8e..55e1ba5600f 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt @@ -134,7 +134,7 @@ typealias FetchGroupOptions = uniffi.moq.MoqFetchGroupOptions typealias TrackInfo = uniffi.moq.MoqTrackInfo /** One audio frame: PCM payload bytes plus a presentation timestamp. */ typealias AudioFrame = uniffi.moq.MoqAudioFrame -/** Selects the audio encoder codec. Build one with `AudioCodec.opus()`. */ +/** Selects the audio encoder codec. Build one with `AudioCodec.opus()` or `AudioCodec.aac()`. */ typealias AudioCodec = uniffi.moq.MoqAudioCodec /** A raw PCM sample format, mirroring WebCodecs `AudioData.format`. */ typealias AudioSampleFormat = uniffi.moq.MoqAudioSampleFormat diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index 0902031a5ae..420227f31a7 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -154,7 +154,7 @@ client = moq.Client( - `.publish_audio(format, init, *, label=None, track=None) → MediaProducer`. `init` is required: an OpusHead or AudioSpecificConfig resolves the whole rendition. `track` names the track; otherwise a unique name is derived from the format. - `.publish_video(format, init=b"", *, label=None, hint=None, track=None) → MediaProducer`. `init` may be empty for a format that resolves in band; a `VideoHint` pins catalog fields the stream can't reveal (bitrate) or publishes the catalog before the first keyframe. `track` names the track as in `publish_audio`. - `.encode_video(input, output, *, bandwidth=None) → VideoProducer`. Encode raw `VideoFrame`s inside the binding; `.write(frame)` each one. - - `.encode_audio(name, input, output, *, bandwidth=None) → AudioProducer`. Encode raw PCM `AudioFrame`s; the codec is `output.codec`, e.g. `AudioCodec.opus()`, with `output.frame_duration_us` setting the Opus frame length. + - `.encode_audio(name, input, output, *, bandwidth=None) → AudioProducer`. Encode raw PCM `AudioFrame`s; the codec is `output.codec`, e.g. `AudioCodec.opus()` or `AudioCodec.aac()`, with `output.frame_duration_us` setting the Opus frame length (0 takes the codec's own frame, which AAC needs). - `.close()` ends the broadcast for good; a second call is a no-op. `.finish()` is its deprecated alias. - **`BroadcastDynamic`**. Async source of tracks requested by subscribers. - `await .requested_track() → TrackRequest`. Call `.accept()` on it for a `TrackProducer`, or `.abort(code)` to reject. diff --git a/py/moq-rs/moq/publish.py b/py/moq-rs/moq/publish.py index 322009e6a0a..20e69b2e147 100644 --- a/py/moq-rs/moq/publish.py +++ b/py/moq-rs/moq/publish.py @@ -754,8 +754,8 @@ def encode_audio( ) -> AudioProducer: """Publish a raw-audio track with an in-process encoder. - Select the codec with ``moq.AudioCodec.opus()`` (currently the only - constructor), placed in ``output``. + Select the codec with ``moq.AudioCodec.opus()`` or + ``moq.AudioCodec.aac()``, placed in ``output``. Pass ``bandwidth`` to reserve this track's bitrate against the session's allocator so a co-resident video encoder sizes itself against what is left. diff --git a/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md b/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md index 946a68a0a6c..9aaee72e13b 100644 --- a/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md +++ b/quest/m1/2848-follow-the-bandwidth-grant-in-moq-audio-instead-of.md @@ -33,20 +33,18 @@ grant; `Options::bandwidth` documents that their own loop; the capture driver's `_reservation` goes away. Public entry points for a manual ceiling stay `Producer::set_bitrate` and `Encoder::set_bitrate`. -- The audio-codecs line branch moves the Opus encoder behind a backend seam: - the rate setter and its floor live in - `rs/moq-audio/src/encode/backend/libopus.rs` there, and - `Encoder::set_bitrate` dispatches through the backend. Target whichever - shape is on the base when this starts. -- Floor: `set_opus_bitrate` refuses anything outside +- The Opus encoder sits behind the encode backend seam: the rate setter and + its floor live in `rs/moq-audio/src/encode/backend/libopus.rs`, and + `Encoder::set_bitrate` dispatches through the backend. +- Floor: the libopus backend's `set_bitrate` refuses anything outside `opus::bitrate_floor(codec_rate, frame_size).max(500)` to - `300_000 * channels` (`encoder.rs`, `rs/moq-audio/src/opus.rs`). `Policy::min` defaults to a tenth of + `300_000 * channels` (`backend/libopus.rs`, `rs/moq-audio/src/opus.rs`). `Policy::min` defaults to a tenth of the ceiling (`rs/moq-mux/src/rate.rs`); for Opus it is the codec floor, so a grant below it clamps there and never errors. The reservation's ceiling is the configured bitrate; only the policy target moves. - PCM: `pcm::bitrate(sample_rate, channels)` is `pub(crate)` (`rs/moq-audio/src/pcm.rs`), `Settings::bitrate` is refused for it - and so is `set_bitrate` (`encoder.rs`). A PCM + and so is `set_bitrate` (`encoder.rs`, `backend/pcm.rs`). A PCM Producer reserves its fixed rate and runs no policy. That is the same reserve-only usage passthrough imports use, so nothing new is added for it. - Priority is unchanged: `PRIORITY` puts audio at 80 and video at 60 diff --git a/quest/m1/README.md b/quest/m1/README.md index 027063f5eea..5cef63b6d7a 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -72,7 +72,16 @@ QUIC studies there on that rule. - [C++ through moq-ffi](/quest/m1/cpp/README.md) - generated C++ over moq-ffi with futures and expected-style errors, shipped as a tarball, vcpkg, and Conan, and adopted by the OBS plugin - [Generated C bindings](/quest/m1/c/README.md) - C generated from moq-ffi ships as `moq-c` 0.8.0 and replaces the hand-written libmoq - [OBS native codecs](/quest/m1/obs-moq-video/README.md) - replace FFmpeg video and audio decoding with moq-video and moq-audio, deliver GPU frames, and use native audio/video encoders -- [Audio codecs](/quest/m1/audio-codecs/README.md) - platform audio codecs, explicit unsupported cases, and channel layouts up to 7.1 +- [AudioToolbox decode](/quest/m1/audio-decode-audiotoolbox.md) - macOS and iOS decode HE-AAC, multichannel AAC, and what else the framework offers +- [HE-AAC catalog output](/quest/m1/he-aac-catalog-output.md) - HE-AAC catalog entries name the output rate and layout, not the LC core +- [TS Opus export refusals](/quest/m1/ts-opus-export-refusals.md) - the TS exporter refuses Opus heads its channel code cannot describe instead of mislabeling them +- [TS Opus channel codes](/quest/m1/ts-opus-channel-codes.md) - TS Opus with a channel code of 0x81 or above imports with its real head or is refused, never guessed as stereo +- [AudioToolbox encode](/quest/m1/audio-encode-audiotoolbox.md) - macOS and iOS encode AAC-LC +- [AAC encode refusals](/quest/m1/aac-encode-refusals.md) - on dev, `Config::encode` refuses channel counts it cannot name instead of writing stereo +- [AAC parse truncated SBR](/quest/m1/aac-parse-truncated-sbr.md) - `Config::parse` refuses SBR and PS configs cut off before their core +- [GStreamer surround Opus](/quest/m1/gst-opus-surround.md) - the moq-gst sink publishes 3 to 8 channel Opus with the OpusHead its caps describe +- [TS AAC PCE joins](/quest/m1/ts-aac-pce-join.md) - PCE-described AAC over TS plays after a mid-stream join or resume, and a missing PCE silences only its track +- [FFI frame duration default](/quest/m1/ffi-frame-duration-default.md) - on dev, the binding audio encoder takes the codec's own frame by default, so `aac()` needs no explicit 0 - [Opus mapping family](/quest/m1/opus-mapping-family.md) - on dev, the Opus head config keeps its mapping family only in `mapping` - [mp4-atom dOps mapping](/quest/m1/mp4-atom-dops-mapping.md) - a released mp4-atom reads and writes any `dOps` channel mapping family and table - [CMAF surround Opus](/quest/m1/cmaf-opus-surround.md) - fMP4 import and export carry an Opus channel mapping table diff --git a/quest/m1/aac-encode-refusals.md b/quest/m1/aac-encode-refusals.md new file mode 100644 index 00000000000..5f6dca02906 --- /dev/null +++ b/quest/m1/aac-encode-refusals.md @@ -0,0 +1,27 @@ +# [S] AAC config encode refuses unnameable channel counts + +## Goal + +`moq_mux::codec::aac::Config::encode` never writes an AudioSpecificConfig that +names the wrong layout. A channel count no channelConfiguration names is +refused, not logged and written as stereo, the way the ADTS writer refuses it. + +## Plan + +- `encode` returns `Bytes` today, so refusing is a published API break: this + retargets to `dev`. Decide whether it returns a `Result` or whether a + constructor validates the count up front so encoding cannot fail. +- A count a program config element could describe (7, or more than 8) is + still refused unless the caller supplies a layout; guessing speaker + positions is what this removes. +- Callers in `moq-audio` (encoder config, description synthesis) already + validate first; check they keep their error messages. `Producer` synthesizes + the ASC at construction, so it refuses such a layout there. +- JS already matches: `@moq/hang`'s `audioSpecificConfig` throws for the same + counts (#4119). Test every count from 1 to 8 and one beyond. + +Public API: `Config::encode` (or its constructor) changes. Wire: none. + +## Related + +- [#4283](https://github.com/moq-dev/moq/pull/4283) - the ADTS export refusals this mirrors diff --git a/quest/m1/aac-parse-truncated-sbr.md b/quest/m1/aac-parse-truncated-sbr.md new file mode 100644 index 00000000000..3a6d94fc831 --- /dev/null +++ b/quest/m1/aac-parse-truncated-sbr.md @@ -0,0 +1,21 @@ +# [XS] AAC config parse refuses truncated SBR and PS + +## Goal + +`Config::parse` refuses an AudioSpecificConfig that signals SBR or PS +(object type 5 or 29) but ends before its extension rate and core object type, +instead of accepting it as if the core were known. + +## Plan + +- The export path already requires these fields; `parse` stays lenient only + because `Config::encode` writes a two-byte config for those object types. + Once encode refuses or completes them, the leniency has no producer. +- Check the `moq-audio` tests that feed a two-byte HE-AAC config; they should + keep asserting a refusal, just a different one. + +Public API: none beyond a new error case. Wire: none. + +## Required + +- [AAC encode refusals](/quest/m1/aac-encode-refusals.md) - encode stops producing truncated SBR and PS configs diff --git a/quest/m1/audio-codecs/README.md b/quest/m1/audio-codecs/README.md deleted file mode 100644 index e9c3cf198bc..00000000000 --- a/quest/m1/audio-codecs/README.md +++ /dev/null @@ -1,69 +0,0 @@ -# Audio codecs - -## Goal - -A broadcast that plays in the browser plays natively. Today the browser -decodes whatever the platform offers (HE-AAC, 5.1 AAC, AC-3, surround Opus) -while `moq-audio` decodes Opus and AAC-LC in mono or stereo, so the same -stream plays on moq.dev and fails in OBS, `moq play`, and every binding. The -native side grows the backend seam `moq-video` already has, uses the OS codec -where one exists, keeps symphonia as the pure-Rust fallback, and carries more -than two channels end to end. Encoding follows the same seam so a native -publisher can produce AAC. - -## Plan - -Platform first, exactly like video: AudioToolbox on macOS and iOS, Media -Foundation on Windows, MediaCodec on Android, and symphonia (AAC-LC -mono/stereo) as the software fallback that openh264 is for H.264. Linux has no -OS audio decoder, so HE-AAC and multichannel AAC stay refused there, stated in -the docs and rejected at construction. A platform backend claims every catalog -codec its framework opens, so AC-3, E-AC-3, MP3, and FLAC ride along on the -hosts that have them; each still needs a fixture before the backend advertises -it. - -Use the extensible `Layout` contract settled in main, with well-known layouts in one -canonical order, derived from the codec description (AAC channelConfiguration, -OpusHead mapping) so the catalog and wire do not change. Every decoder reorders -from its codec's native order into that one, so the mixer, the FFI, and OBS -never guess where the LFE is. Playback downmixes to whatever the output device -opened. Preserve the existing arbitrary-channel PCM passthrough through an -unspecified discrete layout; refuse spatial remixing when speaker positions -are unknown instead of guessing them. - -Encode mirrors decode: an `encode::backend` seam, `Codec::Aac` meaning AAC-LC -at the input's layout, and platform encoders behind it. Opus encode stays -mono/stereo. - -The next merge from main conflicts in `rs/moq-audio/src/decode/decoder.rs`: -[#4442](https://github.com/moq-dev/moq/pull/4442) conceals one Opus frame on -loss there, while this line moved that logic into `decode/backend/libopus.rs`. -Port the fix by hand, taking the concealed duration from the multistream -packet rather than the single-stream call. - -The core configuration and layout contracts land in main. These quests implement -surround and backend dispatch on that contract; each platform then lands as -its own decode and encode quest so verification stays per host. The -HE-AAC refusal and the PCE parse are defects in what ships today and are -ready now. - -## Required - -- [Named codecs](/quest/m1/audio-codecs/named-codecs.md) - `decode::Kind::Named` keeps the published codec names and picks backends internally; must land before the line merges -- [HE-AAC refusal](/quest/m1/audio-codecs/he-aac-refusal.md) - implicit-SBR HE-AAC over TS is refused instead of half-decoded as the LC core -- [AAC PCE](/quest/m1/audio-codecs/aac-pce.md) - a channel_config of 0 parses the program config element instead of guessing stereo -- [Layout](/quest/m1/audio-codecs/layout.md) - the settled `Layout` carries up to 7.1 through decode, resample, playback, and the FFI -- [Decode seam](/quest/m1/audio-codecs/decode-backend.md) - `decode::backend` selects a platform decoder before symphonia, mirroring moq-video -- [AudioToolbox decode](/quest/m1/audio-codecs/decode-audiotoolbox.md) - macOS and iOS decode HE-AAC, multichannel AAC, and what else the framework offers -- [Opus surround](/quest/m1/audio-codecs/opus-surround.md) - mapping family 1 decodes on every host through the multistream decoder -- [Encode seam](/quest/m1/audio-codecs/encode-backend.md) - `encode::backend` and `Codec::Aac`, so a native publisher can produce AAC-LC -- [AudioToolbox encode](/quest/m1/audio-codecs/encode-audiotoolbox.md) - macOS and iOS encode AAC-LC - -## Related - -- [OBS native codecs](/quest/m1/obs-moq-video/README.md) - the OBS source and encoder adapters consume this through moq-ffi; #3498 narrowed OBS to what moq-audio decodes today -- [Dart codec parity](/quest/m1/dart-codecs.md) - Dart gains these once it builds with the `audio` feature -- [Media Foundation decode](/quest/m2/audio-decode-mediafoundation.md) - Windows decodes HE-AAC, multichannel AAC, and what else the MFTs offer -- [Media Foundation encode](/quest/m2/audio-encode-mediafoundation.md) - Windows encodes AAC-LC -- [MediaCodec decode](/quest/m2/audio-decode-mediacodec.md) - Android decodes HE-AAC, multichannel AAC, and what else the device offers -- [MediaCodec encode](/quest/m2/audio-encode-mediacodec.md) - Android encodes AAC-LC diff --git a/quest/m1/audio-codecs/aac-pce.md b/quest/m1/audio-codecs/aac-pce.md deleted file mode 100644 index db99ec93f95..00000000000 --- a/quest/m1/audio-codecs/aac-pce.md +++ /dev/null @@ -1,34 +0,0 @@ -# [S] moq-mux: an AAC channel_config of 0 parses the PCE or refuses the track - -## Goal - -The catalog never invents an AAC channel count. A stream whose -channelConfiguration is 0 gets its count from the program config element it -carries, and a reserved value refuses the track with a clear error. Today -both map to stereo with a warning. - -## Plan - -The ADTS and ASC importers in `rs/moq-mux/src/codec/aac` map -`channel_config == 0` and every value from 8 to 15 to stereo and warn. -Warn-then-continue is banned: supported or refused. - -- ASC: with `channel_config == 0` the GASpecificConfig carries a - `program_config_element`; parse its front, side, back, and LFE element - counts into the channel count (and, once [Layout](/quest/m1/audio-codecs/layout.md) - lands, into a layout). -- ADTS: channel_config 0 means the PCE is in the first raw data block. Parse - it there, once per track, the same way the HE-AAC sniff reads the first - block's fill elements. -- Give every ASC configuration from 8 to 15 an explicit disposition: implement - any supported channel mapping and return `Error::Unsupported` for every - remaining value, including reserved configurations. -- Regression: an ASC fixture with a PCE reports its real count; an ADTS - fixture with an in-band PCE does too; each value from 8 to 15 has its - supported count asserted or is refused; the - common configurations 1 to 7 are unchanged. - -## Related - -- [HE-AAC refusal](/quest/m1/audio-codecs/he-aac-refusal.md) - reads the same first block -- [Layout](/quest/m1/audio-codecs/layout.md) - what the parsed PCE eventually maps to diff --git a/quest/m1/audio-codecs/decode-backend.md b/quest/m1/audio-codecs/decode-backend.md deleted file mode 100644 index ecfb6f64ba9..00000000000 --- a/quest/m1/audio-codecs/decode-backend.md +++ /dev/null @@ -1,43 +0,0 @@ -# [M] A decode backend seam that prefers the platform codec - -## Goal - -`moq_audio::decode` selects a backend per codec the way `moq_video::decode` -does: platform first, software fallback, and a `Kind` to force one. Opus, -PCM, and symphonia AAC-LC become the software backends, and the crate -documents which codecs each host decodes. - -## Plan - -Mirror `rs/moq-video/src/decode/backend` in name and shape: a crate-private -`Backend` trait (`decode`, `flush`, `name`), an `open(codec, config)` that -walks the platform candidates before the software ones and refuses when none -takes the track. Use the backend-selection configuration and Decoder -constructor settled in main rather than adding a conflicting public shape. -`Decoder::name()` reports what was opened, which the OBS -stats and `moq play` surface. - -- The seam is generic over `hang::catalog::AudioCodec`, so a backend advertises - the set it opens and the selector asks each in order. Symphonia advertises - AAC-LC mono/stereo only; the platform backends that follow advertise what - their framework opens and has a fixture for. -- Move today's Opus, PCM, and symphonia code behind the trait without changing - behavior; the HE-AAC sniff from [HE-AAC refusal](/quest/m1/audio-codecs/he-aac-refusal.md) - lands in the symphonia backend. -- A backend's output rate and layout are what it produced, not what the - catalog said (HE-AAC doubles the rate); `Consumer` already resamples and - remixes to the requested output, so that stays the seam's contract. -- The `aac` feature keeps gating symphonia. Platform backends are - `cfg(target_os)` like their video counterparts. Audio has no MediaCodec - feature yet; its Android quest introduces the optional dependency following - the settled media build policy. -- Docs: `doc/lib/rs/moq-audio.md` gains the backend table `moq-video.md` has, - and states the Linux gap. `doc/bin/cli.md` and `doc/bin/obs.md` follow. -- Regression: the selection order and `Named` refusal, tested with a stub - backend like the video seam's `probe`. - -The FFI does not expose `Kind` until a consumer asks. - -## Related - -- [Layout](/quest/m1/audio-codecs/layout.md) - independent; the platform backends need both diff --git a/quest/m1/audio-codecs/encode-audiotoolbox.md b/quest/m1/audio-codecs/encode-audiotoolbox.md deleted file mode 100644 index 401142b2919..00000000000 --- a/quest/m1/audio-codecs/encode-audiotoolbox.md +++ /dev/null @@ -1,31 +0,0 @@ -# [M] AudioToolbox AAC encode on macOS and iOS - -## Goal - -On macOS and iOS, `Codec::Aac` encodes through AudioToolbox at the input's -layout, up to 7.1, and the result plays in the browser, `moq play`, and OBS. - -## Plan - -An `AudioConverter` from interleaved `f32` to `kAudioFormatMPEG4AAC`, behind -the encode seam as the platform candidate on macOS and iOS. - -- The catalog ASC is synthesized at construction per the encode seam; read - `kAudioConverterCompressionMagicCookie` at open and assert it matches. - `kAudioConverterPrimeInfo` gives the delay the timestamps fold in. -- Bitrate through `kAudioConverterEncodeBitRate`, updated live where the - converter allows. -- Regression: a stereo and a 5.1 encode round-trip through the AudioToolbox - decoder and through symphonia (stereo only), with timestamps continuous - across the priming. -- Decided in [#4183](https://github.com/moq-dev/moq/pull/4183): the uniffi - `MoqAudioEncoderOutput::frame_duration_us` default moves from 20000 to 0 - (the codec's own frame) with this quest, so `aac()` works without an - explicit 0. Changing a published binding default is a break, so that - change targets `dev`. - -## Required - -- [Encode seam](/quest/m1/audio-codecs/encode-backend.md) - the candidate order this backend joins -- [Layout](/quest/m1/audio-codecs/layout.md) - the input layout the encoder accepts -- [AudioToolbox decode](/quest/m1/audio-codecs/decode-audiotoolbox.md) - the round-trip regression decodes through it diff --git a/quest/m1/audio-codecs/encode-backend.md b/quest/m1/audio-codecs/encode-backend.md deleted file mode 100644 index 8d18a9a16fa..00000000000 --- a/quest/m1/audio-codecs/encode-backend.md +++ /dev/null @@ -1,50 +0,0 @@ -# [M] An encode backend seam and an AAC output codec - -## Goal - -`moq_audio::encode` selects a backend the way `moq_video::encode` does, and -`Codec::Aac` is a valid output: AAC-LC at the input's sample rate and layout, -published with the AudioSpecificConfig description every player expects. A -host with no AAC encoder refuses it at construction. - -## Plan - -Mirror the decode seam: `encode::backend` with a crate-private `Backend` -trait (`encode`, `flush`, `set_bitrate`, `name`), an `open(codec, config)` -that walks platform candidates before software ones, using the public settings -and selection contract settled in main. Opus and PCM retain their behavior. This -quest adds AAC through platform encoders; no software AAC dependency is selected. - -- `encode::Codec` gains `Aac`, meaning `mp4a.40.2`, and `as_str` / `FromStr` - accept `"aac"`, which is what libmoq's codec string carries. moq-ffi's - immutable codec object gains an `aac()` constructor and conversion; do not - reintroduce a closed binding enum. The generated bindings, hand-written - wrappers, and docs follow the Cross-Package Sync table. -- Catalog emission: `AudioCodec::AAC` with profile 2, `Container::Legacy`, - and the encoder's reported delay folded into timestamps like Opus pre-skip - is today. `Producer` registers the rendition before the first frame is - written, so the ASC `description` is synthesized at construction from the - config with `moq_mux::codec::aac::Config::encode`, never read back from the - backend's first packet. A backend that reports its own header (a magic - cookie, `csd-0`, `MF_MT_USER_DATA`) must produce one equal to the synthesized - ASC, asserted in its tests. -- The line branch's `aac-encode-refusals` quest makes `Config::encode` refuse - a channel count no channelConfiguration names instead of writing stereo, so - that synthesis is fallible and `Producer` refuses such a layout at - construction. JS matches: `@moq/hang`'s `audioSpecificConfig` throws for the - same counts (#4119, on the line). This absorbs the former m2 - aac-encode-refusal quest, a duplicate of that line quest. -- Frame size is the codec's (1024 samples for AAC), so `frame_duration` is - validated per codec rather than against the Opus table. -- Bitrate updates go through the backend; one that cannot change rate - mid-stream keeps its opening rate, as the video seam documents. -- Regression: the selection order with a stub backend; `Codec::Aac` refused on - a host with no backend; the Opus and PCM paths unchanged. - -## Required - -- [Decode seam](/quest/m1/audio-codecs/decode-backend.md) - the naming and shape this mirrors - -## Related - -- [OBS audio publishing](/quest/m1/obs-moq-video/audio-publish.md) - the OBS encoder adapter can offer AAC once this lands diff --git a/quest/m1/audio-codecs/he-aac-refusal.md b/quest/m1/audio-codecs/he-aac-refusal.md deleted file mode 100644 index f7995cc0f71..00000000000 --- a/quest/m1/audio-codecs/he-aac-refusal.md +++ /dev/null @@ -1,34 +0,0 @@ -# [S] Refuse implicit-SBR HE-AAC instead of half-decoding it - -## Goal - -An HE-AAC stream that signals AAC-LC and carries SBR only in band is refused -with a clear error, the same way explicitly signaled and backward-compatible -HE-AAC already are. Today it decodes as the LC core at half the sample rate -with no indication anything is wrong. - -## Plan - -ADTS carries a 2-bit profile, so HE-AAC over MPEG-TS (SRT, `moq import ts`) -always arrives as `mp4a.40.2` with a synthesized LC AudioSpecificConfig. The -config-level checks in `rs/moq-audio/src/aac.rs` cannot see it, and the code -says so. The stream itself can: the first raw data block carries an `ID_FIL` -element with `EXT_SBR_DATA` (or `EXT_SBR_DATA_CRC`), and every later frame -does too. - -- Sniff the fill elements of the first packet before handing it to symphonia. - An SBR extension makes the track `Error::Unsupported` with the same wording - as the config-level refusal, naming the host's decoder as the reason. -- Symphonia already walks the element tree, so the sniff is a small parser - over the same syntax, not a decode. It runs once per track. -- Regression: an ADTS fixture with implicit SBR is refused; the existing - explicit and backward-compatible fixtures keep their errors; an LC fixture - with an unrelated fill element still decodes. -- When a platform decoder handles the track ([Decode seam](/quest/m1/audio-codecs/decode-backend.md)), - the sniff belongs to the symphonia backend only; the OS decoders read SBR in - band themselves. - -## Related - -- [Decode seam](/quest/m1/audio-codecs/decode-backend.md) - the sniff becomes the software backend's contract -- [AAC PCE](/quest/m1/audio-codecs/aac-pce.md) - the other place the catalog lies about an AAC stream diff --git a/quest/m1/audio-codecs/layout.md b/quest/m1/audio-codecs/layout.md deleted file mode 100644 index 2df431c95cd..00000000000 --- a/quest/m1/audio-codecs/layout.md +++ /dev/null @@ -1,51 +0,0 @@ -# [M] Channel layouts through decode, playback, and the FFI - -## Goal - -`moq-audio` carries up to 7.1 end to end. A decoded frame says which layout -it is in, the playback mixer downmixes it to whatever the device opened, a raw -PCM consumer can ask for a layout, and the FFI and libmoq expose the same. -Proven with multichannel PCM, the one codec that needs no new decoder. - -## Plan - -Extend the Layout contract settled in main with supported surround layouts -(2.1, quad, 5.0, 5.1, 6.1, 7.1, and the other AAC channelConfiguration and -Opus mapping family 1 entries) in one canonical order, the SMPTE/WAVE order. -Keep the representation extensible. Each codec module maps its native -order into it: AAC's `C L R Ls Rs LFE` and Opus's Vorbis `L C R Ls Rs LFE` -both become `L R C LFE Ls Rs`. An unspecified discrete PCM layout remains -valid for passthrough but is refused for spatial remixing; never invent speaker -positions from an arbitrary channel count. - -- Reuse the settled PCM descriptors and codec/consumer settings. This quest - adds supported layout behavior rather than replacing public field types. - Frame stays layout-free since the consumer fixed it at construction. -- `resample::remix` becomes a generic remix over layouts: ITU-R BS.775 - coefficients for downmix, silence in the extra speakers for upmix, and the - existing mono/stereo paths as the two-channel special cases. The resampler is - already channel-generic. -- Playback: the mix bus takes the device's layout instead of fixed stereo, the - device chooser prefers the widest well-known layout the device offers (a - 5.1 HDMI sink opens at six channels, a headset at two), and each `Sink` - remixes into the bus. Today's "silence past the front pair" fan-out goes. -- moq-ffi and libmoq keep `channels` as a count, and the count means the - default layout for that count (the WAVE convention: 3 is 2.1, 4 is quad, 6 - is 5.1, 8 is 7.1), delivered or accepted in the canonical order. No record, - `repr(C)` struct, or binding changes, so this stays on `main`; only the - Rust API names the layout, and a binding that needs 5.0 rather than 5.1 is - a later additive field. Document the mapping in every binding's audio doc. -- The catalog does not change: `channel_count` already carries what the - description implies, and `js/hang`'s `aac.ts` stops falling back to stereo - for a count it cannot map. -- Regressions: a 5.1 PCM broadcast published through `encode::Producer` and - read back through `decode::Consumer` at 5.1, at stereo, and at mono; the - mixer fed a 5.1 sink into a stereo bus and a stereo sink into a 5.1 bus; the - device chooser picking six channels when offered. - -Capture stays mono/stereo, and Opus encode stays mapping family 0. - -## Related - -- [Opus surround](/quest/m1/audio-codecs/opus-surround.md) - the first coded multichannel consumer of the layout -- [AudioToolbox decode](/quest/m1/audio-codecs/decode-audiotoolbox.md) - the first platform decoder producing more than stereo diff --git a/quest/m1/audio-codecs/named-codecs.md b/quest/m1/audio-codecs/named-codecs.md deleted file mode 100644 index 4bba08d514e..00000000000 --- a/quest/m1/audio-codecs/named-codecs.md +++ /dev/null @@ -1,27 +0,0 @@ -# [XS] Kind::Named keeps its codec names - -## Goal - -`moq_audio::decode::Kind::Named` accepts what published moq-audio 0.1.6 -accepts, the codec names (`"opus"`, `"aac"`, `"pcm"`), so the line can merge -to `main` without breaking callers. [#4131](https://github.com/moq-dev/moq/pull/4131) -switched it to backend names (`"libopus"`, `"symphonia"`, `"pcm"`) on the line -branch, which turns every existing `Named("opus")` or `Named("aac")` into -`Error::Unsupported` after an upgrade. This must land before the line PR -[#4081](https://github.com/moq-dev/moq/pull/4081) merges to `main`. - -## Plan - -- Decided: keep codec names; backends are picked internally. Which backend - decodes AAC (AudioToolbox, Media Foundation, symphonia) is the library's - choice through `Auto` and `Software`, not a string a caller has to know and - that changes per platform. This reverses #4131's reasoning on purpose: the - published contract wins over matching moq-video's backend naming. -- Make `encode::Kind` read the same way. It is unpublished, so drop `Named` - there or give it the same codec meaning, whichever leaves the two enums - mirrored; don't keep backend names on one side only. -- Tests that forced a backend by name move to a crate-private seam. -- Docs and the `Kind` doc comments list the codec names. - -Public API: `decode::Kind::Named` returns to its published meaning, so the -line stays additive on `main`. Wire: none. diff --git a/quest/m1/audio-codecs/opus-surround.md b/quest/m1/audio-codecs/opus-surround.md deleted file mode 100644 index de6247ae0c0..00000000000 --- a/quest/m1/audio-codecs/opus-surround.md +++ /dev/null @@ -1,26 +0,0 @@ -# [S] Opus surround through the multistream decoder - -## Goal - -An Opus track with channel mapping family 1 (up to 7.1, RFC 7845 §5.1.1) -decodes on every host, delivered in the canonical `Layout` order. Pure Rust, -so this is the one multichannel path Linux gets. - -## Plan - -- `moq_mux::codec::opus::Config` parses the channel mapping (family, stream - count, coupled count, and the mapping table) instead of skipping it. Family - 0 stays mono/stereo; family 1 maps to a `Layout` by channel count; family - 255 and unknown families are refused, since they carry no speaker - assignment. -- The Opus decode backend opens `opus_multistream_decoder_create` from - `unsafe-libopus` when the family is 1, and reorders Vorbis order into the - canonical one on the way out. -- Encode stays family 0; `Config::encode` keeps refusing more than two - channels. -- Regression: a family-1 5.1 fixture decodes to six channels in canonical - order; family 255 is refused at construction. - -## Required - -- [Layout](/quest/m1/audio-codecs/layout.md) - the type the mapping resolves to diff --git a/quest/m1/audio-codecs/decode-audiotoolbox.md b/quest/m1/audio-decode-audiotoolbox.md similarity index 70% rename from quest/m1/audio-codecs/decode-audiotoolbox.md rename to quest/m1/audio-decode-audiotoolbox.md index effbebb8098..cda8f73b5cc 100644 --- a/quest/m1/audio-codecs/decode-audiotoolbox.md +++ b/quest/m1/audio-decode-audiotoolbox.md @@ -10,9 +10,14 @@ documents as unsupported. ## Plan An `AudioConverter` from the packetized format to interleaved `f32` at the -codec's native rate and layout, behind the decode seam as the first platform -candidate on `target_os = "macos"` and `"ios"`. `objc2-audio-toolbox` is the -binding, alongside the `objc2-core-audio-types` the crate already carries. +codec's native rate and layout, behind the decode seam +(`rs/moq-audio/src/decode/backend`) as the first platform candidate on +`target_os = "macos"` and `"ios"`. `objc2-audio-toolbox` is the binding, +alongside the `objc2-core-audio-types` the crate already carries. + +- With a platform tier in place, `Auto` falling past a refusing platform + decoder to software should warn, as moq-video's `select` does; the seam + only aggregates the refusals into its error today. - Build the `AudioStreamBasicDescription` and magic cookie from the catalog description; the converter reports the output layout, which maps to @@ -20,7 +25,8 @@ binding, alongside the `objc2-core-audio-types` the crate already carries. - HE-AAC: the converter reads SBR in band and reports the doubled rate; the seam passes it through. No config-level guessing. - Priming and remainder: AudioToolbox reports `kAudioConverterPrimeInfo`; - trim it so timestamps line up with symphonia's output on the same stream. + report it as the backend's startup delay, which the front end trims, so + timestamps line up with symphonia's output on the same stream. - Every codec the backend advertises has a fixture and a decode test, and the test asserts the layout order matches the canonical one (the LFE and centre end up where `Layout` says). @@ -29,11 +35,6 @@ binding, alongside the `objc2-core-audio-types` the crate already carries. - Docs: `doc/bin/obs.md` drops the HE-AAC and multichannel caveat on macOS, and the backend table names what this host decodes. -## Required - -- [Decode seam](/quest/m1/audio-codecs/decode-backend.md) - the candidate order this backend joins -- [Layout](/quest/m1/audio-codecs/layout.md) - what a multichannel frame is delivered as - ## Related - [Media Foundation decode](/quest/m2/audio-decode-mediafoundation.md) - the same shape on Windows diff --git a/quest/m1/audio-encode-audiotoolbox.md b/quest/m1/audio-encode-audiotoolbox.md new file mode 100644 index 00000000000..6892e275b16 --- /dev/null +++ b/quest/m1/audio-encode-audiotoolbox.md @@ -0,0 +1,37 @@ +# [M] AudioToolbox AAC encode on macOS and iOS + +## Goal + +On macOS and iOS, `Codec::Aac` encodes through AudioToolbox at the input's +layout, up to 7.1, and the result plays in the browser, `moq play`, and OBS. + +## Plan + +An `AudioConverter` from interleaved `f32` to `kAudioFormatMPEG4AAC`, behind +the encode seam as the platform candidate on macOS and iOS. + +- The catalog ASC is synthesized at construction per the encode seam; read + `kAudioConverterCompressionMagicCookie` at open and assert it matches. + `kAudioConverterPrimeInfo` gives the delay the timestamps fold in. +- Bitrate through `kAudioConverterEncodeBitRate`, updated live where the + converter allows. +- The seam assumes one packet per frame. If the converter holds output back, + the backend needs a `flush` and a zero-or-more return, which changes + `Encoder::encode` and so targets `dev`. +- Gate the seam's "AAC refused without a platform encoder" test to hosts + without one. +- Regression: a stereo and a 5.1 encode round-trip through the AudioToolbox + decoder and through symphonia (stereo only), with timestamps continuous + across the priming. +- That continuity fails today for an epoch below the delay: `Producer::timestamp` + (`rs/moq-audio/src/encode/producer.rs`) clamps each priming packet to zero, + so a zero epoch stamps `[0, 0, 0, 20_000]`, and `decode::Consumer` reads the + duplicates as holes and resets AAC between them. Shift the whole timeline by + the deficit instead, including the terminal end (found in #4081 review). +- Until [FFI frame duration default](/quest/m1/ffi-frame-duration-default.md) + lands on `dev`, binding callers pass `frame_duration_us: 0` with `aac()`. + Split out on 2026-09-30 so this quest stays on `main`. + +## Required + +- [AudioToolbox decode](/quest/m1/audio-decode-audiotoolbox.md) - the round-trip regression decodes through it diff --git a/quest/m1/cmaf-opus-surround.md b/quest/m1/cmaf-opus-surround.md index da3ae24b669..ab6b86e93c6 100644 --- a/quest/m1/cmaf-opus-surround.md +++ b/quest/m1/cmaf-opus-surround.md @@ -19,4 +19,3 @@ its table intact. ## Required - [mp4-atom dOps mapping](/quest/m1/mp4-atom-dops-mapping.md) - `Dops` carries the mapping family and table -- [Audio codecs](/quest/m1/audio-codecs/README.md) - `opus::Mapping` and a `Config::encode` that writes any family's table diff --git a/quest/m1/ffi-frame-duration-default.md b/quest/m1/ffi-frame-duration-default.md new file mode 100644 index 00000000000..56496f8c79b --- /dev/null +++ b/quest/m1/ffi-frame-duration-default.md @@ -0,0 +1,22 @@ +# [XS] FFI audio encoder takes the codec's own frame by default + +## Goal + +On `dev`, `MoqAudioEncoderOutput::frame_duration_us` defaults to 0, the +codec's own frame, so `MoqAudioCodec::aac()` works without an explicit 0 in +every binding. Opus still encodes 20 ms frames by default. + +## Plan + +- Decided in [#4183](https://github.com/moq-dev/moq/pull/4183): the uniffi + default moves from 20000 to 0. Changing a published binding default is a + break, so this targets `dev`. Split from AudioToolbox encode on 2026-09-30, + since a child of a `main`-bound line cannot land on `dev`. +- `rs/moq-ffi/src/audio.rs` already treats 0 as the codec's frame; the + `default_frame_duration_matches_moq_audio` test that pins 20000 to + moq-audio's default goes away with the literal. +- Update the wrappers and docs that restate 20000: the Python test asserting + the default, `py/moq-rs/README.md`, and `doc/lib/{py,swift,kt,go,dart}`. + libmoq already reads 0 as the default. + +Public API: breaking default in moq-ffi and every binding. Wire: none. diff --git a/quest/m1/gst-opus-surround.md b/quest/m1/gst-opus-surround.md new file mode 100644 index 00000000000..8b7a195ebcf --- /dev/null +++ b/quest/m1/gst-opus-surround.md @@ -0,0 +1,21 @@ +# [S] Surround Opus from GStreamer + +## Goal + +`moq-gst`'s sink publishes a 3 to 8 channel `audio/x-opus` stream with the +OpusHead its caps describe, so surround Opus from `opusenc` plays natively like +the same stream from Matroska or MPEG-TS. + +## Plan + +- The sink refuses more than two channels because it builds the head from + `channels` and `rate` alone. Multichannel Opus caps also carry + `channel-mapping-family`, `stream-count`, `coupled-count`, and + `channel-mapping`; build the mapping with `opus::Mapping::new`, which + validates them, and refuse caps that omit or contradict them. +- Prefer a `streamheader` OpusHead when the caps carry one, if that path is + simpler and covers the same streams. +- Regression: an `opusenc` 5.1 pipeline publishes a family 1 description that + `moq-audio` decodes to six channels. + +Public API: none. Wire: none. diff --git a/quest/m1/he-aac-catalog-output.md b/quest/m1/he-aac-catalog-output.md new file mode 100644 index 00000000000..9032995d6e9 --- /dev/null +++ b/quest/m1/he-aac-catalog-output.md @@ -0,0 +1,29 @@ +# [S] HE-AAC catalog entries describe the output + +## Goal + +A catalog entry for HE-AAC or HE-AACv2 names what the stream plays as, for +example 48 kHz stereo, not its AAC-LC core (24 kHz, and mono for v2). Players +and gateways that size buffers or pick a decoder from the catalog see the real +output. + +## Plan + +- `Config::parse` reports the core rate and channel count because those lead + an explicit SBR or PS AudioSpecificConfig. The FLV and MKV importers copy + them into the catalog; fMP4 takes the sample entry instead, so the importers + disagree for the same stream. +- Derive the output from the config: the extension rate under SBR, two + channels under PS. Implicit SBR, found only in band, cannot be known from the + config; keep the documented half-rate behavior for it. +- Consumers that rebuild a config from catalog fields (description synthesis in + `moq-audio`, the MSF path) must not then mistake the output rate for the core. +- Regression: the `fdkaacenc` HE-AAC and HE-AACv2 FLV fixtures under + `rs/moq-mux/src/container/ts/test_data` import as 48 kHz stereo, matching + ffprobe. + +Public API: possibly `Config` fields. Wire: catalog values change for HE-AAC. + +## Related + +- [#4283](https://github.com/moq-dev/moq/pull/4283) - found while labeling HE-AAC for ADTS diff --git a/quest/m1/obs-moq-video/README.md b/quest/m1/obs-moq-video/README.md index 16027a90966..f44a2582416 100644 --- a/quest/m1/obs-moq-video/README.md +++ b/quest/m1/obs-moq-video/README.md @@ -38,6 +38,7 @@ Decided in the 2026-09-30 audit: the Windows and Linux GPU decode paths and the - [macOS GPU input](/quest/m2/obs-macos.md) - feed compositor frames to VideoToolbox without a CPU round trip; needs physical-hardware proof - [Windows GPU input](/quest/m2/obs-windows.md) - feed D3D11 compositor frames to the encoder without CPU staging; needs physical-hardware proof - [Video hardware validation](/quest/m3/video-hardware.md) - physical hardware evidence is required for each claimed GPU path -- [Audio codecs](/quest/m1/audio-codecs/README.md) - HE-AAC, multichannel, and native AAC encode reach the OBS source and encoder adapters through moq-ffi +- [AudioToolbox decode](/quest/m1/audio-decode-audiotoolbox.md) - HE-AAC and multichannel AAC reach the OBS source on macOS through moq-ffi +- [AudioToolbox encode](/quest/m1/audio-encode-audiotoolbox.md) - native AAC encode reaches the OBS encoder adapter on macOS through moq-ffi - [Linux GPU input](/quest/m3/obs-linux-gpu.md) - allocation-export feasibility and its dependent implementation are deferred - [VAAPI encode and decode](/quest/m2/video-vaapi.md) - owns Linux backend decode/import capabilities; reconcile its older dependency assumptions against current code diff --git a/quest/m1/obs-moq-video/audio-playback.md b/quest/m1/obs-moq-video/audio-playback.md index d7da76a3f41..c7072e45b10 100644 --- a/quest/m1/obs-moq-video/audio-playback.md +++ b/quest/m1/obs-moq-video/audio-playback.md @@ -23,4 +23,4 @@ Decided: the earlier receive branch (#3498, merged only into the stranded `codex ## Related - [Video source replacement](/quest/m1/obs-moq-video/source.md) - coordinate the shared timestamp and source lifecycle without blocking audio rollout -- [Channel layouts](/quest/m1/audio-codecs/layout.md) - the moq-audio layouts this mapping mirrors +- [Channel layouts](https://github.com/moq-dev/moq/pull/4119) - the moq-audio layouts this mapping mirrors diff --git a/quest/m1/obs-moq-video/audio-publish.md b/quest/m1/obs-moq-video/audio-publish.md index ae2543cd356..3b7cf9981a5 100644 --- a/quest/m1/obs-moq-video/audio-publish.md +++ b/quest/m1/obs-moq-video/audio-publish.md @@ -8,7 +8,7 @@ MoQ publishing can encode OBS's mixed audio with moq-audio Opus while preserving - Expose `moq_audio::encode::Encoder` through a codec-only moq-ffi type with owned encoder/packet handles, so every binding gets it. The existing raw audio producer combines encoding and publication and must not create a second publication alongside the OBS encoded output. Reuse frame sizing, bitrate updates, catalog configuration, and finish/padding behavior. - Implement the OBS audio encoder interface, including fixed input frame size, mono/stereo PCM conversion, timestamps, codec headers, final padding, and packet release. Ask OBS for the input layout the encoder supports; moq-audio does not implement arbitrary channel remapping. Keep capture/mixing/device ownership in OBS. -- Publish Opus initially. Leave AAC with the existing OBS mode and defer PCM publishing UI, since the output currently declares AAC/Opus. Correct stale binding documentation that describes the raw codec parser as Opus-only if that API is touched. +- Publish Opus initially. `encode::Codec::Aac` lets the adapter offer AAC where a platform encoder exists; until then leave AAC with the existing OBS mode and defer PCM publishing UI, since the output currently declares AAC/Opus. Correct stale binding documentation that describes the raw codec parser as Opus-only if that API is touched. - Apply the shared presets and independent audio bitrate. Test 10/20 ms packetization, frame-size changes at stream boundaries, partial final frames, silence, reconnect, saturation, and stop with pending output. Verify decoded audio and A/V timestamps with a real subscriber. - Land the internal adapter independently; the combined Use MoQ encoders UI becomes available when the video adapter also lands. Do not expose a temporary video/audio mix-and-match product UI. @@ -16,7 +16,3 @@ MoQ publishing can encode OBS's mixed audio with moq-audio Opus while preserving - [OBS migration](/quest/m1/cpp/obs.md) - the plugin is on the generated C++ first - [Encoder presets](/quest/m1/obs-moq-video/presets.md) - shared policy and truthful reporting - -## Related - -- [Encode seam](/quest/m1/audio-codecs/encode-backend.md) - `Codec::Aac` lets the adapter offer AAC instead of leaving it to the OBS encoder mode diff --git a/quest/m1/opus-mapping-family.md b/quest/m1/opus-mapping-family.md index f2dec437cd4..9bd243a1ddf 100644 --- a/quest/m1/opus-mapping-family.md +++ b/quest/m1/opus-mapping-family.md @@ -2,14 +2,10 @@ ## Goal -On dev, `moq_mux::codec::opus::Config` stores the channel mapping family in one place: the audio-codecs line's `mapping: Option`. The `mapping_family: u8` field that #4130 shipped in moq-mux 0.10.8 is removed, and every reader takes the family from `mapping`. +On dev, `moq_mux::codec::opus::Config` stores the channel mapping family in one place: `mapping: Option`. The `mapping_family: u8` field that #4130 shipped in moq-mux 0.10.8 is removed, and every reader takes the family from `mapping`. ## Plan -Decided 2026-09-28 while merging main into the audio-codecs line: that sync keeps both fields so the line stays additive on main, and `encode` refuses a `mapping_family` that disagrees with `mapping`. Removing the duplicate breaks the published moq-mux API, so it lands on dev once the line has merged. Update main's fMP4 and MSF paths that read `mapping_family`, plus the TS importer, which sets both fields. +Decided 2026-09-28 while merging main into the audio-codecs line: that sync keeps both fields so the line stays additive on main, and `encode` refuses a `mapping_family` that disagrees with `mapping`. Removing the duplicate breaks the published moq-mux API, so it lands on dev. Update main's fMP4 and MSF paths that read `mapping_family`, plus the TS importer, which sets both fields. Public API: breaking in moq-mux (field removed). Wire: none. - -## Required - -- [Audio codecs](/quest/m1/audio-codecs/README.md) - the line that introduces `mapping` diff --git a/quest/m1/ts-aac-pce-join.md b/quest/m1/ts-aac-pce-join.md new file mode 100644 index 00000000000..e31f2e1ff99 --- /dev/null +++ b/quest/m1/ts-aac-pce-join.md @@ -0,0 +1,31 @@ +# [S] TS AAC program config survives joins and resumes + +## Goal + +AAC whose layout lives in a program config element (ADTS `channel_config` 0) +plays over MPEG-TS for a receiver that joins mid-stream or after a resume. A +missing PCE silences that one track instead of failing the whole program. + +## Plan + +Found in review of the audio-codecs line (#4081), 2026-09-30. + +- Import: `aac::in_band_config` returns `ProgramConfigMissing` when the first + frame seen has no leading PCE, and `?` ends the whole TS import, video + included (`rs/moq-mux/src/container/ts/import.rs`). Instead, keep the + reservation, drop frames on that track until one leads with a PCE, and log + once. ffmpeg's ADTS muxer writes the PCE only in the first frame, so a late + join of an ffmpeg source stays silent; say so in the docs. +- Export: `mux` takes the PCE on the first frame only + (`rs/moq-mux/src/container/ts/export.rs`), so `resume()`/`rewind()` and any + mid-stream receiver never see it. Repeat it, either on every frame or with + each PAT/PMT, and pick whichever ffmpeg and the import side accept. +- Regression: an export resumed before its first span re-emits the PCE, and an + import that starts on a PCE-less frame publishes the track once a PCE + arrives, while the other tracks keep flowing. + +Public API: none. Wire: none; TS output gains repeated PCEs. + +## Related + +- [TS Opus channel codes](/quest/m1/ts-opus-channel-codes.md) - the same per-track refusal principle for Opus descriptors diff --git a/quest/m1/ts-opus-channel-codes.md b/quest/m1/ts-opus-channel-codes.md new file mode 100644 index 00000000000..221cc675592 --- /dev/null +++ b/quest/m1/ts-opus-channel-codes.md @@ -0,0 +1,27 @@ +# [S] TS Opus import refuses or parses extended channel codes + +## Goal + +An MPEG-TS Opus stream whose extension descriptor carries a +`channel_config_code` of 0x81 or above imports with its real OpusHead or is +refused. It never decodes as a guessed stereo stream, which misreads every +multistream packet. + +## Plan + +- The importer falls back to stereo for codes it does not know. 0x81 is + specified as an explicitly coded layout (channel count, mapping family, stream + counts, and table in the descriptor), and ffmpeg's muxer also writes + `0x80 | channels` for an alternate table its own demuxer does not read. Check + the Opus-in-TS spec and ffmpeg before deciding which codes to parse. +- Build parsed layouts with the public `opus::Mapping::new`, which validates + the table; refuse any code that is reserved or does not parse, per stream, + without failing the rest of the program. +- Fixtures from a real muxer where one exists; a hand-built descriptor + otherwise, noted as such. + +Public API: none. Wire: none. + +## Related + +- [TS Opus export refusals](/quest/m1/ts-opus-export-refusals.md) - the exporter side of the same descriptor diff --git a/quest/m1/ts-opus-export-refusals.md b/quest/m1/ts-opus-export-refusals.md new file mode 100644 index 00000000000..b376124fbf3 --- /dev/null +++ b/quest/m1/ts-opus-export-refusals.md @@ -0,0 +1,23 @@ +# [S] TS Opus export refuses what it cannot label + +## Goal + +`moq-mux`'s MPEG-TS exporter never labels an Opus track with a channel +configuration its packets do not have. A track whose OpusHead the Opus +extension descriptor can describe exports as today; anything else is refused, +not written with a guessed `channel_config_code`. + +## Plan + +- The exporter derives `channel_config_code` from the catalog channel count + alone, clamped to 1..=8, so a family 255 or ambisonics head, a family 1 head + with a non-Vorbis table, or more than eight channels exports mislabeled. + Decide from the parsed description: family 0, and family 1 with the Vorbis + default mapping, keep the plain code; refuse the rest, or write the explicit + layout if the import side of + [TS Opus channel codes](/quest/m1/ts-opus-channel-codes.md) settles + one both sides agree on. +- A track with no description stays mono or stereo only. +- Tests with real heads, checked against ffprobe where ffmpeg reads the result. + +Public API: none. Wire: none; TS output changes only for inputs it mislabeled. diff --git a/quest/m2/audio-decode-mediacodec.md b/quest/m2/audio-decode-mediacodec.md index 35498472260..5158823f91d 100644 --- a/quest/m2/audio-decode-mediacodec.md +++ b/quest/m2/audio-decode-mediacodec.md @@ -26,8 +26,6 @@ behind a new optional audio `mediacodec` feature and the decode seam, on `target ## Required - [Mobile ownership](/quest/m1/mobile-ownership.md) - if Kotlin owns platform codecs, this backend is moot -- [Decode seam](/quest/m1/audio-codecs/decode-backend.md) - the candidate order this backend joins -- [Layout](/quest/m1/audio-codecs/layout.md) - what a multichannel frame is delivered as ## Related diff --git a/quest/m2/audio-decode-mediafoundation.md b/quest/m2/audio-decode-mediafoundation.md index 2fb647fff1a..e480e5b00ce 100644 --- a/quest/m2/audio-decode-mediafoundation.md +++ b/quest/m2/audio-decode-mediafoundation.md @@ -22,11 +22,6 @@ ones. Behind the decode seam as the first candidate on `target_os = - Verification runs on a Windows host; the per-PR CI only compiles the platform code (`just rs windows`). -## Required - -- [Decode seam](/quest/m1/audio-codecs/decode-backend.md) - the candidate order this backend joins -- [Layout](/quest/m1/audio-codecs/layout.md) - what a multichannel frame is delivered as - ## Related - [Windows decoded frames](/quest/m2/obs-decode-windows.md) - the OBS Windows line this feeds diff --git a/quest/m2/audio-encode-mediacodec.md b/quest/m2/audio-encode-mediacodec.md index 5adc169241f..52ead7973e8 100644 --- a/quest/m2/audio-encode-mediacodec.md +++ b/quest/m2/audio-encode-mediacodec.md @@ -13,6 +13,9 @@ behind the `mediacodec` feature and the encode seam. - `audio/mp4a-latm` with `KEY_AAC_PROFILE` = LC. The catalog ASC is synthesized at construction per the encode seam, since `csd-0` only arrives with the first output buffer; assert the two match. +- MediaCodec pipelines output, which the one-packet-per-frame seam does not + allow yet: add a `flush` and a zero-or-more return, a change to + `Encoder::encode` that targets `dev`, unless the AudioToolbox quest already did. - Multichannel is device-dependent; probe the encoder's capabilities at open and refuse a layout it does not list. - Round-trip regression through the MediaCodec decoder; runtime proof on a @@ -21,6 +24,4 @@ behind the `mediacodec` feature and the encode seam. ## Required - [Mobile ownership](/quest/m1/mobile-ownership.md) - if Kotlin owns platform codecs, this backend is moot -- [Encode seam](/quest/m1/audio-codecs/encode-backend.md) - the candidate order this backend joins -- [Layout](/quest/m1/audio-codecs/layout.md) - the input layout the encoder accepts - [MediaCodec decode](/quest/m2/audio-decode-mediacodec.md) - the round-trip regression decodes through it diff --git a/quest/m2/audio-encode-mediafoundation.md b/quest/m2/audio-encode-mediafoundation.md index 6600698e7c4..97b0d3b62b0 100644 --- a/quest/m2/audio-encode-mediafoundation.md +++ b/quest/m2/audio-encode-mediafoundation.md @@ -20,6 +20,4 @@ behind the encode seam on Windows. ## Required -- [Encode seam](/quest/m1/audio-codecs/encode-backend.md) - the candidate order this backend joins -- [Layout](/quest/m1/audio-codecs/layout.md) - the input layout the encoder accepts - [Media Foundation decode](/quest/m2/audio-decode-mediafoundation.md) - the round-trip regression decodes through it diff --git a/rs/libmoq/src/audio.rs b/rs/libmoq/src/audio.rs index b23a57c18e0..21d3b1c2257 100644 --- a/rs/libmoq/src/audio.rs +++ b/rs/libmoq/src/audio.rs @@ -67,6 +67,9 @@ pub struct moq_audio_encoder_input { /// `moq_audio_sample_format` discriminant. pub format: u32, pub sample_rate: u32, + /// Interleaved channel count, which also names the speaker layout by the + /// WAVE convention: 1 mono, 2 stereo, 3 2.1, 4 quad, 5 5.0, 6 5.1, 7 6.1, + /// 8 7.1, in front left, front right, center, LFE, back, side order. pub channels: u32, } @@ -76,7 +79,8 @@ pub struct moq_audio_encoder_input { #[repr(C)] #[allow(non_camel_case_types)] pub struct moq_audio_encoder_output { - /// Codec id, UTF-8 (currently only "opus"). + /// Codec id, UTF-8: "opus", "pcm", or "aac". AAC encodes through the + /// platform's encoder, so a host without one refuses it. pub codec: *const c_char, pub codec_len: usize, /// 0 = derive from input. @@ -86,8 +90,8 @@ pub struct moq_audio_encoder_output { /// 0 = libopus default. pub bitrate: u32, /// Encoded frame duration in microseconds. Opus accepts exactly - /// 2500/5000/10000/20000/40000/60000 us. 0 = the 20 ms default, which - /// matches the JS publish path. + /// 2500/5000/10000/20000/40000/60000 us. 0 = the codec's default: 20 ms for + /// Opus, which matches the JS publish path, and 1024 samples for AAC. pub frame_duration_us: u32, } @@ -98,7 +102,9 @@ pub struct moq_audio_decoder_output { pub format: u32, /// 0 = deliver at the codec's native sample rate. pub sample_rate: u32, - /// 0 = deliver at the codec's native channel count. + /// 0 = deliver at the codec's native channel count. A count names its + /// layout as `moq_audio_encoder_input.channels` describes, and the decoder + /// remixes to it. pub channels: u32, /// Upper bound on buffering before skipping a stalled group, in /// microseconds. Same congestion-control knob as diff --git a/rs/moq-audio/Cargo.toml b/rs/moq-audio/Cargo.toml index 930600d357d..5fe9bc27161 100644 --- a/rs/moq-audio/Cargo.toml +++ b/rs/moq-audio/Cargo.toml @@ -27,7 +27,7 @@ default = ["aac"] # AAC-LC decode via symphonia. Pure Rust, so it costs no toolchain: the trade # this crate already refused for Opus. Only a subscriber to an ingest-sourced # broadcast needs it (RTMP, SRT/TS, fmp4, and gstreamer all publish AAC, while -# everything this crate encodes is Opus or PCM), so a publish-only build can +# this crate encodes in software is Opus or PCM), so a publish-only build can # drop it and the two crates it pulls. aac = ["dep:symphonia-codec-aac", "dep:symphonia-core"] # Device capture. Microphones go through cpal (pure-Rust: CoreAudio / WASAPI / diff --git a/rs/moq-audio/src/aac.rs b/rs/moq-audio/src/aac.rs index 7c8b9482334..52fb66e3dd3 100644 --- a/rs/moq-audio/src/aac.rs +++ b/rs/moq-audio/src/aac.rs @@ -1,7 +1,7 @@ //! AAC constraints, the sibling of the `opus` and `pcm` modules. //! -//! Only the decode side exists: there is no Rust AAC encoder, so this crate -//! publishes Opus or PCM and reads AAC that a gateway produced. +//! The decode side. There is no Rust AAC encoder, so `encode` produces AAC only +//! through a platform backend and otherwise reads AAC that a gateway produced. use crate::Error; diff --git a/rs/moq-audio/src/aec.rs b/rs/moq-audio/src/aec.rs index 607d0111cae..da24dda60a1 100644 --- a/rs/moq-audio/src/aec.rs +++ b/rs/moq-audio/src/aec.rs @@ -40,7 +40,7 @@ use sonora::config::{EchoCanceller, GainController2, NoiseSuppression, NoiseSupp use sonora::{AudioProcessing, StreamConfig}; use crate::Error; -use crate::playback::{self, BUS_CHANNELS}; +use crate::playback::{self, REFERENCE_CHANNELS}; /// Sample rate the echo reference is resampled to on its way out of the mixer. /// @@ -187,7 +187,7 @@ impl Control { "echo cancellation needs a microphone between 8 and 384 kHz (got {sample_rate})" ))); } - if channels == 0 || channels > BUS_CHANNELS as u32 { + if channels == 0 || channels > REFERENCE_CHANNELS as u32 { return Err(Error::Unsupported(format!( "echo cancellation accepts a mono or stereo microphone (got {channels} channels)" ))); @@ -381,9 +381,9 @@ impl State { self.pending = Vec::with_capacity(headroom); self.processed = Vec::with_capacity(headroom); - self.reference_frame = vec![0.0; REFERENCE_FRAME * BUS_CHANNELS]; - self.render_in = vec![0.0; REFERENCE_FRAME * BUS_CHANNELS]; - self.render_out = vec![0.0; REFERENCE_FRAME * BUS_CHANNELS]; + self.reference_frame = vec![0.0; REFERENCE_FRAME * REFERENCE_CHANNELS]; + self.render_in = vec![0.0; REFERENCE_FRAME * REFERENCE_CHANNELS]; + self.render_out = vec![0.0; REFERENCE_FRAME * REFERENCE_CHANNELS]; self.capture_in = vec![0.0; frame * channels]; self.capture_out = vec![0.0; frame * channels]; @@ -453,7 +453,7 @@ impl State { if let Some(reference) = reference { while reference.available_frames() >= REFERENCE_FRAME { reference.read_interleaved(reference_frame, false); - deinterleave(reference_frame, render_in, BUS_CHANNELS); + deinterleave(reference_frame, render_in, REFERENCE_CHANNELS); let _ = process_render(processor, render_in, render_out); } } @@ -484,7 +484,7 @@ impl State { /// The format the mixer's reference tap arrives in. fn reference_config() -> StreamConfig { - StreamConfig::new(REFERENCE_RATE, BUS_CHANNELS as u16) + StreamConfig::new(REFERENCE_RATE, REFERENCE_CHANNELS as u16) } /// Feed one reference frame to the echo model. @@ -602,7 +602,7 @@ impl Reference { /// canceller reads it back at [`REFERENCE_RATE`]. fn channel(rate: u32) -> (ResamplingProd, ResamplingCons) { resampling_channel::( - BUS_CHANNELS, + REFERENCE_CHANNELS, rate, REFERENCE_RATE, true, @@ -652,7 +652,7 @@ mod tests { /// Push one 10 ms stereo frame of `value` into the tap. fn play(prod: &mut ResamplingProd, value: f32) { - prod.push_interleaved(&vec![value; REFERENCE_FRAME * BUS_CHANNELS]); + prod.push_interleaved(&vec![value; REFERENCE_FRAME * REFERENCE_CHANNELS]); } #[test] @@ -976,10 +976,10 @@ mod tests { fn round(&mut self) -> (f64, f64) { let played: Vec = (0..self.frame).map(|_| self.noise.next()).collect(); - let mut reference = vec![0.0f32; self.frame * BUS_CHANNELS]; + let mut reference = vec![0.0f32; self.frame * REFERENCE_CHANNELS]; for (i, sample) in played.iter().enumerate() { - reference[i * BUS_CHANNELS] = *sample; - reference[i * BUS_CHANNELS + 1] = *sample; + reference[i * REFERENCE_CHANNELS] = *sample; + reference[i * REFERENCE_CHANNELS + 1] = *sample; } self.prod.push_interleaved(&reference); @@ -1112,13 +1112,13 @@ mod tests { let mut tone = Vec::with_capacity(frames * 2 * 4); for frame in 0..frames { let value = (std::f32::consts::TAU * 440.0 * frame as f32 / 48_000.0).sin() * 0.5; - for _ in 0..BUS_CHANNELS { + for _ in 0..REFERENCE_CHANNELS { tone.extend_from_slice(&value.to_le_bytes()); } } let mut energy = 0.0f64; - let mut buf = vec![0.0f32; REFERENCE_FRAME * BUS_CHANNELS]; + let mut buf = vec![0.0f32; REFERENCE_FRAME * REFERENCE_CHANNELS]; for _ in 0..20 { let _ = sink.write(&tone).expect("write"); diff --git a/rs/moq-audio/src/decode/backend/libopus.rs b/rs/moq-audio/src/decode/backend/libopus.rs new file mode 100644 index 00000000000..07b03607b05 --- /dev/null +++ b/rs/moq-audio/src/decode/backend/libopus.rs @@ -0,0 +1,440 @@ +//! Opus through libopus, the software decoder for every host. +//! +//! Every stream goes through the multistream decoder, which is also how a +//! family 0 (mono/stereo) stream decodes: one stream, coupled when stereo. + +use unsafe_libopus::{ + OPUS_OK, OPUS_RESET_STATE, OPUS_SET_GAIN_REQUEST, OpusMSDecoder, opus_multistream_decode_float, + opus_multistream_decoder_create, opus_multistream_decoder_ctl_impl, opus_multistream_decoder_destroy, varargs, +}; + +use super::Backend; +use crate::decode::Decoded; +use crate::{Error, Layout, opus}; + +pub(super) const NAME: &str = "libopus"; + +/// Opus packets cap at 120 ms (RFC 6716 §2.1.4). +const MAX_FRAME_MS: usize = 120; + +/// The family 0 streams: one stream, coupled when stereo, decoded in order. +const MONO: &[u8] = &[0]; +const STEREO: &[u8] = &[0, 1]; + +pub(super) struct Libopus { + inner: *mut OpusMSDecoder, + layout: Layout, + /// For each canonical channel, the Vorbis-order channel it comes from, when they differ. + reorder: Option<&'static [usize]>, + /// Opus streams in one packet. Family 0 is one; the rest come from the mapping. + streams: u8, + pre_skip: usize, + max_frame_size: usize, + /// Frames per channel in the last packet that decoded, which is what a lost + /// packet most likely carried. `None` until one has. + last_frame_size: Option, + in_dtx: bool, +} + +// SAFETY: the decoder is owned exclusively and libopus keeps no thread-local state. +unsafe impl Send for Libopus {} + +impl Libopus { + /// Decodes at 48 kHz with the pre-skip and output gain the OpusHead + /// `description` declares; its input rate is metadata. A missing description + /// falls back to the catalog's channel count, which must then be mono or + /// stereo. A description that does not parse is refused: guessing family 0 + /// would decode those packets with the wrong stream layout. + /// + /// Channel mapping family 1 decodes up to 7.1 in the canonical [`Layout`] + /// order; every other family is refused, since none declares speakers. + pub(super) fn open(catalog: &hang::catalog::AudioConfig) -> Result, Error> { + let head = opus::head(catalog)?; + let channel_count = head.channel_count; + + let (streams, coupled, table, layout, reorder) = match &head.mapping { + None => { + let table = match opus::validate_channels(channel_count)? { + 1 => MONO, + _ => STEREO, + }; + let layout = Layout::from_channels(channel_count)?; + (1, table.len() as i32 - 1, table, layout, None) + } + Some(mapping) if mapping.family() == 1 => { + let (layout, reorder) = vorbis(channel_count)?; + let (streams, coupled) = (mapping.streams() as i32, mapping.coupled() as i32); + (streams, coupled, mapping.table(), layout, reorder) + } + Some(mapping) => { + return Err(Error::Unsupported(format!( + "opus channel mapping family {} declares no speaker positions", + mapping.family() + ))); + } + }; + + let mut err = 0i32; + // SAFETY: `table` holds one entry per output channel, the count we pass, + // and the out-pointer is valid; inner is checked for null below. + let inner = unsafe { + opus_multistream_decoder_create( + opus::DECODE_RATE as i32, + table.len() as i32, + streams, + coupled, + table.as_ptr(), + &mut err, + ) + }; + if err != OPUS_OK || inner.is_null() { + return Err(opus::error(err, "opus_multistream_decoder_create")); + } + + // Owned before the gain ctl so a failure there still destroys the decoder. + let decoder = Self { + inner, + layout, + reorder, + streams: streams as u8, + pre_skip: head.pre_skip as usize, + max_frame_size: (opus::DECODE_RATE as usize * MAX_FRAME_MS) / 1000, + last_frame_size: None, + in_dtx: false, + }; + + // Same Q7.8 dB units as OpusHead, and it survives OPUS_RESET_STATE. + // SAFETY: `inner` owns a live decoder and OPUS_SET_GAIN takes one i32. + let rc = unsafe { + opus_multistream_decoder_ctl_impl(decoder.inner, OPUS_SET_GAIN_REQUEST, varargs![head.output_gain as i32]) + }; + if rc != OPUS_OK { + return Err(opus::error(rc, "OPUS_SET_GAIN")); + } + + Ok(Box::new(decoder)) + } +} + +/// The layout a family 1 stream of `channels` declares (RFC 7845 §5.1.1.2), and +/// how to reorder its Vorbis channel order into that layout's canonical one. +/// +/// Vorbis puts the center between the fronts and the LFE last. Its "rear" +/// pair in 5.0 and 5.1 is the surround pair, which is side in the canonical +/// layouts, while 7.1 has distinct side and rear pairs. +fn vorbis(channels: u32) -> Result<(Layout, Option<&'static [usize]>), Error> { + Ok(match channels { + 1 => (Layout::Mono, None), + 2 => (Layout::Stereo, None), + // L, C, R. + 3 => (Layout::ThreePointZero, Some(&[0, 2, 1])), + // FL, FR, RL, RR. + 4 => (Layout::Quad, None), + // FL, C, FR, RL, RR. + 5 => (Layout::FivePointZero, Some(&[0, 2, 1, 3, 4])), + // FL, C, FR, RL, RR, LFE. + 6 => (Layout::FivePointOne, Some(&[0, 2, 1, 5, 3, 4])), + // FL, C, FR, SL, SR, RC, LFE. + 7 => (Layout::SixPointOne, Some(&[0, 2, 1, 6, 5, 3, 4])), + // FL, C, FR, SL, SR, RL, RR, LFE. + 8 => (Layout::SevenPointOne, Some(&[0, 2, 1, 7, 5, 6, 3, 4])), + other => { + return Err(Error::Unsupported(format!( + "opus channel mapping family 1 has no {other}-channel layout" + ))); + } + }) +} + +impl Backend for Libopus { + /// An empty packet conceals as much audio as the last packet that decoded + /// held, and is refused before any has. Loss during DTX remains classified + /// as DTX, while loss during active audio remains active. + fn decode(&mut self, packet: &[u8]) -> Result { + let channels = self.layout.channels() as usize; + // libopus conceals exactly `frame_size` samples for a lost packet, and + // the decoder can't know how long it was, so assume the last one's length. + // A real packet decodes into the most it can hold. + let frame_size = if packet.is_empty() { + self.last_frame_size.ok_or_else(|| { + Error::Decode("opus packet lost before any packet decoded, so no length to conceal".into()) + })? + } else { + self.max_frame_size + }; + let mut out = vec![0.0f32; frame_size * channels]; + // SAFETY: `inner` owns a live OpusMSDecoder; packet/out slices are bounded by + // the lengths we pass. + let samples = unsafe { + opus_multistream_decode_float( + self.inner, + packet.as_ptr(), + packet.len() as i32, + out.as_mut_ptr(), + frame_size as i32, + 0, + ) + }; + if samples < 0 { + return Err(opus::decode_error(samples)); + } + if !packet.is_empty() { + self.last_frame_size = Some(samples as usize); + } + out.truncate(samples as usize * channels); + + if let Some(order) = self.reorder { + let mut vorbis = [0.0f32; 8]; + for frame in out.chunks_exact_mut(channels) { + vorbis[..channels].copy_from_slice(frame); + for (sample, &from) in frame.iter_mut().zip(order) { + *sample = vorbis[from]; + } + } + } + + let activity = opus::multistream_activity(packet, self.streams, self.in_dtx); + self.in_dtx = activity.is_dtx(); + Ok(Decoded { samples: out, activity }) + } + + fn reset(&mut self) -> Result<(), Error> { + // SAFETY: `inner` owns a live decoder and OPUS_RESET_STATE takes no arguments. + let rc = unsafe { opus_multistream_decoder_ctl_impl(self.inner, OPUS_RESET_STATE, varargs![]) }; + if rc != OPUS_OK { + return Err(opus::error(rc, "OPUS_RESET_STATE")); + } + self.in_dtx = false; + Ok(()) + } + + fn sample_rate(&self) -> u32 { + opus::DECODE_RATE + } + + fn layout(&self) -> Layout { + self.layout + } + + fn delay(&self) -> usize { + self.pre_skip + } + + fn name(&self) -> &str { + NAME + } +} + +impl Drop for Libopus { + fn drop(&mut self) { + // SAFETY: `inner` is a live OpusMSDecoder that nothing else aliases. + unsafe { opus_multistream_decoder_destroy(self.inner) }; + } +} + +#[cfg(test)] +mod tests { + use unsafe_libopus::{ + OPUS_APPLICATION_AUDIO, opus_multistream_encode_float, opus_multistream_encoder_destroy, + opus_multistream_surround_encoder_create, + }; + + use crate::Error; + use crate::decode::{Config, Decoder}; + use crate::layout::Speaker::{self, *}; + + /// Speakers in Vorbis channel order for each family 1 channel count (RFC 7845 §5.1.1.2). + const VORBIS: [&[Speaker]; 8] = [ + &[FrontCenter], + &[FrontLeft, FrontRight], + &[FrontLeft, FrontCenter, FrontRight], + &[FrontLeft, FrontRight, BackLeft, BackRight], + &[FrontLeft, FrontCenter, FrontRight, SideLeft, SideRight], + &[FrontLeft, FrontCenter, FrontRight, SideLeft, SideRight, Lfe], + &[FrontLeft, FrontCenter, FrontRight, SideLeft, SideRight, BackCenter, Lfe], + &[ + FrontLeft, + FrontCenter, + FrontRight, + SideLeft, + SideRight, + BackLeft, + BackRight, + Lfe, + ], + ]; + + const RATE: usize = 48_000; + const FRAME: usize = 960; + const PACKETS: usize = 15; + + /// A distinct tone per speaker, low for the LFE, which libopus band-limits. + fn tone(speaker: Speaker) -> f32 { + match speaker { + Lfe => 80.0, + other => 400.0 + 300.0 * other as u8 as f32, + } + } + + /// Encode `channels` of Vorbis-ordered tones as a family 1 stream, returning + /// its OpusHead and packets. + fn surround(channels: usize) -> (bytes::Bytes, Vec>) { + let speakers = VORBIS[channels - 1]; + let (mut streams, mut coupled, mut mapping) = (0i32, 0i32, [0u8; 8]); + let mut err = 0i32; + // SAFETY: every out-pointer is valid and `mapping` holds `channels` entries. + let encoder = unsafe { + opus_multistream_surround_encoder_create( + RATE as i32, + channels as i32, + 1, + &mut streams, + &mut coupled, + mapping.as_mut_ptr(), + OPUS_APPLICATION_AUDIO, + &mut err, + ) + }; + assert!(err == 0 && !encoder.is_null(), "encoder create failed: {err}"); + + let packets = (0..PACKETS) + .map(|packet| { + let mut pcm = Vec::with_capacity(FRAME * channels); + for i in packet * FRAME..(packet + 1) * FRAME { + for &speaker in speakers { + let phase = std::f32::consts::TAU * tone(speaker) * i as f32 / RATE as f32; + pcm.push(phase.sin() * 0.5); + } + } + let mut out = vec![0u8; 4000]; + // SAFETY: `encoder` is live, `pcm` holds FRAME frames, and `out` is as long as we say. + let len = unsafe { + opus_multistream_encode_float(encoder, pcm.as_ptr(), FRAME as i32, out.as_mut_ptr(), 4000) + }; + assert!(len > 0, "encode failed: {len}"); + out.truncate(len as usize); + out + }) + .collect(); + // SAFETY: `encoder` is live and not used again. + unsafe { opus_multistream_encoder_destroy(encoder) }; + + let mut head = moq_mux::codec::opus::Config::new(RATE as u32, 2) + .encode() + .unwrap() + .to_vec(); + head[9] = channels as u8; + head[18] = 1; + head.extend_from_slice(&[streams as u8, coupled as u8]); + head.extend_from_slice(&mapping[..channels]); + (head.into(), packets) + } + + fn catalog(head: bytes::Bytes, channels: u32) -> hang::catalog::AudioConfig { + let mut catalog = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Opus, 48_000, channels); + catalog.description = Some(head); + catalog + } + + /// Energy of `samples` at `freq`, by the Goertzel recurrence. + fn power(samples: &[f32], freq: f32) -> f32 { + let coeff = 2.0 * (std::f32::consts::TAU * freq / RATE as f32).cos(); + let (mut s1, mut s2) = (0.0f32, 0.0f32); + for &x in samples { + let s = x + coeff * s1 - s2; + s2 = s1; + s1 = s; + } + s1 * s1 + s2 * s2 - coeff * s1 * s2 + } + + /// Every family 1 layout decodes with each canonical channel carrying its + /// own speaker's tone, which pins the Vorbis reorder independently of it. + #[test] + fn family_one_decodes_in_canonical_order() { + for channels in 1..=8 { + let (head, packets) = surround(channels); + let mut decoder = Decoder::new(&catalog(head, channels as u32), &Config::default()).unwrap(); + let layout = decoder.layout(); + // The layout has exactly the Vorbis speakers, which canonical order sorts. + let mut speakers = VORBIS[channels - 1].to_vec(); + speakers.sort_by_key(|&speaker| speaker as u8); + assert_eq!(layout.speakers().unwrap(), speakers, "{channels} channels"); + + let mut pcm = Vec::new(); + for packet in &packets { + pcm.extend(decoder.decode(packet).unwrap().samples); + } + // Skip the encoder's warmup. + let pcm = &pcm[pcm.len() / 2..]; + + let tones: Vec = VORBIS[channels - 1].iter().copied().map(tone).collect(); + for (index, &speaker) in layout.speakers().unwrap().iter().enumerate() { + let channel: Vec = pcm.iter().skip(index).step_by(channels).copied().collect(); + let loudest = tones + .iter() + .copied() + .max_by(|a, b| power(&channel, *a).total_cmp(&power(&channel, *b))) + .unwrap(); + assert_eq!(loudest, tone(speaker), "{channels} channels, {speaker:?} at {index}"); + } + } + } + + /// An all-DTX surround packet is one empty Opus packet per stream. Read as a + /// single stream, the later subpackets look like payload and the span is lost. + #[test] + fn surround_silence_is_dtx() { + let (head, packets) = surround(6); + let mut decoder = Decoder::new(&catalog(head.clone(), 6), &Config::default()).unwrap(); + let mid = decoder.decode(&packets[PACKETS / 2]).unwrap(); + assert!(mid.activity.is_active(), "a coded surround frame must stay active"); + + // Two coupled streams, then two mono, each a 20 ms empty frame. + let dtx = [0xfc, 0x00, 0xfc, 0x00, 0xf8, 0x00, 0xf8]; + let mut decoder = Decoder::new(&catalog(head, 6), &Config::default()).unwrap(); + let decoded = decoder.decode(&dtx).expect("empty multistream packet"); + assert!(decoded.activity.is_dtx(), "all-DTX surround packet read as active"); + assert_eq!(decoded.samples.len() % 6, 0); + } + + /// A description that is present but truncated used to be dropped, and a + /// stereo catalog then opened a family 0 decoder for a family 1 or 255 head. + #[test] + fn malformed_description_is_refused() { + for family in [1u8, 255] { + let mut head = moq_mux::codec::opus::Config::new(48_000, 2).encode().unwrap().to_vec(); + head[18] = family; + let err = Decoder::new(&catalog(head.into(), 2), &Config::default()) + .err() + .expect("refused"); + assert!( + matches!(&err, Error::Unsupported(message) if message.contains("opus description")), + "family {family}: {err}" + ); + } + + let plain = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Opus, 48_000, 2); + assert!(Decoder::new(&plain, &Config::default()).is_ok()); + } + + /// Families other than 0 and 1 carry no speaker positions, so there is + /// nothing to put in a layout: refused, not passed through as discrete. + #[test] + fn other_families_are_refused() { + for (family, channels, table) in [(255u8, 2u8, &[2, 0, 0, 1][..]), (2, 4, &[4, 0, 0, 1, 2, 3])] { + let mut head = moq_mux::codec::opus::Config::new(48_000, 2).encode().unwrap().to_vec(); + head[9] = channels; + head[18] = family; + head.extend_from_slice(table); + + let err = Decoder::new(&catalog(head.into(), channels.into()), &Config::default()) + .err() + .expect("refused"); + assert!( + matches!(&err, Error::Unsupported(message) if message.contains("no speaker positions")), + "family {family}: {err}" + ); + } + } +} diff --git a/rs/moq-audio/src/decode/backend/mod.rs b/rs/moq-audio/src/decode/backend/mod.rs new file mode 100644 index 00000000000..45d76b3e6f2 --- /dev/null +++ b/rs/moq-audio/src/decode/backend/mod.rs @@ -0,0 +1,289 @@ +//! Pluggable audio decoder backends. +//! +//! The audio mirror of `moq-video`'s decode backends. [`Backend`] is the seam +//! between the codec and the [`Decoder`](super::Decoder) front end, which owns +//! what every codec shares: trimming the startup delay a backend reports. +//! +//! [`open`] tries the platform decoders before the software ones, skipping any +//! that does not advertise the catalog codec, and refuses when none opens the +//! track. [`Kind::Named`] names the codec, not a backend, so which backend +//! decodes it stays the library's choice. The software tier is libopus for Opus, a passthrough for PCM, and +//! symphonia for AAC-LC mono and stereo (behind the `aac` feature). No platform +//! decoder is wired in yet. + +use hang::catalog::{AudioCodec, AudioConfig}; + +use super::Decoded; +use super::decoder::{Config, Kind}; +use crate::{Error, Layout}; + +mod libopus; +mod pcm; +#[cfg(feature = "aac")] +mod symphonia; + +/// An opened decoder: packets in, interleaved `f32` PCM out. +/// +/// Unwind safe because the published `Decoder` that boxes it is. +pub(crate) trait Backend: Send + std::panic::UnwindSafe + std::panic::RefUnwindSafe { + /// Decode one packet into interleaved samples at [`sample_rate`](Self::sample_rate) + /// and [`layout`](Self::layout), untrimmed. + fn decode(&mut self, packet: &[u8]) -> Result; + + /// Drop codec history after a discontinuity, so the next packet does not + /// predict from audio that is no longer adjacent. + fn reset(&mut self) -> Result<(), Error>; + + /// The rate this backend decodes to, which may differ from the catalog's. + fn sample_rate(&self) -> u32; + + /// The layout this backend decodes to, which may differ from the catalog's. + fn layout(&self) -> Layout; + + /// Frames at the start of the stream that are codec priming, not media. + fn delay(&self) -> usize { + 0 + } + + /// The stable lowercase name of this backend, as [`Decoder::name`](super::Decoder::name) + /// reports it. Callers never select by it. + fn name(&self) -> &str; +} + +type Open = fn(&AudioConfig) -> Result, Error>; + +/// A backend constructor: its name, the catalog codecs it advertises, and an opener. +struct Candidate { + name: &'static str, + supports: fn(&AudioCodec) -> bool, + open: Open, +} + +/// Operating-system decoders, in priority order. +const PLATFORM: &[Candidate] = &[]; + +const SOFTWARE: &[Candidate] = &[ + Candidate { + name: libopus::NAME, + supports: |codec| matches!(codec, AudioCodec::Opus), + open: libopus::Libopus::open, + }, + Candidate { + name: pcm::NAME, + supports: |codec| matches!(codec, AudioCodec::Pcm), + open: pcm::Pcm::open, + }, + // Claims every AAC profile and refuses at open what it can't decode: the + // profile that matters is the description's, which the catalog string can + // contradict. + #[cfg(feature = "aac")] + Candidate { + name: symphonia::NAME, + supports: |codec| matches!(codec, AudioCodec::AAC(_)), + open: symphonia::Symphonia::open, + }, +]; + +/// The name [`Kind::Named`] uses for a catalog codec, `None` for one this crate has no name for. +fn codec_name(codec: &AudioCodec) -> Option<&'static str> { + match codec { + AudioCodec::Opus => Some("opus"), + AudioCodec::Pcm => Some("pcm"), + AudioCodec::AAC(_) => Some("aac"), + _ => None, + } +} + +/// Open the first backend that advertises the catalog codec and accepts the track. +pub(crate) fn open(catalog: &AudioConfig, config: &Config) -> Result, Error> { + if let Kind::Named(requested) = &config.kind + && codec_name(&catalog.codec) != Some(requested) + { + return Err(Error::Unsupported(format!( + "audio decoder {requested:?} is unavailable for {}", + catalog.codec + ))); + } + + select(catalog, candidates(&config.kind, PLATFORM, SOFTWARE)) +} + +/// The candidates `kind` allows, in the order to try them. +/// +/// Takes the tiers as arguments so a test can supply stubs instead of whatever +/// this host compiles in. +fn candidates<'a>(kind: &Kind, platform: &'a [Candidate], software: &'a [Candidate]) -> Vec<&'a Candidate> { + match kind { + Kind::Software => software.iter().collect(), + // `open` has already checked that a name matches the codec. + Kind::Auto | Kind::Named(_) => platform.iter().chain(software).collect(), + } +} + +fn select(catalog: &AudioConfig, candidates: Vec<&Candidate>) -> Result, Error> { + let codec = &catalog.codec; + let mut refused = Vec::new(); + + for candidate in candidates { + if !(candidate.supports)(codec) { + continue; + } + match (candidate.open)(catalog) { + Ok(backend) => return Ok(backend), + Err(err) => refused.push((candidate.name, err)), + } + } + + // One refusal is the whole answer, so keep its variant: a malformed + // description stays a container error rather than becoming a string. + if refused.len() == 1 { + let (_, err) = refused.remove(0); + return Err(err); + } + if !refused.is_empty() { + let reasons: Vec = refused.iter().map(|(name, err)| format!("{name}: {err}")).collect(); + return Err(Error::Unsupported(reasons.join(", "))); + } + + Err(Error::Unsupported(format!("unsupported audio codec: {codec}"))) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::Activity; + + /// Opens anything it advertises and reports which candidate it came from. + struct Stub(&'static str); + + impl Backend for Stub { + fn decode(&mut self, _packet: &[u8]) -> Result { + Ok(Decoded { + samples: Vec::new(), + activity: Activity::Active, + }) + } + + fn reset(&mut self) -> Result<(), Error> { + Ok(()) + } + + fn sample_rate(&self) -> u32 { + 48_000 + } + + fn layout(&self) -> Layout { + Layout::Stereo + } + + fn name(&self) -> &str { + self.0 + } + } + + const PLATFORM_STUB: Candidate = Candidate { + name: "platform", + supports: |codec| matches!(codec, AudioCodec::Opus), + open: |_| Ok(Box::new(Stub("platform"))), + }; + + /// Compiled in but refusing the track, like a platform decoder asked for a + /// layout its framework does not open. + const REFUSING: Candidate = Candidate { + name: "refusing", + supports: |codec| matches!(codec, AudioCodec::Opus), + open: |_| Err(Error::Unsupported("not this track".into())), + }; + + const SOFTWARE_STUB: Candidate = Candidate { + name: "software", + supports: |codec| matches!(codec, AudioCodec::Opus), + open: |_| Ok(Box::new(Stub("software"))), + }; + + /// Advertises nothing but PCM, so an Opus track never reaches its opener. + const PCM_ONLY: Candidate = Candidate { + name: "pcm-only", + supports: |codec| matches!(codec, AudioCodec::Pcm), + open: |_| panic!("opened for a codec it does not advertise"), + }; + + fn opus() -> AudioConfig { + AudioConfig::new(AudioCodec::Opus, 48_000, 2) + } + + fn pick(kind: Kind, platform: &[Candidate], software: &[Candidate]) -> Result { + let backend = select(&opus(), candidates(&kind, platform, software))?; + Ok(backend.name().to_owned()) + } + + #[test] + fn auto_prefers_platform() { + let name = pick(Kind::Auto, &[PCM_ONLY, PLATFORM_STUB], &[SOFTWARE_STUB]).unwrap(); + assert_eq!(name, "platform"); + } + + #[test] + fn auto_falls_back_to_software() { + let name = pick(Kind::Auto, &[REFUSING], &[SOFTWARE_STUB]).unwrap(); + assert_eq!(name, "software"); + } + + #[test] + fn software_skips_platform() { + let name = pick(Kind::Software, &[PLATFORM_STUB], &[SOFTWARE_STUB]).unwrap(); + assert_eq!(name, "software"); + } + + /// A codec name is not a backend selector: it tries the same tiers as `Auto`. + #[test] + fn named_codec_picks_like_auto() { + let name = pick(Kind::Named("opus".into()), &[PLATFORM_STUB], &[SOFTWARE_STUB]).unwrap(); + assert_eq!(name, "platform"); + } + + #[test] + fn every_refusal_is_reported() { + const ALSO_REFUSING: Candidate = Candidate { + name: "also-refusing", + ..REFUSING + }; + + let err = pick(Kind::Auto, &[REFUSING], &[ALSO_REFUSING]).unwrap_err(); + let message = err.to_string(); + assert!( + message.contains("refusing: ") && message.contains("also-refusing: "), + "{message}" + ); + } + + fn named(name: &str) -> Config { + Config { + kind: Kind::Named(name.into()), + } + } + + /// The codec names published moq-audio accepts still open their codec. + #[test] + fn codec_names_open_their_codec() { + let pcm = AudioConfig::new(AudioCodec::Pcm, 48_000, 2); + assert_eq!(open(&pcm, &named("pcm")).unwrap().name(), pcm::NAME); + assert_eq!(open(&opus(), &named("opus")).unwrap().name(), libopus::NAME); + } + + /// A name for another codec is refused, not quietly swapped for one that decodes. + #[test] + fn another_codecs_name_is_refused() { + assert!(matches!(open(&opus(), &named("pcm")), Err(Error::Unsupported(_)))); + } + + /// Backend names are internal: asking for one is refused like any unknown name. + #[test] + fn backend_names_are_refused() { + let message = open(&opus(), &named(libopus::NAME)) + .err() + .expect("libopus is a backend, not a codec") + .to_string(); + assert!(message.contains("\"libopus\"") && message.contains("opus"), "{message}"); + } +} diff --git a/rs/moq-audio/src/decode/backend/pcm.rs b/rs/moq-audio/src/decode/backend/pcm.rs new file mode 100644 index 00000000000..bead86fb5e0 --- /dev/null +++ b/rs/moq-audio/src/decode/backend/pcm.rs @@ -0,0 +1,78 @@ +//! Uncompressed little-endian `f32` PCM, described entirely by the catalog. + +use super::Backend; +use crate::decode::Decoded; +use crate::{Activity, Error, Layout, pcm}; + +pub(super) const NAME: &str = "pcm"; + +pub(super) struct Pcm { + sample_rate: u32, + layout: Layout, + bytes_per_frame: usize, +} + +impl Pcm { + /// Uses the catalog's rate and channel count, and requires an absent `description`. + pub(super) fn open(catalog: &hang::catalog::AudioConfig) -> Result, Error> { + if catalog.sample_rate == 0 { + return Err(Error::Unsupported("pcm sample rate must be greater than zero".into())); + } + if catalog.channel_count == 0 { + return Err(Error::Unsupported("pcm channel count must be greater than zero".into())); + } + if catalog.description.is_some() { + return Err(Error::Unsupported("pcm catalog description must be absent".into())); + } + let bitrate = pcm::bitrate(catalog.sample_rate, catalog.channel_count)?; + if catalog.bitrate.is_some_and(|declared| declared != bitrate) { + return Err(Error::Unsupported(format!( + "pcm catalog bitrate must be {bitrate} bits per second" + ))); + } + + Ok(Box::new(Self { + sample_rate: catalog.sample_rate, + layout: Layout::from_channels(catalog.channel_count)?, + bytes_per_frame: pcm::frame_bytes(1, catalog.channel_count)?, + })) + } +} + +impl Backend for Pcm { + fn decode(&mut self, packet: &[u8]) -> Result { + if packet.is_empty() || !packet.len().is_multiple_of(self.bytes_per_frame) { + return Err(Error::Misaligned { + got: packet.len(), + expected: packet.len().max(1).next_multiple_of(self.bytes_per_frame), + }); + } + + let samples = packet + .as_chunks::<{ pcm::BYTES_PER_SAMPLE }>() + .0 + .iter() + .map(|sample| f32::from_le_bytes(*sample)) + .collect(); + Ok(Decoded { + samples, + activity: Activity::Active, + }) + } + + fn reset(&mut self) -> Result<(), Error> { + Ok(()) + } + + fn sample_rate(&self) -> u32 { + self.sample_rate + } + + fn layout(&self) -> Layout { + self.layout + } + + fn name(&self) -> &str { + NAME + } +} diff --git a/rs/moq-audio/src/decode/backend/symphonia.rs b/rs/moq-audio/src/decode/backend/symphonia.rs new file mode 100644 index 00000000000..e2a87c6253d --- /dev/null +++ b/rs/moq-audio/src/decode/backend/symphonia.rs @@ -0,0 +1,106 @@ +//! AAC-LC through symphonia, the pure-Rust fallback for hosts without a +//! platform AAC decoder. + +use symphonia_core::codecs::audio::AudioDecoder; + +use super::Backend; +use crate::decode::Decoded; +use crate::{Activity, Error, Layout, aac}; + +pub(super) const NAME: &str = "symphonia"; + +pub(super) struct Symphonia { + inner: symphonia_codec_aac::AacDecoder, + sample_rate: u32, + layout: Layout, +} + +impl Symphonia { + /// AAC-LC in mono or stereo only, which is what every gateway that feeds + /// this crate publishes. + /// + /// HE-AAC is rejected however its config spells it: leading with SBR or PS + /// (mp4a.40.5 / .29), or leading with LC and declaring SBR in a sync extension + /// after the core. Symphonia decodes no SBR either way, so the alternative is + /// half-rate audio that sounds like a fault rather than an unsupported codec. + /// A stream that signals SBR only in band is indistinguishable from LC in the + /// config, and does decode as the core. + pub(super) fn open(catalog: &hang::catalog::AudioConfig) -> Result, Error> { + use symphonia_core::codecs::audio::well_known::CODEC_ID_AAC; + use symphonia_core::codecs::audio::{AudioCodecParameters, AudioDecoderOptions}; + + let hang::catalog::AudioCodec::AAC(codec) = &catalog.codec else { + return Err(Error::Unsupported(format!("symphonia cannot decode {}", catalog.codec))); + }; + let description = aac::description(catalog, codec.profile)?; + + let mut params = AudioCodecParameters::new(); + params + .for_codec(CODEC_ID_AAC) + .with_extra_data(description.to_vec().into_boxed_slice()); + + let inner = symphonia_codec_aac::AacDecoder::try_new(¶ms, &AudioDecoderOptions::default()) + .map_err(|err| Error::Unsupported(format!("aac decoder: {err}")))?; + + // Resolved by the decoder from the config, so this is what it will emit + // even when the catalog's own fields say otherwise. + let params = inner.codec_params(); + let sample_rate = params + .sample_rate + .ok_or_else(|| Error::Unsupported("aac config declares no sample rate".into()))?; + let channel_count = params + .channels + .as_ref() + .map(|channels| channels.count()) + .ok_or_else(|| Error::Unsupported("aac config declares no channels".into()))?; + + Ok(Box::new(Self { + inner, + sample_rate, + layout: Layout::from_channels(channel_count as u32)?, + })) + } +} + +impl Backend for Symphonia { + fn decode(&mut self, packet: &[u8]) -> Result { + // The packet is a raw AAC frame, not ADTS, so there is nothing to timestamp + // it with here: the container carries the timestamp and the decoder only + // reads the payload. + let packet = symphonia_core::packet::PacketRef::new( + 0, + symphonia_core::units::Timestamp::ZERO, + symphonia_core::units::Duration::ZERO, + packet, + ); + + let decoded = self + .inner + .decode_ref(&packet) + .map_err(|err| Error::Decode(format!("aac: {err}")))?; + + let mut samples = Vec::new(); + decoded.copy_to_vec_interleaved(&mut samples); + Ok(Decoded { + samples, + activity: Activity::Active, + }) + } + + fn reset(&mut self) -> Result<(), Error> { + self.inner.reset(); + Ok(()) + } + + fn sample_rate(&self) -> u32 { + self.sample_rate + } + + fn layout(&self) -> Layout { + self.layout + } + + fn name(&self) -> &str { + NAME + } +} diff --git a/rs/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index 52f448a5322..1259d8addf1 100644 --- a/rs/moq-audio/src/decode/consumer.rs +++ b/rs/moq-audio/src/decode/consumer.rs @@ -5,7 +5,7 @@ use std::collections::VecDeque; use bytes::Bytes; use super::decoder::{Config, Decoder}; -use crate::resample::{Resampler, remix, validate_remix}; +use crate::resample::{Remix, Resampler}; use crate::{Activity, Error, Format, Frame, Layout}; /// Where a consumer starts on a track that already holds groups. @@ -63,6 +63,8 @@ pub struct Consumer { decoder: Decoder, track: moq_mux::container::Consumer, resampler: Option, + /// Converts the decoded layout to the output's, when they differ. + remix: Option, options: Options, max_age: std::time::Duration, resolved_sample_rate: u32, @@ -111,7 +113,9 @@ impl Consumer { let decoder = Decoder::new(catalog, &options.decoder)?; let sample_rate = options.output.sample_rate.unwrap_or_else(|| decoder.sample_rate()); let layout = options.output.layout.unwrap_or_else(|| decoder.layout()); - validate_remix(decoder.layout(), layout)?; + let remix = (decoder.layout() != layout) + .then(|| Remix::new(decoder.layout(), layout)) + .transpose()?; let resampler = if sample_rate == decoder.sample_rate() { None @@ -165,6 +169,7 @@ impl Consumer { decoder, track, resampler, + remix, options, max_age, resolved_sample_rate: sample_rate, @@ -182,6 +187,11 @@ impl Consumer { }) } + /// The decoder backend name in use, e.g. `"libopus"` or `"symphonia"`. + pub fn name(&self) -> &str { + self.decoder.name() + } + /// The options this consumer was built with. pub fn options(&self) -> &Options { &self.options @@ -438,10 +448,9 @@ impl Consumer { /// Remix and pack decoded PCM into an output frame. fn frame(&self, pcm: Vec, timestamp: moq_net::Timestamp, activity: Activity) -> Result { - let pcm = if self.decoder.layout() == self.resolved_layout { - pcm - } else { - remix(&pcm, self.decoder.layout(), self.resolved_layout)? + let pcm = match &self.remix { + Some(remix) => remix.process(&pcm), + None => pcm, }; let bytes = self diff --git a/rs/moq-audio/src/decode/decoder.rs b/rs/moq-audio/src/decode/decoder.rs index 0267cd417f9..7b600582fd6 100644 --- a/rs/moq-audio/src/decode/decoder.rs +++ b/rs/moq-audio/src/decode/decoder.rs @@ -1,36 +1,25 @@ //! Audio decoder front end. //! -//! Mirror of [`encode::Encoder`](crate::encode::Encoder): dispatches over the -//! catalog codec and produces interleaved `f32` PCM. - -use unsafe_libopus::{ - OPUS_OK, OPUS_RESET_STATE, OPUS_SET_GAIN_REQUEST, OpusDecoder, opus_decode_float, opus_decoder_create, - opus_decoder_ctl_impl, opus_decoder_destroy, varargs, -}; - -#[cfg(feature = "aac")] -use symphonia_core::codecs::audio::AudioDecoder; +//! Mirror of [`encode::Encoder`](crate::encode::Encoder): opens a +//! [`Backend`](super::backend::Backend) for the catalog codec and trims its +//! startup delay, producing interleaved `f32` PCM. use super::Decoded; -#[cfg(feature = "aac")] -use crate::aac; -use crate::opus; -use crate::pcm; -use crate::{Activity, Error, Layout}; - -/// Opus packets cap at 120 ms (RFC 6716 §2.1.4). -const MAX_FRAME_MS: usize = 120; +use super::backend::{self, Backend}; +use crate::{Error, Layout}; /// Decoder backend selection. #[derive(Clone, Debug, Default, PartialEq, Eq)] #[non_exhaustive] pub enum Kind { - /// Pick the available backend automatically. + /// Prefer a platform decoder, falling back to software. #[default] Auto, - /// Require the built-in software backend. + /// Require a software backend. Software, - /// Require a backend by its stable lowercase name. + /// Require the track to be this codec, by its lowercase name: `"opus"`, + /// `"pcm"`, or `"aac"`. Any other codec is refused. The library still picks + /// the backend, platform first. Named(String), } @@ -54,187 +43,43 @@ impl Config { /// The bring-your-own-payload layer under [`Consumer`](super::Consumer): use it /// when the packets don't come from a plain track subscription. pub struct Decoder { - backend: Backend, - sample_rate: u32, - layout: Layout, + backend: Box, + /// Startup delay in native-rate frames, and how much of it is left to trim. delay: usize, -} - -enum Backend { - Opus(Opus), - Pcm { - bytes_per_frame: usize, - }, - #[cfg(feature = "aac")] - Aac(Box), -} - -struct Opus { - inner: *mut OpusDecoder, - pre_skip_remaining: usize, - max_frame_size: usize, - /// Frames per channel in the last packet that decoded, which is what a lost - /// packet most likely carried. `None` until one has. - last_frame_size: Option, - in_dtx: bool, -} - -// SAFETY: see Encoder. -unsafe impl Send for Opus {} - -/// Boxed in [`Backend`]: the symphonia decoder carries its own filterbank state, -/// which is far larger than the other backends' handles. -#[cfg(feature = "aac")] -struct Aac { - inner: symphonia_codec_aac::AacDecoder, + delay_remaining: usize, } impl Decoder { /// Build a decoder from a catalog [`AudioConfig`](hang::catalog::AudioConfig). /// /// Opus decodes at 48 kHz with the pre-skip and gain its OpusHead - /// `description` declares, refusing a malformed head or a channel mapping - /// other than mono/stereo; without a description it takes the catalog's - /// channel count and applies neither. PCM uses the catalog fields directly - /// and requires an absent `description`. + /// `description` declares, refusing a malformed head; without a description + /// it takes the catalog's channel count and applies neither. PCM uses the + /// catalog fields directly and requires an absent `description`. AAC reads + /// its AudioSpecificConfig, synthesizing one from the catalog when absent. pub fn new(catalog: &hang::catalog::AudioConfig, config: &Config) -> Result { - let name = match &catalog.codec { - hang::catalog::AudioCodec::Opus => "opus", - hang::catalog::AudioCodec::Pcm => "pcm", - #[cfg(feature = "aac")] - hang::catalog::AudioCodec::AAC(_) => "aac", - codec => return Err(Error::Unsupported(format!("unsupported audio codec: {codec}"))), - }; - match &config.kind { - Kind::Auto | Kind::Software => {} - Kind::Named(requested) if requested == name => {} - Kind::Named(requested) => { - return Err(Error::Unsupported(format!( - "audio decoder backend {requested:?} is unavailable for {name}" - ))); - } - } - match &catalog.codec { - hang::catalog::AudioCodec::Opus => Self::new_opus(catalog), - hang::catalog::AudioCodec::Pcm => Self::new_pcm(catalog), - #[cfg(feature = "aac")] - hang::catalog::AudioCodec::AAC(aac) => Self::new_aac(catalog, aac.profile), - codec => Err(Error::Unsupported(format!("unsupported audio codec: {codec}"))), - } - } - - fn new_opus(catalog: &hang::catalog::AudioConfig) -> Result { - let head = opus::head(catalog)?; - let channels = opus::validate_channels(head.channel_count)?; - - let mut err = 0i32; - // SAFETY: out-pointer is valid; inner is checked for null below. - let inner = unsafe { opus_decoder_create(opus::DECODE_RATE as i32, channels, &mut err) }; - if err != OPUS_OK || inner.is_null() { - return Err(opus::error(err, "opus_decoder_create")); - } - // Owned before the gain ctl so a failure there still destroys the decoder. - let decoder = Opus { - inner, - pre_skip_remaining: head.pre_skip as usize, - max_frame_size: (opus::DECODE_RATE as usize * MAX_FRAME_MS) / 1000, - last_frame_size: None, - in_dtx: false, - }; - - // Same Q7.8 dB units as OpusHead, and it survives OPUS_RESET_STATE. - // SAFETY: `inner` owns a live decoder and OPUS_SET_GAIN takes one i32. - let rc = - unsafe { opus_decoder_ctl_impl(decoder.inner, OPUS_SET_GAIN_REQUEST, varargs![head.output_gain as i32]) }; - if rc != OPUS_OK { - return Err(opus::error(rc, "OPUS_SET_GAIN")); - } - + let backend = backend::open(catalog, config)?; + let delay = backend.delay(); Ok(Self { - delay: decoder.pre_skip_remaining, - backend: Backend::Opus(decoder), - sample_rate: opus::DECODE_RATE, - layout: Layout::from_channels(head.channel_count)?, + backend, + delay, + delay_remaining: delay, }) } - /// AAC-LC only, which is what every gateway that feeds this crate publishes. - /// - /// HE-AAC is rejected however its config spells it: leading with SBR or PS - /// (mp4a.40.5 / .29), or leading with LC and declaring SBR in a sync extension - /// after the core. Symphonia decodes no SBR either way, so the alternative is - /// half-rate audio that sounds like a fault rather than an unsupported codec. - /// A stream that signals SBR only in band is indistinguishable from LC in the - /// config, and does decode as the core. - #[cfg(feature = "aac")] - fn new_aac(catalog: &hang::catalog::AudioConfig, profile: u8) -> Result { - use symphonia_core::codecs::audio::well_known::CODEC_ID_AAC; - use symphonia_core::codecs::audio::{AudioCodecParameters, AudioDecoderOptions}; - - let description = aac::description(catalog, profile)?; - - let mut params = AudioCodecParameters::new(); - params - .for_codec(CODEC_ID_AAC) - .with_extra_data(description.to_vec().into_boxed_slice()); - - let inner = symphonia_codec_aac::AacDecoder::try_new(¶ms, &AudioDecoderOptions::default()) - .map_err(|err| Error::Unsupported(format!("aac decoder: {err}")))?; - - // Resolved by the decoder from the config, so this is what it will emit - // even when the catalog's own fields say otherwise. - let params = inner.codec_params(); - let sample_rate = params - .sample_rate - .ok_or_else(|| Error::Unsupported("aac config declares no sample rate".into()))?; - let channel_count = params - .channels - .as_ref() - .map(|channels| channels.count()) - .ok_or_else(|| Error::Unsupported("aac config declares no channels".into()))?; - - Ok(Self { - backend: Backend::Aac(Box::new(Aac { inner })), - sample_rate, - layout: Layout::from_channels(channel_count as u32)?, - delay: 0, - }) + /// The decoder backend name in use, e.g. `"libopus"` or `"symphonia"`. + pub fn name(&self) -> &str { + self.backend.name() } - fn new_pcm(catalog: &hang::catalog::AudioConfig) -> Result { - if catalog.sample_rate == 0 { - return Err(Error::Unsupported("pcm sample rate must be greater than zero".into())); - } - if catalog.channel_count == 0 { - return Err(Error::Unsupported("pcm channel count must be greater than zero".into())); - } - if catalog.description.is_some() { - return Err(Error::Unsupported("pcm catalog description must be absent".into())); - } - let bitrate = pcm::bitrate(catalog.sample_rate, catalog.channel_count)?; - if catalog.bitrate.is_some_and(|declared| declared != bitrate) { - return Err(Error::Unsupported(format!( - "pcm catalog bitrate must be {bitrate} bits per second" - ))); - } - let bytes_per_frame = pcm::frame_bytes(1, catalog.channel_count)?; - - Ok(Self { - backend: Backend::Pcm { bytes_per_frame }, - sample_rate: catalog.sample_rate, - layout: Layout::from_channels(catalog.channel_count)?, - delay: 0, - }) - } - - /// The rate the codec decodes at, read from the catalog. + /// The rate the codec decodes at, which may differ from the catalog's. pub fn sample_rate(&self) -> u32 { - self.sample_rate + self.backend.sample_rate() } - /// The PCM layout decoded from the catalog. + /// The PCM layout the codec decodes to. pub fn layout(&self) -> Layout { - self.layout + self.backend.layout() } /// Reset codec history and reapply startup delay for a new discontinuous epoch. @@ -246,27 +91,12 @@ impl Decoder { /// Reapply catalog startup delay for a new playhead epoch without resetting codec prediction. pub(super) fn reapply_delay(&mut self) { - if let Backend::Opus(opus) = &mut self.backend { - opus.pre_skip_remaining = self.delay; - } + self.delay_remaining = self.delay; } /// Reset codec prediction after packet loss without reapplying stream startup delay. pub(super) fn reset_prediction(&mut self) -> Result<(), Error> { - match &mut self.backend { - Backend::Opus(opus) => { - // SAFETY: `inner` owns a live decoder and OPUS_RESET_STATE takes no arguments. - let rc = unsafe { opus_decoder_ctl_impl(opus.inner, OPUS_RESET_STATE, varargs![]) }; - if rc != OPUS_OK { - return Err(crate::opus::error(rc, "OPUS_RESET_STATE")); - } - opus.in_dtx = false; - } - Backend::Pcm { .. } => {} - #[cfg(feature = "aac")] - Backend::Aac(aac) => aac.inner.reset(), - } - Ok(()) + self.backend.reset() } /// How much startup delay is still to be trimmed, in native-rate frames. @@ -275,12 +105,7 @@ impl Decoder { /// it, so a caller tracking where a packet ends has to add back whatever this /// dropped across the call. pub(super) fn delay_remaining(&self) -> usize { - match &self.backend { - Backend::Opus(opus) => opus.pre_skip_remaining, - Backend::Pcm { .. } => 0, - #[cfg(feature = "aac")] - Backend::Aac(_) => 0, - } + self.delay_remaining } /// Decode one packet into interleaved `f32` PCM and report its codec activity. @@ -291,101 +116,14 @@ impl Decoder { /// no length to conceal. Loss during DTX remains classified as DTX, while loss /// during active audio remains active. pub fn decode(&mut self, packet: &[u8]) -> Result { - match &mut self.backend { - Backend::Opus(opus) => { - let channels = self.layout.channels() as usize; - // libopus conceals exactly `frame_size` samples for a lost packet, and - // the decoder can't know how long it was, so assume the last one's length. - // A real packet decodes into the most it can hold. - let frame_size = if packet.is_empty() { - opus.last_frame_size.ok_or_else(|| { - Error::Decode("opus packet lost before any packet decoded, so no length to conceal".into()) - })? - } else { - opus.max_frame_size - }; - let mut out = vec![0.0f32; frame_size * channels]; - // SAFETY: `inner` owns a live OpusDecoder; packet/out slices are - // bounded by the lengths we pass. - let samples = unsafe { - opus_decode_float( - &mut *opus.inner, - packet.as_ptr(), - packet.len() as i32, - out.as_mut_ptr(), - frame_size as i32, - 0, - ) - }; - if samples < 0 { - return Err(crate::opus::decode_error(samples)); - } - if !packet.is_empty() { - opus.last_frame_size = Some(samples as usize); - } - out.truncate(samples as usize * channels); - let trim_frames = opus.pre_skip_remaining.min(samples as usize); - if trim_frames > 0 { - let trim_samples = trim_frames * channels; - out.copy_within(trim_samples.., 0); - out.truncate(out.len() - trim_samples); - opus.pre_skip_remaining -= trim_frames; - } - let activity = crate::opus::activity(packet, opus.in_dtx); - opus.in_dtx = activity.is_dtx(); - Ok(Decoded { samples: out, activity }) - } - Backend::Pcm { bytes_per_frame } => { - if packet.is_empty() || !packet.len().is_multiple_of(*bytes_per_frame) { - return Err(Error::Misaligned { - got: packet.len(), - expected: packet.len().max(1).next_multiple_of(*bytes_per_frame), - }); - } - - let out = packet - .as_chunks::<{ pcm::BYTES_PER_SAMPLE }>() - .0 - .iter() - .map(|sample| f32::from_le_bytes([sample[0], sample[1], sample[2], sample[3]])) - .collect(); - Ok(Decoded { - samples: out, - activity: Activity::Active, - }) - } - #[cfg(feature = "aac")] - Backend::Aac(aac) => { - // The packet is a raw AAC frame, not ADTS, so there is nothing to - // timestamp it with here: the container carries the timestamp and the - // decoder only reads the payload. - let packet = symphonia_core::packet::PacketRef::new( - 0, - symphonia_core::units::Timestamp::ZERO, - symphonia_core::units::Duration::ZERO, - packet, - ); - - let decoded = aac - .inner - .decode_ref(&packet) - .map_err(|err| Error::Decode(format!("aac: {err}")))?; - - let mut out = Vec::new(); - decoded.copy_to_vec_interleaved(&mut out); - Ok(Decoded { - samples: out, - activity: Activity::Active, - }) - } + let mut decoded = self.backend.decode(packet)?; + let channels = self.backend.layout().channels() as usize; + let trim = self.delay_remaining.min(decoded.samples.len() / channels); + if trim > 0 { + decoded.samples.drain(..trim * channels); + self.delay_remaining -= trim; } - } -} - -impl Drop for Opus { - fn drop(&mut self) { - // SAFETY: `inner` is a live OpusDecoder that nothing else aliases. - unsafe { opus_decoder_destroy(self.inner) }; + Ok(decoded) } } @@ -420,10 +158,18 @@ pub(crate) mod tests { catalog } + /// The published `Decoder` was unwind safe before it boxed a backend; keep it so. + #[test] + fn decoder_is_unwind_safe() { + fn assert_unwind_safe() {} + assert_unwind_safe::(); + } + #[cfg(feature = "aac")] #[test] fn aac_decodes_a_sine() { let mut decoder = Decoder::new(&aac_catalog(), &Config::default()).unwrap(); + assert_eq!(decoder.name(), "symphonia"); assert_eq!(decoder.sample_rate(), 44_100); assert_eq!(decoder.layout(), Layout::Mono); @@ -607,26 +353,6 @@ pub(crate) mod tests { } } - /// Mapping families other than 0 need the multistream decoder; a stereo - /// family 1 head is refused rather than decoded as family 0. - #[test] - fn opus_refuses_unsupported_channel_mappings() { - let valid = moq_mux::codec::opus::Config::new(48_000, 2).encode().unwrap().to_vec(); - for family in [1, 255] { - let mut description = valid.clone(); - description[18] = family; - // One coupled stream, left then right. - description.extend_from_slice(&[1, 1, 0, 1]); - - let mut catalog = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Opus, 48_000, 2); - catalog.description = Some(description.into()); - assert!( - matches!(Decoder::new(&catalog, &Config::default()), Err(Error::Unsupported(_))), - "family {family}" - ); - } - } - /// Without a description the catalog shapes the stream, which has no pre-skip. #[test] fn opus_decodes_without_a_description() { @@ -679,6 +405,24 @@ pub(crate) mod tests { )); } + /// Published moq-audio accepts the codec's name, not a backend's. + #[cfg(feature = "aac")] + #[test] + fn named_aac_decodes_aac() { + let config = Config { + kind: Kind::Named("aac".into()), + }; + assert!(Decoder::new(&aac_catalog(), &config).is_ok()); + + let config = Config { + kind: Kind::Named("opus".into()), + }; + assert!(matches!( + Decoder::new(&aac_catalog(), &config), + Err(Error::Unsupported(_)) + )); + } + #[test] fn refuses_unavailable_backend() { let catalog = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Pcm, 48_000, 2); diff --git a/rs/moq-audio/src/decode/mod.rs b/rs/moq-audio/src/decode/mod.rs index 7e3cbd14a71..6f4500054c4 100644 --- a/rs/moq-audio/src/decode/mod.rs +++ b/rs/moq-audio/src/decode/mod.rs @@ -10,8 +10,11 @@ //! [`Decoded`] interleaved `f32` samples. //! //! [`Options`] keeps subscription and output policy separate from the -//! lower-level decoder [`Config`]. +//! lower-level decoder [`Config`], whose [`Kind`] picks the backend: a +//! platform decoder first where one takes the track, then software (libopus, +//! PCM, and symphonia for AAC-LC). +mod backend; mod consumer; mod decoded; mod decoder; diff --git a/rs/moq-audio/src/encode/backend/libopus.rs b/rs/moq-audio/src/encode/backend/libopus.rs new file mode 100644 index 00000000000..118c701be46 --- /dev/null +++ b/rs/moq-audio/src/encode/backend/libopus.rs @@ -0,0 +1,207 @@ +//! Opus through libopus 1.3.1, via [`unsafe_libopus`]. + +use bytes::Bytes; +use unsafe_libopus::{ + OPUS_APPLICATION_AUDIO, OPUS_GET_BITRATE_REQUEST, OPUS_GET_LOOKAHEAD_REQUEST, OPUS_OK, OPUS_RESET_STATE, + OPUS_SET_BITRATE_REQUEST, OPUS_SET_DTX_REQUEST, OpusEncoder, opus_encode_float, opus_encoder_create, + opus_encoder_ctl_impl, opus_encoder_destroy, varargs, +}; + +use super::Backend; +use crate::encode::{Encoded, Settings}; +use crate::{Error, opus}; + +pub(super) const NAME: &str = "libopus"; + +/// libopus packet size ceiling per RFC 6716 §3.4. +const MAX_PACKET_BYTES: usize = 4_000; + +pub(super) struct Libopus { + inner: *mut OpusEncoder, + scratch: Vec, + sample_rate: u32, + channels: u32, + frame_size: usize, + bitrate: u64, + lookahead: usize, +} + +// SAFETY: OpusEncoder is heap-allocated state owned exclusively by this +// struct; libopus encoder methods take a single &mut, so a unique owner is +// allowed to move it across threads. +unsafe impl Send for Libopus {} + +impl Libopus { + /// Opens at the settings' rate and layout, which the front end has already + /// checked against what Opus codes. + pub(super) fn open(settings: &Settings) -> Result, Error> { + Ok(Box::new(Self::new(settings)?)) + } + + fn new(settings: &Settings) -> Result { + let sample_rate = settings.sample_rate; + let channels = settings.layout.channels(); + let frame_size = opus::frame_size(sample_rate, settings.frame_duration)?; + + let mut err = 0i32; + // SAFETY: out-pointer `err` is valid; inner is checked for null below. + let inner = unsafe { + opus_encoder_create( + sample_rate as i32, + opus::validate_channels(channels)?, + OPUS_APPLICATION_AUDIO, + &mut err, + ) + }; + if err != OPUS_OK || inner.is_null() { + return Err(opus::error(err, "opus_encoder_create")); + } + + // Owned from here, so an early return below destroys it. + let mut backend = Self { + inner, + scratch: vec![0u8; MAX_PACKET_BYTES], + sample_rate, + channels, + frame_size, + bitrate: 0, + lookahead: 0, + }; + + if let Some(bitrate) = settings.bitrate { + backend.set_rate(bitrate.as_bps())?; + } + backend.set_ctl(OPUS_SET_DTX_REQUEST, i32::from(settings.dtx), "OPUS_SET_DTX")?; + + let bitrate = backend.get_ctl(OPUS_GET_BITRATE_REQUEST, "OPUS_GET_BITRATE")?; + backend.bitrate = u64::try_from(bitrate) + .map_err(|_| Error::Unsupported(format!("Opus reported negative bitrate {bitrate}")))?; + let lookahead = backend.get_ctl(OPUS_GET_LOOKAHEAD_REQUEST, "OPUS_GET_LOOKAHEAD")?; + backend.lookahead = usize::try_from(lookahead) + .map_err(|_| Error::Unsupported(format!("Opus reported negative lookahead {lookahead}")))?; + + Ok(backend) + } + + /// Refuse rates libopus would silently clamp, then apply the rest. + fn set_rate(&mut self, bitrate: u64) -> Result<(), Error> { + let (channels, frame_size) = (self.channels, self.frame_size); + let max = 300_000 * channels as u64; + let min = opus::bitrate_floor(self.sample_rate, frame_size).max(500); + if !(min..=max).contains(&bitrate) { + return Err(Error::Unsupported(format!( + "Opus bitrate must be between {min} and {max} bits per second for {channels} channel(s) at {frame_size} samples, got {bitrate}" + ))); + } + self.set_ctl(OPUS_SET_BITRATE_REQUEST, bitrate as i32, "OPUS_SET_BITRATE") + } + + fn set_ctl(&mut self, request: i32, value: i32, name: &'static str) -> Result<(), Error> { + // SAFETY: `inner` owns a live encoder and each request here expects one i32. + let rc = unsafe { opus_encoder_ctl_impl(self.inner, request, varargs![value]) }; + if rc != OPUS_OK { + return Err(opus::error(rc, name)); + } + Ok(()) + } + + fn get_ctl(&self, request: i32, name: &'static str) -> Result { + let mut value = 0; + // SAFETY: `inner` owns a live encoder and each request here expects one + // valid mutable i32 output. + let rc = unsafe { opus_encoder_ctl_impl(self.inner, request, varargs![&mut value]) }; + if rc != OPUS_OK { + return Err(opus::error(rc, name)); + } + Ok(value) + } +} + +impl Backend for Libopus { + fn encode(&mut self, pcm: &[f32]) -> Result { + // SAFETY: `inner` owns a live OpusEncoder; pcm and scratch slices are + // bounded by the lengths we pass, and the front end sized `pcm` to one frame. + let n = unsafe { + opus_encode_float( + self.inner, + pcm.as_ptr(), + self.frame_size as i32, + self.scratch.as_mut_ptr(), + self.scratch.len() as i32, + ) + }; + if n < 0 { + return Err(opus::error(n, "opus_encode_float")); + } + let payload = Bytes::copy_from_slice(&self.scratch[..n as usize]); + let activity = opus::activity(&payload, false); + Ok(Encoded { payload, activity }) + } + + fn reset(&mut self) { + // SAFETY: `inner` owns a live encoder and OPUS_RESET_STATE takes no arguments. + let rc = unsafe { opus_encoder_ctl_impl(self.inner, OPUS_RESET_STATE, varargs![]) }; + debug_assert_eq!(rc, OPUS_OK, "OPUS_RESET_STATE failed with {rc}"); + } + + fn set_bitrate(&mut self, bitrate: u64) -> Result<(), Error> { + if bitrate != self.bitrate { + self.set_rate(bitrate)?; + self.bitrate = bitrate; + } + Ok(()) + } + + fn bitrate(&self) -> u64 { + self.bitrate + } + + fn delay(&self) -> usize { + self.lookahead + } + + fn name(&self) -> &str { + NAME + } +} + +impl Drop for Libopus { + fn drop(&mut self) { + // SAFETY: `inner` is a live OpusEncoder that nothing else aliases. + unsafe { opus_encoder_destroy(self.inner) }; + } +} + +#[cfg(test)] +mod tests { + use unsafe_libopus::OPUS_GET_DTX_REQUEST; + + use super::*; + + #[test] + fn runtime_bitrate_reaches_libopus() { + let mut backend = Libopus::new(&Settings { + bitrate: Some(moq_net::bandwidth::Rate::from_bps(64_000)), + ..Settings::default() + }) + .unwrap(); + + backend.set_bitrate(32_000).unwrap(); + assert_eq!(backend.bitrate(), 32_000); + assert_eq!( + backend.get_ctl(OPUS_GET_BITRATE_REQUEST, "OPUS_GET_BITRATE").unwrap(), + 32_000 + ); + } + + #[test] + fn applies_dtx_control() { + let backend = Libopus::new(&Settings { + dtx: true, + ..Settings::default() + }) + .unwrap(); + + assert_eq!(backend.get_ctl(OPUS_GET_DTX_REQUEST, "OPUS_GET_DTX").unwrap(), 1); + } +} diff --git a/rs/moq-audio/src/encode/backend/mod.rs b/rs/moq-audio/src/encode/backend/mod.rs new file mode 100644 index 00000000000..97f4dbdc025 --- /dev/null +++ b/rs/moq-audio/src/encode/backend/mod.rs @@ -0,0 +1,336 @@ +//! Pluggable audio encoder backends. +//! +//! The mirror of the decode backends. [`Backend`] is the seam between the codec +//! and the [`Encoder`](super::Encoder) front end, which owns what every backend +//! of a codec shares: validating [`Settings`](super::Settings) against the +//! codec, framing the input, draining the startup delay at the end, and the +//! catalog entry, whose description is synthesized from the settings rather than +//! read back from the backend. +//! +//! [`open`] tries the platform encoders before the software ones, skipping any +//! that does not emit the codec, and refuses when none opens. [`Kind::Named`] +//! names the codec, not a backend, so which backend encodes it stays the +//! library's choice. The software tier +//! is libopus for Opus and a passthrough for PCM. AAC has no software encoder, +//! so it is only as available as the platform's, and no platform encoder is +//! wired in yet. + +use super::Encoded; +use super::encoder::{Codec, Kind, Settings}; +use crate::Error; + +mod libopus; +mod pcm; + +#[cfg(test)] +pub(crate) mod stub; + +/// An opened encoder: one frame of interleaved `f32` PCM in, one packet out. +/// +/// Input arrives at the settings' rate, in the crate's canonical channel order +/// for the settings' layout; a codec with another native order reorders it here. +/// +/// One packet per frame is part of the contract: the producer stamps packets by +/// counting frames. A codec that pipelines output (MediaCodec) needs a `flush` +/// and a zero-or-more return, which changes `Encoder::encode` too, so that lands +/// with the first backend that needs it rather than as an always-empty method. +/// +/// Unwind safe because the published `Encoder` that boxes it is. +pub(crate) trait Backend: Send + std::panic::UnwindSafe + std::panic::RefUnwindSafe { + /// Encode exactly one frame of the codec's frame size. + fn encode(&mut self, pcm: &[f32]) -> Result; + + /// Drop codec history so the next frame codes as if it were the first. + fn reset(&mut self); + + /// Retune the live encoder to `bitrate` bits per second, a no-op at the current + /// rate. + /// + /// No default: a backend that can't change rate mid-stream refuses with + /// [`Error::Unsupported`] and keeps its opening rate, rather than inheriting a + /// silent no-op that ignores congestion. + fn set_bitrate(&mut self, bitrate: u64) -> Result<(), Error>; + + /// The current target bitrate in bits per second, as the codec resolved it. + fn bitrate(&self) -> u64; + + /// Frames of codec priming at the start of the decoded stream, at the codec + /// rate: Opus lookahead, AAC encoder delay. + fn delay(&self) -> usize; + + /// The stable lowercase name of this backend, as [`Encoder::name`](super::Encoder::name) + /// reports it. Callers never select by it. + fn name(&self) -> &str; +} + +/// A backend constructor: its name, the codecs it emits, and an opener. +struct Candidate { + name: &'static str, + codecs: &'static [Codec], + open: fn(&Settings) -> Result, Error>, +} + +/// Operating-system encoders, in priority order. +const PLATFORM: &[Candidate] = &[]; + +const SOFTWARE: &[Candidate] = &[ + Candidate { + name: libopus::NAME, + codecs: &[Codec::Opus], + open: libopus::Libopus::open, + }, + Candidate { + name: pcm::NAME, + codecs: &[Codec::Pcm], + open: pcm::Pcm::open, + }, +]; + +/// The platform tier on a test thread that called [`stub::install`], so AAC tests +/// open the same backend on every host and every other test sees the real tiers. +#[cfg(test)] +const STUB_PLATFORM: &[Candidate] = &[Candidate { + name: stub::NAME, + codecs: &[Codec::Aac], + open: stub::Stub::open, +}]; + +/// Open the first backend that emits the codec and accepts the settings. +pub(crate) fn open(settings: &Settings) -> Result, Error> { + if let Kind::Named(requested) = &settings.kind + && requested != settings.codec.as_str() + { + return Err(Error::Unsupported(format!( + "audio encoder {requested:?} is unavailable for {}", + settings.codec + ))); + } + + #[cfg(test)] + let platform = match stub::installed() { + true => STUB_PLATFORM, + false => PLATFORM, + }; + #[cfg(not(test))] + let platform = PLATFORM; + + select(settings, candidates(&settings.kind, platform, SOFTWARE)) +} + +/// The candidates `kind` allows, in the order to try them. +/// +/// Takes the tiers as arguments so a test can supply stubs instead of whatever +/// this host compiles in. +fn candidates<'a>(kind: &Kind, platform: &'a [Candidate], software: &'a [Candidate]) -> Vec<&'a Candidate> { + match kind { + Kind::Software => software.iter().collect(), + // `open` has already checked that a name matches the codec. + Kind::Auto | Kind::Named(_) => platform.iter().chain(software).collect(), + } +} + +fn select(settings: &Settings, candidates: Vec<&Candidate>) -> Result, Error> { + let codec = settings.codec; + let mut refused = Vec::new(); + + for candidate in candidates { + if !candidate.codecs.contains(&codec) { + continue; + } + match (candidate.open)(settings) { + Ok(backend) => return Ok(backend), + Err(err) => refused.push((candidate.name, err)), + } + } + + // One refusal is the whole answer, so keep its variant. + if refused.len() == 1 { + let (_, err) = refused.remove(0); + return Err(err); + } + if !refused.is_empty() { + let reasons: Vec = refused.iter().map(|(name, err)| format!("{name}: {err}")).collect(); + return Err(Error::Unsupported(reasons.join(", "))); + } + + let available: Vec<&str> = PLATFORM + .iter() + .chain(SOFTWARE) + .filter(|c| c.codecs.contains(&codec)) + .map(|c| c.name) + .collect(); + let available = match available.is_empty() { + true => "none".to_owned(), + false => available.join(", "), + }; + Err(Error::Unsupported(match &settings.kind { + Kind::Software => format!("no software {codec} audio encoder (this build has: {available})"), + Kind::Auto | Kind::Named(_) => format!("no {codec} audio encoder (this build has: {available})"), + })) +} + +#[cfg(test)] +mod tests { + use super::*; + + /// Opens anything it advertises and reports which candidate it came from. + struct Fake(&'static str); + + impl Backend for Fake { + fn encode(&mut self, _pcm: &[f32]) -> Result { + Ok(Encoded::new(bytes::Bytes::new())) + } + + fn reset(&mut self) {} + + fn set_bitrate(&mut self, _bitrate: u64) -> Result<(), Error> { + Ok(()) + } + + fn bitrate(&self) -> u64 { + 0 + } + + fn delay(&self) -> usize { + 0 + } + + fn name(&self) -> &str { + self.0 + } + } + + const PLATFORM_STUB: Candidate = Candidate { + name: "platform", + codecs: &[Codec::Aac], + open: |_| Ok(Box::new(Fake("platform"))), + }; + + /// Compiled in but refusing the settings, like a platform encoder asked for a + /// layout its framework does not open. + const REFUSING: Candidate = Candidate { + name: "refusing", + codecs: &[Codec::Aac], + open: |_| Err(Error::Unsupported("not these settings".into())), + }; + + const SOFTWARE_STUB: Candidate = Candidate { + name: "software", + codecs: &[Codec::Aac], + open: |_| Ok(Box::new(Fake("software"))), + }; + + /// Emits nothing but PCM, so an AAC request never reaches its opener. + const PCM_ONLY: Candidate = Candidate { + name: "pcm-only", + codecs: &[Codec::Pcm], + open: |_| panic!("opened for a codec it does not emit"), + }; + + fn aac(kind: Kind) -> Settings { + Settings { + kind, + ..Settings::from_input(Codec::Aac, &Default::default()) + } + } + + fn pick(kind: Kind, platform: &[Candidate], software: &[Candidate]) -> Result { + let settings = aac(kind); + let backend = select(&settings, candidates(&settings.kind, platform, software))?; + Ok(backend.name().to_owned()) + } + + #[test] + fn auto_prefers_platform() { + let name = pick(Kind::Auto, &[PCM_ONLY, PLATFORM_STUB], &[SOFTWARE_STUB]).unwrap(); + assert_eq!(name, "platform"); + } + + #[test] + fn auto_falls_back_to_software() { + let name = pick(Kind::Auto, &[REFUSING], &[SOFTWARE_STUB]).unwrap(); + assert_eq!(name, "software"); + } + + #[test] + fn software_skips_platform() { + let name = pick(Kind::Software, &[PLATFORM_STUB], &[SOFTWARE_STUB]).unwrap(); + assert_eq!(name, "software"); + } + + /// A codec name is not a backend selector: it tries the same tiers as `Auto`. + #[test] + fn named_codec_picks_like_auto() { + let name = pick(Kind::Named("aac".into()), &[PLATFORM_STUB], &[SOFTWARE_STUB]).unwrap(); + assert_eq!(name, "platform"); + } + + #[test] + fn every_refusal_is_reported() { + const ALSO_REFUSING: Candidate = Candidate { + name: "also-refusing", + ..REFUSING + }; + + let err = pick(Kind::Auto, &[REFUSING], &[ALSO_REFUSING]).unwrap_err(); + let message = err.to_string(); + assert!( + message.contains("refusing: ") && message.contains("also-refusing: "), + "{message}" + ); + } + + /// No AAC encoder is wired in outside the test stub, so `Auto` refuses at + /// construction and says there is nothing to fall back to. A platform backend + /// gates this to the hosts without one. + #[test] + fn aac_without_a_platform_encoder_is_refused() { + let err = open(&aac(Kind::Auto)).err().expect("no AAC encoder on this host"); + let message = err.to_string(); + assert!(message.contains("aac") && message.contains("none"), "{message}"); + } + + /// The stub stands in for the platform tier only, so `Software` still refuses + /// AAC with it installed. + #[test] + fn stub_is_not_software() { + let _stub = stub::install(); + assert_eq!(open(&aac(Kind::Auto)).unwrap().name(), stub::NAME); + + let err = open(&aac(Kind::Software)).err().expect("no software AAC encoder"); + assert!(err.to_string().contains("no software aac"), "{err}"); + } + + fn named(codec: Codec, name: &str) -> Settings { + Settings { + codec, + kind: Kind::Named(name.into()), + ..Settings::default() + } + } + + /// A codec's own name opens that codec, like `Auto`. + #[test] + fn codec_names_open_their_codec() { + let _stub = stub::install(); + assert_eq!(open(&named(Codec::Opus, "opus")).unwrap().name(), libopus::NAME); + assert_eq!(open(&named(Codec::Pcm, "pcm")).unwrap().name(), pcm::NAME); + assert_eq!(open(&named(Codec::Aac, "aac")).unwrap().name(), stub::NAME); + } + + /// A name for another codec is refused, not quietly swapped for the settings' codec. + #[test] + fn another_codecs_name_is_refused() { + assert!(matches!(open(&named(Codec::Opus, "pcm")), Err(Error::Unsupported(_)))); + } + + /// Backend names are internal: asking for one is refused like any unknown name. + #[test] + fn backend_names_are_refused() { + let message = open(&named(Codec::Opus, libopus::NAME)) + .err() + .expect("libopus is a backend, not a codec") + .to_string(); + assert!(message.contains("\"libopus\"") && message.contains("opus"), "{message}"); + } +} diff --git a/rs/moq-audio/src/encode/backend/pcm.rs b/rs/moq-audio/src/encode/backend/pcm.rs new file mode 100644 index 00000000000..62a2382a536 --- /dev/null +++ b/rs/moq-audio/src/encode/backend/pcm.rs @@ -0,0 +1,55 @@ +//! Uncompressed little-endian `f32` PCM, which needs no codec at all. + +use super::Backend; +use crate::encode::{Encoded, Settings}; +use crate::{Error, Layout, pcm}; + +pub(super) const NAME: &str = "pcm"; + +pub(super) struct Pcm { + bitrate: u64, +} + +impl Pcm { + /// The catalog carries only a channel count, so a named layout that count + /// would decode as another one is refused rather than relabeled. + pub(super) fn open(settings: &Settings) -> Result, Error> { + let layout = settings.layout; + if !matches!(layout, Layout::Discrete(_)) && Layout::from_channels(layout.channels())? != layout { + return Err(Error::Unsupported(format!( + "pcm carries only a channel count, which decodes as {:?}, not {layout:?}", + Layout::from_channels(layout.channels())? + ))); + } + let bitrate = pcm::bitrate(settings.sample_rate, settings.layout.channels())?; + Ok(Box::new(Self { bitrate })) + } +} + +impl Backend for Pcm { + fn encode(&mut self, pcm: &[f32]) -> Result { + let mut payload = Vec::with_capacity(std::mem::size_of_val(pcm)); + for sample in pcm { + payload.extend_from_slice(&sample.to_le_bytes()); + } + Ok(Encoded::new(payload.into())) + } + + fn reset(&mut self) {} + + fn set_bitrate(&mut self, _bitrate: u64) -> Result<(), Error> { + Err(Error::Unsupported("pcm bitrate is fixed".into())) + } + + fn bitrate(&self) -> u64 { + self.bitrate + } + + fn delay(&self) -> usize { + 0 + } + + fn name(&self) -> &str { + NAME + } +} diff --git a/rs/moq-audio/src/encode/backend/stub.rs b/rs/moq-audio/src/encode/backend/stub.rs new file mode 100644 index 00000000000..a64cf664689 --- /dev/null +++ b/rs/moq-audio/src/encode/backend/stub.rs @@ -0,0 +1,86 @@ +//! A stand-in AAC encoder, so the AAC front end is testable on a host with no +//! platform encoder. A test opts in with [`install`]; every other test sees the +//! real tiers. + +use std::cell::Cell; + +use bytes::Bytes; + +use super::Backend; +use crate::Error; +use crate::encode::{Encoded, Settings}; + +pub(crate) const NAME: &str = "stub"; + +/// The AudioToolbox AAC-LC encoder delay, which is what a real backend reports. +pub(crate) const DELAY: usize = 2112; + +thread_local! { + static INSTALLED: Cell = const { Cell::new(false) }; +} + +/// Stand the stub in for the platform tier on this thread until the guard drops. +pub(crate) fn install() -> Installed { + INSTALLED.set(true); + Installed(()) +} + +/// Whether this thread has the stub installed. +pub(super) fn installed() -> bool { + INSTALLED.get() +} + +/// Uninstalls the stub on drop. +pub(crate) struct Installed(()); + +impl Drop for Installed { + fn drop(&mut self) { + INSTALLED.set(false); + } +} + +/// Emits each frame's index as its payload, and cannot retune. +pub(crate) struct Stub { + bitrate: u64, + frames: u64, +} + +impl Stub { + pub(super) fn open(settings: &Settings) -> Result, Error> { + Ok(Box::new(Self { + bitrate: settings.bitrate.map_or(128_000, |rate| rate.as_bps()), + frames: 0, + })) + } +} + +impl Backend for Stub { + fn encode(&mut self, _pcm: &[f32]) -> Result { + let payload = Bytes::copy_from_slice(&self.frames.to_be_bytes()); + self.frames += 1; + Ok(Encoded::new(payload)) + } + + fn reset(&mut self) { + self.frames = 0; + } + + fn set_bitrate(&mut self, bitrate: u64) -> Result<(), Error> { + match bitrate == self.bitrate { + true => Ok(()), + false => Err(Error::Unsupported("the stub cannot change rate mid-stream".into())), + } + } + + fn bitrate(&self) -> u64 { + self.bitrate + } + + fn delay(&self) -> usize { + DELAY + } + + fn name(&self) -> &str { + NAME + } +} diff --git a/rs/moq-audio/src/encode/capture.rs b/rs/moq-audio/src/encode/capture.rs index 33fc3f428fa..580ad4e1b02 100644 --- a/rs/moq-audio/src/encode/capture.rs +++ b/rs/moq-audio/src/encode/capture.rs @@ -12,7 +12,7 @@ use moq_mux::catalog::hang::CatalogExt; use super::producer::Reserved; use super::{Input, Options, Producer}; use crate::capture; -use crate::resample::{Resampler, remix, validate_remix}; +use crate::resample::{Remix, Resampler}; use crate::{Error, Format, Frame, Layout as PcmLayout}; /// Backoff bounds for reopening a capture source. The quick first retry covers @@ -445,7 +445,7 @@ impl Driver { None => continue, }, }; - let pcm_layout = match PcmLayout::from_channels(layout.channels) { + let pcm_layout = match device_layout(layout.channels) { Ok(layout) => layout, Err(err) => match self.failed(err, track, desired.revision).await { Some(result) => return Some(result), @@ -891,23 +891,29 @@ impl EncoderOutput<'_, E> { } } +/// The layout of a capture device, which reports only a channel count. That names +/// speakers for mono and stereo alone: a six-channel microphone array is not a +/// 5.1 speaker layout, so it stays discrete rather than being remixed as one. +fn device_layout(channels: u32) -> Result { + match channels { + 0..=2 => PcmLayout::from_channels(channels), + channels => Ok(PcmLayout::Discrete(channels)), + } +} + /// Converts one opened stream's native layout into the producer's fixed input /// layout. A new instance per open keeps filter state out of recovery gaps. struct Converter { - input: capture::Layout, - output: capture::Layout, + remix: Option, resampler: Option, anchor_us: Option, } impl Converter { fn new(input: capture::Layout, output: capture::Layout) -> Result { - if input.channels != output.channels { - validate_remix( - PcmLayout::from_channels(input.channels)?, - PcmLayout::from_channels(output.channels)?, - )?; - } + let remix = (input.channels != output.channels) + .then(|| Remix::new(device_layout(input.channels)?, device_layout(output.channels)?)) + .transpose()?; let resampler = if input.sample_rate == output.sample_rate { None @@ -924,8 +930,7 @@ impl Converter { }; Ok(Self { - input, - output, + remix, resampler, anchor_us: None, }) @@ -956,10 +961,8 @@ impl Converter { let data = resampler.process(&samples.data, moq_net::Timestamp::from_micros(timestamp_us)?)?; samples.replace(data); } - if self.input.channels != self.output.channels { - let input = PcmLayout::from_channels(self.input.channels)?; - let output = PcmLayout::from_channels(self.output.channels)?; - let data = remix(&samples.data, input, output)?; + if let Some(remix) = &self.remix { + let data = remix.process(&samples.data); samples.replace(data); } if samples.data.is_empty() { diff --git a/rs/moq-audio/src/encode/encoder.rs b/rs/moq-audio/src/encode/encoder.rs index ca2045a6333..5ba2e3b0747 100644 --- a/rs/moq-audio/src/encode/encoder.rs +++ b/rs/moq-audio/src/encode/encoder.rs @@ -1,26 +1,29 @@ //! Audio encoder front end. //! -//! [`Encoder`] dispatches over the closed [`Codec`] set. Opus wraps libopus -//! 1.3.1 via [`unsafe_libopus`], while PCM serializes interleaved `f32` samples -//! directly. +//! [`Encoder`] checks [`Settings`] against the codec, opens a +//! [`Backend`](super::backend::Backend) for it, and owns what every backend of a +//! codec shares: framing, the terminal drain, and the catalog entry. use std::str::FromStr; use std::time::Duration; use bytes::Bytes; -use unsafe_libopus::{ - OPUS_APPLICATION_AUDIO, OPUS_GET_BITRATE_REQUEST, OPUS_GET_LOOKAHEAD_REQUEST, OPUS_OK, OPUS_RESET_STATE, - OPUS_SET_BITRATE_REQUEST, OPUS_SET_DTX_REQUEST, OpusEncoder, opus_encode_float, opus_encoder_create, - opus_encoder_ctl_impl, opus_encoder_destroy, varargs, -}; use super::Encoded; +use super::backend::{self, Backend}; use crate::opus; use crate::pcm; use crate::{Error, Format, Layout}; -/// libopus packet size ceiling per RFC 6716 §3.4. -const MAX_PACKET_BYTES: usize = 4_000; +/// Samples per channel in one AAC-LC frame. +const AAC_FRAME_SIZE: usize = 1024; + +/// The audioObjectType of AAC-LC (ISO 14496-3 Table 1.17), `mp4a.40.2`. +const AAC_LC: u8 = 2; + +/// The widest sample rate an AudioSpecificConfig can name: the escape from the +/// frequency table is a 24-bit field. +const AAC_MAX_SAMPLE_RATE: u32 = 0xFF_FFFF; /// Output audio codec. `#[non_exhaustive]` so new codecs can be added without /// breaking external `match`es. @@ -32,6 +35,9 @@ pub enum Codec { Opus, /// Uncompressed interleaved little-endian IEEE-754 binary32 PCM. Pcm, + /// AAC-LC (`mp4a.40.2`), through the platform's encoder. A host without one + /// refuses it at construction. + Aac, } impl Codec { @@ -41,6 +47,7 @@ impl Codec { match self { Self::Opus => "opus", Self::Pcm => "pcm", + Self::Aac => "aac", } } } @@ -58,11 +65,27 @@ impl FromStr for Codec { match s { "opus" => Ok(Self::Opus), "pcm" => Ok(Self::Pcm), + "aac" => Ok(Self::Aac), other => Err(Error::Unsupported(format!("unknown codec: {other}"))), } } } +/// Encoder backend selection. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +#[non_exhaustive] +pub enum Kind { + /// Prefer a platform encoder, falling back to software. + #[default] + Auto, + /// Require a software backend. + Software, + /// Require [`Settings::codec`] to be this codec, by its lowercase name: + /// `"opus"`, `"pcm"`, or `"aac"`. Any other codec is refused. The library + /// still picks the backend, platform first. + Named(String), +} + /// PCM supplied to [`Producer::write`](super::Producer::write). #[derive(Clone, Debug)] #[non_exhaustive] @@ -101,9 +124,12 @@ pub struct Settings { /// Sample rate accepted by the codec. pub sample_rate: u32, /// Layout accepted by the codec. + /// + /// AAC takes the layouts its channelConfiguration names: mono, stereo, 3.0, + /// 4.0, 5.0, 5.1, and 7.1. pub layout: Layout, - /// Bitrate in bits per second. `None` lets Opus pick. PCM requires `None` - /// because its bitrate is fixed by the sample rate and channel count. + /// Bitrate in bits per second. `None` lets the codec pick. PCM requires + /// `None` because its bitrate is fixed by the sample rate and channel count. /// /// Rates too low for Opus to code anything at the chosen /// [`frame_duration`](Self::frame_duration) are rejected. The floor is 1200 @@ -113,8 +139,13 @@ pub struct Settings { /// Enable Opus discontinuous transmission during silence. pub dtx: bool, /// Encoded frame duration. Opus accepts 2.5 / 5 / 10 / 20 / 40 / 60 ms. - /// PCM accepts any duration containing a whole number of samples. + /// PCM accepts any duration containing a whole number of samples. AAC frames + /// are 1024 samples, so it accepts the duration that rounds to that at + /// [`sample_rate`](Self::sample_rate), which [`from_input`](Self::from_input) + /// fills in. pub frame_duration: Duration, + /// Which encoder implementation to use. + pub kind: Kind, } impl Settings { @@ -127,6 +158,7 @@ impl Settings { bitrate: None, dtx: false, frame_duration: Duration::from_millis(20), + kind: Kind::Auto, } } @@ -134,13 +166,72 @@ impl Settings { pub fn from_input(codec: Codec, input: &Input) -> Self { let sample_rate = match codec { Codec::Opus => opus::pick_rate(input.sample_rate), - Codec::Pcm => input.sample_rate, + Codec::Pcm | Codec::Aac => input.sample_rate, + }; + let defaults = Self::new(sample_rate, input.layout); + let frame_duration = match codec { + Codec::Aac => aac_frame_duration(sample_rate), + Codec::Opus | Codec::Pcm => defaults.frame_duration, }; Self { codec, - sample_rate, - layout: input.layout, - ..Self::default() + frame_duration, + ..defaults + } + } + + /// Check the settings against the codec, returning its frame size. + /// + /// Codec rules live here rather than in a backend, so every backend of a + /// codec refuses the same settings. + fn frame_size(&self) -> Result { + self.layout.validate()?; + let (rate, channels) = (self.sample_rate, self.layout.channels()); + + match self.codec { + Codec::Opus => { + opus::validate_rate(rate)?; + if !matches!(self.layout, Layout::Mono | Layout::Stereo) { + return Err(Error::Unsupported("opus requires a named mono or stereo layout".into())); + } + opus::frame_size(rate, self.frame_duration) + } + Codec::Pcm => { + if self.bitrate.is_some() { + return Err(Error::Unsupported( + "pcm bitrate is fixed; leave Settings::bitrate unset".into(), + )); + } + if self.dtx { + return Err(Error::Unsupported( + "pcm does not support discontinuous transmission".into(), + )); + } + if rate == 0 { + return Err(Error::Unsupported("pcm sample rate must be greater than zero".into())); + } + let frame_size = pcm::frame_size(rate, self.frame_duration)?; + pcm::frame_bytes(frame_size, channels)?; + pcm::bitrate(rate, channels)?; + Ok(frame_size) + } + Codec::Aac => { + if self.dtx { + return Err(Error::Unsupported( + "aac does not support discontinuous transmission".into(), + )); + } + aac_config(self)?; + let frames = (self.frame_duration.as_nanos() * u128::from(rate) + 500_000_000) / 1_000_000_000; + if frames != AAC_FRAME_SIZE as u128 { + return Err(Error::Unsupported(format!( + "aac frames are {AAC_FRAME_SIZE} samples, {:?} at {rate} Hz (got {:?})", + aac_frame_duration(rate), + self.frame_duration + ))); + } + Ok(AAC_FRAME_SIZE) + } } } } @@ -151,6 +242,52 @@ impl Default for Settings { } } +/// One AAC frame at `sample_rate`, to the nearest nanosecond. +fn aac_frame_duration(sample_rate: u32) -> Duration { + if sample_rate == 0 { + return Duration::ZERO; + } + let rate = u64::from(sample_rate); + Duration::from_nanos((AAC_FRAME_SIZE as u64 * 1_000_000_000 + rate / 2) / rate) +} + +/// The AudioSpecificConfig fields for AAC-LC at the settings' rate and layout. +/// +/// Only layouts with a channelConfiguration are accepted, since synthesizing +/// one from a bare count would mislabel the rest: config 3 is 3.0 where the +/// count's default layout is 2.1, and 6.1 has no config the encoder writes. +/// 7.1 takes config 7, the one every decoder reads as eight channels. +fn aac_config(settings: &Settings) -> Result { + let layout = settings.layout; + if !matches!( + layout, + Layout::Mono + | Layout::Stereo + | Layout::ThreePointZero + | Layout::FourPointZero + | Layout::FivePointZero + | Layout::FivePointOne + | Layout::SevenPointOne + ) { + return Err(Error::Unsupported(format!( + "aac has no channelConfiguration for {layout:?}; use mono, stereo, 3.0, 4.0, 5.0, 5.1, or 7.1" + ))); + } + + let sample_rate = settings.sample_rate; + if !(1..=AAC_MAX_SAMPLE_RATE).contains(&sample_rate) { + return Err(Error::Unsupported(format!( + "aac sample rate must be between 1 and {AAC_MAX_SAMPLE_RATE} Hz (got {sample_rate})" + ))); + } + + Ok(moq_mux::codec::aac::Config { + profile: AAC_LC, + sample_rate, + channel_count: layout.channels(), + }) +} + /// Audio encoder over codec-sized interleaved `f32` PCM. /// /// Build one with [`Encoder::new`], feed full PCM frames via @@ -158,38 +295,16 @@ impl Default for Settings { /// [`finish`](Self::finish). Publish every packet either call returns and apply /// the terminal [`Finish::discard_padding`] when the container supports it. pub struct Encoder { - backend: Backend, + backend: Box, settings: Settings, - /// Codec sample rate. - codec_rate: u32, - /// Codec channel count. - codec_channels: u32, - /// Current libopus target bitrate. - bitrate: u64, - /// Encoder lookahead expressed in the OpusHead 48 kHz timebase. - pre_skip: u16, - /// Encoder lookahead in codec-rate frames. - lookahead: usize, frame_size: usize, + /// The catalog description, synthesized from the settings at construction so + /// the rendition can be registered before the first packet exists. + description: Option, /// Whether input has reached the codec, since a fresh encoder owes no drain. started: bool, } -enum Backend { - Opus(Opus), - Pcm, -} - -struct Opus { - inner: *mut OpusEncoder, - scratch: Vec, -} - -// SAFETY: OpusEncoder is heap-allocated state owned exclusively by this -// struct; libopus encoder methods take a single &mut, so a unique owner is -// allowed to move it across threads. -unsafe impl Send for Opus {} - /// Packets emitted by [`Encoder::finish`] and the decoded padding at their end. pub struct Finish { packets: Vec, @@ -214,158 +329,40 @@ impl Finish { } impl Encoder { - /// Open an encoder for `settings`. + /// Open an encoder for `settings`, refusing a codec no backend on this host + /// encodes. pub fn new(settings: &Settings) -> Result { - settings.layout.validate()?; - match settings.codec { - Codec::Opus => Self::new_opus(settings.clone()), - Codec::Pcm => Self::new_pcm(settings.clone()), - } - } - - fn new_opus(settings: Settings) -> Result { - let codec_rate = settings.sample_rate; - opus::validate_rate(codec_rate)?; - - let codec_channels = settings.layout.channels(); - if !matches!(settings.layout, Layout::Mono | Layout::Stereo) { - return Err(Error::Unsupported("opus requires a named mono or stereo layout".into())); - } - let channels = opus::validate_channels(codec_channels)?; + let frame_size = settings.frame_size()?; + let backend = backend::open(settings)?; - let frame_size = opus::frame_size(codec_rate, settings.frame_duration)?; - - let mut err = 0i32; - // SAFETY: out-pointer `err` is valid; inner is checked for null below. - let inner = unsafe { opus_encoder_create(codec_rate as i32, channels, OPUS_APPLICATION_AUDIO, &mut err) }; - if err != OPUS_OK || inner.is_null() { - return Err(opus::error(err, "opus_encoder_create")); - } - - let configured = Self::configure_opus(inner, &settings, codec_rate, codec_channels, frame_size); - let (bitrate, lookahead, pre_skip) = match configured { - Ok(configured) => configured, - Err(err) => { - // SAFETY: `inner` was created above and not yet handed out. - unsafe { opus_encoder_destroy(inner) }; - return Err(err); + let description = match settings.codec { + Codec::Opus => { + // OpusHead carries the lookahead in the 48 kHz timebase. + let lookahead = backend.delay() as u64; + let pre_skip = u16::try_from((lookahead * 48_000) / u64::from(settings.sample_rate)) + .map_err(|_| Error::Unsupported(format!("Opus lookahead {lookahead} does not fit in OpusHead")))?; + let head = moq_mux::codec::opus::Config::new(settings.sample_rate, settings.layout.channels()) + .with_pre_skip(pre_skip) + .encode() + .map_err(moq_mux::Error::from)?; + Some(head) } + Codec::Aac => Some(aac_config(settings)?.encode()), + Codec::Pcm => None, }; Ok(Self { - backend: Backend::Opus(Opus { - inner, - scratch: vec![0u8; MAX_PACKET_BYTES], - }), - settings, - codec_rate, - codec_channels, - bitrate, - pre_skip, - lookahead, + backend, + settings: settings.clone(), frame_size, + description, started: false, }) } - fn new_pcm(settings: Settings) -> Result { - if settings.bitrate.is_some() { - return Err(Error::Unsupported( - "pcm bitrate is fixed; leave Settings::bitrate unset".into(), - )); - } - if settings.dtx { - return Err(Error::Unsupported( - "pcm does not support discontinuous transmission".into(), - )); - } - - let codec_rate = settings.sample_rate; - if codec_rate == 0 { - return Err(Error::Unsupported("pcm sample rate must be greater than zero".into())); - } - - let codec_channels = settings.layout.channels(); - if codec_channels == 0 { - return Err(Error::Unsupported("pcm channel count must be greater than zero".into())); - } - let frame_size = pcm::frame_size(codec_rate, settings.frame_duration)?; - pcm::frame_bytes(frame_size, codec_channels)?; - let bitrate = pcm::bitrate(codec_rate, codec_channels)?; - Ok(Self { - backend: Backend::Pcm, - settings, - codec_rate, - codec_channels, - bitrate, - pre_skip: 0, - lookahead: 0, - frame_size, - started: false, - }) - } - - fn configure_opus( - inner: *mut OpusEncoder, - settings: &Settings, - codec_rate: u32, - codec_channels: u32, - frame_size: usize, - ) -> Result<(u64, usize, u16), Error> { - if let Some(bitrate) = settings.bitrate { - Self::set_opus_bitrate(inner, codec_channels, bitrate.as_bps(), codec_rate, frame_size)?; - } - Self::set_opus_ctl(inner, OPUS_SET_DTX_REQUEST, i32::from(settings.dtx), "OPUS_SET_DTX")?; - - let bitrate = Self::get_opus_ctl(inner, OPUS_GET_BITRATE_REQUEST, "OPUS_GET_BITRATE")?; - let bitrate = u64::try_from(bitrate) - .map_err(|_| Error::Unsupported(format!("Opus reported negative bitrate {bitrate}")))?; - let lookahead = Self::get_opus_ctl(inner, OPUS_GET_LOOKAHEAD_REQUEST, "OPUS_GET_LOOKAHEAD")?; - let lookahead = u64::try_from(lookahead) - .map_err(|_| Error::Unsupported(format!("Opus reported negative lookahead {lookahead}")))?; - let pre_skip = u16::try_from((lookahead * 48_000) / codec_rate as u64) - .map_err(|_| Error::Unsupported(format!("Opus lookahead {lookahead} does not fit in OpusHead")))?; - let lookahead = usize::try_from(lookahead) - .map_err(|_| Error::Unsupported(format!("Opus lookahead {lookahead} does not fit in memory")))?; - - Ok((bitrate, lookahead, pre_skip)) - } - - fn set_opus_bitrate( - inner: *mut OpusEncoder, - channels: u32, - bitrate: u64, - codec_rate: u32, - frame_size: usize, - ) -> Result<(), Error> { - let max = 300_000 * channels as u64; - let min = opus::bitrate_floor(codec_rate, frame_size).max(500); - if !(min..=max).contains(&bitrate) { - return Err(Error::Unsupported(format!( - "Opus bitrate must be between {min} and {max} bits per second for {channels} channel(s) at {frame_size} samples, got {bitrate}" - ))); - } - Self::set_opus_ctl(inner, OPUS_SET_BITRATE_REQUEST, bitrate as i32, "OPUS_SET_BITRATE") - } - - fn set_opus_ctl(inner: *mut OpusEncoder, request: i32, value: i32, name: &'static str) -> Result<(), Error> { - // SAFETY: `inner` owns a live encoder and each request here expects one i32. - let rc = unsafe { opus_encoder_ctl_impl(inner, request, varargs![value]) }; - if rc != OPUS_OK { - return Err(opus::error(rc, name)); - } - Ok(()) - } - - fn get_opus_ctl(inner: *mut OpusEncoder, request: i32, name: &'static str) -> Result { - let mut value = 0; - // SAFETY: `inner` owns a live encoder and each request here expects one - // valid mutable i32 output. - let rc = unsafe { opus_encoder_ctl_impl(inner, request, varargs![&mut value]) }; - if rc != OPUS_OK { - return Err(opus::error(rc, name)); - } - Ok(value) + /// The encoder backend name in use, e.g. `"libopus"`. + pub fn name(&self) -> &str { + self.backend.name() } /// The encoder settings, including the latest accepted runtime bitrate. @@ -382,13 +379,13 @@ impl Encoder { /// Sample rate the codec actually runs at, which is /// [`Settings::sample_rate`]. pub fn codec_rate(&self) -> u32 { - self.codec_rate + self.settings.sample_rate } /// Channel count the codec actually runs at, which is /// [`Settings::layout`]'s channel count. pub fn codec_channels(&self) -> u32 { - self.codec_channels + self.settings.layout.channels() } /// Number of samples per channel the codec consumes per call to @@ -399,23 +396,21 @@ impl Encoder { /// Current target bitrate. pub fn bitrate(&self) -> moq_net::bandwidth::Rate { - moq_net::bandwidth::Rate::from_bps(self.bitrate) + moq_net::bandwidth::Rate::from_bps(self.backend.bitrate()) } - /// Retune the live Opus encoder to `bitrate`. + /// Retune the live encoder to `bitrate`. + /// + /// # Errors + /// + /// Returns [`Error::Unsupported`] when the codec's rate is fixed (PCM) or the + /// backend can't change it mid-stream. The encoder keeps running at its + /// opening rate, so a caller driving a control loop should stop adapting + /// rather than stop encoding. pub fn set_bitrate(&mut self, bitrate: moq_net::bandwidth::Rate) -> Result<(), Error> { - let Backend::Opus(opus) = &mut self.backend else { - return Err(Error::Unsupported("pcm bitrate is fixed".into())); - }; - if bitrate.as_bps() != self.bitrate { - Self::set_opus_bitrate( - opus.inner, - self.codec_channels, - bitrate.as_bps(), - self.codec_rate, - self.frame_size, - )?; - self.bitrate = bitrate.as_bps(); + let previous = self.backend.bitrate(); + self.backend.set_bitrate(bitrate.as_bps())?; + if bitrate.as_bps() != previous { self.settings.bitrate = Some(bitrate); } Ok(()) @@ -423,11 +418,7 @@ impl Encoder { /// Drop all codec history so a later epoch cannot emit audio from this one. pub(super) fn reset(&mut self) { - if let Backend::Opus(opus) = &mut self.backend { - // SAFETY: `inner` owns a live encoder and OPUS_RESET_STATE takes no arguments. - let rc = unsafe { opus_encoder_ctl_impl(opus.inner, OPUS_RESET_STATE, varargs![]) }; - debug_assert_eq!(rc, OPUS_OK, "OPUS_RESET_STATE failed with {rc}"); - } + self.backend.reset(); self.started = false; } @@ -436,47 +427,34 @@ impl Encoder { self.started } + /// Codec priming the catalog can't signal, in codec-rate frames, which the + /// producer folds into its timestamps instead. + /// + /// Opus declares its lookahead as OpusHead pre-skip, which the decoder trims, + /// so nothing is folded. An AudioSpecificConfig has no such field, so each + /// AAC packet is stamped that much earlier and the priming lands before the + /// first input sample rather than delaying it. + pub(super) fn folded_delay(&self) -> usize { + match self.settings.codec { + Codec::Aac => self.backend.delay(), + Codec::Opus | Codec::Pcm => 0, + } + } + /// Encode one frame of interleaved `f32` PCM at [`codec_rate`](Self::codec_rate). /// /// `pcm.len()` must equal `frame_size() * codec_channels()`. The /// [`Producer`](super::Producer) handles format conversion and resampling /// before calling this; for direct use, the caller does the same. pub fn encode(&mut self, pcm: &[f32]) -> Result { - let expected = self.frame_size * self.codec_channels as usize; + let expected = self.frame_size * self.codec_channels() as usize; if pcm.len() != expected { return Err(Error::Misaligned { got: std::mem::size_of_val(pcm), expected: expected * std::mem::size_of::(), }); } - let encoded = match &mut self.backend { - Backend::Opus(opus) => { - // SAFETY: `inner` owns a live OpusEncoder; pcm and scratch slices - // are bounded by the lengths we pass. - let n = unsafe { - opus_encode_float( - opus.inner, - pcm.as_ptr(), - self.frame_size as i32, - opus.scratch.as_mut_ptr(), - opus.scratch.len() as i32, - ) - }; - if n < 0 { - return Err(crate::opus::error(n, "opus_encode_float")); - } - let payload = Bytes::copy_from_slice(&opus.scratch[..n as usize]); - let activity = crate::opus::activity(&payload, false); - Encoded { payload, activity } - } - Backend::Pcm => { - let mut payload = Vec::with_capacity(std::mem::size_of_val(pcm)); - for sample in pcm { - payload.extend_from_slice(&sample.to_le_bytes()); - } - Encoded::new(payload.into()) - } - }; + let encoded = self.backend.encode(pcm)?; self.started = true; Ok(encoded) } @@ -496,7 +474,7 @@ impl Encoder { /// Same drain as [`finish`](Self::finish), without consuming the encoder. pub(super) fn drain(&mut self, pcm: &[f32]) -> Result { - let channels = self.codec_channels as usize; + let channels = self.codec_channels() as usize; let frame_samples = self.frame_size * channels; if pcm.len() > frame_samples || !pcm.len().is_multiple_of(channels) { return Err(Error::Misaligned { @@ -529,7 +507,8 @@ impl Encoder { }); } - let drain = self.lookahead.saturating_sub(padding); + let lookahead = self.backend.delay(); + let drain = lookahead.saturating_sub(padding); let silence = vec![0.0; frame_samples]; for _ in 0..drain.div_ceil(self.frame_size) { packets.push(self.encode(&silence)?); @@ -538,7 +517,7 @@ impl Encoder { let discard_padding = packets .len() .saturating_mul(self.frame_size) - .saturating_sub(self.lookahead) + .saturating_sub(lookahead) .saturating_sub(source_frames); Ok(Finish { @@ -549,46 +528,27 @@ impl Encoder { /// hang catalog entry describing this encoder's output stream. pub fn catalog(&self) -> hang::catalog::AudioConfig { - match self.settings.codec { - Codec::Opus => { - // `codec_channels` is validated to mono/stereo at encoder construction, - // so the OpusHead (channel mapping family 0) always encodes. - let head = moq_mux::codec::opus::Config::new(self.codec_rate, self.codec_channels) - .with_pre_skip(self.pre_skip) - .encode() - .expect("opus encoder channels validated to mono/stereo"); - - let mut config = hang::catalog::AudioConfig::new( - hang::catalog::AudioCodec::Opus, - self.codec_rate, - self.codec_channels, - ); - config.bitrate = self.settings.bitrate.map(moq_net::bandwidth::Rate::as_bps); - config.description = Some(head); - config.container = hang::catalog::Container::Legacy; - config - } - Codec::Pcm => { - let mut config = hang::catalog::AudioConfig::new( - hang::catalog::AudioCodec::Pcm, - self.codec_rate, - self.codec_channels, - ); - config.bitrate = Some( - pcm::bitrate(self.codec_rate, self.codec_channels) - .expect("pcm encoder bitrate validated at construction"), - ); - config.container = hang::catalog::Container::Legacy; - config - } - } - } -} + let (rate, channels) = (self.codec_rate(), self.codec_channels()); + let (codec, bitrate): (hang::catalog::AudioCodec, _) = match self.settings.codec { + Codec::Opus => ( + hang::catalog::AudioCodec::Opus, + self.settings.bitrate.map(moq_net::bandwidth::Rate::as_bps), + ), + Codec::Pcm => ( + hang::catalog::AudioCodec::Pcm, + Some(pcm::bitrate(rate, channels).expect("pcm encoder bitrate validated at construction")), + ), + Codec::Aac => ( + hang::catalog::AAC { profile: AAC_LC }.into(), + self.settings.bitrate.map(moq_net::bandwidth::Rate::as_bps), + ), + }; -impl Drop for Opus { - fn drop(&mut self) { - // SAFETY: `inner` is a live OpusEncoder that nothing else aliases. - unsafe { opus_encoder_destroy(self.inner) }; + let mut config = hang::catalog::AudioConfig::new(codec, rate, channels); + config.bitrate = bitrate; + config.description = self.description.clone(); + config.container = hang::catalog::Container::Legacy; + config } } @@ -609,11 +569,11 @@ mod tests { out } - fn opus_inner(encoder: &Encoder) -> *mut OpusEncoder { - let Backend::Opus(opus) = &encoder.backend else { - panic!("expected Opus encoder"); - }; - opus.inner + /// The published `Encoder` was unwind safe before it boxed a backend; keep it so. + #[test] + fn encoder_is_unwind_safe() { + fn assert_unwind_safe() {} + assert_unwind_safe::(); } #[test] @@ -675,7 +635,6 @@ mod tests { let desc = cfg.description.expect("OpusHead should be present"); assert_eq!(desc.len(), 19); let head = moq_mux::codec::opus::Config::parse(&mut desc.as_ref()).unwrap(); - assert_eq!(head.pre_skip, enc.pre_skip); assert_eq!(head.pre_skip, 312); } @@ -688,7 +647,7 @@ mod tests { let first = dec.decode(&enc.encode(&frame).unwrap().payload).unwrap(); assert_eq!( first.samples.len(), - (enc.frame_size() - enc.pre_skip as usize) * enc.codec_channels() as usize + (enc.frame_size() - enc.backend.delay()) * enc.codec_channels() as usize ); let second = dec.decode(&enc.encode(&frame).unwrap().payload).unwrap(); @@ -757,15 +716,6 @@ mod tests { enc.set_bitrate(moq_net::bandwidth::Rate::from_bps(32_000)).unwrap(); assert_eq!(enc.bitrate(), moq_net::bandwidth::Rate::from_bps(32_000)); assert_eq!(enc.settings().bitrate, Some(moq_net::bandwidth::Rate::from_bps(32_000))); - assert_eq!( - Encoder::get_opus_ctl( - opus_inner(&enc), - unsafe_libopus::OPUS_GET_BITRATE_REQUEST, - "OPUS_GET_BITRATE" - ) - .unwrap(), - 32_000 - ); } #[test] @@ -777,20 +727,6 @@ mod tests { assert_eq!(enc.bitrate(), original); } - #[test] - fn opus_applies_dtx_control() { - let enc = Encoder::new(&Settings { - dtx: true, - ..Settings::default() - }) - .unwrap(); - - assert_eq!( - Encoder::get_opus_ctl(opus_inner(&enc), unsafe_libopus::OPUS_GET_DTX_REQUEST, "OPUS_GET_DTX").unwrap(), - 1 - ); - } - #[test] fn codec_roundtrips_as_str() { assert_eq!(Codec::Opus.as_str(), "opus"); @@ -799,15 +735,20 @@ mod tests { assert_eq!(Codec::Pcm.as_str(), "pcm"); assert_eq!(Codec::Pcm.to_string(), "pcm"); assert_eq!("pcm".parse::().unwrap(), Codec::Pcm); - assert!("aac".parse::().is_err()); + assert_eq!(Codec::Aac.as_str(), "aac"); + assert_eq!(Codec::Aac.to_string(), "aac"); + assert_eq!("aac".parse::().unwrap(), Codec::Aac); + assert!("mp3".parse::().is_err()); } #[test] fn settings_fix_the_codec_rate() { let enc = Encoder::new(&Settings::new(24_000, Layout::Mono)).unwrap(); assert_eq!(enc.codec_rate(), 24_000); - assert_eq!(enc.catalog().sample_rate, 24_000); - assert_eq!(enc.pre_skip, 312); + let catalog = enc.catalog(); + assert_eq!(catalog.sample_rate, 24_000); + let head = moq_mux::codec::opus::Config::parse(&mut catalog.description.unwrap().as_ref()).unwrap(); + assert_eq!(head.pre_skip, 312); } #[test] @@ -826,6 +767,31 @@ mod tests { assert_eq!(output.samples, input); } + /// A PCM catalog names only a count, and 3 or 4 channels decode as 2.1 or + /// quad, so 3.0 and 4.0 are refused; discrete channels still pass through. + #[test] + fn pcm_refuses_layouts_its_count_cannot_name() { + for layout in [Layout::ThreePointZero, Layout::FourPointZero] { + let err = Encoder::new(&Settings { + codec: Codec::Pcm, + ..Settings::new(48_000, layout) + }); + assert!(matches!(err, Err(Error::Unsupported(_))), "{layout:?}"); + } + + for layout in [Layout::TwoPointOne, Layout::Quad, Layout::Discrete(3)] { + let mut enc = Encoder::new(&Settings { + codec: Codec::Pcm, + ..Settings::new(48_000, layout) + }) + .unwrap(); + let mut dec = Decoder::new(&enc.catalog(), &DecodeConfig::default()).unwrap(); + let input = sine(440.0, enc.codec_rate(), enc.codec_channels(), enc.frame_size()); + let output = dec.decode(&enc.encode(&input).unwrap().payload).unwrap(); + assert_eq!(output.samples, input, "{layout:?}"); + } + } + #[test] fn pcm_catalog_declares_fixed_bitrate() { let enc = Encoder::new(&Settings { @@ -883,8 +849,10 @@ mod tests { assert!(matches!(Encoder::new(&settings), Err(Error::Unsupported(_)))); } + /// The catalog carries only a count, so a discrete layout comes back as the + /// count's default one, with the samples untouched. #[test] - fn pcm_preserves_discrete_multichannel_layout() { + fn pcm_passes_discrete_multichannel_samples_through() { let settings = Settings { codec: Codec::Pcm, ..Settings::new(48_000, Layout::Discrete(3)) @@ -895,7 +863,7 @@ mod tests { let input = [0.1, 0.2, 0.3].repeat(encoder.frame_size()); let output = decoder.decode(&encoder.encode(&input).unwrap().payload).unwrap(); - assert_eq!(decoder.layout(), Layout::Discrete(3)); + assert_eq!(decoder.layout(), Layout::TwoPointOne); assert_eq!(output.samples, input); } @@ -904,4 +872,129 @@ mod tests { let settings = Settings::new(48_000, Layout::Discrete(2)); assert!(matches!(Encoder::new(&settings), Err(Error::Unsupported(_)))); } + + fn aac(layout: Layout) -> Settings { + Settings::from_input(Codec::Aac, &Input::new(48_000, layout)) + } + + /// Open `settings` on the test stub, since this host has no AAC encoder. + fn stub(settings: &Settings) -> Result { + let _stub = backend::stub::install(); + Encoder::new(settings) + } + + /// Without the stub, the public constructor sees the real tiers and refuses. + #[test] + fn aac_is_refused_without_an_encoder() { + let err = Encoder::new(&aac(Layout::Stereo)) + .err() + .expect("no AAC encoder on this host"); + assert!(matches!(err, Error::Unsupported(_)), "{err}"); + } + + /// The ASC is synthesized from the settings, so it exists before any packet. + #[test] + fn aac_catalog_carries_the_synthesized_asc() { + let enc = stub(&aac(Layout::Stereo)).unwrap(); + assert_eq!(enc.name(), backend::stub::NAME); + assert_eq!(enc.frame_size(), 1024); + + let catalog = enc.catalog(); + assert_eq!(catalog.codec, hang::catalog::AAC { profile: 2 }.into()); + assert_eq!(catalog.codec.to_string(), "mp4a.40.2"); + assert_eq!(catalog.sample_rate, 48_000); + assert_eq!(catalog.channel_count, 2); + assert_eq!(catalog.container, hang::catalog::Container::Legacy); + // AAC-LC (2), 48 kHz (index 3), stereo (config 2). + assert_eq!(catalog.description.as_deref(), Some(&[0x11, 0x90][..])); + } + + #[test] + fn aac_takes_the_layouts_with_a_channel_configuration() { + for (layout, config) in [ + (Layout::Mono, 1), + (Layout::Stereo, 2), + (Layout::ThreePointZero, 3), + (Layout::FourPointZero, 4), + (Layout::FivePointZero, 5), + (Layout::FivePointOne, 6), + (Layout::SevenPointOne, 7), + ] { + let catalog = stub(&aac(layout)).unwrap().catalog(); + let description = catalog.description.unwrap(); + assert_eq!(description[1] >> 3 & 0xF, config, "{layout:?}"); + assert_eq!(catalog.channel_count, layout.channels(), "{layout:?}"); + } + + for layout in [ + Layout::TwoPointOne, + Layout::Quad, + Layout::SixPointOne, + Layout::Discrete(2), + ] { + assert!(matches!(stub(&aac(layout)), Err(Error::Unsupported(_))), "{layout:?}"); + } + } + + /// AAC frames are 1024 samples however the duration is spelled. + #[test] + fn aac_frame_duration_is_the_codecs() { + assert_eq!(aac(Layout::Stereo).frame_duration, Duration::from_nanos(21_333_333)); + let settings = Settings { + frame_duration: Duration::from_micros(21_333), + ..aac(Layout::Stereo) + }; + assert_eq!(stub(&settings).unwrap().frame_size(), 1024); + + let settings = Settings { + frame_duration: Duration::from_millis(20), + ..aac(Layout::Stereo) + }; + let err = stub(&settings).err().expect("20 ms is 960 samples"); + assert!(err.to_string().contains("1024"), "{err}"); + } + + #[test] + fn aac_refuses_dtx() { + let settings = Settings { + dtx: true, + ..aac(Layout::Stereo) + }; + assert!(matches!(stub(&settings), Err(Error::Unsupported(_)))); + } + + /// A backend that can't retune keeps its opening rate. + #[test] + fn fixed_rate_backend_keeps_its_opening_rate() { + let mut enc = stub(&Settings { + bitrate: Some(moq_net::bandwidth::Rate::from_bps(96_000)), + ..aac(Layout::Stereo) + }) + .unwrap(); + + let err = enc.set_bitrate(moq_net::bandwidth::Rate::from_bps(64_000)); + assert!(matches!(err, Err(Error::Unsupported(_)))); + assert_eq!(enc.bitrate(), moq_net::bandwidth::Rate::from_bps(96_000)); + assert_eq!(enc.settings().bitrate, Some(moq_net::bandwidth::Rate::from_bps(96_000))); + assert_eq!(enc.catalog().bitrate, Some(96_000)); + } + + /// The drain pushes the encoder delay out through whole silent frames. + #[test] + fn aac_finish_drains_the_encoder_delay() { + let mut enc = stub(&aac(Layout::Mono)).unwrap(); + assert_eq!(enc.folded_delay(), backend::stub::DELAY); + enc.encode(&[0.0; 1024]).unwrap(); + + // 2112 frames of delay take three 1024-frame packets. + let finish = enc.finish(&[]).unwrap(); + assert_eq!(finish.packets().len(), 3); + assert_eq!(finish.discard_padding(), 3 * 1024 - backend::stub::DELAY); + } + + /// Opus signals its lookahead as pre-skip, so the producer folds none of it. + #[test] + fn opus_folds_no_delay() { + assert_eq!(Encoder::new(&Settings::default()).unwrap().folded_delay(), 0); + } } diff --git a/rs/moq-audio/src/encode/mod.rs b/rs/moq-audio/src/encode/mod.rs index 9c918b97445..10c3125e416 100644 --- a/rs/moq-audio/src/encode/mod.rs +++ b/rs/moq-audio/src/encode/mod.rs @@ -1,6 +1,8 @@ //! Encode raw PCM and publish it as a moq audio track. //! -//! The output codec is selected via [`Codec`]. +//! The output codec is selected via [`Codec`], and the implementation behind it +//! via [`Kind`]: a platform encoder when the host has one, software otherwise. +//! AAC has no software encoder, so a host without a platform one refuses it. //! //! Entry points, high to low level: //! - `publish_capture` captures a microphone (or system audio) and publishes @@ -15,6 +17,7 @@ //! `publish_capture` is unlinked above because it only exists with the `capture` //! feature, so a default-feature rustdoc build has nothing to link to. +mod backend; mod encoded; mod encoder; mod producer; @@ -23,7 +26,7 @@ mod producer; mod capture; pub use encoded::Encoded; -pub use encoder::{Codec, Encoder, Finish, Input, Settings}; +pub use encoder::{Codec, Encoder, Finish, Input, Kind, Settings}; pub use producer::{Options, Producer}; #[cfg(feature = "capture")] diff --git a/rs/moq-audio/src/encode/producer.rs b/rs/moq-audio/src/encode/producer.rs index dcc3d1c9569..742f5636793 100644 --- a/rs/moq-audio/src/encode/producer.rs +++ b/rs/moq-audio/src/encode/producer.rs @@ -10,7 +10,7 @@ use moq_net::Timestamp; use super::encoded::Encoded; use super::encoder::{Encoder, Input, Settings}; -use crate::resample::{Resampler, remix, validate_remix}; +use crate::resample::{Remix, Resampler}; use crate::{Activity, Error, Frame}; /// Encode and publication policy for [`Producer`]. @@ -64,6 +64,8 @@ impl Default for Options { pub struct Producer { encoder: Encoder, input: Input, + /// Converts the input layout to the codec's, when they differ. + remix: Option, resampler: Option, track: moq_mux::container::Producer, _ext: std::marker::PhantomData E>, @@ -140,7 +142,9 @@ impl Reserved { /// Separate from [`encode`](Self::encode), which cannot fail, so a layout the /// codec rejects leaves the reservation intact for another input. pub(crate) fn register(&mut self, input: Input, options: &Options) -> Result { - validate_remix(input.layout, options.settings.layout)?; + let remix = (input.layout != options.settings.layout) + .then(|| Remix::new(input.layout, options.settings.layout)) + .transpose()?; let encoder = Encoder::new(&options.settings)?; let resampler = if input.sample_rate == encoder.codec_rate() { @@ -163,6 +167,7 @@ impl Reserved { Ok(Registered { encoder, input, + remix, resampler, }) } @@ -172,6 +177,7 @@ impl Reserved { Producer { encoder: registered.encoder, input: registered.input, + remix: registered.remix, resampler: registered.resampler, track: self.track, _ext: self._ext, @@ -193,6 +199,7 @@ impl Reserved { pub(crate) struct Registered { encoder: Encoder, input: Input, + remix: Option, resampler: Option, } @@ -337,7 +344,10 @@ impl Producer { let input = &self.input; let (format, channels) = (input.format, input.layout.channels()); let pcm = format.as_interleaved_f32(frame.data.as_ref(), channels)?; - let pcm = remix(&pcm, input.layout, self.encoder.settings().layout)?; + let pcm = match &self.remix { + Some(remix) => remix.process(&pcm), + None => pcm.into_owned(), + }; let pcm: Vec = match self.resampler.as_mut() { Some(r) => r.process(&pcm, frame.timestamp)?, None => pcm, @@ -356,7 +366,12 @@ impl Producer { let chunk: Vec = self.pending.drain(..frame_samples).collect(); let packet = self.encoder.encode(&chunk)?; - let timestamp = Self::timestamp(epoch_us, self.frames_produced, self.encoder.codec_rate())?; + let timestamp = Self::timestamp( + epoch_us, + self.frames_produced, + self.encoder.folded_delay(), + self.encoder.codec_rate(), + )?; self.frames_produced += self.encoder.frame_size() as u64; self.activity = packet.activity; Self::publish(&mut self.track, packet, timestamp)?; @@ -366,10 +381,18 @@ impl Producer { Ok(()) } - /// PTS of the next frame: the epoch plus the samples emitted since it. - fn timestamp(epoch_us: u64, frames_produced: u64, codec_rate: u32) -> Result { - let offset_us = (frames_produced * 1_000_000) / codec_rate as u64; - Ok(Timestamp::from_micros(epoch_us + offset_us)?) + /// PTS of the frame `frames` samples past the epoch, stamped `delay` samples + /// earlier to fold in codec priming the catalog can't signal. + /// + /// Priming that would land before a zero epoch is stamped at zero instead: it + /// decodes to the codec's warm-up rather than to input, so only its spacing is + /// lost. + fn timestamp(epoch_us: u64, frames: u64, delay: usize, codec_rate: u32) -> Result { + let frames = i128::from(frames) - delay as i128; + let offset_us = (frames * 1_000_000).div_euclid(i128::from(codec_rate)); + let micros = (i128::from(epoch_us) + offset_us).max(0); + let micros = u64::try_from(micros).map_err(|_| moq_net::TimeOverflow)?; + Ok(Timestamp::from_micros(micros)?) } fn publish( @@ -464,8 +487,10 @@ impl Producer { let codec_rate = self.encoder.codec_rate(); let channels = self.encoder.codec_channels() as usize; let source_frames = self.pending.len() / channels; - let start = Self::timestamp(epoch_us, self.frames_produced, codec_rate)?; - let end = Self::timestamp(epoch_us, self.frames_produced + source_frames as u64, codec_rate)?; + let delay = self.encoder.folded_delay(); + let start = Self::timestamp(epoch_us, self.frames_produced, delay, codec_rate)?; + // The source ends where it ends: priming only moves the packets carrying it. + let end = Self::timestamp(epoch_us, self.frames_produced + source_frames as u64, 0, codec_rate)?; let finish = self.encoder.drain(&self.pending)?; let discard_padding = finish.discard_padding(); let packets = finish.into_packets(); @@ -483,7 +508,7 @@ impl Producer { )?; } else { for packet in packets { - let timestamp = Self::timestamp(epoch_us, self.frames_produced, codec_rate)?; + let timestamp = Self::timestamp(epoch_us, self.frames_produced, delay, codec_rate)?; self.activity = packet.activity; Self::publish(&mut self.track, packet, timestamp)?; self.frames_produced += frame_size as u64; @@ -888,6 +913,50 @@ mod tests { assert_eq!(pts, vec![1_000_000]); } + /// AAC can't signal its encoder delay, so each packet is stamped that much + /// earlier and the first input sample still decodes at the epoch. + #[tokio::test] + async fn aac_folds_the_encoder_delay_into_timestamps() { + async fn pts(epoch_us: u64) -> Vec { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let catalog = moq_mux::catalog::Producer::new(&mut broadcast, moq_mux::catalog::Config::default()).unwrap(); + let consumer = broadcast.consume(); + + let input = Input::new(48_000, Layout::Mono); + let options = Options { + track: Some("audio".to_string()), + settings: Settings::from_input(crate::encode::Codec::Aac, &input), + ..Options::default() + }; + let stub = crate::encode::backend::stub::install(); + let mut producer = Producer::new(&mut broadcast, catalog, input, &options).unwrap(); + drop(stub); + + let track = consumer + .track("audio") + .unwrap() + .subscribe(moq_net::track::Subscription::default().with_max_age(Duration::from_secs(1))) + .await + .unwrap(); + let mut reader = moq_mux::container::Consumer::new( + track, + moq_mux::container::legacy::Wire(moq_mux::container::Kind::Audio), + ); + + producer.write(&pcm_frame(&[0.1; 4 * 1024], epoch_us)).unwrap(); + let mut pts = Vec::new(); + for _ in 0..4 { + pts.push(reader.read().await.unwrap().expect("a packet").timestamp.as_micros()); + } + pts + } + + // 2112 frames of delay at 48 kHz is 44 ms, rounded down per packet. + assert_eq!(pts(1_000_000).await, vec![956_000, 977_333, 998_666, 1_020_000]); + // Priming before a zero epoch stamps at zero; the input still starts on time. + assert_eq!(pts(0).await, vec![0, 0, 0, 20_000]); + } + /// The encoder needs no correction for the resampler's own delay: it anchors /// the epoch to the first input timestamp and advances by emitted samples, /// while `Resampler::process` drops its startup silence rather than passing it diff --git a/rs/moq-audio/src/layout.rs b/rs/moq-audio/src/layout.rs index 0ff4d0d09b1..90373ed715f 100644 --- a/rs/moq-audio/src/layout.rs +++ b/rs/moq-audio/src/layout.rs @@ -1,6 +1,11 @@ use crate::Error; /// Speaker meaning and interleaving order for PCM channels. +/// +/// Named layouts interleave in the SMPTE/WAVE order (front left, front right, +/// center, LFE, back left, back right, back center, side left, side right), +/// keeping only the speakers the layout has. Every decoder reorders its codec's +/// native order into this one. #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] #[non_exhaustive] pub enum Layout { @@ -10,11 +15,47 @@ pub enum Layout { #[default] Stereo, /// Channels with no declared speaker positions, in source order. + /// + /// Passes through unchanged but can't be remixed into another layout. Discrete(u32), + /// 2.1: left, right, LFE. + TwoPointOne, + /// 3.0: left, right, center. + ThreePointZero, + /// Quad: left, right, back left, back right. + Quad, + /// 4.0: left, right, center, back center. + FourPointZero, + /// 5.0: left, right, center, side left, side right. + FivePointZero, + /// 5.1: left, right, center, LFE, side left, side right. + FivePointOne, + /// 6.1: left, right, center, LFE, back center, side left, side right. + SixPointOne, + /// 7.1: left, right, center, LFE, back left, back right, side left, side right. + SevenPointOne, +} + +/// One speaker position, declared in the canonical interleaving order. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub(crate) enum Speaker { + FrontLeft, + FrontRight, + FrontCenter, + Lfe, + BackLeft, + BackRight, + BackCenter, + SideLeft, + SideRight, } impl Layout { - /// Infer today's conventional layout from a channel count. + /// The default layout for a channel count, by the WAVE convention: 1 is mono, + /// 2 stereo, 3 2.1, 4 quad, 5 5.0, 6 5.1, 7 6.1, and 8 7.1. + /// + /// Any other count is [`Discrete`](Self::Discrete), since there is no + /// convention to take speaker positions from. pub fn from_channels(channels: u32) -> Result { match channels { 0 => Err(Error::Unsupported( @@ -22,6 +63,12 @@ impl Layout { )), 1 => Ok(Self::Mono), 2 => Ok(Self::Stereo), + 3 => Ok(Self::TwoPointOne), + 4 => Ok(Self::Quad), + 5 => Ok(Self::FivePointZero), + 6 => Ok(Self::FivePointOne), + 7 => Ok(Self::SixPointOne), + 8 => Ok(Self::SevenPointOne), channels => Ok(Self::Discrete(channels)), } } @@ -29,12 +76,40 @@ impl Layout { /// Number of interleaved channels in this layout. pub fn channels(self) -> u32 { match self { - Self::Mono => 1, - Self::Stereo => 2, Self::Discrete(channels) => channels, + layout => layout.speakers().map_or(0, <[_]>::len) as u32, } } + /// The speaker each channel feeds, in interleaved order, or `None` for a + /// discrete layout. + pub(crate) fn speakers(self) -> Option<&'static [Speaker]> { + use Speaker::*; + + Some(match self { + Self::Mono => &[FrontCenter], + Self::Stereo => &[FrontLeft, FrontRight], + Self::Discrete(_) => return None, + Self::TwoPointOne => &[FrontLeft, FrontRight, Lfe], + Self::ThreePointZero => &[FrontLeft, FrontRight, FrontCenter], + Self::Quad => &[FrontLeft, FrontRight, BackLeft, BackRight], + Self::FourPointZero => &[FrontLeft, FrontRight, FrontCenter, BackCenter], + Self::FivePointZero => &[FrontLeft, FrontRight, FrontCenter, SideLeft, SideRight], + Self::FivePointOne => &[FrontLeft, FrontRight, FrontCenter, Lfe, SideLeft, SideRight], + Self::SixPointOne => &[FrontLeft, FrontRight, FrontCenter, Lfe, BackCenter, SideLeft, SideRight], + Self::SevenPointOne => &[ + FrontLeft, + FrontRight, + FrontCenter, + Lfe, + BackLeft, + BackRight, + SideLeft, + SideRight, + ], + }) + } + pub(crate) fn validate(self) -> Result<(), Error> { if self.channels() == 0 { return Err(Error::Unsupported( @@ -44,3 +119,54 @@ impl Layout { Ok(()) } } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn counts_map_to_the_wave_defaults() { + let expected = [ + Layout::Mono, + Layout::Stereo, + Layout::TwoPointOne, + Layout::Quad, + Layout::FivePointZero, + Layout::FivePointOne, + Layout::SixPointOne, + Layout::SevenPointOne, + ]; + for (count, layout) in (1..).zip(expected) { + assert_eq!(Layout::from_channels(count).unwrap(), layout); + assert_eq!(layout.channels(), count); + } + + assert_eq!(Layout::from_channels(9).unwrap(), Layout::Discrete(9)); + assert!(Layout::from_channels(0).is_err()); + } + + /// Canonical order is the WAVE bit order, so every layout's speakers must + /// ascend through [`Speaker`]'s declaration order without repeating. + #[test] + fn speakers_follow_the_canonical_order() { + let layouts = [ + Layout::Mono, + Layout::Stereo, + Layout::TwoPointOne, + Layout::ThreePointZero, + Layout::Quad, + Layout::FourPointZero, + Layout::FivePointZero, + Layout::FivePointOne, + Layout::SixPointOne, + Layout::SevenPointOne, + ]; + for layout in layouts { + let speakers = layout.speakers().unwrap(); + assert!( + speakers.windows(2).all(|pair| (pair[0] as u8) < (pair[1] as u8)), + "{layout:?} is out of order" + ); + } + } +} diff --git a/rs/moq-audio/src/lib.rs b/rs/moq-audio/src/lib.rs index b8c7aa92428..92d1c04dfff 100644 --- a/rs/moq-audio/src/lib.rs +++ b/rs/moq-audio/src/lib.rs @@ -3,8 +3,9 @@ //! Counterpart to [`moq-video`](https://crates.io/crates/moq-video) for audio //! tracks, and shaped the same way. Sits on top of [`moq_mux`] and [`hang`] and //! adds the missing piece for native callers: Rust-native Opus and uncompressed -//! PCM codecs that turn raw samples into HANG audio tracks and back, plus AAC-LC -//! on the way in, which is what the gateways (RTMP, SRT, HLS, gstreamer) publish. +//! PCM codecs that turn raw samples into HANG audio tracks and back, plus AAC-LC, +//! which is what the gateways (RTMP, SRT, HLS, gstreamer) publish. AAC decodes in +//! software and encodes only through a platform encoder. //! //! - `capture` describes an audio source (`capture::Config`) and grabs buffers //! per platform: a microphone via cpal (CoreAudio / WASAPI / ALSA) everywhere, @@ -26,7 +27,7 @@ //! - [`decode`] subscribes to an encoded track and decodes it back to PCM. //! [`decode::Consumer`] is the mirror of [`encode::Producer`]. It reads AAC-LC //! too, behind the default-on `aac` feature, since a broadcast that came in -//! through a gateway is AAC rather than one of the two codecs we encode. +//! through a gateway is AAC rather than one of the codecs we encode in software. //! - `playback` plays decoded PCM out a speaker. `playback::Engine` owns the //! output device and mixes the `playback::Sink`s registered with it, so one //! device serves every track in a call. Requires the `playback` feature, so diff --git a/rs/moq-audio/src/opus.rs b/rs/moq-audio/src/opus.rs index c8b2e8fac26..8b744bc09ee 100644 --- a/rs/moq-audio/src/opus.rs +++ b/rs/moq-audio/src/opus.rs @@ -20,9 +20,8 @@ pub(crate) const DECODE_RATE: u32 = 48_000; /// The OpusHead a decoder opens with. /// -/// The catalog's description when present, refused when malformed or when it -/// asks for a channel mapping this crate cannot decode. Without one, a -/// mono/stereo stream with no pre-skip or gain, shaped by the catalog. +/// The catalog's description when present, refused when malformed. Without +/// one, a family 0 stream with no pre-skip or gain, shaped by the catalog. pub(crate) fn head(catalog: &hang::catalog::AudioConfig) -> Result { let Some(description) = &catalog.description else { return Ok(moq_mux::codec::opus::Config::new( @@ -30,16 +29,8 @@ pub(crate) fn head(catalog: &hang::catalog::AudioConfig) -> Result Error { if code == unsafe_libopus::OPUS_INVALID_PACKET { return Error::Decode(format!("libopus rejected the packet (code {code})")); } - error(code, "opus_decode_float") + error(code, "opus_multistream_decode_float") } /// Classify a packet, preserving DTX across packet loss. @@ -108,6 +99,171 @@ pub(crate) fn activity(packet: &[u8], in_dtx: bool) -> Activity { } } +/// Classify a multistream packet, preserving DTX across packet loss. +/// +/// Every stream but the last is self-delimited (RFC 6716 framing plus the length +/// libopus writes ahead of that stream's payload). One `opus_packet_parse` of the +/// whole buffer treats the later streams as payload, so an all-DTX surround +/// packet reads as active. DTX means every stream coded nothing. +pub(crate) fn multistream_activity(packet: &[u8], streams: u8, in_dtx: bool) -> Activity { + if packet.is_empty() { + return if in_dtx { Activity::Dtx } else { Activity::Active }; + } + if streams <= 1 { + return activity(packet, in_dtx); + } + if streams_carry_nothing(packet, streams) { + Activity::Dtx + } else { + Activity::Active + } +} + +/// Whether every stream in a multistream packet coded no audio. +fn streams_carry_nothing(mut packet: &[u8], streams: u8) -> bool { + for index in 0..streams { + let last = index + 1 == streams; + if last { + return carries_nothing(packet); + } + let Some((silent, offset)) = self_delimited(packet) else { + return false; + }; + if !silent { + return false; + } + packet = &packet[offset..]; + } + false +} + +/// One self-delimited Opus packet at the front of `data`: whether every frame is +/// empty, and how many bytes it occupies, including its trailing padding. +/// +/// `None` when the bytes are not that packet. The length of the last frame is +/// coded where libopus puts it, before the frame payloads. +fn self_delimited(data: &[u8]) -> Option<(bool, usize)> { + if data.is_empty() { + return None; + } + let framesize = unsafe { unsafe_libopus::opus_packet_get_samples_per_frame(data.as_ptr(), 48_000) }; + if framesize <= 0 { + return None; + } + + let toc = data[0]; + let mut pos = 1usize; + let mut len = data.len() - 1; + let mut last_size = len; + let mut cbr = false; + let mut pad = 0usize; + let mut sizes = [0i32; 48]; + + let count = match toc & 0x3 { + 0 => 1, + 1 => { + cbr = true; + 2 + } + 2 => { + let (bytes, size) = parse_size(data.get(pos..pos.checked_add(len)?)?)?; + len = len.checked_sub(bytes)?; + if size as usize > len { + return None; + } + sizes[0] = size; + pos += bytes; + last_size = len - size as usize; + 2 + } + _ => { + if len < 1 { + return None; + } + let ch = data[pos]; + pos += 1; + len -= 1; + let count = (ch & 0x3f) as usize; + if count == 0 || count > sizes.len() || framesize as usize * count > 5760 { + return None; + } + if ch & 0x40 != 0 { + loop { + if len == 0 { + return None; + } + let p = data[pos] as usize; + pos += 1; + len -= 1; + let tmp = if p == 255 { 254 } else { p }; + len = len.checked_sub(tmp)?; + pad += tmp; + if p != 255 { + break; + } + } + } + cbr = ch & 0x80 == 0; + if !cbr { + last_size = len; + for slot in &mut sizes[..count - 1] { + let (bytes, size) = parse_size(data.get(pos..pos.checked_add(len)?)?)?; + len = len.checked_sub(bytes)?; + if size as usize > len { + return None; + } + *slot = size; + pos += bytes; + last_size = last_size.checked_sub(bytes + size as usize)?; + } + } + count + } + }; + + let (bytes, size) = parse_size(data.get(pos..pos.checked_add(len)?)?)?; + len = len.checked_sub(bytes)?; + if size as usize > len { + return None; + } + sizes[count - 1] = size; + pos += bytes; + if cbr { + if size as usize * count > len { + return None; + } + for slot in &mut sizes[..count - 1] { + *slot = size; + } + } else if bytes + size as usize > last_size { + return None; + } + + for &frame in &sizes[..count] { + pos = pos.checked_add(frame as usize)?; + if pos > data.len() { + return None; + } + } + let offset = pad.checked_add(pos)?; + if offset == 0 || offset > data.len() { + return None; + } + let silent = sizes[..count].iter().all(|&frame| frame == 0); + Some((silent, offset)) +} + +/// The self-delimited length prefix (RFC 6716 §3.2.5), or `None` when it is cut off. +fn parse_size(data: &[u8]) -> Option<(usize, i32)> { + let first = *data.first()?; + if first < 252 { + Some((1, i32::from(first))) + } else { + let second = *data.get(1)?; + Some((2, 4 * i32::from(second) + i32::from(first))) + } +} + /// Whether the sender coded no audio at all for this packet: a bare TOC whose /// every frame is empty. /// @@ -196,6 +352,38 @@ mod tests { assert_eq!(activity(&[], false), Activity::Active); } + /// A surround packet is one self-delimited Opus packet per stream, then a + /// normal packet for the last. DTX is all of them empty; one coded frame is + /// audio. Parsing the buffer as a single stream would read the later + /// subpackets as that frame's payload. + #[test] + fn multistream_activity_requires_every_stream_empty() { + // 5.1: two coupled streams, then two mono. Code 0, empty frame. + let dtx = [0xfc, 0x00, 0xfc, 0x00, 0xf8, 0x00, 0xf8]; + assert_eq!(multistream_activity(&dtx, 4, false), Activity::Dtx); + // A coded frame on the last stream. + let last = [0xfc, 0x00, 0xfc, 0x00, 0xf8, 0x00, 0xf8, 0xaa]; + assert_eq!(multistream_activity(&last, 4, false), Activity::Active); + // A coded frame on an earlier stream. The length byte is the payload size. + let early = [0xfc, 0x01, 0xaa, 0xfc, 0x00, 0xf8, 0x00, 0xf8]; + assert_eq!(multistream_activity(&early, 4, false), Activity::Active); + // Two empty frames in one self-delimited code-1 packet, then a bare TOC. + let cbr = [0xf9, 0x00, 0xf8]; + assert_eq!(multistream_activity(&cbr, 2, false), Activity::Dtx); + let cbr_payload = [0xf9, 0x01, 0xaa, 0xbb, 0xf8]; + assert_eq!(multistream_activity(&cbr_payload, 2, false), Activity::Active); + // Code 3 packs the 60 ms case: three empty frames, self-delimited, then a bare TOC. + let code3 = [0xfb, 0x03, 0x00, 0xf8]; + assert_eq!(multistream_activity(&code3, 2, false), Activity::Dtx); + let code3_payload = [0xfb, 0x03, 0x01, 0xaa, 0xbb, 0xcc, 0xf8]; + assert_eq!(multistream_activity(&code3_payload, 2, false), Activity::Active); + // Loss still carries the previous classification, whatever the layout. + assert_eq!(multistream_activity(&[], 4, true), Activity::Dtx); + assert_eq!(multistream_activity(&[], 4, false), Activity::Active); + // One stream is an ordinary packet. + assert_eq!(multistream_activity(&[0xf8], 1, false), Activity::Dtx); + } + /// A silence run's periodic refresh is an ordinarily coded frame, and a /// speech onset can leave an earlier frame of the same packet empty. Neither /// is distinguishable by framing, so both read active rather than risking diff --git a/rs/moq-audio/src/playback.rs b/rs/moq-audio/src/playback.rs index 49e81de3546..1f5e514a683 100644 --- a/rs/moq-audio/src/playback.rs +++ b/rs/moq-audio/src/playback.rs @@ -50,7 +50,7 @@ pub use sink::{Control, Input, Sink, Write}; #[cfg(feature = "aec")] pub(crate) use driver::Shared; #[cfg(feature = "aec")] -pub(crate) use mixer::BUS_CHANNELS; +pub(crate) use mixer::REFERENCE_CHANNELS; use crate::Error; @@ -137,13 +137,14 @@ impl Engine { /// Add a stream to the mix, taking PCM in the layout `input` describes. /// /// Independent of the device: several sinks can play at different rates and - /// channel counts, and each is resampled on its way to the mix. One device + /// layouts, and each is resampled and remixed to the device's on its way to + /// the mix. One device /// mixes up to 64 of them, past which this returns an error rather than /// handing back a sink that plays nothing. pub fn sink(&self, input: Input) -> Result { let sink = self .shared - .add(|id, rate| sink::new(id, rate, input, self.shared.clone(), self.handle.clone()))?; + .add(|id, rate, bus| sink::new(id, rate, bus, input, self.shared.clone(), self.handle.clone()))?; // Covers the case where the mixer's command queue was momentarily full, // so a sink is never left silently unmixed. diff --git a/rs/moq-audio/src/playback/device.rs b/rs/moq-audio/src/playback/device.rs index 8d55a28a42e..680e6a80f7b 100644 --- a/rs/moq-audio/src/playback/device.rs +++ b/rs/moq-audio/src/playback/device.rs @@ -11,10 +11,9 @@ use crate::Error; /// second choice. const RATES: &[u32] = &[48_000, 44_100]; -/// Channel counts to try, best first. The mixer produces stereo, and mono is -/// the only other count worth naming: anything else is a surround layout we -/// would be guessing the speaker order of. -const CHANNELS: &[u16] = &[2, 1]; +/// The widest channel count with a well-known layout. Wider counts name no +/// speaker positions to mix into, so they are never opened. +const MAX_CHANNELS: u16 = 8; /// Sample formats we can write, best first: `f32` is what the mixer produces, /// and the rest are conversions on the way out. @@ -129,16 +128,24 @@ pub(super) fn open(selector: Option<&str>) -> Result { /// Pick the stream format to open `device` with. /// -/// Only considers formats in [`FORMATS`], and prefers in that order: a channel -/// count in [`CHANNELS`], a rate the pipeline already runs at, then a format we -/// write without converting. Failing all of those it takes the highest rate the -/// device supports, since resampling down is kinder than resampling up. +/// Only considers formats in [`FORMATS`] and well-known layouts, and prefers in +/// that order: the device's own channel count, the widest layout, a rate the +/// pipeline already runs at, then a format we write without converting. Failing +/// the rates it takes the highest the device supports, since resampling down is +/// kinder than resampling up. pub(super) fn negotiate(device: &cpal::Device) -> Result { let supported = device .supported_output_configs() .map_err(|err| Error::Playback(format!("cannot enumerate output configs: {err}")))?; - choose(supported).ok_or_else(|| Error::Unsupported("output device offers no sample format we can write".into())) + // What the device is set up for: a 5.1 HDMI sink reports six channels and a + // headset two. Taken first because a sound server's plugin also accepts + // every count up to its limit, where the widest would upmix a headset. + let native = device.default_output_config().ok().map(|config| config.channels()); + + choose(supported, native).ok_or_else(|| { + Error::Unsupported("output device offers no sample format and speaker layout we can write".into()) + }) } /// Pick the best of the stream configurations a device reports. @@ -146,10 +153,14 @@ pub(super) fn negotiate(device: &cpal::Device) -> Result) -> Option { +fn choose( + supported: impl Iterator, + native: Option, +) -> Option { supported .filter(|config| FORMATS.contains(&config.sample_format())) - .min_by_key(preference) + .filter(|config| (1..=MAX_CHANNELS).contains(&config.channels())) + .min_by_key(|config| preference(config, native)) .map(|config| match preferred_rate(&config) { Some(rate) => config.try_with_sample_rate(rate).expect("a rate the range covers"), None => config.with_max_sample_rate(), @@ -164,11 +175,11 @@ fn choose(supported: impl Iterator) -> /// and a pass per channel count that gave up when neither preferred rate matched /// would hand that to the mono device and downmix. The channel count leads /// because a downmix is audible where a resample is not. -fn preference(config: &cpal::SupportedStreamConfigRange) -> (usize, usize, std::cmp::Reverse, usize) { - let channels = CHANNELS - .iter() - .position(|count| *count == config.channels()) - .unwrap_or(CHANNELS.len()); +fn preference( + config: &cpal::SupportedStreamConfigRange, + native: Option, +) -> ((bool, std::cmp::Reverse), usize, std::cmp::Reverse, usize) { + let channels = (native != Some(config.channels()), std::cmp::Reverse(config.channels())); let rate = match preferred_rate(config) { Some(rate) => (RATES.iter().position(|r| *r == rate).expect("from RATES"), rate), // Nothing we asked for, so take the most the device offers: resampling @@ -223,33 +234,72 @@ mod tests { /// the way to a stereo sink. #[test] fn stereo_wins_even_when_the_device_lists_mono_first() { - let chosen = choose([range(1, 48_000, SampleFormat::F32), range(2, 48_000, SampleFormat::F32)].into_iter()) - .expect("a config"); + let chosen = choose( + [range(1, 48_000, SampleFormat::F32), range(2, 48_000, SampleFormat::F32)].into_iter(), + None, + ) + .expect("a config"); assert_eq!(chosen.channels(), 2); } /// Preferring stereo must not refuse a device that has no stereo to offer. #[test] fn mono_is_taken_when_that_is_all_there_is() { - let chosen = choose([range(1, 48_000, SampleFormat::F32)].into_iter()).expect("a config"); + let chosen = choose([range(1, 48_000, SampleFormat::F32)].into_iter(), None).expect("a config"); assert_eq!(chosen.channels(), 1); } - /// Neither preferred count is offered, so the pass that accepts any count - /// has to catch it. Without it a surround-only sink would not open at all. + /// A surround-only sink opens at its own width rather than being refused. #[test] - fn a_count_we_do_not_prefer_still_opens() { - let chosen = choose([range(6, 48_000, SampleFormat::F32)].into_iter()).expect("a config"); + fn a_surround_only_device_opens() { + let chosen = choose([range(6, 48_000, SampleFormat::F32)].into_iter(), None).expect("a config"); assert_eq!(chosen.channels(), 6); } + /// A 5.1 HDMI sink opens at six channels rather than being folded to stereo. + #[test] + fn six_channels_are_chosen_when_offered() { + let offered = || [range(2, 48_000, SampleFormat::F32), range(6, 48_000, SampleFormat::F32)].into_iter(); + assert_eq!(choose(offered(), None).expect("a config").channels(), 6); + assert_eq!(choose(offered(), Some(6)).expect("a config").channels(), 6); + } + + /// A sound server's plugin accepts every count up to its limit, so the + /// device's own count beats the widest: a headset stays at two rather than + /// being upmixed to 7.1 and folded back down by the server. + #[test] + fn the_native_count_beats_the_widest() { + let offered = (1..=8).map(|channels| range(channels, 48_000, SampleFormat::F32)); + assert_eq!(choose(offered, Some(2)).expect("a config").channels(), 2); + } + + /// Past 7.1 there is no convention naming the speakers, so there is nothing + /// to remix into. + #[test] + fn counts_without_a_layout_are_refused() { + assert!(choose([range(12, 48_000, SampleFormat::F32)].into_iter(), Some(12)).is_none()); + let chosen = choose( + [ + range(12, 48_000, SampleFormat::F32), + range(2, 48_000, SampleFormat::F32), + ] + .into_iter(), + Some(12), + ) + .expect("a config"); + assert_eq!(chosen.channels(), 2); + } + /// Rate is preferred within a channel count, not across one: a stereo config /// at an awkward rate beats a mono config at the pipeline's own rate, /// because resampling is inaudible and a downmix is not. #[test] fn channels_outrank_the_sample_rate() { - let chosen = choose([range(1, 48_000, SampleFormat::F32), range(2, 44_100, SampleFormat::F32)].into_iter()) - .expect("a config"); + let chosen = choose( + [range(1, 48_000, SampleFormat::F32), range(2, 44_100, SampleFormat::F32)].into_iter(), + None, + ) + .expect("a config"); assert_eq!((chosen.channels(), chosen.sample_rate()), (2, 44_100)); } @@ -257,8 +307,11 @@ mod tests { /// produces rather than one that costs a conversion. #[test] fn f32_is_preferred_over_a_format_we_convert_to() { - let chosen = choose([range(2, 48_000, SampleFormat::I16), range(2, 48_000, SampleFormat::F32)].into_iter()) - .expect("a config"); + let chosen = choose( + [range(2, 48_000, SampleFormat::I16), range(2, 48_000, SampleFormat::F32)].into_iter(), + None, + ) + .expect("a config"); assert_eq!(chosen.sample_format(), SampleFormat::F32); } @@ -266,8 +319,8 @@ mod tests { /// stream that plays noise. #[test] fn a_device_we_cannot_write_to_is_rejected() { - assert!(choose([range(2, 48_000, SampleFormat::I8)].into_iter()).is_none()); - assert!(choose(std::iter::empty()).is_none()); + assert!(choose([range(2, 48_000, SampleFormat::I8)].into_iter(), None).is_none()); + assert!(choose(std::iter::empty(), None).is_none()); } /// Channels lead even when neither preferred rate is on offer. @@ -278,8 +331,11 @@ mod tests { /// downmix the whole preference exists to avoid. #[test] fn stereo_at_an_awkward_rate_beats_mono_at_a_preferred_one() { - let chosen = choose([range(1, 48_000, SampleFormat::F32), range(2, 96_000, SampleFormat::F32)].into_iter()) - .expect("a config"); + let chosen = choose( + [range(1, 48_000, SampleFormat::F32), range(2, 96_000, SampleFormat::F32)].into_iter(), + None, + ) + .expect("a config"); assert_eq!((chosen.channels(), chosen.sample_rate()), (2, 96_000)); } @@ -293,6 +349,7 @@ mod tests { range(2, 96_000, SampleFormat::F32), ] .into_iter(), + None, ) .expect("a config"); assert_eq!((chosen.channels(), chosen.sample_rate()), (2, 96_000)); @@ -309,6 +366,7 @@ mod tests { range(2, 32_000, SampleFormat::F32), ] .into_iter(), + None, ) .expect("a config"); assert_eq!( diff --git a/rs/moq-audio/src/playback/driver.rs b/rs/moq-audio/src/playback/driver.rs index ce30e3688df..12bbd70fa5e 100644 --- a/rs/moq-audio/src/playback/driver.rs +++ b/rs/moq-audio/src/playback/driver.rs @@ -19,7 +19,7 @@ use rand::RngExt; use super::mixer::{self, Mixer}; use super::sink::{Registration, Sink}; -use crate::Error; +use crate::{Error, Layout}; /// Backoff bounds for reopening a device that failed. The first retry is quick because the common /// case is a device that came right back (a USB re-enumerate, a sample-rate change); the ceiling @@ -78,6 +78,9 @@ struct State { /// Rate the device is running at, which is what sinks resample to. Zero /// until the first stream opens. rate: u32, + /// Layout the device is running in, which is what sinks remix to. Stereo + /// stands in until the first stream opens. + layout: Layout, /// Registration channel to the live mixer, replaced every time the stream is /// rebuilt. `None` while no stream is running. mixer: Option>, @@ -108,13 +111,14 @@ struct State { impl Shared { /// Build a sink, register it, and start mixing it. /// - /// `build` is handed the sink's id and the rate its channel should target. + /// `build` is handed the sink's id and the rate and layout its channel should + /// target. /// It runs with no device open too: the registration waits for the next /// restart, so a device that is briefly missing doesn't become an error the /// caller has to retry. pub(super) fn add(&self, build: F) -> Result where - F: FnOnce(u64, u32) -> Result<(Sink, Registration), Error>, + F: FnOnce(u64, u32, Layout) -> Result<(Sink, Registration), Error>, { let mut state = self.state.lock().unwrap(); @@ -131,7 +135,7 @@ impl Shared { // 48 kHz stands in until a device opens and the channel is rebuilt at // the real rate. let rate = if state.rate == 0 { 48_000 } else { state.rate }; - let (sink, mut registration) = build(state.next_id, rate)?; + let (sink, mut registration) = build(state.next_id, rate, state.layout)?; state.next_id += 1; if let Some(mixer) = &state.mixer { @@ -270,11 +274,11 @@ impl Shared { } /// Point every sink at a freshly opened stream: rebuild each channel at - /// `rate` and hand the new consumers to `mixer`. - fn rebind(&self, rate: u32, mixer: SyncSender) { + /// `rate` and `layout` and hand the new consumers to `mixer`. + fn rebind(&self, rate: u32, layout: Layout, mixer: SyncSender) { let mut state = self.state.lock().unwrap(); for sink in &mut state.sinks { - sink.rebuild(rate); + sink.rebuild(rate, layout); sink.attach(&mixer); } @@ -289,6 +293,7 @@ impl Shared { } state.rate = rate; + state.layout = layout; state.mixer = Some(mixer); // The old mixer is gone, and with it every sink it was told about. state.detaching.clear(); @@ -787,7 +792,8 @@ impl Driver { // a full retirement channel is the one case where the mixer has to free // on the audio thread after all. let (retired_tx, retired_rx) = sync_channel(COMMAND_QUEUE); - let mixer = Mixer::new(rx, retired_tx, rate, channels); + let layout = Layout::from_channels(channels as u32)?; + let mixer = Mixer::new(rx, retired_tx, rate, layout)?; let failures = Arc::new(Failures::default()); let reporter = FailureReporter { @@ -799,7 +805,7 @@ impl Driver { .play() .map_err(|err| Error::Playback(format!("cannot start output stream: {err}")))?; - self.shared.rebind(rate, tx); + self.shared.rebind(rate, layout, tx); self.stream = Some(stream); self.failures = Some(failures); // Replaces the previous receiver, dropping anything the old stream @@ -807,7 +813,7 @@ impl Driver { self.retired = Some(retired_rx); self.retry = RETRY_MIN; - tracing::info!(rate, channels, ?format, "opened audio output"); + tracing::info!(rate, ?layout, ?format, "opened audio output"); Ok(()) } @@ -1005,7 +1011,7 @@ mod tests { let handle = Arc::new(super::super::Handle { commands }); let (tx, mixer) = sync_channel(depth); - shared.rebind(48_000, tx); + shared.rebind(48_000, Layout::Stereo, tx); Wired { shared, @@ -1016,7 +1022,7 @@ mod tests { } fn add(shared: &Arc, handle: &Arc) -> Result { - shared.add(|id, rate| sink::new(id, rate, Input::default(), shared.clone(), handle.clone())) + shared.add(|id, rate, bus| sink::new(id, rate, bus, Input::default(), shared.clone(), handle.clone())) } /// Long enough that only a lost wake, rather than a loaded machine, trips a diff --git a/rs/moq-audio/src/playback/mixer.rs b/rs/moq-audio/src/playback/mixer.rs index d3f23124e37..6187f2ca9ae 100644 --- a/rs/moq-audio/src/playback/mixer.rs +++ b/rs/moq-audio/src/playback/mixer.rs @@ -19,6 +19,10 @@ use fixed_resample::ResamplingCons; #[cfg(feature = "aec")] use fixed_resample::ResamplingProd; +#[cfg(feature = "aec")] +use crate::resample::Remix; +use crate::{Error, Layout}; + /// Frames mixed per pass. The callback buffer is chunked to this so the scratch /// buffers stay a fixed size no matter what period the device asks for. const CHUNK: usize = 1024; @@ -27,9 +31,10 @@ const CHUNK: usize = 1024; /// inaudible as a click, short enough to feel instant. const RAMP: f32 = 0.003; -/// The mix bus is stereo: sinks resample into it and it fans out to however many -/// channels the device wants. -pub(crate) const BUS_CHANNELS: usize = 2; +/// The echo reference is the mix downmixed to stereo, whatever layout the +/// device plays, so the canceller's model survives a device switch. +#[cfg(feature = "aec")] +pub(crate) const REFERENCE_CHANNELS: usize = 2; /// Sinks one device will mix. The entry list is allocated to this up front and /// never grows, which is what keeps registration off the allocator. @@ -138,36 +143,61 @@ pub(super) struct Mixer { /// Where anything the mixer is done with goes to be dropped, since dropping /// it here would free on the audio thread. retired: SyncSender, - /// Channels the device takes. + /// Channels the device takes, which is also the bus layout's: every sink + /// remixes into it on its way here. channels: usize, /// Per-frame gain step, so any change spans [`RAMP`] regardless of rate. step: f32, - /// Stereo accumulator for one chunk. + /// Accumulator for one chunk, in the device's layout. bus: Vec, - /// Stereo scratch for the sink being read. + /// Scratch for the sink being read, in the device's layout. scratch: Vec, - /// Where echo cancellation reads what was played. Fed the mix after - /// clipping but before it fans out, since that is the signal the speaker - /// gets and therefore the one the microphone hears back. + /// Where echo cancellation reads what was played. Fed the clipped mix, since + /// that is the signal the speaker gets and therefore the one the microphone + /// hears back. #[cfg(feature = "aec")] reference: Option>, + /// Downmixes the bus to the reference's stereo. + #[cfg(feature = "aec")] + downmix: Remix, + /// Stereo scratch for the downmixed reference. + #[cfg(feature = "aec")] + stereo: Vec, } impl Mixer { - /// `rate` and `channels` describe the device, not the sinks: each sink - /// resamples into the bus on its way here. - pub(super) fn new(commands: Receiver, retired: SyncSender, rate: u32, channels: usize) -> Self { - Self { + /// `rate` and `layout` describe the device, not the sinks: each sink + /// resamples and remixes into the bus on its way here. + pub(super) fn new( + commands: Receiver, + retired: SyncSender, + rate: u32, + layout: Layout, + ) -> Result { + // Sinks remix by speaker position, so a bus without any has nothing to + // remix into. + if layout.speakers().is_none() { + return Err(Error::Unsupported(format!( + "cannot mix into an output without speaker positions ({layout:?})" + ))); + } + + let channels = layout.channels() as usize; + Ok(Self { entries: Vec::with_capacity(MAX_SINKS), commands, retired, channels, step: 1.0 / (rate as f32 * RAMP), - bus: vec![0.0; CHUNK * BUS_CHANNELS], - scratch: vec![0.0; CHUNK * BUS_CHANNELS], + bus: vec![0.0; CHUNK * channels], + scratch: vec![0.0; CHUNK * channels], #[cfg(feature = "aec")] reference: None, - } + #[cfg(feature = "aec")] + downmix: Remix::new(layout, Layout::Stereo)?, + #[cfg(feature = "aec")] + stereo: vec![0.0; CHUNK * REFERENCE_CHANNELS], + }) } /// Hand something the mixer is done with back to the driver to drop. @@ -234,6 +264,10 @@ impl Mixer { scratch, #[cfg(feature = "aec")] reference, + #[cfg(feature = "aec")] + downmix, + #[cfg(feature = "aec")] + stereo, .. } = self; let channels = *channels; @@ -242,7 +276,7 @@ impl Mixer { let mut done = 0; while done < total { let frames = (total - done).min(CHUNK); - let samples = frames * BUS_CHANNELS; + let samples = frames * channels; bus[..samples].fill(0.0); @@ -257,13 +291,16 @@ impl Mixer { let mut applied = entry.applied; let mut peak = 0.0f32; - for frame in 0..frames { + for (input, mixed) in scratch[..samples] + .chunks_exact(channels) + .zip(bus[..samples].chunks_exact_mut(channels)) + { applied += (target - applied).clamp(-*step, *step); - let left = scratch[frame * 2] * applied; - let right = scratch[frame * 2 + 1] * applied; - peak = peak.max(left.abs()).max(right.abs()); - bus[frame * 2] += left; - bus[frame * 2 + 1] += right; + for (input, mixed) in input.iter().zip(mixed) { + let sample = input * applied; + peak = peak.max(sample.abs()); + *mixed += sample; + } } entry.applied = applied; @@ -280,26 +317,12 @@ impl Mixer { // useful to do about it from here and nothing may be logged. #[cfg(feature = "aec")] if let Some(reference) = reference.as_mut() { - reference.push_interleaved(&bus[..samples]); + let stereo = &mut stereo[..frames * REFERENCE_CHANNELS]; + downmix.apply(&bus[..samples], stereo); + reference.push_interleaved(stereo); } - let out = &mut out[done * channels..(done + frames) * channels]; - match channels { - 1 => { - for (frame, out) in out.iter_mut().enumerate() { - *out = (bus[frame * 2] + bus[frame * 2 + 1]) * 0.5; - } - } - _ => { - for (frame, out) in out.chunks_exact_mut(channels).enumerate() { - out[0] = bus[frame * 2]; - out[1] = bus[frame * 2 + 1]; - // Surround devices get silence past the front pair, which - // is better than duplicating stereo into the rears. - out[2..].fill(0.0); - } - } - } + out[done * channels..(done + frames) * channels].copy_from_slice(&bus[..samples]); done += frames; } @@ -316,6 +339,9 @@ mod tests { const RATE: u32 = 48_000; + /// The bus most tests mix into. + const STEREO: usize = 2; + /// Frames pushed per test: a tenth of a second, far more than any `fill` /// below drains, so a short read never starves by accident. const FRAMES: usize = RATE as usize / 10; @@ -328,21 +354,23 @@ mod tests { /// audio thread never drops one. retired: Receiver, next: u64, + channels: usize, } impl Harness { - fn new(channels: usize) -> Self { - Self::with_depth(channels, 8) + fn new(layout: Layout) -> Self { + Self::with_depth(layout, 8) } - fn with_depth(channels: usize, depth: usize) -> Self { + fn with_depth(layout: Layout, depth: usize) -> Self { let (commands, rx) = sync_channel(depth); let (retired_tx, retired) = sync_channel(MAX_SINKS); Self { - mixer: Mixer::new(rx, retired_tx, RATE, channels), + mixer: Mixer::new(rx, retired_tx, RATE, layout).unwrap(), commands, retired, next: 0, + channels: layout.channels() as usize, } } @@ -352,7 +380,7 @@ mod tests { /// pushed samples and the assertions. fn add(&mut self, gain: Arc) -> (u64, ResamplingProd) { let (prod, cons) = resampling_channel::( - BUS_CHANNELS, + self.channels, RATE, RATE, true, @@ -389,12 +417,12 @@ mod tests { /// Push `frames` stereo frames of a constant sample. fn push(prod: &mut ResamplingProd, value: f32, frames: usize) { - prod.push_interleaved(&vec![value; frames * BUS_CHANNELS]); + prod.push_interleaved(&vec![value; frames * STEREO]); } #[test] fn discards_writes_until_the_device_reads() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let (_, mut prod) = harness.add(Arc::new(Gain::new())); // Nothing has read yet, so these samples are dropped rather than queued @@ -411,7 +439,7 @@ mod tests { #[test] fn sums_sinks_and_clips() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let mut out = vec![0.0f32; 2048]; // Three sinks at 0.5 sum to 1.5, which must clip to 1.0. @@ -433,7 +461,7 @@ mod tests { #[test] fn volume_ramps_instead_of_stepping() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let mut out = vec![0.0f32; 2048]; let gain = Arc::new(Gain::new()); @@ -453,8 +481,8 @@ mod tests { // The whole ramp is monotonic, not just its endpoints. let ramp = (RATE as f32 * RAMP) as usize; assert!(ramp < out.len() / 2, "test buffer is shorter than the ramp"); - for frame in out[..ramp * BUS_CHANNELS] - .as_chunks::() + for frame in out[..ramp * STEREO] + .as_chunks::() .0 .iter() .collect::>() @@ -484,7 +512,7 @@ mod tests { /// device buffer into NaN. #[test] fn output_stays_finite_after_a_non_finite_volume() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let mut out = vec![0.0f32; 2048]; let gain = Arc::new(Gain::new()); @@ -500,7 +528,7 @@ mod tests { #[test] fn peak_reports_the_loudest_sample_then_resets() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let mut out = vec![0.0f32; 2048]; let gain = Arc::new(Gain::new()); @@ -517,7 +545,7 @@ mod tests { #[test] fn removed_sinks_stop_mixing() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let mut out = vec![0.0f32; 2048]; let (id, mut prod) = harness.add(Arc::new(Gain::new())); @@ -536,7 +564,7 @@ mod tests { /// callback would free on the audio thread, so it goes back to the driver. #[test] fn removed_sinks_are_handed_back_rather_than_dropped() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let mut out = vec![0.0f32; 512]; let (id, _prod) = harness.add(Arc::new(Gain::new())); @@ -561,7 +589,7 @@ mod tests { #[cfg(feature = "aec")] #[test] fn the_echo_reference_gets_the_mix() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let mut out = vec![0.0f32; 2048]; let (reference, mut tap) = reference_channel(); @@ -574,7 +602,7 @@ mod tests { // does, so that nothing queues up while nobody is listening. That first // read also primes the channel with its configured latency in silence, // which is why the buffer below is read past it rather than at it. - let mut heard = vec![0.0f32; 2048 * BUS_CHANNELS]; + let mut heard = vec![0.0f32; 2048 * REFERENCE_CHANNELS]; tap.read_interleaved(&mut heard, false); for prod in &mut prods { @@ -596,7 +624,7 @@ mod tests { #[cfg(feature = "aec")] #[test] fn a_replaced_echo_reference_is_handed_back() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let mut out = vec![0.0f32; 512]; harness @@ -629,7 +657,7 @@ mod tests { #[cfg(feature = "aec")] fn reference_channel() -> (ResamplingProd, ResamplingCons) { resampling_channel::( - BUS_CHANNELS, + REFERENCE_CHANNELS, RATE, RATE, true, @@ -645,7 +673,7 @@ mod tests { /// thread, which is why the driver caps registrations at MAX_SINKS. #[test] fn the_entry_list_never_grows() { - let mut harness = Harness::with_depth(2, MAX_SINKS); + let mut harness = Harness::with_depth(Layout::Stereo, MAX_SINKS); let mut out = vec![0.0f32; 512]; let capacity = harness.mixer.entries.capacity(); @@ -660,50 +688,65 @@ mod tests { #[test] fn silence_when_no_sink_is_registered() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let mut out = vec![1.0f32; 512]; harness.fill(&mut out); assert!(out.iter().all(|s| *s == 0.0), "callback buffer was not overwritten"); } + /// The bus is the device's own layout, so every speaker of a surround device + /// carries what the sinks put there rather than silence past the front pair. #[test] - fn mono_device_gets_the_stereo_average() { - let mut harness = Harness::new(1); - let mut out = vec![0.0f32; 1024]; + fn a_surround_bus_mixes_every_speaker() { + let mut harness = Harness::new(Layout::FivePointOne); + let mut out = vec![0.0f32; 6 * 512]; let (_, mut prod) = harness.add(Arc::new(Gain::new())); harness.fill(&mut out); - - // Hard left, so a mono device should hear half of it. - let mut samples = vec![0.0f32; FRAMES * BUS_CHANNELS]; - for frame in samples.as_chunks_mut::().0.iter_mut() { - frame[0] = 1.0; - } - prod.push_interleaved(&samples); + let frame = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6]; + prod.push_interleaved(&frame.repeat(FRAMES)); harness.settle(&mut out); - assert!((out[out.len() - 1] - 0.5).abs() < 1e-5, "got {}", out[out.len() - 1]); + + let last = &out[out.len() - 6..]; + for (got, want) in last.iter().zip(frame) { + assert!((got - want).abs() < 1e-5, "got {last:?}"); + } } + /// The canceller models a stereo reference whatever the device plays, so a + /// surround bus reaches it downmixed rather than cut to its front pair. + #[cfg(feature = "aec")] #[test] - fn surround_devices_get_silence_past_the_front_pair() { - let mut harness = Harness::new(6); - let mut out = vec![0.0f32; 6 * 512]; + fn the_echo_reference_downmixes_a_surround_bus() { + let mut harness = Harness::new(Layout::FivePointOne); + let mut out = vec![0.0f32; 6 * 2048]; + let (reference, mut tap) = reference_channel(); + harness.commands.send(Command::Reference(Some(reference))).unwrap(); let (_, mut prod) = harness.add(Arc::new(Gain::new())); harness.fill(&mut out); - push(&mut prod, 1.0, FRAMES); + let mut heard = vec![0.0f32; 2048 * REFERENCE_CHANNELS]; + tap.read_interleaved(&mut heard, false); + + // Center only, which a stereo downmix splits evenly at -3 dB. + prod.push_interleaved(&[0.0, 0.0, 0.5, 0.0, 0.0, 0.0].repeat(FRAMES)); harness.settle(&mut out); + tap.read_interleaved(&mut heard, false); - let last = &out[out.len() - 6..]; - assert!(last[0] > 0.9 && last[1] > 0.9, "front pair was silent"); - assert!(last[2..].iter().all(|s| *s == 0.0), "rear channels were not silent"); + let want = 0.5 * std::f32::consts::FRAC_1_SQRT_2; + let tail = &heard[heard.len() - 64..]; + assert!( + tail.iter().all(|s| (*s - want).abs() < 1e-5), + "the tap saw {:?}, not the downmix", + &tail[..4] + ); } #[test] fn underflow_reads_as_silence_rather_than_stale_samples() { - let mut harness = Harness::new(2); + let mut harness = Harness::new(Layout::Stereo); let mut out = vec![0.0f32; 8192]; let (_, mut prod) = harness.add(Arc::new(Gain::new())); diff --git a/rs/moq-audio/src/playback/sink.rs b/rs/moq-audio/src/playback/sink.rs index 41b8d0f79de..74bed20c192 100644 --- a/rs/moq-audio/src/playback/sink.rs +++ b/rs/moq-audio/src/playback/sink.rs @@ -1,6 +1,5 @@ //! [`Sink`]: one stream of PCM on its way to the speaker. -use std::borrow::Cow; use std::sync::mpsc::{SyncSender, TrySendError}; use std::sync::{Arc, Mutex}; use std::time::Duration; @@ -8,8 +7,8 @@ use std::time::Duration; use fixed_resample::{PushStatus, ResamplingChannelConfig, ResamplingCons, ResamplingProd, resampling_channel}; use super::driver::Shared; -use super::mixer::{self, BUS_CHANNELS, Gain}; -use crate::resample::remix; +use super::mixer::{self, Gain}; +use crate::resample::Remix; use crate::{Error, Format, Layout}; /// Default for [`Input::latency`]: audio buffered between [`Sink::write`] and @@ -28,7 +27,7 @@ const HEADROOM: f64 = 3.0; /// /// The playback counterpart to [`encode::Input`](crate::encode::Input): it /// describes the buffers you hand in, not the device, which is free to run at -/// its own rate and channel count. +/// its own rate and layout. /// /// `#[non_exhaustive]`: construct via [`Input::default`] and set fields, so new /// options can be added without breaking callers. @@ -40,7 +39,8 @@ pub struct Input { /// Samples per second per channel. Resampled to the device rate if they /// differ. pub sample_rate: u32, - /// Speaker meaning and channel order. + /// Speaker meaning and channel order. Remixed to the device's layout, so it + /// must name speaker positions rather than be [`Layout::Discrete`]. pub layout: Layout, /// How much audio to hold between [`Sink::write`] and the speaker (default: @@ -77,9 +77,9 @@ impl Input { if self.sample_rate == 0 { return Err(Error::Unsupported("sample rate must be > 0".into())); } - if !matches!(self.layout, Layout::Mono | Layout::Stereo) { + if self.layout.speakers().is_none() { return Err(Error::Unsupported(format!( - "playback accepts named mono or stereo input (got {:?})", + "playback needs speaker positions to remix (got {:?})", self.layout ))); } @@ -120,13 +120,13 @@ impl Write { /// One stream of PCM being played, mixed with every other sink on the device. /// /// Write decoded samples with [`write`](Self::write) and drop the sink to stop. -/// Writes are cheap and never block on the device: they hand samples to a ring -/// buffer that the audio thread drains on its own clock, resampling to the -/// device rate on the way. +/// Writes are cheap and never block on the device: they remix to the device's +/// layout and hand samples to a ring buffer that the audio thread drains on its +/// own clock, resampling to the device rate on the way. pub struct Sink { id: u64, input: Input, - prod: Arc>>, + channel: Arc>, control: Control, /// Whether the last write overflowed, so a writer that stays ahead of the /// device logs once rather than on every write. @@ -151,17 +151,21 @@ impl Sink { /// The returned [`Write`] counts input sample frames accepted and dropped; /// dropped live audio should be observed for telemetry, not retried. pub fn write(&mut self, samples: &[u8]) -> Result { - let pcm = self - .input - .format - .as_interleaved_f32(samples, self.input.layout.channels())?; - let pcm = match self.input.layout.channels() as usize { - BUS_CHANNELS => pcm, - _ => Cow::Owned(remix(&pcm, self.input.layout, Layout::Stereo)?), + let channels = self.input.layout.channels(); + let pcm = self.input.format.as_interleaved_f32(samples, channels)?; + let requested_sample_frames = pcm.len() / channels as usize; + + let mut channel = self.channel.lock().unwrap(); + let mixed; + let pcm = match &channel.remix { + Some(remix) => { + mixed = remix.process(&pcm); + &mixed + } + None => pcm.as_ref(), }; - let requested_sample_frames = pcm.len() / BUS_CHANNELS; - let accepted_sample_frames = match self.prod.lock().unwrap().push_interleaved(&pcm) { + let accepted_sample_frames = match channel.prod.push_interleaved(pcm) { // OutputNotReady means the device has not read yet, so these samples // are dropped rather than queued to play late. PushStatus::Ok => { @@ -201,7 +205,7 @@ impl Sink { /// climbs when the writer runs ahead, and falls toward zero when it falls /// behind. pub fn buffered(&self) -> Duration { - Duration::from_secs_f64(self.prod.lock().unwrap().occupied_seconds().max(0.0)) + Duration::from_secs_f64(self.channel.lock().unwrap().prod.occupied_seconds().max(0.0)) } /// The PCM layout this sink was built with. @@ -278,15 +282,21 @@ impl Control { } } +/// The ring into the mixer and the remix that fills it, swapped together when +/// the device changes rate or layout. +struct Channel { + prod: ResamplingProd, + /// Converts the sink's layout to the device's, when they differ. + remix: Option, +} + /// A sink as the driver sees it: enough to rebuild its channel when the device /// changes underneath it. pub(super) struct Registration { pub(super) id: u64, - /// The caller's rate, which is the input side of the channel. - rate: u32, - /// The depth the rebuilt channel has to keep, from the caller's [`Input`]. - latency: Duration, - prod: Arc>>, + /// The caller's rate, layout, and latency: the input side of the channel. + input: Input, + channel: Arc>, gain: Arc, /// The consumer waiting to be handed to a mixer. Taken once it is attached, /// and refilled by [`rebuild`](Self::rebuild). @@ -319,34 +329,36 @@ impl Registration { } } - /// Re-create the channel for a device now running at `rate`, swapping the - /// producer the caller's [`Sink`] writes into. - pub(super) fn rebuild(&mut self, rate: u32) { - let (prod, cons) = channel(self.rate, rate, self.latency); - *self.prod.lock().unwrap() = prod; + /// Re-create the channel for a device now running at `rate` in `bus`, + /// swapping the producer the caller's [`Sink`] writes into. + pub(super) fn rebuild(&mut self, rate: u32, bus: Layout) { + let (channel, cons) = channel(&self.input, rate, bus); + *self.channel.lock().unwrap() = channel; self.pending = Some(cons); } } /// Build a sink and its registration. The device may not be open yet, in which -/// case `rate` is a placeholder the driver replaces on the next rebuild. +/// case `rate` and `bus` are placeholders the driver replaces on the next +/// rebuild. pub(super) fn new( id: u64, rate: u32, + bus: Layout, input: Input, shared: Arc, engine: Arc, ) -> Result<(Sink, Registration), Error> { input.validate()?; - let (prod, cons) = channel(input.sample_rate, rate, input.latency); - let prod = Arc::new(Mutex::new(prod)); + let (channel, cons) = self::channel(&input, rate, bus); + let channel = Arc::new(Mutex::new(channel)); let gain = Arc::new(Gain::new()); let sink = Sink { id, input, - prod: prod.clone(), + channel: channel.clone(), control: Control { gain: gain.clone() }, overflowing: false, shared, @@ -355,9 +367,8 @@ pub(super) fn new( let registration = Registration { id, - rate: sink.input.sample_rate, - latency: sink.input.latency, - prod, + input: sink.input.clone(), + channel, gain, pending: Some(cons), }; @@ -365,14 +376,17 @@ pub(super) fn new( Ok((sink, registration)) } -/// The ring buffer between a writer and the audio thread, resampling the -/// caller's rate to the device's. -fn channel(from: u32, to: u32, latency: Duration) -> (ResamplingProd, ResamplingCons) { - let latency = latency.as_secs_f64(); - resampling_channel::( - BUS_CHANNELS, - from, - to, +/// The ring buffer between a writer and the audio thread, remixing the caller's +/// layout to the device's and resampling its rate to the device's. +fn channel(input: &Input, rate: u32, bus: Layout) -> (Channel, ResamplingCons) { + let remix = + (input.layout != bus).then(|| Remix::new(input.layout, bus).expect("sink and bus layouts name their speakers")); + + let latency = input.latency.as_secs_f64(); + let (prod, cons) = resampling_channel::( + bus.channels() as usize, + input.sample_rate, + rate, // We only ever push interleaved, which lets the channel skip its planar // staging buffer. true, @@ -385,7 +399,9 @@ fn channel(from: u32, to: u32, latency: Duration) -> (ResamplingProd, Resam overflow_autocorrect_percent_threshold: Some(75.0), ..Default::default() }, - ) + ); + + (Channel { prod, remix }, cons) } #[cfg(test)] @@ -393,20 +409,65 @@ mod tests { use super::*; fn sink(input: Input, output_rate: u32) -> (Sink, ResamplingCons) { + sink_into(input, output_rate, Layout::Stereo) + } + + fn sink_into(input: Input, output_rate: u32, bus: Layout) -> (Sink, ResamplingCons) { let shared = Arc::new(Shared::default()); let engine = Arc::new(super::super::Handle { commands: super::super::driver::Commands::default(), }); - let (sink, mut registration) = new(0, output_rate, input, shared, engine).unwrap(); + let (sink, mut registration) = new(0, output_rate, bus, input, shared, engine).unwrap(); (sink, registration.pending.take().unwrap()) } + /// Write `frame` repeated as `input` and read back what the bus got. + fn mix(input: Layout, bus: Layout, frame: &[f32]) -> Vec { + let input = Input { + layout: input, + ..Default::default() + }; + let (mut sink, mut cons) = sink_into(input, 48_000, bus); + let channels = bus.channels() as usize; + cons.read_interleaved(&mut vec![0.0; channels], false); + + let pcm: Vec = frame.repeat(4800).iter().flat_map(|s| s.to_le_bytes()).collect(); + assert_eq!(sink.write(&pcm).unwrap().dropped_sample_frames, 0); + + let mut out = vec![0.0; 4800 * channels]; + cons.read_interleaved(&mut out, false); + out[out.len() - channels..].to_vec() + } + + fn close(got: &[f32], want: &[f32]) { + assert_eq!(got.len(), want.len(), "{got:?} vs {want:?}"); + for (g, w) in got.iter().zip(want) { + assert!((g - w).abs() < 1e-4, "{got:?} vs {want:?}"); + } + } + + /// A 5.1 track on a stereo device plays its downmix, center and surrounds + /// folded into the front pair at -3 dB. + #[test] + fn a_surround_sink_downmixes_into_a_stereo_bus() { + let h = std::f32::consts::FRAC_1_SQRT_2; + let got = mix(Layout::FivePointOne, Layout::Stereo, &[0.1, 0.2, 0.3, 0.4, 0.05, 0.06]); + close(&got, &[0.1 + h * 0.3 + h * 0.05, 0.2 + h * 0.3 + h * 0.06]); + } + + /// A stereo track on a 5.1 device plays from the front pair alone. + #[test] + fn a_stereo_sink_fills_the_front_of_a_surround_bus() { + let got = mix(Layout::Stereo, Layout::FivePointOne, &[0.25, 0.75]); + close(&got, &[0.25, 0.75, 0.0, 0.0, 0.0, 0.0]); + } + fn s16(frames: usize, channels: usize) -> Vec { vec![0; frames * channels * 2] } fn ready(cons: &mut ResamplingCons) { - cons.read_interleaved(&mut [0.0; BUS_CHANNELS], false); + cons.read_interleaved(&mut [0.0; 2], false); } #[test] @@ -495,7 +556,7 @@ mod tests { #[test] fn rejects_layouts_it_cannot_mix() { - for layout in [Layout::Discrete(0), Layout::Discrete(6)] { + for layout in [Layout::Discrete(0), Layout::Discrete(2), Layout::Discrete(6)] { let input = Input { layout, ..Default::default() @@ -511,8 +572,13 @@ mod tests { } #[test] - fn accepts_mono_and_stereo() { - for layout in [Layout::Mono, Layout::Stereo] { + fn accepts_named_layouts() { + for layout in [ + Layout::Mono, + Layout::Stereo, + Layout::FivePointOne, + Layout::SevenPointOne, + ] { let input = Input { layout, ..Default::default() diff --git a/rs/moq-audio/src/resample.rs b/rs/moq-audio/src/resample.rs index 173a3b1ba27..402f0b85295 100644 --- a/rs/moq-audio/src/resample.rs +++ b/rs/moq-audio/src/resample.rs @@ -2,14 +2,17 @@ //! //! Wraps [`rubato`] with a small interleaved-`f32` interface so the //! producer/consumer doesn't have to convert to planar on every call. -//! The resampler keeps the channel layout unchanged; [`remix`] converts mono -//! and stereo after sample-rate conversion. +//! The resampler keeps the channel layout unchanged; [`Remix`] converts between +//! layouts after sample-rate conversion. + +use std::f32::consts::FRAC_1_SQRT_2; use rubato::audioadapter_buffers::direct::SequentialSliceOfVecs; use rubato::{ Async, FixedAsync, Resampler as RubatoTrait, SincInterpolationParameters, SincInterpolationType, WindowFunction, }; +use crate::layout::Speaker; use crate::{Error, Layout}; #[derive(Debug, thiserror::Error)] @@ -301,50 +304,147 @@ impl Resampler { } } -/// Convert between known layouts without assigning positions to discrete channels. -pub(crate) fn remix(samples: &[f32], input: Layout, output: Layout) -> Result, Error> { - validate_remix(input, output)?; - match (input, output) { - (input, output) if input == output => Ok(samples.to_vec()), - (Layout::Mono, Layout::Stereo) => { - let mut output = Vec::with_capacity(samples.len() * 2); - for &sample in samples { - output.extend_from_slice(&[sample, sample]); +/// A channel mix from one layout to another, each output channel a weighted sum +/// of the input channels. +/// +/// Refuses to give discrete channels speaker positions, though it will drop +/// them from named channels. +/// +/// Downmixing uses the ITU-R BS.775 coefficients: center and surrounds fold into +/// the front pair at -3 dB and the LFE is dropped. Upmixing leaves the speakers +/// the input lacks silent. Mono is the exception both ways: it plays at full +/// level from both front speakers when there is no center, and a mono output +/// averages the stereo downmix. +pub(crate) struct Remix { + inputs: usize, + outputs: usize, + /// One row of `inputs` weights per output channel. + weights: Vec, +} + +impl Remix { + pub(crate) fn new(input: Layout, output: Layout) -> Result { + input.validate()?; + output.validate()?; + + let (inputs, outputs) = (input.channels() as usize, output.channels() as usize); + // Dropping speaker positions is always safe; inventing them is not. + let unchanged = input == output || output == Layout::Discrete(inputs as u32); + let weights = match (input.speakers(), output.speakers()) { + _ if unchanged => (0..outputs) + .flat_map(|o| (0..inputs).map(move |i| if i == o { 1.0 } else { 0.0 })) + .collect(), + (Some(from), Some(to)) => weights(from, to), + _ => { + return Err(Error::Unsupported(format!( + "cannot convert audio layout {input:?} to {output:?} without speaker positions" + ))); + } + }; + + Ok(Self { + inputs, + outputs, + weights, + }) + } + + /// Mix whole interleaved input frames into `output`, which holds as many + /// frames. Never allocates, so the audio thread can call it. + pub(crate) fn apply(&self, input: &[f32], output: &mut [f32]) { + for (frame, out) in input + .chunks_exact(self.inputs) + .zip(output.chunks_exact_mut(self.outputs)) + { + for (sample, row) in out.iter_mut().zip(self.weights.chunks_exact(self.inputs)) { + *sample = row.iter().zip(frame).map(|(weight, input)| weight * input).sum(); } - Ok(output) } - (Layout::Stereo, Layout::Mono) => Ok(samples - .as_chunks::<2>() - .0 - .iter() - .map(|pair| (pair[0] + pair[1]) * 0.5) - .collect()), - _ => Err(Error::Unsupported(format!( - "cannot convert audio layout {input:?} to {output:?} without speaker positions" - ))), + } + + /// Mix whole interleaved input frames into a new buffer. + pub(crate) fn process(&self, input: &[f32]) -> Vec { + let mut output = vec![0.0; input.len() / self.inputs * self.outputs]; + self.apply(input, &mut output); + output } } -/// Check that [`remix`] can convert between two layouts. -pub(crate) fn validate_remix(input: Layout, output: Layout) -> Result<(), Error> { - input.validate()?; - output.validate()?; - if input == output - || matches!( - (input, output), - (Layout::Mono, Layout::Stereo) | (Layout::Stereo, Layout::Mono) - ) { - return Ok(()); - } - Err(Error::Unsupported(format!( - "cannot convert audio layout {input:?} to {output:?} without speaker positions" - ))) +/// The weights mixing `input` speakers into `output` speakers, one row per output. +fn weights(input: &[Speaker], output: &[Speaker]) -> Vec { + use Speaker::*; + + // The only layout without a front pair. Average the stereo downmix rather + // than invent a center weight for every speaker. + if output == [FrontCenter] && input != [FrontCenter] { + let stereo = weights(input, &[FrontLeft, FrontRight]); + let (left, right) = stereo.split_at(input.len()); + return left.iter().zip(right).map(|(l, r)| (l + r) * 0.5).collect(); + } + + let mut weights = vec![0.0; output.len() * input.len()]; + let has = |speaker| output.contains(&speaker); + + for (i, &speaker) in input.iter().enumerate() { + let mut feed = |to: Speaker, weight: f32| { + if let Some(o) = output.iter().position(|s| *s == to) { + weights[o * input.len() + i] += weight; + } + }; + + if has(speaker) { + feed(speaker, 1.0); + continue; + } + + match speaker { + FrontCenter => { + let weight = if input == [FrontCenter] { 1.0 } else { FRAC_1_SQRT_2 }; + feed(FrontLeft, weight); + feed(FrontRight, weight); + } + Lfe => {} + SideLeft | BackLeft | SideRight | BackRight => { + let (front, side, back) = match speaker { + SideLeft | BackLeft => (FrontLeft, SideLeft, BackLeft), + _ => (FrontRight, SideRight, BackRight), + }; + // Side and back are the same surround to a layout with only one of them. + let other = if speaker == side { back } else { side }; + if has(other) { + feed(other, 1.0); + } else { + feed(front, FRAC_1_SQRT_2); + } + } + BackCenter => { + if has(BackLeft) { + feed(BackLeft, FRAC_1_SQRT_2); + feed(BackRight, FRAC_1_SQRT_2); + } else if has(SideLeft) { + feed(SideLeft, FRAC_1_SQRT_2); + feed(SideRight, FRAC_1_SQRT_2); + } else { + feed(FrontLeft, 0.5); + feed(FrontRight, 0.5); + } + } + // Every output but mono, handled above, has a front pair. + FrontLeft | FrontRight => unreachable!("{output:?} has no front pair"), + } + } + + weights } #[cfg(test)] mod tests { use super::*; + fn remix(samples: &[f32], input: Layout, output: Layout) -> Result, Error> { + Ok(Remix::new(input, output)?.process(samples)) + } + /// `frames` into a stream at `rate`, as a timestamp in the source's own scale. fn at(frames: u64, rate: u64) -> moq_net::Timestamp { moq_net::Timestamp::from_scale(frames, rate).unwrap() @@ -548,4 +648,105 @@ mod tests { [2.0, 3.0] ); } + + /// One frame of 5.1 with a distinct level per speaker, in canonical order. + const FIVE_ONE: [f32; 6] = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6]; + + fn close(got: &[f32], want: &[f32]) { + assert_eq!(got.len(), want.len(), "{got:?} vs {want:?}"); + for (g, w) in got.iter().zip(want) { + assert!((g - w).abs() < 1e-6, "{got:?} vs {want:?}"); + } + } + + #[test] + fn remix_downmixes_five_one_to_stereo_by_bs775() { + let h = FRAC_1_SQRT_2; + let [l, r, c, _lfe, ls, rs] = FIVE_ONE; + close( + &remix(&FIVE_ONE, Layout::FivePointOne, Layout::Stereo).unwrap(), + &[l + h * c + h * ls, r + h * c + h * rs], + ); + } + + #[test] + fn remix_downmixes_five_one_to_mono_through_stereo() { + let stereo = remix(&FIVE_ONE, Layout::FivePointOne, Layout::Stereo).unwrap(); + close( + &remix(&FIVE_ONE, Layout::FivePointOne, Layout::Mono).unwrap(), + &[(stereo[0] + stereo[1]) * 0.5], + ); + } + + #[test] + fn remix_upmixes_stereo_into_the_front_pair() { + close( + &remix(&[0.25, 0.75], Layout::Stereo, Layout::FivePointOne).unwrap(), + &[0.25, 0.75, 0.0, 0.0, 0.0, 0.0], + ); + } + + #[test] + fn remix_upmixes_mono_into_the_center() { + close( + &remix(&[0.5], Layout::Mono, Layout::FivePointOne).unwrap(), + &[0.0, 0.0, 0.5, 0.0, 0.0, 0.0], + ); + // Quad has no center, so mono plays from both fronts as it does in stereo. + close( + &remix(&[0.5], Layout::Mono, Layout::Quad).unwrap(), + &[0.5, 0.5, 0.0, 0.0], + ); + } + + /// 7.1 to 5.1 folds the back pair into the sides at full level, since a 5.1 + /// surround pair is the only surround it has. + #[test] + fn remix_folds_back_into_side_surrounds() { + let seven = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]; + close( + &remix(&seven, Layout::SevenPointOne, Layout::FivePointOne).unwrap(), + &[0.1, 0.2, 0.3, 0.4, 0.5 + 0.7, 0.6 + 0.8], + ); + } + + #[test] + fn remix_refuses_positions_it_would_invent() { + for (input, output) in [ + (Layout::Discrete(6), Layout::Stereo), + (Layout::Mono, Layout::Discrete(2)), + (Layout::Discrete(0), Layout::Discrete(0)), + ] { + assert!( + matches!(Remix::new(input, output), Err(Error::Unsupported(_))), + "{input:?} -> {output:?}" + ); + } + + assert_eq!( + remix(&[1.0, 2.0, 3.0], Layout::Discrete(3), Layout::Discrete(3)).unwrap(), + [1.0, 2.0, 3.0] + ); + assert_eq!( + remix(&[1.0, 2.0, 3.0], Layout::TwoPointOne, Layout::Discrete(3)).unwrap(), + [1.0, 2.0, 3.0] + ); + assert!(Remix::new(Layout::Discrete(3), Layout::TwoPointOne).is_err()); + } + + /// Every pair of named layouts converts, and the mix is sized to the output. + #[test] + fn remix_converts_between_every_named_layout() { + let layouts: Vec = (1..=8) + .map(|n| Layout::from_channels(n).unwrap()) + .chain([Layout::ThreePointZero, Layout::FourPointZero]) + .collect(); + for &input in &layouts { + for &output in &layouts { + let frame = vec![0.5; input.channels() as usize * 2]; + let mixed = remix(&frame, input, output).unwrap(); + assert_eq!(mixed.len(), output.channels() as usize * 2, "{input:?} -> {output:?}"); + } + } + } } diff --git a/rs/moq-audio/tests/import.rs b/rs/moq-audio/tests/import.rs new file mode 100644 index 00000000000..010c1976c4e --- /dev/null +++ b/rs/moq-audio/tests/import.rs @@ -0,0 +1,64 @@ +//! Container imports that must decode end to end: a stream `moq-mux` imports +//! plays through [`decode::Consumer`] like the same stream from any container. + +use std::time::Duration; + +use moq_audio::{Format, Layout, decode}; + +/// MPEG-TS names surround Opus only by channel count, so the importer has to +/// synthesize the OpusHead mapping table or the decoder refuses the track. +#[tokio::test] +async fn ts_surround_opus_decodes() { + // A 440 Hz center channel in 5.1; see `import_opus_surround_catalog` in moq-mux. + let data = include_bytes!("../../moq-mux/src/container/ts/test_data/opus_5_1.ts"); + + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let broadcast_consumer = broadcast.consume(); + let catalog = moq_mux::catalog::Producer::new(&mut broadcast, moq_mux::catalog::Config::default()).unwrap(); + let mut import = moq_mux::container::ts::Import::new(broadcast, catalog.reserve()); + import.decode(&data[..]).unwrap(); + import.finish().unwrap(); + + let snapshot = catalog.snapshot(); + let (name, config) = snapshot.audio.renditions.iter().next().expect("an Opus track"); + + let mut options = decode::Options::default(); + options.output.format = Format::F32; + // The whole file is imported before anything decodes it. + options.max_age = Duration::from_secs(30); + let mut consumer = decode::Consumer::new(&broadcast_consumer, config, name, options) + .await + .unwrap(); + assert_eq!(consumer.layout(), Layout::FivePointOne); + + // Canonical 5.1 order: FL, FR, FC, LFE, SL, SR. + let mut energy = [0.0f64; 6]; + let mut frames = 0; + while let Some(frame) = tokio::time::timeout(Duration::from_secs(5), consumer.read()) + .await + .expect("decoded frame timed out") + .unwrap() + { + let (samples, rest) = frame.data.as_chunks::<4>(); + assert!(rest.is_empty()); + for chunk in samples.as_chunks::<6>().0 { + for (channel, sample) in energy.iter_mut().zip(chunk) { + *channel += f32::from_le_bytes(*sample).powi(2) as f64; + } + frames += 1; + } + } + + assert!(frames > 12_000, "expected most of 0.5 s at 48 kHz, got {frames} frames"); + let center = energy[2]; + assert!( + center / frames as f64 > 0.001, + "center should carry the tone: {energy:?}" + ); + for (channel, &other) in energy.iter().enumerate().filter(|&(channel, _)| channel != 2) { + assert!( + other < center / 100.0, + "channel {channel} should be near silent: {energy:?}" + ); + } +} diff --git a/rs/moq-audio/tests/roundtrip.rs b/rs/moq-audio/tests/roundtrip.rs index 570dacac45f..55e09bfab39 100644 --- a/rs/moq-audio/tests/roundtrip.rs +++ b/rs/moq-audio/tests/roundtrip.rs @@ -203,3 +203,71 @@ async fn pcm_round_trip_is_lossless() { assert_eq!(decoded, samples); assert!(consumer.read().await.unwrap().is_none()); } + +/// A 5.1 broadcast carries only its channel count in the catalog, which reads +/// back as 5.1 in canonical order and remixes to whatever the subscriber asks +/// for. +#[tokio::test] +async fn pcm_five_one_reads_back_at_any_layout() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let catalog = moq_mux::catalog::Producer::new(&mut broadcast, moq_mux::catalog::Config::default()).unwrap(); + let mut catalog_consumer = catalog.consume().unwrap(); + let broadcast_consumer = broadcast.consume(); + + let input = encode::Input::new(48_000, Layout::FivePointOne); + let mut options = encode::Options::default(); + options.track = Some("pcm".to_string()); + options.settings = encode::Settings::new(48_000, Layout::FivePointOne); + options.settings.codec = encode::Codec::Pcm; + + // A level per speaker: left, right, center, LFE, side left, side right. + let speakers = [0.1f32, 0.2, 0.3, 0.4, 0.05, 0.06]; + let mut producer = encode::Producer::new(&mut broadcast, catalog.clone(), input, &options).unwrap(); + producer + .write(&Frame::new( + f32_bytes(&speakers.repeat(960)), + Timestamp::from_micros(0).unwrap(), + )) + .unwrap(); + + let snapshot = catalog_consumer.next().await.unwrap().unwrap(); + let rendition = snapshot.audio.renditions.get("pcm").unwrap(); + assert_eq!(rendition.channel_count, 6); + + let h = std::f32::consts::FRAC_1_SQRT_2; + let left = 0.1 + h * 0.3 + h * 0.05; + let right = 0.2 + h * 0.3 + h * 0.06; + let cases = [ + (None, Layout::FivePointOne, speakers.to_vec()), + (Some(Layout::Stereo), Layout::Stereo, vec![left, right]), + (Some(Layout::Mono), Layout::Mono, vec![(left + right) * 0.5]), + ]; + + let mut consumers = Vec::new(); + for (output, _, _) in &cases { + let mut options = decode::Options::default(); + options.output.layout = *output; + consumers.push( + decode::Consumer::new(&broadcast_consumer, rendition, "pcm", options) + .await + .unwrap(), + ); + } + producer.finish().unwrap(); + + for (mut consumer, (_, layout, frame)) in consumers.into_iter().zip(cases) { + assert_eq!(consumer.layout(), layout); + let decoded = consumer.read().await.unwrap().unwrap(); + let samples: Vec = decoded + .data + .as_chunks::<4>() + .0 + .iter() + .map(|sample| f32::from_le_bytes([sample[0], sample[1], sample[2], sample[3]])) + .collect(); + assert_eq!(samples.len(), 960 * frame.len(), "{layout:?}"); + for (got, want) in samples.iter().zip(frame.iter().cycle()) { + assert!((got - want).abs() < 1e-6, "{layout:?}: got {got}, want {want}"); + } + } +} diff --git a/rs/moq-cli/src/play/media.rs b/rs/moq-cli/src/play/media.rs index fec8b15c9f4..9734e002834 100644 --- a/rs/moq-cli/src/play/media.rs +++ b/rs/moq-cli/src/play/media.rs @@ -234,7 +234,7 @@ impl Media { decode.output.format = moq_audio::Format::F32; match moq_audio::decode::Consumer::new(&rendition, &config, &name, decode).await { Ok(consumer) => { - tracing::info!(track = name, "playing audio rendition"); + tracing::info!(track = name, decoder = consumer.name(), "playing audio rendition"); if speaker.is_none() { speaker = Some(self.output.speaker().await?); } diff --git a/rs/moq-ffi/src/audio.rs b/rs/moq-ffi/src/audio.rs index 16750c1375e..22c3ba47428 100644 --- a/rs/moq-ffi/src/audio.rs +++ b/rs/moq-ffi/src/audio.rs @@ -48,7 +48,7 @@ impl From for moq_audio::Format { /// Audio codec selection for the encoder. /// /// An immutable object so adding a codec later does not break callers -/// switching over a closed enum. Currently only Opus is available. +/// switching over a closed enum. #[derive(uniffi::Object)] pub struct MoqAudioCodec { inner: moq_audio::encode::Codec, @@ -63,6 +63,16 @@ impl MoqAudioCodec { inner: moq_audio::encode::Codec::Opus, }) } + + /// AAC-LC (`mp4a.40.2`) through the platform's encoder, at the input's rate + /// and layout. A host without one refuses it when the producer is built. + /// Its frames are 1024 samples, so leave `frame_duration_us` at 0. + #[uniffi::constructor] + pub fn aac() -> Arc { + Arc::new(Self { + inner: moq_audio::encode::Codec::Aac, + }) + } } impl MoqAudioCodec { @@ -76,6 +86,9 @@ impl MoqAudioCodec { pub struct MoqAudioEncoderInput { pub format: MoqAudioSampleFormat, pub sample_rate: u32, + /// Interleaved channel count, which also names the speaker layout by the + /// WAVE convention: 1 mono, 2 stereo, 3 2.1, 4 quad, 5 5.0, 6 5.1, 7 6.1, + /// 8 7.1, in front left, front right, center, LFE, back, side order. pub channels: u32, } @@ -93,7 +106,7 @@ pub struct MoqAudioEncoderOutput { pub bitrate: Option, /// Encoded frame duration in microseconds. Opus accepts exactly /// 2500/5000/10000/20000/40000/60000 us, and the default 20 ms matches the - /// JS publish path. + /// JS publish path. 0 takes the codec's own frame, which AAC needs. #[uniffi(default = 20000)] pub frame_duration_us: u32, } @@ -105,7 +118,9 @@ pub struct MoqAudioDecoderOutput { /// `None` delivers samples at the codec's native rate. #[uniffi(default = None)] pub sample_rate: Option, - /// `None` delivers samples at the codec's native channel count. + /// `None` delivers samples at the codec's native channel count. A count + /// names its layout as [`MoqAudioEncoderInput::channels`] describes, and + /// the decoder remixes to it. #[uniffi(default = None)] pub channels: Option, /// Upper bound on buffering before skipping a stalled group, in @@ -285,7 +300,16 @@ impl MoqBroadcastProducer { options.settings.layout = moq_audio::Layout::from_channels(channels)?; } options.settings.bitrate = output.bitrate.map(|bps| moq_net::bandwidth::Rate::from_bps(bps.into())); - options.settings.frame_duration = Duration::from_micros(output.frame_duration_us.into()); + if output.frame_duration_us != 0 { + options.settings.frame_duration = Duration::from_micros(output.frame_duration_us.into()); + } else if output.codec.codec() == moq_audio::encode::Codec::Aac { + // from_input sized this at the input rate. The codec rate may be the + // override above, and AAC's own frame is 1024 samples of that rate. + let mut rated = input.clone(); + rated.sample_rate = options.settings.sample_rate; + options.settings.frame_duration = + moq_audio::encode::Settings::from_input(moq_audio::encode::Codec::Aac, &rated).frame_duration; + } if let Some(bandwidth) = &bandwidth { options.bandwidth = bandwidth.allocator().clone(); } diff --git a/rs/moq-ffi/src/binary.rs b/rs/moq-ffi/src/binary.rs index 3c231757f75..cf9e4000943 100644 --- a/rs/moq-ffi/src/binary.rs +++ b/rs/moq-ffi/src/binary.rs @@ -8,6 +8,7 @@ use std::sync::Arc; +use moq_mux::binary::Config; use moq_mux::catalog::hang::Extra; use crate::error::MoqError; @@ -25,9 +26,9 @@ pub struct MoqBinaryConfig { pub mime: Option, } -impl From for moq_mux::binary::Config { +impl From for Config { fn from(config: MoqBinaryConfig) -> Self { - let mut out = moq_mux::binary::Config::default().with_compression(config.compression); + let mut out = Config::default().with_compression(config.compression); if let Some(mime) = config.mime { out = out.with_mime(mime); } @@ -48,9 +49,7 @@ impl MoqBroadcastProducer { let _guard = crate::ffi::enter(); self.with_state(|state| { let track = state.broadcast.create_track(name, None)?; - let producer = state - .catalog - .binary_snapshot(track, moq_mux::binary::Config::from(config))?; + let producer = state.catalog.binary_snapshot(track, Config::from(config))?; Ok(Arc::new(MoqBinarySnapshotProducer { inner: std::sync::Mutex::new(Some(producer)), })) @@ -68,9 +67,7 @@ impl MoqBroadcastProducer { let _guard = crate::ffi::enter(); self.with_state(|state| { let track = state.broadcast.create_track(name, None)?; - let producer = state - .catalog - .binary_stream(track, moq_mux::binary::Config::from(config))?; + let producer = state.catalog.binary_stream(track, Config::from(config))?; Ok(Arc::new(MoqBinaryStreamProducer { inner: std::sync::Mutex::new(Some(producer)), })) diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 6e5fcf0bf55..f174a220fe6 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -512,6 +512,60 @@ async fn raw_audio_frame_durations() { broadcast.close().unwrap(); } +/// A frame duration of 0 takes the codec's own frame, and AAC, which encodes only +/// through a platform encoder, is refused where there is none. +#[cfg(feature = "audio")] +#[tokio::test] +async fn raw_audio_codec_default_frame() { + use crate::audio::*; + + let broadcast = MoqBroadcastProducer::new().unwrap(); + let input = || MoqAudioEncoderInput { + format: MoqAudioSampleFormat::F32, + sample_rate: 48_000, + channels: 2, + }; + let output = |codec| MoqAudioEncoderOutput { + codec, + sample_rate: None, + channels: None, + bitrate: None, + frame_duration_us: 0, + }; + + let opus = broadcast + .encode_audio("opus".into(), input(), output(MoqAudioCodec::opus()), None) + .unwrap(); + opus.finish().unwrap(); + + assert_eq!(MoqAudioCodec::aac().codec(), moq_audio::encode::Codec::Aac); + let aac = broadcast.encode_audio("aac".into(), input(), output(MoqAudioCodec::aac()), None); + let Err(MoqError::Audio(message)) = aac else { + panic!("no platform AAC encoder on this host"); + }; + assert!(message.contains("no aac audio encoder"), "{message}"); + + // 0 still means 1024 samples after an output-rate override, not the input rate. + let mut resampled = output(MoqAudioCodec::aac()); + resampled.sample_rate = Some(48_000); + let aac = broadcast.encode_audio( + "aac-rate".into(), + MoqAudioEncoderInput { + format: MoqAudioSampleFormat::F32, + sample_rate: 44_100, + channels: 2, + }, + resampled, + None, + ); + let Err(MoqError::Audio(message)) = aac else { + panic!("no platform AAC encoder on this host"); + }; + assert!(message.contains("no aac audio encoder"), "{message}"); + + broadcast.finish().unwrap(); +} + #[tokio::test] async fn raw_track_datagram_roundtrip() { let broadcast = MoqBroadcastProducer::new().unwrap(); diff --git a/rs/moq-mux/src/codec/aac/mod.rs b/rs/moq-mux/src/codec/aac/mod.rs index e2477911fc8..ad46c1773b9 100644 --- a/rs/moq-mux/src/codec/aac/mod.rs +++ b/rs/moq-mux/src/codec/aac/mod.rs @@ -27,6 +27,26 @@ pub enum Error { #[error("unsupported sample rate index: {0}")] UnsupportedSampleRateIndex(u8), + + /// The channelConfiguration is a reserved value (8, 9, 10, or 15). + #[error("reserved channelConfiguration: {0}")] + ReservedChannelConfig(u8), + + /// A program config element is used with an object type that has no GASpecificConfig. + #[error("channelConfiguration 0 is unsupported for audioObjectType {0}")] + ProgramConfigUnsupported(u8), + + /// ADTS signals a program config element, but none leads the first raw data block. + #[error("channelConfiguration 0 without a program config element leading the first raw data block")] + ProgramConfigMissing, + + /// The program config element ends before its declared fields. + #[error("program config element truncated")] + ProgramConfigTruncated, + + /// The program config element declares zero channels. + #[error("program config element declares no channels")] + ProgramConfigEmpty, } pub type Result = std::result::Result; @@ -46,34 +66,21 @@ impl Config { /// (object_type == 31), and explicit sample rates (freq_index == 15). The /// fields are bit-packed and not byte-aligned, so a bit reader is required: /// with an explicit 24-bit rate the channelConfiguration lands mid-byte after - /// it. Any SBR/PS extension bits after the core fields are consumed. + /// it. A channelConfiguration of 0 takes the count from the program config element + /// that follows, and a reserved one is refused. Any SBR/PS extension bits after the + /// core fields are consumed. pub fn parse(buf: &mut T) -> Result { - if buf.remaining() < 2 { - return Err(Error::ConfigTooShort); - } - let mut reader = BitReader::new(buf); - - // audioObjectType: 5 bits, escaped to 6 more when it reads 31. - let mut object_type = reader.read(5, Error::ConfigTooShort)? as u8; - if object_type == 31 { - object_type = 32 + reader.read(6, Error::ExtendedConfigTooShort)? as u8; - } - - // samplingFrequencyIndex: 4 bits; index 15 means an explicit 24-bit rate follows. - let freq_index = reader.read(4, Error::IncompleteConfig)? as u8; - let sample_rate = if freq_index == 15 { - reader.read(24, Error::ExplicitSampleRateTooShort)? - } else { - *SAMPLE_RATES - .get(freq_index as usize) - .ok_or(Error::UnsupportedSampleRateIndex(freq_index))? + let (object_type, sample_rate, channel_config) = read_header(&mut reader)?; + let channel_count = match channel_config { + 0 => { + let core = read_core(&mut reader, object_type)?; + read_general_audio(&mut reader, core)?; + program_config(&mut reader)? + } + _ => channel_count_from_config(channel_config)?, }; - // channelConfiguration: 4 bits, immediately after the (possibly explicit) rate. - let channel_config = reader.read(4, Error::IncompleteConfig)? as u8; - let channel_count = channel_count_from_config(channel_config); - // AudioSpecificConfig can carry variable-length extensions (SBR, PS, etc.). // We've extracted the essential fields; drain the rest so the buffer is advanced. if buf.remaining() > 0 { @@ -132,6 +139,199 @@ impl Config { } } +/// Read an AudioSpecificConfig's leading fields: the audioObjectType, sample rate, and +/// channelConfiguration. +fn read_header(reader: &mut BitReader) -> Result<(u8, u32, u8)> { + if reader.buf.remaining() < 2 { + return Err(Error::ConfigTooShort); + } + let object_type = read_object_type(reader)?; + + // samplingFrequencyIndex: 4 bits; index 15 means an explicit 24-bit rate follows. + let freq_index = reader.read(4, Error::IncompleteConfig)? as u8; + let sample_rate = if freq_index == 15 { + reader.read(24, Error::ExplicitSampleRateTooShort)? + } else { + *SAMPLE_RATES + .get(freq_index as usize) + .ok_or(Error::UnsupportedSampleRateIndex(freq_index))? + }; + + // channelConfiguration: 4 bits, immediately after the (possibly explicit) rate. + let channel_config = reader.read(4, Error::IncompleteConfig)? as u8; + Ok((object_type, sample_rate, channel_config)) +} + +/// Read the core audioObjectType, which explicit SBR and PS name after an extension rate. Any +/// other object type is its own core, and the leading sample rate is always the core's. +fn read_core(reader: &mut BitReader, object_type: u8) -> Result { + if !matches!(object_type, 5 | 29) { + return Ok(object_type); + } + if reader.read(4, Error::IncompleteConfig)? == 15 { + reader.read(24, Error::IncompleteConfig)?; + } + let core = read_object_type(reader)?; + if core == 22 { + // extensionChannelConfiguration, only for ER BSAC. + reader.read(4, Error::IncompleteConfig)?; + } + Ok(core) +} + +/// Read a GASpecificConfig up to the program config element that a channelConfiguration of 0 +/// puts next, refusing a `core` object type whose specific config is something else. +fn read_general_audio(reader: &mut BitReader, core: u8) -> Result<()> { + if !GENERAL_AUDIO.contains(&core) { + return Err(Error::ProgramConfigUnsupported(core)); + } + + // frameLengthFlag, dependsOnCoreCoder (then a 14-bit coreCoderDelay), and extensionFlag. + reader.read(1, Error::IncompleteConfig)?; + if reader.read(1, Error::IncompleteConfig)? == 1 { + reader.read(14, Error::IncompleteConfig)?; + } + reader.read(1, Error::IncompleteConfig)?; + Ok(()) +} + +/// Build the AudioSpecificConfig for a stream that signals its fields per frame, as ADTS does. +/// +/// A `channel_config` of 0 means a program config element leads `block`, the stream's first raw +/// data block; it moves into the config, so the config describes the channels on its own, and +/// `block` advances past it. Any other value leaves `block` untouched. An element placed anywhere +/// else is refused: reaching past the channel data needs a full Huffman decode. +pub(crate) fn in_band_config(profile: u8, sample_rate: u32, channel_config: u8, block: &mut &[u8]) -> Result { + let mut out = BitWriter::default(); + out.write(5, u32::from(profile & 0x1F)); + match SAMPLE_RATES.iter().position(|&rate| rate == sample_rate) { + Some(index) => out.write(4, index as u32), + None => { + out.write(4, 15); + out.write(24, sample_rate); + } + } + out.write(4, u32::from(channel_config)); + + if channel_config == 0 { + // GASpecificConfig: frameLengthFlag, dependsOnCoreCoder, and extensionFlag, all clear. + out.write(3, 0); + + // The element ends byte aligned to the block, so the reader stops exactly past it. + let mut reader = BitReader::new(block); + if reader.read(3, Error::ProgramConfigMissing)? != ID_PCE { + return Err(Error::ProgramConfigMissing); + } + reader.record = Some(out); + program_config(&mut reader)?; + out = reader.record.take().expect("recording set above"); + } + + Ok(Bytes::from(out.bytes)) +} + +/// The fields a stream that signals its config per frame, as ADTS does, carries in each header. +#[derive(Clone, Debug, PartialEq)] +pub(crate) struct InBand { + /// The core audioObjectType. Explicit SBR and PS name it under their own, and a decoder finds + /// them again in band, as it would in a stream that never signaled them (implicit signaling). + pub object_type: u8, + /// The core's sample rate, which SBR doubles on output. + pub sample_rate: u32, + pub channel_config: u8, + /// When `channel_config` is 0, the program config element framed to lead a raw data block: + /// its element ID, then the element aligned to the block. + pub program_config: Option, +} + +/// Split an AudioSpecificConfig into what a stream that carries it per frame signals, as ADTS +/// does; the inverse of [`in_band_config`]. +pub(crate) fn in_band(asc: &[u8]) -> Result { + let mut asc = asc; + let mut reader = BitReader::new(&mut asc); + let (object_type, sample_rate, channel_config) = read_header(&mut reader)?; + let core = read_core(&mut reader, object_type)?; + + let program_config = match channel_config { + 0 => { + read_general_audio(&mut reader, core)?; + let mut out = BitWriter::default(); + out.write(3, ID_PCE); + reader.record = Some(out); + program_config(&mut reader)?; + Some(Bytes::from(reader.record.take().expect("recording set above").bytes)) + } + _ => None, + }; + + Ok(InBand { + object_type: core, + sample_rate, + channel_config, + program_config, + }) +} + +/// The raw data block element ID of a program config element (ISO 14496-3 Table 4.85). +const ID_PCE: u32 = 5; + +/// The audioObjectTypes whose specific config is a GASpecificConfig (ISO 14496-3 §1.6.2.1), the +/// only ones where channelConfiguration 0 means a program config element follows. +const GENERAL_AUDIO: [u8; 12] = [1, 2, 3, 4, 6, 7, 17, 19, 20, 21, 22, 23]; + +/// Read an audioObjectType: 5 bits, escaped to 6 more when it reads 31. +fn read_object_type(reader: &mut BitReader) -> Result { + let object_type = reader.read(5, Error::ConfigTooShort)? as u8; + if object_type == 31 { + return Ok(32 + reader.read(6, Error::ExtendedConfigTooShort)? as u8); + } + Ok(object_type) +} + +/// Walk a program_config_element (ISO 14496-3 Table 4.2) to the number of channels it outputs. +/// +/// Its byte alignment is relative to where the reader started: the AudioSpecificConfig, or the +/// raw data block. +fn program_config(reader: &mut BitReader) -> Result { + let mut read = |n| reader.read(n, Error::ProgramConfigTruncated); + + // element_instance_tag, object_type, sampling_frequency_index. + read(10)?; + let (front, side, back) = (read(4)?, read(4)?, read(4)?); + let (lfe, assoc, cc) = (read(2)?, read(3)?, read(4)?); + // Mono and stereo mixdowns each name an element; a matrix mixdown an index and a flag. + for bits in [4, 4, 3] { + if read(1)? == 1 { + read(bits)?; + } + } + + let mut channels = lfe; + for _ in 0..front + side + back { + // A channel pair element carries two channels, a single channel element one. + channels += 1 + read(1)?; + read(4)?; + } + // Tags of the LFE and data elements, then each coupling channel element's switch flag and tag. + for _ in 0..lfe + assoc { + read(4)?; + } + for _ in 0..cc { + read(5)?; + } + + reader.align(); + let comment = reader.read(8, Error::ProgramConfigTruncated)?; + for _ in 0..comment { + reader.read(8, Error::ProgramConfigTruncated)?; + } + + if channels == 0 { + return Err(Error::ProgramConfigEmpty); + } + Ok(channels) +} + /// The 13 standard AAC sampling frequencies, indexed by samplingFrequencyIndex /// (ISO 14496-3 Table 1.18). Index 15 is the escape for an explicit 24-bit rate. const SAMPLE_RATES: [u32; 13] = [ @@ -147,6 +347,8 @@ struct BitReader<'a, T: Buf> { buf: &'a mut T, current: u8, bits_left: u8, + /// Every bit read is copied here when set, with alignment redone on the writer's own bytes. + record: Option, } impl<'a, T: Buf> BitReader<'a, T> { @@ -155,6 +357,15 @@ impl<'a, T: Buf> BitReader<'a, T> { buf, current: 0, bits_left: 0, + record: None, + } + } + + /// Skip to the next byte boundary. + fn align(&mut self) { + self.bits_left = 0; + if let Some(record) = &mut self.record { + record.align(); } } @@ -172,27 +383,52 @@ impl<'a, T: Buf> BitReader<'a, T> { self.bits_left -= 1; value = (value << 1) | u32::from((self.current >> self.bits_left) & 1); } + if let Some(record) = &mut self.record { + record.write(n, value); + } Ok(value) } } -/// Map an AAC `channel_config` (ISO 14496-3 Table 1.19) to its real channel count. -/// Configs 1..=6 happen to be identity (5.1 has config=6 and 6 channels). Config -/// 7 is 7.1 = 8 channels. Config 0 means "described elsewhere" — we default to -/// stereo. -fn channel_count_from_config(channel_config: u8) -> u32 { - match channel_config { - 1..=6 => channel_config as u32, - 7 => 8, - 0 => { - tracing::warn!("channel_config=0 (program config element) unsupported, defaulting to stereo"); - 2 - } - _ => { - tracing::warn!(channel_config, "unsupported channel config, defaulting to stereo"); - 2 +/// MSB-first bit writer, the inverse of [`BitReader`]. +#[derive(Default)] +struct BitWriter { + bytes: Vec, + /// Bits used in the last byte; 0 when the next write starts a new one. + used: u8, +} + +impl BitWriter { + /// Write the low `n` bits (n <= 32) of `value`, MSB-first. + fn write(&mut self, n: u8, value: u32) { + for i in (0..n).rev() { + if self.used == 0 { + self.bytes.push(0); + } + let bit = ((value >> i) & 1) as u8; + *self.bytes.last_mut().expect("pushed above") |= bit << (7 - self.used); + self.used = (self.used + 1) % 8; } } + + /// Pad the last byte with zeros. + fn align(&mut self) { + self.used = 0; + } +} + +/// Map an AAC `channel_config` (ISO 14496-3 Table 1.19) to its channel count, for every value but +/// 0, which a program config element describes instead. Configs 1..=6 are identity. 7, 12, and 14 +/// are 8 channels (7.1 with wide fronts, rear surrounds, or front heights), 11 is 6.1, and 13 is +/// 22.2. The rest are reserved. +fn channel_count_from_config(channel_config: u8) -> Result { + match channel_config { + 1..=6 => Ok(channel_config as u32), + 7 | 12 | 14 => Ok(8), + 11 => Ok(7), + 13 => Ok(24), + _ => Err(Error::ReservedChannelConfig(channel_config)), + } } /// Inverse of [`channel_count_from_config`]. Defaults to stereo for unsupported @@ -281,10 +517,239 @@ mod tests { assert_eq!(parsed.channel_count, 8, "7.1 surround should round-trip as 8 channels"); } + /// The AudioSpecificConfig ffmpeg 9.0.1 writes for quad (`-af pan=quad|...`, native `aac` + /// encoder, `.m4a`): channelConfiguration 0 and a program config element with two channel + /// pair elements, front and back, then a "Lavc63.1.101" comment and an SBR sync extension. + const FFMPEG_QUAD_ASC: [u8; 24] = [ + 0x11, 0x80, 0x04, 0xC4, 0x04, 0x00, 0x21, 0x10, 0x0C, 0x4C, 0x61, 0x76, 0x63, 0x36, 0x33, 0x2E, 0x31, 0x2E, + 0x31, 0x30, 0x31, 0x56, 0xE5, 0x00, + ]; + + /// Write a program config element with `front`, `side`, and `back` elements (true for a + /// channel pair) and `lfe` LFE elements, starting at the writer's position. + fn write_pce(out: &mut BitWriter, front: &[bool], side: &[bool], back: &[bool], lfe: u32) { + // element_instance_tag, object_type (LC), sampling_frequency_index (48 kHz). + out.write(4, 0); + out.write(2, 1); + out.write(4, 3); + out.write(4, front.len() as u32); + out.write(4, side.len() as u32); + out.write(4, back.len() as u32); + out.write(2, lfe); + // No data or coupling elements, and no mixdowns. + out.write(3, 0); + out.write(4, 0); + out.write(3, 0); + for (tag, &cpe) in front.iter().chain(side).chain(back).enumerate() { + out.write(1, cpe.into()); + out.write(4, tag as u32); + } + for tag in 0..lfe { + out.write(4, tag); + } + out.align(); + // A one-byte comment. + out.write(8, 1); + out.write(8, b'x'.into()); + } + + /// An AudioSpecificConfig with channelConfiguration 0 around [`write_pce`]'s element. + fn pce_asc(object_type: u8, front: &[bool], side: &[bool], back: &[bool], lfe: u32) -> Vec { + let mut out = BitWriter::default(); + out.write(5, object_type.into()); + out.write(4, 3); + out.write(4, 0); + out.write(3, 0); + write_pce(&mut out, front, side, back, lfe); + out.bytes + } + #[test] - fn channel_config_zero_falls_back_to_stereo() { - // Config 0 means "described in PCE" which we don't implement. - assert_eq!(channel_count_from_config(0), 2); + fn parses_ffmpeg_program_config_element() { + let cfg = Config::parse(&mut FFMPEG_QUAD_ASC.as_slice()).unwrap(); + assert_eq!(cfg.profile, 2); + assert_eq!(cfg.sample_rate, 48_000); + assert_eq!(cfg.channel_count, 4, "two channel pair elements"); + } + + #[test] + fn parses_program_config_element_counts() { + // 5.1: a single and a pair in front, a pair in back, and an LFE. + let asc = pce_asc(2, &[false, true], &[], &[true], 1); + assert_eq!(Config::parse(&mut asc.as_slice()).unwrap().channel_count, 6); + + // Side elements count too: 3/2/2 with no LFE. + let asc = pce_asc(2, &[false, true], &[true], &[true], 0); + assert_eq!(Config::parse(&mut asc.as_slice()).unwrap().channel_count, 7); + } + + /// audioObjectType 5 (SBR), 24 kHz core, channelConfiguration 0, a 48 kHz extension rate, + /// then the core type (LC) whose GASpecificConfig carries a front and back pair. + fn sbr_pce_asc() -> Vec { + let mut out = BitWriter::default(); + out.write(5, 5); + out.write(4, 6); + out.write(4, 0); + out.write(4, 3); + out.write(5, 2); + out.write(3, 0); + write_pce(&mut out, &[true], &[], &[true], 0); + out.bytes + } + + #[test] + fn parses_program_config_element_behind_explicit_sbr() { + let cfg = Config::parse(&mut sbr_pce_asc().as_slice()).unwrap(); + assert_eq!(cfg.profile, 5); + assert_eq!(cfg.channel_count, 4); + } + + #[test] + fn refuses_bad_program_config_elements() { + let asc = pce_asc(2, &[], &[], &[], 0); + assert!(matches!( + Config::parse(&mut asc.as_slice()), + Err(Error::ProgramConfigEmpty) + )); + + let asc = pce_asc(2, &[true], &[], &[], 0); + assert!(matches!( + Config::parse(&mut &asc[..asc.len() - 1]), + Err(Error::ProgramConfigTruncated) + )); + + // ALS (36) describes its channels in its own specific config, not a PCE. + let mut out = BitWriter::default(); + out.write(5, 31); + out.write(6, 4); + out.write(4, 3); + out.write(4, 0); + out.write(8, 0); + assert!(matches!( + Config::parse(&mut out.bytes.as_slice()), + Err(Error::ProgramConfigUnsupported(36)) + )); + } + + #[test] + fn channel_config_dispositions() { + let expected = [1, 2, 3, 4, 5, 6, 8]; + for (config, count) in (1..=7).zip(expected) { + let asc = [0x11, 0x80 | (config << 3)]; + assert_eq!(Config::parse(&mut asc.as_slice()).unwrap().channel_count, count); + } + + for (config, count) in [(11, 7), (12, 8), (13, 24), (14, 8)] { + let asc = [0x11, 0x80 | (config << 3)]; + assert_eq!(Config::parse(&mut asc.as_slice()).unwrap().channel_count, count); + } + + for config in [8, 9, 10, 15] { + let asc = [0x11, 0x80 | (config << 3)]; + assert!(matches!( + Config::parse(&mut asc.as_slice()), + Err(Error::ReservedChannelConfig(c)) if c == config + )); + } + } + + #[test] + fn in_band_config_moves_the_program_config_element() { + // A raw data block leading with ID_PCE, which puts the element 3 bits off the byte grid + // the AudioSpecificConfig puts it on, so the copy has to redo the alignment. + let mut block = BitWriter::default(); + block.write(3, ID_PCE); + write_pce(&mut block, &[false, true], &[], &[true], 1); + let pce = block.bytes.clone(); + // The channel elements that follow are never read. + block.write(8, 0xFF); + + let mut rest = block.bytes.as_slice(); + let asc = in_band_config(2, 48_000, 0, &mut rest).unwrap(); + assert_eq!(asc, pce_asc(2, &[false, true], &[], &[true], 1)); + assert_eq!(Config::parse(&mut asc.as_ref()).unwrap().channel_count, 6); + assert_eq!(rest, [0xFF], "the element moves out of the block"); + + // And back: the element leads the block again, byte for byte. + let in_band = in_band(&asc).unwrap(); + assert_eq!(in_band.channel_config, 0); + assert_eq!(in_band.program_config, Some(Bytes::from(pce))); + } + + #[test] + fn in_band_of_ffmpeg_program_config_element() { + // Round trip ffmpeg's own element through a raw data block and back into a config. The + // trailing SBR sync extension is not part of the element, so it drops. + let in_band = in_band(&FFMPEG_QUAD_ASC).unwrap(); + assert_eq!(in_band.channel_config, 0); + let pce = in_band.program_config.unwrap(); + let mut block = pce.as_ref(); + let asc = in_band_config(2, 48_000, 0, &mut block).unwrap(); + assert!(block.is_empty(), "the element is all that was framed"); + assert_eq!(asc, FFMPEG_QUAD_ASC[..FFMPEG_QUAD_ASC.len() - 3]); + } + + #[test] + fn in_band_without_a_program_config_element() { + let stereo = in_band(&[0x11, 0x90]).unwrap(); + assert_eq!((stereo.channel_config, stereo.program_config), (2, None)); + assert_eq!(in_band(&[0x11, 0xE0]).unwrap().channel_config, 12); + } + + #[test] + fn in_band_of_explicit_sbr_is_its_lc_core() { + // GStreamer 1.28 `fdkaacenc` at 48 kHz stereo: HE-AAC is SBR over a 24 kHz stereo LC core, + // and HE-AACv2 is PS over a mono one. + for (asc, channel_config) in [([0x2B, 0x11, 0x88, 0x00], 2), ([0xEB, 0x09, 0x88, 0x00], 1)] { + let expected = InBand { + object_type: 2, + sample_rate: 24_000, + channel_config, + program_config: None, + }; + assert_eq!(in_band(&asc).unwrap(), expected); + } + + // A config naming SBR but stopping before its core has no core to name. + assert!(matches!(in_band(&[0x2A, 0x10]), Err(Error::IncompleteConfig))); + } + + #[test] + fn in_band_of_explicit_sbr_keeps_its_program_config_element() { + let in_band = in_band(&sbr_pce_asc()).unwrap(); + assert_eq!(in_band.object_type, 2); + assert_eq!(in_band.sample_rate, 24_000); + assert_eq!(in_band.channel_config, 0); + let pce = in_band.program_config.expect("a program config element"); + let mut block = pce.as_ref(); + let asc = in_band_config(2, 24_000, 0, &mut block).unwrap(); + assert_eq!(Config::parse(&mut asc.as_ref()).unwrap().channel_count, 4); + } + + #[test] + fn in_band_config_refuses_a_block_without_a_leading_pce() { + // ID_CPE first: any element past the channel data is out of reach. + assert!(matches!( + in_band_config(2, 48_000, 0, &mut [0x20, 0x00].as_slice()), + Err(Error::ProgramConfigMissing) + )); + assert!(matches!( + in_band_config(2, 48_000, 0, &mut [].as_slice()), + Err(Error::ProgramConfigMissing) + )); + } + + #[test] + fn in_band_config_matches_encode() { + // Without a PCE the block is unread and the config is the plain two-byte form. + let asc = in_band_config(2, 44_100, 2, &mut [].as_slice()).unwrap(); + let encoded = Config { + profile: 2, + sample_rate: 44_100, + channel_count: 2, + } + .encode(); + assert_eq!(asc, encoded); } #[test] diff --git a/rs/moq-mux/src/codec/opus/import.rs b/rs/moq-mux/src/codec/opus/import.rs index 1f769f94d9f..9e7a6c1ba5b 100644 --- a/rs/moq-mux/src/codec/opus/import.rs +++ b/rs/moq-mux/src/codec/opus/import.rs @@ -117,7 +117,7 @@ impl Import { pub fn config(init: &[u8]) -> crate::Result { let mut buf = init; let mut config: hang::catalog::AudioConfig = Config::parse(&mut buf)?.into(); - // Publish the head as given: re-encoding it would drop a channel mapping table. + // Publish the head as given: a re-encode would rewrite its version byte. config.description = Some(bytes::Bytes::copy_from_slice(init)); Ok(config) } diff --git a/rs/moq-mux/src/codec/opus/mapping.rs b/rs/moq-mux/src/codec/opus/mapping.rs new file mode 100644 index 00000000000..4157dd5303f --- /dev/null +++ b/rs/moq-mux/src/codec/opus/mapping.rs @@ -0,0 +1,179 @@ +//! The OpusHead channel mapping table (RFC 7845 §5.1.1). + +use bytes::Buf; + +use super::{Error, Result}; + +/// An OpusHead channel mapping table (RFC 7845 §5.1.1), present for every family but 0. +#[derive(Clone, Copy, PartialEq, Eq)] +pub struct Mapping { + family: u8, + streams: u8, + coupled: u8, + channels: u8, + // Sized for the most channels any family allows, so `opus::Config` stays `Copy`. + table: [u8; 255], +} + +/// The fields of a channel mapping table, checked into a [`Mapping`] by [`Mapping::new`]. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Config<'a> { + /// The channel mapping family; 0 has no table and is refused. + pub family: u8, + /// Number of Opus streams in each packet. + pub streams: u8, + /// How many of those streams are coupled (stereo); they come first. + pub coupled: u8, + /// The decoded channel feeding each output channel, 255 for silence. + pub table: &'a [u8], +} + +/// The family 1 stream counts and table for 1 to 8 channels, as libopus and +/// RFC 7845 §5.1.1.2 lay out the Vorbis channel orders. +const VORBIS: [(u8, u8, &[u8]); 8] = [ + (1, 0, &[0]), + (1, 1, &[0, 1]), + (2, 1, &[0, 2, 1]), + (2, 2, &[0, 1, 2, 3]), + (3, 2, &[0, 4, 1, 2, 3]), + (4, 2, &[0, 4, 1, 2, 3, 5]), + (4, 3, &[0, 4, 1, 2, 3, 5, 6]), + (5, 3, &[0, 6, 1, 2, 3, 4, 5, 7]), +]; + +impl Mapping { + /// The family 1 mapping a surround encoder uses for `channels` in Vorbis + /// order, for sources that name only a channel count. + pub(crate) fn vorbis(channels: u8) -> Result { + let (streams, coupled, table) = *channels + .checked_sub(1) + .and_then(|index| VORBIS.get(index as usize)) + .ok_or(Error::UnsupportedChannelCount(channels as u32))?; + Self::new(Config { + family: 1, + streams, + coupled, + table, + }) + } + + /// Check `config` into a mapping with one output channel per table entry. + /// + /// Refuses family 0, a channel count the family does not allow, and a table + /// that names no streams, more coupled streams than streams, or a channel + /// past the decoded ones. + pub fn new(config: Config<'_>) -> Result { + let Config { + family, + streams, + coupled, + table, + } = config; + let max_channels = match family { + 0 => return Err(Error::UnsupportedMappingFamily(0)), + 1 => 8, + _ => 255, + }; + if table.is_empty() || table.len() > max_channels { + return Err(Error::UnsupportedChannelCount(table.len() as u32)); + } + + let decoded = streams as u32 + coupled as u32; + if streams == 0 || coupled > streams || decoded > 255 { + return Err(Error::InvalidMappingTable); + } + if table.iter().any(|&entry| entry != 255 && entry as u32 >= decoded) { + return Err(Error::InvalidMappingTable); + } + + let mut padded = [0u8; 255]; + padded[..table.len()].copy_from_slice(table); + Ok(Self { + family, + streams, + coupled, + channels: table.len() as u8, + table: padded, + }) + } + + pub(super) fn parse(buf: &mut T, family: u8, channels: u8) -> Result { + if buf.remaining() < 2 + channels as usize { + return Err(Error::MappingTableTooShort); + } + let streams = buf.get_u8(); + let coupled = buf.get_u8(); + let mut table = [0u8; 255]; + buf.copy_to_slice(&mut table[..channels as usize]); + Self::new(Config { + family, + streams, + coupled, + table: &table[..channels as usize], + }) + } + + /// The channel mapping family: 1 is the Vorbis speaker order, 2 and 3 are + /// ambisonics, and 255 is channels with no declared position. + pub fn family(&self) -> u8 { + self.family + } + + /// Number of Opus streams in each packet. + pub fn streams(&self) -> u8 { + self.streams + } + + /// How many of those streams are coupled (stereo); they come first. + pub fn coupled(&self) -> u8 { + self.coupled + } + + /// The decoded channel feeding each output channel, 255 for silence. + pub fn table(&self) -> &[u8] { + &self.table[..self.channels as usize] + } +} + +impl std::fmt::Debug for Mapping { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("Mapping") + .field("family", &self.family) + .field("streams", &self.streams) + .field("coupled", &self.coupled) + .field("table", &self.table()) + .finish() + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn new_validates_the_table() { + fn new(family: u8, streams: u8, coupled: u8, table: &[u8]) -> Result { + Mapping::new(Config { + family, + streams, + coupled, + table, + }) + } + + let mapping = new(255, 2, 0, &[0, 1, 255]).unwrap(); + assert_eq!(mapping.family(), 255); + assert_eq!((mapping.streams(), mapping.coupled()), (2, 0)); + assert_eq!(mapping.table(), &[0, 1, 255]); + + assert!(matches!(new(0, 1, 1, &[0, 1]), Err(Error::UnsupportedMappingFamily(0)))); + assert!(matches!(new(1, 1, 0, &[]), Err(Error::UnsupportedChannelCount(0)))); + assert!(matches!(new(1, 9, 0, &[0; 9]), Err(Error::UnsupportedChannelCount(9)))); + for (streams, coupled, table) in [(0, 0, &[0][..]), (1, 2, &[0]), (1, 1, &[2]), (200, 100, &[0])] { + assert!( + matches!(new(1, streams, coupled, table), Err(Error::InvalidMappingTable)), + "{streams} streams, {coupled} coupled, {table:?}" + ); + } + } +} diff --git a/rs/moq-mux/src/codec/opus/mod.rs b/rs/moq-mux/src/codec/opus/mod.rs index a0c6ac0cbba..3565a11761a 100644 --- a/rs/moq-mux/src/codec/opus/mod.rs +++ b/rs/moq-mux/src/codec/opus/mod.rs @@ -4,8 +4,10 @@ //! publishes raw Opus frames (no Ogg framing) to a moq broadcast. mod import; +pub mod mapping; pub use import::*; +pub use mapping::Mapping; use bytes::{Buf, Bytes}; @@ -28,9 +30,8 @@ pub enum Error { #[error("unsupported OpusHead version {0}")] UnsupportedVersion(u8), - /// The channel count is zero, or more than the channel mapping family - /// allows: family 0 (the only one [`Config::encode`] emits) covers - /// mono/stereo, and family 1 up to eight channels. + /// The channel count is zero, or more than the channel mapping family allows: + /// family 0 covers mono/stereo and family 1 up to eight channels. #[error("channel mapping family does not allow {0} channels")] UnsupportedChannelCount(u32), @@ -43,8 +44,11 @@ pub enum Error { #[error("invalid OpusHead channel mapping table")] InvalidMappingTable, - /// [`Config::encode`] only emits channel mapping family 0. - #[error("cannot encode channel mapping family {0}")] + /// A channel mapping family the operation cannot carry: family 0 given to + /// [`Mapping::new`], which has no table; a [`Config::encode`] whose + /// `mapping_family` is not its `mapping`'s; or a container with no room for + /// the table. + #[error("unsupported channel mapping family {0}")] UnsupportedMappingFamily(u8), } @@ -66,7 +70,11 @@ pub struct Config { /// Gain to apply to the decoded output, in Q7.8 dB. pub output_gain: i16, /// Channel mapping family; 0 is mono/stereo with no mapping table. + /// + /// Always `mapping`'s family, or 0 without one. pub mapping_family: u8, + /// The channel mapping table, or `None` for family 0 (mono/stereo, one stream). + pub mapping: Option, } impl Config { @@ -78,6 +86,7 @@ impl Config { pre_skip: 0, output_gain: 0, mapping_family: 0, + mapping: None, } } @@ -89,10 +98,9 @@ impl Config { /// Parse an OpusHead buffer (RFC 7845 §5.1). /// - /// Accepts any minor version and refuses a new major version. A nonzero - /// channel mapping family must carry a complete, consistent mapping table, - /// which is validated but not returned. Bytes after the header are left in - /// `buf`. + /// Accepts any minor version and refuses a new major version. Reads the + /// channel mapping, refusing a channel count the family forbids or an + /// inconsistent mapping table. Bytes after the header are left in `buf`. pub fn parse(buf: &mut T) -> Result { if buf.remaining() < 19 { return Err(Error::HeadTooShort); @@ -112,32 +120,11 @@ impl Config { let output_gain = buf.get_i16_le(); let mapping_family = buf.get_u8(); - let max_channels = match mapping_family { - 0 => 2, - 1 => 8, - _ => 255, + let mapping = match mapping_family { + 0 if (1..=2).contains(&channel_count) => None, + 0 => return Err(Error::UnsupportedChannelCount(channel_count)), + family => Some(Mapping::parse(buf, family, channel_count as u8)?), }; - if channel_count == 0 || channel_count > max_channels { - return Err(Error::UnsupportedChannelCount(channel_count)); - } - - if mapping_family != 0 { - if buf.remaining() < 2 + channel_count as usize { - return Err(Error::MappingTableTooShort); - } - let streams = buf.get_u8() as u32; - let coupled = buf.get_u8() as u32; - if streams == 0 || coupled > streams || streams + coupled > 255 { - return Err(Error::InvalidMappingTable); - } - for _ in 0..channel_count { - // 255 marks a silent channel. - let index = buf.get_u8() as u32; - if index != 255 && index >= streams + coupled { - return Err(Error::InvalidMappingTable); - } - } - } Ok(Self { sample_rate, @@ -145,28 +132,44 @@ impl Config { pre_skip, output_gain, mapping_family, + mapping, }) } - /// Encode the minimal OpusHead packet (19 bytes; channel mapping family 0). + /// Encode an OpusHead packet (RFC 7845 §5.1), followed by the channel mapping + /// table when there is one. /// - /// Errors unless the mapping family is 0 and `channel_count` is 1 or 2, since - /// multichannel streams need a mapping table this helper does not emit. + /// Errors with [`Error::UnsupportedChannelCount`] when `channel_count` is not + /// 1 or 2 without a `mapping` (family 0 is only defined for mono/stereo), or + /// is not the mapping's own channel count, and with + /// [`Error::UnsupportedMappingFamily`] when `mapping_family` is not the + /// mapping's family. pub fn encode(&self) -> Result { - if self.mapping_family != 0 { + if self.mapping_family != self.mapping.map_or(0, |mapping| mapping.family()) { return Err(Error::UnsupportedMappingFamily(self.mapping_family)); } - if !(1..=2).contains(&self.channel_count) { + let valid = match &self.mapping { + None => (1..=2).contains(&self.channel_count), + Some(mapping) => self.channel_count == mapping.table().len() as u32, + }; + if !valid { return Err(Error::UnsupportedChannelCount(self.channel_count)); } - let mut head = Vec::with_capacity(19); + + let mut head = Vec::with_capacity(21 + self.channel_count as usize); head.extend_from_slice(b"OpusHead"); head.push(1); // version head.push(self.channel_count as u8); head.extend_from_slice(&self.pre_skip.to_le_bytes()); head.extend_from_slice(&self.sample_rate.to_le_bytes()); head.extend_from_slice(&self.output_gain.to_le_bytes()); - head.push(0); // channel mapping family (0 = mono/stereo) + match &self.mapping { + None => head.push(0), + Some(mapping) => { + head.extend_from_slice(&[mapping.family(), mapping.streams(), mapping.coupled()]); + head.extend_from_slice(mapping.table()); + } + } Ok(Bytes::from(head)) } } @@ -250,7 +253,7 @@ mod tests { assert!(matches!(err, Error::UnsupportedChannelCount(6))); } - /// A 19-byte family 0 head with the given version, channels, gain, and family. + /// A 19-byte head with the given version, channels, gain, and family. fn head(version: u8, channels: u8, gain: i16, family: u8) -> Vec { let mut head = b"OpusHead".to_vec(); head.push(version); @@ -287,12 +290,75 @@ mod tests { )); } + #[test] + fn parses_a_mapping_table() { + // 5.1 in family 1: four streams, two coupled, Vorbis order. + let mut bytes = head(1, 6, 0, 1); + bytes.extend_from_slice(&[4, 2, 0, 4, 1, 2, 3, 5]); + let trailing = [bytes.as_slice(), b"trailing"].concat(); + let mut buf = trailing.as_slice(); + let parsed = Config::parse(&mut buf).unwrap(); + assert_eq!(buf, b"trailing"); + assert_eq!(parsed.channel_count, 6); + assert_eq!(parsed.mapping_family, 1); + + let mapping = parsed.mapping.unwrap(); + assert_eq!(mapping.family(), 1); + assert_eq!(mapping.streams(), 4); + assert_eq!(mapping.coupled(), 2); + assert_eq!(mapping.table(), &[0, 4, 1, 2, 3, 5]); + + // The table survives a re-encode. + assert_eq!(parsed.encode().unwrap(), bytes); + } + + #[test] + fn encodes_the_vorbis_mappings() { + for channels in 1..=8u8 { + let mut config = Config::new(48_000, channels as u32); + config.mapping_family = 1; + config.mapping = Some(Mapping::vorbis(channels).unwrap()); + let head = config.encode().unwrap(); + assert_eq!(head.len(), 21 + channels as usize, "{channels} channels"); + assert_eq!( + Config::parse(&mut head.as_ref()).unwrap(), + config, + "{channels} channels" + ); + } + + // 5.1 is the table libopus and ffmpeg write. + let five_one = Mapping::vorbis(6).unwrap(); + assert_eq!((five_one.streams(), five_one.coupled()), (4, 2)); + assert_eq!(five_one.table(), &[0, 4, 1, 2, 3, 5]); + + assert!(matches!(Mapping::vorbis(0), Err(Error::UnsupportedChannelCount(0)))); + assert!(matches!(Mapping::vorbis(9), Err(Error::UnsupportedChannelCount(9)))); + + // The channel count must agree with the table. + let mut config = Config::new(48_000, 5); + config.mapping_family = 1; + config.mapping = Some(five_one); + assert!(matches!(config.encode(), Err(Error::UnsupportedChannelCount(5)))); + + // So must the family, both ways. + let mut config = Config::new(48_000, 6); + config.mapping = Some(five_one); + assert!(matches!(config.encode(), Err(Error::UnsupportedMappingFamily(0)))); + let mut config = Config::new(48_000, 2); + config.mapping_family = 1; + assert!(matches!(config.encode(), Err(Error::UnsupportedMappingFamily(1)))); + } + #[test] fn parse_rejects_channel_counts_the_family_does_not_allow() { - for (channels, family) in [(0, 0), (3, 0), (0, 1), (9, 1)] { + for (channels, family) in [(0, 0), (3, 0), (0, 1), (9, 1), (0, 255)] { + let mut bytes = head(1, channels, 0, family); + bytes.extend_from_slice(&[1, 0]); + bytes.extend(std::iter::repeat_n(0, channels as usize)); assert!( matches!( - Config::parse(&mut head(1, channels, 0, family).as_slice()), + Config::parse(&mut bytes.as_slice()), Err(Error::UnsupportedChannelCount(_)) ), "{channels} channels in family {family}" @@ -301,42 +367,26 @@ mod tests { } #[test] - fn parse_reads_a_mapping_table() { - // 5.1 in family 1: four streams, two coupled, Vorbis order. - let mut bytes = head(1, 6, 0, 1); - bytes.extend_from_slice(&[4, 2, 0, 4, 1, 2, 3, 5]); - bytes.extend_from_slice(b"trailing"); - let mut buf = bytes.as_slice(); - let parsed = Config::parse(&mut buf).unwrap(); - assert_eq!(parsed.channel_count, 6); - assert_eq!(parsed.mapping_family, 1); - assert_eq!(buf, b"trailing"); - - // Encode only emits family 0. - assert!(matches!(parsed.encode(), Err(Error::UnsupportedMappingFamily(1)))); - } - - #[test] - fn parse_rejects_a_truncated_or_invalid_mapping_table() { - // No table at all. - let bytes = head(1, 2, 0, 1); + fn parse_rejects_a_bad_mapping_table() { + // Family 1 promising a table that is not there, or only half of it. assert!(matches!( - Config::parse(&mut bytes.as_slice()), + Config::parse(&mut head(1, 2, 0, 1).as_slice()), Err(Error::MappingTableTooShort) )); - - // Table cut short of its last channel. - let mut bytes = head(1, 2, 0, 1); - bytes.extend_from_slice(&[1, 1, 0]); + let mut short = head(1, 2, 0, 1); + short.extend_from_slice(&[1, 1, 0]); assert!(matches!( - Config::parse(&mut bytes.as_slice()), + Config::parse(&mut short.as_slice()), Err(Error::MappingTableTooShort) )); for table in [ - [0, 0, 0, 1], // no streams - [1, 2, 0, 1], // more coupled than streams - [1, 1, 0, 2], // index past the two decoded channels + // No streams. + [0, 0, 0, 1], + // More coupled streams than streams. + [1, 2, 0, 1], + // A channel index past the two decoded channels. + [1, 1, 0, 2], ] { let mut bytes = head(1, 2, 0, 1); bytes.extend_from_slice(&table); @@ -347,8 +397,11 @@ mod tests { } // 255 is a silent channel, not an index. - let mut bytes = head(1, 2, 0, 1); - bytes.extend_from_slice(&[1, 1, 0, 255]); - assert!(Config::parse(&mut bytes.as_slice()).is_ok()); + let mut silent = head(1, 2, 0, 1); + silent.extend_from_slice(&[1, 0, 0, 255]); + assert_eq!( + Config::parse(&mut silent.as_slice()).unwrap().mapping.unwrap().table(), + &[0, 255] + ); } } diff --git a/rs/moq-mux/src/container/ts/adts.rs b/rs/moq-mux/src/container/ts/adts.rs index b5a986a2f30..632947bdce4 100644 --- a/rs/moq-mux/src/container/ts/adts.rs +++ b/rs/moq-mux/src/container/ts/adts.rs @@ -21,7 +21,8 @@ pub(super) struct Header { /// audioObjectType (ADTS `profile` + 1). AAC-LC is 2. pub object_type: u8, pub sample_rate: u32, - pub channel_count: u32, + /// channelConfiguration; 0 means a program config element in the raw data block describes the channels. + pub channel_config: u8, /// Total access-unit length, header included. pub frame_len: usize, /// Header length: 7 without CRC, 9 with. @@ -51,7 +52,7 @@ impl Header { Ok(Self { object_type: profile + 1, sample_rate, - channel_count: channel_count_from_config(channel_config), + channel_config, frame_len, header_len, }) @@ -62,13 +63,21 @@ impl Header { pub(super) fn write_header( object_type: u8, sample_rate: u32, - channel_count: u32, + channel_config: u8, raw_len: usize, ) -> anyhow::Result<[u8; 7]> { - // ADTS `profile` is the 2-bit audioObjectType - 1. - let profile = object_type.saturating_sub(1) & 0x03; + // ADTS `profile` is the 2-bit audioObjectType - 1, so only Main, LC, SSR, and LTP fit. + anyhow::ensure!( + (1..=4).contains(&object_type), + "audioObjectType {object_type} not representable in ADTS" + ); + let profile = object_type - 1; let freq_index = freq_index_from_rate(sample_rate)?; - let channel_config = channel_config_from_count(channel_count); + // ADTS has 3 bits for it; the higher configurations only fit an AudioSpecificConfig. + anyhow::ensure!( + channel_config < 8, + "channelConfiguration {channel_config} not representable in ADTS" + ); let frame_len = raw_len + 7; anyhow::ensure!(frame_len < (1 << 13), "AAC frame too large for ADTS framing"); @@ -96,21 +105,13 @@ fn freq_index_from_rate(sample_rate: u32) -> anyhow::Result { .with_context(|| format!("sample rate {sample_rate} not representable in ADTS")) } -/// Map an AAC `channel_config` (ISO 14496-3 Table 1.19) to a channel count. -fn channel_count_from_config(channel_config: u8) -> u32 { - match channel_config { - 1..=6 => channel_config as u32, - 7 => 8, - _ => 2, - } -} - -/// Inverse of [`channel_count_from_config`]. -fn channel_config_from_count(channel_count: u32) -> u8 { +/// Map a channel count to the ADTS `channel_config` (ISO 14496-3 Table 1.19) naming it, refusing a +/// count that none does rather than guess a layout. +pub(super) fn channel_config_from_count(channel_count: u32) -> anyhow::Result { match channel_count { - 1..=6 => channel_count as u8, - 8 => 7, - _ => 2, + 1..=6 => Ok(channel_count as u8), + 8 => Ok(7), + _ => anyhow::bail!("{channel_count} channels have no ADTS channelConfiguration"), } } @@ -126,7 +127,7 @@ mod tests { assert_eq!(parsed.object_type, 2); assert_eq!(parsed.sample_rate, 48_000); - assert_eq!(parsed.channel_count, 2); + assert_eq!(parsed.channel_config, 2); assert_eq!(parsed.header_len, 7); assert_eq!(parsed.frame_len, 107, "frame_len includes the 7-byte header"); } @@ -138,11 +139,30 @@ mod tests { assert!(Header::parse(&header).is_err()); } + #[test] + fn write_refuses_object_types_outside_the_profile_field() { + for object_type in [0, 5, 29] { + assert!(write_header(object_type, 48_000, 2, 10).is_err()); + } + for object_type in 1..=4 { + let header = write_header(object_type, 48_000, 2, 10).unwrap(); + assert_eq!(Header::parse(&header).unwrap().object_type, object_type); + } + } + + #[test] + fn channel_counts_without_a_configuration_are_refused() { + assert_eq!(channel_config_from_count(8).unwrap(), 7); + for count in [0, 7, 9, 24] { + assert!(channel_config_from_count(count).is_err()); + } + } + #[test] fn frame_len_for_5_1() { let header = write_header(2, 44_100, 6, 512).unwrap(); let parsed = Header::parse(&header).unwrap(); - assert_eq!(parsed.channel_count, 6); + assert_eq!(parsed.channel_config, 6); assert_eq!(parsed.sample_rate, 44_100); assert_eq!(parsed.frame_len, 519); } diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index 5457c6eaa17..e07f1b0d39e 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -37,8 +37,8 @@ use moq_net::Timestamp; use crate::catalog::hang::Catalog; use crate::catalog::{CatalogFormat, Stream}; -use crate::codec::annexb; use crate::codec::video::Reorder; +use crate::codec::{aac, annexb}; use crate::container::{ExportSource, Frame}; use super::adts; @@ -382,11 +382,10 @@ impl Reserve { enum Kind { /// Video carries its TS stream type (H.264 = 0x1B, H.265 = 0x24). Video(StreamType), - Aac { - object_type: u8, - sample_rate: u32, - channel_count: u32, - }, + /// AAC, framed as ADTS. A `channel_config` of 0 defers the layout to a program config + /// element, which leads the next raw data block written and is then taken. A catalog update + /// rebuilds the kind and so repeats it once, which a decoder tuning in mid-stream welcomes. + Aac(aac::InBand), /// Opus (private stream_type 0x06). Each frame is one Opus packet, prefixed with /// the Opus-in-TS access-unit control header and announced with the 'Opus' /// registration plus DVB extension descriptor. @@ -1393,7 +1392,7 @@ impl Export { tracks.iter().find(|t| { matches!( t.kind, - Kind::Aac { .. } | Kind::Opus { .. } | Kind::Mp2 { .. } | Kind::Ac3 | Kind::Eac3 + Kind::Aac(_) | Kind::Opus { .. } | Kind::Mp2 { .. } | Kind::Ac3 | Kind::Eac3 ) }) }) @@ -1405,7 +1404,7 @@ impl Export { .map(|t| { let stream_type = match &t.kind { Kind::Video(stream_type) => *stream_type, - Kind::Aac { .. } => StreamType::AdtsAac, + Kind::Aac(_) => StreamType::AdtsAac, // Opus rides private-data PES; the registration + extension descriptors // below tell the demuxer it's Opus. Kind::Opus { .. } => StreamType::from_u8(0x06).map_err(anyhow::Error::msg)?, @@ -1553,9 +1552,12 @@ impl Export { if self.span_counters.is_none() { self.span_counters = Some(self.counters.clone()); } - let track = self.tracks.get(name).context("missing track")?; + let track = self.tracks.get_mut(name).context("missing track")?; let pid = track.pid; let kind = track.kind.clone(); + if let Kind::Aac(aac) = &mut track.kind { + aac.program_config.take(); + } let is_video = matches!(kind, Kind::Video(_)); let timestamp = frame.timestamp; let keyframe = frame.keyframe; @@ -1565,14 +1567,13 @@ impl Export { // verbatim streams carry no PES payload; the section is written separately below. let es_payload = match &kind { Kind::Video(stream_type) => Some(video_es_payload(*stream_type, track.source.description(), &frame)?), - Kind::Aac { - object_type, - sample_rate, - channel_count, - } => { - let header = adts::write_header(*object_type, *sample_rate, *channel_count, frame.payload.len())?; - let mut framed = Vec::with_capacity(7 + frame.payload.len()); + Kind::Aac(aac) => { + let pce = aac.program_config.as_deref().unwrap_or_default(); + let raw_len = pce.len() + frame.payload.len(); + let header = adts::write_header(aac.object_type, aac.sample_rate, aac.channel_config, raw_len)?; + let mut framed = Vec::with_capacity(header.len() + raw_len); framed.extend_from_slice(&header); + framed.extend_from_slice(pce); framed.extend_from_slice(&frame.payload); Some(framed) } @@ -2307,11 +2308,19 @@ fn video_es_payload(stream_type: StreamType, description: Option<&Bytes>, frame: fn audio_kind(config: &AudioConfig, name: &str) -> anyhow::Result { ensure_raw(&config.container, "audio", name)?; match &config.codec { - AudioCodec::AAC(aac) => Ok(Kind::Aac { - object_type: aac.profile, - sample_rate: config.sample_rate, - channel_count: config.channel_count, - }), + AudioCodec::AAC(codec) => { + // The description is exact, and names the LC core under explicit SBR or PS. Without + // one, the catalog is all there is. + Ok(Kind::Aac(match &config.description { + Some(asc) => aac::in_band(asc)?, + None => aac::InBand { + object_type: codec.profile, + sample_rate: config.sample_rate, + channel_config: adts::channel_config_from_count(config.channel_count)?, + program_config: None, + }, + })) + } AudioCodec::Mp2 => Ok(Kind::Mp2 { sample_rate: config.sample_rate, }), diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index b6b4eef9857..cadb57a7f4a 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -1425,6 +1425,150 @@ async fn ac3_roundtrip_byte_exact() { assert_eq!(roundtripped, ingested, "AC-3 frames must survive byte-for-byte"); } +/// The first ADTS frame of the first AAC PES: its header and raw data block. +fn first_adts_frame(ts: &[u8]) -> (super::adts::Header, Vec) { + let mut pes = PesPacketReader::new(TsPacketReader::new(Cursor::new(ts))); + let packet = pes.read_pes_packet().unwrap().expect("an AAC PES"); + let header = super::adts::Header::parse(&packet.data).unwrap(); + (header, packet.data[header.header_len..header.frame_len].to_vec()) +} + +/// ffmpeg's quad AAC fixture has no channelConfiguration, so its layout rides in a program +/// config element. Import moves it into the description and export puts it back: channel_config +/// 0 in ADTS and the element leading the first raw data block, exactly as ffmpeg wrote it. +#[tokio::test(start_paused = true)] +async fn aac_program_config_roundtrip() { + let data = include_bytes!("test_data/aac_quad.ts"); + + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let consumer = broadcast.consume(); + let catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + let mut import = crate::container::ts::Import::new(broadcast, catalog.reserve()); + import.decode(&BytesMut::from(&data[..])).unwrap(); + import.finish().unwrap(); + + let snapshot = catalog.snapshot(); + let (name, audio) = snapshot.audio.renditions.iter().next().expect("an AAC track"); + assert_eq!(audio.channel_count, 4); + let ingested = read_frames(&consumer, name, Kind::Audio).await; + assert!(!ingested.is_empty(), "no AAC frames"); + + let ts = drain(consumer).await; + assert_packet_aligned(&ts); + + let (header, block) = first_adts_frame(&ts); + assert_eq!(header.channel_config, 0, "the layout is not a channelConfiguration"); + assert_eq!( + block, + first_adts_frame(data).1, + "the first raw data block, element and all" + ); + + let mut broadcast2 = moq_net::broadcast::Info::new().produce(); + let consumer2 = broadcast2.consume(); + let catalog2 = crate::catalog::Producer::new(&mut broadcast2, crate::catalog::Config::default()).unwrap(); + let mut import2 = crate::container::ts::Import::new(broadcast2, catalog2.reserve()); + import2.decode(&BytesMut::from(ts.as_ref())).unwrap(); + import2.finish().unwrap(); + + let snapshot2 = catalog2.snapshot(); + let (name2, audio2) = snapshot2 + .audio + .renditions + .iter() + .next() + .expect("round-trip lost the AAC track"); + assert_eq!(audio2.channel_count, 4); + assert_eq!(audio2.description, audio.description); + let roundtripped = read_frames(&consumer2, name2, Kind::Audio).await; + assert_eq!(roundtripped, ingested, "the element is written once, not per frame"); +} + +/// GStreamer 1.28 `fdkaacenc` output, 48 kHz stereo, remuxed to FLV by ffmpeg 9.0.1. Its +/// AudioSpecificConfig signals SBR (and PS for v2) explicitly: object type 5 or 29 over an LC core +/// at 24 kHz, stereo for v1 and mono for v2. ADTS has two bits for the object type, so export +/// labels the LC core at its own rate and layout and leaves SBR and PS to implicit signaling, the +/// header ffmpeg's ADTS muxer writes too. ffprobe reads the result back as HE-AAC or HE-AACv2 at +/// 48 kHz stereo, like the source. +#[tokio::test(start_paused = true)] +async fn aac_explicit_sbr_exports_its_lc_core() { + let fixtures: [(&[u8], u8); 2] = [ + (include_bytes!("test_data/he_aac.flv"), 2), + (include_bytes!("test_data/he_aac_v2.flv"), 1), + ]; + for (data, channel_config) in fixtures { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let consumer = broadcast.consume(); + let catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + let mut import = crate::container::flv::Import::new(broadcast, catalog.reserve()); + import.decode(data).unwrap(); + import.finish().unwrap(); + + let snapshot = catalog.snapshot(); + let (name, _) = snapshot.audio.renditions.iter().next().expect("an AAC track"); + let ingested = read_frames(&consumer, name, Kind::Audio).await; + assert!(!ingested.is_empty(), "no AAC frames"); + + let ts = drain(consumer).await; + assert_packet_aligned(&ts); + + let (header, block) = first_adts_frame(&ts); + assert_eq!(header.object_type, 2, "the LC core, not a masked SBR or PS"); + assert_eq!(header.sample_rate, 24_000, "the core rate, not the output rate"); + assert_eq!(header.channel_config, channel_config); + assert_eq!(block, ingested[0], "the raw data block is untouched"); + } +} + +/// Without a description, the catalog is all ADTS has to label a track with. A channel count no +/// channelConfiguration names is refused rather than written as stereo, and HE-AAC, whose core +/// rate and layout only a description names, is refused rather than masked to AAC Main. +#[tokio::test(start_paused = true)] +async fn aac_export_refuses_what_adts_cannot_label() { + for (profile, channel_count, refusal) in [(2, 7, "7 channels"), (5, 2, "audioObjectType 5")] { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let consumer = broadcast.consume(); + let mut catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + + let track = broadcast + .create_track( + broadcast.unique_name(".aac"), + hang::container::track_info(hang::catalog::PRIORITY.audio), + ) + .unwrap(); + let mut cfg = AudioConfig::new(AAC { profile }, 48_000, channel_count); + cfg.container = Container::Legacy; + catalog + .modify() + .unwrap() + .audio + .renditions + .insert(track.name().to_string(), cfg); + + let mut producer = Producer::new(track, HangContainer::Legacy(crate::container::Kind::Data)); + producer + .write(Frame { + timestamp: Timestamp::from_millis(0).unwrap(), + duration: None, + payload: Bytes::from_static(&[0x01, 0x02]), + keyframe: true, + }) + .unwrap(); + producer.finish().unwrap(); + + let mut exporter = Export::new(crate::source::announced(&consumer)).await.unwrap(); + let err = loop { + match tokio::time::timeout(Duration::from_secs(1), exporter.next()).await { + Ok(Ok(Some(_))) => continue, + Ok(Ok(None)) => panic!("export completed; expected a refusal naming {refusal}"), + Ok(Err(e)) => break e, + Err(_) => panic!("export neither errored nor completed"), + } + }; + assert!(err.to_string().contains(refusal), "expected {refusal}, got: {err}"); + } +} + /// The ffmpeg E-AC-3 fixture must survive TS -> MoQ -> TS byte-for-byte in an /// audio-only program; the PMT re-announces ATSC 0x87 with the 'EAC3' /// registration descriptor. diff --git a/rs/moq-mux/src/container/ts/import.rs b/rs/moq-mux/src/container/ts/import.rs index 5f4c10ef233..6bbb02801a4 100644 --- a/rs/moq-mux/src/container/ts/import.rs +++ b/rs/moq-mux/src/container/ts/import.rs @@ -532,11 +532,10 @@ impl Import { // by an 'Opus' registration descriptor. Channels and the (always 48 kHz) rate // come from the descriptors, so the importer is built up front. StreamType::Mpeg2PacketizedData if registration_format(descriptors) == Some(*b"Opus") => { - let channel_count = opus_channel_count(descriptors).unwrap_or(2); + let config = opus_config(descriptors)?; let track = self .broadcast .unique_track(".opus", self.catalog.track_info(hang::catalog::PRIORITY.audio))?; - let config = opus::Config::new(48_000, channel_count); let mut config: hang::catalog::AudioConfig = config.into(); config.container = self.container.clone(); Stream::Opus(Box::new(OpusStream { @@ -2325,30 +2324,34 @@ impl AacStream { } }; + let mut block = &data[offset + header.header_len..end]; let import = match &mut self.import { Some(import) => import, None => { - let config = aac::Config { - profile: header.object_type, - sample_rate: header.sample_rate, - channel_count: header.channel_count, - }; + // Synthesize the AudioSpecificConfig `description` so out-of-band consumers + // (fMP4/MKV export, WebCodecs) can configure the decoder. A channel_config of 0 + // moves the program config element out of this first frame into it, as + // ffmpeg's aac_adtstoasc does; the TS export puts it back. + let asc = aac::in_band_config( + header.object_type, + header.sample_rate, + header.channel_config, + &mut block, + )?; + let mut config = aac::config(&asc)?; + config.container = self.container.clone(); // Consume the reservation held since the PMT: this resolves the gated rendition, // and carries the catalog's declared media retention onto the track. - // The importer synthesizes the AudioSpecificConfig `description` from the config so - // out-of-band consumers (fMP4/MKV export, WebCodecs) can configure the decoder. let reserved = self.reserved.take().expect("aac reservation already consumed"); let track = self .broadcast .unique_track(".aac", reserved.track_info(hang::catalog::PRIORITY.audio))?; - let mut config: hang::catalog::AudioConfig = config.into(); - config.container = self.container.clone(); let aac = aac::Import::new(track, reserved, config)?; self.import.insert(aac) } }; - import.decode(&data[offset + header.header_len..end], pts)?; + import.decode(block, pts)?; // Count only completed frames; input gaps and unfinished tails are not a media burst. burst += std::time::Duration::from_nanos((1024_u64 * 1_000_000_000).div_ceil(header.sample_rate as u64)); // The importer accumulates; cut each ADTS frame into its own group (one QUIC stream) @@ -2536,14 +2539,15 @@ fn registration_format(descriptors: &[mpeg2ts::ts::Descriptor]) -> Option<[u8; 4 .and_then(|s| s.try_into().ok()) } -/// The Opus channel count from the DVB extension descriptor (tag 0x7f, ext tag 0x80). +/// The OpusHead implied by the DVB extension descriptor (tag 0x7f, ext tag 0x80). /// /// `channel_config_code` follows the Opus-in-TS mapping (and ffmpeg's demuxer): 0 is dual -/// mono (decoded as stereo), 1..=8 is the channel count directly. Higher codes (0x81 -/// explicitly-coded layouts, reserved values) aren't supported, so they fall back to the -/// caller's default rather than being read as a raw 129..=255 count. -fn opus_channel_count(descriptors: &[mpeg2ts::ts::Descriptor]) -> Option { - descriptors +/// mono (decoded as stereo), 1..=8 is the channel count directly, with family 0 for mono and +/// stereo and the Vorbis family 1 mapping above that. Higher codes (0x81 explicitly-coded +/// layouts, reserved values) aren't supported, so they fall back to stereo rather than being +/// read as a raw 129..=255 count. +fn opus_config(descriptors: &[mpeg2ts::ts::Descriptor]) -> crate::Result { + let channels = descriptors .iter() .find(|d| d.tag == 0x7f && d.data.first() == Some(&0x80)) .and_then(|d| d.data.get(1)) @@ -2552,6 +2556,15 @@ fn opus_channel_count(descriptors: &[mpeg2ts::ts::Descriptor]) -> Option { 1..=8 => Some(cc as u32), _ => None, }) + .unwrap_or(2); + + let mut config = opus::Config::new(48_000, channels); + if channels > 2 { + let mapping = opus::Mapping::vorbis(channels as u8)?; + config.mapping_family = mapping.family(); + config.mapping = Some(mapping); + } + Ok(config) } /// Parse one Opus-in-TS access-unit control header, returning `(header_len, payload_size)`. diff --git a/rs/moq-mux/src/container/ts/import_test.rs b/rs/moq-mux/src/container/ts/import_test.rs index 320a63ef62a..f06ed12c92e 100644 --- a/rs/moq-mux/src/container/ts/import_test.rs +++ b/rs/moq-mux/src/container/ts/import_test.rs @@ -156,6 +156,32 @@ fn import_ac3_catalog() { assert!(audio.description.is_none(), "verbatim AC-3 needs no description"); } +/// `aac_quad.ts` is an ffmpeg-authored audio-only AAC program in quad, which has no +/// channelConfiguration, so its ADTS headers carry 0 and the first raw data block leads with a +/// program config element. Regenerated with (ffmpeg 9.0.1): +/// `ffmpeg -f lavfi -i sine=frequency=440:sample_rate=48000:duration=0.1 +/// -af "pan=quad|FL=c0|FR=c0|BL=c0|BR=c0" -c:a aac -b:a 128k -f mpegts aac_quad.ts`. +#[test] +fn import_aac_program_config_catalog() { + let data = include_bytes!("test_data/aac_quad.ts"); + let catalog = import_ts(data); + + assert_eq!(catalog.audio.renditions.len(), 1, "expected one AAC track"); + let audio = catalog.audio.renditions.values().next().unwrap(); + assert_eq!(audio.codec.to_string(), "mp4a.40.2"); + assert_eq!(audio.sample_rate, 48_000); + assert_eq!( + audio.channel_count, 4, + "two channel pair elements, not a guessed stereo" + ); + + // The element moved into the description is byte-for-byte what ffmpeg itself writes as the + // AudioSpecificConfig for the same stream in MP4, minus the trailing SBR sync extension. + let mut expected = vec![0x11, 0x80, 0x04, 0xC4, 0x04, 0x00, 0x21, 0x10, 0x0C]; + expected.extend_from_slice(b"Lavc63.1.101"); + assert_eq!(audio.description.as_deref(), Some(expected.as_slice())); +} + /// `opus.ts` is an ffmpeg-authored audio-only Opus program (private stream_type 0x06 /// plus the 'Opus' registration and DVB extension descriptors), generated with: /// `ffmpeg -f lavfi -i sine=frequency=440:sample_rate=48000:duration=0.5 @@ -174,6 +200,29 @@ fn import_opus_catalog() { assert_eq!(audio.channel_count, 2); } +/// `opus_5_1.ts` is a 440 Hz center channel in 5.1, which ffmpeg's libopus +/// encodes as family 1 and its muxer labels `channel_config_code` 6: +/// `ffmpeg -f lavfi -i sine=frequency=440:sample_rate=48000:duration=0.5 +/// -ac 6 -c:a libopus -b:a 128k -f mpegts opus_5_1.ts`. The descriptor names only +/// the channel count, so the importer must synthesize the Vorbis mapping table +/// or the track has no OpusHead a decoder accepts. +#[test] +fn import_opus_surround_catalog() { + let data = include_bytes!("test_data/opus_5_1.ts"); + let catalog = import_ts(data); + + assert_eq!(catalog.audio.renditions.len(), 1, "expected one Opus track"); + let audio = catalog.audio.renditions.values().next().unwrap(); + assert_eq!(audio.channel_count, 6); + + let head = crate::codec::opus::Config::parse(&mut audio.description.as_deref().expect("an OpusHead")).unwrap(); + assert_eq!(head.channel_count, 6); + let mapping = head.mapping.expect("a family 1 mapping"); + assert_eq!(mapping.family(), 1); + assert_eq!((mapping.streams(), mapping.coupled()), (4, 2)); + assert_eq!(mapping.table(), &[0, 4, 1, 2, 3, 5]); +} + /// Opus frames from real ffmpeg output must decode: a non-empty run of Opus packets, /// each a plausible size (the control header was stripped, not left in the payload). #[tokio::test(start_paused = true)] diff --git a/rs/moq-mux/src/container/ts/test_data/aac_quad.ts b/rs/moq-mux/src/container/ts/test_data/aac_quad.ts new file mode 100644 index 0000000000000000000000000000000000000000..17aff4786200068fa22e9b89662f19d2ce14ce7f GIT binary patch literal 2632 zcmd6oc~nzZ8o*x&5@etu7#5`(Ng_s&%_VhE*-QwKxUk4naAXTh6l4I|B#;EqAuL4< z5-JL5hDE0Aj0<5qKn@^P>0Xgo^1D+$nimvDz#4H10Fty* z004lA5yfowCKCWL8~`e4fVp%{P{?MhW3_1kaY4lWmNu3));6QS#wWn(l$NpEVVdK! zLtT>|J-0*HOm*J0JUoLUa8M9t8%V{u?Ge*ho-{ zTWH&EwqJz(p)$HUESAKRMLW>Tc;186b@kH1#g_${^a|ghs{`T<@r1+4DI$h%)x$gY z77@96dxH6UAvt%lqYGu`k*!x~3VFn1%BTM=7yE|YMK!Ii@C^tO*~so%pu0}ouhuE! zY=}HK+?W_XybtdJF(dRKcRjpEkCkedk7CwL+`^BaF>mOKr8lSE{%m#m^@tB2%*BXq zU&uKpQd;?a=(H=3%=!#fMV#nuo-R(fU{R2C#ZV-1Xl+IeTuCNiPL?;q7FLo8@R@~` z3+qWBMpg{YRQ0kC_WA7fDOE-^lT5fJgfHj0C06;Q*7@ZqZrarRYZ}Ii-%ZGX%`Y<_ zwCk$%6gP5AHpFhzs{9`tp7h;wOHSp@vLN>@qGFwDDp-*#ead;CoT9vhT=koL$|hEX zjK%c*;^k8Jj%C4D`fi)9Hn8wu5y!B)ZGHK)Wm1pj<)`ZDd1XY?sv8n|bHkqY3|MgA8S%9Z!Q*+m zB}(X_BfIQcU4Ifu`!t5iz`;)0w1cum#Ii-auT@Mt7<)EeY?{9N!K?K1IQxPg&>|;h zD9fPIzUX3}W?*QyDN`8CKN_m$l%P8A9e!&j32hR;&%4%GCtuVY`myaTqr8?HIa=_w z8wb2Puv&uIS`;rG#Y~QOEiS?*$C0cAN@qs^wmW z@K0s;=cuR49Kgqnk6ZoKb)vsXrnFaDt%;=Xr>M`ZY$cSG zhYv=bHHF*@{XweF)bNr!iHvq}5+-X_YMR+r-O}u^QTNnikZc`4xzfi{fC|=>5|o*p zt4ti~KK#>I_o!Pd+TG%^c9?4MxlBTakgMr+@+-*QP~T(|0b#2qyf3=y+{SMpMtFZ6iR4hr&!OLFlBv<$JP=qx*CEgjjX@yIIg4v}^f! zJMOoiQI;fI$~@j&cm33zfj=q6G98v?Gn^$Hxiym%oQ-626{rGhJFVSq6c_Olp#-%Z z2OqDQW#WzLLh4)16qIO%RWZbmuZ*T%r)c}QF0fk_@W~nz;}FDfs{(b;p9#4eX=6}Z zgW%&rCh1Z(G8IA&SlhwJMCzTafH^6f_^Nwud1;sLd7M$($aY)>R=;lr%*~*F*R-n( zA5)EAa`?8P_~{j1cymneuiW2au4^tvw%SOClkSh}+;4c;lCs(RWo~TCW@CC$P-*P> zTVUt}ubICPzqwy!(M*3dIH@^<5^5o`)({8X2f9tEG}s;f3H6bMr@Z)#1Ielg?a%Mg^7 zevv9P3){2D>Yl3gI`BzOW)b!)LH}MaiN0Im^BXOn9U8jX6isc*>%tC@fJb-k5Cp>V z)FuY5`Lw}HXd+H<2jaO=e^9mhI`F>*mOr@@cHj^CL^3KnFsGdSE90fhzw#JZE%~;P zz4#-LyX|4%|NqT1Is(Ov4(n?QHx*CgmPZp3UAw7VHE6CHJe#<{JWPy?AAcr)C;3L2 zMrp^kI1)zBIokF~8;$DE6TzBGEODD$-5! Qn0E6##`H6}Y$K`j-^lX>rT_o{ literal 0 HcmV?d00001 diff --git a/rs/moq-mux/src/container/ts/test_data/he_aac.flv b/rs/moq-mux/src/container/ts/test_data/he_aac.flv new file mode 100644 index 0000000000000000000000000000000000000000..5bf778ce3c02107160e456ee1dca1f0b63c0e1b5 GIT binary patch literal 3110 zcmd5;c~BEq9DW-z5D+90P*g0&0wP|KQILWm96}Y3P!$9f2_$BM=8*dmQP4q-;ZhML zU~L>xK`Mw^AP_-X7!fRrNWl=qyFo5f5eVtqBv?D`Uv^;nZQkzNcl_S>e);y>b=%~H zU;zNyuz*kNY*l7@$WBqqDel zI0W`E0L9ToIT`3H+e2t<-T{WH=N0dtJt3@UIESR_0Gc78j9>;AL4dAub|9C|2xQR# z#Y{b52AdYd4c;3NOykfo0L$jBwg!4^76-P4GlD}PF$_RRfDp)K^B~WF0}R#J5DdVh zgJD_43gNP0u?Dz(tOE=cfx=Dd1z-*k0Qah?zAphw2}x+302_-Y8xbOLJusvqZhc}v zR5s4k1xUQ!K!D+m{}-wtyIYWYBLGWLq9q8?qbXirp-^BYQQ_z8FK-v?wC@RPeOoqB z;5c@0c8=qS+_C@V$a;GDuNmt?aoM{u7B{fNH8s-y>NtZmM?%-E*CuCU=z17mY>83d zp_0HS8@2B0@SWS5iqs)&ifl z*h}ZawqX;+LhIUn!l?b)9?|cKa*lL7(_N%VF#{LsfP=n%Z)pWBzx)vf<1L| z(`OUz6+8m_seNDpW??S&+lrWH>uB=KYSpFcc{4ta&rYd0H8(3m?BAfI)A3yGEB5}IvRqR{tlwrEI zO|SxG4S@&`IG>&#xPs>Wa8tHa zF069=s>>3)X-h>kxuIii^DpMlx|iXH%I&D4^<~VmefKlzTFq-%Gn4^f46Zl+;xs@4 zmr_gSGnbiA8J{-Jh(K=XY$+LkdjvkHXW!J7{FJAW@!ZaJ^j59&x)$@-L^<8e%_2Or)2vFu0l$+xyq+OjCAU$9H<*r{-P+zwc1|?S(U$_nL7T zMJkmJ)6%)QPc*hPXCy_svK0F+*vIV|Qg3>MhznS!R@R>dNri1zV zBU=N<-P6X~3~?)-iS6#(yp7%9$=uAh3GH~uE=CXa&A(i_pS%M88ea%&dSfo*w9lvC zJ_`$S5}!+fUkK&Lfruy}N*14D-}uY}MR2>n!|g@`%qL?yDT?i*`IF*#k&1j0ej74e sek{HgxzjrlDRScKv{q%ghGO*PVD`6gE`GJ@yIKUqe*ejeP$I|v1S3oeTL1t6 literal 0 HcmV?d00001 diff --git a/rs/moq-mux/src/container/ts/test_data/he_aac_v2.flv b/rs/moq-mux/src/container/ts/test_data/he_aac_v2.flv new file mode 100644 index 0000000000000000000000000000000000000000..1df313b4099b5f084b889f928d0e7a24784f352c GIT binary patch literal 3297 zcmd5;dpOf;9Djc^8Z}Kxky-T*>-|z3c&+lFB;)Y-W0Lrj{ zX#fnOH3SBzu!7byLTPriP#O*nr~n+D6G97RvVwqhce8GNw~sBr(>Qb{iw>8-83v$O zQ)*CSFjYFvrUeEEFk~}5!P1F;%&?ieppA)a0w}RV86gZ7f`BPfYhMO~R*3hO5Lyr&1F(U?q@@5K$P9vGTt)~R62kz*1gQD40)rvXEddPKS~dm{(8aKr zGTE#^Se63ZR%QT0M&Ls2_yI5m2!OsSjra4xYvlyAtp*1#$_EjIqANJHb#NXc9l@Rl zO2bhq9zP(wAi-itJr96IDA#;Q-Bxglry7O!6ykdA5Q+6Lr0@FU(MP$LK<+I7Y(&{Y z?t~-h?QCv_^W`SpGHt#5F+4})<^RfTjK~sKmgJT>jdc!1uuh0ncC^_sUaMB|c}b}6QA z^=F&boo2sjkL|fvndIQ9TJ6+Serx1TdfUWlAW@U z^FU-qCSNVy)Of$H?$0+PqSxMe*w|x9<{Y;ivCtCnHc#>J89Fs;OFXH+yu-65R0Z`2 zGpGy3h@${lz)lZzH6H*0IsskP__(Cd9=GDTXIoXc*!o1&!MXgyV8nbUk8G7q9c8-za6E(vhcg%Q)@cUe|egtXAcZuZ$v5dt41` zA>qt_LOV2%m*u+<-3rYa67KL$in{I84UTUmE1L&La*UClM48MWa+x7O>MLN_6$sHc)~CI1XsfPGx}$l2@9)iTdhT?Au4VTta^F_;C-z*$ zT*~JNQ9RCaKg+PY`Cz3Y>H#tf%of@$WKJ}A@GLa!c>wt$GmyKfCDu^6LtI%NY5C3_ zsi#t@+j5hSfZ6X)M_3gv=yIjL#Na)y`3rMqxX-TeeN}IOa>mtw)-oOE?}nOj?l5Hp zuqjU&l4Sx;2T8D@5sjPks`+t?JSlyBeIG^Z-Y`ri#pW3h8X}1E%kM~dqHs}F@`b2; zuSy=5E1nt?x@D8glPoH_m6`ylB-tLGD5On-XN;$eTr^gaW@wm_6AbwG4|b1+^CGKw zKW`EwCW_WONl;(0{7wbk#LjLd=czSBE}y42yeH^J2(kt7T8(y?6A2E(^;myU86GEsCz38#c@e8Nm4+bg{8Y~Vwckih$@h?&uPTF) ztBmwLGfnNr3^i-xCl9Mf2kqni{QPcDi8xNnQdn1a0LL?Kx>4aBH_)zx!j4Rk@V9Gx zjrMEXiH-J`mxes-B7l*r%o5V#{arqawwj&~!!kOZ)yoh=AWT=-@lx;(WN$2beDn${ z(7Ajlp8VH>&BK22qvtk`I24FG3njugR4?<6((6SfME&zc4YE&Zle{IX3$kw|X&G%R zYPfo~E(12k`vuvD9PLK*&pQyL0f9fsT4q1F+%vjzmyXxI0_%VKHI+Fsd)K636E4|lK%z_QapPA literal 0 HcmV?d00001 diff --git a/rs/moq-mux/src/container/ts/test_data/opus_5_1.ts b/rs/moq-mux/src/container/ts/test_data/opus_5_1.ts new file mode 100644 index 0000000000000000000000000000000000000000..14ad7cb9c04960dcb68052e1a3177667cb971d93 GIT binary patch literal 5452 zcmdUzc{G&k1IOP{_PtEm%FTRI-LqG}PcXW;EyC)31B(xqsZ>HRrtZ&%E#V`9AOS`8@BO7j7sj0vJ;j z08kqMtbx`55IsuFVjGCd+&m!A%bVBE>(@}9lU`~N^hJ}7wSU(KZU~3~K#d@?I{=~r zO0`?-{#_M+*amLH=+03i&FuaLpaNWsFFww#sKAh53`Z2#&9TmfA71=_{sC?TsBzl> zK)668005w7PLqR209ig4x!K}$#w@OmJ) z?M;KG)nKuZy<5CkoO72%M=x&c(%LG9f?^M6obL@9r(==U<>Dn0Bkx_DM!udQXm~A_ z79j*j9nf(pe8xR#a1bDBp1LB_2MatzBWIQB9*aJr5XgUfF!P|aFv^H_wV9a;XQx7O zbt55o`eCTq`Szii(FV}sbmiBX+IJ(~Uy)Pv;aF^Xa}+pOsuic~R~9<%9^K57zxZ;T zrZRMq^M5Cq&Ah7aoo~Ol+8QJ=+?gIrG$?b76blfavgG1!`1J|;ZrH)_aBun72ljrJ za_xg2-hS3ekeOt`=&pVi_-7ZNeIH<~`+(56E3vq%8SkxLWv`_hZk_fM)u<}@LiYlw zzc|`zY4pXMm{oe!(V6Qc3u~Pv#S*{Ii1+IY#c)-06T2$9iCxuLclBDqhO4nmS9y2W zVkk)V;u_+TC~0?Z-!|0fA9U#(D!H&gq*T97ED^snS*qWW>sD)&X+h$a?5!Rxp2iKo zq%IGi(si>vc(&7*EXDVc1V%CewPWX*QH zhX7W*(>LvhqL%Nxpg`EmDe`3^Q!dQ;gGhlqN^xk&PS57*5V>*f)w+$WAWL?TJ}by< z<}sN6e%icL<7|lFkZ|6OUE=9PA|$?ZX(%_x9<|Mah%pqq|ndKkVvX+8N%iA6vfi;qr=ySi-?yQ;nJYM$nXtL7|My+9bsAvSC3IhHaE0}v4PsevVK z144a;@n`OZ`mViY68mGh0-7owyIW2)M)0@2IReAiEFlm)I9B0o~W`^z!|^x4hSSj`|Bb$MPIT%_RL#aS{> zIAmL8pZ^Bsxd-ygpDtUj30~8P^t<=cwBp%3P#-r&8M#e0P< zh5}`;s4AQHfa`k{M*G5wm)cdKEnn*p(epmlPVwO9PQ()gNkucUk4lYLCJsjIi#1s| zsLml_IaO7z5&DusMKV2VN2JRNmhT&-zN@>U`nkh9dnaGs7m0dds$~IR&^VQu;lj>9 zZNPq1>hno~wEp|p5CX!H!Mg-E#pdk=o(1B$8t8O!~ zJBSbLQfEiyW|{fU?0oB5!pFE{dWla;O;iJ~FuFs7|HRe5^c?vcC+XOlO6V2%Ai-@e z*FkHu_#R%{|K!mZILh~==NhVbnavYN>H|To!7xoR`s1`h8W#NW-1*|GBzMJq4G{IH zf%RE2{zr;!VpqjBv8%9kSKC}RTpeM#I#0k*e#cqOFY||dE#6aH`Z~^K6{hf<589Qv zGvDe=Df|@8_t)1H8|dtYaDYS*2e?$B*6?3 zBwoDqVEj9Zt0yI;Q<8LM^lypbo+=ersXeexDQf%24O`T~h0 z9=AYRc*<}F?4N$Z;9c69<5OY?4eQhO@dN5%%guqEg4bWY{Pf)jHOOvlbMvONCmMVd zxI33sGMR*&9g%s*fh;oWcw*J`}1kmID zMhUIhKW(3{d4_gPN?D|~dQv!r(On<<_g&ShJZxQ*`zQjtLYGiqUKvLPIjh%A_lod1 zrhGT|>Phj|Y+t*pgq#J-0P%69J^S699f!3c1$`kNSlcr|N$6~fe^u7hN)NwB(xbc; zVwBJp{|~+JH=+voIVI(c6^AX`Pwy#{B@gb?E2VD$ literal 0 HcmV?d00001 diff --git a/swift/Sources/Moq/Aliases.swift b/swift/Sources/Moq/Aliases.swift index dcfef7b25ea..c864511cfff 100644 --- a/swift/Sources/Moq/Aliases.swift +++ b/swift/Sources/Moq/Aliases.swift @@ -52,7 +52,7 @@ public typealias VideoDecodedFrame = MoqVideoDecodedFrame public typealias AudioDecoderOutput = MoqFFI.MoqAudioDecoderOutput /// A raw PCM sample format, mirroring WebCodecs `AudioData.format`. public typealias AudioSampleFormat = MoqFFI.MoqAudioSampleFormat -/// Selects the audio encoder codec. Build one with `AudioCodec.opus()`. +/// Selects the audio encoder codec. Build one with `AudioCodec.opus()` or `AudioCodec.aac()`. public typealias AudioCodec = MoqFFI.MoqAudioCodec /// One raw video frame: pixels in the configured layout plus a presentation /// timestamp. diff --git a/swift/Sources/Moq/Broadcast.swift b/swift/Sources/Moq/Broadcast.swift index 15a29613c6d..d7b3f6e555a 100644 --- a/swift/Sources/Moq/Broadcast.swift +++ b/swift/Sources/Moq/Broadcast.swift @@ -273,7 +273,7 @@ public final class BroadcastProducer: Sendable { /// Open a raw-audio track. PCM written via `AudioProducer.write` is encoded /// inside the FFI boundary per `input`/`output`. Select the codec with - /// `AudioCodec.opus()` (currently the only constructor), placed in `output`. + /// `AudioCodec.opus()` or `AudioCodec.aac()`, placed in `output`. /// /// Pass `bandwidth` to reserve this track's bitrate against the session's /// allocator so a co-resident video encoder sizes itself against what is left. From 5124f813497a54e070ebb05282278533c807ee6f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 09:51:10 -0700 Subject: [PATCH 110/128] quest(moxygen): Moxygen compatibility (#4253) Co-authored-by: Claude Opus 5.5 --- dart/moq_ffi/lib/src/moq.dart | 4 +- doc/concept/standard.md | 31 +- doc/lib/rs/moq-net.md | 2 +- drafts/draft-lcurley-moq-e2ee.md | 3 +- go/wrapper/README.md | 2 +- go/wrapper/types.go | 1 + js/net/src/ietf/priority.test.ts | 5 + js/net/src/lite/track.test.ts | 2 +- js/net/src/track.test.ts | 4 +- js/net/src/track.ts | 12 +- kt/README.md | 2 +- py/moq-rs/README.md | 2 +- quest/m0/ietf-legal-input.md | 2 +- quest/m0/ietf-subgroup-refusal.md | 4 - quest/m1/README.md | 3 +- quest/m1/datagram-unfetchable.md | 3 +- quest/m1/e2ee/README.md | 2 +- quest/m1/ietf-fetch-location.md | 23 + quest/m1/ietf-fetch-only.md | 29 + quest/m1/js-ietf-datagram.md | 32 +- quest/m1/moxygen/README.md | 40 -- quest/m1/moxygen/datagram.md | 23 - quest/m1/moxygen/fetch.md | 31 - quest/m1/moxygen/priority.md | 28 - quest/m2/signed-priority.md | 13 +- rs/libmoq/src/api.rs | 6 +- rs/moq-e2ee/tests/transport.rs | 17 +- rs/moq-ffi/src/consumer.rs | 2 +- rs/moq-ffi/src/producer.rs | 5 +- rs/moq-net/src/fuzz.rs | 3 +- rs/moq-net/src/ietf/datagram.rs | 301 ++++++++ rs/moq-net/src/ietf/fetch.rs | 3 +- rs/moq-net/src/ietf/mod.rs | 2 + rs/moq-net/src/ietf/publisher.rs | 916 +++++++++++++++++++----- rs/moq-net/src/ietf/session.rs | 25 + rs/moq-net/src/ietf/subscriber.rs | 956 ++++++++++++++++++++++++-- rs/moq-net/src/lite/test_transport.rs | 17 + rs/moq-net/src/lite/track.rs | 2 +- rs/moq-net/src/model/bandwidth.rs | 11 +- rs/moq-net/src/model/datagram.rs | 6 +- rs/moq-net/src/model/resume.rs | 38 +- rs/moq-net/src/model/track.rs | 38 +- rs/moq-net/tests/datagram.rs | 102 +-- rs/moq-tokio/tests/broadcast.rs | 137 ++++ swift/README.md | 2 +- 45 files changed, 2415 insertions(+), 477 deletions(-) create mode 100644 quest/m1/ietf-fetch-location.md create mode 100644 quest/m1/ietf-fetch-only.md delete mode 100644 quest/m1/moxygen/README.md delete mode 100644 quest/m1/moxygen/datagram.md delete mode 100644 quest/m1/moxygen/fetch.md delete mode 100644 quest/m1/moxygen/priority.md create mode 100644 rs/moq-net/src/ietf/datagram.rs diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index e4d5f7532b5..b91803e2d79 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -1775,7 +1775,7 @@ class MoqTrackInfo { final int? maxAgeUs; final int? timescale; MoqTrackInfo({ - this.priority = 0, + this.priority = 127, this.maxAgeUs = null, this.timescale = null, }); @@ -12573,7 +12573,7 @@ void _checkApiChecksums() { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqtrackconsumer_recv_datagram() != - 29049) { + 17412) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqtrackconsumer_recv_group() != 60887) { diff --git a/doc/concept/standard.md b/doc/concept/standard.md index 54801adec8a..a5d59d0daaa 100644 --- a/doc/concept/standard.md +++ b/doc/concept/standard.md @@ -34,18 +34,35 @@ the block; other groups and the session stay open. An IETF publisher declares the track's default priority in `SUBSCRIBE_OK` or `PUBLISH` when that draft carries track properties. Groups without a priority flag inherit it. If the property is absent, the IETF wire default of 128 maps -to model priority 127, where higher values are served first. - -On drafts 14–19, the Rust publisher serves relative joining `FETCH` requests -with offset zero for `NextObject` subscriptions. The fetch delivers the saved -current-group prefix, and the subscription delivers later objects. Standalone, -absolute joining, and nonzero-offset fetches are refused. Draft-20 uses -subscription fills instead. JavaScript publishing does not yet serve `FETCH`; +to model priority 127, where higher values are served first. A track that +never sets a priority is 127 as well, so it goes out as 128 on IETF and 127 +on moq-lite. + +On drafts 14–19, the Rust publisher answers a standalone `FETCH` within one +group from the cache. A relay fetches a missing group upstream with a `FETCH` +of that one whole group, and an upstream refusal is the refusal the fetcher +sees. A range touching several groups is refused with `NOT_SUPPORTED`, as is +any `FETCH` on draft-20 and later, which moved the range into +`LOCATION_FILTER`. A standalone `FETCH` +carries no timestamps, since no `SUBSCRIBE_OK` declared a timescale for it. + +On drafts 14–19, the Rust publisher also serves relative and absolute joining +`FETCH` requests for `NextObject` subscriptions, for the subscription group's +saved prefix only, while the subscription delivers later objects. One reaching +back to earlier groups is refused with `NOT_SUPPORTED`. Draft-20 uses +subscription fills instead. JavaScript +publishing does not yet serve `FETCH`; Rust and JavaScript subscribers request unfiltered delivery on older drafts because they do not issue joining fetches. Other publishers may replay a cached backlog for that filter; selecting the next group instead would leave static tracks waiting for a group that never arrives. +A moq-lite datagram is a single-frame group, so on moq-transport it travels +as an `OBJECT_DATAGRAM` at object 0 whose Group ID is the sequence, and a relay +forwards it without renumbering. A datagram carrying any other Object ID, or a +status other than Normal, is dropped. JavaScript does not yet carry datagrams +on moq-transport. + A client may present one credential in its `SETUP` with the `AUTHORIZATION TOKEN` option. The server reads a value (`USE_VALUE`, or `REGISTER`, which it treats as a value since it advertises no token cache) and hands its Token Type diff --git a/doc/lib/rs/moq-net.md b/doc/lib/rs/moq-net.md index 910211481f8..322894a4c3c 100644 --- a/doc/lib/rs/moq-net.md +++ b/doc/lib/rs/moq-net.md @@ -21,7 +21,7 @@ above ([hang](/lib/rs/hang)); relays and CDNs implement only this. - **Tracks** carry groups with a priority, a retention window, and a timescale. Subscribers set their own priority and max age and can change them live. - **Groups** are written frame by frame and delivered on independent streams. Old groups are cached for fetch-by-sequence; stale groups are skipped per the subscriber's budget. - **Track ends**: `finish()` ends a track at its live edge, while `finish_at(n)` declares the exclusive end ahead of it and still accepts the groups below. A subscriber awaits it with `finished()`. A remote track ends only once every group below its end has arrived or was dropped; one reset before its header arrived is skipped after the subscription's max age on moq-lite (one second without one), or after one second on IETF. -- **Datagrams** send a single small frame unreliably on moq-lite 05+. +- **Datagrams** send a single small frame unreliably on moq-lite 05+ and moq-transport. - **Routes** record the relay hops and a cost, which is what the relay [cluster](/bin/relay/cluster) routes on. A hop of 0 marks the chain anonymous: `Route::is_anonymous()` is true, and that route ranks below every fully identified one. `Route::source()` says where a delivered route entered: `Source::Local`, or `Source::Peer(hop)` when a handle marked `origin::Producer::peer()` announced it. `origin::Consumer::local()` sees only the local ones. - **Stats** counters per broadcast and session, drained by [`moq-stats`](https://docs.rs/moq-stats). diff --git a/drafts/draft-lcurley-moq-e2ee.md b/drafts/draft-lcurley-moq-e2ee.md index ec68f21aa9c..25ca49c8eac 100644 --- a/drafts/draft-lcurley-moq-e2ee.md +++ b/drafts/draft-lcurley-moq-e2ee.md @@ -227,7 +227,8 @@ An Object ID above `2^32-1` MUST be refused as `identity` before encryption or d ## Datagrams A datagram uses `domain = 0x01`, its 64-bit sequence as `group`, and `frame = 0`. -MoQ Transport has no datagram mapping in this profile; shared vectors cover grouped tracks on both transports and datagrams on moq-lite only. +On MoQ Transport, a datagram is an Object at ID 0 in an OBJECT_DATAGRAM whose Group ID is the sequence. +Shared vectors cover grouped tracks on both transports and datagrams on moq-lite only. ## Nonce The 96-bit AES-GCM nonce is: diff --git a/go/wrapper/README.md b/go/wrapper/README.md index 781c8d055e9..1f9d3750301 100644 --- a/go/wrapper/README.md +++ b/go/wrapper/README.md @@ -110,7 +110,7 @@ Raw tracks support best-effort datagrams alongside groups: `TrackProducer.Append sends one `Frame` and returns its sequence number, while `TrackConsumer.RecvDatagram` and `TrackConsumer.Datagrams` receive them in arrival order. Payloads are capped at 1200 bytes. Datagram delivery requires a datagram-capable transport and lite-05 or -newer moq-lite; IETF moq-transport, pre-lite-05, WebSocket, and TCP paths do not +newer moq-lite, or moq-transport; pre-lite-05, WebSocket, and TCP paths do not deliver them, and there is no stream fallback. ## Versioning diff --git a/go/wrapper/types.go b/go/wrapper/types.go index 3c588ba2dfa..a0d490ccbaf 100644 --- a/go/wrapper/types.go +++ b/go/wrapper/types.go @@ -48,6 +48,7 @@ type ( // Subscription holds subscriber-side delivery preferences: priority, ordering, max age, and group range. Subscription = ffi.MoqSubscription // TrackInfo holds publisher-side track properties: priority, ordering, max age, and timescale. + // A zero Priority is the least urgent, not the default; set 127 for the midpoint a nil TrackInfo uses. TrackInfo = ffi.MoqTrackInfo // Video describes one catalog rendition, including whether the publisher recommends temporarily avoiding it. Video = ffi.MoqVideo diff --git a/js/net/src/ietf/priority.test.ts b/js/net/src/ietf/priority.test.ts index a05f8b26505..b04da83354e 100644 --- a/js/net/src/ietf/priority.test.ts +++ b/js/net/src/ietf/priority.test.ts @@ -1,4 +1,5 @@ import { expect, test } from "bun:test"; +import { infoDefaults } from "../track.ts"; import { fromWire, toWire } from "./priority.ts"; test("IETF subscriber priority is lower first", () => { @@ -17,3 +18,7 @@ test("subscriber priority round trips", () => { expect(fromWire(toWire(priority))).toBe(priority); } }); + +test("an unset track priority is the draft's usual publisher priority", () => { + expect(toWire(infoDefaults().priority)).toBe(128); +}); diff --git a/js/net/src/lite/track.test.ts b/js/net/src/lite/track.test.ts index ca4d25d44f9..34217581b9f 100644 --- a/js/net/src/lite/track.test.ts +++ b/js/net/src/lite/track.test.ts @@ -48,7 +48,7 @@ test("TrackInfo round-trips on draft-05", async () => { test("TrackInfo defaults match cross-language wire bytes", async () => { const info = new TrackInfo(infoDefaults()); expect(await bytes((w) => info.encode(w, Version.DRAFT_05), Version.DRAFT_05)).toEqual( - new Uint8Array([0x06, 0x00, 0x00, 0x53, 0x88, 0x43, 0xe8]), + new Uint8Array([0x06, 0x7f, 0x00, 0x53, 0x88, 0x43, 0xe8]), ); }); diff --git a/js/net/src/track.test.ts b/js/net/src/track.test.ts index c8c516b67e6..04ac64ae9ba 100644 --- a/js/net/src/track.test.ts +++ b/js/net/src/track.test.ts @@ -27,9 +27,9 @@ function mockMonotonicTime(initial: number) { }; } -test("priority reads the committed info and is 0 before accept", () => { +test("priority reads the committed info and is the midpoint before accept", () => { const producer = new TrackProducer("video"); - expect(producer.priority).toBe(0); + expect(producer.priority).toBe(127); producer.accept({ priority: 60 }); expect(producer.priority).toBe(60); }); diff --git a/js/net/src/track.ts b/js/net/src/track.ts index 52dc4034e01..45df6e4320f 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -30,6 +30,10 @@ const PRUNE_SLICES = 8; /** Default {@link Info.maxAge} window (milliseconds) when the publisher does not set one. */ export const DEFAULT_MAX_AGE_MS = Milli(5000); +// The higher-first midpoint. IETF flips priority (lower first), so this goes out as 128, the +// draft's usual publisher priority, while moq-lite carries 127 as written: one urgency on both. +const DEFAULT_PRIORITY = 127; + /** Maximum buffered datagrams per subscriber; mirrors Rust's bounded send buffer. */ const MAX_DATAGRAMS = 64; @@ -70,7 +74,7 @@ export interface Info { * or non-finite value and a result past `Number.MAX_SAFE_INTEGER`. */ maxAge: Milli; - /** Tie-break priority between subscriptions of equal subscriber priority (`0..=255`). */ + /** Tie-break priority between subscriptions of equal subscriber priority (`0..=255`, higher first). Defaults to `127`. */ priority: number; } @@ -103,7 +107,7 @@ export function infoDefaults(info: Partial = {}): Info { return { timescale: Timescale(info.timescale ?? Timescale.MILLI), maxAge: maxAgeMillis(info.maxAge ?? DEFAULT_MAX_AGE_MS), - priority: priorityByte(info.priority ?? 0), + priority: priorityByte(info.priority ?? DEFAULT_PRIORITY), }; } @@ -481,13 +485,13 @@ export class Producer { } /** - * Publisher priority from the committed {@link Info}, or 0 before {@link accept}. + * Publisher priority from the committed {@link Info}, or the default before {@link accept}. * * Higher is served first. Hang publishers set this from `Catalog.PRIORITY` so * audio outranks video on the wire and in the bandwidth allocator. */ get priority(): number { - return this.#state.info.peek()?.priority ?? 0; + return this.#state.info.peek()?.priority ?? DEFAULT_PRIORITY; } /** diff --git a/kt/README.md b/kt/README.md index 2afe6524f6d..7e0958fd691 100644 --- a/kt/README.md +++ b/kt/README.md @@ -52,7 +52,7 @@ The `dev.moq` package is intentionally thin: Kotlin has extension functions, so - **Fetched media**: `fetchMediaGroup(...).frames()` streams the decoded frames of one retained group, then completes. - **Duration extensions** (`Durations.kt`): the FFI carries microseconds as integers, so `stats.rtt`, `backoff.initial`, `frame.timestamp`, and their siblings read back as a `kotlin.time.Duration`. - **`logLevel(...)`**: configures native Rust tracing without importing the raw bindings package. -- **Raw datagrams**: `TrackProducer.appendDatagram(Frame(payload, timestampUs))` sends one best-effort frame and returns its sequence; `TrackConsumer.recvDatagram()` and `datagrams()` receive them. Payloads are capped at 1200 bytes, require a datagram-capable transport plus lite-05 or newer moq-lite, and have no stream fallback. +- **Raw datagrams**: `TrackProducer.appendDatagram(Frame(payload, timestampUs))` sends one best-effort frame and returns its sequence; `TrackConsumer.recvDatagram()` and `datagrams()` receive them. Payloads are capped at 1200 bytes, require a datagram-capable transport plus lite-05 or newer moq-lite or moq-transport, and have no stream fallback. - **`MoqException.isShutdown`** (`Errors.kt`): true for the graceful `Cancelled`/`Closed` cases. ## Versioning diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index 420227f31a7..75d2c1ea877 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -212,7 +212,7 @@ Every handle whose cleanup is `cancel()` is an async context manager, so exiting - **`Catalog`**. `.audio: dict[str, Audio]`, `.video: dict[str, Video]`, `.display`, `.rotation`, `.flip`. - **`Frame`**. `.payload: bytes`, `.timestamp_us: int`. The unit of every write and every raw read. - **`MediaFrame`**. `.payload: bytes`, `.timestamp_us: int`, `.keyframe: bool`. Returned by media subscriptions. `keyframe` marks a group start or video keyframe; for audio it is true only at a group start. -- **`Datagram`**. `.sequence: int`, `.timestamp_us: int`, `.payload: bytes`. Delivered only on datagram-capable transports and lite-05 or newer moq-lite. +- **`Datagram`**. `.sequence: int`, `.timestamp_us: int`, `.payload: bytes`. Delivered only on datagram-capable transports with lite-05 or newer moq-lite, or moq-transport. - **`Audio`**. `.codec`, `.sample_rate`, `.channel_count`, `.bitrate`, `.description`. - **`Video`**. `.codec`, `.coded: Dimensions`, `.display_aspect`, `.bitrate`, `.stalled`, `.framerate`, `.description`. A true `.stalled` recommends temporarily avoiding the rendition without making it unavailable. - **`Subscription`**. Subscriber delivery preferences: priority, staleness, and optional group range. diff --git a/quest/m0/ietf-legal-input.md b/quest/m0/ietf-legal-input.md index c90b5f547bf..32ebf87922b 100644 --- a/quest/m0/ietf-legal-input.md +++ b/quest/m0/ietf-legal-input.md @@ -14,7 +14,7 @@ Each of these closes the session today with `PROTOCOL_VIOLATION`: - FETCH on drafts 20+ still decodes the removed Fetch Type field (`ietf/fetch.rs`). Decode the draft-20 layout: namespace, name and params, with the range in LOCATION_FILTER. Refuse it `NOT_SUPPORTED` until - [moxygen FETCH](/quest/m1/moxygen/fetch.md) serves it. Fix the encoder and + [Draft-20 FETCH](/quest/m1/ietf-fetch-location.md) serves it. Fix the encoder and the pinned test in `version.rs`. - Request parameters the draft allows on a message fail `decode_params!`: AUTHORIZATION TOKEN (0x03) anywhere, NEW_GROUP_REQUEST (0x32) and the diff --git a/quest/m0/ietf-subgroup-refusal.md b/quest/m0/ietf-subgroup-refusal.md index 969ea143388..872ad8504c2 100644 --- a/quest/m0/ietf-subgroup-refusal.md +++ b/quest/m0/ietf-subgroup-refusal.md @@ -20,7 +20,3 @@ is the check. Moved from the moxygen line to m0 in the 2026-09-30 audit: a non-zero subgroup ending the upstream session is exactly m0's "legal input never fails a session", and moxygen will send it at Seattle interop on 2026-10-12. - -## Related - -- [Moxygen compatibility](/quest/m1/moxygen/README.md) - subgroups stay out of scope; only the blast radius is in diff --git a/quest/m1/README.md b/quest/m1/README.md index 5cef63b6d7a..12f1f067c0a 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -61,7 +61,8 @@ QUIC studies there on that rule. - [Data track clock](/quest/m1/data-track-clock.md) - JSON and binary data tracks stamp on the catalog's clock at write time, matching the media's anchored clock - [Go and Dart doc samples](/quest/m1/doc-samples-go-dart.md) - Go and Dart doc samples compile against their wrappers - [Data capture in bindings](/quest/m1/data-capture-bindings.md) - moq-ffi and every wrapper pass a data frame's capture time, and the JSON window producer takes one -- [Moxygen compatibility](/quest/m1/moxygen/README.md) - one subgroup per group, whole-group FETCH, and one datagram per group, never a full moxygen pass +- [Draft-20 FETCH](/quest/m1/ietf-fetch-location.md) - a draft-20+ FETCH within one group is served from its LOCATION_FILTER, as older drafts are +- [Fetch without SUBSCRIBE](/quest/m1/ietf-fetch-only.md) - a relay fetches from an IETF upstream without subscribing, finished tracks included, with End of Track always reported - [JS IETF datagrams](/quest/m1/js-ietf-datagram.md) - `@moq/net` sends and receives datagram groups over moq-transport, like Rust - [Datagrams are live-only](/quest/m1/datagram-unfetchable.md) - no FETCH, replay to a new subscriber, or cache fill ever returns a datagram group - [#2991](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - one dynamic producer per track name in both languages, with the sequence namespace surviving a replacement diff --git a/quest/m1/datagram-unfetchable.md b/quest/m1/datagram-unfetchable.md index 2de867c657f..76fa052c69d 100644 --- a/quest/m1/datagram-unfetchable.md +++ b/quest/m1/datagram-unfetchable.md @@ -24,7 +24,7 @@ datagram flag, and reports it as "unsupported": - A received fetch object with the datagram flag is refused as not fetchable. It fails only that fetch or fill, not the session, because draft-16+ allows the flag (maintainer, 09-29, on Codex's review). That covers the relay's group - fill (`recv_group_fetch_objects`, on the moxygen line) and the joining-fetch + fill (`recv_group_fetch_objects`) and the joining-fetch fill (`run_fill_objects`). - Update `drafts/draft-lcurley-moq-lite.md` to say datagrams are neither cached nor fetchable, and `doc/concept/`. Run `just drafts check` and @@ -51,6 +51,5 @@ range apart from one dropped for any other reason. ## Related -- [Moxygen compatibility](/quest/m1/moxygen/README.md) - says it carries one datagram per group live; this keeps them out of FETCH - [JS IETF datagrams](/quest/m1/js-ietf-datagram.md) - JS datagram send and receive over moq-transport - [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - datagram groups stay best effort there too diff --git a/quest/m1/e2ee/README.md b/quest/m1/e2ee/README.md index 07e41ce3c9c..0dcb75b674d 100644 --- a/quest/m1/e2ee/README.md +++ b/quest/m1/e2ee/README.md @@ -40,7 +40,7 @@ The Rust and TypeScript cores expose the same surface, and nothing else: - Deterministic secret-derived physical names hide catalog, codec, role, quality, timeline, and custom-track semantics. Authorized clients derive the encrypted catalog track name, then learn the remaining opaque names from its decrypted contents. Every catalog representation is encrypted; Rust publishers must not emit a plaintext MSF catalog. - A platform that forwards and meters protected bytes must never preview, record, archive, transmux, transcode, transcribe, compose, or inspect them, rejecting those paths before opening a processing session or writing product state. Applications needing those operations terminate E2EE outside the platform. A platform classifies protected broadcasts by its own credential or product state, never by name; the moq.pro (downstream) exclusion classifier and dashboard work stay downstream. -- The first proof covers browser TypeScript and native Rust publication and playback in both directions, with grouped audio and video over both moq-lite and MoQ Transport. Shared vectors cover groups and moq-lite datagrams; MoQ Transport has no datagram delivery. +- The first proof covers browser TypeScript and native Rust publication and playback in both directions, with grouped audio and video over both moq-lite and MoQ Transport. Shared vectors cover groups and moq-lite datagrams; JavaScript has no MoQ Transport datagram delivery yet. ## Required diff --git a/quest/m1/ietf-fetch-location.md b/quest/m1/ietf-fetch-location.md new file mode 100644 index 00000000000..54daf01a6a2 --- /dev/null +++ b/quest/m1/ietf-fetch-location.md @@ -0,0 +1,23 @@ +# [S] Draft-20 FETCH + +## Goal + +On drafts 20 and later, a FETCH whose LOCATION_FILTER stays within one group +is answered the way drafts 14 to 19 answer a standalone FETCH: from cache, with +a miss fetched upstream, and an upstream refusal passed through. A range +touching several groups is refused `NOT_SUPPORTED`, as on older drafts. + +## Plan + +Today both sides refuse FETCH on draft-20+ `NOT_SUPPORTED`: the publisher in +`run_fetch_stream`, and the relay's upstream group fill in `run_group_fetch`, +because the codec still carries the removed Fetch Type field. +[Legal IETF input](/quest/m0/ietf-legal-input.md) fixes the codec. Then drop +both refusals, and flip `fetch_moq_transport_20` in `rs/moq-tokio/tests` back +to a served fetch. + +Update the draft-20 note in `doc/concept/standard.md`. + +## Required + +- [Legal IETF input](/quest/m0/ietf-legal-input.md) - decodes the draft-20 FETCH this serves diff --git a/quest/m1/ietf-fetch-only.md b/quest/m1/ietf-fetch-only.md new file mode 100644 index 00000000000..a7bdc908e66 --- /dev/null +++ b/quest/m1/ietf-fetch-only.md @@ -0,0 +1,29 @@ +# [M] Fetch without SUBSCRIBE + +## Goal + +A relay serves a FETCH-only demand for an IETF upstream track without +SUBSCRIBE upstream. A finished upstream track can still be fetched, and a +FETCH_OK that reaches the end of the track says so every time. + +## Plan + +The origin splices a route only once the track's info is known. moq-lite gets +it from TRACK_INFO, so its fetch-only demand never subscribes. IETF has no +TRACK_INFO, so today fetch-only demand still makes the relay SUBSCRIBE upstream. +Two symptoms follow: + +- A finished upstream track refuses the SUBSCRIBE, so its groups cannot be + fetched either. +- The live subscription races the group FETCHes. End of Track is known only + once an upstream FETCH_OK reports it, so a downstream FETCH that runs to the + end can answer before that and leave End of Track unset. moxygen's "FETCH + with large objects" case flakes on this. + +TRACK_STATUS is the likely source of the info. The publisher refuses it today, +so both sides are in scope. Keep the SUBSCRIBE path for real subscription +demand. + +## Related + +- [JavaScript FETCH](/quest/m1/js-fetch.md) - the browser publisher answers these fetches diff --git a/quest/m1/js-ietf-datagram.md b/quest/m1/js-ietf-datagram.md index db210e7b25a..7ecfb8faabc 100644 --- a/quest/m1/js-ietf-datagram.md +++ b/quest/m1/js-ietf-datagram.md @@ -1,29 +1,21 @@ -# [M] @moq/net datagrams over moq-transport +# [M] JavaScript moq-transport datagrams ## Goal -A `@moq/net` session on moq-transport sends and receives datagram groups as -`OBJECT_DATAGRAM`, one object per group with its sequence kept, as Rust does. -A datagram track crosses IETF between Rust and JS in both directions in -`just test interop`. +`@moq/net` sends and receives datagrams over moq-transport as +`OBJECT_DATAGRAM`, matching Rust: one Object at ID 0 is a single-frame group +whose Group ID is the sequence. A JavaScript publisher's datagrams reach a Rust +subscriber, and a Rust publisher's reach a JavaScript one. ## Plan -- JS routes datagrams on moq-lite only (`js/net/src/lite/datagram.ts`, - `runDatagrams` from lite-05); `js/net/src/ietf/` reads and writes none. - Mirror the lite path on the IETF session and the Rust mapping from #4274: - receive decodes `OBJECT_DATAGRAM` and inserts on the aliased subscription's - track; send writes object 0 with END_OF_GROUP, the explicit publisher - priority, and the timestamp property when the track has a timescale. -- Keep Rust's edges: an Object ID other than 0, a non-Normal status, or an - unbound alias is dropped; a malformed Type closes the session. Rust covers - drafts 14 and later, whose Type flags differ between 14 and 15+; decide - what draft 07, which JS also speaks, does. -- Add IETF datagram cases beside the lite ones in the interop harness. +Port `rs/moq-net/src/ietf/datagram.rs` and the session's send and receive +loops. Decode every draft's Type flags, drop what the model cannot carry the +same way Rust does, and close the session on a malformed Type. -Public API: none expected. Wire: `@moq/net` moq-transport sessions send and -accept `OBJECT_DATAGRAM` as the drafts define; no project draft changes. +The integration test `ietf does not deliver datagrams` flips to delivery on +every supported draft, and `just test interop --all` covers both directions. -## Required +## Related -- [moxygen interop](/quest/m1/moxygen/README.md) - its datagram groups quest (done on the line) is the Rust side this mirrors and interops with +- [Datagrams are live-only](/quest/m1/datagram-unfetchable.md) - the subscribe range for datagrams, settled on both protocols diff --git a/quest/m1/moxygen/README.md b/quest/m1/moxygen/README.md deleted file mode 100644 index e478e9d0308..00000000000 --- a/quest/m1/moxygen/README.md +++ /dev/null @@ -1,40 +0,0 @@ -# Moxygen compatibility - -## Goal - -More compatibility with moxygen's moq-test suite, never a full pass. A peer -that speaks one subgroup per group, FETCH of whole groups, and one datagram -per group gets those through the relay. - -## Plan - -`conformance_test.sh` on draft-16 scored 0/76 against moq-relay 0.15.1. -Subgroup subscribes did return objects. The relay decodes IETF into the -moq-lite track and writes a new subgroup. A green run of all 76 cases is not -the exit test. - -Out of scope, so they are not reopened as bugs: - -- PUBLISH. The relay refuses it. Routing stays SUBSCRIBE per namespace. -- Subgroups. A non-zero subgroup id is dropped. One stream per group. -- Per-group priority. `track::Info` has one priority. A 200/201 split by - group parity stays a gap. -- Foreign object extensions. Dropped. A timestamp we add is ours. -- The end-of-group bit. Optional in draft-16. The group's one stream FINs - at the end, so the bit adds nothing this line will do. -- Several datagram objects in one group. -- A peer that answers SUBSCRIBE_NAMESPACE with unimplemented. The session - already continues. - -Docs stay inline in the change that makes them stale. No new guide. - -## Required - -- [Default track priority](/quest/m1/moxygen/priority.md) - an unset track priority is the midpoint on moq-lite and on IETF, not the least urgent value -- [Group FETCH](/quest/m1/moxygen/fetch.md) - an IETF FETCH of whole groups is served from cache or fetched upstream, one group at a time -- [Datagram groups](/quest/m1/moxygen/datagram.md) - an IETF datagram that is one object in a group arrives as a moq-lite datagram group - -## Related - -- [JavaScript FETCH](/quest/m1/js-fetch.md) - the browser publisher answers a FETCH this relay forwards -- [Track priority scope](/quest/m1/track-priority-scope.md) - send-order fairness, not the default value diff --git a/quest/m1/moxygen/datagram.md b/quest/m1/moxygen/datagram.md deleted file mode 100644 index c794b5e57d8..00000000000 --- a/quest/m1/moxygen/datagram.md +++ /dev/null @@ -1,23 +0,0 @@ -# [M] Datagram groups - -## Goal - -An IETF datagram that carries one object for a group is delivered as a -moq-lite datagram: one single-frame group, sequence preserved. Several -objects in one datagram group stay unsupported. - -## Plan - -moq-lite already does this. A datagram is a subscribe id, a group sequence, a -timestamp, and a payload. `insert_datagram` keeps the sequence so a relay -does not renumber it. - -The IETF session does not read or write QUIC datagrams, so a datagram -subscribe delivers nothing. Copy the lite path onto that session. Do not -invent a second object list inside the group. - -The moxygen cases with one object per group are the ones this can pass. - -## Related - -- [Moxygen compatibility](/quest/m1/moxygen/README.md) - the line this belongs to diff --git a/quest/m1/moxygen/fetch.md b/quest/m1/moxygen/fetch.md deleted file mode 100644 index e38d1e533b3..00000000000 --- a/quest/m1/moxygen/fetch.md +++ /dev/null @@ -1,31 +0,0 @@ -# [L] Group FETCH - -## Goal - -An IETF FETCH that asks for whole groups is answered. A group already in -cache is served from there. A miss fetches that group upstream. Subscribers -still FETCH one group at a time. A publisher may be asked for a range, which -the relay walks one group at a time. A publisher refusal is what the -subscriber sees. - -## Plan - -Standalone FETCH and a non-zero joining FETCH are refused today with -"not supported". Those forms exist only before draft-20; on draft-20+ the -range comes from LOCATION_FILTER. Walk `track::Consumer::fetch_group`, one group, then the -next. Do not add an archive. - -A joining FETCH is the same walk for the groups it names. A form the walk -cannot express is still an explicit refusal, not a hang. - -The moxygen FETCH cases that ask for whole groups are the check. The rest of -that suite is not. - -## Required - -- [Legal IETF input](/quest/m0/ietf-legal-input.md) - decodes the draft-20+ FETCH layout this serves - -## Related - -- [Moxygen compatibility](/quest/m1/moxygen/README.md) - the line this belongs to -- [JavaScript FETCH](/quest/m1/js-fetch.md) - the browser publisher that fills an upstream miss diff --git a/quest/m1/moxygen/priority.md b/quest/m1/moxygen/priority.md deleted file mode 100644 index 6efd6aaa5af..00000000000 --- a/quest/m1/moxygen/priority.md +++ /dev/null @@ -1,28 +0,0 @@ -# [S] Default track priority - -## Goal - -A track that never set a priority is the midpoint on both wires. moq-lite -TRACK_INFO carries that midpoint as written. An IETF subgroup header carries -128. A track that set `track::Info.priority` still uses that value. Per-group -priority stays unsupported. - -## Plan - -`track::Info.priority` defaults to 0, higher-first. moq-lite writes it -verbatim, so the wire byte is 0. IETF flips it, so 0 goes out as 255. The -draft's usual publisher priority is 128. - -One model default serves both. 127 is the higher-first midpoint: lite writes -127, IETF writes 128. Do not special-case each wire to the byte 128. That -would make the two encodings different urgencies. - -Rust and JavaScript both pin the old default TRACK_INFO bytes -(`0x06, 0x00, ...`). Update those fixtures with the new default. - -The moxygen 200 versus 201 split by group parity is out of scope. - -## Related - -- [Moxygen compatibility](/quest/m1/moxygen/README.md) - the line this belongs to -- [Track priority scope](/quest/m1/track-priority-scope.md) - fairness across owners, not this default diff --git a/quest/m2/signed-priority.md b/quest/m2/signed-priority.md index 5f2136fb720..bd41dd592a6 100644 --- a/quest/m2/signed-priority.md +++ b/quest/m2/signed-priority.md @@ -19,11 +19,10 @@ Decided with the maintainer: range, with no saturation. An unset priority goes out as IETF 127, not the draft's usual 128, and an absent IETF priority decodes to 0, the unset default. Pin both ends in tests. -- Invariant, kept from the [moxygen line](/quest/m1/moxygen/README.md)'s - default-priority quest (#4273): one urgency on both wires, so the IETF byte - is always `255 -` the lite byte. Mapping IETF as `128 - p` to hit the - draft's 128 would break it, which is why the default is one step off the - draft there. +- Invariant, kept from the default-priority change (#4273): one urgency on + both wires, so the IETF byte is always `255 -` the lite byte. Mapping IETF + as `128 - p` to hit the draft's 128 would break it, which is why the + default is one step off the draft there. - hang's built-in priorities move above 0, so hang media outranks a track that never set one. Something like catalog 40, text 30, audio 20, video 10; the spacing is the implementer's call. Rust and JS keep matching values. @@ -48,10 +47,6 @@ Decided in the 2026-09-30 audit: moved to m2. It stays deferred unless it ships in the same `dev` release as the moxygen default change, so the default byte moves once instead of twice. -## Required - -- [Moxygen compatibility](/quest/m1/moxygen/README.md) - ships the 127 default and the one-urgency invariant this re-maps - ## Related - [Scope track priority](/quest/m1/track-priority-scope.md) - which streams a priority competes with, not its type diff --git a/rs/libmoq/src/api.rs b/rs/libmoq/src/api.rs index d8c6dbcfda4..5d429aaedef 100644 --- a/rs/libmoq/src/api.rs +++ b/rs/libmoq/src/api.rs @@ -491,8 +491,8 @@ pub struct moq_datagram { /// Publisher-side raw track properties. /// /// A null [moq_publish_track] `info` pointer uses the moq-net defaults. -/// A zero-initialized struct also uses those defaults, except `priority` where -/// zero is the default itself. +/// A zero-initialized struct also uses those defaults, except `priority`, which +/// has no presence flag: zero is the least urgent, and 127 is the moq-net default. #[repr(C)] #[allow(non_camel_case_types)] pub struct moq_track_info { @@ -3619,7 +3619,7 @@ pub extern "C" fn moq_consume_track_cancel(track: u32) -> i32 { /// touched again, so release `user_data` there. The terminal callback fires even after /// [moq_consume_datagrams_cancel]. Read each datagram with [moq_consume_datagram] and release /// it with [moq_consume_datagram_free]. Datagrams arrive only over datagram-capable -/// transports and lite-05 or newer moq-lite; there is no stream fallback. +/// transports on moq-transport or lite-05 and newer moq-lite; there is no stream fallback. /// /// Returns a non-zero handle to the subscription on success, or a negative code on failure. /// diff --git a/rs/moq-e2ee/tests/transport.rs b/rs/moq-e2ee/tests/transport.rs index bb114105e2c..72dde42bc77 100644 --- a/rs/moq-e2ee/tests/transport.rs +++ b/rs/moq-e2ee/tests/transport.rs @@ -1,4 +1,4 @@ -//! Grouped tracks on moq-lite and MoQ Transport; datagrams on moq-lite. +//! Grouped tracks and datagrams on moq-lite and MoQ Transport. mod support; @@ -104,10 +104,9 @@ async fn grouped_over_ietf() { .expect("timed out"); } -#[tokio::test] -async fn datagrams_over_lite() { +async fn datagram_roundtrip(version: &str) { tokio::time::timeout(TEST_TIMEOUT, async { - let mut fixture = connect_protected("moq-lite-05".parse().unwrap(), "audio").await; + let mut fixture = connect_protected(version.parse().unwrap(), "audio").await; fixture .producer .append_datagram(Timestamp::from_millis(9).unwrap(), b"opus") @@ -123,3 +122,13 @@ async fn datagrams_over_lite() { .await .expect("timed out"); } + +#[tokio::test] +async fn datagrams_over_lite() { + datagram_roundtrip("moq-lite-05").await; +} + +#[tokio::test] +async fn datagrams_over_ietf() { + datagram_roundtrip("moq-transport-21").await; +} diff --git a/rs/moq-ffi/src/consumer.rs b/rs/moq-ffi/src/consumer.rs index 84da7e0076a..14e441e3209 100644 --- a/rs/moq-ffi/src/consumer.rs +++ b/rs/moq-ffi/src/consumer.rs @@ -633,7 +633,7 @@ impl MoqTrackConsumer { /// Receive the next best-effort datagram in arrival order. /// /// Returns `None` when the track ends. Datagram delivery is unavailable over - /// IETF moq-transport, pre-lite-05 moq-lite, and stream-only transports. + /// pre-lite-05 moq-lite and stream-only transports. /// Datagrams are a separate cursor from groups, so this works alongside either /// group order, never commits the track to one, and progresses while a group /// read is pending. diff --git a/rs/moq-ffi/src/producer.rs b/rs/moq-ffi/src/producer.rs index 377ec3c7a40..dfee87f50db 100644 --- a/rs/moq-ffi/src/producer.rs +++ b/rs/moq-ffi/src/producer.rs @@ -11,11 +11,12 @@ use crate::media::{MoqAudioInit, MoqContainerFormat, MoqContainerInit, MoqFrame, /// Publisher-side track properties, mirroring [`moq_net::track::Info`]. /// /// Construct with the fields you care about; the rest use raw-track defaults -/// (priority 0, the publisher's default max age, microsecond timescale). +/// (priority 127, the publisher's default max age, microsecond timescale). #[derive(Clone, uniffi::Record)] pub struct MoqTrackInfo { /// Priority, used only to break ties between subscriptions of equal subscriber priority. - #[uniffi(default = 0)] + /// Higher is more urgent; the default 127 is the midpoint. + #[uniffi(default = 127)] pub priority: u8, /// Maximum age of a non-latest group before the publisher evicts it, in /// microseconds. Null uses the default. This is the publisher-side half of diff --git a/rs/moq-net/src/fuzz.rs b/rs/moq-net/src/fuzz.rs index a7dd0261951..36c0a4be23f 100644 --- a/rs/moq-net/src/fuzz.rs +++ b/rs/moq-net/src/fuzz.rs @@ -61,7 +61,7 @@ const IETF_VERSIONS: &[ietf::Version] = &[ const LITE_KINDS: u8 = 21; /// How many types [`ietf_wire`] dispatches over. -const IETF_KINDS: u8 = 39; +const IETF_KINDS: u8 = 40; /// Split the two selector bytes off the input: a version and a type. fn select(data: &[u8], versions: usize) -> Option<(usize, u8, &[u8])> { @@ -436,6 +436,7 @@ pub fn ietf_wire(data: &[u8]) -> bool { 36 => roundtrip::(rest, version, stable), 37 => roundtrip::(rest, version, stable), 38 => roundtrip::(rest, version, stable), + 39 => roundtrip::(rest, version, stable), _ => unreachable!("kind is taken modulo IETF_KINDS"), } } diff --git a/rs/moq-net/src/ietf/datagram.rs b/rs/moq-net/src/ietf/datagram.rs new file mode 100644 index 00000000000..fae9b48bdfc --- /dev/null +++ b/rs/moq-net/src/ietf/datagram.rs @@ -0,0 +1,301 @@ +//! OBJECT_DATAGRAM: one Object carried in a QUIC datagram (draft-14 section 10.3.1 through +//! draft-20 section 11.3.1). +//! +//! The model counterpart is [`crate::Datagram`], a single-frame group, so only an Object at +//! ID 0 maps onto it. The Type is a set of flags on every draft; draft-14 lacks the +//! DEFAULT_PRIORITY bit and a status with an omitted Object ID. + +use bytes::{Buf, BufMut, Bytes}; + +use crate::coding::{Decode, DecodeError, Encode, EncodeError}; + +use super::Version; + +/// The bits of an OBJECT_DATAGRAM Type. +mod flag { + pub const PROPERTIES: u64 = 0x01; + pub const END_OF_GROUP: u64 = 0x02; + pub const ZERO_OBJECT_ID: u64 = 0x04; + pub const DEFAULT_PRIORITY: u64 = 0x08; + pub const STATUS: u64 = 0x20; + /// Every defined bit. Anything else, including the reserved 0x10, is invalid. + pub const ALL: u64 = PROPERTIES | END_OF_GROUP | ZERO_OBJECT_ID | DEFAULT_PRIORITY | STATUS; +} + +/// What follows an OBJECT_DATAGRAM's header. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum DatagramBody { + /// The Object Payload, delimited by the datagram boundary. + Payload(Bytes), + /// The Object Status of an Object without a payload. + Status(u64), +} + +/// A decoded OBJECT_DATAGRAM. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ObjectDatagram { + pub track_alias: u64, + pub group_id: u64, + /// The Object ID, or `None` when the ZERO_OBJECT_ID bit omits it (Object 0). + pub object_id: Option, + /// The Publisher Priority, or `None` to inherit the subscription's (draft-15+). + pub publisher_priority: Option, + /// No Object past this one exists in the group. + pub end_of_group: bool, + /// The Object Properties block without its length prefix, which carries the Timestamp. + pub properties: Option>, + pub body: DatagramBody, +} + +impl ObjectDatagram { + /// Whether `kind` is a Type this draft defines. + fn valid(kind: u64, version: Version) -> bool { + match version { + Version::Draft14 => kind <= 0x07 || kind == 0x20 || kind == 0x21, + // A status cannot also end the group. + _ => kind & !flag::ALL == 0 && !(kind & flag::STATUS != 0 && kind & flag::END_OF_GROUP != 0), + } + } +} + +impl Encode for ObjectDatagram { + fn encode(&self, w: &mut W, version: Version) -> Result<(), EncodeError> { + let mut kind = 0; + if self.properties.is_some() { + kind |= flag::PROPERTIES; + } + if self.end_of_group { + kind |= flag::END_OF_GROUP; + } + if self.object_id.is_none() { + kind |= flag::ZERO_OBJECT_ID; + } + if self.publisher_priority.is_none() { + kind |= flag::DEFAULT_PRIORITY; + } + if matches!(self.body, DatagramBody::Status(_)) { + kind |= flag::STATUS; + } + if !Self::valid(kind, version) { + return Err(EncodeError::InvalidState); + } + + kind.encode(w, version)?; + self.track_alias.encode(w, version)?; + self.group_id.encode(w, version)?; + if let Some(object_id) = self.object_id { + object_id.encode(w, version)?; + } + if let Some(priority) = self.publisher_priority { + priority.encode(w, version)?; + } + if let Some(properties) = &self.properties { + // A present but empty block is a protocol violation for the peer. + if properties.is_empty() { + return Err(EncodeError::InvalidState); + } + properties.encode(w, version)?; + } + + match &self.body { + DatagramBody::Status(status) => { + // Draft-17 on: only a Normal Object may carry Properties. + let legacy = matches!(version, Version::Draft14 | Version::Draft15 | Version::Draft16); + if !legacy && *status != 0 && self.properties.is_some() { + return Err(EncodeError::InvalidState); + } + status.encode(w, version)? + } + DatagramBody::Payload(payload) => { + // Runs to the datagram boundary: written raw, no length prefix. + if w.remaining_mut() < payload.len() { + return Err(EncodeError::Short); + } + w.put_slice(payload); + } + } + Ok(()) + } +} + +impl Decode for ObjectDatagram { + fn decode(r: &mut R, version: Version) -> Result { + let kind = u64::decode(r, version)?; + if !Self::valid(kind, version) { + return Err(DecodeError::InvalidValue); + } + + let track_alias = u64::decode(r, version)?; + let group_id = u64::decode(r, version)?; + let object_id = match kind & flag::ZERO_OBJECT_ID != 0 { + true => None, + false => Some(u64::decode(r, version)?), + }; + let publisher_priority = match kind & flag::DEFAULT_PRIORITY != 0 { + true => None, + false => Some(u8::decode(r, version)?), + }; + let properties = match kind & flag::PROPERTIES != 0 { + true => { + let properties = Vec::::decode(r, version)?; + if properties.is_empty() { + return Err(DecodeError::InvalidValue); + } + Some(properties) + } + false => None, + }; + + let body = match kind & flag::STATUS != 0 { + true => { + let status = u64::decode(r, version)?; + // Draft-17 on: only a Normal Object may carry Properties. + let legacy = matches!(version, Version::Draft14 | Version::Draft15 | Version::Draft16); + if !legacy && status != 0 && properties.is_some() { + return Err(DecodeError::InvalidValue); + } + if r.has_remaining() { + return Err(DecodeError::TrailingBytes); + } + DatagramBody::Status(status) + } + false => DatagramBody::Payload(r.copy_to_bytes(r.remaining())), + }; + + Ok(Self { + track_alias, + group_id, + object_id, + publisher_priority, + end_of_group: kind & flag::END_OF_GROUP != 0, + properties, + body, + }) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + const ALL: [Version; 9] = [ + Version::Draft14, + Version::Draft15, + Version::Draft16, + Version::Draft17, + Version::Draft18, + Version::Draft19, + Version::Draft20, + Version::Draft21, + Version::Draft22, + ]; + + fn single(priority: Option) -> ObjectDatagram { + ObjectDatagram { + track_alias: 3, + group_id: 42, + object_id: None, + publisher_priority: priority, + end_of_group: true, + properties: Some(vec![0x10, 0x05]), + body: DatagramBody::Payload(Bytes::from_static(b"hello")), + } + } + + #[test] + fn roundtrip_every_draft() { + for version in ALL { + let datagram = single(Some(7)); + let mut buf = datagram.encode_bytes(version).unwrap(); + assert_eq!(buf[0], 0x07, "{version}: properties, end of group, object 0"); + let decoded = ObjectDatagram::decode(&mut buf, version).unwrap(); + assert_eq!(decoded, datagram, "{version}"); + assert!(!buf.has_remaining()); + } + } + + #[test] + fn default_priority_needs_draft15() { + assert!(matches!( + single(None).encode_bytes(Version::Draft14), + Err(EncodeError::InvalidState) + )); + assert!(ObjectDatagram::decode(&mut &[0x0C, 0x01, 0x02][..], Version::Draft14).is_err()); + + let mut buf = single(None).encode_bytes(Version::Draft16).unwrap(); + assert_eq!(buf[0], 0x0F); + assert_eq!( + ObjectDatagram::decode(&mut buf, Version::Draft16).unwrap(), + single(None) + ); + } + + #[test] + fn explicit_object_id_and_status() { + let datagram = ObjectDatagram { + track_alias: 1, + group_id: 2, + object_id: Some(0), + publisher_priority: Some(128), + end_of_group: false, + properties: None, + body: DatagramBody::Status(0), + }; + for version in ALL { + let mut buf = datagram.encode_bytes(version).unwrap(); + assert_eq!(buf[0], 0x20, "{version}"); + assert_eq!(ObjectDatagram::decode(&mut buf, version).unwrap(), datagram); + } + } + + #[test] + fn rejects_invalid_types() { + for version in ALL { + // A status that ends the group, the reserved bit, and a bit past the defined ones. + for kind in [0x22u64, 0x10, 0x40] { + let mut bytes = kind.encode_bytes(version).unwrap().to_vec(); + bytes.extend_from_slice(&[0x01, 0x02, 0x03, 0x04]); + assert!( + ObjectDatagram::decode(&mut &bytes[..], version).is_err(), + "{version}: {kind:#x}" + ); + } + } + } + + #[test] + fn status_with_properties_needs_normal() { + let datagram = ObjectDatagram { + track_alias: 1, + group_id: 2, + object_id: Some(0), + publisher_priority: Some(0), + end_of_group: false, + properties: Some(vec![0x10, 0x05]), + body: DatagramBody::Status(3), + }; + for version in ALL { + let legacy = matches!(version, Version::Draft14 | Version::Draft15 | Version::Draft16); + match datagram.encode_bytes(version) { + Ok(mut buf) => { + assert!(legacy, "{version}"); + assert_eq!(ObjectDatagram::decode(&mut buf, version).unwrap(), datagram); + } + Err(err) => { + assert!(!legacy, "{version}"); + assert!(matches!(err, EncodeError::InvalidState)); + } + } + } + } + + #[test] + fn rejects_empty_properties() { + // PROPERTIES and ZERO_OBJECT_ID, alias 1, group 2, priority 0, empty block. + let bytes = [0x05, 0x01, 0x02, 0x00, 0x00, b'x']; + assert!(matches!( + ObjectDatagram::decode(&mut &bytes[..], Version::Draft16), + Err(DecodeError::InvalidValue) + )); + } +} diff --git a/rs/moq-net/src/ietf/fetch.rs b/rs/moq-net/src/ietf/fetch.rs index 5987d8efbc7..57e7d07fe3b 100644 --- a/rs/moq-net/src/ietf/fetch.rs +++ b/rs/moq-net/src/ietf/fetch.rs @@ -167,7 +167,8 @@ impl Message for Fetch<'_> { ); let subscriber_priority = subscriber_priority.unwrap_or(128); - let group_order = group_order.unwrap_or(GroupOrder::Descending); + // No preference: the publisher picks the order. + let group_order = group_order.unwrap_or(GroupOrder::Any); Ok(Self { request_id, diff --git a/rs/moq-net/src/ietf/mod.rs b/rs/moq-net/src/ietf/mod.rs index 9c8577b3400..944c2778934 100644 --- a/rs/moq-net/src/ietf/mod.rs +++ b/rs/moq-net/src/ietf/mod.rs @@ -9,6 +9,7 @@ mod parameters; mod adapter; pub mod cluster; mod control; +mod datagram; pub(crate) mod error; mod fetch; mod filter; @@ -35,6 +36,7 @@ mod track; mod version; use control::Control; +pub use datagram::*; pub use fetch::*; pub use filter::*; pub use goaway::*; diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index b6bbe921791..5de4a889e8c 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -15,7 +15,7 @@ use web_transport_trait::poll::SendStream as _; use crate::{ AsPath, Error, Timescale, Timestamp, - coding::{Stream, Writer}, + coding::{Encode as _, Stream, Writer}, ietf::{self, Control, EndLocation, FetchHeader, FetchType, Filter, GroupOrder, Location, RequestId}, track::Subscription, util::{MaybeBoxedExt, MaybeSendBox}, @@ -44,6 +44,83 @@ enum FillStep { Done, } +/// Where a fetch object sits relative to the one written before it on the same stream. +#[derive(Clone, Copy)] +enum FetchPrior { + /// The first object on the stream. + None, + /// The next object of the same group. + Same, +} + +/// The group a FETCH answers with, read out of the cache so a later eviction cannot +/// truncate what FETCH_OK already promised. +struct FetchedGroup { + sequence: u64, + /// The Object ID of the first frame. + first: u64, + frames: Vec, + /// The group ended within the range, so every frame it will ever hold was read. + complete: bool, +} + +impl FetchPrior { + /// The prior for the next object of a single-group stream, clearing `first`. + fn next(first: &mut bool) -> Self { + match std::mem::take(first) { + true => Self::None, + false => Self::Same, + } + } +} + +impl FetchedGroup { + /// One past the last Object ID read. + fn end(&self) -> u64 { + self.first + self.frames.len() as u64 + } +} + +/// Read group `sequence` of `track` for a FETCH, from object `skip` up to the exclusive +/// `until`, or through the end of the group without one. +/// +/// This is a [`track::Consumer::fetch_group`], so a relay fetches a miss upstream. +async fn read_fetch( + track: &track::Consumer, + sequence: u64, + skip: u64, + until: Option, + priority: u8, +) -> Result { + let fetch = group::Fetch { + priority, + frame_start: skip, + }; + let mut group = track.fetch_group(sequence, fetch).await?; + + // `fetch_group` positions the consumer at `skip`, or refuses a group that no + // longer holds it. + let first = group.index(); + let mut frames = Vec::new(); + let mut complete = false; + while until.is_none_or(|until| first + (frames.len() as u64) < until) { + match group.read_frame().await? { + Some(frame) => frames.push(frame), + None => { + complete = true; + break; + } + } + } + + Ok(FetchedGroup { + sequence, + first, + frames, + complete, + }) +} + /// A broadcast whose route table is watched for changes in what we advertise: the /// namespace becoming (un)advertisable, or its path or cost moving. struct Watched { @@ -877,20 +954,13 @@ where stream, sequence, index, - std::mem::take(&mut first), + FetchPrior::next(&mut first), frame.timestamp, timescale, version, ) .await?; - stream.encode(&(frame.payload.len() as u64)).await?; - if frame.payload.is_empty() && matches!(version, Version::Draft14 | Version::Draft15) { - stream.encode(&0u64).await?; - } - if !frame.payload.is_empty() { - let mut payload = frame.payload; - stream.write_all(&mut payload).await?; - } + Self::write_fetch_payload(stream, frame.payload, version).await?; } index += 1; group.keep_alive(); @@ -922,7 +992,7 @@ where stream, sequence, index, - std::mem::take(&mut first), + FetchPrior::next(&mut first), frame.timestamp, timescale, version, @@ -968,7 +1038,7 @@ where stream: &mut Writer, sequence: u64, object: u64, - first: bool, + prior: FetchPrior, timestamp: Timestamp, timescale: Option, version: Version, @@ -993,10 +1063,10 @@ where return Ok(()); } - let header = match first { + let header = match prior { // The first object must carry its absolute Group and Object IDs. Include the // priority too: "same as the prior object" has no prior to refer to. - true => ietf::FetchObject::Object { + FetchPrior::None => ietf::FetchObject::Object { subgroup: ietf::FetchSubgroup::Zero, group: Some(sequence), object: Some(object), @@ -1004,7 +1074,7 @@ where properties, }, // Same group and priority; the Object ID is the prior one plus one. - false => ietf::FetchObject::Object { + FetchPrior::Same => ietf::FetchObject::Object { subgroup: ietf::FetchSubgroup::Zero, group: None, object: None, @@ -1018,6 +1088,24 @@ where Ok(()) } + /// Write a whole fetch object's length and payload, after its header. + async fn write_fetch_payload( + stream: &mut Writer, + payload: bytes::Bytes, + version: Version, + ) -> Result<(), Error> { + stream.encode(&(payload.len() as u64)).await?; + // Draft-14 and 15 still carry a Normal status after an empty object. + if payload.is_empty() && matches!(version, Version::Draft14 | Version::Draft15) { + stream.encode(&0u64).await?; + } + if !payload.is_empty() { + let mut payload = payload; + stream.write_all(&mut payload).await?; + } + Ok(()) + } + /// Register a pending subscription until the returned guard drops. fn register_join(&self, request_id: RequestId) -> Join { self.joins.lock().insert(request_id, None); @@ -1027,166 +1115,160 @@ where } } - /// Serve the current-group prefix for a relative joining FETCH with offset zero. + /// Answer a FETCH within one group: a standalone range of the named track, or a + /// joining FETCH's prefix of its subscription's group. + /// + /// The answer is buffered before replying: FETCH_OK names where the response ends, + /// which a range running past the track only learns by reading it, and a refusal can + /// still replace it until then. async fn run_fetch_stream(mut self, mut stream: Stream, msg: ietf::Fetch<'_>) -> Result<(), Error> { + let priority = super::priority::from_wire(msg.subscriber_priority); + + // Draft-20 moved the range into LOCATION_FILTER and replaced joining FETCH with + // subscription fills; this still reads the older layout. if Filter::is_draft20(self.version) { return self .reject_fetch( stream, msg.request_id, &Error::Unsupported, - "joining FETCH removed in draft-20", + "FETCH not supported on draft-20", ) .await; } - let subscribe_id = match msg.fetch_type { - FetchType::Standalone { .. } => { - return self - .reject_fetch(stream, msg.request_id, &Error::Unsupported, "not supported") - .await; - } - FetchType::RelativeJoining { - subscriber_request_id, - group_offset, + let (track, start, end, timescale, joined) = match msg.fetch_type { + FetchType::Standalone { + namespace, + track, + start, + end, } => { - if group_offset != 0 { + // 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 { return self - .reject_fetch(stream, msg.request_id, &Error::Unsupported, "not supported") + .reject_fetch(stream, msg.request_id, &Error::InvalidRange, "empty range") .await; - } - subscriber_request_id + }; + + // The peer must have seen the announcement to name this namespace, so this + // resolves like a SUBSCRIBE does. + let broadcast = match self.serving_origin().await.request_broadcast(&namespace).await { + Ok(broadcast) => broadcast, + Err(err) => return self.reject_fetch(stream, msg.request_id, &err, &err.to_string()).await, + }; + let track = match broadcast.track(&track) { + Ok(track) => track, + Err(err) => return self.reject_fetch(stream, msg.request_id, &err, &err.to_string()).await, + }; + + // No SUBSCRIBE declared a timescale for this request, so its objects go + // out unstamped. + (track, start, end, None, false) } - FetchType::AbsoluteJoining { .. } => { - return self - .reject_fetch(stream, msg.request_id, &Error::Unsupported, "not supported") - .await; + FetchType::RelativeJoining { + subscriber_request_id, .. + } + | FetchType::AbsoluteJoining { + subscriber_request_id, .. + } => { + let (end, cache, timescale) = match self.joined(&mut stream, subscriber_request_id).await? { + Ok(joined) => joined, + Err((err, reason)) => return self.reject_fetch(stream, msg.request_id, &err, reason).await, + }; + let start = match msg.fetch_type { + FetchType::RelativeJoining { group_offset, .. } => end.group.saturating_sub(group_offset), + FetchType::AbsoluteJoining { group_id, .. } if group_id <= end.group => group_id, + _ => { + return self + .reject_fetch( + stream, + msg.request_id, + &Error::InvalidRange, + "joining group past the subscription", + ) + .await; + } + }; + ( + cache, + Location { + group: start, + object: 0, + }, + end, + timescale, + true, + ) } }; - // Request streams can arrive out of order. Wait on registration, while bounding - // the lifetime of a request whose subscription never arrives or resolves. - let joined = { - let mut pending = false; - let mut deadline = crate::runtime::Deadline::after(&self.runtime, Duration::from_secs(10)); + // 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 { + return self + .reject_fetch( + stream, + msg.request_id, + &Error::Unsupported, + "FETCH spanning several groups not supported", + ) + .await; + } + let until = (end.object > 0).then_some(end.object); + + // The subscriber cancelling is the only other way this ends early, and is owed + // nothing. + let group = { + let mut read = std::pin::pin!(read_fetch(&track, start.group, start.object, until, priority)); kio::wait(|waiter| { let mut cx = std::task::Context::from_waker(waiter.waker()); - // The request reader is what the subscriber FINs or resets. The writer - // on a draft-14-16 virtual stream reports closed immediately, which is - // not a cancellation. if stream.reader.poll_closed(&mut cx).is_ready() { - return Poll::Ready(Err(Error::Cancel)); + return Poll::Ready(None); } - let joins = self.joins.poll(waiter, |joins| match joins.get(&subscribe_id) { - Some(Some(_)) => Poll::Ready(()), - Some(None) => { - pending = true; - Poll::Pending - } - None if pending => Poll::Ready(()), - None => Poll::Pending, - }); - if let Poll::Ready(joins) = joins { - return Poll::Ready(Ok(joins.get(&subscribe_id).cloned().flatten())); - } - if deadline.poll(waiter).is_ready() { - return Poll::Ready(if pending { Err(Error::Timeout) } else { Ok(None) }); - } - Poll::Pending + waiter.poll_future(read.as_mut()).map(Some) }) .await }; - let joined = match joined { - Err(Error::Timeout) => { - return self - .reject_fetch(stream, msg.request_id, &Error::Timeout, "subscription not ready") - .await; - } - result => result?, + let group = match group { + Some(Ok(group)) => group, + Some(Err(err)) => return self.reject_fetch(stream, msg.request_id, &err, &err.to_string()).await, + None => return Ok(()), }; - let (end, cache, timescale) = match joined { - None => { - return self - .reject_fetch( - stream, - msg.request_id, - &if matches!( - self.version, - Version::Draft14 - | Version::Draft15 | Version::Draft16 - | Version::Draft17 | Version::Draft18 - | Version::Draft19 - ) { - Error::InvalidJoiningRequestId - } else { - Error::NotFound - }, - "no such subscription", - ) - .await; - } - Some(Joined::Unsupported) => { - if matches!(self.version, Version::Draft14 | Version::Draft15 | Version::Draft16) { - self.session.close( - crate::SessionError::ProtocolViolation.to_code(), - "joining FETCH requires Largest Object filter", - ); - return Err(Error::ProtocolViolation); - } - return self - .reject_fetch( - stream, - msg.request_id, - &Error::Unsupported, - "joining filter not supported", - ) - .await; - } - Some(Joined::Empty) => { + + let (end_location, end_of_track) = if joined { + // The subscription starts at the saved Largest Object, so the prefix of that + // group has to be here in full or the two leave a gap. + if group.end() != end.object { return self - .reject_fetch( - stream, - msg.request_id, - &Error::InvalidRange, - "no objects at subscription start", - ) + .reject_fetch(stream, msg.request_id, &Error::Evicted, "joining prefix unavailable") .await; } - Some(Joined::Group { end, cache, timescale }) => (end, cache, timescale), - }; - let priority = super::priority::from_wire(msg.subscriber_priority); - let mut group = match cache - .fetch_group( - end.group, - group::Fetch { - priority, - ..Default::default() - }, - ) - .await - { - Ok(group) => group, - Err(err) => { - return self - .reject_fetch(stream, msg.request_id, &err, "joining group unavailable") - .await; + (end, false) + } else { + let end_of_track = group.complete && track.final_sequence() == group.sequence.checked_add(1); + // 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 { + true => ( + Location { + group: group.sequence, + object: group.end(), + }, + true, + ), + false => (end, false), } }; - // Retain the promised prefix before success: a cached group may already have - // evicted its front, and later cache eviction must not truncate this FETCH. - let mut prefix = Vec::new(); - for _ in 0..end.object { - match group.read_frame().await { - Ok(Some(frame)) => prefix.push(frame), - _ => { - return self - .reject_fetch(stream, msg.request_id, &Error::Evicted, "joining prefix unavailable") - .await; - } - } - } - // FETCH_OK on every draft, never REQUEST_OK: section 5.2 allows exactly one FETCH_OK or // REQUEST_ERROR in answer to a FETCH, and REQUEST_OK's own definition lists the other // requests it answers without ever naming this one. @@ -1199,13 +1281,15 @@ where _ => None, }, // Only draft-14 encodes it, and only as the publisher restating the order. - group_order: msg.group_order.any_to_descending(), - end_of_track: false, - end_location: end, + group_order: match msg.group_order { + GroupOrder::Descending => GroupOrder::Descending, + _ => GroupOrder::Ascending, + }, + end_of_track, + end_location, }) .await?; - // The FETCH owns the retained prefix, capped at the subscription snapshot. let uni = self.session.open_uni().await.map_err(Error::from_transport)?; let mut writer = Writer::new(uni, self.version); writer.set_priority(priority); @@ -1215,25 +1299,19 @@ where request_id: msg.request_id, }) .await?; - for (index, frame) in prefix.into_iter().enumerate() { + let mut first = true; + for (object, frame) in (group.first..).zip(group.frames) { Self::write_fetch_object( &mut writer, - end.group, - index as u64, - index == 0, + group.sequence, + object, + FetchPrior::next(&mut first), frame.timestamp, timescale, self.version, ) .await?; - writer.encode(&(frame.payload.len() as u64)).await?; - if frame.payload.is_empty() && matches!(self.version, Version::Draft14 | Version::Draft15) { - writer.encode(&0u64).await?; - } - if !frame.payload.is_empty() { - let mut payload = frame.payload; - writer.write_all(&mut payload).await?; - } + Self::write_fetch_payload(&mut writer, frame.payload, self.version).await?; } writer.close().await?; @@ -1245,6 +1323,76 @@ where Ok(()) } + /// Resolve the subscription a joining FETCH names to its saved start, or the refusal + /// to answer the FETCH with. + async fn joined( + &mut self, + stream: &mut Stream, + subscribe_id: RequestId, + ) -> Result), (Error, &'static str)>, Error> { + // Request streams can arrive out of order. Wait on registration, while bounding + // the lifetime of a request whose subscription never arrives or resolves. + let joined = { + let mut pending = false; + let mut deadline = crate::runtime::Deadline::after(&self.runtime, Duration::from_secs(10)); + kio::wait(|waiter| { + let mut cx = std::task::Context::from_waker(waiter.waker()); + // The request reader is what the subscriber FINs or resets. The writer + // on a draft-14-16 virtual stream reports closed immediately, which is + // not a cancellation. + if stream.reader.poll_closed(&mut cx).is_ready() { + return Poll::Ready(Err(Error::Cancel)); + } + let joins = self.joins.poll(waiter, |joins| match joins.get(&subscribe_id) { + Some(Some(_)) => Poll::Ready(()), + Some(None) => { + pending = true; + Poll::Pending + } + None if pending => Poll::Ready(()), + None => Poll::Pending, + }); + if let Poll::Ready(joins) = joins { + return Poll::Ready(Ok(joins.get(&subscribe_id).cloned().flatten())); + } + if deadline.poll(waiter).is_ready() { + return Poll::Ready(if pending { Err(Error::Timeout) } else { Ok(None) }); + } + Poll::Pending + }) + .await + }; + let refusal = match joined { + Err(Error::Timeout) => (Error::Timeout, "subscription not ready"), + Err(err) => return Err(err), + Ok(Some(Joined::Group { end, cache, timescale })) => return Ok(Ok((end, cache, timescale))), + Ok(None) => ( + match self.version { + Version::Draft14 + | Version::Draft15 + | Version::Draft16 + | Version::Draft17 + | Version::Draft18 + | Version::Draft19 => Error::InvalidJoiningRequestId, + _ => Error::NotFound, + }, + "no such subscription", + ), + Ok(Some(Joined::Unsupported)) => { + if matches!(self.version, Version::Draft14 | Version::Draft15 | Version::Draft16) { + self.session.close( + crate::SessionError::ProtocolViolation.to_code(), + "joining FETCH requires Largest Object filter", + ); + return Err(Error::ProtocolViolation); + } + (Error::Unsupported, "joining filter not supported") + } + Ok(Some(Joined::Empty)) => (Error::InvalidRange, "no objects at subscription start"), + }; + Ok(Err(refusal)) + } + async fn reject_track_status(&self, mut stream: Stream, request_id: RequestId) -> Result<(), Error> { let error_code = request::to_code(&Error::Unsupported, request::Kind::TrackStatus, self.version); if self.version == Version::Draft14 { @@ -1968,6 +2116,9 @@ struct TrackServe { opened: Arc, /// The track's exclusive end, once its groups ran out because it finished. end: Option, + /// Serve the track's datagrams too, as OBJECT_DATAGRAMs. Off when the transport has no + /// datagrams; there is no stream fallback. + datagrams: bool, } impl TrackServe { @@ -1988,8 +2139,10 @@ impl TrackServe { } } track.end_at(range.end.map_or(Bound::Unbounded, |end| Bound::Included(end.group))); + let datagrams = session.max_datagram_size() > 0; Self { + datagrams, session, track, request_id, @@ -2103,6 +2256,8 @@ impl TrackServe { ); } Poll::Ready(Ok(None)) => { + // Datagrams written before the track finished still go out. + self.poll_datagrams(waiter); self.draining = true; if let Poll::Ready(Ok(end)) = self.track.poll_finished(waiter) { self.end = Some(end); @@ -2113,10 +2268,59 @@ impl TrackServe { Poll::Pending => break, } } + // Groups first, so a burst of datagrams cannot starve them. + self.poll_datagrams(waiter); // Newly created group machines start now rather than on the next wake. let _ = self.children.poll(waiter); Poll::Pending } + + /// Send every buffered datagram as an OBJECT_DATAGRAM, best-effort, like moq-lite. + /// + /// A datagram is Object 0 of a group that has no other, so the Object ends its group. + /// The track's end or failure surfaces through its groups, so this only stops. + fn poll_datagrams(&mut self, waiter: &kio::Waiter) { + if !self.datagrams { + return; + } + while let Poll::Ready(Ok(Some(datagram))) = self.track.poll_recv_datagram(waiter) { + let sequence = datagram.sequence; + let properties = match self.timescale { + Some(timescale) => { + let mut properties = Vec::new(); + if ietf::encode_object_time(&mut properties, datagram.timestamp, timescale, self.version).is_err() { + continue; + } + Some(properties) + } + None => None, + }; + let body = ietf::ObjectDatagram { + track_alias: self.request_id.0, + group_id: sequence, + object_id: None, + publisher_priority: Some(super::priority::to_wire(self.track.info().priority)), + end_of_group: true, + properties, + body: ietf::DatagramBody::Payload(datagram.payload), + }; + let Ok(body) = body.encode_bytes(self.version) else { + continue; + }; + + let max = self.session.max_datagram_size(); + if body.len() > max { + tracing::debug!( + sequence, + size = body.len(), + max, + "dropping datagram larger than the transport limit" + ); + continue; + } + let _ = self.session.send_datagram(&body); + } + } } /// Serves one group on its own unidirectional stream in the moq-transport @@ -2496,10 +2700,31 @@ mod group_priority_test { /// every moq-transport peer. #[tokio::test] async fn group_header_carries_the_publisher_priority() { + let header = serve_group_header(track::Info::default().with_priority(hang_audio_priority())).await; + assert_eq!( + header.publisher_priority, + priority::to_wire(hang_audio_priority()), + "the wire is lower-first, so audio must encode below video" + ); + assert!( + priority::to_wire(hang_audio_priority()) < priority::to_wire(hang_video_priority()), + "audio outranks video on the wire" + ); + } + + /// A track that never set a priority is the draft's usual publisher priority, 128, + /// not 255, the least urgent value a peer like moxygen would deprioritize. + #[tokio::test] + async fn group_header_defaults_to_the_midpoint() { + let header = serve_group_header(track::Info::default()).await; + assert_eq!(header.publisher_priority, 128); + } + + /// Serve one group of a track with `info` and decode the subgroup header it opens with. + async fn serve_group_header(info: track::Info) -> ietf::GroupHeader { let log = crate::lite::test_transport::Log::default(); let session = SinkSession::new(log.clone()); - let info = track::Info::default().with_priority(hang_audio_priority()); let track = track::Producer::new(std::sync::Arc::new(crate::broadcast::Info::default()), "test", info); let subscriber = track.subscribe(None); @@ -2520,16 +2745,7 @@ mod group_priority_test { let written = log.writes.lock().unwrap().clone(); let mut buf = bytes::Bytes::from(written); - let header = ietf::GroupHeader::decode(&mut buf, Version::Draft14).expect("a group header"); - assert_eq!( - header.publisher_priority, - priority::to_wire(hang_audio_priority()), - "the wire is lower-first, so audio must encode below video" - ); - assert!( - priority::to_wire(hang_audio_priority()) < priority::to_wire(hang_video_priority()), - "audio outranks video on the wire" - ); + ietf::GroupHeader::decode(&mut buf, Version::Draft14).expect("a group header") } /// `hang::catalog::PRIORITY` isn't reachable from `moq-net` (hang depends on it, not the @@ -3512,6 +3728,337 @@ mod serve_tests { assert!(buf.is_empty()); } + /// Every draft that carries a standalone FETCH. + const FETCH_DRAFTS: [Version; 6] = [ + Version::Draft14, + Version::Draft15, + Version::Draft16, + Version::Draft17, + Version::Draft18, + Version::Draft19, + ]; + + /// Groups `0..count`, each holding `g-0` and `g-1`, skipping `hole`. + fn publish_pairs(h: &mut Serve, count: u64, hole: Option) { + for sequence in (0..count).filter(|sequence| Some(*sequence) != hole) { + let mut group = h.track.create_group(group::Info { sequence }).unwrap(); + for object in 0..2 { + group + .write_frame(timestamp(), format!("{sequence}-{object}").into_bytes()) + .unwrap(); + } + group.finish().unwrap(); + } + } + + /// Run a standalone FETCH of `room/video`, returning what the peer reads back. + async fn standalone_fetch(h: &Serve, start: Location, end: Location, group_order: GroupOrder) -> bytes::Bytes { + let version = h.publisher.version; + let mark = h.log.writes.lock().unwrap().len(); + let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); + h.publisher + .clone() + .run_fetch_stream( + stream, + ietf::Fetch { + request_id: FETCH_ID, + subscriber_priority: 128, + group_order, + fetch_type: FetchType::Standalone { + namespace: crate::Path::new("room"), + track: "video".into(), + start, + end, + }, + }, + ) + .await + .unwrap(); + bytes::Bytes::from(h.log.writes.lock().unwrap()[mark..].to_vec()) + } + + /// Decode a FETCH_OK and the fetch stream after it, as `(group, object, payload)`. + fn fetch_answer(mut buf: bytes::Bytes, version: Version) -> (ietf::FetchOk, Vec<(u64, u64, String)>) { + assert_eq!( + u64::decode(&mut buf, version).unwrap(), + ietf::FetchOk::ID, + "{version}: not a FETCH_OK" + ); + let ok = ietf::FetchOk::decode(&mut buf, version).unwrap(); + assert_eq!(u64::decode(&mut buf, version).unwrap(), FetchHeader::TYPE); + assert_eq!(FetchHeader::decode(&mut buf, version).unwrap().request_id, FETCH_ID); + + let mut objects = Vec::new(); + let mut prior: Option<(u64, u64)> = None; + while !buf.is_empty() { + let (group, object) = if version == Version::Draft14 { + let group = u64::decode(&mut buf, version).unwrap(); + assert_eq!(u64::decode(&mut buf, version).unwrap(), 0, "subgroup"); + let object = u64::decode(&mut buf, version).unwrap(); + let _priority = u8::decode(&mut buf, version).unwrap(); + let _properties = Vec::::decode(&mut buf, version).unwrap(); + (group, object) + } else { + let ietf::FetchObject::Object { group, object, .. } = + ietf::FetchObject::decode(&mut buf, version).unwrap() + else { + panic!("{version}: unexpected End of Range"); + }; + match (prior, group) { + (None, group) => (group.unwrap(), object.unwrap()), + // No Group ID: the same group, and an absent Object ID Delta is one. + (Some((group, prior)), None) => (group, prior + object.unwrap_or(1)), + (Some((prior, _)), Some(group)) => { + let group = match version { + Version::Draft15 | Version::Draft16 | Version::Draft17 => group, + _ => prior + group + 1, + }; + (group, object.unwrap()) + } + } + }; + let size = u64::decode(&mut buf, version).unwrap() as usize; + let payload = String::from_utf8(buf.split_to(size).to_vec()).unwrap(); + objects.push((group, object, payload)); + prior = Some((group, object)); + } + (ok, objects) + } + + /// The `(group, object, payload)` a range of two-frame groups holds. + fn pairs(groups: impl IntoIterator) -> Vec<(u64, u64, String)> { + groups + .into_iter() + .flat_map(|group| (0..2).map(move |object| (group, object, format!("{group}-{object}")))) + .collect() + } + + /// A whole group is answered on one fetch stream. + #[tokio::test] + async fn a_standalone_fetch_serves_one_whole_group() { + for version in FETCH_DRAFTS { + let mut h = serve(version); + publish_pairs(&mut h, 5, None); + settle().await; + + // An End Object of 0 asks for the whole End Group. + let buf = standalone_fetch( + &h, + Location { group: 2, object: 0 }, + Location { group: 2, object: 0 }, + GroupOrder::Ascending, + ) + .await; + let (ok, objects) = fetch_answer(buf, version); + assert_eq!(ok.end_location, Location { group: 3, object: 0 }, "{version}"); + assert!(!ok.end_of_track, "{version}"); + assert_eq!(objects, pairs([2]), "{version}"); + assert!(h.log.resets().is_empty(), "{version}"); + } + } + + /// The last group of a finished track ends the response one past its last object, + /// with End of Track set. + #[tokio::test] + async fn a_standalone_fetch_of_the_last_group_reports_the_end_of_track() { + for version in FETCH_DRAFTS { + let mut h = serve(version); + publish_pairs(&mut h, 5, None); + h.track.finish().unwrap(); + settle().await; + + let buf = standalone_fetch( + &h, + Location { group: 4, object: 1 }, + Location { group: 4, object: 0 }, + GroupOrder::Any, + ) + .await; + let (ok, objects) = fetch_answer(buf, version); + assert_eq!(ok.end_location, Location { group: 4, object: 2 }, "{version}"); + assert!(ok.end_of_track, "{version}"); + assert_eq!(objects, pairs([4])[1..].to_vec(), "{version}"); + } + } + + /// Draft-20 carries the range in LOCATION_FILTER, which is not read yet. + #[tokio::test] + async fn a_draft20_fetch_is_refused() { + for version in [Version::Draft20, Version::Draft21, Version::Draft22] { + let mut h = serve(version); + publish_pairs(&mut h, 3, None); + settle().await; + + let buf = standalone_fetch( + &h, + Location { group: 1, object: 0 }, + Location { group: 1, object: 0 }, + GroupOrder::Ascending, + ) + .await; + assert_eq!(fetch_refusal(buf, version), 0x3, "{version}"); + } + } + + /// A range touching several groups is refused, in either order: on a relay each + /// missing group would be its own upstream fetch. + #[tokio::test] + async fn a_standalone_fetch_of_several_groups_is_refused() { + for version in FETCH_DRAFTS { + for order in [GroupOrder::Ascending, GroupOrder::Descending] { + let mut h = serve(version); + publish_pairs(&mut h, 3, None); + settle().await; + + let buf = standalone_fetch( + &h, + Location { group: 0, object: 1 }, + Location { group: 1, object: 1 }, + order, + ) + .await; + assert_eq!(fetch_refusal(buf, version), 0x3, "{version}"); + } + } + } + + /// Read a REQUEST_ERROR (or draft-14 FETCH_ERROR) off a refused FETCH, as its code. + fn fetch_refusal(mut buf: bytes::Bytes, version: Version) -> u64 { + let id = u64::decode(&mut buf, version).unwrap(); + let code = match version { + Version::Draft14 => { + assert_eq!(id, ietf::FetchError::ID); + ietf::FetchError::decode(&mut buf, version).unwrap().error_code + } + _ => { + assert_eq!(id, ietf::RequestError::ID); + ietf::RequestError::decode(&mut buf, version).unwrap().error_code + } + }; + assert!(buf.is_empty(), "{version}: a refusal opens no fetch stream"); + code + } + + /// A group that does not exist, below the newest one or past it, is refused. + #[tokio::test] + async fn a_standalone_fetch_of_a_missing_group_is_refused() { + for version in FETCH_DRAFTS { + for missing in [2, 5] { + let mut h = serve(version); + publish_pairs(&mut h, 4, Some(2)); + settle().await; + + let buf = standalone_fetch( + &h, + Location { + group: missing, + object: 0, + }, + Location { + group: missing, + object: 0, + }, + GroupOrder::Ascending, + ) + .await; + assert_eq!( + fetch_refusal(buf, version), + does_not_exist(version), + "{version}: group {missing}" + ); + } + } + } + + /// A joining FETCH reaching back before the subscription's group is refused, like any + /// FETCH touching several groups. + #[tokio::test] + async fn a_joining_fetch_reaching_back_is_refused() { + for version in JOINING_DRAFTS { + let mut h = serve(version); + publish_pairs(&mut h, 4, None); + let mut group = h.track.create_group(group::Info { sequence: 4 }).unwrap(); + group.write_frame(timestamp(), b"4-0".as_slice()).unwrap(); + settle().await; + + let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); + let mut serving = std::pin::pin!( + h.publisher + .clone() + .run_subscribe_stream(stream, subscribe(Filter::NextObject, None)) + ); + registered(&h, serving.as_mut()).await; + + for fetch_type in [ + FetchType::RelativeJoining { + subscriber_request_id: RequestId(REQUEST_ID), + group_offset: 2, + }, + FetchType::AbsoluteJoining { + subscriber_request_id: RequestId(REQUEST_ID), + group_id: 1, + }, + ] { + let mark = h.log.writes.lock().unwrap().len(); + let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); + h.publisher + .clone() + .run_fetch_stream( + stream, + ietf::Fetch { + request_id: FETCH_ID, + subscriber_priority: 128, + group_order: GroupOrder::Ascending, + fetch_type, + }, + ) + .await + .unwrap(); + let buf = bytes::Bytes::from(h.log.writes.lock().unwrap()[mark..].to_vec()); + + assert_eq!(fetch_refusal(buf, version), 0x3, "{version}"); + } + } + } + + /// An absolute joining FETCH starting past the subscription's group names an empty range. + #[tokio::test] + async fn an_absolute_joining_fetch_past_the_subscription_is_refused() { + let version = Version::Draft16; + let mut h = serve(version); + publish_pairs(&mut h, 3, None); + settle().await; + + let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); + let mut serving = std::pin::pin!( + h.publisher + .clone() + .run_subscribe_stream(stream, subscribe(Filter::NextObject, None)) + ); + registered(&h, serving.as_mut()).await; + + let mark = h.log.writes.lock().unwrap().len(); + let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); + h.publisher + .clone() + .run_fetch_stream( + stream, + ietf::Fetch { + request_id: FETCH_ID, + subscriber_priority: 128, + group_order: GroupOrder::Ascending, + fetch_type: FetchType::AbsoluteJoining { + subscriber_request_id: RequestId(REQUEST_ID), + group_id: 5, + }, + }, + ) + .await + .unwrap(); + let buf = bytes::Bytes::from(h.log.writes.lock().unwrap()[mark..].to_vec()); + assert_eq!(fetch_refusal(buf, version), invalid_range(version)); + } + /// A fill against an empty track has an empty range: no fetch stream is owed. #[tokio::test] async fn an_empty_track_opens_no_fill_stream() { @@ -5033,8 +5580,8 @@ mod tests { (writes, h.log.resets()) } - /// Send a FETCH we don't implement, returning the same pair. - async fn fetch_unsupported(version: Version, fetch_type: FetchType<'_>) -> (Vec, Vec) { + /// Send a FETCH we refuse, returning the same pair. + async fn fetch_refused(version: Version, fetch_type: FetchType<'_>) -> (Vec, Vec) { let h = harness(version); let stream = Stream::open(&mut h.session.clone(), version).await.unwrap(); @@ -5078,8 +5625,8 @@ mod tests { /// Every FETCH we refuse goes out through its own error encoder, so it needs the same /// finish: a reset there loses the rejection the same way. #[tokio::test] - async fn unsupported_fetch_is_refused_without_resetting_the_stream() { - let unsupported = || { + async fn a_refused_fetch_does_not_reset_the_stream() { + let refused = || { [ ( "standalone", @@ -5091,25 +5638,20 @@ mod tests { }, ), ( - "relative joining with an offset", - FetchType::RelativeJoining { - subscriber_request_id: RequestId(3), - group_offset: 1, - }, - ), - ( - "absolute joining", - FetchType::AbsoluteJoining { - subscriber_request_id: RequestId(3), - group_id: 7, + "empty range", + FetchType::Standalone { + namespace: crate::Path::new("nothing/here"), + track: "video".into(), + start: Location { group: 2, object: 0 }, + end: Location { group: 1, object: 0 }, }, ), ] }; for version in [Version::Draft17, Version::Draft18, Version::Draft19, Version::Draft20] { - for (label, fetch_type) in unsupported() { - let (writes, resets) = fetch_unsupported(version, fetch_type).await; + for (label, fetch_type) in refused() { + let (writes, resets) = fetch_refused(version, fetch_type).await; assert!(!writes.is_empty(), "{version} {label}: nothing was sent"); assert_eq!( diff --git a/rs/moq-net/src/ietf/session.rs b/rs/moq-net/src/ietf/session.rs index fcb9f300079..2230852b538 100644 --- a/rs/moq-net/src/ietf/session.rs +++ b/rs/moq-net/src/ietf/session.rs @@ -204,6 +204,7 @@ where subscriber.clone(), version ))); + let mut datagrams = std::pin::pin!(err_only(run_datagrams(adapter.clone(), subscriber.clone()))); // Unsolicited PUBLISH_NAMESPACE unless the peer requires solicitation; // see `Publisher::run_publish_namespaces`. let mut pub_ns_run = std::pin::pin!(err_only(publisher.clone().run_publish_namespaces())); @@ -254,6 +255,9 @@ where if let Poll::Ready(err) = waiter.poll_future(dispatch.as_mut()) { return Poll::Ready(Err(err)); } + if let Poll::Ready(err) = waiter.poll_future(datagrams.as_mut()) { + return Poll::Ready(Err(err)); + } if task_set.poll(waiter).is_ready() { return Poll::Ready(Ok(())); } @@ -346,6 +350,7 @@ where subscriber.clone(), version ))); + let mut datagrams = std::pin::pin!(err_only(run_datagrams(session.clone(), subscriber.clone()))); let mut goaway_recv = std::pin::pin!(err_only(goaway_recv)); let mut setup = std::pin::pin!(setup); // Unsolicited PUBLISH_NAMESPACE unless the peer requires solicitation; @@ -385,6 +390,9 @@ where if let Poll::Ready(err) = waiter.poll_future(dispatch.as_mut()) { return Poll::Ready(Err(err)); } + if let Poll::Ready(err) = waiter.poll_future(datagrams.as_mut()) { + return Poll::Ready(Err(err)); + } if let Poll::Ready(err) = waiter.poll_future(goaway_recv.as_mut()) { return Poll::Ready(Err(err)); } @@ -725,6 +733,23 @@ where } } +/// Receive QUIC datagrams, each an OBJECT_DATAGRAM for one of our subscriptions. +/// +/// A transport without datagrams never delivers one, so this parks. A transport failure +/// or a malformed datagram ends the session. +async fn run_datagrams(mut session: S, subscriber: Subscriber) -> Result<(), Error> +where + S: crate::transport::poll::Boxable, +{ + if session.max_datagram_size() == 0 { + return Ok(()); + } + loop { + let payload = session.recv_datagram().await.map_err(Error::from_transport)?; + subscriber.recv_datagram(payload)?; + } +} + async fn run_uni_group( subscriber: &mut Subscriber, stream: &mut Reader, diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 4fc5a5c68b9..79f6cd0f6b9 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -145,6 +145,9 @@ struct State { // Joining FETCH request ids, mapped to the SUBSCRIBE they name. fetches: HashMap, + // Group FETCH request ids, filling a cache miss. + group_fetches: HashMap>, + // Track aliases chosen by the remote publisher. aliases: TrackAliases, @@ -285,6 +288,52 @@ impl Fill { } } +/// A standalone FETCH of one group through its end, from FETCH_OK to its fetch stream. +enum GroupFetch { + /// Waiting on FETCH_OK, which the fetch stream can overtake. + Pending, + /// Accepted into the track cache, waiting for the fetch stream to write it. + Ready { + producer: group::Producer, + timescale: Option, + /// The first Object ID requested, which the producer starts at. + start: u64, + /// The exclusive last Object ID, when FETCH_OK's End Location falls inside the group. + end: Option, + }, + /// A fetch stream is writing the group. + Receiving, + /// The group is written or failed. + Done, +} + +/// A group FETCH's entry in [`State::group_fetches`], removed when its request ends. +struct GroupFetchEntry { + state: Lock, + fetch_id: RequestId, + slot: kio::Producer, +} + +impl GroupFetchEntry { + fn new(state: &Lock, fetch_id: RequestId, slot: kio::Producer) -> Self { + state.lock().group_fetches.insert(fetch_id, slot.clone()); + Self { + state: state.clone(), + fetch_id, + slot, + } + } +} + +impl Drop for GroupFetchEntry { + fn drop(&mut self) { + self.state.lock().group_fetches.remove(&self.fetch_id); + // A fetch stream that overtook a refused or unserved FETCH_OK holds its own clone + // of the slot, so only closing it wakes that stream. + let _ = self.slot.close(); + } +} + /// A pre-draft-20 joining FETCH, sent as its own request after SUBSCRIBE. #[derive(Debug, Clone, Copy, PartialEq, Eq)] enum JoiningFetch { @@ -1730,6 +1779,9 @@ where true => request.resolving_start(), false => request, }; + // Serves cache misses with a group FETCH. Registered before accepting, so a miss + // queued meanwhile waits for it rather than failing for want of a handler. + let dynamic = request.dynamic(); let mut track = request.accept(info); if live { let _ = track.start_at(largest.map(|largest| largest.group)); @@ -1776,9 +1828,12 @@ where enum End { Unused, Done(Result), + Fetch(group::Request), } let mut fetch_done = fetching.is_none(); + // Group FETCHes for cache misses, cancelled with the subscription. + let mut group_fetches = TaskSet::owned(); let cancelled = { let mut done = std::pin::pin!(Self::read_publish_done(&mut stream.reader, self.version)); loop { @@ -1789,6 +1844,11 @@ where { fetch_done = true; } + // An error is the track closing, which the arms below report. + if let Poll::Ready(Ok(request)) = dynamic.poll_requested_group(waiter) { + return Poll::Ready(End::Fetch(request)); + } + let _ = group_fetches.poll(waiter); if track.poll_unused(waiter).is_ready() { return Poll::Ready(End::Unused); } @@ -1797,6 +1857,15 @@ where .await; match end { + End::Fetch(request) => { + let fetch = self.clone().run_group_fetch( + broadcast_path.to_owned(), + track_name.clone(), + request, + timescale, + ); + group_fetches.push(fetch); + } End::Unused => match track.abort_unused(Error::Cancel) { Ok(()) => { tracing::info!(broadcast = %self.origin.absolute(&broadcast_path), track = %track_name, "subscribe cancelled"); @@ -2265,6 +2334,61 @@ where Ok(()) } + + /// Deliver one OBJECT_DATAGRAM as a datagram on its subscription's track: a + /// single-frame group at the Group ID. + /// + /// A malformed datagram is the peer breaking the protocol, so it errors. One the model + /// cannot carry is dropped like any lost datagram: an Object past ID 0 (the group would + /// need a second object), a status other than Normal, or an alias that is not bound + /// yet (the draft lets us drop rather than buffer). + pub fn recv_datagram(&self, payload: bytes::Bytes) -> Result<(), Error> { + let mut buf = payload; + let datagram = ietf::ObjectDatagram::decode(&mut buf, self.version)?; + let (alias, sequence) = (datagram.track_alias, datagram.group_id); + + if datagram.object_id.unwrap_or(0) != 0 { + tracing::debug!(alias, sequence, "dropping a datagram past object 0"); + return Ok(()); + } + let payload = match datagram.body { + ietf::DatagramBody::Payload(payload) => payload, + ietf::DatagramBody::Status(0) => bytes::Bytes::new(), + ietf::DatagramBody::Status(status) => { + tracing::debug!(alias, sequence, status, "dropping a datagram status"); + return Ok(()); + } + }; + + let mut state = self.state.lock(); + let request_id = match state.aliases.read().map.get(&alias) { + Some(Alias::Active(request_id)) => *request_id, + _ => { + tracing::debug!(alias, sequence, "dropping a datagram for an unbound alias"); + return Ok(()); + } + }; + let Some(track) = state.subscribes.get_mut(&request_id) else { + return Ok(()); + }; + + // Like a subgroup object: a track that declared no timescale is stamped on arrival. + let timestamp = match (track.timescale, &datagram.properties) { + (Some(timescale), Some(properties)) => { + ietf::decode_object_time(&mut properties.as_slice(), timescale, self.version)? + } + _ => None, + }; + let timestamp = timestamp.unwrap_or_else(|| crate::Timestamp::from(self.runtime.now())); + + let Some(producer) = track.producer.as_mut() else { + return Ok(()); + }; + if let Err(err) = producer.insert_datagram(sequence, timestamp, payload) { + tracing::debug!(%err, alias, sequence, "dropping datagram"); + } + Ok(()) + } } /// Mark where the track ends, as an END_OF_TRACK object said. @@ -2303,6 +2427,9 @@ enum Ended { Track, } +/// Object status: no object at or past this location in the group exists (draft-14, 15). +const END_OF_GROUP: u64 = 0x3; + /// Object status: no object at or past this location exists (every implemented draft). const END_OF_TRACK: u64 = 0x4; @@ -2561,6 +2688,11 @@ where let _: u64 = stream.decode().await?; let header: ietf::FetchHeader = stream.decode().await?; + let group_fetch = self.state.lock().group_fetches.get(&header.request_id).cloned(); + if let Some(slot) = group_fetch { + return self.recv_group_fetch(stream, slot).await; + } + let (subscribe_id, fill, joining, largest, _counted) = { let state = self.state.lock(); // A draft-20 fill is named by the SUBSCRIBE's request id. A pre-draft-20 joining @@ -2719,7 +2851,8 @@ where head: &mut Option<(u64, u64, crate::recv::Group)>, ) -> Result<(), Error> { let mut prior_group = None; - while let Some(object) = decode_fetch_object(stream, self.version).await? { + let mut first = true; + while let Some(object) = decode_fetch_object(stream, self.version, std::mem::take(&mut first)).await? { if !object.subgroup_ok { tracing::warn!("subgroup ID is not supported, dropping fill"); return Err(Error::Unsupported); @@ -2778,40 +2911,363 @@ where } } - // The properties carry the frame's presentation timestamp (the Timestamp Object - // Property) in the units the track declared. A track that declared none opted - // out, so its frames are stamped on arrival instead. - let timestamp = match (object.properties, timescale) { - (Some(properties), Some(timescale)) => { - let mut properties = bytes::Bytes::from(properties); - ietf::decode_object_time(&mut properties, timescale, self.version)? - } - _ => None, + let (_, next, producer) = head.as_mut().expect("the head was created above"); + if !self + .recv_fetch_payload(stream, producer, object.properties, timescale) + .await? + { + return Err(Error::Unsupported); + } + *next += 1; + } + + Ok(()) + } + + /// Read one fetch object's length and payload into `producer`, after its header. + /// + /// Returns `false` for a draft-14 or 15 end-of-group or end-of-track marker, which + /// is a status rather than a frame. + async fn recv_fetch_payload( + &self, + stream: &mut Reader, + producer: &mut group::Producer, + properties: Option>, + timescale: Option, + ) -> Result { + // The properties carry the frame's presentation timestamp (the Timestamp Object + // Property) in the units the track declared. A track that declared none opted + // out, so its frames are stamped on arrival instead. + let timestamp = match (properties, timescale) { + (Some(properties), Some(timescale)) => { + let mut properties = bytes::Bytes::from(properties); + ietf::decode_object_time(&mut properties, timescale, self.version)? + } + _ => None, + }; + let timestamp = timestamp.unwrap_or_else(|| crate::Timestamp::from(self.runtime.now())); + + // A fetch object has no status field from draft-16 on; a zero length is simply + // an empty object. Draft-14 and 15 still encode Normal (0) after a zero length. + let size: u64 = stream.decode().await?; + if size == 0 && matches!(self.version, Version::Draft14 | Version::Draft15) { + match stream.decode::().await? { + 0 => {} + END_OF_GROUP | END_OF_TRACK => return Ok(false), + _ => return Err(Error::Unsupported), + } + } + + // `create_frame_owned` is the allocation chokepoint and rejects an oversized `size` + // before allocating, so no pre-check is needed. + let mut frame = producer.create_frame_owned(frame::Info { size, timestamp })?; + if let Err(err) = std::future::poll_fn(|cx| stream.poll_read_frame(cx, &mut frame)).await { + let _ = frame.abort(err.clone()); + return Err(err); + } + frame.finish()?; + Ok(true) + } + + /// Fetch a group from the publisher to fill a cache miss, with a standalone FETCH for + /// this subscription's track. It asks from the frame the reader wants through the end + /// of the group, so a publisher that evicted the prefix can still answer. + /// + /// The group is accepted only once FETCH_OK arrives, so a refusal reaches every + /// waiting [`track::Consumer::fetch_group`] as the publisher's own error. The objects + /// arrive on a fetch stream, which [`Self::recv_fill`] routes into the group. + async fn run_group_fetch( + self, + broadcast: PathOwned, + name: String, + request: group::Request, + timescale: Option, + ) { + let sequence = request.sequence(); + let start = request.frame_start(); + if self.going_away.is_set() { + request.reject(Error::GoingAway); + return; + } + // Our FETCH still encodes the Fetch Type field that draft-20 removed. + if Filter::is_draft20(self.version) { + request.reject(Error::Unsupported); + return; + } + + let fetch_id = match self.control.next_request_id(&self.runtime).await { + Ok(id) => id, + Err(err) => return request.reject(err), + }; + + // Registered before the FETCH goes out, since its fetch stream can overtake FETCH_OK. + let slot = kio::Producer::new(GroupFetch::Pending); + let _registered = GroupFetchEntry::new(&self.state, fetch_id, slot.clone()); + + let mut stream = match Stream::open(&mut self.session.clone(), self.version).await { + Ok(stream) => stream, + Err(err) => return request.reject(err), + }; + + let res = async { + stream.writer.encode(&ietf::Fetch::ID).await?; + stream + .writer + .encode(&ietf::Fetch { + request_id: fetch_id, + subscriber_priority: super::priority::to_wire(request.priority()), + group_order: GroupOrder::Ascending, + // An End Object of 0 is the whole End Group. + fetch_type: FetchType::Standalone { + namespace: broadcast.clone(), + track: name.as_str().into(), + start: ietf::Location { + group: sequence, + object: start, + }, + end: ietf::Location { + group: sequence, + object: 0, + }, + }, + }) + .await?; + self.read_group_fetch_response(&mut stream).await + } + .await; + + let ok = match res { + Ok(ok) => ok, + Err(err) => { + tracing::debug!(%err, group = sequence, "group fetch refused"); + request.reject(err); + let _ = stream.writer.close().await; + return; + } + }; + + // The publisher knows where the track ends, which a range FETCH downstream needs. + if ok.end_of_track { + let end = ok.end_location; + let Some(final_sequence) = end.group.checked_add(u64::from(end.object > 0)) else { + request.reject(Error::ProtocolViolation); + let _ = stream.writer.close().await; + return; }; - let timestamp = timestamp.unwrap_or_else(|| crate::Timestamp::from(self.runtime.now())); - - // A fetch object has no status field from draft-16 on; a zero length is simply - // an empty object. Draft-14 and 15 still encode Normal (0) after a zero length. - let size: u64 = stream.decode().await?; - if size == 0 && matches!(self.version, Version::Draft14 | Version::Draft15) { - let status: u64 = stream.decode().await?; - if status != 0 { - return Err(Error::Unsupported); + request.finish_track_at(final_sequence); + } + + // An empty answer opens no fetch stream at all. + let end = ok.end_location; + if (end.group, end.object) <= (sequence, start) { + request.reject(Error::NotFound); + let _ = stream.writer.close().await; + return; + } + // An exclusive End Location inside the group is its Largest Object plus one, so + // the stream owes every object up to it. One past the group covers it whole. + let end = (end.group == sequence).then_some(end.object); + + // Only a track nothing has subscribed to yet takes this info, as SUBSCRIBE_OK would + // have set it. + let info = track::Info::default() + .with_timescale(Timescale::MICRO) + .with_max_age(self.origin.default_max_age()); + let mut producer = match request.accept(info) { + Ok(producer) => producer, + // Already served by a concurrent fetch, or the track closed. + Err(err) => { + tracing::debug!(%err, group = sequence, "group fetch not served"); + let _ = stream.writer.close().await; + return; + } + }; + // The objects keep the IDs they have in the group rather than restarting at 0. + if let Err(err) = producer.start_at(start) { + let _ = producer.abort(err); + let _ = stream.writer.close().await; + return; + } + if let Ok(mut state) = slot.write() { + *state = GroupFetch::Ready { + producer, + timescale, + start, + end, + }; + } + + // Hold the request open until its fetch stream is done: closing our side first is + // what a draft-14-16 adapter reads as cancelling the FETCH. A publisher that fails + // after FETCH_OK resets the request instead and owes no fetch stream, so the group + // it left waiting is aborted. A FIN is not that: the fetch stream can trail it. + let mut open = true; + let reset = kio::wait(|waiter| { + if open { + let mut cx = std::task::Context::from_waker(waiter.waker()); + match stream.reader.poll_closed(&mut cx) { + Poll::Ready(Err(err)) => return Poll::Ready(Some(err)), + Poll::Ready(Ok(())) => open = false, + Poll::Pending => {} } } + slot.poll(waiter, |state| match &**state { + GroupFetch::Done => Poll::Ready(()), + _ => Poll::Pending, + }) + .map(|_| None) + }) + .await; + if let Some(err) = reset + && let Ok(mut state) = slot.write() + && matches!(*state, GroupFetch::Ready { .. }) + && let GroupFetch::Ready { producer, .. } = std::mem::replace(&mut *state, GroupFetch::Done) + { + let _ = producer.abort(err); + } + let _ = stream.writer.close().await; + } - let (_, next, producer) = head.as_mut().expect("the head was created above"); + /// Read the answer to a group FETCH: FETCH_OK, or the publisher's refusal as an error. + async fn read_group_fetch_response(&self, stream: &mut Stream) -> Result { + let type_id: u64 = stream.reader.decode().await?; + let size: u16 = stream.reader.decode().await?; + let mut data = stream.reader.read_exact(size as usize).await?; - // `create_frame_owned` is the allocation chokepoint and rejects an oversized `size` - // before allocating, so no pre-check is needed. - let mut frame = producer.create_frame_owned(frame::Info { size, timestamp })?; - if let Err(err) = std::future::poll_fn(|cx| stream.poll_read_frame(cx, &mut frame)).await { - let _ = frame.abort(err.clone()); - return Err(err); + match type_id { + ietf::FetchOk::ID => Ok(ietf::FetchOk::decode_msg(&mut data, self.version)?), + ietf::FetchError::ID if self.version == Version::Draft14 => { + let msg = ietf::FetchError::decode_msg(&mut data, self.version)?; + Err(request::from_code(msg.error_code, request::Kind::Fetch, self.version)) } - frame.finish()?; + ietf::RequestError::ID => { + let msg = ietf::RequestError::decode_msg(&mut data, self.version)?; + Err(request::from_code(msg.error_code, request::Kind::Fetch, self.version)) + } + _ => Err(Error::UnexpectedMessage), + } + } - *next += 1; + /// Write a group FETCH's objects into the group it accepted. + async fn recv_group_fetch( + &mut self, + stream: &mut Reader, + slot: kio::Producer, + ) -> Result<(), Error> { + // FETCH_OK can trail its own fetch stream. Taking the group in the same step is + // what refuses a second stream for one request. + let taken = kio::wait(|waiter| { + match slot.poll(waiter, |state| match &**state { + GroupFetch::Pending => Poll::Pending, + _ => Poll::Ready(()), + }) { + Poll::Ready(Ok(mut state)) => { + Poll::Ready(match std::mem::replace(&mut *state, GroupFetch::Receiving) { + GroupFetch::Ready { + producer, + timescale, + start, + end, + } => Ok((producer, timescale, start, end)), + other => { + *state = other; + Err(Error::Unsupported) + } + }) + } + Poll::Ready(Err(_)) => Poll::Ready(Err(Error::Dropped)), + Poll::Pending => Poll::Pending, + } + }) + .await; + let (producer, timescale, start, end) = taken?; + + let mut producer = crate::recv::Group::new(producer); + let res = match self + .recv_group_fetch_objects(stream, &mut producer, start, end, timescale) + .await + { + Ok(()) => producer.finish(), + Err(err) => { + let _ = producer.abort(err.clone()); + Err(err) + } + }; + + if let Ok(mut state) = slot.write() { + *state = GroupFetch::Done; + } + res + } + + /// Decode one group's objects: all in the producer's group, numbered from `start` with + /// no gaps, and through `end` (exclusive) when FETCH_OK named one inside the group. + async fn recv_group_fetch_objects( + &self, + stream: &mut Reader, + producer: &mut group::Producer, + start: u64, + end: Option, + timescale: Option, + ) -> Result<(), Error> { + let sequence = producer.info().sequence; + let mut next = start; + let mut prior_group = None; + let mut ended = false; + let mut first = true; + while let Some(object) = decode_fetch_object(stream, self.version, std::mem::take(&mut first)).await? { + if ended { + tracing::warn!(sequence, "a group fetch continued past its end marker"); + return Err(Error::ProtocolViolation); + } + if !object.subgroup_ok { + tracing::warn!("subgroup ID is not supported, dropping group fetch"); + return Err(Error::Unsupported); + } + + let group = resolve_fetch_group(self.version, prior_group, object.group)?; + if let Some(group) = group { + prior_group = Some(group); + } + let id = match (object.group.is_some(), object.object) { + (true, Some(id)) => Some(id), + (false, None | Some(1)) => Some(next), + _ => None, + }; + // Another group, or an ID before the next one, is outside what was asked for. + if group.is_some_and(|group| group != sequence) || id.is_some_and(|id| id < next) { + tracing::warn!(sequence, next, group = ?group, object = ?id, "a group fetch answered outside its range"); + return Err(Error::ProtocolViolation); + } + // A skipped ID is an object that does not exist, a hole the model cannot hold. + if id != Some(next) { + tracing::warn!(sequence, next, object = ?id, "a group fetch skipped an object"); + return Err(Error::Unsupported); + } + + match self + .recv_fetch_payload(stream, producer, object.properties, timescale) + .await? + { + true => next += 1, + false => ended = true, + } + if end.is_some_and(|end| next > end) { + tracing::warn!(sequence, ?end, "a group fetch continued past FETCH_OK's End Location"); + return Err(Error::ProtocolViolation); + } + } + + // A clean FIN short of the promised end would otherwise cache a truncated group as + // a complete one. + if end.is_some_and(|end| next < end) { + tracing::warn!( + sequence, + next, + ?end, + "a group fetch ended before FETCH_OK's End Location" + ); + return Err(Error::ProtocolViolation); } Ok(()) @@ -2827,9 +3283,13 @@ struct FetchedObject { } /// Decode the next fetch object header, or `None` at stream end. +/// +/// The `first` object on a stream has no prior to inherit from, so a field it leaves to +/// the prior object is a protocol violation. async fn decode_fetch_object( stream: &mut Reader, version: Version, + first: bool, ) -> Result, Error> { if version == Version::Draft14 { let Some(group) = stream.decode_maybe::().await? else { @@ -2857,17 +3317,27 @@ async fn decode_fetch_object( subgroup, group, object, + priority, properties, - .. - }) => Some(FetchedObject { - group, - object, - subgroup_ok: matches!( - subgroup, - ietf::FetchSubgroup::Zero | ietf::FetchSubgroup::Prior | ietf::FetchSubgroup::Explicit(0) - ), - properties, - }), + }) => { + let inherits = group.is_none() + || object.is_none() + || priority.is_none() + || matches!(subgroup, ietf::FetchSubgroup::Prior | ietf::FetchSubgroup::PriorPlusOne); + if first && inherits { + tracing::warn!("the first fetch object refers to a prior object"); + return Err(Error::ProtocolViolation); + } + Some(FetchedObject { + group, + object, + subgroup_ok: matches!( + subgroup, + ietf::FetchSubgroup::Zero | ietf::FetchSubgroup::Prior | ietf::FetchSubgroup::Explicit(0) + ), + properties, + }) + } }) } @@ -3009,7 +3479,7 @@ impl GroupIngest { let frame = group.create_frame_owned(frame::Info { size: 0, timestamp })?; frame.finish()?; self.phase = IngestPhase::Delta; - } else if status == 3 && !self.has_end { + } else if status == END_OF_GROUP && !self.has_end { self.phase = IngestPhase::Finished(Ended::Group); } else if status == END_OF_TRACK { // Defined on every implemented draft, whether or not the header marks @@ -3508,6 +3978,67 @@ mod tests { ); } + /// An OBJECT_DATAGRAM at object 0 is a datagram group at its Group ID; anything the model + /// cannot carry as one is dropped, and a malformed one is the peer's violation. + #[tokio::test] + async fn an_object_datagram_is_a_datagram_group() { + use crate::coding::Encode as _; + use futures::FutureExt as _; + + let subscriber = subscriber_with_tracks(&[(RequestId(11), "cam", "audio")]); + subscriber.register_alias(RequestId(11), 7).unwrap(); + let mut consumer = { + let mut state = subscriber.state.lock(); + let track = state.subscribes.get_mut(&RequestId(11)).unwrap(); + track.timescale = Some(Timescale::default()); + track.producer.as_ref().unwrap().subscribe(None) + }; + + let timestamp = crate::Timestamp::new(96_000, Timescale::default()).unwrap(); + let datagram = |alias: u64, group_id: u64, object_id: Option, body: ietf::DatagramBody| { + let mut properties = Vec::new(); + ietf::encode_object_time(&mut properties, timestamp, Timescale::default(), Version::Draft19).unwrap(); + ietf::ObjectDatagram { + track_alias: alias, + group_id, + object_id, + publisher_priority: None, + // Only a Normal Object may carry Properties, and a status cannot end the group. + end_of_group: matches!(body, ietf::DatagramBody::Payload(_)), + properties: matches!(body, ietf::DatagramBody::Payload(_)).then_some(properties), + body, + } + .encode_bytes(Version::Draft19) + .unwrap() + }; + let payload = |bytes: &'static [u8]| ietf::DatagramBody::Payload(bytes::Bytes::from_static(bytes)); + + // Dropped: a second object in the group, an unbound alias, and a status. + subscriber + .recv_datagram(datagram(7, 4, Some(1), payload(b"no"))) + .unwrap(); + subscriber.recv_datagram(datagram(8, 4, None, payload(b"no"))).unwrap(); + subscriber + .recv_datagram(datagram(7, 4, None, ietf::DatagramBody::Status(END_OF_TRACK))) + .unwrap(); + + subscriber + .recv_datagram(datagram(7, 9, Some(0), payload(b"yes"))) + .unwrap(); + let received = consumer.recv_datagram().now_or_never().unwrap().unwrap().unwrap(); + assert_eq!(received.sequence, 9, "the Group ID is the sequence"); + assert_eq!(received.timestamp, timestamp); + assert_eq!(&received.payload[..], b"yes"); + assert!( + consumer.recv_datagram().now_or_never().is_none(), + "only one got through" + ); + + // A status datagram cannot end the group. + let malformed = bytes::Bytes::from_static(&[0x22, 0x07, 0x04, 0x00]); + assert!(is_protocol_violation(&subscriber.recv_datagram(malformed).unwrap_err())); + } + /// One alias naming two different tracks is the collision section 11.1 makes fatal. #[test] fn an_alias_reused_for_another_track_is_fatal() { @@ -6591,6 +7122,177 @@ mod stitch_tests { assert_eq!(frames[0].1, b"g7-0"); assert_eq!(frames[1].1, b"g7-1"); } + + /// A draft-14/15 end-of-group marker ends a group fetch, so an object after it is a + /// violation rather than another frame. + #[tokio::test] + async fn a_group_fetch_refuses_an_object_past_its_end_marker() { + const DRAFT: Version = Version::Draft15; + let header = |object: u64| ietf::FetchObject::Object { + subgroup: ietf::FetchSubgroup::Zero, + group: Some(SEQUENCE), + object: Some(object), + priority: Some(0), + properties: None, + }; + let mut buf = bytes::BytesMut::new(); + header(0).encode(&mut buf, DRAFT).unwrap(); + 1u64.encode(&mut buf, DRAFT).unwrap(); + buf.put_slice(b"a"); + header(1).encode(&mut buf, DRAFT).unwrap(); + 0u64.encode(&mut buf, DRAFT).unwrap(); + END_OF_GROUP.encode(&mut buf, DRAFT).unwrap(); + header(1).encode(&mut buf, DRAFT).unwrap(); + 1u64.encode(&mut buf, DRAFT).unwrap(); + buf.put_slice(b"b"); + + let mut run = GroupFetchRun::new(DRAFT, buf.to_vec()).await; + let res = run.recv_objects(0, None).await; + assert!(matches!(res, Err(Error::ProtocolViolation)), "{res:?}"); + } + + /// The first object on a fetch stream has no prior object, so leaving any field to + /// the prior one is a violation, not "the requested group, from its start". + #[tokio::test] + async fn a_group_fetch_refuses_a_first_object_that_inherits() { + use ietf::FetchSubgroup::{Prior, Zero}; + let header = |group, object, subgroup, priority| ietf::FetchObject::Object { + subgroup, + group, + object, + priority, + properties: None, + }; + let headers = [ + // Both IDs omitted: "the requested group, from its start" is exactly the bug. + header(None, None, Zero, Some(0)), + header(Some(SEQUENCE), None, Zero, Some(0)), + header(Some(SEQUENCE), Some(0), Prior, Some(0)), + header(Some(SEQUENCE), Some(0), Zero, None), + ]; + + for version in [Version::Draft15, VERSION] { + for header in &headers { + let mut buf = bytes::BytesMut::new(); + header.encode(&mut buf, version).unwrap(); + 1u64.encode(&mut buf, version).unwrap(); + buf.put_slice(b"a"); + + let mut run = GroupFetchRun::new(version, buf.to_vec()).await; + let res = run.recv_objects(0, None).await; + assert!( + matches!(res, Err(Error::ProtocolViolation)), + "{version} {header:?}: {res:?}" + ); + } + } + } + + /// FETCH_OK's End Location inside the group promises every object before it. A stream + /// that FINs short of it, or runs past it, fails the group instead of caching it. + #[tokio::test] + async fn a_group_fetch_must_reach_its_end_location() { + const END: u64 = 3; + for (count, complete) in [(2, false), (3, true), (4, false)] { + let payloads: Vec<&[u8]> = [b"a", b"b", b"c", b"d"][..count].iter().map(|p| &p[..]).collect(); + let mut run = GroupFetchRun::new(VERSION, group_fetch_objects(SEQUENCE, 0, &payloads)).await; + + let group = run.track.create_group(group::Info { sequence: SEQUENCE }).unwrap(); + let mut consumer = group.consume(); + let slot = kio::Producer::new(GroupFetch::Ready { + producer: group, + timescale: None, + start: 0, + end: Some(END), + }); + let res = run.subscriber.recv_group_fetch(&mut run.stream, slot).await; + assert_eq!(res.is_ok(), complete, "{count} objects: {res:?}"); + + let mut read = 0; + let end = loop { + match consumer.read_frame().await { + Ok(Some(_)) => read += 1, + Ok(None) => break Ok(read), + Err(err) => break Err(err), + } + }; + match complete { + true => assert_eq!(end.expect("a complete group"), END), + false => assert!(end.is_err(), "{count} objects: the group must fail, not end"), + } + } + } + + /// A group fetch's objects after the FETCH_HEADER: the first one names the group and + /// `start`, and every later one is the next object. + fn group_fetch_objects(sequence: u64, start: u64, payloads: &[&[u8]]) -> Vec { + let mut buf = bytes::BytesMut::new(); + for (index, payload) in payloads.iter().enumerate() { + let first = index == 0; + ietf::FetchObject::Object { + subgroup: ietf::FetchSubgroup::Zero, + group: first.then_some(sequence), + object: first.then_some(start), + priority: first.then_some(0), + properties: None, + } + .encode(&mut buf, VERSION) + .unwrap(); + (payload.len() as u64).encode(&mut buf, VERSION).unwrap(); + buf.put_slice(payload); + } + buf.to_vec() + } + + /// A subscriber reading one scripted group fetch stream, already past its header. + struct GroupFetchRun { + subscriber: Subscriber, + stream: Reader<::RecvStream, Version>, + track: track::Producer, + _tasks: (Tasks, TaskSet), + } + + impl GroupFetchRun { + async fn new(version: Version, objects: Vec) -> Self { + let mut session = ScriptedSession::per_stream_eof(vec![objects]); + let tasks = TaskSet::new(); + let subscriber = Subscriber::new( + crate::time::Clock::tokio(), + session.clone(), + crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(), + Control::new(None, false), + None, + peer::PeerSetup::default(), + crate::Hop::new(1).unwrap(), + None, + version, + tasks.0.clone(), + Default::default(), + ); + let (_, recv) = session.open_bi().await.unwrap(); + let track = track::Producer::new( + std::sync::Arc::new(crate::broadcast::Info::default()), + "video", + track::Info::default(), + ); + + Self { + subscriber, + stream: Reader::new(recv, version), + track, + _tasks: tasks, + } + } + + /// Decode the stream into a fresh group numbered from `start`. + async fn recv_objects(&mut self, start: u64, end: Option) -> Result<(), Error> { + let mut group = self.track.create_group(group::Info { sequence: SEQUENCE }).unwrap(); + group.start_at(start).unwrap(); + self.subscriber + .recv_group_fetch_objects(&mut self.stream, &mut group, start, end, None) + .await + } + } } /// A scripted peer answering SUBSCRIBE then FETCH, so the join is spelled on the wire. @@ -6601,6 +7303,7 @@ mod joining_fetch_tests { coding::Encode as _, lite::test_transport::ScriptedSession, model::ProduceTest, + transport::poll::Session as _, util::{TaskSet, Tasks}, }; @@ -6901,4 +7604,179 @@ mod joining_fetch_tests { let writes = log.writes.lock().unwrap().clone(); assert!(writes.is_empty(), "a refused join must not write SUBSCRIBE"); } + + /// A publisher that resets the request after FETCH_OK owes no fetch stream, so the + /// group it accepted is aborted instead of left open for every reader to wait on. + /// Without that, `run_group_fetch` never returns. + #[tokio::test(start_paused = true)] + async fn a_group_fetch_reset_after_fetch_ok_aborts_the_group() { + const VERSION: Version = Version::Draft19; + const GROUP: u64 = 4; + + let ok = message_bytes( + ietf::FetchOk::ID, + &ietf::FetchOk { + request_id: None, + group_order: GroupOrder::Ascending, + end_of_track: false, + end_location: ietf::Location { + group: GROUP + 1, + object: 0, + }, + }, + VERSION, + ); + + let session = ScriptedSession::per_stream_reset(vec![ok]); + let (tasks, _task_set) = crate::util::TaskSet::new(); + let subscriber = Subscriber::new( + crate::time::Clock::tokio(), + session.clone(), + crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(), + Control::new(None, false), + None, + peer::PeerSetup::default(), + crate::Hop::new(1).unwrap(), + None, + VERSION, + tasks, + Default::default(), + ); + + let track = track::Producer::new( + std::sync::Arc::new(crate::broadcast::Info::default()), + "video", + track::Info::default(), + ); + let dynamic = track.dynamic(); + let consumer = track.consume(); + let mut fetch = std::pin::pin!(consumer.fetch_group(GROUP, None)); + assert!(futures::poll!(fetch.as_mut()).is_pending()); + let request = dynamic.requested_group().await.expect("no group requested"); + + subscriber + .clone() + .run_group_fetch(Path::new("broadcast").to_owned(), "video".into(), request, None) + .await; + + assert!(fetch.await.is_err(), "the accepted group was aborted"); + } + + /// A cache miss for a group's tail asks upstream from the frame the reader wants and + /// numbers what arrives from there, so a publisher that evicted the prefix can answer. + #[tokio::test(start_paused = true)] + async fn a_group_fetch_asks_from_the_wanted_frame() { + const VERSION: Version = Version::Draft19; + const GROUP: u64 = 4; + const START: u64 = 2; + + let ok = message_bytes( + ietf::FetchOk::ID, + &ietf::FetchOk { + request_id: None, + group_order: GroupOrder::Ascending, + end_of_track: false, + end_location: ietf::Location { + group: GROUP + 1, + object: 0, + }, + }, + VERSION, + ); + + // The fetch stream answering our first request id, from object START on. + let mut objects = bytes::BytesMut::new(); + ietf::FetchHeader::TYPE.encode(&mut objects, VERSION).unwrap(); + ietf::FetchHeader { + request_id: RequestId(1), + } + .encode(&mut objects, VERSION) + .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, + } + .encode(&mut objects, VERSION) + .unwrap(); + 1u64.encode(&mut objects, VERSION).unwrap(); + objects.extend_from_slice(&payload[..]); + } + + let session = ScriptedSession::per_stream_eof(vec![ok, objects.to_vec()]); + let (tasks, _task_set) = crate::util::TaskSet::new(); + let subscriber = Subscriber::new( + crate::time::Clock::tokio(), + session.clone(), + crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(), + Control::new(None, false), + None, + peer::PeerSetup::default(), + crate::Hop::new(1).unwrap(), + None, + VERSION, + tasks, + Default::default(), + ); + + let track = track::Producer::new( + std::sync::Arc::new(crate::broadcast::Info::default()), + "video", + track::Info::default(), + ); + let dynamic = track.dynamic(); + let consumer = track.consume(); + let mut fetch = std::pin::pin!(consumer.fetch_group(GROUP, group::Fetch::default().with_frame_start(START))); + assert!(futures::poll!(fetch.as_mut()).is_pending()); + let request = dynamic.requested_group().await.expect("no group requested"); + + let serving = tokio::spawn(subscriber.clone().run_group_fetch( + Path::new("broadcast").to_owned(), + "video".into(), + request, + None, + )); + settle().await; + + // The fetch stream, as the peer would open it. + let (_, recv) = session.clone().open_bi().await.unwrap(); + let mut stream = Reader::new(recv, VERSION); + subscriber.clone().recv_fill(&mut stream).await.expect("group fetch"); + serving.await.expect("run_group_fetch"); + + let mut group = fetch.await.expect("fetched"); + assert_eq!(group.index(), START, "the group starts where the reader wanted"); + let mut payloads = Vec::new(); + while let Some(frame) = group.read_frame().await.expect("complete") { + payloads.push(frame.payload.to_vec()); + } + assert_eq!(payloads, [b"c".to_vec(), b"d".to_vec()]); + + let messages = decode_messages(&session.log, VERSION); + let fetch = messages.iter().find(|(id, _)| *id == ietf::Fetch::ID).expect("FETCH"); + let mut body = fetch.1.clone(); + let msg = ietf::Fetch::decode_msg(&mut body, VERSION).unwrap(); + let FetchType::Standalone { start, end, .. } = msg.fetch_type else { + panic!("a group fetch is standalone: {:?}", msg.fetch_type); + }; + assert_eq!( + start, + ietf::Location { + group: GROUP, + object: START + } + ); + assert_eq!( + end, + ietf::Location { + group: GROUP, + object: 0 + }, + "through the end of the group" + ); + } } diff --git a/rs/moq-net/src/lite/test_transport.rs b/rs/moq-net/src/lite/test_transport.rs index ff69af76af1..497cb3b3267 100644 --- a/rs/moq-net/src/lite/test_transport.rs +++ b/rs/moq-net/src/lite/test_transport.rs @@ -546,6 +546,8 @@ pub struct ScriptedRecv { /// Report EOF once the script is exhausted rather than parking, so a test can drive /// a read loop all the way through its exit path. See [`ScriptedSession::eof`]. eof: bool, + /// Report a reset once the script is exhausted. See [`ScriptedSession::per_stream_reset`]. + reset: bool, log: Log, } @@ -566,6 +568,7 @@ impl poll::RecvStream for ScriptedRecv { }; match take { + 0 if self.reset => Poll::Ready(Err(SinkError)), 0 if self.eof => Poll::Ready(Ok(None)), 0 => Poll::Pending, take => Poll::Ready(Ok(Some(take))), @@ -592,6 +595,8 @@ pub struct ScriptedSession { pub log: Log, /// Whether an exhausted script reports EOF instead of parking. eof: bool, + /// Whether an exhausted script reports a reset instead of parking. + reset: bool, script: Arc>>, /// Per-stream scripts popped by `open_bi` in order; `None` shares `script` /// across every stream. @@ -611,6 +616,7 @@ impl ScriptedSession { Self { log: Log::default(), eof: false, + reset: false, script: Arc::new(Mutex::new(script)), queue: None, open_gate: None, @@ -661,6 +667,15 @@ impl ScriptedSession { } } + /// Like [`Self::per_stream`], but an exhausted script resets the stream, as a peer + /// that fails after replying would. + pub fn per_stream_reset(scripts: Vec>) -> Self { + Self { + reset: true, + ..Self::per_stream(scripts) + } + } + /// Append to the shared script: the peer sending more on a stream it already opened. /// Nothing is woken, so the test re-polls the reader itself. pub fn push(&self, bytes: &[u8]) { @@ -689,6 +704,7 @@ impl poll::Session for ScriptedSession { Poll::Ready(Ok(ScriptedRecv { script: Arc::new(Mutex::new(script)), eof: self.eof, + reset: self.reset, log: self.log.clone(), })) } @@ -720,6 +736,7 @@ impl poll::Session for ScriptedSession { ScriptedRecv { script, eof: self.eof, + reset: self.reset, log: self.log.clone(), }, ))) diff --git a/rs/moq-net/src/lite/track.rs b/rs/moq-net/src/lite/track.rs index 68f2e10d487..1d4ad41da06 100644 --- a/rs/moq-net/src/lite/track.rs +++ b/rs/moq-net/src/lite/track.rs @@ -133,7 +133,7 @@ mod test { let mut buf = Vec::new(); info.encode(&mut buf, Version::Lite05).unwrap(); - assert_eq!(buf, [0x06, 0x00, 0x00, 0x53, 0x88, 0x43, 0xe8]); + assert_eq!(buf, [0x06, 0x7f, 0x00, 0x53, 0x88, 0x43, 0xe8]); } #[test] diff --git a/rs/moq-net/src/model/bandwidth.rs b/rs/moq-net/src/model/bandwidth.rs index 735ab783392..58977552ea3 100644 --- a/rs/moq-net/src/model/bandwidth.rs +++ b/rs/moq-net/src/model/bandwidth.rs @@ -232,9 +232,9 @@ impl Allocator { /// decision about what to *produce*, and there is no single subscriber /// priority to read when several are watching one track. /// - /// That last part is what carries the common case, since publishers leave - /// `priority` at its default today: one tier of audio and video still serves - /// audio's small reservation in full before video takes the remainder. + /// That last part carries a publisher that leaves `priority` at its default: + /// one tier of audio and video still serves audio's small reservation in full + /// before video takes the remainder. /// /// The reservation lasts as long as the returned [`Reservation`]: hold it for as /// long as the sender is publishing, change the ceiling with @@ -663,9 +663,8 @@ mod tests { assert_eq!(allocate(bps(1_000_000), &wants, 1), Some(bps(0))); } - /// Publishers don't set [`track::Info::priority`] today (it defaults to 0 and - /// `hang::container::track_info` leaves it there), so audio and video land in - /// one tier. That has to come out right anyway, and it does: max-min fair + /// A publisher that doesn't set [`track::Info::priority`] puts audio and video + /// in one tier. That has to come out right anyway, and it does: max-min fair /// satisfies the small claim first, so audio still gets its full reservation /// and video takes the rest. Priority only changes the answer once a tier's /// smaller claims outgrow an even split. diff --git a/rs/moq-net/src/model/datagram.rs b/rs/moq-net/src/model/datagram.rs index f3055072079..a8c20b09796 100644 --- a/rs/moq-net/src/model/datagram.rs +++ b/rs/moq-net/src/model/datagram.rs @@ -8,10 +8,10 @@ //! //! Delivery is best-effort per hop: a session drops (with a debug log) any datagram whose encoded //! body exceeds the transport's datagram size, and sessions that can't carry datagrams at all -//! (IETF moq-transport, moq-lite before 05, or stream-only transports like WebSocket) never -//! deliver them. +//! (moq-lite before 05, or stream-only transports like WebSocket) never deliver them. //! -//! Wire counterpart: [`crate::lite::Datagram`]. +//! Wire counterparts: [`crate::lite::Datagram`], and on moq-transport an OBJECT_DATAGRAM at +//! object 0 whose Group ID is the sequence ([`crate::ietf::ObjectDatagram`]). use bytes::Bytes; diff --git a/rs/moq-net/src/model/resume.rs b/rs/moq-net/src/model/resume.rs index 089c361fafc..5e797e0835e 100644 --- a/rs/moq-net/src/model/resume.rs +++ b/rs/moq-net/src/model/resume.rs @@ -727,6 +727,13 @@ impl Consumer { self.state.read().latest() } + /// The newest segment's declared exclusive end, where fetches are routed. + pub(crate) fn final_sequence(&self) -> Option { + // Copied out: the segment's track takes its own lock. + let track = self.state.read().segments.last().map(|segment| segment.track.clone())?; + track.final_sequence() + } + /// One past the newest position across the segments: where a route taking this /// logical track over would resume. pub(crate) fn resume_position(&self) -> Option { @@ -843,11 +850,13 @@ impl kio::Pollable for Fetching { type Output = Result; fn poll(&self, waiter: &kio::Waiter) -> Poll { - if let Some(group) = (Consumer { + if let Some(mut group) = (Consumer { state: self.state.clone(), }) .cached_group(self.sequence, self.options.frame_start) { + // Sitting where the caller asked, as a fetch from the segment's own track would. + group.start_at(self.options.frame_start); return Poll::Ready(Ok(group)); } @@ -2928,6 +2937,33 @@ mod test { assert_eq!(read(&mut group), b"b4"); } + /// A cached copy is handed back sitting at the requested frame, the same as a fetch + /// the segment's own track answers. + #[tokio::test] + async fn a_cached_fetch_starts_at_the_requested_frame() { + let (track_a, consumer_a) = track_pair("a"); + let mut producer = Producer::new(); + producer.switch(&consumer_a, None).unwrap(); + + let mut group = track_a.create_group(group::Info { sequence: 0 }).unwrap(); + for payload in ["f0", "f1", "f2"] { + group + .write_frame(crate::Timestamp::ZERO, payload.as_bytes().to_vec()) + .unwrap(); + } + group.finish().unwrap(); + + let mut group = producer + .consume() + .fetch_group(0, group::Fetch::default().with_frame_start(1)) + .now_or_never() + .expect("cached fetch should resolve") + .unwrap(); + assert_eq!(group.index(), 1); + let frame = group.read_frame().now_or_never().unwrap().unwrap().unwrap(); + assert_eq!(frame.payload.as_ref(), b"f1"); + } + #[tokio::test] async fn fetch_waits_for_first_segment() { let (mut track_a, consumer_a) = track_pair("a"); diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 49aa3ba2ecb..c3bc6f17b06 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -35,6 +35,10 @@ use std::{ /// Default [`Info::max_age`] when the publisher doesn't set one. pub const DEFAULT_MAX_AGE: Duration = Duration::from_secs(5); +// The higher-first midpoint. IETF flips priority (lower first), so this goes out as 128, the +// draft's usual publisher priority, while moq-lite carries 127 as written: one urgency on both. +const DEFAULT_PRIORITY: u8 = 127; + /// Maximum number of datagrams retained in the per-track send buffer. /// /// Datagrams are a best-effort send buffer, not a replay cache (unlike groups): only the last @@ -106,6 +110,7 @@ pub struct Info { pub max_age: Duration, /// The publisher's priority for this track, used only to break ties between /// subscriptions of equal subscriber priority. Reported in TRACK_INFO (Lite05+). + /// Higher is more urgent. Defaults to 127, the midpoint. pub priority: u8, } @@ -114,7 +119,7 @@ impl Default for Info { Self { timescale: Timescale::default(), max_age: DEFAULT_MAX_AGE, - priority: 0, + priority: DEFAULT_PRIORITY, } } } @@ -1374,9 +1379,8 @@ impl Producer { /// track's groups but drawing from the same sequence namespace (so interleaving with /// [`Self::append_group`] never reuses a number). There is no group fallback: each /// session drops (with a debug log) any datagram whose encoded body exceeds the - /// transport's datagram size, and sessions that can't carry datagrams at all (IETF - /// moq-transport, moq-lite before 05, or stream-only transports like WebSocket) never - /// deliver them. Keep payloads well under the 1200-byte minimum path MTU. An origin + /// transport's datagram size, and sessions that can't carry datagrams at all (moq-lite + /// before 05, or stream-only transports like WebSocket) never deliver them. Keep payloads well under the 1200-byte minimum path MTU. An origin /// publisher uses this; a relay preserving upstream numbering uses /// [`Self::insert_datagram`]. pub fn append_datagram(&mut self, timestamp: Timestamp, payload: B) -> Result { @@ -2229,7 +2233,11 @@ impl Demand { /// The publisher's tie-break priority, as set in [`Info::priority`]. pub(crate) fn priority(&self) -> u8 { // Always Some once the track exists; a closed one reads its last value. - self.state.read().info.as_ref().map_or(0, |info| info.priority) + self.state + .read() + .info + .as_ref() + .map_or(DEFAULT_PRIORITY, |info| info.priority) } /// Whether anyone is subscribed right now, without waiting. @@ -2788,6 +2796,16 @@ impl Consumer { } } + /// The declared exclusive final sequence, or `None` while the track is open ended. + /// + /// A spliced track answers for its newest segment, which is where fetches go. + pub(crate) fn final_sequence(&self) -> Option { + match &self.inner { + ConsumerKind::Plain(state) => state.read().final_sequence, + ConsumerKind::Spliced(resume) => resume.final_sequence(), + } + } + /// The frame-precise point a replacement route should resume from: one past the /// last frame this copy produced. `None` if it produced nothing. /// @@ -2982,6 +3000,16 @@ impl group::Request { res } + /// Declare the track's exclusive final sequence, as the publisher answering this + /// fetch reported it. A no-op once the track declared one, or holds a later group. + pub(crate) fn finish_track_at(&self, final_sequence: u64) { + if let Ok(mut state) = TrackState::modify(&self.state) + && state.final_sequence.is_none() + { + let _ = state.set_final(final_sequence); + } + } + /// Reject the fetch, resolving every joined [`Consumer::fetch_group`] with `err`. pub fn reject(mut self, err: Error) { self.done = true; diff --git a/rs/moq-net/tests/datagram.rs b/rs/moq-net/tests/datagram.rs index 4cc78b1297d..d974cc580e5 100644 --- a/rs/moq-net/tests/datagram.rs +++ b/rs/moq-net/tests/datagram.rs @@ -1,4 +1,4 @@ -//! MoQ Lite datagram delivery over the in-memory mock transport. +//! Datagram delivery over the in-memory mock transport, on moq-lite and moq-transport. //! //! Covers the whole receive path end to end: publisher encoding, the transport's //! datagram channel, the subscriber's receive loop and `route_datagram`, and @@ -9,7 +9,6 @@ mod support; use std::time::Duration; -use futures::FutureExt as _; use moq_net::{Hop, Timestamp, Version}; use support::harness::{MockConnectOptions, MockPair, connect_mock}; @@ -110,53 +109,74 @@ async fn datagrams_reach_the_subscriber_in_order() { .expect("timed out"); } -/// MoQ Transport has no datagram mapping: groups still flow, inserted datagrams do not. +/// MoQ Transport carries a datagram as an OBJECT_DATAGRAM at object 0, so it arrives as a +/// datagram with its sequence, alongside the groups on streams. #[tokio::test] -async fn ietf_does_not_deliver_datagrams() { - tokio::time::timeout(TEST_TIMEOUT, async { - let publisher = produce_origin(1); - let consumer_origin = produce_origin(2); +async fn ietf_delivers_datagrams() { + for version in [ + "moq-transport-14", + "moq-transport-16", + "moq-transport-17", + "moq-transport-20", + ] { + tokio::time::timeout(TEST_TIMEOUT, ietf_delivers_datagrams_on(version)) + .await + .unwrap_or_else(|_| panic!("{version}: timed out")); + } +} - let broadcast = publisher.create_broadcast("bench").unwrap(); - let mut producer = broadcast.create_track("datagrams", None).unwrap(); - broadcast.announce(Default::default()).unwrap(); +async fn ietf_delivers_datagrams_on(version: &str) { + let publisher = produce_origin(1); + let consumer_origin = produce_origin(2); - let mut options = MockConnectOptions::new("moq-transport-19".parse::().unwrap()); - options.server_publish = Some(publisher.consume()); - options.client_subscribe = Some(consumer_origin.clone()); - let _pair = connect_mock(options).await; + let broadcast = publisher.create_broadcast("bench").unwrap(); + let mut producer = broadcast.create_track("datagrams", None).unwrap(); + broadcast.announce(Default::default()).unwrap(); - let consumer = consumer_origin.consume(); - consumer.routed("bench").await.unwrap(); - let remote = consumer.request_broadcast("bench").await.unwrap(); - let mut subscriber = remote.track("datagrams").unwrap().subscribe(None).await.unwrap(); + let mut options = MockConnectOptions::new(version.parse::().unwrap()); + options.server_publish = Some(publisher.consume()); + options.client_subscribe = Some(consumer_origin.clone()); + let _pair = connect_mock(options).await; - producer - .write_frame(Timestamp::from_millis(0).unwrap(), &b"before"[..]) - .unwrap(); - let before = subscriber.recv_group().await.unwrap().unwrap(); - assert_eq!(before.sequence, 0); + let consumer = consumer_origin.consume(); + consumer.routed("bench").await.unwrap(); + let remote = consumer.request_broadcast("bench").await.unwrap(); + let mut subscriber = remote.track("datagrams").unwrap().subscribe(None).await.unwrap(); - producer - .insert_datagram( - 0, - Timestamp::from_millis(7).unwrap(), - bytes::Bytes::from_static(PAYLOAD), - ) - .unwrap(); - producer - .write_frame(Timestamp::from_millis(1).unwrap(), &b"after"[..]) - .unwrap(); - let after = subscriber.recv_group().await.unwrap().unwrap(); - assert_eq!(after.sequence, 1); + // A group first, so the subscription's alias is bound before any datagram lands. + producer + .write_frame(Timestamp::from_millis(0).unwrap(), &b"before"[..]) + .unwrap(); + let mut before = subscriber.recv_group().await.unwrap().unwrap(); + assert_eq!(before.sequence, 0, "{version}"); + // Drafts without a track timescale stamp objects on arrival, datagrams included. + let stamped = before.next_frame().await.unwrap().unwrap().timestamp.value() == 0; - assert!( - subscriber.recv_datagram().now_or_never().is_none(), - "MoQ Transport must not map datagrams" + producer + .insert_datagram( + 5, + Timestamp::from_millis(7).unwrap(), + bytes::Bytes::from_static(PAYLOAD), + ) + .unwrap(); + let datagram = subscriber.recv_datagram().await.unwrap().unwrap(); + assert_eq!(datagram.sequence, 5, "{version}: the relay must not renumber"); + assert_eq!(&datagram.payload[..], PAYLOAD, "{version}"); + if stamped { + let expected = Timestamp::from_millis(7).unwrap(); + assert_eq!( + datagram.timestamp.convert(expected.scale()).unwrap(), + expected, + "{version}" ); - }) - .await - .expect("timed out"); + } + + // The group sequence continues past the datagram. + producer + .write_frame(Timestamp::from_millis(8).unwrap(), &b"after"[..]) + .unwrap(); + let after = subscriber.recv_group().await.unwrap().unwrap(); + assert_eq!(after.sequence, 6, "{version}"); } /// Explicit insert keeps the origin sequence on the lite wire, including a gap. diff --git a/rs/moq-tokio/tests/broadcast.rs b/rs/moq-tokio/tests/broadcast.rs index 23a16c1fde0..2ab11f6844a 100644 --- a/rs/moq-tokio/tests/broadcast.rs +++ b/rs/moq-tokio/tests/broadcast.rs @@ -376,6 +376,143 @@ async fn broadcast_moq_lite_05_fetch_webtransport() { lite05_fetch_roundtrip("https").await; } +/// A cache miss over moq-transport is a standalone FETCH of the one group, served from +/// the publisher's cache, and a group the publisher lacks comes back as the publisher's +/// own refusal. Without `served`, the version has no FETCH and the miss is refused. +async fn transport_fetch_roundtrip(version: &str, served: bool) { + let pub_origin = moq_tokio::origin::spawn(); + let broadcast = pub_origin.create_broadcast("test").expect("failed to create broadcast"); + broadcast + .announce(Default::default()) + .expect("failed to announce broadcast"); + let track = broadcast.create_track("video", None).expect("failed to create track"); + for sequence in 0..3u64 { + let mut group = track.append_group().expect("failed to append group"); + for frame in 0..2 { + group + .write_frame( + moq_net::Timestamp::ZERO, + bytes::Bytes::from(format!("{sequence}-{frame}")), + ) + .expect("failed to write frame"); + } + group.finish().expect("failed to finish group"); + } + + let mut server_config = moq_tokio::listen::Config::default(); + server_config.bind = Some("[::]:0".parse().unwrap()); + server_config.tls.generate = vec!["localhost".into()]; + server_config.version = vec![version.parse().unwrap()]; + let server = server_config.init(Default::default()).expect("failed to init server"); + let mut server = server.listen().await.expect("failed to listen"); + let addr = server.local_addr().expect("failed to get local addr"); + + let sub_origin = moq_tokio::origin::spawn(); + let sub_consumer = sub_origin.consume(); + let mut announcements = sub_consumer.announced(); + + let mut client_config = moq_tokio::connect::Config::default(); + client_config.tls.insecure = Some(true); + client_config.version = vec![version.parse().unwrap()]; + let client = client_config.init(Default::default()).expect("failed to init client"); + let url: url::Url = format!("moqt://localhost:{}", addr.port()).parse().unwrap(); + + let server_handle = tokio::spawn(async move { + let request = server.accept().await.expect("no incoming connection"); + let session = request.with_publisher(&pub_origin).ok().await?; + let _broadcast = broadcast; + let _track = track; + let _ = session.closed().await; + Ok::<_, anyhow::Error>(()) + }); + + let client = client.with_subscriber(sub_origin); + let (_client, connection) = tokio::time::timeout(TIMEOUT, connect_once(client, url)) + .await + .expect("client connect timed out") + .expect("client connect failed"); + + tokio::time::timeout(TIMEOUT, announcements.next()) + .await + .expect("announce timed out") + .expect("origin closed"); + let bc = tokio::time::timeout(TIMEOUT, sub_consumer.request_broadcast("test")) + .await + .expect("request timed out") + .expect("announced broadcast resolves"); + + let fetched = tokio::time::timeout(TIMEOUT, async { bc.track("video").unwrap().fetch_group(1, None).await }) + .await + .expect("fetch timed out"); + if !served { + assert!( + matches!(fetched, Err(moq_net::Error::Unsupported)), + "expected an unsupported FETCH, got {:?}", + fetched.err() + ); + drop(connection); + server_handle + .await + .expect("server task panicked") + .expect("server task failed"); + return; + } + let mut group = fetched.expect("fetch failed"); + assert_eq!(group.sequence, 1); + for frame in 0..2 { + let payload = tokio::time::timeout(TIMEOUT, group.read_frame()) + .await + .expect("read timed out") + .expect("read failed") + .expect("group ended early"); + assert_eq!(payload.payload, bytes::Bytes::from(format!("1-{frame}"))); + } + let end = tokio::time::timeout(TIMEOUT, group.read_frame()) + .await + .expect("read timed out") + .expect("read failed"); + assert!(end.is_none(), "the group ends after its frames"); + + let refused = tokio::time::timeout(TIMEOUT, async { bc.track("video").unwrap().fetch_group(7, None).await }) + .await + .expect("fetch timed out"); + assert!( + matches!(refused, Err(moq_net::Error::NotFound)), + "expected the publisher's refusal, got {:?}", + refused.err() + ); + + drop(connection); + server_handle + .await + .expect("server task panicked") + .expect("server task failed"); +} + +#[tracing_test::traced_test] +#[tokio::test] +async fn fetch_moq_transport_14() { + transport_fetch_roundtrip("moq-transport-14", true).await; +} + +#[tracing_test::traced_test] +#[tokio::test] +async fn fetch_moq_transport_16() { + transport_fetch_roundtrip("moq-transport-16", true).await; +} + +#[tracing_test::traced_test] +#[tokio::test] +async fn fetch_moq_transport_18() { + transport_fetch_roundtrip("moq-transport-18", true).await; +} + +#[tracing_test::traced_test] +#[tokio::test] +async fn fetch_moq_transport_20() { + transport_fetch_roundtrip("moq-transport-20", false).await; +} + /// A fetch must be served while a live subscription is active on the same track. /// The relay subscribes starting at the latest group, so an older group isn't /// cached and the fetch has to issue a wire FETCH concurrently with the diff --git a/swift/README.md b/swift/README.md index 613831a5810..3317296c37a 100644 --- a/swift/README.md +++ b/swift/README.md @@ -72,7 +72,7 @@ Incoming server `Request` values expose the query-free `path` before acceptance. Raw tracks also expose best-effort datagrams: `TrackProducer.appendDatagram(_:timestampUs:)` returns the assigned sequence number, `TrackConsumer.recvDatagram()` receives one datagram, and `TrackConsumer.datagrams` streams them in arrival order. Payloads are capped at 1200 bytes. -Datagrams require a datagram-capable transport and lite-05 or newer moq-lite; IETF moq-transport, +Datagrams require a datagram-capable transport and lite-05 or newer moq-lite, or moq-transport; pre-lite-05, WebSocket, and TCP paths do not deliver them, and there is no stream fallback. JSON tracks carry your own `Codable` types with the framing handled for you. You opt into one of two From 8c01e32aae11e5a166ea905980ffe7f7520d0d09 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 11:23:40 -0700 Subject: [PATCH 111/128] fix(moq-net): a stream reset with an unmapped code no longer ends an IETF session (#4602) Co-authored-by: Claude Opus 5.5 --- quest/m0/README.md | 6 +-- quest/m0/ietf-subgroup-refusal.md | 22 ---------- rs/moq-net/src/ietf/session.rs | 59 +++++++++++++++++++++++---- rs/moq-net/src/ietf/subscriber.rs | 34 +++++++++++++++ rs/moq-net/src/lite/test_transport.rs | 43 ++++++++++++------- 5 files changed, 116 insertions(+), 48 deletions(-) delete mode 100644 quest/m0/ietf-subgroup-refusal.md diff --git a/quest/m0/README.md b/quest/m0/README.md index fae3a99c494..4385874effd 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -18,9 +18,8 @@ no release quest gates this milestone. The Pronto GPU integration lives in moq.pro. Relay hardening: IETF interop leads the ranking, since only those quests -block Seattle. Subgroup refusal came from the moxygen line and IETF stream -types from m1; both moved here in the 2026-09-30 audit because a session -ended by legal input is exactly what Seattle would hit. The DoS hardening +block Seattle. IETF stream types came from m1 in the 2026-09-30 audit +because a session ended by legal input is exactly what Seattle would hit. The DoS hardening from an external review on 2026-09-29, verified against `main`, stays in m0 as security work. Its quests describe fixes, not exploits. @@ -43,7 +42,6 @@ Published API or wire breaks still land on dev; each quest's Plan says so. - [Legal IETF input](/quest/m0/ietf-legal-input.md) - draft-20+ FETCH, allowed parameters, INCLUDE_PROPERTIES and FORWARD=0 decode and are refused per request, not session-fatal - [IETF FIN semantics](/quest/m0/ietf-fin-not-cancel.md) - a request stream FIN stops updates without cancelling, and REQUEST_UPDATE on a subscribe is parsed -- [Subgroup refusal](/quest/m0/ietf-subgroup-refusal.md) - a non-zero moq-transport subgroup costs that one stream, never the session - [IETF stream types](/quest/m0/ietf-uni-stream-types.md) - padding streams are discarded stream-only and an unknown uni type closes the session, per draft-21 - [Request caps](/quest/m0/request-caps.md) - lite message sizes, IETF request IDs, and per-session announces and subscriptions are bounded - [quest check everywhere](/quest/m0/quest-check-everywhere.md) - `quest check` guards `main`, `dev`, and the line branches on push and PR, not only PRs into `main` diff --git a/quest/m0/ietf-subgroup-refusal.md b/quest/m0/ietf-subgroup-refusal.md deleted file mode 100644 index 872ad8504c2..00000000000 --- a/quest/m0/ietf-subgroup-refusal.md +++ /dev/null @@ -1,22 +0,0 @@ -# [S] Subgroup refusal stays on the stream - -## Goal - -A peer that sends a non-zero subgroup on moq-transport loses that one stream, -never the session. Every other track on the session keeps flowing. - -## Plan - -Against moxygen's `moqtest_server`, a track with two subgroups per group ended -the relay's upstream session, and the server reconnected. Our side refuses the -stream today. Whether the session ends because of how we refuse it (the reset -code, STOP_SENDING, or the alias state it leaves behind) or because the peer -reacts badly to a correct refusal is not known yet. Reproduce it first. If the -peer is at fault, say so on its tracker and keep a regression test for our side. - -A test with an IETF peer that sends a subgroup 1 stream next to a healthy track -is the check. - -Moved from the moxygen line to m0 in the 2026-09-30 audit: a non-zero -subgroup ending the upstream session is exactly m0's "legal input never fails -a session", and moxygen will send it at Seattle interop on 2026-10-12. diff --git a/rs/moq-net/src/ietf/session.rs b/rs/moq-net/src/ietf/session.rs index 2230852b538..439c259b4e1 100644 --- a/rs/moq-net/src/ietf/session.rs +++ b/rs/moq-net/src/ietf/session.rs @@ -420,8 +420,8 @@ where }; match &res { - Err(Error::Transport(_)) => { - tracing::info!("session terminated"); + Err(err @ Error::Transport(_)) => { + tracing::info!(%err, "session terminated"); session.close(SessionError::Internal.to_code(), ""); } Err(err) => { @@ -652,6 +652,12 @@ where // the peer wrote to. Failing the loop here would tear down the whole session // over a single stream the peer had already given up on. Only death is // tolerated: bytes that arrive and do not parse stay session-fatal. + // + // A transport error counts as death too. A reset whose code the transport cannot + // place in the stream registry surfaces as one: over raw QUIC a moq-transport + // peer resets with its own codes (moxygen's CANCELLED is 0x1), which the + // WebTransport code mapping rejects. If the connection itself died, the next + // accept reports it. let kind: u64 = match tasks .drive(|waiter| { let mut cx = std::task::Context::from_waker(waiter.waker()); @@ -660,7 +666,13 @@ where .await { Ok(kind) => kind, - Err(err @ (Error::Cancel | Error::Stream(_) | Error::Remote(_) | Error::Decode(DecodeError::Short))) => { + Err( + err @ (Error::Cancel + | Error::Stream(_) + | Error::Remote(_) + | Error::Transport(_) + | Error::Decode(DecodeError::Short)), + ) => { tracing::debug!(%err, "dropping uni stream that died before its type"); continue; } @@ -830,7 +842,13 @@ where // header that does not parse included, still fails the session. let (id, data) = match header { Ok(header) => header, - Err(err @ (Error::Cancel | Error::Stream(_) | Error::Remote(_) | Error::Decode(DecodeError::Short))) => { + Err( + err @ (Error::Cancel + | Error::Stream(_) + | Error::Remote(_) + | Error::Transport(_) + | Error::Decode(DecodeError::Short)), + ) => { tracing::debug!(%err, "dropping bidi stream that died before its header"); continue; } @@ -1269,10 +1287,23 @@ mod tests { a_dead_incoming_stream_is_not_fatal(crate::lite::test_transport::DeadStreamSession::bis(1)).await; } + /// moxygen resets a subgroup stream it opened but never wrote with its own CANCELLED + /// (0x1). Over raw QUIC our transport reads that code through the WebTransport space + /// and cannot map it, which used to end the session. + #[tokio::test] + async fn a_uni_stream_reset_with_an_unmapped_code_does_not_end_the_session() { + a_dead_incoming_stream_is_not_fatal(crate::lite::test_transport::DeadStreamSession::unis(1).unmapped()).await; + } + + #[tokio::test] + async fn a_bidi_stream_reset_with_an_unmapped_code_does_not_end_the_session() { + a_dead_incoming_stream_is_not_fatal(crate::lite::test_transport::DeadStreamSession::bis(1).unmapped()).await; + } + /// The bytes a publisher writes at the head of a group's unidirectional stream. Built /// with the crate's own encoder so the framing can't drift from the decoder the /// dispatch loop runs. - async fn subgroup_header(version: Version, track_alias: u64) -> Vec { + async fn subgroup_header(version: Version, track_alias: u64, sub_group_id: u64) -> Vec { let log = crate::lite::test_transport::Log::default(); let mut writer = crate::coding::Writer::new(crate::lite::test_transport::SinkSend::new(log.clone()), version); @@ -1280,9 +1311,12 @@ mod tests { .encode(&ietf::GroupHeader { track_alias, group_id: 0, - sub_group_id: 0, + sub_group_id, publisher_priority: 128, - flags: ietf::GroupFlags::default(), + flags: ietf::GroupFlags { + has_subgroup: sub_group_id != 0, + ..Default::default() + }, }) .await .unwrap(); @@ -1341,7 +1375,7 @@ mod tests { /// A late group must reach the dispatch loop and stop with CANCELLED. #[tokio::test(start_paused = true)] async fn a_group_for_a_retired_alias_is_stopped_with_cancelled() { - let log = dispatch_uni(subgroup_header(Version::Draft19, 7).await, Some(7)).await; + let log = dispatch_uni(subgroup_header(Version::Draft19, 7, 0).await, Some(7)).await; assert_eq!( log.stops(), @@ -1351,6 +1385,15 @@ mod tests { assert_eq!(log.closes(), vec![], "one dropped group may not close the session"); } + /// A non-zero subgroup is refused on its own stream, never by closing the session. + #[tokio::test(start_paused = true)] + async fn a_non_zero_subgroup_is_stopped_without_closing_the_session() { + let log = dispatch_uni(subgroup_header(Version::Draft19, 7, 1).await, None).await; + + assert_eq!(log.stops(), vec![crate::ietf::error::INTERNAL_ERROR]); + assert_eq!(log.closes(), vec![], "one refused subgroup may not close the session"); + } + #[tokio::test(start_paused = true)] async fn unknown_uni_type_does_not_claim_the_session_closed() { let log = dispatch_uni(vec![0], None).await; diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index 79f6cd0f6b9..0c28ed961bf 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -6609,6 +6609,40 @@ mod stitch_tests { settled.await; } + /// A subgroup 1 stream costs only itself: the track's subgroup 0 stream still arrives. + #[tokio::test] + async fn a_non_zero_subgroup_leaves_the_track_flowing() { + let mut refused = Vec::new(); + ietf::GroupHeader { + track_alias: ALIAS, + group_id: SEQUENCE, + sub_group_id: 1, + publisher_priority: 0, + flags: ietf::GroupFlags { + has_subgroup: true, + first_object: true, + ..Default::default() + }, + } + .encode(&mut refused, VERSION) + .unwrap(); + + let h = Harness::new(Fill::Done, vec![refused, tail_stream(SEQUENCE, 0, &[b"ok"])]); + let mut consumer = h.track.subscribe(None); + + let mut stream = h.stream().await; + let result = h.subscriber.clone().recv_group(&mut stream).await; + assert!(matches!(result, Err(Error::Unsupported)), "{result:?}"); + + let mut stream = h.stream().await; + h.subscriber.clone().recv_group(&mut stream).await.unwrap(); + let (sequence, frames) = read_group(&mut consumer).await; + assert_eq!(sequence, SEQUENCE); + assert_eq!(frames.len(), 1); + assert_eq!(frames[0].1, b"ok"); + assert!(h.session.log.closes().is_empty()); + } + #[tokio::test] async fn object_extension_limit() { for size in [65536usize, 65537] { diff --git a/rs/moq-net/src/lite/test_transport.rs b/rs/moq-net/src/lite/test_transport.rs index 497cb3b3267..be9aef7f6b2 100644 --- a/rs/moq-net/src/lite/test_transport.rs +++ b/rs/moq-net/src/lite/test_transport.rs @@ -179,13 +179,18 @@ impl poll::RecvStream for PendingRecv { } } -/// A reset with stream code 0, decoded as `Error::Stream(StreamError::Internal)`. -#[derive(Debug, Clone, Default)] -pub struct ResetError; +/// A RESET_STREAM as the transport reports it. `Some(code)` decodes as +/// `Error::Stream`; `None` is a code the transport could not place in the stream +/// registry, which decodes as `Error::Transport`. +#[derive(Debug, Clone, Copy)] +pub struct ResetError(pub Option); impl std::fmt::Display for ResetError { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - write!(f, "stream reset by peer (code 0)") + match self.0 { + Some(code) => write!(f, "stream reset by peer (code {code})"), + None => write!(f, "stream reset by peer (unmapped code)"), + } } } @@ -197,27 +202,27 @@ impl web_transport_trait::Error for ResetError { } fn stream_error(&self) -> Option { - Some(0) + self.0 } } /// A stream that died before delivering a single byte: every read reports a -/// code-0 RESET_STREAM ([`ResetError`]), the wire shape of a reset arriving -/// ahead of any payload. QUIC does not order a reset behind the data, so this -/// reaches an accept loop in normal operation, not just from a misbehaving peer. -pub struct DeadRecv; +/// RESET_STREAM ([`ResetError`]), the wire shape of a reset arriving ahead of any +/// payload. QUIC does not order a reset behind the data, so this reaches an accept +/// loop in normal operation, not just from a misbehaving peer. +pub struct DeadRecv(ResetError); impl poll::RecvStream for DeadRecv { type Error = ResetError; fn poll_read(&mut self, _cx: &mut Context<'_>, _dst: &mut [u8]) -> Poll, Self::Error>> { - Poll::Ready(Err(ResetError)) + Poll::Ready(Err(self.0)) } fn stop(&mut self, _code: u32) {} fn poll_closed(&mut self, _cx: &mut Context<'_>) -> Poll> { - Poll::Ready(Err(ResetError)) + Poll::Ready(Err(self.0)) } } @@ -230,6 +235,7 @@ pub struct DeadStreamSession { pub log: Log, unis: Arc>, bis: Arc>, + reset: ResetError, } impl DeadStreamSession { @@ -239,6 +245,7 @@ impl DeadStreamSession { log: Log::default(), unis: Arc::new(Mutex::new(count)), bis: Arc::new(Mutex::new(0)), + reset: ResetError(Some(0)), } } @@ -248,9 +255,17 @@ impl DeadStreamSession { log: Log::default(), unis: Arc::new(Mutex::new(0)), bis: Arc::new(Mutex::new(count)), + reset: ResetError(Some(0)), } } + /// Reset with a code the transport cannot map, the way a raw QUIC moq-transport + /// peer's CANCELLED reads through the WebTransport code space. + pub fn unmapped(mut self) -> Self { + self.reset = ResetError(None); + self + } + fn take(counter: &Mutex) -> bool { let mut remaining = counter.lock().unwrap(); match *remaining { @@ -270,21 +285,21 @@ impl poll::Session for DeadStreamSession { fn poll_accept_uni(&mut self, _cx: &mut Context<'_>) -> Poll> { match Self::take(&self.unis) { - true => Poll::Ready(Ok(DeadRecv)), + true => Poll::Ready(Ok(DeadRecv(self.reset))), false => Poll::Pending, } } fn poll_accept_bi(&mut self, _cx: &mut Context<'_>) -> Poll, Self::Error>> { match Self::take(&self.bis) { - true => Poll::Ready(Ok((SinkSend::new(self.log.clone()), DeadRecv))), + true => Poll::Ready(Ok((SinkSend::new(self.log.clone()), DeadRecv(self.reset)))), false => Poll::Pending, } } fn poll_open_bi(&mut self, _cx: &mut Context<'_>) -> Poll, Self::Error>> { self.log.bi_opens.fetch_add(1, Ordering::Relaxed); - Poll::Ready(Ok((SinkSend::new(self.log.clone()), DeadRecv))) + Poll::Ready(Ok((SinkSend::new(self.log.clone()), DeadRecv(self.reset)))) } fn poll_open_uni(&mut self, _cx: &mut Context<'_>) -> Poll> { From 6469f201c51a0e6b78c205a42e698f16d1475e79 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 11:27:40 -0700 Subject: [PATCH 112/128] fix(relay)!: remove cluster gossip discovery (#4601) Co-authored-by: Claude Opus 5.5 --- doc/bin/cli.md | 7 +- doc/bin/relay/cluster.md | 57 +- doc/bin/relay/config.md | 1 - doc/bin/relay/http.md | 13 +- doc/bin/relay/index.md | 2 +- doc/concept/moq-lite.md | 4 +- doc/setup/upgrade.md | 12 +- quest/m0/README.md | 1 - quest/m0/remove-gossip.md | 43 -- quest/m1/cluster-routing/topology.md | 7 +- rs/moq-cli/src/args.rs | 8 +- rs/moq-relay/README.md | 5 +- rs/moq-relay/src/cluster.rs | 890 ++++---------------------- rs/moq-relay/src/connection.rs | 6 +- rs/moq-relay/src/internal.rs | 13 +- rs/moq-relay/src/nodes.rs | 358 ++--------- rs/moq-relay/src/uring.rs | 3 - rs/moq-relay/src/web.rs | 2 +- rs/moq-relay/tests/cluster_unknown.rs | 2 +- rs/moq-relay/tests/hidden_cluster.rs | 9 +- 20 files changed, 231 insertions(+), 1212 deletions(-) delete mode 100644 quest/m0/remove-gossip.md diff --git a/doc/bin/cli.md b/doc/bin/cli.md index d236b883323..2e3f831dd85 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -260,8 +260,8 @@ and publishes on the cluster origin. A `moq --cluster-lan` process and a `--cluster-lan` advertises this process on the LAN over mDNS and meshes with every other participating MoQ process. It reuses `--listen`, filling in an ephemeral port and a generated certificate when those are unset. A LAN peer -authenticates with its mDNS credential; `cluster.token` is for static and -gossip peers only. +authenticates with its mDNS credential; `cluster.token` is for +`--cluster-connect` and `--cluster-connect-api` peers only. ```bash moq --cluster-lan import capture @@ -279,8 +279,7 @@ under. Peers using a different name never discover this one. It defaults to configuration. An application built on the library picks its own name. The WAN flags (`--cluster-connect`, `--cluster-connect-api`, `--cluster-node`, -`--cluster-mesh`, `--cluster-token`, `--cluster-id`, `--cluster-tier`) match -the relay. `--cluster-connect` and `--cluster-connect-api` are a MoQ side on +`--cluster-token`, `--cluster-id`, `--cluster-tier`) match the relay. `--cluster-connect` and `--cluster-connect-api` are a MoQ side on their own, so `moq --cluster-connect https://relay.example import ts` needs no `--connect`. See [Clustering](/bin/relay/cluster). diff --git a/doc/bin/relay/cluster.md b/doc/bin/relay/cluster.md index 88bc2f3e288..31dbdf069b3 100644 --- a/doc/bin/relay/cluster.md +++ b/doc/bin/relay/cluster.md @@ -43,7 +43,9 @@ connection stays in place, and the 0 keeps it ranked as anonymous. ## Topology -List the peers each relay dials. That's the whole topology. +List the peers each relay dials. That's the whole topology: a relay dials only +peers from `connect`, [`connect_api`](#dynamic-peer-lists), or +[LAN discovery](#lan-discovery), never a URL learned from an announcement. ```toml # us-west.toml @@ -54,6 +56,10 @@ connect = ["https://us-east.example.com/"] A chain (`eu-west <- us-east <- us-west`) dedupes fetches through the middle; a full mesh trades that for one fewer hop. Mix shapes as your traffic demands. +For a full mesh, list every other relay, or serve the list from `connect_api`. +A session carries both directions, so one dial per pair is enough; listing a +pair on both sides opens a redundant second session. + ## Link costs Add `?cost=N` to a peer URL to route by price instead of hop count. An unpriced @@ -112,35 +118,12 @@ the warm side while the cold price still says who sits closest to the publisher. moq-transport has nowhere to carry the cold price, so a route learned from it ranks with an unknown (worst-case) one. -## Discovery - -Instead of listing every peer, tell each relay its own URL and turn on gossip. -Connected relays learn about each other and dial back; between any two -gossiping nodes, only the one with the smaller URL dials. - -```toml -[cluster] -connect = ["https://us-east.example.com/"] -node = "https://us-west.example.com/" -mesh = true -``` - -A relay with `node` and `mesh` but no `connect` is a passive rendezvous. - -Gossip trusts every node advertised under `.internal/origins/` and dials it -with `cluster.token`, unless the advertised URL carries its own `?jwt=`. Keep -client grants off `.internal/`: a client that can publish there can add a peer -that receives the token. - -Give `node` an authenticated TLS scheme (`https://`, `wss://`, `moqt://`, or -`moql://`). Peers dial that URL with the token, so `ws://` and `tcp://` send it -in cleartext, and `http://` pins a fingerprint fetched over plain HTTP and -may fall back to `ws://`. +## LAN discovery -On a LAN there may be no seed peer to gossip through. `[cluster.lan]` advertises -this relay over mDNS and dials the peers that advertise back, so a rack or a -home lab meshes with no seed list. A `moq --cluster-lan` process on the same -network joins the same mesh: +On a LAN there may be no one to list. `[cluster.lan]` advertises this relay +over mDNS and dials the peers that advertise back, so a rack or a home lab +meshes with no seed list. A `moq --cluster-lan` process on the same network +joins the same mesh: ```toml [cluster] @@ -155,10 +138,10 @@ enabled = true ``` A LAN peer authenticates with its mDNS credential on `/.cluster/` -and is never handed `cluster.token`; that token is for static and gossip peers -only. The advertisement carries the listener fingerprint when the certificate -was generated or supplied in-memory, the `node` URL when one is configured, -and at least one of them. `secret` is optional. Without it, anyone who can +and is never handed `cluster.token`; that token is for `connect` and +`connect_api` peers only. The advertisement carries the listener fingerprint +when the certificate was generated or supplied in-memory, the `node` URL when +one is configured, and at least one of them. `secret` is optional. Without it, anyone who can reach the listener joins, so leave it unset only on networks you trust. With it, only peers that prove they hold the same key are discovered or accepted. mDNS is still an open channel: the secret authenticates the record, it does @@ -199,8 +182,8 @@ clients decode it. Peers dial with **mTLS** (recommended: `listen.tls.root` on the listener, `connect.tls.cert`/`key` on the dialer) or a **JWT** (inline `?jwt=` on a peer -URL, `token` on a peer object, or a shared `cluster.token` file for static and -gossip peers). The +URL, `token` on a peer object, or a shared `cluster.token` file for every +listed peer). The accepting relay admits a peer through the same lease as any client: its certificate is reported to the auth server, which grants it, so a mesh needs `moq auth serve --mtls-publish '**' --mtls-subscribe '**'` (or a server of @@ -219,5 +202,5 @@ accepted peer counts only when its grant sets `peer: true`; otherwise it looks like a client ingesting here. An embedder reads this as `Route::source()` and filters with `origin::Consumer::local()`. -The `/nodes` [internal endpoint](/bin/relay/http#get-nodes) shows the cluster -as this relay sees it. +The `/nodes` [internal endpoint](/bin/relay/http#get-nodes) lists the peers +this relay dialed and holds a session with. diff --git a/doc/bin/relay/config.md b/doc/bin/relay/config.md index 6cec124121a..209b8032e3c 100644 --- a/doc/bin/relay/config.md +++ b/doc/bin/relay/config.md @@ -132,7 +132,6 @@ See [Authentication](/bin/relay/auth). [cluster] connect = ["https://us-east.example.com/?cost=10"] # Peers to dial. ?cost prices the link, or use {url, cost, egress, token} objects. node = "https://us-west.example.com/" # This relay's own URL. -mesh = true # Gossip: peers discover and dial `node`. connect_api = "https://api.example.com/peers" # Or fetch the peer list (JSON array of URLs and/or objects) live. token = "cluster.jwt" # JWT for dials without an inline ?jwt=. id = 12345 # Stable Hop ID across restarts. diff --git a/doc/bin/relay/http.md b/doc/bin/relay/http.md index 8046e48a263..04ef66b7deb 100644 --- a/doc/bin/relay/http.md +++ b/doc/bin/relay/http.md @@ -92,9 +92,10 @@ curl -X POST 'http://127.0.0.1:9101/sessions/revalidate?id=00ff' ### GET /nodes -This relay's view of the cluster: each visible node's URL, Hop ID, the route -its advertisement took, and the connections to it (with the same `conn` id the -logs use). A route is priced twice: `cost` as the cluster stands, which reads 0 -through a relay already carrying the broadcast, and `cold_cost` with those -discounts removed, which is what tells two warm relays apart. It is best-effort -correlation, not authenticated identity. +The peers this relay dialed and holds a session with: each node's URL, without +its query, and the connections to it, with the same `conn` id the logs use. +Peers that dialed this relay are not listed, since they declare no URL. + +```json +{ "nodes": [{ "node": "https://us-east.example.com/", "connections": [{ "id": 3 }] }] } +``` diff --git a/doc/bin/relay/index.md b/doc/bin/relay/index.md index 623168eb8dc..a2af14c1061 100644 --- a/doc/bin/relay/index.md +++ b/doc/bin/relay/index.md @@ -13,7 +13,7 @@ relay serves video, audio, and data alike. - **QUIC, WebTransport, and WebSocket** listeners, so browsers and native clients connect to one process. - **Path-scoped authentication** with JWTs, mTLS for peers, and anonymous patterns, decided by an auth server or a static grant. See [Authentication](/bin/relay/auth). -- **Clustering** across hosts and regions with hop-list routing, per-link costs, gossip discovery, and dynamic peer lists. See [Clustering](/bin/relay/cluster). +- **Clustering** across hosts and regions with hop-list routing, per-link costs, LAN discovery, and dynamic peer lists. See [Clustering](/bin/relay/cluster). - **A group cache** with byte and age budgets, so late joiners and the HLS gateway can fetch recent history. - **HTTP endpoints** to list broadcasts, fetch groups, probe health, and scrape Prometheus metrics. See [HTTP](/bin/relay/http). - **Live stats** published as MoQ tracks per node and per tenant, split by billing tier. diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index e627c18f211..9cf9cffd8e9 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -104,8 +104,8 @@ through the new one. A path segment starting with `.` hides a route from discovery, the way a dotfile hides from `ls`. A platform publishes its own broadcasts there (relay -stats under `.stats/`, cluster gossip under `.internal/`) without them turning -up in an app that lists everything and plays what it finds. Only segments +stats under `.stats/`) without them turning up in an app that lists +everything and plays what it finds. Only segments below the requested prefix count: listing the root skips `.stats/node`, but listing `.stats` shows `node`. A `.` elsewhere in a segment (`catalog.pro`) is part of the name. diff --git a/doc/setup/upgrade.md b/doc/setup/upgrade.md index 12dfbcdb506..ecf39af0bc3 100644 --- a/doc/setup/upgrade.md +++ b/doc/setup/upgrade.md @@ -49,6 +49,7 @@ variables follow the flag (`MOQ_SERVER_BIND` is `MOQ_LISTEN`). | TOML `listen`, `connect`, `failover_delay`, `reconnect`, `disable_verify` | `bind`, `url`, `race`, `once` (inverted), `insecure` | | `--cluster-linger` | removed; a broadcast closes when its last publisher is lost | | `--cluster-connect host:port` | a full URL, `https://host/?jwt=TOKEN` | +| `--cluster-mesh`, TOML `mesh` | removed; list every peer with `--cluster-connect` or `--cluster-connect-api` | | `moq --origin`, `--name`, `--latency-max` | `--hop`, `--broadcast`, `--max-age` | | `moq publish`, `moq subscribe` | `moq import`, `moq export` | | `moq token`, the `moq-token` binary | `moq auth` | @@ -98,9 +99,14 @@ Other changes to a deployment: the relay's client CA verifies, so keep that CA to cluster peers. - **`moq --listen` needs auth.** A CLI listener refuses to start without `--auth-url` or `--auth-public` instead of accepting everyone. -- **Other 0.14 auth differences kept.** A 0.14 peer that dials with a - cluster JWT no longer sees `.internal/origins` gossip; peers identify by - certificate or LAN path. An auth server's `root` alias may have any depth. +- **Gossip discovery is removed.** A relay dials only the peers it lists or + finds on the LAN, never a URL learned from an announcement, and no longer + announces `.internal/origins`. The `/nodes` endpoint lists only peers this + relay dialed. Until every relay that ran `--cluster-mesh` is upgraded, keep + client grants off `.internal/`: an older relay still dials any URL announced + there with `cluster.token`, and an upgraded peer still forwards it. +- **Other 0.14 auth differences kept.** Peers identify by certificate or LAN + path. An auth server's `root` alias may have any depth. A path in `--cluster-connect` is not refused, although it shifts the mesh frame. `moq auth serve --key` takes a file, not an https or JWKS URL. `moq auth sign --root` is the token root and JS `verify --root` the dialed diff --git a/quest/m0/README.md b/quest/m0/README.md index 4385874effd..a384f0eefad 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -47,7 +47,6 @@ Published API or wire breaks still land on dev; each quest's Plan says so. - [quest check everywhere](/quest/m0/quest-check-everywhere.md) - `quest check` guards `main`, `dev`, and the line branches on push and PR, not only PRs into `main` - [noq reassembly cap](/quest/m0/noq-reassembly-cap.md) - noq carries quinn's stream reassembly cap and the connection receive window is finite by default - [qmux reset race](/quest/m0/qmux-reset-race.md) - qmux handles RESET_STREAM under one lock instead of panicking -- [Remove gossip](/quest/m0/remove-gossip.md) - a relay dials only configured peers; `cluster.mesh` is refused at startup - [Shared fronts](/quest/m0/shared-fronts.md) - viewer sessions share a front, so fronts scale with peers, not viewers - [Frame alloc budget](/quest/m0/frame-alloc-budget.md) - frame buffers pre-allocate within a per-session budget and otherwise grow with bytes received - [Handshake deadline](/quest/m0/handshake-deadline.md) - an unfinished handshake or slow HTTP header times out diff --git a/quest/m0/remove-gossip.md b/quest/m0/remove-gossip.md deleted file mode 100644 index 80b0635a49f..00000000000 --- a/quest/m0/remove-gossip.md +++ /dev/null @@ -1,43 +0,0 @@ -# [S] Remove cluster gossip discovery - -## Goal - -A relay dials only peers an operator configured: `cluster.connect`, the -connect API, or LAN mDNS. Gossip discovery (`cluster.mesh`), which advertises -under `.internal/origins/` and dials whatever URL appears there with -`cluster.token`, is removed. It is the only path that dials a URL learned -from an announcement. The design favors a configured full mesh, and moq.pro drives peers -through `--cluster-connect-api` and never enables gossip. - -## Plan - -- Delete gossip advertising and discovery (`rs/moq-relay/src/cluster.rs`, - `nodes.rs` `MESH_PREFIX`) and whatever becomes dead behind them. Keep - `cluster.node` only if something else still reads it. -- `nodes.rs` also backs the internal `/nodes` endpoint (`internal.rs` - `serve_nodes`), which merges gossiped advertisements with direct sessions. - It keeps direct sessions only; document the changed response. -- Retarget `rs/moq-relay/tests/hidden_cluster.rs` to another `.`-prefixed - hidden broadcast, and fix the `.internal/origins` comment in - `connection.rs`. -- Lands on `main` as a security fix, not `dev`. `--cluster-mesh`, - `MOQ_CLUSTER_MESH` and `mesh = true` fail at startup with a message - pointing at `cluster.connect`, so nobody silently loses their mesh. - Decided 2026-09-29. moq-cli reuses moq-relay's cluster config, so the same - refusal covers `moq`'s `--cluster-mesh` (`doc/bin/cli.md`). -- `rs/moq-net/tests/mesh_withdraw.rs` stays: it already wires origins to - each other directly (`MockPair`), which is what a configured full mesh - does, and its withdraw semantics still apply. Rewrite it only if gossip - removal changes what it exercises. Decided in the 2026-09-30 audit. -- Docs: rewrite the Discovery section of `doc/bin/relay/cluster.md`, drop the - `.internal/` warning, and add an upgrade note in `doc/setup/upgrade.md`. - Fix the mesh examples in `doc/bin/cli.md`, `doc/bin/relay/config.md`, and - `rs/moq-relay/README.md`, then search the repo for `cluster-mesh` and - `mesh = true` in any other examples and demo recipes. - -Public API: removes a relay config field and flag. Wire: relays stop -announcing `.internal/origins`. - -## Related - -- [Cluster topology](/quest/m1/cluster-routing/topology.md) - takes its topology from configured links only, so it waits on this diff --git a/quest/m1/cluster-routing/topology.md b/quest/m1/cluster-routing/topology.md index 35adf5f6a40..d10cc59f9c2 100644 --- a/quest/m1/cluster-routing/topology.md +++ b/quest/m1/cluster-routing/topology.md @@ -12,8 +12,7 @@ relay K exists or how to reach it. Decided: the topology is configured. `--cluster-connect` or the connect API gives the relay graph and link costs, and LAN mDNS dials peers that then count -as configured links. Gossip discovery is gone first, by -[Remove gossip](/quest/m0/remove-gossip.md). +as configured links. Gossip discovery is already gone. Candidate mechanics, from the simulator (see the questline README's findings): @@ -51,10 +50,6 @@ time, including restart, a link flapping, and a digest racing a link that just came up. Expose the computed graph where operators already look (`/nodes` in `rs/moq-relay/src/internal.rs`). -## Required - -- [Remove gossip](/quest/m0/remove-gossip.md) - configured links are the only topology source - ## Related - [Cluster idle timeout](/quest/m1/cluster-idle-timeout.md) - liveness only reports what the session layer detects diff --git a/rs/moq-cli/src/args.rs b/rs/moq-cli/src/args.rs index 733a4eaff1b..01678e32b9e 100644 --- a/rs/moq-cli/src/args.rs +++ b/rs/moq-cli/src/args.rs @@ -1602,9 +1602,11 @@ mod tests { assert!(err.contains(reported), "{err}"); } - let cli = Invocation::try_parse_from(["moq", "--cluster-mesh", "auth", "generate"]).unwrap(); - let err = cli.reject("auth").unwrap_err().to_string(); - assert!(err.contains("--cluster-mesh"), "{err}"); + // Gossip discovery is removed, so its flag is refused for every verb. + let Err(err) = Invocation::try_parse_from(["moq", "--cluster-mesh", "auth", "generate"]) else { + panic!("--cluster-mesh must be refused"); + }; + assert!(err.to_string().contains("--cluster-mesh"), "{err}"); #[cfg(unix)] { diff --git a/rs/moq-relay/README.md b/rs/moq-relay/README.md index f1cac529ad2..88edcfac41d 100644 --- a/rs/moq-relay/README.md +++ b/rs/moq-relay/README.md @@ -61,9 +61,10 @@ HTTPS is currently not supported. Relays can be joined together to proxy announcements and subscriptions. A viewer talks to whichever relay is closest; if their broadcast lives elsewhere in the cluster, the local relay fetches it from a neighbor and caches it. Hop tracking on every broadcast keeps loops out and picks the shortest path when there's more than one. - `--cluster-connect ` lists the peers this relay dials. Repeatable; defines the topology by hand. A simple chain like `eu-west <- us-east <- us-west` lets `us-east` cache and dedup the transatlantic fetches that fan out to many `us-west` viewers. -- `--cluster-mesh ` is optional. When set, this relay advertises its own URL to connected peers and dials any peers it learns about, so larger clusters don't need each node hand-configured. You still need at least one connection (in or out) so the advertisement has a path to flow. A relay with `--cluster-mesh` set and no `--cluster-connect` is a passive rendezvous. +- `--cluster-connect-api ` fetches that list from an endpoint or file instead, reloading it without a restart. +- `--cluster-lan` finds peers on the local network over mDNS. -`--cluster-root` and `--cluster-node` from earlier versions were removed. The relay errors at startup if either is set and points at the replacements. +A relay only dials peers listed this way or found on the LAN. `--cluster-mesh` gossip discovery was removed; the relay errors at startup if it is set. See [doc/bin/relay/cluster.md](https://github.com/moq-dev/moq/blob/main/doc/bin/relay/cluster.md) for the full walkthrough, including topology trade-offs and authentication. diff --git a/rs/moq-relay/src/cluster.rs b/rs/moq-relay/src/cluster.rs index 545b76b3bf6..bdfa5d91499 100644 --- a/rs/moq-relay/src/cluster.rs +++ b/rs/moq-relay/src/cluster.rs @@ -5,32 +5,23 @@ use std::{ Arc, Mutex, atomic::{AtomicU64, Ordering}, }, - time::{Duration, Instant}, + time::Duration, }; use anyhow::Context; use moq_net::origin; -use moq_net::{Hop, Path, stats::Tier}; +use moq_net::{Hop, stats::Tier}; use reqwest_middleware::ClientWithMiddleware; use tokio::task::AbortHandle; use tracing::Instrument as _; use url::Url; -use crate::{auth, nodes::MESH_PREFIX}; +use crate::auth; /// The request path prefix a LAN mesh dial presents, marking it as a peer rather /// than an ordinary publisher or viewer on the same listener. pub(crate) const CLUSTER_PATH: &str = "/.cluster"; -/// How often the discovery loop scans for stale entries. -const SWEEP_INTERVAL: Duration = Duration::from_secs(30); - -/// How long a peer must stay unannounced before we abort the dial. Must clear the -/// "prefer shorter hop" re-announce flap (which arrives as -/// unannounce-then-announce within sub-milliseconds) plus reasonable churn from -/// a peer restart. -const STALE_AFTER: Duration = Duration::from_secs(60); - /// How often the relay re-checks an http(s) `--cluster-connect-api` endpoint. The /// HTTP cache middleware suppresses the actual network round-trip while the cached /// list is still fresh (per the response's `Cache-Control`), so this is the floor @@ -38,16 +29,6 @@ const STALE_AFTER: Duration = Duration::from_secs(60); /// ticks turn into real conditional GETs. const CONNECT_API_POLL_INTERVAL: Duration = Duration::from_secs(30); -/// Mesh tiebreaker for gossip-discovered peers. In a full mesh both peers -/// discover each other and would each open a dial, leaving two redundant -/// sessions. The session is bidirectional (we publish *and* consume on it), so -/// one suffices. Break the symmetry on URL order: only dial peers that sort -/// after us, making the lexicographically-smaller node the client and the -/// larger the server. The skipped side still gets the connection inbound. -fn should_dial(self_url: &str, peer: &str) -> bool { - peer > self_url -} - /// One cluster peer to dial, as listed in [`Config::connect`] or returned /// by a `connect_api` endpoint. /// @@ -233,7 +214,7 @@ struct DialTarget { key: String, url: Url, /// Extra candidates after [`Self::url`], in dial order. Empty for a - /// static, gossip, or API peer, which has one address. + /// static or API peer, which has one address. urls: Vec, cost: Option, /// Advertised certificate fingerprint to pin. LAN only. @@ -245,6 +226,7 @@ struct DialTarget { impl DialTarget { /// Parse a bare peer URL, keeping its inline `?cost=` / `?jwt=`. + #[cfg(test)] fn parse(peer: &str) -> anyhow::Result { Self::from_peer(&Peer::new(peer)) } @@ -332,52 +314,6 @@ impl DialTarget { } } -/// Every currently-live gossip path for a canonical peer, in announcement order. -/// Query changes create a new path before the old path necessarily unannounces, -/// so the latest live path owns the dial configuration. -#[derive(Default)] -struct GossipTargets { - by_key: HashMap>, -} - -enum GossipUpdate { - /// The current advertisement changed to this target. - Current(DialTarget), - /// A non-current or unknown advertisement disappeared. - Unchanged, - /// The peer has no live advertisements left. - Gone, -} - -impl GossipTargets { - fn announce(&mut self, advertisement: String, target: DialTarget) -> DialTarget { - let targets = self.by_key.entry(target.key.clone()).or_default(); - targets.retain(|(existing, _)| existing != &advertisement); - targets.push((advertisement, target.clone())); - target - } - - fn unannounce(&mut self, advertisement: &str, key: &str) -> GossipUpdate { - let Some(targets) = self.by_key.get_mut(key) else { - return GossipUpdate::Unchanged; - }; - let was_current = targets.last().is_some_and(|(current, _)| current == advertisement); - let previous_len = targets.len(); - targets.retain(|(existing, _)| existing != advertisement); - if targets.len() == previous_len { - return GossipUpdate::Unchanged; - } - if targets.is_empty() { - self.by_key.remove(key); - return GossipUpdate::Gone; - } - if was_current { - return GossipUpdate::Current(targets.last().expect("live target exists").1.clone()); - } - GossipUpdate::Unchanged - } -} - /// Parse a complete dynamic peer list before mutating the live dial set. A bad /// entry or conflicting duplicate rejects the whole update, preserving the /// last-known-good topology. @@ -399,7 +335,7 @@ fn parse_peer_list(list: Vec, node: Option<&str>) -> anyhow::Result, - gossip: Option, api: Option, #[cfg(feature = "cluster-lan")] mdns: Option, @@ -434,7 +365,6 @@ impl DialSources { fn get(&self, source: DialSource) -> Option<&DialTarget> { match source { DialSource::Static => self.seeded.as_ref(), - DialSource::Gossip => self.gossip.as_ref(), DialSource::Api => self.api.as_ref(), #[cfg(feature = "cluster-lan")] DialSource::Mdns => self.mdns.as_ref(), @@ -444,7 +374,6 @@ impl DialSources { fn set(&mut self, source: DialSource, target: DialTarget) { match source { DialSource::Static => self.seeded = Some(target), - DialSource::Gossip => self.gossip = Some(target), DialSource::Api => self.api = Some(target), #[cfg(feature = "cluster-lan")] DialSource::Mdns => self.mdns = Some(target), @@ -454,7 +383,6 @@ impl DialSources { fn clear(&mut self, source: DialSource) { match source { DialSource::Static => self.seeded = None, - DialSource::Gossip => self.gossip = None, DialSource::Api => self.api = None, #[cfg(feature = "cluster-lan")] DialSource::Mdns => self.mdns = None, @@ -462,33 +390,29 @@ impl DialSources { } /// The source to fall back to when the active one is released, most durable - /// first: operator intent, then the API list, then the two discovery - /// mechanisms whose targets come and go on their own. + /// first: operator intent, then the API list, then LAN discovery, whose + /// targets come and go on their own. fn fallback(&self) -> Option<(DialSource, &DialTarget)> { let fallback = self .seeded .as_ref() .map(|target| (DialSource::Static, target)) - .or_else(|| self.api.as_ref().map(|target| (DialSource::Api, target))) - .or_else(|| self.gossip.as_ref().map(|target| (DialSource::Gossip, target))); + .or_else(|| self.api.as_ref().map(|target| (DialSource::Api, target))); #[cfg(feature = "cluster-lan")] let fallback = fallback.or_else(|| self.mdns.as_ref().map(|target| (DialSource::Mdns, target))); fallback } } -/// One entry in [`DialMap`]. `unannounced_at` carries the gossip stale timer; the -/// sweep uses it to decide when the gossip source has truly gone vs. is just -/// flapping between paths. It's only meaningful while `sources.gossip` is set. +/// One entry in [`DialMap`]. struct DialEntry { handle: AbortHandle, sources: DialSources, active: DialSource, - unannounced_at: Option, } /// Map of in-flight cluster dials, keyed by canonical peer identity. Cloneable: the inner -/// map is shared via `Arc>` so the discovery task and the static-seed +/// map is shared via `Arc>` so the discovery tasks and the static-seed /// phase write to the same set of entries. #[derive(Clone, Default)] struct DialMap { @@ -514,7 +438,7 @@ impl DialMap { /// Add or update one source's target, replacing the live dial only when that /// source already owns it. Other sources retain their latest target as a /// fallback without changing the first source's active configuration. - fn upsert(&self, target: DialTarget, source: DialSource, spawn: &mut F) -> bool + fn upsert(&self, target: DialTarget, source: DialSource, spawn: &mut F) where F: FnMut(DialTarget) -> AbortHandle, { @@ -522,12 +446,11 @@ impl DialMap { if let Some(entry) = map.get_mut(&target.key) { let replace = entry.active == source && entry.sources.get(source) != Some(&target); entry.sources.set(source, target.clone()); - let reannounced = source == DialSource::Gossip && entry.unannounced_at.take().is_some(); if replace { entry.handle.abort(); entry.handle = spawn(target); } - return reannounced; + return; } let key = target.key.clone(); @@ -540,10 +463,8 @@ impl DialMap { handle, sources, active: source, - unannounced_at: None, }, ); - false } /// Release one source. If it owned the live dial, switch to a remaining @@ -577,42 +498,6 @@ impl DialMap { entry.handle.abort(); } - /// Start the gossip stale timer on `peer` if it isn't already pending. No-op - /// unless the peer is currently wanted by gossip. Idempotent: a repeat - /// unannounce while a timestamp is pending doesn't reset the clock. - fn mark_unannounced(&self, peer: &str, now: Instant) { - let mut map = self.inner.lock().expect("dial map poisoned"); - if let Some(entry) = map.get_mut(peer) - && entry.sources.gossip.is_some() - { - entry.unannounced_at.get_or_insert(now); - } - } - - /// Release the gossip source from entries whose unannounce has stuck for at - /// least `threshold`, aborting the dial only if no other source still wants it. - fn sweep_stale(&self, now: Instant, threshold: Duration, spawn: &mut F) - where - F: FnMut(DialTarget) -> AbortHandle, - { - let mut map = self.inner.lock().expect("dial map poisoned"); - let expired: Vec = map - .iter_mut() - .filter_map(|(peer, entry)| { - let at = entry.unannounced_at?; - (now.duration_since(at) >= threshold).then(|| { - entry.unannounced_at = None; - peer.clone() - }) - }) - .collect(); - drop(map); - - for peer in expired { - self.release(&peer, DialSource::Gossip, spawn); - } - } - /// Reconcile the API source against `desired`, including changes to a peer's /// dial-affecting URL or link cost while its canonical identity stays fixed. fn reconcile_api(&self, desired: &HashMap, mut spawn: F) @@ -639,10 +524,10 @@ impl DialMap { /// Configuration for relay clustering. /// -/// [`Self::connect`] / [`Self::connect_api`] list peers to dial. [`Self::node`] is -/// this relay's own URL (identity); [`Self::mesh`] enables gossip, advertising that -/// URL so other peers discover and dial it. Set `node` + `mesh` with no `connect` -/// to act as a passive rendezvous. +/// [`Self::connect`] / [`Self::connect_api`] list peers to dial, and +/// [`Self::node`] is this relay's own URL (identity). A relay only dials peers +/// configured here or found on the LAN; it never dials a URL learned from an +/// announcement. /// /// Hop-based routing on broadcasts prevents announcement loops regardless of topology. #[serde_with::serde_as] @@ -703,7 +588,7 @@ pub struct Config { /// notifications (with a periodic re-check fallback). This relay's own /// [`Self::node`] value, when set, is sent as a `?node=` query param so the /// server can return this node's peers. The relay keeps the last good list if - /// a fetch fails. Composes with [`Self::connect`] and [`Self::mesh`]. + /// a fetch fails. Composes with [`Self::connect`]. #[usage( name = "cluster-connect-api", long = "cluster-connect-api", @@ -714,8 +599,8 @@ pub struct Config { /// This relay's own externally-reachable URL (identity). Sent to /// [`Self::connect_api`] as a `?node=` query param so the endpoint can return - /// this node's peers, and advertised to other relays when [`Self::mesh`] gossip - /// is enabled. On its own it neither opens nor accepts a connection. + /// this node's peers, and advertised over mDNS when LAN discovery is on. On + /// its own it neither opens nor accepts a connection. #[usage( name = "cluster-node", long = "cluster-node", @@ -724,15 +609,10 @@ pub struct Config { )] pub node: Option, - /// Enable gossip discovery: advertise this relay's [`Self::node`] URL on the - /// cluster origin so peers can find and dial it (and so this relay discovers - /// peers the same way). Requires [`Self::node`]. Boolean flag: pass - /// `--cluster-mesh` (or `=true` / `=false`). - /// - /// Kept as a string for backwards compatibility: `--cluster-mesh` used to take - /// this relay's URL. A non-boolean value is treated as a legacy [`Self::node`] - /// (with a deprecation warning), or an error if it conflicts with an explicit - /// `--cluster-node`. Accepts a TOML boolean or string. + /// Released spelling of the removed gossip discovery, kept so + /// [`Self::deprecated`] can refuse it. Any value, boolean or the older URL + /// form, is refused. + #[doc(hidden)] #[usage( name = "cluster-mesh", long = "cluster-mesh", @@ -741,6 +621,7 @@ pub struct Config { default_missing = "true", num_args = 0..=1, require_equals = true, + hide = true, )] #[serde(default, deserialize_with = "deserialize_bool_or_string")] pub mesh: Option, @@ -752,12 +633,10 @@ pub struct Config { pub lan: LanConfig, /// JWT presented on outbound cluster dials, read from this file. Applied to - /// any static, API, or gossip peer whose URL doesn't already carry a - /// `?jwt=` and whose object entry sets no `token`. An inline `?jwt=` or - /// object `token` provides a per-peer credential for static or `connect_api` - /// peers. Gossip should use this shared token or mTLS - /// because the advertised node URL is public. LAN peers never receive it; - /// they authenticate with their mDNS credential. + /// any static or API peer whose URL doesn't already carry a `?jwt=` and + /// whose object entry sets no `token`. An inline `?jwt=` or object `token` + /// provides a per-peer credential instead. LAN peers never receive it; they + /// authenticate with their mDNS credential. #[usage( name = "cluster-token", long = "cluster-token", @@ -804,6 +683,14 @@ impl Config { "a broadcast closes as soon as its last publisher is lost", ); } + if self.mesh.is_some() { + found.changed( + "--cluster-mesh", + Some("MOQ_CLUSTER_MESH"), + "--cluster-connect or --cluster-connect-api", + "gossip discovery is removed; list every peer this relay dials", + ); + } if self.connect.iter().any(|peer| is_legacy_peer(peer.url())) { found.changed( "--cluster-connect", @@ -1006,9 +893,7 @@ impl std::fmt::Debug for Started { /// The resolved settings behind a [`Started`] that has work to do. struct Work { - gossip: bool, node: Option, - can_dial: bool, token: String, /// The live mDNS advertisement, bound by [`Cluster::start`]. #[cfg(feature = "cluster-lan")] @@ -1029,7 +914,7 @@ struct Work { pub struct Cluster { config: Config, client: Option, - /// Dial template for LAN peers that pin a fingerprint; static and gossip + /// Dial template for LAN peers that pin a fingerprint; static and API /// dials keep [`Self::client`]. connect: Option, quic: Option, @@ -1112,7 +997,7 @@ impl Cluster { origin_config.cache_duration = cache.duration; } let origin = moq_tokio::origin::spawn_config(origin_config); - let nodes = crate::nodes::Nodes::new(origin.clone()); + let nodes = crate::nodes::Nodes::default(); tracing::info!(hop_id = %origin.hop(), configured = config.id.is_some(), "cluster initialized"); Ok(Cluster { config, @@ -1234,36 +1119,6 @@ impl Cluster { Some(origin) } - /// Resolve whether gossip is on and which URL this relay advertises, from - /// `cluster.node` and the (string-typed) `cluster.mesh` toggle. - /// - /// `mesh` is `"true"` / `"false"` normally. For backwards compatibility a - /// non-boolean value is the legacy "advertise this URL" form: it turns gossip - /// on and supplies the node URL (with a deprecation warning), unless it - /// conflicts with an explicit `cluster.node`, which is an error. - fn resolve_mesh(&self) -> anyhow::Result<(bool, Option)> { - let node = self.config.node.clone(); - match self.config.mesh.as_deref() { - None => Ok((false, node)), - Some("true") => Ok((true, node)), - Some("false") => Ok((false, node)), - Some(legacy) => { - tracing::warn!( - value = %legacy, - "`--cluster-mesh` is now a boolean; treating the value as `--cluster-node` for backwards \ - compatibility. Set `--cluster-node ` and `--cluster-mesh` instead." - ); - match &node { - Some(node) if node != legacy => anyhow::bail!( - "`--cluster-mesh` was given URL {legacy:?}, which conflicts with `--cluster-node` {node:?}. \ - `--cluster-mesh` is now a boolean; set the address only via `--cluster-node`." - ), - _ => Ok((true, Some(legacy.to_owned()))), - } - } - } - } - /// Whether `--cluster-lan` asked this relay to discover peers over mDNS. fn lan(&self) -> bool { #[cfg(feature = "cluster-lan")] @@ -1351,16 +1206,10 @@ impl Cluster { /// would release systemd's dependent units on a relay that is about to exit. /// Call this before signalling readiness, and hand the result to `run`. /// - /// Bails when `mesh` gossip is on without `node`, or when peers are configured - /// to dial but no client was attached via [`with_client`](Self::with_client). + /// Bails when peers are configured to dial but no client was attached via + /// [`with_client`](Self::with_client). pub async fn start(self) -> anyhow::Result { - let (gossip, node) = self.resolve_mesh()?; - anyhow::ensure!( - !gossip || node.is_some(), - "`--cluster-mesh` (gossip) requires `--cluster-node ` so there's an address to advertise. \ - See https://doc.moq.dev/bin/relay/cluster." - ); - + let node = self.config.node.clone(); let lan = self.lan(); #[cfg(feature = "cluster-lan")] self.config.lan.validate()?; @@ -1387,12 +1236,8 @@ impl Cluster { } } - let has_outbound = !self.config.connect.is_empty() || self.config.connect_api.is_some(); - // Every mechanism that opens a dial, so gossip discovery runs whenever - // there is something to dial with, not only when a peer was listed. - let can_dial = has_outbound || lan; - let has_work = can_dial || gossip; - if !has_work { + let can_dial = !self.config.connect.is_empty() || self.config.connect_api.is_some() || lan; + if !can_dial { tracing::info!("no cluster peers configured; running standalone"); return Ok(Started { work: None, @@ -1400,12 +1245,10 @@ impl Cluster { }); } - if can_dial { - anyhow::ensure!( - self.client.is_some(), - "cluster peers configured but no QUIC client attached (call Cluster::with_client)" - ); - } + anyhow::ensure!( + self.client.is_some(), + "cluster peers configured but no QUIC client attached (call Cluster::with_client)" + ); // Only http(s) sources need the TLS client; a local file doesn't. if let Some(source) = &self.config.connect_api { @@ -1449,9 +1292,7 @@ impl Cluster { Ok(Started { work: Some(Work { - gossip, node, - can_dial, token, #[cfg(feature = "cluster-lan")] discovery, @@ -1461,29 +1302,18 @@ impl Cluster { } /// Runs the cluster event loop against the work [`start`](Self::start) - /// resolved. - /// - /// Modes are derived from config: passive rendezvous (`node` + `mesh` gossip, - /// no peers to dial) parks after publishing self-registration and does not - /// require a QUIC client; active (`connect` / `connect_api` set) dials peers - /// and, when `mesh` gossip is on, also advertises `node` and runs discovery. + /// resolved: dials the static peers, then keeps the `connect_api` list and + /// LAN discovery reconciled into the same dial set. async fn run_work(self, work: Work) -> anyhow::Result<()> { let Work { - gossip, node, - can_dial, token, #[cfg(feature = "cluster-lan")] discovery, } = work; - // Static `--cluster-connect` peers and gossip-discovered peers share one - // dial map so a peer reached via both paths only opens a single dial. - // Gossip-driven unannounces don't abort immediately. The discovery loop - // runs a periodic sweep that only aborts entries whose unannounce has - // stuck for [`STALE_AFTER`]. That filters out the prefer-shorter-hop flap - // (sub-millisecond unannounce-then-announce) while still cleaning up - // peers that truly left. + // Every source shares one dial map so a peer reached via several only + // opens a single dial. let dialed = DialMap::default(); let mut tasks = tokio::task::JoinSet::new(); // Tasks whose ending is a failure rather than an ordinary lifecycle event, @@ -1522,45 +1352,6 @@ impl Cluster { supervised.spawn(async move { this.run_mdns(dialed, discovery).await }); } - // Held in scope so the registration stays announced until `run` exits. - // Discovery is paired with it: a gossip-only relay (passive rendezvous) has - // nothing to discover, so we only run it when we also have an outbound peer. - // The path itself is the advertisement: an empty broadcast, announced. - let mut self_registration: Option = if gossip { - // Checked above: gossip requires `node`. - let node = node.as_deref().expect("gossip requires --cluster-node"); - let path = Path::new(MESH_PREFIX).join(node); - let registration = self - .origin - .create_broadcast(&path) - .expect(".internal/origins is within the relay origin's root"); - registration - .announce(moq_net::origin::Route::default()) - .expect("the origin driver outlives the cluster"); - tracing::info!(%node, %path, "advertising cluster node URL"); - - if can_dial { - let this = self.clone(); - let token = token.clone(); - let dialed = dialed.clone(); - // Canonical, so the tiebreaker compares the same spelling both sides do. - let self_url = canonicalize_peer_key(node); - tasks.spawn(async move { - this.run_discovery(self_url, token, dialed).await; - }); - } - - Some(registration) - } else { - None - }; - - if tasks.is_empty() && supervised.is_empty() { - // Passive rendezvous: park to keep `self_registration` alive. The - // process still exits via the other arms of `tokio::select!` in main. - std::future::pending::<()>().await - } - loop { tokio::select! { // A supervised task ending at all is a failure, so its result decides @@ -1571,104 +1362,16 @@ impl Cluster { else => break, } } - - // Deliberate shutdown: closing the registration retracts the route. - if let Some(registration) = self_registration.as_mut() { - registration.close(); - } Ok(()) } - /// Watch `.internal/origins/*` for peer registrations and dial each newly- - /// announced URL that sorts after our own (see [`should_dial`]); the peer on - /// the other side of that comparison dials us, so each pair opens one session - /// instead of two. Unannounces don't abort immediately. They just mark the - /// entry as "pending cleanup" with a timestamp. A periodic sweep evicts - /// entries whose unannounce has stuck for [`STALE_AFTER`]. The "prefer - /// shorter hop" path in origin::Producer delivers re-announces as - /// unannounce-then-announce within sub-milliseconds, which clears the - /// pending-cleanup timestamp long before the sweep fires. - async fn run_discovery(self, self_url: String, token: String, dialed: DialMap) { - let Ok(consumer) = self - .origin - .consume() - .scope(MESH_PREFIX, &moq_net::Patterns::from(moq_net::Pattern::all())) - else { - tracing::warn!("could not scope cluster origin to {MESH_PREFIX}; discovery disabled"); - return; - }; - let mut announced = consumer.announced(); - let mut live = GossipTargets::default(); - - let mut sweep = tokio::time::interval(SWEEP_INTERVAL); - sweep.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip); - // Skip the first immediate tick; nothing has had a chance to go stale yet. - sweep.tick().await; - - loop { - tokio::select! { - ann = announced.next() => { - let Some(update) = ann else { return; }; - let relative = update.prefix; - // The address to dial, which keeps its query: `run_remote` reads - // `?cost=` and `?jwt=` off it. The key is only its identity. - let peer = advertised_node_url(relative.as_str()); - let target = match DialTarget::parse(&peer) { - Ok(target) => target, - Err(err) => { - tracing::warn!(%err, "invalid gossiped cluster peer URL; ignoring update"); - continue; - } - }; - // Skip self and any peer we lose the tiebreaker to; that side - // dials us instead, so each pair forms a single session. - if !should_dial(&self_url, &target.key) { - continue; - } - let advertisement = relative.as_str().to_owned(); - match update.kind.is_active() { - true => { - let target = live.announce(advertisement, target); - let mut spawn = |target: DialTarget| { - tracing::info!(peer = %target.key, "discovered cluster peer; dialing"); - tokio::spawn(self.clone().supervise_remote(target, token.clone())).abort_handle() - }; - let key = target.key.clone(); - if dialed.upsert(target, DialSource::Gossip, &mut spawn) { - tracing::debug!(peer = %key, "reannounce within sweep window; keeping dial"); - } - } - false => match live.unannounce(&advertisement, &target.key) { - GossipUpdate::Current(target) => { - let mut spawn = |target: DialTarget| { - tracing::info!(peer = %target.key, "cluster peer advertisement changed; redialing"); - tokio::spawn(self.clone().supervise_remote(target, token.clone())).abort_handle() - }; - dialed.upsert(target, DialSource::Gossip, &mut spawn); - } - GossipUpdate::Unchanged => {} - GossipUpdate::Gone => dialed.mark_unannounced(&target.key, Instant::now()), - }, - } - } - _ = sweep.tick() => { - let mut spawn = |target: DialTarget| { - tracing::info!(peer = %target.key, "cluster peer source changed; redialing"); - tokio::spawn(self.clone().supervise_remote(target, token.clone())).abort_handle() - }; - dialed.sweep_stale(Instant::now(), STALE_AFTER, &mut spawn); - } - } - } - } - /// Dial every process that advertises itself on the LAN. /// /// Each candidate is [`Peer::urls`](moq_tokio::mdns::Peer::urls) in order /// (node first) on `/.cluster/`, with the advertised fingerprint /// pinned. The lower discovery id dials; the other waits inbound. A LAN dial - /// never carries `?jwt=` — [`Config::token`] is for static and gossip - /// peers only. + /// never carries `?jwt=`: [`Config::token`] is for static and API peers + /// only. #[cfg(feature = "cluster-lan")] async fn run_mdns(self, dialed: DialMap, mut discovery: moq_tokio::mdns::Discovery) -> anyhow::Result<()> { use moq_tokio::mdns::Event; @@ -2135,8 +1838,8 @@ fn connect_api_is_http(source: &str) -> bool { /// /// The modern form is a full URL, e.g. `https://host/?jwt=TOKEN`, which is used /// verbatim. A bare host or `host:port` is wrapped in `https://.../` for -/// gossip and `--cluster-connect-api` lists; user-supplied `--cluster-connect` -/// entries refuse that form through [`Config::deprecated`]. +/// `--cluster-connect-api` lists; user-supplied `--cluster-connect` entries +/// refuse that form through [`Config::deprecated`]. fn peer_url(peer: &str) -> anyhow::Result { // A full URL has a scheme separator; a bare host or `host:port` does not // (and `Url::parse` would otherwise mis-read `host:port` as scheme `host`). @@ -2147,33 +1850,6 @@ fn peer_url(peer: &str) -> anyhow::Result { Url::parse(&format!("https://{peer}/")).context("invalid cluster peer host") } -/// The address to dial for a node advertised under `MESH_PREFIX`. -/// -/// A relay advertises its URL as a broadcast path, and [`Path`] collapses slash -/// runs, so `https://relay-b.example/` arrives as `https:/relay-b.example`. The -/// scheme is put back here rather than read as a hostname. -/// -/// The trailing colon on the leading segment is what marks a scheme: a bare -/// `host:port` carries its colon in the middle of the segment, never at the end, -/// so the two spellings can't be mistaken for each other and no list of known -/// schemes is needed. A scheme-less advertisement means `https`, exactly as -/// [`peer_url`] reads a bare host. -/// -/// The query survives, because [`Cluster::run_remote`] reads `?cost=` and `?jwt=` -/// off the address it dials. Pass the result through [`canonicalize_peer_key`] -/// for an identity key; don't dial the key, which drops the query. -/// -/// A trailing slash on a non-empty URL path does not survive, since a path has no -/// way to spell one. `https://a.example/edge/` advertises the same as -/// `https://a.example/edge`. -pub(crate) fn advertised_node_url(advertised: &str) -> String { - match advertised.split_once('/') { - // The segment already ends in `:`, so this restores the `//` the path ate. - Some((scheme, rest)) if scheme.ends_with(':') => format!("{scheme}//{rest}"), - _ => advertised.to_owned(), - } -} - /// Whether a peer string uses the released bare-host / `host:port` form rather /// than a full URL. Used so [`Config::deprecated`] can refuse /// `--cluster-connect` entries that still use it. @@ -2199,10 +1875,9 @@ pub(crate) fn canonicalize_peer_key(peer: &str) -> String { url.set_fragment(None); url.set_username("").ok(); url.set_password(None).ok(); - // Gossip round-trips the URL through `Path`, which trims slashes and - // collapses runs of them, so the key normalizes the path the same way. - // A non-special scheme like `moqt` keeps its trailing slash otherwise, - // and `moqt://a.example:4443/` is an ordinary way to spell a node. + // Trim and collapse path slashes: a non-special scheme like `moqt` keeps + // its trailing slash otherwise, and `moqt://a.example:4443/` is an + // ordinary way to spell the same node as `moqt://a.example:4443`. let segments: Vec<&str> = url.path().split('/').filter(|s| !s.is_empty()).collect(); let path = match segments.is_empty() { true => String::new(), @@ -2216,8 +1891,9 @@ pub(crate) fn canonicalize_peer_key(peer: &str) -> String { } /// Deserialize a field that accepts either a TOML boolean or string into an -/// `Option` (booleans become `"true"` / `"false"`). Lets `cluster.mesh` -/// take the modern `mesh = true` form or the legacy `mesh = ""` form. +/// `Option` (booleans become `"true"` / `"false"`). Lets the removed +/// `cluster.mesh` parse in both its released forms, `mesh = true` and +/// `mesh = ""`, so it is refused by name rather than as an unknown type. fn deserialize_bool_or_string<'de, D>(deserializer: D) -> Result, D::Error> where D: serde::Deserializer<'de>, @@ -2398,138 +2074,20 @@ mod tests { keys.iter().map(|key| ((*key).to_string(), target(key))).collect() } - /// A query change creates a new gossip path before the old path necessarily - /// unannounces. Removing that old path must not stale the replacement. - #[test] - fn gossip_old_unannounce_keeps_new_target() { - let mut live = GossipTargets::default(); - let old = DialTarget::parse("https://peer.example/?cost=1").unwrap(); - let new = DialTarget::parse("https://peer.example/?cost=2").unwrap(); - live.announce("peer.example/?cost=1".to_string(), old.clone()); - live.announce("peer.example/?cost=2".to_string(), new.clone()); - - assert!(matches!( - live.unannounce("peer.example/?cost=1", &old.key), - GossipUpdate::Unchanged - )); - assert!(matches!( - live.unannounce("peer.example/?cost=2", &new.key), - GossipUpdate::Gone - )); - } - - /// If the current gossip path disappears while an older one is still live, - /// the remaining target becomes current again. - #[test] - fn gossip_current_unannounce_restores_live_fallback() { - let mut live = GossipTargets::default(); - let old = DialTarget::parse("https://peer.example/?cost=1").unwrap(); - let new = DialTarget::parse("https://peer.example/?cost=2").unwrap(); - live.announce("peer.example/?cost=1".to_string(), old.clone()); - live.announce("peer.example/?cost=2".to_string(), new.clone()); - - let GossipUpdate::Current(current) = live.unannounce("peer.example/?cost=2", &new.key) else { - panic!("older live advertisement must become current"); - }; - assert!(current == old); - } - - /// `mark_unannounced` is a no-op for static peers (operator intent says - /// "always dial"), so the sweep never has a stale timestamp to act on. - #[tokio::test] - async fn sweep_preserves_static_peer() { - let dialed = DialMap::default(); - dialed.insert(target("static-peer:4443"), placeholder_handle(), DialSource::Static); - - let long_ago = Instant::now() - Duration::from_secs(3600); - dialed.mark_unannounced("static-peer:4443", long_ago); - dialed.sweep_stale(Instant::now(), STALE_AFTER, &mut |_| panic!("must not redial")); - - assert!(dialed.contains("static-peer:4443")); - } - - /// A gossip-discovered peer whose unannounce has stuck longer than the - /// threshold gets aborted and removed. - #[tokio::test] - async fn sweep_evicts_stale_gossip_peer() { - let dialed = DialMap::default(); - let now = Instant::now(); - dialed.insert(target("gone:4443"), placeholder_handle(), DialSource::Gossip); - dialed.mark_unannounced("gone:4443", now - STALE_AFTER - Duration::from_secs(1)); - - dialed.sweep_stale(now, STALE_AFTER, &mut |_| panic!("must not redial")); - - assert!(!dialed.contains("gone:4443")); - } - - /// A gossip-discovered peer whose unannounce is recent stays in the map; the - /// sweep is only allowed to evict entries past the full threshold so that the - /// prefer-shorter-hop flap (sub-millisecond unannounce-then-announce) doesn't - /// trip it. - #[tokio::test] - async fn sweep_keeps_recently_unannounced_peer() { - let dialed = DialMap::default(); - let now = Instant::now(); - dialed.insert(target("flapping:4443"), placeholder_handle(), DialSource::Gossip); - dialed.mark_unannounced("flapping:4443", now - Duration::from_millis(50)); - - dialed.sweep_stale(now, STALE_AFTER, &mut |_| panic!("must not redial")); - - assert!(dialed.contains("flapping:4443")); - } - - /// A peer that's currently announced (no pending unannounce) is never swept. - #[tokio::test] - async fn sweep_keeps_currently_announced_peer() { - let dialed = DialMap::default(); - dialed.insert(target("healthy:4443"), placeholder_handle(), DialSource::Gossip); - // No mark_unannounced -> stays announced. - - dialed.sweep_stale(Instant::now(), STALE_AFTER, &mut |_| panic!("must not redial")); - - assert!(dialed.contains("healthy:4443")); - } - - /// A re-announce after an unannounce clears the pending-sweep timestamp, so - /// the entry survives even if the original unannounce was old enough to - /// otherwise trigger eviction. - #[tokio::test] - async fn reannounce_cancels_pending_sweep() { - let dialed = DialMap::default(); - let now = Instant::now(); - let target = target("flap:4443"); - dialed.insert(target.clone(), placeholder_handle(), DialSource::Gossip); - dialed.mark_unannounced("flap:4443", now - STALE_AFTER - Duration::from_secs(1)); - - // Re-adding the gossip source (a reannounce) clears the pending sweep. - assert!( - dialed.upsert(target.clone(), DialSource::Gossip, &mut |_| panic!("must not redial")), - "should report a cleared pending-sweep" - ); - dialed.sweep_stale(now, STALE_AFTER, &mut |_| panic!("must not redial")); - - assert!(dialed.contains("flap:4443")); - // A second reannounce has nothing to clear. - assert!(!dialed.upsert(target, DialSource::Gossip, &mut |_| panic!("must not redial"))); - } - - /// A peer wanted by both gossip and the API survives losing either source: the - /// dial is only torn down once the last source releases it. + /// A peer wanted by both a static seed and the API survives losing either + /// source: the dial is only torn down once the last source releases it. #[tokio::test] async fn multi_source_peer_survives_until_last_release() { let dialed = DialMap::default(); - let now = Instant::now(); - // Gossiped first, then also appears in the API list. - dialed.insert(target("both:4443"), placeholder_handle(), DialSource::Gossip); + // Seeded first, then also appears in the API list. + dialed.insert(target("both:4443"), placeholder_handle(), DialSource::Static); dialed.reconcile_api(&desired(&["both:4443"]), |_| panic!("already dialed")); - // Dropped from the API list -> still wanted by gossip. - dialed.reconcile_api(&HashMap::new(), |_| panic!("gossip dial stays active")); - assert!(dialed.contains("both:4443"), "gossip still wants it"); + // Dropped from the API list -> still wanted by the seed. + dialed.reconcile_api(&HashMap::new(), |_| panic!("static dial stays active")); + assert!(dialed.contains("both:4443"), "the seed still wants it"); - // Now gossip goes stale too -> the dial is finally released. - dialed.mark_unannounced("both:4443", now - STALE_AFTER - Duration::from_secs(1)); - dialed.sweep_stale(now, STALE_AFTER, &mut |_| panic!("must not redial")); + dialed.release("both:4443", DialSource::Static, &mut |_| panic!("must not redial")); assert!(!dialed.contains("both:4443")); } @@ -2538,27 +2096,26 @@ mod tests { #[tokio::test] async fn insert_merges_redundant_dial() { let dialed = DialMap::default(); - dialed.insert(target("p:4443"), placeholder_handle(), DialSource::Gossip); + dialed.insert(target("p:4443"), placeholder_handle(), DialSource::Static); dialed.insert(target("p:4443"), placeholder_handle(), DialSource::Api); - // Dropping the API source leaves the gossip source holding the dial. - dialed.reconcile_api(&HashMap::new(), |_| panic!("gossip dial stays active")); - assert!(dialed.contains("p:4443"), "gossip source still holds the dial"); + // Dropping the API source leaves the static source holding the dial. + dialed.reconcile_api(&HashMap::new(), |_| panic!("static dial stays active")); + assert!(dialed.contains("p:4443"), "static source still holds the dial"); } /// `reconcile_api` drops API dials missing from the desired set, reports the - /// newly desired ones for the caller to spawn, and never touches Static or - /// Gossip dials (even when they're absent from the API list). + /// newly desired ones for the caller to spawn, and never touches Static dials + /// (even when they're absent from the API list). #[tokio::test] async fn reconcile_api_adds_and_removes_only_api() { let dialed = DialMap::default(); dialed.insert(target("static:4443"), placeholder_handle(), DialSource::Static); - dialed.insert(target("gossip:4443"), placeholder_handle(), DialSource::Gossip); dialed.insert(target("api-keep:4443"), placeholder_handle(), DialSource::Api); dialed.insert(target("api-drop:4443"), placeholder_handle(), DialSource::Api); // Desired: keep one existing API peer, drop the other, add a new one. - // Static/Gossip peers are not in the list but must survive. + // The static peer is not in the list but must survive. let mut to_add = Vec::new(); dialed.reconcile_api(&desired(&["api-keep:4443", "api-new:4443"]), |target| { to_add.push(target.key); @@ -2570,7 +2127,6 @@ mod tests { assert!(dialed.contains("api-keep:4443")); assert!(!dialed.contains("api-drop:4443"), "dropped API peer must be removed"); assert!(dialed.contains("static:4443"), "static peer must survive reconcile"); - assert!(dialed.contains("gossip:4443"), "gossip peer must survive reconcile"); } /// A peer already dialed via another source is not re-reported for dialing, @@ -2590,19 +2146,17 @@ mod tests { #[tokio::test] async fn inactive_source_update_applies_on_takeover() { let dialed = DialMap::default(); - let gossip = DialTarget::parse("https://peer.example/?cost=1").unwrap(); + let seeded = DialTarget::parse("https://peer.example/?cost=1").unwrap(); let api = DialTarget::parse("https://peer.example/?cost=3").unwrap(); let old_task = tokio::spawn(std::future::pending::<()>()); - dialed.insert(gossip.clone(), old_task.abort_handle(), DialSource::Gossip); + dialed.insert(seeded.clone(), old_task.abort_handle(), DialSource::Static); let desired = [(api.key.clone(), api.clone())].into_iter().collect(); dialed.reconcile_api(&desired, |_| panic!("inactive source must not redial")); assert!(!old_task.is_finished()); - let now = Instant::now(); - dialed.mark_unannounced(&gossip.key, now - STALE_AFTER - Duration::from_secs(1)); let mut spawned = Vec::new(); - dialed.sweep_stale(now, STALE_AFTER, &mut |target| { + dialed.release(&seeded.key, DialSource::Static, &mut |target| { spawned.push(target); placeholder_handle() }); @@ -2620,14 +2174,14 @@ mod tests { let dialed = DialMap::default(); let target = DialTarget::parse("https://peer.example/?cost=1").unwrap(); let task = tokio::spawn(std::future::pending::<()>()); - dialed.insert(target.clone(), task.abort_handle(), DialSource::Gossip); + dialed.insert(target.clone(), task.abort_handle(), DialSource::Static); let desired = [(target.key.clone(), target.clone())].into_iter().collect(); dialed.reconcile_api(&desired, |_| panic!("inactive source must not redial")); - let now = Instant::now(); - dialed.mark_unannounced(&target.key, now - STALE_AFTER - Duration::from_secs(1)); - dialed.sweep_stale(now, STALE_AFTER, &mut |_| panic!("identical fallback must not redial")); + dialed.release(&target.key, DialSource::Static, &mut |_| { + panic!("identical fallback must not redial") + }); assert!(!task.is_finished(), "healthy dial must be preserved"); let map = dialed.inner.lock().expect("dial map"); @@ -2935,30 +2489,22 @@ mod tests { task.abort(); } - /// The mesh tiebreaker only dials peers that sort after us, so exactly one - /// side of each pair opens the dial. Self never dials self. - #[test] - fn should_dial_prefers_larger_url() { - // Smaller hostname is the client: it dials the larger. - assert!(should_dial("a.example.com:4443", "b.example.com:4443")); - // Larger hostname is the server: it waits for the inbound dial. - assert!(!should_dial("b.example.com:4443", "a.example.com:4443")); - // Never dial self. - assert!(!should_dial("self.example.com:4443", "self.example.com:4443")); - } - - /// Enabling gossip (`--cluster-mesh`) without `--cluster-node` has no address to - /// advertise, so it must fail fast with a message naming the missing flag. + /// Gossip discovery is removed, so every released `--cluster-mesh` form, the + /// boolean and the older self-URL, stops construction and names the + /// replacement instead of leaving a relay without the peers it expected. #[tokio::test] - async fn gossip_without_node_errors() { - let config = Config { - mesh: Some("true".to_string()), - ..Default::default() - }; - let err = new_cluster(config).unwrap().start().await.expect_err("should error"); - let msg = format!("{err}"); - assert!(msg.contains("--cluster-node"), "missing --cluster-node in: {msg}"); - assert!(msg.contains("--cluster-mesh"), "missing --cluster-mesh in: {msg}"); + async fn removed_mesh_is_refused() { + for value in ["true", "false", "rendezvous.example.com:4443"] { + let err = new_cluster(Config { + mesh: Some(value.to_string()), + ..Default::default() + }) + .err() + .expect("mesh must be refused"); + let msg = format!("{err}"); + assert!(msg.contains("--cluster-mesh / MOQ_CLUSTER_MESH"), "{value}: {msg}"); + assert!(msg.contains("--cluster-connect"), "{value}: {msg}"); + } } /// A valid `cluster.id` is used verbatim as the relay's Hop ID, giving the @@ -2973,8 +2519,8 @@ mod tests { assert_eq!(cluster.origin.hop().id(), 42); } - /// Cache settings land on the one origin serving, node discovery, and stats - /// share. A handle cloned at construction stays on that origin. + /// Cache settings land on the one origin serving and stats share. A handle + /// cloned at construction stays on that origin. #[tokio::test] async fn constructed_origin_keeps_cache_and_handles() { let duration = Duration::from_secs(5); @@ -3021,26 +2567,7 @@ mod tests { .expect("broadcast resolves") .expect("broadcast present"); - let path = Path::new(MESH_PREFIX).join("https://peer.example/"); - let mut announced = consumer - .clone() - .scope(MESH_PREFIX, &moq_net::Patterns::from(moq_net::Pattern::all())) - .expect("mesh prefix") - .announced(); - let registration = origin.create_broadcast(&path).expect("node advertise"); - registration.announce(Default::default()).expect("announce node"); - let update = tokio::time::timeout(Duration::from_secs(2), announced.next()) - .await - .expect("node advertised") - .expect("announce"); - assert!(update.kind.is_active()); - let snapshot = cluster.nodes.snapshot(); - assert!( - snapshot.nodes.iter().any(|node| node.node.contains("peer.example")), - "node discovery reads the constructed origin: {snapshot:?}" - ); - - let stats_path = Path::new(".stats").join("node").join("test"); + let stats_path = moq_net::Path::new(".stats").join("node").join("test"); tokio::time::timeout(Duration::from_secs(5), consumer.routed(&stats_path)) .await .expect("stats announced") @@ -3062,71 +2589,49 @@ mod tests { } } - /// A relay configured with `cluster.node` + `cluster.mesh` gossip and no peers - /// (passive rendezvous) must run without a QUIC client, publish its - /// self-registration on the cluster origin, and keep that registration alive - /// (i.e. not exit and drop the broadcast). - #[tokio::test(start_paused = true)] - async fn passive_rendezvous_runs_without_client_and_advertises_self() { - let cluster = new_cluster(Config { - node: Some("rendezvous.example.com:4443".to_string()), - mesh: Some("true".to_string()), - ..Default::default() - }) - .unwrap(); - - // Snapshot a consumer on the cluster origin before run() takes ownership of - // `cluster` so we can later check that the registration was published. - let mut watcher = cluster.origin.consume().with_hidden(true).announced(); - - let started = cluster.clone().start().await.expect("cluster start"); - let mut handle = tokio::spawn(async move { started.run().await }); - - // Give the runtime a moment to execute the synchronous setup work. - tokio::time::sleep(tokio::time::Duration::from_millis(10)).await; - - // The self-registration route must be visible on the origin. - let update = watcher.try_next().expect("self-registration must be published"); - assert_eq!(update.prefix.as_str(), ".internal/origins/rendezvous.example.com:4443"); - assert!(update.kind.is_active()); - - // run() must NOT have returned: dropping the broadcast (via run returning) - // would unannounce the registration immediately. Use a short timeout to - // confirm we're still parked. - let still_running = tokio::time::timeout(tokio::time::Duration::from_millis(50), &mut handle) - .await - .is_err(); - assert!(still_running, "passive rendezvous run() should park, not return"); - - handle.abort(); - } - - /// `cluster.node` (identity) and `cluster.mesh` (gossip toggle) round-trip - /// through TOML and survive the CLI re-parse when no flags override them. - /// `mesh` is a string that accepts a TOML boolean for compatibility. + /// `cluster.node` (identity) round-trips through TOML and survives the CLI + /// re-parse when no flags override it. #[test] - fn cluster_node_and_mesh_round_trip() { + fn cluster_node_round_trip() { // Usage reads the environment while parsing, so serialize with the tests // that mutate it. let _env = crate::test_env::EnvGuard::lock(); - let toml = "[cluster]\nnode = \"us-east.example.com:4443\"\nmesh = true\nconnect = [\"https://root.example.com:4443/\"]\n"; + let toml = "[cluster]\nnode = \"us-east.example.com:4443\"\nconnect = [\"https://root.example.com:4443/\"]\n"; let dir = std::env::temp_dir().join("moq-relay-cluster-test"); std::fs::create_dir_all(&dir).unwrap(); - let path = dir.join("cluster-node-mesh-toml.toml"); + let path = dir.join("cluster-node-toml.toml"); std::fs::write(&path, toml).unwrap(); let args = vec![std::ffi::OsString::from("moq-relay"), std::ffi::OsString::from(&path)]; let config = RelayConfig::parse_and_merge(args).expect("config load"); assert_eq!(config.cluster.node.as_deref(), Some("us-east.example.com:4443")); - // A TOML boolean deserializes into the string form. - assert_eq!(config.cluster.mesh.as_deref(), Some("true")); assert_eq!( config.cluster.connect, vec![Peer::new("https://root.example.com:4443/")] ); } + /// A TOML `mesh` in either released type is refused by name at load, so a + /// config file that relied on gossip stops instead of starting without peers. + #[test] + fn toml_mesh_is_refused() { + // Usage reads the environment while parsing, so serialize with the tests + // that mutate it. + let _env = crate::test_env::EnvGuard::lock(); + + let dir = std::env::temp_dir().join("moq-relay-cluster-test"); + std::fs::create_dir_all(&dir).unwrap(); + for (name, value) in [("bool", "true"), ("url", "\"us-east.example.com:4443\"")] { + let path = dir.join(format!("cluster-mesh-{name}-toml.toml")); + std::fs::write(&path, format!("[cluster]\nmesh = {value}\n")).unwrap(); + + let args = vec![std::ffi::OsString::from("moq-relay"), std::ffi::OsString::from(&path)]; + let err = RelayConfig::parse_and_merge(args).expect_err("mesh must be refused"); + assert!(err.to_string().contains("--cluster-mesh"), "{name}: {err}"); + } + } + /// Static config accepts the object form beside bare URLs, through the same /// type the connect API parses. #[test] @@ -3158,20 +2663,6 @@ mod tests { assert_eq!(desired.len(), 2); } - /// The legacy `--cluster-mesh ` form (now a boolean) is honored for - /// backwards compatibility: it enables gossip and supplies the node URL. - #[tokio::test] - async fn legacy_mesh_url_enables_gossip_as_node() { - let cluster = new_cluster(Config { - mesh: Some("rendezvous.example.com:4443".to_string()), - ..Default::default() - }) - .unwrap(); - let (gossip, node) = cluster.resolve_mesh().expect("legacy mesh url resolves"); - assert!(gossip); - assert_eq!(node.as_deref(), Some("rendezvous.example.com:4443")); - } - /// `--cluster-connect` accepts a full URL verbatim (preserving its `?jwt=`) /// and falls back to wrapping a bare host / `host:port` in `https://.../`. #[test] @@ -3220,117 +2711,6 @@ mod tests { assert!(!format!("{err:#}").contains("top-secret")); } - /// What a discovering relay reads off `announced()` for this node. - fn advertised(node: &str) -> String { - Path::new(MESH_PREFIX) - .join(node) - .as_str() - .strip_prefix(&format!("{MESH_PREFIX}/")) - .expect("advertised under the mesh prefix") - .to_owned() - } - - /// A node URL is advertised as a broadcast path, which collapses the `//` after - /// the scheme. It has to come back as the same address anyway, or every - /// gossip-discovered peer is dialed as the hostname `https`. - #[test] - fn a_node_url_survives_a_broadcast_path() { - for node in [ - "https://a.example/", - "https://b.example:4443/", - "tcp://c.example:4443", - "https://d.example/?cost=7", - "https://e.example/deep/path", - // Legacy bare forms, which carry no scheme and default to https. - "rendezvous.example.com:4443", - "cdn.example.com", - ] { - let dialed = advertised_node_url(&advertised(node)); - assert_eq!( - peer_url(&dialed).unwrap(), - peer_url(node).unwrap(), - "{node} did not survive a round trip through a broadcast path" - ); - } - } - - /// The dialed address keeps its query. `run_remote` reads `?cost=` off it to - /// price the link, so canonicalizing first (which drops the query) would leave - /// every gossip-discovered link silently at the default cost. - #[test] - fn an_advertised_url_keeps_the_query_it_is_dialed_with() { - let dialed = advertised_node_url(&advertised("https://a.example/?cost=10")); - assert_eq!(dialed, "https://a.example/?cost=10"); - - // The value has to reach where `run_remote` reads it. - let mut url = peer_url(&dialed).unwrap(); - assert_eq!(take_cost(&mut url).unwrap(), Some(10)); - assert_eq!(url.as_str(), "https://a.example/"); - } - - /// The colon that ends a scheme is the only signal, so a bare `host:port` (whose - /// colon sits mid-segment) must not be read as one. - #[test] - fn a_bare_host_port_is_not_read_as_a_scheme() { - assert_eq!( - advertised_node_url("rendezvous.example.com:4443"), - "rendezvous.example.com:4443" - ); - assert_eq!( - canonicalize_peer_key(&advertised_node_url("rendezvous.example.com:4443")), - "https://rendezvous.example.com:4443/" - ); - } - - /// What a discovering relay reads off an mDNS record for this node, mirroring - /// [`lan_discovery`] and `moq_tokio::mdns::Config::with_node`. - fn advertised_lan(node: &str) -> String { - let mut url = peer_url(node).expect("valid node"); - url.set_fragment(None); - url.set_username("").ok(); - url.set_password(None).ok(); - url.to_string() - } - - /// The two discovery paths must land on the same peer key, or one relay gets - /// two [`DialMap`] entries and is dialed twice. This is self-triggering: the - /// session the mDNS dial opens is what carries the peer's gossip - /// advertisement, so the second dial follows the first. - /// - /// Gossip round-trips the node URL through a [`Path`] (slashes trimmed and - /// collapsed) while mDNS strips the fragment and userinfo, so the key has to - /// absorb both. The realistic trigger is a trailing slash: `moqt` is not a - /// special scheme, so `Url` keeps one that `Path` would have dropped. - #[test] - fn gossip_and_mdns_agree_on_a_peer_key() { - for node in [ - "moqt://a.example:4443/", - "https://a.example/edge/", - "https://a.example/#pos", - "https://user:pw@a.example/", - // Controls: spellings both paths already agreed on. - "https://a.example/", - "https://b.example:4443/deep/path", - "tcp://c.example:4443", - "rendezvous.example.com:4443", - ] { - let gossip = canonicalize_peer_key(&advertised_node_url(&advertised(node))); - let mdns = canonicalize_peer_key(&advertised_lan(node)); - assert_eq!(gossip, mdns, "{node} has two peer keys, so it is dialed twice"); - } - } - - /// With both sides canonical, exactly one of a pair dials. - #[test] - fn gossiped_urls_keep_the_tiebreaker_symmetric() { - let a = canonicalize_peer_key("https://a.example/"); - let b = canonicalize_peer_key(&advertised_node_url("https:/b.example")); - assert!( - should_dial(&a, &b) != should_dial(&b, &a), - "exactly one side of a pair must dial" - ); - } - /// The same relay spelled as a bare `host:port`, a full URL, or a URL with an /// inline jwt all canonicalize to one key, so they share a single dial entry. #[tokio::test] @@ -3353,20 +2733,6 @@ mod tests { assert_ne!(canonicalize_peer_key("host:4443"), canonicalize_peer_key("host:5555")); } - /// A legacy mesh URL that disagrees with an explicit `--cluster-node` is a - /// conflict, not a silent pick. - #[tokio::test] - async fn legacy_mesh_url_conflicting_with_node_errors() { - let cluster = new_cluster(Config { - mesh: Some("a.example.com:4443".to_string()), - node: Some("b.example.com:4443".to_string()), - ..Default::default() - }) - .unwrap(); - let err = cluster.resolve_mesh().expect_err("conflict should error"); - assert!(format!("{err}").contains("conflicts with"), "got: {err}"); - } - /// The nested `[cluster.lan]` table survives the TOML-to-CLI merge. #[cfg(feature = "cluster-lan")] #[test] diff --git a/rs/moq-relay/src/connection.rs b/rs/moq-relay/src/connection.rs index 8d5e460c849..96eb782d95e 100644 --- a/rs/moq-relay/src/connection.rs +++ b/rs/moq-relay/src/connection.rs @@ -79,7 +79,6 @@ impl Connection { /// Admits and serves this connection until it closes. #[tracing::instrument("conn", skip_all, fields(id = self.id, remote = self.request.remote_addr().map(tracing::field::display), session = tracing::field::Empty))] pub async fn run(self) -> anyhow::Result<()> { - let peer_hop = self.request.peer_hop(); let (lease, registration) = match self.admit().await { Ok(admitted) => admitted, Err(err) => { @@ -120,7 +119,6 @@ impl Connection { request = request.with_subscriber(publish); } let session = request.ok().await?; - let _node_connection = peer_hop.map(|origin| self.cluster.nodes.connect_inbound(self.id, origin)); tracing::info!(version = %session.version(), %transport, "negotiated"); @@ -201,8 +199,8 @@ pub(crate) struct Grants { /// `cluster_peer` marks an authenticated cluster peer (a verified client /// certificate or the LAN credential), which discovers hidden routes whether /// or not it asks. A peer that predates the hidden opt-in (below moq-lite-07-wip, -/// or moq-transport without MoQ Hidden) would otherwise lose `.internal/origins` -/// and every other dot path during a rolling upgrade. +/// or moq-transport without MoQ Hidden) would otherwise lose every dot path +/// during a rolling upgrade. // TODO: drop the exemption once deployed peers all opt in. pub(crate) fn authorize( cluster: &cluster::Cluster, diff --git a/rs/moq-relay/src/internal.rs b/rs/moq-relay/src/internal.rs index fa97f3dfc8b..906881b13d4 100644 --- a/rs/moq-relay/src/internal.rs +++ b/rs/moq-relay/src/internal.rs @@ -17,8 +17,7 @@ //! crossing it, so they have no place on the `moq-stats` wire. //! - `/health` - a liveness mirror of the public probe, for internal checks //! that don't want to hit the customer port. -//! - `/nodes` - the cluster nodes visible through gossip plus established -//! direct relay connections. +//! - `/nodes` - the cluster peers this relay dialed and holds a session with. //! - `/sessions` and `/sessions/revalidate` - list or nudge live sessions on //! this node. A push only causes a re-check, so a caller on this trusted //! plane gains nothing a scheduled cadence would not do. @@ -292,11 +291,8 @@ async fn serve_metrics(State(state): State) -> Response { ([(http::header::CONTENT_TYPE, "text/plain; version=0.0.4")], body).into_response() } -/// Cluster nodes currently visible through gossip or a direct outbound dial. -/// -/// Inbound connections appear only after their SETUP origin identity resolves -/// to a unique `.internal/origins` node advertisement. Sessions without a -/// unique match are omitted. +/// Cluster peers this relay dialed and currently holds a session with. Accepted +/// peer sessions are omitted, since a peer declares no URL to list it under. async fn serve_nodes(State(state): State) -> Json { Json(state.nodes.map(|nodes| nodes.snapshot()).unwrap_or_default()) } @@ -875,8 +871,7 @@ mod tests { #[tokio::test] async fn nodes_endpoint_uses_the_attached_cluster_registry() { - let origin = moq_tokio::origin::spawn_config(moq_net::origin::Config::new(moq_net::Hop::new(100).unwrap())); - let nodes = crate::nodes::Nodes::new(origin); + let nodes = crate::nodes::Nodes::default(); let _connection = nodes.connect_outbound(0, "https://relay-b.example/"); let state = InternalState { stats: moq_net::stats::Registry::disabled(), diff --git a/rs/moq-relay/src/nodes.rs b/rs/moq-relay/src/nodes.rs index 28bf31ab77b..3a0596fde5e 100644 --- a/rs/moq-relay/src/nodes.rs +++ b/rs/moq-relay/src/nodes.rs @@ -1,253 +1,84 @@ -//! The local cluster topology view behind the internal `/nodes` endpoint. +//! The local cluster view behind the internal `/nodes` endpoint. //! -//! Combines the node advertisements gossiped under [`MESH_PREFIX`] with the -//! direct relay sessions this process currently holds, so an operator can see -//! which peers are visible, which are connected, and who dialed whom. +//! Lists the peers this relay dialed and currently holds a session with, keyed +//! by the URL it dialed. Accepted peer sessions are not listed: a peer declares +//! no URL, so there is nothing to name it by. use std::{ collections::{BTreeMap, HashMap}, sync::{Arc, Mutex}, }; -use moq_net::{Hop, origin}; use serde::Serialize; -/// Namespace containing the empty broadcasts used to advertise cluster nodes. -pub(crate) const MESH_PREFIX: &str = ".internal/origins"; - -/// A local view of announced cluster nodes and established direct connections. -#[derive(Clone)] +/// Established outbound cluster connections, by `conn` id. +#[derive(Clone, Default)] pub(crate) struct Nodes { - origin: origin::Producer, - connections: Arc, -} - -#[derive(Default)] -struct Connections { - entries: Mutex>, -} - -#[derive(Clone)] -struct ConnectionRecord { - direction: Direction, - target: ConnectionTarget, -} - -#[derive(Clone)] -enum ConnectionTarget { - Node(String), - Hop(Hop), + connections: Arc>>, } /// The JSON document returned by the internal `/nodes` endpoint. #[derive(Debug, Default, Serialize)] pub(crate) struct Snapshot { - /// Announced or directly connected cluster nodes. + /// Dialed cluster nodes with a live session. pub nodes: Vec, } -/// One known cluster node in the local topology view. +/// One dialed cluster node. #[derive(Debug, Serialize)] pub(crate) struct Node { - /// Canonical URL advertised for the node. + /// Canonical URL this relay dialed, without its query. pub node: String, - /// Hop identity from the node's announcement, when available. - pub origin_id: Option, - /// Selected route for the node's internal advertisement. - pub announced: Option, - /// Established direct connections to this node. + /// Established connections to this node. pub connections: Vec, } -/// The selected route for a node advertisement. -#[derive(Debug, Serialize)] -pub(crate) struct Announcement { - /// Hop identities in traversal order, oldest first. - pub hops: Vec, - /// Number of hops in the selected route. - pub hop_count: usize, - /// Accumulated cost of the selected route as the mesh stands: zero at any relay - /// already carrying the broadcast. - pub cost: u64, - /// The same route priced with every warm discount removed, which is what ranks - /// two relays that both discounted to zero. - pub cold_cost: u64, -} - -/// An established direct cluster connection. +/// An established outbound cluster connection. #[derive(Debug, Serialize)] pub(crate) struct Connection { /// The session's `conn` id, matching the `conn{id}` span its log lines carry. /// Process-local, and only meaningful while the session lasts. pub id: u64, - /// Whether this relay accepted or initiated the connection. - pub direction: Direction, -} - -/// Direction of an established cluster connection. -#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)] -#[serde(rename_all = "lowercase")] -pub(crate) enum Direction { - /// A connection accepted from another relay. - Inbound, - /// A connection initiated by this relay. - Outbound, -} - -struct NodeBuilder { - origin_id: Option, - announced: Option, - connections: Vec, -} - -/// The advertisements one scan of the discovery namespace turned up. -#[derive(Default)] -struct Announced { - nodes: BTreeMap, - /// Hop id to the single node advertising it, or `None` once more than one - /// does and the id no longer identifies a peer. - origins: HashMap>, } -/// Removes a live connection from the topology view when its session ends. +/// Removes a live connection from the view when its session ends. pub(crate) struct ConnectionGuard { nodes: Nodes, id: u64, } impl Nodes { - pub(crate) fn new(origin: origin::Producer) -> Self { - Self { - origin, - connections: Arc::default(), - } - } - /// Record a dial this relay initiated, keyed by the URL it dialed. /// /// `id` is the session's `conn` id from /// [`Cluster::next_connection_id`](crate::cluster::Cluster::next_connection_id). pub(crate) fn connect_outbound(&self, id: u64, node: impl Into) -> ConnectionGuard { - self.connect(id, Direction::Outbound, ConnectionTarget::Node(node.into())) - } - - /// Record a session this relay accepted, keyed by the origin the peer declared. - /// - /// `id` is the session's `conn` id from - /// [`Cluster::next_connection_id`](crate::cluster::Cluster::next_connection_id). - pub(crate) fn connect_inbound(&self, id: u64, origin: Hop) -> ConnectionGuard { - self.connect(id, Direction::Inbound, ConnectionTarget::Hop(origin)) - } - - fn connect(&self, id: u64, direction: Direction, target: ConnectionTarget) -> ConnectionGuard { self.connections - .entries .lock() .expect("node connection registry poisoned") - .insert(id, ConnectionRecord { direction, target }); + .insert(id, node.into()); ConnectionGuard { nodes: self.clone(), id, } } - /// The node advertisements currently visible under [`MESH_PREFIX`]. - fn announced(&self) -> Announced { - match self - .origin - .consume() - .scope(MESH_PREFIX, &moq_net::Patterns::from(moq_net::Pattern::all())) - { - Ok(consumer) => self.scan_announced(&mut consumer.announced()), - Err(_) => Announced::default(), - } - } - - /// Drain every update the cursor has buffered into a node map. - fn scan_announced(&self, announced: &mut moq_net::announce::Consumer) -> Announced { - let mut scanned = Announced::default(); - - while let Some(update) = announced.try_next() { - // A retraction can land mid-drain (a re-announce is a metadata update, - // not a retract-and-announce). Skip it rather than end the scan, which - // would drop every node still queued behind it. - if !update.kind.is_active() { - continue; - } - - let key = canonical_announced_node(update.prefix.as_str()); - let route = update.route; - let hop_ids = route.hops.iter().map(|origin| origin.id()).collect::>(); - // An advertisement with no hops never crossed a link, so it is our own. - let origin_id = hop_ids.first().copied().unwrap_or_else(|| self.origin.hop().id()); - - scanned - .origins - .entry(origin_id) - .and_modify(|current| { - if current.as_deref() != Some(&key) { - *current = None; - } - }) - .or_insert_with(|| Some(key.clone())); - - scanned.nodes.insert( - key, - NodeBuilder { - origin_id: Some(origin_id.to_string()), - announced: Some(Announcement { - hop_count: hop_ids.len(), - hops: hop_ids.into_iter().map(|origin| origin.to_string()).collect(), - cost: route.cost.warm, - cold_cost: route.cost.cold, - }), - connections: Vec::new(), - }, - ); - } - - scanned - } - pub(crate) fn snapshot(&self) -> Snapshot { - let Announced { mut nodes, origins } = self.announced(); - - let connections = self - .connections - .entries - .lock() - .expect("node connection registry poisoned"); - let mut connections = connections.iter().collect::>(); - connections.sort_by_key(|(id, _)| **id); - for (&id, connection) in connections { - let key = match &connection.target { - ConnectionTarget::Node(node) => canonical_node(node), - ConnectionTarget::Hop(origin) => { - let Some(Some(node)) = origins.get(&origin.id()) else { - continue; - }; - node.clone() - } - }; - let node = nodes.entry(key).or_insert_with(|| NodeBuilder { - origin_id: None, - announced: None, - connections: Vec::new(), - }); - node.connections.push(Connection { - id, - direction: connection.direction, - }); + let mut nodes = BTreeMap::>::new(); + let connections = self.connections.lock().expect("node connection registry poisoned"); + for (&id, node) in connections.iter() { + nodes + .entry(crate::cluster::canonicalize_peer_key(node)) + .or_default() + .push(Connection { id }); } Snapshot { nodes: nodes .into_iter() - .map(|(key, node)| Node { - node: key, - origin_id: node.origin_id, - announced: node.announced, - connections: node.connections, + .map(|(node, mut connections)| { + connections.sort_by_key(|connection| connection.id); + Node { node, connections } }) .collect(), } @@ -258,97 +89,37 @@ impl Drop for ConnectionGuard { fn drop(&mut self) { self.nodes .connections - .entries .lock() .expect("node connection registry poisoned") .remove(&self.id); } } -fn canonical_node(node: &str) -> String { - crate::cluster::canonicalize_peer_key(node) -} - -fn canonical_announced_node(node: &str) -> String { - canonical_node(&crate::cluster::advertised_node_url(node)) -} - #[cfg(test)] mod tests { use super::*; - use moq_net::{Hop, Hops}; - - async fn announced_node( - origin: &moq_net::origin::Producer, - node: &str, - hops: &[u64], - cost: u64, - ) -> moq_net::origin::Dynamic { - let hops = Hops::try_from( - hops.iter() - .map(|id| Hop::new(*id).expect("valid test origin")) - .collect::>(), - ) - .unwrap(); - let path = moq_net::Path::new(MESH_PREFIX).join(node); - let announcement = origin - .dynamic(&path, moq_net::origin::Route::default().with_hops(hops).with_cost(cost)) - .unwrap(); - origin.consume().routed(&path).await.expect("test node announced"); - announcement - } - - #[tokio::test] - async fn snapshot_combines_announcements_and_live_connections() { - const REMOTE_ID: u64 = 9_007_199_254_740_993; - let origin = moq_tokio::origin::spawn_config(moq_net::origin::Config::new(Hop::new(100).unwrap())); - let nodes = Nodes::new(origin.clone()); - let _remote = announced_node(&origin, "https://relay-b.example/", &[REMOTE_ID], 7).await; - let _outbound = nodes.connect_outbound(0, "https://relay-b.example/"); - let _inbound = nodes.connect_inbound(1, Hop::new(REMOTE_ID).unwrap()); + #[test] + fn snapshot_groups_live_connections_by_node() { + let nodes = Nodes::default(); + let _second = nodes.connect_outbound(1, "https://relay-b.example/"); + let _first = nodes.connect_outbound(0, "https://relay-b.example"); + let _other = nodes.connect_outbound(2, "https://relay-a.example/"); - let snapshot = nodes.snapshot(); - assert_eq!(snapshot.nodes.len(), 1); - let node = &snapshot.nodes[0]; - assert_eq!(node.node, "https://relay-b.example/"); - assert_eq!(node.origin_id.as_deref(), Some("9007199254740993")); - assert_eq!(node.announced.as_ref().unwrap().hops, vec!["9007199254740993"]); - assert_eq!(node.announced.as_ref().unwrap().hop_count, 1); - assert_eq!(node.announced.as_ref().unwrap().cost, 7); - assert_eq!(node.announced.as_ref().unwrap().cold_cost, 7); - assert_eq!(node.connections.len(), 2); - assert_eq!(node.connections[0].direction, Direction::Outbound); - assert_eq!(node.connections[1].direction, Direction::Inbound); assert_eq!( - serde_json::to_value(&snapshot).unwrap(), + serde_json::to_value(nodes.snapshot()).unwrap(), serde_json::json!({ - "nodes": [{ - "node": "https://relay-b.example/", - "origin_id": "9007199254740993", - "announced": { "hops": ["9007199254740993"], "hop_count": 1, "cost": 7, "cold_cost": 7 }, - "connections": [ - { "id": 0, "direction": "outbound" }, - { "id": 1, "direction": "inbound" } - ] - }] + "nodes": [ + { "node": "https://relay-a.example/", "connections": [{ "id": 2 }] }, + { "node": "https://relay-b.example/", "connections": [{ "id": 0 }, { "id": 1 }] } + ] }), ); } - #[tokio::test] - async fn snapshot_omits_unresolved_inbound_connections() { - let origin = moq_tokio::origin::spawn_config(moq_net::origin::Config::new(Hop::new(100).unwrap())); - let nodes = Nodes::new(origin); - let _inbound = nodes.connect_inbound(0, Hop::new(200).unwrap()); - - assert!(nodes.snapshot().nodes.is_empty()); - } - - #[tokio::test] - async fn snapshot_stops_reporting_closed_outbound_connections() { - let origin = moq_tokio::origin::spawn_config(moq_net::origin::Config::new(Hop::new(100).unwrap())); - let nodes = Nodes::new(origin); + #[test] + fn snapshot_stops_reporting_closed_outbound_connections() { + let nodes = Nodes::default(); let connection = nodes.connect_outbound(0, "https://relay-b.example/"); assert_eq!(nodes.snapshot().nodes.len(), 1); @@ -356,58 +127,11 @@ mod tests { assert!(nodes.snapshot().nodes.is_empty()); } - #[tokio::test] - async fn outbound_node_omits_credentials_from_url() { - let origin = moq_tokio::origin::spawn_config(moq_net::origin::Config::new(Hop::new(100).unwrap())); - let nodes = Nodes::new(origin); + #[test] + fn outbound_node_omits_credentials_from_url() { + let nodes = Nodes::default(); let _connection = nodes.connect_outbound(0, "https://relay-b.example/?jwt=secret"); assert_eq!(nodes.snapshot().nodes[0].node, "https://relay-b.example/"); } - - /// A re-announce reaches the cursor as unannounce-then-announce, so a bare - /// unannounce can sit ahead of nodes still queued behind it. Treating that as - /// the end of the scan would silently truncate `/nodes` whenever the cluster - /// churned mid-request. - #[tokio::test(start_paused = true)] - async fn scan_skips_an_unannounce_queued_ahead_of_another_node() { - let origin = moq_tokio::origin::spawn_config(moq_net::origin::Config::new(Hop::new(100).unwrap())); - let nodes = Nodes::new(origin.clone()); - let first = announced_node(&origin, "https://relay-a.example/", &[200], 1).await; - let _second = announced_node(&origin, "https://relay-b.example/", &[300], 1).await; - - let consumer = origin - .consume() - .scope(MESH_PREFIX, &moq_net::Patterns::from(moq_net::Pattern::all())) - .expect("mesh prefix is in root"); - let mut announced = consumer.announced(); - - // Take relay-a's replayed announce, then retire it so the cursor queues a - // bare unannounce ahead of relay-b's still-pending announce. - let first_update = announced.try_next().expect("replayed announce"); - assert_eq!( - canonical_announced_node(first_update.prefix.as_str()), - "https://relay-a.example/" - ); - drop(first); - - let scanned = nodes.scan_announced(&mut announced); - assert!( - scanned.nodes.contains_key("https://relay-b.example/"), - "the unannounce ahead of relay-b truncated the scan" - ); - } - - #[tokio::test] - async fn duplicate_origin_ids_do_not_resolve_inbound_connections() { - let origin = moq_tokio::origin::spawn_config(moq_net::origin::Config::new(Hop::new(100).unwrap())); - let nodes = Nodes::new(origin.clone()); - let _first = announced_node(&origin, "https://relay-b.example/", &[200], 1).await; - let _second = announced_node(&origin, "https://relay-c.example/", &[200], 1).await; - let _inbound = nodes.connect_inbound(0, Hop::new(200).unwrap()); - - let snapshot = nodes.snapshot(); - assert_eq!(snapshot.nodes.len(), 2); - assert!(snapshot.nodes.iter().all(|node| node.connections.is_empty())); - } } diff --git a/rs/moq-relay/src/uring.rs b/rs/moq-relay/src/uring.rs index 2583ac43deb..9e6766f4f69 100644 --- a/rs/moq-relay/src/uring.rs +++ b/rs/moq-relay/src/uring.rs @@ -762,7 +762,6 @@ async fn serve_connection( } }; - let peer_hop = request.peer_hop(); let lease = lease.with_stats(grants.stats.clone()); let mut request = request.with_stats(grants.stats); if let Some(subscribe) = grants.subscribe { @@ -779,7 +778,6 @@ async fn serve_connection( err => tracing::debug!(%err, "session driver ended"), } }); - let node_connection = peer_hop.map(|origin| serve.cluster.nodes.connect_inbound(id, origin)); tracing::info!(id, version = %session.version(), transport = %moq_tokio::server::Transport::Quic, "negotiated"); @@ -788,7 +786,6 @@ async fn serve_connection( // and the shutdown broadcast on the shared runtime. let shutdown = serve.shutdown.clone(); serve.tokio.spawn(async move { - let _node_connection = node_connection; if let Err(err) = crate::connection::supervise(session, lease, shutdown, registration).await { tracing::warn!(id, %err, "connection closed"); } diff --git a/rs/moq-relay/src/web.rs b/rs/moq-relay/src/web.rs index b5e09791ed3..7b5e20b0592 100644 --- a/rs/moq-relay/src/web.rs +++ b/rs/moq-relay/src/web.rs @@ -917,7 +917,7 @@ async fn serve_fetch( let result = tokio::time::timeout_at(deadline, async { // NOTE: The auth token is already scoped to the broadcast. // Block until a route covers the broadcast (within the fetch deadline) so - // freshly-connected subscribers don't get a spurious 404 before gossip arrives. + // freshly-connected subscribers don't get a spurious 404 before the announce arrives. let consumer = origin.consume(); let broadcast = consumer.routed_broadcast("").await.map_err(|_| StatusCode::NOT_FOUND)?; let sequence = match params.group { diff --git a/rs/moq-relay/tests/cluster_unknown.rs b/rs/moq-relay/tests/cluster_unknown.rs index 8bad8f13a8a..090e51ffc93 100644 --- a/rs/moq-relay/tests/cluster_unknown.rs +++ b/rs/moq-relay/tests/cluster_unknown.rs @@ -1,6 +1,6 @@ //! Regression for an external publisher whose protocol does not declare a Hop ID. //! The relay stamps that publisher with a random Hop ID of the connection's own; -//! reflected cluster paths must not replace it while gossiping around a redundant mesh. +//! reflected cluster paths must not replace it while propagating around a redundant mesh. use std::time::Duration; diff --git a/rs/moq-relay/tests/hidden_cluster.rs b/rs/moq-relay/tests/hidden_cluster.rs index e49437910f1..8bfef7266ea 100644 --- a/rs/moq-relay/tests/hidden_cluster.rs +++ b/rs/moq-relay/tests/hidden_cluster.rs @@ -1,5 +1,5 @@ //! A cluster peer that predates the hidden opt-in still discovers the relay's -//! `.`-named broadcasts, so a mixed-version mesh keeps `.internal/origins`. +//! `.`-named broadcasts, so a mixed-version mesh keeps its hidden paths. use std::time::Duration; @@ -69,16 +69,13 @@ async fn old_peer_keeps_hidden_paths(version: moq_net::Version) { let cluster = cluster::Cluster::new(cluster::Options::new(cluster_config)) .expect("cluster init") .with_client(client); - let node = cluster - .origin - .create_broadcast(".internal/origins/test") - .expect("create hidden"); + let node = cluster.origin.create_broadcast(".hidden/test").expect("create hidden"); node.announce(Default::default()).expect("announce hidden"); let cluster_run = tokio::spawn(cluster.clone().start().await.expect("cluster start").run()); loop { let update = discovered.next().await.expect("peer origin closed"); - if update.kind.is_active() && update.prefix.as_str() == ".internal/origins/test" { + if update.kind.is_active() && update.prefix.as_str() == ".hidden/test" { break; } } From cb65fb0e8b75a6547acbd3dcf83fcdfd041ed026 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 12:41:38 -0700 Subject: [PATCH 113/128] fix(net): prune departed subscribers when registering a new one (#4604) Co-authored-by: Claude Opus 5.5 --- quest/m0/README.md | 1 - quest/m0/subscriber-prune.md | 19 ---------- rs/moq-net/benches/track.rs | 71 ++++++++++++++++++++++++++++++++++- rs/moq-net/src/model/track.rs | 31 ++++++++++++++- 4 files changed, 99 insertions(+), 23 deletions(-) delete mode 100644 quest/m0/subscriber-prune.md diff --git a/quest/m0/README.md b/quest/m0/README.md index a384f0eefad..8263867ee71 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -50,7 +50,6 @@ Published API or wire breaks still land on dev; each quest's Plan says so. - [Shared fronts](/quest/m0/shared-fronts.md) - viewer sessions share a front, so fronts scale with peers, not viewers - [Frame alloc budget](/quest/m0/frame-alloc-budget.md) - frame buffers pre-allocate within a per-session budget and otherwise grow with bytes received - [Handshake deadline](/quest/m0/handshake-deadline.md) - an unfinished handshake or slow HTTP header times out -- [Subscriber prune](/quest/m0/subscriber-prune.md) - a track's subscription list holds only live subscribers - [Revalidate overflow](/quest/m0/revalidate-overflow.md) - no auth duration can overflow a deadline and abort the relay - [Wildcard](/quest/m0/wildcard/README.md) - a relay resolves subscriptions against advertised prefixes, a service claims the prefix it could serve and refuses the rest instead of enumerating broadcasts, and the browser player treats a covering claim as availability - [Audio quality harness](/quest/m0/audio-quality-harness/README.md) - a browser playout latency regression fails a nightly run instead of arriving as a bug report, and its recorder supplies the jitter target's replay traces diff --git a/quest/m0/subscriber-prune.md b/quest/m0/subscriber-prune.md deleted file mode 100644 index eecffd3dce6..00000000000 --- a/quest/m0/subscriber-prune.md +++ /dev/null @@ -1,19 +0,0 @@ -# [XS] A track drops departed subscribers - -## Goal - -A track's subscription list holds only live subscribers. Today -`register_subscription` (`model/track.rs`) pushes without pruning, and closed -entries are only removed when the aggregate changes. While at least one -viewer stays, churning viewers with identical preferences accumulate, and -`combined_subscription` walks all of them on every wake. - -## Plan - -- Remove an entry when its subscriber drops, or `retain` live entries on push - and on each poll, whichever keeps the wake path cheapest. -- A unit test that churns identical subscribers under one steady viewer and - asserts the list length stays bounded. -- A benchmark swept over steady viewers and churn rate. - -Public API: none. Wire: none. diff --git a/rs/moq-net/benches/track.rs b/rs/moq-net/benches/track.rs index 55926989962..79e4043bd24 100644 --- a/rs/moq-net/benches/track.rs +++ b/rs/moq-net/benches/track.rs @@ -7,6 +7,10 @@ //! `track_aborted_scan` isolates the other half of delivery: how much a cached //! prefix of aborted groups costs the scan that has to walk past it. //! +//! `track_subscriber_churn` measures viewers joining and leaving beside steady ones: +//! each departure wakes the producer's aggregate poll, which walks the subscription +//! list, so departed entries left in the list show up as a slope over churn. +//! //! Run with `cargo bench -p moq-net --bench track`. use std::hint::black_box; @@ -15,7 +19,7 @@ use std::task::Poll; use std::time::{Duration, Instant}; use bytes::Bytes; -use criterion::{BenchmarkId, Criterion, Throughput, criterion_group, criterion_main}; +use criterion::{BatchSize, BenchmarkId, Criterion, Throughput, criterion_group, criterion_main}; use moq_net::{Error, Timestamp, broadcast, cache, track}; /// Fanout sizes spanning a direct viewer, a small room, and a large room. @@ -30,6 +34,12 @@ const PAYLOAD: usize = 64; /// Small enough to reach steady-state eviction during Criterion warm-up. const CACHE_CAPACITY: u64 = 64 * 1024; +/// Steady viewers that stay subscribed while others churn. +const STEADY: [usize; 3] = [1, 8, 64]; + +/// Viewers that join and leave, one at a time, during one measured run. +const CHURN: [usize; 3] = [8, 64, 512]; + /// Concurrent publishers sharing one relay-style cache pool. const WRITERS: [usize; 4] = [1, 2, 4, 8]; @@ -123,6 +133,40 @@ impl AbortedScan { } } +/// Steady viewers on one track, with the producer's aggregate poll caught up. +struct Churn { + _broadcast: broadcast::Producer, + track: track::Producer, + _steady: Vec, + waiter: kio::Waiter, +} + +impl Churn { + fn new(steady: usize) -> Self { + let broadcast = broadcast::Info::default().produce(); + let mut track = broadcast.create_track("bench", None).unwrap(); + let steady = (0..steady).map(|_| track.subscribe(None)).collect(); + let waiter = kio::Waiter::noop(); + assert!(track.poll_subscription_changed(&waiter).is_ready()); + + Self { + _broadcast: broadcast, + track, + _steady: steady, + waiter, + } + } + + /// Join and leave `churn` times with the steady viewers' preferences, polling the + /// aggregate after each departure the way a relay forwarding demand upstream does. + fn run(&mut self, churn: usize) { + for _ in 0..churn { + drop(self.track.subscribe(None)); + assert!(self.track.poll_subscription_changed(&self.waiter).is_pending()); + } + } +} + fn bench_fanout(c: &mut Criterion) { let mut group = c.benchmark_group("track_fanout_group"); for subscribers in FANOUT { @@ -206,5 +250,28 @@ fn bench_aborted_scan(c: &mut Criterion) { group.finish(); } -criterion_group!(benches, bench_fanout, bench_parallel_write, bench_aborted_scan); +fn bench_subscriber_churn(c: &mut Criterion) { + let mut group = c.benchmark_group("track_subscriber_churn"); + for steady in STEADY { + for churn in CHURN { + group.throughput(Throughput::Elements(churn as u64)); + group.bench_with_input( + BenchmarkId::new(format!("steady_{steady}"), churn), + &churn, + |b, &churn| { + b.iter_batched_ref(|| Churn::new(steady), |setup| setup.run(churn), BatchSize::SmallInput); + }, + ); + } + } + group.finish(); +} + +criterion_group!( + benches, + bench_fanout, + bench_parallel_write, + bench_aborted_scan, + bench_subscriber_churn +); criterion_main!(benches); diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index c3bc6f17b06..96702bb84ce 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -2109,13 +2109,20 @@ fn clamp_combined(combined: Option, bound: Option) -> Op /// Register a subscription if the track is live: clone the shared list out of the /// state, release the track lock, then push under the list's own lock. A closed /// track skips the push; nothing aggregates the preferences anymore. +/// +/// Departed subscribers are pruned here too. The aggregate poll only prunes when the +/// aggregate changes, so churning subscribers with the same preferences as a steady +/// one would otherwise pile up and be walked on every wake. Pruning on push bounds the +/// list by its peak live count, and the push already wakes the pollers. fn register_subscription(state: kio::Ref<'_, TrackState>, subscription: &kio::Producer) { if state.is_closed() { return; } let subs = state.subscriptions.clone(); drop(state); - subs.lock().push(subscription.consume()); + let mut subs = subs.lock(); + subs.retain(|sub| !sub.is_closed()); + subs.push(subscription.consume()); } /// A weak reference to a track that doesn't prevent auto-close. @@ -5563,6 +5570,28 @@ mod test { assert_eq!(producer.subscription().unwrap().max_age, Duration::from_secs(2)); } + #[test] + fn churned_subscribers_do_not_accumulate() { + let mut producer = track_producer("test", None); + let consumer = producer.consume(); + let waiter = kio::Waiter::noop(); + + let _steady = producer.subscribe(None); + assert!(producer.poll_subscription_changed(&waiter).is_ready()); + + // Identical preferences leave the aggregate unchanged, so the poll never + // reaches its own prune; registration has to drop the departed entries. + for _ in 0..100 { + drop(producer.subscribe(None)); + drop(consumer.subscribe(None)); + assert!(producer.poll_subscription_changed(&waiter).is_pending()); + } + + let subs = producer.state.read().subscriptions.clone(); + let len = subs.read().len(); + assert!(len <= 2, "departed subscribers accumulated: {len}"); + } + /// Append a finished group presenting at `millis`, so the track carries a media /// timeline for the drift budget to measure against. fn append_at(producer: &mut Producer, millis: u64) -> u64 { From 58ceaf745e69a25680f26786dd0a64b30bad07c4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 12:47:53 -0700 Subject: [PATCH 114/128] quest(quic): hard-fork quinn in-tree as moq-quic (#4617) Co-authored-by: Claude Opus 5.5 --- quest/m0/noq-reassembly-cap.md | 7 ++- quest/m1/README.md | 2 +- quest/m1/bbr-ack-cleanup.md | 4 ++ quest/m1/perf/README.md | 1 + quest/m1/perf/uring-copies.md | 31 +++++++++++ quest/m1/quic/README.md | 70 +++++++++++-------------- quest/m1/quic/bbr-app-limited-edges.md | 4 ++ quest/m1/quic/bbr-app-limited.md | 11 ++-- quest/m1/quic/fork/README.md | 72 ++++++++++++++++++++++++++ quest/m1/quic/fork/bbr3.md | 37 +++++++++++++ quest/m1/quic/fork/import.md | 31 +++++++++++ quest/m1/quic/fork/stream-slots.md | 26 ++++++++++ quest/m1/quic/fork/switch.md | 32 ++++++++++++ quest/m1/quic/peer-limits.md | 1 + quest/m1/quic/reliable-reset.md | 5 ++ quest/m1/quic/scheduler.md | 6 +++ quest/m1/quic/send-errors.md | 29 +++++++++++ quest/m1/quic/shard.md | 45 ++++++++++++++++ quest/m1/quic/upstream.md | 72 -------------------------- quest/m2/README.md | 6 +-- quest/m2/multipath-spike.md | 64 ----------------------- quest/m2/noq-socket-close.md | 13 +++-- quest/m2/quic-ack-hook.md | 18 +++---- quest/m2/quic-ack-progress.md | 21 ++++---- quest/m2/quic-bbr-loss-parity.md | 4 +- quest/m2/quic-bbr-natural-drain.md | 5 +- quest/m2/quic-careful-resume.md | 5 ++ quest/m2/quic-deadline.md | 6 +-- quest/m2/quic-ecn-measure.md | 4 ++ quest/m2/quic-ecn.md | 5 ++ quest/m2/quic-egress-profile.md | 4 ++ quest/m2/quic-io-boundary.md | 34 ++++++++++++ quest/m2/quic-keep-alive.md | 9 +++- quest/m2/quic-probe.md | 6 +++ quest/m2/quic-qmux.md | 63 ++++++++++++++-------- quest/m3/quic-gcc.md | 5 ++ quest/m3/quic-receive-ts.md | 1 + 37 files changed, 517 insertions(+), 242 deletions(-) create mode 100644 quest/m1/perf/uring-copies.md create mode 100644 quest/m1/quic/fork/README.md create mode 100644 quest/m1/quic/fork/bbr3.md create mode 100644 quest/m1/quic/fork/import.md create mode 100644 quest/m1/quic/fork/stream-slots.md create mode 100644 quest/m1/quic/fork/switch.md create mode 100644 quest/m1/quic/send-errors.md create mode 100644 quest/m1/quic/shard.md delete mode 100644 quest/m1/quic/upstream.md delete mode 100644 quest/m2/multipath-spike.md create mode 100644 quest/m2/quic-io-boundary.md diff --git a/quest/m0/noq-reassembly-cap.md b/quest/m0/noq-reassembly-cap.md index 160d9c08f72..cc4a200a020 100644 --- a/quest/m0/noq-reassembly-cap.md +++ b/quest/m0/noq-reassembly-cap.md @@ -20,7 +20,8 @@ the crates are renamed. and #22: fold the port into those releases or take the next patch numbers, then bump the pins here. - Open the same port as a PR on n0-computer/noq (approved 2026-09-29; the - advisory is public). iroh builds stay on the unfixed upstream crate until + advisory is public; opened as + [noq#828](https://github.com/n0-computer/noq/pull/828)). iroh builds stay on the unfixed upstream crate until n0 releases it; bump when they do. - Give `moq-tokio` a finite default connection `receive_window` instead of the backend's `VarInt::MAX` (`rs/moq-tokio/src/noq.rs` `apply_windows`, @@ -32,6 +33,10 @@ the crates are renamed. - `rs/moq-uring` depends on `moq-noq-proto` too, so the same pin bump covers the io_uring workers. +The in-tree [fork](/quest/m1/quic/fork/README.md) inherits the cap from +quinn main, so after it lands only the receive-window default and iroh's noq +pin remain relevant on `dev`. + Public API: none. Wire: a peer that exceeds the chunk cap is closed. ## Related diff --git a/quest/m1/README.md b/quest/m1/README.md index 12f1f067c0a..c74d353d0b0 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -91,7 +91,7 @@ QUIC studies there on that rule. - [Audio rendition pick](/quest/m1/audio-ranked.md) - single-track FLV/RTMP and WHEP serve the best audio rendition, not the first by name - [FLV catalog stream](/quest/m1/flv-catalog-stream.md) - on dev, `flv::Export` takes a catalog stream like fmp4, replacing `with_select` - [io_uring flow control](/quest/m1/uring-flow-control-windows.md) - the relay's io_uring workers honor the QUIC flow-control windows instead of refusing them -- [Own the QUIC stack](/quest/m1/quic/README.md) - the moq-noq fork carries ACK progress, reliable reset, hierarchical scheduling, deadlines, peer limits, and qmux +- [Own the QUIC stack](/quest/m1/quic/README.md) - quinn hard-forked in-tree as `moq-quic`, carrying BBR, reliable reset, hierarchical scheduling, peer limits, and endpoint sharding - [QoS](/quest/m1/qos/README.md) - broadcast health: relay starvation and timeliness histograms, on dev - [Catalog track alias](/quest/m1/catalog-track-alias.md) - catalog rendition keys become aliases with an optional `track` name, so one catalog lists renditions from several broadcasts - [Media stats](/quest/m1/stats/README.md) - publishers announce a stats track in the catalog, viewers answer a soliciting catalog through a per-catalog `.echo` broadcast, and a Rust encoder adapts to them diff --git a/quest/m1/bbr-ack-cleanup.md b/quest/m1/bbr-ack-cleanup.md index bb0db79437a..a0b9db7614b 100644 --- a/quest/m1/bbr-ack-cleanup.md +++ b/quest/m1/bbr-ack-cleanup.md @@ -53,6 +53,10 @@ immutable fork release, and pin the corrected dependency chain here before completing this quest. Do not wait for the broader QUIC stack release. Update internal packet-lifetime comments inline; no new user guide is needed. +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - lands in `moq-quic` on `dev`, not the frozen fork + ## Related - [BBR starvation edges](/quest/m1/quic/bbr-app-limited-edges.md) - also edits `bbr3/mod.rs`; one owner there at a time diff --git a/quest/m1/perf/README.md b/quest/m1/perf/README.md index 4eb4d4ad0fc..dc7aa2ce62a 100644 --- a/quest/m1/perf/README.md +++ b/quest/m1/perf/README.md @@ -66,3 +66,4 @@ the rest. - [Ingest batch](/quest/m1/perf/ingest-batch.md) - relay ingest pays one lock, wake, and clock read per chunk burst instead of per chunk - [#3122](/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md) - moq-uring: ~2.5% of relay CPU is vdso clock reads; the drive loop and its callers each re-read Instant::now() - [#3199](/quest/m1/perf/3199-moq-uring-remove-sq-indirection-and-per-enter-ring-fd.md) - moq-uring: remove SQ indirection and per-enter ring fd lookup +- [Remove moq-uring copies](/quest/m1/perf/uring-copies.md) - egress, stream send and receive, and datagram receive stop copying where the QUIC core already allows it, on `dev` after the fork diff --git a/quest/m1/perf/uring-copies.md b/quest/m1/perf/uring-copies.md new file mode 100644 index 00000000000..591596afc0b --- /dev/null +++ b/quest/m1/perf/uring-copies.md @@ -0,0 +1,31 @@ +# [S] Remove moq-uring's avoidable copies + +## Goal + +moq-uring stops copying and allocating on paths where the QUIC core already +supports zero-copy, with a measured before/after. + +## Plan + +Found in the 2026-09-30 fork planning; none needs a QUIC API change: + +- Egress: `quic/noq/connection.rs` copies each GSO train from `scratch` into + the TX buffer. Hand the TX pool's `Vec` to `poll_transmit` directly; it + encrypts in place and only reserves when capacity is short. +- Stream send: moq-net's `write_chunk(Bytes)` falls back to the trait's + default `poll_write_buf`, which copies through `poll_write(&[u8])`. Route + it to the core's `write_chunks` so large chunks are kept by reference. +- Stream receive: moq-uring uses the trait's default `poll_read_chunk`, which + allocates an 8 KiB `BytesMut` and copies each read. Return the core's + `Bytes` directly. +- Datagram receive: `endpoint.rs` allocates a `BytesMut` per GRO segment. + Copy once per completion and split it into segments. + +The clock-read fix stays in +[#3122](/quest/m1/perf/3122-moq-uring-2-5-of-relay-cpu-is-vdso-clock-reads-the-drive.md). +Measure with the echo benches and `just bench`. This branches from `dev`, +where the fork lands; paths above are pre-fork names. + +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the copies are removed on `moq-quic`, not the frozen fork diff --git a/quest/m1/quic/README.md b/quest/m1/quic/README.md index d09e79e75b5..856696ec7b1 100644 --- a/quest/m1/quic/README.md +++ b/quest/m1/quic/README.md @@ -2,12 +2,12 @@ ## Goal -MoQ owns the QUIC features it needs. noq, the Quinn-derived stack n0 -maintains for Iroh, is the parent; the moq-dev fork carries what MoQ needs on -MoQ's schedule and offers it upstream when it is general. One core serves the -tokio backend, the thread-per-core `moq-uring` backend, iroh, and qmux. The -features are BBR correctness, reliable stream resets, hierarchical stream -scheduling with per-broadcast fairness, and wider limits for relay peers. +MoQ owns the QUIC features it needs in an in-tree stack, `moq-quic`, hard +forked from quinn (see [the fork](/quest/m1/quic/fork/README.md) for why +quinn and not noq). One core serves the tokio backend, the thread-per-core +`moq-uring` backend, and qmux; iroh stays on upstream noq. The features are +BBR correctness, reliable stream resets, hierarchical stream scheduling with +per-broadcast fairness, wider limits for relay peers, and endpoint sharding. Per-stream acknowledgment progress, per-stream deadlines, qmux on the shared stream state machine, and the experiments (GCC, receive timestamps, the egress profile, media probing, L4S, careful resume, deadline keep-alive) live in @@ -15,35 +15,29 @@ profile, media probing, L4S, careful resume, deadline keep-alive) live in ## Plan -Everything here ships from moq-dev/noq, the fork MoQ publishes as `moq-noq*`. -One stack carries every change on MoQ's own QUIC paths; a build with the `iroh` -feature also compiles upstream noq, and iroh connections are outside what these -quests reach. +Decided in the 2026-09-30 plan: the moq-dev/noq soft fork is replaced by a +hard fork of quinn in `rs/`, so every QUIC change here waits for +[the fork](/quest/m1/quic/fork/README.md) and lands on `dev`. Retarget this +line's PR (#3975) to `dev` when the fork starts. moq-dev/noq is frozen to +security patches for `main`. -The seven BBR correctness fixes shipped in moq-noq 1.3.1 (#4206). The -remaining BBR quests here and [BBR ACK cleanup](/quest/m1/bbr-ack-cleanup.md) -all edit `bbr3/mod.rs`, so one owner should work there at a time. -Controller-level regressions extend the shared test `Sim` in `bbr3/mod.rs` -with only what each needs, rather than adding another simulation loop; a fix -at the transport boundary still needs a transport test through the real -callbacks. The existing loops stay, since the fork merges upstream weekly and -a port would conflict. Each BBR fix ships in a fork patch release without -waiting for the remaining transport features. The comparison against -Google's BBR is part of the separate -[natural drain study](/quest/m2/quic-bbr-natural-drain.md). +Older quests say "the fork" or "noq"; read that as `moq-quic`. Their steps to +publish a fork release, pin it, or offer a change upstream are superseded: +a change lands in-tree with its consumer, and upstreaming is optional. -Rules the line keeps: +The seven BBR correctness fixes shipped in moq-noq 1.3.1 (#4206) and move to +`moq-quic` with the [BBR3 port](/quest/m1/quic/fork/bbr3.md). The remaining +BBR quests here and [BBR ACK cleanup](/quest/m1/bbr-ack-cleanup.md) all edit +`bbr3/mod.rs`, so one owner should work there at a time. Controller-level +regressions extend the shared test `Sim` in `bbr3/mod.rs` with only what each +needs, rather than adding another simulation loop; a fix at the transport +boundary still needs a transport test through the real callbacks. The +comparison against Google's BBR is part of the separate +[natural drain study](/quest/m2/quic-bbr-natural-drain.md). -- a carried change lists its upstream PR or the reason it has none; -- the fork's packages are `moq-noq-proto`, `moq-noq`, and `moq-noq-udp`, - never a crate that impersonates the parent; -- published MoQ crates depend on crates.io releases of the fork, never a - workspace-only Cargo patch or a mutable branch; -- each feature quest releases the fork crate it changes and records the - parent noq commit it is based on; there is no separate release quest; -- MoQ's config names congestion families (`Loss`, `Delay`, and `RealTime` - once GCC ships), never algorithms; noq's public `Controller` trait is the - seam experiments plug into, and MoQ owns which algorithm each family means. +MoQ's config names congestion families (`Loss`, `Delay`, and `RealTime` once +GCC ships), never algorithms; the `Controller` trait is the seam experiments +plug into, and MoQ owns which algorithm each family means. The scheduling contract has three levels: strict subscription priority, byte-fair service between send groups at the same priority, then the @@ -54,12 +48,11 @@ This is a transport API change, not a MoQ wire change. Decided in the 2026-09-30 audit: deadlines, qmux, BBR loss parity, ECN measurement, ACK progress, and the ACK hook moved to m2, since no m1 quest -consumes them. The release quest was deleted: the fork already publishes to -crates.io (moq-noq 1.3.2, web-transport-moq 2.0.0) with no workspace patch, -and the qmux crate release folds into [qmux](/quest/m2/quic-qmux.md). +consumes them. ## Required +- [Hard fork](/quest/m1/quic/fork/README.md) - quinn in-tree as `moq-quic`, with BBR3 and lazy stream slots, and MoQ switched onto it - [BBR idle burst](/quest/m1/quic/bbr-app-limited.md) - a fork regression proves a burst after a long idle is paced at the learned bandwidth, closing #4219 - [Mark BBR starvation wherever the source runs dry](/quest/m1/quic/bbr-app-limited-edges.md) - partial polls count, local send caps do not, receiver credit is pinned - [Deliver the application close before io_uring teardown](/quest/m1/quic/uring-close.md) - @@ -71,8 +64,9 @@ and the qmux crate release folds into [qmux](/quest/m2/quic-qmux.md). the lossy scalar; retransmits follow the same order - [Relay peers get wider limits](/quest/m1/quic/peer-limits.md) - MAX_STREAMS and MAX_DATA are raised after SETUP identifies a cluster peer -- [Upstream the fork](/quest/m1/quic/upstream.md) - every general carried - change is offered to n0-computer/noq once its shape has settled +- [Shard the endpoint](/quest/m1/quic/shard.md) - the library shards a + server endpoint across cores by default, replacing the `--workers` group +- [Surface UDP send errors](/quest/m1/quic/send-errors.md) - a client drops a QUIC attempt the moment its address family is unreachable ## Related @@ -80,8 +74,6 @@ and the qmux crate release folds into [qmux](/quest/m2/quic-qmux.md). per-broadcast fairness policy on cluster sessions - [Starvation](/quest/m1/qos/starvation.md) - the first consumer of ACK progress: how far behind viewers are, from the relay's point of view -- [Multipath spike](/quest/m2/multipath-spike.md) - a noq capability that - MoQ does not use yet - [Discover media headroom](/quest/m2/quic-probe.md) - test useful-media pacing before adding redundant probe traffic - [L4S on the backbone](/quest/m2/quic-ecn.md) - an ECT(1) option in the fork, an `ecn` config knob, and a dualpi2 measurement - [Careful resume on reconnect](/quest/m2/quic-careful-resume.md) - a redial starts at the previous connection's rate diff --git a/quest/m1/quic/bbr-app-limited-edges.md b/quest/m1/quic/bbr-app-limited-edges.md index fc47d4d2556..fdcc2b07b2d 100644 --- a/quest/m1/quic/bbr-app-limited-edges.md +++ b/quest/m1/quic/bbr-app-limited-edges.md @@ -32,6 +32,10 @@ drains, a sender blocked only by `send_window`, and a stream blocked by receiver credit. Builds on the seven fixes released in moq-noq 1.3.1. No public API or wire change is intended. +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - lands in `moq-quic` on `dev`, not the frozen fork + ## Related - [BBR idle burst](/quest/m1/quic/bbr-app-limited.md) - the first app-limited fix this extends diff --git a/quest/m1/quic/bbr-app-limited.md b/quest/m1/quic/bbr-app-limited.md index f0ea70c90ce..47c10053ad0 100644 --- a/quest/m1/quic/bbr-app-limited.md +++ b/quest/m1/quic/bbr-app-limited.md @@ -27,13 +27,12 @@ minutes, send 250 KB, and assert the pacing rate stays at or above about If it still stalls, find the remaining cause, such as ProbeRTT entered during the idle or a stale `bw_shortterm`, and fix it in the fork. Dropping the estimate after a long idle is a policy change for the m2 study, not this -quest. The `iroh` feature uses upstream noq, which lacks #5; offering it -there belongs to the upstream quest. +quest. -## Closes +## Required -- [#4219](https://github.com/moq-dev/moq/issues/4219) - the first send after an idle period is paced at a trickle +- [Hard fork](/quest/m1/quic/fork/README.md) - lands in `moq-quic` on `dev`, not the frozen fork -## Related +## Closes -- [Upstream the fork](/quest/m1/quic/upstream.md) - offer the starvation fix upstream +- [#4219](https://github.com/moq-dev/moq/issues/4219) - the first send after an idle period is paced at a trickle diff --git a/quest/m1/quic/fork/README.md b/quest/m1/quic/fork/README.md new file mode 100644 index 00000000000..c016b0574ec --- /dev/null +++ b/quest/m1/quic/fork/README.md @@ -0,0 +1,72 @@ +# Hard-fork quinn into the monorepo as moq-quic + +## Goal + +MoQ's QUIC stack lives in `rs/` as `moq-quic` (the sans-IO core), +`moq-quic-udp`, `moq-quic-tokio`, and `web-transport-moq`, forked from +quinn-rs/quinn `main`. Every MoQ QUIC path (moq-tokio and moq-uring) runs on +it, the `moq-noq*` dependencies are gone, and a QUIC change lands in the same +PR as the MoQ code that needs it. + +Out of scope: iroh keeps upstream noq (the `iroh` feature still compiles it for +iroh's controller factory), and multipath, NAT traversal, and QAD are not +carried. + +## Plan + +Decided in the 2026-09-30 plan, with reasons, so later sessions don't reopen +them: + +- **Hard fork, no merges.** The moq-dev/noq soft fork never merged upstream + (its weekly sync job failed on a workflow-permission error), n0-computer/noq + slowed to 5-7 commits a month in Aug-Sep, and n0's strict semver limits + what we can upstream, not what a fork can change. Upstream fixes are + cherry-picked by hand; offering our changes upstream is optional courtesy, + not tracked work. +- **Base on quinn, not noq.** quinn-proto is 32.9k lines against noq-proto's + 58.5k, about 15k of which is multipath, NAT traversal, and QAD that MoQ + never negotiates. Stripping those from noq was estimated at 2-3 weeks with + loss-recovery risk, and would leave every quinn fix a hand port. quinn ships + security fixes the day the advisory publishes (11 in 2026), and staying + close to its code keeps those cherry-picks cheap. The cost is re-porting + BBR3, the controller callbacks, and lazy stream slots, which is why MoQ + moved to noq in the first place (#1706, #3342, #3789). +- **Multipath is deleted**, and with it the multipath spike. +- **In-tree**, so `just check` and CI cover the stack, one PR spans the core + and its consumers, and `main` and `dev` each carry their own copy instead of + double-landing fixes on the 1.3 and 2.0 fork lines. +- **Named by role**: `moq-quic`, `moq-quic-udp`, `moq-quic-tokio`; + `web-transport-moq` keeps its name. Each crate's README and license credit + quinn and noq. +- **Lands on `dev`.** moq-tokio exposes `noq::Endpoint`, + `noq::TransportConfig`, and `noq::Incoming` publicly, so the crate swap is + a break. +- **Security folds into the fork.** Rebasing on quinn picks up the 2026 + advisories noq is missing; `main` stays on `moq-noq` until `dev` releases. + [noq reassembly cap](/quest/m0/noq-reassembly-cap.md) still finishes on the + old fork for `main`. +- **moq-dev/noq is frozen**: security patches for `main` only, archived once + no released MoQ crate depends on it. The other + [QUIC quests](/quest/m1/quic/README.md) wait for this line and land + in-tree on `dev`. + +This README's own work: delete moq-dev/noq's `moq-sync.yml`, mark its README +frozen, and document advisory triage in `rs/moq-quic/README.md`. `cargo audit` +cannot match renamed crates, so the triage is: watch quinn-rs/quinn's security +advisories and releases, check each fix against `moq-quic`, and port it with +its regression test. Every carried change in moq-dev/noq's `CHANGELOG-MOQ.md` +is either ported by a child quest or recorded as not applicable in the +[switch](/quest/m1/quic/fork/switch.md) PR. + +## Required + +- [Import quinn](/quest/m1/quic/fork/import.md) - quinn's three crates build and test in-tree as `moq-quic*`, verbatim at a recorded commit, with no consumer yet +- [Port BBR3](/quest/m1/quic/fork/bbr3.md) - the fork's corrected BBR3 and controller callbacks run on `moq-quic` as the default controller +- [Lazy stream slots](/quest/m1/quic/fork/stream-slots.md) - relay memory on `moq-quic` matches `moq-noq` +- [Switch](/quest/m1/quic/fork/switch.md) - `web-transport-moq`, moq-tokio, and moq-uring run on `moq-quic`, and `moq-noq*` is gone + +## Related + +- [Shard the endpoint](/quest/m1/quic/shard.md) - the first feature the fork makes possible +- [Remove moq-uring copies](/quest/m1/perf/uring-copies.md) - cheap copy removals on the new core +- [Redesign the QUIC I/O boundary](/quest/m2/quic-io-boundary.md) - the breaking perf rewrite, gated on a profile diff --git a/quest/m1/quic/fork/bbr3.md b/quest/m1/quic/fork/bbr3.md new file mode 100644 index 00000000000..45d81cbcc16 --- /dev/null +++ b/quest/m1/quic/fork/bbr3.md @@ -0,0 +1,37 @@ +# [L] Port BBR3 and the controller callbacks + +## Goal + +`moq-quic` carries the BBR3 controller from moq-dev/noq, with every +correctness fix the fork has shipped, and it is the default controller. The +fork's BBR regressions pass on `moq-quic`. + +## Plan + +Move moq-dev/noq's `congestion/bbr3/` over as a unit rather than starting from +quinn#2481: the fork's copy already descends from #2481 and carries the seven +BBR fixes (#4206), the app-limited fix, and the classic ECN CE response +(moq-dev/noq#12). Port the `Controller` extensions it depends on (`PacketId` +and packet-space callbacks, app-limited, cwnd-limited, ACK frequency) by hand; +they are about 350 lines in `connection/mod.rs` and `pacing.rs`. + +The fork's roughly 580 lines of regression tests are written against noq's +test harness; rework them onto quinn's rather than porting the harness. Keep +MoQ's config naming controller families (`Loss`, `Delay`), never algorithms. + +BBR3 must fill in `ControllerMetrics::bandwidth_estimate` (quinn#2802, merged), +which the [switch](/quest/m1/quic/fork/switch.md) reads for +`web-transport-moq`'s bandwidth stat. + +Verify with the fork's BBR tests and the benchmark matrix against `moq-noq` +1.3.x on the same workloads; report any throughput or latency difference. + +## Required + +- [Import quinn](/quest/m1/quic/fork/import.md) + +## Related + +- [noq#819](https://github.com/n0-computer/noq/issues/819) - BBR3 as the default, proposed to n0; their sims often favor Cubic +- [noq#475](https://github.com/n0-computer/noq/issues/475) - the original BBR ask +- [noq#768](https://github.com/n0-computer/noq/issues/768) - the `inflight_at_loss` underflow the fork fixed with `saturating_sub`; keep that regression diff --git a/quest/m1/quic/fork/import.md b/quest/m1/quic/fork/import.md new file mode 100644 index 00000000000..b0f6c03b3d2 --- /dev/null +++ b/quest/m1/quic/fork/import.md @@ -0,0 +1,31 @@ +# [M] Import quinn as moq-quic + +## Goal + +`rs/moq-quic`, `rs/moq-quic-udp`, and `rs/moq-quic-tokio` are quinn-proto, +quinn-udp, and quinn from quinn-rs/quinn `main`, and they build and pass their +own tests in `just check` and CI. Nothing consumes them yet. + +## Plan + +Keep the first commit verbatim at a recorded quinn commit so a reviewer can +diff it against upstream; renames, workspace lints, and edition fixes go in +separate commits. Record the parent commit in `rs/moq-quic/README.md` with the +advisory triage process the [questline](/quest/m1/quic/fork/README.md) +describes. + +Carry [quinn#2724](https://github.com/quinn-rs/quinn/pull/2724) as its own +cherry-pick commit (the same fix as noq#746, decided 2026-09-30): when the +kernel rejects a GSO batch with EIO or EINVAL, quinn-udp disables GSO and +drops the batch, so an Android client's Initial waits a full RTO and the +WebSocket fallback wins the race. Resend the batch instead. List it as carried +in `rs/moq-quic/README.md`; drop it if upstream lands +[quinn#2748](https://github.com/quinn-rs/quinn/pull/2748) and we cherry-pick +that. moq-uring's own UDP path (`rs/moq-uring/src/udp.rs`) submits GSO +trains itself, so check whether it drops a rejected train the same way, and +fix it here if so. + +Keep quinn's own features (qlog, rustls providers, runtimes) as they are; +pruning waits until the [switch](/quest/m1/quic/fork/switch.md) shows what MoQ +uses. Wire the crates into release-plz like the other `rs/` crates, and check +that the added test time fits CI. diff --git a/quest/m1/quic/fork/stream-slots.md b/quest/m1/quic/fork/stream-slots.md new file mode 100644 index 00000000000..4956c768bd8 --- /dev/null +++ b/quest/m1/quic/fork/stream-slots.md @@ -0,0 +1,26 @@ +# [S] Lazy stream slots on moq-quic + +## Goal + +`moq-quic` allocates stream state lazily, so relay memory on it matches +`moq-noq` on the bulk and fanout workloads. + +## Plan + +Cherry-pick the approved commits of quinn#2601 (the same change noq took as +noq#667); decided 2026-09-30 not to rebase the upstream PR first. #3342 measured the +difference it makes: 75 vs 141 MiB relay memory on bulk and 31 vs 97 MiB on +fanout. Re-run those workloads on `moq-quic` with and without the change. + +Check the port against quinn's 2026 MAX_STREAM_DATA advisory fix: noq's lazy +stream code was not exploitable there because it checks the limit itself, so +make sure the combined code keeps exactly one check. + +## Required + +- [Import quinn](/quest/m1/quic/fork/import.md) + +## Related + +- [quinn#2601](https://github.com/quinn-rs/quinn/pull/2601) - the approved upstream PR this cherry-picks +- [noq#667](https://github.com/n0-computer/noq/pull/667) - the same change merged into noq diff --git a/quest/m1/quic/fork/switch.md b/quest/m1/quic/fork/switch.md new file mode 100644 index 00000000000..e69eedff6b5 --- /dev/null +++ b/quest/m1/quic/fork/switch.md @@ -0,0 +1,32 @@ +# [M] Switch MoQ onto moq-quic + +## Goal + +`web-transport-moq` lives in `rs/` on `moq-quic-tokio`, moq-tokio and +moq-uring run on `moq-quic`, and no workspace crate depends on `moq-noq*`. +Upstream `noq-proto` remains only for the `iroh` feature. + +## Plan + +Move `web-transport-moq` from moq-dev/noq. It derives from +web-transport-quinn; its noq-only parts are `PathId::ZERO` and `path_stats`. +Report bandwidth from quinn's `PathStats::bandwidth_estimate` instead of the +current cwnd/rtt guess. + +moq-uring built against both quinn-proto and noq-proto until #3811, behind +about 20 `cfg` lines (stats fields, CID generator, qlog, BBR). Rename +`rs/moq-uring/src/quic/noq` by role and use that history as the map. Keep +moq-uring's `qlog` feature working on quinn's qlog. + +Rename the `noq` cargo features by role (`quic` is the recommendation); +confirm the name with the maintainer in the PR. Update every doc and example +that names noq, and run `just test interop --all`. + +In the PR, list each carried change from moq-dev/noq's `CHANGELOG-MOQ.md` as +ported (with its quest) or not applicable (with the reason). + +## Required + +- [Import quinn](/quest/m1/quic/fork/import.md) +- [Port BBR3](/quest/m1/quic/fork/bbr3.md) +- [Lazy stream slots](/quest/m1/quic/fork/stream-slots.md) diff --git a/quest/m1/quic/peer-limits.md b/quest/m1/quic/peer-limits.md index 7c36f74bc25..2646f5a6ff5 100644 --- a/quest/m1/quic/peer-limits.md +++ b/quest/m1/quic/peer-limits.md @@ -32,6 +32,7 @@ viewer session does not; the io_uring path applies the same values; a ## Required +- [Hard fork](/quest/m1/quic/fork/README.md) - lands in `moq-quic` on `dev`, not the frozen fork - [io_uring flow control](/quest/m1/uring-flow-control-windows.md) - the io_uring workers hardcode their windows today, so the peer values have nothing to raise there until the static windows reach them diff --git a/quest/m1/quic/reliable-reset.md b/quest/m1/quic/reliable-reset.md index 64becb43ca2..eca1feab383 100644 --- a/quest/m1/quic/reliable-reset.md +++ b/quest/m1/quic/reliable-reset.md @@ -64,6 +64,10 @@ Track the unversioned draft during implementation. The planning baseline is draft 10, with transport parameter `0x1d` and frame type `0x24`; do not freeze provisional codepoints if the document changes before release. +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - lands in `moq-quic` on `dev`, not the frozen fork + ## Related - moq-net (`rs/moq-net/src/tail.rs`) and `@moq/net` (`js/net/src/tail.ts`) wait @@ -72,3 +76,4 @@ provisional codepoints if the document changes before release. known browser-compliance gap. - [qmux on the QUIC stream state machine](/quest/m2/quic-qmux.md) - consumes the same reset state without a parallel implementation +- [noq#809](https://github.com/n0-computer/noq/issues/809) - the RESET_STREAM_AT ask to n0 diff --git a/quest/m1/quic/scheduler.md b/quest/m1/quic/scheduler.md index c28b33fb3ae..e39292b84a2 100644 --- a/quest/m1/quic/scheduler.md +++ b/quest/m1/quic/scheduler.md @@ -102,6 +102,10 @@ scheduler completion must not wait for that dependent integration. Preserve working behavior on backends not yet migrated, and remove queue code only where the new implementation makes it redundant. +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - lands in `moq-quic` on `dev`, not the frozen fork + ## Closes - [#699](https://github.com/moq-dev/moq/issues/699) - close this issue when the @@ -119,3 +123,5 @@ where the new implementation makes it redundant. scope - [Signed priority](/quest/m2/signed-priority.md) - changes the priority type this orders on; keep the ordering, not just the type +- [noq#816](https://github.com/n0-computer/noq/issues/816) - the send-group proposal to n0; this quest supersedes it +- [noq#817](https://github.com/n0-computer/noq/issues/817) - the 64-bit priority ask; send groups replace the scalar, but the per-stream order within a group must still hold a 64-bit group sequence diff --git a/quest/m1/quic/send-errors.md b/quest/m1/quic/send-errors.md new file mode 100644 index 00000000000..429ad578aca --- /dev/null +++ b/quest/m1/quic/send-errors.md @@ -0,0 +1,29 @@ +# [S] Surface UDP send errors so the client can fall back + +## Goal + +When a UDP send fails because the address family is unreachable (for +example an IPv6 target on a host without IPv6 routing), `moq-quic-tokio` +reports the error instead of swallowing it, and moq-tokio's dial race drops +that QUIC attempt at once rather than waiting out the handshake timeout. + +## Plan + +Rebase [kixelated/quinn#3](https://github.com/kixelated/quinn/pull/3) onto +`moq-quic-udp` and `moq-quic-tokio`. It is 154 commits behind quinn main and +never went upstream; it touches only the udp and tokio crates, not the +sans-IO core. Decided 2026-09-30: an m1 quest after the switch, since the +client connect path is user-facing. + +Only fatal, destination-specific errors end the attempt; transient ones +(`ENOBUFS`, `EAGAIN`) stay handled as packet loss, as today. Test the fallback with a dial +against an unroutable family, and check that moq-uring maps the same errors +through its ring. + +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic-udp` and `moq-quic-tokio` + +## Related + +- [quinn#2766](https://github.com/quinn-rs/quinn/issues/2766) - the upstream issue diff --git a/quest/m1/quic/shard.md b/quest/m1/quic/shard.md new file mode 100644 index 00000000000..b62bd345223 --- /dev/null +++ b/quest/m1/quic/shard.md @@ -0,0 +1,45 @@ +# [M] Shard the QUIC endpoint across cores + +## Goal + +A `moq-quic` server endpoint shards across cores by default where the +platform can steer (Linux): the library +forms the steered `SO_REUSEPORT` group and issues connection IDs that name +their shard, and each runtime (moq-tokio and moq-uring) only drives the +shards it is handed on threads of its own. The relay's `--workers` flag +becomes an optional count override, and the two copies of the group logic +are gone. + +## Plan + +Decided in the 2026-09-30 plan: the library shards and the runtime drives. +The library does not own threads, so embedders (libmoq, moq-ffi) keep their +own threading model. + +- `moq-quic-udp` absorbs `moq-sock::shard` (the group, claims, and steering + filter); `moq-sock` keeps binding and CPU helpers. +- `moq-quic` issues shard-prefixed connection IDs itself, replacing the + custom CID generators in moq-tokio and moq-uring. +- moq-tokio's `worker/group.rs` shrinks to spawning one pinned + `current_thread` runtime per shard; moq-uring's `udp::Bound` group code is + replaced by the library's. +- A server endpoint defaults to one shard per core only where + `SO_REUSEPORT` steering works, which today is Linux: `moq-sock` returns + `Unsupported` for both load balancing and steering elsewhere. macOS and + Windows keep a genuine single-socket endpoint, and an explicit count above + one is refused there rather than silently ignored. +- Before flipping the default, add a benchmark sweeping shard count against + concurrent session load (publishers and subscribers), so steering, + dispatch, and per-shard overhead show up as slopes. A single + default-versus-one-socket run cannot show a cost that grows with either + axis. + +Update `doc/bin/relay/` for the flag change. + +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the stack has to be in-tree before the library can own sharding + +## Related + +- [UDP demux](/quest/m2/one-port/udp-demux.md) - demuxes each shard's socket; keep the demux over whatever the library hands out diff --git a/quest/m1/quic/upstream.md b/quest/m1/quic/upstream.md deleted file mode 100644 index 796f087fd93..00000000000 --- a/quest/m1/quic/upstream.md +++ /dev/null @@ -1,72 +0,0 @@ -# [M] Upstream the fork - -## Goal - -Every general change the fork carries has been offered to n0-computer/noq as -a reviewable pull request, and the fork's carried set is only what upstream -declined or what is MoQ-specific. The noq maintainers have seen this roadmap -before the first proposal lands, so nothing arrives as a surprise. - -## Plan - -Fork now, upstream opportunistically: this quest is the "opportunistically" -half, and it completes the line rather than gating it. Each feature quest -lands in the fork on MoQ's schedule; once a feature has shipped in a MoQ -release and its shape has stopped moving, split it into an upstream PR with -the tests it landed with. - -Offer the seven BBR correctness fixes (moq-noq 1.3.1, #4206) and -their [loss](/quest/m2/quic-bbr-loss-parity.md) and -[starvation](/quest/m1/quic/bbr-app-limited-edges.md) follow-ups with their -regressions before promoting BBR as the default. Reuse existing -upstream work, particularly [PR #802](https://github.com/n0-computer/noq/pull/802), -and preserve attribution; the fork found that #802's `has_sample()` check -fires one ACK late under noq's callback order and that its 1-ms floor keeps -sub-millisecond paths at the placeholder rate, so offer both back there. The -additive `PacketId` callbacks answer upstream's TODO on the `Controller` -impl. Fixes can be offered as their shapes settle; upstream acceptance never -gates the fork's corrected release. - -Then the feature proposal order, each linked to its producing quest: - -0. BBR3 as `TransportConfig`'s default controller (noq-proto 1.2.0 defaults - to Cubic, `config/transport.rs:586`, while MoQ has run BBR3 by default - since it adopted noq): a one-line change whose point is that every noq - and iroh user, the maintainers included, runs the controller MoQ depends - on, so its regressions are found upstream and not only here; -1. per-stream acknowledgment progress ([ACK progress](/quest/m2/quic-ack-progress.md)); -2. `RESET_STREAM_AT` ([reliable reset](/quest/m1/quic/reliable-reset.md)); -3. hierarchical send groups ([scheduler](/quest/m1/quic/scheduler.md)); -4. per-stream deadlines ([deadlines](/quest/m2/quic-deadline.md)); -5. the qmux crate over the shared stream state machine ([qmux](/quest/m2/quic-qmux.md)). - -Items 1, 4, and 5 moved to m2 in the 2026-09-30 audit; like the other m2 -features they are offered when they land and do not gate this quest. The -other m2 features (keep-alive by deadline, careful resume as a `Controller` -wrapper, ECT(1) marking, the media-headroom mechanism) are offered when they -land, but do not gate this quest: an m1 quest must not wait on m2 work. The -next experiments (receive timestamps, GCC, the egress profile, the -natural-drain check) join the list only with a -positive verdict. - -Record in this quest what upstream accepted, what it asked to see as an -extension crate, and what it declined; a declined change stays in the fork -with the link beside it. The quest completes when the m1 items above have -been offered and answered. - -## Required - -- [Mark BBR starvation wherever the source runs dry](/quest/m1/quic/bbr-app-limited-edges.md) -- [Reliable stream reset](/quest/m1/quic/reliable-reset.md) -- [Hierarchical stream scheduling](/quest/m1/quic/scheduler.md) - -## Related - -- [Keep-alive by deadline](/quest/m2/quic-keep-alive.md), - [Careful resume on reconnect](/quest/m2/quic-careful-resume.md), - [L4S on the backbone](/quest/m2/quic-ecn.md), - [Discover media headroom](/quest/m2/quic-probe.md) - m2 features offered - upstream when they land -- [BBR media study](/quest/m2/quic-bbr-natural-drain.md), - [Receive timestamps](/quest/m3/quic-receive-ts.md), [GCC](/quest/m3/quic-gcc.md) - - experiments that join the list with a positive verdict diff --git a/quest/m2/README.md b/quest/m2/README.md index f79539a25fd..4de4234a256 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -46,7 +46,7 @@ waiting on an upstream release waits in [m4](/quest/m4/README.md). - [Starvation at frame granularity](/quest/m2/starvation-frames.md) - the acknowledged frontier moves at every frame boundary through `poll_acked`, with a delivery-delay histogram for jitter -- [Per-stream ACK progress](/quest/m2/quic-ack-progress.md) - the fork reports +- [Per-stream ACK progress](/quest/m2/quic-ack-progress.md) - `moq-quic` reports how far a send stream has been acknowledged and when - [poll_acked in web-transport](/quest/m2/quic-ack-hook.md) - the backend-neutral hook that awaits an acknowledged stream offset, implemented @@ -88,13 +88,13 @@ waiting on an upstream release waits in [m4](/quest/m4/README.md). - [vcpkg registry](/quest/m2/cpp-vcpkg.md) - a registry we own serves the prebuilt package to `vcpkg` manifests - [Binary delta stats](/quest/m2/stats-delta.md) - an on-demand varint delta flavor of every stats track, if relay encode CPU still matters after the JSON fixes - [#3115](/quest/m2/3115-moqsink-the-publication-has-no-generation-so-a-flush.md) - moqsink: a flushing restart after EOS opens a new publication generation -- [Multipath spike](/quest/m2/multipath-spike.md) - whether bonded contribution over multipath QUIC is worth building, given it needs noq on both ends +- [QUIC I/O boundary](/quest/m2/quic-io-boundary.md) - moq-uring receives from the buffer ring and transmits into registered buffers with no copy, once a profile says where - [BBR media study](/quest/m2/quic-bbr-natural-drain.md) - whether bounded drain credit avoids ProbeRTT deadline interference, and where our BBR differs from Google's - [Discover media headroom](/quest/m2/quic-probe.md) - test useful-media pacing before adding redundant probe traffic - [L4S on the backbone](/quest/m2/quic-ecn.md) - an ECT(1) option in the fork, an `ecn` config knob, and a dualpi2 measurement - [Careful resume on reconnect](/quest/m2/quic-careful-resume.md) - a redial starts at the previous connection's rate - [Keep-alive by deadline](/quest/m2/quic-keep-alive.md) - a PING only when the idle deadline nears, no fixed timer -- [noq socket close](/quest/m2/noq-socket-close.md) - noq releases an endpoint's socket on close, so moq-tokio drops its wrapper +- [Socket close](/quest/m2/noq-socket-close.md) - `moq-quic` releases an endpoint's socket on close, so moq-tokio drops its wrapper - [GOP overhead](/quest/m2/gop-overhead.md) - price the I-frames a short GOP pays for, deciding whether a long GOP plus a keyframe request is worth designing - [Per-program SI](/quest/m2/ts-program-si.md) - a selected TS program's broadcast carries only its own service's SDT and EIT - [TS import health](/quest/m2/ts-import-health.md) - `moq import ts` counts the TR 101 290 errors of the feed it receives, PCR and PTS graded on its own values diff --git a/quest/m2/multipath-spike.md b/quest/m2/multipath-spike.md deleted file mode 100644 index 6e7646f68b0..00000000000 --- a/quest/m2/multipath-spike.md +++ /dev/null @@ -1,64 +0,0 @@ -# [M] Multipath spike - -## Goal - -A verdict on whether bonded contribution over multipath QUIC is worth -building, backed by two paths actually carrying one session. Bonding means -sending a broadcast over several links at once (cellular plus cellular plus -wifi) so a field encoder survives any one of them degrading, which is the -business LiveU and Peplink built on proprietary tech and SRT has no answer -for. - -## Plan - -The protocol work is done and unused. `noq` implements draft-ietf-quic-multipath -in full (`open_path`, `path_events`, `path_stats`, a `Path` type, and a -substantial test suite), but `apply_transport` never calls -`max_concurrent_multipath_paths`, whose default is `None`, so multipath is not -negotiated on any MoQ connection. - -The spike is small: call that setter, add a max-paths knob beside the other -transport settings, and open a second path from the connect side. It rides -entirely below the `web_transport_trait` line, because -`web_transport_moq::Session` derefs to `noq::Connection` and the trait requires -`Clone`, so the backend can hand one clone to moq-net and keep another to -drive paths on. No trait change, no moq-net change, and none belongs there: a -browser WebTransport backend could never implement it. - -**What the spike is really for is the constraint nobody has written down.** -`max_concurrent_multipath_paths` maps to the `initial_max_path_id` transport -parameter, which both peers negotiate, so a multipath session needs noq on -*both* ends. noq is the only native QUIC backend, while browser and qmux -transports have no such thing. So bonded contribution is not an opt-in client feature; it -constrains every relay and client on the path to run noq. Establish what that -actually costs before anyone builds a fan-out socket. - -Prove it on a multi-homed host, which is enough to negotiate and open a second -path and is not yet phone bonding. - -Then record what the rest would take, so a go verdict has something to plan -from and a no-go says why: - -- **One endpoint is one UDP socket.** `FourTuple` carries `local_ip` only, - because "we can only specify the `src_ip`, not the source port", and setting - a source IP does not choose an egress interface. Android needs - `Network.bindSocket` and iOS needs an interface bind to reach the cellular - radio at all. The escape hatch is `Endpoint::new_with_abstract_socket` with a - fan-out `AsyncUdpSocket` owning one interface-bound socket per radio, which - then has to answer for `local_addr`, and take the conservative minimum for - `max_receive_segments` and `may_fragment`. -- **Stats are single-path shaped.** `ConnectionStats` carries one `rtt` and one - `estimated_send_rate`, and per-path scheduling for contribution would need - both that and `web_transport_trait::Stats` reshaped. -- **Scheduling policy is unchosen**: duplicate every path for redundancy, or - stripe across them for capacity. - -Naming trap: `Path` in moq-net is the broadcast namespace path, and -`Client::with_path` is the MoQ SETUP resource path. A network path needs a -different name. - -Target `main`: `apply_transport` lives in `rs/moq-tokio/src/noq.rs` there -too, and the max-paths knob is additive. - -Public API: an additive transport setting in `moq-tokio`. Wire: none; multipath -is negotiated by QUIC transport parameters, below MoQ. diff --git a/quest/m2/noq-socket-close.md b/quest/m2/noq-socket-close.md index 3fa7a9621b8..a442d2121b6 100644 --- a/quest/m2/noq-socket-close.md +++ b/quest/m2/noq-socket-close.md @@ -1,21 +1,24 @@ -# [M] noq releases an endpoint's socket on close +# [M] moq-quic releases an endpoint's socket on close ## Goal -A noq endpoint can close its UDP socket, and report when it has, without +A `moq-quic` endpoint can close its UDP socket, and report when it has, without waiting for every connection handle to drop. moq-tokio then deletes the closable socket wrapper that #4087 added to make `Listener::close` release the port. ## Plan -In moq-dev/noq, add an endpoint operation that closes the endpoint, waits +In `moq-quic-tokio`, add an endpoint operation that closes the endpoint, waits until each connection has sent its close, and then releases the socket. Later -sends are dropped and receives end. Test it there. Cut a noq release, bump the -pin, and replace moq-tokio's wrapper with the upstream call. The Go +sends are dropped and receives end. Test it there and replace moq-tokio's wrapper with it in the same PR. The Go `TestReconnectAcrossRelayRestart` and moq-tokio's `close_releases_quic_socket` stay green. +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the endpoint is in-tree + ## Related - [Listener close](https://github.com/moq-dev/moq/pull/4087) - the local wrapper this replaces diff --git a/quest/m2/quic-ack-hook.md b/quest/m2/quic-ack-hook.md index 2879ba8da37..9dbb125ee1c 100644 --- a/quest/m2/quic-ack-hook.md +++ b/quest/m2/quic-ack-hook.md @@ -3,18 +3,14 @@ ## Goal A released `web-transport-trait` lets a sender await acknowledgment of a -named byte offset on a send stream, a released `web-transport-moq` implements +named byte offset on a send stream, `web-transport-moq` implements it, and every other backend reports that it cannot rather than returning a guess. ## Plan The trait method lives in `moq-dev/web-transport`. The `web-transport-moq` -adapter lives in the moq-dev/noq fork and is released from it -(Cargo.toml:236-237), so its implementation folds into -[ACK progress](/quest/m2/quic-ack-progress.md)'s release rather than a -separate one. This quest exists so the release it produces is one condition -dependents wait on; it supersedes the design in moq-dev/web-transport#368, +adapter is in-tree after [the fork](/quest/m1/quic/fork/README.md). This quest supersedes the design in moq-dev/web-transport#368, whose snapshot-counter shape loses the wakeups a latency sample needs. Add one method to `SendStream`, in the trait's poll style: @@ -33,7 +29,7 @@ use. A default body cannot construct a backend's own `Self::Error`, so unsupported has to live in the return type rather than the error, and a consumer must treat `None` as unknown, never as delivered. -Implement it in `web-transport-moq`, in the fork, over the fork's accessor. Leave +Implement it in `web-transport-moq` over `moq-quic`'s accessor. Leave `web-transport-wasm` on the default; the browser's `WebTransportSendStream.getStats()` is unimplemented in shipping Chrome and its `bytesAcknowledged` is at risk in the W3C draft. qmux over a reliable transport may treat serialization as @@ -45,17 +41,15 @@ the middle of an in-flight frame, several waiters on one stream in offset order, a waiter whose offset lies beyond the final size, reset by sender, STOP_SENDING by the receiver, and session close. -Cut a `web-transport-trait` release, and ship the adapter in the fork -release that carries ACK progress. The quest completes when both are on -crates.io. +Cut a `web-transport-trait` release; the adapter lands in-tree against it. Decided in the 2026-09-30 audit: moved to m2 with its only consumer, [frame-granularity starvation](/quest/m2/starvation-frames.md). ## Required -- [Per-stream ACK progress in noq](/quest/m2/quic-ack-progress.md) - the - noq-proto accessor the adapter reads, released together +- [Per-stream ACK progress](/quest/m2/quic-ack-progress.md) - the + `moq-quic` accessor the adapter reads ## Related diff --git a/quest/m2/quic-ack-progress.md b/quest/m2/quic-ack-progress.md index 839ad1b145c..cca026beb77 100644 --- a/quest/m2/quic-ack-progress.md +++ b/quest/m2/quic-ack-progress.md @@ -1,17 +1,16 @@ -# [S] noq-proto reports per-stream acknowledgment progress +# [S] moq-quic reports per-stream acknowledgment progress ## Goal -A released noq-proto lets a sender ask how much of a send stream the peer has +`moq-quic` lets a sender ask how much of a send stream the peer has acknowledged and when each acknowledgment was received, corrected for the peer's reported ACK delay. Nothing MoQ builds on top needs private state. ## Plan -The work lives in the moq-dev/noq fork. This quest exists so the release it -produces is one condition dependents wait on. +The work lives in `moq-quic`, in-tree after [the fork](/quest/m1/quic/fork/README.md). -noq-proto already tracks everything needed in `SendBuffer`: the acknowledged +noq-proto (and so quinn-proto; check on the fork) already tracks everything needed in `SendBuffer`: the acknowledged range set, `fully_acked_offset()`, and the unacked length. `Connection` also computes the peer's `ack_delay` per ACK frame when it updates the RTT estimator. Expose that state through the public `SendStream` handle without @@ -33,16 +32,18 @@ stream teardown: the accessor must not return a prefix that includes bytes the peer will never acknowledge, and a waiter for an offset beyond the final size must resolve with the reset instead of hanging. -Land it in the fork and offer it upstream once it is stable. The -`web-transport-moq` half of [the ACK hook](/quest/m2/quic-ack-hook.md) lives -in the same fork repository and ships in the same release. The quest -completes when a `moq-noq-proto` release carries the accessor and -`Cargo.lock` here can name it. +The `web-transport-moq` half of [the ACK hook](/quest/m2/quic-ack-hook.md) +is in-tree too and can land in the same PR. Decided in the 2026-09-30 audit: moved to m2 with its consumers, the ACK hook and [frame-granularity starvation](/quest/m2/starvation-frames.md). +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the accessor lands in `moq-quic` + ## Related - [poll_acked in web-transport](/quest/m2/quic-ack-hook.md) - the first consumer of the accessor +- [noq#808](https://github.com/n0-computer/noq/issues/808) - the acked-offset ask to n0 diff --git a/quest/m2/quic-bbr-loss-parity.md b/quest/m2/quic-bbr-loss-parity.md index 5a2cb439a6c..1b6d118264f 100644 --- a/quest/m2/quic-bbr-loss-parity.md +++ b/quest/m2/quic-bbr-loss-parity.md @@ -35,6 +35,6 @@ Decided in the 2026-09-30 audit: moved to m2. The seven correctness fixes already shipped, and this remaining gap has no observed impact on MoQ traffic yet. -## Related +## Required -- [Upstream the fork](/quest/m1/quic/upstream.md) - offers this fix alongside the seven +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork diff --git a/quest/m2/quic-bbr-natural-drain.md b/quest/m2/quic-bbr-natural-drain.md index 5ca6de5d3b3..a6dd11bde91 100644 --- a/quest/m2/quic-bbr-natural-drain.md +++ b/quest/m2/quic-bbr-natural-drain.md @@ -75,7 +75,10 @@ pinned code and configurations. Keep transport differences and QUICHE flags explicit and compare each algorithm change separately. A simulation result is not an end-to-end network measurement. +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork + ## Related -- [Upstream the fork](/quest/m1/quic/upstream.md) - share useful findings with upstream - [Discover media headroom](/quest/m2/quic-probe.md) - preserving an estimate and discovering spare capacity are separate problems diff --git a/quest/m2/quic-careful-resume.md b/quest/m2/quic-careful-resume.md index 30d906eb0ac..d00d185ebd0 100644 --- a/quest/m2/quic-careful-resume.md +++ b/quest/m2/quic-careful-resume.md @@ -30,8 +30,13 @@ Measure time to the encoder's target rate after a reconnect on the impaired path profile, plus loss and latency during the jump. Ship it on by default only when the jump never makes the first second worse than slow start. +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork + ## Related - [Transport upgrade](/quest/m1/transport-upgrade/README.md) - one of the reconnects this speeds up - [Drain](/quest/m1/drain/README.md) - GOAWAY redials are the other +- [noq#815](https://github.com/n0-computer/noq/issues/815) - the careful-resume proposal to n0 diff --git a/quest/m2/quic-deadline.md b/quest/m2/quic-deadline.md index 008fcbf9c20..a644a87043b 100644 --- a/quest/m2/quic-deadline.md +++ b/quest/m2/quic-deadline.md @@ -42,12 +42,11 @@ retransmitted past their deadline (must be zero), spurious resets under reordering, and probe overhead versus the default PTO. A proactive probe that raises loss or latency under any profile stays off by default. -Decided in the 2026-09-30 audit: moved to m2. No m1 quest consumes it, and -[Upstream the fork](/quest/m1/quic/upstream.md) offers it when it lands -rather than waiting on it. +Decided in the 2026-09-30 audit: moved to m2. No m1 quest consumes it. ## Required +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork - [Hierarchical stream scheduling](/quest/m1/quic/scheduler.md) - the scheduler decides which stream's data a probe carries @@ -57,3 +56,4 @@ rather than waiting on it. delay replaces the half-RTT estimate - [Discover media headroom](/quest/m2/quic-probe.md) - can reuse retransmission machinery if redundant capacity probes prove worthwhile +- [noq#813](https://github.com/n0-computer/noq/issues/813) - the per-stream deadline proposal to n0 diff --git a/quest/m2/quic-ecn-measure.md b/quest/m2/quic-ecn-measure.md index b04caf44818..32657baf08d 100644 --- a/quest/m2/quic-ecn-measure.md +++ b/quest/m2/quic-ecn-measure.md @@ -39,3 +39,7 @@ from 1.3.1 is a defective baseline, not evidence that classic ECN cannot help. Decided in the 2026-09-30 audit: moved to m2 with its only consumer, [L4S on the backbone](/quest/m2/quic-ecn.md). + +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork diff --git a/quest/m2/quic-ecn.md b/quest/m2/quic-ecn.md index a2779e7c031..8e6db1d0df6 100644 --- a/quest/m2/quic-ecn.md +++ b/quest/m2/quic-ecn.md @@ -35,5 +35,10 @@ need the fork. ## Required +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork - [Measure ECN on the backbone](/quest/m2/quic-ecn-measure.md) - the provider verdict this quest acts on + +## Related + +- [noq#814](https://github.com/n0-computer/noq/issues/814) - the L4S proposal to n0 diff --git a/quest/m2/quic-egress-profile.md b/quest/m2/quic-egress-profile.md index 6a30e7127f7..71c75e9d178 100644 --- a/quest/m2/quic-egress-profile.md +++ b/quest/m2/quic-egress-profile.md @@ -48,6 +48,10 @@ Report CPU per Gbps, RSS, loss, and p99 latency via `just bench BASE` on Linux. The verdict names which levers ship and which qdisc, if any, relay hosts need. +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork + ## Related - [#3201](/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md) - diff --git a/quest/m2/quic-io-boundary.md b/quest/m2/quic-io-boundary.md new file mode 100644 index 00000000000..69b8beef509 --- /dev/null +++ b/quest/m2/quic-io-boundary.md @@ -0,0 +1,34 @@ +# [L] Redesign the QUIC I/O boundary around io_uring + +## Goal + +`moq-quic`'s sans-IO boundary lets moq-uring receive from the kernel's +buffer ring and transmit into registered buffers, with no copy between the +kernel and the crypto. The API may break; it is in-tree. + +## Plan + +Decided in the 2026-09-30 plan: commit to the redesign, but start only after +a noq or `moq-quic` profile shows where ingress and egress spend their time. +No current profile is from noq, and every other copy is removed without an +API change by [Remove moq-uring copies](/quest/m1/perf/uring-copies.md). + +Candidates, to be ranked by the profile: + +- `Endpoint::handle` accepts a foreign-owned buffer (a buffer-ring slot), and + stream frames keep references to it instead of requiring an owned + `BytesMut`. +- `poll_transmit` writes into a caller slice or registered buffer as a + contract, not by relying on `Vec` capacity. +- One `handle` call takes a whole GRO batch. + +Registered TX buffers ([#3204](/quest/m3/3204-moq-uring-register-tx-pool-buffers-for-zero-copy-sends.md)) +and `SENDMSG_ZC` ([#3201](/quest/m3/3201-moq-uring-use-sendmsg-zc-for-large-udp-gso-trains.md)) +build on the transmit contract. Report relay CPU per Gbps before and after on +the same workloads. + +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the redesign breaks `moq-quic`'s API +- [Relay profiles](/quest/m1/performance-profiles.md) - the redesign targets measured costs +- [Remove moq-uring copies](/quest/m1/perf/uring-copies.md) - the cheap wins land first, so the profile shows what is left diff --git a/quest/m2/quic-keep-alive.md b/quest/m2/quic-keep-alive.md index 7c7fc08512d..609172872f4 100644 --- a/quest/m2/quic-keep-alive.md +++ b/quest/m2/quic-keep-alive.md @@ -24,7 +24,6 @@ timeout by hand. Replace it in the fork: - Keep `keep_alive_interval` as a maximum: `None` means "as late as possible"; a value means "no later than this", for a NAT binding with a shorter life than the idle timeout. That is the only knob. -- The multipath per-path keep-alive follows the same rule per path. moq-tokio's `quic.keep_alive` (`rs/moq-tokio/src/quic.rs`) in the `[quic]` sections, CLI flags, and env vars becomes that optional maximum, default none, @@ -34,3 +33,11 @@ documented in `doc/bin/relay/config.md` for NAT-sensitive deployments. The qmux Tests: an idle connection survives an idle timeout with exactly one PING per period; a busy connection sends none; a lost PING is probed before the deadline; the maximum knob shortens the period. + +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork + +## Related + +- [noq#810](https://github.com/n0-computer/noq/issues/810) - the proposal to n0; flub and matheus23 asked to keep a cap for NAT bindings, which the optional maximum covers diff --git a/quest/m2/quic-probe.md b/quest/m2/quic-probe.md index 9f9f4827d13..ffe83c091c6 100644 --- a/quest/m2/quic-probe.md +++ b/quest/m2/quic-probe.md @@ -44,7 +44,13 @@ is not proof of full path capacity. Persist regressions in CI and broader network scenarios at least nightly. A measured no-go is a valid outcome; retain the baseline and record why before exposing an ineffective option. +## Required + +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork + ## Related - [Natural media drains](/quest/m2/quic-bbr-natural-drain.md) - separate ProbeRTT policy experiment - [GCC egress experiment](/quest/m3/quic-gcc.md) - delay control changes what headroom means +- [noq#811](https://github.com/n0-computer/noq/issues/811) - probing while app-limited, proposed to n0 +- [noq#476](https://github.com/n0-computer/noq/issues/476) - the earlier bitrate-probing ask diff --git a/quest/m2/quic-qmux.md b/quest/m2/quic-qmux.md index 30bde059131..a131cdfb01b 100644 --- a/quest/m2/quic-qmux.md +++ b/quest/m2/quic-qmux.md @@ -1,17 +1,39 @@ -# [L] Run qmux on the QUIC stream state machine +# [XL] Run qmux on the QUIC stream state machine ## Goal -qmux uses noq-proto for stream lifecycle, flow -control, datagram buffering, priority scheduling, and transport parameters. -It owns only record framing and the semantics that differ from QUIC, instead -of maintaining a parallel stream implementation. +qmux lives in the monorepo and uses `moq-quic`'s stream state machine for +stream lifecycle, flow control, datagram buffering, priority scheduling, and +transport parameters. It owns only record framing, its transport adapters, +and the semantics that differ from QUIC, instead of maintaining a parallel +stream implementation. moq-tokio and moq-relay depend on the in-tree crate, +and moq-dev/web-transport no longer carries a Rust qmux. ## Plan +Decided in the 2026-09-30 plan: + +- **Scope is the Rust core plus adapters.** Port the prototype core and + moq-dev/web-transport's TCP, TLS, WebSocket, and UDS adapters, ALPN + negotiation, byte-stream framing, and socket stats (about 2.3k lines) onto + it, along with the `web-transport-trait` impl. The TypeScript `@moq/qmux` + and `@moq/web-socket-stream` stay in moq-dev/web-transport with their own + state machine and become the interop reference. +- **All four wire versions stay**: draft-02, draft-01, draft-00, and the + legacy `webtransport` format, since published clients (and the TS peer) + negotiate them. They differ only in record framing, so they share the one + state machine. +- **Shape**: the sans-IO part is `moq_quic::mux`, a module behind a feature, + so it reaches the stream state without widening `moq-quic`'s public API. + The tokio session, adapters, and trait impl are the `qmux` crate, published + from the monorepo under the existing crates.io name as its next breaking + version. moq-dev/web-transport removes its copy; the external dependents + (atmoq-moq-native, web-transport-ws) can move to the new release on their own schedule. + Start from the green -[kixelated/quinn#2](https://github.com/kixelated/quinn/pull/2) prototype. Rebase -it onto noq and preserve its central invariant: drive the +[kixelated/quinn#2](https://github.com/kixelated/quinn/pull/2) prototype, +which is already quinn-based. Rebase it onto `moq-quic` and preserve its +central invariant: drive the existing stream state machine through the same receive and write entry points as QUIC, then treat serialization to the reliable underlying transport as the acknowledgment. Do not copy the stream maps, flow-control accounting, reset @@ -34,32 +56,29 @@ reusable acceptance fixtures, including byte fairness, strict priority, newest/oldest group ordering, cancellation, and blocked-stream behavior. The native scheduler does not wait for this dependent proof. -Add the missing wire evidence before release: golden draft-02 vectors, -bidirectional interoperability against the published `qmux` 0.5.x crate, and +Add the missing wire evidence before release: golden vectors for each of the four versions, +bidirectional interoperability against the last web-transport `qmux` release (0.6.x), and the TypeScript qmux/WebSocket peer used by `js/net`. Preserve rejection of prohibited QUIC frames, params-first setup, record-size validation, close and reset semantics (the first recorded close wins, as close codes #4262 settled on dev), keep-alive behavior, and bounded flow-control tests. -The crate lives in the fork's workspace as `moq-noq-qmux`, so the stream -state machine internals it drives stay crate-private there; `moq-dev/web-transport`'s -`qmux` becomes a thin re-export or is retired. There must be one stream -state machine in the dependency graph, and the accessors qmux needs are -`pub(crate)` to that workspace, never part of `moq-noq-proto`'s public API. +There must be one stream state machine in the dependency graph. -Release it from the fork like the other fork crates: tag `moq-noq-qmux` with -the parent noq commit and the carried patches (each with its upstream PR or -the reason there is none), pin the crates.io version in this workspace, and -verify minimal, default, and all-feature builds so enabling iroh, qmux, or -the uring runtime never unifies two copies of the stream state. The quest -completes when that release is on crates.io and `Cargo.lock` names it. +Verify minimal, default, and all-feature builds so enabling iroh, qmux, or +the uring runtime never unifies two copies of the stream state. -Decided in the 2026-09-30 audit: moved to m2, since no m1 quest consumes it. -The separate QUIC release quest was deleted and its qmux step folded here. +Decided in the 2026-09-30 audit: moved to m2, since no m1 quest consumes it; +the fork plan the same day kept it there. ## Required +- [Hard fork](/quest/m1/quic/fork/README.md) - qmux drives `moq-quic` - [Reliable stream reset](/quest/m1/quic/reliable-reset.md) - qmux reuses the extension's stream state rather than implementing reset locally - [Hierarchical stream scheduling](/quest/m1/quic/scheduler.md) - qmux must expose the same scheduling contract as native QUIC + +## Related + +- [noq#812](https://github.com/n0-computer/noq/issues/812) - the qmux proposal to n0 diff --git a/quest/m3/quic-gcc.md b/quest/m3/quic-gcc.md index 268726aa01a..ff482bdd4d1 100644 --- a/quest/m3/quic-gcc.md +++ b/quest/m3/quic-gcc.md @@ -33,5 +33,10 @@ exists. ## Required +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork - [Receive timestamps](/quest/m3/quic-receive-ts.md) - the per-packet arrival times the delay filter runs on + +## Related + +- [noq#818](https://github.com/n0-computer/noq/issues/818) - the GCC proposal to n0; matheus23 asked for a non-breaking `Controller` trait diff --git a/quest/m3/quic-receive-ts.md b/quest/m3/quic-receive-ts.md index ad94b72070e..7cf17d9bd8f 100644 --- a/quest/m3/quic-receive-ts.md +++ b/quest/m3/quic-receive-ts.md @@ -32,6 +32,7 @@ GCC until such a consumer exists. ## Required +- [Hard fork](/quest/m1/quic/fork/README.md) - the change lands in `moq-quic`, not the frozen fork - A native-to-native consumer of receive timestamps (browsers never see them) ## Related From c73f0b52f2c1370891b2c9ee9f453dcac48ca26f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 12:49:43 -0700 Subject: [PATCH 115/128] quest: drop relay memory benchmark (#4621) Co-authored-by: GPT-6 --- quest/m0/wildcard/README.md | 3 +- quest/m1/cluster-routing/README.md | 2 -- quest/m1/cluster-routing/memory.md | 46 ------------------------- quest/m1/cluster-routing/propagation.md | 10 ++---- 4 files changed, 3 insertions(+), 58 deletions(-) delete mode 100644 quest/m1/cluster-routing/memory.md diff --git a/quest/m0/wildcard/README.md b/quest/m0/wildcard/README.md index a41beec582e..78e88a1dd5a 100644 --- a/quest/m0/wildcard/README.md +++ b/quest/m0/wildcard/README.md @@ -23,8 +23,7 @@ is the catch-all `**`, a claim about every path at once. The cost of enumerating is real even though its last measurement is stale. One announcement measured 8.8 KB per relay plus 4.3 KB per additional route -before prefix routes made a standby route a table entry; -[Cluster routing's memory benchmark](/quest/m1/cluster-routing/memory.md) remeasures it. Whatever the current +before prefix routes made a standby route a table entry. Whatever the current number, every relay that hears an announcement pays it whether or not anything there subscribes, so "workers times broadcasts" is that number multiplied across the fleet in resident memory. diff --git a/quest/m1/cluster-routing/README.md b/quest/m1/cluster-routing/README.md index ee1ec30ac98..16121aff8dd 100644 --- a/quest/m1/cluster-routing/README.md +++ b/quest/m1/cluster-routing/README.md @@ -42,7 +42,6 @@ Settled in the 2026-09-30 `/quest-plan`: before they publish). If lite-07 is finalized first for the Wildcard rollout, the remaining children move to the next wip version; finalizing never waits on this line. -- The before/after memory figure is a committed benchmark, measured first. - A short idle timeout for cluster sessions is its own m1 quest, [Cluster idle timeout](/quest/m1/cluster-idle-timeout.md), since it helps today's path vector too. @@ -179,7 +178,6 @@ Once every child has landed: ## Required -- [Memory benchmark](/quest/m1/cluster-routing/memory.md) - a committed benchmark states per-announcement, per-route, and per-peer relay memory, before anything changes - [Topology](/quest/m1/cluster-routing/topology.md) - relays learn the relay graph once from a cluster message, apart from routes - [Propagation](/quest/m1/cluster-routing/propagation.md) - decides how each announcement reaches every relay once, and writes the implementation children - [Selection](/quest/m1/cluster-routing/selection.md) - a broadcast under overlapping prefixes routes to one origin deterministically, and same-epoch origins are one source diff --git a/quest/m1/cluster-routing/memory.md b/quest/m1/cluster-routing/memory.md deleted file mode 100644 index a97d2e7b38d..00000000000 --- a/quest/m1/cluster-routing/memory.md +++ /dev/null @@ -1,46 +0,0 @@ -# [S] Relay memory benchmark - -## Goal - -A committed benchmark states what a relay's memory costs per announced -broadcast, per extra route, and per peer session, so the rest of -[Cluster routing](/quest/m1/cluster-routing/README.md) has a before figure and -reports its after figure against the same code. Chat-shaped traffic (one -broadcast per channel or per chatter) and Wildcard's "workers times -broadcasts" argument both depend on the answer. - -## Plan - -Every published figure is stale. The old baseline was 8.8 KB per announced -broadcast plus 4.3 KB per extra route on `adad52b`, measured with two -throwaway `moq-net` examples driving an origin under a counting allocator and -reading `/proc/self/statm`. Since then -[moq#2989](https://github.com/moq-dev/moq/pull/2989) cut `kio`'s inline waiter -slots from 32 to 4, and [moq#3225](https://github.com/moq-dev/moq/pull/3225) -made a standby route a table entry rather than an object graph. Neither -example was committed, since they needed `#[doc(hidden)]` size probes on -private types. - -- Measure through the public API with a counting allocator (as - `rs/moq-net/benches/session.rs` already does for groups), not private size - probes, so the benchmark survives the redesign. -- Sweep both axes: broadcasts announced, and peers each one is routed through, - so a cost that grows with the table rather than the touched path shows as a - slope. -- Keep two costs apart: the route table and per-announcement state - (`RouteEntry`, `ServeState` in `rs/moq-net/src/model/origin.rs`) scale with - announcements and routes, while the served-content cache a `ServeState` - materializes scales with demand. Per-peer bookkeeping is the lite - publisher's `live` map and `AnnounceEncoder` entries, the lite subscriber's - `Announced.routes`, and the IETF `watched` and `held`. -- Run it in the nightly benchmark job - ([Benchmark regressions in CI](/quest/m1/bench-ci.md)) or its own nightly - step if that has not landed. -- Record the before figures in the PR and in the questline README, and derive - the shed threshold on a degree-5, 1 GB node from them. The implementation - child that replaces per-peer routes reports the after figures. - -## Related - -- [Wildcard](/quest/m0/wildcard/README.md) - cites the stale figure -- [Benchmark regressions in CI](/quest/m1/bench-ci.md) - where the benchmark runs nightly diff --git a/quest/m1/cluster-routing/propagation.md b/quest/m1/cluster-routing/propagation.md index 1614b590ab9..283b0d20c78 100644 --- a/quest/m1/cluster-routing/propagation.md +++ b/quest/m1/cluster-routing/propagation.md @@ -36,8 +36,7 @@ Candidates to choose between or combine: prefix-shared paths, instead of per-event messages. Measure the choice with the simulator's scenarios (messages and bytes per -event, convergence, stale revival, restart, failover) and the -[Memory benchmark](/quest/m1/cluster-routing/memory.md)'s figures. +event, convergence, stale revival, restart, failover). Open questions the chosen design must answer: @@ -57,16 +56,11 @@ Open questions the chosen design must answer: The implementation quests it writes replace the empty-prefix ANNOUNCE_REQUEST between peers and per-hop path-vector announcements, drop `Hop Base` and -`Hop Keep` from the current wip lite version, and report the memory -benchmark's after figures. Add each one to the Required of +`Hop Keep` from the current wip lite version. Add each one to the Required of [Selection](/quest/m1/cluster-routing/selection.md) and [Routing between clusters](/quest/m1/cluster-routing/inter-cluster.md), so neither starts on a record shape that is not implemented yet. -## Required - -- [Memory benchmark](/quest/m1/cluster-routing/memory.md) - the before figures the choice is weighed against - ## Related - [Cross-relay delivery under bursts](/quest/m1/cross-relay-bursts.md) - its report of closed broadcasts announced for minutes is evidence for per-origin seqnos From d29985af7fdb10e66b98120ac295bc90b1913b45 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 12:51:08 -0700 Subject: [PATCH 116/128] fix(nix): keep the packaged relay unit in moq-relay's source (#4622) Co-authored-by: Claude Opus 5.5 --- nix/overlay.nix | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/nix/overlay.nix b/nix/overlay.nix index 6c5a7f1ce3a..e13c1f40516 100644 --- a/nix/overlay.nix +++ b/nix/overlay.nix @@ -49,7 +49,16 @@ let ); moqRelayArgs = crateInfo ../rs/moq-relay/Cargo.toml // { - src = cleanCargoSource; + # A config test `include_str!`s the packaged systemd unit so its ExecStart + # keeps parsing, and the default filter drops non-Cargo files. + src = final.lib.cleanSourceWith { + src = ../.; + name = "source"; + filter = + path: type: + (final.lib.hasSuffix "/packaging/moq-relay/moq-relay.service" path) + || (filterCargoSources path type); + }; cargoExtraArgs = "-p moq-relay --features jemalloc"; # Enable frame pointers for profiling support (negligible overhead on x86_64). # This also ensures the CDN build matches what Cachix caches. From 9157692f6a907a4af714182c999553150347daeb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 13:10:26 -0700 Subject: [PATCH 117/128] fix(demo): serve distinct HLS renditions (#4620) Co-authored-by: GPT-6 --- quest/m1/README.md | 1 - quest/m1/serve-hls-renditions.md | 15 --------------- sh/demo/serve-hls.sh | 8 ++++---- 3 files changed, 4 insertions(+), 20 deletions(-) delete mode 100644 quest/m1/serve-hls-renditions.md diff --git a/quest/m1/README.md b/quest/m1/README.md index c74d353d0b0..ff2fe1e7033 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -32,7 +32,6 @@ QUIC studies there on that rule. - [Raw stream codes](/quest/m1/raw-stream-codes.md) - raw QUIC stream resets and stops carry the application's code, not an HTTP/3-mapped one - [IETF drain before close](/quest/m1/ietf-drain-before-close.md) - moq-transport sessions deliver finished tracks before a graceful close, as moq-lite does - [Close waits for the tail](/quest/m1/close-tail.md) - on lite-07, `close()` returns `Ok` only after each subscriber FINs its Subscribe Stream, having read the track to its end -- [Demo serve-hls renditions](/quest/m1/serve-hls-renditions.md) - `just pub serve-hls` serves 720p and 144p instead of two 256-wide copies - [moq play drain tail](/quest/m1/play-drain-tail.md) - retired renditions and finite tracks play their last 10 ms of audio - [WebTransport close upstream](/quest/m1/wt-close-upstream.md) - web-transport-moq delivers the close capsule itself, and moq-tokio's `CLOSE_LINGER` is deleted - [Browser close code](/quest/m1/browser-close-code.md) - a playwright case proves the page reads a relay's close code and reason, on every web-transport backend diff --git a/quest/m1/serve-hls-renditions.md b/quest/m1/serve-hls-renditions.md deleted file mode 100644 index 36c0094f433..00000000000 --- a/quest/m1/serve-hls-renditions.md +++ /dev/null @@ -1,15 +0,0 @@ -# [XS] Demo serve-hls publishes distinct renditions - -## Goal - -`just pub serve-hls` serves two renditions at different resolutions, as -`just pub hls` does. Today both come out 256 wide: the `-vf:0` and `-vf:1` -options aren't per-stream in ffmpeg, so the last filter wins. - -## Plan - -Use per-stream filters (`-filter:v:0`, `-filter:v:1`), scaled to 720p and -144p to match `hls`. Scaling the 720p source up to 1080p couldn't encode in -real time on a dev machine. The recipe body lives in `sh/demo/serve-hls.sh`. -Check it by fetching `master.m3u8` and comparing the two renditions' -`RESOLUTION` attributes. diff --git a/sh/demo/serve-hls.sh b/sh/demo/serve-hls.sh index bf5257bc11a..e354a528d95 100755 --- a/sh/demo/serve-hls.sh +++ b/sh/demo/serve-hls.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash -# Encode media/NAME.mp4 into a looping HLS stream under media/NAME/ and serve -# it over HTTP on PORT, for testing HLS import. +# Encode media/NAME.mp4 into a looping HLS stream (720p + 360p + audio) +# under media/NAME/ and serve it over HTTP on PORT, for testing HLS import. # # Usage: sh/demo/serve-hls.sh NAME PORT, from demo/pub. set -euo pipefail @@ -21,8 +21,8 @@ echo ">>> Master playlist: http://localhost:$port/master.m3u8" ffmpeg -loglevel warning -re -stream_loop -1 -i "$input" \ -map 0:v:0 -map 0:v:0 -map 0:a:0 \ -r 25 -preset veryfast -g 50 -keyint_min 50 -sc_threshold 0 \ - -c:v:0 libx264 -profile:v:0 high -level:v:0 4.1 -pix_fmt:v:0 yuv420p -tag:v:0 avc1 -bsf:v:0 dump_extra -b:v:0 4M -vf:0 "scale=1920:-2" \ - -c:v:1 libx264 -profile:v:1 high -level:v:1 4.1 -pix_fmt:v:1 yuv420p -tag:v:1 avc1 -bsf:v:1 dump_extra -b:v:1 300k -vf:1 "scale=256:-2" \ + -c:v:0 libx264 -profile:v:0 high -level:v:0 4.1 -pix_fmt:v:0 yuv420p -tag:v:0 avc1 -bsf:v:0 dump_extra -b:v:0 4M -filter:v:0 "scale=-2:720" \ + -c:v:1 libx264 -profile:v:1 high -level:v:1 4.1 -pix_fmt:v:1 yuv420p -tag:v:1 avc1 -bsf:v:1 dump_extra -b:v:1 300k -filter:v:1 "scale=-2:360" \ -c:a aac -b:a 128k \ -f hls \ -hls_time 2 -hls_list_size 12 \ From d04baef4b1ebe6785fd89ed5a2ef5677e2ecfa7b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 13:49:53 -0700 Subject: [PATCH 118/128] fix(net): prune departed subscribers only when the list would grow (#4627) Co-authored-by: Claude Opus 5.5 --- rs/moq-net/benches/track.rs | 31 ++++++++++++++++++++++++++++++- rs/moq-net/src/model/track.rs | 16 ++++++++++++---- 2 files changed, 42 insertions(+), 5 deletions(-) diff --git a/rs/moq-net/benches/track.rs b/rs/moq-net/benches/track.rs index 79e4043bd24..fa18719b8a8 100644 --- a/rs/moq-net/benches/track.rs +++ b/rs/moq-net/benches/track.rs @@ -11,6 +11,9 @@ //! each departure wakes the producer's aggregate poll, which walks the subscription //! list, so departed entries left in the list show up as a slope over churn. //! +//! `track_subscriber_join` measures a burst of viewers joining one track: each join +//! registers in the subscription list, so any per-join walk of it shows up as a slope. +//! //! Run with `cargo bench -p moq-net --bench track`. use std::hint::black_box; @@ -40,6 +43,9 @@ const STEADY: [usize; 3] = [1, 8, 64]; /// Viewers that join and leave, one at a time, during one measured run. const CHURN: [usize; 3] = [8, 64, 512]; +/// Viewers that join at once and stay, during one measured run. +const JOIN: [usize; 3] = [64, 1024, 16384]; + /// Concurrent publishers sharing one relay-style cache pool. const WRITERS: [usize; 4] = [1, 2, 4, 8]; @@ -267,11 +273,34 @@ fn bench_subscriber_churn(c: &mut Criterion) { group.finish(); } +fn bench_subscriber_join(c: &mut Criterion) { + let mut group = c.benchmark_group("track_subscriber_join"); + for join in JOIN { + group.throughput(Throughput::Elements(join as u64)); + group.bench_with_input(BenchmarkId::from_parameter(join), &join, |b, &join| { + b.iter_batched( + || { + let broadcast = broadcast::Info::default().produce(); + let track = broadcast.create_track("bench", None).unwrap(); + (broadcast, track) + }, + |(broadcast, track)| { + let viewers: Vec<_> = (0..join).map(|_| track.subscribe(None)).collect(); + (broadcast, track, viewers) + }, + BatchSize::SmallInput, + ); + }); + } + group.finish(); +} + criterion_group!( benches, bench_fanout, bench_parallel_write, bench_aborted_scan, - bench_subscriber_churn + bench_subscriber_churn, + bench_subscriber_join ); criterion_main!(benches); diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 96702bb84ce..d1aa3d10233 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -2112,8 +2112,9 @@ fn clamp_combined(combined: Option, bound: Option) -> Op /// /// Departed subscribers are pruned here too. The aggregate poll only prunes when the /// aggregate changes, so churning subscribers with the same preferences as a steady -/// one would otherwise pile up and be walked on every wake. Pruning on push bounds the -/// list by its peak live count, and the push already wakes the pollers. +/// one would otherwise pile up and be walked on every wake. Pruning on every push would +/// make a burst of N joins O(N^2), so, like `kio::WaiterList::register`, it only sweeps +/// when the list is about to grow. fn register_subscription(state: kio::Ref<'_, TrackState>, subscription: &kio::Producer) { if state.is_closed() { return; @@ -2121,7 +2122,12 @@ fn register_subscription(state: kio::Ref<'_, TrackState>, subscription: &kio::Pr let subs = state.subscriptions.clone(); drop(state); let mut subs = subs.lock(); - subs.retain(|sub| !sub.is_closed()); + if subs.len() == subs.capacity() { + subs.retain(|sub| !sub.is_closed()); + // Leave at least half free, so each sweep is paid for by the pushes before it. + let live = subs.len(); + subs.reserve(live); + } subs.push(subscription.consume()); } @@ -5588,8 +5594,10 @@ mod test { } let subs = producer.state.read().subscriptions.clone(); + // The list sweeps only when about to grow, so it holds a small multiple of the + // peak live count (2) rather than all 200 departures. let len = subs.read().len(); - assert!(len <= 2, "departed subscribers accumulated: {len}"); + assert!(len <= 8, "departed subscribers accumulated: {len}"); } /// Append a finished group presenting at `millis`, so the track carries a media From 8af3855342c47a16e2a2481d5f299dc8168ddfd5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 14:27:17 -0700 Subject: [PATCH 119/128] fix(json): bound decoded snapshots and accumulated patches (#4632) Co-authored-by: Codex --- rs/moq-json/benches/codec.rs | 27 ++++- rs/moq-json/src/lib.rs | 4 + rs/moq-json/src/snapshot/consumer.rs | 4 + rs/moq-json/src/snapshot/decoder.rs | 171 +++++++++++++++++++++++---- rs/moq-json/src/snapshot/mod.rs | 1 + 5 files changed, 182 insertions(+), 25 deletions(-) diff --git a/rs/moq-json/benches/codec.rs b/rs/moq-json/benches/codec.rs index 1c9c3a6999a..fd2d2f58c62 100644 --- a/rs/moq-json/benches/codec.rs +++ b/rs/moq-json/benches/codec.rs @@ -375,6 +375,30 @@ fn consumer(c: &mut Criterion) { group.finish(); } +fn snapshot_budget(c: &mut Criterion) { + let mut group = c.benchmark_group("snapshot_budget"); + for entries in [100, 1000, 10000] { + let value: Map = (0..entries) + .map(|i| (format!("path-{i}"), json!({"bytes": 123}))) + .collect(); + let bytes = serde_json::to_vec(&value).unwrap(); + for bounded in [false, true] { + group.bench_with_input( + BenchmarkId::new(if bounded { "bounded" } else { "unbounded" }, entries), + &bytes, + |b, bytes| { + let mut config = moq_json::snapshot::consumer::Config::default(); + config.max_size = bounded.then_some(8 * 1024 * 1024); + let mut decoder = moq_json::snapshot::Decoder::::new(config); + decoder.snapshot(bytes).unwrap(); + b.iter(|| decoder.delta(black_box(br#"{"path-0":{"bytes":124}}"#)).unwrap()); + }, + ); + } + } + group.finish(); +} + criterion_group!( benches, encode_patch, @@ -384,6 +408,7 @@ criterion_group!( marshal, baseline, producer, - consumer + consumer, + snapshot_budget ); criterion_main!(benches); diff --git a/rs/moq-json/src/lib.rs b/rs/moq-json/src/lib.rs index 8683f64964d..656f62b114a 100644 --- a/rs/moq-json/src/lib.rs +++ b/rs/moq-json/src/lib.rs @@ -84,6 +84,10 @@ pub enum Error { /// a continuous log. #[error("stream rolled to a second group")] Rolled, + + /// A decoded frame or reconstructed snapshot exceeded its configured byte budget. + #[error("decoded JSON exceeded {0} bytes")] + TooLarge(usize), } impl From for Error { diff --git a/rs/moq-json/src/snapshot/consumer.rs b/rs/moq-json/src/snapshot/consumer.rs index 536d5752cf4..7457b8b947b 100644 --- a/rs/moq-json/src/snapshot/consumer.rs +++ b/rs/moq-json/src/snapshot/consumer.rs @@ -17,6 +17,10 @@ pub struct Config { /// How the frames are compressed. Must match the encoder's /// [`Config::compression`](super::Config::compression). Defaults to [`Compression::None`]. pub compression: Compression, + + /// Maximum bytes in an inflated frame or the compact JSON of the reconstructed value. + /// Unset preserves the DEFLATE decoder's default frame cap and leaves state size unlimited. + pub max_size: Option, } /// Consumes a JSON value from a track, reconstructing it from snapshots and deltas. diff --git a/rs/moq-json/src/snapshot/decoder.rs b/rs/moq-json/src/snapshot/decoder.rs index e2782df42f5..31ece91018f 100644 --- a/rs/moq-json/src/snapshot/decoder.rs +++ b/rs/moq-json/src/snapshot/decoder.rs @@ -31,6 +31,7 @@ use crate::{Error, Result}; pub struct Decoder { /// Whether frames are DEFLATE-compressed, matching the encoder's config. compression: bool, + max_size: Option, /// The current group's DEFLATE decoder (one window per group), rebuilt at each snapshot. flate: Option, @@ -52,6 +53,7 @@ impl Decoder { pub fn new(config: Config) -> Self { Self { compression: config.compression.is_deflate(), + max_size: config.max_size, flate: None, plain: Vec::new(), check: RefCell::new(crate::merge::CheckScratch::default()), @@ -65,37 +67,65 @@ impl Decoder { /// Also starts the group's DEFLATE window, so this must be called at every group boundary, not /// only the first. pub fn snapshot(&mut self, payload: &[u8]) -> Result<()> { - // Each group is its own compressed stream, so the window starts cold here. - self.flate = self.compression.then(moq_flate::Decoder::new); - self.current = Some(match self.flate.as_mut() { - Some(flate) => serde_json::from_slice(&flate.frame(payload)?)?, - None => serde_json::from_slice(payload)?, + self.current = None; + // Every group starts a new DEFLATE window; enforce the budget while inflating. + self.flate = self.compression.then(|| { + moq_flate::Decoder::with_max_frame_size(self.max_size.map_or(moq_flate::DEFAULT_MAX_FRAME_SIZE, |size| { + (size as u64).min(moq_flate::DEFAULT_MAX_FRAME_SIZE) + })) }); - Ok(()) + let inflated = self.flate.as_mut().map(|flate| flate.frame(payload)).transpose()?; + let plain = inflated.as_deref().unwrap_or(payload); + if let Some(limit) = self.max_size + && plain.len() > limit + { + return Err(Error::TooLarge(limit)); + } + self.current = Some(serde_json::from_slice(plain)?); + self.check_size() } - /// Apply one of a group's later frames: an [RFC 7396](https://www.rfc-editor.org/rfc/rfc7396.html) - /// merge patch against the current value. - /// - /// Errors with [`Error::MissingSnapshot`] when no snapshot has been applied yet, since a patch - /// has nothing to apply to. + /// Apply a merge patch, refusing frames or reconstructed state beyond the configured budget. + /// A failed patch invalidates the baseline; start a new snapshot before applying more deltas. pub fn delta(&mut self, payload: &[u8]) -> Result<()> { if self.current.is_none() { return Err(Error::MissingSnapshot); } - - let plain = match self.flate.as_mut() { - Some(flate) => { - flate.frame_into(payload, &mut self.plain)?; - self.plain.as_slice() + let result = (|| { + let plain = match self.flate.as_mut() { + Some(flate) => { + flate.frame_into(payload, &mut self.plain)?; + self.plain.as_slice() + } + None => payload, + }; + if let Some(limit) = self.max_size + && plain.len() > limit + { + return Err(Error::TooLarge(limit)); } - None => payload, - }; - crate::merge::apply_bytes( - self.current.as_mut().expect("a snapshot precedes any delta"), - plain, - &self.check, - )?; + crate::merge::apply_bytes( + self.current.as_mut().expect("a snapshot precedes any delta"), + plain, + &self.check, + )?; + self.check_size() + })(); + if result.is_err() { + self.current = None; + } + result + } + + fn check_size(&mut self) -> Result<()> { + let Some(limit) = self.max_size else { return Ok(()) }; + // Count the compact representation without allocating another full snapshot. + // A patch and the prior state are each bounded, and an oversized result is + // released before it can be materialized or used by another patch. + if serde_json::to_writer(Budget(limit), self.current.as_ref().unwrap()).is_err() { + self.current = None; + return Err(Error::TooLarge(limit)); + } Ok(()) } @@ -105,6 +135,22 @@ impl Decoder { } } +struct Budget(usize); + +impl std::io::Write for Budget { + fn write(&mut self, bytes: &[u8]) -> std::io::Result { + if bytes.len() > self.0 { + return Err(std::io::Error::other("JSON size budget exceeded")); + } + self.0 -= bytes.len(); + Ok(bytes.len()) + } + + fn flush(&mut self) -> std::io::Result<()> { + Ok(()) + } +} + impl Decoder { /// Materialize the reconstructed value as `T`, or `None` before the first snapshot. /// @@ -145,7 +191,10 @@ mod test { use serde_json::{Value, json}; fn consume(compression: Compression) -> ConsumerConfig { - ConsumerConfig { compression } + ConsumerConfig { + compression, + ..Default::default() + } } fn deflate() -> Config { @@ -177,6 +226,80 @@ mod test { out } + #[test] + fn inflated_snapshots_and_patches_obey_the_budget() { + for snapshot in [true, false] { + let mut config = consume(Compression::Deflate); + config.max_size = Some(1024); + let mut decoder = Decoder::::new(config); + let mut encoder = moq_flate::Encoder::new(); + if !snapshot { + decoder.snapshot(&encoder.frame(b"{}")).unwrap(); + } + let payload = encoder.frame( + serde_json::to_string(&json!({"large": "x".repeat(4096)})) + .unwrap() + .as_bytes(), + ); + assert!(payload.len() < 1024); + let result = if snapshot { + decoder.snapshot(&payload) + } else { + decoder.delta(&payload) + }; + assert!(matches!(result, Err(Error::Flate(moq_flate::Error::TooLarge(1024))))); + assert!(decoder.value().is_none()); + } + } + + #[test] + fn patches_cannot_accumulate_past_the_budget() { + for compression in [Compression::None, Compression::Deflate] { + let mut config = consume(compression); + config.max_size = Some(13); + let mut decoder = Decoder::::new(config); + let mut encoder = moq_flate::Encoder::new(); + let mut payload = |bytes: &[u8]| { + if compression == Compression::Deflate { + encoder.frame(bytes).to_vec() + } else { + bytes.to_vec() + } + }; + decoder.snapshot(&payload(br#"{"a":1}"#)).unwrap(); + decoder.delta(&payload(br#"{"b":2}"#)).unwrap(); // exactly 13 bytes + assert_eq!(decoder.value(), Some(&json!({"a":1,"b":2}))); + decoder.delta(&payload(br#"{"a":null}"#)).unwrap(); // deletion frees budget + decoder.delta(&payload(br#"{"c":3}"#)).unwrap(); + assert!(matches!( + decoder.delta(&payload(br#"{"d":4}"#)), + Err(Error::TooLarge(13)) + )); + assert!(decoder.value().is_none()); + assert!(matches!(decoder.delta(b"{}"), Err(Error::MissingSnapshot))); + // A fresh group can recover after refusal. + let bytes = if compression == Compression::Deflate { + moq_flate::Encoder::new().frame(b"{}").to_vec() + } else { + b"{}".to_vec() + }; + decoder.snapshot(&bytes).unwrap(); + } + } + + #[test] + fn plain_frames_obey_the_budget_before_parsing() { + let config = ConsumerConfig { + max_size: Some(2), + ..Default::default() + }; + let mut decoder = Decoder::::new(config); + assert!(matches!(decoder.snapshot(b"not json"), Err(Error::TooLarge(2)))); + decoder.snapshot(b"{}").unwrap(); + assert!(matches!(decoder.delta(b"not json"), Err(Error::TooLarge(2)))); + assert!(decoder.value().is_none()); + } + #[test] fn plaintext_roundtrip() { let values = vec![ diff --git a/rs/moq-json/src/snapshot/mod.rs b/rs/moq-json/src/snapshot/mod.rs index 9b86d81e8d4..761ccaf0094 100644 --- a/rs/moq-json/src/snapshot/mod.rs +++ b/rs/moq-json/src/snapshot/mod.rs @@ -76,6 +76,7 @@ mod test { track, consumer::Config { compression: Compression::Deflate, + ..Default::default() }, ) } From 1bbbdbb784b538c1483614d60a49283779f66356 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 14:40:52 -0700 Subject: [PATCH 120/128] fix(net): prune departed subscribers on every aggregate wake (#4633) Co-authored-by: Claude Opus 5.5 --- rs/moq-net/benches/track.rs | 30 ++++++++- rs/moq-net/src/model/track.rs | 121 ++++++++++++++++++++-------------- 2 files changed, 100 insertions(+), 51 deletions(-) diff --git a/rs/moq-net/benches/track.rs b/rs/moq-net/benches/track.rs index fa18719b8a8..14f7661d3b0 100644 --- a/rs/moq-net/benches/track.rs +++ b/rs/moq-net/benches/track.rs @@ -10,6 +10,8 @@ //! `track_subscriber_churn` measures viewers joining and leaving beside steady ones: //! each departure wakes the producer's aggregate poll, which walks the subscription //! list, so departed entries left in the list show up as a slope over churn. +//! `track_subscriber_churn_after_peak` runs the same churn after a departed audience, +//! so entries walked in proportion to the old peak show up as a slope over it. //! //! `track_subscriber_join` measures a burst of viewers joining one track: each join //! registers in the subscription list, so any per-join walk of it shows up as a slope. @@ -46,6 +48,9 @@ const CHURN: [usize; 3] = [8, 64, 512]; /// Viewers that join at once and stay, during one measured run. const JOIN: [usize; 3] = [64, 1024, 16384]; +/// Viewers that joined and left before the churn, leaving the list room for that many. +const PEAK: [usize; 3] = [0, 1024, 16384]; + /// Concurrent publishers sharing one relay-style cache pool. const WRITERS: [usize; 4] = [1, 2, 4, 8]; @@ -148,12 +153,16 @@ struct Churn { } impl Churn { - fn new(steady: usize) -> Self { + /// `peak` more viewers join and leave first, and the aggregate poll sees them go. + fn new(steady: usize, peak: usize) -> Self { let broadcast = broadcast::Info::default().produce(); let mut track = broadcast.create_track("bench", None).unwrap(); let steady = (0..steady).map(|_| track.subscribe(None)).collect(); + let peak: Vec<_> = (0..peak).map(|_| track.subscribe(None)).collect(); let waiter = kio::Waiter::noop(); assert!(track.poll_subscription_changed(&waiter).is_ready()); + drop(peak); + assert!(track.poll_subscription_changed(&waiter).is_pending()); Self { _broadcast: broadcast, @@ -265,7 +274,11 @@ fn bench_subscriber_churn(c: &mut Criterion) { BenchmarkId::new(format!("steady_{steady}"), churn), &churn, |b, &churn| { - b.iter_batched_ref(|| Churn::new(steady), |setup| setup.run(churn), BatchSize::SmallInput); + b.iter_batched_ref( + || Churn::new(steady, 0), + |setup| setup.run(churn), + BatchSize::SmallInput, + ); }, ); } @@ -273,6 +286,18 @@ fn bench_subscriber_churn(c: &mut Criterion) { group.finish(); } +fn bench_subscriber_churn_after_peak(c: &mut Criterion) { + const CHURN: usize = 512; + let mut group = c.benchmark_group("track_subscriber_churn_after_peak"); + group.throughput(Throughput::Elements(CHURN as u64)); + for peak in PEAK { + group.bench_with_input(BenchmarkId::from_parameter(peak), &peak, |b, &peak| { + b.iter_batched_ref(|| Churn::new(1, peak), |setup| setup.run(CHURN), BatchSize::SmallInput); + }); + } + group.finish(); +} + fn bench_subscriber_join(c: &mut Criterion) { let mut group = c.benchmark_group("track_subscriber_join"); for join in JOIN { @@ -301,6 +326,7 @@ criterion_group!( bench_parallel_write, bench_aborted_scan, bench_subscriber_churn, + bench_subscriber_churn_after_peak, bench_subscriber_join ); criterion_main!(benches); diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index d1aa3d10233..77edf9ce98f 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -1749,22 +1749,7 @@ impl Producer { let (subs, bound) = (state.subscriptions.clone(), state.max_age_bound()); drop(state); - let prev = &self.prev_subscription; - let mut combined = None; - let mut guard = ready!(subs.poll(waiter, |subs| { - let next = combined_subscription(subs, bound, waiter); - if &next == prev { - Poll::Pending - } else { - combined = next; - Poll::Ready(()) - } - })); - // The aggregate changed: prune any closed subscribers now that we hold the lock. - guard.retain(|sub| !sub.is_closed()); - drop(guard); - self.prev_subscription = combined.clone(); - Poll::Ready(Ok(combined)) + poll_combined_changed(&subs, bound, &mut self.prev_subscription, waiter).map(Ok) } /// Poll for the producer becoming unused (every consumer dropped). @@ -2008,19 +1993,60 @@ impl Drop for Alive { } } -/// Aggregate every live subscriber's preferences into the most demanding request. +/// Poll until the aggregate across `subs` differs from `prev`, then store and return it. +/// +/// Departed subscribers are pruned whenever the scan meets one, even when the aggregate +/// holds. Churn with a steady viewer's preferences never changes it, so otherwise every +/// wake would walk every departed entry the list has room for since its peak. +fn poll_combined_changed( + subs: &kio::Shared, + bound: Option, + prev: &mut Option, + waiter: &kio::Waiter, +) -> Poll> { + loop { + let mut next = None; + let mut departed = false; + let mut guard = ready!(subs.poll(waiter, |subs| { + (next, departed) = combined_subscription(subs, bound, waiter); + if departed || next != *prev { + Poll::Ready(()) + } else { + Poll::Pending + } + })); + if departed { + guard.retain(|sub| !sub.is_closed()); + } + drop(guard); + if next != *prev { + *prev = next.clone(); + return Poll::Ready(next); + } + // Only pruned: a ready poll skips registering, so poll again to park on the list. + } +} + +/// Aggregate every live subscriber's preferences into the most demanding request, and +/// report whether any departed subscriber is still listed. /// /// Read-only: iterates the subscriptions immutably and registers `waiter` on each, so a /// preference update (or a subscriber dropping) wakes the caller's poll. Callers decide /// readiness from the returned value, then prune closed subscribers through the `Mut`. -fn combined_subscription(subs: &Subscriptions, bound: Option, waiter: &kio::Waiter) -> Option { +fn combined_subscription( + subs: &Subscriptions, + bound: Option, + waiter: &kio::Waiter, +) -> (Option, bool) { let mut combined = None; + let mut departed = false; for sub in subs.iter() { // A closed consumer means the subscriber dropped: it holds no live demand. // `Consumer::poll` evaluates the closure before the closed flag, so it would // still replay the final value into the aggregate; skip it explicitly so a // departed subscriber can't keep the aggregate pinned to its last request. if sub.is_closed() { + departed = true; continue; } // Arm both waiters explicitly. `poll` registers on the value channel only @@ -2035,7 +2061,7 @@ fn combined_subscription(subs: &Subscriptions, bound: Option, waiter: combined = Some(merged); } } - clamp_combined(combined, bound) + (clamp_combined(combined, bound), departed) } /// A non-blocking aggregate of the current subscriptions, without arming any waiter. @@ -2110,11 +2136,9 @@ fn clamp_combined(combined: Option, bound: Option) -> Op /// state, release the track lock, then push under the list's own lock. A closed /// track skips the push; nothing aggregates the preferences anymore. /// -/// Departed subscribers are pruned here too. The aggregate poll only prunes when the -/// aggregate changes, so churning subscribers with the same preferences as a steady -/// one would otherwise pile up and be walked on every wake. Pruning on every push would -/// make a burst of N joins O(N^2), so, like `kio::WaiterList::register`, it only sweeps -/// when the list is about to grow. +/// Departed subscribers are pruned here too, so the list stays bounded on a track whose +/// aggregate nobody polls. Pruning on every push would make a burst of N joins O(N^2), +/// so, like `kio::WaiterList::register`, it only sweeps when the list is about to grow. fn register_subscription(state: kio::Ref<'_, TrackState>, subscription: &kio::Producer) { if state.is_closed() { return; @@ -4444,22 +4468,7 @@ impl Request { let (subs, bound) = (state.subscriptions.clone(), state.max_age_bound()); drop(state); - let prev = &self.prev_subscription; - let mut combined = None; - let mut guard = ready!(subs.poll(waiter, |subs| { - let next = combined_subscription(subs, bound, waiter); - if &next == prev { - Poll::Pending - } else { - combined = next; - Poll::Ready(()) - } - })); - // The aggregate changed: prune any closed subscribers now that we hold the lock. - guard.retain(|sub| !sub.is_closed()); - drop(guard); - self.prev_subscription = combined.clone(); - Poll::Ready(combined) + poll_combined_changed(&subs, bound, &mut self.prev_subscription, waiter) } pub(super) fn weak(&self) -> TrackWeak { @@ -5578,28 +5587,42 @@ mod test { #[test] fn churned_subscribers_do_not_accumulate() { - let mut producer = track_producer("test", None); + let producer = track_producer("test", None); let consumer = producer.consume(); - let waiter = kio::Waiter::noop(); - let _steady = producer.subscribe(None); - assert!(producer.poll_subscription_changed(&waiter).is_ready()); - // Identical preferences leave the aggregate unchanged, so the poll never - // reaches its own prune; registration has to drop the departed entries. + // Nobody polls the aggregate here, so registration alone has to bound the list. for _ in 0..100 { drop(producer.subscribe(None)); drop(consumer.subscribe(None)); - assert!(producer.poll_subscription_changed(&waiter).is_pending()); } + // Registration sweeps only when the list is about to grow, so it holds a small + // multiple of the peak live count (2) rather than all 200 departures. let subs = producer.state.read().subscriptions.clone(); - // The list sweeps only when about to grow, so it holds a small multiple of the - // peak live count (2) rather than all 200 departures. let len = subs.read().len(); assert!(len <= 8, "departed subscribers accumulated: {len}"); } + #[test] + fn aggregate_poll_prunes_after_a_peak() { + let mut producer = track_producer("test", None); + let waiter = kio::Waiter::noop(); + let _steady = producer.subscribe(None); + assert!(producer.poll_subscription_changed(&waiter).is_ready()); + + // A departed burst leaves room for many entries, and identical preferences never + // change the aggregate, so each wake has to prune what it walks. + drop((0..1000).map(|_| producer.subscribe(None)).collect::>()); + for _ in 0..100 { + drop(producer.subscribe(None)); + assert!(producer.poll_subscription_changed(&waiter).is_pending()); + + let subs = producer.state.read().subscriptions.clone(); + assert_eq!(subs.read().len(), 1, "the poll walked past departed subscribers"); + } + } + /// Append a finished group presenting at `millis`, so the track carries a media /// timeline for the drift budget to measure against. fn append_at(producer: &mut Producer, millis: u64) -> u64 { From 400b89a6ed3c3411ba0e5b326a9faa1bcd41f9fb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 14:44:46 -0700 Subject: [PATCH 121/128] perf(net): share route ranking across announcement cursors (#4634) Co-authored-by: GPT-6 --- rs/moq-net/benches/origin.rs | 69 +++++++++++-- rs/moq-net/src/model/origin.rs | 177 +++++++++++++++++++++++++-------- 2 files changed, 198 insertions(+), 48 deletions(-) diff --git a/rs/moq-net/benches/origin.rs b/rs/moq-net/benches/origin.rs index 62692ebd9d2..a07846379ef 100644 --- a/rs/moq-net/benches/origin.rs +++ b/rs/moq-net/benches/origin.rs @@ -5,8 +5,8 @@ //! (cursors), so a cost that grows with the size of the table rather than with //! the tree around the touched path shows up as a slope. The table is a trie //! keyed by path segment: an announcement visits only the cursors on the walk -//! down to its prefix and beneath it, and each recomputes its best route from -//! the entries at that prefix alone. +//! down to its prefix and beneath it. Competing routes at that prefix are +//! ranked once per change, then each cursor selects its first visible entry. //! //! Run with `cargo bench -p moq-net --bench origin`. @@ -20,9 +20,9 @@ use moq_net::{Hop, Hops, Pattern, Patterns, Timestamp, announce, broadcast, kio, const SHAPES: [(usize, usize); 3] = [(100, 10), (1_000, 100), (1_000, 1_000)]; /// `(duplicates, subscribers)` shapes for one *contended* prefix: how many -/// routes cover the same path, against how many cursors watch it. The first row -/// is a live fleet's mesh width; the rest sweep past it so the slope is visible. -const CONTENDED: [(usize, usize); 4] = [(30, 30), (60, 60), (240, 60), (240, 240)]; +/// routes cover the same path, against how many cursors watch it. Includes +/// sparse fanout, a live fleet's mesh width, and larger contended tables. +const CONTENDED: [(usize, usize); 6] = [(1, 1), (30, 1), (30, 30), (60, 60), (240, 60), (240, 240)]; /// An origin with `publishers` broadcasts under `room/` and `subscribers` /// cursors watching everything. The handles are held: dropping a broadcast @@ -175,8 +175,7 @@ fn bench_announce_fleet(c: &mut Criterion) { /// publisher produces. A mesh produces the other one: the same path arrives /// once per peer it can travel through, so a prefix carries one entry per peer. /// The trie narrows a change to the touched prefix, but picking the winner -/// there still visits every entry at it, once per watching cursor, so both are -/// swept. +/// there shares the ranking across its watching cursors, so both are swept. /// /// The arriving route is priced below every incumbent so it takes the prefix /// outright: each cursor is told twice per iteration, once for the new winner @@ -219,6 +218,61 @@ fn bench_announce_duplicate(c: &mut Criterion) { group.finish(); } +/// Re-price a live mesh route with cursors watching different scopes. +/// The challenger alternates between winning and losing, so selection must +/// honor each cursor's scope rather than reuse one global winner. +fn bench_reprice_duplicate(c: &mut Criterion) { + let mut group = c.benchmark_group("origin/reprice_duplicate"); + for (duplicates, subscribers) in CONTENDED { + let id = BenchmarkId::from_parameter(format!("{duplicates}d_{subscribers}s")); + group.bench_function(id, |b| { + let (producer, _driver) = origin::Producer::new(origin::Config::default()); + let _routes: Vec<_> = (1..=duplicates) + .map(|peer| { + producer + .scope( + "", + &Patterns::from(Pattern::subtree(&format!("{PATH}/p{}", (peer - 1) % 2)).unwrap()), + ) + .unwrap() + .dynamic(PATH, peer_route(peer as u64, INCUMBENT_COST)) + .unwrap() + }) + .collect(); + let challenger = duplicates as u64 + 1; + let route = producer + .dynamic(PATH, peer_route(challenger, INCUMBENT_COST + 1)) + .unwrap(); + let mut cursors: Vec = (0..subscribers) + .map(|peer| { + producer + .consume() + .scope( + "", + &Patterns::from(Pattern::subtree(&format!("{PATH}/p{}", peer % 2)).unwrap()), + ) + .unwrap() + .with_hidden(true) + .announced() + }) + .collect(); + for cursor in &mut cursors { + while cursor.next().now_or_never().flatten().is_some() {} + } + b.iter(|| { + for cost in [INCUMBENT_COST - 1, INCUMBENT_COST + 1] { + route.update(peer_route(challenger, cost)).unwrap(); + for cursor in &mut cursors { + let update = cursor.next().now_or_never().flatten().expect("winner changed"); + assert_eq!(update.route.cost, moq_net::origin::Cost::new(cost.min(INCUMBENT_COST))); + } + } + }); + }); + } + group.finish(); +} + /// The contended path: one node's stats feed, which every peer in the mesh /// carries a route to. const PATH: &str = ".stats/p0/node/edge0"; @@ -429,6 +483,7 @@ criterion_group!( bench_announce_mounted, bench_announce_fleet, bench_announce_duplicate, + bench_reprice_duplicate, bench_announce_fronts, bench_serve_idle, bench_subscribe, diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 2758b39347f..4413b418da6 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -1001,6 +1001,50 @@ impl TableCursor { && self.named.as_ref().is_none_or(|(mount, _)| mount.names(&entry.prefix)) } + /// Deliver a changed winner at this presented prefix. + fn update(&mut self, presented: &PathOwned, best: Option<&RouteEntry>) { + match best { + Some(entry) => { + let meta = (entry.hops.clone(), entry.cost, entry.entered()); + let served = entry.server.is_some(); + let captures = self.captures(&entry.prefix); + let previous = self + .current + .insert(presented.clone(), (entry.id, meta.clone(), served, captures.clone())); + match previous { + // Unchanged metadata and servability: nothing the consumer could + // act on, even if the winning entry itself changed (a reconnect + // under an identical route is invisible, which is the point). A + // servability flip is delivered: a request that failed Unroutable + // under an advertise-only route retries on the update, and hiding + // it would park that waiter forever. + Some((_, prev, prev_served, prev_captures)) + if prev == meta && prev_served == served && prev_captures == captures => {} + // Captures are consumer identity, not route metadata. Replace the + // old identity explicitly so capture-keyed consumers can remove it. + Some((_, prev, _, prev_captures)) if prev_captures != captures => { + if let Ok(mut state) = self.state.write() { + state.apply_unannounce(self.under.join(presented), prev, prev_captures); + state.apply_announce(self.under.join(presented), meta, captures); + } + } + _ => { + if let Ok(mut state) = self.state.write() { + state.apply_announce(self.under.join(presented), meta, captures); + } + } + } + } + None => { + if let Some((_, last, _, captures)) = self.current.remove(presented) + && let Ok(mut state) = self.state.write() + { + state.apply_unannounce(self.under.join(presented), last, captures); + } + } + } + } + /// Whether the hidden rule lets this cursor discover a route at `prefix`. fn discovers(&self, prefix: &Path) -> bool { self.hidden.discovers(&self.heads, prefix) @@ -3206,12 +3250,32 @@ impl OriginState { fn sync_route(&mut self, prefix: &Path, claim: &Pattern) { // Split borrows: the recompute reads `routes` while mutating a cursor. let routes = &self.routes; + let mut candidates = None; for id in routes.cursors_touching(prefix) { let Some(cursor) = self.cursors.get_mut(&id) else { continue; }; if let Some(presented) = cursor.presented(prefix, claim) { - Self::sync_cursor(routes, cursor, &presented); + if presented.is_empty() { + // A cursor root can collapse several covering prefixes into one. + Self::sync_cursor(routes, cursor, &presented); + } else { + // Every non-root presentation refers to this exact prefix. Rank + // its routes once, then take each cursor's first visible entry. + let candidates = candidates.get_or_insert_with(|| { + let mut entries: Vec<_> = routes + .at(prefix) + .map(|entry| (route_order(prefix, entry), entry)) + .collect(); + entries.sort_unstable_by_key(|(order, _)| *order); + entries + }); + let best = candidates + .iter() + .map(|(_, entry)| *entry) + .find(|entry| cursor.visible(entry)); + cursor.update(&presented, best); + } } } // The fronts and requesters under the prefix re-select from the table. @@ -3257,46 +3321,7 @@ impl OriginState { .min_by_key(|entry| route_order(&entry.prefix, entry)) }); - match best { - Some(entry) => { - let meta = (entry.hops.clone(), entry.cost, entry.entered()); - let served = entry.server.is_some(); - let captures = cursor.captures(&entry.prefix); - let previous = cursor - .current - .insert(presented.clone(), (entry.id, meta.clone(), served, captures.clone())); - match previous { - // Unchanged metadata and servability: nothing the consumer could - // act on, even if the winning entry itself changed (a reconnect - // under an identical route is invisible, which is the point). A - // servability flip is delivered: a request that failed Unroutable - // under an advertise-only route retries on the update, and hiding - // it would park that waiter forever. - Some((_, prev, prev_served, prev_captures)) - if prev == meta && prev_served == served && prev_captures == captures => {} - // Captures are consumer identity, not route metadata. Replace the - // old identity explicitly so capture-keyed consumers can remove it. - Some((_, prev, _, prev_captures)) if prev_captures != captures => { - if let Ok(mut state) = cursor.state.write() { - state.apply_unannounce(cursor.under.join(presented), prev, prev_captures); - state.apply_announce(cursor.under.join(presented), meta, captures); - } - } - _ => { - if let Ok(mut state) = cursor.state.write() { - state.apply_announce(cursor.under.join(presented), meta, captures); - } - } - } - } - None => { - if let Some((_, last, _, captures)) = cursor.current.remove(presented) - && let Ok(mut state) = cursor.state.write() - { - state.apply_unannounce(cursor.under.join(presented), last, captures); - } - } - } + cursor.update(presented, best); } /// Register a cursor and replay the current best route per presented prefix. @@ -6104,6 +6129,76 @@ mod tests { assert_eq!(video.assert_next_active("").cost, Cost::new(5)); } + #[tokio::test] + async fn route_changes_preserve_each_cursors_visible_winner() { + let producer = origin(1).produce(); + let consumer = producer.consume(); + let mut all = consumer.clone().announced(); + let mut excluded = consumer.clone().excluding(origin(7)).announced(); + let mut video = consumer + .clone() + .scope("", &scopes(&["room/live/video"])) + .unwrap() + .announced(); + let mut rooted = consumer + .scope("room/live", &Patterns::from(Pattern::all())) + .unwrap() + .announced(); + + let chat = producer + .scope("", &scopes(&["room/live/chat"])) + .unwrap() + .dynamic("room/live", Route::default().with_hops(hops(&[7])).with_cost(1)) + .unwrap(); + assert_eq!(all.assert_next_active("room/live").cost, Cost::new(1)); + assert_eq!(rooted.assert_next_active("").cost, Cost::new(1)); + excluded.assert_next_wait(); + video.assert_next_wait(); + + let video_route = producer + .scope("", &scopes(&["room/live/video"])) + .unwrap() + .dynamic("room/live", Route::default().with_hops(hops(&[8])).with_cost(5)) + .unwrap(); + all.assert_next_wait(); + rooted.assert_next_wait(); + assert_eq!(excluded.assert_next_active("room/live").cost, Cost::new(5)); + assert_eq!(video.assert_next_active("room/live").cost, Cost::new(5)); + + chat.update(Route::default().with_hops(hops(&[7])).with_cost(9)) + .unwrap(); + assert_eq!(all.assert_next_active("room/live").cost, Cost::new(5)); + assert_eq!(rooted.assert_next_active("").cost, Cost::new(5)); + excluded.assert_next_wait(); + video.assert_next_wait(); + + drop(video_route); + assert_eq!(all.assert_next_active("room/live").cost, Cost::new(9)); + assert_eq!(rooted.assert_next_active("").cost, Cost::new(9)); + excluded.assert_next_ended("room/live"); + video.assert_next_ended("room/live"); + } + + #[tokio::test] + async fn root_cursor_keeps_the_more_specific_covering_route() { + let producer = origin(1).produce(); + let broad = producer.dynamic("room", Route::default().with_cost(1)).unwrap(); + let narrow = producer.dynamic("room/live", Route::default().with_cost(9)).unwrap(); + let mut announced = producer + .consume() + .scope("room/live/video", &Patterns::from(Pattern::all())) + .unwrap() + .announced(); + assert_eq!(announced.assert_next_active("").cost, Cost::new(9)); + + broad.update(Route::default().with_cost(0)).unwrap(); + announced.assert_next_wait(); + narrow.update(Route::default().with_cost(8)).unwrap(); + assert_eq!(announced.assert_next_active("").cost, Cost::new(8)); + drop(narrow); + assert_eq!(announced.assert_next_active("").cost, Cost::new(0)); + } + #[tokio::test] async fn dynamic_accepts_a_max_depth_prefix() { let producer = origin(1).produce(); From e488e699122857fbf8f145514989af1c08f5877a Mon Sep 17 00:00:00 2001 From: t0ms Date: Wed, 30 Sep 2026 23:54:06 +0100 Subject: [PATCH 122/128] fix(moq-mux): keep the TS export hold across a rewind (#4618) Co-authored-by: Luke Curley Co-authored-by: Claude Opus 5.5 --- rs/moq-mux/src/container/ts/export.rs | 24 +-- rs/moq-mux/src/container/ts/export_test.rs | 162 +++++++++++++++++---- 2 files changed, 146 insertions(+), 40 deletions(-) diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index e07f1b0d39e..e493c9a3afc 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -174,8 +174,8 @@ pub struct Export { /// high-water mark rather than on every frame. watermark: Option, /// When the interleave started waiting on a lagging track: the arrival of the - /// first leading frame it held. Cleared once every track has caught up - /// ([`Self::pick_next_track`]). + /// first leading frame it held. Cleared once every track has caught up, or by + /// [`Self::resume`], but not by a rewind ([`Self::pick_next_track`]). stall: Option, /// Wakes [`Self::pick_next_track`] once the stall has lasted `max_age`. hold: Option>>, @@ -1284,6 +1284,10 @@ impl Export { track.discontinuity = 0; self.stale.insert(name.clone()); } + // A replacement broadcast gets its own budget: only a rewind within one broadcast + // carries a stall across. + self.stall = None; + self.hold = None; self.rewind(); Ok(()) } @@ -1299,9 +1303,8 @@ impl Export { self.keyframes.clear(); self.queue.clear(); self.watermark = None; - // The new generation waits for every track again, with a fresh budget: a - // frame held across the break restarts its `arrived` below. - self.stall = None; + // The stall carries across with its budget, and so does a held frame's + // `arrived` ([`Self::pick_next_track`]). self.clock = None; self.low = None; self.last_pcr = None; @@ -1319,8 +1322,7 @@ impl Export { if let Some(pending) = track.pending.as_ref() { track.discontinuity = pending.discontinuity; } - if let Some(mut pending) = track.pending.take() { - pending.arrived = web_async::time::Instant::now(); + if let Some(pending) = track.pending.take() { track.pending = track.admit(pending, self.epoch); } } @@ -1516,8 +1518,12 @@ impl Export { /// sources give a stalled group, output goes around the lagging track until it /// catches up; zero keeps arrival order. The stall is timed from its first held /// frame rather than per frame: a frame's successor is only pulled once it goes - /// out, so a per-frame wait would release one frame per `max_age`. No track is - /// fenced, so a boundary does not jump the queue. + /// out, so a per-frame wait would release one frame per `max_age`. A rewind does + /// not restart it either: a source's latency skip is a rewind, and a hold renewed + /// at each one delays every source by the budget they skip on, so under loss the + /// feed collapses into alternating holds and skips. [`Self::resume`] does, since a + /// replacement broadcast owes nothing to the one it replaced. No track is fenced, + /// so a boundary does not jump the queue. fn pick_next_track(&mut self, waiter: &kio::Waiter) -> Option { let (timestamp, pid, name, arrived) = self .tracks diff --git a/rs/moq-mux/src/container/ts/export_test.rs b/rs/moq-mux/src/container/ts/export_test.rs index cadb57a7f4a..f51b49f1952 100644 --- a/rs/moq-mux/src/container/ts/export_test.rs +++ b/rs/moq-mux/src/container/ts/export_test.rs @@ -3912,10 +3912,10 @@ async fn tune_in_does_not_wait_on_dropped_audio() { assert!(!out.is_empty(), "the tune-in waited on audio it had dropped"); } -/// A rewind taken while going around a quiet track gives the new generation a -/// fresh hold rather than the one that already expired. +/// A rewind taken while going around a quiet track keeps going around it: the +/// expired hold carries into the new generation rather than starting afresh. #[tokio::test(start_paused = true)] -async fn rewind_restarts_the_stall() { +async fn rewind_keeps_an_expired_stall() { let max_age = Duration::from_millis(500); let mut rig = Interleave::new(); let mut export = rig.export(max_age).await; @@ -3935,33 +3935,18 @@ async fn rewind_restarts_the_stall() { for tick in 0..=5 { rig.video(GOP + tick); } - // Well inside `max_age`: the new generation must still be waiting on the audio. - while let Ok(frame) = tokio::time::timeout(max_age / 5, export.next()).await { - out.extend(frame.expect("exporter error")); - } - let after = |out: &[Frame]| { - pes_pts_in_order(out) - .into_iter() - .filter(|&pts| pts > GOP * VIDEO_US * 90 / 1_000) - .count() - }; - assert_eq!( - after(&out), - 0, - "the new generation went around the audio without waiting" - ); - - // Once its own wait lapses, it goes around the audio too. - tokio::time::advance(max_age).await; out.extend(poll_frames(&mut export)); - assert!(after(&out) > 0, "the new generation never went out"); + let after = pes_pts_in_order(&out) + .into_iter() + .filter(|&pts| pts >= GOP * VIDEO_US * 90 / 1_000) + .count(); + assert!(after > 0, "the new generation waited on the audio again"); assert_eq!(export.discontinuity(), 1); } -/// A frame held across a rewind starts the new generation's hold afresh rather than -/// from when it first arrived. +/// A frame held across a rewind keeps the wait it has already served. #[tokio::test(start_paused = true)] -async fn rewind_restarts_a_held_frame() { +async fn rewind_keeps_a_held_frame_waiting_time() { let max_age = Duration::from_millis(500); let mut rig = Interleave::new(); let mut export = rig.export(max_age).await; @@ -3980,15 +3965,70 @@ async fn rewind_restarts_a_held_frame() { rig.video.discontinuity().unwrap(); rig.video(GOP); out.extend(poll_frames(&mut export)); - assert_eq!( - export.discontinuity(), - 0, - "the held audio went around the video at once" - ); + assert_eq!(export.discontinuity(), 1, "the held audio waited a second budget"); +} +/// A rewind part way through a hold neither ends it nor renews it: the new generation +/// waits out only what is left of the budget. +#[tokio::test(start_paused = true)] +async fn rewind_keeps_a_partial_stall() { + let max_age = Duration::from_millis(500); + let mut rig = Interleave::new(); + let mut export = rig.export(max_age).await; + let mut out = Vec::new(); + + rig.video(0); + rig.audio_until(1, &mut export, &mut out); + for tick in 1..=5 { + rig.video(tick); + } + assert!(poll_frames(&mut export).is_empty(), "video waits for the quiet audio"); + tokio::time::advance(max_age / 2).await; + assert!(poll_frames(&mut export).is_empty(), "the hold lapsed early"); + + rig.video.discontinuity().unwrap(); + for tick in 0..=5 { + rig.video(GOP + tick); + } + assert!(poll_frames(&mut export).is_empty(), "the rewind ended the hold"); + + tokio::time::advance(max_age / 2).await; + assert!(!poll_frames(&mut export).is_empty(), "the rewind renewed the hold"); + assert_eq!(export.discontinuity(), 1); +} + +/// Under loss every source skip is a rewind. However many arrive while a sparse +/// track stays quiet, the interleave holds for one budget, not one per rewind: +/// renewing it at each would delay every source by the budget they skip on, +/// and the feed would collapse into alternating holds and skips. +#[tokio::test(start_paused = true)] +async fn repeated_rewinds_hold_once() { + let max_age = Duration::from_millis(500); + let mut rig = Interleave::new(); + let mut export = rig.export(max_age).await; + let mut out = Vec::new(); + + rig.video(0); + rig.audio_until(1, &mut export, &mut out); + for tick in 1..=5 { + rig.video(tick); + } + assert!(poll_frames(&mut export).is_empty(), "video waits for the quiet audio"); tokio::time::advance(max_age).await; out.extend(poll_frames(&mut export)); - assert_eq!(export.discontinuity(), 1, "the new generation never went out"); + + for generation in 1..=8 { + rig.video.discontinuity().unwrap(); + for tick in 0..=5 { + rig.video(generation * GOP + tick); + } + out.extend(poll_frames(&mut export)); + assert_eq!( + export.discontinuity(), + generation, + "rewind {generation} held the feed for a fresh budget" + ); + } } /// A section lost before the cycle wraps commits an observed subset; the next @@ -5609,6 +5649,66 @@ async fn resume_after(finish: bool) { assert_eq!(pes_count(&after), 10, "the returned broadcast's frames all went out"); } +/// A replacement broadcast gets a fresh interleave budget: a hold that expired on the +/// broadcast before it doesn't let the new one go around a track still within its own. +#[tokio::test(start_paused = true)] +async fn resume_does_not_inherit_an_expired_stall() { + let max_age = Duration::from_secs(2); + let origin = crate::source::produce_origin(); + let source = crate::Source::new(origin.consume(), "live"); + let publish = || { + let mut broadcast = origin.publish("live", Default::default()).unwrap(); + let catalog = crate::catalog::Producer::new(&mut broadcast, crate::catalog::Config::default()).unwrap(); + (broadcast, catalog) + }; + // Output that needs no more than a tenth of the budget to pass. + async fn quick(export: &mut Export, max_age: Duration) -> Vec { + let mut out = Vec::new(); + while let Ok(frame) = tokio::time::timeout(max_age / 10, export.next()).await { + out.extend(frame.expect("exporter error")); + } + out + } + + let (mut broadcast, mut catalog) = publish(); + let mut leading = aac_rendition(&mut broadcast, &mut catalog, "a.aac"); + let mut quiet = aac_rendition(&mut broadcast, &mut catalog, "b.aac"); + let ended = source.broadcast().await.unwrap(); + let mut export = Export::new(source.clone()).await.unwrap().with_max_age(max_age); + write_aac(&mut quiet, 0); + for ms in (0..200).step_by(20) { + write_aac(&mut leading, ms); + } + quick(&mut export, max_age).await; + tokio::time::advance(max_age).await; + assert!( + !quick(&mut export, max_age).await.is_empty(), + "the leading track went around the quiet one" + ); + drop((broadcast, catalog, leading, quiet)); + let (_, end) = drain_to_end(&mut export).await; + assert!(end.is_err(), "a drop fails the export"); + + let (mut broadcast, mut catalog) = publish(); + let mut leading = aac_rendition(&mut broadcast, &mut catalog, "a.aac"); + let mut quiet = aac_rendition(&mut broadcast, &mut catalog, "b.aac"); + source.returned(&ended).await.unwrap(); + export.resume().await.unwrap(); + for ms in (0..200).step_by(20) { + write_aac(&mut leading, ms); + } + assert_eq!( + pes_count(&quick(&mut export, max_age).await), + 0, + "the replacement went around its quiet track on the old broadcast's budget" + ); + write_aac(&mut quiet, 200); + assert!( + !quick(&mut export, max_age).await.is_empty(), + "the replacement went out once both tracks showed" + ); +} + #[tokio::test(start_paused = true)] async fn resume_after_a_finish() { resume_after(true).await; From 1b090d085e32ca93cd32ebeecade4dfb1bf9e627 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 16:28:15 -0700 Subject: [PATCH 123/128] quest(m1): plan #4595, #4635, T-STD TS export, and Discord requests (#4637) Co-authored-by: Claude Opus 5.5 --- quest/m1/README.md | 18 ++++- quest/m1/catalog-omit-empty.md | 23 ++++++ quest/m1/clock-anchor-public.md | 29 ++++++++ quest/m1/data-capture-bindings.md | 55 -------------- quest/m1/data-config-nesting.md | 40 ++++++++++ quest/m1/data-consumer-timestamps.md | 38 ++++++++++ quest/m1/flv-export-delay.md | 22 ++++++ quest/m1/ietf-timestamp-units.md | 27 +++++++ quest/m1/js-prune-cache-window.md | 28 +++++++ quest/m1/js-publish-timestamp.md | 18 +++++ quest/m1/lite-late-lower-group.md | 63 ++++++++++++++++ quest/m1/mkv-export-delay.md | 22 ++++++ quest/m1/plan-max-delay.md | 27 +++++++ quest/m1/plan-untimed-objects.md | 46 ++++++++++++ quest/m1/publish-timestamp.md | 61 +++++++++++++++ quest/m1/source-map-removal.md | 17 +++++ quest/m1/timestamp-rewind-detail.md | 29 ++++++++ quest/m1/tstd/README.md | 27 +++++++ .../byte-schedule.md} | 13 +++- quest/m1/tstd/check.md | 25 +++++++ quest/m1/tstd/delay.md | 74 +++++++++++++++++++ 21 files changed, 641 insertions(+), 61 deletions(-) create mode 100644 quest/m1/catalog-omit-empty.md create mode 100644 quest/m1/clock-anchor-public.md delete mode 100644 quest/m1/data-capture-bindings.md create mode 100644 quest/m1/data-config-nesting.md create mode 100644 quest/m1/data-consumer-timestamps.md create mode 100644 quest/m1/flv-export-delay.md create mode 100644 quest/m1/ietf-timestamp-units.md create mode 100644 quest/m1/js-prune-cache-window.md create mode 100644 quest/m1/js-publish-timestamp.md create mode 100644 quest/m1/lite-late-lower-group.md create mode 100644 quest/m1/mkv-export-delay.md create mode 100644 quest/m1/plan-max-delay.md create mode 100644 quest/m1/plan-untimed-objects.md create mode 100644 quest/m1/publish-timestamp.md create mode 100644 quest/m1/source-map-removal.md create mode 100644 quest/m1/timestamp-rewind-detail.md create mode 100644 quest/m1/tstd/README.md rename quest/m1/{ts-export-byte-schedule.md => tstd/byte-schedule.md} (76%) create mode 100644 quest/m1/tstd/check.md create mode 100644 quest/m1/tstd/delay.md diff --git a/quest/m1/README.md b/quest/m1/README.md index ff2fe1e7033..0a35642776c 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -37,8 +37,10 @@ QUIC studies there on that rule. - [Browser close code](/quest/m1/browser-close-code.md) - a playwright case proves the page reads a relay's close code and reason, on every web-transport backend - [Resumed groups](/quest/m1/resume-latest.md) - a half-delivered group ends once the new copy is past it, so a group-only reader never parks after a mid-group failover - [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 +- [Late lower groups](/quest/m1/lite-late-lower-group.md) - a moq-lite subscriber with a floor receives a group created below the first served one, as moq-transport does - [Parked reads wake](/quest/m1/parked-read-wakes.md) - a read parked on an evicted or aborted group wakes and re-judges, for resume successors and plain tracks alike - [Reader end parity](/quest/m1/reader-end-parity.md) - JS readers see a track's end once the newest group reaches the declared end, as Rust readers do +- [JS cache window](/quest/m1/js-prune-cache-window.md) - js/net ages idle groups on a cache window and keeps max_age as media-time staleness, as Rust does - [Cross-relay bursts](/quest/m1/cross-relay-bursts.md) - bursty small-group tracks cross two relays without lost groups, unanswered FETCHes, or stalls - [Request stream cancel](/quest/m1/request-stream-serve.md) - a lite publisher stops resolving a SUBSCRIBE or FETCH once the requester FINs or resets, through one wrapper that owns every request stream's reader - [Session death parity](/quest/m1/session-death.md) - a local close ends tracks cleanly in both languages, and JS group readers see the session's error on session death @@ -46,7 +48,9 @@ QUIC studies there on that rule. - [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 - [CI runner stalls](/quest/m1/ci-runner-stalls.md) - the 0.4 to 0.8 s freezes of both interop tracks on CI are attributed from a week of nightlies and fixed or told apart from playback bugs - [Catalog estimate rate](/quest/m1/catalog-estimate-rate.md) - a rising `jitter`/`delay` estimate republishes the catalog at most once a second, in js/publish and moq-mux +- [Rewind detail](/quest/m1/timestamp-rewind-detail.md) - a refused timestamp rewind names the frame's timestamp and the live edge - [Legacy end overshoot](/quest/m1/legacy-end-overshoot.md) - browser playback survives a group that starts inside the previous group's estimated end +- [Plan: max-delay](/quest/m1/plan-max-delay.md) - decide whether `max_age` becomes `max_delay` across the CLI, APIs, and bindings - [Wire compatibility](/quest/m1/wire-compat.md) - a nightly run tests this checkout against the last published release for tokens, session wire, and catalog/container - [TS PSI reassembly](/quest/m1/ts-psi-reassembly.md) - `import ts` reads a PAT or PMT that spans packets or follows a nonzero pointer_field instead of aborting, and one corrupted section costs a repetition and a counted `CRC_error`, not the import - [TS damaged units](/quest/m1/ts-damaged-units.md) - one malformed PES or access unit is dropped, counted as `damaged`, and resynced at the next keyframe instead of ending the import @@ -59,9 +63,17 @@ QUIC studies there on that rule. - [Auth client CA](/quest/m1/relay-auth-client-ca.md) - on dev, `auth::Config::validate` and `init` take the client-CA flag, so no caller can skip the check - [Data track clock](/quest/m1/data-track-clock.md) - JSON and binary data tracks stamp on the catalog's clock at write time, matching the media's anchored clock - [Go and Dart doc samples](/quest/m1/doc-samples-go-dart.md) - Go and Dart doc samples compile against their wrappers -- [Data capture in bindings](/quest/m1/data-capture-bindings.md) - moq-ffi and every wrapper pass a data frame's capture time, and the JSON window producer takes one +- [Publishing requires a timestamp](/quest/m1/publish-timestamp.md) - every Rust and binding publish API takes a timestamp; nothing fills in now for the caller +- [JS publishing requires a timestamp](/quest/m1/js-publish-timestamp.md) - the same in @moq/json, @moq/binary, and @moq/net +- [Plan: untimed peer objects](/quest/m1/plan-untimed-objects.md) - decide what a frame's timestamp is when a moq-transport or pre-lite-05 peer sends none +- [Data consumer timestamps](/quest/m1/data-consumer-timestamps.md) - json and binary consumers return each value's timestamp, in Rust and every binding +- [Nested data configs](/quest/m1/data-config-nesting.md) - docs nest `BinaryConfig`/`JsonConfig` in an application section instead of flattening it +- [Omit empty catalog sections](/quest/m1/catalog-omit-empty.md) - a Rust catalog with no video or audio leaves those keys out, as JS does +- [Public clock anchor](/quest/m1/clock-anchor-public.md) - an application demuxer shares one source offset across its tracks through `Anchor` and `Lane` +- [Delete SourceMap](/quest/m1/source-map-removal.md) - on dev, `Anchor` with its `Lane`s is the one way onto the broadcast clock - [Draft-20 FETCH](/quest/m1/ietf-fetch-location.md) - a draft-20+ FETCH within one group is served from its LOCATION_FILTER, as older drafts are - [Fetch without SUBSCRIBE](/quest/m1/ietf-fetch-only.md) - a relay fetches from an IETF upstream without subscribing, finished tracks included, with End of Track always reported +- [IETF timestamp units](/quest/m1/ietf-timestamp-units.md) - drafts 14-16 stop sending Timestamp properties they can't give units for - [JS IETF datagrams](/quest/m1/js-ietf-datagram.md) - `@moq/net` sends and receives datagram groups over moq-transport, like Rust - [Datagrams are live-only](/quest/m1/datagram-unfetchable.md) - no FETCH, replay to a new subscriber, or cache fill ever returns a datagram group - [#2991](/quest/m1/2991-net-coalesce-dynamic-tracks-and-preserve-sequences-across.md) - one dynamic producer per track name in both languages, with the sequence namespace surviving a replacement @@ -134,7 +146,9 @@ QUIC studies there on that rule. - [Catalog warmup](/quest/m1/catalog-warmup.md) - `warmup` on video and audio renditions, in the catalog and the draft - [Audio warmup](/quest/m1/audio-warmup.md) - a viewer joining an Opus rendition mid-stream never hears the unconverged first 80 ms - [#3021](/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md) - moq-gst picks the broadcast wall epoch; a restarted source is a new epoch, not a forward re-anchor -- [TS byte schedule](/quest/m1/ts-export-byte-schedule.md) - moq export ts places PCRs and padding on the byte grid `mpegts.muxRate` implies, so a receiver can clock off arrival +- [T-STD TS export](/quest/m1/tstd/README.md) - `moq export ts` is a proper remux that passes the T-STD buffer model, starting with a fixed `--delay` +- [FLV export delay](/quest/m1/flv-export-delay.md) - FLV interleaves through the shared fixed-delay release stage +- [MKV export delay](/quest/m1/mkv-export-delay.md) - MKV interleaves through the shared fixed-delay release stage - [Release profile](/quest/m1/release-profile.md) - every release build gets fat LTO, one codegen unit, and stripping from the workspace profile instead of three script exports - [Size report](/quest/m1/size-report.md) - a nightly job reports every shipped artifact's size, native and JS, and alerts when one grows - [Publish lazy file source](/quest/m1/publish-lazy-file.md) - a camera or screen `` stops downloading mediabunny's ~99 KB gzip diff --git a/quest/m1/catalog-omit-empty.md b/quest/m1/catalog-omit-empty.md new file mode 100644 index 00000000000..93818c6114b --- /dev/null +++ b/quest/m1/catalog-omit-empty.md @@ -0,0 +1,23 @@ +# [XS] The hang catalog omits empty video and audio sections + +## Goal + +A Rust-published hang catalog with no video or audio renditions leaves out the +`video` or `audio` key, as the JS publisher already does, instead of writing +`"video":{"renditions":{}},"audio":{"renditions":{}}`. + +## Plan + +Requested by an external consumer (OneTooMany, Discord): data-only broadcasts +fill logs with misleading empty sections. + +Give `Video` and `Audio` an `is_empty` (no renditions), as `Text` has, and add +`skip_serializing_if` on `video` and `audio` in +`rs/hang/src/catalog/root.rs`, like `text`/`json`/`binary`, and update the +tests that pin the empty output (`root.rs` and +`rs/moq-mux/src/catalog/hang/ext.rs`). + +Wire-compatible, so it lands on `main`: Rust already defaults an absent +section on read, and `@moq/hang` has accepted an absent one since #401 +(2025-06). The draft already marks both optional; decided to leave its wording +unchanged. diff --git a/quest/m1/clock-anchor-public.md b/quest/m1/clock-anchor-public.md new file mode 100644 index 00000000000..d491aa60981 --- /dev/null +++ b/quest/m1/clock-anchor-public.md @@ -0,0 +1,29 @@ +# [S] moq-mux exports the per-source clock anchor + +## Goal + +An application running its own demuxer puts several tracks of one source on +the broadcast `Clock` with one shared offset, as the built-in TS, fMP4, and +FLV importers do, without going through a built-in importer. + +## Plan + +Requested by an external consumer (OneTooMany, Discord): their MPEG-TS +ingest publishes video, KLV, and sometimes audio from one program. One +`SourceMap` per track lets tracks drift apart by their first-PTS difference, +and one shared `SourceMap` reads interleave (beyond `MAX_REORDER`) as a reset. + +Decided: make `clock::Anchor` and `clock::Lane` public with the API the +importers already use: `Anchor::new(clock)`, `translate(&mut lane, pts)`, +`translate_at`, `extend`, and `Lane::restart`, with `Lane: Default`. Additive, +so it lands on `main` for a 0.10 patch. + +Open for the PR: the export path. Proposal: `pub mod clock` with +`moq_mux::clock::{Anchor, Lane}`, keeping the root `Clock` re-export. Ask the +maintainer with alternatives. + +Document both in `doc/lib/rs/moq-mux.md`, with a two-track example. + +Their other `ts::Import` gaps (MPEG-2 video, KLV reassembly) stay unplanned +until requested directly. The H.265 per-packet error is +[TS damaged units](/quest/m1/ts-damaged-units.md). diff --git a/quest/m1/data-capture-bindings.md b/quest/m1/data-capture-bindings.md deleted file mode 100644 index faefa6dc997..00000000000 --- a/quest/m1/data-capture-bindings.md +++ /dev/null @@ -1,55 +0,0 @@ -# [M] Bindings stamp data frames with a capture time - -## Goal - -A moq-ffi publisher, and every wrapper over it (Python, Swift, Kotlin, Go, -Dart), can pass a capture time with a JSON or binary snapshot `update` or -stream `append`, so its data tracks advertise `delay` and `jitter` like a Rust -publisher's. Leaving it out keeps today's behaviour. The Go and Python -wrappers gain the binary snapshot and stream producers they lack. `moq-json`'s `window` -producer takes a capture time too. Settled scope: moq-ffi and its wrappers, -not libmoq. - -## Plan - -- #4270 gives the Rust producers `moq_net::Timed`, built with - `Timed::from(value).at(t)`. The `moq-mux` data producers take - `Timed<_, Instant>`, map it onto the broadcast clock, and refuse one ahead of - now (`Error::InvalidCapture`). The moq-ffi producers in - `rs/moq-ffi/src/{json,binary}.rs` pass bare values. -- Settled: the capture time is a media timestamp on the broadcast's - timeline. moq-ffi exposes the broadcast clock's `now()` as a timestamp; - callers stamp payloads with values taken from it, and moq refuses one ahead - of now. That keeps a device or process clock out, as the Rust `Instant` - mapping does. The `moq-mux` producers take an `Instant` today, so either - map the timestamp back through the clock inside moq-ffi or give the clock a - typed timestamp moq-mux accepts; keep a raw `Timestamp` from compiling - there. Make it optional on the existing methods, never a `_with_capture` - twin. -- `moq-json` window: `window::Producer::push` stamps `Timestamp::now()` - (`rs/moq-json/src/window/producer.rs`). Accept `Timed` as the snapshot and - stream producers do. Nothing in `moq-mux` publishes window mode, so there is - no estimator to feed. -- Wrappers follow per the cross-package sync table, each with a test that a - past capture time is accepted and a future one refused. -- Go (`go/wrapper/moq`) and Python (`py/moq-rs`) wrap only the JSON - producers; [#4137](https://github.com/moq-dev/moq/pull/4137) added - `publish_binary_snapshot` / `publish_binary_stream` to moq-ffi without - them. Add hand-written binary wrappers there, capture time included, so - the capture tests cover binary too. The maintainer asked for this. Update - `doc/lib/{py,swift,kt,go,dart}`. - -Public API: breaking, so it lands on `dev`. A new parameter on the generated -`update` and `append` breaks every published binding caller (Go, for one, has -no optional arguments), and a `_with_x` twin is ruled out. The broadcast clock -`now()` and the Go and Python binary producers are additive; -`window::Producer::push` accepts `Timed`, source-compatible. -Wire: none. - -## Required - -- [JSON and flate namespaces](/quest/m1/ffi-shape/json.md) - moves the data producers this changes, so the two breaks land in order rather than colliding - -## Related - -- [Generated C bindings](/quest/m1/c/README.md) - replaces libmoq, so C inherits this from moq-ffi diff --git a/quest/m1/data-config-nesting.md b/quest/m1/data-config-nesting.md new file mode 100644 index 00000000000..95c7ab5a9ed --- /dev/null +++ b/quest/m1/data-config-nesting.md @@ -0,0 +1,40 @@ +# [XS] Docs nest a data config instead of flattening it + +## Goal + +The docs and doctests for application data sections nest `BinaryConfig` or +`JsonConfig` in a `config` field instead of `#[serde(flatten)]`ing it, so a +field added to either config later can never collide with an application's own +fields. + +```rust +struct Mavlink { + config: BinaryConfig, + sysid: u8, +} +``` + +## Plan + +Requested by an external consumer (OneTooMany, Discord). No code flattens +these configs today; only docs and tests do. The built-in `json`/`binary` +sections serialize the config directly as the map value, so their wire shape +is unchanged. An application section becomes +`{"config":{"mode":...},"sysid":1}`. + +Update: + +- `doc/lib/rs/moq-mux.md` (the `Mavlink` example, its `AsMut` impl returning + `&mut self.config`, and the `catalog::Entry::new(name, &entry.config)` line) +- `doc/concept/hang.md` (the "flattening the JSON or binary entry" prose) +- the `RenditionConfig` doctest in `rs/moq-mux/src/catalog/tracks.rs` +- `a_data_config_flattens_into_an_application_entry` in + `rs/hang/src/catalog/root.rs` (rename; the `extra` assertion no longer + applies) and `mod section` in `rs/moq-mux/src/binary.rs` + +`doc/lib/rs/hang.md`'s flatten of a whole extension into `Catalog` is a +different pattern and stays. + +## Related + +- [Robot teleoperation](/quest/m2/teleop/robot.md) - decides where robot fields ride in the catalog diff --git a/quest/m1/data-consumer-timestamps.md b/quest/m1/data-consumer-timestamps.md new file mode 100644 index 00000000000..98fcb1dc863 --- /dev/null +++ b/quest/m1/data-consumer-timestamps.md @@ -0,0 +1,38 @@ +# [M] Data consumers return each value's timestamp + +## Goal + +A JSON or binary data consumer returns each value with its frame's timestamp, +so an application can carry data onto another track, or sync it with video, +at the exact time it was published. Covers moq-json, moq-binary, the moq-mux +wrappers, moq-ffi, and every binding wrapper. + +## Plan + +Requested by an external consumer (OneTooMany, Discord), who translates +MAVLink into application telemetry and must keep its timestamps to stay in +sync with video. + +Every `moq_net::Frame` has a timestamp, but the consumers decode only +`frame.payload` and drop it: `moq_mux::{json,binary}::Consumer::next` and the +moq-json and moq-binary snapshot and stream consumers they wrap. A snapshot +consumer returns the timestamp of the frame it decoded last. + +Decided: `next()` and `poll_next()` return `Timed`, the type the producers +take, whose `at` becomes required in +[Publishing requires a timestamp](/quest/m1/publish-timestamp.md). The +timestamp is the frame's media timestamp on the track's timescale. +[Plan: untimed peer objects](/quest/m1/plan-untimed-objects.md) decides +whether a peer can deliver a frame without one; if it can, `at` becomes an +`Option` here, so this waits for it and breaks once. + +moq-ffi's json/binary consumers return the timestamp too, and the py, swift, +kt, go, and dart wrappers and `doc/lib/*` follow. JS readers stay with +[Data sync in watch](/quest/m3/watch-data-sync.md). + +Public API: breaking, on `dev`. Wire: none. + +## Required + +- [Publishing requires a timestamp](/quest/m1/publish-timestamp.md) - makes `Timed.at` required, the type this returns +- [Plan: untimed peer objects](/quest/m1/plan-untimed-objects.md) - decides whether the returned timestamp can be absent diff --git a/quest/m1/flv-export-delay.md b/quest/m1/flv-export-delay.md new file mode 100644 index 00000000000..4496cb2e952 --- /dev/null +++ b/quest/m1/flv-export-delay.md @@ -0,0 +1,22 @@ +# [S] FLV export releases frames on a fixed delay + +## Goal + +`moq export flv --delay ` interleaves tracks through the shared +fixed-delay release stage, so its tag order is a function of the media, not +of arrival, as the TS export's is. + +## Plan + +Today `pick_next_track` (`rs/moq-mux/src/container/flv/export.rs`) takes the +smallest *pending* timestamp, so which track goes first depends on which frame +has arrived. Replace it with the release stage from +[fixed-delay release](/quest/m1/tstd/delay.md), with the same `--delay` flag +and the same late-frame drop. Update `doc/bin/cli.md`. + +Public API: the exporter gains a delay setting; breaking only if it replaces +an existing one. Wire: none. + +## Required + +- [Fixed-delay release](/quest/m1/tstd/delay.md) - builds the shared release stage diff --git a/quest/m1/ietf-timestamp-units.md b/quest/m1/ietf-timestamp-units.md new file mode 100644 index 00000000000..cb9343378e2 --- /dev/null +++ b/quest/m1/ietf-timestamp-units.md @@ -0,0 +1,27 @@ +# [XS] IETF drafts 14-16 send no timestamps without units + +## Goal + +On moq-transport drafts 14 through 16, where TIMESCALE can't be sent, the Rust +and JS publishers write no Timestamp object property, as +`drafts/draft-lcurley-moq-timestamp.md` requires ("A publisher that emits +Timestamps MUST send TIMESCALE"). + +## Plan + +Rust sets `has_extensions: self.timescale.is_some()` +(`rs/moq-net/src/ietf/publisher.rs`), but `Properties::encode` never writes +the TIMESCALE block before draft-17 (`rs/moq-net/src/ietf/properties.rs`), so +drafts 14-16 carry timestamps without units. The Rust subscriber ignores them. +Gate the Timestamp property on a timescale actually sent. Check js/net's +`stamped` flag (`js/net/src/ietf/publisher.ts`) for the same gap. + +Before landing, check whether an interop peer on draft-14 reads the Timestamp +property without TIMESCALE. If one does, ask whether to keep it. + +Fix the stale `track::Info::timescale` doc (`rs/moq-net/src/model/track.rs`), +which says IETF always falls back to local milliseconds; draft-17 and later +carry TIMESCALE. + +Wire: stops sending a property peers can't interpret, on published drafts. +Public API: none. Lands on `main`. diff --git a/quest/m1/js-prune-cache-window.md b/quest/m1/js-prune-cache-window.md new file mode 100644 index 00000000000..c955c2244e1 --- /dev/null +++ b/quest/m1/js-prune-cache-window.md @@ -0,0 +1,28 @@ +# [S] js/net ages cached groups on a cache window, not max_age + +## Goal + +js/net retains cached groups the way Rust does. A wall-clock idle window +bounds memory, and `max_age` is only the media-time staleness budget, so a +congestion stall can't age content out of a JS publisher's cache. + +## Plan + +`#prune` (`js/net/src/track.ts`) evicts a group after `info.maxAge` of +wall-clock idleness, measured on the group's `activity`. Rust keeps those +apart: `track::Info::max_age` is measured in media timestamps, and the cache +pool's `expiry` is the separate wall-clock bound +(`rs/moq-net/src/model/cache.rs`). Give js/net a cache window of its own for +idle eviction, as Rust's pool has, and leave `maxAge` to `#drift` / +`#isStale`. Add a test with mocked time where a stalled track keeps its groups +past `maxAge`. + +[Generated @moq/net](/quest/m1/rs2ts/README.md) will replace this code with +Rust's model; the maintainer chose to fix it by hand first. + +Public API: none unless the window is configurable (keep it private). Wire: +none. + +## Related + +- [Generated @moq/net](/quest/m1/rs2ts/README.md) - retires js/net's hand-written model diff --git a/quest/m1/js-publish-timestamp.md b/quest/m1/js-publish-timestamp.md new file mode 100644 index 00000000000..02549b2db61 --- /dev/null +++ b/quest/m1/js-publish-timestamp.md @@ -0,0 +1,18 @@ +# [M] JS publishing requires a timestamp + +## Goal + +`@moq/json`, `@moq/binary`, and `@moq/net` publish APIs take a timestamp and +never fill in `Timestamp.now()` for the caller, mirroring +[Publishing requires a timestamp](/quest/m1/publish-timestamp.md). + +## Plan + +Today the json and binary snapshot and stream producers default +`at = Timestamp.now()`, the json window producer always uses now, and js/net's +`writeString`, `writeJson`, and `writeBool` stamp now. Make the timestamp a +required argument on each, with the same shape as Rust's `Timed`. Callers in +the repository (js/hang catalog, js/publish, js/room) pass their clock's now +explicitly. Update `doc/lib/js/{json,binary,net}.md`. + +Public API: breaking, on `dev`. Wire: none. diff --git a/quest/m1/lite-late-lower-group.md b/quest/m1/lite-late-lower-group.md new file mode 100644 index 00000000000..451ed6ec016 --- /dev/null +++ b/quest/m1/lite-late-lower-group.md @@ -0,0 +1,63 @@ +# [S] moq-lite delivers a late group above the subscriber's floor + +## Goal + +A moq-lite subscriber with an explicit floor receives every group at or above +that floor that its `max_age` still considers fresh, whatever order the +publisher created them in, as moq-transport already does. Today the lite +publisher silently drops a group created below the first group it served: the +publisher's `create_group` and `write_frame` succeed, and the subscriber sees a +clean end without it. + +## Plan + +`TrackRun::start` (`rs/moq-net/src/lite/publisher.rs`) sends `SUBSCRIBE_START` +for the first served group and then calls `raise_start_to(start)`, which +suppresses every lower group regardless of the subscription's floor and +budget. #4387 added it to resolve a relayed subscription's start from its +source; keep that fix (see the note in +[Track tail interop](/quest/m1/track-tail-interop.md)) while honoring an +explicit floor. + +Decided: + +- An explicit floor delivers late lower groups within `max_age`, matching + moq-transport, draft-ietf-moq-transport ("subscriptions without a filter pass + all Objects"), and moq-mux's floor handling (#3258). +- `start: None` joins where the publisher starts: the first served group + becomes the floor, so a group created below it is dropped by design. This is + what moq-mux's `container::Consumer` and the IETF publisher already assume. + Fix the `Subscription::start` docs in moq-net (which say `None` equals a + floor of group 0) and the matching js/net docs. +- `raise_start_to` applies only when the subscription has no explicit floor + (`start.is_none()`). With an explicit floor, `SUBSCRIBE_START` still reports + the first served group, but nothing below it is suppressed. +- Aggregation follows: `Subscription::poll_combined` + (`rs/moq-net/src/model/subscription.rs`) lets any `None` clear another + subscriber's explicit floor, so a relay forwards "join at the start" upstream + and the explicit-floor subscriber still loses group 0. An explicit floor + survives mixing with `None`; the loosest explicit floor wins. Each + subscriber's own cursor still filters what it sees. +- `start_floor_suppresses_late_lower_arrivals` stays as the `None` case: it + subscribes with `None`, receives group 7, raises the start to 7 as + `SUBSCRIBE_START` does, and group 5 is still suppressed. Add its explicit-floor + twin, which delivers group 5. + +If `drafts/draft-lcurley-moq-lite.md` describes `SUBSCRIBE_START` as an +implicit drop below the start regardless of the floor, update it in the same +PR. + +Test: port the reporter's deterministic repro +(`rs/moq-net/tests/late_lower_group.rs` on kidq330's fork, paused time and the +mock transport) for lite-05, lite-06, and lite-07-wip, direct and through a +relay, with the in-process and moq-transport controls. Add a mixed case through +a relay: a `None` subscriber already receiving group 1, then one with a floor +of group 0, and a fresh group 0 reaches only the second. + +## Closes + +- [#4595](https://github.com/moq-dev/moq/issues/4595) - moq-lite: a group created below the first served group is silently dropped + +## Related + +- [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - once publishers name every undelivered group, a group dropped under the None floor can be named instead of vanishing diff --git a/quest/m1/mkv-export-delay.md b/quest/m1/mkv-export-delay.md new file mode 100644 index 00000000000..4fb5d5fcf67 --- /dev/null +++ b/quest/m1/mkv-export-delay.md @@ -0,0 +1,22 @@ +# [S] MKV export releases frames on a fixed delay + +## Goal + +`moq export mkv --delay ` interleaves tracks through the shared +fixed-delay release stage, so its tag order is a function of the media, not +of arrival, as the TS export's is. + +## Plan + +Today `pick_next_track` (`rs/moq-mux/src/container/mkv/export.rs`) takes the +smallest *pending* timestamp, so which track goes first depends on which frame +has arrived. Replace it with the release stage from +[fixed-delay release](/quest/m1/tstd/delay.md), with the same `--delay` flag +and the same late-frame drop. Update `doc/bin/cli.md`. + +Public API: the exporter gains a delay setting; breaking only if it replaces +an existing one. Wire: none. + +## Required + +- [Fixed-delay release](/quest/m1/tstd/delay.md) - builds the shared release stage diff --git a/quest/m1/plan-max-delay.md b/quest/m1/plan-max-delay.md new file mode 100644 index 00000000000..a8c700c497f --- /dev/null +++ b/quest/m1/plan-max-delay.md @@ -0,0 +1,27 @@ +# [S] Plan: rename max-age to max-delay + +## Goal + +Decide whether the staleness budget is renamed from `max_age` to `max_delay` +everywhere: the CLI flags (publish and import retention, rtmp, subscribe), the +moq-net `Subscription::max_age` and `track::Info::max_age`, js/net's `maxAge`, +and the bindings. Then rewrite this quest into implementation quests, or +delete it. + +## Plan + +The maintainer finds "delay" clearer than "age" for how far a group may fall +behind before it's skipped. `moq play --delay` and `moq export ts --delay` +(planned in [fixed-delay release](/quest/m1/tstd/delay.md)) use one delay +knob for presentation and staleness; only `moq play`'s exists today. + +To weigh: + +- Publisher retention (`track::Info::max_age`) really is an age of cached + content, while the subscriber budget is a delay. They may deserve different + names rather than one rename. +- The wire fields are `Publisher Max Age` and `Subscriber Max Age` in + `drafts/draft-lcurley-moq-lite.md`. + Renaming the draft's field is free on the wire, but it churns the spec. +- A rename breaks every published API and binding, so it lands on `dev`, + mirrored across Rust, JS, and the bindings in one release. diff --git a/quest/m1/plan-untimed-objects.md b/quest/m1/plan-untimed-objects.md new file mode 100644 index 00000000000..33344c05b2e --- /dev/null +++ b/quest/m1/plan-untimed-objects.md @@ -0,0 +1,46 @@ +# [S] Plan: untimed peer objects + +## Goal + +Decide what a frame's timestamp is when a peer sends none, and rewrite this +quest into implementation quests. That covers IETF objects on a track without +TIMESCALE or without a Timestamp property, and lite-01 to lite-04, which have +no timestamp on the wire. The decision must not invent a timeline that +changes with the relay path. + +## Plan + +Today every receiver fills local arrival time (`Timestamp::from(runtime.now())` +in `rs/moq-net/src/{lite,ietf}/subscriber.rs`, `?? Timestamp.now()` in js/net), +as `drafts/draft-lcurley-moq-timestamp.md` mandates. On lite-05 and later, a +relay then forwards those stamps as if they were real. A failover to another +first hop changes them, so the timeline jumps, and they break the "one clock +per broadcast" property. The maintainer dislikes this. + +Settled elsewhere: publishing always requires a timestamp +([Publishing requires a timestamp](/quest/m1/publish-timestamp.md)), and +lite-05 and lite-06 (published) can't encode an absent one. + +Candidates: + +- Faithful absence (leaning): the model and consumers carry + `Option` so a relay forwards "none" as none. lite-07-wip encodes + it by shifting the FRAME Timestamp Delta and the DATAGRAM Timestamp by one + (0 = absent); an absent frame doesn't move the delta baseline. A lite-05/06 + encoder writes its send time. Untimed groups are never media-stale; the + pool's wall-clock expiry still reclaims them, and start resolution picks the + latest group instead of replaying the cache. +- First-hop arrival, documented: no change, but the failover jump stays. +- 0 as a sentinel: rejected. It collides with a real pts of 0. +- `max_age` on max(wall, pts): the maintainer asked. Rust keeps `max_age` as + media-time staleness so a congestion stall can't age content out, with the + pool's expiry as the wall-clock bound (`rs/moq-net/src/model/cache.rs`). + +Facts to gather: which IETF implementations send TIMESCALE and Timestamp +(moxygen, the interop matrix), and every model decision that reads a +timestamp (`track.rs` staleness and `GroupExpiry`, `resume.rs` successors, +`group.rs` `poll_timestamp`, which treats "has a timestamp" as "has a frame"). + +Output: implementation quests, and updates to +[Data consumer timestamps](/quest/m1/data-consumer-timestamps.md), whose +return type depends on this, and to the timestamp and lite drafts. diff --git a/quest/m1/publish-timestamp.md b/quest/m1/publish-timestamp.md new file mode 100644 index 00000000000..edce12e6a48 --- /dev/null +++ b/quest/m1/publish-timestamp.md @@ -0,0 +1,61 @@ +# [L] Publishing requires a timestamp + +## Goal + +Every publish API takes a timestamp, and nothing below it invents one. A +frame's timestamp is the publisher's statement of when the content happened. +A library never fills in "now" on the caller's behalf. Covers moq-net, +moq-json, moq-binary, moq-mux, moq-ffi, and every binding wrapper (Python, +Swift, Kotlin, Go, Dart). Not libmoq, which the +[Generated C bindings](/quest/m1/c/README.md) replace. + +## Plan + +Decided (2026-09-30): the wire timestamp stays required, so the publish side +must be too. Today `Timed.at: None` means "stamp when written": moq-json and +moq-binary fill `Timestamp::now()` (moq-net's clock, not the broadcast's), and +moq-mux's `Clock::stamp` fills the broadcast clock's `now()`. The FFI raw +`MoqFrame.timestamp_us` and `MoqDatagram.timestamp_us` default to 0. + +- `moq_net::Timed` keeps its name and gets a required `at: T`, with no + `From`. The json/binary consumers return the same type (see + [Data consumer timestamps](/quest/m1/data-consumer-timestamps.md)). +- moq-json (snapshot, stream, and window, whose `push` always stamps now) and + moq-binary producers take `Timed<_, Timestamp>`. The moq-mux data producers + take `Timed<_, Instant>` and map it onto the broadcast clock, refusing one + ahead of now (`Error::InvalidCapture`), as today; `Clock::stamp` stops + filling `None`. `catalog::data::Listing::record` then always has a capture + time for `delay` and `jitter`. +- Publishers inside the repository (hang catalog snapshots, MSF, stats, room + chat, examples) pass their clock's now explicitly. +- moq-ffi: the + capture time is a media timestamp on the broadcast's timeline. moq-ffi + exposes the broadcast clock's `now()` as a timestamp; callers stamp payloads + with values taken from it, and moq refuses one ahead of now. That keeps a + device or process clock out, as the Rust `Instant` mapping does. Either map + the timestamp back through the clock inside moq-ffi or give the clock a + typed timestamp moq-mux accepts; keep a raw `Timestamp` from compiling + there. The json/binary `update` and `append` take it as a required + argument, and the raw frame and datagram records lose their `default = 0`. +- Go (`go/wrapper/moq`) and Python (`py/moq-rs`) wrap only the JSON + producers; [#4137](https://github.com/moq-dev/moq/pull/4137) added + `publish_binary_snapshot` / `publish_binary_stream` to moq-ffi without + them. Add hand-written binary wrappers there. The maintainer asked for this. + Each wrapper gets a test that a past capture time is accepted and a future + one refused. +- Docs: "stamped when written" in `doc/lib/rs/{moq-json,moq-binary}.md` and + `rs/moq-net/src/model/timed.rs`, plus `doc/lib/{py,swift,kt,go,dart}`. + +What a receiver fills in when a peer sends no timestamp is out of scope: +[Plan: untimed peer objects](/quest/m1/plan-untimed-objects.md). + +Public API: breaking, on `dev`. Wire: none. + +## Required + +- [JSON and flate namespaces](/quest/m1/ffi-shape/json.md) - moves the data producers this changes, so the two breaks land in order rather than colliding + +## Related + +- [Data track clock](/quest/m1/data-track-clock.md) - the moq-mux mapping this keeps reads the catalog's clock at write time +- [JS publishing requires a timestamp](/quest/m1/js-publish-timestamp.md) - the same change in the JS packages diff --git a/quest/m1/source-map-removal.md b/quest/m1/source-map-removal.md new file mode 100644 index 00000000000..f4eddc12de4 --- /dev/null +++ b/quest/m1/source-map-removal.md @@ -0,0 +1,17 @@ +# [XS] Delete SourceMap + +## Goal + +On `dev`, `moq_mux::SourceMap` and `Clock::source` are gone, so an `Anchor` +with its `Lane`s is the one way to map a source onto the broadcast clock. + +## Plan + +`SourceMap` is an `Anchor` plus one `Lane`, and nothing in the repository uses +it. A single-track source uses `Anchor` with one `Lane`. Migrate the +`SourceMap` tests in `rs/moq-mux/src/clock.rs` onto `Anchor`, and update +`doc/lib/rs/moq-mux.md`. + +## Required + +- [Public clock anchor](/quest/m1/clock-anchor-public.md) - `Anchor` and `Lane` must be public first diff --git a/quest/m1/timestamp-rewind-detail.md b/quest/m1/timestamp-rewind-detail.md new file mode 100644 index 00000000000..d10328975d8 --- /dev/null +++ b/quest/m1/timestamp-rewind-detail.md @@ -0,0 +1,29 @@ +# [XS] A timestamp rewind names the frame and the edge + +## Goal + +When `container::Producer::write` refuses a frame below the live edge, the +error says which timestamp it refused and where the edge was, so a report like +#4635 diagnoses itself from the error text alone. + +## Plan + +`container::TimestampRewind` (`rs/moq-mux/src/container/mod.rs`) is a unit +struct, raised at `rs/moq-mux/src/container/producer.rs` when +`frame.timestamp < live_edge`, and also constructed on the consumer side +(`rs/moq-mux/src/container/consumer.rs`); give those the same detail. Give it `timestamp` and `edge` fields and put +both, in microseconds, in its message, for example "frame timestamp 1790802494898431 +µs is below the live edge 1790802494898432 µs". moq-ffi surfaces the message +unchanged. + +#4635 could not be reproduced: FLAC and AAC share this path, and strictly +increasing timestamps with a cut per frame pass. A cut per frame makes every +frame a group start, so it refuses any backward step, while a dip inside an +open group is tolerated. Test: a FLAC `import::Track` with `cut(None)` per +frame and one frame 1 µs back reports both values. + +Public API: a unit struct gains fields, so breaking, on `dev`. Wire: none. + +## Related + +- [#4635](https://github.com/moq-dev/moq/issues/4635) - the report this makes diagnosable; it stays open until the reporter's sequence is known diff --git a/quest/m1/tstd/README.md b/quest/m1/tstd/README.md new file mode 100644 index 00000000000..ec8f9dc2cff --- /dev/null +++ b/quest/m1/tstd/README.md @@ -0,0 +1,27 @@ +# T-STD compliant TS export + +## Goal + +`moq export ts` output passes a full ISO 13818-1 T-STD buffer-model check +(transport, multiplex, and elementary buffers, with every access unit decoded +at its DTS without overflow or underflow), on a clean path and under +sustained loss. That is the bar for the media-aware lane to carry primary +distribution. Without it, only the passthrough lane can. + +## Plan + +Decided (2026-09-30), from a discussion with t0ms and Gwendal's email: a +TS export has to be a proper remux, not an interleave of demuxed tracks. +Padding, pacing, and muxing all assume a fixed delay, so the export gets one +first. t0ms is testing whether T-STD compliance is feasible at all; record +the result here. If it isn't, re-plan this line. + +This README owns the end-to-end proof: the #4613 netem rig (10% loss, a real +~10 Mb/s broadcast TS) passes the strict T-STD check, and the recipe runs +nightly. + +## Required + +- [Fixed-delay release](/quest/m1/tstd/delay.md) - frames go out at media time plus a fixed `--delay`, in one order under loss +- [T-STD check](/quest/m1/tstd/check.md) - the harness grades the full buffer model instead of the transport buffer alone +- [TS byte schedule](/quest/m1/tstd/byte-schedule.md) - PCRs sit on the byte grid the mux rate implies, paced against the fixed delay diff --git a/quest/m1/ts-export-byte-schedule.md b/quest/m1/tstd/byte-schedule.md similarity index 76% rename from quest/m1/ts-export-byte-schedule.md rename to quest/m1/tstd/byte-schedule.md index 1130acbd2d2..5ff8a268bd6 100644 --- a/quest/m1/ts-export-byte-schedule.md +++ b/quest/m1/tstd/byte-schedule.md @@ -16,10 +16,11 @@ UDP sink is out of scope; delivery stays with an external tool. `rs/moq-mux/src/container/ts/export.rs` (`advance`, `emit`, `stuff`): a PCR's value follows its byte position at the mux rate, and a keyframe burst is spread over the slots before its DTS instead of landing between two PCRs. -- That makes the mux run ahead of decode by a buffer delay. The delay grows to - fit the largest burst seen and is capped by `--max-age`, which already bounds - the pacer's lead; no new flag. Say what happens when a burst does not fit the - cap (fail loud, or drop to VBR with a warning) and record the choice here. +- That makes the mux run ahead of decode by a buffer delay. Decided + (2026-09-30): the delay is the fixed `--delay` from + [fixed-delay release](/quest/m1/tstd/delay.md), not one that grows + to fit bursts. Say what happens when a burst does not fit the delay (fail + loud, or drop to VBR with a warning) and record the choice here. - The CLI `Delivery` pacer releases one slice per PCR interval; confirm it still writes on the schedule the PCRs describe. - `test/ts/pcr-timing.py`'s `pcr-schedule` grades the bytes between @@ -28,3 +29,7 @@ UDP sink is out of scope; delivery stays with an external tool. a PCR slot; the generated clip mostly pads and passes already. - `doc/bin/cli.md`: say that export pads to `mpegts.muxRate` on a constant-rate schedule and what latency that adds. + +## Required + +- [Fixed-delay release](/quest/m1/tstd/delay.md) - the delay this schedule paces against diff --git a/quest/m1/tstd/check.md b/quest/m1/tstd/check.md new file mode 100644 index 00000000000..a7c42f511f8 --- /dev/null +++ b/quest/m1/tstd/check.md @@ -0,0 +1,25 @@ +# [M] The TS harness grades the full T-STD buffer model + +## Goal + +`test/ts/compliance.py` models every T-STD buffer an elementary stream passes +through, not only the transport buffer. It fails a stream where any buffer +overflows or where an access unit hasn't fully arrived by its DTS, and the TS +recipe runs it strictly against `moq export ts` output in CI. + +## Plan + +Today the `tstd` check models only the transport-buffer (TB) smoothing stage. +It's a shape check that warns unless `--strict` is set (`test/ts/README.md`). +Extend it to the multiplex buffer (MB, for video) and elementary buffer (EB) +with the ISO 13818-1 leak rates and sizes for each stream type and level, and +remove each access unit at its DTS. Timing stays on the stream's own PCR +clock, so the result is deterministic for a file. + +Validate the model before gating: a known-compliant reference TS passes, and +a deliberately bursty one fails. Where TSDuck or another maintained tool +already implements T-STD, prefer it over hand-rolled math. + +Gate: strict `tstd` in the TS recipe for export output. Until +[fixed-delay release](/quest/m1/tstd/delay.md) lands, the check will likely +fail, so land it report-only and flip the gate in that PR. diff --git a/quest/m1/tstd/delay.md b/quest/m1/tstd/delay.md new file mode 100644 index 00000000000..e07d26616e6 --- /dev/null +++ b/quest/m1/tstd/delay.md @@ -0,0 +1,74 @@ +# [M] Muxing exports release frames on a fixed delay + +## Goal + +`moq export ts --delay ` works like an SRT receiver's TSBPD, through a +release stage in moq-mux that the FLV and MKV exports adopt next. Each frame +goes out at its media time plus a fixed delay, measured from when the first +frame arrived, and in `(pts, pid)` order across tracks. A frame that misses its +deadline is dropped and counted. Output order is then a function of the media +alone, even under sustained loss, and the output runs at the source's pace +instead of bursting after a stall. + +## Plan + +Decided (2026-09-30): + +- Why: TS assumes a constant end-to-end delay. Its tracks share one PCR clock, + and a receiver's T-STD buffers are sized for access units that arrive a fixed + time before their DTS, which is what SRT and UDP sinks deliver. +- The release stage is shared, not TS-specific: it takes each track's + frames, releases them in `(pts, track)` order at anchor + pts + delay, and + drops and counts late ones. TS adopts it here; FLV and MKV follow in their + own quests. fMP4 stays out: it deliberately skips cross-track ordering, + because its demuxers index by track (`fmp4/export.rs`). The fixed delay is + needed only at the final receiver; relays stay hop-by-hop. + Open for the PR: the stage's name and module. Ask the maintainer. +- One mode. Fixed-delay release replaces the stall/hold interleave in + `rs/moq-mux/src/container/ts/export.rs` (`stall`, `hold`, and the wait in + `pick_next_track`), which is deleted. #4618 is the interim fix for #4613 + until this lands. The hold can't stay deterministic under loss, because a + rewind clears every track's `timeline`, so the mux falls back to arrival + order until a quiet track shows. +- The release clock is anchored at the first frame's local arrival. A rewind + (a new program generation) re-anchors it. Publisher clock drift slowly + grows or shrinks the buffer; correct it only if measured. +- The flag is `--delay`, like `moq play`'s: one knob sets both the release + delay and the sources' staleness budget, and it replaces `--max-age` on + `moq export ts` (`moq play` already dropped `--max-age` for the same reason). + moq-srt egress passes its SRT latency (`rs/moq-srt/src/ts.rs`, which feeds + it to the muxer as the skip budget today). +- Deadlines are on decode time, not PTS. Reordered video reaches the muxer in + decode order (PTS 0, 120, 40, 80 ms), so a PTS deadline would either strand + a B-frame behind its reference or send it first. Each frame's deadline is + anchor + its authored DTS + delay, each track keeps its decode order, and + tracks interleave by `(DTS, pid)`, which is also the order T-STD removes + access units in. +- Late frames are dropped, as SRT's too-late drop does. A dropped video frame + leaves its track waiting for the next keyframe. + +Open: a backlogged or finished source (a file sink, an archive replay) would +come out at real-time pace from the first frame's arrival. Decide whether +release only gates drops and ordering, with pacing left to the CLI's +`Delivery` pacer, or whether file sinks skip it. + +Test with mocked time: two exporters fed the same frames with different +arrival skew, every frame inside its deadline in both, emit identical packet +order. Separately, a frame arriving after its deadline is dropped and counted, +and the rest still go out in `(DTS, pid)` order. A B-frame fixture (decode +order PTS 0, 120, 40, 80) loses nothing on a clean path. It must pass before +the hold is deleted. Rerun the #4613 netem rig (10% loss, 120 s) and +compare with #4618's numbers. + +Update `doc/bin/cli.md` and the `moq export ts` examples. + +Public API: `ts::Export` takes the delay in place of its max age and loses the +hold; breaking, on `dev`. Wire: +none. + +## Related + +- [FLV export delay](/quest/m1/flv-export-delay.md) - adopts the release stage +- [MKV export delay](/quest/m1/mkv-export-delay.md) - adopts the release stage +- [TS byte schedule](/quest/m1/tstd/byte-schedule.md) - uses this delay as its mux-ahead buffer delay +- [Plan: max-delay](/quest/m1/plan-max-delay.md) - whether `max_age` becomes `max_delay` everywhere else From e89fce17d979c3f051d99e1a10758cabc7f05bc1 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 16:44:31 -0700 Subject: [PATCH 124/128] quest: apply the wildcard/cluster audit (#4629) Co-authored-by: Claude Opus 5.5 --- quest/m0/README.md | 1 + quest/m0/path-hunting.md | 49 +++++ quest/m1/README.md | 5 +- quest/m1/cluster-routing/README.md | 187 ++++++------------ quest/m1/cluster-routing/inter-cluster.md | 14 +- quest/m1/cluster-routing/propagation.md | 67 ------- quest/m1/cluster-routing/roles.md | 54 +++++ quest/m1/cluster-routing/selection.md | 42 ++-- quest/m1/cluster-routing/topology.md | 56 ------ quest/m1/hop-aligned-import.md | 4 +- quest/m1/{cluster-routing => }/hop-removal.md | 2 +- quest/m1/ietf-cluster-off.md | 40 ++++ quest/m1/route-cost.md | 29 +++ quest/m2/README.md | 1 + quest/m2/ietf-cluster-peers.md | 32 +++ 15 files changed, 296 insertions(+), 287 deletions(-) create mode 100644 quest/m0/path-hunting.md delete mode 100644 quest/m1/cluster-routing/propagation.md create mode 100644 quest/m1/cluster-routing/roles.md delete mode 100644 quest/m1/cluster-routing/topology.md rename quest/m1/{cluster-routing => }/hop-removal.md (96%) create mode 100644 quest/m1/ietf-cluster-off.md create mode 100644 quest/m1/route-cost.md create mode 100644 quest/m2/ietf-cluster-peers.md diff --git a/quest/m0/README.md b/quest/m0/README.md index 8263867ee71..5ec1c79c845 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -47,6 +47,7 @@ Published API or wire breaks still land on dev; each quest's Plan says so. - [quest check everywhere](/quest/m0/quest-check-everywhere.md) - `quest check` guards `main`, `dev`, and the line branches on push and PR, not only PRs into `main` - [noq reassembly cap](/quest/m0/noq-reassembly-cap.md) - noq carries quinn's stream reassembly cap and the connection receive window is finite by default - [qmux reset race](/quest/m0/qmux-reset-race.md) - qmux handles RESET_STREAM under one lock instead of panicking +- [Path hunting](/quest/m0/path-hunting.md) - a withdrawn path is retracted about once per relay instead of hunting stale alternatives, with a hold-down on route updates and no wire change - [Shared fronts](/quest/m0/shared-fronts.md) - viewer sessions share a front, so fronts scale with peers, not viewers - [Frame alloc budget](/quest/m0/frame-alloc-budget.md) - frame buffers pre-allocate within a per-session budget and otherwise grow with bytes received - [Handshake deadline](/quest/m0/handshake-deadline.md) - an unfinished handshake or slow HTTP header times out diff --git a/quest/m0/path-hunting.md b/quest/m0/path-hunting.md new file mode 100644 index 00000000000..7ca416b2467 --- /dev/null +++ b/quest/m0/path-hunting.md @@ -0,0 +1,49 @@ +# [M] A withdrawn path stops hunting + +## Goal + +When a broadcast ends, each relay in a lite-06 mesh retracts it about once, +instead of re-announcing stale alternatives. Today one withdrawal on live's +34-relay graph costs hundreds to over a thousand extra announce starts, and +on Kick dev an ended name drew 575 to 57,805 mesh announce starts (median +about 13,000) while live names drew one flood (moq-dev/moq.pro#2116). New +and removed routes still propagate at once, and no wire changes. + +## Plan + +Promoted from the cluster routing line to m0 on 2026-09-30: it is today's +partial-mesh hunting that #4399 left open, and it is hurting production. + +Decided (2026-09-30), lite-06, no wire change: + +- A route *update*, where a relay's advertised route for a path switches to a + different route, waits a short hold-down before it is re-advertised. A new + path (nothing advertised yet) and a removal (nothing left) go out at once. +- So when the best route is withdrawn and an alternative remains, the relay + retracts at once and re-announces the alternative only if it survives the + hold-down. Stale alternatives are withdrawn inside that window and never + spread. A genuine failover, where a link dies but the origin still + publishes, is delayed by the hold-down; pick the value from the repro, and + report the failover cost it adds. +- Check the interaction with #4399's withdrawal hiding and with + subscriptions already pinned to a route (fronts keep serving from a live + source; only advertisements are held). + +Test first: land moq.pro's in-process repro upstream (real lite-06 sessions +over the mock transport on live's 34-relay graph, mocked time), asserting +about one retraction per relay for a single withdrawal from a non-hub +publisher, plus a failover test where a link dies and the path comes back +through another route after the hold-down. It must fail on `main` today. + +Then moq.pro moves its pin and confirms about one retraction wave per ended +name on Kick dev after a deploy the user approves (moq.pro's own quest). + +If no hold-down closes it, the fallback is a per-origin seqno on cluster +links in the wip lite version; report before building it. + +Public API: none expected. Wire: none. + +## Related + +- [Cluster routing](/quest/m1/cluster-routing/README.md) - tiers shrink the core graph this hunts on +- [Cross-relay delivery under bursts](/quest/m1/cross-relay-bursts.md) - closed broadcasts announced for minutes, the same symptom diff --git a/quest/m1/README.md b/quest/m1/README.md index 0a35642776c..a2c2562c696 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -23,7 +23,10 @@ QUIC studies there on that rule. ## Required - [Cluster idle timeout](/quest/m1/cluster-idle-timeout.md) - a relay notices a silent peer relay within seconds, not after the shared 30 s QUIC idle timeout -- [Cluster routing](/quest/m1/cluster-routing/README.md) - a relay learns the relay graph once and each announcement once, not once per neighbour, and redundant publishers share an epoch instead of `--hop` +- [moq-transport peers are plain clients](/quest/m1/ietf-cluster-off.md) - no moq-transport session negotiates the cluster extension, so none can splice a pool's members on a Hop ID label +- [Cluster routing](/quest/m1/cluster-routing/README.md) - edge and core tiers carry each broadcast into a region once over path vector, with the backbone hidden from end users +- [Remove `--hop`](/quest/m1/hop-removal.md) - on `dev`, redundant publishers share an explicit `@`, and `--hop` and the publisher's Hop ID are gone +- [One route cost](/quest/m1/route-cost.md) - on `dev`, Warm and Cold collapse to one static route cost - [Track tail interop](/quest/m1/track-tail-interop.md) - a Rust publisher ending a track with a group in flight is read to its end by the JS subscriber, and the reverse, in `just test interop` - [Merge queue](/quest/m1/merge-queue.md) - the required checks run on `merge_group`, so a stale green check can no longer break main - [Binding audio delay](/quest/m1/binding-surface.md) - moq-ffi and every wrapper configure and observe audio playout delay diff --git a/quest/m1/cluster-routing/README.md b/quest/m1/cluster-routing/README.md index 16121aff8dd..386f8655e93 100644 --- a/quest/m1/cluster-routing/README.md +++ b/quest/m1/cluster-routing/README.md @@ -2,128 +2,66 @@ ## Goal -Cut cluster gossip. A relay learns how to reach each other relay once, from -a topology shared across the cluster rather than repeated in every route, -and learns each announcement once rather than once per neighbour. Every relay -still holds the ledger of live announcements that ANNOUNCE_REQUEST and a cold -SUBSCRIBE need, and a broadcast under overlapping prefixes routes to one -origin deterministically. Redundancy an operator configures may deliver more -than one copy. - -Non-goals: warm re-origination (a warm relay would be one more origin with a -cost, so leave room for it), and a permanently mixed-version cluster. +A cluster carries each broadcast into a region once and never exposes its +backbone to end users. Relays take an explicit edge or core role: edges +serve end users and spread paths over their region's cores, cores link to +the cores of other regions over configured links with static costs, and +routing between them stays path vector. A broadcast under overlapping +prefixes routes to one origin deterministically. Redundancy an operator +configures may deliver more than one copy. + +Non-goals: edges acting as each other's intermediates (it makes edges a +bigger DDoS target), cache-aware route switching, and a permanently +mixed-version cluster. ## Plan ### Decisions -Settled in the 2026-09-30 `/quest-plan`: - -- The goal stays wide. The design below is the current candidate, not a - decision; [Propagation](/quest/m1/cluster-routing/propagation.md) settles - how announcements move and writes the implementation children that follow. -- Topology is a cluster message kept apart from routes, built from configured - links only (`--cluster-connect`, the connect API, LAN mDNS). Gossip - discovery goes first, but only the topology child waits on it. -- Every relay holds a record for every live announcement, since - ANNOUNCE_REQUEST and a SUBSCRIBE with no prior announce both need one. - Scoping that knowledge by demand needs registries, which Propagation may - defer to m2. -- `--hop` goes. An epoch-qualified concrete path (`foo/@`) is the - identity of a source: origins that announce the same one are - interchangeable, which is how a redundant pair is expressed. It is strictly - better than a Hop ID, which is per session, so a connection could not - publish several broadcasts with different identities. A path a claim - produces keeps Wildcard's per-origin identity, even once announced - concretely, since each worker's output is its own. -- The line lands on `dev`: deleting `--hop` and the publisher's Hop setup - parameter breaks a published CLI and wire. Wire changes go in the current - wip version (`moq-lite-07-wip` today, dropping `Hop Base` and `Hop Keep` - before they publish). If lite-07 is finalized first for the Wildcard - rollout, the remaining children move to the next wip version; finalizing - never waits on this line. -- A short idle timeout for cluster sessions is its own m1 quest, - [Cluster idle timeout](/quest/m1/cluster-idle-timeout.md), since it helps - today's path vector too. -- Reduced flooding ([RFC 9667](https://www.rfc-editor.org/rfc/rfc9667)) and - registries are m2 unless Propagation pulls registries in; Propagation writes - whichever it defers. +Settled in the 2026-09-30 wildcard audit (cache tiers), replacing the +link-state and existence-split design planned earlier that day: + +- Two roles, edge and core. Where a region has one edge, that edge is also + its core. A region may have several cores, which do not link to each other. + An edge dials every core in its region over qmux on TLS (intra-region links + are not congested) and picks one per path by rendezvous hashing, so a + broadcast crosses into a region once. An edge never re-advertises one + core's routes to another, so it is never transit. Cores dial the cores of + the regions they link to, only those with lower names, so each pair has one + connection. Cores are hidden from end users, which is the DDoS shield. See + [Edge and core](/quest/m1/cluster-routing/roles.md). +- Core links are configured and static, and may skip PoPs when the RTT is + short: Seattle pulls from San Jose directly rather than via Oregon. Nothing + switches routes on cache state, so Warm and Cold collapse to one route cost + ([One route cost](/quest/m1/route-cost.md)), and the wildcard line's route + upgrade quest is deleted. +- No link-state topology. With split-horizon edges and a sparse core graph, + path vector with hop lists stays loop-free, path hunting is confined to the + cores, liveness flooding (the simulator's dominant link-state cost) is never + paid, and failure detection sets the outage window either way. The parked + implementation is #4631. If stale paths remain on the tiered layout, the + fix is [Path hunting](/quest/m0/path-hunting.md), promoted to m0: a hold-down + on route updates, with no wire change. +- The line lands on `main`: its children are additive. The two breaking + changes left it for `dev` on their own: + [Remove `--hop`](/quest/m1/hop-removal.md) and + [One route cost](/quest/m1/route-cost.md). +- Cluster links are moq-lite only; moq-transport peers are plain clients + ([moq-transport peers are plain clients](/quest/m1/ietf-cluster-off.md)). +- An epoch-qualified concrete path (`foo/@`) is a source's identity: + origins that announce the same one are interchangeable, which is how a + redundant pair is expressed. A path a claim produces keeps Wildcard's + per-origin identity. See [Selection](/quest/m1/cluster-routing/selection.md). - Between clusters, announcements stay path vector with cluster ids as hops, in the last child. - -### Why not path vector or Babel - -Today every relay advertises its best route to every peer not already in the -hop chain, and pulls every peer's full table with an empty-prefix -ANNOUNCE_REQUEST. One publish costs about R·(d-1) announces for R relays of -mesh degree d, every relay learns every broadcast (`.stats` and `.internal` -included), and a link change rewrites every route crossing it. On moq.pro's -live fleet (26 PoPs, average degree about 5) each relay receives every event -about five times. Babel ([RFC 8966](https://www.rfc-editor.org/rfc/rfc8966)) -shrinks the message and skips equal-cost reroutes, but it is still distance -vector: the same fan-out, the same global knowledge, and no loop freedom -when several sources claim a prefix (section 2.7), which pools and wildcards -make MoQ's common case. - -moq.pro's routing simulator (`just rs sim`, -[moq.pro#2020](https://github.com/moq-dev/moq.pro/pull/2020)) measured worse -than that on live's relay graph (34 relays, mean degree 8.4): a publish costs -about 750 announces, and ending a path's only publisher explores stale -alternatives for about a second and 39k to 80k announces, with subscribes -looping meanwhile. Coalescing each writer for 10 ms cuts that by 7x and leaves -the loops. Hiding the routes through a peer that withdrew the path -([#4399](https://github.com/moq-dev/moq/pull/4399)) reduces that path hunting -but does not end it; see the findings below. - -### Candidate design - -The children own their parts: topology in -[Topology](/quest/m1/cluster-routing/topology.md), existence and registries -in [Propagation](/quest/m1/cluster-routing/propagation.md), origin choice in -[Selection](/quest/m1/cluster-routing/selection.md). - -- Existence is split from reachability. An announcement carries the path, its - origin relay, and the origin's cost, and nothing about the path to it. -- An existence event carries the origin's seqno, scoped to its incarnation. A - relay applies an event only when it is newer than the last it applied for - that path and origin, and keeps an ended path's seqno, so a start delayed on - a stale tree or a failed-over registry cannot revive it. Babel keeps - feasibility past withdrawal for the same reason - ([RFC 8966 section 3.7.3](https://www.rfc-editor.org/rfc/rfc8966#section-3.7.3)). -- A new incarnation is learned from existence, never inferred from liveness: - it announces a reset (its incarnation at seqno 0) that ends everything the - old one published, and a relay applies a reset and the records after it as - one batch. Incarnations are ordered, so a delayed reset from an older one is - dropped. Purging on a liveness report instead drops a restarted origin's - broadcasts until their re-announce lands, which the simulator showed as live - broadcasts reported offline. -- Relays flood per-link liveness among themselves with a per-link seqno scoped - to the relay's incarnation, batched for a short hold-down, with a digest - exchange on session up. -- A relay picks the origin with the lowest shortest-path distance plus origin - cost, ties broken by rendezvous hashing (HRW) of the requested path and the - origin id, and forwards along its shortest path. The longest covering - prefix still ranks first, per [Wildcard](/quest/m0/wildcard/README.md). The - first relay's choice rides the SUBSCRIBE, and transit relays forward toward - that origin by topology alone. SUBSCRIBE and FETCH carry a visited-relay - list as a loop safety net. -- Announcements to clients are on demand: a relay forwards only the union of - its clients' ANNOUNCE_REQUEST prefixes. `.stats` becomes ordinary demand. -- Registries are an optional, configured tier: moq-relay in a registry mode, - one or more per region. Registries form a small full mesh and flood - existence among themselves, so an event crosses an ocean once per remote - registry. A relay fails over to the next-nearest registry and reconciles; - with none reachable it freezes its view and alerts rather than falling back - to flooding. -- Without registries, existence floods along the shortest-path tree, one copy - per relay. A relay forwards an event only when it changes its view, and a - relay that gains a child in its tree pushes that origin's reset and records - to it. -- The cluster switches versions as a whole; older lite and IETF sessions stay - at its edges. +- Anything specific to moq.pro's deployment (generating peer lists and roles + from its inventory, its simulator) is planned in moq.pro, not here. ### Simulator findings +Measured on the earlier flat mesh; they motivated the link-state design the +tiers decision replaced, and still bound what path vector costs. + The report is moq.pro's `just rs sim` (every scenario on live's graph) and `just rs sim sweep` (synthetic regional graphs of 34, 340, and 1020 relays). It carries messages and bytes by kind, per relay and cross-region, @@ -147,8 +85,8 @@ registry. relay loss is noticed after the 30 s QUIC idle timeout in every candidate, and subscribes through it go nowhere until then. - The simulator saw no loop while views agreed, and HRW split an equal-cost - pool 63/49 where today's hash of the announced prefix sends all of it to one - sibling. On live's graph no disagreement looped across 20 seeds of link, + pool 63/49 where a hash of the announced prefix sent all of it to one + sibling (Wildcard has since keyed the tie on the requested path). On live's graph no disagreement looped across 20 seeds of link, cost, and relay churn. - One registry per region and two cost about the same; two halves the busiest registry's load. A registration sent on a dead registry session @@ -169,26 +107,25 @@ registry. Once every child has landed: -- An end-to-end test: a multi-relay cluster in `rs/moq-relay/tests` where a - publish, an end, a relay restart, and a redundant-pair failover each reach - a subscriber on a far relay, with time mocked. -- Rewrite `doc/bin/relay/cluster.md` into the operator's view (topology, - link costs, idle timeout, redundant pairs), and add a routing page under - `doc/concept`. +- An end-to-end test: a two-region cluster in `rs/moq-relay/tests` where a + publish, an end, a core loss, and a redundant-pair failover each reach a + subscriber on a far edge, with time mocked. +- Rewrite `doc/bin/relay/cluster.md` into the operator's view (edge and core + layout, dial rules, TLS edge links, link costs, idle timeout, redundant + pairs), and add a routing page under `doc/concept`. ## Required -- [Topology](/quest/m1/cluster-routing/topology.md) - relays learn the relay graph once from a cluster message, apart from routes -- [Propagation](/quest/m1/cluster-routing/propagation.md) - decides how each announcement reaches every relay once, and writes the implementation children +- [Edge and core](/quest/m1/cluster-routing/roles.md) - relays take an explicit edge or core role; edges spread paths over their region's cores and are never transit - [Selection](/quest/m1/cluster-routing/selection.md) - a broadcast under overlapping prefixes routes to one origin deterministically, and same-epoch origins are one source -- [Remove `--hop`](/quest/m1/cluster-routing/hop-removal.md) - redundant publishers share an explicit `@`, and `--hop` and the publisher's Hop ID are gone - [Between clusters](/quest/m1/cluster-routing/inter-cluster.md) - announcements crossing a cluster boundary stay path vector with cluster ids as hops ## Related - [Wildcard](/quest/m0/wildcard/README.md) - the longest-prefix rule, pool spread, and reply identity Selection builds on -- [Cluster idle timeout](/quest/m1/cluster-idle-timeout.md) - failure detection sets every outage window, today and after this line +- [Remove `--hop`](/quest/m1/hop-removal.md) - on `dev`: redundant publishers share an explicit `@` +- [One route cost](/quest/m1/route-cost.md) - on `dev`: Warm and Cold collapse to one static cost - [Same-hop importers](/quest/m1/hop-aligned-import.md) - the importer half of a redundant pair; `--hop` removal re-keys it to a shared epoch - [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - a redundant pair shares one epoch -- [Cross-relay delivery under bursts](/quest/m1/cross-relay-bursts.md) - its #4349 report also shows closed broadcasts announced for up to 229 s and flapping between Retracted and Announced across nodes, evidence for per-incarnation seqnos +- [Cross-relay delivery under bursts](/quest/m1/cross-relay-bursts.md) - its #4349 report shows closed broadcasts announced for up to 229 s, evidence for per-origin seqnos - [Routing cost domains](/quest/m3/routing-cost-domains.md) - cost across the cluster boundaries this keeps path vector diff --git a/quest/m1/cluster-routing/inter-cluster.md b/quest/m1/cluster-routing/inter-cluster.md index 43386d65eff..7bc07c072fa 100644 --- a/quest/m1/cluster-routing/inter-cluster.md +++ b/quest/m1/cluster-routing/inter-cluster.md @@ -5,18 +5,18 @@ Announcements crossing a cluster boundary stay path vector with cluster ids as the hops, like BGP between autonomous systems. A customer's on-prem cluster is one hop, and an announcement naming the receiving cluster is -dropped. Inside a cluster nothing carries a list of relay hops. +dropped. Inside a cluster, hop lists name relays; across a boundary they name +clusters. ## Plan - A boundary is a configured link to a relay of another cluster; decide how a relay knows its own cluster id and its peer's. -- What crosses a boundary is what the chosen - [Propagation](/quest/m1/cluster-routing/propagation.md) design holds, plus - its cluster-id list. An imported record keeps that list as provenance, so +- What crosses a boundary is a cluster's announcement, plus its cluster-id + list. An imported record keeps that list as provenance, so whichever boundary relay exports it appends its own cluster id to the full list; stripping it on import would let A → B → C → A re-enter A. -- The remote origin is outside the receiving cluster's topology, so the +- The remote origin is outside the receiving cluster, so the importing boundary relay announces the record inside its cluster as the origin, with the boundary link's cost added. The serving origin's identity still rides the reply, so re-originating does not merge two sources. @@ -31,10 +31,6 @@ draft updated in the same PR. Tests: two clusters with two boundary links and an origin that is not a boundary relay, and three clusters in a cycle with different ingress and egress relays, where an announcement neither loops nor re-enters its origin cluster. -## Required - -- [Propagation](/quest/m1/cluster-routing/propagation.md) - the record shape a boundary exports - ## Related - [Routing cost domains](/quest/m3/routing-cost-domains.md) - designs policy on this path vector diff --git a/quest/m1/cluster-routing/propagation.md b/quest/m1/cluster-routing/propagation.md deleted file mode 100644 index 283b0d20c78..00000000000 --- a/quest/m1/cluster-routing/propagation.md +++ /dev/null @@ -1,67 +0,0 @@ -# [M] Plan announcement propagation - -## Goal - -Decide how an announcement reaches every relay in a cluster once, rather than -once per neighbour, and how every relay keeps the ledger of live announcements -that ANNOUNCE_REQUEST and a cold SUBSCRIBE need. The output is a decision -recorded in the [questline README](/quest/m1/cluster-routing/README.md), -worked counterexamples, and rewritten implementation quests, not production -code. - -## Plan - -Decided: every relay holds a record for every live announcement, and an -announcement names its origin relay and cost, not a path to it -([Topology](/quest/m1/cluster-routing/topology.md) supplies reachability). - -Candidates to choose between or combine: - -- **Tree flooding with per-origin seqnos.** The README's candidate design: - existence floods along the origin's shortest-path tree, a relay forwards an - event only when it changes its view, and per-origin seqnos with - incarnation resets stop stale revivals. This is the same as "skip a - neighbour already closer to the origin": a relay forwards only to its - children in that origin's tree. -- **A central node owns gossip.** Registries: an optional tier, one or more - per region, full-meshed among themselves. An ingest relay registers with - its nearest, an edge sends its ANNOUNCE_REQUEST there, and a relay fails - over to the next-nearest and reconciles (its full live set at its current - seqno, ending whatever it leaves out; the registry's snapshot carries each - origin's last reconcile seqno). With none reachable a relay freezes its - view and alerts. The simulator found registries buy cross-ocean bytes and - one-round-trip announce latency, not message count, at live's 34 relays. -- **A compressed ledger.** The records are a replicated ledger of every live - announcement; sync it with digests (anti-entropy) and compress it, such as - prefix-shared paths, instead of per-event messages. - -Measure the choice with the simulator's scenarios (messages and bytes per -event, convergence, stale revival, restart, failover). - -Open questions the chosen design must answer: - -- How long a relay keeps an ended path's seqno. A new origin incarnation - clears it; within one, it must outlive every delayed copy of the start. -- How a relay that just became another's tree child catches up on what it - missed within the same incarnation. Its reset only marks a new incarnation, - so the push may need a watermark like the registry reconcile's: it ends only - what the child holds at or below it, and a delayed push cannot erase newer - records. -- How long a relay keeps the records of an origin that never comes back. They - stop being reported once it is unreachable, but nothing removes them. -- Whether registries belong in this line. If deferred, write an m2 quest for - them with sharding (HRW over a prefix key) and a mixed-version bridge as its - open questions, and one for reduced flooding - ([RFC 9667](https://www.rfc-editor.org/rfc/rfc9667)). - -The implementation quests it writes replace the empty-prefix ANNOUNCE_REQUEST -between peers and per-hop path-vector announcements, drop `Hop Base` and -`Hop Keep` from the current wip lite version. Add each one to the Required of -[Selection](/quest/m1/cluster-routing/selection.md) and -[Routing between clusters](/quest/m1/cluster-routing/inter-cluster.md), so -neither starts on a record shape that is not implemented yet. - -## Related - -- [Cross-relay delivery under bursts](/quest/m1/cross-relay-bursts.md) - its report of closed broadcasts announced for minutes is evidence for per-origin seqnos -- [Announcement shapes](/quest/m2/announce-shapes.md) - announcements between relays must keep their shape diff --git a/quest/m1/cluster-routing/roles.md b/quest/m1/cluster-routing/roles.md new file mode 100644 index 00000000000..c6e2f9628e9 --- /dev/null +++ b/quest/m1/cluster-routing/roles.md @@ -0,0 +1,54 @@ +# [M] Edge and core relays + +## Goal + +A relay runs as an edge or a core, and a cluster built from them carries +each broadcast into a region once. An edge serves end users, dials every core +in its region, spreads paths over those cores by rendezvous hashing, and is +never transit between cores. A core serves only cluster peers, dials the +cores of the regions it links to, and never dials an edge. + +## Plan + +Decided in the 2026-09-30 wildcard audit (cache tiers): + +- The role is the node's own `cluster.role`, explicit, from config or + alongside the peer list the connect API returns. A relay whose links + contradict its role (an edge linked to another edge, a core dialing an + edge) fails at startup. Where a region has one edge, that edge is its core. +- A relay with no role is a legacy peer and links any peer, as before roles. + A core accepts and dials a legacy peer as a core-grade link, and an edge + never links one. This is what lets an operator migrate one region at a + time: a migrated region's cores bridge to the unmigrated mesh. A + permanently mixed cluster stays a non-goal. +- A core refuses a session that is not a cluster peer, loudly, so a + misrouted client fails instead of silently exposing the shield. +- Cores dial only cores with lower names, so each pair has one connection; + cores in one region do not link to each other. This is configuration: the + relay follows its peer list, and whatever generates the list applies the + rule. +- Edge links run qmux over TLS on TCP, not WebSocket and not QUIC: + intra-region links are not congested. qmux over TCP exists today only in + plaintext (`tcp://`); add `tls://`, wired to qmux's existing `tls` module. + (Scheme name decided 2026-09-30.) +- An edge never re-advertises a route learned from one core to another core: + its cluster dials publish only what entered locally + (`origin::Consumer::local()`), so no core routes through an edge. +- An edge picks a core per path with the path-keyed rendezvous hash the + wildcard line gave `route_order`, so every edge in a region sends a path to + the same core, and failover moves only the paths the lost core served. The + per-path spread across equally ranked cores is + [Selection](/quest/m1/cluster-routing/selection.md)'s. + +Test: a two-region cluster (two edges and two cores in one region, one core +in the other) in `rs/moq-relay/tests`, where subscribers on both edges of a +region cause one cross-region subscription per broadcast, a route from one +core never reaches another through an edge, a client dialing a core is +refused, and losing a core moves only its paths. + +Public API: a relay config field for the role and a TLS qmux URL scheme. +Wire: none expected. + +## Related + +- [moq-transport peers are plain clients](/quest/m1/ietf-cluster-off.md) - cluster links are lite-only diff --git a/quest/m1/cluster-routing/selection.md b/quest/m1/cluster-routing/selection.md index c75f2b5b81a..8cb3b0cbd50 100644 --- a/quest/m1/cluster-routing/selection.md +++ b/quest/m1/cluster-routing/selection.md @@ -3,7 +3,8 @@ ## Goal A broadcast under overlapping announcements routes to one origin chosen -deterministically, and every relay forwards toward that origin by topology. +deterministically, and an edge spreads paths over its region's cores so +every edge sends a given path the same way. Origins that announce the same epoch-qualified concrete path are one source, so a subscriber moves between them at a group boundary when the incumbent ends or becomes unreachable. @@ -26,45 +27,34 @@ Decided: announce the same epoch-qualified path and must not pool. This extends Wildcard's resume rule to concrete same-epoch origins. -Candidate mechanics: +Candidate mechanics (re-scoped to path vector by the 2026-09-30 tiers +decision; there is no topology to forward by): -- A relay picks the origin with the lowest shortest-path distance plus origin - cost, ties broken by rendezvous hashing (HRW) of the requested path and the - origin id, and forwards along its shortest path. That is a shortest path to - a virtual node linked to every origin, so it is loop-free whenever relays - agree on the topology. -- The first relay's choice rides the SUBSCRIBE and FETCH, and transit relays - forward toward that origin by topology alone, never re-selecting. - Re-selection against another existence view loops: a relay that lost a - specific claim falls back to a broader one through a relay still routing to - the specific one - ([RFC 8966 section 3.5.4](https://www.rfc-editor.org/rfc/rfc8966#section-3.5.4)). - A refusal follows Wildcard's refusal rule: only a capacity refusal lets the - first relay select once more within the same longest-prefix tier, excluding - the refusing origin, and any other refusal is terminal. -- SUBSCRIBE and FETCH carry a visited-relay list end to end. It catches loops - while liveness views disagree and names the path for stats. The serving - origin's identity rides the reply, per Wildcard's first-hop resume rule. +- Route selection stays `route_order` over the routes a relay holds: longest + prefix, then cost, then a rendezvous hash (HRW) of the requested path and + the route's origin. At an edge that spreads paths over the region's cores + and makes every edge pick the same core for a path; failover moves only the + paths the lost core won. +- A refusal follows Wildcard's refusal rule: every refusal is terminal, and + an origin sheds load by withdrawing or re-pricing its route instead. +- The serving origin's identity rides the Origin field of the reply, per + Wildcard's resume rule. Open: -- Whether equal-cost next hops should spread by a hash of the path. A fixed - tie-break sends every path through the same neighbour, and its failure - takes them all. - How a relay tells claim output from a redundant pair. One candidate: a concrete path an origin announces under its own claim keeps per-origin identity, since a redundant publisher claims nothing. -Wire: SUBSCRIBE and FETCH fields in the current wip lite version, with the -draft updated in the same PR. Tests cover an HRW split across an equal-cost +Wire: none expected; if one is needed it goes in the current wip lite +version with the draft. Tests cover an HRW split across an equal-cost pool, refusal and reselection, a same-epoch pair failing over mid-track with no timestamp rewind, and a concrete double claim whose loser's subscribers end and resubscribe rather than splice. ## Required -- [Topology](/quest/m1/cluster-routing/topology.md) - distance to each origin -- [Propagation](/quest/m1/cluster-routing/propagation.md) - the record shape that names each origin +- [Edge and core](/quest/m1/cluster-routing/roles.md) - the edges and cores this spreads over - [Wildcard](/quest/m0/wildcard/README.md) - the longest-prefix rule, pool spread, and reply identity this builds on ## Related diff --git a/quest/m1/cluster-routing/topology.md b/quest/m1/cluster-routing/topology.md deleted file mode 100644 index d10cc59f9c2..00000000000 --- a/quest/m1/cluster-routing/topology.md +++ /dev/null @@ -1,56 +0,0 @@ -# [L] Cluster topology - -## Goal - -Relays learn the relay graph once, from a cluster message kept apart from -routes, instead of every route repeating how to reach its origin. Each relay -knows every configured link, whether it is up, and its cost, and computes its -shortest path to every other relay. No announcement is needed to learn that -relay K exists or how to reach it. - -## Plan - -Decided: the topology is configured. `--cluster-connect` or the connect API -gives the relay graph and link costs, and LAN mDNS dials peers that then count -as configured links. Gossip discovery is already gone. - -Candidate mechanics, from the simulator (see the questline README's -findings): - -- Relays flood per-link liveness among themselves with a per-link seqno. The - seqno is scoped to the relay's incarnation, so a restarted relay's links - supersede its stale ones instead of looking older. -- A relay batches the liveness reports it sends, its own and those it - forwards, for a short hold-down (50 ms in the simulator), and recomputes its - shortest paths after a matching delay, as OSPF's SPF delay does. Unbatched, - one relay restart at 340 relays sent half a million messages; batched, 27k. -- On session up, relays exchange a digest (each reporter's incarnation and - its seqno per link) and send only what the other lacks. A reporter's - reports flood separately, so its newest seqno alone would hide a missing - older one. The digest already counts the fresh report of the link that just - came up; sending the database first replays the relay's own report from - when the link went down, and the peer drops the link it is using. -- Distance compares cost, then hop count, so every hop strictly shortens it - even across `?cost=0` links. - -Reduced flooding ([RFC 9667](https://www.rfc-editor.org/rfc/rfc9667)) is -out of scope; [Propagation](/quest/m1/cluster-routing/propagation.md) writes -it as an m2 quest if it stays deferred. - -Open: moq-transport cluster peers. Cluster links accept moq-transport 17+ -today via the cluster extension (`drafts/draft-lcurley-moq-cluster.md`), -which these messages do not reach. -Either extend that draft, or refuse a cluster session that does not negotiate -the wip lite version, per the README's "the cluster switches versions as a -whole". Never accept a peer that cannot carry the topology. - -Wire: new cluster-session messages in the current wip lite version, with the -draft updated in the same PR. Tests drive topologies in process with mocked -time, including restart, a link flapping, and a digest racing a link that -just came up. Expose the computed graph where operators already look -(`/nodes` in `rs/moq-relay/src/internal.rs`). - -## Related - -- [Cluster idle timeout](/quest/m1/cluster-idle-timeout.md) - liveness only reports what the session layer detects -- [Drain](/quest/m1/drain/README.md) - a second relay per PoP joins this topology diff --git a/quest/m1/hop-aligned-import.md b/quest/m1/hop-aligned-import.md index 250076067bd..56ec73b95bc 100644 --- a/quest/m1/hop-aligned-import.md +++ b/quest/m1/hop-aligned-import.md @@ -15,7 +15,7 @@ exits (#4354). Decided: same-hop publishers MUST publish the same broadcasts and tracks. Keep `--hop` for now: the users' bugs are on one relay today. Cluster routing replaces it with a shared explicit epoch on `dev` (decided -2026-09-30), and its [`--hop` removal](/quest/m1/cluster-routing/hop-removal.md) +2026-09-30), and its [`--hop` removal](/quest/m1/hop-removal.md) re-keys this quest's docs and tests. The importer work holds under either key. Make every container importer (ts, fmp4, flv, mkv, and the SRT, RTMP, and HLS gateways that reuse them) meet the contract when fed one @@ -44,5 +44,5 @@ survives the standby joining and the incumbent stopping. ## Related -- [Remove `--hop`](/quest/m1/cluster-routing/hop-removal.md) - on dev, a redundant pair shares an explicit epoch instead, and this quest's docs and tests are re-keyed to it +- [Remove `--hop`](/quest/m1/hop-removal.md) - on dev, a redundant pair shares an explicit epoch instead, and this quest's docs and tests are re-keyed to it - [Broadcast epochs](/quest/m1/broadcast-epoch/README.md) - a redundant pair shares one epoch diff --git a/quest/m1/cluster-routing/hop-removal.md b/quest/m1/hop-removal.md similarity index 96% rename from quest/m1/cluster-routing/hop-removal.md rename to quest/m1/hop-removal.md index 2dcdf8221f1..7000837b894 100644 --- a/quest/m1/cluster-routing/hop-removal.md +++ b/quest/m1/hop-removal.md @@ -32,7 +32,7 @@ idle timeout (a failover service that retracts it, or active-active delivery to the relay). Neither is required to land this. Public API and wire: removes a CLI flag and the publisher's Hop setup -parameter; lands with the line on `dev`. +parameter; lands on `dev`, outside the cluster routing line (which lands on `main`). ## Required diff --git a/quest/m1/ietf-cluster-off.md b/quest/m1/ietf-cluster-off.md new file mode 100644 index 00000000000..4c8bd4be470 --- /dev/null +++ b/quest/m1/ietf-cluster-off.md @@ -0,0 +1,40 @@ +# [S] moq-transport peers are plain clients + +## Goal + +No moq-transport session negotiates the MoQ Cluster extension +(`draft-lcurley-moq-cluster`). A moq-transport peer is always served as a +plain client: it never receives Hop IDs or relay costs and never acts as a +cluster link. Cluster links are moq-lite only. moq-transport end users stay +fully supported. + +## Plan + +Why now: the Wildcard line spreads a pool's paths behind one route, and names +the serving member only in lite-07's reply Origin. The cluster extension has +no such field, so a moq-transport downstream relay pins failover to the +advertisement's first Hop ID, which labels the pool rather than the member, +and can splice one member's objects onto another's. A peer that never learns +Hop IDs cannot make that mistake. Decided in the 2026-09-30 wildcard audit, +matching the topology decision that cluster links are lite-only. + +- Stop offering and accepting the cluster Setup Options in Rust + (`rs/moq-net/src/ietf/cluster.rs`, `parameters.rs`, `publish_namespace.rs`) + and JS (`js/net/src/ietf/cluster.ts` and its callers). A peer that offers + them is served as if it had not. +- Delete what becomes dead, in both languages. The draft stays: + [moq-transport cluster peers](/quest/m2/ietf-cluster-peers.md) extends it + and brings the code back. +- Update `doc/bin/relay/cluster.md` and `doc/concept` wherever they say + moq-transport relays can join a cluster. +- Test: a moq-transport 17+ peer that offers the extension gets a session + with no cluster parameters, and an announcement reaches it with no Hop IDs. + +Lands on `main`: extension negotiation is optional, so a peer that offered it +still gets a working session. Public API: none expected. Wire: we stop +negotiating an optional extension. + +## Related + +- [Edge and core](/quest/m1/cluster-routing/roles.md) - cluster links are lite-only +- [Wildcard](/quest/m0/wildcard/README.md) - the pool spread that makes a Hop ID label unsafe to splice on diff --git a/quest/m1/route-cost.md b/quest/m1/route-cost.md new file mode 100644 index 00000000000..e058957d870 --- /dev/null +++ b/quest/m1/route-cost.md @@ -0,0 +1,29 @@ +# [M] One route cost + +## Goal + +A route carries one static cost. Warm and Cold Route Cost, and the +cache-state accounting behind Warm, are gone from the next wip lite version +and from moq-net's model. lite-06 peers keep working. + +## Plan + +Decided in the 2026-09-30 wildcard audit (cache tiers): with configured edge +and core tiers and static core links, nothing switches routes on cache +state, so Warm has no job. + +- The next wip lite version (`moq-lite-07-wip` while it is unpublished) + carries a single route cost in ANNOUNCE_START and ANNOUNCE_UPDATE. Update + `drafts/draft-lcurley-moq-lite.md` in the same PR. +- lite-06 sessions keep parsing both fields: read Warm as the cost and + ignore Cold, and write the one cost as Warm with Cold at the saturation + ceiling. +- The single cost still prices a standby claim above a live one, per the + wildcard line's standby floor. Update that text in + `quest/m0/wildcard/README.md` and anything else naming `Cost { warm, cold }`. +- Replace `Cost { warm, cold }` in `rs/moq-net/src/model/origin.rs` and its + JS mirror, and delete what computes Warm from cache state. +- The moq-transport cluster extension already carries one cost. + +Public API: `Cost` changes shape (a break, so it lands on `dev`). Wire: the +wip version drops a field; lite-06 is unchanged. diff --git a/quest/m2/README.md b/quest/m2/README.md index 4de4234a256..e9c6f6e9f11 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -112,5 +112,6 @@ waiting on an upstream release waits in [m4](/quest/m4/README.md). - [SEI separation study](/quest/m2/sei.md) - measure whether separating SEI saves enough, or has a metadata-only consumer, to justify a split - [Compressed tracks](/quest/m2/flate.md) - moq-ffi and every wrapper expose flate tracks through a `flate` namespace like `json` - [Announcement shapes](/quest/m2/announce-shapes.md) - moq-lite announcements and interests carry prefix, exact, suffix, or prefix+suffix shapes that survive relay hops, benchmarked over the announce table +- [moq-transport cluster peers](/quest/m2/ietf-cluster-peers.md) - an extended cluster draft lets moq-transport relays peer again, stitching failover on the reply's origin - [MSFTS convergence](/quest/m2/msfts-convergence.md) - the demultiplexed TS lane converges on MSFTS where the two still differ: program tables and the ES payload unit - [VAAPI encode and decode](/quest/m2/video-vaapi.md) - H.265 encode and decode, pre-generated bindings, and pooled resize surfaces, including the moq-dev/vaapi release that carries them diff --git a/quest/m2/ietf-cluster-peers.md b/quest/m2/ietf-cluster-peers.md new file mode 100644 index 00000000000..24c9d708499 --- /dev/null +++ b/quest/m2/ietf-cluster-peers.md @@ -0,0 +1,32 @@ +# [L] moq-transport cluster peers + +## Goal + +A moq-transport relay can join a cluster as a peer again, through an +extended `draft-lcurley-moq-cluster`, and never splices one pool member's +content onto another's. + +## Plan + +Replaces the wildcard line's "Cluster origin reply" quest. Until this lands, +moq-transport peers are plain clients +([moq-transport peers are plain clients](/quest/m1/ietf-cluster-off.md)). + +The extension must carry what a lite cluster link carries by then: + +- The serving origin in the reply, mirroring lite-07's SUBSCRIBE_OK and + FETCH_OK Origin, so a downstream stitches failover on the member serving the + path rather than the advertisement's first Hop ID. The draft's "Several + Publishers of One Namespace" section changes with it. +- Whatever the [cluster routing line](/quest/m1/cluster-routing/README.md) + settles for topology and selection, since cluster links are lite-only there. + +Test: two workers behind a pool relay behind a moq-transport downstream relay; +killing the serving worker ends the downstream subscription rather than +splicing the survivor's objects. + +Wire: extends `draft-lcurley-moq-cluster`, updated in the same PR. + +## Required + +- [Cluster routing](/quest/m1/cluster-routing/README.md) - settles what a cluster link carries From ef2511e101f80a70f1d4897bdbbb38f7f5018e69 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 17:40:55 -0700 Subject: [PATCH 125/128] fix(moq-net): hold route updates so a withdrawal retracts once (#4642) Co-authored-by: Claude Opus 5.5 --- doc/bin/relay/cluster.md | 7 + rs/moq-net/src/driver.rs | 1 + rs/moq-net/src/ietf/publisher.rs | 14 +- rs/moq-net/src/lite/publisher.rs | 4 + rs/moq-net/src/model/mod.rs | 2 +- rs/moq-net/src/model/origin.rs | 283 +++++++++++++++++++++++++--- rs/moq-net/src/time.rs | 27 +++ rs/moq-net/tests/mesh_withdraw.rs | 76 +++++++- rs/moq-net/tests/support/harness.rs | 15 ++ rs/moq-net/tests/support/mock.rs | 63 +++++-- 10 files changed, 446 insertions(+), 46 deletions(-) diff --git a/doc/bin/relay/cluster.md b/doc/bin/relay/cluster.md index 31dbdf069b3..d64da538e70 100644 --- a/doc/bin/relay/cluster.md +++ b/doc/bin/relay/cluster.md @@ -22,6 +22,13 @@ relayed from what the peer just withdrew, rather than falling back to them one by one. During reconnect, another session from that peer can still advertise the broadcast; an old session's withdrawal does not invalidate that route. +A relay two hops from the publisher's still holds routes relayed through others. +So a change of a broadcast's best route waits 300 ms before it is announced, +while a new broadcast and a removed one go out at once. By then the withdrawal +has usually removed the other stale routes too, and the relay sends one +retraction instead of advertising each stale path in turn. Requests still +follow the current best route immediately; only the announcement waits. + Failover routes must carry copies of the same broadcast. For each track, the relay requires matching timescale, retention window, publisher priority, and group ordering. A source with different properties is refused before its groups diff --git a/rs/moq-net/src/driver.rs b/rs/moq-net/src/driver.rs index 22c677e4bb4..41779a81aed 100644 --- a/rs/moq-net/src/driver.rs +++ b/rs/moq-net/src/driver.rs @@ -62,6 +62,7 @@ impl Driver { /// Panics if `now` is earlier than the previous poll or construction time. pub fn poll(&mut self, now: Instant, waiter: &kio::Waiter) -> Result, Error> { self.clock.advance(now); + self.clock.register_driver(waiter); match self.state.poll(waiter) { Poll::Ready(Ok(())) => Err(Error::Closed), Poll::Ready(Err(err)) => Err(err), diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index 5de4a889e8c..8b11b56424c 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -5147,7 +5147,12 @@ mod tests { async fn a_repricing_is_a_request_update() { const VERSION: Version = Version::Draft19; - let origin = crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(); + // Forward the update at once: the hold is not what this checks. + let origin = crate::origin::Config { + update_hold: Duration::ZERO, + ..crate::origin::Config::new(crate::Hop::new(1).unwrap()) + } + .produce(); let _cold = origin .announce("cam", crate::origin::Route::default().with_cost(4)) .unwrap(); @@ -5214,7 +5219,12 @@ mod tests { async fn a_publisher_change_is_a_request_update() { const VERSION: Version = Version::Draft19; - let origin = crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(); + // Forward the update at once: the hold is not what this checks. + let origin = crate::origin::Config { + update_hold: Duration::ZERO, + ..crate::origin::Config::new(crate::Hop::new(1).unwrap()) + } + .produce(); let publisher_a = crate::Hops::try_from(vec![crate::Hop::new(7).unwrap()]).unwrap(); let publisher_b = crate::Hops::try_from(vec![crate::Hop::new(8).unwrap()]).unwrap(); let _from_a = origin diff --git a/rs/moq-net/src/lite/publisher.rs b/rs/moq-net/src/lite/publisher.rs index 4ca5adafbd2..c967dc27500 100644 --- a/rs/moq-net/src/lite/publisher.rs +++ b/rs/moq-net/src/lite/publisher.rs @@ -1857,6 +1857,7 @@ mod announce_test { h.announcement .update(crate::origin::Route::default().with_hops(pub_hops()).with_cost(3)) .unwrap(); + tokio::time::sleep(crate::origin::DEFAULT_UPDATE_HOLD).await; settle().await; match h.wire.take_announces().as_slice() { [lite::AnnounceBroadcast::Restart { id: 0, hops, cost }] => { @@ -1908,10 +1909,12 @@ mod announce_test { let mut h = harness().await; let route = |cost| crate::origin::Route::default().with_hops(pub_hops()).with_cost(cost); h.announcement.update(route(u64::MAX)).unwrap(); + tokio::time::sleep(crate::origin::DEFAULT_UPDATE_HOLD).await; settle().await; assert_eq!(h.wire.take_announces().len(), 1, "expected the clamped restart"); h.announcement.update(route(u64::MAX - 1)).unwrap(); + tokio::time::sleep(crate::origin::DEFAULT_UPDATE_HOLD).await; settle().await; h.assert_idle(); } @@ -1981,6 +1984,7 @@ mod announce_test { .with_cost(u64::MAX), ) .unwrap(); + tokio::time::sleep(crate::origin::DEFAULT_UPDATE_HOLD).await; settle().await; match h.wire.take_announces().as_slice() { [lite::AnnounceBroadcast::Restart { cost, .. }] => { diff --git a/rs/moq-net/src/model/mod.rs b/rs/moq-net/src/model/mod.rs index 39937261fd1..78bbe59c922 100644 --- a/rs/moq-net/src/model/mod.rs +++ b/rs/moq-net/src/model/mod.rs @@ -41,7 +41,7 @@ pub use timed::Timed; /// Publishing broadcasts, announcing routes, and consuming both through an origin. pub mod origin { pub use super::origin_impl::{ - Config, Consumer, Cost, Driver, Dynamic, Producer, Request, Requesting, Route, Source, + Config, Consumer, Cost, DEFAULT_UPDATE_HOLD, Driver, Dynamic, Producer, Request, Requesting, Route, Source, }; } diff --git a/rs/moq-net/src/model/origin.rs b/rs/moq-net/src/model/origin.rs index 4413b418da6..300a46640f4 100644 --- a/rs/moq-net/src/model/origin.rs +++ b/rs/moq-net/src/model/origin.rs @@ -126,8 +126,24 @@ pub struct Config { /// edge. Defaults to [`track::DEFAULT_MAX_AGE`], and [`Self::cache_duration`] /// still caps it. pub default_max_age: Duration, + + /// How long an announce cursor holds a changed route before delivering it. + /// + /// A new route and a removed one are delivered at once; only an update (a + /// prefix whose best route changes while it stays reachable) waits, and a + /// newer change during the wait replaces it. When a publisher withdraws, a + /// relay that loses its best route but still holds routes derived from the + /// withdrawn one sends nothing while the withdrawal wave removes them, then one + /// retraction, instead of advertising each stale path in turn. It must outlast + /// the wave's spread across the mesh. Defaults to [`DEFAULT_UPDATE_HOLD`]; + /// zero delivers updates at once. + pub update_hold: Duration, } +/// The default [`Config::update_hold`]: longer than a withdrawal takes to cross a +/// global mesh, with margin. +pub const DEFAULT_UPDATE_HOLD: Duration = Duration::from_millis(300); + impl Default for Config { /// A fresh random hop with no byte target and the default idle expiry. fn default() -> Self { @@ -137,6 +153,7 @@ impl Default for Config { pool, cache_duration: Duration::MAX, default_max_age: track::DEFAULT_MAX_AGE, + update_hold: DEFAULT_UPDATE_HOLD, } } } @@ -634,6 +651,18 @@ fn route_order(prefix: &Path, entry: &RouteEntry) -> (bool, Cost, bool, usize, u /// The `(hops, cost, source)` metadata an announce cursor delivers alongside a prefix. type RouteMeta = (Hops, Cost, Source); +/// A pending update's hold, keyed by prefix in its [`AnnounceConsumer`]. +/// +/// A consumer reads the origin's clock outside the driver, where it holds the +/// driver's last reading, not the time the update arrived. So a hold first waits +/// for the driver's next reading (armed a nanosecond past the stale one, which +/// wakes the driver at once), and counts from there. +#[derive(Clone, Copy)] +enum Held { + Anchoring(Instant), + Until(Instant), +} + /// One coalesced update queued for an `AnnounceConsumer`. /// /// At most one entry exists per prefix, so a slow consumer's pending set is @@ -698,9 +727,48 @@ impl OriginConsumerState { } } - /// Take one update to deliver to the consumer, if any. - fn take(&mut self) -> Option { - let prefix = self.pending.keys().next()?.clone(); + /// Whether the pending entry at `prefix` changes a route the consumer holds + /// to another route, rather than adding or removing one. + fn is_update(&self, prefix: &PathOwned, update: &PendingUpdate) -> bool { + matches!(update, PendingUpdate::Announce(_)) && self.delivered.contains(prefix) + } + + /// The first pending prefix ready to deliver, or when the next held one is. + /// See [`Config::update_hold`]; a hold starts the first time a scan sees it. + fn scan( + &self, + held: &mut HashMap, + now: Option, + hold: Duration, + ) -> Result> { + let mut wake = None; + for (prefix, update) in &self.pending { + let holds = !hold.is_zero() && !self.ended && self.is_update(prefix, update); + let Some(now) = now.filter(|_| holds) else { + return Ok(prefix.clone()); + }; + // The clock reads the driver's last advance, which may be stale: anchor the + // hold on the first advance after the update arrived, by waking the driver. + let until = match held.get(prefix).copied() { + None => { + held.insert(prefix.clone(), Held::Anchoring(now)); + now + Duration::from_nanos(1) + } + Some(Held::Anchoring(seen)) if now <= seen => seen + Duration::from_nanos(1), + Some(Held::Anchoring(_)) => { + held.insert(prefix.clone(), Held::Until(now + hold)); + now + hold + } + Some(Held::Until(until)) if until <= now => return Ok(prefix.clone()), + Some(Held::Until(until)) => until, + }; + wake = Some(wake.map_or(until, |w: Instant| w.min(until))); + } + Err(wake) + } + + /// Take the pending update at `prefix` for delivery. + fn take_prefix(&mut self, prefix: PathOwned) -> Option { let ((meta, captures), kind) = match self.pending.remove(&prefix).unwrap() { PendingUpdate::Announce(meta) => { // The consumer has seen this prefix before, so it is a metadata update. @@ -1347,7 +1415,7 @@ impl Producer { pub fn new(config: Config) -> (Self, Driver) { let (tasks, set) = TaskSet::new(); let scope = OriginScope::default(); - let shared = kio::Shared::::default(); + let shared = kio::Shared::new(OriginState::new(config.update_hold)); let timers = Clock::default(); let pool = config.pool.clone(); let producer = Self { @@ -1402,6 +1470,7 @@ impl Producer { pool: self.pool.clone(), cache_duration: self.cache_duration, default_max_age: self.default_max_age, + update_hold: self.shared.lock().update_hold, } } @@ -1428,7 +1497,7 @@ impl Producer { hop, scope: OriginScope::empty(), root: PathOwned::default(), - shared: kio::Shared::default(), + shared: kio::Shared::new(OriginState::new(DEFAULT_UPDATE_HOLD)), pool: cache::Pool::default(), cache_duration: Duration::MAX, default_max_age: track::DEFAULT_MAX_AGE, @@ -2024,6 +2093,7 @@ impl Driver { /// has drained. pub fn poll(&mut self, now: Instant, waiter: &kio::Waiter) -> Result, Error> { self.timers.advance(now); + self.timers.register_driver(waiter); let result = self.state.poll(waiter); let gc = self.pool.gc(now); if result.is_ready() { @@ -3145,8 +3215,11 @@ impl RouteTable { /// Carried in a [`kio::Shared`], so producers, consumers, and handlers work /// under one lock. Broadcasts published here are route table entries like the /// routes announced from elsewhere; this holds everything that serves a path. -#[derive(Default)] struct OriginState { + // See [`Config::update_hold`]. No `Default`: every origin takes it from its + // config, so no path silently disables the hold. + update_hold: Duration, + // The announced routes, keyed by prefix. The table holds one entry per live // advertisement, not one per broadcast consumer. routes: RouteTable, @@ -3177,6 +3250,19 @@ struct OriginState { } impl OriginState { + fn new(update_hold: Duration) -> Self { + Self { + update_hold, + routes: RouteTable::default(), + next_route: 0, + next_watch: 0, + cursors: HashMap::new(), + fronts: WeakCache::default(), + withdrawn: HashMap::new(), + closed: false, + } + } + /// Whether a peer in `hops` withdrew `prefix`. fn withdrawn_through(&self, prefix: &Path, hops: &Hops) -> bool { if self.withdrawn.is_empty() { @@ -3930,7 +4016,14 @@ impl Consumer { if let Some(mount) = self.scope.mount(&self.root) { // A root the mount resolves past the depth limit has nothing to announce. let Some(root) = mount.resolve(&self.root) else { - return AnnounceConsumer::new(self.root.clone(), Vec::new(), state, self.stats.clone(), &self.shared); + return AnnounceConsumer::new( + self.root.clone(), + Vec::new(), + state, + self.stats.clone(), + &self.shared, + self.timers.clone(), + ); }; let cursors = vec![cursor( root, @@ -3940,7 +4033,14 @@ impl Consumer { PathOwned::default(), Vec::new(), )]; - return AnnounceConsumer::new(self.root.clone(), cursors, state, self.stats.clone(), &self.shared); + return AnnounceConsumer::new( + self.root.clone(), + cursors, + state, + self.stats.clone(), + &self.shared, + self.timers.clone(), + ); } // Otherwise the consumer's own cursor, minus the mounted subtrees, plus one @@ -3984,7 +4084,14 @@ impl Consumer { holes, ), ); - AnnounceConsumer::new(self.root.clone(), cursors, state, self.stats.clone(), &self.shared) + AnnounceConsumer::new( + self.root.clone(), + cursors, + state, + self.stats.clone(), + &self.shared, + self.timers.clone(), + ) } /// Returns a cheap duplicate of this read handle. @@ -4287,6 +4394,13 @@ pub struct AnnounceConsumer { // Holds the waiter a `Stream` poll registered; disjoint from `state` so the // borrow never collides with the body's. park: kio::Park, + + // Held updates (see [`Config::update_hold`]): their holds by prefix, the + // clock they count on, and the timer that wakes the next. + update_hold: Duration, + held: HashMap, + timers: Clock, + hold: crate::runtime::Deadline, } impl AnnounceConsumer { @@ -4296,10 +4410,13 @@ impl AnnounceConsumer { state: kio::Producer, stats: stats::Session, shared: &kio::Shared, + timers: Clock, ) -> Self { let mut ids = Vec::with_capacity(cursors.len()); + let update_hold; { let mut table = shared.lock(); + update_hold = table.update_hold; if table.closed { // A cursor on a dead origin is born ended. if let Ok(mut state) = state.write() { @@ -4322,6 +4439,10 @@ impl AnnounceConsumer { stats, guards: HashMap::new(), park: kio::Park::default(), + update_hold, + held: HashMap::new(), + hold: crate::runtime::Deadline::new(&timers), + timers, } } @@ -4356,29 +4477,53 @@ impl AnnounceConsumer { /// cursor is closed, or `Poll::Pending` after registering `waiter` to be /// notified when the next update arrives. pub fn poll_next(&mut self, waiter: &kio::Waiter) -> Poll> { - let update = { - let mut state = match ready!(self.state.poll(waiter, |state| { - if state.pending.is_empty() && !state.ended { - Poll::Pending - } else { - Poll::Ready(()) + loop { + let now = self.timers.try_now(); + let hold = self.update_hold; + let held = &mut self.held; + let mut ready = None; + let mut wake = None; + let update = match self.state.poll(waiter, |state| { + if state.pending.is_empty() { + return match state.ended { + true => Poll::Ready(()), + false => Poll::Pending, + }; + } + match state.scan(held, now, hold) { + Ok(prefix) => { + ready = Some(prefix); + Poll::Ready(()) + } + Err(at) => { + wake = at; + Poll::Pending + } } - })) { - Ok(state) => state, + }) { + Poll::Ready(Ok(mut state)) => match ready { + Some(prefix) => state.take_prefix(prefix), + None => { + // Ended by the origin's teardown, pending updates already + // drained; close the channel so every closure signal agrees. + state.close(); + None + } + }, // Closed: discard the Ref so its MutexGuard doesn't escape this call. - Err(_) => return Poll::Ready(None), - }; - match state.take() { - Some(update) => update, - None => { - // Ended by the origin's teardown, pending updates already - // drained; close the channel so every closure signal agrees. - state.close(); - return Poll::Ready(None); + Poll::Ready(Err(_)) => None, + Poll::Pending => { + self.hold.set(wake); + ready!(self.hold.poll(waiter)); + continue; } - } - }; - Poll::Ready(Some(self.hand_out(update))) + }; + let Some(update) = update else { + return Poll::Ready(None); + }; + self.held.remove(&update.prefix); + return Poll::Ready(Some(self.hand_out(update))); + } } /// Returns the next update without blocking. @@ -4386,7 +4531,21 @@ impl AnnounceConsumer { /// Returns None if there is no update available; NOT because the cursor is closed. /// Use [`Self::is_closed`] to check if the cursor is closed. pub fn try_next(&mut self) -> Option { - let update = self.state.write().ok()?.take()?; + let now = self.timers.try_now(); + let mut state = self.state.write().ok()?; + let prefix = match state.scan(&mut self.held, now, self.update_hold) { + Ok(prefix) => prefix, + Err(wake) => { + // Arm the hold even though nothing polls it: the armed timer wakes the + // driver, so its clock reaches the deadline for a later call to see. + drop(state); + self.hold.set(wake); + return None; + } + }; + self.held.remove(&prefix); + let update = state.take_prefix(prefix)?; + drop(state); Some(self.hand_out(update)) } @@ -6439,6 +6598,70 @@ mod tests { assert_eq!(announced.assert_next_active("room/x").source(), Source::Peer(origin(8))); } + /// A caller that only polls with `try_next` still gets a held update once its + /// hold passes. Nothing else wakes the idle driver, so the hold's own timer + /// must, or the origin's clock never reaches the deadline. + #[tokio::test(start_paused = true)] + async fn try_next_delivers_a_held_update() { + // Let paused time pass and every task woken by it run. + async fn step(by: Duration) { + tokio::time::advance(by).await; + for _ in 0..10 { + tokio::task::yield_now().await; + } + } + + let producer = origin(1).produce(); + let peer = producer.clone().peer(); + let mut announced = producer.consume().announced(); + step(Duration::from_millis(1)).await; + + let route = |chain: &[u64], via| Route::default().with_hops(hops(chain)).with_via(origin(via)); + let near = peer.dynamic("room", route(&[9, 2], 2)).unwrap(); + assert!(announced.try_next().unwrap().kind.is_active()); + + let _far = peer.dynamic("room", route(&[9, 3, 4], 4)).unwrap(); + drop(near); + assert!(announced.try_next().is_none(), "the update is held"); + step(Duration::from_millis(1)).await; + assert!(announced.try_next().is_none(), "the update is still held"); + step(DEFAULT_UPDATE_HOLD).await; + let update = announced.try_next().expect("the hold passed"); + assert_eq!(update.kind, AnnounceKind::Updated); + assert_eq!(update.route.hops, hops(&[9, 3, 4])); + } + + /// A new route and a removal are delivered at once. A change of the best route + /// waits out the update hold, and a newer change during the wait replaces it. + #[tokio::test(start_paused = true)] + async fn a_changed_route_waits_out_the_hold() { + let producer = origin(1).produce(); + let peer = producer.clone().peer(); + let mut announced = producer.consume().announced(); + // Holds count on the driver's clock, which starts at its first poll. + tokio::time::sleep(Duration::from_millis(1)).await; + + let route = |chain: &[u64], via| Route::default().with_hops(hops(chain)).with_via(origin(via)); + let near = peer.dynamic("room", route(&[9, 2], 2)).unwrap(); + announced.assert_next_active("room"); + + // The best route changes twice; the consumer sees only the last, once. + let far = peer.dynamic("room", route(&[9, 3, 4], 4)).unwrap(); + let farther = peer.dynamic("room", route(&[9, 5, 6, 7], 7)).unwrap(); + let start = tokio::time::Instant::now(); + drop(near); + drop(far); + let update = announced.next().await.unwrap(); + assert_eq!(update.kind, AnnounceKind::Updated); + assert_eq!(update.route.hops, hops(&[9, 5, 6, 7])); + assert_eq!(start.elapsed(), DEFAULT_UPDATE_HOLD); + announced.assert_next_wait(); + + // The last route goes: retracted at once. + drop(farther); + announced.assert_next_ended("room"); + } + /// A peer withdrawing a prefix hides the routes there through it, so the next /// best is never a path derived from the one withdrawn. Announcing again /// revives them, and nothing is remembered once no route passes through it. diff --git a/rs/moq-net/src/time.rs b/rs/moq-net/src/time.rs index bef0ba27b41..d73b688d4e9 100644 --- a/rs/moq-net/src/time.rs +++ b/rs/moq-net/src/time.rs @@ -66,6 +66,9 @@ struct State { now: Option, next: u64, timers: BTreeMap<(Instant, u64), Arc>>, + /// The driver's poll, woken when a timer armed outside it becomes the earliest, + /// so the driver's sleep never outlasts a deadline it did not see. + driver: kio::WaiterList, } impl Clock { @@ -100,6 +103,21 @@ impl Clock { } } + /// The latest supplied instant, or `None` before the first. + pub(crate) fn try_now(&self) -> Option { + let state = self.0.lock().unwrap(); + #[cfg(test)] + if state.automatic { + return Some(tokio::time::Instant::now().into_std()); + } + state.now + } + + /// Register the driver's poll to be woken by a new earliest timer. + pub(crate) fn register_driver(&self, waiter: &kio::Waiter) { + waiter.register(&mut self.0.lock().unwrap().driver); + } + pub(crate) fn timeout(&self) -> Option { self.0.lock().unwrap().timers.first_key_value().map(|((at, _), _)| *at) } @@ -160,6 +178,15 @@ impl crate::runtime::Timer for Timer { && state.now.is_none_or(|now| at > now) { state.timers.insert((at, self.id), self.waiters.clone()); + if state + .timers + .first_key_value() + .is_some_and(|(key, _)| *key == (at, self.id)) + { + let mut driver = state.driver.take(); + drop(state); + driver.wake(); + } } } fn poll(&mut self, waiter: &kio::Waiter) -> Poll<()> { diff --git a/rs/moq-net/tests/mesh_withdraw.rs b/rs/moq-net/tests/mesh_withdraw.rs index 37a9c349535..65d04646cbf 100644 --- a/rs/moq-net/tests/mesh_withdraw.rs +++ b/rs/moq-net/tests/mesh_withdraw.rs @@ -12,7 +12,7 @@ use std::{collections::HashMap, time::Duration}; use tokio::sync::mpsc; use moq_net::{Hop, Version, announce, broadcast, origin}; -use support::harness::{MockPair, peer}; +use support::harness::{MockPair, peer, peer_with_latency}; fn produce_origin(hop: u64) -> origin::Producer { let (producer, driver) = origin::Producer::new(origin::Config::new(Hop::new(hop).unwrap())); @@ -144,3 +144,77 @@ async fn partial_mesh_withdraw_then_republish() { } let _broadcasts = mesh.publish(100, 5).await; } + +/// A 34-relay partial mesh: moq.pro's production graph on 2026-09-30, where +/// relays in neighboring PoPs peer and most reach a publisher's relay through +/// others. +#[rustfmt::skip] +const PRODUCTION: &[(usize, usize)] = &[ + (0, 20), (0, 22), (0, 29), (1, 3), (1, 12), (1, 14), (1, 21), (2, 20), (2, 26), (2, 32), (3, 8), + (3, 11), (3, 15), (3, 16), (3, 17), (3, 18), (3, 21), (3, 22), (3, 23), (3, 24), (3, 29), (3, 30), + (3, 31), (4, 7), (4, 20), (4, 22), (4, 25), (4, 29), (5, 20), (5, 27), (5, 33), (6, 23), (6, 24), + (6, 30), (6, 31), (7, 22), (7, 25), (7, 29), (8, 15), (8, 17), (8, 21), (8, 23), (8, 30), (9, 19), + (9, 22), (9, 23), (9, 28), (9, 29), (9, 30), (10, 19), (10, 20), (10, 22), (10, 23), (10, 26), + (10, 27), (10, 28), (10, 29), (10, 30), (10, 32), (10, 33), (11, 15), (11, 16), (11, 21), + (12, 14), (12, 27), (12, 33), (13, 14), (13, 27), (13, 33), (14, 26), (14, 27), (14, 32), + (14, 33), (15, 21), (16, 18), (16, 21), (17, 21), (17, 24), (17, 31), (18, 21), (18, 22), + (18, 23), (18, 24), (18, 29), (18, 30), (18, 31), (19, 22), (19, 23), (19, 26), (19, 28), + (19, 29), (19, 30), (19, 32), (20, 22), (20, 26), (20, 27), (20, 29), (20, 32), (20, 33), + (21, 22), (21, 23), (21, 24), (21, 29), (21, 30), (21, 31), (22, 23), (22, 24), (22, 25), + (22, 26), (22, 27), (22, 28), (22, 29), (22, 30), (22, 31), (22, 32), (22, 33), (23, 24), + (23, 28), (23, 29), (23, 30), (23, 31), (24, 29), (24, 30), (24, 31), (25, 29), (26, 27), + (26, 28), (26, 29), (26, 32), (26, 33), (27, 29), (27, 32), (27, 33), (28, 29), (28, 30), + (28, 32), (29, 30), (29, 31), (29, 32), (29, 33), (30, 31), (32, 33), +]; + +/// One-way latency in ms for each [`PRODUCTION`] link, from the great-circle +/// distance between its PoPs at 200 km/ms over a path 1.5 times as long, plus 1 ms. +#[rustfmt::skip] +const PRODUCTION_LATENCY_MS: &[u64] = &[ + 10, 7, 7, 50, 30, 51, 50, 9, 13, 13, 5, 4, 6, 8, 3, 4, 1, 50, 6, 4, 50, 6, 4, 50, 63, 58, 50, 58, + 16, 5, 5, 10, 10, 10, 10, 12, 1, 12, 6, 3, 5, 8, 8, 5, 4, 43, 5, 4, 43, 6, 11, 8, 49, 22, 23, 6, + 8, 49, 22, 23, 3, 5, 4, 41, 103, 103, 60, 91, 91, 59, 64, 59, 64, 6, 9, 8, 3, 6, 6, 4, 48, 4, 3, + 48, 4, 3, 5, 44, 26, 1, 5, 44, 26, 15, 21, 18, 15, 21, 18, 50, 6, 4, 50, 6, 4, 45, 47, 12, 29, 30, + 5, 1, 45, 47, 29, 30, 2, 44, 45, 1, 2, 47, 2, 1, 12, 9, 26, 29, 1, 9, 30, 9, 1, 5, 44, 26, 45, 47, + 29, 30, 2, 9, +]; + +/// One withdrawal on a partial mesh retracts everywhere once. A relay two hops +/// from the publisher's hears only that its neighbor withdrew, and must not +/// fall back to, and re-advertise, another path derived from the same +/// announcement. Holding route updates (`origin::Config::update_hold`) lets the +/// withdrawal remove those paths first; with link latency and no hold, each +/// withdrawal here costs tens of thousands of announcements. +#[tokio::test(start_paused = true)] +async fn partial_mesh_withdraw_retracts_once() { + let version: Version = "moq-lite-06".parse().unwrap(); + let nodes: Vec<_> = (1..=34).map(produce_origin).collect(); + let mut pairs = Vec::new(); + for (&(a, b), &ms) in PRODUCTION.iter().zip(PRODUCTION_LATENCY_MS) { + pairs.push(peer_with_latency(version, &nodes[a], &nodes[b], Duration::from_millis(ms)).await); + } + let mut watched: Vec<_> = nodes.iter().map(|node| watch(node.consume().announced())).collect(); + + for publisher in [5, 13, 22, 26, 32] { + let broadcast = nodes[publisher].create_broadcast(format!("room/{publisher}")).unwrap(); + broadcast.announce(Default::default()).unwrap(); + for (relay, watched) in watched.iter_mut().enumerate() { + let updates = drain(watched).await; + assert!( + updates.values().all(|kinds| kinds.last().unwrap().is_active()), + "relay {relay}: {updates:?}" + ); + } + + drop(broadcast); + let mut hunted = Vec::new(); + for (relay, watched) in watched.iter_mut().enumerate() { + let updates = drain(watched).await; + let kinds = &updates[&format!("room/{publisher}")]; + if kinds != &[announce::Kind::Retracted] { + hunted.push((relay, kinds.clone())); + } + } + assert!(hunted.is_empty(), "publisher {publisher}: {hunted:?}"); + } +} diff --git a/rs/moq-net/tests/support/harness.rs b/rs/moq-net/tests/support/harness.rs index 2c4db0b07d3..3b8b5683f2b 100644 --- a/rs/moq-net/tests/support/harness.rs +++ b/rs/moq-net/tests/support/harness.rs @@ -29,6 +29,8 @@ pub struct MockConnectOptions { pub server_publish: Option, /// Origin the server inserts remote broadcasts into. pub server_subscribe: Option, + /// One-way delay for stream data in each direction. + pub latency: std::time::Duration, } impl MockConnectOptions { @@ -40,6 +42,7 @@ impl MockConnectOptions { client_subscribe: None, server_publish: None, server_subscribe: None, + latency: std::time::Duration::ZERO, } } } @@ -67,6 +70,7 @@ pub struct MockPair { pub async fn connect_mock(opts: MockConnectOptions) -> MockPair { let protocol = opts.version.alpn(); let (client_transport, server_transport) = create_mock_session_pair(Some(protocol)); + client_transport.set_latency(opts.latency); let transports = (client_transport.clone(), server_transport.clone()); let mut client = Client::new().with_versions(opts.version.into()); @@ -117,6 +121,16 @@ pub async fn connect_mock(opts: MockConnectOptions) -> MockPair { /// Peer two relays the way `moq-relay`'s cluster does: one session, both directions. pub async fn peer(version: Version, a: &origin::Producer, b: &origin::Producer) -> MockPair { + peer_with_latency(version, a, b, std::time::Duration::ZERO).await +} + +/// [`peer`] over a link with a one-way `latency`. +pub async fn peer_with_latency( + version: Version, + a: &origin::Producer, + b: &origin::Producer, + latency: std::time::Duration, +) -> MockPair { let a = a.clone().peer(); let b = b.clone().peer(); let mut options = MockConnectOptions::new(version); @@ -124,5 +138,6 @@ pub async fn peer(version: Version, a: &origin::Producer, b: &origin::Producer) options.client_subscribe = Some(a); options.server_publish = Some(b.consume().with_hidden(true)); options.server_subscribe = Some(b); + options.latency = latency; connect_mock(options).await } diff --git a/rs/moq-net/tests/support/mock.rs b/rs/moq-net/tests/support/mock.rs index 36e5f74ea05..e2813e1f4ba 100644 --- a/rs/moq-net/tests/support/mock.rs +++ b/rs/moq-net/tests/support/mock.rs @@ -13,8 +13,11 @@ //! its earlier data is read. use std::{ + future::Future, + pin::Pin, sync::{Arc, Mutex}, task::{Context, Poll}, + time::Duration, }; use bytes::Bytes; @@ -104,9 +107,12 @@ impl ClosedSignal { } } +/// A chunk in flight: readable by the peer once the link latency has passed. +type Flight = (tokio::time::Instant, StreamChunk); + /// A mock send stream backed by a queue to the peer's reader. pub struct MockSendStream { - tx: Option>, + tx: Option>, closed: Arc, park: kio::Park, /// Acknowledge the FIN as soon as it is sent, for a stream the peer's transport holds @@ -124,7 +130,8 @@ impl MockSendStream { return Err(err); } let tx = self.tx.as_ref().ok_or_else(MockError::closed)?; - tx.try_push(chunk).map_err(|_| MockError::closed()) + let arrival = tokio::time::Instant::now() + self.conn.latency(); + tx.try_push((arrival, chunk)).map_err(|_| MockError::closed()) } } @@ -190,7 +197,11 @@ impl Drop for MockSendStream { /// A mock receive stream backed by a queue from the peer's writer. pub struct MockRecvStream { - rx: kio::Queue, + rx: kio::Queue, + /// The next chunk, popped but still crossing the link. + flight: Option, + /// Wakes the reader when `flight` lands. + landing: Option>>, /// Buffered bytes from a chunk that was partially consumed. buf: Bytes, /// Whether we hit FIN or reset. @@ -205,16 +216,29 @@ impl MockRecvStream { /// Pop the next chunk, mapping queue closure to an implicit FIN. Once everything /// sent before a CONNECTION_CLOSE is read, an unfinished stream fails with it. fn poll_chunk(&mut self, cx: &mut Context<'_>) -> Poll> { - let waiter = self.park.hold(cx); - self.conn.waiters.register(waiter); - match self.rx.poll_pop(waiter) { - Poll::Ready(Ok(chunk)) => Poll::Ready(Some(chunk)), - Poll::Ready(Err(_)) => Poll::Ready(None), - Poll::Pending => match self.conn.error() { - Some(_) => Poll::Ready(Some(StreamChunk::Closed)), - None => Poll::Pending, - }, + if self.flight.is_none() { + let waiter = self.park.hold(cx); + self.conn.waiters.register(waiter); + match self.rx.poll_pop(waiter) { + Poll::Ready(Ok(flight)) => self.flight = Some(flight), + Poll::Ready(Err(_)) => return Poll::Ready(None), + Poll::Pending => { + return match self.conn.error() { + Some(_) => Poll::Ready(Some(StreamChunk::Closed)), + None => Poll::Pending, + }; + } + } + } + let (arrival, _) = self.flight.as_ref().expect("flight set above"); + if *arrival > tokio::time::Instant::now() { + let landing = self + .landing + .get_or_insert_with(|| Box::pin(tokio::time::sleep_until(*arrival))); + landing.as_mut().reset(*arrival); + std::task::ready!(landing.as_mut().poll(cx)); } + Poll::Ready(self.flight.take().map(|(_, chunk)| chunk)) } } @@ -313,6 +337,8 @@ fn new_stream_pair(conn: &Arc) -> (MockSendStream, MockRecvStre }; let recv = MockRecvStream { rx: queue, + flight: None, + landing: None, buf: Bytes::new(), done: false, closed, @@ -332,11 +358,17 @@ fn new_stream_pair(conn: &Arc) -> (MockSendStream, MockRecvStre struct ConnectionState { /// Set once by whichever side closes first. close_state: Mutex>, + /// One-way delay for stream data in each direction. Zero by default. + latency: Mutex, /// Wakes both sides when close_state is populated. waiters: kio::Fan, } impl ConnectionState { + fn latency(&self) -> Duration { + *self.latency.lock().unwrap() + } + /// The close every stream and accept fails with, once the connection closed. fn error(&self) -> Option { let state = self.close_state.lock().unwrap(); @@ -580,6 +612,13 @@ impl MockSession { pub fn lose_datagrams(&self) { *self.side.lossy.lock().unwrap() = true; } + + /// Delay stream data sent from now on by `latency` in each direction, keeping + /// each stream in order. Measured on tokio's clock, so paused-time tests advance + /// through it without sleeping. + pub fn set_latency(&self, latency: Duration) { + *self.side.conn.latency.lock().unwrap() = latency; + } } impl MockSession { From 472231acdb17b0e797b53eeba60a053661842805 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 17:49:04 -0700 Subject: [PATCH 126/128] fix(hls): an estimated framerate keeps the rendition (#4641) Co-authored-by: Claude Opus 5.5 --- rs/moq-hls/src/export/mod.rs | 56 +++++++++++++++++ rs/moq-hls/src/export/rendition.rs | 35 +++++++---- rs/moq-hls/src/export/renditions.rs | 8 +-- rs/moq-mux/src/container/fmp4/muxer.rs | 85 ++++++++++++++++++++++++++ 4 files changed, 169 insertions(+), 15 deletions(-) diff --git a/rs/moq-hls/src/export/mod.rs b/rs/moq-hls/src/export/mod.rs index 1d3cc5df926..058eca36c6a 100644 --- a/rs/moq-hls/src/export/mod.rs +++ b/rs/moq-hls/src/export/mod.rs @@ -708,6 +708,62 @@ mod tests { assert_eq!(video.bandwidth(), 2_000_000); } + // The estimator also measures the framerate and publishes it once it settles, so an + // imported source gains one about a second in. Rebuilding for it would re-time the fMP4 + // (its timescale derives from the framerate) and churn every recording cursor mid-stream. + #[tokio::test] + async fn estimated_framerate_keeps_the_rendition() { + let origin = produce_origin(); + let _broadcast = origin.create_broadcast("live").expect("publish allowed"); + _broadcast.announce(Default::default()).expect("publish allowed"); + settle().await; + let upstream = empty_upstream(&origin, "live").await; + + let mut catalog = catalog_with_both(); + catalog.video.renditions.get_mut("video0").unwrap().framerate = None; + let renditions = renditions::Producer::new(Config::default().window); + let mut cursor = renditions.subscribe(); + renditions.sync(&upstream, &catalog); + let video = renditions.get(Kind::Video, "video0").expect("video rendition"); + while next_event(&mut cursor).await.is_some() {} + + for framerate in [Some(30.0), Some(60.0)] { + catalog.video.renditions.get_mut("video0").unwrap().framerate = framerate; + renditions.sync(&upstream, &catalog); + assert!( + Arc::ptr_eq(&video, &renditions.get(Kind::Video, "video0").unwrap()), + "the video rendition survives a framerate estimate of {framerate:?}" + ); + assert!(next_event(&mut cursor).await.is_none(), "no rendition churn"); + } + + // The settled estimate still reaches the fallback cadence of a duration-less frame, + // at the timescale the rendition was built with (90 kHz without a framerate). + let muxer = video.muxer().unwrap(); + assert_eq!(muxer.timescale().as_u64(), 90_000); + let fragment = muxer.fragment(0, &[vp8_frame(0, true)]).unwrap(); + assert_eq!(first_sample_duration(&fragment), Some(1_500), "16.7 ms at 90 kHz"); + + // An NTSC estimate is 1501.5 ticks at 90 kHz: it snaps to whole ticks and still muxes. + catalog.video.renditions.get_mut("video0").unwrap().framerate = Some(60_000.0 / 1001.0); + renditions.sync(&upstream, &catalog); + let fragment = video.muxer().unwrap().fragment(0, &[vp8_frame(0, true)]).unwrap(); + assert_eq!(first_sample_duration(&fragment), Some(1_502)); + } + + /// The `trun` duration of a fragment's first sample. + fn first_sample_duration(fragment: &bytes::Bytes) -> Option { + use moq_mux::container::fmp4::mp4_atom::{self, DecodeMaybe}; + + let mut cursor = std::io::Cursor::new(fragment.as_ref()); + while let Some(atom) = mp4_atom::Any::decode_maybe(&mut cursor).unwrap() { + if let mp4_atom::Any::Moof(moof) = atom { + return moof.traf[0].trun[0].entries[0].duration; + } + } + panic!("no moof in fragment"); + } + #[tokio::test] async fn estimate_before_first_init_reaches_aac_descriptor() { let origin = produce_origin(); diff --git a/rs/moq-hls/src/export/rendition.rs b/rs/moq-hls/src/export/rendition.rs index 7d30ee5f326..af468b35cc7 100644 --- a/rs/moq-hls/src/export/rendition.rs +++ b/rs/moq-hls/src/export/rendition.rs @@ -192,9 +192,9 @@ fn normalize_video(config: &VideoConfig) -> VideoConfig { config.delay = None; config.label = None; config.stalled = None; - // The muxer ignores a non-finite framerate, and NaN never equals itself, so a catalog - // carrying one would otherwise look different from itself on every republish. - config.framerate = config.framerate.filter(|fps| fps.is_finite()); + // Publishers estimate it and republish once it settles. The rendition keeps the fMP4 + // timescale it was built with, and the framerate is refreshed in place like the bitrate. + config.framerate = None; config } @@ -218,6 +218,9 @@ pub struct Rendition { /// Advertised bitrate for the master playlist `BANDWIDTH` attribute; read through /// [`bandwidth`](Self::bandwidth), refreshed in place by [`refresh`](Self::refresh). bitrate: RwLock>, + /// The latest catalog framerate (video only), refreshed in place by [`refresh`](Self::refresh): + /// the muxer's fallback sample cadence and the DASH `frameRate`. + framerate: RwLock>, /// Coded width, for the master playlist `RESOLUTION` (video only). pub width: Option, /// Coded height, for the master playlist `RESOLUTION` (video only). @@ -250,8 +253,8 @@ pub struct Rendition { impl Rendition { /// Whether `config` describes the same media this rendition is already serving, i.e. whether /// it decodes and muxes identically. Fields the publisher revises without touching the media - /// (its bitrate and jitter estimates, a label) are ignored here and picked up by - /// [`refresh`](Self::refresh) instead. + /// (its bitrate, jitter, and framerate estimates, a label) are ignored here, and the bitrate + /// and framerate are picked up by [`refresh`](Self::refresh) instead. pub(crate) fn matches_video(&self, config: &VideoConfig) -> bool { let Config::Video(current) = &self.config else { return false; @@ -273,14 +276,15 @@ impl Rendition { self.bitrate().unwrap_or(default_bandwidth(self.kind)) } - /// Take the advertised bitrate from a catalog update that - /// [`matches`](Self::matches_video) this rendition. + /// Take the advertised bitrate and framerate from a catalog update that + /// [`matches`](Self::matches_video) this rendition (audio passes no framerate). /// /// The publisher's estimator republishes the catalog whenever its measured bitrate moves, so /// this is the common update by far: rebuilding the rendition for it would reset the playlist /// window, the cached init segment, and `EXT-X-MEDIA-SEQUENCE` several times a minute. - pub(crate) fn refresh(&self, bitrate: Option) { + pub(crate) fn refresh(&self, bitrate: Option, framerate: Option) { *self.bitrate.write().expect("bitrate lock poisoned") = bitrate; + *self.framerate.write().expect("framerate lock poisoned") = framerate; } /// The latest catalog bitrate, preserving `None` for muxer-specific fallback behavior. @@ -288,6 +292,11 @@ impl Rendition { *self.bitrate.read().expect("bitrate lock poisoned") } + /// The latest catalog framerate. + fn framerate(&self) -> Option { + *self.framerate.read().expect("framerate lock poisoned") + } + /// Build a video rendition over the broadcast's timeline `section`, timed by the /// catalog root `clock`. /// @@ -304,6 +313,7 @@ impl Rendition { name, kind: Kind::Video, bitrate: RwLock::new(config.bitrate), + framerate: RwLock::new(config.framerate), width: config.coded_width, height: config.coded_height, codec: config.codec.to_string(), @@ -330,6 +340,7 @@ impl Rendition { name, kind: Kind::Audio, bitrate: RwLock::new(config.bitrate), + framerate: RwLock::new(None), width: None, height: None, codec: config.codec.to_string(), @@ -565,7 +576,7 @@ impl Rendition { }) .collect(); let (framerate, sample_rate, channel_count) = match &self.config { - Config::Video(config) => (config.framerate, None, None), + Config::Video(_) => (self.framerate(), None, None), Config::Audio(config) => (None, Some(config.sample_rate), Some(config.channel_count)), }; Some(mpd::Representation { @@ -611,13 +622,15 @@ impl Rendition { clock.wall_clock(pts).ok() } - fn muxer(&self) -> Result { + /// A muxer at the timescale this rendition's config chose, with the latest bitrate and + /// fallback framerate. + pub(crate) fn muxer(&self) -> Result { let bitrate = self.bitrate(); Ok(match &self.config { Config::Video(config) => { let mut config = config.clone(); config.bitrate = bitrate; - Muxer::video(&config)? + Muxer::video(&config)?.with_framerate(self.framerate()) } Config::Audio(config) => { let mut config = config.clone(); diff --git a/rs/moq-hls/src/export/renditions.rs b/rs/moq-hls/src/export/renditions.rs index 63815fed7ca..757b9657dfc 100644 --- a/rs/moq-hls/src/export/renditions.rs +++ b/rs/moq-hls/src/export/renditions.rs @@ -352,7 +352,7 @@ impl Producer { /// "Reconfigured" means the media itself changed (see [`Rendition::matches_video`]). A /// rendition whose entry only carries a revised estimate is kept as-is and just takes the /// new advertised bitrate, since the publisher republishes the catalog every time its - /// measured bitrate or jitter moves. + /// measured bitrate, jitter, or framerate moves. /// /// Renditions are only servable when the catalog advertises the broadcast's timeline (its /// root `archive` entry): without one there is nothing to render playlists from, so the @@ -405,8 +405,8 @@ impl Producer { let key = (Kind::Video, name.clone()); if let Some(rendition) = current.get(&key) { // Survived the stale pass, so it decodes the same: keep its window, its cached - // init segment and its media sequence, and just take the new advertised bitrate. - rendition.refresh(video.bitrate); + // init segment and its media sequence, and just take the new bitrate and framerate. + rendition.refresh(video.bitrate, video.framerate); continue; } let rendition = match Rendition::video(name.clone(), video, upstream, section.clone(), clock) { @@ -422,7 +422,7 @@ impl Producer { for (name, audio) in &catalog.audio.renditions { let key = (Kind::Audio, name.clone()); if let Some(rendition) = current.get(&key) { - rendition.refresh(audio.bitrate); + rendition.refresh(audio.bitrate, None); continue; } let rendition = match Rendition::audio(name.clone(), audio, upstream, section.clone(), clock) { diff --git a/rs/moq-mux/src/container/fmp4/muxer.rs b/rs/moq-mux/src/container/fmp4/muxer.rs index 373e260236a..c220b7ddb56 100644 --- a/rs/moq-mux/src/container/fmp4/muxer.rs +++ b/rs/moq-mux/src/container/fmp4/muxer.rs @@ -125,6 +125,36 @@ impl Muxer { Ok(self) } + /// Synthesize missing video sample durations at `framerate`, a newer estimate than the + /// config this muxer was built from. + /// + /// Only the fallback cadence follows it: the timescale, and so the init segment, stays the + /// one the original config chose. The cadence snaps to whole ticks at that timescale (an NTSC + /// rate is fractional ticks at 90 kHz, which would otherwise fail to mux as inexact). Ignored + /// for audio, for a missing, non-finite or non-positive rate, and for one whose frame rounds + /// to zero ticks or past `trun`'s 32-bit sample duration. + pub fn with_framerate(mut self, framerate: Option) -> Self { + if !matches!(self.kind, Kind::Video(_)) { + return self; + } + let Some(fps) = framerate.filter(|fps| fps.is_finite() && *fps > 0.0) else { + return self; + }; + let timescale = self.timescale.as_u64(); + let ticks = (timescale as f64 / fps).round(); + if !(1.0..=f64::from(u32::MAX)).contains(&ticks) { + return self; + } + // Exactly `ticks / timescale`, rounded to the nanosecond, so the fallback snaps back to + // `ticks` within the muxer's one-nanosecond tolerance. + let timescale = u128::from(timescale); + let nanos = (ticks as u128 * 1_000_000_000 + timescale / 2) / timescale; + if let Ok(nanos) = u64::try_from(nanos) { + self.default_frame = Duration::from_nanos(nanos); + } + self + } + /// The rendition's catalog container, whichever kind of track this is. fn catalog_container(&self) -> &CatalogContainer { match &self.kind { @@ -582,6 +612,61 @@ mod tests { assert_eq!(decoded[0].timestamp.as_micros(), 33_333); } + // A rendition built before the publisher's framerate estimate settled keeps its 90 kHz + // timescale, but a duration-less frame follows the newer cadence. + #[test] + fn with_framerate_updates_the_fallback_without_the_timescale() { + let muxer = video_muxer_without_framerate().with_framerate(Some(60.0)); + assert_eq!(muxer.timescale().as_u64(), 90_000); + let fragment = muxer.fragment(0, &[frame(0, true)]).unwrap(); + assert_eq!(super::super::sample_durations(&fragment), vec![Some(1_500)]); + } + + // An NTSC rate is fractional ticks at a timescale that doesn't divide it (1501.5 at 90 kHz), + // so the cadence snaps to whole ticks rather than failing the fragment as inexact. + #[test] + fn with_framerate_snaps_a_fractional_cadence_to_whole_ticks() { + for (fps, ticks) in [(60_000.0 / 1001.0, 1_502), (24_000.0 / 1001.0, 3_754)] { + let muxer = video_muxer_without_framerate().with_framerate(Some(fps)); + let fragment = muxer.fragment(0, &[frame(0, true)]).unwrap(); + assert_eq!(super::super::sample_durations(&fragment), vec![Some(ticks)], "{fps}"); + } + + // 30 kHz doesn't divide a second's nanoseconds either: 1251.25 ticks rounds to 1251. + let mut config = VideoConfig::new(VideoCodec::VP8); + config.framerate = Some(30.0); + let muxer = Muxer::video(&config).unwrap().with_framerate(Some(24_000.0 / 1001.0)); + assert_eq!(muxer.timescale().as_u64(), 30_000); + let fragment = muxer.fragment(0, &[frame(0, true)]).unwrap(); + assert_eq!(super::super::sample_durations(&fragment), vec![Some(1_251)]); + } + + #[test] + fn with_framerate_ignores_an_unusable_rate() { + // 90 kHz at 1e-6 fps is 9e10 ticks per frame, past trun's 32 bits; at 1e9 fps it is 0. + for fps in [ + None, + Some(0.0), + Some(-30.0), + Some(f64::NAN), + Some(f64::INFINITY), + Some(1e-6), + Some(1e9), + ] { + let muxer = video_muxer_without_framerate().with_framerate(fps); + let fragment = muxer.fragment(0, &[frame(0, true)]).unwrap(); + // The 30 fps fallback at 90 kHz. + assert_eq!(super::super::sample_durations(&fragment), vec![Some(3_000)], "{fps:?}"); + } + } + + fn video_muxer_without_framerate() -> Muxer { + let mut config = VideoConfig::new(VideoCodec::VP8); + config.coded_width = Some(320); + config.coded_height = Some(240); + Muxer::video(&config).unwrap() + } + #[test] fn with_timescale_recomputes_the_fallback_frame_duration() { let timescale = moq_net::Timescale::new(90_000).unwrap(); From d78b82160e19545ece395c5fa9718be03a3a95cc Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 19:07:45 -0700 Subject: [PATCH 127/128] fix: adapt main's new tests to dev's APIs after the merge Main's tests assumed the pre-dev shapes: announce cursors without the Live marker, Reader/Writer without a version, the removed broadcast finish, and a rewind rule that refused any frame below the live edge. Co-Authored-By: Claude Opus 5.5 --- js/net/src/ietf/subscriber.test.ts | 8 ++++---- js/net/src/lite/track.test.ts | 14 +++++++------- js/publish/src/video/encoder.test.ts | 22 ++++++++++++++++++++-- rs/moq-ffi/src/test.rs | 2 +- rs/moq-gst/src/sink/pad.rs | 17 +++++++++-------- rs/moq-tokio/tests/broadcast.rs | 2 +- 6 files changed, 42 insertions(+), 23 deletions(-) diff --git a/js/net/src/ietf/subscriber.test.ts b/js/net/src/ietf/subscriber.test.ts index 49e5654b0dd..bdaf6b07d0b 100644 --- a/js/net/src/ietf/subscriber.test.ts +++ b/js/net/src/ietf/subscriber.test.ts @@ -128,7 +128,7 @@ test("an advertisement with no path is stamped per connection", async () => { new PublishNamespace({ requestId: 0n, trackNamespace: Path.from("legacy") }), stream, ); - const hops = (await announced.next())?.route.hops ?? []; + const hops = (await nextRoute(announced))?.route.hops ?? []; expect(hops).toHaveLength(2); expect(hops[0]).not.toBe(UNKNOWN_HOP); expect(hops[1]).toBe(UNKNOWN_HOP); @@ -1125,9 +1125,9 @@ test("local readers filter hidden unsolicited namespaces from a legacy peer", as ), ); } - expect((await plain.next())?.prefix).toBe(Path.from("visible")); - expect((await opted.next())?.prefix).toBe(Path.from(".stats/node")); - expect((await opted.next())?.prefix).toBe(Path.from("visible")); + expect((await nextRoute(plain))?.prefix).toBe(Path.from("visible")); + expect((await nextRoute(opted))?.prefix).toBe(Path.from(".stats/node")); + expect((await nextRoute(opted))?.prefix).toBe(Path.from("visible")); for (const stream of streams) stream.close(); plain.close(); opted.close(); diff --git a/js/net/src/lite/track.test.ts b/js/net/src/lite/track.test.ts index f6f971d1c74..034642fc9ab 100644 --- a/js/net/src/lite/track.test.ts +++ b/js/net/src/lite/track.test.ts @@ -141,8 +141,8 @@ test("mutated TrackInfo fields emit no bytes on encode", async () => { for (const version of [Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07]) { test(`optional max age survives ${version}`, async () => { for (const maxAge of [undefined, 0, 30_000, Number.MAX_SAFE_INTEGER]) { - const encoded = await bytes((w) => new TrackInfo({ maxAge }).encode(w, version)); - const got = await TrackInfo.decode(new Reader(undefined, encoded), version); + const encoded = await bytes((w) => new TrackInfo({ maxAge }).encode(w, version), version); + const got = await TrackInfo.decode(new Reader(undefined, encoded, version), version); expect(got.maxAge).toBe( version !== Version.DRAFT_07 && maxAge === Number.MAX_SAFE_INTEGER ? undefined : maxAge, ); @@ -152,8 +152,8 @@ for (const version of [Version.DRAFT_05, Version.DRAFT_06, Version.DRAFT_07]) { for (const version of [Version.DRAFT_05, Version.DRAFT_06]) { test(`legacy unlimited value fits the old u53 reader on ${version}`, async () => { - const encoded = await bytes((w) => new TrackInfo({}).encode(w, version)); - const old = new Reader(undefined, encoded); + const encoded = await bytes((w) => new TrackInfo({}).encode(w, version), version); + const old = new Reader(undefined, encoded, version); await old.u53(); // message length await old.u8(); // priority if (version === Version.DRAFT_05) await old.bool(); @@ -170,12 +170,12 @@ for (const version of [Version.DRAFT_05, Version.DRAFT_06]) { if (version === Version.DRAFT_05) await w.bool(false); await w.u62(age); await w.u53(1000); - }); + }, version); const encoded = await bytes(async (w) => { await w.u53(payload.length); await w.write(payload); - }); - const info = await TrackInfo.decode(new Reader(undefined, encoded), version); + }, version); + const info = await TrackInfo.decode(new Reader(undefined, encoded, version), version); expect(info.maxAge).toBe(age < boundary ? Number(age) : undefined); } }); diff --git a/js/publish/src/video/encoder.test.ts b/js/publish/src/video/encoder.test.ts index 96aac84f3d9..60f7ea50102 100644 --- a/js/publish/src/video/encoder.test.ts +++ b/js/publish/src/video/encoder.test.ts @@ -758,17 +758,31 @@ test("cut forces a keyframe, coalescing requests and spacing them at least 500ms const keys: number[] = []; class RecordingVideoEncoder { state: CodecState = "unconfigured"; + #output: VideoEncoderInit["output"]; + #codec?: string; + + constructor(init: VideoEncoderInit) { + this.#output = init.output; + } static async isConfigSupported(config: VideoEncoderConfig): Promise<{ supported: boolean }> { return { supported: config.codec.startsWith("avc1") }; } - configure(): void { + configure(config: VideoEncoderConfig): void { this.state = "configured"; + this.#codec = config.codec; } + // Records the test's frames only, not the probe's. encode(frame: VideoFrame, options?: VideoEncoderEncodeOptions): void { - if (options?.keyFrame) keys.push(frame.timestamp / 1000); + if (options?.keyFrame && frame instanceof Frame) keys.push(frame.timestamp / 1000); + } + + // Only the probe flushes; report the configured codec, as Chrome does. + async flush(): Promise { + const chunk = { type: "key", timestamp: 0, byteLength: 1, copyTo: () => {} }; + this.#output(chunk as never, { decoderConfig: { codec: this.#codec } } as never); } close(): void { @@ -782,6 +796,8 @@ test("cut forces a keyframe, coalescing requests and spacing them at least 500ms value: RecordingVideoEncoder, writable: true, }); + const videoFrame = Object.getOwnPropertyDescriptor(globalThis, "VideoFrame"); + Object.defineProperty(globalThis, "VideoFrame", { configurable: true, value: FakeVideoFrame, writable: true }); class Frame { readonly timestamp: number; @@ -852,5 +868,7 @@ test("cut forces a keyframe, coalescing requests and spacing them at least 500ms track.close(); if (original) Object.defineProperty(globalThis, "VideoEncoder", original); else Reflect.deleteProperty(globalThis, "VideoEncoder"); + if (videoFrame) Object.defineProperty(globalThis, "VideoFrame", videoFrame); + else Reflect.deleteProperty(globalThis, "VideoFrame"); } }); diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 39ac674b845..c0f5ee44be8 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -581,7 +581,7 @@ async fn raw_audio_codec_default_frame() { }; assert!(message.contains("no aac audio encoder"), "{message}"); - broadcast.finish().unwrap(); + broadcast.close().unwrap(); } #[tokio::test] diff --git a/rs/moq-gst/src/sink/pad.rs b/rs/moq-gst/src/sink/pad.rs index 78ed3080882..b606283142b 100644 --- a/rs/moq-gst/src/sink/pad.rs +++ b/rs/moq-gst/src/sink/pad.rs @@ -1779,16 +1779,17 @@ mod tests { pad.push_buffer(data, Some(gst::ClockTime::from_mseconds(pts)), None, None, now) .unwrap() }; - assert_eq!(push(&mut pad, h264_keyframe_au(), 0), PushOutcome::Published); - assert_eq!(push(&mut pad, delta.clone(), 33), PushOutcome::Published); - assert_eq!(push(&mut pad, h264_keyframe_au(), 100), PushOutcome::Published); - assert_eq!(push(&mut pad, delta.clone(), 133), PushOutcome::Published); + assert_eq!(push(&mut pad, h264_keyframe_au(), 1000), PushOutcome::Published); + assert_eq!(push(&mut pad, delta.clone(), 1033), PushOutcome::Published); + assert_eq!(push(&mut pad, h264_keyframe_au(), 1100), PushOutcome::Published); + assert_eq!(push(&mut pad, delta.clone(), 1133), PushOutcome::Published); + // Below the previous group's start, so not a reordered frame the producer tolerates. assert_eq!(push(&mut pad, rewind, 16), PushOutcome::Dropped); assert!(!pad.is_failed()); - assert_eq!(push(&mut pad, delta.clone(), 166), PushOutcome::Dropped); - assert_eq!(push(&mut pad, h264_keyframe_au(), 66), PushOutcome::Dropped); - assert_eq!(push(&mut pad, h264_keyframe_au(), 200), PushOutcome::Published); - assert_eq!(push(&mut pad, delta.clone(), 233), PushOutcome::Published); + assert_eq!(push(&mut pad, delta.clone(), 1166), PushOutcome::Dropped); + assert_eq!(push(&mut pad, h264_keyframe_au(), 1066), PushOutcome::Dropped); + assert_eq!(push(&mut pad, h264_keyframe_au(), 1200), PushOutcome::Published); + assert_eq!(push(&mut pad, delta.clone(), 1233), PushOutcome::Published); } } diff --git a/rs/moq-tokio/tests/broadcast.rs b/rs/moq-tokio/tests/broadcast.rs index 90d44359da2..28148e95756 100644 --- a/rs/moq-tokio/tests/broadcast.rs +++ b/rs/moq-tokio/tests/broadcast.rs @@ -432,7 +432,7 @@ async fn transport_fetch_roundtrip(version: &str, served: bool) { .expect("client connect timed out") .expect("client connect failed"); - tokio::time::timeout(TIMEOUT, announcements.next()) + tokio::time::timeout(TIMEOUT, next_update(&mut announcements)) .await .expect("announce timed out") .expect("origin closed"); From 70927aa67918396a3e1028717d7f1063bf412605 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 30 Sep 2026 19:35:00 -0700 Subject: [PATCH 128/128] fix(net): take a group FETCH's retention from FETCH_OK FETCH_OK carries MAX_CACHE_DURATION where SUBSCRIBE_OK does (the draft-14/15 parameter, the Track Properties block from draft-16), so a track a relay only fetches gets its publisher's window instead of no limit. Also points the timestamp quests at moq-flate and @moq/flate, which absorbed moq-binary on dev. Co-Authored-By: Claude Opus 5.5 --- doc/concept/moq-lite.md | 3 +- quest/m1/README.md | 2 +- quest/m1/data-consumer-timestamps.md | 6 +-- quest/m1/js-publish-timestamp.md | 4 +- quest/m1/publish-timestamp.md | 17 ++++--- rs/moq-net/src/ietf/fetch.rs | 70 ++++++++++++++++++++++++-- rs/moq-net/src/ietf/publisher.rs | 1 + rs/moq-net/src/ietf/subscriber.rs | 74 +++++++++++++++++++++++++++- 8 files changed, 156 insertions(+), 21 deletions(-) diff --git a/doc/concept/moq-lite.md b/doc/concept/moq-lite.md index 624a52ba201..6d70ac61376 100644 --- a/doc/concept/moq-lite.md +++ b/doc/concept/moq-lite.md @@ -273,7 +273,8 @@ substituting a local default. Media tracks explicitly use 30 seconds so a segmented egress can still find its segments. IETF carries this value as MAX\_CACHE\_DURATION, received on every supported draft -and sent from draft 17 onward. Drafts 14–16 remain receive-only for compatibility +and sent from draft 17 onward. A relay reads it from FETCH\_OK as well as SUBSCRIBE\_OK, so a track it +only fetches still learns its window. Drafts 14–16 remain receive-only for compatibility with older implementations. This is an approximate mapping: IETF measures wall time, while max age uses media timestamps and always keeps the newest group. EXPIRES describes subscription lifetime and does not set retention. diff --git a/quest/m1/README.md b/quest/m1/README.md index ed4759584bf..dbd3d4780ff 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -70,7 +70,7 @@ QUIC studies there on that rule. - [Data track clock](/quest/m1/data-track-clock.md) - JSON and binary data tracks stamp on the catalog's clock at write time, matching the media's anchored clock - [Go and Dart doc samples](/quest/m1/doc-samples-go-dart.md) - Go and Dart doc samples compile against their wrappers - [Publishing requires a timestamp](/quest/m1/publish-timestamp.md) - every Rust and binding publish API takes a timestamp; nothing fills in now for the caller -- [JS publishing requires a timestamp](/quest/m1/js-publish-timestamp.md) - the same in @moq/json, @moq/binary, and @moq/net +- [JS publishing requires a timestamp](/quest/m1/js-publish-timestamp.md) - the same in @moq/json, @moq/flate, and @moq/net - [Plan: untimed peer objects](/quest/m1/plan-untimed-objects.md) - decide what a frame's timestamp is when a moq-transport or pre-lite-05 peer sends none - [Data consumer timestamps](/quest/m1/data-consumer-timestamps.md) - json and binary consumers return each value's timestamp, in Rust and every binding - [Nested data configs](/quest/m1/data-config-nesting.md) - docs nest `BinaryConfig`/`JsonConfig` in an application section instead of flattening it diff --git a/quest/m1/data-consumer-timestamps.md b/quest/m1/data-consumer-timestamps.md index 98fcb1dc863..3ac4aebdbe3 100644 --- a/quest/m1/data-consumer-timestamps.md +++ b/quest/m1/data-consumer-timestamps.md @@ -4,7 +4,7 @@ A JSON or binary data consumer returns each value with its frame's timestamp, so an application can carry data onto another track, or sync it with video, -at the exact time it was published. Covers moq-json, moq-binary, the moq-mux +at the exact time it was published. Covers moq-json, moq-flate, the moq-mux wrappers, moq-ffi, and every binding wrapper. ## Plan @@ -15,7 +15,7 @@ sync with video. Every `moq_net::Frame` has a timestamp, but the consumers decode only `frame.payload` and drop it: `moq_mux::{json,binary}::Consumer::next` and the -moq-json and moq-binary snapshot and stream consumers they wrap. A snapshot +moq-json and moq-flate snapshot and stream consumers they wrap. A snapshot consumer returns the timestamp of the frame it decoded last. Decided: `next()` and `poll_next()` return `Timed`, the type the producers @@ -26,7 +26,7 @@ timestamp is the frame's media timestamp on the track's timescale. whether a peer can deliver a frame without one; if it can, `at` becomes an `Option` here, so this waits for it and breaks once. -moq-ffi's json/binary consumers return the timestamp too, and the py, swift, +moq-ffi's json/flate consumers return the timestamp too, and the py, swift, kt, go, and dart wrappers and `doc/lib/*` follow. JS readers stay with [Data sync in watch](/quest/m3/watch-data-sync.md). diff --git a/quest/m1/js-publish-timestamp.md b/quest/m1/js-publish-timestamp.md index 02549b2db61..40fbc836a1b 100644 --- a/quest/m1/js-publish-timestamp.md +++ b/quest/m1/js-publish-timestamp.md @@ -2,13 +2,13 @@ ## Goal -`@moq/json`, `@moq/binary`, and `@moq/net` publish APIs take a timestamp and +`@moq/json`, `@moq/flate`, and `@moq/net` publish APIs take a timestamp and never fill in `Timestamp.now()` for the caller, mirroring [Publishing requires a timestamp](/quest/m1/publish-timestamp.md). ## Plan -Today the json and binary snapshot and stream producers default +Today the json and flate snapshot and stream producers default `at = Timestamp.now()`, the json window producer always uses now, and js/net's `writeString`, `writeJson`, and `writeBool` stamp now. Make the timestamp a required argument on each, with the same shape as Rust's `Timed`. Callers in diff --git a/quest/m1/publish-timestamp.md b/quest/m1/publish-timestamp.md index edce12e6a48..0c4aa6b8b09 100644 --- a/quest/m1/publish-timestamp.md +++ b/quest/m1/publish-timestamp.md @@ -5,7 +5,7 @@ Every publish API takes a timestamp, and nothing below it invents one. A frame's timestamp is the publisher's statement of when the content happened. A library never fills in "now" on the caller's behalf. Covers moq-net, -moq-json, moq-binary, moq-mux, moq-ffi, and every binding wrapper (Python, +moq-json, moq-flate, moq-mux, moq-ffi, and every binding wrapper (Python, Swift, Kotlin, Go, Dart). Not libmoq, which the [Generated C bindings](/quest/m1/c/README.md) replace. @@ -13,15 +13,15 @@ Swift, Kotlin, Go, Dart). Not libmoq, which the Decided (2026-09-30): the wire timestamp stays required, so the publish side must be too. Today `Timed.at: None` means "stamp when written": moq-json and -moq-binary fill `Timestamp::now()` (moq-net's clock, not the broadcast's), and +moq-flate fill `Timestamp::now()` (moq-net's clock, not the broadcast's), and moq-mux's `Clock::stamp` fills the broadcast clock's `now()`. The FFI raw `MoqFrame.timestamp_us` and `MoqDatagram.timestamp_us` default to 0. - `moq_net::Timed` keeps its name and gets a required `at: T`, with no - `From`. The json/binary consumers return the same type (see + `From`. The json/flate consumers return the same type (see [Data consumer timestamps](/quest/m1/data-consumer-timestamps.md)). - moq-json (snapshot, stream, and window, whose `push` always stamps now) and - moq-binary producers take `Timed<_, Timestamp>`. The moq-mux data producers + moq-flate producers take `Timed<_, Timestamp>`. The moq-mux data producers take `Timed<_, Instant>` and map it onto the broadcast clock, refusing one ahead of now (`Error::InvalidCapture`), as today; `Clock::stamp` stops filling `None`. `catalog::data::Listing::record` then always has a capture @@ -35,15 +35,16 @@ moq-mux's `Clock::stamp` fills the broadcast clock's `now()`. The FFI raw device or process clock out, as the Rust `Instant` mapping does. Either map the timestamp back through the clock inside moq-ffi or give the clock a typed timestamp moq-mux accepts; keep a raw `Timestamp` from compiling - there. The json/binary `update` and `append` take it as a required + there. The json/flate `update` and `append` take it as a required argument, and the raw frame and datagram records lose their `default = 0`. - Go (`go/wrapper/moq`) and Python (`py/moq-rs`) wrap only the JSON producers; [#4137](https://github.com/moq-dev/moq/pull/4137) added - `publish_binary_snapshot` / `publish_binary_stream` to moq-ffi without - them. Add hand-written binary wrappers there. The maintainer asked for this. + `publish_binary_snapshot` / `publish_binary_stream` (now + `publish_flate_*`) to moq-ffi without them. Add hand-written flate wrappers + there. The maintainer asked for this. Each wrapper gets a test that a past capture time is accepted and a future one refused. -- Docs: "stamped when written" in `doc/lib/rs/{moq-json,moq-binary}.md` and +- Docs: "stamped when written" in `doc/lib/rs/{moq-json,moq-flate}.md` and `rs/moq-net/src/model/timed.rs`, plus `doc/lib/{py,swift,kt,go,dart}`. What a receiver fills in when a peer sends no timestamp is out of scope: diff --git a/rs/moq-net/src/ietf/fetch.rs b/rs/moq-net/src/ietf/fetch.rs index 57e7d07fe3b..7bf6d6d3619 100644 --- a/rs/moq-net/src/ietf/fetch.rs +++ b/rs/moq-net/src/ietf/fetch.rs @@ -187,6 +187,9 @@ pub struct FetchOk { pub group_order: GroupOrder, pub end_of_track: bool, 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. + pub properties: super::Properties, } impl Message for FetchOk { const ID: u64 = 0x18; @@ -213,6 +216,8 @@ impl Message for FetchOk { self.end_of_track.encode(w, version)?; self.end_location.encode(w, version)?; encode_params!(w, version,); + // Track Properties are the final field, so nothing may follow. + self.properties.encode(w, version)?; } } Ok(()) @@ -230,12 +235,19 @@ impl Message for FetchOk { let group_order = GroupOrder::decode(buf, version)?; let end_of_track = bool::decode(buf, version)?; let end_location = Location::decode(buf, version)?; - let _params = Parameters::decode(buf, version)?; + let params = Parameters::decode(buf, version)?; + let properties = super::Properties { + max_cache_duration: params + .get_varint(super::ParameterVarInt::from(0x04)) + .map(std::time::Duration::from_millis), + ..Default::default() + }; Ok(Self { request_id, group_order, end_of_track, end_location, + properties, }) } _ => { @@ -244,11 +256,15 @@ impl Message for FetchOk { // GROUP_ORDER isn't legal here, but keep accepting it so a peer that still sends // it doesn't have its session torn down over a hint. decode_params!(buf, version, + 0x04 => max_cache_duration: Option, 0x22 => group_order: Option, ); - // FETCH_OK may declare a timescale; we don't surface it yet, and a fetched - // object without an interpretable timestamp is stamped on arrival. - let _ = super::Properties::decode(buf, version)?; + // The timescale is read but not surfaced yet: a fetched object without an + // interpretable timestamp is stamped on arrival. + let mut properties = super::Properties::decode(buf, version)?; + if version == Version::Draft15 { + properties.max_cache_duration = max_cache_duration.map(std::time::Duration::from_millis); + } let group_order = group_order.unwrap_or(GroupOrder::Descending); @@ -257,6 +273,7 @@ impl Message for FetchOk { group_order, end_of_track, end_location, + properties, }) } } @@ -594,6 +611,7 @@ mod tests { group_order: GroupOrder::Descending, end_of_track: false, end_location: Location { group: 5, object: 3 }, + properties: Default::default(), }; let encoded = encode_message(&msg, Version::Draft14); @@ -653,6 +671,7 @@ mod tests { group_order: GroupOrder::Descending, end_of_track: false, end_location: Location { group: 5, object: 3 }, + properties: Default::default(), }; let encoded = encode_message(&msg, Version::Draft15); @@ -670,6 +689,7 @@ mod tests { group_order: GroupOrder::Descending, end_of_track: false, end_location: Location { group: 5, object: 3 }, + properties: Default::default(), }; let encoded = encode_message(&msg, Version::Draft16); @@ -687,6 +707,7 @@ mod tests { group_order: GroupOrder::Descending, end_of_track: false, end_location: Location { group: 5, object: 3 }, + properties: Default::default(), }; let encoded = encode_message(&msg, Version::Draft17); @@ -725,6 +746,7 @@ mod tests { group_order: GroupOrder::Descending, end_of_track: false, end_location: Location { group: 5, object: 3 }, + properties: Default::default(), }; let encoded = encode_message(&msg, Version::Draft18); @@ -745,6 +767,7 @@ mod tests { group_order: GroupOrder::Descending, end_of_track: false, end_location: Location { group: 5, object: 3 }, + properties: Default::default(), }; #[rustfmt::skip] @@ -867,3 +890,42 @@ mod object_tests { assert!(FetchObject::decode(&mut bytes, VERSION).is_err()); } } + +#[cfg(test)] +mod cache_duration_tests { + use super::*; + use std::time::Duration; + + /// FETCH_OK carries MAX_CACHE_DURATION where SUBSCRIBE_OK does, so a track fetched with no + /// subscription still learns its retention window. + #[test] + fn max_cache_duration_is_read_in_each_drafts_field() { + for version in [ + Version::Draft14, + Version::Draft15, + Version::Draft16, + Version::Draft17, + Version::Draft18, + Version::Draft19, + Version::Draft20, + Version::Draft21, + Version::Draft22, + ] { + for age in [0u64, 30_000] { + let mut payload = match version { + Version::Draft14 => vec![0, 1, 0, 0, 0, 1, 4], + Version::Draft15 => vec![0, 0, 0, 0, 1, 4], + Version::Draft16 => vec![0, 0, 0, 0, 0, 4], + _ => vec![0, 0, 0, 0, 4], + }; + age.encode(&mut payload, version).unwrap(); + let got = FetchOk::decode_msg(&mut payload.as_slice(), version).unwrap(); + assert_eq!( + got.properties.max_cache_duration, + Some(Duration::from_millis(age)), + "{version}" + ); + } + } + } +} diff --git a/rs/moq-net/src/ietf/publisher.rs b/rs/moq-net/src/ietf/publisher.rs index e0664917404..34b24f39c97 100644 --- a/rs/moq-net/src/ietf/publisher.rs +++ b/rs/moq-net/src/ietf/publisher.rs @@ -1291,6 +1291,7 @@ where }, end_of_track, end_location, + properties: Default::default(), }) .await?; diff --git a/rs/moq-net/src/ietf/subscriber.rs b/rs/moq-net/src/ietf/subscriber.rs index e77be6f2e5a..6165ea47a5f 100644 --- a/rs/moq-net/src/ietf/subscriber.rs +++ b/rs/moq-net/src/ietf/subscriber.rs @@ -3145,8 +3145,11 @@ where let end = (end.group == sequence).then_some(end.object); // Only a track nothing has subscribed to yet takes this info, as SUBSCRIBE_OK would - // have set it. - let info = track::Info::default().with_timescale(Timescale::MICRO); + // have set it. FETCH_OK carries the same Track Properties, so the retention window + // comes from it. + let info = track::Info::default() + .with_timescale(Timescale::MICRO) + .with_max_age(ok.properties.max_cache_duration); let mut producer = match request.accept(info) { Ok(producer) => producer, // Already served by a concurrent fetch, or the track closed. @@ -7532,6 +7535,7 @@ mod joining_fetch_tests { group_order: GroupOrder::Ascending, end_of_track: false, end_location: ietf::Location { group: 4, object: 2 }, + properties: Default::default(), }, version, ) @@ -7801,6 +7805,7 @@ mod joining_fetch_tests { group: GROUP + 1, object: 0, }, + properties: Default::default(), }, VERSION, ); @@ -7840,6 +7845,70 @@ mod joining_fetch_tests { assert!(fetch.await.is_err(), "the accepted group was aborted"); } + /// A group FETCH for a track nothing subscribed to takes its retention window from + /// FETCH_OK's properties, as a subscription would from SUBSCRIBE_OK's. + #[tokio::test(start_paused = true)] + async fn a_group_fetch_takes_fetch_ok_max_age() { + const GROUP: u64 = 4; + const MAX_AGE: Duration = Duration::from_secs(12); + + for version in [Version::Draft17, Version::Draft19] { + let ok = message_bytes( + ietf::FetchOk::ID, + &ietf::FetchOk { + request_id: None, + group_order: GroupOrder::Ascending, + end_of_track: false, + end_location: ietf::Location { + group: GROUP + 1, + object: 0, + }, + properties: ietf::Properties { + max_cache_duration: Some(MAX_AGE), + ..Default::default() + }, + }, + version, + ); + + let session = ScriptedSession::per_stream_reset(vec![ok]); + let (tasks, _task_set) = crate::util::TaskSet::new(); + let subscriber = Subscriber::new( + crate::time::Clock::tokio(), + session.clone(), + crate::origin::Config::new(crate::Hop::new(1).unwrap()).produce(), + Control::new(None, false), + None, + peer::PeerSetup::default(), + crate::Hop::new(1).unwrap(), + None, + version, + tasks, + Default::default(), + ); + + // A track the publisher has not accepted, so the fetch supplies its info. + let broadcast = crate::broadcast::Info::new().produce(); + let reserved = broadcast.reserve_track("video").unwrap(); + let dynamic = reserved.dynamic(); + let track = broadcast.consume().track("video").unwrap(); + let mut fetch = std::pin::pin!(track.fetch_group(GROUP, None)); + assert!(futures::poll!(fetch.as_mut()).is_pending()); + let request = dynamic.requested_group().await.expect("no group requested"); + + subscriber + .clone() + .run_group_fetch(Path::new("broadcast").to_owned(), "video".into(), request, None) + .await; + + let info = tokio::time::timeout(Duration::from_secs(1), track.query()) + .await + .expect("the fetch installed the track info") + .expect("info"); + assert_eq!(info.max_age, Some(MAX_AGE), "{version}"); + } + } + /// A cache miss for a group's tail asks upstream from the frame the reader wants and /// numbers what arrives from there, so a publisher that evicted the prefix can answer. #[tokio::test(start_paused = true)] @@ -7858,6 +7927,7 @@ mod joining_fetch_tests { group: GROUP + 1, object: 0, }, + properties: Default::default(), }, VERSION, );