From f9b1d0c27673a6d8ead7be2d7a3239871fa602ce Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 21:16:35 -0700 Subject: [PATCH 1/7] chore(quest): claim quest/m1/api-audit/resolve/bindings.md Quest-Claim: 2a81023751c83b86 From b7d011ea609a039d07ef302e674172b270806e65 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 21:23:14 -0700 Subject: [PATCH 2/7] feat(ffi)!: name the binding resolutions request and follow moq-ffi's request_broadcast and announced_broadcast become request(path, epoch) and follow(path, epoch), and MoqAnnouncedBroadcast becomes MoqFollowing, mirroring origin::Following. The C ABI renames moq_origin_announced_broadcast to moq_origin_follow and gives both resolutions an optional epoch. Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/README.md | 6 +- rs/moq-c/c-tests/audio-decode-output.c | 2 +- rs/moq-c/c-tests/decode-output.c | 2 +- rs/moq-c/src/api.rs | 54 ++++++--- rs/moq-c/src/origin.rs | 41 ++++--- rs/moq-c/src/test.rs | 143 +++++++++++++++++++----- rs/moq-ffi/src/origin.rs | 47 ++++---- rs/moq-ffi/src/test.rs | 149 +++++++++++++++++-------- test/interop/clients/c/subscribe.c | 8 +- 9 files changed, 318 insertions(+), 134 deletions(-) diff --git a/rs/moq-c/README.md b/rs/moq-c/README.md index aa3e6b93731..0e12666c421 100644 --- a/rs/moq-c/README.md +++ b/rs/moq-c/README.md @@ -55,10 +55,10 @@ int32_t moq_session_request_free(uint32_t request); int32_t moq_origin_create(void); int32_t moq_origin_close(uint32_t origin); int32_t moq_origin_create_broadcast(uint32_t origin, const char *path, uintptr_t path_len, uint32_t *broadcast); -int32_t moq_origin_request(uint32_t origin, const char *path, uintptr_t path_len, moq_status_callback on_broadcast, void *user_data); +int32_t moq_origin_request(uint32_t origin, const char *path, uintptr_t path_len, const char *epoch, uintptr_t epoch_len, moq_status_callback on_broadcast, void *user_data); int32_t moq_origin_request_cancel(uint32_t task); -int32_t moq_origin_announced_broadcast(uint32_t origin, const char *path, uintptr_t path_len, moq_status_callback on_broadcast, void *user_data); -int32_t moq_origin_announced_broadcast_cancel(uint32_t task); +int32_t moq_origin_follow(uint32_t origin, const char *path, uintptr_t path_len, const char *epoch, uintptr_t epoch_len, moq_status_callback on_broadcast, void *user_data); +int32_t moq_origin_follow_cancel(uint32_t task); int32_t moq_origin_announced(uint32_t origin, const moq_announce_config *config, moq_status_callback on_announce, void *user_data); int32_t moq_origin_announced_info(uint32_t announced, moq_announce_event *dst); int32_t moq_origin_announced_free(uint32_t announced); diff --git a/rs/moq-c/c-tests/audio-decode-output.c b/rs/moq-c/c-tests/audio-decode-output.c index 4799a02940e..4262c61c1d6 100644 --- a/rs/moq-c/c-tests/audio-decode-output.c +++ b/rs/moq-c/c-tests/audio-decode-output.c @@ -118,7 +118,7 @@ int main(void) { CHECK(moq_encode_audio_frame((uint32_t)producer, &frame) == 0); CHECK(moq_encode_audio_finish((uint32_t)producer) == 0); - CHECK(moq_origin_request((uint32_t)origin, path, strlen(path), on_broadcast, &c) > 0); + CHECK(moq_origin_request((uint32_t)origin, path, strlen(path), NULL, 0, on_broadcast, &c) > 0); pthread_mutex_lock(&c.mutex); wait_until(&c, &c.broadcast); pthread_mutex_unlock(&c.mutex); diff --git a/rs/moq-c/c-tests/decode-output.c b/rs/moq-c/c-tests/decode-output.c index 6f8fb0e9199..4a6717583cb 100644 --- a/rs/moq-c/c-tests/decode-output.c +++ b/rs/moq-c/c-tests/decode-output.c @@ -252,7 +252,7 @@ int main(void) { fail("error: moq_encode_video_cut failed (%s)\n", moq_error()); publish_frames(producer, 5); - int32_t request = moq_origin_request((uint32_t)origin, path, strlen(path), on_broadcast, &c); + int32_t request = moq_origin_request((uint32_t)origin, path, strlen(path), NULL, 0, on_broadcast, &c); if (request <= 0) fail("error: moq_origin_request failed: %d\n", request); pthread_mutex_lock(&c.mu); diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 628fb5aad0d..d8deb0d552e 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -2059,16 +2059,20 @@ pub extern "C" fn moq_origin_announced_cancel(announced: u32) -> i32 { /// /// Resolves against future announcements: it waits for the announcement to arrive (e.g. over the /// network) and then delivers the broadcast handle via `on_broadcast`. Use it right after -/// [moq_session_connect] to avoid racing announcement gossip. To resolve against only what is -/// reachable now, use [moq_origin_request] instead. A broadcast created on this origin -/// resolves once it is announced, like a remote one. +/// [moq_session_connect] to avoid racing announcement gossip. To resolve one publisher instance +/// instead, use [moq_origin_request]. A broadcast created on this origin resolves once it is +/// announced, like a remote one. +/// +/// `epoch` is the UUIDv7 text of the only publisher instance to follow, or NULL (or empty) to +/// follow every instance. A pinned follow never delivers another instance taking over, and +/// delivers its own instance again if it returns after an end. /// /// `on_broadcast` is invoked with a positive broadcast handle once announced, and again with a /// new handle each time another publisher instance takes over (a restarted publisher, or a /// replacement session) or the broadcast returns after it went offline. Drop what was read /// from the previous handle then: its tracks end when its session does. The wait ends with -/// exactly one terminal code: `0` (after [moq_origin_announced_broadcast_cancel], or the origin -/// closing once a handle was delivered) or a negative error. After the terminal (`<= 0`) callback, +/// exactly one terminal code: `0` (after [moq_origin_follow_cancel], or the origin closing +/// once a handle was delivered) or a negative error. After the terminal (`<= 0`) callback, /// `on_broadcast` is never called again and `user_data` is never touched again, so release /// `user_data` there. The broadcast handle is usable with [moq_consume_catalog] / [moq_consume_track] /// and must be freed separately with [moq_consume_close]. @@ -2077,45 +2081,53 @@ pub extern "C" fn moq_origin_announced_cancel(announced: u32) -> i32 { /// /// # Safety /// - The caller must ensure that path is a valid pointer to path_len bytes of data. +/// - `epoch` may be NULL, or must point at `epoch_len` readable bytes. /// - The caller must keep `user_data` valid until the terminal (`<= 0`) `on_broadcast` callback. #[unsafe(no_mangle)] -pub unsafe extern "C" fn moq_origin_announced_broadcast( +pub unsafe extern "C" fn moq_origin_follow( origin: u32, path: *const c_char, path_len: usize, + epoch: *const c_char, + epoch_len: usize, on_broadcast: ffi::moq_status_callback, user_data: *mut c_void, ) -> i32 { ffi::enter(move || { let origin = ffi::parse_id(origin)?; let path = unsafe { ffi::parse_str(path, path_len)? }.to_string(); + let epoch = unsafe { parse_epoch(epoch, epoch_len)? }; let on_broadcast = unsafe { ffi::OnStatus::new(user_data, on_broadcast)? }; - State::lock().origin.consume_announced(origin, path, on_broadcast) + State::lock().origin.follow(origin, path, epoch, on_broadcast) }) } -/// Abort a wait started by [moq_origin_announced_broadcast]. +/// Abort a wait started by [moq_origin_follow]. /// /// Returns immediately: zero on success, or a negative code if already closed. Does NOT free -/// `user_data`. The [moq_origin_announced_broadcast] `on_broadcast` callback still fires once more +/// `user_data`. The [moq_origin_follow] `on_broadcast` callback still fires once more /// with a terminal `0` (or a negative error), and that final callback is where `user_data` should /// be released. Any broadcast handle already delivered is unaffected and must still be freed with /// [moq_consume_close]. #[unsafe(no_mangle)] -pub extern "C" fn moq_origin_announced_broadcast_cancel(task: u32) -> i32 { +pub extern "C" fn moq_origin_follow_cancel(task: u32) -> i32 { ffi::enter(move || { let task = ffi::parse_id(task)?; - State::lock().origin.consume_announced_close(task) + State::lock().origin.resolve_close(task) }) } -/// Request a broadcast from an origin by path, resolving as soon as it can be served. +/// Request a broadcast from an origin by path, resolving one publisher instance as soon as it +/// can be served. /// /// Owns discovery of the path and retries route churn while resolving one publisher instance. /// It fails as unroutable once discovery has synced without a covering route, including a /// broadcast created but not announced. No separate announcement stream is needed. /// Serve on-demand paths with [moq_origin_requests]. /// +/// `epoch` is the UUIDv7 text of the only publisher instance to accept, or NULL (or empty) for +/// any instance. A request pinned to an instance that does not serve the path is unroutable. +/// /// `on_broadcast` is invoked with a positive broadcast handle once served, then exactly once more /// with a terminal code: `0` (finished, including after [moq_origin_request_cancel]) or a negative /// error. After the terminal (`<= 0`) callback, `user_data` is never touched again, so release it @@ -2126,20 +2138,24 @@ pub extern "C" fn moq_origin_announced_broadcast_cancel(task: u32) -> i32 { /// /// # Safety /// - The caller must ensure that path is a valid pointer to path_len bytes of data. +/// - `epoch` may be NULL, or must point at `epoch_len` readable bytes. /// - The caller must keep `user_data` valid until the terminal (`<= 0`) `on_broadcast` callback. #[unsafe(no_mangle)] pub unsafe extern "C" fn moq_origin_request( origin: u32, path: *const c_char, path_len: usize, + epoch: *const c_char, + epoch_len: usize, on_broadcast: ffi::moq_status_callback, user_data: *mut c_void, ) -> i32 { ffi::enter(move || { let origin = ffi::parse_id(origin)?; let path = unsafe { ffi::parse_str(path, path_len)? }.to_string(); + let epoch = unsafe { parse_epoch(epoch, epoch_len)? }; let on_broadcast = unsafe { ffi::OnStatus::new(user_data, on_broadcast)? }; - State::lock().origin.request(origin, path, on_broadcast) + State::lock().origin.request(origin, path, epoch, on_broadcast) }) } @@ -2153,10 +2169,20 @@ pub unsafe extern "C" fn moq_origin_request( pub extern "C" fn moq_origin_request_cancel(task: u32) -> i32 { ffi::enter(move || { let task = ffi::parse_id(task)?; - State::lock().origin.consume_announced_close(task) + State::lock().origin.resolve_close(task) }) } +/// Parse an optional publisher epoch, where NULL or empty means unpinned. +/// +/// # Safety +/// - `epoch` may be NULL, or must point at `epoch_len` readable bytes. +unsafe fn parse_epoch(epoch: *const c_char, epoch_len: usize) -> Result, Error> { + unsafe { ffi::parse_str_optional(epoch, epoch_len)? } + .map(|epoch| epoch.parse().map_err(|_| Error::InvalidCode)) + .transpose() +} + /// Close an origin and clean up its resources. /// /// The origin keeps running while a broadcast published on it or a diff --git a/rs/moq-c/src/origin.rs b/rs/moq-c/src/origin.rs index 357bc67dc26..2248dc16f77 100644 --- a/rs/moq-c/src/origin.rs +++ b/rs/moq-c/src/origin.rs @@ -216,8 +216,14 @@ impl Origin { /// /// The callback fires a broadcast handle (> 0) for each instance serving the path, until a /// single terminal code (`0` on close, negative on error). Returns a task handle for - /// cancellation via [`Self::consume_announced_close`]. - pub fn consume_announced(&mut self, origin: Id, path: String, on_broadcast: OnStatus) -> Result { + /// cancellation via [`Self::resolve_close`]. + pub fn follow( + &mut self, + origin: Id, + path: String, + epoch: Option, + on_broadcast: OnStatus, + ) -> Result { let origin = self.active.get(origin).ok_or(Error::OriginNotFound)?; origin.driver.check()?; let driver = origin.driver.clone(); @@ -227,20 +233,21 @@ impl Origin { |state| &mut state.origin.consume_task, |close| async move { driver - .watch(Self::run_consume_announced(on_broadcast, consumer, path, close)) + .watch(Self::run_follow(on_broadcast, consumer, path, epoch, close)) .await }, ) } - async fn run_consume_announced( + async fn run_follow( callback: OnStatus, consumer: Consumer, path: String, + epoch: Option, mut close: oneshot::Receiver<()>, ) -> Result<(), Error> { // An unreachable path and a closed origin both mean no broadcast can ever arrive here. - let mut announced = match consumer.follow(path.as_str(), None) { + let mut announced = match consumer.follow(path.as_str(), epoch) { Ok(announced) => announced, Err(moq_net::Error::Unauthorized) => return Err(Error::BroadcastNotFound), Err(err) => return Err(err.into()), @@ -271,12 +278,17 @@ impl Origin { /// Request the broadcast at `path`, delivering its handle once it can be served. /// - /// Unlike [`Self::consume`] (announced-only, fails fast) and [`Self::consume_announced`] - /// (waits indefinitely for a future announcement), this resolves against any route - /// announced now: the callback fires the broadcast - /// handle (> 0) once served, then a terminal `0`; or a single terminal code (`0` on close, - /// negative on error) if it can't be served. Returns a task handle for cancellation. - pub fn request(&mut self, origin: Id, path: String, on_broadcast: OnStatus) -> Result { + /// Unlike [`Self::follow`] (waits indefinitely, delivering each publisher instance), this + /// resolves one instance: the callback fires the broadcast handle (> 0) once served, then a + /// terminal `0`; or a single terminal code (`0` on close, negative on error) if it can't be + /// served. Returns a task handle for cancellation. + pub fn request( + &mut self, + origin: Id, + path: String, + epoch: Option, + on_broadcast: OnStatus, + ) -> Result { let origin = self.active.get(origin).ok_or(Error::OriginNotFound)?; origin.driver.check()?; let driver = origin.driver.clone(); @@ -286,7 +298,7 @@ impl Origin { |state| &mut state.origin.consume_task, |close| async move { driver - .watch(Self::run_request(on_broadcast, consumer, path, close)) + .watch(Self::run_request(on_broadcast, consumer, path, epoch, close)) .await }, ) @@ -296,10 +308,11 @@ impl Origin { callback: OnStatus, consumer: Consumer, path: String, + epoch: Option, mut close: oneshot::Receiver<()>, ) -> Result<(), Error> { // Resolves to an error when no announced route can serve the path. - let pending = consumer.request(path.as_str(), None); + let pending = consumer.request(path.as_str(), epoch); // `biased` so a pending close always wins over a ready broadcast. let broadcast = tokio::select! { @@ -314,7 +327,7 @@ impl Origin { Ok(()) } - pub fn consume_announced_close(&mut self, task: Id) -> Result<(), Error> { + pub fn resolve_close(&mut self, task: Id) -> Result<(), Error> { self.consume_task.close(task, Error::NotFound) } diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 6428e4fd7b0..d92449c7eb4 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -44,6 +44,8 @@ fn request_broadcast(origin: u32, path: &[u8]) -> u32 { origin, path.as_ptr() as *const c_char, path.len(), + std::ptr::null(), + 0, Some(channel_callback), cb.ptr, ) @@ -71,6 +73,8 @@ fn request_once(origin: u32, path: &[u8]) -> i32 { origin, path.as_ptr() as *const c_char, path.len(), + std::ptr::null(), + 0, Some(channel_callback), cb.ptr, ) @@ -2860,6 +2864,8 @@ fn dynamic_serves_a_request_under_a_prefix() { origin, path.as_ptr() as *const c_char, path.len(), + std::ptr::null(), + 0, Some(channel_callback), req_cb.ptr, ) @@ -3713,17 +3719,19 @@ fn local_publish_consume() { } #[test] -fn consume_announced_local() { +fn follow_local() { let origin = id(moq_origin_create()); // Start waiting before the broadcast exists: the announcement arrives afterwards. let cb = Callback::new(); let path = b"live"; let task = id(unsafe { - moq_origin_announced_broadcast( + moq_origin_follow( origin, path.as_ptr() as *const c_char, path.len(), + std::ptr::null(), + 0, Some(channel_callback), cb.ptr, ) @@ -3736,7 +3744,7 @@ fn consume_announced_local() { // The broadcast handle; the wait carries on for the next instance until cancelled. let consume = id(cb.recv()); - assert_eq!(moq_origin_announced_broadcast_cancel(task), 0); + assert_eq!(moq_origin_follow_cancel(task), 0); assert_eq!(cb.recv_terminal(), 0, "cancel delivers terminal 0"); // The delivered handle behaves like one from moq_origin_request. @@ -3875,26 +3883,28 @@ fn consume_audio_follows_a_sibling_broadcast_reference() { } #[test] -fn consume_announced_close_cancels() { +fn follow_close_cancels() { let origin = id(moq_origin_create()); // Wait for a broadcast that never arrives, then cancel it. let cb = Callback::new(); let path = b"never"; let task = id(unsafe { - moq_origin_announced_broadcast( + moq_origin_follow( origin, path.as_ptr() as *const c_char, path.len(), + std::ptr::null(), + 0, Some(channel_callback), cb.ptr, ) }); - assert_eq!(moq_origin_announced_broadcast_cancel(task), 0); + assert_eq!(moq_origin_follow_cancel(task), 0); assert_eq!(cb.recv_terminal(), 0, "close delivers terminal 0"); assert!( - moq_origin_announced_broadcast_cancel(task) < 0, + moq_origin_follow_cancel(task) < 0, "double-close should fail" ); @@ -3919,15 +3929,17 @@ fn publish_run(origin: u32, path: &str) -> moq_net::origin::Publication { /// Another publisher instance taking the path delivers a fresh handle on the same wait. #[test] -fn consume_announced_follows_a_restart() { +fn follow_delivers_a_restart() { let origin = id(moq_origin_create()); let cb = Callback::new(); let path = b"live"; let task = id(unsafe { - moq_origin_announced_broadcast( + moq_origin_follow( origin, path.as_ptr() as *const c_char, path.len(), + std::ptr::null(), + 0, Some(channel_callback), cb.ptr, ) @@ -3941,7 +3953,7 @@ fn consume_announced_follows_a_restart() { assert_eq!(moq_consume_close(first), 0); assert_eq!(moq_consume_close(second), 0); - assert_eq!(moq_origin_announced_broadcast_cancel(task), 0); + assert_eq!(moq_origin_follow_cancel(task), 0); assert_eq!(cb.recv_terminal(), 0, "cancel delivers terminal 0"); drop((first_run, second_run)); assert_eq!(moq_origin_close(origin), 0); @@ -3951,7 +3963,7 @@ fn consume_announced_follows_a_restart() { /// that announced it must not deliver it again. `dynamic_at` is where the route the wait first /// resolves through covers the path: above it, the takeover's restart lands while resolving; /// at it, the origin holds that restart for the default [`moq_net::origin::Config::update_hold`]. -fn consume_announced_delivers_a_takeover_once(dynamic_at: &str) { +fn follow_delivers_a_takeover_once(dynamic_at: &str) { let origin = id(moq_origin_create()); let dynamic = { let _runtime = crate::ffi::RUNTIME.enter(); @@ -3961,10 +3973,12 @@ fn consume_announced_delivers_a_takeover_once(dynamic_at: &str) { let cb = Callback::new(); let path = b"live"; let task = id(unsafe { - moq_origin_announced_broadcast( + moq_origin_follow( origin, path.as_ptr() as *const c_char, path.len(), + std::ptr::null(), + 0, Some(channel_callback), cb.ptr, ) @@ -3982,20 +3996,83 @@ fn consume_announced_delivers_a_takeover_once(dynamic_at: &str) { ); assert_eq!(moq_consume_close(delivered), 0); - assert_eq!(moq_origin_announced_broadcast_cancel(task), 0); + assert_eq!(moq_origin_follow_cancel(task), 0); assert_eq!(cb.recv_terminal(), 0, "cancel delivers terminal 0"); drop((takeover, dynamic)); assert_eq!(moq_origin_close(origin), 0); } #[test] -fn consume_announced_delivers_a_takeover_once_while_resolving() { - consume_announced_delivers_a_takeover_once(""); +fn follow_delivers_a_takeover_once_while_resolving() { + follow_delivers_a_takeover_once(""); +} + +#[test] +fn follow_delivers_a_held_takeover_once() { + follow_delivers_a_takeover_once("live"); +} + +/// `moq_origin_request` and `moq_origin_follow` share one signature. +type Resolve = unsafe extern "C" fn( + u32, + *const c_char, + usize, + *const c_char, + usize, + crate::ffi::moq_status_callback, + *mut c_void, +) -> i32; + +/// Resolve `live` on `origin` through `call`, pinned to `epoch`. +fn resolve_pinned(call: Resolve, origin: u32, epoch: &str, cb: &Callback) -> i32 { + let path = b"live"; + unsafe { + call( + origin, + path.as_ptr() as *const c_char, + path.len(), + epoch.as_ptr() as *const c_char, + epoch.len(), + Some(channel_callback), + cb.ptr, + ) + } } +/// An epoch pins both resolutions to one publisher instance: a request for another one fails, +/// a follower never delivers another one taking over, and malformed epoch text is refused. #[test] -fn consume_announced_delivers_a_held_takeover_once() { - consume_announced_delivers_a_takeover_once("live"); +fn an_epoch_pins_request_and_follow() { + let origin = id(moq_origin_create()); + let epoch = moq_net::Epoch::mint(); + let first = publish(origin, "live", moq_net::origin::Route::default().with_epoch(epoch.clone())); + let epoch = epoch.to_string(); + + let cb = Callback::new(); + id(resolve_pinned(moq_origin_request, origin, &epoch, &cb)); + assert_eq!(moq_consume_close(id(cb.recv())), 0); + assert_eq!(cb.recv_terminal(), 0); + let cb = Callback::new(); + id(resolve_pinned(moq_origin_request, origin, &moq_net::Epoch::mint().to_string(), &cb)); + assert!(cb.recv() < 0, "another instance resolved"); + assert!(resolve_pinned(moq_origin_follow, origin, "not-an-epoch", &Callback::new()) < 0); + + let cb = Callback::new(); + let task = id(resolve_pinned(moq_origin_follow, origin, &epoch, &cb)); + let delivered = id(cb.recv()); + let second = publish_run(origin, "live"); + assert!( + cb.rx + .recv_timeout(moq_net::origin::Config::default().update_hold * 2) + .is_err(), + "the follower delivered another instance" + ); + + assert_eq!(moq_consume_close(delivered), 0); + assert_eq!(moq_origin_follow_cancel(task), 0); + assert_eq!(cb.recv_terminal(), 0, "cancel delivers terminal 0"); + drop((first, second)); + assert_eq!(moq_origin_close(origin), 0); } /// Serve `prefix` on `origin` dynamically. @@ -4006,12 +4083,14 @@ fn serve_dynamic(origin: u32, prefix: &str) -> moq_net::origin::Requests { } /// Wait for the broadcast at `path` on `origin`, delivering each instance through `cb`. -fn consume_announced(origin: u32, path: &[u8], cb: &Callback) -> u32 { +fn follow(origin: u32, path: &[u8], cb: &Callback) -> u32 { id(unsafe { - moq_origin_announced_broadcast( + moq_origin_follow( origin, path.as_ptr() as *const c_char, path.len(), + std::ptr::null(), + 0, Some(channel_callback), cb.ptr, ) @@ -4038,7 +4117,7 @@ extern "C" fn gated_callback(user_data: *mut c_void, code: i32) { /// answers under the same epoch. So the instance serving the path afterwards is delivered again, /// though the caller still holds a handle to its epoch. #[test] -fn consume_announced_delivers_the_instance_again_after_an_end() { +fn follow_delivers_the_instance_again_after_an_end() { let origin = id(moq_origin_create()); let (tx, rx) = mpsc::channel(); let (release, hold) = mpsc::channel(); @@ -4048,10 +4127,12 @@ fn consume_announced_delivers_the_instance_again_after_an_end() { }); let path = b"live"; let task = id(unsafe { - moq_origin_announced_broadcast( + moq_origin_follow( origin, path.as_ptr() as *const c_char, path.len(), + std::ptr::null(), + 0, Some(gated_callback), &*gate as *const Gate as *mut c_void, ) @@ -4080,7 +4161,7 @@ fn consume_announced_delivers_the_instance_again_after_an_end() { assert_eq!(moq_consume_close(first), 0); assert_eq!(moq_consume_close(again), 0); - assert_eq!(moq_origin_announced_broadcast_cancel(task), 0); + assert_eq!(moq_origin_follow_cancel(task), 0); assert_eq!(recv(), 0, "cancel delivers terminal 0"); drop((run, dynamic, served, gate)); assert_eq!(moq_origin_close(origin), 0); @@ -4089,11 +4170,11 @@ fn consume_announced_delivers_the_instance_again_after_an_end() { /// A handle the caller freed no longer counts as delivered, so the restart that names its /// instance delivers it again rather than leaving the caller with nothing. #[test] -fn consume_announced_delivers_a_freed_takeover_again() { +fn follow_delivers_a_freed_takeover_again() { let origin = id(moq_origin_create()); let dynamic = serve_dynamic(origin, "live"); let cb = Callback::new(); - let task = consume_announced(origin, b"live", &cb); + let task = follow(origin, b"live", &cb); // Without an epoch, the origin holds the takeover's restart past its resolution. let _unanswered = crate::ffi::RUNTIME.block_on(dynamic.requested_broadcast()).unwrap(); @@ -4102,7 +4183,7 @@ fn consume_announced_delivers_a_freed_takeover_again() { let again = id(cb.recv()); assert_eq!(moq_consume_close(again), 0); - assert_eq!(moq_origin_announced_broadcast_cancel(task), 0); + assert_eq!(moq_origin_follow_cancel(task), 0); assert_eq!(cb.recv_terminal(), 0, "cancel delivers terminal 0"); drop((takeover, dynamic)); assert_eq!(moq_origin_close(origin), 0); @@ -4112,11 +4193,11 @@ fn consume_announced_delivers_a_freed_takeover_again() { /// reach the follower as an end and a start after the wait delivers the newcomer. That start /// must not deliver it again. #[test] -fn consume_announced_delivers_a_gap_while_resolving_once() { +fn follow_delivers_a_gap_while_resolving_once() { let origin = id(moq_origin_create()); let dynamic = serve_dynamic(origin, ""); let cb = Callback::new(); - let task = consume_announced(origin, b"live", &cb); + let task = follow(origin, b"live", &cb); let _unanswered = crate::ffi::RUNTIME.block_on(dynamic.requested_broadcast()).unwrap(); { @@ -4134,7 +4215,7 @@ fn consume_announced_delivers_a_gap_while_resolving_once() { ); assert_eq!(moq_consume_close(delivered), 0); - assert_eq!(moq_origin_announced_broadcast_cancel(task), 0); + assert_eq!(moq_origin_follow_cancel(task), 0); assert_eq!(cb.recv_terminal(), 0, "cancel delivers terminal 0"); drop(arrival); assert_eq!(moq_origin_close(origin), 0); @@ -6245,16 +6326,18 @@ fn server_accepts_a_session() { let path = b"demo"; let announced_cb = Callback::new(); let task = id(unsafe { - moq_origin_announced_broadcast( + moq_origin_follow( received, path.as_ptr() as *const c_char, path.len(), + std::ptr::null(), + 0, Some(channel_callback), announced_cb.ptr, ) }); let consumed = id(announced_cb.recv()); - assert_eq!(moq_origin_announced_broadcast_cancel(task), 0); + assert_eq!(moq_origin_follow_cancel(task), 0); assert_eq!(announced_cb.recv_terminal(), 0); // Prime the subscription, then queue a finished tail before closing the accepted // session. Its terminal callback must not report success after aborting the tail. diff --git a/rs/moq-ffi/src/origin.rs b/rs/moq-ffi/src/origin.rs index 67962b90f12..cae5ea665fe 100644 --- a/rs/moq-ffi/src/origin.rs +++ b/rs/moq-ffi/src/origin.rs @@ -210,13 +210,13 @@ impl Announced { } /// Follows one exact path, resolving each publisher instance that serves it. -struct AnnouncedBroadcast { +struct Following { inner: moq_net::origin::Following, origin: moq_net::origin::Consumer, driver: Background, } -impl AnnouncedBroadcast { +impl Following { async fn available(&mut self) -> Result, MoqError> { let broadcast = self.driver.watch(async { Ok(self.inner.available().await?) }).await?; Ok(Arc::new(MoqBroadcastConsumer::routed( @@ -230,7 +230,7 @@ impl AnnouncedBroadcast { /// A route over a prefix, carried by a [`MoqAnnounceEvent`]. /// /// Carries no broadcast: resolve a specific path with -/// `MoqOriginConsumer::request_broadcast` (after an event proves it is +/// `MoqOriginConsumer::request` (after an event proves it is /// covered). The application decides which paths name broadcasts. #[derive(Clone, Debug, PartialEq, Eq, uniffi::Record)] pub struct MoqAnnounce { @@ -302,8 +302,8 @@ impl From for MoqAnnounceEvent { /// Follows a specific broadcast across the publisher instances that serve it. #[derive(uniffi::Object)] -pub struct MoqAnnouncedBroadcast { - task: Task, +pub struct MoqFollowing { + task: Task, } impl MoqOriginProducer { @@ -462,19 +462,23 @@ impl MoqOriginConsumer { })) } - /// Follow the broadcast at `path`, resolving each publisher instance that serves it. + /// Follow the broadcast at `path` across the publisher instances that serve it. /// - /// Unlike `request_broadcast`, this waits for future announcements and keeps following - /// publisher instances. A local broadcast resolves once announced, like a remote one. - pub fn announced_broadcast(&self, path: String) -> Result, MoqError> { + /// Unlike `request`, this waits for future announcements and keeps following publisher + /// instances. A local broadcast resolves once announced, like a remote one. Pass an + /// `epoch` (UUIDv7 text) to follow only that instance: another one taking over is never + /// handed out, and the instance is handed out again if it returns after an end. + #[uniffi::method(default(epoch = None))] + pub fn follow(&self, path: String, epoch: Option) -> Result, MoqError> { let _guard = crate::ffi::enter(); self.driver.check()?; + let epoch: Option = epoch.as_deref().map(str::parse).transpose()?; // Following checks the permission eagerly, so an unreachable path fails here rather // than surfacing later as a `Closed` the caller can't tell from the origin ending. - let inner = self.inner.follow(path.as_str(), None)?; + let inner = self.inner.follow(path.as_str(), epoch)?; - Ok(Arc::new(MoqAnnouncedBroadcast { - task: Task::new(AnnouncedBroadcast { + Ok(Arc::new(MoqFollowing { + task: Task::new(Following { inner, origin: self.inner.clone(), driver: self.driver.clone(), @@ -482,18 +486,21 @@ impl MoqOriginConsumer { })) } - /// Request a broadcast by path, resolving as soon as it can be served. + /// Request the broadcast at `path`, resolving one publisher instance as soon as it can be served. /// /// Resolves through the best announced route covering the path: an announced broadcast /// on this origin, a route a session announced (served on demand by that session), or a /// dynamic handler on the origin. The most specific prefix wins, then the cheapest. An /// unannounced broadcast is unroutable once discovery has synced without a covering route. /// The request owns discovery of its path and retries route churn until then; no separate - /// announcement stream is needed. Drop the returned future to cancel. - pub async fn request_broadcast(&self, path: String) -> Result, MoqError> { + /// announcement stream is needed. Pass an `epoch` (UUIDv7 text) to refuse any other + /// publisher instance. Drop the returned future to cancel. + #[uniffi::method(default(epoch = None))] + pub async fn request(&self, path: String, epoch: Option) -> Result, MoqError> { + let epoch: Option = epoch.as_deref().map(str::parse).transpose()?; let broadcast = self .driver - .watch(async { Ok(self.inner.request(path.as_str(), None).await?) }) + .watch(async { Ok(self.inner.request(path.as_str(), epoch).await?) }) .await?; Ok(Arc::new(MoqBroadcastConsumer::routed( broadcast, @@ -651,10 +658,10 @@ impl MoqAnnounceConsumer { } } -// ---- MoqAnnouncedBroadcast ---- +// ---- MoqFollowing ---- #[uniffi::export] -impl MoqAnnouncedBroadcast { +impl MoqFollowing { /// Wait for the next publisher instance serving the broadcast. Returns `Closed` if cancelled /// or the origin is closed. /// @@ -692,7 +699,7 @@ mod supervision_tests { let healthy = MoqOriginProducer::new(Default::default()); let publication = healthy.create_broadcast("healthy".into()).unwrap(); publication.announce(Default::default()).unwrap(); - healthy.consume().request_broadcast("healthy".into()).await.unwrap(); + healthy.consume().request("healthy".into(), None).await.unwrap(); } #[tokio::test] @@ -801,7 +808,7 @@ mod supervision_tests { let broadcast = publication.broadcast(); let track = broadcast.publish_track("data".into(), None).unwrap(); let open = track.append_group().unwrap(); - let consumer = origin.consume().request_broadcast("routed".into()).await.unwrap(); + let consumer = origin.consume().request("routed".into(), None).await.unwrap(); let subscriber = consumer.subscribe_track("data".into(), None).await.unwrap(); let group = subscriber.recv_group().await.unwrap().unwrap(); let catalog = crate::media::MoqMediaCatalogConsumer::subscribe(&consumer) diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 58614cf37a3..8b8b236a28a 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -222,7 +222,7 @@ fn video_init(format: MoqVideoFormat, data: Vec) -> MoqVideoInit { /// A local reference published asynchronously may appear after discovery has synced empty. /// These tests wait for that future announcement before resolving the reference. async fn await_announced(consumer: &MoqOriginConsumer, path: &str) -> Arc { - let announced = consumer.announced_broadcast(path.into()).unwrap(); + let announced = consumer.follow(path.into(), None).unwrap(); tokio::time::timeout(TIMEOUT, announced.available()) .await .unwrap_or_else(|_| panic!("timed out waiting for {path} to be announced")) @@ -2955,21 +2955,21 @@ fn audio_rejects_bad_init_bytes() { /// Creating a broadcast does not make it exist for anyone: nothing crosses the /// announce cursor and nothing resolves until `announce`, locally exactly as for a -/// peer. `announced_broadcast` waits for the announcement. +/// peer. `follow` waits for the announcement. #[tokio::test] async fn create_broadcast_is_invisible_until_announced() { let origin = MoqOriginProducer::new(MoqOriginConfig::default()); let consumer = origin.consume(); let publication = origin.create_broadcast("live".into()).unwrap(); - let unroutable = tokio::time::timeout(TIMEOUT, consumer.request_broadcast("live".into())) + let unroutable = tokio::time::timeout(TIMEOUT, consumer.request("live".into(), None)) .await .expect("an unroutable request answers at once"); assert!(unroutable.is_err(), "an unannounced broadcast is unroutable"); let announced = consumer.announced(MoqAnnounceConfig::default()).unwrap(); let pending = tokio::spawn(async move { announced.next().await }); - let waiting = consumer.announced_broadcast("live".into()).unwrap(); + let waiting = consumer.follow("live".into(), None).unwrap(); let waited = tokio::spawn(async move { waiting.available().await }); tokio::time::sleep(std::time::Duration::from_millis(50)).await; assert!(!pending.is_finished(), "create_broadcast must not advertise the path"); @@ -2999,12 +2999,12 @@ async fn create_broadcast_is_invisible_until_announced() { /// rooting the cursor *at* the path would name it "", making the broadcast its own root, so /// a legal `../sibling` reference would read as escaping for every binding built on this. #[tokio::test] -async fn announced_broadcast_keeps_the_requested_path() { +async fn follow_keeps_the_requested_path() { let origin = MoqOriginProducer::new(MoqOriginConfig::default()); let consumer = origin.consume(); let broadcast = create_announced(&origin, "a/pub"); - let announced = consumer.announced_broadcast("a/pub".into()).unwrap(); + let announced = consumer.follow("a/pub".into(), None).unwrap(); let waited = tokio::time::timeout(TIMEOUT, announced.available()) .await .expect("timed out waiting for the announcement") @@ -3012,7 +3012,7 @@ async fn announced_broadcast_keeps_the_requested_path() { assert_eq!(waited.inner().info().path.as_str(), "a/pub"); // The same broadcast reached by request names itself identically. - let requested = tokio::time::timeout(TIMEOUT, consumer.request_broadcast("a/pub".into())) + let requested = tokio::time::timeout(TIMEOUT, consumer.request("a/pub".into(), None)) .await .expect("timed out requesting the broadcast") .unwrap(); @@ -3164,7 +3164,7 @@ async fn media_consumers_follow_a_rendition_track_in_a_sibling_broadcast() { /// Announcement filters do not re-root the origin, so relative broadcast references /// keep the same meaning as they have on the unfiltered consumer. #[tokio::test] -async fn announced_broadcasts_resolve_siblings_under_the_prefix() { +async fn followed_broadcasts_resolve_siblings_under_the_prefix() { let origin = MoqOriginProducer::new(MoqOriginConfig::default()); let consumer = origin.consume(); let announced = consumer @@ -3422,7 +3422,7 @@ async fn announce_and_unannounce_toggles_discovery() { wait_live(&announced, false).await; // Unannounced for local consumers exactly as for peers. - let unroutable = tokio::time::timeout(TIMEOUT, consumer.request_broadcast("live".into())) + let unroutable = tokio::time::timeout(TIMEOUT, consumer.request("live".into(), None)) .await .expect("an unroutable request answers at once"); assert!(unroutable.is_err(), "an unannounced broadcast is unroutable"); @@ -3430,7 +3430,7 @@ async fn announce_and_unannounce_toggles_discovery() { // Announcing again brings it back. publication.announce(MoqAnnounceRoute::default()).unwrap(); wait_live(&announced, true).await; - tokio::time::timeout(TIMEOUT, consumer.request_broadcast("live".into())) + tokio::time::timeout(TIMEOUT, consumer.request("live".into(), None)) .await .expect("timed out requesting the reannounced broadcast") .expect("a reannounced broadcast resolves"); @@ -3459,7 +3459,7 @@ async fn dropping_a_publication_keeps_its_route() { broadcast.close().unwrap(); publication.broadcast().close().unwrap(); for path in ["live", "held"] { - let unroutable = tokio::time::timeout(TIMEOUT, consumer.request_broadcast(path.into())) + let unroutable = tokio::time::timeout(TIMEOUT, consumer.request(path.into(), None)) .await .expect("an unroutable request answers at once"); assert!(unroutable.is_err(), "a closed broadcast is unroutable"); @@ -3483,7 +3483,7 @@ async fn a_stale_publication_leaves_its_replacement_alone() { Err(MoqError::Closed) )); assert!(matches!(stale.unannounce(), Err(MoqError::Closed))); - tokio::time::timeout(TIMEOUT, consumer.request_broadcast("live".into())) + tokio::time::timeout(TIMEOUT, consumer.request("live".into(), None)) .await .expect("timed out requesting the replacement") .expect("the replacement still resolves"); @@ -3497,7 +3497,7 @@ async fn finish_unpublishes() { let consumer = origin.consume(); let broadcast = create_announced(&origin, "live"); - let announced = consumer.announced_broadcast("live".into()).unwrap(); + let announced = consumer.follow("live".into(), None).unwrap(); tokio::time::timeout(TIMEOUT, announced.available()) .await .expect("timed out waiting for the announcement") @@ -3508,7 +3508,7 @@ async fn finish_unpublishes() { broadcast.close().unwrap(); let removed = tokio::time::timeout(TIMEOUT, async { loop { - if consumer.request_broadcast("live".into()).await.is_err() { + if consumer.request("live".into(), None).await.is_err() { return; } tokio::time::sleep(std::time::Duration::from_millis(10)).await; @@ -4503,7 +4503,7 @@ async fn accepting_a_request_after_close_is_refused() { } #[tokio::test] -async fn announced_broadcast() { +async fn follow() { let origin = MoqOriginProducer::new(MoqOriginConfig::default()); let _broadcast = create_announced(&origin, "test/broadcast"); @@ -4531,9 +4531,9 @@ async fn dynamic_broadcast_request() { let dynamic = serve(&origin, ""); let consumer = origin.consume(); - let request_broadcast = { + let requesting = { let consumer = consumer.clone(); - tokio::spawn(async move { consumer.request_broadcast("dynamic/broadcast".into()).await }) + tokio::spawn(async move { consumer.request("dynamic/broadcast".into(), None).await }) }; let request = tokio::time::timeout(TIMEOUT, dynamic.requested_broadcast()) @@ -4558,7 +4558,7 @@ async fn dynamic_broadcast_request() { .unwrap(); assert!(matches!(request.path(), Err(MoqError::Closed))); - let broadcast = tokio::time::timeout(TIMEOUT, request_broadcast) + let broadcast = tokio::time::timeout(TIMEOUT, requesting) .await .expect("timed out waiting for requested broadcast result") .expect("request task panicked") @@ -4593,9 +4593,9 @@ async fn dynamic_serves_a_request_under_a_prefix() { let consumer = origin.consume(); let dynamic = serve(&origin, "live"); - let request_broadcast = { + let requesting = { let consumer = consumer.clone(); - tokio::spawn(async move { consumer.request_broadcast("live/cam".into()).await }) + tokio::spawn(async move { consumer.request("live/cam".into(), None).await }) }; let request = tokio::time::timeout(TIMEOUT, dynamic.requested_broadcast()) .await @@ -4605,14 +4605,14 @@ async fn dynamic_serves_a_request_under_a_prefix() { let prepared = request.prepare(moq_net::Epoch::mint().to_string()).unwrap(); let served = prepared.broadcast(); prepared.publish().unwrap(); - tokio::time::timeout(TIMEOUT, request_broadcast) + tokio::time::timeout(TIMEOUT, requesting) .await .expect("timed out waiting for the request to resolve") .expect("request task panicked") .expect("the handler served the path"); dynamic.cancel(); - let err = tokio::time::timeout(TIMEOUT, consumer.request_broadcast("live/other".into())) + let err = tokio::time::timeout(TIMEOUT, consumer.request("live/other".into(), None)) .await .expect("timed out waiting for the retraction to reject the request") .err() @@ -4636,9 +4636,9 @@ async fn dynamic_keeps_the_origin_alive() { let dynamic = serve(&origin, ""); drop(origin); - let request_broadcast = { + let requesting = { let consumer = consumer.clone(); - tokio::spawn(async move { consumer.request_broadcast("live".into()).await }) + tokio::spawn(async move { consumer.request("live".into(), None).await }) }; let request = tokio::time::timeout(TIMEOUT, dynamic.requested_broadcast()) .await @@ -4647,7 +4647,7 @@ async fn dynamic_keeps_the_origin_alive() { let prepared = request.prepare(moq_net::Epoch::mint().to_string()).unwrap(); let served = prepared.broadcast(); prepared.publish().unwrap(); - tokio::time::timeout(TIMEOUT, request_broadcast) + tokio::time::timeout(TIMEOUT, requesting) .await .expect("timed out waiting for the request to resolve") .expect("request task panicked") @@ -5366,9 +5366,9 @@ async fn dynamic_broadcast_request_can_reject() { let dynamic = serve(&origin, ""); let consumer = origin.consume(); - let request_broadcast = { + let requesting = { let consumer = consumer.clone(); - tokio::spawn(async move { consumer.request_broadcast("missing".into()).await }) + tokio::spawn(async move { consumer.request("missing".into(), None).await }) }; let request = tokio::time::timeout(TIMEOUT, dynamic.requested_broadcast()) @@ -5380,7 +5380,7 @@ async fn dynamic_broadcast_request_can_reject() { request.reject(404).unwrap(); assert!(matches!(request.path(), Err(MoqError::Closed))); - let result = tokio::time::timeout(TIMEOUT, request_broadcast) + let result = tokio::time::timeout(TIMEOUT, requesting) .await .expect("timed out waiting for rejected broadcast") .expect("request task panicked"); @@ -5396,7 +5396,7 @@ async fn cancelling_dynamic_broadcasts_unregisters_the_handler() { dynamic.cancel(); assert!(matches!(dynamic.requested_broadcast().await, Err(MoqError::Closed))); - let result = tokio::time::timeout(TIMEOUT, consumer.request_broadcast("missing".into())) + let result = tokio::time::timeout(TIMEOUT, consumer.request("missing".into(), None)) .await .expect("request stayed pending after the dynamic handler was cancelled"); let err = match result { @@ -5437,7 +5437,7 @@ fn without_runtime() { other => panic!("expected an announcement, got {other:?}"), }; assert_eq!(announcement.prefix, "test"); - let _bc = pollster::block_on(consumer.request_broadcast("test".into())).unwrap(); + let _bc = pollster::block_on(consumer.request("test".into(), None)).unwrap(); let client = MoqClient::new(MoqClientConfig { tls: insecure_tls(), @@ -5625,7 +5625,7 @@ async fn roundtrip(media: &MoqMediaTrackProducer, track: &MoqMediaTrackConsumer, /// is still open, as a GOAWAY drain does. Without an epoch that is another instance: the /// next `available()` hands it out, and reading it carries on past the old session's close. #[tokio::test] -async fn announced_broadcast_follows_an_epochless_replacement() { +async fn follow_follows_an_epochless_replacement() { let server_origin = MoqOriginProducer::new(MoqOriginConfig::default()); let server = MoqServer::new(MoqServerConfig { bind: Some("127.0.0.1:0".into()), @@ -5672,7 +5672,7 @@ async fn announced_broadcast_follows_an_epochless_replacement() { }; let first = connect().await; - let followed = viewer.consume().announced_broadcast("cam".into()).unwrap(); + let followed = viewer.consume().follow("cam".into(), None).unwrap(); let old = tokio::time::timeout(TIMEOUT, followed.available()) .await .expect("timed out waiting for the broadcast") @@ -5703,10 +5703,10 @@ async fn announced_broadcast_follows_an_epochless_replacement() { /// keeps the same handle. Dropped while the instance is covered but not yet served, the retry /// must still hand that instance out rather than wait for another. #[tokio::test] -async fn announced_broadcast_retries_a_dropped_wait() { +async fn follow_retries_a_dropped_wait() { let origin = MoqOriginProducer::new(MoqOriginConfig::default()); let dynamic = serve(&origin, ""); - let followed = origin.consume().announced_broadcast("live".into()).unwrap(); + let followed = origin.consume().follow("live".into(), None).unwrap(); let waiting = followed.clone(); let dropped = tokio::spawn(async move { waiting.available().await }); @@ -5732,10 +5732,10 @@ async fn announced_broadcast_retries_a_dropped_wait() { /// is where the route the wait first resolves through covers the path: above it, the takeover's /// restart lands while resolving; at it, the origin holds that restart for /// the default [`moq_net::origin::Config::update_hold`]. -async fn announced_broadcast_hands_out_a_takeover_once(dynamic_at: &str) { +async fn follow_hands_out_a_takeover_once(dynamic_at: &str) { let origin = MoqOriginProducer::new(MoqOriginConfig::default()); let dynamic = serve(&origin, dynamic_at); - let followed = origin.consume().announced_broadcast("live".into()).unwrap(); + let followed = origin.consume().follow("live".into(), None).unwrap(); let waiting = followed.clone(); let first = tokio::spawn(async move { waiting.available().await }); @@ -5759,22 +5759,22 @@ async fn announced_broadcast_hands_out_a_takeover_once(dynamic_at: &str) { } #[tokio::test] -async fn announced_broadcast_hands_out_a_takeover_once_while_resolving() { - announced_broadcast_hands_out_a_takeover_once("").await; +async fn follow_hands_out_a_takeover_once_while_resolving() { + follow_hands_out_a_takeover_once("").await; } #[tokio::test] -async fn announced_broadcast_hands_out_a_held_takeover_once() { - announced_broadcast_hands_out_a_takeover_once("live").await; +async fn follow_hands_out_a_held_takeover_once() { + follow_hands_out_a_takeover_once("live").await; } /// An end is a gap that ended every request on the old route, even when a claim above the path /// answers under the same epoch. So the instance serving the path afterwards is handed out /// again, though its epoch is the one the caller still holds. #[tokio::test] -async fn announced_broadcast_hands_out_the_instance_again_after_an_end() { +async fn follow_hands_out_the_instance_again_after_an_end() { let origin = MoqOriginProducer::new(MoqOriginConfig::default()); - let followed = origin.consume().announced_broadcast("live".into()).unwrap(); + let followed = origin.consume().follow("live".into(), None).unwrap(); let route = MoqAnnounceRoute { epoch: Some(moq_mint_epoch()), ..Default::default() @@ -5811,14 +5811,69 @@ async fn announced_broadcast_hands_out_the_instance_again_after_an_end() { publication.broadcast().close().unwrap(); } +/// An epoch pins both resolutions to one publisher instance: a request for another one is +/// unroutable, and a follower never hands out another one taking over. +#[tokio::test] +async fn an_epoch_pins_request_and_follow() { + let origin = MoqOriginProducer::new(MoqOriginConfig::default()); + let consumer = origin.consume(); + let epoch = moq_mint_epoch(); + let first = origin.create_broadcast("live".into()).unwrap(); + first + .announce(MoqAnnounceRoute { + epoch: Some(epoch.clone()), + ..Default::default() + }) + .unwrap(); + + let pinned = tokio::time::timeout(TIMEOUT, consumer.request("live".into(), Some(epoch.clone()))) + .await + .expect("timed out requesting the pinned instance") + .unwrap(); + assert_eq!(pinned.inner().info().epoch.as_ref().map(ToString::to_string), Some(epoch.clone())); + let err = tokio::time::timeout(TIMEOUT, consumer.request("live".into(), Some(moq_mint_epoch()))) + .await + .expect("timed out requesting another instance") + .err() + .expect("another instance is unroutable"); + assert_protocol( + &err, + crate::error::MoqErrorScope::Stream, + crate::error::MoqProtocolKind::Unroutable, + ); + assert!(matches!( + consumer.follow("live".into(), Some("not-an-epoch".into())), + Err(MoqError::InvalidEpoch { .. }) + )); + + let followed = consumer.follow("live".into(), Some(epoch.clone())).unwrap(); + tokio::time::timeout(TIMEOUT, followed.available()) + .await + .expect("timed out following the pinned instance") + .unwrap(); + let second = origin.create_broadcast("live".into()).unwrap(); + second + .announce(MoqAnnounceRoute { + epoch: Some(moq_mint_epoch()), + ..Default::default() + }) + .unwrap(); + let next = tokio::spawn(async move { followed.available().await }); + tokio::time::sleep(moq_net::origin::Config::default().update_hold * 2).await; + assert!(!next.is_finished(), "the follower handed out another instance"); + next.abort(); + first.broadcast().close().unwrap(); + second.broadcast().close().unwrap(); +} + /// The route a wait resolves through leaving, and another instance arriving before it resolves, /// reach the follower as an end and a start after the wait hands the newcomer out. That start /// must not hand it out again. #[tokio::test] -async fn announced_broadcast_hands_out_a_gap_while_resolving_once() { +async fn follow_hands_out_a_gap_while_resolving_once() { let origin = MoqOriginProducer::new(MoqOriginConfig::default()); let dynamic = serve(&origin, ""); - let followed = origin.consume().announced_broadcast("live".into()).unwrap(); + let followed = origin.consume().follow("live".into(), None).unwrap(); let waiting = followed.clone(); let first = tokio::spawn(async move { waiting.available().await }); @@ -5845,10 +5900,10 @@ async fn announced_broadcast_hands_out_a_gap_while_resolving_once() { /// A handle the caller dropped no longer counts as handed out, so the restart that names it /// hands it out again rather than leaving the caller with nothing. #[tokio::test] -async fn announced_broadcast_hands_out_a_dropped_takeover_again() { +async fn follow_hands_out_a_dropped_takeover_again() { let origin = MoqOriginProducer::new(MoqOriginConfig::default()); let dynamic = serve(&origin, "live"); - let followed = origin.consume().announced_broadcast("live".into()).unwrap(); + let followed = origin.consume().follow("live".into(), None).unwrap(); let waiting = followed.clone(); let first = tokio::spawn(async move { waiting.available().await }); @@ -5940,7 +5995,7 @@ async fn server_client_roundtrip_auto_origin() { // session's publisher is discoverable through its own consumer. let local_broadcast = create_announced(&publisher, "local-only"); // Visibility is asynchronous, so wait for the announcement rather than requesting. - let local_announced = consumer.announced_broadcast("local-only".into()).unwrap(); + let local_announced = consumer.follow("local-only".into(), None).unwrap(); tokio::time::timeout(TIMEOUT, local_announced.available()) .await .expect("timed out waiting for the loopback broadcast") diff --git a/test/interop/clients/c/subscribe.c b/test/interop/clients/c/subscribe.c index 0353ce0ddaf..a25023aab22 100644 --- a/test/interop/clients/c/subscribe.c +++ b/test/interop/clients/c/subscribe.c @@ -462,7 +462,7 @@ static void finish(ctx_t *c, const struct timespec *deadline) { char *path = malloc(length); if (!path) fail("error: cannot allocate health path\n"); snprintf(path, length, "%s.health", c->finish.path); - c->finish.health_wait = moq_origin_announced_broadcast((uint32_t)c->origin, path, strlen(path), on_finish_health, c); + c->finish.health_wait = moq_origin_follow((uint32_t)c->origin, path, strlen(path), NULL, 0, on_finish_health, c); free(path); if (c->finish.health_wait <= 0) fail("error: health registration failed\n"); @@ -507,10 +507,10 @@ static void drain(ctx_t *c) { if (audio[i] > 0) moq_decode_audio_cancel((uint32_t)audio[i]); } if (cancel_catalog) moq_consume_catalog_cancel((uint32_t)c->catalog); - moq_origin_announced_broadcast_cancel((uint32_t)c->broadcast_wait); + moq_origin_follow_cancel((uint32_t)c->broadcast_wait); if (c->finish.enabled) { moq_origin_announced_cancel((uint32_t)c->finish.announcements); - moq_origin_announced_broadcast_cancel((uint32_t)c->finish.health_wait); + moq_origin_follow_cancel((uint32_t)c->finish.health_wait); } moq_session_close((uint32_t)c->session); @@ -638,7 +638,7 @@ int main(int argc, char **argv) { // announced. moq_origin_announced_broadcast resolves via on_broadcast once it's // available; we block on the condvar until then (or the deadline). c.broadcast_wait = - moq_origin_announced_broadcast((uint32_t)c.origin, broadcast, strlen(broadcast), on_broadcast, &c); + moq_origin_follow((uint32_t)c.origin, broadcast, strlen(broadcast), NULL, 0, on_broadcast, &c); if (c.broadcast_wait <= 0) { fail("error: moq_origin_announced_broadcast failed: %d\n", c.broadcast_wait); } From 4024d44e48dc3525c3b75e0cb6e6088155b73e3a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 21:27:41 -0700 Subject: [PATCH 3/7] feat(bindings)!: mirror request and follow in every wrapper Python, Swift, Kotlin, Dart, Go, C, C++, and OBS move from request_broadcast/announced_broadcast to request(path, epoch) and follow(path, epoch), and AnnouncedBroadcast becomes Following. The Dart bindings are regenerated, and tests, docs, interop clients, and the wasm harness follow. Deletes the bindings quest. Co-Authored-By: Claude Opus 5.5 --- c/moq/test/probe.c | 8 +- cpp/moq/test/probe.cpp | 2 +- cpp/obs/src/moq-source.cpp | 4 +- cpp/obs/test/moq-audio-encoder-test.cpp | 2 +- cpp/obs/test/moq-output-test.cpp | 2 +- dart/moq/lib/src/aliases.dart | 4 +- dart/moq/lib/src/client.dart | 16 +- dart/moq/test/moq_test.dart | 16 +- dart/moq_ffi/lib/src/moq.dart | 316 +++++++++--------- demo/carla/sim/moq_carla_sim/publish.py | 2 +- demo/carla/sim/tests/test_publish.py | 2 +- doc/lib/cpp/index.md | 2 +- doc/lib/dart/index.md | 4 +- doc/lib/go/index.md | 4 +- doc/lib/kt/index.md | 2 +- doc/lib/py/index.md | 2 +- doc/lib/swift/index.md | 2 +- go/wrapper/README.md | 2 +- go/wrapper/client.go | 21 +- go/wrapper/doc.go | 2 +- go/wrapper/moq_test.go | 36 +- go/wrapper/origin.go | 41 +-- go/wrapper/origin_internal_test.go | 14 +- go/wrapper/reconnect_test.go | 4 +- go/wrapper/types.go | 2 +- kt/README.md | 2 +- .../kotlin/dev/moq/Aliases.kt | 4 +- .../jvmAndAndroidMain/kotlin/dev/moq/Moq.kt | 23 +- .../kotlin/dev/moq/SmokeTest.kt | 18 +- py/moq-ffi/tests/exit_inside_callback.py | 2 +- py/moq-rs/README.md | 8 +- py/moq-rs/docs/index.md | 4 +- py/moq-rs/examples/clock.py | 2 +- py/moq-rs/moq/__init__.py | 4 +- py/moq-rs/moq/client.py | 17 +- py/moq-rs/moq/origin.py | 32 +- py/moq-rs/tests/test_local.py | 67 ++-- py/moq-rs/tests/test_server.py | 4 +- quest/m1/api-audit/resolve/README.md | 7 +- quest/m1/api-audit/resolve/bindings.md | 21 -- swift/README.md | 2 +- swift/Sources/Moq/Aliases.swift | 2 +- swift/Sources/Moq/Origin.swift | 28 +- swift/Tests/MoqTests/SmokeTests.swift | 18 +- test/interop/clients/c/subscribe.c | 8 +- test/interop/clients/cpp/main.cpp | 4 +- test/interop/clients/go/main.go | 6 +- test/interop/clients/python/interop.py | 6 +- test/wasm/baseline/consumer.ts | 2 +- test/wasm/baseline/uniffi.ts | 2 +- test/wasm/uniffi/cases.ts | 6 +- 51 files changed, 408 insertions(+), 403 deletions(-) delete mode 100644 quest/m1/api-audit/resolve/bindings.md diff --git a/c/moq/test/probe.c b/c/moq/test/probe.c index 111c80109fa..fdb7eea7af6 100644 --- a/c/moq/test/probe.c +++ b/c/moq/test/probe.c @@ -319,10 +319,10 @@ int main(void) { /* Subscriber: resolve the announced broadcast and subscribe to its track. */ moq_origin_consumer *remote_origin = moq_session_consume(session); - moq_announced_broadcast *announced = NULL; - ok(moq_origin_consumer_announced_broadcast(remote_origin, "probe", &announced), "announced_broadcast"); + moq_following *following = NULL; + ok(moq_origin_consumer_follow(remote_origin, "probe", NULL, &following), "follow"); result available = {0}; - task = moq_announced_broadcast_available(announced, on_broadcast, &available); + task = moq_following_available(following, on_broadcast, &available); moq_broadcast_consumer *remote = await(&available, "available"); moq_task_free(task); result subscribed = {0}; @@ -382,7 +382,7 @@ int main(void) { moq_track_consumer_free(consumer); moq_broadcast_consumer_free(remote); - moq_announced_broadcast_free(announced); + moq_following_free(following); moq_origin_consumer_free(remote_origin); moq_session_free(session); moq_session_free(served); diff --git a/cpp/moq/test/probe.cpp b/cpp/moq/test/probe.cpp index 3b72bf2e59b..c79e40dd08f 100644 --- a/cpp/moq/test/probe.cpp +++ b/cpp/moq/test/probe.cpp @@ -249,7 +249,7 @@ int main() { auto session = ok(connecting.get(), "connect"); // Subscriber: resolve the announced broadcast and subscribe to its track. - auto announced = ok(session->consume()->announced_broadcast("probe"), "announced_broadcast"); + auto announced = ok(session->consume()->follow("probe", std::nullopt), "follow"); auto remote = ok(announced->available().get(), "available"); auto consumer = ok(remote->subscribe_track("data", std::nullopt).get(), "subscribe_track"); diff --git a/cpp/obs/src/moq-source.cpp b/cpp/obs/src/moq-source.cpp index dfb5425162f..fde2d0e8548 100644 --- a/cpp/obs/src/moq-source.cpp +++ b/cpp/obs/src/moq-source.cpp @@ -144,7 +144,7 @@ struct Connection { std::shared_ptr client; std::shared_ptr session; - std::shared_ptr announced; + std::shared_ptr announced; // How many publisher instances `announced` has handed out; the newest is the one read. uint64_t instance = 0; @@ -417,7 +417,7 @@ static void moq_source_on_connect(struct moq_source *ctx, const std::shared_ptr< // Wait for the broadcast to be announced. Announcements arrive over the session // after it connects, so resolving against only what is announced *now* would race // them and blank the source for a broadcast that is live. - auto announced = conn->session->consume()->announced_broadcast(conn->broadcast); + auto announced = conn->session->consume()->follow(conn->broadcast, std::nullopt); if (!announced) { LOG_ERROR("Failed to request broadcast '%s': %s", conn->broadcast.c_str(), announced.error().to_string().c_str()); diff --git a/cpp/obs/test/moq-audio-encoder-test.cpp b/cpp/obs/test/moq-audio-encoder-test.cpp index 1b7a326a6c4..0ac27c34ca0 100644 --- a/cpp/obs/test/moq-audio-encoder-test.cpp +++ b/cpp/obs/test/moq-audio-encoder-test.cpp @@ -214,7 +214,7 @@ void CheckSubscriberDecodes(const char *preset, size_t channels) init.data = encoder.ExtraData(); auto track = TestOk(moq::MediaTrackProducer::audio(broadcast, moq::MediaTarget::kNamed{}, init), "audio track"); - auto announced = TestOk(origin->consume()->announced_broadcast("room"), "announced_broadcast"); + auto announced = TestOk(origin->consume()->follow("room", std::nullopt), "follow"); auto consumer = TestOk(announced->available().get(), "available"); auto catalogs = TestOk(moq::MediaCatalogConsumer::subscribe(consumer).get(), "catalog consumer"); std::optional catalog; diff --git a/cpp/obs/test/moq-output-test.cpp b/cpp/obs/test/moq-output-test.cpp index 7c0efb325e8..dd758210273 100644 --- a/cpp/obs/test/moq-output-test.cpp +++ b/cpp/obs/test/moq-output-test.cpp @@ -337,7 +337,7 @@ encoder_packet audioPacket(std::vector &payload, int64_t pts) // The output's broadcast as the relay serves it, or null once the wait times out. std::shared_ptr relayBroadcast(TestRelay &relay) { - auto announced = TestOk(relay.origin->consume()->announced_broadcast("room"), "announced_broadcast"); + auto announced = TestOk(relay.origin->consume()->follow("room", std::nullopt), "follow"); auto available = announced->available(); if (available.wait_for(std::chrono::seconds(10)) != std::future_status::ready) return nullptr; diff --git a/dart/moq/lib/src/aliases.dart b/dart/moq/lib/src/aliases.dart index 53c97b386c1..c763b237140 100644 --- a/dart/moq/lib/src/aliases.dart +++ b/dart/moq/lib/src/aliases.dart @@ -61,8 +61,8 @@ typedef AnnounceConsumer = MoqAnnounceConsumer; /// A literal prefix, an optional relative pattern, and the hidden-path opt-in for announcement discovery. typedef AnnounceConfig = MoqAnnounceConfig; -/// A pending wait for a route to cover a specific path. -typedef AnnouncedBroadcast = MoqAnnouncedBroadcast; +/// Follows a specific broadcast path across the publisher instances that serve it. +typedef Following = MoqFollowing; /// How a broadcast advertises its exact path: its static production cost and publisher epoch. typedef AnnounceRoute = MoqAnnounceRoute; diff --git a/dart/moq/lib/src/client.dart b/dart/moq/lib/src/client.dart index 008679e4bca..f8bda830179 100644 --- a/dart/moq/lib/src/client.dart +++ b/dart/moq/lib/src/client.dart @@ -230,13 +230,15 @@ final class Moq { }) => session.consume().announced(config: options._ffi); /// Follow the broadcast at exactly [path]: each `available()` resolves the - /// next publisher instance serving it, such as a restarted publisher. - AnnouncedBroadcast announcedBroadcast(String path) => - session.consume().announcedBroadcast(path: path); - - /// Resolve an existing broadcast at [path]. - Future requestBroadcast(String path) => - session.consume().requestBroadcast(path: path); + /// next publisher instance serving it, such as a restarted publisher. Pass an + /// [epoch] (UUIDv7 text) to follow only that instance. + Following follow(String path, {String? epoch}) => + session.consume().follow(path: path, epoch: epoch); + + /// Resolve one publisher instance of the broadcast at [path]. Pass an + /// [epoch] (UUIDv7 text) to refuse any other instance. + Future request(String path, {String? epoch}) => + session.consume().request(path: path, epoch: epoch); /// The session's bandwidth allocator. /// diff --git a/dart/moq/test/moq_test.dart b/dart/moq/test/moq_test.dart index 76ed785e749..d1d4c9c665f 100644 --- a/dart/moq/test/moq_test.dart +++ b/dart/moq/test/moq_test.dart @@ -219,9 +219,7 @@ void main() { (await announcement.timeout(timeout) as AnnounceEventStart).announce; expect(announced.prefix, 'live'); - final requested = await client - .requestBroadcast(announced.prefix) - .timeout(timeout); + final requested = await client.request(announced.prefix).timeout(timeout); final consumer = await requested .subscribeTrack(name: 'events', subscription: null) .timeout(timeout); @@ -402,7 +400,7 @@ void main() { broadcast.publishTrack(name: 'events', info: null); final consumer = origin.consume(); await expectLater( - consumer.requestBroadcast(path: 'live').timeout(timeout), + consumer.request(path: 'live').timeout(timeout), throwsA(anything), ); @@ -417,17 +415,17 @@ void main() { expect(retracted, isA()); expect((retracted as AnnounceEventEnd).announce.prefix, 'live'); await expectLater( - consumer.requestBroadcast(path: 'live').timeout(timeout), + consumer.request(path: 'live').timeout(timeout), throwsA(anything), ); publication.announce(route: AnnounceRoute()); expect(await nextRoute(announced), isA()); - await consumer.requestBroadcast(path: 'live').timeout(timeout); + await consumer.request(path: 'live').timeout(timeout); // Disposing the publication keeps the route; closing the broadcast ends it. publication.dispose(); - await consumer.requestBroadcast(path: 'live').timeout(timeout); + await consumer.request(path: 'live').timeout(timeout); broadcast.close(); expect(await nextRoute(announced), isA()); announced.cancel(); @@ -447,7 +445,7 @@ void main() { throwsA(isA()), ); expect(() => stale.unannounce(), throwsA(isA())); - await origin.consume().requestBroadcast(path: 'live').timeout(timeout); + await origin.consume().request(path: 'live').timeout(timeout); replacement.broadcast().close(); }); @@ -490,7 +488,7 @@ void main() { test('dynamic serves a request under a prefix', () async { final origin = MoqOriginProducer(config: MoqOriginConfig()); final dynamic = origin.requests(prefix: 'live'); - final pending = origin.consume().requestBroadcast(path: 'live/cam'); + final pending = origin.consume().request(path: 'live/cam'); final request = await dynamic.requestedBroadcast().timeout(timeout); expect(request.path(), 'live/cam'); final prepared = request.prepare(epoch: mintEpoch()); diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 92a0e4d32f3..eda57f94111 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -11561,97 +11561,6 @@ class FfiConverterMoqAnnounceConsumer { } } -abstract class MoqAnnouncedBroadcastInterface { - UniffiRustFuture available(); - void cancel(); -} - -final _MoqAnnouncedBroadcastFinalizer = Finalizer>((ptr) { - rustCall( - (status) => uniffi_moq_ffi_fn_free_moqannouncedbroadcast(ptr, status), - ); -}); - -class MoqAnnouncedBroadcast implements MoqAnnouncedBroadcastInterface { - late final Pointer _ptr; - bool _isDisposed = false; - MoqAnnouncedBroadcast._(this._ptr) { - _MoqAnnouncedBroadcastFinalizer.attach(this, _ptr, detach: this); - } - factory MoqAnnouncedBroadcast.lift(Pointer ptr) { - return MoqAnnouncedBroadcast._(ptr); - } - Pointer uniffiClonePointer() { - if (_isDisposed) { - throw StateError("Object has already been disposed"); - } - return rustCall( - (status) => uniffi_moq_ffi_fn_clone_moqannouncedbroadcast(_ptr, status), - ); - } - - void dispose() { - if (_isDisposed) { - return; - } - _isDisposed = true; - _MoqAnnouncedBroadcastFinalizer.detach(this); - rustCall( - (status) => uniffi_moq_ffi_fn_free_moqannouncedbroadcast(_ptr, status), - ); - } - - UniffiRustFuture available() { - return uniffiRustCallAsync( - () => uniffi_moq_ffi_fn_method_moqannouncedbroadcast_available( - uniffiClonePointer(), - ), - ffi_moq_ffi_rust_future_poll_u64, - ffi_moq_ffi_rust_future_complete_u64, - ffi_moq_ffi_rust_future_cancel_u64, - ffi_moq_ffi_rust_future_free_u64, - (ptr) => - FfiConverterMoqBroadcastConsumer.lift(Pointer.fromAddress(ptr)), - moqExceptionErrorHandler, - ); - } - - void cancel() { - return rustCall((status) { - uniffi_moq_ffi_fn_method_moqannouncedbroadcast_cancel( - uniffiClonePointer(), - status, - ); - }, null); - } -} - -class FfiConverterMoqAnnouncedBroadcast { - static MoqAnnouncedBroadcast lift(Pointer ptr) { - return MoqAnnouncedBroadcast.lift(ptr); - } - - static Pointer lower(MoqAnnouncedBroadcast value) { - return value.uniffiClonePointer(); - } - - static int allocationSize(MoqAnnouncedBroadcast value) { - return 8; - } - - static LiftRetVal read(Uint8List buf) { - final handle = buf.buffer.asByteData(buf.offsetInBytes).getInt64(0); - final pointer = Pointer.fromAddress(handle); - return LiftRetVal(MoqAnnouncedBroadcast.lift(pointer), 8); - } - - static int write(MoqAnnouncedBroadcast value, Uint8List buf) { - final handle = lower(value); - buf.buffer.asByteData(buf.offsetInBytes).setInt64(0, handle.address); - return 8; - } -} - abstract class MoqBroadcastPreparedInterface { MoqBroadcastProducer broadcast(); MoqPublication publish(); @@ -11840,11 +11749,98 @@ class FfiConverterMoqBroadcastRequest { } } +abstract class MoqFollowingInterface { + UniffiRustFuture available(); + void cancel(); +} + +final _MoqFollowingFinalizer = Finalizer>((ptr) { + rustCall((status) => uniffi_moq_ffi_fn_free_moqfollowing(ptr, status)); +}); + +class MoqFollowing implements MoqFollowingInterface { + late final Pointer _ptr; + bool _isDisposed = false; + MoqFollowing._(this._ptr) { + _MoqFollowingFinalizer.attach(this, _ptr, detach: this); + } + factory MoqFollowing.lift(Pointer ptr) { + return MoqFollowing._(ptr); + } + Pointer uniffiClonePointer() { + if (_isDisposed) { + throw StateError("Object has already been disposed"); + } + return rustCall( + (status) => uniffi_moq_ffi_fn_clone_moqfollowing(_ptr, status), + ); + } + + void dispose() { + if (_isDisposed) { + return; + } + _isDisposed = true; + _MoqFollowingFinalizer.detach(this); + rustCall((status) => uniffi_moq_ffi_fn_free_moqfollowing(_ptr, status)); + } + + UniffiRustFuture available() { + return uniffiRustCallAsync( + () => + uniffi_moq_ffi_fn_method_moqfollowing_available(uniffiClonePointer()), + ffi_moq_ffi_rust_future_poll_u64, + ffi_moq_ffi_rust_future_complete_u64, + ffi_moq_ffi_rust_future_cancel_u64, + ffi_moq_ffi_rust_future_free_u64, + (ptr) => + FfiConverterMoqBroadcastConsumer.lift(Pointer.fromAddress(ptr)), + moqExceptionErrorHandler, + ); + } + + void cancel() { + return rustCall((status) { + uniffi_moq_ffi_fn_method_moqfollowing_cancel( + uniffiClonePointer(), + status, + ); + }, null); + } +} + +class FfiConverterMoqFollowing { + static MoqFollowing lift(Pointer ptr) { + return MoqFollowing.lift(ptr); + } + + static Pointer lower(MoqFollowing value) { + return value.uniffiClonePointer(); + } + + static int allocationSize(MoqFollowing value) { + return 8; + } + + static LiftRetVal read(Uint8List buf) { + final handle = buf.buffer.asByteData(buf.offsetInBytes).getInt64(0); + final pointer = Pointer.fromAddress(handle); + return LiftRetVal(MoqFollowing.lift(pointer), 8); + } + + static int write(MoqFollowing value, Uint8List buf) { + final handle = lower(value); + buf.buffer.asByteData(buf.offsetInBytes).setInt64(0, handle.address); + return 8; + } +} + abstract class MoqOriginConsumerInterface { MoqAnnounceConsumer announced({required MoqAnnounceConfig config}); - MoqAnnouncedBroadcast announcedBroadcast({required String path}); - UniffiRustFuture requestBroadcast({ + MoqFollowing follow({required String path, String? epoch = null}); + UniffiRustFuture request({ required String path, + String? epoch = null, }); } @@ -11893,26 +11889,28 @@ class MoqOriginConsumer implements MoqOriginConsumerInterface { ); } - MoqAnnouncedBroadcast announcedBroadcast({required String path}) { + MoqFollowing follow({required String path, String? epoch = null}) { return rustCallWithLifter( - (status) => - uniffi_moq_ffi_fn_method_moqoriginconsumer_announced_broadcast( - uniffiClonePointer(), - FfiConverterString.lower(path), - status, - ), - FfiConverterMoqAnnouncedBroadcast.lift, + (status) => uniffi_moq_ffi_fn_method_moqoriginconsumer_follow( + uniffiClonePointer(), + FfiConverterString.lower(path), + FfiConverterOptionalString.lower(epoch), + status, + ), + FfiConverterMoqFollowing.lift, moqExceptionErrorHandler, ); } - UniffiRustFuture requestBroadcast({ + UniffiRustFuture request({ required String path, + String? epoch = null, }) { return uniffiRustCallAsync( - () => uniffi_moq_ffi_fn_method_moqoriginconsumer_request_broadcast( + () => uniffi_moq_ffi_fn_method_moqoriginconsumer_request( uniffiClonePointer(), FfiConverterString.lower(path), + FfiConverterOptionalString.lower(epoch), ), ffi_moq_ffi_rust_future_poll_u64, ffi_moq_ffi_rust_future_complete_u64, @@ -18222,35 +18220,6 @@ external Pointer uniffi_moq_ffi_fn_method_moqannounceconsumer_next( Pointer ptr, ); -@Native Function(Pointer, Pointer)>( - assetId: _uniffiAssetId, -) -external Pointer uniffi_moq_ffi_fn_clone_moqannouncedbroadcast( - Pointer handle, - Pointer uniffiStatus, -); - -@Native, Pointer)>( - assetId: _uniffiAssetId, -) -external void uniffi_moq_ffi_fn_free_moqannouncedbroadcast( - Pointer handle, - Pointer uniffiStatus, -); - -@Native Function(Pointer)>(assetId: _uniffiAssetId) -external Pointer uniffi_moq_ffi_fn_method_moqannouncedbroadcast_available( - Pointer ptr, -); - -@Native, Pointer)>( - assetId: _uniffiAssetId, -) -external void uniffi_moq_ffi_fn_method_moqannouncedbroadcast_cancel( - Pointer ptr, - Pointer uniffiStatus, -); - @Native Function(Pointer, Pointer)>( assetId: _uniffiAssetId, ) @@ -18325,6 +18294,35 @@ external void uniffi_moq_ffi_fn_method_moqbroadcastrequest_reject( Pointer uniffiStatus, ); +@Native Function(Pointer, Pointer)>( + assetId: _uniffiAssetId, +) +external Pointer uniffi_moq_ffi_fn_clone_moqfollowing( + Pointer handle, + Pointer uniffiStatus, +); + +@Native, Pointer)>( + assetId: _uniffiAssetId, +) +external void uniffi_moq_ffi_fn_free_moqfollowing( + Pointer handle, + Pointer uniffiStatus, +); + +@Native Function(Pointer)>(assetId: _uniffiAssetId) +external Pointer uniffi_moq_ffi_fn_method_moqfollowing_available( + Pointer ptr, +); + +@Native, Pointer)>( + assetId: _uniffiAssetId, +) +external void uniffi_moq_ffi_fn_method_moqfollowing_cancel( + Pointer ptr, + Pointer uniffiStatus, +); + @Native Function(Pointer, Pointer)>( assetId: _uniffiAssetId, ) @@ -18351,22 +18349,27 @@ external Pointer uniffi_moq_ffi_fn_method_moqoriginconsumer_announced( ); @Native< - Pointer Function(Pointer, RustBuffer, Pointer) + Pointer Function( + Pointer, + RustBuffer, + RustBuffer, + Pointer, + ) >(assetId: _uniffiAssetId) -external Pointer -uniffi_moq_ffi_fn_method_moqoriginconsumer_announced_broadcast( +external Pointer uniffi_moq_ffi_fn_method_moqoriginconsumer_follow( Pointer ptr, RustBuffer path, + RustBuffer epoch, Pointer uniffiStatus, ); -@Native Function(Pointer, RustBuffer)>( +@Native Function(Pointer, RustBuffer, RustBuffer)>( assetId: _uniffiAssetId, ) -external Pointer -uniffi_moq_ffi_fn_method_moqoriginconsumer_request_broadcast( +external Pointer uniffi_moq_ffi_fn_method_moqoriginconsumer_request( Pointer ptr, RustBuffer path, + RustBuffer epoch, ); @Native Function(Pointer, Pointer)>( @@ -20126,12 +20129,6 @@ external int uniffi_moq_ffi_checksum_method_moqannounceconsumer_cancel(); @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqannounceconsumer_next(); -@Native(assetId: _uniffiAssetId) -external int uniffi_moq_ffi_checksum_method_moqannouncedbroadcast_available(); - -@Native(assetId: _uniffiAssetId) -external int uniffi_moq_ffi_checksum_method_moqannouncedbroadcast_cancel(); - @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqbroadcastprepared_broadcast(); @@ -20147,16 +20144,20 @@ external int uniffi_moq_ffi_checksum_method_moqbroadcastrequest_prepare(); @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqbroadcastrequest_reject(); +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqfollowing_available(); + +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqfollowing_cancel(); + @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqoriginconsumer_announced(); @Native(assetId: _uniffiAssetId) -external int -uniffi_moq_ffi_checksum_method_moqoriginconsumer_announced_broadcast(); +external int uniffi_moq_ffi_checksum_method_moqoriginconsumer_follow(); @Native(assetId: _uniffiAssetId) -external int -uniffi_moq_ffi_checksum_method_moqoriginconsumer_request_broadcast(); +external int uniffi_moq_ffi_checksum_method_moqoriginconsumer_request(); @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqoriginproducer_consume(); @@ -20835,13 +20836,6 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqannounceconsumer_next() != 38311) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqannouncedbroadcast_available() != - 47724) { - throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); - } - if (uniffi_moq_ffi_checksum_method_moqannouncedbroadcast_cancel() != 63175) { - throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); - } if (uniffi_moq_ffi_checksum_method_moqbroadcastprepared_broadcast() != 42363) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); @@ -20858,15 +20852,19 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqbroadcastrequest_reject() != 9727) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } + if (uniffi_moq_ffi_checksum_method_moqfollowing_available() != 39867) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } + if (uniffi_moq_ffi_checksum_method_moqfollowing_cancel() != 37387) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } if (uniffi_moq_ffi_checksum_method_moqoriginconsumer_announced() != 16595) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqoriginconsumer_announced_broadcast() != - 40619) { + if (uniffi_moq_ffi_checksum_method_moqoriginconsumer_follow() != 6409) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqoriginconsumer_request_broadcast() != - 36974) { + if (uniffi_moq_ffi_checksum_method_moqoriginconsumer_request() != 26056) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqoriginproducer_consume() != 52357) { diff --git a/demo/carla/sim/moq_carla_sim/publish.py b/demo/carla/sim/moq_carla_sim/publish.py index dc9ced6527b..967f09bb12d 100644 --- a/demo/carla/sim/moq_carla_sim/publish.py +++ b/demo/carla/sim/moq_carla_sim/publish.py @@ -359,7 +359,7 @@ async def _pump_driver( """ log.info("driver %s connected (epoch %s)", driver_id, epoch) try: - broadcast = await client.request_broadcast(path) + broadcast = await client.request(path) control = moq.json.SnapshotConsumer(await broadcast.subscribe_track("control")) async for message in control: command = parse_command(driver_id, message, epoch) diff --git a/demo/carla/sim/tests/test_publish.py b/demo/carla/sim/tests/test_publish.py index ab36f542785..9d8646e1b67 100644 --- a/demo/carla/sim/tests/test_publish.py +++ b/demo/carla/sim/tests/test_publish.py @@ -217,7 +217,7 @@ def announced(self, prefix: str, *, filter: str): assert (prefix, filter) == ("viewer/carla/truck1", "*") return self.announcements - async def request_broadcast(self, path: str): + async def request(self, path: str): self.requested.append(path) sequence = len(self.requested) diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index 20995a40a57..d77985f418c 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -87,7 +87,7 @@ void ok(moq::expected result) { // Subscribe. auto client = ok(moq::Client::init({})); // a moq::ClientConfig; {} takes every default auto session = ok(client->connect("https://relay.example.com").get()); -auto announced = ok(session->consume()->announced_broadcast("my-stream.hang")); +auto announced = ok(session->consume()->follow("my-stream.hang", std::nullopt)); auto broadcast = ok(announced->available().get()); auto catalogs = ok(moq::MediaCatalogConsumer::subscribe(broadcast).get()); if (auto catalog = ok(catalogs->next().get())) { // std::nullopt once the catalog ends diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index 51dd58c06ba..ba654d0d989 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -67,7 +67,7 @@ moq } }); // Wait for a publisher at one path; call available() again for the next one. -final broadcast = await moq.announcedBroadcast('live/camera').available(); +final broadcast = await moq.follow('live/camera').available(); final catalog = await media.CatalogConsumer.subscribe(broadcast: broadcast); print(await catalog.next()); ``` @@ -102,7 +102,7 @@ encoder.finish(); // Decode a subscribed rendition. Dispose each frame promptly. import 'package:moq/video.dart' as video; -final remote = await moq.announcedBroadcast('live/camera').available(); +final remote = await moq.follow('live/camera').available(); final renditions = await media.CatalogConsumer.subscribe(broadcast: remote); final decoder = await video.Consumer.subscribe( broadcast: remote, diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index b5d42aa5407..19baef34708 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -75,7 +75,7 @@ for event, err := range announced.All(ctx) { } // Prefix stays origin-relative; Captures reports what each wildcard matched. fmt.Printf("captures: %v\n", ann.Captures) - broadcast, err := client.RequestBroadcast(ctx, ann.Prefix) + broadcast, err := client.Request(ctx, ann.Prefix, nil) if err != nil { log.Fatal(err) } @@ -125,7 +125,7 @@ The rest of the [shared feature list](/lib/#what-every-binding-can-do) maps one to one; the API reference has the names, and [Layers](/lib/layers) shows which module holds each. -- **Context cancellation.** Every call that can block takes a `context.Context` first, and cancelling it tears down the native work, not just your wait. A one-shot call (`RequestBroadcast`, `FetchGroup`, `Server.Accept`) aborts alone; a stream read (`Next`, `ReadFrame`, and the iterators over them) cancels the stream it reads. +- **Context cancellation.** Every call that can block takes a `context.Context` first, and cancelling it tears down the native work, not just your wait. A one-shot call (`Request`, `FetchGroup`, `Server.Accept`) aborts alone; a stream read (`Next`, `ReadFrame`, and the iterators over them) cancels the stream it reads. - **Keep owners reachable.** An origin from `moq.NewOriginProducer` has no `Close`. It ends when the garbage collector reaches its last owner (each producer, published broadcast, and `OriginRequests`), and its consumers then fail with `moq.ErrClosed`. - **Bandwidth ownership.** An encoder you manage can reserve a share of the session's bandwidth. Reuse its reservation when the ceiling changes; before abandoning or replacing it, call `Update(0)` to return its share and automatic probe ceiling without waiting for garbage collection. The track can stay subscribed and the reservation can be reused. - **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `Cut()`: after every frame, or at a segment cadence to align with video. diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index 52e2a492ac1..531e922a46d 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -59,7 +59,7 @@ Moq.connect("https://relay.example.com", ClientConfig(tls = ClientTls(roots = li } // Prefixes stay origin-relative; captures reports what each wildcard matched. println(announce.captures) - val broadcast = moq.requestBroadcast(announce.prefix) + val broadcast = moq.request(announce.prefix) println(catalog(broadcast)) } } diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index 8f56f83d11d..80ebdd0934d 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -51,7 +51,7 @@ async def main(): continue # AnnounceEventUpdate or AnnounceEventEnd announcement = event.announce print(announcement.captures) # what * matched, or None for a partial overlap - broadcast = await client.request_broadcast(announcement.prefix) + broadcast = await client.request(announcement.prefix) catalog = await moq.media.catalog(broadcast) id, audio = next(iter(catalog.audio.items())) async for frame in await moq.media.TrackConsumer.subscribe(broadcast, id, audio): diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index 6245d8f7f8d..5af5264056d 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -59,7 +59,7 @@ for try await event in try session.consume.announced(prefix: "live/", filter: "* } // Prefixes stay origin-relative; captures reports what each wildcard matched. print(announcement.captures ?? []) - let broadcast = try await session.consume.requestBroadcast(path: announcement.prefix) + let broadcast = try await session.consume.request(path: announcement.prefix) for try await catalog in try await Media.CatalogConsumer.subscribe(broadcast: broadcast) { print(catalog) } diff --git a/go/wrapper/README.md b/go/wrapper/README.md index eaee4298f65..2cd23e980d3 100644 --- a/go/wrapper/README.md +++ b/go/wrapper/README.md @@ -143,7 +143,7 @@ the session closed, i.e. not a real failure) and `moq.IsAuthError(err)` (HTTP Every call that can block takes a `context.Context` and aborts cleanly when it is cancelled, leaving nothing running in the background. A one-shot call (a subscribe, -a fetch, `RequestBroadcast`, `Resolve`, `WantedChanged`, `Used`/`Unused`, `Server.Accept`) aborts on +a fetch, `Request`, `Resolve`, `WantedChanged`, `Used`/`Unused`, `Server.Accept`) aborts on its own and leaves the object usable; a stream read cancels the stream it reads. See the package doc for details. diff --git a/go/wrapper/client.go b/go/wrapper/client.go index 4f1f8e71b43..533b9d788f1 100644 --- a/go/wrapper/client.go +++ b/go/wrapper/client.go @@ -312,18 +312,19 @@ func (c *Client) Announced(options AnnounceOptions) (*AnnounceConsumer, error) { return c.consumer.Announced(options) } -// AnnouncedBroadcast follows path, resolving each publisher instance that serves -// it. -func (c *Client) AnnouncedBroadcast(path string) (*AnnouncedBroadcast, error) { - return c.consumer.AnnouncedBroadcast(path) +// Follow follows path, resolving each publisher instance that serves it. A +// non-nil epoch follows only that instance. +func (c *Client) Follow(path string, epoch *string) (*Following, error) { + return c.consumer.Follow(path, epoch) } -// RequestBroadcast resolves a broadcast at path as soon as it can be served: an -// existing exact-path broadcast, a covering announced route, or a dynamic -// fallback on the origin, or an error. Unlike AnnouncedBroadcast, it does not wait -// for a future announcement. -func (c *Client) RequestBroadcast(ctx context.Context, path string) (*BroadcastConsumer, error) { - return c.consumer.RequestBroadcast(ctx, path) +// Request resolves one publisher instance of the broadcast at path as soon as +// it can be served: an existing exact-path broadcast, a covering announced +// route, or a dynamic fallback on the origin, or an error. Unlike Follow, it +// does not wait for a future announcement. A non-nil epoch refuses any other +// instance. +func (c *Client) Request(ctx context.Context, path string, epoch *string) (*BroadcastConsumer, error) { + return c.consumer.Request(ctx, path, epoch) } // Session returns the underlying session. Hold the client (or session) to keep diff --git a/go/wrapper/doc.go b/go/wrapper/doc.go index 4728018d1a0..a9f4aa52eba 100644 --- a/go/wrapper/doc.go +++ b/go/wrapper/doc.go @@ -24,7 +24,7 @@ // owner. // // What a cancel tears down depends on the call. A one-shot call (a subscribe, a -// fetch, RequestBroadcast, Resolve, a TrackDemand's WantedChanged, a +// fetch, Request, Resolve, a TrackDemand's WantedChanged, a // Fill's Unused, Server.Accept) aborts on its own and leaves the // object it was made on usable, so the same // broadcast, producer, or server takes the next call. A stream read (any Next, diff --git a/go/wrapper/moq_test.go b/go/wrapper/moq_test.go index 97145359327..136f946fc68 100644 --- a/go/wrapper/moq_test.go +++ b/go/wrapper/moq_test.go @@ -58,7 +58,7 @@ func TestDynamicBroadcastRequest(t *testing.T) { } requested := make(chan result, 1) go func() { - broadcast, err := origin.Consume().RequestBroadcast(ctx, "dynamic/broadcast") + broadcast, err := origin.Consume().Request(ctx, "dynamic/broadcast", nil) requested <- result{broadcast: broadcast, err: err} }() @@ -274,7 +274,7 @@ func TestAudioConsumerDelay(t *testing.T) { t.Fatal(err) } - bc, err := origin.Consume().RequestBroadcast(ctx, "audio-delay") + bc, err := origin.Consume().Request(ctx, "audio-delay", nil) if err != nil { t.Fatal(err) } @@ -449,7 +449,7 @@ func testDecodeVideoFrame(t *testing.T, surface bool) { } } - bc, err := origin.Consume().RequestBroadcast(ctx, "video-decode-frame") + bc, err := origin.Consume().Request(ctx, "video-decode-frame", nil) if err != nil { t.Fatal(err) } @@ -664,7 +664,7 @@ func TestLocalPublishConsumeAudio(t *testing.T) { t.Fatalf("route hops = %v, want empty for local origin", ann.Route.Hops) } - bc, err := consumer.RequestBroadcast(ctx, ann.Prefix) + bc, err := consumer.Request(ctx, ann.Prefix, nil) if err != nil { t.Fatal(err) } @@ -1173,10 +1173,10 @@ func TestConsumerCancelConcurrent(t *testing.T) { wg.Wait() } -// TestRequestBroadcastCancelKeepsTheOrigin cancels a RequestBroadcast parked on a +// TestRequestCancelKeepsTheOrigin cancels a Request parked on a // dynamic handler, then proves the origin still resolves: the cancel has to abort // that one request rather than the consumer it was made on. -func TestRequestBroadcastCancelKeepsTheOrigin(t *testing.T) { +func TestRequestCancelKeepsTheOrigin(t *testing.T) { origin := newOrigin(t) dynamic, err := origin.Requests("") if err != nil { @@ -1191,7 +1191,7 @@ func TestRequestBroadcastCancelKeepsTheOrigin(t *testing.T) { ctx, cancel := context.WithCancel(context.Background()) requested := make(chan error, 1) go func() { - _, err := consumer.RequestBroadcast(ctx, "never/served") + _, err := consumer.Request(ctx, "never/served", nil) requested <- err }() @@ -1209,7 +1209,7 @@ func TestRequestBroadcastCancelKeepsTheOrigin(t *testing.T) { t.Fatalf("err = %v, want context.Canceled", err) } case <-waitCtx.Done(): - t.Fatal("RequestBroadcast did not return after its context was cancelled") + t.Fatal("Request did not return after its context was cancelled") } _ = pending.Reject(0) @@ -1217,7 +1217,7 @@ func TestRequestBroadcastCancelKeepsTheOrigin(t *testing.T) { // cancel had torn the origin down. resolved := make(chan error, 1) go func() { - _, err := consumer.RequestBroadcast(waitCtx, "later/served") + _, err := consumer.Request(waitCtx, "later/served", nil) resolved <- err }() @@ -1448,7 +1448,7 @@ func TestBroadcastIsReachableOnlyWhileAnnounced(t *testing.T) { t.Fatal(err) } consumer := origin.Consume() - if _, err := consumer.RequestBroadcast(ctx, "live"); err == nil { + if _, err := consumer.Request(ctx, "live", nil); err == nil { t.Fatal("an unannounced broadcast must be unroutable") } @@ -1472,7 +1472,7 @@ func TestBroadcastIsReachableOnlyWhileAnnounced(t *testing.T) { if retracted, ok := event.(moq.AnnounceEventEnd); !ok || retracted.Announce.Prefix != "live" { t.Fatalf("unannounce: event=%+v", event) } - if _, err := consumer.RequestBroadcast(ctx, "live"); err == nil { + if _, err := consumer.Request(ctx, "live", nil); err == nil { t.Fatal("an unannounced broadcast must be unroutable") } @@ -1480,7 +1480,7 @@ func TestBroadcastIsReachableOnlyWhileAnnounced(t *testing.T) { t.Fatal(err) } nextAnnounced(t, ctx, announced) - if _, err := consumer.RequestBroadcast(ctx, "live"); err != nil { + if _, err := consumer.Request(ctx, "live", nil); err != nil { t.Fatal(err) } if err := broadcast.Close(); err != nil { @@ -1520,8 +1520,8 @@ func TestStalePublicationLeavesItsReplacementAlone(t *testing.T) { if err := stale.Unannounce(); !errors.Is(err, moq.ErrClosed) { t.Fatalf("stale Unannounce = %v, want ErrClosed", err) } - if _, err := origin.Consume().RequestBroadcast(ctx, "live"); err != nil { - t.Fatalf("RequestBroadcast = %v, want the replacement", err) + if _, err := origin.Consume().Request(ctx, "live", nil); err != nil { + t.Fatalf("Request = %v, want the replacement", err) } } @@ -1671,7 +1671,7 @@ func TestDynamicServesARequestUnderAPrefix(t *testing.T) { consumer := origin.Consume() done := make(chan error, 1) go func() { - _, err := consumer.RequestBroadcast(ctx, "live/cam") + _, err := consumer.Request(ctx, "live/cam", nil) done <- err }() @@ -1711,7 +1711,7 @@ func TestClosingAPreparedAnswerRefusesTheRequest(t *testing.T) { consumer := origin.Consume() done := make(chan error, 1) go func() { - _, err := consumer.RequestBroadcast(ctx, "live/cam") + _, err := consumer.Request(ctx, "live/cam", nil) done <- err }() @@ -1728,10 +1728,10 @@ func TestClosingAPreparedAnswerRefusesTheRequest(t *testing.T) { select { case err := <-done: if err == nil { - t.Fatal("RequestBroadcast succeeded, want the abandoned answer refused") + t.Fatal("Request succeeded, want the abandoned answer refused") } if ctx.Err() != nil { - t.Fatalf("RequestBroadcast err = %v, want a refusal before the deadline", err) + t.Fatalf("Request err = %v, want a refusal before the deadline", err) } case <-ctx.Done(): t.Fatal(ctx.Err()) diff --git a/go/wrapper/origin.go b/go/wrapper/origin.go index 58a701d2c02..bac6f59a75f 100644 --- a/go/wrapper/origin.go +++ b/go/wrapper/origin.go @@ -200,24 +200,25 @@ func (o *OriginConsumer) Announced(options AnnounceOptions) (*AnnounceConsumer, return &AnnounceConsumer{inner: inner}, nil } -// AnnouncedBroadcast follows an exact path, resolving each publisher instance -// that serves it. -func (o *OriginConsumer) AnnouncedBroadcast(path string) (*AnnouncedBroadcast, error) { - inner, err := o.inner.AnnouncedBroadcast(path) +// Follow follows an exact path, resolving each publisher instance that serves +// it. A non-nil epoch (UUIDv7 text) follows only that instance. +func (o *OriginConsumer) Follow(path string, epoch *string) (*Following, error) { + inner, err := o.inner.Follow(path, epoch) if err != nil { return nil, err } - return &AnnouncedBroadcast{inner: inner}, nil -} - -// RequestBroadcast resolves a broadcast at path as soon as it can be served, -// through the best announced route covering it: an announced broadcast on this -// origin, a route a session announced (served on demand by that session), or a -// dynamic handler on the origin; errors if nothing can serve it, including a -// broadcast created but not announced. Unlike AnnouncedBroadcast, it -// does not wait for a future announcement. Blocks until resolved. -func (o *OriginConsumer) RequestBroadcast(ctx context.Context, path string) (*BroadcastConsumer, error) { - inner, err := o.inner.RequestBroadcast(ctx, path) + return &Following{inner: inner}, nil +} + +// Request resolves one publisher instance of the broadcast at path as soon as +// it can be served, through the best announced route covering it: an announced +// broadcast on this origin, a route a session announced (served on demand by +// that session), or a dynamic handler on the origin; errors if nothing can +// serve it, including a broadcast created but not announced. Unlike Follow, it +// does not wait for a future announcement. A non-nil epoch (UUIDv7 text) +// refuses any other instance. Blocks until resolved. +func (o *OriginConsumer) Request(ctx context.Context, path string, epoch *string) (*BroadcastConsumer, error) { + inner, err := o.inner.Request(ctx, path, epoch) if err != nil { return nil, err } @@ -248,9 +249,9 @@ func (a *AnnounceConsumer) Cancel() { a.inner.Cancel() } -// AnnouncedBroadcast follows a specific broadcast across its publisher instances. -type AnnouncedBroadcast struct { - inner *ffi.MoqAnnouncedBroadcast +// Following follows a specific broadcast across its publisher instances. +type Following struct { + inner *ffi.MoqFollowing } // Available blocks until the next publisher instance serves the broadcast and @@ -259,7 +260,7 @@ type AnnouncedBroadcast struct { // publisher, or a replacement session) or for the broadcast to return after it went // offline. Drop what was read from the previous instance then: its tracks end when // its session does. -func (a *AnnouncedBroadcast) Available(ctx context.Context) (*BroadcastConsumer, error) { +func (a *Following) Available(ctx context.Context) (*BroadcastConsumer, error) { inner, err := bridge.CallHandle(ctx, a.inner.Cancel, a.inner.Available) if err != nil { return nil, err @@ -268,6 +269,6 @@ func (a *AnnouncedBroadcast) Available(ctx context.Context) (*BroadcastConsumer, } // Cancel stops awaiting the broadcast. -func (a *AnnouncedBroadcast) Cancel() { +func (a *Following) Cancel() { a.inner.Cancel() } diff --git a/go/wrapper/origin_internal_test.go b/go/wrapper/origin_internal_test.go index 1e70aadb0d9..8e99a3d4b34 100644 --- a/go/wrapper/origin_internal_test.go +++ b/go/wrapper/origin_internal_test.go @@ -30,8 +30,8 @@ func TestOriginEndsWithItsProducer(t *testing.T) { if update != nil || err != nil { t.Fatalf("Next = (%v, %v), want the end of the stream", update, err) } - if _, err := consumer.RequestBroadcast(ctx, "live"); !errors.Is(err, ErrClosed) { - t.Fatalf("RequestBroadcast err = %v, want ErrClosed", err) + if _, err := consumer.Request(ctx, "live", nil); !errors.Is(err, ErrClosed) { + t.Fatalf("Request err = %v, want ErrClosed", err) } } @@ -58,7 +58,7 @@ func TestRequestsKeepTheOrigin(t *testing.T) { } requested := make(chan result, 1) go func() { - broadcast, err := consumer.RequestBroadcast(ctx, "live") + broadcast, err := consumer.Request(ctx, "live", nil) requested <- result{broadcast: broadcast, err: err} }() @@ -83,7 +83,7 @@ func TestRequestsKeepTheOrigin(t *testing.T) { t.Fatal(ctx.Err()) } if res.err != nil { - t.Fatalf("RequestBroadcast err = %v, want the served broadcast", res.err) + t.Fatalf("Request err = %v, want the served broadcast", res.err) } } @@ -108,13 +108,13 @@ func TestReleasingAPublicationKeepsItsRoute(t *testing.T) { } publication.inner.Destroy() - if _, err := consumer.RequestBroadcast(ctx, "live"); err != nil { - t.Fatalf("RequestBroadcast = %v, want the released publication's broadcast", err) + if _, err := consumer.Request(ctx, "live", nil); err != nil { + t.Fatalf("Request = %v, want the released publication's broadcast", err) } if err := broadcast.Close(); err != nil { t.Fatal(err) } - if _, err := consumer.RequestBroadcast(ctx, "live"); err == nil { + if _, err := consumer.Request(ctx, "live", nil); err == nil { t.Fatal("a closed broadcast must be unroutable") } } diff --git a/go/wrapper/reconnect_test.go b/go/wrapper/reconnect_test.go index 40c20a46112..eca76e3b1fa 100644 --- a/go/wrapper/reconnect_test.go +++ b/go/wrapper/reconnect_test.go @@ -227,7 +227,7 @@ func TestReconnectAcrossRelayRestart(t *testing.T) { awaitAnnouncement(t, ctx, announced, "live") - before, err := subscriber.RequestBroadcast(ctx, "live") + before, err := subscriber.Request(ctx, "live", nil) if err != nil { t.Fatal(err) } @@ -266,7 +266,7 @@ func TestReconnectAcrossRelayRestart(t *testing.T) { // The subscriber resolves the re-announced broadcast again and receives // frames, which is how a worker follows a relay restart: the old handle's // broadcast closed with its source, and the announcement is what re-anchors. - after, err := subscriber.RequestBroadcast(ctx, "live") + after, err := subscriber.Request(ctx, "live", nil) if err != nil { t.Fatal(err) } diff --git a/go/wrapper/types.go b/go/wrapper/types.go index a8d36371723..6b1f5abc478 100644 --- a/go/wrapper/types.go +++ b/go/wrapper/types.go @@ -40,7 +40,7 @@ type ( // Announce is a route over a prefix: the origin-relative Prefix, what each filter // wildcard matched (nil Captures for a route that only overlaps the scope), and the // Route serving it. It carries no broadcast; resolve a path with - // [OriginConsumer.RequestBroadcast]. + // [OriginConsumer.Request]. Announce = ffi.MoqAnnounce // AnnounceEvent is what an AnnounceConsumer yields: AnnounceEventStart, // AnnounceEventUpdate, AnnounceEventEnd, or AnnounceEventRestart. diff --git a/kt/README.md b/kt/README.md index 4c53ba75d8b..f01efff502b 100644 --- a/kt/README.md +++ b/kt/README.md @@ -41,7 +41,7 @@ Moq.connect("https://relay.example.com").use { moq -> println("got broadcast ${announce.prefix}") println("captures ${announce.captures}") - val catalog = dev.moq.media.catalog(moq.requestBroadcast(announce.prefix)) + val catalog = dev.moq.media.catalog(moq.request(announce.prefix)) println("catalog: $catalog") } } diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt index cc84227d1df..bf527fd7b8b 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt @@ -53,8 +53,8 @@ typealias BroadcastPrepared = uniffi.moq.MoqBroadcastPrepared typealias AnnounceConsumer = uniffi.moq.MoqAnnounceConsumer /** A literal prefix, an optional relative pattern, and the hidden-path opt-in for announcement discovery. */ typealias AnnounceConfig = uniffi.moq.MoqAnnounceConfig -/** A pending wait for a route to cover a specific path. */ -typealias AnnouncedBroadcast = uniffi.moq.MoqAnnouncedBroadcast +/** Follows a specific broadcast path across the publisher instances that serve it. */ +typealias Following = uniffi.moq.MoqFollowing /** A route over a prefix: its origin-relative path, wildcard captures, and route metadata. */ typealias Announce = uniffi.moq.MoqAnnounce /** diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt index a0b7eb238fe..66528ce225f 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Moq.kt @@ -35,21 +35,24 @@ class Moq internal constructor( /** * Follow exactly [path], resolving each publisher instance that serves it. * - * Unlike [requestBroadcast] this waits indefinitely for a future - * announcement, and each later `available()` waits for the next instance, - * such as a restarted publisher. Cancel the returned handle to stop waiting. + * Unlike [request] this waits indefinitely for a future announcement, and + * each later `available()` waits for the next instance, such as a restarted + * publisher. Pass an [epoch] (UUIDv7 text) to follow only that instance. + * Cancel the returned handle to stop waiting. */ - fun announcedBroadcast(path: String): AnnouncedBroadcast = session.consume().announcedBroadcast(path) + fun follow(path: String, epoch: String? = null): Following = session.consume().follow(path, epoch) /** - * Resolve the broadcast at [path] as soon as it can be served: a local - * broadcast at the exact path, the best announced route covering it, or a - * dynamic fallback on the origin. + * Resolve one publisher instance of the broadcast at [path] as soon as it + * can be served: a local broadcast at the exact path, the best announced + * route covering it, or a dynamic fallback on the origin. * - * Unlike [announcedBroadcast] this does not wait for a future announcement; - * it throws when neither can serve the path. + * Unlike [follow] this does not wait for a future announcement; it throws + * when neither can serve the path. Pass an [epoch] (UUIDv7 text) to refuse + * any other instance. */ - suspend fun requestBroadcast(path: String): BroadcastConsumer = session.consume().requestBroadcast(path) + suspend fun request(path: String, epoch: String? = null): BroadcastConsumer = + session.consume().request(path, epoch) /** * The session's bandwidth allocator. diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index 656b6859c8d..933e8d7d9e3 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -531,7 +531,7 @@ class SmokeTest { origin.createBroadcast("live").use { publication -> publication.broadcast().use { it.publishTrack("events", null) } val consumer = origin.consume() - assertFailsWith { consumer.requestBroadcast("live") } + assertFailsWith { consumer.request("live") } publication.announce(AnnounceRoute()) val announced = consumer.announced(AnnounceConfig()) @@ -541,11 +541,11 @@ class SmokeTest { publication.unannounce() val retracted = assertIs(announced.nextRoute()) assertEquals("live", retracted.announce.prefix) - assertFailsWith { consumer.requestBroadcast("live") } + assertFailsWith { consumer.request("live") } publication.announce(AnnounceRoute()) assertIs(announced.nextRoute()) - consumer.requestBroadcast("live") + consumer.request("live") } } } @@ -559,11 +559,11 @@ class SmokeTest { publication.broadcast().use { broadcast -> publication.use { it.announce(AnnounceRoute()) } assertIs(announced.nextRoute()) - consumer.requestBroadcast("live") + consumer.request("live") broadcast.end() assertIs(announced.nextRoute()) - assertFailsWith { consumer.requestBroadcast("live") } + assertFailsWith { consumer.request("live") } } } } @@ -579,7 +579,7 @@ class SmokeTest { replacement.announce(AnnounceRoute()) assertFailsWith { stale.announce(AnnounceRoute()) } assertFailsWith { stale.unannounce() } - origin.consume().requestBroadcast("live") + origin.consume().request("live") replacement.broadcast().use { it.end() } } } @@ -624,7 +624,7 @@ class SmokeTest { OriginProducer(OriginConfig()).use { origin -> origin.requests("live").use { dynamic -> val pending = async { - origin.consume().requestBroadcast("live/cam") + origin.consume().request("live/cam") } val request = dynamic.requestedBroadcast() assertEquals("live/cam", request.path()) @@ -751,7 +751,7 @@ class SmokeTest { ) publication.announce(AnnounceRoute()) - val consumer = origin.consume().requestBroadcast("audio-delay") + val consumer = origin.consume().request("audio-delay") val catalog = CatalogConsumer.subscribe(consumer).next()!! val rendition = catalog.audio["mic"]!! @@ -802,7 +802,7 @@ class SmokeTest { video.write(VideoFrame(timestampUs = i.toULong() * 33_333uL, data = rgba)) } - val consumer = origin.consume().requestBroadcast("video-decode-frame") + val consumer = origin.consume().request("video-decode-frame") val catalog = CatalogConsumer.subscribe(consumer).next()!! val rendition = catalog.video["camera"]!! diff --git a/py/moq-ffi/tests/exit_inside_callback.py b/py/moq-ffi/tests/exit_inside_callback.py index ce4d75568a6..6abe1fa4042 100644 --- a/py/moq-ffi/tests/exit_inside_callback.py +++ b/py/moq-ffi/tests/exit_inside_callback.py @@ -59,7 +59,7 @@ async def main() -> None: broadcast = publication.broadcast() track = broadcast.publish_track("data", moq_ffi.MoqTrackInfo(timescale=1_000_000)) - consumer = await origin.consume().request_broadcast("exit") + consumer = await origin.consume().request("exit") subscriber = await consumer.subscribe_track("data", None) # Written once the read is parked, so the runtime thread delivers the wake. diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index a386939ee0c..f2e5aa39b7c 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -33,7 +33,7 @@ async def main(): if not isinstance(event, (moq.AnnounceEventStart, moq.AnnounceEventRestart)): continue # AnnounceEventUpdate or AnnounceEventEnd # A route covers a prefix and carries no broadcast, so resolve the path. - broadcast = await client.request_broadcast(event.announce.prefix) + broadcast = await client.request(event.announce.prefix) catalog = await moq.media.catalog(broadcast) for id, audio in catalog.audio.items(): @@ -245,7 +245,7 @@ same either way. Opaque bytes go on a plain `TrackProducer`. - **`GroupConsumer`**. Async iterator of raw `Frame`s. - `.read_frame() -> Frame | None` returns a raw frame with optional capture time. -Every handle whose cleanup is `cancel()` is an async context manager, so exiting `async with` releases it: the consumers (`media.CatalogConsumer`, `media.TrackConsumer`, `media.GroupConsumer`, `TrackConsumer`, `audio.Consumer`, `video.Consumer`, `GroupConsumer`, `json.SnapshotConsumer`, `json.StreamConsumer`, `json.WindowConsumer`, `AnnounceConsumer`, `AnnouncedBroadcast`) and the dynamic sources (`OriginRequests`, `BroadcastRequests`, `TrackRequests`). +Every handle whose cleanup is `cancel()` is an async context manager, so exiting `async with` releases it: the consumers (`media.CatalogConsumer`, `media.TrackConsumer`, `media.GroupConsumer`, `TrackConsumer`, `audio.Consumer`, `video.Consumer`, `GroupConsumer`, `json.SnapshotConsumer`, `json.StreamConsumer`, `json.WindowConsumer`, `AnnounceConsumer`, `Following`) and the dynamic sources (`OriginRequests`, `BroadcastRequests`, `TrackRequests`). ### Origin (advanced) @@ -261,8 +261,8 @@ Every handle whose cleanup is `cancel()` is an async context manager, so exiting - Async iterator yielding `BroadcastRequest` - **`OriginConsumer`**. Discover broadcasts. - `.announced(prefix, filter=None) → AnnounceConsumer` (async iterator of `AnnounceEvent`: `AnnounceEventStart`, `AnnounceEventUpdate`, `AnnounceEventEnd`, or `AnnounceEventRestart`, each carrying an `Announce` whose `.route.epoch` names the publisher run; on a restart, request the path again); `filter` is a pattern relative to the literal prefix, while each `Announce.prefix` stays origin-relative and `.captures` reports wildcard matches - - `.announced_broadcast(path) → AnnouncedBroadcast` (awaitable, waits until something serves the path) - - `.request_broadcast(path) → BroadcastConsumer` (awaitable; owns discovery and resolves one instance, or raises once synced without a route) + - `.follow(path, epoch=None) → Following` (awaitable, waits until something serves the path, then each instance that takes over; an `epoch` follows only that instance) + - `.request(path, epoch=None) → BroadcastConsumer` (awaitable; owns discovery and resolves one instance, or raises once synced without a route; an `epoch` refuses any other instance) ### Types diff --git a/py/moq-rs/docs/index.md b/py/moq-rs/docs/index.md index 3d8f6935ab2..1351c75c8be 100644 --- a/py/moq-rs/docs/index.md +++ b/py/moq-rs/docs/index.md @@ -18,7 +18,7 @@ async def main(): async with moq.Client("https://cdn.moq.dev/anon") as client: async for event in client.announced(): if isinstance(event, moq.AnnounceEventStart): - broadcast = await client.request_broadcast(event.announce.prefix) + broadcast = await client.request(event.announce.prefix) print(await moq.media.catalog(broadcast)) @@ -169,7 +169,7 @@ broadcast, and producers advertise it in the catalog. OriginRequests Publication AnnounceConsumer - AnnouncedBroadcast + Following Announce AnnounceEvent AnnounceEventStart diff --git a/py/moq-rs/examples/clock.py b/py/moq-rs/examples/clock.py index 6e1f186efbc..d7a89720d7c 100644 --- a/py/moq-rs/examples/clock.py +++ b/py/moq-rs/examples/clock.py @@ -41,7 +41,7 @@ async def publish(url: str, broadcast_name: str, track_name: str, insecure: bool async def subscribe(url: str, broadcast_name: str, track_name: str, insecure: bool) -> None: async with moq.Client(url, tls=moq.ClientTls(insecure=insecure)) as client: print(f"waiting for {broadcast_name!r} at {url}") - broadcast = await client.announced_broadcast(broadcast_name) + broadcast = await client.follow(broadcast_name) print(f"subscribed to {broadcast_name!r} track={track_name!r}") track = await broadcast.subscribe_track(track_name) diff --git a/py/moq-rs/moq/__init__.py b/py/moq-rs/moq/__init__.py index 444077a386c..8f5a72b486e 100644 --- a/py/moq-rs/moq/__init__.py +++ b/py/moq-rs/moq/__init__.py @@ -17,7 +17,6 @@ from .origin import ( Announce, AnnounceConsumer, - AnnouncedBroadcast, AnnounceEvent, AnnounceEventEnd, AnnounceEventRestart, @@ -25,6 +24,7 @@ AnnounceEventUpdate, BroadcastPrepared, BroadcastRequest, + Following, OriginConsumer, OriginProducer, OriginRequests, @@ -85,7 +85,6 @@ "Anchor", "Announce", "AnnounceConsumer", - "AnnouncedBroadcast", "AnnounceEvent", "AnnounceEventEnd", "AnnounceEventRestart", @@ -117,6 +116,7 @@ "QuicConfig", "FetchGroupOptions", "Fill", + "Following", "Grant", "GrantConsumer", "GroupConsumer", diff --git a/py/moq-rs/moq/client.py b/py/moq-rs/moq/client.py index 9b476539a0b..c741caa936b 100644 --- a/py/moq-rs/moq/client.py +++ b/py/moq-rs/moq/client.py @@ -14,7 +14,7 @@ ) from ._records import Backoff, ClientTls, QuicConfig, WebSocketConfig, _implementation, _strs -from .origin import AnnounceConsumer, AnnouncedBroadcast, OriginConsumer, OriginProducer, Publication +from .origin import AnnounceConsumer, Following, OriginConsumer, OriginProducer, Publication from .session import Session from .subscribe import BroadcastConsumer @@ -169,16 +169,19 @@ def announced(self, prefix: str = "", *, filter: str | None = None, hidden: bool """ return self._require_consumer().announced(prefix, filter=filter, hidden=hidden) - def announced_broadcast(self, path: str) -> AnnouncedBroadcast: + def follow(self, path: str, *, epoch: str | None = None) -> Following: """Follow the broadcast at exactly ``path`` across its publisher instances. - See :meth:`OriginConsumer.announced_broadcast`. + See :meth:`OriginConsumer.follow`. """ - return self._require_consumer().announced_broadcast(path) + return self._require_consumer().follow(path, epoch=epoch) - async def request_broadcast(self, path: str) -> BroadcastConsumer: - """Request a broadcast by path, resolving as soon as it can be served.""" - return await self._require_consumer().request_broadcast(path) + async def request(self, path: str, *, epoch: str | None = None) -> BroadcastConsumer: + """Request the broadcast at ``path``, resolving one publisher instance as soon as it can be served. + + See :meth:`OriginConsumer.request`. + """ + return await self._require_consumer().request(path, epoch=epoch) def _require_publisher(self) -> OriginProducer: if self._publisher is None: diff --git a/py/moq-rs/moq/origin.py b/py/moq-rs/moq/origin.py index 744fd569881..6584ce1356e 100644 --- a/py/moq-rs/moq/origin.py +++ b/py/moq-rs/moq/origin.py @@ -6,10 +6,10 @@ MoqAnnounce, MoqAnnounceConfig, MoqAnnounceConsumer, - MoqAnnouncedBroadcast, MoqAnnounceEvent, MoqBroadcastPrepared, MoqBroadcastRequest, + MoqFollowing, MoqOriginConfig, MoqOriginConsumer, MoqOriginProducer, @@ -27,7 +27,7 @@ matched (``captures``, ``None`` for a partial overlap), and the ``route`` serving it. It carries no broadcast. Resolve a specific path with -:meth:`OriginConsumer.request_broadcast`. By convention a publisher announces +:meth:`OriginConsumer.request`. By convention a publisher announces each broadcast's exact path, so subscribers can enumerate broadcasts from routes. """ @@ -69,7 +69,7 @@ def cancel(self) -> None: self._inner.cancel() -class AnnouncedBroadcast: +class Following: """Follows a specific path across the publisher instances that serve it. ``await`` it (or call :meth:`available`) to get the :class:`BroadcastConsumer` @@ -77,7 +77,7 @@ class AnnouncedBroadcast: Usable as an async context manager. """ - def __init__(self, inner: MoqAnnouncedBroadcast) -> None: + def __init__(self, inner: MoqFollowing) -> None: self._inner = inner async def __aenter__(self): @@ -196,9 +196,9 @@ def cancel(self) -> None: class OriginConsumer: """The discovery side of an origin: find and subscribe to broadcasts. - Iterate :meth:`announced` to watch broadcasts appear, await - :meth:`announced_broadcast` for a specific path, or :meth:`request_broadcast` - to resolve one as soon as it can be served. + Iterate :meth:`announced` to watch broadcasts appear, :meth:`follow` a + specific path across its publisher instances, or :meth:`request` one + instance as soon as it can be served. """ def __init__(self, inner: MoqOriginConsumer) -> None: @@ -211,25 +211,25 @@ def announced(self, prefix: str = "", *, filter: str | None = None, hidden: bool """ return AnnounceConsumer(self._inner.announced(MoqAnnounceConfig(prefix=prefix, filter=filter, hidden=hidden))) - def announced_broadcast(self, path: str) -> AnnouncedBroadcast: + def follow(self, path: str, *, epoch: str | None = None) -> Following: """Follow the broadcast at ``path``, resolving each publisher instance that serves it. A broadcast created on this origin resolves once it is announced, like a - remote one. + remote one. Pass an ``epoch`` (UUIDv7 text) to follow only that instance. """ - return AnnouncedBroadcast(self._inner.announced_broadcast(path)) + return Following(self._inner.follow(path, epoch)) - async def request_broadcast(self, path: str) -> BroadcastConsumer: - """Request a broadcast by path, resolving as soon as it can be served. + async def request(self, path: str, *, epoch: str | None = None) -> BroadcastConsumer: + """Request the broadcast at ``path``, resolving one publisher instance as soon as it can be served. Resolves through the best announced route covering the path: an announced broadcast on this origin, a route a session announced (served on demand by that session), or a dynamic handler on the origin. An - unannounced broadcast is unroutable. Unlike - `announced_broadcast`, this answers for what is reachable now and raises - if nothing can serve the path. + unannounced broadcast is unroutable. Unlike :meth:`follow`, this + answers for what is reachable now and raises if nothing can serve the + path. Pass an ``epoch`` (UUIDv7 text) to refuse any other instance. """ - return BroadcastConsumer(await self._inner.request_broadcast(path)) + return BroadcastConsumer(await self._inner.request(path, epoch)) class OriginProducer: diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index 3ad84e994ed..7bfabd27ad2 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -213,7 +213,7 @@ async def test_local_publish_consume_audio(): async for announcement in routes(consumer.announced()): assert announcement.prefix == "live" - broadcast_consumer = await consumer.request_broadcast(announcement.prefix) + broadcast_consumer = await consumer.request(announcement.prefix) catalog = await moq.media.catalog(broadcast_consumer) assert len(catalog.audio) == 1 @@ -249,7 +249,7 @@ async def test_video_publish_consume(): consumer = origin.consume() async for announcement in routes(consumer.announced()): - broadcast_consumer = await consumer.request_broadcast(announcement.prefix) + broadcast_consumer = await consumer.request(announcement.prefix) catalog = await moq.media.catalog(broadcast_consumer) assert len(catalog.video) == 1 @@ -289,7 +289,7 @@ async def test_video_publish_named_track(): consumer = origin.consume() async for announcement in routes(consumer.announced()): - broadcast_consumer = await consumer.request_broadcast(announcement.prefix) + broadcast_consumer = await consumer.request(announcement.prefix) catalog = await moq.media.catalog(broadcast_consumer) assert list(catalog.video.keys()) == ["hd"] break @@ -305,7 +305,7 @@ async def test_multiple_frames_ordering(): consumer = origin.consume() async for announcement in routes(consumer.announced()): - broadcast_consumer = await consumer.request_broadcast(announcement.prefix) + broadcast_consumer = await consumer.request(announcement.prefix) catalog = await moq.media.catalog(broadcast_consumer) track_name = list(catalog.audio.keys())[0] audio = catalog.audio[track_name] @@ -335,7 +335,7 @@ async def test_catalog_update_on_new_track(): consumer = origin.consume() async for announcement in routes(consumer.announced()): - broadcast_consumer = await consumer.request_broadcast(announcement.prefix) + broadcast_consumer = await consumer.request(announcement.prefix) cat_consumer = await moq.media.CatalogConsumer.subscribe(broadcast_consumer) # First catalog: 1 audio track. @@ -375,7 +375,7 @@ async def test_announced_broadcast(): async for announcement in routes(consumer.announced()): assert announcement.prefix == "test/broadcast" - broadcast_consumer = await consumer.request_broadcast(announcement.prefix) + broadcast_consumer = await consumer.request(announcement.prefix) _catalog = await moq.media.CatalogConsumer.subscribe(broadcast_consumer) break @@ -418,7 +418,7 @@ async def test_finish_serves_until_closed(): moq.media.CatalogProducer(broadcast).finish() # A late subscriber still drains the finished track while the broadcast is up. - late = await consumer.request_broadcast("finish") + late = await consumer.request("finish") reader = await late.subscribe_track("status") frame = await asyncio.wait_for(reader.read_frame(), timeout=5) assert frame is not None and frame.payload == b"tail" @@ -742,7 +742,7 @@ async def test_dynamic_broadcast_request(): dynamic = origin.requests("") consumer = origin.consume() - request_broadcast = asyncio.create_task(consumer.request_broadcast("dynamic/broadcast")) + requesting = asyncio.create_task(consumer.request("dynamic/broadcast")) request = await asyncio.wait_for(dynamic.requested_broadcast(), timeout=5.0) assert request.path == "dynamic/broadcast" @@ -754,7 +754,7 @@ async def test_dynamic_broadcast_request(): with pytest.raises(Exception): _ = request.path - broadcast = await asyncio.wait_for(request_broadcast, timeout=5.0) + broadcast = await asyncio.wait_for(requesting, timeout=5.0) track_consumer = await broadcast.subscribe_track("status") payload = b"served dynamically" track.write_frame(payload, timedelta(microseconds=20_000)) @@ -772,7 +772,7 @@ async def test_dynamic_broadcast_request_can_reject(): dynamic = origin.requests("") consumer = origin.consume() - request_broadcast = asyncio.create_task(consumer.request_broadcast("missing")) + requesting = asyncio.create_task(consumer.request("missing")) request = await asyncio.wait_for(dynamic.requested_broadcast(), timeout=5.0) assert request.path == "missing" @@ -781,7 +781,7 @@ async def test_dynamic_broadcast_request_can_reject(): _ = request.path with pytest.raises(Exception): - await asyncio.wait_for(request_broadcast, timeout=5.0) + await asyncio.wait_for(requesting, timeout=5.0) def test_raw_append_group_sequence_increments(): @@ -925,7 +925,7 @@ async def test_container_consumer_default_latency_and_context_manager(): consumer = origin.consume() async for announcement in routes(consumer.announced()): - broadcast_consumer = await consumer.request_broadcast(announcement.prefix) + broadcast_consumer = await consumer.request(announcement.prefix) catalog = await moq.media.catalog(broadcast_consumer) track_name, audio = next(iter(catalog.audio.items())) @@ -952,7 +952,7 @@ async def test_raw_publish_consume(): async for announcement in routes(consumer.announced()): assert announcement.prefix == "robot/arm" - broadcast_consumer = await consumer.request_broadcast(announcement.prefix) + broadcast_consumer = await consumer.request(announcement.prefix) raw_consumer = await broadcast_consumer.subscribe_track("events") payload = b'{"cmd": "button_changed", "arm": "left", "button": "THUMB", "state": "PRESSED"}' @@ -975,7 +975,7 @@ async def test_raw_multiple_frames(): consumer = origin.consume() async for announcement in routes(consumer.announced()): - broadcast_consumer = await consumer.request_broadcast(announcement.prefix) + broadcast_consumer = await consumer.request(announcement.prefix) subscription = moq.Subscription(max_delay=timedelta(seconds=1), ranges=FROM_GROUP_0) raw_consumer = await broadcast_consumer.subscribe_track("commands", subscription) @@ -1082,7 +1082,7 @@ async def test_raw_group_sequence(): consumer = origin.consume() async for announcement in routes(consumer.announced()): - broadcast_consumer = await consumer.request_broadcast(announcement.prefix) + broadcast_consumer = await consumer.request(announcement.prefix) raw_consumer = await broadcast_consumer.subscribe_track( "seq", moq.Subscription(max_delay=timedelta(seconds=1), ranges=FROM_GROUP_0) ) @@ -1244,7 +1244,7 @@ async def test_raw_multi_frame_group(): consumer = origin.consume() async for announcement in routes(consumer.announced()): - broadcast_consumer = await consumer.request_broadcast(announcement.prefix) + broadcast_consumer = await consumer.request(announcement.prefix) raw_consumer = await broadcast_consumer.subscribe_track("chunks") group_producer = raw.append_group() @@ -1479,7 +1479,7 @@ async def test_audio_consumer_reports_its_playout_delay(): ) consumer = origin.consume() - broadcast_consumer = await asyncio.wait_for(consumer.request_broadcast("audio-delay"), timeout=5.0) + broadcast_consumer = await asyncio.wait_for(consumer.request("audio-delay"), timeout=5.0) catalog = await asyncio.wait_for(moq.media.catalog(broadcast_consumer), timeout=5.0) rendition = catalog.audio["mic"] @@ -1535,7 +1535,7 @@ async def test_decode_video_frame(): video.write(moq.video.Frame(timestamp=timedelta(microseconds=i * 33_333), data=rgba)) consumer = origin.consume() - broadcast_consumer = await asyncio.wait_for(consumer.request_broadcast("video-decode-frame"), timeout=5.0) + broadcast_consumer = await asyncio.wait_for(consumer.request("video-decode-frame"), timeout=5.0) catalog = await asyncio.wait_for(moq.media.catalog(broadcast_consumer), timeout=5.0) track_name = next(iter(catalog.video)) rendition = catalog.video[track_name] @@ -1568,7 +1568,7 @@ async def test_broadcast_is_reachable_only_while_announced(): track = publication.broadcast.publish_track("events") consumer = origin.consume() with pytest.raises(Exception): - await asyncio.wait_for(consumer.request_broadcast("live"), timeout=5.0) + await asyncio.wait_for(consumer.request("live"), timeout=5.0) publication.announce() announced = consumer.announced() @@ -1581,17 +1581,34 @@ async def test_broadcast_is_reachable_only_while_announced(): assert isinstance(retracted, moq.AnnounceEventEnd) assert retracted.announce.prefix == "live" with pytest.raises(Exception): - await asyncio.wait_for(consumer.request_broadcast("live"), timeout=5.0) + await asyncio.wait_for(consumer.request("live"), timeout=5.0) publication.announce() back = await next_route(announced) assert isinstance(back, moq.AnnounceEventStart) - await asyncio.wait_for(consumer.request_broadcast("live"), timeout=5.0) + await asyncio.wait_for(consumer.request("live"), timeout=5.0) announced.cancel() track.finish() publication.broadcast.close() +async def test_an_epoch_pins_request_and_follow(): + origin = moq.OriginProducer() + consumer = origin.consume() + epoch = moq.mint_epoch() + publication = origin.create_broadcast("live") + publication.announce(moq.AnnounceRoute(epoch=epoch)) + + await asyncio.wait_for(consumer.request("live", epoch=epoch), timeout=5.0) + with pytest.raises(moq.Error.Protocol): + await asyncio.wait_for(consumer.request("live", epoch=moq.mint_epoch()), timeout=5.0) + with pytest.raises(moq.Error.InvalidEpoch): + consumer.follow("live", epoch="not-an-epoch") + async with consumer.follow("live", epoch=epoch) as following: + await asyncio.wait_for(following.available(), timeout=5.0) + publication.broadcast.close() + + async def test_dropping_a_publication_keeps_its_route(): origin = moq.OriginProducer() consumer = origin.consume() @@ -1600,11 +1617,11 @@ async def test_dropping_a_publication_keeps_its_route(): assert publication.broadcast is broadcast publication.announce() del publication - await asyncio.wait_for(consumer.request_broadcast("live"), timeout=5.0) + await asyncio.wait_for(consumer.request("live"), timeout=5.0) broadcast.close() with pytest.raises(moq.Error.Protocol): - await asyncio.wait_for(consumer.request_broadcast("live"), timeout=5.0) + await asyncio.wait_for(consumer.request("live"), timeout=5.0) async def test_a_stale_publication_leaves_its_replacement_alone(): @@ -1620,7 +1637,7 @@ async def test_a_stale_publication_leaves_its_replacement_alone(): stale.announce() with pytest.raises(moq.Error.Closed): stale.unannounce() - await asyncio.wait_for(consumer.request_broadcast("live"), timeout=5.0) + await asyncio.wait_for(consumer.request("live"), timeout=5.0) replacement.broadcast.close() @@ -1653,7 +1670,7 @@ async def test_dynamic_serves_a_request_under_a_prefix(): dynamic = origin.requests("live") consumer = origin.consume() - pending = asyncio.create_task(consumer.request_broadcast("live/cam")) + pending = asyncio.create_task(consumer.request("live/cam")) request = await asyncio.wait_for(dynamic.requested_broadcast(), timeout=5.0) assert request.path == "live/cam" served = request.prepare(moq.mint_epoch()).publish() diff --git a/py/moq-rs/tests/test_server.py b/py/moq-rs/tests/test_server.py index 3c8fcd9ff42..c8f3f7f664c 100644 --- a/py/moq-rs/tests/test_server.py +++ b/py/moq-rs/tests/test_server.py @@ -74,7 +74,7 @@ async def accept_loop() -> None: async for announcement in routes(client.announced()): assert announcement.prefix == "hello" - broadcast_consumer = await client.request_broadcast(announcement.prefix) + broadcast_consumer = await client.request(announcement.prefix) catalog = await moq.media.catalog(broadcast_consumer) track_name, audio = next(iter(catalog.audio.items())) assert audio.codec == "opus" @@ -535,7 +535,7 @@ async def drain(reader: moq.TrackConsumer) -> None: async for announcement in routes(consume.announced()): assert announcement.prefix == "live" break - consumer = await asyncio.wait_for(consume.request_broadcast("live"), timeout=5.0) + consumer = await asyncio.wait_for(consume.request("live"), timeout=5.0) reader = await asyncio.wait_for(consumer.subscribe_track("data"), timeout=5.0) reading.append(asyncio.create_task(drain(reader))) demand = track.demand() diff --git a/quest/m1/api-audit/resolve/README.md b/quest/m1/api-audit/resolve/README.md index a09c383de19..c5b169c1f3b 100644 --- a/quest/m1/api-audit/resolve/README.md +++ b/quest/m1/api-audit/resolve/README.md @@ -37,8 +37,10 @@ per language and one for the callers, so each reviews on its own. Rust has landed: `request(path, epoch)` and `follow(path, epoch)` (returning `origin::Following`), with `routed`, `routed_broadcast`, and the route-level `announce::Follow` gone, and its in-tree callers following the path where they -used to wait for a route. JS proceeds in parallel; the bindings follow Rust, -and the callers follow both. +used to wait for a route. JS has landed `follow(path, {epoch})`. The bindings +have landed too: moq-ffi, the C ABI, and every wrapper name them `request` and +`follow` with an optional epoch, `follow` returning `Following`. The callers +follow both. This README's own work, once every child lands: the lifecycle and churn checks across languages, the required Nix gate, and all-language interop @@ -50,7 +52,6 @@ Wire: none. ## Required -- [Bindings request and follow](/quest/m1/api-audit/resolve/bindings.md) - moq-ffi, the C ABI, and every wrapper mirror `request` and `follow` with an optional epoch - [The watch player's follow prop](/quest/m1/api-audit/resolve/watch.md) - `@moq/watch`'s `Broadcast` names its resolution choice `follow` instead of `announced` - [Callers resolve once](/quest/m1/api-audit/resolve/callers.md) - no caller hand-rolls synced resolution or decides table absence by wall clock diff --git a/quest/m1/api-audit/resolve/bindings.md b/quest/m1/api-audit/resolve/bindings.md deleted file mode 100644 index 7c4cf1fc20e..00000000000 --- a/quest/m1/api-audit/resolve/bindings.md +++ /dev/null @@ -1,21 +0,0 @@ -# [M] Bindings request and follow - -## Goal - -moq-ffi, the C ABI, and every wrapper (py, swift, kt, dart, go, cpp, OBS) -mirror `request` and `follow`, each with an optional epoch, and their -consumers use them. - -## Plan - -Split from [Two broadcast resolutions](/quest/m1/api-audit/resolve/README.md) -on 2026-10-28 (maintainer). Today's binding names already inherit the -owned-discovery behavior from -[moq-dev/moq#6445](https://github.com/moq-dev/moq/pull/6445), not the final -naming. - -Regenerate bindings from source, update every wrapper's tests, READMEs and -`doc/lib/*`, add an Impact migration note per package, and run -`just test interop --all`. - -Public API: breaking in moq-ffi, the C ABI, and every wrapper. Wire: none. diff --git a/swift/README.md b/swift/README.md index 0370c13cb3e..e08de344375 100644 --- a/swift/README.md +++ b/swift/README.md @@ -46,7 +46,7 @@ for try await event in announced { print("got broadcast \(announcement.prefix)") print("captures \(announcement.captures ?? [])") - let broadcast = try await session.consume.requestBroadcast(path: announcement.prefix) + let broadcast = try await session.consume.request(path: announcement.prefix) let catalog = try await Media.CatalogConsumer.subscribe(broadcast: broadcast) for try await update in catalog { print("catalog: \(update)") diff --git a/swift/Sources/Moq/Aliases.swift b/swift/Sources/Moq/Aliases.swift index 390792a4e61..57b41b0b19b 100644 --- a/swift/Sources/Moq/Aliases.swift +++ b/swift/Sources/Moq/Aliases.swift @@ -57,7 +57,7 @@ public typealias AnnounceRoute = MoqFFI.MoqAnnounceRoute public typealias Route = MoqFFI.MoqRoute /// A route over a prefix: the origin-relative `prefix`, what each filter /// wildcard matched (`captures`, `nil` for a partial overlap), and the `route` -/// serving it. Resolve a path with `OriginConsumer.requestBroadcast`. +/// serving it. Resolve a path with `OriginConsumer.request`. public typealias Announce = MoqFFI.MoqAnnounce /// What an `AnnounceConsumer` yields: `.start`, `.update`, `.end`, or /// `.restart` (request the path again), each carrying an `Announce`. diff --git a/swift/Sources/Moq/Origin.swift b/swift/Sources/Moq/Origin.swift index 7ba9b8612c4..8dfe72169d6 100644 --- a/swift/Sources/Moq/Origin.swift +++ b/swift/Sources/Moq/Origin.swift @@ -153,17 +153,19 @@ public final class OriginConsumer: Sendable { } /// Follow an exact path, resolving each publisher instance that serves it. - public func announcedBroadcast(path: String) throws -> AnnouncedBroadcast { - AnnouncedBroadcast(try ffi.announcedBroadcast(path: path)) + /// Pass an `epoch` (UUIDv7 text) to follow only that instance. + public func follow(path: String, epoch: String? = nil) throws -> Following { + Following(try ffi.follow(path: path, epoch: epoch)) } - /// Request a broadcast by path, resolving as soon as it can be served through the - /// best announced route covering it: an announced broadcast on this origin, a route - /// a session announced (served on demand by that session), or a dynamic handler on - /// the origin, or an error if nothing can serve it. Unlike `announcedBroadcast`, - /// this does not wait for a future announcement. - public func requestBroadcast(path: String) async throws -> BroadcastConsumer { - BroadcastConsumer(try await ffi.requestBroadcast(path: path)) + /// Request a broadcast by path, resolving one publisher instance as soon as it can be + /// served through the best announced route covering it: an announced broadcast on this + /// origin, a route a session announced (served on demand by that session), or a dynamic + /// handler on the origin, or an error if nothing can serve it. Unlike `follow`, this + /// does not wait for a future announcement. Pass an `epoch` (UUIDv7 text) to refuse + /// any other instance. + public func request(path: String, epoch: String? = nil) async throws -> BroadcastConsumer { + BroadcastConsumer(try await ffi.request(path: path, epoch: epoch)) } } @@ -199,11 +201,11 @@ public final class AnnounceConsumer: AsyncSequence, Sendable { } } -/// A pending wait for a specific broadcast path. -public final class AnnouncedBroadcast: Sendable { - let ffi: MoqAnnouncedBroadcast +/// Follows a specific broadcast path across the publisher instances that serve it. +public final class Following: Sendable { + let ffi: MoqFollowing - init(_ ffi: MoqAnnouncedBroadcast) { + init(_ ffi: MoqFollowing) { self.ffi = ffi } diff --git a/swift/Tests/MoqTests/SmokeTests.swift b/swift/Tests/MoqTests/SmokeTests.swift index fab7d34af1c..78492450836 100644 --- a/swift/Tests/MoqTests/SmokeTests.swift +++ b/swift/Tests/MoqTests/SmokeTests.swift @@ -173,7 +173,7 @@ final class SmokeTests: XCTestCase { _ = try publication.broadcast.publishTrack(name: "events") let consumer = origin.consume() do { - _ = try await consumer.requestBroadcast(path: "live") + _ = try await consumer.request(path: "live") XCTFail("an unannounced broadcast must be unroutable") } catch {} @@ -190,7 +190,7 @@ final class SmokeTests: XCTestCase { } XCTAssertEqual(retracted.prefix, "live") do { - _ = try await consumer.requestBroadcast(path: "live") + _ = try await consumer.request(path: "live") XCTFail("an unannounced broadcast must be unroutable") } catch {} @@ -198,7 +198,7 @@ final class SmokeTests: XCTestCase { guard case .start = try await nextRoute(announced) else { return XCTFail("expected a reannouncement") } - _ = try await consumer.requestBroadcast(path: "live") + _ = try await consumer.request(path: "live") } /// Releasing a publication keeps its route; closing the broadcast ends it. @@ -210,11 +210,11 @@ final class SmokeTests: XCTestCase { XCTAssertTrue(broadcast === publication?.broadcast) try publication?.announce() publication = nil - _ = try await consumer.requestBroadcast(path: "live") + _ = try await consumer.request(path: "live") try broadcast.close() do { - _ = try await consumer.requestBroadcast(path: "live") + _ = try await consumer.request(path: "live") XCTFail("a closed broadcast must be unroutable") } catch {} } @@ -238,7 +238,7 @@ final class SmokeTests: XCTestCase { return XCTFail("expected Closed, got \(error)") } } - _ = try await origin.consume().requestBroadcast(path: "live") + _ = try await origin.consume().request(path: "live") try replacement.broadcast.close() } @@ -281,7 +281,7 @@ final class SmokeTests: XCTestCase { let origin = OriginProducer() let dynamic = try origin.requests(prefix: "live") let pending = Task { - try await origin.consume().requestBroadcast(path: "live/cam") + try await origin.consume().request(path: "live/cam") } let request = try await dynamic.requestedBroadcast() XCTAssertEqual(try request.path, "live/cam") @@ -603,7 +603,7 @@ final class SmokeTests: XCTestCase { ) try publication.announce() - let consumer = try await origin.consume().requestBroadcast(path: "audio-delay") + let consumer = try await origin.consume().request(path: "audio-delay") let catalogs = try await Media.CatalogConsumer.subscribe(broadcast: consumer) // XCTUnwrap takes an autoclosure, which can't hold an await. let nextCatalog = try await catalogs.next() @@ -660,7 +660,7 @@ final class SmokeTests: XCTestCase { try video.write(VideoFrame(timestampUs: UInt64(i) * 33_333, data: rgba)) } - let consumer = try await origin.consume().requestBroadcast(path: "video-decode-frame") + let consumer = try await origin.consume().request(path: "video-decode-frame") let catalogs = try await Media.CatalogConsumer.subscribe(broadcast: consumer) // XCTUnwrap takes an autoclosure, which can't hold an await. let nextCatalog = try await catalogs.next() diff --git a/test/interop/clients/c/subscribe.c b/test/interop/clients/c/subscribe.c index a25023aab22..79465beccb5 100644 --- a/test/interop/clients/c/subscribe.c +++ b/test/interop/clients/c/subscribe.c @@ -64,7 +64,7 @@ struct ctx { int32_t origin; int32_t session; int32_t broadcast_wait; - int32_t broadcast; // handle delivered by moq_origin_announced_broadcast (0 until it arrives) + int32_t broadcast; // handle delivered by moq_origin_follow (0 until it arrives) int32_t catalog; int32_t video_track; // handle from moq_consume_video (0 until on_catalog starts it) @@ -85,7 +85,7 @@ struct ctx { // on main's stack and moq-c keeps the pointer until each registration's // terminal (<= 0) callback fires, so main must not return until every one of // them has. Closing the session ends its state registration alone; -// moq_origin_announced_broadcast, moq_consume_catalog and moq_consume_video each +// moq_origin_follow, moq_consume_catalog and moq_consume_video each // keep the pointer until their own terminal. See drain() at the bottom. static void done(ctx_t *c, int *flag) { pthread_mutex_lock(&c->mu); @@ -635,12 +635,12 @@ int main(int argc, char **argv) { } // The broadcast arrives over the network after connect, so wait for it to be - // announced. moq_origin_announced_broadcast resolves via on_broadcast once it's + // announced. moq_origin_follow resolves via on_broadcast once it's // available; we block on the condvar until then (or the deadline). c.broadcast_wait = moq_origin_follow((uint32_t)c.origin, broadcast, strlen(broadcast), NULL, 0, on_broadcast, &c); if (c.broadcast_wait <= 0) { - fail("error: moq_origin_announced_broadcast failed: %d\n", c.broadcast_wait); + fail("error: moq_origin_follow failed: %d\n", c.broadcast_wait); } pthread_mutex_lock(&c.mu); diff --git a/test/interop/clients/cpp/main.cpp b/test/interop/clients/cpp/main.cpp index d984c926c44..aeae1706eee 100644 --- a/test/interop/clients/cpp/main.cpp +++ b/test/interop/clients/cpp/main.cpp @@ -345,7 +345,7 @@ int subscribe( const auto read_deadline = finish ? Clock::now() + std::chrono::duration_cast(std::chrono::duration(timeout)) : deadline; - auto announced = ok(session->consume()->announced_broadcast(path), "announced_broadcast"); + auto announced = ok(session->consume()->follow(path, std::nullopt), "follow"); auto consumer = until(announced->available(), read_deadline, "available"); // The catalog is a live track. A lazy publisher (e.g. the browser, which only encodes on @@ -401,7 +401,7 @@ int subscribe( const auto *end = std::get_if(&event->get_variant()); if (end && end->announce.prefix == path) break; } - auto watch = ok(session->consume()->announced_broadcast(path + ".health"), "health watch"); + auto watch = ok(session->consume()->follow(path + ".health", std::nullopt), "health watch"); auto health = until(watch->available(), read_deadline, "health available"); auto track = until(health->subscribe_track("live", std::nullopt), read_deadline, "health subscribe"); auto group = until(track->next_group(), read_deadline, "health group"); diff --git a/test/interop/clients/go/main.go b/test/interop/clients/go/main.go index 64438228588..6628c00f196 100644 --- a/test/interop/clients/go/main.go +++ b/test/interop/clients/go/main.go @@ -306,7 +306,7 @@ func finishSubscribe(ctx context.Context, client *moq.Client, broadcast string, return err } defer announcements.Cancel() - announced, err := client.AnnouncedBroadcast(broadcast) + announced, err := client.Follow(broadcast, nil) if err != nil { return err } @@ -403,7 +403,7 @@ func finishSubscribe(ctx context.Context, client *moq.Client, broadcast string, break } } - healthAnnounced, err := client.AnnouncedBroadcast(broadcast + ".health") + healthAnnounced, err := client.Follow(broadcast + ".health", nil) if err != nil { return err } @@ -534,7 +534,7 @@ func subscribe(ctx context.Context, url, broadcast string, opts dialOptions, tim return finishSubscribe(readCtx, client, broadcast, frames) } - announced, err := client.AnnouncedBroadcast(broadcast) + announced, err := client.Follow(broadcast, nil) if err != nil { return err } diff --git a/test/interop/clients/python/interop.py b/test/interop/clients/python/interop.py index 332598d0124..1ebb6a43c8c 100644 --- a/test/interop/clients/python/interop.py +++ b/test/interop/clients/python/interop.py @@ -181,7 +181,7 @@ async def _catalog_with_media(consumer: moq.BroadcastConsumer) -> moq.media.Cata async def _finish_subscribe(client: moq.Client, broadcast: str, frames: int) -> None: # Watch the exact path before resolving it, retaining END while media drains. async with client.announced(broadcast) as announcements: - async with client.announced_broadcast(broadcast) as announced: + async with client.follow(broadcast) as announced: consumer = await announced async with await moq.media.CatalogConsumer.subscribe(consumer) as catalogs: async for catalog in catalogs: @@ -224,7 +224,7 @@ async def _finish_subscribe(client: moq.Client, broadcast: str, frames: int) -> else: raise RuntimeError("announcement stream ended before broadcast END") - async with client.announced_broadcast(f"{broadcast}.health") as announced_health: + async with client.follow(f"{broadcast}.health") as announced_health: health = await announced_health async with await health.subscribe_track("live") as live: seen = False @@ -295,7 +295,7 @@ async def subscribe( await asyncio.wait_for(_finish_subscribe(client, broadcast, frames), timeout) return assert audio_out is not None and audio_ms is not None - consumer = await asyncio.wait_for(client.announced_broadcast(broadcast), timeout) + consumer = await asyncio.wait_for(client.follow(broadcast), timeout) catalog = await asyncio.wait_for(_catalog_with_media(consumer), timeout) id, video = next(iter(catalog.video.items())) diff --git a/test/wasm/baseline/consumer.ts b/test/wasm/baseline/consumer.ts index 4fc044df6aa..9eed7331dcd 100644 --- a/test/wasm/baseline/consumer.ts +++ b/test/wasm/baseline/consumer.ts @@ -163,7 +163,7 @@ async function run(config: Sample) { Array.from({ length: config.publishers }, async (_, publisher) => { const broadcast = await session .consume() - .announcedBroadcast(`${config.id}/${publisher}`) + .follow(`${config.id}/${publisher}`) .available(); const track = await broadcast.subscribeTrack("data", undefined); disposers.push(() => track.cancel()); diff --git a/test/wasm/baseline/uniffi.ts b/test/wasm/baseline/uniffi.ts index 8cc3dc01a10..323ae1c06fa 100644 --- a/test/wasm/baseline/uniffi.ts +++ b/test/wasm/baseline/uniffi.ts @@ -12,7 +12,7 @@ export interface Uniffi { } interface Session { - consume(): { announcedBroadcast(path: string): { available(): Promise } }; + consume(): { follow(path: string): { available(): Promise } }; cancel(code: number): void; } diff --git a/test/wasm/uniffi/cases.ts b/test/wasm/uniffi/cases.ts index bd8ab520b94..aa6c36e78d2 100644 --- a/test/wasm/uniffi/cases.ts +++ b/test/wasm/uniffi/cases.ts @@ -339,7 +339,7 @@ const remote: Record Promise> = { const broadcast = publication.broadcast(); const track = broadcast.publishTrack("data", TIMED); publication.announce(MoqAnnounceRoute.create({})); - const consumer = await within(subscriber.consume().announcedBroadcast(path).available(), 5000, "announce"); + const consumer = await within(subscriber.consume().follow(path).available(), 5000, "announce"); const sub = await consumer.subscribeTrack("data", undefined); const seen: string[] = []; for (const sequence of [5n, 2n ** 32n, 2n ** 53n - 1n, ...HIGH]) { @@ -372,7 +372,7 @@ const remote: Record Promise> = { const broadcast = publication.broadcast(); broadcast.publishTrack("data", TIMED); publication.announce(MoqAnnounceRoute.create({})); - const consumer = await within(subscriber.consume().announcedBroadcast(path).available(), 5000, "announce"); + const consumer = await within(subscriber.consume().follow(path).available(), 5000, "announce"); const outcome = await settle( consumer.subscribeTrack("missing", undefined).then((track) => track.recvGroup()), 5000, @@ -397,7 +397,7 @@ const remote: Record Promise> = { const broadcast = publication.broadcast(); const track = broadcast.publishTrack("data", TIMED); publication.announce(MoqAnnounceRoute.create({})); - const consumer = await within(subscriber.consume().announcedBroadcast(path).available(), 5000, "announce"); + const consumer = await within(subscriber.consume().follow(path).available(), 5000, "announce"); const sub = await consumer.subscribeTrack("data", undefined); const group = track.appendGroup(); group.writeFrame({ payload: payload(4), timestampUs: 0n }); From c064dc3c5ec3bef9f528e28240515aa5f360bd35 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 21:28:22 -0700 Subject: [PATCH 4/7] style: format the binding epoch tests Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/src/test.rs | 18 ++++++++++++------ rs/moq-ffi/src/test.rs | 5 ++++- 2 files changed, 16 insertions(+), 7 deletions(-) diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index d92449c7eb4..ed859f90661 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -3903,10 +3903,7 @@ fn follow_close_cancels() { assert_eq!(moq_origin_follow_cancel(task), 0); assert_eq!(cb.recv_terminal(), 0, "close delivers terminal 0"); - assert!( - moq_origin_follow_cancel(task) < 0, - "double-close should fail" - ); + assert!(moq_origin_follow_cancel(task) < 0, "double-close should fail"); assert_eq!(moq_origin_close(origin), 0); } @@ -4045,7 +4042,11 @@ fn resolve_pinned(call: Resolve, origin: u32, epoch: &str, cb: &Callback) -> i32 fn an_epoch_pins_request_and_follow() { let origin = id(moq_origin_create()); let epoch = moq_net::Epoch::mint(); - let first = publish(origin, "live", moq_net::origin::Route::default().with_epoch(epoch.clone())); + let first = publish( + origin, + "live", + moq_net::origin::Route::default().with_epoch(epoch.clone()), + ); let epoch = epoch.to_string(); let cb = Callback::new(); @@ -4053,7 +4054,12 @@ fn an_epoch_pins_request_and_follow() { assert_eq!(moq_consume_close(id(cb.recv())), 0); assert_eq!(cb.recv_terminal(), 0); let cb = Callback::new(); - id(resolve_pinned(moq_origin_request, origin, &moq_net::Epoch::mint().to_string(), &cb)); + id(resolve_pinned( + moq_origin_request, + origin, + moq_net::Epoch::mint().as_ref(), + &cb, + )); assert!(cb.recv() < 0, "another instance resolved"); assert!(resolve_pinned(moq_origin_follow, origin, "not-an-epoch", &Callback::new()) < 0); diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 8b8b236a28a..dfb9696217b 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -5830,7 +5830,10 @@ async fn an_epoch_pins_request_and_follow() { .await .expect("timed out requesting the pinned instance") .unwrap(); - assert_eq!(pinned.inner().info().epoch.as_ref().map(ToString::to_string), Some(epoch.clone())); + assert_eq!( + pinned.inner().info().epoch.as_ref().map(ToString::to_string), + Some(epoch.clone()) + ); let err = tokio::time::timeout(TIMEOUT, consumer.request("live".into(), Some(moq_mint_epoch()))) .await .expect("timed out requesting another instance") From 882a21ac6aaa8958bbc022cc87ff257d91821114 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 21:36:23 -0700 Subject: [PATCH 5/7] quest: the bindings' renames have landed Co-Authored-By: Claude Opus 5.5 --- quest/m1/api-audit/resolve/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/quest/m1/api-audit/resolve/README.md b/quest/m1/api-audit/resolve/README.md index 428db7bcea9..3e5cb0dc774 100644 --- a/quest/m1/api-audit/resolve/README.md +++ b/quest/m1/api-audit/resolve/README.md @@ -47,7 +47,7 @@ across languages, the required Nix gate, and all-language interop (`just test interop --all`). Public API: breaking task shape in moq-net; behavior changes in `@moq/net` and -the bindings. Final method/epoch naming remains breaking across every wrapper. +the bindings. The method and epoch renames broke every wrapper. Wire: none. ## Required From 309cd8dfe14c14bf43464def93265736c1ad5026 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 28 Oct 2026 22:03:10 -0700 Subject: [PATCH 6/7] test(bindings): synchronize the epoch-pinning follow tests on events The moq-ffi and moq-c epoch-pinning tests slept for twice the update hold before asserting the pinned follower was still pending, which proved nothing about whether the takeover had been processed. An unpinned request now resolves the takeover and holds the answer first, so a follower that wrongly accepted it would hand it out within one pass. moq-ffi polls the follower once in place; moq-c spawns a marker task behind the follower on its single-threaded runtime and expects the marker first, then expects the pinned instance once the takeover goes. Both fail on every run with the pin dropped. Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/src/test.rs | 22 ++++++++++++++-------- rs/moq-ffi/src/test.rs | 21 +++++++++++++++++---- 2 files changed, 31 insertions(+), 12 deletions(-) diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index ed859f90661..0926bdd1181 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -4037,7 +4037,8 @@ fn resolve_pinned(call: Resolve, origin: u32, epoch: &str, cb: &Callback) -> i32 } /// An epoch pins both resolutions to one publisher instance: a request for another one fails, -/// a follower never delivers another one taking over, and malformed epoch text is refused. +/// a follower never delivers another one taking over but delivers its own once it serves again, +/// and malformed epoch text is refused. #[test] fn an_epoch_pins_request_and_follow() { let origin = id(moq_origin_create()); @@ -4063,16 +4064,21 @@ fn an_epoch_pins_request_and_follow() { assert!(cb.recv() < 0, "another instance resolved"); assert!(resolve_pinned(moq_origin_follow, origin, "not-an-epoch", &Callback::new()) < 0); + // Another instance takes over before the follow starts. An unpinned request resolves it and + // holds the answer, so a follower resolving it joins that answer within its first pass. + let second = publish_run(origin, "live"); + let takeover = id(request_once(origin, b"live")); let cb = Callback::new(); let task = id(resolve_pinned(moq_origin_follow, origin, &epoch, &cb)); + // The runtime is one thread running the tasks spawned from outside it in order, so this one + // reports only after the follower's first pass has applied the takeover. + let tx = unsafe { &*(cb.ptr as *const mpsc::Sender) }.clone(); + crate::ffi::RUNTIME.spawn(async move { tx.send(i32::MAX).unwrap() }); + assert_eq!(cb.recv(), i32::MAX, "the follower delivered another instance"); + // Once the takeover goes, the pinned instance serves the path again and is delivered. + assert_eq!(moq_consume_close(takeover), 0); + second.unannounce(); let delivered = id(cb.recv()); - let second = publish_run(origin, "live"); - assert!( - cb.rx - .recv_timeout(moq_net::origin::Config::default().update_hold * 2) - .is_err(), - "the follower delivered another instance" - ); assert_eq!(moq_consume_close(delivered), 0); assert_eq!(moq_origin_follow_cancel(task), 0); diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index dfb9696217b..628afc9e7c7 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -5861,10 +5861,23 @@ async fn an_epoch_pins_request_and_follow() { ..Default::default() }) .unwrap(); - let next = tokio::spawn(async move { followed.available().await }); - tokio::time::sleep(moq_net::origin::Config::default().update_hold * 2).await; - assert!(!next.is_finished(), "the follower handed out another instance"); - next.abort(); + // An unpinned request resolves the takeover and holds it, so a follower resolving it joins + // that answer at once: one poll, which applies the takeover first, would hand it out. + let takeover = tokio::time::timeout(TIMEOUT, consumer.request("live".into(), None)) + .await + .expect("timed out requesting the takeover") + .unwrap(); + assert_ne!( + takeover.inner().info().epoch.as_ref().map(ToString::to_string), + Some(epoch) + ); + let next = std::pin::pin!(followed.available()); + assert!( + next.poll(&mut std::task::Context::from_waker(std::task::Waker::noop())) + .is_pending(), + "the follower handed out another instance" + ); + drop(takeover); first.broadcast().close().unwrap(); second.broadcast().close().unwrap(); } From 43da41669ef05028d2e4c2f3b80639963b26c393 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 29 Oct 2026 09:00:36 -0700 Subject: [PATCH 7/7] fix: unblock the carla epoch quest and format the merged baseline consumer Co-Authored-By: Claude Opus 5.5 --- quest/m1/api-audit/resolve/callers.md | 6 +----- test/wasm/baseline/consumer.ts | 5 +---- 2 files changed, 2 insertions(+), 9 deletions(-) diff --git a/quest/m1/api-audit/resolve/callers.md b/quest/m1/api-audit/resolve/callers.md index 617bd4bd4b2..9c7279f0baa 100644 --- a/quest/m1/api-audit/resolve/callers.md +++ b/quest/m1/api-audit/resolve/callers.md @@ -16,12 +16,8 @@ with `request` or `follow`; see driver's epoch from its announcement, then `_pump_driver` requests the path unpinned. A newer run that took over in between is read under the old run's lease until its own announcement cancels the task. Pass the announced epoch -to the Python wrapper's `request(path, epoch)` once the bindings expose it. +to the Python wrapper's `request(path, epoch=...)`. Run the demo's sim tests (`demo/carla/sim`). Public API: none. Wire: none. - -## Required - -- [Bindings request and follow](/quest/m1/api-audit/resolve/bindings.md) - the Python wrapper's `request` takes an epoch diff --git a/test/wasm/baseline/consumer.ts b/test/wasm/baseline/consumer.ts index f4875d6d094..002ae022290 100644 --- a/test/wasm/baseline/consumer.ts +++ b/test/wasm/baseline/consumer.ts @@ -160,10 +160,7 @@ async function run(config: Sample) { disposers.push(() => session.cancel(0)); await Promise.all( Array.from({ length: config.publishers }, async (_, publisher) => { - const broadcast = await session - .consume() - .follow(`${config.id}/${publisher}`) - .available(); + const broadcast = await session.consume().follow(`${config.id}/${publisher}`).available(); const track = await broadcast.subscribeTrack("data", undefined); disposers.push(() => track.cancel()); const group = await track.recvGroup();