From 242914d014d155bb1c6658d9c01162271645cb91 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Fri, 23 Oct 2026 00:39:53 -0700 Subject: [PATCH 1/6] chore(quest): claim quest/m1/audit-simplify.md Quest-Claim: 2c1a07c29f5cb1eb From 5c0c9a3288e6681b8f1455b76631716c0e388480 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Fri, 23 Oct 2026 00:47:35 -0700 Subject: [PATCH 2/6] docs(mux): drop a removed method's doc left on the importers' cut Nine importers kept the first two lines of a deleted measurement method's doc above `cut` (and AAC's `advance`), so rustdoc showed them as part of the wrong method. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01EeyiEy5FWz3z44DYZVo7vU --- rs/moq-mux/src/codec/aac/import.rs | 2 -- rs/moq-mux/src/codec/av1/import.rs | 2 -- rs/moq-mux/src/codec/flac/import.rs | 2 -- rs/moq-mux/src/codec/h265/import.rs | 2 -- rs/moq-mux/src/codec/legacy.rs | 2 -- rs/moq-mux/src/codec/mp3.rs | 2 -- rs/moq-mux/src/codec/opus/import.rs | 2 -- rs/moq-mux/src/codec/vp8/import.rs | 2 -- rs/moq-mux/src/codec/vp9/import.rs | 2 -- 9 files changed, 18 deletions(-) diff --git a/rs/moq-mux/src/codec/aac/import.rs b/rs/moq-mux/src/codec/aac/import.rs index 78cfd5cffb6..e844c2c4914 100644 --- a/rs/moq-mux/src/codec/aac/import.rs +++ b/rs/moq-mux/src/codec/aac/import.rs @@ -66,8 +66,6 @@ impl Import { self.track.abort(err); } - /// Publish what the track measured (bitrate, jitter) into the catalog rendition, filling only - /// the fields its config didn't supply. /// Record the media duration emitted together by the TS importer. pub(crate) fn burst(&mut self, duration: std::time::Duration) -> crate::Result<()> { self.track.burst(duration) diff --git a/rs/moq-mux/src/codec/av1/import.rs b/rs/moq-mux/src/codec/av1/import.rs index 324e33e9a32..5fb4815c315 100644 --- a/rs/moq-mux/src/codec/av1/import.rs +++ b/rs/moq-mux/src/codec/av1/import.rs @@ -226,8 +226,6 @@ impl Import { self.track.abort(err); } - /// Publish what the track measured (bitrate, jitter) into the catalog rendition, filling only - /// the fields its config didn't supply. /// Cut the current group at `end` without finishing the track. pub fn cut(&mut self, end: Option) -> Result<()> { self.track.cut(end)?; diff --git a/rs/moq-mux/src/codec/flac/import.rs b/rs/moq-mux/src/codec/flac/import.rs index 19fa646ebfb..4ad69fc2b95 100644 --- a/rs/moq-mux/src/codec/flac/import.rs +++ b/rs/moq-mux/src/codec/flac/import.rs @@ -62,8 +62,6 @@ impl Import { self.track.abort(err); } - /// Publish what the track measured (bitrate, jitter) into the catalog rendition, filling only - /// the fields its config didn't supply. /// Cut the current group at `end` without finishing the track. pub fn cut(&mut self, end: Option) -> crate::Result<()> { self.track.cut(end)?; diff --git a/rs/moq-mux/src/codec/h265/import.rs b/rs/moq-mux/src/codec/h265/import.rs index 60f5256b18c..916510b5dfd 100644 --- a/rs/moq-mux/src/codec/h265/import.rs +++ b/rs/moq-mux/src/codec/h265/import.rs @@ -147,8 +147,6 @@ impl Import { self.track.abort(err); } - /// Publish what the track measured (bitrate, jitter) into the catalog rendition, filling only - /// the fields its config didn't supply. /// Cut the current group at `end` without finishing the track. pub fn cut(&mut self, end: Option) -> Result<()> { self.track.cut(end)?; diff --git a/rs/moq-mux/src/codec/legacy.rs b/rs/moq-mux/src/codec/legacy.rs index d54fc8814f5..41f291a95e1 100644 --- a/rs/moq-mux/src/codec/legacy.rs +++ b/rs/moq-mux/src/codec/legacy.rs @@ -169,8 +169,6 @@ impl Import { self.track.abort(err); } - /// Publish what the track measured (bitrate, jitter) into the catalog rendition, filling only - /// the fields its config didn't supply. /// Cut the current group at `end` without finishing the track. pub fn cut(&mut self, end: Option) -> crate::Result<()> { self.track.cut(end)?; diff --git a/rs/moq-mux/src/codec/mp3.rs b/rs/moq-mux/src/codec/mp3.rs index b5d186932e7..b77918ccf30 100644 --- a/rs/moq-mux/src/codec/mp3.rs +++ b/rs/moq-mux/src/codec/mp3.rs @@ -151,8 +151,6 @@ impl Import { self.track.abort(err); } - /// Publish what the track measured (bitrate, jitter) into the catalog rendition, filling only - /// the fields its config didn't supply. /// Cut the current group at `end` without finishing the track. pub fn cut(&mut self, end: Option) -> crate::Result<()> { self.track.cut(end)?; diff --git a/rs/moq-mux/src/codec/opus/import.rs b/rs/moq-mux/src/codec/opus/import.rs index b00c4749a57..db913304c38 100644 --- a/rs/moq-mux/src/codec/opus/import.rs +++ b/rs/moq-mux/src/codec/opus/import.rs @@ -64,8 +64,6 @@ impl Import { self.track.abort(err); } - /// Publish what the track measured (bitrate, jitter) into the catalog rendition, filling only - /// the fields its config didn't supply. /// Cut the current group at `end` without finishing the track. pub fn cut(&mut self, end: Option) -> crate::Result<()> { self.track.cut(end)?; diff --git a/rs/moq-mux/src/codec/vp8/import.rs b/rs/moq-mux/src/codec/vp8/import.rs index c3ff8fbc911..37ac32b80ff 100644 --- a/rs/moq-mux/src/codec/vp8/import.rs +++ b/rs/moq-mux/src/codec/vp8/import.rs @@ -114,8 +114,6 @@ impl Import { self.track.abort(err); } - /// Publish what the track measured (bitrate, jitter) into the catalog rendition, filling only - /// the fields its config didn't supply. /// Cut the current group at `end` without finishing the track. pub fn cut(&mut self, end: Option) -> crate::Result<()> { self.track.cut(end)?; diff --git a/rs/moq-mux/src/codec/vp9/import.rs b/rs/moq-mux/src/codec/vp9/import.rs index 2b78901e75e..a04aeada0e1 100644 --- a/rs/moq-mux/src/codec/vp9/import.rs +++ b/rs/moq-mux/src/codec/vp9/import.rs @@ -115,8 +115,6 @@ impl Import { self.track.abort(err); } - /// Publish what the track measured (bitrate, jitter) into the catalog rendition, filling only - /// the fields its config didn't supply. /// Cut the current group at `end` without finishing the track. pub fn cut(&mut self, end: Option) -> crate::Result<()> { self.track.cut(end)?; From 0fe7a38394d4e2a9b1f05c67ecc9f015d440892d Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Fri, 23 Oct 2026 00:53:09 -0700 Subject: [PATCH 3/6] refactor(mux): dispatch the import facades' codec arms once `import::Track` and `TrackStream` repeated an eleven- (or three-) arm match in every forwarding method. A local macro in the style of fMP4's `media!` now expands the arms, and `reset_split` holds the splitter reset that `discontinuity` and `seek` share. Behavior is unchanged. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01EeyiEy5FWz3z44DYZVo7vU --- rs/moq-mux/src/import/track.rs | 295 +++++++++------------------------ 1 file changed, 78 insertions(+), 217 deletions(-) diff --git a/rs/moq-mux/src/import/track.rs b/rs/moq-mux/src/import/track.rs index 582d4275fa1..7feb51a728b 100644 --- a/rs/moq-mux/src/import/track.rs +++ b/rs/moq-mux/src/import/track.rs @@ -171,6 +171,23 @@ enum TrackKind { Flac(crate::codec::flac::Import), } +/// Forward a call to whichever codec importer a [`Track`] holds. +macro_rules! import { + ($kind:expr, $import:ident => $body:expr) => { + match $kind { + TrackKind::Avc3 { $import, .. } | TrackKind::Avc1 { $import, .. } => $body, + TrackKind::Hev1 { $import, .. } | TrackKind::Hvc1 { $import, .. } => $body, + TrackKind::Av01 { $import, .. } => $body, + TrackKind::Vp8($import) => $body, + TrackKind::Vp9($import) => $body, + TrackKind::Aac($import) => $body, + TrackKind::Opus($import) => $body, + TrackKind::Mp3($import) => $body, + TrackKind::Flac($import) => $body, + } + }; +} + /// A single-codec importer for whole frames. /// /// Use this when the caller already has whole frames (the typical case for files @@ -406,56 +423,18 @@ impl Track { /// Record a locally encoded frame's transport handoff. Call this only for an original /// encoder; file, pipe, and network imports must leave the clock out of the estimate. pub fn flush(&mut self, timestamp: moq_net::Timestamp, now: moq_clock::Instant) -> Result<()> { - match self.kind { - TrackKind::Avc3 { ref mut import, .. } | TrackKind::Avc1 { ref mut import, .. } => { - import.flush(timestamp, now) - } - TrackKind::Hev1 { ref mut import, .. } | TrackKind::Hvc1 { ref mut import, .. } => { - import.flush(timestamp, now) - } - TrackKind::Av01 { ref mut import, .. } => import.flush(timestamp, now), - TrackKind::Vp8(ref mut import) => import.flush(timestamp, now), - TrackKind::Vp9(ref mut import) => import.flush(timestamp, now), - TrackKind::Aac(ref mut import) => import.flush(timestamp, now), - TrackKind::Opus(ref mut import) => import.flush(timestamp, now), - TrackKind::Mp3(ref mut import) => import.flush(timestamp, now), - TrackKind::Flac(ref mut import) => import.flush(timestamp, now), - } + import!(&mut self.kind, import => import.flush(timestamp, now)) } /// Finish the importer, flushing any buffered data. pub fn finish(&mut self) -> Result<()> { - match self.kind { - TrackKind::Avc3 { ref mut import, .. } => import.finish(), - TrackKind::Avc1 { ref mut import, .. } => import.finish(), - TrackKind::Hev1 { ref mut import, .. } => import.finish(), - TrackKind::Hvc1 { ref mut import, .. } => import.finish(), - TrackKind::Av01 { ref mut import, .. } => import.finish(), - TrackKind::Vp8(ref mut import) => import.finish(), - TrackKind::Vp9(ref mut import) => import.finish(), - TrackKind::Aac(ref mut import) => import.finish(), - TrackKind::Opus(ref mut import) => import.finish(), - TrackKind::Mp3(ref mut import) => import.finish(), - TrackKind::Flac(ref mut import) => import.finish(), - } + import!(&mut self.kind, import => import.finish()) } /// Abort the track with `err` instead of finishing it cleanly, so subscribers /// see the real cause rather than [`moq_net::Error::Dropped`]. Consumes the importer. pub fn abort(self, err: moq_net::Error) { - match self.kind { - TrackKind::Avc3 { import, .. } => import.abort(err), - TrackKind::Avc1 { import, .. } => import.abort(err), - TrackKind::Hev1 { import, .. } => import.abort(err), - TrackKind::Hvc1 { import, .. } => import.abort(err), - TrackKind::Av01 { import, .. } => import.abort(err), - TrackKind::Vp8(import) => import.abort(err), - TrackKind::Vp9(import) => import.abort(err), - TrackKind::Aac(import) => import.abort(err), - TrackKind::Opus(import) => import.abort(err), - TrackKind::Mp3(import) => import.abort(err), - TrackKind::Flac(import) => import.abort(err), - } + import!(self.kind, import => import.abort(err)) } /// Cut the current group at `end` without finishing the track. @@ -464,19 +443,7 @@ impl Track { /// per packet (the lowest latency), or at a segment cadence to align with video. pub fn cut(&mut self, end: Option) -> Result<()> { self.group_start = None; - match self.kind { - TrackKind::Avc3 { ref mut import, .. } => import.cut(end), - TrackKind::Avc1 { ref mut import, .. } => import.cut(end), - TrackKind::Hev1 { ref mut import, .. } => import.cut(end), - TrackKind::Hvc1 { ref mut import, .. } => import.cut(end), - TrackKind::Av01 { ref mut import, .. } => import.cut(end), - TrackKind::Vp8(ref mut import) => import.cut(end), - TrackKind::Vp9(ref mut import) => import.cut(end), - TrackKind::Aac(ref mut import) => import.cut(end), - TrackKind::Opus(ref mut import) => import.cut(end), - TrackKind::Mp3(ref mut import) => import.cut(end), - TrackKind::Flac(ref mut import) => import.cut(end), - } + import!(&mut self.kind, import => import.cut(end)) } /// Mark a timeline break, clearing partial frames and restarting handoff measurement. @@ -484,92 +451,38 @@ impl Track { /// Publishes a marker without lowering advertised values; resumed timestamps must continue forward. pub fn discontinuity(&mut self) -> Result<()> { self.group_start = None; - match self.kind { - TrackKind::Avc3 { - ref mut split, - ref mut import, - } => { - split.reset(); - import.discontinuity() - } - TrackKind::Avc1 { ref mut import, .. } => import.discontinuity(), - TrackKind::Hev1 { - ref mut split, - ref mut import, - } => { - split.reset(); - import.discontinuity() - } - TrackKind::Hvc1 { ref mut import, .. } => import.discontinuity(), - TrackKind::Av01 { - ref mut split, - ref mut import, - } => { - split.reset(); - import.discontinuity() - } - TrackKind::Vp8(ref mut import) => import.discontinuity(), - TrackKind::Vp9(ref mut import) => import.discontinuity(), - TrackKind::Aac(ref mut import) => import.discontinuity(), - TrackKind::Opus(ref mut import) => import.discontinuity(), - TrackKind::Mp3(ref mut import) => import.discontinuity(), - TrackKind::Flac(ref mut import) => import.discontinuity(), - } + self.reset_split(); + import!(&mut self.kind, import => import.discontinuity()) } /// Close the current group and open the next one at `sequence`. pub fn seek(&mut self, sequence: u64) -> Result<()> { self.group_start = None; - match self.kind { - TrackKind::Avc3 { - ref mut split, - ref mut import, - } => { - split.reset(); - import.seek(sequence) - } - TrackKind::Avc1 { ref mut import, .. } => import.seek(sequence), - TrackKind::Hev1 { - ref mut split, - ref mut import, - } => { - split.reset(); - import.seek(sequence) - } - TrackKind::Hvc1 { ref mut import, .. } => import.seek(sequence), - TrackKind::Av01 { - ref mut split, - ref mut import, - } => { - split.reset(); - import.seek(sequence) - } - TrackKind::Vp8(ref mut import) => import.seek(sequence), - TrackKind::Vp9(ref mut import) => import.seek(sequence), - TrackKind::Aac(ref mut import) => import.seek(sequence), - TrackKind::Opus(ref mut import) => import.seek(sequence), - TrackKind::Mp3(ref mut import) => import.seek(sequence), - TrackKind::Flac(ref mut import) => import.seek(sequence), + self.reset_split(); + import!(&mut self.kind, import => import.seek(sequence)) + } + + /// Drop the partial access unit of a format split from a byte stream. + fn reset_split(&mut self) { + match &mut self.kind { + TrackKind::Avc3 { split, .. } => split.reset(), + TrackKind::Hev1 { split, .. } => split.reset(), + TrackKind::Av01 { split, .. } => split.reset(), + TrackKind::Avc1 { .. } + | TrackKind::Hvc1 { .. } + | TrackKind::Vp8(_) + | TrackKind::Vp9(_) + | TrackKind::Aac(_) + | TrackKind::Opus(_) + | TrackKind::Mp3(_) + | TrackKind::Flac(_) => {} } } /// A watch-only handle to the track's subscriber demand. pub fn demand(&self) -> moq_net::track::Demand { - match self.kind { - TrackKind::Avc3 { ref import, .. } => import.demand(), - TrackKind::Avc1 { ref import, .. } => import.demand(), - TrackKind::Hev1 { ref import, .. } => import.demand(), - TrackKind::Hvc1 { ref import, .. } => import.demand(), - TrackKind::Av01 { ref import, .. } => import.demand(), - TrackKind::Vp8(ref import) => import.demand(), - TrackKind::Vp9(ref import) => import.demand(), - TrackKind::Aac(ref import) => import.demand(), - TrackKind::Opus(ref import) => import.demand(), - TrackKind::Mp3(ref import) => import.demand(), - TrackKind::Flac(ref import) => import.demand(), - } + import!(&self.kind, import => import.demand()) } - /// The name of the track this importer publishes. pub fn name(&self) -> String { self.demand().name().to_string() @@ -617,6 +530,26 @@ enum TrackStreamKind { }, } +/// Forward a call to the splitter and importer a [`TrackStream`] holds. +macro_rules! stream { + ($kind:expr, $split:pat, $import:pat => $body:expr) => { + match $kind { + TrackStreamKind::Avc3 { + split: $split, + import: $import, + } => $body, + TrackStreamKind::Hev1 { + split: $split, + import: $import, + } => $body, + TrackStreamKind::Av01 { + split: $split, + import: $import, + } => $body, + } + }; +} + /// A single-codec importer for a raw byte stream with unknown frame boundaries. /// /// Use this when the caller does not know the frame boundaries (piped Annex-B @@ -711,116 +644,44 @@ impl TrackStream { /// Decode a chunk of the byte stream. pub fn decode(&mut self, data: &[u8]) -> Result<()> { - match self.kind { - TrackStreamKind::Avc3 { - ref mut split, - ref mut import, - } => { - let frames = split.decode(data, None)?; - import.decode(frames) - } - TrackStreamKind::Hev1 { - ref mut split, - ref mut import, - } => { - let frames = split.decode(data, None)?; - import.decode(frames) - } - TrackStreamKind::Av01 { - ref mut split, - ref mut import, - } => { - let frames = split.decode(data, None)?; - import.decode(frames) - } - } + stream!(&mut self.kind, split, import => { + let frames = split.decode(data, None)?; + import.decode(frames) + }) } /// Finish the importer, flushing any buffered data. pub fn finish(&mut self) -> Result<()> { - match self.kind { - TrackStreamKind::Avc3 { - ref mut split, - ref mut import, - } => { - let tail = split.flush(None)?; - import.decode(tail)?; - import.finish() - } - TrackStreamKind::Hev1 { - ref mut split, - ref mut import, - } => { - let tail = split.flush(None)?; - import.decode(tail)?; - import.finish() - } - TrackStreamKind::Av01 { - ref mut split, - ref mut import, - } => { - let tail = split.flush(None)?; - import.decode(tail)?; - import.finish() - } - } + stream!(&mut self.kind, split, import => { + let tail = split.flush(None)?; + import.decode(tail)?; + import.finish() + }) } /// Abort the track with `err` instead of finishing it cleanly, so subscribers /// see the real cause rather than [`moq_net::Error::Dropped`]. Consumes the importer. pub fn abort(self, err: moq_net::Error) { - match self.kind { - TrackStreamKind::Avc3 { import, .. } => import.abort(err), - TrackStreamKind::Hev1 { import, .. } => import.abort(err), - TrackStreamKind::Av01 { import, .. } => import.abort(err), - } + stream!(self.kind, _, import => import.abort(err)) } /// Cut the current group at `end` without finishing the track. pub fn cut(&mut self, end: Option) -> Result<()> { - match self.kind { - TrackStreamKind::Avc3 { ref mut import, .. } => import.cut(end), - TrackStreamKind::Hev1 { ref mut import, .. } => import.cut(end), - TrackStreamKind::Av01 { ref mut import, .. } => import.cut(end), - } + stream!(&mut self.kind, _, import => import.cut(end)) } /// Close the current group and open the next one at `sequence`. pub fn seek(&mut self, sequence: u64) -> Result<()> { - match self.kind { - TrackStreamKind::Avc3 { - ref mut split, - ref mut import, - } => { - split.reset(); - import.seek(sequence) - } - TrackStreamKind::Hev1 { - ref mut split, - ref mut import, - } => { - split.reset(); - import.seek(sequence) - } - TrackStreamKind::Av01 { - ref mut split, - ref mut import, - } => { - split.reset(); - import.seek(sequence) - } - } + stream!(&mut self.kind, split, import => { + split.reset(); + import.seek(sequence) + }) } /// A watch-only handle to the track's subscriber demand. pub fn demand(&self) -> moq_net::track::Demand { - match self.kind { - TrackStreamKind::Avc3 { ref import, .. } => import.demand(), - TrackStreamKind::Hev1 { ref import, .. } => import.demand(), - TrackStreamKind::Av01 { ref import, .. } => import.demand(), - } + stream!(&self.kind, _, import => import.demand()) } - /// The name of the track this importer publishes. pub fn name(&self) -> String { self.demand().name().to_string() From 7b814c0aaaef0375c90f64e92e02dc62b2667fe9 Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Fri, 23 Oct 2026 00:54:52 -0700 Subject: [PATCH 4/6] quest: finish the m1 simplification audit and queue the m2 run The m2 successor carries the m0 leftovers that open PRs kept busy, the importer forwarding and H.264/H.265 import duplication left for later, and settles the m0 proposals. The Go wrapper's lost handle on a cancelled call traced to the generated binding, so it gets its own quest. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01EeyiEy5FWz3z44DYZVo7vU --- quest/m1/README.md | 1 - quest/m1/audit-simplify.md | 89 -------------------------- quest/m2/README.md | 2 + quest/m2/audit-simplify.md | 108 ++++++++++++++++++++++++++++++++ quest/m2/go-cancelled-result.md | 38 +++++++++++ 5 files changed, 148 insertions(+), 90 deletions(-) delete mode 100644 quest/m1/audit-simplify.md create mode 100644 quest/m2/audit-simplify.md create mode 100644 quest/m2/go-cancelled-result.md diff --git a/quest/m1/README.md b/quest/m1/README.md index c8225ec763e..8ab4e14a24a 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -158,7 +158,6 @@ tracks, so per-group stats stop costing cluster announces. - [One Annex-B exporter](/quest/m1/annexb-export.md) - H.264 and H.265 Annex-B export share one private lifecycle, which also follows a rebound rendition - [One CLI duration type](/quest/m1/cli-duration.md) - moq-cli, moq-bench and moq-relay reuse moq-tokio's public `cli::Duration` instead of their own copies - [Shared watch and publish UI](/quest/m1/js-ui.md) - a new `@moq/ui` package holds the graph, buttons, and support banner that watch and publish duplicate -- [Simplification audit](/quest/m1/audit-simplify.md) - repeat the simplification audit, starting with the m0 leftovers, before the next major release - [Artifact size audit](/quest/m1/audit-size.md) - binary, FFI, WASM, and bundle growth since the m0 run is explained, fixed, or planned - [Compile time audit](/quest/m1/audit-compile-time.md) - build-time hotspots are measured against the m0 baselines and the worst are fixed or planned - [Peer count bounds](/quest/m1/peer-count-bounds.md) - namespace interests, a legacy announce list, a WebSocket upgrade, and public HTTP admission are bounded by what the peer sent or by an existing budget diff --git a/quest/m1/audit-simplify.md b/quest/m1/audit-simplify.md deleted file mode 100644 index 1df5b2b6422..00000000000 --- a/quest/m1/audit-simplify.md +++ /dev/null @@ -1,89 +0,0 @@ -# [M] Simplification audit - -## Goal - -The code and APIs that cost the most complexity for what they deliver are -simplified: duplicate mechanisms merged, layers, options, and generics with -one user collapsed, and features that don't earn their keep narrowed or -removed. The result is net simpler, even where that means less scope. - -## Plan - -Recurs once per major release (decided 2026-10-19). The PR that finishes -this run also adds the next one with the same file name at the end of the next -milestone's `Required` (m0 to m1, m1 to m2). The successor keeps the Goal -and this paragraph; the rest of its Plan is rewritten with what this run -learned: baselines, results, and what to check first. A successor placed in m2 -also lists the [release cut](/quest/m2/release/cut.md) under `Required`, so it -waits for the release in flight to ship. Only `/quest-delete` ends the -recurrence. Fixes land in the run's PR, one commit each, rather than as follow-ups. -Only a change that needs a maintainer decision (public API, scope) or is -independently landable and too large to review alongside the rest becomes a -follow-up through `/quest-plan`. - -Narrowing a feature or reshaping an API is the maintainer's call, so those -are proposals with a recommendation, filed as follow-ups. Unlike the [dead -code audit](/quest/m2/audit-dead-code.md), this targets code that is used but -overbuilt. - -### Check first - -Left from the m0 run because open work edited the same code (close-tail drain -landed in [#5762](https://github.com/moq-dev/moq/pull/5762)): - -- `ietf/session.rs` `start()` builds both halves twice across the draft arms, - and the IETF publisher/subscriber constructors drifted from lite's config - structs. -- Lite and IETF `GroupServe` share their open, flush, and FIN-settle driver. -- `ietf/adapter.rs` reimplements `kio::Queue`; keep a drop guard for the - writer. - -Maintainer proposals from m0, not yet planned, each with its recommendation: - -- Yes: a moq-video raw-frame publisher that moq-ffi and moq-c both wrap, - removing about 250 duplicated encode and bandwidth-follow lines. moq-c's - copy calls `pollster::block_on(set_bitrate)` on the C runtime while holding - the encoder lock, which may stall other moq-c tasks (unverified). -- Yes, after the publisher: move the bindings' duplicated `Background` into - moq-tokio, with a blanket `Driver for &mut D` in moq-net. -- Yes: make Python's `connect` the `Client` class, dropping a 27-parameter - forwarding signature. -- No: typealias the Swift wrapper's forwarding classes. The wrapping is - deliberate (argument labels, no `Moq` prefixes), and it would break Swift. -- Keep: Kotlin's `AnnounceConsumer.updates()` cancels on every completion - while the other flows cancel only on cancellation; its doc promises that. - -The Go wrapper's `Server.Accept` and handle-returning methods skip -`bridge.CallHandle`, which may leak an accepted handle on cancellation. This -is unverified and worth its own investigation. - -### Results (m0, 2026-10-20) - -Three PRs, all private and behavior-preserving: -[#5977](https://github.com/moq-dev/moq/pull/5977), -[#6049](https://github.com/moq-dev/moq/pull/6049), and this run's final PR. -They merged the JSON stream consumer into the byte stream consumer, one IETF -request-error writer in Rust and JS, Rust's lite version gates mirrored in -JS, one moq-c task slab with no never-`None` entries, one moq-c media consume -path, one Kotlin pull adapter, one Python async stream base, small Go -duplicates, one queue-once keyed waker in moq-net, and one armed change wait -in js/net's publishers. - -### Kept on purpose - -- Backend and playback traits have several implementations or device-free - test doubles; catalog traits erase application extension types. -- The ietf publisher's `RequestWaker` and lite's `FetchWake` stay apart from - the queue-once waker: one collects into a list and wakes an owner, the - other fills a set. -- js/net's subscriber grant checks stay hand-written: `auth_gate.ts` `Gate` - only checks publish grants, and a direction flag costs what it saves. -- The JS datagram send and receive loops: the lite and IETF error handling - and `served` bookkeeping differ, so a shared loop needs hooks. -- Dart and C++ wrappers are already thin. - -Transport adapter deduplication and compression removal have dedicated work; -avoid a second design here. Start with the items above, then the largest -modules again, and the bindings' forwarding layers. The largest moq-net -modules at the end of m0: `ietf/publisher.rs` 16,047 lines, -`model/origin.rs` 11,863, and `lite/subscriber.rs` 7,181. diff --git a/quest/m2/README.md b/quest/m2/README.md index 37c347bf711..144d531e93f 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -108,6 +108,7 @@ ranked just below deterministic TS legs, which it requires. - [Go module proxy](/quest/m2/go-module-proxy.md) - `moq.dev/moq-ffi` ships from a static GOPROXY we host, so its staticlibs stop growing git history by ~61 MiB per release - [Go per-platform lib modules](/quest/m2/go-ffi-platform-modules.md) - a Go build downloads only the host's staticlib, and `go mod vendor` works - [Go first dial failure](/quest/m2/go-first-dial-failure.md) - Go reports why a first dial fails, and the Kotlin and Dart docs name `client.failure()` correctly +- [Go cancelled results](/quest/m2/go-cancelled-result.md) - a Go call cancelled as it completes destroys the handle it produced instead of leaving it to the finalizer - [Dart on iOS](/quest/m2/dart-ios.md) - prove the shipped iOS native asset actually loads on a device, which no CI can - [Mobile completion](/quest/m2/mobile-completion.md) - verify the Swift and Kotlin bindings over Rust-owned capture - [Browser publishing paths under test](/quest/m2/publish-firefox.md) - the media harness publishes from Firefox too, covering the worker capture and video-element fallback Chromium never takes @@ -231,3 +232,4 @@ ranked just below deterministic TS legs, which it requires. - [Quest tree audit](/quest/m2/audit-quests.md) - repeat the whole-tree audit after the release ships, against the m1 baseline - [CI workflow audit](/quest/m2/audit-ci.md) - repeat the per-workflow and per-job review after the release ships, against the m1 baselines - [Performance audit](/quest/m2/audit-perf.md) - benchmarks that regressed since the m1 run are explained, fixed, or planned, and unbenched hot paths get coverage +- [Simplification audit](/quest/m2/audit-simplify.md) - repeat the simplification audit, starting with the m1 leftovers, after the release ships diff --git a/quest/m2/audit-simplify.md b/quest/m2/audit-simplify.md new file mode 100644 index 00000000000..f28cde5ea72 --- /dev/null +++ b/quest/m2/audit-simplify.md @@ -0,0 +1,108 @@ +# [M] Simplification audit + +## Goal + +The code and APIs that cost the most complexity for what they deliver are +simplified: duplicate mechanisms merged, layers, options, and generics with +one user collapsed, and features that don't earn their keep narrowed or +removed. The result is net simpler, even where that means less scope. + +## Plan + +Recurs once per major release (decided 2026-10-19). The PR that finishes +this run also adds the next one with the same file name at the end of the next +milestone's `Required` (m0 to m1, m1 to m2). The successor keeps the Goal +and this paragraph; the rest of its Plan is rewritten with what this run +learned: baselines, results, and what to check first. A successor placed in m2 +also lists the [release cut](/quest/m2/release/cut.md) under `Required`, so it +waits for the release in flight to ship. Only `/quest-delete` ends the +recurrence. Fixes land in the run's PR, one commit each, rather than as follow-ups. +Only a change that needs a maintainer decision (public API, scope) or is +independently landable and too large to review alongside the rest becomes a +follow-up through `/quest-plan`. + +Narrowing a feature or reshaping an API is the maintainer's call, so those +are proposals with a recommendation, filed as follow-ups. Unlike the [dead +code audit](/quest/m2/audit-dead-code.md), this targets code that is used but +overbuilt. + +### Check first + +The m1 run (2026-10-23) ran while about 150 PRs were open, touching every +moq-net session module, the bindings, moq-tokio, moq-relay, and moq-cli, so it +skipped those. Still open from m0, unchanged because open work kept editing +the same code: + +- `ietf/session.rs` `start()` builds both halves twice across the draft arms, + and the IETF publisher/subscriber constructors drifted from lite's config + structs. +- Lite and IETF `GroupServe` share their open, flush, and FIN-settle driver. +- `ietf/adapter.rs` reimplements `kio::Queue`; keep a drop guard for the + writer. +- Python's `connect` forwards every `Client` parameter, still about a dozen + after the [wrapper config](https://github.com/moq-dev/moq/pull/6507) nesting. + Binding `connect = Client` keeps the call signature, so it needs no + decision. Expect the wrappers' other forwarding layers to have changed too. + +New from m1: + +- The codec importers (H.264, H.265, AV1, VP8, VP9, AAC, Opus, MP3, FLAC, and + legacy) each forward `demand`, `flush`, `finish`, `abort`, `cut`, + `discontinuity`, and `seek` to their container producer. Dropping the + forwards means exposing a shared track handle, which is an API proposal. The + audio and video producers differ in their config type, so check the + handle can be one type before proposing it. +- moq-mux's H.264 and H.265 `Import` and `Split` share their shape but differ + in SEI scanning, open-GOP recovery points, and error variants. A generic + version needed enough hooks that it was left alone; recheck it if those + converge. + +Proposals from m0 are settled. The moq-video raw-frame publisher and the +shared `Background` would each have had moq-ffi as their only user once the +[generated C bindings](/quest/m1/c/README.md) retire moq-c's hand-written +copies, so both were dropped. The Go wrapper's missing `bridge.CallHandle` is +in the generated binding, not the wrapper: see +[Go cancelled results](/quest/m2/go-cancelled-result.md). + +### Results (m1, 2026-10-23) + +One PR, private and behavior-preserving: moq-mux's `import::Track` and +`TrackStream` expand their codec arms through one macro each, and nine +importers lost a deleted method's doc left on `cut`. The H.264 and H.265 +exporters were already planned as [one Annex-B exporter](/quest/m1/annexb-export.md), +ordered after the rendition rebind, so this run left them alone. Search the +quest tree before fixing a duplicate: the 2026-10-22 refactor audit filed +several. + +### Kept on purpose + +- Backend and playback traits have several implementations or device-free + test doubles; catalog traits erase application extension types. +- The ietf publisher's `RequestWaker` and lite's `FetchWake` stay apart from + the queue-once waker: one collects into a list and wakes an owner, the + other fills a set. +- js/net's subscriber grant checks stay hand-written: `auth_gate.ts` `Gate` + only checks publish grants, and a direction flag costs what it saves. +- The JS datagram send and receive loops: the lite and IETF error handling + and `served` bookkeeping differ, so a shared loop needs hooks. +- Dart and C++ wrappers are already thin. The Swift wrapper's forwarding + classes stay classes, for argument labels and unprefixed names. +- Kotlin's `AnnounceConsumer.updates()` cancels on every completion, as its + doc promises. +- The `until_wanted` loop copied into moq-audio, moq-boy, moq-video, and + moq-transcode is one line over `Demand::wanted_changed`. A helper on + `Demand` would be a second way to wait for the one demand signal + [refresh](/quest/m1/refresh/README.md) chose. +- js/net's lite version gates mirror Rust's on purpose, and its per-message + IETF error classes are distinct wire messages. + +Transport adapter deduplication and compression removal have dedicated work; +avoid a second design here. Start with the items above, then the largest +modules again, and the bindings' forwarding layers. The largest moq-net +modules at the end of m1: `ietf/publisher.rs` 17,182 lines, +`ietf/subscriber.rs` 17,066, `model/origin.rs` 13,036, `lite/publisher.rs` +8,508, and `lite/subscriber.rs` 7,839. The three m0 named all grew. + +## Required + +- [Release cut](/quest/m2/release/cut.md) - wait for the release in flight to ship diff --git a/quest/m2/go-cancelled-result.md b/quest/m2/go-cancelled-result.md new file mode 100644 index 00000000000..75275972402 --- /dev/null +++ b/quest/m2/go-cancelled-result.md @@ -0,0 +1,38 @@ +# [S] Go cancelled results + +## Goal + +A Go call whose context is cancelled just as the native call completes +destroys the handle it produced right away, instead of leaving it live until +the garbage collector runs its finalizer. The case that matters is +`Server.Accept`: today the incoming session it accepted sits unanswered until +GC, and the same goes for subscriptions, fetches, resolves, and broadcast +requests the caller gave up on. + +## Plan + +Found in the m1 simplification audit (2026-10-23) and checked against the +generated binding. The cause is in `uniffiRustCallAsync`, which +`kixelated/uniffi-bindgen-go` generates. When ctx is cancelled, it cancels +the Rust future and waits for it. If the future had already completed, the +result is lifted into a Go object anyway, then dropped behind +`ctx.Err()`. The object has a finalizer, so it is reclaimed eventually but +not promptly. + +The wrapper cannot close this. `bridge.CallHandle` gives the binding a +context that never cancels, so the Rust future keeps running after the +caller leaves. For `Server.Accept` that future would take the next incoming +request, which the release then destroys: a real connection lost. + +Fix it in the generator: when the call was cancelled, run the result type's +destroyer instead of returning nothing. The generator already emits a +destroyer per type, including records and optionals that hold objects. Then +the wrapper's direct ctx calls (`Server.Accept`, `SubscribeTrack`, +`FetchGroup`, `Resolve`, `RequestBroadcast`) are correct as they are. Check +whether `bridge.CallHandle` still covers anything once the binding releases +these results itself. If the +[generator hard fork](/quest/m2/uniffi-fork.md) has landed, the change goes +there; otherwise into the current fork, with a pin bump. + +Test it with a cancelled context racing a call that completes at once, and +count live native handles rather than waiting on GC. From 57c0500690144304fb49763c478e0ca08b64309f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 23 Oct 2026 16:14:34 -0700 Subject: [PATCH 5/6] quest: scope the Go cancelled-result leak to calls without their own cancel Co-Authored-By: Claude Opus 5.5 --- quest/m2/go-cancelled-result.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/quest/m2/go-cancelled-result.md b/quest/m2/go-cancelled-result.md index 75275972402..d51bcf5f84b 100644 --- a/quest/m2/go-cancelled-result.md +++ b/quest/m2/go-cancelled-result.md @@ -19,16 +19,21 @@ result is lifted into a Go object anyway, then dropped behind `ctx.Err()`. The object has a finalizer, so it is reclaimed eventually but not promptly. -The wrapper cannot close this. `bridge.CallHandle` gives the binding a -context that never cancels, so the Rust future keeps running after the -caller leaves. For `Server.Accept` that future would take the next incoming -request, which the release then destroys: a real connection lost. +The wrapper cannot close this. `bridge.CallHandle` releases a late handle +only when the call has its own `cancel` (as `Request.Accept` does), because +it then gives the binding a context that never cancels. These calls have no +such `cancel`, so the Rust future would keep running after the caller +leaves. For `Server.Accept` that future would take the next incoming +request, which the release then destroys: a real connection lost. With a nil +`cancel`, `CallHandle` passes ctx through, so `Auth.Add` leaks the same way. Fix it in the generator: when the call was cancelled, run the result type's destroyer instead of returning nothing. The generator already emits a destroyer per type, including records and optionals that hold objects. Then the wrapper's direct ctx calls (`Server.Accept`, `SubscribeTrack`, -`FetchGroup`, `Resolve`, `RequestBroadcast`) are correct as they are. Check +`FetchGroup`, `Resolve`, `RequestBroadcast`) and `Auth.Add` are correct as +they are. A binding that destroys the result returns `ctx.Err()`, which +`run` never releases, so nothing is destroyed twice. Check whether `bridge.CallHandle` still covers anything once the binding releases these results itself. If the [generator hard fork](/quest/m2/uniffi-fork.md) has landed, the change goes From 21f8b1671c665110b83f725ab1c4b86423dd3574 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 23 Oct 2026 16:15:44 -0700 Subject: [PATCH 6/6] quest: drop the finished refresh epic's link from the m2 simplification audit Co-Authored-By: Claude Opus 5.5 --- quest/m2/audit-simplify.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/quest/m2/audit-simplify.md b/quest/m2/audit-simplify.md index f28cde5ea72..fa34b279d54 100644 --- a/quest/m2/audit-simplify.md +++ b/quest/m2/audit-simplify.md @@ -91,8 +91,7 @@ several. doc promises. - The `until_wanted` loop copied into moq-audio, moq-boy, moq-video, and moq-transcode is one line over `Demand::wanted_changed`. A helper on - `Demand` would be a second way to wait for the one demand signal - [refresh](/quest/m1/refresh/README.md) chose. + `Demand` would be a second way to wait for the one demand signal. - js/net's lite version gates mirror Rust's on purpose, and its per-message IETF error classes are distinct wire messages.