Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ removal, a rename, or a wire, catalog, or format change that is free until
- **Native media and gateways.** [The video producer](/quest/m2/video-producer.md),
[the hole wait](/quest/m2/delay-hole-wait.md),
[moq-vaapi's exports](/quest/m2/vaapi-exports.md),
[the WHEP pull's announcement](/quest/m2/whep-pull-announce.md), and
[a chained WHEP pull's shutdown](/quest/m2/whep-chain-shutdown.md), and
[upstream str0m](https://github.com/moq-dev/moq/pull/8963), which reverses the
2026-10-30 vendoring.
- **JS and browser.** [`@moq/net`](/quest/m2/js-net-api.md),
Expand Down
39 changes: 39 additions & 0 deletions quest/m2/whep-chain-shutdown.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# [S] A WHEP pull chained into an export stops cleanly

## Goal

Stopping `moq import webrtc --connect <whep> -- export rtmp --connect <rtmp>`
with SIGTERM exits 0 and logs no warning about its own tracks. The RTMP export
does not fail with `the source's clock runs +59.8 ppm off ours, past the 30 ppm
the output's may follow`. The WHEP ingest's tracks (`0.opus`, `1.avc3`,
`catalog.json`, `catalog`) end with `finish()` or `abort()` instead of logging
`track::Producer dropped without finish() or abort()`. Non-goal: orderly
broadcast ends while the process keeps running, which
[export-close](/quest/m3/export-close.md) owns.

## Plan

Found 2026-11-17 while validating
[moq-dev/moq#8997](https://github.com/moq-dev/moq/pull/8997) on the built
binary. Its PR body's Validation section has the three-process loopback setup
(an ffmpeg source through `export webrtc --listen`, the chain, and an RTMP
sink), and the stop shows both symptoms in some runs. The maintainer picked
this follow-up when picking #8997 to merge.

- **Clock drift on stop.** The error comes from the drift estimate in
`rs/moq-mux/src/jitter.rs` (`Error` in `rs/moq-mux/src/error.rs`), judged over
only the few seconds the chain ran, while the ingest's timeline was still
settling from arrival time onto RTCP sender reports (`IngestClock` in
`rs/moq-webrtc/src/session.rs`). First find out whether the stop causes it
(for example, a timestamp jump while draining) or whether a short run would
trip it anyway. Then fix whichever is at fault: the ingest timeline or an
estimate that lacks enough samples to judge drift.
- **Unfinished tracks.** `Session::run` aborts the sink only when its loop
returns. A SIGTERM drops the pull's future instead, which drops the
`IngestSink` and its bridges unfinished. Finish or abort them on drop, the
way the rtsp import closes its catalog after its select.

## Related

- [Container export ends cleanly](/quest/m3/export-close.md) - an export's orderly end when its broadcast closes
- [Interop stops publishers cleanly](/quest/m3/interop-shutdown-warnings.md) - the same unfinished-producer warning in the CLI FETCH round
32 changes: 0 additions & 32 deletions quest/m2/whep-pull-announce.md

This file was deleted.

73 changes: 61 additions & 12 deletions rs/moq-cli/src/webrtc.rs
Original file line number Diff line number Diff line change
Expand Up @@ -85,27 +85,35 @@ fn scope_producer(origin: &moq_net::origin::Producer, name: &str) -> anyhow::Res
}

/// WHEP client: pull a remote broadcast into the Origin under `target.name` (import),
/// announced under `instance`.
/// announced under `instance` once its catalog names a track.
pub async fn connect_import(target: ImportTarget, url: Url, instance: moq_net::Instance) -> anyhow::Result<()> {
let name = &target.name;
// The WHEP pull fills the tracks as they arrive; announce up front so viewers
// can discover the broadcast while it connects. Held until the pull ends.
// Hidden until the catalog exists: a viewer or export that resolved the broadcast earlier
// would find no catalog track. Held until the pull ends.
let route = target
.origin
.route(
name,
moq_net::origin::RouteOptions::default().with_instance(instance, 0),
)
.route(name, moq_net::origin::RouteOptions::hidden().with_instance(instance, 0))
.context("failed to create broadcast")?;
let catalog = moq_mux::catalog::Producer::new(&mut route.broadcast().clone(), target.ingest.catalog())?;
let client = moq_webrtc::Client::new(moq_webrtc::client::Config::default())?;

tracing::info!(url = %RedactedUrl::new(&url), %name, "WHEP client pulling");
notify_ready();

let client = moq_webrtc::Client::new(moq_webrtc::client::Config::default())?;
client
.pull(url, route.broadcast().clone(), target.ingest.catalog())
.await?;
Ok(())
let announce = async {
let mut updates = catalog.consume()?;
// The pull ends the catalog when its session ends, and reports why itself.
if let Ok(Some(_)) = updates.next().await {
route.announce().context("failed to announce broadcast")?;
tracing::info!(%name, "publishing WHEP broadcast");
}
std::future::pending::<anyhow::Result<()>>().await
};

tokio::select! {
end = client.pull(url, route.broadcast(), &catalog) => Ok(end?),
err = announce => err,
}
}

/// WHIP client: push a broadcast from the Origin to a remote (export).
Expand Down Expand Up @@ -149,3 +157,44 @@ async fn serve(router: axum::Router, role: &str, listen: Listen) -> anyhow::Resu

crate::web::serve(listener, app, None).await
}

#[cfg(test)]
mod tests {
use futures::FutureExt;

use super::*;

/// A WHEP pull keeps its broadcast hidden while the session negotiates, since nothing has
/// published its catalog yet, and never announces a pull that fails before then.
#[tokio::test]
async fn a_whep_pull_hides_its_broadcast_until_the_catalog_exists() {
let origin = moq_tokio::origin::spawn();
let consumer = origin.consume();
let mut announced = consumer.announced();
// A WHEP endpoint that takes the offer and never answers it.
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let url = format!("http://{}/whep", listener.local_addr().unwrap())
.parse()
.unwrap();
let target = ImportTarget {
origin,
name: "pulled".to_string(),
ingest: moq_mux::Ingest::default(),
};
let pull = tokio::spawn(connect_import(target, url, moq_net::Instance::random()));

let (offer, _) = listener.accept().await.unwrap();
assert!(
announced.next().now_or_never().is_none(),
"announced before the catalog exists"
);

drop(offer);
pull.await.unwrap().expect_err("the endpoint hung up without an answer");
// The origin ends with the pull, so the only announcement left would be the pull's.
assert!(
announced.next().now_or_never().flatten().is_none(),
"announced a failed pull"
);
}
}
33 changes: 21 additions & 12 deletions rs/moq-webrtc/src/client/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -50,18 +50,25 @@ impl Client {
&self.http
}

/// `client pull`: ingest a remote WHEP feed and publish it as `broadcast`, its tracks
/// minted under `catalog`, until the session ends.
/// `client pull`: ingest a remote WHEP feed into `broadcast`, publishing its renditions
/// on `catalog`, until the session ends.
///
/// The caller owns the broadcast, so its announcement and any linger after the end are
/// the caller's too.
/// The catalog gets its first update once the session negotiates a track. The caller owns
/// the broadcast, so its announcement and any linger after the end are the caller's too.
/// Any end, clean or not, aborts the catalog and every track with its cause.
pub async fn pull(
&self,
url: Url,
broadcast: moq_net::broadcast::Producer,
catalog: moq_mux::catalog::Config,
broadcast: &moq_net::broadcast::Producer,
catalog: &moq_mux::catalog::Producer,
) -> crate::Result<()> {
whep::dial(self, url, broadcast, catalog).await
let result = whep::dial(self, url, broadcast.clone(), catalog.clone()).await;
// A dial that fails before its session runs leaves the catalog open; a session already
// aborted it with its cause, which this keeps.
if let Err(err) = &result {
catalog.clone().abort(moq_net::Error::Transport(err.to_string()));
}
result
}

/// `client publish`: push the broadcast `source` resolved to a remote WHIP endpoint,
Expand All @@ -86,20 +93,22 @@ mod tests {
let address = listener.local_addr().expect("local address");
drop(listener);

let origin = moq_tokio::origin::spawn();
let broadcast = origin
.route("test", moq_net::origin::RouteOptions::hidden())
.expect("create broadcast");
let mut broadcast = moq_net::broadcast::Info::new().produce();
let catalog = moq_mux::catalog::Producer::new(&mut broadcast, Default::default()).unwrap();
let url = format!("http://user:pass@{address}/whep/test?jwt=secret")
.parse()
.expect("WHEP URL");
let err = Client::new(Config::default())
.unwrap()
.pull(url, broadcast.broadcast().clone(), Default::default())
.pull(url, &broadcast, &catalog)
.await
.expect_err("dial a closed port");

assert!(matches!(err, crate::Error::Http(_)), "unexpected error: {err}");
assert!(
catalog.consume().unwrap().next().await.is_err(),
"the failed dial aborts the catalog"
);
let printed = format!("{err} {err:?}");
for secret in ["jwt", "secret", "user:pass"] {
assert!(!printed.contains(secret), "error leaked {secret}: {printed}");
Expand Down
4 changes: 2 additions & 2 deletions rs/moq-webrtc/src/client/whep.rs
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,9 @@ pub(crate) async fn dial(
client: &Client,
url: Url,
broadcast: moq_net::broadcast::Producer,
catalog: moq_mux::catalog::Config,
catalog: moq_mux::catalog::Producer,
) -> Result<()> {
let sink = Box::new(IngestSink::new(broadcast, catalog)?);
let sink = Box::new(IngestSink::new(broadcast, catalog));

let socket = session::bind_udp().await?;
let mut rtc = session::rtc_config()?.build(kio::clock::now().into_std());
Expand Down
33 changes: 17 additions & 16 deletions rs/moq-webrtc/src/ingest.rs
Original file line number Diff line number Diff line change
Expand Up @@ -18,22 +18,24 @@ pub struct IngestSink {
}

impl IngestSink {
/// Fill `broadcast`, whose announcement the caller owns.
pub fn new(mut broadcast: moq_net::broadcast::Producer, config: moq_mux::catalog::Config) -> Result<Self> {
let catalog = moq_mux::catalog::Producer::new(&mut broadcast, config)?;
Ok(Self {
/// Fill `broadcast` and its `catalog`, whose announcement the caller owns.
pub fn new(broadcast: moq_net::broadcast::Producer, catalog: moq_mux::catalog::Producer) -> Self {
Self {
broadcast,
catalog,
bridges: session::Bridges::new(),
_route: None,
})
}
}

/// Fill `route`'s broadcast, keeping the route for the session's life.
/// Fill `route`'s broadcast under a catalog minted from `config`, keeping the route for
/// the session's life.
pub fn routed(route: moq_net::origin::Route, config: moq_mux::catalog::Config) -> Result<Self> {
let mut broadcast = route.broadcast().clone();
let catalog = moq_mux::catalog::Producer::new(&mut broadcast, config)?;
Ok(Self {
_route: Some(route.clone()),
..Self::new(route.broadcast().clone(), config)?
_route: Some(route),
..Self::new(broadcast, catalog)
})
}
}
Expand Down Expand Up @@ -104,12 +106,10 @@ mod tests {
/// bridges mint, not just on the catalog producer it was set on.
#[tokio::test]
async fn tracks_inherit_the_configured_max_age() {
let broadcast = moq_net::broadcast::Info::new().produce();
let mut sink = IngestSink::new(
broadcast.clone(),
moq_mux::catalog::Config::default().with_max_age(Duration::from_secs(3)),
)
.unwrap();
let mut broadcast = moq_net::broadcast::Info::new().produce();
let config = moq_mux::catalog::Config::default().with_max_age(Duration::from_secs(3));
let catalog = moq_mux::catalog::Producer::new(&mut broadcast, config).unwrap();
let mut sink = IngestSink::new(broadcast.clone(), catalog);

sink.on_track(
"0".into(),
Expand All @@ -127,9 +127,10 @@ mod tests {
/// included, so the held sink serves them to a late subscriber for the linger.
#[tokio::test]
async fn finish_keeps_every_track_for_the_linger() {
let broadcast = moq_net::broadcast::Info::new().produce();
let mut broadcast = moq_net::broadcast::Info::new().produce();
let consumer = broadcast.consume();
let mut sink = IngestSink::new(broadcast, moq_mux::catalog::Config::default()).unwrap();
let catalog = moq_mux::catalog::Producer::new(&mut broadcast, Default::default()).unwrap();
let mut sink = IngestSink::new(broadcast, catalog);
let audio = str0m::media::MediaKind::Audio;
sink.on_track("0".into(), audio, str0m::format::Codec::Opus, Some((48_000, 2)))
.unwrap();
Expand Down
10 changes: 6 additions & 4 deletions rs/moq-webrtc/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -225,8 +225,9 @@ mod tests {
let output_consumer = output.broadcast().consume();
let client = Client::new(client::Config::default()).unwrap();
let url = format!("http://{address}/whep/source").parse().expect("WHEP URL");
let fill = output.broadcast().clone();
let viewer = tokio::spawn(async move { client.pull(url, fill, Default::default()).await });
let mut fill = output.broadcast().clone();
let catalog = moq_mux::catalog::Producer::new(&mut fill, Default::default()).unwrap();
let viewer = tokio::spawn(async move { client.pull(url, &fill, &catalog).await });
let session = kio::clock::timeout(TIMEOUT, sessions.recv())
.await
.expect("WHEP negotiation timed out")
Expand Down Expand Up @@ -554,8 +555,9 @@ mod tests {
let whep = format!("http://user:pass@{address}/whep/ingested?jwt=canary-7f3e")
.parse()
.expect("WHEP URL");
let fill = output.broadcast().clone();
let whep_client = tokio::spawn(async move { client.pull(whep, fill, Default::default()).await });
let mut fill = output.broadcast().clone();
let catalog = moq_mux::catalog::Producer::new(&mut fill, Default::default()).unwrap();
let whep_client = tokio::spawn(async move { client.pull(whep, &fill, &catalog).await });
let (whep_id, whep_task) = kio::clock::timeout(TIMEOUT, sources_rx.recv())
.await
.expect("WHEP negotiation timed out")
Expand Down
Loading