Skip to main content

moq_wasm/media/
local_broadcast.rs

1use std::sync::Arc;
2
3use broadcast::{Broadcast, RelayConnection};
4use moqt::{
5    client::{self, HandlerId, PublishTrackOptions, TrackWriter},
6    executor,
7    publish::Retention,
8};
9use tokio::sync::watch;
10
11use super::{
12    broadcast_end::BroadcastEnd,
13    event_timeline::EventTimeline,
14    media_source::{MediaSource, MediaSourceOptions},
15};
16use crate::Session;
17
18/// A broadcast in `namespace`, published by `BroadcastBuilder::announce`.
19pub fn create_broadcast(session: &Session, namespace: &[impl AsRef<str>]) -> BroadcastBuilder {
20    let client = session.client().clone();
21    let connection = RelayConnection::with_client_session(&client);
22    let handler = client.add_handler(Arc::new(connection.clone()));
23    let namespace = namespace
24        .iter()
25        .map(|part| part.as_ref().to_string())
26        .collect();
27    BroadcastBuilder {
28        tracks: BroadcastTracks {
29            client,
30            broadcast: Broadcast::new(connection, namespace),
31            handler,
32        },
33    }
34}
35
36/// The tracks registered before the PUBLISH_NAMESPACE, so that a SUBSCRIBE
37/// the relay forwards at once finds them.
38pub struct BroadcastBuilder {
39    tracks: BroadcastTracks,
40}
41
42impl BroadcastBuilder {
43    /// A track the session answers SUBSCRIBE and FETCH for. Fails when
44    /// `options.publish` is set: a PUBLISH must follow PUBLISH_NAMESPACE, so
45    /// publish such a track on the `LocalBroadcast`.
46    pub async fn publish_track(
47        &self,
48        name: &str,
49        options: PublishTrackOptions,
50    ) -> anyhow::Result<TrackWriter> {
51        anyhow::ensure!(
52            !options.publish,
53            "a PUBLISH follows the namespace: publish the track after announce"
54        );
55        self.tracks.publish_track(name, options).await
56    }
57
58    pub async fn event_timeline(
59        &self,
60        name: &str,
61        retention: Retention,
62    ) -> anyhow::Result<EventTimeline> {
63        self.tracks.event_timeline(name, retention).await
64    }
65
66    /// PUBLISH_NAMESPACE (draft-14 §9.23). Fails when the relay refuses it.
67    pub async fn announce(self) -> anyhow::Result<LocalBroadcast> {
68        self.tracks.broadcast.announce().await?;
69        Ok(LocalBroadcast {
70            tracks: self.tracks,
71            ended_sender: watch::Sender::new(false),
72            withdrawn: false,
73        })
74    }
75}
76
77/// A published namespace; a media source's tracks reach subscribers through
78/// the MSF catalog. `add_media_source` and dropping it without `close` spawn
79/// tasks (the latter withdraws the namespace), so call both inside the tokio
80/// runtime.
81pub struct LocalBroadcast {
82    tracks: BroadcastTracks,
83    ended_sender: watch::Sender<bool>,
84    withdrawn: bool,
85}
86
87impl LocalBroadcast {
88    /// As `BroadcastBuilder::publish_track`, with `options.publish` too.
89    pub async fn publish_track(
90        &self,
91        name: &str,
92        options: PublishTrackOptions,
93    ) -> anyhow::Result<TrackWriter> {
94        self.tracks.publish_track(name, options).await
95    }
96
97    pub async fn event_timeline(
98        &self,
99        name: &str,
100        retention: Retention,
101    ) -> anyhow::Result<EventTimeline> {
102        self.tracks.event_timeline(name, retention).await
103    }
104
105    pub fn add_media_source(&self, options: MediaSourceOptions) -> MediaSource {
106        MediaSource::new(
107            &self.tracks.broadcast,
108            options,
109            BroadcastEnd::new(&self.ended_sender),
110        )
111    }
112
113    /// PUBLISH_NAMESPACE_DONE (draft-14 §9.26). The media sources stop:
114    /// their pushes fail from now on.
115    pub async fn close(mut self) -> anyhow::Result<()> {
116        self.withdrawn = true;
117        self.ended_sender.send_replace(true);
118        self.tracks
119            .client
120            .moqt_session()
121            .publisher()
122            .publish_namespace_done(self.tracks.broadcast.namespace().join("/"))
123            .await
124    }
125}
126
127impl Drop for LocalBroadcast {
128    fn drop(&mut self) {
129        self.ended_sender.send_replace(true);
130        if self.withdrawn {
131            return;
132        }
133        let session = self.tracks.client.moqt_session().clone();
134        let track_namespace = self.tracks.broadcast.namespace().join("/");
135        executor::spawn("moq-wasm-namespace-done", async move {
136            if let Err(error) = session
137                .publisher()
138                .publish_namespace_done(track_namespace.clone())
139                .await
140            {
141                tracing::warn!(error = %format!("{error:#}"), track_namespace, "PUBLISH_NAMESPACE_DONE failed");
142            }
143        });
144    }
145}
146
147/// What the builder and the broadcast share: the broadcast, answered by its
148/// handler on the session until it is dropped.
149struct BroadcastTracks {
150    client: Arc<client::Session>,
151    broadcast: Broadcast,
152    handler: HandlerId,
153}
154
155impl BroadcastTracks {
156    async fn publish_track(
157        &self,
158        name: &str,
159        options: PublishTrackOptions,
160    ) -> anyhow::Result<TrackWriter> {
161        self.client
162            .publish_track(self.broadcast.namespace(), name, options)
163            .await
164    }
165
166    async fn event_timeline(
167        &self,
168        name: &str,
169        retention: Retention,
170    ) -> anyhow::Result<EventTimeline> {
171        let options = PublishTrackOptions {
172            retention,
173            ..PublishTrackOptions::default()
174        };
175        EventTimeline::open(self.publish_track(name, options).await?).await
176    }
177}
178
179impl Drop for BroadcastTracks {
180    fn drop(&mut self) {
181        self.client.remove_handler(self.handler);
182    }
183}
184
185#[cfg(test)]
186mod tests {
187    use serde_json::json;
188
189    use super::*;
190    use crate::{
191        media::MediaSourceError,
192        test_support::{TEST_TIMEOUT, TestRelay},
193    };
194
195    #[tokio::test]
196    async fn announce_publishes_the_namespace() {
197        // Arrange
198        let mut relay = TestRelay::spawn("announce");
199        let session = relay.connect().await;
200        let builder = create_broadcast(&session, &["anon", "robot"]);
201
202        // Act
203        let _broadcast = builder.announce().await.unwrap();
204
205        // Assert
206        assert_eq!(relay.next_request().await, "PUBLISH_NAMESPACE anon/robot");
207    }
208
209    #[tokio::test]
210    async fn the_builder_refuses_a_track_published_before_the_namespace() {
211        // Arrange
212        let relay = TestRelay::spawn("builder-publish");
213        let session = relay.connect().await;
214        let builder = create_broadcast(&session, &["anon", "robot"]);
215        let options = PublishTrackOptions {
216            publish: true,
217            ..PublishTrackOptions::default()
218        };
219
220        // Act
221        let result = builder.publish_track("status", options).await;
222
223        // Assert
224        assert!(result.is_err());
225    }
226
227    #[tokio::test]
228    async fn close_withdraws_the_namespace() {
229        // Arrange
230        let mut relay = TestRelay::spawn("close");
231        let session = relay.connect().await;
232        let broadcast = create_broadcast(&session, &["anon", "robot"])
233            .announce()
234            .await
235            .unwrap();
236        relay.next_request().await;
237
238        // Act
239        broadcast.close().await.unwrap();
240
241        // Assert
242        assert_eq!(
243            relay.next_request().await,
244            "PUBLISH_NAMESPACE_DONE anon/robot"
245        );
246    }
247
248    #[tokio::test]
249    async fn dropping_the_broadcast_withdraws_the_namespace() {
250        // Arrange
251        let mut relay = TestRelay::spawn("drop");
252        let session = relay.connect().await;
253        let broadcast = create_broadcast(&session, &["anon", "robot"])
254            .announce()
255            .await
256            .unwrap();
257        relay.next_request().await;
258
259        // Act
260        drop(broadcast);
261
262        // Assert
263        assert_eq!(
264            relay.next_request().await,
265            "PUBLISH_NAMESPACE_DONE anon/robot"
266        );
267    }
268
269    #[tokio::test]
270    async fn a_media_source_stops_with_its_broadcast() {
271        // Arrange
272        let mut relay = TestRelay::spawn("media-stop");
273        let session = relay.connect().await;
274        let broadcast = create_broadcast(&session, &["anon", "robot"])
275            .announce()
276            .await
277            .unwrap();
278        relay.next_request().await;
279        let source = broadcast.add_media_source(MediaSourceOptions::new("camera"));
280
281        // Act
282        broadcast.close().await.unwrap();
283        let configured = source.configure_audio("opus", 48_000, 1, None);
284        let waited = tokio::time::timeout(TEST_TIMEOUT, source.keyframe_request()).await;
285
286        // Assert
287        assert!(matches!(configured, Err(MediaSourceError::Stopped(_))));
288        assert!(matches!(waited, Ok(Err(_))), "{waited:?}");
289    }
290
291    #[tokio::test]
292    async fn an_event_timeline_appends_each_record_as_an_object() {
293        // Arrange
294        let mut relay = TestRelay::spawn("event-timeline");
295        let session = relay.connect().await;
296        let builder = create_broadcast(&session, &["anon", "robot"]);
297        let events = builder
298            .event_timeline("events", Retention::For(std::time::Duration::from_secs(60)))
299            .await
300            .unwrap();
301        let _broadcast = builder.announce().await.unwrap();
302        relay.next_request().await;
303
304        // Act
305        let object = relay
306            .next_object_after("anon/robot", "events", async {
307                events
308                    .append(&json!({"T": 1, "data": "start"}))
309                    .await
310                    .unwrap();
311            })
312            .await;
313
314        // Assert: §8 a record list of one
315        assert_eq!(object.as_ref(), br#"[{"T":1,"data":"start"}]"#);
316    }
317}