From ed2a0b15f794786f4acbb1cf1b4635ab8f84a292 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 14:39:18 -0800 Subject: [PATCH 01/14] chore(quest): claim quest/m1/explicit-state/mux-gst.md Quest-Claim: a9b1aded15cfdbe3 From b616826f6bda21ebfc846d82494dc887574ec29e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 14:59:40 -0800 Subject: [PATCH 02/14] refactor(mux,gst): export source, gst pads and source readers hold one phase each ExportSource keeps its start options, wire format, priority and sibling instance inside SourceState. The gst sink pad's producer, the request pad's stream phase, the element's drain and the source's per-rendition reader are each one enum. Co-Authored-By: Claude Opus 5.5 --- rs/moq-gst/src/sink/imp.rs | 87 +++++---- rs/moq-gst/src/sink/pad.rs | 272 ++++++++++++++++++----------- rs/moq-gst/src/sink/request_pad.rs | 43 +++-- rs/moq-gst/src/source/imp.rs | 66 ++++--- rs/moq-mux/src/container/source.rs | 218 ++++++++++++----------- 5 files changed, 410 insertions(+), 276 deletions(-) diff --git a/rs/moq-gst/src/sink/imp.rs b/rs/moq-gst/src/sink/imp.rs index 5b405e54259..eb405a63c68 100644 --- a/rs/moq-gst/src/sink/imp.rs +++ b/rs/moq-gst/src/sink/imp.rs @@ -22,7 +22,7 @@ use hang::moq_net; use super::listed::{Listed, Watch}; use super::pad::{CapsOutcome, Names, ProducerOptions, PushOutcome, caps_supported}; -use super::request_pad::{MoqSinkPad, Notifications, PadLifecycle}; +use super::request_pad::{MoqSinkPad, Notifications, PadLifecycle, Phase}; use super::session::{ CAT, Completion, CompletionHandle, ConnectionStatus, RUNTIME, ResolvedSettings, Session, SessionRegistration, notify, sessions_structure, @@ -77,13 +77,21 @@ struct State { names: Names, /// How long a clean end keeps the finished broadcast up before its EOS. linger: Duration, - /// Whether the finished broadcast closed, so the EOS it owes may go out. - drained: bool, - /// The task serving the finished broadcast for its linger, aborted on stop. - lingering: Option, - /// Whether this publication's single EOS message already went out. One per publication, not per - /// entry to PLAYING: a finished publication is terminal here, so there is nothing to announce twice. - eos_delivered: bool, + /// How far a clean finish has wound the publication down. + drain: Drain, +} + +/// How far a cleanly finished publication has wound down, ending in its one EOS. +enum Drain { + /// The publication has not finished cleanly. + Open, + /// Serving the finished broadcast for its linger, until the task ends or a stop aborts it. + Lingering(tokio::task::AbortHandle), + /// The finished broadcast closed, so the EOS it owes may go out. + Closed, + /// The EOS went out. One per publication, not per entry to PLAYING: a finished publication is + /// terminal here, so there is nothing to announce twice. + Posted, } impl State { @@ -117,10 +125,10 @@ fn claim_eos(control: &mut Control) -> Posted { return Posted::Nothing; }; // Only a clean finish drains, so a drained publication ended with EOS. - if state.eos_delivered || !state.drained { + if !matches!(state.drain, Drain::Closed) { return Posted::Nothing; } - state.eos_delivered = true; + state.drain = Drain::Posted; Posted::Message { session: state.session.completion(), kind: MessageKind::Eos, @@ -484,10 +492,10 @@ impl ElementImpl for MoqSink { let mut control = self.control.lock().unwrap(); control.admissions.remove(sink_pad); let mut lifecycle = sink_pad.lifecycle(); - if lifecycle.releasing { + if lifecycle.is_released() { return; } - lifecycle.releasing = true; + lifecycle.phase = Phase::Released; if let Err(err) = lifecycle.media.finalize() { gst::warning!(CAT, "finalize on release {}: {err:?}", pad.name()); } @@ -496,7 +504,6 @@ impl ElementImpl for MoqSink { if self.obj().remove_pad(pad).is_ok() { self.obj().child_removed(pad, pad.name().as_str()); } - sink_pad.lifecycle().releasing = false; sink_pad.notify_changes(changes); let finished = { let mut control = self.control.lock().unwrap(); @@ -600,9 +607,7 @@ impl MoqSink { watch, names: Names::default(), linger, - drained: false, - lingering: None, - eos_delivered: false, + drain: Drain::Open, }); let pads = self.pads_locked(&control); let state = control.live.as_ref().unwrap(); @@ -614,7 +619,7 @@ impl MoqSink { let mut lifecycle = pad.lifecycle(); let changes = lifecycle.reset(); lifecycle.completion = Some(completion.clone()); - if !lifecycle.releasing { + if !lifecycle.is_released() { lifecycle.media.reserve(catalog, wall.clone(), &state.names); } changes @@ -683,7 +688,7 @@ impl MoqSink { gst::warning!(CAT, "finalize on stop: {err:?}"); } // Close the broadcast before reaping the session task. This also ends a linger early. - if let Some(lingering) = state.lingering.take() { + if let Drain::Lingering(lingering) = &state.drain { lingering.abort(); } state.route.broadcast().close(); @@ -725,7 +730,7 @@ impl MoqSink { let _rt = RUNTIME.enter(); let (outcome, changes) = { let mut lifecycle = pad.lifecycle(); - let Some(completion) = lifecycle.completion.as_ref().filter(|_| !lifecycle.releasing) else { + let Some(completion) = lifecycle.completion.as_ref().filter(|_| !lifecycle.is_released()) else { return Err(gst::FlowError::Flushing); }; // The element's own end comes before the pad's: a broken rendition is isolated so the others @@ -802,7 +807,7 @@ impl MoqSink { true => None, false => { let mut lifecycle = sink_pad.lifecycle(); - match lifecycle.releasing { + match lifecycle.is_released() { true => None, false => { lifecycle.media.invalidate(); @@ -826,7 +831,7 @@ impl MoqSink { && let Some(catalog) = state.catalog.as_ref() { let mut lifecycle = sink_pad.lifecycle(); - if lifecycle.releasing { + if lifecycle.is_released() { return false; } Some(observe_caps(state, catalog, sink_pad, &mut lifecycle, &caps)) @@ -847,7 +852,7 @@ impl MoqSink { let control = self.control.lock().unwrap(); let completion = control.live.as_ref().map(|state| state.session.completion()); let mut lifecycle = sink_pad.lifecycle(); - if !lifecycle.releasing { + if !lifecycle.is_released() { // The link is which publication the pad belongs to, not whether that publication is // still open. Dropping it after the end would answer the next buffer with Flushing // instead of the terminal result it earned. @@ -871,8 +876,8 @@ impl MoqSink { if let Some(state) = control.live.as_ref().filter(|state| state.is_open()) { let _rt = RUNTIME.enter(); let mut lifecycle = sink_pad.lifecycle(); - if !lifecycle.releasing { - lifecycle.ended = true; + if !lifecycle.is_released() { + lifecycle.phase = Phase::Eos; retired = lifecycle.retire_bandwidth(); if let Some(catalog) = &state.catalog && let Err(err) = lifecycle.media.end_unresolved(catalog) @@ -907,8 +912,8 @@ impl MoqSink { if let Some(state) = control.live.as_ref().filter(|state| state.is_open()) { let _rt = RUNTIME.enter(); let mut lifecycle = sink_pad.lifecycle(); - if !lifecycle.releasing { - lifecycle.ended = false; + if !lifecycle.is_released() { + lifecycle.phase = Phase::Streaming; if let Some(catalog) = &state.catalog { lifecycle.media.reserve(catalog, state.wall.clone(), &state.names); } @@ -929,10 +934,10 @@ impl MoqSink { Some(state) => { let _rt = RUNTIME.enter(); let mut lifecycle = sink_pad.lifecycle(); - match lifecycle.releasing { + match lifecycle.is_released() { true => None, false => { - lifecycle.ended = false; + lifecycle.phase = Phase::Streaming; lifecycle.media.flush(); let catalog = state.catalog.as_ref(); if let Some(catalog) = catalog { @@ -995,9 +1000,9 @@ impl MoqSink { let completion = control.live.as_ref().map(|state| state.session.completion()); let mut lifecycle = pad.lifecycle(); // Decided here, holding both locks. `owns_pad` cannot answer it: a pad stays the element's - // between being marked `releasing` and being removed, and a second look at the publication + // between being marked released and being removed, and a second look at the publication // would read a different instant than the one this confirmation ran in. - let admission = match lifecycle.releasing { + let admission = match lifecycle.is_released() { true => Admission::Rejected, false => { let failed = completion @@ -1028,7 +1033,7 @@ impl MoqSink { .into_iter() .filter_map(|pad| pad.downcast::().ok()) .collect::>(); - let all_ended = !pads.is_empty() && pads.iter().all(|pad| pad.lifecycle().ended); + let all_ended = !pads.is_empty() && pads.iter().all(|pad| pad.lifecycle().phase == Phase::Eos); if !all_ended || !state.is_open() { return Finished::default(); } @@ -1039,7 +1044,7 @@ impl MoqSink { let mut closed = Vec::new(); for pad in pads { let mut lifecycle = pad.lifecycle(); - if lifecycle.releasing || !self.owns_pad(&pad) { + if lifecycle.is_released() || !self.owns_pad(&pad) { continue; } let (track, result) = lifecycle.media.finish(); @@ -1101,7 +1106,7 @@ impl MoqSink { let linger = state.linger; if linger.is_zero() { drop(finished); - state.drained = true; + state.drain = Drain::Closed; return claim_eos(control); } gst::info!( @@ -1114,7 +1119,7 @@ impl MoqSink { self.obj().downgrade(), state.session.completion(), )); - state.lingering = Some(task.abort_handle()); + state.drain = Drain::Lingering(task.abort_handle()); Posted::Nothing } @@ -1123,7 +1128,12 @@ impl MoqSink { let message = { let mut control = self.control.lock().unwrap(); match control.live.as_mut() { - Some(state) if std::sync::Arc::ptr_eq(&state.session.completion(), session) => state.drained = true, + Some(state) + if std::sync::Arc::ptr_eq(&state.session.completion(), session) + && matches!(state.drain, Drain::Lingering(_)) => + { + state.drain = Drain::Closed + } _ => return, } claim_eos(&mut control) @@ -1214,7 +1224,7 @@ impl MoqSink { .completion .as_ref() .is_some_and(|completion| std::sync::Arc::ptr_eq(completion, session)); - (!lifecycle.releasing && belongs).then(|| PadUpdate { + (!lifecycle.is_released() && belongs).then(|| PadUpdate { pad: pad.clone(), changes: lifecycle.fail(format!("session failed: {error}")), }) @@ -2177,7 +2187,7 @@ mod tests { element.set_state(gst::State::Paused).expect("start session"); let pad = pad.downcast::().expect("MoqSinkPad"); - pad.lifecycle().releasing = true; + pad.lifecycle().phase = Phase::Released; sink.imp().control.lock().unwrap().admissions.insert(pad.clone()); let (admission, finished) = sink.imp().confirm_admission(&pad); sink.imp().publish_finished(finished); @@ -2188,7 +2198,6 @@ mod tests { "and it did so while the pad still belonged to the element, which is the window \ `owns_pad` cannot see" ); - pad.lifecycle().releasing = false; let _ = element.set_state(gst::State::Null); } @@ -2460,6 +2469,8 @@ mod tests { let start = kio::clock::now(); let finished = moq_mux::Linger::new([broadcast], track, linger); let lingering = tokio::spawn(linger_task(finished, sink.downgrade(), session)); + sink.imp().control.lock().unwrap().live.as_mut().expect("live session").drain = + Drain::Lingering(lingering.abort_handle()); kio::clock::sleep(linger - Duration::from_secs(1)).await; let mut late = consumer.track("video").unwrap().subscribe(None).await.unwrap(); diff --git a/rs/moq-gst/src/sink/pad.rs b/rs/moq-gst/src/sink/pad.rs index 806abe8e5d5..df865ebad32 100644 --- a/rs/moq-gst/src/sink/pad.rs +++ b/rs/moq-gst/src/sink/pad.rs @@ -96,9 +96,10 @@ impl Names { /// Keep finished rendition owners until a whole run's catalog has closed. #[must_use] +#[derive(Default)] pub(super) struct Closed { - track: Option, - /// The catalog `track` published in, kept open until the owner drops. + _track: Option, + /// The catalog `_track` published in, kept open until the owner drops. _catalog: Option, } @@ -292,23 +293,40 @@ pub enum PushOutcome { Failed(String), } +/// Where a pad's producer is in its life. +enum Producer { + /// No producer and no catalog slot. `caps` are the ones a finished producer was built from: CAPS + /// stay sticky across a flush, so a resumed stream rebuilds from them. + Idle { caps: Option }, + /// The requested pad gates the first catalog even before CAPS can name its rendition. + Reserved { + slot: Box, + caps: Option, + }, + /// CAPS built a producer, which publishes the pad's buffers. + Publishing(Box), + /// A producer build or write rejected this pad's caps or bitstream; further buffers are dropped + /// and the track stays finalized. Isolated to the pad, so the session and other pads keep going. + /// The reason is not kept here: whichever call failed returns it. + Failed, +} + +/// A live producer and what it was built from. +struct Publishing { + track: Sink, + /// The catalog `track` publishes in. + catalog: moq_mux::catalog::Producer, + caps: gst::Caps, + /// Whether `track` has a configured name, which may be requested again. A generated one never is. + named: bool, +} + /// One sink pad's producer plus its timeline policy. pub struct Pad { - /// The requested pad gates the first catalog even before CAPS can name its rendition. - reserved: Option, + producer: Producer, wall: Option>, /// The run's, once reserved; until then this pad's own, which still covers renegotiation. names: Names, - track: Option, - /// The catalog `track` publishes in, set with it. - catalog: Option, - /// Whether `track` has a configured name, which may be requested again. A generated one never is. - named: bool, - caps: Option, - /// Set once a producer build rejects this pad's caps or bitstream; further buffers are dropped and - /// the track stays finalized. Isolated to the pad, so the session and other pads keep going. The - /// reason is not kept here: whichever call failed returns it. - failed: bool, state: PadState, segment_info: Option, /// Kept only to map a buffer PTS to a running time. @@ -322,14 +340,9 @@ impl Pad { /// A fresh pad with no caps, no segment, and no producer yet. pub fn new() -> Self { Self { - reserved: None, + producer: Producer::Idle { caps: None }, wall: None, names: Names::default(), - track: None, - catalog: None, - named: false, - caps: None, - failed: false, state: PadState::NoSegment, segment_info: None, segment: None, @@ -346,15 +359,39 @@ impl Pad { ) { self.wall = Some(wall); self.names = names.clone(); - if self.reserved.is_none() && self.track.is_none() && !self.failed { - self.reserved = Some(catalog.reserve()); + if let Producer::Idle { caps } = &mut self.producer { + self.producer = Producer::Reserved { + slot: Box::new(catalog.reserve()), + caps: caps.take(), + }; + } + } + + /// The live producer's track, if any. + fn track(&self) -> Option<&Sink> { + match &self.producer { + Producer::Publishing(publishing) => Some(&publishing.track), + _ => None, + } + } + + /// The live producer's media track, if it is one. + fn media_mut(&mut self) -> Option<&mut Media> { + match &mut self.producer { + Producer::Publishing(publishing) => match &mut publishing.track { + Sink::Media(media) => Some(media), + _ => None, + }, + _ => None, } } /// An ended pad can no longer resolve its config, but resolved tracks keep their usual lifetime. pub(super) fn end_unresolved(&mut self, catalog: &moq_mux::catalog::Producer) -> Result<()> { - self.reserved.take(); - if let Some(Sink::Media(media)) = &self.track { + if let Producer::Reserved { caps, .. } = &mut self.producer { + self.producer = Producer::Idle { caps: caps.take() }; + } + if let Some(Sink::Media(media)) = self.track() { // Read current state, not the gated wire snapshot. An untouched guard emits nothing and // avoids cloning every rendition. Drop it before finalize takes the catalog lock again. let mut catalog = catalog.clone(); @@ -377,15 +414,15 @@ impl Pad { /// The caps to rebuild from when [`end_unresolved`](Self::end_unresolved) finished this pad and its /// stream resumes: CAPS stay sticky across a flush, so none arrives to rebuild it. pub(super) fn resumable_caps(&self) -> Option { - match (&self.track, self.failed) { - (None, false) => self.caps.clone(), - _ => None, + match &self.producer { + Producer::Idle { caps } | Producer::Reserved { caps, .. } => caps.clone(), + Producer::Publishing(_) | Producer::Failed => None, } } /// True once this pad has been invalidated by a bad caps/bitstream; the caller drops its buffers. pub fn is_failed(&self) -> bool { - self.failed + matches!(self.producer, Producer::Failed) } /// A watch-only handle to the active track's subscriber demand, once viewers can find the track. @@ -395,7 +432,7 @@ impl Pad { /// would keep it out of the catalog for good. Opaque data has no catalog entry by design; its /// subscribers name the track directly, so its demand is live from negotiation. pub(super) fn demand(&self, listed: &Listed) -> Option { - let track = self.track.as_ref()?; + let track = self.track()?; match track { Sink::Opaque(_) => {} Sink::Media(_) | Sink::Text(_) if listed.contains(&track.name()) => {} @@ -413,20 +450,32 @@ impl Pad { catalog: &moq_mux::catalog::Producer, options: ProducerOptions<'_>, ) -> CapsOutcome { - if self.failed { - return CapsOutcome::Unchanged; - } - if self.track.is_some() - && let Some(caps) = &self.caps - && same_importer(caps, options.caps) - { - self.caps = Some(options.caps.clone()); - return CapsOutcome::Unchanged; + match &mut self.producer { + Producer::Failed => return CapsOutcome::Unchanged, + Producer::Publishing(publishing) if same_importer(&publishing.caps, options.caps) => { + publishing.caps = options.caps.clone(); + return CapsOutcome::Unchanged; + } + _ => {} } - let reserved = self.reserved.take().unwrap_or_else(|| catalog.reserve()); - match self.build(broadcast, reserved, options) { - Ok(name) => { - self.catalog = Some(catalog.clone()); + let slot = match std::mem::replace(&mut self.producer, Producer::Idle { caps: None }) { + Producer::Reserved { slot, .. } => *slot, + // A live producer stays until the build finalizes it. + previous => { + self.producer = previous; + catalog.reserve() + } + }; + let caps = options.caps.clone(); + let named = options.requested.is_some(); + match self.build(broadcast, slot, options) { + Ok((name, track)) => { + self.producer = Producer::Publishing(Box::new(Publishing { + track, + catalog: catalog.clone(), + caps, + named, + })); CapsOutcome::Active(name) } Err(err) => { @@ -442,7 +491,7 @@ impl Pad { broadcast: &moq_net::broadcast::Producer, reserved: moq_mux::catalog::Reserved, options: ProducerOptions<'_>, - ) -> Result { + ) -> Result<(String, Sink)> { let ProducerOptions { container, caps, @@ -452,7 +501,6 @@ impl Pad { // Renegotiation to new content: finalize the previous producer before replacing it (closed once, // not abandoned), so its name has ended and the replacement takes a fresh one. self.finalize()?; - self.named = requested.is_some(); let requested = requested.map(|name| { let claimed = self.names.claim(name); if claimed != name { @@ -475,9 +523,7 @@ impl Pad { let info = moq_net::track::Info::default() .with_timescale(moq_net::Timescale::MICRO) .with_max_age(std::time::Duration::from_secs(5)); - self.track = Some(Sink::Opaque(Box::new(request.accept(info)))); - self.caps = Some(caps.clone()); - return Ok(name); + return Ok((name, Sink::Opaque(Box::new(request.accept(info))))); } let mut broadcast = broadcast.clone(); // Every codec converges on one import::Track; only the caps -> importer construction differs. The @@ -489,14 +535,8 @@ impl Pad { // text with a presentation time, so there is nothing to parse, only a text rendition to declare. if structure.name().as_str() == "text/x-raw" { let name = Self::track_name(&broadcast, requested, ".vtt"); - self.track = Some(Sink::Text(Box::new(Self::reserve_text( - &mut broadcast, - reserved, - name.clone(), - structure, - )?))); - self.caps = Some(caps.clone()); - return Ok(name); + let text = Self::reserve_text(&mut broadcast, reserved, name.clone(), structure)?; + return Ok((name, Sink::Text(Box::new(text)))); } let mut pre_skip = None; @@ -618,16 +658,15 @@ impl Pad { } other => anyhow::bail!("unsupported caps: {other}"), }; - self.track = Some(Sink::Media(Box::new(Media { + let media = Media { track, audio, group_start: None, discontinuity: false, keyframe: !audio, pre_skip, - }))); - self.caps = Some(caps.clone()); - Ok(name) + }; + Ok((name, Sink::Media(Box::new(media)))) } /// The name this pad publishes under: the one it was given, else a generated `0{suffix}`. @@ -724,7 +763,7 @@ impl Pad { if let Err(err) = self.finalize() { gst::warning!(CAT, "finalize on failed pad: {err:?}"); } - self.failed = true; + self.producer = Producer::Failed; } /// Invalidate this producer after a failure detected outside the codec importer. @@ -754,7 +793,7 @@ impl Pad { let segment = segment.downcast::().ok(); if self.segment.is_some() && self.segment != segment - && let Some(Sink::Media(media)) = self.track.as_mut() + && let Some(media) = self.media_mut() { media.discontinuity = true; } @@ -785,7 +824,7 @@ impl Pad { /// Restart measurement on the next frame while retaining the current segment. pub fn discontinuity(&mut self) { if self.segment.is_some() - && let Some(Sink::Media(media)) = self.track.as_mut() + && let Some(media) = self.media_mut() { media.discontinuity = true; } @@ -795,30 +834,16 @@ impl Pad { /// decode order and B-frames carry non-monotonic presentation timestamps, so a PTS regression is /// normal reordering. Timeline breaks are caught at the SEGMENT level (the `Invalid` state). fn frame_timestamp(&self, pts: Option) -> Result { - match self.state { - PadState::Active => { - // to_running_time_full is signed: a buffer before the segment returns Negative, which - // frame_micros drops; to_running_time would instead clip it to None and lose the reason. - let running_time = self - .segment - .as_ref() - .zip(pts) - .and_then(|(segment, pts)| segment.to_running_time_full(pts)) - .and_then(signed_nanos); - frame_micros(running_time) - } - PadState::NoSegment => Err("buffer before a valid SEGMENT"), - PadState::Invalid => Err("buffer on an invalidated timeline"), - } + frame_timestamp(self.state, self.segment.as_ref(), pts) } /// Place the run on the wall clock before its first valid timestamp can reach an importer. pub(super) fn place_wall(&self, buffer: &gst::BufferRef, sample: super::wall::Sample) -> Result<()> { let Some(wall) = &self.wall else { return Ok(()) }; - if self.failed || self.track.is_none() { + let Some(track) = self.track() else { return Ok(()); - } - let timestamp = if matches!(self.track, Some(Sink::Opaque(_))) + }; + let timestamp = if matches!(track, Sink::Opaque(_)) && buffer.pts().is_none() && self.state == PadState::Active { @@ -843,12 +868,9 @@ impl Pad { /// The PTS `buffer` publishes at: its own, except an Opus packet's, which moves onto hang's /// timeline (see [`PreSkip`]). pub(super) fn timeline_pts(&mut self, buffer: &gst::BufferRef) -> Result> { - match &mut self.track { - Some(Sink::Media(media)) if !self.failed => match &mut media.pre_skip { - Some(pre_skip) => pre_skip.pts(buffer), - None => Ok(buffer.pts()), - }, - _ => Ok(buffer.pts()), + match self.media_mut().and_then(|media| media.pre_skip.as_mut()) { + Some(pre_skip) => pre_skip.pts(buffer), + None => Ok(buffer.pts()), } } @@ -859,24 +881,25 @@ impl Pad { duration: Option, current_running_time: Option, ) -> std::result::Result { - if self.failed { - return Ok(PushOutcome::Dropped); - } - if self.track.is_none() { - gst::warning!(CAT, "dropping buffer received before caps"); - return Ok(PushOutcome::Dropped); - } - let opaque = matches!(self.track.as_ref(), Some(Sink::Opaque(_))); + let publishing = match &mut self.producer { + Producer::Failed => return Ok(PushOutcome::Dropped), + Producer::Publishing(publishing) => publishing, + Producer::Idle { .. } | Producer::Reserved { .. } => { + gst::warning!(CAT, "dropping buffer received before caps"); + return Ok(PushOutcome::Dropped); + } + }; + let opaque = matches!(publishing.track, Sink::Opaque(_)); let timestamp = if opaque && pts.is_none() && self.state == PadState::Active { let running_time = current_running_time.ok_or("no current running time for unstamped opaque data")?; let nanos = i64::try_from(running_time.nseconds()).map_err(|_| "current running time is out of range")?; frame_micros(Some(nanos)) } else { - self.frame_timestamp(pts) + frame_timestamp(self.state, self.segment.as_ref(), pts) }; match timestamp { Ok(micros) => { - let result: Result<()> = match self.track.as_mut().expect("track present") { + let result: Result<()> = match &mut publishing.track { Sink::Media(media) => match media.write(&data, micros) { Ok(false) => { gst::debug!( @@ -943,27 +966,64 @@ impl Pad { /// Finish once, retaining rendition owners so closing a run cannot publish their removal. pub(super) fn finish(&mut self) -> (Closed, Result) { - self.reserved.take(); - let mut closed = Closed { - track: self.track.take(), - _catalog: self.catalog.take(), - }; - let Some(track) = closed.track.as_mut() else { - return (closed, Ok(false)); + let publishing = match std::mem::replace(&mut self.producer, Producer::Idle { caps: None }) { + Producer::Publishing(publishing) => publishing, + Producer::Reserved { caps, .. } => { + self.producer = Producer::Idle { caps }; + return (Closed::default(), Ok(false)); + } + unchanged => { + self.producer = unchanged; + return (Closed::default(), Ok(false)); + } }; - let result = match track { + let Publishing { + mut track, + catalog, + caps, + named, + } = *publishing; + let result = match &mut track { Sink::Media(media) => media.track.finish().map_err(anyhow::Error::from), Sink::Text(text) => text.producer.finish().map_err(anyhow::Error::from), Sink::Opaque(producer) => producer.clone().finish().map_err(anyhow::Error::from), }; - if self.named { + if named { self.names.end(track.name()); } - self.failed |= result.is_err(); + self.producer = match result { + Ok(()) => Producer::Idle { caps: Some(caps) }, + Err(_) => Producer::Failed, + }; + let closed = Closed { + _track: Some(track), + _catalog: Some(catalog), + }; (closed, result.map(|()| true)) } } +/// Map `pts` onto the timeline `state` and `segment` anchor, in microseconds. +fn frame_timestamp( + state: PadState, + segment: Option<&gst::FormattedSegment>, + pts: Option, +) -> Result { + match state { + PadState::Active => { + // to_running_time_full is signed: a buffer before the segment returns Negative, which + // frame_micros drops; to_running_time would instead clip it to None and lose the reason. + let running_time = segment + .zip(pts) + .and_then(|(segment, pts)| segment.to_running_time_full(pts)) + .and_then(signed_nanos); + frame_micros(running_time) + } + PadState::NoSegment => Err("buffer before a valid SEGMENT"), + PadState::Invalid => Err("buffer on an invalidated timeline"), + } +} + /// The mapping fields on an `audio/x-opus` caps structure. Absent fields stay absent: /// a present field of the wrong type is refused rather than treated as missing. struct OpusDeclared { diff --git a/rs/moq-gst/src/sink/request_pad.rs b/rs/moq-gst/src/sink/request_pad.rs index 7291f38d478..06ffe44f4f5 100644 --- a/rs/moq-gst/src/sink/request_pad.rs +++ b/rs/moq-gst/src/sink/request_pad.rs @@ -61,13 +61,25 @@ struct Bandwidth { watch_task: Option>, } +/// Where a request pad's stream is, from its request to its release. +#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)] +pub(super) enum Phase { + /// Its stream is flowing, or has yet to start. + #[default] + Streaming, + /// Its stream reached EOS; a flush or a new stream starts it again. Unlike [`Status::Ended`], the + /// track may still be live: the element finalizes the tracks once every pad is here. + Eos, + /// Being released, or released. Nothing moves it out again. + Released, +} + /// Everything owned by one request pad, protected by one lock. pub(super) struct PadLifecycle { settings: Settings, pub(super) media: Pad, bandwidth: Option, - pub(super) ended: bool, - pub(super) releasing: bool, + pub(super) phase: Phase, /// This pad's link to its publication. `None` is no live session for the pad, which is why a buffer /// arriving before one exists is refused rather than dropped. pub(super) completion: Option, @@ -79,8 +91,7 @@ impl Default for PadLifecycle { settings: Settings::default(), media: Pad::new(), bandwidth: None, - ended: false, - releasing: false, + phase: Phase::Streaming, completion: None, } } @@ -219,7 +230,12 @@ impl Settings { } impl PadLifecycle { - /// The configured track name while this pad is not releasing. + /// Whether the pad is being released, or was: nothing changes it any more. + pub(super) fn is_released(&self) -> bool { + self.phase == Phase::Released + } + + /// The configured track name. pub(super) fn requested(&self) -> Option<&str> { self.settings.requested.as_deref() } @@ -276,8 +292,8 @@ impl PadLifecycle { pad: &MoqSinkPad, listed: &Listed, ) -> Option { - // An ended pad reports nothing until it resumes; a failed one has no track left. - if self.ended || self.releasing { + // An ended pad reports nothing until it resumes; a released one has no track left. + if self.phase != Phase::Streaming { return None; } self.restore_bandwidth(allocator, pad, listed) @@ -345,7 +361,9 @@ impl PadLifecycle { let status = self.settings.set_status(Status::Pending); let demand = self.bandwidth.take().is_some(); self.media = Pad::new(); - self.ended = false; + if self.phase == Phase::Eos { + self.phase = Phase::Streaming; + } self.completion = None; Notifications { track, @@ -435,7 +453,7 @@ impl ObjectImpl for MoqSinkPadImp { fn set_property(&self, _id: usize, value: &glib::Value, pspec: &glib::ParamSpec) { let mut lifecycle = self.lifecycle.lock().unwrap(); - if lifecycle.releasing { + if lifecycle.is_released() { gst::warning!( CAT, obj = self.obj(), @@ -528,13 +546,12 @@ impl MoqSinkPad { } } - /// Reset a detached pad without asking GStreamer to remove it twice. + /// Reset and release a detached pad without asking GStreamer to remove it twice. pub(super) fn reset_detached(&self) { let changes = { let mut lifecycle = self.lifecycle(); - let changes = lifecycle.reset(); - lifecycle.releasing = false; - changes + lifecycle.phase = Phase::Released; + lifecycle.reset() }; self.notify_changes(changes); } diff --git a/rs/moq-gst/src/source/imp.rs b/rs/moq-gst/src/source/imp.rs index 0105f7ef25f..d5f0d2c2dca 100644 --- a/rs/moq-gst/src/source/imp.rs +++ b/rs/moq-gst/src/source/imp.rs @@ -1299,10 +1299,26 @@ struct Current { /// A rendition a [`Follower`] plays. struct Entry { shape: Shape, - /// Reading the current instance, if it is. - reader: Option, + reading: Reading, +} + +/// Whether a rendition reads the current instance. +enum Reading { + /// No reader: no instance yet, or one that does not serve it. + Idle, + Reader(ReaderHandle), /// Delisted while reading: plays out the instance it reads, then leaves. - draining: bool, + Draining(ReaderHandle), +} + +impl Reading { + /// The running reader, draining or not. + fn reader(&self) -> Option<&ReaderHandle> { + match self { + Reading::Idle => None, + Reading::Reader(reader) | Reading::Draining(reader) => Some(reader), + } + } } /// A running [`Reader`], cancelled when dropped. @@ -1430,23 +1446,32 @@ impl Follower { // warmup for the next one. let reshaped = shape != entry.shape; entry.shape = shape; - if reshaped { - entry.reader = None; - fresh.insert(rendition.clone()); - } - entry.draining = false; + entry.reading = match std::mem::replace(&mut entry.reading, Reading::Idle) { + _ if reshaped => { + fresh.insert(rendition.clone()); + Reading::Idle + } + Reading::Reader(reader) | Reading::Draining(reader) => Reading::Reader(reader), + Reading::Idle => Reading::Idle, + }; true } // A delisted rendition plays out the instance it reads, then leaves. One that never // took its pad, or that is disabled or now reads another broadcast, stops now. None => { - entry.draining = !pads.is_listed(rendition) + let drains = !pads.is_listed(rendition) && !disabled.contains(rendition) && entry - .reader - .as_ref() + .reading + .reader() .is_some_and(|reader| reader.live.load(Ordering::Acquire)); - entry.draining + if !drains { + return false; + } + if let Reading::Reader(reader) = std::mem::replace(&mut entry.reading, Reading::Idle) { + entry.reading = Reading::Draining(reader); + } + true } }); for (rendition, shape) in wanted { @@ -1455,8 +1480,7 @@ impl Follower { rendition, Entry { shape, - reader: None, - draining: false, + reading: Reading::Idle, }, ); } @@ -1537,9 +1561,10 @@ impl Follower { /// Stop reading the instance. A draining rendition leaves with it. fn idle(&mut self) { - self.renditions.retain(|_, entry| !entry.draining); + self.renditions + .retain(|_, entry| !matches!(entry.reading, Reading::Draining(_))); for entry in self.renditions.values_mut() { - entry.reader = None; + entry.reading = Reading::Idle; } } @@ -1557,7 +1582,7 @@ impl Follower { return; }; for (rendition, entry) in &mut self.renditions { - if entry.reader.is_none() && only(rendition) && serves(instance, entry.shape.instance.as_ref()) { + if matches!(entry.reading, Reading::Idle) && only(rendition) && serves(instance, entry.shape.instance.as_ref()) { self.next_id += 1; let (cancel, cancelled) = watch::channel(false); let live = Arc::new(AtomicBool::new(false)); @@ -1580,7 +1605,7 @@ impl Follower { }), RUNTIME.handle(), ); - entry.reader = Some(ReaderHandle { id, live, cancel }); + entry.reading = Reading::Reader(ReaderHandle { id, live, cancel }); } } } @@ -1590,11 +1615,10 @@ impl Follower { let Some(entry) = self.renditions.get_mut(&rendition) else { return; }; - if entry.reader.as_ref().is_none_or(|reader| reader.id != id) { + if entry.reading.reader().is_none_or(|reader| reader.id != id) { return; } - entry.reader = None; - if entry.draining { + if let Reading::Draining(_) = std::mem::replace(&mut entry.reading, Reading::Idle) { self.renditions.remove(&rendition); } else if let Exit::Unlisted = exit && self.playback.session.pads.is_listed(&rendition) diff --git a/rs/moq-mux/src/container/source.rs b/rs/moq-mux/src/container/source.rs index 6380781b2a8..fa80f3324c6 100644 --- a/rs/moq-mux/src/container/source.rs +++ b/rs/moq-mux/src/container/source.rs @@ -58,17 +58,41 @@ impl VideoTransform { /// A subscription that resolves on first poll, then the live consumer. enum SourceState { /// Waiting for the target broadcast (the catalog broadcast, or a cross-broadcast - /// reference) to resolve; the track (by name) is subscribed once it does. - Requesting(crate::Binding, String), + /// reference) to resolve; [`Target::track`] is subscribed once it does. + Requesting { binding: crate::Binding, start: Start }, /// Waiting for the subscription to resolve (blocks on the publisher's SUBSCRIBE_OK). - Subscribing(kio::Pending), + Subscribing { + pending: Box>, + media: HangContainer, + live: bool, + instance: Option, + }, /// The resolved consumer, reading frames. Boxed because it's much larger than - /// the `Subscribing` variant (clippy `large_enum_variant`). - Active(Box>), - /// The sibling instance it read went, and its rendition with it. + /// the other variants (clippy `large_enum_variant`). + Active(Box), + /// The track ended, the sibling instance it read went, or the source was stopped. Ended, } +/// How a source subscribes, fixed before its first poll. +struct Start { + /// Wire format the consumer decodes. + media: HangContainer, + /// Start at the newest group, rather than the oldest the max delay still reaches. + live: bool, + /// Read only groups after this one, so a resubscription skips groups already read. + after: Option, +} + +/// A resolved subscription. +struct Active { + consumer: Consumer, + /// Keeps the subscription's priority registered while it reads. + _priority: crate::source::Priority, + /// The sibling broadcast the rendition reads: its end ends the rendition. + instance: Option, +} + /// The track a source reads: its broadcast's path, the instance that broadcast must have, and /// the track's name there. #[derive(Clone, Debug, PartialEq, Eq)] @@ -88,9 +112,15 @@ impl Target { }) } - fn request(&self, source: &crate::Source) -> SourceState { - let binding = source.request_path(&self.path, self.instance.as_ref()); - SourceState::Requesting(binding, self.track.clone()) + fn request(&self, source: &crate::Source, media: HangContainer) -> SourceState { + SourceState::Requesting { + binding: source.request_path(&self.path, self.instance.as_ref()), + start: Start { + media, + live: false, + after: None, + }, + } } } @@ -118,16 +148,9 @@ pub(crate) struct ExportSource { /// The rendition's ID in the catalog. name: String, source: crate::Source, - priority_control: Option, target: Target, state: SourceState, - /// Wire format, consumed when the subscription resolves into a consumer. - media: Option, max_delay: std::time::Duration, - /// Start at the newest group, rather than the oldest the max delay still reaches. - live: bool, - /// Read only groups after this one, so a resubscription skips groups already read. - after: Option, transform: Option, /// Resolved codec configuration record (avcC / hvcC / AudioSpecificConfig / /// OpusHead). Some once the codec config is available - from the catalog @@ -155,8 +178,6 @@ pub(crate) struct ExportSource { delivered: Option, /// Set while continuing another source, until the first sync frame past what it delivered. splice: Option, - /// The sibling broadcast the rendition reads, once resolved: its end ends the rendition. - instance: Option, } impl ExportSource { @@ -280,13 +301,9 @@ impl ExportSource { Self { name: name.to_string(), source: source.clone(), - priority_control: None, - state: target.request(source), + state: target.request(source, media), target, - media: Some(media), max_delay, - live: false, - after: None, transform: None, description: None, video_codec: None, @@ -301,7 +318,6 @@ impl ExportSource { latest: None, delivered: None, splice: None, - instance: None, } } @@ -340,9 +356,9 @@ impl ExportSource { /// that still does fails with [`Error::RenditionRewound`](crate::Error::RenditionRewound). pub(crate) fn resuming(mut self, resume: &Resume) -> Self { if resume.target == self.target { - self.after = resume.group; + self.start().after = resume.group; } else { - self.live = true; + self.start().live = true; self.splice = resume.latest.map(|read| Splice { read, group: None }); } self.latest = resume.latest; @@ -354,15 +370,24 @@ impl ExportSource { /// hop drops each group a newer one supersedes, and raising it later cannot recover the /// groups that follow the edge. pub fn live(mut self) -> Self { - self.live = true; + self.start().live = true; self } + /// The subscription options a builder sets. Each builder consumes a source no poll has + /// moved out of [`SourceState::Requesting`], since only the constructors hand one out. + fn start(&mut self) -> &mut Start { + match &mut self.state { + SourceState::Requesting { start, .. } => start, + _ => unreachable!("configured after polling"), + } + } + /// The group sequence of the last frame read, or None until the subscription resolves. /// Meaningful only once a frame was read. pub(crate) fn group(&self) -> Option { match &self.state { - SourceState::Active(consumer) => Some(consumer.group()), + SourceState::Active(active) => Some(active.consumer.group()), _ => None, } } @@ -451,7 +476,7 @@ impl ExportSource { /// Receive group handles and wait for all input bytes while frame delivery is backpressured. pub fn poll_received(&mut self, waiter: &kio::Waiter) -> Poll<()> { match &mut self.state { - SourceState::Active(consumer) => consumer.poll_received(waiter), + SourceState::Active(active) => active.consumer.poll_received(waiter), SourceState::Ended => Poll::Ready(()), _ => Poll::Pending, } @@ -504,73 +529,73 @@ impl ExportSource { /// Read the track's normalized media or a clean group boundary. fn poll_track(&mut self, waiter: &kio::Waiter) -> Poll>> { - if matches!(self.state, SourceState::Ended) { - return Poll::Ready(Ok(None)); - } - // Resolve a cross-broadcast reference into a broadcast before subscribing. - if matches!(self.state, SourceState::Requesting(..)) { - let (broadcast, name, sibling) = { - let SourceState::Requesting(pending, name) = &self.state else { - unreachable!("just matched Requesting"); - }; - (ready!(pending.poll_broadcast(waiter))?, name.clone(), pending.sibling()) - }; - if sibling { - self.instance = Some(broadcast.clone()); - } + if let SourceState::Requesting { binding, start } = &self.state { + let broadcast = ready!(binding.poll_broadcast(waiter))?; + let instance = binding.sibling().then(|| broadcast.clone()); let mut subscription = moq_net::track::Subscription::default() .with_delay(moq_net::track::Delay::default().with_max(self.max_delay)); - if let Some(after) = self.after { + if let Some(after) = start.after { subscription = subscription.with_range((Bound::Excluded(after), Bound::Unbounded)); } - let track = match broadcast.track(&name) { + let track = match broadcast.track(&self.target.track) { Ok(track) => track, - Err(_) if self.instance_ended(waiter) => return self.end(), + Err(_) if instance.as_ref().is_some_and(|i| i.poll_closed(waiter).is_ready()) => return self.end(), Err(err) => return Poll::Ready(Err(err.into())), }; - self.state = SourceState::Subscribing(track.subscribe(self.source.subscription(subscription))); + let pending = Box::new(track.subscribe(self.source.subscription(subscription))); + let SourceState::Requesting { start, .. } = std::mem::replace(&mut self.state, SourceState::Ended) else { + unreachable!("just matched Requesting"); + }; + self.state = SourceState::Subscribing { + pending, + media: start.media, + live: start.live, + instance, + }; } // Resolve the subscription before reading any frames. - if matches!(self.state, SourceState::Subscribing(_)) { - // Scope the `pending` borrow so it ends before we touch `self.media`/`self.state`. - let track = { - let SourceState::Subscribing(pending) = &self.state else { - unreachable!("just matched Subscribing"); - }; - match pending.poll_ok(waiter) { - Poll::Ready(Ok(track)) => track, - Poll::Ready(Err(_)) | Poll::Pending if self.instance_ended(waiter) => return self.end(), - Poll::Ready(Err(err)) => return Poll::Ready(Err(err.into())), - Poll::Pending => return Poll::Pending, + if let SourceState::Subscribing { pending, instance, .. } = &self.state { + let track = match pending.poll_ok(waiter) { + Poll::Ready(Ok(track)) => track, + Poll::Ready(Err(_)) | Poll::Pending if instance.as_ref().is_some_and(|i| i.poll_closed(waiter).is_ready()) => { + return self.end(); } + Poll::Ready(Err(err)) => return Poll::Ready(Err(err.into())), + Poll::Pending => return Poll::Pending, + }; + let priority = self.source.control(track.control())?; + let SourceState::Subscribing { + media, live, instance, .. + } = std::mem::replace(&mut self.state, SourceState::Ended) + else { + unreachable!("just matched Subscribing"); }; - let media = self - .media - .take() - .expect("media present until the subscription resolves"); - self.priority_control = Some(self.source.control(track.control())?); let consumer = Consumer::new(track, media); - let consumer = match self.live { + let consumer = match live { true => consumer.live(), false => consumer, }; - self.state = SourceState::Active(Box::new(consumer)); + self.state = SourceState::Active(Box::new(Active { + consumer, + _priority: priority, + instance, + })); } loop { // Scope the consumer borrow to the poll so `self.transform` / // `self.refresh_description` can borrow `self` afterwards. let (frame, arrived) = { - let SourceState::Active(consumer) = &mut self.state else { - unreachable!("subscription resolved into an Active consumer"); + let SourceState::Active(active) = &mut self.state else { + return Poll::Ready(Ok(None)); }; + let consumer = &mut active.consumer; let item = match consumer.poll_item(waiter) { Poll::Ready(Ok(item)) => item, // Only an orderly shutdown of the instance is its end: malformed media or a - // failed transport still fails the export. The field, not `instance_ended`, so - // the borrow stays off the consumer. + // failed transport still fails the export. Poll::Ready(Err(crate::Error::Moq( moq_net::Error::Cancel | moq_net::Error::Closed @@ -579,7 +604,7 @@ impl ExportSource { | moq_net::Error::Session(moq_net::SessionError::Cancel), ))) | Poll::Pending - if self + if active .instance .as_ref() .is_some_and(|instance| instance.poll_closed(waiter).is_ready()) => @@ -630,11 +655,7 @@ impl ExportSource { self.cuts += u64::from(std::mem::take(&mut self.open)); return Poll::Ready(Ok(Some(Event::Cut { observed }))); } - None => { - self.priority_control = None; - self.finish_ends(); - return Poll::Ready(Ok(None)); - } + None => return self.end(), } }; @@ -669,29 +690,29 @@ impl ExportSource { } } - /// Whether the sibling broadcast this rendition reads has stopped serving, registering - /// `waiter` for when it does. Its track stalling or failing then is that instance's end, - /// which ends the rendition rather than the export once what it delivered is read; following - /// the instance that replaces it is the export's own call. - fn instance_ended(&self, waiter: &kio::Waiter) -> bool { - self.instance - .as_ref() - .is_some_and(|instance| instance.poll_closed(waiter).is_ready()) - } - /// Release a replaced instance's subscription while keeping its resolved metadata. pub(crate) fn stop(&mut self) { self.finish_ends(); self.state = SourceState::Ended; - self.priority_control = None; - self.instance = None; } - /// End the rendition with its instance. + /// Whether the sibling broadcast this rendition reads has stopped serving. + #[cfg(test)] + fn instance_ended(&self, waiter: &kio::Waiter) -> bool { + let instance = match &self.state { + SourceState::Subscribing { instance, .. } => instance.as_ref(), + SourceState::Active(active) => active.instance.as_ref(), + _ => None, + }; + instance.is_some_and(|instance| instance.poll_closed(waiter).is_ready()) + } + + /// End the rendition: its track ended, or the sibling instance it read went. Its track + /// stalling or failing then is that instance's end, which ends the rendition rather than the + /// export once what it delivered is read; following the instance that replaces it is the + /// export's own call. fn end(&mut self) -> Poll>> { - self.finish_ends(); - self.state = SourceState::Ended; - self.priority_control = None; + self.stop(); Poll::Ready(Ok(None)) } @@ -1355,14 +1376,15 @@ mod tests { .produce() .create_track("audio", hang::container::track_info(hang::catalog::PRIORITY.audio)) .unwrap(); - let consumer = Consumer::new( - track.subscribe( - moq_net::track::Subscription::default() - .with_delay(moq_net::track::Delay::default().with_max(Duration::from_secs(10))), - ), - HangContainer::Legacy(crate::container::Kind::Audio), + let subscribed = track.subscribe( + moq_net::track::Subscription::default() + .with_delay(moq_net::track::Delay::default().with_max(Duration::from_secs(10))), ); - export.state = SourceState::Active(Box::new(consumer)); + export.state = SourceState::Active(Box::new(Active { + _priority: export.source.control(subscribed.control()).unwrap(), + consumer: Consumer::new(subscribed, HangContainer::Legacy(crate::container::Kind::Audio)), + instance: None, + })); (track, export) } From c13f685c1dffef7f5923180e3f40f9f115dbf66b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 15:14:52 -0800 Subject: [PATCH 03/14] refactor(hls): the segment window, claim and import generation hold one phase each The window's ended/cut/failed become one Phase, so a push after the end is refused. The claim is the channel the media watcher waits on, replacing the separate retiring flag. The import's importer, map and discontinuity form one Generation. Co-Authored-By: Claude Opus 5.5 --- rs/moq-hls/src/export/rendition.rs | 84 ++++++++++------------- rs/moq-hls/src/export/segments.rs | 104 ++++++++++++++++++++--------- rs/moq-hls/src/import.rs | 85 ++++++++++++----------- 3 files changed, 157 insertions(+), 116 deletions(-) diff --git a/rs/moq-hls/src/export/rendition.rs b/rs/moq-hls/src/export/rendition.rs index 37c5429b6ec..19aa48eb41c 100644 --- a/rs/moq-hls/src/export/rendition.rs +++ b/rs/moq-hls/src/export/rendition.rs @@ -132,8 +132,6 @@ struct Handle { /// The query pinning the track instance. Even an info query creates publisher demand, /// so a lazy rendition holds it only while serving media. track: Option, - /// The bound sibling ended, so only its retained rows drain. - ended: bool, } impl Handle { @@ -159,7 +157,6 @@ impl Media { let mut handle = Handle { binding: Arc::new(source.bind(rel, reference.instance())?), track: None, - ended: false, }; if !lazy && let Poll::Ready(Ok(broadcast)) = handle.binding.poll_broadcast(&kio::Waiter::noop()) { handle.capture(&broadcast, track); @@ -173,10 +170,11 @@ impl Media { }) } - /// Whether incoming rows should be listed: not once the bound sibling ended. + /// Whether incoming rows should be listed: not once the window stopped listing, as it does + /// when the bound sibling ends. fn admits(&self, window: &segments::Producer) -> bool { self.sync(window); - !self.handle.lock().expect("media lock poisoned").ended + window.lists() } /// End the window when a bound sibling has ended; retain its rows and media for draining. @@ -191,10 +189,9 @@ impl Media { if !self.lazy { handle.capture(&broadcast, &self.track); } - if self.sibling && !handle.ended && broadcast.poll_closed(waiter).is_ready() { + if self.sibling && broadcast.poll_closed(waiter).is_ready() { // End and Restart both drain only the pinned instance. Looking its path up again // could serve a replacement under the old track's rows. - handle.ended = true; window.end(); } } @@ -405,10 +402,9 @@ pub struct Rendition { fanout: renditions::Fanout, /// Follows the media track's groups into [`live`](Self::live); ends when the rendition drops. watcher: Mutex, - /// Set once the catalog drops or replaces the rendition (see [`retire`](Self::retire)). - retiring: kio::Producer, - /// Which segments this instance lists. - claim: Mutex, + /// Which segments this instance lists. A channel so the media watcher wakes once a + /// [`retire`](Self::retire) leaves no segment pending. + claim: kio::Producer, /// The retired instance this one replaced under the same playlist URI, whose segments its playlist /// still lists ahead of its own until the window slides past them (see [`after`](Self::after)). /// Released once none is listed, or by a restart. @@ -528,7 +524,7 @@ impl kio::Task for Idle { let Some(rendition) = self.rendition.upgrade() else { return Poll::Ready(()); }; - let mut claim = rendition.claim.lock().expect("claim lock poisoned"); + let mut claim = rendition.claim(); let mut watcher = rendition.watcher.lock().expect("watcher lock poisoned"); // A finished window keeps listing what it listed, inherited predecessor rows included, // and keeps its track pin: reads of its retained groups go through it, since a closed @@ -684,8 +680,7 @@ impl Rendition { live: Arc::new(segments::Producer::new(0)), fanout, watcher: Mutex::default(), - retiring: kio::Producer::new(false), - claim: Mutex::default(), + claim: kio::Producer::default(), previous: Mutex::new(None), media: Arc::new(media), run: kio::Producer::default(), @@ -727,8 +722,7 @@ impl Rendition { live: Arc::new(segments::Producer::new(0)), fanout, watcher: Mutex::default(), - retiring: kio::Producer::new(false), - claim: Mutex::default(), + claim: kio::Producer::default(), previous: Mutex::new(None), media: Arc::new(media), run: kio::Producer::default(), @@ -778,7 +772,7 @@ impl Rendition { // The playlist URI stays the same, so it keeps its target duration (RFC 8216 6.2.1). self.target_duration = handoff.target_duration; let start = handoff.next; - self.claim = Mutex::new(Claim { + self.claim = kio::Producer::new(Claim { start, next: start, ..Claim::default() @@ -799,7 +793,7 @@ impl Rendition { /// the media and the catalog are separate tracks, so the successor's first group can arrive first. pub(crate) fn retire(self: &Arc, successor: Option<&VideoConfig>) -> Handoff { let (next, pending) = { - let mut claim = self.claim.lock().expect("claim lock poisoned"); + let mut claim = self.claim(); claim.retired = true; claim.boundary = claim.seen; if let Some(resized) = self.handover(&claim, successor) { @@ -815,10 +809,6 @@ impl Rendition { } (claim.next, claim.pending) }; - *self - .retiring - .write() - .unwrap_or_else(|_| unreachable!("the rendition holds its producer")) = true; // Once retired, one that neither lists nor waits to list a segment never will, so the // replacement keeps only what this one was keeping: churn can't stack empty instances. let lists = pending || !self.live.window().segments.is_empty(); @@ -851,6 +841,12 @@ impl Rendition { (same_track && resizes && resized.group >= unplaced).then_some(resized) } + fn claim(&self) -> kio::Mut<'_, Claim> { + self.claim + .write() + .unwrap_or_else(|_| unreachable!("the rendition holds its claim")) + } + fn previous(&self) -> Option> { self.previous.lock().expect("previous lock poisoned").clone() } @@ -1984,22 +1980,16 @@ fn broken(segments: &[u64], inherited: usize) -> usize { .unwrap_or(0) } -/// Ready once `rendition` is retired with no segment left waiting to list, or is gone. -/// -/// The claim is read on every poll, so a retire that leaves nothing pending wakes it. -fn poll_retired(retiring: &kio::Consumer, rendition: &Weak, waiter: &kio::Waiter) -> Poll<()> { - // Upgraded outside the channel's lock, so the last strong reference never drops under it. - let Some(rendition) = rendition.upgrade() else { - return Poll::Ready(()); - }; - let done = |retiring: &bool| *retiring && !rendition.claim.lock().expect("claim lock poisoned").pending; +/// Ready once the rendition is retired with no segment left waiting to list, or is gone. +fn poll_retired(claim: &kio::Consumer, waiter: &kio::Waiter) -> Poll<()> { // A closed channel means the rendition is gone, which ends the watch all the same. - retiring - .poll(waiter, |retiring| match done(retiring) { - true => Poll::Ready(()), - false => Poll::Pending, - }) - .map(|_| ()) + match claim.poll(waiter, |claim| match claim.retired && !claim.pending { + true => Poll::Ready(()), + false => Poll::Pending, + }) { + Poll::Ready(_) => Poll::Ready(()), + Poll::Pending => Poll::Pending, + } } /// Follows a rendition's media track into its window, numbering its groups on the grid, until the @@ -2011,7 +2001,7 @@ fn poll_retired(retiring: &kio::Consumer, rendition: &Weak, wai /// lists that segment whole, and the same URL must name the same bytes everywhere. struct WatchMedia { rendition: Weak, - retiring: kio::Consumer, + claim: kio::Consumer, /// Taken from the rendition on the first poll. follow: Option, /// The rendition's media and the binding it is read through, held while the watch runs. @@ -2138,7 +2128,7 @@ impl Follow { return Some(Ok(())); }; // Held while listing, so a retire sees exactly what this instance lists. - let mut claim = rendition.claim.lock().expect("claim lock poisoned"); + let mut claim = rendition.claim(); // Retired, a group past the last it had read is the replacement's: this instance lists // the segments and gaps before the first holding one, and its own part of that one, then // stops there. @@ -2242,7 +2232,7 @@ impl WatchMedia { fn new(rendition: &Arc) -> Self { Self { rendition: Arc::downgrade(rendition), - retiring: rendition.retiring.consume(), + claim: rendition.claim.consume(), follow: None, held: None, groups: None, @@ -2253,7 +2243,7 @@ impl WatchMedia { fn poll_watch(&mut self, waiter: &kio::Waiter) -> Poll> { let follow = self.follow.as_mut().expect("taken on the first poll"); loop { - let retired = || poll_retired(&self.retiring, &self.rendition, waiter).is_ready(); + let retired = || poll_retired(&self.claim, waiter).is_ready(); match &mut self.step { Step::Start => { // A replacement lists nothing until its predecessor has listed all it will, so @@ -2274,7 +2264,7 @@ impl WatchMedia { } ready!(previous.live.poll_closed(waiter)); let (next, boundary) = { - let claim = previous.claim.lock().expect("claim lock poisoned"); + let claim = previous.claim(); (claim.next, claim.boundary) }; // Another track, or the same name in another broadcast, numbers its groups afresh. @@ -2284,7 +2274,7 @@ impl WatchMedia { .is_some_and(|rendition| rendition.continues(previous)); follow.after = boundary.filter(|_| continues); if let Some(rendition) = self.rendition.upgrade() { - let mut claim = rendition.claim.lock().expect("claim lock poisoned"); + let mut claim = rendition.claim(); claim.start = claim.start.max(next); claim.next = claim.next.max(next); } @@ -2394,9 +2384,10 @@ impl kio::Task for WatchMedia { let track = self.follow.take().expect("taken on the first poll").track; match result { Ok(()) => rendition.end(), - // A bound sibling that ended takes its track down with it: that ends the rendition, - // whose retained rows drain, rather than failing it. - Err(_) if !rendition.media.admits(&rendition.live) => rendition.end(), + // A bound sibling that ended takes its track down with it: that ended the rendition, + // whose retained rows drain, rather than failing it. A window cut or failed already + // keeps how it stopped. + Err(_) if !rendition.media.admits(&rendition.live) => {} // Never retried (the origin already rides out transient source failures), and not // papered over with gaps: the rendition's playlist answers the error. Err(err) => { @@ -2891,7 +2882,6 @@ mod tests { let mut handle = Handle { binding: Arc::new(moq_mux::Binding::new(consumer.clone())), track: None, - ended: false, }; handle.capture(&consumer, "video"); assert!(serve.track.lock().unwrap().is_some(), "the query was served"); diff --git a/rs/moq-hls/src/export/segments.rs b/rs/moq-hls/src/export/segments.rs index 795b4e8f1e2..2a6a59530e2 100644 --- a/rs/moq-hls/src/export/segments.rs +++ b/rs/moq-hls/src/export/segments.rs @@ -82,18 +82,26 @@ struct State { sequence: u64, /// The newest discontinuity seen, retained when the playlist window becomes empty. discontinuity: u64, - /// The media track ended: the rendition is over (`EXT-X-ENDLIST`). - ended: bool, - /// The run was replaced: the listed rows are final, so nothing appends, trims, or fails them. - cut: bool, - /// The media track or the catalog failed, so every listing refuses with this error. - failed: Option, + /// Whether rows still arrive, and if not, why. + phase: Phase, /// Bumped whenever the window is cleared, so a cursor can tell its position is stale. resets: u64, /// Total rows appended, so a cursor can detect eviction even before its first read. produced: u64, } +/// Whether a window still lists new rows, and if not, why. Each later phase is final. +enum Phase { + /// Rows arrive as the media watcher reads them. + Live, + /// The media track ended, or the bound sibling did: the rendition is over (`EXT-X-ENDLIST`). + Ended, + /// The run was replaced: the listed rows are final, so nothing appends, trims, or fails them. + Cut, + /// The media track or the catalog failed, so every listing refuses with this error. + Failed(crate::Error), +} + /// The most segments a playlist window lists, however short they are. /// /// Bounds the window however short its segments are, so an edge that joined long ago lists no @@ -193,8 +201,8 @@ impl State { sequence: self.sequence, discontinuity: self.rows.front().map_or(self.discontinuity, |row| row.discontinuity), segments: self.rows.iter().cloned().collect(), - ended: self.ended, - failed: self.failed.clone(), + ended: matches!(self.phase, Phase::Ended | Phase::Cut), + failed: self.failure(), closed: false, } } @@ -207,10 +215,21 @@ impl State { } Ok(match self.rows.get((position.1 - first) as usize) { Some(row) => Next::Ready(row.clone()), - None if self.ended || self.failed.is_some() => Next::Done, - None => Next::Pending, + None if self.live() => Next::Pending, + None => Next::Done, }) } + + fn live(&self) -> bool { + matches!(self.phase, Phase::Live) + } + + fn failure(&self) -> Option { + match &self.phase { + Phase::Failed(err) => Some(err.clone()), + _ => None, + } + } } impl Producer { @@ -222,21 +241,20 @@ impl Producer { rows: VecDeque::new(), sequence: start, discontinuity: 0, - ended: false, - cut: false, - failed: None, + phase: Phase::Live, resets: 0, produced: 0, }), } } - /// Append a row, evicting the front of the window past `window` (see [`evicts`]). + /// Append a row, evicting the front of the window past `window` (see [`evicts`]). A window + /// that ended, failed, or was cut lists nothing more. pub fn push(&self, row: Row, window: Duration) { let Ok(mut state) = self.state.write() else { return; }; - if state.cut { + if !state.live() { return; } @@ -267,10 +285,10 @@ impl Producer { state.sequence = state.rows.front().unwrap().segment; } - /// Clear every retained row after the media timestamps went back. + /// Clear every retained row after the media timestamps went back, unless no row arrives again. pub fn clear(&self) { if let Ok(mut state) = self.state.write() - && !state.cut + && state.live() { state.rows.clear(); state.resets += 1; @@ -279,18 +297,21 @@ impl Producer { /// Mark the media finished: the playlist gets `EXT-X-ENDLIST` and cursors end once drained. pub fn end(&self) { - if let Ok(mut state) = self.state.write() { - state.ended = true; + if let Ok(mut state) = self.state.write() + && state.live() + { + state.phase = Phase::Ended; } } /// Mark the window failed with `err`: every listing refuses with it instead of ending, and - /// cursors return it once drained. No row is pushed after. + /// cursors return it once drained. No row is pushed after. The first failure stays, and a cut + /// window keeps the rows it listed. pub fn fail(&self, err: crate::Error) { if let Ok(mut state) = self.state.write() - && !state.cut + && matches!(state.phase, Phase::Live | Phase::Ended) { - state.failed.get_or_insert(err); + state.phase = Phase::Failed(err); } } @@ -298,9 +319,10 @@ impl Producer { /// playlist gets `EXT-X-ENDLIST`, cursors drain those rows and then end, and whatever the /// replaced run sends later is refused. A window that already failed keeps its failure. pub fn cut(&self) { - if let Ok(mut state) = self.state.write() { - state.cut = true; - state.ended = true; + if let Ok(mut state) = self.state.write() + && matches!(state.phase, Phase::Live | Phase::Ended) + { + state.phase = Phase::Cut; } self.close(); } @@ -310,12 +332,17 @@ impl Producer { #[cfg(feature = "server")] pub fn finished(&self) -> bool { let state = self.state.read(); - state.ended || state.failed.is_some() || state.is_closed() + !state.live() || state.is_closed() + } + + /// Whether the window still lists new rows: it has not ended, failed, or been cut. + pub fn lists(&self) -> bool { + self.state.read().live() } /// Why the window failed, if it did. pub fn failure(&self) -> Option { - self.state.read().failed.clone() + self.state.read().failure() } /// Close the channel: no more rows will arrive. A [`Consumer`] drains the segments it @@ -383,7 +410,7 @@ impl Producer { /// Poll until the window lists a row, ends, fails, or closes. pub fn poll_listed(&self, waiter: &kio::Waiter) -> Poll<()> { match self.state.poll_ref(waiter, |state| { - match !state.rows.is_empty() || state.ended || state.failed.is_some() { + match !state.rows.is_empty() || !state.live() { true => Poll::Ready(()), false => Poll::Pending, } @@ -425,9 +452,9 @@ impl Producer { allow(dead_code, reason = "only the `server` feature uses it") )] pub fn poll_failed(&self, waiter: &kio::Waiter) -> Poll<()> { - match self.state.poll_ref(waiter, |state| match state.failed { - Some(_) => Poll::Ready(()), - None => Poll::Pending, + match self.state.poll_ref(waiter, |state| match state.phase { + Phase::Failed(_) => Poll::Ready(()), + _ => Poll::Pending, }) { Poll::Ready(Ok(())) => Poll::Ready(()), _ => Poll::Pending, @@ -671,6 +698,21 @@ mod tests { assert!(live.window().ended); } + // An ended window lists nothing more: the playlist already went out with `EXT-X-ENDLIST`. + #[test] + fn an_ended_window_refuses_rows() { + let live = Producer::new(0); + let window = Duration::from_secs(30); + live.push(row(0, 0, 0, 2_000), window); + live.end(); + live.push(row(1, 1, 2_000, 2_000), window); + live.clear(); + let snapshot = live.window(); + assert!(snapshot.ended); + let segments: Vec<_> = snapshot.segments.iter().map(|row| row.segment).collect(); + assert_eq!(segments, [0]); + } + // A cut freezes the listed rows: later records, trims, resets, and failures are refused, and // the window reads as ended. One that failed first keeps its failure. #[test] diff --git a/rs/moq-hls/src/import.rs b/rs/moq-hls/src/import.rs index 1d444f158db..1a0a7e4f6c0 100644 --- a/rs/moq-hls/src/import.rs +++ b/rs/moq-hls/src/import.rs @@ -403,12 +403,9 @@ struct TrackState { /// separate audio rendition publishes video only). select: select::Broadcast, sink: Sink, - /// The importer for the current init segment generation, minted by [`Self::ensure_map`]. - importer: Option, + /// The current init segment's importer, minted by [`Self::ensure_map`]. + generation: Option, next_sequence: Option, - next_discontinuity: Option, - /// The `EXT-X-MAP` resource the current `importer` was initialized from. - map: Option, media_range: RangeCursor, /// Consecutive failed ingest attempts, reset by any successful one. See /// [`MAX_RENDITION_FAILURES`]. @@ -420,6 +417,15 @@ struct TrackState { followed: bool, } +/// One init segment's importer, and where it reached on the media timeline. +struct Generation { + /// The `EXT-X-MAP` resource the importer was initialized from. + map: Resource, + importer: Fmp4, + /// The discontinuity sequence of the last segment imported, `None` before the first. + discontinuity: Option, +} + impl TrackState { fn new(label: String, playlist: Url, select: select::Broadcast, sink: Sink) -> Self { Self { @@ -427,10 +433,8 @@ impl TrackState { playlist, select, sink, - importer: None, + generation: None, next_sequence: None, - next_discontinuity: None, - map: None, media_range: RangeCursor::default(), failures: 0, ended: false, @@ -444,8 +448,7 @@ impl TrackState { /// players stop selecting a rendition that no longer advances; a later successful step rebuilds /// it from the init segment. fn evict(&mut self) { - self.importer = None; - self.map = None; + self.generation = None; self.reanchor(); } @@ -602,7 +605,7 @@ impl TrackState { let resource = resolve_map(url, map.byte_range.as_ref())?; // The resolved resource IS the init segment's identity: same bytes, same generation. - if self.map.as_ref() == Some(&resource) { + if self.generation.as_ref().is_some_and(|generation| generation.map == resource) { return Ok(()); } @@ -616,12 +619,14 @@ impl TrackState { // The old generation must finish before retiring its catalog entries, so a subscriber // draining its final group sees a clean end instead of a dropped producer. - if let Some(previous) = self.importer.as_mut() { - previous.finish()?; + if let Some(previous) = self.generation.as_mut() { + previous.importer.finish()?; } - self.importer = Some(importer); - self.map = Some(resource); - self.next_discontinuity = None; + self.generation = Some(Generation { + map: resource, + importer, + discontinuity: None, + }); info!(label = %self.label, "loaded HLS init segment generation"); Ok(()) } @@ -650,15 +655,16 @@ impl TrackState { // (and so validate) the sequence on that path so media sequence can't silently // auto-increment into the discontinuity bits. let group_sequence = moq_sequence(discontinuity_sequence, sequence)?; - let reanchored = - self.next_sequence != Some(sequence) || self.next_discontinuity != Some(discontinuity_sequence); // `consume_segments` resolves the effective map before every segment, so a missing // importer means the playlist never carried an `EXT-X-MAP`. - let importer = self.importer.as_mut().ok_or(Error::MissingMap)?; + let generation = self.generation.as_mut().ok_or(Error::MissingMap)?; + let reanchored = + self.next_sequence != Some(sequence) || generation.discontinuity != Some(discontinuity_sequence); + let importer = &mut generation.importer; // Only a discontinuity starts a new media timeline; a sequence skip must keep advancing. - if self - .next_discontinuity + if generation + .discontinuity .is_some_and(|previous| previous != discontinuity_sequence) { importer.discontinuity()?; @@ -670,7 +676,11 @@ impl TrackState { // carries no styp. Every rendition declares the same ones; the HLS segmenter drops a cut // that would land inside its minimum segment duration, so the duplicates cost nothing. importer.cut()?; - importer.decode(&bytes).map_err(|err| match err { + let decoded = importer.decode(&bytes); + if decoded.is_ok() { + generation.discontinuity = Some(discontinuity_sequence); + } + decoded.map_err(|err| match err { // Timestamp resets are unsupported: the published tracks never rewind, and no later // pass can import this segment, so it is refused rather than retried. moq_mux::Error::TimestampRewind(_) @@ -688,7 +698,6 @@ impl TrackState { self.media_range = range; self.next_sequence = Some(sequence + 1); - self.next_discontinuity = Some(discontinuity_sequence); Ok(()) } @@ -838,8 +847,8 @@ impl Import { /// broadcast to a [`moq_mux::Linger`] to keep them up for late subscribers. pub fn finish(&mut self) -> Result<()> { for track in self.video.iter_mut().chain(self.audio.iter_mut()) { - if let Some(importer) = &mut track.importer { - importer.finish()?; + if let Some(generation) = &mut track.generation { + generation.importer.finish()?; } } self.sink.catalog.finish()?; @@ -854,14 +863,14 @@ impl Import { /// the import: every rendition is dead afterwards. pub fn abort(mut self, err: moq_net::Error) { for track in &mut self.video { - if let Some(importer) = track.importer.take() { - importer.abort(err.clone()); + if let Some(generation) = track.generation.take() { + generation.importer.abort(err.clone()); } } if let Some(track) = &mut self.audio - && let Some(importer) = track.importer.take() + && let Some(generation) = track.generation.take() { - importer.abort(err.clone()); + generation.importer.abort(err.clone()); } self.sink.catalog.clone().abort(err); } @@ -918,7 +927,7 @@ impl Import { // drop the rest or abort the whole step. OnError::Warn => { track.failures += 1; - if track.failures >= MAX_RENDITION_FAILURES && track.importer.is_some() { + if track.failures >= MAX_RENDITION_FAILURES && track.generation.is_some() { warn!(label = %track.label, %err, failures = track.failures, "rendition import keeps failing, dropping it until it recovers"); track.evict(); } else { @@ -1990,7 +1999,7 @@ mod tests { let (mut import, catalog) = write_import(&temp_dir(), &resource, &playlist); assert!(matches!(import.init().await, Err(Error::PlaylistEnded))); - assert!(import.video[0].importer.is_none(), "nothing was imported"); + assert!(import.video[0].generation.is_none(), "nothing was imported"); assert!(catalog.snapshot().video.renditions.is_empty()); let run = kio::clock::timeout(Duration::from_secs(5), import.run()) @@ -2085,7 +2094,7 @@ mod tests { let (mut import, _catalog) = write_import(&dir, &resource, &playlist); import.init().await.unwrap(); - assert!(import.video[0].importer.is_some(), "the rendition imported once"); + assert!(import.video[0].generation.is_some(), "the rendition imported once"); // The source goes away underneath us. std::fs::remove_file(dir.join("media.m3u8")).unwrap(); @@ -2093,13 +2102,13 @@ mod tests { for _ in 0..MAX_RENDITION_FAILURES - 1 { import.step(OnError::Warn).await.unwrap(); assert!( - import.video[0].importer.is_some(), + import.video[0].generation.is_some(), "a transient failure keeps the rendition" ); } import.step(OnError::Warn).await.unwrap(); - assert!(import.video[0].importer.is_none(), "the dead rendition is retired"); + assert!(import.video[0].generation.is_none(), "the dead rendition is retired"); } /// A decode refusal retires its importer at once, rather than after @@ -2128,7 +2137,7 @@ mod tests { std::fs::write(dir.join("media.m3u8"), format!("{playlist}#EXTINF:1,\nvideo1.m4s\n")).unwrap(); let step = import.step(OnError::Warn).await.unwrap(); assert!(step.failed.is_some()); - assert!(import.video[0].importer.is_none()); + assert!(import.video[0].generation.is_none()); std::fs::write(dir.join("video1.m4s"), &segment).unwrap(); let step = import.step(OnError::Warn).await.unwrap(); assert!(step.failed.is_none()); @@ -2160,7 +2169,7 @@ mod tests { for _ in 0..MAX_RENDITION_FAILURES { assert!(import.step(OnError::Warn).await.unwrap().ended); } - assert!(import.video[0].importer.is_some(), "the ended rendition is kept"); + assert!(import.video[0].generation.is_some(), "the ended rendition is kept"); } /// A live window longer than `ANCHOR_SEGMENTS` is joined mid-playlist, which means the @@ -2199,7 +2208,7 @@ mod tests { let track = &import.video[0]; assert!( - track.importer.is_some(), + track.generation.is_some(), "the EXT-X-MAP from the skipped prefix must initialize the importer" ); // Four segments and a three-segment rewind, so segment 0 is skipped: the one @@ -2235,7 +2244,7 @@ mod tests { assert_eq!(snapshot.video.renditions.len(), 1); assert_eq!(snapshot.audio.renditions.len(), 1); assert_eq!( - import.video[0].map.as_ref().unwrap().range.unwrap().start, + import.video[0].generation.as_ref().unwrap().map.range.unwrap().start, second_init as u64 ); } From 8a62b0c6d5afd87773e97c953e9abb16274a42d2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 15:25:47 -0800 Subject: [PATCH 04/14] fix(mux,hang): a skip records where the skipped group ended The container consumer's reader and startup are each one enum, and the catalog publish gate is one Gate. In both languages every move past a group records where its content ended, so a group continuing one skipped mid-read plays on instead of waiting out the max delay as a hole. Co-Authored-By: Claude Opus 5.5 --- .../container/consumer.nonsequential.test.ts | 39 ++++++ js/hang/src/container/consumer.ts | 26 ++-- rs/moq-mux/src/catalog/producer.rs | 93 +++++++------ rs/moq-mux/src/container/consumer.rs | 124 +++++++++++------- 4 files changed, 179 insertions(+), 103 deletions(-) diff --git a/js/hang/src/container/consumer.nonsequential.test.ts b/js/hang/src/container/consumer.nonsequential.test.ts index ac379567042..45eb07fcb13 100644 --- a/js/hang/src/container/consumer.nonsequential.test.ts +++ b/js/hang/src/container/consumer.nonsequential.test.ts @@ -92,3 +92,42 @@ test("Consumer waits on a non-sequential hang group because it has no per-frame consumer.close(); }); + +// A skip past a group already begun records where it ended, as Rust's `skip_to` does, so a later group +// continuing its timeline plays on at once rather than waiting out the max delay as if a group were +// missing in between. Sparse sequence numbers leave only the timeline to prove nothing is missing, +// and the empty group in between says nothing of it. +test("Consumer plays on a group continuing one it skipped mid-read", async () => { + const track = new Track.Producer("test"); + const consumer = new Consumer(track.subscribe(), { + format: new LegacyFormat("audio"), + delay: { max: 500 as Milli }, + }); + const write = (sequence: bigint, timestamps: number[]) => { + const group = track.createGroup(sequence); + for (const timestamp of timestamps) { + group.writeFrame({ + payload: encodeLegacyFrame(timestamp as Micro, new Uint8Array([0x01])), + timestamp: Time.Timestamp.now(), + }); + } + group.finish(); + }; + + write(0n, [0, 100_000, 200_000, 300_000, 400_000]); + expect((await nextFrame(consumer))?.group).toBe(0n); + const empty = track.createGroup(10n); + await clock.advance(Nano.zero); + // The newest frame is past the budget behind the first group's next, so its rest is skipped, up to + // the group in between, which ends without a frame. + write(20n, [400_000, 700_000]); + empty.finish(); + await clock.advance(Nano.zero); + expect(await poll(consumer.next())).toMatchObject({ kind: "gap" }); + const next = await poll(nextFrame(consumer)); + expect(next === "pending" ? next : next?.group).toBe(20n); + + consumer.close(); + track.finish(); + track.close(); +}); diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index ff97e6cb370..414802910b3 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -194,7 +194,7 @@ export class Consumer { #hole?: Instant; // Presentation end (max PTS + duration) of the group we most recently advanced past, so next()'s // promotion guard can tell a timeline-continuous next group from one sitting after a gap. - // Maintained only via #recordPresented; see its comment for the invariant. + // Written only by #pass, which every move past a group goes through. #presentedEnd?: Micro; // Group of the last media frame next() returned, so an endpoint after it reads as that frame's // duration rather than a declared stop. @@ -519,14 +519,13 @@ export class Consumer { return group.consumer.closed.peek() ?? null; } - // Record where a group's content ends as the cursor advances past it. next()'s promotion guard - // compares the following group's first PTS against this to tell an unbroken timeline from a real - // gap, so EVERY site that moves #active past a group must call this; a site that forgets leaves a - // stale end behind and silently blocks the next contiguous group forever. A group with no frames - // (empty, or errored before the first one) says nothing about the timeline, so it leaves the last - // known end in place rather than wiping it. - #recordPresented(group: Group): void { + // Move the cursor past `group` to `next`, recording where the group's content ends. next()'s + // promotion guard compares the following group's first PTS against that to tell an unbroken + // timeline from a real gap. A group with no frames (empty, or errored before the first one) says + // nothing about the timeline, so it leaves the last known end in place rather than wiping it. + #pass(group: Group, next: bigint | undefined): void { if (group.end !== undefined) this.#presentedEnd = group.end; + this.#active = next; } // Skip the oldest groups while the buffered span exceeds the max delay. Returns true if any was skipped. @@ -588,7 +587,7 @@ export class Consumer { } this.#groups.shift(); - this.#active = this.#groups[0]?.consumer.sequence; + this.#pass(first, this.#groups[0]?.consumer.sequence); const next = this.#groups[0]; const nextStart = next?.frames.at(0)?.timestamp ?? next?.end; @@ -659,8 +658,7 @@ export class Consumer { this.#groups.shift(); console.warn(`skipping covered group: ${active.consumer.sequence} -> ${next.consumer.sequence}`); - this.#recordPresented(active); - this.#active = next.consumer.sequence; + this.#pass(active, next.consumer.sequence); this.#discard(active); this.#updateBuffered(); @@ -692,8 +690,7 @@ export class Consumer { const nextStart = next.frames.at(0)?.timestamp; const marker = !head.empty && !head.media; if (marker || !ptsContiguous(head.end ?? this.#presentedEnd, nextStart)) this.#lost = true; - this.#recordPresented(head); - this.#active = next.consumer.sequence; + this.#pass(head, next.consumer.sequence); this.#discard(head); this.#updateBuffered(); @@ -941,9 +938,8 @@ export class Consumer { // the hole expired -- every group through the skip path, i.e. constant stutter. A real // PTS gap is different: an intermediate group may still be in transit, so fall back to // +1 there (the promotion guard above fixes it up once a continuous group arrives). - this.#recordPresented(head); const next = this.#groups.at(0); - this.#active = continues(head, next) ? next.consumer.sequence : seq + 1n; + this.#pass(head, continues(head, next) ? next.consumer.sequence : seq + 1n); } head.consumer.close(); this.#release(head); diff --git a/rs/moq-mux/src/catalog/producer.rs b/rs/moq-mux/src/catalog/producer.rs index fbbe4245c4a..679034015c4 100644 --- a/rs/moq-mux/src/catalog/producer.rs +++ b/rs/moq-mux/src/catalog/producer.rs @@ -30,7 +30,7 @@ struct State { /// Gates the initial catalog publish until all reservations resolve (see /// [`reserve`](Producer::reserve)). - reservations: Reservations, + gate: Gate, /// Why the catalog tracks are closed, so [`Producer::modify`] refuses further edits with the /// cause: [`Producer::finish`], [`Producer::abort`], or a failed drop-time publish. @@ -67,6 +67,12 @@ impl State { /// promises no frames, so it doesn't count. A listed rendition covers application-defined /// sections the base fields can't see, and an importer that lists tracks in the extension /// reports them through [`ext_tracks`](Self::ext_tracks). + /// Whether a buffering gate opens now: no reservation is outstanding and the catalog lists a + /// track. The track scan runs last, so releasing each of many reservations stays linear. + fn gate_opens(&mut self) -> bool { + matches!(self.gate, Gate::Buffering { reservers: 0, .. }) && self.lists_track() + } + fn lists_track(&mut self) -> bool { use std::any::TypeId; // Video and audio carry `enabled`, which only the base check reads. @@ -242,7 +248,7 @@ fn adopt( /// /// A panic under this lock comes from code we hand the catalog to: a [`RenditionConfig::insert`] /// implementation, or serializing an extension during a publish. Neither leaves the state -/// inconsistent (at worst the catalog is missing an entry, while `owned` and `reservations` still +/// inconsistent (at worst the catalog is missing an entry, while `owned` and `gate` still /// describe exactly what is live), so poisoning protects nothing here. It would only turn the next /// [`Rendition`](super::Rendition) drop into a panic during unwinding, which aborts the process. fn take(state: &Mutex>) -> MutexGuard<'_, State> { @@ -256,23 +262,24 @@ fn owner_key(name: &str) -> (std::any::TypeId, String) { /// The initial-publish gate, tracking the [`Reserved`](super::Reserved) handles still outstanding. /// -/// The initial catalog snapshot is withheld from the broadcast until `reservers == 0`. A live -/// `Reserved` counts as one reserver; a [`Rendition`](super::Rendition) holds its own `Reserved` -/// clone until it's fulfilled (or dropped), so an unresolved rendition keeps the gate shut too. See -/// [`Reserved`](super::Reserved). +/// A live `Reserved` counts as one reserver; a [`Rendition`](super::Rendition) holds its own +/// `Reserved` clone until it's fulfilled (or dropped), so an unresolved rendition keeps the gate +/// shut too. See [`Reserved`](super::Reserved). #[derive(Default)] -struct Reservations { - /// Live `Reserved` handles (including the one each unfulfilled `Rendition` holds). - reservers: usize, - /// A catalog change was made while buffering and is awaiting the initial publish. Without this - /// we'd emit an empty snapshot when the gate opens on a catalog nobody ever touched. - pending: bool, - /// Whether the initial snapshot has been published (buffering is over). - published: bool, - /// Whether anything ever reserved, making this an importer's catalog: its initial snapshot also - /// waits for a [listed track](State::lists_track), so input that declares none never announces. - /// An incremental producer that never reserves publishes as it goes. - reserved: bool, +enum Gate { + /// Nothing ever reserved: an incremental producer publishes as it goes. + #[default] + Unreserved, + /// An importer's catalog, withholding its initial snapshot until no reservation is outstanding + /// and it [lists a track](State::lists_track), so input that declares none never announces. + Buffering { + reservers: usize, + /// A catalog change was made while buffering and is awaiting the initial publish. Without + /// this we'd emit an empty snapshot when the gate opens on a catalog nobody ever touched. + pending: bool, + }, + /// The initial snapshot went out: every change publishes. + Published, } /// The catalog tracks. @@ -512,7 +519,7 @@ impl Producer { catalog, owned: BTreeMap::new(), ext_tracks: None, - reservations: Reservations::default(), + gate: Gate::default(), closed: None, clock, anchored, @@ -807,8 +814,17 @@ impl Producer { /// Register a live [`Reserved`](super::Reserved) handle. pub(super) fn add_reserver(&self) { let mut state = take(&self.current); - state.reservations.reservers += 1; - state.reservations.reserved = true; + match &mut state.gate { + Gate::Unreserved => { + state.gate = Gate::Buffering { + reservers: 1, + pending: false, + } + } + Gate::Buffering { reservers, .. } => *reservers += 1, + // Only the initial publish waits for reservations. + Gate::Published => {} + } } /// Drop a [`Reserved`](super::Reserved) handle, flushing the initial snapshot if that was the @@ -816,8 +832,9 @@ impl Producer { pub(super) fn release_reserver(&mut self) { { let mut state = take(&self.current); - let r = &mut state.reservations; - r.reservers = r.reservers.saturating_sub(1); + if let Gate::Buffering { reservers, .. } = &mut state.gate { + *reservers = reservers.saturating_sub(1); + } } self.flush_if_ready(); } @@ -825,16 +842,12 @@ impl Producer { /// Publish the buffered snapshot once, if buffering has just finished with a change staged. pub(super) fn flush_if_ready(&mut self) { let mut state = take(&self.current); - let r = &state.reservations; // Nothing was staged (e.g. every stream was ignored): stay unpublished so a later change - // still triggers the first emit, rather than publishing an empty catalog now. The track - // scan runs last, so releasing each of many reservations stays linear. - if r.published || r.reservers != 0 || !r.pending || !state.lists_track() { + // still triggers the first emit, rather than publishing an empty catalog now. + if !matches!(state.gate, Gate::Buffering { pending: true, .. }) || !state.gate_opens() { return; } - let r = &mut state.reservations; - r.pending = false; - r.published = true; + state.gate = Gate::Published; // A snapshot on the wire is a mapping a reader may have copied. state.anchored = true; state.estimates.fold(); @@ -1123,20 +1136,16 @@ impl Guard<'_, E> { self.state.catalog.media.clock = self.state.clock.wall(); adopted?; - { - // Withhold every emit while still buffering the initial reserved set, or until a reserved - // catalog names a track; the mutation stays in `current` and `pending` marks it for the - // flush once the gate opens. The track scan runs last, so a published catalog skips it. - let r = &self.state.reservations; - let withhold = !r.published && (r.reservers != 0 || (r.reserved && !self.state.lists_track())); - let r = &mut self.state.reservations; - if withhold { - r.pending = true; - return Ok(()); + // Withhold every emit while still buffering the initial reserved set, or until a reserved + // catalog names a track; the mutation stays in `current` and `pending` marks it for the + // flush once the gate opens. + if matches!(self.state.gate, Gate::Buffering { .. }) && !self.state.gate_opens() { + if let Gate::Buffering { pending, .. } = &mut self.state.gate { + *pending = true; } - r.pending = false; - r.published = true; + return Ok(()); } + self.state.gate = Gate::Published; // A snapshot on the wire is a mapping a reader may have copied. self.state.anchored = true; diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 71879c83fc4..bba78577dad 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -127,8 +127,7 @@ pub(crate) enum Item { /// moves on to the next group like a skip past a slow group, read or not: the consumer can hold no /// more of what it would wait behind. pub struct Consumer { - // Dropped once an error ends the reader, releasing the publisher's demand. - track: Option, + reader: Reader, name: std::sync::Arc, format: F, @@ -152,13 +151,8 @@ pub struct Consumer { // once a skip refunds room: it pulls again itself. gated: bool, - // The subscription named no floor when the consumer was built, so the cursor has yet to - // choose its first group: the floor once resolved, raised to the publisher's resolved - // start, or else the first arrivals. Cleared once one is chosen. - startup: bool, - - // Latch onto the newest group instead, discarding what arrived below it. - newest: bool, + // How the cursor chooses its first group. + startup: Startup, // How far behind the live edge an unfloored start reaches, before the warmup: see `Delay::min`. min_delay: std::time::Duration, @@ -166,9 +160,6 @@ pub struct Consumer { // How much further than the min delay an unfloored start reaches: see `Playout`. warmup: std::time::Duration, - // When the newest group had landed as the first one arrived, once an unfloored start waits. - anchor: Option, - // The point an unfloored start reached back to, the live edge less the reach, once it chose. target: Option, @@ -207,9 +198,31 @@ pub struct Consumer { // The group the last event came from. group: u64, +} - // The track failed, so no group can arrive. Returned once the groups already here drain. - track_error: Option, +/// Whether a [`Consumer`] still reads its subscription. +enum Reader { + /// Receiving groups. + Reading(moq_net::track::Subscriber), + /// The track failed, so no group can arrive. The error is returned once the groups already here + /// drain. + Failed(moq_net::track::Subscriber, E), + /// An error ended the reader, which reads as finished from then on. The subscription is + /// released, and the publisher's demand with it. + Ended, +} + +/// How a [`Consumer`]'s cursor chooses its first group. +#[derive(Clone, Copy)] +enum Startup { + /// The floor once resolved, raised to the publisher's resolved start, or else the first + /// arrivals. `anchor` is when the newest group had landed as the first one arrived, once such a + /// start waits for its reach. + Earliest { anchor: Option }, + /// The newest group, discarding what arrived below it. + Newest, + /// The cursor is on its first group or past it. + Started, } /// Two adjacent groups are timeline-contiguous when the next start is within this slack @@ -365,7 +378,7 @@ impl Consumer { .min(track.info().max_age.unwrap_or(std::time::Duration::MAX)); Self { name: track.name().into(), - track: Some(track), + reader: Reader::Reading(track), format, current: start.unwrap_or(0), pending: VecDeque::new(), @@ -373,11 +386,9 @@ impl Consumer { collect_at: 1, memory: Memory::new(DEFAULT_MAX_BUFFER), gated: false, - startup: true, - newest: false, + startup: Startup::Earliest { anchor: None }, min_delay: subscription.delay.min.unwrap_or_default(), warmup: std::time::Duration::ZERO, - anchor: None, target: None, warmed: None, max_delay, @@ -389,7 +400,6 @@ impl Consumer { gap: false, next: None, group: 0, - track_error: None, } } @@ -398,8 +408,7 @@ impl Consumer { /// subscription keeps its budget, so every group after the start arrives as it would for any /// reader; what arrived below the start is discarded. pub(crate) fn live(mut self) -> Self { - self.startup = true; - self.newest = true; + self.startup = Startup::Newest; self } @@ -485,14 +494,14 @@ impl Consumer { pub(crate) fn poll_event(&mut self, waiter: &kio::Waiter) -> Poll, F::Error>> { // An error ended the reader, which reads as finished from then on: a decode error has // already consumed the frame it came from, so reading on would skip it. - if self.track.is_none() { + if let Reader::Ended = self.reader { return Poll::Ready(Ok(None)); } let event = ready!(self.poll_event_inner(waiter)); if event.is_err() { // Nothing more is read, so release the subscription and the groups it holds rather // than pin the publisher's demand and cache for as long as the caller keeps this. - self.track = None; + self.reader = Reader::Ended; self.pending.clear(); } Poll::Ready(event) @@ -519,7 +528,7 @@ impl Consumer { // below, since timestamps can't reveal it: a gap below the served window looks like // in-flight groups until the budget expires, or forever on a quiet track. Skipping // stays the budget's job. - if self.startup && !self.newest { + if let Startup::Earliest { .. } = self.startup { let floor = self.subscriber().floor(); let served = match self.subscriber().poll_start(waiter) { Poll::Ready(served) => served, @@ -534,10 +543,10 @@ impl Consumer { if let Some(start) = start { self.pending.retain(|group| group.sequence >= start); self.current = start; - self.startup = false; + self.startup = Startup::Started; } } - if self.startup { + if !matches!(self.startup, Startup::Started) { // NOTE: poll_min_timestamp buffers at least one frame per group and // registers the waiter on the ones still empty. Any wire frame counts, so a // paused track whose only group is a marker still reads its end. The oldest @@ -552,7 +561,7 @@ impl Consumer { // largest names it before its stream lands: the backlog's oldest group can arrive // first, and starting there loses the groups after it once the live edge moves a // budget past them. - let start = match self.newest { + let start = match matches!(self.startup, Startup::Newest) { true => { let mut start = self.pending.back().expect("a group has a frame").sequence; while let Poll::Ready(Some(largest)) = self.subscriber().poll_largest(waiter) { @@ -569,7 +578,7 @@ impl Consumer { // Nothing has been read, so discarding what lies below the start is no gap. self.discard(|group| group.sequence < start)?; self.current = start; - self.startup = false; + self.startup = Startup::Started; } } @@ -733,10 +742,12 @@ impl Consumer { let since = front.late; let elapsed = since.elapsed() >= self.max_delay; let aged = next_group.is_some_and(|(_, start)| max_timestamp.saturating_sub(start) >= self.max_delay); - let excluded = self - .track - .as_ref() - .is_some_and(|track| track.next_in_range(self.current).is_none_or(|next| next >= sequence)); + let excluded = match &self.reader { + Reader::Reading(track) | Reader::Failed(track, _) => { + track.next_in_range(self.current).is_none_or(|next| next >= sequence) + } + Reader::Ended => false, + }; // The groups past the hole already fill the max buffer, so it can hold none of what // would arrive into it. let full = self.memory.full(); @@ -798,7 +809,9 @@ impl Consumer { } if finished && self.pending.is_empty() { - if let Some(err) = self.track_error.take() { + if let Reader::Failed(..) = self.reader + && let Reader::Failed(_, err) = std::mem::replace(&mut self.reader, Reader::Ended) + { // The caller only gets the bare error, with nothing to say which track died. tracing::warn!(track = &*self.name, error = ?err, "track failed; ending the reader"); return Poll::Ready(Err(err)); @@ -912,6 +925,10 @@ impl Consumer { tracing::debug!(old = self.current, new = new_current, "skipping slow groups"); + // The group left behind presented this far, which a later hole is measured from. + if let Some(end) = current_end { + self.presented_end = Some(end); + } self.current = new_current; self.note_group_edge(); Ok(()) @@ -960,9 +977,11 @@ impl Consumer { } // Wall time: the newest group landed a whole reach ago. - let arrived = *self - .anchor - .get_or_insert_with(|| self.pending.back().expect("a group has a frame").group.arrived()); + let landed = self.pending.back().expect("a group has a frame").group.arrived(); + let arrived = match &mut self.startup { + Startup::Earliest { anchor } => *anchor.get_or_insert(landed), + Startup::Newest | Startup::Started => landed, + }; if arrived.elapsed() >= reach { return Some(lowest); } @@ -984,7 +1003,10 @@ impl Consumer { // The subscription, which only an error ending the reader drops. fn subscriber(&mut self) -> &mut moq_net::track::Subscriber { - self.track.as_mut().expect("read only until an error ends the reader") + match &mut self.reader { + Reader::Reading(track) | Reader::Failed(track, _) => track, + Reader::Ended => unreachable!("read only until an error ends the reader"), + } } // Media this reader will never deliver: the next item is preceded by a gap. @@ -1007,11 +1029,11 @@ impl Consumer { /// Receive group handles and wait for the track and every received group to finish. pub(crate) fn poll_received(&mut self, waiter: &kio::Waiter) -> Poll<()> { - if self.track.is_none() { + if let Reader::Ended = self.reader { return Poll::Ready(()); } ready!(self.poll_read_finish(waiter)); - if self.track_error.is_some() { + if let Reader::Failed(..) = self.reader { return Poll::Pending; } let first = self @@ -1032,7 +1054,7 @@ impl Consumer { fn poll_read_finish(&mut self, waiter: &kio::Waiter) -> Poll<()> { self.collect_pending(waiter); self.gated = false; - if self.track_error.is_some() { + if let Reader::Failed(..) = self.reader { return Poll::Ready(()); } loop { @@ -1045,7 +1067,9 @@ impl Consumer { let next = match ready!(self.subscriber().poll_recv_group(waiter)) { Ok(next) => next, Err(err) => { - self.track_error = Some(err.into()); + if let Reader::Reading(track) = std::mem::replace(&mut self.reader, Reader::Ended) { + self.reader = Reader::Failed(track, err.into()); + } return Poll::Ready(()); } }; @@ -1162,7 +1186,7 @@ impl Consumer { /// nothing older. pub fn set_delay(&mut self, delay: Delay) { // An ended reader has no subscription left to tune. - let Some(track) = &mut self.track else { + let (Reader::Reading(track) | Reader::Failed(track, _)) = &mut self.reader else { return; }; self.min_delay = delay.min.unwrap_or_default(); @@ -1514,6 +1538,14 @@ mod tests { use super::Container as ContainerTrait; use super::*; use crate::catalog::hang::Container; + + /// The subscription a consumer still reads. + fn subscribed(consumer: &Consumer) -> &moq_net::track::Subscriber { + match &consumer.reader { + Reader::Reading(track) | Reader::Failed(track, _) => track, + Reader::Ended => panic!("the reader ended"), + } + } use std::time::Duration; use bytes::Bytes; @@ -3729,7 +3761,7 @@ mod tests { max: Some(Duration::from_millis(500)), }); assert!( - consumer.startup, + matches!(consumer.startup, Startup::Earliest { .. }), "a local range names no start, so the start still reaches back" ); @@ -3797,7 +3829,7 @@ mod tests { Duration::from_millis(200), Duration::from_millis(300), ); - let subscription = consumer.track.as_ref().unwrap().subscription(); + let subscription = subscribed(&consumer).subscription(); assert_eq!(subscription.delay.min, Some(Duration::from_secs(2))); assert_eq!(subscription.delay.max, Some(Duration::from_millis(500))); assert_eq!(consumer.max_delay, Duration::from_millis(200)); @@ -3815,7 +3847,7 @@ mod tests { let consumer_track = track.subscribe(moq_net::track::Subscription::default().with_delay(delay)); let consumer = Playout::new(delay, Duration::from_millis(300)) .consumer(consumer_track, Container::Legacy(crate::container::Kind::Data)); - let subscription = consumer.track.as_ref().unwrap().subscription(); + let subscription = subscribed(&consumer).subscription(); assert_eq!(subscription.delay.min, Some(Duration::from_millis(100))); assert_eq!(subscription.delay.max, Some(Duration::from_millis(500))); assert_eq!(consumer.max_delay, Duration::from_millis(200)); @@ -3835,7 +3867,7 @@ mod tests { min: Some(Duration::from_millis(500)), max: None, }); - assert_eq!(consumer.track.as_ref().unwrap().subscription().delay.max, None); + assert_eq!(subscribed(&consumer).subscription().delay.max, None); write_group(&mut track, 5, &[ts(5_000_000)]); assert!( From 8870dc39ef8d4a9a682bdd031967a8bbd5736ff5 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 15:29:33 -0800 Subject: [PATCH 05/14] refactor(rtmp): the connected app name lives in the session's Connected state Co-Authored-By: Claude Opus 5.5 --- rs/moq-rtmp/src/rml/sessions/server/mod.rs | 76 +++++-------------- .../src/rml/sessions/server/session_state.rs | 6 +- 2 files changed, 25 insertions(+), 57 deletions(-) diff --git a/rs/moq-rtmp/src/rml/sessions/server/mod.rs b/rs/moq-rtmp/src/rml/sessions/server/mod.rs index c92f804eb33..bd1c0605424 100644 --- a/rs/moq-rtmp/src/rml/sessions/server/mod.rs +++ b/rs/moq-rtmp/src/rml/sessions/server/mod.rs @@ -52,7 +52,6 @@ pub struct ServerSession { start_time: Instant, serializer: ChunkSerializer, deserializer: ChunkDeserializer, - connected_app_name: Option, request: Option, current_state: SessionState, fms_version: String, @@ -75,7 +74,6 @@ impl ServerSession { start_time: Instant::now(), serializer: ChunkSerializer::new(), deserializer: ChunkDeserializer::new(), - connected_app_name: None, request: None, current_state: SessionState::Started, fms_version: config.fms_version, @@ -487,7 +485,7 @@ impl ServerSession { transaction_id: f64, command_object: Value<'_>, ) -> Result, ServerSessionError> { - if self.current_state != SessionState::Started || self.request.is_some() { + if !matches!(self.current_state, SessionState::Started) || self.request.is_some() { return Err(ServerSessionError::RepeatedConnect); } @@ -649,13 +647,8 @@ impl ServerSession { &mut self, mut arguments: Values<'_>, ) -> Result, ServerSessionError> { - if self.current_state != SessionState::Connected { + let Some(app_name) = self.app_name() else { return Ok(Vec::new()); - } - - let app_name = match self.connected_app_name { - Some(ref name) => name.clone(), - None => return Ok(Vec::new()), }; // First argument should be the stream id to close @@ -720,7 +713,7 @@ impl ServerSession { &mut self, transaction_id: f64, ) -> Result, ServerSessionError> { - if self.current_state != SessionState::Connected || self.active_stream.is_some() { + if self.app_name().is_none() || self.active_stream.is_some() { let packet = self.create_error_packet( "NetConnection.Call.Failed", "one stream is allowed after connect", @@ -763,7 +756,7 @@ impl ServerSession { return Ok(vec![ServerSessionResult::OutboundResponse(packet)]); } - if self.current_state != SessionState::Connected { + let Some(app_name) = self.app_name() else { let packet = self.create_error_packet( "NetStream.Publish.Start", "Can't publish before connecting", @@ -771,7 +764,7 @@ impl ServerSession { stream_id, )?; return Ok(vec![ServerSessionResult::OutboundResponse(packet)]); - } + }; if !matches!( self.active_stream.as_ref().filter(|_| stream_id == 1), @@ -788,19 +781,6 @@ impl ServerSession { return Ok(vec![ServerSessionResult::OutboundResponse(packet)]); } - let app_name = match self.connected_app_name { - Some(ref name) => name.clone(), - None => { - let packet = self.create_error_packet( - "NetStream.Publish.Start", - "Can't publish before connecting", - transaction_id, - stream_id, - )?; - return Ok(vec![ServerSessionResult::OutboundResponse(packet)]); - } - }; - let stream_key = match arguments.next().unwrap() { Value::Utf8String(stream_key) => stream_key.to_owned(), _ => { @@ -880,7 +860,7 @@ impl ServerSession { return Ok(vec![ServerSessionResult::OutboundResponse(packet)]); } - if self.current_state != SessionState::Connected { + let Some(app_name) = self.app_name() else { let packet = self.create_error_packet( "NetStream.Play.Start", "Can't play before connecting", @@ -888,7 +868,7 @@ impl ServerSession { stream_id, )?; return Ok(vec![ServerSessionResult::OutboundResponse(packet)]); - } + }; if !matches!( self.active_stream.as_ref().filter(|_| stream_id == 1), @@ -905,19 +885,6 @@ impl ServerSession { return Ok(vec![ServerSessionResult::OutboundResponse(packet)]); } - let app_name = match self.connected_app_name { - Some(ref name) => name.clone(), - None => { - let packet = self.create_error_packet( - "NetStream.Play.Start", - "Can't play before connecting", - transaction_id, - stream_id, - )?; - return Ok(vec![ServerSessionResult::OutboundResponse(packet)]); - } - }; - let stream_key = match arguments.next().unwrap() { Value::Utf8String(stream_key) => stream_key.to_owned(), _ => { @@ -1024,7 +991,7 @@ impl ServerSession { return None; } - let app_name = self.connected_app_name.clone()?; + let app_name = self.app_name()?; let StreamState::Publishing { ref stream_key, .. } = self.active_stream.as_ref().filter(|_| stream_id == 1)?.current_state else { @@ -1049,14 +1016,9 @@ impl ServerSession { stream_id: u32, timestamp: RtmpTimestamp, ) -> Result, ServerSessionError> { - if self.current_state != SessionState::Connected { + let Some(app_name) = self.app_name() else { // Audio data sent before connected, just ignore it. return Ok(Vec::new()); - } - - let app_name = match self.connected_app_name { - Some(ref x) => x.clone(), - None => return Ok(Vec::new()), // No app name so we aren't in a valid connection state. }; let publish_stream_key = match self.active_stream.as_ref().filter(|_| stream_id == 1) { @@ -1133,14 +1095,9 @@ impl ServerSession { stream_id: u32, timestamp: RtmpTimestamp, ) -> Result, ServerSessionError> { - if self.current_state != SessionState::Connected { + let Some(app_name) = self.app_name() else { // Video data sent before connected, just ignore it. return Ok(Vec::new()); - } - - let app_name = match self.connected_app_name { - Some(ref x) => x.clone(), - None => return Ok(Vec::new()), // No app name so we aren't in a valid connection state. }; let publish_stream_key = match self.active_stream.as_ref().filter(|_| stream_id == 1) { @@ -1172,13 +1129,22 @@ impl ServerSession { Ok(Vec::new()) } + /// The app name a connect accepted, while connected. + fn app_name(&self) -> Option { + match &self.current_state { + SessionState::Connected { app_name } => Some(app_name.clone()), + SessionState::Started | SessionState::Completed => None, + } + } + fn accept_connection_request( &mut self, app_name: String, transaction_id: f64, ) -> Result, ServerSessionError> { - self.connected_app_name = Some(app_name.clone()); - self.current_state = SessionState::Connected; + self.current_state = SessionState::Connected { + app_name: app_name.clone(), + }; let mut command_object_properties = HashMap::new(); command_object_properties.insert("fmsVer".to_string(), Amf0Value::Utf8String(self.fms_version.clone())); diff --git a/rs/moq-rtmp/src/rml/sessions/server/session_state.rs b/rs/moq-rtmp/src/rml/sessions/server/session_state.rs index 330bec0e73e..c887317fbac 100644 --- a/rs/moq-rtmp/src/rml/sessions/server/session_state.rs +++ b/rs/moq-rtmp/src/rml/sessions/server/session_state.rs @@ -1,6 +1,8 @@ -#[derive(Eq, PartialEq)] pub enum SessionState { Started, - Connected, + /// A connect was accepted for `app_name`. + Connected { + app_name: String, + }, Completed, } From 84bac6d357cc5e9483590ca8c42bfeb48701d6dd Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 15:32:34 -0800 Subject: [PATCH 06/14] fix(webrtc): an ICE agent's failure is a phase every later next reports Co-Authored-By: Claude Opus 5.5 --- rs/moq-webrtc/src/ice/agent.rs | 71 +++++++++++++++++++++------------- 1 file changed, 45 insertions(+), 26 deletions(-) diff --git a/rs/moq-webrtc/src/ice/agent.rs b/rs/moq-webrtc/src/ice/agent.rs index a4331f8050c..57b7b5d3fb4 100644 --- a/rs/moq-webrtc/src/ice/agent.rs +++ b/rs/moq-webrtc/src/ice/agent.rs @@ -37,7 +37,7 @@ const STUN_SENDS: u32 = 7; const STUN_LAST_WAIT: u32 = 16; /// Why an [`Agent`] stopped. -#[derive(Debug, thiserror::Error)] +#[derive(Clone, Debug, thiserror::Error)] pub enum Error { /// The peer disconnected, str0m closed the connection, or the inbound queue ended. #[error("peer connection closed")] @@ -91,6 +91,17 @@ struct Query { deadline: Instant, } +/// Where the connection is in its life. +enum Phase { + /// An offer awaits its answer, which holds off the [`ESTABLISH_TIMEOUT`]. + Held, + /// ICE has yet to connect; the [`ESTABLISH_TIMEOUT`] runs from `started`. + Establishing { started: Instant }, + Connected, + /// The connection ended, for this reason: every later [`Agent::next`] reports it. + Failed(Error), +} + /// Drives one [`Rtc`] over a UDP socket until the connection ends. pub struct Agent { rtc: Rtc, @@ -108,15 +119,11 @@ pub struct Agent { /// When every STUN query answered or gave up, once [`Event::Gathered`] went out. gathered: Option, events: VecDeque, - /// Why the connection ended, found while draining and reported by the next [`Agent::next`]. - failed: Option, /// When str0m next wants a timeout, as of the last drain. timeout: Instant, /// Datagrams the socket refused for lack of buffer space, sent first next time. outbox: VecDeque<(Vec, SocketAddr)>, - /// When the [`ESTABLISH_TIMEOUT`] started, or `None` while an offer awaits its answer. - started: Option, - connected: bool, + phase: Phase, } impl Agent { @@ -138,11 +145,9 @@ impl Agent { stun: Vec::new(), gathered: None, events: VecDeque::new(), - failed: None, timeout: now, outbox: VecDeque::new(), - started: Some(now), - connected: false, + phase: Phase::Establishing { started: now }, }; // Signaling already changed the connection. agent.drain(); @@ -188,14 +193,16 @@ impl Agent { /// for an offer whose answer has yet to arrive: signaling time is the caller's. #[cfg_attr(not(feature = "p2p"), allow(dead_code, reason = "only the p2p transport offers"))] pub fn awaiting_answer(mut self) -> Self { - self.started = None; + self.phase = Phase::Held; self } /// Change the connection through a guard that drains what the change produced /// when dropped: transmits are sent, and events wait for [`Agent::next`]. pub fn rtc_mut(&mut self) -> RtcMut<'_> { - self.started.get_or_insert_with(Instant::now); + if let Phase::Held = self.phase { + self.phase = Phase::Establishing { started: Instant::now() }; + } self.change() } @@ -213,8 +220,8 @@ impl Agent { if let Some(event) = self.events.pop_front() { return Ok(event); } - if let Some(err) = self.failed.take() { - return Err(err); + if let Phase::Failed(err) = &self.phase { + return Err(err.clone()); } if self.gathered.is_none() && self.stun.is_empty() { self.gathered = Some(Instant::now()); @@ -232,11 +239,13 @@ impl Agent { // A dead Rtc (DTLS failure, explicit disconnect) reports a never-firing // timeout instead of an error, which would park this loop forever. if !self.rtc.is_alive() { - return Err(Error::Closed); + self.fail(Error::Closed); + continue; } let establish = self.establish(); if establish.is_some_and(|at| at <= Instant::now()) { - return Err(Error::Timeout); + self.fail(Error::Timeout); + continue; } let deadline = self.stun.iter().map(|q| q.deadline).chain(establish); @@ -248,7 +257,8 @@ impl Agent { packet = self.inbound.packets.recv() => { let Some((data, src)) = packet else { // Every sender dropped: nothing more will arrive. - return Err(Error::Closed); + self.fail(Error::Closed); + continue; }; self.receive(&data, src); continue; @@ -266,24 +276,26 @@ impl Agent { } } - /// When [`ESTABLISH_TIMEOUT`] expires, or `None` while it is held or ICE connected. + /// When [`ESTABLISH_TIMEOUT`] expires, or `None` while it is held, gathering, or over. fn establish(&self) -> Option { - match (self.started, self.gathered) { - (Some(started), Some(gathered)) if !self.connected => Some(started.max(gathered) + ESTABLISH_TIMEOUT), + match (&self.phase, self.gathered) { + (Phase::Establishing { started }, Some(gathered)) => Some((*started).max(gathered) + ESTABLISH_TIMEOUT), _ => None, } } /// Poll str0m until it asks for a timeout: transmits are sent, events queued. fn drain(&mut self) { - while self.failed.is_none() { + while !matches!(self.phase, Phase::Failed(_)) { let output = match self.rtc.poll_output() { Ok(output) => output, // Before ICE connects no DTLS record can reach the peer, so a DTLS failure // is its handshake giving up on retransmitting into the void. Its flights // (~31s, randomly jittered) race the establishment deadline, so report // either as ICE never connecting. - Err(str0m::RtcError::Dtls(_)) if !self.connected => return self.fail(Error::Timeout), + Err(str0m::RtcError::Dtls(_)) if !matches!(self.phase, Phase::Connected) => { + return self.fail(Error::Timeout); + } Err(err) => return self.fail(Error::rtc(err)), }; match output { @@ -299,7 +311,9 @@ impl Agent { if *state == IceConnectionState::Disconnected { return self.fail(Error::Closed); } - self.connected |= state.is_connected(); + if state.is_connected() { + self.phase = Phase::Connected; + } } self.events.push_back(Event::Rtc(event)); } @@ -309,7 +323,9 @@ impl Agent { /// Keep the first reason the connection ended. fn fail(&mut self, err: Error) { - self.failed.get_or_insert(err); + if !matches!(self.phase, Phase::Failed(_)) { + self.phase = Phase::Failed(err); + } } /// Send without waiting, keeping the datagram for later when the socket is full. @@ -500,12 +516,12 @@ mod tests { #[tokio::test] async fn awaiting_answer_holds_the_deadline() { let mut agent = unpolled().awaiting_answer(); - assert_eq!(agent.started, None); + assert!(matches!(agent.phase, Phase::Held)); // The agent's own changes, such as timeouts and STUN, leave it held. drop(agent.change()); - assert_eq!(agent.started, None); + assert!(matches!(agent.phase, Phase::Held)); drop(agent.rtc_mut()); - assert!(agent.started.is_some()); + assert!(matches!(agent.phase, Phase::Establishing { .. })); } #[tokio::test] @@ -553,6 +569,9 @@ mod tests { }; assert!(matches!(err, Error::Timeout), "{err:?}"); assert_eq!(agent.establish(), None, "the deadline had yet to start"); + // The reason sticks: driving the agent again reports it again. + let again = agent.next().await; + assert!(matches!(again, Err(Error::Timeout)), "{again:?}"); } #[test] From 19c0df2b6216008ed5951afc375dc90eec0c864c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 15:35:37 -0800 Subject: [PATCH 07/14] refactor(webrtc): the p2p channel handout is one phase Co-Authored-By: Claude Opus 5.5 --- rs/moq-webrtc/src/p2p/mod.rs | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/rs/moq-webrtc/src/p2p/mod.rs b/rs/moq-webrtc/src/p2p/mod.rs index 8abe06a9072..abcdceacc4a 100644 --- a/rs/moq-webrtc/src/p2p/mod.rs +++ b/rs/moq-webrtc/src/p2p/mod.rs @@ -532,8 +532,7 @@ impl Peer { role, max_message, channel: None, - waiter: None, - taken: false, + handout: Handout::Unasked, }; use tracing::Instrument; tokio::spawn(moq_tokio::panic::isolate(driver.run()).instrument(tracing::Span::current())); @@ -638,10 +637,17 @@ struct Driver { /// The remote peer's SCTP message limit, once its description is applied. max_message: Option, channel: Option>, - /// The session waiting for the channel to open. - waiter: Option>>, - /// Whether a session already asked for the channel, which only one may carry. - taken: bool, + handout: Handout, +} + +/// Which session the channel goes to: only one may carry it. +enum Handout { + /// No session asked for the channel yet. + Unasked, + /// A session waits for the channel to open or fail to. + Waiting(oneshot::Sender>), + /// A session took the channel, or heard why it never opened. + Taken, } impl Driver { @@ -679,7 +685,7 @@ impl Driver { Error::Closed => tracing::debug!("peer connection closed"), err => tracing::debug!(%err, "peer connection failed"), } - if let Some(waiter) = self.waiter.take() { + if let Handout::Waiting(waiter) = self.handout { let _ = waiter.send(Err(err)); } } @@ -743,12 +749,11 @@ impl Driver { } Command::Candidate(candidate) => self.agent.rtc_mut().add_remote_candidate(candidate), Command::Channel(reply) => { - if self.taken { + if !matches!(self.handout, Handout::Unasked) { let _ = reply.send(Err(Error::Taken)); return; } - self.taken = true; - self.waiter = Some(reply); + self.handout = Handout::Waiting(reply); self.deliver(); } } @@ -868,7 +873,9 @@ impl Driver { let Some(channel) = &mut self.channel else { return; }; - let Some(waiter) = self.waiter.take() else { + let handout = std::mem::replace(&mut self.handout, Handout::Taken); + let Handout::Waiting(waiter) = handout else { + self.handout = handout; return; }; let result = match channel { From 3ce232e21af5be97366882f4da01c42c5041fdbd Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 15:37:18 -0800 Subject: [PATCH 08/14] refactor(mux): a jitter track's admission is one phase Co-Authored-By: Claude Opus 5.5 --- rs/moq-mux/src/jitter.rs | 42 ++++++++++++++++++++++++++-------------- 1 file changed, 27 insertions(+), 15 deletions(-) diff --git a/rs/moq-mux/src/jitter.rs b/rs/moq-mux/src/jitter.rs index 00209a8c89d..a654f641ddb 100644 --- a/rs/moq-mux/src/jitter.rs +++ b/rs/moq-mux/src/jitter.rs @@ -221,7 +221,9 @@ impl Buffer { let cut = std::mem::take(&mut track.queue).len() as u64; track.bytes = 0; // A cancel resumes the old publisher, whose next frames may reference the cut ones. - track.waiting |= cut > 0; + if cut > 0 { + track.admit = Admit::Waiting; + } match track.started { true => self.active.dropped += cut, false => self.active.trimmed += cut, @@ -741,6 +743,18 @@ struct Floor { began: Instant, } +/// Which frames a track admits to its queue. +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +enum Admit { + /// Every frame that makes its deadline. + Flowing, + /// None until the next sync frame. + Waiting, + /// It resumed at its last sync frame after waiting, whose leading frames are dropped too: + /// they reference the frames dropped while waiting. + Resumed, +} + struct Track { /// Frames in arrival order, each with its generation, decode time, deadline and bytes. queue: VecDeque<(u64, Decode, Instant, T, usize)>, @@ -754,11 +768,7 @@ struct Track { arrived: Instant, /// The generation of the last frame. generation: u64, - /// Frames are dropped until the next sync frame. - waiting: bool, - /// Whether the track resumed at its last sync frame after waiting, whose leading frames are - /// dropped too. - resumed: bool, + admit: Admit, /// Whether a frame of it has gone out. Until one has, a loss takes everything it holds. started: bool, } @@ -1035,8 +1045,7 @@ impl Engine { decode: arrival.decode, arrived: arrival.arrived, generation, - waiting: false, - resumed: false, + admit: Admit::Flowing, started: false, }); track.restart = arrival.restart; @@ -1045,16 +1054,19 @@ impl Engine { track.generation = generation; let push = match deadline { _ if stale => { - track.waiting = true; + track.admit = Admit::Waiting; Push::Waiting } - _ if track.waiting && !arrival.sync => Push::Waiting, - _ if track.resumed && arrival.leading => Push::Waiting, + _ if track.admit == Admit::Waiting && !arrival.sync => Push::Waiting, + _ if track.admit == Admit::Resumed && arrival.leading => Push::Waiting, Some(deadline) if arrival.arrived <= deadline || self.delay.is_zero() => { + // A frame past the checks above while waiting is a sync frame. if arrival.sync { - track.resumed = track.waiting; + track.admit = match track.admit { + Admit::Waiting => Admit::Resumed, + Admit::Flowing | Admit::Resumed => Admit::Flowing, + }; } - track.waiting = false; let cost = arrival.cost(); track.bytes += cost; track @@ -1065,7 +1077,7 @@ impl Engine { } // Past the deadline, or so far off the clock that no instant holds it. _ => { - track.waiting = true; + track.admit = Admit::Waiting; Push::Late } }; @@ -1073,7 +1085,7 @@ impl Engine { Push::Queued => {} _ if track.started => self.dropped += 1, // A leading frame of the sync frame the track starts at, which stays queued. - _ if !track.waiting => self.trimmed += 1, + _ if track.admit != Admit::Waiting => self.trimmed += 1, _ => { self.trimmed += 1 + track.queue.len() as u64; track.queue.clear(); From cd9a7da10394e9d658bf2cdc19118ef91440aebd Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 15:53:29 -0800 Subject: [PATCH 09/14] style: rustfmt Co-Authored-By: Claude Opus 5.5 --- rs/moq-gst/src/sink/imp.rs | 10 ++++++++-- rs/moq-gst/src/sink/pad.rs | 4 +--- rs/moq-gst/src/source/imp.rs | 5 ++++- rs/moq-hls/src/export/segments.rs | 8 ++++---- rs/moq-hls/src/import.rs | 6 +++++- rs/moq-mux/src/container/source.rs | 4 +++- rs/moq-webrtc/src/ice/agent.rs | 8 ++++++-- 7 files changed, 31 insertions(+), 14 deletions(-) diff --git a/rs/moq-gst/src/sink/imp.rs b/rs/moq-gst/src/sink/imp.rs index eb405a63c68..f27e66b3a58 100644 --- a/rs/moq-gst/src/sink/imp.rs +++ b/rs/moq-gst/src/sink/imp.rs @@ -2469,8 +2469,14 @@ mod tests { let start = kio::clock::now(); let finished = moq_mux::Linger::new([broadcast], track, linger); let lingering = tokio::spawn(linger_task(finished, sink.downgrade(), session)); - sink.imp().control.lock().unwrap().live.as_mut().expect("live session").drain = - Drain::Lingering(lingering.abort_handle()); + sink.imp() + .control + .lock() + .unwrap() + .live + .as_mut() + .expect("live session") + .drain = Drain::Lingering(lingering.abort_handle()); kio::clock::sleep(linger - Duration::from_secs(1)).await; let mut late = consumer.track("video").unwrap().subscribe(None).await.unwrap(); diff --git a/rs/moq-gst/src/sink/pad.rs b/rs/moq-gst/src/sink/pad.rs index df865ebad32..33b4013e8d6 100644 --- a/rs/moq-gst/src/sink/pad.rs +++ b/rs/moq-gst/src/sink/pad.rs @@ -843,9 +843,7 @@ impl Pad { let Some(track) = self.track() else { return Ok(()); }; - let timestamp = if matches!(track, Sink::Opaque(_)) - && buffer.pts().is_none() - && self.state == PadState::Active + let timestamp = if matches!(track, Sink::Opaque(_)) && buffer.pts().is_none() && self.state == PadState::Active { sample .running diff --git a/rs/moq-gst/src/source/imp.rs b/rs/moq-gst/src/source/imp.rs index d5f0d2c2dca..aa69a2e0802 100644 --- a/rs/moq-gst/src/source/imp.rs +++ b/rs/moq-gst/src/source/imp.rs @@ -1582,7 +1582,10 @@ impl Follower { return; }; for (rendition, entry) in &mut self.renditions { - if matches!(entry.reading, Reading::Idle) && only(rendition) && serves(instance, entry.shape.instance.as_ref()) { + if matches!(entry.reading, Reading::Idle) + && only(rendition) + && serves(instance, entry.shape.instance.as_ref()) + { self.next_id += 1; let (cancel, cancelled) = watch::channel(false); let live = Arc::new(AtomicBool::new(false)); diff --git a/rs/moq-hls/src/export/segments.rs b/rs/moq-hls/src/export/segments.rs index 2a6a59530e2..ae4a3ed76e3 100644 --- a/rs/moq-hls/src/export/segments.rs +++ b/rs/moq-hls/src/export/segments.rs @@ -409,12 +409,12 @@ impl Producer { /// Poll until the window lists a row, ends, fails, or closes. pub fn poll_listed(&self, waiter: &kio::Waiter) -> Poll<()> { - match self.state.poll_ref(waiter, |state| { - match !state.rows.is_empty() || !state.live() { + match self + .state + .poll_ref(waiter, |state| match !state.rows.is_empty() || !state.live() { true => Poll::Ready(()), false => Poll::Pending, - } - }) { + }) { Poll::Ready(_) => Poll::Ready(()), Poll::Pending => Poll::Pending, } diff --git a/rs/moq-hls/src/import.rs b/rs/moq-hls/src/import.rs index 1a0a7e4f6c0..9cb2693591c 100644 --- a/rs/moq-hls/src/import.rs +++ b/rs/moq-hls/src/import.rs @@ -605,7 +605,11 @@ impl TrackState { let resource = resolve_map(url, map.byte_range.as_ref())?; // The resolved resource IS the init segment's identity: same bytes, same generation. - if self.generation.as_ref().is_some_and(|generation| generation.map == resource) { + if self + .generation + .as_ref() + .is_some_and(|generation| generation.map == resource) + { return Ok(()); } diff --git a/rs/moq-mux/src/container/source.rs b/rs/moq-mux/src/container/source.rs index fa80f3324c6..63214a09041 100644 --- a/rs/moq-mux/src/container/source.rs +++ b/rs/moq-mux/src/container/source.rs @@ -559,7 +559,9 @@ impl ExportSource { if let SourceState::Subscribing { pending, instance, .. } = &self.state { let track = match pending.poll_ok(waiter) { Poll::Ready(Ok(track)) => track, - Poll::Ready(Err(_)) | Poll::Pending if instance.as_ref().is_some_and(|i| i.poll_closed(waiter).is_ready()) => { + Poll::Ready(Err(_)) | Poll::Pending + if instance.as_ref().is_some_and(|i| i.poll_closed(waiter).is_ready()) => + { return self.end(); } Poll::Ready(Err(err)) => return Poll::Ready(Err(err.into())), diff --git a/rs/moq-webrtc/src/ice/agent.rs b/rs/moq-webrtc/src/ice/agent.rs index bb81322d842..324c7e16674 100644 --- a/rs/moq-webrtc/src/ice/agent.rs +++ b/rs/moq-webrtc/src/ice/agent.rs @@ -97,7 +97,9 @@ enum Phase { /// An offer awaits its answer, which holds off the [`ESTABLISH_TIMEOUT`]. Held, /// ICE has yet to connect; the [`ESTABLISH_TIMEOUT`] runs from `started`. - Establishing { started: Instant }, + Establishing { + started: Instant, + }, Connected, /// The connection ended, for this reason: every later [`Agent::next`] reports it. Failed(Error), @@ -202,7 +204,9 @@ impl Agent { /// when dropped: transmits are sent, and events wait for [`Agent::next`]. pub fn rtc_mut(&mut self) -> RtcMut<'_> { if let Phase::Held = self.phase { - self.phase = Phase::Establishing { started: Instant::now() }; + self.phase = Phase::Establishing { + started: Instant::now(), + }; } self.change() } From c2d4d397441b37f5a3c8e25659aaa67255ecabb8 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 15:53:29 -0800 Subject: [PATCH 10/14] quest: rewrite mux-gst to the TS and fMP4 export lifecycles that remain Co-Authored-By: Claude Opus 5.5 --- quest/m1/explicit-state/README.md | 2 +- quest/m1/explicit-state/mux-gst.md | 71 +++++++++++------------------- 2 files changed, 27 insertions(+), 46 deletions(-) diff --git a/quest/m1/explicit-state/README.md b/quest/m1/explicit-state/README.md index 2850e41ae87..6fd91a4bfaf 100644 --- a/quest/m1/explicit-state/README.md +++ b/quest/m1/explicit-state/README.md @@ -79,7 +79,7 @@ which collapses that state and waits on [Drop set](/quest/m1/drop-set.md). - [A failed finish is final](/quest/m1/explicit-state/finish-final.md) - producers and importers are never half-finished, and refuse input after finish - [Track and group end-of-life](/quest/m1/explicit-state/track-end.md) - moq-net's track and group outcomes are one enum each, in Rust and JS - [moq-net phase data](/quest/m1/explicit-state/net-phases.md) - moq-net's session and subscription state machines keep each phase's data in its variant -- [moq-mux and moq-gst lifecycles](/quest/m1/explicit-state/mux-gst.md) - export sources, TS and fMP4 export tracks, and gst pads are explicit state +- [TS and fMP4 export lifecycles](/quest/m1/explicit-state/mux-gst.md) - the TS export program and tracks and the fMP4 export track are explicit state ## Related diff --git a/quest/m1/explicit-state/mux-gst.md b/quest/m1/explicit-state/mux-gst.md index f4f0b63c0de..ead70fb397a 100644 --- a/quest/m1/explicit-state/mux-gst.md +++ b/quest/m1/explicit-state/mux-gst.md @@ -1,57 +1,38 @@ -# [M] moq-mux and moq-gst lifecycles +# [M] TS and fMP4 export lifecycles ## Goal -The lifecycles of moq-mux and moq-gst export and ingest are explicit state: -export sources, TS and fMP4 export tracks and programs, the HLS segment -window, the container consumer's startup, and the GStreamer sink and source -pads. Each phase's data lives in its variant, and no `.expect()` or flag -ordering stands in for a phase. +The TS and fMP4 export lifecycles in moq-mux are explicit state: the TS +export program and its tracks, the TS follower, passthrough, and group +buffer, and the fMP4 export track. Each phase's data lives in its variant, +and no `.expect()` or flag ordering stands in for a phase. ## Plan The shared decisions are in the [epic](/quest/m1/explicit-state/README.md). -No confirmed bug is folded into this child. Reproduce these two first: +No confirmed bug is folded into this child. Two suspected ones were checked +and are not defects: -- **fMP4 export** (`rs/moq-mux/src/container/fmp4/export.rs`): a track that - ends before it is ever described, while the catalog stays live, may keep - `init_ready()` false forever. -- **TS export track** (`rs/moq-mux/src/container/ts/export.rs`): - - Withdrawing a track keeps its parked frames, so it can become both - `withdrawn` and `listed`. - - `finished` carries five meanings, and the "gone" predicate ANDs eight - conditions. +- An fMP4 export track that ends before it is described, while the catalog + stays live, keeps `init_ready()` false. That wait is bounded: once other + tracks have media it fails at the init queue limit, naming the track. + Otherwise the live catalog can still move the rendition. +- A withdrawn TS track whose parked frames already went out stays listed. + This is intended, and `revision_test.rs` covers it. Instances to redesign: -- **TS export `Program`**: `catalog`, `catalog_ended`, `cataloged`, - `retired`, `left`, `psi`, and others. `resume` hand-resets six fields. -- **`ExportSource`** (`container/source.rs`): `media`, `priority_control`, - `instance`, `live`, and `after` belong inside the `SourceState` variants. -- **Container `Consumer`** (`container/consumer.rs`): the startup phase and - the `track`/`track_error` reader state. The JS twin is - `js/hang/src/container/consumer.ts`, whose `#checkMaxDelay` moves `#active` - without `#recordPresented`. Change both together. -- **HLS** (`rs/moq-hls`): - - The segment window keeps `ended`, `cut`, and `failed`, and `push` after - `end()` isn't refused. - - Retiring a `Claim` takes two locks. - - The importer's `TrackState` generation fields. -- **Catalog publish gate** (`catalog/producer.rs`): `Reservations` writes its - predicate twice, in two shapes. -- **TS `Follower.refused`** belongs inside `Serving`. The TS `Passthrough` - start and clock, and the `GroupBuffer` content kind, also become explicit. -- **moq-gst sink pads** (`rs/moq-gst/src/sink/request_pad.rs`, `pad.rs`, - `imp.rs`): - - The `ended` bool means something different from `Status::Ended`. - - `releasing` is cleared after removal. - - The element's `drained`/`lingering`/`eos_delivered` and the pad's - `reserved`/`track`/`catalog`/`caps`/`failed` encode phases. -- **moq-gst source** `Entry`'s `reader`/`draining`. -- **Others**: - - The RTMP `ServerSession`: the connected app name belongs inside - `SessionState::Connected`. - - The moq-webrtc ICE `Agent`: its failure isn't sticky. - - The p2p channel handout. - - The jitter `Track`. +- **TS export `Program`** (`rs/moq-mux/src/container/ts/export.rs`): + `catalog`, `catalog_ended`, `cataloged`, `retired`, `left`, `psi`, and + others. `resume` hand-resets six fields. +- **TS export track**: `finished` carries five meanings, and the "gone" + predicate ANDs eight conditions. +- **TS `Follower.refused`** (`ts/follower.rs`) belongs inside `Serving`. The + TS `Passthrough` start and clock, and the `GroupBuffer` content kind, also + become explicit. +- **fMP4 export track** (`rs/moq-mux/src/container/fmp4/export.rs`): + `source`, `described`, `finished`, `resume`, and `group_finished` encode + its phases. Land after + [moq-dev/moq#7916](https://github.com/moq-dev/moq/pull/7916), which + rewrites this file. From f2526ca7b0e70df2724437d3b1b53641c5cee97b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 15:55:00 -0800 Subject: [PATCH 11/14] refactor(hls): a window's lists check stays inside the crate Co-Authored-By: Claude Opus 5.5 --- rs/moq-hls/src/export/segments.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rs/moq-hls/src/export/segments.rs b/rs/moq-hls/src/export/segments.rs index ae4a3ed76e3..4c9b51d8267 100644 --- a/rs/moq-hls/src/export/segments.rs +++ b/rs/moq-hls/src/export/segments.rs @@ -336,7 +336,7 @@ impl Producer { } /// Whether the window still lists new rows: it has not ended, failed, or been cut. - pub fn lists(&self) -> bool { + pub(crate) fn lists(&self) -> bool { self.state.read().live() } From 8e51176503bd15c0c3ec9b3c14dd327079a28040 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 16:15:24 -0800 Subject: [PATCH 12/14] fix(gst): a rendition already draining keeps draining across catalog updates Co-Authored-By: Claude Opus 5.5 --- rs/moq-gst/src/source/imp.rs | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/rs/moq-gst/src/source/imp.rs b/rs/moq-gst/src/source/imp.rs index aa69a2e0802..c6420807f92 100644 --- a/rs/moq-gst/src/source/imp.rs +++ b/rs/moq-gst/src/source/imp.rs @@ -1468,7 +1468,10 @@ impl Follower { if !drains { return false; } - if let Reading::Reader(reader) = std::mem::replace(&mut entry.reading, Reading::Idle) { + // A later catalog update finds it already draining: it keeps playing out. + if let Reading::Reader(reader) | Reading::Draining(reader) = + std::mem::replace(&mut entry.reading, Reading::Idle) + { entry.reading = Reading::Draining(reader); } true @@ -3231,7 +3234,8 @@ mod session_tests { /// short: the pad owes downstream every frame of the track and an EOS. /// /// The subscriber's view of that arrival order is reproduced exactly: the head of the track, - /// then the catalog update, then the tail and the clean end. + /// then the catalog update, then the tail and the clean end. A second update lands while the + /// rendition drains, which must leave it draining. #[test] fn a_retired_rendition_drains_to_eos() { const HEAD: u64 = 3; @@ -3248,6 +3252,9 @@ mod session_tests { let _audio = broadcast .create_track("audio", hang::container::track_info(hang::catalog::PRIORITY.audio)) .unwrap(); + let _audio2 = broadcast + .create_track("audio2", hang::container::track_info(hang::catalog::PRIORITY.audio)) + .unwrap(); { let mut guard = catalog.modify().unwrap(); guard.video.renditions = BTreeMap::from([("video".to_string(), video_rendition())]); @@ -3320,6 +3327,19 @@ mod session_tests { } await_pad(&element, "audio_"); + // A second update while the video drains, whose new audio pad proves it was acted on. + { + let mut guard = catalog.modify().unwrap(); + guard.audio.renditions.insert("audio2".to_string(), audio_rendition()); + } + for _ in 0..100 { + if pads(&element, "audio_").len() == 2 { + break; + } + block(Duration::from_millis(50)); + } + assert_eq!(pads(&element, "audio_").len(), 2, "the second update never landed"); + // A reader the update cancelled still has to notice. It takes its pad with it when it does, // so the wait is only ever served in full by one that is still reading. for _ in 0..10 { From 8e236bf48252a5e660017314e80c9be401e2f324 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 16:27:27 -0800 Subject: [PATCH 13/14] test(gst): the second catalog update is awaited on pad-added, not polled Co-Authored-By: Claude Opus 5.5 --- rs/moq-gst/src/source/imp.rs | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/rs/moq-gst/src/source/imp.rs b/rs/moq-gst/src/source/imp.rs index c6420807f92..9c298a2b735 100644 --- a/rs/moq-gst/src/source/imp.rs +++ b/rs/moq-gst/src/source/imp.rs @@ -3328,17 +3328,16 @@ mod session_tests { await_pad(&element, "audio_"); // A second update while the video drains, whose new audio pad proves it was acted on. + let (added, added_rx) = std::sync::mpsc::channel(); + let handler = element.connect_pad_added(move |_, pad| { + let _ = added.send(pad.name().to_string()); + }); { let mut guard = catalog.modify().unwrap(); guard.audio.renditions.insert("audio2".to_string(), audio_rendition()); } - for _ in 0..100 { - if pads(&element, "audio_").len() == 2 { - break; - } - block(Duration::from_millis(50)); - } - assert_eq!(pads(&element, "audio_").len(), 2, "the second update never landed"); + while !added_rx.recv().expect("the element is alive").starts_with("audio_") {} + element.disconnect(handler); // A reader the update cancelled still has to notice. It takes its pad with it when it does, // so the wait is only ever served in full by one that is still reading. From c28871334f578a4fa4a4129c080916333edf2c9f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 21:16:19 -0800 Subject: [PATCH 14/14] fix(hls,mux): a restart clears an ended window; drop the unobservable skip write Rendition::restart clears its window on a generation change. The phase guard refused clear() on an ended window, so the old run's rows stayed listed under the new generation. clear() is refused only on a cut window again, as before the enum. The Rust skip_to presented_end write never changed output: any later read of presented_end before it is overwritten happens with a gap already pending, so it is removed. Co-Authored-By: Claude Opus 5.5 --- rs/moq-hls/src/export/segments.rs | 20 +++++++++++++++++--- rs/moq-mux/src/container/consumer.rs | 4 ---- 2 files changed, 17 insertions(+), 7 deletions(-) diff --git a/rs/moq-hls/src/export/segments.rs b/rs/moq-hls/src/export/segments.rs index 4c9b51d8267..21f0e793761 100644 --- a/rs/moq-hls/src/export/segments.rs +++ b/rs/moq-hls/src/export/segments.rs @@ -285,10 +285,11 @@ impl Producer { state.sequence = state.rows.front().unwrap().segment; } - /// Clear every retained row after the media timestamps went back, unless no row arrives again. + /// Clear every retained row, after the media timestamps went back or a new publisher run + /// replaced them. An ended or failed window stays so; a cut window keeps what it listed. pub fn clear(&self) { if let Ok(mut state) = self.state.write() - && state.live() + && !matches!(state.phase, Phase::Cut) { state.rows.clear(); state.resets += 1; @@ -706,13 +707,26 @@ mod tests { live.push(row(0, 0, 0, 2_000), window); live.end(); live.push(row(1, 1, 2_000, 2_000), window); - live.clear(); let snapshot = live.window(); assert!(snapshot.ended); let segments: Vec<_> = snapshot.segments.iter().map(|row| row.segment).collect(); assert_eq!(segments, [0]); } + // A restart still drops an ended window's rows, so the new run's generation never lists the + // previous run's segments. The window stays ended. + #[test] + fn an_ended_window_still_clears() { + let live = Producer::new(0); + let window = Duration::from_secs(30); + live.push(row(0, 0, 0, 2_000), window); + live.end(); + live.clear(); + let snapshot = live.window(); + assert!(snapshot.ended); + assert!(snapshot.segments.is_empty()); + } + // A cut freezes the listed rows: later records, trims, resets, and failures are refused, and // the window reads as ended. One that failed first keeps its failure. #[test] diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 4208b6507a3..29d0872c2a7 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -926,10 +926,6 @@ impl Consumer { tracing::debug!(old = self.current, new = new_current, "skipping slow groups"); - // The group left behind presented this far, which a later hole is measured from. - if let Some(end) = current_end { - self.presented_end = Some(end); - } self.current = new_current; self.note_group_edge(); Ok(())