Skip to content
Merged
5 changes: 4 additions & 1 deletion doc/bin/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -324,7 +324,10 @@ long for the same publisher instance to come back, and carries on with the same
stream. A replacement (a restarted publisher, under a new
[epoch](/concept/moq-lite#publisher-epochs)) exits 1 unless `--stitch` follows
it as a full program switch: a new PMT from its catalog, with every PID flagging
the break. Without `--stitch` the export stays on the old publisher while it is
the break. `--linger` also bounds a mid-stream stitch from the replacement
announcement through its first catalog snapshot; expiry exits 1. The default
`--linger 0s` follows only a replacement whose catalog is already available.
Without `--stitch` the export stays on the old publisher while it is
up. Only lite-07 sessions carry epochs, so on the default version every return
is a replacement. An export that fails while the broadcast stays up, such as on
a codec TS cannot carry, exits 1 without lingering. Only `ts` can mark a break,
Expand Down
4 changes: 3 additions & 1 deletion doc/bin/srt.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,9 @@ while its stale connection is still open replaces it at once: viewers see the
broadcast restart, and their next subscribe reaches the new feed. An
`export srt` stream ends with its broadcast; `--linger` and `--stitch` follow a
return or a replacement on the same connection, as they do for
[`export ts`](/bin/cli#retention-and-latency).
[`export ts`](/bin/cli#retention-and-latency). The linger also bounds a
mid-stream replacement's first catalog; expiry ends the export with an error.
With the default `--linger 0s`, that catalog must already be available.

A multi-program feed is refused unless `--program`
picks one: `--program 2` imports program 2 alone, and `--program all`
Expand Down
1 change: 0 additions & 1 deletion quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,6 @@ folded into Dropped sources.
- [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - a viewer joining at a recovery point drops the leading pictures it cannot decode; continuous viewers keep them
- [Audio warmup](/quest/m1/audio-warmup.md) - a viewer joining an Opus rendition mid-stream never hears the unconverged first 80 ms
- [#3021](/quest/m1/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md) - moq-gst picks the broadcast wall epoch; a restarted source is a new epoch, not a forward re-anchor
- [TS stitch catalog bound](/quest/m1/ts-follow-catalog-bound.md) - `--linger` bounds a mid-stream `--stitch` until the replacement's catalog arrives, so it ends loudly instead of stalling
- [moqsink first catalog](/quest/m1/gst-first-catalog.md) - a restarted `moqsink` lists every requested pad in its first catalog, so `moqsrc` resumes each on its held pad
- [moqsrc A/V alignment](/quest/m1/gst-src-av-sync.md) - every `moqsrc` pad of a run shares one timestamp reference and segment base
- [TS passthrough export](/quest/m1/ts-passthrough-export.md) - `export ts --passthrough` writes the `m2ts` track back byte-identical (less late drops) on a fixed delay
Expand Down
2 changes: 1 addition & 1 deletion quest/m1/initial-catalog-routing.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,5 +57,5 @@ decision rather than an invented retry or compatibility layer.
- [Fallback PR #5284](https://github.com/moq-dev/moq/pull/5284) - check its actual effect on this reproduction before duplicating work
- [Transport upgrade](/quest/m1/transport-upgrade/README.md) - existing handover and epoch contracts
- [TS duration fidelity](/quest/m0/ts-duration-fidelity.md) - previously captured only a short suffix, not zero-packet initial acquisition
- [Replacement catalog linger](/quest/m1/ts-follow-catalog-bound.md) - bounds a midstream stitch, not initial discovery
- [Replacement catalog linger #5305](https://github.com/moq-dev/moq/pull/5305) - bounds a midstream stitch, not initial discovery
- [Pair validation](/test/ts/README.md#table-anchoring-table-anchorpy) - independent grader/acquisition checks
34 changes: 0 additions & 34 deletions quest/m1/ts-follow-catalog-bound.md

This file was deleted.

2 changes: 1 addition & 1 deletion quest/m1/ts-same-instance-resume.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ required behavior or API change returns to the maintainer for a decision.
- [Validation PR #5328](https://github.com/moq-dev/moq/pull/5328#issuecomment-6114456593) - failing full-check evidence
- [Catalog identity controls #5333](https://github.com/moq-dev/moq/pull/5333) - initial acquisition preserves the selected contract
- [Live clock validation](/quest/m1/ts-live-clock.md) - independent local live failure
- [Replacement catalog linger](/quest/m1/ts-follow-catalog-bound.md) - #5305 owns the bound on a mid-stream switch's first catalog
- [Replacement catalog linger #5305](https://github.com/moq-dev/moq/pull/5305) - owns the bound on a mid-stream switch's first catalog
- [Same-epoch importers](/quest/m1/hop-aligned-import.md) - shared catalogs, tracks and source-derived group identity
- [Closed fallback #5284](https://github.com/moq-dev/moq/pull/5284) - early WebSocket closure and its transport-test fix
- [TS duration fidelity](/quest/m0/ts-duration-fidelity.md) - diagnose a shared end-of-stream cause only if reproduced
1 change: 1 addition & 0 deletions rs/moq-cli/src/args.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1060,6 +1060,7 @@ pub struct Transport {
/// How long to wait for the same publisher instance to come back once it ends (e.g. `10s`),
/// then carry on with the same stream. A replacement exits 1 unless `--stitch` is passed.
/// An export that fails while the broadcast is still up exits without waiting.
/// Also bounds a stitched replacement through its first catalog; zero requires it already available.
#[usage(long, default = "0s")]
pub linger: crate::duration::Duration,

Expand Down
1 change: 1 addition & 0 deletions rs/moq-cli/src/srt.rs
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ pub struct ExportArgs {
/// How long to wait for the same publisher instance to come back once it ends (e.g. `10s`),
/// then carry on with the same stream. A replacement ends the stream unless `--stitch`
/// is passed.
/// Also bounds a stitched replacement through its first catalog; zero requires it already available.
#[usage(long, default = "0s")]
pub linger: crate::duration::Duration,

Expand Down
236 changes: 234 additions & 2 deletions rs/moq-mux/src/container/ts/export_test.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7945,7 +7945,10 @@ async fn a_follower_stitches_onto_the_next_replacement_when_one_goes_before_it_r
let origin = crate::source::produce_origin();
let route = || moq_net::origin::Route::default().with_epoch(moq_net::Epoch::mint());
let first = publish_bare(&origin, Some(&moq_net::Epoch::mint()));
let mut follower = follower(&origin).await.with_stitch(true);
let mut follower = follower(&origin)
.await
.with_stitch(true)
.with_linger(Duration::from_secs(10));

// Replaced, but the replacement's catalog request is never answered before it goes.
let second = origin.publish("live", route()).unwrap();
Expand All @@ -7957,13 +7960,15 @@ async fn a_follower_stitches_onto_the_next_replacement_when_one_goes_before_it_r
"resolving the replacement"
);
drop((second, unanswered));
let third = publish_bare(&origin, Some(&moq_net::Epoch::mint()));
let mut third = publish_bare(&origin, Some(&moq_net::Epoch::mint()));
std::ops::DerefMut::deref_mut(&mut third.1.modify().unwrap());
assert!(
tokio::time::timeout(Duration::from_secs(1), follower.next())
.await
.is_err(),
"following the next replacement"
);
assert!(follower.export().cataloged(), "the replacement served its catalog");

// Once the first instance is gone too, the third one's end ends the export.
finish(first);
Expand Down Expand Up @@ -8338,6 +8343,233 @@ async fn a_follower_ignores_a_covering_prefix_while_the_exact_route_serves() {
assert!(matches!(end, Ok(None)), "no replacement: {end:?}");
}

/// Both the catalog subscription and its first snapshot share the restart's linger bound.
#[tokio::test(start_paused = true)]
async fn a_midstream_stitch_catalog_expires_at_the_linger() {
for snapshot in [false, true] {
for linger in [Duration::ZERO, Duration::from_secs(10)] {
let origin = crate::source::produce_origin();
let _first = publish_bare(&origin, Some(&moq_net::Epoch::mint()));
let mut follower = follower(&origin).await.with_stitch(true).with_linger(linger);
let second = origin
.publish(
"live",
moq_net::origin::Route::default().with_epoch(moq_net::Epoch::mint()),
)
.unwrap();
let _unanswered = second.dynamic();
let _silent = snapshot.then(|| second.create_track(hang::Catalog::DEFAULT_NAME, None).unwrap());
let waiter = kio::Waiter::noop();
if !linger.is_zero() {
assert!(follower.poll_next(&waiter).is_pending());
tokio::time::advance(linger - Duration::from_millis(1)).await;
assert!(follower.poll_next(&waiter).is_pending());
tokio::time::advance(Duration::from_millis(1)).await;
}
let std::task::Poll::Ready(Err(err)) = follower.poll_next(&waiter) else {
panic!("replacement catalog wait must fail at the linger, snapshot={snapshot}, linger={linger:?}");
};
assert!(err.to_string().contains("live"), "{err}");
assert!(err.to_string().contains("catalog"), "{err}");
}
}
}

/// A catalog ready before the bound completes the switch, including zero linger.
#[tokio::test(start_paused = true)]
async fn a_midstream_stitch_catalog_within_linger_clears_the_bound() {
for linger in [Duration::ZERO, Duration::from_secs(10)] {
let origin = crate::source::produce_origin();
let _first = publish_bare(&origin, Some(&moq_net::Epoch::mint()));
let mut follower = follower(&origin).await.with_stitch(true).with_linger(linger);
let epoch = moq_net::Epoch::mint();
let (_second, mut catalog) = publish_bare(&origin, Some(&epoch));
let waiter = kio::Waiter::noop();
if !linger.is_zero() {
assert!(follower.poll_next(&waiter).is_pending());
tokio::time::advance(linger - Duration::from_millis(1)).await;
}
std::ops::DerefMut::deref_mut(&mut catalog.modify().unwrap());
// Resolve the local async serving path so zero linger sees an already available
// subscription and snapshot, rather than a request still parked on the driver.
let broadcast = origin
.consume()
.request_broadcast("live", Some(epoch.clone()))
.await
.unwrap();
let mut available = crate::catalog::Consumer::<()>::new(&broadcast, crate::catalog::CatalogFormat::Hang)
.await
.unwrap();
use crate::catalog::Stream;
kio::wait(|waiter| available.poll_next(waiter)).await.unwrap().unwrap();
let next = follower.poll_next(&waiter);
assert!(next.is_pending(), "{next:?}, linger={linger:?}");
assert!(follower.export().cataloged());
assert_eq!(follower.export().instance(), Some(&epoch));
tokio::time::advance(Duration::from_secs(20)).await;
assert!(
follower.poll_next(&waiter).is_pending(),
"the first snapshot clears the bound"
);
}
}

/// A stitch onto a replacement that goes before it resolves leaves the export awaiting its
/// current replacement's catalog, by that replacement's own deadline.
#[tokio::test(start_paused = true)]
async fn a_nested_stitch_keeps_the_pending_catalog_deadline() {
let origin = crate::source::produce_origin();
let linger = Duration::from_secs(10);
let _first = publish_bare(&origin, Some(&moq_net::Epoch::mint()));
let mut follower = follower(&origin).await.with_stitch(true).with_linger(linger);
let start = tokio::time::Instant::now();

// Switched onto a replacement whose catalog never delivers a snapshot.
let _second = publish_bare(&origin, Some(&moq_net::Epoch::mint()));
assert!(
tokio::time::timeout(Duration::from_secs(2), follower.next())
.await
.is_err(),
"awaiting the replacement's catalog"
);

// Replaced again, but that one's catalog request is never answered before it goes.
let third = origin
.publish(
"live",
moq_net::origin::Route::default().with_epoch(moq_net::Epoch::mint()),
)
.unwrap();
let unanswered = third.dynamic();
assert!(
tokio::time::timeout(Duration::from_secs(1), follower.next())
.await
.is_err(),
"resolving the next replacement"
);
drop((third, unanswered));

let end = tokio::time::timeout(linger * 3, follower.next())
.await
.expect("the second replacement's deadline still bounds it");
let err = end.expect_err("a replacement without a catalog fails");
assert!(err.to_string().contains("catalog"), "{err}");
assert_eq!(start.elapsed(), linger);
}

/// A replacement restored after its own deadline, when the next one goes before it resolves,
/// fails even with its late first snapshot ready.
#[tokio::test(start_paused = true)]
async fn a_nested_stitch_restored_after_its_deadline_fails() {
let origin = crate::source::produce_origin();
let linger = Duration::from_secs(10);
let _first = publish_bare(&origin, Some(&moq_net::Epoch::mint()));
let mut follower = follower(&origin).await.with_stitch(true).with_linger(linger);
let start = tokio::time::Instant::now();

// Switched onto a replacement whose catalog has no snapshot yet, bounded at 10s.
let epoch = moq_net::Epoch::mint();
let (_second, mut catalog) = publish_bare(&origin, Some(&epoch));
assert!(
tokio::time::timeout(Duration::from_secs(2), follower.next())
.await
.is_err(),
"awaiting the replacement's catalog"
);

// Replaced again at 2s, bounded at 12s, but that one's catalog request is never answered.
let third = origin
.publish(
"live",
moq_net::origin::Route::default().with_epoch(moq_net::Epoch::mint()),
)
.unwrap();
let unanswered = third.dynamic();
assert!(
tokio::time::timeout(Duration::from_secs(1), follower.next())
.await
.is_err(),
"resolving the next replacement"
);

// At 11s, the third goes and the second's first snapshot is ready, both past its deadline.
tokio::time::advance(linger + Duration::from_secs(1) - start.elapsed()).await;
drop((third, unanswered));
std::ops::DerefMut::deref_mut(&mut catalog.modify().unwrap());
// Deliver the snapshot through the local serving path, so it is ready on the next poll.
let broadcast = origin.consume().request_broadcast("live", Some(epoch)).await.unwrap();
let mut available = crate::catalog::Consumer::<()>::new(&broadcast, crate::catalog::CatalogFormat::Hang)
.await
.unwrap();
use crate::catalog::Stream;
kio::wait(|waiter| available.poll_next(waiter)).await.unwrap().unwrap();

let std::task::Poll::Ready(Err(err)) = follower.poll_next(&kio::Waiter::noop()) else {
panic!("a snapshot after the restored replacement's deadline must not count");
};
assert!(err.to_string().contains("catalog"), "{err}");
}

/// A replacement whose catalog closes before its first snapshot fails the stitch, rather than
/// ending the export cleanly.
#[tokio::test(start_paused = true)]
async fn a_midstream_stitch_catalog_closed_without_a_snapshot_fails() {
let origin = crate::source::produce_origin();
let _first = publish_bare(&origin, Some(&moq_net::Epoch::mint()));
let mut follower = follower(&origin)
.await
.with_stitch(true)
.with_linger(Duration::from_secs(10));

let (_second, mut catalog) = publish_bare(&origin, Some(&moq_net::Epoch::mint()));
assert!(
tokio::time::timeout(Duration::from_secs(1), follower.next())
.await
.is_err(),
"awaiting the replacement's catalog"
);

catalog.finish().unwrap();
drop(catalog);
let end = tokio::time::timeout(Duration::from_secs(30), follower.next())
.await
.expect("the closed catalog ends the export");
let err = end.expect_err("a replacement without a catalog fails");
assert!(err.to_string().contains("catalog"), "{err}");
}

/// A snapshot that arrives after the deadline, before the follower polls again, is too late.
#[tokio::test(start_paused = true)]
async fn a_midstream_stitch_catalog_after_the_linger_fails() {
let origin = crate::source::produce_origin();
let linger = Duration::from_secs(10);
let _first = publish_bare(&origin, Some(&moq_net::Epoch::mint()));
let mut follower = follower(&origin).await.with_stitch(true).with_linger(linger);
let epoch = moq_net::Epoch::mint();
let (_second, mut catalog) = publish_bare(&origin, Some(&epoch));
let waiter = kio::Waiter::noop();
assert!(follower.poll_next(&waiter).is_pending());

tokio::time::advance(linger).await;
std::ops::DerefMut::deref_mut(&mut catalog.modify().unwrap());
// Deliver the snapshot through the local serving path, so it is ready on the next poll.
let broadcast = origin
.consume()
.request_broadcast("live", Some(epoch.clone()))
.await
.unwrap();
let mut available = crate::catalog::Consumer::<()>::new(&broadcast, crate::catalog::CatalogFormat::Hang)
.await
.unwrap();
use crate::catalog::Stream;
kio::wait(|waiter| available.poll_next(waiter)).await.unwrap().unwrap();

let std::task::Poll::Ready(Err(err)) = follower.poll_next(&waiter) else {
panic!("a snapshot after the linger must not count");
};
assert!(err.to_string().contains("catalog"), "{err}");
}

/// The audio PTS in `frames`.
fn audio_pts(frames: &[Frame]) -> Vec<u64> {
let bytes: Vec<u8> = frames.iter().flat_map(|f| f.payload.iter().copied()).collect();
Expand Down
Loading
Loading