From 0fe5689eda3d4c88dc6be752ac6852fd518296e1 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 06:25:32 -0800 Subject: [PATCH 1/3] chore(quest): claim quest/m2/finish-sweep.md Quest-Claim: 643c164d506d880b From e70d9a0144b83c160b81d82c5c5aa6aeaf873cb8 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 07:06:15 -0800 Subject: [PATCH 2/3] feat!: finishing an importer or the video producer returns a Finished handle Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/src/publish.rs | 29 ++--- rs/moq-c/src/video.rs | 18 ++- rs/moq-cli/src/publish.rs | 5 +- rs/moq-ffi/src/media.rs | 37 ++---- rs/moq-ffi/src/video.rs | 5 +- rs/moq-gst/src/sink/pad.rs | 12 +- rs/moq-mux/benches/containers.rs | 27 ++-- rs/moq-mux/src/codec/aac/import.rs | 17 ++- rs/moq-mux/src/codec/av1/import.rs | 12 +- rs/moq-mux/src/codec/flac/import.rs | 12 +- rs/moq-mux/src/codec/h264/import.rs | 17 ++- rs/moq-mux/src/codec/h265/import.rs | 17 ++- rs/moq-mux/src/codec/legacy.rs | 17 ++- rs/moq-mux/src/codec/mp3.rs | 12 +- rs/moq-mux/src/codec/opus/import.rs | 19 ++- rs/moq-mux/src/codec/vp8/import.rs | 16 ++- rs/moq-mux/src/codec/vp9/import.rs | 14 ++- rs/moq-mux/src/container/ts/import.rs | 18 +-- rs/moq-mux/src/import/mod.rs | 10 +- rs/moq-mux/src/import/track.rs | 171 ++++++++++++++++++++------ rs/moq-rtsp/src/client.rs | 13 +- rs/moq-video/src/encode/mod.rs | 2 +- rs/moq-video/src/encode/producer.rs | 75 ++++++----- rs/moq-webrtc/src/codec/av1.rs | 4 +- rs/moq-webrtc/src/codec/h264.rs | 4 +- rs/moq-webrtc/src/codec/h265.rs | 4 +- rs/moq-webrtc/src/codec/mod.rs | 30 ++--- rs/moq-webrtc/src/codec/opus.rs | 4 +- rs/moq-webrtc/src/codec/vp8.rs | 2 +- rs/moq-webrtc/src/codec/vp9.rs | 2 +- rs/moq-webrtc/src/session.rs | 11 +- test/interop/clients/rust/finish.rs | 6 +- 32 files changed, 410 insertions(+), 232 deletions(-) diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index 2436e473864..cfd126a418a 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -301,15 +301,6 @@ impl Abort for Data> { } } -/// The cause a failed import ends its tracks with, so a reader sees the publisher fail rather than -/// `Dropped`. Only a moq-net error has a wire code; any other reaches readers as `Internal`. -fn cause(err: &moq_mux::Error) -> moq_net::Error { - match err { - moq_mux::Error::Moq(err) => err.clone(), - _ => moq_net::StreamError::Internal.into(), - } -} - impl std::ops::Deref for Kept { type Target = T; @@ -681,15 +672,19 @@ impl Publish { } pub fn media_finish(&mut self, media: Id) -> Result<(), Error> { - let mut track = self.media.remove(media).ok_or(Error::MediaNotFound)?; - if let Err(err) = track.finish() { - track.children.forget(Child::Media(media)); - let cause = cause(&err); - track.abort(cause); - return Err(err.into()); + let Kept { inner, children } = self.media.remove(media).ok_or(Error::MediaNotFound)?; + match inner.track.finish() { + // The broadcast keeps the finished track, so its finish still holds it. + Ok(finished) => { + children.keep(Child::Media(media), finished); + Ok(()) + } + // A failed finish already ended the track with its cause. + Err(err) => { + children.forget(Child::Media(media)); + Err(err.into()) + } } - track.keep(Child::Media(media)); - Ok(()) } /// Write a whole chunk of container bytes. diff --git a/rs/moq-c/src/video.rs b/rs/moq-c/src/video.rs index 3634e5ddbfe..628eef88b36 100644 --- a/rs/moq-c/src/video.rs +++ b/rs/moq-c/src/video.rs @@ -539,18 +539,24 @@ fn surface(_frame: &moq_video::Frame) -> *const c_void { /// anyway would leave a truncated stream indistinguishable from a complete one, /// and only the local caller would ever learn otherwise. fn finalize( - mut producer: moq_video::encode::Producer, + producer: moq_video::encode::Producer, drained: Result<(), moq_video::Error>, children: &crate::publish::Children, child: crate::publish::Child, ) -> Result<(), Error> { match drained { - Ok(()) => { - producer.finish()?; + Ok(()) => match producer.finish() { // The broadcast keeps the finished track, so its finish still holds it. - children.keep(child, producer); - Ok(()) - } + Ok(finished) => { + children.keep(child, finished); + Ok(()) + } + // A failed finish already ended the track with its cause. + Err(err) => { + children.forget(child); + Err(err.into()) + } + }, Err(err) => { children.forget(child); producer.abort(moq_net::Error::Transport(err.to_string())); diff --git a/rs/moq-cli/src/publish.rs b/rs/moq-cli/src/publish.rs index c5d42c93109..42b1efbf275 100644 --- a/rs/moq-cli/src/publish.rs +++ b/rs/moq-cli/src/publish.rs @@ -227,8 +227,7 @@ impl PublishDecoder { Self::Avc3 { mut split, mut import } => { let tail = split.flush(None)?; import.decode(tail)?; - import.finish()?; - FinishedDecoder::Avc3(import) + FinishedDecoder::Avc3(Box::new(import.finish()?)) } Self::Fmp4(d) => FinishedDecoder::Fmp4(Box::new(d.finish()?)), Self::Ts(d) => FinishedDecoder::Ts(Box::new(d.finish()?)), @@ -254,7 +253,7 @@ impl PublishDecoder { /// A [`PublishDecoder`] whose tracks finished, holding them so they stay servable. enum FinishedDecoder { - Avc3(Box), + Avc3(Box>), Fmp4(Box), Ts(Box), TsPrograms(Box), diff --git a/rs/moq-ffi/src/media.rs b/rs/moq-ffi/src/media.rs index 7eaacedcf2c..6679b41e117 100644 --- a/rs/moq-ffi/src/media.rs +++ b/rs/moq-ffi/src/media.rs @@ -1250,14 +1250,12 @@ impl MoqMediaTrackProducer { pub fn finish(&self) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let mut guard = self.inner.lock().unwrap(); - let mut media = guard.take().ok_or(MoqError::Closed)?; - if let Err(err) = media.import.finish() { - media.import.abort(cause(&err)); - return Err(MoqError::Codec { - reason: format!("finish failed: {err}"), - }); - } - self.children.keep(media); + let media = guard.take().ok_or(MoqError::Closed)?; + // A failed finish already ended the track with its cause. + let finished = media.import.finish().map_err(|err| MoqError::Codec { + reason: format!("finish failed: {err}"), + })?; + self.children.keep(finished); Ok(()) } } @@ -1389,27 +1387,16 @@ impl MoqMediaTrackStreamProducer { pub fn finish(&self) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let mut guard = self.inner.lock().unwrap(); - let mut media = guard.take().ok_or(MoqError::Closed)?; - if let Err(err) = media.import.finish() { - media.import.abort(cause(&err)); - return Err(MoqError::Codec { - reason: format!("finish failed: {err}"), - }); - } - self.children.keep(media); + let media = guard.take().ok_or(MoqError::Closed)?; + // A failed finish already ended the track with its cause. + let finished = media.import.finish().map_err(|err| MoqError::Codec { + reason: format!("finish failed: {err}"), + })?; + self.children.keep(finished); Ok(()) } } -/// The cause a failed import ends its tracks with, so a reader sees the publisher fail rather than -/// `Dropped`. Only a moq-net error has a wire code; any other reaches readers as `Internal`. -fn cause(err: &moq_mux::Error) -> moq_net::Error { - match err { - moq_mux::Error::Moq(err) => err.clone(), - _ => moq_net::StreamError::Internal.into(), - } -} - /// Reserve the named track, or a unique one named after the format. fn reserve_track( broadcast: &moq_net::broadcast::Producer, diff --git a/rs/moq-ffi/src/video.rs b/rs/moq-ffi/src/video.rs index 51026fe02bd..6c9956331ce 100644 --- a/rs/moq-ffi/src/video.rs +++ b/rs/moq-ffi/src/video.rs @@ -309,14 +309,13 @@ fn drain( /// anyway would leave a truncated stream indistinguishable from a complete one, /// and only the local caller would ever learn otherwise. fn finalize( - mut producer: moq_video::encode::Producer, + producer: moq_video::encode::Producer, drained: Result<(), moq_video::Error>, children: &crate::producer::Children, ) -> Result<(), MoqError> { match drained { Ok(()) => { - producer.finish()?; - children.keep(producer); + children.keep(producer.finish()?); Ok(()) } Err(err) => { diff --git a/rs/moq-gst/src/sink/pad.rs b/rs/moq-gst/src/sink/pad.rs index 2a8e1b03a2d..94ba2adb22f 100644 --- a/rs/moq-gst/src/sink/pad.rs +++ b/rs/moq-gst/src/sink/pad.rs @@ -98,6 +98,8 @@ impl Names { #[derive(Default)] pub(super) struct Closed { _track: Option, + /// A finished audio or video track, which no longer has a [`Sink`]. + _media: Option, /// A finished text track, which no longer has a [`Sink`]. _text: Option>, /// The catalog `_track` published in, kept open until the owner drops. @@ -986,11 +988,12 @@ impl Pad { self.names.end(track.name()); } let mut text = None; + let mut media = None; let (result, track) = match track { - Sink::Media(mut media) => ( - media.track.finish().map_err(anyhow::Error::from), - Some(Sink::Media(media)), - ), + Sink::Media(sink) => { + let result = sink.track.finish().map(|finished| media = Some(finished)); + (result.map_err(anyhow::Error::from), None) + } Sink::Text(sink) => { let result = sink.producer.finish().map(|finished| text = Some(finished)); (result.map_err(anyhow::Error::from), None) @@ -1007,6 +1010,7 @@ impl Pad { }; let closed = Closed { _track: track, + _media: media, _text: text, _catalog: Some(catalog), }; diff --git a/rs/moq-mux/benches/containers.rs b/rs/moq-mux/benches/containers.rs index f8e72f2a4fc..ffa46ee788a 100644 --- a/rs/moq-mux/benches/containers.rs +++ b/rs/moq-mux/benches/containers.rs @@ -151,12 +151,19 @@ fn import_cmaf_chunks( } struct Annexb { - _broadcast: moq_net::broadcast::Producer, + broadcast: moq_net::broadcast::Producer, catalog: moq_mux::catalog::Producer, import: h264::Import, split: h264::Split, } +/// What a finished [`Annexb`] import keeps published, returned so the timed run drops none of it. +struct Imported { + _broadcast: moq_net::broadcast::Producer, + catalog: moq_mux::catalog::Producer, + _track: moq_mux::container::Finished, +} + impl Annexb { fn new() -> Self { let mut broadcast = moq_net::broadcast::Info::new().produce(); @@ -166,29 +173,32 @@ impl Annexb { .unwrap(); let import = h264::Import::new(track, catalog.reserve(), Default::default()).unwrap(); Self { - _broadcast: broadcast, + broadcast, catalog, import, split: h264::Split::new(), } } - fn decode(&mut self, payload: &Bytes, frames: usize) { + fn decode(mut self, payload: &Bytes, frames: usize) -> Imported { for index in 0..frames { let pts = timestamp(index); let mut complete = self.split.decode(payload, pts).unwrap(); complete.extend(self.split.flush(pts).unwrap()); self.import.decode(complete).unwrap(); } - self.import.finish().unwrap(); + Imported { + _broadcast: self.broadcast, + catalog: self.catalog, + _track: self.import.finish().unwrap(), + } } } // Collect only timed import work, excluding the output validation in setup. #[inline(never)] -fn profiled_import(mut import: Annexb, payload: &Bytes, frames: usize) -> Annexb { - import.decode(payload, frames); - import +fn profiled_import(import: Annexb, payload: &Bytes, frames: usize) -> Imported { + import.decode(payload, frames) } /// `fragments` moofs whose `tracks` trafs each split their samples into `runs` one-sample runs, @@ -414,8 +424,7 @@ fn containers(c: &mut Criterion) { } assert_eq!(fragments, tracks * frames); } else { - let mut import = Annexb::new(); - import.decode(&payload, frames); + let import = Annexb::new().decode(&payload, frames); assert_eq!(import.catalog.snapshot().video.renditions.len(), 1); } assert!(!data.is_empty()); diff --git a/rs/moq-mux/src/codec/aac/import.rs b/rs/moq-mux/src/codec/aac/import.rs index 487e49dffaf..a7f5c41e200 100644 --- a/rs/moq-mux/src/codec/aac/import.rs +++ b/rs/moq-mux/src/codec/aac/import.rs @@ -54,10 +54,19 @@ impl Import { self.track.track().demand() } - /// Finish the track, flushing the current group. - pub fn finish(&mut self) -> crate::Result<()> { - self.track.end_with(None)?; - Ok(()) + /// Finish the track, flushing the current group, and return the [`Finished`](crate::container::Finished) + /// track, which keeps it and its catalog rendition published. + /// + /// A finish that fails ends the track with the cause instead, so it can't be retried. + pub fn finish( + self, + ) -> crate::Result> { + self.track.finish() + } + + /// [`finish`](Self::finish) the track in place, for an owner that keeps this importer. + pub(crate) fn end(&mut self) -> crate::Result<()> { + self.track.end_with(None) } /// Abort the track with `err` instead of finishing it cleanly, so subscribers diff --git a/rs/moq-mux/src/codec/av1/import.rs b/rs/moq-mux/src/codec/av1/import.rs index 9930a2efcc9..f41951ae60f 100644 --- a/rs/moq-mux/src/codec/av1/import.rs +++ b/rs/moq-mux/src/codec/av1/import.rs @@ -197,10 +197,14 @@ impl Import { self.track.track().demand() } - /// Finish the track, flushing the current group. - pub fn finish(&mut self) -> Result<()> { - self.track.end_with(None)?; - Ok(()) + /// Finish the track, flushing the current group, and return the [`Finished`](crate::container::Finished) + /// track, which keeps it and its catalog rendition published. + /// + /// A finish that fails ends the track with the cause instead, so it can't be retried. + pub fn finish( + self, + ) -> crate::Result> { + self.track.finish() } /// Abort the track with `err` instead of finishing it cleanly, so subscribers diff --git a/rs/moq-mux/src/codec/flac/import.rs b/rs/moq-mux/src/codec/flac/import.rs index 5a3cace0319..b1a74c7f6d7 100644 --- a/rs/moq-mux/src/codec/flac/import.rs +++ b/rs/moq-mux/src/codec/flac/import.rs @@ -45,10 +45,14 @@ impl Import { self.track.track().demand() } - /// Finish the track, flushing the current group. - pub fn finish(&mut self) -> crate::Result<()> { - self.track.end_with(None)?; - Ok(()) + /// Finish the track, flushing the current group, and return the [`Finished`](crate::container::Finished) + /// track, which keeps it and its catalog rendition published. + /// + /// A finish that fails ends the track with the cause instead, so it can't be retried. + pub fn finish( + self, + ) -> crate::Result> { + self.track.finish() } /// Abort the track with `err` instead of finishing it cleanly, so subscribers diff --git a/rs/moq-mux/src/codec/h264/import.rs b/rs/moq-mux/src/codec/h264/import.rs index f44411da656..453e8f1c828 100644 --- a/rs/moq-mux/src/codec/h264/import.rs +++ b/rs/moq-mux/src/codec/h264/import.rs @@ -131,10 +131,19 @@ impl Import { self.track.track() } - /// Finish the track, flushing any buffered data. - pub fn finish(&mut self) -> Result<()> { - self.track.end_with(None)?; - Ok(()) + /// Finish the track, flushing the current group, and return the [`Finished`](crate::container::Finished) + /// track, which keeps it and its catalog rendition published. + /// + /// A finish that fails ends the track with the cause instead, so it can't be retried. + pub fn finish( + self, + ) -> crate::Result> { + self.track.finish() + } + + /// [`finish`](Self::finish) the track in place, for an owner that keeps this importer. + pub(crate) fn end(&mut self) -> crate::Result<()> { + self.track.end_with(None) } /// Abort the track with `err` instead of finishing it cleanly, so subscribers diff --git a/rs/moq-mux/src/codec/h265/import.rs b/rs/moq-mux/src/codec/h265/import.rs index cdde9f7018c..f111872d65c 100644 --- a/rs/moq-mux/src/codec/h265/import.rs +++ b/rs/moq-mux/src/codec/h265/import.rs @@ -134,10 +134,19 @@ impl Import { self.track.track() } - /// Finish the track, flushing the current group. - pub fn finish(&mut self) -> Result<()> { - self.track.end_with(None)?; - Ok(()) + /// Finish the track, flushing the current group, and return the [`Finished`](crate::container::Finished) + /// track, which keeps it and its catalog rendition published. + /// + /// A finish that fails ends the track with the cause instead, so it can't be retried. + pub fn finish( + self, + ) -> crate::Result> { + self.track.finish() + } + + /// [`finish`](Self::finish) the track in place, for an owner that keeps this importer. + pub(crate) fn end(&mut self) -> crate::Result<()> { + self.track.end_with(None) } /// Abort the track with `err` instead of finishing it cleanly, so subscribers diff --git a/rs/moq-mux/src/codec/legacy.rs b/rs/moq-mux/src/codec/legacy.rs index 21f868bbafd..4595ea280e5 100644 --- a/rs/moq-mux/src/codec/legacy.rs +++ b/rs/moq-mux/src/codec/legacy.rs @@ -157,10 +157,19 @@ impl Import { self.track.name() } - /// Finish the track, flushing the current group. - pub fn finish(&mut self) -> crate::Result<()> { - self.track.end_with(None)?; - Ok(()) + /// Finish the track, flushing the current group, and return the [`Finished`](crate::container::Finished) + /// track, which keeps it and its catalog rendition published. + /// + /// A finish that fails ends the track with the cause instead, so it can't be retried. + pub fn finish( + self, + ) -> crate::Result> { + self.track.finish() + } + + /// [`finish`](Self::finish) the track in place, for an owner that keeps this importer. + pub(crate) fn end(&mut self) -> crate::Result<()> { + self.track.end_with(None) } /// Abort the track with `err` instead of finishing it cleanly, so subscribers diff --git a/rs/moq-mux/src/codec/mp3.rs b/rs/moq-mux/src/codec/mp3.rs index 6e26dba466c..142f40bd7d0 100644 --- a/rs/moq-mux/src/codec/mp3.rs +++ b/rs/moq-mux/src/codec/mp3.rs @@ -134,10 +134,14 @@ impl Import { self.track.track().demand() } - /// Finish the track, flushing the current group. - pub fn finish(&mut self) -> crate::Result<()> { - self.track.end_with(None)?; - Ok(()) + /// Finish the track, flushing the current group, and return the [`Finished`](crate::container::Finished) + /// track, which keeps it and its catalog rendition published. + /// + /// A finish that fails ends the track with the cause instead, so it can't be retried. + pub fn finish( + self, + ) -> crate::Result> { + self.track.finish() } /// Abort the track with `err` instead of finishing it cleanly, so subscribers diff --git a/rs/moq-mux/src/codec/opus/import.rs b/rs/moq-mux/src/codec/opus/import.rs index 34621d04aa0..25dbd368ca5 100644 --- a/rs/moq-mux/src/codec/opus/import.rs +++ b/rs/moq-mux/src/codec/opus/import.rs @@ -47,10 +47,19 @@ impl Import { self.track.track().demand() } - /// Finish the track, flushing the current group. - pub fn finish(&mut self) -> crate::Result<()> { - self.track.end_with(None)?; - Ok(()) + /// Finish the track, flushing the current group, and return the [`Finished`](crate::container::Finished) + /// track, which keeps it and its catalog rendition published. + /// + /// A finish that fails ends the track with the cause instead, so it can't be retried. + pub fn finish( + self, + ) -> crate::Result> { + self.track.finish() + } + + /// [`finish`](Self::finish) the track in place, for an owner that keeps this importer. + pub(crate) fn end(&mut self) -> crate::Result<()> { + self.track.end_with(None) } /// Abort the track with `err` instead of finishing it cleanly, so subscribers @@ -205,6 +214,6 @@ mod tests { assert_eq!(frame.payload.as_ref(), payload); assert_eq!(frame.timestamp, Timestamp::from_micros(1_000).unwrap()); - import.finish().unwrap(); + let _finished = import.finish().unwrap(); } } diff --git a/rs/moq-mux/src/codec/vp8/import.rs b/rs/moq-mux/src/codec/vp8/import.rs index 7acda2efb84..6f37f8b3574 100644 --- a/rs/moq-mux/src/codec/vp8/import.rs +++ b/rs/moq-mux/src/codec/vp8/import.rs @@ -95,10 +95,14 @@ impl Import { self.track.track().demand() } - /// Finish the track, flushing the current group. - pub fn finish(&mut self) -> crate::Result<()> { - self.track.end_with(None)?; - Ok(()) + /// Finish the track, flushing the current group, and return the [`Finished`](crate::container::Finished) + /// track, which keeps it and its catalog rendition published. + /// + /// A finish that fails ends the track with the cause instead, so it can't be retried. + pub fn finish( + self, + ) -> crate::Result> { + self.track.finish() } /// Abort the track with `err` instead of finishing it cleanly, so subscribers @@ -175,7 +179,7 @@ mod tests { .decode(&interframe, Some(Timestamp::from_micros(33_000).unwrap())) .unwrap(); - import.finish().unwrap(); + let _finished = import.finish().unwrap(); } /// A reservation that selected LOC makes the importer write LOC frames and advertise the @@ -212,7 +216,7 @@ mod tests { assert_eq!(frame.payload, keyframe); assert_eq!(frame.timestamp, Timestamp::from_micros(0).unwrap()); - import.finish().unwrap(); + let _finished = import.finish().unwrap(); } /// An interframe before any key frame has no dimensions, so the Producer diff --git a/rs/moq-mux/src/codec/vp9/import.rs b/rs/moq-mux/src/codec/vp9/import.rs index a6c5e331e6c..1c22324a633 100644 --- a/rs/moq-mux/src/codec/vp9/import.rs +++ b/rs/moq-mux/src/codec/vp9/import.rs @@ -96,10 +96,14 @@ impl Import { self.track.track().demand() } - /// Finish the track, flushing the current group. - pub fn finish(&mut self) -> crate::Result<()> { - self.track.end_with(None)?; - Ok(()) + /// Finish the track, flushing the current group, and return the [`Finished`](crate::container::Finished) + /// track, which keeps it and its catalog rendition published. + /// + /// A finish that fails ends the track with the cause instead, so it can't be retried. + pub fn finish( + self, + ) -> crate::Result> { + self.track.finish() } /// Abort the track with `err` instead of finishing it cleanly, so subscribers @@ -174,7 +178,7 @@ mod tests { .decode(&[0x84, 0x00, 0x00], Some(Timestamp::from_micros(33_000).unwrap())) .unwrap(); - import.finish().unwrap(); + let _finished = import.finish().unwrap(); } #[tokio::test(start_paused = true)] diff --git a/rs/moq-mux/src/container/ts/import.rs b/rs/moq-mux/src/container/ts/import.rs index 2e45f95ee69..1409acc5ffb 100644 --- a/rs/moq-mux/src/container/ts/import.rs +++ b/rs/moq-mux/src/container/ts/import.rs @@ -3492,7 +3492,7 @@ impl Stream { let published = video::avc(split, import, assembly, true)?; *split = Default::default(); assembly.finish(); - import.finish()?; + import.end()?; return Ok(published); } Stream::H265 { @@ -3503,7 +3503,7 @@ impl Stream { let published = video::hevc(split, import, assembly, true)?; *split = Default::default(); assembly.finish(); - import.finish()?; + import.end()?; return Ok(published); } Stream::Opus(stream) => stream.finish()?, @@ -4026,8 +4026,8 @@ impl AacStream { if let Some(end) = open.take() { import.cut(Some(end))?; } - import.finish()?; - self.import = None; + // The ended track retires with its handle, since the rest publishes under a new name. + drop(self.import.take().map(aac::Import::finish).transpose()?); self.last = None; } let import = match &mut self.import { @@ -4179,7 +4179,7 @@ impl AacStream { self.reserved.take(); } if let Some(import) = &mut self.import { - import.finish()?; + import.end()?; } Ok(drained) } @@ -4244,7 +4244,7 @@ impl OpusStream { } fn finish(&mut self) -> anyhow::Result<()> { - Ok(self.import.finish()?) + Ok(self.import.end()?) } fn abort(self, err: moq_net::Error) { @@ -4673,8 +4673,8 @@ impl LegacyStream { if let Some(end) = open.take() { import.cut(Some(end))?; } - import.finish()?; - self.import = None; + // The ended track retires with its handle, since the rest publishes under a new name. + drop(self.import.take().map(legacy::Import::finish).transpose()?); self.last = None; } let import = match &mut self.import { @@ -4788,7 +4788,7 @@ impl LegacyStream { self.reserved.take(); } if let Some(import) = &mut self.import { - import.finish()?; + import.end()?; } Ok(drained) } diff --git a/rs/moq-mux/src/import/mod.rs b/rs/moq-mux/src/import/mod.rs index 3324b9f631c..313b9e5ee6d 100644 --- a/rs/moq-mux/src/import/mod.rs +++ b/rs/moq-mux/src/import/mod.rs @@ -21,12 +21,12 @@ pub mod container; mod format; mod init; -mod track; +pub mod track; pub use container::Container; pub use format::{AudioFormat, ContainerFormat, Format, Kind, VideoFormat}; pub use init::{AudioInit, ContainerInit, VideoInit}; -pub use track::*; +pub use track::{Track, TrackStream}; /// A finished importer keeps its tracks and renditions published, but not its input storage. /// @@ -119,8 +119,7 @@ mod tests { let pts = moq_net::Timestamp::from_micros(pts).unwrap(); track.decode(keyframe.clone(), Some(pts)).unwrap(); } - track.finish().unwrap(); - Box::new(track) + Box::new(track.finish().unwrap()) }); } @@ -132,8 +131,7 @@ mod tests { let init = VideoInit::new(VideoFormat::Avc3, Bytes::new()); let mut track = TrackStream::video(avc3(broadcast), catalog.reserve(), init).unwrap(); track.decode(&stream).unwrap(); - track.finish().unwrap(); - Box::new(track) + Box::new(track.finish().unwrap()) }); } diff --git a/rs/moq-mux/src/import/track.rs b/rs/moq-mux/src/import/track.rs index 14d120de4f5..a102966b883 100644 --- a/rs/moq-mux/src/import/track.rs +++ b/rs/moq-mux/src/import/track.rs @@ -10,8 +10,7 @@ use crate::catalog::VideoHint; use crate::catalog::hang::CatalogExt; use crate::container::Frame; -use super::{AudioFormat, VideoFormat}; -pub use super::{AudioInit, VideoInit}; +use super::{AudioFormat, AudioInit, VideoFormat, VideoInit}; /// The caller's video fields, defaulting the codec from the format when the codec carries no extra /// parameters (VP8), so a hint with a codec can publish before the first frame. @@ -431,18 +430,35 @@ impl Track { Ok(()) } - /// Finish the importer, flushing any buffered data. - pub fn finish(&mut self) -> Result<()> { + /// Finish the importer, flushing any buffered data, and return the [`Finished`] track, which + /// keeps it and its catalog rendition published. + /// + /// A finish that fails ends the track with the cause instead, so it can't be retried. + pub fn finish(mut self) -> Result { // Each decode flushed its whole frame, so a splitter holds at most a picture its init - // carried. It is taken out to flush, so its input storage ends with the input. The import - // stays, keeping the finished track and its rendition published. - match &mut self.kind { - TrackKind::Avc3 { split, import } => import.decode(std::mem::take(split).flush(None)?)?, - TrackKind::Hev1 { split, import } => import.decode(std::mem::take(split).flush(None)?)?, - TrackKind::Av01 { split, import } => import.decode(std::mem::take(split).flush(None)?)?, - _ => {} + // carried. + let flushed = (|| match &mut self.kind { + TrackKind::Avc3 { split, import } => import.decode(split.flush(None)?), + TrackKind::Hev1 { split, import } => import.decode(split.flush(None)?), + TrackKind::Av01 { split, import } => import.decode(split.flush(None)?), + _ => Ok(()), + })(); + if let Err(err) = flushed { + self.abort(err.reason()); + return Err(err); } - import!(&mut self.kind, import => import.finish()) + let inner = match self.kind { + TrackKind::Avc3 { import, .. } | TrackKind::Avc1 { import, .. } => FinishedKind::Video(import.finish()?), + TrackKind::Hev1 { import, .. } | TrackKind::Hvc1 { import, .. } => FinishedKind::Video(import.finish()?), + TrackKind::Av01 { import, .. } => FinishedKind::Video(import.finish()?), + TrackKind::Vp8(import) => FinishedKind::Video(import.finish()?), + TrackKind::Vp9(import) => FinishedKind::Video(import.finish()?), + TrackKind::Aac(import) => FinishedKind::Audio(import.finish()?), + TrackKind::Opus(import) => FinishedKind::Audio(import.finish()?), + TrackKind::Mp3(import) => FinishedKind::Audio(import.finish()?), + TrackKind::Flac(import) => FinishedKind::Audio(import.finish()?), + }; + Ok(Finished { inner }) } /// Abort the track with `err` instead of finishing it cleanly, so subscribers @@ -744,14 +760,18 @@ impl TrackStream { }) } - /// Finish the importer, flushing any buffered data. - pub fn finish(&mut self) -> Result<()> { - // The splitter is taken out to flush, so its input storage ends with the input. The import - // stays, keeping the finished track and its rendition published. - stream!(&mut self.kind, split, import => { - publish!(self.gate, import, std::mem::take(split).flush(None)?)?; - import.finish() - }) + /// Finish the importer, publishing the access unit still waiting for a following start code, + /// and return the [`Finished`] track, which keeps it and its catalog rendition published. + /// + /// A finish that fails ends the track with the cause instead, so it can't be retried. + pub fn finish(mut self) -> Result { + let flushed = (|| stream!(&mut self.kind, split, import => publish!(self.gate, import, split.flush(None)?)))(); + if let Err(err) = flushed { + self.abort(err.reason()); + return Err(err); + } + let inner = stream!(self.kind, _, import => FinishedKind::Video(import.finish()?)); + Ok(Finished { inner }) } /// Stop or resume publishing this rendition, advertised as the catalog's @@ -815,6 +835,46 @@ impl TrackStream { } } +/// A [`Track`] or [`TrackStream`] that finished: every frame is published, and the track can +/// still be aborted, but not written to. +/// +/// Dropping it releases the track and its catalog rendition, as dropping the importer does. +/// +/// ```compile_fail,E0599 +/// # fn cannot_decode(mut track: moq_mux::import::track::Finished) { +/// track.decode(b"", None).unwrap(); +/// # } +/// ``` +#[must_use = "dropping it releases the track and its catalog rendition"] +pub struct Finished { + inner: FinishedKind, +} + +/// The finished track a [`Finished`] holds, by the catalog section its rendition is in. +enum FinishedKind { + Video(crate::container::Finished), + Audio(crate::container::Finished), +} + +impl Finished { + /// The name of the track this importer published. + pub fn name(&self) -> &str { + match &self.inner { + FinishedKind::Video(track) => track.name(), + FinishedKind::Audio(track) => track.name(), + } + } + + /// Release the track's cache, reporting `err` to readers that have not drained it; see + /// [`moq_net::track::Finished::abort`]. + pub fn abort(self, err: moq_net::Error) { + match self.inner { + FinishedKind::Video(track) => track.abort(err), + FinishedKind::Audio(track) => track.abort(err), + } + } +} + #[cfg(test)] mod tests { use std::time::Duration; @@ -873,7 +933,7 @@ mod tests { import .decode(b"opus payload", Some(Timestamp::from_micros(1_000).unwrap())) .unwrap(); - import.finish().unwrap(); + let _finished = import.finish().unwrap(); } #[tokio::test(start_paused = true)] @@ -986,10 +1046,11 @@ mod tests { import .decode(b"opus payload", Some(Timestamp::from_micros(2_000).unwrap())) .unwrap(); - import.finish().unwrap(); + let finished = import.finish().unwrap(); + assert!(catalog.snapshot().audio.renditions.contains_key("0.opus")); - // Dropping the importer retires its rendition from the shared catalog. - drop(import); + // Dropping the finished importer retires its rendition from the shared catalog. + drop(finished); assert!(!catalog.snapshot().audio.renditions.contains_key("0.opus")); } @@ -1013,7 +1074,7 @@ mod tests { import .decode(b"opus payload", Some(Timestamp::from_micros(20_000).unwrap())) .unwrap(); - import.finish().unwrap(); + let _finished = import.finish().unwrap(); } #[tokio::test(start_paused = true)] @@ -1046,7 +1107,7 @@ mod tests { assert_eq!(frame.payload, payload); assert_eq!(frame.timestamp, Timestamp::from_micros(1_000).unwrap()); - import.finish().unwrap(); + let _finished = import.finish().unwrap(); } /// Count the frames in each group of a finished track. @@ -1096,7 +1157,7 @@ mod tests { for ts in [30_000, 40_000] { import.decode(b"a", Some(Timestamp::from_micros(ts).unwrap())).unwrap(); } - import.finish().unwrap(); + let _finished = import.finish().unwrap(); assert_eq!(collect_groups(subscriber).await, vec![3, 2]); } @@ -1117,7 +1178,7 @@ mod tests { .decode(b"b", Some(Timestamp::from_micros(pts * 1_000).unwrap())) .unwrap(); } - import.finish().unwrap(); + let _finished = import.finish().unwrap(); // The middle group is the established empty-payload discontinuity marker. assert_eq!(collect_groups(subscriber).await, vec![2, 1, 2]); } @@ -1134,7 +1195,7 @@ mod tests { import.decode(b"a", Some(Timestamp::from_micros(ts).unwrap())).unwrap(); import.cut(None).unwrap(); } - import.finish().unwrap(); + let _finished = import.finish().unwrap(); assert_eq!(collect_groups(subscriber).await, vec![1, 1, 1]); } @@ -1155,7 +1216,7 @@ mod tests { import .decode(b"c", Some(Timestamp::from_micros(20_000).unwrap())) .unwrap(); - import.finish().unwrap(); + let _finished = import.finish().unwrap(); assert_eq!(collect_groups(subscriber).await, vec![2, 1]); } @@ -1179,7 +1240,7 @@ mod tests { .unwrap(); } import.cut(Some(Timestamp::from_micros(1_000_000).unwrap())).unwrap(); - import.finish().unwrap(); + let _finished = import.finish().unwrap(); let audio = catalog.snapshot().audio.renditions.get("audio").cloned().unwrap(); assert!( @@ -1412,7 +1473,7 @@ mod tests { assert_eq!(frame.payload, au, "the payload must pass through verbatim"); assert_eq!(frame.timestamp, Timestamp::from_micros(1_000).unwrap()); - import.finish().unwrap(); + let _finished = import.finish().unwrap(); } const H264_IDR: &[u8] = &[0x65, 0x88, 0x84, 0x21]; @@ -1483,7 +1544,7 @@ mod tests { } let timestamp = Timestamp::from_micros(1_000).unwrap(); import.decode(&keyframe, Some(timestamp)).unwrap(); - import.finish().unwrap(); + let _finished = import.finish().unwrap(); let frame = first_frame(&consumer, "video").await; assert!(frame.keyframe, "{format}, seek={seek}"); assert_eq!(frame.timestamp, timestamp, "{format}, seek={seek}"); @@ -1510,7 +1571,7 @@ mod tests { stream.seek(7).unwrap(); } stream.decode(&keyframe).unwrap(); - stream.finish().unwrap(); + let _finished = stream.finish().unwrap(); let frame = first_frame(&consumer, "video").await; assert!(frame.keyframe, "{format}: streaming seek"); assert_eq!( @@ -1525,18 +1586,46 @@ mod tests { async fn init_picture_published_at_finish(format: VideoFormat, init: Vec) { let (broadcast, catalog) = new_broadcast(); let consumer = broadcast.consume(); - let mut import = Track::video( + let import = Track::video( broadcast.reserve_track("video").unwrap(), catalog.reserve(), VideoInit::new(format, init.clone()), ) .unwrap(); - import.finish().unwrap(); + let _finished = import.finish().unwrap(); let frame = first_frame(&consumer, "video").await; assert!(frame.keyframe, "{format}"); assert_eq!(frame.payload.as_ref(), init.as_slice(), "{format}"); } + /// A finish whose flushed access unit fails ends the track with that failure, so a reader + /// sees the publisher fail rather than the track dropped unfinished. + #[tokio::test(start_paused = true)] + async fn a_failed_finish_aborts_the_track() { + let (broadcast, catalog) = new_broadcast(); + let consumer = broadcast.consume(); + let mut stream = TrackStream::video( + broadcast.reserve_track("video").unwrap(), + catalog.reserve(), + VideoInit::new(VideoFormat::Avc3, h264_init()), + ) + .unwrap(); + let mut track = consumer.track("video").unwrap().subscribe(None).await.unwrap(); + + // A delta slice with no keyframe before it, held by the splitter until the finish flushes it. + stream.decode(&annexb(&[&[0x61, 0xe0, 0x12, 0x34]])).unwrap(); + assert!(stream.finish().is_err()); + + let read = kio::clock::timeout(Duration::from_secs(1), track.recv_group()).await; + let Err(err) = read.expect("the track carried on") else { + panic!("the track ended without a cause"); + }; + assert!( + matches!(err, moq_net::Error::Stream(moq_net::StreamError::Internal)), + "{err:?}" + ); + } + #[tokio::test(start_paused = true)] async fn avc3_init_picture_published_at_finish() { let mut init = h264_init(); @@ -1646,7 +1735,7 @@ mod tests { catalog.snapshot().video.renditions.contains_key("video"), "{format}: no rendition" ); - import.finish().unwrap(); + let _finished = import.finish().unwrap(); } } @@ -1682,7 +1771,7 @@ mod tests { .decode(frame, Some(Timestamp::from_micros(i * 26_122).unwrap())) .unwrap(); } - import.finish().unwrap(); + let _finished = import.finish().unwrap(); // Frames carrying audio per group, ignoring any empty end-of-group marker. let mut groups = Vec::new(); @@ -1731,7 +1820,7 @@ mod tests { for chunk in stream.chunks(3) { import.decode(chunk).unwrap(); } - import.finish().unwrap(); + let _finished = import.finish().unwrap(); let frame = first_frame(&consumer, "video").await; assert!(frame.keyframe, "{format}: the first frame opens a group"); @@ -1799,7 +1888,7 @@ mod tests { assert!(!enabled(), "enabled before the keyframe that resumes it"); write(&mut import, &delta).await; assert!(enabled()); - import.finish().unwrap(); + let _finished = import.finish().unwrap(); // The first group loses the access units still in the splitter at the disable, the // marker breaks the timeline, and the resumed group opens on the keyframe: three @@ -1834,7 +1923,7 @@ mod tests { // Finish flushes the last temporal unit, the keyframe that resumes. import.set_enabled(true).unwrap(); - import.finish().unwrap(); + let _finished = import.finish().unwrap(); assert!(catalog.snapshot().video.renditions["video"].enabled); let frame = first_frame(&consumer, "video").await; diff --git a/rs/moq-rtsp/src/client.rs b/rs/moq-rtsp/src/client.rs index bcf2182cf7b..1db1a493888 100644 --- a/rs/moq-rtsp/src/client.rs +++ b/rs/moq-rtsp/src/client.rs @@ -289,13 +289,14 @@ enum Track { } impl Track { - fn finish(&mut self) -> moq_mux::Result<()> { + /// End the track cleanly. It leaves the broadcast with this handle. + fn finish(self) -> moq_mux::Result<()> { match self { - Self::Video(video) => match &mut **video { - Video::H264 { import, .. } => import.finish(), - Video::H265 { import, .. } => import.finish(), + Self::Video(video) => match *video { + Video::H264 { import, .. } => import.finish().map(drop), + Video::H265 { import, .. } => import.finish().map(drop), }, - Self::Aac(import) => import.finish(), + Self::Aac(import) => import.finish().map(drop), } } @@ -525,7 +526,7 @@ impl Ingest { /// Flush every track and end it cleanly, reporting the first failure. fn finish(&mut self) -> Result<()> { let mut result = Ok(()); - for mut stream in self.streams.drain(..).flatten() { + for stream in self.streams.drain(..).flatten() { result = result.and(stream.track.finish().map_err(Error::from)); } result diff --git a/rs/moq-video/src/encode/mod.rs b/rs/moq-video/src/encode/mod.rs index a7d9c1eb8a8..ee13ee71147 100644 --- a/rs/moq-video/src/encode/mod.rs +++ b/rs/moq-video/src/encode/mod.rs @@ -46,9 +46,9 @@ mod sink; pub use backend::NAMES; pub use encoded::Encoded; pub use encoder::{Applied, Codec, Config, Encoder, Kind, Preset}; -pub use producer::Producer; #[cfg(feature = "capture")] pub use producer::{Capture, Driver, Publication, State, Status, publish_capture}; +pub use producer::{Finished, Producer}; pub use sink::Sink; #[cfg(test)] diff --git a/rs/moq-video/src/encode/producer.rs b/rs/moq-video/src/encode/producer.rs index f9de903fd9a..c997d5338f4 100644 --- a/rs/moq-video/src/encode/producer.rs +++ b/rs/moq-video/src/encode/producer.rs @@ -230,28 +230,20 @@ impl Producer { /// Finalize the track. /// - /// Borrows rather than consumes, so a later [`abort`](Self::abort) can still - /// run after a successful finish. - pub fn finish(&mut self) -> Result<(), Error> { - // Each publish flushed its access unit, so the splitter holds only input storage, which - // ends here. The import stays, keeping the finished track and its rendition published. - match &mut self.codecs { - Codecs::H264 { split, import } => { - *split = Default::default(); - import.finish()? - } - Codecs::H265 { split, import } => { - *split = Default::default(); - import.finish()? - } - } - Ok(()) + /// Consumes the producer, releasing the splitter. The returned [`Finished`] keeps the track + /// and its catalog rendition published, and can still [`abort`](Finished::abort) them. A + /// finish that fails ends the track with an error instead. + pub fn finish(self) -> Result { + // Each publish flushed its access unit, so the splitter holds only input storage. + let track = match self.codecs { + Codecs::H264 { import, .. } => import.finish()?, + Codecs::H265 { import, .. } => import.finish()?, + }; + Ok(Finished { track }) } /// Abort the track with `err` instead of finishing it cleanly, so subscribers /// see the real cause rather than [`moq_net::Error::Dropped`]. - /// - /// Consumes the producer. Still callable after [`finish`](Self::finish). pub fn abort(self, err: moq_net::Error) { match self.codecs { Codecs::H264 { import, .. } => import.abort(err), @@ -260,6 +252,34 @@ impl Producer { } } +/// A video track whose [`Producer`] [finished](Producer::finish) it: every frame is published, +/// and it can still be watched or aborted, but not written to. +/// +/// Dropping it releases the track like dropping a [`Producer`]. +/// +/// ```compile_fail,E0599 +/// # fn cannot_publish(track: moq_video::encode::Finished, encoded: &moq_video::encode::Encoded) { +/// track.publish(encoded).unwrap(); +/// # } +/// ``` +#[must_use = "dropping it releases the track and its catalog rendition"] +pub struct Finished { + track: moq_mux::container::Finished, +} + +impl Finished { + /// A watch-only handle to the track's subscriber demand; see [`Producer::demand`]. + pub fn demand(&self) -> moq_net::track::Demand { + self.track.demand() + } + + /// Abort the track with `err`, so subscribers that have not drained it see the real cause; see + /// [`Producer::abort`]. + pub fn abort(self, err: moq_net::Error) { + self.track.abort(err); + } +} + /// Capture and encode settings for [`publish_capture`]. /// /// The encoded geometry (width / height / framerate) comes from the capture @@ -521,10 +541,10 @@ enum Owned { impl Owned { /// End the track cleanly, best effort: it is usually already going away. fn finish(self) { + // The caller is done with the track, so the finished handle goes with it. let ended = match self { - // The caller is done with the track, so the finished handle goes with it. Self::Track(track) => track.finish().map(drop).map_err(Error::from), - Self::Producer(mut producer) => producer.finish(), + Self::Producer(producer) => producer.finish().map(drop), Self::Done => Ok(()), }; if let Err(err) = ended { @@ -1199,7 +1219,7 @@ mod tests { producer.publish(&encoded).unwrap(); } } - producer.finish().unwrap(); + let _finished = producer.finish().unwrap(); assert_eq!(collect_groups(consumer).await, vec![1, 1, 1]); } @@ -1326,7 +1346,7 @@ mod tests { assert_eq!(rendition.bitrate, Some(6_000_000)); } - /// Finish leaves the handle, so abort can still run. + /// Finish returns a handle, so abort can still run. #[tokio::test] #[cfg(feature = "openh264")] async fn abort_after_finish() { @@ -1352,9 +1372,9 @@ mod tests { producer.publish(&encoded).unwrap(); } - producer.finish().unwrap(); + let finished = producer.finish().unwrap(); assert!(subscriber.recv_group().await.unwrap().is_some()); - producer.abort(moq_net::Error::Cancel); + finished.abort(moq_net::Error::Cancel); } #[tokio::test] @@ -1424,7 +1444,7 @@ mod tests { _broadcast: moq_net::broadcast::Producer, opens: tokio::sync::mpsc::UnboundedSender, stop: Option>, - task: tokio::task::JoinHandle>, + task: tokio::task::JoinHandle>, } impl Fixture { @@ -1530,7 +1550,7 @@ mod tests { /// Stop the loop and finalize the track, as a clean end of capture does. async fn finish(mut self) -> (moq_mux::catalog::Producer, moq_net::broadcast::Consumer) { let _ = self.stop.take().expect("finished once").send(()); - self.task.await.unwrap().unwrap(); + drop(self.task.await.unwrap().unwrap()); (self.catalog, self.consumer) } @@ -2486,8 +2506,7 @@ mod finished { let pts = moq_net::Timestamp::from_micros(pts).unwrap(); producer.publish(&Encoded::new(keyframe(), pts, true)).unwrap(); } - producer.finish().unwrap(); - producer + producer.finish().unwrap() }) .collect(); diff --git a/rs/moq-webrtc/src/codec/av1.rs b/rs/moq-webrtc/src/codec/av1.rs index aeee3ecbedd..1730e9b04ea 100644 --- a/rs/moq-webrtc/src/codec/av1.rs +++ b/rs/moq-webrtc/src/codec/av1.rs @@ -32,8 +32,8 @@ impl codec::Bridge for Bridge { Ok(()) } - fn finish(&mut self) -> Result<()> { - Ok(self.import.finish()?) + fn finish(self: Box) -> Result { + Ok(Box::new(self.import.finish()?)) } fn abort(self: Box, err: moq_net::Error) { diff --git a/rs/moq-webrtc/src/codec/h264.rs b/rs/moq-webrtc/src/codec/h264.rs index dd12bf9428f..37dad1d1d2b 100644 --- a/rs/moq-webrtc/src/codec/h264.rs +++ b/rs/moq-webrtc/src/codec/h264.rs @@ -31,8 +31,8 @@ impl codec::Bridge for Bridge { Ok(()) } - fn finish(&mut self) -> Result<()> { - Ok(self.import.finish()?) + fn finish(self: Box) -> Result { + Ok(Box::new(self.import.finish()?)) } fn abort(self: Box, err: moq_net::Error) { diff --git a/rs/moq-webrtc/src/codec/h265.rs b/rs/moq-webrtc/src/codec/h265.rs index 0aeeb1c8406..9beb5dea258 100644 --- a/rs/moq-webrtc/src/codec/h265.rs +++ b/rs/moq-webrtc/src/codec/h265.rs @@ -33,8 +33,8 @@ impl codec::Bridge for Bridge { Ok(()) } - fn finish(&mut self) -> Result<()> { - Ok(self.import.finish()?) + fn finish(self: Box) -> Result { + Ok(Box::new(self.import.finish()?)) } fn abort(self: Box, err: moq_net::Error) { diff --git a/rs/moq-webrtc/src/codec/mod.rs b/rs/moq-webrtc/src/codec/mod.rs index 67decc236de..911e3be7157 100644 --- a/rs/moq-webrtc/src/codec/mod.rs +++ b/rs/moq-webrtc/src/codec/mod.rs @@ -44,9 +44,9 @@ pub struct Frame { pub trait Bridge: Send { fn push(&mut self, frame: Frame) -> Result<()>; - /// Finish the published track after its final frame, so a finished broadcast keeps - /// serving it. - fn finish(&mut self) -> Result<()>; + /// Finish the published track after its final frame, returning what keeps serving it while + /// the finished broadcast is held. + fn finish(self: Box) -> Result; /// Abort the published track with `err` so subscribers see the real cause /// (the peer disconnected, an ICE failure) rather than a bare `Error::Dropped`. @@ -55,6 +55,9 @@ pub trait Bridge: Send { fn abort(self: Box, err: moq_net::Error); } +/// A bridge's finished track, held so a finished broadcast keeps serving it. +pub type Finished = Box; + /// A mux importer whose catalog configuration is resolved from its first frame. pub(crate) trait DeferredImport: Send + Sized { /// Create the importer and its unresolved catalog rendition. @@ -64,7 +67,7 @@ pub(crate) trait DeferredImport: Send + Sized { fn decode(&mut self, frame: Bytes, pts: moq_net::Timestamp) -> moq_mux::Result<()>; /// Finish the active media track. - fn finish(&mut self) -> moq_mux::Result<()>; + fn finish(self) -> moq_mux::Result>; /// Abort the active media track. fn abort(self, err: moq_net::Error); @@ -79,7 +82,7 @@ impl DeferredImport for moq_mux::codec::vp8::Import { moq_mux::codec::vp8::Import::decode(self, frame, Some(pts)) } - fn finish(&mut self) -> moq_mux::Result<()> { + fn finish(self) -> moq_mux::Result> { moq_mux::codec::vp8::Import::finish(self) } @@ -97,7 +100,7 @@ impl DeferredImport for moq_mux::codec::vp9::Import { moq_mux::codec::vp9::Import::decode(self, frame, Some(pts)) } - fn finish(&mut self) -> moq_mux::Result<()> { + fn finish(self) -> moq_mux::Result> { moq_mux::codec::vp9::Import::finish(self) } @@ -162,15 +165,14 @@ impl DeferredVideo { } /// Finish the media track, whether or not a frame ever created its importer. - pub fn finish(&mut self) -> Result<()> { - match &mut self.state { - // The pending state keeps its own clone, whose appends the end refuses. - DeferredState::Pending(pending) => drop(pending.track.clone().finish()?), - DeferredState::Active(import) => import.finish()?, + pub fn finish(self) -> Result { + Ok(match self.state { + DeferredState::Pending(pending) => Box::new(pending.track.finish()?), + DeferredState::Active(import) => Box::new(import.finish()?), // The track already failed, so there is nothing clean to end. - DeferredState::Failed(_) | DeferredState::Poisoned => {} - } - Ok(()) + DeferredState::Failed(track) => track, + DeferredState::Poisoned => Box::new(()), + }) } /// Abort the media track in either lifecycle state. diff --git a/rs/moq-webrtc/src/codec/opus.rs b/rs/moq-webrtc/src/codec/opus.rs index d4431d11d85..825f6c8c3fa 100644 --- a/rs/moq-webrtc/src/codec/opus.rs +++ b/rs/moq-webrtc/src/codec/opus.rs @@ -33,8 +33,8 @@ impl codec::Bridge for Bridge { Ok(()) } - fn finish(&mut self) -> Result<()> { - Ok(self.import.finish()?) + fn finish(self: Box) -> Result { + Ok(Box::new(self.import.finish()?)) } fn abort(self: Box, err: moq_net::Error) { diff --git a/rs/moq-webrtc/src/codec/vp8.rs b/rs/moq-webrtc/src/codec/vp8.rs index 5817380076c..d56df7ab349 100644 --- a/rs/moq-webrtc/src/codec/vp8.rs +++ b/rs/moq-webrtc/src/codec/vp8.rs @@ -25,7 +25,7 @@ impl codec::Bridge for Bridge { self.import.decode(frame.payload, pts) } - fn finish(&mut self) -> Result<()> { + fn finish(self: Box) -> Result { self.import.finish() } diff --git a/rs/moq-webrtc/src/codec/vp9.rs b/rs/moq-webrtc/src/codec/vp9.rs index e7b71491f76..dfde3c1bf4f 100644 --- a/rs/moq-webrtc/src/codec/vp9.rs +++ b/rs/moq-webrtc/src/codec/vp9.rs @@ -25,7 +25,7 @@ impl codec::Bridge for Bridge { self.import.decode(frame.payload, pts) } - fn finish(&mut self) -> Result<()> { + fn finish(self: Box) -> Result { self.import.finish() } diff --git a/rs/moq-webrtc/src/session.rs b/rs/moq-webrtc/src/session.rs index 51eab73941a..3dea4fdd8d9 100644 --- a/rs/moq-webrtc/src/session.rs +++ b/rs/moq-webrtc/src/session.rs @@ -596,11 +596,16 @@ fn media_time_to_micros(time: &str0m::media::MediaTime) -> u64 { /// events arrive on the ingest side. pub(crate) struct Bridges { inner: HashMap>, + /// The finished bridges' tracks, served until the bridges are dropped. + finished: Vec, } impl Bridges { pub fn new() -> Self { - Self { inner: HashMap::new() } + Self { + inner: HashMap::new(), + finished: Vec::new(), + } } pub fn insert(&mut self, mid: str0m::media::Mid, bridge: Box) { @@ -616,8 +621,8 @@ impl Bridges { /// Finish every bridge's track after the final frame. pub fn finish(&mut self) -> Result<()> { - for bridge in self.inner.values_mut() { - bridge.finish()?; + for bridge in std::mem::take(&mut self.inner).into_values() { + self.finished.push(bridge.finish()?); } Ok(()) } diff --git a/test/interop/clients/rust/finish.rs b/test/interop/clients/rust/finish.rs index 04a049d53db..3112477dd35 100644 --- a/test/interop/clients/rust/finish.rs +++ b/test/interop/clients/rust/finish.rs @@ -78,15 +78,15 @@ async fn main() -> anyhow::Result<()> { if args.role == "publish" { let route = origin.route(&args.broadcast, moq_net::origin::RouteOptions::hidden())?; let mut catalog = moq_mux::catalog::Producer::<()>::new(&mut route.broadcast().clone(), Default::default())?; - let mut media = moq_mux::import::TrackStream::video( + let mut stream = moq_mux::import::TrackStream::video( route.broadcast().reserve_track("video")?, catalog.reserve(), moq_mux::import::VideoInit::new(moq_mux::import::VideoFormat::Avc3, Vec::new()), )?; let mut data = Vec::new(); stdin.read_to_end(&mut data).await?; - media.decode(&data)?; - media.finish()?; + stream.decode(&data)?; + let media = stream.finish()?; catalog.finish()?; route.announce()?; // Keep the finished broadcast up for the late readers, then take it offline. From 9c3a152d89aeb85ee1702e8f2c39abd4709e9b47 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 07:29:51 -0800 Subject: [PATCH 3/3] chore(quest): finish quest/m2/finish-sweep.md Co-Authored-By: Claude Opus 5.5 --- quest/m2/README.md | 2 +- quest/m2/finish-sweep.md | 77 --------------------------- quest/m2/ts-typed-outcomes.md | 1 - quest/m2/video-producer.md | 5 +- rs/moq-mux/src/codec/aac/import.rs | 2 +- rs/moq-mux/src/codec/h264/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/opus/import.rs | 2 +- rs/moq-mux/src/container/ts/import.rs | 10 ++-- 10 files changed, 13 insertions(+), 92 deletions(-) delete mode 100644 quest/m2/finish-sweep.md diff --git a/quest/m2/README.md b/quest/m2/README.md index 42df4d4cfa6..96e7adefb1f 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -59,7 +59,7 @@ removal, a rename, or a wire, catalog, or format change that is free until `mpegts`, one strict rule); [the archive as version 2](/quest/m2/archive-v2.md); [declared ends](/quest/m2/time-addressing/consumers.md), back from m3; - [finish](/quest/m2/finish-sweep.md), [TS outcomes](/quest/m2/ts-typed-outcomes.md), + [TS outcomes](/quest/m2/ts-typed-outcomes.md) and [moq-json writes](/quest/m2/json-write-at.md). - **Native media and gateways.** [The video producer](/quest/m2/video-producer.md), [the hole wait](/quest/m2/delay-hole-wait.md), diff --git a/quest/m2/finish-sweep.md b/quest/m2/finish-sweep.md deleted file mode 100644 index e5befe53efd..00000000000 --- a/quest/m2/finish-sweep.md +++ /dev/null @@ -1,77 +0,0 @@ -# [M] Finishing an importer or the video producer returns a Finished handle - -## Goal - -Every media producer finishes the same way. The ten codec importers in -`rs/moq-mux/src/codec`, the two import front doors that wrap them -(`moq_mux::import::Track` and `TrackStream` in -`rs/moq-mux/src/import/track.rs`), and `moq_video::encode::Producer` take -`finish(self)` and return a `Finished` handle that keeps the track and its -catalog rendition published and can still `abort`. After `finish`, nothing -can publish another frame, because nothing holds the producer. The bindings -and every caller in the tree follow. - -## Plan - -Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): this -completes the 2026-11-07 decision that -[moq-dev/moq#8395](https://github.com/moq-dev/moq/pull/8395) carried out -("finishing a media producer returns a Finished handle", settled in m2 -before the cut). The audit found the sweep stopped short; no new decision -was needed, and none was recorded for leaving these out. - -Facts found by the audit: - -- #8395 converted the moq-mux container producers - (`container::Producer::finish(self) -> Result>`), - moq-json, and - `moq_audio::encode::Producer::finish(self) -> Result`. - The container importers (`fmp4`, `flv`, `mkv`, `ts`) consume and return - a `Finished` too. -- The video twin still borrows: - `rs/moq-video/src/encode/producer.rs`, - `pub fn finish(&mut self) -> Result<(), Error>`, documented as "borrows - rather than consumes, so a later abort can still run after a successful - finish". That is the case the `Finished` handle exists for, and after - `finish`, `publish` is still callable. -- Ten codec importers still take `finish(&mut self) -> Result<()>`: - `aac`, `av1`, `flac`, `h264`, `h265`, `legacy`, `mp3`, `opus`, `vp8`, and - `vp9` under `rs/moq-mux/src/codec` (re-run - `grep -rn 'pub fn finish(&mut self)' rs/moq-mux/src/codec rs/moq-mux/src/import`). - Each ends in `self.track.end_with(None)` on a `container::Producer` that - already has the consuming `finish`. -- `rs/AGENTS.md`: "Terminal operations consume `self`". - -For the PR: - -- Importers first: each `finish(self)` returns the `Finished` of the - container producer it wraps (or a small `Finished` of its own exposing - `name`, `track`, and `abort`, if the wrapped type should stay private). - One shape for all ten; do not invent a per-codec handle. -- `import::Track` and `TrackStream` then return a `Finished` over - whichever importer they hold. Their comment "the import stays, keeping - the finished track and its rendition published" becomes the handle's - job. -- `moq_video::encode::Producer::finish(self) -> Result`, - with `Finished::abort`, matching the audio producer line for line. This - type is being renamed by - [the frame-taking video producer](/quest/m2/video-producer.md); whichever - lands second merges main and keeps both changes. -- Callers hold these behind locks in moq-ffi and moq-c - (`rs/moq-ffi/src/{video,media,audio}.rs`, `rs/moq-c/src/{video,publish}.rs`): - move the producer out of its slot on finish and store the `Finished`, as - the audio encoder bindings already do. moq-cli, moq-gst, moq-rtsp, and - moq-boy follow. The bindings' own API does not change shape. -- Add a `compile_fail` doctest per type, as `container::Finished` has, that - writing after finish does not compile. -- Leave the internal `finish(&mut self)` helpers that are not producers - (`ts::demux`, `ts::video`, `mkv::ebml`, `ts::stats`). - -Public API: breaking for Rust: `finish` on the ten `moq_mux::codec` -importers, `moq_mux::import::{Track, TrackStream}`, and -`moq_video::encode::Producer`. Wire: none. - -## Related - -- [The frame-taking video producer](/quest/m2/video-producer.md) - renames the video type this changes -- [TS import reports typed outcomes](/quest/m2/ts-typed-outcomes.md) - changes the TS importers' `finish` error type diff --git a/quest/m2/ts-typed-outcomes.md b/quest/m2/ts-typed-outcomes.md index 50a345d8f32..2c728d93c88 100644 --- a/quest/m2/ts-typed-outcomes.md +++ b/quest/m2/ts-typed-outcomes.md @@ -75,4 +75,3 @@ change wording, exit codes do not. ## Related - [A multi-program TS import survives a source switch](/quest/m5/ts-multi-program-restart.md) - deferred; would add a restart value to `Programs` -- [Finishing an importer or the video producer returns a Finished handle](/quest/m2/finish-sweep.md) - the other change to importer signatures diff --git a/quest/m2/video-producer.md b/quest/m2/video-producer.md index 35a7d2ee21c..608faf2026a 100644 --- a/quest/m2/video-producer.md +++ b/quest/m2/video-producer.md @@ -51,8 +51,8 @@ For the PR: (`publish_capture`'s `Driver`), which then runs on it, so the capture path and a caller's own frames share one encode loop and one grant follower. Shape it after audio: an `Options` with `bandwidth`, `write(&Frame)`, and - `finish(self) -> Result` from the start (the - [finish sweep](/quest/m2/finish-sweep.md) converts the renamed type). + `finish(self) -> Result`, as the encoded publisher + being renamed already has. - Move moq-boy, moq-ffi, and moq-c onto it and delete their copies of the grant follower. A binding option the lifted type cannot express (moq-ffi's `lower` rendition for the simulcast ladder, `rs/moq-ffi/src/video.rs:370`) @@ -69,6 +69,5 @@ publisher is renamed). moq-ffi and moq-c keep their names. Wire: none. ## Related -- [Terminal operations consume](/quest/m2/finish-sweep.md) - gives the renamed type `finish(self)`; whichever lands second rebases - [One device selector](/quest/m2/native-media-config.md) - changes `encode::Config` in the same crate - [A published capture exposes its grant](/quest/m3/video-publish-grant.md) - adds a getter to the capture handle this runs on diff --git a/rs/moq-mux/src/codec/aac/import.rs b/rs/moq-mux/src/codec/aac/import.rs index a7f5c41e200..3e5a15c7f5e 100644 --- a/rs/moq-mux/src/codec/aac/import.rs +++ b/rs/moq-mux/src/codec/aac/import.rs @@ -65,7 +65,7 @@ impl Import { } /// [`finish`](Self::finish) the track in place, for an owner that keeps this importer. - pub(crate) fn end(&mut self) -> crate::Result<()> { + pub(crate) fn finish_in_place(&mut self) -> crate::Result<()> { self.track.end_with(None) } diff --git a/rs/moq-mux/src/codec/h264/import.rs b/rs/moq-mux/src/codec/h264/import.rs index 453e8f1c828..a6608444a4b 100644 --- a/rs/moq-mux/src/codec/h264/import.rs +++ b/rs/moq-mux/src/codec/h264/import.rs @@ -142,7 +142,7 @@ impl Import { } /// [`finish`](Self::finish) the track in place, for an owner that keeps this importer. - pub(crate) fn end(&mut self) -> crate::Result<()> { + pub(crate) fn finish_in_place(&mut self) -> crate::Result<()> { self.track.end_with(None) } diff --git a/rs/moq-mux/src/codec/h265/import.rs b/rs/moq-mux/src/codec/h265/import.rs index f111872d65c..adefa96daec 100644 --- a/rs/moq-mux/src/codec/h265/import.rs +++ b/rs/moq-mux/src/codec/h265/import.rs @@ -145,7 +145,7 @@ impl Import { } /// [`finish`](Self::finish) the track in place, for an owner that keeps this importer. - pub(crate) fn end(&mut self) -> crate::Result<()> { + pub(crate) fn finish_in_place(&mut self) -> crate::Result<()> { self.track.end_with(None) } diff --git a/rs/moq-mux/src/codec/legacy.rs b/rs/moq-mux/src/codec/legacy.rs index 4595ea280e5..ff15d6fccdf 100644 --- a/rs/moq-mux/src/codec/legacy.rs +++ b/rs/moq-mux/src/codec/legacy.rs @@ -168,7 +168,7 @@ impl Import { } /// [`finish`](Self::finish) the track in place, for an owner that keeps this importer. - pub(crate) fn end(&mut self) -> crate::Result<()> { + pub(crate) fn finish_in_place(&mut self) -> crate::Result<()> { self.track.end_with(None) } diff --git a/rs/moq-mux/src/codec/opus/import.rs b/rs/moq-mux/src/codec/opus/import.rs index 25dbd368ca5..6e9f6a9711e 100644 --- a/rs/moq-mux/src/codec/opus/import.rs +++ b/rs/moq-mux/src/codec/opus/import.rs @@ -58,7 +58,7 @@ impl Import { } /// [`finish`](Self::finish) the track in place, for an owner that keeps this importer. - pub(crate) fn end(&mut self) -> crate::Result<()> { + pub(crate) fn finish_in_place(&mut self) -> crate::Result<()> { self.track.end_with(None) } diff --git a/rs/moq-mux/src/container/ts/import.rs b/rs/moq-mux/src/container/ts/import.rs index 1409acc5ffb..a60204adc2f 100644 --- a/rs/moq-mux/src/container/ts/import.rs +++ b/rs/moq-mux/src/container/ts/import.rs @@ -3492,7 +3492,7 @@ impl Stream { let published = video::avc(split, import, assembly, true)?; *split = Default::default(); assembly.finish(); - import.end()?; + import.finish_in_place()?; return Ok(published); } Stream::H265 { @@ -3503,7 +3503,7 @@ impl Stream { let published = video::hevc(split, import, assembly, true)?; *split = Default::default(); assembly.finish(); - import.end()?; + import.finish_in_place()?; return Ok(published); } Stream::Opus(stream) => stream.finish()?, @@ -4179,7 +4179,7 @@ impl AacStream { self.reserved.take(); } if let Some(import) = &mut self.import { - import.end()?; + import.finish_in_place()?; } Ok(drained) } @@ -4244,7 +4244,7 @@ impl OpusStream { } fn finish(&mut self) -> anyhow::Result<()> { - Ok(self.import.end()?) + Ok(self.import.finish_in_place()?) } fn abort(self, err: moq_net::Error) { @@ -4788,7 +4788,7 @@ impl LegacyStream { self.reserved.take(); } if let Some(import) = &mut self.import { - import.end()?; + import.finish_in_place()?; } Ok(drained) }